@primer/primitives 7.16.0 → 7.17.0-rc.132f02a7

package/src/platforms/index.ts

@@ -0,0 +1,10 @@
+export {css} from './css'
+export {deprecatedJson} from './deprecatedJson'
+export {docJson} from './docJson'
+export {fallbacks} from './fallbacks'
+export {figma} from './figma'
+export {javascript} from './javascript'
+export {json} from './json'
+export {styleLint} from './styleLint'
+export {typeDefinitions} from './typeDefinitions'
+export {typescript} from './typescript'

package/src/platforms/javascript.ts

@@ -0,0 +1,30 @@
+import type StyleDictionary from 'style-dictionary'
+import type {PlatformInitializer} from '../types/PlatformInitializer'
+import {isSource} from '../filters'
+
+export const javascript: PlatformInitializer = (outputFile, prefix, buildPath): StyleDictionary.Platform => ({
+  prefix,
+  buildPath,
+  transforms: [
+    'color/hex',
+    'color/hexMix',
+    'color/hexAlpha',
+    'dimension/rem',
+    'shadow/css',
+    'border/css',
+    'typography/css',
+    'fontFamily/css',
+    'fontWeight/number',
+  ],
+  options: {
+    showFileHeader: false,
+    basePxFontSize: 16,
+  },
+  files: [
+    {
+      format: 'javascript/commonJs',
+      destination: outputFile,
+      filter: isSource,
+    },
+  ],
+})

package/src/platforms/json.ts

@@ -0,0 +1,32 @@
+import type StyleDictionary from 'style-dictionary'
+import type {PlatformInitializer} from '../types/PlatformInitializer'
+import {isSource} from '../filters'
+
+export const json: PlatformInitializer = (outputFile, prefix, buildPath): StyleDictionary.Platform => ({
+  prefix,
+  buildPath,
+  transforms: [
+    'color/hex',
+    'color/hexMix',
+    'color/hexAlpha',
+    'dimension/rem',
+    'shadow/css',
+    'border/css',
+    'typography/css',
+    'fontFamily/css',
+    'fontWeight/number',
+  ],
+  options: {
+    basePxFontSize: 16,
+  },
+  files: [
+    {
+      destination: outputFile,
+      filter: isSource,
+      format: `json/nested-prefixed`,
+      options: {
+        outputReferences: false,
+      },
+    },
+  ],
+})

package/src/platforms/styleLint.ts

@@ -0,0 +1,34 @@
+import type StyleDictionary from 'style-dictionary'
+import type {PlatformInitializer} from '../types/PlatformInitializer'
+import {isSource} from '../filters'
+
+export const styleLint: PlatformInitializer = (outputFile, prefix, buildPath): StyleDictionary.Platform => ({
+  prefix,
+  buildPath,
+  transforms: [
+    'name/pathToKebabCase',
+    'color/hex',
+    'color/hexMix',
+    'color/hexAlpha',
+    'dimension/remPxArray',
+    'shadow/css',
+    'border/css',
+    'typography/css',
+    'fontFamily/css',
+    'fontWeight/number',
+  ],
+  options: {
+    basePxFontSize: 16,
+  },
+  files: [
+    {
+      destination: outputFile,
+      format: `json/one-dimensional`,
+      filter: isSource,
+      options: {
+        outputReferences: false,
+        outputVerbose: true,
+      },
+    },
+  ],
+})

package/src/platforms/typeDefinitions.ts

@@ -0,0 +1,30 @@
+import type StyleDictionary from 'style-dictionary'
+import type {PlatformInitializer} from '../types/PlatformInitializer'
+import {isSource} from '../filters'
+import {upperCaseFirstCharacter} from '../utilities'
+
+export const typeDefinitions: PlatformInitializer = (outputFile, prefix, buildPath): StyleDictionary.Platform => ({
+  prefix,
+  buildPath,
+  transforms: [
+    'color/hex',
+    'color/hexAlpha',
+    'shadow/css',
+    'border/css',
+    'dimension/rem',
+    'typography/css',
+    'fontFamily/css',
+    'fontWeight/number',
+  ],
+  files: [
+    {
+      format: 'typescript/export-definition',
+      destination: `${upperCaseFirstCharacter(outputFile)}DesignTokens.d.ts`,
+      filter: isSource,
+      options: {
+        tokenTypesPath: './src/types/',
+        moduleName: `${upperCaseFirstCharacter(outputFile)}DesignTokens`,
+      },
+    },
+  ],
+})

