@fusion.dev/helix-headless 0.142.1 → 0.144.0

package/dist/listbox/range.d.ts

@@ -0,0 +1,17 @@
+/**
+ * What Shift with Home or End adds to a listbox's selection, as arithmetic
+ * over the options on show.
+ *
+ * Pure and beside the family's `index.ts`, because which options a range takes
+ * in is a fact about a list, and a spec can hold it without a page.
+ */
+/**
+ * The selection after Shift with Home or End: every option shown from the
+ * highlight to the end the key went to, added after what was selected, or
+ * `null` where nothing new is taken in.
+ *
+ * `from` is where the highlight was, as an index into `shown`, or `-1` for no
+ * highlight, which takes in the end alone. `to` is the end the key went to.
+ * APG's multiple-selection listbox.
+ */
+export declare const rangeAdd: (values: readonly string[], shown: readonly string[], from: number, to: number) => string[] | null;

package/dist/listbox/range.js

@@ -0,0 +1,5 @@
+export const rangeAdd = (values, shown, from, to) => {
+    const [start, end] = from < 0 ? [to, to] : [Math.min(from, to), Math.max(from, to)];
+    const added = shown.slice(start, end + 1).filter((value) => !values.includes(value));
+    return added.length > 0 ? [...values, ...added] : null;
+};

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

