@glowhop/core-tour 1.0.0

package/options/validation.d.ts

@@ -0,0 +1,3 @@
+import type { ReadonlyStepProps, WorkflowDefinition } from "../definition";
+export declare function validateStepProps<T>(path: string, props: ReadonlyStepProps<T>): void;
+export declare function validateWorkflowOptions<T>(workflow: WorkflowDefinition<T>): void;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@glowhop/core-tour",
+  "version": "1.0.0",
+  "description": "Framework-agnostic tour controller and DOM runtime for GlowTour.js.",
+  "license": "MIT",
+  "homepage": "https://github.com/Glowhop/GlowTour.js#readme",
+  "bugs": {
+    "url": "https://github.com/Glowhop/GlowTour.js/issues"
+  },
+  "keywords": [
+    "tour",
+    "guided-tour",
+    "onboarding",
+    "dom"
+  ],
+  "engines": {
+    "node": ">=18.19.1"
+  },
+  "files": [
+    "**/*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Glowhop/GlowTour.js.git",
+    "directory": "packages/core"
+  },
+  "type": "module",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./adapter": {
+      "types": "./adapter.d.ts",
+      "import": "./adapter.js"
+    },
+    "./config": {
+      "types": "./config/index.d.ts",
+      "import": "./config/index.js"
+    }
+  },
+  "sideEffects": false
+}

package/runtime/abort.d.ts

@@ -0,0 +1,2 @@
+export declare function abortError(): DOMException;
+export declare function abortableDelay(delay: number, signal: AbortSignal): Promise<void>;

package/runtime/active-step.d.ts

@@ -0,0 +1,72 @@
+import { type ReadonlyStartOptions, type ReadonlyStepProps, type WorkflowStepDefinition } from "../definition";
+import type { StepPropsStore } 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;
+    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>;
+    snapshot(): Readonly<{
+        id: string;
+        initialProps: ReadonlyStepProps<T>;
+        currentProps: ReadonlyStepProps<T>;
+        target: HTMLElement | null;
+    }>;
+}

package/runtime/adapter-contract.d.ts

@@ -0,0 +1,23 @@
+export declare const ADAPTER_BRIDGE_SYMBOL: unique symbol;
+export declare const ADAPTER_BRIDGE_VERSION: 1;
+export interface AdapterRootIds {
+    readonly description: string;
+    readonly popover: string;
+    readonly root: string;
+    readonly title: string;
+}
+export interface AdapterRootBinding {
+    readonly ids: AdapterRootIds;
+    bindOverlay(element: SVGSVGElement): () => void;
+    bindPointer(element: HTMLElement): () => void;
+    bindPopover(element: HTMLElement): () => void;
+    release(): void;
+}
+export interface AdapterRootConnectOptions {
+    readonly idPrefix?: string;
+    readonly root: HTMLElement;
+}
+export interface AdapterBridge {
+    readonly version: typeof ADAPTER_BRIDGE_VERSION;
+    connectRoot(options: AdapterRootConnectOptions): AdapterRootBinding;
+}

package/runtime/root-bridge.d.ts

@@ -0,0 +1,6 @@
+import type { WorkflowDefinition } from "../definition";
+import type { DomTourViewDriver } from "../dom/tour-view-driver";
+export declare function attachRootBridge<T>(tour: object, driver: DomTourViewDriver<T>, isDisposed: () => boolean, onMountReleaseStart: () => void, onMountReleaseComplete: () => void): {
+    assertCanRun(workflow: WorkflowDefinition<T>): Document;
+    release(): void;
+};

package/runtime/step-props-store.d.ts

@@ -0,0 +1,3 @@
+import { type ReadonlyStepProps } from "../definition";
+import type { StepPropsStore } from "../types";
+export declare function createStepPropsStore<T>(initialProps: ReadonlyStepProps<T>, reportListenerError: (error: unknown) => void, path?: string): StepPropsStore<T>;

package/runtime/tour-controller.d.ts

