@fusion.dev/helix-headless 0.142.1 → 0.144.0

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

@@ -1,6 +1,6 @@
 import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
-import type { HelixHeadlessFilterField } from '../field/filter-field.js';
+import { HelixHeadlessFilterField } from '../field/filter-field.js';
 declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinTokensInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
  * @summary A text field for filters, with the active filters shown in it as tokens.
@@ -13,8 +13,10 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * its tokens show a selection it owns, drawn from the options it was given.
  *
  * `value` is the typed text. Every keystroke fires `input` with the text on the
- * element, so a table can narrow as the user types. Tokens are not reported,
- * because they are markup you already hold. Backspace in an empty field fires
+ * element, so a table can narrow as the user types. A form receives the text
+ * under `name`, and then one more entry under `name` for each token: its
+ * `value` attribute, or for a `FilterChip`, its field and values written
+ * `field:values` as the field reads them typed. Backspace in an empty field fires
  * `helix-dismiss` on the last token, the same event its remove control fires,
  * so one handler covers the pointer and the keyboard.
  *
@@ -38,8 +40,11 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * moves through them with the arrow keys, and presses one on Enter. The option
  * fires its own `helix-select`, and you decide what choosing it means. Keys
  * before a colon and values after it use the same panel with different
- * contents. `readFilterText` is exported so you can narrow the panel against
- * partly typed text. The panel opens when it has options and closes when it has
+ * contents. `filter-suggestions` narrows the panel to the options whose words
+ * hold the term at the caret, after its colon, ignoring case and accents, and
+ * hides the rest. `readFilterText` is exported so you can narrow it yourself
+ * against partly typed text. While the panel is open, a reader hears how many
+ * suggestions it offers. The panel opens when it has options and closes when it has
  * none, and a choice does not close it, so after picking a key you see its
  * values next. Use `selectionStart` and `setSelectionRange` to write a
  * completion back and put the caret after it, or the next parse reads the wrong
@@ -69,6 +74,9 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @documentation https://fusion.dev/helix/components/filter-input
  *
  * @slot end - Content after the text, such as a count or a control.
+ * @slot feedback - The message that says what is wrong, for content richer than a string. It shows while there is a message.
+ * @slot hint - Help under the control, for content richer than the `hint` text.
+ * @slot label - The label, for content richer than the `label` text.
  * @slot start - Content before the text, such as a search icon.
  * @slot suggestions - Suggestions for what to type next, as `Option`s and `Option.Group`s.
  * @slot tags - The active filters, as `FilterChip`s or `Tag`s.
@@ -81,7 +89,7 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @event {HelixFacetEvent} helix-facet - Fired when a filter changes, whether it was typed, picked, or removed. Cancelable: call `preventDefault()` to leave the text and the chip as they were.
  * @event {HelixSelectEvent} helix-select - Fired by an option in `suggestions` when it is chosen, and bubbles out of the field. Cancelable: call `preventDefault()` to stop other listeners acting on it. The field takes no action on a choice; you decide what it does.
  * @event {Event} input - Fired when the text changes.
- * @event {Event} toggle - Fired when the suggestions panel opens or closes, with `newState` and `oldState`.
+ * @event {ToggleEvent} toggle - Fired when the suggestions panel opens or closes, with `newState` and `oldState`.
  *
  * @csspart clear - The button that empties the field.
  * @csspart control - The input itself.
@@ -90,6 +98,7 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @csspart hint - The help text under the field, shown while there is no error.
  * @csspart label - The label above the field.
  * @csspart lead - The box before the text that holds the `start` slot.
+ * @csspart live - The live region that says how many suggestions the open panel offers. It is rendered from the first time the panel opens with suggestions.
  * @csspart rest - The count of tokens that did not fit. It is a `<button>` with `expandable` and a `<span>` without it.
  * @csspart surface - The floating panel the suggestions sit in.
  * @csspart tags - The row the tokens sit in.
@@ -115,12 +124,40 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * an icon.
      */
     clearLabel: string;
+    /**
+     * Whether the panel narrows itself to the suggestions that hold the term
+     * being typed, as React Aria's Autocomplete filters. Off, the panel shows
+     * what you slot and you narrow it.
+     */
+    filterSuggestions: boolean;
     /**
      * The text shown while the field is empty.
      *
      * Not a label: it goes when typing starts.
      */
     placeholder: string;
