@clhaas/palette-kit 0.1.8 → 0.3.0

package/src/presets/tokens/radixLike-ui.ts

@@ -0,0 +1,79 @@
+import type { TokenRegistry } from "../../types/index.js";
+
+/**
+ * Radix-like preset aligned with common component library semantics.
+ * Expands coverage for subtle/surface/solid layers and semantic text.
+ */
+export const radixLikeUiTokens: TokenRegistry = {
+  tokens: {
+    "bg.app": {
+      name: "bg.app",
+      description: "Application background for the overall canvas.",
+      category: "background",
+      query: { role: "bg.app", usage: "bg", surface: "app" },
+    },
+    "bg.surface": {
+      name: "bg.surface",
+      description: "Base surface background for cards and panels.",
+      category: "background",
+      query: { role: "bg.surface", usage: "bg", surface: "surface" },
+    },
+    "bg.subtle": {
+      name: "bg.subtle",
+      description: "Subtle background for secondary sections.",
+      category: "background",
+      query: { role: "bg.subtle", usage: "bg", surface: "subtle" },
+    },
+    "bg.solid": {
+      name: "bg.solid",
+      description: "Solid background for high-emphasis elements.",
+      category: "background",
+      query: { role: "bg.solid", usage: "bg", surface: "solid" },
+      states: { hover: true, active: true },
+    },
+    "text.primary": {
+      name: "text.primary",
+      description: "Primary text on standard surfaces.",
+      category: "text",
+      query: { role: "text.primary", usage: "text", surface: "surface" },
+    },
+    "text.secondary": {
+      name: "text.secondary",
+      description: "Secondary text for supporting content.",
+      category: "text",
+      query: { role: "text.secondary", usage: "text", surface: "surface", emphasis: "muted" },
+    },
+    "text.inverse": {
+      name: "text.inverse",
+      description: "Inverse text for solid backgrounds.",
+      category: "text",
+      query: { role: "text.inverse", usage: "text", surface: "solid", emphasis: "inverted" },
+    },
+    "border.default": {
+      name: "border.default",
+      description: "Default border for layout and surfaces.",
+      category: "border",
+      query: { role: "border.default", usage: "border", surface: "surface" },
+    },
+    "border.subtle": {
+      name: "border.subtle",
+      description: "Subtle border for separators.",
+      category: "border",
+      query: { role: "border.subtle", usage: "border", surface: "subtle" },
+    },
+    "icon.default": {
+      name: "icon.default",
+      description: "Default icon color on surfaces.",
+      category: "icon",
+      query: { role: "icon.default", usage: "icon", surface: "surface" },
+      states: { hover: true },
+    },
+    "ring.default": {
+      name: "ring.default",
+      description: "Base ring color (derive focus via state operator).",
+      category: "ring",
+      query: { role: "ring.default", usage: "ring", surface: "surface", emphasis: "strong" },
+      states: { focus: true },
+    },
+  },
+};

package/src/serialize/index.ts

@@ -0,0 +1 @@
+export { serializeColor, serializeResolved } from "./serializeColor.js";

package/src/serialize/normalizeOutput.ts

