@clhaas/palette-kit 0.3.0 → 0.4.0

package/src/engine/onSolid.ts

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

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

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

@@ -1,74 +0,0 @@
-// 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)",
-    },
-  },
-}
-`;