@fusion.dev/helix-headless 0.145.0 → 0.146.0

package/dist/menu/item/menu-item.js

@@ -30,6 +30,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.submenu = false;
         this.start = false;
         this.end = false;
+        this.description = false;
         this.readStart = () => {
             const slot = this.renderRoot.querySelector('slot[name="start"]');
             this.start = (slot?.assignedNodes().length ?? 0) > 0;
@@ -38,6 +39,10 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             const slot = this.renderRoot.querySelector('slot[name="end"]');
             this.end = (slot?.assignedNodes().length ?? 0) > 0;
         };
+        this.readDescription = () => {
+            const slot = this.renderRoot.querySelector('slot[name="description"]');
+            this.description = (slot?.assignedNodes().length ?? 0) > 0;
+        };
         this.readSubmenu = () => {
             const slot = this.renderRoot.querySelector('slot[name="submenu"]');
             this.submenu = (slot?.assignedElements().length ?? 0) > 0;
@@ -74,11 +79,27 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.submenu = named('submenu');
         this.start = named('start');
         this.end = named('end');
+        this.description = named('description');
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();
     }
+    renderDescription() {
+        return html `<slot
+      id="description"
+      name="description"
+      aria-hidden="true"
+      ?data-empty=${!this.description}
+      @slotchange=${this.readDescription}
+    ></slot>`;
+    }
+    get describedBy() {
+        const ids = [this.description ? 'description' : '', this.end ? 'end-words' : '']
+            .filter((id) => id !== '')
+            .join(' ');
+        return ids === '' ? nothing : ids;
+    }
     renderEnd() {
         const kbd = this.tag('kbd');
         return html `<span part="end" ?data-empty=${!this.end && this.shortcut === ''}
@@ -86,10 +107,10 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             ? nothing
             : staticHtml `<${kbd}
               part="shortcut"
-              exportparts="kbd: shortcut-kbd"
+              exportparts="kbd: shortcut-kbd, key: shortcut-key, separator: shortcut-separator"
               aria-hidden="true"
               keys=${this.shortcut}
-            ></${kbd}>`}<slot name="end" @slotchange=${this.readEnd}></slot
+            ></${kbd}>`}<slot id="end-words" name="end" aria-hidden="true" @slotchange=${this.readEnd}></slot
     ></span>`;
     }
     focus() {
@@ -152,6 +173,23 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.tick();
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
     }
+    renderMark(submenu) {
+        if (submenu) {
+            return html `<slot name="chevron" aria-hidden="true"
+        ><svg part="mark" data-mirror fill="currentColor" viewBox=${caretRight.viewBox} aria-hidden="true">
+          ${unsafeSVG(caretRight.content)}
+        </svg></slot
+      >`;
+        }
+        if (this.checked) {
+            return html `<slot name="check" aria-hidden="true"
+        ><svg part="mark" fill="currentColor" viewBox=${check.viewBox} aria-hidden="true">
+          ${unsafeSVG(check.content)}
+        </svg></slot
+      >`;
+        }
+        return nothing;
+    }
     render() {
         if (this.showingSubmenu) {
             return html `<slot name="submenu" @slotchange=${this.readSubmenu}></slot>`;
@@ -169,28 +207,9 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
           ><slot name="start" @slotchange=${this.readStart}></slot
         ></span>
         <slot></slot>
+        ${this.renderDescription()}
         ${this.renderEnd()}
-        ${submenu
-            ? html `<svg
-                part="mark"
-                data-mirror
-                fill="currentColor"
-                viewBox=${caretRight.viewBox}
-                aria-hidden="true"
-              >
-                ${unsafeSVG(caretRight.content)}
-              </svg>`
-            : this.checked
-                ? html `<svg
-                  part="mark"
-                  fill="currentColor"
-                  viewBox=${check.viewBox}
-                  aria-hidden="true"
-                >
-                  ${unsafeSVG(check.content)}
-                </svg>`
-                :
-                    nothing}`;
+        ${this.renderMark(submenu)}`;
         return html `${linked
             ? html `<a
             part="item"
@@ -200,6 +219,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             ?download=${this.download}
             role=${role}
             aria-checked=${checkedState}
+            aria-describedby=${this.describedBy}
             aria-haspopup=${submenu ? 'menu' : nothing}
             aria-keyshortcuts=${keys}
             tabindex="-1"
@@ -210,6 +230,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             part="item"
             role=${role}
             aria-checked=${checkedState}
+            aria-describedby=${this.describedBy}
             aria-disabled=${this.disabled ? 'true' : nothing}
             aria-haspopup=${submenu ? 'menu' : nothing}
             aria-keyshortcuts=${keys}
@@ -265,6 +286,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessMenuItem.prototype, "end", void 0);
+__decorate([
+    state()
+], HelixHeadlessMenuItem.prototype, "description", void 0);
 HelixHeadlessMenuItem = __decorate([
     customElement('helix-headless-menu-item')
 ], HelixHeadlessMenuItem);

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

@@ -28,6 +28,20 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * its heading. Between runs of rows, a `<helix-divider announced>` is a
  * separator a screen reader announces.
  *
+ * Keys: Enter, Space or Down Arrow on the trigger opens the menu on its first
+ * row, and Up Arrow on its last. In the menu, Up and Down Arrow move between
+ * rows, Home and End go to the first and the last, a typed letter moves to
+ * the next row whose name starts with it, Enter and Space choose, Right Arrow
+ * opens a row's submenu and Left Arrow goes back, the two swapping on a
+ * right-to-left page, and Escape closes the menu and returns focus to the
+ * trigger. Tab closes it and moves on.
+ *
+ * While it is open, the surface carries the trigger's width as
+ * `--floating-anchor-inline-size` and the room left below it as
+ * `--floating-available-block-size`, as Radix's dropdown menu publishes its
+ * trigger's width, for a menu as wide as its trigger:
+ * `helix-menu::part(surface) { min-inline-size: var(--floating-anchor-inline-size) }`.
+ *
  * With `context`, the trigger is an area and the menu is its context menu: a
  * right-click, a long press, Shift+F10 or the menu key over the area opens it
  * at the pointer, or at the area's corner from the keyboard, as Radix's context

package/dist/menu/root/menu-root.js

@@ -4,7 +4,7 @@ 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, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, HelixElement, inlineStep, KeyboardNavigationController, MixinCollection, MixinControllerOpen, PopoverController, scrollItemIntoView, slottedWords, tellDisclosure, } from '@fusion.dev/helix-core';
+import { AriaForwardController, anchorElement, customElement, DrilldownController, deepActiveElement, deepContains, HelixElement, inlineStep, KeyboardNavigationController, MixinCollection, MixinControllerOpen, PopoverController, scrollItemIntoView, slottedWords, tellDisclosure, typeaheadBy, } from '@fusion.dev/helix-core';
 import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -29,7 +29,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             items: () => (this.open ? this.items : []),
             reserved: () => ['ArrowLeft', 'ArrowRight'],
             selects: () => false,
-            typeahead: (item) => slottedWords(item, ['']),
+            typeahead: typeaheadBy((item) => slottedWords(item, [''])),
         });
         this.aria = new AriaForwardController(this, {
             label: true,

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

@@ -71,6 +71,21 @@ export declare class HelixHeadlessMeter extends HelixElement {
      * no reader.
      */
     band?: MeterBand;
+    /**
+     * `Intl.NumberFormat` options the reading is written with, as React Aria's
+     * Meter and ProgressBar take them: a unit, a currency, or a number of
+     * decimals. Written as JSON in the attribute.
+     *
+     * ```html
+     * <helix-meter value="18" max="32" format-options='{"style":"unit","unit":"gigabyte"}'></helix-meter>
+     * ```
+     *
+     * A `percent` style writes the share of the range, and any other the value
+     * itself, so the example says "18 GB", and a value past an end as it is.
+     * Absent is a whole percentage. The words are announced as well as shown.
+     * `value-text` still wins.
+     */
+    formatOptions?: Intl.NumberFormatOptions;
     /**
      * Bottom of the high band.
      *
@@ -199,7 +214,11 @@ export declare class HelixHeadlessMeter extends HelixElement {
      * keeps an unbanded meter from being painted as good news.
      */
     private get computedBand();
-    /** What the reading says, which is the consumer's words or a percentage. */
+    /**
+     * What the reading says: the consumer's words, or the reading in
+     * `format-options`, a share of the range for a percent and the value for
+     * anything else.
+     */
     private get text();
     protected willUpdate(changed: PropertyValues): void;
     /**

package/dist/meter/root/meter-root.js

@@ -4,21 +4,10 @@ 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 { customElement, HelixElement, hostAria, slottedWords } from '@fusion.dev/helix-core';
+import { customElement, formatNumber, HelixElement, hostAria, slottedWords, } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
-const percents = new Map();
-const percent = (share, locale) => {
-    let format = percents.get(locale);
-    if (!format) {
-        format = new Intl.NumberFormat(locale || undefined, {
-            maximumFractionDigits: 0,
-            style: 'percent',
-        });
-        percents.set(locale, format);
-    }
-    return format.format(share);
-};
+const WHOLE_PERCENT = { maximumFractionDigits: 0, style: 'percent' };
 let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
     constructor() {
         super(...arguments);
@@ -80,7 +69,11 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         return distance === 0 ? 'good' : distance === 1 ? 'fair' : 'poor';
     }
     get text() {
-        return this.valueText || percent(this.ratio, this.locale);
+        const options = this.formatOptions;
+        return (this.valueText ||
+            (options && options.style !== 'percent'
+                ? formatNumber(Number.isFinite(this.value) ? this.value : this.span.min, this.locale, options)
+                : formatNumber(this.ratio, this.locale, options ?? WHOLE_PERCENT)));
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -90,7 +83,7 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         this.internals.ariaValueMax = String(max);
         this.internals.ariaValueNow = String(this.reading);
         this.internals.ariaValueText =
-            this.valueText || (this.beyond ? percent(this.ratio, this.locale) : null);
+            this.valueText || this.formatOptions !== undefined || this.beyond ? this.text : null;
     }
     renderRound() {
         const bounds = this.thresholds;
@@ -144,6 +137,9 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
 __decorate([
     property()
 ], HelixHeadlessMeter.prototype, "band", void 0);
+__decorate([
+    property({ attribute: 'format-options', type: Object })
+], HelixHeadlessMeter.prototype, "formatOptions", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessMeter.prototype, "high", void 0);

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

@@ -36,8 +36,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/navigation
  *
  * @slot - The destinations, as your own links.
+ * @slot indicator - A marker of your own, drawn inside the `indicator` part, where the current destination's place and size reach it.
  *
- * @csspart indicator - The marker that moves to the current destination.
+ * @csspart indicator - The marker that moves to the current destination. It carries the destination's place and size as `--indicator-x`, `--indicator-y`, `--indicator-inline-size` and `--indicator-block-size`, and `data-placed` once it has been placed.
  * @csspart nav - The navigation landmark.
  */
 export declare class HelixHeadlessNavigation extends HelixElement {

package/dist/navigation/root/navigation-root.js

@@ -53,7 +53,7 @@ let HelixHeadlessNavigation = class HelixHeadlessNavigation extends HelixElement
         });
     }
     get items() {
-        const slot = this.renderRoot.querySelector('slot');
+        const slot = this.renderRoot.querySelector('slot:not([name])');
         return (slot?.assignedElements() ?? []);
     }
     watch() {
@@ -80,7 +80,7 @@ let HelixHeadlessNavigation = class HelixHeadlessNavigation extends HelixElement
     }
     render() {
         return html `<nav part="nav" aria-label=${this.label}>
-      <div part="indicator" aria-hidden="true"></div>
+      <div part="indicator" aria-hidden="true"><slot name="indicator"></slot></div>
       <slot @slotchange=${() => this.watch()}></slot>
     </nav>`;
     }

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

@@ -32,7 +32,8 @@ declare const HelixHeadlessNotifications_base: (new (...args: any[]) => import("
  * **`load-more` adds a button after the list** that sends `helix-load-more`,
  * for a feed that holds one page of a longer list. Append the next page, set
  * `loading` while it is on its way, and take `load-more` off once there is
- * nothing more. The button is hidden while the feed is loading.
+ * nothing more. While the feed is loading the button stays, so focus stays on
+ * it, and it is `aria-disabled` and sends nothing.
  *
  * @since 0.1.0
  * @status stable
@@ -55,7 +56,7 @@ declare const HelixHeadlessNotifications_base: (new (...args: any[]) => import("
  * @csspart live - A copy of the empty and loading messages, in a live region that screen readers announce when they change. Visually hidden in the styled tier.
  * @csspart loading - Shown while the feed is loading.
  * @csspart mark-all - The control that marks everything read.
- * @csspart more - The button after the list that asks for more, while `load-more` is set and the feed is not loading.
+ * @csspart more - The button after the list that asks for more, while `load-more` is set. It is `aria-disabled` while the feed is loading.
  *
  * @cssstate media - While a notification in the list holds something in its media slot, so every row keeps that column.
  */
@@ -260,7 +261,13 @@ export declare class HelixHeadlessNotifications extends HelixHeadlessNotificatio
     private markEmpty;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
-    /** Asks for the next page, for the `load-more` button. */
+    /**
+     * Asks for the next page, for the `load-more` button, unless a page is
+     * already on its way.
+     *
+     * The button stays while the feed is loading, marked `aria-disabled`, so
+     * focus stays on it: removed, it took focus with it to the body.
+     */
     private readonly askForMore;
     /**
      * Marks everything read, and keeps focus in the feed.

package/dist/notifications/root/notifications-root.js

@@ -54,7 +54,9 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
             }
         };
         this.askForMore = () => {
-            this.dispatchEvent(new HelixLoadMoreEvent());
+            if (!this.loading) {
+                this.dispatchEvent(new HelixLoadMoreEvent());
+            }
         };
         this.handleMarkAll = (event) => {
             const button = event.currentTarget;
@@ -151,9 +153,9 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
     rove() {
         const rows = this.reachable;
         const stop = rovingStop(rows, this.stopRow);
-        const direct = this.rows;
-        for (const row of this.items) {
-            const position = direct.indexOf(row) + 1;
+        const items = this.items;
+        for (const row of items) {
+            const position = items.indexOf(row) + 1;
             whenHydrated(row, () => {
                 row.stop = row === stop;
                 row.position = this.total === undefined ? 0 : position;
@@ -210,13 +212,23 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
             </button>`
             : nothing}
       </div>