+    /** What a reader hears for one suggestion, with `{count}` filled in. */
+    suggestionLabel: string;
+    /** What a reader hears for any other number of suggestions, with `{count}` filled in. */
+    suggestionsLabel: string;
+    /** The live region, rendered from the first count said. */
+    private readonly status;
+    /** The count last said, so the same panel is said once. */
+    private saidCount;
+    /** The options this element hid while narrowing, so only those are shown again. */
+    private readonly narrowed;
+    /**
+     * Hides the slotted options whose words do not hold the term at the caret,
+     * under `filter-suggestions`, and shows again the ones it hid before.
+     */
+    private narrow;
+    /** Says how many suggestions the open panel offers, when that changes. */
+    private sayCount;
+    /**
+     * What the form receives: the text, then one entry for each token that
+     * says what it filters. See the class description.
+     */
+    private formValue;
     /** How many tokens did not fit, which is what the row's count renders. */
     private over;
     /**

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

@@ -4,11 +4,14 @@ 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, customElement, drawIcon, HelixFacetEvent, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, restoreValue, scrollItemIntoView, } from '@fusion.dev/helix-core';
+import { AriaForwardController, countLabel, customElement, drawIcon, drawStatus, HelixFacetEvent, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, restoreValue, StatusController, scrollItemIntoView, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { HelixHeadlessFilterField } from '../field/filter-field.js';
 import { readFilterText } from '../grammar.js';
+import { HelixHeadlessFilterMenu } from '../menu/filter-menu.js';
+import { currentTerm, suggests, tokenEntry } from '../suggest.js';
 const asksToGo = (node) => typeof node?.dismiss === 'function';
 const isOption = (node) => 'active' in node && 'value' in node;
 let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinControllerOpen(MixinTokens(MixinControllerValue(MixinField(HelixFormElement)))) {
@@ -20,7 +23,13 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         this.announcesInput = true;
         this.clearable = false;
         this.clearLabel = 'Clear';
+        this.filterSuggestions = false;
         this.placeholder = '';
+        this.suggestionLabel = '{count} suggestion';
+        this.suggestionsLabel = '{count} suggestions';
+        this.status = new StatusController(this);
+        this.saidCount = -1;
+        this.narrowed = new Set();
         this.over = 0;
         this.activeAt = -1;
         this.suggesting = false;
@@ -66,7 +75,9 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             menu.apply(field, []);
         };
         this.handleClear = () => {
-            this.requestValue('');
+            if (this.value !== '' && this.requestValue('')) {
+                this.announceChange();
+            }
             const control = this.control;
             if (control) {
                 restoreValue(control, this.value);
@@ -150,6 +161,51 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             this.over = this.hideOverflow(this.tokens);
         };
     }
+    narrow() {
+        const slot = this.renderRoot?.querySelector('slot[name="suggestions"]');
+        const term = this.filterSuggestions
+            ? currentTerm(this.value, this.control?.selectionStart ?? this.value.length)
+            : '';
+        for (const node of slot?.assignedElements({ flatten: true }) ?? []) {
+            const options = isOption(node) ? [node] : [...node.children].filter(isOption);
+            for (const option of options) {
+                const hide = !suggests(option.textContent ?? '', term);
+                if (hide && !option.hidden) {
+                    option.hidden = true;
+                    this.narrowed.add(option);
+                }
+                else if (!hide && this.narrowed.has(option)) {
+                    option.hidden = false;
+                    this.narrowed.delete(option);
+                }
+            }
+        }
+    }
+    sayCount() {
+        const count = this.open && this.suggesting ? this.suggestions.length : -1;
+        if (count === this.saidCount) {
+            return;
+        }
+        this.saidCount = count;
+        if (count < 0) {
+            return;
+        }
+        this.status.sayNow(countLabel(count, this.suggestionLabel, this.suggestionsLabel, this.lang));
+    }
+    formValue() {
+        const entries = (this.tokens?.assignedElements({ flatten: true }) ?? [])
+            .map(tokenEntry)
+            .filter((entry) => entry !== null);
+        if (this.name === '' || entries.length === 0) {
+            return this.value;
+        }
+        const data = new FormData();
+        data.append(this.name, this.value);
+        for (const entry of entries) {
+            data.append(this.name, entry);
+        }
+        return data;
+    }
     static { this.shadowRootOptions = {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
@@ -177,7 +233,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
                 }
             }
         }
-        return found.filter((option) => !option.disabled);
+        return found.filter((option) => !option.disabled && !option.hidden);
     }
     get selectionDirection() {
         return this.control?.selectionDirection ?? 'none';
@@ -192,12 +248,13 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         this.control?.setSelectionRange(start, end, direction);
     }
     get fields() {
-        return [
-            ...this.querySelectorAll('helix-headless-filter-field, helix-filter-field'),
-        ];
+        return [...this.querySelectorAll('*')].filter((element) => element instanceof HelixHeadlessFilterField);
     }
     menuFor(field) {
-        for (const menu of this.querySelectorAll('helix-headless-filter-menu, helix-filter-menu')) {
+        for (const menu of this.querySelectorAll('*')) {
+            if (!(menu instanceof HelixHeadlessFilterMenu)) {
+                continue;
+            }
             if (menu.fields.some((declared) => (declared.name ?? '') === field)) {
                 return menu;
             }
@@ -259,12 +316,16 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             from < 0 ? (by > 0 ? 0 : options.length - 1) : (from + by + options.length) % options.length;
     }
     refreshSuggesting() {
+        this.narrow();
         const options = this.suggestions;
         this.suggesting = options.length > 0;
         this.activeAt = this.activeAt < options.length ? this.activeAt : -1;
     }
     removeLastToken() {
-        const last = this.tokens?.assignedElements({ flatten: true }).at(-1);
+        const last = this.tokens
+            ?.assignedElements({ flatten: true })
+            .filter((token) => !token.hidden)
+            .at(-1);
         if (asksToGo(last)) {
             last.dismiss();
         }
@@ -303,7 +364,8 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         super.updated(changed);
         this.releaseCaret?.();
         this.releaseCaret = undefined;
-        this.internals.setFormValue(this.value);
+        this.internals.setFormValue(this.formValue());
+        this.sayCount();
         const control = this.control;
         if (control) {
             this.copyValidity(control);
@@ -373,9 +435,17 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
          built only once there were options could never learn that there are
          any. A manual popover puts it in the top layer, so it is not clipped by
          a scrolling table or an overflow on an ancestor. -->
-    <div part="surface" id="suggestions" role="listbox" popover="manual" ?hidden=${!this.open}>
+    <div
+      part="surface"
+      id="suggestions"
+      role="listbox"
+      aria-labelledby=${this.labeled ? this.labelId : nothing}
+      popover="manual"
+      ?hidden=${!this.open}
+    >
       <slot name="suggestions" @slotchange=${this.handleSuggestions}></slot>
     </div>
+    ${drawStatus(this.status)}
     ${this.renderHint()}${this.renderFeedback()}`;
     }
 };
@@ -385,9 +455,18 @@ __decorate([
 __decorate([
     property({ attribute: 'clear-label' })
 ], HelixHeadlessFilterInput.prototype, "clearLabel", void 0);
+__decorate([
+    property({ attribute: 'filter-suggestions', type: Boolean })
+], HelixHeadlessFilterInput.prototype, "filterSuggestions", void 0);
 __decorate([
     property()
 ], HelixHeadlessFilterInput.prototype, "placeholder", void 0);
+__decorate([
+    property({ attribute: 'suggestion-label' })
+], HelixHeadlessFilterInput.prototype, "suggestionLabel", void 0);
+__decorate([
+    property({ attribute: 'suggestions-label' })
+], HelixHeadlessFilterInput.prototype, "suggestionsLabel", void 0);
 __decorate([
     state()
 ], HelixHeadlessFilterInput.prototype, "over", void 0);

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

@@ -0,0 +1,17 @@
+/**
+ * What a filter field narrows its suggestions by, and what it sends a form,
+ * kept apart from the element so each can be read and tested alone.
+ */
+/**
+ * The term being typed at the caret: the run of text since the last space,
+ * and after its colon where it has one, so `status:ope` narrows by `ope`.
+ */
+export declare const currentTerm: (text: string, caret?: number) => string;
+/** Whether a suggestion's words hold the term, ignoring case and accents. */
+export declare const suggests: (words: string, term: string) => boolean;
+/**
+ * What a token sends a form: its `value` attribute, or for a token naming a
+ * field, the field and the values it shows, written `field:values` the way the
+ * field reads them typed. Nothing for a token that says neither.
+ */
+export declare const tokenEntry: (token: Element) => string | null;

