@clhaas/palette-kit 0.3.0 → 0.4.0

package/src/core/tokenRegistry.test.ts

@@ -1,153 +0,0 @@
-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

@@ -1,114 +0,0 @@
-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

@@ -1,32 +0,0 @@
-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

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

@@ -1,30 +0,0 @@
-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

@@ -1,144 +0,0 @@
-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

@@ -1,46 +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: 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

@@ -1,48 +0,0 @@
-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

@@ -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";