@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,357 @@
+import { AriaForwardController, DisabledCascadeController, HelixFormElement } from '@fusion.dev/helix-core';
+import { 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;
+/**
+ * @summary A list of options, one or several of which are the answer.
+ *
+ * @description
+ * **The listbox is the control and the options are its vocabulary.** A Select
+ * is this with a trigger in front of it, a Combobox is this with a text input,
+ * and a command palette is this again: they differ in what opens the list and
+ * what filters it, not in what the list is. Building it as its own family is
+ * what stops each of those reimplementing the keyboard and the filtering.
+ *
+ * **`value` is comma separated when `multiple` is set**, the way
+ * `Checkbox.Group`'s is. It stays a string because that is what a form submits
+ * and what `MixinControllerValue` holds; an array property would be a second
+ * shape for the same fact, and the two would disagree the first time one was
+ * set without the other.
+ *
+ * **Chosen and active are two different things.** Chosen is the answer; active
+ * is where the keyboard is. In a single-select list they move together, which
+ * is the radio group pattern and is what a reader expects from arrow keys. With
+ * `multiple` they come apart: the arrows move without choosing and Space
+ * chooses, because a reader passing over four options on the way to the fifth
+ * did not mean to pick all five.
+ *
+ * **This does not use `KeyboardNavigationController`, and the reason given here
+ * was the wrong one.** It said the controller moves and chooses in one act by
+ * design, so half of this component needed that and half the opposite. The
+ * controller does not work that way: it takes `origin: 'focus' | 'selection'`,
+ * and `focus` exists precisely so a reader can arrow without choosing, which is
+ * what `Tabs` uses in `manual` mode. `focusItem()` and `select()` are separate
+ * members of `NavigableItem`. The incompatibility named above is one the
+ * controller had already solved.
+ *
+ * The real one is where focus lives. `NavigableItem.focusItem()` moves DOM
+ * focus to the item, because the controller's model is a roving tab stop. A
+ * filterable list cannot do that: focus has to stay in the field or typing
+ * stops, so what moves is a virtual cursor and `aria-activedescendant` is what
+ * says where it is. Those two disagree about the one thing neither can
+ * abstract, and no flag reconciles them.
+ *
+ * Worth keeping the distinction sharp, because the old wording invites the
+ * wrong fix: someone reading it would add `origin` to the controller, find it
+ * already there, and conclude this component could adopt it.
+ *
+ * **Filtering hides rather than removes.** An option the filter has hidden is
+ * still the consumer's element in the consumer's order, so a filter that clears
+ * puts the list back exactly as it was with nothing re-rendered. What counts as
+ * a match is a plain case-insensitive substring, and a consumer wanting more
+ * hides options itself: `filter` is a convenience over the same `hidden` the
+ * component uses.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Options, Select list
+ * @documentation https://helix.fusion.dev/components/listbox
+ *
+ * @slot - The options, and any groups of them.
+ * @slot hint - Richer than a string.
+ * @slot label - Richer than a string.
+ *
+ * @event {Event} change - Announced once the value has moved.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired when the answer changes, and cancelable.
+ * @event {HelixFilterEvent} helix-filter - Fired before the list narrows, and cancelable.
+ * @event {Event} input - Announced once the value has moved.
+ *
+ * @csspart empty - Shown when a filter has hidden everything.
+ * @csspart feedback - What is wrong with it.
+ * @csspart filter-icon - The mark beside that field.
+ * @csspart filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart hint - Help under the list.
+ * @csspart items - The list itself.
+ * @csspart label - The question, over the list.
+ * @csspart loading - Shown while the options are still on their way.
+ * @csspart search - The region holding the field that narrows the list.
+ * @csspart search-field - The field itself.
+ */
+export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
+    protected readonly aria: AriaForwardController;
+    /**
+     * What the browser may autofill in the text field, as a platform token.
+     *
+     * **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.
+     */
+    autocomplete: string;
+    /**
+     * What the list is narrowed to, if anything.
+     *
+     * Filtering hides rather than removes, so nothing about the value changes and
+     * the list is still the consumer's own elements in their own order. Reading
+     * gives what is being filtered on; writing declares it theirs, and
+     * `default-filter` seeds one the list owns.
+     *
+     *
+     */
+    get filter(): string;
+    set filter(next: string);
+    /**
+     * What to start narrowed to, where nothing declared it.
+     */
+    defaultFilter: string;
+    /** What the list is narrowed to, whoever set it. */
+    private filterState;
+    /**
+     * Whether the list renders a field for narrowing itself.
+     *
+     * The field lives here rather than in whatever frames the list, because the
+     * filtering already does: `filter`, the empty state and the keyboard are all
+     * this component's. A select that drew its own search box above a listbox
+     * would be writing the same field again, and so would a combobox, and so
+     * would a command palette, which is the fault the three-family split exists
+     * to prevent.
+     */
+    filterable: boolean;
+    /**
+     * Placeholder for the field that narrows the list.
+     */
+    filterLabel: string;
+    /**
+     * Whether more than one option can be the answer.
+     */
+    multiple: boolean;
+    /**
+     * What is shown when a filter has hidden every option.
+     *
+     * From `MixinCollection`, which every collection in the library now shares,
+     * and re-declared here only to keep this list's own wording: "No matches" is
+     * about a filter, and the mixin's "Nothing to show" is about a list that was
+     * never given anything.
+     */
+    emptyText: string;
+    /**
+     * Which option the keyboard is on, which is not what is chosen.
+     */
+    private activeValue;
+    /**
+     * Whether the key being handled was forwarded rather than typed into this.
+     *
+     * Plain state rather than reactive: it is set and cleared inside one
+     * synchronous call, so nothing renders while it is true and nothing outside
+     * can observe it.
+     */
+    private forwarded;
+    /**
+     * Whether anything survived the filter, kept as state rather than counted at
+     * render time.
+     *
+     * Counting during render reads the hiding from the *previous* pass, because
+     * hiding happens in `updated` against options that are the consumer's
+     * elements rather than this component's markup. So a filter matching nothing
+     * rendered the full list, hid every option, and left an empty box with no
+     * message in it: the count was right one pass too late. Written to state
+     * instead, which schedules the one further render that shows it.
+     */
+    private hasMatches;
+    /**
+     * Whether the options have been looked at yet.
+     *
+     * Emptiness is a fact about light DOM children, and the server has none to
+     * 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` runs from `updated`, which the server never reaches, so
+     * this is false exactly when the answer is unknown.
+     */
+    private counted;
+    protected readonly cascade: DisabledCascadeController;
+    /**
+     * Which option is chosen, as an index, or `-1` where none is.
+     *
+     * `<select>`'s own pair, and this control is what stands in for one. The
+     * options are the consumer's own light-DOM children, so an index is a
+     * position among the elements they wrote rather than into anything this
+     * renders, which is what makes it the same number `<select>` would give.
+     *
+     * With `multiple` it is the first chosen one, which is also what the platform
+     * answers: a single index cannot describe a set, and `value` is the property
+     * that can.
+     */
+    get selectedIndex(): number;
+    set selectedIndex(at: number);
+    /**
+     * Which kind of chooser this is, in the platform's two words.
+     *
+     * Derived rather than declared, because `multiple` already decides it and a
+     * second property could disagree.
+     */
+    get type(): string;
+    /**
+     * Every option, in the order a reader meets them.
+     *
+     * Descendants rather than children, because a group puts a level between the
+     * list and its options and the keyboard has to move through a grouped list
+     * exactly as it moves through a flat one.
+     */
+    get options(): HelixHeadlessOption[];
+    /**
+     * Walks the tree, and walks *through* a slot when it meets one.
+     *
+     * Descendants rather than children, because a group puts a level between the
+     * list and its options and the keyboard has to move through a grouped list
+     * exactly as it moves through a flat one.
+     *
+     * Through a slot because that is how this gets composed. `Select` renders a
+     * listbox in its own shadow root with a slot inside it, so the options are
+     * the *select's* light DOM and the listbox's only child is the slot: a plain
+     * `querySelectorAll` finds the slot and no options at all, and the whole
+     * component comes up empty. Found the first time the two were put together,
+     * which is the argument for building the pieces separately rather than
+     * discovering it inside a finished Select.
+     */
+    private collect;
+    /** The groups, found the same way and for the same reason. */
+    private get groups();
+    /** The options a filter has left showing. */
+    private get shown();
+    /** The chosen values, which is a list whether or not `multiple` is set. */
+    get values(): string[];
+    /**
+     * Applies a choice, announcing first so a listener can refuse it.
+     *
+     * With `multiple` a choice is a toggle, because the same press has to be able
+     * to take an answer back; without it a choice replaces whatever was there.
+     */
+    private choose;
+    private readonly handleSelection;
+    /**
+     * Moves the keyboard, and chooses with it only where that is the pattern.
+     *
+     * 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`.
+     */
+    private readonly handleKeydown;
+    /**
+     * Runs the list's own key handling for a caller whose focus is elsewhere.
+     *
+     * A combobox keeps focus in its text field, because that is the whole of what
+     * a combobox is, and still has to move this list with the arrows. Without
+     * this it would have to reimplement the moving, the wrapping, the skipping of
+     * disabled options and the seeding from the current value, and the second
+     * copy would drift from this one the first time either changed.
+     *
+     * Public and taking the event rather than a direction, so a caller forwards
+     * what it received and this decides what the key means. `preventDefault` is
+     * called in here on the keys it acts on, so a caller can hand over every
+     * keydown and let the list ignore the ones that are not its business.
+     *
+     * The entry point is also what says whether moving chooses, which is why the
+     * 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.
+     */
+    navigate(event: KeyboardEvent): void;
+    /**
+     * Brings the chosen option to rest in the middle of the list.
+     *
+     * 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
+     * already manages that: centering is what a caller wants when the list is being
+     * read as a dial rather than scanned as a list, which is what Time Picker's wheels
+     * does 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.
+     */
+    reveal(): void;
+    /** Hides what the filter excludes, and writes the rest onto the options. */
+    private place;
+    /** Reports the answer and the verdict on it. */
+    private sync;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Where the reader is, and failing that where the answer is.
+     *
+     * `activeValue` starts empty, so the first arrow press in a list that already
+     * has a chosen option started from nowhere: Down went to the first option,
+     * which is a move backwards from anything below it, and Up went to the last.
+     * Seeding from the value means the first press moves from what the reader can
+     * see is selected.
+     *
+     * **The keyboard knew this and the announcement did not.** `linkActive` asked
+     * for `activeValue` alone, so a list that had been given a value and not yet
+     * arrowed through pointed `aria-activedescendant` at nothing: a screen reader
+     * was told the list and its selection, and nothing about where the cursor
+     * was, until a key moved it. Both read this now, so the thing announced and
+     * the thing the arrows move from cannot disagree.
+     */
+    private get currentValue();
+    private linkActive;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Narrows the list as the reader types, announcing it first.
+     *
+     * `helix-filter` and not `helix-change`, because nothing about the value
+     * changes: the options are hidden rather than removed, and telling a consumer
+     * their answer moved when it did not is worse than telling them nothing. It
+     * told them nothing before this.
+     */
+    private readonly handleFilter;
+    /** Requests a narrowing, and reports whether the request stood. */
+    requestFilter(next: string): boolean;
+    /**
+     * Sends the keys that belong to the list to the list.
+     *
+     * A reader filtering is still choosing: they type two letters and press Down
+     * to reach what is left, and the field would otherwise swallow it because the
+     * arrows move a caret. Typing keys stay with the field, which is what makes
+     * this different from forwarding everything.
+     *
+     * Escape clears rather than closing. What frames the list may close on Escape
+     * too, so this stops the event when there is something to clear: one press
+     * empties the filter, a second reaches whatever is above and closes it. A
+     * filter that closed the panel would lose the reader's place for a keystroke
+     * they meant as an undo.
+     */
+    private readonly handleFilterKeydown;
+    /**
+     * Focusing the host focuses the list inside it.
+     *
+     * The focusable node is `[part="items"]`, a div in this shadow root, and a
+     * caller outside has no way to reach it: `select` opened its panel and called
+     * `.focus()` on this element, which is not focusable, so focus stayed on the
+     * trigger and the arrow keys never reached the options at all. Delegation is
+     * the platform answering that, and it keeps `document.activeElement` on the
+     * host, which is what a caller reasons about.
+     */
+    static shadowRootOptions: ShadowRootInit;
+    /**
+     * The mark in the filter's field, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding. Those answer different people: the
+     * slot is for the page and the method is for whoever is building the styled
+     * layer, and a fallback with only the first is one a tier can restyle and
+     * cannot change.
+     */
+    protected renderFilterIcon(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-listbox': HelixHeadlessListbox;
+    }
+}
+export {};