@daltonr/pathwrite-svelte 0.5.0

package/src/PathShell.svelte

@@ -0,0 +1,181 @@
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { usePath, setPathContext } from './index.svelte.js';
+  import type { PathDefinition, PathData, PathEngine, PathSnapshot } from './index.svelte.js';
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    path?: PathDefinition<any>;
+    engine?: PathEngine;
+    initialData?: PathData;
+    autoStart?: boolean;
+    backLabel?: string;
+    nextLabel?: string;
+    completeLabel?: string;
+    cancelLabel?: string;
+    hideCancel?: boolean;
+    hideProgress?: boolean;
+    // Callback props replace event dispatching in Svelte 5
+    oncomplete?: (data: PathData) => void;
+    oncancel?: (data: PathData) => void;
+    onevent?: (event: any) => void;
+    // Optional override snippets for header and footer
+    header?: Snippet<[PathSnapshot<any>]>;
+    footer?: Snippet<[PathSnapshot<any>, object]>;
+    // All other props treated as step snippets keyed by step ID
+    [key: string]: Snippet | any;
+  }
+
+  let {
+    path,
+    engine: engineProp,
+    initialData = {},
+    autoStart = true,
+    backLabel = 'Previous',
+    nextLabel = 'Next',
+    completeLabel = 'Complete',
+    cancelLabel = 'Cancel',
+    hideCancel = false,
+    hideProgress = false,
+    oncomplete,
+    oncancel,
+    onevent,
+    header,
+    footer,
+    ...stepSnippets
+  }: Props = $props();
+
+  // Initialize path engine
+  const pathReturn = usePath({
+    engine: engineProp,
+    onEvent: (event) => {
+      onevent?.(event);
+      if (event.type === 'completed') oncomplete?.(event.data);
+      if (event.type === 'cancelled') oncancel?.(event.data);
+    }
+  });
+
+  const { start, next, previous, cancel, goToStep, goToStepChecked, setData, restart } = pathReturn;
+
+  // Provide context for child step components
+  setPathContext({
+    get snapshot() { return pathReturn.snapshot; },
+    next,
+    previous,
+    cancel,
+    goToStep,
+    goToStepChecked,
+    setData,
+    restart: () => restart(path, initialData)
+  });
+
+  // Auto-start the path when no external engine is provided
+  let started = false;
+  onMount(() => {
+    if (autoStart && !started && !engineProp) {
+      started = true;
+      start(path, initialData);
+    }
+  });
+
+  let snap = $derived(pathReturn.snapshot);
+  let actions = $derived({ next, previous, cancel, goToStep, goToStepChecked, setData, restart: () => restart(path, initialData) });
+</script>
+
+<div class="pw-shell">
+  {#if !snap}
+    <div class="pw-shell__empty">
+      <p>No active path.</p>
+      {#if !autoStart}
+        <button type="button" class="pw-shell__start-btn" onclick={() => start(path, initialData)}>
+          Start
+        </button>
+      {/if}
+    </div>
+  {:else}
+    <!-- Header: progress indicator (overridable via header snippet) -->
+    {#if !hideProgress}
+      {#if header}
+        {@render header(snap)}
+      {:else}
+        <div class="pw-shell__header">
+          <div class="pw-shell__steps">
+            {#each snap.steps as step, i}
+              <div class="pw-shell__step pw-shell__step--{step.status}">
+                <span class="pw-shell__step-dot">
+                  {step.status === 'completed' ? '✓' : i + 1}
+                </span>
+                <span class="pw-shell__step-label">{step.title ?? step.id}</span>
+              </div>
+            {/each}
+          </div>
+          <div class="pw-shell__track">
+            <div class="pw-shell__track-fill" style="width: {snap.progress * 100}%"></div>
+          </div>
+        </div>
+      {/if}
+    {/if}
+
+    <!-- Body: current step rendered via named snippet -->
+    <div class="pw-shell__body">
+      {#if stepSnippets[snap.stepId]}
+        {@render stepSnippets[snap.stepId]()}
+      {:else}
+        <p>No content for step "{snap.stepId}"</p>
+      {/if}
+    </div>
+
+    <!-- Validation messages -->
+    {#if snap.validationMessages.length > 0}
+      <ul class="pw-shell__validation">
+        {#each snap.validationMessages as msg}
+          <li class="pw-shell__validation-item">{msg}</li>
+        {/each}
+      </ul>
+    {/if}
+
+    <!-- Footer: navigation buttons (overridable via footer snippet) -->
+    {#if footer}
+      {@render footer(snap, actions)}
+    {:else}
+      <div class="pw-shell__footer">
+        <div class="pw-shell__footer-left">
+          {#if !snap.isFirstStep}
+            <button
+              type="button"
+              class="pw-shell__btn pw-shell__btn--back"
+              disabled={snap.isNavigating || !snap.canMovePrevious}
+              onclick={previous}
+            >
+              {backLabel}
+            </button>
+          {/if}
+        </div>
+        <div class="pw-shell__footer-right">
+          {#if !hideCancel}
+            <button
+              type="button"
+              class="pw-shell__btn pw-shell__btn--cancel"
+              disabled={snap.isNavigating}
+              onclick={cancel}
+            >
+              {cancelLabel}
+            </button>
+          {/if}
+          <button
+            type="button"
+            class="pw-shell__btn pw-shell__btn--next"
+            disabled={snap.isNavigating || !snap.canMoveNext}
+            onclick={next}
+          >
+            {snap.isLastStep ? completeLabel : nextLabel}
+          </button>
+        </div>
+      </div>
+    {/if}
+  {/if}
+</div>
+
+<style>
+  /* Component-level styles inherited from shell.css */
+</style>

package/src/index.svelte.ts

@@ -0,0 +1,254 @@
+import { onDestroy, getContext, setContext } from "svelte";
+import type {
+  PathData,
+  PathDefinition,
+  PathEngine,
+  PathEvent,
+  PathSnapshot
+} from "@daltonr/pathwrite-core";
+import { PathEngine as PathEngineClass } from "@daltonr/pathwrite-core";
+
+// Re-export core types for convenience
+export type {
+  PathData,
+  PathDefinition,
+  PathEngine,
+  PathEvent,
+  PathSnapshot,
+  PathStep,
+  PathStepContext,
+  SerializedPathState
+} from "@daltonr/pathwrite-core";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface UsePathOptions {
+  /**
+   * An externally-managed `PathEngine` to subscribe to — for example, the engine
+   * returned by `restoreOrStart()` from `@daltonr/pathwrite-store-http`.
+   *
+   * 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**.
+   * - `PathShell` will skip its own `autoStart` call.
+   */
+  engine?: PathEngine;
+  /** Called for every engine event (stateChanged, completed, cancelled, resumed). */
+  onEvent?: (event: PathEvent) => void;
+}
+
+export interface UsePathReturn<TData extends PathData = PathData> {
+  /** Current path snapshot, or `null` when no path is active. Reactive via `$state`. */
+  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>;
+  /** 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. */
+  previous: () => Promise<void>;
+  /** Cancel the active path (or sub-path). */
+  cancel: () => Promise<void>;
+  /** Jump directly to a step by ID. Calls onLeave / onEnter but bypasses guards and shouldSkip. */
+  goToStep: (stepId: string) => Promise<void>;
+  /** Jump directly to a step by ID, checking the current step's canMoveNext (forward) or canMovePrevious (backward) guard first. Navigation is blocked if the guard returns false. */
+  goToStepChecked: (stepId: string) => Promise<void>;
+  /** 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. */
+  setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
+  /**
+   * Tear down any active path (without firing hooks) and immediately start the
+   * given path fresh. Safe to call whether or not a path is currently active.
+   * Use for "Start over" / retry flows without remounting the component.
+   */
+  restart: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// usePath - Runes-based API for Svelte 5
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a Pathwrite engine with Svelte 5 runes-based reactivity.
+ * Call this from inside a Svelte component to get a reactive snapshot.
+ * Cleanup is automatic via onDestroy.
+ *
+ * **Note:** `snapshot` is a reactive getter — access it via the returned
+ * object (e.g. `path.snapshot`). Destructuring `snapshot` will lose reactivity.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { usePath } from '@daltonr/pathwrite-svelte';
+ *
+ *   const path = usePath();
+ *
+ *   onMount(() => {
+ *     path.start(myPath, { name: '' });
+ *   });
+ * </script>
+ *
+ * {#if path.snapshot}
+ *   <h2>{path.snapshot.stepId}</h2>
+ *   <button onclick={path.previous} disabled={path.snapshot.isFirstStep}>Previous</button>
+ *   <button onclick={path.next} disabled={!path.snapshot.canMoveNext}>Next</button>
+ * {/if}
+ * ```
+ */
+export function usePath<TData extends PathData = PathData>(
+  options?: UsePathOptions
+): UsePathReturn<TData> {
+  const engine = options?.engine ?? new PathEngineClass();
+
+  // Reactive snapshot via $state rune
+  let _snapshot: PathSnapshot<TData> | null = $state(
+    engine.snapshot() as PathSnapshot<TData> | null
+  );
+
+  // Subscribe to engine events
+  const unsubscribe = engine.subscribe((event: PathEvent) => {
+    if (event.type === "stateChanged" || event.type === "resumed") {
+      _snapshot = event.snapshot as PathSnapshot<TData>;
+    } else if (event.type === "completed" || event.type === "cancelled") {
+      _snapshot = null;
+    }
+    options?.onEvent?.(event);
+  });
+
+  // Auto-cleanup when component is destroyed
+  onDestroy(unsubscribe);
+
+  const start = (path: PathDefinition<any>, initialData: PathData = {}): Promise<void> =>
+    engine.start(path, initialData);
+
+  const startSubPath = (
+    path: PathDefinition<any>,
+    initialData: PathData = {},
+    meta?: Record<string, unknown>
+  ): Promise<void> => engine.startSubPath(path, initialData, meta);
+
+  const next = (): Promise<void> => engine.next();
+  const previous = (): Promise<void> => engine.previous();
+  const cancel = (): Promise<void> => engine.cancel();
+
+  const goToStep = (stepId: string): Promise<void> => engine.goToStep(stepId);
+  const goToStepChecked = (stepId: string): Promise<void> => engine.goToStepChecked(stepId);
+
+  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 restart = (path: PathDefinition<any>, initialData: PathData = {}): Promise<void> =>
+    engine.restart(path, initialData);
+
+  return {
+    get snapshot() { return _snapshot; },
+    start,
+    startSubPath,
+    next,
+    previous,
+    cancel,
+    goToStep,
+    goToStepChecked,
+    setData,
+    restart
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Context API for PathShell
+// ---------------------------------------------------------------------------
+
+const PATH_CONTEXT_KEY = Symbol("pathwrite-context");
+
+export interface PathContext<TData extends PathData = PathData> {
+  readonly snapshot: PathSnapshot<TData> | null;
+  next: () => Promise<void>;
+  previous: () => Promise<void>;
+  cancel: () => Promise<void>;
+  goToStep: (stepId: string) => Promise<void>;
+  goToStepChecked: (stepId: string) => Promise<void>;
+  setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
+  restart: () => Promise<void>;
+}
+
+/**
+ * Get the PathContext from a parent PathShell component.
+ * Use this inside step components to access the path engine.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { getPathContext } from '@daltonr/pathwrite-svelte';
+ *
+ *   const ctx = getPathContext();
+ * </script>
+ *
+ * <input value={ctx.snapshot?.data.name}
+ *        oninput={(e) => ctx.setData('name', e.target.value)} />
+ * <button onclick={ctx.next}>Next</button>
+ * ```
+ */
+export function getPathContext<TData extends PathData = PathData>(): PathContext<TData> {
+  const ctx = getContext<PathContext<TData>>(PATH_CONTEXT_KEY);
+  if (!ctx) {
+    throw new Error(
+      "getPathContext() must be called from a component inside a <PathShell>. " +
+        "Ensure the PathShell component is a parent in the component tree."
+    );
+  }
+  return ctx;
+}
+
+/**
+ * Internal: Set the PathContext for child components.
+ * Used by PathShell component.
+ */
+export function setPathContext<TData extends PathData = PathData>(ctx: PathContext<TData>): void {
+  setContext(PATH_CONTEXT_KEY, ctx);
+}
+
+// ---------------------------------------------------------------------------
+// Helper for binding form inputs
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a two-way binding helper for form inputs.
+ * Returns an object with a reactive `value` property.
+ *
+ * @param getSnapshot - A getter function returning the current snapshot (e.g. `() => path.snapshot`)
+ * @param setData - The `setData` function from `usePath()`
+ * @param key - The data key to bind
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { usePath, bindData } from '@daltonr/pathwrite-svelte';
+ *
+ *   const path = usePath();
+ *   const name = bindData(() => path.snapshot, path.setData, 'name');
+ * </script>
+ *
+ * <input value={name.value} oninput={(e) => name.value = e.target.value} />
+ * ```
+ */
+export function bindData<TData extends PathData, K extends string & keyof TData>(
+  getSnapshot: () => PathSnapshot<TData> | null,
+  setData: <Key extends string & keyof TData>(key: Key, value: TData[Key]) => Promise<void>,
+  key: K
+): { readonly value: TData[K]; set: (value: TData[K]) => void } {
+  return {
+    get value(): TData[K] {
+      return (getSnapshot()?.data[key] ?? undefined) as TData[K];
+    },
+    set(value: TData[K]) {
+      setData(key, value);
+    }
+  };
+}
+
+// Export PathShell component
+export { default as PathShell } from "./PathShell.svelte";
+