add transition transformer

Author: lukasoppermann

src/filters/index.ts

@@ -12,3 +12,4 @@ export {isNumber} from './isNumber.js'
 export {isShadow} from './isShadow.js'
 export {isSource} from './isSource.js'
 export {isTypography} from './isTypography.js'
+export {isTransition} from './isTransition.js'

src/filters/isTransition.test.ts

@@ -0,0 +1,22 @@
+import {getMockToken} from '../test-utilities/index.js'
+import {isTransition} from './isTransition.js'
+
+describe('Filter: isTransition', () => {
+  it('returns true if $type property is `transition`', () => {
+    expect(isTransition(getMockToken({$type: 'transition'}))).toStrictEqual(true)
+  })
+
+  it('returns false if $type property is not `transition`', () => {
+    expect(isTransition(getMockToken({$type: 'pumpkin'}))).toStrictEqual(false)
+  })
+
+  it('returns false if $type property is missing', () => {
+    expect(isTransition(getMockToken({alpha: 0.4}))).toStrictEqual(false)
+  })
+
+  it('returns false if $type property is falsy', () => {
+    expect(isTransition(getMockToken({$type: false}))).toStrictEqual(false)
+    expect(isTransition(getMockToken({$type: undefined}))).toStrictEqual(false)
+    expect(isTransition(getMockToken({$type: null}))).toStrictEqual(false)
+  })
+})

src/filters/isTransition.ts

@@ -0,0 +1,10 @@
+import type {TransformedToken} from 'style-dictionary/types'
+
+/**
+ * @description Checks if token is of $type `transition`
+ * @param token [TransformedToken](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts)
+ * @returns boolean
+ */
+export const isTransition = (token: TransformedToken): boolean => {
+  return token.$type === 'transition'
+}

src/platforms/css.ts

@@ -35,6 +35,7 @@ export const css: PlatformInitializer = (outputFile, prefix, buildPath, options)
       'shadow/css',
       'border/css',
       'typography/css',
+      'transition/css',
       'fontFamily/css',
       'fontWeight/number',
       'gradient/css',

src/primerStyleDictionary.ts

@@ -25,6 +25,7 @@ import {
   dimensionToRemPxArray,
   floatToPixel,
   floatToPixelUnitless,
+  transitionToCss,
 } from './transformers/index.js'
 import {
   javascriptCommonJs,
@@ -152,6 +153,8 @@ PrimerStyleDictionary.registerTransform(borderToCss)
 
 PrimerStyleDictionary.registerTransform(typographyToCss)
 
+PrimerStyleDictionary.registerTransform(transitionToCss)
+
 PrimerStyleDictionary.registerTransform(fontWeightToNumber)
 
 PrimerStyleDictionary.registerTransform(fontFamilyToCss)

src/test-utilities/getMockToken.ts

@@ -36,9 +36,9 @@ export const getMockToken = (
     [key: keyof TransformedToken]: unknown
   },
   options?: getMockTokenOptions,
-) => {
+): TransformedToken => {
   return {
     ...removeProps(mockTokenDefaults, options?.remove),
     ...valueOverrides,
-  }
+  } as TransformedToken
 }

src/transformers/index.ts

@@ -23,3 +23,4 @@ export {namePathToKebabCase} from './namePathToKebabCase.js'
 export {namePathToSlashNotation} from './namePathToSlashNotation.js'
 export {shadowToCss} from './shadowToCss.js'
 export {typographyToCss} from './typographyToCss.js'
+export {transitionToCss} from './transitionToCss.js'

src/transformers/transitionToCss.test.ts

