@clhaas/palette-kit 0.1.8 → 0.3.0

package/src/engine/onSolid.ts

@@ -0,0 +1,178 @@
+import { computeApcaLc } from "../contrast/apca.js";
+import { solveContrast } from "../contrast/solver.js";
+import { blendSrgb, toSrgbColor } from "../contrast/utils.js";
+import { contrastRatio } from "../contrast/wcag2.js";
+import type { ContrastRequirement, OnSolidQuery } from "../types/index.js";
+import { applyOperators } from "./applyOperators.js";
+import { mapColorContextToEngine } from "./context.js";
+import type { OkLchColor } from "./generateScale.js";
+import { normalizeOnSolidQuery, normalizeQuery } from "./normalize.js";
+import type { BaseResolvedColor, ThemeConfig } from "./resolveBaseColor.js";
+import { resolveBaseColor } from "./resolveBaseColor.js";
+
+const DEFAULT_SOLVE_EPSILON = 0.01;
+
+const nearWhite: OkLchColor = { l: 97, c: 0, h: 0, alpha: 1 };
+const nearBlack: OkLchColor = { l: 15, c: 0, h: 0, alpha: 1 };
+
+const defaultContrastForUsage = (usage: OnSolidQuery["usage"]): ContrastRequirement => ({
+  model: "apca",
+  targetLc: usage === "text" ? 75 : 60,
+});
+
+const validateFixedAlpha = (alpha: number) => {
+  if (alpha < 0 || alpha > 1) {
+    throw new Error("Fixed alpha must be between 0 and 1");
+  }
+
+  return alpha;
+};
+
+const resolveAlphaStrategy = (
+  alpha: OnSolidQuery["alpha"] | undefined,
+  usage: OnSolidQuery["usage"],
+  strict: boolean,
+): { mode: "none" } | { mode: "fixed"; alpha: number } => {
+  if (!alpha) {
+    return { mode: "fixed", alpha: usage === "text" ? 0.92 : 0.72 };
+  }
+
+  if (alpha.mode === "none") {
+    return alpha;
+  }
+
+  if (alpha.mode === "fixed") {
+    return { mode: "fixed", alpha: validateFixedAlpha(alpha.alpha) };
+  }
+
+  if (strict) {
+    throw new Error('onSolid does not support alpha.mode "solveOnBackground"');
+  }
+
+  console.warn(
+    'onSolid does not support alpha.mode "solveOnBackground"; falling back to fixed defaults',
+  );
+  return { mode: "fixed", alpha: usage === "text" ? 0.92 : 0.72 };
+};
+
+const checkContrastWithAlpha = (
+  fg: OkLchColor,
+  bg: OkLchColor,
+  req: ContrastRequirement,
+  alpha: number,
+  epsilon = DEFAULT_SOLVE_EPSILON,
+): { pass: boolean; value: number } => {
+  if (req.model === "none") {
+    return { pass: true, value: 0 };
+  }
+
+  const fgSrgb = toSrgbColor(fg);
+  const bgSrgb = toSrgbColor(bg);
+
+  if (!fgSrgb || !bgSrgb) {
+    return { pass: false, value: Number.NaN };
+  }
+
+  const composite = blendSrgb(fgSrgb, bgSrgb, alpha);
+
+  if (req.model === "apca") {
+    const value = Math.abs(computeApcaLc(composite, bgSrgb));
+    const minTarget = req.minLc ?? req.targetLc;
+    const maxTarget = req.maxLc ?? Number.POSITIVE_INFINITY;
+    return {
+      pass: Number.isFinite(value) && value >= minTarget - epsilon && value <= maxTarget + epsilon,
+      value,
+    };
+  }
+
+  const value = contrastRatio(composite, bgSrgb);
+  return { pass: Number.isFinite(value) && value + epsilon >= req.minRatio, value };
+};
+
+export function onSolid(query: OnSolidQuery, theme: ThemeConfig): BaseResolvedColor {
+  const normalized = normalizeOnSolidQuery(query);
+  const contrastRequirement = normalized.contrast ?? defaultContrastForUsage(normalized.usage);
+  const alphaStrategy = resolveAlphaStrategy(
+    normalized.alpha,
+    normalized.usage,
+    normalized.output.strict,
+  );
+  const alpha = alphaStrategy.mode === "none" ? 1 : alphaStrategy.alpha;
+
+  const bgNormalized = normalizeQuery({
+    role: normalized.bgRole,
+    usage: "bg",
+    surface: "solid",
+    context: normalized.context,
+    state: normalized.state,
+    emphasis: normalized.emphasis,
+  });
+  const bgBase = resolveBaseColor(bgNormalized, theme);
+  // Apply state/emphasis operators to the background before onSolid solves.
+  const bgResolved = applyOperators(bgBase, bgNormalized, theme);
+  const bg = bgResolved.oklch;
+
+  const baseFg = bg.l >= 50 ? nearBlack : nearWhite;
+  const seedUsed = `oklch(${baseFg.l}% ${baseFg.c} ${baseFg.h})`;
+
+  const solverContext = {
+    preset: theme.preset,
+    surface: bgNormalized.surface,
+    context: mapColorContextToEngine(bgNormalized.context),
+  };
+
+  const solved = solveContrast({ ...baseFg, alpha }, bg, contrastRequirement, solverContext, {
+    strict: normalized.output.strict,
+  });
+
+  let finalAlpha = alpha;
+  let finalColor = solved.color;
+  let finalCheck = checkContrastWithAlpha(
+    finalColor,
+    bg,
+    contrastRequirement,
+    finalAlpha,
+    DEFAULT_SOLVE_EPSILON,
+  );
+
+  if (!finalCheck.pass && finalAlpha < 1) {
+    finalAlpha = 1;
+    const solvedOpaque = solveContrast(
+      { ...baseFg, alpha: 1 },
+      bg,
+      contrastRequirement,
+      solverContext,
+      { strict: normalized.output.strict },
+    );
+
+    finalColor = solvedOpaque.color;
+    finalCheck = checkContrastWithAlpha(
+      finalColor,
+      bg,
+      contrastRequirement,
+      finalAlpha,
+      DEFAULT_SOLVE_EPSILON,
+    );
+  }
+
+  if (!finalCheck.pass && normalized.output.strict) {
+    const target =
+      contrastRequirement.model === "apca"
+        ? contrastRequirement.targetLc
+        : contrastRequirement.model === "wcag2"
+          ? contrastRequirement.minRatio
+          : 0;
+    throw new Error(
+      `onSolid contrast failed (${contrastRequirement.model}) target=${
+        target
+      } value=${finalCheck.value}`,
+    );
+  }
+
+  return {
+    oklch: { ...finalColor, alpha: finalAlpha },
+    step: 0,
+    variantUsed: "onSolid",
+    seedUsed,
+  };
+}