@@ -0,0 +1,63 @@
+import type { OutputOptions } from "../types/index.js";
+
+const gamutMappings: NonNullable<OutputOptions["gamutMapping"]>[] = [
+  "clip",
+  "compressChroma",
+  "preferP3ThenCompress",
+];
+
+const srgbFormats: NonNullable<OutputOptions["srgbFormat"]>[] = ["hex", "rgb", "rgba"];
+
+const formatString = (value: string | undefined) => (value ? value.trim() : undefined);
+
+const assertOneOf = <T extends string>(value: string, options: readonly T[], label: string): T => {
+  if (!options.includes(value as T)) {
+    throw new Error(`${label} must be one of: ${options.join(", ")} (received "${value}")`);
+  }
+  return value as T;
+};
+
+export type NormalizedOutput = Required<
+  Pick<OutputOptions, "preferSpace" | "includeSpaces" | "gamutMapping" | "strict" | "srgbFormat">
+> & {
+  precision: Required<NonNullable<OutputOptions["precision"]>>;
+  includeMeta: boolean;
+};
+
+export const normalizeOutput = (output?: OutputOptions): NormalizedOutput => {
+  const preferSpaceValue = formatString(output?.preferSpace);
+  const gamutMappingValue = formatString(output?.gamutMapping);
+  const srgbFormatValue = formatString(output?.srgbFormat);
+
+  const preferSpace = preferSpaceValue
+    ? assertOneOf(preferSpaceValue, ["oklch", "srgb", "p3"], "output preferSpace")
+    : "oklch";
+
+  const gamutMapping = gamutMappingValue
+    ? assertOneOf(gamutMappingValue, gamutMappings, "output gamutMapping")
+    : "preferP3ThenCompress";
+
+  const srgbFormat = srgbFormatValue
+    ? assertOneOf(srgbFormatValue, srgbFormats, "output srgbFormat")
+    : "hex";
+
+  if (output?.strict !== undefined && typeof output.strict !== "boolean") {
+    throw new Error("Output strict must be a boolean");
+  }
+
+  return {
+    preferSpace,
+    includeSpaces: output?.includeSpaces ?? [],
+    gamutMapping,
+    precision: {
+      l: 1,
+      c: 3,
+      h: 1,
+      alpha: 2,
+      ...output?.precision,
+    },
+    strict: output?.strict ?? false,
+    includeMeta: output?.includeMeta ?? false,
+    srgbFormat,
+  };
+};

package/src/serialize/serializeColor.ts

