@daltonr/pathwrite-react-native 0.9.0

package/README.md

@@ -0,0 +1,302 @@
+# @daltonr/pathwrite-react-native
+
+React Native adapter for `@daltonr/pathwrite-core`. Exposes path state as reactive React state via `useSyncExternalStore`, with stable action callbacks, an optional context provider, and an optional `PathShell` default UI built from React Native primitives.
+
+Works with Expo (managed and bare workflow) and bare React Native projects. Targets iOS and Android.
+
+## Installation
+
+```bash
+npm install @daltonr/pathwrite-core @daltonr/pathwrite-react-native
+```
+
+Peer dependencies: `react >= 18.0.0`, `react-native >= 0.72.0`.
+
+## Exports
+
+```typescript
+import {
+  PathShell,         // React Native UI shell
+  usePath,           // Hook — creates a scoped engine
+  usePathContext,    // Hook — reads the nearest PathProvider
+  PathProvider,      // Context provider
+  // Core types re-exported for convenience:
+  PathEngine,
+  PathData,
+  PathDefinition,
+  PathEvent,
+  PathSnapshot,
+  PathStep,
+  PathStepContext,
+  StepChoice,
+  SerializedPathState,
+} from "@daltonr/pathwrite-react-native";
+```
+
+---
+
+## Quick Start — PathShell
+
+The fastest way to get started. `PathShell` manages the engine lifecycle, renders the active step, and provides navigation buttons. The default header shows numbered step dots (✓ when completed), the current step title, and a progress bar.
+
+```tsx
+import { PathShell } from "@daltonr/pathwrite-react-native";
+import { myPath, INITIAL_DATA } from "./my-path";
+import { DetailsStep } from "./DetailsStep";
+import { ReviewStep } from "./ReviewStep";
+
+export function MyFlow() {
+  return (
+    <PathShell
+      path={myPath}
+      initialData={INITIAL_DATA}
+      onComplete={(data) => console.log("Done!", data)}
+      steps={{
+        details: <DetailsStep />,
+        review:  <ReviewStep />,
+      }}
+    />
+  );
+}
+```
+
+Inside step components, use `usePathContext()` to read state and dispatch actions:
+
+```tsx
+import { usePathContext } from "@daltonr/pathwrite-react-native";
+import type { MyData } from "./my-path";
+
+export function DetailsStep() {
+  const { snapshot, setData } = usePathContext<MyData>();
+  const name = snapshot?.data.name ?? "";
+
+  return (
+    <TextInput
+      value={name}
+      onChangeText={(text) => setData("name", text)}
+      placeholder="Your name"
+    />
+  );
+}
+```
+
+---
+
+## Option A — `usePath` hook (component-scoped)
+
+Each call creates an isolated engine. Good when a single screen owns the path.
+
+```tsx
+import { usePath } from "@daltonr/pathwrite-react-native";
+import { myPath } from "./my-path";
+
+function MyScreen() {
+  const { snapshot, start, next, previous, setData } = usePath({
+    onEvent(event) {
+      if (event.type === "completed") console.log("Done!", event.data);
+    }
+  });
+
+  useEffect(() => {
+    start(myPath, { name: "" });
+  }, []);
+
+  if (!snapshot) return null;
+
+  return (
+    <View>
+      <Text>{snapshot.stepTitle ?? snapshot.stepId}</Text>
+      <Text>Step {snapshot.stepIndex + 1} of {snapshot.stepCount}</Text>
+      <Pressable onPress={previous} disabled={snapshot.isNavigating}>
+        <Text>Back</Text>
+      </Pressable>
+      <Pressable onPress={next} disabled={snapshot.isNavigating || !snapshot.canMoveNext}>
+        <Text>{snapshot.isLastStep ? "Complete" : "Next"}</Text>
+      </Pressable>
+    </View>
+  );
+}
+```
+
+## Option B — `PathProvider` + `usePathContext` (tree-scoped)
+
+Share one engine across a component tree — step components read state without prop-drilling.
+
+```tsx
+import { PathProvider } from "@daltonr/pathwrite-react-native";
+
+// Root — start the path once, then render children
+function WizardRoot() {
+  const { snapshot, start, next } = usePathContext();
+  useEffect(() => { start(myPath, {}); }, []);
+  return (
+    <View>
+      {snapshot && <Text>Step {snapshot.stepIndex + 1}</Text>}
+      <Pressable onPress={next}><Text>Next</Text></Pressable>
+    </View>
+  );
+}
+
+// Wrap in the provider at the navigation/screen level
+export function WizardScreen() {
+  return (
+    <PathProvider>
+      <WizardRoot />
+    </PathProvider>
+  );
+}
+```
+
+---
+
+## Path definition
+
+Path definitions are plain objects — no classes, no decorators, framework-agnostic.
+
+```typescript
+import type { PathDefinition } from "@daltonr/pathwrite-react-native";
+
+interface MyData {
+  name: string;
+  agreed: boolean;
+}
+
+export const myPath: PathDefinition<MyData> = {
+  id: "onboarding",
+  steps: [
+    {
+      id: "name",
+      title: "Your Name",
+      canMoveNext: ({ data }) => data.name.trim().length >= 2,
+    },
+    {
+      id: "terms",
+      title: "Terms",
+      canMoveNext: ({ data }) => data.agreed,
+    },
+    {
+      id: "done",
+      title: "All Done",
+    },
+  ],
+};
+```
+
+---
+
+## Conditional steps — `shouldSkip`
+
+Steps with a `shouldSkip` guard are removed from the flow when the guard returns `true`. The progress indicator updates automatically.
+
+```typescript
+{
+  id: "address-details",
+  shouldSkip: ({ data }) => data.deliveryMethod !== "postal",
+}
+```
+
+---
+
+## Conditional forms — `StepChoice`
+
+A `StepChoice` step selects one inner step at runtime based on current data. Useful for showing different form variants without branching the path definition.
+
+```typescript
+{
+  id: "address",
+  select: ({ data }) => data.country === "US" ? "address-us" : "address-ie",
+  steps: [
+    { id: "address-us", title: "US Address" },
+    { id: "address-ie", title: "Irish Address" },
+  ],
+}
+```
+
+The snapshot exposes both `stepId` (the outer choice id, `"address"`) and `formId` (the selected inner step, `"address-us"`). When using `PathShell`, pass both inner step IDs as keys in the `steps` map — the shell resolves the correct one automatically:
+
+```tsx
+<PathShell
+  path={myPath}
+  steps={{
+    name:       <NameStep />,
+    "address-us": <USAddressStep />,
+    "address-ie": <IrishAddressStep />,
+    done:       <DoneStep />,
+  }}
+/>
+```
+
+---
+
+## Sub-paths
+
+Push a sub-path onto the stack from within a step. The parent path resumes from the same step when the sub-path completes.
+
+```typescript
+const { startSubPath } = usePathContext();
+
+function handleStartSubWizard() {
+  startSubPath(subWizardPath, {});
+}
+```
+
+---
+
+## PathShell props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `path` | `PathDefinition` | required | The path to drive. |
+| `steps` | `Record<string, ReactNode>` | required | Map of step ID → content. |
+| `initialData` | `PathData` | `{}` | Initial data passed to `engine.start()`. |
+| `engine` | `PathEngine` | — | Externally managed engine (e.g., from `restoreOrStart()`). |
+| `autoStart` | `boolean` | `true` | Start the path automatically on mount. |
+| `onComplete` | `(data) => void` | — | Called when the path completes. |
+| `onCancel` | `(data) => void` | — | Called when the path is cancelled. |
+| `onEvent` | `(event) => void` | — | Called for every engine event. |
+| `backLabel` | `string` | `"Previous"` | Label for the back button. |
+| `nextLabel` | `string` | `"Next"` | Label for the next button. |
+| `completeLabel` | `string` | `"Complete"` | Label for the next button on the last step. |
+| `cancelLabel` | `string` | `"Cancel"` | Label for the cancel button. |
+| `hideCancel` | `boolean` | `false` | Hide the cancel button. |
+| `hideProgress` | `boolean` | `false` | Hide the progress header (numbered dots, current step title, and progress bar). Also hidden automatically for single-step top-level paths. |
+| `disableBodyScroll` | `boolean` | `false` | Replace the `ScrollView` body wrapper with a plain `View`. Use when the step content contains a `FlatList` or other virtualized list to avoid the "VirtualizedList inside ScrollView" warning. The step is then responsible for its own scroll. |
+| `footerLayout` | `"wizard" \| "form" \| "auto"` | `"auto"` | `"wizard"` puts back on the left; `"form"` puts cancel on the left. |
+| `renderHeader` | `(snapshot) => ReactNode` | — | Replace the default progress header entirely. |
+| `renderFooter` | `(snapshot, actions) => ReactNode` | — | Replace the default nav buttons. |
+| `style` | `StyleProp<ViewStyle>` | — | Override for the root `View`. |
+
+---
+
+## usePath options and return value
+
+```typescript
+usePath(options?: {
+  engine?: PathEngine;       // Use an externally-managed engine
+  onEvent?: (event: PathEvent) => void;
+})
+```
+
+Returns `UsePathReturn<TData>`:
+
+| Field | Type | Description |
+|---|---|---|
+| `snapshot` | `PathSnapshot<TData> \| null` | Current state. `null` when no path is active. |
+| `start` | `(path, data?) => void` | Start a path. |
+| `startSubPath` | `(path, data?, meta?) => void` | Push a sub-path. |
+| `next` | `() => void` | Advance. Completes on the last step. |
+| `previous` | `() => void` | Go back. |
+| `cancel` | `() => void` | Cancel the active path. |
+| `goToStep` | `(stepId) => void` | Jump to a step (no guard check). |
+| `goToStepChecked` | `(stepId) => void` | Jump to a step (checks current step guard first). |
+| `setData` | `(key, value) => void` | Update one data field. |
+| `resetStep` | `() => void` | Restore data to step-entry state. |
+| `restart` | `(path, data?) => void` | Tear down and restart fresh. |
+
+---
+
+## Testing
+
+Hook tests (`usePath`, `usePathContext`) use `@testing-library/react` in a jsdom environment — no device or simulator required. The hooks are pure React (they use only `useSyncExternalStore`, `useCallback`, `useRef`) and work identically in both RN and web contexts.
+
+PathShell component tests require `@testing-library/react-native` and a React Native test environment (e.g., Jest with `react-native` preset or Expo's Jest preset).

package/dist/index.d.ts

@@ -0,0 +1,151 @@
+import type { PropsWithChildren, ReactElement, ReactNode } from "react";
+import type { StyleProp, ViewStyle } from "react-native";
+import { PathData, PathDefinition, PathEngine, PathEvent, PathSnapshot } from "@daltonr/pathwrite-core";
+export interface UsePathOptions {
+    /**
+     * An externally-managed `PathEngine` to subscribe to — for example, one
+     * returned by `restoreOrStart()` from `@daltonr/pathwrite-store`.
+     *
+     * When provided:
+     * - `usePath` will **not** create its own engine.
+     * - The snapshot is seeded immediately from the engine's current state.
+     * - The engine lifecycle (start / cleanup) is the **caller's responsibility**.
+     */
+    engine?: PathEngine;
+    /** Called for every engine event. The callback ref is kept current — changing it does not re-subscribe. */
+    onEvent?: (event: PathEvent) => void;
+}
+export interface UsePathReturn<TData extends PathData = PathData> {
+    /** Current path snapshot, or `null` when no path is active. Triggers a re-render on change. */
+    snapshot: PathSnapshot<TData> | null;
+    /** Start (or restart) a path. */
+    start: (path: PathDefinition<any>, initialData?: PathData) => void;
+    /** Push a sub-path onto the stack. */
+    startSubPath: (path: PathDefinition<any>, initialData?: PathData, meta?: Record<string, unknown>) => void;
+    /** Advance one step. Completes the path on the last step. */
+    next: () => void;
+    /** Go back one step. */
+    previous: () => void;
+    /** Cancel the active path (or sub-path). */
+    cancel: () => void;
+    /** Jump directly to a step by ID, bypassing guards and shouldSkip. */
+    goToStep: (stepId: string) => void;
+    /** Jump directly to a step by ID, checking the current step's guard first. */
+    goToStepChecked: (stepId: string) => void;
+    /** Update a single data value. When `TData` is specified, key and value are type-checked. */
+    setData: <K extends string & keyof TData>(key: K, value: TData[K]) => void;
+    /** Reset the current step's data to what it was when the step was entered. */
+    resetStep: () => void;
+    /** Tear down any active path and immediately start the given path fresh. */
+    restart: () => void;
+}
+export type PathProviderProps = PropsWithChildren<{
+    onEvent?: (event: PathEvent) => void;
+}>;
+export declare function usePath<TData extends PathData = PathData>(options?: UsePathOptions): UsePathReturn<TData>;
+/**
+ * Provides a single `usePath` instance to all descendants.
+ * Consume with `usePathContext()`.
+ */
+export declare function PathProvider({ children, onEvent }: PathProviderProps): ReactElement;
+/**
+ * Access the nearest `PathProvider`'s path instance.
+ * Throws if used outside of a `<PathProvider>`.
+ */
+export declare function usePathContext<TData extends PathData = PathData>(): Omit<UsePathReturn<TData>, "snapshot"> & {
+    snapshot: PathSnapshot<TData>;
+};
+export interface PathShellHandle {
+    /** Restart the shell's current path with its original `initialData`, without unmounting. */
+    restart: () => void;
+}
+export interface PathShellActions {
+    next: () => void;
+    previous: () => void;
+    cancel: () => void;
+    goToStep: (stepId: string) => void;
+    goToStepChecked: (stepId: string) => void;
+    setData: (key: string, value: unknown) => void;
+    restart: () => void;
+}
+export interface PathShellProps {
+    /** The path definition to drive. */
+    path: PathDefinition<any>;
+    /** An externally-managed engine. When supplied, PathShell skips its own start() call. */
+    engine?: PathEngine;
+    /** Map of step ID → React Native content. The shell renders `steps[snapshot.stepId]` for the current step. */
+    steps: Record<string, ReactNode>;
+    /** Initial data passed to engine.start(). */
+    initialData?: PathData;
+    /** If true, the path is started automatically on mount. Defaults to true. */
+    autoStart?: boolean;
+    /** Called when the path completes. */
+    onComplete?: (data: PathData) => void;
+    /** Called when the path is cancelled. */
+    onCancel?: (data: PathData) => void;
+    /** Called for every engine event. */
+    onEvent?: (event: PathEvent) => void;
+    /** Label for the Previous button. Defaults to "Previous". */
+    backLabel?: string;
+    /** Label for the Next button. Defaults to "Next". */
+    nextLabel?: string;
+    /** Label for the Complete button (last step). Defaults to "Complete". */
+    completeLabel?: string;
+    /** Label for the Cancel button. Defaults to "Cancel". */
+    cancelLabel?: string;
+    /** If true, hide the Cancel button. */
+    hideCancel?: boolean;
+    /** If true, hide the progress dots. Also hidden automatically when the path has only one step. */
+    hideProgress?: boolean;
+    /**
+     * Footer layout mode:
+     * - `"auto"` (default): "form" for single-step top-level paths, "wizard" otherwise.
+     * - `"wizard"`: Back on left, Cancel and Next on right.
+     * - `"form"`: Cancel on left, Next alone on right.
+     */
+    footerLayout?: "wizard" | "form" | "auto";
+    /**
+     * Controls whether the shell renders its auto-generated field-error summary box.
+     * - `"summary"` (default): Shell renders the labeled error list below the step body.
+     * - `"inline"`: Suppress the summary — handle errors inside the step component instead.
+     * - `"both"`: Render the shell summary AND whatever the step component renders.
+     */
+    validationDisplay?: "summary" | "inline" | "both";
+    /** Render prop to replace the header (progress area). */
+    renderHeader?: (snapshot: PathSnapshot) => ReactNode;
+    /** Render prop to replace the footer (navigation area). */
+    renderFooter?: (snapshot: PathSnapshot, actions: PathShellActions) => ReactNode;
+    /** Style override for the root container. */
+    style?: StyleProp<ViewStyle>;
+    /**
+     * Passed to the internal `KeyboardAvoidingView`. Use this to account for
+     * any header or navigation bar above the shell (e.g. a React Navigation header).
+     * Defaults to `0`.
+     */
+    keyboardVerticalOffset?: number;
+    /**
+     * When `true`, replaces the `ScrollView` body wrapper with a plain `View`.
+     * Use this when the step content contains a `FlatList`, `SectionList`, or
+     * other virtualized list to avoid the "VirtualizedList inside ScrollView"
+     * warning. The step is then responsible for managing its own scroll.
+     */
+    disableBodyScroll?: boolean;
+}
+/**
+ * Default UI shell for React Native. Renders a progress dot indicator,
+ * step content, and navigation buttons.
+ *
+ * ```tsx
+ * <PathShell
+ *   path={myPath}
+ *   initialData={{ name: "" }}
+ *   onComplete={handleDone}
+ *   steps={{
+ *     details: <DetailsStep />,
+ *     review:  <ReviewStep />,
+ *   }}
+ * />
+ * ```
+ */
+export declare const PathShell: import("react").ForwardRefExoticComponent<PathShellProps & import("react").RefAttributes<PathShellHandle>>;
+export type { PathData, FieldErrors, PathDefinition, PathEngine, PathEvent, PathSnapshot, PathStep, PathStepContext, ProgressLayout, RootProgress, SerializedPathState, StepChoice, } from "@daltonr/pathwrite-core";