@clhaas/palette-kit 0.3.0 → 0.4.0

package/dist/core/tokenRegistry.js

@@ -1,83 +0,0 @@
-import { COLOR_STATES, normalizeQuery } from "../engine/normalize.js";
-const ALLOWED_TOKEN_STATES = COLOR_STATES.filter((state) => state !== "default");
-const validateTokenStates = (states, name) => {
-    if (!states)
-        return;
-    for (const [state, enabled] of Object.entries(states)) {
-        if (enabled !== true) {
-            throw new Error(`Token "${name}" state "${state}" must be true`);
-        }
-        if (!ALLOWED_TOKEN_STATES.includes(state)) {
-            throw new Error(`Invalid token state "${state}" for "${name}"`);
-        }
-    }
-};
-/**
- * Validate a token definition for safe registry usage.
- *
- * Guarantees (Phase 3):
- * - registry stays declarative (no output options / no embedded color literals)
- * - tokens are base tokens (interactive states declared via `token.states`)
- */
-export const validateTokenDefinition = (token) => {
-    if (typeof token.name !== "string" || !token.name.trim()) {
-        throw new Error("Token name is required");
-    }
-    if (typeof token.query?.role !== "string" || !token.query.role.trim()) {
-        throw new Error(`Token "${token.name}" requires a query role`);
-    }
-    if (!token.query.usage) {
-        throw new Error(`Token "${token.name}" requires a usage`);
-    }
-    if (!token.query.surface) {
-        throw new Error(`Token "${token.name}" requires a surface`);
-    }
-    const rawState = token.query.state;
-    const normalizedState = typeof rawState === "string" ? rawState.trim() : rawState;
-    if (normalizedState && normalizedState !== "default") {
-        throw new Error(`Token "${token.name}" must not encode state in query; declare supported states via token.states`);
-    }
-    const onKind = token.query.on?.kind;
-    if (onKind === "color") {
-        throw new Error(`Token "${token.name}" must not include a literal background color hint; use { kind: "role" } or { kind: "auto" }`);
-    }
-    if (token.query.output) {
-        throw new Error(`Token "${token.name}" must not include output options`);
-    }
-    validateTokenStates(token.states, token.name);
-    // Delegate to core validation for strict field validation.
-    normalizeQuery({ ...token.query, output: { strict: true } });
-};
-/**
- * Validate a token registry and each token definition it contains.
- */
-export const validateTokenRegistry = (registry) => {
-    const entries = Object.entries(registry.tokens);
-    if (entries.length === 0) {
-        throw new Error("Token registry must include at least one token");
-    }
-    for (const [name, token] of entries) {
-        if (token.name !== name) {
-            throw new Error(`Token name mismatch: expected "${name}", got "${token.name}"`);
-        }
-        validateTokenDefinition(token);
-    }
-};
-/**
- * Resolve a token definition through the provided theme.
- */
-export const resolveToken = (token, theme) => {
-    validateTokenDefinition(token);
-    return theme.resolve(token.query);
-};
-/**
- * Resolve all tokens in a registry while preserving key order.
- */
-export const resolveTokenRegistry = (registry, theme) => {
-    validateTokenRegistry(registry);
-    const resolved = {};
-    for (const [name, token] of Object.entries(registry.tokens)) {
-        resolved[name] = theme.resolve(token.query);
-    }
-    return resolved;
-};

package/dist/core/tokenRegistry.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/core/tokenRegistry.test.js