package/dist/filter-input/suggest.js

@@ -0,0 +1,23 @@
+export const currentTerm = (text, caret = text.length) => {
+    const before = text.slice(0, caret);
+    const word = before.slice(before.search(/\S*$/u));
+    const colon = word.indexOf(':');
+    return (colon === -1 ? word : word.slice(colon + 1)).replace(/^-/u, '');
+};
+export const suggests = (words, term) => {
+    const plain = (text) => text.normalize('NFD').replace(/\p{M}/gu, '').toLowerCase();
+    return term === '' || plain(words).includes(plain(term));
+};
+export const tokenEntry = (token) => {
+    const written = token.getAttribute('value');
+    if (written !== null) {
+        return written;
+    }
+    const field = token.getAttribute('name');
+    const values = (token.textContent ?? '').replace(/\s+/gu, ' ').trim();
+    if (!field || values === '') {
+        return null;
+    }
+    const negated = token.getAttribute('operator')?.startsWith('not') ? '-' : '';
+    return `${negated}${field}:${values.replace(/\s*,\s*/gu, ',')}`;
+};

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

@@ -0,0 +1,33 @@
+/**
+ * What a Format Date was asked for, in its own spelling: the `Intl` options a
+ * consumer set, and whether the timestamp is a day with no time of day.
+ */
+export interface Asked {
+    dateOnly: boolean;
+    dateStyle?: 'full' | 'long' | 'medium' | 'short' | undefined;
+    day?: 'numeric' | '2-digit' | undefined;
+    era?: 'long' | 'narrow' | 'short' | undefined;
+    hour?: 'numeric' | '2-digit' | undefined;
+    hourCycle?: 'h11' | 'h12' | 'h23' | 'h24' | undefined;
+    minute?: 'numeric' | '2-digit' | undefined;
+    month?: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow' | undefined;
+    second?: 'numeric' | '2-digit' | undefined;
+    timeStyle?: 'full' | 'long' | 'medium' | 'short' | undefined;
+    timeZone?: string | undefined;
+    timeZoneName?: 'long' | 'short' | undefined;
+    weekday?: 'long' | 'short' | 'narrow' | undefined;
+    year?: 'numeric' | '2-digit' | undefined;
+}
+/**
+ * The `Intl.DateTimeFormat` options for what was asked, and none that was not.
+ *
+ * **A style wins over the fields.** `dateStyle` and `timeStyle` are each
+ * locale's own whole pattern, and `Intl` throws a `TypeError` when one is
+ * given beside `month` or `hour`, so the fields are left out wherever a style
+ * is set. `hourCycle` and `timeZone` go with either.
+ *
+ * **A day with no time is read in UTC** unless a zone is given. Parsed, it is
+ * midnight UTC, and read in a zone west of it that is the day before: measured
+ * before this, `2026-08-04` read "August 3, 2026" in Los Angeles.
+ */
+export declare const formatOptions: (asked: Asked) => Intl.DateTimeFormatOptions;

