attaform 0.27.1 → 0.27.3

package/dist/shared/{attaform.CEXUlUkc.d.ts → attaform.gqOCvpSB.d.ts}

@@ -1,4 +1,4 @@
-import { G as GenericForm, F as FormKey, a as UseFormReturnType, a4 as RegisterValue, T as PathKey, k as DisplayCtx, w as GetDisplayState, l as DisplayMachine, S as Path, a9 as SlimPrimitiveKind, C as CoercionEntry, e as CoercionRegistry, af as ValidationError, A as AbstractSchema, aj as WriteMeta, h as DeepPartial, ak as WriteShape, as as TransformAbortHolder, ad as ValidateOn, d as AttaformDefaults, at as RegisterModelDynamicCustomDirective } from './attaform.C3WnCDXz.js';
+import { G as GenericForm, F as FormKey, a as UseFormReturnType, a4 as RegisterValue, T as PathKey, k as DisplayCtx, w as GetDisplayState, l as DisplayMachine, S as Path, a9 as SlimPrimitiveKind, C as CoercionEntry, e as CoercionRegistry, af as ValidationError, A as AbstractSchema, aj as WriteMeta, h as DeepPartial, ak as WriteShape, as as TransformAbortHolder, ad as ValidateOn, d as AttaformDefaults, at as RegisterModelDynamicCustomDirective } from './attaform.BIPSHY5U.js';
 import { Ref, ComputedRef, App, InjectionKey, Plugin } from 'vue';
 
 /**
@@ -441,6 +441,20 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
     readonly submitted: Ref<boolean>;
     readonly submitError: Ref<Error | null>;
     readonly departAttempts: Ref<number>;
+    /**
+     * Effective data-freeze state: `true` when either the form's own
+     * `disabled` config resolves truthy or `externalLock` is set. Read at
+     * the write chokepoint (`setValueAtPath`), the register value's
+     * `disabled`, and the field display predicate.
+     */
+    readonly effectiveDisabled: ComputedRef<boolean>;
+    /**
+     * Wizard-driven freeze channel. `useWizard` sets this `true` for a
+     * locked step's member form; ORed into `effectiveDisabled` so the
+     * wizard lock is authoritative and a member form cannot escape it by
+     * passing `disabled: false`. Default `false`.
+     */
+    readonly externalLock: Ref<boolean>;
     /**
      * `true` while a function-form `defaultValues` factory is in flight.
      * Stays `false` for plain-value `defaultValues`. Shared across every
@@ -1012,16 +1026,40 @@ type AnyForm = {
  *    `submissionAttempts > 0` is the "user has tried" signal.
  *  - `errorCount` — `form.meta.errorCount`. Count of active validation
  *    errors (zero when valid).
+ *  - `locked`: `true` when this step sits after an uncleared gate. Its
+ *    member form is frozen (data writes no-op) and navigation to it is
+ *    refused, so a stepper can render it as an unreachable step. `false`
+ *    when no gate seals it. Orthogonal to `gate`: the first uncleared
+ *    gate reads `locked: false` (you must reach it to clear it), while a
+ *    later gate sealed behind it reads both `gate: 'uncleared'` and
+ *    `locked: true`.
+ *  - `gate`: this step's own role as a hard prerequisite. `null` when the
+ *    step is not a `gate()`; `'uncleared'` while its member form is
+ *    unconfirmed (so it seals every later step); `'cleared'` once
+ *    confirmed by a clean member submit or a seeded-valid form gate at
+ *    mount. Reflects the live compiled shape, so a conditional `gate()`
+ *    that a function slot drops resolves to `null`.
  *
  * Noop forms generated for string slots surface as default-valid
- * (`{ valid: true, dirty: false, submitted: false, errorCount: 0 }`).
+ * (`{ valid: true, dirty: false, submitted: false, errorCount: 0, locked: false, gate: null }`),
+ * unless the string slot is a `gate('...')`, whose `gate` tracks the
+ * in-session acknowledgment.
  */
 type FormStatus = {
     readonly valid: boolean;
     readonly dirty: boolean;
     readonly submitted: boolean;
     readonly errorCount: number;
+    readonly locked: boolean;
+    readonly gate: 'cleared' | 'uncleared' | null;
 };
