@nextlyhq/ui 0.0.2-alpha.6 → 0.0.2-alpha.60

package/README.md

@@ -31,56 +31,134 @@ pnpm add react react-dom lucide-react
 
 ## Setup
 
-The components ship as Tailwind CSS 4 token consumers. They reference HSL CSS variables (`--background`, `--primary`, `--border`, etc.) which your project must define.
+The package ships three CSS entry points. Pick one:
 
-**Tailwind v4 (recommended)**
+**Zero config — pre-compiled bundle**
 
-In your global CSS, define the design tokens with `@theme` and import the components:
+Import the pre-built stylesheet once at your root. It bundles Tailwind, every design token
+(on `:root`, flipped under `.dark`), and the base reset, so components render fully styled
+with no build wiring:
 
-```css
-/* app/globals.css */
-@import "tailwindcss";
+```tsx
+import "@nextlyhq/ui/styles.css";
+import { Button } from "@nextlyhq/ui";
 
-@theme {
-  --color-background: hsl(0 0% 100%);
-  --color-foreground: hsl(222 47% 11%);
-  --color-primary: hsl(221 83% 53%);
-  --color-primary-foreground: hsl(0 0% 100%);
-  /* ...the rest. See `uiPreset` for the full token contract. */
-}
+<Button variant="outline">Click me</Button>;
 ```
 
-The exported `uiPreset` is the reference contract: it lists every token name the components expect. Use it to write the matching `@theme` block (or import it directly if you are still on Tailwind v3).
+**Bring your own Tailwind v4 build**
 
-```tsx
-import { Button } from "@nextlyhq/ui";
+If you already run Tailwind v4, import just the tokens and let your pipeline compile the
+utilities the components use:
 
-<Button variant="outline">Click me</Button>;
+```css
+/* app/globals.css */
+@import "tailwindcss";
+@import "@nextlyhq/ui/theme.css";
+@source "../node_modules/@nextlyhq/ui/dist";
 ```
 
+`theme.css` defines the tokens as complete OKLCH color values (`--nx-background`, `--nx-primary`,
+`--nx-border`, …) with `@theme inline` mappings and the dark-mode overrides. Reference tokens
+directly (`var(--nx-primary)`) — never wrap them in `hsl()`. `uiPreset` remains available
+as a Tailwind v3 preset from `@nextlyhq/ui/tailwind-preset`.
+
+> Inside a Nextly admin plugin you need neither import — the admin already provides the
+> tokens. See the [**Plugin UI authoring guide**](./docs/plugin-ui-authoring.md).
+
 ## Components
 
 **Buttons and inputs:** `Button`, `Input`, `Textarea`, `Label`
 **Display:** `Badge`, `Card`, `Alert`, `Separator`, `Skeleton`, `Progress`
 **Toggles:** `Checkbox`, `RadioGroup`, `Switch`, `Collapsible`
 **Layout and disclosure:** `Accordion`, `Avatar`, `Tabs`, `Tooltip`, `Popover`
+**Resizable regions:** `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`
+**Hierarchies:** `TreeView` (virtualized, keyboard-operable)
 **Overlays:** `Dialog`, `AlertDialog`, `Sheet`
-**Menus and command palette:** `DropdownMenu`, `Select`, `Command`
+**Menus and command palette:** `DropdownMenu`, `ContextMenu`, `Select`, `Command`
 **Feedback:** `Spinner`, `Toaster` (with `toast()` helper)
 **Tables:** `Table` primitives, `ResponsiveTable`, `TableSearch`, `TablePagination`, `TableSkeleton`, `TableEmpty`, `TableError`, `TableLoading`
 **Providers:** `PortalProvider`, `usePortalContainer`
