@getvitops/utils 8.0.1 → 8.2.0-alpha.0

package/dist/color/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","names":["OKLCH_Space","sRGB_Space","P3_Space"],"sources":["../../src/color/colors.ts","../../src/color/color-harmony.ts"],"sourcesContent":["import Color from 'colorjs.io';\nimport {\n  OKLCH as OKLCH_Space,\n  sRGB as sRGB_Space,\n  P3 as P3_Space,\n  ColorSpace,\n  to,\n  toGamutCSS,\n  clone,\n  serialize,\n  type PlainColorObject,\n} from 'colorjs.io/fn';\n\nColorSpace.register(OKLCH_Space);\nColorSpace.register(sRGB_Space);\nColorSpace.register(P3_Space);\n\nexport interface RgbResult {\n  r: number;\n  g: number;\n  b: number;\n  inGamut: boolean;\n  /** Max channel overshoot beyond [0,1] before clamping. 0 when in gamut. */\n  gamutDistance: number;\n}\n\n/**\n * Convert OKLCh to sRGB, returning 0-255 clamped values with gamut flag.\n * Fast path for per-pixel canvas rendering (no gamut mapping, just clamp).\n */\nexport function oklchToSrgb(l: number, c: number, h: number): RgbResult {\n  const col: PlainColorObject = { space: OKLCH_Space, coords: [l, c, h], alpha: 1 };\n  const rgb = to(col, sRGB_Space);\n  const [r, g, b] = rgb.coords;\n  const inGamut = r >= 0 && r <= 1 && g >= 0 && g <= 1 && b >= 0 && b <= 1;\n  const gamutDistance = inGamut ? 0 : Math.max(-r, r - 1, -g, g - 1, -b, b - 1, 0);\n  return {\n    r: Math.max(0, Math.min(255, Math.round(r * 255))),\n    g: Math.max(0, Math.min(255, Math.round(g * 255))),\n    b: Math.max(0, Math.min(255, Math.round(b * 255))),\n    inGamut,\n    gamutDistance,\n  };\n}\n\n/**\n * Convert OKLCh to Display P3, returning 0-255 clamped values with gamut flag.\n * Fast path for per-pixel canvas rendering on P3 displays.\n */\nexport function oklchToP3(l: number, c: number, h: number): RgbResult {\n  const col: PlainColorObject = { space: OKLCH_Space, coords: [l, c, h], alpha: 1 };\n  const rgb = to(col, P3_Space);\n  const [r, g, b] = rgb.coords;\n  const inGamut = r >= 0 && r <= 1 && g >= 0 && g <= 1 && b >= 0 && b <= 1;\n  const gamutDistance = inGamut ? 0 : Math.max(-r, r - 1, -g, g - 1, -b, b - 1, 0);\n  return {\n    r: Math.max(0, Math.min(255, Math.round(r * 255))),\n    g: Math.max(0, Math.min(255, Math.round(g * 255))),\n    b: Math.max(0, Math.min(255, Math.round(b * 255))),\n    inGamut,\n    gamutDistance,\n  };\n}\n\n/**\n * Gamut-map an OKLCh color using the CSS gamut mapping algorithm, return hex.\n * Slower than oklchToSrgb/oklchToP3 (uses iterative reduction), use for single colors only.\n */\nexport function gamutMapOklchToHex(\n  l: number,\n  c: number,\n  h: number,\n  space: 'srgb' | 'p3' = 'srgb',\n): string {\n  const col: PlainColorObject = { space: OKLCH_Space, coords: [l, c, h], alpha: 1 };\n  const targetSpace = space === 'p3' ? P3_Space : sRGB_Space;\n  const mapped = toGamutCSS(clone(col), { space: targetSpace });\n  const rgb = to(mapped, sRGB_Space);\n  return serialize(rgb, { format: 'hex' });\n}\n\n// Standard 11-step scale - will be transposed based on input anchors\nexport const STEP_NAMES = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;\nexport type StepName = (typeof STEP_NAMES)[number];\n\nexport const COLOR_GROUPS = [\n  'neutral',\n  'brand',\n  'primary',\n  'accent',\n  'complement',\n  'success',\n  'warning',\n  'error',\n  'info',\n] as const;\nexport type ColorGroup = (typeof COLOR_GROUPS)[number];\n\n/**\n * Convert hex color to OKLCH components\n */\nexport function hexToOklch(hex: string): { l: number; c: number; h: number } {\n  const color = new Color(hex);\n  const oklch = color.to('oklch');\n  return {\n    l: oklch.coords[0],\n    c: oklch.coords[1],\n    h: oklch.coords[2] || 0,\n  };\n}\n\nexport function oklchToHex(oklch: { l: number; c: number; h: number }): string {\n  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);\n  const srgb = color.to('srgb');\n  if (!srgb.inGamut()) {\n    srgb.toGamut({ method: 'css' });\n  }\n  return srgb.toString({ format: 'hex' });\n}\n\n/**\n * Convert OKLCH CSS string to hex color\n * @example oklchStringToHex(\"oklch(50% 0.15 270)\") => \"#8b5cf6\"\n */\nexport function oklchStringToHex(oklchString: string): string {\n  try {\n    const color = new Color(oklchString);\n    const srgb = color.to('srgb');\n    if (!srgb.inGamut()) {\n      srgb.toGamut({ method: 'css' });\n    }\n    return srgb.toString({ format: 'hex' });\n  } catch {\n    return '#808080';\n  }\n}\n\n/**\n * Format a color name by separating compound words\n * Examples: \"mediumseagreen\" -> \"Medium Sea Green\", \"darkblue\" -> \"Dark Blue\"\n */\nexport function formatColorName(name: string): string {\n  if (!name) return 'Unknown';\n\n  const specialCases: Record<string, string> = {\n    aliceblue: 'Alice Blue',\n    antiquewhite: 'Antique White',\n    blanchedalmond: 'Blanched Almond',\n    blueviolet: 'Blue Violet',\n    burlywood: 'Burly Wood',\n    cadetblue: 'Cadet Blue',\n    cornflowerblue: 'Cornflower Blue',\n    darkblue: 'Dark Blue',\n    darkcyan: 'Dark Cyan',\n    darkgoldenrod: 'Dark Goldenrod',\n    darkgray: 'Dark Gray',\n    darkgreen: 'Dark Green',\n    darkgrey: 'Dark Grey',\n    darkkhaki: 'Dark Khaki',\n    darkmagenta: 'Dark Magenta',\n    darkolivegreen: 'Dark Olive Green',\n    darkorange: 'Dark Orange',\n    darkorchid: 'Dark Orchid',\n    darkred: 'Dark Red',\n    darksalmon: 'Dark Salmon',\n    darkseagreen: 'Dark Sea Green',\n    darkslateblue: 'Dark Slate Blue',\n    darkslategray: 'Dark Slate Gray',\n    darkslategrey: 'Dark Slate Grey',\n    darkturquoise: 'Dark Turquoise',\n    darkviolet: 'Dark Violet',\n    deeppink: 'Deep Pink',\n    deepskyblue: 'Deep Sky Blue',\n    dimgray: 'Dim Gray',\n    dimgrey: 'Dim Grey',\n    dodgerblue: 'Dodger Blue',\n    floralwhite: 'Floral White',\n    forestgreen: 'Forest Green',\n    ghostwhite: 'Ghost White',\n    greenyellow: 'Green Yellow',\n    hotpink: 'Hot Pink',\n    indianred: 'Indian Red',\n    lavenderblush: 'Lavender Blush',\n    lawngreen: 'Lawn Green',\n    lemonchiffon: 'Lemon Chiffon',\n    lightblue: 'Light Blue',\n    lightcoral: 'Light Coral',\n    lightcyan: 'Light Cyan',\n    lightgoldenrodyellow: 'Light Goldenrod Yellow',\n    lightgray: 'Light Gray',\n    lightgreen: 'Light Green',\n    lightgrey: 'Light Grey',\n    lightpink: 'Light Pink',\n    lightsalmon: 'Light Salmon',\n    lightseagreen: 'Light Sea Green',\n    lightskyblue: 'Light Sky Blue',\n    lightslategray: 'Light Slate Gray',\n    lightslategrey: 'Light Slate Grey',\n    lightsteelblue: 'Light Steel Blue',\n    lightyellow: 'Light Yellow',\n    limegreen: 'Lime Green',\n    mediumaquamarine: 'Medium Aquamarine',\n    mediumblue: 'Medium Blue',\n    mediumorchid: 'Medium Orchid',\n    mediumpurple: 'Medium Purple',\n    mediumseagreen: 'Medium Sea Green',\n    mediumslateblue: 'Medium Slate Blue',\n    mediumspringgreen: 'Medium Spring Green',\n    mediumturquoise: 'Medium Turquoise',\n    mediumvioletred: 'Medium Violet Red',\n    midnightblue: 'Midnight Blue',\n    mintcream: 'Mint Cream',\n    mistyrose: 'Misty Rose',\n    navajowhite: 'Navajo White',\n    oldlace: 'Old Lace',\n    olivedrab: 'Olive Drab',\n    orangered: 'Orange Red',\n    palegoldenrod: 'Pale Goldenrod',\n    palegreen: 'Pale Green',\n    paleturquoise: 'Pale Turquoise',\n    palevioletred: 'Pale Violet Red',\n    papayawhip: 'Papaya Whip',\n    peachpuff: 'Peach Puff',\n    powderblue: 'Powder Blue',\n    rosybrown: 'Rosy Brown',\n    royalblue: 'Royal Blue',\n    saddlebrown: 'Saddle Brown',\n    sandybrown: 'Sandy Brown',\n    seagreen: 'Sea Green',\n    skyblue: 'Sky Blue',\n    slateblue: 'Slate Blue',\n    slategray: 'Slate Gray',\n    slategrey: 'Slate Grey',\n    springgreen: 'Spring Green',\n    steelblue: 'Steel Blue',\n    whitesmoke: 'White Smoke',\n    yellowgreen: 'Yellow Green',\n  };\n\n  const lowerName = name.toLowerCase();\n  if (specialCases[lowerName]) {\n    return specialCases[lowerName];\n  }\n\n  // Default: just capitalize first letter\n  return name.charAt(0).toUpperCase() + name.slice(1);\n}\n\n/**\n * Get the closest CSS color name for a hex color\n */\nexport function getColorName(hex: string): string {\n  try {\n    const color = new Color(hex);\n    const oklch = color.to('oklch');\n    const hue = oklch.coords[2] || 0;\n\n    if (hue < 30 || hue >= 330) return 'Red';\n    if (hue < 60) return 'Orange';\n    if (hue < 90) return 'Yellow';\n    if (hue < 150) return 'Green';\n    if (hue < 210) return 'Cyan';\n    if (hue < 270) return 'Blue';\n    if (hue < 330) return 'Purple';\n    return 'Unknown';\n  } catch {\n    return 'Unknown';\n  }\n}\n\n/**\n * Get color name with hue value\n */\nexport function getColorNameWithHue(hex: string): string {\n  try {\n    const color = new Color(hex);\n    const oklch = color.to('oklch');\n    const hue = oklch.coords[2] || 0;\n    const roundedHue = Math.round(hue / 10) * 10;\n    const name = getColorName(hex);\n    return `${name} ${roundedHue}`;\n  } catch {\n    return 'Unknown';\n  }\n}\n\n// Color harmony definitions\nexport const HARMONY_TYPES = [\n  'single',\n  'analogous',\n  'triad',\n  'complementary',\n  'split-complementary',\n  'square',\n  'compound',\n] as const;\nexport type HarmonyType = (typeof HARMONY_TYPES)[number];\n\nexport interface HarmonyDefinition {\n  label: string;\n  offsets: number[];\n  primaryIndex: number;\n}\n\nexport const HARMONY_DEFINITIONS: Record<HarmonyType, HarmonyDefinition> = {\n  single: {\n    label: 'Single',\n    offsets: [0],\n    primaryIndex: 0,\n  },\n  analogous: {\n    label: 'Analogous',\n    offsets: [-30, 0, 30],\n    primaryIndex: 1,\n  },\n  triad: {\n    label: 'Triad',\n    offsets: [0, 120, 240],\n    primaryIndex: 0,\n  },\n  complementary: {\n    label: 'Complementary',\n    offsets: [0, 180],\n    primaryIndex: 0,\n  },\n  'split-complementary': {\n    label: 'Split Complementary',\n    offsets: [0, 150, 210],\n    primaryIndex: 0,\n  },\n  square: {\n    label: 'Square',\n    offsets: [0, 90, 180, 270],\n    primaryIndex: 0,\n  },\n  compound: {\n    label: 'Compound',\n    offsets: [-30, 0, 180, 210],\n    primaryIndex: 1,\n  },\n};\n\n/**\n * The shared lightness ladder every ramp is built on (lightest → darkest).\n *\n * Fixed, NOT seed-derived. Two hues at the same step have to read equally light,\n * otherwise one contrast table cannot serve every hue and a `muted` variant means\n * something different depending on which role you ask. Only chroma and hue vary\n * between ramps.\n *\n * The previous engine transposed this curve onto each seed, which let relative\n * luminance at step 300 range from 0.253 (rust) to 0.384 (amber) across the\n * shipped palette — the drift this replaces.\n *\n * Anchored steps are the one deliberate exception: see `generateOklchPalette`.\n */\nexport const LIGHTNESS_LADDER: Record<StepName, number> = {\n  50: 0.98,\n  100: 0.95,\n  200: 0.9,\n  300: 0.83,\n  400: 0.74,\n  500: 0.65,\n  600: 0.54,\n  700: 0.47,\n  800: 0.38,\n  900: 0.29,\n  950: 0.21,\n};\n\n/**\n * Chroma a ramp decays *towards* beyond its outermost anchors, so the near-white\n * and near-black ends keep a whisper of the hue instead of going flat grey. The\n * dark end carries slightly more because chroma reads weaker against black.\n *\n * It is a CEILING, not a target — `Math.min(ENDPOINT_CHROMA.x, anchor.c)`. That\n * distinction is the whole reason a neutral is authorable. The interpolation\n * factor reaches exactly 1 at steps 50 and 950 for every anchor position, so as a\n * target it made the endpoints these constants *unconditionally*: seeds at chroma\n * 0.001, 0.002, 0.05 and 0.2 all produced a byte-identical step 50. A brand\n * wanting plain white with grey panels had no seed that worked, and chroma 0 was\n * worst of all — colorjs returns NaN hue for a true achromatic colour, which\n * `hexToOklch` collapses to 0, so the \"neutral\" came out pink.\n *\n * As a ceiling, a low-chroma seed simply stays low and a chroma-0 seed stays 0 at\n * every unanchored step, which makes the NaN-hue collapse invisible rather than\n * something `hexToOklch` has to solve (its `|| 0` is load-bearing for\n * `getColorName`).\n */\nexport const ENDPOINT_CHROMA = { light: 0.008, dark: 0.015 } as const;\n\ninterface OklchColor {\n  l: number;\n  c: number;\n  h: number;\n}\n\n/**\n * Parses an OKLCH CSS string into numerical components.\n * @param oklchString - e.g., 'oklch(50% 0.15 270)'\n * @returns Lightness (0-1), Chroma (0-~0.37), Hue (0-360)\n */\nexport function parseOklch(oklchString: string): OklchColor {\n  const parts = oklchString.match(/oklch\\(([^ ]+) ([^ ]+) ([^ ]+)\\)/);\n  if (!parts) throw new Error('Invalid OKLCH string format.');\n\n  const [, lRaw = '', cRaw = '', hRaw = ''] = parts;\n  const l = parseFloat(lRaw) / (lRaw.includes('%') ? 100 : 1);\n  const c = parseFloat(cRaw);\n  const h = parseFloat(hRaw);\n\n  return { l, c, h };\n}\n\n/**\n * Linearly interpolates a value between a start and end point.\n */\nfunction lerp(start: number, end: number, factor: number): number {\n  return start + factor * (end - start);\n}\n\n/**\n * Interpolate hue the short way round the wheel. A ramp anchored at 350° and 10°\n * spans 20°, not 340° — the naive lerp sent it the long way through cyan.\n */\nfunction lerpHue(start: number, end: number, factor: number): number {\n  const delta = ((((end - start) % 360) + 540) % 360) - 180;\n  return (start + delta * factor + 360) % 360;\n}\n\n/**\n * The ladder step whose lightness is closest to `lightness` — i.e. where a\n * supplied colour naturally belongs.\n */\nexport function assignStepByLightness(lightness: number): StepName {\n  let closestStep: StepName = 500;\n  let minDiff = Math.abs(lightness - LIGHTNESS_LADDER[500]);\n\n  for (const step of STEP_NAMES) {\n    const diff = Math.abs(lightness - LIGHTNESS_LADDER[step]);\n    if (diff < minDiff) {\n      minDiff = diff;\n      closestStep = step;\n    }\n  }\n\n  return closestStep;\n}\n\n/**\n * How far an anchored colour sits from its step's ladder lightness.\n *\n * The generator surfaces this as a warning: a large deviation is legal (the\n * caller asked for that exact colour) but it means the hue will read heavier or\n * lighter than its siblings at that step, which is worth knowing rather than\n * discovering later.\n */\nexport function ladderDeviation(step: StepName, lightness: number): number {\n  return lightness - LIGHTNESS_LADDER[step];\n}\n\n/** Absolute chroma ceiling — beyond this nothing survives gamut mapping anyway. */\nconst MAX_CHROMA = 0.37;\n\n/**\n * Build a complete 11-step OKLCH ramp from one or more anchor colours.\n *\n * **Ladder-first with exact anchors.** Every anchor is reproduced *verbatim* at\n * its step; every other step takes its lightness from `LIGHTNESS_LADDER`, with\n * chroma and hue interpolated between the flanking anchors and decayed toward\n * `ENDPOINT_CHROMA` beyond the outermost ones.\n *\n * The consequence is the point: a client's brand hex survives byte-for-byte,\n * while the other ten steps stay directly comparable to every other hue. The\n * deviation from the ladder is bounded and *local to anchored steps* — unlike\n * the previous engine, which warped the whole ramp to fit its anchors so every\n * step drifted.\n *\n * Chroma may come out beyond the sRGB gamut here; that is deliberate.\n * `oklchStringToHex` gamut-maps with the CSS algorithm, which reduces chroma\n * while holding lightness, so the ladder survives the conversion.\n */\nexport function generateOklchPalette(\n  input: string | string[] | Record<string, string>,\n): Record<StepName, string> {\n  let anchors: Record<number, string> = {};\n\n  if (typeof input === 'string') {\n    anchors[assignStepByLightness(parseOklch(input).l)] = input;\n  } else if (Array.isArray(input)) {\n    for (const colorStr of input) {\n      anchors[assignStepByLightness(parseOklch(colorStr).l)] = colorStr;\n    }\n  } else if (typeof input === 'object' && input !== null) {\n    anchors = { ...input };\n  } else {\n    throw new Error(\n      'Input must be a color string, array of colors, or object with step assignments',\n    );\n  }\n\n  const parsedAnchors: Record<number, OklchColor> = {};\n  for (const [key, value] of Object.entries(anchors)) {\n    parsedAnchors[Number(key)] = parseOklch(value);\n  }\n\n  const anchorSteps = Object.keys(parsedAnchors)\n    .map(Number)\n    .sort((a, b) => a - b) as StepName[];\n\n  // Interpolate across step *index*, not the numeric label: the labels aren't\n  // evenly spaced (50→100 is a smaller jump than 100→200), so lerping on them\n  // would bunch the ramp up at the light end.\n  const idx = (step: number) => STEP_NAMES.indexOf(step as StepName);\n  const lastIdx = STEP_NAMES.length - 1;\n\n  const palette: Record<number, string> = {};\n\n  for (const step of STEP_NAMES) {\n    // An anchor is the caller's exact colour. Emit it untouched.\n    if (parsedAnchors[step]) {\n      palette[step] = anchors[step] as string;\n      continue;\n    }\n\n    // `lighter` is the nearest anchor with a smaller step (50 is lightest);\n    // `darker` the nearest with a larger one.\n    const lighter = [...anchorSteps].reverse().find((s) => s < step);\n    const darker = anchorSteps.find((s) => s > step);\n\n    let chroma: number;\n    let hue: number;\n\n    if (lighter !== undefined && darker !== undefined) {\n      const a = parsedAnchors[lighter] as OklchColor;\n      const b = parsedAnchors[darker] as OklchColor;\n      const factor = (idx(step) - idx(lighter)) / (idx(darker) - idx(lighter));\n      chroma = lerp(a.c, b.c, factor);\n      hue = lerpHue(a.h, b.h, factor);\n    } else if (lighter !== undefined) {\n      // Past the darkest anchor — fade toward the tinted near-black end.\n      const a = parsedAnchors[lighter] as OklchColor;\n      const factor = (idx(step) - idx(lighter)) / (lastIdx - idx(lighter));\n      chroma = lerp(a.c, Math.min(ENDPOINT_CHROMA.dark, a.c), factor);\n      hue = a.h;\n    } else if (darker !== undefined) {\n      // Past the lightest anchor — fade toward the tinted near-white end.\n      const b = parsedAnchors[darker] as OklchColor;\n      const factor = (idx(darker) - idx(step)) / idx(darker);\n      chroma = lerp(b.c, Math.min(ENDPOINT_CHROMA.light, b.c), factor);\n      hue = b.h;\n    } else {\n      chroma = 0.1;\n      hue = 0;\n    }\n\n    const lightness = LIGHTNESS_LADDER[step];\n    const finalL = (lightness * 100).toFixed(2) + '%';\n    const finalC = Math.min(chroma, MAX_CHROMA).toFixed(4);\n    const finalH = hue.toFixed(2);\n\n    palette[step] = `oklch(${finalL} ${finalC} ${finalH})`;\n  }\n\n  return palette;\n}\n\n// ── Contrast + endpoints (for the functional-token layer) ────────────────────\n\n/** APCA lightness-contrast (Lc) magnitude between a foreground and background. */\nexport function contrastLc(fg: string, bg: string): number {\n  return Math.abs(new Color(bg).contrast(fg, 'APCA'));\n}\n\n/**\n * Pick a tinted near-white or near-black foreground for best contrast on `bg`\n * (a whisper of the background's hue mixed into off-white/off-black).\n */\nexport function pickOn(bg: string, hue?: number): string {\n  const h = hue ?? hexToOklch(bg).h;\n  const white = oklchToHex({ l: 0.98, c: 0.01, h });\n  const black = oklchToHex({ l: 0.16, c: 0.02, h });\n  return contrastLc(white, bg) >= contrastLc(black, bg) ? white : black;\n}\n\n/**\n * The tinted off-white / off-black endpoints for a hue — white/black with a\n * whisper of the hue mixed in. These are the text/background tints every ramp\n * needs (and the one exception strict brand kits allow).\n *\n * Derived from `LIGHTNESS_LADDER` and `ENDPOINT_CHROMA` rather than its own\n * literals, so a strict tone kit's endpoints land on the same ladder rungs a\n * generated ramp would have used. This is the single definition — callers must\n * not hand-write their own near-white/near-black.\n */\nexport function tintedEndpoints(hue: number, chroma?: number): { light: string; dark: string } {\n  return {\n    light: oklchToHex({\n      l: LIGHTNESS_LADDER[50],\n      c: Math.min(chroma ?? ENDPOINT_CHROMA.light, 0.02),\n      h: hue,\n    }),\n    dark: oklchToHex({\n      l: LIGHTNESS_LADDER[950],\n      c: Math.min((chroma ?? ENDPOINT_CHROMA.dark) * 1.5, 0.03),\n      h: hue,\n    }),\n  };\n}\n","/**\n * Color harmony strategies for generating complementary colors\n */\n\nexport type HarmonyStrategy =\n  | 'complement'\n  | 'analogous-plus'\n  | 'analogous-minus'\n  | 'triadic-plus'\n  | 'triadic-minus'\n  | 'split-plus'\n  | 'split-minus'\n  | 'tetradic-plus'\n  | 'tetradic-minus';\n\nexport interface HarmonyOption {\n  id: HarmonyStrategy;\n  label: string;\n  description: string;\n  hueShift: number;\n}\n\nexport const HARMONY_STRATEGIES: HarmonyOption[] = [\n  {\n    id: 'complement',\n    label: 'Complement',\n    description: 'Opposite on color wheel (high contrast)',\n    hueShift: 180,\n  },\n  {\n    id: 'analogous-plus',\n    label: 'Analogous+',\n    description: 'Adjacent colors (harmonious)',\n    hueShift: 30,\n  },\n  {\n    id: 'analogous-minus',\n    label: 'Analogous-',\n    description: 'Adjacent colors (harmonious)',\n    hueShift: -30,\n  },\n  {\n    id: 'triadic-plus',\n    label: 'Triadic+',\n    description: 'Evenly spaced (balanced)',\n    hueShift: 120,\n  },\n  {\n    id: 'triadic-minus',\n    label: 'Triadic-',\n    description: 'Evenly spaced (balanced)',\n    hueShift: -120,\n  },\n  {\n    id: 'split-plus',\n    label: 'Split Complement+',\n    description: 'Near opposite (softer contrast)',\n    hueShift: 150,\n  },\n  {\n    id: 'split-minus',\n    label: 'Split Complement-',\n    description: 'Near opposite (softer contrast)',\n    hueShift: -150,\n  },\n  {\n    id: 'tetradic-plus',\n    label: 'Tetradic+',\n    description: 'Square spacing (rich palette)',\n    hueShift: 90,\n  },\n  {\n    id: 'tetradic-minus',\n    label: 'Tetradic-',\n    description: 'Square spacing (rich palette)',\n    hueShift: -90,\n  },\n];\n\n/**\n * Applies a harmony strategy to a hue value\n */\nexport function applyHarmonyStrategy(baseHue: number, strategy: HarmonyStrategy): number {\n  const harmonyOption = HARMONY_STRATEGIES.find((h) => h.id === strategy);\n  if (!harmonyOption) return baseHue;\n\n  let newHue = baseHue + harmonyOption.hueShift;\n\n  // Normalize to 0-360 range\n  while (newHue < 0) newHue += 360;\n  while (newHue >= 360) newHue -= 360;\n\n  return newHue;\n}\n\n/**\n * Gets all harmony suggestions for a given base hue\n */\nexport function getHarmonySuggestions(\n  baseHue: number,\n): Array<{ strategy: HarmonyStrategy; hue: number; label: string; description: string }> {\n  return HARMONY_STRATEGIES.map((strategy) => ({\n    strategy: strategy.id,\n    hue: applyHarmonyStrategy(baseHue, strategy.id),\n    label: strategy.label,\n    description: strategy.description,\n  }));\n}\n\n/**\n * Default functional color hues (if user doesn't specify)\n */\nexport const DEFAULT_FUNCTIONAL_HUES = {\n  success: 142, // Green\n  warning: 38, // Orange/Amber\n  error: 0, // Red\n  info: 200, // Blue\n} as const;\n\n/**\n * Suggests a functional color hue based on existing palette to maintain harmony\n */\nexport function suggestFunctionalColorHue(\n  type: keyof typeof DEFAULT_FUNCTIONAL_HUES,\n  existingHues: number[],\n): number {\n  const defaultHue = DEFAULT_FUNCTIONAL_HUES[type];\n\n  if (existingHues.length === 0) {\n    return defaultHue;\n  }\n\n  // Find the closest existing hue and adjust slightly to maintain harmony\n  const avgHue = existingHues.reduce((sum, h) => sum + h, 0) / existingHues.length;\n\n  // Rotate the default hue to be more in line with the palette's color temperature\n  const hueShift = avgHue - 200; // Assuming 200 is neutral blue\n  let adjustedHue = defaultHue + hueShift * 0.3; // 30% influence\n\n  // Normalize\n  while (adjustedHue < 0) adjustedHue += 360;\n  while (adjustedHue >= 360) adjustedHue -= 360;\n\n  return adjustedHue;\n}\n"],"mappings":"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"}
+{"version":3,"file":"index.mjs","names":["OKLCH_Space","sRGB_Space","P3_Space"],"sources":["../../src/color/colors.ts","../../src/color/color-harmony.ts"],"sourcesContent":["import Color from 'colorjs.io';\nimport {\n  OKLCH as OKLCH_Space,\n  sRGB as sRGB_Space,\n  P3 as P3_Space,\n  ColorSpace,\n  to,\n  toGamutCSS,\n  clone,\n  serialize,\n  type PlainColorObject,\n} from 'colorjs.io/fn';\n\nColorSpace.register(OKLCH_Space);\nColorSpace.register(sRGB_Space);\nColorSpace.register(P3_Space);\n\nexport interface RgbResult {\n  r: number;\n  g: number;\n  b: number;\n  inGamut: boolean;\n  /** Max channel overshoot beyond [0,1] before clamping. 0 when in gamut. */\n  gamutDistance: number;\n}\n\n/**\n * Convert OKLCh to sRGB, returning 0-255 clamped values with gamut flag.\n * Fast path for per-pixel canvas rendering (no gamut mapping, just clamp).\n */\nexport function oklchToSrgb(l: number, c: number, h: number): RgbResult {\n  const col: PlainColorObject = { space: OKLCH_Space, coords: [l, c, h], alpha: 1 };\n  const rgb = to(col, sRGB_Space);\n  const [r, g, b] = rgb.coords;\n  const inGamut = r >= 0 && r <= 1 && g >= 0 && g <= 1 && b >= 0 && b <= 1;\n  const gamutDistance = inGamut ? 0 : Math.max(-r, r - 1, -g, g - 1, -b, b - 1, 0);\n  return {\n    r: Math.max(0, Math.min(255, Math.round(r * 255))),\n    g: Math.max(0, Math.min(255, Math.round(g * 255))),\n    b: Math.max(0, Math.min(255, Math.round(b * 255))),\n    inGamut,\n    gamutDistance,\n  };\n}\n\n/**\n * Convert OKLCh to Display P3, returning 0-255 clamped values with gamut flag.\n * Fast path for per-pixel canvas rendering on P3 displays.\n */\nexport function oklchToP3(l: number, c: number, h: number): RgbResult {\n  const col: PlainColorObject = { space: OKLCH_Space, coords: [l, c, h], alpha: 1 };\n  const rgb = to(col, P3_Space);\n  const [r, g, b] = rgb.coords;\n  const inGamut = r >= 0 && r <= 1 && g >= 0 && g <= 1 && b >= 0 && b <= 1;\n  const gamutDistance = inGamut ? 0 : Math.max(-r, r - 1, -g, g - 1, -b, b - 1, 0);\n  return {\n    r: Math.max(0, Math.min(255, Math.round(r * 255))),\n    g: Math.max(0, Math.min(255, Math.round(g * 255))),\n    b: Math.max(0, Math.min(255, Math.round(b * 255))),\n    inGamut,\n    gamutDistance,\n  };\n}\n\n/**\n * Gamut-map an OKLCh color using the CSS gamut mapping algorithm, return hex.\n * Slower than oklchToSrgb/oklchToP3 (uses iterative reduction), use for single colors only.\n */\nexport function gamutMapOklchToHex(\n  l: number,\n  c: number,\n  h: number,\n  space: 'srgb' | 'p3' = 'srgb',\n): string {\n  const col: PlainColorObject = { space: OKLCH_Space, coords: [l, c, h], alpha: 1 };\n  const targetSpace = space === 'p3' ? P3_Space : sRGB_Space;\n  const mapped = toGamutCSS(clone(col), { space: targetSpace });\n  const rgb = to(mapped, sRGB_Space);\n  return serialize(rgb, { format: 'hex' });\n}\n\n// Standard 11-step scale - will be transposed based on input anchors\nexport const STEP_NAMES = [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950] as const;\nexport type StepName = (typeof STEP_NAMES)[number];\n\nexport const COLOR_GROUPS = [\n  'neutral',\n  'brand',\n  'primary',\n  'accent',\n  'complement',\n  'success',\n  'warning',\n  'error',\n  'info',\n] as const;\nexport type ColorGroup = (typeof COLOR_GROUPS)[number];\n\n/**\n * Convert hex color to OKLCH components\n */\nexport function hexToOklch(hex: string): { l: number; c: number; h: number } {\n  const color = new Color(hex);\n  const oklch = color.to('oklch');\n  return {\n    l: oklch.coords[0],\n    c: oklch.coords[1],\n    h: oklch.coords[2] || 0,\n  };\n}\n\nexport function oklchToHex(oklch: { l: number; c: number; h: number }): string {\n  const color = new Color('oklch', [oklch.l, oklch.c, oklch.h]);\n  const srgb = color.to('srgb');\n  if (!srgb.inGamut()) {\n    srgb.toGamut({ method: 'css' });\n  }\n  return srgb.toString({ format: 'hex' });\n}\n\n/**\n * Convert OKLCH CSS string to hex color\n * @example oklchStringToHex(\"oklch(50% 0.15 270)\") => \"#8b5cf6\"\n */\nexport function oklchStringToHex(oklchString: string): string {\n  try {\n    const color = new Color(oklchString);\n    const srgb = color.to('srgb');\n    if (!srgb.inGamut()) {\n      srgb.toGamut({ method: 'css' });\n    }\n    return srgb.toString({ format: 'hex' });\n  } catch {\n    return '#808080';\n  }\n}\n\n/**\n * Format a color name by separating compound words\n * Examples: \"mediumseagreen\" -> \"Medium Sea Green\", \"darkblue\" -> \"Dark Blue\"\n */\nexport function formatColorName(name: string): string {\n  if (!name) return 'Unknown';\n\n  const specialCases: Record<string, string> = {\n    aliceblue: 'Alice Blue',\n    antiquewhite: 'Antique White',\n    blanchedalmond: 'Blanched Almond',\n    blueviolet: 'Blue Violet',\n    burlywood: 'Burly Wood',\n    cadetblue: 'Cadet Blue',\n    cornflowerblue: 'Cornflower Blue',\n    darkblue: 'Dark Blue',\n    darkcyan: 'Dark Cyan',\n    darkgoldenrod: 'Dark Goldenrod',\n    darkgray: 'Dark Gray',\n    darkgreen: 'Dark Green',\n    darkgrey: 'Dark Grey',\n    darkkhaki: 'Dark Khaki',\n    darkmagenta: 'Dark Magenta',\n    darkolivegreen: 'Dark Olive Green',\n    darkorange: 'Dark Orange',\n    darkorchid: 'Dark Orchid',\n    darkred: 'Dark Red',\n    darksalmon: 'Dark Salmon',\n    darkseagreen: 'Dark Sea Green',\n    darkslateblue: 'Dark Slate Blue',\n    darkslategray: 'Dark Slate Gray',\n    darkslategrey: 'Dark Slate Grey',\n    darkturquoise: 'Dark Turquoise',\n    darkviolet: 'Dark Violet',\n    deeppink: 'Deep Pink',\n    deepskyblue: 'Deep Sky Blue',\n    dimgray: 'Dim Gray',\n    dimgrey: 'Dim Grey',\n    dodgerblue: 'Dodger Blue',\n    floralwhite: 'Floral White',\n    forestgreen: 'Forest Green',\n    ghostwhite: 'Ghost White',\n    greenyellow: 'Green Yellow',\n    hotpink: 'Hot Pink',\n    indianred: 'Indian Red',\n    lavenderblush: 'Lavender Blush',\n    lawngreen: 'Lawn Green',\n    lemonchiffon: 'Lemon Chiffon',\n    lightblue: 'Light Blue',\n    lightcoral: 'Light Coral',\n    lightcyan: 'Light Cyan',\n    lightgoldenrodyellow: 'Light Goldenrod Yellow',\n    lightgray: 'Light Gray',\n    lightgreen: 'Light Green',\n    lightgrey: 'Light Grey',\n    lightpink: 'Light Pink',\n    lightsalmon: 'Light Salmon',\n    lightseagreen: 'Light Sea Green',\n    lightskyblue: 'Light Sky Blue',\n    lightslategray: 'Light Slate Gray',\n    lightslategrey: 'Light Slate Grey',\n    lightsteelblue: 'Light Steel Blue',\n    lightyellow: 'Light Yellow',\n    limegreen: 'Lime Green',\n    mediumaquamarine: 'Medium Aquamarine',\n    mediumblue: 'Medium Blue',\n    mediumorchid: 'Medium Orchid',\n    mediumpurple: 'Medium Purple',\n    mediumseagreen: 'Medium Sea Green',\n    mediumslateblue: 'Medium Slate Blue',\n    mediumspringgreen: 'Medium Spring Green',\n    mediumturquoise: 'Medium Turquoise',\n    mediumvioletred: 'Medium Violet Red',\n    midnightblue: 'Midnight Blue',\n    mintcream: 'Mint Cream',\n    mistyrose: 'Misty Rose',\n    navajowhite: 'Navajo White',\n    oldlace: 'Old Lace',\n    olivedrab: 'Olive Drab',\n    orangered: 'Orange Red',\n    palegoldenrod: 'Pale Goldenrod',\n    palegreen: 'Pale Green',\n    paleturquoise: 'Pale Turquoise',\n    palevioletred: 'Pale Violet Red',\n    papayawhip: 'Papaya Whip',\n    peachpuff: 'Peach Puff',\n    powderblue: 'Powder Blue',\n    rosybrown: 'Rosy Brown',\n    royalblue: 'Royal Blue',\n    saddlebrown: 'Saddle Brown',\n    sandybrown: 'Sandy Brown',\n    seagreen: 'Sea Green',\n    skyblue: 'Sky Blue',\n    slateblue: 'Slate Blue',\n    slategray: 'Slate Gray',\n    slategrey: 'Slate Grey',\n    springgreen: 'Spring Green',\n    steelblue: 'Steel Blue',\n    whitesmoke: 'White Smoke',\n    yellowgreen: 'Yellow Green',\n  };\n\n  const lowerName = name.toLowerCase();\n  if (specialCases[lowerName]) {\n    return specialCases[lowerName];\n  }\n\n  // Default: just capitalize first letter\n  return name.charAt(0).toUpperCase() + name.slice(1);\n}\n\n/**\n * Get the closest CSS color name for a hex color\n */\nexport function getColorName(hex: string): string {\n  try {\n    const color = new Color(hex);\n    const oklch = color.to('oklch');\n    const hue = oklch.coords[2] || 0;\n\n    if (hue < 30 || hue >= 330) return 'Red';\n    if (hue < 60) return 'Orange';\n    if (hue < 90) return 'Yellow';\n    if (hue < 150) return 'Green';\n    if (hue < 210) return 'Cyan';\n    if (hue < 270) return 'Blue';\n    if (hue < 330) return 'Purple';\n    return 'Unknown';\n  } catch {\n    return 'Unknown';\n  }\n}\n\n/**\n * Get color name with hue value\n */\nexport function getColorNameWithHue(hex: string): string {\n  try {\n    const color = new Color(hex);\n    const oklch = color.to('oklch');\n    const hue = oklch.coords[2] || 0;\n    const roundedHue = Math.round(hue / 10) * 10;\n    const name = getColorName(hex);\n    return `${name} ${roundedHue}`;\n  } catch {\n    return 'Unknown';\n  }\n}\n\n// Color harmony definitions\nexport const HARMONY_TYPES = [\n  'single',\n  'analogous',\n  'triad',\n  'complementary',\n  'split-complementary',\n  'square',\n  'compound',\n] as const;\nexport type HarmonyType = (typeof HARMONY_TYPES)[number];\n\nexport interface HarmonyDefinition {\n  label: string;\n  offsets: number[];\n  primaryIndex: number;\n}\n\nexport const HARMONY_DEFINITIONS: Record<HarmonyType, HarmonyDefinition> = {\n  single: {\n    label: 'Single',\n    offsets: [0],\n    primaryIndex: 0,\n  },\n  analogous: {\n    label: 'Analogous',\n    offsets: [-30, 0, 30],\n    primaryIndex: 1,\n  },\n  triad: {\n    label: 'Triad',\n    offsets: [0, 120, 240],\n    primaryIndex: 0,\n  },\n  complementary: {\n    label: 'Complementary',\n    offsets: [0, 180],\n    primaryIndex: 0,\n  },\n  'split-complementary': {\n    label: 'Split Complementary',\n    offsets: [0, 150, 210],\n    primaryIndex: 0,\n  },\n  square: {\n    label: 'Square',\n    offsets: [0, 90, 180, 270],\n    primaryIndex: 0,\n  },\n  compound: {\n    label: 'Compound',\n    offsets: [-30, 0, 180, 210],\n    primaryIndex: 1,\n  },\n};\n\n/**\n * The shared lightness ladder every ramp is built on (lightest → darkest).\n *\n * Fixed, NOT seed-derived. Two hues at the same step have to read equally light,\n * otherwise one contrast table cannot serve every hue and a `muted` variant means\n * something different depending on which role you ask. Only chroma and hue vary\n * between ramps.\n *\n * The previous engine transposed this curve onto each seed, which let relative\n * luminance at step 300 range from 0.253 (rust) to 0.384 (amber) across the\n * shipped palette — the drift this replaces.\n *\n * Anchored steps are the one deliberate exception: see `generateOklchPalette`.\n */\nexport const LIGHTNESS_LADDER: Record<StepName, number> = {\n  50: 0.98,\n  100: 0.95,\n  200: 0.9,\n  300: 0.83,\n  400: 0.74,\n  500: 0.65,\n  600: 0.54,\n  700: 0.47,\n  800: 0.38,\n  900: 0.29,\n  950: 0.21,\n};\n\n/**\n * Chroma a ramp decays *towards* beyond its outermost anchors, so the near-white\n * and near-black ends keep a whisper of the hue instead of going flat grey. The\n * dark end carries slightly more because chroma reads weaker against black.\n *\n * It is a CEILING, not a target — `Math.min(ENDPOINT_CHROMA.x, anchor.c)`. That\n * distinction is the whole reason a neutral is authorable. The interpolation\n * factor reaches exactly 1 at steps 50 and 950 for every anchor position, so as a\n * target it made the endpoints these constants *unconditionally*: seeds at chroma\n * 0.001, 0.002, 0.05 and 0.2 all produced a byte-identical step 50. A brand\n * wanting plain white with grey panels had no seed that worked, and chroma 0 was\n * worst of all — colorjs returns NaN hue for a true achromatic colour, which\n * `hexToOklch` collapses to 0, so the \"neutral\" came out pink.\n *\n * As a ceiling, a low-chroma seed simply stays low and a chroma-0 seed stays 0 at\n * every unanchored step, which makes the NaN-hue collapse invisible rather than\n * something `hexToOklch` has to solve (its `|| 0` is load-bearing for\n * `getColorName`).\n */\nexport const ENDPOINT_CHROMA = { light: 0.008, dark: 0.015 } as const;\n\ninterface OklchColor {\n  l: number;\n  c: number;\n  h: number;\n}\n\n/**\n * Parses an OKLCH CSS string into numerical components.\n * @param oklchString - e.g., 'oklch(50% 0.15 270)'\n * @returns Lightness (0-1), Chroma (0-~0.37), Hue (0-360)\n */\nexport function parseOklch(oklchString: string): OklchColor {\n  const parts = oklchString.match(/oklch\\(([^ ]+) ([^ ]+) ([^ ]+)\\)/);\n  if (!parts) throw new Error('Invalid OKLCH string format.');\n\n  const [, lRaw = '', cRaw = '', hRaw = ''] = parts;\n  const l = parseFloat(lRaw) / (lRaw.includes('%') ? 100 : 1);\n  const c = parseFloat(cRaw);\n  const h = parseFloat(hRaw);\n\n  return { l, c, h };\n}\n\n/**\n * Linearly interpolates a value between a start and end point.\n */\nfunction lerp(start: number, end: number, factor: number): number {\n  return start + factor * (end - start);\n}\n\n/**\n * Interpolate hue the short way round the wheel. A ramp anchored at 350° and 10°\n * spans 20°, not 340° — the naive lerp sent it the long way through cyan.\n */\nfunction lerpHue(start: number, end: number, factor: number): number {\n  const delta = ((((end - start) % 360) + 540) % 360) - 180;\n  return (start + delta * factor + 360) % 360;\n}\n\n/**\n * The ladder step whose lightness is closest to `lightness` — i.e. where a\n * supplied colour naturally belongs.\n */\nexport function assignStepByLightness(lightness: number): StepName {\n  let closestStep: StepName = 500;\n  let minDiff = Math.abs(lightness - LIGHTNESS_LADDER[500]);\n\n  for (const step of STEP_NAMES) {\n    const diff = Math.abs(lightness - LIGHTNESS_LADDER[step]);\n    if (diff < minDiff) {\n      minDiff = diff;\n      closestStep = step;\n    }\n  }\n\n  return closestStep;\n}\n\n/**\n * How far an anchored colour sits from its step's ladder lightness.\n *\n * The generator surfaces this as a warning: a large deviation is legal (the\n * caller asked for that exact colour) but it means the hue will read heavier or\n * lighter than its siblings at that step, which is worth knowing rather than\n * discovering later.\n */\nexport function ladderDeviation(step: StepName, lightness: number): number {\n  return lightness - LIGHTNESS_LADDER[step];\n}\n\n/** Absolute chroma ceiling — beyond this nothing survives gamut mapping anyway. */\nconst MAX_CHROMA = 0.37;\n\n/**\n * Build a complete 11-step OKLCH ramp from one or more anchor colours.\n *\n * **Ladder-first with exact anchors.** Every anchor is reproduced *verbatim* at\n * its step; every other step takes its lightness from `LIGHTNESS_LADDER`, with\n * chroma and hue interpolated between the flanking anchors and decayed toward\n * `ENDPOINT_CHROMA` beyond the outermost ones.\n *\n * The consequence is the point: a client's brand hex survives byte-for-byte,\n * while the other ten steps stay directly comparable to every other hue. The\n * deviation from the ladder is bounded and *local to anchored steps* — unlike\n * the previous engine, which warped the whole ramp to fit its anchors so every\n * step drifted.\n *\n * Chroma may come out beyond the sRGB gamut here; that is deliberate.\n * `oklchStringToHex` gamut-maps with the CSS algorithm, which reduces chroma\n * while holding lightness, so the ladder survives the conversion.\n */\nexport function generateOklchPalette(\n  input: string | string[] | Record<string, string>,\n): Record<StepName, string> {\n  let anchors: Record<number, string> = {};\n\n  if (typeof input === 'string') {\n    anchors[assignStepByLightness(parseOklch(input).l)] = input;\n  } else if (Array.isArray(input)) {\n    for (const colorStr of input) {\n      anchors[assignStepByLightness(parseOklch(colorStr).l)] = colorStr;\n    }\n  } else if (typeof input === 'object' && input !== null) {\n    anchors = { ...input };\n  } else {\n    throw new Error(\n      'Input must be a color string, array of colors, or object with step assignments',\n    );\n  }\n\n  const parsedAnchors: Record<number, OklchColor> = {};\n  for (const [key, value] of Object.entries(anchors)) {\n    parsedAnchors[Number(key)] = parseOklch(value);\n  }\n\n  const anchorSteps = Object.keys(parsedAnchors)\n    .map(Number)\n    .sort((a, b) => a - b) as StepName[];\n\n  // Interpolate across step *index*, not the numeric label: the labels aren't\n  // evenly spaced (50→100 is a smaller jump than 100→200), so lerping on them\n  // would bunch the ramp up at the light end.\n  const idx = (step: number) => STEP_NAMES.indexOf(step as StepName);\n  const lastIdx = STEP_NAMES.length - 1;\n\n  const palette: Record<number, string> = {};\n\n  for (const step of STEP_NAMES) {\n    // An anchor is the caller's exact colour. Emit it untouched.\n    if (parsedAnchors[step]) {\n      palette[step] = anchors[step] as string;\n      continue;\n    }\n\n    // `lighter` is the nearest anchor with a smaller step (50 is lightest);\n    // `darker` the nearest with a larger one.\n    const lighter = [...anchorSteps].reverse().find((s) => s < step);\n    const darker = anchorSteps.find((s) => s > step);\n\n    let chroma: number;\n    let hue: number;\n\n    if (lighter !== undefined && darker !== undefined) {\n      const a = parsedAnchors[lighter] as OklchColor;\n      const b = parsedAnchors[darker] as OklchColor;\n      const factor = (idx(step) - idx(lighter)) / (idx(darker) - idx(lighter));\n      chroma = lerp(a.c, b.c, factor);\n      hue = lerpHue(a.h, b.h, factor);\n    } else if (lighter !== undefined) {\n      // Past the darkest anchor — fade toward the tinted near-black end.\n      const a = parsedAnchors[lighter] as OklchColor;\n      const factor = (idx(step) - idx(lighter)) / (lastIdx - idx(lighter));\n      chroma = lerp(a.c, Math.min(ENDPOINT_CHROMA.dark, a.c), factor);\n      hue = a.h;\n    } else if (darker !== undefined) {\n      // Past the lightest anchor — fade toward the tinted near-white end.\n      const b = parsedAnchors[darker] as OklchColor;\n      const factor = (idx(darker) - idx(step)) / idx(darker);\n      chroma = lerp(b.c, Math.min(ENDPOINT_CHROMA.light, b.c), factor);\n      hue = b.h;\n    } else {\n      chroma = 0.1;\n      hue = 0;\n    }\n\n    const lightness = LIGHTNESS_LADDER[step];\n    const finalL = (lightness * 100).toFixed(2) + '%';\n    const finalC = Math.min(chroma, MAX_CHROMA).toFixed(4);\n    const finalH = hue.toFixed(2);\n\n    palette[step] = `oklch(${finalL} ${finalC} ${finalH})`;\n  }\n\n  return palette;\n}\n\n// ── Contrast + endpoints (for the functional-token layer) ────────────────────\n\n/** APCA lightness-contrast (Lc) magnitude between a foreground and background. */\nexport function contrastLc(fg: string, bg: string): number {\n  return Math.abs(new Color(bg).contrast(fg, 'APCA'));\n}\n\n/**\n * Pick a tinted near-white or near-black foreground for best contrast on `bg`\n * (a whisper of the background's hue mixed into off-white/off-black).\n */\nexport function pickOn(bg: string, hue?: number): string {\n  const h = hue ?? hexToOklch(bg).h;\n  const white = oklchToHex({ l: 0.98, c: 0.01, h });\n  const black = oklchToHex({ l: 0.16, c: 0.02, h });\n  return contrastLc(white, bg) >= contrastLc(black, bg) ? white : black;\n}\n\n/**\n * The tinted off-white / off-black endpoints for a hue — white/black with a\n * whisper of the hue mixed in. These are the text/background tints every ramp\n * needs (and the one exception strict brand kits allow).\n *\n * Derived from `LIGHTNESS_LADDER` and `ENDPOINT_CHROMA` rather than its own\n * literals, so a strict tone kit's endpoints land on the same ladder rungs a\n * generated ramp would have used. This is the single definition — callers must\n * not hand-write their own near-white/near-black.\n */\nexport function tintedEndpoints(hue: number, chroma?: number): { light: string; dark: string } {\n  return {\n    light: oklchToHex({\n      l: LIGHTNESS_LADDER[50],\n      c: Math.min(chroma ?? ENDPOINT_CHROMA.light, 0.02),\n      h: hue,\n    }),\n    dark: oklchToHex({\n      l: LIGHTNESS_LADDER[950],\n      c: Math.min((chroma ?? ENDPOINT_CHROMA.dark) * 1.5, 0.03),\n      h: hue,\n    }),\n  };\n}\n","/**\n * Color harmony strategies for generating complementary colors\n */\n\nexport type HarmonyStrategy =\n  | 'complement'\n  | 'analogous-plus'\n  | 'analogous-minus'\n  | 'triadic-plus'\n  | 'triadic-minus'\n  | 'split-plus'\n  | 'split-minus'\n  | 'tetradic-plus'\n  | 'tetradic-minus';\n\nexport interface HarmonyOption {\n  id: HarmonyStrategy;\n  label: string;\n  description: string;\n  hueShift: number;\n}\n\nexport const HARMONY_STRATEGIES: HarmonyOption[] = [\n  {\n    id: 'complement',\n    label: 'Complement',\n    description: 'Opposite on color wheel (high contrast)',\n    hueShift: 180,\n  },\n  {\n    id: 'analogous-plus',\n    label: 'Analogous+',\n    description: 'Adjacent colors (harmonious)',\n    hueShift: 30,\n  },\n  {\n    id: 'analogous-minus',\n    label: 'Analogous-',\n    description: 'Adjacent colors (harmonious)',\n    hueShift: -30,\n  },\n  {\n    id: 'triadic-plus',\n    label: 'Triadic+',\n    description: 'Evenly spaced (balanced)',\n    hueShift: 120,\n  },\n  {\n    id: 'triadic-minus',\n    label: 'Triadic-',\n    description: 'Evenly spaced (balanced)',\n    hueShift: -120,\n  },\n  {\n    id: 'split-plus',\n    label: 'Split Complement+',\n    description: 'Near opposite (softer contrast)',\n    hueShift: 150,\n  },\n  {\n    id: 'split-minus',\n    label: 'Split Complement-',\n    description: 'Near opposite (softer contrast)',\n    hueShift: -150,\n  },\n  {\n    id: 'tetradic-plus',\n    label: 'Tetradic+',\n    description: 'Square spacing (rich palette)',\n    hueShift: 90,\n  },\n  {\n    id: 'tetradic-minus',\n    label: 'Tetradic-',\n    description: 'Square spacing (rich palette)',\n    hueShift: -90,\n  },\n];\n\n/**\n * Applies a harmony strategy to a hue value\n */\nexport function applyHarmonyStrategy(baseHue: number, strategy: HarmonyStrategy): number {\n  const harmonyOption = HARMONY_STRATEGIES.find((h) => h.id === strategy);\n  if (!harmonyOption) return baseHue;\n\n  let newHue = baseHue + harmonyOption.hueShift;\n\n  // Normalize to 0-360 range\n  while (newHue < 0) newHue += 360;\n  while (newHue >= 360) newHue -= 360;\n\n  return newHue;\n}\n\n/**\n * Gets all harmony suggestions for a given base hue\n */\nexport function getHarmonySuggestions(\n  baseHue: number,\n): Array<{ strategy: HarmonyStrategy; hue: number; label: string; description: string }> {\n  return HARMONY_STRATEGIES.map((strategy) => ({\n    strategy: strategy.id,\n    hue: applyHarmonyStrategy(baseHue, strategy.id),\n    label: strategy.label,\n    description: strategy.description,\n  }));\n}\n\n/**\n * Default functional color hues (if user doesn't specify)\n */\nexport const DEFAULT_FUNCTIONAL_HUES = {\n  success: 142, // Green\n  warning: 38, // Orange/Amber\n  error: 0, // Red\n  info: 200, // Blue\n} as const;\n\n/**\n * Suggests a functional color hue based on existing palette to maintain harmony\n */\nexport function suggestFunctionalColorHue(\n  type: keyof typeof DEFAULT_FUNCTIONAL_HUES,\n  existingHues: number[],\n): number {\n  const defaultHue = DEFAULT_FUNCTIONAL_HUES[type];\n\n  if (existingHues.length === 0) {\n    return defaultHue;\n  }\n\n  // Find the closest existing hue and adjust slightly to maintain harmony\n  const avgHue = existingHues.reduce((sum, h) => sum + h, 0) / existingHues.length;\n\n  // Rotate the default hue to be more in line with the palette's color temperature\n  const hueShift = avgHue - 200; // Assuming 200 is neutral blue\n  let adjustedHue = defaultHue + hueShift * 0.3; // 30% influence\n\n  // Normalize\n  while (adjustedHue < 0) adjustedHue += 360;\n  while (adjustedHue >= 360) adjustedHue -= 360;\n\n  return adjustedHue;\n}\n"],"mappings":"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"}

