@daltonr/pathwrite-solid 0.11.0
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 +351 -0
- package/dist/index.css +476 -0
- package/dist/index.d.ts +143 -0
- package/dist/index.js +157 -0
- package/dist/index.js.map +1 -0
- package/package.json +58 -0
- package/src/index.tsx +597 -0
package/dist/index.css
ADDED
|
@@ -0,0 +1,476 @@
|
|
|
1
|
+
/*
|
|
2
|
+
* Pathwrite — Default Shell Stylesheet
|
|
3
|
+
*
|
|
4
|
+
* Optional CSS for the <PathShell> / <pw-shell> default UI components.
|
|
5
|
+
* Import this file if you want sensible out-of-the-box styling.
|
|
6
|
+
* Every visual value is a CSS custom property (--pw-*) so you can
|
|
7
|
+
* theme the shell without overriding selectors.
|
|
8
|
+
*
|
|
9
|
+
* Usage (React / Vue):
|
|
10
|
+
* import "adapter-package/styles.css";
|
|
11
|
+
*
|
|
12
|
+
* Usage (Angular) — add to the styles array in angular.json:
|
|
13
|
+
* "node_modules/@daltonr/pathwrite-angular/dist/index.css"
|
|
14
|
+
*/
|
|
15
|
+
|
|
16
|
+
/* ------------------------------------------------------------------ */
|
|
17
|
+
/* Custom property defaults */
|
|
18
|
+
/* ------------------------------------------------------------------ */
|
|
19
|
+
:root {
|
|
20
|
+
/* Layout */
|
|
21
|
+
--pw-shell-max-width: 720px;
|
|
22
|
+
--pw-shell-padding: 24px;
|
|
23
|
+
--pw-shell-gap: 20px;
|
|
24
|
+
--pw-shell-radius: 10px;
|
|
25
|
+
|
|
26
|
+
/* Colours */
|
|
27
|
+
--pw-color-bg: #ffffff;
|
|
28
|
+
--pw-color-border: #dbe4f0;
|
|
29
|
+
--pw-color-text: #1f2937;
|
|
30
|
+
--pw-color-muted: #5b677a;
|
|
31
|
+
--pw-color-primary: #2563eb;
|
|
32
|
+
--pw-color-primary-light: rgba(37, 99, 235, 0.12);
|
|
33
|
+
--pw-color-btn-bg: #f8fbff;
|
|
34
|
+
--pw-color-btn-border: #c2d0e5;
|
|
35
|
+
|
|
36
|
+
/* Progress */
|
|
37
|
+
--pw-dot-size: 32px;
|
|
38
|
+
--pw-dot-font-size: 13px;
|
|
39
|
+
--pw-track-height: 4px;
|
|
40
|
+
|
|
41
|
+
/* Buttons */
|
|
42
|
+
--pw-btn-padding: 8px 16px;
|
|
43
|
+
--pw-btn-radius: 6px;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/* ------------------------------------------------------------------ */
|
|
47
|
+
/* Shell root */
|
|
48
|
+
/* ------------------------------------------------------------------ */
|
|
49
|
+
.pw-shell {
|
|
50
|
+
max-width: var(--pw-shell-max-width);
|
|
51
|
+
margin: 0 auto;
|
|
52
|
+
display: flex;
|
|
53
|
+
flex-direction: column;
|
|
54
|
+
gap: var(--pw-shell-gap);
|
|
55
|
+
padding: var(--pw-shell-padding);
|
|
56
|
+
font-family: system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
|
|
57
|
+
color: var(--pw-color-text);
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
/* ------------------------------------------------------------------ */
|
|
61
|
+
/* Empty state */
|
|
62
|
+
/* ------------------------------------------------------------------ */
|
|
63
|
+
.pw-shell__empty {
|
|
64
|
+
text-align: center;
|
|
65
|
+
padding: 32px 16px;
|
|
66
|
+
color: var(--pw-color-muted);
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
.pw-shell__start-btn {
|
|
70
|
+
margin-top: 12px;
|
|
71
|
+
border: 1px solid var(--pw-color-btn-border);
|
|
72
|
+
background: var(--pw-color-btn-bg);
|
|
73
|
+
color: var(--pw-color-text);
|
|
74
|
+
padding: var(--pw-btn-padding);
|
|
75
|
+
border-radius: var(--pw-btn-radius);
|
|
76
|
+
cursor: pointer;
|
|
77
|
+
font-size: 14px;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/* ------------------------------------------------------------------ */
|
|
81
|
+
/* Root progress — persistent top-level bar visible during sub-paths */
|
|
82
|
+
/* ------------------------------------------------------------------ */
|
|
83
|
+
.pw-shell__root-progress {
|
|
84
|
+
background: var(--pw-color-bg);
|
|
85
|
+
border: 1px solid var(--pw-color-border);
|
|
86
|
+
border-radius: var(--pw-shell-radius);
|
|
87
|
+
padding: 20px 24px 16px;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
.pw-shell__root-progress .pw-shell__steps {
|
|
91
|
+
display: flex;
|
|
92
|
+
justify-content: space-between;
|
|
93
|
+
margin-bottom: 12px;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
.pw-shell__root-progress .pw-shell__step {
|
|
97
|
+
display: flex;
|
|
98
|
+
flex-direction: column;
|
|
99
|
+
align-items: center;
|
|
100
|
+
gap: 6px;
|
|
101
|
+
flex: 1;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/* Merge root progress + sub-path header into a single card */
|
|
105
|
+
.pw-shell__root-progress + .pw-shell__header {
|
|
106
|
+
margin-top: calc(-1 * var(--pw-shell-gap));
|
|
107
|
+
border-top: 1px solid var(--pw-color-border);
|
|
108
|
+
border-top-left-radius: 0;
|
|
109
|
+
border-top-right-radius: 0;
|
|
110
|
+
padding: 12px 24px 12px;
|
|
111
|
+
opacity: 0.6;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
.pw-shell__root-progress:has(+ .pw-shell__header) {
|
|
115
|
+
border-bottom-left-radius: 0;
|
|
116
|
+
border-bottom-right-radius: 0;
|
|
117
|
+
padding-bottom: 12px;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
.pw-shell__root-progress + .pw-shell__header .pw-shell__steps {
|
|
121
|
+
margin-bottom: 6px;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
.pw-shell__root-progress + .pw-shell__header .pw-shell__step-dot {
|
|
125
|
+
width: 22px;
|
|
126
|
+
height: 22px;
|
|
127
|
+
font-size: 10px;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
.pw-shell__root-progress + .pw-shell__header .pw-shell__step-label {
|
|
131
|
+
font-size: 10px;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
.pw-shell__root-progress + .pw-shell__header .pw-shell__track {
|
|
135
|
+
height: 3px;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/* Split layout — disable the merged-card effect */
|
|
139
|
+
.pw-shell--progress-split .pw-shell__root-progress + .pw-shell__header {
|
|
140
|
+
margin-top: 0;
|
|
141
|
+
border-top: 1px solid var(--pw-color-border);
|
|
142
|
+
border-radius: var(--pw-shell-radius);
|
|
143
|
+
}
|
|
144
|
+
.pw-shell--progress-split .pw-shell__root-progress:has(+ .pw-shell__header) {
|
|
145
|
+
border-radius: var(--pw-shell-radius);
|
|
146
|
+
padding-bottom: 16px;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
/* ------------------------------------------------------------------ */
|
|
150
|
+
/* Header — progress indicator */
|
|
151
|
+
/* ------------------------------------------------------------------ */
|
|
152
|
+
.pw-shell__header {
|
|
153
|
+
background: var(--pw-color-bg);
|
|
154
|
+
border: 1px solid var(--pw-color-border);
|
|
155
|
+
border-radius: var(--pw-shell-radius);
|
|
156
|
+
padding: 20px 24px 16px;
|
|
157
|
+
}
|
|
158
|
+
|
|
159
|
+
.pw-shell__steps {
|
|
160
|
+
display: flex;
|
|
161
|
+
justify-content: space-between;
|
|
162
|
+
margin-bottom: 12px;
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
.pw-shell__step {
|
|
166
|
+
display: flex;
|
|
167
|
+
flex-direction: column;
|
|
168
|
+
align-items: center;
|
|
169
|
+
gap: 6px;
|
|
170
|
+
flex: 1;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
.pw-shell__step-dot {
|
|
174
|
+
width: var(--pw-dot-size);
|
|
175
|
+
height: var(--pw-dot-size);
|
|
176
|
+
border-radius: 50%;
|
|
177
|
+
display: flex;
|
|
178
|
+
align-items: center;
|
|
179
|
+
justify-content: center;
|
|
180
|
+
font-size: var(--pw-dot-font-size);
|
|
181
|
+
font-weight: 600;
|
|
182
|
+
border: 2px solid var(--pw-color-border);
|
|
183
|
+
background: var(--pw-color-bg);
|
|
184
|
+
color: var(--pw-color-muted);
|
|
185
|
+
transition: all 0.25s ease;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
.pw-shell__step--completed .pw-shell__step-dot {
|
|
189
|
+
background: var(--pw-color-primary);
|
|
190
|
+
border-color: var(--pw-color-primary);
|
|
191
|
+
color: #fff;
|
|
192
|
+
}
|
|
193
|
+
|
|
194
|
+
.pw-shell__step--current .pw-shell__step-dot {
|
|
195
|
+
border-color: var(--pw-color-primary);
|
|
196
|
+
color: var(--pw-color-primary);
|
|
197
|
+
box-shadow: 0 0 0 3px var(--pw-color-primary-light);
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
.pw-shell__step-label {
|
|
201
|
+
font-size: 12px;
|
|
202
|
+
color: var(--pw-color-muted);
|
|
203
|
+
text-align: center;
|
|
204
|
+
white-space: nowrap;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
.pw-shell__step--current .pw-shell__step-label {
|
|
208
|
+
color: var(--pw-color-primary);
|
|
209
|
+
font-weight: 600;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
.pw-shell__step--completed .pw-shell__step-label {
|
|
213
|
+
color: var(--pw-color-text);
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
/* Track / fill */
|
|
217
|
+
.pw-shell__track {
|
|
218
|
+
height: var(--pw-track-height);
|
|
219
|
+
background: var(--pw-color-border);
|
|
220
|
+
border-radius: calc(var(--pw-track-height) / 2);
|
|
221
|
+
overflow: hidden;
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
.pw-shell__track-fill {
|
|
225
|
+
height: 100%;
|
|
226
|
+
background: var(--pw-color-primary);
|
|
227
|
+
border-radius: calc(var(--pw-track-height) / 2);
|
|
228
|
+
transition: width 0.3s ease;
|
|
229
|
+
}
|
|
230
|
+
|
|
231
|
+
/* ------------------------------------------------------------------ */
|
|
232
|
+
/* Body — step content */
|
|
233
|
+
/* ------------------------------------------------------------------ */
|
|
234
|
+
.pw-shell__body {
|
|
235
|
+
background: var(--pw-color-bg);
|
|
236
|
+
border: 1px solid var(--pw-color-border);
|
|
237
|
+
border-radius: var(--pw-shell-radius);
|
|
238
|
+
padding: var(--pw-shell-padding);
|
|
239
|
+
min-height: 120px;
|
|
240
|
+
}
|
|
241
|
+
|
|
242
|
+
/* ------------------------------------------------------------------ */
|
|
243
|
+
/* Validation messages */
|
|
244
|
+
/* ------------------------------------------------------------------ */
|
|
245
|
+
:root {
|
|
246
|
+
--pw-color-error: #dc2626;
|
|
247
|
+
--pw-color-error-bg: #fef2f2;
|
|
248
|
+
--pw-color-error-border: #fecaca;
|
|
249
|
+
--pw-color-warning: #d97706;
|
|
250
|
+
--pw-color-warning-bg: #fffbeb;
|
|
251
|
+
--pw-color-warning-border: #fde68a;
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
.pw-shell__validation {
|
|
255
|
+
list-style: none;
|
|
256
|
+
margin: 0;
|
|
257
|
+
padding: 12px 16px;
|
|
258
|
+
background: var(--pw-color-error-bg);
|
|
259
|
+
border: 1px solid var(--pw-color-error-border);
|
|
260
|
+
border-radius: var(--pw-shell-radius);
|
|
261
|
+
display: flex;
|
|
262
|
+
flex-direction: column;
|
|
263
|
+
gap: 4px;
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
.pw-shell__validation-item {
|
|
267
|
+
font-size: 13px;
|
|
268
|
+
color: var(--pw-color-error);
|
|
269
|
+
padding-left: 16px;
|
|
270
|
+
position: relative;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
.pw-shell__validation-item::before {
|
|
274
|
+
content: "•";
|
|
275
|
+
position: absolute;
|
|
276
|
+
left: 4px;
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
.pw-shell__validation-label {
|
|
280
|
+
font-weight: 600;
|
|
281
|
+
margin-right: 3px;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
.pw-shell__validation-label::after {
|
|
285
|
+
content: ":";
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/* ------------------------------------------------------------------ */
|
|
289
|
+
/* Blocking error (guard-level message, not field-attached) */
|
|
290
|
+
/* ------------------------------------------------------------------ */
|
|
291
|
+
.pw-shell__blocking-error {
|
|
292
|
+
margin: 0;
|
|
293
|
+
padding: 8px 16px;
|
|
294
|
+
font-size: 13px;
|
|
295
|
+
color: var(--pw-color-error);
|
|
296
|
+
}
|
|
297
|
+
|
|
298
|
+
/* ------------------------------------------------------------------ */
|
|
299
|
+
/* Warning messages */
|
|
300
|
+
/* ------------------------------------------------------------------ */
|
|
301
|
+
.pw-shell__warnings {
|
|
302
|
+
list-style: none;
|
|
303
|
+
margin: 0;
|
|
304
|
+
padding: 12px 16px;
|
|
305
|
+
background: var(--pw-color-warning-bg);
|
|
306
|
+
border: 1px solid var(--pw-color-warning-border);
|
|
307
|
+
border-radius: var(--pw-shell-radius);
|
|
308
|
+
display: flex;
|
|
309
|
+
flex-direction: column;
|
|
310
|
+
gap: 4px;
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
.pw-shell__warnings-item {
|
|
314
|
+
font-size: 13px;
|
|
315
|
+
color: var(--pw-color-warning);
|
|
316
|
+
padding-left: 16px;
|
|
317
|
+
position: relative;
|
|
318
|
+
}
|
|
319
|
+
|
|
320
|
+
.pw-shell__warnings-item::before {
|
|
321
|
+
content: "•";
|
|
322
|
+
position: absolute;
|
|
323
|
+
left: 4px;
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
.pw-shell__warnings-label {
|
|
327
|
+
font-weight: 600;
|
|
328
|
+
margin-right: 3px;
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
.pw-shell__warnings-label::after {
|
|
332
|
+
content: ":";
|
|
333
|
+
}
|
|
334
|
+
|
|
335
|
+
/* ------------------------------------------------------------------ */
|
|
336
|
+
/* Footer — navigation buttons */
|
|
337
|
+
/* ------------------------------------------------------------------ */
|
|
338
|
+
.pw-shell__footer {
|
|
339
|
+
display: flex;
|
|
340
|
+
justify-content: space-between;
|
|
341
|
+
align-items: center;
|
|
342
|
+
}
|
|
343
|
+
|
|
344
|
+
.pw-shell__footer-left,
|
|
345
|
+
.pw-shell__footer-right {
|
|
346
|
+
display: flex;
|
|
347
|
+
gap: 8px;
|
|
348
|
+
}
|
|
349
|
+
|
|
350
|
+
.pw-shell__btn {
|
|
351
|
+
border: 1px solid var(--pw-color-btn-border);
|
|
352
|
+
background: var(--pw-color-btn-bg);
|
|
353
|
+
color: var(--pw-color-text);
|
|
354
|
+
padding: var(--pw-btn-padding);
|
|
355
|
+
border-radius: var(--pw-btn-radius);
|
|
356
|
+
cursor: pointer;
|
|
357
|
+
font-size: 14px;
|
|
358
|
+
transition: background 0.15s ease, border-color 0.15s ease;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
.pw-shell__btn:hover:not(:disabled) {
|
|
362
|
+
background: var(--pw-color-border);
|
|
363
|
+
}
|
|
364
|
+
|
|
365
|
+
.pw-shell__btn:disabled {
|
|
366
|
+
opacity: 0.5;
|
|
367
|
+
cursor: not-allowed;
|
|
368
|
+
}
|
|
369
|
+
|
|
370
|
+
.pw-shell__btn--next {
|
|
371
|
+
background: var(--pw-color-primary);
|
|
372
|
+
border-color: var(--pw-color-primary);
|
|
373
|
+
color: #fff;
|
|
374
|
+
position: relative;
|
|
375
|
+
}
|
|
376
|
+
|
|
377
|
+
.pw-shell__btn--next:hover:not(:disabled) {
|
|
378
|
+
background: #1d4ed8;
|
|
379
|
+
border-color: #1d4ed8;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
@keyframes pw-spin {
|
|
383
|
+
to { transform: rotate(360deg); }
|
|
384
|
+
}
|
|
385
|
+
|
|
386
|
+
.pw-shell__btn--next.pw-shell__btn--loading {
|
|
387
|
+
color: transparent;
|
|
388
|
+
pointer-events: none;
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
.pw-shell__btn--next.pw-shell__btn--loading::after {
|
|
392
|
+
content: "";
|
|
393
|
+
position: absolute;
|
|
394
|
+
top: 50%;
|
|
395
|
+
left: 50%;
|
|
396
|
+
width: 14px;
|
|
397
|
+
height: 14px;
|
|
398
|
+
margin: -7px 0 0 -7px;
|
|
399
|
+
border: 2px solid rgba(255, 255, 255, 0.35);
|
|
400
|
+
border-top-color: #fff;
|
|
401
|
+
border-radius: 50%;
|
|
402
|
+
animation: pw-spin 0.6s linear infinite;
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
.pw-shell__btn--back {
|
|
406
|
+
background: transparent;
|
|
407
|
+
border-color: var(--pw-color-primary);
|
|
408
|
+
color: var(--pw-color-primary);
|
|
409
|
+
}
|
|
410
|
+
|
|
411
|
+
.pw-shell__btn--back:hover:not(:disabled) {
|
|
412
|
+
background: var(--pw-color-primary-light);
|
|
413
|
+
}
|
|
414
|
+
|
|
415
|
+
.pw-shell__btn--cancel {
|
|
416
|
+
color: var(--pw-color-muted);
|
|
417
|
+
border-color: transparent;
|
|
418
|
+
background: transparent;
|
|
419
|
+
}
|
|
420
|
+
|
|
421
|
+
.pw-shell__btn--cancel:hover:not(:disabled) {
|
|
422
|
+
background: var(--pw-color-primary-light);
|
|
423
|
+
}
|
|
424
|
+
|
|
425
|
+
/* ------------------------------------------------------------------ */
|
|
426
|
+
/* Error panel — replaces footer when status === "error" */
|
|
427
|
+
/* ------------------------------------------------------------------ */
|
|
428
|
+
.pw-shell__error {
|
|
429
|
+
background: var(--pw-color-error-bg);
|
|
430
|
+
border: 1px solid var(--pw-color-error-border);
|
|
431
|
+
border-radius: var(--pw-shell-radius);
|
|
432
|
+
padding: 16px 20px;
|
|
433
|
+
display: flex;
|
|
434
|
+
flex-direction: column;
|
|
435
|
+
gap: 10px;
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
.pw-shell__error-title {
|
|
439
|
+
font-size: 14px;
|
|
440
|
+
font-weight: 600;
|
|
441
|
+
color: var(--pw-color-error);
|
|
442
|
+
}
|
|
443
|
+
|
|
444
|
+
.pw-shell__error-message {
|
|
445
|
+
font-size: 13px;
|
|
446
|
+
color: var(--pw-color-muted);
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
.pw-shell__error-actions {
|
|
450
|
+
display: flex;
|
|
451
|
+
gap: 8px;
|
|
452
|
+
align-items: center;
|
|
453
|
+
margin-top: 2px;
|
|
454
|
+
}
|
|
455
|
+
|
|
456
|
+
.pw-shell__btn--retry {
|
|
457
|
+
background: var(--pw-color-error);
|
|
458
|
+
border-color: var(--pw-color-error);
|
|
459
|
+
color: #fff;
|
|
460
|
+
}
|
|
461
|
+
|
|
462
|
+
.pw-shell__btn--retry:hover:not(:disabled) {
|
|
463
|
+
opacity: 0.9;
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
.pw-shell__btn--suspend {
|
|
467
|
+
color: var(--pw-color-muted);
|
|
468
|
+
border-color: transparent;
|
|
469
|
+
background: transparent;
|
|
470
|
+
font-size: 13px;
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
.pw-shell__btn--suspend:hover:not(:disabled) {
|
|
474
|
+
background: var(--pw-color-primary-light);
|
|
475
|
+
}
|
|
476
|
+
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
import { type Component, type JSX, type Accessor } from "solid-js";
|
|
2
|
+
import { PathData, PathDefinition, PathEngine, PathEvent, PathSnapshot, ProgressLayout } from "@daltonr/pathwrite-core";
|
|
3
|
+
export interface UsePathOptions {
|
|
4
|
+
/**
|
|
5
|
+
* An externally-managed `PathEngine` to subscribe to — for example, the engine
|
|
6
|
+
* returned by `createPersistedEngine()` from `@daltonr/pathwrite-store`.
|
|
7
|
+
*
|
|
8
|
+
* When provided:
|
|
9
|
+
* - `usePath` will **not** create its own engine.
|
|
10
|
+
* - The snapshot is seeded immediately from the engine's current state.
|
|
11
|
+
* - The engine lifecycle (start / cleanup) is the **caller's responsibility**.
|
|
12
|
+
* - `PathShell` will skip its own `autoStart` call.
|
|
13
|
+
*/
|
|
14
|
+
engine?: PathEngine;
|
|
15
|
+
/** Called for every engine event (stateChanged, completed, cancelled, resumed). */
|
|
16
|
+
onEvent?: (event: PathEvent) => void;
|
|
17
|
+
}
|
|
18
|
+
export interface UsePathReturn<TData extends PathData = PathData> {
|
|
19
|
+
/**
|
|
20
|
+
* Reactive snapshot accessor. Call `snapshot()` to read the current value.
|
|
21
|
+
* Automatically tracked as a reactive dependency when read inside JSX or effects.
|
|
22
|
+
*/
|
|
23
|
+
snapshot: Accessor<PathSnapshot<TData> | null>;
|
|
24
|
+
/** Start (or restart) a path. */
|
|
25
|
+
start: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
|
|
26
|
+
/** Push a sub-path onto the stack. Requires an active path. Pass an optional `meta` object for correlation — it is returned unchanged to the parent step's `onSubPathComplete` / `onSubPathCancel` hooks. */
|
|
27
|
+
startSubPath: (path: PathDefinition<any>, initialData?: PathData, meta?: Record<string, unknown>) => Promise<void>;
|
|
28
|
+
/** Advance one step. Completes the path on the last step. */
|
|
29
|
+
next: () => Promise<void>;
|
|
30
|
+
/** Go back one step. No-op when already on the first step of a top-level path. Pops back to the parent path when on the first step of a sub-path. */
|
|
31
|
+
previous: () => Promise<void>;
|
|
32
|
+
/** Cancel the active path (or sub-path). */
|
|
33
|
+
cancel: () => Promise<void>;
|
|
34
|
+
/** Jump directly to a step by ID. Calls onLeave / onEnter but bypasses guards and shouldSkip. */
|
|
35
|
+
goToStep: (stepId: string) => Promise<void>;
|
|
36
|
+
/** Jump directly to a step by ID, checking the current step's canMoveNext (forward) or canMovePrevious (backward) guard first. Navigation is blocked if the guard returns false. */
|
|
37
|
+
goToStepChecked: (stepId: string) => Promise<void>;
|
|
38
|
+
/** Update a single data value; triggers re-renders via stateChanged. When `TData` is specified, `key` and `value` are type-checked against your data shape. */
|
|
39
|
+
setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
|
|
40
|
+
/** Reset the current step's data to what it was when the step was entered. Useful for "Clear" or "Reset" buttons. */
|
|
41
|
+
resetStep: () => Promise<void>;
|
|
42
|
+
/**
|
|
43
|
+
* Tear down any active path (without firing hooks) and immediately start the
|
|
44
|
+
* given path fresh. Safe to call whether or not a path is currently active.
|
|
45
|
+
* Use for "Start over" / retry flows without remounting the component.
|
|
46
|
+
*/
|
|
47
|
+
restart: () => Promise<void>;
|
|
48
|
+
/** Re-runs the operation that set `snapshot().error`. Increments `retryCount` on repeated failure. No-op when there is no pending error. */
|
|
49
|
+
retry: () => Promise<void>;
|
|
50
|
+
/** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
|
|
51
|
+
suspend: () => Promise<void>;
|
|
52
|
+
/** Trigger inline validation on all steps without navigating. Sets `snapshot().hasValidated`. */
|
|
53
|
+
validate: () => void;
|
|
54
|
+
}
|
|
55
|
+
export declare function usePath<TData extends PathData = PathData>(options?: UsePathOptions): UsePathReturn<TData>;
|
|
56
|
+
/**
|
|
57
|
+
* Access the nearest `PathShell`'s path instance and optional services object.
|
|
58
|
+
* Throws if used outside of a PathShell component.
|
|
59
|
+
*
|
|
60
|
+
* Both generics are type-level assertions, not runtime guarantees:
|
|
61
|
+
* - `TData` narrows `snapshot().data`
|
|
62
|
+
* - `TServices` types the `services` value — must match what was passed to `PathShell`
|
|
63
|
+
*/
|
|
64
|
+
export declare function usePathContext<TData extends PathData = PathData, TServices = unknown>(): Omit<UsePathReturn<TData>, "snapshot"> & {
|
|
65
|
+
snapshot: Accessor<PathSnapshot<TData>>;
|
|
66
|
+
services: TServices;
|
|
67
|
+
};
|
|
68
|
+
export interface PathShellActions {
|
|
69
|
+
next: () => Promise<void>;
|
|
70
|
+
previous: () => Promise<void>;
|
|
71
|
+
cancel: () => Promise<void>;
|
|
72
|
+
goToStep: (stepId: string) => Promise<void>;
|
|
73
|
+
goToStepChecked: (stepId: string) => Promise<void>;
|
|
74
|
+
setData: (key: string, value: unknown) => Promise<void>;
|
|
75
|
+
restart: () => Promise<void>;
|
|
76
|
+
retry: () => Promise<void>;
|
|
77
|
+
suspend: () => Promise<void>;
|
|
78
|
+
}
|
|
79
|
+
export interface PathShellProps {
|
|
80
|
+
path: PathDefinition<any>;
|
|
81
|
+
/**
|
|
82
|
+
* An externally-managed engine — for example, the engine returned by
|
|
83
|
+
* `createPersistedEngine()`. When supplied, `PathShell` will skip its own
|
|
84
|
+
* `start()` call and drive the UI from the provided engine instead.
|
|
85
|
+
*/
|
|
86
|
+
engine?: PathEngine;
|
|
87
|
+
initialData?: PathData;
|
|
88
|
+
autoStart?: boolean;
|
|
89
|
+
/**
|
|
90
|
+
* Step render functions keyed by step ID (or `formId` for StepChoice steps).
|
|
91
|
+
* ```tsx
|
|
92
|
+
* <PathShell steps={{ details: (snap) => <DetailsStep snapshot={snap} />, review: (snap) => <ReviewStep snapshot={snap} /> }} />
|
|
93
|
+
* ```
|
|
94
|
+
*/
|
|
95
|
+
steps?: Record<string, (snapshot: PathSnapshot) => JSX.Element>;
|
|
96
|
+
onComplete?: (data: PathData) => void;
|
|
97
|
+
onCancel?: (data: PathData) => void;
|
|
98
|
+
onEvent?: (event: PathEvent) => void;
|
|
99
|
+
renderHeader?: (snapshot: PathSnapshot) => JSX.Element;
|
|
100
|
+
renderFooter?: (snapshot: PathSnapshot, actions: PathShellActions) => JSX.Element;
|
|
101
|
+
backLabel?: string;
|
|
102
|
+
nextLabel?: string;
|
|
103
|
+
completeLabel?: string;
|
|
104
|
+
loadingLabel?: string;
|
|
105
|
+
cancelLabel?: string;
|
|
106
|
+
hideCancel?: boolean;
|
|
107
|
+
hideProgress?: boolean;
|
|
108
|
+
/** If true, hide the footer (navigation buttons). The error panel is still shown on async failure regardless of this prop. */
|
|
109
|
+
hideFooter?: boolean;
|
|
110
|
+
/**
|
|
111
|
+
* Footer layout mode:
|
|
112
|
+
* - `"auto"` (default): Uses "form" for single-step top-level paths, "wizard" otherwise.
|
|
113
|
+
* - `"wizard"`: Back button on left, Cancel and Submit together on right.
|
|
114
|
+
* - `"form"`: Cancel on left, Submit alone on right. Back button never shown.
|
|
115
|
+
*/
|
|
116
|
+
footerLayout?: "wizard" | "form" | "auto";
|
|
117
|
+
/**
|
|
118
|
+
* Controls whether the shell renders its auto-generated field-error summary box.
|
|
119
|
+
* - `"summary"` (default): Shell renders the labeled error list below the step body.
|
|
120
|
+
* - `"inline"`: Suppress the summary — handle errors inside the step component instead.
|
|
121
|
+
* - `"both"`: Render the shell summary AND whatever the step renders.
|
|
122
|
+
*/
|
|
123
|
+
validationDisplay?: "summary" | "inline" | "both";
|
|
124
|
+
/**
|
|
125
|
+
* Controls how progress bars are arranged when a sub-path is active.
|
|
126
|
+
* - `"merged"` (default): Root and sub-path bars in one card.
|
|
127
|
+
* - `"split"`: Root and sub-path bars as separate cards.
|
|
128
|
+
* - `"rootOnly"`: Only the root bar — sub-path bar hidden.
|
|
129
|
+
* - `"activeOnly"`: Only the active (sub-path) bar — root bar hidden.
|
|
130
|
+
*/
|
|
131
|
+
progressLayout?: ProgressLayout;
|
|
132
|
+
/**
|
|
133
|
+
* Services object passed through context to all step components.
|
|
134
|
+
* Step components access it via `usePathContext<TData, TServices>()`.
|
|
135
|
+
*/
|
|
136
|
+
services?: object | null;
|
|
137
|
+
/** When true, calls `validate()` on the engine so all steps show inline errors simultaneously. Useful when this shell is nested inside a step of an outer shell: bind to the outer snapshot's `hasAttemptedNext`. */
|
|
138
|
+
validateWhen?: boolean;
|
|
139
|
+
class?: string;
|
|
140
|
+
}
|
|
141
|
+
export declare const PathShell: Component<PathShellProps>;
|
|
142
|
+
export type { PathData, FieldErrors, PathDefinition, PathEvent, PathSnapshot, PathStep, PathStepContext, ProgressLayout, RootProgress, SerializedPathState, } from "@daltonr/pathwrite-core";
|
|
143
|
+
export { PathEngine } from "@daltonr/pathwrite-core";
|