@fusion.dev/helix-headless 0.142.1 → 0.144.0

package/dist/tour/root/tour-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 { customElement, HelixBeforeActivateEvent, HelixBeforeCloseEvent, HelixCompleteEvent, HelixElement, hostAria, 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';
-let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
+import { onPage, waitFor } from '../wait.js';
+let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
         this.backLabel = '';
@@ -16,7 +17,8 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
         this.indexState = undefined;
         this.label = '';
         this.nextLabel = '';
-        this.open = false;
+        this.progress = false;
+        this.progressLabel = '{index} of {count}';
         this.skipLabel = '';
         this.spotlightPadding = 8;
         this.sizer = undefined;
@@ -42,6 +44,8 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
         this.handleViewport = () => {
             this.light();
         };
+        this.followed = false;
+        this.veiled = false;
     }
     get index() {
         return this.indexState ?? this.defaultIndex;
@@ -71,19 +75,14 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
         this.move(this.index - 1);
     }
     skip() {
-        const event = new HelixBeforeCloseEvent();
-        this.dispatchEvent(event);
-        if (event.defaultPrevented) {
-            return;
-        }
-        this.open = false;
+        this.requestOpen(false);
     }
     finish() {
         this.dispatchEvent(new HelixCompleteEvent({ value: String(this.index) }));
         this.open = false;
     }
     move(to) {
-        requestChange({
+        const moved = requestChange({
             apply: (value) => {
                 this.index = value;
             },
@@ -91,6 +90,9 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
             host: this,
             next: to,
         });
+        if (moved) {
+            this.dispatchEvent(new HelixActivateEvent({ value: String(this.index) }));
+        }
     }
     connectedCallback() {
         super.connectedCallback();
@@ -110,15 +112,61 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
         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);
-        hostAria(this.internals, { label: this.label, role: 'region' });
+        hostAria(this.internals, {
+            label: this.open ? this.label : '',
+            role: this.open ? 'region' : '',
+        });
     }
     updated(changed) {
         super.updated(changed);
         this.settle();
         this.light();
+        this.follow(changed);
+        this.wait();
+    }
+    follow(changed) {
+        if (!this.followed) {
+            this.followed = true;
+            return;
+        }
+        const opened = changed.has('open') && this.open && changed.get('open') === false;
+        const closed = changed.has('open') && !this.open && changed.get('open') === true;
+        const active = deepActiveElement();
+        const inside = active === null || active === document.body || deepContains(this, active);
+        if (opened) {
+            if (active instanceof HTMLElement && !deepContains(this, active)) {
+                this.returnFocus = active;
+            }
+            this.focusCurrent();
+        }
+        else if (closed) {
+            const back = this.returnFocus;
+            this.returnFocus = undefined;
+            if (inside && back?.isConnected) {
+                back.focus();
+            }
+        }
+        else if (this.open && changed.has('index') && inside) {
+            this.focusCurrent();
+        }
+    }
+    focusCurrent() {
+        const stops = this.stops;
+        const stop = stops[Math.max(0, Math.min(this.index, stops.length - 1))];
+        if (!stop) {
+            return;
+        }
+        void stop.updateComplete.then(() => {
+            if (this.open && stop.current) {
+                stop.focus();
+            }
+        });
     }
     settle() {
         const stops = this.stops;
@@ -128,6 +176,11 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
                 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;
                 }
@@ -144,12 +197,41 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
         });
     }
     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') {
@@ -187,7 +269,7 @@ let HelixHeadlessTour = class HelixHeadlessTour extends HelixElement {
     }
     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"
@@ -216,8 +298,11 @@ __decorate([
     property({ attribute: 'next-label' })
 ], HelixHeadlessTour.prototype, "nextLabel", void 0);
 __decorate([
-    property({ reflect: true, type: Boolean })
-], HelixHeadlessTour.prototype, "open", void 0);
+    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);
@@ -230,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,6 +34,13 @@ 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`, 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
  * @category overlays
@@ -32,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.
  *
@@ -43,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.
@@ -85,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`.
      */