+/**
+ * Seed shape accepted by `useWizard({ defaultStatuses })`. Mirrors
+ * `FormStatus` minus its two live-computed flags, `locked` and `gate`:
+ * both are derived from the wizard's gates and overlaid on every status
+ * read, so a seed never carries them (a seeded value would be ignored).
+ */
+type FormStatusSeed = Omit<FormStatus, 'locked' | 'gate'>;
 /**
  * Flat error shape returned per form by `wizard.allErrors[key]`. Each
  * entry carries the formKey + path tuple so consumers can route to the
@@ -1082,6 +1120,13 @@ type WizardCtx = {
     readonly forms: Readonly<Record<FormKey, WizardCtxForm>>;
     readonly currentKey: FormKey | undefined;
 };
+/**
+ * What a function slot or a `lazy()` / `gate()` resolver may yield: a
+ * participating form, a bare affordance key, a nested `lazy()` / `gate()`
+ * wrapper (so the two compose in either order), or `null` / `undefined`
+ * to drop the position from the compiled list.
+ */
+type SlotResolution<Ctx = WizardCtx> = AnyForm | string | null | undefined | LazyMarker<Ctx> | GateMarker;
 /**
  * Internal phantom brand for `LazyMarker`. The runtime brand symbol
  * lives in `core/wizard-lazy.ts`; this declaration keeps the marker
@@ -1103,8 +1148,46 @@ declare const _lazyBrand: unique symbol;
  */
 type LazyMarker<Ctx = WizardCtx> = {
     readonly [_lazyBrand]: true;
-    readonly resolve: (ctx: Ctx) => AnyForm | string | null | undefined;
+    readonly resolve: (ctx: Ctx) => SlotResolution<Ctx>;
 };
+/**
+ * Internal phantom brand for `GateMarker`. The runtime brand symbol
+ * lives in `core/wizard-gate.ts`; this declaration keeps the marker
+ * type unforgeable without circular module imports.
+ */
+declare const _gateBrand: unique symbol;
+/**
+ * Brand-typed marker returned by `gate(step)`. Wrapping a slot in
+ * `gate()` makes it a hard prerequisite: an uncleared gate seals every
+ * step positioned after it, and the gate's own form is the only way
+ * past. A gate clears on a member form's clean submit (confirmation),
+ * never on a value merely going valid (intent), and its form freezes
+ * once cleared so a back-navigation is a read-only review.
+ *
+ * `Inner` carries the wrapped slot's static type so `gate` stays
+ * transparent to the type machinery: `gate(form)` still contributes the
+ * form's key to `wizard.forms` and still counts as a guaranteed step,
+ * while `gate(lazy(fn))` stays maybe-absent exactly like the lazy slot
+ * it wraps. See {@link UnwrapGate}.
+ *
+ * Construct via the `gate()` helper exported from the same entry as
+ * `useWizard`. The marker is opaque at the type level; consumers do not
+ * assemble it directly.
+ */
+type GateMarker<Inner = unknown> = {
+    readonly [_gateBrand]: true;
+    readonly inner: Inner;
+};
+/**
+ * Strip every `gate()` wrapper off a slot type, exposing the inner
+ * slot's static shape. A gate is identity-on-shape — it changes runtime
+ * reachability, never the compiled type — so the forms map and the
+ * non-empty-tuple predicate both unwrap it before inspecting a slot.
+ * Recursive, so a doubly-wrapped `gate(gate(form))` still resolves to
+ * `form`. This is what makes `gate(lazy(s))` and `lazy((ctx) => gate(s))`
+ * agree at the type level as well as at runtime.
+ */
+type UnwrapGate<T> = T extends GateMarker<infer Inner> ? UnwrapGate<Inner> : T;
 /**
  * One position in the source `useWizard({ steps })` array. Each slot
  * resolves to a compiled `{ key, form }` step, or drops out:
@@ -1118,12 +1201,15 @@ type LazyMarker<Ctx = WizardCtx> = {
  *                        list. Lets a conditional step read inline as
  *                        `cond ? form : null` without pre-filtering the
  *                        array.
- *  - function          — eager slot, re-evaluates reactively. Returns
- *                        one of the above, or `null` / `undefined` to
+ *  - function          — eager slot, re-evaluates reactively. Returns a
+ *                        `SlotResolution`, or `null` / `undefined` to
  *                        drop the slot from the compiled list.
  *  - `LazyMarker`      — memoized function slot (see `lazy`).
+ *  - `GateMarker`      — hard-prerequisite wrapper (see `gate`). Wraps
+ *                        any of the above; transparent to the compiled
+ *                        step's type, opaque to reachability.
  */
