feat: introduce and provide enum-like JS objects for most hardcoded c…

…onfig strings (#1367)
amzn · Dec 9, 2024 · fbd0eb2 · fbd0eb2
1 parent 5aad797
commit fbd0eb2
Show file tree

Hide file tree

Showing 122 changed files with 2,851 additions and 1,927 deletions.
diff --git a/.changeset/five-vans-whisper.md b/.changeset/five-vans-whisper.md
@@ -0,0 +1,5 @@
+---
+'style-dictionary': minor
+---
+
+Introduce a new entrypoint: `style-dictionary/enums` for most of the library's hard-coded string values. Most of these are built-in hooks names. This provides better type-safety for consumers as well as various maintainability related benefits for this library. [See documentation for more info](https://styledictionary.com/reference/enums).
diff --git a/README.md b/README.md
@@ -91,16 +91,18 @@ StyleDictionary.buildAllPlatforms();
 The `.extend()` method is an overloaded method that can also take an object with the configuration in the same format as a config.json file.
 
 ```javascript
+import { formats, transformGroups } from 'style-dictionary/enums';
+
 const StyleDictionary = require('style-dictionary').extend({
   source: ['tokens/**/*.json'],
   platforms: {
     scss: {
-      transformGroup: 'scss',
+      transformGroup: transformGroups.scss,
       buildPath: 'build/',
       files: [
         {
           destination: 'variables.scss',
-          format: 'scss/variables',
+          format: formats.scssVariables,
         },
       ],
     },
@@ -294,10 +296,11 @@ The style dictionary build system is made to be extended. We don't know exactly
 
 ```javascript
 const StyleDictionary = require('style-dictionary').extend('config.json');
+import { transforms, transformTypes } from 'style-dictionary/enums';
 
 StyleDictionary.registerTransform({
-  name: 'time/seconds',
-  type: 'value',
+  name: transforms.timeSeconds,
+  type: transformTypes.value,
   filter: function (token) {
     return token.type === 'time';
   },

diff --git a/__integration__/android.test.js b/__integration__/android.test.js
@@ -16,30 +16,34 @@ import { fs } from 'style-dictionary/fs';
 import { resolve } from '../lib/resolve.js';
 import { buildPath } from './_constants.js';
 import { clearOutput } from '../__tests__/__helpers.js';
+import { formats, transformGroups } from 'style-dictionary/enums';
+
+const { androidResources } = formats;
+const { android } = transformGroups;
 
 describe('integration', async () => {
   before(async () => {
     const sd = new StyleDictionary({
       source: [`__integration__/tokens/**/[!_]*.json?(c)`],
       platforms: {
         android: {
-          transformGroup: `android`,
+          transformGroup: android,
           buildPath,
           files: [
             {
               destination: `resources.xml`,
-              format: `android/resources`,
+              format: androidResources,
             },
             {
               destination: `resourcesWithReferences.xml`,
-              format: `android/resources`,
+              format: androidResources,
               options: {
                 outputReferences: true,
               },
             },
             {
               destination: `colors.xml`,
-              format: `android/resources`,
+              format: androidResources,
               filter: {
                 type: `color`,
               },
@@ -56,7 +60,7 @@ describe('integration', async () => {
   });
 
   describe('android', async () => {
-    describe(`android/resources`, async () => {
+    describe(androidResources, async () => {
       it(`should match snapshot`, async () => {
         const output = fs.readFileSync(resolve(`${buildPath}resources.xml`), {
           encoding: 'UTF-8',

diff --git a/__integration__/async.test.js b/__integration__/async.test.js
@@ -17,11 +17,12 @@ import { fs } from 'style-dictionary/fs';
 import { resolve } from '../lib/resolve.js';
 import { buildPath } from './_constants.js';
 import { clearOutput } from '../__tests__/__helpers.js';
+import { transforms, propertyFormatNames, transformTypes } from '../lib/enums/index.js';
 
 const sleep = async (time) => {
   await new Promise((resolve) => setTimeout(resolve, time));
 };
-
+const { attributeCti, nameKebab, timeSeconds, htmlIcon, sizeRem, colorCss } = transforms;
 const textFile = resolve(`${buildPath}text.txt`);
 
 // Tests all hooks async, into a single config
@@ -58,7 +59,7 @@ describe('integration', async function () {
 
     SDExtension.registerTransform({
       name: 'foo-value-transform',
-      type: 'value',
+      type: transformTypes.value,
       filter: (token) => token.value === 'foo',
       transform: async () => {
         await sleep(10);
@@ -74,7 +75,11 @@ describe('integration', async function () {
         return (
           (await fileHeader({ file })) +
           ':root {\n' +
-          formattedVariables({ format: 'css', dictionary, outputReferences }) +
+          formattedVariables({
+            format: propertyFormatNames.css,
+            dictionary,
+            outputReferences,
+          }) +
           '\n}\n'
         );
       },
@@ -96,12 +101,12 @@ describe('integration', async function () {
       platforms: {
         css: {
           transforms: [
-            'attribute/cti',
-            'name/kebab',
-            'time/seconds',
-            'html/icon',
-            'size/rem',
-            'color/css',
+            attributeCti,
+            nameKebab,
+            timeSeconds,
+            htmlIcon,
+            sizeRem,
+            colorCss,
             'foo-value-transform',
           ],
           buildPath,

diff --git a/__integration__/compose.test.js b/__integration__/compose.test.js
@@ -16,6 +16,9 @@ import { fs } from 'style-dictionary/fs';
 import { resolve } from '../lib/resolve.js';
 import { buildPath } from './_constants.js';
 import { clearOutput } from '../__tests__/__helpers.js';
+import { formats } from '../lib/enums/index.js';
+
+const { composeObject } = formats;
 
 describe('integration', async () => {
   before(async () => {
@@ -28,15 +31,15 @@ describe('integration', async () => {
           files: [
             {
               destination: 'StyleDictionary.kt',
-              format: 'compose/object',
+              format: composeObject,
               options: {
                 className: 'StyleDictionary',
                 packageName: 'com.example.tokens',
               },
             },
             {
               destination: 'StyleDictionaryWithReferences.kt',
-              format: 'compose/object',
+              format: composeObject,
               options: {
                 outputReferences: true,
                 className: 'StyleDictionary',

diff --git a/__integration__/css.test.js b/__integration__/css.test.js
@@ -16,6 +16,9 @@ import { fs } from 'style-dictionary/fs';
 import { resolve } from '../lib/resolve.js';
 import { buildPath } from './_constants.js';
 import { clearOutput } from '../__tests__/__helpers.js';
+import { formats, transformGroups } from '../lib/enums/index.js';
+
+const { cssVariables } = formats;
 
 describe('integration', async () => {
   before(async () => {
@@ -33,35 +36,35 @@ describe('integration', async () => {
       },
       platforms: {
         css: {
-          transformGroup: 'css',
+          transformGroup: transformGroups.css,
           buildPath,
           files: [
             {
               destination: 'variables.css',
-              format: 'css/variables',
+              format: cssVariables,
               options: {
                 formatting: { indentation: '    ' },
               },
             },
             {
               destination: 'variablesWithReferences.css',
-              format: 'css/variables',
+              format: cssVariables,
               options: {
                 outputReferences: true,
                 outputReferenceFallbacks: false,
               },
             },
             {
               destination: 'variablesWithReferenceFallbacks.css',
-              format: 'css/variables',
+              format: cssVariables,
               options: {
                 outputReferences: true,
                 outputReferenceFallbacks: true,
               },
             },
             {
               destination: 'variablesWithSelector.css',
-              format: 'css/variables',
+              format: cssVariables,
               options: {
                 selector: '.test',
               },
@@ -78,7 +81,7 @@ describe('integration', async () => {
   });
 
   describe('css', async () => {
-    describe('css/variables', async () => {
+    describe(cssVariables, async () => {
       it(`should match snapshot`, async () => {
         const output = fs.readFileSync(resolve(`${buildPath}variables.css`), {
           encoding: 'UTF-8',

diff --git a/__integration__/customFileHeader.test.js b/__integration__/customFileHeader.test.js
@@ -16,6 +16,10 @@ import { fs } from 'style-dictionary/fs';
 import { resolve } from '../lib/resolve.js';
 import { buildPath } from './_constants.js';
 import { clearOutput } from '../__tests__/__helpers.js';
+import { formats, transformGroups } from '../lib/enums/index.js';
+
+const { cssVariables, javascriptModule } = formats;
+const { css, js } = transformGroups;
 
 describe(`integration`, async () => {
   before(async () => {
@@ -46,26 +50,26 @@ describe(`integration`, async () => {
 
       platforms: {
         css: {
-          transformGroup: `css`,
+          transformGroup: css,
           buildPath,
           files: [
             {
               destination: `registeredFileHeader.css`,
-              format: `css/variables`,
+              format: cssVariables,
               options: {
                 fileHeader: `valid custom file headers test fileHeader`,
               },
             },
             {
               destination: `configFileHeader.css`,
-              format: `css/variables`,
+              format: cssVariables,
               options: {
                 fileHeader: `configFileHeader`,
               },
             },
             {
               destination: `inlineFileHeader.css`,
-              format: `css/variables`,
+              format: cssVariables,
               options: {
                 fileHeader: () => {
                   return [`build version 1.0.0`];
@@ -75,26 +79,26 @@ describe(`integration`, async () => {
           ],
         },
         js: {
-          transformGroup: `js`,
+          transformGroup: js,
           buildPath,
           options: {
             fileHeader: `configFileHeader`,
           },
           files: [
             {
               destination: `noOptions.js`,
-              format: `javascript/module`,
+              format: javascriptModule,
             },
             {
               destination: `showFileHeader.js`,
-              format: `javascript/module`,
+              format: javascriptModule,
               options: {
                 showFileHeader: false,
               },
             },
             {
               destination: `fileHeaderOverride.js`,
-              format: `javascript/module`,
+              format: javascriptModule,
               options: {
                 fileHeader: () => [`Header overridden`],
               },

diff --git a/__integration__/customFormats.test.js b/__integration__/customFormats.test.js
@@ -16,6 +16,9 @@ import { fs } from 'style-dictionary/fs';
 import { resolve } from '../lib/resolve.js';
 import { buildPath } from './_constants.js';
 import { clearOutput } from '../__tests__/__helpers.js';
+import { transformGroups } from '../lib/enums/index.js';
+
+const { js } = transformGroups;
 
 describe('integration', async () => {
   before(async () => {
@@ -34,7 +37,7 @@ describe('integration', async () => {
       },
       platforms: {
         inlineCustomFormats: {
-          transformGroup: 'js',
+          transformGroup: js,
           buildPath,
           options: {
             otherOption: `platform option`,
@@ -59,7 +62,7 @@ describe('integration', async () => {
           ],
         },
         customFormats: {
-          transformGroup: 'js',
+          transformGroup: js,
           buildPath,
           options: {
             otherOption: `platform option`,

diff --git a/__integration__/flutter.test.js b/__integration__/flutter.test.js
@@ -16,26 +16,30 @@ import { fs } from 'style-dictionary/fs';
 import { resolve } from '../lib/resolve.js';
 import { buildPath } from './_constants.js';
 import { clearOutput } from '../__tests__/__helpers.js';
+import { formats, transformGroups } from '../lib/enums/index.js';
+
+const { flutterClassDart } = formats;
+const { flutter, flutterSeparate } = transformGroups;
 
 describe('integration', async () => {
   before(async () => {
     const sd = new StyleDictionary({
       source: [`__integration__/tokens/**/[!_]*.json?(c)`],
       platforms: {
         flutter: {
-          transformGroup: `flutter`,
+          transformGroup: flutter,
           buildPath,
           files: [
             {
               destination: 'style_dictionary.dart',
-              format: 'flutter/class.dart',
+              format: flutterClassDart,
               options: {
                 className: 'StyleDictionary',
               },
             },
             {
               destination: 'style_dictionary_with_references.dart',
-              format: 'flutter/class.dart',
+              format: flutterClassDart,
               options: {
                 outputReferences: true,
                 className: 'StyleDictionary',
@@ -44,12 +48,12 @@ describe('integration', async () => {
           ],
         },
         flutter_separate: {
-          transformGroup: `flutter-separate`,
+          transformGroup: flutterSeparate,
           buildPath,
           files: [
             {
               destination: 'style_dictionary_color.dart',
-              format: 'flutter/class.dart',
+              format: flutterClassDart,
               options: {
                 className: 'StyleDictionaryColor',
                 type: 'color',
@@ -60,7 +64,7 @@ describe('integration', async () => {
             },
             {
               destination: 'style_dictionary_sizes.dart',
-              format: 'flutter/class.dart',
+              format: flutterClassDart,
               options: {
                 className: 'StyleDictionarySize',
                 type: 'float',