@fusion.dev/helix-headless 0.2.0 → 0.4.0

package/dist/color-input/root/color-input-root.js

@@ -8,152 +8,22 @@ import { AriaForwardController, customElement, HelixFormElement, MixinController
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
-/* Side-effect import, because this renders a picker in its own shadow root and
-   a custom element registers on import. The path is relative, so this registers
-   the base picker and the styled file's identical import registers the styled
-   one; `tier` picks which name the template asks for. */
 import '../../color-picker/index.js';
 import { parseColor, toCss } from '../../color-picker/color.js';
-/**
- * @summary A color, typed in any syntax or picked from a panel.
- *
- * @description
- * **The picker is `helix-color-picker`, not a second one written here.** It owns the
- * square, the ramps, the eyedropper and the syntax toggle, and it is worth
- * having on its own: a settings pane wants a picker flat on the page with
- * nothing to open. This element is the field, the overlay, and the form.
- * Exactly the arrangement Date Input has with `helix-date-picker`.
- *
- * **Typed as well as picked, and the typing is the reason this is not
- * `<input type="color">`.** The native control gives a free picker and takes
- * nearly all styling with it, which is a fair trade until a product needs the
- * panel to match everything around it. What is kept from the native one is the
- * part worth keeping: a real text field, so a reader who has the hex pastes it
- * and never opens anything.
- *
- * **Every syntax is read; the one `format` names is written.** `#f00`,
- * `#ff0000`, `rgb(255 0 0)`, `rgba(255,0,0,.5)`, `rgb(255 0 0 / 50%)` and
- * `hsl(0 100% 50%)` are all colors, and a field that refuses one because it
- * prefers another is arguing with the person using it. What the field *shows* is
- * the value itself, for the reason Date Input gives about its dates: half-typed
- * input does not survive a round trip through a formatter.
- *
- * The custom property below is written by this component and never set by a
- * consumer: it carries a value this element resolved and CSS cannot, which is
- * what lets a stylesheet on this tier paint the swatch without parsing anything
- * itself.
- *
- * @since 0.1.0
- * @status experimental
- * @category forms
- * @aliases ColorField, ColourInput, InputColor
- * @documentation https://helix.fusion.dev/components/color-input
- *
- * @slot end - Content at the trailing end, before the trigger.
- * @slot feedback - What is wrong with it.
- * @slot hint - Help under the field.
- * @slot start - Content at the leading end of the field, inside its border.
- * @slot trigger - The mark on the field saying a panel opens.
- *
- * @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 {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
- *
- * @csspart control - The text input carrying the value. Absent in `swatch`.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box holding the text and the trigger.
- * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart label - The question, over the field.
- * @csspart picker - The color picker inside it.
- * @csspart picker-actions - The group holding the eyedropper and the syntax toggle.
- * @csspart picker-channel - One ramp.
- * @csspart picker-channel-control - The range input.
- * @csspart picker-channel-feedback - What is wrong with it.
- * @csspart picker-channel-field - The row: the control and its readout.
- * @csspart picker-channel-hint - Help under the track, while nothing is wrong.
- * @csspart picker-channel-label - The question, over the track.
- * @csspart picker-channel-marker - One mark.
- * @csspart picker-channel-marker-label - The value a mark stands at, when `marker-labels` is set.
- * @csspart picker-channel-markers - The row of marks along the track.
- * @csspart picker-channel-output - The current value, shown beside it.
- * @csspart picker-channels - The ramps beside it.
- * @csspart picker-controls - The row under the square.
- * @csspart picker-eyedropper - The control that samples a color from the screen.
- * @csspart picker-eyedropper-button - The inner control.
- * @csspart picker-footer - The row holding the value and the tools.
- * @csspart picker-format - The control that changes the syntax the value is written in.
- * @csspart picker-format-button - The inner control.
- * @csspart picker-grid - The saturation and brightness square.
- * @csspart picker-grid-brightness - The range input for its vertical axis.
- * @csspart picker-grid-handle - The mark showing where in the square the color sits.
- * @csspart picker-grid-saturation - The range input for the square's horizontal axis.
- * @csspart picker-icon - A glyph this component draws.
- * @csspart picker-sample - The chip of the current color, which copies it when pressed.
- * @csspart picker-swatch - One preset.
- * @csspart picker-swatches - The row of presets.
- * @csspart picker-value - The color as text, which can be typed or pasted.
- * @csspart preview - The chip showing the color, inside the trigger.
- * @csspart surface - The floating panel.
- * @csspart trigger - The control that opens the panel.
- *
- * @cssproperty --color-input-swatch - The chosen color, to paint over the transparency check.
- */
 let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinControllerOpen(MixinControllerValue(MixinField(HelixFormElement))) {
     constructor() {
         super(...arguments);
-        /* A consumer's `aria-describedby` names ids in their own tree and the control
-           is in this shadow root, so the reference has to be carried down as an
-           element rather than copied as an id. See `AriaForwardController`: measured
-           in Chrome's own tree, the host held the description and the control the
-           reader is actually on was exposed without it. */
         this.aria = new AriaForwardController(this, {
             target: () => this.renderRoot?.querySelector('[part="control"]') ?? null,
         });
-        /**
-         * Whether the color carries an alpha channel.
-         */
         this.alpha = false;
-        /**
-         * 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 holds a color, so a browser offering to fill it with a
-         * saved address is competing for the same keystrokes as the picker. A
-         * consumer who wants autofill can still ask.
-         */
         this.autocomplete = 'off';
-        /**
-         * Whether the reader may change the format from the panel.
-         */
         this.noFormat = false;
-        /**
-         * What the field says before a color is in it.
-         */
         this.placeholder = '#000000';
-        /**
-         * Colors offered under the picker, as a comma-separated list.
-         */
         this.swatches = '';
-        /**
-         * Accessible name for the control that opens the panel.
-         */
         this.triggerLabel = 'Choose a color';
-        /** The overlay, placed against the field for the reason Date Input gives. */
         this.panel = new PopoverController(this, {
             anchor: () => this.renderRoot?.querySelector('[part="field"]'),
-            /* The surface *and* the trigger.
-             *
-             * A control is not always one element: the button that opens this panel is
-             * part of it, and a press on it is not a press outside. Scoped to the
-             * surface alone, `pointerdown` on the trigger closes the panel and the
-             * trigger's own `toggleOpen` reopens it on the `click` that follows, so the
-             * panel can never be closed by the button that opened it.
-             *
-             * `DismissController` documents this exact failure and takes a list for
-             * it. */
             boundary: () => [
                 this.renderRoot?.querySelector('[part="surface"]'),
                 this.renderRoot?.querySelector('[part="trigger"]'),
@@ -163,23 +33,7 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinControl
             placement: 'bottom-start',
             surface: () => this.renderRoot?.querySelector('[part="surface"]'),
         });
-        /**
-         * The last value that was a color.
-         *
-         * Half-typed input reaches here on every keystroke and most of it is not a
-         * color, so the picker is given the last thing that was one rather than a
-         * fallback. Typing `#00ff00` one character at a time goes `#`, `#0`, `#00`,
-         * `#00f`, `#00ff`, `#00ff0`, `#00ff00`: measured, the square went red, red,
-         * red, blue, blue, **red**, green, because two of those are colors and the
-         * ones between are not. Holding the last good one takes the flicker out and
-         * leaves the square on blue until green arrives.
-         *
-         * Not state, because it is only ever read on a render the value already
-         * caused. The same reasoning Date Input records for its calendar, which will
-         * not follow a date until the field says something complete.
-         */
         this.settled = '';
-        /** Relayed under this element's name, so a consumer hears one control. */
         this.handleInput = (event) => {
             event.stopPropagation();
             this.requestValue(event.target.value);
@@ -190,21 +44,12 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinControl
             this.requestValue(event.detail.value);
             this.restore();
         };
-        /**
-         * The picker is about to take the pointer over, so the panel gets out of the
-         * way and comes back after.
-         *
-         * `helix-color-picker` says what it is doing rather than reaching for a panel it
-         * cannot know it is in. A floating panel left up during an eyedropper is one
-         * the reader cannot dismiss and may well be trying to sample from underneath.
-         */
         this.handleSampleStart = () => {
             this.requestOpen(false);
         };
         this.handleSampleEnd = () => {
             this.requestOpen(true);
         };
-        /** Escape shuts the panel without moving the color. */
         this.handleKeydown = (event) => {
             if (event.key === 'Escape' && this.open) {
                 event.stopPropagation();
@@ -213,14 +58,6 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinControl
             }
         };
     }
-    /**
-     * What the label points at and validity hangs off.
-     *
-     * The input where there is one, the trigger where there is not. `setValidity`
-     * needs an element to anchor the message to and a label needs something
-     * focusable to name, and in `swatch` the trigger is the only control in the
-     * field. It carries `id="control"` there for the same reason.
-     */
     get anchor() {
         if (typeof this.renderRoot?.querySelector !== 'function') {
             return null;
@@ -233,22 +70,13 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinControl
         }
         return this.renderRoot.querySelector('[part="control"]');
     }
-    /** What the picker should show, which is only ever a color. */
     get picked() {
         return parseColor(this.value) ? this.value : this.settled;
     }
-    /** What the trigger's swatch paints, which is only ever a color. */
     get painted() {
         const parsed = parseColor(this.value);
         return parsed ? toCss(parsed) : 'transparent';
     }
-    /*
-     * Puts the field back where the answer differs from what was typed.
-     *
-     * `requestValue` announces and decides; this is the other half, which Input
-     * and Date Input both need for the same reason: the native control has already
-     * changed, so wherever the answer does not follow it, it has to be restored.
-     */
     restore() {
         const control = this.control;
         if (control && control.value !== this.value) {
@@ -256,7 +84,6 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinControl
         }
         this.sync();
     }
-    /** Reports the value and the validity the host stands behind. */
     sync() {
         this.internals.setFormValue(this.value);
         const anchor = this.anchor;
@@ -264,10 +91,6 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinControl
             return;
         }
         const control = this.control;
-        /* Checked here rather than left to the input, which is `text` and has no
-           idea what a color is. `type="color"` is what was given up to own the
-           panel, and it would not have helped: it has no invalid state, because it
-           cannot hold one. */
         if (this.value !== '' && parseColor(this.value) === null) {
             this.internals.setValidity({ badInput: true }, 'Enter a color, like #ff0000, rgb(255 0 0) or hsl(0 100% 50%).', anchor);
         }
@@ -275,36 +98,20 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinControl
             this.internals.setValidity(control.validity, control.validationMessage, control);
         }
         else {
-            /* A swatch has no native validity of its own, so `required` is the only
-               thing left to check and this element has to check it: an empty value on
-               a required field is the one state a block of color can be wrong in. */
             this.internals.setValidity(this.required && this.value === '' ? { valueMissing: true } : {}, this.required && this.value === '' ? 'Choose a color.' : '', anchor);
         }
         this.refreshFeedback();
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        // Whatever the markup arrived with, so a form knows before anything is typed.
         this.sync();
     }
     updated(changed) {
         super.updated(changed);
-        /* Every update, not only the ones that name `value`.
-           `value` is an accessor over `valueState ?? defaultValue`, so a consumer
-           moving `default-value` on an untouched control moves what the form
-           submits without ever putting `value` in the changed map, and the reported
-           entry goes stale. Native `<input>` updates in exactly that case, which is
-           the behavior the mixin's own notes take as the reference. */
         this.sync();
         if (changed.has('value') && parseColor(this.value)) {
             this.settled = this.value;
         }
-        /* Driven from here rather than from the toggle, because `open` is a property
-           a consumer may set directly and the panel has to follow either way. The
-           controller is idempotent, so arriving twice for one open costs nothing.
-           Without this the surface stays `display: none`, a `popover` element being
-           hidden until something shows it, and the square inside measures zero,
-           which is the one measurement a drag cannot work without. */
         if (this.open) {
             this.panel.show();
         }
@@ -312,33 +119,9 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinControl
             this.panel.hide();
         }
     }
