@clhaas/palette-kit 0.3.0 → 0.4.0

package/src/contrast/scoring.test.ts

@@ -1,188 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { scoreApca, scoreContrast } from "./scoring.js";
-import type { ContrastRequirement } from "../types/index.js";
-import type { ContrastCheckResult } from "./types.js";
-
-describe("scoreApca", () => {
-  it("prefers values closer to target within range", () => {
-    const target = 60;
-    const min = 50;
-    const max = 80;
-    const hasMax = true;
-
-    expect(scoreApca(60, target, min, max, hasMax)).toBeGreaterThan(
-      scoreApca(80, target, min, max, hasMax),
-    );
-  });
-
-  it("penalizes values outside the range", () => {
-    const target = 60;
-    const min = 50;
-    const max = 80;
-    const hasMax = true;
-
-    expect(scoreApca(40, target, min, max, hasMax)).toBeLessThan(0);
-    expect(scoreApca(90, target, min, max, hasMax)).toBeLessThan(0);
-  });
-
-  it("penalizes below min and prefers target when no max", () => {
-    const target = 60;
-    const min = 50;
-    const max = Number.POSITIVE_INFINITY;
-    const hasMax = false;
-
-    expect(scoreApca(40, target, min, max, hasMax)).toBeLessThan(
-      scoreApca(55, target, min, max, hasMax),
-    );
-    expect(scoreApca(60, target, min, max, hasMax)).toBeGreaterThan(
-      scoreApca(70, target, min, max, hasMax),
-    );
-  });
-
-  it("returns NEGATIVE_INFINITY for NaN values", () => {
-    const target = 60;
-    const min = 50;
-    const max = 80;
-    const hasMax = true;
-
-    expect(scoreApca(Number.NaN, target, min, max, hasMax)).toBe(
-      Number.NEGATIVE_INFINITY,
-    );
-  });
-});
-
-describe("scoreContrast", () => {
-  describe("with APCA contrast model", () => {
-    it("delegates to scoreApca with correct parameters when maxLc is defined", () => {
-      const result: ContrastCheckResult = {
-        model: "apca",
-        target: 60,
-        value: 65,
-        pass: true,
-      };
-      const req: ContrastRequirement = {
-        model: "apca",
-        targetLc: 60,
-        minLc: 50,
-        maxLc: 80,
-      };
-
-      const score = scoreContrast(result, req);
-      const expectedScore = scoreApca(65, 60, 50, 80, true);
-      
-      expect(score).toBe(expectedScore);
-    });
-
-    it("delegates to scoreApca without max when maxLc is undefined", () => {
-      const result: ContrastCheckResult = {
-        model: "apca",
-        target: 60,
-        value: 65,
-        pass: true,
-      };
-      const req: ContrastRequirement = {
-        model: "apca",
-        targetLc: 60,
-        minLc: 50,
-      };
-
-      const score = scoreContrast(result, req);
-      const expectedScore = scoreApca(65, 60, 50, Number.POSITIVE_INFINITY, false);
-      
-      expect(score).toBe(expectedScore);
-    });
-
-    it("uses targetLc as min when minLc is undefined", () => {
-      const result: ContrastCheckResult = {
-        model: "apca",
-        target: 60,
-        value: 65,
-        pass: true,
-      };
-      const req: ContrastRequirement = {
-        model: "apca",
-        targetLc: 60,
-      };
-
-      const score = scoreContrast(result, req);
-      const expectedScore = scoreApca(65, 60, 60, Number.POSITIVE_INFINITY, false);
-      
-      expect(score).toBe(expectedScore);
-    });
-  });
-
-  describe("with WCAG2 contrast model", () => {
-    it("returns the raw contrast value", () => {
-      const result: ContrastCheckResult = {
-        model: "wcag2",
-        target: 4.5,
-        value: 7.2,
-        pass: true,
-      };
-      const req: ContrastRequirement = {
-        model: "wcag2",
-        minRatio: 4.5,
-      };
-
-      const score = scoreContrast(result, req);
-      
-      expect(score).toBe(7.2);
-    });
-  });
-
-  describe("with NaN or non-finite values", () => {
-    it("returns NEGATIVE_INFINITY for NaN", () => {
-      const result: ContrastCheckResult = {
-        model: "apca",
-        target: 60,
-        value: Number.NaN,
-        pass: false,
-      };
-      const req: ContrastRequirement = {
-        model: "apca",
-        targetLc: 60,
-        minLc: 50,
-      };
-
-      const score = scoreContrast(result, req);
-      
-      expect(score).toBe(Number.NEGATIVE_INFINITY);
-    });
-
-    it("returns NEGATIVE_INFINITY for positive infinity", () => {
-      const result: ContrastCheckResult = {
-        model: "apca",
-        target: 60,
-        value: Number.POSITIVE_INFINITY,
-        pass: false,
-      };
-      const req: ContrastRequirement = {
-        model: "apca",
-        targetLc: 60,
-        minLc: 50,
-      };
-
-      const score = scoreContrast(result, req);
-      
-      expect(score).toBe(Number.NEGATIVE_INFINITY);
-    });
-
-    it("returns NEGATIVE_INFINITY for negative infinity", () => {
-      const result: ContrastCheckResult = {
-        model: "wcag2",
-        target: 4.5,
-        value: Number.NEGATIVE_INFINITY,
-        pass: false,
-      };
-      const req: ContrastRequirement = {
-        model: "wcag2",
-        minRatio: 4.5,
-      };
-
-      const score = scoreContrast(result, req);
-      
-      expect(score).toBe(Number.NEGATIVE_INFINITY);
-    });
-  });
-});

