@fusion.dev/helix-headless 0.143.0 → 0.145.0

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

@@ -22,6 +22,13 @@ declare const HelixHeadlessTour_base: (new (...args: any[]) => import("@fusion.d
  * `toggle` work as they do on `Dialog`. Setting `open` starts the run, and
  * `skip()` and `requestOpen(false)` end it early.
  *
+ * Each stop is told its place in the run, from `progress-label`, such as "2 of
+ * 5". It describes the stop's panel, so a screen reader says it at every stop,
+ * and `progress` draws it in the panel as well. A dialog or a floating stop,
+ * which has nothing to light, is shown over the `backdrop` part. At a `wait`
+ * stop the run waits for that stop's target to be on the page, and moves on by
+ * itself.
+ *
  * **Focus follows the run.** Opening moves focus to the first stop's panel,
  * and moving on from a control in a stop moves it to the next one. Ending the
  * tour puts focus back on the element that had it when the tour opened, unless
@@ -45,6 +52,7 @@ declare const HelixHeadlessTour_base: (new (...args: any[]) => import("@fusion.d
  * @event {HelixTourAskEvent} helix-tour-ask - Fired when a stop's control is pressed to move the tour. The stop sends it, and the tour handles it.
  * @event {ToggleEvent} toggle - Sent when the tour starts or ends, with `newState` and `oldState`.
  *
+ * @csspart backdrop - Behind a dialog or a floating stop, which lights nothing. It draws no box until you give it one.
  * @csspart spotlight - The box over the current target. It also draws the dimmed area around the target.
  *
  * @cssstate open - While the tour is running.
@@ -86,6 +94,15 @@ export declare class HelixHeadlessTour extends HelixHeadlessTour_base {
      * Label for the control that goes on.
      */
     nextLabel: string;
+    /**
+     * Draws each stop's place in the run in its panel, as well as saying it.
+     */
+    progress: boolean;
+    /**
+     * Each stop's place in the run, with `{index}` and `{count}` filled in.
+     * Translate it with the rest of your text.
+     */
+    progressLabel: string;
     /**
      * Label for the control that leaves the tour.
      */
@@ -160,6 +177,24 @@ export declare class HelixHeadlessTour extends HelixHeadlessTour_base {
     private settle;
     /** The current stop's target while the run is open, which is what the light falls on. */
     private get lit();
+    /** The stop being shown, or nothing where there are no stops. */
+    private get current();
+    /** Stops waiting, where a `wait` stop is waiting. */
+    private unwait;
+    /** The `wait` stop being waited on, so a render that changed nothing starts nothing. */
+    private waiting;
+    /**
+     * Waits at a `wait` stop for its target to be on the page, then moves on.
+     *
+     * On the stop's own root, which is where its `for` resolves.
+     */
+    private wait;
+    /**
+     * Whether the current stop is shown over the backdrop: a dialog or a floating
+     * stop, or one with no target, which have nothing to light. Read with the
+     * light, after the stops are known, since the first render cannot know them.
+     */
+    private veiled;
     /** Reads the current target's box, which is where the light falls. */
     private light;
     /** Keeps `sizer` on the lit target, and on nothing once there is none. */

package/dist/tour/root/tour-root.js

@@ -4,9 +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, deepActiveElement, deepContains, HelixActivateEvent, HelixBeforeActivateEvent, HelixCompleteEvent, HelixElement, hostAria, MixinControllerOpen, requestChange, whenHydrated, } from '@fusion.dev/helix-core';
+import { customElement, deepActiveElement, deepContains, fillTemplate, HelixActivateEvent, HelixBeforeActivateEvent, HelixCompleteEvent, HelixElement, hostAria, MixinControllerOpen, requestChange, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, queryAssignedElements, state } from 'lit/decorators.js';
+import { onPage, waitFor } from '../wait.js';
 let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
@@ -16,6 +17,8 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
         this.indexState = undefined;
         this.label = '';
         this.nextLabel = '';
+        this.progress = false;
+        this.progressLabel = '{index} of {count}';
         this.skipLabel = '';
         this.spotlightPadding = 8;
         this.sizer = undefined;
@@ -42,6 +45,7 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
             this.light();
         };
         this.followed = false;
+        this.veiled = false;
     }
     get index() {
         return this.indexState ?? this.defaultIndex;
@@ -108,6 +112,9 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
         window.removeEventListener('scroll', this.handleViewport, { capture: true });
         this.sizer?.disconnect();
         this.sized = undefined;
+        this.unwait?.();
+        this.unwait = undefined;
+        this.waiting = undefined;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -121,6 +128,7 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
         this.settle();
         this.light();
         this.follow(changed);
+        this.wait();
     }
     follow(changed) {
         if (!this.followed) {
@@ -168,6 +176,11 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
                 stop.current = this.open && index === at;
                 stop.first = index === 0;
                 stop.last = index === stops.length - 1;
+                stop.position = fillTemplate(this.progressLabel, {
+                    count: stops.length,
+                    index: index + 1,
+                });
+                stop.progress = this.progress;
                 if (this.backLabel !== '') {
                     stop.backLabel = this.backLabel;
                 }
@@ -184,12 +197,41 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
         });
     }
     get lit() {
+        const stop = this.current;
+        return this.open && stop?.type === undefined ? stop?.target : undefined;
+    }
+    get current() {
         const stops = this.stops;
-        return this.open
-            ? stops[Math.max(0, Math.min(this.index, stops.length - 1))]?.target
-            : undefined;
+        return stops[Math.max(0, Math.min(this.index, stops.length - 1))];
+    }
+    wait() {
+        const stop = this.open ? this.current : undefined;
+        const next = stop?.type === 'wait' ? stop : undefined;
+        if (next === this.waiting) {
+            return;
+        }
+        this.unwait?.();
+        this.unwait = undefined;
+        this.waiting = next;
+        if (!next) {
+            return;
+        }
+        this.unwait = waitFor(next.getRootNode(), () => onPage(next.target), () => {
+            this.waiting = undefined;
+            this.unwait = undefined;
+            queueMicrotask(() => {
+                if (this.open && this.current === next) {
+                    this.next();
+                }
+            });
+        });
     }
     light() {
+        const stop = this.open ? this.current : undefined;
+        const veiled = stop !== undefined && stop.type !== 'wait' && (stop.type !== undefined || !stop.target);
+        if (veiled !== this.veiled) {
+            this.veiled = veiled;
+        }
         const target = this.lit;
         this.watch(target);
         if (!target || typeof target.getBoundingClientRect !== 'function') {
@@ -227,7 +269,7 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
     }
     render() {
         const spot = this.spot;
-        return html `${spot === undefined
+        return html `${this.veiled ? html `<div part="backdrop" aria-hidden="true"></div>` : ''}${spot === undefined
             ? ''
             : html `<div
             part="spotlight"
@@ -255,6 +297,12 @@ __decorate([
 __decorate([
     property({ attribute: 'next-label' })
 ], HelixHeadlessTour.prototype, "nextLabel", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessTour.prototype, "progress", void 0);
+__decorate([
+    property({ attribute: 'progress-label' })
+], HelixHeadlessTour.prototype, "progressLabel", void 0);
 __decorate([
     property({ attribute: 'skip-label' })
 ], HelixHeadlessTour.prototype, "skipLabel", void 0);
@@ -267,6 +315,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessTour.prototype, "spot", void 0);
+__decorate([
+    state()
+], HelixHeadlessTour.prototype, "veiled", void 0);
 HelixHeadlessTour = __decorate([
     customElement('helix-headless-tour')
 ], HelixHeadlessTour);

package/dist/tour/stop/tour-stop.d.ts

@@ -1,5 +1,5 @@
 import { HelixElement, type Placement } from '@fusion.dev/helix-core';
-import type { PropertyValues, TemplateResult } from 'lit';
+import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../button/index.js';
 /**
  * @summary One stop on a tour: the element it points at, and a panel of content about it.
@@ -15,7 +15,16 @@ import '../../button/index.js';
  * - **Visibility.** The stop shows when it is `current`, which the root sets.
  *
  * Put any content in the stop, such as a `Card`, or a heading and a line of
- * text. There are no fixed title or body parts.
+ * text. The `heading` and `description` slots are optional places for the
+ * title and the line under it, which then name and describe the panel.
+ *
+ * **A stop has a type.** Without one it is a bubble pointing at its target.
+ * `type="dialog"` is a panel in the middle of the window, over a backdrop, for
+ * a welcome or a summary with nothing to point at. `type="floating"` is a
+ * panel in a corner of the window, which the styled tier puts at the end of
+ * the line, for a note that points at nothing in particular. `type="wait"` shows nothing: the tour waits
+ * for the element `for` names to be on the page, such as a menu the reader has
+ * to open, and moves on by itself.
  *
  * **The buttons are slot fallback.** With nothing in the `actions` slot, you
  * get Back, Next, and Skip, already wired. Slot your own `actions` and drive
@@ -25,9 +34,12 @@ import '../../button/index.js';
  * on the page from markup. It resolves against the stop's root node, so a stop
  * inside a shadow tree points at a target in that tree.
  *
- * The panel is a `group`, named by the first heading in the stop's content,
- * and only while the stop is shown. `focus()` moves focus to the panel, which
- * is what the tour does when it opens or moves on.
+ * The panel is a `group`, and a `dialog` for a dialog stop, only while the
+ * stop is shown. It is named by the `heading` slot, then by the first heading
+ * in the content, then by `label`, and otherwise by its place in the tour. It
+ * is described by the `description` slot and by its place, such as "2 of 5",
+ * so a screen reader says where the reader is at every stop. `focus()` moves
+ * focus to the panel, which is what the tour does when it opens or moves on.
  *
  * @since 0.1.0
  * @status stable
@@ -36,6 +48,8 @@ import '../../button/index.js';
  *
  * @slot - The stop's content. Any content works, such as a card, or a heading and a line.
  * @slot actions - Replaces the controls, which are Back, Next, and Skip.
+ * @slot description - A line under the title, which describes the panel.
+ * @slot heading - The stop's title, which names the panel.
  *
  * @event {HelixTourAskEvent} helix-tour-ask - Fired when one of the stop's controls is pressed, to move the tour.
  *
@@ -47,14 +61,20 @@ import '../../button/index.js';
  * @csspart arrow-top - The arrow while the panel is above its target, on the panel's bottom edge. Applied with `arrow`.
  * @csspart back - The control that goes to the previous stop.
  * @csspart back-button - The button inside `back`.
+ * @csspart back-live - The live region inside `back`.
  * @csspart back-text - The words on that button, trimmed to their capitals and baseline.
  * @csspart bubble - The panel that points at the target.
  * @csspart content - The region holding the slotted content.
+ * @csspart description - The slot the description is in. It draws no box until you give it one.
+ * @csspart heading - The slot the title is in. It draws no box until you give it one.
  * @csspart next - The control that goes to the next stop, and finishes the tour on the last stop.
  * @csspart next-button - The button inside `next`.
+ * @csspart next-live - The live region inside `next`.
  * @csspart next-text - The words on that button, trimmed to their capitals and baseline.
+ * @csspart progress - The stop's place in the tour, such as "2 of 5". It describes the panel, and is shown when the tour has `progress`.
  * @csspart skip - The control that ends the tour early.
  * @csspart skip-button - The button inside `skip`.
+ * @csspart skip-live - The live region inside `skip`.
  * @csspart skip-text - The words on that button, trimmed to their capitals and baseline.
  *
  * @cssstate placed-bottom - The panel sits below its target.
@@ -89,6 +109,11 @@ export declare class HelixHeadlessTourStop extends HelixElement {
      * The id of the element the stop points at.
      */
     for: string;
+    /**
+     * The panel's name, where neither the `heading` slot nor the content holds a
+     * heading.
+     */
+    label: string;
     /**
      * Whether the stop is the last one. Its next control then shows `doneLabel`.
      */
@@ -101,10 +126,30 @@ export declare class HelixHeadlessTourStop extends HelixElement {
      * The side of the target the panel is placed on when there is room.
      */
     placement: Placement;
+    /**
+     * @internal Set by the tour: the stop's place in it, such as "2 of 5".
+     */
+    position: string;
+    /**
+     * @internal Set by the tour: whether the stop's place is drawn as well as
+     * read.
+     */
+    progress: boolean;
     /**
      * Label for the control that leaves the tour.
      */
     skipLabel: string;
+    /**
+     * What kind of stop this is. Unset, it is a bubble pointing at its target.
+     *
+     * - `dialog`: a panel in the middle of the window, over a backdrop
+     * - `floating`: a panel in a corner of the window
+     * - `wait`: nothing shown, while the tour waits for the target to be on the page
+     *
+     * Reflected, because the styled tier places a dialog and a floating panel by
+     * it, and unset at rest, so no default is written onto the host.
+     */
+    type?: 'dialog' | 'floating' | 'wait';
     /**
      * The side of its target the panel last landed on, which names the arrow's
      * second part. Undefined until the first placement, which the server never
@@ -123,9 +168,9 @@ export declare class HelixHeadlessTourStop extends HelixElement {
      */
     focus(options?: FocusOptions): void;
     /**
-     * Names the panel by the first heading in the content, by element
-     * reference: the heading is in the light DOM and the panel in this shadow
-     * root, which an IDREF cannot cross.
+     * Names and describes the panel, by element reference: the words are in the
+     * light DOM and the panel in this shadow root, which an IDREF cannot cross.
+     * `stopNaming` decides which words.
      */
     private nameByHeading;
     protected updated(changed: PropertyValues): void;

package/dist/tour/stop/tour-stop.js

@@ -4,10 +4,12 @@ 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, elementById, HelixElement, HelixTourAskEvent, PopoverController, } from '@fusion.dev/helix-core';
+import { arrowReach, customElement, elementById, HelixElement, HelixTourAskEvent, PopoverController, reflectElements, sideOf, } from '@fusion.dev/helix-core';
+import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import '../../button/index.js';
+import { stopNaming } from '../naming.js';
 let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
     constructor() {
         super(...arguments);
@@ -16,26 +18,30 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
         this.doneLabel = 'Done';
         this.first = false;
         this.for = '';
+        this.label = '';
         this.last = false;
         this.nextLabel = 'Next';
         this.placement = 'bottom';
+        this.position = '';
+        this.progress = false;
         this.skipLabel = 'Skip';
         this.floating = new PopoverController(this, {
             anchor: () => this.target,
             arrow: () => this.partNamed('arrow'),
             offset: () => {
                 const tour = this.parentElement;
-                return ((tour?.spotlightPadding ?? 0) + (this.partNamed('arrow')?.offsetWidth ?? 0) / Math.SQRT2);
+                return (tour?.spotlightPadding ?? 0) + arrowReach(this.partNamed('arrow'));
             },
             onDismiss: () => { },
             onPlace: (placement) => {
-                const side = placement.split('-')[0];
+                const side = sideOf(placement);
                 this.toggleState('placed-bottom', side === 'bottom');
                 this.toggleState('placed-left', side === 'left');
                 this.toggleState('placed-right', side === 'right');
                 this.toggleState('placed-top', side === 'top');
                 this.side = side;
             },
+            place: () => this.type === undefined,
             placement: () => this.placement,
             surface: () => this.partNamed('bubble'),
         });
@@ -53,17 +59,23 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
     }
     nameByHeading() {
         const bubble = this.partNamed('bubble');
-        if (!bubble || !('ariaLabelledByElements' in bubble)) {
-            return;
-        }
-        const heading = 'h1, h2, h3, h4, h5, h6, [role="heading"]';
-        const found = [...this.children].flatMap((one) => one.matches(heading) ? [one] : [...one.querySelectorAll(heading)])[0];
-        bubble.ariaLabelledByElements = found ? [found] : null;
+        const slotted = (name) => this.renderRoot
+            .querySelector(`slot[name="${name}"]`)
+            ?.assignedElements({ flatten: true }) ?? [];
+        const { describedBy, labelledBy } = stopNaming({
+            content: [...this.children].filter((one) => !one.slot),
+            description: slotted('description'),
+            heading: slotted('heading'),
+            labeled: this.label !== '',
+            progress: this.position === '' ? null : this.partNamed('progress'),
+        });
+        reflectElements(bubble, 'ariaLabelledByElements', labelledBy, true);
+        reflectElements(bubble, 'ariaDescribedByElements', describedBy, true);
     }
     updated(changed) {
         super.updated(changed);
         this.nameByHeading();
-        if (this.current) {
+        if (this.current && this.type !== 'wait') {
             this.floating.show();
         }
         else {
@@ -74,14 +86,14 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
         return html `<slot name="actions">
       <${this.tag('button')}
         part="skip"
-      exportparts="button: skip-button, text: skip-text" emphasis="ghost" @click=${() => this.ask('skip')}>
+      exportparts="button: skip-button, live: skip-live, text: skip-text" emphasis="ghost" @click=${() => this.ask('skip')}>
         ${this.skipLabel}
       </${this.tag('button')}>
       ${this.first
             ? ''
             : html `<${this.tag('button')}
               part="back"
-      exportparts="button: back-button, text: back-text"
+      exportparts="button: back-button, live: back-live, text: back-text"
               emphasis="outlined"
               @click=${() => this.ask('back')}
             >
@@ -89,7 +101,7 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
             </${this.tag('button')}>`}
       <${this.tag('button')}
         part="next"
-      exportparts="button: next-button, text: next-text"
+      exportparts="button: next-button, live: next-live, text: next-text"
         emphasis="solid"
         tone="primary"
         @click=${() => this.ask('next')}
@@ -102,16 +114,22 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
         return html `<div
       part="bubble"
       popover="manual"
-      role="group"
+      role=${this.type === 'dialog' ? 'dialog' : 'group'}
       tabindex="-1"
-      ?hidden=${!this.current}
+      aria-label=${this.label || nothing}
+      ?hidden=${!this.current || this.type === 'wait'}
     >
       ${''}
       <div
         part="arrow${this.side ? { bottom: ' arrow-bottom', left: ' arrow-left', right: ' arrow-right', top: ' arrow-top' }[this.side] : ''}"
         aria-hidden="true"
       ></div>
+      <slot name="heading" part="heading" @slotchange=${this.nameByHeading}></slot>
+      <slot name="description" part="description" @slotchange=${this.nameByHeading}></slot>
       <div part="content"><slot></slot></div>
+      ${this.position === ''
+            ? ''
+            : html `<span part="progress" ?hidden=${!this.progress}>${this.position}</span>`}
       <div part="actions">
         ${this.renderActions()}
       </div>
@@ -136,6 +154,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessTourStop.prototype, "for", void 0);
+__decorate([
+    property()
+], HelixHeadlessTourStop.prototype, "label", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessTourStop.prototype, "last", void 0);
@@ -145,9 +166,18 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessTourStop.prototype, "placement", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessTourStop.prototype, "position", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessTourStop.prototype, "progress", void 0);
 __decorate([
     property({ attribute: 'skip-label' })
 ], HelixHeadlessTourStop.prototype, "skipLabel", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessTourStop.prototype, "type", void 0);
 __decorate([
     state()
 ], HelixHeadlessTourStop.prototype, "side", void 0);

package/dist/tour/wait.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Calls `then` once `ready` answers yes: at once if it already does, and
+ * otherwise on the first change to the tree under `root` after which it does.
+ *
+ * What a tour's `wait` stop rests on: the tour waits for the element the stop
+ * names to be on the page, such as a menu the reader has to open, and moves on
+ * by itself. Returns a function that stops waiting.
+ */
+export declare const waitFor: (root: Node, ready: () => boolean, then: () => void) => (() => void);
+/** Whether an element is on the page and draws something a reader can see. */
+export declare const onPage: (element: Element | null | undefined) => boolean;

package/dist/tour/wait.js

@@ -0,0 +1,19 @@
+export const waitFor = (root, ready, then) => {
+    if (ready()) {
+        then();
+        return () => { };
+    }
+    if (typeof MutationObserver === 'undefined') {
+        return () => { };
+    }
+    const watcher = new MutationObserver(() => {
+        if (ready()) {
+            watcher.disconnect();
+            then();
+        }
+    });
+    watcher.observe(root, { attributes: true, childList: true, subtree: true });
+    return () => watcher.disconnect();
+};
+export const onPage = (element) => element?.isConnected === true &&
+    (typeof element.getClientRects !== 'function' || element.getClientRects().length > 0);

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

@@ -23,21 +23,33 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  * a `value` is chosen as well and sends `helix-select`, unless the tree has
  * `nesting="heading"`, where a branch names the list under it.
  *
+ * A `disabled` item is reached by the arrow keys and announced as unavailable,
+ * and a press, Enter or Space on it does nothing.
+ *
+ * A `lazy` item is a branch whose children you load when it opens: opening it
+ * sends `helix-load`, the row says it is busy, and the children you add appear
+ * in it. Remove `lazy` once they are in.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases TreeNode, Branch, Leaf
  * @documentation https://fusion.dev/helix/components/tree
  *
  * @slot - The item's label.
+ * @slot chevron - Replaces the expand and collapse mark of a branch, such as with your own icon.
  * @slot children - Nested items, which make this a branch.
  * @slot end - Content after the label, at the far side of the row, such as a count or a state.
  * @slot start - Content before the label and after the chevron, such as a mark for the item.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before a branch closes, and cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before a branch opens, and cancelable.
+ * @event {HelixLoadEvent} helix-load - Fired when a `lazy` item opens, so you can load its children.
  * @event {HelixSelectEvent} helix-select - Fired when the item is chosen, and cancelable. Canceling it changes nothing.
  * @event {ToggleEvent} toggle - Sent when the branch opens or closes, with `newState` and `oldState`.
  *
+ * @csspart checkbox - The check mark's box, in a tree with `selection-mode="multiple"`.
+ * @csspart checkbox-checked - The check mark's box while the item is checked.
+ * @csspart checkbox-mixed - The check mark's box while some of a branch's items are checked.
  * @csspart group - The container for nested items.
  * @csspart item - The node, and the focus target unless `href` moves it to the row.
  * @csspart label - The label text.
@@ -46,10 +58,26 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  *
  * @cssproperty --tree-level - How deep this row sits, counting from one as `aria-level` does, for the indent.
  *
+ * @cssstate loading - While a `lazy` item is open and its children have not arrived.
  * @cssstate open - While its children are shown.
  * @cssstate selected - While it is selected.
  */
 export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
+    /**
+     * @internal Set by the tree: whether the item draws a check mark and is
+     * checked rather than selected, as under `selection-mode="multiple"`.
+     */
+    checkable: boolean;
+    /**
+     * @internal Set by the tree in `selection-mode="multiple"`: whether the item
+     * is checked, `mixed` for a branch some of whose items are.
+     */
+    checked: boolean | 'mixed';
+    /**
+     * Whether the item cannot be chosen, opened or followed. The arrow keys still
+     * reach it, so a reader knows it is there.
+     */
+    disabled: boolean;
     /**
      * @internal Set by the tree: whether a branch heads the list under it, as
      * under `nesting="heading"`. Such a branch only opens and closes when it is
@@ -64,6 +92,13 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * current page on every item a consumer never asked to be one.
      */
     href: string;
+    /**
+     * Whether the item is a branch whose children are loaded when it opens.
+     *
+     * Opening it sends `helix-load`. Add the children to its `children` slot,
+     * and remove `lazy` once they are in, as Web Awesome's tree item does.
+     */
+    lazy: boolean;
     /**
      * The node's depth from the root. The tree counts it, so indentation needs no
      * nested CSS.
@@ -151,7 +186,7 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * row rather than the wrapper around it.
      */
     focusItem(): void;
-    /** Selects this node and sends `helix-select`. */
+    /** Selects this node and sends `helix-select`. A disabled node sends nothing. */
     select(): void;
     /**
      * Chooses this node, as a press or Enter does.
@@ -163,6 +198,13 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * value and nothing listens for it.
      */
     activate(): void;
+    /**
+     * Opens or closes a branch, unless the item is disabled.
+     *
+     * Every press and key that opens a branch comes through here, so `disabled`
+     * holds for all of them. A script can still set `open`.
+     */
+    toggleOpen(): boolean;
     /**
      * Follows a link slotted into the name, if there is one.
      *
@@ -184,8 +226,17 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * its children.
      */
     private follow;
+    /** A press on the check mark checks the item and leaves a branch as it is. */
+    private readonly handleCheckClick;
     private readonly handleToggleClick;
     private readonly handleRowClick;
+    /**
+     * The expand and collapse mark of a branch, as the `chevron` slot's
+     * fallback, so an icon of your own replaces it by being slotted.
+     */
+    protected renderToggle(): TemplateResult;
+    /** The check mark, in a tree with `selection-mode="multiple"`. */
+    private renderCheckbox;
     /** Everything inside the row, which is the same whichever element it is. */
     private renderRow;
     /**
@@ -204,6 +255,8 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * a consumer's markup means. What stops is the write back.
      */
     protected willUpdate(changed: PropertyValues): void;
+    /** Asks for a lazy branch's children when it opens. */
+    protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {