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

package/src/PrimerStyleDictionary.ts

@@ -0,0 +1,226 @@
+import StyleDictionary from 'style-dictionary'
+import {w3cJsonParser} from './parsers'
+import {
+  borderToCss,
+  colorToHexAlpha,
+  colorToRgbAlpha,
+  colorToHex,
+  colorToHexMix,
+  colorToRgbaFloat,
+  dimensionToRem,
+  dimensionToPixelUnitless,
+  durationToCss,
+  figmaAttributes,
+  fontFamilyToCss,
+  fontWeightToNumber,
+  jsonDeprecated,
+  namePathToDotNotation,
+  namePathToCamelCase,
+  namePathToKebabCase,
+  namePathToSlashNotation,
+  namePathToFigma,
+  shadowToCss,
+  typographyToCss,
+  dimensionToRemPxArray,
+} from './transformers'
+import {
+  javascriptCommonJs,
+  javascriptEsm,
+  typescriptExportDefinition,
+  jsonNestedPrefixed,
+  cssThemed,
+  cssCustomMedia,
+  jsonOneDimensional,
+  jsonPostCssFallback,
+  cssWrapMediaQuery,
+  cssVariables,
+  jsonFigma,
+} from './formats'
+
+/**
+ * Parsers
+ *
+ */
+StyleDictionary.registerParser(w3cJsonParser)
+
+/**
+ * Formats
+ *
+ */
+StyleDictionary.registerFormat({
+  name: 'css/themed',
+  formatter: cssThemed,
+})
+
+StyleDictionary.registerFormat({
+  name: 'css/customMedia',
+  formatter: cssCustomMedia,
+})
+
+StyleDictionary.registerFormat({
+  name: 'css/wrapMediaQuery',
+  formatter: cssWrapMediaQuery,
+})
+
+StyleDictionary.registerFormat({
+  name: 'css/variables',
+  formatter: cssVariables,
+})
+
+StyleDictionary.registerFormat({
+  name: 'javascript/esm',
+  formatter: javascriptEsm,
+})
+
+StyleDictionary.registerFormat({
+  name: 'javascript/commonJs',
+  formatter: javascriptCommonJs,
+})
+
+StyleDictionary.registerFormat({
+  name: 'typescript/export-definition',
+  formatter: typescriptExportDefinition,
+})
+
+StyleDictionary.registerFormat({
+  name: 'json/nested-prefixed',
+  formatter: jsonNestedPrefixed,
+})
+
+StyleDictionary.registerFormat({
+  name: 'json/one-dimensional',
+  formatter: jsonOneDimensional,
+})
+
+StyleDictionary.registerFormat({
+  name: 'json/postCss-fallback',
+  formatter: jsonPostCssFallback,
+})
+
+StyleDictionary.registerFormat({
+  name: 'json/figma',
+  formatter: jsonFigma,
+})
+
+/**
+ * Transformers
+ *
+ */
+StyleDictionary.registerTransform({
+  name: 'color/rgbAlpha',
+  ...colorToRgbAlpha,
+})
+
+StyleDictionary.registerTransform({
+  name: 'color/rgbaFloat',
+  ...colorToRgbaFloat,
+})
+
+StyleDictionary.registerTransform({
+  name: 'color/hexAlpha',
+  ...colorToHexAlpha,
+})
+
+StyleDictionary.registerTransform({
+  name: 'color/hexMix',
+  ...colorToHexMix,
+})
+
+StyleDictionary.registerTransform({
+  name: 'color/hex',
+  ...colorToHex,
+})
+
+StyleDictionary.registerTransform({
+  name: 'dimension/rem',
+  ...dimensionToRem,
+})
+
+StyleDictionary.registerTransform({
+  name: 'dimension/remPxArray',
+  ...dimensionToRemPxArray,
+})
+
+StyleDictionary.registerTransform({
+  name: 'dimension/pixelUnitless',
+  ...dimensionToPixelUnitless,
+})
+
+StyleDictionary.registerTransform({
+  name: 'duration/css',
+  ...durationToCss,
+})
+
+StyleDictionary.registerTransform({
+  name: 'figma/attributes',
+  ...figmaAttributes,
+})
+
+StyleDictionary.registerTransform({
+  name: 'json/deprecated',
+  ...jsonDeprecated,
+})
+
+StyleDictionary.registerTransform({
+  name: 'name/pathToCamelCase',
+  ...namePathToCamelCase,
+})
+
+StyleDictionary.registerTransform({
+  name: 'name/pathToDotNotation',
+  ...namePathToDotNotation,
+})
+
+StyleDictionary.registerTransform({
+  name: 'name/pathToFigma',
+  ...namePathToFigma,
+})
+
+StyleDictionary.registerTransform({
+  name: 'name/pathToCamelCase',
+  ...namePathToCamelCase,
+})
+
+StyleDictionary.registerTransform({
+  name: 'name/pathToKebabCase',
+  ...namePathToKebabCase,
+})
+
+StyleDictionary.registerTransform({
+  name: 'name/pathToSlashNotation',
+  ...namePathToSlashNotation,
+})
+
+StyleDictionary.registerTransform({
+  name: 'shadow/css',
+  ...shadowToCss,
+})
+
+StyleDictionary.registerTransform({
+  name: 'border/css',
+  ...borderToCss,
+})
+
+StyleDictionary.registerTransform({
+  name: 'typography/css',
+  ...typographyToCss,
+})
+
+StyleDictionary.registerTransform({
+  name: 'fontWeight/number',
+  ...fontWeightToNumber,
+})
+
+StyleDictionary.registerTransform({
+  name: 'fontFamily/css',
+  ...fontFamilyToCss,
+})
+
+/**
+ * @name {@link PrimerStyleDictionary}
+ * @description Returns style dictionary object with primer preset that includes parsers, formats and transformers
+ * @parsers [w3cJsonParser](https://github.com/primer/primitives/blob/main/config//parsers/w3c-json-parser.ts)
+ * @formats [javascript/esm](https://github.com/primer/primitives/blob/main/config/formats/javascript-esm.ts), [javascript/commonJs](https://github.com/primer/primitives/blob/main/config/formats/javascript-commonJs.ts), [typescript/export-definition](https://github.com/primer/primitives/blob/main/config/formats/typescript-export-defition.ts)
+ * @transformers [color/rgbAlpha](https://github.com/primer/primitives/blob/main/config/tranformers/color-to-rgb-alpha.ts), [color/hexAlpha](https://github.com/primer/primitives/blob/main/config/tranformers/color-to-hex-alpha.ts), [color/hex](https://github.com/primer/primitives/blob/main/config/tranformers/color-to-hex6.ts), [json/deprecated](https://github.com/primer/primitives/blob/main/config/tranformers/json-deprecated.ts), [name/pathToDotNotation](https://github.com/primer/primitives/blob/main/config/tranformers/name-path-to-dot-notation.ts)
+ */
+export const PrimerStyleDictionary: StyleDictionary.Core = StyleDictionary