package/src/contrast/scoring.ts

@@ -1,48 +0,0 @@
-import type { ContrastRequirement } from "../types/index.js";
-import type { ContrastCheckResult } from "./types.js";
-
-export const scoreApca = (
-  value: number,
-  target: number,
-  min: number,
-  max: number,
-  hasMax: boolean,
-) => {
-  if (Number.isNaN(value)) {
-    return Number.NEGATIVE_INFINITY;
-  }
-
-  if (hasMax) {
-    if (value >= min && value <= max) {
-      return 1000 - Math.abs(value - target);
-    }
-
-    if (value < min) {
-      return -(min - value);
-    }
-
-    return -(value - max);
-  }
-
-  if (value < min) {
-    const distance = min - value;
-    return -distance * 10 - Math.abs(value - target);
-  }
-
-  return -Math.abs(value - target);
-};
-
-export const scoreContrast = (result: ContrastCheckResult, req: ContrastRequirement) => {
-  if (!Number.isFinite(result.value)) {
-    return Number.NEGATIVE_INFINITY;
-  }
-
-  if (req.model === "apca") {
-    const min = req.minLc ?? req.targetLc;
-    const hasMax = req.maxLc !== undefined;
-    const max = req.maxLc ?? Number.POSITIVE_INFINITY;
-    return scoreApca(result.value, req.targetLc, min, max, hasMax);
-  }
-
-  return result.value;
-};

package/src/contrast/solver.test.ts

