@fusion.dev/helix-headless 0.147.0 → 0.149.0

package/dist/listbox/reorder/listbox-reorder.js

@@ -0,0 +1,151 @@
+import { ReorderController } from '@fusion.dev/helix-core';
+const WORDS = {
+    canceledLabel: ['canceled-label', 'Canceled'],
+    droppedLabel: ['dropped-label', 'Dropped'],
+    movedLabel: ['moved-label', '{name} moved to position {position} of {count}'],
+    pickedUpLabel: ['picked-up-label', 'Picked up {name}'],
+};
+const MOVES = ['dragging', 'drop-after', 'drop-before'];
+const keyOfItem = (item) => String(typeof item === 'object' ? item.value : item);
+export class ListboxReorderController {
+    constructor(host, sheet, listSheet) {
+        this.marked = new Set();
+        this.host = host;
+        this.sheet = sheet;
+        this.listSheet = listSheet;
+        host.addController(this);
+        this.reorder = new ReorderController(host, {
+            axis: 'block',
+            box: (key) => this.optionFor(key)?.getBoundingClientRect(),
+            current: () => {
+                const active = this.drawn.find((option) => option.active);
+                return active && !active.disabled ? active.value : undefined;
+            },
+            enabled: () => host.reorderable && host.filter === '' && host.layout !== 'grid' && !host.isDisabled,
+            grip: (event) => {
+                const option = this.optionOf(event);
+                return option && !option.disabled ? { element: option, key: option.value } : undefined;
+            },
+            holds: false,
+            keys: (key) => this.keysAround(key),
+            name: (key) => this.optionFor(key)?.text || key,
+            preview: (key) => this.optionFor(key),
+            scroller: () => host.renderRoot?.querySelector('[part="items"]') ?? null,
+        });
+    }
+    hostUpdated() {
+        queueMicrotask(() => this.mark());
+    }
+    drawPreview(on) {
+        const root = this.host.renderRoot;
+        const drawn = root?.querySelector('[part="drag-preview"]');
+        if (on && root && !drawn) {
+            const preview = document.createElement('div');
+            for (const [name, value] of [
+                ['part', 'drag-preview'],
+                ['popover', 'manual'],
+                ['aria-hidden', 'true'],
+                ['inert', ''],
+            ]) {
+                preview.setAttribute(name, value);
+            }
+            root.append(preview);
+        }
+        else if (!on) {
+            drawn?.remove();
+        }
+    }
+    get drawn() {
+        const host = this.host;
+        return (host.items
+            ? [...(host.renderRoot?.querySelector('[data-rows]')?.children ?? [])]
+            : host.options);
+    }
+    optionOf(event) {
+        const drawn = this.drawn;
+        return event.composedPath().find((node) => drawn.includes(node));
+    }
+    optionFor(key) {
+        return this.drawn.find((option) => option.value === key);
+    }
+    keysAround(key) {
+        const { items, options } = this.host;
+        if (items) {
+            return items.map(keyOfItem);
+        }
+        const parent = options.find((option) => option.value === key)?.parentElement;
+        return options.filter((option) => option.parentElement === parent).map((one) => one.value);
+    }
+    mark() {
+        const on = this.host.reorderable;
+        adopt(this.host, this.listSheet, on);
+        this.drawPreview(on);
+        const drawn = this.drawn;
+        const marked = new Set();
+        for (const option of drawn) {
+            const move = on ? this.reorder.moveOf(option.value) : undefined;
+            if (move || this.marked.has(option)) {
+                for (const state of MOVES) {
+                    option.toggleState(state, state === move);
+                }
+            }
+            if (move) {
+                marked.add(option);
+            }
+            adopt(option, this.sheet, on);
+        }
+        for (const option of this.marked) {
+            if (!drawn.includes(option)) {
+                for (const state of MOVES) {
+                    option.toggleState(state, false);
+                }
+            }
+        }
+        this.marked = marked;
+    }
+}
+const adopt = (element, given, on) => {
+    const root = element.shadowRoot;
+    const sheet = given?.styleSheet;
+    if (!root || !sheet || root.adoptedStyleSheets.includes(sheet) === on) {
+        return;
+    }
+    root.adoptedStyleSheets = on
+        ? [...root.adoptedStyleSheets, sheet]
+        : root.adoptedStyleSheets.filter((one) => one !== sheet);
+};
+const given = new WeakMap();
+const attach = (list, sheet, listSheet) => {
+    const controller = given.get(list) ?? new ListboxReorderController(list);
+    given.set(list, controller);
+    controller.sheet ??= sheet;
+    controller.listSheet ??= listSheet;
+};
+const onPage = (of, root = document) => [...root.querySelectorAll('*')].flatMap((node) => [
+    ...(node instanceof of ? [node] : []),
+    ...(node.shadowRoot ? onPage(of, node.shadowRoot) : []),
+]);
+export const reorderListbox = (element, sheet, listSheet) => {
+    element.addInitializer((host) => attach(host, sheet, listSheet));
+    if (typeof document !== 'undefined') {
+        for (const list of onPage(element)) {
+            attach(list, sheet, listSheet);
+            list.requestUpdate();
+        }
+    }
+    const proto = element.prototype;
+    for (const [name, [attribute, fallback]] of Object.entries(WORDS)) {
+        if (name in proto) {
+            continue;
+        }
+        Object.defineProperty(proto, name, {
+            configurable: true,
+            get() {
+                return this.getAttribute(attribute) ?? fallback;
+            },
+            set(next) {
+                this.setAttribute(attribute, next);
+            },
+        });
+    }
+};

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