package/src/engine/resolveBaseColor.test.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+
+import { parseColor } from "../utils/parseColor.js";
+import type { ColorQuery } from "../types/index.js";
+import { normalizeQuery } from "./normalize.js";
+import { resolveBaseColor } from "./resolveBaseColor.js";
+import type { ThemeConfig } from "./resolveBaseColor.js";
+
+const themeConfig: ThemeConfig = {
+  seeds: {
+    light: { neutral: "#8B8D98", accent: "#3D63DD" },
+    dark: { neutral: "#8B8D98", accent: "#3D63DD" },
+  },
+  variants: {
+    "category:food": "#C2410C",
+  },
+  preset: "modern",
+};
+
+describe("resolveBaseColor", () => {
+  const r = (query: ColorQuery) => resolveBaseColor(normalizeQuery(query), themeConfig);
+
+  it("defaults action roles to accent when variant is missing", () => {
+    const result = r({
+      role: "action.primary",
+      usage: "bg",
+      surface: "solid",
+      context: "light",
+    });
+
+    expect(result.variantUsed).toBe("accent");
+    expect(result.seedUsed).toBe(themeConfig.seeds.light.accent);
+  });
+
+  it("defaults text roles to neutral when variant is missing", () => {
+    const result = r({
+      role: "text.primary",
+      usage: "text",
+      surface: "surface",
+      context: "light",
+    });
+
+    expect(result.variantUsed).toBe("neutral");
+    expect(result.seedUsed).toBe(themeConfig.seeds.light.neutral);
+  });
+
+  it("uses custom category variants when provided", () => {
+    const result = r({
+      role: "bg.category",
+      variant: "category:food",
+      usage: "bg",
+      surface: "surface",
+      context: "light",
+    });
+
+    expect(result.variantUsed).toBe("category:food");
+    expect(result.seedUsed).toBe(themeConfig.variants?.["category:food"]);
+  });
+
+  it("falls back to accent for missing category variants", () => {
+    const result = r({
+      role: "bg.category",
+      variant: "category:missing",
+      usage: "bg",
+      surface: "surface",
+      context: "light",
+    });
+
+    expect(result.variantUsed).toBe("accent");
+    expect(result.seedUsed).toBe(themeConfig.seeds.light.accent);
+  });
+
+  it("chooses steps based on usage and surface", () => {
+    const appBg = r({ role: "bg.app", usage: "bg", surface: "app", context: "light" });
+    const solidBg = r({ role: "bg.solid", usage: "bg", surface: "solid", context: "light" });
+    const borderSurface = r({
+      role: "border.surface",
+      usage: "border",
+      surface: "surface",
+      context: "light",
+    });
+    const ring = r({ role: "ring.focus", usage: "ring", surface: "surface", context: "light" });
+
+    expect(appBg.step).toBe(1);
+    expect(solidBg.step).toBe(9);
+    expect(borderSurface.step).toBe(6);
+    expect(ring.step).toBe(8);
+  });
+
+  it("returns valid OKLCH values with stable hue", () => {
+    const result = r({
+      role: "action.primary",
+      usage: "bg",
+      surface: "solid",
+      context: "light",
+    });
+    const seed = parseColor(themeConfig.seeds.light.accent);
+
+    expect(result.oklch.l).toBeGreaterThanOrEqual(0);
+    expect(result.oklch.l).toBeLessThanOrEqual(100);
+    expect(result.oklch.c).toBeGreaterThanOrEqual(0);
+    expect(result.oklch.h).toBeCloseTo(seed.okLch.channels[2], 6);
+  });
+
+  it("accepts normalized queries without re-normalizing", () => {
+    const normalized = normalizeQuery({
+      role: "text.secondary",
+      usage: "text",
+      surface: "surface",
+      context: "dark",
+    });
+
+    const result = resolveBaseColor(normalized, themeConfig);
+
+    expect(result.step).toBe(11);
+  });
+});

