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.
- package/CHANGELOG.md +436 -0
- package/LICENSE +21 -0
- package/README.md +323 -2
- package/dist/compat-introjs.cjs +7 -0
- package/dist/compat-introjs.d.cts +118 -0
- package/dist/compat-introjs.d.ts +118 -0
- package/dist/compat-introjs.global.js +7 -0
- package/dist/compat-introjs.js +7 -0
- package/dist/hints.cjs +7 -0
- package/dist/hints.d.cts +131 -0
- package/dist/hints.d.ts +131 -0
- package/dist/hints.global.js +7 -0
- package/dist/hints.js +7 -0
- package/dist/index.cjs +7 -0
- package/dist/index.d.cts +613 -0
- package/dist/index.d.ts +613 -0
- package/dist/index.global.js +7 -0
- package/dist/index.js +7 -0
- package/dist/inject-styles.cjs +680 -0
- package/dist/inject-styles.d.cts +20 -0
- package/dist/inject-styles.d.ts +20 -0
- package/dist/inject-styles.js +680 -0
- package/dist/locales.cjs +7 -0
- package/dist/locales.d.cts +28 -0
- package/dist/locales.d.ts +28 -0
- package/dist/locales.global.js +7 -0
- package/dist/locales.js +7 -0
- package/dist/styles.css +673 -0
- package/dist/types-M-1II5wP.d.cts +257 -0
- package/dist/types-M-1II5wP.d.ts +257 -0
- package/package.json +195 -4
|
@@ -0,0 +1,257 @@
|
|
|
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
|
+
|
|
13
|
+
/** Sides the tooltip can be placed on, relative to the target. */
|
|
14
|
+
type Side = "top" | "bottom" | "left" | "right";
|
|
15
|
+
/** Cross-axis alignment of the tooltip along the chosen side. */
|
|
16
|
+
type Align = "start" | "center" | "end";
|
|
17
|
+
/**
|
|
18
|
+
* Placement of the tooltip: a side with optional alignment,
|
|
19
|
+
* or "center" for a floating step without a target.
|
|
20
|
+
*/
|
|
21
|
+
type Placement = Side | `${Side}-${Align}` | "center";
|
|
22
|
+
|
|
23
|
+
interface Labels {
|
|
24
|
+
next: string;
|
|
25
|
+
back: string;
|
|
26
|
+
done: string;
|
|
27
|
+
skip: string;
|
|
28
|
+
/** Template for "3 of 7"; `{step}` and `{total}` are substituted. */
|
|
29
|
+
stepOf: string;
|
|
30
|
+
/** aria-label announcing the step, e.g. for the live region. */
|
|
31
|
+
stepAnnouncement: string;
|
|
32
|
+
/** Label of the `showOnce` checkbox. */
|
|
33
|
+
dontShowAgain: string;
|
|
34
|
+
/**
|
|
35
|
+
* Dismiss button of a hint popover (`sitetourkit/hints`). Optional so existing
|
|
36
|
+
* custom label sets keep type-checking; the bundled locales all provide it.
|
|
37
|
+
*/
|
|
38
|
+
hintDismiss?: string;
|
|
39
|
+
}
|
|
40
|
+
interface ShowOnceOptions {
|
|
41
|
+
/** Persistence key, e.g. "tour:onboarding". */
|
|
42
|
+
key: string;
|
|
43
|
+
/** Where to persist: localStorage (default), sessionStorage or a custom adapter. */
|
|
44
|
+
storage?: StorageKind;
|
|
45
|
+
/** Render a "don't show this again" checkbox in the tooltip. */
|
|
46
|
+
checkbox?: boolean;
|
|
47
|
+
/**
|
|
48
|
+
* Show the tour again after this many milliseconds ("remind me in 30 days").
|
|
49
|
+
* Omitted means the opt-out never expires.
|
|
50
|
+
*/
|
|
51
|
+
ttlMs?: number;
|
|
52
|
+
}
|
|
53
|
+
interface ScrollOptions {
|
|
54
|
+
/** Vertical positioning of the target after scrolling. "off" disables scrolling. */
|
|
55
|
+
block: "center" | "nearest" | "off";
|
|
56
|
+
behavior: "smooth" | "auto";
|
|
57
|
+
/** Extra distance in px kept between the target and the viewport edge. */
|
|
58
|
+
padding: number;
|
|
59
|
+
}
|
|
60
|
+
interface OverlayOptions {
|
|
61
|
+
opacity: number;
|
|
62
|
+
color: string;
|
|
63
|
+
/** Gap in px between the target and the spotlight cutout edge. */
|
|
64
|
+
padding: number;
|
|
65
|
+
/** Corner radius of the cutout in px. */
|
|
66
|
+
radius: number;
|
|
67
|
+
clickToExit: boolean;
|
|
68
|
+
/** Duration of the cutout "flow" animation between steps, in ms. */
|
|
69
|
+
transitionMs: number;
|
|
70
|
+
}
|
|
71
|
+
interface ButtonsOptions {
|
|
72
|
+
next: boolean;
|
|
73
|
+
back: boolean;
|
|
74
|
+
skip: boolean;
|
|
75
|
+
/** Turn the Next button into Done on the last step (otherwise Next is disabled). */
|
|
76
|
+
doneOnLast: boolean;
|
|
77
|
+
/** Hide the Back button on the first step instead of rendering it disabled. */
|
|
78
|
+
hideBackOnFirst: boolean;
|
|
79
|
+
/**
|
|
80
|
+
* Hide the Next button on the last step instead of rendering it disabled.
|
|
81
|
+
* Only applies when `doneOnLast` is off (otherwise Done is shown).
|
|
82
|
+
*/
|
|
83
|
+
hideNextOnLast: boolean;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Waiting for an asynchronously mounted target (SPA views, lazy widgets).
|
|
87
|
+
* While the target is missing the step floats in the center; the DOM is
|
|
88
|
+
* watched and the spotlight flows to the target as soon as it appears.
|
|
89
|
+
*/
|
|
90
|
+
interface WaitForTargetOptions {
|
|
91
|
+
/** How long to keep watching for the target, in ms. */
|
|
92
|
+
timeoutMs: number;
|
|
93
|
+
/** After the timeout: keep the floating step or skip to the next one. */
|
|
94
|
+
onTimeout: "float" | "skip";
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Auto-advance when the user interacts with the highlighted target
|
|
98
|
+
* ("click here to continue"). `true` means `{ event: "click" }`.
|
|
99
|
+
* Requires interaction with the target (`disableInteraction: false`).
|
|
100
|
+
*/
|
|
101
|
+
type AdvanceOn = true | {
|
|
102
|
+
event?: string;
|
|
103
|
+
};
|
|
104
|
+
/** Resolvable reference to a step's target element. */
|
|
105
|
+
type TargetRef = string | Element | (() => Element | null);
|
|
106
|
+
interface StepContext {
|
|
107
|
+
index: number;
|
|
108
|
+
step: Step;
|
|
109
|
+
target: Element | null;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Custom renderer for step content. Receives the content host element;
|
|
113
|
+
* may return a cleanup function invoked when the step changes or the tour ends.
|
|
114
|
+
*/
|
|
115
|
+
type RenderStep = (ctx: StepContext, host: HTMLElement) => void | (() => void);
|
|
116
|
+
interface StepInput {
|
|
117
|
+
/** Highlight target. Omit for a centered, floating step. */
|
|
118
|
+
target?: TargetRef;
|
|
119
|
+
/** Additional elements to spotlight together with `target` (extra cutouts). */
|
|
120
|
+
highlight?: TargetRef[];
|
|
121
|
+
title?: string;
|
|
122
|
+
content: string;
|
|
123
|
+
placement?: Placement;
|
|
124
|
+
disableInteraction?: boolean;
|
|
125
|
+
scroll?: Partial<ScrollOptions>;
|
|
126
|
+
classes?: {
|
|
127
|
+
tooltip?: string;
|
|
128
|
+
};
|
|
129
|
+
/** Overrides `TourOptions.renderStep` for this step. */
|
|
130
|
+
renderStep?: RenderStep;
|
|
131
|
+
/** Overrides `TourOptions.waitForTarget` for this step; `false` disables. */
|
|
132
|
+
waitForTarget?: Partial<WaitForTargetOptions> | false;
|
|
133
|
+
/** Overrides `TourOptions.lockScroll` for this step. */
|
|
134
|
+
lockScroll?: boolean;
|
|
135
|
+
/** Advance to the next step when the target receives this event. */
|
|
136
|
+
advanceOn?: AdvanceOn;
|
|
137
|
+
/** Return `false` to cancel showing this step (navigation is aborted). */
|
|
138
|
+
onBeforeShow?: (ctx: StepContext) => void | boolean | Promise<void | boolean>;
|
|
139
|
+
onShown?: (ctx: StepContext) => void;
|
|
140
|
+
}
|
|
141
|
+
/** Normalized step used internally and exposed via `tour.steps`. */
|
|
142
|
+
interface Step extends StepInput {
|
|
143
|
+
placement: Placement;
|
|
144
|
+
disableInteraction: boolean;
|
|
145
|
+
lockScroll: boolean;
|
|
146
|
+
/** Resolved waiting policy (tour default merged with the step override). */
|
|
147
|
+
waitForTarget: WaitForTargetOptions | false;
|
|
148
|
+
}
|
|
149
|
+
interface TourOptions {
|
|
150
|
+
steps: StepInput[];
|
|
151
|
+
/** Where the tour root is mounted. Defaults to `document.body`. */
|
|
152
|
+
container?: Element;
|
|
153
|
+
/**
|
|
154
|
+
* Scope for resolving string selectors and for scanning `[data-tour]`
|
|
155
|
+
* elements. Pass a `ShadowRoot` (or a subtree element) to tour content
|
|
156
|
+
* inside a web component: `document.querySelector` cannot reach into a
|
|
157
|
+
* shadow tree. Function targets work regardless of this option.
|
|
158
|
+
*/
|
|
159
|
+
root?: Document | ShadowRoot | Element;
|
|
160
|
+
/**
|
|
161
|
+
* Base name of the declarative attributes, `data-tour` by default. Set it
|
|
162
|
+
* when the page already uses `data-tour` for its own purposes — otherwise
|
|
163
|
+
* a `createTour()` without `steps` would build a tour out of that markup.
|
|
164
|
+
* Modifiers follow the base name: `data-tk-step-title`, `-placement`, ...
|
|
165
|
+
*/
|
|
166
|
+
dataAttribute?: string;
|
|
167
|
+
labels: Labels;
|
|
168
|
+
buttons: ButtonsOptions;
|
|
169
|
+
bullets: boolean;
|
|
170
|
+
progress: boolean;
|
|
171
|
+
stepNumbers: boolean;
|
|
172
|
+
placement: Placement;
|
|
173
|
+
placementPrecedence: Side[];
|
|
174
|
+
overlay: OverlayOptions;
|
|
175
|
+
keyboard: boolean;
|
|
176
|
+
/**
|
|
177
|
+
* Exit on Esc. An Esc the host already handled (`event.defaultPrevented`)
|
|
178
|
+
* is ignored, so a dialog opened on top of a step can close without ending
|
|
179
|
+
* the tour. Navigation keys are exempt from that check: apps routinely
|
|
180
|
+
* preventDefault arrows to stop the page from scrolling.
|
|
181
|
+
*/
|
|
182
|
+
exitOnEsc: boolean;
|
|
183
|
+
disableInteraction: boolean;
|
|
184
|
+
/**
|
|
185
|
+
* Mark `<body>` with `tk-tour-active` while the tour is mounted, so host
|
|
186
|
+
* CSS can move its own chrome (toasts, sticky bars) out of the way.
|
|
187
|
+
*/
|
|
188
|
+
hostClasses: boolean;
|
|
189
|
+
/**
|
|
190
|
+
* Freeze page scrolling while the tour runs (opt-in), compensating for the
|
|
191
|
+
* scrollbar so the layout does not jump. Like `modal`, this deliberately
|
|
192
|
+
* mutates the host document element and restores it on exit. Programmatic
|
|
193
|
+
* scrolling to targets keeps working — only the user's own scrolling is
|
|
194
|
+
* blocked. Can be overridden per step.
|
|
195
|
+
*/
|
|
196
|
+
lockScroll: boolean;
|
|
197
|
+
/**
|
|
198
|
+
* Modal mode (opt-in): the tooltip gets `aria-modal="true"` and everything
|
|
199
|
+
* outside the tour root is made `inert` while the tour runs. This is the
|
|
200
|
+
* one deliberate exception (besides the temporary scroll-margin) to the
|
|
201
|
+
* "never mutate the host DOM" rule — attributes are restored on exit.
|
|
202
|
+
* Implies that the highlighted target is not interactive.
|
|
203
|
+
*/
|
|
204
|
+
modal: boolean;
|
|
205
|
+
/**
|
|
206
|
+
* Wait for asynchronously mounted targets (SPA). Steps whose target is
|
|
207
|
+
* missing float in the center while the DOM is watched; the spotlight
|
|
208
|
+
* flows to the target once it appears. `false` disables watching.
|
|
209
|
+
*/
|
|
210
|
+
waitForTarget: WaitForTargetOptions | false;
|
|
211
|
+
scroll: ScrollOptions;
|
|
212
|
+
/**
|
|
213
|
+
* When `true`, step title/content are rendered as HTML.
|
|
214
|
+
* Off by default: content is rendered via `textContent` (XSS-safe).
|
|
215
|
+
*/
|
|
216
|
+
allowHTML: boolean;
|
|
217
|
+
/**
|
|
218
|
+
* Applied to every HTML string before it is inserted, when `allowHTML` is
|
|
219
|
+
* on. Plug in DOMPurify (or an equivalent) to keep untrusted content safe:
|
|
220
|
+
* `sanitize: (html) => DOMPurify.sanitize(html)`. Ignored while
|
|
221
|
+
* `allowHTML` is off, where everything already goes through `textContent`.
|
|
222
|
+
*/
|
|
223
|
+
sanitize?: (html: string) => string;
|
|
224
|
+
/**
|
|
225
|
+
* Show the tour only once per user: `start()` becomes a no-op after the
|
|
226
|
+
* tour has been completed (or opted out via the checkbox).
|
|
227
|
+
*/
|
|
228
|
+
showOnce?: ShowOnceOptions;
|
|
229
|
+
/**
|
|
230
|
+
* Multi-page tours: persists the current step index on every step change,
|
|
231
|
+
* `start()` resumes from the stored index; completing or explicitly exiting
|
|
232
|
+
* the tour clears the key (navigating away does not).
|
|
233
|
+
*/
|
|
234
|
+
persistProgress?: {
|
|
235
|
+
key: string;
|
|
236
|
+
storage?: StorageKind;
|
|
237
|
+
};
|
|
238
|
+
/** Default custom renderer for step content (per-step `renderStep` wins). */
|
|
239
|
+
renderStep?: RenderStep;
|
|
240
|
+
theme?: string;
|
|
241
|
+
classes?: {
|
|
242
|
+
tooltip?: string;
|
|
243
|
+
overlay?: string;
|
|
244
|
+
button?: string;
|
|
245
|
+
};
|
|
246
|
+
zIndex?: number;
|
|
247
|
+
}
|
|
248
|
+
/** User-facing options: everything optional, nested objects partial. */
|
|
249
|
+
type TourOptionsInput = Partial<Omit<TourOptions, "labels" | "buttons" | "overlay" | "scroll" | "waitForTarget">> & {
|
|
250
|
+
labels?: Partial<Labels>;
|
|
251
|
+
buttons?: Partial<ButtonsOptions>;
|
|
252
|
+
overlay?: Partial<OverlayOptions>;
|
|
253
|
+
scroll?: Partial<ScrollOptions>;
|
|
254
|
+
waitForTarget?: Partial<WaitForTargetOptions> | false;
|
|
255
|
+
};
|
|
256
|
+
|
|
257
|
+
export type { Labels as L, Placement as P, StepInput as S, TourOptionsInput as T, TargetRef as a, Side as b, ScrollOptions as c, StorageKind as d };
|
|
@@ -0,0 +1,257 @@
|
|
|
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
|
+
|
|
13
|
+
/** Sides the tooltip can be placed on, relative to the target. */
|
|
14
|
+
type Side = "top" | "bottom" | "left" | "right";
|
|
15
|
+
/** Cross-axis alignment of the tooltip along the chosen side. */
|
|
16
|
+
type Align = "start" | "center" | "end";
|
|
17
|
+
/**
|
|
18
|
+
* Placement of the tooltip: a side with optional alignment,
|
|
19
|
+
* or "center" for a floating step without a target.
|
|
20
|
+
*/
|
|
21
|
+
type Placement = Side | `${Side}-${Align}` | "center";
|
|
22
|
+
|
|
23
|
+
interface Labels {
|
|
24
|
+
next: string;
|
|
25
|
+
back: string;
|
|
26
|
+
done: string;
|
|
27
|
+
skip: string;
|
|
28
|
+
/** Template for "3 of 7"; `{step}` and `{total}` are substituted. */
|
|
29
|
+
stepOf: string;
|
|
30
|
+
/** aria-label announcing the step, e.g. for the live region. */
|
|
31
|
+
stepAnnouncement: string;
|
|
32
|
+
/** Label of the `showOnce` checkbox. */
|
|
33
|
+
dontShowAgain: string;
|
|
34
|
+
/**
|
|
35
|
+
* Dismiss button of a hint popover (`sitetourkit/hints`). Optional so existing
|
|
36
|
+
* custom label sets keep type-checking; the bundled locales all provide it.
|
|
37
|
+
*/
|
|
38
|
+
hintDismiss?: string;
|
|
39
|
+
}
|
|
40
|
+
interface ShowOnceOptions {
|
|
41
|
+
/** Persistence key, e.g. "tour:onboarding". */
|
|
42
|
+
key: string;
|
|
43
|
+
/** Where to persist: localStorage (default), sessionStorage or a custom adapter. */
|
|
44
|
+
storage?: StorageKind;
|
|
45
|
+
/** Render a "don't show this again" checkbox in the tooltip. */
|
|
46
|
+
checkbox?: boolean;
|
|
47
|
+
/**
|
|
48
|
+
* Show the tour again after this many milliseconds ("remind me in 30 days").
|
|
49
|
+
* Omitted means the opt-out never expires.
|
|
50
|
+
*/
|
|
51
|
+
ttlMs?: number;
|
|
52
|
+
}
|
|
53
|
+
interface ScrollOptions {
|
|
54
|
+
/** Vertical positioning of the target after scrolling. "off" disables scrolling. */
|
|
55
|
+
block: "center" | "nearest" | "off";
|
|
56
|
+
behavior: "smooth" | "auto";
|
|
57
|
+
/** Extra distance in px kept between the target and the viewport edge. */
|
|
58
|
+
padding: number;
|
|
59
|
+
}
|
|
60
|
+
interface OverlayOptions {
|
|
61
|
+
opacity: number;
|
|
62
|
+
color: string;
|
|
63
|
+
/** Gap in px between the target and the spotlight cutout edge. */
|
|
64
|
+
padding: number;
|
|
65
|
+
/** Corner radius of the cutout in px. */
|
|
66
|
+
radius: number;
|
|
67
|
+
clickToExit: boolean;
|
|
68
|
+
/** Duration of the cutout "flow" animation between steps, in ms. */
|
|
69
|
+
transitionMs: number;
|
|
70
|
+
}
|
|
71
|
+
interface ButtonsOptions {
|
|
72
|
+
next: boolean;
|
|
73
|
+
back: boolean;
|
|
74
|
+
skip: boolean;
|
|
75
|
+
/** Turn the Next button into Done on the last step (otherwise Next is disabled). */
|
|
76
|
+
doneOnLast: boolean;
|
|
77
|
+
/** Hide the Back button on the first step instead of rendering it disabled. */
|
|
78
|
+
hideBackOnFirst: boolean;
|
|
79
|
+
/**
|
|
80
|
+
* Hide the Next button on the last step instead of rendering it disabled.
|
|
81
|
+
* Only applies when `doneOnLast` is off (otherwise Done is shown).
|
|
82
|
+
*/
|
|
83
|
+
hideNextOnLast: boolean;
|
|
84
|
+
}
|
|
85
|
+
/**
|
|
86
|
+
* Waiting for an asynchronously mounted target (SPA views, lazy widgets).
|
|
87
|
+
* While the target is missing the step floats in the center; the DOM is
|
|
88
|
+
* watched and the spotlight flows to the target as soon as it appears.
|
|
89
|
+
*/
|
|
90
|
+
interface WaitForTargetOptions {
|
|
91
|
+
/** How long to keep watching for the target, in ms. */
|
|
92
|
+
timeoutMs: number;
|
|
93
|
+
/** After the timeout: keep the floating step or skip to the next one. */
|
|
94
|
+
onTimeout: "float" | "skip";
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* Auto-advance when the user interacts with the highlighted target
|
|
98
|
+
* ("click here to continue"). `true` means `{ event: "click" }`.
|
|
99
|
+
* Requires interaction with the target (`disableInteraction: false`).
|
|
100
|
+
*/
|
|
101
|
+
type AdvanceOn = true | {
|
|
102
|
+
event?: string;
|
|
103
|
+
};
|
|
104
|
+
/** Resolvable reference to a step's target element. */
|
|
105
|
+
type TargetRef = string | Element | (() => Element | null);
|
|
106
|
+
interface StepContext {
|
|
107
|
+
index: number;
|
|
108
|
+
step: Step;
|
|
109
|
+
target: Element | null;
|
|
110
|
+
}
|
|
111
|
+
/**
|
|
112
|
+
* Custom renderer for step content. Receives the content host element;
|
|
113
|
+
* may return a cleanup function invoked when the step changes or the tour ends.
|
|
114
|
+
*/
|
|
115
|
+
type RenderStep = (ctx: StepContext, host: HTMLElement) => void | (() => void);
|
|
116
|
+
interface StepInput {
|
|
117
|
+
/** Highlight target. Omit for a centered, floating step. */
|
|
118
|
+
target?: TargetRef;
|
|
119
|
+
/** Additional elements to spotlight together with `target` (extra cutouts). */
|
|
120
|
+
highlight?: TargetRef[];
|
|
121
|
+
title?: string;
|
|
122
|
+
content: string;
|
|
123
|
+
placement?: Placement;
|
|
124
|
+
disableInteraction?: boolean;
|
|
125
|
+
scroll?: Partial<ScrollOptions>;
|
|
126
|
+
classes?: {
|
|
127
|
+
tooltip?: string;
|
|
128
|
+
};
|
|
129
|
+
/** Overrides `TourOptions.renderStep` for this step. */
|
|
130
|
+
renderStep?: RenderStep;
|
|
131
|
+
/** Overrides `TourOptions.waitForTarget` for this step; `false` disables. */
|
|
132
|
+
waitForTarget?: Partial<WaitForTargetOptions> | false;
|
|
133
|
+
/** Overrides `TourOptions.lockScroll` for this step. */
|
|
134
|
+
lockScroll?: boolean;
|
|
135
|
+
/** Advance to the next step when the target receives this event. */
|
|
136
|
+
advanceOn?: AdvanceOn;
|
|
137
|
+
/** Return `false` to cancel showing this step (navigation is aborted). */
|
|
138
|
+
onBeforeShow?: (ctx: StepContext) => void | boolean | Promise<void | boolean>;
|
|
139
|
+
onShown?: (ctx: StepContext) => void;
|
|
140
|
+
}
|
|
141
|
+
/** Normalized step used internally and exposed via `tour.steps`. */
|
|
142
|
+
interface Step extends StepInput {
|
|
143
|
+
placement: Placement;
|
|
144
|
+
disableInteraction: boolean;
|
|
145
|
+
lockScroll: boolean;
|
|
146
|
+
/** Resolved waiting policy (tour default merged with the step override). */
|
|
147
|
+
waitForTarget: WaitForTargetOptions | false;
|
|
148
|
+
}
|
|
149
|
+
interface TourOptions {
|
|
150
|
+
steps: StepInput[];
|
|
151
|
+
/** Where the tour root is mounted. Defaults to `document.body`. */
|
|
152
|
+
container?: Element;
|
|
153
|
+
/**
|
|
154
|
+
* Scope for resolving string selectors and for scanning `[data-tour]`
|
|
155
|
+
* elements. Pass a `ShadowRoot` (or a subtree element) to tour content
|
|
156
|
+
* inside a web component: `document.querySelector` cannot reach into a
|
|
157
|
+
* shadow tree. Function targets work regardless of this option.
|
|
158
|
+
*/
|
|
159
|
+
root?: Document | ShadowRoot | Element;
|
|
160
|
+
/**
|
|
161
|
+
* Base name of the declarative attributes, `data-tour` by default. Set it
|
|
162
|
+
* when the page already uses `data-tour` for its own purposes — otherwise
|
|
163
|
+
* a `createTour()` without `steps` would build a tour out of that markup.
|
|
164
|
+
* Modifiers follow the base name: `data-tk-step-title`, `-placement`, ...
|
|
165
|
+
*/
|
|
166
|
+
dataAttribute?: string;
|
|
167
|
+
labels: Labels;
|
|
168
|
+
buttons: ButtonsOptions;
|
|
169
|
+
bullets: boolean;
|
|
170
|
+
progress: boolean;
|
|
171
|
+
stepNumbers: boolean;
|
|
172
|
+
placement: Placement;
|
|
173
|
+
placementPrecedence: Side[];
|
|
174
|
+
overlay: OverlayOptions;
|
|
175
|
+
keyboard: boolean;
|
|
176
|
+
/**
|
|
177
|
+
* Exit on Esc. An Esc the host already handled (`event.defaultPrevented`)
|
|
178
|
+
* is ignored, so a dialog opened on top of a step can close without ending
|
|
179
|
+
* the tour. Navigation keys are exempt from that check: apps routinely
|
|
180
|
+
* preventDefault arrows to stop the page from scrolling.
|
|
181
|
+
*/
|
|
182
|
+
exitOnEsc: boolean;
|
|
183
|
+
disableInteraction: boolean;
|
|
184
|
+
/**
|
|
185
|
+
* Mark `<body>` with `tk-tour-active` while the tour is mounted, so host
|
|
186
|
+
* CSS can move its own chrome (toasts, sticky bars) out of the way.
|
|
187
|
+
*/
|
|
188
|
+
hostClasses: boolean;
|
|
189
|
+
/**
|
|
190
|
+
* Freeze page scrolling while the tour runs (opt-in), compensating for the
|
|
191
|
+
* scrollbar so the layout does not jump. Like `modal`, this deliberately
|
|
192
|
+
* mutates the host document element and restores it on exit. Programmatic
|
|
193
|
+
* scrolling to targets keeps working — only the user's own scrolling is
|
|
194
|
+
* blocked. Can be overridden per step.
|
|
195
|
+
*/
|
|
196
|
+
lockScroll: boolean;
|
|
197
|
+
/**
|
|
198
|
+
* Modal mode (opt-in): the tooltip gets `aria-modal="true"` and everything
|
|
199
|
+
* outside the tour root is made `inert` while the tour runs. This is the
|
|
200
|
+
* one deliberate exception (besides the temporary scroll-margin) to the
|
|
201
|
+
* "never mutate the host DOM" rule — attributes are restored on exit.
|
|
202
|
+
* Implies that the highlighted target is not interactive.
|
|
203
|
+
*/
|
|
204
|
+
modal: boolean;
|
|
205
|
+
/**
|
|
206
|
+
* Wait for asynchronously mounted targets (SPA). Steps whose target is
|
|
207
|
+
* missing float in the center while the DOM is watched; the spotlight
|
|
208
|
+
* flows to the target once it appears. `false` disables watching.
|
|
209
|
+
*/
|
|
210
|
+
waitForTarget: WaitForTargetOptions | false;
|
|
211
|
+
scroll: ScrollOptions;
|
|
212
|
+
/**
|
|
213
|
+
* When `true`, step title/content are rendered as HTML.
|
|
214
|
+
* Off by default: content is rendered via `textContent` (XSS-safe).
|
|
215
|
+
*/
|
|
216
|
+
allowHTML: boolean;
|
|
217
|
+
/**
|
|
218
|
+
* Applied to every HTML string before it is inserted, when `allowHTML` is
|
|
219
|
+
* on. Plug in DOMPurify (or an equivalent) to keep untrusted content safe:
|
|
220
|
+
* `sanitize: (html) => DOMPurify.sanitize(html)`. Ignored while
|
|
221
|
+
* `allowHTML` is off, where everything already goes through `textContent`.
|
|
222
|
+
*/
|
|
223
|
+
sanitize?: (html: string) => string;
|
|
224
|
+
/**
|
|
225
|
+
* Show the tour only once per user: `start()` becomes a no-op after the
|
|
226
|
+
* tour has been completed (or opted out via the checkbox).
|
|
227
|
+
*/
|
|
228
|
+
showOnce?: ShowOnceOptions;
|
|
229
|
+
/**
|
|
230
|
+
* Multi-page tours: persists the current step index on every step change,
|
|
231
|
+
* `start()` resumes from the stored index; completing or explicitly exiting
|
|
232
|
+
* the tour clears the key (navigating away does not).
|
|
233
|
+
*/
|
|
234
|
+
persistProgress?: {
|
|
235
|
+
key: string;
|
|
236
|
+
storage?: StorageKind;
|
|
237
|
+
};
|
|
238
|
+
/** Default custom renderer for step content (per-step `renderStep` wins). */
|
|
239
|
+
renderStep?: RenderStep;
|
|
240
|
+
theme?: string;
|
|
241
|
+
classes?: {
|
|
242
|
+
tooltip?: string;
|
|
243
|
+
overlay?: string;
|
|
244
|
+
button?: string;
|
|
245
|
+
};
|
|
246
|
+
zIndex?: number;
|
|
247
|
+
}
|
|
248
|
+
/** User-facing options: everything optional, nested objects partial. */
|
|
249
|
+
type TourOptionsInput = Partial<Omit<TourOptions, "labels" | "buttons" | "overlay" | "scroll" | "waitForTarget">> & {
|
|
250
|
+
labels?: Partial<Labels>;
|
|
251
|
+
buttons?: Partial<ButtonsOptions>;
|
|
252
|
+
overlay?: Partial<OverlayOptions>;
|
|
253
|
+
scroll?: Partial<ScrollOptions>;
|
|
254
|
+
waitForTarget?: Partial<WaitForTargetOptions> | false;
|
|
255
|
+
};
|
|
256
|
+
|
|
257
|
+
export type { Labels as L, Placement as P, StepInput as S, TourOptionsInput as T, TargetRef as a, Side as b, ScrollOptions as c, StorageKind as d };
|