@clhaas/palette-kit 0.1.7 → 0.3.0

package/src/contrast/wcag2.ts

@@ -0,0 +1,24 @@
+import type { SrgbColor } from "./types.js";
+
+const clamp01 = (value: number) => Math.min(1, Math.max(0, value));
+
+const toLinear = (channel: number) => {
+  const value = clamp01(channel);
+  return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+};
+
+export const relativeLuminance = (color: SrgbColor): number => {
+  const r = toLinear(color.r);
+  const g = toLinear(color.g);
+  const b = toLinear(color.b);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+
+export const contrastRatio = (fg: SrgbColor, bg: SrgbColor): number => {
+  const fgLum = relativeLuminance(fg);
+  const bgLum = relativeLuminance(bg);
+  const lighter = Math.max(fgLum, bgLum);
+  const darker = Math.min(fgLum, bgLum);
+  const ratio = (lighter + 0.05) / (darker + 0.05);
+  return Number.isFinite(ratio) ? ratio : Number.NaN;
+};

package/src/core/createTheme.ts

@@ -0,0 +1,78 @@
+import { onSolid } from "../engine/onSolid.js";
+import type { BaseResolvedColor, ThemeConfig } from "../engine/resolveBaseColor.js";
+import { serializeResolved } from "../serialize/serializeColor.js";
+import type {
+  ColorContext,
+  ColorQuery,
+  ColorRole,
+  OnSolidQuery,
+  OutputOptions,
+  ResolvedColor,
+} from "../types/index.js";
+import { resolve } from "./resolve.js";
+import { resolveMany } from "./resolveMany.js";
+
+export type PaletteTheme = {
+  /**
+   * Resolve a single color query to the core OKLCH output shape.
+   */
+  resolve: (query: ColorQuery) => BaseResolvedColor;
+  /**
+   * Resolve a batch of color queries while preserving input order.
+   */
+  resolveMany: (queries: ColorQuery[]) => BaseResolvedColor[];
+  /**
+   * Resolve a color role with inference and DX validation.
+   *
+   * Inference and strict/non-strict behavior is shared with `theme.resolve(...)` and is
+   * implemented inside query normalization.
+   *
+   * When `output.strict` is true, missing inference throws an error; otherwise
+   * safe defaults are used.
+   */
+  color: (role: ColorRole, options?: Omit<ColorQuery, "role">) => BaseResolvedColor;
+  /**
+   * Resolve a foreground color against a solid background (APCA/WCAG aware).
+   */
+  onSolid: (query: OnSolidQuery) => BaseResolvedColor;
+  /**
+   * Serialize a resolved color query for external outputs (CSS, RN, JSON, etc.).
+   */
+  serialize: (query: ColorQuery, options?: OutputOptions) => ResolvedColor;
+  /**
+   * Return a new theme instance with a bound context.
+   */
+  withContext: (context: ColorContext) => PaletteTheme;
+};
+
+export function createTheme(config: ThemeConfig): PaletteTheme {
+  const themeConfig: ThemeConfig = {
+    ...config,
+    preset: config.preset ?? "modern",
+    variants: config.variants ?? {},
+  };
+
+  const applyBoundContext = <T extends { context?: ColorContext }>(
+    query: T,
+    boundContext?: ColorContext,
+  ) => (boundContext ? { context: boundContext, ...query } : query);
+
+  const buildTheme = (boundContext?: ColorContext): PaletteTheme => ({
+    resolve: (query) => resolve(applyBoundContext(query, boundContext), themeConfig),
+    resolveMany: (queries) =>
+      resolveMany(
+        queries.map((query) => applyBoundContext(query, boundContext)),
+        themeConfig,
+      ),
+    color: (role, options) =>
+      resolve(applyBoundContext({ role, ...(options ?? {}) }, boundContext), themeConfig),
+    onSolid: (query) => onSolid(applyBoundContext(query, boundContext), themeConfig),
+    serialize: (query, options) => {
+      const resolved = resolve(applyBoundContext(query, boundContext), themeConfig);
+      return serializeResolved(resolved, options);
+    },
+    withContext: (context) => buildTheme(context),
+  });
+
+  return buildTheme();
+}

package/src/core/dx-helpers.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from "vitest";
+
+import { createTheme } from "./createTheme.js";
+import type { ColorQuery } from "../types/index.js";
+
+describe("Phase 2 helpers", () => {
+  const theme = createTheme({
+    seeds: {
+      light: { neutral: "#8B8D98", accent: "#3D63DD" },
+      dark: { neutral: "#8B8D98", accent: "#3D63DD" },
+    },
+    preset: "modern",
+  });
+
+  it("resolveMany preserves input order", () => {
+    const queries: ColorQuery[] = [
+      { role: "bg.app", usage: "bg", surface: "app", context: "light" },
+      { role: "text.primary", usage: "text", surface: "surface", context: "light" },
+    ];
+
+    const expected = queries.map((query) => theme.resolve(query));
+    const results = theme.resolveMany(queries);
+
+    expect(results.map((result) => result.step)).toEqual(expected.map((result) => result.step));
+    expect(results.map((result) => result.seedUsed)).toEqual(
+      expected.map((result) => result.seedUsed),
+    );
+  });
+
+  it("withContext applies bound context and allows overrides", () => {
+    const darkTheme = theme.withContext("dark");
+    const bound = darkTheme.resolve({ role: "bg.app", usage: "bg", surface: "app" });
+    const explicit: ColorQuery = {
+      role: "bg.app",
+      usage: "bg",
+      surface: "app",
+      context: "dark",
+    };
+    const explicitResolved = theme.resolve(explicit);
+
+    expect(bound.step).toBe(explicitResolved.step);
+
+    const override = darkTheme.resolve({
+      role: "bg.app",
+      usage: "bg",
+      surface: "app",
+      context: "light",
+    });
+    const light: ColorQuery = {
+      role: "bg.app",
+      usage: "bg",
+      surface: "app",
+      context: "light",
+    };
+    const lightResolved = theme.resolve(light);
+
+    expect(override.step).toBe(lightResolved.step);
+  });
+
+  it("theme.color infers usage and surface from role", () => {
+    const inferred = theme.color("bg.app");
+    const explicit = theme.resolve({ role: "bg.app", usage: "bg", surface: "app" });
+
+    expect(inferred.step).toBe(explicit.step);
+    expect(inferred.seedUsed).toBe(explicit.seedUsed);
+  });
+
+  it("theme.color throws in strict mode when inference is missing", () => {
+    expect(() =>
+      theme.color("custom.role", {
+        output: { strict: true },
+      }),
+    ).toThrow(/Usage is required for role/i);
+
+    expect(() =>
+      theme.color("text.custom", {
+        output: { strict: true },
+      }),
+    ).toThrow(/Surface is required for role/i);
+  });
+
+});

package/src/core/index.ts

@@ -0,0 +1,7 @@
+export { createTheme } from "./createTheme.js";
+export {
+  resolveToken,
+  resolveTokenRegistry,
+  validateTokenDefinition,
+  validateTokenRegistry,
+} from "./tokenRegistry.js";

package/src/core/onSolid.test.ts

@@ -0,0 +1,146 @@
+import { describe, expect, it, vi } from "vitest";
+
+import * as apca from "../contrast/apca.js";
+import { blendSrgb, toSrgbColor } from "../contrast/utils.js";
+import type { OkLchColor } from "../engine/generateScale.js";
+import * as operators from "../engine/applyOperators.js";
+import { createTheme } from "./createTheme.js";
+
+const passesApca = (fg: OkLchColor, bg: OkLchColor, targetLc: number, alpha = 1) => {
+  const fgSrgb = toSrgbColor(fg);
+  const bgSrgb = toSrgbColor(bg);
+
+  if (!fgSrgb || !bgSrgb) {
+    return false;
+  }
+
+  const composite = blendSrgb(fgSrgb, bgSrgb, alpha);
+  const value = Math.abs(apca.computeApcaLc(composite, bgSrgb));
+  return value >= targetLc;
+};
+
+const theme = createTheme({
+  seeds: {
+    light: { neutral: "#8B8D98", accent: "#3D63DD" },
+    dark: { neutral: "#8B8D98", accent: "#3D63DD" },
+  },
+  preset: "modern",
+});
+
+describe("onSolid", () => {
+  it("chooses a white-ish foreground on dark solids", () => {
+    const bg = theme.resolve({
+      role: "action.primary",
+      usage: "bg",
+      surface: "solid",
+      context: "dark",
+    });
+    const result = theme.onSolid({
+      bgRole: "action.primary",
+      usage: "text",
+      context: "dark",
+    });
+
+    expect(bg.oklch.l).toBeLessThan(50);
+    expect(result.oklch.l).toBeGreaterThan(50);
+    expect(passesApca(result.oklch, bg.oklch, 75, result.oklch.alpha ?? 1)).toBe(true);
+  });
+
+  it("chooses a black-ish foreground on light solids", () => {
+    const bg = theme.resolve({
+      role: "action.primary",
+      usage: "bg",
+      surface: "solid",
+      context: "light",
+    });
+    const result = theme.onSolid({
+      bgRole: "action.primary",
+      usage: "icon",
+      context: "light",
+    });
+
+    expect(bg.oklch.l).toBeGreaterThanOrEqual(50);
+    expect(result.oklch.l).toBeLessThan(50);
+    expect(passesApca(result.oklch, bg.oklch, 60, result.oklch.alpha ?? 1)).toBe(true);
+  });
+
+  it("raises alpha to 1 when needed for contrast", () => {
+    const bg = theme.resolve({
+      role: "action.primary",
+      usage: "bg",
+      surface: "solid",
+      context: "dark",
+    });
+    const result = theme.onSolid({
+      bgRole: "action.primary",
+      usage: "icon",
+      context: "dark",
+      contrast: { model: "apca", targetLc: 90 },
+    });
+
+    expect(result.oklch.alpha).toBe(1);
+    expect(passesApca(result.oklch, bg.oklch, 90, 1)).toBe(true);
+    expect(passesApca(result.oklch, bg.oklch, 90, 0.72)).toBe(false);
+  });
+
+  it("throws in strict mode when contrast is impossible", () => {
+    expect(() =>
+      theme.onSolid({
+        bgRole: "action.primary",
+        usage: "text",
+        context: "light",
+        contrast: { model: "apca", targetLc: 140 },
+        output: { strict: true },
+      }),
+    ).toThrow(/onSolid contrast failed|Contrast solver failed/i);
+  });
+
+  it("accepts results within epsilon for strict checks", () => {
+    const spy = vi.spyOn(apca, "computeApcaLc").mockImplementation(() => 74.995);
+
+    try {
+      expect(() =>
+        theme.onSolid({
+          bgRole: "action.primary",
+          usage: "text",
+          context: "light",
+          contrast: { model: "apca", targetLc: 75 },
+          output: { strict: true },
+        }),
+      ).not.toThrow();
+    } finally {
+      spy.mockRestore();
+    }
+  });
+
+  it("keeps alpha at 1 when mode is none", () => {
+    const result = theme.onSolid({
+      bgRole: "action.primary",
+      usage: "text",
+      context: "dark",
+      alpha: { mode: "none" },
+    });
+
+    expect(result.oklch.alpha).toBe(1);
+  });
+
+  it("applies state and emphasis to the background before solving", () => {
+    const spy = vi.spyOn(operators, "applyOperators");
+
+    theme.onSolid({
+      bgRole: "action.primary",
+      usage: "text",
+      context: "light",
+      state: "hover",
+      emphasis: "strong",
+    });
+
+    expect(spy).toHaveBeenCalledWith(
+      expect.any(Object),
+      expect.objectContaining({ state: "hover", emphasis: "strong" }),
+      expect.any(Object),
+    );
+
+    spy.mockRestore();
+  });
+});

package/src/core/qa.v1.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, it } from "vitest";
+
+import { serializeColor } from "../export/serializeColor.js";
+import { createTheme } from "./createTheme.js";
+
+const buildTheme = () =>
+  createTheme({
+    seeds: {
+      light: { neutral: "#111827", accent: "#3d63dd" },
+      dark: { neutral: "#111827", accent: "#3d63dd" },
+    },
+  });
+
+const toOklchString = (oklch: { l: number; c: number; h: number; alpha?: number }) =>
+  serializeColor(oklch, { preferSpace: "oklch", includeMeta: true });
+
+describe("QA v1", () => {
+  it("resolves light/dark background without NaNs", () => {
+    const theme = buildTheme();
+
+    const light = theme.resolve({
+      role: "bg.app",
+      usage: "bg",
+      context: "light",
+      surface: "app",
+    });
+    const dark = theme.resolve({
+      role: "bg.app",
+      usage: "bg",
+      context: "dark",
+      surface: "app",
+    });
+
+    const lightSerialized = toOklchString(light.oklch);
+    const darkSerialized = toOklchString(dark.oklch);
+
+    expect(typeof lightSerialized.value).toBe("string");
+    expect(lightSerialized.value.includes("oklch(")).toBe(true);
+    expect(Number.isFinite(lightSerialized.alpha)).toBe(true);
+    expect(lightSerialized.alpha).toBeGreaterThanOrEqual(0);
+    expect(lightSerialized.alpha).toBeLessThanOrEqual(1);
+
+    expect(typeof darkSerialized.value).toBe("string");
+    expect(darkSerialized.value.includes("oklch(")).toBe(true);
+    expect(Number.isFinite(darkSerialized.alpha)).toBe(true);
+    expect(darkSerialized.alpha).toBeGreaterThanOrEqual(0);
+    expect(darkSerialized.alpha).toBeLessThanOrEqual(1);
+  });
+
+  it("solves primary/secondary text on solid backgrounds", () => {
+    const theme = buildTheme();
+
+    const primary = theme.onSolid({
+      bgRole: "action.primary",
+      usage: "text",
+      context: "light",
+      contrast: { model: "apca", targetLc: 75 },
+    });
+    const secondary = theme.onSolid({
+      bgRole: "action.primary",
+      usage: "text",
+      context: "light",
+      contrast: { model: "apca", targetLc: 60 },
+    });
+
+    const primarySerialized = toOklchString(primary.oklch);
+    const secondarySerialized = toOklchString(secondary.oklch);
+
+    expect(primarySerialized.value).not.toBe("");
+    expect(primarySerialized.alpha).toBeGreaterThanOrEqual(0);
+    expect(primarySerialized.alpha).toBeLessThanOrEqual(1);
+
+    expect(secondarySerialized.value).not.toBe("");
+    expect(secondarySerialized.alpha).toBeGreaterThanOrEqual(0);
+    expect(secondarySerialized.alpha).toBeLessThanOrEqual(1);
+  });
+
+  it("handles solid button states and onSolid text", () => {
+    const theme = buildTheme();
+    const base = {
+      role: "action.primary",
+      usage: "bg" as const,
+      surface: "solid" as const,
+      context: "light" as const,
+    };
+
+    const states = ["default", "hover", "active"] as const;
+    const serializedStates = states.map((state) =>
+      toOklchString(theme.resolve({ ...base, state }).oklch).value,
+    );
+
+    serializedStates.forEach((value) => {
+      expect(value.startsWith("oklch(")).toBe(true);
+    });
+
+    const onSolidText = toOklchString(
+      theme.onSolid({ bgRole: "action.primary", usage: "text", context: "light" }).oklch,
+    );
+
+    expect(onSolidText.alpha).toBeGreaterThanOrEqual(0.85);
+    expect(onSolidText.alpha).toBeLessThanOrEqual(1);
+  });
+
+  it("produces a distinct focus ring color with meta", () => {
+    const theme = buildTheme();
+
+    const ring = toOklchString(
+      theme.resolve({
+        role: "focus.ring",
+        variant: "accent",
+        usage: "ring",
+        context: "light",
+        surface: "surface",
+        contrast: { model: "apca", targetLc: 45 },
+      }).oklch,
+    );
+
+    const surface = toOklchString(
+      theme.resolve({
+        role: "surface.card",
+        usage: "bg",
+        context: "light",
+        surface: "surface",
+      }).oklch,
+    );
+
+    expect(ring.value).not.toBe(surface.value);
+    expect(ring.meta?.gamutMapping).toBeDefined();
+  });
+
+  it("keeps overlay scrim alpha stable", () => {
+    const theme = buildTheme();
+
+    const scrim = toOklchString(
+      theme.resolve({
+        role: "overlay.scrim",
+        usage: "bg",
+        surface: "overlay",
+        context: "dark",
+        alpha: { mode: "fixed", alpha: 0.55 },
+      }).oklch,
+    );
+
+    expect(scrim.alpha).toBeGreaterThanOrEqual(0);
+    expect(scrim.alpha).toBeLessThanOrEqual(1);
+    expect(scrim.value.includes("oklch(")).toBe(true);
+    expect(scrim.value.includes("NaN")).toBe(false);
+  });
+});

