@fusion.dev/helix-headless 0.0.0-dev

package/dist/color-picker/color.js

@@ -0,0 +1,238 @@
+/**
+ * Reading and writing the color syntaxes a field is allowed to hold.
+ *
+ * **The working model is HSB**, hue and saturation and brightness, because that
+ * is what the panel is: a square of saturation against brightness with a hue
+ * ramp beside it. HSL would put the square's corners somewhere a reader does not
+ * expect, since full saturation in HSL is a mid-lightness band rather than a
+ * corner.
+ *
+ * **Every syntax here is read; three are written.** A field that refuses
+ * `rgb(255 0 0)` because it prefers hex is a field arguing with the person using
+ * it, so the space-separated forms, the comma forms, `rgba` and `hsla` are all
+ * taken. What is written back is whichever of hex, rgb or hsl the component is
+ * set to, so a value stays in the shape the consumer asked for however it was
+ * entered.
+ *
+ * **What is written is the comma form.** Both are valid and the space-separated
+ * one is newer, which was the reason it was chosen first; the commas are what a
+ * reader recognizes, what most code around them holds, and what pastes into
+ * anything without a second thought. A syntax a value is handed *out* in is not
+ * the place to be early. `rgba` and `hsla` come with them, since a comma form
+ * with a fourth argument is spelled that way.
+ *
+ * Its own module rather than sitting in the element, because it is arithmetic
+ * with no DOM in it: this is the half worth testing directly.
+ */
+/** Keeps a number inside a range, since every channel here has one. */
+const clamp = (value, low, high) => Math.min(high, Math.max(low, value));
+/** `50%` and `0.5` mean the same thing wherever an alpha is accepted. */
+const toAlpha = (token) => {
+    if (token === undefined) {
+        return 100;
+    }
+    const number = Number.parseFloat(token);
+    if (Number.isNaN(number)) {
+        return 100;
+    }
+    return clamp(token.includes('%') ? number : number * 100, 0, 100);
+};
+/** A channel written either as `255` or as `100%`. */
+const toByte = (token) => {
+    const number = Number.parseFloat(token);
+    return clamp(token.includes('%') ? (number / 100) * 255 : number, 0, 255);
+};
+const rgbToHsb = (red, green, blue, alpha) => {
+    const r = red / 255;
+    const g = green / 255;
+    const b = blue / 255;
+    const high = Math.max(r, g, b);
+    const low = Math.min(r, g, b);
+    const span = high - low;
+    let hue = 0;
+    if (span !== 0) {
+        if (high === r) {
+            hue = (g - b) / span + (g < b ? 6 : 0);
+        }
+        else if (high === g) {
+            hue = (b - r) / span + 2;
+        }
+        else {
+            hue = (r - g) / span + 4;
+        }
+        hue *= 60;
+    }
+    return {
+        alpha,
+        brightness: Math.round(high * 100),
+        hue: Math.round(hue),
+        saturation: Math.round(high === 0 ? 0 : (span / high) * 100),
+    };
+};
+/** HSB to bytes, which is the road every written syntax goes down. */
+export const toRgb = (color) => {
+    const hue = (((color.hue % 360) + 360) % 360) / 60;
+    const saturation = color.saturation / 100;
+    const brightness = color.brightness / 100;
+    const chroma = brightness * saturation;
+    const middle = chroma * (1 - Math.abs((hue % 2) - 1));
+    const base = brightness - chroma;
+    const sextants = [
+        [chroma, middle, 0],
+        [middle, chroma, 0],
+        [0, chroma, middle],
+        [0, middle, chroma],
+        [middle, 0, chroma],
+        [chroma, 0, middle],
+    ];
+    const [red, green, blue] = sextants[Math.floor(hue) % 6] ?? [0, 0, 0];
+    return {
+        blue: Math.round((blue + base) * 255),
+        green: Math.round((green + base) * 255),
+        red: Math.round((red + base) * 255),
+    };
+};
+/** HSB to HSL, which is a different pair of numbers for the same color. */
+const toHsl = (color) => {
+    const saturation = color.saturation / 100;
+    const brightness = color.brightness / 100;
+    const lightness = (brightness * (2 - saturation)) / 2;
+    return {
+        hue: ((color.hue % 360) + 360) % 360,
+        lightness: Math.round(lightness * 100),
+        saturation: Math.round((lightness === 0 || lightness === 1
+            ? 0
+            : (brightness - lightness) / Math.min(lightness, 1 - lightness)) * 100),
+    };
+};
+/**
+ * Splits a comma-separated list of colors, ignoring the commas inside them.
+ *
+ * A plain `split(',')` is what this was, and it cannot hold the legacy syntaxes:
+ * `#ef4444, rgb(249 115 22), rgba(34,197,94,.5)` came apart into six fragments,
+ * four of them not colors, and the row quietly rendered three swatches instead
+ * of four. The modern space-separated forms survived it, which is what made the
+ * list look like it worked.
+ *
+ * Depth rather than a regular expression, because the thing that matters is
+ * whether a comma is inside a function call and that is exactly what a counter
+ * answers. No color syntax nests, so a single counter is enough.
+ */
+export const splitColors = (value) => {
+    const found = [];
+    let depth = 0;
+    let current = '';
+    for (const character of value) {
+        if (character === '(') {
+            depth += 1;
+        }
+        else if (character === ')') {
+            depth = Math.max(0, depth - 1);
+        }
+        if (character === ',' && depth === 0) {
+            found.push(current.trim());
+            current = '';
+        }
+        else {
+            current += character;
+        }
+    }
+    found.push(current.trim());
+    return found.filter(Boolean);
+};
+/**
+ * Any of the syntaxes to the working model, or `null` where it is not a color.
+ *
+ * Named colors are not here. Resolving `rebeccapurple` means either shipping
+ * the table of a hundred and forty or asking the browser, and the browser is not
+ * present on the server: a field that accepted a name client-side and rejected
+ * it during a server render would be worse than one that never took it.
+ */
+export const parseColor = (value) => {
+    const text = value.trim().toLowerCase();
+    if (text === '') {
+        return null;
+    }
+    if (text.startsWith('#')) {
+        const digits = text.slice(1);
+        const short = digits.length === 3 || digits.length === 4;
+        const long = digits.length === 6 || digits.length === 8;
+        if ((!short && !long) || !/^[\da-f]+$/.test(digits)) {
+            return null;
+        }
+        const width = short ? 1 : 2;
+        const channel = (index) => {
+            const piece = digits.slice(index * width, index * width + width);
+            return Number.parseInt(short ? piece + piece : piece, 16);
+        };
+        const carriesAlpha = digits.length === 4 || digits.length === 8;
+        return rgbToHsb(channel(0), channel(1), channel(2), carriesAlpha ? Math.round((channel(3) / 255) * 100) : 100);
+    }
+    /* Commas and the slash both become spaces, which collapses every legal
+       spelling into one list: `rgba(255,0,0,0.5)` and `rgb(255 0 0 / 50%)` are the
+       same four tokens by the time they are read. */
+    const call = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(text);
+    if (!call?.[1] || call[2] === undefined) {
+        return null;
+    }
+    /* Destructured with a fallback rather than indexed, because an index into an
+       array is `string | undefined` here and three of these are read twice. Four
+       names cost less than six assertions. */
+    const [first = '', second = '', third = '', fourth] = call[2]
+        .replace(/[,/]/g, ' ')
+        .split(/\s+/)
+        .filter(Boolean);
+    if (first === '' || second === '' || third === '') {
+        return null;
+    }
+    const alpha = toAlpha(fourth);
+    if (call[1].startsWith('rgb')) {
+        return rgbToHsb(toByte(first), toByte(second), toByte(third), alpha);
+    }
+    const hue = Number.parseFloat(first);
+    const saturation = clamp(Number.parseFloat(second), 0, 100) / 100;
+    const lightness = clamp(Number.parseFloat(third), 0, 100) / 100;
+    if (Number.isNaN(hue) || Number.isNaN(saturation) || Number.isNaN(lightness)) {
+        return null;
+    }
+    // HSL to HSB, the inverse of `toHsl` above.
+    const brightness = lightness + saturation * Math.min(lightness, 1 - lightness);
+    return {
+        alpha,
+        brightness: Math.round(brightness * 100),
+        hue: Math.round(((hue % 360) + 360) % 360),
+        saturation: Math.round((brightness === 0 ? 0 : 2 * (1 - lightness / brightness)) * 100),
+    };
+};
+/**
+ * The working model back out, in the syntax asked for.
+ *
+ * The alpha is written only where the component carries one. A consumer who did
+ * not ask for transparency should not have to strip `ff` off every hex or read
+ * past a fourth argument they never wanted.
+ */
+export const formatColor = (color, format, withAlpha) => {
+    const alpha = clamp(color.alpha, 0, 100) / 100;
+    /* Two decimal places at most, and no trailing zeros: an alpha is a fraction
+       here and `0.5` is what a stylesheet holds, not `0.50` and not
+       `0.5019607843137255`. */
+    const opacity = Number(alpha.toFixed(2));
+    if (format === 'hsl') {
+        const { hue, lightness, saturation } = toHsl(color);
+        const body = `${Math.round(hue)}, ${saturation}%, ${lightness}%`;
+        return withAlpha ? `hsla(${body}, ${opacity})` : `hsl(${body})`;
+    }
+    const { blue, green, red } = toRgb(color);
+    if (format === 'rgb') {
+        const body = `${red}, ${green}, ${blue}`;
+        return withAlpha ? `rgba(${body}, ${opacity})` : `rgb(${body})`;
+    }
+    const byte = (one) => one.toString(16).padStart(2, '0');
+    const hex = `#${byte(red)}${byte(green)}${byte(blue)}`;
+    return withAlpha ? hex + byte(Math.round(alpha * 255)) : hex;
+};
+/** The color as CSS, for the swatches and the tracks. Always with its alpha. */
+export const toCss = (color) => {
+    const { blue, green, red } = toRgb(color);
+    return `rgb(${red} ${green} ${blue} / ${clamp(color.alpha, 0, 100)}%)`;
+};