package/src/filters/index.ts

@@ -0,0 +1,12 @@
+export {isBorder} from './isBorder'
+export {isColor} from './isColor'
+export {isColorWithAlpha} from './isColorWithAlpha'
+export {isColorWithMix} from './isColorWithMix'
+export {isDimension} from './isDimension'
+export {isDeprecated} from './isDeprecated'
+export {isFromFile} from './isFromFile'
+export {isFontFamily} from './isFontFamily'
+export {isFontWeight} from './isFontWeight'
+export {isShadow} from './isShadow'
+export {isSource} from './isSource'
+export {isTypography} from './isTypography'

package/src/filters/isBorder.ts

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

package/src/filters/isColor.ts

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

package/src/filters/isColorWithAlpha.ts

@@ -0,0 +1,11 @@
+import type StyleDictionary from 'style-dictionary'
+import {isColor} from './isColor'
+
+/**
+ * @description Checks if token is color with an alpha value
+ * @param arguments [StyleDictionary.TransformedToken](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts)
+ * @returns boolean
+ */
+export const isColorWithAlpha = (token: StyleDictionary.TransformedToken): boolean => {
+  return isColor(token) && token.alpha !== undefined && typeof token.alpha === 'number'
+}

package/src/filters/isColorWithMix.ts

@@ -0,0 +1,33 @@
+import type StyleDictionary from 'style-dictionary'
+import {isColor} from './isColor'
+
+const throwError = (token: StyleDictionary.TransformedToken) => {
+  throw new Error(
+    `Invalid mix property on token: ${token.name}. "mix.color": ${token.mix.color}, "mix.weight": ${
+      typeof token.mix.weight === 'string' ? `"${token.mix.weight}" (string)` : token.mix.weight
+    } must be a number between 0 and 1. In file: "${token.filePath}".`,
+  )
+}
+
+/**
+ * @description Checks if token is color and has a mix property
+ * @param arguments [StyleDictionary.TransformedToken](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts)
+ * @returns boolean
+ */
+export const isColorWithMix = (token: StyleDictionary.TransformedToken): boolean => {
+  // no color or no mix property
+  if (!isColor(token) || token.mix === undefined || token.mix === null) {
+    return false
+  }
+  // invalid mix property
+  if (
+    typeof token.mix.color !== 'string' ||
+    typeof token.mix.weight !== 'number' ||
+    token.mix.weight < 0 ||
+    token.mix.weight > 1
+  ) {
+    throwError(token)
+  }
+  // valid mix property
+  return true
+}

