@fusion.dev/helix-headless 0.165.0 → 0.167.0

package/dist/element-events.generated.js

@@ -17,6 +17,7 @@ registerElementEvents({
     'helix-headless-callout': ['helix-dismiss'],
     'helix-headless-canvas': [
         'helix-before-move',
+        'helix-before-paste',
         'helix-before-reconnect',
         'helix-before-relabel',
         'helix-canvas-edit',
@@ -25,6 +26,7 @@ registerElementEvents({
         'helix-canvas-zoom',
         'helix-connect',
         'helix-move',
+        'helix-pasted',
         'helix-reconnect',
         'helix-relabel',
         'helix-remove',
@@ -36,7 +38,14 @@ registerElementEvents({
     'helix-headless-chat-message': ['helix-send'],
     'helix-headless-checkbox': ['change', 'helix-before-toggle', 'input'],
     'helix-headless-checkbox-group': ['change', 'helix-before-change', 'input'],
-    'helix-headless-code-block': ['helix-before-toggle', 'helix-toggle'],
+    'helix-headless-code-block': [
+        'change',
+        'helix-before-change',
+        'helix-before-toggle',
+        'helix-copy',
+        'helix-copy-error',
+        'helix-toggle',
+    ],
     'helix-headless-color-input': [
         'change',
         'helix-before-change',
@@ -186,7 +195,13 @@ registerElementEvents({
     'helix-headless-map-route': ['helix-map-part-change'],
     'helix-headless-map-terrain': ['helix-map-part-change'],
     'helix-headless-megamenu': ['helix-before-close', 'helix-before-open', 'toggle'],
-    'helix-headless-menu': ['helix-before-close', 'helix-before-open', 'helix-select', 'toggle'],
+    'helix-headless-menu': [
+        'helix-before-close',
+        'helix-before-open',
+        'helix-filter',
+        'helix-select',
+        'toggle',
+    ],
     'helix-headless-menu-item': ['helix-before-toggle', 'helix-select'],
     'helix-headless-meter': ['helix-band'],
     'helix-headless-notification': ['helix-dismiss', 'helix-read'],

package/dist/file-input/root/file-input-root.d.ts

@@ -2,7 +2,7 @@ import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core'
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import { type FileStatus } from '../status.js';
 export type { FileStatus } from '../status.js';
-import '../../tag/index.js';
+import '../../tag/root/index.js';
 declare const HelixHeadlessFileInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
  * @summary A field for choosing files from a picker or by dropping them on it.

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

@@ -11,7 +11,7 @@ import { property, state } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import { screenFiles } from '../screen.js';
 import { barOf, saysStatus } from '../status.js';
-import '../../tag/index.js';
+import '../../tag/root/index.js';
 const size = (bytes, locale, inBytes) => {
     const units = ['', 'KB', 'MB', 'GB', 'TB'];
     let value = bytes;

package/dist/filter-input/menu/filter-menu.d.ts

@@ -82,6 +82,7 @@ import '../../menu/index.js';
  * @csspart menu-header - The bar above a field's page, with the back button and the field's name.
  * @csspart menu-live - The inner menu's `live` part: the region that screen readers announce the empty and loading messages from.
  * @csspart menu-loading - Shown while the fields are loading.
+ * @csspart menu-search-field - The inner menu's filter field, drawn with `filterable`.
  * @csspart menu-surface - The floating panel the menu is drawn on.
  * @csspart menu-title - The name of the field whose page is showing.
  */

package/dist/filter-input/menu/filter-menu.js

@@ -126,7 +126,7 @@ let HelixHeadlessFilterMenu = class HelixHeadlessFilterMenu extends HelixElement
         return html `<${menu}
       part="menu"
       exportparts="back: menu-back, back-mark: menu-back-mark, empty: menu-empty, header: menu-header,
-        live: menu-live, loading: menu-loading, surface: menu-surface, title: menu-title"
+        live: menu-live, loading: menu-loading, search-field: menu-search-field, surface: menu-surface, title: menu-title"
       label=${this.label}
       @helix-select=${this.handleSelect}
     >

package/dist/format-date/root/format-date-root.d.ts

@@ -84,7 +84,8 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      */
     calendar?: DateCalendar | MonthCalendar;
     /**
-     * The timestamp, in any format `Date` can parse.
+     * The timestamp: a `Date`, milliseconds since the epoch, or a string in any
+     * format `Date` can parse. The attribute is the string.
      *
      * An ISO string is what an API sends and what `<time datetime>` takes, so it
      * is the shape that needs no translation at either end. Left unset this
@@ -100,7 +101,7 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      * it. An element rendered on a server needs the attribute; one rendered in a
      * browser may use either.
      */
-    date: string;
+    date: Date | number | string;
     /**
      * The locale's own pattern for the date: `full`, `long`, `medium`, or
      * `short`. Set, it stands in for `weekday`, `day`, `month`, `year` and `era`.
@@ -259,7 +260,13 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
     private get dateOnly();
     /** The timestamp, or nothing where there is not one to read. */
     private get moment();
-    /** The timestamp as written, in the attribute or in the light DOM. */
+    /**
+     * The timestamp as written, in the property, the attribute or the light DOM.
+     *
+     * A `Date` or a number is written as its ISO string, so it is read the way an
+     * attribute is. Measured before this: assigning `new Date()` threw, since
+     * only a string has `trim`, where Shoelace and Web Awesome take a `Date`.
+     */
     private get source();
     /** Whether the reading is how long ago rather than the date. */
     private get reading();

package/dist/format-date/root/format-date-root.js

@@ -44,7 +44,12 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         return Number.isNaN(parsed.getTime()) ? undefined : parsed;
     }
     get source() {
-        return (this.date || this.written).trim();
+        const date = this.date;
+        if (typeof date === 'string') {
+            return (date || this.written).trim();
+        }
+        const at = new Date(date);
+        return Number.isNaN(at.getTime()) ? '' : at.toISOString();
     }
     get reading() {
         return this.elapsed || this.relative !== undefined;

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

@@ -542,7 +542,8 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      */
     navigate(event: KeyboardEvent): void;
     /**
-     * Scrolls the chosen option to the middle of the list.
+     * Scrolls the chosen option to the middle of the list, or the highlighted one
+     * where nothing is chosen.
      *
      * A method rather than something this does on its own, because a listbox
      * opening on its answer usually wants it merely *visible* and the browser
@@ -554,6 +555,16 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * arithmetic, since the chosen option may not be drawn.
      */
     reveal(): void;
+    /**
+     * Puts the highlight on the option holding `value`, without choosing it, so
+     * the arrow keys move from there. Nothing changes where no option a reader
+     * can reach holds `value`.
+     *
+     * Time Picker calls it for a time between two of its steps, which no option
+     * holds: without it the first arrow moved from the top of the list, so Down
+     * from 14:07 went to midnight.
+     */
+    highlightValue(value: string): void;
     /** Hides what the filter excludes, and writes the rest onto the options. */
     private place;
     /**

package/dist/listbox/root/listbox-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, centerInView, chosenValues, columnStep, countLabel, customElement, DelayController, DisabledCascadeController, drawAutofill, endInSight, formatWords, HelixFilterEvent, HelixFormElement, HelixLoadMoreEvent, hostAria, inlineStep, MixinCollection, MixinControllerValue, MixinField, markMatches, OptionWindowController, onApple, pageRows, rangeAdd, reportValues, requestChange, scrollItemIntoView, selectsAll, Typeahead, toggleEvery, typesCharacter, UpgradeController, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { AriaForwardController, centerInView, chosenValues, columnStep, countLabel, customElement, DelayController, DisabledCascadeController, drawAutofill, endInSight, filterKeeps, formatWords, HelixFilterEvent, HelixFormElement, HelixLoadMoreEvent, hostAria, inlineStep, MixinCollection, MixinControllerValue, MixinField, markMatches, OptionWindowController, onApple, pageRows, rangeAdd, reportValues, requestChange, scrollItemIntoView, selectsAll, Typeahead, toggleEvery, typesCharacter, UpgradeController, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { magnifyingGlass } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -391,21 +391,30 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             return;
         }
         const items = this.partNamed('items');
-        const chosen = this.options.find((option) => option.selected && !option.hidden);
+        const chosen = this.options.find((option) => option.selected && !option.hidden) ??
+            this.options.find((option) => option.value === this.activeValue && !option.hidden);
         if (items && chosen) {
             centerInView(items, chosen);
         }
     }
+    highlightValue(value) {
+        if (!this.shown.some((option) => !option.disabled && option.value === value)) {
+            return;
+        }
+        this.typeahead.reset();
+        this.parked = false;
+        this.activeValue = value;
+        if (this.childrenKnown) {
+            this.place();
+        }
+    }
     place() {
         this.forgetRemoved();
         const typed = this.filter.trim();
         const needle = typed.toLowerCase();
-        const match = this.filterMatch;
         const chosen = new Set(this.values);
         for (const option of this.entries) {
-            option.hidden =
-                needle !== '' &&
-                    !(match ? match(option.text, typed) : option.text.toLowerCase().includes(needle));
+            option.hidden = !filterKeeps(option.text, typed, this.filterMatch);
             option.selected = chosen.has(option.value);
         }
         for (const group of this.groups) {

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

@@ -47,6 +47,12 @@ import '../../kbd/index.js';
  * slots, so a mark of your own replaces either by being slotted. Neither is
  * read as part of the row's name.
  *
+ * In a menu with `filterable`, focus stays in the menu's filter field and the
+ * row the arrow keys reach is highlighted: the field names it with
+ * `aria-activedescendant`, the row carries its role on its host so the field
+ * can point at it, and `:state(highlighted)` says which row it is. A row with
+ * an `href` then follows its link without an anchor, as `Option` does.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases Menu option, Menu row
@@ -75,6 +81,7 @@ import '../../kbd/index.js';
  * @csspart surface - The panel a submenu opens in beside the row, under the menu's `submenus="flyout"`.
  *
  * @cssstate checked - The row is checked.
+ * @cssstate highlighted - In a menu with `filterable`, the arrow keys or the pointer reached the row while focus stays in the filter field.
  * @cssstate submenu-mark - Under `submenus="flyout"`, a row in this row's submenu can be ticked or opens a submenu, so the submenu keeps its trailing column.
  * @cssstate submenu-start - Under `submenus="flyout"`, a row in this row's submenu has content before its label, so the submenu keeps its leading column.
  */
@@ -144,6 +151,11 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * `submenus="flyout"`. Written by the menu.
      */
     flyout: boolean;
+    /**
+     * @internal Whether the row is the one the keys reached in a menu that keeps
+     * focus in its filter field. Written by the menu.
+     */
+    highlighted: boolean;
     /**
      * The URL the row links to. Setting it renders the row as a link.
      *
@@ -200,6 +212,12 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * The row's value, sent in `helix-select` when the row is chosen.
      */
     value: string;
+    /**
+     * @internal Whether the menu keeps focus in its filter field, so the row is
+     * highlighted rather than focused and says what it is from its host, where
+     * the field's `aria-activedescendant` can reach it. Written by the menu.
+     */
+    virtual: boolean;
     /**
      * @internal Read by a parent to identify its children across the light DOM,
      * which is cheaper than `instanceof` and is why this is public rather than
@@ -414,6 +432,8 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * still line up without every row carrying an empty box to line them up with.
      */
     protected renderMark(submenu: boolean): TemplateResult | typeof nothing;
+    /** Whether the row says what it is from its host, for a field's `aria-activedescendant`. */
+    private get onHost();
     protected render(): TemplateResult | typeof nothing;
 }
 declare global {

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;