LCOV - code coverage report
Current view: top level - src/platform/onboarding - useCoachmarkTarget.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 95.7 % 47 45
Test Date: 2026-11-17 04:17:53

            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              : }
        

Generated by: LCOV version 2.0-1