@fusion.dev/helix-headless 0.1.0 → 0.3.0

package/dist/combobox/root/combobox-root.js

@@ -10,259 +10,31 @@ import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html } from 'lit/static-html.js';
-/* Side-effect import, because this renders a listbox in its own shadow root and
-   a custom element registers on import. The path is relative, so this registers
-   the base listbox and the styled file's identical import registers the styled
-   one; `tier` picks which name the template asks for. */
 import '../../listbox/index.js';
-/* And the tags, for the same reason: `multiple` renders one per chosen option
-   and a custom element registers on import. */
 import '../../tag/index.js';
-/**
- * Whether an edit added characters rather than taking them away.
- *
- * `beforeinput` and `input` both carry `inputType`, and it is the platform's
- * own answer to what the reader just did: `insertText` for typing,
- * `insertFromPaste` for a paste, and one of several `delete*` for the ways of
- * removing. Anything without one is treated as an insertion, because the only
- * events with no `inputType` here are the ones a script dispatches, and a test
- * or a consumer setting the value means it to behave like typing.
- */
 const isInsertion = (event) => !event.inputType?.startsWith('delete');
-/**
- * @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. 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.
- *
- * **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.
- * @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.
- */
 let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerOpen(MixinControllerValue(MixinField(HelixFormElement))) {
     constructor() {
         super(...arguments);
-        /* A consumer's `aria-describedby` names ids in their own tree and the control
-           is in this shadow root, so the reference has to be carried down as an
-           element rather than copied as an id. See `AriaForwardController`: measured
-           in Chrome's own tree, the host held the description and the control the
-           reader is actually on was exposed without it. */
         this.aria = new AriaForwardController(this, {
             target: () => this.renderRoot?.querySelector('[part="control"]') ?? null,
         });
-        /**
-         * 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.
-         */
         this.autocomplete = 'off';
-        /**
-         * 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.
-         */
         this.creatable = false;
-        /**
-         * What the create row says, before the words it would add.
-         */
         this.createLabel = 'Add';
-        /**
-         * Words shown where the filter has hidden everything.
-         */
         this.emptyText = 'No matches';
-        /**
-         * Accessible name for the list, which has no visible one of its own.
-         */
         this.listLabel = 'Options';
-        /**
-         * 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.
-         */
         this.loading = false;
-        /**
-         * What the list says while they are on their way.
-         */
         this.loadingText = 'Loading';
-        /**
-         * 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.
-         */
         this.maxTags = 0;
-        /**
-         * 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.
-         */
         this.multiple = false;
-        /**
-         * Text shown while nothing has been chosen.
-         */
         this.placeholder = '';
-        /**
-         * What a tag's remove control is called, since the mark has no name.
-         */
         this.removeLabel = 'Remove';
-        /**
-         * 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.
-         */
         this.suggest = false;
-        /**
-         * 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.
-         */
         this.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.
-         */
         this.suggestion = '';
         this.panel = new PopoverController(this, {
             anchor: () => this.renderRoot?.querySelector('[part="field"]'),
-            /* The surface *and* the field. Scoped to the surface alone, a press on the
-               field counts as outside, so `pointerdown` closes the panel and the
-               field's own handler reopens it on the `click` that follows. */
             boundary: () => [
                 this.renderRoot?.querySelector('[part="surface"]'),
                 this.renderRoot?.querySelector('[part="field"]'),
@@ -273,33 +45,16 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
             surface: () => this.renderRoot?.querySelector('[part="surface"]'),
         });
         this.handleInput = (event) => {
-            // Stopped for the reason `Input.handleInput` gives: the inner control's own
-            // `input` is composed and would reach a consumer beside this element's.
             event.stopPropagation();
             const typed = event.target.value;
             this.typed = typed;
-            /* The list is narrowed before the completion is looked for, because the
-               completion is the first thing still showing and that is not known until
-               the filter has run. */
             this.listbox?.requestFilter(typed);
             this.suggestion = this.suggest && isInsertion(event) ? this.completionFor(typed) : '';
             if (!this.open) {
                 this.requestOpen(true);
             }
         };
-        /**
-         * 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.
-         */
         this.handleKeydown = (event) => {
-            /* The input carries `disabled` too, so a reader never gets this far: the
-               platform suppresses the event before any listener sees it. Said here
-               anyway, because then the element's own state is what refuses rather than
-               a detail of the node it happens to render, and a consumer dispatching a
-               key at it gets the same answer a reader would. */
             if (this.isDisabled) {
                 return;
             }
@@ -316,14 +71,6 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
                 }
                 return;
             }
-            /* Backspace on an empty field takes the last tag off.
-             *
-             * Only when empty, so it never competes with deleting a character, and
-             * only the last, because that is the one the caret is against. This is the
-             * keyboard's version of pressing a tag's remove control, and without it a
-             * reader who chose four things with the keyboard has to reach for a pointer
-             * to undo one.
-             */
             if (event.key === 'Backspace' && this.multiple && this.typed === '') {
                 const last = this.values.at(-1);
                 if (last !== undefined) {
@@ -332,45 +79,22 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
                 }
                 return;
             }
-            /* Enter with nothing left in the list creates, where there is anything to
-               create. Only then: with matches showing, Enter belongs to whichever one
-               the arrows are on, and a reader pressing it over a highlighted "Rust"
-               meant Rust. The row is still there to be pressed for the other case. */
             if (event.key === 'Enter' && this.creation !== '' && !this.showing) {
                 event.preventDefault();
                 this.create();
                 return;
             }
-            /* Opening on the first arrow, before the list is asked to move: a closed
-               combobox pressed Down should show its options and land on the first,
-               which is one gesture to the reader and two steps here. */
             if (!this.open && (event.key === 'ArrowDown' || event.key === 'ArrowUp')) {
                 this.requestOpen(true);
             }
             this.listbox?.navigate(event);
         };
-        /**
-         * 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.
-         */
         this.handleChange = (event) => {
             event.stopPropagation();
-            /* From the event rather than from the listbox, which is one choice behind:
-               it carries what is being *proposed*, dispatched before it is applied,
-               which is what makes it refusable. The listbox never applies it anyway,
-               since this element passes `.value` down and that is a consumer declaring
-               ownership. */
             const { value } = event.detail;
-            /* And nothing happens on a refusal. Refusing a change should leave the
-               control where it was, not clear the filter and shut the panel as though
-               it had been taken. */
             if (!this.requestValue(value)) {
                 return;
             }
-            // Either way the search is spent: it found what it was for.
             this.typed = '';
             this.suggestion = '';
             this.listbox?.requestFilter('');
@@ -378,24 +102,6 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
                 this.close();
             }
         };
