feat: add markdown and markdown/table

amzn · Oct 1, 2024 · ad2b987 · ad2b987
1 parent 996fc0e
commit ad2b987
Show file tree

Hide file tree

Showing 10 changed files with 568 additions and 0 deletions.
diff --git a/__integration__/__snapshots__/customFormats.test.snap.js b/__integration__/__snapshots__/customFormats.test.snap.js
@@ -717,6 +717,10 @@ snapshots["integration custom formats inline custom with new args should match s
           "name/camel",
           "color/css",
           "size/object"
+        ],
+        "markdown": [
+          "attribute/cti",
+          "name/human"
         ]
       },
       "transforms": {
@@ -1671,6 +1675,10 @@ snapshots["integration custom formats register custom format with new args shoul
           "name/camel",
           "color/css",
           "size/object"
+        ],
+        "markdown": [
+          "attribute/cti",
+          "name/human"
         ]
       },
       "transforms": {

diff --git a/__integration__/__snapshots__/markdown.test.snap.js b/__integration__/__snapshots__/markdown.test.snap.js
diff --git a/__integration__/markdown.test.js b/__integration__/markdown.test.js
@@ -0,0 +1,70 @@
+/*
+ * Copyright Target Corporation. All Rights Reserved.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance with
+ * the License. A copy of the License is located at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * or in the "license" file accompanying this file. This file is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+ * CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions
+ * and limitations under the License.
+ */
+import { expect } from 'chai';
+import StyleDictionary from 'style-dictionary';
+import { fs } from 'style-dictionary/fs';
+import { resolve } from '../lib/resolve.js';
+import { buildPath } from './_constants.js';
+import { clearOutput } from '../__tests__/__helpers.js';
+
+describe('integration', async () => {
+  before(async () => {
+    const sd = new StyleDictionary({
+      source: [`__integration__/tokens/**/[!_]*.json?(c)`],
+      platforms: {
+        markdown: {
+          transformGroup: `markdown`,
+          buildPath,
+          files: [
+            {
+              destination: 'StyleDictionary.md',
+              format: 'markdown/table',
+            },
+            {
+              destination: 'StyleDictionaryWithReferences.md',
+              format: 'markdown/table',
+              options: {
+                outputReferences: true,
+              },
+            },
+          ],
+        },
+      },
+    });
+    await sd.buildAllPlatforms();
+  });
+
+  afterEach(() => {
+    clearOutput(buildPath);
+  });
+
+  describe('markdown', async () => {
+    describe(`markdown/table`, async () => {
+      it(`should match snapshot`, async () => {
+        const output = fs.readFileSync(resolve(`${buildPath}StyleDictionary.md`), {
+          encoding: `UTF-8`,
+        });
+        await expect(output).to.matchSnapshot();
+      });
+
+      describe(`with references`, async () => {
+        it(`should match snapshot`, async () => {
+          const output = fs.readFileSync(resolve(`${buildPath}StyleDictionaryWithReferences.md`), {
+            encoding: `UTF-8`,
+          });
+          await expect(output).to.matchSnapshot();
+        });
+      });
+    });
+  });
+});
diff --git a/__tests__/formats/__snapshots__/all.test.snap.js b/__tests__/formats/__snapshots__/all.test.snap.js
@@ -1513,3 +1513,28 @@ class {
 }`;
 /* end snapshot formats all should match flutter/class.dart snapshot with fileHeaderTimestamp set */
 
+snapshots["formats all should match markdown/table snapshot"] = 
+`
+<!--
+  Do not edit directly, this file was auto-generated.
+-->
+
+| Token | Type | Value |
+| --- | --- | --- |
+| color_red | undefined | \u0060#FF0000\u0060 |
+`;
+/* end snapshot formats all should match markdown/table snapshot */
+
+snapshots["formats all should match markdown/table snapshot with fileHeaderTimestamp set"] = 
+`
+<!--
+  Do not edit directly, this file was auto-generated.
+  Generated on Sat, 01 Jan 2000 00:00:00 GMT
+-->
+
+| Token | Type | Value |
+| --- | --- | --- |
+| color_red | undefined | \u0060#FF0000\u0060 |
+`;
+/* end snapshot formats all should match markdown/table snapshot with fileHeaderTimestamp set */
+
diff --git a/docs/src/content/docs/reference/Hooks/Formats/index.md b/docs/src/content/docs/reference/Hooks/Formats/index.md
@@ -177,6 +177,7 @@ Not all formats use the `outputReferences` option because that file format might
 - [compose/object](predefined/#composeobject)
 - [ios-swift/class.swift](predefined/#ios-swiftclassswift)
 - [flutter/class.dart](predefined/#flutterclassdart)
+- [markdown/table](predefined/#markdowntable)
 
 You can create custom formats that output references as well. See the [Custom format with output references](#custom-format-with-output-references) section.
 

diff --git a/docs/src/content/docs/reference/Hooks/Formats/predefined.md b/docs/src/content/docs/reference/Hooks/Formats/predefined.md
@@ -911,3 +911,24 @@ class StyleDictionary {
 ```
 
 ---
+
+### markdown/table
+
+Creates a Markdown file containing a table with a row for each property.
+
+| Param                           | Type                                  | Description                                                                                                                                                                                                |
+| ------------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `options`                       | `Object`                              |                                                                                                                                                                                                            |
+| `options.showFileHeader`        | `boolean`                             | Whether or not to include a comment that has the build date. Defaults to `true`                                                                                                                            |
+| `options.showDescriptionColumn` | `boolean`                             | Whether or not to include the description column in the table. Defaults to `false`                                                                                                                         |
+| `options.outputReferences`      | `boolean \| OutputReferencesFunction` | Whether or not to keep [references](#references-in-output-files) (a -> b -> c) in the output. Defaults to `false`. Also allows passing a function to conditionally output references on a per token basis. |
+
+Example:
+
+```md title="colors.md"
+| Token | Type  | Value       |
+| ----- | ----- | ----------- |
+| red 5 | color | `#fffaf3f2` |
+```
+
+---
diff --git a/docs/src/content/docs/reference/Hooks/Transform Groups/predefined.md b/docs/src/content/docs/reference/Hooks/Transform Groups/predefined.md
@@ -211,3 +211,12 @@ Transforms:
 [name/camel](/reference/hooks/transforms/predefined#namecamel)
 [size/object](/reference/hooks/transforms/predefined#sizeobject)
 [color/css](/reference/hooks/transforms/predefined#colorcss)
+
+---
+
+### markdown
+
+Transforms:
+
+[attribute/cti](/reference/hooks/transforms/predefined#attributecti)
+[name/human](/reference/hooks/transforms/predefined#namehuman)
diff --git a/lib/common/formats.js b/lib/common/formats.js
@@ -45,6 +45,7 @@ import scssMapDeep from './templates/scss/map-deep.template.js';
 import scssMapFlat from './templates/scss/map-flat.template.js';
 import macrosTemplate from './templates/ios/macros.template.js';
 import plistTemplate from './templates/ios/plist.template.js';
+import markdownTable from './templates/markdown/table.md.template.js';
 
 /**
  * @typedef {import('../../types/Format.ts').Format} Format
@@ -1532,6 +1533,50 @@ declare const ${moduleName}: ${JSON.stringify(treeWalker(dictionary.tokens), nul
     });
     return flutterClassDart({ allTokens: sortedTokens, file, options, formatProperty, header });
   },
+
+  // Markdown templates
+  /**
+   * Creates a Markdown file containing a table with a row for each property.
+   *
+   * @memberof Formats
+   * @kind member
+   * @typedef {Object} markdownTableOpts
+   * @property {boolean} [markdownTableOpts.showFileHeader=true] - Whether or not to include a comment that has the build date
+   * @property {boolean} [markdownTableOpts.showDescriptionColumn=false] - Whether or not to show the description column in the table
+   * @property {OutputReferences} [markdownTableOpts.outputReferences=false] - Whether or not to keep [references](/#/formats?id=references-in-output-files) (a -> b -> c) in the output.
+   * @param {FormatArgs & { options?: markdownTableOpts }} options
+   * @example
+   * ```md
+   * | Token | Type | Value |
+   * | --- | --- | --- |
+   * | red 5 | color | `#fffaf3f2` |
+   * ```
+   */
+  'markdown/table': async function ({ dictionary, options, file }) {
+    const { allTokens, tokens, unfilteredTokens } = dictionary;
+    const { outputReferences, formatting, usesDtcg } = options;
+    const formatProperty = createPropertyFormatter({
+      outputReferences,
+      dictionary,
+      formatting,
+      usesDtcg,
+    });
+
+    let sortedTokens;
+    if (outputReferences) {
+      sortedTokens = [...allTokens].sort(sortByReference(tokens, { unfilteredTokens }));
+    } else {
+      sortedTokens = [...allTokens].sort(sortByName);
+    }
+
+    const header = await fileHeader({
+      file,
+      commentStyle: 'xml',
+      formatting: getFormattingCloneWithoutPrefix(formatting),
+      options,
+    });
+    return markdownTable({ allTokens: sortedTokens, options, formatProperty, header });
+  },
 };
 
 // Mark which formats are nested

diff --git a/lib/common/templates/markdown/table.md.template.js b/lib/common/templates/markdown/table.md.template.js
@@ -0,0 +1,30 @@
+/**
+ * @typedef {import('../../../../types/DesignToken.ts').TransformedToken} TransformedToken
+ * @typedef {import('../../../../types/Config.ts').Config} Config
+ * @typedef {import('../../../../types/Config.ts').LocalOptions} LocalOptions
+ */
+
+/**
+ * @param {{
+ *   allTokens: TransformedToken[]
+ *   formatProperty: (token: TransformedToken) => string
+ *   options: Config & LocalOptions
+ *   header: string
+ * }} opts
+ */
+export default ({ allTokens, formatProperty, options, header }) => {
+  const hasDescription = options.showDescriptionColumn;
+
+  return `
+${header}
+
+| Token | ${hasDescription ? 'Description  | ' : ''}Type | Value |
+| --- | ${hasDescription ? '---  | ' : ''}--- | --- |
+${allTokens
+  .map(
+    (token) =>
+      `| ${token.name.replace(/ $/, '')} | ${hasDescription ? (token.$description ? token.$description : token.comment ? token.comment : '') + ' | ' : ''}${token.original.type} | \u0060${options.usesDtcg ? JSON.stringify(token.original.$value) : token.original.value}\u0060 |`,
+  )
+  .join('\n')}
+`;
+};
diff --git a/lib/common/transformGroups.js b/lib/common/transformGroups.js
@@ -322,4 +322,14 @@ export default {
    * @memberof TransformGroups
    */
   'react-native': ['name/camel', 'color/css', 'size/object'],
+
+  /**
+   * Transforms:
+   *
+   * [attribute/cti](/reference/hooks/transforms/predefined#attributecti)
+   * [name/human](/reference/hooks/transforms/predefined#namehuman)
+   *
+   * @memberof TransformGroups
+   */
+  markdown: ['attribute/cti', 'name/human'],
 };