@clhaas/palette-kit 0.1.7 → 0.3.0

package/src/operators/index.ts

@@ -0,0 +1,3 @@
+export { applyEmphasisOperator } from "./emphasis.js";
+export { applyStateOperator } from "./state.js";
+export type { OperatorInput } from "./types.js";

package/src/operators/state.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from "vitest";
+
+import { applyStateOperator } from "./state.js";
+
+const base = {
+  oklch: { l: 60, c: 0.12, h: 210 },
+  context: "light" as const,
+  surface: "surface" as const,
+  usage: "bg" as const,
+  state: "default" as const,
+  emphasis: "default" as const,
+  preset: "modern" as const,
+  step: 9,
+};
+
+describe("applyStateOperator", () => {
+  it("darkens hover in light context", () => {
+    const result = applyStateOperator({ ...base, state: "hover" });
+
+    expect(result.l).toBeLessThan(base.oklch.l);
+  });
+
+  it("lightens hover in dark context", () => {
+    const result = applyStateOperator({ ...base, context: "dark", state: "hover" });
+
+    expect(result.l).toBeGreaterThan(base.oklch.l);
+  });
+
+  it("active is stronger than hover", () => {
+    const hover = applyStateOperator({ ...base, state: "hover" });
+    const active = applyStateOperator({ ...base, state: "active" });
+
+    expect(Math.abs(active.l - base.oklch.l)).toBeGreaterThan(Math.abs(hover.l - base.oklch.l));
+  });
+
+  it("selected is less aggressive than active", () => {
+    const selected = applyStateOperator({ ...base, state: "selected" });
+    const active = applyStateOperator({ ...base, state: "active" });
+
+    expect(Math.abs(selected.l - base.oklch.l)).toBeLessThan(Math.abs(active.l - base.oklch.l));
+  });
+
+  it("disabled reduces chroma", () => {
+    const disabled = applyStateOperator({ ...base, state: "disabled" });
+
+    expect(disabled.c).toBeLessThan(base.oklch.c * 0.6);
+  });
+
+  it("returns the original color for default state", () => {
+    const result = applyStateOperator({ ...base, state: "default" });
+
+    expect(result).toEqual(base.oklch);
+  });
+
+  it("focus only affects ring and border usage", () => {
+    const bgFocus = applyStateOperator({ ...base, usage: "bg", state: "focus" });
+    const ringFocus = applyStateOperator({ ...base, usage: "ring", state: "focus" });
+    const borderFocus = applyStateOperator({ ...base, usage: "border", state: "focus" });
+
+    expect(bgFocus.l).toBeCloseTo(base.oklch.l, 6);
+    expect(ringFocus.l).not.toBeCloseTo(base.oklch.l, 6);
+    expect(Math.abs(borderFocus.l - base.oklch.l)).toBeLessThan(
+      Math.abs(ringFocus.l - base.oklch.l),
+    );
+  });
+});

package/src/operators/state.ts