package/dist/color-picker/index.d.ts

@@ -0,0 +1,2 @@
+export * from './color.js';
+export * from './root/color-picker-root.js';

package/dist/color-picker/index.js

@@ -0,0 +1,2 @@
+export * from './color.js';
+export * from './root/color-picker-root.js';

package/dist/color-picker/root/color-picker-root.d.ts

@@ -0,0 +1,303 @@
+import { HelixFormElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import '../../button/index.js';
+import '../../button-group/index.js';
+import '../../slider/index.js';
+import { type Color, type ColorFormat } from '../color.js';
+declare const HelixHeadlessColorPicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
+/**
+ * @summary Picks a color, from a square and two ramps.
+ *
+ * @description
+ * **The picker itself, with no field around it.** Color Input is this element in
+ * a panel behind a text field, the same way Date Input is `helix-date-picker` in a
+ * panel: a form wants a field, and a settings pane or a toolbar wants the picker
+ * sitting flat on the page with nothing to open. Neither should be the other one
+ * with parts hidden.
+ *
+ * **The square is two real range inputs.** Saturation and brightness are each an
+ * `<input type="range">`, laid over the square and made invisible, and the
+ * handle is drawn from their values. The pointer gets the square; the keyboard
+ * gets the arrow keys, Home, End and the page keys; a screen reader gets two
+ * sliders that announce a name and a number. All of it is the platform's, and
+ * nothing here implements a key handler. There is no `role="application"`, which
+ * is the usual way this control is built and amounts to asking a screen reader
+ * to stop helping.
+ *
+ * **The working model is HSB, and the value is derived from it.** The reverse
+ * loses colors: black is `brightness: 0`, whose hue and saturation are both
+ * undefined, so a reader who drags to the bottom of the square and back would
+ * get gray where they had red. Holding the model means a color survives a trip
+ * through one that has no hue. A value arriving from outside is read into the
+ * model once, which is the only moment the conversion runs in that direction.
+ *
+ * **Every syntax is read; the one `format` names is written.** `#f00`,
+ * `#ff0000`, `rgb(255 0 0)`, `rgba(255,0,0,.5)` and `hsl(0 100% 50%)` are all
+ * colors. Named colors are the exception, and deliberately: resolving
+ * `rebeccapurple` means shipping a table of a hundred and forty or asking the
+ * browser, and there is no browser during a server render.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Color, ColorArea, Swatch picker
+ * @documentation https://helix.fusion.dev/components/color-picker
+ *
+ * @slot eyedropper-icon - The glyph on the screen-sampling control, usually a dropper.
+ *
+ * @event {Event} change - Announced once the value has moved.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the color changes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixCopyEvent} helix-copy - Fired when the color is put on the clipboard.
+ * @event {HelixSampleEndEvent} helix-sample-end - The eyedropper has closed, whether or not a color was taken.
+ * @event {HelixSampleStartEvent} helix-sample-start - The eyedropper is opening, so anything covering the page should get out of the way.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart actions - The group holding the eyedropper and the syntax toggle.
+ * @csspart channel - One ramp.
+ * @csspart channel-control - The range input.
+ * @csspart channel-feedback - What is wrong with it.
+ * @csspart channel-field - The row: the control and its readout.
+ * @csspart channel-hint - Help under the track, while nothing is wrong.
+ * @csspart channel-label - The question, over the track.
+ * @csspart channel-marker - One mark.
+ * @csspart channel-marker-label - The value a mark stands at, when `marker-labels` is set.
+ * @csspart channel-markers - The row of marks along the track.
+ * @csspart channel-output - The current value, shown beside it.
+ * @csspart channels - The ramps beside it.
+ * @csspart controls - The row under the square.
+ * @csspart eyedropper - The control that samples a color from the screen.
+ * @csspart eyedropper-button - The inner control.
+ * @csspart footer - The row holding the value and the tools.
+ * @csspart format - The control that changes the syntax the value is written in.
+ * @csspart format-button - The inner control.
+ * @csspart grid - The saturation and brightness square.
+ * @csspart grid-brightness - The range input for its vertical axis.
+ * @csspart grid-handle - The mark showing where in the square the color sits.
+ * @csspart grid-saturation - The range input for the square's horizontal axis.
+ * @csspart icon - A glyph this component draws.
+ * @csspart sample - The chip of the current color, which copies it when pressed.
+ * @csspart swatch - One preset.
+ * @csspart swatches - The row of presets.
+ * @csspart value - The color as text, which can be typed or pasted.
+ *
+ * @cssproperty --color-picker-brightness - The chosen brightness, 0 to 100, as a percentage.
+ * @cssproperty --color-picker-hue - The chosen hue, 0 to 360, unitless.
+ * @cssproperty --color-picker-saturation - The chosen saturation, 0 to 100, as a percentage.
+ * @cssproperty --color-picker-swatch - A color to paint: the current one on the sample, a preset's on each preset.
+ */
+export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_base {
+    /**
+     * What the browser may autofill in the text field, as a platform token.
+     *
+     * **Defaults to `off`, which is not the platform's default and is the
+     * point.** The field filters a list rather than collecting a value, so a
+     * browser offering to fill it with a saved address is competing for the same
+     * keystrokes as the listbox. A consumer who wants autofill can still ask.
+     */
+    autocomplete: string;
+    /**
+     * Whether the current selection fails validation.
+     *
+     * A flag rather than a message, which is the split Date Picker already drew and
+     * these two now follow. A flat picker has no room of its own for a sentence:
+     * the field that wraps one owns the label, the hint and the feedback, and a
+     * second message inside the panel would be the same error said twice. What is
+     * left for the picker is the one thing the field cannot draw from outside, the
+     * mark on the answer itself.
+     */
+    invalid: boolean;
+    /**
+     * Whether the color carries an alpha channel.
+     *
+     * Off by default, because it widens every value written, and a consumer who
+     * did not ask for transparency should not have to strip a byte off each one.
+     */
+    alpha: boolean;
+    /**
+     * The syntax the value is written in: `hex`, `rgb` or `hsl`.
+     *
+     * Only what is written. Everything is read whatever this says, so a picker on
+     * `hex` still takes an `rgb()` handed to it and stores the hex for it.
+     */
+    format?: ColorFormat;
+    /**
+     * Whether to leave the value out, for a picker whose value is stated elsewhere.
+     *
+     * The row reads the color as text and lets it be typed or pasted, which is
+     * what makes this element complete standing on a page: a square and two ramps
+     * can build a color and cannot state one, and a reader who has a hex already
+     * should not have to find it by dragging.
+     *
+     * Color Input sets this, because its field is that input. Two editable fields
+     * for one value is the outcome worth avoiding: two places to type, and no
+     * answer to which one is authoritative or which has the caret. The other way
+     * round was considered, Color Input dropping its own field and letting this be
+     * the only one, and it is worse for a form: the value cannot be read or pasted
+     * without opening a panel.
+     */
+    noValue: boolean;
+    /**
+     * Whether the reader may change the format.
+     */
+    noFormat: boolean;
+    /**
+     * Whether the eyedropper is offered where the browser has one.
+     */
+    noEyedropper: boolean;
+    /**
+     * Colors offered under the picker, as a comma-separated list.
+     */
+    swatches: string;
+    /**
+     * The color the reader has moved to, or nothing while they have moved none.
+     *
+     * Held rather than re-read, which is the whole point: see the class
+     * description. Cleared whenever a value arrives from anywhere else, so the
+     * next reading comes from that value instead.
+     */
+    private moved;
+    /**
+     * Whether this browser can sample a color off the screen.
+     *
+     * Settled after the first render rather than at construction, because there is
+     * no `window` on the server, and a button that ships in the markup and does
+     * nothing in Firefox is worse than one that is never offered.
+     */
+    private sampling;
+    /**
+     * Whether the value on this element was produced here.
+     *
+     * The one bit that keeps the model from being overwritten by the value it just
+     * produced. Without it, dragging to the bottom of the square writes black,
+     * which reads back as hue 0 and saturation 0, and the next drag starts gray.
+     */
+    private owned;
+    /** Where the picker stands: what was moved, or what the value says, or the start. */
+    get color(): Color;
+    /**
+     * Whether the tools row holds anything at all.
+     *
+     * The group is withheld rather than rendered empty, because it is an element
+     * with a role and a name: an empty group labeled "Color tools" announces
+     * nothing, and the footer cannot tell it is empty either, so the row kept its
+     * padding with nothing in it.
+     */
+    private get tools();
+    /** The presets, as written, with anything that is not a color dropped. */
+    private get presets();
+    /**
+     * The last value that was a color.
+     *
+     * Half-typed input reaches the row on every keystroke and most of it is not a
+     * color, so the square is given the last thing that was one. Typing `#00ff00`
+     * a character at a time goes `#`, `#0`, `#00`, `#00f`, `#00ff`, `#00ff0`,
+     * `#00ff00`: two of those are colors and the ones between are not, so without
+     * this the square walks red, blue, red, green. Color Input keeps the same
+     * guard for its own field, each local to the input it protects.
+     */
+    private settled;
+    /** Takes what was typed, and lets the square follow only a whole color. */
+    private readonly handleValueInput;
+    /** Moves part of the model and announces the value that follows from it. */
+    private readonly move;
+    /**
+     * Copying the value, which is the one thing here worth taking away.
+     *
+     * A reader who has just built a color wants it in a stylesheet, and the
+     * alternative is selecting text out of a field that may not be on screen. The
+     * chip is the obvious target: it is the color, at the size of a control, and
+     * it had no job at all before this.
+     *
+     * The controller rather than the four lines it replaces, because a copy button
+     * is coming and the two share everything that is easy to get wrong: the write,
+     * the confirmation, the timer that ends it, the event, and a failure that is
+     * correctly silent.
+     */
+    private readonly copier;
+    /** Takes a preset, in this picker's syntax rather than as the preset spelled it. */
+    private readonly handleSwatch;
+    /** Walks the format on, and rewrites the value in it. */
+    private readonly handleFormat;
+    /**
+     * Samples a color from anywhere on the screen.
+     *
+     * `helix-sample-start` and `helix-sample-end` bracket it, because whatever is
+     * holding this picker may need to get out of the way: `EyeDropper` takes the
+     * pointer over, and a floating panel left up during it is one the reader
+     * cannot dismiss and may well be trying to sample from underneath. This
+     * element cannot know it is in a panel, so it says what it is doing and lets
+     * whatever does know decide.
+     */
+    private readonly handleEyeDropper;
+    /**
+     * Dragging in the square.
+     *
+     * The two ranges are the state, so this reads a point and writes to them
+     * rather than keeping a position of its own. Pointer capture, so a drag that
+     * leaves the square keeps going: leaving and coming back is how a reader
+     * reaches a corner, and without it the handle stops wherever the pointer left.
+     */
+    private readonly handleGridPointer;
+    protected firstUpdated(changed: import('lit').PropertyValues): void;
+    protected updated(changed: import('lit').PropertyValues): void;
+    /** Puts the keyboard on the square, which is the control a reader wants. */
+    focus(options?: FocusOptions): void;
+    /** One of the ramps under the square. */
+    protected renderChannel(channel: 'alpha' | 'hue', label: string, max: number, value: number): TemplateResult;
+    /**
+     * One axis of the area, taken the way `takeChannel` takes a rail.
+     *
+     * **Named rather than inline because of the first line.** These were two arrow
+     * functions that moved the color and stopped nothing, so the `<input
+     * type="range">` behind each axis sent its own composed `input` straight past
+     * this element to whoever was listening on it: a consumer dragging the area
+     * received the range's event and not this component's. `takeChannel` beside it
+     * has stopped its own since it was written, which is what made the omission
+     * hard to see. Found by sweeping every family that renders a native control.
+     */
+    private takeArea;
+    /**
+     * A channel's new value, read off the slider that just applied it.
+     *
+     * **Both native events, because a slider sends both and at different
+     * moments.** It is one of the controls a reader edits continuously, so it
+     * announces `input` all the way through a drag and `change` when the drag
+     * ends. Listening only for the commit meant the picker heard nothing while a
+     * handle moved and the hue and alpha handles did not move at all.
+     *
+     * **Read off the target rather than out of a detail**, which is what changed
+     * on 26 Aug 2026. This bound `helix-input` and `helix-change` and took the
+     * proposed value out of the event. Those are requests: they announce what the
+     * slider is *about* to do, before anything has moved and while a listener may
+     * still refuse it. The native pair fires after the slider applied, so the
+     * value is on the element and cannot disagree with it. See 294.
+     *
+     * Idempotent, so taking both costs nothing: the same value applied twice is
+     * the same color.
+     */
+    private takeChannel;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * The eyedropper and the swatch tools, which are a group of buttons, behind a seam the styled tier can move.
+     *
+     * A method rather than a fragment inline, so a tier above can render its own,
+     * wrap this one, pass it a property the base does not know about, or leave it
+     * out, without reimplementing the whole template to do any of them. The tag is
+     * interpolated rather than written, so `tier` resolves it: this renders the
+     * headless element, and a styled subclass that sets `tier` renders the styled one
+     * from the same template.
+     */
+    protected renderTools(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-color-picker': HelixHeadlessColorPicker;
+    }
+}
+export {};