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