LCOV - code coverage report
Current view: top level - src/platform/onboarding - onboardingTours.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 77.8 % 18 14
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : import { shallowReactive } from 'vue'
       2              : import type { Ref } from 'vue'
       3              : 
       4              : import type { OnboardingTourNotStartedReason } from '@comfyorg/telemetry/types'
       5              : 
       6              : /** Every tour, including ones whose steps a consumer registers at runtime. */
       7         2355 : export const ENTRY_PATHS = ['appMode', 'firstRun'] as const
       8              : 
       9              : export type EntryPath = (typeof ENTRY_PATHS)[number]
      10              : 
      11              : /** Setting holding the tours the user has completed or dismissed. */
      12         2355 : export const TOUR_SEEN_SETTING = 'Comfy.OnboardingCoachmarks.Seen'
      13              : 
      14              : export type CoachPlacement =
      15              :   | 'left'
      16              :   | 'right'
      17              :   | 'center'
      18              :   | 'bottom'
      19              :   /** Left of the target, vertically centred on it (clamps to the viewport edge). */
      20              :   | 'leftCenter'
      21              :   /** Right of the target, vertically centred on it (clamps to the viewport edge). */
      22              :   | 'rightCenter'
      23              :   /** Sits on whichever horizontal side of the target has more room. */
      24              :   | 'auto'
      25              : 
      26              : /** Every element a tour can point at; the e2e drift guard asserts each resolves. */
      27         2355 : export const COACH_IDS = {
      28              :   appRunButton: 'app-run-button',
      29              :   inputsList: 'inputs-list',
      30              :   outputs: 'outputs',
      31              :   assetsPanel: 'assets-panel'
      32              : } as const
      33              : 
      34              : /**
      35              :  * Graph-view anchors for the first-run tour and its nudge. Kept out of
      36              :  * {@link COACH_IDS} because the drift guard iterates that map and asserts each
      37              :  * id resolves in App mode, where the canvas anchors do not exist.
      38              :  * `runButton` and `templatesButton` are ordinary chrome, so only the first-run
      39              :  * walk and the nudge e2e cover their drift.
      40              :  */
      41         2355 : export const FIRST_RUN_COACH_IDS = {
      42              :   runButton: 'first-run-run-button',
      43              :   source: 'first-run-source',
      44              :   prompt: 'first-run-prompt',
      45              :   sink: 'first-run-sink',
      46              :   templatesButton: 'first-run-templates-button'
      47              : } as const
      48              : 
      49              : export type CoachId =
      50              :   | (typeof COACH_IDS)[keyof typeof COACH_IDS]
      51              :   | (typeof FIRST_RUN_COACH_IDS)[keyof typeof FIRST_RUN_COACH_IDS]
      52              : 
      53              : interface StepBase {
      54              :   /**
      55              :    * Derives the step's translation keys:
      56              :    * `onboardingCoachmarks.<tour>.<name>.title|body`, plus optional
      57              :    * `primary`/`skip` button-label overrides. Read inside a reactive effect, so
      58              :    * a getter here re-resolves the copy as the step's subject changes.
      59              :    */
      60              :   name: string
      61              :   /** Runs when the step is shown; the signal aborts on leaving the step. */
      62              :   onEnter?: (signal: AbortSignal) => void | Promise<void>
      63              : }
      64              : 
      65              : /** Renders the landing dialog: no target, no spotlight, no placement. */
      66              : interface LandingStep extends StepBase {
      67              :   kind: 'landing'
      68              :   image?: string
      69              : }
      70              : 
      71              : /** Spotlights a target, or centres itself when the step names none. */
      72              : export interface SpotlightStep extends StepBase {
      73              :   kind: 'spotlight'
      74              :   /** Element to spotlight (the first laid-out registered candidate wins). */
      75              :   coachId?: CoachId
      76              :   placement: CoachPlacement
      77              :   /** Open this sidebar tab when the step starts (e.g. to reveal its target). */
      78              :   openSidebarTab?: string
      79              :   /** Target mounts later (e.g. a dialog); wait for it instead of dropping the step. */
      80              :   deferTarget?: boolean
      81              :   /** Lets pointer input through the scrim's holes and releases the focus trap. */
      82              :   interactive?: boolean
      83              :   /** Draws a pointer glyph on the card edge facing the target. */
      84              :   cursor?: boolean
      85              :   /**
      86              :    * Offers no primary action: the only way past this step is doing the thing it
      87              :    * asks for in the app, and the consumer advances once that happens.
      88              :    */
      89              :   selfAdvancing?: boolean
      90              : }
      91              : 
      92              : export type CoachStep = LandingStep | SpotlightStep
      93              : 
      94              : export interface TourResolution {
      95              :   steps: CoachStep[]
      96              :   reason?: OnboardingTourNotStartedReason
      97              : }
      98              : 
      99              : /** A tour's steps: a fixed list, or a resolver that builds them at start. */
     100              : export type TourDefinition =
     101              :   | CoachStep[]
     102              :   | (() => Promise<CoachStep[] | TourResolution>)
     103              : 
     104              : /**
     105              :  * Fixes the running step set (and so the step count) at tour start: drops steps
     106              :  * whose own target isn't mounted, keeping targetless and deferred steps.
     107              :  */
     108            6 : export function resolveSteps(
     109              :   steps: CoachStep[],
     110              :   isMounted: (id: CoachId) => boolean
     111              : ): CoachStep[] {
     112            6 :   return steps.filter(
     113              :     (s) =>
     114              :       s.kind === 'landing' ||
     115              :       !s.coachId ||
     116              :       s.deferTarget ||
     117              :       isMounted(s.coachId)
     118              :   )
     119              : }
     120              : 
     121         2355 : const TOURS: Partial<Record<EntryPath, TourDefinition>> = {
     122              :   appMode: [
     123              :     {
     124              :       kind: 'landing',
     125              :       name: 'landing',
     126              :       image: '/assets/images/app-mode-landing.png'
     127              :     },
     128              :     {
     129              :       kind: 'spotlight',
     130              :       name: 'inputs',
     131              :       coachId: COACH_IDS.inputsList,
     132              :       placement: 'auto',
     133              :       deferTarget: true
     134              :     },
     135              :     {
     136              :       kind: 'spotlight',
     137              :       name: 'run',
     138              :       coachId: COACH_IDS.appRunButton,
     139              :       placement: 'auto',
     140              :       deferTarget: true
     141              :     },
     142              :     {
     143              :       kind: 'spotlight',
     144              :       name: 'outputs',
     145              :       coachId: COACH_IDS.outputs,
     146              :       placement: 'leftCenter',
     147              :       deferTarget: true
     148              :     },
     149              :     {
     150              :       kind: 'spotlight',
     151              :       name: 'assets',
     152              :       coachId: COACH_IDS.assetsPanel,
     153              :       placement: 'auto',
     154              :       deferTarget: true,
     155              :       openSidebarTab: 'assets'
     156              :     }
     157              :   ]
     158              : }
     159              : 
     160         2355 : const HOLDS = shallowReactive(new Map<EntryPath, Readonly<Ref<boolean>>>())
     161              : 
     162              : /** False ends the tour: the context its steps point at is gone. */
     163         2355 : export function registerTourHolds(
     164              :   entry: EntryPath,
     165              :   holds?: Readonly<Ref<boolean>>
     166              : ) {
     167         2355 :   if (holds) HOLDS.set(entry, holds)
     168            0 :   else HOLDS.delete(entry)
     169              : }
     170              : 
     171              : /**
     172              :  * Registers a tour whose steps are built by a higher layer — the layer rules
     173              :  * forbid this one from importing them. Re-registering replaces the definition.
     174              :  */
     175            0 : export function registerTour(
     176              :   entry: EntryPath,
     177              :   definition: TourDefinition,
     178              :   holds?: Readonly<Ref<boolean>>
     179              : ) {
     180            0 :   TOURS[entry] = definition
     181            0 :   registerTourHolds(entry, holds)
     182              : }
     183              : 
     184            6 : export function tourDefinition(entry: EntryPath): TourDefinition | undefined {
     185            6 :   return TOURS[entry]
     186              : }
     187              : 
     188              : /** True for a tour that registered no condition — it has no context to lose. */
     189         4810 : export function tourHolds(entry: EntryPath): boolean {
     190         4810 :   return HOLDS.get(entry)?.value ?? true
     191              : }
        

Generated by: LCOV version 2.0-1