attaform 0.24.4 → 0.26.0

package/dist/shared/{attaform.B1N47eDM.d.ts → attaform.CEY_WLRJ.d.mts}

@@ -1,4 +1,4 @@
-import { F as FormKey, W as PathKey, m as DisplayCtx, d as GetDisplayState, n as DisplayMachine, V as Path, aa as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, ag as ValidationError, a as AbstractSchema, ak as WriteMeta, j as DeepPartial, al as WriteShape, at as TransformAbortHolder, ae as ValidateOn, A as AttaformDefaults, b as UseFormReturnType, c as RegisterValue } from './attaform.QFrCtJBO.js';
+import { F as FormKey, b as UseFormReturnType, G as GenericForm, W as PathKey, m as DisplayCtx, d as GetDisplayState, n as DisplayMachine, V as Path, aa as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, ag as ValidationError, a as AbstractSchema, ak as WriteMeta, j as DeepPartial, al as WriteShape, at as TransformAbortHolder, ae as ValidateOn, A as AttaformDefaults, c as RegisterValue } from './attaform.DBNjHgNj.mjs';
 import { Ref, ComputedRef, App, InjectionKey } from 'vue';
 
 /**
@@ -137,23 +137,27 @@ declare const _lazyBrand: unique symbol;
  */
 type LazyMarker<Ctx = WizardCtx> = {
     readonly [_lazyBrand]: true;
-    readonly resolve: (ctx: Ctx) => AnyForm | string | undefined;
+    readonly resolve: (ctx: Ctx) => AnyForm | string | null | undefined;
 };
 /**
  * One position in the source `useWizard({ steps })` array. Each slot
- * resolves to a compiled `{ key, form }` step:
+ * resolves to a compiled `{ key, form }` step, or drops out:
  *
  *  - `AnyForm`         — a form declared via `useForm`. Surfaced as-is.
  *  - `string`          — bare key. The wizard generates a noop form
  *                        under the hood so the external surface stays
  *                        uniform across affordance positions (intro,
  *                        terms, congratulations, review surfaces).
+ *  - `null` / `undefined` — a literal absence, dropped from the compiled
+ *                        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 `undefined` to drop the
- *                        slot from the compiled list.
+ *                        one of the above, or `null` / `undefined` to
+ *                        drop the slot from the compiled list.
  *  - `LazyMarker`      — memoized function slot (see `lazy`).
  */
