rastack 0.0.24 → 0.0.26

package/dist/tokens/define.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `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 } from "./types";
+/** An alias reference to another token: `ref("color.brand.500")` → `"{color.brand.500}"`. */
+export declare function ref(path: string): string;
+/** True when a string is a DTCG alias (`"{a.b.c}"`). */
+export declare function isAlias(value: unknown): value is string;
+/** Strip the braces from an alias: `"{a.b}"` → `"a.b"`. */
+export declare function aliasTarget(value: string): string;
+/**
+ * Typed token builders. Each accepts a literal value or an alias produced by
+ * {@link ref}, plus an optional `$description`.
+ */
+export declare const t: {
+    /** A colour: any CSS colour string (or an alias). */
+    color: (value: string, description?: string) => DesignToken;
+    /**
+     * 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;
+    /** A font-family stack. */
+    fontFamily: (value: string | string[], description?: string) => DesignToken;
+    /** A font weight (numeric `700` or keyword `"bold"`). */
+    fontWeight: (value: number | string, description?: string) => DesignToken;
+    /** A duration — `"200ms"`, or a bare `number` of milliseconds. */
+    duration: (value: string | number, description?: string) => DesignToken;
+    /** A cubic-bezier easing curve: `[x1, y1, x2, y2]`. */
+    cubicBezier: (value: [number, number, number, number], description?: string) => DesignToken;
+    /** A raw number token (line-height, z-index, opacity, …). */
+    number: (value: number, description?: string) => DesignToken;
+    /** A shadow (or a stack of shadows) → a CSS `box-shadow`. */
+    shadow: (value: ShadowValue | ShadowValue[], description?: string) => DesignToken;
+};
+/**
+ * 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 declare function defineTokens(input: TokenDocument | ThemedTokens): ThemedTokens;

package/dist/tokens/define.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * `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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.t = void 0;
+exports.ref = ref;
+exports.isAlias = isAlias;
+exports.aliasTarget = aliasTarget;
+exports.defineTokens = defineTokens;
+/** An alias reference to another token: `ref("color.brand.500")` → `"{color.brand.500}"`. */
+function ref(path) {
+    return `{${path}}`;
+}
+/** True when a string is a DTCG alias (`"{a.b.c}"`). */
+function isAlias(value) {
+    return typeof value === "string" && /^\{[^{}]+\}$/.test(value);
+}
+/** Strip the braces from an alias: `"{a.b}"` → `"a.b"`. */
+function aliasTarget(value) {
+    return value.slice(1, -1);
+}
+function token(type, value, description) {
+    const out = { $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`.
+ */
+exports.t = {
+    /** A colour: any CSS colour string (or an alias). */
+    color: (value, description) => 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, description) => token("dimension", typeof value === "number" ? `${value}px` : value, description),
+    /** A font-family stack. */
+    fontFamily: (value, description) => token("fontFamily", value, description),
+    /** A font weight (numeric `700` or keyword `"bold"`). */
+    fontWeight: (value, description) => token("fontWeight", value, description),
+    /** A duration — `"200ms"`, or a bare `number` of milliseconds. */
+    duration: (value, description) => token("duration", typeof value === "number" ? `${value}ms` : value, description),
+    /** A cubic-bezier easing curve: `[x1, y1, x2, y2]`. */
+    cubicBezier: (value, description) => token("cubicBezier", value, description),
+    /** A raw number token (line-height, z-index, opacity, …). */
+    number: (value, description) => token("number", value, description),
+    /** A shadow (or a stack of shadows) → a CSS `box-shadow`. */
+    shadow: (value, description) => 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}.
+ */
+function defineTokens(input) {
+    if (isThemed(input)) {
+        return { modes: {}, ...input };
+    }
+    return { tokens: input, modes: {} };
+}
+function isThemed(input) {
+    return (typeof input.tokens === "object" &&
+        input.tokens !== null);
+}

package/dist/tokens/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `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/dist/tokens/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * `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`).
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./define"), exports);
+__exportStar(require("./theme"), exports);
+__exportStar(require("./color"), exports);
+__exportStar(require("./resolve"), exports);
+__exportStar(require("./css"), exports);
+__exportStar(require("./ts"), exports);

package/dist/tokens/resolve.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 { ResolvedToken, ThemedTokens, TokenDocument } from "./types";
+/**
+ * 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 declare function resolveTokens(doc: TokenDocument): ResolvedToken[];
+/** Deep-merge `override` onto `base`, returning a new document (base untouched). */
+export declare function mergeTokens(base: TokenDocument, override: TokenDocument): TokenDocument;
+/** 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 declare function resolveTheme(themed: ThemedTokens): ResolvedTheme;
+/**
+ * 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 declare function cssVarName(path: string, prefix?: string): string;

package/dist/tokens/resolve.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * 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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTokens = resolveTokens;
+exports.mergeTokens = mergeTokens;
+exports.resolveTheme = resolveTheme;
+exports.cssVarName = cssVarName;
+const define_1 = require("./define");
+const types_1 = require("./types");
+/** 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) {
+    const entries = [];
+    const walk = (node, prefix, inheritedType) => {
+        const groupType = node?.$type ?? inheritedType;
+        for (const key of Object.keys(node)) {
+            if (META_KEYS.has(key))
+                continue;
+            const child = node[key];
+            const path = [...prefix, key];
+            if ((0, types_1.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.
+ */
+function resolveTokens(doc) {
+    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, seen) => {
+        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 ((0, define_1.isAlias)(value)) {
+            const target = (0, define_1.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 = {
+            path,
+            type: resolved.type,
+            value: resolved.value,
+        };
+        if ((0, define_1.isAlias)(value))
+            out.aliasOf = (0, define_1.aliasTarget)(value);
+        if (token.$description)
+            out.$description = token.$description;
+        return out;
+    });
+}
+/** Deep-merge `override` onto `base`, returning a new document (base untouched). */
+function mergeTokens(base, override) {
+    const out = Array.isArray(base) ? [...base] : { ...base };
+    for (const key of Object.keys(override)) {
+        const o = override[key];
+        const b = out[key];
+        if (o &&
+            b &&
+            typeof o === "object" &&
+            typeof b === "object" &&
+            !(0, types_1.isToken)(o) &&
+            !(0, types_1.isToken)(b)) {
+            out[key] = mergeTokens(b, o);
+        }
+        else {
+            out[key] = o;
+        }
+    }
+    return out;
+}
+/**
+ * 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.
+ */
+function resolveTheme(themed) {
+    const base = resolveTokens(themed.tokens);
+    const modes = {};
+    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.
+ */
+function cssVarName(path, prefix = "") {
+    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}`;
+}

package/dist/tokens/studio.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The design studio page — a self-contained, dependency-free HTML app that
+ * `rastack design` serves. It **showcases** the design system (colour swatches,
+ * type ramp, spacing, radii, shadows, and live component previews built from the
+ * tokens themselves) and lets you **edit** token values in place — with a live
+ * preview — then save them back to the source, or export the DTCG JSON / CSS.
+ *
+ * Pure: given a themed doc it returns an HTML string, so it renders identically
+ * whether served by the CLI or snapshotted in a test. The page talks to the CLI
+ * server over two tiny endpoints: `POST /save` (persist) and it embeds
+ * everything else it needs inline.
+ */
+import { ThemedTokens } from "./types";
+export interface StudioOptions {
+    prefix?: string;
+    /** Whether the running server accepts `POST /save` (false for module sources). */
+    editable?: boolean;
+    title?: string;
+}
+/** Render the full design-studio HTML document for a themed token set. */
+export declare function renderStudio(themed: ThemedTokens, options?: StudioOptions): string;