@@ -1,133 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { createTheme } from "./createTheme.js";
-import { resolveToken, resolveTokenRegistry, validateTokenRegistry } from "./tokenRegistry.js";
-describe("token registry", () => {
-    const theme = createTheme({
-        seeds: {
-            light: { neutral: "#8B8D98", accent: "#3D63DD" },
-            dark: { neutral: "#8B8D98", accent: "#3D63DD" },
-        },
-        preset: "modern",
-    });
-    it("validates tokens and resolves through theme.resolve", () => {
-        const registry = {
-            tokens: {
-                "bg.app": {
-                    name: "bg.app",
-                    description: "App background",
-                    category: "background",
-                    query: { role: "bg.app", usage: "bg", surface: "app" },
-                    states: { hover: true },
-                },
-            },
-        };
-        validateTokenRegistry(registry);
-        const resolved = resolveTokenRegistry(registry, theme);
-        expect(resolved["bg.app"].step).toBeGreaterThan(0);
-        const single = resolveToken(registry.tokens["bg.app"], theme);
-        const expected = theme.resolve(registry.tokens["bg.app"].query);
-        expect(single.step).toBe(expected.step);
-    });
-    it("throws when required query fields are missing", () => {
-        const registry = {
-            tokens: {
-                "text.primary": {
-                    name: "text.primary",
-                    query: { role: "text.primary", usage: "text" },
-                },
-            },
-        };
-        expect(() => validateTokenRegistry(registry)).toThrow(/requires a surface/i);
-    });
-    it("throws when output options are provided", () => {
-        const registry = {
-            tokens: {
-                "bg.app": {
-                    name: "bg.app",
-                    query: {
-                        role: "bg.app",
-                        usage: "bg",
-                        surface: "app",
-                        output: { strict: true },
-                    },
-                },
-            },
-        };
-        expect(() => validateTokenRegistry(registry)).toThrow(/must not include output/i);
-    });
-    it("treats whitespace-padded default state as default", () => {
-        const registry = {
-            tokens: {
-                "bg.app": {
-                    name: "bg.app",
-                    query: {
-                        role: "bg.app",
-                        usage: "bg",
-                        surface: "app",
-                        state: " default ",
-                    },
-                },
-            },
-        };
-        expect(() => validateTokenRegistry(registry)).not.toThrow();
-    });
-    it("throws when token query encodes a non-default state", () => {
-        const registry = {
-            tokens: {
-                "bg.app": {
-                    name: "bg.app",
-                    query: { role: "bg.app", usage: "bg", surface: "app", state: "hover" },
-                },
-            },
-        };
-        expect(() => validateTokenRegistry(registry)).toThrow(/must not encode state/i);
-    });
-    it("throws when token query includes a literal background color hint", () => {
-        const registry = {
-            tokens: {
-                "bg.app": {
-                    name: "bg.app",
-                    query: {
-                        role: "bg.app",
-                        usage: "bg",
-                        surface: "app",
-                        on: { kind: "color", value: "#fff" },
-                    },
-                },
-            },
-        };
-        expect(() => validateTokenRegistry(registry)).toThrow(/literal background color/i);
-    });
-    it("throws when token states include invalid keys or non-true values", () => {
-        const invalidKey = {
-            tokens: {
-                "bg.app": {
-                    name: "bg.app",
-                    query: { role: "bg.app", usage: "bg", surface: "app" },
-                    states: { nope: true },
-                },
-            },
-        };
-        expect(() => validateTokenRegistry(invalidKey)).toThrow(/Invalid token state/i);
-        const includesDefault = {
-            tokens: {
-                "bg.app": {
-                    name: "bg.app",
-                    query: { role: "bg.app", usage: "bg", surface: "app" },
-                    states: { default: true },
-                },
-            },
-        };
-        expect(() => validateTokenRegistry(includesDefault)).toThrow(/Invalid token state/i);
-        const nonTrueValue = {
-            tokens: {
-                "bg.app": {
-                    name: "bg.app",
-                    query: { role: "bg.app", usage: "bg", surface: "app" },
-                    states: { hover: false },
-                },
-            },
-        };
-        expect(() => validateTokenRegistry(nonTrueValue)).toThrow(/must be true/i);
-    });
-});

package/dist/engine/applyOperators.d.ts

@@ -1,3 +0,0 @@
-import type { NormalizedQuery } from "./normalize.js";
-import type { BaseResolvedColor, ThemeConfig } from "./resolveBaseColor.js";
-export declare const applyOperators: (base: BaseResolvedColor, normalized: NormalizedQuery, theme: ThemeConfig) => BaseResolvedColor;

package/dist/engine/applyOperators.js

@@ -1,23 +0,0 @@
-import { applyEmphasisOperator } from "../operators/emphasis.js";
-import { applyStateOperator } from "../operators/state.js";
-import { mapColorContextToEngine } from "./context.js";
-export const applyOperators = (base, normalized, theme) => {
-    const context = mapColorContextToEngine(normalized.context);
-    const operatorInput = {
-        oklch: base.oklch,
-        context,
-        surface: normalized.surface,
-        usage: normalized.usage,
-        state: normalized.state,
-        emphasis: normalized.emphasis,
-        preset: theme.preset,
-        step: base.step,
-    };
-    // Emphasis defines the baseline hierarchy; state applies transient interaction.
-    const emphasized = applyEmphasisOperator(operatorInput);
-    const stated = applyStateOperator({ ...operatorInput, oklch: emphasized });
-    return {
-        ...base,
-        oklch: stated,
-    };
-};

package/dist/engine/context.d.ts

@@ -1,4 +0,0 @@
-import type { ColorContext } from "../types/index.js";
-import type { NormalizedQuery } from "./normalize.js";
-export type EngineContext = "light" | "dark";
-export declare const mapColorContextToEngine: (context: ColorContext | NormalizedQuery["context"]) => EngineContext;