@@ -0,0 +1,260 @@
+import { formatHex, formatHex8 } from "culori";
+import { isInGamut, mapToGamut, toGamutRgb } from "../engine/gamut.js";
+import type { OkLchColor } from "../engine/generateScale.js";
+import type { BaseResolvedColor } from "../engine/resolveBaseColor.js";
+import type { ColorMeta, OutputOptions, ResolvedColor } from "../types/index.js";
+import { clamp } from "../utils/clamp.js";
+import { type NormalizedOutput, normalizeOutput } from "./normalizeOutput.js";
+
+type SerializedColorJson = ResolvedColor;
+
+type SerializationDiagnostics = {
+  spaceUsed: NonNullable<OutputOptions["preferSpace"]>;
+  clipped?: boolean;
+  compressed?: boolean;
+};
+
+const roundTo = (value: number, digits: number) => {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+};
+
+const formatNumber = (value: number, digits: number) => {
+  const rounded = roundTo(value, digits);
+  if (digits === 0) {
+    return String(Math.round(rounded));
+  }
+  const fixed = rounded.toFixed(digits);
+  return fixed.replace(/\.?0+$/, "");
+};
+
+const normalizeHue = (hue: number) => ((hue % 360) + 360) % 360;
+
+const formatOklch = (color: OkLchColor, precision: NormalizedOutput["precision"]) => {
+  const alpha = clamp(color.alpha ?? 1, 0, 1);
+  const hasAlpha = alpha < 1;
+  const l = formatNumber(clamp(color.l, 0, 100), precision.l);
+  const c = formatNumber(Math.max(0, color.c), precision.c);
+  const h = formatNumber(normalizeHue(color.h), precision.h);
+  const alphaPart = hasAlpha ? ` / ${formatNumber(alpha, precision.alpha)}` : "";
+  return `oklch(${l}% ${c} ${h}${alphaPart})`;
+};
+
+const formatDisplayP3 = (
+  rgb: { r: number; g: number; b: number },
+  alpha: number,
+  precision: NormalizedOutput["precision"],
+) => {
+  const r = formatNumber(clamp(rgb.r, 0, 1), precision.c);
+  const g = formatNumber(clamp(rgb.g, 0, 1), precision.c);
+  const b = formatNumber(clamp(rgb.b, 0, 1), precision.c);
+  const alphaPart = alpha < 1 ? ` / ${formatNumber(alpha, precision.alpha)}` : "";
+  return `color(display-p3 ${r} ${g} ${b}${alphaPart})`;
+};
+
+const formatSrgbHex = (rgb: { r: number; g: number; b: number }, alpha: number) => {
+  const rgbColor = {
+    mode: "rgb" as const,
+    r: clamp(rgb.r, 0, 1),
+    g: clamp(rgb.g, 0, 1),
+    b: clamp(rgb.b, 0, 1),
+    alpha,
+  };
+  return alpha < 1 ? formatHex8(rgbColor) : formatHex(rgbColor);
+};
+
+const formatSrgbFunction = (
+  rgb: { r: number; g: number; b: number },
+  alpha: number,
+  precision: NormalizedOutput["precision"],
+  forceAlpha: boolean,
+) => {
+  const toChannel = (value: number) => String(Math.round(clamp(value, 0, 1) * 255));
+  const r = toChannel(rgb.r);
+  const g = toChannel(rgb.g);
+  const b = toChannel(rgb.b);
+
+  if (forceAlpha || alpha < 1) {
+    return `rgba(${r} ${g} ${b} / ${formatNumber(alpha, precision.alpha)})`;
+  }
+
+  return `rgb(${r} ${g} ${b})`;
+};
+
+const formatSrgb = (
+  rgb: { r: number; g: number; b: number },
+  alpha: number,
+  output: NormalizedOutput,
+) => {
+  switch (output.srgbFormat) {
+    case "rgb":
+      return formatSrgbFunction(rgb, alpha, output.precision, false);
+    case "rgba":
+      return formatSrgbFunction(rgb, alpha, output.precision, true);
+    default:
+      return formatSrgbHex(rgb, alpha);
+  }
+};
+
+const buildDiagnostics = (
+  spaceUsed: SerializationDiagnostics["spaceUsed"],
+  clipped?: boolean,
+  compressed?: boolean,
+): SerializationDiagnostics => ({
+  spaceUsed,
+  ...(clipped ? { clipped } : {}),
+  ...(compressed ? { compressed } : {}),
+});
+
+const buildMeta = (
+  meta: ColorMeta | undefined,
+  output: NormalizedOutput,
+  diagnostics: SerializationDiagnostics,
+): ColorMeta | undefined =>
+  output.includeMeta
+    ? {
+        ...meta,
+        spaceUsed: diagnostics.spaceUsed,
+        gamutMapping: output.gamutMapping,
+        ...(diagnostics.clipped ? { clipped: diagnostics.clipped } : {}),
+        ...(diagnostics.compressed ? { compressed: diagnostics.compressed } : {}),
+      }
+    : undefined;
+
+const resolveAlpha = (baseAlpha: number, mapped?: OkLchColor) =>
+  clamp(mapped?.alpha ?? baseAlpha, 0, 1);
+
+const requirePreferredSpace = (
+  prefer: NormalizedOutput["preferSpace"],
+  strict: boolean,
+  value: string | undefined,
+  fallback: string,
+) => {
+  if (!strict) return value ?? fallback;
+  // In strict mode, do not silently fall back for explicit non-oklch preferences.
+  if (prefer !== "oklch" && !value) {
+    throw new Error(`Unable to serialize preferred space: ${prefer}`);
+  }
+  return value ?? fallback;
+};
+
+const resolveUsedSpace = (
+  prefer: NormalizedOutput["preferSpace"],
+  preferredValue: string | undefined,
+): NormalizedOutput["preferSpace"] => {
+  if (prefer === "oklch") {
+    return "oklch";
+  }
+
+  return preferredValue ? prefer : "oklch";
+};
+
+/**
+ * Serialize raw OKLCH channels into CSS-ready strings for the requested spaces.
+ *
+ * @param color - OKLCH channels resolved by the core resolver.
+ * @param output - Serialization options for precision, gamut mapping, and output spaces.
+ * @param meta - Optional metadata to include when `includeMeta` is enabled.
+ */
+export const serializeColor = (
+  color: OkLchColor,
+  output?: OutputOptions,
+  meta?: ColorMeta,
+): ResolvedColor => {
+  const normalized = normalizeOutput(output);
+  const alpha = clamp(color.alpha ?? 1, 0, 1);
+  const spaces = new Set([normalized.preferSpace, ...normalized.includeSpaces]);
+
+  const oklchText = formatOklch(color, normalized.precision);
+
+  const needsSrgb = spaces.has("srgb") || normalized.preferSpace === "srgb";
+  const srgbInGamut = needsSrgb ? isInGamut(color, "srgb") : false;
+  const srgbColor = needsSrgb
+    ? mapToGamut(color, "srgb", normalized.gamutMapping, normalized.strict)
+    : undefined;
+  const srgbRgb = srgbColor ? toGamutRgb(srgbColor, "srgb") : null;
+  const srgbAlpha = resolveAlpha(alpha, srgbColor);
+  const srgbText = srgbRgb ? formatSrgb(srgbRgb, srgbAlpha, normalized) : undefined;
+  const srgbClipped = needsSrgb && normalized.gamutMapping === "clip" && !srgbInGamut;
+  const srgbCompressed =
+    needsSrgb && normalized.gamutMapping !== "clip" && !srgbInGamut ? true : undefined;
+
+  const needsP3 = spaces.has("p3") || normalized.preferSpace === "p3";
+  const p3InGamut = needsP3 ? isInGamut(color, "p3") : false;
+  const p3Color = needsP3
+    ? normalized.gamutMapping === "preferP3ThenCompress" && p3InGamut
+      ? color
+      : mapToGamut(color, "p3", normalized.gamutMapping, normalized.strict)
+    : undefined;
+  const p3Rgb = p3Color ? toGamutRgb(p3Color, "p3") : null;
+  const p3Alpha = resolveAlpha(alpha, p3Color);
+  const p3Text = p3Rgb ? formatDisplayP3(p3Rgb, p3Alpha, normalized.precision) : undefined;
+  const p3Clipped = needsP3 && normalized.gamutMapping === "clip" && !p3InGamut;
+  const p3Compressed =
+    needsP3 && normalized.gamutMapping !== "clip" && !p3InGamut ? true : undefined;
+
+  const preferredValue =
+    normalized.preferSpace === "srgb"
+      ? srgbText
+      : normalized.preferSpace === "p3"
+        ? p3Text
+        : oklchText;
+
+  const value = (() => {
+    if (normalized.preferSpace === "srgb") {
+      return requirePreferredSpace("srgb", normalized.strict, srgbText, oklchText);
+    }
+    if (normalized.preferSpace === "p3") {
+      return requirePreferredSpace("p3", normalized.strict, p3Text, oklchText);
+    }
+    return oklchText;
+  })();
+
+  const spaceUsed = resolveUsedSpace(normalized.preferSpace, preferredValue);
+  const diagnostics = (() => {
+    if (spaceUsed === "srgb") {
+      return buildDiagnostics(spaceUsed, srgbClipped, srgbCompressed);
+    }
+    if (spaceUsed === "p3") {
+      return buildDiagnostics(spaceUsed, p3Clipped, p3Compressed);
+    }
+    return buildDiagnostics(spaceUsed);
+  })();
+
+  return {
+    value,
+    srgb: spaces.has("srgb") ? srgbText : undefined,
+    p3: spaces.has("p3") ? p3Text : undefined,
+    oklch: spaces.has("oklch") ? oklchText : undefined,
+    alpha,
+    meta: buildMeta(meta, normalized, diagnostics),
+  };
+};
+
+/**
+ * Serialize a resolver output while preserving resolver metadata.
+ *
+ * @param color - Result of the core resolver.
+ * @param output - Serialization options for precision, gamut mapping, and output spaces.
+ */
+export const serializeResolved = (
+  color: BaseResolvedColor,
+  output?: OutputOptions,
+): ResolvedColor => {
+  const meta: ColorMeta = {
+    step: color.step,
+    variantUsed: color.variantUsed,
+    seedUsed: color.seedUsed,
+  };
+
+  return serializeColor(color.oklch, output, meta);
+};
+
+export const serializeColorJson = (
+  color: OkLchColor,
+  output?: OutputOptions,
+  meta?: ColorMeta,
+): SerializedColorJson => {
+  // JSON export is string-based and mirrors CSS serialization intentionally.
+  return serializeColor(color, output, meta);
+};

