@fusion.dev/helix-headless 0.142.1 → 0.144.0

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

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     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, MixinPickerField, parseColor, toCss, } from '@fusion.dev/helix-core';
+import { AriaForwardController, colorName, customElement, HelixFormElement, MixinControllerOpen, MixinControllerValue, MixinField, MixinPickerField, parseColor, toCss, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
@@ -17,8 +17,12 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
         });
         this.alpha = false;
         this.autocomplete = 'off';
+        this.channelFields = false;
+        this.colorWords = {};
         this.noFormat = false;
         this.placeholder = '#000000';
+        this.readOnly = false;
+        this.announcesInput = true;
         this.swatches = '';
         this.triggerLabel = 'Choose a color';
         this.settled = '';
@@ -32,9 +36,17 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
             if (event.composedPath()[0] !== event.currentTarget) {
                 return;
             }
-            this.requestValue(event.detail.value);
+            if (!this.requestValue(event.detail.value)) {
+                event.preventDefault();
+            }
             this.restore();
         };
+        this.handlePickerSettled = (event) => {
+            event.stopPropagation();
+            if (event.composedPath()[0] === event.currentTarget) {
+                this.announceChange();
+            }
+        };
         this.handleSampleStart = () => {
             this.requestOpen(false);
         };
@@ -42,12 +54,31 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
             this.requestOpen(true);
         };
     }
+    requestValue(next) {
+        if (this.readOnly) {
+            return false;
+        }
+        return super.requestValue(next);
+    }
+    requestOpen(next) {
+        if (next && this.readOnly) {
+            return false;
+        }
+        return super.requestOpen(next);
+    }
     get anchor() {
         return this.control ?? this.partNamed('trigger');
     }
     get picked() {
         return parseColor(this.value) ? this.value : this.settled;
     }
+    get swatchWords() {
+        const parsed = parseColor(this.value);
+        if (!parsed) {
+            return this.value || this.triggerLabel;
+        }
+        return `${colorName(parsed, this.colorWords, this.lang)} ${this.value}`;
+    }
     get painted() {
         const parsed = parseColor(this.value);
         return parsed ? toCss(parsed) : 'transparent';
@@ -85,21 +116,25 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
         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, eyedropper-text: picker-eyedropper-text, footer: picker-footer, format: picker-format,
-        format-button: picker-format-button, format-text: picker-format-text, grid: picker-grid,
+        eyedropper-button: picker-eyedropper-button, eyedropper-live: picker-eyedropper-live, eyedropper-text: picker-eyedropper-text,
+        field: picker-field, field-input: picker-field-input, field-label: picker-field-label,
+        fields: picker-fields, footer: picker-footer, format: picker-format,
+        format-button: picker-format-button, format-live: picker-format-live, format-text: picker-format-text, 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}
+      ?channel-fields=${this.channelFields}
       ?no-format=${this.noFormat}
       ?no-value=${this.variant !== 'swatch'}
+      .colorWords=${this.colorWords}
       .format=${this.format ?? 'hex'}
       .value=${this.picked}
       swatches=${this.swatches || nothing}
       ?disabled=${this.isDisabled}
       @helix-before-change=${this.handlePickerChange}
-      @change=${this.stopInner}
+      @change=${this.handlePickerSettled}
       @input=${this.stopInner}
       @helix-sample-start=${this.handleSampleStart}
       @helix-sample-end=${this.handleSampleEnd}
@@ -130,8 +165,11 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
           aria-describedby=${this.describedBy ?? nothing}
           aria-invalid=${this.invalidity ?? nothing}
           ?disabled=${this.isDisabled}
+          ?readonly=${this.readOnly}
           ?required=${this.required}
+          @change=${this.handleCommit}
           @input=${this.handleInput}
