@fusion.dev/helix-headless 0.154.0 → 0.156.0

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

@@ -15,7 +15,7 @@ import { areaAt, hueAt } from '../wheel.js';
 import '../../button/index.js';
 import '../../button-group/index.js';
 import '../../slider/index.js';
-const FORMATS = ['hex', 'rgb', 'hsl'];
+const FORMATS = ['hex', 'rgb', 'hsl', 'oklch'];
 const START = { alpha: 100, brightness: 100, hue: 0, saturation: 100 };
 let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPickerFeedback(MixinControllerValue(HelixFormElement)) {
     constructor() {
@@ -26,13 +26,16 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
         this.blueLabel = 'Blue';
         this.brightnessLabel = 'Brightness';
         this.channelFields = false;
+        this.chromaLabel = 'Chroma';
         this.colorWords = {};
         this.copiedLabel = 'Copied';
         this.copyLabel = 'Copy {value}';
         this.eyedropperLabel = 'Sample a color from the screen';
         this.formatLabel = 'Syntax: {format}. Change it.';
         this.greenLabel = 'Green';
+        this.hint = '';
         this.hueLabel = 'Hue';
+        this.label = '';
         this.lightnessLabel = 'Lightness';
         this.noEyedropper = false;
         this.noFormat = false;
@@ -50,6 +53,11 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
         this.valueMissingMessage = 'Choose a color.';
         this.wheel = false;
         this.sampling = false;
+        this.handleNamingSlot = () => {
+            this.requestUpdate();
+        };
+        this.dragging = false;
+        this.picking = false;
         this.owned = false;
         this.announcesInput = true;
         this.unsettled = false;
@@ -132,6 +140,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
                 return;
             }
             this.dispatchEvent(new HelixSampleStartEvent());
+            this.picking = true;
             try {
                 const { sRGBHex } = await new Dropper().open();
                 const parsed = parseColor(sRGBHex);
@@ -142,6 +151,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
             }
             catch {
             }
+            this.picking = false;
             this.dispatchEvent(new HelixSampleEndEvent());
         };
         this.handleGridPointer = (event) => {
@@ -150,12 +160,14 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
             }
             const grid = event.currentTarget;
             if (event.type === 'pointerup' || event.type === 'pointercancel') {
+                this.dragging = false;
                 this.settle();
                 return;
             }
             if (event.type === 'pointerdown') {
+                this.dragging = true;
                 capturePointer(grid, event.pointerId);
-                this.partNamed('grid-saturation')?.focus();
+                this.partNamed('grid-saturation')?.focus({ preventScroll: true });
             }
             else if (!grid.hasPointerCapture(event.pointerId)) {
                 return;
@@ -181,7 +193,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
             }
             if (event.type === 'pointerdown') {
                 capturePointer(wheel, event.pointerId);
-                this.partNamed('wheel-hue')?.focus();
+                this.partNamed('wheel-hue')?.focus({ preventScroll: true });
             }
             else if (!wheel.hasPointerCapture(event.pointerId)) {
                 return;
@@ -232,6 +244,23 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
         };
     }
     static { this.words = 'helix-color-picker'; }