package/src/platforms/typescript.ts

@@ -0,0 +1,30 @@
+import type StyleDictionary from 'style-dictionary'
+import type {PlatformInitializer} from '../types/PlatformInitializer'
+import {isSource} from '../filters'
+
+export const typescript: PlatformInitializer = (outputFile, prefix, buildPath): StyleDictionary.Platform => ({
+  prefix,
+  buildPath,
+  transforms: [
+    'color/hex',
+    'color/hexMix',
+    'color/hexAlpha',
+    'dimension/rem',
+    'shadow/css',
+    'border/css',
+    'typography/css',
+    'fontFamily/css',
+    'fontWeight/number',
+  ],
+  options: {
+    showFileHeader: false,
+    basePxFontSize: 16,
+  },
+  files: [
+    {
+      format: 'javascript/esm',
+      destination: outputFile,
+      filter: isSource,
+    },
+  ],
+})

package/src/schemas/alphaValue.ts

@@ -0,0 +1,12 @@
+import {z} from 'zod'
+import {schemaErrorMessage} from '../utilities/schemaErrorMessage'
+
+export const alphaValue = z.any().refine(
+  value => typeof value === 'number' && value >= 0 && value <= 1,
+  value => ({
+    message: schemaErrorMessage(
+      `Invalid alpha value: "${value}" (${typeof value})`,
+      'Alpha value must be a number between 0 and 1.',
+    ),
+  }),
+)

package/src/schemas/baseToken.ts

@@ -0,0 +1,7 @@
+import {z} from 'zod'
+
+export const baseToken = z
+  .object({
+    $description: z.string().optional(),
+  })
+  .strict()

package/src/schemas/borderToken.ts

@@ -0,0 +1,19 @@
+import {z} from 'zod'
+import {baseToken} from './baseToken'
+import {referenceValue} from './referenceValue'
+import {colorHexValue} from './colorHexValue'
+import {dimensionValue} from './dimensionValue'
+import {tokenType} from './tokenType'
+
+export const borderValue = z.object({
+  color: z.union([colorHexValue, referenceValue]),
+  style: z.enum(['solid', 'dashed', 'dotted', 'double', 'groove', 'ridge', 'outset', 'inset']),
+  width: z.union([dimensionValue, referenceValue]),
+})
+
+export const borderToken = baseToken
+  .extend({
+    $value: z.union([borderValue, referenceValue]),
+    $type: tokenType('border'),
+  })
+  .strict()

package/src/schemas/collections.ts

@@ -0,0 +1,49 @@
+import {z} from 'zod'
+import {joinFriendly} from '../utilities/joinFriendly'
+import {schemaErrorMessage} from '../utilities/schemaErrorMessage'
+
+type Collections =
+  | 'base/color/light'
+  | 'base/color/light-high-contrast'
+  | 'base/color/dark'
+  | 'base/color/dark-dimmed'
+  | 'base/color/dark-high-contrast'
+  | 'base/typography'
+  | 'mode'
+  | 'pattern/mode'
+  | 'base/size'
+  | 'functional/size'
+  | 'pattern/size'
+  | 'typography'
+
+export const collection = (collections: Collections[]) => {
+  return z.string().refine(
+    value => collections.includes(value as Collections),
+    value => ({
+      message: schemaErrorMessage(
+        `Invalid collection: "${value}"`,
+        `Valid collections are ${joinFriendly(collections)}`,
+      ),
+    }),
+  )
+}
+
+type Modes =
+  | 'light'
+  | 'dark'
+  | 'dark dimmed'
+  | 'light high contrast'
+  | 'dark high contrast'
+  | 'light colorblind'
+  | 'dark colorblind'
+  | 'light tritanopia'
+  | 'dark tritanopia'
+
+export const mode = (modes: Modes[]) => {
+  return z.string().refine(
+    value => modes.includes(value as Modes),
+    value => ({
+      message: schemaErrorMessage(`Invalid mode: "${value}"`, `Valid modes are ${joinFriendly(modes)}`),
+    }),
+  )
+}

package/src/schemas/colorHexValue.ts