@@ -1,5 +1,5 @@
 import { AriaForwardController, DisabledCascadeController, HelixFormElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+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,6 +20,22 @@ 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.
+ *
+ * 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.
+ *
+ * As a filter narrows the list, a screen reader hears how many options are
+ * left, such as "3 results", from `result-label` and `results-label`. A filter
+ * that leaves none says `empty-text`.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
@@ -27,9 +43,12 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
  * @documentation https://fusion.dev/helix/components/listbox
  *
  * @slot - The options, and any groups of them.
+ * @slot empty - What the list shows when it has no options to show, for content richer than `empty-text`.
+ * @slot feedback - The message that says what is wrong, for content richer than a string. It shows while there is a message.
  * @slot filter-icon - The icon in the filter field. Defaults to a magnifying glass.
  * @slot hint - The hint, for content richer than plain text.
  * @slot label - The label, for content richer than plain text.
+ * @slot loading - What the list shows while its options load, for content richer than `loading-text`.
  *
  * @event {Event} change - Fired after the value changes.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired when the value is about to change, and cancelable.
@@ -43,12 +62,14 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
  * @csspart hint - Help under the list.
  * @csspart items - The list of options.
  * @csspart label - The label above the list.
- * @csspart live - A copy of the empty and loading text, in a region that screen readers announce when it changes. Visually hidden in the styled tier.
+ * @csspart live - A copy of the empty and loading text, and how many options a filter left, in a region that screen readers announce when it changes. Visually hidden in the styled tier.
  * @csspart loading - The text shown while the options load.
  * @csspart search - The region that holds the filter field.
  * @csspart search-field - The filter field.
  *
+ * @cssstate empty - The list has no options to show: none were given, or the filter hid every one.
  * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
+ * @cssstate loading - While `loading` is set.
  */
 export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
     protected readonly aria: AriaForwardController;
@@ -95,18 +116,63 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * own search boxes would be three copies of one field.
      */
     filterable: boolean;
+    /**
+     * How long typing in the filter field rests before the list is filtered, in
+     * milliseconds. `0` filters on every keystroke.
+     *
+     * For a list filtered on a server, where `helix-filter` starts a request: a
+     * reader typing a word sends one request for the word, not one for each
+     * letter. Enter and the arrow keys filter at once on what is typed, so they
+     * act on the list the reader expects.
+     */
+    filterDelay: number;
     /**
      * Placeholder text for the filter field.
      */
     filterLabel: string;
+    /**
+     * Stops the arrow keys from choosing each option they move to. Enter, Space
+     * or a click chooses the highlighted option.
+     *
+     * By default a single-choice list chooses as the arrows move, as a radio
+     * group does. Select and Time Input set this on the list in their panel, so
+     * a reader can move through the options before closing the panel on one.
+     */
+    manual: boolean;
     /**
      * Whether more than one option can be chosen.
      */
     multiple: boolean;
+    /**
+     * What a screen reader hears when a filter leaves one option. `{count}` is
+     * the count.
+     */
+    resultLabel: string;
+    /**
+     * What a screen reader hears when a filter leaves any other number of
+     * options. `{count}` is the count.
+     *
+     * **Two sentences, chosen by `Intl.PluralRules`**, which is Data Table's
+     * pair: a language with more forms than two picks the one for its `one` and
+     * writes the rest here.
+     */
+    resultsLabel: string;
     /**
      * Which option the keyboard is on, which is not what is chosen.
      */
     private activeValue;
+    /**
+     * Whether the highlight was cleared on purpose, so the filter does not put
+     * it back on the first match.
+     */
+    private parked;
+    /** The letters typed at the list, which move the highlight to a match. */
+    private readonly typeahead;
+    /**
+     * The values of the options seen on the last pass, so an option that leaves
+     * can be told apart from one that has not arrived yet.
+     */
+    private seen;
     /**
      * Whether the key being handled was forwarded rather than typed into this.
      *
@@ -150,6 +216,38 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      */
     get selectedIndex(): number;
     set selectedIndex(at: number);
+    /**
+     * @internal Moves the highlight without choosing, for the control that owns
+     * this list: to the first or last option a reader can reach, to the chosen
+     * one (or the first where none is), or nowhere.
+     *
+     * Select opens its panel on the chosen option, or on the last one for
+     * ArrowUp, and Combobox moves the highlight off the list onto its create row.
+     */
+    highlight(where: 'first' | 'last' | 'none' | 'selected'): void;
+    /**
+     * Says how many options a filter left, in the live region.
+     *
+     * **A reader typing into a filter cannot see the list narrow**, and React
+     * Aria and Web Awesome both say the count as it changes. Only "No matches"
+     * was said here, so a query that left forty options and one that left one
+     * sounded the same. Said when the filter changes and the count with it, so
+     * a keystroke that leaves the same options says nothing new. An empty filter
+     * says nothing, being the list as it was given; no matches is `empty-text`,
+     * which the region says in place of this.
+     */
+    private tell;
+    /**
+     * @internal Moves the highlight to the option whose words start with the
+     * letters typed, and returns its value, or nothing where none matches.
+     *
+     * For a control that takes the letters while this list is not where focus
+     * is: Select's closed trigger chooses the option this returns, as a native
+     * `<select>` does.
+     */
+    typeaheadTo(key: string): string | undefined;
+    /** @internal Whether letters typed in the last moment are still one search. */
+    get typing(): boolean;
     /**
      * The kind of list, as the platform names it: `select-one` or
      * `select-multiple`.
@@ -196,8 +294,37 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * Space and Enter are how a multi-select list chooses, and they are also how
      * a single-select one confirms what the arrows already did, so they act
      * either way rather than being guarded on `multiple`.
+     *
+     * **A reader in a text field is typing.** That is a filter field of this
+     * list's own, or a combobox's field that forwards its keys through
+     * `navigate`. There a Space is a character, Home and End move the caret, and
+     * a letter is a letter. Measured before this: a Space typed into a filter,
+     * a combobox or a command palette chose the highlighted option and closed the
+     * panel, so a query of two words could not be typed.
      */
     private readonly handleKeydown;
+    /**
+     * Puts the highlight on an option, and chooses it where moving is choosing.
+     *
+     * Chosen on the way past only where moving is choosing. With `multiple` a
+     * reader passing over four options on the way to the fifth did not mean to
+     * pick all five, and with `manual` the owner has asked for the same.
+     *
+     * Nor where the keys were forwarded. A list with the focus on it selects as
+     * it moves, which is the pattern for a listbox; a combobox's arrows move the
+     * highlight and Enter takes it, which is the pattern for a combobox, and the
+     * two differ by exactly which element the reader is in. Measured before
+     * this: the first Down in a combobox committed the second option and shut the
+     * panel, one keystroke into the interaction.
+     */
+    private arrive;
+    /**
+     * How many rows PageUp and PageDown move: as many as the list shows at once.
+     *
+     * Measured off the rendered list and its first shown row. Where there is no
+     * layout to measure, as on a server or in a test double, it is ten.
+     */
+    private pageSize;
     /**
      * Runs the list's own key handling for a caller whose focus is elsewhere.
      *
@@ -215,8 +342,9 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * flag is set here rather than exposed as a property. The difference between
      * a listbox and a combobox is not a mode a consumer picks: it is which
      * element the reader's focus is in, and that is exactly what calling this
-     * rather than being typed into means. Enter and Space still choose, because
-     * those are the caller asking for the answer rather than for a move.
+     * rather than being typed into means. Enter still chooses, because that is
+     * the caller asking for the answer rather than for a move. Space, Home, End
+     * and letters are left to the caller's field, where they are typing.
      */
     navigate(event: KeyboardEvent): void;
     /**
@@ -236,6 +364,25 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
     reveal(): void;
     /** Hides what the filter excludes, and writes the rest onto the options. */
     private place;
+    /**
+     * Whether another Helix component renders this list and binds its value
+     * down, as Select, Combobox, Command and Time Picker do. That component seeds
+     * and corrects the value, so this list leaves both to it.
+     *
+     * By the tag rather than by `instanceof`, for the reason `optionsAmong`
+     * gives: a second copy of the library on a page is a second class.
+     */
+    private get owned();
+    /**
+     * Takes an option that has left the list out of the value.
+     *
+     * Only one that was here before: a value set ahead of its options, which a
+     * list loading them from a server does, is kept until they arrive. Measured
+     * before this: removing the chosen option left the list showing nothing
+     * chosen while its form still submitted the removed value. A native
+     * `<select>` drops it too, and sends no event for it.
+     */
+    private forgetRemoved;
     /** Scrolls the active option into view, which needs the rendered list to scroll. */
     private followActive;
     /** Reports the answer and the verdict on it. */
@@ -243,6 +390,16 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Takes `<helix-option selected>` as the list's default value, as a native
+     * `<select>` takes `<option selected>`.
+     *
+     * Only where the list declares no `default-value` of its own, which wins. A
+     * form reset returns to it, which is what `Option.defaultSelected` says.
+     * Read from the options once they are known, so a list served by a server
+     * shows the choice from hydration on.
+     */
+    private seedDeclared;
     /**
      * Where the reader is, and failing that where the answer is.
      *
@@ -267,6 +424,12 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * their answer moved when it did not is worse than telling them nothing.
      */
     private readonly handleFilter;
+    /** The filter waiting out `filterDelay`, if any. */
+    private readonly filtering;
+    /** Filters on what the field holds, and puts the field back where that was refused. */
+    private takeFilter;
+    /** Filters at once on a filter still waiting out `filterDelay`. */
+    private flushFilter;
     /** Requests a new filter, and returns whether the request went through. */
     requestFilter(next: string): boolean;
     /**
@@ -305,6 +468,23 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * cannot change.
      */
     protected renderFilterIcon(): TemplateResult;
+    /**
+     * Whether there is anything to show.
+     *
+     * Showing nothing is not the same as empty. A filter that hides every option
+     * is empty, and one with no filter and no options is empty too, but a list
+     * still waiting on its options is neither.
+     */
+    private get showsOptions();
+    /**
+     * The empty or loading line, with a slot for each so either can be richer
+     * than its text.
+     *
+     * **The text is the slot's fallback**, which is this library's rule for a
+     * content property, so `empty-text` still shows where nothing is slotted and
+     * the live region still says it.
+     */
+    protected renderStatus(hasContent: boolean): TemplateResult | typeof nothing;
     protected render(): TemplateResult;
 }
 declare global {