@vielzeug/beacon 0.0.0-stage → 26.10.17

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.
Files changed (69) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +56 -2
  3. package/dist/_dev.cjs +2 -0
  4. package/dist/_dev.cjs.map +1 -0
  5. package/dist/_dev.d.ts +2 -0
  6. package/dist/_dev.d.ts.map +1 -0
  7. package/dist/_dev.js +7 -0
  8. package/dist/_dev.js.map +1 -0
  9. package/dist/_emit.cjs +2 -0
  10. package/dist/_emit.cjs.map +1 -0
  11. package/dist/_emit.d.ts +12 -0
  12. package/dist/_emit.d.ts.map +1 -0
  13. package/dist/_emit.js +30 -0
  14. package/dist/_emit.js.map +1 -0
  15. package/dist/_scroll.cjs +2 -0
  16. package/dist/_scroll.cjs.map +1 -0
  17. package/dist/_scroll.d.ts +14 -0
  18. package/dist/_scroll.d.ts.map +1 -0
  19. package/dist/_scroll.js +17 -0
  20. package/dist/_scroll.js.map +1 -0
  21. package/dist/_storage.cjs +2 -0
  22. package/dist/_storage.cjs.map +1 -0
  23. package/dist/_storage.d.ts +10 -0
  24. package/dist/_storage.d.ts.map +1 -0
  25. package/dist/_storage.js +33 -0
  26. package/dist/_storage.js.map +1 -0
  27. package/dist/_target.cjs +2 -0
  28. package/dist/_target.cjs.map +1 -0
  29. package/dist/_target.d.ts +2 -0
  30. package/dist/_target.d.ts.map +1 -0
  31. package/dist/_target.js +32 -0
  32. package/dist/_target.js.map +1 -0
  33. package/dist/beacon.cjs +2 -0
  34. package/dist/beacon.cjs.map +1 -0
  35. package/dist/beacon.iife.js +2 -0
  36. package/dist/beacon.iife.js.map +1 -0
  37. package/dist/beacon.js +486 -0
  38. package/dist/beacon.js.map +1 -0
  39. package/dist/coachmark.cjs +2 -0
  40. package/dist/coachmark.cjs.map +1 -0
  41. package/dist/coachmark.d.ts +12 -0
  42. package/dist/coachmark.d.ts.map +1 -0
  43. package/dist/coachmark.js +125 -0
  44. package/dist/coachmark.js.map +1 -0
  45. package/dist/errors.cjs +2 -0
  46. package/dist/errors.cjs.map +1 -0
  47. package/dist/errors.d.ts +11 -0
  48. package/dist/errors.d.ts.map +1 -0
  49. package/dist/errors.js +10 -0
  50. package/dist/errors.js.map +1 -0
  51. package/dist/index.cjs +1 -0
  52. package/dist/index.d.ts +6 -0
  53. package/dist/index.d.ts.map +1 -0
  54. package/dist/index.js +5 -0
  55. package/dist/target.cjs +2 -0
  56. package/dist/target.cjs.map +1 -0
  57. package/dist/target.d.ts +15 -0
  58. package/dist/target.d.ts.map +1 -0
  59. package/dist/target.js +36 -0
  60. package/dist/target.js.map +1 -0
  61. package/dist/tour.cjs +2 -0
  62. package/dist/tour.cjs.map +1 -0
  63. package/dist/tour.d.ts +13 -0
  64. package/dist/tour.d.ts.map +1 -0
  65. package/dist/tour.js +239 -0
  66. package/dist/tour.js.map +1 -0
  67. package/dist/types.d.ts +248 -0
  68. package/dist/types.d.ts.map +1 -0
  69. package/package.json +50 -4