package/src/core/resolve.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "vitest";
+
+import { createTheme } from "./createTheme.js";
+
+const theme = createTheme({
+  seeds: {
+    light: { neutral: "#8B8D98", accent: "#3D63DD" },
+    dark: { neutral: "#8B8D98", accent: "#3D63DD" },
+  },
+  preset: "modern",
+});
+
+describe("resolve", () => {
+  it("applies state operators via theme.resolve", () => {
+    const baseLight = theme.resolve({
+      role: "bg.solid",
+      usage: "bg",
+      surface: "solid",
+      context: "light",
+    });
+    const hoverLight = theme.resolve({
+      role: "bg.solid",
+      usage: "bg",
+      surface: "solid",
+      context: "light",
+      state: "hover",
+    });
+    const baseDark = theme.resolve({
+      role: "bg.solid",
+      usage: "bg",
+      surface: "solid",
+      context: "dark",
+    });
+    const hoverDark = theme.resolve({
+      role: "bg.solid",
+      usage: "bg",
+      surface: "solid",
+      context: "dark",
+      state: "hover",
+    });
+    const activeDark = theme.resolve({
+      role: "bg.solid",
+      usage: "bg",
+      surface: "solid",
+      context: "dark",
+      state: "active",
+    });
+    const activeLight = theme.resolve({
+      role: "bg.solid",
+      usage: "bg",
+      surface: "solid",
+      context: "light",
+      state: "active",
+    });
+    const disabledLight = theme.resolve({
+      role: "bg.solid",
+      usage: "bg",
+      surface: "solid",
+      context: "light",
+      state: "disabled",
+    });
+    const disabledDark = theme.resolve({
+      role: "bg.solid",
+      usage: "bg",
+      surface: "solid",
+      context: "dark",
+      state: "disabled",
+    });
+
+    expect(hoverLight.oklch.l).toBeLessThan(baseLight.oklch.l);
+    expect(hoverDark.oklch.l).toBeGreaterThan(baseDark.oklch.l);
+    expect(Math.abs(activeLight.oklch.l - baseLight.oklch.l)).toBeGreaterThan(
+      Math.abs(hoverLight.oklch.l - baseLight.oklch.l),
+    );
+    expect(Math.abs(activeDark.oklch.l - baseDark.oklch.l)).toBeGreaterThan(
+      Math.abs(hoverDark.oklch.l - baseDark.oklch.l),
+    );
+    expect(disabledLight.oklch.c).toBeLessThan(baseLight.oklch.c * 0.6);
+    expect(disabledDark.oklch.c).toBeLessThan(baseDark.oklch.c * 0.6);
+  });
+
+  it("applies emphasis via theme.resolve", () => {
+    const base = theme.resolve({
+      role: "text.primary",
+      usage: "text",
+      surface: "surface",
+      context: "light",
+    });
+    const muted = theme.resolve({
+      role: "text.primary",
+      usage: "text",
+      surface: "surface",
+      context: "light",
+      emphasis: "muted",
+    });
+
+    expect(muted.oklch.c).toBeLessThan(base.oklch.c);
+  });
+});

