@daltonr/pathwrite-svelte 0.9.0 → 0.10.1

package/src/PathShell.svelte

@@ -1,13 +1,9 @@
 <script lang="ts">
   import { onMount } from 'svelte';
-  import { usePath, setPathContext } from './index.svelte.js';
+  import { usePath, setPathContext, formatFieldKey, errorPhaseMessage, stepIdToCamelCase } from './index.svelte.js';
   import type { PathDefinition, PathData, PathEngine, PathSnapshot, ProgressLayout } from './index.svelte.js';
   import type { Snippet, Component } from 'svelte';
 
-  /** Converts a camelCase or lowercase field key to a display label. */
-  function formatFieldKey(key: string): string {
-    return key.replace(/([A-Z])/g, ' $1').replace(/^./, c => c.toUpperCase()).trim();
-  }
 
   interface Props {
     path?: PathDefinition<any>;
@@ -17,6 +13,7 @@
     backLabel?: string;
     nextLabel?: string;
     completeLabel?: string;
+    loadingLabel?: string;
     cancelLabel?: string;
     hideCancel?: boolean;
     hideProgress?: boolean;
@@ -42,6 +39,11 @@
      * - "activeOnly": Only the active (sub-path) bar — root bar hidden.
      */
     progressLayout?: ProgressLayout;
+    /**
+     * Services object passed through context to all step components.
+     * Step components access it via `usePathContext<TData, TServices>()`.
+     */
+    services?: unknown;
     // Callback props replace event dispatching in Svelte 5
     oncomplete?: (data: PathData) => void;
     oncancel?: (data: PathData) => void;
@@ -61,12 +63,14 @@
     backLabel = 'Previous',
     nextLabel = 'Next',
     completeLabel = 'Complete',
+    loadingLabel = undefined,
     cancelLabel = 'Cancel',
     hideCancel = false,
     hideProgress = false,
     footerLayout = 'auto',
     validationDisplay = 'summary',
     progressLayout = 'merged',
+    services = null,
     oncomplete,
     oncancel,
     onevent,
@@ -77,7 +81,7 @@
 
   // Initialize path engine
   const pathReturn = usePath({
-    engine: engineProp,
+    get engine() { return engineProp; },
     onEvent: (event) => {
       onevent?.(event);
       if (event.type === 'completed') oncomplete?.(event.data);
@@ -85,7 +89,7 @@
     }
   });
 
-  const { start, next, previous, cancel, goToStep, goToStepChecked, setData, restart: restartFn } = pathReturn;
+  const { start, next, previous, cancel, goToStep, goToStepChecked, setData, restart: restartFn, retry, suspend } = pathReturn;
 
   // Provide context for child step components
   setPathContext({
@@ -96,7 +100,10 @@
     goToStep,
     goToStepChecked,
     setData,
-    restart: () => restartFn(path, initialData)
+    restart: () => restartFn(path, initialData),
+    retry,
+    suspend,
+    get services() { return services; },
   });
 
   // Auto-start the path when no external engine is provided
@@ -108,8 +115,16 @@
     }
   });
 
+  function warnMissingStep(stepId: string): void {
+    const camel = stepIdToCamelCase(stepId);
+    const hint = camel !== stepId
+      ? ` No snippet found for "${stepId}" or its camelCase form "${camel}". If your step ID contains hyphens, pass the snippet as a camelCase prop: ${camel}={YourComponent}.`
+      : ` No snippet found for "${stepId}".`;
+    console.warn(`[PathShell]${hint}`);
+  }
+
   let snap = $derived(pathReturn.snapshot);
