feat: store original TS type on and align more TS types to dimension

.changeset/cyan-pots-punch.md

@@ -0,0 +1,5 @@
+---
+'@tokens-studio/sd-transforms': patch
+---
+
+Fix alignTypes to also include `borderWidth`, `letterSpacing`, `paragraphSpacing` and `paragraphIndent` and align them to `dimension`.

.changeset/eleven-crabs-think.md

@@ -0,0 +1,5 @@
+---
+'@tokens-studio/sd-transforms': minor
+---
+
+Add the `originalType` property to `$extensions.['studio.tokens']` to store the original Tokens Studio token type, when the type is aligned to DTCG types. LetterSpacing transform is the transform in this package that actually needs to use this, because it doesn't want to match all dimension tokens, but it does want to match letterSpacing tokens.

README.md

@@ -8,7 +8,9 @@
 
 - [Installation](#installation)
 - [Compatibility](#compatibility)
-- [Getting Started](#usage)
+- [Usage](#usage)
+  - [Using the preprocessor](#using-the-preprocessor)
+  - [Using expand](#using-expand)
   - [Using the transforms](#using-the-transforms)
   - [Custom Transform Group](#custom-transform-group)
   - [Options](#options)
@@ -125,6 +127,11 @@ You must add the `'tokens-studio'` preprocessor explicitly in the configuration:
 
 This allows `fontStyles` to be extracted when they are embedded in `fontWeights`, aligns Tokens Studio token types with DTCG token types, and allows excluding parent keys for single-file Tokens Studio exports.
 
+> [!TIP]
+> The align types part of the preprocessor aligns Tokens Studio token types to DTCG token types.
+> The original Tokens Studio type in this scenario will be stored at `$extensions['studio.tokens'].originalType` if this happens.
+> This allows you to use the original type e.g. for token filtering/matching for your custom transforms.
+
 ### Using "Expand"
 
 > Expand used to be an sd-transforms exclusive feature but has moved to Style Dictionary itself under a slightly different API.
@@ -541,7 +548,7 @@ You can adjust to how many decimals the result should be rounded using `Platform
 
 This transform adds `px` as a unit when dimension-like tokens do not have a unit.
 
-**matches**: `token.type` is one of `['sizing', 'spacing', 'borderRadius', 'borderWidth', 'fontSizes', 'dimension']`
+**matches**: `token.type` is one of `['fontSize', 'dimension', 'border', 'typography', 'shadow']`
 
 #### before
 
@@ -597,7 +604,7 @@ This transforms opacity token values declared with `%` into a number between `0`
 
 This transforms line-height token values declared with `%` into a unitless value.
 
-**matches**: `token.type` is `'lineHeights'`
+**matches**: `token.type` is `'lineHeight'` or `token.type` is `'typography'`
 
 #### before
 
@@ -625,7 +632,7 @@ This transforms line-height token values declared with `%` into a unitless value
 
 This transforms fontweight from keynames to fontweight numbers.
 
-**matches**: `token.type` is `'fontWeights'`
+**matches**: `token.type` is `'fontWeight'` or `token.type` is `'typography'`
 
 #### before
 
@@ -715,7 +722,7 @@ This transforms color modifiers from Tokens Studio to color values.
 
 This transforms letter-spacing token values declared with `%` to a value with `em`.
 
-**matches**: `token.type` is `'letterSpacing'`
+**matches**: `token.$extensions['studio.tokens'].originalType` is `'letterSpacing'` or `token.type` is `'typography'`
 
 #### before
 

package.json

@@ -35,7 +35,7 @@
   "dependencies": {
     "@bundled-es-modules/deepmerge": "^4.3.1",
     "@bundled-es-modules/postcss-calc-ast-parser": "^0.1.6",
-    "@tokens-studio/types": "^0.4.0",
+    "@tokens-studio/types": "^0.5.1",
     "colorjs.io": "^0.4.3",
     "expr-eval-fork": "^2.0.2",
     "is-mergeable-object": "^1.1.1"

src/preprocessors/align-types.ts

@@ -14,6 +14,10 @@ const typesMap = {
   spacing: 'dimension',
   sizing: 'dimension',
   borderRadius: 'dimension',
+  borderWidth: 'dimension',
+  letterSpacing: 'dimension',
+  paragraphSpacing: 'dimension',
+  paragraphIndent: 'dimension',
   text: 'content',
 } as Partial<Record<valueOfTokenTypes, string>>;
 
@@ -31,11 +35,24 @@ function recurse(slice: DeepKeyTokenMap<false> | SingleToken<false>) {
   if (isToken) {
     const { $value, value, type, $type } = slice;
     const usesDTCG = Object.hasOwn(slice, '$value');
-    const t = (usesDTCG ? $type : type) as string;
+    const t = (usesDTCG ? $type : type) as valueOfTokenTypes;
     const v = usesDTCG ? $value : value;
     const tProp = `${usesDTCG ? '$' : ''}type` as '$type' | 'type';
     const newT = (typesMap[t as keyof typeof typesMap] ?? t) as valueOfTokenTypes;
-    (slice[tProp] as valueOfTokenTypes) = newT;
+    const k = 'studio.tokens' as keyof typeof slice.$extensions;
+
+    if (newT !== t) {
+      // replace the type with new type
+      (slice[tProp] as valueOfTokenTypes) = newT;
+      // store the original type as metadata
+      slice.$extensions = {
+        ...slice.$extensions,
+        [k]: {
+          ...(slice.$extensions?.[k] ?? {}),
+          originalType: t as TokenTypes,
+        },
+      };
+    }
 
     // now also check propsMap if we need to map some props
     if (typeof v === 'object') {

src/register.ts

@@ -104,7 +104,11 @@ export async function register(sd: typeof StyleDictionary, transformOpts?: Trans
     transitive: true,
     filter: token => {
       const type = token.$type ?? token.type;
-      return typeof type === 'string' && ['letterSpacing', 'typography'].includes(type);
+      const originalType = token.$extensions?.['studio.tokens']?.originalType;
+      return (
+        typeof type === 'string' &&
+        (['letterSpacing', 'typography'].includes(type) || originalType === 'letterSpacing')
+      );
     },
     transform: token => transformLetterSpacingForCSS(token),
   });

test/integration/sd-transforms.test.ts

@@ -62,7 +62,7 @@ describe('sd-transforms smoke tests', () => {
   --sdColorsGradient: linear-gradient(180deg, #000000 0%, rgba(0, 0, 0, 0.00) 45%);
   --sdLineHeightsHeading: 1.1;
   --sdLineHeightsBody: 1.4;
-  --sdLetterSpacingDefault: 0;
+  --sdLetterSpacingDefault: 0rem;
   --sdLetterSpacingIncreased: 1.5em;
   --sdLetterSpacingDecreased: -0.05em;
   --sdFontWeightsHeadingRegular: 600;
@@ -117,7 +117,7 @@ describe('sd-transforms smoke tests', () => {
   --sd-colors-gradient: linear-gradient(180deg, #000000 0%, rgba(0, 0, 0, 0.00) 45%);
   --sd-line-heights-heading: 1.1;
   --sd-line-heights-body: 1.4;
-  --sd-letter-spacing-default: 0;
+  --sd-letter-spacing-default: 0rem;
   --sd-letter-spacing-increased: 1.5em;
   --sd-letter-spacing-decreased: -0.05em;
   --sd-font-weights-heading-regular: 600;

test/spec/preprocessors/align-types.spec.ts

@@ -12,13 +12,22 @@ const tokenObj = {
       weight: {
         value: 400,
         type: 'fontWeights',
+        $extensions: {
+          'studio.tokens': {
+            modify: undefined,
+          },
+          'foo.bar': { some: 'metadata' },
+        },
       },
     },
     semantic: {
       sizings: {
         lg: {
           value: '30px',
           type: 'sizing',
+          $extensions: {
+            'foo.bar': { some: 'metadata' },
+          },
         },
       },
     },
@@ -63,13 +72,26 @@ const tokenObjAligned = {
       weight: {
         value: 400,
         type: 'fontWeight',
+        $extensions: {
+          'studio.tokens': {
+            modify: undefined,
+            originalType: 'fontWeights',
+          },
+          'foo.bar': { some: 'metadata' },
+        },
       },
     },
     semantic: {
       sizings: {
         lg: {
           value: '30px',
           type: 'dimension',
+          $extensions: {
+            'studio.tokens': {
+              originalType: 'sizing',
+            },
+            'foo.bar': { some: 'metadata' },
+          },
         },
       },
     },
@@ -88,6 +110,11 @@ const tokenObjAligned = {
           },
         ],
         type: 'shadow',
+        $extensions: {
+          'studio.tokens': {
+            originalType: 'boxShadow',
+          },
+        },
       },
       shadowSingle: {
         value: {
@@ -99,6 +126,11 @@ const tokenObjAligned = {
           type: 'innerShadow',
         },
         type: 'shadow',
+        $extensions: {
+          'studio.tokens': {
+            originalType: 'boxShadow',
+          },
+        },
       },
     },
   },
@@ -114,13 +146,22 @@ const tokenObjDTCG = {
       weight: {
         $value: 400,
         $type: 'fontWeights',
+        $extensions: {
+          'studio.tokens': {
+            modify: undefined,
+          },
+          'foo.bar': { some: 'metadata' },
+        },
       },
     },
     semantic: {
       sizings: {
         lg: {
           $value: '30px',
           $type: 'sizing',
+          $extensions: {
+            'foo.bar': { some: 'metadata' },
+          },
         },
       },
     },
@@ -165,13 +206,26 @@ const tokenObjAlignedDTCG = {
       weight: {
         $value: 400,
         $type: 'fontWeight',
+        $extensions: {
+          'studio.tokens': {
+            modify: undefined,
+            originalType: 'fontWeights',
+          },
+          'foo.bar': { some: 'metadata' },
+        },
       },
     },
     semantic: {
       sizings: {
         lg: {
           $value: '30px',
           $type: 'dimension',
+          $extensions: {
+            'studio.tokens': {
+              originalType: 'sizing',
+            },
+            'foo.bar': { some: 'metadata' },
+          },
         },
       },
     },
@@ -190,6 +244,11 @@ const tokenObjAlignedDTCG = {
           },
         ],
         $type: 'shadow',
+        $extensions: {
+          'studio.tokens': {
+            originalType: 'boxShadow',
+          },
+        },
       },
       shadowSingle: {
         $value: {
@@ -201,6 +260,11 @@ const tokenObjAlignedDTCG = {
           type: 'innerShadow',
         },
         $type: 'shadow',
+        $extensions: {
+          'studio.tokens': {
+            originalType: 'boxShadow',
+          },
+        },
       },
     },
   },

test/spec/register.spec.ts

@@ -328,7 +328,7 @@ describe('register', () => {
   --colorsGradient: linear-gradient(180deg, #000000 0%, rgba(0, 0, 0, 0.00) 45%);
   --lineHeightsHeading: 1.1;
   --lineHeightsBody: 1.4;
-  --letterSpacingDefault: 0;
+  --letterSpacingDefault: 0rem;
   --letterSpacingIncreased: 1.5em;
   --letterSpacingDecreased: -0.05em;
   --fontWeightsHeadingRegular: 600;