-        /**
-         * Anywhere in the field opens the list, and puts the caret where typing goes.
-         *
-         * On the field rather than on the `<input>`. The caret is a sibling of the
-         * input and so is the tag strip, so a handler on the input alone leaves the
-         * one part of the control that visibly says "this opens" doing nothing.
-         * 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.
-         */
         this.handleFieldClick = (event) => {
             if (this.isDisabled) {
                 return;
@@ -410,21 +116,12 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
                 this.requestOpen(true);
             }
         };
-        /** One tag asking to be taken out of the set. */
         this.handleDismiss = (event) => {
             event.stopPropagation();
             const tag = event.currentTarget;
             this.drop(tag.dataset.value ?? '');
         };
     }
-    /**
-     * 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() {
         return this.listbox?.selectedIndex ?? -1;
     }
@@ -434,63 +131,26 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
             listbox.selectedIndex = at;
         }
     }
-    /** Which kind of chooser this is, in the platform's two words. */
     get type() {
         return this.multiple ? 'select-multiple' : 'select-one';
     }
     get listbox() {
         return this.renderRoot?.querySelector('[part="listbox"]') ?? null;
     }
-    /** The values chosen, in the order they were chosen. */
     get values() {
         return this.value === '' ? [] : this.value.split(',');
     }
-    /**
-     * 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.
-     */
     get chosen() {
         const options = this.listbox?.options ?? [];
-        /* Nothing at all is not the same as nothing matching.
-         *
-         * On the server there are no options to look in, because they are light DOM
-         * children the server cannot see, and before the slot is assigned there are
-         * none either. Falling back there would put the raw value on screen for one
-         * paint and then swap it for the option's words, which reads as the field
-         * correcting a mistake. With options present, a value none of them carries
-         * is a created one, and showing it is the only way to show it at all. */
         const known = options.length > 0;
         const words = new Map(options.map((option) => [option.value, option.text]));
         return this.values
             .filter((value) => known || words.has(value))
             .map((value) => ({ text: words.get(value) ?? value, value }));
     }
-    /**
-     * 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.
-     */
     get showing() {
         return (this.listbox?.options ?? []).some((option) => !option.hidden);
     }
