Line data Source code
1 : import { autoUpdate, flip, offset, shift, useFloating } from '@floating-ui/vue'
2 : import type {
3 : Middleware,
4 : Placement,
5 : Rect,
6 : ReferenceElement
7 : } from '@floating-ui/vue'
8 : import { refDebounced, useEventListener } from '@vueuse/core'
9 : import { computed, ref, toValue, watchEffect } from 'vue'
10 : import type { MaybeRefOrGetter, Ref } from 'vue'
11 :
12 : import {
13 : CARD_GAP,
14 : CURSOR_GAP,
15 : VIEWPORT_MARGIN,
16 : topSafeInset
17 : } from './coachmarkLayout'
18 : import {
19 : coachmarkElements,
20 : isRectTarget,
21 : laidOutRect
22 : } from './coachmarkRegistry'
23 : import type { CoachTarget } from './coachmarkRegistry'
24 : import type { CoachPlacement, SpotlightStep } from './onboardingTours'
25 :
26 : // A target animating in via CSS transform reports through neither scroll nor
27 : // resize events; poll each frame until its rect holds still this long.
28 2355 : const MOTION_SETTLE_MS = 250
29 :
30 2355 : const PLACEMENT: Record<
31 : Exclude<CoachPlacement, 'auto' | 'center'>,
32 : Placement
33 : > = {
34 : left: 'left-start',
35 : right: 'right-start',
36 : leftCenter: 'left',
37 : rightCenter: 'right',
38 : bottom: 'bottom'
39 : }
40 :
41 4717 : function floatingPlacement(step: SpotlightStep | null): Placement {
42 4717 : const placement = step?.placement
43 4717 : if (!placement || placement === 'auto' || placement === 'center')
44 6 : return 'right-start'
45 4711 : return PLACEMENT[placement]
46 : }
47 :
48 : // Surfaces the measured target rect so the spotlight can trace it.
49 2355 : const captureReference: Middleware = {
50 : name: 'captureReference',
51 : fn: (state) => ({ data: { rect: state.rects.reference } })
52 : }
53 :
54 4717 : function floatingMiddleware(
55 : step: SpotlightStep | null,
56 : topInset: number
57 : ): Middleware[] {
58 4717 : const list: Middleware[] = [offset(step?.cursor ? CURSOR_GAP : CARD_GAP)]
59 4717 : if (!step?.placement || step.placement === 'auto') list.push(flip())
60 : // shift only guards the main axis by default; crossAxis keeps vertically-
61 : // centred placements (leftCenter, rightCenter) on-screen too.
62 4717 : list.push(
63 : shift({
64 : crossAxis: true,
65 : padding: {
66 : top: topInset,
67 : left: VIEWPORT_MARGIN,
68 : right: VIEWPORT_MARGIN,
69 : bottom: CARD_GAP
70 : }
71 : }),
72 : captureReference
73 : )
74 4717 : return list
75 : }
76 :
77 : /**
78 : * A deferred target animates in under its own CSS transform, which reports
79 : * through neither scroll nor resize: it is still settling until its rect has
80 : * held still long enough for the debounced copy to catch up.
81 : */
82 24 : export function isSettling(
83 : step: SpotlightStep | null,
84 : rect: DOMRect | null,
85 : settled: DOMRect | null
86 : ): boolean {
87 24 : return !!step?.deferTarget && rect !== settled
88 : }
89 :
90 : /**
91 : * Locates a step's target in the registry and positions the card beside it with
92 : * Floating UI, following the target until its rect settles.
93 : */
94 2358 : export function useCoachmarkTarget(
95 : step: MaybeRefOrGetter<SpotlightStep | null>,
96 : cardRef: Ref<HTMLElement | null>
97 : ) {
98 2358 : const candidates = computed<readonly CoachTarget[]>(() => {
99 4717 : const id = toValue(step)?.coachId
100 4717 : return id ? coachmarkElements(id) : []
101 : })
102 :
103 2358 : const anchor = computed(
104 : () => candidates.value.find((candidate) => laidOutRect(candidate)) ?? null
105 : )
106 :
107 2358 : const movingAnchor = computed(() =>
108 : anchor.value && isRectTarget(anchor.value) ? anchor.value : null
109 : )
110 :
111 2358 : const targetMoves = computed(() => !!movingAnchor.value)
112 :
113 2358 : const reference = computed<ReferenceElement | null>(() => {
114 2362 : const candidate = anchor.value
115 2362 : if (!candidate) return null
116 7 : if (!isRectTarget(candidate)) return candidate
117 0 : return {
118 : getBoundingClientRect: () => candidate.getRect() ?? new DOMRect()
119 : }
120 : })
121 :
122 : // The top bar's height only changes on resize, so read it once and refresh
123 : // then — Floating UI re-runs the middleware every frame while tracking motion.
124 2358 : const topInset = ref(topSafeInset())
125 2358 : useEventListener('resize', () => {
126 74 : topInset.value = topSafeInset()
127 : })
128 :
129 2358 : const { floatingStyles, middlewareData, isPositioned, placement, update } =
130 : useFloating(reference, cardRef, {
131 : open: () => !!cardRef.value,
132 : strategy: 'fixed',
133 : transform: false,
134 : placement: () => floatingPlacement(toValue(step)),
135 : middleware: () => floatingMiddleware(toValue(step), topInset.value)
136 : })
137 :
138 2358 : watchEffect((onCleanup) => {
139 2358 : const candidate = movingAnchor.value
140 2358 : if (!candidate) return
141 0 : onCleanup(candidate.onMove(() => update()))
142 : })
143 :
144 2358 : const targetRect = computed<DOMRect | null>(() => {
145 : const data = middlewareData.value.captureReference as
146 : | { rect: Rect }
147 : | undefined
148 2375 : const rect = data?.rect
149 2375 : if (!rect || rect.width === 0) return null
150 17 : return new DOMRect(rect.x, rect.y, rect.width, rect.height)
151 : })
152 :
153 2358 : const settledRect = refDebounced(targetRect, MOTION_SETTLE_MS)
154 2358 : const trackMotion = computed(() =>
155 : isSettling(toValue(step), targetRect.value, settledRect.value)
156 : )
157 :
158 2358 : watchEffect((onCleanup) => {
159 2368 : const element = anchor.value
160 2368 : const floating = cardRef.value
161 2368 : if (!element || isRectTarget(element) || !floating) return
162 10 : onCleanup(
163 : autoUpdate(element, floating, update, {
164 : animationFrame: trackMotion.value
165 : })
166 : )
167 : })
168 :
169 : /** Whether a candidate is anchored — a rect target holds no element. */
170 : const hasTarget = computed(() => !!anchor.value)
171 :
172 2358 : return {
173 : anchor,
174 : hasTarget,
175 : targetRect,
176 : targetMoves,
177 : floatingStyles,
178 : isPositioned,
179 : placement
180 : }
181 : }
|