@@ -1,4 +1,4 @@
-import { AriaForwardController, DisabledCascadeController, HelixFormElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, type DataOptionItem, DisabledCascadeController, HelixFormElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import { HelixHeadlessOption } from '../../option/root/option-root.js';
 declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
@@ -20,16 +20,32 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
  * active option is where the keyboard is: the arrow keys move it, and
  * `aria-activedescendant` points to it while focus stays on the list.
  *
- * The arrow keys, Home, End, PageUp and PageDown move the highlight, and typed
- * letters move it to the next option whose words start with them. In a
- * single-choice list the highlight is the choice unless `manual` is set; then
- * Enter, Space or a click chooses. With `multiple`, Space toggles the
- * highlighted option, Shift with an arrow adds the option it moves to, Shift
- * with Home or End adds every option from the highlight to that end, and
- * Control+A or Command+A chooses every option, or none where all are chosen.
- * In a filter field, Space, Home, End and letters edit the text, and with
- * `multiple`, Control with Shift and Home or End adds every option from the
- * highlight to that end.
+ * **Keyboard.** The list is one tab stop, or its filter field is where there
+ * is one. In a single-choice list the highlight is the choice unless `manual`
+ * is set; then Enter, Space or a click chooses.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Down, Up | Moves the highlight to the next or the previous option, round from the last to the first. With `layout="grid"`, to the option below or above, stopping at the edge. |
+ * | Right, Left | With `layout="grid"`, moves to the next or the previous option, mirrored right to left. In a filter field, moves the caret. |
+ * | Home, End | Moves to the first or the last option. In a filter field, moves the caret. |
+ * | Page Down, Page Up | Moves by as many options as the list shows at once. |
+ * | A letter or a word | Moves to the next option whose words start with what you typed. In a filter field, types it. |
+ * | Enter | Chooses the highlighted option, or follows it where it is a link. |
+ * | Space | Chooses the highlighted option, or with `multiple` toggles it. In a filter field, types a space. |
+ * | Shift with Down or Up | With `multiple`, adds the option the highlight moves to. In a filter field, moves the highlight and leaves the value. |
+ * | Shift with Space | With `multiple`, adds every option from the one last chosen to the highlighted one. In a filter field, types a space. |
+ * | Shift with Home or End | With `multiple`, adds every option from the highlight to that end. In a filter field, hold Control as well. |
+ * | Control or Command with A | With `multiple`, chooses every option, or none where all are chosen. In a filter field, selects the text. |
+ * | Escape | In a filter field, clears the filter. |
+ * | Alt with Up or Down | In a `reorderable` list, moves the highlighted option a place. Alt with Home or End moves it to either end. |
+ *
+ * **ARIA.** The `items` part is the `listbox`, named by the label and
+ * described by the hint and the message, with `aria-multiselectable` under
+ * `multiple`, `aria-required`, `aria-invalid`, and `aria-busy` while loading.
+ * Each option is an `option` with `aria-selected`. The list, or its filter
+ * field, points `aria-activedescendant` at the highlighted option; the field
+ * is `aria-autocomplete="list"` and controls the list.
  *
  * An option with `href` is a link: Enter or a press follows it and selects
  * nothing, and moving onto it with the arrows does not follow it.
@@ -38,6 +54,26 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
  * left, such as "3 results", from `result-label` and `results-label`. A filter
  * that leaves none says `empty-text`.
  *
+ * **Moving options** is a separate import, `@fusion.dev/helix/listbox/reorder`,
+ * so a list that never moves options carries none of its code. With it
+ * imported, `reorderable` lets a reader move options:
+ *
+ * - Alt with Up or Down moves the highlighted option a place, and Alt with
+ *   Home or End moves it to either end, as the APG's rearrangeable listbox
+ *   does. The highlight stays on it.
+ * - A pointer drags an option, with a drop indicator, and the list scrolls near
+ *   an edge. A press that does not travel still chooses the option.
+ * - A drop sends `helix-before-reorder`, which you can refuse, and then
+ *   `helix-reorder`, whose `keys` hold every value in the new order. **You
+ *   move the options**, or set `items` in the new order: the list moves no
+ *   element of yours.
+ * - The list says each move in its `live` region. The words are the
+ *   `moved-label`, `canceled-label`, `dropped-label`, and `picked-up-label`
+ *   attributes, which the import reads.
+ * - An option in a group moves within its group. Options do not move while a
+ *   filter narrows the list, under `layout="grid"`, or while the list is
+ *   disabled.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
@@ -56,8 +92,10 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
  *
  * @event {Event} change - Fired after the value changes.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired when the value is about to change, and cancelable.
+ * @event {HelixBeforeReorderEvent} helix-before-reorder - Fired when an option is dropped at a new place, in a `reorderable` list with `@fusion.dev/helix/listbox/reorder` imported, with every value in the new order. Cancelable: cancel it to keep the option where it is.
  * @event {HelixFilterEvent} helix-filter - Fired before the list is filtered, and cancelable.
  * @event {HelixLoadMoreEvent} helix-load-more - Fired once the list is scrolled within a screen of its end, once for each number of options, and not while `loading` is set. Add the next page of options and set `loading` while you fetch it.
+ * @event {HelixReorderEvent} helix-reorder - Fired after `helix-before-reorder` when nobody canceled it. Move your options, or your `items`, to the order in `keys`. Cancelable: cancel it to say the move did not happen.
  * @event {Event} input - Fired after the value changes.
  *
  * @csspart empty - The text shown when the list has no options to show, or the filter hides every one. `:state(no-results)` is set for the second.
@@ -68,7 +106,7 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
  * @csspart hint - Help under the list.
  * @csspart items - The list of options.
  * @csspart label - The label above the list.
- * @csspart live - A copy of the empty and loading text, and how many options a filter left, in a region that screen readers announce when it changes. Visually hidden in the styled tier.
+ * @csspart live - A copy of the empty and loading text, how many options a filter left, and each move in a `reorderable` list, in a region that screen readers announce when it changes. Visually hidden in the styled tier.
  * @csspart loading - The text shown while the options load.
  * @csspart search - The region that holds the filter field.
  * @csspart search-field - The filter field.
@@ -80,14 +118,23 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
  * @cssstate no-results - A filter hid every option of a list that has some.
  */
 export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-listbox': { filterLabel: 'Filtern' } })`.
+     */
+    static words: string;
     protected readonly aria: AriaForwardController;
     /**
-     * What the browser may autofill in the text field, as a platform token.
+     * What a browser's autofill may choose, as a platform token such as
+     * `country` or `cc-exp-month`, as a native `<select>` takes it.
+     *
+     * Set, the list draws a hidden native `<select>` with the same options for
+     * the browser to fill, as React Aria's `HiddenSelect` does, and a fill
+     * chooses the option. `off`, the default, draws none.
      *
-     * **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.
+     * **The filter field is never filled.** It narrows the list rather than
+     * collecting a value, so a browser offering it a saved address competes
+     * with the reader for the same keystrokes: it is always `off`.
      */
     autocomplete: string;
     /**
@@ -138,14 +185,49 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * Placeholder text for the filter field.
      */
     filterLabel: string;
+    /**
+     * The options as data, for a list too long to draw whole: each a value,
+     * which is also its words, or a record with a `value`, a `label` and
+     * `disabled`. Set, the list draws only the options in sight, and the ones
+     * you write as children are not read.
+     *
+     * **Every option is still reachable.** The keyboard, the typeahead, the
+     * filter and the value work over the whole set, and the option the keyboard
+     * is on is drawn wherever it is, so a screen reader is told about it. Each
+     * drawn option says its place in the set (`aria-posinset`, `aria-setsize`).
+     * React Aria virtualizes a `ListBox` with its `Virtualizer`; this is core's
+     * `VirtualizeController`.
+     *
+     * **The list needs a height to scroll in**: the styled tier's
+     * `--listbox-max-block-size`, or a `max-block-size` on `::part(items)` in the
+     * headless tier. Import the Option family as well, whose elements are drawn.
+     * A server sends the list empty, and the options are drawn once it hydrates.
+     */
+    items: readonly DataOptionItem[] | undefined;
+    /**
+     * How the options are laid out, which the arrow keys follow: `stack`, one
+     * under another, or `grid`, in rows and columns, as React Aria's `ListBox`
+     * lays out cards or photos. With `grid`, Up and Down move within a column,
+     * and Left and Right along the list, mirrored right to left.
+     *
+     * The columns are the stylesheet's: the styled tier draws them at
+     * `--listbox-column-min-inline-size` or wider, and a headless list lays out
+     * `::part(items)` as it likes, since the keys read where each option is
+     * drawn. A list of `items` stays a stack. Left out, the list is a stack,
+     * and the host carries no attribute for it.
+     */
+    layout?: 'grid' | 'stack';
+    /** Draws `items` a window at a time. See core's `OptionWindowController`. */
+    private readonly data;
     /**
      * What the list says when its options could not be loaded, such as after a
-     * request to a server fails. Empty is no error.
+     * request to a server fails. Empty, null or no attribute is no error, so
+     * removing the attribute clears it.
      *
      * Set, it shows under any options there are, in place of `empty-text` and
      * `loading-text`, and a screen reader hears it. Clear it when you ask again.
      */
-    loadError: string;
+    loadError: string | null;
     /**
      * Stops the arrow keys from choosing each option they move to. Enter, Space
      * or a click chooses the highlighted option.
@@ -157,6 +239,9 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
     manual: boolean;
     /**
      * Whether more than one option can be chosen.
+     *
+     * A press then toggles the option pressed, and Shift with a press adds every
+     * option from the one last chosen to it, as React Aria's list does.
      */
     multiple: boolean;
     /**
@@ -167,19 +252,40 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      */
     noResultsText?: string;
     /**
-     * What a screen reader hears when a filter leaves one option. `{count}` is
-     * the count.
+     * Lets a reader move options, once `@fusion.dev/helix/listbox/reorder` (or
+     * `@fusion.dev/helix-headless/listbox/reorder`) is imported: Alt with an
+     * arrow moves the highlighted option, and a pointer drags one. The list
+     * moves no option itself: you move your options, or your `items`, on
+     * `helix-reorder`. Without that import it does nothing, so a list that never
+     * moves options carries none of the code.
      */
-    resultLabel: string;
+    reorderable: boolean;
     /**
-     * What a screen reader hears when a filter leaves any other number of
-     * options. `{count}` is the count.
+     * What a screen reader hears when a filter leaves one option, where
+     * `results-label` should not say it. `{count}` is the count.
      *
-     * **Two sentences, chosen by `Intl.PluralRules`**, which is Data Table's
-     * pair: a language with more forms than two picks the one for its `one` and
-     * writes the rest here.
+     * @deprecated Write every form in `results-label`, as `{count, plural, one
+     * {# result} other {# results}}`. Removed in the next major version.
+     */
+    resultLabel?: string;
+    /**
+     * What a screen reader hears when a filter narrows the list. `{count}` is
+     * how many options are left, written in the locale, and each language
+     * writes the forms it has: `{count, plural, one {# wynik} few {# wyniki}
+     * many {# wyników} other {# wyniku}}`.
      */
     resultsLabel: string;
+    /**
+     * What VoiceOver hears as the highlight reaches a chosen option from the
+     * filter field, on Apple devices. `{name}` is the option's words.
+     */
+    selectedLabel: string;
+    /**
+     * The message reported when the field is required and no option is chosen.
+     * Absent, or empty, is this sentence, or the words registered for the page's
+     * locale.
+     */
+    valueMissingMessage: string;
     /**
      * Which option the keyboard is on, which is not what is chosen.
      */
@@ -189,6 +295,16 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * it back on the first match.
      */
     private parked;
+    /**
+     * The option last chosen, which Shift with Space or with a press extends
+     * from.
+     */
+    private anchor;
+    /**
+     * Whether Shift was held for the press being handled, read off the click on
+     * its way down to the option, which is where React Aria extends a range.
+     */
+    private shifted;
     /** The letters typed at the list, which move the highlight to a match. */
     private readonly typeahead;
     /**
@@ -212,6 +328,9 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * markup, so the hiding is done to them in `willUpdate` and the render reads
      * the answer it left here. Counted during render instead, a filter matching
      * nothing left an empty box with no message in it.
+     *
+     * Plain rather than reactive: `place` writes it inside an update, which
+     * draws it, and a slot change asks for that update.
      */
     private hasMatches;
     /**
@@ -221,7 +340,7 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * count: without this the list shipped "Nothing to show" over markup that was
      * about to have options in it, which is the one thing an empty state must
      * never do. `place` does not run on the server, so this is false exactly
-     * when the answer is unknown.
+     * when the answer is unknown. Plain, for the reason `hasMatches` is.
      */
     private counted;
     protected readonly cascade: DisabledCascadeController;
@@ -260,6 +379,17 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * which the region says in place of this.
      */
     private tell;
+    /**
+     * Says the option the arrows reached from the filter field, on Apple devices.
+     *
+     * **VoiceOver does not read the option `aria-activedescendant` points to**
+     * while focus is in a text field, so a filterable list moved its highlight
+     * in silence there. React Aria's combobox says the option on Apple devices,
+     * with "selected" where it is chosen; the field here is the same pattern.
+     * Only while the field has focus, so a highlight placed as the list opens
+     * or seeded from the value says nothing until the reader moves it.
+     */
+    private tellActive;
     /**
      * @internal Moves the highlight to the option whose words start with the
      * letters typed, and returns its value, or nothing where none matches.
@@ -269,6 +399,13 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * `<select>` does.
      */
     typeaheadTo(key: string): string | undefined;
+    /**
+     * @internal Called when the option already chosen is chosen again, which
+     * changes nothing here and answers the question for the control that opened
+     * the list. Select and Combobox close their panel on it, as a native
+     * `<select>` closes when its own answer is pressed.
+     */
+    chosenAgain: (() => void) | undefined;
     /** @internal Whether letters typed in the last moment are still one search. */
     get typing(): boolean;
     /**
@@ -298,8 +435,16 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * component comes up empty.
      */
     private among;
-    /** The groups, found the same way and for the same reason. */
+    /**
+     * The groups, found the same way and for the same reason, and by their
+     * name rather than their class, as the rules are: a list that holds no group
+     * does not carry the group's code, and either tier's tag ends the same way.
+     */
     private get groups();
+    /** Every option the list reads: the records of `items`, or the elements. */
+    private get entries();
+    /** The option elements on the page: the ones drawn for `items`, or the children. */
+    private get elements();
     /** The options a filter has left showing. */
     private get shown();
     /** The chosen values, as an array whether or not `multiple` is set. */
@@ -312,6 +457,12 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      */
     private choose;
     private readonly handleSelection;
+    /**
+     * Adds every option a reader can reach from the one last chosen to `to`,
+     * APG's Shift with Space and React Aria's Shift with a press. With none
+     * chosen yet, it adds `to` alone and the next range starts there.
+     */
+    private extend;
     /**
      * Moves the keyboard, and chooses with it only where that is the pattern.
      *
@@ -326,6 +477,7 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * a combobox or a command palette chose the highlighted option and closed the
      * panel, so a query of two words could not be typed.
      */
+    private readonly handleClick;
     private readonly handleKeydown;
     /**
      * Puts the highlight on an option, and chooses it where moving is choosing.
@@ -380,10 +532,8 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * read as a dial rather than scanned as a list, which is what Time Picker's
      * wheels do with three of these.
      *
-     * A delta from the two boxes rather than `offsetTop`. An option is a slotted
-     * light DOM child, so its `offsetParent` is whatever is positioned above it,
-     * which is not this list and is not guaranteed to be anything: measuring both
-     * rects and moving by the difference needs no such assumption.
+     * Measured by core's `centerInView`, or, for a list of `items`, by the
+     * arithmetic, since the chosen option may not be drawn.
      */
     reveal(): void;
     /** Hides what the filter excludes, and writes the rest onto the options. */
@@ -523,6 +673,8 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * different thing to say from a list that has none.
      */
     private get noResults();
+    /** Whether `load-error` holds words, which a removed attribute does not. */
+    private get failed();
     /** The error, or what a filter that hid everything says, before the shared words. */
     protected renderLive(hasContent: boolean): TemplateResult;
     protected render(): TemplateResult;