@fusion.dev/helix-headless 0.22.0 → 0.24.0

package/dist/filter-input/root/filter-input-root.d.ts

@@ -1,5 +1,6 @@
 import { AriaForwardController, HelixFormElement, PopoverController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
+import type { HelixHeadlessFilterField } from '../field/filter-field.js';
 declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinTokensInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
  * @summary A field that narrows something else, beside what is already narrowing it.
@@ -22,13 +23,32 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * `helix-dismiss` its own remove control fires, so a consumer who handled the
  * pointer has already handled the keyboard.
  *
- * **It can suggest what to type next, and it never learns the grammar.** Slot
- * `helix-option` elements into `suggestions` and the field shows them, moves
- * through them with the arrows, and lets Enter press one; the option fires its
- * own `helix-select` and the consumer decides what choosing meant. Deciding
- * *what* to suggest is theirs too: keys before a colon and values after it are
- * the same panel with different contents, which is all a two-level filter is,
- * and the parse that tells them apart belongs where the domain does.
+ * **It reads what was declared, and nothing that was not.** Write
+ * `FilterField`s — usually inside the `FilterMenu` slotted into `start`, so the
+ * picker and the text work off one set — and Enter reads the box against them:
+ * `disposition:refunded,settled` and `-disposition:refunded` announce
+ * `helix-facet`, exactly as ticking those values in the picker would, and the
+ * text they were read from goes. Everything else stays where it was typed, so
+ * `refund tuesday disposition:settled` is a filter and a search at once.
+ * `grammar.ts` carries the whole rule and is worth reading before relying on it;
+ * the short version is that Helix owns the punctuation and the consumer owns
+ * every word in it. A field with no `FilterField` in it parses nothing, which is
+ * the behavior this had before it could.
+ *
+ * **A field whose values cannot be listed belongs here rather than in the
+ * picker.** `assignee:ada` is a filter and nobody wants to enumerate every name
+ * in the company, but a menu page for it would have nothing on it to press.
+ * Written directly inside this element it is read by the grammar and never
+ * offered as a page: unslotted, so nothing draws it, which is the same trick
+ * `FilterField` already plays on its own children.
+ *
+ * **It can suggest what to type next, and deciding what to suggest is still the
+ * consumer's.** Slot `helix-option` elements into `suggestions` and the field
+ * shows them, moves through them with the arrows, and lets Enter press one; the
+ * option fires its own `helix-select` and the consumer decides what choosing
+ * meant. Keys before a colon and values after it are the same panel with
+ * different contents, and `readFilterText` is exported for a consumer narrowing
+ * that panel against what a reader has half typed.
  *
  * **The panel opens when there is something in it and closes when there is
  * not**, rather than on a choice. A reader who picks a key wants its values
@@ -55,7 +75,12 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * The tokens are neither, because they are not state. They are the consumer's
  * own elements in a slot, so there is nothing for this to own and nothing to
  * report back: a token goes when the consumer removes it from their markup,
- * having been asked by `helix-dismiss`.
+ * having been asked by `helix-dismiss`. **A `FilterChip` naming a declared field
+ * is asked differently**, and it has to be: the picker holds what is ticked, so
+ * a chip that removed itself without telling it left the value ticked in a list
+ * nobody could see was wrong. That dismissal is answered as the field being
+ * filtered by nothing, so it arrives as `helix-facet` like every other change
+ * and the chip goes because the filter went.
  *
  * @since 0.1.0
  * @status experimental
@@ -66,12 +91,15 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @slot end - After the text, for a count or a control.
  * @slot start - Before the text, for a search icon.
  * @slot suggestions - What could be typed next, as `Option`s, and `Option.Group`s of them.
- * @slot tags - What is already narrowing the results, as `Tag`s.
+ * @slot tags - What is already narrowing the results, as `FilterChip`s or `Tag`s.
  *
  * @event {Event} change - Relayed from the input once the reader has finished.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes, and cancelable.
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the suggestions go, and cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the suggestions show, and cancelable.
+ * @event {HelixDismissEvent} helix-dismiss - A token asking to go, from its close control or from Backspace on an empty field. A `FilterChip` naming a declared field is answered as `helix-facet` instead. Cancelable: refusing it takes the decision and the token stays.
+ * @event {HelixFacetEvent} helix-facet - Fired when a filter changes, whether read out of the text, picked, or dismissed. Cancelable: refusing it leaves the text and the chip where they were.
+ * @event {HelixSelectEvent} helix-select - A suggestion was chosen: the option's own, heard here because it bubbles out of `suggestions`. Cancelable: refusing it takes the decision from any other listener, and this field never acts on a choice itself, since what it means is the page's.
  * @event {Event} input - Announced once the text has moved.
  * @event {Event} toggle - Says the panel moved, carrying `newState` and `oldState`.
  *
@@ -81,6 +109,7 @@ declare const HelixHeadlessFilterInput_base: (new (...args: any[]) => import("@f
  * @csspart field - The box holding everything.
  * @csspart hint - Help under the field, while nothing is wrong.
  * @csspart label - The question, over the field.
+ * @csspart lead - The box before the text, holding whatever is slotted into `start`.
  * @csspart rest - How many tokens did not fit. A `<button>` with `expandable`, a `<span>` without it.
  * @csspart surface - The floating panel the suggestions sit in.
  * @csspart tags - The row the tokens sit in.
@@ -129,6 +158,24 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * `aria-controls` all arrive with the first option and leave with the last.
      */
     private suggesting;
+    /**
+     * Whether anything is slotted before the text.
+     *
+     * The leading box is drawn only where there is something to put in it, and it
+     * is a box rather than a bare slot because it carries the seam between what a
+     * consumer put at the head of the field and the field itself. `Menu.Item`
+     * reads its own leading slot the same way and for the same reason: the light
+     * DOM answer is not reactive, so a control added after the first render would
+     * never get the box.
+     *
+     * **Empty, the box is `hidden`, not flagged**, for `Checkbox`'s reason: this
+     * tier has no sheet, and `::part(lead)` cannot be qualified by an attribute,
+     * so a `data-` flag left a headless field an empty flex item it had no way to
+     * remove, and the first chip sat one gap further in than the rest.
+     */
+    private leading;
+    /** Whether `leading` has had its first answer from the children. */
+    private leadRead;
     /**
      * Whether Escape has closed the panel over text that still has suggestions.
      *
@@ -195,6 +242,64 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
     private readonly handleInput;
     /** Relayed, because `change` does not cross a shadow boundary on its own. */
     private readonly handleChange;
+    /**
+     * The fields this can be filtered by, wherever they were written.
+     *
+     * Descendants rather than children, because the usual place to write them is
+     * inside the `FilterMenu` slotted into `start`: the picker and the text are
+     * two ways at one set of declarations, and asking a consumer to write them
+     * twice would be asking which of the two surfaces is the real one.
+     */
+    get fields(): HelixHeadlessFilterField[];
+    /**
+     * The picker holding a field, where the consumer wrote one.
+     *
+     * The picker keeps what is ticked, so anything that changes a filter has to
+     * go through it or the two surfaces start disagreeing: a filter typed here
+     * that the menu never heard about leaves the value unticked in a list the
+     * reader is about to open.
+     */
+    private menuFor;
+    /**
+     * Says a field is now filtered by these values, through the picker where
+     * there is one, and reports whether it stood.
+     *
+     * Announced by the menu rather than relayed by this element, so the ticks and
+     * the event never come from two places. A consumer who wrote `FilterField`s
+     * without a picker gets it from here, which is the only case where nothing
+     * else could have said it.
+     */
+    private announceFacet;
+    /**
+     * A chip asking to go, answered as the filter going.
+     *
+     * **Taken rather than passed on, and only for a chip naming a declared
+     * field.** Left alone, a dismissed chip removed itself and told the picker
+     * nothing, so the menu went on showing the value ticked and the reader's next
+     * press on it read as *unticking*: they pressed `Refunded` and nothing came
+     * back. Turning the request into `apply(field, [])` puts it down the one road
+     * every other filter takes, so the chip goes because the filter went. A
+     * consumer refusing that `helix-facet` keeps both, which is the answer a
+     * refusal should give.
+     *
+     * Everything else in the row is untouched: a plain `Tag`, or a chip for
+     * something no `FilterField` declares, is the consumer's to answer.
+     */
+    private readonly handleDismiss;
+    /**
+     * Reads what has been typed, announces whatever of it was a filter, and takes
+     * that much of the text away.
+     *
+     * **Nothing at all without declarations**, which is what keeps this from
+     * changing under a consumer who never asked for it: a field with no
+     * `FilterField` in it has no vocabulary to read against, so Enter stays the
+     * form's and every keystroke is still just text.
+     *
+     * Refusing a `helix-facet` leaves that term's text where the reader wrote it,
+     * so a consumer who declines one is not left with a box that has silently
+     * emptied itself of a filter they did not take.
+     */
+    private readFilters;
     /**
      * Empties the text and gives the caret back.
      *
@@ -248,6 +353,8 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * this element and must not close what is being pressed.
      */
     private readonly handleFocusOut;
+    /** The leading box again, whenever what is in front of the text changes. */
+    private readonly handleLeading;
     /** The row again, whenever what is in it changes. */
     private readonly handleTokens;
     /**
@@ -261,6 +368,8 @@ export declare class HelixHeadlessFilterInput extends HelixHeadlessFilterInput_b
      * something it was never given.
      */
     protected removeLastToken(): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;

package/dist/filter-input/root/filter-input-root.js

@@ -4,10 +4,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { AriaForwardController, customElement, drawIcon, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, restoreValue, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, drawIcon, HelixFacetEvent, HelixFormElement, holdCaret, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, PopoverController, restoreValue, } from '@fusion.dev/helix-core';
 import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { readFilterText } from '../grammar.js';
 const asksToGo = (node) => typeof node?.dismiss === 'function';
 const isOption = (node) => 'active' in node && 'value' in node;
 let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinControllerOpen(MixinTokens(MixinControllerValue(MixinField(HelixFormElement)))) {
@@ -23,6 +24,8 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
         this.over = 0;
         this.activeAt = -1;
         this.suggesting = false;
+        this.leading = false;
+        this.leadRead = false;
         this.dismissed = false;
         this.panel = new PopoverController(this, {
             anchor: () => this.renderRoot?.querySelector('[part="field"]'),
@@ -47,6 +50,20 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             event.stopPropagation();
             this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
         };
+        this.handleDismiss = (event) => {
+            const chip = event.composedPath()[0];
+            if (!(chip instanceof HTMLElement) || chip.slot !== 'tags') {
+                return;
+            }
+            const field = chip.getAttribute('name') ?? '';
+            const menu = field === '' ? null : this.menuFor(field);
+            if (!menu) {
+                return;
+            }
+            event.preventDefault();
+            event.stopPropagation();
+            menu.apply(field, []);
+        };
         this.handleClear = () => {
             this.requestValue('');
             const control = this.control;
@@ -59,6 +76,12 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             if (this.tokenKeydown(event, this.value)) {
                 return;
             }
+            if (event.key === 'Enter' && !(this.open && this.suggestions[this.activeAt])) {
+                if (this.readFilters() > 0) {
+                    event.preventDefault();
+                }
+                return;
+            }
             if (!this.suggesting) {
                 return;
             }
@@ -119,6 +142,9 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             this.activeAt = -1;
             this.requestOpen(false);
         };
+        this.handleLeading = (event) => {
+            this.leading = event.target.assignedNodes({ flatten: true }).length > 0;
+        };
         this.handleTokens = () => {
             this.over = this.hideOverflow(this.tokens);
         };
@@ -164,6 +190,56 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
     setSelectionRange(start, end, direction) {
         this.control?.setSelectionRange(start, end, direction);
     }
+    get fields() {
+        return [
+            ...this.querySelectorAll('helix-headless-filter-field, helix-filter-field'),
+        ];
+    }
+    menuFor(field) {
+        for (const menu of this.querySelectorAll('helix-headless-filter-menu, helix-filter-menu')) {
+            if (menu.fields.some((declared) => (declared.name ?? '') === field)) {
+                return menu;
+            }
+        }
+        return null;
+    }
+    announceFacet(facet) {
+        const menu = this.menuFor(facet.field);
+        return menu
+            ? menu.apply(facet.field, facet.values, facet.operator)
+            : this.dispatchEvent(new HelixFacetEvent(facet));
+    }
+    readFilters() {
+        const fields = this.fields;
+        if (fields.length === 0) {
+            return 0;
+        }
+        const reading = readFilterText(this.value, fields.map((field) => field.vocabulary));
+        if (reading.terms.length === 0) {
+            return 0;
+        }
+        let taken = 0;
+        const refused = [];
+        for (const term of reading.terms) {
+            if (this.announceFacet(term.facet)) {
+                taken += 1;
+            }
+            else {
+                refused.push(...term.written);
+            }
+        }
+        if (taken === 0) {
+            return 0;
+        }
+        this.requestValue([...refused, reading.text].filter(Boolean).join(' '));
+        const control = this.control;
+        if (control) {
+            restoreValue(control, this.value);
+        }
+        this.dismissed = false;
+        this.settleOpen();
+        return taken;
+    }
     settleOpen() {
         const focused = this.matches(':focus-within') || this.contains(document.activeElement);
         this.requestOpen(this.suggesting && !this.dismissed && !this.isDisabled && focused);
@@ -192,8 +268,20 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
             last.dismiss();
         }
     }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('helix-dismiss', this.handleDismiss);
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('helix-dismiss', this.handleDismiss);
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
+        if (!this.leadRead && this.childrenKnown) {
+            this.leadRead = true;
+            this.leading = this.knownChildren.some((child) => child.slot === 'start');
+        }
         if (!this.hasUpdated) {
             return;
         }
@@ -206,6 +294,7 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
+        this.finishHydration();
         this.handleTokens();
         this.refreshSuggesting();
     }
@@ -242,7 +331,9 @@ let HelixHeadlessFilterInput = class HelixHeadlessFilterInput extends MixinContr
     render() {
         return html `${this.renderLabel()}
     <div part="field" @focusin=${this.handleFocusIn} @focusout=${this.handleFocusOut}>
-      <slot name="start"></slot>
+      <div part="lead" ?hidden=${!this.leading}>
+        <slot name="start" @slotchange=${this.handleLeading}></slot>
+      </div>
       ${this.renderTokenRow(html `<slot name="tags" @slotchange=${this.handleTokens}></slot>`, this.over)}
       <input
         part="control"
@@ -303,6 +394,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessFilterInput.prototype, "suggesting", void 0);
+__decorate([
+    state()
+], HelixHeadlessFilterInput.prototype, "leading", void 0);
 HelixHeadlessFilterInput = __decorate([
     customElement('helix-headless-filter-input')
 ], HelixHeadlessFilterInput);

package/dist/format-date/root/format-date-root.js

@@ -107,7 +107,7 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         const now = new Date();
         this.clock = now.getTime();
         const { next } = elapsedTime(this.locale)(moment, now);
-        if (!Number.isFinite(next)) {
+        if (!Number.isFinite(next) || !this.isConnected) {
             return;
         }
         this.stopTicking = subscribe(next, () => this.tick());

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from '@fusion.dev/helix-core';
 export * from './accordion/index.js';
 export * from './announcement/index.js';
 export * from './app-header/index.js';
+export * from './area-chart/index.js';
 export * from './avatar/index.js';
 export * from './badge/index.js';
 export * from './bar-chart/index.js';
@@ -35,6 +36,7 @@ export * from './copy-button/index.js';
 export * from './data-table/index.js';
 export * from './date-input/index.js';
 export * from './date-picker/index.js';
+export * from './description-list/index.js';
 export * from './dialog/index.js';
 export * from './divider/index.js';
 export * from './donut-chart/index.js';
@@ -61,6 +63,7 @@ export * from './meter/index.js';
 export * from './navigation/index.js';
 export * from './notifications/index.js';
 export * from './number-input/index.js';
+export * from './object-inspector/index.js';
 export * from './option/index.js';
 export * from './outline/index.js';
 export * from './pagination/index.js';
@@ -71,9 +74,11 @@ export * from './qr-code/index.js';
 export * from './quote/index.js';
 export * from './radio/index.js';
 export * from './rating/index.js';
+export * from './scatter-chart/index.js';
 export * from './scroll-area/index.js';
 export * from './select/index.js';
 export * from './skeleton/index.js';
+export * from './skip-link/index.js';
 export * from './slider/index.js';
 export * from './sparkline/index.js';
 export * from './speed-dial/index.js';

package/dist/index.js

@@ -3,6 +3,7 @@ export * from '@fusion.dev/helix-core';
 export * from './accordion/index.js';
 export * from './announcement/index.js';
 export * from './app-header/index.js';
+export * from './area-chart/index.js';
 export * from './avatar/index.js';
 export * from './badge/index.js';
 export * from './bar-chart/index.js';
@@ -26,6 +27,7 @@ export * from './copy-button/index.js';
 export * from './data-table/index.js';
 export * from './date-input/index.js';
 export * from './date-picker/index.js';
+export * from './description-list/index.js';
 export * from './dialog/index.js';
 export * from './divider/index.js';
 export * from './donut-chart/index.js';
@@ -52,6 +54,7 @@ export * from './meter/index.js';
 export * from './navigation/index.js';
 export * from './notifications/index.js';
 export * from './number-input/index.js';
+export * from './object-inspector/index.js';
 export * from './option/index.js';
 export * from './outline/index.js';
 export * from './pagination/index.js';
@@ -62,9 +65,11 @@ export * from './qr-code/index.js';
 export * from './quote/index.js';
 export * from './radio/index.js';
 export * from './rating/index.js';
+export * from './scatter-chart/index.js';
 export * from './scroll-area/index.js';
 export * from './select/index.js';
 export * from './skeleton/index.js';
+export * from './skip-link/index.js';
 export * from './slider/index.js';
 export * from './sparkline/index.js';
 export * from './speed-dial/index.js';

package/dist/line-chart/root/line-chart-root.d.ts

@@ -21,6 +21,11 @@ declare const HelixHeadlessLineChart_base: typeof HelixElement & (new (...args:
  * **One scale across every series**, the same as the bar chart, because two
  * series drawn to different scales are two charts sharing a picture.
  *
+ * **Not the chart for a total made of parts.** `area` washes each series from
+ * the floor on its own, so they overlap; `Area Chart` stacks them, so the top
+ * edge is the total and each band is a share. A line chart answers how each
+ * series moved, an area chart how the whole is made up.
+ *
  * **The labels are HTML beside the drawing rather than `<text>` inside it**, for
  * the reason `BarChart` records: an `<svg>` that fills its box scales its type
  * with everything else, the same `font-size` arriving at 10px in a narrow chart
@@ -57,10 +62,12 @@ declare const HelixHeadlessLineChart_base: typeof HelixElement & (new (...args:
  */
 export declare class HelixHeadlessLineChart extends HelixHeadlessLineChart_base {
     /**
-     * Whether a wash is drawn under each line.
+     * Whether a wash is drawn under each line, each from the floor on its own.
+     * The washes overlap rather than add up: for parts that make a total, use
+     * `Area Chart`, which stacks them.
      *
      * Absent is lines alone, which is what suits more than one series: washes
-     * stack and the lower ones are read through the upper. One series over a
+     * overlap and the lower ones are read through the upper. One series over a
      * ground it should feel like a quantity against is the case for this.
      */
     area: boolean;

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

@@ -114,11 +114,10 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * 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.
+     * The options are the consumer's elements rather than this component's
+     * markup, so the hiding is done to them in `willUpdate` and the render reads
+     * the answer it left here. Counted during render instead, a filter matching
+     * nothing left an empty box with no message in it.
      */
     private hasMatches;
     /**
@@ -127,8 +126,8 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
      * 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.
+     * never do. `place` does not run on the server, so this is false exactly
+     * when the answer is unknown.
      */
     private counted;
     protected readonly cascade: DisabledCascadeController;
@@ -231,6 +230,8 @@ export declare class HelixHeadlessListbox extends HelixHeadlessListbox_base {
     reveal(): void;
     /** Hides what the filter excludes, and writes the rest onto the options. */
     private place;
+    /** Scrolls the active option into view, which needs the rendered list to scroll. */
+    private followActive;
     /** Reports the answer and the verdict on it. */
     private sync;
     connectedCallback(): void;

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

@@ -274,7 +274,9 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
             this.hasMatches = anyShown;
         }
         this.counted = true;
-        const active = shown.find((option) => option.value === this.activeValue);
+    }
+    followActive() {
+        const active = this.shown.find((option) => option.value === this.activeValue);
         if (active) {
             const items = this.renderRoot.querySelector('[part="items"]');
             scrollItemIntoView(active, { padding: 4, ...(items ? { scroller: items } : {}) });
@@ -300,6 +302,9 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label, role: 'listbox' });
         this.internals.ariaMultiSelectable = this.multiple ? 'true' : null;
+        if (this.children !== undefined && !this.hydrating) {
+            this.place();
+        }
     }
     get currentValue() {
         return this.activeValue || (this.value.split(',')[0] ?? '');
@@ -314,7 +319,7 @@ let HelixHeadlessListbox = class HelixHeadlessListbox extends MixinCollection(Mi
     }
     updated(changed) {
         super.updated(changed);
-        this.place();
+        this.followActive();
         this.sync();
         this.linkHost();
         this.linkActive();

package/dist/menu/item/menu-item.d.ts

@@ -12,8 +12,9 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  *
  * **The role follows the shape.** A row that can be ticked is
  * `menuitemcheckbox` and carries `aria-checked`, because a reader is told "one
- * of these is on" rather than "here is a button". A row that opens a page keeps
- * `menuitem` and says `aria-haspopup`, since the page it opens is a menu.
+ * of these is on" rather than "here is a button"; `exclusive` makes it
+ * `menuitemradio`, for a set where only one can be. A row that opens a page
+ * keeps `menuitem` and says `aria-haspopup`, since the page it opens is a menu.
  *
  * Whether it is on the page showing is set by the menu as a property, never as
  * an attribute: an attribute written onto a consumer's element after it
@@ -64,6 +65,19 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * about who may name a file on somebody's disk rather than a gap here.
      */
     download: boolean;
+    /**
+     * Whether only one row of the set it belongs to can be on.
+     *
+     * Announcement and nothing else, the way `checkable` is: this element applies
+     * no choice and polices no group, so what it does is tell a reader which kind
+     * of set they are in. `menuitemcheckbox` says every row here is independent,
+     * which for a run of comparisons, or the values of a filter that compares
+     * against one, is the opposite of true.
+     *
+     * Meaningless without `checkable`, since a row that cannot be ticked is not
+     * one of a set of anything.
+     */
+    exclusive: boolean;
     /**
      * Where the row goes, which makes it a real link.
      *
@@ -98,13 +112,14 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     rel: string;
     /**
-     * Whether this row's submenu is the page showing.
+     * Whether the page showing is this row's submenu, or one below it.
      *
      * Separate from `onPage`, and it has to be. A row that opened a page is not
      * itself on that page, so both are false for it, and rendering nothing on
      * that basis takes its `slot[name="submenu"]` with it: the rows inside have
-     * nowhere to be assigned and are never laid out. The element that holds the
-     * page has to keep the slot even when it shows no row of its own.
+     * nowhere to be assigned and are never laid out. Every row on the way down to
+     * the open page has to keep its slot, not only the one directly above it.
+     * Three levels deep, the topmost row holds the slot the middle one lives in.
      */
     showingSubmenu: boolean;
     /**
@@ -131,7 +146,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     get hasSubmenu(): boolean;
     /**
-     * Whether anything is slotted into `submenu`. Read after first render.
+     * Whether anything is slotted into `submenu`.
      *
      * State rather than a getter over `children`. A getter is read during
      * `render()` with nothing to re-read it, so a submenu arriving after the
@@ -144,7 +159,40 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * once at first render. See the note there.
      */
     private submenu;
+    /**
+     * Whether anything is slotted before the label.
+     *
+     * The leading box is drawn only where there is something to put in it, the
+     * same way the trailing mark is. What keeps the labels on one edge is the
+     * track the menu reserves for the page, not a box on every row, so a row with
+     * nothing here takes no box and still lines up with its neighbors.
+     *
+     * Read from the slot rather than from the light DOM, because the light DOM
+     * answer is not reactive: a consumer who adds an icon to one row after first
+     * render changes nothing this element is told about, and `slotchange` is
+     * exactly the thing that is.
+     */
+    private start;
+    /**
+     * Both answers, from the children, before each render.
+     *
+     * The slots exist only once a render has made them: read through them, the
+     * first render drew no caret and no leading box and a second render had to
+     * follow it. `slotchange` still reads them, for a child that arrives later.
+     * Not on the server, where `children` is undefined, nor while hydrating what
+     * one sent.
+     */
+    protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
+    /**
+     * Re-reads whether anything is before the label.
+     *
+     * The slot itself is always rendered and it is the box around it that comes
+     * and goes, which is what makes this safe where `readSubmenu` needed the note
+     * it carries: there is one `slot[name="start"]` in one template branch, so it
+     * is never rebuilt and never fires on its way out.
+     */
+    private readonly readStart;
     /**
      * Re-reads whether anything is in the submenu, from whichever slot is current.
      *