package/dist/engine/context.js

@@ -1 +0,0 @@
-export const mapColorContextToEngine = (context) => (context === "dark" || context === "dimmed" ? "dark" : "light");

package/dist/engine/gamut.d.ts

@@ -1,13 +0,0 @@
-import type { OutputOptions } from "../types/index.js";
-import type { OkLchColor } from "./generateScale.js";
-export type GamutTarget = "srgb" | "p3";
-export type GamutMapping = NonNullable<OutputOptions["gamutMapping"]>;
-type GamutRgb = {
-    r: number;
-    g: number;
-    b: number;
-};
-export declare const isInGamut: (color: OkLchColor, target: GamutTarget) => boolean;
-export declare const mapToGamut: (color: OkLchColor, target: GamutTarget, mapping: GamutMapping, strict: boolean) => OkLchColor;
-export declare const toGamutRgb: (color: OkLchColor, target: GamutTarget) => GamutRgb | null;
-export {};

package/dist/engine/gamut.js

@@ -1,101 +0,0 @@
-import { clampChroma, converter } from "culori";
-import { clamp } from "../utils/clamp.js";
-const toRgb = converter("rgb");
-const toP3 = converter("p3");
-const toOklch = converter("oklch");
-const normalizeHue = (hue) => ((hue % 360) + 360) % 360;
-const toCuloriOklch = (color) => ({
-    mode: "oklch",
-    l: clamp(color.l, 0, 100) / 100,
-    c: Math.max(0, color.c),
-    h: color.h,
-    alpha: color.alpha ?? 1,
-});
-const fromCuloriOklch = (color) => ({
-    l: clamp(typeof color.l === "number" && Number.isFinite(color.l) ? color.l * 100 : 0, 0, 100),
-    c: Math.max(0, typeof color.c === "number" && Number.isFinite(color.c) ? color.c : 0),
-    h: normalizeHue(typeof color.h === "number" && Number.isFinite(color.h) ? color.h : 0),
-    ...(typeof color.alpha === "number" ? { alpha: color.alpha } : {}),
-});
-const clamp01 = (value) => Math.min(1, Math.max(0, value));
-const toTargetRgb = (color, target) => {
-    const source = toCuloriOklch(color);
-    const rgb = target === "p3" ? toP3(source) : toRgb(source);
-    if (!rgb) {
-        return null;
-    }
-    const r = typeof rgb.r === "number" && Number.isFinite(rgb.r) ? rgb.r : Number.NaN;
-    const g = typeof rgb.g === "number" && Number.isFinite(rgb.g) ? rgb.g : Number.NaN;
-    const b = typeof rgb.b === "number" && Number.isFinite(rgb.b) ? rgb.b : Number.NaN;
-    if (!Number.isFinite(r) || !Number.isFinite(g) || !Number.isFinite(b)) {
-        return null;
-    }
-    return { r, g, b };
-};
-const toOklchFromRgb = (rgb, target) => {
-    const converted = toOklch({
-        mode: (target === "p3" ? "p3" : "rgb"),
-        r: clamp01(rgb.r),
-        g: clamp01(rgb.g),
-        b: clamp01(rgb.b),
-    });
-    if (!converted) {
-        return null;
-    }
-    return fromCuloriOklch(converted);
-};
-const GAMUT_EPSILON = 1e-6;
-const inGamut = (rgb) => !!rgb &&
-    Number.isFinite(rgb.r) &&
-    Number.isFinite(rgb.g) &&
-    Number.isFinite(rgb.b) &&
-    rgb.r >= -GAMUT_EPSILON &&
-    rgb.r <= 1 + GAMUT_EPSILON &&
-    rgb.g >= -GAMUT_EPSILON &&
-    rgb.g <= 1 + GAMUT_EPSILON &&
-    rgb.b >= -GAMUT_EPSILON &&
-    rgb.b <= 1 + GAMUT_EPSILON;
-const fallbackColor = (color) => ({
-    l: 0,
-    c: 0,
-    h: 0,
-    alpha: color.alpha ?? 1,
-});
-export const isInGamut = (color, target) => inGamut(toTargetRgb(color, target));
-export const mapToGamut = (color, target, mapping, strict) => {
-    // Note:
-    // `preferP3ThenCompress` is primarily a caller-level strategy (e.g. serializeColor prefers P3 when possible).
-    // Inside this mapper, any non-clip mapping uses chroma compression (via clampChroma) when mapping is needed.
-    const rgb = toTargetRgb(color, target);
-    if (!rgb) {
-        if (strict) {
-            throw new Error(`Unable to convert color to ${target}`);
-        }
-        return fallbackColor(color);
-    }
-    if (mapping === "clip") {
-        if (inGamut(rgb)) {
-            return color;
-        }
-        const clipped = { r: clamp01(rgb.r), g: clamp01(rgb.g), b: clamp01(rgb.b) };
-        const clippedOklch = toOklchFromRgb(clipped, target);
-        return clippedOklch
-            ? {
-                ...clippedOklch,
-                ...(typeof color.alpha === "number" ? { alpha: color.alpha } : {}),
-            }
-            : fallbackColor(color);
-    }
-    if (inGamut(rgb)) {
-        return color;
-    }
-    const clamped = clampChroma(toCuloriOklch(color), "oklch", target === "p3" ? "p3" : "rgb");
-    if (!clamped) {
-        if (strict) {
-            throw new Error(`Unable to clamp chroma for ${target}`);
-        }
-        return fallbackColor(color);
-    }
-    return fromCuloriOklch(clamped);
-};
-export const toGamutRgb = (color, target) => toTargetRgb(color, target);

