@terrazzo/token-tools 0.0.2 → 0.0.3

package/src/css/lib.ts

@@ -0,0 +1,54 @@
+import { kebabCase } from 'scule';
+
+/** Function that generates a var(…) statement */
+export type IDGenerator = (id: string) => string;
+
+export const defaultAliasTransform = (id: string) => `var(${makeCSSVar(id)})`;
+
+/** Generate shorthand CSS for select token types */
+export function generateShorthand({ $type, localID }: { $type: string; localID: string }): string | undefined {
+  switch ($type) {
+    case 'transition': {
+      return ['duration', 'delay', 'timing-function']
+        .map((p) => makeCSSVar(`${localID}-${p}`, { wrapVar: true }))
+        .join(' ');
+    }
+    // note: "typography" is not set in shorthand because it can often unset values unintentionally.
+    // @see https://developer.mozilla.org/en-US/docs/Web/CSS/font
+  }
+}
+
+/** Build object of alias values */
+export function transformCompositeAlias<T extends {}>(
+  value: T,
+  { aliasOf, transformAlias = defaultAliasTransform }: { aliasOf: string; transformAlias?: IDGenerator },
+): Record<string, string> {
+  const output: Record<string, string> = {};
+  for (const key in value) {
+    output[kebabCase(key)] = transformAlias(`${aliasOf}-${key}`);
+  }
+  return output as Record<keyof T, string>;
+}
+
+const CSS_VAR_RE =
+  /(?:(\p{Uppercase_Letter}?\p{Lowercase_Letter}+|\p{Uppercase_Letter}+|\p{Number}+|[\u{80}-\u{10FFFF}]+|_)|.)/u;
+
+export interface MakeCSSVarOptions {
+  /** Prefix with string */
+  prefix?: string;
+  /** Wrap with `var(…)` (default: false) */
+  wrapVar?: boolean;
+}
+
+/**
+ * Generate a valid CSS variable from any string
+ * Code by @dfrankland
+ */
+export function makeCSSVar(name: string, { prefix, wrapVar = false }: MakeCSSVarOptions = {}): string {
+  let property = name.split(CSS_VAR_RE).filter(Boolean).join('-');
+  if (prefix && !property.startsWith(`${prefix}-`)) {
+    property = `${prefix}-${property}`;
+  }
+  const finalProperty = `--${property}`.toLocaleLowerCase();
+  return wrapVar ? `var(${finalProperty})` : finalProperty;
+}

package/src/css/link.ts

@@ -0,0 +1,12 @@
+import { type IDGenerator, defaultAliasTransform } from './lib.js';
+
+/** Convert link value to CSS */
+export function transformLinkValue(
+  value: string,
+  { aliasOf, transformAlias = defaultAliasTransform }: { aliasOf?: string; transformAlias?: IDGenerator } = {},
+): string {
+  if (aliasOf) {
+    return transformAlias(aliasOf);
+  }
+  return `url("${value}")`;
+}

package/src/css/number.ts

@@ -0,0 +1,9 @@
+import { type IDGenerator, defaultAliasTransform } from './lib.js';
+
+/** Convert number value to CSS */
+export function transformNumberValue(
+  value: number,
+  { aliasOf, transformAlias = defaultAliasTransform }: { aliasOf?: string; transformAlias?: IDGenerator } = {},
+): string {
+  return aliasOf ? transformAlias(aliasOf) : String(value);
+}

package/src/css/shadow.ts

@@ -0,0 +1,75 @@
+import type { ShadowTokenNormalized, ShadowValueNormalized } from '../types';
+import { transformColorValue } from './color.js';
+import { transformDimensionValue } from './dimension.js';
+import { type IDGenerator, defaultAliasTransform } from './lib.js';
+
+/** Convert shadow subvalue to CSS */
+export function transformShadowLayer(
+  value: ShadowValueNormalized,
+  {
+    color,
+    partialAliasOf,
+    transformAlias = defaultAliasTransform,
+  }: {
+    color: string;
+    partialAliasOf?: Partial<Record<keyof ShadowValueNormalized, string>>;
+    transformAlias?: IDGenerator;
+  },
+): string | Record<string, string> {
+  const offsetX = partialAliasOf?.offsetX
+    ? transformAlias(partialAliasOf.offsetX)
+    : transformDimensionValue(value.offsetX, { transformAlias });
+  const offsetY = partialAliasOf?.offsetY
+    ? transformAlias(partialAliasOf.offsetY)
+    : transformDimensionValue(value.offsetY, { transformAlias });
+  const blur = partialAliasOf?.blur
+    ? transformAlias(partialAliasOf.blur)
+    : transformDimensionValue(value.blur, { transformAlias });
+  const spread = partialAliasOf?.spread
+    ? transformAlias(partialAliasOf.spread)
+    : transformDimensionValue(value.spread, { transformAlias });
+
+  return [offsetX, offsetY, blur, spread, color].join(' ');
+}
+
+/** Convert shadow value to CSS */
+export function transformShadowValue(
+  value: ShadowTokenNormalized['$value'],
+  {
+    aliasOf,
+    partialAliasOf,
+    transformAlias = defaultAliasTransform,
+  }: {
+    aliasOf?: string;
+    partialAliasOf?: Partial<Record<keyof ShadowValueNormalized, string>>[];
+    transformAlias?: IDGenerator;
+  } = {},
+): string | Record<string, string> {
+  if (aliasOf) {
+    return transformAlias(aliasOf);
+  }
+  const colors = value.map(({ color }, i) =>
+    partialAliasOf?.[i]?.color
+      ? transformAlias(partialAliasOf[i]!.color!)
+      : transformColorValue(color, { transformAlias }),
+  );
+  const isHDR = colors.some((c) => typeof c === 'object');
+
+  const formatShadow = (colorKey: string) =>
+    value
+      .map((v, i) =>
+        transformShadowLayer(v, {
+          color:
+            typeof colors[i] === 'string'
+              ? (colors[i] as string)
+              : colors[i]![colorKey as keyof (typeof colors)[number]]!,
+          partialAliasOf: partialAliasOf?.[i],
+          transformAlias,
+        }),
+      )
+      .join(', ');
+
+  return !isHDR
+    ? formatShadow('.')
+    : { '.': formatShadow('.'), srgb: formatShadow('srgb'), p3: formatShadow('p3'), rec2020: formatShadow('rec2020') };
+}

package/src/css/string.ts

@@ -0,0 +1,11 @@
+import { type IDGenerator, defaultAliasTransform } from './lib.js';
+
+/** Convert string value to CSS */
+export function transformStringValue(
+  value: string | number | boolean,
+  { aliasOf, transformAlias = defaultAliasTransform }: { aliasOf?: string; transformAlias?: IDGenerator } = {},
+): string {
+  // this seems like a useless function—because it is—but this is a placeholder
+  // that can handle unexpected values in the future should any arise
+  return aliasOf ? transformAlias(aliasOf) : String(value);
+}

package/src/css/stroke-style.ts

@@ -0,0 +1,13 @@
+import type { StrokeStyleValue } from '../types.js';
+import { type IDGenerator, defaultAliasTransform } from './lib.js';
+
+/** Convert strokeStyle value to CSS */
+export function transformStrokeStyleValue(
+  value: string | StrokeStyleValue,
+  { aliasOf, transformAlias = defaultAliasTransform }: { aliasOf?: string; transformAlias?: IDGenerator } = {},
+): string {
+  if (aliasOf) {
+    return transformAlias(aliasOf);
+  }
+  return typeof value === 'string' ? value : 'dashed'; // CSS doesn’t have `dash-array`; it’s just "dashed"
+}

package/src/css/transition.ts

@@ -0,0 +1,41 @@
+import type { TransitionValueNormalized } from '../types.js';
+import { transformCubicBezierValue } from './cubic-bezier.js';
+import { transformDurationValue } from './duration.js';
+import { type IDGenerator, defaultAliasTransform, transformCompositeAlias } from './lib.js';
+
+/** Convert transition value to multiple CSS values */
+export function transformTransitionValue(
+  value: TransitionValueNormalized,
+  {
+    aliasOf,
+    partialAliasOf,
+    transformAlias = defaultAliasTransform,
+  }: {
+    aliasOf?: string;
+    partialAliasOf?: Partial<Record<keyof typeof value, string>>;
+    transformAlias?: IDGenerator;
+  } = {},
+): {
+  duration: ReturnType<typeof transformDurationValue>;
+  delay: ReturnType<typeof transformDurationValue>;
+  'timing-function': ReturnType<typeof transformCubicBezierValue>;
+} {
+  if (aliasOf) {
+    return transformCompositeAlias(value, { aliasOf, transformAlias }) as {
+      duration: ReturnType<typeof transformDurationValue>;
+      delay: ReturnType<typeof transformDurationValue>;
+      'timing-function': ReturnType<typeof transformCubicBezierValue>;
+    };
+  }
+  return {
+    duration: partialAliasOf?.duration
+      ? transformAlias(partialAliasOf.duration)
+      : transformDurationValue(value.duration, { transformAlias }),
+    delay: partialAliasOf?.delay
+      ? transformAlias(partialAliasOf.delay)
+      : transformDurationValue(value.delay, { transformAlias }),
+    'timing-function': partialAliasOf?.timingFunction
+      ? transformAlias(partialAliasOf.timingFunction)
+      : transformCubicBezierValue(value.timingFunction, { transformAlias }),
+  };
+}

