sitetourkit 0.0.0-stage → 0.7.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,613 @@
1
+ /**
2
+ * Pluggable persistence used by `showOnce` (tours) and `rememberDismissed`
3
+ * (hints). Web storage calls are wrapped in try/catch with an in-memory
4
+ * fallback: privacy modes and storage quotas must never break a tour.
5
+ */
6
+ interface StorageAdapter {
7
+ get(key: string): string | null;
8
+ set(key: string, value: string): void;
9
+ remove(key: string): void;
10
+ }
11
+ type StorageKind = "local" | "session" | StorageAdapter;
12
+ /** Public in-process adapter (`storage: memoryStorage` in options). */
13
+ declare const memoryStorage: StorageAdapter;
14
+ declare function resolveStorage(kind?: StorageKind): StorageAdapter;
15
+
16
+ /** Sides the tooltip can be placed on, relative to the target. */
17
+ type Side = "top" | "bottom" | "left" | "right";
18
+ /** Cross-axis alignment of the tooltip along the chosen side. */
19
+ type Align = "start" | "center" | "end";
20
+ /**
21
+ * Placement of the tooltip: a side with optional alignment,
22
+ * or "center" for a floating step without a target.
23
+ */
24
+ type Placement = Side | `${Side}-${Align}` | "center";
25
+
26
+ interface Labels {
27
+ next: string;
28
+ back: string;
29
+ done: string;
30
+ skip: string;
31
+ /** Template for "3 of 7"; `{step}` and `{total}` are substituted. */
32
+ stepOf: string;
33
+ /** aria-label announcing the step, e.g. for the live region. */
34
+ stepAnnouncement: string;
35
+ /** Label of the `showOnce` checkbox. */
36
+ dontShowAgain: string;
37
+ /**
38
+ * Dismiss button of a hint popover (`sitetourkit/hints`). Optional so existing
39
+ * custom label sets keep type-checking; the bundled locales all provide it.
40
+ */
41
+ hintDismiss?: string;
42
+ }
43
+ interface ShowOnceOptions {
44
+ /** Persistence key, e.g. "tour:onboarding". */
45
+ key: string;
46
+ /** Where to persist: localStorage (default), sessionStorage or a custom adapter. */
47
+ storage?: StorageKind;
48
+ /** Render a "don't show this again" checkbox in the tooltip. */
49
+ checkbox?: boolean;
50
+ /**
51
+ * Show the tour again after this many milliseconds ("remind me in 30 days").
52
+ * Omitted means the opt-out never expires.
53
+ */
54
+ ttlMs?: number;
55
+ }
56
+ interface ScrollOptions {
57
+ /** Vertical positioning of the target after scrolling. "off" disables scrolling. */
58
+ block: "center" | "nearest" | "off";
59
+ behavior: "smooth" | "auto";
60
+ /** Extra distance in px kept between the target and the viewport edge. */
61
+ padding: number;
62
+ }
63
+ interface OverlayOptions {
64
+ opacity: number;
65
+ color: string;
66
+ /** Gap in px between the target and the spotlight cutout edge. */
67
+ padding: number;
68
+ /** Corner radius of the cutout in px. */
69
+ radius: number;
70
+ clickToExit: boolean;
71
+ /** Duration of the cutout "flow" animation between steps, in ms. */
72
+ transitionMs: number;
73
+ }
74
+ interface ButtonsOptions {
75
+ next: boolean;
76
+ back: boolean;
77
+ skip: boolean;
78
+ /** Turn the Next button into Done on the last step (otherwise Next is disabled). */
79
+ doneOnLast: boolean;
80
+ /** Hide the Back button on the first step instead of rendering it disabled. */
81
+ hideBackOnFirst: boolean;
82
+ /**
83
+ * Hide the Next button on the last step instead of rendering it disabled.
84
+ * Only applies when `doneOnLast` is off (otherwise Done is shown).
85
+ */
86
+ hideNextOnLast: boolean;
87
+ }
88
+ /**
89
+ * Waiting for an asynchronously mounted target (SPA views, lazy widgets).
90
+ * While the target is missing the step floats in the center; the DOM is
91
+ * watched and the spotlight flows to the target as soon as it appears.
92
+ */
93
+ interface WaitForTargetOptions {
94
+ /** How long to keep watching for the target, in ms. */
95
+ timeoutMs: number;
96
+ /** After the timeout: keep the floating step or skip to the next one. */
97
+ onTimeout: "float" | "skip";
98
+ }
99
+ /**
100
+ * Auto-advance when the user interacts with the highlighted target
101
+ * ("click here to continue"). `true` means `{ event: "click" }`.
102
+ * Requires interaction with the target (`disableInteraction: false`).
103
+ */
104
+ type AdvanceOn = true | {
105
+ event?: string;
106
+ };
107
+ /** Resolvable reference to a step's target element. */
108
+ type TargetRef = string | Element | (() => Element | null);
109
+ interface StepContext {
110
+ index: number;
111
+ step: Step;
112
+ target: Element | null;
113
+ }
114
+ /**
115
+ * Custom renderer for step content. Receives the content host element;
116
+ * may return a cleanup function invoked when the step changes or the tour ends.
117
+ */
118
+ type RenderStep = (ctx: StepContext, host: HTMLElement) => void | (() => void);
119
+ interface StepInput {
120
+ /** Highlight target. Omit for a centered, floating step. */
121
+ target?: TargetRef;
122
+ /** Additional elements to spotlight together with `target` (extra cutouts). */
123
+ highlight?: TargetRef[];
124
+ title?: string;
125
+ content: string;
126
+ placement?: Placement;
127
+ disableInteraction?: boolean;
128
+ scroll?: Partial<ScrollOptions>;
129
+ classes?: {
130
+ tooltip?: string;
131
+ };
132
+ /** Overrides `TourOptions.renderStep` for this step. */
133
+ renderStep?: RenderStep;
134
+ /** Overrides `TourOptions.waitForTarget` for this step; `false` disables. */
135
+ waitForTarget?: Partial<WaitForTargetOptions> | false;
136
+ /** Overrides `TourOptions.lockScroll` for this step. */
137
+ lockScroll?: boolean;
138
+ /** Advance to the next step when the target receives this event. */
139
+ advanceOn?: AdvanceOn;
140
+ /** Return `false` to cancel showing this step (navigation is aborted). */
141
+ onBeforeShow?: (ctx: StepContext) => void | boolean | Promise<void | boolean>;
142
+ onShown?: (ctx: StepContext) => void;
143
+ }
144
+ /** Normalized step used internally and exposed via `tour.steps`. */
145
+ interface Step extends StepInput {
146
+ placement: Placement;
147
+ disableInteraction: boolean;
148
+ lockScroll: boolean;
149
+ /** Resolved waiting policy (tour default merged with the step override). */
150
+ waitForTarget: WaitForTargetOptions | false;
151
+ }
152
+ interface TourOptions {
153
+ steps: StepInput[];
154
+ /** Where the tour root is mounted. Defaults to `document.body`. */
155
+ container?: Element;
156
+ /**
157
+ * Scope for resolving string selectors and for scanning `[data-tour]`
158
+ * elements. Pass a `ShadowRoot` (or a subtree element) to tour content
159
+ * inside a web component: `document.querySelector` cannot reach into a
160
+ * shadow tree. Function targets work regardless of this option.
161
+ */
162
+ root?: Document | ShadowRoot | Element;
163
+ /**
164
+ * Base name of the declarative attributes, `data-tour` by default. Set it
165
+ * when the page already uses `data-tour` for its own purposes — otherwise
166
+ * a `createTour()` without `steps` would build a tour out of that markup.
167
+ * Modifiers follow the base name: `data-tk-step-title`, `-placement`, ...
168
+ */
169
+ dataAttribute?: string;
170
+ labels: Labels;
171
+ buttons: ButtonsOptions;
172
+ bullets: boolean;
173
+ progress: boolean;
174
+ stepNumbers: boolean;
175
+ placement: Placement;
176
+ placementPrecedence: Side[];
177
+ overlay: OverlayOptions;
178
+ keyboard: boolean;
179
+ /**
180
+ * Exit on Esc. An Esc the host already handled (`event.defaultPrevented`)
181
+ * is ignored, so a dialog opened on top of a step can close without ending
182
+ * the tour. Navigation keys are exempt from that check: apps routinely
183
+ * preventDefault arrows to stop the page from scrolling.
184
+ */
185
+ exitOnEsc: boolean;
186
+ disableInteraction: boolean;
187
+ /**
188
+ * Mark `<body>` with `tk-tour-active` while the tour is mounted, so host
189
+ * CSS can move its own chrome (toasts, sticky bars) out of the way.
190
+ */
191
+ hostClasses: boolean;
192
+ /**
193
+ * Freeze page scrolling while the tour runs (opt-in), compensating for the
194
+ * scrollbar so the layout does not jump. Like `modal`, this deliberately
195
+ * mutates the host document element and restores it on exit. Programmatic
196
+ * scrolling to targets keeps working — only the user's own scrolling is
197
+ * blocked. Can be overridden per step.
198
+ */
199
+ lockScroll: boolean;
200
+ /**
201
+ * Modal mode (opt-in): the tooltip gets `aria-modal="true"` and everything
202
+ * outside the tour root is made `inert` while the tour runs. This is the
203
+ * one deliberate exception (besides the temporary scroll-margin) to the
204
+ * "never mutate the host DOM" rule — attributes are restored on exit.
205
+ * Implies that the highlighted target is not interactive.
206
+ */
207
+ modal: boolean;
208
+ /**
209
+ * Wait for asynchronously mounted targets (SPA). Steps whose target is
210
+ * missing float in the center while the DOM is watched; the spotlight
211
+ * flows to the target once it appears. `false` disables watching.
212
+ */
213
+ waitForTarget: WaitForTargetOptions | false;
214
+ scroll: ScrollOptions;
215
+ /**
216
+ * When `true`, step title/content are rendered as HTML.
217
+ * Off by default: content is rendered via `textContent` (XSS-safe).
218
+ */
219
+ allowHTML: boolean;
220
+ /**
221
+ * Applied to every HTML string before it is inserted, when `allowHTML` is
222
+ * on. Plug in DOMPurify (or an equivalent) to keep untrusted content safe:
223
+ * `sanitize: (html) => DOMPurify.sanitize(html)`. Ignored while
224
+ * `allowHTML` is off, where everything already goes through `textContent`.
225
+ */
226
+ sanitize?: (html: string) => string;
227
+ /**
228
+ * Show the tour only once per user: `start()` becomes a no-op after the
229
+ * tour has been completed (or opted out via the checkbox).
230
+ */
231
+ showOnce?: ShowOnceOptions;
232
+ /**
233
+ * Multi-page tours: persists the current step index on every step change,
234
+ * `start()` resumes from the stored index; completing or explicitly exiting
235
+ * the tour clears the key (navigating away does not).
236
+ */
237
+ persistProgress?: {
238
+ key: string;
239
+ storage?: StorageKind;
240
+ };
241
+ /** Default custom renderer for step content (per-step `renderStep` wins). */
242
+ renderStep?: RenderStep;
243
+ theme?: string;
244
+ classes?: {
245
+ tooltip?: string;
246
+ overlay?: string;
247
+ button?: string;
248
+ };
249
+ zIndex?: number;
250
+ }
251
+ /** User-facing options: everything optional, nested objects partial. */
252
+ type TourOptionsInput = Partial<Omit<TourOptions, "labels" | "buttons" | "overlay" | "scroll" | "waitForTarget">> & {
253
+ labels?: Partial<Labels>;
254
+ buttons?: Partial<ButtonsOptions>;
255
+ overlay?: Partial<OverlayOptions>;
256
+ scroll?: Partial<ScrollOptions>;
257
+ waitForTarget?: Partial<WaitForTargetOptions> | false;
258
+ };
259
+ type Direction = "forward" | "backward";
260
+ type CompleteReason = "finished" | "skipped";
261
+ /**
262
+ * A type alias (not an interface): aliases get an implicit index signature,
263
+ * which satisfies the emitter's `EventMap` constraint while `keyof TourEvents`
264
+ * stays a closed union — typos in event names fail to compile.
265
+ */
266
+ type TourEvents = {
267
+ start: (e: {
268
+ steps: ReadonlyArray<Step>;
269
+ }) => void | Promise<void>;
270
+ beforeStepChange: (e: {
271
+ from: number | undefined;
272
+ to: number;
273
+ direction: Direction;
274
+ step: Step;
275
+ cancel(): void;
276
+ }) => void | Promise<void>;
277
+ stepChange: (e: StepContext) => void | Promise<void>;
278
+ beforeExit: (e: {
279
+ cancel(): void;
280
+ }) => void | Promise<void>;
281
+ exit: (e: Record<string, never>) => void | Promise<void>;
282
+ complete: (e: {
283
+ reason: CompleteReason;
284
+ }) => void | Promise<void>;
285
+ };
286
+
287
+ /** Per-call overrides for `Tour.start`. */
288
+ interface StartOptions {
289
+ /**
290
+ * Tear down any other running tour first (and wait for it). Without this,
291
+ * starting a second tour leaves two overlays and two focus traps on screen
292
+ * and only logs a warning — switching tours from a menu is the common case.
293
+ */
294
+ replace?: boolean;
295
+ }
296
+ interface Tour {
297
+ /**
298
+ * Starts the tour. Resolves to `false` when there is nothing to show
299
+ * (no steps, already running, opted out via `showOnce`, or no DOM).
300
+ */
301
+ start(options?: StartOptions): Promise<boolean>;
302
+ /** Ends the tour; `force` bypasses the `beforeExit` guard. */
303
+ exit(force?: boolean): Promise<boolean>;
304
+ /**
305
+ * Completes the tour programmatically with `reason: "finished"` (fires
306
+ * `beforeExit` → `complete` → `exit`, marks `showOnce` as seen).
307
+ * Resolves to `false` when inactive or cancelled by the guard.
308
+ */
309
+ complete(): Promise<boolean>;
310
+ /** Instant teardown: removes DOM and all listeners, no events, no animations. */
311
+ destroy(): void;
312
+ next(): Promise<void>;
313
+ back(): Promise<void>;
314
+ /** Jumps to a step by 0-based index. */
315
+ goTo(index: number): Promise<void>;
316
+ /** Re-syncs geometry; with `rescanSteps` also re-reads steps and re-renders the current one. */
317
+ refresh(rescanSteps?: boolean): void;
318
+ readonly index: number | undefined;
319
+ readonly steps: ReadonlyArray<Step>;
320
+ readonly isActive: boolean;
321
+ /** Applies an options patch; an active tour re-renders the current step live. */
322
+ setOptions(patch: TourOptionsInput): Tour;
323
+ on<E extends keyof TourEvents & string>(event: E, handler: TourEvents[E]): () => void;
324
+ once<E extends keyof TourEvents & string>(event: E, handler: TourEvents[E]): () => void;
325
+ }
326
+ /**
327
+ * Step index saved by `persistProgress`, or `null` when there is nothing to
328
+ * resume. Lets a host decide whether to offer "continue where you left off"
329
+ * *before* building the tour, without reading the storage format itself —
330
+ * that format is an implementation detail and has changed before.
331
+ */
332
+ declare function getPersistedProgress(key: string, storage?: StorageKind): number | null;
333
+ /**
334
+ * Creates a tour instance. Safe to call in SSR environments: the DOM is only
335
+ * touched by `start()`, which no-ops (with a warning) outside the browser.
336
+ */
337
+ declare function createTour(input?: TourOptionsInput): Tour;
338
+
339
+ /** Applies tour-level defaults to raw step inputs. */
340
+ declare function normalizeSteps(inputs: StepInput[], options: TourOptions): Step[];
341
+ interface FromDataAttributesOptions {
342
+ /** Only include elements whose `<attribute>-group` equals this value. */
343
+ group?: string;
344
+ /**
345
+ * Base attribute name, `data-tour` by default. Every modifier derives from
346
+ * it (`data-tour-title`, `-step`, ...), so a page that already uses
347
+ * `data-tour` for something else can scan `data-tk-step` instead.
348
+ */
349
+ attribute?: string;
350
+ }
351
+ declare const DEFAULT_DATA_ATTRIBUTE = "data-tour";
352
+ /**
353
+ * Validates a custom base attribute. A name without the `data-` prefix would
354
+ * produce invalid markup and a selector that silently matches nothing.
355
+ */
356
+ declare function resolveDataAttribute(attribute?: string): string;
357
+ /**
358
+ * Collects steps declared in HTML via `data-tour*` attributes.
359
+ *
360
+ * Elements with an explicit `data-tour-step="N"` claim slot N (1-based);
361
+ * elements without a number fill the remaining gaps in document order.
362
+ * Hidden elements (`display: none`, `visibility: hidden`) are skipped.
363
+ *
364
+ * Supported attributes: `data-tour` (content), `-title`, `-step`, `-group`,
365
+ * `-placement`, `-no-interaction`, `-lock-scroll`, `-highlight` (extra
366
+ * cutouts), `-wait` (async target policy) and `-advance-on` (auto-next).
367
+ * The base name is configurable via `options.attribute`.
368
+ */
369
+ declare function fromDataAttributes(root?: ParentNode, options?: FromDataAttributesOptions): StepInput[];
370
+
371
+ /**
372
+ * Declarative tour launcher for server-rendered pages (e.g. ASP.NET MVC):
373
+ * any element with `data-tour-trigger` starts a tour on click without a single
374
+ * line of application JS beyond `bindTriggers()`. A non-empty attribute value
375
+ * filters scanned steps by `data-tour-group`.
376
+ *
377
+ * Steps are scanned inside `root`, so a binding scoped to a widget only tours
378
+ * that widget. Uses event delegation, so triggers added to the DOM later
379
+ * (partial views, AJAX) keep working.
380
+ *
381
+ * `options.dataAttribute` renames the whole family, trigger included:
382
+ * `data-tk-step` markup is launched by `[data-tk-step-trigger]`.
383
+ *
384
+ * Returns an unbind function. Unbinding also destroys the tour this binding
385
+ * started (instant teardown, no events) — a route change must not leave an
386
+ * overlay, a focus trap and a DOM watcher behind.
387
+ */
388
+ declare function bindTriggers(root?: ParentNode, options?: TourOptionsInput): () => void;
389
+
390
+ interface HighlightOptions {
391
+ overlay?: Partial<OverlayOptions>;
392
+ /** Scroll the target into view; `false` disables. */
393
+ scroll?: Partial<ScrollOptions> | false;
394
+ /**
395
+ * Dismiss on Esc (default true), unless the host already handled that Esc
396
+ * (`event.defaultPrevented`). Backdrop clicks obey `overlay.clickToExit`.
397
+ */
398
+ exitOnEsc?: boolean;
399
+ /** Mark `<body>` with `tk-highlight-active` while the spotlight is up. */
400
+ hostClasses?: boolean;
401
+ theme?: string;
402
+ zIndex?: number;
403
+ container?: Element;
404
+ /** Scope for resolving string selectors (e.g. a `ShadowRoot`). */
405
+ root?: Document | ShadowRoot | Element;
406
+ classes?: {
407
+ overlay?: string;
408
+ };
409
+ }
410
+ /** Per-call overrides for `Highlight.move`. */
411
+ interface HighlightMoveOptions {
412
+ /** Scroll the new target into view (default: the instance's `scroll` policy). */
413
+ scroll?: boolean;
414
+ }
415
+ interface Highlight {
416
+ /**
417
+ * Moves the spotlight to another target: the cutout flows to it and the
418
+ * page scrolls it into view. Pass `{ scroll: false }` when the caller is
419
+ * only re-pointing at an equivalent element (a re-rendered node) and the
420
+ * viewport must stay where the user left it.
421
+ */
422
+ move(target: TargetRef, options?: HighlightMoveOptions): void;
423
+ /**
424
+ * Re-syncs the cutout with the current DOM geometry. Cheap and silent: no
425
+ * animation, no scrolling. A string or function target is resolved again,
426
+ * so a target replaced by a re-render is picked up automatically.
427
+ */
428
+ refresh(): void;
429
+ /** Removes the spotlight and all listeners. */
430
+ destroy(): void;
431
+ readonly isActive: boolean;
432
+ }
433
+ /**
434
+ * Standalone spotlight without a tour: dims the page and cuts a hole around
435
+ * the target — no tooltip, no focus management. Reuses the tour's overlay,
436
+ * geometry tracking and scrolling, so it works inside transform/filter
437
+ * stacking contexts and follows the target on scroll/resize.
438
+ */
439
+ declare function highlight(target: TargetRef, options?: HighlightOptions): Highlight;
440
+
441
+ /**
442
+ * Minimal typed event emitter.
443
+ * Handlers may be async; `emit` awaits all of them sequentially so that
444
+ * cancellable events (via `cancel()`) work with asynchronous listeners.
445
+ */
446
+ type EventMap = Record<string, (payload: never) => void | Promise<void>>;
447
+ declare class Emitter<TEvents extends EventMap> {
448
+ private readonly _listeners;
449
+ /** Subscribe to an event. Returns an unsubscribe function. */
450
+ on<E extends keyof TEvents>(event: E, handler: TEvents[E]): () => void;
451
+ /** Subscribe to a single occurrence of an event. */
452
+ once<E extends keyof TEvents>(event: E, handler: TEvents[E]): () => void;
453
+ off<E extends keyof TEvents>(event: E, handler: TEvents[E]): void;
454
+ /**
455
+ * Handlers are application code: one of them throwing must not abort the
456
+ * remaining listeners, reject the transition promise (the tour drives
457
+ * transitions with `void engine.next()`, so nobody would catch it) or leave
458
+ * the tour half-rendered. Failures are reported and swallowed — a broken
459
+ * analytics callback is not a reason to strand the user mid-tour.
460
+ */
461
+ emit<E extends keyof TEvents>(event: E, payload: Parameters<TEvents[E]>[0]): Promise<void>;
462
+ removeAll(): void;
463
+ }
464
+
465
+ type EngineState = "idle" | "active";
466
+ /**
467
+ * The engine drives step transitions and emits lifecycle events;
468
+ * a delegate (the DOM renderer) performs the actual visuals.
469
+ * The engine itself never touches the DOM apart from resolving target refs,
470
+ * which keeps it fully unit-testable.
471
+ */
472
+ interface EngineDelegate {
473
+ mount(): void | Promise<void>;
474
+ showStep(ctx: StepContext, direction: Direction): void | Promise<void>;
475
+ unmount(): void | Promise<void>;
476
+ }
477
+ /**
478
+ * Resolves a step target. String selectors are queried inside `scope`, which
479
+ * defaults to the document — pass a `ShadowRoot` to reach elements a plain
480
+ * `document.querySelector` cannot see. Element and function refs ignore it.
481
+ */
482
+ declare function resolveTarget(ref: TargetRef | undefined, scope?: ParentNode): Element | null;
483
+ declare class TourEngine {
484
+ private readonly _delegate;
485
+ private readonly _getScope;
486
+ readonly events: Emitter<TourEvents>;
487
+ private _state;
488
+ private _steps;
489
+ private _index;
490
+ private _queue;
491
+ /**
492
+ * `getScope` supplies the lookup root for string targets; it is a callback
493
+ * because the tour facade lets `setOptions` change it mid-flight.
494
+ */
495
+ constructor(_delegate: EngineDelegate, _getScope?: () => ParentNode | undefined);
496
+ get state(): EngineState;
497
+ get index(): number | undefined;
498
+ get steps(): ReadonlyArray<Step>;
499
+ get isActive(): boolean;
500
+ setSteps(steps: Step[]): void;
501
+ /**
502
+ * Serializes all public transitions: a rapid double-click on "Next"
503
+ * runs the second transition only after the first one fully settles.
504
+ */
505
+ private _enqueue;
506
+ /** Starts the tour, optionally from a specific step (multi-page resume). */
507
+ start(steps: Step[], startAt?: number): Promise<boolean>;
508
+ next(): Promise<void>;
509
+ back(): Promise<void>;
510
+ goTo(index: number): Promise<void>;
511
+ /** Exit initiated by the skip/close button: reports the tour as completed-by-skipping. */
512
+ skip(): Promise<boolean>;
513
+ /**
514
+ * Programmatic completion: reports the tour as `finished` regardless of the
515
+ * current step (e.g. the user reached the goal outside the tour flow).
516
+ * Guarded by `beforeExit` like every other completion path.
517
+ */
518
+ complete(): Promise<boolean>;
519
+ exit(force?: boolean): Promise<boolean>;
520
+ /** Re-shows the current step without firing navigation guards (used by refresh). */
521
+ reshow(): Promise<void>;
522
+ /** Immediate reset used by destroy(); the delegate is torn down by the caller. */
523
+ forceIdle(): void;
524
+ private _complete;
525
+ private _goTo;
526
+ private _exit;
527
+ /** Emits the cancellable `beforeExit` guard; `false` means "stay active". */
528
+ private _requestExit;
529
+ private _teardown;
530
+ }
531
+
532
+ /** Axis-aligned rectangle in viewport coordinates. */
533
+ interface Rect {
534
+ x: number;
535
+ y: number;
536
+ width: number;
537
+ height: number;
538
+ }
539
+ interface Size {
540
+ width: number;
541
+ height: number;
542
+ }
543
+
544
+ interface PlacementConfig {
545
+ /** Distance between the target rect and the tooltip (arrow included). */
546
+ gap: number;
547
+ /** Minimum distance kept between the tooltip and the viewport edges. */
548
+ viewportPadding: number;
549
+ /** Half-diagonal of the arrow square; keeps the arrow away from rounded corners. */
550
+ arrowInset: number;
551
+ /**
552
+ * Right-to-left context: `start`/`end` alignments are logical and mirror
553
+ * on the horizontal axis (top/bottom sides). Physical sides stay as-is.
554
+ */
555
+ rtl: boolean;
556
+ }
557
+ declare const defaultPlacementConfig: PlacementConfig;
558
+ interface ResolvedPlacement {
559
+ /** Final side after flipping, or "center" when nothing fits / no target. */
560
+ side: Side | "center";
561
+ align: Align;
562
+ x: number;
563
+ y: number;
564
+ /**
565
+ * Arrow offset along the tooltip edge (distance from the tooltip's
566
+ * left edge for top/bottom sides, from the top edge for left/right).
567
+ * `null` for centered placement (no arrow).
568
+ */
569
+ arrow: number | null;
570
+ }
571
+ /**
572
+ * Validates a placement coming from untyped sources (data attributes, the
573
+ * intro.js adapter). An unknown value would silently degrade to a centered
574
+ * tooltip, which reads as "the library ignored my markup".
575
+ */
576
+ declare function isPlacement(value: string | null | undefined): value is Placement;
577
+ declare function parsePlacement(placement: Placement): {
578
+ side: Side | "center";
579
+ align: Align | undefined;
580
+ };
581
+ /**
582
+ * Resolves the tooltip position in three passes:
583
+ * 1. flip — keep the desired side if it fits, otherwise walk `precedence`,
584
+ * falling back to "center" when no side has room;
585
+ * 2. shift — clamp the cross-axis coordinate into the viewport;
586
+ * 3. arrow — project the target center onto the tooltip edge and clamp it
587
+ * away from the corners.
588
+ */
589
+ declare function resolvePlacement(desired: Placement, target: Rect | null, tooltip: Size, viewport: Rect, precedence: Side[], config?: Partial<PlacementConfig>): ResolvedPlacement;
590
+
591
+ /**
592
+ * Watches the signals that commonly move the target relative to the viewport
593
+ * (scrolling in any container, window resize, element/document resize) and
594
+ * invokes the callback at most once per animation frame.
595
+ *
596
+ * Not covered: CSS transform changes, sibling DOM reordering and other layout
597
+ * shifts that leave every observed size untouched — call `tour.refresh()`
598
+ * after such mutations.
599
+ *
600
+ * Returns a cleanup function.
601
+ */
602
+ declare function autoUpdate(elements: Array<Element | null>, callback: () => void): () => void;
603
+
604
+ declare const defaultLabels: Labels;
605
+ declare function getDefaultOptions(): TourOptions;
606
+
607
+ /**
608
+ * Library version. Injected from package.json at build time (tsup/vitest
609
+ * `define`); dev servers without the define see the "0.0.0-dev" fallback.
610
+ */
611
+ declare const version: string;
612
+
613
+ export { type AdvanceOn, type Align, type ButtonsOptions, type CompleteReason, DEFAULT_DATA_ATTRIBUTE, type Direction, Emitter, type EngineDelegate, type EngineState, type EventMap, type FromDataAttributesOptions, type Highlight, type HighlightMoveOptions, type HighlightOptions, type Labels, type OverlayOptions, type Placement, type PlacementConfig, type Rect, type RenderStep, type ResolvedPlacement, type ScrollOptions, type ShowOnceOptions, type Side, type Size, type StartOptions, type Step, type StepContext, type StepInput, type StorageAdapter, type StorageKind, type TargetRef, type Tour, TourEngine, type TourEvents, type TourOptions, type TourOptionsInput, type WaitForTargetOptions, autoUpdate, bindTriggers, createTour, defaultLabels, defaultPlacementConfig, fromDataAttributes, getDefaultOptions, getPersistedProgress, highlight, isPlacement, memoryStorage, normalizeSteps, parsePlacement, resolveDataAttribute, resolvePlacement, resolveStorage, resolveTarget, version };