@clhaas/palette-kit 0.1.8 → 0.3.0

package/src/core/tokenRegistry.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from "vitest";
+
+import { createTheme } from "./createTheme.js";
+import { resolveToken, resolveTokenRegistry, validateTokenRegistry } from "./tokenRegistry.js";
+import type { TokenRegistry } from "../types/index.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: TokenRegistry = {
+      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: TokenRegistry = {
+      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: TokenRegistry = {
+      tokens: {
+        "bg.app": {
+          name: "bg.app",
+          query: {
+            role: "bg.app",
+            usage: "bg",
+            surface: "app",
+            output: { strict: true },
+          } as never,
+        },
+      },
+    };
+
+    expect(() => validateTokenRegistry(registry)).toThrow(/must not include output/i);
+  });
+
+  it("treats whitespace-padded default state as default", () => {
+    const registry: TokenRegistry = {
+      tokens: {
+        "bg.app": {
+          name: "bg.app",
+          query: {
+            role: "bg.app",
+            usage: "bg",
+            surface: "app",
+            state: " default " as never,
+          } as never,
+        },
+      },
+    };
+
+    expect(() => validateTokenRegistry(registry)).not.toThrow();
+  });
+
+  it("throws when token query encodes a non-default state", () => {
+    const registry: TokenRegistry = {
+      tokens: {
+        "bg.app": {
+          name: "bg.app",
+          query: { role: "bg.app", usage: "bg", surface: "app", state: "hover" as never } as never,
+        },
+      },
+    };
+
+    expect(() => validateTokenRegistry(registry)).toThrow(/must not encode state/i);
+  });
+
+  it("throws when token query includes a literal background color hint", () => {
+    const registry: TokenRegistry = {
+      tokens: {
+        "bg.app": {
+          name: "bg.app",
+          query: {
+            role: "bg.app",
+            usage: "bg",
+            surface: "app",
+            on: { kind: "color", value: "#fff" } as never,
+          },
+        },
+      },
+    };
+
+    expect(() => validateTokenRegistry(registry)).toThrow(/literal background color/i);
+  });
+
+  it("throws when token states include invalid keys or non-true values", () => {
+    const invalidKey: TokenRegistry = {
+      tokens: {
+        "bg.app": {
+          name: "bg.app",
+          query: { role: "bg.app", usage: "bg", surface: "app" },
+          states: { nope: true } as never,
+        },
+      },
+    };
+    expect(() => validateTokenRegistry(invalidKey)).toThrow(/Invalid token state/i);
+
+    const includesDefault: TokenRegistry = {
+      tokens: {
+        "bg.app": {
+          name: "bg.app",
+          query: { role: "bg.app", usage: "bg", surface: "app" },
+          states: { default: true } as never,
+        },
+      },
+    };
+    expect(() => validateTokenRegistry(includesDefault)).toThrow(/Invalid token state/i);
+
+    const nonTrueValue: TokenRegistry = {
+      tokens: {
+        "bg.app": {
+          name: "bg.app",
+          query: { role: "bg.app", usage: "bg", surface: "app" },
+          states: { hover: false } as never,
+        },
+      },
+    };
+    expect(() => validateTokenRegistry(nonTrueValue)).toThrow(/must be true/i);
+  });
+});

package/src/core/tokenRegistry.ts

@@ -0,0 +1,114 @@
+import { COLOR_STATES, normalizeQuery } from "../engine/normalize.js";
+import type { BaseResolvedColor } from "../engine/resolveBaseColor.js";
+import type { TokenDefinition, TokenRegistry, TokenState } from "../types/index.js";
+import type { PaletteTheme } from "./createTheme.js";
+
+const ALLOWED_TOKEN_STATES: TokenState[] = COLOR_STATES.filter(
+  (state): state is TokenState => state !== "default",
+);
+
+const validateTokenStates = (states: TokenDefinition["states"], name: string) => {
+  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 as TokenState)) {
+      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: TokenDefinition): void => {
+  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 as { state?: unknown }).state;
+  const normalizedState = typeof rawState === "string" ? rawState.trim() : (rawState as undefined);
+  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 as { kind?: string } | undefined)?.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: TokenRegistry): void => {
+  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: TokenDefinition, theme: PaletteTheme): BaseResolvedColor => {
+  validateTokenDefinition(token);
+  return theme.resolve(token.query);
+};
+
+/**
+ * Resolve all tokens in a registry while preserving key order.
+ */
+export const resolveTokenRegistry = (
+  registry: TokenRegistry,
+  theme: PaletteTheme,
+): Record<string, BaseResolvedColor> => {
+  validateTokenRegistry(registry);
+  const resolved: Record<string, BaseResolvedColor> = {};
+
+  for (const [name, token] of Object.entries(registry.tokens)) {
+    resolved[name] = theme.resolve(token.query);
+  }
+
+  return resolved;
+};