-    /**
-     * 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.
-     */
     get creation() {
         const typed = this.typed.trim();
         if (!this.creatable || typed === '') {
@@ -499,13 +159,6 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
         const exists = (this.listbox?.options ?? []).some((option) => option.text.trim().toLowerCase() === typed.toLowerCase());
         return exists ? '' : typed;
     }
-    /**
-     * 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.
-     */
     create() {
         const wanted = this.creation;
         if (wanted === '') {
@@ -525,26 +178,16 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
             this.close();
         }
     }
-    /** The choices that get a tag, which is all of them until `maxTags` says not. */
     get shown() {
         const held = this.chosen;
         return this.maxTags > 0 ? held.slice(0, this.maxTags) : held;
     }
-    /** How many are held beyond the ones shown. */
     get restCount() {
         return Math.max(0, this.chosen.length - this.shown.length);
     }
-    /** What a single-choice field shows at rest, which the tags replace. */
     get word() {
         return this.chosen[0]?.text ?? '';
     }
-    /**
-     * 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.
-     */
     drop(value) {
         this.requestValue(this.values.filter((one) => one !== value).join(','));
     }
@@ -555,14 +198,6 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
         this.requestOpen(false);
         this.renderRoot.querySelector('[part="control"]')?.focus();
     }
-    /**
-     * 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.
-     */
     completionFor(typed) {
         if (typed === '') {
             return '';
@@ -571,12 +206,6 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
         const match = (this.listbox?.options ?? []).find((option) => !option.hidden && !option.disabled && option.text.toLowerCase().startsWith(needle));
         return match && match.text.length > typed.length ? match.text : '';
     }
-    /**
-     * 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.
-     */
     sync() {
         this.internals.setFormValue(this.value === '' ? null : this.value);
         this.reportRequired(this.value === '', 'Choose one to continue.', 'control');
@@ -588,29 +217,7 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
     updated(changed) {
         super.updated?.(changed);
         this.sync();
-        /* After the render, not during it: the input's value is a binding, so
-           selecting a range of it before Lit has written it selects a range of the
-           previous value.
-         
-           **And written here rather than left to the binding, because the binding
-           stops writing.** Lit dirty-checks a property binding against the value it
-           last wrote, not against the DOM, and typing changes the DOM underneath
-           it. Type `r` into a list holding Ruby and the completion is `Ruby`, so
-           the field is written `Ruby` with `uby` selected. Type `u` and the field
-           is already `Ru` because the browser replaced the selection, and the
-           completion is *still* `Ruby`: unchanged, so Lit writes nothing and
-           `changed.has('suggestion')` is false, so nothing is selected either. The
-           completion then appears on the first character and never again.
-         
-           Reconciled against what the input actually holds, which is the only thing
-           that knows. */
         const control = this.renderRoot.querySelector('[part="control"]');
-        /* The same expression the template binds, because this has to agree with it
-           in both directions. Writing only when there is a completion puts the
-           field right while one is showing and leaves it stale afterwards: this
-           reconcile writes behind Lit's back, so Lit's own dirty-check then
-           believes the DOM already holds whatever it last wrote and declines to
-           correct it. */
         const wanted = this.multiple || this.open ? this.suggestion || this.typed : this.word;
         if (control && control.value !== wanted) {
             control.value = wanted;
@@ -623,28 +230,11 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
         }
         else {
             this.panel.hide();
-            /* And the filter goes with it, for the reason the class note records: a
-               control reopened still narrowed is one whose second use starts from the
-               first one's leftovers.
-      
-               All three, not the listbox's copy alone. A surviving `typed` is
-               invisible on close, because a closed single-choice field shows the
-               chosen words instead, and comes back with the list behind it showing
-               everything the moment it reopens. */
             this.typed = '';
             this.suggestion = '';
             this.listbox?.requestFilter('');
         }
     }
-    /**
-     * 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 replace, wrap
-     * or omit it without reimplementing the whole template. 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.
-     */
     renderListbox() {
         return html `<${this.tag('listbox')}
       part="listbox"
@@ -671,15 +261,6 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
       <slot @slotchange=${() => this.requestUpdate()}></slot>
     </${this.tag('listbox')}>`;
     }
-    /**
-     * 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 replace, wrap
-     * or omit it without reimplementing the whole template. 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.
-     */
     renderTag(option) {
         return html `<${this.tag('tag')}
                     part="tag"
@@ -691,15 +272,6 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
                     >${option.text}</${this.tag('tag')}
                   >`;
     }
-    /**
-     * 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.
-     */
     renderIndicator() {
         return html `<slot name="indicator">
       <svg part="indicator" fill="currentColor" viewBox=${caretDown.viewBox} aria-hidden="true">