fix: .d.ts type issue and resulting type errors (#1249)

* fix: .d.ts type issue and resulting type errors * chore: switch to using TS files for local reusable type interfaces * fix: remove on token group level
amzn · Jun 28, 2024 · cb78c3d · cb78c3d
1 parent 076c969
commit cb78c3d
Show file tree

Hide file tree

Showing 92 changed files with 373 additions and 347 deletions.
diff --git a/.changeset/beige-parrots-complain.md b/.changeset/beige-parrots-complain.md
@@ -0,0 +1,5 @@
+---
+'style-dictionary': patch
+---
+
+Update `typeDtcgDelegate` utility to remove the $type on token group level between parsing/preprocessing step.
diff --git a/__tests__/utils/typeDtcgDelegate.test.js b/__tests__/utils/typeDtcgDelegate.test.js
@@ -54,7 +54,6 @@ describe('utils', () => {
 
       expect(typeDtcgDelegate(tokens)).to.eql({
         dimension: {
-          $type: 'dimension',
           scale: {
             $value: '2',
             $type: 'math',
@@ -71,9 +70,7 @@ describe('utils', () => {
               },
             },
             deep2: {
-              $type: 'math',
               deeper: {
-                $type: 'other',
                 evenDeeper: {
                   $value: '12',
                   $type: 'math',
@@ -132,7 +129,6 @@ describe('utils', () => {
 
       expect(typeDtcgDelegate(tokens)).to.eql({
         dimension: {
-          $type: 'dimension',
           scale: {
             $value: '2',
             $type: 'math',
@@ -149,9 +145,7 @@ describe('utils', () => {
               },
             },
             deep2: {
-              $type: 'math',
               deeper: {
-                $type: 'other',
                 evenDeeper: {
                   $value: '12',
                   $type: 'math',

diff --git a/docs/src/components/sd-playground.ts b/docs/src/components/sd-playground.ts
@@ -1,5 +1,4 @@
 import StyleDictionary from 'style-dictionary';
-import type { Config } from 'style-dictionary/types';
 import memfs from '@bundled-es-modules/memfs';
 import type { fs as VolumeType } from 'memfs';
 import { LitElement, html, css } from 'lit';
@@ -13,6 +12,7 @@ import { changeLang, init, monaco } from '../monaco/monaco.ts';
 import { analyzeDependencies } from '../utils/analyzeDependencies.ts';
 import { downloadZIP } from '../../../lib/utils/downloadFile.js';
 import type SlRadioGroup from '@shoelace-style/shoelace/dist/components/radio-group/radio-group.js';
+import type { Config } from '../../../types/Config.ts';
 
 const { Volume } = memfs;
 

diff --git a/docs/src/content/docs/reference/Utils/DTCG.md b/docs/src/content/docs/reference/Utils/DTCG.md
@@ -67,6 +67,11 @@ We built this utility because it's cheaper to apply the inheritance once, rather
 
 This utility runs by default in Style-Dictionary after the parser hook and before the preprocessor hook.
 
+:::caution
+Important to note is that the `$type` prop on the group level will be removed during this step, and will only exist on the token level.
+If you want the `$type` to go back to the group level (highest possible common ancestor), then please use [`convertToDTCG`](#converttodtcg) for this.
+:::
+
 ```js
 import { typeDtcgDelegate } from 'style-dictionary/utils';
 
@@ -105,7 +110,6 @@ Output:
 ```js
 {
   dimensions: {
-    $type: 'dimension',
     sm: {
       $value: '5',
       $type: 'dimension',

diff --git a/examples/advanced/tokens-deprecation/templates/ios-plist.template.js b/examples/advanced/tokens-deprecation/templates/ios-plist.template.js
@@ -1,9 +1,9 @@
 /**
- * @typedef {import('../../../../types/DesignToken.d.ts').Dictionary} Dictionary
- * @typedef {import('../../../../types/DesignToken.d.ts').TransformedToken} TransformedToken
- * @typedef {import('../../../../types/File.d.ts').File} File
- * @typedef {import('../../../../types/Config.d.ts').Config} Config
- * @typedef {import('../../../../types/Config.d.ts').LocalOptions} LocalOptions
+ * @typedef {import('style-dictionary/types').Dictionary} Dictionary
+ * @typedef {import('style-dictionary/types').TransformedToken} TransformedToken
+ * @typedef {import('style-dictionary/types').File} File
+ * @typedef {import('style-dictionary/types').Config} Config
+ * @typedef {import('style-dictionary/types').LocalOptions} LocalOptions
  */
 
 /**

diff --git a/examples/advanced/tokens-deprecation/templates/web-scss.template.js b/examples/advanced/tokens-deprecation/templates/web-scss.template.js
@@ -1,7 +1,7 @@
 /**
- * @typedef {import('../../../../types/DesignToken.d.ts').TransformedToken} TransformedToken
- * @typedef {import('../../../../types/Config.d.ts').Config} Config
- * @typedef {import('../../../../types/Config.d.ts').LocalOptions} LocalOptions
+ * @typedef {import('style-dictionary/types').TransformedToken} TransformedToken
+ * @typedef {import('style-dictionary/types').Config} Config
+ * @typedef {import('style-dictionary/types').LocalOptions} LocalOptions
  */
 
 /**

diff --git a/lib/Register.js b/lib/Register.js
@@ -6,14 +6,14 @@ import filterBuiltins from './common/filters.js';
 import { deepmerge } from './utils/deepmerge.js';
 
 /**
- * @typedef {import('../types/File.d.ts').FileHeader} FileHeader
- * @typedef {import('../types/Parser.d.ts').Parser} Parser
- * @typedef {import('../types/Preprocessor.d.ts').Preprocessor} Preprocessor
- * @typedef {import('../types/Transform.d.ts').Transform} Transform
- * @typedef {import('../types/Filter.d.ts').Filter} Filter
- * @typedef {import('../types/Format.d.ts').Format} Format
- * @typedef {import('../types/Action.d.ts').Action} Action
- * @typedef {import('../types/Config.d.ts').Hooks} Hooks
+ * @typedef {import('../types/File.ts').FileHeader} FileHeader
+ * @typedef {import('../types/Parser.ts').Parser} Parser
+ * @typedef {import('../types/Preprocessor.ts').Preprocessor} Preprocessor
+ * @typedef {import('../types/Transform.ts').Transform} Transform
+ * @typedef {import('../types/Filter.ts').Filter} Filter
+ * @typedef {import('../types/Format.ts').Format} Format
+ * @typedef {import('../types/Action.ts').Action} Action
+ * @typedef {import('../types/Config.ts').Hooks} Hooks
  */
 
 /**
@@ -293,7 +293,7 @@ export class Register {
   }
 
   /**
-   * @param {import('../types/Parser.d.ts').Parser} parser
+   * @param {import('../types/Parser.ts').Parser} parser
    * @param {typeof Register | Register} target
    */
   static __registerParser(parser, target) {

diff --git a/lib/StyleDictionary.js b/lib/StyleDictionary.js
@@ -41,19 +41,20 @@ import cleanDirs from './cleanDirs.js';
 import cleanActions from './cleanActions.js';
 
 /**
- * @typedef {import('../types/Volume.d.ts').Volume} Volume
- * @typedef {import('../types/Config.d.ts').Config} Config
- * @typedef {import('../types/Config.d.ts').PlatformConfig} PlatformConfig
- * @typedef {import('../types/Config.d.ts').LogConfig} LogConfig
- * @typedef {import('../types/Config.d.ts').Expand} Expand
- * @typedef {import('../types/Config.d.ts').ExpandConfig} ExpandConfig
- * @typedef {import('../types/File.d.ts').File} File
- * @typedef {import('../types/Filter.d.ts').Filter} Filter
- * @typedef {import('../types/DesignToken.d.ts').DesignToken} Token
- * @typedef {import('../types/DesignToken.d.ts').TransformedToken} TransformedToken
- * @typedef {import('../types/DesignToken.d.ts').DesignTokens} Tokens
- * @typedef {import('../types/DesignToken.d.ts').TransformedTokens} TransformedTokens
- * @typedef {import('../types/DesignToken.d.ts').Dictionary} Dictionary
+ * @typedef {import('../types/Volume.ts').Volume} Volume
+ * @typedef {import('../types/Config.ts').Config} Config
+ * @typedef {import('../types/Config.ts').PlatformConfig} PlatformConfig
+ * @typedef {import('../types/Config.ts').LogConfig} LogConfig
+ * @typedef {import('../types/Config.ts').Expand} Expand
+ * @typedef {import('../types/Config.ts').ExpandConfig} ExpandConfig
+ * @typedef {import('../types/File.ts').File} File
+ * @typedef {import('../types/Filter.ts').Filter} Filter
+ * @typedef {import('../types/DesignToken.ts').DesignToken} Token
+ * @typedef {import('../types/DesignToken.ts').TransformedToken} TransformedToken
+ * @typedef {import('../types/DesignToken.ts').DesignTokens} Tokens
+ * @typedef {import('../types/DesignToken.ts').PreprocessedTokens} PreprocessedTokens
+ * @typedef {import('../types/DesignToken.ts').TransformedTokens} TransformedTokens
+ * @typedef {import('../types/DesignToken.ts').Dictionary} Dictionary
  */
 
 const PROPERTY_VALUE_COLLISIONS = GroupMessages.GROUP.PropertyValueCollisions;
@@ -109,7 +110,7 @@ export default class StyleDictionary extends Register {
     super();
     this.config = config;
     this.options = {};
-    /** @type {Tokens|TransformedTokens} */
+    /** @type {Tokens|TransformedTokens|PreprocessedTokens} */
     this.tokens = {};
     /** @type {TransformedToken[]} */
     this.allTokens = [];
@@ -332,16 +333,19 @@ export default class StyleDictionary extends Register {
     }
 
     // Merge inline, include, and source tokens
+    /** @type {PreprocessedTokens|Tokens} */
     let tokens = deepExtend([{}, inlineTokens, includeTokens, sourceTokens]);
     if (this.usesDtcg) {
+      // this is where they go from type Tokens -> Preprocessed tokens because the prop $type is removed
       tokens = typeDtcgDelegate(tokens);
     }
+    let preprocessedTokens = /** @type {PreprocessedTokens} */ (tokens);
     if (this.shouldRunExpansion(this.expand)) {
-      tokens = expandTokens(tokens, this.options);
+      preprocessedTokens = expandTokens(preprocessedTokens, this.options);
     }
     this.options = { ...this.options, usesDtcg: this.usesDtcg };
     this.tokens = await preprocess(
-      tokens,
+      preprocessedTokens,
       this.preprocessors,
       this.hooks.preprocessors,
       this.options,
@@ -386,7 +390,7 @@ export default class StyleDictionary extends Register {
     // We don't want to mutate the original object
     const platformConfig = transformConfig(this.platforms[platform], this, platform);
 
-    let platformProcessedTokens = this.tokens;
+    let platformProcessedTokens = /** @type {PreprocessedTokens} */ (this.tokens);
     if (this.shouldRunExpansion(platformConfig.expand)) {
       platformProcessedTokens = expandTokens(platformProcessedTokens, this.options, platformConfig);
     }
@@ -396,7 +400,9 @@ export default class StyleDictionary extends Register {
       this.hooks.preprocessors,
     );
 
-    let exportableResult = platformProcessedTokens;
+    let exportableResult = /** @type {PreprocessedTokens|TransformedTokens} */ (
+      platformProcessedTokens
+    );
 
     /**
      * @type {string[]}

diff --git a/lib/cleanActions.js b/lib/cleanActions.js
@@ -13,10 +13,10 @@
 import { fs } from 'style-dictionary/fs';
 
 /**
- * @typedef {import('../types/Volume.d.ts').Volume} Volume
- * @typedef {import('../types/DesignToken.d.ts').Dictionary} Dictionary
- * @typedef {import('../types/Config.d.ts').PlatformConfig} PlatformConfig
- * @typedef {import('../types/Config.d.ts').Config} Config
+ * @typedef {import('../types/Volume.ts').Volume} Volume
+ * @typedef {import('../types/DesignToken.ts').Dictionary} Dictionary
+ * @typedef {import('../types/Config.ts').PlatformConfig} PlatformConfig
+ * @typedef {import('../types/Config.ts').Config} Config
  */
 
 /**

diff --git a/lib/cleanDir.js b/lib/cleanDir.js
@@ -16,9 +16,9 @@ import { dirname } from 'path-unified';
 import { fs } from 'style-dictionary/fs';
 
 /**
- * @typedef {import('../types/Volume.d.ts').Volume} Volume
- * @typedef {import('../types/Config.d.ts').PlatformConfig} Config
- * @typedef {import('../types/File.d.ts').File} File
+ * @typedef {import('../types/Volume.ts').Volume} Volume
+ * @typedef {import('../types/Config.ts').PlatformConfig} Config
+ * @typedef {import('../types/File.ts').File} File
  */
 
 /**

diff --git a/lib/cleanDirs.js b/lib/cleanDirs.js
@@ -14,8 +14,8 @@
 import cleanDir from './cleanDir.js';
 
 /**
- * @typedef {import('../types/Volume.d.ts').Volume} Volume
- * @typedef {import('../types/Config.d.ts').PlatformConfig} Config
+ * @typedef {import('../types/Volume.ts').Volume} Volume
+ * @typedef {import('../types/Config.ts').PlatformConfig} Config
  */
 
 /**

diff --git a/lib/cleanFile.js b/lib/cleanFile.js
@@ -15,9 +15,9 @@ import chalk from 'chalk';
 import { fs } from 'style-dictionary/fs';
 
 /**
- * @typedef {import('../types/Volume.d.ts').Volume} Volume
- * @typedef {import('../types/File.d.ts').File} File
- * @typedef {import('../types/Config.d.ts').PlatformConfig} PlatformConfig
+ * @typedef {import('../types/Volume.ts').Volume} Volume
+ * @typedef {import('../types/File.ts').File} File
+ * @typedef {import('../types/Config.ts').PlatformConfig} PlatformConfig
  */
 
 /**

diff --git a/lib/cleanFiles.js b/lib/cleanFiles.js
@@ -14,8 +14,8 @@
 import cleanFile from './cleanFile.js';
 
 /**
- * @typedef {import('../types/Volume.d.ts').Volume} Volume
- * @typedef {import('../types/Config.d.ts').PlatformConfig} PlatformConfig
+ * @typedef {import('../types/Volume.ts').Volume} Volume
+ * @typedef {import('../types/Config.ts').PlatformConfig} PlatformConfig
  */
 
 /**

diff --git a/lib/common/actions.js b/lib/common/actions.js
@@ -14,10 +14,10 @@
 import { fs } from 'style-dictionary/fs';
 
 /**
- * @typedef {import('../../types/DesignToken.d.ts').Dictionary} Dictionary
- * @typedef {import('../../types/Action.d.ts').Action} Action
+ * @typedef {import('../../types/DesignToken.ts').Dictionary} Dictionary
+ * @typedef {import('../../types/Action.ts').Action} Action
  * @typedef {import('../../types/Config.js').PlatformConfig} Config
- * @typedef {import('../../types/DesignToken.d.ts').TransformedToken} Token
+ * @typedef {import('../../types/DesignToken.ts').TransformedToken} Token
  */
 
 /**

diff --git a/lib/common/filters.js b/lib/common/filters.js
@@ -12,7 +12,7 @@
  */
 
 /**
- * @typedef {import('../../types/Filter.d.ts').Filter} Filter
+ * @typedef {import('../../types/Filter.ts').Filter} Filter
  */
 
 /**

diff --git a/lib/common/formatHelpers/createPropertyFormatter.js b/lib/common/formatHelpers/createPropertyFormatter.js
@@ -14,10 +14,10 @@ import { getReferences } from '../../utils/references/getReferences.js';
 import usesReferences from '../../utils/references/usesReferences.js';
 
 /**
- * @typedef {import('../../../types/DesignToken.d.ts').TransformedToken} TransformedToken
- * @typedef {import('../../../types/DesignToken.d.ts').Dictionary} Dictionary
- * @typedef {import('../../../types/File.d.ts').FormattingOptions} Formatting
- * @typedef {import('../../../types/Format.d.ts').OutputReferences} OutputReferences
+ * @typedef {import('../../../types/DesignToken.ts').TransformedToken} TransformedToken
+ * @typedef {import('../../../types/DesignToken.ts').Dictionary} Dictionary
+ * @typedef {import('../../../types/File.ts').FormattingOptions} Formatting
+ * @typedef {import('../../../types/Format.ts').OutputReferences} OutputReferences
  */
 
 /**
@@ -116,7 +116,7 @@ function addComment(to_ret_token, comment, options) {
  * @param {Formatting} [options.formatting] - Custom formatting properties that define parts of a declaration line in code. The configurable strings are: `prefix`, `indentation`, `separator`, `suffix`, `lineSeparator`, `fileHeaderTimestamp`, `header`, `footer`, `commentStyle` and `commentPosition`. Those are used to generate a line like this: `${indentation}${prefix}${token.name}${separator} ${prop.value}${suffix}`. The remaining formatting options are used for the fileHeader helper.
  * @param {boolean} [options.themeable] [false] - Whether tokens should default to being themeable.
  * @param {boolean} [options.usesDtcg] [false] - Whether DTCG token syntax should be uses.
- * @returns {(token: import('../../../types/DesignToken.d.ts').TransformedToken) => string}
+ * @returns {(token: import('../../../types/DesignToken.ts').TransformedToken) => string}
  */
 export default function createPropertyFormatter({
   outputReferences = false,

diff --git a/lib/common/formatHelpers/fileHeader.js b/lib/common/formatHelpers/fileHeader.js
@@ -12,10 +12,10 @@
  */
 
 /**
- * @typedef {import('../../../types/File.d.ts').File} File
- * @typedef {import('../../../types/File.d.ts').FileHeader} FileHeader
- * @typedef {import('../../../types/File.d.ts').FormattingOptions} Formatting
- * @typedef {import('../../../types/Config.d.ts').Config} Config
+ * @typedef {import('../../../types/File.ts').File} File
+ * @typedef {import('../../../types/File.ts').FileHeader} FileHeader
+ * @typedef {import('../../../types/File.ts').FormattingOptions} Formatting
+ * @typedef {import('../../../types/Config.ts').Config} Config
  */
 
 const lineSeparator = `\n`;

diff --git a/lib/common/formatHelpers/formattedVariables.js b/lib/common/formatHelpers/formattedVariables.js
@@ -15,11 +15,11 @@ import createPropertyFormatter from './createPropertyFormatter.js';
 import sortByReference from './sortByReference.js';
 
 /**
- * @typedef {import('../../../types/DesignToken.d.ts').TransformedToken} Token
- * @typedef {import('../../../types/DesignToken.d.ts').TransformedTokens} Tokens
- * @typedef {import('../../../types/File.d.ts').FormattingOptions} Formatting
+ * @typedef {import('../../../types/DesignToken.ts').TransformedToken} Token
+ * @typedef {import('../../../types/DesignToken.ts').TransformedTokens} Tokens
+ * @typedef {import('../../../types/File.ts').FormattingOptions} Formatting
  * @typedef {import('../../../types/Format').OutputReferences} OutputReferences
- * @typedef {import('../../../types/DesignToken.d.ts').Dictionary} Dictionary
+ * @typedef {import('../../../types/DesignToken.ts').Dictionary} Dictionary
  */
 
 const defaultFormatting = {

diff --git a/lib/common/formatHelpers/getTypeScriptType.js b/lib/common/formatHelpers/getTypeScriptType.js
@@ -12,8 +12,8 @@
  */
 
 /**
- * @typedef {import('../../../types/Config.d.ts').LocalOptions} Options
- * @typedef {import('../../../types/Config.d.ts').Config} Config
+ * @typedef {import('../../../types/Config.ts').LocalOptions} Options
+ * @typedef {import('../../../types/Config.ts').Config} Config
  */
 
 /**

diff --git a/lib/common/formatHelpers/iconsWithPrefix.js b/lib/common/formatHelpers/iconsWithPrefix.js
@@ -12,9 +12,9 @@
  */
 
 /**
- * @typedef {import('../../../types/DesignToken.d.ts').TransformedToken} Token
- * @typedef {import('../../../types/Config.d.ts').Config} Options
- * @typedef {import('../../../types/Config.d.ts').PlatformConfig} PlatformConfig
+ * @typedef {import('../../../types/DesignToken.ts').TransformedToken} Token
+ * @typedef {import('../../../types/Config.ts').Config} Options
+ * @typedef {import('../../../types/Config.ts').PlatformConfig} PlatformConfig
  */
 
 /**

diff --git a/lib/common/formatHelpers/minifyDictionary.js b/lib/common/formatHelpers/minifyDictionary.js
@@ -12,7 +12,7 @@
  */
 
 /**
- * @typedef {import('../../../types/DesignToken.d.ts').TransformedTokens} Tokens
+ * @typedef {import('../../../types/DesignToken.ts').TransformedTokens} Tokens
  */
 
 /**
-Original file line number
+Diff line change
@@ Expand Up / @@ -12,7 +12,7 @@ @@
      */
     /**
-     * @typedef {import('../../types/Filter.d.ts').Filter} Filter
+     * @typedef {import('../../types/Filter.ts').Filter} Filter
      */
     /**
@@ Expand Down @@