-type StepSlot<Ctx = WizardCtx> = AnyForm | string | null | undefined | ((ctx: Ctx) => AnyForm | string | null | undefined) | LazyMarker<Ctx>;
+type StepSlot<Ctx = WizardCtx> = AnyForm | string | null | undefined | ((ctx: Ctx) => SlotResolution<Ctx>) | LazyMarker<Ctx> | GateMarker;
 /**
  * Shape returned by the `restore` callback. Carries the active step's
  * key; intentionally open-ended (object form) so future additions land
@@ -1231,10 +1317,14 @@ type WizardOptions = {
      *   3. else seed value for this key → frozen seed
      *   4. else → pending sentinel
      *
+     * The `locked` flag is never seeded: it is computed live from the
+     * wizard's gates and overlaid on every status read, so the seed shape
+     * is `FormStatus` minus `locked`.
+     *
      * Unknown keys in the seed object dev-warn so a stale resume payload
      * surfaces at construction.
      */
-    readonly defaultStatuses?: Record<string, FormStatus> | (() => Record<string, FormStatus>) | (() => Promise<Record<string, FormStatus>>);
+    readonly defaultStatuses?: Record<string, FormStatusSeed> | (() => Record<string, FormStatusSeed>) | (() => Promise<Record<string, FormStatusSeed>>);
     /**
      * Optional progress override. When omitted, the wizard exposes
      * `progress` as `valid_step_count / count` (normalised to `[0, 1]`).
@@ -1277,7 +1367,7 @@ type WizardOptions = {
  * nullish nor a (maybe-absent) function / `lazy()` slot. One of these
  * anywhere in the tuple proves the compiled list is non-empty.
  */
