@enigmax/primitives 0.23.0 → 0.24.0

package/registry.json

@@ -156,7 +156,7 @@
     {
       "name": "input",
       "title": "Input, one field for every type",
-      "description": "A field you pass props to, typed by its `type`: password gets the reveal toggle, a generator, a strength meter and a breach check; search gets debouncing, ranking and a clear button; everything else is a plain field with native props. What each type needs is loaded when that type is used, so a form of text fields ships none of it.",
+      "description": "A field you pass props to, typed by its `type`: password gets the reveal toggle, a generator, a strength meter and a breach check; search gets debouncing, ranking and a clear button; color gets a swatch and a picker panel - saturation square, hue and alpha rails, presets and the screen eyedropper - instead of the operating system popup; everything else is a plain field with native props. What each type needs is loaded when that type is used, so a form of text fields ships none of it.",
       "targets": [
         "vanilla",
         "astro",
@@ -224,7 +224,8 @@
           ],
           "rewrite": {
             "@/core/search": "./search-core",
-            "@/core/password": "./password-core"
+            "@/core/password": "./password-core",
+            "@/core/color": "./color-core"
           }
         },
         {
@@ -262,6 +263,43 @@
             "@/core/search": "./search-core"
           }
         },
+        {
+          "path": "src/core/color.ts",
+          "dest": "input/color-core.ts",
+          "targets": [
+            "vanilla",
+            "astro",
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/input/color-styles.ts",
+          "dest": "input/color-styles.ts",
+          "targets": [
+            "react"
+          ]
+        },
+        {
+          "path": "src/react/input/color.tsx",
+          "dest": "input/color.tsx",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/color": "./color-core",
+            "@/react/input/write-value": "./write-value",
+            "@/react/input/color-styles": "./color-styles",
+            "@/react/input/types": "./types"
+          }
+        },
+        {
+          "path": "recipes/color/styles.css",
+          "dest": "input/color.css",
+          "targets": [
+            "react"
+          ],
+          "style": "css"
+        },
         {
           "path": "recipes/input/styles.css",
           "dest": "input/styles.css",
@@ -286,7 +324,8 @@
             "@/react/input/types": "./types",
             "@/react/input/password": "./password",
             "@/react/input/search": "./search",
-            "@/core/password": "./password-core"
+            "@/core/password": "./password-core",
+            "@/react/input/color": "./color"
           }
         },
         {
@@ -322,7 +361,26 @@
         "[data-enigma-password-strength-segment][data-filled]",
         "[data-enigma-password-strength-label]",
         "[data-enigma-password-strength-warning]",
-        "[data-enigma-input-action=clear]"
+        "[data-enigma-input-action=clear]",
+        "[data-enigma-color]",
+        "[data-enigma-color][data-open]",
+        "[data-enigma-color-swatch]",
+        "[data-enigma-color-swatch][data-invalid]",
+        "[data-enigma-color-checkers]",
+        "[data-enigma-color-fill]",
+        "[data-enigma-color-panel]",
+        "[data-enigma-color-panel][data-side=top]",
+        "[data-enigma-color-area]",
+        "[data-enigma-color-controls]",
+        "[data-enigma-color-rails]",
+        "[data-enigma-color-rail=hue]",
+        "[data-enigma-color-rail=alpha]",
+        "[data-enigma-color-gradient]",
+        "[data-enigma-color-thumb]",
+        "[data-enigma-color-preview]",
+        "[data-enigma-color-eyedropper]",
+        "[data-enigma-color-swatches]",
+        "[data-enigma-color-preset]"
       ],
       "docs": "docs/notes/primitives.md#input",
       "recipes": [
@@ -739,7 +797,7 @@
     {
       "name": "context-menu",
       "title": "Context menu",
-      "description": "A right-click menu with the desktop's behaviour: submenus that open on a beat of hovering and survive a diagonal pointer, icons, a second line, shortcuts printed on the right, checkable and radio rows, separators and captions, destructive rows in red, an optional heading naming what it acts on, a filter once a level is long, a long level rendered a window at a time, and a submenu fetched on demand and cached. Opens at the pointer, on a long press, and on Shift+F10. A menu with no rows does not open at all. It brings its own theme - an unstyled popup is transparent text over the page rather than a plain-looking control.",
+      "description": "A right-click menu with the desktop's behaviour: submenus that open on a beat of hovering and survive a diagonal pointer, icons, a second line, shortcuts printed on the right, checkable and radio rows, separators and captions, destructive rows in red, an optional heading naming what it acts on, a filter once a level is long, a long level rendered a window at a time, and a submenu fetched on demand and cached. Opens at the pointer, on a long press, and on Shift+F10. Copy, Cut and Paste are built from whatever was right-clicked and are on by default, because the browser menu this one replaces has them. A menu with no rows does not open at all. It brings its own theme - an unstyled popup is transparent text over the page rather than a plain-looking control.",
       "targets": [
         "react"
       ],
@@ -779,6 +837,16 @@
             "@/core/keys": "./keys"
           }
         },
