@fusion.dev/helix-headless 0.142.0 → 0.143.0

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { HelixElement, HostClickController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessToggle_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinSelectableItemInterface) & typeof HelixElement;
 /**
@@ -26,6 +26,8 @@ declare const HelixHeadlessToggle_base: (new (...args: any[]) => import("@fusion
  * @cssstate selected - The item is chosen.
  */
 export declare class HelixHeadlessToggle extends HelixHeadlessToggle_base {
+    /** A click on the element itself, `click()` included, chooses it, as on `Radio`. */
+    protected readonly clicks: HostClickController;
     /**
      * Whether the markup declares the item chosen. A form reset returns to it.
      *
@@ -56,23 +58,25 @@ export declare class HelixHeadlessToggle extends HelixHeadlessToggle_base {
     get defaultSelected(): boolean;
     set defaultSelected(next: boolean);
     /**
-     * Whether the item holds the group's tab stop while nothing is chosen.
+     * Whether the item holds the group's tab stop. Unset, the chosen item holds
+     * it.
      *
-     * The stop normally rides on the selection, and an unanswered group has no
-     * selection, so without this the keyboard cannot reach it. Written by the
-     * group, with no attribute: it is coordination between elements, and
-     * `tabindex` on a host the consumer rendered is the change a React consumer's
-     * hydration reports and does not patch up.
+     * Written by the group on every item: `true` for the chosen item, or for the
+     * first item that can be chosen while there is no selection to carry the
+     * stop, and `false` for every item, the chosen one too, while a toolbar the
+     * group sits in holds the stop. No attribute: it is coordination between
+     * elements, and `tabindex` on a host the consumer rendered is the change a
+     * React consumer's hydration reports and does not patch up.
      */
-    focusable: boolean;
+    focusable?: boolean;
     /**
      * Asks for the render that follows a hydration, so the stop stops being every
      * choice's.
      *
      * `tabindex` reads `childrenKnown` and a hydrating render is one where that is
      * false, which is what keeps the hydrating render the server's. Nothing else
-     * would ask: the group writes an already-false `focusable` onto every choice
-     * but one, which changes nothing and so re-renders nothing.
+     * is sure to ask: a write from the group that leaves `focusable` as it was
+     * re-renders nothing.
      */
     protected firstUpdated(changed: PropertyValues): void;
     protected render(): TemplateResult;

package/dist/toggle/root/toggle-root.js

@@ -4,13 +4,13 @@ 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, MixinSelectableItem } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, HostClickController, MixinSelectableItem, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessToggle = class HelixHeadlessToggle extends MixinSelectableItem(HelixElement) {
     constructor() {
         super(...arguments);
-        this.focusable = false;
+        this.clicks = new HostClickController(this, () => this.partNamed('item'));
     }
     get defaultSelected() {
         return this.hasAttribute('selected');
@@ -29,7 +29,7 @@ let HelixHeadlessToggle = class HelixHeadlessToggle extends MixinSelectableItem(
       role="radio"
       aria-checked=${this.selected ? 'true' : 'false'}
       ?disabled=${this.disabled}
-      tabindex=${this.selected || this.focusable || !this.childrenKnown ? '0' : '-1'}
+      tabindex=${(this.focusable ?? this.selected) || !this.childrenKnown ? '0' : '-1'}
       @click=${() => this.select()}
     >
       <slot></slot>

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

@@ -1,4 +1,4 @@
-import { HelixElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A group of controls that share one tab stop.
@@ -9,7 +9,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * The toolbar is one tab stop, and the arrow keys move between its controls, so
  * three toolbars take three presses of Tab to pass. Any element the browser can
- * focus counts as a control, including your own elements.
+ * focus counts as a control, including your own elements. A child that takes no
+ * focus, such as a divider, is skipped. A menu is reached at its trigger.
+ *
+ * A nested composite, such as a toggle group, is one stop on the toolbar's
+ * axis: the toolbar's arrows move past it, and the arrows across the toolbar
+ * move inside it. A composite with a `focusable` property, as Toggle Group
+ * has, gives up its own tab stop while the toolbar's is elsewhere, so Tab
+ * stops once in the toolbar. A composite without one keeps its own tab stop.
  *
  * @since 0.1.0
  * @status stable
@@ -24,27 +31,50 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 export declare class HelixHeadlessToolbar extends HelixElement {
     /**
      * The toolbar's name, read by screen readers.
+     *
+     * An `aria-label` or `aria-labelledby` on the host names the toolbar too,
+     * and wins over this.
      */
     label: string;
+    /** Carries a host `aria-label` and `aria-labelledby` to the toolbar. */
+    protected readonly aria: AriaForwardController;
+    /**
+     * Whether the stop has been written onto controls this package does not
+     * know, which happens on the first focus. From then on, every move of the
+     * stop has to write them too, or the one at `0` can be removed or disabled
+     * and leave every other one at `-1`.
+     */
+    private wroteForeign;
     /**
      * The direction the arrow keys move focus in.
      */
     orientation?: 'horizontal' | 'vertical';
     private watcher;
     /**
-     * Children that can take the tab stop, in document order.
-     *
-     * Every child that is not `disabled` and not `aria-hidden`, which is
-     * deliberately a test on the element rather than a list of tag names: a
-     * toolbar holds anything, including elements this package has never heard of.
-     * Client only, there being no tree to walk on the server.
+     * The children that take part in the toolbar, in document order, each with
+     * the elements in it that take focus.
      *
-     * **It does not ask a child whether it is focusable.** Reading a `focusable`
-     * property is what `setTabStop` does when moving the stop, not what this does
-     * when choosing the set, so an element that is neither disabled nor hidden and
-     * still cannot take focus is counted here and skipped there.
+     * A test on the element rather than a list of tag names: a toolbar holds
+     * anything, including elements this package has never heard of. A child
+     * that takes no focus and holds nothing that does is skipped. Client only,
+     * there being no tree to walk on the server.
      */
     private get controls();
+    /** The elements in a child's light DOM that take focus. */
+    private within;
+    /**
+     * The stops of a child that takes focus itself: the child, or the members of
+     * a composite that owns its tab stop, such as a toggle group, which the
+     * toolbar enters at a member and moves the stop of through `focusable`.
+     */
+    private inside;
+    /**
+     * Where focus lands on arriving at a control. A nested composite is entered
+     * at the stop it holds, which for a toggle group is the chosen toggle.
+     */
+    private entry;
+    /** The control a press or a focus came from, by its path. */
+    private origin;
     /**
      * Moves the single tab stop to one control.
      *
@@ -74,9 +104,10 @@ export declare class HelixHeadlessToolbar extends HelixElement {
      * already at `-1`, leaving a toolbar the keyboard cannot reach at all. A Save
      * button disabling itself once the form is clean is enough to do it.
      *
-     * `foreign` stays false, the same as the first claim: a control this package
-     * has never heard of that was never given `tabindex="-1"` is still in the
-     * document's own tab order, so it is never the one that gets stranded.
+     * `foreign` stays false, the same as the first claim, until a focus has
+     * written `tabindex="-1"` onto foreign controls. From then on `setTabStop`
+     * writes them as well, so removing or disabling the native button that held
+     * the stop hands it to the first one left.
      */
     private readonly restoreTabStop;
     /**
@@ -86,6 +117,15 @@ export declare class HelixHeadlessToolbar extends HelixElement {
      * so a reflected default cannot appear on the host after hydration.
      */
     private get axis();
+    /**
+     * The toolbar's own keys, from inside a nested composite.
+     *
+     * In capture, ahead of the composite, which answers every arrow itself and
+     * would otherwise hold the reader inside it. Only the keys along the
+     * toolbar's axis and Home and End are taken, so the arrows across it still
+     * move inside the composite.
+     */
+    private readonly handleCompositeKeydown;
     private readonly handleKeydown;
     connectedCallback(): void;
     disconnectedCallback(): void;

package/dist/toolbar/root/toolbar-root.js

@@ -4,28 +4,63 @@ 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, inlineStep, keyClaimed } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, HelixElement, inlineStep, keyClaimed, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 const KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End']);
 const ownsTabStop = (node) => 'focusable' in node;
+const NATIVE = 'a[href], button, input, select, textarea, [tabindex], [contenteditable=""], [contenteditable="true"]';
+const TABBABLE = NATIVE.replace('[tabindex]', '[tabindex]:not([tabindex="-1"])');
+const takesFocus = (node) => {
+    if (!(node instanceof HTMLElement) ||
+        node.hasAttribute('disabled') ||
+        node.getAttribute('aria-hidden') === 'true') {
+        return false;
+    }
+    return (node.matches(NATIVE) ||
+        ownsTabStop(node) ||
+        node.shadowRoot?.delegatesFocus === true ||
+        node.shadowRoot?.querySelector(TABBABLE) != null);
+};
 let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
     constructor() {
         super(...arguments);
         this.label = 'Toolbar';
+        this.aria = new AriaForwardController(this, {
+            label: true,
+            target: () => this.partNamed('toolbar'),
+        });
+        this.wroteForeign = false;
         this.handleFocusIn = (event) => {
-            const control = this.controls.find((entry) => entry.contains(event.target));
+            const control = this.origin(event);
             if (control) {
                 this.setTabStop(control);
             }
         };
         this.restoreTabStop = () => {
             const controls = this.controls;
-            const held = controls.some((control) => ownsTabStop(control) ? control.focusable : control.tabIndex === 0);
+            const held = controls.some((control) => {
+                const composite = control.stops.length !== 1;
+                const element = composite ? control.child : control.stops[0];
+                if (ownsTabStop(element)) {
+                    return element.focusable;
+                }
+                return composite || element.tabIndex === 0;
+            });
             if (controls.length > 0 && !held) {
                 this.setTabStop(controls[0], false);
             }
         };
+        this.handleCompositeKeydown = (event) => {
+            const control = this.origin(event);
+            if (!control || control.stops.length === 1) {
+                return;
+            }
+            this.handleKeydown(event);
+            if (event.defaultPrevented) {
+                event.stopPropagation();
+            }
+        };
         this.handleKeydown = (event) => {
             if (!KEYS.has(event.key) || keyClaimed(event)) {
                 return;
@@ -34,7 +69,8 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
             const forward = this.axis === 'horizontal' ? along === 1 : event.key === 'ArrowDown';
             const back = this.axis === 'horizontal' ? along === -1 : event.key === 'ArrowUp';
             const controls = this.controls;
-            const current = controls.findIndex((entry) => entry.contains(event.target));
+            const origin = this.origin(event);
+            const current = origin ? controls.findIndex((control) => control.child === origin.child) : -1;
             if (current === -1) {
                 return;
             }
@@ -57,30 +93,75 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
             event.preventDefault();
             const target = controls[next];
             this.setTabStop(target);
-            target?.focus();
+            const element = target ? this.entry(target) : undefined;
+            if (element && 'focusItem' in element && typeof element.focusItem === 'function') {
+                element.focusItem();
+            }
+            else {
+                element?.focus();
+            }
         };
     }
     get controls() {
-        return [...this.children].filter((child) => {
-            if (!(child instanceof HTMLElement)) {
-                return false;
+        const controls = [];
+        for (const child of this.children) {
+            if (!(child instanceof HTMLElement) ||
+                child.hasAttribute('disabled') ||
+                child.getAttribute('aria-hidden') === 'true') {
+                continue;
             }
-            return !child.hasAttribute('disabled') && child.getAttribute('aria-hidden') !== 'true';
-        });
+            const stops = takesFocus(child) ? this.inside(child) : this.within(child);
+            if (stops.length > 0) {
+                controls.push({ child, stops });
+            }
+        }
+        return controls;
+    }
+    within(child) {
+        return [...child.querySelectorAll('*')].filter(takesFocus);
+    }
+    inside(child) {
+        if (!ownsTabStop(child)) {
+            return [child];
+        }
+        const members = this.within(child);
+        return members.length > 1 ? members : [child];
+    }
+    entry(control) {
+        const { stops } = control;
+        if (stops.length === 1) {
+            return stops[0];
+        }
+        return (stops.find((stop) => (ownsTabStop(stop) && stop.focusable) ||
+            stop.selected === true) ?? stops[0]);
+    }
+    origin(event) {
+        const path = event.composedPath();
+        return this.controls.find((control) => control.stops.some((stop) => path.includes(stop)));
     }
     setTabStop(active, foreign = true) {
+        if (foreign) {
+            this.wroteForeign = true;
+        }
         for (const control of this.controls) {
-            const stop = control === active;
-            if (ownsTabStop(control)) {
-                control.focusable = stop;
+            if (control.stops.length !== 1) {
+                if (ownsTabStop(control.child)) {
+                    control.child.focusable = control.child === active?.child;
+                }
+                continue;
+            }
+            const element = control.stops[0];
+            const stop = control.child === active?.child;
+            if (ownsTabStop(element)) {
+                element.focusable = stop;
             }
-            else if (foreign) {
-                control.tabIndex = stop ? 0 : -1;
+            else if (foreign || this.wroteForeign) {
+                element.tabIndex = stop ? 0 : -1;
             }
         }
     }
     async claimTabStop() {
-        const pending = [...new Set(this.controls.map((control) => control.localName))].filter((name) => name.includes('-'));
+        const pending = [...new Set([...this.children].map((child) => child.localName))].filter((name) => name.includes('-'));
         await Promise.all(pending.map((name) => customElements.whenDefined(name)));
         this.setTabStop(this.controls[0], false);
     }
@@ -89,6 +170,7 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
     }
     connectedCallback() {
         super.connectedCallback();
+        this.addEventListener('keydown', this.handleCompositeKeydown, true);
         this.addEventListener('keydown', this.handleKeydown);
         this.addEventListener('focusin', this.handleFocusIn);
         this.watcher = new MutationObserver(this.restoreTabStop);
@@ -100,6 +182,7 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.removeEventListener('keydown', this.handleCompositeKeydown, true);
         this.removeEventListener('keydown', this.handleKeydown);
         this.removeEventListener('focusin', this.handleFocusIn);
         this.watcher?.disconnect();

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

@@ -27,7 +27,12 @@ declare const HelixHeadlessTooltip_base: (new (...args: any[]) => import("@fusio
  * `for`, the tooltip warns once on first open if the attribute is missing.
  *
  * The tooltip shows on hover and on focus. It hides on pointer leave, on blur,
- * on Escape, and when the trigger is activated.
+ * on Escape, and when the trigger is activated. The pointer can move from the
+ * trigger onto the bubble and the bubble stays.
+ *
+ * Once one tooltip is showing, moving to another trigger shows its tooltip
+ * with no `delay`, and the first one hides. The same holds for 300
+ * milliseconds after a tooltip hides.
  *
  * @since 0.1.0
  * @status stable
@@ -35,13 +40,15 @@ declare const HelixHeadlessTooltip_base: (new (...args: any[]) => import("@fusio
  * @aliases Hint, Popup label
  * @documentation https://fusion.dev/helix/components/tooltip
  *
- * @slot - The trigger: the element the tooltip describes.
+ * @slot - The trigger, in the wrapping form. A trigger here gets no
+ * description, so use it only where the trigger's name says what the tooltip
+ * says, and use `for` otherwise.
  * @slot content - Rich content for the bubble. It replaces the `content`
  * property.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - The bubble is about to hide. Cancelable: cancel it to keep it shown.
  * @event {HelixBeforeOpenEvent} helix-before-open - The bubble is about to show. Cancelable: cancel it to keep it hidden.
- * @event {Event} toggle - The bubble opened or closed. The event carries `newState` and `oldState`.
+ * @event {ToggleEvent} toggle - The bubble opened or closed. The event carries `newState` and `oldState`.
  *
  * @csspart arrow - The arrow that points at the trigger.
  * @csspart arrow-bottom - Added to `arrow` while the bubble is below its trigger, with the arrow on the bubble's top edge.
@@ -249,8 +256,27 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      * the reader had moved on to.
      */
     hide(): void;
-    /** Shows after the pointer has rested for `delay`. */
+    /**
+     * Shows after the pointer has rested for `delay`, or at once while the
+     * tooltips are warm.
+     *
+     * **Warm is another tooltip showing, or one that hid within `SKIP_DELAY`.**
+     * A reader scanning a toolbar has already waited once, and waiting again on
+     * every control turns the scan into a series of pauses.
+     */
     private readonly showLater;
+    /**
+     * The pointer reached the bubble, in the `for` form.
+     *
+     * The bubble is not inside the element `for` names, so moving onto it leaves
+     * the trigger and would hide it after `delay-out`. WCAG 1.4.13 asks that a
+     * reader can move onto it, to read it under a magnifier or to select its
+     * text. Wrapping, the bubble is inside the host and the host's own pointer
+     * listeners already hold it.
+     */
+    private readonly holdOnBubble;
+    /** The pointer left the bubble, in the `for` form. */
+    private readonly leaveBubble;
     /** Hides after `delayOut`, so crossing the gap to the bubble does not close it. */
     private readonly hideLater;
     /**
@@ -342,6 +368,13 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      * this should not be the thing to settle it.
      */
     private auditDescription;
+    /**
+     * Whether the wrapped trigger's own name is the tooltip's text.
+     *
+     * The name a consumer writes: `aria-label`, then a `label` a Helix control
+     * renders as its name, then the trigger's text.
+     */
+    private triggerSays;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected firstUpdated(changed: PropertyValues): void;

package/dist/tooltip/root/tooltip-root.js

@@ -8,6 +8,13 @@ import { anchorElement, customElement, elementById, HelixElement, hostAria, Mixi
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
 const GENERIC = new Set(['div', 'p', 'section', 'span']);
+const SKIP_DELAY = 300;
+const WARMTH = Symbol.for('fusion.helix.tooltip.warmth');
+const warmth = () => {
+    const globals = globalThis;
+    globals[WARMTH] ??= { hidAt: Number.NEGATIVE_INFINITY, showing: new Set() };
+    return globals[WARMTH];
+};
 let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
@@ -51,8 +58,26 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         this.showLater = () => {
             this.holds.add('pointer');
             clearTimeout(this.timer);
+            const warm = warmth();
+            const others = [...warm.showing].some((one) => one !== this);
+            if (others || performance.now() - warm.hidAt < SKIP_DELAY) {
+                this.show();
+                return;
+            }
             this.timer = setTimeout(() => this.show(), this.delay);
         };
+        this.holdOnBubble = () => {
+            if (!this.named) {
+                return;
+            }
+            this.holds.add('pointer');
+            clearTimeout(this.timer);
+        };
+        this.leaveBubble = () => {
+            if (this.named) {
+                this.hideLater();
+            }
+        };
         this.hideLater = () => {
             this.holds.delete('pointer');
             clearTimeout(this.timer);
@@ -175,6 +200,9 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         }
         this.audited = true;
         if (this.for === '') {
+            if (this.triggerSays(this.describedText)) {
+                return;
+            }
             reportRuntime({
                 kind: 'wrapped-trigger',
                 message: `<${this.localName}> is wrapping its trigger rather than naming one, so its text ` +
@@ -211,6 +239,12 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
             tag: this.localName,
         });
     }
+    triggerSays(text) {
+        const flat = (words) => (words ?? '').replace(/\s+/gu, ' ').trim();
+        const trigger = this.trigger;
+        const name = trigger.getAttribute('aria-label') ?? trigger.getAttribute('label') ?? trigger.textContent;
+        return text !== '' && flat(name) === flat(text);
+    }
     connectedCallback() {
         super.connectedCallback();
         if (this.hasUpdated) {
@@ -222,6 +256,7 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         this.unbind();
         this.holds.clear();
         clearTimeout(this.timer);
+        warmth().showing.delete(this);
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -233,11 +268,22 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
             this.bind();
         }
         if (changed.has('open')) {
+            const warm = warmth();
             if (this.open) {
+                for (const other of [...warm.showing]) {
+                    if (other !== this) {
+                        other.holds.clear();
+                        other.hide();
+                    }
+                }
+                warm.showing.add(this);
                 this.bubbleLayer.show();
                 this.auditDescription();
             }
             else {
+                if (warm.showing.delete(this)) {
+                    warm.hidAt = performance.now();
+                }
                 this.bubbleLayer.hide();
             }
         }
@@ -257,6 +303,8 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         part="tooltip${side ? { bottom: ' tooltip-bottom', left: ' tooltip-left', right: ' tooltip-right', top: ' tooltip-top' }[side] : ''}"
         popover="manual"
         role="tooltip"
+        @pointerenter=${this.holdOnBubble}
+        @pointerleave=${this.leaveBubble}
       >
         <span
           part="arrow${side ? { bottom: ' arrow-bottom', left: ' arrow-left', right: ' arrow-right', top: ' arrow-top' }[side] : ''}"

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

@@ -1,6 +1,7 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
+declare const HelixHeadlessTour_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
  * @summary A guided tour of an interface, one stop at a time.
  *
@@ -17,6 +18,16 @@ import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
  * The root measures the target's position in the browser. Nothing is measured
  * on the server, because a tour starts only on request.
  *
+ * `open`, `default-open`, `helix-before-open`, `helix-before-close` and
+ * `toggle` work as they do on `Dialog`. Setting `open` starts the run, and
+ * `skip()` and `requestOpen(false)` end it early.
+ *
+ * **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
+ * you have moved it somewhere else on the page. A stop does not trap focus, so
+ * you can still `Tab` out to the element it describes.
+ *
  * @since 0.1.0
  * @status stable
  * @category overlays
@@ -25,15 +36,20 @@ import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
  *
  * @slot - The stops, in the order they are shown.
  *
+ * @event {HelixActivateEvent} helix-activate - Fired after the current stop changes, with the new index.
  * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current stop changes, with the new index. Cancelable: call `preventDefault()` to stay on the current stop.
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the user ends the tour early. Cancelable: call `preventDefault()` to keep the tour open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before `requestOpen(true)` starts the tour. Cancelable: call `preventDefault()` to keep it closed.
  * @event {HelixCompleteEvent} helix-complete - Fired when the last stop is
  * finished.
  * @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 spotlight - The box over the current target. It also draws the dimmed area around the target.
+ *
+ * @cssstate open - While the tour is running.
  */
-export declare class HelixHeadlessTour extends HelixElement {
+export declare class HelixHeadlessTour extends HelixHeadlessTour_base {
     /**
      * Label for the control that goes back, passed to every stop.
      */
@@ -70,10 +86,6 @@ export declare class HelixHeadlessTour extends HelixElement {
      * Label for the control that goes on.
      */
     nextLabel: string;
-    /**
-     * Whether the tour is running.
-     */
-    open: boolean;
     /**
      * Label for the control that leaves the tour.
      */
@@ -121,6 +133,22 @@ export declare class HelixHeadlessTour extends HelixElement {
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** Where focus was when the tour opened, to give it back when it ends. */
+    private returnFocus;
+    /** Whether `follow` has seen the first update. */
+    private followed;
+    /**
+     * Moves focus with the run.
+     *
+     * Opening takes it to the current stop. Moving takes it to the new stop when
+     * it was in the tour, which is where a reader pressing Next is, and leaves it
+     * where it is otherwise. Closing gives it back to where it was before, again
+     * only when it was in the tour: a reader who moved to the target has chosen
+     * where to be.
+     */
+    private follow;
+    /** Focuses the current stop's panel once the stop has shown it. */
+    private focusCurrent;
     /**
      * Tells each stop where it is in the run.
      *
@@ -143,3 +171,4 @@ declare global {
         'helix-headless-tour': HelixHeadlessTour;
     }
 }
+export {};