@flowsterix/core 0.10.1 → 0.10.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +298 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,298 @@
|
|
|
1
|
+
# @flowsterix/core Maintainer Documentation
|
|
2
|
+
|
|
3
|
+
This is the maintainer-facing source of truth for `@flowsterix/core`.
|
|
4
|
+
|
|
5
|
+
It covers:
|
|
6
|
+
|
|
7
|
+
- package architecture and concepts
|
|
8
|
+
- runtime data flows
|
|
9
|
+
- capabilities map
|
|
10
|
+
- exhaustive API inventory for exported runtime values and types
|
|
11
|
+
- testing and release workflow
|
|
12
|
+
|
|
13
|
+
This document is implementation-oriented, not end-user onboarding.
|
|
14
|
+
|
|
15
|
+
## Quick Facts
|
|
16
|
+
|
|
17
|
+
- package root: `packages/core`
|
|
18
|
+
- source entry: `src/index.ts`
|
|
19
|
+
- package exports:
|
|
20
|
+
- `@flowsterix/core`
|
|
21
|
+
- published outputs: `dist/*`
|
|
22
|
+
- package publishes only `dist`
|
|
23
|
+
|
|
24
|
+
## Purpose and Boundaries
|
|
25
|
+
|
|
26
|
+
`@flowsterix/core` contains the framework-agnostic tour engine:
|
|
27
|
+
|
|
28
|
+
- flow definition model (`FlowDefinition`, `Step`, advance rules, dialogs, HUD options)
|
|
29
|
+
- typed event bus
|
|
30
|
+
- flow store state machine (`createFlowStore`)
|
|
31
|
+
- storage adapters and snapshot abstractions
|
|
32
|
+
- schema validation (`zod`)
|
|
33
|
+
- version migration/resolution utilities
|
|
34
|
+
|
|
35
|
+
`@flowsterix/react` and other UI integrations should treat this package as runtime authority for state transitions and event semantics.
|
|
36
|
+
|
|
37
|
+
## Architecture Overview
|
|
38
|
+
|
|
39
|
+
```mermaid
|
|
40
|
+
flowchart TD
|
|
41
|
+
A["FlowDefinition"] --> B["createFlow / validateFlowDefinition"]
|
|
42
|
+
B --> C["createFlowStore"]
|
|
43
|
+
C --> D["FlowState transitions"]
|
|
44
|
+
C --> E["EventBus emit lifecycle events"]
|
|
45
|
+
C --> F["StorageAdapter hydrate/persist"]
|
|
46
|
+
F --> G["Version helpers<br/>compare + migrate + reset"]
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Core Concepts
|
|
50
|
+
|
|
51
|
+
- `FlowDefinition`:
|
|
52
|
+
- declarative flow graph: steps, version, optional dialogs/hud/migration.
|
|
53
|
+
- `FlowState`:
|
|
54
|
+
- runtime state snapshot with status, step index, version, timestamps.
|
|
55
|
+
- `FlowStore`:
|
|
56
|
+
- transition API (`start`, `next`, `back`, `goToStep`, `pause`, `resume`, `cancel`, `complete`, `advanceStep`) plus subscription.
|
|
57
|
+
- `FlowEvents`:
|
|
58
|
+
- typed lifecycle and step transition events.
|
|
59
|
+
- `StorageAdapter`:
|
|
60
|
+
- pluggable persistence layer over `StorageSnapshot`.
|
|
61
|
+
- Version handling:
|
|
62
|
+
- supports semantic comparison and migration/reset on mismatch.
|
|
63
|
+
|
|
64
|
+
## Runtime Data Flows
|
|
65
|
+
|
|
66
|
+
### 1. Definition Validation Path
|
|
67
|
+
|
|
68
|
+
1. Definition is created/validated via:
|
|
69
|
+
- `createFlow`
|
|
70
|
+
- `validateFlowDefinition`
|
|
71
|
+
- `flowDefinitionSchema`
|
|
72
|
+
2. Cross-reference invariants are checked (for example dialog references).
|
|
73
|
+
|
|
74
|
+
### 2. Store Transition Path
|
|
75
|
+
|
|
76
|
+
1. `createFlowStore` initializes state and event bus.
|
|
77
|
+
2. Transition methods call internal `commit`.
|
|
78
|
+
3. `commit`:
|
|
79
|
+
- updates normalized state
|
|
80
|
+
- persists snapshot (if enabled)
|
|
81
|
+
- emits lifecycle + step transition + state change events
|
|
82
|
+
- notifies subscribers
|
|
83
|
+
|
|
84
|
+
### 3. Hydration + Version Resolution Path
|
|
85
|
+
|
|
86
|
+
1. Storage snapshot is loaded and validated.
|
|
87
|
+
2. Version mismatch is resolved via `handleVersionMismatch`:
|
|
88
|
+
- `same` -> continue
|
|
89
|
+
- `minor` -> step ID/index resolution
|
|
90
|
+
- `major` -> migrate function if available, otherwise reset
|
|
91
|
+
3. Resulting state is committed and propagated.
|
|
92
|
+
|
|
93
|
+
### 4. Analytics Path
|
|
94
|
+
|
|
95
|
+
- `FlowAnalyticsHandlers` maps event names to callback handlers (e.g. `onFlowStart`, `onStepEnter`).
|
|
96
|
+
- Emitted in parallel with event bus dispatch from the store.
|
|
97
|
+
|
|
98
|
+
## Capabilities Matrix
|
|
99
|
+
|
|
100
|
+
| Capability | Primary APIs | Implementation |
|
|
101
|
+
| --- | --- | --- |
|
|
102
|
+
| Definition validation | `createFlow`, `validateFlowDefinition`, `flowDefinitionSchema` | `src/createFlow.ts`, `src/validation.ts` |
|
|
103
|
+
| Typed event bus | `createEventBus`, `EventBus` | `src/events.ts` |
|
|
104
|
+
| Flow state machine | `createFlowStore`, `FlowStore` | `src/state.ts` |
|
|
105
|
+
| Storage abstractions | `StorageAdapter`, `StorageSnapshot` | `src/storage.ts` |
|
|
106
|
+
| In-memory storage | `MemoryStorageAdapter` | `src/storage.ts` |
|
|
107
|
+
| Browser storage | `createLocalStorageAdapter` | `src/storage.ts` |
|
|
108
|
+
| API storage | `createApiStorageAdapter` | `src/storage.ts` |
|
|
109
|
+
| Promise normalization | `resolveMaybePromise`, `MaybePromise` | `src/storage.ts`, `src/types.ts` |
|
|
110
|
+
| Version compare/parse/serialize | `compareVersions`, `parseVersion`, `serializeVersion` | `src/version.ts` |
|
|
111
|
+
| Version mismatch resolution | `handleVersionMismatch`, `buildStepIdMap` | `src/version.ts` |
|
|
112
|
+
| Declarative data model/types | `FlowDefinition`, `Step`, etc. | `src/types.ts` |
|
|
113
|
+
|
|
114
|
+
## API Inventory (Exhaustive)
|
|
115
|
+
|
|
116
|
+
This inventory reflects everything exported from `src/index.ts`.
|
|
117
|
+
|
|
118
|
+
### Runtime Exports
|
|
119
|
+
|
|
120
|
+
- `createFlow`
|
|
121
|
+
- `createEventBus`
|
|
122
|
+
- `createFlowStore`
|
|
123
|
+
- `MemoryStorageAdapter`
|
|
124
|
+
- `createApiStorageAdapter`
|
|
125
|
+
- `createLocalStorageAdapter`
|
|
126
|
+
- `resolveMaybePromise`
|
|
127
|
+
- `flowDefinitionSchema`
|
|
128
|
+
- `validateFlowDefinition`
|
|
129
|
+
- `buildStepIdMap`
|
|
130
|
+
- `compareVersions`
|
|
131
|
+
- `handleVersionMismatch`
|
|
132
|
+
- `parseVersion`
|
|
133
|
+
- `serializeVersion`
|
|
134
|
+
|
|
135
|
+
### Type Exports
|
|
136
|
+
|
|
137
|
+
- Event bus/storage/store options:
|
|
138
|
+
- `EventBus`
|
|
139
|
+
- `EventHandler`
|
|
140
|
+
- `EventKey`
|
|
141
|
+
- `FlowStoreOptions`
|
|
142
|
+
- `ApiStorageAdapterOptions`
|
|
143
|
+
- `StorageAdapter`
|
|
144
|
+
- `StorageSnapshot`
|
|
145
|
+
- Core model and runtime:
|
|
146
|
+
- `MaybePromise`
|
|
147
|
+
- `FlowStatus`
|
|
148
|
+
- `FlowCancelReason`
|
|
149
|
+
- `FlowVersion`
|
|
150
|
+
- `FlowState`
|
|
151
|
+
- `FlowStore`
|
|
152
|
+
- `StartFlowOptions`
|
|
153
|
+
- `ResumeStrategy`
|
|
154
|
+
- Steps and transition model:
|
|
155
|
+
- `StepDirection`
|
|
156
|
+
- `StepEnterReason`
|
|
157
|
+
- `StepExitReason`
|
|
158
|
+
- `StepCompleteReason`
|
|
159
|
+
- `StepTransitionPayload`
|
|
160
|
+
- `StepEnterEvent`
|
|
161
|
+
- `StepExitEvent`
|
|
162
|
+
- `StepCompleteEvent`
|
|
163
|
+
- `StepPlacement`
|
|
164
|
+
- `StepMask`
|
|
165
|
+
- `HiddenTargetFallbackMode`
|
|
166
|
+
- `ScrollMarginConfig`
|
|
167
|
+
- `StepScrollMode`
|
|
168
|
+
- `StepTargetBehavior`
|
|
169
|
+
- `StepTarget`
|
|
170
|
+
- `StepControlState`
|
|
171
|
+
- `StepControls`
|
|
172
|
+
- `StepWaitForSubscribeContext`
|
|
173
|
+
- `StepWaitForPredicate`
|
|
174
|
+
- `StepWaitForSubscribe`
|
|
175
|
+
- `StepWaitFor`
|
|
176
|
+
- `AdvancePredicateContext`
|
|
177
|
+
- `AdvanceRule`
|
|
178
|
+
- `StepHookContext`
|
|
179
|
+
- `StepHook`
|
|
180
|
+
- `Step`
|
|
181
|
+
- HUD and dialog config types:
|
|
182
|
+
- `BackdropInteractionMode`
|
|
183
|
+
- `FlowHudPopoverOptions`
|
|
184
|
+
- `FlowHudBackdropOptions`
|
|
185
|
+
- `FlowHudBehaviorOptions`
|
|
186
|
+
- `FlowHudGuardElementFocusRing`
|
|
187
|
+
- `FlowHudRenderMode`
|
|
188
|
+
- `FlowHudTokenOverrides`
|
|
189
|
+
- `FlowHudOptions`
|
|
190
|
+
- `DialogAutoOpen`
|
|
191
|
+
- `DialogAutoClose`
|
|
192
|
+
- `DialogConfig`
|
|
193
|
+
- Version/migration types:
|
|
194
|
+
- `VersionCompareResult`
|
|
195
|
+
- `VersionMismatchAction`
|
|
196
|
+
- `MigrationContext`
|
|
197
|
+
- `FlowMigrateFn`
|
|
198
|
+
- `VersionMismatchInfo`
|
|
199
|
+
- Error/event/analytics types:
|
|
200
|
+
- `FlowDefinition`
|
|
201
|
+
- `FlowErrorCode`
|
|
202
|
+
- `FlowErrorEvent`
|
|
203
|
+
- `FlowEvents`
|
|
204
|
+
- `FlowAnalyticsHandlers`
|
|
205
|
+
|
|
206
|
+
## Files and Responsibilities
|
|
207
|
+
|
|
208
|
+
- Public API barrel:
|
|
209
|
+
- `src/index.ts`
|
|
210
|
+
- Data model and contracts:
|
|
211
|
+
- `src/types.ts`
|
|
212
|
+
- Validation:
|
|
213
|
+
- `src/validation.ts`
|
|
214
|
+
- `src/createFlow.ts`
|
|
215
|
+
- Event bus:
|
|
216
|
+
- `src/events.ts`
|
|
217
|
+
- State machine:
|
|
218
|
+
- `src/state.ts`
|
|
219
|
+
- Storage:
|
|
220
|
+
- `src/storage.ts`
|
|
221
|
+
- Versioning and migration:
|
|
222
|
+
- `src/version.ts`
|
|
223
|
+
|
|
224
|
+
## Invariants and Behavioral Rules
|
|
225
|
+
|
|
226
|
+
- `FlowDefinition.version` is required and serialized as `major.minor`.
|
|
227
|
+
- Store methods are async-aware through `MaybePromise`.
|
|
228
|
+
- Terminal states (`completed`, `cancelled`) are preserved across version mismatch.
|
|
229
|
+
- Minor version mismatch prefers `stepId` remap before fallback to valid index.
|
|
230
|
+
- Major mismatch uses `migrate` if present, otherwise resets.
|
|
231
|
+
- `advanceStep(stepId)` is guarded and no-ops unless current step matches.
|
|
232
|
+
- Storage hydration accepts legacy numeric version snapshots for backward compatibility.
|
|
233
|
+
|
|
234
|
+
## Debugging Checklist
|
|
235
|
+
|
|
236
|
+
1. Definition validation
|
|
237
|
+
- run through `createFlow`/`validateFlowDefinition`
|
|
238
|
+
- verify dialog references and step IDs
|
|
239
|
+
|
|
240
|
+
2. State transitions
|
|
241
|
+
- inspect `FlowState.status`, `stepIndex`, `cancelReason`, `updatedAt`
|
|
242
|
+
- confirm transition method called while status permits it
|
|
243
|
+
|
|
244
|
+
3. Event lifecycle
|
|
245
|
+
- verify event bus listeners for:
|
|
246
|
+
- `stepEnter`, `stepExit`, `stepComplete`, `stepChange`, `stateChange`
|
|
247
|
+
- `flowStart`, `flowResume`, `flowPause`, `flowCancel`, `flowComplete`
|
|
248
|
+
|
|
249
|
+
4. Persistence and hydration
|
|
250
|
+
- confirm `storageKey`, adapter behavior, and `persistOnChange`
|
|
251
|
+
- inspect snapshot shape and version format
|
|
252
|
+
|
|
253
|
+
5. Version mismatches
|
|
254
|
+
- check compare result (`same|minor|major`)
|
|
255
|
+
- check migration callback behavior and fallback reset path
|
|
256
|
+
|
|
257
|
+
## Local Workflow
|
|
258
|
+
|
|
259
|
+
Run from repo root:
|
|
260
|
+
|
|
261
|
+
```bash
|
|
262
|
+
pnpm --filter @flowsterix/core test
|
|
263
|
+
pnpm --filter @flowsterix/core typecheck
|
|
264
|
+
pnpm --filter @flowsterix/core build
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Important:
|
|
268
|
+
|
|
269
|
+
- consuming apps generally execute `dist` artifacts
|
|
270
|
+
- source edits may require rebuild to be reflected in consuming runtime
|
|
271
|
+
- never hand-edit `dist`
|
|
272
|
+
|
|
273
|
+
## Current Tests
|
|
274
|
+
|
|
275
|
+
- `src/__tests__/events.test.ts`
|
|
276
|
+
- `src/__tests__/flowEvents.test.ts`
|
|
277
|
+
- `src/__tests__/storage.test.ts`
|
|
278
|
+
- `src/__tests__/validation.test.ts`
|
|
279
|
+
- `src/__tests__/version.test.ts`
|
|
280
|
+
|
|
281
|
+
When changing behavior:
|
|
282
|
+
|
|
283
|
+
- add/adjust tests in the corresponding domain (`state`, `storage`, `version`, `validation`, `events`)
|
|
284
|
+
- use deterministic tests for migration and persistence edge cases
|
|
285
|
+
- validate both sync and async adapter paths when touching commit/persist logic
|
|
286
|
+
|
|
287
|
+
## Release and Maintenance Checklist
|
|
288
|
+
|
|
289
|
+
1. Update implementation and tests.
|
|
290
|
+
2. Run:
|
|
291
|
+
- `pnpm --filter @flowsterix/core test`
|
|
292
|
+
- `pnpm --filter @flowsterix/core typecheck`
|
|
293
|
+
- `pnpm --filter @flowsterix/core build`
|
|
294
|
+
3. Update `CHANGELOG.md`.
|
|
295
|
+
4. Update this README when:
|
|
296
|
+
- exports change
|
|
297
|
+
- invariants or migration semantics change
|
|
298
|
+
- storage/version behavior changes
|