-  let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData) });
+  let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restartFn(path, initialData), retry, suspend });
 
   // Auto-detect footer layout: single-step top-level paths use "form", everything else uses "wizard"
   let resolvedFooterLayout = $derived(
@@ -187,13 +202,22 @@
 
     <!-- Body: current step rendered via named snippet.
          Prefer formId (inner step id of a StepChoice) so consumers can
-         register snippets by inner step ids directly. -->
+         register snippets by inner step ids directly.
+         Hyphenated step IDs (e.g. "cover-letter") are normalised to camelCase
+         ("coverLetter") as a fallback, since Svelte props must be valid JS
+         identifiers. -->
     <div class="pw-shell__body">
       {#if snap.formId && stepSnippets[snap.formId]}
-        <svelte:component this={stepSnippets[snap.formId]} />
+        {@const StepComponent = stepSnippets[snap.formId]}
+        <StepComponent />
       {:else if stepSnippets[snap.stepId]}
-        <svelte:component this={stepSnippets[snap.stepId]} />
+        {@const StepComponent = stepSnippets[snap.stepId]}
+        <StepComponent />
+      {:else if stepSnippets[stepIdToCamelCase(snap.formId ?? snap.stepId)]}
+        {@const StepComponent = stepSnippets[stepIdToCamelCase(snap.formId ?? snap.stepId)]}
+        <StepComponent />
       {:else}
+        {warnMissingStep(snap.stepId)}
         <p>No content for step "{snap.stepId}"</p>
       {/if}
     </div>
@@ -220,8 +244,36 @@
       </ul>
     {/if}
 
+    <!-- Blocking error — guard returned { allowed: false, reason } -->
+    {#if validationDisplay !== 'inline' && snap.hasAttemptedNext && snap.blockingError}
+      <p class="pw-shell__blocking-error">{snap.blockingError}</p>
+    {/if}
+
+    <!-- Error panel: replaces footer when an async operation has failed -->
+    {#if snap.status === "error" && snap.error}
+      {@const err = snap.error}
+      {@const escalated = err.retryCount >= 2}
+      <div class="pw-shell__error">
+        <div class="pw-shell__error-title">{escalated ? "Still having trouble." : "Something went wrong."}</div>
+        <div class="pw-shell__error-message">{errorPhaseMessage(err.phase)}{err.message ? ` ${err.message}` : ""}</div>
+        <div class="pw-shell__error-actions">
+          {#if !escalated}
+            <button type="button" class="pw-shell__btn pw-shell__btn--retry" onclick={retry}>Try again</button>
+          {/if}
+          {#if snap.hasPersistence}
+            <button
+              type="button"
+              class="pw-shell__btn {escalated ? 'pw-shell__btn--retry' : 'pw-shell__btn--suspend'}"
+              onclick={suspend}
+            >Save and come back later</button>
+          {/if}
+          {#if escalated && !snap.hasPersistence}
+            <button type="button" class="pw-shell__btn pw-shell__btn--retry" onclick={retry}>Try again</button>
+          {/if}
+        </div>
+      </div>
     <!-- Footer: navigation buttons (overridable via footer snippet) -->
-    {#if footer}
+    {:else if footer}
       {@render footer(snap, actions)}
     {:else}
       <div class="pw-shell__footer">
@@ -231,7 +283,7 @@
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              disabled={snap.isNavigating}
+              disabled={snap.status !== "idle"}
               onclick={cancel}
             >
               {cancelLabel}
@@ -241,7 +293,7 @@
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
-              disabled={snap.isNavigating || !snap.canMovePrevious}
+              disabled={snap.status !== "idle" || !snap.canMovePrevious}
               onclick={previous}
             >
               {backLabel}
@@ -254,7 +306,7 @@
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              disabled={snap.isNavigating}
+              disabled={snap.status !== "idle"}
               onclick={cancel}
             >
               {cancelLabel}
@@ -264,10 +316,11 @@
           <button
             type="button"
             class="pw-shell__btn pw-shell__btn--next"
-            disabled={snap.isNavigating}
+            class:pw-shell__btn--loading={snap.status !== "idle"}
+            disabled={snap.status !== "idle"}
             onclick={next}
           >
-            {snap.isLastStep ? completeLabel : nextLabel}
+            {snap.status !== 'idle' && loadingLabel ? loadingLabel : snap.isLastStep ? completeLabel : nextLabel}
           </button>
         </div>
       </div>

package/src/index.svelte.ts

@@ -8,7 +8,8 @@ import type {
 } from "@daltonr/pathwrite-core";
 import { PathEngine as PathEngineClass } from "@daltonr/pathwrite-core";
 
-// Re-export core types for convenience
+// Re-export core utilities and types for convenience
+export { formatFieldKey, errorPhaseMessage } from "@daltonr/pathwrite-core";
 export type {
   PathData,
   FieldErrors,
@@ -75,6 +76,10 @@ export interface UsePathReturn<TData extends PathData = PathData> {
    * Use for "Start over" / retry flows without remounting the component.
    */
   restart: () => Promise<void>;
+  /** Re-runs the operation that set `snapshot.error`. Increments `retryCount` on repeated failure. No-op when there is no pending error. */
+  retry: () => Promise<void>;
+  /** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
+  suspend: () => Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -180,6 +185,8 @@ export function usePath<TData extends PathData = PathData>(
   const resetStep = (): Promise<void> => engine.resetStep();
 
   const restart = (): Promise<void> => engine.restart();
+  const retry = (): Promise<void> => engine.retry();
+  const suspend = (): Promise<void> => engine.suspend();
 
   return {
     get snapshot() { return _snapshot; },
@@ -192,7 +199,9 @@ export function usePath<TData extends PathData = PathData>(
     goToStepChecked,
     setData,
     resetStep,
-    restart
+    restart,
+    retry,
+    suspend
   };
 }
 
@@ -202,7 +211,7 @@ export function usePath<TData extends PathData = PathData>(
 
 const PATH_CONTEXT_KEY = Symbol("pathwrite-context");
 
-export interface PathContext<TData extends PathData = PathData> {
+export interface PathContext<TData extends PathData = PathData, TServices = unknown> {
   readonly snapshot: PathSnapshot<TData>;
   next: () => Promise<void>;
   previous: () => Promise<void>;
@@ -212,18 +221,30 @@ export interface PathContext<TData extends PathData = PathData> {
   setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
   resetStep: () => Promise<void>;
   restart: () => Promise<void>;
+  /** Re-run the operation that set `snapshot.error`. */
+  retry: () => Promise<void>;
+  /** Pause with intent to return, preserving all state. Emits `suspended`. */
+  suspend: () => Promise<void>;
+  /**
+   * Services object passed through context from `PathShell`.
+   * Typed as `TServices` when `usePathContext<TData, TServices>()` is used.
+   */
+  services: TServices;
 }
 
 /**
- * Get the PathContext from a parent PathShell component.
+ * Access the nearest `PathShell`'s path instance and optional services object.
  * Use this inside step components to access the path engine.
  *
+ * - `TData` narrows `ctx.snapshot?.data`
+ * - `TServices` types the `services` value — must match what was passed to `PathShell`
+ *
  * @example
  * ```svelte
  * <script lang="ts">
- *   import { getPathContext } from '@daltonr/pathwrite-svelte';
+ *   import { usePathContext } from '@daltonr/pathwrite-svelte';
  *
- *   const ctx = getPathContext();
+ *   const ctx = usePathContext();
  * </script>
  *
  * <input value={ctx.snapshot?.data.name}
@@ -231,11 +252,11 @@ export interface PathContext<TData extends PathData = PathData> {
  * <button onclick={ctx.next}>Next</button>
  * ```
  */
-export function getPathContext<TData extends PathData = PathData>(): PathContext<TData> {
-  const ctx = getContext<PathContext<TData>>(PATH_CONTEXT_KEY);
+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(
-      "getPathContext() must be called from a component inside a <PathShell>. " +
+      "usePathContext() must be called from a component inside a <PathShell>. " +
         "Ensure the PathShell component is a parent in the component tree."
     );
   }
@@ -246,7 +267,7 @@ export function getPathContext<TData extends PathData = PathData>(): PathContext
  * Internal: Set the PathContext for child components.
  * Used by PathShell component.
  */
-export function setPathContext<TData extends PathData = PathData>(ctx: PathContext<TData>): void {
+export function setPathContext<TData extends PathData = PathData, TServices = unknown>(ctx: PathContext<TData, TServices>): void {
   setContext(PATH_CONTEXT_KEY, ctx);
 }
 
@@ -289,6 +310,16 @@ export function bindData<TData extends PathData, K extends string & keyof TData>
   };
 }
 
+/**
+ * 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.
+ */
+export function stepIdToCamelCase(id: string): string {
+  return id.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+}
+
 // Export PathShell component
 export { default as PathShell } from "./PathShell.svelte";