@glowhop/core-tour 1.3.1 → 1.5.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;
@@ -26,6 +27,17 @@ export interface TourViewDriver<T> {
      * than throw.
      */
     retarget(step: ActiveStep<T>, signal: AbortSignal): Promise<void> | void;
+    /**
+     * Reports that the navigation under way is waiting for the next step's
+     * target to resolve. The presented step has not left yet, so its popover is
+     * the one that carries the wait.
+     */
+    setTargetPending?(pending: boolean): void;
+    /**
+     * Hides or shows the popover of the running tour. A step still entering reads it as it is
+     * presented. Every `start()` shows it again first.
+     */
+    setPopoverHidden?(hidden: boolean): void;
     dispose(): void;
     releaseMount?(): void;
     setCommands?(commands: TourViewCommands): void;
@@ -65,6 +77,14 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
      * instead of freezing the presentation.
      */
     private awaitingStepUi;
+    /**
+     * True while the popover and pointer stand aside for a user scroll, until the
+     * page has been still for `USER_SCROLL_IDLE_DELAY` and, when the target was
+     * left off screen, the step has scrolled it back. The spotlight keeps
+     * tracking the target throughout.
+     */
+    private userScrolling;
+    private scrollTimer?;
     private activeTarget;
     private targetFocusedAtFreeze;
     private lastTargetRect;
@@ -73,11 +93,30 @@ 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;
+    /** True while the controller waits for the next step's target, see `setTargetPending`. */
+    private targetPending;
+    /** True while the consumer hides the popover, see `setPopoverHidden`. */
+    private popoverHidden;
+    /**
+     * 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;
@@ -88,6 +127,21 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     registerOverlay(element: SVGSVGElement | null): void;
     registerPopover(element: HTMLElement | null): void;
     registerPointer(element: HTMLElement | null): void;
+    /**
+     * Flags the presented popover as waiting for the next step's target, and
+     * disables its advance control for as long as the wait lasts: the step the
+     * user asked to leave stays on screen, and an advance that is already
+     * refused by the controller must not keep looking available. Cleared by the
+     * controller when the target settles, and by any teardown.
+     */
+    setTargetPending(pending: boolean): void;
+    /**
+     * Hides the popover and hands the page back while it is hidden: nothing is left to trap focus
+     * in, so the page leaves `inert`, focus moves from the popover to the target, and the shortcuts
+     * stop. The overlay, the pointer and the scroll lock stay. Showing it again replays the entrance
+     * and makes the step modal again. A step still entering applies it once presented.
+     */
+    setPopoverHidden(hidden: boolean): void;
     show(step: ActiveStep<T>, direction: TourDirection, signal: AbortSignal, onBeforePopoverAppear?: () => void | Promise<void>): Promise<void>;
     clear(signal: AbortSignal): Promise<void>;
     releaseMount(): void;
@@ -96,7 +150,10 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private activateRegisteredElements;
     private initializeElements;
     private syncModality;
+    private claimModal;
     private releaseModality;
+    /** Gives the page back without releasing the document's modal claim. */
+    private liftModality;
     private restoreInertBranches;
     /**
      * Brings the spotlight onto the target, then hands the step's popover and
@@ -125,6 +182,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
@@ -144,12 +203,68 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
     private updatePosition;
     /** Per-frame follow-up for the popover and pointer, once they are on screen. */
     private trackStepUi;
+    /**
+     * A scroll of the page, or of a scroller around the target, while the step is
+     * on screen. The popover and pointer stand aside at the first one, since
+     * following a travelling rect would fade them out and in every few pixels,
+     * and come back once the page has been still for a moment.
+     */
+    private onUserScroll;
+    private waitForScrollIdle;
+    /**
+     * The page has been still for a moment: brings the popover and pointer back,
+     * after `scroll.returnDelay` has scrolled the target back into view when the
+     * user left part of it outside.
+     */
+    private settleScroll;
+    /**
+     * Scrolls the target back in. As on entrance, `awaitingStepUi` leaves the
+     * spotlight to follow the page on its own and the scroll events this raises
+     * to be ignored; set together with `userScrolling`, it marks the scroll back,
+     * which a wheel or touch drag interrupts.
+     */
+    private scrollBack;
+    private revealAfterScroll;
+    private stopUserScroll;
+    /**
+     * Moves the popover along with its target and returns its placement. A hidden popover stays
+     * where it is: moving it would fade it back in. The pointer still keeps clear of its placement.
+     */
+    private placePopover;
     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;
+    /**
+     * Makes a presented step modal and moves focus into its popover, or keeps the popover hidden. A
+     * popover shown again after the entrance passed over it enters now.
+     */
+    private engagePopover;
+    /**
+     * Fades the popover out and stops guarding focus. Focus left in the popover goes to the target,
+     * or is dropped when the target cannot take it: `inert` would otherwise drop it on the body. The
+     * focus the tour gives back when it ends is kept for the step that shows the popover again.
+     */
+    private concealPopover;
+    /**
+     * Replays the popover's entrance on the rect the step was last placed on (a frozen step has no
+     * live target to measure), then makes the step modal again.
+     */
+    private revealPopover;
+    private isPopoverConcealed;
     private activateFocus;
     private syncScrollLock;
     private syncShortcutLabels;
@@ -167,6 +282,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 +312,15 @@ 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, or stepped aside for a user scroll. 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 +329,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>;
     /**
@@ -227,6 +356,8 @@ export declare class DomTourViewDriver<T> implements TourViewDriver<T> {
      * lets the backdrop appear while the page is still travelling.
      */
     private beginTargetScroll;
+    /** Scrolls the target in as the step asks, and returns the settle wait as `beginTargetScroll` does. */
+    private scrollTargetIntoView;
     /**
      * Resolves once the scroller has held still for a couple of frames.
      *

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

@@ -14,18 +14,29 @@ export default class PopoverElement extends GlowTourElement {
     private readonly mutationLease;
     protected _getNextStyles(position: DOMRect, step: TourElementStep): Keyframe;
     resolvePosition(targetPosition: DOMRect, step: TourElementStep): PopoverPosition;
+    /**
+     * Marks the popover as waiting for the next step's target. Written through the mutation lease,
+     * like every other attribute the popover owns, so unbinding the element gives it back clean.
+     */
+    setAwaitingTarget(awaiting: boolean): void;
     private _centerPosition;
     private _applyPositionState;
     /**
      * 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 +45,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";