package/src/serialize/serializeResolved.test.ts

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+
+import { createTheme } from "../core/createTheme.js";
+import { serializeColor, serializeResolved } from "./serializeColor.js";
+
+describe("serializeResolved", () => {
+  it("includes resolver metadata when includeMeta is true", () => {
+    const resolved = {
+      oklch: { l: 60, c: 0.2, h: 40, alpha: 0.5 },
+      step: 7,
+      variantUsed: "accent",
+      seedUsed: "#123456",
+    };
+
+    const result = serializeResolved(resolved, { includeMeta: true, preferSpace: "oklch" });
+
+    expect(result.meta?.step).toBe(7);
+    expect(result.meta?.variantUsed).toBe("accent");
+    expect(result.meta?.seedUsed).toBe("#123456");
+    expect(result.meta?.spaceUsed).toBe("oklch");
+    expect(result.meta?.gamutMapping).toBe("preferP3ThenCompress");
+  });
+});
+
+describe("serializeColor", () => {
+  it("uses rgba output when explicitly requested", () => {
+    const color = { l: 60, c: 0.2, h: 40, alpha: 1 };
+    const result = serializeColor(color, { preferSpace: "srgb", srgbFormat: "rgba" });
+
+    expect(result.value.startsWith("rgba(")).toBe(true);
+  });
+});
+
+describe("theme.serialize", () => {
+  it("serializes a resolved query using the theme", () => {
+    const theme = createTheme({
+      seeds: {
+        light: { neutral: "#8B8D98", accent: "#3D63DD" },
+        dark: { neutral: "#8B8D98", accent: "#3D63DD" },
+      },
+      preset: "modern",
+    });
+
+    const result = theme.serialize(
+      {
+        role: "bg.solid",
+        usage: "bg",
+        surface: "solid",
+        context: "light",
+      },
+      { preferSpace: "oklch" },
+    );
+
+    expect(result.value.startsWith("oklch(")).toBe(true);
+    expect(result.alpha).toBeGreaterThanOrEqual(0);
+  });
+});