@@ -1,147 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { parseColor } from "../utils/parseColor.js";
-import { solveContrast } from "./solver.js";
-
-const toOkLch = (hex: string) => {
-  const parsed = parseColor(hex);
-  return {
-    l: parsed.okLch.channels[0] * 100,
-    c: parsed.okLch.channels[1],
-    h: parsed.okLch.channels[2],
-    alpha: parsed.okLch.alpha,
-  };
-};
-
-describe("solveContrast", () => {
-  it("raises contrast on light backgrounds", () => {
-    const fg = toOkLch("#777777");
-    const bg = toOkLch("#ffffff");
-
-    const result = solveContrast(
-      fg,
-      bg,
-      { model: "wcag2", minRatio: 4.5 },
-      { surface: "surface", context: "light" },
-    );
-
-    expect(result.result.pass).toBe(true);
-    expect(result.result.value).toBeGreaterThanOrEqual(4.5);
-    expect(result.color.l).toBeGreaterThanOrEqual(0);
-    expect(result.color.l).toBeLessThanOrEqual(100);
-    expect(result.color.c).toBeGreaterThanOrEqual(0);
-  });
-
-  it("returns original color when contrast model is none", () => {
-    const fg = toOkLch("#777777");
-    const bg = toOkLch("#ffffff");
-
-    const result = solveContrast(
-      fg,
-      bg,
-      { model: "none" },
-      { surface: "surface", context: "light" },
-    );
-
-    expect(result.result.pass).toBe(true);
-    expect(result.iterations).toBe(0);
-    expect(result.color).toEqual(fg);
-  });
-
-  it("skips when background is missing and strict is false", () => {
-    const fg = toOkLch("#777777");
-
-    const result = solveContrast(
-      fg,
-      undefined,
-      { model: "wcag2", minRatio: 4.5 },
-      { surface: "surface", context: "light" },
-      { strict: false },
-    );
-
-    expect(result.result.pass).toBe(false);
-    expect(Number.isNaN(result.result.value)).toBe(true);
-  });
-
-  it("throws when background is missing and strict is true", () => {
-    const fg = toOkLch("#777777");
-
-    expect(() =>
-      solveContrast(
-        fg,
-        undefined,
-        { model: "wcag2", minRatio: 4.5 },
-        { surface: "surface", context: "light" },
-        { strict: true },
-      ),
-    ).toThrowError(/requires background/i);
-  });
-
-  it("raises contrast on dark backgrounds", () => {
-    const fg = toOkLch("#777777");
-    const bg = toOkLch("#111111");
-
-    const result = solveContrast(
-      fg,
-      bg,
-      { model: "wcag2", minRatio: 4.5 },
-      { surface: "surface", context: "dark" },
-    );
-
-    expect(result.result.pass).toBe(true);
-    expect(result.result.value).toBeGreaterThanOrEqual(4.5);
-  });
-
-  it("keeps hue stable", () => {
-    const fg = toOkLch("#3366ff");
-    const bg = toOkLch("#ffffff");
-
-    const result = solveContrast(
-      fg,
-      bg,
-      { model: "wcag2", minRatio: 4.5 },
-      { surface: "surface", context: "light" },
-    );
-
-    expect(result.color.h).toBeCloseTo(fg.h, 6);
-  });
-
-  it("throws in strict mode when target is unattainable", () => {
-    const fg = toOkLch("#ffffff");
-    const bg = toOkLch("#ffffff");
-
-    expect(() =>
-      solveContrast(
-        fg,
-        bg,
-        { model: "wcag2", minRatio: 30 },
-        { surface: "surface", context: "light" },
-        { strict: true },
-      ),
-    ).toThrowError(/contrast solver failed/i);
-  });
-
-  it("prefers APCA values closer to target within the allowed range", () => {
-    const fg = toOkLch("#777777");
-    const bg = toOkLch("#ffffff");
-    const minLc = 50;
-    const maxLc = 80;
-    const targetLc = 60;
-
-    const result = solveContrast(
-      fg,
-      bg,
-      { model: "apca", targetLc, minLc, maxLc },
-      { surface: "surface", context: "light" },
-    );
-
-    const value = result.result.value;
-    const targetDistance = Math.abs(value - targetLc);
-    const maxDistance = Math.abs(maxLc - targetLc);
-
-    expect(result.result.pass).toBe(true);
-    expect(value).toBeGreaterThanOrEqual(minLc);
-    expect(value).toBeLessThanOrEqual(maxLc);
-    expect(targetDistance).toBeLessThanOrEqual(maxDistance);
-  });
-});

package/src/contrast/solver.ts

