@daltonr/pathwrite-svelte 0.13.1 → 0.14.0

package/src/index.svelte.ts

@@ -1,11 +1,5 @@
 import { onDestroy, getContext, setContext } from "svelte";
-import type {
-  PathData,
-  PathDefinition,
-  PathEngine,
-  PathEvent,
-  PathSnapshot
-} from "@daltonr/pathwrite-core";
+import type { PathData, PathDefinition, PathEngine, PathEvent, PathSnapshot } from "@daltonr/pathwrite-core";
 import { PathEngine as PathEngineClass } from "@daltonr/pathwrite-core";
 
 // Re-export core utilities and types for convenience
@@ -17,18 +11,19 @@ export type {
   PathEngine,
   PathEvent,
   PathSnapshot,
+  StepStatus,
   PathStep,
   PathStepContext,
   ProgressLayout,
   RootProgress,
-  SerializedPathState
+  SerializedPathState,
 } from "@daltonr/pathwrite-core";
 
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
 
-export interface UsePathOptions {
+export interface UsePathOptions<TData extends PathData = PathData> {
   /**
    * An externally-managed `PathEngine` to subscribe to — for example, the engine
    * returned by `restoreOrStart()` from `@daltonr/pathwrite-store`.
@@ -45,23 +40,27 @@ export interface UsePathOptions {
    * later (e.g. from an async `restoreOrStart()`) or is swapped is adopted —
    * the hook re-subscribes and re-seeds its snapshot from the new engine.
    */
-  engine?: PathEngine;
+  engine?: PathEngine<TData>;
   /** Called for every engine event (stateChanged, completed, cancelled, resumed). */
-  onEvent?: (event: PathEvent) => void;
+  onEvent?: (event: PathEvent<TData>) => void;
 }
 
 export interface UsePathReturn<TData extends PathData = PathData> {
   /**
-   * Current path snapshot, or `null` when no path is active. Reactive via `$state`.
+   * Current path snapshot, or `null` when no path is active. Reactive via `$state.raw`.
    *
    * ⚠️ **Do not destructure.** `const { snapshot } = usePath()` captures the value
    * once and loses reactivity. Always access as `path.snapshot`.
    */
   readonly snapshot: PathSnapshot<TData> | null;
   /** Start (or restart) a path. */
-  start: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
-  /** 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. */
-  startSubPath: (path: PathDefinition<any>, initialData?: PathData, meta?: Record<string, unknown>) => Promise<void>;
+  start: (path: PathDefinition<TData>, initialData?: Partial<TData>) => Promise<void>;
+  /** Push a sub-path onto the stack. Requires an active path. A sub-path has its own data, so any definition is accepted. Pass an optional `meta` object for correlation — it is returned unchanged to the parent step's `onSubPathComplete` / `onSubPathCancel` hooks. */
+  startSubPath: (
+    path: PathDefinition,
+    initialData?: PathData,
+    meta?: Record<string, unknown>
+  ) => Promise<void>;
   /** Advance one step. Completes the path on the last step. */
   next: () => Promise<void>;
   /** 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. */
@@ -150,21 +149,24 @@ export interface UsePathReturn<TData extends PathData = PathData> {
  * ```
  */
 export function usePath<TData extends PathData = PathData>(
-  options?: UsePathOptions
+  options?: UsePathOptions<TData>
 ): UsePathReturn<TData> {
-  let ownEngine: PathEngine | null = null;
-  const resolveEngine = (): PathEngine => options?.engine ?? (ownEngine ??= new PathEngineClass());
+  let ownEngine: PathEngine<TData> | null = null;
+  const resolveEngine = (): PathEngine<TData> =>
+    options?.engine ?? (ownEngine ??= new PathEngineClass<TData>());
   let engine = resolveEngine();
 
-  let _snapshot: PathSnapshot<TData> | null = $state(
-    engine.snapshot() as PathSnapshot<TData> | null
-  );
+  // `$state.raw`, not `$state`: snapshots are immutable values the engine
+  // replaces wholesale on every change and nothing mutates them in place, so a
+  // deep proxy over each one (and its `data`) would be pure overhead. Every
+  // update below reassigns the whole value, which is what `$state.raw` tracks.
+  let _snapshot: PathSnapshot<TData> | null = $state.raw(engine.snapshot());
 
-  const onEngineEvent = (event: PathEvent): void => {
+  const onEngineEvent = (event: PathEvent<TData>): void => {
     if (event.type === "stateChanged" || event.type === "resumed") {
-      _snapshot = event.snapshot as PathSnapshot<TData>;
+      _snapshot = event.snapshot;
     } else if (event.type === "completed" || event.type === "cancelled") {
-      _snapshot = engine.snapshot() as PathSnapshot<TData> | null;
+      _snapshot = engine.snapshot();
     }
     options?.onEvent?.(event);
   };
@@ -179,19 +181,22 @@ export function usePath<TData extends PathData = PathData>(
       if (next === engine) return;
       unsubscribe();
       engine = next;
-      _snapshot = engine.snapshot() as PathSnapshot<TData> | null;
+      _snapshot = engine.snapshot();
       unsubscribe = engine.subscribe(onEngineEvent);
     });
   });
 
   // Auto-cleanup when component is destroyed
-  onDestroy(() => { unsubscribe(); stopWatching(); });
+  onDestroy(() => {
+    unsubscribe();
+    stopWatching();
+  });
 
-  const start = (path: PathDefinition<any>, initialData: PathData = {}): Promise<void> =>
+  const start = (path: PathDefinition<TData>, initialData: Partial<TData> = {}): Promise<void> =>
     engine.start(path, initialData);
 
   const startSubPath = (
-    path: PathDefinition<any>,
+    path: PathDefinition,
     initialData: PathData = {},
     meta?: Record<string, unknown>
   ): Promise<void> => engine.startSubPath(path, initialData, meta);
@@ -200,11 +205,13 @@ export function usePath<TData extends PathData = PathData>(
   const previous = (): Promise<void> => engine.previous();
   const cancel = (): Promise<void> => engine.cancel();
 
-  const goToStep = (stepId: string, options?: { validateOnLeave?: boolean }): Promise<void> => engine.goToStep(stepId, options);
-  const goToStepChecked = (stepId: string, options?: { validateOnLeave?: boolean }): Promise<void> => engine.goToStepChecked(stepId, options);
+  const goToStep = (stepId: string, options?: { validateOnLeave?: boolean }): Promise<void> =>
+    engine.goToStep(stepId, options);
+  const goToStepChecked = (stepId: string, options?: { validateOnLeave?: boolean }): Promise<void> =>
+    engine.goToStepChecked(stepId, options);
 
-  const setData = (<K extends string & keyof TData>(key: K, value: TData[K]): Promise<void> =>
-    engine.setData(key, value as unknown)) as UsePathReturn<TData>["setData"];
+  const setData = <K extends string & keyof TData>(key: K, value: TData[K]): Promise<void> =>
+    engine.setData(key, value);
 
   const resetStep = (): Promise<void> => engine.resetStep();
 
@@ -215,7 +222,9 @@ export function usePath<TData extends PathData = PathData>(
   const validate = (): void => engine.validate();
 
   return {
-    get snapshot() { return _snapshot; },
+    get snapshot() {
+      return _snapshot;
+    },
     start,
     startSubPath,
     next,
@@ -228,7 +237,7 @@ export function usePath<TData extends PathData = PathData>(
     restart,
     retry,
     suspend,
-    validate
+    validate,
   };
 }
 
@@ -263,7 +272,10 @@ const PATH_CONTEXT_KEY = Symbol("pathwrite-context");
  * returns (derived from `UsePathReturn`, so the two cannot drift apart) plus
  * the `services` object given to `<PathShell>`.
  */
-export interface PathContext<TData extends PathData = PathData, TServices = unknown> extends UsePathReturn<TData> {
+export interface PathContext<
+  TData extends PathData = PathData,
+  TServices = unknown,
+> extends UsePathReturn<TData> {
   services: TServices;
 }
 
@@ -287,7 +299,10 @@ export interface PathContext<TData extends PathData = PathData, TServices = unkn
  * <button onclick={ctx.next}>Next</button>
  * ```
  */
-export function usePathContext<TData extends PathData = PathData, TServices = unknown>(): PathContext<TData, TServices> {
+export function usePathContext<TData extends PathData = PathData, TServices = unknown>(): PathContext<
+  TData,
+  TServices
+> {
   const ctx = getContext<PathContext<TData, TServices>>(PATH_CONTEXT_KEY);
   if (!ctx) {
     throw new Error(
@@ -302,7 +317,9 @@ export function usePathContext<TData extends PathData = PathData, TServices = un
  * Internal: Set the PathContext for child components.
  * Used by PathShell component.
  */
-export function setPathContext<TData extends PathData = PathData, TServices = unknown>(ctx: PathContext<TData, TServices>): void {
+export function setPathContext<TData extends PathData = PathData, TServices = unknown>(
+  ctx: PathContext<TData, TServices>
+): void {
   setContext(PATH_CONTEXT_KEY, ctx);
 }
 
@@ -312,7 +329,8 @@ export function setPathContext<TData extends PathData = PathData, TServices = un
  * the outer shell's context for `restoreKey` auto-wiring — must be called
  * before `setPathContext()` so it reads the parent rather than self.
  */
-export function getPathContextOrNull<TData extends PathData = PathData, TServices = unknown>(): PathContext<TData, TServices> | undefined {
+export function getPathContextOrNull<TData extends PathData = PathData, TServices = unknown>():
+  PathContext<TData, TServices> | undefined {
   return getContext<PathContext<TData, TServices>>(PATH_CONTEXT_KEY);
 }
 
@@ -351,15 +369,15 @@ export function bindData<TData extends PathData, K extends string & keyof TData>
     },
     set(value: TData[K]) {
       setData(key, value);
-    }
+    },
   };
 }
 
 /**
  * Converts a hyphenated step ID to camelCase.
- * Used internally by PathShell to resolve step snippets when a step ID contains
- * hyphens (e.g. "cover-letter" → "coverLetter"), since Svelte prop names must
- * be valid JavaScript identifiers.
+ * Used internally by PathShell as a fallback key into its `steps` record, so a
+ * hyphenated step ID (e.g. "cover-letter") also resolves an entry registered
+ * under its camelCase form ("coverLetter").
  */
 export function stepIdToCamelCase(id: string): string {
   return id.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
@@ -367,4 +385,3 @@ export function stepIdToCamelCase(id: string): string {
 
 // Export PathShell component
 export { default as PathShell } from "./PathShell.svelte";
-