@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
@@ -0,0 +1 @@
1
+ {"version":3,"file":"beacon.js","names":["tappers","tapper","event","error","signal","options","handler","KEY_PREFIX","id","STATUSES","value","record","entries","key","box","target","resolved","a","b","lastAvailable","observer","next","onChange","element","message","opts","config","version","autoShow","storage","controller","disposal","warnTap","clearTappers","eligible","step","HIDDEN","current","loadSequence","result","emit","rect","stopObserver","waiting","sequence","stored","raw","loaded","before","behavior","viewportHeight","reserved","documentTop","idealTop","correctedTop","maxScroll","clampedTop","seen","targetTimeoutMs","autoScroll","status","stopped","stopLayout","index","previous","timer","s","resumeAt","candidate"],"sources":["../src/_emit.ts","../src/_storage.ts","../src/target.ts","../src/_target.ts","../src/errors.ts","../src/coachmark.ts","../src/_dev.ts","../src/_scroll.ts","../src/tour.ts"],"sourcesContent":["/** Shared tap() plumbing: zero overhead when idle, handler errors swallowed, auto-detach on abort. */\nexport function createTappers<E extends { readonly type: string }>(signal: AbortSignal) {\n const tappers = new Set<(event: E) => void>();\n\n const emit = (event: E): void => {\n if (tappers.size === 0) return;\n for (const tapper of tappers) {\n try {\n tapper(event);\n } catch {\n // Observability must not affect tour behavior.\n }\n }\n };\n\n const warn = (error: unknown): void => {\n if (tappers.size === 0) return;\n emit({ error, message: error instanceof Error ? error.message : String(error), type: 'warning' } as unknown as E);\n };\n\n const tap = (handler: (event: E) => void, options?: { readonly signal?: AbortSignal }): (() => void) => {\n if (signal.aborted || options?.signal?.aborted) return () => {};\n const detach = (): void => {\n tappers.delete(handler);\n };\n tappers.add(handler);\n signal.addEventListener('abort', detach, { once: true });\n options?.signal?.addEventListener('abort', detach, { once: true });\n\n return detach;\n };\n\n return { clear: () => tappers.clear(), emit, tap, warn };\n}\n","import type { BeaconProgress, BeaconStatus, BeaconStorage } from './types';\n\n/** Prefix keeps beacon records from colliding with an app's other storage keys. */\nconst KEY_PREFIX = '@vielzeug/beacon:';\n\nexport const storageKey = (id: string): string => `${KEY_PREFIX}${id}`;\n\nconst STATUSES = new Set<BeaconStatus>(['active', 'completed', 'dismissed', 'idle', 'paused']);\n\n/**\n * Validates a record read back from storage. Persisted values cross a trust\n * boundary: a stale, hand-edited, or foreign record must not crash a tour.\n */\nexport function parseProgress(value: unknown): BeaconProgress | null {\n if (typeof value !== 'object' || value === null) return null;\n const record = value as Record<string, unknown>;\n if (typeof record.version !== 'number' || !Number.isFinite(record.version)) return null;\n if (typeof record.stepIndex !== 'number' || !Number.isInteger(record.stepIndex) || record.stepIndex < -1) return null;\n if (!STATUSES.has(record.status as BeaconStatus)) return null;\n\n return { status: record.status as BeaconStatus, stepIndex: record.stepIndex, version: record.version };\n}\n\n/** Progress kept for the lifetime of one handle; the fallback when no storage is configured. */\nexport function createMemoryStorage(): BeaconStorage {\n const entries = new Map<string, BeaconProgress>();\n\n return {\n get: (key) => entries.get(key),\n remove: (key) => {\n entries.delete(key);\n },\n set: (key, value) => {\n entries.set(key, value);\n },\n };\n}\n","import type { BeaconRect, BeaconTarget, BeaconTargetResolver } from './types';\n\nconst isElement = (value: unknown): value is Element => typeof Element !== 'undefined' && value instanceof Element;\n\nconst isRect = (value: unknown): value is BeaconRect =>\n typeof value === 'object' &&\n value !== null &&\n typeof (value as BeaconRect).x === 'number' &&\n typeof (value as BeaconRect).y === 'number' &&\n typeof (value as BeaconRect).width === 'number' &&\n typeof (value as BeaconRect).height === 'number';\n\n/** Copies into a plain rect: a DOMRect carries methods and a prototype the contract does not promise. */\nconst normalize = (value: Element | BeaconRect | null): BeaconRect | null => {\n if (value === null) return null;\n if (!isElement(value)) return value;\n const box = value.getBoundingClientRect();\n\n return { height: box.height, width: box.width, x: box.x, y: box.y };\n};\n\n/**\n * Resolves a target to a viewport-space rect, or `null` when it is not available\n * yet. The shape matches `getBoundingClientRect()` and `@vielzeug/orbit`'s\n * `Rect`, so a presentation layer can anchor an orbit positioner with:\n *\n * ```ts\n * const reference = { getBoundingClientRect: () => resolveTarget(step.target) ?? ZERO_RECT };\n * ```\n *\n * Call it on every position update rather than caching the result: a target\n * moves when the page scrolls, and the panel has to follow.\n */\nexport function resolveTarget(target: BeaconTarget): BeaconRect | null {\n if (typeof target === 'string') {\n if (typeof document === 'undefined') return null;\n\n return normalize(document.querySelector(target));\n }\n\n if (typeof target === 'function') {\n const resolved = (target as BeaconTargetResolver)();\n\n return normalize(resolved === null || resolved === undefined ? null : resolved);\n }\n\n return normalize(target);\n}\n\n/** @internal Whether a target currently resolves; decides whether observation is needed. */\nexport function targetAvailable(target: BeaconTarget): boolean {\n return resolveTarget(target) !== null;\n}\n\n/**\n * @internal The live element a target points at, or `null` when it resolves to a\n * bare rect or is not in the document. Layout observation needs the element:\n * a rect has no box to watch, so those targets stay scroll/resize-only.\n */\nexport function targetElement(target: BeaconTarget): Element | null {\n if (typeof target === 'string') {\n return typeof document === 'undefined' ? null : document.querySelector(target);\n }\n\n if (typeof target === 'function') {\n const resolved = (target as BeaconTargetResolver)();\n\n return resolved === null || resolved === undefined || !isElement(resolved) ? null : resolved;\n }\n\n return isElement(target) ? target : null;\n}\n\n/** @internal Static targets never change availability, so there is nothing to observe. */\nexport function isStaticTarget(target: BeaconTarget): boolean {\n return isElement(target) || isRect(target);\n}\n\n/** @internal Value equality for rects, so a layout refresh that changed nothing republishes nothing. */\nexport function sameRect(a: BeaconRect | null, b: BeaconRect | null): boolean {\n if (a === null || b === null) return a === b;\n\n return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;\n}\n","import { isStaticTarget, targetAvailable, targetElement } from './target';\nimport type { BeaconTarget } from './types';\n\n/**\n * @internal Calls `onChange` whenever a target's availability flips: element\n * added, removed, or a resolver's result changing. Selector and resolver targets\n * are polled on DOM mutations; static element and rect targets never change\n * availability, so there is nothing to observe and this returns `null`.\n */\nexport function observeTarget(target: BeaconTarget, onChange: () => void, signal: AbortSignal): (() => void) | null {\n if (isStaticTarget(target)) return null;\n if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') return null;\n\n let lastAvailable = targetAvailable(target);\n const observer = new MutationObserver(() => {\n const next = targetAvailable(target);\n if (next !== lastAvailable) {\n lastAvailable = next;\n onChange();\n }\n });\n\n observer.observe(document.documentElement, { attributes: true, childList: true, subtree: true });\n const stop = (): void => {\n observer.disconnect();\n signal.removeEventListener('abort', stop);\n };\n signal.addEventListener('abort', stop, { once: true });\n\n return stop;\n}\n\n/**\n * @internal Calls `onChange` whenever a target's box moves or resizes without a\n * window scroll or resize: content added above it, a grid reflow, a collapsing\n * menu. Watches the resolved element itself and `document.body`, so both the\n * element's own size changes and sibling/parent growth that pushes it around\n * report. Rect targets have no element to watch and return `null`; they stay\n * scroll/resize-only.\n */\nexport function observeTargetLayout(\n target: BeaconTarget,\n onChange: () => void,\n signal: AbortSignal,\n): (() => void) | null {\n const element = targetElement(target);\n\n if (!element || typeof document === 'undefined' || typeof ResizeObserver === 'undefined') return null;\n\n const observer = new ResizeObserver(onChange);\n\n observer.observe(element);\n // The body watch is the sibling-growth catch: adding a tile below a target\n // does not resize the target, but it resizes the page.\n observer.observe(document.body);\n\n const stop = (): void => {\n observer.disconnect();\n signal.removeEventListener('abort', stop);\n };\n signal.addEventListener('abort', stop, { once: true });\n\n return stop;\n}\n","/** Base class for all beacon errors. Use `instanceof BeaconError` to catch any beacon-originated error. */\nexport class BeaconError extends Error {\n constructor(message: string, opts?: ErrorOptions) {\n super(message, opts);\n this.name = new.target.name;\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n\n/** Thrown when tour or coachmark configuration is invalid, such as an empty `steps` array or duplicate step ids. */\nexport class BeaconConfigError extends BeaconError {}\n\n/** Thrown when a disposed handle is used after {@link BeaconTourHandle.dispose}. */\nexport class BeaconDisposedError extends BeaconError {}\n","import { signal } from '@vielzeug/ripple';\nimport { createTappers } from './_emit';\nimport { createMemoryStorage, parseProgress, storageKey } from './_storage';\nimport { observeTarget, observeTargetLayout } from './_target';\nimport { BeaconConfigError, BeaconDisposedError } from './errors';\nimport { resolveTarget, sameRect } from './target';\nimport type {\n BeaconCoachmarkConfig,\n BeaconCoachmarkEvent,\n BeaconCoachmarkHandle,\n BeaconCurrentStep,\n BeaconProgress,\n BeaconStep,\n} from './types';\n\n/**\n * Creates a coachmark: a single contextual hint anchored to one target, shown\n * the first time a user reaches that feature and dismissed permanently after.\n * The same \"explain this button once\" pattern that makes tours worth keeping\n * after launch week, without sequencing anything.\n *\n * Like tours, coachmarks version: bumping `version` re-shows a hint users\n * already saw, which covers a button whose meaning changed.\n */\nexport function createCoachmark(config: BeaconCoachmarkConfig): BeaconCoachmarkHandle {\n if (!config.id) throw new BeaconConfigError('createCoachmark: \"id\" must be a non-empty string');\n\n const version = config.version ?? 1;\n const autoShow = config.autoShow ?? 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<BeaconCoachmarkEvent>(disposal);\n\n const eligible = signal(true);\n\n const step: BeaconStep = {\n data: config.data,\n description: config.description,\n id: config.id,\n placement: config.placement ?? 'auto',\n presentation: config.presentation ?? 'auto',\n target: config.target,\n title: config.title,\n };\n\n const HIDDEN: BeaconCurrentStep = {\n placement: step.placement ?? 'auto',\n presentation: step.presentation ?? 'auto',\n rect: null,\n step: null,\n stepIndex: 0,\n totalSteps: 0,\n };\n\n const current = signal<BeaconCurrentStep>(HIDDEN);\n\n let stopWaiting: (() => void) | null = null;\n let loadSequence = 0;\n\n const disposedError = (): BeaconDisposedError => new BeaconDisposedError('This coachmark handle has been disposed.');\n const guard = (): void => {\n if (disposal.aborted) throw disposedError();\n };\n\n const persistSeen = (): void => {\n const record: BeaconProgress = { status: 'completed', stepIndex: 0, 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 stopWaitingForTarget = (): void => {\n stopWaiting?.();\n stopWaiting = null;\n };\n\n const showInternal = (): void => {\n guard();\n if (!eligible.peek() || current.peek().step !== null) return;\n\n const publish = (): void => {\n current.value = { ...HIDDEN, rect: resolveTarget(config.target), step };\n emit({ type: 'coachmark:show' });\n watchLayout();\n };\n\n // Keep the rect honest while the hint is up: scroll and resize move the\n // target, the target's box can resize, and page growth can push it around;\n // a target that leaves the document drops the rect to null.\n const watchLayout = (): void => {\n const onLayout = (): void => {\n const rect = resolveTarget(config.target);\n if (sameRect(rect, current.peek().rect)) return;\n current.value = { ...current.peek(), rect };\n };\n\n window.addEventListener('scroll', onLayout, { passive: true });\n window.addEventListener('resize', onLayout);\n const stopObserver = observeTargetLayout(config.target, onLayout, disposal);\n const stop = (): void => {\n window.removeEventListener('scroll', onLayout);\n window.removeEventListener('resize', onLayout);\n stopObserver?.();\n };\n disposal.addEventListener('abort', stop, { once: true });\n stopWaiting = (): void => {\n stop();\n stopWaiting = null;\n };\n };\n\n if (resolveTarget(config.target)) {\n publish();\n return;\n }\n\n // Target not mounted yet: wait for it so the hint appears when the user reaches the feature.\n let waiting = true;\n let stopObserver: (() => void) | null = null;\n stopWaiting = (): void => {\n waiting = false;\n stopObserver?.();\n stopObserver = null;\n };\n stopObserver = observeTarget(\n config.target,\n () => {\n if (!waiting || !eligible.peek()) return;\n stopWaitingForTarget();\n publish();\n },\n disposal,\n );\n emit({ type: 'target-waiting' });\n };\n\n // Boot: read the seen-record, then optionally auto-show.\n const sequence = ++loadSequence;\n const applyStored = (raw: unknown): void => {\n if (sequence !== loadSequence || disposal.aborted) return;\n const stored = parseProgress(raw);\n eligible.value = !(stored && stored.version >= version && stored.status === 'completed');\n if (eligible.peek() && autoShow) {\n queueMicrotask(() => {\n if (!disposal.aborted) showInternal();\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 current,\n dismiss(): void {\n guard();\n stopWaitingForTarget();\n current.value = HIDDEN;\n eligible.value = false;\n persistSeen();\n emit({ type: 'coachmark:dismiss' });\n },\n disposalSignal: disposal,\n dispose(): void {\n if (disposal.aborted) return;\n emit({ type: 'dispose' });\n stopWaitingForTarget();\n controller.abort();\n clearTappers();\n },\n get disposed(): boolean {\n return disposal.aborted;\n },\n eligible,\n hide(): void {\n guard();\n stopWaitingForTarget();\n current.value = HIDDEN;\n },\n id: config.id,\n reset(): void {\n guard();\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 eligible.value = true;\n },\n show: showInternal,\n tap,\n [Symbol.dispose](): void {\n this.dispose();\n },\n };\n}\n","const isDev = !(globalThis as { __BEACON_PROD__?: boolean }).__BEACON_PROD__;\n\n/** @internal @security Messages may include user-supplied data. */\nexport function warn(msg: string): void {\n if (isDev) console.warn(`[@vielzeug/beacon] ${msg}`);\n}\n\n/** @internal Multi-step development-only logic; skipped entirely in production builds. */\nexport function devOnly(fn: () => void): void {\n if (isDev) fn();\n}\n","import { resolveTarget } from './target';\nimport type { BeaconTarget } from './types';\n\n/** Options for {@link scrollTargetIntoView}. */\nexport interface ScrollIntoViewOptions {\n /** Scroll behavior. Default `'smooth'` when the user has not requested reduced motion, else `'auto'`. */\n readonly behavior?: 'auto' | 'instant' | 'smooth';\n /** Pixels reserved at the top of the viewport for sticky headers. Number or a function read at scroll time. Default `0`. */\n readonly offset?: number | (() => number);\n}\n\nconst prefersReducedMotion = (): boolean =>\n typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;\n\n/**\n * Centers a target in the viewport, keeping it clear of a sticky header.\n * Returns whether the target was found. No-op without a DOM.\n */\nexport function scrollTargetIntoView(target: BeaconTarget, options: ScrollIntoViewOptions = {}): boolean {\n if (typeof window === 'undefined' || typeof document === 'undefined') return false;\n\n const before = resolveTarget(target);\n if (!before) return false;\n\n const behavior = options.behavior ?? (prefersReducedMotion() ? 'auto' : 'smooth');\n const viewportHeight = window.innerHeight || document.documentElement.clientHeight;\n const reserved = typeof options.offset === 'function' ? options.offset() : (options.offset ?? 0);\n // The rect is viewport-space; scrolling answers in document space.\n const documentTop = before.y + (globalThis.scrollY ?? 0);\n\n // Center first: the cheapest correct default for tall and short targets alike.\n const idealTop = documentTop - (viewportHeight - before.height) / 2;\n // A sticky header covers the top `reserved` px: when the target's top edge\n // would land inside that band, sit it just below the reserved area instead.\n // One scrollTo: a second smooth scroll would interrupt the first mid-flight.\n const correctedTop = reserved > 0 && documentTop - idealTop < reserved ? documentTop - reserved : idealTop;\n const maxScroll = Math.max(0, document.documentElement.scrollHeight - viewportHeight);\n const clampedTop = Math.min(Math.max(0, correctedTop), maxScroll);\n\n window.scrollTo({ behavior, top: clampedTop });\n\n return true;\n}\n","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,2 @@
1
+ const e=require("./_emit.cjs"),t=require("./_storage.cjs"),n=require("./target.cjs"),r=require("./_target.cjs"),i=require("./errors.cjs");let a=require("@vielzeug/ripple");function createCoachmark(o){if(!o.id)throw new i.BeaconConfigError(`createCoachmark: "id" must be a non-empty string`);let s=o.version??1,c=o.autoShow??!0,l=o.storage??t.createMemoryStorage(),u=t.storageKey(o.id),d=new AbortController,{signal:f}=d,{emit:p,warn:m,tap:h,clear:g}=e.createTappers(f),_=(0,a.signal)(!0),v={data:o.data,description:o.description,id:o.id,placement:o.placement??`auto`,presentation:o.presentation??`auto`,target:o.target,title:o.title},y={placement:v.placement??`auto`,presentation:v.presentation??`auto`,rect:null,step:null,stepIndex:0,totalSteps:0},b=(0,a.signal)(y),stopWaiting=null,x=0,disposedError=()=>new i.BeaconDisposedError(`This coachmark handle has been disposed.`),guard=()=>{if(f.aborted)throw disposedError()},persistSeen=()=>{let e={status:`completed`,stepIndex:0,version:s};try{let t=l.set(u,e);t instanceof Promise&&t.catch(e=>m(e))}catch(e){m(e)}},stopWaitingForTarget=()=>{stopWaiting?.(),stopWaiting=null},showInternal=()=>{if(guard(),!_.peek()||b.peek().step!==null)return;let publish=()=>{b.value={...y,rect:n.resolveTarget(o.target),step:v},p({type:`coachmark:show`}),watchLayout()},watchLayout=()=>{let onLayout=()=>{let e=n.resolveTarget(o.target);n.sameRect(e,b.peek().rect)||(b.value={...b.peek(),rect:e})};window.addEventListener(`scroll`,onLayout,{passive:!0}),window.addEventListener(`resize`,onLayout);let e=r.observeTargetLayout(o.target,onLayout,f),stop=()=>{window.removeEventListener(`scroll`,onLayout),window.removeEventListener(`resize`,onLayout),e?.()};f.addEventListener(`abort`,stop,{once:!0}),stopWaiting=()=>{stop(),stopWaiting=null}};if(n.resolveTarget(o.target)){publish();return}let e=!0,t=null;stopWaiting=()=>{e=!1,t?.(),t=null},t=r.observeTarget(o.target,()=>{e&&_.peek()&&(stopWaitingForTarget(),publish())},f),p({type:`target-waiting`})},S=++x,applyStored=e=>{if(S!==x||f.aborted)return;let n=t.parseProgress(e);_.value=!(n&&n.version>=s&&n.status===`completed`),_.peek()&&c&&queueMicrotask(()=>{f.aborted||showInternal()})};try{let e=l.get(u);e instanceof Promise?e.then(applyStored,e=>m(e)):applyStored(e)}catch(e){m(e)}return{current:b,dismiss(){guard(),stopWaitingForTarget(),b.value=y,_.value=!1,persistSeen(),p({type:`coachmark:dismiss`})},disposalSignal:f,dispose(){f.aborted||(p({type:`dispose`}),stopWaitingForTarget(),d.abort(),g())},get disposed(){return f.aborted},eligible:_,hide(){guard(),stopWaitingForTarget(),b.value=y},id:o.id,reset(){guard();try{let e=l.remove(u);e instanceof Promise&&e.catch(e=>m(e))}catch(e){m(e)}_.value=!0},show:showInternal,tap:h,[Symbol.dispose](){this.dispose()}}}exports.createCoachmark=createCoachmark;
2
+ //# sourceMappingURL=coachmark.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"coachmark.cjs","names":["BeaconConfigError","createMemoryStorage","storageKey","createTappers","signal","BeaconDisposedError","resolveTarget","sameRect","observeTargetLayout","observeTarget","parseProgress","require__emit","require__storage","require_target","require__target","require_errors","_vielzeug_ripple","config","version","autoShow","storage","key","controller","disposal","warnTap","clearTappers","eligible","step","HIDDEN","current","loadSequence","record","result","error","emit","rect","stopObserver","waiting","sequence","stored","raw","loaded"],"sources":["../src/coachmark.ts"],"sourcesContent":["import { signal } from '@vielzeug/ripple';\nimport { createTappers } from './_emit';\nimport { createMemoryStorage, parseProgress, storageKey } from './_storage';\nimport { observeTarget, observeTargetLayout } from './_target';\nimport { BeaconConfigError, BeaconDisposedError } from './errors';\nimport { resolveTarget, sameRect } from './target';\nimport type {\n BeaconCoachmarkConfig,\n BeaconCoachmarkEvent,\n BeaconCoachmarkHandle,\n BeaconCurrentStep,\n BeaconProgress,\n BeaconStep,\n} from './types';\n\n/**\n * Creates a coachmark: a single contextual hint anchored to one target, shown\n * the first time a user reaches that feature and dismissed permanently after.\n * The same \"explain this button once\" pattern that makes tours worth keeping\n * after launch week, without sequencing anything.\n *\n * Like tours, coachmarks version: bumping `version` re-shows a hint users\n * already saw, which covers a button whose meaning changed.\n */\nexport function createCoachmark(config: BeaconCoachmarkConfig): BeaconCoachmarkHandle {\n if (!config.id) throw new BeaconConfigError('createCoachmark: \"id\" must be a non-empty string');\n\n const version = config.version ?? 1;\n const autoShow = config.autoShow ?? 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<BeaconCoachmarkEvent>(disposal);\n\n const eligible = signal(true);\n\n const step: BeaconStep = {\n data: config.data,\n description: config.description,\n id: config.id,\n placement: config.placement ?? 'auto',\n presentation: config.presentation ?? 'auto',\n target: config.target,\n title: config.title,\n };\n\n const HIDDEN: BeaconCurrentStep = {\n placement: step.placement ?? 'auto',\n presentation: step.presentation ?? 'auto',\n rect: null,\n step: null,\n stepIndex: 0,\n totalSteps: 0,\n };\n\n const current = signal<BeaconCurrentStep>(HIDDEN);\n\n let stopWaiting: (() => void) | null = null;\n let loadSequence = 0;\n\n const disposedError = (): BeaconDisposedError => new BeaconDisposedError('This coachmark handle has been disposed.');\n const guard = (): void => {\n if (disposal.aborted) throw disposedError();\n };\n\n const persistSeen = (): void => {\n const record: BeaconProgress = { status: 'completed', stepIndex: 0, 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 stopWaitingForTarget = (): void => {\n stopWaiting?.();\n stopWaiting = null;\n };\n\n const showInternal = (): void => {\n guard();\n if (!eligible.peek() || current.peek().step !== null) return;\n\n const publish = (): void => {\n current.value = { ...HIDDEN, rect: resolveTarget(config.target), step };\n emit({ type: 'coachmark:show' });\n watchLayout();\n };\n\n // Keep the rect honest while the hint is up: scroll and resize move the\n // target, the target's box can resize, and page growth can push it around;\n // a target that leaves the document drops the rect to null.\n const watchLayout = (): void => {\n const onLayout = (): void => {\n const rect = resolveTarget(config.target);\n if (sameRect(rect, current.peek().rect)) return;\n current.value = { ...current.peek(), rect };\n };\n\n window.addEventListener('scroll', onLayout, { passive: true });\n window.addEventListener('resize', onLayout);\n const stopObserver = observeTargetLayout(config.target, onLayout, disposal);\n const stop = (): void => {\n window.removeEventListener('scroll', onLayout);\n window.removeEventListener('resize', onLayout);\n stopObserver?.();\n };\n disposal.addEventListener('abort', stop, { once: true });\n stopWaiting = (): void => {\n stop();\n stopWaiting = null;\n };\n };\n\n if (resolveTarget(config.target)) {\n publish();\n return;\n }\n\n // Target not mounted yet: wait for it so the hint appears when the user reaches the feature.\n let waiting = true;\n let stopObserver: (() => void) | null = null;\n stopWaiting = (): void => {\n waiting = false;\n stopObserver?.();\n stopObserver = null;\n };\n stopObserver = observeTarget(\n config.target,\n () => {\n if (!waiting || !eligible.peek()) return;\n stopWaitingForTarget();\n publish();\n },\n disposal,\n );\n emit({ type: 'target-waiting' });\n };\n\n // Boot: read the seen-record, then optionally auto-show.\n const sequence = ++loadSequence;\n const applyStored = (raw: unknown): void => {\n if (sequence !== loadSequence || disposal.aborted) return;\n const stored = parseProgress(raw);\n eligible.value = !(stored && stored.version >= version && stored.status === 'completed');\n if (eligible.peek() && autoShow) {\n queueMicrotask(() => {\n if (!disposal.aborted) showInternal();\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 current,\n dismiss(): void {\n guard();\n stopWaitingForTarget();\n current.value = HIDDEN;\n eligible.value = false;\n persistSeen();\n emit({ type: 'coachmark:dismiss' });\n },\n disposalSignal: disposal,\n dispose(): void {\n if (disposal.aborted) return;\n emit({ type: 'dispose' });\n stopWaitingForTarget();\n controller.abort();\n clearTappers();\n },\n get disposed(): boolean {\n return disposal.aborted;\n },\n eligible,\n hide(): void {\n guard();\n stopWaitingForTarget();\n current.value = HIDDEN;\n },\n id: config.id,\n reset(): void {\n guard();\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 eligible.value = true;\n },\n show: showInternal,\n tap,\n [Symbol.dispose](): void {\n this.dispose();\n },\n };\n}\n"],"mappings":"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"}
@@ -0,0 +1,12 @@
1
+ import type { BeaconCoachmarkConfig, BeaconCoachmarkHandle } from './types';
2
+ /**
3
+ * Creates a coachmark: a single contextual hint anchored to one target, shown
4
+ * the first time a user reaches that feature and dismissed permanently after.
5
+ * The same "explain this button once" pattern that makes tours worth keeping
6
+ * after launch week, without sequencing anything.
7
+ *
8
+ * Like tours, coachmarks version: bumping `version` re-shows a hint users
9
+ * already saw, which covers a button whose meaning changed.
10
+ */
11
+ export declare function createCoachmark(config: BeaconCoachmarkConfig): BeaconCoachmarkHandle;
12
+ //# sourceMappingURL=coachmark.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"coachmark.d.ts","sourceRoot":"","sources":["../src/coachmark.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EACV,qBAAqB,EAErB,qBAAqB,EAItB,MAAM,SAAS,CAAC;AAEjB;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,qBAAqB,GAAG,qBAAqB,CAwLpF"}
@@ -0,0 +1,125 @@
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 } from "./target.js";
4
+ import { observeTarget as o, observeTargetLayout as s } from "./_target.js";
5
+ import { BeaconConfigError as c, BeaconDisposedError as l } from "./errors.js";
6
+ import { signal as u } from "@vielzeug/ripple";
7
+ //#region src/coachmark.ts
8
+ function createCoachmark(d) {
9
+ if (!d.id) throw new c("createCoachmark: \"id\" must be a non-empty string");
10
+ let f = d.version ?? 1, p = d.autoShow ?? !0, m = d.storage ?? t(), h = r(d.id), g = new AbortController(), { signal: _ } = g, { emit: v, warn: y, tap: b, clear: x } = e(_), S = u(!0), C = {
11
+ data: d.data,
12
+ description: d.description,
13
+ id: d.id,
14
+ placement: d.placement ?? "auto",
15
+ presentation: d.presentation ?? "auto",
16
+ target: d.target,
17
+ title: d.title
18
+ }, w = {
19
+ placement: C.placement ?? "auto",
20
+ presentation: C.presentation ?? "auto",
21
+ rect: null,
22
+ step: null,
23
+ stepIndex: 0,
24
+ totalSteps: 0
25
+ }, T = u(w), stopWaiting = null, E = 0, disposedError = () => new l("This coachmark handle has been disposed."), guard = () => {
26
+ if (_.aborted) throw disposedError();
27
+ }, persistSeen = () => {
28
+ let e = {
29
+ status: "completed",
30
+ stepIndex: 0,
31
+ version: f
32
+ };
33
+ try {
34
+ let t = m.set(h, e);
35
+ t instanceof Promise && t.catch((e) => y(e));
36
+ } catch (e) {
37
+ y(e);
38
+ }
39
+ }, stopWaitingForTarget = () => {
40
+ stopWaiting?.(), stopWaiting = null;
41
+ }, showInternal = () => {
42
+ if (guard(), !S.peek() || T.peek().step !== null) return;
43
+ let publish = () => {
44
+ T.value = {
45
+ ...w,
46
+ rect: i(d.target),
47
+ step: C
48
+ }, v({ type: "coachmark:show" }), watchLayout();
49
+ }, watchLayout = () => {
50
+ let onLayout = () => {
51
+ let e = i(d.target);
52
+ a(e, T.peek().rect) || (T.value = {
53
+ ...T.peek(),
54
+ rect: e
55
+ });
56
+ };
57
+ window.addEventListener("scroll", onLayout, { passive: !0 }), window.addEventListener("resize", onLayout);
58
+ let e = s(d.target, onLayout, _), stop = () => {
59
+ window.removeEventListener("scroll", onLayout), window.removeEventListener("resize", onLayout), e?.();
60
+ };
61
+ _.addEventListener("abort", stop, { once: !0 }), stopWaiting = () => {
62
+ stop(), stopWaiting = null;
63
+ };
64
+ };
65
+ if (i(d.target)) {
66
+ publish();
67
+ return;
68
+ }
69
+ let e = !0, t = null;
70
+ stopWaiting = () => {
71
+ e = !1, t?.(), t = null;
72
+ }, t = o(d.target, () => {
73
+ e && S.peek() && (stopWaitingForTarget(), publish());
74
+ }, _), v({ type: "target-waiting" });
75
+ }, D = ++E, applyStored = (e) => {
76
+ if (D !== E || _.aborted) return;
77
+ let t = n(e);
78
+ S.value = !(t && t.version >= f && t.status === "completed"), S.peek() && p && queueMicrotask(() => {
79
+ _.aborted || showInternal();
80
+ });
81
+ };
82
+ try {
83
+ let e = m.get(h);
84
+ e instanceof Promise ? e.then(applyStored, (e) => y(e)) : applyStored(e);
85
+ } catch (e) {
86
+ y(e);
87
+ }
88
+ return {
89
+ current: T,
90
+ dismiss() {
91
+ guard(), stopWaitingForTarget(), T.value = w, S.value = !1, persistSeen(), v({ type: "coachmark:dismiss" });
92
+ },
93
+ disposalSignal: _,
94
+ dispose() {
95
+ _.aborted || (v({ type: "dispose" }), stopWaitingForTarget(), g.abort(), x());
96
+ },
97
+ get disposed() {
98
+ return _.aborted;
99
+ },
100
+ eligible: S,
101
+ hide() {
102
+ guard(), stopWaitingForTarget(), T.value = w;
103
+ },
104
+ id: d.id,
105
+ reset() {
106
+ guard();
107
+ try {
108
+ let e = m.remove(h);
109
+ e instanceof Promise && e.catch((e) => y(e));
110
+ } catch (e) {
111
+ y(e);
112
+ }
113
+ S.value = !0;
114
+ },
115
+ show: showInternal,
116
+ tap: b,
117
+ [Symbol.dispose]() {
118
+ this.dispose();
119
+ }
120
+ };
121
+ }
122
+ //#endregion
123
+ export { createCoachmark };
124
+
125
+ //# sourceMappingURL=coachmark.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"coachmark.js","names":["config","BeaconConfigError","version","autoShow","storage","createMemoryStorage","key","storageKey","controller","disposal","warnTap","clearTappers","createTappers","eligible","signal","step","HIDDEN","current","loadSequence","BeaconDisposedError","record","result","error","resolveTarget","emit","rect","sameRect","stopObserver","observeTargetLayout","waiting","observeTarget","sequence","stored","parseProgress","raw","loaded"],"sources":["../src/coachmark.ts"],"sourcesContent":["import { signal } from '@vielzeug/ripple';\nimport { createTappers } from './_emit';\nimport { createMemoryStorage, parseProgress, storageKey } from './_storage';\nimport { observeTarget, observeTargetLayout } from './_target';\nimport { BeaconConfigError, BeaconDisposedError } from './errors';\nimport { resolveTarget, sameRect } from './target';\nimport type {\n BeaconCoachmarkConfig,\n BeaconCoachmarkEvent,\n BeaconCoachmarkHandle,\n BeaconCurrentStep,\n BeaconProgress,\n BeaconStep,\n} from './types';\n\n/**\n * Creates a coachmark: a single contextual hint anchored to one target, shown\n * the first time a user reaches that feature and dismissed permanently after.\n * The same \"explain this button once\" pattern that makes tours worth keeping\n * after launch week, without sequencing anything.\n *\n * Like tours, coachmarks version: bumping `version` re-shows a hint users\n * already saw, which covers a button whose meaning changed.\n */\nexport function createCoachmark(config: BeaconCoachmarkConfig): BeaconCoachmarkHandle {\n if (!config.id) throw new BeaconConfigError('createCoachmark: \"id\" must be a non-empty string');\n\n const version = config.version ?? 1;\n const autoShow = config.autoShow ?? 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<BeaconCoachmarkEvent>(disposal);\n\n const eligible = signal(true);\n\n const step: BeaconStep = {\n data: config.data,\n description: config.description,\n id: config.id,\n placement: config.placement ?? 'auto',\n presentation: config.presentation ?? 'auto',\n target: config.target,\n title: config.title,\n };\n\n const HIDDEN: BeaconCurrentStep = {\n placement: step.placement ?? 'auto',\n presentation: step.presentation ?? 'auto',\n rect: null,\n step: null,\n stepIndex: 0,\n totalSteps: 0,\n };\n\n const current = signal<BeaconCurrentStep>(HIDDEN);\n\n let stopWaiting: (() => void) | null = null;\n let loadSequence = 0;\n\n const disposedError = (): BeaconDisposedError => new BeaconDisposedError('This coachmark handle has been disposed.');\n const guard = (): void => {\n if (disposal.aborted) throw disposedError();\n };\n\n const persistSeen = (): void => {\n const record: BeaconProgress = { status: 'completed', stepIndex: 0, 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 stopWaitingForTarget = (): void => {\n stopWaiting?.();\n stopWaiting = null;\n };\n\n const showInternal = (): void => {\n guard();\n if (!eligible.peek() || current.peek().step !== null) return;\n\n const publish = (): void => {\n current.value = { ...HIDDEN, rect: resolveTarget(config.target), step };\n emit({ type: 'coachmark:show' });\n watchLayout();\n };\n\n // Keep the rect honest while the hint is up: scroll and resize move the\n // target, the target's box can resize, and page growth can push it around;\n // a target that leaves the document drops the rect to null.\n const watchLayout = (): void => {\n const onLayout = (): void => {\n const rect = resolveTarget(config.target);\n if (sameRect(rect, current.peek().rect)) return;\n current.value = { ...current.peek(), rect };\n };\n\n window.addEventListener('scroll', onLayout, { passive: true });\n window.addEventListener('resize', onLayout);\n const stopObserver = observeTargetLayout(config.target, onLayout, disposal);\n const stop = (): void => {\n window.removeEventListener('scroll', onLayout);\n window.removeEventListener('resize', onLayout);\n stopObserver?.();\n };\n disposal.addEventListener('abort', stop, { once: true });\n stopWaiting = (): void => {\n stop();\n stopWaiting = null;\n };\n };\n\n if (resolveTarget(config.target)) {\n publish();\n return;\n }\n\n // Target not mounted yet: wait for it so the hint appears when the user reaches the feature.\n let waiting = true;\n let stopObserver: (() => void) | null = null;\n stopWaiting = (): void => {\n waiting = false;\n stopObserver?.();\n stopObserver = null;\n };\n stopObserver = observeTarget(\n config.target,\n () => {\n if (!waiting || !eligible.peek()) return;\n stopWaitingForTarget();\n publish();\n },\n disposal,\n );\n emit({ type: 'target-waiting' });\n };\n\n // Boot: read the seen-record, then optionally auto-show.\n const sequence = ++loadSequence;\n const applyStored = (raw: unknown): void => {\n if (sequence !== loadSequence || disposal.aborted) return;\n const stored = parseProgress(raw);\n eligible.value = !(stored && stored.version >= version && stored.status === 'completed');\n if (eligible.peek() && autoShow) {\n queueMicrotask(() => {\n if (!disposal.aborted) showInternal();\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 current,\n dismiss(): void {\n guard();\n stopWaitingForTarget();\n current.value = HIDDEN;\n eligible.value = false;\n persistSeen();\n emit({ type: 'coachmark:dismiss' });\n },\n disposalSignal: disposal,\n dispose(): void {\n if (disposal.aborted) return;\n emit({ type: 'dispose' });\n stopWaitingForTarget();\n controller.abort();\n clearTappers();\n },\n get disposed(): boolean {\n return disposal.aborted;\n },\n eligible,\n hide(): void {\n guard();\n stopWaitingForTarget();\n current.value = HIDDEN;\n },\n id: config.id,\n reset(): void {\n guard();\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 eligible.value = true;\n },\n show: showInternal,\n tap,\n [Symbol.dispose](): void {\n this.dispose();\n },\n };\n}\n"],"mappings":"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"}
@@ -0,0 +1,2 @@
1
+ var BeaconError=class extends Error{constructor(e,t){super(e,t),this.name=new.target.name,Object.setPrototypeOf(this,new.target.prototype)}},BeaconConfigError=class extends BeaconError{},BeaconDisposedError=class extends BeaconError{};exports.BeaconConfigError=BeaconConfigError,exports.BeaconDisposedError=BeaconDisposedError,exports.BeaconError=BeaconError;
2
+ //# sourceMappingURL=errors.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.cjs","names":["message","opts"],"sources":["../src/errors.ts"],"sourcesContent":["/** Base class for all beacon errors. Use `instanceof BeaconError` to catch any beacon-originated error. */\nexport class BeaconError extends Error {\n constructor(message: string, opts?: ErrorOptions) {\n super(message, opts);\n this.name = new.target.name;\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n\n/** Thrown when tour or coachmark configuration is invalid, such as an empty `steps` array or duplicate step ids. */\nexport class BeaconConfigError extends BeaconError {}\n\n/** Thrown when a disposed handle is used after {@link BeaconTourHandle.dispose}. */\nexport class BeaconDisposedError extends BeaconError {}\n"],"mappings":"AACA,IAAa,YAAb,cAAiC,KAAM,CACrC,YAAY,EAAiB,EAAqB,CAChD,MAAMA,EAASC,CAAI,EACnB,KAAK,KAAO,WAAW,KACvB,OAAO,eAAe,KAAM,WAAW,SAAS,CAClD,CACF,EAGa,kBAAb,cAAuC,WAAY,CAAC,EAGvC,oBAAb,cAAyC,WAAY,CAAC,E"}
@@ -0,0 +1,11 @@
1
+ /** Base class for all beacon errors. Use `instanceof BeaconError` to catch any beacon-originated error. */
2
+ export declare class BeaconError extends Error {
3
+ constructor(message: string, opts?: ErrorOptions);
4
+ }
5
+ /** Thrown when tour or coachmark configuration is invalid, such as an empty `steps` array or duplicate step ids. */
6
+ export declare class BeaconConfigError extends BeaconError {
7
+ }
8
+ /** Thrown when a disposed handle is used after {@link BeaconTourHandle.dispose}. */
9
+ export declare class BeaconDisposedError extends BeaconError {
10
+ }
11
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,2GAA2G;AAC3G,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY;CAKjD;AAED,oHAAoH;AACpH,qBAAa,iBAAkB,SAAQ,WAAW;CAAG;AAErD,oFAAoF;AACpF,qBAAa,mBAAoB,SAAQ,WAAW;CAAG"}
package/dist/errors.js ADDED
@@ -0,0 +1,10 @@
1
+ //#region src/errors.ts
2
+ var BeaconError = class extends Error {
3
+ constructor(e, t) {
4
+ super(e, t), this.name = new.target.name, Object.setPrototypeOf(this, new.target.prototype);
5
+ }
6
+ }, BeaconConfigError = class extends BeaconError {}, BeaconDisposedError = class extends BeaconError {};
7
+ //#endregion
8
+ export { BeaconConfigError, BeaconDisposedError, BeaconError };
9
+
10
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","names":["message","opts"],"sources":["../src/errors.ts"],"sourcesContent":["/** Base class for all beacon errors. Use `instanceof BeaconError` to catch any beacon-originated error. */\nexport class BeaconError extends Error {\n constructor(message: string, opts?: ErrorOptions) {\n super(message, opts);\n this.name = new.target.name;\n Object.setPrototypeOf(this, new.target.prototype);\n }\n}\n\n/** Thrown when tour or coachmark configuration is invalid, such as an empty `steps` array or duplicate step ids. */\nexport class BeaconConfigError extends BeaconError {}\n\n/** Thrown when a disposed handle is used after {@link BeaconTourHandle.dispose}. */\nexport class BeaconDisposedError extends BeaconError {}\n"],"mappings":";AACA,IAAa,cAAb,cAAiC,MAAM;CACrC,YAAY,GAAiB,GAAqB;EAGhD,AAFA,MAAMA,GAASC,CAAI,GACnB,KAAK,OAAO,WAAW,MACvB,OAAO,eAAe,MAAM,WAAW,SAAS;CAClD;AACF,GAGa,oBAAb,cAAuC,YAAY,CAAC,GAGvC,sBAAb,cAAyC,YAAY,CAAC"}
package/dist/index.cjs ADDED
@@ -0,0 +1 @@
1
+ Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./target.cjs"),t=require("./errors.cjs"),n=require("./coachmark.cjs"),r=require("./tour.cjs");exports.BeaconConfigError=t.BeaconConfigError,exports.BeaconDisposedError=t.BeaconDisposedError,exports.BeaconError=t.BeaconError,exports.createCoachmark=n.createCoachmark,exports.createTour=r.createTour,exports.resolveTarget=e.resolveTarget;
@@ -0,0 +1,6 @@
1
+ export { createCoachmark } from './coachmark';
2
+ export { BeaconConfigError, BeaconDisposedError, BeaconError } from './errors';
3
+ export { resolveTarget } from './target';
4
+ export { createTour } from './tour';
5
+ export type { BeaconBaseEvent, BeaconCoachmarkConfig, BeaconCoachmarkEvent, BeaconCoachmarkHandle, BeaconCurrentStep, BeaconPlacement, BeaconPresentation, BeaconProgress, BeaconRect, BeaconStatus, BeaconStep, BeaconStorage, BeaconTarget, BeaconTargetResolver, BeaconTourConfig, BeaconTourEvent, BeaconTourHandle, } from './types';
6
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAC/E,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,QAAQ,CAAC;AACpC,YAAY,EACV,eAAe,EACf,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,iBAAiB,EACjB,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,UAAU,EACV,YAAY,EACZ,UAAU,EACV,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,GACjB,MAAM,SAAS,CAAC"}
package/dist/index.js ADDED
@@ -0,0 +1,5 @@
1
+ import { resolveTarget as e } from "./target.js";
2
+ import { BeaconConfigError as t, BeaconDisposedError as n, BeaconError as r } from "./errors.js";
3
+ import { createCoachmark as i } from "./coachmark.js";
4
+ import { createTour as a } from "./tour.js";
5
+ export { t as BeaconConfigError, n as BeaconDisposedError, r as BeaconError, i as createCoachmark, a as createTour, e as resolveTarget };
@@ -0,0 +1,2 @@
1
+ var isElement=e=>typeof Element<`u`&&e instanceof Element,isRect=e=>typeof e==`object`&&!!e&&typeof e.x==`number`&&typeof e.y==`number`&&typeof e.width==`number`&&typeof e.height==`number`,normalize=e=>{if(e===null)return null;if(!isElement(e))return e;let t=e.getBoundingClientRect();return{height:t.height,width:t.width,x:t.x,y:t.y}};function resolveTarget(e){return typeof e==`string`?typeof document>`u`?null:normalize(document.querySelector(e)):normalize(typeof e==`function`?e()??null:e)}function targetAvailable(e){return resolveTarget(e)!==null}function targetElement(e){if(typeof e==`string`)return typeof document>`u`?null:document.querySelector(e);if(typeof e==`function`){let t=e();return t==null||!isElement(t)?null:t}return isElement(e)?e:null}function isStaticTarget(e){return isElement(e)||isRect(e)}function sameRect(e,t){return e===null||t===null?e===t:e.x===t.x&&e.y===t.y&&e.width===t.width&&e.height===t.height}exports.isStaticTarget=isStaticTarget,exports.resolveTarget=resolveTarget,exports.sameRect=sameRect,exports.targetAvailable=targetAvailable,exports.targetElement=targetElement;
2
+ //# sourceMappingURL=target.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"target.cjs","names":["value","box","target","resolved","a","b"],"sources":["../src/target.ts"],"sourcesContent":["import type { BeaconRect, BeaconTarget, BeaconTargetResolver } from './types';\n\nconst isElement = (value: unknown): value is Element => typeof Element !== 'undefined' && value instanceof Element;\n\nconst isRect = (value: unknown): value is BeaconRect =>\n typeof value === 'object' &&\n value !== null &&\n typeof (value as BeaconRect).x === 'number' &&\n typeof (value as BeaconRect).y === 'number' &&\n typeof (value as BeaconRect).width === 'number' &&\n typeof (value as BeaconRect).height === 'number';\n\n/** Copies into a plain rect: a DOMRect carries methods and a prototype the contract does not promise. */\nconst normalize = (value: Element | BeaconRect | null): BeaconRect | null => {\n if (value === null) return null;\n if (!isElement(value)) return value;\n const box = value.getBoundingClientRect();\n\n return { height: box.height, width: box.width, x: box.x, y: box.y };\n};\n\n/**\n * Resolves a target to a viewport-space rect, or `null` when it is not available\n * yet. The shape matches `getBoundingClientRect()` and `@vielzeug/orbit`'s\n * `Rect`, so a presentation layer can anchor an orbit positioner with:\n *\n * ```ts\n * const reference = { getBoundingClientRect: () => resolveTarget(step.target) ?? ZERO_RECT };\n * ```\n *\n * Call it on every position update rather than caching the result: a target\n * moves when the page scrolls, and the panel has to follow.\n */\nexport function resolveTarget(target: BeaconTarget): BeaconRect | null {\n if (typeof target === 'string') {\n if (typeof document === 'undefined') return null;\n\n return normalize(document.querySelector(target));\n }\n\n if (typeof target === 'function') {\n const resolved = (target as BeaconTargetResolver)();\n\n return normalize(resolved === null || resolved === undefined ? null : resolved);\n }\n\n return normalize(target);\n}\n\n/** @internal Whether a target currently resolves; decides whether observation is needed. */\nexport function targetAvailable(target: BeaconTarget): boolean {\n return resolveTarget(target) !== null;\n}\n\n/**\n * @internal The live element a target points at, or `null` when it resolves to a\n * bare rect or is not in the document. Layout observation needs the element:\n * a rect has no box to watch, so those targets stay scroll/resize-only.\n */\nexport function targetElement(target: BeaconTarget): Element | null {\n if (typeof target === 'string') {\n return typeof document === 'undefined' ? null : document.querySelector(target);\n }\n\n if (typeof target === 'function') {\n const resolved = (target as BeaconTargetResolver)();\n\n return resolved === null || resolved === undefined || !isElement(resolved) ? null : resolved;\n }\n\n return isElement(target) ? target : null;\n}\n\n/** @internal Static targets never change availability, so there is nothing to observe. */\nexport function isStaticTarget(target: BeaconTarget): boolean {\n return isElement(target) || isRect(target);\n}\n\n/** @internal Value equality for rects, so a layout refresh that changed nothing republishes nothing. */\nexport function sameRect(a: BeaconRect | null, b: BeaconRect | null): boolean {\n if (a === null || b === null) return a === b;\n\n return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;\n}\n"],"mappings":"AAEA,IAAM,UAAa,GAAqC,OAAO,QAAY,KAAeA,aAAiB,QAErG,OAAU,GACd,OAAOA,GAAU,YACjBA,GACA,OAAQA,EAAqB,GAAM,UACnC,OAAQA,EAAqB,GAAM,UACnC,OAAQA,EAAqB,OAAU,UACvC,OAAQA,EAAqB,QAAW,SAGpC,UAAa,GAA0D,CAC3E,GAAIA,IAAU,KAAM,OAAO,KAC3B,GAAI,CAAC,UAAUA,CAAK,EAAG,OAAOA,EAC9B,IAAMC,EAAMD,EAAM,sBAAsB,EAExC,MAAO,CAAE,OAAQC,EAAI,OAAQ,MAAOA,EAAI,MAAO,EAAGA,EAAI,EAAG,EAAGA,EAAI,CAAE,CACpE,EAcA,SAAgB,cAAc,EAAyC,CAarE,OAZI,OAAOC,GAAW,SAChB,OAAO,SAAa,IAAoB,KAErC,UAAU,SAAS,cAAcA,CAAM,CAAC,EAMxC,UAHL,OAAOA,GAAW,WACFA,EAED,GAA8C,KAGhDA,CAFjB,CAGF,CAGA,SAAgB,gBAAgB,EAA+B,CAC7D,OAAO,cAAcA,CAAM,IAAM,IACnC,CAOA,SAAgB,cAAc,EAAsC,CAClE,GAAI,OAAOA,GAAW,SACpB,OAAO,OAAO,SAAa,IAAc,KAAO,SAAS,cAAcA,CAAM,EAG/E,GAAI,OAAOA,GAAW,WAAY,CAChC,IAAMC,EAAYD,EAAgC,EAElD,OAAOC,GAAa,MAAkC,CAAC,UAAUA,CAAQ,EAAI,KAAOA,CACtF,CAEA,OAAO,UAAUD,CAAM,EAAIA,EAAS,IACtC,CAGA,SAAgB,eAAe,EAA+B,CAC5D,OAAO,UAAUA,CAAM,GAAK,OAAOA,CAAM,CAC3C,CAGA,SAAgB,SAAS,EAAsB,EAA+B,CAG5E,OAFIE,IAAM,MAAQC,IAAM,KAAaD,IAAMC,EAEpCD,EAAE,IAAMC,EAAE,GAAKD,EAAE,IAAMC,EAAE,GAAKD,EAAE,QAAUC,EAAE,OAASD,EAAE,SAAWC,EAAE,MAC7E,C"}
@@ -0,0 +1,15 @@
1
+ import type { BeaconRect, BeaconTarget } from './types';
2
+ /**
3
+ * Resolves a target to a viewport-space rect, or `null` when it is not available
4
+ * yet. The shape matches `getBoundingClientRect()` and `@vielzeug/orbit`'s
5
+ * `Rect`, so a presentation layer can anchor an orbit positioner with:
6
+ *
7
+ * ```ts
8
+ * const reference = { getBoundingClientRect: () => resolveTarget(step.target) ?? ZERO_RECT };
9
+ * ```
10
+ *
11
+ * Call it on every position update rather than caching the result: a target
12
+ * moves when the page scrolls, and the panel has to follow.
13
+ */
14
+ export declare function resolveTarget(target: BeaconTarget): BeaconRect | null;
15
+ //# sourceMappingURL=target.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../src/target.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAwB,MAAM,SAAS,CAAC;AAqB9E;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,YAAY,GAAG,UAAU,GAAG,IAAI,CAcrE"}
package/dist/target.js ADDED
@@ -0,0 +1,36 @@
1
+ //#region src/target.ts
2
+ var isElement = (e) => typeof Element < "u" && e instanceof Element, isRect = (e) => typeof e == "object" && !!e && typeof e.x == "number" && typeof e.y == "number" && typeof e.width == "number" && typeof e.height == "number", normalize = (e) => {
3
+ if (e === null) return null;
4
+ if (!isElement(e)) return e;
5
+ let t = e.getBoundingClientRect();
6
+ return {
7
+ height: t.height,
8
+ width: t.width,
9
+ x: t.x,
10
+ y: t.y
11
+ };
12
+ };
13
+ function resolveTarget(e) {
14
+ return typeof e == "string" ? typeof document > "u" ? null : normalize(document.querySelector(e)) : normalize(typeof e == "function" ? e() ?? null : e);
15
+ }
16
+ function targetAvailable(e) {
17
+ return resolveTarget(e) !== null;
18
+ }
19
+ function targetElement(e) {
20
+ if (typeof e == "string") return typeof document > "u" ? null : document.querySelector(e);
21
+ if (typeof e == "function") {
22
+ let t = e();
23
+ return t == null || !isElement(t) ? null : t;
24
+ }
25
+ return isElement(e) ? e : null;
26
+ }
27
+ function isStaticTarget(e) {
28
+ return isElement(e) || isRect(e);
29
+ }
30
+ function sameRect(e, t) {
31
+ return e === null || t === null ? e === t : e.x === t.x && e.y === t.y && e.width === t.width && e.height === t.height;
32
+ }
33
+ //#endregion
34
+ export { isStaticTarget, resolveTarget, sameRect, targetAvailable, targetElement };
35
+
36
+ //# sourceMappingURL=target.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"target.js","names":["value","box","target","resolved","a","b"],"sources":["../src/target.ts"],"sourcesContent":["import type { BeaconRect, BeaconTarget, BeaconTargetResolver } from './types';\n\nconst isElement = (value: unknown): value is Element => typeof Element !== 'undefined' && value instanceof Element;\n\nconst isRect = (value: unknown): value is BeaconRect =>\n typeof value === 'object' &&\n value !== null &&\n typeof (value as BeaconRect).x === 'number' &&\n typeof (value as BeaconRect).y === 'number' &&\n typeof (value as BeaconRect).width === 'number' &&\n typeof (value as BeaconRect).height === 'number';\n\n/** Copies into a plain rect: a DOMRect carries methods and a prototype the contract does not promise. */\nconst normalize = (value: Element | BeaconRect | null): BeaconRect | null => {\n if (value === null) return null;\n if (!isElement(value)) return value;\n const box = value.getBoundingClientRect();\n\n return { height: box.height, width: box.width, x: box.x, y: box.y };\n};\n\n/**\n * Resolves a target to a viewport-space rect, or `null` when it is not available\n * yet. The shape matches `getBoundingClientRect()` and `@vielzeug/orbit`'s\n * `Rect`, so a presentation layer can anchor an orbit positioner with:\n *\n * ```ts\n * const reference = { getBoundingClientRect: () => resolveTarget(step.target) ?? ZERO_RECT };\n * ```\n *\n * Call it on every position update rather than caching the result: a target\n * moves when the page scrolls, and the panel has to follow.\n */\nexport function resolveTarget(target: BeaconTarget): BeaconRect | null {\n if (typeof target === 'string') {\n if (typeof document === 'undefined') return null;\n\n return normalize(document.querySelector(target));\n }\n\n if (typeof target === 'function') {\n const resolved = (target as BeaconTargetResolver)();\n\n return normalize(resolved === null || resolved === undefined ? null : resolved);\n }\n\n return normalize(target);\n}\n\n/** @internal Whether a target currently resolves; decides whether observation is needed. */\nexport function targetAvailable(target: BeaconTarget): boolean {\n return resolveTarget(target) !== null;\n}\n\n/**\n * @internal The live element a target points at, or `null` when it resolves to a\n * bare rect or is not in the document. Layout observation needs the element:\n * a rect has no box to watch, so those targets stay scroll/resize-only.\n */\nexport function targetElement(target: BeaconTarget): Element | null {\n if (typeof target === 'string') {\n return typeof document === 'undefined' ? null : document.querySelector(target);\n }\n\n if (typeof target === 'function') {\n const resolved = (target as BeaconTargetResolver)();\n\n return resolved === null || resolved === undefined || !isElement(resolved) ? null : resolved;\n }\n\n return isElement(target) ? target : null;\n}\n\n/** @internal Static targets never change availability, so there is nothing to observe. */\nexport function isStaticTarget(target: BeaconTarget): boolean {\n return isElement(target) || isRect(target);\n}\n\n/** @internal Value equality for rects, so a layout refresh that changed nothing republishes nothing. */\nexport function sameRect(a: BeaconRect | null, b: BeaconRect | null): boolean {\n if (a === null || b === null) return a === b;\n\n return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;\n}\n"],"mappings":";AAEA,IAAM,aAAa,MAAqC,OAAO,UAAY,OAAeA,aAAiB,SAErG,UAAU,MACd,OAAOA,KAAU,cACjBA,KACA,OAAQA,EAAqB,KAAM,YACnC,OAAQA,EAAqB,KAAM,YACnC,OAAQA,EAAqB,SAAU,YACvC,OAAQA,EAAqB,UAAW,UAGpC,aAAa,MAA0D;CAC3E,IAAIA,MAAU,MAAM,OAAO;CAC3B,IAAI,CAAC,UAAUA,CAAK,GAAG,OAAOA;CAC9B,IAAMC,IAAMD,EAAM,sBAAsB;CAExC,OAAO;EAAE,QAAQC,EAAI;EAAQ,OAAOA,EAAI;EAAO,GAAGA,EAAI;EAAG,GAAGA,EAAI;CAAE;AACpE;AAcA,SAAgB,cAAc,GAAyC;CAarE,OAZI,OAAOC,KAAW,WAChB,OAAO,WAAa,MAAoB,OAErC,UAAU,SAAS,cAAcA,CAAM,CAAC,IAMxC,UAHL,OAAOA,KAAW,aACFA,EAED,KAA8C,OAGhDA,CAFjB;AAGF;AAGA,SAAgB,gBAAgB,GAA+B;CAC7D,OAAO,cAAcA,CAAM,MAAM;AACnC;AAOA,SAAgB,cAAc,GAAsC;CAClE,IAAI,OAAOA,KAAW,UACpB,OAAO,OAAO,WAAa,MAAc,OAAO,SAAS,cAAcA,CAAM;CAG/E,IAAI,OAAOA,KAAW,YAAY;EAChC,IAAMC,IAAYD,EAAgC;EAElD,OAAOC,KAAa,QAAkC,CAAC,UAAUA,CAAQ,IAAI,OAAOA;CACtF;CAEA,OAAO,UAAUD,CAAM,IAAIA,IAAS;AACtC;AAGA,SAAgB,eAAe,GAA+B;CAC5D,OAAO,UAAUA,CAAM,KAAK,OAAOA,CAAM;AAC3C;AAGA,SAAgB,SAAS,GAAsB,GAA+B;CAG5E,OAFIE,MAAM,QAAQC,MAAM,OAAaD,MAAMC,IAEpCD,EAAE,MAAMC,EAAE,KAAKD,EAAE,MAAMC,EAAE,KAAKD,EAAE,UAAUC,EAAE,SAASD,EAAE,WAAWC,EAAE;AAC7E"}
package/dist/tour.cjs ADDED
@@ -0,0 +1,2 @@
1
+ const e=require("./_emit.cjs"),t=require("./_storage.cjs"),n=require("./target.cjs"),r=require("./_target.cjs"),i=require("./errors.cjs");require("./_dev.cjs");const a=require("./_scroll.cjs");let o=require("@vielzeug/ripple");var validateConfig=e=>{if(!e.id)throw new i.BeaconConfigError(`createTour: "id" must be a non-empty string`);if(!Array.isArray(e.steps)||e.steps.length===0)throw new i.BeaconConfigError(`createTour: tour "${e.id}" must have at least one step`);let t=new Set;for(let n of e.steps){if(!n.id)throw new i.BeaconConfigError(`createTour: every step of tour "${e.id}" needs a non-empty id`);if(t.has(n.id))throw new i.BeaconConfigError(`createTour: duplicate step id "${n.id}" in tour "${e.id}"`);t.add(n.id)}};function createTour(s){validateConfig(s);let c=s.version??1,l=s.targetTimeoutMs??1/0,u=s.autoScroll??!0,d=s.storage??t.createMemoryStorage(),f=t.storageKey(s.id),p=new AbortController,{signal:m}=p,{emit:h,warn:g,tap:_,clear:v}=e.createTappers(m),y=(0,o.signal)(`idle`),b=(0,o.signal)(!0),x=(0,o.signal)({placement:s.placement??`auto`,presentation:s.presentation??`auto`,rect:null,step:null,stepIndex:-1,totalSteps:s.steps.length}),stopWaiting=null,S=0,disposedError=()=>new i.BeaconDisposedError(`This tour handle has been disposed.`),guard=()=>{if(m.aborted)throw disposedError()},persist=()=>{let e={status:y.peek(),stepIndex:x.peek().stepIndex,version:c};try{let t=d.set(f,e);t instanceof Promise&&t.catch(e=>g(e))}catch(e){g(e)}},clearPersisted=()=>{try{let e=d.remove(f);e instanceof Promise&&e.catch(e=>g(e))}catch(e){g(e)}},setStatus=e=>{y.peek()!==e&&(y.value=e,persist(),h({status:e,type:`status-change`}))},stopTargetWatch=()=>{stopWaiting?.(),stopWaiting=null},refreshActiveRect=()=>{let e=x.peek().step;if(!e?.target)return;let t=n.resolveTarget(e.target);n.sameRect(t,x.peek().rect)||(x.value={...x.peek(),rect:t})},watchActiveTarget=e=>{let t=!1,onLayout=()=>{t||refreshActiveRect()};window.addEventListener(`scroll`,onLayout,{passive:!0}),window.addEventListener(`resize`,onLayout);let n=r.observeTarget(e,onLayout,m),i=r.observeTargetLayout(e,onLayout,m),stop=()=>{t||(t=!0,window.removeEventListener(`scroll`,onLayout),window.removeEventListener(`resize`,onLayout),n?.(),i?.())};return m.addEventListener(`abort`,stop,{once:!0}),stop},publishStep=e=>{stopTargetWatch();let t=s.steps[e]??null,r=x.peek().step;r&&r!==t&&h({index:x.peek().stepIndex,step:r,type:`step:complete`}),x.value={placement:t?.placement??s.placement??`auto`,presentation:t?.presentation??s.presentation??`auto`,rect:t?.target?n.resolveTarget(t.target):null,step:t,stepIndex:e,totalSteps:s.steps.length},t&&(h({index:e,step:t,type:`step:start`}),u&&t.target&&a.scrollTargetIntoView(t.target,{offset:s.scrollOffset}),t.target&&(stopWaiting=watchActiveTarget(t.target)))},finishInternal=e=>{stopTargetWatch();let t=x.peek().step;t&&h({index:x.peek().stepIndex,step:t,type:`step:complete`}),x.value={...x.peek(),rect:null,step:null,stepIndex:-1},setStatus(`completed`),h({reason:e,type:`tour:complete`})},activateStep=e=>{stopTargetWatch();let t=s.steps[e];if(!t)return;if(!t.target||l===0||n.targetAvailable(t.target)){publishStep(e);return}let i=!0,a=null,o=null,c=t.target;stopWaiting=()=>{i=!1,o?.(),o=null,a!==null&&(clearTimeout(a),a=null)},o=r.observeTarget(c,()=>{i&&n.targetAvailable(c)&&publishStep(e)},m),h({index:e,message:`Waiting for step "${t.id}" to become visible.`,step:t,type:`target-waiting`}),Number.isFinite(l)&&(a=setTimeout(()=>{i&&(stopTargetWatch(),h({message:`Skipped step "${t.id}": its target did not appear within ${l}ms.`,type:`target-missing`}),e+1<s.steps.length?activateStep(e+1):finishInternal(`finish`))},l))},advanceTo=e=>{e<0||(e>=s.steps.length?finishInternal(`finish`):(y.peek()!==`active`&&setStatus(`active`),activateStep(e)))},startInternal=()=>{guard();let e=y.peek();if(e===`completed`||e===`dismissed`||e===`active`)return;let t=Math.max(0,x.peek().stepIndex);setStatus(`active`),activateStep(t)},C=++S,applyStored=e=>{if(C!==S||m.aborted)return;let n=t.parseProgress(e);if(n&&n.version>=c){if(n.status===`completed`||n.status===`dismissed`){y.value=n.status,b.value=!1;return}(n.status===`active`||n.status===`paused`)&&(y.value=`paused`,x.value={...x.peek(),stepIndex:Math.min(n.stepIndex,s.steps.length-1)})}b.value=!0,s.autoStart&&queueMicrotask(()=>{m.aborted||startInternal()})};try{let e=d.get(f);e instanceof Promise?e.then(applyStored,e=>g(e)):applyStored(e)}catch(e){g(e)}return{back(){guard(),advanceTo(x.peek().stepIndex-1)},current:x,dismiss(){guard(),y.peek()!==`completed`&&y.peek()!==`dismissed`&&(stopTargetWatch(),x.value={...x.peek(),rect:null,step:null,stepIndex:-1},setStatus(`dismissed`),h({type:`tour:dismiss`}))},disposalSignal:m,dispose(){m.aborted||(h({type:`dispose`}),stopTargetWatch(),p.abort(),v())},get disposed(){return m.aborted},eligible:b,finish(){guard(),y.peek()!==`completed`&&finishInternal(`finish`)},goto(e){guard();let t=typeof e==`number`?e:s.steps.findIndex(t=>t.id===e);t<0||t>=s.steps.length?`${String(e)}${s.id}`:advanceTo(t)},id:s.id,next(){guard(),advanceTo(x.peek().stepIndex+1)},pause(){guard(),y.peek()===`active`&&(stopTargetWatch(),x.value={...x.peek(),rect:null},setStatus(`paused`))},reset(){guard(),stopTargetWatch(),clearPersisted(),x.value={placement:s.placement??`auto`,presentation:s.presentation??`auto`,rect:null,step:null,stepIndex:-1,totalSteps:s.steps.length},y.value=`idle`,b.value=!0,h({status:`idle`,type:`status-change`})},skip(){guard(),y.peek()!==`completed`&&y.peek()!==`dismissed`&&(stopTargetWatch(),x.value={...x.peek(),rect:null,step:null,stepIndex:-1},setStatus(`dismissed`),h({reason:`skip`,type:`tour:complete`}))},start:startInternal,status:y,steps:s.steps,tap:_,[Symbol.dispose](){this.dispose()}}}exports.createTour=createTour;
2
+ //# sourceMappingURL=tour.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tour.cjs","names":["BeaconConfigError","createMemoryStorage","storageKey","createTappers","signal","BeaconDisposedError","resolveTarget","sameRect","observeTarget","observeTargetLayout","targetAvailable","parseProgress","require__emit","require__storage","require_target","require__target","require_errors","require__scroll","_vielzeug_ripple","config","seen","step","version","targetTimeoutMs","autoScroll","storage","key","controller","disposal","warnTap","clearTappers","status","eligible","current","loadSequence","record","result","error","next","emit","rect","stopped","stopObserver","target","stopLayout","index","previous","waiting","timer","s","resumeAt","sequence","stored","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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"}
package/dist/tour.d.ts ADDED
@@ -0,0 +1,13 @@
1
+ import type { BeaconTourConfig, BeaconTourHandle } from './types';
2
+ /**
3
+ * Creates a guided tour: a sequential, resumable walkthrough over the app's own
4
+ * DOM. The engine owns step order, target waiting, persistence, and events; a
5
+ * presentation layer (refine's tour components or the app's markup) renders
6
+ * `current` wherever it likes.
7
+ *
8
+ * Progress persists under the tour's id. A stored record written under an older
9
+ * `version` makes the tour eligible again, which is how feature announcements
10
+ * re-reach users who finished the original tour.
11
+ */
12
+ export declare function createTour(config: BeaconTourConfig): BeaconTourHandle;
13
+ //# sourceMappingURL=tour.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tour.d.ts","sourceRoot":"","sources":["../src/tour.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAKV,gBAAgB,EAEhB,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAkBjB;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,gBAAgB,GAAG,gBAAgB,CA+UrE"}