attaform 0.27.2 → 0.27.4

package/dist/shared/{attaform.B2d0FszH.d.ts → attaform.DKtXMaJB.d.ts}

@@ -1026,13 +1026,24 @@ 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()`
- *    (see `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 gate. `false` when no gate seals it.
+ *  - `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 seeded cleared via
+ *    `defaultStatuses`. 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, locked: false }`).
+ * (`{ 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;
@@ -1040,14 +1051,30 @@ type FormStatus = {
     readonly submitted: boolean;
     readonly errorCount: number;
     readonly locked: boolean;
+    readonly gate: 'cleared' | 'uncleared' | null;
 };
 /**
- * Seed shape accepted by `useWizard({ defaultStatuses })`. Mirrors
- * `FormStatus` minus `locked`: the lock flag is computed live from the
- * wizard's gates and overlaid on every status read, so a seed never
- * carries it (a seeded value would be ignored).
- */
-type FormStatusSeed = Omit<FormStatus, 'locked'>;
+ * Seed shape accepted by `useWizard({ defaultStatuses })`. Every field is
+ * optional; an omitted meta field falls back to the pending sentinel on
+ * read.
+ *
+ * `locked` is never accepted: it is purely live-derived (sealed behind an
+ * earlier uncleared gate) and overlaid on every status read, so a seeded
+ * value would be ignored.
+ *
+ * `gate` is a WRITE-only seed, not a status field echoed back on read. A
+ * seed of `'cleared'` latches the gate's cleared state once at construction
+ * (an SSR restore of a confirmed prerequisite); the live `gate` overlay
+ * then owns the read. `'uncleared'` is the default and seeds nothing. Only
+ * a step that compiles to a `gate()` honors it — other keys ignore it.
+ */
+type FormStatusSeed = {
+    readonly valid?: boolean;
+    readonly dirty?: boolean;
+    readonly submitted?: boolean;
+    readonly errorCount?: number;
+    readonly gate?: 'cleared' | 'uncleared';
+};
 /**
  * Flat error shape returned per form by `wizard.allErrors[key]`. Each
  * entry carries the formKey + path tuple so consumers can route to the
@@ -1302,12 +1329,20 @@ type WizardOptions = {
      * Status resolution priority per form:
      *   1. `store.defaultsResolved === true` → derive from `form.meta`
      *   2. else noop form → built-in always-valid status
-     *   3. else seed value for this key → frozen seed
+     *   3. else seed value for this key → seed over the pending sentinel
      *   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`.
+     * `locked` is never seeded: it is computed live from the wizard's gates
+     * and overlaid on every status read. `gate: 'cleared'` IS honored, but as
+     * a one-shot seed of the gate's cleared latch at construction (an SSR
+     * restore of a confirmed prerequisite), not as a status field echoed on
+     * read — the live `gate` overlay owns the read. Only a step that compiles
+     * to a `gate()` honors it. See `FormStatusSeed`.
+     *
+     * SSR note: the async factory resolves after hydration (client-only), so
+     * a gate seeded through it clears post-hydration. For a gate that must
+     * render open on the first server byte, use the plain or sync-factory
+     * form (resolve server truth in the page's `setup` await).
      *
      * Unknown keys in the seed object dev-warn so a stale resume payload
      * surfaces at construction.
@@ -1547,7 +1582,19 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *  - `reset()`     — zeros wizard lifecycle (`submissionAttempts`,
  *                    `visited`), resets every form, returns
  *                    `currentStep` to `steps[0].key`, and invokes
- *                    `persist` with the cleared state.
+ *                    `persist` with the cleared state. Re-applies the
+ *                    `defaultStatuses` gate seed, so a reboot returns to
+ *                    the seeded initial clearance, not fully sealed.
+ *  - `relock(key, commit)` — re-seal a cleared gate, contingent on
+ *                    `commit`. Awaits `commit` (a server-side revoke) and
+ *                    re-seals only if it resolves clean, so the gate reflects
+ *                    server-confirmed truth the same way a clearing submit
+ *                    does; a thrown `commit` leaves it as-is. Seal-only (never
+ *                    opens a gate), so it cannot become the leading-signal
+ *                    foot-gun `gate()` exists to prevent. `commit` is required
+ *                    (pass `() => {}` for a deliberate client-only re-seal).
+ *                    Resolves whether the gate ended up sealed; never rejects.
+ *                    Resolves `false` (dev-warn) on a non-gate key.
  */
 type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepSlot>> = {
     readonly key: string;
@@ -1576,6 +1623,7 @@ type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepS
     readonly tryNext: () => Promise<boolean>;
     readonly handleSubmit: (onSubmit: WizardOnSubmit, onError?: WizardOnError) => (event?: Event) => Promise<void>;
     readonly reset: () => void;
+    readonly relock: (key: FormKey, commit: () => void | Promise<void>) => Promise<boolean>;
 };
 
 /**

package/dist/shared/{attaform.CvaPYOZu.cjs → attaform.DXwJVUNS.cjs}

@@ -1,8 +1,8 @@
 'use strict';
 
-const serializeScript = require('./attaform.CXHebpij.cjs');
+const serializeScript = require('./attaform.Ib2seKUE.cjs');
 const devtoolsShared = require('./attaform.BBaMFa-k.cjs');
-const walkFieldMeta = require('./attaform.CIPwCQe8.cjs');
+const walkFieldMeta = require('./attaform.CX2NHAFs.cjs');
 const zod = require('zod');
 
 const fieldMeta = walkFieldMeta.fieldMetaStore;
@@ -1299,4 +1299,4 @@ exports.unwrapPipe = unwrapPipe;
 exports.useForm = useForm;
 exports.withMeta = withMeta;
 exports.zodV4Adapter = zodV4Adapter;
-//# sourceMappingURL=attaform.CvaPYOZu.cjs.map
+//# sourceMappingURL=attaform.DXwJVUNS.cjs.map