package/dist/engine/gamut.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/engine/gamut.test.js

@@ -1,23 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { isInGamut, mapToGamut } from "./gamut.js";
-describe("gamut mapping", () => {
-    const outOfSrgbInP3 = { l: 60, c: 0.2, h: 40 };
-    it("detects out-of-gamut sRGB colors", () => {
-        expect(isInGamut(outOfSrgbInP3, "srgb")).toBe(false);
-        expect(isInGamut(outOfSrgbInP3, "p3")).toBe(true);
-    });
-    it("clips to sRGB gamut", () => {
-        const clipped = mapToGamut(outOfSrgbInP3, "srgb", "clip", false);
-        expect(isInGamut(clipped, "srgb")).toBe(true);
-    });
-    it("compresses chroma to sRGB gamut", () => {
-        const compressed = mapToGamut(outOfSrgbInP3, "srgb", "compressChroma", false);
-        expect(isInGamut(compressed, "srgb")).toBe(true);
-        expect(compressed.c).toBeLessThanOrEqual(outOfSrgbInP3.c);
-    });
-    it("keeps chroma when already in P3", () => {
-        const mapped = mapToGamut(outOfSrgbInP3, "p3", "preferP3ThenCompress", false);
-        expect(isInGamut(mapped, "p3")).toBe(true);
-        expect(mapped.c).toBeCloseTo(outOfSrgbInP3.c, 4);
-    });
-});

package/dist/engine/generateScale.d.ts

@@ -1,15 +0,0 @@
-import type { CurvePresetName } from "../presets/index.js";
-import type { SurfaceIntent } from "../types/index.js";
-export type OkLchColor = {
-    l: number;
-    c: number;
-    h: number;
-    alpha?: number;
-};
-type GenerateScaleOptions = {
-    context: "light" | "dark";
-    surface: SurfaceIntent;
-    preset?: CurvePresetName;
-};
-export declare function generateScale(seed: OkLchColor, options: GenerateScaleOptions): OkLchColor[];
-export {};

package/dist/engine/generateScale.js

@@ -1,29 +0,0 @@
-import { curvePresets } from "../presets/index.js";
-import { clamp } from "../utils/clamp.js";
-import { lerp } from "../utils/lerp.js";
-const STEPS = 12;
-const OKLCH_L_MIN = 0;
-const OKLCH_L_MAX = 100;
-export function generateScale(seed, options) {
-    const presetName = options.preset ?? "modern";
-    const preset = curvePresets[presetName];
-    const surfaceCurve = preset.surfaces[options.surface];
-    const range = surfaceCurve.ranges[options.context];
-    return Array.from({ length: STEPS }, (_, index) => {
-        const t = index / (STEPS - 1);
-        const lightnessT = surfaceCurve.l(t);
-        const chromaT = surfaceCurve.c(lightnessT);
-        const l = clamp(lerp(range.l[0], range.l[1], lightnessT), OKLCH_L_MIN, OKLCH_L_MAX);
-        // Allow select surfaces to exceed seed chroma slightly while staying within range caps.
-        const chromaBoost = range.chromaBoost ?? 1;
-        const boostedSeed = (seed.c ?? range.cMax) * chromaBoost;
-        const maxChroma = Math.min(range.cMax, Math.max(0, boostedSeed));
-        const c = clamp(lerp(range.cMin, maxChroma, chromaT), 0, range.cMax);
-        return {
-            l,
-            c,
-            h: seed.h,
-            alpha: seed.alpha,
-        };
-    });
-}

package/dist/engine/generateScale.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/engine/generateScale.test.js