@@ -0,0 +1,122 @@
+import type { OkLchColor } from "../engine/generateScale.js";
+import { clamp } from "../utils/clamp.js";
+import type { OperatorInput } from "./types.js";
+import { getNeutralL, getSurfaceRange } from "./utils.js";
+
+type StateTuning = {
+  hover: number;
+  active: number;
+  selected: number;
+  focus: number;
+  disabledChroma: number;
+  disabledNeutralPull: number;
+};
+
+const STATE_TUNING: Record<OperatorInput["surface"], StateTuning> = {
+  app: {
+    hover: 2,
+    active: 4,
+    selected: 3,
+    focus: 2,
+    disabledChroma: 0.45,
+    disabledNeutralPull: 0.45,
+  },
+  surface: {
+    hover: 2.5,
+    active: 4.5,
+    selected: 3.5,
+    focus: 2.5,
+    disabledChroma: 0.45,
+    disabledNeutralPull: 0.45,
+  },
+  subtle: {
+    hover: 3,
+    active: 5.5,
+    selected: 4,
+    focus: 3,
+    disabledChroma: 0.45,
+    disabledNeutralPull: 0.5,
+  },
+  solid: {
+    hover: 4,
+    active: 7,
+    selected: 5,
+    focus: 4,
+    disabledChroma: 0.4,
+    disabledNeutralPull: 0.55,
+  },
+  overlay: {
+    hover: 3,
+    active: 5.5,
+    selected: 4,
+    focus: 3,
+    disabledChroma: 0.45,
+    disabledNeutralPull: 0.5,
+  },
+  data: {
+    hover: 4,
+    active: 7,
+    selected: 5,
+    focus: 4,
+    disabledChroma: 0.4,
+    disabledNeutralPull: 0.55,
+  },
+  transparent: {
+    hover: 2,
+    active: 4,
+    selected: 3,
+    focus: 2,
+    disabledChroma: 0.45,
+    disabledNeutralPull: 0.45,
+  },
+};
+
+const FOCUS_BORDER_SCALE = 0.6;
+
+const clampOkLch = (color: OkLchColor, maxChroma: number): OkLchColor => ({
+  ...color,
+  l: clamp(color.l, 0, 100),
+  c: clamp(color.c, 0, maxChroma),
+});
+
+export const applyStateOperator = (input: OperatorInput): OkLchColor => {
+  const { state, context, surface, usage } = input;
+  const tuning = STATE_TUNING[surface];
+  const range = getSurfaceRange(input.preset, surface, context);
+  const neutralL = getNeutralL(input.preset, surface, context);
+  const direction = context === "light" ? -1 : 1;
+
+  if (state === "default") {
+    return input.oklch;
+  }
+
+  if (state === "focus" && usage !== "ring" && usage !== "border") {
+    return input.oklch;
+  }
+
+  const next: OkLchColor = { ...input.oklch };
+
+  switch (state) {
+    case "hover":
+      next.l += direction * tuning.hover;
+      break;
+    case "active":
+      next.l += direction * tuning.active;
+      break;
+    case "selected":
+      next.l += direction * tuning.selected;
+      break;
+    case "focus":
+      next.l += direction * tuning.focus * (usage === "border" ? FOCUS_BORDER_SCALE : 1);
+      break;
+    case "disabled":
+      next.c *= tuning.disabledChroma;
+      next.l += (neutralL - next.l) * tuning.disabledNeutralPull;
+      break;
+    default:
+      // Allow unknown/future states to be no-ops to avoid unexpected shifts.
+      return input.oklch;
+  }
+
+  return clampOkLch(next, range.cMax);
+};

package/src/operators/types.ts

@@ -0,0 +1,14 @@
+import type { OkLchColor } from "../engine/generateScale.js";
+import type { CurvePresetName } from "../presets/index.js";
+import type { ColorEmphasis, ColorState, ColorUsage, SurfaceIntent } from "../types/index.js";
+
+export type OperatorInput = {
+  oklch: OkLchColor;
+  context: "light" | "dark";
+  surface: SurfaceIntent;
+  usage: ColorUsage;
+  state: ColorState;
+  emphasis: ColorEmphasis;
+  preset?: CurvePresetName;
+  step: number;
+};

package/src/operators/utils.ts

@@ -0,0 +1,44 @@
+import type { CurvePresetName } from "../presets/index.js";
+import { curvePresets } from "../presets/index.js";
+import type { SurfaceIntent } from "../types/index.js";
+import { clamp } from "../utils/clamp.js";
+import { lerp } from "../utils/lerp.js";
+
+// TODO: deduplicate with generateScale constants and helpers.
+const STEPS = 12;
+const OKLCH_L_MIN = 0;
+const OKLCH_L_MAX = 100;
+
+export type OperatorContext = "light" | "dark";
+
+export const getSurfaceRange = (
+  presetName: CurvePresetName | undefined,
+  surface: SurfaceIntent,
+  context: OperatorContext,
+) => {
+  const preset = curvePresets[presetName ?? "modern"];
+  return preset.surfaces[surface].ranges[context];
+};
+
+export const getNeutralL = (
+  presetName: CurvePresetName | undefined,
+  surface: SurfaceIntent,
+  context: OperatorContext,
+) => {
+  const range = getSurfaceRange(presetName, surface, context);
+  return (range.l[0] + range.l[1]) / 2;
+};
+
+export const getStepLightness = (
+  presetName: CurvePresetName | undefined,
+  surface: SurfaceIntent,
+  context: OperatorContext,
+  step: number,
+) => {
+  const preset = curvePresets[presetName ?? "modern"];
+  const surfaceCurve = preset.surfaces[surface];
+  const range = surfaceCurve.ranges[context];
+  const t = clamp((step - 1) / (STEPS - 1), 0, 1);
+  const lightnessT = surfaceCurve.l(t);
+  return clamp(lerp(range.l[0], range.l[1], lightnessT), OKLCH_L_MIN, OKLCH_L_MAX);
+};

