@clhaas/palette-kit 0.1.8 → 0.3.0

package/src/engine/normalize.ts

@@ -0,0 +1,550 @@
+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,
+  };
+}