package/src/engine/resolveBaseColor.ts

@@ -0,0 +1,203 @@
+import type { CurvePresetName } from "../presets/index.js";
+import type {
+  ColorQuery,
+  ColorUsage,
+  CssColorString,
+  SemanticVariant,
+  SurfaceIntent,
+} from "../types/index.js";
+import { parseColor } from "../utils/parseColor.js";
+import { mapColorContextToEngine } from "./context.js";
+import { generateScale, type OkLchColor } from "./generateScale.js";
+import type { NormalizedQuery } from "./normalize.js";
+import { normalizeQuery } from "./normalize.js";
+
+type ThemeSeeds = {
+  neutral: CssColorString;
+  accent: CssColorString;
+};
+
+export type ThemeConfig = {
+  seeds: {
+    light: ThemeSeeds;
+    dark: ThemeSeeds;
+  };
+  variants?: Record<string, CssColorString>;
+  preset?: CurvePresetName;
+};
+
+type VariantResolution = {
+  variantUsed: string;
+  seedUsed: CssColorString;
+};
+
+const isCategoryVariant = (variant: string) => variant.startsWith("category:");
+const isChartVariant = (variant: string) => variant.startsWith("chart:");
+
+const aliasVariants = new Set<SemanticVariant>(["success", "warning", "danger", "info"]);
+
+const inferVariantFromRole = (role: string): "neutral" | "accent" => {
+  const normalizedRole = role.toLowerCase();
+
+  if (normalizedRole.startsWith("action.")) {
+    return "accent";
+  }
+
+  if (
+    normalizedRole.startsWith("bg.") ||
+    normalizedRole.startsWith("surface.") ||
+    normalizedRole.startsWith("border.") ||
+    normalizedRole.startsWith("text.")
+  ) {
+    return "neutral";
+  }
+
+  return "neutral";
+};
+
+const resolveVariantSeed = (
+  variant: SemanticVariant | undefined,
+  role: string,
+  config: ThemeConfig,
+  contextKey: "light" | "dark",
+): VariantResolution => {
+  if (variant) {
+    if (variant === "neutral" || variant === "accent") {
+      return {
+        variantUsed: variant,
+        seedUsed: config.seeds[contextKey][variant],
+      };
+    }
+
+    if (isCategoryVariant(variant) || isChartVariant(variant)) {
+      const customSeed = config.variants?.[variant];
+      if (customSeed) {
+        return { variantUsed: variant, seedUsed: customSeed };
+      }
+
+      return { variantUsed: "accent", seedUsed: config.seeds[contextKey].accent };
+    }
+
+    if (aliasVariants.has(variant)) {
+      return { variantUsed: "accent", seedUsed: config.seeds[contextKey].accent };
+    }
+
+    return { variantUsed: "accent", seedUsed: config.seeds[contextKey].accent };
+  }
+
+  const inferredVariant = inferVariantFromRole(role);
+
+  return {
+    variantUsed: inferredVariant,
+    seedUsed: config.seeds[contextKey][inferredVariant],
+  };
+};
+
+const clampStep = (value: number) => Math.min(12, Math.max(1, value));
+
+const resolveStep = (usage: ColorUsage, surface: SurfaceIntent): number => {
+  switch (usage) {
+    case "bg": {
+      switch (surface) {
+        case "app":
+          return 1;
+        case "surface":
+          return 2;
+        case "subtle":
+          return 3;
+        case "solid":
+          return 9;
+        case "overlay":
+          return 2;
+        case "data":
+          return 9;
+        case "transparent":
+          return 1;
+        default:
+          return 2;
+      }
+    }
+    case "border": {
+      switch (surface) {
+        case "solid":
+        case "data":
+          return 8;
+        default:
+          return 6;
+      }
+    }
+    case "text":
+      return 11;
+    case "icon":
+      return 11;
+    case "ring":
+      return 8;
+    case "stroke":
+      return surface === "data" ? 9 : 8;
+    case "fill":
+      return 9;
+    default:
+      return 6;
+  }
+};
+
+export type BaseResolvedColor = {
+  oklch: OkLchColor;
+  step: number;
+  variantUsed: string;
+  seedUsed: CssColorString;
+};
+
+// Best-effort guard: ColorQuery may include state/emphasis already; a branded flag
+// from normalizeQuery would be the strict approach in a future version.
+const isNormalizedQuery = (value: ColorQuery | NormalizedQuery): value is NormalizedQuery =>
+  typeof value === "object" &&
+  value !== null &&
+  typeof value.role === "string" &&
+  typeof value.usage === "string" &&
+  typeof value.surface === "string" &&
+  typeof value.context === "string" &&
+  typeof value.state === "string" &&
+  typeof value.emphasis === "string";
+
+export function resolveBaseColor(query: ColorQuery, theme: ThemeConfig): BaseResolvedColor;
+export function resolveBaseColor(
+  normalized: NormalizedQuery,
+  theme: ThemeConfig,
+): BaseResolvedColor;
+export function resolveBaseColor(
+  query: ColorQuery | NormalizedQuery,
+  theme: ThemeConfig,
+): BaseResolvedColor {
+  const normalized = isNormalizedQuery(query) ? query : normalizeQuery(query);
+  const contextKey = mapColorContextToEngine(normalized.context);
+  const { variantUsed, seedUsed } = resolveVariantSeed(
+    normalized.variant,
+    normalized.role,
+    theme,
+    contextKey,
+  );
+
+  const parsedSeed = parseColor(seedUsed);
+  const seed: OkLchColor = {
+    l: parsedSeed.okLch.channels[0] * 100,
+    c: parsedSeed.okLch.channels[1],
+    h: parsedSeed.okLch.channels[2],
+    alpha: parsedSeed.okLch.alpha,
+  };
+
+  const scale = generateScale(seed, {
+    context: contextKey,
+    surface: normalized.surface,
+    preset: theme.preset,
+  });
+  const step = clampStep(resolveStep(normalized.usage, normalized.surface));
+  const oklch = scale[step - 1];
+
+  return {
+    oklch,
+    step,
+    variantUsed,
+    seedUsed,
+  };
+}

