@daltonr/pathwrite-react 0.9.0 → 0.10.1

package/src/index.ts

@@ -17,7 +17,9 @@ import {
   PathEvent,
   PathSnapshot,
   ProgressLayout,
-  RootProgress
+  RootProgress,
+  formatFieldKey,
+  errorPhaseMessage,
 } from "@daltonr/pathwrite-core";
 
 // ---------------------------------------------------------------------------
@@ -67,11 +69,29 @@ export interface UsePathReturn<TData extends PathData = PathData> {
    * Use for "Start over" / retry flows without remounting the component.
    */
   restart: () => void;
+  /**
+   * Re-runs the operation that set `snapshot.error`. Increments `snapshot.error.retryCount`
+   * on repeated failure so shells can escalate from "Try again" to "Come back later".
+   * No-op when there is no pending error.
+   */
+  retry: () => void;
+  /**
+   * Pauses the path with intent to return. Emits a `suspended` event that the application
+   * listens for to dismiss the wizard UI. All state and data are preserved.
+   */
+  suspend: () => void;
 }
 
 export type PathProviderProps = PropsWithChildren<{
   /** Forwarded to the internal usePath hook. */
   onEvent?: (event: PathEvent) => void;
+  /**
+   * Services object passed through context to all step components.
+   * Step components access it via `usePathContext<TData, TServices>()`.
+   * Typed as `unknown` here so `PathProvider` stays non-generic — provide a
+   * typed services interface via the `TServices` type parameter on `usePathContext`.
+   */
+  services?: unknown;
 }>;
 
 // ---------------------------------------------------------------------------
@@ -160,37 +180,58 @@ export function usePath<TData extends PathData = PathData>(options?: UsePathOpti
 
   const restart = useCallback(() => engine.restart(), [engine]);
 
-  return { snapshot, start, startSubPath, next, previous, cancel, goToStep, goToStepChecked, setData, resetStep, restart };
+  const retry = useCallback(() => engine.retry(), [engine]);
+
+  const suspend = useCallback(() => engine.suspend(), [engine]);
+
+  return { snapshot, start, startSubPath, next, previous, cancel, goToStep, goToStepChecked, setData, resetStep, restart, retry, suspend };
 }
 
 // ---------------------------------------------------------------------------
 // Context + Provider
 // ---------------------------------------------------------------------------
 
-const PathContext = createContext<UsePathReturn | null>(null);
+interface PathContextValue {
+  path: UsePathReturn;
+  services: unknown;
+}
+
+const PathContext = createContext<PathContextValue | null>(null);
 
 /**
  * Provides a single `usePath` instance to all descendants.
  * Consume with `usePathContext()`.
  */