@@ -0,0 +1,18 @@
+import {z} from 'zod'
+import {schemaErrorMessage} from '../utilities/schemaErrorMessage'
+
+const colorHex3RegEx = '^#[0-9a-f]{3}$'
+const colorHex6RegEx = '^#[0-9a-f]{6}$'
+const colorHex8RegEx = '^#[0-9a-f]{8}$'
+
+const colorHexRegex = new RegExp(`(${colorHex3RegEx})|(${colorHex6RegEx})|(${colorHex8RegEx})`, 'i')
+
+export const colorHexValue = z.string().refine(
+  color => colorHexRegex.test(color),
+  color => ({
+    message: schemaErrorMessage(
+      `Invalid color: "${color}"`,
+      'Color must be a hex string or a reference to a color token.',
+    ),
+  }),
+)

package/src/schemas/colorToken.ts

@@ -0,0 +1,50 @@
+import {z} from 'zod'
+import {colorHexValue} from './colorHexValue'
+import {referenceValue} from './referenceValue'
+import {alphaValue} from './alphaValue'
+import {baseToken} from './baseToken'
+import {collection, mode} from './collections'
+import {scopes} from './scopes'
+import {tokenType} from './tokenType'
+
+export const colorToken = baseToken
+  .extend({
+    $value: z.union([colorHexValue, referenceValue]),
+    $type: tokenType('color'),
+    alpha: alphaValue.optional().nullable(),
+    mix: z
+      .object({
+        color: z.string(),
+        weight: z.number().min(0).max(1),
+      })
+      .nullable()
+      .optional(),
+    $extensions: z
+      .object({
+        'org.primer.figma': z.object({
+          collection: collection([
+            'base/color/light',
+            'base/color/light-high-contrast',
+            'base/color/dark',
+            'base/color/dark-dimmed',
+            'base/color/dark-high-contrast',
+            'mode',
+            'pattern/mode',
+          ]).optional(),
+          mode: mode([
+            'light',
+            'dark',
+            'dark dimmed',
+            'light high contrast',
+            'dark high contrast',
+            'light colorblind',
+            'dark colorblind',
+            'light tritanopia',
+            'dark tritanopia',
+          ]).optional(),
+          scopes: scopes(['all', 'bgColor', 'fgColor', 'borderColor']).optional(),
+        }),
+      })
+      .optional(),
+  })
+  .strict()

package/src/schemas/designToken.ts

@@ -0,0 +1,38 @@
+import {z} from 'zod'
+import {tokenName} from './tokenName'
+import {stringToken} from './stringToken'
+import {viewportRangeToken} from './viewportRangeToken'
+import {numberToken} from './numberToken'
+import {fontWeightToken} from './fontWeightToken'
+import {typographyToken} from './typographyToken'
+import {borderToken} from './borderToken'
+import {dimensionToken} from './dimensionToken'
+import {colorToken} from './colorToken'
+import {fontFamilyToken} from './fontFamilyToken'
+import {shadowToken} from './shadowToken'
+import {durationToken} from './durationToken'
+
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore: TODO: fix this
+export const designToken = z.record(
+  tokenName,
+  z.lazy(() => {
+    return z.union([
+      z.discriminatedUnion('$type', [
+        colorToken,
+        dimensionToken,
+        shadowToken,
+        borderToken,
+        fontFamilyToken,
+        fontWeightToken,
+        typographyToken,
+        viewportRangeToken,
+        numberToken,
+        durationToken,
+        stringToken,
+      ]),
+      // referenceToken,
+      designToken,
+    ])
+  }),
+)

package/src/schemas/dimensionToken.ts

@@ -0,0 +1,22 @@
+import {z} from 'zod'
+import {baseToken} from './baseToken'
+import {referenceValue} from './referenceValue'
+import {collection} from './collections'
+import {scopes} from './scopes'
+import {dimensionValue} from './dimensionValue'
+import {tokenType} from './tokenType'
+
+export const dimensionToken = baseToken
+  .extend({
+    $value: z.union([dimensionValue, referenceValue]),
+    $type: tokenType('dimension'),
+    $extensions: z
+      .object({
+        'org.primer.figma': z.object({
+          collection: collection(['base/size', 'functional/size', 'pattern/size', 'typography']),
+          scopes: scopes(['all', 'size', 'gap', 'radius', 'borderColor']),
+        }),
+      })
+      .optional(),
+  })
+  .strict()

package/src/schemas/dimensionValue.ts

@@ -0,0 +1,16 @@
+import {z} from 'zod'
+import {schemaErrorMessage} from '../utilities/schemaErrorMessage'
+
+export const dimensionValue = z.union([
+  z.string().refine(
+    dim => /(^-?[0-9]+(px|rem)$|^-?[0-9]+\.?[0-9]*em$)/.test(dim),
+    val => ({
+      message: schemaErrorMessage(
+        `Invalid dimension: "${val}"`,
+        `Dimension must be a string with a unit (px, rem or em) or 0`,
+      ),
+    }),
+  ),
+  z.literal('0'),
+  z.literal(0),
+])