+        {
+          "path": "src/core/clipboard-menu.ts",
+          "dest": "context-menu/clipboard-menu.ts",
+          "targets": [
+            "react"
+          ],
+          "rewrite": {
+            "@/core/context-menu": "./context-menu"
+          }
+        },
         {
           "path": "src/react/slot.tsx",
           "dest": "context-menu/slot.tsx",
@@ -823,7 +891,8 @@
             "@/core/keys": "./keys",
             "@/react/slot": "./slot",
             "@/react/context-menu/styles": "./styles",
-            "@/react/context-menu/context": "./context"
+            "@/react/context-menu/context": "./context",
+            "@/core/clipboard-menu": "./clipboard-menu"
           }
         },
         {
@@ -838,7 +907,8 @@
             "@/react/context-menu/context": "./context",
             "@/react/context-menu/styles": "./styles",
             "@/core/context-menu": "./context-menu",
-            "@/core/keys": "./keys"
+            "@/core/keys": "./keys",
+            "@/core/clipboard-menu": "./clipboard-menu"
           }
         }
       ],

package/src/core/clipboard-menu.ts

@@ -0,0 +1,270 @@
+/**
+ * The rows every context menu on a desktop already has: Copy, Cut and Paste.
+ *
+ * A menu opened over a selection or over a field is expected to offer them - the browser's own
+ * does, and replacing that menu with a custom one takes them away without saying so. Which is
+ * why they are ON by default here and turned off with a prop, rather than the other way round:
+ * the defect is silent, so the default has to be the safe one.
+ *
+ * WHAT DECIDES THEY APPEAR is what was right-clicked, and it is read at the moment the menu
+ * opens, not from React state - by then the selection is settled (a `contextmenu` event fires
+ * after the press has adjusted it) and the caret is still where the visitor left it.
+ *
+ * - **Copy**, when there is selected text under the pointer.
+ * - **Cut**, when that selection is also in something writable.
+ * - **Paste**, in anything writable - and disabled when the clipboard is known to be empty.
+ *
+ * Not a React module: what a selection is, whether a field takes writes, and how text is put
+ * back into one are DOM questions, so a menu drawn by anything else gets the same rows.
+ */
+
+import type { ContextMenuEntry } from "@/core/context-menu";
+
+/** The ids these rows carry. Namespaced, so they can never collide with a caller's own. */
+export const CLIPBOARD_PREFIX = "enigma:clipboard:";
+
+export type ClipboardAction = "copy" | "cut" | "paste";
+
+/**
+ * Input types with a text selection.
+ *
+ * An allowlist rather than a guess: reading `selectionStart` on `number`, `date`, `color` or
+ * `email` throws `InvalidStateError` in every browser, because the spec only defines the
+ * selection API for these five. A try/catch would hide it; knowing which is which is better.
+ */
+const SELECTABLE_TYPES = new Set(["text", "search", "url", "tel", "password"]);
+
+/** What the menu was opened over, as far as the clipboard is concerned. */
+export interface ClipboardTarget {
+    /** The field or contenteditable under the pointer, or null when it is neither. */
+    editable: HTMLElement | null;
+    /** Whether that element takes writes: not disabled, not read-only. */
+    writable: boolean;
+    /** The selected text, from the field's own selection or the document's. */
+    selection: string;
+    /**
+     * Whether that text may be put on the clipboard.
+     *
+     * False for a password field. The clipboard is shared with every other application on the
+     * machine and is not cleared, so a menu that copies a password out of a masked field
+     * leaks it somewhere the visitor cannot see - and the browser's own menu refuses too.
+     */
+    copyable: boolean;
+    /** Where the selection was, so it can be put back after the menu has taken focus. */
+    range: { start: number; end: number; } | null;
+}
+
+export interface ClipboardMenuLabels {
+    copy?: string;
+    cut?: string;
+    paste?: string;
+}
+
+export interface ClipboardMenuOptions {
+    copy?: boolean;
+    cut?: boolean;
+    paste?: boolean;
+    labels?: ClipboardMenuLabels;
+    /** Whatever the renderer draws icons with. `unknown`, because a core cannot know. */
+    icons?: { copy?: unknown; cut?: unknown; paste?: unknown; };
+    /** The clipboard is known to be empty, so Paste is listed and greyed rather than missing. */
+    clipboardEmpty?: boolean;
+}
+
+const EMPTY: ClipboardTarget = { editable: null, writable: false, selection: "", copyable: true, range: null };
+
+function isEditableElement(node: Element | null): node is HTMLElement {
+    return Boolean(node && (node as HTMLElement).isContentEditable);
+}
+
+/** The text selected in the document, but only where it touches the element clicked on. */
+function documentSelection(element: Element | null): string {
+    const selection = typeof window === "undefined" ? null : window.getSelection();
+    if (!selection || selection.isCollapsed || selection.rangeCount === 0) return "";
+    const range = selection.getRangeAt(0);
+    // Selected text elsewhere on the page is not what this menu is over: a right-click away
+    // from a selection offers to copy something the visitor is not pointing at.
+    if (element && !range.intersectsNode(element)) return "";
+    return selection.toString();
+}
+
+/** What was right-clicked, read the moment the menu opens. */
+export function inspectClipboardTarget(node: EventTarget | null): ClipboardTarget {
+    if (typeof document === "undefined") return EMPTY;
+    const element = node instanceof Element ? node : null;
+
+    const field = element?.closest?.("input, textarea") as HTMLInputElement | HTMLTextAreaElement | null;
+    if (field) {
+        const password = field instanceof HTMLInputElement && field.type === "password";
+        const selectable = field instanceof HTMLTextAreaElement || SELECTABLE_TYPES.has(field.type);
+        const start = selectable ? field.selectionStart ?? 0 : 0;
+        const end = selectable ? field.selectionEnd ?? 0 : 0;
+        return {
+            editable: field,
+            writable: !field.disabled && !field.readOnly,
+            selection: selectable ? field.value.slice(start, end) : "",
+            copyable: !password,
+            range: selectable ? { start, end } : null
+        };
+    }
+
+    const editable = isEditableElement(element) ? (element.closest("[contenteditable]") as HTMLElement | null) ?? element : null;
+    return {
+        editable,
+        writable: Boolean(editable),
+        selection: documentSelection(element),
+        copyable: true,
+        // A contenteditable's selection is a live DOM Range the browser keeps for us; there is
+        // no pair of offsets to restore, and re-focusing the element puts the caret back.
+        range: null
+    };
+}
+
+/**
+ * Whether the clipboard has text in it, or null when that cannot be known.
+ *
+ * Null is the common answer and not a failure: reading the clipboard needs permission, and
+ * asking for it puts a browser prompt on screen just to decide whether to grey out a row -
+ * which is a worse trade than showing an enabled Paste that turns out to do nothing. So the
+ * permission is only READ, never requested, and the clipboard is only opened where it has
+ * already been granted.
+ */
+export async function clipboardHasText(): Promise<boolean | null> {
+    if (typeof navigator === "undefined" || !navigator.clipboard?.readText) return null;
+    try {
+        const status = await navigator.permissions?.query({ name: "clipboard-read" as PermissionName });
+        if (status?.state !== "granted") return null;
+        return (await navigator.clipboard.readText()).length > 0;
+    } catch {
+        // Firefox has no `clipboard-read` in its permission registry, Safari refuses the
+        // query outright. Both mean "unknown", which is what the caller already handles.
+        return null;
+    }
+}
+
+/** The rows for this target, in the order every desktop menu puts them. */
+export function clipboardEntries(target: ClipboardTarget, options: ClipboardMenuOptions = {}): ContextMenuEntry[] {
+    const { copy = true, cut = true, paste = true, labels = {}, icons = {}, clipboardEmpty = false } = options;
+    const entries: ContextMenuEntry[] = [];
+    const selected = target.selection.length > 0 && target.copyable;
+    const canPaste = typeof navigator !== "undefined" && Boolean(navigator.clipboard?.readText);
+
+    if (copy && selected) {
+        entries.push({ id: `${CLIPBOARD_PREFIX}copy`, label: labels.copy ?? "Copy", shortcut: "Mod+C", icon: icons.copy });
+    }
+    if (cut && selected && target.writable) {
+        entries.push({ id: `${CLIPBOARD_PREFIX}cut`, label: labels.cut ?? "Cut", shortcut: "Mod+X", icon: icons.cut });
+    }
+    if (paste && target.writable && canPaste) {
+        entries.push({
+            id: `${CLIPBOARD_PREFIX}paste`,
+            label: labels.paste ?? "Paste",
+            shortcut: "Mod+V",
+            icon: icons.paste,
+            // Listed and greyed rather than dropped: a row that disappears between two opens
+            // is read as the menu being unreliable, and every desktop menu greys this one.
+            disabled: clipboardEmpty
+        });
+    }
+    return entries;
+}
+
+/** Which clipboard row an id belongs to, or null for anything that is not one of ours. */
+export function clipboardAction(id: string): ClipboardAction | null {
+    if (!id.startsWith(CLIPBOARD_PREFIX)) return null;
+    const action = id.slice(CLIPBOARD_PREFIX.length);
+    return action === "copy" || action === "cut" || action === "paste" ? action : null;
+}
+
+/**
+ * Put the caret back where it was before the menu took focus.
+ *
+ * Choosing a row moves focus into the panel and then destroys it, so by the time the action
+ * runs the field is not focused and its selection is gone. Both are restored first, or Cut
+ * deletes nothing and Paste inserts at position zero.
+ */
+function restore(target: ClipboardTarget): void {
+    const element = target.editable;
+    if (!element) return;
+    element.focus({ preventScroll: true });
+    if (!target.range) return;
+    const field = element as HTMLInputElement | HTMLTextAreaElement;
+    try { field.setSelectionRange(target.range.start, target.range.end); } catch { /* not selectable */ }
+}
+
+/**
+ * Write a value the way a keystroke would, for either kind of field.
+ *
+ * The same trick `<Input>` uses, and for the same reason: assigning `.value` is invisible to
+ * React, which compares against the last value it rendered and skips the change event. The
+ * setter has to come from the element's OWN prototype - a textarea's is not an input's.
+ */
+function writeFieldValue(field: HTMLInputElement | HTMLTextAreaElement, next: string): void {
+    const prototype = field instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+    const setter = Object.getOwnPropertyDescriptor(prototype, "value")?.set;
+    if (setter) setter.call(field, next);
+    else field.value = next;
+    field.dispatchEvent(new Event("input", { bubbles: true }));
+}
+
+/**
+ * Replace what is selected with `text` (or delete it, when `text` is empty).
+ *
+ * `execCommand("insertText")` first, deprecated as it is: it is the only insertion that joins
+ * the browser's own UNDO stack, so Ctrl+Z after a paste behaves like a paste and not like a
+ * value that appeared from nowhere. The fallback is exact and does everything but the undo.
+ */
+function replaceSelection(target: ClipboardTarget, text: string): void {
+    const element = target.editable;
+    if (!element) return;
+
+    try {
+        if (document.execCommand("insertText", false, text)) return;
+    } catch {
+        // Denied, or not implemented. The fallback below is the whole behaviour anyway.
+    }
+
+    const field = element as HTMLInputElement | HTMLTextAreaElement;
+    if (typeof field.setSelectionRange !== "function" || target.range === null) return;
+    const start = field.selectionStart ?? target.range.start;
+    const end = field.selectionEnd ?? target.range.end;
+    writeFieldValue(field, field.value.slice(0, start) + text + field.value.slice(end));
+    const caret = start + text.length;
+    try { field.setSelectionRange(caret, caret); } catch { /* not selectable */ }
+}
+
+/**
+ * Do what the row says.
+ *
+ * Called straight from the press that chose it, so the browser still counts it as a user
+ * gesture - which is what the clipboard API requires and what makes a paste possible at all.
+ * Returns whether the action happened: a refused permission and an empty clipboard are both
+ * "no", and neither is worth an exception the caller has to catch.
+ */
+export async function performClipboardAction(action: ClipboardAction, target: ClipboardTarget): Promise<boolean> {
+    restore(target);
+
+    if (action === "copy" || action === "cut") {
+        if (!target.selection || !target.copyable) return false;
+        try {
+            await navigator.clipboard.writeText(target.selection);
+        } catch {
+            // An insecure context, or a browser that refuses without permission. The
+            // deprecated command still works in both, and it is the only fallback there is.
+            try { if (!document.execCommand("copy")) return false; } catch { return false; }
+        }
+        if (action === "cut" && target.writable) replaceSelection(target, "");
+        return true;
+    }
+
+    if (!target.writable) return false;
+    try {
+        const text = await navigator.clipboard.readText();
+        if (!text) return false;
+        replaceSelection(target, text);
+        return true;
+    } catch {
+        // Refused, dismissed, or empty. Nothing changed, so there is nothing to report.
+        return false;
+    }
+}