+          @keypress=${this.handleKeypress}
         />`}
         <slot name="end"></slot>
         <button
@@ -139,6 +177,7 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
           id=${this.variant === 'swatch' ? 'control' : nothing}
           type="button"
           aria-controls="surface"
+          aria-disabled=${this.readOnly ? 'true' : nothing}
           aria-expanded=${this.open ? 'true' : 'false'}
           aria-haspopup="dialog"
           aria-label=${this.variant === 'swatch' ? nothing : this.triggerLabel}
@@ -148,7 +187,7 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
                 : 'swatch-value'
             : nothing}
           ?disabled=${this.isDisabled}
-          @click=${() => this.toggleOpen()}
+          @click=${this.handleTriggerClick}
         >
           <span
             part="preview"
@@ -156,7 +195,7 @@ let HelixHeadlessColorInput = class HelixHeadlessColorInput extends MixinPickerF
           ></span>
           <slot name="trigger"></slot>
           ${this.variant === 'swatch'
-            ? html `<span id="swatch-value" hidden>${this.value || this.triggerLabel}</span>`
+            ? html `<span id="swatch-value" hidden>${this.swatchWords}</span>`
             : nothing}
         </button>
       </div>
@@ -181,6 +220,12 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessColorInput.prototype, "autocomplete", void 0);
+__decorate([
+    property({ attribute: 'channel-fields', type: Boolean })
+], HelixHeadlessColorInput.prototype, "channelFields", void 0);
+__decorate([
+    property({ attribute: 'color-words', type: Object })
+], HelixHeadlessColorInput.prototype, "colorWords", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessColorInput.prototype, "format", void 0);
@@ -190,6 +235,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessColorInput.prototype, "placeholder", void 0);
+__decorate([
+    property({ attribute: 'readonly', reflect: true, type: Boolean })
+], HelixHeadlessColorInput.prototype, "readOnly", void 0);
 __decorate([
     property()
 ], HelixHeadlessColorInput.prototype, "swatches", void 0);

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

@@ -0,0 +1,26 @@
+import { type Color, type ColorFormat } from '@fusion.dev/helix-core';
+/** One number a color is written with, in the syntax the picker writes. */
+export type ChannelName = 'alpha' | 'blue' | 'green' | 'hue' | 'lightness' | 'red' | 'saturation';
+/** A channel as a field shows it: its number and the range it may take. */
+export interface ChannelField {
+    channel: ChannelName;
+    max: number;
+    min: number;
+    value: number;
+}
+/**
+ * The numbers a color is written with in `format`, for a field each, as React
+ * Aria's ColorField takes a `channel`: red, green and blue for hex and rgb,
+ * hue, saturation and lightness for hsl, and the opacity where the picker
+ * carries one.
+ *
+ * Hex is written as bytes, so its fields are the bytes: a field of two hex
+ * digits would ask a reader to count in base sixteen.
+ */
+export declare const channelFields: (value: string, color: Color, format: ColorFormat, alpha: boolean) => ChannelField[];
+/**
+ * The value with one channel set, kept inside the channel's range and written
+ * in `format` the way the picker writes every value: the comma form, and the
+ * opacity only with `alpha`. `null` where the number is no number.
+ */
+export declare const writeChannel: (fields: readonly ChannelField[], format: ColorFormat, alpha: boolean, channel: ChannelName, value: number) => string | null;

package/dist/color-picker/channels.js

@@ -0,0 +1,84 @@
+import { toHsl, toRgb } from '@fusion.dev/helix-core';
+const clamp = (value, low, high) => Math.min(high, Math.max(low, value));
+const percent = (token) => {
+    if (token === undefined) {
+        return 100;
+    }
+    const number = Number.parseFloat(token);
+    return Number.isNaN(number) ? 100 : clamp(token.includes('%') ? number : number * 100, 0, 100);
+};
+const readWritten = (value, format) => {
+    const text = value.trim().toLowerCase();
+    if (format !== 'hsl' && /^#([\da-f]{3,4}|[\da-f]{6}|[\da-f]{8})$/.test(text)) {
+        const digits = text.slice(1);
+        const width = digits.length <= 4 ? 1 : 2;
+        const byte = (index) => {
+            const piece = digits.slice(index * width, index * width + width);
+            return Number.parseInt(width === 1 ? piece + piece : piece, 16);
+        };
+        const count = digits.length / width;
+        return [byte(0), byte(1), byte(2), count === 4 ? Math.round((byte(3) / 255) * 100) : 100];
+    }
+    const call = /^(rgba?|hsla?)\(([^)]*)\)$/.exec(text);
+    if (!call?.[1] || call[2] === undefined) {
+        return null;
+    }
+    if (call[1].startsWith('hsl') !== (format === 'hsl')) {
+        return null;
+    }
+    const [first, second, third, fourth] = call[2].replace(/[,/]/g, ' ').split(/\s+/).filter(Boolean);
+    const numbers = [first, second, third].map((one) => Number.parseFloat(one ?? ''));
+    if (numbers.some(Number.isNaN)) {
+        return null;
+    }
+    return [...numbers, percent(fourth)].map((one) => Math.round(one));
+};
+export const channelFields = (value, color, format, alpha) => {
+    const written = readWritten(value, format);
+    const fromModel = () => {
+        if (format === 'hsl') {
+            const { hue, lightness, saturation } = toHsl(color);
+            return [Math.round(hue), saturation, lightness, Math.round(color.alpha)];
+        }
+        const { blue, green, red } = toRgb(color);
+        return [red, green, blue, Math.round(color.alpha)];
+    };
+    const [one = 0, two = 0, three = 0, four = 100] = written ?? fromModel();
+    const fields = format === 'hsl'
+        ? [
+            { channel: 'hue', max: 360, min: 0, value: one },
+            { channel: 'saturation', max: 100, min: 0, value: two },
+            { channel: 'lightness', max: 100, min: 0, value: three },
+        ]
+        : [
+            { channel: 'red', max: 255, min: 0, value: one },
+            { channel: 'green', max: 255, min: 0, value: two },
+            { channel: 'blue', max: 255, min: 0, value: three },
+        ];
+    return alpha ? [...fields, { channel: 'alpha', max: 100, min: 0, value: four }] : fields;
+};
+export const writeChannel = (fields, format, alpha, channel, value) => {
+    if (Number.isNaN(value)) {
+        return null;
+    }
+    const numbers = new Map(fields.map((field) => [field.channel, field.value]));
+    const field = fields.find((one) => one.channel === channel);
+    if (field === undefined) {
+        return null;
+    }
+    numbers.set(channel, clamp(Math.round(value), field.min, field.max));
+    const get = (name, fallback = 0) => numbers.get(name) ?? fallback;
+    const opacity = get('alpha', 100);
+    const fraction = Number((opacity / 100).toFixed(2));
+    if (format === 'hsl') {
+        const body = `${get('hue')}, ${get('saturation')}%, ${get('lightness')}%`;
+        return alpha ? `hsla(${body}, ${fraction})` : `hsl(${body})`;
+    }
+    if (format === 'rgb') {
+        const body = `${get('red')}, ${get('green')}, ${get('blue')}`;
+        return alpha ? `rgba(${body}, ${fraction})` : `rgb(${body})`;
+    }
+    const byte = (one) => one.toString(16).padStart(2, '0');
+    const hex = `#${byte(get('red'))}${byte(get('green'))}${byte(get('blue'))}`;
+    return alpha ? hex + byte(Math.round((opacity / 100) * 255)) : hex;
+};

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