@@ -0,0 +1,107 @@
+import { WorkflowBuilder } from "../builder";
+import type { WorkflowDefinition } from "../definition";
+import { type TourViewDriver } from "../dom/tour-view-driver";
+import type { GlowTour, GlowTourOptions, RunOptions, StartOptions, TourEventSource, TourState } from "../types";
+interface TourControllerOptions<T> extends GlowTourOptions {
+    assertCanRun?: (workflow: WorkflowDefinition<T>) => Document | void;
+    onDispose?: () => void;
+    reportUnhandledError?: (error: Error) => void;
+}
+export declare class TourController<T> {
+    private readonly driver;
+    private readonly options;
+    private snapshot;
+    private workflow;
+    private steps;
+    private index;
+    private direction;
+    private status;
+    private error;
+    private operationToken;
+    private publicationRevision;
+    private operation;
+    private disposed;
+    private retainedPresentation;
+    private readonly stateListeners;
+    private readonly stepPropsSubscriptions;
+    private tourStartedAt;
+    private stepEnteredAt;
+    private commandSource;
+    readonly state: Readonly<{
+        get: () => TourState<T>;
+        subscribe: (listener: (state: TourState<T>) => void) => () => void;
+    }>;
+    constructor(driver: TourViewDriver<T>, options?: TourControllerOptions<T>);
+    create(name: string, options?: StartOptions<T>): WorkflowBuilder<T>;
+    run(workflow: WorkflowDefinition<T>, runOptions?: RunOptions): Promise<void>;
+    advance(source?: TourEventSource): Promise<void>;
+    previous(source?: TourEventSource): Promise<void>;
+    goToStep(index: number): Promise<void>;
+    cancel(source?: TourEventSource): Promise<void>;
+    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;
+    private transitionFromPublic;
+    private transition;
+    private runActions;
+    private resolveTarget;
+    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).
+     */
+    private resetToIdle;
+    private handleFailure;
+    private beginOperation;
+    private createStepContext;
+    private createBeforeActionStepContext;
+    private invalidateOperation;
+    private signalFor;
+    private assertCurrent;
+    private isCurrent;
+    private assertNotDisposed;
+    private currentStep;
+    private releaseStepPropsSubscriptions;
+    private canNavigate;
+    private isAdvanceButtonAvailable;
+    private isPreviousButtonAvailable;
+    private isCancelAvailable;
+    private isPresentedAdvanceAvailable;
+    private isPresentedPreviousAvailable;
+    private isPresentedCancelAvailable;
+    private canCancel;
+    private setStatus;
+    private publish;
+    private notifyStateListener;
+    /**
+     * True when at least one listener is attached. Every emission site checks this
+     * first so that a tour with no monitoring builds no payloads and reads no clock.
+     */
+    private hasEventListeners;
+    private emit;
+    private notifyEventListener;
+    /** Emits `step:leave` for the step being left, with the time spent on it. */
+    private emitStepLeave;
+    private reportSubscriberError;
+    private reportUnhandledError;
+    private createSnapshot;
+    private capturePresentation;
+}
+/**
+ * Creates a new GlowTour.js instance.
+ * @param options Tour options for error handling.
+ * @returns A tour controller ready to run workflows.
+ */
+export declare function createGlowTour<T>(options?: GlowTourOptions): GlowTour<T>;
+export {};

package/state/focus-guard.d.ts

@@ -0,0 +1,32 @@
+type FocusDirection = "advance" | "previous";
+export interface FocusGuardScope {
+    popover: HTMLElement;
+    direction: FocusDirection;
+    allowedTarget?: HTMLElement | null;
+    allowTargetInteraction?: boolean;
+    autoFocus?: boolean;
+    fallback?: HTMLElement | null;
+}
+export declare class FocusGuard {
+    private initialFocus;
+    private document;
+    private popover;
+    private allowedTarget;
+    private allowTargetInteraction;
+    private fallback;
+    private fallbackLease;
+    private direction;
+    private active;
+    private redirecting;
+    private readonly handleFocusIn;
+    activate(scope: FocusGuardScope): void;
+    update(scope: FocusGuardScope): void;
+    focus(): void;
+    deactivate(): void;
+    private isAllowed;
+    private focusFallback;
+    private setFallback;
+    private restoreFallback;
+    private findFocusable;
+}
+export {};

package/state/focusable.d.ts

@@ -0,0 +1,6 @@
+export declare const FOCUSABLE_SELECTOR: string;
+export declare const TOUR_TRIGGER_SELECTOR: string;
+export declare function focusableElements(root: HTMLElement): HTMLElement[];
+export declare function focusableElementsOwnedBy(root: HTMLElement): HTMLElement[];
+export declare function focusableTourControls(root: HTMLElement): HTMLElement[];
+export declare function isFocusable(element: HTMLElement): boolean;

package/state/scroll-lock.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Locks page scroll on `document.body` while a tour is active, compensating
+ * for the scrollbar's width so hiding it does not shift the layout.
+ *
+ * Mirrors the setup/teardown shape of {@link "./focus-guard".FocusGuard}:
+ * `activate` captures and overrides the body's inline scroll-affecting
+ * styles, `deactivate` restores exactly what was there before.
+ */
+export declare class ScrollLock {
+    private document;
+    private previousOverflow;
+    private previousPaddingRight;
+    private active;
+    activate(document: Document | null | undefined): void;
+    deactivate(): void;
+    private scrollbarWidth;
+    private computedPaddingRight;
+}