-    /** Puts the caret in the field, the way a label pointing at one would. */
     focus(options) {
         this.anchor?.focus(options);
     }
-    /*
-     * The picker is told `no-value` because the field above it is that input.
-     *
-     * Standing on a page, helix-color-picker states its own color as text: a square and
-     * two ramps can build one and cannot state one, and a reader who already has a
-     * hex should not have to find it by dragging. Here that row would be a second
-     * editable field for the same value, which is two places to type with no
-     * answer to which one is authoritative or which has the caret.
-     *
-     * Not the other way round, this element dropping its own field and letting the
-     * panel's be the only one: the value could then not be read at a glance or
-     * pasted without opening a panel.
-     */
-    /**
-     * The picker the field opens, 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.
-     */
     renderPicker() {
         return html `<${this.tag('color-picker')}
       part="picker"

package/dist/color-picker/color.js

@@ -1,31 +1,4 @@
-/**
- * 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 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;
@@ -36,7 +9,6 @@ const toAlpha = (token) => {
     }
     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);
@@ -68,7 +40,6 @@ const rgbToHsb = (red, green, blue, alpha) => {
         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;
@@ -91,7 +62,6 @@ export const toRgb = (color) => {
         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;
@@ -104,19 +74,6 @@ const toHsl = (color) => {
             : (brightness - lightness) / Math.min(lightness, 1 - lightness)) * 100),
     };
 };
-/**
- * Splits a comma-separated list of colors, ignoring the commas inside them.
- *
- * A plain `split(',')` cannot hold the legacy syntaxes:
- * `#ef4444, rgb(249 115 22), rgba(34,197,94,.5)` comes apart into six fragments,
- * four of them not colors, and the row quietly renders three swatches instead of
- * four. The modern space-separated forms survive it, which is what makes such a
- * list look like it works.
- *
- * 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;
@@ -139,14 +96,6 @@ export const splitColors = (value) => {
     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 === '') {
@@ -167,16 +116,10 @@ export const parseColor = (value) => {
         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+/)
@@ -194,7 +137,6 @@ export const parseColor = (value) => {
     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,
@@ -203,18 +145,8 @@ export const parseColor = (value) => {
         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);
@@ -230,7 +162,6 @@ export const formatColor = (color, format, withAlpha) => {
     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)}%)`;