-export function PathProvider({ children, onEvent }: PathProviderProps): ReactElement {
+export function PathProvider({ children, onEvent, services }: PathProviderProps): ReactElement {
   const path = usePath({ onEvent });
-  return createElement(PathContext.Provider, { value: path }, children);
+  return createElement(PathContext.Provider, { value: { path, services: services ?? null } }, children);
 }
 
 /**
- * Access the nearest `PathProvider`'s path instance.
- * Throws if used outside of a `<PathProvider>`.
+ * Access the nearest `PathProvider`'s path instance and optional services object.
+ * Throws if used outside of a `<PathProvider>` or `<PathShell>`.
+ *
+ * Both generics are type-level assertions, not runtime guarantees:
+ * - `TData` narrows `snapshot.data`
+ * - `TServices` types the `services` value — must match what was passed to `PathShell` or `PathProvider`
  *
- * The optional generic narrows `snapshot.data` for convenience — it is a
- * **type-level assertion**, not a runtime guarantee.
+ * @example
+ * ```tsx
+ * function OfficeStep() {
+ *   const { snapshot, services } = usePathContext<HiringData, HiringServices>();
+ *   // services is typed as HiringServices
+ * }
+ * ```
  */
-export function usePathContext<TData extends PathData = PathData>(): Omit<UsePathReturn<TData>, "snapshot"> & { snapshot: PathSnapshot<TData> } {
+export function usePathContext<TData extends PathData = PathData, TServices = unknown>(): Omit<UsePathReturn<TData>, "snapshot"> & { snapshot: PathSnapshot<TData>; services: TServices } {
   const ctx = useContext(PathContext);
   if (ctx === null) {
     throw new Error("usePathContext must be used within a <PathProvider>.");
   }
-  return ctx as Omit<UsePathReturn<TData>, "snapshot"> & { snapshot: PathSnapshot<TData> };
+  return {
+    ...(ctx.path as unknown as Omit<UsePathReturn<TData>, "snapshot"> & { snapshot: PathSnapshot<TData> }),
+    services: ctx.services as TServices
+  };
 }
 
 // ---------------------------------------------------------------------------
@@ -238,11 +279,6 @@ export function useField<TData extends PathData, K extends string & keyof TData>
 // Helpers
 // ---------------------------------------------------------------------------
 
-/** Converts a camelCase or lowercase field key to a display label.
- *  e.g. "firstName" → "First Name", "email" → "Email" */
-function formatFieldKey(key: string): string {
-  return key.replace(/([A-Z])/g, " $1").replace(/^./, c => c.toUpperCase()).trim();
-}
 
 // ---------------------------------------------------------------------------
 // Default UI — PathShell
@@ -275,6 +311,8 @@ export interface PathShellProps {
   nextLabel?: string;
   /** Label for the Complete button (shown on the last step). Defaults to `"Complete"`. */
   completeLabel?: string;
+  /** Label shown on the Next/Complete button while an async operation is in progress. Defaults to `undefined` (button shows a CSS spinner but keeps its label). */
+  loadingLabel?: string;
   /** Label for the Cancel button. Defaults to `"Cancel"`. */
   cancelLabel?: string;
   /** If true, hide the Cancel button. Defaults to `false`. */
@@ -309,6 +347,22 @@ export interface PathShellProps {
    * - `"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>()`.
+   *
+   * The same services object that was passed to your path factory function
+   * should be passed here so step components can call service methods directly
+   * (e.g. parameterised queries that depend on mid-step user input).
+   *
+   * @example
+   * ```tsx
+   * const svc = new LiveHiringServices();
+   * const path = createHiringPath(svc);
+   * <PathShell path={path} services={svc} steps={{ ... }} />
+   * ```
+   */
+  services?: unknown;
 }
 
 export interface PathShellHandle {
@@ -325,6 +379,10 @@ export interface PathShellActions {
   setData: (key: string, value: unknown) => void;
   /** Restart the shell's current path with its current `initialData`. */
   restart: () => void;
+  /** Re-run the operation that set `snapshot.error`. See `PathEngine.retry()`. */
+  retry: () => void;
+  /** Pause with intent to return, preserving all state. Emits `suspended`. */
+  suspend: () => void;
 }
 
 /**
@@ -355,6 +413,7 @@ export const PathShell = forwardRef<PathShellHandle, PathShellProps>(function Pa
   backLabel = "Previous",
   nextLabel = "Next",
   completeLabel = "Complete",
+  loadingLabel,
   cancelLabel = "Cancel",
   hideCancel = false,
   hideProgress = false,
@@ -364,6 +423,7 @@ export const PathShell = forwardRef<PathShellHandle, PathShellProps>(function Pa
   renderFooter,
   validationDisplay = "summary",
   progressLayout = "merged",
+  services,
 }: PathShellProps, ref): ReactElement {
   const pathReturn = usePath({
     engine: externalEngine,
@@ -374,7 +434,7 @@ export const PathShell = forwardRef<PathShellHandle, PathShellProps>(function Pa
     }
   });
 
-  const { snapshot, start, next, previous, cancel, goToStep, goToStepChecked, setData, restart } = pathReturn;
+  const { snapshot, start, next, previous, cancel, goToStep, goToStepChecked, setData, restart, retry, suspend } = pathReturn;
 
   useImperativeHandle(ref, () => ({
     restart: () => restart(),
@@ -399,8 +459,10 @@ export const PathShell = forwardRef<PathShellHandle, PathShellProps>(function Pa
     ? ((snapshot.formId ? steps[snapshot.formId] : undefined) ?? steps[snapshot.stepId] ?? null)
     : null;
 
+  const contextValue: PathContextValue = { path: pathReturn, services: services ?? null };
+
   if (!snapshot) {
-    return createElement(PathContext.Provider, { value: pathReturn },
+    return createElement(PathContext.Provider, { value: contextValue },
       createElement("div", { className: cls("pw-shell", className) },
         createElement("div", { className: "pw-shell__empty" },
           createElement("p", null, "No active path."),
@@ -416,7 +478,9 @@ export const PathShell = forwardRef<PathShellHandle, PathShellProps>(function Pa
 
   const actions: PathShellActions = {
     next, previous, cancel, goToStep, goToStepChecked, setData,
-    restart: () => restart()
+    restart: () => restart(),
+    retry: () => retry(),
+    suspend: () => suspend(),
   };
 
   const showRoot = !hideProgress && !!snapshot.rootProgress && progressLayout !== "activeOnly";
@@ -424,7 +488,7 @@ export const PathShell = forwardRef<PathShellHandle, PathShellProps>(function Pa
     ? true
     : (snapshot.stepCount > 1 || snapshot.nestingLevel > 0) && progressLayout !== "rootOnly");
 
-  return createElement(PathContext.Provider, { value: pathReturn },
+  return createElement(PathContext.Provider, { value: contextValue },
     createElement("div", { className: cls("pw-shell", progressLayout !== "merged" && `pw-shell--progress-${progressLayout}`, className) },
       // Root progress — persistent top-level bar visible during sub-paths
       showRoot && defaultRootProgress(snapshot.rootProgress!),
@@ -452,12 +516,18 @@ export const PathShell = forwardRef<PathShellHandle, PathShellProps>(function Pa
           )
         )
       ),
-      // Footer — navigation buttons
-      renderFooter
-        ? renderFooter(snapshot, actions)
-        : defaultFooter(snapshot, actions, {
-            backLabel, nextLabel, completeLabel, cancelLabel, hideCancel, footerLayout
-          })
+      // Blocking error — guard returned { allowed: false, reason }
+      validationDisplay !== "inline" && snapshot.hasAttemptedNext && snapshot.blockingError &&
+        createElement("p", { className: "pw-shell__blocking-error" }, snapshot.blockingError),
+      // Error panel — replaces footer when an async operation has failed
+      snapshot.status === "error" && snapshot.error
+        ? defaultErrorPanel(snapshot, actions)
+        // Footer — navigation buttons
+        : renderFooter
+          ? renderFooter(snapshot, actions)
+          : defaultFooter(snapshot, actions, {
+              backLabel, nextLabel, completeLabel, loadingLabel, cancelLabel, hideCancel, footerLayout
+            })
     )
   );
 });
@@ -522,6 +592,47 @@ function defaultHeader(snapshot: PathSnapshot): ReactElement {
   );
 }
 
+// ---------------------------------------------------------------------------
+// Default error panel
+// ---------------------------------------------------------------------------
+
+
+function defaultErrorPanel(
+  snapshot: PathSnapshot,
+  actions: PathShellActions
+): ReactElement {
+  const { error, hasPersistence } = snapshot;
+  if (!error) return createElement("div", null);
+  const escalated = error.retryCount >= 2;
+  const title = escalated ? "Still having trouble." : "Something went wrong.";
+  const phaseMsg = errorPhaseMessage(error.phase);
+
+  return createElement("div", { className: "pw-shell__error" },
+    createElement("div", { className: "pw-shell__error-title" }, title),
+    createElement("div", { className: "pw-shell__error-message" },
+      phaseMsg,
+      error.message && ` ${error.message}`
+    ),
+    createElement("div", { className: "pw-shell__error-actions" },
+      !escalated && createElement("button", {
+        type: "button",
+        className: "pw-shell__btn pw-shell__btn--retry",
+        onClick: actions.retry
+      }, "Try again"),
+      hasPersistence && createElement("button", {
+        type: "button",
+        className: cls("pw-shell__btn", escalated ? "pw-shell__btn--retry" : "pw-shell__btn--suspend"),
+        onClick: actions.suspend
+      }, "Save and come back later"),
+      escalated && !hasPersistence && createElement("button", {
+        type: "button",
+        className: "pw-shell__btn pw-shell__btn--retry",
+        onClick: actions.retry
+      }, "Try again")
+    )
+  );
+}
+
 // ---------------------------------------------------------------------------
 // Default footer (navigation buttons)
 // ---------------------------------------------------------------------------
@@ -530,6 +641,7 @@ interface FooterLabels {
   backLabel: string;
   nextLabel: string;
   completeLabel: string;
+  loadingLabel?: string;
   cancelLabel: string;
   hideCancel: boolean;
   footerLayout: "wizard" | "form" | "auto";
@@ -553,14 +665,14 @@ function defaultFooter(
       isFormMode && !labels.hideCancel && createElement("button", {
         type: "button",
         className: "pw-shell__btn pw-shell__btn--cancel",
-        disabled: snapshot.isNavigating,
+        disabled: snapshot.status !== "idle",
         onClick: actions.cancel
       }, labels.cancelLabel),
       // Wizard mode: Back on the left
       !isFormMode && !snapshot.isFirstStep && createElement("button", {
         type: "button",
         className: "pw-shell__btn pw-shell__btn--back",
-        disabled: snapshot.isNavigating || !snapshot.canMovePrevious,
+        disabled: snapshot.status !== "idle" || !snapshot.canMovePrevious,
         onClick: actions.previous
       }, labels.backLabel)
     ),
@@ -569,16 +681,18 @@ function defaultFooter(
       !isFormMode && !labels.hideCancel && createElement("button", {
         type: "button",
         className: "pw-shell__btn pw-shell__btn--cancel",
-        disabled: snapshot.isNavigating,
+        disabled: snapshot.status !== "idle",
         onClick: actions.cancel
       }, labels.cancelLabel),
       // Both modes: Submit on the right
       createElement("button", {
         type: "button",
-        className: "pw-shell__btn pw-shell__btn--next",
-        disabled: snapshot.isNavigating,
+        className: cls("pw-shell__btn pw-shell__btn--next", snapshot.status !== "idle" && "pw-shell__btn--loading"),
+        disabled: snapshot.status !== "idle",
         onClick: actions.next
-      }, snapshot.isLastStep ? labels.completeLabel : labels.nextLabel)
+      }, snapshot.status !== "idle" && labels.loadingLabel
+          ? labels.loadingLabel
+          : snapshot.isLastStep ? labels.completeLabel : labels.nextLabel)
     )
   );
 }