package/src/core/color.ts

@@ -0,0 +1,248 @@
+/**
+ * Reading a colour, writing one, and converting between the two models a picker needs.
+ *
+ * Arithmetic only, like every other core here: no DOM, no framework. The picker drags a
+ * saturation/value square and a hue rail, which are HSV; a form field holds `#3b82f6`,
+ * `rgb(59, 130, 246)` or an `hsl()`, which is what a stylesheet and a database take. This
+ * module is the translation between them.
+ *
+ * Two things it does NOT do, both on purpose:
+ *
+ * - **Named colours.** `red`, `rebeccapurple` and the other 146 are a table nobody needs in
+ *   a bundle to drag a square, and the DOM already resolves them for free (assign the name
+ *   to `style.color` and read it back). The picker's canonical value is a hex string.
+ * - **Colour spaces past sRGB.** `oklch()` and `color()` describe colours a hex cannot, so
+ *   accepting one here and handing back `#rrggbb` would silently clip it. Parsing returns
+ *   null instead, which the field reports as unparseable rather than as a different colour.
+ */
+
+/** sRGB, 0-255 per channel, with alpha 0-1. The transport shape everything converts through. */
+export interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+}
+
+/** Hue 0-360, saturation and value 0-1, alpha 0-1. What the picker's two controls move. */
+export interface Hsv {
+    h: number;
+    s: number;
+    v: number;
+    a: number;
+}
+
+/** Hue 0-360, saturation and lightness 0-1, alpha 0-1. Only used by `hsl()` in and out. */
+export interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+    a: number;
+}
+
+/** How a colour is written back into the field. */
+export type ColorFormat = "hex" | "rgb" | "hsl";
+
+export interface FormatColorOptions {
+    /** Write the alpha channel. Off drops it, so a half-transparent colour becomes opaque. */
+    alpha?: boolean;
+}
+
+function clamp(value: number, min: number, max: number): number {
+    return value < min ? min : value > max ? max : value;
+}
+
+/** 0-1, and never NaN: an unparsed alpha must not travel as one and poison every later sum. */
+function clampAlpha(value: number): number {
+    return Number.isFinite(value) ? clamp(value, 0, 1) : 1;
+}
+
+function channel(value: number): number {
+    return Math.round(clamp(value, 0, 255));
+}
+
+/** `"50%"` -> 0.5, `"0.5"` -> 0.5. Both spellings are legal for every CSS component. */
+function ratio(token: string, scale: number): number {
+    const text = token.trim();
+    const value = Number.parseFloat(text);
+    if (!Number.isFinite(value)) return Number.NaN;
+    return text.endsWith("%") ? (value / 100) * scale : value;
+}
+
+/**
+ * The components inside `rgb(...)` / `hsl(...)`, however they are punctuated.
+ *
+ * CSS Color 4 allows `rgb(0 0 0 / 50%)` beside the legacy `rgba(0, 0, 0, 0.5)`, and both
+ * turn up in real stylesheets - a value pasted out of devtools is usually the space form.
+ * Splitting on the separators rather than matching one syntax accepts them both without a
+ * second regular expression to keep in step with the first.
+ */
+function components(body: string): string[] {
+    return body.split(/[\s,/]+/).map((part) => part.trim()).filter(Boolean);
+}
+
+/**
+ * A colour string to sRGB, or null when it is not one.
+ *
+ * Null is the whole point of the return type: a field is unparseable for as long as someone
+ * is halfway through typing `#3b8`, and a picker that guesses at that moment fights the
+ * caret. Everything here is tolerant of what a person types - a missing `#`, upper case,
+ * stray spaces - and intolerant of what would be a guess.
+ */
+export function parseColor(input: string): Rgb | null {
+    const text = input.trim().toLowerCase();
+    if (!text) return null;
+
+    // The one keyword worth a line: it is what an empty colour is called everywhere in CSS,
+    // and a picker that cannot read back what it wrote for alpha 0 is broken.
+    if (text === "transparent") return { r: 0, g: 0, b: 0, a: 0 };
+
+    const hex = /^#?([0-9a-f]+)$/.exec(text);
+    if (hex) return fromHex(hex[1]);
+
+    const functional = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(text);
+    if (!functional) return null;
+
+    const parts = components(functional[2]);
+    if (parts.length < 3 || parts.length > 4) return null;
+    const alpha = parts.length === 4 ? clampAlpha(ratio(parts[3], 1)) : 1;
+
+    if (functional[1].startsWith("rgb")) {
+        const values = parts.slice(0, 3).map((part) => ratio(part, 255));
+        if (values.some((value) => !Number.isFinite(value))) return null;
+        return { r: channel(values[0]), g: channel(values[1]), b: channel(values[2]), a: alpha };
+    }
+
+    // `hsl(210deg 40% 96%)`. The angle units past degrees are rare enough in hand-written CSS
+    // that supporting them would be speculative; a plain number is degrees, which is the rule
+    // CSS itself uses.
+    const hue = Number.parseFloat(parts[0]);
+    const saturation = ratio(parts[1], 1);
+    const lightness = ratio(parts[2], 1);
+    if (!Number.isFinite(hue) || !Number.isFinite(saturation) || !Number.isFinite(lightness)) return null;
+    return hslToRgb({ h: hue, s: clamp(saturation, 0, 1), l: clamp(lightness, 0, 1), a: alpha });
+}
+
+/**
+ * `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa` - and nothing else.
+ *
+ * Five and seven digits are REFUSED rather than padded. A truncated paste is the common way
+ * to arrive at one, and inventing the missing digit produces a colour nobody chose.
+ */
+function fromHex(digits: string): Rgb | null {
+    const size = digits.length;
+    if (size !== 3 && size !== 4 && size !== 6 && size !== 8) return null;
+
+    const short = size <= 4;
+    const at = (index: number): number => {
+        const slice = short ? digits[index].repeat(2) : digits.slice(index * 2, index * 2 + 2);
+        return Number.parseInt(slice, 16);
+    };
+    const alpha = size === 4 || size === 8 ? at(3) / 255 : 1;
+    return { r: at(0), g: at(1), b: at(2), a: clampAlpha(alpha) };
+}
+
+/** `#rrggbb`, or `#rrggbbaa` when alpha is asked for and the colour is not opaque. */
+export function toHex(color: Rgb, options: FormatColorOptions = {}): string {
+    const pair = (value: number): string => channel(value).toString(16).padStart(2, "0");
+    const alpha = clampAlpha(color.a);
+    const suffix = options.alpha && alpha < 1 ? pair(Math.round(alpha * 255)) : "";
+    return `#${pair(color.r)}${pair(color.g)}${pair(color.b)}${suffix}`;
+}
+
+/**
+ * A colour back to a string.
+ *
+ * The legacy comma syntax for `rgb()` and `hsl()`, deliberately: this string is going into a
+ * field someone will paste into a stylesheet, a spreadsheet or an older toolchain, and the
+ * space-and-slash form is the one those still refuse.
+ */
+export function formatColor(color: Rgb, format: ColorFormat = "hex", options: FormatColorOptions = {}): string {
+    const alpha = clampAlpha(color.a);
+    const opaque = !options.alpha || alpha >= 1;
+    // Three decimals: enough to survive a round trip through a hex byte (1/255), short enough
+    // that the field does not fill up with digits nobody chose.
+    const printed = Number.parseFloat(alpha.toFixed(3));
+
+    if (format === "hex") return toHex(color, options);
+    if (format === "rgb") {
+        const body = `${channel(color.r)}, ${channel(color.g)}, ${channel(color.b)}`;
+        return opaque ? `rgb(${body})` : `rgba(${body}, ${printed})`;
+    }
+
+    const hsl = rgbToHsl(color);
+    const body = `${Math.round(hsl.h)}, ${Math.round(hsl.s * 100)}%, ${Math.round(hsl.l * 100)}%`;
+    return opaque ? `hsl(${body})` : `hsla(${body}, ${printed})`;
+}
+
+/**
+ * sRGB to HSV, keeping a hue the arithmetic cannot see.
+ *
+ * THE colour picker bug, and it is in almost every hand-rolled one: hue is undefined at
+ * black, at white and at every grey, because those have no dominant channel. Recomputing it
+ * from the RGB therefore returns 0 - red - so dragging the square into its bottom-left
+ * corner and back out again resets a hue the visitor picked, and the rail jumps under their
+ * finger. `fallbackHue` is the hue they last chose, and it is what the picker keeps its own
+ * state for.
+ */
+export function rgbToHsv(color: Rgb, fallbackHue = 0): Hsv {
+    const r = clamp(color.r, 0, 255) / 255;
+    const g = clamp(color.g, 0, 255) / 255;
+    const b = clamp(color.b, 0, 255) / 255;
+    const max = Math.max(r, g, b);
+    const span = max - Math.min(r, g, b);
+
+    let h = fallbackHue;
+    if (span > 0) {
+        if (max === r) h = ((g - b) / span) % 6;
+        else if (max === g) h = (b - r) / span + 2;
+        else h = (r - g) / span + 4;
+        h *= 60;
+        if (h < 0) h += 360;
+    }
+
+    return { h, s: max === 0 ? 0 : span / max, v: max, a: clampAlpha(color.a) };
+}
+
+export function hsvToRgb(color: Hsv): Rgb {
+    const h = ((color.h % 360) + 360) % 360;
+    const s = clamp(color.s, 0, 1);
+    const v = clamp(color.v, 0, 1);
+
+    const c = v * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = v - c;
+    const [r, g, b] = h < 60 ? [c, x, 0]
+        : h < 120 ? [x, c, 0]
+            : h < 180 ? [0, c, x]
+                : h < 240 ? [0, x, c]
+                    : h < 300 ? [x, 0, c]
+                        : [c, 0, x];
+
+    return { r: channel((r + m) * 255), g: channel((g + m) * 255), b: channel((b + m) * 255), a: clampAlpha(color.a) };
+}
+
+/** sRGB to HSL. Same undefined hue at the greys, same reason to pass the one being kept. */
+export function rgbToHsl(color: Rgb, fallbackHue = 0): Hsl {
+    const hsv = rgbToHsv(color, fallbackHue);
+    const l = hsv.v * (1 - hsv.s / 2);
+    // Saturation is not shared between the two models: at the same hue, HSL's denominator is
+    // how far the lightness is from black OR white, which is why a "vivid" HSV colour flattens
+    // if its saturation is copied across instead of converted.
+    const s = l === 0 || l === 1 ? 0 : (hsv.v - l) / Math.min(l, 1 - l);
+    return { h: hsv.h, s: clamp(s, 0, 1), l, a: hsv.a };
+}
+
+export function hslToRgb(color: Hsl): Rgb {
+    const s = clamp(color.s, 0, 1);
+    const l = clamp(color.l, 0, 1);
+    const v = l + s * Math.min(l, 1 - l);
+    return hsvToRgb({ h: color.h, s: v === 0 ? 0 : 2 * (1 - l / v), v, a: color.a });
+}
+
+/** Same colour, to the byte. Used to tell a value the picker wrote from one someone typed. */
+export function colorEquals(a: Rgb | null, b: Rgb | null): boolean {
+    if (!a || !b) return a === b;
+    return channel(a.r) === channel(b.r) && channel(a.g) === channel(b.g) && channel(a.b) === channel(b.b)
+        && Math.round(clampAlpha(a.a) * 255) === Math.round(clampAlpha(b.a) * 255);
+}