@daltonr/pathwrite-svelte 0.5.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 Richard Dalton
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,468 @@
+# @daltonr/pathwrite-svelte
+
+Svelte 5 adapter for [@daltonr/pathwrite-core](../core) — reactive stores with lifecycle hooks, guards, and optional `<PathShell>` default UI.
+
+## Installation
+
+```bash
+npm install @daltonr/pathwrite-svelte
+```
+
+> **Requires Svelte 5.** This adapter uses runes (`$props`, `$derived`, `$state`) and snippets (`{#snippet}`, `{@render}`).
+
+## Quick Start
+
+### Option 1: Use `usePath()` with custom UI
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { usePath } from '@daltonr/pathwrite-svelte';
+  
+  const { snapshot, start, next, previous, setData } = usePath();
+  
+  const myPath = {
+    id: 'signup',
+    steps: [
+      { id: 'details', title: 'Your Details' },
+      { id: 'review', title: 'Review' }
+    ]
+  };
+  
+  onMount(() => {
+    start(myPath, { name: '', email: '' });
+  });
+  
+  let snap = $derived($snapshot);
+</script>
+
+{#if snap}
+  <h2>{snap.steps[snap.stepIndex].title}</h2>
+  
+  {#if snap.stepId === 'details'}
+    <input
+      type="text"
+      value={snap.data.name || ''}
+      oninput={(e) => setData('name', e.currentTarget.value)}
+      placeholder="Name"
+    />
+    <input
+      type="email"
+      value={snap.data.email || ''}
+      oninput={(e) => setData('email', e.currentTarget.value)}
+      placeholder="Email"
+    />
+  {:else if snap.stepId === 'review'}
+    <p>Name: {snap.data.name}</p>
+    <p>Email: {snap.data.email}</p>
+  {/if}
+  
+  <button onclick={previous} disabled={snap.isFirstStep || snap.isNavigating}>
+    Previous
+  </button>
+  <button onclick={next} disabled={!snap.canMoveNext || snap.isNavigating}>
+    {snap.isLastStep ? 'Complete' : 'Next'}
+  </button>
+{/if}
+```
+
+### Option 2: Use `<PathShell>` with snippets
+
+```svelte
+<script lang="ts">
+  import { PathShell } from '@daltonr/pathwrite-svelte';
+  import '@daltonr/pathwrite-svelte/styles.css';
+  
+  import DetailsForm from './DetailsForm.svelte';
+  import ReviewPanel from './ReviewPanel.svelte';
+  
+  const signupPath = {
+    id: 'signup',
+    steps: [
+      { id: 'details', title: 'Your Details' },
+      { id: 'review', title: 'Review' }
+    ]
+  };
+  
+  function handleComplete(data) {
+    console.log('Completed!', data);
+  }
+</script>
+
+<PathShell
+  path={signupPath}
+  initialData={{ name: '', email: '' }}
+  oncomplete={handleComplete}
+>
+  {#snippet details()}
+    <DetailsForm />
+  {/snippet}
+  {#snippet review()}
+    <ReviewPanel />
+  {/snippet}
+</PathShell>
+```
+
+Each step is a **Svelte 5 snippet** whose name matches the step ID. PathShell collects them automatically and renders the active one.
+
+---
+
+## Simple vs Persisted
+
+PathShell supports two modes. Pick the one that fits your use case:
+
+### Simple — PathShell manages the engine
+
+Pass `path` and `initialData`. PathShell creates and starts the engine for you:
+
+```svelte
+<PathShell
+  path={signupPath}
+  initialData={{ name: '' }}
+  oncomplete={handleComplete}
+>
+  {#snippet details()}
+    <DetailsForm />
+  {/snippet}
+</PathShell>
+```
+
+**Use this when:** you don't need persistence, restoration, or custom observers. Quick prototypes, simple forms, one-off wizards.
+
+### Persisted — you create the engine
+
+Create the engine yourself with `restoreOrStart()` and pass it via `engine`. PathShell subscribes to it but does not start or own it:
+
+```svelte
+<script>
+  import { HttpStore, restoreOrStart, httpPersistence } from '@daltonr/pathwrite-store-http';
+
+  let engine = $state(null);
+
+  onMount(async () => {
+    const result = await restoreOrStart({
+      store: new HttpStore({ baseUrl: '/api/wizard' }),
+      key: 'user:onboarding',
+      path: signupPath,
+      initialData: { name: '' },
+      observers: [
+        httpPersistence({ store, key: 'user:onboarding', strategy: 'onNext' })
+      ]
+    });
+    engine = result.engine;
+  });
+</script>
+
+{#if engine}
+  <PathShell {engine} oncomplete={handleComplete}>
+    {#snippet details()}
+      <DetailsForm />
+    {/snippet}
+  </PathShell>
+{/if}
+```
+
+**Use this when:** you need auto-persistence, restore-on-reload, or custom observers. Production apps, checkout flows, anything where losing progress matters.
+
+> **Don't pass both.** `path` and `engine` are mutually exclusive. If you pass `engine`, PathShell will not call `start()` — it assumes the engine is already running.
+
+---
+
+## ⚠️ Step Components Must Use `getPathContext()`
+
+Step components rendered inside `<PathShell>` access the path engine via `getPathContext()` — **not** Svelte's raw `getContext()`.
+
+```svelte
+<script lang="ts">
+  // ✅ Correct — always use getPathContext()
+  import { getPathContext } from '@daltonr/pathwrite-svelte';
+  const { snapshot, setData } = getPathContext();
+
+  // ❌ Wrong — this will silently return undefined
+  // import { getContext } from 'svelte';
+  // const { snapshot, setData } = getContext('pathContext');
+</script>
+
+{#if $snapshot}
+  <input
+    value={$snapshot.data.name || ''}
+    oninput={(e) => setData('name', e.currentTarget.value)}
+  />
+{/if}
+```
+
+`getPathContext()` uses a `Symbol` key internally and throws a clear error if called outside a `<PathShell>`. Using `getContext()` with a string key will fail silently.
+
+---
+
+## API
+
+### `usePath<TData>(options?)`
+
+Create a Pathwrite engine with Svelte store bindings. Returns reactive stores and action methods.
+
+```typescript
+const {
+  snapshot,    // Readable<PathSnapshot | null>
+  start,       // (path, initialData?) => Promise<void>
+  next,        // () => Promise<void>
+  previous,    // () => Promise<void>
+  cancel,      // () => Promise<void>
+  setData,     // (key, value) => Promise<void>
+  // ... more actions
+} = usePath();
+```
+
+#### Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `engine` | `PathEngine` | External engine (e.g., from `restoreOrStart()`) |
+| `onEvent` | `(event) => void` | Called for every engine event |
+
+#### Returns
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `snapshot` | `Readable<PathSnapshot \| null>` | Current path state (reactive store) |
+| `start` | `function` | Start a path |
+| `startSubPath` | `function` | Launch a sub-path |
+| `next` | `function` | Go to next step |
+| `previous` | `function` | Go to previous step |
+| `cancel` | `function` | Cancel the path |
+| `goToStep` | `function` | Jump to step by ID |
+| `goToStepChecked` | `function` | Jump with guard checks |
+| `setData` | `function` | Update data |
+| `restart` | `function` | Restart the path |
+
+### `<PathShell>`
+
+Default UI shell with progress indicator and navigation buttons.
+
+#### Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `path` | `PathDefinition` | — | Path definition (for self-managed engine) |
+| `engine` | `PathEngine` | — | External engine (for persistence — see below) |
+| `initialData` | `PathData` | `{}` | Initial data |
+| `autoStart` | `boolean` | `true` | Auto-start on mount |
+| `backLabel` | `string` | `"Previous"` | Previous button label |
+| `nextLabel` | `string` | `"Next"` | Next button label |
+| `completeLabel` | `string` | `"Complete"` | Complete button label |
+| `cancelLabel` | `string` | `"Cancel"` | Cancel button label |
+| `hideCancel` | `boolean` | `false` | Hide cancel button |
+| `hideProgress` | `boolean` | `false` | Hide progress indicator |
+
+> **`path` vs `engine`:** Pass `path` for simple wizards where PathShell manages the engine. Pass `engine` when you create the engine yourself (e.g., via `restoreOrStart()` for persistence). These are mutually exclusive — don't pass both.
+
+#### Callbacks
+
+| Callback | Type | Description |
+|----------|------|-------------|
+| `oncomplete` | `(data) => void` | Called when path completes |
+| `oncancel` | `(data) => void` | Called when path is cancelled |
+| `onevent` | `(event) => void` | Called for every event |
+
+#### Snippets
+
+Step content is provided as Svelte 5 snippets. The snippet name must match the step ID:
+
+```svelte
+<PathShell path={myPath}>
+  {#snippet details()}
+    <DetailsStep />
+  {/snippet}
+  {#snippet review()}
+    <ReviewStep />
+  {/snippet}
+</PathShell>
+```
+
+You can also override the header and footer:
+
+```svelte
+<PathShell path={myPath}>
+  {#snippet header(snap)}
+    <h2>Step {snap.stepIndex + 1} of {snap.stepCount}</h2>
+  {/snippet}
+
+  {#snippet details()}
+    <DetailsStep />
+  {/snippet}
+
+  {#snippet footer(snap, actions)}
+    <button onclick={actions.previous} disabled={snap.isFirstStep}>
+      ← Back
+    </button>
+    <button onclick={actions.next} disabled={!snap.canMoveNext}>
+      {snap.isLastStep ? 'Finish' : 'Continue →'}
+    </button>
+  {/snippet}
+</PathShell>
+```
+
+### `getPathContext<TData>()`
+
+Get the path context from a parent `<PathShell>`. Use this inside step components.
+
+```svelte
+<script lang="ts">
+  import { getPathContext } from '@daltonr/pathwrite-svelte';
+  
+  const { snapshot, next, setData } = getPathContext();
+</script>
+
+{#if $snapshot}
+  <input
+    value={$snapshot.data.name || ''}
+    oninput={(e) => setData('name', e.currentTarget.value)}
+  />
+  <button onclick={next}>Next</button>
+{/if}
+```
+
+### `bindData(snapshot, setData, key)`
+
+Helper to create a two-way binding store.
+
+```svelte
+<script lang="ts">
+  import { usePath, bindData } from '@daltonr/pathwrite-svelte';
+  
+  const { snapshot, setData } = usePath();
+  const name = bindData(snapshot, setData, 'name');
+</script>
+
+<input bind:value={$name} />
+```
+
+## PathSnapshot
+
+The `snapshot` store contains the current path state:
+
+```typescript
+interface PathSnapshot {
+  pathId: string;
+  stepId: string;
+  stepIndex: number;
+  stepCount: number;
+  data: PathData;
+  nestingLevel: number;
+  isFirstStep: boolean;
+  isLastStep: boolean;
+  canMoveNext: boolean;
+  canMovePrevious: boolean;
+  isNavigating: boolean;
+  progress: number;  // 0-1
+  steps: Array<{ id: string; title?: string; status: 'completed' | 'current' | 'upcoming' }>;
+  validationMessages: string[];
+}
+```
+
+Access it via the store: `$snapshot`
+
+## Guards and Hooks
+
+Define validation and lifecycle logic in your path definition:
+
+```typescript
+const myPath = {
+  id: 'signup',
+  steps: [
+    {
+      id: 'details',
+      canMoveNext: (ctx) => ctx.data.name && ctx.data.email,
+      validationMessages: (ctx) => {
+        const errors = [];
+        if (!ctx.data.name) errors.push('Name is required');
+        if (!ctx.data.email) errors.push('Email is required');
+        return errors;
+      },
+      onEnter: (ctx) => {
+        console.log('Entered details step');
+      },
+      onLeave: (ctx) => {
+        console.log('Leaving details step');
+      }
+    },
+    { id: 'review' }
+  ]
+};
+```
+
+## Persistence
+
+Use with [@daltonr/pathwrite-store-http](../store-http) for automatic state persistence:
+
+```svelte
+<script lang="ts">
+  import { onMount } from 'svelte';
+  import { PathShell } from '@daltonr/pathwrite-svelte';
+  import { HttpStore, restoreOrStart, httpPersistence } from '@daltonr/pathwrite-store-http';
+  import DetailsForm from './DetailsForm.svelte';
+  import ReviewPanel from './ReviewPanel.svelte';
+  
+  const store = new HttpStore({ baseUrl: '/api/wizard' });
+  const key = 'user:123:signup';
+  
+  let engine = $state(null);
+  let restored = $state(false);
+  
+  onMount(async () => {
+    const result = await restoreOrStart({
+      store,
+      key,
+      path: signupPath,
+      initialData: { name: '', email: '' },
+      observers: [
+        httpPersistence({ store, key, strategy: 'onNext' })
+      ]
+    });
+    engine = result.engine;
+    restored = result.restored;
+  });
+</script>
+
+{#if engine}
+  <PathShell {engine} oncomplete={(data) => console.log('Done!', data)}>
+    {#snippet details()}
+      <DetailsForm />
+    {/snippet}
+    {#snippet review()}
+      <ReviewPanel />
+    {/snippet}
+  </PathShell>
+{/if}
+```
+
+## TypeScript
+
+Type your path data for full type safety:
+
+```typescript
+interface SignupData {
+  name: string;
+  email: string;
+  age: number;
+}
+
+const { snapshot, setData } = usePath<SignupData>();
+
+// ✅ Type-checked
+setData('name', 'John');
+
+// ❌ Type error
+setData('invalid', 'value');
+```
+
+## License
+
+MIT
+
+## See Also
+
+- [@daltonr/pathwrite-core](../core) - Core engine
+- [@daltonr/pathwrite-store-http](../store-http) - HTTP persistence
+- [Documentation](../../docs/guides/DEVELOPER_GUIDE.md)
+

package/dist/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/dist/PathShell.svelte.d.ts

@@ -0,0 +1,24 @@
+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;
+    oncomplete?: (data: PathData) => void;
+    oncancel?: (data: PathData) => void;
+    onevent?: (event: any) => void;
+    header?: Snippet<[PathSnapshot<any>]>;
+    footer?: Snippet<[PathSnapshot<any>, object]>;
+    [key: string]: Snippet | any;
+}
+declare const PathShell: import("svelte").Component<Props, {}, "">;
+type PathShell = ReturnType<typeof PathShell>;
+export default PathShell;
+//# sourceMappingURL=PathShell.svelte.d.ts.map

package/dist/PathShell.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PathShell.svelte.d.ts","sourceRoot":"","sources":["../src/PathShell.svelte.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,QAAQ,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAC5F,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAGpC,UAAU,KAAK;IACb,IAAI,CAAC,EAAE,cAAc,CAAC,GAAG,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,WAAW,CAAC,EAAE,QAAQ,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,YAAY,CAAC,EAAE,OAAO,CAAC;IAEvB,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,QAAQ,KAAK,IAAI,CAAC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;IAE/B,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;IACtC,MAAM,CAAC,EAAE,OAAO,CAAC,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAE9C,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,GAAG,CAAC;CAC9B;AAmJH,QAAA,MAAM,SAAS,2CAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}