package/src/schemas/durationToken.ts

@@ -0,0 +1,12 @@
+import {z} from 'zod'
+import {baseToken} from './baseToken'
+import {referenceValue} from './referenceValue'
+import {durationValue} from './durationValue'
+import {tokenType} from './tokenType'
+
+export const durationToken = baseToken
+  .extend({
+    $value: z.union([durationValue, referenceValue]),
+    $type: tokenType('duration'),
+  })
+  .strict()

package/src/schemas/durationValue.ts

@@ -0,0 +1,9 @@
+import {z} from 'zod'
+import {schemaErrorMessage} from '../utilities/schemaErrorMessage'
+
+export const durationValue = z.string().refine(
+  duration => /(^[0-9]+ms$)/.test(duration),
+  val => ({
+    message: schemaErrorMessage(`Invalid duration: "${val}"`, `A duration must be a string with an "ms"`),
+  }),
+)

package/src/schemas/fontFamilyToken.ts

@@ -0,0 +1,21 @@
+import {z} from 'zod'
+import {referenceValue} from './referenceValue'
+import {baseToken} from './baseToken'
+import {tokenType} from './tokenType'
+import {collection} from './collections'
+import {scopes} from './scopes'
+
+export const fontFamilyToken = baseToken
+  .extend({
+    $value: z.union([z.string(), referenceValue]),
+    $type: tokenType('fontFamily'),
+    $extensions: z
+      .object({
+        'org.primer.figma': z.object({
+          collection: collection(['base/typography', 'typography']).optional(),
+          scopes: scopes(['all']).optional(),
+        }),
+      })
+      .optional(),
+  })
+  .strict()

package/src/schemas/fontWeightToken.ts

@@ -0,0 +1,22 @@
+import {z} from 'zod'
+import {fontWeightValue} from './fontWeightValue'
+import {referenceValue} from './referenceValue'
+import {baseToken} from './baseToken'
+import {tokenType} from './tokenType'
+import {collection} from './collections'
+import {scopes} from './scopes'
+
+export const fontWeightToken = baseToken
+  .extend({
+    $type: tokenType('fontWeight'),
+    $value: z.union([fontWeightValue, referenceValue]),
+    $extensions: z
+      .object({
+        'org.primer.figma': z.object({
+          collection: collection(['base/typography', 'typography']).optional(),
+          scopes: scopes(['all']).optional(),
+        }),
+      })
+      .optional(),
+  })
+  .strict()

package/src/schemas/fontWeightValue.ts

@@ -0,0 +1,14 @@
+import {z} from 'zod'
+import {schemaErrorMessage} from '../utilities/schemaErrorMessage'
+
+const allowed = [100, 200, 300, 400, 500, 600, 700, 800, 900, 950]
+
+export const fontWeightValue = z.number().refine(
+  value => allowed.includes(value),
+  value => ({
+    message: schemaErrorMessage(
+      `Invalid font weight value: "${value}"`,
+      `Font weight must be one of ${allowed.join(', ')}`,
+    ),
+  }),
+)

package/src/schemas/numberToken.ts

@@ -0,0 +1,11 @@
+import {z} from 'zod'
+import {baseToken} from './baseToken'
+import {referenceValue} from './referenceValue'
+import {tokenType} from './tokenType'
+
+export const numberToken = baseToken
+  .extend({
+    $value: z.union([z.number(), referenceValue]),
+    $type: tokenType('number'),
+  })
+  .strict()

package/src/schemas/referenceValue.ts

@@ -0,0 +1,12 @@
+import {z} from 'zod'
+import {schemaErrorMessage} from '../utilities/schemaErrorMessage'
+
+export const referenceValue = z.string().refine(
+  ref => /^{\w+(\.\w+)*(\.\w+|\.@)}$/.test(ref),
+  ref => ({
+    message: schemaErrorMessage(
+      `Invalid reference: "${ref}"`,
+      'Reference must be a string in the format "{path.to.token}".',
+    ),
+  }),
+)

package/src/schemas/scopes.ts

