@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/listbox/root/listbox-root.js

@@ -11,43 +11,9 @@ import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { HelixHeadlessOptionGroup } from '../../option/group/option-group.js';
 import { HelixHeadlessOption } from '../../option/root/option-root.js';
-/** The keys that move within a list, which is every key that moves at all. */
 const MOVES = new Set(['ArrowDown', 'ArrowUp', 'End', 'Home']);
-/**
- * The ranges each filtering list has matched, so the union can be rebuilt when
- * any one of them changes.
- *
- * `CSS.highlights` is one registry for the whole document, keyed by name, so a
- * second list writing under the same name would erase the first one's marks.
- * Keyed by element and rebuilt from every entry, two filtered lists on a page
- * both stay marked. A `Map` rather than a `WeakMap` because the union has to be
- * walked and a `WeakMap` cannot be, which is why a list takes itself out on
- * disconnect.
- */
 const matched = new Map();
-/** What the marks are called in `CSS.highlights`, and in `preview.css`. */
 const HIGHLIGHT = 'helix-filter-match';
-/*
- * Marks what the filter matched, without touching what it matched it in.
- *
- * The words are the consumer's own light DOM, slotted through as many as two
- * shadow roots, and wrapping the matched part in a `<mark>` would mean this
- * element rewriting their content: markup they wrote would come back changed.
- * The Custom Highlight API paints a range instead. Nothing is inserted and
- * nothing is removed, so an option holding a link or an icon is marked as
- * readily as one holding a bare word.
- *
- * The rule that paints it lives in `preview.css` rather than in a component's
- * styles, which is not a choice either: a highlight is styled from the tree its
- * text lives in, and that text lives in the consumer's document.
- */
-/**
- * Whether this environment can paint a highlight at all.
- *
- * Asked before the ranges are built rather than after: a server, a test
- * environment and an older browser all take that path, and walking every shown
- * option's text nodes for an API that is not there is work with no output.
- */
 const paintable = () => typeof CSS !== 'undefined' && 'highlights' in CSS && typeof Highlight !== 'undefined';
 const paintMatches = () => {
     if (!paintable()) {
@@ -60,14 +26,6 @@ const paintMatches = () => {
     }
     CSS.highlights.set(HIGHLIGHT, new Highlight(...all));
 };
-/**
- * Where a needle sits inside an element, as a range over its text nodes.
- *
- * Walked rather than measured off `textContent`, because the words may be split
- * across several nodes and wrapped in elements of the consumer's, and a match
- * can begin in one node and end in another. The offsets are mapped back onto
- * the nodes they came from, so the range covers the real text either way.
- */
 const rangeFor = (root, needle) => {
     const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT);
     const nodes = [];
@@ -97,159 +55,23 @@ const rangeFor = (root, needle) => {
     }
     return [];
 };
-/**
- * @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 is where
- * focus lives rather than whether moving chooses.** The controller already
- * separates those, taking `origin: 'focus' | 'selection'`. What it cannot do is
- * leave focus alone: `NavigableItem.focusItem()` moves DOM focus to the item,
- * its model being a roving tab stop. A filterable list cannot have that, focus
- * having to stay in the field or typing stops, so what moves is a virtual
- * cursor and `aria-activedescendant` is what says where it is. No flag
- * reconciles the two.
- *
- * **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.
- */
 let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(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="items"]') ?? 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';
-        /**
-         * What to start narrowed to, where nothing declared it.
-         */
         this.defaultFilter = '';
-        /** What the list is narrowed to, whoever set it. */
         this.filterState = undefined;
-        /**
-         * 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.
-         */
         this.emptyText = 'No matches';
-        /**
-         * 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, a combobox and a command palette drawing their
-         * own search boxes would be three copies of one field.
-         */
         this.filterable = false;
-        /**
-         * Placeholder for the field that narrows the list.
-         */
         this.filterLabel = 'Filter';
-        /**
-         * Whether more than one option can be the answer.
-         */
         this.multiple = false;
-        /**
-         * Which option the keyboard is on, which is not what is chosen.
-         */
         this.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.
-         */
         this.forwarded = false;
