@glowhop/core-tour 1.3.0 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glowhop/core-tour",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Framework-agnostic tour controller and DOM runtime for GlowTour.js.",
   "license": "MIT",
   "homepage": "https://github.com/Glowhop/GlowTour.js#readme",

package/runtime/active-step.d.ts

@@ -1,68 +1,30 @@
 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;
+    /**
+     * 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;
     resolveTarget(signal: AbortSignal): Promise<HTMLElement | 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;
@@ -44,6 +44,11 @@ export declare class TourController<T> {
     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,10 +56,12 @@ 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>;
     dispose(): void;
     isDisposed(): boolean;
@@ -62,15 +69,25 @@ export declare class TourController<T> {
     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;
     /**
      * 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 +108,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 +148,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;

package/types/index.d.ts

@@ -16,32 +16,70 @@ export interface TargetResolverContext {
 }
 /** Configures step-level interaction behavior and error handling. */
 export interface StepBehavior {
-    /** Allow user interaction with the page outside the target element. @default false */
+    /** Allow user interaction with the target: the page is no longer inert and pointer events reach the target through the cutout, while the dimmed area still catches clicks. Change it during the step with `context.props.update({ behavior: { allowInteraction } })`. @default false */
     allowInteraction?: boolean;
-    /** Disable automatic focus on the target when the step is entered. @default false */
-    disableAutoFocus?: boolean;
-    /** Disable automatic scroll to the target when the step is entered. @default false */
-    disableAutoScroll?: boolean;
-    /** How to handle when the target is not found: `"wait"` waits and retries, `"skip"` advances to next step, `"error"` halts the tour. @default "error" */
-    missingTargetStrategy?: "wait" | "skip" | "error";
+    /** Leave the page scrollable while the step is shown; set `false` to lock it. Change it during the step with `context.props.update({ behavior: { allowScroll } })`. @default true */
+    allowScroll?: boolean;
+    /**
+     * Focus the popover's Advance control (Back when going back) when the step is shown. Set `false`
+     * to never move focus during the step: it stays where it is, on the body when a modal step
+     * makes the page inert, and placing it is up to you. Focus that leaves the popover and target
+     * is still pulled back, and focus returns to where it was when the tour ends. @default true
+     */
+    autoFocus?: boolean;
+    /** Scroll the target into view when the step is entered. @default true */
+    autoScroll?: boolean;
+    /** What the step does when its target cannot be found. */
+    missingTarget?: MissingTargetOptions;
     /** Scroll behavior options. */
     scroll?: ScrollOptions;
-    /** Timeout in ms to wait for target to appear before applying missingTargetStrategy. @default 3000 */
-    targetTimeout?: number;
     /**
      * Behavior when the dimmed overlay backdrop (outside the cutout around the
      * target) is clicked: `"advance"` moves to the next step, `"cancel"` ends
      * the tour, `"none"` ignores the click. Has no effect when
-     * `allowInteraction` is `true`, since the page stays fully interactive and
-     * there is no modal backdrop to click.
+     * `allowInteraction` is `true`: clicks on the dimmed area are then ignored.
      * @default "none"
      */
     overlayClick?: "none" | "advance" | "cancel";
 }
+/** How a step handles a target that cannot be found. */
+export interface MissingTargetOptions {
+    /**
+     * `"wait"` retries until `timeout`, `"skip"` moves past the step, `"error"` fails the tour,
+     * `"detached"` shows the popover centered in the viewport over a backdrop that covers the whole
+     * screen. A detached step has no pointer and no cutout, does not scroll, keeps the page blocked
+     * even when `allowInteraction` is `true`, and binds no `targetEvents`; its `context.target` is the
+     * document's `<body>`.
+     * @default "error"
+     */
+    strategy?: "wait" | "skip" | "error" | "detached";
+    /** How long to look for the target with the `"wait"` strategy, in milliseconds. @default 3000 */
+    timeout?: number;
+}
 /** Placement directions for positioning the pointer or popover around the target. */
 export type TryOrderOptions = "top" | "bottom" | "left" | "right";
 /** A resolved placement direction, including `"center"` for centered positioning. */
 export type ResolvedPlacement = TryOrderOptions | "center";