@@ -1,235 +0,0 @@
-import { converter } from "culori";
-import type { OkLchColor } from "../engine/generateScale.js";
-import { getSurfaceRange } from "../operators/utils.js";
-import type { CurvePresetName } from "../presets/index.js";
-import type { ContrastRequirement, SurfaceIntent } from "../types/index.js";
-import { computeApcaLc } from "./apca.js";
-import { scoreContrast } from "./scoring.js";
-import type { ContrastCheckResult, SolveOptions, SrgbColor } from "./types.js";
-import { contrastRatio } from "./wcag2.js";
-
-const toSrgb = converter("rgb");
-
-const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
-
-const clampOkLch = (color: OkLchColor, cMax: number): OkLchColor => ({
-  l: clamp(color.l, 0, 100),
-  c: clamp(color.c, 0, cMax),
-  h: color.h,
-  alpha: color.alpha,
-});
-
-const clampOkLchLoose = (color: OkLchColor): OkLchColor => ({
-  l: clamp(color.l, 0, 100),
-  c: Math.max(0, color.c),
-  h: color.h,
-  alpha: color.alpha,
-});
-
-const toSrgbColor = (color: OkLchColor): SrgbColor | null => {
-  const rgb = toSrgb({ mode: "oklch", l: clamp(color.l, 0, 100) / 100, c: color.c, h: color.h });
-
-  if (!rgb) {
-    return null;
-  }
-
-  const r = typeof rgb.r === "number" && Number.isFinite(rgb.r) ? clamp(rgb.r, 0, 1) : 0;
-  const g = typeof rgb.g === "number" && Number.isFinite(rgb.g) ? clamp(rgb.g, 0, 1) : 0;
-  const b = typeof rgb.b === "number" && Number.isFinite(rgb.b) ? clamp(rgb.b, 0, 1) : 0;
-
-  return { r, g, b };
-};
-
-const getTarget = (req: ContrastRequirement): number => {
-  if (req.model === "apca") {
-    return req.targetLc;
-  }
-
-  if (req.model === "wcag2") {
-    return req.minRatio;
-  }
-
-  return 0;
-};
-
-const checkContrast = (
-  fg: OkLchColor,
-  bg: OkLchColor,
-  req: ContrastRequirement,
-  epsilon: number,
-): ContrastCheckResult => {
-  if (req.model === "none") {
-    return { model: "none", target: 0, value: 0, pass: true };
-  }
-
-  const fgSrgb = toSrgbColor(fg);
-  const bgSrgb = toSrgbColor(bg);
-  const target = getTarget(req);
-
-  if (!fgSrgb || !bgSrgb) {
-    return { model: req.model, target, value: Number.NaN, pass: false };
-  }
-
-  if (req.model === "apca") {
-    const value = Math.abs(computeApcaLc(fgSrgb, bgSrgb));
-    const minTarget = req.minLc ?? req.targetLc;
-    const maxTarget = req.maxLc ?? Number.POSITIVE_INFINITY;
-    const pass =
-      Number.isFinite(value) && value >= minTarget - epsilon && value <= maxTarget + epsilon;
-    return { model: "apca", target, value, pass };
-  }
-
-  const value = contrastRatio(fgSrgb, bgSrgb);
-  const pass = Number.isFinite(value) && value + epsilon >= target;
-  return { model: "wcag2", target, value, pass };
-};
-
-const pickBetter = (
-  current: { color: OkLchColor; result: ContrastCheckResult },
-  candidate: { color: OkLchColor; result: ContrastCheckResult },
-  req: ContrastRequirement,
-) => {
-  const currentScore = scoreContrast(current.result, req);
-  const candidateScore = scoreContrast(candidate.result, req);
-  return candidateScore > currentScore ? candidate : current;
-};
-
-export function solveContrast(
-  fg: OkLchColor,
-  bg: OkLchColor | undefined,
-  req: ContrastRequirement,
-  ctx: { preset?: CurvePresetName; surface: SurfaceIntent; context: "light" | "dark" },
-  opts?: SolveOptions,
-): { color: OkLchColor; result: ContrastCheckResult; iterations: number } {
-  const options: Required<SolveOptions> = {
-    strict: false,
-    maxIterations: 24,
-    epsilon: 0.01,
-    ...opts,
-  };
-
-  if (req.model === "none") {
-    return {
-      color: fg,
-      result: { model: "none", target: 0, value: 0, pass: true },
-      iterations: 0,
-    };
-  }
-
-  if (!bg) {
-    if (options.strict) {
-      throw new Error("Contrast solver requires background");
-    }
-
-    return {
-      color: fg,
-      result: { model: req.model, target: getTarget(req), value: Number.NaN, pass: false },
-      iterations: 0,
-    };
-  }
-
-  const range = getSurfaceRange(ctx.preset, ctx.surface, ctx.context);
-  const clamped = clampOkLch(fg, range.cMax);
-  const background = clampOkLchLoose(bg);
-  let iterations = 0;
-
-  const evaluate = (color: OkLchColor) => {
-    const result = checkContrast(color, background, req, options.epsilon);
-    iterations += 1;
-    return result;
-  };
-
-  let best = { color: clamped, result: evaluate(clamped) };
-
-  if (best.result.pass) {
-    return { ...best, iterations };
-  }
-
-  const lMin = 0;
-  const lMax = 100;
-  const sampleT = 0.25;
-  const sampleDown = clamp(clamped.l + (lMin - clamped.l) * sampleT, lMin, lMax);
-  const sampleUp = clamp(clamped.l + (lMax - clamped.l) * sampleT, lMin, lMax);
-
-  let preferredBound = lMin;
-
-  if (iterations < options.maxIterations) {
-    const downCandidate = {
-      color: { ...clamped, l: sampleDown },
-      result: evaluate({ ...clamped, l: sampleDown }),
-    };
-    best = pickBetter(best, downCandidate, req);
-
-    if (best.result.pass) {
-      return { ...best, iterations };
-    }
-
-    if (iterations < options.maxIterations) {
-      const upCandidate = {
-        color: { ...clamped, l: sampleUp },
-        result: evaluate({ ...clamped, l: sampleUp }),
-      };
-      best = pickBetter(best, upCandidate, req);
-
-      if (best.result.pass) {
-        return { ...best, iterations };
-      }
-
-      preferredBound =
-        scoreContrast(upCandidate.result, req) > scoreContrast(downCandidate.result, req)
-          ? lMax
-          : lMin;
-    }
-  }
-
-  const remainingAfterSamples = Math.max(0, options.maxIterations - iterations);
-  const lSteps = Math.max(4, remainingAfterSamples);
-
-  for (let step = 1; step <= lSteps && iterations < options.maxIterations; step += 1) {
-    const t = step / lSteps;
-    const l = clamp(clamped.l + (preferredBound - clamped.l) * t, lMin, lMax);
-    const candidateColor = { ...clamped, l };
-    const result = evaluate(candidateColor);
-    const candidate = { color: candidateColor, result };
-    best = pickBetter(best, candidate, req);
-
-    if (result.pass) {
-      return { color: candidateColor, result, iterations };
-    }
-  }
-
-  let current = { ...best.color };
-
-  while (iterations < options.maxIterations && current.c > 0) {
-    const nextC = clamp(current.c * 0.9, 0, range.cMax);
-    current = { ...current, c: nextC };
-    const result = evaluate(current);
-    best = pickBetter(best, { color: current, result }, req);
-
-    if (result.pass) {
-      return { color: current, result, iterations };
-    }
-
-    const sweepSteps = Math.min(3, options.maxIterations - iterations);
-
-    for (let step = 1; step <= sweepSteps && iterations < options.maxIterations; step += 1) {
-      const t = step / sweepSteps;
-      const l = clamp(current.l + (preferredBound - current.l) * t, lMin, lMax);
-      const candidateColor = { ...current, l };
-      const candidateResult = evaluate(candidateColor);
-      best = pickBetter(best, { color: candidateColor, result: candidateResult }, req);
-
-      if (candidateResult.pass) {
-        return { color: candidateColor, result: candidateResult, iterations };
-      }
-    }
-  }
-
-  if (options.strict) {
-    throw new Error(
-      `Contrast solver failed (${best.result.model}) target=${best.result.target} value=${best.result.value} iterations=${iterations}`,
-    );
-  }
-
-  return { color: best.color, result: best.result, iterations };
-}

