Skip to content

Commit 4746d26

Browse files
mlaursenmlaursen
committed
docs(sassdoc): updated sassdoc for new module system
1 parent ce89374 commit 4746d26

File tree

5 files changed

+145
-76
lines changed

5 files changed

+145
-76
lines changed

‎packages/dev-utils/src/sassdoc.ts‎

Lines changed: 67 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ import {
1414
VariableItem,
1515
} from "sassdoc";
1616

17-
import { nonWebpackDist, packagesRoot, src } from "./constants";
17+
import { nonWebpackDist, packagesRoot, src, tempStylesDir } from "./constants";
1818
import {
1919
combineAllFiles,
2020
CompiledExample,
@@ -24,9 +24,7 @@ import {
2424
FormattedItemLink,
2525
FormattedMixinItem,
2626
FormattedVariableItem,
27-
getColorVariables,
2827
getCompiledValue,
29-
getEverythingScss,
3028
getSassdoc,
3129
isFunctionItem,
3230
isMixinItem,
@@ -46,7 +44,7 @@ export interface FullItemReferenceLink extends ItemReferenceLink {
4644
}
4745

4846
const NO_COMPILE_TOKEN = "<!-- no-compile -->";
49-
const OVERRIDE_VARIABLES_TOKEN = "// OVERRIDE_VARIABLES";
47+
const OVERRIDE_USE_TOKEN = "// OVERRIDE_USE";
5048
const isCompileable = (value: string): boolean =>
5149
/\$?rmd|if\(/.test(value) && !/^--rmd/.test(value);
5250

@@ -102,30 +100,45 @@ function getCompiledValueString(value: VariableValue): string {
102100
.substring(prefix.length);
103101
}
104102

105-
function compileExampleCode(code: string, path: string, name: string): string {
106-
let data = code;
107-
let prefix = "";
108-
const i = code.indexOf(OVERRIDE_VARIABLES_TOKEN);
109-
if (i !== -1) {
110-
prefix = code.substring(0, i);
111-
data = code.substring(i + OVERRIDE_VARIABLES_TOKEN.length);
112-
}
103+
interface CompiledExampleOptions {
104+
/**
105+
* A custom `@use` statement.
106+
*/
107+
use: string;
108+
path: string;
109+
name: string;
110+
code: string;
111+
}
113112

114-
// since everything is part of the same stylesheet to prevent the `@import` IO
115-
// slowdown, have to update variables to be `!global` so that they will be
116-
// overridden/found correctly. (mostly typography)
117-
data = `${getColorVariables()}
118-
${prefix.replace(/;$/g, " !global;")}
113+
function compileExampleCode({
114+
use,
115+
name,
116+
path,
117+
code,
118+
}: CompiledExampleOptions): string {
119+
let useModules: string;
120+
if (use) {
121+
useModules = use.replace('"react-md"', '"react-md/dist/scss/everything"');
122+
} else {
123+
useModules = '@use "react-md/dist/scss/everything" as *;\n';
124+
}
119125

120-
${getEverythingScss()}
126+
const data = `${useModules}
121127
122-
${data}`;
128+
${code}
129+
`;
123130

124131
try {
125-
return format(renderSync({ data }).css.toString(), "css");
132+
return format(
133+
renderSync({
134+
data,
135+
includePaths: [tempStylesDir],
136+
}).css.toString(),
137+
"css"
138+
);
126139
} catch (e) {
127140
log.error("Unable to compile an example with the following code:");
128-
log.error(code);
141+
log.error(data);
129142
log.error();
130143
log.error(`path: ${path}`);
131144
log.error(`name: ${name}`);
@@ -178,6 +191,26 @@ function removeUncompilableCode(code: string): string {
178191

179192
return code;
180193
}
194+
195+
interface FormattedExampleCodeOptions {
196+
use: string;
197+
code: string;
198+
type: ExampleType;
199+
}
200+
201+
function getFormattedExampleCode({
202+
use,
203+
code,
204+
type,
205+
}: FormattedExampleCodeOptions): string {
206+
return format(
207+
`${use || '@use "react-md" as *;\n'}
208+
${code}
209+
`,
210+
getFormatParser(type)
211+
);
212+
}
213+
181214
const isItemRequire = (
182215
item: ItemReference | ItemRequire
183216
): item is ItemRequire => typeof (item as ItemRequire).name === "string";
@@ -231,18 +264,24 @@ function formatItem(
231264

232265
let examples: CompiledExample[] | undefined;
233266
if (example) {
234-
examples = example.map(({ code, type, description }) => {
235-
const exampleCode = removeUncompilableCode(code);
267+
examples = example.map(({ code: rawCode, type, description }) => {
268+
const parts = removeUncompilableCode(rawCode).split(OVERRIDE_USE_TOKEN);
269+
270+
let use = "";
271+
let code: string;
272+
if (parts.length === 2) {
273+
[use, code] = parts;
274+
} else {
275+
[code] = parts;
276+
}
277+
236278
let compiled: string | undefined;
237279
if (type === "scss" && !description.includes(NO_COMPILE_TOKEN)) {
238-
compiled = compileExampleCode(exampleCode, path, name);
280+
compiled = compileExampleCode({ use, code, name, path });
239281
}
240282

241283
return {
242-
code: format(
243-
exampleCode.replace(OVERRIDE_VARIABLES_TOKEN, ""),
244-
getFormatParser(type)
245-
),
284+
code: getFormattedExampleCode({ use, code, type }),
246285
compiled,
247286
type,
248287
description: formatDescription(description),

‎packages/dev-utils/src/utils/copy/styles.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ import { join, sep } from "path";
1212

1313
import {
1414
dist,
15+
everythingScss,
1516
nonWebpackDist,
1617
packagesRoot,
1718
projectRoot,
@@ -89,6 +90,7 @@ function cleanTempStyles(): void {
8990

9091
export async function copyStylesTemp(): Promise<void> {
9192
const files = await glob(PATTERN);
93+
files.push(everythingScss.replace(`${projectRoot}${sep}`, ""));
9294
await Promise.all(
9395
files.map(async (filePath) => {
9496
const contents = getNonTildedContents(filePath);

‎packages/theme/src/_color-a11y.scss‎

Lines changed: 31 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,13 @@ $rmd-theme-default-contrast-ratio: 3 !default;
2121
/// color variables in react md.
2222
///
2323
/// @example scss - Better Contrast Enabled
24-
/// $rmd-theme-better-contrast-colors: true;
25-
/// $rmd-theme-primary: $rmd-teal-500;
26-
/// $rmd-theme-secondary: $rmd-pink-a-200;
27-
/// // OVERRIDE_VARIABLES
24+
/// @use "@react-md/theme/dist/color-palette" as colors;
25+
/// @use "react-md" as * with (
26+
/// $rmd-theme-better-contrast-colors: true,
27+
/// $rmd-theme-primary: colors.$rmd-teal-500,
28+
/// $rmd-theme-secondary: colors.$rmd-pink-a-200,
29+
/// );
30+
/// // OVERRIDE_USE
2831
///
2932
/// // these are the rmd-defaults
3033
/// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default;
@@ -40,10 +43,13 @@ $rmd-theme-default-contrast-ratio: 3 !default;
4043
/// }
4144
///
4245
/// @example scss - Better Contrast Disabled
43-
/// $rmd-theme-better-contrast-colors: false;
44-
/// $rmd-theme-primary: $rmd-teal-500;
45-
/// $rmd-theme-secondary: $rmd-pink-a-200;
46-
/// // OVERRIDE_VARIABLES
46+
/// @use "@react-md/theme/dist/color-palette" as colors;
47+
/// @use "react-md" as * with (
48+
/// $rmd-theme-better-contrast-colors: false,
49+
/// $rmd-theme-primary: colors.$rmd-teal-500,
50+
/// $rmd-theme-secondary: colors.$rmd-pink-a-200,
51+
/// );
52+
/// // OVERRIDE_USE
4753
///
4854
/// // these are the rmd-defaults
4955
/// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default;
@@ -251,10 +257,13 @@ $rmd-theme-linear-channel-values: (
251257
/// to the dark color.
252258
///
253259
/// @example scss - Better Contrast Enabled
254-
/// $rmd-theme-better-contrast-colors: true;
255-
/// $rmd-theme-primary: $rmd-teal-500;
256-
/// $rmd-theme-secondary: $rmd-pink-a-200;
257-
/// // OVERRIDE_VARIABLES
260+
/// @use "@react-md/theme/dist/color-palette" as colors;
261+
/// @use "react-md" as * with (
262+
/// $rmd-theme-better-contrast-colors: true,
263+
/// $rmd-theme-primary: colors.$rmd-teal-500,
264+
/// $rmd-theme-secondary: colors.$rmd-pink-a-200,
265+
/// );
266+
/// // OVERRIDE_USE
258267
///
259268
/// // these are the rmd-defaults
260269
/// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default;
@@ -264,17 +273,19 @@ $rmd-theme-linear-channel-values: (
264273
/// --p: #{$rmd-theme-primary};
265274
/// --s: #{$rmd-theme-secondary};
266275
///
267-
/// // this should be `#000` once compiled since `#000` has a 5.3 contrast
268-
/// // ratio compared to teal while `#fff` has a 3.6 contrast ratio.
276+
/// // since black has a ~5.3 color ratio as compared to white with ~3.6
269277
/// --op: #{$rmd-theme-on-primary};
270278
/// --os: #{$rmd-theme-on-secondary};
271279
/// }
272280
///
273281
/// @example scss - Better Contrast Disabled
274-
/// $rmd-theme-better-contrast-colors: false;
275-
/// $rmd-theme-primary: $rmd-teal-500;
276-
/// $rmd-theme-secondary: $rmd-pink-a-200;
277-
/// // OVERRIDE_VARIABLES
282+
/// @use "@react-md/theme/dist/color-palette" as colors;
283+
/// @use "react-md" as * with (
284+
/// $rmd-theme-better-contrast-colors: false,
285+
/// $rmd-theme-primary: colors.$rmd-teal-500,
286+
/// $rmd-theme-secondary: colors.$rmd-pink-a-200,
287+
/// );
288+
/// // OVERRIDE_USE
278289
///
279290
/// // these are the rmd-defaults
280291
/// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default;
@@ -284,9 +295,8 @@ $rmd-theme-linear-channel-values: (
284295
/// --p: #{$rmd-theme-primary};
285296
/// --s: #{$rmd-theme-secondary};
286297
///
287-
/// // this should be `#fff` once compiled since the light color (`#fff`)
288-
/// // is checked first and meets the minimum contrast ratio requirements
289-
/// // at `3.6`
298+
/// // white has a ~3.6 color ratio so it _is_ contrast compliant with the
299+
/// // minimal contrast ratios even though black would be ~5.6
290300
/// --op: #{$rmd-theme-on-primary};
291301
/// --os: #{$rmd-theme-on-secondary};
292302
/// }

‎packages/theme/src/_mixins.scss‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -89,8 +89,10 @@
8989
/// }
9090
///
9191
/// @example scss - Simple Prefers Color Scheme
92-
/// $rmd-theme-dark-class: 'prefers-color-scheme';
93-
/// // OVERRIDE_VARIABLES
92+
/// @use "react-md" as * with (
93+
/// $rmd-theme-dark-class: 'prefers-color-scheme',
94+
/// );
95+
/// // OVERRIDE_USE
9496
///
9597
/// .container {
9698
/// @include rmd-theme-dark-elevation-styles {
@@ -130,8 +132,10 @@
130132
/// }
131133
///
132134
/// @example scss - CSS Module Prefers Color Scheme Example
133-
/// $rmd-theme-dark-class: 'prefers-color-scheme';
134-
/// // OVERRIDE_VARIABLES
135+
/// @use "react-md" as * with (
136+
/// $rmd-theme-dark-class: 'prefers-color-scheme',
137+
/// );
138+
/// // OVERRIDE_USE
135139
///
136140
/// .container {
137141
/// @include rmd-theme-dark-elevation-styles(true) {

‎packages/typography/src/_variables.scss‎

Lines changed: 37 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -579,37 +579,38 @@ $rmd-typography-overline-styles: () !default;
579579
/// }
580580
///
581581
/// @example scss - Overriding Typography Values
582-
/// $rmd-typography-styles-headline-1: (
583-
/// font-size: 4rem,
584-
/// line-height: 4rem,
585-
/// margin: 0,
582+
/// @use "react-md" as * with (
583+
/// $rmd-typography-headline-1-styles: (
584+
/// font-size: 4rem,
585+
/// line-height: 4rem,
586+
/// margin: 0,
587+
/// ),
588+
/// $rmd-typography-headline-2-styles: (
589+
/// font-size: 3.5rem,
590+
/// line-height: 3.5rem,
591+
/// margin: 0,
592+
/// ),
593+
/// $rmd-typography-headline-3-styles: (
594+
/// margin: 0,
595+
/// ),
596+
/// $rmd-typography-headline-4-styles: (
597+
/// margin: 0,
598+
/// ),
599+
/// $rmd-typography-headline-5-styles: (
600+
/// margin: 0,
601+
/// ),
602+
/// $rmd-typography-headline-6-styles: (
603+
/// margin: 0,
604+
/// ),
586605
/// );
587-
/// $rmd-typography-styles-headline-2: (
588-
/// font-size: 3.5rem,
589-
/// line-height: 3.5rem,
590-
/// margin: 0,
591-
/// );
592-
/// $rmd-typography-styles-headline-3: (
593-
/// margin: 0,
594-
/// );
595-
/// $rmd-typography-styles-headline-4: (
596-
/// margin: 0,
597-
/// );
598-
/// $rmd-typography-styles-headline-5: (
599-
/// margin: 0,
600-
/// );
601-
/// $rmd-typography-styles-headline-6: (
602-
/// margin: 0,
603-
/// );
604-
/// // OVERRIDE_VARIABLES
606+
/// // OVERRIDE_USE
605607
///
606608
/// @each $style in map-keys($rmd-typography-styles) {
607609
/// .#{$style} {
608610
/// @include rmd-typography($style);
609611
/// }
610612
/// }
611613
///
612-
///
613614
/// @type Map
614615
/// @prop {Map} headline-1 - The styles for a headline-1
615616
/// @prop {Map} headline-2 - The styles for a headline-2
@@ -624,6 +625,19 @@ $rmd-typography-overline-styles: () !default;
624625
/// @prop {Map} button - The styles for a button
625626
/// @prop {Map} caption - The styles for a caption
626627
/// @prop {Map} overline - The styles for a overline
628+
/// @require $rmd-typography-headline-1-styles
629+
/// @require $rmd-typography-headline-2-styles
630+
/// @require $rmd-typography-headline-3-styles
631+
/// @require $rmd-typography-headline-4-styles
632+
/// @require $rmd-typography-headline-5-styles
633+
/// @require $rmd-typography-headline-6-styles
634+
/// @require $rmd-typography-subtitle-1-styles
635+
/// @require $rmd-typography-subtitle-2-styles
636+
/// @require $rmd-typography-body-1-styles
637+
/// @require $rmd-typography-body-2-styles
638+
/// @require $rmd-typography-button-styles
639+
/// @require $rmd-typography-caption-styles
640+
/// @require $rmd-typography-overline-styles
627641
$rmd-typography-styles: rmd-typography-set-styles(
628642
$rmd-typography-base,
629643
(

0 commit comments

Comments
 (0)