package/src/core/resolve.ts

@@ -0,0 +1,11 @@
+import { applyOperators } from "../engine/applyOperators.js";
+import { normalizeQuery } from "../engine/normalize.js";
+import type { BaseResolvedColor, ThemeConfig } from "../engine/resolveBaseColor.js";
+import { resolveBaseColor } from "../engine/resolveBaseColor.js";
+import type { ColorQuery } from "../types/index.js";
+
+export function resolve(query: ColorQuery, theme: ThemeConfig): BaseResolvedColor {
+  const normalized = normalizeQuery(query);
+  const base = resolveBaseColor(normalized, theme);
+  return applyOperators(base, normalized, theme);
+}

package/src/core/resolveMany.ts

@@ -0,0 +1,22 @@
+import { applyOperators } from "../engine/applyOperators.js";
+import { normalizeQuery } from "../engine/normalize.js";
+import type { BaseResolvedColor, ThemeConfig } from "../engine/resolveBaseColor.js";
+import { resolveBaseColor } from "../engine/resolveBaseColor.js";
+import type { ColorQuery } from "../types/index.js";
+
+/**
+ * Resolve a batch of color queries while preserving input order.
+ *
+ * Convenience helper to resolve multiple color queries in a single call.
+ */
+export function resolveMany(queries: ColorQuery[], theme: ThemeConfig): BaseResolvedColor[] {
+  const results: BaseResolvedColor[] = [];
+
+  for (const query of queries) {
+    const normalized = normalizeQuery(query);
+    const base = resolveBaseColor(normalized, theme);
+    results.push(applyOperators(base, normalized, theme));
+  }
+
+  return results;
+}