@habit.analytics/habit-claims-journey-components 1.1.13 → 2.1.0

package/README.md

@@ -1,33 +1,36 @@
 # Journey Builder & Form Runner
 
-A visual graph-based form builder and step-by-step form runner, built as two independent, embeddable React widgets.
+A linear, step-based form configurator and a self-contained form runner, distributed as two embeddable React widgets.
 
-**Builder** — drag-and-drop field specs onto a canvas, connect them with conditional edges, and export a portable `JourneySpec` JSON.
+- **Builder (`JourneyBuilderWidget`)** — configure a journey as ordered **Steps → Rows → Fields**, define per-step **navigation rules** (JSON Logic) and optional **API calls**, plus a **Summary** panel and **Init** values. Outputs a portable `JourneySpec` (v2.0).
+- **Runner (`FormRunnerWidget`)** — feeds that `JourneySpec` to a step-by-step engine that evaluates conditions, optionally calls APIs between steps (delegated to the host), collects answers, and renders a review/summary screen.
 
-**Runner** — feed that JSON into a self-contained form engine that navigates users through the journey, evaluates branching conditions, and collects answers.
+> **v2.0 — breaking change vs v1.x.** The visual graph canvas (React Flow / `@xyflow/react`) has been removed. Legacy v1.x journeys (`nodes`/`edges`) are still accepted and auto-converted on import for read-only consumption, but new journeys are authored against the **`form_config`** model described below.
 
 ---
 
 ## Architecture
 
 ```
-┌─────────────────────────────────────────────────────┐
-│                  Host Application                   │
-│                                                     │
-│  ┌──────────────────────┐  ┌──────────────────────┐ │
-│  │ JourneyBuilderWidget │  │  FormRunnerWidget     │ │
-│  │                      │  │                       │ │
-│  │  specs ──► Catalog   │  │  journey ──► Engine   │ │
-│  │            Canvas    │  │              Widgets   │ │
-│  │            Props     │  │              History   │ │
-│  │                      │  │              Summary   │ │
-│  │  onSave(journey) ◄── │  │  onSubmit(answers) ◄─ │ │
-│  │  onChange(journey) ◄─ │  │                       │ │
-│  └──────────────────────┘  └──────────────────────┘ │
-│                                                     │
-│         Both consume JourneySpec + types from        │
-│              src/types/journey.ts                    │
-└─────────────────────────────────────────────────────┘
+┌─────────────────────────────────────────────────────────────┐
+│                     Host Application                        │
+│                                                             │
+│  ┌──────────────────────────┐   ┌────────────────────────┐  │
+│  │  JourneyBuilderWidget    │   │   FormRunnerWidget     │  │
+│  │                          │   │                        │  │
+│  │  specs    ──► Catalog    │   │  journey ──► Engine    │  │
+│  │  journey  ──► Editor     │   │  initialAnswers ──►    │  │
+│  │              Steps/Rows  │   │              prefill    │  │
+│  │              Fields tab  │   │  onStepApiCall ◄────   │  │
+│  │              Init / JSON │   │  onStepApiError ◄────  │  │
+│  │              Summary     │   │  onFileSelect ◄────    │  │
+│  │  onSave / onPublish ──►  │   │  onSubmit(answers) ──► │  │
+│  │  onChange ──►            │   │  onSave (draft) ──►    │  │
+│  └──────────────────────────┘   └────────────────────────┘  │
+│                                                             │
+│       Both consume `JourneySpec` + types from               │
+│                  `src/types/journey.ts`                     │
+└─────────────────────────────────────────────────────────────┘
 ```
 
 ---
@@ -37,69 +40,86 @@ A visual graph-based form builder and step-by-step form runner, built as two ind
 | Layer | Technology |
 |---|---|
 | UI framework | React 18 + TypeScript |
-| Graph canvas | `@xyflow/react` (React Flow v12) |
-| State management | Zustand (scoped per widget instance) |
-| Edge conditions | `json-logic-js` |
-| Styling | Tailwind CSS + shadcn/ui |
+| State management | Zustand (scoped per widget instance, 50-step undo/redo, dirty tracking) |
+| Condition engine | `json-logic-js` |
+| Styling | Tailwind CSS (prefixed `cj-`) + scoped CSS variables (`--claims-journey-*`) |
 | Build tool | Vite |
 
+Peer deps: `react`, `react-dom`. The previous `@xyflow/react` peer dep has been **removed** in v2.0.
+
 ---
 
 ## Quick Start
 
 ```bash
-# Clone and install
-git clone <YOUR_GIT_URL>
-cd journey-builder
 npm install
-
-# Start dev server
 npm run dev
 ```
 
-The demo app runs at `http://localhost:5173`:
-- `/` — Builder with sample property specs
-- `/runner` — Runner loaded from the builder's current graph
+Demo app at `http://localhost:5173`:
+- `/` — Builder with sample specs
+- `/runner` — Runner loaded from the builder's current journey
 
 ---
 
 ## Installation (as a library)
 
 ```bash
-npm install journey-builder
+npm install habit-claims-journey-components
 ```
 
