@anvpx/motion-themes 0.0.0-stage → 0.1.1

package/dist/dtcg.js

@@ -0,0 +1,57 @@
+const isTree = (node) => typeof node === "object" && node !== null && !Array.isArray(node);
+/** Token name -> raw `$value` for every token directly inside the named group. */
+export const readGroup = (tree, group) => {
+    const node = tree[group];
+    if (!isTree(node))
+        throw new Error(`theme token group "${group}" is missing`);
+    const entries = Object.entries(node)
+        .filter(([name]) => !name.startsWith("$"))
+        .map(([name, token]) => {
+        if (!isTree(token) || !("$value" in token)) {
+            throw new Error(`token "${group}.${name}" has no $value`);
+        }
+        return [name, token.$value];
+    });
+    return Object.fromEntries(entries);
+};
+const mapValues = (values, convert) => Object.fromEntries(Object.entries(values).map(([name, value]) => [name, convert(value, name)]));
+const asString = (value, name) => {
+    if (typeof value !== "string")
+        throw new Error(`token "${name}" must be a string`);
+    return value;
+};
+const parseUnit = (value, name, unit) => {
+    const text = asString(value, name);
+    if (!text.endsWith(unit))
+        throw new Error(`token "${name}" must end in "${unit}", got "${text}"`);
+    return Number(text.slice(0, -unit.length));
+};
+export const toPx = (values) => mapValues(values, (value, name) => parseUnit(value, name, "px"));
+export const toSeconds = (values) => mapValues(values, (value, name) => parseUnit(value, name, "ms") / 1000);
+export const toNumbers = (values) => mapValues(values, (value, name) => {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`token "${name}" must be a finite number`);
+    }
+    return value;
+});
+const HEX_COLOUR = /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/** Colour functions with literal arguments only: no nested function, quote or escape can load a resource. */
+const FUNCTION_COLOUR = /^(?:rgba?|hsla?|hwb|lab|lch|oklab|oklch)\(\s*[-+0-9a-z.%,/\s]*\)$/i;
+const KEYWORD_COLOUR = /^[a-z]+$/i;
+/** Colour tokens: hex, a literal-argument colour function or a keyword; never `url()` or another function. */
+export const toColours = (values) => mapValues(values, (value, name) => {
+    const text = asString(value, name);
+    if (![HEX_COLOUR, FUNCTION_COLOUR, KEYWORD_COLOUR].some((grammar) => grammar.test(text))) {
+        throw new Error(`token "${name}" must be a plain colour (hex, rgb(), hsl(), hwb(), lab(), lch(), oklab(), oklch() or keyword), got "${text}"`);
+    }
+    return text;
+});
+const escapeQuoted = (family) => family.replace(/["\\]/g, "\\$&");
+const quoteIfNeeded = (family) => /[\s"\\]/.test(family) ? `"${escapeQuoted(family)}"` : family;
+export const toFontStacks = (values) => mapValues(values, (value, name) => {
+    if (!Array.isArray(value))
+        throw new Error(`token "${name}" must be a font family array`);
+    return value.map((family) => quoteIfNeeded(asString(family, name))).join(", ");
+});
+/** Like `readGroup`, but an absent group is an empty record (optional token groups). */
+export const readOptionalGroup = (tree, group) => isTree(tree[group]) ? readGroup(tree, group) : {};

package/dist/grade/grades.d.ts

@@ -0,0 +1,24 @@
+export declare const GRADE_NAMES: readonly ["none", "warm", "cool", "noir"];
+export type GradeName = (typeof GRADE_NAMES)[number];
+export declare const TONE_MAPS: readonly ["none", "hable", "reinhard", "mobius"];
+export type ToneMap = (typeof TONE_MAPS)[number];
+type GradeDoc = Readonly<Record<string, unknown>>;
+declare const isGradeName: (name: string) => name is GradeName;
+export { isGradeName };
+/**
+ * DTCG `color.grade.*` tokens parsed with the shared colour grammar.
+ * Extra names are rejected so the enum stays small and reviewable.
+ */
+export declare const parseGrades: (doc: GradeDoc) => Record<GradeName, string>;
+/** Curated grades from the shipped DTCG fragment, or a caller-supplied doc. */
+export declare const resolveGrades: (doc?: GradeDoc) => Record<GradeName, string>;
+/** `.cube` LUT shipped as CC0 data in the assets package luts dir; `none` needs no LUT. */
+export declare const gradeLutFile: (name: GradeName) => string | null;
+export declare const gradeToneMap: (name: GradeName) => ToneMap;
+export declare const gradeFilter: (name: GradeName) => string;
+/**
+ * Projects grade tokens through the existing CSS custom-property pattern:
+ * `--mk-color-grade-<name>` for the DTCG colour plus `--mk-grade-filter/lut/tonemap-<name>`
+ * for the runtime mapping. Throws on names or values that could break out of `<style>`.
+ */
+export declare const toGradeCssVars: (grades: Readonly<Record<string, string>>) => string;

package/dist/grade/grades.js

@@ -0,0 +1,85 @@
+import { readGroup, toColours } from "../dtcg.js";
+import gradeTokens from "./grades.json" with { type: "json" };
+export const GRADE_NAMES = ["none", "warm", "cool", "noir"];
+export const TONE_MAPS = ["none", "hable", "reinhard", "mobius"];
+const isGradeName = (name) => GRADE_NAMES.includes(name);
+export { isGradeName };
+const checkedGrade = (name) => {
+    if (!isGradeName(name))
+        throw new Error(`unknown grade "${name}"; use one of: ${GRADE_NAMES.join("|")}`);
+    return name;
+};
+/**
+ * DTCG `color.grade.*` tokens parsed with the shared colour grammar.
+ * Extra names are rejected so the enum stays small and reviewable.
+ */
+export const parseGrades = (doc) => {
+    const raw = readGroup(doc, "grade");
+    const colours = toColours(raw);
+    for (const name of Object.keys(colours)) {
+        checkedGrade(name);
+    }
+    for (const name of GRADE_NAMES) {
+        if (colours[name] === undefined)
+            throw new Error(`grade "${name}" is missing`);
+    }
+    return Object.fromEntries(GRADE_NAMES.map((name) => [name, colours[name]]));
+};
+/** Curated grades from the shipped DTCG fragment, or a caller-supplied doc. */
+export const resolveGrades = (doc = gradeTokens) => parseGrades(doc);
+/** `.cube` LUT shipped as CC0 data in the assets package luts dir; `none` needs no LUT. */
+export const gradeLutFile = (name) => {
+    checkedGrade(name);
+    return name === "none" ? null : `luts/${name}.cube`;
+};
+/**
+ * HDR-prepare tone-map selection only (SDR output stays SDR).
+ * Mirrors kajisho5 `HDR_TO_SDR` names: hable / reinhard / mobius.
+ */
+const TONE_MAP_OF = {
+    none: "none",
+    warm: "hable",
+    cool: "reinhard",
+    noir: "mobius",
+};
+export const gradeToneMap = (name) => TONE_MAP_OF[checkedGrade(name)];
+/** CSS preview filter; the runtime uses the `.cube` via a three.js LUT pass when available. */
+const FILTER_OF = {
+    none: "none",
+    warm: "sepia(0.18) saturate(1.15) contrast(1.05)",
+    cool: "saturate(1.1) hue-rotate(-8deg) brightness(1.02)",
+    noir: "grayscale(1) contrast(1.15)",
+};
+export const gradeFilter = (name) => FILTER_OF[checkedGrade(name)];
+const TOKEN_KEY = /^[a-zA-Z][a-zA-Z0-9-]*$/;
+const UNSAFE_VALUE = /[<>{};\r\n]|\/\*/;
+const checkedKey = (key) => {
+    if (!TOKEN_KEY.test(key))
+        throw new Error(`invalid token name "${key}"; use letters, digits, -`);
+    return key;
+};
+const checkedValue = (name, value) => {
+    if (UNSAFE_VALUE.test(value))
+        throw new Error(`unsafe CSS value for ${name}: "${value}"`);
+    return value;
+};
+/**
+ * Projects grade tokens through the existing CSS custom-property pattern:
+ * `--mk-color-grade-<name>` for the DTCG colour plus `--mk-grade-filter/lut/tonemap-<name>`
+ * for the runtime mapping. Throws on names or values that could break out of `<style>`.
+ */
+export const toGradeCssVars = (grades) => {
+    const lines = [];
+    for (const name of GRADE_NAMES) {
+        const colour = grades[name];
+        if (typeof colour !== "string")
+            throw new Error(`grade "${name}" is missing`);
+        const key = checkedKey(name);
+        lines.push(`  --mk-color-grade-${key}: ${checkedValue(key, colour)};`);
+        lines.push(`  --mk-grade-filter-${key}: ${checkedValue(`${key}-filter`, gradeFilter(name))};`);
+        const lut = gradeLutFile(name) ?? "none";
+        lines.push(`  --mk-grade-lut-${key}: ${checkedValue(`${key}-lut`, lut)};`);
+        lines.push(`  --mk-grade-tonemap-${key}: ${checkedValue(`${key}-tonemap`, gradeToneMap(name))};`);
+    }
+    return [":root {", ...lines, "}", ""].join("\n");
+};

package/dist/grade/grades.json

@@ -0,0 +1,22 @@
+{
+    "$description": "motion-kit grade tokens, DTCG color.grade.* (curated cinematic looks; LUT files ship as CC0 data in the assets luts dir)",
+    "grade": {
+        "$type": "color",
+        "none": {
+            "$value": "#ffffff",
+            "$description": "Neutral: no primary shift; no LUT."
+        },
+        "warm": {
+            "$value": "#ffb46b",
+            "$description": "Warm primary correction: amber lift for skin tones and daylight."
+        },
+        "cool": {
+            "$value": "#6bc5ff",
+            "$description": "Cool primary correction: teal-blue lift for night and tech."
+        },
+        "noir": {
+            "$value": "#8a8a8a",
+            "$description": "Noir: desaturated high-contrast monochrome."
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { calmAccentAtom, calmMotionAtom, calmTitleAtom, syntheticAtomFixtures, } from "./atoms/fixtures.ts";
+export { type AtomRegistry, createAtomRegistry, listVerifiedAtoms, registryCanonicalBytes, resolveAtom, } from "./atoms/registry.ts";
+export { type AtomKind, type AuthoringAtom, atomRef, canonicalAtomBytes, parseAuthoringAtom, } from "./atoms/types.ts";
+export { CVD_DELTA_E_MIN, chartContrastIssues, chartCvdIssues, isStrictChart, MARK_CONTRAST_MIN, spacingIssues, type ThemeIssue, } from "./checks.ts";
+export { contrastRatio } from "./contrast.ts";
+export { toCssVars } from "./css.ts";
+export { CVD_KINDS, type CvdKind, deltaE, minPairwiseDeltaE } from "./cvd.ts";
+export { GRADE_NAMES, type GradeName, gradeFilter, gradeLutFile, gradeToneMap, isGradeName, parseGrades, resolveGrades, TONE_MAPS, type ToneMap, toGradeCssVars, } from "./grade/grades.ts";
+export { mixHex, type OptionalTokens, resolveOptionalTokens } from "./optional.ts";
+export { bundledThemeDocs, resolveTheme, THEME_NAMES, type ThemeName } from "./resolve.ts";

package/dist/index.js

@@ -0,0 +1,10 @@
+export { calmAccentAtom, calmMotionAtom, calmTitleAtom, syntheticAtomFixtures, } from "./atoms/fixtures.js";
+export { createAtomRegistry, listVerifiedAtoms, registryCanonicalBytes, resolveAtom, } from "./atoms/registry.js";
+export { atomRef, canonicalAtomBytes, parseAuthoringAtom, } from "./atoms/types.js";
+export { CVD_DELTA_E_MIN, chartContrastIssues, chartCvdIssues, isStrictChart, MARK_CONTRAST_MIN, spacingIssues, } from "./checks.js";
+export { contrastRatio } from "./contrast.js";
+export { toCssVars } from "./css.js";
+export { CVD_KINDS, deltaE, minPairwiseDeltaE } from "./cvd.js";
+export { GRADE_NAMES, gradeFilter, gradeLutFile, gradeToneMap, isGradeName, parseGrades, resolveGrades, TONE_MAPS, toGradeCssVars, } from "./grade/grades.js";
+export { mixHex, resolveOptionalTokens } from "./optional.js";
+export { bundledThemeDocs, resolveTheme, THEME_NAMES } from "./resolve.js";

package/dist/optional.d.ts

@@ -0,0 +1,40 @@
+import type { ResolvedTheme } from "@anvpx/motion-schema";
+/** Optional theme tokens (docs/STORE.md 3.3); every field has a default derived from the required keys. */
+export interface OptionalTokens {
+    /** Heading stack; defaults to the body (`sans`) stack. */
+    readonly fontDisplay: string;
+    /** Semantic colours; default to chart slots 3 (green), 7 (amber) and 5 (red). */
+    readonly status: {
+        readonly good: string;
+        readonly warn: string;
+        readonly bad: string;
+    };
+    readonly stroke: {
+        readonly card: number;
+        readonly icon: number;
+    };
+    readonly shadow: {
+        readonly mode: "none" | "soft" | "hard";
+        readonly color: string;
+    };
+    /** Static film grain opacity, 0..0.12. */
+    readonly grainOpacity: number;
+    /** Five-step ramp from `accentSoft` to `accent`. */
+    readonly chartSequential: readonly string[];
+    readonly numeric: "tabular" | "proportional";
+}
+type Doc = Readonly<Record<string, unknown>>;
+/** Linear mix of two hex colours in sRGB; `ratio` 0 gives `from`, 1 gives `to`. */
+export declare const mixHex: (from: string, to: string, ratio: number) => string;
+/**
+ * Reads the optional token groups of a DTCG theme document (`status`, `stroke`, `shadow`, `grain`,
+ * `chartSequential`, `numeric`; `font.display` arrives through `theme.fonts`) and fills the rest from
+ * `theme`. Pure; throws on a malformed token.
+ */
+export declare const resolveOptionalTokens: (theme: ResolvedTheme, doc: Doc) => OptionalTokens;
+/**
+ * Custom properties for the optional groups the document actually declares (`status`, `shadow`, `grain`,
+ * `stroke`, `numeric`); a group the theme omits yields nothing, so scenes keep their own fallback.
+ */
+export declare const optionalVars: (theme: ResolvedTheme, doc: Doc) => Record<string, string>;
+export {};

package/dist/optional.js

@@ -0,0 +1,151 @@
+import { channelsOf } from "./contrast.js";
+import { readOptionalGroup, toPx } from "./dtcg.js";
+const SHADOW_MODES = ["none", "soft", "hard"];
+const NUMERIC_MODES = ["tabular", "proportional"];
+const GRAIN_MAX = 0.12;
+const RAMP_STEPS = 5;
+const STATUS_SLOT = { good: 2, warn: 6, bad: 4 };
+const FALLBACK_INK = "#000000";
+const colourOf = (value, name) => {
+    if (typeof value !== "string")
+        throw new Error(`token "${name}" must be a hex colour string`);
+    channelsOf(value);
+    return value;
+};
+const oneOf = (value, allowed, name) => {
+    const hit = allowed.find((option) => option === value);
+    if (hit === undefined)
+        throw new Error(`token "${name}" must be one of ${allowed.join("|")}`);
+    return hit;
+};
+const hex = (channel) => Math.round(channel).toString(16).padStart(2, "0");
+/** Linear mix of two hex colours in sRGB; `ratio` 0 gives `from`, 1 gives `to`. */
+export const mixHex = (from, to, ratio) => {
+    const a = channelsOf(from);
+    const b = channelsOf(to);
+    const mixed = a.map((channel, index) => channel + ((b[index] ?? 0) - channel) * ratio);
+    return `#${mixed.map(hex).join("")}`;
+};
+const rampOf = (theme) => {
+    const from = theme.colors.accentSoft ?? theme.colors.bg ?? "#ffffff";
+    const to = theme.colors.accent ?? FALLBACK_INK;
+    return Array.from({ length: RAMP_STEPS }, (_, step) => mixHex(from, to, step / (RAMP_STEPS - 1)));
+};
+const statusColour = (group, key, theme) => {
+    const given = group[key];
+    if (given !== undefined)
+        return colourOf(given, `status.${key}`);
+    return theme.chart[STATUS_SLOT[key]] ?? theme.colors.accent ?? FALLBACK_INK;
+};
+const numberAt = (group, key, fallback) => {
+    const value = group[key];
+    if (value === undefined)
+        return fallback;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`token "${key}" must be a finite number`);
+    }
+    return value;
+};
+const strokeOf = (doc, key, fallback) => {
+    const given = readOptionalGroup(doc, "stroke")[key];
+    return given === undefined ? fallback : (toPx({ [key]: given })[key] ?? fallback);
+};
+const sequentialOf = (doc, theme) => {
+    const given = Object.entries(readOptionalGroup(doc, "chartSequential"))
+        .sort(([a], [b]) => Number(a) - Number(b))
+        .map(([name, value]) => colourOf(value, `chartSequential.${name}`));
+    if (given.length === 0)
+        return rampOf(theme);
+    if (given.length !== RAMP_STEPS) {
+        throw new Error(`chartSequential needs ${RAMP_STEPS} steps, got ${given.length}`);
+    }
+    return given;
+};
+const shadowOf = (doc, theme) => {
+    const group = readOptionalGroup(doc, "shadow");
+    return {
+        mode: oneOf(group.mode ?? "none", SHADOW_MODES, "shadow.mode"),
+        color: group.color === undefined
+            ? (theme.colors.fg ?? FALLBACK_INK)
+            : colourOf(group.color, "shadow.color"),
+    };
+};
+const grainOf = (doc) => {
+    const grain = numberAt(readOptionalGroup(doc, "grain"), "opacity", 0);
+    if (grain < 0 || grain > GRAIN_MAX) {
+        throw new Error(`token "grain.opacity" must be 0..${GRAIN_MAX}`);
+    }
+    return grain;
+};
+/**
+ * Reads the optional token groups of a DTCG theme document (`status`, `stroke`, `shadow`, `grain`,
+ * `chartSequential`, `numeric`; `font.display` arrives through `theme.fonts`) and fills the rest from
+ * `theme`. Pure; throws on a malformed token.
+ */
+export const resolveOptionalTokens = (theme, doc) => {
+    const status = readOptionalGroup(doc, "status");
+    return {
+        fontDisplay: theme.fonts.display ?? theme.fonts.sans ?? "system-ui, sans-serif",
+        status: {
+            good: statusColour(status, "good", theme),
+            warn: statusColour(status, "warn", theme),
+            bad: statusColour(status, "bad", theme),
+        },
+        stroke: { card: strokeOf(doc, "card", 0), icon: strokeOf(doc, "icon", 1.75) },
+        shadow: shadowOf(doc, theme),
+        grainOpacity: grainOf(doc),
+        chartSequential: sequentialOf(doc, theme),
+        numeric: oneOf(readOptionalGroup(doc, "numeric").mode ?? "tabular", NUMERIC_MODES, "numeric.mode"),
+    };
+};
+const SHADOW_SOFT = "0 24px 56px -28px";
+const SHADOW_HARD = "8px 8px 0";
+const SHADOW_SOFT_MIX = 40;
+const GRAIN_TILE = 256;
+const GRAIN_FREQUENCY = 0.8;
+const GRAIN_SEED = 7;
+const shadowValue = ({ mode, color }) => {
+    if (mode === "none")
+        return "none";
+    if (mode === "hard")
+        return `${SHADOW_HARD} ${color}`;
+    return `${SHADOW_SOFT} color-mix(in srgb, ${color} ${SHADOW_SOFT_MIX}%, transparent)`;
+};
+/** Static, seeded noise tile as a percent-encoded data URI (no network, deterministic). */
+const grainImage = (opacity) => {
+    const svg = [
+        `<svg xmlns='http://www.w3.org/2000/svg' width='${GRAIN_TILE}' height='${GRAIN_TILE}'>`,
+        `<filter id='n'><feTurbulence type='fractalNoise' baseFrequency='${GRAIN_FREQUENCY}' numOctaves='2' seed='${GRAIN_SEED}' stitchTiles='stitch'/><feColorMatrix type='saturate' values='0'/></filter>`,
+        `<rect width='100%' height='100%' filter='url(#n)' opacity='${opacity}'/></svg>`,
+    ].join("");
+    return `url("data:image/svg+xml,${encodeURIComponent(svg)}")`;
+};
+/** `--mk-status-<key>` for each status colour the document declares. */
+const statusVars = (tokens, doc) => {
+    const group = readOptionalGroup(doc, "status");
+    const keys = ["good", "warn", "bad"].filter((key) => group[key] !== undefined);
+    return Object.fromEntries(keys.map((key) => [`--mk-status-${key}`, tokens.status[key]]));
+};
+/**
+ * Custom properties for the optional groups the document actually declares (`status`, `shadow`, `grain`,
+ * `stroke`, `numeric`); a group the theme omits yields nothing, so scenes keep their own fallback.
+ */
+export const optionalVars = (theme, doc) => {
+    const tokens = resolveOptionalTokens(theme, doc);
+    const vars = {};
+    const has = (group, key) => readOptionalGroup(doc, group)[key] !== undefined;
+    if (has("shadow", "mode"))
+        vars["--mk-shadow-card"] = shadowValue(tokens.shadow);
+    if (has("grain", "opacity") && tokens.grainOpacity > 0) {
+        vars["--mk-grain-image"] = grainImage(tokens.grainOpacity);
+    }
+    Object.assign(vars, statusVars(tokens, doc));
+    if (has("stroke", "card"))
+        vars["--mk-stroke-card"] = `${tokens.stroke.card}px`;
+    if (has("stroke", "icon"))
+        vars["--mk-stroke-icon"] = `${tokens.stroke.icon}px`;
+    if (has("numeric", "mode")) {
+        vars["--mk-numeric"] = tokens.numeric === "tabular" ? "tabular-nums" : "normal";
+    }
+    return vars;
+};