package/src/export/__snapshots__/exportTheme.test.ts.snap

@@ -0,0 +1,74 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`exportTheme > exports deterministic CSS with @supports overrides 1`] = `
+":root {
+  --pk-bg-app: #dddee1;
+  --pk-custom-alias: #f1f4fb;
+  --pk-text-primary: #f1f4fb;
+}
+
+@supports (color: oklch(0% 0 0)) {
+  :root {
+    --pk-bg-app: oklch(90% 0.004 264.7);
+    --pk-bg-app-oklch: oklch(90% 0.004 264.7);
+    --pk-custom-alias: oklch(96.7% 0.01 264.7);
+    --pk-custom-alias-oklch: oklch(96.7% 0.01 264.7);
+    --pk-text-primary: oklch(96.7% 0.01 264.7);
+    --pk-text-primary-oklch: oklch(96.7% 0.01 264.7);
+  }
+}
+
+@supports (color: color(display-p3 1 1 1)) {
+  :root {
+    --pk-bg-app-p3: color(display-p3 0.866 0.87 0.88);
+    --pk-custom-alias-p3: color(display-p3 0.947 0.957 0.981);
+    --pk-text-primary-p3: color(display-p3 0.947 0.957 0.981);
+  }
+}
+"
+`;
+
+exports[`exportTheme > exports deterministic JSON with light/dark contexts 1`] = `
+{
+  "dark": {
+    "bg.app": {
+      "alpha": 1,
+      "oklch": "oklch(6% 0.004 264.7)",
+      "srgb": "#010101",
+      "value": "oklch(6% 0.004 264.7)",
+    },
+    "custom.alias": {
+      "alpha": 1,
+      "oklch": "oklch(27.5% 0.01 264.7)",
+      "srgb": "#25282d",
+      "value": "oklch(27.5% 0.01 264.7)",
+    },
+    "text.primary": {
+      "alpha": 1,
+      "oklch": "oklch(27.5% 0.01 264.7)",
+      "srgb": "#25282d",
+      "value": "oklch(27.5% 0.01 264.7)",
+    },
+  },
+  "light": {
+    "bg.app": {
+      "alpha": 1,
+      "oklch": "oklch(90% 0.004 264.7)",
+      "srgb": "#dddee1",
+      "value": "oklch(90% 0.004 264.7)",
+    },
+    "custom.alias": {
+      "alpha": 1,
+      "oklch": "oklch(96.7% 0.01 264.7)",
+      "srgb": "#f1f4fb",
+      "value": "oklch(96.7% 0.01 264.7)",
+    },
+    "text.primary": {
+      "alpha": 1,
+      "oklch": "oklch(96.7% 0.01 264.7)",
+      "srgb": "#f1f4fb",
+      "value": "oklch(96.7% 0.01 264.7)",
+    },
+  },
+}
+`;