@fusion.dev/helix-headless 0.147.0 → 0.148.0

package/dist/legend/root/legend-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 { customElement, HelixBeforeChangeEvent, HelixElement, KeyboardNavigationController, requestChange, SourceController, seriesIndex, seriesKey, typeaheadBy, } from '@fusion.dev/helix-core';
+import { customElement, focusItemOf, HelixElement, KeyboardNavigationController, requestValue, SourceController, seriesIndex, seriesKey, typeaheadBy, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { isHidden, namesIn, toggledNames } from '../hidden-series.js';
@@ -19,14 +19,7 @@ let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
         this.stop = 0;
         this.keys = new KeyboardNavigationController(this, {
             items: () => this.toggles
-                ? [...this.renderRoot.querySelectorAll('[part="toggle"]')].map((button) => ({
-                    contains: (node) => button.contains(node),
-                    disabled: false,
-                    focusItem: () => button.focus(),
-                    select: () => { },
-                    selected: false,
-                    words: button.textContent?.trim() ?? '',
-                }))
+                ? [...this.renderRoot.querySelectorAll('[part="toggle"]')].map((button) => focusItemOf(button, { words: button.textContent?.trim() ?? '' }))
                 : [],
             origin: 'focus',
             selects: () => false,
@@ -73,14 +66,8 @@ let HelixHeadlessLegend = class HelixHeadlessLegend extends HelixElement {
         super.disconnectedCallback();
     }
     toggle(name) {
-        requestChange({
-            apply: (value) => {
-                this.hiddenSeries = value;
-                this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
-            },
-            event: (value) => new HelixBeforeChangeEvent({ value }),
-            host: this,
-            next: toggledNames(this.hiddenSeries, name),
+        requestValue(this, toggledNames(this.hiddenSeries, name), (value) => {
+            this.hiddenSeries = value;
         });
     }
     names() {

package/dist/list/root/list-root.js

@@ -4,13 +4,12 @@ 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 { commaList, customElement, HelixActionEvent, HelixBeforeChangeEvent, HelixElement, hostAria, inlineStep, KeyboardNavigationController, requestChange, rovingStop, selectsAll, typeaheadByWords, whenHydrated, } from '@fusion.dev/helix-core';
+import { commaList, customElement, focusItemOf, HelixActionEvent, HelixElement, hostAria, inlineStep, KeyboardNavigationController, pressedOwnControl, requestValue, rovingStop, scrollRoom, selectsAll, typeaheadByWords, whenHydrated, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessListItem } from '../item/list-item.js';
 import { numbering } from '../numbering.js';
 import { choiceValue, pageReach, rowStop, } from '../selection.js';
-const PRESSABLE = 'a[href], button, input, label, select, textarea, [tabindex]';
 let HelixHeadlessList = class HelixHeadlessList extends HelixElement {
     constructor() {
         super(...arguments);
@@ -71,11 +70,8 @@ let HelixHeadlessList = class HelixHeadlessList extends HelixElement {
             if (!row) {
                 return;
             }
-            const path = event.composedPath();
             const cell = row.cell;
-            const end = cell && path.includes(cell) ? path.indexOf(cell) : path.indexOf(row);
-            const inner = path.slice(0, Math.max(0, end));
-            if (inner.some((node) => node instanceof HTMLElement && node.matches(PRESSABLE))) {
+            if (pressedOwnControl(event, cell && event.composedPath().includes(cell) ? cell : row)) {
                 return;
             }
             if (this.selectionMode === 'none') {
@@ -110,14 +106,11 @@ let HelixHeadlessList = class HelixHeadlessList extends HelixElement {
         return this.interactive ? this.rows.filter((row) => !row.disabled) : [];
     }
     navigable(row) {
-        return {
-            contains: (node) => row.contains(node),
+        return focusItemOf(row, {
             disabled: row.disabled,
-            focusItem: () => row.focusItem(),
-            select: () => { },
-            selected: false,
+            focus: () => row.focusItem(),
             words: row.words,
-        };
+        });
     }
     valueFor(row) {
         return row.value || row.words;
@@ -149,14 +142,8 @@ let HelixHeadlessList = class HelixHeadlessList extends HelixElement {
         if (next === null) {
             return;
         }
-        requestChange({
-            apply: (value) => {
-                this.value = value;
-                this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
-            },
-            event: (value) => new HelixBeforeChangeEvent({ value }),
-            host: this,
-            next,
+        requestValue(this, next, (value) => {
+            this.value = value;
         });
     }
     choice(row, extend, toggle, arrived) {
@@ -203,8 +190,7 @@ let HelixHeadlessList = class HelixHeadlessList extends HelixElement {
             const box = one.getBoundingClientRect();
             return { bottom: box.bottom, top: box.top };
         });
-        const room = this.scrollHeight > this.clientHeight + 1 ? this.clientHeight : window.innerHeight;
-        const target = rows[pageReach(edges, rows.indexOf(row), room, step)];
+        const target = rows[pageReach(edges, rows.indexOf(row), scrollRoom(this), step)];
         if (target && target !== row) {
             target.focusItem();
         }

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,31 @@ 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. |
+ *
+ * **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.
@@ -82,12 +97,16 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
 export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
     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 +157,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.
@@ -180,6 +234,11 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * writes the rest here.
      */
     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;
     /**
      * Which option the keyboard is on, which is not what is chosen.
      */
@@ -189,6 +248,8 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * it back on the first match.
      */
     private parked;
+    /** The option last chosen, which Shift with Space extends from. */
+    private anchor;
     /** The letters typed at the list, which move the highlight to a match. */
     private readonly typeahead;
     /**
@@ -212,6 +273,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 +285,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 +324,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 +344,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 +380,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 +402,11 @@ 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. With none chosen yet, it adds `to` alone.
+     */
+    private extend;
     /**
      * Moves the keyboard, and chooses with it only where that is the pattern.
      *
@@ -380,10 +475,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 +616,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;