-type IsGuaranteedStep<T> = [null] extends [T] ? false : [undefined] extends [T] ? false : T extends LazyMarker | ((...args: unknown[]) => unknown) ? false : T extends string ? true : T extends {
+type IsGuaranteedStep<T, U = UnwrapGate<T>> = [null] extends [U] ? false : [undefined] extends [U] ? false : U extends LazyMarker | ((...args: unknown[]) => unknown) ? false : U extends string ? true : U extends {
     readonly key: string;
 } ? true : false;
 /**
@@ -1307,13 +1397,16 @@ type CurrentStepOf<S> = StaticallyNonEmpty<S> extends true ? FormKey : FormKey |
  */
 type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? UseFormReturnType<GenericForm> : UseFormReturnType<GenericForm> | undefined;
 /**
- * Per-slot contribution to {@link FormsRecordOf}. Strips a `null` /
+ * Per-slot contribution to {@link FormsRecordOf}. Unwraps a `gate()`
+ * wrapper (transparent to the compiled type) and strips a `null` /
  * `undefined` (a literal absence or a `cond ? form : null` union) off the
- * slot first, so a conditionally-present form still maps to its key and
- * stays concretely typed on `wizard.forms`; a purely nullish slot
- * contributes nothing.
+ * slot first, so both a conditionally-present form and a `gate(form)`
+ * still map to their key and stay concretely typed on `wizard.forms`; a
+ * purely nullish slot contributes nothing.
  */
-type SlotRecord<First, F = Exclude<First, null | undefined>> = [F] extends [never] ? unknown : F extends string ? {
+type SlotRecord<First, U = UnwrapGate<First>, F = Exclude<U, null | undefined>> = [F] extends [
+    never
+] ? unknown : F extends string ? {
     readonly [P in F]: AnyForm;
 } : F extends {
     readonly key: infer K extends string;
@@ -1337,6 +1430,9 @@ type SlotRecord<First, F = Exclude<First, null | undefined>> = [F] extends [neve
  *  - **Function / `lazy()` slot**: contributes nothing to the static
  *    map. Runtime-resolved forms are still reachable via the
  *    catch-all index signature on `WizardForms` (typed as `AnyForm`).
+ *  - **`gate()` slot**: transparent — unwrapped to the slot it wraps, so
+ *    `gate(form)` contributes the form's key and `gate(lazy(fn))`
+ *    contributes nothing, exactly like the wrapped slot on its own.
  *
  * Recursion is bounded by the tuple length; real-world wizards land
  * well below the TS instantiation budget.
@@ -1442,14 +1538,15 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *                    `back()` does not pop; the trail is the audit
  *                    log, not the back-stack.
  *  - `next/back/goTo` — pure navigation. Refuses while `submitting`.
- *  - `tryNext()`   — validate the active step, then advance iff it
- *                    passed; invalid input keeps the pin put under the
- *                    form's standard error reveal (first error focused,
- *                    display state advanced). The inline-bindable
- *                    shorthand for `activeForm.handleSubmit(() =>
- *                    next())`. Resolves to whether the pin moved. No-ops
- *                    to `false` on a degenerate or final-step wizard
- *                    (finish via `handleSubmit`).
+ *  - `tryNext()`   — submit the active step, and once that submit
+ *                    resolves clean, advance; invalid input keeps the pin
+ *                    put under the form's standard error reveal (first
+ *                    error focused, display state advanced). The advance
+ *                    runs after the submit settles, so a `gate()` on the
+ *                    active step clears in a single call. Inline-bindable
+ *                    (`@click="wizard.tryNext()"`); resolves to whether
+ *                    the pin moved. No-ops to `false` on a degenerate or
+ *                    final-step wizard (finish via `handleSubmit`).
  *  - `handleSubmit(onSubmit, onError?)` — always validates the entire
  *                    step list, from any step, and never advances the
  *                    pin: on success it latches `done`; on any error it
@@ -1809,11 +1906,61 @@ declare function injectWizard(input?: string | InjectWizardInput): UseWizardRetu
  *    resolves from scratch.
  *  - Resolving to `null` or `undefined` drops the slot from the compiled
  *    list until the resolver next re-fires.
+ *  - The resolver may return a `gate()` wrapper, so a lazy slot can gate
+ *    what it resolves to; `lazy((ctx) => gate(s))` and `gate(lazy(s))`
+ *    resolve identically.
  *
  * The runtime brand returned by `lazy()` is opaque. Use
  * {@link isLazyMarker} to detect it.
  */
-declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => AnyForm | string | null | undefined): LazyMarker<Ctx>;
+declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => SlotResolution<Ctx>): LazyMarker<Ctx>;
+
+/**
+ * Wrap a step slot in `gate()` to make it a hard prerequisite: while the
+ * gate is uncleared, every step positioned after it is inaccessible, and
+ * the gate's own form is the only way past.
+ *
+ * A gate is safe by construction. It does not hand the consumer a
+ * predicate to key on; it bakes the correct semantics in:
+ *
+ *  - **Confirmation, not intent.** The gate clears only when a member
+ *    form submits clean, never when a value merely goes valid. Checking
+ *    the box does nothing; submitting the consent step is what opens the
+ *    rail. This is the whole reason `gate()` exists: a leading value
+ *    signal lets a downstream step collect data before the prerequisite
+ *    is confirmed.
+ *  - **Linear-forward.** An uncleared gate seals every step after it.
+ *    Order places it: put `gate(step)` immediately before what it
+ *    guards. Everything downstream is both un-navigable and, through the
+ *    `disabled` data freeze, un-fillable, so a deep link, the browser
+ *    back button, or a stray `goTo` all redirect to the gate.
+ *  - **Freeze-after-clear.** A cleared gate's own form freezes, so
+ *    navigating back to it is a read-only review with no withdrawal
+ *    path. There is no re-lock dance.
+ *
+ * Wrap any slot kind:
+ *
+ *   const wizard = useWizard({ steps: [gate(consent), shipping, payment] })
+ *
+ * A **form** gate (`gate(consentForm)`) clears when its form submits
+ * clean, and is treated as pre-cleared on reload when its member form
+ * rehydrates already valid (a persisted consent), so a seeded-valid gate
+ * SSR-renders open. A bare-string **affordance** gate (`gate('terms')`)
+ * clears on acknowledgment (advancing past it), and re-prompts each
+ * session because that acknowledgment is ephemeral.
+ *
+ * Conditional gates come from composition, not an options bag:
+ *
+ *   () => (transfer.values.amount > 10_000 ? gate(kyc) : kyc)
+ *
+ * `gate()` composes with `lazy()` in either order:
+ * `gate(lazy(fn))` and `lazy((ctx) => gate(fn(ctx)))` resolve
+ * identically.
+ *
+ * The runtime brand returned by `gate()` is opaque. Use
+ * {@link isGateMarker} to detect it.
+ */
+declare function gate<const Inner extends StepSlot>(step: Inner): GateMarker<Inner>;
 
 /**
  * Stable identifiers for library-emitted `ValidationError` codes.
@@ -1891,6 +2038,16 @@ declare const AttaformErrorCode: {
      * form-level path `[]`.
      */
     readonly SubmitError: "atta:submit-error";
