@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,396 @@
+import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import '../../listbox/index.js';
+import '../../tag/index.js';
+declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
+/**
+ * @summary A field that filters a list as it is typed into.
+ *
+ * @description
+ * **The list is `helix-listbox`, and the filtering is its own.** It already
+ * owns narrowing, the empty state, the highlight, `aria-activedescendant` and
+ * scrolling an option into view, and every one of those is a decision with a
+ * long note attached. Rewriting them here would be a second copy to keep in
+ * step; what is left for this element is the field, the panel and the traffic
+ * between them.
+ *
+ * **The text and the value are two things.** What a reader types is a filter,
+ * not an answer: it narrows the list and is thrown away. The value is whichever
+ * option they then choose, and the field is rewritten to that option's words
+ * once they have. A combobox that treated the typing as the value would submit
+ * "jav" to a form, which is the mistake a plain input makes and the reason this
+ * component exists.
+ *
+ * That is also why the field is emptied of its filter on close rather than left
+ * holding it: a control reopened still narrowed by the last visit's search is a
+ * control whose second use starts from the first one's leftovers. Select
+ * records the same, having been fixed for it.
+ *
+ * **Focus stays in the field, which is the whole of what a combobox is.** The
+ * arrows move the list without leaving the text, which is why the listbox has a
+ * public `navigate`: the moving, the wrapping, the skipping of disabled options
+ * and the seeding from the current value all stay in the one place that already
+ * does them.
+ *
+ * `role="combobox"` on the input rather than on a wrapper, because the thing
+ * the pattern describes is the text field, and `aria-controls` can name the
+ * listbox because both are in this shadow root. The active option cannot be
+ * named that way, being the consumer's light DOM, so it is linked by element
+ * reference for the reason Listbox records at length.
+ *
+ * **With `multiple`, the chosen options are tags in the field.** A field that
+ * says "Rust, Ruby, Go" is a sentence the reader has to parse to find out what
+ * is in it, and offers nothing to press to take one out: Select does that today
+ * and it is the weakest part of it. A tag apiece is one object per answer, each
+ * with its own remove control, which is what the reader already believes they
+ * are looking at.
+ *
+ * The panel stays open while more than one can be chosen, because a control
+ * that shut after each pick is one the reader has to reopen to keep using. The
+ * filter clears on each choice instead, so the next pick starts from the whole
+ * list rather than from the last search.
+ *
+ * **`creatable` announces, and does not write.** The options are the consumer's
+ * light DOM and nothing here puts an element into it: a component that grew the
+ * consumer's markup would be a component their framework re-renders over. What
+ * this does is offer a row saying what would be added, take the value when the
+ * reader presses it, and say so with `helix-create`. A consumer who has to
+ * validate first refuses the event and adds nothing.
+ *
+ * Which leaves a value naming no option, and that is what the words fall back
+ * to: for anything chosen the field shows the option's text if there is one and
+ * the value itself otherwise. No copy is stored, so a consumer who then adds a
+ * real option with that value has its words take over on the next render.
+ *
+ * **`suggest` finishes the word, and only ever forwards.** The field completes
+ * to the first option the typing begins, with the part the reader did not type
+ * selected, so the next character replaces it and Delete removes it. Applied on
+ * insertion alone: completing after a deletion would put back what the reader
+ * just took out, and a field that cannot be shortened is a field that cannot be
+ * corrected. Measured as the difference between `insertText` and the several
+ * `delete*` input types, which is what the platform already says about which
+ * happened.
+ *
+ * The filter stays what was typed rather than what was completed. Filtering on
+ * the completion would narrow the list to the one option it came from, so a
+ * reader typing "ru" would be shown "Rust" alone and never learn Ruby was
+ * there.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category forms
+ * @aliases Autocomplete, Typeahead, Search select
+ * @documentation https://helix.fusion.dev/components/combobox
+ *
+ * @slot - The options, which are `helix-option` elements.
+ * @slot end - After it, for a unit or a clear button.
+ * @slot indicator - Replaces the caret saying the field opens.
+ * @slot start - Before the text, for an icon.
+ *
+ * @event {Event} change - Announced once the value has moved.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the chosen option changes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixCreateEvent} helix-create - Fired when the reader asks for something the list does not hold, and cancelable.
+ * @event {Event} input - Announced once the value has moved.
+ * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ *
+ * @csspart control - The text field itself.
+ * @csspart create - The row offering to add what was typed.
+ * @csspart feedback - What is wrong with it.
+ * @csspart field - The box around the text and its marks.
+ * @csspart hint - Help under the field, while nothing is wrong.
+ * @csspart indicator - The caret.
+ * @csspart label - The question, over the field.
+ * @csspart listbox - The list inside it.
+ * @csspart listbox-empty - Shown when a filter has hidden everything.
+ * @csspart listbox-feedback - What is wrong with it.
+ * @csspart listbox-filter-icon - The mark beside that field.
+ * @csspart listbox-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart listbox-hint - Help under the list.
+ * @csspart listbox-items - The list itself.
+ * @csspart listbox-label - The question, over the list.
+ * @csspart listbox-loading - Shown while the options are still on their way.
+ * from the listbox.
+ * @csspart listbox-search - The region holding the field that narrows the list.
+ * @csspart listbox-search-field - The field itself.
+ * @csspart rest - The count of choices held beyond `max-tags`.
+ * @csspart surface - The floating panel.
+ * @csspart tag - One chosen option.
+ * @csspart tag-dismiss - The remove button, when `dismissible`.
+ * @csspart tag-dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart tag-prefix - The category before the label.
+ * @csspart tags - The row of chosen options, when `multiple` is set.
+ */
+export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_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;
+    /**
+     * Text shown while nothing has been chosen.
+     */
+    placeholder: string;
+    /**
+     * Whether more than one option can be chosen.
+     *
+     * The list already does the work: `value` comes apart on commas, a press
+     * toggles rather than replaces, and the arrows move without choosing. What
+     * this adds is the tags, and keeping the panel open between picks.
+     *
+     * A comma is therefore not available inside an option's value, which is the
+     * listbox's contract and not this element's to change.
+     */
+    multiple: boolean;
+    /**
+     * Whether the reader may answer with something the list does not hold.
+     *
+     * The row appears while what is typed matches no option's words exactly, so
+     * it is offered next to near misses too: a reader typing "Ruby on Rails" with
+     * "Ruby" in the list wants the one they are typing, not the one they are
+     * halfway through.
+     */
+    creatable: boolean;
+    /**
+     * Whether the field finishes the word as it is typed.
+     *
+     * `suggest` rather than `autocomplete`, which is a real HTML attribute this
+     * element already sets on the input it renders, and two things of one name
+     * meaning different things on the same control is a question a consumer
+     * should not have to ask.
+     */
+    suggest: boolean;
+    /**
+     * What the create row says, before the words it would add.
+     */
+    createLabel: string;
+    /**
+     * What a tag's remove control is called, since the mark has no name.
+     */
+    removeLabel: string;
+    /**
+     * How many tags to draw before the rest become a count. `multiple` only.
+     *
+     * `0` is all of them, and is the default: a cap that guesses is worse than no
+     * cap, because the number that fits depends on the width of the field and the
+     * length of what is in it, neither of which this element knows. What a cap is
+     * genuinely for is a field in a row or a table cell, where a set of twelve
+     * choices would push everything below it down a line at a time.
+     *
+     * The remainder is counted rather than hidden. `+3` is a fact a reader can act
+     * on, where a row that silently stops is a field that appears to have lost
+     * what was put in it. Date Input and Time Input carry the same property and
+     * the same reasoning.
+     */
+    maxTags: number;
+    /**
+     * Accessible name for the list, which has no visible one of its own.
+     */
+    listLabel: string;
+    /**
+     * Whether the options are still on their way.
+     *
+     * Passed straight to the list, which is where the rows are and so where the
+     * message belongs.
+     */
+    loading: boolean;
+    /**
+     * What the list says while they are on their way.
+     */
+    loadingText: string;
+    /**
+     * Words shown where the filter has hidden everything.
+     */
+    emptyText: string;
+    /**
+     * What the reader has typed, which narrows the list and is not the value.
+     *
+     * State rather than a property, because it is a keystroke rather than API: a
+     * consumer sets `value` to say what is chosen, and nothing outside needs to
+     * say what is half-typed.
+     */
+    private typed;
+    /**
+     * The completed words, where the field is finishing one, and empty otherwise.
+     *
+     * Held apart from `typed` rather than replacing it, because they are needed
+     * for different things at the same moment: this one is what the input shows,
+     * `typed` is what the list is filtered by, and the selection between them is
+     * what the reader is offered.
+     */
+    private suggestion;
+    /**
+     * Which option is chosen, as an index, or `-1` where none is.
+     *
+     * Read off the listbox this renders, which owns the options and is where the
+     * same two properties are implemented. Delegating rather than recomputing is
+     * what keeps a composed control and the control inside it from answering
+     * differently: they are one chooser to a consumer.
+     */
+    get selectedIndex(): number;
+    set selectedIndex(at: number);
+    /** Which kind of chooser this is, in the platform's two words. */
+    get type(): string;
+    private get listbox();
+    protected readonly panel: PopoverController;
+    /** The values chosen, in the order they were chosen. */
+    private get values();
+    /**
+     * The chosen options themselves, for their words.
+     *
+     * Read off the options rather than stored, because the words are the
+     * consumer's content and a copy of them goes stale the moment they change it.
+     * Select records the same.
+     *
+     * In the value's own order, which is the order they were chosen. It has to
+     * be: a created answer is not in the list at all, so there is no position in
+     * the list to give it. Neither order ever reshuffles what is already there,
+     * so a tag does not move out from under the pointer about to remove it.
+     */
+    private get chosen();
+    /**
+     * Whether the filter has left anything to choose.
+     *
+     * Read off the options rather than asked of the listbox, which keeps its own
+     * answer to this private. Both come from the same place: `hidden` is what the
+     * filter writes onto an option, and it is public because hiding one by hand
+     * is a thing a consumer may do.
+     */
+    private get showing();
+    /**
+     * What the create row would add, or nothing where there is nothing to add.
+     *
+     * Empty where the words already name an option exactly, case aside: offering
+     * to add "Rust" under a list showing "Rust" is offering the reader a second
+     * copy of what they are looking at.
+     */
+    private get creation();
+    /**
+     * Takes what the reader typed as an answer, once anyone listening allows it.
+     *
+     * Added to the set with `multiple` and replacing it without, which is the
+     * same rule choosing an option follows: what differs about a created answer
+     * is where it came from, not how many the field holds.
+     */
+    private create;
+    /** The choices that get a tag, which is all of them until `maxTags` says not. */
+    private get shown();
+    /** How many are held beyond the ones shown. */
+    private get restCount();
+    /** What a single-choice field shows at rest, which the tags replace. */
+    private get word();
+    /**
+     * Takes one value out of the set, which is what a tag's remove control does.
+     *
+     * `drop` rather than `remove`, which every element already has: `Element`
+     * defines `remove()` and a method of that name here would be overriding it,
+     * so `combobox.remove()` would stop taking the combobox out of the document.
+     */
+    private drop;
+    private close;
+    private readonly handleInput;
+    /**
+     * The words of the first option the typing begins, or nothing.
+     *
+     * Case-insensitively matched and returned in the option's own case, so a
+     * reader typing "ru" is offered "Rust" rather than "rust": the completion is
+     * a name from the list, and correcting the reader's capitals to match it is
+     * the whole point of showing it.
+     */
+    private completionFor;
+    /**
+     * The keys the field answers, and the ones it hands on.
+     *
+     * Everything that moves within the list goes to the list, which is what
+     * `navigate` is for. Escape and Tab are the field's, because they are about
+     * the panel rather than about the options in it.
+     */
+    private readonly handleKeydown;
+    /**
+     * Takes what the list announced and stops it there.
+     *
+     * The listbox says `helix-before-change` under its own name, and a consumer
+     * listening on this element would otherwise hear two changes for one choice,
+     * one of them naming a control they did not put on the page.
+     */
+    private readonly handleChange;
+    /**
+     * Anywhere in the field opens the list, and puts the caret where typing goes.
+     *
+     * On the field rather than on the `<input>`, which is where it was. The caret
+     * is a sibling of the input and so is the tag strip, so pressing the one part
+     * of the control that visibly says "this opens" did nothing at all, and a
+     * reader who wanted the list had to find the text box. Anything drawn inside
+     * the field is the field.
+     *
+     * A tag is the exception, because a tag is its own control: its dismiss
+     * removes a choice, and opening the list on the way past would leave the
+     * reader looking at a panel they did not ask for. Read from the composed
+     * path, since the press lands on a button inside the tag's shadow root and
+     * the event has retargeted by the time it arrives here.
+     *
+     * It only ever opens. Closing is Escape, a choice, or leaving, which is what
+     * the input already did and what a text field wants: a control that closed
+     * when you clicked into the middle of your own typing would be unusable.
+     */
+    private readonly handleFieldClick;
+    /** One tag asking to be taken out of the set. */
+    private readonly handleDismiss;
+    /**
+     * Reports the answer and the verdict on it.
+     *
+     * The value rather than the typed text, which is the whole point of the
+     * component: a form that received "jav" got the filter, not an option.
+     */
+    private sync;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * The list the field filters, behind a seam the styled tier can move.
+     *
+     * A method rather than a fragment inline, so a tier above can render its own,
+     * wrap this one, pass it a property the base does not know about, or leave it
+     * out, without reimplementing the whole template to do any of them. The tag is
+     * interpolated rather than written, so `tier` resolves it: this renders the
+     * headless element, and a styled subclass that sets `tier` renders the styled one
+     * from the same template.
+     */
+    protected renderListbox(): TemplateResult;
+    /**
+     * One chosen option, as a tag, behind a seam the styled tier can move.
+     *
+     * A method rather than a fragment inline, so a tier above can render its own,
+     * wrap this one, pass it a property the base does not know about, or leave it
+     * out, without reimplementing the whole template to do any of them. The tag is
+     * interpolated rather than written, so `tier` resolves it: this renders the
+     * headless element, and a styled subclass that sets `tier` renders the styled one
+     * from the same template.
+     */
+    protected renderTag(option: {
+        text: string;
+        value: string;
+    }): TemplateResult;
+    /**
+     * The caret saying the field opens, 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 renderIndicator(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-combobox': HelixHeadlessCombobox;
+    }
+}
+export {};