-```typescript
+```tsx
 import {
   JourneyBuilderWidget,
   FormRunnerWidget,
-} from 'journey-builder';
+} from 'habit-claims-journey-components';
 
 import type {
   JourneySpec,
   ClaimPropertySpec,
-} from 'journey-builder';
+  FormConfig,
+  EnrichedAnswer,
+  StepApiRequest,
+  InitApiRequest,
+} from 'habit-claims-journey-components';
 ```
 
+CSS is auto-injected — **do not import a separate `style.css`**.
+
+The parent of `JourneyBuilderWidget` must have an explicit height (the widget fills `100%`).
+
+See [INTEGRATION.md](./INTEGRATION.md) for full install methods and copy-paste setup.
+
 ---
 
 ## Usage
 
 ### JourneyBuilderWidget
 
-The visual graph editor. Provide field specifications and receive the journey graph via callbacks.
-
 ```tsx
-import { JourneyBuilderWidget } from 'journey-builder';
-
-function BuilderPage({ specs, existingJourney }) {
+import { JourneyBuilderWidget } from 'habit-claims-journey-components';
+import type { ClaimPropertySpec, JourneySpec } from 'habit-claims-journey-components';
+
+function BuilderPage({
+  specs,
+  existing,
+}: {
+  specs: ClaimPropertySpec[];
+  existing?: JourneySpec | null;
+}) {
   return (
-    <JourneyBuilderWidget
-      specs={specs}
-      journey={existingJourney}
-      onSave={(journey) => saveToApi(journey)}
-      onChange={(journey) => console.log('Graph changed', journey)}
-    />
+    <div style={{ width: '100%', height: '100vh' }}>
+      <JourneyBuilderWidget
+        specs={specs}
+        journey={existing}
+        onSave={(spec) => saveDraft(spec)}
+        onPublish={(spec) => publish(spec)}
+        onChange={(spec) => console.log('changed', spec)}
+        onOpenRunner={() => navigate('/runner')}
+        readOnly={false}
+        googleMapsApiKey={import.meta.env.VITE_GOOGLE_MAPS_KEY}
+      />
+    </div>
   );
 }
 ```
@@ -108,25 +128,48 @@ function BuilderPage({ specs, existingJourney }) {
 
 | Prop | Type | Required | Description |
 |---|---|---|---|
-| `specs` | `ClaimPropertySpec[]` | ✅ | Field specifications shown in the drag-and-drop catalog |
-| `journey` | `JourneySpec \| null` | — | Existing journey to load on mount |
-| `onSave` | `(spec: JourneySpec) => void` | — | Called when the user clicks Export/Save |
-| `onChange` | `(spec: JourneySpec) => void` | — | Called on every graph mutation (node/edge add, move, delete, edit) |
+| `specs` | `ClaimPropertySpec[]` | — | Field specifications shown in the catalog and "Add field" dialogs |
+| `journey` | `JourneySpec \| null` | — | Existing journey to load on mount. v1.x graph and v2.x `form_config` both accepted |
+| `onSave` | `(spec: JourneySpec) => void` | — | Fired by the Save button. Marks the store as clean |
+| `onPublish` | `(spec: JourneySpec) => void` | — | Fired by the Publish button |
+| `onChange` | `(spec: JourneySpec) => void` | — | Fired on every config mutation (steps/rows/fields/navigation/summary/init/theme) |
+| `onUnlockEdit` | `() => void` | — | Shown as "Unlock edit" when `readOnly` is `true` |
+| `onOpenRunner` | `() => void` | — | Shown as a "Preview" button in the header |
+| `readOnly` | `boolean` | — | Disables editing, hides destructive controls, surfaces the unlock action |
+| `googleMapsApiKey` | `string` | — | Enables the Google Places address widget in previews |
+
+The builder UI exposes four tabs: **Steps**, **Fields**, **Init**, **JSON**.
 
 ---
 
 ### FormRunnerWidget
 
-The step-by-step form engine. Provide a journey spec and receive collected answers.
-
 ```tsx
-import { FormRunnerWidget } from 'journey-builder';
+import { FormRunnerWidget } from 'habit-claims-journey-components';
+import type { JourneySpec, StepApiRequest } from 'habit-claims-journey-components';
 
-function RunnerPage({ journey }) {
+function RunnerPage({ journey }: { journey: JourneySpec }) {
   return (
     <FormRunnerWidget
       journey={journey}
+      initialAnswers={{ /* optional pre-fill */ }}
+      enrichedOutput
       onSubmit={(answers) => submitToApi(answers)}
+      onSave={(partial) => saveDraft(partial)}
+      onFileSelect={async (file, key) => uploadToS3(file, key)}
+      onStepApiCall={async (req: StepApiRequest) => {
+        const res = await fetch(req.url, {
+          method: req.method,
+          headers: { 'Content-Type': 'application/json', ...req.headers },
+          body: req.body ? JSON.stringify(req.body) : undefined,
+        });
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      }}
+      onStepApiError={(err, req) => trackError(err, req)}
+      onInitApiCall={async (req) => (await fetch(req.url, { method: req.method, headers: req.headers })).json()}
+      googleMapsApiKey={import.meta.env.VITE_GOOGLE_MAPS_KEY}
+      fullScreen
     />
   );
 }
@@ -136,120 +179,271 @@ function RunnerPage({ journey }) {
 
 | Prop | Type | Required | Description |
 |---|---|---|---|
-| `journey` | `JourneySpec` | ✅ | The journey graph to run |
-| `specs` | `ClaimPropertySpec[]` | — | Optional specs for label/schema lookups |
-| `onSubmit` | `(answers: Record<string, unknown>) => void` | — | Called on form submission. Defaults to copying JSON to clipboard |
+| `journey` | `JourneySpec` | ✅ | The journey to run. v1.x or v2.x |
+| `onSubmit` | `(answers: Record<string, unknown>) => void` | — | Called when the user confirms the summary screen. Defaults to copying JSON to clipboard |
+| `onSave` | `(partial: Record<string, unknown>) => void` | — | Called whenever the user reaches a checkpoint mid-journey, suitable for draft persistence |
+| `onFileSelect` | `(file: File, questionKey: string) => Promise<string \| UploadResult \| void> \| void` | — | Host-side upload handler for upload widgets. Returns a URL or `{ url, name, ... }` |
+| `onStepApiCall` | `(req: StepApiRequest) => Promise<unknown>` | — | **Recommended.** Delegates per-step API calls to the host (auth, CORS, retries, telemetry). Return value is stored as that step's `api_response` and is referenceable from later JSON Logic and the Summary |
+| `onStepApiError` | `(err: unknown, req: StepApiRequest) => void` | — | Called when a step API call fails. When provided, the runner skips its default error toast. Fires regardless of the `on_error` policy. Exceptions thrown by this handler are caught and logged — they never crash the runner |
+| `onInitApiCall` | `(req: InitApiRequest) => Promise<unknown>` | — | Delegates the optional init/prefill API call to the host |
+| `initialAnswers` | `Record<string, unknown>` | — | Seeds the runner with existing values. The engine walks forward until it hits the first unanswered question, or straight to the summary if everything is filled |
+| `enrichedOutput` | `boolean` | — | When `true`, `onSubmit` receives `{ [key]: { data, schema } }` instead of the flat answers map |
+| `googleMapsApiKey` | `string` | — | Enables the Google Places address widget |
+| `fullScreen` | `boolean` | — | Renders the runner full-viewport (otherwise it fills its parent) |
+
+##### `StepApiRequest`
+
+```ts
+type StepApiRequest = {
+  step_id: string;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  url: string;
+  headers: Record<string, string>;
+  body?: unknown;                          // already-interpolated JSON
+  answers: Record<string, unknown>;        // current answers snapshot
+};
+```
 
----
+##### `InitApiRequest`
 
-## Data Types
+```ts
+type InitApiRequest = {
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  url: string;
+  headers?: Record<string, string>;
+};
+```
 
-### `ClaimPropertySpec`
+##### Step API `on_error` policy
 
-A field definition from your data model.
+Each step's `navigation.api_call.on_error` controls what happens when the call (or `onStepApiCall`) throws:
 
-```typescript
-interface ClaimPropertySpec {
-  id: string;
-  namespace: string;         // e.g. "insured.full_name"
-  claimspec_id: string;
-  parent_id: string | null;
-  order_index: number;
-  schema: string;            // e.g. "v1_string", "v2_date-1", "v2_currency-1"
-  label: string;             // Human-readable label
-  options: ClaimPropertySpecOption[] | null;
-  help_text: string | null;
-  placeholder: string | null;
-  // ...additional display fields
-}
-```
+| Value | Behavior |
+|---|---|
+| `block` *(default)* | Stay on the current step, surface an error. `apiResponses[step_id]` is left untouched (preserves any previous successful response) |
+| `continue` | Proceed using the step's navigation rules. `api_response` for this step stays unset; any previous successful value is preserved |
+| `goto:<step_id>` | Jump straight to the given step (e.g. an error screen), bypassing rules |
+
+`onStepApiError` is always called when present, regardless of policy. If the handler itself throws, the runner catches the error, logs it (`onStepApiError handler threw`), and still honors the configured `on_error` policy.
+
+---
 
-### `JourneySpec`
+## Data Model — `JourneySpec` (v2.0)
 
-The portable journey graph format — output of the Builder, input of the Runner.
+A `JourneySpec` is a portable envelope that wraps a `form_config` plus journey-level metadata.
 
-```typescript
+```ts
 interface JourneySpec {
   journey_id: string;
   claimspec_id: string;
-  version: string;
-  nodes: JourneySpecNode[];
-  edges: JourneySpecEdge[];
-  start_node_id: string | null;
+  version: string;             // "2.0.x" for the linear model
+  form_config: FormConfig;     // ◀ the new authoring model
+  theme?: JourneyTheme;
+  mode?: JourneyMode;
+
+  // Legacy v1.x — preserved when re-exporting an imported v1 spec.
+  nodes?: JourneySpecNode[];
+  edges?: JourneySpecEdge[];
+  start_node_id?: string | null;
+}
+```
+
+### `FormConfig`
+
+```ts
+interface FormConfig {
+  steps: FormStep[];               // ordered
+  fields: FormField[];             // flat catalog, referenced by id
+  summary: SummaryPanelConfig;
+  init: InitConfig;
 }
 ```
 
-### `JourneySpecNode`
-
-```typescript
-interface JourneySpecNode {
-  node_id: string;
-  question_key: string;                    // Namespace used as answer key
-  source_property_spec_id: string;
-  schema: string;
-  options?: ClaimPropertySpecOption[];
-  actor: 'customer' | 'operator';
-  bindings: { target_namespace: string }[];
-  ui: { widget: string };
-  layout: { x: number; y: number };
-  label_override?: string;
+### `FormStep`
+
+```ts
+interface FormStep {
+  step_id: string;
+  title: string;
+  description?: string;
+  rows: FormRow[];                 // each row has field_ids[]
+  navigation: {
+    api_call?: StepApiCall;        // fired when leaving the step
+    rules: NavRule[];              // JSON Logic; first match wins
+    button_label?: string;
+  };
+}
+```
+
+### `NavRule`
+
+```ts
+interface NavRule {
+  rule_id: string;
+  condition: Record<string, unknown> | null;   // null = always (default)
+  next_step_id: string;                        // or "__submit__"
+  priority?: number;
+}
+```
+
+### `StepApiCall`
+
+```ts
+interface StepApiCall {
+  enabled: boolean;
+  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+  url: string;
+  headers?: Record<string, string>;
+  body_template?: string;          // tokens like {{answers.foo}} interpolated by the runner
+  on_error?: 'block' | 'continue' | `goto:${string}`;   // defaults to 'block'
+}
+```
+
+### `FormField`
+
+```ts
+interface FormField {
+  field_id: string;
+  namespace: string;               // answer key
+  label: string;
+  labelOverride?: string;
+  specId?: string;                 // or "custom"
+  schema: string;                  // e.g. "v1_string", "v2_date-1"
+  options?: ClaimPropertySpecOption[] | null;
+  widget?: string;                 // override (e.g. "email", "textarea")
   required?: boolean;
+  actor?: 'customer' | 'operator';
+  bindings?: { target_namespace: string }[];
+  uploadConfig?: UploadConfig;
+  allowFuture?: boolean;
+  placeholder?: string;
+  helpText?: string;
+}
+```
+
+### `SummaryPanelConfig`
+
+```ts
+interface SummaryPanelConfig {
+  title: string;
+  show_pricing?: boolean;
+  sections: SummarySection[];
+}
+
+interface SummarySection {
+  section_id: string;
+  title: string;
+  visible_from_step?: number;      // 1-based
+  until_step?: number;             // 1-based
+  display_fields: SummaryDisplayField[];
+}
+
+interface SummaryDisplayField {
+  display_id: string;
+  source: 'form_field' | 'api_response';
+  field_id?: string;               // when source === 'form_field'
+  step_id?: string;                // when source === 'api_response'
+  response_path?: string;          // dot-path inside api_response
+  label: string;
+  format?: 'text' | 'date' | 'datetime' | 'currency' | 'number';
 }
 ```
 
-### `JourneySpecEdge`
+### `InitConfig`
+
+```ts
+interface InitConfig {
+  values: Record<string, unknown>;
+  api?: {
+    enabled: boolean;
+    method: 'GET' | 'POST';
+    url: string;
+    headers?: Record<string, string>;
+    mapping?: Record<string, string>;   // namespace -> response_path
+  };
+}
+```
 
-```typescript
-interface JourneySpecEdge {
-  edge_id: string;
-  from_node_id: string;
-  to_node_id: string;
-  condition: Record<string, unknown> | null;  // JSON Logic expression
-  priority: number;
-  is_default: boolean;
+### `JourneyTheme`
+
+CSS variables injected on the runner/builder root, overriding `--claims-journey-*` defaults. Colors are **HSL triplets** (e.g. `"222 47% 11%"`).
+
+```ts
+interface JourneyTheme {
+  primaryColor?: string;
+  backgroundColor?: string;
+  cardColor?: string;
+  foregroundColor?: string;
+  fontFamilyHeading?: string;
+  fontFamilyBody?: string;
+  fontSizeBase?: number;     // px
+  borderRadius?: number;     // rem
+  spacing?: 'compact' | 'cozy' | 'spacious';
 }
 ```
 
 ---
 
+## JSON Schema validation
+
+Draft-07 JSON Schemas describing `FormConfig` and `JourneySpec` v2 ship with the package and are re-exported as plain objects:
+
+```ts
+import Ajv from 'ajv';
+import { formConfigSchema, journeySpecSchema } from 'habit-claims-journey-components';
+
+const ajv = new Ajv({ allErrors: true, strict: false });
+ajv.addSchema(formConfigSchema);          // resolved by $id from journeySpecSchema
+const validate = ajv.compile(journeySpecSchema);
+
+if (!validate(spec)) console.error(validate.errors);
+```
+
+Schema sources:
+- [`src/schemas/form-config.schema.json`](./src/schemas/form-config.schema.json)
+- [`src/schemas/journey-spec.schema.json`](./src/schemas/journey-spec.schema.json)
+
+See [docs/SCHEMAS.md](./docs/SCHEMAS.md) for the full reference of required fields, types, and enumerations.
+
+---
+
 ## Supported Schema Types
 
 | Schema | Widget | Validation |
 |---|---|---|
 | `v1_string` | Text input | — |
 | `v2_single_option_select-1` | Dropdown select | Must pick an option |
-| `v2_date-1` | Date picker | Valid date |
+| `v2_date-1` | Date picker | Valid date; `allowFuture` controls future dates |
 | `v2_currency-1` | Currency input | Numeric |
-| `v2_single_asset_upload` | File upload | — |
+| `v2_single_asset_upload` | File upload (via `onFileSelect`) | Type/size from `uploadConfig` |
 | `v2_phone-1` | Phone with country code | Length check |
 | `v2_email-1` | Email input | Format regex |
 
-Nodes support **widget overrides** — any field can adopt a different widget (e.g., a string field rendered as an email input).
+Fields can override the default widget via `widget` (e.g. a `v1_string` rendered as `"textarea"` or `"email"`).
 
 ---
 
 ## Builder Features
 
-- **Drag-and-drop** specs from a searchable, filterable catalog
-- **Custom nodes** — create fields not tied to existing specs
-- **Visual edge condition editor** — AND/OR rules with comparison operators
-- **Advanced JSON Logic mode** — direct editing for complex conditions
-- **Condition testing panel** — validate edge logic with sample data
-- **Graph validation** — detects loops, orphans, missing conditions, duplicate bindings
-- **Auto-layout** — automatic graph arrangement
-- **Keyboard shortcuts** — Delete, Ctrl+Z/Y (undo/redo), Ctrl+C/V (copy/paste), Ctrl+D (duplicate)
-- **Import/Export** — full-fidelity JourneySpec JSON via file upload or paste
-- **Path highlighting** — visual tracking during preview
+- **Steps tab** — three-pane layout (Steps list / Step editor / Summary editor) with drag-and-drop rows and inline field reuse from the catalog
+- **Fields tab** — global catalog with Used/Unused filter and quick-jump chips that take you straight to the Step using each field
+- **Init tab** — static initial values + optional prefill API call mapping (`namespace → response_path`)
+- **JSON tab** — full `JourneySpec` view with copy / download / paste-to-import escape hatch
+- **Per-step API calls** — method, URL, headers, JSON body template (`{{answers.foo}}`), and `on_error` policy
+- **Per-step navigation rules** — JSON Logic conditions, priority, `__submit__` target
+- **Theme panel** — primary/background/card/foreground colors, fonts, base size, radius, spacing scale
+- **Persistence** — dirty-state tracking, Save / Publish, 50-action undo/redo, read-only mode with unlock action
 
 ## Runner Features
 
-- **Step-by-step navigation** with progress bar
-- **Conditional branching** — JSON Logic evaluation at each edge
-- **Answer history** — scrollable list with jump-back navigation
-- **Schema-aware widgets** — renders the correct input for each field type
-- **Required field enforcement** — blocks navigation until valid
-- **Review screen** — summary of all answers before submission
-- **Bindings propagation** — answers auto-mapped to target namespaces
+- **Step-by-step navigation** with non-destructive back/forward and mid-journey draft persistence (via `initialAnswers`)
+- **Auto-progression** through steps whose only effect is a navigation rule
+- **JSON Logic** evaluation against `{ answers, api_responses }`
+- **Host-delegated APIs** — per-step (`onStepApiCall`) and init (`onInitApiCall`), with three `on_error` policies
+- **File upload** — async `onFileSelect` returning a URL or rich `UploadResult`
+- **Schema-aware widgets** with mobile-first touch targets (48px min) and iOS-zoom-safe inputs
+- **Vertical summary screen** rendering the configured `SummaryPanelConfig`
+- **Enriched output** — `enrichedOutput` flag wraps each answer as `{ data, schema }`
 
 ---
 
@@ -257,40 +451,341 @@ Nodes support **widget overrides** — any field can adopt a different widget (e
 
 ```
 src/
-├── index.ts                          # Barrel exports
-├── types/journey.ts                  # Shared types & schema helpers
+├── index.ts                                # Barrel exports
+├── types/journey.ts                        # Public types & helpers
 ├── components/
-│   ├── journey-builder/
-│   │   ├── JourneyBuilderWidget.tsx  # ◀ Entry point widget
-│   │   ├── JourneyBuilder.tsx        # Layout (catalog + canvas + props panel)
-│   │   ├── JourneyCanvas.tsx         # React Flow canvas
-│   │   ├── QuestionNode.tsx          # Custom node component
-│   │   ├── SpecsCatalog.tsx          # Draggable spec list
-│   │   ├── PropertiesPanel.tsx       # Node/edge property editors
-│   │   ├── NodePropertiesEditor.tsx
-│   │   ├── EdgePropertiesEditor.tsx
-│   │   ├── ConditionalEdge.tsx       # Custom edge with labels
-│   │   ├── CreateNodeDialog.tsx      # Custom field creation
-│   │   ├── ImportJourneyDialog.tsx
-│   │   ├── FormPreviewPanel.tsx      # Inline preview
-│   │   ├── GraphValidationPanel.tsx  # Validation results
-│   │   ├── edge-editor/             # Condition editing components
-│   │   └── preview-widgets/         # Schema-specific input widgets
+│   ├── form-configurator/                  # ◀ v2.0 Builder
+│   │   ├── JourneyBuilderWidget.tsx        # Entry point
+│   │   ├── FormConfigurator.tsx            # Tabs + layout
+│   │   ├── steps/                          # Steps tab
+│   │   ├── fields/                         # Fields tab (Used/Unused filter)
+│   │   ├── init/                           # Init tab
+│   │   ├── json/                           # JSON tab
+│   │   └── summary/                        # Summary editor
 │   ├── runner/
-│   │   ├── FormRunnerWidget.tsx      # ◀ Entry point widget
-│   │   └── AnswerHistoryList.tsx
-│   └── ui/                          # shadcn/ui components
+│   │   └── FormRunnerWidget.tsx            # ◀ Runner entry point
+│   ├── journey-builder/                    # Shared previews, theme panel, portal context
+│   │   └── preview-widgets/                # Schema-specific widgets
+│   └── ui/                                 # shadcn/ui primitives
 ├── stores/
-│   └── journeyBuilderStore.ts       # Zustand store (internal)
+│   └── formConfiguratorStore.ts            # Zustand store + legacy converter
 ├── lib/
-│   └── graph-validation.ts          # Validation engine
-└── pages/                           # Demo app pages
+│   └── theme-css.ts                        # CSS-variable builder for JourneyTheme
+└── pages/                                  # Demo app
     ├── Index.tsx
     └── Runner.tsx
 ```
 
 ---
 
+## Migration v1 → v2
+
+v2.0 replaces the React Flow graph canvas with a linear **Steps → Rows → Fields** configurator. Legacy v1.x specs (`nodes`/`edges`/`start_node_id`) are still accepted on import and auto-converted to a `form_config`.
+
+### Removed dependency
+
+```diff
+- "@xyflow/react": "^12.x"   // no longer a peer dependency
+```
+
+### CSS
+
+```diff
+- import 'habit-claims-journey-components/style.css';
++ // CSS is auto-injected by the bundle — no separate import needed
+```
+
+### `JourneyBuilderWidget` props
+
+| v1.x | v2.x | Notes |
+|---|---|---|
+| `specs` | `specs` | Unchanged |
+| `journey` | `journey` | Accepts both v1 and v2 shapes |
+| `onSave(spec)` | `onSave(spec)` | Now also marks the store as clean |
+| — | `onPublish(spec)` | **New** — dedicated publish action |
+| — | `onChange(spec)` | **New** — fires on every mutation |
+| — | `onOpenRunner()` | **New** — header "Preview" button |
+| — | `readOnly` | **New** — disables editing |
+| — | `onUnlockEdit()` | **New** — shown when `readOnly` is on |
+| — | `googleMapsApiKey` | **New** — enables Location widget previews |
+| `onNodeClick`, `onEdgeClick`, `nodeTypes`, `edgeTypes` | — | **Removed** (no canvas) |
+
+```diff
+  <JourneyBuilderWidget
+    specs={specs}
+    journey={existing}
+    onSave={spec => save(spec)}
++   onPublish={spec => publish(spec)}
++   onChange={spec => setDraft(spec)}
++   onOpenRunner={() => navigate('/runner')}
++   readOnly={false}
++   googleMapsApiKey={import.meta.env.VITE_GOOGLE_MAPS_KEY}
+  />
+```
+
+### `FormRunnerWidget` props
+
+| v1.x | v2.x | Notes |
+|---|---|---|
+| `journey` | `journey` | Now drives `form_config` (or auto-converted legacy graph) |
+| `onSubmit(answers)` | `onSubmit(answers)` | Set `enrichedOutput` for `{ data, schema }` shape |
+| `onFileSelect(file, key)` | `onFileSelect(file, key)` | May now return `UploadResult` `{ url, filename, mimetype?, size? }` |
+| `onApiCall(req)` | **`onStepApiCall(req: StepApiRequest)`** | Renamed; request includes `step_id` and `answers` snapshot |
+| — | `onStepApiError(err, req)` | **New** — suppresses the default error toast; safe even if it throws |
+| — | `onInitApiCall(req: InitApiRequest)` | **New** — host-delegated init/prefill call |
+| — | `onSave(partial)` | **New** — mid-journey draft persistence |
+| `initialValues` | **`initialAnswers`** | Renamed for consistency with the engine |
+| — | `enrichedOutput` | **New** — wraps every answer as `{ data, schema }` |
+| — | `fullScreen` | **New** — viewport-fill layout |
+| `mode`, `groups` | — | Ignored; layout is now driven by `form_config.steps`/`rows` |
+
+```diff
+  <FormRunnerWidget
+    journey={journey}
+-   initialValues={draft}
++   initialAnswers={draft}
++   enrichedOutput
+-   onApiCall={async (req) => fetchJson(req.url, req)}
++   onStepApiCall={async (req) => fetchJson(req.url, req)}
++   onStepApiError={(err, req) => logger.warn(err, req)}
++   onInitApiCall={async (req) => fetchJson(req.url, req)}
++   onSave={(partial) => saveDraft(partial)}
+    onSubmit={(answers) => submit(answers)}
+  />
+```
+
+### `JourneySpec` shape
+
+```diff
+  {
+    "journey_id": "j-001",
+    "claimspec_id": "cs-001",
+-   "version": "1.0",
+-   "nodes": [ /* JourneySpecNode[] */ ],
+-   "edges": [ /* JourneySpecEdge[] */ ],
+-   "start_node_id": "node-1",
+-   "mode": "sequential",
+-   "groups": []
++   "version": "2.0",
++   "form_config": {
++     "steps":   [ /* FormStep[]  — rows -> field_ids */ ],
++     "fields":  [ /* FormField[] — flat catalog */ ],
++     "summary": { "title": "Review", "sections": [] },
++     "init":    { "values": {} }
++   }
+  }
+```
+
+Importing a v1 spec is transparent: the store converts `nodes`/`edges` to `form_config` on load. Re-exporting preserves the legacy fields for downstream consumers that still read them.
+
+### Step API errors
+
+v1 always blocked navigation on a failing API call. v2 introduces an explicit per-step policy on `navigation.api_call.on_error`:
+
+| Value | Behavior |
+|---|---|
+| `block` *(default)* | Stay on the step; `apiResponses[step_id]` is preserved |
+| `continue` | Run navigation rules; `api_response` for this step stays unset |
+| `goto:<step_id>` | Jump to the named step (e.g. an error screen) |
+
+---
+
+## Full Examples
+
+### Minimal `FormConfig`
+
+A two-step journey with a select that branches to a follow-up step or skips to submit.
+
+```json
+{
+  "steps": [
+    {
+      "step_id": "step-vehicle",
+      "title": "Your vehicle",
+      "rows": [
+        { "row_id": "r1", "layout": "vertical", "field_ids": ["f-plate", "f-has-damage"] }
+      ],
+      "navigation": {
+        "rules": [
+          {
+            "rule_id": "rule-damage",
+            "condition": { "==": [{ "var": "answers.vehicle.has_damage" }, "yes"] },
+            "next_step_id": "step-damage",
+            "priority": 10
+          },
+          { "rule_id": "rule-default", "condition": null, "next_step_id": "__submit__" }
+        ]
+      }
+    },
+    {
+      "step_id": "step-damage",
+      "title": "Describe the damage",
+      "rows": [{ "row_id": "r2", "layout": "vertical", "field_ids": ["f-damage-notes"] }],
+      "navigation": {
+        "rules": [{ "rule_id": "r-end", "condition": null, "next_step_id": "__submit__" }]
+      }
+    }
+  ],
+  "fields": [
+    { "field_id": "f-plate", "namespace": "vehicle.plate", "label": "License plate", "schema": "v1_string", "required": true },
+    {
+      "field_id": "f-has-damage",
+      "namespace": "vehicle.has_damage",
+      "label": "Is the vehicle damaged?",
+      "schema": "v2_single_option_select-1",
+      "required": true,
+      "options": [
+        { "data": "yes", "label": "Yes" },
+        { "data": "no",  "label": "No" }
+      ]
+    },
+    { "field_id": "f-damage-notes", "namespace": "vehicle.damage_notes", "label": "Damage description", "schema": "v1_string", "widget": "textarea" }
+  ],
+  "summary": {
+    "title": "Review your claim",
+    "sections": [
+      {
+        "section_id": "sec-vehicle",
+        "title": "Vehicle",
+        "display_fields": [
+          { "display_id": "d-plate",  "source": "form_field", "field_id": "f-plate",        "label": "Plate" },
+          { "display_id": "d-damage", "source": "form_field", "field_id": "f-damage-notes", "label": "Damage" }
+        ]
+      }
+    ]
+  },
+  "init": { "values": { "vehicle.country": "BR" } }
+}
+```
+
+### Full `JourneySpec` with API call + init prefill
+
+Per-step `api_call` with `on_error: "goto:..."`, a summary section reading from `api_response`, and an `init.api` prefill.
+
+```json
+{
+  "journey_id": "j-auto-claim-001",
+  "claimspec_id": "cs-auto-1",
+  "version": "2.0",
+  "form_config": {
+    "steps": [
+      {
+        "step_id": "step-id",
+        "title": "Find your policy",
+        "rows": [{ "row_id": "r1", "layout": "horizontal", "field_ids": ["f-doc"] }],
+        "navigation": {
+          "api_call": {
+            "enabled": true,
+            "method": "POST",
+            "url": "https://api.example.com/policies/lookup",
+            "headers": { "x-tenant": "acme" },
+            "body_template": "{\"document\":\"{{answers.customer.document}}\"}",
+            "on_error": "goto:step-not-found"
+          },
+          "rules": [
+            { "rule_id": "r-ok", "condition": null, "next_step_id": "step-confirm" }
+          ]
+        }
+      },
+      {
+        "step_id": "step-confirm",
+        "title": "Confirm your policy",
+        "rows": [{ "row_id": "r2", "layout": "vertical", "field_ids": ["f-accept"] }],
+        "navigation": {
+          "rules": [{ "rule_id": "r-end", "condition": null, "next_step_id": "__submit__" }]
+        }
+      },
+      {
+        "step_id": "step-not-found",
+        "title": "We couldn't find your policy",
+        "rows": [],
+        "navigation": { "rules": [] }
+      }
+    ],
+    "fields": [
+      { "field_id": "f-doc",    "namespace": "customer.document", "label": "Document ID", "schema": "v1_string", "required": true },
+      { "field_id": "f-accept", "namespace": "consent.accepted",  "label": "I confirm the details above", "schema": "v2_single_option_select-1", "required": true,
+        "options": [{ "data": "yes", "label": "Yes" }] }
+    ],
+    "summary": {
+      "title": "Review",
+      "sections": [
+        {
+          "section_id": "sec-policy",
+          "title": "Policy",
+          "display_fields": [
+            { "display_id": "d-holder", "source": "api_response", "step_id": "step-id", "response_path": "policy.holder.name",   "label": "Holder" },
+            { "display_id": "d-plate",  "source": "api_response", "step_id": "step-id", "response_path": "policy.vehicle.plate", "label": "Plate" }
+          ]
+        }
+      ]
+    },
+    "init": {
+      "values": {},
+      "api": {
+        "enabled": true,
+        "method": "GET",
+        "url": "https://api.example.com/session/prefill",
+        "headers": { "x-tenant": "acme" },
+        "mapping": {
+          "customer.full_name": "user.name",
+          "customer.email":     "user.email"
+        }
+      }
+    }
+  },
+  "theme": {
+    "primaryColor": "222 47% 11%",
+    "fontFamilyHeading": "Poppins, sans-serif",
+    "fontFamilyBody": "Roboto, sans-serif",
+    "borderRadius": 0.75,
+    "spacing": "cozy"
+  }
+}
+```
+
+### Handling `StepApiRequest` on the host
+
+The runner builds a `StepApiRequest` whenever a step has an enabled `api_call`. `body` is already interpolated from `body_template` against the live `answers`; `answers` is a snapshot for host-side enrichment (auth, tenant context, etc.).
+
+```ts
+import type { StepApiRequest } from 'habit-claims-journey-components';
+
+async function onStepApiCall(req: StepApiRequest) {
+  // req = { step_id, method, url, headers, body?, answers }
+  const res = await fetch(req.url, {
+    method: req.method,
+    headers: {
+      'Content-Type': 'application/json',
+      authorization: `Bearer ${getToken()}`,
+      ...req.headers,
+    },
+    body: req.body !== undefined ? JSON.stringify(req.body) : undefined,
+  });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  // The returned value is stored as api_responses[req.step_id]
+  // and is referenceable from later JSON Logic rules and the Summary.
+  return res.json();
+}
+```
+
+### Handling `InitApiRequest` on the host
+
+Fired once on runner mount when `form_config.init.api.enabled` is `true`. The response is walked through `init.api.mapping` (namespace → dot-path) to seed `answers` before the first step renders.
+
+```ts
+import type { InitApiRequest } from 'habit-claims-journey-components';
+
+async function onInitApiCall(req: InitApiRequest) {
+  // req = { method, url, headers? }
+  const res = await fetch(req.url, { method: req.method, headers: req.headers });
+  if (!res.ok) throw new Error(`Init HTTP ${res.status}`);
+  return res.json();
+}
+```
+
+---
+
 ## License
 
 MIT