package/src/presets/curves.ts

@@ -0,0 +1,168 @@
+import type { SurfaceIntent } from "../types/index.js";
+import { clamp } from "../utils/clamp.js";
+import { smoothstep } from "../utils/smoothstep.js";
+
+export type CurvePresetName = "modern" | "radixLike";
+
+export type CurveFn = (t: number) => number;
+
+export type SurfaceCurve = {
+  l: CurveFn;
+  c: CurveFn;
+  ranges: {
+    light: { l: [number, number]; cMin: number; cMax: number; chromaBoost?: number };
+    dark: { l: [number, number]; cMin: number; cMax: number; chromaBoost?: number };
+  };
+};
+
+export type CurvePreset = {
+  name: CurvePresetName;
+  surfaces: Record<SurfaceIntent, SurfaceCurve>;
+};
+
+const normalizeT = (t: number) => clamp(t, 0, 1);
+const lightnessCurve: CurveFn = (t) => smoothstep(normalizeT(t));
+const chromaCurve: CurveFn = (t) => Math.sin(Math.PI * normalizeT(t));
+
+export const modern: CurvePreset = {
+  name: "modern",
+  surfaces: {
+    // app: fundo do app (separação mínima, chroma baixíssimo)
+    app: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [90, 99], cMin: 0.004, cMax: 0.05 },
+        dark: { l: [6, 22], cMin: 0.004, cMax: 0.07 },
+      },
+    },
+    // surface: cards/panels (separação leve do app bg, chroma baixo)
+    surface: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [84, 97], cMin: 0.008, cMax: 0.08 },
+        dark: { l: [8, 28], cMin: 0.008, cMax: 0.09 },
+      },
+    },
+    // subtle: tints/hover backgrounds (um pouco mais de chroma, ainda calmo)
+    subtle: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [78, 95], cMin: 0.012, cMax: 0.1 },
+        dark: { l: [10, 32], cMin: 0.012, cMax: 0.11 },
+      },
+    },
+    // solid: backgrounds sólidos (chroma mais alto, pensado para onSolid)
+    solid: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [46, 90], cMin: 0.03, cMax: 0.18, chromaBoost: 1.25 },
+        dark: { l: [12, 42], cMin: 0.03, cMax: 0.2, chromaBoost: 1.25 },
+      },
+    },
+    // overlay: modal surfaces/scrims (chroma baixo, controle forte de L)
+    overlay: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [72, 96], cMin: 0.01, cMax: 0.09 },
+        dark: { l: [14, 40], cMin: 0.01, cMax: 0.1 },
+      },
+    },
+    // data: charts/heatmaps (pode usar chroma maior sem “gritar”)
+    data: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [38, 86], cMin: 0.04, cMax: 0.22, chromaBoost: 1.3 },
+        dark: { l: [18, 48], cMin: 0.04, cMax: 0.24, chromaBoost: 1.3 },
+      },
+    },
+    // transparent: base quase neutra (chroma quase zero; usado para ghost)
+    transparent: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [62, 96], cMin: 0, cMax: 0.06 },
+        dark: { l: [8, 30], cMin: 0, cMax: 0.07 },
+      },
+    },
+  },
+};
+
+export const radixLike: CurvePreset = {
+  name: "radixLike",
+  surfaces: {
+    // app: fundo do app (separação mínima, chroma baixíssimo)
+    app: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [92, 99], cMin: 0.003, cMax: 0.06 },
+        dark: { l: [4, 18], cMin: 0.003, cMax: 0.08 },
+      },
+    },
+    // surface: cards/panels (separação leve do app bg, chroma baixo)
+    surface: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [86, 97], cMin: 0.006, cMax: 0.1 },
+        dark: { l: [6, 24], cMin: 0.006, cMax: 0.11 },
+      },
+    },
+    // subtle: tints/hover backgrounds (um pouco mais de chroma, ainda calmo)
+    subtle: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [80, 94], cMin: 0.01, cMax: 0.12 },
+        dark: { l: [8, 30], cMin: 0.01, cMax: 0.13 },
+      },
+    },
+    // solid: backgrounds sólidos (chroma mais alto, pensado para onSolid)
+    solid: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [50, 88], cMin: 0.035, cMax: 0.2, chromaBoost: 1.25 },
+        dark: { l: [10, 38], cMin: 0.035, cMax: 0.22, chromaBoost: 1.25 },
+      },
+    },
+    // overlay: modal surfaces/scrims (chroma baixo, controle forte de L)
+    overlay: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [74, 96], cMin: 0.01, cMax: 0.11 },
+        dark: { l: [12, 38], cMin: 0.01, cMax: 0.12 },
+      },
+    },
+    // data: charts/heatmaps (pode usar chroma maior sem “gritar”)
+    data: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [40, 84], cMin: 0.05, cMax: 0.24, chromaBoost: 1.3 },
+        dark: { l: [16, 46], cMin: 0.05, cMax: 0.26, chromaBoost: 1.3 },
+      },
+    },
+    // transparent: base quase neutra (chroma quase zero; usado para ghost)
+    transparent: {
+      l: lightnessCurve,
+      c: chromaCurve,
+      ranges: {
+        light: { l: [60, 94], cMin: 0, cMax: 0.08 },
+        dark: { l: [6, 28], cMin: 0, cMax: 0.09 },
+      },
+    },
+  },
+};
+
+export const curvePresets: Record<CurvePresetName, CurvePreset> = {
+  modern,
+  radixLike,
+};