-      <div part="list" role="list" aria-busy=${this.loading ? 'true' : nothing}>
+      <div
+        part="list"
+        role="list"
+        aria-busy=${this.loading ? 'true' : nothing}
+        aria-label=${this.label || nothing}
+      >
         <slot name="items" @slotchange=${this.handleSlotChange}></slot>
         ${this.renderStatus(hasItems)}
       </div>
       ${this.renderLive(hasItems)}
-      ${this.loadMore && !this.loading
-            ? html `<button part="more" type="button" @click=${this.askForMore}>
+      ${this.loadMore
+            ? html `<button
+              part="more"
+              type="button"
+              aria-disabled=${this.loading ? 'true' : nothing}
+              @click=${this.askForMore}
+            >
               ${this.loadMoreLabel}
             </button>`
             : nothing}

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

@@ -25,9 +25,10 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * The locale's group separators are read in every field, so `1,234` is a
  * number in `en-US`.
  *
- * On iOS and iPadOS the field is a text field described as a number field,
- * with no `role="spinbutton"`, which VoiceOver reads as a slider you cannot
- * type in. React Aria's NumberField does the same.
+ * On iOS and iPadOS the field is a plain text field, with no
+ * `role="spinbutton"`, which VoiceOver reads as a slider you cannot type in,
+ * and no role description, so VoiceOver says the field is required. React
+ * Aria's NumberField does the same.
  *
  * Validity follows the platform's rules: `min`, `max`, and `step` are checked
  * and reported through the host's own `setValidity`, under the platform's flag
@@ -36,6 +37,19 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * Stepping is separate from typing, so a number is not corrected while you type
  * it.
  *
+ * **Keyboard.** The field is one tab stop, and the stepper buttons are not in
+ * the tab order.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Up, Down | Steps the value up or down by `step`. |
+ * | Page Up, Page Down | Steps by `large-step` steps, ten by default. |
+ * | Home, End | Goes to `min` or `max`, where there is one. Without one, moves the caret. |
+ * | Enter | Commits the typed number and submits the form, as a native field does. |
+ *
+ * The field has `role="spinbutton"` with `aria-valuenow`, `aria-valuemin`,
+ * `aria-valuemax`, and the formatted text in `aria-valuetext`.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
@@ -154,11 +168,6 @@ export declare class HelixHeadlessNumberInput extends HelixHeadlessNumberInput_b
      * Prevents editing. The value is still submitted with the form.
      */
     readOnly: boolean;
-    /**
-     * What the field is described as on iOS and iPadOS, where it carries no
-     * spinbutton role. See the class description.
-     */
-    roleDescription: string;
     /**
      * Makes the label a grip that changes the value when it is dragged.
      *

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

@@ -4,7 +4,7 @@ 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, appleTouch, valueAsNumber as asNumber, customElement, fillTemplate, formatNumber, numberAsValue as fromNumber, HelixFormElement, holdCaret, MixinControllerValue, MixinField, parseNumber, restoreValue, } from '@fusion.dev/helix-core';
+import { AriaForwardController, appleTouch, valueAsNumber as asNumber, customElement, fillTemplate, formatNumber, numberAsValue as fromNumber, HelixFormElement, holdCaret, MixinControllerValue, MixinField, parseNumber, restoreValue, submitImplicitly, } from '@fusion.dev/helix-core';
 import { minus, plus } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -24,7 +24,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         this.locale = '';
         this.placeholder = '';
         this.readOnly = false;
-        this.roleDescription = 'number field';
         this.scrub = false;
         this.step = 1;
         this.valueText = '';
@@ -138,7 +137,7 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
         };
         this.handleKeypress = (event) => {
             if (event.key === 'Enter' && !event.defaultPrevented) {
-                this.submitImplicitly();
+                submitImplicitly(this.form);
             }
         };
     }
@@ -317,7 +316,6 @@ let HelixHeadlessNumberInput = class HelixHeadlessNumberInput extends MixinContr
           .value=${this.shown}
           type="text"
           role=${this.touchApple ? nothing : 'spinbutton'}
-          aria-roledescription=${this.touchApple ? this.roleDescription : nothing}
           inputmode="decimal"
           autocomplete=${this.autocomplete || nothing}
           name=${this.name || nothing}
@@ -411,9 +409,6 @@ __decorate([
 __decorate([
     property({ attribute: 'readonly', reflect: true, type: Boolean })
 ], HelixHeadlessNumberInput.prototype, "readOnly", void 0);
-__decorate([
-    property({ attribute: 'role-description' })
-], HelixHeadlessNumberInput.prototype, "roleDescription", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessNumberInput.prototype, "scrub", void 0);

package/dist/object-inspector/root/object-inspector-root.d.ts

@@ -15,13 +15,29 @@ import { type Row } from '../rows.js';
  * works with server rendering and with React hydration, which skips object
  * properties. `value` wins when both are set.
  *
- * The tree is one tab stop. Up and Down move between rows, Right opens a branch
- * or moves into it, Left closes it or moves to its parent, and Home and End
- * move to the first and last rows. Typing moves to the next row whose key
- * starts with what was typed, and `*` opens every branch beside the active
- * row. Focus stays on the tree, and `aria-activedescendant` marks the active
- * row. Each row carries its real level, position, and set size, including in
- * a windowed tree.
+ * **Keyboard.** The tree is one tab stop, and focus moves from row to row.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Down, Up | Moves to the next or the previous row. |
+ * | Right | Opens a closed branch, or moves into an open one. Left on a right-to-left page. |
+ * | Left | Closes an open branch, or moves to the parent. Right on a right-to-left page. |
+ * | Home, End | Moves to the first or the last row. |
+ * | Enter, Space | Opens or closes a branch. |
+ * | `*` | Opens every branch beside the active row. |
+ * | A letter or a word | Moves to the next row whose key starts with what you typed. |
+ * | Command+C, Control+C | Copies the active row, where no text is selected. |
+ *
+ * The tree is a `treegrid`, as React Aria's Tree is: each entry is a `row` with
+ * one cell, and carries its real level, position, and set size, including in a
+ * windowed tree. Nothing in it is chosen, so no row carries `aria-selected`,
+ * and a focused row is not announced as selected.
+ *
+ * A reader opening or closing a branch sends `helix-before-open` or
+ * `helix-before-close`, which you can cancel, and then `toggle` with
+ * `newState` and `oldState`, as `<details>` does. The branch is the active
+ * row, and `expanded` holds every open branch. `*` asks once for all the
+ * branches it opens. A script writing `expanded` or `active` sends nothing.
  *
  * `active` is the active row's path, written the way a JSON Pointer writes it:
  * the empty string for the root and `/meta/tags/0` for an entry under it.
@@ -60,9 +76,12 @@ import { type Row } from '../rows.js';
  *
  * @event {HelixActivateEvent} helix-activate - The active row moved, by a key or a click. The detail's `value` is its path.
  * @event {HelixBeforeActivateEvent} helix-before-activate - The active row is about to move, with its new path. Cancelable: cancel it to keep the row where it is.
+ * @event {HelixBeforeCloseEvent} helix-before-close - A reader is about to close the active branch. Cancelable: cancel it to keep the branch open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - A reader is about to open the active branch, or `*` the branches beside it. Cancelable: cancel it to keep them closed.
  * @event {HelixCopyEvent} helix-copy - A value was put on the clipboard, from the copy button or the keyboard.
  * @event {HelixFilterEvent} helix-filter - Text was typed in the filter field, with what it now holds. Cancelable: cancel it to keep the filter as it was.
  * @event {HelixFilteredEvent} helix-filtered - The filter field changed `filter`, which now holds the text.
+ * @event {ToggleEvent} toggle - A reader opened or closed a branch, with `newState` and `oldState`. `expanded` holds every open branch.
  *
  * @csspart after - The space the rows below the drawn rows would take, when `windowed` is set.
  * @csspart before - The space the rows above the drawn rows would take, when `windowed` is set.
@@ -90,14 +109,14 @@ import { type Row } from '../rows.js';
  * @csspart live - How many entries a filter matched, in a region that screen readers announce when it changes. Drawn from the first filter on. Visually hidden in the styled tier.
  * @csspart null - A `null`.
  * @csspart number - A number.
- * @csspart row - One entry, as a tree item.
- * @csspart row-active - The entry the keyboard is on. Set alongside `row`.
+ * @csspart row - One entry, as a row of the tree grid, which takes focus.
+ * @csspart row-active - The entry the keyboard is on, which holds the tab stop. Set alongside `row`.
  * @csspart row-match - An entry whose key or value holds the filter. Set alongside `row`.
  * @csspart search-field - The field that sets `filter`, with `filterable`.
  * @csspart string - A string, in quotes.
  * @csspart summary - The brackets that stand for a branch's contents.
  * @csspart toggle - The caret on a branch. It points down when the branch is open and sideways when it is closed.
- * @csspart tree - The tree, which is the element that receives focus.
+ * @csspart tree - The tree grid that holds the rows.
  *
  * @cssproperty --object-inspector-level - How deep a row is, from 0 at the root, for indenting it.
  */
@@ -230,6 +249,10 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     private found;
     /** Set by a keyboard move, so the next render brings the active row into view. */
     private revealing;
+    /** Set by a reader's move, so the next render moves focus to the active row. */
+    private focusing;
+    /** Whether a row held focus as this update began, so a row the render moved gets it back. */
+    private hadFocus;
     /** What has been typed toward a key, and when the last letter came. */
     private typed;
     /** The branches of the last value seen, by path, so a new value can tell old ones from new. */
@@ -266,16 +289,17 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     /** Opens the branches around each path, where the value has them. */
     private openAround;
     protected willUpdate(changed: PropertyValues): void;
-    /**
-     * Where the active row goes once the rows have moved: onto `path` where it
-     * is still shown, onto the first match where a filter just hid it, and
-     * otherwise onto the nearest branch around it that is.
-     */
-    private place;
     /** Says how many entries the filter matched, and nothing for an empty one. */
     private tell;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /**
+     * Moves focus to the active row, once it is drawn.
+     *
+     * After a reader's move only, so a script writing `active` does not take
+     * focus from wherever the reader is.
+     */
+    private focusActive;
     private load;
     /**
      * Brings the active row into the box.
@@ -292,6 +316,20 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     private reveal;
     /** What copying takes: a branch as indented JSON, a string as itself. */
     private copyable;
+    /**
+     * Asks to open or close branches, and then does and says so:
+     * `helix-before-open` or `helix-before-close`, which a listener can cancel,
+     * then `toggle`. A reader's act only. Returns whether they moved.
+     */
+    private requestOpen;
+    /**
+     * Says a branch opened or closed under the platform's own name and in its
+     * shape: `toggle` with `newState` and `oldState`, not bubbling, as
+     * `<details>` sends it and as the open mixin does for the families whose
+     * open state it owns. A real `ToggleEvent` where the platform has one, and a
+     * plain event carrying the same two fields where it does not.
+     */
+    private announceToggle;
     private toggle;
     /**
      * Moves the active row, asking first: `helix-before-activate` with the path,
@@ -299,8 +337,6 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      */
     private move;
     private readonly handleKeydown;
-    /** Opens every branch at the active row's level under the same parent, as `*` asks. */
-    private openSiblings;
     /**
      * Moves to the next row whose key starts with what was typed.
      *
@@ -313,7 +349,7 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     private handleRowClick;
     /** Text typed in the filter field, asked for before the tree narrows to it. */
     private readonly handleFilterInput;
-    /** Down from the filter field goes to the tree, where the matches are. */
+    /** Down from the filter field goes to the active row, where the matches are. */
     private readonly handleFilterKeydown;
     private renderValue;
     /**
@@ -321,17 +357,29 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      *
      * **`row-active` and no attribute beside it.** Which row the keys are on is
      * drawn by a sheet and by nothing else: the accessibility tree hears it from
-     * `aria-activedescendant` on the tree, which points at this row's id, so an
-     * attribute would be a second spelling with no reader. The name is the one a
-     * consumer can reach, nothing being able to follow `::part()` with an
-     * attribute selector.
+     * focus, which the row holds, so an attribute would be a second spelling with
+     * no reader. The name is the one a consumer can reach, nothing being able to
+     * follow `::part()` with an attribute selector.
      *
-     * **`aria-selected="false"` on every row**, because nothing here is chosen.
-     * Chromium takes the active descendant of a single-selection tree as selected
-     * when no row says otherwise, so every arrow press was also announced as a
-     * selection. An explicit false is the one thing that turns that off.
+     * **A `row` of a `treegrid` with one cell, focused itself, and no
+     * `aria-selected`**, because nothing here is chosen. Chromium takes the
+     * focused item of a single-selection `tree` as selected, by focus or by
+     * `aria-activedescendant` (measured), so every arrow press was also announced
+     * as a selection, and `aria-selected="false"` on every row was the one way to
+     * turn it off. A row of a tree grid is not selected by focus, which is why
+     * React Aria's Tree is one. The cell is `display: contents`, so the row lays
+     * out its text as it did.
      */
     private renderRow;
+    /** Whether a row of the tree holds focus. */
+    private hasFocusedRow;
+    /**
+     * A row that takes focus some other way than the keys, from a script or a
+     * screen reader, becomes the active row, so focus and the keys agree.
+     */
+    private readonly handleFocusIn;
+    /** A row kept drawn for focus is let go once focus leaves it. */
+    private readonly handleFocusOut;
     /** The copy button, behind the seam Code Block's uses, so each tier renders its own. */
     protected renderCopyButton(row: Row | undefined): TemplateResult;
     protected render(): TemplateResult;