@wizzard-packages/core 0.4.1 → 0.5.0-canary-20260908083257

package/dist/{flow-Bmv_KegP.d.cts → expr-C9w_odUt.d.cts}

@@ -45,10 +45,15 @@ type Expr = null | boolean | number | string | readonly Expr[] | {
 interface Scope {
     data: Record<string, unknown>;
     ctx: Record<string, unknown>;
-    /** Present inside a `repeat` group. */
+    /**
+     * Present inside a `repeat` group. `key` is the item's identity under
+     * `keyBy` - the one part a flow can use to address its own item's data,
+     * because `index` moves when the list is reordered.
+     */
     loop?: {
         index: number;
         item: unknown;
+        key: string;
     };
 }
 type Resolver = (args: Json | undefined, scope: Scope) => unknown;
@@ -84,83 +89,4 @@ type AsyncRegistry = Readonly<Record<string, AsyncResolver>>;
 /** Evaluates to a boolean, awaiting `$ref`. An absent expression is `true`. */
 declare function testAsync(e: Expr | undefined, scope: Scope, registry?: AsyncRegistry): Promise<boolean>;
 
-/**
- * The flow definition. Pure JSON — no functions, no class instances, nothing
- * that `JSON.stringify` would drop. The same object can be written by hand,
- * served by a backend, or generated; the engine cannot tell which.
- *
- * Everything that cannot be serialized is named instead: `view` names a
- * component, `$ref` names a function, both looked up in a registry the host
- * supplies.
- */
-interface FlowDefinition {
-    id: string;
-    /** Bumped by the producer when the shape changes; used to reject stale patches. */
-    version?: number;
-    /** Default linear order. A step missing from `order` is reachable only via `on.next`. */
-    order?: readonly string[];
-    /** Keyed by id, not an array, so a patch can address one step without index maths. */
-    steps: Readonly<Record<string, StepDef>>;
-    policy?: NavigationPolicy;
-    validate?: {
-        on?: 'change' | 'blur' | 'next' | 'manual';
-        debounceMs?: number;
-    };
-}
-type NavigationPolicy = 'sequential' | 'visited' | 'free';
-type Target = string | {
-    to: string;
-    when?: Expr;
-};
-interface StepBase {
-    label?: string;
-    /** Reachability. A step whose `when` is false is skipped, not shown disabled. */
-    when?: Expr;
-    guards?: {
-        enter?: Expr;
-        exit?: Expr;
-    };
-    on?: {
-        next?: Target | readonly Target[];
-        back?: Target | 'auto';
-    };
-    /** Key of this step's slice of `data`. Defaults to the step id. */
-    slice?: string;
-    /** Field schema for the host to render. The engine never reads it. */
-    ui?: Json;
-    /** Loaded on enter, with an abort signal. */
-    load?: {
-        $ref: string;
-        args?: Json;
-    };
-    /** The body of this step arrives later, from the host. */
-    deferred?: boolean;
-}
-interface AtomStep extends StepBase {
-    view?: string;
-    validate?: {
-        $ref: string;
-        args?: Json;
-    };
-}
-/**
- * A sub-flow. With `repeat` it is also the loop construct — the same machinery,
- * because a loop is a sub-flow entered once per item. Iteration state lives in
- * the runtime frame, never in the definition, so the flow stays static and
- * diffable.
- */
-interface GroupStep extends StepBase {
-    flow: string | FlowDefinition;
-    repeat?: {
-        over: Expr;
-        keyBy?: string;
-    };
-    /** Parent expressions piped into the child's `ctx`. */
-    input?: Readonly<Record<string, Expr>>;
-}
-type StepDef = AtomStep | GroupStep;
-declare const isGroup: (s: StepDef) => s is GroupStep;
-/** Sentinel target meaning the flow is finished. */
-declare const END: "@end";
-
-export { type AtomStep as A, END as E, type FlowDefinition as F, type GroupStep as G, type Json as J, type NavigationPolicy as N, type Registry as R, type StepDef as S, type Target as T, type AsyncRegistry as a, type Scope as b, type Expr as c, type Resolver as d, ExprError as e, evaluate as f, evaluateAsync as g, type AsyncResolver as h, isSync as i, testAsync as j, isGroup as k, test as t };
+export { type AsyncRegistry as A, type Expr as E, type Json as J, type Registry as R, type Scope as S, type Resolver as a, ExprError as b, evaluateAsync as c, type AsyncResolver as d, evaluate as e, testAsync as f, isSync as i, test as t };

package/dist/{flow-Bmv_KegP.d.ts → expr-C9w_odUt.d.ts}

@@ -45,10 +45,15 @@ type Expr = null | boolean | number | string | readonly Expr[] | {
 interface Scope {
     data: Record<string, unknown>;
     ctx: Record<string, unknown>;
-    /** Present inside a `repeat` group. */
+    /**
+     * Present inside a `repeat` group. `key` is the item's identity under
+     * `keyBy` - the one part a flow can use to address its own item's data,
+     * because `index` moves when the list is reordered.
+     */
     loop?: {
         index: number;
         item: unknown;
+        key: string;
     };
 }
 type Resolver = (args: Json | undefined, scope: Scope) => unknown;
@@ -84,83 +89,4 @@ type AsyncRegistry = Readonly<Record<string, AsyncResolver>>;
 /** Evaluates to a boolean, awaiting `$ref`. An absent expression is `true`. */
 declare function testAsync(e: Expr | undefined, scope: Scope, registry?: AsyncRegistry): Promise<boolean>;
 
-/**
- * The flow definition. Pure JSON — no functions, no class instances, nothing
- * that `JSON.stringify` would drop. The same object can be written by hand,
- * served by a backend, or generated; the engine cannot tell which.
- *
- * Everything that cannot be serialized is named instead: `view` names a
- * component, `$ref` names a function, both looked up in a registry the host
- * supplies.
- */
-interface FlowDefinition {
-    id: string;
-    /** Bumped by the producer when the shape changes; used to reject stale patches. */
-    version?: number;
-    /** Default linear order. A step missing from `order` is reachable only via `on.next`. */
-    order?: readonly string[];
-    /** Keyed by id, not an array, so a patch can address one step without index maths. */
-    steps: Readonly<Record<string, StepDef>>;
-    policy?: NavigationPolicy;
-    validate?: {
-        on?: 'change' | 'blur' | 'next' | 'manual';
-        debounceMs?: number;
-    };
-}
-type NavigationPolicy = 'sequential' | 'visited' | 'free';
-type Target = string | {
-    to: string;
-    when?: Expr;
-};
-interface StepBase {
-    label?: string;
-    /** Reachability. A step whose `when` is false is skipped, not shown disabled. */
-    when?: Expr;
-    guards?: {
-        enter?: Expr;
-        exit?: Expr;
-    };
-    on?: {
-        next?: Target | readonly Target[];
-        back?: Target | 'auto';
-    };
-    /** Key of this step's slice of `data`. Defaults to the step id. */
-    slice?: string;
-    /** Field schema for the host to render. The engine never reads it. */
-    ui?: Json;
-    /** Loaded on enter, with an abort signal. */
-    load?: {
-        $ref: string;
-        args?: Json;
-    };
-    /** The body of this step arrives later, from the host. */
-    deferred?: boolean;
-}
-interface AtomStep extends StepBase {
-    view?: string;
-    validate?: {
-        $ref: string;
-        args?: Json;
-    };
-}
-/**
- * A sub-flow. With `repeat` it is also the loop construct — the same machinery,
- * because a loop is a sub-flow entered once per item. Iteration state lives in
- * the runtime frame, never in the definition, so the flow stays static and
- * diffable.
- */
-interface GroupStep extends StepBase {
-    flow: string | FlowDefinition;
-    repeat?: {
-        over: Expr;
-        keyBy?: string;
-    };
-    /** Parent expressions piped into the child's `ctx`. */
-    input?: Readonly<Record<string, Expr>>;
-}
-type StepDef = AtomStep | GroupStep;
-declare const isGroup: (s: StepDef) => s is GroupStep;
-/** Sentinel target meaning the flow is finished. */
-declare const END: "@end";
-
-export { type AtomStep as A, END as E, type FlowDefinition as F, type GroupStep as G, type Json as J, type NavigationPolicy as N, type Registry as R, type StepDef as S, type Target as T, type AsyncRegistry as a, type Scope as b, type Expr as c, type Resolver as d, ExprError as e, evaluate as f, evaluateAsync as g, type AsyncResolver as h, isSync as i, testAsync as j, isGroup as k, test as t };
+export { type AsyncRegistry as A, type Expr as E, type Json as J, type Registry as R, type Scope as S, type Resolver as a, ExprError as b, evaluateAsync as c, type AsyncResolver as d, evaluate as e, testAsync as f, isSync as i, test as t };

package/dist/flow-B6E6c5Gc.d.ts

@@ -0,0 +1,90 @@
+import { E as Expr, J as Json } from './expr-C9w_odUt.js';
+
+/**
+ * The flow definition. Pure JSON — no functions, no class instances, nothing
+ * that `JSON.stringify` would drop. The same object can be written by hand,
+ * served by a backend, or generated; the engine cannot tell which.
+ *
+ * Everything that cannot be serialized is named instead: `view` names a
+ * component, `$ref` names a function, both looked up in a registry the host
+ * supplies.
+ */
+interface FlowDefinition {
+    id: string;
+    /** Bumped by the producer when the shape changes; used to reject stale patches. */
+    version?: number;
+    /** Default linear order. A step missing from `order` is reachable only via `on.next`. */
+    order?: readonly string[];
+    /** Keyed by id, not an array, so a patch can address one step without index maths. */
+    steps: Readonly<Record<string, StepDef>>;
+    policy?: NavigationPolicy;
+    validate?: {
+        on?: 'change' | 'blur' | 'next' | 'manual';
+        debounceMs?: number;
+    };
+}
+type NavigationPolicy = 'sequential' | 'visited' | 'free';
+type Target = string | {
+    to: string;
+    when?: Expr;
+};
+interface StepBase {
+    label?: string;
+    /** Reachability. A step whose `when` is false is skipped, not shown disabled. */
+    when?: Expr;
+    guards?: {
+        enter?: Expr;
+        exit?: Expr;
+    };
+    on?: {
+        next?: Target | readonly Target[];
+        back?: Target | 'auto';
+    };
+    /** Key of this step's slice of `data`. Defaults to the step id. */
+    slice?: string;
+    /** Field schema for the host to render. The engine never reads it. */
+    ui?: Json;
+    /** Loaded on enter, with an abort signal. */
+    load?: {
+        $ref: string;
+        args?: Json;
+    };
+    /** The body of this step arrives later, from the host. */
+    deferred?: boolean;
+    /**
+     * What to forget when this step is left, forwards or backwards. Data is
+     * kept by default: a person who goes back and returns expects their answers
+     * to still be there. `true` drops the step's whole slice (`slice`, or the
+     * step id); a list drops those `data` paths, in the same path language as
+     * `set()`. Nothing is cleared on completion — that data is the submission.
+     */
+    clearOnLeave?: readonly string[] | true;
+}
+interface AtomStep extends StepBase {
+    view?: string;
+    validate?: {
+        $ref: string;
+        args?: Json;
+    };
+}
+/**
+ * A sub-flow. With `repeat` it is also the loop construct — the same machinery,
+ * because a loop is a sub-flow entered once per item. Iteration state lives in
+ * the runtime frame, never in the definition, so the flow stays static and
+ * diffable.
+ */
+interface GroupStep extends StepBase {
+    flow: string | FlowDefinition;
+    repeat?: {
+        over: Expr;
+        keyBy?: string;
+    };
+    /** Parent expressions piped into the child's `ctx`. */
+    input?: Readonly<Record<string, Expr>>;
+}
+type StepDef = AtomStep | GroupStep;
+declare const isGroup: (s: StepDef) => s is GroupStep;
+/** Sentinel target meaning the flow is finished. */
+declare const END: "@end";
+
+export { type AtomStep as A, END as E, type FlowDefinition as F, type GroupStep as G, type NavigationPolicy as N, type StepDef as S, type Target as T, isGroup as i };

package/dist/flow-kC0pucDF.d.cts

@@ -0,0 +1,90 @@
+import { E as Expr, J as Json } from './expr-C9w_odUt.cjs';
+
+/**
+ * The flow definition. Pure JSON — no functions, no class instances, nothing
+ * that `JSON.stringify` would drop. The same object can be written by hand,
+ * served by a backend, or generated; the engine cannot tell which.
+ *
+ * Everything that cannot be serialized is named instead: `view` names a
+ * component, `$ref` names a function, both looked up in a registry the host
+ * supplies.
+ */
+interface FlowDefinition {
+    id: string;
+    /** Bumped by the producer when the shape changes; used to reject stale patches. */
+    version?: number;
+    /** Default linear order. A step missing from `order` is reachable only via `on.next`. */
+    order?: readonly string[];
+    /** Keyed by id, not an array, so a patch can address one step without index maths. */
+    steps: Readonly<Record<string, StepDef>>;
+    policy?: NavigationPolicy;
+    validate?: {
+        on?: 'change' | 'blur' | 'next' | 'manual';
+        debounceMs?: number;
+    };
+}
+type NavigationPolicy = 'sequential' | 'visited' | 'free';
+type Target = string | {
+    to: string;
+    when?: Expr;
+};
+interface StepBase {
+    label?: string;
+    /** Reachability. A step whose `when` is false is skipped, not shown disabled. */
+    when?: Expr;
+    guards?: {
+        enter?: Expr;
+        exit?: Expr;
+    };
+    on?: {
+        next?: Target | readonly Target[];
+        back?: Target | 'auto';
+    };
+    /** Key of this step's slice of `data`. Defaults to the step id. */
+    slice?: string;
+    /** Field schema for the host to render. The engine never reads it. */
+    ui?: Json;
+    /** Loaded on enter, with an abort signal. */
+    load?: {
+        $ref: string;
+        args?: Json;
+    };
+    /** The body of this step arrives later, from the host. */
+    deferred?: boolean;
+    /**
+     * What to forget when this step is left, forwards or backwards. Data is
+     * kept by default: a person who goes back and returns expects their answers
+     * to still be there. `true` drops the step's whole slice (`slice`, or the
+     * step id); a list drops those `data` paths, in the same path language as
+     * `set()`. Nothing is cleared on completion — that data is the submission.
+     */
+    clearOnLeave?: readonly string[] | true;
+}
+interface AtomStep extends StepBase {
+    view?: string;
+    validate?: {
+        $ref: string;
+        args?: Json;
+    };
+}
+/**
+ * A sub-flow. With `repeat` it is also the loop construct — the same machinery,
+ * because a loop is a sub-flow entered once per item. Iteration state lives in
+ * the runtime frame, never in the definition, so the flow stays static and
+ * diffable.
+ */
+interface GroupStep extends StepBase {
+    flow: string | FlowDefinition;
+    repeat?: {
+        over: Expr;
+        keyBy?: string;
+    };
+    /** Parent expressions piped into the child's `ctx`. */
+    input?: Readonly<Record<string, Expr>>;
+}
+type StepDef = AtomStep | GroupStep;
+declare const isGroup: (s: StepDef) => s is GroupStep;
+/** Sentinel target meaning the flow is finished. */
+declare const END: "@end";
+
+export { type AtomStep as A, END as E, type FlowDefinition as F, type GroupStep as G, type NavigationPolicy as N, type StepDef as S, type Target as T, isGroup as i };

package/dist/navigate-DJkRL8XS.d.ts

@@ -0,0 +1,199 @@
+import { R as Registry, S as Scope, A as AsyncRegistry } from './expr-C9w_odUt.js';
+import { F as FlowDefinition, E as END, S as StepDef } from './flow-B6E6c5Gc.js';
+import { W as WizardState, F as Frame } from './state-BFDnj4LP.js';
+
+/**
+ * The navigation pipeline.
+ *
+ * Every way of moving — next, back, jump — runs through this one function, so
+ * there is one place where validation, guards, loading and policy are ordered,
+ * and one place that can get the ordering wrong. The 0.x engine implemented
+ * this three times, in the React context, the React store and the Vue binding,
+ * and the three copies disagreed about the default for validation and about
+ * whether middleware ran at all.
+ *
+ * Two writes happen, and only two. The first is the epoch bump in phase 0,
+ * which is the lock: a concurrent call has to see it to know it superseded us.
+ * The second is the single commit in phase 9. Nothing is written in between, so
+ * a navigation that loses the race, throws, or is aborted leaves no trace.
+ *
+ * Sub-flows and repeat groups push frames onto the stack, and this pass walks a
+ * single level on its own. The traversal that walks the rest lives behind
+ * `@wizzard-packages/core/groups` and is installed as `ctx.groups`: phase 0.5
+ * asks it which flow owns the current frame and what the scope there is, phase
+ * 4 asks it for the whole move, phase 8 asks it again when the data moved under
+ * an await, and phase 9 commits the stack it returned. With nothing installed
+ * every one of those falls back to the flat expression it replaced.
+ */
+type NavReason = 'invalid' | 'blocked' | 'no-target' | 'superseded' | 'aborted' | 'not-reachable';
+type NavResult = {
+    ok: true;
+    from: string | null;
+    to: string | typeof END;
+} | {
+    ok: false;
+    reason: NavReason;
+    /** Which plugin or guard refused. Replaces the goToStepResult probe of 0.x. */
+    by?: string;
+    errors?: Readonly<Record<string, string>>;
+};
+type NavIntent = {
+    type: 'next';
+} | {
+    type: 'back';
+} | {
+    type: 'go';
+    to: string;
+    force?: boolean;
+};
+/** What a plugin may answer from beforeNavigate. */
+type NavDecision = void | false | {
+    block: string;
+} | {
+    redirect: string;
+};
+/**
+ * One navigation attempt as `onAttempt` reports it: once when it starts and
+ * once when it ends, with the result, or errors, with what was thrown.
+ *
+ * `id` counts attempts on one wizard, so a plugin can pair an end with its
+ * start when two overlap - a superseded attempt ends after the one that
+ * superseded it began. `source` is `'start'` for the engine's own first move,
+ * so a log can tell it from a call the application made. `rev` is the state's
+ * revision at the moment of the event.
+ */
+type AttemptPhase = {
+    phase: 'start';
+} | {
+    phase: 'end';
+    result: NavResult;
+} | {
+    phase: 'error';
+    error: unknown;
+};
+type Attempt = {
+    id: number;
+    intent: NavIntent;
+    source: 'call' | 'start';
+    rev: number;
+} & AttemptPhase;
+interface Hooks {
+    name: string;
+    /**
+     * Runs once, when the engine is built, before anything reads it. A plugin
+     * that restores a saved session does it here. The returned function, if any,
+     * runs on `destroy`.
+     *
+     * A commit made from inside `init` does not come back as `onCommit`: the
+     * plugin already knows what it just wrote, and re-entering is how a restore
+     * turns into a loop.
+     */
+    init?: (host: PluginHost) => void | (() => void);
+    /**
+     * Every committed state, from any path - navigation, `set`, `patch`,
+     * `setCtx`, `reset`, `patchFlow`. A plugin that persists writes here.
+     *
+     * Not a veto and not a place to be slow: it runs inside the write, so
+     * throwing disables the plugin rather than failing the write.
+     */
+    onCommit?: (state: WizardState, previous: WizardState) => void;
+    beforeNavigate?: (e: {
+        from: string | null;
+        to: string | typeof END | null;
+        state: WizardState;
+    }) => NavDecision | Promise<NavDecision>;
+    afterNavigate?: (e: {
+        from: string | null;
+        to: string | typeof END;
+        state: WizardState;
+    }) => void;
+    /**
+     * Every attempt to move, whether or not it commits. A refused `next()` never
+     * writes, so `onCommit` cannot report it; this can, with the reason. Fired
+     * by the store around the whole pipeline, never from inside it, and never
+     * for `cancel()` - the aborted attempt ends here with its `aborted` result.
+     *
+     * Observation only, like `onCommit`: throwing disables the plugin.
+     */
+    onAttempt?: (attempt: Attempt) => void;
+    /** Supplies the body of a deferred step, typically over the network. */
+    loadStep?: (stepId: string, signal: AbortSignal) => Promise<StepDef | undefined>;
+}
+/** What a plugin is handed at `init`. Deliberately small: read, and write once. */
+interface PluginHost {
+    getState: () => WizardState;
+    getFlow: () => FlowDefinition;
+    /** Replaces state through the one commit path, exactly as the engine does. */
+    commit: (patch: Partial<WizardState>) => void;
+}
+interface NavHost {
+    read: () => WizardState;
+    /** The single setter owned by the store. Notifies listeners exactly once. */
+    write: (next: WizardState) => void;
+}
+/**
+ * Sub-flow definitions by the key a `GroupStep.flow` string names them by. The
+ * same registry `checkSession` and `buildGraph` take: the expression `Registry`
+ * holds resolver functions, not definitions, so a group referenced by id has
+ * nothing else that could resolve it.
+ */
+type SubFlows = Readonly<Record<string, FlowDefinition>>;
+/**
+ * Group and repeat traversal, installed rather than imported.
+ *
+ * The implementation is `@wizzard-packages/core/groups`, its own entry with its
+ * own budget, so a flat flow carries none of it. The type lives here because a
+ * type costs a bundle nothing and this entry has to be able to accept one.
+ */
+interface Traversal {
+    /** Phase 0.5: the flow that owns the top frame, and the scope at that frame. */
+    here: (root: FlowDefinition, state: WizardState, registry?: Registry, subFlows?: SubFlows) => {
+        flow: FlowDefinition;
+        scope: Scope;
+    };
+    /**
+     * Phase 4: the whole move, pure. `null` means no target.
+     *
+     * `flow` is the flow that owns the *new* top frame, which is not always the
+     * one `here` named: a move that enters or leaves a group changes which flow
+     * phases 5-7 have to look the target up in.
+     */
+    step: (root: FlowDefinition, state: WizardState, intent: NavIntent, registry?: Registry, subFlows?: SubFlows) => {
+        stack: readonly Frame[];
+        to: string | typeof END;
+        flow: FlowDefinition;
+        scope: Scope;
+    } | {
+        ok: false;
+        reason: 'invalid' | 'not-reachable';
+        by: string;
+        errors?: Readonly<Record<string, string>>;
+    } | null;
+}
+interface NavContext {
+    flow: FlowDefinition;
+    registry?: AsyncRegistry;
+    hooks?: readonly Hooks[];
+    /** Returns field errors, or null when the step is valid. */
+    validate?: (stepId: string, state: WizardState) => Promise<Readonly<Record<string, string>> | null>;
+    /**
+     * Runs the load of a step before entering it.
+     *
+     * Both the reference and the scope arrive from the pipeline rather than being
+     * looked back up. A step inside a sub-flow has no id in the root flow, and
+     * the scope the resolver needs is the one *after* the move: on entry to a
+     * repeat, `loop` does not exist in the committed state at all, and on an
+     * advance it still names the item being left.
+     */
+    load?: (stepId: string, load: unknown, scope: Scope, signal: AbortSignal) => Promise<void>;
+    /** Group and repeat traversal. Absent means flat flows only. */
+    groups?: Traversal;
+    /** Sub-flow definitions a string `GroupStep.flow` names. */
+    subFlows?: SubFlows;
+    signal?: AbortSignal;
+}
+declare function runNav(ctx: NavContext, host: NavHost, intent: NavIntent, opts?: {
+    validate?: boolean;
+}): Promise<NavResult>;
+
+export { type AttemptPhase as A, type Hooks as H, type NavIntent as N, type PluginHost as P, type SubFlows as S, type Traversal as T, type NavResult as a, type NavReason as b, type NavDecision as c, type Attempt as d, type NavHost as e, type NavContext as f, runNav as r };