fix(documentation): Convert fenced code snippet to Source and use dar…

…k theme (#1928) After Storybook 7.4.0, the documentation served (and not build) doesn't display code snippet properly: ![Teams_emZES03vNY](https://github.com/swisspost/design-system/assets/12294151/478903b7-4d3d-4e88-a9a5-dbee57136815) This PR convert fenced code snippet to Source element, officially supported. Most code snippets are available in an external file (one code snippet per file) and imported into the Source element. This PR also set dark theme as default for code snippets (and closes #1677). --------- Co-authored-by: Oliver Schürch <[email protected]>
swisspost · Sep 7, 2023 · 823948e · 823948e
1 parent bd185a0
commit 823948e
Show file tree

Hide file tree

Showing 79 changed files with 896 additions and 910 deletions.
diff --git a/packages/documentation/.storybook/preview.ts b/packages/documentation/.storybook/preview.ts
@@ -13,6 +13,8 @@ import scss from 'react-syntax-highlighter/dist/esm/languages/prism/scss';
 
 SyntaxHighlighter.registerLanguage('scss', scss);
 
+export const SourceDarkMode = true;
+
 const preview: Preview = {
   parameters: {
     options: {
@@ -56,6 +58,7 @@ const preview: Preview = {
       },
       source: {
         excludeDecorators: true,
+        dark: SourceDarkMode,
         transform: (snippet: string) => format(snippet, prettierOptions),
       },
       components: resetComponents,

diff --git a/packages/documentation/src/shared/styles-package-import-individual.sample.ts b/packages/documentation/src/shared/styles-package-import-individual.sample.ts
@@ -0,0 +1,25 @@
+interface Props {
+  components: string[];
+  required?: { icons: boolean; floatingLabel: boolean; formFeedback: boolean };
+}
+
+const requiredLabels: { [key: string]: string } = {
+  'icons': 'required if you use icons',
+  'floating-label': 'required if you use floating-labels',
+  'form-feedback': 'required if you use validation feedbacks',
+};
+
+export function getStylesPackageImportIndividual(props: Props) {
+  const basics = `@use '@swisspost/design-system-styles/basics.scss';`;
+  const generateComponentLine = (name: string) =>
+    `@use '@swisspost/design-system-styles/components/${name}.scss';`;
+  const components = props.components.map(generateComponentLine).join('\n');
+
+  const required = Object.keys(props?.required || {}).reduce(
+    (acc: string, curr: string) =>
+      `${acc}\n// ${requiredLabels[curr]}\n${generateComponentLine(curr)}`,
+    '',
+  );
+
+  return `${basics}\n${components}\n${required}`;
+}
diff --git a/packages/documentation/src/shared/styles-package-import.mdx b/packages/documentation/src/shared/styles-package-import.mdx
@@ -0,0 +1,20 @@
+import { Source } from '@storybook/blocks';
+import { getStylesPackageImportIndividual } from './styles-package-import-individual.sample';
+
+## SCSS Imports
+
+To import all styles from the design-system-styles package:
+
+<Source
+  code={`
+@use '@swisspost/design-system-styles/index.scss';
+  `}
+  language="scss"
+/>
+
+To import only the styles required for this component:
+
+<Source
+  code={getStylesPackageImportIndividual(props)}
+  language="scss"
+/>
diff --git a/packages/documentation/src/stories/components/alert/alert.docs.mdx b/packages/documentation/src/stories/components/alert/alert.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 import * as AlertStories from './alert.stories';
+import StylesPackageImport from '../../../shared/styles-package-import.mdx';
 
 <Meta of={AlertStories} />
 
@@ -16,20 +17,7 @@ By default, alerts are rendered with a contextually appropriate icon.
 <Canvas of={AlertStories.Default} />
 <Controls of={AlertStories.Default} />
 
-## SCSS Imports
-
-To import all styles from the design-system-styles package:
-
-```scss
-@use '@swisspost/design-system-styles/index.scss';
-```
-
-To import only the styles required for this component:
-
-```scss
-@use '@swisspost/design-system-styles/basics.scss';
-@use '@swisspost/design-system-styles/components/alert.scss';
-```
+<StylesPackageImport components={["alert"]} />
 
 ## Specific examples of application
 

diff --git a/packages/documentation/src/stories/components/badge/badge.docs.mdx b/packages/documentation/src/stories/components/badge/badge.docs.mdx
@@ -1,5 +1,6 @@
-import { Meta, Canvas, Controls } from '@storybook/blocks';
+import { Canvas, Controls, Meta } from '@storybook/blocks';
 import * as badgeStories from './badge.stories';
+import StylesPackageImport from '../../../shared/styles-package-import.mdx';
 
 <Meta of={badgeStories} />
 
@@ -14,20 +15,7 @@ import * as badgeStories from './badge.stories';
   <Controls of={badgeStories.Default} />
 </div>
 
-## SCSS Imports
-
-To import all styles from the design-system-styles package:
-
-```scss
-@use '@swisspost/design-system-styles/index.scss';
-```
-
-To import only the styles required for this component:
-
-```scss
-@use '@swisspost/design-system-styles/basics.scss';
-@use '@swisspost/design-system-styles/components/badge.scss';
-```
+<StylesPackageImport components={["badge"]} />
 
 ## Examples
 

diff --git a/packages/documentation/src/stories/components/blockquote/blockquote.docs.mdx b/packages/documentation/src/stories/components/blockquote/blockquote.docs.mdx
@@ -1,13 +1,15 @@
-import { Meta, Canvas, Controls } from '@storybook/blocks';
+import { Canvas, Controls, Meta } from '@storybook/blocks';
 import * as BlockquoteStories from './blockquote.stories.ts';
+import StylesPackageImport from '../../../shared/styles-package-import.mdx';
 
 <Meta of={BlockquoteStories} />
 
 # Blockquote
 
 <div className="lead">
-  For quoting blocks of content from another source within your document. Wrap `<blockquote
-  class="blockquote">` around any HTML as the quote.
+  For quoting blocks of content from another source within your document. Wrap `
+  <blockquote
+    class="blockquote">` around any HTML as the quote.
 </div>
 
 <Canvas of={BlockquoteStories.Default} />
@@ -16,27 +18,15 @@ import * as BlockquoteStories from './blockquote.stories.ts';
   <Controls of={BlockquoteStories.Default} />
 </div>
 
-## SCSS Imports
-
-To import all styles from the design-system-styles package:
-
-```scss
-@use '@swisspost/design-system-styles/index.scss';
-```
-
-To import only the styles required for this component:
-
-```scss
-@use '@swisspost/design-system-styles/basics.scss';
-@use '@swisspost/design-system-styles/components/blockquote.scss';
-```
+<StylesPackageImport components={["blockquote"]} />
 
 ## Concrete Examples of Application
 
 The following examples show the different characteristics of the component. These can differ in the type of visualization, the html structure, as well as when, how and why they are displayed.
 
 ### Nested
 
-To add simple quote characters around any nested text within your blockquote, you can wrap it with a <code>&lt;q&gt;</code> tag.
+To add simple quote characters around any nested text within your blockquote, you can wrap it with a
+<code>&lt;q&gt;</code> tag.
 
 <Canvas of={BlockquoteStories.Nested} />
diff --git a/packages/documentation/src/stories/components/button-group/button-group.docs.mdx b/packages/documentation/src/stories/components/button-group/button-group.docs.mdx
@@ -1,5 +1,6 @@
 import { Canvas, Controls, Meta } from '@storybook/blocks';
 import * as ButtonGroupStories from './button-group.stories';
+import StylesPackageImport from '../../../shared/styles-package-import.mdx';
 
 <Meta of={ButtonGroupStories} />
 
@@ -14,20 +15,7 @@ import * as ButtonGroupStories from './button-group.stories';
   <Controls of={ButtonGroupStories.Default} />
 </div>
 
-## SCSS Imports
-
-To import all styles from the design-system-styles package:
-
-```scss
-@use '@swisspost/design-system-styles/index.scss';
-```
-
-To import only the styles required for this component:
-
-```scss
-@use '@swisspost/design-system-styles/basics.scss';
-@use '@swisspost/design-system-styles/components/badge.scss';
-```
+<StylesPackageImport components={["button-group"]} />
 
 ## Concrete Examples of Application
 

diff --git a/packages/documentation/src/stories/components/button/button.docs.mdx b/packages/documentation/src/stories/components/button/button.docs.mdx
@@ -1,6 +1,7 @@
-import { Meta, Canvas, Controls } from '@storybook/blocks';
+import { Canvas, Controls, Meta } from '@storybook/blocks';
 import LinkTo from '@storybook/addon-links/react';
 import * as ButtonStories from './button.stories';
+import StylesPackageImport from '../../../shared/styles-package-import.mdx';
 
 <Meta of={ButtonStories} />
 
@@ -16,31 +17,17 @@ import * as ButtonStories from './button.stories';
   <Controls of={ButtonStories.Default} />
 </div>
 
-## SCSS Imports
-
-To import all styles from the design-system-styles package:
-
-```scss
-@use '@swisspost/design-system-styles/index.scss';
-```
-
-To import only the styles required for this component:
-
-```scss
-@use '@swisspost/design-system-styles/basics.scss';
-@use '@swisspost/design-system-styles/components/button.scss';
-
-// required if you use icons
-@use '@swisspost/design-system-styles/components/icons.scss';
-```
+<StylesPackageImport components={["button"]} required={{ icons: true }} />
 
 ## Concrete Examples of Application
 
 The following examples show the different characteristics of the component. These can differ in the type of visualization, the html structure, as well as when, how and why they are displayed.
 
 ### Inverted
 
-Inverted buttons don't need special classes anymore, just use any of the <LinkTo kind="utilities-background" story="docs">background classes</LinkTo> to set the background and you're done for the day.
+Inverted buttons don't need special classes anymore, just use any of the
+<LinkTo kind="utilities-background" story="docs">background
+  classes</LinkTo> to set the background and you're done for the day.
 
 <Canvas of={ButtonStories.Inverted} />
 

diff --git a/packages/documentation/src/stories/components/card/card.docs.mdx b/packages/documentation/src/stories/components/card/card.docs.mdx
@@ -1,6 +1,7 @@
-import { Meta, Canvas, Controls } from '@storybook/blocks';
-import LinkTo from '@storybook/addon-links/react';
+import { Canvas, Controls, Meta } from '@storybook/blocks';
 import * as CardStories from './card.stories';
+import StylesPackageImport from '../../../shared/styles-package-import.mdx';
+import LinkTo from '@storybook/addon-links/react';
 
 <Meta of={CardStories} />
 
@@ -14,27 +15,15 @@ Built with flexbox, they offer easy alignment and mix well with other components
 
 They have no fixed width to start, so they’ll naturally fill the full width of its parent element.
 This is easily customizable using the grid for example,
-for more details read our <LinkTo kind="foundations-layout" story="docs">layout docs</LinkTo>.
+for more details read our
+<LinkTo kind="foundations-layout" story="docs">layout docs</LinkTo>.
 
-<Canvas of={CardStories.Default}/>
+<Canvas of={CardStories.Default} />
 <div className="hide-col-default">
   <Controls of={CardStories.Default} />
 </div>
 
-## SCSS Imports
-
-To import all styles from the design-system-styles package:
-
-```scss
-@use '@swisspost/design-system-styles/index.scss';
-```
-
-To import only the styles required for this component:
-
-```scss
-@use '@swisspost/design-system-styles/basics.scss';
-@use '@swisspost/design-system-styles/components/card.scss';
-```
+<StylesPackageImport components={["card"]} />
 
 ## Examples
 
@@ -60,7 +49,8 @@ Use card groups to render cards as a single, attached element with equal width a
 ### Bad example
 
 <div className="alert alert-danger mb-3">
-  Never use text with a background image because you can't ensure it is readable by everyone for all languages and browser sizes.
+  Never use text with a background image because you can't ensure it is readable by everyone for all languages and
+  browser sizes.
 </div>
 
 <Canvas of={CardStories.BackgroundImage} />
diff --git a/packages/documentation/src/stories/components/checkbox/checkbox.docs.mdx b/packages/documentation/src/stories/components/checkbox/checkbox.docs.mdx
@@ -1,6 +1,7 @@
-import { Meta, Canvas, Controls } from '@storybook/blocks';
+import { Canvas, Controls, Meta, Source } from '@storybook/blocks';
 import LinkTo from '@storybook/addon-links/react';
 import * as checkboxStories from './checkbox.stories';
+import StylesPackageImport from '../../../shared/styles-package-import.mdx';
 
 <Meta of={checkboxStories} />
 
@@ -17,23 +18,7 @@ Our checkboxes use custom icons to indicate checked or indeterminate states.
   <Controls of={checkboxStories.Default} />
 </div>
 
-## SCSS Imports
-
-To import all styles from the design-system-styles package:
-
-```css
-@use '@swisspost/design-system-styles/index.scss';
-```
-
-To import only the styles required for this component:
-
-```css
-@use '@swisspost/design-system-styles/basics.scss';
-@use '@swisspost/design-system-styles/components/form-check.scss';
-
-// required if you use validation feedbacks
-@use '@swisspost/design-system-styles/components/form-feedback.scss';
-```
+<StylesPackageImport components={["form-check"]} required={{ 'form-feedback': true }} />
 
 ## Examples
 
@@ -53,9 +38,10 @@ visit [Accessible Web Designs indeterminate checkbox](http://www.barrierefreies-
 
 The indeterminate state can only be set via JavaScript and is styled using the `:indeterminate` pseudo-class.
 
-```javascript
-document.querySelector('input[type="checkbox"]').indeterminate = true;
-```
+<Source
+  code={`document.querySelector('input[type="checkbox"]').indeterminate = true;`}
+  language="javascript"
+/>
 
 ### Inline
 

diff --git a/packages/documentation/src/stories/components/choice-card/checkbox-card.docs.mdx b/packages/documentation/src/stories/components/choice-card/checkbox-card.docs.mdx
@@ -1,5 +1,6 @@
-import { Meta, Canvas, Controls } from '@storybook/blocks';
+import { Canvas, Controls, Meta } from '@storybook/blocks';
 import * as CheckboxCardStories from './checkbox-card.stories';
+import StylesPackageImport from '../../../shared/styles-package-import.mdx';
 
 <Meta of={CheckboxCardStories} />
 
@@ -13,8 +14,8 @@ import * as CheckboxCardStories from './checkbox-card.stories';
 <div className="alert alert-info">
   <h2 class="h5">Firefox fallback classes</h2>
   Firefox currently does not support <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/:has">
-    the new <abbr title="Cascading Style Sheets">CSS</abbr> :has pseudo-selector
-  </a>. As a fallback, the following states have to be mirrored on the top level element in the form
+  the new <abbr title="Cascading Style Sheets">CSS</abbr> :has pseudo-selector
+</a>. As a fallback, the following states have to be mirrored on the top level element in the form
   of classes:
   <ul>
     <li>
@@ -47,17 +48,4 @@ Checkbox cards can be grouped together. Use a `fieldset`/`legend` combination to
   <Controls of={CheckboxCardStories.Group} />
 </div>
 
-## SCSS Imports
-
-To import all styles from the design-system-styles package:
-
-```scss
-@use '@swisspost/design-system-styles/index.scss';
-```
-
-To import only the styles required for this component:
-
-```scss
-@use '@swisspost/design-system-styles/basics.scss';
-@use '@swisspost/design-system-styles/components/choice-control-card.scss';
-```
+<StylesPackageImport components={["choice-control-card"]} />