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