+/** One CSS class, or several. A string may hold several space-separated classes. */
+export type ClassValue = string | readonly string[];
+/**
+ * Classes added to the tour components while a step is shown, one entry per component.
+ *
+ * They are added to the classes passed to the component itself, never replacing them. A step's entry
+ * overrides the workflow's entry for the same component; the components the step leaves out keep the
+ * workflow's classes.
+ */
+export interface TourClassNames {
+    overlay?: ClassValue;
+    popover?: ClassValue;
+    pointer?: ClassValue;
+    header?: ClassValue;
+    content?: ClassValue;
+    footer?: ClassValue;
+    advance?: ClassValue;
+    previous?: ClassValue;
+    cancel?: ClassValue;
+}
 /** Base configuration for animated elements. */
 export interface BaseOptions {
     /** Enable or disable animations. */
@@ -51,8 +89,8 @@ export interface BaseOptions {
 }
 /** Configures the pointer indicator that highlights the target element. */
 export interface IndicatorOptions extends BaseOptions {
-    /** Hide the indicator. @default false */
-    disabled?: boolean;
+    /** Hide the indicator. It only shows on steps that allow interaction. @default false */
+    hidden?: boolean;
     /** Gap between the target and the indicator in pixels. */
     gap?: number;
     /** Placement preference order when positioning the indicator. @default ["left", "right", "top", "bottom"] */
@@ -72,7 +110,7 @@ export interface OverlayOptions extends BaseOptions {
 /** Configures the arrow that points from the popover to the target. */
 export interface PopoverArrowOptions {
     /** Hide the arrow. @default false */
-    disabled?: boolean;
+    hidden?: boolean;
     /** Color of the arrow (CSS color). */
     color?: string;
     /** Size of the arrow in pixels. @default 12 */
@@ -90,11 +128,41 @@ export interface PopoverArrowOptions {
      */
     styleNonce?: string;
     /**
-     * Skip injecting the built-in arrow `<style>` element entirely. Provide the
+     * Inject the built-in arrow `<style>` element. Set `false` to provide the
      * equivalent rules yourself through whatever channel your CSP allows, such
      * as an external stylesheet.
+     * @default true
      */
-    disableAutoStyles?: boolean;
+    autoStyles?: boolean;
+}
+/**
+ * Whether the user may run a tour control. `"enabled"` is the default. New states may be added in
+ * a minor version.
+ */
+export type TourControlState = "enabled" | "disabled";
+/** One navigation command: whether the user may run it and the keys that run it. */
+export interface TourControl {
+    /**
+     * `"disabled"` blocks the command everywhere the tour UI offers it: its button is disabled, and
+     * its keys and `overlayClick` do nothing. Navigation through the tour API and the step context
+     * stays available. To hide a button, give it a class through `classNames`.
+     * @default "enabled"
+     */
+    state?: TourControlState;
+    /** Keys that run the command while the step is shown. An empty array turns them off. */
+    keys?: readonly string[];
+}
+/**
+ * The advance, previous and cancel commands. A step's controls override the workflow ones field by
+ * field: a step that only sets `advance.state` keeps the workflow's `advance.keys`.
+ */
+export interface TourControls {
+    /** @default { state: "enabled", keys: ["Enter", "ArrowRight"] } */
+    advance?: TourControl;
+    /** @default { state: "enabled", keys: ["ArrowLeft", "Backspace"] } */
+    previous?: TourControl;
+    /** @default { state: "enabled", keys: ["Escape"] } */
+    cancel?: TourControl;
 }
 /** Configures the popover box that displays content for each step. */
 export interface PopoverOptions extends BaseOptions {
@@ -102,39 +170,8 @@ export interface PopoverOptions extends BaseOptions {
     placementTryOrder?: readonly TryOrderOptions[];
     /** Arrow configuration. */
     arrow?: PopoverArrowOptions;
-    /** Hide the footer section. @default false */
-    hideFooter?: boolean;
-    /**
-     * Disables only previous-button and previous-keyboard controls. Programmatic
-     * navigation through the tour API and step context remains available.
-     */
-    disablePreviousButton?: boolean;
-    /** Hide the previous button. @default false */
-    hidePreviousButton?: boolean;
-    /**
-     * Disables only advance-button and advance-keyboard controls. Programmatic
-     * navigation through the tour API and step context remains available.
-     */
-    disableAdvanceButton?: boolean;
-    /** Hide the advance button. @default false */
-    hideAdvanceButton?: boolean;
     /** Gap between the target and the popover in pixels. @default 16 */
     gap?: number;
-    /** Keyboard shortcuts for navigation. */
-    keyboardShortcuts?: {
-        /**
-         * Keys that trigger previous step. @default ["ArrowLeft", "Backspace"]
-         */
-        previous?: readonly string[];
-        /**
-         * Keys that trigger advance step. @default ["Enter", "ArrowRight"]
-         */
-        advance?: readonly string[];
-        /**
-         * Keys that trigger cancel. @default ["Escape"]
-         */
-        cancel?: readonly string[];
-    };
 }
 /**
  * Scroll behavior options passed to Element.scrollIntoView().
@@ -165,8 +202,8 @@ export interface AnimationOptions {
 export interface LifecycleHookContext<T> {
     /**
      * The step associated with this lifecycle transition:
-     * - `onStart`: the first step about to be entered (`workflow.steps[0]`), or
-     *   `null` if the workflow has no steps.
+     * - `onStart`: the step `start()` starts on (the `startAt` step, or the first
+     *   step), or `null` if the workflow has no steps.
      * - `onCancel`: the step the tour is currently on when cancellation is
      *   requested. Always non-null in practice, since a step is always active
      *   at the point a tour can be cancelled.
@@ -190,15 +227,6 @@ export interface LifecycleHookContext<T> {
 }
 /** Options for starting a tour workflow. */
 export interface StartOptions<T> {
-    /** Allow users to cancel the tour. @default true */
-    cancellable?: boolean;
-    /**
-     * Leaves page scroll available while the tour is active. Set `false` to lock
-     * scroll instead, restoring it on finish, cancel, error, or dispose.
-     *
-     * @default true
-     */
-    allowScroll?: boolean;
     /** Default overlay options for all steps. */
     overlay?: OverlayOptions;
     /** Default popover options for all steps. */
@@ -209,6 +237,10 @@ export interface StartOptions<T> {
     animated?: boolean;
     /** Default step behavior for all steps. */
     behavior?: StepBehavior;
+    /** Default controls for all steps. See `TourControls`. */
+    controls?: TourControls;
+    /** Classes added to the tour components on every step. See `TourClassNames`. */
+    classNames?: TourClassNames;
     /** Lifecycle hook called when the tour starts. */
     onStart?: (context: LifecycleHookContext<T>) => void | Promise<void>;
     /** Lifecycle hook called when the tour is cancelled. */
@@ -225,12 +257,22 @@ export interface StartOptions<T> {
 }
 /** Update to step properties, either as a full replacement or via a function. */
 export type StepPropsUpdate<T> = ReadonlyStepProps<T> | ((current: ReadonlyStepProps<T>) => ReadonlyStepProps<T>);
+/**
+ * Partial change to step properties, for `StepPropsStore.update`. Fields it leaves out are kept.
+ * `data` is merged key by key; `overlay`, `popover`, `indicator`, `behavior` and `controls` are
+ * merged the way step options merge over workflow defaults; arrays such as `placementTryOrder` or
+ * `keys` are replaced. `classNames` is merged per component: a component it names gets exactly the
+ * classes given.
+ */
+export type StepPropsPatch<T> = Partial<ReadonlyStepProps<T>>;
 /** Store for the current step's properties. */
 export interface StepPropsStore<T> {
     /** Get the current step properties. */
     get(): ReadonlyStepProps<T>;
-    /** Update the current step properties. */
+    /** Replace the current step properties. */
     set(update: StepPropsUpdate<T>): void;
+    /** Merge a partial change into the current step properties. See `StepPropsPatch`. */
+    update(patch: StepPropsPatch<T> | ((current: ReadonlyStepProps<T>) => StepPropsPatch<T>)): void;
     /** Subscribe to changes in step properties. Returns an unsubscribe function. */
     subscribe(listener: (props: ReadonlyStepProps<T>) => void): () => void;
 }
@@ -242,17 +284,39 @@ export interface StepContext<T> {
     cancel(): Promise<void>;
     /** Navigate to the previous step. */
     previous(): Promise<void>;
-    /** The DOM element being highlighted for this step. */
+    /**
+     * Navigate to the step with this id, skipping the steps in between. Stops the remaining actions
+     * of this step, like `advance()`. Throws when no step has this id.
+     */
+    goTo(id: string): Promise<void>;
+    /**
+     * The direction of the navigation that entered this step. Captured when the context is created, so
+     * it does not change while the step's callbacks run.
+     */
+    readonly direction: TourDirection;
+    /** The step properties as initially configured, before any `props.set()`. */
+    readonly initialProps: ReadonlyStepProps<T>;
+    /** The DOM element being highlighted for this step, or the document's `<body>` for a detached step. */
     readonly target: HTMLElement;
     /** Store for reading and updating the current step's properties. */
     readonly props: StepPropsStore<T>;
     /** Signal that aborts when the step is exited or the tour is cancelled. */
     readonly signal: AbortSignal;
 }
-/** Context passed to transition hooks (beforeAdvance, beforePrevious, beforeCancel). */
-export type BeforeActionStepContext<T> = Readonly<ReadonlyStepProps<T> & {
-    readonly target: HTMLElement;
-}>;
+/**
+ * Context passed to the `beforeEnter` and `beforeLeave` step hooks. It has no navigation methods:
+ * a transition is already in progress when these hooks run. `direction` is the direction of that
+ * navigation, so the step being left and the step being entered see the same value.
+ */
+export interface StepHookContext<T> extends Omit<StepContext<T>, "advance" | "cancel" | "goTo" | "previous"> {
+    /**
+     * Call it synchronously, or before the hook's returned promise resolves, to stop the navigation.
+     * The tour stays on the step it was on and emits nothing: `beforeLeave` keeps the step, and
+     * `beforeEnter` does not show the next one. When `beforeEnter` aborts the first step of `start()`,
+     * the tour goes back to `idle`, like an `onStart` abort.
+     */
+    abort(): void;
+}
 /** Context passed to target event handlers. */
 export type StepEventContext<T> = StepContext<T>;
 /** Options for the waitUntil step action. */
@@ -268,16 +332,16 @@ export type StepActionResult = boolean | void;
 export type StepAction<T> = (context: StepContext<T>) => Promise<StepActionResult> | StepActionResult;
 /** A step action or a delay in milliseconds. */
 export type StepActionInstruction<T> = StepAction<T> | number;
-/** A callback that runs before transitioning to the next/previous step or cancelling. */
-export type StepTransitionAction<T> = (context: BeforeActionStepContext<T>) => void | Promise<void>;
+/** A callback that runs before a step is entered or left (`beforeEnter` / `beforeLeave`). */
+export type StepHookAction<T> = (context: StepHookContext<T>) => void | Promise<void>;
 /** Handler for an event fired on the target element during a step. */
-export interface EventHandler<TStepProps, TEvent extends Event = Event> {
+export interface TargetEventHandler<TStepProps, TEvent extends Event = Event> {
     /** Event name(s) to listen for. */
     event: string;
     /** Callback invoked when the event fires. */
     callback: (event: TEvent, context: StepEventContext<TStepProps>) => void | Promise<void>;
 }
-/** Tour lifecycle status. */
+/** Tour lifecycle status. New statuses may be added in a minor release: keep a default branch when switching over it. */
 export type TourStatus = "idle" | "starting" | "transitioning" | "active" | "finished" | "cancelled" | "error" | "disposed";
 /** Direction of tour navigation. */
 export type TourDirection = "advance" | "previous";
@@ -331,13 +395,16 @@ export interface GlowTour<T> {
     /** Create a new workflow builder with the given name. */
     create(name: string, options?: StartOptions<T>): WorkflowBuilder<T>;
     /** Run a workflow, optionally starting at a specific step. */
-    run(workflow: WorkflowDefinition<T>, options?: RunOptions): Promise<void>;
+    start(workflow: WorkflowDefinition<T>, options?: RunOptions): Promise<void>;
     /** Advance to the next step. */
     advance(): Promise<void>;
     /** Go to the previous step. */
     previous(): Promise<void>;
-    /** Jump to a specific step by index. */
-    goToStep(index: number): Promise<void>;
+    /**
+     * Go to the step with this id, skipping the steps in between. Does nothing while a transition is
+     * in progress or when that step is already shown. Throws when no step has this id.
+     */
+    goTo(id: string): Promise<void>;
     /** Cancel the current tour. */
     cancel(): Promise<void>;
     /** Dispose the tour and free resources. */
@@ -346,7 +413,7 @@ export interface GlowTour<T> {
     readonly state: ReadonlyTourState<T>;
 }
 /**
- * Per-run options. Unlike `StartOptions`, these belong to one `run()` call and
+ * Per-run options. Unlike `StartOptions`, these belong to one `start()` call and
  * are never baked into the reusable workflow definition.
  */
 export interface RunOptions {
@@ -365,13 +432,15 @@ export interface RunOptions {
 /**
  * What triggered a transition.
  *
- * `"api"` covers every call your own code makes — `advance()`, `previous()`,
- * `goToStep()`, `cancel()`, and the `context.advance()` available inside a step
- * action. The other three are the user acting on the tour UI directly.
+ * `"api"` covers every call your own code makes: `advance()`, `previous()`,
+ * `goTo()`, `cancel()`, and the same methods on the context of a step action.
+ * The other three are the user acting on the tour UI directly.
+ *
+ * New sources may be added in a minor release: keep a default branch when switching over it.
  */
 export type TourEventSource = "api" | "trigger" | "keyboard" | "overlay";
-/** Name of a monitoring event. */
-export type TourEventType = "tour:start" | "step:enter" | "step:leave" | "tour:complete" | "tour:cancel" | "tour:error";
+/** Name of a monitoring event. New events may be added in a minor release: keep a default branch when switching over it. */
+export type TourEventType = "tour:start" | "step:enter" | "step:leave" | "step:skip" | "tour:complete" | "tour:cancel" | "tour:error";
 /**
  * A monitoring event, as handed to `onEvent`.
  *
@@ -402,7 +471,7 @@ export interface TourEvent {
      * How long the thing this event names had been running, in milliseconds.
      *
      * For `step:leave`, the time spent on that step. For `tour:complete`,
-     * `tour:cancel` and `tour:error`, the time since `run()` was called. For
+     * `tour:cancel` and `tour:error`, the time since `start()` was called. For
      * `tour:start` and `step:enter` — the beginnings — always `0`.
      */
     readonly durationMs: number;
@@ -444,11 +513,6 @@ export type StepParameters<T> = {
     id: string;
     /** The target element or selector for this step. */
     target: TargetResolver;
-    /**
-     * Reset step properties to initial values when entering this step.
-     * @default true
-     */
-    resetPropsOnEnter?: boolean;
     /** Overlay options for this step (overrides workflow defaults). */
     overlay?: OverlayOptions;
     /** Popover options for this step (overrides workflow defaults). */
@@ -457,8 +521,12 @@ export type StepParameters<T> = {
     indicator?: IndicatorOptions;
     /** Step behavior (overrides workflow defaults). */
     behavior?: StepBehavior;
-    /** The title content for this step. */
-    title: T;
+    /** Navigation controls for this step (overrides workflow defaults field by field). See `TourControls`. */
+    controls?: TourControls;
+    /** Classes added to the tour components on this step (overrides workflow defaults per component). See `TourClassNames`. */
+    classNames?: TourClassNames;
+    /** The title content for this step. Without a title, the popover is named by its content. */
+    title?: T;
     /** The body content for this step. */
     content: T;
     /** Arbitrary data associated with this step. */

package/utils/options.d.ts

@@ -1,7 +1,19 @@
-import type { AnimationOptions, IndicatorOptions, OverlayOptions, PopoverOptions, ScrollOptions, StepBehavior } from "../types";
+import type { DeepReadonly, ReadonlyStepProps } from "../definition";
+import type { AnimationOptions, IndicatorOptions, OverlayOptions, PopoverOptions, ScrollOptions, StepBehavior, StepPropsPatch, TourControls } from "../types";
+/**
+ * Merges a partial change into step props: fields it leaves out are kept, `data` is merged key by
+ * key, `overlay` / `popover` / `indicator` / `behavior` / `controls` go through their option merges,
+ * `classNames` is merged per component, and arrays are replaced.
+ * Builds a step's initial props over the workflow defaults, and backs `StepPropsStore.update`.
+ */
+export declare function mergeStepProps<T>(base: StepPropsPatch<T>, patch: StepPropsPatch<T>): ReadonlyStepProps<T>;
 export declare function mergeOverlayOptions(defaults?: OverlayOptions, overrides?: OverlayOptions): OverlayOptions | undefined;
 export declare function mergeIndicatorOptions(defaults?: IndicatorOptions, overrides?: IndicatorOptions): IndicatorOptions | undefined;
 export declare function mergePopoverOptions(defaults?: PopoverOptions, overrides?: PopoverOptions): PopoverOptions | undefined;
 export declare function mergeScrollOptions(defaults?: ScrollOptions, overrides?: ScrollOptions): ScrollOptions | undefined;
 export declare function mergeAnimationOptions(defaults?: AnimationOptions, overrides?: AnimationOptions): AnimationOptions | undefined;
 export declare function mergeStepBehavior(defaults?: StepBehavior, overrides?: StepBehavior): StepBehavior | undefined;
+/** Whether a control is enabled, so its button, keys and `overlayClick` may run its command. */
+export declare function isControlAvailable(props: {
+    readonly controls?: DeepReadonly<TourControls>;
+} | undefined, command: "advance" | "previous" | "cancel"): boolean;