@@ -1,4 +1,4 @@
-import { type Color, type ColorFormat, HelixFormElement } from '@fusion.dev/helix-core';
+import { type Color, type ColorFormat, type ColorWords, HelixFormElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../button/index.js';
 import '../../button-group/index.js';
@@ -21,6 +21,17 @@ declare const HelixHeadlessColorPicker_base: (new (...args: any[]) => import("@f
  * hue or saturation, so a model read back from the value would turn red into
  * gray after you drag to the bottom of the square and back.
  *
+ * The square is one tab stop. In it, the up and down arrows move brightness
+ * and the left and right arrows move saturation, and PageUp and PageDown move
+ * brightness by ten. The picker sends `input` as the color moves and `change`
+ * when a drag, a key, a typed value or a preset settles it, as
+ * `<input type="color">` does.
+ *
+ * A screen reader hears the color's name, such as "vibrant red", after the two
+ * numbers on the square and after the number on the hue ramp, and each preset
+ * is named by its color. Set `color-words` to speak the names in another
+ * language.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
@@ -51,11 +62,17 @@ declare const HelixHeadlessColorPicker_base: (new (...args: any[]) => import("@f
  * @csspart controls - The row under the square.
  * @csspart eyedropper - The control that samples a color from the screen.
  * @csspart eyedropper-button - The button inside `eyedropper`.
- * @csspart eyedropper-text - The words on that button, trimmed to their capitals and baseline.
+ * @csspart eyedropper-live - The live region of the button inside `eyedropper`, which says its pending label.
+ * @csspart eyedropper-text - The words on the button inside `eyedropper`, trimmed to their capitals and baseline.
+ * @csspart field - One channel's number field with its label, in `channel-fields`.
+ * @csspart field-input - The number input in a channel's field.
+ * @csspart field-label - The name above a channel's number input.
+ * @csspart fields - The row of channel number fields, in `channel-fields`.
  * @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 button inside `format`.
- * @csspart format-text - The words on that button, trimmed to their capitals and baseline.
+ * @csspart format-live - The live region of the button inside `format`, which says its pending label.
+ * @csspart format-text - The words on the button inside `format`, trimmed to their capitals and baseline.
  * @csspart grid - The saturation and brightness square. Draw the mark that shows
  * where the color sits with `::part(grid)::after` in your stylesheet. The
  * square carries the two channels as `--color-picker-saturation` and
@@ -89,6 +106,14 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      * ramps. A consumer who wants autofill can still ask.
      */
     autocomplete: string;
+    /**
+     * The message shown when the value is text that is not a color.
+     */
+    badInputMessage?: string;
+    /**
+     * What the blue channel's field is called, in `channel-fields`.
+     */
+    blueLabel: string;
     /**
      * What the square's vertical ramp is called.
      *
@@ -96,6 +121,32 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      * language hears its own rather than English between its own labels.
      */
     brightnessLabel: string;
+    /**
+     * Whether the picker shows a number field for each channel of the color, as
+     * React Aria's ColorField does with `channel`: red, green and blue for hex
+     * and rgb, hue, saturation and lightness for hsl, and the opacity with
+     * `alpha`.
+     *
+     * For a reader who has the numbers from a brand guide, and for a keyboard,
+     * where typing 128 is quicker than holding an arrow key. The fields follow
+     * the syntax the format toggle sets.
+     */
+    channelFields: boolean;
+    /**
+     * The words a color's name is spoken in, as JSON keyed by their English,
+     * such as `{"red": "rot", "vibrant": "kräftiges"}`.
+     *
+     * **A color is named the way React Aria names one**, as "vibrant red" or
+     * "dark grayish blue", and the keys are the ones `@react-stately/color`
+     * translates, so a table a page already has for it can be handed over whole.
+     * `colorName` and `transparentColorName` are the two sentences that put the
+     * words together. A word left out is spoken in English.
+     *
+     * The name follows the numbers on the square, follows the number on the hue
+     * ramp, and names each preset, so a reader who cannot see the color hears
+     * which one it is.
+     */
+    colorWords: Partial<ColorWords>;
     /**
      * The text the sample shows for a moment after it copies the value.
      */
@@ -120,6 +171,10 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      * What the syntax toggle is called, with `{format}` filled in.
      */
     formatLabel: string;
+    /**
+     * What the green channel's field is called, in `channel-fields`.
+     */
+    greenLabel: string;
     /**
      * What the hue channel is called.
      */
@@ -134,6 +189,11 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      * thing the field cannot draw from outside, the mark on the answer itself.
      */
     invalid: boolean;
+    /**
+     * What the lightness channel's field is called, in `channel-fields` with
+     * hsl.
+     */
+    lightnessLabel: string;
     /**
      * Hides the eyedropper. Without it, the eyedropper appears in browsers that
      * support one.
@@ -194,6 +254,10 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      * letting it open would take a color from the reader and drop it.
      */
     readOnly: boolean;
+    /**
+     * What the red channel's field is called, in `channel-fields`.
+     */
+    redLabel: string;
     /**
      * Requires a color before the form can submit.
      *
@@ -210,13 +274,11 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      * would give one control two of each. What is left is the validity call and
      * the anchor the browser points its bubble at.
      *
-     * **Emptiness is the only fault reported, and bad input deliberately is
-     * not.** The value row is typed into a character at a time and every
-     * keystroke reaches `requestValue`, so `#0`, `#00` and `#00f` would each be a
-     * reported fault on the way to `#00ff00`. Date Picker and Time Picker can
-     * report bad input because their value moves only on a commit. Color Input
-     * reports it for this family instead, once, against the field the reader
-     * typed into.
+     * **Text that is not a color is bad input**, so a form does not submit
+     * `#00` from a half-typed value. The picker draws no message of its own, so
+     * reporting it as each keystroke arrives shows nothing until the form asks;
+     * Color Input shows its own message against the field the reader typed
+     * into.
      */
     required: boolean;
     /**
@@ -268,6 +330,18 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      * which reads back as hue 0 and saturation 0, and the next drag starts gray.
      */
     private owned;
+    /** Dragged and keyed, so a move is announced as `input` alone. See `announcesInput`. */
+    protected readonly announcesInput = true;
+    /** Whether the value has moved since `change` was last sent. */
+    private unsettled;
+    /**
+     * Sends `change` for a value that has settled, where it moved.
+     *
+     * Measured before this: a six-step drag sent six `change` events, so a
+     * consumer saving on `change`, as they would for `<input type="color">`,
+     * saved on every frame.
+     */
+    private settle;
     /** The current color: the last one moved to, the value, or the start color. */
     get color(): Color;
     /**
@@ -365,6 +439,16 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
      * `required`.
      */
     private sync;
+    /**
+     * Moves the square from the keyboard, both axes from either of its inputs.
+     *
+     * The square is two native ranges, and a native range maps every arrow to
+     * its own one axis: on the saturation input, ArrowUp moved the handle
+     * sideways. Here the vertical keys move brightness and the horizontal keys
+     * move saturation, turned on a right-to-left page as the pointer is, which is
+     * what React Aria's ColorArea does.
+     */
+    private readonly handleAreaKeydown;
     /**
      * Reports "required and empty", or clears it.
      *
@@ -377,13 +461,35 @@ export declare class HelixHeadlessColorPicker extends HelixHeadlessColorPicker_b
     protected updated(changed: import('lit').PropertyValues): void;
     /** Moves focus to the square. */
     focus(options?: FocusOptions): void;
+    /** What each channel's field is called, from the words a page gives. */
+    private channelWord;
+    /**
+     * Takes a number typed into a channel's field. A field emptied or holding
+     * something that is not a number moves nothing, so a reader can clear it to
+     * type afresh.
+     */
+    private readonly handleField;
+    /**
+     * Takes a value written out whole, as `move` takes a part of the model: the
+     * square follows it, keeping its hue where the value is a gray with none to
+     * give, and a refusal puts the square back.
+     */
+    private takeWritten;
+    /**
+     * A number field for each channel, behind a seam the styled tier can move.
+     *
+     * `live` on the value, so a number put back inside its range, 300 for a byte,
+     * is redrawn though the value it settles on is the one drawn before.
+     */
+    protected renderFields(color: Color): TemplateResult;
     /**
      * One of the ramps under the square.
      *
      * `protected` rather than `private`, the method being the seam a tier above
-     * renders its own ramp through.
+     * renders its own ramp through. `spoken` is what a screen reader says for the
+     * ramp's value, with `{value}` filled in, and empty says the number alone.
      */
-    protected renderChannel(channel: 'alpha' | 'hue', label: string, max: number, value: number): TemplateResult;
+    protected renderChannel(channel: 'alpha' | 'hue', label: string, max: number, value: number, spoken?: string): TemplateResult;
     /**
      * A slider's own request, kept inside.
      *