package/src/filters/isDeprecated.ts

@@ -0,0 +1,10 @@
+import type StyleDictionary from 'style-dictionary'
+
+/**
+ * @description Checks if token has a valid `deprecated` property
+ * @param arguments [StyleDictionary.TransformedToken](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts)
+ * @returns boolean
+ */
+export const isDeprecated = (token: StyleDictionary.TransformedToken): boolean => {
+  return token.deprecated === true || typeof token.deprecated === 'string'
+}

package/src/filters/isDimension.ts

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

package/src/filters/isDuration.ts

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

package/src/filters/isFontFamily.ts

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

package/src/filters/isFontWeight.ts

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

package/src/filters/isFromFile.ts

@@ -0,0 +1,12 @@
+import type StyleDictionary from 'style-dictionary'
+
+/**
+ * @description Checks if token comes from a specific file
+ * @param token [StyleDictionary.TransformedToken](https://github.com/amzn/style-dictionary/blob/main/types/TransformedToken.d.ts)
+ * @param files - array of file paths
+ * @returns boolean
+ */
+export const isFromFile = (token: StyleDictionary.TransformedToken, files: string[]): boolean => {
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+  return files?.includes(token.filePath) === true
+}

package/src/filters/isShadow.ts

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

package/src/filters/isSource.ts

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

package/src/filters/isTypography.ts

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

package/src/formats/cssCustomMedia.ts

@@ -0,0 +1,24 @@
+import StyleDictionary from 'style-dictionary'
+import type {FormatterArguments} from 'style-dictionary/types/Format'
+import {format} from 'prettier'
+const {fileHeader} = StyleDictionary.formatHelpers
+
+/**
+ * @description Converts `StyleDictionary.dictionary.tokens` to css with @custom-media
+ * @param arguments [FormatterArguments](https://github.com/amzn/style-dictionary/blob/main/types/Format.d.ts)
+ * @returns formatted `string`
+ */
+export const cssCustomMedia: StyleDictionary.Formatter = ({
+  dictionary,
+  options: _options,
+  file,
+}: FormatterArguments) => {
+  // add file header
+  const output = [fileHeader({file})]
+  // add single theme css
+  dictionary.allTokens.map(({name, value}) => {
+    output.push(`@custom-media --${name} ${value};`)
+  })
+  // return prettified
+  return format(output.join('\n'), {parser: 'css', printWidth: 500})
+}

