@clhaas/palette-kit 0.3.0 → 0.4.0

package/src/engine/normalize.ts

@@ -1,550 +0,0 @@
-import type {
-  AlphaStrategy,
-  BackgroundHint,
-  ColorContext,
-  ColorEmphasis,
-  ColorQuery,
-  ColorSpace,
-  ColorState,
-  ColorUsage,
-  ContrastRequirement,
-  OnSolidQuery,
-  OutputOptions,
-  SemanticVariant,
-  SurfaceIntent,
-} from "../types/index.js";
-
-export type NormalizedQuery = Required<
-  Pick<ColorQuery, "role" | "usage" | "context" | "surface" | "state" | "emphasis">
-> & {
-  variant?: ColorQuery["variant"];
-  on?: ColorQuery["on"];
-  contrast?: ColorQuery["contrast"];
-  alpha?: ColorQuery["alpha"];
-  output: Required<Omit<OutputOptions, "format">>;
-};
-
-export type NormalizedOnSolidQuery = Required<
-  Pick<OnSolidQuery, "bgRole" | "usage" | "context" | "state" | "emphasis">
-> & {
-  alpha?: OnSolidQuery["alpha"];
-  contrast?: OnSolidQuery["contrast"];
-  output: Required<Omit<OutputOptions, "format">>;
-};
-
-const usages: ColorUsage[] = ["bg", "border", "text", "icon", "ring", "shadow", "stroke", "fill"];
-const onSolidUsages: OnSolidQuery["usage"][] = ["text", "icon"];
-
-const contexts: ColorContext[] = ["light", "dark", "highContrast", "dimmed"];
-
-const surfaces: SurfaceIntent[] = [
-  "app",
-  "surface",
-  "subtle",
-  "solid",
-  "overlay",
-  "data",
-  "transparent",
-];
-
-export const COLOR_STATES: readonly ColorState[] = [
-  "default",
-  "hover",
-  "active",
-  "selected",
-  "focus",
-  "disabled",
-];
-
-const emphases: ColorEmphasis[] = ["muted", "subtle", "default", "strong", "inverted"];
-
-const semanticVariants: SemanticVariant[] = [
-  "neutral",
-  "accent",
-  "success",
-  "warning",
-  "danger",
-  "info",
-  "highlight",
-  "premium",
-];
-
-const colorSpaces: ColorSpace[] = ["srgb", "p3", "oklch"];
-
-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(`Invalid ${label}: "${value}"`);
-  }
-
-  return value as T;
-};
-
-const normalizeRole = (role: string | undefined) => {
-  if (role === undefined) {
-    throw new Error("Color role is required");
-  }
-
-  const trimmed = role.trim();
-  if (!trimmed) {
-    throw new Error("Color role is required");
-  }
-
-  return trimmed;
-};
-
-const normalizeBgRole = (role: string | undefined) => {
-  if (role === undefined) {
-    throw new Error("Background role (bgRole) is required");
-  }
-
-  const trimmed = role.trim();
-  if (!trimmed) {
-    throw new Error("Background role (bgRole) is required");
-  }
-
-  return trimmed;
-};
-
-const hexColorPattern = /^#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
-
-const inferUsageFromRole = (role: string): ColorUsage | undefined => {
-  const normalizedRole = role.trim().toLowerCase();
-
-  if (normalizedRole.startsWith("text.")) {
-    return "text";
-  }
-
-  if (normalizedRole.startsWith("icon.")) {
-    return "icon";
-  }
-
-  if (normalizedRole.startsWith("border.")) {
-    return "border";
-  }
-
-  if (
-    normalizedRole.startsWith("bg.") ||
-    normalizedRole.startsWith("surface.") ||
-    normalizedRole.startsWith("overlay.")
-  ) {
-    return "bg";
-  }
-
-  if (normalizedRole.startsWith("focus.") || normalizedRole.startsWith("ring.")) {
-    return "ring";
-  }
-
-  if (normalizedRole.startsWith("chart.")) {
-    const tokens = normalizedRole.split(".");
-
-    if (tokens.includes("stroke")) {
-      return "stroke";
-    }
-
-    if (tokens.includes("fill")) {
-      return "fill";
-    }
-
-    if (tokens.includes("grid")) {
-      return "border";
-    }
-
-    if (tokens.includes("label") || tokens.includes("text")) {
-      return "text";
-    }
-  }
-
-  return undefined;
-};
-
-/**
- * Infer surface intent from role naming patterns.
- *
- * Recognizes:
- * - Direct surface token prefixes: `"app.*"`, `"surface.*"`, `"solid.*"`, etc.
- * - Background patterns: `"bg.app"`, `"bg.surface"`, `"bg.solid"`, etc.
- *
- * @example
- * inferSurfaceFromRole("bg.app") // "app"
- * @example
- * inferSurfaceFromRole("app.bg") // "app"
- */
-const inferSurfaceFromRole = (role: string): SurfaceIntent | undefined => {
-  const normalizedRole = role.trim().toLowerCase();
-  const tokens = normalizedRole.split(".");
-  const [first, second] = tokens;
-
-  if (first && surfaces.includes(first as SurfaceIntent)) {
-    return first as SurfaceIntent;
-  }
-
-  if (first === "bg" && second && surfaces.includes(second as SurfaceIntent)) {
-    return second as SurfaceIntent;
-  }
-
-  return undefined;
-};
-
-/**
- * Infer semantic variant from role token.
- *
- * Recognizes:
- * - Semantic variants: `"neutral"`, `"accent"`, `"success"`, `"warning"`, etc.
- * - Custom categories: `"category:*"`
- * - Chart variants: `"chart:*"`
- *
- * @example
- * inferVariantFromRole("success.bg") // "success"
- * @example
- * inferVariantFromRole("category:sales.fill") // "category:sales"
- */
-const inferVariantFromRole = (role: string): SemanticVariant | undefined => {
-  const token = role.trim().split(".")[0];
-  const normalized = token?.toLowerCase();
-
-  if (!normalized) {
-    return undefined;
-  }
-
-  if (semanticVariants.includes(normalized as SemanticVariant)) {
-    return normalized as SemanticVariant;
-  }
-
-  if (/^(category|chart):.+/.test(normalized)) {
-    return normalized as SemanticVariant;
-  }
-
-  return undefined;
-};
-
-const normalizeVariant = (variant: string | undefined): SemanticVariant | undefined => {
-  if (!variant) {
-    return undefined;
-  }
-
-  const trimmed = variant.trim();
-
-  if (semanticVariants.includes(trimmed as SemanticVariant)) {
-    return trimmed as SemanticVariant;
-  }
-
-  if (/^(category|chart):.+/.test(trimmed)) {
-    return trimmed as SemanticVariant;
-  }
-
-  throw new Error(`Invalid variant: "${variant}"`);
-};
-
-const warn = (message: string) => {
-  console.warn(message);
-};
-
-/**
- * Cache used to deduplicate inference warnings.
- *
- * Notes:
- * - This is intentionally module-scoped so repeated calls don't spam logs.
- * - To avoid unbounded growth in long-running processes, this cache is capped
- *   and clears itself when the cap is reached.
- */
-const inferenceWarnings = new Set<string>();
-
-const MAX_INFERENCE_WARNINGS = 1000;
-
-const warnInferenceOnce = (key: string, message: string) => {
-  if (inferenceWarnings.has(key)) return;
-  if (inferenceWarnings.size >= MAX_INFERENCE_WARNINGS) {
-    inferenceWarnings.clear();
-  }
-  inferenceWarnings.add(key);
-  console.warn(message);
-};
-
-const missingUsageMessage = (role: string) =>
-  `Usage is required for role: "${role}". Provide usage explicitly (e.g. { usage: "text" }) or use a role prefix like "text.", "icon.", "bg.", "border.", "ring."`;
-
-const missingSurfaceMessage = (role: string) =>
-  `Surface is required for role: "${role}". Provide surface explicitly (e.g. { surface: "surface" }) or use a role pattern like "bg.app", "bg.surface", "app.*"`;
-
-const normalizeBackgroundHint = (
-  hint: BackgroundHint | undefined,
-  strict: boolean,
-): BackgroundHint | undefined => {
-  if (!hint) {
-    return undefined;
-  }
-
-  if (hint.kind === "auto") {
-    return hint;
-  }
-
-  if (hint.kind === "role") {
-    const trimmedRole = normalizeRole(hint.role);
-    return { kind: "role", role: trimmedRole };
-  }
-
-  if (hint.kind === "color") {
-    const value = hint.value.trim();
-    if (!value) {
-      throw new Error("Background hint color value is required");
-    }
-
-    if (!hexColorPattern.test(value)) {
-      if (strict) {
-        throw new Error(`Invalid background hint color value: "${hint.value}"`);
-      }
-
-      warn(`Unvalidated background hint color value: "${hint.value}"`);
-    }
-
-    return { kind: "color", value };
-  }
-
-  throw new Error(`Invalid background hint kind: "${(hint as BackgroundHint).kind}"`);
-};
-
-const normalizeContrast = (
-  contrast: ContrastRequirement | undefined,
-): ContrastRequirement | undefined => {
-  if (!contrast) {
-    return undefined;
-  }
-
-  if (contrast.model === "apca") {
-    if (!Number.isFinite(contrast.targetLc)) {
-      throw new Error("APCA targetLc must be a number");
-    }
-
-    if (contrast.minLc !== undefined && !Number.isFinite(contrast.minLc)) {
-      throw new Error("APCA minLc must be a number");
-    }
-
-    if (contrast.maxLc !== undefined && !Number.isFinite(contrast.maxLc)) {
-      throw new Error("APCA maxLc must be a number");
-    }
-
-    // Validate logical relationships between APCA contrast bounds
-    if (contrast.minLc !== undefined && contrast.maxLc !== undefined) {
-      if (contrast.minLc > contrast.maxLc) {
-        throw new Error("APCA minLc cannot be greater than maxLc");
-      }
-    }
-
-    if (contrast.minLc !== undefined && contrast.minLc > contrast.targetLc) {
-      throw new Error("APCA minLc cannot be greater than targetLc");
-    }
-
-    if (contrast.maxLc !== undefined && contrast.targetLc > contrast.maxLc) {
-      throw new Error("APCA targetLc cannot be greater than maxLc");
-    }
-    return contrast;
-  }
-
-  if (contrast.model === "wcag2") {
-    const minRatio =
-      "minRatio" in contrast ? contrast.minRatio : (contrast as { ratio?: number }).ratio;
-
-    if (minRatio === undefined) {
-      throw new Error("WCAG2 contrast requires either 'minRatio' or legacy 'ratio' property");
-    }
-
-    if (!Number.isFinite(minRatio)) {
-      throw new Error("WCAG2 minRatio must be a number");
-    }
-
-    return { model: "wcag2", minRatio };
-  }
-
-  if (contrast.model === "none") {
-    return contrast;
-  }
-
-  throw new Error(`Invalid contrast model: "${(contrast as ContrastRequirement).model}"`);
-};
-
-const validateIncludeSpaces = (includeSpaces: ColorSpace[] | undefined): ColorSpace[] => {
-  const value = includeSpaces ?? [];
-
-  value.forEach((space) => {
-    assertOneOf(space, colorSpaces, "output includeSpaces");
-  });
-
-  return value;
-};
-
-const normalizeAlpha = (alpha: AlphaStrategy | undefined): AlphaStrategy | undefined => {
-  if (!alpha) {
-    return undefined;
-  }
-
-  if (alpha.mode === "none") {
-    return alpha;
-  }
-
-  if (alpha.mode === "fixed") {
-    if (!Number.isFinite(alpha.alpha)) {
-      throw new Error("Fixed alpha must be a number");
-    }
-
-    return alpha;
-  }
-
-  if (alpha.mode === "solveOnBackground") {
-    return alpha;
-  }
-
-  throw new Error(`Invalid alpha strategy mode: "${(alpha as AlphaStrategy).mode}"`);
-};
-
-const normalizeOutput = (
-  output: OutputOptions | undefined,
-): Required<Omit<OutputOptions, "format">> => {
-  const preferSpaceValue = formatString(output?.preferSpace);
-  const gamutMappingValue = formatString(output?.gamutMapping);
-  const srgbFormatValue = formatString(output?.srgbFormat);
-  const includeSpaces = validateIncludeSpaces(output?.includeSpaces);
-
-  const preferSpace = preferSpaceValue
-    ? assertOneOf(preferSpaceValue, colorSpaces, "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");
-  }
-
-  if (output?.includeMeta !== undefined && typeof output.includeMeta !== "boolean") {
-    throw new Error("Output includeMeta must be a boolean");
-  }
-
-  return {
-    preferSpace,
-    includeSpaces,
-    gamutMapping,
-    strict: output?.strict ?? false,
-    precision: {
-      l: 1,
-      c: 3,
-      h: 1,
-      ...output?.precision,
-    },
-    includeMeta: output?.includeMeta ?? false,
-    srgbFormat,
-  };
-};
-
-/**
- * Normalize a user-facing ColorQuery into a fully populated, validated structure.
- *
- * - Applies defaults for missing fields (context, surface, state, emphasis, output).
- * - Infers usage and surface from role naming patterns when not provided.
- * - In strict mode, missing required fields throw actionable errors.
- * - In non-strict mode, safe defaults are applied with explicit warnings.
- * - Validates nested objects (background hints, contrast requirements, alpha strategies).
- * - Trims string inputs and enforces allowed enum values.
- *
- * @example
- * normalizeQuery({ role: "text.primary" });
- * @example
- * normalizeQuery({
- *   role: "bg.canvas",
- *   on: { kind: "color", value: "#fff" },
- *   contrast: { model: "apca", targetLc: 60 },
- *   output: { strict: true },
- * });
- */
-export function normalizeQuery(q: ColorQuery): NormalizedQuery {
-  const role = normalizeRole(formatString(q.role));
-  const contextValue = formatString(q.context) ?? "light";
-  const inferredSurface = inferSurfaceFromRole(role);
-  const surfaceValue = formatString(q.surface) ?? inferredSurface ?? "surface";
-  const stateValue = formatString(q.state) ?? "default";
-  const emphasisValue = formatString(q.emphasis) ?? "default";
-  const output = normalizeOutput(q.output);
-  const usageValue = formatString(q.usage) ?? inferUsageFromRole(role);
-  const variantValue = formatString(q.variant) ?? inferVariantFromRole(role);
-
-  if (!usageValue) {
-    if (output.strict) {
-      throw new Error(missingUsageMessage(role));
-    }
-
-    warnInferenceOnce(
-      `usage:${role}`,
-      `Defaulting usage to "bg" for role: "${role}". ${missingUsageMessage(role)}`,
-    );
-  }
-
-  if (!formatString(q.surface) && !inferredSurface) {
-    if (output.strict) {
-      throw new Error(missingSurfaceMessage(role));
-    }
-
-    warnInferenceOnce(
-      `surface:${role}`,
-      `Defaulting surface to "surface" for role: "${role}". ${missingSurfaceMessage(role)}`,
-    );
-  }
-
-  return {
-    role,
-    usage: assertOneOf(usageValue ?? "bg", usages, "usage"),
-    context: assertOneOf(contextValue, contexts, "context"),
-    surface: assertOneOf(surfaceValue, surfaces, "surface"),
-    state: assertOneOf(stateValue, COLOR_STATES, "state"),
-    emphasis: assertOneOf(emphasisValue, emphases, "emphasis"),
-    variant: normalizeVariant(variantValue),
-    on: normalizeBackgroundHint(q.on, output.strict),
-    contrast: normalizeContrast(q.contrast),
-    alpha: normalizeAlpha(q.alpha),
-    output,
-  };
-}
-
-/**
- * Normalize a user-facing OnSolidQuery into a fully populated, validated structure.
- *
- * - Applies defaults for missing fields (context, state, emphasis, output).
- * - Validates usage ("text" | "icon") and required background role.
- * - Validates nested objects (contrast requirements, alpha strategies).
- */
-export function normalizeOnSolidQuery(q: OnSolidQuery): NormalizedOnSolidQuery {
-  const bgRole = normalizeBgRole(formatString(q.bgRole));
-  const usageValue = formatString(q.usage);
-  const contextValue = formatString(q.context) ?? "light";
-  const stateValue = formatString(q.state) ?? "default";
-  const emphasisValue = formatString(q.emphasis) ?? "default";
-  const output = normalizeOutput(q.output);
-
-  if (!usageValue) {
-    throw new Error("On-solid usage is required (text or icon)");
-  }
-
-  return {
-    bgRole,
-    usage: assertOneOf(usageValue, onSolidUsages, "onSolid usage"),
-    context: assertOneOf(contextValue, contexts, "context"),
-    state: assertOneOf(stateValue, COLOR_STATES, "state"),
-    emphasis: assertOneOf(emphasisValue, emphases, "emphasis"),
-    contrast: normalizeContrast(q.contrast),
-    alpha: normalizeAlpha(q.alpha),
-    output,
-  };
-}