@glowhop/core-tour 1.3.1 → 1.4.0

package/definition/step-props.d.ts

@@ -1,10 +1,18 @@
-import type { ReadonlyStepProps, StepProps } from "./types";
+import type { TourClassNames, TourControls } from "../types";
+import type { DeepReadonly, ReadonlyStepProps, StepProps } from "./types";
 /**
  * Creates a shallow clone of step properties with deep clones of nested objects.
  * @param props The properties to clone.
  * @returns A mutable copy of the properties.
  */
 export declare function cloneStepProps<T>(props: ReadonlyStepProps<T>): StepProps<T>;
+/** Copies `controls` into frozen records, with frozen copies of their `keys`. */
+export declare function cloneControls(controls: DeepReadonly<TourControls> | undefined): TourControls | undefined;
+/**
+ * Copies `classNames` into a frozen record. Its class arrays are shared rather than copied: they are
+ * typed readonly and nothing in the tour writes to them, and copying them costs bundle size.
+ */
+export declare function cloneClassNames(classNames: TourClassNames | undefined): TourClassNames | undefined;
 /**
  * Creates a deep-frozen copy of step properties.
  * @param props The properties to freeze.

package/definition/types.d.ts

@@ -1,18 +1,21 @@
-import type { EventHandler, IndicatorOptions, OverlayOptions, PopoverOptions, PrimitiveValue, StartOptions, StepActionInstruction, StepBehavior, StepParameters, StepTransitionAction, TargetResolver } from "../types";
+import type { IndicatorOptions, OverlayOptions, PopoverOptions, PrimitiveValue, StartOptions, StepActionInstruction, StepBehavior, StepHookAction, StepParameters, TargetEventHandler, TargetResolver, TourClassNames, TourControls } from "../types";
 /** Recursively makes all properties readonly at any depth. */
 export type DeepReadonly<T> = T extends (...arguments_: infer _Arguments) => infer _Return ? T : T extends readonly (infer TEntry)[] ? readonly DeepReadonly<TEntry>[] : T extends object ? {
     readonly [TKey in keyof T]: DeepReadonly<T[TKey]>;
 } : T;
-/** Step properties (title, content, and optional display options) excluding target and behavior. */
-export type StepProps<T> = Omit<StepParameters<T>, "id" | "target" | "resetPropsOnEnter" | "behavior">;
+/** Step properties (title, content, behavior, and optional display options) excluding id and target. */
+export type StepProps<T> = Omit<StepParameters<T>, "id" | "target">;
 /** Immutable step properties. */
 export type ReadonlyStepProps<T> = {
-    readonly title: T;
+    readonly title?: T;
     readonly content: T;
     readonly data?: Readonly<Record<string, PrimitiveValue>>;
     readonly overlay?: DeepReadonly<OverlayOptions>;
     readonly popover?: DeepReadonly<PopoverOptions>;
     readonly indicator?: DeepReadonly<IndicatorOptions>;
+    readonly behavior?: DeepReadonly<StepBehavior>;
+    readonly controls?: DeepReadonly<TourControls>;
+    readonly classNames?: DeepReadonly<TourClassNames>;
 };
 /** Immutable tour start options. */
 export type ReadonlyStartOptions<T> = DeepReadonly<StartOptions<T>>;