package/dist/tour.js ADDED
@@ -0,0 +1,239 @@
1
+ import { createTappers as e } from "./_emit.js";
2
+ import { createMemoryStorage as t, parseProgress as n, storageKey as r } from "./_storage.js";
3
+ import { resolveTarget as i, sameRect as a, targetAvailable as o } from "./target.js";
4
+ import { observeTarget as s, observeTargetLayout as c } from "./_target.js";
5
+ import { BeaconConfigError as l, BeaconDisposedError as u } from "./errors.js";
6
+ import "./_dev.js";
7
+ import { scrollTargetIntoView as d } from "./_scroll.js";
8
+ import { signal as f } from "@vielzeug/ripple";
9
+ //#region src/tour.ts
10
+ var validateConfig = (e) => {
11
+ if (!e.id) throw new l("createTour: \"id\" must be a non-empty string");
12
+ if (!Array.isArray(e.steps) || e.steps.length === 0) throw new l(`createTour: tour "${e.id}" must have at least one step`);
13
+ let t = /* @__PURE__ */ new Set();
14
+ for (let n of e.steps) {
15
+ if (!n.id) throw new l(`createTour: every step of tour "${e.id}" needs a non-empty id`);
16
+ if (t.has(n.id)) throw new l(`createTour: duplicate step id "${n.id}" in tour "${e.id}"`);
17
+ t.add(n.id);
18
+ }
19
+ };
20
+ function createTour(l) {
21
+ validateConfig(l);
22
+ let p = l.version ?? 1, m = l.targetTimeoutMs ?? Infinity, h = l.autoScroll ?? !0, g = l.storage ?? t(), _ = r(l.id), v = new AbortController(), { signal: y } = v, { emit: b, warn: x, tap: S, clear: C } = e(y), w = f("idle"), T = f(!0), E = f({
23
+ placement: l.placement ?? "auto",
24
+ presentation: l.presentation ?? "auto",
25
+ rect: null,
26
+ step: null,
27
+ stepIndex: -1,
28
+ totalSteps: l.steps.length
29
+ }), stopWaiting = null, D = 0, disposedError = () => new u("This tour handle has been disposed."), guard = () => {
30
+ if (y.aborted) throw disposedError();
31
+ }, persist = () => {
32
+ let e = {
33
+ status: w.peek(),
34
+ stepIndex: E.peek().stepIndex,
35
+ version: p
36
+ };
37
+ try {
38
+ let t = g.set(_, e);
39
+ t instanceof Promise && t.catch((e) => x(e));
40
+ } catch (e) {
41
+ x(e);
42
+ }
43
+ }, clearPersisted = () => {
44
+ try {
45
+ let e = g.remove(_);
46
+ e instanceof Promise && e.catch((e) => x(e));
47
+ } catch (e) {
48
+ x(e);
49
+ }
50
+ }, setStatus = (e) => {
51
+ w.peek() !== e && (w.value = e, persist(), b({
52
+ status: e,
53
+ type: "status-change"
54
+ }));
55
+ }, stopTargetWatch = () => {
56
+ stopWaiting?.(), stopWaiting = null;
57
+ }, refreshActiveRect = () => {
58
+ let e = E.peek().step;
59
+ if (!e?.target) return;
60
+ let t = i(e.target);
61
+ a(t, E.peek().rect) || (E.value = {
62
+ ...E.peek(),
63
+ rect: t
64
+ });
65
+ }, watchActiveTarget = (e) => {
66
+ let t = !1, onLayout = () => {
67
+ t || refreshActiveRect();
68
+ };
69
+ window.addEventListener("scroll", onLayout, { passive: !0 }), window.addEventListener("resize", onLayout);
70
+ let n = s(e, onLayout, y), r = c(e, onLayout, y), stop = () => {
71
+ t || (t = !0, window.removeEventListener("scroll", onLayout), window.removeEventListener("resize", onLayout), n?.(), r?.());
72
+ };
73
+ return y.addEventListener("abort", stop, { once: !0 }), stop;
74
+ }, publishStep = (e) => {
75
+ stopTargetWatch();
76
+ let t = l.steps[e] ?? null, n = E.peek().step;
77
+ n && n !== t && b({
78
+ index: E.peek().stepIndex,
79
+ step: n,
80
+ type: "step:complete"
81
+ }), E.value = {
82
+ placement: t?.placement ?? l.placement ?? "auto",
83
+ presentation: t?.presentation ?? l.presentation ?? "auto",
84
+ rect: t?.target ? i(t.target) : null,
85
+ step: t,
86
+ stepIndex: e,
87
+ totalSteps: l.steps.length
88
+ }, t && (b({
89
+ index: e,
90
+ step: t,
91
+ type: "step:start"
92
+ }), h && t.target && d(t.target, { offset: l.scrollOffset }), t.target && (stopWaiting = watchActiveTarget(t.target)));
93
+ }, finishInternal = (e) => {
94
+ stopTargetWatch();
95
+ let t = E.peek().step;
96
+ t && b({
97
+ index: E.peek().stepIndex,
98
+ step: t,
99
+ type: "step:complete"
100
+ }), E.value = {
101
+ ...E.peek(),
102
+ rect: null,
103
+ step: null,
104
+ stepIndex: -1
105
+ }, setStatus("completed"), b({
106
+ reason: e,
107
+ type: "tour:complete"
108
+ });
109
+ }, activateStep = (e) => {
110
+ stopTargetWatch();
111
+ let t = l.steps[e];
112
+ if (!t) return;
113
+ if (!t.target || m === 0 || o(t.target)) {
114
+ publishStep(e);
115
+ return;
116
+ }
117
+ let n = !0, r = null, i = null, a = t.target;
118
+ stopWaiting = () => {
119
+ n = !1, i?.(), i = null, r !== null && (clearTimeout(r), r = null);
120
+ }, i = s(a, () => {
121
+ n && o(a) && publishStep(e);
122
+ }, y), b({
123
+ index: e,
124
+ message: `Waiting for step "${t.id}" to become visible.`,
125
+ step: t,
126
+ type: "target-waiting"
127
+ }), Number.isFinite(m) && (r = setTimeout(() => {
128
+ n && (stopTargetWatch(), b({
129
+ message: `Skipped step "${t.id}": its target did not appear within ${m}ms.`,
130
+ type: "target-missing"
131
+ }), e + 1 < l.steps.length ? activateStep(e + 1) : finishInternal("finish"));
132
+ }, m));
133
+ }, advanceTo = (e) => {
134
+ e < 0 || (e >= l.steps.length ? finishInternal("finish") : (w.peek() !== "active" && setStatus("active"), activateStep(e)));
135
+ }, startInternal = () => {
136
+ guard();
137
+ let e = w.peek();
138
+ if (e === "completed" || e === "dismissed" || e === "active") return;
139
+ let t = Math.max(0, E.peek().stepIndex);
140
+ setStatus("active"), activateStep(t);
141
+ }, O = ++D, applyStored = (e) => {
142
+ if (O !== D || y.aborted) return;
143
+ let t = n(e);
144
+ if (t && t.version >= p) {
145
+ if (t.status === "completed" || t.status === "dismissed") {
146
+ w.value = t.status, T.value = !1;
147
+ return;
148
+ }
149
+ (t.status === "active" || t.status === "paused") && (w.value = "paused", E.value = {
150
+ ...E.peek(),
151
+ stepIndex: Math.min(t.stepIndex, l.steps.length - 1)
152
+ });
153
+ }
154
+ T.value = !0, l.autoStart && queueMicrotask(() => {
155
+ y.aborted || startInternal();
156
+ });
157
+ };
158
+ try {
159
+ let e = g.get(_);
160
+ e instanceof Promise ? e.then(applyStored, (e) => x(e)) : applyStored(e);
161
+ } catch (e) {
162
+ x(e);
163
+ }
164
+ return {
165
+ back() {
166
+ guard(), advanceTo(E.peek().stepIndex - 1);
167
+ },
168
+ current: E,
169
+ dismiss() {
170
+ guard(), w.peek() !== "completed" && w.peek() !== "dismissed" && (stopTargetWatch(), E.value = {
171
+ ...E.peek(),
172
+ rect: null,
173
+ step: null,
174
+ stepIndex: -1
175
+ }, setStatus("dismissed"), b({ type: "tour:dismiss" }));
176
+ },
177
+ disposalSignal: y,
178
+ dispose() {
179
+ y.aborted || (b({ type: "dispose" }), stopTargetWatch(), v.abort(), C());
180
+ },
181
+ get disposed() {
182
+ return y.aborted;
183
+ },
184
+ eligible: T,
185
+ finish() {
186
+ guard(), w.peek() !== "completed" && finishInternal("finish");
187
+ },
188
+ goto(e) {
189
+ guard();
190
+ let t = typeof e == "number" ? e : l.steps.findIndex((t) => t.id === e);
191
+ t < 0 || t >= l.steps.length ? `${String(e)}${l.id}` : advanceTo(t);
192
+ },
193
+ id: l.id,
194
+ next() {
195
+ guard(), advanceTo(E.peek().stepIndex + 1);
196
+ },
197
+ pause() {
198
+ guard(), w.peek() === "active" && (stopTargetWatch(), E.value = {
199
+ ...E.peek(),
200
+ rect: null
201
+ }, setStatus("paused"));
202
+ },
203
+ reset() {
204
+ guard(), stopTargetWatch(), clearPersisted(), E.value = {
205
+ placement: l.placement ?? "auto",
206
+ presentation: l.presentation ?? "auto",
207
+ rect: null,
208
+ step: null,
209
+ stepIndex: -1,
210
+ totalSteps: l.steps.length
211
+ }, w.value = "idle", T.value = !0, b({
212
+ status: "idle",
213
+ type: "status-change"
214
+ });
215
+ },
216
+ skip() {
217
+ guard(), w.peek() !== "completed" && w.peek() !== "dismissed" && (stopTargetWatch(), E.value = {
218
+ ...E.peek(),
219
+ rect: null,
220
+ step: null,
221
+ stepIndex: -1
222
+ }, setStatus("dismissed"), b({
223
+ reason: "skip",
224
+ type: "tour:complete"
225
+ }));
226
+ },
227
+ start: startInternal,
228
+ status: w,
229
+ steps: l.steps,
230
+ tap: S,
231
+ [Symbol.dispose]() {
232
+ this.dispose();
233
+ }
234
+ };
235
+ }
236
+ //#endregion
237
+ export { createTour };
238
+
239
+ //# sourceMappingURL=tour.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tour.js","names":["config","BeaconConfigError","seen","step","version","targetTimeoutMs","autoScroll","storage","createMemoryStorage","key","storageKey","controller","disposal","warnTap","clearTappers","createTappers","status","signal","eligible","current","loadSequence","BeaconDisposedError","record","result","error","next","emit","rect","resolveTarget","sameRect","stopped","stopObserver","observeTarget","target","stopLayout","observeTargetLayout","index","previous","scrollTargetIntoView","targetAvailable","waiting","timer","s","resumeAt","sequence","stored","parseProgress","raw","loaded","candidate"],"sources":["../src/tour.ts"],"sourcesContent":["import { signal } from '@vielzeug/ripple';\nimport { devOnly, warn } from './_dev';\nimport { createTappers } from './_emit';\nimport { scrollTargetIntoView } from './_scroll';\nimport { createMemoryStorage, parseProgress, storageKey } from './_storage';\nimport { observeTarget, observeTargetLayout } from './_target';\nimport { BeaconConfigError, BeaconDisposedError } from './errors';\nimport { resolveTarget, sameRect, targetAvailable } from './target';\nimport type {\n BeaconCurrentStep,\n BeaconProgress,\n BeaconStatus,\n BeaconTarget,\n BeaconTourConfig,\n BeaconTourEvent,\n BeaconTourHandle,\n} from './types';\n\nconst validateConfig = (config: BeaconTourConfig): void => {\n if (!config.id) throw new BeaconConfigError('createTour: \"id\" must be a non-empty string');\n if (!Array.isArray(config.steps) || config.steps.length === 0) {\n throw new BeaconConfigError(`createTour: tour \"${config.id}\" must have at least one step`);\n }\n\n const seen = new Set<string>();\n for (const step of config.steps) {\n if (!step.id) throw new BeaconConfigError(`createTour: every step of tour \"${config.id}\" needs a non-empty id`);\n if (seen.has(step.id)) {\n throw new BeaconConfigError(`createTour: duplicate step id \"${step.id}\" in tour \"${config.id}\"`);\n }\n seen.add(step.id);\n }\n};\n\n/**\n * Creates a guided tour: a sequential, resumable walkthrough over the app's own\n * DOM. The engine owns step order, target waiting, persistence, and events; a\n * presentation layer (refine's tour components or the app's markup) renders\n * `current` wherever it likes.\n *\n * Progress persists under the tour's id. A stored record written under an older\n * `version` makes the tour eligible again, which is how feature announcements\n * re-reach users who finished the original tour.\n */\nexport function createTour(config: BeaconTourConfig): BeaconTourHandle {\n validateConfig(config);\n\n const version = config.version ?? 1;\n const targetTimeoutMs = config.targetTimeoutMs ?? Number.POSITIVE_INFINITY;\n const autoScroll = config.autoScroll ?? true;\n const storage = config.storage ?? createMemoryStorage();\n const key = storageKey(config.id);\n\n const controller = new AbortController();\n const { signal: disposal } = controller;\n const { emit, warn: warnTap, tap, clear: clearTappers } = createTappers<BeaconTourEvent>(disposal);\n\n const status = signal<BeaconStatus>('idle');\n const eligible = signal(true);\n const current = signal<BeaconCurrentStep>({\n placement: config.placement ?? 'auto',\n presentation: config.presentation ?? 'auto',\n rect: null,\n step: null,\n stepIndex: -1,\n totalSteps: config.steps.length,\n });\n\n let stopWaiting: (() => void) | null = null;\n let loadSequence = 0;\n\n const disposedError = (): BeaconDisposedError => new BeaconDisposedError('This tour handle has been disposed.');\n const guard = (): void => {\n if (disposal.aborted) throw disposedError();\n };\n\n const persist = (): void => {\n const record: BeaconProgress = { status: status.peek(), stepIndex: current.peek().stepIndex, version };\n\n try {\n const result = storage.set(key, record) as unknown;\n if (result instanceof Promise) result.catch((error: unknown) => warnTap(error));\n } catch (error) {\n warnTap(error);\n }\n };\n\n const clearPersisted = (): void => {\n try {\n const result = storage.remove(key) as unknown;\n if (result instanceof Promise) result.catch((error: unknown) => warnTap(error));\n } catch (error) {\n warnTap(error);\n }\n };\n\n const setStatus = (next: BeaconStatus): void => {\n if (status.peek() === next) return;\n status.value = next;\n persist();\n emit({ status: next, type: 'status-change' });\n };\n\n const stopTargetWatch = (): void => {\n stopWaiting?.();\n stopWaiting = null;\n };\n\n /** Re-reads the active step's rect; republishes only when it actually moved. */\n const refreshActiveRect = (): void => {\n const step = current.peek().step;\n if (!step?.target) return;\n const rect = resolveTarget(step.target);\n if (sameRect(rect, current.peek().rect)) return;\n current.value = { ...current.peek(), rect };\n };\n\n /**\n * Keeps the active step's rect honest for as long as the step is visible:\n * scroll and resize move the target, the target's own box can resize, and\n * content added elsewhere on the page can push it around without either —\n * all of which refresh the rect. A target that leaves the document\n * (collapsed menu, route change) drops the rect to `null` instead of\n * anchoring the card to a ghost. The card's positioner re-measures on the\n * repaint the rect write triggers, so no extra listener is needed there.\n */\n const watchActiveTarget = (target: BeaconTarget): (() => void) => {\n let stopped = false;\n const onLayout = (): void => {\n if (!stopped) refreshActiveRect();\n };\n\n window.addEventListener('scroll', onLayout, { passive: true });\n window.addEventListener('resize', onLayout);\n const stopObserver = observeTarget(target, onLayout, disposal);\n const stopLayout = observeTargetLayout(target, onLayout, disposal);\n const stop = (): void => {\n if (stopped) return;\n stopped = true;\n window.removeEventListener('scroll', onLayout);\n window.removeEventListener('resize', onLayout);\n stopObserver?.();\n stopLayout?.();\n };\n disposal.addEventListener('abort', stop, { once: true });\n\n return stop;\n };\n\n /** Publishes `index` as the visible step: completes the previous step, emits step:start, scrolls. */\n const publishStep = (index: number): void => {\n stopTargetWatch();\n const step = config.steps[index] ?? null;\n const previous = current.peek().step;\n if (previous && previous !== step) emit({ index: current.peek().stepIndex, step: previous, type: 'step:complete' });\n\n current.value = {\n placement: step?.placement ?? config.placement ?? 'auto',\n presentation: step?.presentation ?? config.presentation ?? 'auto',\n rect: step?.target ? resolveTarget(step.target) : null,\n step,\n stepIndex: index,\n totalSteps: config.steps.length,\n };\n\n if (step) {\n emit({ index, step, type: 'step:start' });\n if (autoScroll && step.target) scrollTargetIntoView(step.target, { offset: config.scrollOffset });\n if (step.target) stopWaiting = watchActiveTarget(step.target);\n }\n };\n\n const finishInternal = (reason: 'finish' | 'skip'): void => {\n stopTargetWatch();\n const step = current.peek().step;\n if (step) emit({ index: current.peek().stepIndex, step, type: 'step:complete' });\n current.value = { ...current.peek(), rect: null, step: null, stepIndex: -1 };\n setStatus('completed');\n emit({ reason, type: 'tour:complete' });\n };\n\n /**\n * Makes `index` the active step, waiting for its target when it is not on\n * screen yet (lazy route, closed dialog) and reporting `target-waiting` so a\n * presentation can say \"continue when you're ready\" instead of looking\n * frozen. A step without a target (intro or outro) and a `targetTimeoutMs`\n * of `0` publish immediately.\n */\n const activateStep = (index: number): void => {\n stopTargetWatch();\n const step = config.steps[index];\n if (!step) return;\n\n if (!step.target || targetTimeoutMs === 0 || targetAvailable(step.target)) {\n publishStep(index);\n return;\n }\n\n let waiting = true;\n let timer: ReturnType<typeof setTimeout> | null = null;\n let stopObserver: (() => void) | null = null;\n const target = step.target;\n stopWaiting = (): void => {\n waiting = false;\n stopObserver?.();\n stopObserver = null;\n if (timer !== null) {\n clearTimeout(timer);\n timer = null;\n }\n };\n\n stopObserver = observeTarget(\n target,\n () => {\n if (waiting && targetAvailable(target)) {\n publishStep(index);\n }\n },\n disposal,\n );\n\n if (!stopObserver) {\n devOnly(() => warn(`step \"${step.id}\" of tour \"${config.id}\" has a static target that is not in the document`));\n }\n\n emit({ index, message: `Waiting for step \"${step.id}\" to become visible.`, step, type: 'target-waiting' });\n\n if (Number.isFinite(targetTimeoutMs)) {\n timer = setTimeout(() => {\n if (!waiting) return;\n stopTargetWatch();\n emit({\n message: `Skipped step \"${step.id}\": its target did not appear within ${targetTimeoutMs}ms.`,\n type: 'target-missing',\n });\n if (index + 1 < config.steps.length) activateStep(index + 1);\n else finishInternal('finish');\n }, targetTimeoutMs);\n }\n };\n\n const advanceTo = (index: number): void => {\n if (index < 0) return;\n if (index >= config.steps.length) {\n finishInternal('finish');\n return;\n }\n if (status.peek() !== 'active') setStatus('active');\n activateStep(index);\n };\n\n const startInternal = (): void => {\n guard();\n const s = status.peek();\n if (s === 'completed' || s === 'dismissed' || s === 'active') return;\n const resumeAt = Math.max(0, current.peek().stepIndex);\n setStatus('active');\n activateStep(resumeAt);\n };\n\n // Boot: load persisted progress, then decide eligibility and optional autoStart.\n const sequence = ++loadSequence;\n const applyStored = (raw: unknown): void => {\n if (sequence !== loadSequence || disposal.aborted) return;\n const stored = parseProgress(raw);\n\n if (stored && stored.version >= version) {\n if (stored.status === 'completed' || stored.status === 'dismissed') {\n status.value = stored.status;\n eligible.value = false;\n return;\n }\n if (stored.status === 'active' || stored.status === 'paused') {\n status.value = 'paused';\n current.value = { ...current.peek(), stepIndex: Math.min(stored.stepIndex, config.steps.length - 1) };\n }\n }\n // Fresh, paused, or superseded by a newer version: eligible.\n eligible.value = true;\n if (config.autoStart) {\n queueMicrotask(() => {\n if (!disposal.aborted) startInternal();\n });\n }\n };\n\n try {\n const loaded = storage.get(key) as unknown;\n if (loaded instanceof Promise) loaded.then(applyStored, (error: unknown) => warnTap(error));\n else applyStored(loaded);\n } catch (error) {\n warnTap(error);\n }\n\n return {\n back(): void {\n guard();\n advanceTo(current.peek().stepIndex - 1);\n },\n current,\n dismiss(): void {\n guard();\n if (status.peek() === 'completed' || status.peek() === 'dismissed') return;\n stopTargetWatch();\n current.value = { ...current.peek(), rect: null, step: null, stepIndex: -1 };\n setStatus('dismissed');\n emit({ type: 'tour:dismiss' });\n },\n disposalSignal: disposal,\n dispose(): void {\n if (disposal.aborted) return;\n emit({ type: 'dispose' });\n stopTargetWatch();\n controller.abort();\n clearTappers();\n },\n get disposed(): boolean {\n return disposal.aborted;\n },\n eligible,\n finish(): void {\n guard();\n if (status.peek() === 'completed') return;\n finishInternal('finish');\n },\n goto(step: number | string): void {\n guard();\n const index = typeof step === 'number' ? step : config.steps.findIndex((candidate) => candidate.id === step);\n if (index < 0 || index >= config.steps.length) {\n warn(`goto: step \"${String(step)}\" is not part of tour \"${config.id}\"`);\n return;\n }\n advanceTo(index);\n },\n id: config.id,\n next(): void {\n guard();\n advanceTo(current.peek().stepIndex + 1);\n },\n pause(): void {\n guard();\n if (status.peek() !== 'active') return;\n stopTargetWatch();\n current.value = { ...current.peek(), rect: null };\n setStatus('paused');\n },\n reset(): void {\n guard();\n stopTargetWatch();\n clearPersisted();\n current.value = {\n placement: config.placement ?? 'auto',\n presentation: config.presentation ?? 'auto',\n rect: null,\n step: null,\n stepIndex: -1,\n totalSteps: config.steps.length,\n };\n status.value = 'idle';\n eligible.value = true;\n emit({ status: 'idle', type: 'status-change' });\n },\n skip(): void {\n guard();\n if (status.peek() === 'completed' || status.peek() === 'dismissed') return;\n stopTargetWatch();\n current.value = { ...current.peek(), rect: null, step: null, stepIndex: -1 };\n setStatus('dismissed');\n emit({ reason: 'skip', type: 'tour:complete' });\n },\n start: startInternal,\n status,\n steps: config.steps,\n tap,\n [Symbol.dispose](): void {\n this.dispose();\n },\n };\n}\n"],"mappings":"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"}
@@ -0,0 +1,248 @@
1
+ import type { Readable } from '@vielzeug/ripple';
2
+ /**
3
+ * Beacon is headless: it decides *what* to show and *where* its anchor is, and
4
+ * never renders. A presentation layer (`@vielzeug/refine`'s `ore-tour`, which
5
+ * consumes a handle through `card.bind(handle)`, or an app's own markup) reads
6
+ * {@link BeaconTourHandle.current} and positions itself with the rect the
7
+ * handle publishes.
8
+ */
9
+ /**
10
+ * A viewport-space rectangle, in CSS pixels relative to the document origin.
11
+ * Matches `@vielzeug/orbit`'s `Rect` shape, so a rect target can anchor a
12
+ * positioner directly through {@link createVirtualReference}.
13
+ */
14
+ export interface BeaconRect {
15
+ readonly height: number;
16
+ readonly width: number;
17
+ readonly x: number;
18
+ readonly y: number;
19
+ }
20
+ /** Resolves a target lazily; returning `null` means "not available yet". */
21
+ export type BeaconTargetResolver = () => Element | BeaconRect | null;
22
+ /**
23
+ * What a step points at. A selector or `Element` anchors to real DOM; a rect (or
24
+ * a resolver returning one) anchors to geometry that has no element, such as a
25
+ * canvas region or a chart datum.
26
+ */
27
+ export type BeaconTarget = BeaconTargetResolver | BeaconRect | Element | string;
28
+ /** How a step should be presented. `auto` lets the presentation layer pick by available space. */
29
+ export type BeaconPresentation = 'auto' | 'bottom-sheet' | 'modal' | 'popover';
30
+ /** Preferred side for an anchored presentation; `auto` asks the positioning layer to choose. */
31
+ export type BeaconPlacement = 'auto' | 'bottom' | 'bottom-end' | 'bottom-start' | 'left' | 'left-end' | 'left-start' | 'right' | 'right-end' | 'right-start' | 'top' | 'top-end' | 'top-start';
32
+ /** One stop in a tour. `id` is stable and persisted, so renaming it resets progress for that step. */
33
+ export interface BeaconStep {
34
+ /** Free-form data the presentation layer can read; Beacon never interprets it. */
35
+ readonly data?: unknown;
36
+ /** Supporting copy. */
37
+ readonly description?: string;
38
+ /** Stable step identity, unique within the tour. */
39
+ readonly id: string;
40
+ /** Overrides the tour-level placement for this step. */
41
+ readonly placement?: BeaconPlacement;
42
+ /** Overrides the tour-level presentation for this step. */
43
+ readonly presentation?: BeaconPresentation;
44
+ /** Omit for an intro/outro step that centers instead of anchoring. */
45
+ readonly target?: BeaconTarget;
46
+ /** Headline copy. */
47
+ readonly title?: string;
48
+ }
49
+ /** Lifecycle of a tour, persisted across visits. */
50
+ export type BeaconStatus = 'active' | 'completed' | 'dismissed' | 'idle' | 'paused';
51
+ /** The persisted record for one tour or coachmark. */
52
+ export interface BeaconProgress {
53
+ readonly status: BeaconStatus;
54
+ /** `-1` before the first step, otherwise the active step index. */
55
+ readonly stepIndex: number;
56
+ /** The {@link BeaconTourConfig.version} the record was written under. */
57
+ readonly version: number;
58
+ }
59
+ /**
60
+ * Minimal storage contract. A plain object or `Map` works in tests; a
61
+ * `@vielzeug/vault` store plugs in with a six-line bridge:
62
+ *
63
+ * ```ts
64
+ * const store = createLocalStorage({ name: 'beacon', schema, codecs });
65
+ * const storage: BeaconStorage = {
66
+ * get: (key) => store.get('progress', key),
67
+ * remove: (key) => store.delete('progress', key),
68
+ * set: (key, value) => store.put('progress', { id: key, ...value }),
69
+ * };
70
+ * ```
71
+ *
72
+ * Values are JSON, so any structured-cloneable record round-trips.
73
+ */
74
+ export interface BeaconStorage {
75
+ get(key: string): Promise<BeaconProgress | null | undefined> | BeaconProgress | null | undefined;
76
+ remove(key: string): Promise<unknown> | unknown;
77
+ set(key: string, value: BeaconProgress): Promise<unknown> | unknown;
78
+ }
79
+ /** Options shared by every {@link createTour} call. */
80
+ export interface BeaconTourConfig {
81
+ /** Scroll each anchored step's target into view when it becomes active. Default `true`. */
82
+ readonly autoScroll?: boolean;
83
+ /** Start the tour on the next microtask when it is eligible. Default `false`. */
84
+ readonly autoStart?: boolean;
85
+ /** Unique identity, used as the storage key. */
86
+ readonly id: string;
87
+ /** Default placement handed to the presentation layer. Default `'auto'`. */
88
+ readonly placement?: BeaconPlacement;
89
+ /** Default presentation handed to the presentation layer. Default `'auto'`. */
90
+ readonly presentation?: BeaconPresentation;
91
+ /** Pixels kept clear at the top of the viewport for a sticky header, read at scroll time. Default `0`. */
92
+ readonly scrollOffset?: number | (() => number);
93
+ /** Every step, in order. Must contain at least one. */
94
+ readonly steps: readonly BeaconStep[];
95
+ /** Storage for progress. Omit to keep progress in memory for this handle only. */
96
+ readonly storage?: BeaconStorage;
97
+ /**
98
+ * How long to wait for a step's target to appear before skipping that step, in
99
+ * ms. Default `Infinity` (wait as long as the user needs — the tour resumes
100
+ * when they navigate to the target). `0` shows the step immediately with a
101
+ * `null` rect instead of waiting.
102
+ */
103
+ readonly targetTimeoutMs?: number;
104
+ /**
105
+ * Bump to re-show a tour users already finished. A stored record under an older
106
+ * version makes the tour eligible again; a record at this version does not.
107
+ */
108
+ readonly version?: number;
109
+ }
110
+ /** Options for {@link createCoachmark}. */
111
+ export interface BeaconCoachmarkConfig {
112
+ /** Show automatically on the next microtask when not yet seen. Default `true`. */
113
+ readonly autoShow?: boolean;
114
+ /** Free-form data for the presentation layer. */
115
+ readonly data?: unknown;
116
+ readonly description?: string;
117
+ /** Unique identity, used as the storage key. */
118
+ readonly id: string;
119
+ readonly placement?: BeaconPlacement;
120
+ readonly presentation?: BeaconPresentation;
121
+ /** Storage for the seen/seen-version record. Omit for memory-only. */
122
+ readonly storage?: BeaconStorage;
123
+ /** Where the hint points. */
124
+ readonly target: BeaconTarget;
125
+ readonly title?: string;
126
+ /** Bump to re-show a coachmark the user already saw. */
127
+ readonly version?: number;
128
+ }
129
+ /**
130
+ * The snapshot a presentation layer renders from. Both handles publish one:
131
+ * a tour's `current` moves through its steps, a coachmark's is its single step
132
+ * while visible and `null` while hidden.
133
+ */
134
+ export interface BeaconCurrentStep {
135
+ readonly placement: BeaconPlacement;
136
+ readonly presentation: BeaconPresentation;
137
+ /**
138
+ * Resolved anchor rect, or `null` for a centered step, an unresolved target,
139
+ * or an anchored step whose target left the document. Beacon keeps the rect
140
+ * fresh on scroll, resize, and target layout changes while a step is active.
141
+ */
142
+ readonly rect: BeaconRect | null;
143
+ /** `null` before the tour starts and after it ends. */
144
+ readonly step: BeaconStep | null;
145
+ readonly stepIndex: number;
146
+ readonly totalSteps: number;
147
+ }
148
+ /** Events every beacon handle can report. */
149
+ export type BeaconBaseEvent = {
150
+ readonly type: 'dispose';
151
+ } | {
152
+ readonly error: unknown;
153
+ readonly message: string;
154
+ readonly type: 'warning';
155
+ };
156
+ /** Notable moments a tour reports through `tap`. */
157
+ export type BeaconTourEvent = {
158
+ readonly index: number;
159
+ readonly step: BeaconStep;
160
+ readonly type: 'step:start';
161
+ } | {
162
+ readonly index: number;
163
+ readonly step: BeaconStep;
164
+ readonly type: 'step:complete';
165
+ } | {
166
+ readonly reason: 'finish' | 'skip';
167
+ readonly type: 'tour:complete';
168
+ } | {
169
+ readonly type: 'tour:dismiss';
170
+ } | {
171
+ readonly status: BeaconStatus;
172
+ readonly type: 'status-change';
173
+ } | {
174
+ readonly message: string;
175
+ readonly type: 'target-missing';
176
+ } | {
177
+ readonly index: number;
178
+ readonly message: string;
179
+ readonly step: BeaconStep;
180
+ readonly type: 'target-waiting';
181
+ } | BeaconBaseEvent;
182
+ /** Notable moments a coachmark reports through `tap`. */
183
+ export type BeaconCoachmarkEvent = {
184
+ readonly type: 'coachmark:show';
185
+ } | {
186
+ readonly type: 'coachmark:dismiss';
187
+ } | {
188
+ readonly type: 'target-waiting';
189
+ } | BeaconBaseEvent;
190
+ /** The running tour returned by {@link createTour}. */
191
+ export interface BeaconTourHandle {
192
+ /** Return to the previous step. No-op on the first step. Throws after dispose. */
193
+ back(): void;
194
+ /** The step to render, kept live. Beacon re-publishes the rect on scroll, resize, and target layout changes while a step is active. */
195
+ readonly current: Readable<BeaconCurrentStep>;
196
+ /** End the tour by closing it (Escape, backdrop). Persisted as dismissed; {@link reset} makes it available again. */
197
+ dismiss(): void;
198
+ readonly disposalSignal: AbortSignal;
199
+ dispose(): void;
200
+ readonly disposed: boolean;
201
+ /** Whether the tour should be offered to this user: never run, dismissed-and-re-eligible, or superseded by a newer version. */
202
+ readonly eligible: Readable<boolean>;
203
+ /** Mark the tour finished and stop showing it. */
204
+ finish(): void;
205
+ /** Jump to a step by id or index. Throws after dispose. */
206
+ goto(step: number | string): void;
207
+ readonly id: string;
208
+ /** Advance to the next step, or finish on the last one. Throws after dispose. */
209
+ next(): void;
210
+ /** Stop showing the tour, keeping progress so {@link start} can resume it. */
211
+ pause(): void;
212
+ /** Discard persisted progress so the tour is eligible again. */
213
+ reset(): void;
214
+ /** End the tour from a "Skip" control. Persisted like {@link dismiss}, reported with reason `'skip'`. */
215
+ skip(): void;
216
+ /** Begin (or resume) the tour. No-op when already completed. Throws after dispose. */
217
+ start(): void;
218
+ readonly status: Readable<BeaconStatus>;
219
+ readonly steps: readonly BeaconStep[];
220
+ tap(handler: (event: BeaconTourEvent) => void, options?: {
221
+ readonly signal?: AbortSignal;
222
+ }): () => void;
223
+ [Symbol.dispose](): void;
224
+ }
225
+ /** The running coachmark returned by {@link createCoachmark}. */
226
+ export interface BeaconCoachmarkHandle {
227
+ /** The hint as a single-step snapshot: `step` is the hint while visible, `null` while hidden. */
228
+ readonly current: Readable<BeaconCurrentStep>;
229
+ /** Hide the hint and record it as seen. */
230
+ dismiss(): void;
231
+ readonly disposalSignal: AbortSignal;
232
+ dispose(): void;
233
+ readonly disposed: boolean;
234
+ /** Whether the coachmark should be offered: never seen, or superseded by a newer version. */
235
+ readonly eligible: Readable<boolean>;
236
+ /** Hide the hint without marking it seen, so it can show again. */
237
+ hide(): void;
238
+ readonly id: string;
239
+ /** Discard the persisted record so the coachmark is eligible again. */
240
+ reset(): void;
241
+ /** Show the hint. No-op once {@link dismiss}ed without a newer version. Throws after dispose. */
242
+ show(): void;
243
+ tap(handler: (event: BeaconCoachmarkEvent) => void, options?: {
244
+ readonly signal?: AbortSignal;
245
+ }): () => void;
246
+ [Symbol.dispose](): void;
247
+ }
248
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,52 @@
1
1
  {
2
2
  "name": "@vielzeug/beacon",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "26.10.17",
4
+ "description": "Guided onboarding and contextual product tours for web applications",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/helmuthdu/vielzeug",
8
+ "directory": "packages/beacon"
9
+ },
10
+ "license": "MIT",
11
+ "type": "module",
12
+ "engines": {
13
+ "node": ">=22"
14
+ },
15
+ "files": [
16
+ "dist"
17
+ ],
18
+ "main": "./dist/index.cjs",
19
+ "module": "./dist/index.js",
20
+ "types": "dist/index.d.ts",
21
+ "exports": {
22
+ ".": {
23
+ "import": "./dist/index.js",
24
+ "require": "./dist/index.cjs",
25
+ "types": "./dist/index.d.ts"
26
+ }
27
+ },
28
+ "sideEffects": false,
29
+ "publishConfig": {
30
+ "access": "public",
31
+ "registry": "https://registry.npmjs.org/"
32
+ },
33
+ "scripts": {
34
+ "build": "vite build && pnpm --silent run build:bundle && pnpm --silent run build:types",
35
+ "build:bundle": "vite build --config vite.bundle.config.ts",
36
+ "build:types": "tsc -p tsconfig.declarations.json",
37
+ "fix": "biome check --write src",
38
+ "lint": "biome ci src",
39
+ "prepublishOnly": "pnpm --silent run build",
40
+ "test": "vitest"
41
+ },
42
+ "dependencies": {
43
+ "@vielzeug/ripple": "26.10.17"
44
+ },
45
+ "devDependencies": {
46
+ "@types/node": "^26.6.5",
47
+ "jsdom": "^30.1.3",
48
+ "typescript": "^6.0.3",
49
+ "vite": "^8.3.4",
50
+ "vitest": "^5.0.5"
51
+ }
52
+ }