-        /**
-         * 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
-         * leaves an empty box with no message in it. Written to state instead, which
-         * schedules the one further render that shows it.
-         */
         this.hasMatches = true;
-        /**
-         * 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.
-         */
         this.counted = false;
-        /* Stated once, and the group never thinks about it again. See the
-           controller: cascading by hand from each method that changes the set
-           leaves the paths that reached it differing by component. */
         this.cascade = new DisabledCascadeController(this, {
             items: () => this.options,
         });
@@ -258,13 +80,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             this.activeValue = event.detail.value;
             this.choose(event.detail.value);
         };
-        /**
-         * 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`.
-         */
         this.handleKeydown = (event) => {
             const shown = this.shown.filter((option) => !option.disabled);
             if (shown.length === 0) {
@@ -277,9 +92,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
                 }
                 return;
             }
-            /* The list's own movement keys, plus Enter, which is choosing rather than
-               moving and is still the list's: a reader who has narrowed to one option
-               expects Enter to take it without leaving the field first. */
             if (!MOVES.has(event.key) && event.key !== 'Enter') {
                 return;
             }
@@ -304,30 +116,11 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
                 return;
             }
             this.activeValue = target.value;
-            /* 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.
-        
-               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. */
             if (!this.multiple && !this.forwarded) {
                 this.choose(target.value);
             }
         };
-        /**
-         * 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.
-         */
         this.handleFilter = (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 control = event.target;
             this.requestFilter(control.value);
@@ -335,26 +128,8 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
                 control.value = this.filter;
             }
         };
-        /**
-         * 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.
-         */
         this.handleFilterKeydown = (event) => {
             if (event.key === 'Escape' && this.filter !== '') {
-                /* Stopped and prevented whether or not the clearing stands. The reader
-                   pressed Escape at a filtered list, so the key was for this list either
-                   way, and letting it through to close the surface around it would be a
-                   second thing happening from one press. */
                 event.stopPropagation();
                 event.preventDefault();
                 this.requestFilter('');
@@ -363,35 +138,10 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             if (!MOVES.has(event.key)) {
                 return;
             }
-            /* **Forwarded, because the reader is in the field.** `navigate` says the
-               rule this has to follow: a listbox and a combobox differ by which element
-               the focus is in, not by a mode, and a reader typing into a filter is in
-               the second case whether or not the field belongs to this element. So the
-               arrows move the highlight and Enter takes it, which is what Enter already
-               does by bubbling to the host handler.
-        
-               **Never move focus to `[part="items"]` and re-dispatch the key instead.**
-               Both halves fail: focus on the list means moving chooses, so a single
-               press commits a value the reader was arrowing past, and the original
-               press goes on bubbling to the same host handler the re-dispatch already
-               reached. Measured on a bare `<helix-listbox filterable>`, one Down
-               produced two `helix-change` events and a highlight two rows down.
-        
-               `stopPropagation` is what closes the second half: the field handled the
-               key, so it must not arrive at the host as well. The move keys are the
-               only ones taken, so Enter, Tab and every character still pass. */
             event.stopPropagation();
             this.navigate(event);
         };
     }
-    /**
-     * 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() {
         return this.filterState ?? this.defaultFilter;
     }
@@ -400,18 +150,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         this.filterState = next;
         this.requestUpdate('filter', previous);
     }
-    /**
-     * 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() {
         return this.options.findIndex((option) => option.selected);
     }
@@ -419,34 +157,12 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         const option = this.options[at];
         this.value = option?.value ?? '';
     }
-    /**
-     * 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() {
         return this.multiple ? 'select-multiple' : 'select-one';
     }
-    /**
-     * 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() {
         return this.collect(this.children);
     }
-    /**
-     * Walks the tree, and walks *through* a slot when it meets 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.
-     */
     collect(nodes) {
         const found = [];
         for (const node of nodes) {
@@ -462,7 +178,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         }
         return found;
     }