package/src/presets/index.ts

@@ -0,0 +1,2 @@
+export type { CurveFn, CurvePreset, CurvePresetName, SurfaceCurve } from "./curves.js";
+export { curvePresets, modern, radixLike } from "./curves.js";

package/src/presets/tokens/index.ts

@@ -0,0 +1,3 @@
+export { minimalUiTokens } from "./minimal-ui.js";
+export { modernUiTokens } from "./modern-ui.js";
+export { radixLikeUiTokens } from "./radixLike-ui.js";

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

@@ -0,0 +1,55 @@
+import type { TokenRegistry } from "../../types/index.js";
+
+/**
+ * Minimal token preset aimed at quick adoption.
+ * Focuses on a small, coherent base set for app surfaces and text.
+ */
+export const minimalUiTokens: TokenRegistry = {
+  tokens: {
+    "bg.app": {
+      name: "bg.app",
+      description: "Base application background.",
+      category: "background",
+      query: { role: "bg.app", usage: "bg", surface: "app" },
+    },
+    "bg.surface": {
+      name: "bg.surface",
+      description: "Default surface background for containers.",
+      category: "background",
+      query: { role: "bg.surface", usage: "bg", surface: "surface" },
+    },
+    "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 on standard surfaces.",
+      category: "text",
+      query: { role: "text.secondary", usage: "text", surface: "surface", emphasis: "muted" },
+    },
+    "border.default": {
+      name: "border.default",
+      description: "Default border for surfaces and containers.",
+      category: "border",
+      query: { role: "border.default", usage: "border", surface: "surface" },
+      states: { hover: true },
+    },
+    "icon.default": {
+      name: "icon.default",
+      description: "Default icon color on standard 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/presets/tokens/modern-ui.ts

@@ -0,0 +1,85 @@
+import type { TokenRegistry } from "../../types/index.js";
+
+/**
+ * Modern preset aimed at richer UI surfaces with strong emphasis options.
+ */
+export const modernUiTokens: TokenRegistry = {
+  tokens: {
+    "bg.app": {
+      name: "bg.app",
+      description: "Primary application background.",
+      category: "background",
+      query: { role: "bg.app", usage: "bg", surface: "app" },
+    },
+    "bg.surface": {
+      name: "bg.surface",
+      description: "Default surface background for content containers.",
+      category: "background",
+      query: { role: "bg.surface", usage: "bg", surface: "surface" },
+    },
+    "bg.subtle": {
+      name: "bg.subtle",
+      description: "Subtle surface for secondary sections.",
+      category: "background",
+      query: { role: "bg.subtle", usage: "bg", surface: "subtle" },
+    },
+    "bg.solid": {
+      name: "bg.solid",
+      description: "Solid surface for emphasized elements.",
+      category: "background",
+      query: { role: "bg.solid", usage: "bg", surface: "solid" },
+      states: { hover: true, active: true },
+    },
+    "text.primary": {
+      name: "text.primary",
+      description: "Primary text for default 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 or accented surfaces.",
+      category: "text",
+      query: { role: "text.inverse", usage: "text", surface: "solid", emphasis: "inverted" },
+    },
+    "border.default": {
+      name: "border.default",
+      description: "Default border for containers and layout.",
+      category: "border",
+      query: { role: "border.default", usage: "border", surface: "surface" },
+    },
+    "border.strong": {
+      name: "border.strong",
+      description: "High-emphasis border for focused containers.",
+      category: "border",
+      query: { role: "border.strong", usage: "border", surface: "surface", emphasis: "strong" },
+      states: { hover: true },
+    },
+    "icon.default": {
+      name: "icon.default",
+      description: "Primary icon color for default surfaces.",
+      category: "icon",
+      query: { role: "icon.default", usage: "icon", surface: "surface" },
+      states: { hover: true },
+    },
+    "icon.muted": {
+      name: "icon.muted",
+      description: "Muted icons for less prominent actions.",
+      category: "icon",
+      query: { role: "icon.muted", usage: "icon", surface: "surface", emphasis: "muted" },
+    },
+    "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/presets/tokens/presets.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from "vitest";
+
+import { createTheme } from "../../core/createTheme.js";
+import type { TokenRegistry } from "../../types/index.js";
+import {
+  minimalUiTokens,
+  modernUiTokens,
+  radixLikeUiTokens,
+} from "./index.js";
+import { validateTokenRegistry } from "../../core/tokenRegistry.js";
+import { exportThemeCss, exportThemeJson } from "../../export/exportTheme.js";
+
+const toThemeTokens = (registry: TokenRegistry) =>
+  Object.fromEntries(
+    Object.entries(registry.tokens).map(([name, token]) => [name, token.query]),
+  );
+
+describe("token presets", () => {
+  const theme = createTheme({
+    seeds: {
+      light: { neutral: "#8B8D98", accent: "#3D63DD" },
+      dark: { neutral: "#8B8D98", accent: "#3D63DD" },
+    },
+    preset: "modern",
+  });
+
+  it("validates all preset registries", () => {
+    expect(() => validateTokenRegistry(minimalUiTokens)).not.toThrow();
+    expect(() => validateTokenRegistry(radixLikeUiTokens)).not.toThrow();
+    expect(() => validateTokenRegistry(modernUiTokens)).not.toThrow();
+  });
+
+  it("exports CSS/JSON for each preset", () => {
+    const registries = [minimalUiTokens, radixLikeUiTokens, modernUiTokens];
+
+    for (const registry of registries) {
+      const tokens = toThemeTokens(registry);
+      const css = exportThemeCss(theme, tokens, { preferSpace: "oklch" }).css;
+      const json = exportThemeJson(theme, tokens, { preferSpace: "oklch" }).tokens;
+
+      expect(css.length).toBeGreaterThan(0);
+      expect(Object.keys(json.light).length).toBeGreaterThan(0);
+      expect(Object.keys(json.dark).length).toBeGreaterThan(0);
+    }
+  });
+});