@@ -97,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
@@ -110,7 +159,20 @@ export declare class HelixHeadlessTourStop extends HelixElement {
     /** The element the stop points at, or `null` when no element has the `for` id. */
     get target(): HTMLElement | null;
     private readonly floating;
-    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Moves focus to the panel while the stop is shown.
+     *
+     * The host draws no box and takes no focus, so focusing it did nothing. The
+     * panel takes focus without joining the `Tab` order, and a screen reader
+     * reads the group it is.
+     */
+    focus(options?: FocusOptions): void;
+    /**
+     * 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;
     /**
      * Skip, back and next, behind a seam the styled tier can move.

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, hostAria, 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'),
         });
@@ -43,13 +49,33 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
     get target() {
         return this.for === '' ? null : elementById(this, this.for);
     }
-    willUpdate(changed) {
-        super.willUpdate(changed);
-        hostAria(this.internals, { role: 'group' });
+    focus(options) {
+        const bubble = this.partNamed('bubble');
+        if (this.current && bubble) {
+            bubble.focus(options);
+            return;
+        }
+        super.focus(options);
+    }
+    nameByHeading() {
+        const bubble = this.partNamed('bubble');
+        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);
-        if (this.current) {
+        this.nameByHeading();
+        if (this.current && this.type !== 'wait') {
             this.floating.show();
         }
         else {
@@ -60,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')}
             >
@@ -75,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')}
@@ -85,13 +111,25 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
     </slot>`;
     }
     render() {
-        return html `<div part="bubble" popover="manual" ?hidden=${!this.current}>
+        return html `<div
+      part="bubble"
+      popover="manual"
+      role=${this.type === 'dialog' ? 'dialog' : 'group'}
+      tabindex="-1"
+      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>
@@ -116,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);
@@ -125,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

@@ -19,6 +19,10 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  * **`href` makes the whole row a link**, rendered as an `<a>`. Enter, middle
  * click, and the status bar then work anywhere on the row.
  *
+ * Pressing a branch, or Enter or Space on it, opens or closes it. A branch with
+ * a `value` is chosen as well and sends `helix-select`, unless the tree has
+ * `nesting="heading"`, where a branch names the list under it.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases TreeNode, Branch, Leaf
@@ -32,7 +36,7 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  * @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 {HelixSelectEvent} helix-select - Fired when the item is chosen, and cancelable. Canceling it changes nothing.
- * @event {Event} toggle - Sent when the branch opens or closes, with `newState` and `oldState`.
+ * @event {ToggleEvent} toggle - Sent when the branch opens or closes, with `newState` and `oldState`.
  *
  * @csspart group - The container for nested items.
  * @csspart item - The node, and the focus target unless `href` moves it to the row.
@@ -46,6 +50,12 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  * @cssstate selected - While it is selected.
  */
 export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
+    /**
+     * @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
+     * pressed, because it names a list and is not a destination of its own.
+     */
+    heads: boolean;
     /**
      * The URL this node links to. Setting it makes the row a link.
      *
@@ -101,14 +111,14 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * Where the link opens. Use it for a row that leaves the site.
      */
     target: string;
-    /**
-     * Identifies the item to your code. It is sent in `helix-select`.
-     */
-    value: string;
     /**
      * Whether this item holds the tree's single tab stop.
      */
     focusable: boolean;
+    /**
+     * Identifies the item to your code. It is sent in `helix-select`.
+     */
+    value: string;
     /**
      * Whether anything is slotted into `children`.
      *
@@ -119,6 +129,12 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      */
     private branch;
     protected firstUpdated(changed: PropertyValues): void;
+    /**
+     * @internal Whether pressing this branch chooses it as well as opening or
+     * closing it: it has a value and does not head its list. Read by the tree
+     * for Enter and Space.
+     */
+    get choosable(): boolean;
     /**
      * @internal Whether this row holds children, read by the tree, which moves
      * and opens differently for a branch. Public rather than protected because

package/dist/tree/item/tree-item.js

@@ -12,12 +12,13 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
+        this.heads = false;
         this.href = '';
         this.rel = '';
         this.selected = false;
         this.target = '';
-        this.value = '';
         this.focusable = false;
+        this.value = '';
         this.branch = false;
         this.handleToggleClick = (event) => {
             event.preventDefault();
@@ -28,6 +29,9 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
             const onLink = event.composedPath().some((node) => node instanceof HTMLAnchorElement);
             if (this.branch && this.href === '') {
                 if (!onLink) {
+                    if (this.choosable) {
+                        this.select();
+                    }
                     this.toggleOpen();
                 }
                 return;
@@ -46,6 +50,9 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
             this.branch = slot.assignedElements().length > 0;
         });
     }
+    get choosable() {
+        return this.value !== '' && !this.heads;
+    }
     get isBranch() {
         return this.branch;
     }
@@ -145,6 +152,9 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
       </div>`;
     }
 };
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessTreeItem.prototype, "heads", void 0);
 __decorate([
     property()
 ], HelixHeadlessTreeItem.prototype, "href", void 0);
@@ -160,12 +170,12 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessTreeItem.prototype, "target", void 0);
-__decorate([
-    property()
-], HelixHeadlessTreeItem.prototype, "value", void 0);
 __decorate([
     state()
 ], HelixHeadlessTreeItem.prototype, "focusable", void 0);
+__decorate([
+    property()
+], HelixHeadlessTreeItem.prototype, "value", void 0);
 __decorate([
     state()
 ], HelixHeadlessTreeItem.prototype, "branch", void 0);