rastack 0.0.24 → 0.0.26

package/src/tokens/css.ts

@@ -0,0 +1,138 @@
+/**
+ * CSS custom-property emitter — the primary, framework-agnostic output.
+ *
+ * Design tokens become CSS variables under `:root`, and each **mode** becomes a
+ * selector scope that overrides only the tokens it changes. A running app then
+ * switches theme by toggling one attribute (`<html data-theme="dark">`), and
+ * every `var(--…)` reference recascades for free. Aliases are preserved as
+ * `var(--target)` rather than inlined, so overriding a base token
+ * automatically flows through everything that references it.
+ */
+
+import { cssVarName, ResolvedTheme, resolveTheme } from "./resolve";
+import { ThemedTokens, ResolvedToken, ShadowValue, TokenValue } from "./types";
+
+export interface CssOptions {
+  /** Prefix every variable: `prefix: "rs"` → `--rs-color-brand-500`. */
+  prefix?: string;
+  /**
+   * How a mode maps to a selector. Given the mode name, return the selector
+   * whose block holds that mode's overrides. Default: `[data-theme="<mode>"]`,
+   * with the default mode also written to `:root`.
+   */
+  modeSelector?: (mode: string) => string;
+  /** Root selector for the base tokens. Default `:root`. */
+  rootSelector?: string;
+}
+
+/** Render one CSS number/length; bare numbers stay unitless. */
+function dim(v: string | number): string {
+  return typeof v === "number" ? `${v}px` : v;
+}
+
+/** Quote a font-family entry only when it contains whitespace. */
+function fontEntry(name: string): string {
+  return /\s/.test(name) && !/^["']/.test(name) ? `"${name}"` : name;
+}
+
+function shadow(s: ShadowValue): string {
+  const parts = [
+    s.inset ? "inset" : "",
+    dim(s.offsetX),
+    dim(s.offsetY),
+    s.blur != null ? dim(s.blur) : "",
+    s.spread != null ? dim(s.spread) : "",
+    s.color,
+  ];
+  return parts.filter(Boolean).join(" ");
+}
+
+/** Format a resolved token's literal value as a CSS declaration value. */
+export function formatCssValue(token: ResolvedToken): string {
+  const { type, value } = token;
+  switch (type) {
+    case "fontFamily":
+      return (Array.isArray(value) ? (value as string[]) : [value as string])
+        .map(fontEntry)
+        .join(", ");
+    case "cubicBezier":
+      return `cubic-bezier(${(value as unknown as number[]).join(", ")})`;
+    case "shadow":
+      return (Array.isArray(value) ? (value as ShadowValue[]) : [value as ShadowValue])
+        .map(shadow)
+        .join(", ");
+    case "dimension":
+      return dim(value as string | number);
+    case "number":
+    case "fontWeight":
+    case "color":
+    case "duration":
+      return String(value);
+    default:
+      return typeof value === "object" ? JSON.stringify(value) : String(value);
+  }
+}
+
+/** The right-hand side of a token's CSS declaration: `var(--alias)` or a literal. */
+function declValue(token: ResolvedToken, prefix: string): string {
+  if (token.aliasOf) return `var(${cssVarName(token.aliasOf, prefix)})`;
+  return formatCssValue(token);
+}
+
+function block(
+  selector: string,
+  tokens: ResolvedToken[],
+  prefix: string,
+  indent = "  ",
+): string {
+  const lines = tokens.map(
+    (tok) => `${indent}${cssVarName(tok.path, prefix)}: ${declValue(tok, prefix)};`,
+  );
+  return `${selector} {\n${lines.join("\n")}\n}`;
+}
+
+/** Only the tokens whose emitted declaration differs from the base. */
+function changed(
+  base: ResolvedToken[],
+  mode: ResolvedToken[],
+  prefix: string,
+): ResolvedToken[] {
+  const baseDecl = new Map(base.map((t) => [t.path, declValue(t, prefix)]));
+  return mode.filter((t) => baseDecl.get(t.path) !== declValue(t, prefix));
+}
+
+/** Emit CSS custom properties for a resolved theme (base + mode scopes). */
+export function emitCssFromResolved(
+  resolved: ResolvedTheme,
+  options: CssOptions = {},
+): string {
+  const prefix = options.prefix ?? "";
+  const root = options.rootSelector ?? ":root";
+  const modeSelector = options.modeSelector ?? ((m) => `[data-theme="${m}"]`);
+
+  const blocks: string[] = [
+    `/* Generated by \`rastack tokens\` — do not edit by hand. */`,
+  ];
+
+  // Base + the default mode both live on :root, so an app with no attribute set
+  // still gets a complete, sensible theme.
+  const defaultMode = resolved.defaultMode;
+  const rootTokens =
+    defaultMode && resolved.modes[defaultMode]
+      ? resolved.modes[defaultMode]
+      : resolved.base;
+  blocks.push(block(root, rootTokens, prefix));
+
+  for (const [name, tokens] of Object.entries(resolved.modes)) {
+    const diff = changed(resolved.base, tokens, prefix);
+    if (!diff.length) continue;
+    blocks.push(block(modeSelector(name), diff, prefix));
+  }
+
+  return blocks.join("\n\n") + "\n";
+}
+
+/** Emit CSS custom properties for a themed token document. */
+export function emitCss(themed: ThemedTokens, options: CssOptions = {}): string {
+  return emitCssFromResolved(resolveTheme(themed), options);
+}

package/src/tokens/define.ts

@@ -0,0 +1,128 @@
+/**
+ * `rastack/tokens` — the TypeScript-first authoring DSL for design tokens.
+ *
+ * You author your design system in TypeScript; the compiler
+ * (`rastack tokens`) emits the canonical DTCG JSON plus ready-to-use CSS custom
+ * properties and a typed theme object. This mirrors the resource DSL
+ * (`rastack/define`): TypeScript is the single source of truth.
+ *
+ * ```ts
+ * import { defineTokens, t, ref } from "rastack/tokens";
+ *
+ * export default defineTokens({
+ *   tokens: {
+ *     color: {
+ *       brand: { 500: t.color("#4F6BFF"), 600: t.color("#3B54E8") },
+ *       text:  t.color(ref("color.brand.500")),   // alias
+ *     },
+ *     space: { sm: t.dimension(8), md: t.dimension(16) },
+ *     radius: { md: t.dimension(10) },
+ *     font: { sans: t.fontFamily(["Inter", "system-ui", "sans-serif"]) },
+ *   },
+ *   modes: {
+ *     light: { color: { bg: t.color("#FFFFFF") } },
+ *     dark:  { color: { bg: t.color("#06080F") } },
+ *   },
+ *   defaultMode: "light",
+ * });
+ * ```
+ *
+ * The builders are thin: each returns a plain `{ $type, $value }` DTCG token, so
+ * a token tree authored with `t.*` is byte-identical to one hand-written as
+ * JSON. You can freely mix the two.
+ */
+
+import {
+  DesignToken,
+  ShadowValue,
+  ThemedTokens,
+  TokenDocument,
+  TokenType,
+} from "./types";
+
+/** An alias reference to another token: `ref("color.brand.500")` → `"{color.brand.500}"`. */
+export function ref(path: string): string {
+  return `{${path}}`;
+}
+
+/** True when a string is a DTCG alias (`"{a.b.c}"`). */
+export function isAlias(value: unknown): value is string {
+  return typeof value === "string" && /^\{[^{}]+\}$/.test(value);
+}
+
+/** Strip the braces from an alias: `"{a.b}"` → `"a.b"`. */
+export function aliasTarget(value: string): string {
+  return value.slice(1, -1);
+}
+
+function token<T extends TokenType>(
+  type: T,
+  value: DesignToken["$value"],
+  description?: string,
+): DesignToken {
+  const out: DesignToken = { $type: type, $value: value };
+  if (description) out.$description = description;
+  return out;
+}
+
+/**
+ * Typed token builders. Each accepts a literal value or an alias produced by
+ * {@link ref}, plus an optional `$description`.
+ */
+export const t = {
+  /** A colour: any CSS colour string (or an alias). */
+  color: (value: string, description?: string): DesignToken =>
+    token("color", value, description),
+
+  /**
+   * A dimension — spacing, sizing, radius. A bare `number` is treated as `px`
+   * (the common case); pass a string for other units (`"1rem"`, `"50%"`).
+   */
+  dimension: (value: string | number, description?: string): DesignToken =>
+    token("dimension", typeof value === "number" ? `${value}px` : value, description),
+
+  /** A font-family stack. */
+  fontFamily: (value: string | string[], description?: string): DesignToken =>
+    token("fontFamily", value, description),
+
+  /** A font weight (numeric `700` or keyword `"bold"`). */
+  fontWeight: (value: number | string, description?: string): DesignToken =>
+    token("fontWeight", value, description),
+
+  /** A duration — `"200ms"`, or a bare `number` of milliseconds. */
+  duration: (value: string | number, description?: string): DesignToken =>
+    token("duration", typeof value === "number" ? `${value}ms` : value, description),
+
+  /** A cubic-bezier easing curve: `[x1, y1, x2, y2]`. */
+  cubicBezier: (
+    value: [number, number, number, number],
+    description?: string,
+  ): DesignToken => token("cubicBezier", value as unknown as string[], description),
+
+  /** A raw number token (line-height, z-index, opacity, …). */
+  number: (value: number, description?: string): DesignToken =>
+    token("number", value, description),
+
+  /** A shadow (or a stack of shadows) → a CSS `box-shadow`. */
+  shadow: (value: ShadowValue | ShadowValue[], description?: string): DesignToken =>
+    token("shadow", value, description),
+};
+
+/**
+ * Author a themeable token set. Accepts either a bare token tree or the full
+ * `{ tokens, modes, defaultMode }` shape, and always normalises to
+ * {@link ThemedTokens}.
+ */
+export function defineTokens(input: TokenDocument | ThemedTokens): ThemedTokens {
+  if (isThemed(input)) {
+    return { modes: {}, ...input };
+  }
+  return { tokens: input, modes: {} };
+}
+
+function isThemed(input: TokenDocument | ThemedTokens): input is ThemedTokens {
+  return (
+    typeof (input as ThemedTokens).tokens === "object" &&
+    (input as ThemedTokens).tokens !== null
+  );
+}

package/src/tokens/index.ts

@@ -0,0 +1,18 @@
+/**
+ * `rastack/tokens` core — the design-system framework.
+ *
+ * A TypeScript-first authoring DSL over the **W3C Design Tokens (DTCG)**
+ * standard, a resolver (alias + `$type` inheritance + cycle detection), and
+ * pure emitters (CSS custom properties, a typed theme). Everything here is
+ * filesystem- and React-free, so it builds for the browser and is what
+ * `rastack/theme` runs at runtime. The `rastack tokens` CLI adds file IO on top
+ * (see `tools/src/tokens/compile.ts`).
+ */
+
+export * from "./types";
+export * from "./define";
+export * from "./theme";
+export * from "./color";
+export * from "./resolve";
+export * from "./css";
+export * from "./ts";

package/src/tokens/resolve.ts

@@ -0,0 +1,170 @@
+/**
+ * Token resolution — the compiler's core pass.
+ *
+ * Given a DTCG token tree, produce a flat, ordered list of {@link ResolvedToken}
+ * with:
+ *   - **`$type` inheritance** — a token inherits the nearest ancestor group's
+ *     `$type` when it doesn't declare its own (a DTCG rule).
+ *   - **alias resolution** — a `"{a.b.c}"` value is followed to its source,
+ *     transitively, with cycle detection. The immediate alias target is kept
+ *     (`aliasOf`) so emitters can preserve the reference.
+ *   - **stable ordering** — depth-first in author order, so output diffs are
+ *     minimal.
+ */
+
+import { aliasTarget, isAlias } from "./define";
+import {
+  DesignToken,
+  isToken,
+  ResolvedToken,
+  ThemedTokens,
+  TokenDocument,
+  TokenType,
+  TokenValue,
+} from "./types";
+
+/** A flat map from dotted path to the raw token, plus its inherited type. */
+interface RawEntry {
+  path: string;
+  token: DesignToken;
+  /** Type after group inheritance but before alias type-borrowing. */
+  ownType: TokenType | undefined;
+}
+
+/** Metadata keys on a group that are not children. */
+const META_KEYS = new Set(["$type", "$description", "$value", "$extensions"]);
+
+/** Flatten a token tree to raw entries, applying group `$type` inheritance. */
+function flatten(doc: TokenDocument): RawEntry[] {
+  const entries: RawEntry[] = [];
+
+  const walk = (node: any, prefix: string[], inheritedType: TokenType | undefined) => {
+    const groupType = (node?.$type as TokenType | undefined) ?? inheritedType;
+    for (const key of Object.keys(node)) {
+      if (META_KEYS.has(key)) continue;
+      const child = node[key];
+      const path = [...prefix, key];
+      if (isToken(child)) {
+        entries.push({
+          path: path.join("."),
+          token: child,
+          ownType: child.$type ?? groupType,
+        });
+      } else if (child && typeof child === "object") {
+        walk(child, path, groupType);
+      }
+    }
+  };
+
+  walk(doc, [], undefined);
+  return entries;
+}
+
+/**
+ * Resolve a token document into ordered, alias-free {@link ResolvedToken}s.
+ * Throws on a dangling alias or an alias cycle — the token equivalent of the
+ * resource compiler's dangling-FK / circular-dependency checks.
+ */
+export function resolveTokens(doc: TokenDocument): ResolvedToken[] {
+  const raw = flatten(doc);
+  const byPath = new Map(raw.map((e) => [e.path, e]));
+
+  // Resolve one path to its literal value + effective type, following aliases.
+  const resolveValue = (
+    path: string,
+    seen: string[],
+  ): { value: TokenValue; type: TokenType | undefined } => {
+    const entry = byPath.get(path);
+    if (!entry) {
+      throw new Error(
+        `Token "${seen[seen.length - 1] ?? path}" aliases unknown token "${path}".`,
+      );
+    }
+    const value = entry.token.$value;
+    if (isAlias(value)) {
+      const target = aliasTarget(value);
+      if (seen.includes(target)) {
+        throw new Error(
+          `Alias cycle detected: ${[...seen, target].join(" → ")}.`,
+        );
+      }
+      const resolved = resolveValue(target, [...seen, target]);
+      // A pure alias borrows its target's type when it has none of its own.
+      return { value: resolved.value, type: entry.ownType ?? resolved.type };
+    }
+    return { value, type: entry.ownType };
+  };
+
+  return raw.map(({ path, token }) => {
+    const value = token.$value;
+    const resolved = resolveValue(path, [path]);
+    const out: ResolvedToken = {
+      path,
+      type: resolved.type,
+      value: resolved.value,
+    };
+    if (isAlias(value)) out.aliasOf = aliasTarget(value);
+    if (token.$description) out.$description = token.$description;
+    return out;
+  });
+}
+
+/** Deep-merge `override` onto `base`, returning a new document (base untouched). */
+export function mergeTokens(
+  base: TokenDocument,
+  override: TokenDocument,
+): TokenDocument {
+  const out: any = Array.isArray(base) ? [...base] : { ...base };
+  for (const key of Object.keys(override)) {
+    const o = (override as any)[key];
+    const b = (out as any)[key];
+    if (
+      o &&
+      b &&
+      typeof o === "object" &&
+      typeof b === "object" &&
+      !isToken(o) &&
+      !isToken(b)
+    ) {
+      out[key] = mergeTokens(b, o);
+    } else {
+      out[key] = o;
+    }
+  }
+  return out;
+}
+
+/** The resolved base plus, per mode, the resolved base-merged-with-that-mode. */
+export interface ResolvedTheme {
+  base: ResolvedToken[];
+  modes: Record<string, ResolvedToken[]>;
+  defaultMode?: string;
+}
+
+/**
+ * Resolve a themed token set: the base tree, and every mode as the base
+ * deep-merged with that mode's overrides. Callers diff a mode against the base
+ * to emit only what changed.
+ */
+export function resolveTheme(themed: ThemedTokens): ResolvedTheme {
+  const base = resolveTokens(themed.tokens);
+  const modes: Record<string, ResolvedToken[]> = {};
+  for (const [name, overrides] of Object.entries(themed.modes ?? {})) {
+    modes[name] = resolveTokens(mergeTokens(themed.tokens, overrides));
+  }
+  return { base, modes, defaultMode: themed.defaultMode };
+}
+
+/**
+ * The CSS custom-property name for a token path.
+ * `color.brand.500` → `--color-brand-500`. Segments are lower-cased and any
+ * non-word character becomes `-`, so numeric and camelCase keys stay valid.
+ */
+export function cssVarName(path: string, prefix = ""): string {
+  const body = path
+    .split(".")
+    .map((s) => s.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase())
+    .join("-")
+    .replace(/[^a-z0-9-]+/g, "-");
+  return `--${prefix ? `${prefix}-` : ""}${body}`;
+}