@daltonr/pathwrite-react 0.1.3 → 0.1.5
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 +9 -1
- package/dist/index.css +4 -2
- package/dist/index.d.ts +2 -2
- package/dist/index.js.map +1 -1
- package/package.json +6 -3
- package/src/index.ts +368 -0
package/README.md
CHANGED
|
@@ -91,7 +91,7 @@ function NavButtons() {
|
|
|
91
91
|
| `previous()` | `function` | Go back one step. Cancels the path from the first step. |
|
|
92
92
|
| `cancel()` | `function` | Cancel the active path (or sub-path). |
|
|
93
93
|
| `goToStep(stepId)` | `function` | Jump directly to a step by ID. Calls `onLeave` / `onEnter` but bypasses guards and `shouldSkip`. |
|
|
94
|
-
| `setData(key, value)` | `function` | Update a single data value; triggers re-render via `stateChanged`. |
|
|
94
|
+
| `setData(key, value)` | `function` | Update a single data value; triggers re-render via `stateChanged`. When `TData` is specified, `key` and `value` are type-checked against your data shape. |
|
|
95
95
|
|
|
96
96
|
All action callbacks are **referentially stable** — safe to pass as props or include in dependency arrays without causing unnecessary re-renders.
|
|
97
97
|
|
|
@@ -112,6 +112,14 @@ snapshot?.data.age; // number
|
|
|
112
112
|
|
|
113
113
|
The generic is a **type-level assertion** — it narrows `snapshot.data` for convenience but is not enforced at runtime. Define your data shape once in a `PathDefinition<FormData>` and the types will stay consistent throughout.
|
|
114
114
|
|
|
115
|
+
`setData` is also typed against `TData` — passing a wrong key or mismatched value type is a compile-time error:
|
|
116
|
+
|
|
117
|
+
```tsx
|
|
118
|
+
setData("name", 42); // ✗ TS error: number is not assignable to string
|
|
119
|
+
setData("typo", "x"); // ✗ TS error: "typo" is not a key of FormData
|
|
120
|
+
setData("name", "Alice"); // ✓
|
|
121
|
+
```
|
|
122
|
+
|
|
115
123
|
### Snapshot guard booleans
|
|
116
124
|
|
|
117
125
|
The snapshot includes `canMoveNext` and `canMovePrevious` — the evaluated results of the current step's navigation guards. Use them to proactively disable buttons:
|
package/dist/index.css
CHANGED
|
@@ -7,8 +7,10 @@
|
|
|
7
7
|
* theme the shell without overriding selectors.
|
|
8
8
|
*
|
|
9
9
|
* Usage:
|
|
10
|
-
* import "@daltonr/pathwrite-
|
|
11
|
-
*
|
|
10
|
+
* import "@daltonr/pathwrite-react/styles.css"; // React
|
|
11
|
+
* import "@daltonr/pathwrite-vue/styles.css"; // Vue
|
|
12
|
+
* // Angular: add "node_modules/@daltonr/pathwrite-angular/dist/index.css"
|
|
13
|
+
* // to the styles array in angular.json
|
|
12
14
|
*/
|
|
13
15
|
|
|
14
16
|
/* ------------------------------------------------------------------ */
|
package/dist/index.d.ts
CHANGED
|
@@ -19,8 +19,8 @@ export interface UsePathReturn<TData extends PathData = PathData> {
|
|
|
19
19
|
cancel: () => void;
|
|
20
20
|
/** Jump directly to a step by ID. Calls onLeave / onEnter but bypasses guards and shouldSkip. */
|
|
21
21
|
goToStep: (stepId: string) => void;
|
|
22
|
-
/** Update a single data value; triggers a re-render via stateChanged. */
|
|
23
|
-
setData: (key:
|
|
22
|
+
/** Update a single data value; triggers a re-render via stateChanged. When `TData` is specified, `key` and `value` are type-checked against your data shape. */
|
|
23
|
+
setData: <K extends string & keyof TData>(key: K, value: TData[K]) => void;
|
|
24
24
|
}
|
|
25
25
|
export type PathProviderProps = PropsWithChildren<{
|
|
26
26
|
/** Forwarded to the internal usePath hook. */
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,aAAa,EACb,WAAW,EACX,UAAU,EACV,SAAS,EACT,MAAM,EACN,oBAAoB,EACrB,MAAM,OAAO,CAAC;AAEf,OAAO,EAGL,UAAU,EAGX,MAAM,yBAAyB,CAAC;AAmCjC,8EAA8E;AAC9E,eAAe;AACf,8EAA8E;AAE9E,MAAM,UAAU,OAAO,CAAoC,OAAwB;IACjF,sDAAsD;IACtD,MAAM,SAAS,GAAG,MAAM,CAAoB,IAAI,CAAC,CAAC;IAClD,IAAI,SAAS,CAAC,OAAO,KAAK,IAAI,EAAE,CAAC;QAC/B,SAAS,CAAC,OAAO,GAAG,IAAI,UAAU,EAAE,CAAC;IACvC,CAAC;IACD,MAAM,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC;IAEjC,4EAA4E;IAC5E,MAAM,UAAU,GAAG,MAAM,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAC5C,UAAU,CAAC,OAAO,GAAG,OAAO,EAAE,OAAO,CAAC;IAEtC,+DAA+D;IAC/D,MAAM,WAAW,GAAG,MAAM,CAA6B,IAAI,CAAC,CAAC;IAE7D,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,QAAoB,EAAE,EAAE,CACvB,MAAM,CAAC,SAAS,CAAC,CAAC,KAAgB,EAAE,EAAE;QACpC,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;YAC9D,WAAW,CAAC,OAAO,GAAG,KAAK,CAAC,QAA+B,CAAC;QAC9D,CAAC;aAAM,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YACpE,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC;QAC7B,CAAC;QACD,UAAU,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QAC5B,QAAQ,EAAE,CAAC;IACb,CAAC,CAAC,EACJ,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,WAAW,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,WAAW,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;IAE/D,MAAM,QAAQ,GAAG,oBAAoB,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;IAE9D,0BAA0B;IAC1B,MAAM,KAAK,GAAG,WAAW,CACvB,CAAC,IAAoB,EAAE,cAAwB,EAAE,EAAE,EAAE,CACnD,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,WAAW,CAAC,EACjC,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,YAAY,GAAG,WAAW,CAC9B,CAAC,IAAoB,EAAE,cAAwB,EAAE,EAAE,EAAE,CACnD,MAAM,CAAC,YAAY,CAAC,IAAI,EAAE,WAAW,CAAC,EACxC,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IACxD,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAE5D,MAAM,QAAQ,GAAG,WAAW,CAC1B,CAAC,MAAc,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAC3C,CAAC,MAAM,CAAC,CACT,CAAC;IAEF,MAAM,OAAO,GAAG,WAAW,CACzB,
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@daltonr/pathwrite-react",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.5",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"description": "React adapter for @daltonr/pathwrite-core — hooks, context provider, and optional <PathShell> default UI.",
|
|
@@ -18,7 +18,9 @@
|
|
|
18
18
|
"multi-step",
|
|
19
19
|
"workflow"
|
|
20
20
|
],
|
|
21
|
-
"sideEffects": [
|
|
21
|
+
"sideEffects": [
|
|
22
|
+
"**/*.css"
|
|
23
|
+
],
|
|
22
24
|
"exports": {
|
|
23
25
|
".": {
|
|
24
26
|
"types": "./dist/index.d.ts",
|
|
@@ -30,6 +32,7 @@
|
|
|
30
32
|
"types": "dist/index.d.ts",
|
|
31
33
|
"files": [
|
|
32
34
|
"dist",
|
|
35
|
+
"src",
|
|
33
36
|
"README.md",
|
|
34
37
|
"LICENSE"
|
|
35
38
|
],
|
|
@@ -42,7 +45,7 @@
|
|
|
42
45
|
"react": ">=18.0.0"
|
|
43
46
|
},
|
|
44
47
|
"dependencies": {
|
|
45
|
-
"@daltonr/pathwrite-core": "^0.1.
|
|
48
|
+
"@daltonr/pathwrite-core": "^0.1.5"
|
|
46
49
|
},
|
|
47
50
|
"devDependencies": {
|
|
48
51
|
"react": "^18.3.1",
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,368 @@
|
|
|
1
|
+
import {
|
|
2
|
+
createContext,
|
|
3
|
+
createElement,
|
|
4
|
+
useCallback,
|
|
5
|
+
useContext,
|
|
6
|
+
useEffect,
|
|
7
|
+
useRef,
|
|
8
|
+
useSyncExternalStore
|
|
9
|
+
} from "react";
|
|
10
|
+
import type { PropsWithChildren, ReactElement, ReactNode } from "react";
|
|
11
|
+
import {
|
|
12
|
+
PathData,
|
|
13
|
+
PathDefinition,
|
|
14
|
+
PathEngine,
|
|
15
|
+
PathEvent,
|
|
16
|
+
PathSnapshot
|
|
17
|
+
} from "@daltonr/pathwrite-core";
|
|
18
|
+
|
|
19
|
+
// ---------------------------------------------------------------------------
|
|
20
|
+
// Types
|
|
21
|
+
// ---------------------------------------------------------------------------
|
|
22
|
+
|
|
23
|
+
export interface UsePathOptions {
|
|
24
|
+
/** Called for every engine event (stateChanged, completed, cancelled, resumed). */
|
|
25
|
+
onEvent?: (event: PathEvent) => void;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
export interface UsePathReturn<TData extends PathData = PathData> {
|
|
29
|
+
/** Current path snapshot, or `null` when no path is active. Triggers a React re-render on change. */
|
|
30
|
+
snapshot: PathSnapshot<TData> | null;
|
|
31
|
+
/** Start (or restart) a path. */
|
|
32
|
+
start: (path: PathDefinition, initialData?: PathData) => void;
|
|
33
|
+
/** Push a sub-path onto the stack. Requires an active path. */
|
|
34
|
+
startSubPath: (path: PathDefinition, initialData?: PathData) => void;
|
|
35
|
+
/** Advance one step. Completes the path on the last step. */
|
|
36
|
+
next: () => void;
|
|
37
|
+
/** Go back one step. Cancels the path from the first step. */
|
|
38
|
+
previous: () => void;
|
|
39
|
+
/** Cancel the active path (or sub-path). */
|
|
40
|
+
cancel: () => void;
|
|
41
|
+
/** Jump directly to a step by ID. Calls onLeave / onEnter but bypasses guards and shouldSkip. */
|
|
42
|
+
goToStep: (stepId: string) => void;
|
|
43
|
+
/** Update a single data value; triggers a re-render via stateChanged. When `TData` is specified, `key` and `value` are type-checked against your data shape. */
|
|
44
|
+
setData: <K extends string & keyof TData>(key: K, value: TData[K]) => void;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
export type PathProviderProps = PropsWithChildren<{
|
|
48
|
+
/** Forwarded to the internal usePath hook. */
|
|
49
|
+
onEvent?: (event: PathEvent) => void;
|
|
50
|
+
}>;
|
|
51
|
+
|
|
52
|
+
// ---------------------------------------------------------------------------
|
|
53
|
+
// usePath hook
|
|
54
|
+
// ---------------------------------------------------------------------------
|
|
55
|
+
|
|
56
|
+
export function usePath<TData extends PathData = PathData>(options?: UsePathOptions): UsePathReturn<TData> {
|
|
57
|
+
// Stable engine instance for the lifetime of the hook
|
|
58
|
+
const engineRef = useRef<PathEngine | null>(null);
|
|
59
|
+
if (engineRef.current === null) {
|
|
60
|
+
engineRef.current = new PathEngine();
|
|
61
|
+
}
|
|
62
|
+
const engine = engineRef.current;
|
|
63
|
+
|
|
64
|
+
// Keep the onEvent callback current without changing the subscribe identity
|
|
65
|
+
const onEventRef = useRef(options?.onEvent);
|
|
66
|
+
onEventRef.current = options?.onEvent;
|
|
67
|
+
|
|
68
|
+
// Cached snapshot — updated only inside the subscribe callback
|
|
69
|
+
const snapshotRef = useRef<PathSnapshot<TData> | null>(null);
|
|
70
|
+
|
|
71
|
+
const subscribe = useCallback(
|
|
72
|
+
(callback: () => void) =>
|
|
73
|
+
engine.subscribe((event: PathEvent) => {
|
|
74
|
+
if (event.type === "stateChanged" || event.type === "resumed") {
|
|
75
|
+
snapshotRef.current = event.snapshot as PathSnapshot<TData>;
|
|
76
|
+
} else if (event.type === "completed" || event.type === "cancelled") {
|
|
77
|
+
snapshotRef.current = null;
|
|
78
|
+
}
|
|
79
|
+
onEventRef.current?.(event);
|
|
80
|
+
callback();
|
|
81
|
+
}),
|
|
82
|
+
[engine]
|
|
83
|
+
);
|
|
84
|
+
|
|
85
|
+
const getSnapshot = useCallback(() => snapshotRef.current, []);
|
|
86
|
+
|
|
87
|
+
const snapshot = useSyncExternalStore(subscribe, getSnapshot);
|
|
88
|
+
|
|
89
|
+
// Stable action callbacks
|
|
90
|
+
const start = useCallback(
|
|
91
|
+
(path: PathDefinition, initialData: PathData = {}) =>
|
|
92
|
+
engine.start(path, initialData),
|
|
93
|
+
[engine]
|
|
94
|
+
);
|
|
95
|
+
|
|
96
|
+
const startSubPath = useCallback(
|
|
97
|
+
(path: PathDefinition, initialData: PathData = {}) =>
|
|
98
|
+
engine.startSubPath(path, initialData),
|
|
99
|
+
[engine]
|
|
100
|
+
);
|
|
101
|
+
|
|
102
|
+
const next = useCallback(() => engine.next(), [engine]);
|
|
103
|
+
const previous = useCallback(() => engine.previous(), [engine]);
|
|
104
|
+
const cancel = useCallback(() => engine.cancel(), [engine]);
|
|
105
|
+
|
|
106
|
+
const goToStep = useCallback(
|
|
107
|
+
(stepId: string) => engine.goToStep(stepId),
|
|
108
|
+
[engine]
|
|
109
|
+
);
|
|
110
|
+
|
|
111
|
+
const setData = useCallback(
|
|
112
|
+
<K extends string & keyof TData>(key: K, value: TData[K]) => engine.setData(key, value as unknown),
|
|
113
|
+
[engine]
|
|
114
|
+
) as UsePathReturn<TData>["setData"];
|
|
115
|
+
|
|
116
|
+
return { snapshot, start, startSubPath, next, previous, cancel, goToStep, setData };
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
// ---------------------------------------------------------------------------
|
|
120
|
+
// Context + Provider
|
|
121
|
+
// ---------------------------------------------------------------------------
|
|
122
|
+
|
|
123
|
+
const PathContext = createContext<UsePathReturn | null>(null);
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Provides a single `usePath` instance to all descendants.
|
|
127
|
+
* Consume with `usePathContext()`.
|
|
128
|
+
*/
|
|
129
|
+
export function PathProvider({ children, onEvent }: PathProviderProps): ReactElement {
|
|
130
|
+
const path = usePath({ onEvent });
|
|
131
|
+
return createElement(PathContext.Provider, { value: path }, children);
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/**
|
|
135
|
+
* Access the nearest `PathProvider`'s path instance.
|
|
136
|
+
* Throws if used outside of a `<PathProvider>`.
|
|
137
|
+
*
|
|
138
|
+
* The optional generic narrows `snapshot.data` for convenience — it is a
|
|
139
|
+
* **type-level assertion**, not a runtime guarantee.
|
|
140
|
+
*/
|
|
141
|
+
export function usePathContext<TData extends PathData = PathData>(): UsePathReturn<TData> {
|
|
142
|
+
const ctx = useContext(PathContext);
|
|
143
|
+
if (ctx === null) {
|
|
144
|
+
throw new Error("usePathContext must be used within a <PathProvider>.");
|
|
145
|
+
}
|
|
146
|
+
return ctx as UsePathReturn<TData>;
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
// ---------------------------------------------------------------------------
|
|
150
|
+
// Default UI — PathShell
|
|
151
|
+
// ---------------------------------------------------------------------------
|
|
152
|
+
|
|
153
|
+
export interface PathShellProps {
|
|
154
|
+
/** The path definition to drive. */
|
|
155
|
+
path: PathDefinition;
|
|
156
|
+
/** Map of step ID → content. The shell renders `steps[snapshot.stepId]` for the current step. */
|
|
157
|
+
steps: Record<string, ReactNode>;
|
|
158
|
+
/** Initial data passed to `engine.start()`. */
|
|
159
|
+
initialData?: PathData;
|
|
160
|
+
/** If true, the path is started automatically on mount. Defaults to `true`. */
|
|
161
|
+
autoStart?: boolean;
|
|
162
|
+
/** Called when the path completes. Receives the final data. */
|
|
163
|
+
onComplete?: (data: PathData) => void;
|
|
164
|
+
/** Called when the path is cancelled. Receives the data at time of cancellation. */
|
|
165
|
+
onCancel?: (data: PathData) => void;
|
|
166
|
+
/** Called for every engine event. */
|
|
167
|
+
onEvent?: (event: PathEvent) => void;
|
|
168
|
+
/** Label for the Back button. Defaults to `"Back"`. */
|
|
169
|
+
backLabel?: string;
|
|
170
|
+
/** Label for the Next button. Defaults to `"Next"`. */
|
|
171
|
+
nextLabel?: string;
|
|
172
|
+
/** Label for the Finish button (shown on the last step). Defaults to `"Finish"`. */
|
|
173
|
+
finishLabel?: string;
|
|
174
|
+
/** Label for the Cancel button. Defaults to `"Cancel"`. */
|
|
175
|
+
cancelLabel?: string;
|
|
176
|
+
/** If true, hide the Cancel button. Defaults to `false`. */
|
|
177
|
+
hideCancel?: boolean;
|
|
178
|
+
/** If true, hide the progress indicator. Defaults to `false`. */
|
|
179
|
+
hideProgress?: boolean;
|
|
180
|
+
/** Optional extra CSS class on the root element. */
|
|
181
|
+
className?: string;
|
|
182
|
+
/** Render prop to replace the entire header (progress area). Receives the snapshot. */
|
|
183
|
+
renderHeader?: (snapshot: PathSnapshot) => ReactNode;
|
|
184
|
+
/** Render prop to replace the entire footer (navigation area). Receives the snapshot and actions. */
|
|
185
|
+
renderFooter?: (snapshot: PathSnapshot, actions: PathShellActions) => ReactNode;
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
export interface PathShellActions {
|
|
189
|
+
next: () => void;
|
|
190
|
+
previous: () => void;
|
|
191
|
+
cancel: () => void;
|
|
192
|
+
goToStep: (stepId: string) => void;
|
|
193
|
+
setData: (key: string, value: unknown) => void;
|
|
194
|
+
}
|
|
195
|
+
|
|
196
|
+
/**
|
|
197
|
+
* Default UI shell that renders a progress indicator, step content, and navigation
|
|
198
|
+
* buttons. Pass a `steps` map to define per-step content.
|
|
199
|
+
*
|
|
200
|
+
* ```tsx
|
|
201
|
+
* <PathShell
|
|
202
|
+
* path={myPath}
|
|
203
|
+
* initialData={{ name: "" }}
|
|
204
|
+
* onComplete={handleDone}
|
|
205
|
+
* steps={{
|
|
206
|
+
* details: <DetailsForm />,
|
|
207
|
+
* review: <ReviewPanel />,
|
|
208
|
+
* }}
|
|
209
|
+
* />
|
|
210
|
+
* ```
|
|
211
|
+
*/
|
|
212
|
+
export function PathShell({
|
|
213
|
+
path: pathDef,
|
|
214
|
+
steps,
|
|
215
|
+
initialData = {},
|
|
216
|
+
autoStart = true,
|
|
217
|
+
onComplete,
|
|
218
|
+
onCancel,
|
|
219
|
+
onEvent,
|
|
220
|
+
backLabel = "Back",
|
|
221
|
+
nextLabel = "Next",
|
|
222
|
+
finishLabel = "Finish",
|
|
223
|
+
cancelLabel = "Cancel",
|
|
224
|
+
hideCancel = false,
|
|
225
|
+
hideProgress = false,
|
|
226
|
+
className,
|
|
227
|
+
renderHeader,
|
|
228
|
+
renderFooter,
|
|
229
|
+
}: PathShellProps): ReactElement {
|
|
230
|
+
const pathReturn = usePath({
|
|
231
|
+
onEvent(event) {
|
|
232
|
+
onEvent?.(event);
|
|
233
|
+
if (event.type === "completed") onComplete?.(event.data);
|
|
234
|
+
if (event.type === "cancelled") onCancel?.(event.data);
|
|
235
|
+
}
|
|
236
|
+
});
|
|
237
|
+
|
|
238
|
+
const { snapshot, start, next, previous, cancel, goToStep, setData } = pathReturn;
|
|
239
|
+
|
|
240
|
+
// Auto-start on mount
|
|
241
|
+
const startedRef = useRef(false);
|
|
242
|
+
useEffect(() => {
|
|
243
|
+
if (autoStart && !startedRef.current) {
|
|
244
|
+
startedRef.current = true;
|
|
245
|
+
start(pathDef, initialData);
|
|
246
|
+
}
|
|
247
|
+
// eslint-disable-next-line react-hooks/exhaustive-deps
|
|
248
|
+
}, []);
|
|
249
|
+
|
|
250
|
+
// Look up step content from the steps map
|
|
251
|
+
const stepContent = snapshot ? (steps[snapshot.stepId] ?? null) : null;
|
|
252
|
+
|
|
253
|
+
if (!snapshot) {
|
|
254
|
+
return createElement(PathContext.Provider, { value: pathReturn },
|
|
255
|
+
createElement("div", { className: cls("pw-shell", className) },
|
|
256
|
+
createElement("div", { className: "pw-shell__empty" },
|
|
257
|
+
createElement("p", null, "No active path."),
|
|
258
|
+
!autoStart && createElement("button", {
|
|
259
|
+
type: "button",
|
|
260
|
+
className: "pw-shell__start-btn",
|
|
261
|
+
onClick: () => start(pathDef, initialData)
|
|
262
|
+
}, "Start")
|
|
263
|
+
)
|
|
264
|
+
)
|
|
265
|
+
);
|
|
266
|
+
}
|
|
267
|
+
|
|
268
|
+
const actions: PathShellActions = { next, previous, cancel, goToStep, setData };
|
|
269
|
+
|
|
270
|
+
return createElement(PathContext.Provider, { value: pathReturn },
|
|
271
|
+
createElement("div", { className: cls("pw-shell", className) },
|
|
272
|
+
// Header — progress indicator
|
|
273
|
+
!hideProgress && (renderHeader
|
|
274
|
+
? renderHeader(snapshot)
|
|
275
|
+
: defaultHeader(snapshot)),
|
|
276
|
+
// Body — step content
|
|
277
|
+
createElement("div", { className: "pw-shell__body" }, stepContent),
|
|
278
|
+
// Footer — navigation buttons
|
|
279
|
+
renderFooter
|
|
280
|
+
? renderFooter(snapshot, actions)
|
|
281
|
+
: defaultFooter(snapshot, actions, {
|
|
282
|
+
backLabel, nextLabel, finishLabel, cancelLabel, hideCancel
|
|
283
|
+
})
|
|
284
|
+
)
|
|
285
|
+
);
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
// ---------------------------------------------------------------------------
|
|
289
|
+
// Default header (progress indicator)
|
|
290
|
+
// ---------------------------------------------------------------------------
|
|
291
|
+
|
|
292
|
+
function defaultHeader(snapshot: PathSnapshot): ReactElement {
|
|
293
|
+
return createElement("div", { className: "pw-shell__header" },
|
|
294
|
+
createElement("div", { className: "pw-shell__steps" },
|
|
295
|
+
...snapshot.steps.map((step, i) =>
|
|
296
|
+
createElement("div", {
|
|
297
|
+
key: step.id,
|
|
298
|
+
className: cls("pw-shell__step", `pw-shell__step--${step.status}`)
|
|
299
|
+
},
|
|
300
|
+
createElement("span", { className: "pw-shell__step-dot" },
|
|
301
|
+
step.status === "completed" ? "✓" : String(i + 1)
|
|
302
|
+
),
|
|
303
|
+
createElement("span", { className: "pw-shell__step-label" },
|
|
304
|
+
step.title ?? step.id
|
|
305
|
+
)
|
|
306
|
+
)
|
|
307
|
+
)
|
|
308
|
+
),
|
|
309
|
+
createElement("div", { className: "pw-shell__track" },
|
|
310
|
+
createElement("div", {
|
|
311
|
+
className: "pw-shell__track-fill",
|
|
312
|
+
style: { width: `${snapshot.progress * 100}%` }
|
|
313
|
+
})
|
|
314
|
+
)
|
|
315
|
+
);
|
|
316
|
+
}
|
|
317
|
+
|
|
318
|
+
// ---------------------------------------------------------------------------
|
|
319
|
+
// Default footer (navigation buttons)
|
|
320
|
+
// ---------------------------------------------------------------------------
|
|
321
|
+
|
|
322
|
+
interface FooterLabels {
|
|
323
|
+
backLabel: string;
|
|
324
|
+
nextLabel: string;
|
|
325
|
+
finishLabel: string;
|
|
326
|
+
cancelLabel: string;
|
|
327
|
+
hideCancel: boolean;
|
|
328
|
+
}
|
|
329
|
+
|
|
330
|
+
function defaultFooter(
|
|
331
|
+
snapshot: PathSnapshot,
|
|
332
|
+
actions: PathShellActions,
|
|
333
|
+
labels: FooterLabels
|
|
334
|
+
): ReactElement {
|
|
335
|
+
return createElement("div", { className: "pw-shell__footer" },
|
|
336
|
+
createElement("div", { className: "pw-shell__footer-left" },
|
|
337
|
+
!snapshot.isFirstStep && createElement("button", {
|
|
338
|
+
type: "button",
|
|
339
|
+
className: "pw-shell__btn pw-shell__btn--back",
|
|
340
|
+
disabled: snapshot.isNavigating || !snapshot.canMovePrevious,
|
|
341
|
+
onClick: actions.previous
|
|
342
|
+
}, labels.backLabel)
|
|
343
|
+
),
|
|
344
|
+
createElement("div", { className: "pw-shell__footer-right" },
|
|
345
|
+
!labels.hideCancel && createElement("button", {
|
|
346
|
+
type: "button",
|
|
347
|
+
className: "pw-shell__btn pw-shell__btn--cancel",
|
|
348
|
+
disabled: snapshot.isNavigating,
|
|
349
|
+
onClick: actions.cancel
|
|
350
|
+
}, labels.cancelLabel),
|
|
351
|
+
createElement("button", {
|
|
352
|
+
type: "button",
|
|
353
|
+
className: "pw-shell__btn pw-shell__btn--next",
|
|
354
|
+
disabled: snapshot.isNavigating || !snapshot.canMoveNext,
|
|
355
|
+
onClick: actions.next
|
|
356
|
+
}, snapshot.isLastStep ? labels.finishLabel : labels.nextLabel)
|
|
357
|
+
)
|
|
358
|
+
);
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
// ---------------------------------------------------------------------------
|
|
362
|
+
// Helpers
|
|
363
|
+
// ---------------------------------------------------------------------------
|
|
364
|
+
|
|
365
|
+
|
|
366
|
+
function cls(...parts: (string | undefined | false | null)[]): string {
|
|
367
|
+
return parts.filter(Boolean).join(" ");
|
|
368
|
+
}
|