@fusion.dev/helix-headless 0.158.0 → 0.159.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);

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

@@ -1,6 +1,23 @@
-import { HelixElement, type Placement } from '@fusion.dev/helix-core';
+import { HelixElement, OpenPhaseController, type Placement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../button/index.js';
+/** What a stop's `effect` is given: the stop's place, its target, and the tour's moves. */
+export interface TourStopContext {
+    /** The stop's index in the tour. */
+    index: number;
+    /** Goes on to the next stop, as Next does. */
+    next(): void;
+    /** Ends the tour early, as Skip does. */
+    skip(): void;
+    /** The element `for` names, now, or `null` where it is not on the page yet. */
+    target: HTMLElement | null;
+}
+/**
+ * A stop's `effect`: run as the tour reaches the stop, before it is shown. A
+ * promise holds the stop back until it settles, and a function returned, or
+ * resolved, runs when the tour leaves the stop.
+ */
+export type TourStopEffect = (context: TourStopContext) => void | (() => void) | Promise<void | (() => void)>;
 /**
  * @summary One stop on a tour: the element it points at, and a panel of content about it.
  *
@@ -30,6 +47,13 @@ import '../../button/index.js';
  * get Back, Next, and Skip, already wired. Slot your own `actions` and drive
  * them with `next()`, `back()`, and `skip()` on the root.
  *
+ * **Set `effect` to prepare the page for a stop**, such as opening the menu
+ * it points into or loading what it describes. It is a function, set from
+ * script, that the tour runs as it reaches the stop. Return a promise and the
+ * stop waits for it, and the tour has `:state(preparing)` meanwhile; return a
+ * function, or resolve to one, and the tour runs it when it leaves the stop.
+ * Zag's tour step has the same `effect`.
+ *
  * **`for` is an id, as with `Tooltip`**, so you can point at a target elsewhere
  * 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.
@@ -81,6 +105,8 @@ import '../../button/index.js';
  * @csspart skip-spinner - The ring `skip` turns while it is pending.
  * @csspart skip-text - The words on that button, trimmed to their capitals and baseline.
  *
+ * @cssstate entering - From the moment the stop is shown until its entrance has finished.
+ * @cssstate exiting - From the moment the stop is left until its exit has finished.
  * @cssstate placed-bottom - The panel sits below its target.
  * @cssstate placed-left - The panel sits to the left of its target.
  * @cssstate placed-right - The panel sits to the right of its target.
@@ -110,6 +136,11 @@ export declare class HelixHeadlessTourStop extends HelixElement {
      * Label for the control that goes on from the last stop.
      */
     doneLabel: string;
+    /**
+     * Run as the tour reaches the stop, before it is shown: see the description
+     * above. A function, so it is set from script and has no attribute.
+     */
+    effect?: TourStopEffect;
     /**
      * Whether the stop is the first one, with no stop before it.
      */
@@ -165,6 +196,7 @@ export declare class HelixHeadlessTourStop extends HelixElement {
      * makes.
      */
     private side?;
+    protected readonly phases: OpenPhaseController;
     /** The element the stop points at, or `null` when no element has the `for` id. */
     get target(): HTMLElement | null;
     private readonly floating;

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

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { arrowReach, customElement, elementById, HelixElement, HelixTourAskEvent, PopoverController, reflectElements, sideOf, words, } from '@fusion.dev/helix-core';
+import { arrowReach, customElement, elementById, HelixElement, HelixTourAskEvent, OpenPhaseController, PopoverController, reflectElements, sideOf, words, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
@@ -25,6 +25,14 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
         this.position = '';
         this.progress = false;
         this.skipLabel = 'Skip';
+        this.phases = new OpenPhaseController(this, {
+            mark: {
+                entering: (on) => this.toggleState('entering', on),
+                exiting: (on) => this.toggleState('exiting', on),
+            },
+            open: () => this.current && this.type !== 'wait',
+            surface: () => this.partNamed('bubble'),
+        });
         this.floating = new PopoverController(this, {
             anchor: () => this.target,
             arrow: () => this.partNamed('arrow'),
@@ -154,6 +162,9 @@ __decorate([
     words,
     property({ attribute: 'done-label' })
 ], HelixHeadlessTourStop.prototype, "doneLabel", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessTourStop.prototype, "effect", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessTourStop.prototype, "first", void 0);