package/dist/format-date/options.js

@@ -0,0 +1,42 @@
+const FIELDS = [
+    'day',
+    'era',
+    'hour',
+    'minute',
+    'month',
+    'second',
+    'timeZoneName',
+    'weekday',
+    'year',
+];
+export const formatOptions = (asked) => {
+    const options = {};
+    const styled = asked.dateStyle !== undefined || asked.timeStyle !== undefined;
+    if (styled) {
+        if (asked.dateStyle) {
+            options.dateStyle = asked.dateStyle;
+        }
+        if (asked.timeStyle) {
+            options.timeStyle = asked.timeStyle;
+        }
+    }
+    else {
+        for (const field of FIELDS) {
+            const value = asked[field];
+            if (value) {
+                ;
+                options[field] = value;
+            }
+        }
+    }
+    if (asked.hourCycle) {
+        options.hourCycle = asked.hourCycle;
+    }
+    if (asked.timeZone) {
+        options.timeZone = asked.timeZone;
+    }
+    else if (asked.dateOnly) {
+        options.timeZone = 'UTC';
+    }
+    return options;
+};

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

@@ -12,13 +12,29 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * renders both `minute` and `month` as `m`, so a compact "3m" could mean three
  * minutes or three months. `elapsedTime` in `helix/core` does the measurement.
  *