+    slottedIn(name) {
+        return this.knownChildren.filter((child) => child.slot === name);
+    }
+    get named() {
+        return (this.label ||
+            this.slottedIn('label')
+                .map((child) => child.textContent ?? '')
+                .join(' ')
+                .trim());
+    }
+    get hinted() {
+        return this.hint !== '' || this.slottedIn('hint').length > 0;
+    }
+    get describedBy() {
+        const ids = [this.hinted ? 'hint' : '', this.feedback === '' ? '' : 'feedback'].filter(Boolean);
+        return ids.length > 0 ? ids.join(' ') : nothing;
+    }
     settle() {
         if (this.unsettled) {
             this.unsettled = false;
@@ -299,6 +328,8 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
         return {
             alpha: this.opacityLabel,
             blue: this.blueLabel,
+            brightness: this.brightnessLabel,
+            chroma: this.chromaLabel,
             green: this.greenLabel,
             hue: this.hueLabel,
             lightness: this.lightnessLabel,
@@ -327,10 +358,10 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
           <input
             part="field-input"
             type="number"
-            inputmode="numeric"
+            inputmode=${field.step < 1 ? 'decimal' : 'numeric'}
             min=${field.min}
             max=${field.max}
-            step="1"
+            step=${field.step}
             .value=${live(String(field.value))}
             ?disabled=${this.isDisabled}
             ?readonly=${this.readOnly}
@@ -350,7 +381,8 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
       exportparts="control: channel-control, feedback: channel-feedback, field: channel-field,
         hint: channel-hint, label: channel-label, marker: channel-marker,
         marker-label: channel-marker-label, markers: channel-markers, output: channel-output,
-        tooltip: channel-tooltip, tooltips: channel-tooltips"
+        thumb: channel-thumb, thumbs: channel-thumbs, tooltip: channel-tooltip,
+        tooltips: channel-tooltips"
       data-channel=${channel}
       aria-invalid=${this.marked ? 'true' : nothing}
       label=${label}
@@ -391,10 +423,18 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
     willUpdate(changed) {
         super.willUpdate(changed);
         const outside = [...(this.internals.labels ?? [])];
-        hostAria(this.internals, { labelledBy: outside, role: outside.length > 0 ? 'group' : '' });
+        const named = this.named;
+        hostAria(this.internals, {
+            label: outside.length > 0 ? '' : named,
+            labelledBy: outside,
+            role: outside.length > 0 || named !== '' ? 'group' : '',
+        });
         if (!this.hydrating) {
             this.sampling = 'EyeDropper' in globalThis;
         }
+        this.toggleState('copied', this.copier.copied);
+        this.toggleState('dragging', this.dragging);
+        this.toggleState('sampling', this.picking);
     }
     renderTools() {
         return html `<${this.tag('button-group')} part="actions" label=${this.toolsLabel}>
@@ -471,7 +511,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
         const reversed = square('brightness');
         const hue = hueName({ alpha: 100, brightness: 100, hue: color.hue, saturation: 100 }, this.colorWords, locale);
         const hueSaid = (value) => new Intl.ListFormat(locale, { style: 'short', type: 'unit' }).format([String(value), hue]);
-        const owner = this.getAttribute('aria-label')?.trim();
+        const owner = this.getAttribute('aria-label')?.trim() || this.named;
         const axisName = (channel) => (owner ? `${owner}, ${channel}` : channel);
         const area = html `<div
         part="grid"
@@ -488,7 +528,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
           min="0"
           max="100"
           aria-label=${axisName(this.saturationLabel)}
-          aria-describedby=${this.feedback === '' ? nothing : 'feedback'}
+          aria-describedby=${this.describedBy}
           aria-valuetext=${both}
           aria-invalid=${this.marked ? 'true' : nothing}
           .value=${String(color.saturation)}
@@ -505,7 +545,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
           tabindex="-1"
           style="writing-mode: vertical-lr; direction: rtl"
           aria-label=${axisName(this.brightnessLabel)}
-          aria-describedby=${this.feedback === '' ? nothing : 'feedback'}
+          aria-describedby=${this.describedBy}
           aria-valuetext=${reversed}
           aria-invalid=${this.marked ? 'true' : nothing}
           .value=${String(color.brightness)}
@@ -514,7 +554,10 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
           @change=${() => this.settle()}
         />
       </div>`;
-        return html `${this.wheel
+        return html `<div part="label" ?hidden=${this.named === ''}>
+        <slot name="label" @slotchange=${this.handleNamingSlot}>${this.label}</slot>
+      </div>
+      ${this.wheel
             ? html `<div
             part="wheel"
             style="--color-picker-hue: ${color.hue}"
@@ -531,7 +574,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
               max="360"
               dir="ltr"
               aria-label=${axisName(this.hueLabel)}
-              aria-describedby=${this.feedback === '' ? nothing : 'feedback'}
+              aria-describedby=${this.describedBy}
               aria-valuetext=${hueSaid(color.hue)}
               aria-invalid=${this.marked ? 'true' : nothing}
               .value=${String(color.hue)}
@@ -574,7 +617,7 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
                 part="value"
                 type="text"
                 aria-label=${this.valueLabel}
-                aria-describedby=${this.feedback === '' ? nothing : 'feedback'}
+                aria-describedby=${this.describedBy}
                 aria-invalid=${this.marked ? 'true' : nothing}
                 autocomplete=${this.autocomplete || nothing}
                 spellcheck="false"
@@ -591,6 +634,9 @@ let HelixHeadlessColorPicker = class HelixHeadlessColorPicker extends MixinPicke
       </div>
 
       ${this.presets.length === 0 ? nothing : this.renderSwatches(painted)}
+      <div part="hint" id="hint" ?hidden=${!this.hinted}>
+        <slot name="hint" @slotchange=${this.handleNamingSlot}>${this.hint}</slot>
+      </div>
       ${this.renderPickerFeedback()}`;
     }
 };
@@ -615,6 +661,10 @@ __decorate([
 __decorate([
     property({ attribute: 'channel-fields', type: Boolean })
 ], HelixHeadlessColorPicker.prototype, "channelFields", void 0);
+__decorate([
+    words,
+    property({ attribute: 'chroma-label' })
+], HelixHeadlessColorPicker.prototype, "chromaLabel", void 0);
 __decorate([
     property({ attribute: 'color-words', converter: wordsConverter })
 ], HelixHeadlessColorPicker.prototype, "colorWords", void 0);
@@ -641,10 +691,16 @@ __decorate([
     words,
     property({ attribute: 'green-label' })
 ], HelixHeadlessColorPicker.prototype, "greenLabel", void 0);
+__decorate([
+    property()
+], HelixHeadlessColorPicker.prototype, "hint", void 0);
 __decorate([
     words,
     property({ attribute: 'hue-label' })
 ], HelixHeadlessColorPicker.prototype, "hueLabel", void 0);
+__decorate([
+    property()
+], HelixHeadlessColorPicker.prototype, "label", void 0);
 __decorate([
     words,
     property({ attribute: 'lightness-label' })
@@ -711,6 +767,12 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessColorPicker.prototype, "swatchAt", void 0);
+__decorate([
+    state()
+], HelixHeadlessColorPicker.prototype, "dragging", void 0);
+__decorate([
+    state()
+], HelixHeadlessColorPicker.prototype, "picking", void 0);
 HelixHeadlessColorPicker = __decorate([
     customElement('helix-headless-color-picker')
 ], HelixHeadlessColorPicker);

package/dist/combobox/root/combobox-root.d.ts

@@ -198,6 +198,16 @@ export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_base {
      * every keystroke. See Listbox's `filter-delay`.
      */
     filterDelay: number;
+    /**
+     * What the form receives for each chosen option: `key`, its `value`, or
+     * `text`, its words, as React Aria's ComboBox `formValue` offers.
+     *
+     * `text` is for a server that wants what the reader saw, such as a city's
+     * name. A value no option carries, typed with `allows-custom-value` or made
+     * with `creatable`, is sent as it is either way. Absent is `key`, and the
+     * host carries no attribute for it.
+     */
+    formValue?: 'key' | 'text';
     /**
      * The list's name, read by screen readers. The list has no visible name.
      */

package/dist/combobox/root/combobox-root.js

@@ -453,11 +453,23 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
         return this.partNamed('control') ?? super.focusTarget;
     }
     sync() {
-        if (this.multiple) {
-            reportValues(this.internals, this.name, this.value === '' ? [] : this.value.split(','));
+        const values = this.multiple ? this.values : this.value === '' ? [] : [this.value];
+        const words = this.formValue === 'text'
+            ? new Map(optionsAmong(this.knownChildren).map((option) => [option.value, option.text]))
+            : undefined;
+        const answers = words ? values.map((value) => words.get(value) ?? value) : values;
+        if (!this.multiple) {
+            this.internals.setFormValue(answers[0] ?? null, this.value);
+        }
+        else if (words && this.name !== '' && answers.length > 0) {
+            const data = new FormData();
+            for (const answer of answers) {
+                data.append(this.name, answer);
+            }
+            this.internals.setFormValue(data, this.value);
         }
         else {
-            this.internals.setFormValue(this.value === '' ? null : this.value);
+            reportValues(this.internals, this.name, answers);
         }
         this.reportRequired(this.value === '', this.valueMissingMessage, 'control');
     }
@@ -677,6 +689,9 @@ __decorate([
 __decorate([
     property({ attribute: 'filter-delay', type: Number })
 ], HelixHeadlessCombobox.prototype, "filterDelay", void 0);
+__decorate([
+    property({ attribute: 'form-value' })
+], HelixHeadlessCombobox.prototype, "formValue", void 0);
 __decorate([
     words,
     property({ attribute: 'list-label' })

package/dist/command/root/command-root.d.ts

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { type DataOptionItem, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../dialog/index.js';
 import '../../listbox/index.js';
@@ -22,10 +22,51 @@ declare const HelixHeadlessCommand_base: (new (...args: any[]) => import("@fusio
  * palette is open. `mod` means Command on a Mac and Control elsewhere, so you
  * write one binding.
  *
+ * With `inline`, the palette is drawn in the page with no dialog, as a search
+ * over a list that is always shown.
+ *
+ * **Pages.** A command can open a page of commands of its own, as a palette
+ * offers "Change theme" and then the themes. Give the option `opens` with a
+ * name, and slot the page's commands as `page:` and that name:
+ *
+ * ```html
+ * <helix-command>
+ *   <helix-option value="theme" opens="theme">Change theme</helix-option>
+ *   <helix-option value="dark" slot="page:theme">Dark</helix-option>
+ *   <helix-option value="light" slot="page:theme">Light</helix-option>
+ * </helix-command>
+ * ```
+ *
+ * Choosing the opener says `helix-select` with its value, and canceling it
+ * keeps the page that is shown. The list then shows the page, named by the
+ * opener's words, and Backspace in an empty filter goes back. `page` says
+ * which page is shown.
+ *
  * The filter is cleared when the palette closes, so each opening starts from
  * the full list. Combobox and Select do the same. As typing narrows the list, a
  * screen reader hears how many commands are left, such as "3 commands".
  *
+ * **Keyboard.** Focus goes to the filter field as the palette opens, and the
+ * highlight moves through the commands while you type.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | `hotkey`, Command or Control with K by default | Opens the palette from anywhere on the page, or closes it. With `inline`, puts focus in its filter field. |
+ * | Down, Up | Moves the highlight to the next or the previous command, round from the last to the first. |
+ * | Page Down, Page Up | Moves the highlight by as many commands as the list shows at once. |
+ * | Home, End, Left, Right | Move the caret in the filter field. |
+ * | Enter | Runs the highlighted command, or follows it where it is a link, and closes the palette. On a command with `opens`, shows its page. |
+ * | Command or Control with Enter | Takes the highlighted command's `alternate` destination, where it has one. |
+ * | Backspace | In an empty filter on a page, goes back to the page before. |
+ * | Escape | Clears the filter. With the filter empty, closes the palette and puts focus back where it was. |
+ * | Tab | Stays in the palette, which is modal. With `inline`, moves on through the page. |
+ *
+ * **ARIA.** The palette is a modal `dialog` named by `label`, or with
+ * `inline` no dialog at all. Inside it the filter field is a `combobox` with
+ * `aria-activedescendant` on the highlighted command, and the commands are a
+ * `listbox` of `option`s. How many commands typing left, the empty text and
+ * the loading text are said in a polite live region.
+ *
  * @since 0.1.0
  * @status stable
  * @category navigation
@@ -35,7 +76,9 @@ declare const HelixHeadlessCommand_base: (new (...args: any[]) => import("@fusio
  * @slot - The commands, and any groups of them.
  * @slot empty - What the palette shows when typing matches no commands, for content richer than `empty-text`.
  * @slot error - What the palette shows while `load-error` is set, for content richer than its text.
+ * @slot filter-icon - Replaces the magnifying glass in the filter field.
  * @slot footer - Content under the list, such as the keys that work in the palette.
+ * @slot header - Content above the filter field, such as a title or the scope being searched. A heading here does not rename the palette, which `label` names.
  * @slot loading - What the palette shows while the commands load, for content richer than `loading-text`.
  * @slot no-results - What the palette shows when typing matches no commands, for content richer than `no-results-text`.
  *
@@ -67,6 +110,10 @@ declare const HelixHeadlessCommand_base: (new (...args: any[]) => import("@fusio
  * @csspart listbox-search - The region that holds the filter field.
  * @csspart listbox-search-field - The filter field.
  *
+ * @cssstate empty - The list shows no commands: there are none, or typing hid every one.
+ * @cssstate error - While `load-error` is set.
+ * @cssstate loading - While `loading` is set.
+ * @cssstate no-results - Typing hid every one of the commands, where there are some.
  * @cssstate open - While the palette is open.
  */
 export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
@@ -95,6 +142,26 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * with: one key, said once.
      */
     hotkey: string;
+    /**
+     * Draws the palette in the page, where it stands, with no dialog: a search
+     * over a list of commands, as React Aria's Autocomplete is drawn.
+     *
+     * The list is always shown, and `hotkey` puts focus in its filter field.
+     * Choosing a command says `helix-select` and leaves the list where it is,
+     * and `open`, `toggle` and the dialog's parts do nothing.
+     */
+    inline: boolean;
+    /**
+     * The commands as data, for a palette too long to draw whole: each a value,
+     * which is also its words, or a record with a `value`, a `label` and
+     * `disabled`. Handed to the list, which draws only the commands in sight and
+     * reads no children while it is set. See Listbox's `items`.
+     *
+     * Choosing one says `helix-select` with its value, as a child option does.
+     * A command that is a link, or that has an `alternate`, is an option you
+     * write as a child.
+     */
+    items: readonly DataOptionItem[] | undefined;
     /**
      * Accessible name for the overlay, which has no visible heading.
      */
@@ -122,6 +189,19 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * some. Absent, `empty-text` shows. See Listbox's `no-results-text`.
      */
     noResultsText?: string;
+    /**
+     * The page of commands shown, by name: empty for the commands you write
+     * with no `slot`, or a name for the commands slotted as `page:` and the
+     * name, such as `slot="page:theme"`.
+     *
+     * An option with `opens` set to a name goes to that page when it is chosen,
+     * in place of running, and Backspace in an empty filter goes back to the
+     * page before. Closing the palette goes back to the first page. Set it to
+     * open the palette on a page of your choosing.
+     */
+    page: string;
+    /** The pages gone through to reach this one, which Backspace walks back. */
+    private trail;
     /**
      * The text shown in the filter field before anything is typed.
      */
@@ -169,6 +249,8 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * palette the reader never sees.
      */
     private readonly handleHotkey;
+    /** The list's filter field, where a reader types. */
+    private get searchField();
     /**
      * Takes what the list announced and says it under this element's name.
      *
@@ -183,6 +265,18 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * could not be run again: Enter did nothing and the palette stayed open.
      */
     private readonly handleChange;
+    /**
+     * Shows a page of commands, with the trail that leads back from it. The
+     * filter starts empty, as it does on opening, and the field keeps focus.
+     */
+    private goTo;
+    /** Backspace in an empty filter, on a page, goes back to the page before. */
+    private readonly handleBack;
+    /**
+     * The list's name: the palette's, or on a page, the words of the command
+     * that opens it.
+     */
+    private get listName();
     /**
      * The row under the keyboard, read from the `active` property the listbox
      * writes on each option.
@@ -217,6 +311,20 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
+    /**
+     * The list's loading, error and empty states on the host too, so a page
+     * styles the whole palette from them, as Combobox does. Read once the list
+     * has drawn its filter, since `hidden` is what the filter writes onto a
+     * command.
+     */
+    private markStatus;
+    /**
+     * After the list has filtered on what was typed. The event comes before the
+     * filter is applied, so the list's update is waited for a turn later.
+     */
+    private readonly handleFilter;
+    /** Whether a child fills the named slot, so it is handed on to the dialog or the list. */
+    private fills;
     protected updated(changed: PropertyValues): void;
     /**
      * The surface the palette opens in, behind a seam the styled tier can move.
@@ -229,6 +337,13 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * from the same template.
      */
     protected renderDialog(): TemplateResult;
+    /**
+     * The filterable list of commands, which the dialog holds, or the page with
+     * `inline`, behind a seam the styled tier can move.
+     */
+    protected renderListbox(): TemplateResult;
+    /** The row under the list, in the dialog's footer or, `inline`, under the list itself. */
+    private renderFooter;
     protected render(): TemplateResult;
 }
 declare global {