@fusion.dev/helix-headless 0.157.0 → 0.159.0

package/dist/tabs/root/tabs-root.js

@@ -33,10 +33,14 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
         this.manual = false;
         this.scrollControls = false;
         this.handleSelection = (event) => {
-            if (event.defaultPrevented || !this.tabs.includes(event.target)) {
+            if (!this.tabs.includes(event.target)) {
                 return;
             }
-            this.requestActive(event.detail.value);
+            queueMicrotask(() => {
+                if (!event.defaultPrevented) {
+                    this.requestActive(event.detail.value);
+                }
+            });
         };
         this.more = { end: false, start: false };
         this.measure = () => {
@@ -89,12 +93,19 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
         const behavior = matchMedia('(prefers-reduced-motion: reduce)').matches ? 'auto' : 'smooth';
         strip.scrollBy(down ? { behavior, top: by } : { behavior, left: isRtl(this) ? -by : by });
     }
+    beside(gone, tabs) {
+        const at = this.held.indexOf(gone);
+        const by = new Map(tabs.map((tab) => [tab.value, tab]));
+        const order = [...this.held.slice(at + 1), ...this.held.slice(0, at).reverse()];
+        return order.map((value) => by.get(value)).find((tab) => tab !== undefined && !tab.disabled);
+    }
     sync() {
         const tabs = this.tabs;
         const declared = this.active === '' ? tabs.find((tab) => tab.selected) : undefined;
-        const value = (declared ?? this.resolveActive(tabs))?.value ?? '';
         const previous = this.active;
         const gone = this.held.includes(previous) && !tabs.some((tab) => tab.value === previous);
+        const value = (declared ?? (gone ? this.beside(previous, tabs) : undefined) ?? this.resolveActive(tabs))
+            ?.value ?? '';
         this.held = tabs.map((tab) => tab.value);
         if (gone && value !== '') {
             this.active = value;
@@ -192,19 +203,19 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
         if (!this.scrollControls) {
             return nothing;
         }
-        const down = this.orientation === 'vertical';
-        const icon = down ? (toward > 0 ? caretDown : caretUp) : toward > 0 ? caretRight : caretLeft;
-        const glyph = html `<svg
-      data-mirror=${down ? nothing : ''}
-      aria-hidden="true"
-      fill="currentColor"
-      viewBox=${icon.viewBox}
-    >${unsafeSVG(icon.content)}</svg>`;
         const shown = toward > 0 ? this.more.end : this.more.start;
         const keepFocus = (event) => event.preventDefault();
         return toward > 0
-            ? html `<button part="scroll-end" type="button" tabindex="-1" aria-hidden="true" ?hidden=${!shown} @mousedown=${keepFocus} @click=${() => this.scrollStrip(1)}>${glyph}</button>`
-            : html `<button part="scroll-start" type="button" tabindex="-1" aria-hidden="true" ?hidden=${!shown} @mousedown=${keepFocus} @click=${() => this.scrollStrip(-1)}>${glyph}</button>`;
+            ? html `<button part="scroll-end" type="button" tabindex="-1" aria-hidden="true" ?hidden=${!shown} @mousedown=${keepFocus} @click=${() => this.scrollStrip(1)}>${this.renderScrollIcon(1)}</button>`
+            : html `<button part="scroll-start" type="button" tabindex="-1" aria-hidden="true" ?hidden=${!shown} @mousedown=${keepFocus} @click=${() => this.scrollStrip(-1)}>${this.renderScrollIcon(-1)}</button>`;
+    }
+    renderScrollIcon(toward) {
+        const down = this.orientation === 'vertical';
+        const icon = down ? (toward > 0 ? caretDown : caretUp) : toward > 0 ? caretRight : caretLeft;
+        const mirror = down ? nothing : '';
+        return toward > 0
+            ? html `<slot name="scroll-end-icon"><svg part="scroll-end-mark" data-mirror=${mirror} aria-hidden="true" fill="currentColor" viewBox=${icon.viewBox}>${unsafeSVG(icon.content)}</svg></slot>`
+            : html `<slot name="scroll-start-icon"><svg part="scroll-start-mark" data-mirror=${mirror} aria-hidden="true" fill="currentColor" viewBox=${icon.viewBox}>${unsafeSVG(icon.content)}</svg></slot>`;
     }
     render() {
         return html `<div

package/dist/tabs/tab/tab.d.ts

@@ -16,8 +16,8 @@ declare const HelixHeadlessTab_base: (new (...args: any[]) => import("@fusion.de
  * can: a press on its `dismiss` mark, or Delete or Backspace while the tab
  * has focus, sends `helix-dismiss`. The tab does not remove itself, because
  * your code owns the set, so remove the tab and its panel in your handler.
- * Focus moves to the tab beside it, and the tab set selects a tab that is
- * left.
+ * Focus moves to the tab beside it, and where the tab was selected, the tab
+ * set selects that same tab.
  * The tab says the key through `aria-keyshortcuts`, and the mark is for the
  * pointer, hidden from screen readers.
  *
@@ -27,11 +27,13 @@ declare const HelixHeadlessTab_base: (new (...args: any[]) => import("@fusion.de
  * @documentation https://fusion.dev/helix/components/tabs
  *
  * @slot - The tab's label.
+ * @slot dismiss-icon - Replaces the glyph on the mark that closes a `dismissible` tab.
  *
  * @event {HelixDismissEvent} helix-dismiss - A `dismissible` tab was asked to close. The tab does not remove itself, so remove it and its panel in response. Cancelable.
  * @event {HelixSelectEvent} helix-select - Fired when the tab is chosen. Cancelable: canceling it stops the change and leaves the decision to you.
  *
  * @csspart dismiss - The mark a pointer presses to close a `dismissible` tab.
+ * @csspart dismiss-mark - The glyph on that mark, where none is slotted.
  * @csspart tab - The tab itself.
  *
  * @cssstate selected - While it is the tab selected.

package/dist/tabs/tab/tab.js

@@ -53,7 +53,9 @@ let HelixHeadlessTab = class HelixHeadlessTab extends MixinDismissible(MixinSele
             return nothing;
         }
         return html `<span part="dismiss" aria-hidden="true" title=${this.dismissLabel} @click=${this.handleDismissPress}
-      ><svg fill="currentColor" viewBox=${x.viewBox} aria-hidden="true">${unsafeSVG(x.content)}</svg></span
+      ><slot name="dismiss-icon"
+        ><svg part="dismiss-mark" fill="currentColor" viewBox=${x.viewBox} aria-hidden="true">${unsafeSVG(x.content)}</svg></slot
+      ></span
     >`;
     }
     updated(changed) {

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

@@ -10,8 +10,9 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  *
  * **Each item runs its own timer.** A timer held by the region would restart
  * with each new message, and the last of three messages would stay for nine
- * seconds. It pauses while the pointer or focus is on the message, and while
- * the page is hidden, so a message is not spent in a background tab.
+ * seconds. It pauses while the pointer or focus is on the message or anywhere
+ * in the region's stack, and while the page is hidden, so a message is not
+ * spent in a background tab.
  *
  * **Each message is an `alertdialog` named by its words**, which is how a reader
  * who moves into the stack hears which message they are on. Give it a
@@ -20,10 +21,11 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  * says each message once as it arrives, a `danger` one assertively, so a
  * message is never a live region of its own.
  *
- * A touch or a pen swipes a message toward the end of the line, and past
- * halfway, or quickly, dismisses it through the same `helix-dismiss` as its
- * control. While it moves, the distance is on the `item` part as
- * `--toast-swipe-x`.
+ * A touch or a pen swipes a message toward the end of the line, or toward the
+ * edge the region's `swipe-direction` names, and past halfway, or quickly,
+ * dismisses it through the same `helix-dismiss` as its control. While it
+ * moves, the distance is on the `item` part as `--toast-swipe-x` or
+ * `--toast-swipe-y`.
  *
  * **Escape dismisses the message holding focus**, through the same
  * `helix-dismiss`, and focus moves to the next message.
@@ -60,9 +62,10 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  *
  * @cssproperty --toast-duration - How long this message stays, in milliseconds, for a progress hint.
  * @cssproperty --toast-swipe-x - How far a swipe has moved the message across, in pixels, toward the right.
+ * @cssproperty --toast-swipe-y - How far a swipe has moved the message down, in pixels, under a `swipe-direction` of `top` or `bottom`.
  *
  * @cssstate closed - The message has been dismissed and is hidden, or leaving.
- * @cssstate paused - The dismiss timer is paused, while a pointer or focus is on the message, or while the page is hidden.
+ * @cssstate paused - The dismiss timer is paused, while a pointer or focus is on the message or in the stack, or while the page is hidden.
  * @cssstate waiting - The region holds the message back, past its `max-visible`, until a message before it goes.
  */
 export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base {
@@ -96,8 +99,24 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
      */
     get open(): boolean;
     set open(next: boolean);
+    /**
+     * @internal Set by the region: whether a pointer or focus in the stack holds
+     * this message's timer.
+     */
+    regionHeld: boolean;
+    /**
+     * @internal Set by the region: the edge a swipe dismisses toward, from its
+     * `swipe-direction`.
+     */
+    swipeToward: 'bottom' | 'end' | 'start' | 'top';
+    /** Whether the timer is held for `regionHeld`, so the hold is let go once. */
+    private regionHolding;
+    /** Holds the timer while the region asks, and lets it go once. */
+    private holdForRegion;
+    /** The physical edge a swipe dismisses toward. */
+    private get swipeTo();
     protected readonly swipes: SwipeController;
-    /** Writes how far a swipe has moved the message toward the end of the line. */
+    /** Writes how far a swipe has moved the message toward its edge. */
     private slide;
     /**
      * The dismiss timer, which pauses while a reader is on the message, and

package/dist/toast/item/toast-item.js

@@ -4,30 +4,34 @@ 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 { CountdownController, customElement, drawDismiss, drawDismissGlyph, HelixElement, hostAria, isRtl, MixinDismissible, requestChange, SwipeController, settleSwipe, swipeEdge, toneMark, towardEdge, } from '@fusion.dev/helix-core';
+import { CountdownController, customElement, drawDismiss, drawDismissGlyph, edgeOffset, HelixElement, hostAria, isRtl, MixinDismissible, requestChange, SwipeController, settleSwipe, swipeAxis, swipeEdge, toneMark, towardEdge, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissible(HelixElement) {
     constructor() {
         super(...arguments);
+        this.regionHeld = false;
+        this.swipeToward = 'end';
+        this.regionHolding = false;
         this.swipes = new SwipeController(this, {
-            axis: () => (this.open ? 'x' : undefined),
-            end: (dx, _dy, vx) => {
-                const edge = swipeEdge('end', isRtl(this));
-                const width = this.partNamed('item')?.getBoundingClientRect().width ?? 0;
+            axis: () => (this.open ? swipeAxis(this.swipeTo) : undefined),
+            end: (dx, dy, vx, vy) => {
+                const edge = this.swipeTo;
+                const box = this.partNamed('item')?.getBoundingClientRect();
+                const across = swipeAxis(edge) === 'x';
                 const shown = settleSwipe({
                     points: [1],
-                    size: width,
-                    travel: Math.max(0, towardEdge(edge, dx, 0)),
-                    velocity: towardEdge(edge, vx, 0),
+                    size: (across ? box?.width : box?.height) ?? 0,
+                    travel: Math.max(0, towardEdge(edge, dx, dy)),
+                    velocity: towardEdge(edge, vx, vy),
                 });
                 if (shown === 0 && this.dismiss()) {
                     return;
                 }
                 this.slide(0);
             },
-            move: (dx) => this.slide(Math.max(0, towardEdge(swipeEdge('end', isRtl(this)), dx, 0))),
+            move: (dx, dy) => this.slide(Math.max(0, towardEdge(this.swipeTo, dx, dy))),
             start: (_target, event) => event.pointerType !== 'mouse',
             surface: () => this.partNamed('item'),
         });
@@ -81,9 +85,27 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         this.openState = next;
         this.requestUpdate('open', previous);
     }
+    holdForRegion() {
+        const want = this.regionHeld && this.isConnected;
+        if (want === this.regionHolding) {
+            return;
+        }
+        this.regionHolding = want;
+        if (want) {
+            this.countdown.hold();
+        }
+        else {
+            this.countdown.release();
+        }
+    }
+    get swipeTo() {
+        return swipeEdge(this.swipeToward, isRtl(this));
+    }
     slide(travel) {
-        const physical = isRtl(this) ? -travel : travel;
-        this.partNamed('item')?.style.setProperty('--toast-swipe-x', travel === 0 ? '' : `${Math.round(physical)}px`);
+        const item = this.partNamed('item');
+        const { x, y } = edgeOffset(this.swipeTo, travel);
+        item?.style.setProperty('--toast-swipe-x', x === 0 ? '' : `${Math.round(x)}px`);
+        item?.style.setProperty('--toast-swipe-y', y === 0 ? '' : `${Math.round(y)}px`);
     }
     wait(waiting) {
         if (waiting) {
@@ -133,12 +155,14 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
             else {
                 this.resume();
             }
+            this.holdForRegion();
         }
         this.addEventListener('keydown', this.handleKeydown);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.holding = false;
+        this.regionHolding = false;
         this.removeEventListener('keydown', this.handleKeydown);
     }
     willUpdate(changed) {
@@ -156,6 +180,12 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         if (changed.has('waiting')) {
             this.wait(this.waiting);
         }
+        if (changed.has('regionHeld')) {
+            this.holdForRegion();
+        }
+        if (changed.has('swipeToward')) {
+            this.partNamed('item')?.style.setProperty('touch-action', swipeAxis(this.swipeTo) === 'y' ? 'pan-x' : '');
+        }
     }
     assigned(name) {
         return (this.renderRoot
@@ -229,6 +259,12 @@ __decorate([
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessToastItem.prototype, "open", null);
+__decorate([
+    property({ attribute: false, type: Boolean })
+], HelixHeadlessToastItem.prototype, "regionHeld", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessToastItem.prototype, "swipeToward", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessToastItem.prototype, "tone", void 0);

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

@@ -34,7 +34,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * to render them from: it appends a message of the region's own tier and
  * removes it once it has been dismissed and has finished leaving. Messages
  * you render yourself stay yours, and the region never removes them. A touch
- * or a pen swipes a message away toward the end of the line.
+ * or a pen swipes a message away toward the end of the line, or toward the
+ * edge `swipe-direction` names.
+ *
+ * **Every message's timer waits while a pointer or focus is in the stack**, as
+ * React Aria's and Radix's regions do, so a reader moving from one message to
+ * the next does not lose the one behind them.
  *
  * **The stack is in the top layer.** The `region` part is a `popover="manual"`
  * shown while a message is showing, and shown again above a modal dialog that
@@ -127,6 +132,11 @@ export declare class HelixHeadlessToast extends HelixElement {
      * departures, which is what `orientation` does.
      */
     placement?: 'bottom-center' | 'bottom-end' | 'bottom-start' | 'top-center' | 'top-end' | 'top-start';
+    /**
+     * The edge a touch or a pen swipes a message toward to dismiss it: `end`,
+     * the end of the line, or `start`, `top` or `bottom`. Unset is `end`.
+     */
+    swipeDirection?: 'bottom' | 'end' | 'start' | 'top';
     protected willUpdate(changed: PropertyValues): void;
     /** What the polite region is saying. */
     private said;
@@ -190,6 +200,19 @@ export declare class HelixHeadlessToast extends HelixElement {
     private watcher;
     /** The messages that are showing, in order. */
     private get showing();
+    /** Whether a pointer is over the stack. */
+    private pointerIn;
+    /** Whether focus is in the stack. */
+    private focusIn;
+    /**
+     * Tells every message whether the stack holds its timer and which way it
+     * swipes, which only the region knows.
+     */
+    private inform;
+    private readonly handlePointerEnter;
+    private readonly handlePointerLeave;
+    /** Focus leaving the stack, and not moving between its messages. */
+    private readonly handleFocusOut;
     /** The messages `max-visible` holds back. */
     private readonly held;
     /**

package/dist/toast/root/toast-root.js

@@ -40,12 +40,34 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
             }
         };
         this.made = new WeakSet();
+        this.pointerIn = false;
+        this.focusIn = false;
+        this.handlePointerEnter = () => {
+            this.pointerIn = true;
+            this.inform();
+        };
+        this.handlePointerLeave = () => {
+            this.pointerIn = false;
+            this.inform();
+        };
+        this.handleFocusOut = (event) => {
+            const next = event.relatedTarget;
+            if (next instanceof Node && deepContains(this, next)) {
+                return;
+            }
+            this.focusIn = false;
+            this.inform();
+        };
         this.held = new WeakSet();
         this.handleFocusIn = (event) => {
             const from = event.relatedTarget;
             if (from instanceof HTMLElement && !deepContains(this, from)) {
                 this.focusOrigin = from;
             }
+            if (!this.focusIn) {
+                this.focusIn = true;
+                this.inform();
+            }
         };
         this.handleDismiss = (event) => {
             const item = event.target;
@@ -177,6 +199,22 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
     get showing() {
         return [...this.children].filter((one) => one instanceof HTMLElement && !one.hidden && !this.held.has(one));
     }
+    inform() {
+        const held = this.pointerIn || this.focusIn;
+        for (const one of this.children) {
+            const item = one;
+            if (!('regionHeld' in item)) {
+                continue;
+            }
+            if (item.regionHeld !== held) {
+                item.regionHeld = held;
+            }
+            const toward = this.swipeDirection ?? 'end';
+            if (item.swipeToward !== toward) {
+                item.swipeToward = toward;
+            }
+        }
+    }
     queue() {
         const max = this.maxVisible;
         const line = [...this.children].filter((one) => one instanceof HTMLElement && one.open !== false);
@@ -267,11 +305,15 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('focusin', this.handleFocusIn);
+        this.addEventListener('focusout', this.handleFocusOut);
+        this.addEventListener('pointerenter', this.handlePointerEnter);
+        this.addEventListener('pointerleave', this.handlePointerLeave);
         this.addEventListener('helix-dismiss', this.handleDismiss);
         document.addEventListener('keydown', this.handleHotkey);
         this.watcher = new MutationObserver((records) => {
             const added = records.flatMap((record) => [...record.addedNodes]);
             this.restack();
+            this.inform();
             this.place(added);
             this.tell(added);
             this.sweep();
@@ -289,7 +331,12 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('focusin', this.handleFocusIn);
+        this.removeEventListener('focusout', this.handleFocusOut);
+        this.removeEventListener('pointerenter', this.handlePointerEnter);
+        this.removeEventListener('pointerleave', this.handlePointerLeave);
         this.removeEventListener('helix-dismiss', this.handleDismiss);
+        this.pointerIn = false;
+        this.focusIn = false;
         document.removeEventListener('keydown', this.handleHotkey);
         this.watcher?.disconnect();
         this.watcher = undefined;
@@ -297,6 +344,7 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.queue();
+        this.inform();
         this.place();
     }
     updated(changed) {
@@ -305,6 +353,9 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
             this.restack();
             this.place();
         }
+        if (changed.has('swipeDirection')) {
+            this.inform();
+        }
     }
     render() {
         return html `<div part="region" popover="manual" tabindex="-1"><slot></slot><span part="live" role="status">${this.said}</span><span part="live" role="alert">${this.urgent}</span></div>`;
@@ -323,6 +374,9 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessToast.prototype, "placement", void 0);
+__decorate([
+    property({ attribute: 'swipe-direction' })
+], HelixHeadlessToast.prototype, "swipeDirection", void 0);
 __decorate([
     state()
 ], HelixHeadlessToast.prototype, "said", void 0);

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

@@ -44,6 +44,17 @@ declare const HelixHeadlessTour_base: (new (...args: any[]) => import("@fusion.d
  * least distance that brings it on screen, so the stop that points at it is
  * on screen too.
  *
+ * **A stop's `effect` runs as the tour reaches it**, before it is shown, and
+ * the stop waits for a promise it returns, with `:state(preparing)` on the
+ * tour meanwhile. A function it returns runs when the tour leaves the stop.
+ *
+ * **A press outside the current stop and its target does nothing by
+ * default**, so a reader can use the page the tour is describing. Set
+ * `outside-press="close"` to end the tour on one, through `helix-before-close`
+ * as Skip does, or `outside-press="block"` to refuse it, so the stop and its
+ * target are all a pointer can reach while the tour runs, as Zag's
+ * `preventInteraction` does.
+ *
  * **Keyboard.** Focus is on the current stop's panel, which is not in the
  * `Tab` order itself.
  *
@@ -89,6 +100,7 @@ declare const HelixHeadlessTour_base: (new (...args: any[]) => import("@fusion.d
  * @cssproperty --tour-spotlight-y - The lit box's top edge, from the window's top edge, in pixels. Written on the spotlight while it lights a target.
  *
  * @cssstate open - While the tour is running.
+ * @cssstate preparing - While the tour waits for the current stop's `effect` before showing the stop.
  * @cssstate waiting - While the tour waits at a `wait` stop for its target to be on the page.
  */
 export declare class HelixHeadlessTour extends HelixHeadlessTour_base {
@@ -134,6 +146,12 @@ export declare class HelixHeadlessTour extends HelixHeadlessTour_base {
      * Label for the control that goes on.
      */
     nextLabel: string;
+    /**
+     * What a press outside the current stop and its target does while the tour
+     * runs. Unset, nothing: the page stays usable. `close` ends the tour, as
+     * Skip does, and `block` refuses the press.
+     */
+    outsidePress?: 'block' | 'close';
     /**
      * Draws each stop's place in the run in its panel, as well as saying it.
      */
@@ -201,6 +219,22 @@ export declare class HelixHeadlessTour extends HelixHeadlessTour_base {
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Answers a press outside the current stop and its target, as
+     * `outside-press` asks. A press on the tour's own parts, the stop or the
+     * target is the reader using the tour.
+     */
+    private readonly handleOutside;
+    /** The stop whose `effect` has run, and the function to run on leaving it. */
+    private entered;
+    /** The stop held back while its `effect` settles. */
+    private preparing;
+    /**
+     * Runs the current stop's `effect` as the tour reaches it, and the last
+     * one's leaving function as it leaves, and holds the stop back while a
+     * promise settles.
+     */
+    private enter;
     protected updated(changed: PropertyValues): void;
     /** The target last scrolled into view, so a render that moved nothing scrolls nothing. */
     private revealed;

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

@@ -59,6 +59,25 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
         this.handleViewport = () => {
             this.light();
         };
+        this.handleOutside = (event) => {
+            const mode = this.outsidePress;
+            if (!this.open || !mode) {
+                return;
+            }
+            const path = event.composedPath();
+            const stop = this.current;
+            const target = stop?.type === undefined ? stop?.target : undefined;
+            if (path.includes(this) || (target && path.includes(target))) {
+                return;
+            }
+            if (mode === 'block') {
+                event.preventDefault();
+                event.stopPropagation();
+            }
+            else if (event.type === 'pointerdown') {
+                this.skip();
+            }
+        };
         this.followed = false;
         this.veiled = false;
     }
@@ -122,6 +141,8 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
         this.addEventListener('helix-tour-ask', this.handleAsk);
         this.addEventListener('keydown', this.handleArrows);
         document.addEventListener('keydown', this.handleKeydown);
+        document.addEventListener('pointerdown', this.handleOutside, true);
+        document.addEventListener('click', this.handleOutside, true);
         window.addEventListener('resize', this.handleViewport, { passive: true });
         window.addEventListener('scroll', this.handleViewport, { capture: true, passive: true });
         if (this.hasUpdated) {
@@ -133,6 +154,9 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
         this.removeEventListener('helix-tour-ask', this.handleAsk);
         this.removeEventListener('keydown', this.handleArrows);
         document.removeEventListener('keydown', this.handleKeydown);
+        document.removeEventListener('pointerdown', this.handleOutside, true);
+        document.removeEventListener('click', this.handleOutside, true);
+        this.enter(undefined);
         window.removeEventListener('resize', this.handleViewport);
         window.removeEventListener('scroll', this.handleViewport, { capture: true });
         this.sizer?.disconnect();
@@ -149,8 +173,67 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
             role: this.open ? 'region' : '',
         });
     }
+    enter(stop) {
+        if (stop === this.entered?.stop) {
+            return;
+        }
+        const left = this.entered;
+        this.entered = stop ? { stop } : undefined;
+        left?.leave?.();
+        this.preparing = undefined;
+        this.toggleState('preparing', false);
+        const effect = stop?.effect;
+        if (!stop || !effect) {
+            return;
+        }
+        const ran = effect({
+            index: this.index,
+            next: () => this.next(),
+            skip: () => this.skip(),
+            target: stop.target,
+        });
+        const keep = (leave) => {
+            if (typeof leave !== 'function') {
+                return;
+            }
+            if (this.entered?.stop === stop) {
+                this.entered.leave = leave;
+            }
+            else {
+                ;
+                leave();
+            }
+        };
+        if (typeof ran?.then !== 'function') {
+            keep(ran);
+            return;
+        }
+        this.preparing = stop;
+        this.toggleState('preparing', true);
+        void ran
+            .then(keep, () => undefined)
+            .then(() => {
+            if (this.preparing !== stop) {
+                return;
+            }
+            this.preparing = undefined;
+            this.toggleState('preparing', false);
+            this.requestUpdate();
+            void this.updateComplete.then(() => {
+                const active = deepActiveElement();
+                const waiting = active === null ||
+                    active === document.body ||
+                    active === this.returnFocus ||
+                    deepContains(this, active);
+                if (waiting) {
+                    this.focusCurrent();
+                }
+            });
+        });
+    }
     updated(changed) {
         super.updated(changed);
+        this.enter(this.open ? this.current : undefined);
         this.reveal();
         this.settle();
         this.light();
@@ -228,7 +311,7 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
         const at = Math.max(0, Math.min(this.index, stops.length - 1));
         stops.forEach((stop, index) => {
             whenHydrated(stop, () => {
-                stop.current = this.open && index === at;
+                stop.current = this.open && index === at && this.preparing !== stop;
                 stop.first = index === 0;
                 stop.last = index === stops.length - 1;
                 stop.position = formatWords(this, 'progressLabel', {
@@ -253,7 +336,9 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
     }
     get lit() {
         const stop = this.current;
-        return this.open && stop?.type === undefined ? stop?.target : undefined;
+        return this.open && stop?.type === undefined && this.preparing !== stop
+            ? stop?.target
+            : undefined;
     }
     get current() {
         const stops = this.stops;
@@ -285,7 +370,8 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
         });
     }
     light() {
-        const stop = this.open ? this.current : undefined;
+        const shown = this.current;
+        const stop = this.open && this.preparing !== shown ? shown : undefined;
         const veiled = stop !== undefined && stop.type !== 'wait' && (stop.type !== undefined || !stop.target);
         if (veiled !== this.veiled) {
             this.veiled = veiled;
@@ -355,6 +441,9 @@ __decorate([
 __decorate([
     property({ attribute: 'next-label' })
 ], HelixHeadlessTour.prototype, "nextLabel", void 0);
+__decorate([
+    property({ attribute: 'outside-press' })
+], HelixHeadlessTour.prototype, "outsidePress", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessTour.prototype, "progress", void 0);