package/src/formats/cssThemed.ts

@@ -0,0 +1,35 @@
+import StyleDictionary from 'style-dictionary'
+import type {FormatterArguments} from 'style-dictionary/types/Format'
+import {format} from 'prettier'
+import type {LineFormatting} from 'style-dictionary/types/FormatHelpers'
+const {fileHeader, formattedVariables} = StyleDictionary.formatHelpers
+
+/**
+ * @description Converts `StyleDictionary.dictionary.tokens` to css with prefers dark and light section
+ * @param arguments [FormatterArguments](https://github.com/amzn/style-dictionary/blob/main/types/Format.d.ts)
+ * @param arguments.options outputReferences `boolean`, selector `string`, selectorLight `string`, selectorDark `string`
+ * @returns formatted `string`
+ */
+export const cssThemed: StyleDictionary.Formatter = ({dictionary, options = {}, file}: FormatterArguments) => {
+  const {selector, selectorLight, selectorDark} = options
+  const {outputReferences, descriptions} = options
+  const formatting: LineFormatting = {
+    commentStyle: descriptions ? 'long' : 'none',
+  }
+  // add file header
+  const output = [fileHeader({file})]
+  // add single theme css
+  output.push(`${selector || ':root'}${selectorLight ? `, ${selectorLight}` : ''}{
+    ${formattedVariables({format: 'css', dictionary, outputReferences, formatting})}
+  }`)
+  // add auto dark theme css
+  if (selectorDark) {
+    output.push(`@media (prefers-color-scheme: dark) {
+      ${selectorDark} {
+        ${formattedVariables({format: 'css', dictionary, outputReferences, formatting})}
+      }
+    }`)
+  }
+  // return prettified
+  return format(output.join('\n'), {parser: 'css', printWidth: 500})
+}

package/src/formats/cssVariables.ts

@@ -0,0 +1,25 @@
+import StyleDictionary from 'style-dictionary'
+import type {FormatterArguments} from 'style-dictionary/types/Format'
+import type {LineFormatting} from 'style-dictionary/types/FormatHelpers'
+const {fileHeader, formattedVariables} = StyleDictionary.formatHelpers
+
+/**
+ * @description Converts `StyleDictionary.dictionary.tokens` to css with prefers dark and light section
+ * @param arguments [FormatterArguments](https://github.com/amzn/style-dictionary/blob/main/types/Format.d.ts)
+ * @param arguments.options outputReferences `boolean`, selector `string`, selectorLight `string`, selectorDark `string`
+ * @returns formatted `string`
+ */
+export const cssVariables: StyleDictionary.Formatter = ({dictionary, options = {}, file}: FormatterArguments) => {
+  const selector = options.selector ? options.selector : `:root`
+  const {outputReferences, descriptions} = options
+  const formatting: LineFormatting = {
+    commentStyle: descriptions ? 'long' : 'none',
+  }
+
+  return `${fileHeader({file})}${selector} {\n${formattedVariables({
+    format: 'css',
+    dictionary,
+    outputReferences,
+    formatting,
+  })}\n}\n`
+}

package/src/formats/cssWrapMediaQuery.ts

