@fusion.dev/helix-headless 0.165.0 → 0.166.0

package/dist/menu/item/menu-item.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 { ariaChord, auditName, customElement, deepActiveElement, HelixBeforeToggleEvent, HelixElement, HelixSelectEvent, isRtl, onApple, onUnlessFalse, PopoverController, requestChange, slotFilled, } from '@fusion.dev/helix-core';
+import { ariaChord, auditName, customElement, deepActiveElement, followLink, HelixBeforeToggleEvent, HelixElement, HelixSelectEvent, hostAria, isRtl, onApple, onUnlessFalse, PopoverController, requestChange, slotFilled, } from '@fusion.dev/helix-core';
 import { caretRight, check } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -21,6 +21,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.exclusive = false;
         this.expanded = false;
         this.flyout = false;
+        this.highlighted = false;
         this.href = '';
         this.onPage = true;
         this.rel = '';
@@ -28,6 +29,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.showingSubmenu = false;
         this.target = '';
         this.value = '';
+        this.virtual = false;
         this.isMenuItem = true;
         this.keepsOpen = false;
         this.submenu = false;
@@ -90,6 +92,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleState('checked', this.checked);
+        this.toggleState('highlighted', this.virtual && this.highlighted);
         if (!this.childrenKnown) {
             return;
         }
@@ -109,6 +112,11 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
     }
     updated(changed) {
         super.updated(changed);
+        hostAria(this.internals, {
+            describedBy: this.onHost
+                ? [...this.renderRoot.querySelectorAll('#description, #end-words')].filter((slot) => slot.id === 'description' ? this.description : this.end)
+                : [],
+        });
         if (this.partNamed('item')) {
             auditName(this, () => this.partNamed('item') ?? undefined, 'Give the row words in its default slot, or a label on the icon it holds.');
         }
@@ -126,7 +134,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         const ids = [this.description ? 'description' : '', this.end ? 'end-words' : '']
             .filter((id) => id !== '')
             .join(' ');
-        return ids === '' ? nothing : ids;
+        return ids === '' ? null : ids;
     }
     renderEnd() {
         const kbd = this.tag('kbd');
@@ -151,6 +159,9 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.choose();
     }
     get active() {
+        if (this.virtual) {
+            return this.highlighted;
+        }
         const active = deepActiveElement();
         return active !== null && active.getRootNode() === this.renderRoot;
     }
@@ -201,7 +212,11 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         const spaceKeeps = space && this.choice && !this.hasSubmenu;
         this.keepsOpen = this.closeOnSelect === undefined ? spaceKeeps : !this.closeOnSelect;
         this.tick();
-        this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
+        if (this.dispatchEvent(new HelixSelectEvent({ value: this.value })) &&
+            this.virtual &&
+            this.href !== '') {
+            followLink(this.ownerDocument, this);
+        }
     }
     renderMark(submenu) {
         if (submenu) {
@@ -220,19 +235,31 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         }
         return nothing;
     }