-    /** The groups, found the same way and for the same reason. */
     get groups() {
         const found = [];
         const walk = (nodes) => {
@@ -481,20 +196,12 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         walk(this.children);
         return found;
     }
-    /** The options a filter has left showing. */
     get shown() {
         return this.options.filter((option) => !option.hidden);
     }
-    /** The chosen values, which is a list whether or not `multiple` is set. */
     get values() {
         return this.value === '' ? [] : this.value.split(',');
     }
-    /**
-     * 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.
-     */
     choose(value) {
         const chosen = this.values;
         const next = this.multiple
@@ -506,31 +213,8 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         if (joined === this.value) {
             return;
         }
-        /* Through the mixin rather than hand-rolled: writing `value` is how a
-           consumer says it is theirs, so a listbox writing its own would take
-           ownership away from them on every change. */
         this.requestValue(joined);
     }
-    /**
-     * 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 reimplement the moving, the wrapping, the skipping of
-     * disabled options and the seeding from the current value.
-     *
-     * 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) {
         this.forwarded = true;
         try {
@@ -540,34 +224,12 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             this.forwarded = false;
         }
     }
-    /**
-     * 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 do 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() {
         const items = this.renderRoot?.querySelector('[part="items"]');
         const chosen = this.options.find((option) => option.selected && !option.hidden);
         if (!items || !chosen) {
             return;
         }
-        /* Twice, and the second pass is not superstition. The first delta is
-           computed against whatever layout is current when this is called, and
-           inside a panel that has just been revealed it is a frame behind: measured,
-           one call landed a whole row short, 672 where 704 was wanted, and calling
-           it again from a settled layout put it exactly on center. Reading a rect
-           forces layout, so the second pass sees the result of the first and
-           corrects the remainder. It stops as soon as there is nothing left to
-           correct, so the usual case is one pass and a cheap check. */
         for (let pass = 0; pass < 2; pass += 1) {
             const box = items.getBoundingClientRect();
             const row = chosen.getBoundingClientRect();
@@ -581,7 +243,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             items.scrollTop += off;
         }
     }
-    /** Hides what the filter excludes, and writes the rest onto the options. */
     place() {
         const needle = this.filter.trim().toLowerCase();
         const chosen = new Set(this.values);
@@ -589,26 +250,10 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             option.hidden = needle !== '' && !option.text.toLowerCase().includes(needle);
             option.selected = chosen.has(option.value);
         }
-        /* A group whose options the filter has all hidden goes with them. CSS
-           cannot do this: a heading and its options are siblings under the group,
-           so the rule would be `:host(:has(...))`, which is dropped at parse time.
-           The listbox can, because it is the thing that did the hiding and already
-           knows which. Left showing, the picture was a heading over nothing, which
-           reads as a group whose contents failed to render. */
         for (const group of this.groups) {
             const inside = this.collect(group.children);
             group.hidden = inside.length > 0 && inside.every((option) => option.hidden);
         }
-        /* The keyboard cannot sit on something the filter has hidden, so it moves
-           to the first thing still showing rather than nowhere: a list whose active
-           option has just been filtered away is a list the next arrow press would
-           start from the top of anyway.
-    
-           But only where there is a filter to have hidden it, or a highlight worth
-           rescuing. Clearing one must not *invent* a highlight out of nothing:
-           measured, a combobox clears its filter as it closes, and that alone
-           parked the highlight on the first option while the panel was shut, so
-           the reader's first Down arrived at the second. */
         const shown = this.shown;
         const rescue = needle !== '' || this.activeValue !== '';
         if (rescue && !shown.some((option) => option.value === this.activeValue)) {
@@ -617,8 +262,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         for (const option of this.options) {
             option.active = option.value === this.activeValue;
         }
-        /* And the marks, from the same needle that did the hiding: the two answers
-           have to come from one place or a list can show a match it does not mark. */
         if (needle === '' || !paintable()) {
             matched.delete(this);
         }
@@ -637,7 +280,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             scrollItemIntoView(active, { padding: 4, ...(items ? { scroller: items } : {}) });
         }
     }
