chore: create docs, upload button, ordered first

docs/src/components/sd-dtcg-convert.ts

@@ -0,0 +1,55 @@
+import { LitElement, html } from 'lit';
+import { ref, createRef } from 'lit/directives/ref.js';
+import '@shoelace-style/shoelace/dist/components/button/button.js';
+import { convertJSONToDTCG, convertZIPToDTCG } from '../../../lib/utils/convertToDTCG.js';
+import { downloadJSON, downloadZIP } from '../../../lib/utils/downloadFile.js';
+
+class SdDtcgConvert extends LitElement {
+  fileInputRef = createRef();
+
+  render() {
+    return html`
+      <sl-button @click=${this.triggerUpload} variant="primary">Convert tokens to DTCG</sl-button>
+      <input
+        ${ref(this.fileInputRef)}
+        @change=${this.upload}
+        id="upload-tokens-input"
+        type="file"
+        accept="application/*, text/*"
+        aria-hidden="true"
+        hidden
+      />
+    `;
+  }
+
+  triggerUpload() {
+    const fileInput = this.fileInputRef.value;
+    if (fileInput) {
+      fileInput.dispatchEvent(new MouseEvent('click'));
+    }
+  }
+
+  async upload(ev: Event) {
+    if (ev.target instanceof HTMLInputElement) {
+      const file = ev.target.files?.[0];
+      if (file) {
+        const today = new Date(Date.now());
+        const filename = `dtcg-tokens_${today.getFullYear()}-${today.getMonth()}-${(
+          '0' + today.getDate()
+        ).slice(-2)}`;
+
+        if (file.type.includes('zip')) {
+          const zipBlob = await convertZIPToDTCG(file);
+          await downloadZIP(zipBlob, `${filename}.zip`);
+        } else if (file.type.includes('json')) {
+          const jsonBlob = await convertJSONToDTCG(file);
+          await downloadJSON(jsonBlob, `${filename}.json`);
+        } else {
+          throw new Error('Only ZIP and JSON type uploads are supported.');
+        }
+      }
+    }
+  }
+}
+
+customElements.define('sd-dtcg-convert', SdDtcgConvert);

docs/src/components/sd-playground.ts

@@ -11,8 +11,8 @@ import '@shoelace-style/shoelace/dist/components/option/option.js';
 import { bundle } from '../utils/rollup-bundle.ts';
 import { changeLang, init, monaco } from '../monaco/monaco.ts';
 import { analyzeDependencies } from '../utils/analyzeDependencies.ts';
-import type SlRadioGroup from '@shoelace-style/shoelace/dist/components/radio-group/radio-group.js';
 import { downloadZIP } from '../../../lib/utils/downloadFile.js';
+import type SlRadioGroup from '@shoelace-style/shoelace/dist/components/radio-group/radio-group.js';
 
 const { Volume } = memfs;
 

docs/src/content/docs/info/DTCG.mdx

@@ -0,0 +1,35 @@
+---
+title: Design Token Community Group
+sidebar:
+  order: 4
+---
+
+import tokens from '/public/demo-tokens.json';
+
+There is a [W3C Design Token Community Group](https://www.w3.org/community/design-tokens/), whose goal it is to "provide standards upon which products and design tools can rely for sharing stylistic pieces of a design system at scale".
+
+What that boils down to right now is a [draft specification for how Design Tokens ought to be formatted](https://design-tokens.github.io/community-group/format/), for cross-tool and cross-platform interoperability.
+Since Style Dictionary v4, we have first-class support for this format.
+
+## Convert your Tokens to DTCG
+
+We also export a tool that allows you to convert your design tokens in the old format to the DTCG format:
+
+<div spacer></div>
+<sd-dtcg-convert></sd-dtcg-convert>
+
+What it does:
+
+- Turn `value`, `type` and `description` design token property keys into `$value`, `$type` and `$description` respectively.
+- Move the `$type` properties from the design tokens onto the uppermost common ancestor token group
+
+What it does not do (atm, feel free to raise suggestions):
+
+- Refactor type values commonly used to the DTCG types, e.g. size -> dimension.
+
+## Live demo
+
+<sd-playground tokens={JSON.stringify({ value: JSON.stringify(tokens, null, 2), lang: 'json'})} default-selected="tokens" id="main-demo">
+
+  <div style="height: 100%" slot="monaco-editor"></div>
+</sd-playground>

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

@@ -1,5 +1,7 @@
 ---
 title: Architecture
+sidebar:
+  order: 2
 ---
 
 This is how Style Dictionary works under the hood.

docs/src/content/docs/info/package_structure.mdx

@@ -1,5 +1,7 @@
 ---
 title: Package Structure
+sidebar:
+  order: 3
 ---
 
 import { FileTree } from '@astrojs/starlight/components';

docs/src/setup.ts

@@ -55,16 +55,19 @@ themeObserver.observe(document.documentElement, {
   attributeFilter: [themeAttr],
 });
 
-// Conditionally load the sd-playground Web Component definition if we find an instance of it.
-const firstPlaygroundEl = document.querySelector('sd-playground');
+const CEs = ['sd-playground', 'sd-dtcg-convert'];
 
-if (firstPlaygroundEl) {
-  const observer = new IntersectionObserver((entries) => {
-    entries.forEach((entry) => {
-      if (entry.isIntersecting) {
-        import('./components/sd-playground.ts');
-      }
+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(firstPlaygroundEl);
-}
+    observer.observe(firstEl);
+  }
+});

lib/utils/convertToDTCG.js

@@ -57,9 +57,20 @@ function recurse(slice, opts) {
     // If it's only 1 type, we know we can apply the type on the ancestor group
     // and remove it from the children
     if (types.size === 1 && opts?.applyTypesToGroup !== false) {
-      slice.$type = [...types][0];
+      const entries = Object.entries(slice);
+
+      // TODO: add test that checks $type being ordered first on token groups
+      // delete everything in the slice without losing the reference to the slice
       Object.keys(slice).forEach((key) => {
-        delete slice[key].$type;
+        delete slice[key];
+      });
+      // put the type FIRST
+      slice.$type = [...types][0];
+      // then put the rest of the key value pairs back, now we always ordered $type first on the token group
+      entries.forEach(([key, value]) => {
+        if (key !== '$type') {
+          slice[key] = value;
+        }
       });
     }
   }
@@ -106,7 +117,7 @@ async function blobify(blobOrPath) {
  * @param {string} [path]
  */
 function validateBlobType(blob, type, path) {
-  if (blob.type.includes(type)) {
+  if (!blob.type.includes(type)) {
     throw new Error(
       `File ${path ?? '(Blob)'} is of type ${blob.type}, but a ${type} type blob was expected.`,
     );