@clhaas/palette-kit 0.3.0 → 0.4.0

package/src/contrast/wcag2.ts

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

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

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

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

package/src/core/onSolid.test.ts

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

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

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

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

@@ -1,22 +0,0 @@
-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;
-}