package/dist/crm/index.d.mts

@@ -0,0 +1,288 @@
+import { t as ConversionEvent } from "../types-7ELci8RQ.mjs";
+//#region src/crm/types.d.ts
+/**
+ * The CRM module's own option surface.
+ *
+ * Deliberately structural rather than `Config['site']['crm']` imported from
+ * `@getvitops/generator`: the generator already depends on this package, so
+ * importing back would be a cycle. The vocabulary mirrors that block field for
+ * field — the same arrangement, and for the same reason, as `IndexingConfig`
+ * and `NotifyContext` beside it.
+ *
+ * Optional fields are written `?: T | undefined` throughout: `exactOptionalPropertyTypes`
+ * is on, and these describe a *parsed JSON config* where an absent key and an
+ * explicit `undefined` are the same thing.
+ */
+type CrmProvider = 'hubspot' | 'bigin' | 'jobber';
+/** Human-readable label per provider, for the notification email's Delivery
+ * line (`describeCrmResult`) and anywhere else a provider must be named
+ * without a hand-written ternary. Exhaustive by type — a provider missing
+ * here is a compile error, not a mislabelled email. */
+export declare const PROVIDER_LABELS: Record<CrmProvider, string>;
+/** Bigin's data centre — the region a self-client's tokens and API host belong to. */
+type BiginDataCenter = 'com' | 'ca' | 'eu' | 'in' | 'com.au' | 'jp';
+interface HubSpotConfig {
+  portalId: string;
+  formGuid: string;
+  /** Default `na`. Only affects the submissions API host. */
+  dataCenter?: 'na' | 'eu' | undefined;
+}
+interface BiginPipelineConfig {
+  enabled: boolean;
+  subPipeline?: string | undefined;
+  stage?: string | undefined;
+}
+interface BiginConfig {
+  dataCenter: BiginDataCenter;
+  /** Default `Email` — Bigin's own unique field, used for `upsert`'s dedupe. */
+  duplicateCheckField?: string | undefined;
+  pipeline?: BiginPipelineConfig | undefined;
+}
+interface JobberConfig {
+  /**
+   * The pinned `X-JOBBER-GRAPHQL-VERSION` date this integration was built and
+   * tested against. Overriding it is an escape hatch for a client's app
+   * pinned to a different version — not something to reach for casually,
+   * since Jobber's schema can change field names between versions.
+   */
+  apiVersion?: string | undefined;
+  /**
+   * Look up an existing client by email before creating one (default
+   * **false**). Jobber's `clientCreate` has no upsert, so a resubmitting
+   * visitor creates a second client unless this runs — but the lookup query's
+   * filter shape is not yet verified against a live Jobber schema (see
+   * `jobber.ts`'s docblock), so it defaults off rather than risk a wrong
+   * query silently blocking a real submission. Set `true` once verified for
+   * your account.
+   */
+  dedupe?: boolean | undefined;
+  note?: {
+    /** Attach a best-effort note carrying the message + unmapped
+     * attribution (default true). A failure here never downgrades the
+     * client write's own success — see `jobber.ts`. */
+    enabled?: boolean | undefined;
+  } | undefined;
+}
+interface CrmConfig {
+  provider: CrmProvider;
+  enabled?: boolean | undefined;
+  hubspot?: HubSpotConfig | undefined;
+  bigin?: BiginConfig | undefined;
+  jobber?: JobberConfig | undefined;
+  /** Submitted field name → CRM property name. Unmapped fields are dropped, not guessed. */
+  fieldMap?: Record<string, string> | undefined;
+  /** `_ac` tracking key → CRM property name. Same drop-if-unmapped rule. */
+  trackingFields?: Record<string, string> | undefined;
+}
+/** Credentials, never config — always injected by the caller from env vars. */
+interface HubSpotCredentials {
+  accessToken: string;
+}
+interface BiginCredentials {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+/**
+ * Jobber's self-client OAuth credential. The refresh token is expected to be
+ * static — Refresh Token Rotation must be OFF in the app's Developer Center
+ * settings, since a Worker reading a static env var cannot persist a rotated
+ * one. See `jobber-token.ts` for the detection when a client's app has it on
+ * anyway.
+ */
+interface JobberCredentials {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+type CrmCredentials = {
+  provider: 'hubspot';
+  hubspot: HubSpotCredentials;
+} | {
+  provider: 'bigin';
+  bigin: BiginCredentials;
+} | {
+  provider: 'jobber';
+  jobber: JobberCredentials;
+};
+/** A channel's decision: on, or off with a stated reason. Mirrors `ChannelPlan`. */
+interface CrmPlan {
+  enabled: boolean;
+  provider?: CrmProvider | undefined;
+  /** Why it's off. Present iff `enabled` is false. */
+  skip?: string | undefined;
+}
+/** A provider-neutral record — what a submission maps to, before either executor
+ * renders it into that CRM's own request shape. */
+interface CrmRecord {
+  firstName?: string | undefined;
+  lastName?: string | undefined;
+  email?: string | undefined;
+  phone?: string | undefined;
+  company?: string | undefined;
+  message?: string | undefined;
+  /** Mapped fields beyond the identity ones above, keyed by the CRM property name. */
+  extra: Record<string, string>;
+  /** `trackingFields`-mapped attribution, keyed by the CRM property name. Empty
+   * when the visitor arrived with no `_ac` cookie — never an error. */
+  attribution: Record<string, string>;
+}
+/**
+ * The outcome of one delivery attempt. Never thrown — a CRM write is
+ * best-effort and its failure is a fact for the caller to log or notify with,
+ * not an exception to propagate into the request that produced the submission.
+ */
+interface CrmResult {
+  ok: boolean;
+  provider: CrmProvider;
+  /** The created/updated record's id, when the CRM returned one. */
+  recordId?: string | undefined;
+  /** Why it didn't write, or what the classification of the failure was. */
+  reason?: string | undefined;
+  /** The provider's own error/status code, when it gave one. */
+  code?: string | undefined;
+}
+//#endregion
+//#region src/crm/hubspot.d.ts
+interface HubSpotSubmitContext {
+  hutk?: string | undefined;
+  pageUri?: string | undefined;
+  pageName?: string | undefined;
+}
+/**
+ * Submit one record to HubSpot's secure forms endpoint.
+ *
+ * Never throws — a network failure or an unparsable response both come back
+ * as a `CrmResult` with `ok: false`, the same "structured result, not an
+ * exception" rule `security/turnstile.ts` and `indexing/gsc.ts` follow. Status
+ * classification: 401 is a rejected/expired token; 400 naming
+ * `MISSING_REQUIRED_FIELDS` or an unrecognised field name is a mapping
+ * problem (`fieldMap`/`trackingFields` naming a property that isn't on the
+ * form); 429 is the per-portal rate limit.
+ */
+export declare function submitToHubSpot(record: CrmRecord, config: HubSpotConfig, credentials: HubSpotCredentials, context?: HubSpotSubmitContext, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<CrmResult>;
+//#endregion
+//#region src/crm/map.d.ts
+/**
+ * Bigin requires `Last_Name`; a form that only asked for a full name or an
+ * email needs one derived rather than 400ing on insert.
+ *
+ * The fallback chain, in order: an explicit last name field → the last space-
+ * separated token of a full name → the local part of the email address →
+ * refuse, with a stated reason, rather than fabricate a name from nothing.
+ * `map.ts` never emits an empty `lastName` for Bigin — `deliverToCrm` reads
+ * the refusal and skips the write instead of letting the CRM reject it.
+ */
+export declare function deriveLastName(identity: {
+  firstName?: string | undefined;
+  lastName?: string | undefined;
+  fullName: string;
+  email?: string | undefined;
+}): {
+  lastName: string;
+} | {
+  refusal: string;
+};
+export declare function mapSubmission(event: ConversionEvent, config: CrmConfig): CrmRecord;
+//#endregion
+//#region src/crm/plan.d.ts
+export declare function planCrm(config: CrmConfig | undefined, credentials: CrmCredentials | undefined): CrmPlan;
+//#endregion
+//#region src/crm/bigin.d.ts
+export declare function zohoApiHost(dataCenter: string): string;
+/**
+ * Write one record to Bigin. Never throws — a token-exchange failure, a
+ * network error and a rejected response all come back as `CrmResult`.
+ */
+export declare function submitToBigin(record: CrmRecord, config: BiginConfig, credentials: BiginCredentials, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<CrmResult>;
+//#endregion
+//#region src/crm/jobber.d.ts
+/**
+ * Write one record to Jobber. Never throws — a token-exchange failure, a
+ * network error, a top-level GraphQL `errors[]`, and a `userErrors[]` all
+ * come back as a `CrmResult` with `ok: false`.
+ */
+export declare function submitToJobber(record: CrmRecord, config: JobberConfig, credentials: JobberCredentials, pageUri: string | undefined, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<CrmResult>;
+//#endregion
+//#region src/crm/zoho-token.d.ts
+export declare function zohoAccountsHost(dataCenter: string): string;
+interface ZohoOAuth {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+/**
+ * Exchange a refresh token for a short-lived Bigin access token, reusing a
+ * cached one while it's still valid.
+ *
+ * `now` is a parameter so cache expiry is testable without a fake clock, the
+ * same convention `google/token.ts`'s `googleAccessToken` uses.
+ */
+export declare function zohoAccessToken(oauth: ZohoOAuth, dataCenter: string, fetchImpl?: typeof fetch, now?: number): Promise<string>;
+/** Test-only: clear the module-level cache between cases. */
+export declare function clearZohoTokenCache(): void;
+//#endregion
+//#region src/crm/jobber-token.d.ts
+/**
+ * Jobber OAuth2 refresh-token exchange.
+ *
+ * A plain `application/x-www-form-urlencoded` POST, same shape as Zoho's —
+ * see `zoho-token.ts` for why that keeps this Worker-safe (no `node:crypto`,
+ * unlike `google/token.ts`'s service-account JWT).
+ *
+ * One thing Zoho's grant never does: Jobber's Refresh Token Rotation is ON by
+ * default for a new app, and when it's on, every exchange returns a *new*
+ * refresh token and invalidates the old one. A Worker reading a static env
+ * var (`VITOPS_JOBBER_REFRESH_TOKEN`) cannot persist that new value, so this
+ * integration requires rotation turned OFF in the app's Developer Center
+ * settings — a legitimate setup requirement, since a per-client private app
+ * is never published to Jobber's Marketplace (where rotation ON is
+ * mandatory). `zohoAccessToken`'s Zoho equivalent has no such failure mode to
+ * detect, because Zoho's grant is long-lived by default.
+ *
+ * Cached per isolate, keyed on the refresh token, with an expiry margin —
+ * same rationale as `zoho-token.ts`.
+ */
+interface JobberOAuth {
+  clientId: string;
+  clientSecret: string;
+  refreshToken: string;
+}
+/**
+ * Exchange a refresh token for a short-lived Jobber access token, reusing a
+ * cached one while it's still valid.
+ *
+ * Throws a specific, actionable error when Jobber's response carries a
+ * *different* refresh token than the one sent — the rotation case above.
+ * Without this check, rotation surfaces an hour later as an opaque 401 on a
+ * lead that is already lost; with it, the first submission after rotation
+ * turns on names the fix.
+ *
+ * `now` is a parameter so cache expiry is testable without a fake clock, the
+ * same convention `zoho-token.ts`'s `zohoAccessToken` uses.
+ */
+export declare function jobberAccessToken(oauth: JobberOAuth, fetchImpl?: typeof fetch, now?: number): Promise<string>;
+/** Test-only: clear the module-level cache between cases. */
+export declare function clearJobberTokenCache(): void;
+//#endregion
+//#region src/crm/index.d.ts
+export interface CrmDeps {
+  credentials?: CrmCredentials | undefined;
+  fetch?: typeof fetch | undefined;
+  timeoutMs?: number | undefined;
+  /**
+   * The visitor's page context, provider-neutral. HubSpot reads `hutk` (its
+   * own session cookie) to stitch the submission to its tracking; Jobber
+   * reads `pageUri` for the note body. Not every provider uses every field —
+   * an unused one is simply ignored, which is why this is one shape rather
+   * than a per-provider option the caller has to pick correctly.
+   */
+  pageContext?: HubSpotSubmitContext | undefined;
+}
+export declare function deliverToCrm(event: ConversionEvent, config: CrmConfig | undefined, deps?: CrmDeps): Promise<CrmResult | null>;
+/** A one-line, human-readable delivery note — what `conversion.ts` folds into
+ * the notification email's "Delivery" section. */
+export declare function describeCrmResult(result: CrmResult | null): string | null;
+//#endregion
+export type { BiginConfig, BiginCredentials, BiginDataCenter, BiginPipelineConfig, CrmConfig, CrmCredentials, CrmPlan, CrmProvider, CrmRecord, CrmResult, HubSpotConfig, HubSpotCredentials, HubSpotSubmitContext, JobberConfig, JobberCredentials, JobberOAuth };
+//# sourceMappingURL=index.d.mts.map

package/dist/crm/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/crm/types.ts","../../src/crm/hubspot.ts","../../src/crm/map.ts","../../src/crm/plan.ts","../../src/crm/bigin.ts","../../src/crm/jobber.ts","../../src/crm/zoho-token.ts","../../src/crm/jobber-token.ts","../../src/crm/index.ts"],"mappings":";;;;;;;;;;;;;;;KAcY;;;;;qBAMC,iBAAiB,OAAO;;KAOzB;UAEK;EACf;EACA;;EAEA;;UAGe;EACf;EACA;EACA;;UAGe;EACf,YAAY;;EAEZ;EACA,WAAW;;UAGI;;;;;;;EAOf;;;;;;;;;;EAUA;EACA;;;;IAKM;;;UAKS;EACf,UAAU;EACV;EACA,UAAU;EACV,QAAQ;EACR,SAAS;;EAET,WAAW;;EAEX,iBAAiB;;;UAIF;EACf;;UAGe;EACf;EACA;EACA;;;;;;;;;UAUe;EACf;EACA;EACA;;KAGU;EACN;EAAqB,SAAS;;EAC9B;EAAmB,OAAO;;EAC1B;EAAoB,QAAQ;;;UAGjB;EACf;EACA,WAAW;;EAEX;;;;UAKe;EACf;EACA;EACA;EACA;EACA;EACA;;EAEA,OAAO;;;EAGP,aAAa;;;;;;;UAQE;EACf;EACA,UAAU;;EAEV;;EAEA;;EAEA;;;;UCjHe;EACf;EACA;EACA;;;;;;;;;;;;;wBAcoB,gBACpB,QAAQ,WACR,QAAQ,eACR,aAAa,oBACb,UAAS,sBACT,mBAAkB,OAClB,qBACC,QAAQ;;;;;;;;;;;;;wBCtCK,eAAe;EAC7B;EACA;EACA;EACA;;EACI;;EAAuB;;wBAgDb,cAAc,OAAO,iBAAiB,QAAQ,YAAY;;;wBC/C1D,QACd,QAAQ,uBACR,aAAa,6BACZ;;;wBCba,YAAY;;;;;wBAsBN,cACpB,QAAQ,WACR,QAAQ,aACR,aAAa,kBACb,mBAAkB,OAClB,qBACC,QAAQ;;;;;;;;wBCoJW,eACpB,QAAQ,WACR,QAAQ,cACR,aAAa,mBACb,6BACA,mBAAkB,OAClB,qBACC,QAAQ;;;wBCpLK,iBAAiB;UAehB;EACf;EACA;EACA;;;;;;;;;wBAUoB,gBACpB,OAAO,WACP,oBACA,mBAAkB,OAClB,eACC;;wBAkCa;;;;;;;;;;;;;;;;;;;;;;;UC3DC;EACf;EACA;EACA;;;;;;;;;;;;;;;wBAgBoB,kBACpB,OAAO,aACP,mBAAkB,OAClB,eACC;;wBA8Ca;;;iBCvEC;EACf,cAAc;EACd,eAAe;EACf;;;;;;;;EAQA,cAAc;;wBAGM,aACpB,OAAO,iBACP,QAAQ,uBACR,OAAM,UACL,QAAQ;;;wBAwDK,kBAAkB,QAAQ"}