-type StepSlot<Ctx = WizardCtx> = AnyForm | string | ((ctx: Ctx) => AnyForm | string | undefined) | LazyMarker<Ctx>;
+type StepSlot<Ctx = WizardCtx> = AnyForm | string | null | undefined | ((ctx: Ctx) => AnyForm | string | null | undefined) | LazyMarker<Ctx>;
 /**
  * Shape returned by the `restore` callback. Carries the active step's
  * key; intentionally open-ended (object form) so future additions land
@@ -178,8 +182,9 @@ type WizardRestoreFn = () => WizardRestoreState | undefined;
 type WizardPersistFn = (state: WizardRestoreState) => void;
 /**
  * Submit context passed to the `onSubmit` callback registered via
- * `wizard.handleSubmit(onSubmit, onError?)`. Same shape on every step;
- * `isFinal` distinguishes intermediate vs final calls.
+ * `wizard.handleSubmit(onSubmit, onError?)`. `handleSubmit` always
+ * processes the whole step list, so `values` carries every form's
+ * parsed output regardless of which step fired the submit.
  *
  *  - `values` — namespaced aggregate keyed by form key, mirroring
  *               `wizard.allValues`. Reflects parsed output for every
@@ -190,9 +195,11 @@ type WizardPersistFn = (state: WizardRestoreState) => void;
  *               because the form ref carries its schema info.
  *  - `currentKey` — key of the step that fired this submission.
  *  - `isFinal`   — `true` when `currentKey` is the last position in
- *               `wizard.steps`. Intermediate calls validate the active
- *               form only and advance; final calls validate every form
- *               and stay on the terminal step.
+ *               `wizard.steps`. Positional only: it reports where the
+ *               submit fired, never what got validated. A user who steps
+ *               back, edits, and submits from the middle sees
+ *               `isFinal === false`, yet the whole list is still
+ *               processed and `done` still latches on success.
  */
 type WizardSubmitContext = {
     readonly values: Readonly<Record<FormKey, unknown>>;
@@ -209,9 +216,11 @@ type WizardSubmitContext = {
 type WizardOnSubmit = (ctx: WizardSubmitContext) => void | Promise<void>;
 /**
  * Optional `onError` callback registered via `wizard.handleSubmit`.
- * Receives the aggregate error list. Entries originate from per-form
- * validation, activation failures (`atta:activation-failed`), and a
- * submit callback that left errors on a processed step (the
+ * Receives the aggregate error list spanning EVERY step (handleSubmit
+ * validates the whole wizard), so a failed submit surfaces every form's
+ * errors at once, not just the active step's. Entries originate from
+ * per-form validation, activation failures (`atta:activation-failed`),
+ * and a submit callback that left errors on a processed step (the
  * `setErrors(...); return` server-rejection path). Sync or async; the
  * returned promise gates `wizard.submitting`.
  */
@@ -296,24 +305,55 @@ type WizardOptions = {
      */
     readonly persist?: WizardPersistFn | false;
 };
+/**
+ * True when a single slot is guaranteed to contribute exactly one
+ * compiled step: a bare form or affordance string that is neither
+ * 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 {
+    readonly key: string;
+} ? true : false;
 /**
  * Predicate: is the steps tuple statically guaranteed to compile to a
- * non-empty list? A tuple passes when (a) it's not the empty array
- * literal and (b) it carries no function or `lazy()` slot — those
- * slot kinds can resolve to `undefined` at runtime and drop the
- * compiled position. Form slots and bare-string affordance slots
- * always preserve their position; a tuple made of only those kinds is
- * statically safe.
+ * non-empty list? True when at least one element is a guaranteed step
+ * (see `IsGuaranteedStep`). Function / `lazy()` slots may resolve to
+ * nothing, and `null` / `undefined` (a literal absence or a
+ * `cond ? form : null` union) is an explicit drop, so none of those
+ * prove non-emptiness; a tuple of only maybe-absent slots stays
+ * honestly `| undefined`.
  *
  * Used to narrow `currentStep` / `activeForm` to their non-`undefined`
  * shapes in the common-case wizard, while keeping the honest union
  * everywhere a runtime drop is reachable.
  */
-type StaticallyNonEmpty<S> = S extends readonly [] ? false : S extends readonly (infer Item)[] ? Item extends LazyMarker | ((...args: unknown[]) => unknown) ? false : true : false;
+type StaticallyNonEmpty<S> = S extends readonly [infer First, ...infer Rest] ? IsGuaranteedStep<First> extends true ? true : StaticallyNonEmpty<Rest> : false;
 /** Active step's key, narrowed to `string` when `S` is statically safe. */
 type CurrentStepOf<S> = StaticallyNonEmpty<S> extends true ? FormKey : FormKey | undefined;
-/** Active step's form handle, narrowed to `AnyForm` when `S` is statically safe. */
-type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? AnyForm : AnyForm | undefined;
+/**
+ * Active step's form handle, schema-erased to `UseFormReturnType<GenericForm>`
+ * and narrowed to non-`undefined` when `S` is statically safe. The runtime
+ * value is a live facade over the active step, so reads (`.values`, `.meta`,
+ * `.history`) and `.handleSubmit` always target the current step. Values are
+ * loose here because the active step's schema is not statically known; reach
+ * for the original form ref or `ctx.get(ref)` when you need typed per-step
+ * values.
+ */
+type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? UseFormReturnType<GenericForm> : UseFormReturnType<GenericForm> | undefined;
+/**
+ * Per-slot contribution to {@link FormsRecordOf}. 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.
+ */
+type SlotRecord<First, F = Exclude<First, null | undefined>> = [F] extends [never] ? unknown : F extends string ? {
+    readonly [P in F]: AnyForm;
+} : F extends {
+    readonly key: infer K extends string;
+} ? {
+    readonly [P in K]: F;
+} : unknown;
 /**
  * Recursive tuple walk that builds the static portion of
  * `wizard.forms`. Each step slot contributes to the record:
@@ -325,7 +365,9 @@ type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? AnyForm : AnyForm |
  *    the form's own `key` becomes the record key, and the value is
  *    the concrete form handle type — so drilling
  *    `wizard.forms.shipping.values.address` carries the schema-derived
- *    field types through.
+ *    field types through. A form kept behind a `cond ? form : null`
+ *    conditional still maps to its key.
+ *  - **`null` / `undefined` slot**: contributes nothing.
  *  - **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`).
@@ -336,13 +378,7 @@ type ActiveFormOf<S> = StaticallyNonEmpty<S> extends true ? AnyForm : AnyForm |
 type FormsRecordOf<S> = S extends readonly [
     infer First,
     ...infer Rest extends ReadonlyArray<StepSlot>
-] ? (First extends string ? {
-    readonly [P in First]: AnyForm;
-} : First extends {
-    readonly key: infer K extends string;
-} ? {
-    readonly [P in K]: First;
-} : unknown) & FormsRecordOf<Rest> : unknown;
+] ? SlotRecord<First> & FormsRecordOf<Rest> : unknown;
 /**
  * `wizard.forms` typed view. Combines the static per-step type map
  * with a catch-all `Record<FormKey, AnyForm>` fallback so:
@@ -376,9 +412,15 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *                    slots). Otherwise reads as `string | undefined`
  *                    so the degenerate case (empty list at runtime)
  *                    surfaces honestly.
- *  - `activeForm`  — the active step's form handle. Same narrowing as
- *                    `currentStep`. Noop forms cover string slots in
- *                    the normal path.
+ *  - `activeForm`  — a LIVE view of the active step's form. Operating
+ *                    through it always targets the current step, so a
+ *                    handler captured once at setup
+ *                    (`wizard.activeForm.handleSubmit(() =>
+ *                    wizard.next())`) retargets as the wizard advances.
+ *                    No longer `===` the raw per-step handle; reach for
+ *                    `wizard.forms[key]` when you need raw identity.
+ *                    Same `undefined` narrowing as `currentStep`. Noop
+ *                    forms cover string slots in the normal path.
  *  - `activeIndex` — 0-based position of the active step.
  *  - `isFinalStep` — `true` when `currentStep === steps[count - 1].key`.
  *  - `steps`       — ordered list of compiled `{ key, form }` slots.
@@ -404,13 +446,13 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *                    Forward-looking; reactive to current form
  *                    validity. Gates "Finish button enable" style UI.
  *  - `done`        — monotonic latch: flips `true` the first time a
- *                    final-step `handleSubmit` resolves without throwing
- *                    AND leaves no errors set on any step, and stays
- *                    `true` through subsequent edits or invalidations. A
- *                    callback that calls `setErrors` and returns (the
- *                    documented server-rejection path) is a failed submit,
- *                    so it does not flip `done`. Only `reset()` flips it
- *                    back. Gates "show success card" style UI that should
+ *                    `handleSubmit` resolves without throwing AND leaves
+ *                    no errors set on any step, and stays `true` through
+ *                    subsequent edits or invalidations. A callback that
+ *                    calls `setErrors` and returns (the documented
+ *                    server-rejection path) is a failed submit, so it
+ *                    does not flip `done`. Only `reset()` flips it back.
+ *                    Gates "show success card" style UI that should
  *                    reflect submission history rather than current
  *                    validity.
  *  - `submitting`  — `true` while a `wizard.handleSubmit` call is in
@@ -434,11 +476,23 @@ 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`.
- *  - `handleSubmit(onSubmit, onError?)` — universal across all steps.
- *                    Intermediate calls validate the active form and
- *                    advance; final calls validate every form. Returns
- *                    an event handler suitable for `<form @submit>` or
- *                    imperative use.
+ *  - `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`).
+ *  - `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
+ *                    focuses the first failing step and fires `onError`
+ *                    with errors spanning every step. To gate advancing
+ *                    a step on its own validity, compose with the active
+ *                    form's submit: `activeForm.handleSubmit(() =>
+ *                    wizard.next())`. Returns an event handler suitable
+ *                    for `<form @submit>` or imperative use.
  *  - `reset()`     — zeros wizard lifecycle (`submissionAttempts`,
  *                    `visited`), resets every form, returns
  *                    `currentStep` to `steps[0].key`, and invokes
@@ -468,6 +522,7 @@ type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepS
     readonly next: () => Promise<void>;
     readonly back: () => void;
     readonly goTo: (key: string) => void;
+    readonly tryNext: () => Promise<boolean>;
     readonly handleSubmit: (onSubmit: WizardOnSubmit, onError?: WizardOnError) => (event?: Event) => Promise<void>;
     readonly reset: () => void;
 };
@@ -1546,8 +1601,10 @@ type InjectFormInput = {
  * independent of component-tree position.
  *
  * Returns `null` when no matching form exists (no ambient ancestor, or
- * the named key isn't registered). A dev-mode warning points at the
- * call site to help diagnose typos. Always narrow before using:
+ * the named key isn't registered yet). A dev-mode warning points at the
+ * call site, lists the registered keys, and flags the mount-timing case
+ * (a form created by a child or sibling isn't registered until its own
+ * setup runs). Always narrow before using:
  *
  * ```ts
  * const form = injectForm<Shape>('signup')
@@ -1650,9 +1707,10 @@ declare function useRegister<V = unknown>(): UseRegisterReturn<V> | undefined;
  *
  * The wizard's surface is read-only from the consumer's side:
  * navigation (`next` / `back` / `goTo`) walks positional indices,
- * `handleSubmit` validates the active form on intermediate steps and
- * the whole wizard on the final step, and URL synchronization rides on
- * `restore` / `persist` callbacks that default to `?step=<key>`.
+ * `handleSubmit` validates the whole step list from any step and never
+ * advances (gate advance with `activeForm.handleSubmit(() =>
+ * wizard.next())`), and URL synchronization rides on `restore` /
+ * `persist` callbacks that default to `?step=<key>`.
  */
 declare function useWizard<const S extends ReadonlyArray<StepSlot>>(options: WizardOptions & {
     readonly steps: S;
@@ -1696,8 +1754,10 @@ type InjectWizardInput = {
  * constructed with `useWizard({ steps, key })` to be reachable.
  *
  * Returns `null` when no matching wizard exists (no ambient ancestor,
- * or the named key isn't registered). A dev-mode warning points at the
- * call site to help diagnose typos. Always narrow before using:
+ * or the named key isn't registered yet). A dev-mode warning points at
+ * the call site, lists the registered keys, and flags the mount-timing
+ * case (a wizard created by a child or sibling isn't registered until
+ * its own setup runs). Always narrow before using:
  *
  * ```ts
  * const wizard = injectWizard('signup')
@@ -1747,13 +1807,13 @@ declare function injectWizard(input?: string | InjectWizardInput): UseWizardRetu
  *    this one.
  *  - `wizard.reset()` clears every lazy slot's cache so a reboot truly
  *    resolves from scratch.
- *  - Resolving to `undefined` drops the slot from the compiled list
- *    until the resolver next re-fires.
+ *  - Resolving to `null` or `undefined` drops the slot from the compiled
+ *    list until the resolver next re-fires.
  *
  * The runtime brand returned by `lazy()` is opaque. Use
  * {@link isLazyMarker} to detect it.
  */
-declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => AnyForm | string | undefined): LazyMarker<Ctx>;
+declare function lazy<Ctx = WizardCtx>(resolve: (ctx: Ctx) => AnyForm | string | null | undefined): LazyMarker<Ctx>;
 
 /**
  * Stable identifiers for library-emitted `ValidationError` codes.
@@ -1820,6 +1880,17 @@ declare const AttaformErrorCode: {
      * Override it per error by passing your own `code` (`api:…`, `auth:…`).
      */
     readonly UserError: "atta:user-error";
+    /**
+     * Stamped on a `ValidationError` synthesized from a throw or rejection
+     * out of a `handleSubmit` `onSubmit` callback. The raw error also lands
+     * on `form.meta.submitError` (a raw-`Error` inspection channel); this
+     * code marks the copy piped into the user-error layer so the failure
+     * also surfaces on `form.errors` / `meta.ownErrors` / `firstOwnError`
+     * where the UI already reads. A throw carrying its own `path` / `code`
+     * keeps them; a bare `Error` or a non-Error throw defaults here at the
+     * form-level path `[]`.
+     */
+    readonly SubmitError: "atta:submit-error";
 };
 type AttaformErrorCode = (typeof AttaformErrorCode)[keyof typeof AttaformErrorCode];
 

package/dist/shared/{attaform.CwqTCeTZ.mjs → attaform.CSXDW2tO.mjs}

@@ -1,6 +1,6 @@
-import { f as fieldMetaStore, g as getFieldMetaForSchema, a as getFieldMetaListForSchema, s as slimPrimitivesWalk, c as createAbstractSchema, w as walkPathSegments, d as deriveDefaultWalk, b as getFieldMetaPathMap, m as mergeDeep, p as peelEmbeddedDefault, N as NO_EMBEDDED_DEFAULT } from './attaform.lcTiMoma.mjs';
-import { o as humanize, p as getAtPath, n as slimKindOf, q as setAtPath, h as useAbstractForm } from './attaform.iJ4y3sHU.mjs';
-import { A as AttaformError, _ as __DEV__, f as canonicalizePath, a as InvalidUseFormConfigError } from './attaform.DwsfkfSY.mjs';
+import { f as fieldMetaStore, g as getFieldMetaForSchema, a as getFieldMetaListForSchema, s as slimPrimitivesWalk, c as createAbstractSchema, w as walkPathSegments, d as deriveDefaultWalk, b as getFieldMetaPathMap, m as mergeDeep, p as peelEmbeddedDefault, N as NO_EMBEDDED_DEFAULT } from './attaform.CXVmZtFq.mjs';
+import { o as humanize, p as getAtPath, n as slimKindOf, q as setAtPath, h as useAbstractForm } from './attaform.BoYqnIPI.mjs';
+import { A as AttaformError, _ as __DEV__, f as canonicalizePath, a as InvalidUseFormConfigError } from './attaform.DGhIix5D.mjs';
 
 const fieldMeta = fieldMetaStore;
 function withMeta(schema, payload) {
@@ -1628,4 +1628,4 @@ function useForm(configuration) {
 }
 
 export { fieldMeta as f, isZodSchemaType as i, useForm as u, withMeta as w, zodAdapter as z };
-//# sourceMappingURL=attaform.CwqTCeTZ.mjs.map
+//# sourceMappingURL=attaform.CSXDW2tO.mjs.map