+    get onHost() {
+        return this.virtual && this.onPage && !this.showingSubmenu;
+    }
     render() {
+        const submenu = this.hasSubmenu;
+        const ticks = this.choice;
+        const role = ticks ? (this.exclusive ? 'menuitemradio' : 'menuitemcheckbox') : 'menuitem';
+        const checkedState = ticks ? (this.checked ? 'true' : 'false') : null;
+        const keys = this.shortcut === '' ? null : ariaChord(this.shortcut, !this.hydrating && onApple());
+        const host = this.onHost;
+        const internals = this.internals;
+        internals.role = host ? role : null;
+        internals.ariaChecked = host ? checkedState : null;
+        internals.ariaDisabled = host && this.disabled ? 'true' : null;
+        internals.ariaHasPopup = host && submenu ? 'menu' : null;
+        internals.ariaExpanded = host && this.flyout && submenu ? String(this.expanded) : null;
+        internals.ariaKeyShortcuts = host ? keys : null;
+        const own = (value) => (host || value === null ? nothing : value);
         if (this.showingSubmenu) {
             return html `<slot name="submenu" @slotchange=${this.readSubmenu}></slot>`;
         }
         if (!this.onPage) {
             return nothing;
         }
-        const submenu = this.hasSubmenu;
-        const linked = this.href !== '' && !this.disabled;
-        const ticks = this.choice;
-        const role = ticks ? (this.exclusive ? 'menuitemradio' : 'menuitemcheckbox') : 'menuitem';
-        const checkedState = ticks ? (this.checked ? 'true' : 'false') : nothing;
-        const keys = this.shortcut === '' ? nothing : ariaChord(this.shortcut, !this.hydrating && onApple());
+        const linked = this.href !== '' && !this.disabled && !this.virtual;
         const inside = html `<span part="start" ?data-empty=${!this.start}
           ><slot name="start" @slotchange=${this.readStart}></slot
         ></span>
@@ -249,11 +276,11 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             rel=${this.rel || nothing}
             ?download=${this.download}
             role=${role}
-            aria-checked=${checkedState}
-            aria-describedby=${this.describedBy}
+            aria-checked=${own(checkedState)}
+            aria-describedby=${own(this.describedBy)}
             aria-haspopup=${submenu ? 'menu' : nothing}
             aria-expanded=${this.flyout && submenu ? String(this.expanded) : nothing}
-            aria-keyshortcuts=${keys}
+            aria-keyshortcuts=${own(keys)}
             tabindex="-1"
             @click=${this.handleClick}
             @keydown=${this.handleKeydown}
@@ -261,14 +288,14 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             : html `<div
             part="item"
             id=${this.flyout ? 'row' : nothing}
-            role=${role}
-            aria-checked=${checkedState}
-            aria-describedby=${this.describedBy}
-            aria-disabled=${this.disabled ? 'true' : nothing}
-            aria-haspopup=${submenu ? 'menu' : nothing}
-            aria-expanded=${this.flyout && submenu ? String(this.expanded) : nothing}
-            aria-keyshortcuts=${keys}
-            tabindex=${this.disabled ? nothing : '-1'}
+            role=${own(role)}
+            aria-checked=${own(checkedState)}
+            aria-describedby=${own(this.describedBy)}
+            aria-disabled=${own(this.disabled ? 'true' : null)}
+            aria-haspopup=${own(submenu ? 'menu' : null)}
+            aria-expanded=${own(this.flyout && submenu ? String(this.expanded) : null)}
+            aria-keyshortcuts=${own(keys)}
+            tabindex=${own(this.disabled ? null : '-1')}
             @click=${this.handleClick}
             @keydown=${this.handleKeydown}
           >${inside}</div>`}
@@ -307,6 +334,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessMenuItem.prototype, "flyout", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessMenuItem.prototype, "highlighted", void 0);
 __decorate([
     property()
 ], HelixHeadlessMenuItem.prototype, "href", void 0);
@@ -328,6 +358,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessMenuItem.prototype, "value", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessMenuItem.prototype, "virtual", void 0);
 __decorate([
     state()
 ], HelixHeadlessMenuItem.prototype, "submenu", void 0);

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

@@ -65,6 +65,21 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * opens it from the keyboard, and the trigger is described by
  * `long-press-label`, which says so.
  *
+ * **A filter field.** With `filterable`, the menu opens with focus in a field
+ * above its rows, and typing narrows the rows of the page the keys move in,
+ * as React Aria's `Autocomplete` around a `Menu` does. A row is kept where its
+ * words hold the filter, in any case, or where `filterMatch` says so. Each
+ * page starts unfiltered, and the filter is cleared as the menu closes. Where
+ * typing keeps no row, the menu shows `no-results-text`. Focus stays in the
+ * field: Up and Down Arrow move the highlight through the rows that are left,
+ * Enter chooses the highlighted row, Right Arrow opens its submenu, Left Arrow
+ * on a submenu goes back, and Escape clears the filter and then closes the
+ * menu. Home, End and the other keys move the caret and type. The field names
+ * the highlighted row with `aria-activedescendant`, and the rows are a `menu`
+ * after the field. Cancel `helix-filter` to keep every row
+ * showing and narrow the rows yourself, such as by replacing them with rows
+ * from a server.
+ *
  * @since 0.1.0
  * @status stable
  * @category overlays
@@ -72,10 +87,12 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @documentation https://fusion.dev/helix/components/menu
  *
  * @slot - The items.
+ * @slot no-results - What the menu shows when the filter keeps no rows, for content richer than `no-results-text`.
  * @slot trigger - The control that opens the menu, or with `context` the area a context menu opens over.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - The menu is about to close. Cancelable: cancel it to keep it open.
  * @event {HelixBeforeOpenEvent} helix-before-open - The menu is about to open. Cancelable: cancel it to keep it closed.
+ * @event {HelixFilterEvent} helix-filter - The text in the filter field changed, with the new text in `detail.value`. Cancelable: cancel it to keep every row showing and narrow the rows yourself.
  * @event {HelixSelectEvent} helix-select - An item was chosen. Cancelable: cancel it to keep the menu open.
  * @event {ToggleEvent} toggle - The menu opened or closed. The event carries `newState` and `oldState`.
  *
@@ -85,7 +102,8 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @csspart header - The bar above a submenu, holding the way back and its name.
  * @csspart live - A live region that repeats the empty and loading text, so screen readers announce it when it changes. Visually hidden in the styled tier.
  * @csspart loading - The text shown while the items are loading.
- * @csspart surface - The floating panel the menu is drawn on.
+ * @csspart search-field - With `filterable`, the field that narrows the rows.
+ * @csspart surface - The floating panel the menu is drawn on. It is the `menu` itself, and with `filterable` it holds the filter field and then the `menu`.
  * @csspart title - The name of the submenu that is showing.
  *
  * @cssproperty --floating-anchor-inline-size - The trigger's width, written on the panel while it is open, as in `min-inline-size: var(--floating-anchor-inline-size)`. Read it; a value set here is written over.
@@ -123,6 +141,31 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * asks for one, with a right-click, a long press, Shift+F10 or the menu key.
      */
     context: boolean;
+    /**
+     * The text the rows are filtered by, which the filter field holds.
+     *
+     * Cleared as the menu closes and as a submenu opens or closes, so each page
+     * starts with every row showing.
+     */
+    filter: string;
+    /**
+     * Whether the menu shows a field above its rows that narrows them as the
+     * reader types, with focus staying in the field.
+     */
+    filterable: boolean;
+    /**
+     * The filter field's name and placeholder.
+     */
+    filterLabel: string;
+    /**
+     * Whether a row is kept by the filter: a function given the row's words and
+     * the filter, trimmed, that returns `true` to keep it showing, as React
+     * Aria's `Autocomplete` takes `filter`. See Listbox's `filterMatch`.
+     *
+     * Absent, a row is kept where its words hold the filter, in any case. A
+     * property only, there being no way to write a function in markup.
+     */
+    filterMatch?: ((text: string, filter: string) => boolean) | undefined;
     /**
      * Accessible name for the surface.
      *
@@ -153,6 +196,10 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * to open the menu. Translate it with the rest of your interface.
      */
     longPressLabel: string;
+    /**
+     * The text shown when the filter keeps no rows.
+     */
+    noResultsText: string;
     /**
      * Space between the trigger and the surface, in pixels.
      */
@@ -234,6 +281,35 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private get trigger();
     /** The items on the page that is showing, which is what the keys move over. */
     private get items();
+    /** The element that is the `menu`: the surface, or with `filterable` the box after the field. */
+    private get menuBox();
+    /** The filter field, with `filterable`. */
+    private get field();
+    /** The submenu the filter narrows, or null for the top page. */
+    private filterPage;
+    /** The filter a listener refused, which narrows nothing. */
+    private refused;
+    /** Whether the filter is narrowing the rows. */
+    private get filtering();
+    /** Whether the filter keeps a row: one of another page, or one whose words it matches. */
+    private kept;
+    /**
+     * Asks to filter by new text, which the field and `filter` then hold. A
+     * refusal keeps every row showing, for a page that narrows them itself.
+     */
+    private requestFilter;
+    private readonly handleFilterInput;
+    /** Filters by what the reader typed, and highlights the first row kept. */
+    private filterBy;
+    /** The row the keys reached while focus stays in the filter field. */
+    private highlighted;
+    /**
+     * Moves the reader to a row: focus, or with `filterable` the highlight,
+     * which the field names with `aria-activedescendant`. An element reference,
+     * because the field is in this shadow root and the row in the tree around
+     * it, the one direction a reference crosses.
+     */
+    private reach;
     /** Opens the menu. */
     show(): void;
     /** Opens the menu with focus on its first or its last row. */
@@ -260,6 +336,8 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * below the fold of a scrolled panel.
      */
     private readonly handleFocusIn;
+    /** Scrolls the panel that holds a row to show it. */
+    private revealRow;
     private readonly handleKeydown;
     /**
      * Down and Up on the trigger open the menu on its first and its last row.
@@ -276,6 +354,11 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * `open-on="long-press"`, or a touch or a pen held on a context menu's area.
      */
     private readonly handlePointerDown;
+    /**
+     * Keeps focus in the filter field through a press on a row or the way
+     * back, as React Aria's virtual focus does: the press still chooses.
+     */
+    private readonly handleMouseDown;
     private readonly handlePointerMove;
     private readonly handlePointerUp;
     private readonly handlePointerCancel;