@glowhop/core-tour 1.3.1 → 1.5.0

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@glowhop/core-tour",
-  "version": "1.3.1",
-  "description": "Framework-agnostic tour controller and DOM runtime for GlowTour.js.",
+  "version": "1.5.0",
+  "description": "Framework-agnostic product tour engine for GlowTour.js: the tour controller and DOM runtime behind onboarding tours in any framework.",
   "license": "MIT",
-  "homepage": "https://github.com/Glowhop/GlowTour.js#readme",
+  "homepage": "https://glowtour.dev/",
   "bugs": {
     "url": "https://github.com/Glowhop/GlowTour.js/issues"
   },
@@ -20,7 +20,9 @@
     "dom",
     "headless",
     "framework-agnostic",
-    "ssr"
+    "ssr",
+    "onboarding-tour",
+    "intro-js-alternative"
   ],
   "engines": {
     "node": ">=18.19.1"

package/runtime/active-step.d.ts

@@ -1,68 +1,31 @@
 import { type ReadonlyStartOptions, type ReadonlyStepProps, type WorkflowStepDefinition } from "../definition";
-import type { StepPropsStore } from "../types";
+import type { StepPropsStore, TourDirection } from "../types";
 export declare class ActiveStep<T> {
     readonly definition: WorkflowStepDefinition<T>;
     readonly path: string;
     private readonly rootDocument?;
     readonly initialProps: ReadonlyStepProps<T>;
     readonly props: StepPropsStore<T>;
-    readonly behavior: import("../types").StepBehavior | undefined;
     readonly animated: boolean | undefined;
-    readonly allowScroll: boolean;
     target: HTMLElement | null;
+    /** Shown without its target (`missingTarget.strategy: "detached"`); `target` is then the body. */
+    detached: boolean;
+    /** The navigation that last brought the tour to this step. */
+    direction: TourDirection;
     constructor(definition: WorkflowStepDefinition<T>, defaults: ReadonlyStartOptions<T>, reportSubscriberError?: (error: unknown) => void, path?: string, rootDocument?: Document | undefined);
-    reset(): void;
-    get overlay(): {
-        readonly color?: string | undefined;
-        readonly opacity?: number | undefined;
-        readonly padding?: number | undefined;
-        readonly radius?: number | undefined;
-        readonly animated?: boolean | undefined;
-        readonly animation?: {
-            readonly duration: number;
-            readonly easing: string;
-        } | undefined;
-    } | undefined;
-    get popover(): {
-        readonly placementTryOrder?: readonly import("../types").TryOrderOptions[] | undefined;
-        readonly arrow?: {
-            readonly disabled?: boolean | undefined;
-            readonly color?: string | undefined;
-            readonly size?: number | undefined;
-            readonly borderWidth?: number | undefined;
-            readonly borderRadius?: number | undefined;
-            readonly edgePadding?: number | undefined;
-            readonly styleNonce?: string | undefined;
-            readonly disableAutoStyles?: boolean | undefined;
-        } | undefined;
-        readonly hideFooter?: boolean | undefined;
-        readonly disablePreviousButton?: boolean | undefined;
-        readonly hidePreviousButton?: boolean | undefined;
-        readonly disableAdvanceButton?: boolean | undefined;
-        readonly hideAdvanceButton?: boolean | undefined;
-        readonly gap?: number | undefined;
-        readonly keyboardShortcuts?: {
-            readonly previous?: readonly string[] | undefined;
-            readonly advance?: readonly string[] | undefined;
-            readonly cancel?: readonly string[] | undefined;
-        } | undefined;
-        readonly animated?: boolean | undefined;
-        readonly animation?: {
-            readonly duration: number;
-            readonly easing: string;
-        } | undefined;
-    } | undefined;
-    get indicator(): {
-        readonly disabled?: boolean | undefined;
-        readonly gap?: number | undefined;
-        readonly placementTryOrder?: readonly import("../types").TryOrderOptions[] | undefined;
-        readonly animated?: boolean | undefined;
-        readonly animation?: {
-            readonly duration: number;
-            readonly easing: string;
-        } | undefined;
-    } | undefined;
-    resolveTarget(signal: AbortSignal): Promise<HTMLElement | null>;
+    /**
+     * Reads `behavior.allowInteraction` live: `props.update({ behavior })` changes it while the step runs.
+     * A detached step has no target to interact with, so it always blocks the page.
+     */
+    allowsInteraction(): boolean;
+    /** Reads `behavior.autoFocus` live: `false` hands every focus move to the page. */
+    autoFocuses(): boolean;
+    /** Reads `behavior.allowScroll` live: `props.update({ behavior })` changes it while the step runs. */
+    allowsScroll(): boolean;
+    /** Returns the target, or the promise to wait on when the resolver is async. */
+    resolveTarget(signal: AbortSignal): HTMLElement | Promise<HTMLElement | null> | null;
+    /** Marks the step detached and returns the body it stands on, or `null` without a document. */
+    detach(): HTMLElement;
     snapshot(): Readonly<{
         id: string;
         initialProps: ReadonlyStepProps<T>;

package/runtime/tour-controller.d.ts

@@ -4,11 +4,11 @@ import { type TourViewDriver } from "../dom/tour-view-driver";
 import type { GlowTour, GlowTourOptions, RunOptions, StartOptions, TourEventSource, TourState } from "../types";
 /**
  * How long a step stays frozen on its last known position after its target
- * disappears from the DOM, before the configured `missingTargetStrategy`
+ * disappears from the DOM, before the configured `missingTarget.strategy`
  * takes over. Covers the dominant case — a framework remounting the target
  * within a frame or two — without a visible unmount/remount flicker. Not
  * configurable: it is a presentation detail of the recovery, not a policy
- * choice; `missingTargetStrategy` and `targetTimeout` remain the only knobs.
+ * choice; `missingTarget.strategy` and `missingTarget.timeout` remain the only knobs.
  * Exported for the test suite's timing assertions only.
  */
 export declare const TARGET_LOSS_GRACE_MS = 150;
@@ -37,13 +37,25 @@ export declare class TourController<T> {
     private recoveringTarget;
     private operationToken;
     private publicationRevision;
+    /**
+     * The operation currently parked on a target that has not resolved yet, or `null`. The step being
+     * left is still on screen while a navigation waits, so the wait is reported on its presentation.
+     */
+    private awaitingTargetOperation;
     private operation;
+    /** Set by `hidePopover()`, see `TourState.popoverHidden`. Only a running tour reports it. */
+    private popoverHidden;
     private disposed;
     private retainedPresentation;
     private readonly stateListeners;
     private readonly stepPropsSubscriptions;
     private tourStartedAt;
     private stepEnteredAt;
+    /**
+     * The step `tour:start` names, while that event is held back. It is emitted just before the
+     * first event that can no longer be taken back, so a start that a `beforeEnter` aborts emits nothing.
+     */
+    private pendingTourStart;
     private commandSource;
     readonly state: Readonly<{
         get: () => TourState<T>;
@@ -51,26 +63,49 @@ export declare class TourController<T> {
     }>;
     constructor(driver: TourViewDriver<T>, options?: TourControllerOptions<T>);
     create(name: string, options?: StartOptions<T>): WorkflowBuilder<T>;
-    run(workflow: WorkflowDefinition<T>, runOptions?: RunOptions): Promise<void>;
+    start(workflow: WorkflowDefinition<T>, runOptions?: RunOptions): Promise<void>;
     advance(source?: TourEventSource): Promise<void>;
     previous(source?: TourEventSource): Promise<void>;
-    goToStep(index: number): Promise<void>;
+    goTo(id: string): Promise<void>;
+    /** The direction of a jump from the current step to the step at `index`. */
+    private directionTo;
     cancel(source?: TourEventSource): Promise<void>;
+    /** `tour.hidePopover()` and `tour.showPopover()`. */
+    setPopoverHidden(hidden: boolean): void;
+    private isRunning;
     dispose(): void;
     isDisposed(): boolean;
     /** @internal Called by the private root bridge before it releases DOM resources. */
     beginMountRelease(): void;
     /** @internal Called after the private root bridge has finished releasing its lease. */
     completeMountRelease(): void;
-    private enter;
+    /**
+     * Moves to the step at `index`, or further in `direction` past steps skipped for a missing target.
+     * Nothing is emitted before `beforeEnter` lets the navigation through, so an abort leaves no trace.
+     * Then come the held `tour:start`, a `step:skip` per skipped step, and one `step:leave` for the
+     * step being left. `lostStep` is the step whose target disappeared during recovery: it cannot stay
+     * on screen, so skipping backward past the first step cancels the tour, and a `beforeEnter` abort
+     * turns into its missing-target error.
+     */
+    private navigate;
     private transitionFromPublic;
     private transition;
+    /** Runs `beforeEnter` or `beforeLeave`, and tells whether it called `abort()` before settling. */
+    private runStepHook;
     private runActions;
     private resolveTarget;
+    /**
+     * Reports a navigation waiting on the next step's target. The presentation on screen still
+     * belongs to the step being left, so the driver marks that popover and disables its advance
+     * control until the target settles. Keyed by operation: a superseded navigation never clears the
+     * wait its replacement declared. The freeze of a target lost mid-step is deliberately not a wait
+     * here, see `recoverDisconnectedTarget`.
+     */
+    private setAwaitingTarget;
     /**
      * Repeatedly re-resolves `step.target` until it succeeds or `budgetMs`
      * elapses, polling every 16ms like `resolveTarget`. Unlike `resolveTarget`
-     * it never applies `missingTargetStrategy` itself — callers decide what a
+     * it never applies `missingTarget.strategy` itself — callers decide what a
      * timed-out budget means (grace period vs. a "wait" strategy's own
      * timeout), so the same polling loop serves both.
      */
@@ -91,22 +126,21 @@ export declare class TourController<T> {
      * comes back, so it has to keep working.
      */
     private recoverDisconnectedTarget;
-    private advancePastMissingTarget;
-    private advancePastRecoveryMissingTarget;
     private missingTargetError;
     private finish;
     private cancelCurrent;
     private createLifecycleHookContext;
     /**
-     * Restores the controller to its pre-`run()` idle state. Used when an
-     * aborted lifecycle hook prevents the tour from ever becoming active
-     * (`onStart` abort, and the zero-step `onFinish` abort edge case).
+     * Restores the controller to its pre-`start()` idle state. Used when an
+     * aborted hook prevents the tour from ever becoming active (`onStart`, the
+     * first step's `beforeEnter`, and the zero-step `onFinish` edge case). A
+     * tour this `start()` replaced is still on screen, so it is cleared first.
      */
     private resetToIdle;
     private handleFailure;
     private beginOperation;
     private createStepContext;
-    private createBeforeActionStepContext;
+    private createStepHookContext;
     private invalidateOperation;
     private signalFor;
     private assertCurrent;
@@ -132,6 +166,8 @@ export declare class TourController<T> {
     private hasEventListeners;
     private emit;
     private notifyEventListener;
+    /** Emits the held `tour:start` once, before the first event that can no longer be taken back. */
+    private flushTourStart;
     /** Emits `step:leave` for the step being left, with the time spent on it. */
     private emitStepLeave;
     private reportSubscriberError;

package/state/focus-guard.d.ts

@@ -5,6 +5,8 @@ export interface FocusGuardScope {
     allowedTarget?: HTMLElement | null;
     allowTargetInteraction?: boolean;
     autoFocus?: boolean;
+    /** The caller focuses a control later: keep a focus already in scope until then. */
+    deferFocus?: boolean;
     fallback?: HTMLElement | null;
 }
 export declare class FocusGuard {
@@ -22,7 +24,20 @@ export declare class FocusGuard {
     activate(scope: FocusGuardScope): void;
     update(scope: FocusGuardScope): void;
     focus(): void;
+    /**
+     * Remembers the element focus returns to when the guard deactivates. The driver calls it before
+     * making the rest of the page inert, because inerting an ancestor blurs the focused element.
+     * Does nothing once a focus is remembered or the guard is active. `pending` is a focus a clear
+     * could not give back before this show replaced it, and wins over the current focus.
+     */
+    captureInitialFocus(reference: HTMLElement, pending?: HTMLElement | null): void;
     deactivate(): void;
+    /**
+     * Stops guarding and returns the element focus should go back to, without moving focus. Lets
+     * the caller restore it once the page has left `inert`: screen readers ignore focus moved onto
+     * content their accessibility tree has not caught up with yet.
+     */
+    release(): HTMLElement | null;
     private isAllowed;
     private focusFallback;
     private setFallback;