@@ -0,0 +1,135 @@
+import {getMockToken} from '../test-utilities/getMockToken.js'
+import {transitionToCss} from './transitionToCss.js'
+
+describe('transitionToCss', () => {
+  it('should transform basic transition token to CSS', () => {
+    const token = getMockToken({
+      $value: {
+        duration: '300ms',
+        timing: [0.4, 0, 0.2, 1],
+      },
+      $type: 'transition',
+    })
+
+    expect(transitionToCss.transform(token, {}, {})).toBe('300ms cubic-bezier(0.4, 0, 0.2, 1)')
+  })
+
+  it('should transform transition token with delay to CSS', () => {
+    const token = getMockToken({
+      $value: {
+        duration: '300ms',
+        timing: [0.4, 0, 0.2, 1],
+        delay: '100ms',
+      },
+      $type: 'transition',
+    })
+
+    expect(transitionToCss.transform(token, {}, {})).toBe('300ms cubic-bezier(0.4, 0, 0.2, 1) 100ms')
+  })
+
+  it('should transform transition token with resolved references', () => {
+    const token = {
+      $value: {
+        duration: '300ms',
+        timing: [0.4, 0, 0.2, 1],
+        delay: '0ms',
+      },
+      $type: 'transition',
+    }
+    const resolvedRefs = {
+      duration: '300ms',
+      timing: [0.4, 0, 0.2, 1],
+      delay: '0ms',
+    }
+
+    expect(transitionToCss.transform(token, resolvedRefs)).toBe('300ms cubic-bezier(0.4, 0, 0.2, 1) 0ms')
+  })
+
+  it('should transform transition token with mixed values and references', () => {
+    const token = getMockToken({
+      $value: {
+        duration: '{motion.duration.base.value}',
+        timing: [0.4, 0, 0.2, 1],
+        delay: '0ms',
+      },
+      $type: 'transition',
+    })
+
+    expect(transitionToCss.transform(token, resolvedRefs)).toBe('300ms cubic-bezier(0.4, 0, 0.2, 1) 0ms')
+  })
+
+  it('should handle common timing function aliases', () => {
+    const token = {
+      $value: {
+        duration: '300ms',
+        timing: [0.4, 0, 1, 1],
+      },
+      $type: 'transition',
+    }
+
+    expect(transitionToCss.transform(token, {}, {})).toBe('300ms ease-out')
+  })
+
+  it('should handle direct reference token', () => {
+    const token = {
+      $value: '{motion.transition.standard}',
+      $type: 'transition',
+    }
+    const resolvedRefs = {
+      'motion.transition.standard': {
+        duration: '300ms',
+        timing: [0.4, 0, 0.2, 1],
+        delay: '0ms',
+      },
+    }
+
+    expect(transitionToCss.transform(token, resolvedRefs)).toBe('300ms cubic-bezier(0.4, 0, 0.2, 1) 0ms')
+  })
+
+  it('should handle missing optional delay', () => {
+    const token = {
+      $value: {
+        duration: '300ms',
+        timing: [0.4, 0, 0.2, 1],
+      },
+      $type: 'transition',
+    }
+
+    expect(transitionToCss.transform(token, {}, {})).toBe('300ms cubic-bezier(0.4, 0, 0.2, 1)')
+  })
+
+  it('should throw error for invalid token type', () => {
+    const token = {
+      $value: {
+        duration: '300ms',
+        timing: [0.4, 0, 0.2, 1],
+      },
+      $type: 'invalid',
+    }
+
+    expect(() => transitionToCss.transform(token, {}, {})).toThrow('Invalid token type: invalid')
+  })
+
+  it('should throw error for missing required properties', () => {
+    const token = {
+      $value: {
+        duration: '300ms',
+      },
+      $type: 'transition',
+    }
+    // @ts-expect-error: testing invalid token
+    expect(() => transitionToCss.transform(token, {}, {})).toThrow('Missing required property: timing')
+  })
+
+  it('should throw error for invalid timing value', () => {
+    const token = {
+      $value: {
+        duration: '300ms',
+        timing: [0.4, 0, 0.2], // Missing one value
+      },
+      $type: 'transition',
+    }
+
+    expect(() => transitionToCss.transform(token, {}, {})).toThrow('Invalid timing value')
+  })
+})

src/transformers/transitionToCss.ts

@@ -0,0 +1,31 @@
+import {isTransition} from '../filters/index.js'
+import {checkRequiredTokenProperties} from './utilities/checkRequiredTokenProperties.js'
+import {getTokenValue} from './utilities/getTokenValue.js'
+import type {Transform, TransformedToken} from 'style-dictionary/types'
+
+/**
+ * @description converts transition tokens to CSS transition string
+ * @type value transformer — [StyleDictionary.ValueTransform](https://github.com/amzn/style-dictionary/blob/main/types/Transform.d.ts)
+ * @matcher matches all tokens of $type `transition`
+ * @transformer returns css transition `string`
+ */
+export const transitionToCss: Transform = {
+  name: 'transition/css',
+  type: 'value',
+  transitive: true,
+  filter: isTransition,
+  transform: (token: TransformedToken) => {
+    // extract value
+    const value = getTokenValue(token)
+
+    // if value is a string, it's probably a reference, return as is
+    if (typeof value === 'string') {
+      return value
+    }
+
+    // check required properties
+    checkRequiredTokenProperties(value, ['duration', 'timingFunction'])
+
+    return `${value.duration} ${value.timingFunction} ${value.delay ? value.delay : ''}`.trim()
+  },
+}