@@ -21,14 +24,11 @@ export interface WorkflowStepDefinition<T> {
     /** Stable identifier, unique within the workflow. */
     readonly id: string;
     readonly target: TargetResolver;
-    readonly resetPropsOnEnter?: boolean;
-    readonly behavior?: DeepReadonly<StepBehavior>;
     readonly props: ReadonlyStepProps<T>;
     readonly actions: readonly StepActionInstruction<T>[];
-    readonly eventHandlers: readonly EventHandler<T>[];
-    readonly advanceAction: StepTransitionAction<T> | null;
-    readonly previousAction: StepTransitionAction<T> | null;
-    readonly cancelAction: StepTransitionAction<T> | null;
+    readonly targetEvents: readonly TargetEventHandler<T>[];
+    readonly beforeEnter: StepHookAction<T> | null;
+    readonly beforeLeave: StepHookAction<T> | null;
 }
 /** A complete tour workflow definition (immutable). */
 export interface WorkflowDefinition<T> {

package/definition/workflow-definition.d.ts

@@ -1,16 +1,13 @@
-import type { EventHandler, StartOptions, StepActionInstruction, StepParameters, StepTransitionAction } from "../types";
+import type { StartOptions, StepActionInstruction, StepHookAction, StepParameters, TargetEventHandler } from "../types";
 import type { StepProps, WorkflowDefinition, WorkflowStepDefinition } from "./types";
 export interface WorkflowStepDraft<T> {
     id: string;
     target: StepParameters<T>["target"];
-    resetPropsOnEnter?: boolean;
     props: StepProps<T>;
-    behavior?: StepParameters<T>["behavior"];
     actions: StepActionInstruction<T>[];
-    eventHandlers: EventHandler<T>[];
-    advanceAction: StepTransitionAction<T> | null;
-    previousAction: StepTransitionAction<T> | null;
-    cancelAction: StepTransitionAction<T> | null;
+    targetEvents: TargetEventHandler<T>[];
+    beforeEnter: StepHookAction<T> | null;
+    beforeLeave: StepHookAction<T> | null;
 }
 /**
  * Creates a mutable copy of a workflow step definition.

package/dom/tour-view-driver.d.ts

@@ -5,6 +5,7 @@ export interface TourViewCommands {
     canAdvance(): boolean;
     canCancel(): boolean;
     canPrevious(): boolean;
+    goTo(id: string): Promise<void>;
     isAdvanceDisabled(): boolean;
     isCancelDisabled(): boolean;
     isPreviousDisabled(): boolean;
@@ -73,11 +74,26 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private modalDocument;
     private modalRoot;
     private overlay;
-    private pendingKeyboardCommand;
+    /** A command asked for while a visible popover was replaced, run once the new step is presented. */
+    private pendingCommand;
     private pointer;
     private pendingFocusGeneration;
+    /**
+     * The last click a presented step's button handled. It bubbles on to the window after the
+     * command it ran started the next step, and must not be queued a second time there.
+     */
+    private handledTriggerClick;
     private popover;
     private presentationDirty;
+    /**
+     * The focus a clear gives back once the popover has faded out. Kept past a clear that a new show
+     * supersedes, so that tour returns focus there instead of to the fading popover.
+     */
+    private focusToRestore;
+    /** The `allowInteraction` value the overlay, the page modality and the focus guard reflect. */
+    private appliedAllowInteraction;
+    /** Set when a live `allowInteraction` change started the pointer fade; the next frame clears it. */
+    private pointerFading;
     private rafId;
     private rafCancel;
     private root;
@@ -96,6 +112,7 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private activateRegisteredElements;
     private initializeElements;
     private syncModality;
+    private claimModal;
     private releaseModality;
     private restoreInertBranches;
     /**
@@ -125,6 +142,8 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private presentStepUi;
     /** The popover and pointer entrance itself, started synchronously. */
     private enterStepUi;
+    /** Fades the pointer in on the target, or out when the step does not show it. */
+    private presentPointer;
     private attachStepResources;
     /**
      * Binds the step's custom event handlers to its target element. Split out
@@ -146,9 +165,20 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private trackStepUi;
     private observeDynamicOperation;
     private handleKeydown;
+    /**
+     * The keyboard shortcut a keydown asks for, if `available` allows it. `null` leaves the key to the
+     * browser, as Enter on a focused control is: on a tour button, the click it produces runs that
+     * button's own command after the consumer's click handlers, like a pointer click.
+     */
+    private keyboardCommand;
     private handleOverlayClick;
     private queueTransitionKeydown;
-    private flushPendingKeyboardCommand;
+    /**
+     * Queues the command of a tour button clicked while a visible popover is replaced. Listening on
+     * the window runs after the consumer's own click handlers, so a prevented click queues nothing.
+     */
+    private queueTransitionClick;
+    private flushPendingCommand;
     private loopFocus;
     private activateFocus;
     private syncScrollLock;
@@ -167,6 +197,11 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private syncControl;
     private isConsumerDisabled;
     private isLiveDisabled;
+    /**
+     * The props the overlay and popover render: the step's own, flagged when the step is detached so
+     * the overlay drops its cutout and the popover centers itself.
+     */
+    private elementProps;
     private isPointerEnabled;
     private cleanupStepResources;
     private cleanupTargetResources;
@@ -192,6 +227,14 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
      * and to restore the step's own setting once retargeted.
      */
     private applyInteractionLock;
+    /** Applies the step's own interaction setting to the overlay, the page modality and the focus guard. */
+    private applyInteraction;
+    /**
+     * Applies a `behavior.allowInteraction` changed through the step props while the step is on
+     * screen. A step still entering reads the new value when it presents, and a frozen one keeps
+     * interaction off until `retarget()` restores it. The indicator fades in or out instead of snapping.
+     */
+    private syncInteraction;
     private isFocusInsideTarget;
     /**
      * Resumes a presentation frozen by `freezeForDisconnectedTarget` on its new
@@ -200,7 +243,7 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
      * and popover to the new rect on the next frame. Deliberately skips
      * `appear()` (no re-entrance animation) and `activateFocus()` (focus stays
      * where the user left it), only reclaiming it if it was on the target that
-     * just disappeared.
+     * just disappeared and the step auto focuses.
      */
     retarget(step: ActiveStep<T>, signal: AbortSignal): Promise<void>;
     /**

package/elements/base.d.ts

@@ -1,5 +1,7 @@
 import type { IndicatorOptions, OverlayOptions, PopoverOptions } from "../types";
 export interface TourElementStep {
+    /** No target: the popover is centered and the backdrop has no cutout. */
+    readonly detached?: boolean;
     readonly indicator?: IndicatorOptions;
     readonly overlay?: OverlayOptions;
     readonly popover?: PopoverOptions;
@@ -12,6 +14,13 @@ export default abstract class GlowTourElement {
         disabled?: boolean;
     } | undefined;
     private readonly animations;
+    /**
+     * Animations that ran to completion and whose `fill: "forwards"` still applies.
+     *
+     * They keep overriding the element's inline styles, so a presentation that writes its state
+     * without animating would be painted with the previous animation's last frame instead.
+     */
+    private readonly filledAnimations;
     private readonly cancelledAnimations;
     private released;
     constructor(element: HTMLElement | SVGSVGElement, options?: {
@@ -49,12 +58,25 @@ export default abstract class GlowTourElement {
      */
     private _finishWhileDocumentHidden;
     protected _waitForAnimation(animation: Animation): Promise<boolean>;
-    protected abstract _disappear(): Promise<void>;
+    /**
+     * Drops what finished animations still impose on the element.
+     *
+     * Every animation is followed by the inline styles that record the state it landed on, so
+     * releasing the fill leaves the element exactly as it looks. Without this, a fade-out that
+     * finished keeps forcing `opacity: 0` over the inline `opacity: 1` of the next presentation,
+     * and an unanimated one never starts an animation of its own to take the fill over.
+     */
+    protected _releaseFilledAnimations(): void;
+    protected abstract _disappear(hideFromAssistiveTechnology?: boolean): Promise<void>;
     protected abstract _getNextStyles(position: DOMRect, step: TourElementStep): Keyframe;
     abstract updatePosition(nextPosition: DOMRect, step: TourElementStep): void;
     abstract initializeProps(): void;
     getElement(): HTMLElement | SVGSVGElement | null;
-    disappear(): Promise<void>;
+    /**
+     * Fades the element out. The popover stays exposed to assistive technology when passed `false`,
+     * for a step change: its live region then announces the new step and focus stays in it.
+     */
+    disappear(hideFromAssistiveTechnology?: boolean): Promise<void>;
     release(): void;
     cancelAnimations(): void;
     protected _cancelAnimation(animation: Animation): void;

package/elements/popover.d.ts

@@ -19,13 +19,19 @@ export default class PopoverElement extends GlowTourElement {
     /**
      * Fades the popover in at `nextPosition` and commits that placement.
      *
-     * The outgoing half of a step change is {@link disappear}, deliberately kept
-     * separate: between the two, the caller swaps the step's content while the
-     * popover is off screen, and — when the step scrolls — waits for the scroll
-     * to settle so this entrance reads a rect that will not move again.
+     * The outgoing half of a step change is `disappear(false)`, which keeps the
+     * popover exposed to assistive technology, deliberately kept separate: between the two, the caller swaps the step's
+     * content while the popover is faded out, and — when the step scrolls — waits
+     * for the scroll to settle so this entrance reads a rect that will not move
+     * again.
      */
     present(nextPosition: DOMRect, step: TourElementStep): Promise<void>;
-    initializeProps(): void;
+    /**
+     * Resets the popover to its idle presentation. A step change that replaces a
+     * visible popover passes `false`: the popover stays exposed so its live
+     * region announces the new step and focus stays in it.
+     */
+    initializeProps(hideFromAssistiveTechnology?: boolean): void;
     updatePosition(nextPosition: DOMRect, step: TourElementStep, onReposition?: (reposition: Promise<void>) => void): ResolvedPlacement;
     cancelAnimations(): void;
     private _flushReposition;
@@ -34,8 +40,14 @@ export default class PopoverElement extends GlowTourElement {
     private _applyArrowStyles;
     private _applyArrowStyle;
     _appear(position: DOMRect, step: TourElementStep): Promise<void>;
-    _disappear(): Promise<void>;
+    _disappear(hideFromAssistiveTechnology?: boolean): Promise<void>;
     protected _release(): void;
     private _applyVisibleState;
+    /**
+     * Out of sight but still exposed to assistive technology. Pointer input is blocked the way
+     * `inert` blocks it: the controller ignores commands mid-transition, so a click must not look
+     * accepted.
+     */
+    private _applyFadedState;
     private _applyHiddenState;
 }

package/index.d.ts

@@ -1,4 +1,4 @@
 export type { EventName, WorkflowBuilder, WorkflowStepBuilder } from "./builder";
 export type { ReadonlyStartOptions, ReadonlyStepProps, WorkflowDefinition, WorkflowStepDefinition, } from "./definition";
 export { createGlowTour } from "./runtime/tour-controller";
-export type { AnimationOptions, BaseOptions, BeforeActionStepContext, EventHandler, GlowTour, GlowTourOptions, IndicatorOptions, LifecycleHookContext, OverlayOptions, PopoverArrowOptions, PopoverOptions, PrimitiveValue, ReadonlyTourState, ResolvedPlacement, ScrollOptions, StartOptions, StepAction, StepActionInstruction, StepActionResult, StepBehavior, StepContext, StepEventContext, StepParameters, StepPropsStore, StepPropsUpdate, StepTransitionAction, TargetResolver, TargetResolverContext, TourCurrentStep, TourDirection, TourEvent, TourEventListener, TourEventSource, TourEventType, TourState, TourStatus, TryOrderOptions, WaitUntilOptions, } from "./types";
+export type { AnimationOptions, BaseOptions, ClassValue, GlowTour, GlowTourOptions, IndicatorOptions, LifecycleHookContext, MissingTargetOptions, OverlayOptions, PopoverArrowOptions, PopoverOptions, PrimitiveValue, ReadonlyTourState, ResolvedPlacement, ScrollOptions, StartOptions, StepAction, StepActionInstruction, StepActionResult, StepBehavior, StepContext, StepEventContext, StepHookAction, StepHookContext, StepParameters, StepPropsPatch, StepPropsStore, StepPropsUpdate, TargetEventHandler, TargetResolver, TargetResolverContext, TourClassNames, TourControl, TourControlState, TourControls, TourCurrentStep, TourDirection, TourEvent, TourEventListener, TourEventSource, TourEventType, TourState, TourStatus, TryOrderOptions, WaitUntilOptions, } from "./types";