package/src/css/typography.ts

@@ -0,0 +1,44 @@
+import { kebabCase } from 'scule';
+import { transformFontFamilyValue } from './font-family.js';
+import { transformFontWeightValue } from './font-weight.js';
+import { type IDGenerator, defaultAliasTransform, transformCompositeAlias } from './lib.js';
+import { transformStringValue } from './string.js';
+
+/** Convert typography value to multiple CSS values */
+export function transformTypographyValue(
+  value: Record<string, string | string[]>,
+  {
+    aliasOf,
+    partialAliasOf,
+    transformAlias = defaultAliasTransform,
+  }: { aliasOf?: string; partialAliasOf?: Record<keyof typeof value, string>; transformAlias?: IDGenerator } = {},
+): Record<string, string> {
+  const output: Record<string, string> = {};
+  if (aliasOf) {
+    return transformCompositeAlias(value, { aliasOf, transformAlias });
+  }
+  for (const [property, subvalue] of Object.entries(value)) {
+    let transformedValue: string;
+    if (partialAliasOf?.[property]) {
+      transformedValue = transformAlias(partialAliasOf[property]!);
+    } else {
+      switch (property) {
+        case 'fontFamily': {
+          transformedValue = transformFontFamilyValue(subvalue as string[], { transformAlias });
+          break;
+        }
+        case 'fontSize':
+        case 'fontWeight': {
+          transformedValue = transformFontWeightValue(subvalue as string, { transformAlias });
+          break;
+        }
+        default: {
+          transformedValue = transformStringValue(subvalue as string, { transformAlias });
+          break;
+        }
+      }
+    }
+    output[kebabCase(property)] = transformedValue;
+  }
+  return output;
+}

package/src/index.ts

@@ -1,3 +1,5 @@
 export * from './color.js';
 export * from './id.js';
 export * from './string.js';
+export * from './transform.js';
+export * from './types.js';

package/src/js/index.ts

@@ -0,0 +1,31 @@
+import type { TokenNormalized } from '../types.js';
+
+export interface TransformJSValueOptions {
+  mode: string;
+  /** indent space count */
+  indent?: number;
+  /** initial indent level */
+  startingIndent?: number;
+}
+
+/**
+ * Convert token value to a JS string via acorn/astring.
+ */
+export function transformJSValue<T extends TokenNormalized>(
+  token: T,
+  { mode, indent = 2, startingIndent = 0 }: TransformJSValueOptions,
+) {
+  if (!(mode in token.mode)) {
+    return;
+  }
+  const indentStart = startingIndent > 0 ? ' '.repeat(startingIndent ?? 2) : '';
+
+  // note: since tokens are JSON-serializable to begin with, using
+  // JSON.stringify generates the same output as an AST parser/generator would
+  // but faster and without the added overhead (even acorn/astring leave object
+  // keys quoted).
+
+  // TODO: use @biomejs/js-api when it’s stable for pretty formatting
+
+  return JSON.stringify(token.mode[mode]!.$value, undefined, indent).replace(/\n/g, `\n${indentStart}`);
+}

package/src/transform.ts

@@ -0,0 +1,23 @@
+export interface CustomTransformOptions {
+  /** Token $type */
+  $type: string;
+}
+
+/** Give a user pertinent feedback if they override a transform incorrectly */
+export function validateCustomTransform(value: unknown, { $type }: CustomTransformOptions) {
+  if (value) {
+    if ((typeof value !== 'string' && typeof value !== 'object') || Array.isArray(value)) {
+      throw new Error(
+        `transform(): expected string or Object of strings, received ${Array.isArray(value) ? 'Array' : typeof value}`,
+      );
+    }
+    switch ($type) {
+      case 'typography': {
+        if (typeof value !== 'object') {
+          throw new Error('transform(): typography tokens must be an object of keys');
+        }
+        break;
+      }
+    }
+  }
+}