package/src/engine/applyOperators.ts

@@ -0,0 +1,32 @@
+import { applyEmphasisOperator } from "../operators/emphasis.js";
+import { applyStateOperator } from "../operators/state.js";
+import { mapColorContextToEngine } from "./context.js";
+import type { NormalizedQuery } from "./normalize.js";
+import type { BaseResolvedColor, ThemeConfig } from "./resolveBaseColor.js";
+
+export const applyOperators = (
+  base: BaseResolvedColor,
+  normalized: NormalizedQuery,
+  theme: ThemeConfig,
+): BaseResolvedColor => {
+  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/src/engine/context.ts

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

package/src/engine/gamut.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, it } from "vitest";
+
+import { isInGamut, mapToGamut } from "./gamut.js";
+import type { OkLchColor } from "./generateScale.js";
+
+describe("gamut mapping", () => {
+  const outOfSrgbInP3: OkLchColor = { 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/src/engine/gamut.ts

@@ -0,0 +1,144 @@
+import { clampChroma, converter } from "culori";
+
+import type { OutputOptions } from "../types/index.js";
+import { clamp } from "../utils/clamp.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 };
+type CuloriOklch = { mode: "oklch"; l: number; c: number; h: number; alpha?: number };
+
+const toRgb = converter("rgb");
+const toP3 = converter("p3");
+const toOklch = converter("oklch");
+
+const normalizeHue = (hue: number) => ((hue % 360) + 360) % 360;
+
+const toCuloriOklch = (color: OkLchColor): CuloriOklch => ({
+  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?: number; c?: number; h?: number; alpha?: number }) => ({
+  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: number) => Math.min(1, Math.max(0, value));
+
+const toTargetRgb = (color: OkLchColor, target: GamutTarget): GamutRgb | null => {
+  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: GamutRgb, target: GamutTarget) => {
+  const converted = toOklch({
+    mode: (target === "p3" ? "p3" : "rgb") as "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: GamutRgb | null) =>
+  !!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: OkLchColor): OkLchColor => ({
+  l: 0,
+  c: 0,
+  h: 0,
+  alpha: color.alpha ?? 1,
+});
+
+export const isInGamut = (color: OkLchColor, target: GamutTarget): boolean =>
+  inGamut(toTargetRgb(color, target));
+
+export const mapToGamut = (
+  color: OkLchColor,
+  target: GamutTarget,
+  mapping: GamutMapping,
+  strict: boolean,
+): OkLchColor => {
+  // 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: OkLchColor, target: GamutTarget): GamutRgb | null =>
+  toTargetRgb(color, target);

package/src/engine/generateScale.test.ts

@@ -0,0 +1,46 @@
+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: number[]) =>
+  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/src/engine/generateScale.ts

@@ -0,0 +1,48 @@
+import type { CurvePresetName } from "../presets/index.js";
+import { curvePresets } from "../presets/index.js";
+import type { SurfaceIntent } from "../types/index.js";
+import { clamp } from "../utils/clamp.js";
+import { lerp } from "../utils/lerp.js";
+
+export type OkLchColor = {
+  l: number;
+  c: number;
+  h: number;
+  alpha?: number;
+};
+
+type GenerateScaleOptions = {
+  context: "light" | "dark";
+  surface: SurfaceIntent;
+  preset?: CurvePresetName;
+};
+
+const STEPS = 12;
+const OKLCH_L_MIN = 0;
+const OKLCH_L_MAX = 100;
+
+export function generateScale(seed: OkLchColor, options: GenerateScaleOptions): OkLchColor[] {
+  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/src/engine/index.ts

@@ -0,0 +1,8 @@
+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";