@@ -0,0 +1,16 @@
+import {z} from 'zod'
+import {joinFriendly} from '../utilities/joinFriendly'
+import {schemaErrorMessage} from '../utilities/schemaErrorMessage'
+
+export type ValidScope = 'all' | 'bgColor' | 'fgColor' | 'borderColor' | 'size' | 'gap' | 'radius' | 'effectColor'
+const validScopes: ValidScope[] = ['all', 'bgColor', 'fgColor', 'borderColor', 'size', 'gap', 'radius', 'effectColor']
+
+export const scopes = (scopeSubset?: ValidScope[]) => {
+  const scopeArray = scopeSubset ?? validScopes
+  return z.array(z.string()).refine(
+    value => value.every(item => scopeArray.includes(item as ValidScope)),
+    value => ({
+      message: schemaErrorMessage(`Invalid scope: "${value}"`, `Valid scopes are: ${joinFriendly(scopeArray)}`),
+    }),
+  )
+}

package/src/schemas/shadowToken.ts

@@ -0,0 +1,45 @@
+import {z} from 'zod'
+import {baseToken} from './baseToken'
+import {referenceValue} from './referenceValue'
+import {colorHexValue} from './colorHexValue'
+import {alphaValue} from './alphaValue'
+import {dimensionValue} from './dimensionValue'
+import {tokenType} from './tokenType'
+import {collection, mode} from './collections'
+
+export const shadowValue = z
+  .object({
+    color: z.union([colorHexValue, referenceValue]),
+    alpha: z.union([alphaValue, referenceValue]),
+    offsetX: z.union([dimensionValue, referenceValue]),
+    offsetY: z.union([dimensionValue, referenceValue]),
+    blur: z.union([dimensionValue, referenceValue]),
+    spread: z.union([dimensionValue, referenceValue]),
+    inset: z.boolean().optional(),
+  })
+  .strict()
+
+export const shadowToken = baseToken
+  .extend({
+    $value: z.union([shadowValue, z.array(shadowValue), referenceValue]),
+    $type: tokenType('shadow'),
+    $extensions: z
+      .object({
+        'org.primer.figma': z.object({
+          collection: collection(['mode']).optional(),
+          mode: mode([
+            'light',
+            'dark',
+            'dark dimmed',
+            'light high contrast',
+            'dark high contrast',
+            'light colorblind',
+            'dark colorblind',
+            'light tritanopia',
+            'dark tritanopia',
+          ]).optional(),
+        }),
+      })
+      .optional(),
+  })
+  .strict()

package/src/schemas/stringToken.ts

@@ -0,0 +1,11 @@
+import {z} from 'zod'
+import {baseToken} from './baseToken'
+import {referenceValue} from './referenceValue'
+import {tokenType} from './tokenType'
+
+export const stringToken = baseToken
+  .extend({
+    $value: z.union([z.string(), referenceValue]),
+    $type: tokenType('string'),
+  })
+  .strict()

package/src/schemas/tokenName.ts

@@ -0,0 +1,12 @@
+import {z} from 'zod'
+import {schemaErrorMessage} from '../utilities/schemaErrorMessage'
+
+export const tokenName = z.string().refine(
+  name => /(^[a-z0-9][A-Za-z0-9-]*$|^@$)/.test(name),
+  name => ({
+    message: schemaErrorMessage(
+      `Invalid token name: "${name}"`,
+      'Token name must be kebab-case or camelCase, and start with a lowercase letter or number and consist only of letters, numbers, and hyphens.',
+    ),
+  }),
+)

package/src/schemas/tokenType.ts

@@ -0,0 +1,4 @@
+import {z} from 'zod'
+import type {TokenType} from './validTokenType'
+
+export const tokenType = ($type: TokenType) => z.literal($type)

package/src/schemas/typographyToken.ts

@@ -0,0 +1,20 @@
+import {z} from 'zod'
+import {referenceValue} from './referenceValue'
+import {dimensionValue} from './dimensionValue'
+import {baseToken} from './baseToken'
+import {fontWeightValue} from './fontWeightValue'
+import {tokenType} from './tokenType'
+
+export const typographyValue = z.object({
+  fontSize: z.union([dimensionValue, referenceValue]),
+  lineHeight: z.union([dimensionValue, referenceValue]).optional(),
+  fontWeight: z.union([fontWeightValue, referenceValue]),
+  fontFamily: z.union([z.string().min(1), referenceValue]),
+})
+
+export const typographyToken = baseToken
+  .extend({
+    $value: z.union([typographyValue, referenceValue]),
+    $type: tokenType('typography'),
+  })
+  .strict()