From 4746d265adcc2dcaffb260a565462b9d9c28805e Mon Sep 17 00:00:00 2001 From: Mikkel Laursen Date: Wed, 8 Sep 2021 20:41:23 -0600 Subject: [PATCH] docs(sassdoc): updated sassdoc for new module system --- packages/dev-utils/src/sassdoc.ts | 95 +++++++++++++++------ packages/dev-utils/src/utils/copy/styles.ts | 2 + packages/theme/src/_color-a11y.scss | 52 ++++++----- packages/theme/src/_mixins.scss | 12 ++- packages/typography/src/_variables.scss | 60 ++++++++----- 5 files changed, 145 insertions(+), 76 deletions(-) diff --git a/packages/dev-utils/src/sassdoc.ts b/packages/dev-utils/src/sassdoc.ts index 84412f99e9..fc210f235c 100644 --- a/packages/dev-utils/src/sassdoc.ts +++ b/packages/dev-utils/src/sassdoc.ts @@ -14,7 +14,7 @@ import { VariableItem, } from "sassdoc"; -import { nonWebpackDist, packagesRoot, src } from "./constants"; +import { nonWebpackDist, packagesRoot, src, tempStylesDir } from "./constants"; import { combineAllFiles, CompiledExample, @@ -24,9 +24,7 @@ import { FormattedItemLink, FormattedMixinItem, FormattedVariableItem, - getColorVariables, getCompiledValue, - getEverythingScss, getSassdoc, isFunctionItem, isMixinItem, @@ -46,7 +44,7 @@ export interface FullItemReferenceLink extends ItemReferenceLink { } const NO_COMPILE_TOKEN = ""; -const OVERRIDE_VARIABLES_TOKEN = "// OVERRIDE_VARIABLES"; +const OVERRIDE_USE_TOKEN = "// OVERRIDE_USE"; const isCompileable = (value: string): boolean => /\$?rmd|if\(/.test(value) && !/^--rmd/.test(value); @@ -102,30 +100,45 @@ function getCompiledValueString(value: VariableValue): string { .substring(prefix.length); } -function compileExampleCode(code: string, path: string, name: string): string { - let data = code; - let prefix = ""; - const i = code.indexOf(OVERRIDE_VARIABLES_TOKEN); - if (i !== -1) { - prefix = code.substring(0, i); - data = code.substring(i + OVERRIDE_VARIABLES_TOKEN.length); - } +interface CompiledExampleOptions { + /** + * A custom `@use` statement. + */ + use: string; + path: string; + name: string; + code: string; +} - // since everything is part of the same stylesheet to prevent the `@import` IO - // slowdown, have to update variables to be `!global` so that they will be - // overridden/found correctly. (mostly typography) - data = `${getColorVariables()} -${prefix.replace(/;$/g, " !global;")} +function compileExampleCode({ + use, + name, + path, + code, +}: CompiledExampleOptions): string { + let useModules: string; + if (use) { + useModules = use.replace('"react-md"', '"react-md/dist/scss/everything"'); + } else { + useModules = '@use "react-md/dist/scss/everything" as *;\n'; + } -${getEverythingScss()} + const data = `${useModules} -${data}`; +${code} +`; try { - return format(renderSync({ data }).css.toString(), "css"); + return format( + renderSync({ + data, + includePaths: [tempStylesDir], + }).css.toString(), + "css" + ); } catch (e) { log.error("Unable to compile an example with the following code:"); - log.error(code); + log.error(data); log.error(); log.error(`path: ${path}`); log.error(`name: ${name}`); @@ -178,6 +191,26 @@ function removeUncompilableCode(code: string): string { return code; } + +interface FormattedExampleCodeOptions { + use: string; + code: string; + type: ExampleType; +} + +function getFormattedExampleCode({ + use, + code, + type, +}: FormattedExampleCodeOptions): string { + return format( + `${use || '@use "react-md" as *;\n'} +${code} +`, + getFormatParser(type) + ); +} + const isItemRequire = ( item: ItemReference | ItemRequire ): item is ItemRequire => typeof (item as ItemRequire).name === "string"; @@ -231,18 +264,24 @@ function formatItem( let examples: CompiledExample[] | undefined; if (example) { - examples = example.map(({ code, type, description }) => { - const exampleCode = removeUncompilableCode(code); + examples = example.map(({ code: rawCode, type, description }) => { + const parts = removeUncompilableCode(rawCode).split(OVERRIDE_USE_TOKEN); + + let use = ""; + let code: string; + if (parts.length === 2) { + [use, code] = parts; + } else { + [code] = parts; + } + let compiled: string | undefined; if (type === "scss" && !description.includes(NO_COMPILE_TOKEN)) { - compiled = compileExampleCode(exampleCode, path, name); + compiled = compileExampleCode({ use, code, name, path }); } return { - code: format( - exampleCode.replace(OVERRIDE_VARIABLES_TOKEN, ""), - getFormatParser(type) - ), + code: getFormattedExampleCode({ use, code, type }), compiled, type, description: formatDescription(description), diff --git a/packages/dev-utils/src/utils/copy/styles.ts b/packages/dev-utils/src/utils/copy/styles.ts index 8a3a6b3489..6f2d397973 100644 --- a/packages/dev-utils/src/utils/copy/styles.ts +++ b/packages/dev-utils/src/utils/copy/styles.ts @@ -12,6 +12,7 @@ import { join, sep } from "path"; import { dist, + everythingScss, nonWebpackDist, packagesRoot, projectRoot, @@ -89,6 +90,7 @@ function cleanTempStyles(): void { export async function copyStylesTemp(): Promise { const files = await glob(PATTERN); + files.push(everythingScss.replace(`${projectRoot}${sep}`, "")); await Promise.all( files.map(async (filePath) => { const contents = getNonTildedContents(filePath); diff --git a/packages/theme/src/_color-a11y.scss b/packages/theme/src/_color-a11y.scss index 78fca18094..cc40976d4f 100644 --- a/packages/theme/src/_color-a11y.scss +++ b/packages/theme/src/_color-a11y.scss @@ -21,10 +21,13 @@ $rmd-theme-default-contrast-ratio: 3 !default; /// color variables in react md. /// /// @example scss - Better Contrast Enabled -/// $rmd-theme-better-contrast-colors: true; -/// $rmd-theme-primary: $rmd-teal-500; -/// $rmd-theme-secondary: $rmd-pink-a-200; -/// // OVERRIDE_VARIABLES +/// @use "@react-md/theme/dist/color-palette" as colors; +/// @use "react-md" as * with ( +/// $rmd-theme-better-contrast-colors: true, +/// $rmd-theme-primary: colors.$rmd-teal-500, +/// $rmd-theme-secondary: colors.$rmd-pink-a-200, +/// ); +/// // OVERRIDE_USE /// /// // these are the rmd-defaults /// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default; @@ -40,10 +43,13 @@ $rmd-theme-default-contrast-ratio: 3 !default; /// } /// /// @example scss - Better Contrast Disabled -/// $rmd-theme-better-contrast-colors: false; -/// $rmd-theme-primary: $rmd-teal-500; -/// $rmd-theme-secondary: $rmd-pink-a-200; -/// // OVERRIDE_VARIABLES +/// @use "@react-md/theme/dist/color-palette" as colors; +/// @use "react-md" as * with ( +/// $rmd-theme-better-contrast-colors: false, +/// $rmd-theme-primary: colors.$rmd-teal-500, +/// $rmd-theme-secondary: colors.$rmd-pink-a-200, +/// ); +/// // OVERRIDE_USE /// /// // these are the rmd-defaults /// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default; @@ -251,10 +257,13 @@ $rmd-theme-linear-channel-values: ( /// to the dark color. /// /// @example scss - Better Contrast Enabled -/// $rmd-theme-better-contrast-colors: true; -/// $rmd-theme-primary: $rmd-teal-500; -/// $rmd-theme-secondary: $rmd-pink-a-200; -/// // OVERRIDE_VARIABLES +/// @use "@react-md/theme/dist/color-palette" as colors; +/// @use "react-md" as * with ( +/// $rmd-theme-better-contrast-colors: true, +/// $rmd-theme-primary: colors.$rmd-teal-500, +/// $rmd-theme-secondary: colors.$rmd-pink-a-200, +/// ); +/// // OVERRIDE_USE /// /// // these are the rmd-defaults /// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default; @@ -264,17 +273,19 @@ $rmd-theme-linear-channel-values: ( /// --p: #{$rmd-theme-primary}; /// --s: #{$rmd-theme-secondary}; /// -/// // this should be `#000` once compiled since `#000` has a 5.3 contrast -/// // ratio compared to teal while `#fff` has a 3.6 contrast ratio. +/// // since black has a ~5.3 color ratio as compared to white with ~3.6 /// --op: #{$rmd-theme-on-primary}; /// --os: #{$rmd-theme-on-secondary}; /// } /// /// @example scss - Better Contrast Disabled -/// $rmd-theme-better-contrast-colors: false; -/// $rmd-theme-primary: $rmd-teal-500; -/// $rmd-theme-secondary: $rmd-pink-a-200; -/// // OVERRIDE_VARIABLES +/// @use "@react-md/theme/dist/color-palette" as colors; +/// @use "react-md" as * with ( +/// $rmd-theme-better-contrast-colors: false, +/// $rmd-theme-primary: colors.$rmd-teal-500, +/// $rmd-theme-secondary: colors.$rmd-pink-a-200, +/// ); +/// // OVERRIDE_USE /// /// // these are the rmd-defaults /// // $rmd-theme-on-primary: rmd-theme-best-contrast-color($rmd-theme-primary) !default; @@ -284,9 +295,8 @@ $rmd-theme-linear-channel-values: ( /// --p: #{$rmd-theme-primary}; /// --s: #{$rmd-theme-secondary}; /// -/// // this should be `#fff` once compiled since the light color (`#fff`) -/// // is checked first and meets the minimum contrast ratio requirements -/// // at `3.6` +/// // white has a ~3.6 color ratio so it _is_ contrast compliant with the +/// // minimal contrast ratios even though black would be ~5.6 /// --op: #{$rmd-theme-on-primary}; /// --os: #{$rmd-theme-on-secondary}; /// } diff --git a/packages/theme/src/_mixins.scss b/packages/theme/src/_mixins.scss index 5f76b525d1..5f4cdc3143 100644 --- a/packages/theme/src/_mixins.scss +++ b/packages/theme/src/_mixins.scss @@ -89,8 +89,10 @@ /// } /// /// @example scss - Simple Prefers Color Scheme -/// $rmd-theme-dark-class: 'prefers-color-scheme'; -/// // OVERRIDE_VARIABLES +/// @use "react-md" as * with ( +/// $rmd-theme-dark-class: 'prefers-color-scheme', +/// ); +/// // OVERRIDE_USE /// /// .container { /// @include rmd-theme-dark-elevation-styles { @@ -130,8 +132,10 @@ /// } /// /// @example scss - CSS Module Prefers Color Scheme Example -/// $rmd-theme-dark-class: 'prefers-color-scheme'; -/// // OVERRIDE_VARIABLES +/// @use "react-md" as * with ( +/// $rmd-theme-dark-class: 'prefers-color-scheme', +/// ); +/// // OVERRIDE_USE /// /// .container { /// @include rmd-theme-dark-elevation-styles(true) { diff --git a/packages/typography/src/_variables.scss b/packages/typography/src/_variables.scss index 1b534e422c..7dce7eb006 100644 --- a/packages/typography/src/_variables.scss +++ b/packages/typography/src/_variables.scss @@ -579,29 +579,31 @@ $rmd-typography-overline-styles: () !default; /// } /// /// @example scss - Overriding Typography Values -/// $rmd-typography-styles-headline-1: ( -/// font-size: 4rem, -/// line-height: 4rem, -/// margin: 0, +/// @use "react-md" as * with ( +/// $rmd-typography-headline-1-styles: ( +/// font-size: 4rem, +/// line-height: 4rem, +/// margin: 0, +/// ), +/// $rmd-typography-headline-2-styles: ( +/// font-size: 3.5rem, +/// line-height: 3.5rem, +/// margin: 0, +/// ), +/// $rmd-typography-headline-3-styles: ( +/// margin: 0, +/// ), +/// $rmd-typography-headline-4-styles: ( +/// margin: 0, +/// ), +/// $rmd-typography-headline-5-styles: ( +/// margin: 0, +/// ), +/// $rmd-typography-headline-6-styles: ( +/// margin: 0, +/// ), /// ); -/// $rmd-typography-styles-headline-2: ( -/// font-size: 3.5rem, -/// line-height: 3.5rem, -/// margin: 0, -/// ); -/// $rmd-typography-styles-headline-3: ( -/// margin: 0, -/// ); -/// $rmd-typography-styles-headline-4: ( -/// margin: 0, -/// ); -/// $rmd-typography-styles-headline-5: ( -/// margin: 0, -/// ); -/// $rmd-typography-styles-headline-6: ( -/// margin: 0, -/// ); -/// // OVERRIDE_VARIABLES +/// // OVERRIDE_USE /// /// @each $style in map-keys($rmd-typography-styles) { /// .#{$style} { @@ -609,7 +611,6 @@ $rmd-typography-overline-styles: () !default; /// } /// } /// -/// /// @type Map /// @prop {Map} headline-1 - The styles for a headline-1 /// @prop {Map} headline-2 - The styles for a headline-2 @@ -624,6 +625,19 @@ $rmd-typography-overline-styles: () !default; /// @prop {Map} button - The styles for a button /// @prop {Map} caption - The styles for a caption /// @prop {Map} overline - The styles for a overline +/// @require $rmd-typography-headline-1-styles +/// @require $rmd-typography-headline-2-styles +/// @require $rmd-typography-headline-3-styles +/// @require $rmd-typography-headline-4-styles +/// @require $rmd-typography-headline-5-styles +/// @require $rmd-typography-headline-6-styles +/// @require $rmd-typography-subtitle-1-styles +/// @require $rmd-typography-subtitle-2-styles +/// @require $rmd-typography-body-1-styles +/// @require $rmd-typography-body-2-styles +/// @require $rmd-typography-button-styles +/// @require $rmd-typography-caption-styles +/// @require $rmd-typography-overline-styles $rmd-typography-styles: rmd-typography-set-styles( $rmd-typography-base, (