@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,456 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { AriaForwardController, customElement, HelixFormElement, MixinControllerOpen, MixinControllerValue, MixinField, PopoverController, } from '@fusion.dev/helix-core';
+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 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 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,
+        });
+        /**
+         * 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.
+         */
+        this.autocomplete = 'off';
+        /**
+         * Whether the color carries an alpha channel.
+         */
+        this.alpha = false;
+        /**
+         * 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 closed the panel and the
+             * trigger's own `toggleOpen` reopened it on the `click` that followed, so
+             * the panel could never be closed by the button that opened it. Measured
+             * across all five popover-bearing components: Menu, Popover and Tooltip
+             * already named their invoker; this one and its three siblings did not, and
+             * all four stayed open on a second press where Menu closed.
+             *
+             * `DismissController` documents this exact failure and takes a list for it.
+             * The list was the fix; using it was the part that did not happen here. */
+            boundary: () => [
+                this.renderRoot?.querySelector('[part="surface"]'),
+                this.renderRoot?.querySelector('[part="trigger"]'),
+            ],
+            offset: () => 8,
+            onDismiss: () => this.requestOpen(false),
+            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);
+            this.restore();
+        };
+        this.handlePickerChange = (event) => {
+            event.stopPropagation();
+            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();
+                this.requestOpen(false);
+                this.control?.focus();
+            }
+        };
+    }
+    /**
+     * 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;
+        }
+        return this.control ?? this.renderRoot.querySelector('[part="trigger"]');
+    }
+    get control() {
+        if (typeof this.renderRoot?.querySelector !== 'function') {
+            return null;
+        }
+        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) {
+            control.value = this.value;
+        }
+        this.sync();
+    }
+    /** Reports the value and the validity the host stands behind. */
+    sync() {
+        this.internals.setFormValue(this.value);
+        const anchor = this.anchor;
+        if (!anchor) {
+            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);
+        }
+        else if (control) {
+            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 went stale. Native `<input>` updates in exactly that case, which is
+           the behavior the mixin's own notes take as the reference. Fifteen of the
+           twenty controls here already reported unconditionally; this is one of the
+           five that did not. */
+        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();
+        }
+        else {
+            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.
+     *
+     * The other way round was considered, this element dropping its own field and
+     * letting the panel's be the only one. It is worse for a form: the value could
+     * 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"
+      exportparts="actions: picker-actions, channel: picker-channel, channel-control: picker-channel-control,
+        channel-feedback: picker-channel-feedback, channel-field: picker-channel-field,
+        channel-hint: picker-channel-hint, channel-label: picker-channel-label,
+        channel-marker: picker-channel-marker, channel-marker-label: picker-channel-marker-label,
+        channel-markers: picker-channel-markers, channel-output: picker-channel-output,
+        channels: picker-channels, controls: picker-controls, eyedropper: picker-eyedropper,
+        eyedropper-button: picker-eyedropper-button, footer: picker-footer, format: picker-format,
+        format-button: picker-format-button, grid: picker-grid,
+        grid-brightness: picker-grid-brightness, grid-handle: picker-grid-handle,
+        grid-saturation: picker-grid-saturation, icon: picker-icon, sample: picker-sample,
+        swatch: picker-swatch, swatches: picker-swatches, value: picker-value"
+      ?invalid=${this.resolvedFeedback !== ''}
+      ?alpha=${this.alpha}
+      ?no-format=${this.noFormat}
+      ?no-value=${this.variant !== 'swatch'}
+      .format=${this.format ?? 'hex'}
+      .value=${this.picked}
+      swatches=${this.swatches || nothing}
+      ?disabled=${this.isDisabled}
+      @helix-before-change=${this.handlePickerChange}
+      @change=${this.stopInner}
+      @input=${this.stopInner}
+      @helix-sample-start=${this.handleSampleStart}
+      @helix-sample-end=${this.handleSampleEnd}
+    ></${this.tag('color-picker')}>`;
+    }
+    render() {
+        return html `${this.renderLabel()}
+      <div part="field" @keydown=${this.handleKeydown}>
+        <!-- The same pair Input carries, in the same places: leading content
+             before the text, trailing content after it and before the trigger.
+             A label wanting to sit inside the field rather than over it goes
+             here, which is what the toggle group's own label-placement does and
+             what this had no way to express. Backticks stay out of this
+             comment: it is inside a tagged template, so one would end the
+             literal and the error lands on a line further down. -->
+        <slot name="start"></slot>
+        ${this.variant === 'swatch'
+            ? nothing
+            : html `<input
+          part="control"
+          id="control"
+          type="text"
+          .value=${this.value}
+          name=${this.name || nothing}
+          placeholder=${this.placeholder || nothing}
+          autocomplete=${this.autocomplete || nothing}
+          spellcheck="false"
+          aria-describedby=${this.describedBy ?? nothing}
+          ?disabled=${this.isDisabled}
+          ?required=${this.required}
+          @input=${this.handleInput}
+        />`}
+        <slot name="end"></slot>
+        <button
+          part="trigger"
+          id=${this.variant === 'swatch' ? 'control' : nothing}
+          type="button"
+          aria-controls="surface"
+          aria-expanded=${this.open ? 'true' : 'false'}
+          aria-haspopup="dialog"
+          aria-label=${this.triggerLabel}
+          ?disabled=${this.isDisabled}
+          @click=${() => this.toggleOpen()}
+        >
+          <span
+            part="preview"
+            style="--color-input-swatch: ${this.value === '' ? 'transparent' : this.painted}"
+          ></span>
+          <slot name="trigger"></slot>
+        </button>
+      </div>
+
+      <div part="surface" id="surface" popover="manual" ?hidden=${!this.open}>
+        ${this.renderPicker()}
+      </div>
+      ${this.renderHint()}${this.renderFeedback()}`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessColorInput.prototype, "autocomplete", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessColorInput.prototype, "variant", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessColorInput.prototype, "alpha", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessColorInput.prototype, "format", void 0);
+__decorate([
+    property({ attribute: 'no-format', type: Boolean })
+], HelixHeadlessColorInput.prototype, "noFormat", void 0);
+__decorate([
+    property()
+], HelixHeadlessColorInput.prototype, "placeholder", void 0);
+__decorate([
+    property()
+], HelixHeadlessColorInput.prototype, "swatches", void 0);
+__decorate([
+    property({ attribute: 'trigger-label' })
+], HelixHeadlessColorInput.prototype, "triggerLabel", void 0);
+HelixHeadlessColorInput = __decorate([
+    customElement('helix-headless-color-input')
+], HelixHeadlessColorInput);
+export { HelixHeadlessColorInput };

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

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+/** A color as the panel holds it. Alpha and the two percentages are 0 to 100. */
+export interface Color {
+    alpha: number;
+    brightness: number;
+    hue: number;
+    saturation: number;
+}
+/** The syntaxes a value can be written in. */
+export type ColorFormat = 'hex' | 'hsl' | 'rgb';
+/** HSB to bytes, which is the road every written syntax goes down. */
+export declare const toRgb: (color: Color) => {
+    blue: number;
+    green: number;
+    red: number;
+};
+/**
+ * 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 declare const splitColors: (value: string) => string[];
+/**
+ * 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 declare const parseColor: (value: string) => Color | null;
+/**
+ * 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 declare const formatColor: (color: Color, format: ColorFormat, withAlpha: boolean) => string;
+/** The color as CSS, for the swatches and the tracks. Always with its alpha. */
+export declare const toCss: (color: Color) => string;