package/src/serialize.ts

@@ -0,0 +1 @@
+export * from "./serialize/index.js";

package/src/types/index.ts

@@ -0,0 +1,207 @@
+export type CssColorString = string;
+
+export type ColorSpace = "srgb" | "p3" | "oklch";
+
+export type ColorContext = "light" | "dark" | "highContrast" | "dimmed";
+
+export type SurfaceIntent =
+  | "app"
+  | "surface"
+  | "subtle"
+  | "solid"
+  | "overlay"
+  | "data"
+  | "transparent";
+
+export type ColorState = "default" | "hover" | "active" | "selected" | "focus" | "disabled";
+
+export type ColorEmphasis = "muted" | "subtle" | "default" | "strong" | "inverted";
+
+export type SemanticVariant =
+  | "neutral"
+  | "accent"
+  | "success"
+  | "warning"
+  | "danger"
+  | "info"
+  | "highlight"
+  | "premium"
+  | `category:${string}`
+  | `chart:${string}`;
+
+export type ColorRole = string;
+
+export type ColorUsage = "bg" | "border" | "text" | "icon" | "ring" | "shadow" | "stroke" | "fill";
+
+/**
+ * Token-safe background hints.
+ * Tokens must not embed literal colors.
+ */
+export type TokenBackgroundHint = { kind: "auto" } | { kind: "role"; role: ColorRole };
+
+/**
+ * Token-safe query shape (Phase 3).
+ * - `output` is forbidden (export/serializer concern)
+ * - `on.kind: "color"` is forbidden (no embedded colors)
+ * - `state` must not be encoded (states are operators; declare via TokenDefinition.states)
+ */
+export type TokenQuery = Omit<ColorQuery, "output" | "on" | "state"> & {
+  output?: never;
+  on?: TokenBackgroundHint;
+  state?: never;
+};
+
+/**
+ * Token-supported interactive states.
+ *
+ * Note: `"default"` is the base token, so it is intentionally excluded here.
+ */
+export type TokenState = Exclude<ColorState, "default">;
+
+/**
+ * Declarative set of supported states for a token.
+ * Use `true` to mark a state as supported.
+ */
+export type TokenStates = Partial<Record<TokenState, true>>;
+
+export type BackgroundHint =
+  | { kind: "auto" }
+  | { kind: "role"; role: ColorRole }
+  | { kind: "color"; value: CssColorString };
+
+export type ContrastRequirement =
+  | { model: "apca"; targetLc: number; minLc?: number; maxLc?: number }
+  | { model: "wcag2"; minRatio: number }
+  | { model: "none" };
+
+export type AlphaStrategy =
+  | { mode: "none" }
+  | { mode: "fixed"; alpha: number }
+  | { mode: "solveOnBackground" };
+
+export interface OutputOptions {
+  preferSpace?: ColorSpace;
+  includeSpaces?: ColorSpace[];
+  gamutMapping?: "clip" | "compressChroma" | "preferP3ThenCompress";
+  strict?: boolean;
+  precision?: {
+    l?: number;
+    c?: number;
+    h?: number;
+    alpha?: number;
+  };
+  includeMeta?: boolean;
+  srgbFormat?: "hex" | "rgb" | "rgba";
+}
+
+export interface RawColor {
+  space: ColorSpace;
+  channels: number[];
+  alpha: number;
+}
+
+export interface ColorMeta {
+  role?: ColorRole;
+  variant?: SemanticVariant;
+  usage?: ColorUsage;
+  context?: ColorContext;
+  surface?: SurfaceIntent;
+  state?: ColorState;
+  emphasis?: ColorEmphasis;
+  on?: BackgroundHint;
+  contrast?: ContrastRequirement;
+  step?: number;
+  variantUsed?: string;
+  seedUsed?: CssColorString;
+  gamutMapping?: OutputOptions["gamutMapping"];
+  spaceUsed?: ColorSpace;
+  clipped?: boolean;
+  compressed?: boolean;
+  provenance?: string;
+}
+
+/**
+ * Declarative token definition consumed by registries, exporters, CLI and codegen.
+ *
+ * Rules:
+ * - Tokens never carry actual color values.
+ * - `query.output` is forbidden; output formatting is decided by serializers/exporters.
+ * - Do not encode interactive state in `query.state`; declare supported states via `states`.
+ * - Do not embed literal background colors via `query.on: { kind: "color" }`.
+ */
+export interface TokenDefinition {
+  name: string;
+  description?: string;
+  query: TokenQuery;
+  category?: string;
+  states?: TokenStates;
+}
+
+/**
+ * Collection of base token definitions keyed by token name.
+ */
+export interface TokenRegistry {
+  tokens: Record<string, TokenDefinition>;
+}
+
+export interface ResolvedColor {
+  /**
+   * Serialized string corresponding to `preferSpace`.
+   * Always present.
+   */
+  value: CssColorString;
+  /**
+   * Auxiliary sRGB representation.
+   * Only present if included via `includeSpaces`.
+   */
+  srgb?: CssColorString;
+  /**
+   * Auxiliary Display-P3 representation.
+   * Only present if included via `includeSpaces`.
+   */
+  p3?: CssColorString;
+  /**
+   * Auxiliary OKLCH representation.
+   * Only present if included via `includeSpaces`.
+   */
+  oklch?: CssColorString;
+  alpha: number;
+  meta?: ColorMeta;
+}
+
+export interface ColorQuery {
+  role: ColorRole;
+  variant?: SemanticVariant;
+  usage?: ColorUsage;
+  context?: ColorContext;
+  surface?: SurfaceIntent;
+  state?: ColorState;
+  emphasis?: ColorEmphasis;
+  on?: BackgroundHint;
+  contrast?: ContrastRequirement;
+  alpha?: AlphaStrategy;
+  output?: OutputOptions;
+}
+
+export interface OnSolidQuery {
+  bgRole: ColorRole;
+  usage: "text" | "icon";
+  context?: ColorContext;
+  state?: ColorState;
+  emphasis?: ColorEmphasis;
+  alpha?: AlphaStrategy;
+  contrast?: ContrastRequirement;
+  output?: OutputOptions;
+}
+
+export interface SemanticColorTheme {
+  resolve(query: ColorQuery): ResolvedColor;
+  resolveMany(queries: ColorQuery[]): ResolvedColor[];
+  color(role: ColorRole, options?: Omit<ColorQuery, "role">): ResolvedColor;
+  onSolid(query: OnSolidQuery): ResolvedColor;
+  withContext(context: ColorContext): SemanticColorTheme;
+  export: {
+    cssVars(): string;
+    json(): unknown;
+  };
+}

package/src/utils/clamp.ts

@@ -0,0 +1,2 @@
+export const clamp = (value: number, min: number, max: number) =>
+  Math.min(max, Math.max(min, value));

package/src/utils/index.ts

@@ -0,0 +1 @@
+export { parseColor } from "./parseColor.js";

package/src/utils/lerp.ts

@@ -0,0 +1 @@
+export const lerp = (start: number, end: number, t: number) => start + (end - start) * t;