@@ -0,0 +1,29 @@
+import StyleDictionary from 'style-dictionary'
+import type {FormatterArguments} from 'style-dictionary/types/Format'
+import {format} from 'prettier'
+import type {LineFormatting} from 'style-dictionary/types/FormatHelpers'
+const {fileHeader, formattedVariables} = StyleDictionary.formatHelpers
+
+/**
+ * @description Converts `StyleDictionary.dictionary.tokens` to css with @custom-media
+ * @param arguments [FormatterArguments](https://github.com/amzn/style-dictionary/blob/main/types/Format.d.ts)
+ * @returns formatted `string`
+ */
+export const cssWrapMediaQuery: StyleDictionary.Formatter = ({dictionary, options, file}: FormatterArguments) => {
+  const {outputReferences, descriptions} = options
+  const formatting: LineFormatting = {
+    commentStyle: descriptions ? 'long' : 'none',
+  }
+  // get specific media query or use screen
+  const mediaQuery = options.mediaQuery?.[file.destination] || 'screen'
+  // add file header
+  const output = [fileHeader({file})]
+  // add meadia query
+  output.push(`@media ${mediaQuery} {\n:root {`)
+  // add tokens
+  output.push(formattedVariables({format: 'css', dictionary, outputReferences, formatting}))
+  // close media query
+  output.push(`}\n}`)
+  // return prettified
+  return format(output.join('\n'), {parser: 'css', printWidth: 500})
+}

package/src/formats/index.ts

@@ -0,0 +1,11 @@
+export {cssThemed} from './cssThemed'
+export {cssCustomMedia} from './cssCustomMedia'
+export {cssWrapMediaQuery} from './cssWrapMediaQuery'
+export {cssVariables} from './cssVariables'
+export {jsonFigma} from './jsonFigma'
+export {javascriptCommonJs} from './javascriptCommonJs'
+export {javascriptEsm} from './javascriptEsm'
+export {jsonNestedPrefixed} from './jsonNestedPrefixed'
+export {jsonOneDimensional} from './jsonOneDimensional'
+export {jsonPostCssFallback} from './jsonPostCssFallback'
+export {typescriptExportDefinition} from './typescriptExportDefinition'

package/src/formats/javascriptCommonJs.ts

@@ -0,0 +1,21 @@
+import {format} from 'prettier'
+import {jsonToNestedValue} from './utilities/jsonToNestedValue'
+import {prefixTokens} from './utilities/prefixTokens'
+import StyleDictionary from 'style-dictionary'
+import type {FormatterArguments} from 'style-dictionary/types/Format'
+
+const {fileHeader} = StyleDictionary.formatHelpers
+
+/**
+ * @description Converts `StyleDictionary.dictionary.tokens` to javascript commonJS module
+ * @param arguments [FormatterArguments](https://github.com/amzn/style-dictionary/blob/main/types/Format.d.ts)
+ * @returns formatted `string`
+ */
+export const javascriptCommonJs: StyleDictionary.Formatter = ({dictionary, file, platform}: FormatterArguments) => {
+  // add prefix if defined
+  const tokens = prefixTokens(dictionary.tokens, platform)
+  // add file header and convert output
+  const output = `${fileHeader({file})}exports.default = ${JSON.stringify(jsonToNestedValue(tokens), null, 2)}\n`
+  // return prettified
+  return format(output, {parser: 'typescript', printWidth: 500})
+}

package/src/formats/javascriptEsm.ts

@@ -0,0 +1,21 @@
+import StyleDictionary from 'style-dictionary'
+import {format} from 'prettier'
+import {jsonToNestedValue} from './utilities/jsonToNestedValue'
+import {prefixTokens} from './utilities/prefixTokens'
+import type {FormatterArguments} from 'style-dictionary/types/Format'
+
+const {fileHeader} = StyleDictionary.formatHelpers
+
+/**
+ * @description Converts `StyleDictionary.dictionary.tokens` to javascript esm (javascript export statement)
+ * @param arguments [FormatterArguments](https://github.com/amzn/style-dictionary/blob/main/types/Format.d.ts)
+ * @returns formatted `string`
+ */
+export const javascriptEsm: StyleDictionary.Formatter = ({dictionary, file, platform}: FormatterArguments) => {
+  // add prefix if defined
+  const tokens = prefixTokens(dictionary.tokens, platform)
+  // add file header and convert output
+  const output = `${fileHeader({file})}export default \n${JSON.stringify(jsonToNestedValue(tokens), null, 2)}\n`
+  // return prettified
+  return format(output, {parser: 'typescript', printWidth: 500})
+}