-**Utilities:** `cn`, `uiPreset`
+
+> Which of these carry a stability guarantee is recorded in
+> [STABILITY.md](https://github.com/nextlyhq/nextly/blob/main/packages/ui/STABILITY.md). A component becomes `@public` once a first-party
+> plugin depends on it; everything else is `@experimental` and may change in any
+> release.
+
+**Utilities:** `cn` (from `@nextlyhq/ui/utils`), `uiPreset` (from `@nextlyhq/ui/tailwind-preset`)
+
+> Both ship from their own subpaths rather than the root: the root bundle is
+> published with `"use client"`, and neither of these contains a React runtime,
+> so a server component or a Tailwind config can import them safely.
+
+## Stylesheets
+
+| Import                           | Use when                                                                                                                              |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `@nextlyhq/ui/styles.css`        | The app is yours end to end. Styles the whole document, Tailwind preflight included.                                                  |
+| `@nextlyhq/ui/styles.scoped.css` | Dropping a few components into an existing app. Every rule is confined to `.nextly-ui`, so the rest of the page keeps its own styles. |
+| `@nextlyhq/ui/theme.css`         | You compile Tailwind yourself and want the token contract only.                                                                       |
+
+The scoped sheet needs a wrapper element, and dark mode goes on the same element:
+
+```tsx
+import "@nextlyhq/ui/styles.scoped.css";
+
+<div className="nextly-ui">
+  <Button>Save</Button>
+</div>;
+```
+
+It keeps preflight rather than dropping it — these components are designed against a
+normalised baseline — but confines it to the wrapper, so your headings, lists and form
+controls outside it are untouched. Three things CSS resolves globally are namespaced
+along with the selectors, so the sheet cannot reach outside the wrapper through them
+either: animation names (it will not displace a `spin` or `fade-in` you define),
+Tailwind's internal `--tw-*` registrations, and the ancestor classes `dark:` and
+`group-*:` variants look for. Dark mode is therefore driven by the wrapper, not by a
+`dark` class higher up your page.
+
+### Overlays need a portal container
+
+AlertDialog, Command, ContextMenu, Dialog, DropdownMenu, Popover, Select, Sheet and
+Tooltip render
+their overlay through a portal, which defaults to `document.body` — outside the wrapper,
+where the scoped rules and tokens do not reach. Triggers would look right and the menus
+they open would not. Point them back inside with `PortalProvider`:
+
+```tsx
+import { useState } from "react";
+import { PortalProvider } from "@nextlyhq/ui";
+import "@nextlyhq/ui/styles.scoped.css";
+
+function Kit({ children }: { children: React.ReactNode }) {
+  const [container, setContainer] = useState<HTMLElement | null>(null);
+
+  return (
+    <div className="nextly-ui" ref={setContainer}>
+      <PortalProvider container={container}>{children}</PortalProvider>
+    </div>
+  );
+}
+```
+
+A callback ref rather than `useRef` because the container has to be a state value: on the
+first render it is still `null`, and the overlays need a re-render once the element exists.
+
+This does not apply to `styles.css`, where the rules are document-wide and
+`document.body` is already covered.
 
 ## Compatibility
 
-| Tool           | Version                                                          |
-| -------------- | ---------------------------------------------------------------- |
-| React          | 18 or 19                                                         |
-| Tailwind CSS   | 4+ (the `uiPreset` JS export also works as a Tailwind v3 preset) |
-| `lucide-react` | 0.400+                                                           |
+| Tool           | Version                                                                |
+| -------------- | ---------------------------------------------------------------------- |
+| React          | 18 or 19                                                               |
+| Tailwind CSS   | 4+ (`@nextlyhq/ui/tailwind-preset` also works as a Tailwind v3 preset) |
+| `lucide-react` | 0.400+                                                                 |
 
 ## Documentation
 
+- [**Plugin UI authoring guide**](./docs/plugin-ui-authoring.md): the token contract, dark mode, container queries, and the design lint guard
 - [**Admin customization**](https://nextlyhq.com/docs/admin/customization): theming, branding, and custom field UIs
 
 ## Related packages

package/dist/color.cjs

@@ -0,0 +1,193 @@
+'use strict';
+
+// src/lib/color/convert.ts
+var clamp01 = (n) => n < 0 ? 0 : n > 1 ? 1 : n;
+var MAX_SRGB_CHROMA = 0.5;
+function normalizeHue(hue) {
+  if (!Number.isFinite(hue)) return 0;
+  const wrapped = hue % 360;
+  return wrapped < 0 ? wrapped + 360 : wrapped;
+}
+function hsvToRgb({ h, s, v }) {
+  const hue = normalizeHue(h);
+  const sat = clamp01(s);
+  const val = clamp01(v);
+  const sector = hue / 60;
+  const chroma = val * sat;
+  const x = chroma * (1 - Math.abs(sector % 2 - 1));
+  const base = val - chroma;
+  let rgb;
+  if (sector < 1) rgb = [chroma, x, 0];
+  else if (sector < 2) rgb = [x, chroma, 0];
+  else if (sector < 3) rgb = [0, chroma, x];
+  else if (sector < 4) rgb = [0, x, chroma];
+  else if (sector < 5) rgb = [x, 0, chroma];
+  else rgb = [chroma, 0, x];
+  return { r: rgb[0] + base, g: rgb[1] + base, b: rgb[2] + base };
+}
+function rgbToHsv({ r, g, b }) {
+  const red = clamp01(r);
+  const green = clamp01(g);
+  const blue = clamp01(b);
+  const max = Math.max(red, green, blue);
+  const min = Math.min(red, green, blue);
+  const chroma = max - min;
+  let hue = 0;
+  if (chroma !== 0) {
+    if (max === red) hue = (green - blue) / chroma % 6;
+    else if (max === green) hue = (blue - red) / chroma + 2;
+    else hue = (red - green) / chroma + 4;
+    hue *= 60;
+  }
+  return {
+    h: normalizeHue(hue),
+    s: max === 0 ? 0 : chroma / max,
+    v: max
+  };
+}
+function toLinear(channel) {
+  return channel <= 0.04045 ? channel / 12.92 : Math.pow((channel + 0.055) / 1.055, 2.4);
+}
+function toGamma(channel) {
+  return channel <= 31308e-7 ? channel * 12.92 : 1.055 * Math.pow(channel, 1 / 2.4) - 0.055;
+}
+function linearRgbToOklab(r, g, b) {
+  const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+  const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+  const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+  return [
+    0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_,
+    1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_,
+    0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_
+  ];
+}
+function oklabToLinearRgb(L, a, b) {
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+  return [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s
+  ];
+}
+function rgbToOklch({ r, g, b }) {
+  const [L, A, B] = linearRgbToOklab(
+    toLinear(clamp01(r)),
+    toLinear(clamp01(g)),
+    toLinear(clamp01(b))
+  );
+  const chroma = Math.sqrt(A * A + B * B);
+  const hue = chroma < 1e-6 ? 0 : normalizeHue(Math.atan2(B, A) * 180 / Math.PI);
+  return { l: L, c: chroma, h: hue };
+}
+function inGamut([r, g, b]) {
+  const epsilon = 0;
+  return r >= -epsilon && r <= 1 + epsilon && g >= -epsilon && g <= 1 + epsilon && b >= -epsilon && b <= 1 + epsilon;
+}
+function oklchToRgb({ l, c, h }) {
+  const lightness = clamp01(l);
+  const hueRadians = normalizeHue(h) * Math.PI / 180;
+  const at = (chroma) => oklabToLinearRgb(
+    lightness,
+    chroma * Math.cos(hueRadians),
+    chroma * Math.sin(hueRadians)
+  );
+  const requested = Math.max(0, c);
+  let fitting = at(requested);
+  if (!inGamut(fitting)) {
+    let low = 0;
+    let high = Math.min(requested, MAX_SRGB_CHROMA);
+    for (let i = 0; i < 20; i++) {
+      const mid = (low + high) / 2;
+      if (inGamut(at(mid))) low = mid;
+      else high = mid;
+    }
+    fitting = at(low);
+  }
+  return {
+    r: clamp01(toGamma(fitting[0])),
+    g: clamp01(toGamma(fitting[1])),
+    b: clamp01(toGamma(fitting[2]))
+  };
+}
+
+// src/lib/color/hex.ts
+var HEX = /^#?(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+var clamp012 = (n) => n < 0 ? 0 : n > 1 ? 1 : n;
+function pair(channel) {
+  const value = Number.isFinite(channel) ? clamp012(channel) : 0;
+  return Math.round(value * 255).toString(16).padStart(2, "0");
+}
+function parseHex(input) {
+  const text = input.trim();
+  if (!HEX.test(text)) return null;
+  const digits = text.replace("#", "");
+  const short = digits.length < 6;
+  const size = short ? 1 : 2;
+  const channel = (index) => {
+    const slice = digits.slice(index * size, index * size + size);
+    return parseInt(short ? slice + slice : slice, 16) / 255;
+  };
+  const hasAlpha = digits.length === 4 || digits.length === 8;
+  return {
+    r: channel(0),
+    g: channel(1),
+    b: channel(2),
+    alpha: hasAlpha ? channel(3) : 1
+  };
+}
+function toHex(color, alpha = 1) {
+  const opacity = Number.isFinite(alpha) ? clamp012(alpha) : 1;
+  const opaque = `#${pair(color.r)}${pair(color.g)}${pair(color.b)}`;
+  return opacity === 1 ? opaque : `${opaque}${pair(opacity)}`;
+}
+
+// src/lib/color/picker-geometry.ts
+var clamp013 = (n) => n < 0 ? 0 : n > 1 ? 1 : n;
+function pointOnSurface(clientX, clientY, rect) {
+  return {
+    x: rect.width === 0 ? 0 : clamp013((clientX - rect.left) / rect.width),
+    y: rect.height === 0 ? 0 : clamp013((clientY - rect.top) / rect.height)
+  };
+}
+function saturationValueAt(point) {
+  return { s: clamp013(point.x), v: 1 - clamp013(point.y) };
+}
+function surfacePointFor(s, v) {
+  return { x: clamp013(s), y: 1 - clamp013(v) };
+}
+function hueAt(fraction) {
+  const hue = clamp013(fraction) * 360;
+  return hue >= 360 ? 0 : hue;
+}
+function huePosition(hue) {
+  const wrapped = (hue % 360 + 360) % 360;
+  return wrapped / 360;
+}
+function hueSliderValue(hue, max) {
+  const step = Math.round(huePosition(hue) * (max + 1));
+  return step > max ? max : step;
+}
+
+exports.hsvToRgb = hsvToRgb;
+exports.hueAt = hueAt;
+exports.huePosition = huePosition;
+exports.hueSliderValue = hueSliderValue;
+exports.normalizeHue = normalizeHue;
+exports.oklchToRgb = oklchToRgb;
+exports.parseHex = parseHex;
+exports.pointOnSurface = pointOnSurface;
+exports.rgbToHsv = rgbToHsv;
+exports.rgbToOklch = rgbToOklch;
+exports.saturationValueAt = saturationValueAt;
+exports.surfacePointFor = surfacePointFor;
+exports.toHex = toHex;
+//# sourceMappingURL=color.cjs.map
+//# sourceMappingURL=color.cjs.map

package/dist/color.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/color/convert.ts","../src/lib/color/hex.ts","../src/lib/color/picker-geometry.ts"],"names":["clamp01"],"mappings":"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","file":"color.cjs","sourcesContent":["/**\n * Conversions between the colour models an editing surface needs.\n *\n * ## Why each model is here\n *\n * - **sRGB** is what a screen displays and what `#rrggbb` encodes. Everything ends here.\n * - **HSV** is what a colour picker is: a square of saturation against value, beside a hue\n *   strip. No other model puts those three controls in the shape people expect.\n * - **OKLCH** is what this product's own theme is written in — every token in `theme.css` is an\n *   `oklch()` value. A picker that cannot read it cannot edit the theme.\n *\n * ## Why the maths is here rather than in a library\n *\n * These are fixed, published transforms: the sRGB transfer function and the OKLab matrices are\n * specified in CSS Color 4 and do not change. The package ships no runtime colour dependency, and\n * this module keeps it that way. `culori` remains a DEV dependency used as a test oracle — the\n * conversions here are cross-checked against it rather than trusted on their own.\n *\n * ## The part that is genuinely hard\n *\n * OKLCH describes more colours than a screen can show. Converting one that falls outside sRGB has\n * no correct answer, only choices, and the naive choice — clamp each channel independently — is\n * the wrong one: it shifts hue, because clipping red without clipping green changes the ratio\n * between them. {@link oklchToRgb} reduces chroma instead, holding lightness and hue, which is the\n * approach CSS Color 4 describes for gamut mapping.\n *\n * @module lib/color/convert\n */\n\n/**\n * An sRGB colour with channels in [0, 1]. Alpha is carried separately.\n *\n * @experimental\n */\nexport interface Rgb {\n  r: number;\n  g: number;\n  b: number;\n}\n\n/**\n * Hue in [0, 360), saturation and value in [0, 1].\n *\n * @experimental\n */\nexport interface Hsv {\n  h: number;\n  s: number;\n  v: number;\n}\n\n/**\n * Perceptual lightness in [0, 1], chroma from 0, hue in [0, 360).\n *\n * @experimental\n */\nexport interface Oklch {\n  l: number;\n  c: number;\n  h: number;\n}\n\nconst clamp01 = (n: number): number => (n < 0 ? 0 : n > 1 ? 1 : n);\n\n/**\n * A chroma no displayable sRGB colour exceeds.\n *\n * The most saturated sRGB primaries sit near 0.37 in OKLCH; this leaves headroom above that and\n * gives the gamut search a fixed bracket, so its error is absolute rather than proportional to\n * whatever the caller asked for.\n */\nconst MAX_SRGB_CHROMA = 0.5;\n\n/**\n * Wrap a hue into [0, 360), so -30 and 330 are the same angle.\n *\n * @experimental\n */\nexport function normalizeHue(hue: number): number {\n  if (!Number.isFinite(hue)) return 0;\n  const wrapped = hue % 360;\n  return wrapped < 0 ? wrapped + 360 : wrapped;\n}\n\n/**\n * HSV to sRGB.\n * Saturation and value are clamped rather than rejected: a picker drags them, and a drag that\n * overshoots by a rounding error should saturate rather than throw.\n *\n * @experimental\n */\nexport function hsvToRgb({ h, s, v }: Hsv): Rgb {\n  const hue = normalizeHue(h);\n  const sat = clamp01(s);\n  const val = clamp01(v);\n\n  const sector = hue / 60;\n  const chroma = val * sat;\n  // The second-largest component, which falls as the hue moves away from a primary.\n  const x = chroma * (1 - Math.abs((sector % 2) - 1));\n  const base = val - chroma;\n\n  let rgb: [number, number, number];\n  if (sector < 1) rgb = [chroma, x, 0];\n  else if (sector < 2) rgb = [x, chroma, 0];\n  else if (sector < 3) rgb = [0, chroma, x];\n  else if (sector < 4) rgb = [0, x, chroma];\n  else if (sector < 5) rgb = [x, 0, chroma];\n  else rgb = [chroma, 0, x];\n\n  return { r: rgb[0] + base, g: rgb[1] + base, b: rgb[2] + base };\n}\n\n/**\n * sRGB to HSV.\n * Hue is UNDEFINED for a grey and value is undefined for black, and this returns 0 for both. A\n * picker must not take that 0 as the user's hue: it is the absence of one. Holding hue across a\n * drag to zero saturation is the caller's job, which is why a picker keeps HSV as its state\n * rather than deriving it from the colour each render.\n *\n * @experimental\n */\nexport function rgbToHsv({ r, g, b }: Rgb): Hsv {\n  const red = clamp01(r);\n  const green = clamp01(g);\n  const blue = clamp01(b);\n\n  const max = Math.max(red, green, blue);\n  const min = Math.min(red, green, blue);\n  const chroma = max - min;\n\n  let hue = 0;\n  if (chroma !== 0) {\n    if (max === red) hue = ((green - blue) / chroma) % 6;\n    else if (max === green) hue = (blue - red) / chroma + 2;\n    else hue = (red - green) / chroma + 4;\n    hue *= 60;\n  }\n\n  return {\n    h: normalizeHue(hue),\n    s: max === 0 ? 0 : chroma / max,\n    v: max,\n  };\n}\n\n/** The sRGB transfer function, gamma-encoded to linear light. */\nfunction toLinear(channel: number): number {\n  return channel <= 0.04045\n    ? channel / 12.92\n    : Math.pow((channel + 0.055) / 1.055, 2.4);\n}\n\n/** The inverse transfer function, linear light back to gamma-encoded. */\nfunction toGamma(channel: number): number {\n  return channel <= 0.0031308\n    ? channel * 12.92\n    : 1.055 * Math.pow(channel, 1 / 2.4) - 0.055;\n}\n\n/**\n * Linear sRGB to OKLab.\n *\n * The two matrices and the cube root between them are the definition of OKLab, given in CSS\n * Color 4. They are transcribed rather than derived.\n */\nfunction linearRgbToOklab(\n  r: number,\n  g: number,\n  b: number\n): [number, number, number] {\n  const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;\n  const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;\n  const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;\n\n  const l_ = Math.cbrt(l);\n  const m_ = Math.cbrt(m);\n  const s_ = Math.cbrt(s);\n\n  return [\n    0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_,\n    1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_,\n    0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_,\n  ];\n}\n\n/** OKLab back to linear sRGB, the inverse of {@link linearRgbToOklab}. */\nfunction oklabToLinearRgb(\n  L: number,\n  a: number,\n  b: number\n): [number, number, number] {\n  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;\n  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;\n  const s_ = L - 0.0894841775 * a - 1.291485548 * b;\n\n  const l = l_ * l_ * l_;\n  const m = m_ * m_ * m_;\n  const s = s_ * s_ * s_;\n\n  return [\n    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,\n    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,\n    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,\n  ];\n}\n\n/**\n * sRGB to OKLCH.\n *\n * @experimental\n */\nexport function rgbToOklch({ r, g, b }: Rgb): Oklch {\n  const [L, A, B] = linearRgbToOklab(\n    toLinear(clamp01(r)),\n    toLinear(clamp01(g)),\n    toLinear(clamp01(b))\n  );\n  const chroma = Math.sqrt(A * A + B * B);\n  // Below this the hue angle is numerical noise rather than a colour, so it is reported as 0\n  // instead of whatever direction the rounding happened to point.\n  const hue =\n    chroma < 1e-6 ? 0 : normalizeHue((Math.atan2(B, A) * 180) / Math.PI);\n  return { l: L, c: chroma, h: hue };\n}\n\n/** Whether every channel of a linear triple lies within the displayable range. */\nfunction inGamut([r, g, b]: [number, number, number]): boolean {\n  // No tolerance at all: the point must be GENUINELY inside the gamut.\n  //\n  // Any fixed tolerance is eventually comparable to the channel values themselves, because those\n  // shrink without bound as lightness falls — 1e-6 broke the hue at l=0.01, and 1e-12 still broke\n  // it at l=0.0001. A tolerance exists to absorb the cube roots' error for a colour sitting\n  // exactly ON the boundary, and the cost of not absorbing it is that such a colour comes back\n  // with its chroma reduced by less than one part in a million, which nothing can display. The\n  // cost of absorbing it is a channel that must then be clamped, and clamping is precisely what\n  // moves the hue this function promises to keep.\n  const epsilon = 0;\n  return (\n    r >= -epsilon &&\n    r <= 1 + epsilon &&\n    g >= -epsilon &&\n    g <= 1 + epsilon &&\n    b >= -epsilon &&\n    b <= 1 + epsilon\n  );\n}\n\n/**\n * OKLCH to sRGB, reducing chroma until the colour fits on screen.\n * OKLCH can name colours a display cannot show. Clamping the channels independently is the\n * obvious response and the wrong one: clipping red without clipping green changes the ratio\n * between them, so the colour that appears is a DIFFERENT HUE from the one asked for. Lightness\n * and hue are what a person chose; chroma is the part they will not miss, so chroma is what is\n * given up.\n * The search is a bisection on chroma, which converges to well under a perceptible step in the\n * fixed number of rounds below — no loop that might not terminate.\n *\n * **The gamut is not always monotonic along this ray, and that is a deliberate trade.** At some\n * lightness and hue pairs the boundary is crossed more than once: at `l = 0.2, h = 264.1` the ray\n * is inside up to c ≈ 0.1192, outside until c ≈ 0.1368, briefly inside again to c ≈ 0.1386. A\n * bisection therefore finds the FIRST boundary rather than the outermost reachable chroma.\n *\n * That is the intended behaviour rather than a limitation. Those islands span roughly a tenth of\n * a degree of hue, so preferring the outermost value would make chroma jump by about 0.021\n * between h = 264.05 and h = 264.10 — a visible step while dragging a hue slider, over a change\n * no one can aim at. Taking the first boundary gives 0.1160, 0.1175, 0.1192, 0.1255, 0.1383\n * across the same sweep: continuous, and one step less saturated at worst. It is also what the\n * CSS Color 4 gamut-mapping algorithm does.\n *\n * @experimental\n */\nexport function oklchToRgb({ l, c, h }: Oklch): Rgb {\n  const lightness = clamp01(l);\n  const hueRadians = (normalizeHue(h) * Math.PI) / 180;\n\n  const at = (chroma: number): [number, number, number] =>\n    oklabToLinearRgb(\n      lightness,\n      chroma * Math.cos(hueRadians),\n      chroma * Math.sin(hueRadians)\n    );\n\n  const requested = Math.max(0, c);\n  let fitting = at(requested);\n\n  if (!inGamut(fitting)) {\n    let low = 0;\n    // Bracketed against an ABSOLUTE ceiling rather than the requested chroma. Halving an\n    // unbounded input a fixed number of times converges on a fraction OF THAT INPUT, so a\n    // sufficiently large chroma leaves the interval far above the gamut and the search returns\n    // zero — discarding the hue entirely and answering grey for a colour that has one. No sRGB\n    // colour exceeds a chroma of roughly 0.37, so this ceiling cannot exclude a reachable one.\n    let high = Math.min(requested, MAX_SRGB_CHROMA);\n    // Halvings of a fixed interval, so the remaining error is absolute: 0.5 / 2^20 is far below\n    // anything a screen or an eye resolves.\n    for (let i = 0; i < 20; i++) {\n      const mid = (low + high) / 2;\n      if (inGamut(at(mid))) low = mid;\n      else high = mid;\n    }\n    fitting = at(low);\n  }\n\n  return {\n    r: clamp01(toGamma(fitting[0])),\n    g: clamp01(toGamma(fitting[1])),\n    b: clamp01(toGamma(fitting[2])),\n  };\n}\n","/**\n * Hex is the notation people type, so it is the picker's front door.\n *\n * It lives beside the conversions rather than in the component that reads it, for the same reason\n * they do: parsing `#3b82f6` is arithmetic on a string, a server rendering a token swatch needs it\n * as much as an editing surface does, and pulling it into client code would put it behind the\n * `\"use client\"` boundary for no benefit.\n *\n * @module lib/color/hex\n */\n\nimport type { Rgb } from \"./convert\";\n\n/**\n * An sRGB colour with its alpha, which is what a hex string can carry and {@link Rgb} cannot.\n *\n * `alpha` is in [0, 1] like the channels, rather than 0-255, so it composes with the conversions\n * without a second unit in play.\n *\n * @experimental\n */\nexport interface Rgba extends Rgb {\n  alpha: number;\n}\n\n/** `#rgb`, `#rgba`, `#rrggbb` or `#rrggbbaa`, with the hash optional and case ignored. */\nconst HEX = /^#?(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;\n\nconst clamp01 = (n: number): number => (n < 0 ? 0 : n > 1 ? 1 : n);\n\n/** A channel byte as a two-digit lowercase pair. */\nfunction pair(channel: number): string {\n  // A non-finite channel becomes 0 rather than passing through. `clamp01(NaN)` is NaN, because\n  // both of its comparisons are false, and formatting that yields the three characters \"NaN\" —\n  // producing `#NaN0000`, which is exactly the string this module documents itself as never\n  // returning.\n  const value = Number.isFinite(channel) ? clamp01(channel) : 0;\n  return Math.round(value * 255)\n    .toString(16)\n    .padStart(2, \"0\");\n}\n\n/**\n * Read a hex colour, or `null` if the input is not one.\n *\n * Returns `null` rather than throwing or substituting black: this reads what someone is part-way\n * through typing, where \"not a colour yet\" is the ordinary case and neither an exception nor a\n * silent black is a useful answer. A caller decides whether to hold the last good value, show a\n * message, or wait.\n *\n * Both short forms are accepted because both are what people paste. `#abc` expands by REPEATING\n * each digit rather than padding with zero — `#abc` is `#aabbcc`, not `#a0b0c0` — which is what CSS\n * does and the only expansion under which `#fff` is white.\n *\n * @experimental\n */\nexport function parseHex(input: string): Rgba | null {\n  const text = input.trim();\n  if (!HEX.test(text)) return null;\n\n  const digits = text.replace(\"#\", \"\");\n  const short = digits.length < 6;\n  const size = short ? 1 : 2;\n  const channel = (index: number): number => {\n    const slice = digits.slice(index * size, index * size + size);\n    return parseInt(short ? slice + slice : slice, 16) / 255;\n  };\n\n  const hasAlpha = digits.length === 4 || digits.length === 8;\n  return {\n    r: channel(0),\n    g: channel(1),\n    b: channel(2),\n    alpha: hasAlpha ? channel(3) : 1,\n  };\n}\n\n/**\n * Write a colour as `#rrggbb`, or `#rrggbbaa` when it is not fully opaque.\n *\n * The alpha pair is omitted at 1 rather than always written, because `#3b82f6ff` is the same colour\n * and the shorter form is what someone expects to see in a field they typed `#3b82f6` into.\n *\n * Channels outside [0, 1] are clamped, so the result is always a valid six- or eight-digit hex\n * string whatever a caller passes. Not for floating-point drift, which rounds to the right byte on\n * its own: it is for a value that is wrong by a lot — a channel still in 0-255, or a computation\n * that overshot — where the alternative is emitting `#17f00-80`, a string nothing downstream can\n * parse and no error explains.\n *\n * @experimental\n */\nexport function toHex(color: Rgb, alpha = 1): string {\n  // A non-finite alpha falls back to 1, not to 0 as a channel does. Both are \"nothing was\n  // specified\", and for alpha that is this parameter's own default — where treating it as 0 would\n  // turn a colour invisible on a stray NaN, silently and with no way to tell from the output.\n  const opacity = Number.isFinite(alpha) ? clamp01(alpha) : 1;\n  const opaque = `#${pair(color.r)}${pair(color.g)}${pair(color.b)}`;\n  return opacity === 1 ? opaque : `${opaque}${pair(opacity)}`;\n}\n","/**\n * The mapping between a pointer on a picker surface and a colour.\n *\n * Kept apart from the component for two reasons. It is arithmetic on numbers,\n * so it belongs on the server-safe side with the rest of `@nextlyhq/ui/color`;\n * and a saturation square is the one part of a picker that cannot be checked by\n * rendering it — jsdom reports every element as zero-sized, so a component test\n * measures nothing and passes. Measured here instead, against known corners.\n *\n * @module lib/color/picker-geometry\n */\n\n/** A position on a surface, each axis in [0, 1] from the top-left. */\nexport interface SurfacePoint {\n  x: number;\n  y: number;\n}\n\nconst clamp01 = (n: number): number => (n < 0 ? 0 : n > 1 ? 1 : n);\n\n/**\n * A pointer position as a fraction of a surface.\n *\n * Clamped, because a drag that begins inside the surface continues to report\n * while the pointer leaves it — which is the interaction people actually use to\n * reach full saturation, and without clamping it produces values outside the\n * colour space rather than the corner they are aiming at.\n *\n * A zero-sized surface answers the top-left rather than dividing by zero. That\n * happens in a test environment and on the first frame before layout.\n *\n * @experimental\n */\nexport function pointOnSurface(\n  clientX: number,\n  clientY: number,\n  rect: { left: number; top: number; width: number; height: number }\n): SurfacePoint {\n  return {\n    x: rect.width === 0 ? 0 : clamp01((clientX - rect.left) / rect.width),\n    y: rect.height === 0 ? 0 : clamp01((clientY - rect.top) / rect.height),\n  };\n}\n\n/**\n * The saturation and value a point on the square stands for.\n *\n * Value runs UPWARD while a surface's y runs downward, so the vertical axis is\n * inverted here. Getting that wrong produces a picker that looks correct and\n * selects the colour vertically mirrored from the one under the cursor.\n *\n * @experimental\n */\nexport function saturationValueAt(point: SurfacePoint): {\n  s: number;\n  v: number;\n} {\n  return { s: clamp01(point.x), v: 1 - clamp01(point.y) };\n}\n\n/**\n * Where the handle sits for a given saturation and value — the inverse of\n * {@link saturationValueAt}.\n *\n * Derived from that function's own inversion rather than written independently,\n * so the two cannot disagree about which way the axis runs.\n *\n * @experimental\n */\nexport function surfacePointFor(s: number, v: number): SurfacePoint {\n  return { x: clamp01(s), y: 1 - clamp01(v) };\n}\n\n/**\n * The hue a horizontal position stands for, in [0, 360).\n *\n * The upper bound is exclusive: 360 and 0 are the same hue, and returning 360\n * lets a handle at the far end read back as a position outside the strip.\n *\n * @experimental\n */\nexport function hueAt(fraction: number): number {\n  const hue = clamp01(fraction) * 360;\n  return hue >= 360 ? 0 : hue;\n}\n\n/** Where the hue handle sits, as a fraction of the strip. @experimental */\nexport function huePosition(hue: number): number {\n  const wrapped = ((hue % 360) + 360) % 360;\n  return wrapped / 360;\n}\n\n/**\n * The integer step a hue occupies on a strip whose last step is `max`.\n *\n * Rounding is what makes this more than a multiplication. A hue just below 360\n * — `#ff0001` is about 359.76 — rounds UP to a step past the end of the strip,\n * and the obvious repair of wrapping it with a modulo sends it to 0: the far\n * LEFT, the opposite end from where that colour belongs. The handle then sits\n * on the wrong side and any keyboard adjustment starts from there. Held at the\n * last step instead, which is where it visually belongs.\n *\n * @experimental\n */\nexport function hueSliderValue(hue: number, max: number): number {\n  const step = Math.round(huePosition(hue) * (max + 1));\n  return step > max ? max : step;\n}\n"]}

package/dist/color.d.cts

@@ -0,0 +1,251 @@
+/**
+ * Conversions between the colour models an editing surface needs.
+ *
+ * ## Why each model is here
+ *
+ * - **sRGB** is what a screen displays and what `#rrggbb` encodes. Everything ends here.
+ * - **HSV** is what a colour picker is: a square of saturation against value, beside a hue
+ *   strip. No other model puts those three controls in the shape people expect.
+ * - **OKLCH** is what this product's own theme is written in — every token in `theme.css` is an
+ *   `oklch()` value. A picker that cannot read it cannot edit the theme.
+ *
+ * ## Why the maths is here rather than in a library
+ *
+ * These are fixed, published transforms: the sRGB transfer function and the OKLab matrices are
+ * specified in CSS Color 4 and do not change. The package ships no runtime colour dependency, and
+ * this module keeps it that way. `culori` remains a DEV dependency used as a test oracle — the
+ * conversions here are cross-checked against it rather than trusted on their own.
+ *
+ * ## The part that is genuinely hard
+ *
+ * OKLCH describes more colours than a screen can show. Converting one that falls outside sRGB has
+ * no correct answer, only choices, and the naive choice — clamp each channel independently — is
+ * the wrong one: it shifts hue, because clipping red without clipping green changes the ratio
+ * between them. {@link oklchToRgb} reduces chroma instead, holding lightness and hue, which is the
+ * approach CSS Color 4 describes for gamut mapping.
+ *
+ * @module lib/color/convert
+ */
+/**
+ * An sRGB colour with channels in [0, 1]. Alpha is carried separately.
+ *
+ * @experimental
+ */
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+/**
+ * Hue in [0, 360), saturation and value in [0, 1].
+ *
+ * @experimental
+ */
+interface Hsv {
+    h: number;
+    s: number;
+    v: number;
+}
+/**
+ * Perceptual lightness in [0, 1], chroma from 0, hue in [0, 360).
+ *
+ * @experimental
+ */
+interface Oklch {
+    l: number;
+    c: number;
+    h: number;
+}
+/**
+ * Wrap a hue into [0, 360), so -30 and 330 are the same angle.
+ *
+ * @experimental
+ */
+declare function normalizeHue(hue: number): number;
+/**
+ * HSV to sRGB.
+ * Saturation and value are clamped rather than rejected: a picker drags them, and a drag that
+ * overshoots by a rounding error should saturate rather than throw.
+ *
+ * @experimental
+ */
+declare function hsvToRgb({ h, s, v }: Hsv): Rgb;
+/**
+ * sRGB to HSV.
+ * Hue is UNDEFINED for a grey and value is undefined for black, and this returns 0 for both. A
+ * picker must not take that 0 as the user's hue: it is the absence of one. Holding hue across a
+ * drag to zero saturation is the caller's job, which is why a picker keeps HSV as its state
+ * rather than deriving it from the colour each render.
+ *
+ * @experimental
+ */
+declare function rgbToHsv({ r, g, b }: Rgb): Hsv;
+/**
+ * sRGB to OKLCH.
+ *
+ * @experimental
+ */
+declare function rgbToOklch({ r, g, b }: Rgb): Oklch;
+/**
+ * OKLCH to sRGB, reducing chroma until the colour fits on screen.
+ * OKLCH can name colours a display cannot show. Clamping the channels independently is the
+ * obvious response and the wrong one: clipping red without clipping green changes the ratio
+ * between them, so the colour that appears is a DIFFERENT HUE from the one asked for. Lightness
+ * and hue are what a person chose; chroma is the part they will not miss, so chroma is what is
+ * given up.
+ * The search is a bisection on chroma, which converges to well under a perceptible step in the
+ * fixed number of rounds below — no loop that might not terminate.
+ *
+ * **The gamut is not always monotonic along this ray, and that is a deliberate trade.** At some
+ * lightness and hue pairs the boundary is crossed more than once: at `l = 0.2, h = 264.1` the ray
+ * is inside up to c ≈ 0.1192, outside until c ≈ 0.1368, briefly inside again to c ≈ 0.1386. A
+ * bisection therefore finds the FIRST boundary rather than the outermost reachable chroma.
+ *
+ * That is the intended behaviour rather than a limitation. Those islands span roughly a tenth of
+ * a degree of hue, so preferring the outermost value would make chroma jump by about 0.021
+ * between h = 264.05 and h = 264.10 — a visible step while dragging a hue slider, over a change
+ * no one can aim at. Taking the first boundary gives 0.1160, 0.1175, 0.1192, 0.1255, 0.1383
+ * across the same sweep: continuous, and one step less saturated at worst. It is also what the
+ * CSS Color 4 gamut-mapping algorithm does.
+ *
+ * @experimental
+ */
+declare function oklchToRgb({ l, c, h }: Oklch): Rgb;
+
+/**
+ * Hex is the notation people type, so it is the picker's front door.
+ *
+ * It lives beside the conversions rather than in the component that reads it, for the same reason
+ * they do: parsing `#3b82f6` is arithmetic on a string, a server rendering a token swatch needs it
+ * as much as an editing surface does, and pulling it into client code would put it behind the
+ * `"use client"` boundary for no benefit.
+ *
+ * @module lib/color/hex
+ */
+
+/**
+ * An sRGB colour with its alpha, which is what a hex string can carry and {@link Rgb} cannot.
+ *
+ * `alpha` is in [0, 1] like the channels, rather than 0-255, so it composes with the conversions
+ * without a second unit in play.
+ *
+ * @experimental
+ */
+interface Rgba extends Rgb {
+    alpha: number;
+}
+/**
+ * Read a hex colour, or `null` if the input is not one.
+ *
+ * Returns `null` rather than throwing or substituting black: this reads what someone is part-way
+ * through typing, where "not a colour yet" is the ordinary case and neither an exception nor a
+ * silent black is a useful answer. A caller decides whether to hold the last good value, show a
+ * message, or wait.
+ *
+ * Both short forms are accepted because both are what people paste. `#abc` expands by REPEATING
+ * each digit rather than padding with zero — `#abc` is `#aabbcc`, not `#a0b0c0` — which is what CSS
+ * does and the only expansion under which `#fff` is white.
+ *
+ * @experimental
+ */
+declare function parseHex(input: string): Rgba | null;
+/**
+ * Write a colour as `#rrggbb`, or `#rrggbbaa` when it is not fully opaque.
+ *
+ * The alpha pair is omitted at 1 rather than always written, because `#3b82f6ff` is the same colour
+ * and the shorter form is what someone expects to see in a field they typed `#3b82f6` into.
+ *
+ * Channels outside [0, 1] are clamped, so the result is always a valid six- or eight-digit hex
+ * string whatever a caller passes. Not for floating-point drift, which rounds to the right byte on
+ * its own: it is for a value that is wrong by a lot — a channel still in 0-255, or a computation
+ * that overshot — where the alternative is emitting `#17f00-80`, a string nothing downstream can
+ * parse and no error explains.
+ *
+ * @experimental
+ */
+declare function toHex(color: Rgb, alpha?: number): string;
+
+/**
+ * The mapping between a pointer on a picker surface and a colour.
+ *
+ * Kept apart from the component for two reasons. It is arithmetic on numbers,
+ * so it belongs on the server-safe side with the rest of `@nextlyhq/ui/color`;
+ * and a saturation square is the one part of a picker that cannot be checked by
+ * rendering it — jsdom reports every element as zero-sized, so a component test
+ * measures nothing and passes. Measured here instead, against known corners.
+ *
+ * @module lib/color/picker-geometry
+ */
+/** A position on a surface, each axis in [0, 1] from the top-left. */
+interface SurfacePoint {
+    x: number;
+    y: number;
+}
+/**
+ * A pointer position as a fraction of a surface.
+ *
+ * Clamped, because a drag that begins inside the surface continues to report
+ * while the pointer leaves it — which is the interaction people actually use to
+ * reach full saturation, and without clamping it produces values outside the
+ * colour space rather than the corner they are aiming at.
+ *
+ * A zero-sized surface answers the top-left rather than dividing by zero. That
+ * happens in a test environment and on the first frame before layout.
+ *
+ * @experimental
+ */
+declare function pointOnSurface(clientX: number, clientY: number, rect: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}): SurfacePoint;
+/**
+ * The saturation and value a point on the square stands for.
+ *
+ * Value runs UPWARD while a surface's y runs downward, so the vertical axis is
+ * inverted here. Getting that wrong produces a picker that looks correct and
+ * selects the colour vertically mirrored from the one under the cursor.
+ *
+ * @experimental
+ */
+declare function saturationValueAt(point: SurfacePoint): {
+    s: number;
+    v: number;
+};
+/**
+ * Where the handle sits for a given saturation and value — the inverse of
+ * {@link saturationValueAt}.
+ *
+ * Derived from that function's own inversion rather than written independently,
+ * so the two cannot disagree about which way the axis runs.
+ *
+ * @experimental
+ */
+declare function surfacePointFor(s: number, v: number): SurfacePoint;
+/**
+ * The hue a horizontal position stands for, in [0, 360).
+ *
+ * The upper bound is exclusive: 360 and 0 are the same hue, and returning 360
+ * lets a handle at the far end read back as a position outside the strip.
+ *
+ * @experimental
+ */
+declare function hueAt(fraction: number): number;
+/** Where the hue handle sits, as a fraction of the strip. @experimental */
+declare function huePosition(hue: number): number;
+/**
+ * The integer step a hue occupies on a strip whose last step is `max`.
+ *
+ * Rounding is what makes this more than a multiplication. A hue just below 360
+ * — `#ff0001` is about 359.76 — rounds UP to a step past the end of the strip,
+ * and the obvious repair of wrapping it with a modulo sends it to 0: the far
+ * LEFT, the opposite end from where that colour belongs. The handle then sits
+ * on the wrong side and any keyboard adjustment starts from there. Held at the
+ * last step instead, which is where it visually belongs.
+ *
+ * @experimental
+ */
+declare function hueSliderValue(hue: number, max: number): number;
+
+export { type Hsv, type Oklch, type Rgb, type Rgba, type SurfacePoint, hsvToRgb, hueAt, huePosition, hueSliderValue, normalizeHue, oklchToRgb, parseHex, pointOnSurface, rgbToHsv, rgbToOklch, saturationValueAt, surfacePointFor, toHex };