chore: add mermaid integration to docs, create architecture (#1221)

Author: jorenbroekema

docs/expressive-code-plugin-language-class.ts

@@ -0,0 +1,32 @@
+import type { ExpressiveCodePlugin } from '@expressive-code/core';
+
+export function pluginLanguageClass(): ExpressiveCodePlugin {
+  return {
+    name: 'PluginLanguageClass',
+    hooks: {
+      postprocessRenderedBlock: (opts) => {
+        if (opts.codeBlock.language === 'mermaid') {
+          const pre = opts.renderData.blockAst.children.find(
+            (child) => child.type === 'element' && child.tagName === 'pre',
+          );
+          if (pre && pre.type === 'element') {
+            // add the mermaid language class so mermaid can pick this up
+            pre.properties = {
+              class: `${opts.codeBlock.language} hidden`,
+            };
+            console.log(pre);
+
+            // replace the AST that expressive code has made and put back the simple text
+            // otherwise mermaid gets confused by all of the generated HTML syntax
+            pre.children = [
+              {
+                value: opts.codeBlock.code,
+                type: 'text',
+              },
+            ];
+          }
+        }
+      },
+    },
+  };
+}

docs/src/components/sd-playground.ts

@@ -235,8 +235,9 @@ class SdPlayground extends LitElement {
             </sl-radio-button>
           `,
         )}
-        <sl-radio-button value="eject" aria-label="Eject" title="Eject" @click=${this.ejectHandler}>
+        <sl-radio-button value="eject" label="Eject" title="Eject" @click=${this.ejectHandler}>
           <svg
+            aria-label="Eject"
             width="20px"
             height="20px"
             viewBox="0 0 24 24"

docs/src/content/docs/info/architecture.md

@@ -4,9 +4,45 @@ sidebar:
   order: 2
 ---
 
-This is how Style Dictionary works under the hood.
-
-![build structure](../../../assets/build-diagram.png)
+This is how Style Dictionary works under the hood:
+
+```mermaid
+flowchart LR
+    subgraph global
+        direction TB
+        Z[Config] -->|Parse config| X
+        X[Parsed Config] -->|Run| A
+        A[Token Files] -->|Parsers| B
+        B[JavaScript Objects] -->|Combine| C
+        C[Dictionary] -->|Preprocessors| C
+        click X "#1-parse-the-config" "Explanation about parsing config"
+        click A "#2-find-all-token-files" "Explanation about finding tokens files"
+        click B "#3-parse-token-files" "Explanation about parsing tokens files"
+        click C "#4-deep-merge-token-files" "Explanation about deep merging tokens into a dictionary"
+    end
+
+    subgraph platform
+        direction TB
+        D[Dictionary] -->|Preprocessors| D
+        D -->|Transforms| E
+        E[Transformed Dictionary] -->|Resolve references| F
+        F[Resolved Dictionary] -->|Transitive transforms| E
+        click D "#5-run-preprocessors-over-the-dictionary" "Explanation about preprocessing the dictionary"
+        click E "#6-transform-the-tokens" "Explanation about transforming tokens"
+        click F "#7-resolve-aliases--references-to-other-values" "Explanation about token references resolution"
+    end
+
+    subgraph files
+        direction TB
+        G[Resolved Dictionary] --> |Filters| H
+        H[Filtered Dictionary] --> |Formats| I
+        H[Filtered Dictionary] --> |File headers| I
+        I[Platform output] --> |Actions| J[Actions output]
+        click I "#8-format-the-tokens-into-files" "Explanation about formatting tokens to output files"
+        click J "#9-run-actions" "Explanation about running actions"
+    end
+    global --> platform --> files
+```
 
 Let's take a closer look into each of these steps.
 
@@ -18,37 +54,35 @@ Style Dictionary is a configuration based framework, you tell it what to do in a
 
 In your [config](/reference/config) file can define `include` and `source`, which are arrays of file path globs. These tell Style Dictionary where to find your token files. You can have them anywhere and in any folder structure as long as you tell Style Dictionary where to find them.
 
-If there are [custom parsers](/reference/hooks/parsers) defined and applied in the config, Style Dictionary will run those on files the applied parsers match.
+## 3. Parse token files
+
+If there are [custom parsers](/reference/hooks/parsers) defined and applied in the config, Style Dictionary will run those on files the applied parsers match. For JSON or JavaScript token files, those are parsed automatically through built-in parsers.
 
-## 3. Deep merge token files
+## 4. Deep merge token files
 
 Style Dictionary takes all the files it found and performs a deep merge. This allows you to split your token files in any way you like, without worrying about accidentally overriding groups of tokens. This gives Style Dictionary a single, complete token object to work from.
 
-## 4. Run preprocessors over the dictionary
+## 5. Run preprocessors over the dictionary
 
 Allows users to configure [custom preprocessors](/reference/hooks/preprocessors), to process the merged dictionary as a whole, rather than per token file individually.
 These preprocessors have to be applied in the config, either on a global or platform level.
+Platform level preprocessors run once you get/export/format/build a platform, at the very start.
 
-## 5. Iterate over the platforms
-
-For each platform defined in your [config](/reference/config), Style Dictionary will do a few steps to get it ready to be consumed on that platform. You don't need to worry about one platform affecting another because everything that happens in a platform is non-destructive.
-Platform-applied preprocessors run now instead of beforehand in step 4.
-
-## 5a. Transform the tokens
+## 6. Transform the tokens
 
 Style Dictionary now traverses over the whole token object and looks for design tokens. It does this by looking for anything with a `value` key. When it comes across a design token, it then performs all the [transforms](/reference/hooks/transforms) defined in your [config](/reference/config) in order.
 
 Value transforms, transforms that modify a token's value, are skipped if the token references another token. Starting in 3.0, you can define a [transitive transform](/reference/hooks/transforms#transitive-transforms) that will transform a value that references another token after that reference has been resolved.
 
-## 5b. Resolve aliases / references to other values
+## 7. Resolve aliases / references to other values
 
 After all the tokens have been transformed, it then does another pass over the token object looking for aliases, which look like `"{size.font.base.value}"`. When it finds these, it then replaces the reference with the transformed value. Because Style Dictionary merges all token files into a single object, aliases can be in any token file and still work.
 
-## 5c. Format the tokens into files
+## 8. Format the tokens into files
 
 Now all the design tokens are ready to be written to a file. Style Dictionary takes the whole transformed and resolved token object and for each file defined in the platform it [formats](/reference/hooks/formats) the token object and write the output to a file. Internally, Style Dictionary creates a flat array of all the design tokens it finds in addition to the token object. This is how you can output a flat SCSS variables file.
 
-## 5d. Run actions
+## 9. Run actions
 
 [Actions](/reference/hooks/actions) are custom code that run in a platform after the files are generated. They are useful for things like copying assets to specific build directories or generating images.
 

docs/src/setup.ts

@@ -1,5 +1,6 @@
 import dark from '@shoelace-style/shoelace/dist/themes/dark.css?raw' assert { type: 'css' };
 import light from '@shoelace-style/shoelace/dist/themes/light.css?raw' assert { type: 'css' };
+import mermaid from 'mermaid';
 import { registeredComponents } from './components/sd-playground.ts';
 
 type Theme = 'dark' | 'light';
@@ -18,11 +19,43 @@ sheets.light.replaceSync(light);
 sheets.dark.theme = true;
 sheets.light.theme = true;
 
+// 77rem
+const VP_THRESHOLD = 1231;
+const getViewportWidth = () =>
+  Math.max(document.documentElement.clientWidth || 0, window.innerWidth || 0);
+
+async function renderMermaid() {
+  const theme = getSelectedTheme();
+  const direction = getViewportWidth() > VP_THRESHOLD ? 'LR' : 'TB';
+  mermaid.initialize({
+    startOnLoad: false,
+    theme,
+  });
+  const elements = [...document.querySelectorAll('.mermaid')] as HTMLPreElement[];
+  await Promise.all(
+    [...elements].map((el) => {
+      // we're storing the original graph definition as a data attribute
+      // because mermaid's render will change the innerText
+      // and we need to be able to re-render on theme swap or window resize
+      const graphDefinition = el.getAttribute('data-mermaid-graph-definition') ?? el.innerText;
+      el.setAttribute('data-mermaid-graph-definition', graphDefinition);
+      return mermaid
+        .render('graphDiv', graphDefinition.replace('flowchart LR', `flowchart ${direction}`))
+        .then(({ svg }) => {
+          el.innerHTML = svg;
+        });
+    }),
+  );
+  [...elements].forEach((el) => {
+    el.classList.remove('hidden');
+  });
+}
+
 function getSelectedTheme() {
   return document.documentElement.getAttribute(themeAttr) as Theme;
 }
 
-function swapTheme(theme: Theme) {
+async function swapTheme(theme: Theme) {
   currTheme = theme;
   // shoelace theme class
   document.documentElement.classList.add(`sl-theme-${theme}`);
@@ -38,36 +71,59 @@ function swapTheme(theme: Theme) {
       comp.editor._themeService.setTheme(`my-${theme}-theme`);
     });
   });
+  await renderMermaid();
 }
 
-// initial
-swapTheme(getSelectedTheme());
+function handleThemeChange() {
+  // MutationObserver that watches the starlight theme attribute for changes, which is handled by the theme toggler
+  const themeObserver = new MutationObserver(() => {
+    const selectedTheme = getSelectedTheme();
+    if (currTheme !== selectedTheme && (selectedTheme === 'dark' || selectedTheme === 'light')) {
+      swapTheme(selectedTheme);
+    }
+  });
+  themeObserver.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: [themeAttr],
+  });
+}
 
-// MutationObserver that watches the starlight theme attribute for changes, which is handled by the theme toggler
-const themeObserver = new MutationObserver(() => {
-  const selectedTheme = getSelectedTheme();
-  if (currTheme !== selectedTheme && (selectedTheme === 'dark' || selectedTheme === 'light')) {
-    swapTheme(selectedTheme);
-  }
-});
-themeObserver.observe(document.documentElement, {
-  attributes: true,
-  attributeFilter: [themeAttr],
-});
+function lazilyLoadCEs(CEs: string[]) {
+  CEs.forEach((CE) => {
+    const firstInstance = document.querySelector(CE);
+    if (firstInstance) {
+      const observer = new IntersectionObserver((entries) => {
+        entries.forEach((entry) => {
+          if (entry.isIntersecting) {
+            // Conditionally load the Web Component definition if we find an instance of it.
+            import(`./components/${CE}.ts`);
+          }
+        });
+      });
+      observer.observe(firstInstance);
+    }
+  });
+}
 
-const CEs = ['sd-playground', 'sd-dtcg-convert'];
+function handleResize() {
+  let prevVPWidth = getViewportWidth();
+  window.addEventListener('resize', () => {
+    const currVWWidth = getViewportWidth();
+    if (
+      (prevVPWidth >= VP_THRESHOLD && currVWWidth < VP_THRESHOLD) ||
+      (prevVPWidth <= VP_THRESHOLD && currVWWidth > VP_THRESHOLD)
+    ) {
+      renderMermaid();
+    }
+    prevVPWidth = currVWWidth;
+  });
+}
 
-CEs.forEach((ce) => {
-  // Conditionally load the sd-playground Web Component definition if we find an instance of it.
-  const firstEl = document.querySelector(ce);
-  if (firstEl) {
-    const observer = new IntersectionObserver((entries) => {
-      entries.forEach((entry) => {
-        if (entry.isIntersecting) {
-          import(`./components/${ce}.ts`);
-        }
-      });
-    });
-    observer.observe(firstEl);
-  }
-});
+async function setup() {
+  handleThemeChange();
+  lazilyLoadCEs(['sd-playground', 'sd-dtcg-convert']);
+  handleResize();
+  // initial
+  await swapTheme(getSelectedTheme());
+}
+setup();

docs/src/styles.css

@@ -79,3 +79,15 @@ a {
     grid-template-columns: 8fr 4fr;
   }
 }
+.expressive-code pre.mermaid *:not(path) {
+  all: revert-layer;
+}
+
+#graphDiv .clickable:hover .label-container {
+  stroke: #3fc6bf;
+  stroke-width: 3px;
+}
+
+.hidden {
+  display: none !important;
+}

docs/starlight-config.ts

@@ -1,6 +1,18 @@
 import type { StarlightUserConfig } from '@astrojs/starlight/types';
+import { pluginLanguageClass } from './expressive-code-plugin-language-class.ts';
 
 export default {
+  expressiveCode: {
+    plugins: [
+      // Call the plugin initialization function inside the `plugins` array
+      pluginLanguageClass(),
+    ],
+    styleOverrides: {
+      textMarkers: {
+        defaultLuminance: ['15%', '85%'],
+      },
+    },
+  },
   title: 'Style Dictionary',
   description:
     'Export your Design Tokens to any platform. iOS, Android, CSS, JS, HTML, sketch files, style documentation, or anything you can think of. Forward-compatible with Design Token Community Group spec.',
@@ -149,13 +161,6 @@ export default {
     },
   ],
   customCss: ['./src/styles.css'],
-  expressiveCode: {
-    styleOverrides: {
-      textMarkers: {
-        defaultLuminance: ['15%', '85%'],
-      },
-    },
-  },
   components: {
     Head: './src/components/Head.astro',
   },