@@ -1,32 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { generateScale } from "./generateScale.js";
-const seed = { l: 49.5, c: 0.19, h: 264.0 };
-const isMonotonic = (values) => values.every((value, index) => index === 0 || value >= values[index - 1] - 1e-6);
-describe("generateScale", () => {
-    it("returns 12 steps", () => {
-        const result = generateScale(seed, { context: "light", surface: "surface" });
-        expect(result).toHaveLength(12);
-    });
-    it("keeps lightness monotonic in light context", () => {
-        const result = generateScale(seed, { context: "light", surface: "surface" });
-        const lightness = result.map((step) => step.l);
-        expect(isMonotonic(lightness)).toBe(true);
-    });
-    it("keeps lightness monotonic in dark context", () => {
-        const result = generateScale(seed, { context: "dark", surface: "surface" });
-        const lightness = result.map((step) => step.l);
-        expect(isMonotonic(lightness)).toBe(true);
-    });
-    it("keeps hue constant across steps", () => {
-        const result = generateScale(seed, { context: "light", surface: "surface" });
-        result.forEach((step) => {
-            expect(step.h).toBeCloseTo(seed.h, 6);
-        });
-    });
-    it("never produces negative chroma", () => {
-        const result = generateScale(seed, { context: "light", surface: "surface" });
-        result.forEach((step) => {
-            expect(step.c).toBeGreaterThanOrEqual(0);
-        });
-    });
-});

package/dist/engine/index.d.ts

@@ -1,8 +0,0 @@
-export type { EngineContext } from "./context.js";
-export { mapColorContextToEngine } from "./context.js";
-export type { OkLchColor } from "./generateScale.js";
-export { generateScale } from "./generateScale.js";
-export type { NormalizedOnSolidQuery, NormalizedQuery } from "./normalize.js";
-export { normalizeOnSolidQuery, normalizeQuery } from "./normalize.js";
-export type { BaseResolvedColor, ThemeConfig } from "./resolveBaseColor.js";
-export { resolveBaseColor } from "./resolveBaseColor.js";

package/dist/engine/index.js

@@ -1,4 +0,0 @@
-export { mapColorContextToEngine } from "./context.js";
-export { generateScale } from "./generateScale.js";
-export { normalizeOnSolidQuery, normalizeQuery } from "./normalize.js";
-export { resolveBaseColor } from "./resolveBaseColor.js";

package/dist/engine/normalize.d.ts

@@ -1,43 +0,0 @@
-import type { ColorQuery, ColorState, OnSolidQuery, OutputOptions } from "../types/index.js";
-export type NormalizedQuery = Required<Pick<ColorQuery, "role" | "usage" | "context" | "surface" | "state" | "emphasis">> & {
-    variant?: ColorQuery["variant"];
-    on?: ColorQuery["on"];
-    contrast?: ColorQuery["contrast"];
-    alpha?: ColorQuery["alpha"];
-    output: Required<Omit<OutputOptions, "format">>;
-};
-export type NormalizedOnSolidQuery = Required<Pick<OnSolidQuery, "bgRole" | "usage" | "context" | "state" | "emphasis">> & {
-    alpha?: OnSolidQuery["alpha"];
-    contrast?: OnSolidQuery["contrast"];
-    output: Required<Omit<OutputOptions, "format">>;
-};
-export declare const COLOR_STATES: readonly ColorState[];
-/**
- * Normalize a user-facing ColorQuery into a fully populated, validated structure.
- *
- * - Applies defaults for missing fields (context, surface, state, emphasis, output).
- * - Infers usage and surface from role naming patterns when not provided.
- * - In strict mode, missing required fields throw actionable errors.
- * - In non-strict mode, safe defaults are applied with explicit warnings.
- * - Validates nested objects (background hints, contrast requirements, alpha strategies).
- * - Trims string inputs and enforces allowed enum values.
- *
- * @example
- * normalizeQuery({ role: "text.primary" });
- * @example
- * normalizeQuery({
- *   role: "bg.canvas",
- *   on: { kind: "color", value: "#fff" },
- *   contrast: { model: "apca", targetLc: 60 },
- *   output: { strict: true },
- * });
- */
-export declare function normalizeQuery(q: ColorQuery): NormalizedQuery;
-/**
- * Normalize a user-facing OnSolidQuery into a fully populated, validated structure.
- *
- * - Applies defaults for missing fields (context, state, emphasis, output).
- * - Validates usage ("text" | "icon") and required background role.
- * - Validates nested objects (contrast requirements, alpha strategies).
- */
-export declare function normalizeOnSolidQuery(q: OnSolidQuery): NormalizedOnSolidQuery;