-    /** Reports the answer and the verdict on it. */
     sync() {
         this.internals.setFormValue(this.value === '' ? null : this.value);
         this.reportRequired(this.value === '', 'Choose one to continue.', 'items');
@@ -651,9 +293,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         super.disconnectedCallback();
         this.removeEventListener('helix-select', this.handleSelection);
         this.removeEventListener('keydown', this.handleKeydown);
-        /* Its marks go with it. The registry is the document's and outlives this
-           element, so a list removed while filtered would leave ranges over text
-           that is no longer on the page. */
         matched.delete(this);
         paintMatches();
     }
@@ -662,44 +301,10 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         hostAria(this.internals, { label: this.label, role: 'listbox' });
         this.internals.ariaMultiSelectable = this.multiple ? 'true' : null;
     }
-    /**
-     * 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.
-     *
-     * Read by `linkActive` as well as by the keys, so the option announced and
-     * the option the arrows move from cannot disagree: asking for `activeValue`
-     * alone points `aria-activedescendant` at nothing until a key has moved it.
-     */
     get currentValue() {
         return this.activeValue || (this.value.split(',')[0] ?? '');
     }
-    /*
-     * Points the focused list at the option the keyboard is on.
-     *
-     * **An element reference and not an id, because an IDREF cannot do this.**
-     * The options are the consumer's light DOM and the element that takes focus
-     * is in this shadow root, so `aria-activedescendant="whatever"` resolves
-     * against the shadow tree, finds nothing, and is dropped in silence. Element
-     * references resolve outward: a shadow-tree element may point at a light-DOM
-     * one, which is the direction this needs.
-     *
-     * Feature-tested rather than assumed, for the reason `hostAria` gives:
-     * assigning to a property an engine does not implement is a no-op rather than
-     * an error. Where it is missing the list still works and still announces its
-     * selection; what is lost is the running commentary as the keys move.
-     */
     linkActive() {
-        /* Whichever element the reader is actually in. `aria-activedescendant` is
-           read from the focused element, so pointing the list at the active option
-           says nothing while focus is in the filter, which is where it now stays.
-           A filterable list announces from its field and a plain one from its
-           items, for the same reason the arrows are forwarded in one and not the
-           other. */
         const list = this.renderRoot.querySelector(this.filterable ? '[part="search-field"]' : '[part="items"]');
         if (!list || !('ariaActiveDescendantElement' in list)) {
             return;
@@ -714,7 +319,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         this.linkHost();
         this.linkActive();
     }
-    /** Requests a narrowing, and reports whether the request stood. */
     requestFilter(next) {
         if (next === this.filter) {
             return true;
@@ -730,29 +334,10 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             next,
         });
     }
-    /**
-     * 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 { this.shadowRootOptions = {
         ...HelixFormElement.shadowRootOptions,
         delegatesFocus: true,
     }; }
-    /**
-     * 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.
-     */
     renderFilterIcon() {
         return html `<slot name="filter-icon">
       <svg part="filter-mark" fill="currentColor" viewBox=${magnifyingGlass.viewBox}>
@@ -761,9 +346,6 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
     </slot>`;
     }
     render() {
-        /* One tab stop for the whole list, which is what a listbox is in the tab
-           order: the arrows move within it. `tabindex` on the wrapper rather than
-           the host so the host stays as the consumer wrote it. */
         return html `${this.renderGroupLabel()}
       ${this.filterable
             ? html `<div part="search">
@@ -789,20 +371,11 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         part="items"
         id="items"
         aria-busy=${this.loading ? 'true' : nothing}
-        ${
-        /* `isDisabled`, matching the filter input above it: on `disabled`
-           alone, a listbox in a disabled fieldset keeps its tab stop and
-           takes arrow keys while its own filter is correctly out. */
-        ''}
+        ${''}
         tabindex=${this.isDisabled ? -1 : 0}
       >
         <slot @slotchange=${() => this.place()}></slot>
-        ${
-        /* Loading and empty come from the shared mixin; what is local is what
-           counts as content. A list with a filter that matched nothing is
-           empty, and one with no filter and no options is empty too, but a
-           list still waiting on its options is neither. */
-        this.renderStatus(this.counted && !this.loading
+        ${this.renderStatus(this.counted && !this.loading
             ? this.filter === ''
                 ? this.options.length > 0
                 : this.hasMatches