+ * **`relative` shows the same reading in words**, such as "3 hours ago" at
+ * `long`, "3 hr. ago" at `short` and "3h ago" at `narrow`, the styles
+ * `sl-relative-time` offers. `numeric="always"` says "1 day ago" where the
+ * default says "yesterday".
+ *
+ * **`date-style` and `time-style` take each locale's own pattern**, such as
+ * "Tuesday, August 4, 2026" at `full`, and stand in for the separate fields,
+ * which `Intl` refuses beside them. `hour-cycle` sets a twelve or twenty-four
+ * hour clock either way.
+ *
  * **The text refreshes on one timer shared by the page.** Each element
  * schedules an update for when its current reading expires, and an element
  * showing a date schedules none, so a long feed left open costs almost nothing.
  *
- * **The output is always `<time datetime>`**, so screen readers, copy and
- * paste, and scripts parsing the page get the exact instant, whatever the
- * visible text says.
+ * **The output is always `<time datetime>`**, so copy and paste and scripts
+ * parsing the page get the exact instant, whatever the visible text says. A
+ * screen reader reads the text, so an `elapsed` reading is named in full, such
+ * as "3 hours ago", and carries the whole date as its title.
+ *
+ * **A date with no time, such as `2026-08-04`, is that day everywhere.** It is
+ * formatted in UTC unless `time-zone` says otherwise, as Date Input and Date
+ * Picker format their dates, so a reader west of UTC sees August 4 and not
+ * August 3.
  *
  * @since 0.1.0
  * @status stable
@@ -47,6 +63,11 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      * browser may use either.
      */
     date: 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`.
+     */
+    dateStyle?: 'full' | 'long' | 'medium' | 'short';
     /**
      * How the day of the month is written, where a date is shown.
      */
@@ -60,10 +81,22 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      * few characters and a date is not.
      */
     elapsed: boolean;
+    /**
+     * How the era is written, such as AD, where a date is shown.
+     */
+    era?: 'long' | 'narrow' | 'short';
     /**
      * How the hour is written, where a time of day is shown.
      */
     hour?: 'numeric' | '2-digit';
+    /**
+     * The clock a time of day is written on: `h12` or `h11` for twelve hours,
+     * `h23` or `h24` for twenty-four.
+     *
+     * Absent is the locale's own, which is right unless your product shows every
+     * reader the same clock whatever their language.
+     */
+    hourCycle?: 'h11' | 'h12' | 'h23' | 'h24';
     /**
      * The locale to format the timestamp in.
      *
@@ -78,10 +111,30 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      * How the month is written, where a date is shown.
      */
     month?: 'numeric' | '2-digit' | 'long' | 'short' | 'narrow';
+    /**
+     * Whether a `relative` reading may use a word for a number: `auto` says
+     * "yesterday" and "now", and `always` says "1 day ago" and "in 0 seconds".
+     */
+    numeric?: 'always' | 'auto';
+    /**
+     * Shows how long ago the timestamp was, or how long until it, in words, in
+     * place of the date: `long` ("3 hours ago"), `short` ("3 hr. ago") or
+     * `narrow` ("3h ago").
+     *
+     * The reading refreshes as it goes stale, as `elapsed` does, and the whole
+     * date is its title. `elapsed` wins where both are set.
+     */
+    relative?: 'long' | 'narrow' | 'short';
     /**
      * How the second is written, where a time of day is shown.
      */
     second?: 'numeric' | '2-digit';
+    /**
+     * The locale's own pattern for the time of day: `full`, `long`, `medium`, or
+     * `short`. Set, it stands in for `hour`, `minute`, `second` and
+     * `time-zone-name`.
+     */
+    timeStyle?: 'full' | 'long' | 'medium' | 'short';
     /**
      * The time zone to read the timestamp in.
      *
@@ -114,10 +167,16 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
     private written;
     private stopTicking;
     private watching;
+    /** Whether the timestamp is a day with no time, which is formatted in UTC. */
+    private get dateOnly();
     /** The timestamp, or nothing where there is not one to read. */
     private get moment();
     /** Every `Intl.DateTimeFormat` option a consumer set, and none they did not. */
     private get options();
+    /** Whether the reading is how long ago rather than the date. */
+    private get reading();
+    /** What the reading says now, and when it stops being true. */
+    private readingAt;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected firstUpdated(changed: PropertyValues): void;