package/src/contrast/types.ts

@@ -1,20 +0,0 @@
-export type ContrastModel = "apca" | "wcag2" | "none";
-
-export type ContrastCheckResult = {
-  model: ContrastModel;
-  target: number;
-  value: number;
-  pass: boolean;
-};
-
-export type SolveOptions = {
-  strict?: boolean;
-  maxIterations?: number;
-  epsilon?: number;
-};
-
-export type SrgbColor = {
-  r: number;
-  g: number;
-  b: number;
-};

package/src/contrast/utils.ts

@@ -1,28 +0,0 @@
-import { converter } from "culori";
-
-import type { OkLchColor } from "../engine/generateScale.js";
-import type { SrgbColor } from "./types.js";
-
-const toSrgb = converter("rgb");
-
-const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
-
-export const toSrgbColor = (color: OkLchColor): SrgbColor | null => {
-  const rgb = toSrgb({ mode: "oklch", l: clamp(color.l, 0, 100) / 100, c: color.c, h: color.h });
-
-  if (!rgb) {
-    return null;
-  }
-
-  const r = typeof rgb.r === "number" && Number.isFinite(rgb.r) ? clamp(rgb.r, 0, 1) : 0;
-  const g = typeof rgb.g === "number" && Number.isFinite(rgb.g) ? clamp(rgb.g, 0, 1) : 0;
-  const b = typeof rgb.b === "number" && Number.isFinite(rgb.b) ? clamp(rgb.b, 0, 1) : 0;
-
-  return { r, g, b };
-};
-
-export const blendSrgb = (fg: SrgbColor, bg: SrgbColor, alpha: number): SrgbColor => ({
-  r: fg.r * alpha + bg.r * (1 - alpha),
-  g: fg.g * alpha + bg.g * (1 - alpha),
-  b: fg.b * alpha + bg.b * (1 - alpha),
-});

package/src/contrast/wcag2.test.ts

@@ -1,21 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import { contrastRatio } from "./wcag2.js";
-
-describe("wcag2 contrastRatio", () => {
-  it("returns high contrast for black on white", () => {
-    const ratio = contrastRatio({ r: 0, g: 0, b: 0 }, { r: 1, g: 1, b: 1 });
-    expect(ratio).toBeGreaterThan(10);
-  });
-
-  it("returns lower contrast for mid gray on white", () => {
-    const gray = 0x77 / 255;
-    const ratio = contrastRatio({ r: gray, g: gray, b: gray }, { r: 1, g: 1, b: 1 });
-    expect(ratio).toBeLessThan(4.5);
-  });
-
-  it("does not return NaN", () => {
-    const ratio = contrastRatio({ r: 0.2, g: 0.4, b: 0.6 }, { r: 0.8, g: 0.7, b: 0.1 });
-    expect(Number.isNaN(ratio)).toBe(false);
-  });
-});