@robertlinde/react-tour-kit 0.8.9 → 1.0.0

package/dist/shared/engine/tour-adapter.type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-adapter.type.js","sourceRoot":"","sources":["../../../src/shared/engine/tour-adapter.type.ts"],"names":[],"mappings":""}

package/dist/shared/engine/tour-engine.d.ts

@@ -0,0 +1,92 @@
+import { type TooltipLayout } from '../geometry/compute-tooltip-layout.util.js';
+import type { Box, Size } from '../geometry/geometry.type.js';
+import type { TourContextType } from '../types/tour-context.type.js';
+import type { TourEndCallback, TourEndReason } from '../types/tour-end-info.type.js';
+import type { TourStep } from '../types/tour-step.type.js';
+import type { TourAdapter } from './tour-adapter.type.js';
+/** Spacing used for layout, shared by both platforms. */
+export declare const tourLayout: {
+    /** Distance between the highlighted area and the tooltip (arrows are at most this long). */
+    readonly gap: 12;
+    /** Space between the target and the edge of the highlighted area. */
+    readonly highlightPadding: 8;
+    /** Minimum distance between the tooltip and the edge of the safe area. */
+    readonly viewportPadding: 12;
+    /** Minimum distance between an arrow and the tooltip's corners. */
+    readonly arrowPadding: 16;
+};
+/** How long to wait for a step's target to appear before skipping it. */
+export declare const targetTimeoutMs = 5000;
+/**
+ * Safety cap for `onBeforeStep`. The tour covers the app meanwhile, so it cannot be waiting for the
+ * user; one that never settles would otherwise leave a dimmed screen with no way out.
+ */
+export declare const beforeStepTimeoutMs = 30000;
+export type TourPhase = 'idle' | 'preparing' | 'revealing' | 'showing';
+/** The step currently on screen. */
+export type ShownStep = {
+    /** Changes only when a step is (re)shown: renderers animate when it changes and apply everything else instantly. */
+    readonly transitionId: number;
+    readonly stepIndex: number;
+    readonly step: TourStep;
+    /** The highlighted part of the target in layer coordinates, or `undefined` for a centred step. */
+    readonly highlight: Box | undefined;
+    readonly layout: TooltipLayout;
+};
+/** Asks the renderer to render the pending step's tooltip invisibly and report its size. */
+export type MeasureRequest = {
+    readonly id: number;
+    readonly stepIndex: number;
+    readonly step: TourStep;
+    readonly maxWidth: number;
+    readonly maxHeight: number;
+};
+/** Everything a renderer needs. Changes only on structural events, never while idle. */
+export type TourViewState = {
+    readonly phase: TourPhase;
+    /**
+     * While `phase` is `'revealing'`: where the next target currently is, updated every frame while it
+     * is scrolled into view, so the highlight can travel with the content.
+     */
+    readonly revealHighlight: Box | undefined;
+    /**
+     * How `revealHighlight` moves: frame by frame with the target (`true`), or straight to where the
+     * target will end up (`false`, on platforms whose measurements lag behind scrolling).
+     */
+    readonly followsScroll: boolean;
+    /** Changes for every tour, so renderers can tell a new tour from a step change. */
+    readonly tourKey: number;
+    readonly steps: readonly TourStep[];
+    readonly shown: ShownStep | undefined;
+    readonly measure: MeasureRequest | undefined;
+};
+export type TourPublicState = Pick<TourContextType, 'isActive' | 'currentStep' | 'steps' | 'currentTourId'>;
+export type TourActions = Pick<TourContextType, 'startTour' | 'endTour' | 'nextStep' | 'prevStep' | 'goToStep'>;
+export type TourEngineOptions = {
+    readonly adapter: TourAdapter;
+    readonly onTourEnd?: TourEndCallback | undefined;
+};
+export type TourEngine = {
+    readonly subscribe: (listener: () => void) => () => void;
+    readonly getPublicState: () => TourPublicState;
+    readonly getViewState: () => TourViewState;
+    /** Stable for the lifetime of the engine. */
+    readonly actions: TourActions;
+    /** Replaces the options (latest props). Never restarts anything. */
+    readonly configure: (options: TourEngineOptions) => void;
+    /** Call on mount; returns the cleanup. Tolerates StrictMode's simulated unmount. */
+    readonly mount: () => () => void;
+    /** Reports the rendered size of a measured tooltip (`MeasureRequest.id`) or of the shown one (`transitionId`). */
+    readonly reportTooltipSize: (id: number, size: Size) => void;
+    /** Ends the tour because of user input in the renderer. */
+    readonly dismiss: (reason: Extract<TourEndReason, 'closed' | 'blur' | 'escape'>) => void;
+};
+/**
+ * Creates the platform-independent tour engine: a small store plus the step lifecycle
+ * (`onBeforeStep` → wait for target → measure tooltip → scroll into view → verify → show).
+ *
+ * Every step change is driven by an action, never by a re-render, so user callbacks run exactly
+ * once per navigation no matter how often React renders. Every asynchronous step is cancellable.
+ */
+export declare function createTourEngine(initialOptions: TourEngineOptions): TourEngine;
+//# sourceMappingURL=tour-engine.d.ts.map

package/dist/shared/engine/tour-engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tour-engine.d.ts","sourceRoot":"","sources":["../../../src/shared/engine/tour-engine.ts"],"names":[],"mappings":"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"}