+    /**
+     * Synthesized by `wizard.handleSubmit` when the whole-wizard submit
+     * would otherwise succeed but a `gate()` step is still uncleared. A
+     * gate clears only on its member form's clean submit (confirmation), so
+     * a downstream step that happens to be valid-by-default must not let the
+     * wizard finish past an unconfirmed prerequisite. Emitted at the gate
+     * form's key (path `[]`) so the aggregate error pipeline routes focus to
+     * the gate, and `done` never latches.
+     */
+    readonly GateNotCleared: "atta:gate-not-cleared";
 };
 type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
 
@@ -2281,5 +2438,5 @@ declare function makeDefaultDisplayState({ showDelay, minVisible, }: DisplayTimi
  */
 declare const defaultDisplayState: GetDisplayState;
 
-export { useWizard as $, createRegistry as B, DEFAULT_TIMINGS as D, defaultCoercionRules as E, defaultDisplayState as G, defineCoercion as H, escapeForInlineScript as J, getRegistryFromApp as K, hydrateAttaformState as M, injectForm as N, OutsideSetupError as O, injectWizard as P, isRegisterValue as Q, RegistryNotInstalledError as R, kAttaformRegistry as T, lazy as V, makeDefaultDisplayState as X, renderAttaformState as Y, useRegister as Z, useRegistry as _, vRegister as a0, AttaformError as c, AttaformErrorCode as d, DEVTOOLS_WINDOW_KEY as f, InvalidPathError as h, InvalidUseFormConfigError as i, ReservedFormKeyError as j, SubmitErrorHandlerError as m, assignKey as y, createAttaform as z };
-export type { AttaformRegistry as A, CompiledStep as C, FormStatus as F, InjectWizardInput as I, LazyMarker as L, SerializedAttaformState as S, UseRegisterReturn as U, WizardAggregateError as W, AnyForm as a, AttaformDevtoolsBridge as b, AttaformPluginOptions as e, DisplayTimings as g, SerializedFormData as k, StepSlot as l, UseWizardReturnType as n, WizardCtx as o, WizardCtxForm as p, WizardOnError as q, WizardOnSubmit as r, WizardOptions as s, WizardPersistFn as t, WizardRestoreFn as u, WizardRestoreState as v, WizardStatusesProxy as w, WizardSubmitContext as x };
+export { renderAttaformState as $, createAttaform as B, DEFAULT_TIMINGS as D, createRegistry as E, defaultCoercionRules as H, defaultDisplayState as J, defineCoercion as K, escapeForInlineScript as M, gate as N, OutsideSetupError as O, getRegistryFromApp as P, hydrateAttaformState as Q, RegistryNotInstalledError as R, injectForm as T, injectWizard as V, isRegisterValue as X, kAttaformRegistry as Y, lazy as Z, makeDefaultDisplayState as _, useRegister as a0, useRegistry as a1, useWizard as a2, vRegister as a3, AttaformError as c, AttaformErrorCode as d, DEVTOOLS_WINDOW_KEY as f, InvalidPathError as i, InvalidUseFormConfigError as j, ReservedFormKeyError as k, SubmitErrorHandlerError as n, assignKey as z };
+export type { AttaformRegistry as A, CompiledStep as C, FormStatus as F, GateMarker as G, InjectWizardInput as I, LazyMarker as L, SerializedAttaformState as S, UseRegisterReturn as U, WizardAggregateError as W, AnyForm as a, AttaformDevtoolsBridge as b, AttaformPluginOptions as e, DisplayTimings as g, FormStatusSeed as h, SerializedFormData as l, StepSlot as m, UseWizardReturnType as o, WizardCtx as p, WizardCtxForm as q, WizardOnError as r, WizardOnSubmit as s, WizardOptions as t, WizardPersistFn as u, WizardRestoreFn as v, WizardRestoreState as w, WizardStatusesProxy as x, WizardSubmitContext as y };