Line data Source code
1 : import { shallowReactive, watch } from 'vue'
2 :
3 : import type { CoachId } from './onboardingTours'
4 :
5 : /** Reports its own rect: a canvas node moves without firing any DOM event. */
6 : export interface RectTarget {
7 : getRect: () => DOMRect | null
8 : onMove: (notify: () => void) => () => void
9 : dispose?: () => void
10 : }
11 :
12 : export type CoachTarget = HTMLElement | RectTarget
13 :
14 48 : export function isRectTarget(target: CoachTarget): target is RectTarget {
15 48 : return !(target instanceof HTMLElement)
16 : }
17 :
18 2355 : const EMPTY: readonly CoachTarget[] = []
19 :
20 : /** A target's rect, once it is rendered with a size. */
21 21 : export function laidOutRect(target: CoachTarget): DOMRect | null {
22 21 : const rect = isRectTarget(target)
23 : ? target.getRect()
24 : : target.getBoundingClientRect()
25 21 : if (!rect || rect.width <= 0 || rect.height <= 0) return null
26 21 : return rect
27 : }
28 :
29 : // An id can map to several elements (e.g. responsive variants); consumers pick
30 : // the first laid-out one.
31 2355 : const registry = shallowReactive(new Map<CoachId, readonly CoachTarget[]>())
32 :
33 4340 : export function registerCoachmark(id: CoachId, target: CoachTarget) {
34 4340 : registry.set(id, [...(registry.get(id) ?? EMPTY), target])
35 : }
36 :
37 276 : export function unregisterCoachmark(id: CoachId, target: CoachTarget) {
38 276 : const next = (registry.get(id) ?? EMPTY).filter((entry) => entry !== target)
39 276 : if (next.length) registry.set(id, next)
40 204 : else registry.delete(id)
41 : }
42 :
43 27 : export function coachmarkElements(id: CoachId): readonly CoachTarget[] {
44 27 : return registry.get(id) ?? EMPTY
45 : }
46 :
47 17 : export function targetMounted(id: CoachId): boolean {
48 17 : return coachmarkElements(id).some((target) => !!laidOutRect(target))
49 : }
50 :
51 : // Frequent enough to feel immediate, cheap enough not to measure every frame.
52 : export const PLACEMENT_POLL_MS = 100
53 :
54 : /** Resolves once a laid-out target for the id exists; false on timeout or abort. */
55 1 : export function waitForTarget(
56 : id: CoachId,
57 : signal: AbortSignal,
58 : timeoutMs: number
59 : ): Promise<boolean> {
60 1 : if (targetMounted(id)) return Promise.resolve(true)
61 : // An already-aborted signal never fires 'abort', so resolve up front.
62 1 : if (signal.aborted) return Promise.resolve(false)
63 1 : return new Promise((resolve) => {
64 1 : let done = false
65 1 : let poll: ReturnType<typeof setTimeout> | undefined
66 1 : function finish(found: boolean) {
67 1 : if (done) return
68 1 : done = true
69 1 : stopWatch()
70 1 : clearTimeout(poll)
71 1 : clearTimeout(timer)
72 1 : signal.removeEventListener('abort', onAbort)
73 1 : resolve(found)
74 : }
75 0 : function onAbort() {
76 0 : finish(false)
77 : }
78 : // Placement is a measurement nothing reports, so it is sampled — but only
79 : // while a candidate is registered, which is reactive.
80 2 : function samplePlacement() {
81 2 : if (targetMounted(id)) finish(true)
82 1 : else if (coachmarkElements(id).length)
83 0 : poll = setTimeout(samplePlacement, PLACEMENT_POLL_MS)
84 : }
85 1 : const stopWatch = watch(
86 : () => coachmarkElements(id).length,
87 : () => {
88 1 : clearTimeout(poll)
89 1 : samplePlacement()
90 : },
91 : { flush: 'post' }
92 : )
93 1 : const timer = setTimeout(() => finish(false), timeoutMs)
94 1 : signal.addEventListener('abort', onAbort)
95 1 : samplePlacement()
96 : })
97 : }
98 :
99 : /** Resets shared state between tests. */
100 : export function clearCoachmarks() {
101 : registry.clear()
102 : }
|