attaform 0.27.2 → 0.27.4

package/dist/shared/{attaform.DIJTp_Kv.d.cts → attaform.Cjh6b6xU.d.cts}

@@ -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.DGCijpZT.mjs → attaform.CuUx4jWI.mjs}

@@ -6346,14 +6346,16 @@ const PENDING_STATUS = {
   dirty: false,
   submitted: false,
   errorCount: 0,
-  locked: false
+  locked: false,
+  gate: null
 };
 const NOOP_VALID_STATUS = {
   valid: true,
   dirty: false,
   submitted: false,
   errorCount: 0,
-  locked: false
+  locked: false,
+  gate: null
 };
 const EMPTY_LOCK_SET = /* @__PURE__ */ new Set();
 function asStatusSource(form) {
@@ -6685,24 +6687,6 @@ function useWizard(options) {
     (slot) => isGateMarker(slot) || isLazyMarker(slot) || typeof slot === "function"
   );
   const clearedGates = reactive(/* @__PURE__ */ new Set());
-  const seededSampled = /* @__PURE__ */ new Set();
-  function isGateVerdictSettled(key) {
-    const store = registry.forms.get(key);
-    if (store === void 0) return false;
-    return store.defaultsResolved.value === true && store.firstValidationDone.value === true && store.activeValidations.value === 0;
-  }
-  function isGateFormValid(key) {
-    const form = formsRecord.value[key] ?? formsAccumulator.get(key);
-    if (form === void 0) return false;
-    return asStatusSource(form).meta?.valid ?? false;
-  }
-  function sampleSeededGate(key) {
-    if (seededSampled.has(key)) return;
-    if (noopForms.has(key)) return;
-    if (!isGateVerdictSettled(key)) return;
-    seededSampled.add(key);
-    if (isGateFormValid(key)) clearedGates.add(key);
-  }
   const gateSubs = /* @__PURE__ */ new Map();
   function reconcileGates() {
     const gateKeys = /* @__PURE__ */ new Set();
@@ -6719,7 +6703,6 @@ function useWizard(options) {
           );
         }
       }
-      sampleSeededGate(key);
     }
     for (const [key, unsub] of gateSubs) {
       if (!gateKeys.has(key)) {
@@ -6777,8 +6760,7 @@ function useWizard(options) {
         for (const step of compiledSteps.value) {
           if (!step.isGate) continue;
           const store = registry.forms.get(step.key);
-          const settled = store !== void 0 && isGateVerdictSettled(step.key);
-          parts.push(`${step.key}:${store !== void 0 ? 1 : 0}:${settled ? 1 : 0}`);
+          parts.push(`${step.key}:${store !== void 0 ? 1 : 0}`);
         }
         return parts.join("|");
       },
@@ -6811,20 +6793,30 @@ function useWizard(options) {
       });
     }
   }
+  function applyGateSeed(map) {
+    if (map === void 0 || !mightGate) return;
+    const gates = gatePositions.value;
+    for (const key of Object.keys(map)) {
+      if (map[key]?.gate === "cleared" && gates.includes(key)) clearedGates.add(key);
+    }
+  }
   const seedRef = ref(void 0);
   const seedInput = options.defaultStatuses;
   if (seedInput !== void 0) {
     const resolved = resolveTrichotomy(seedInput);
     if (resolved.kind === "sync") {
       seedRef.value = resolved.value;
+      applyGateSeed(resolved.value);
     } else {
       const eager = resolved.factory();
       if (eager instanceof Promise) {
         void eager.then((value) => {
           seedRef.value = value;
+          applyGateSeed(value);
         });
       } else {
         seedRef.value = eager;
+        applyGateSeed(eager);
       }
     }
   }
@@ -6835,6 +6827,10 @@ function useWizard(options) {
     const source = asStatusSource(form);
     const computedStatus = computed(() => {
       const locked = navLockSet.value.has(form.key);
+      let gate = null;
+      if (gatePositions.value.includes(form.key)) {
+        gate = clearedGates.has(form.key) ? "cleared" : "uncleared";
+      }
       if (isFormReady(form.key)) {
         const meta = source.meta;
         if (meta !== void 0 && meta !== null) {
@@ -6843,16 +6839,17 @@ function useWizard(options) {
             dirty: meta.dirty,
             submitted: meta.submitted,
             errorCount: meta.errorCount,
-            locked
+            locked,
+            gate
           };
         }
       }
       if (noopForms.has(form.key)) {
-        return locked ? { ...NOOP_VALID_STATUS, locked: true } : NOOP_VALID_STATUS;
+        return locked || gate !== null ? { ...NOOP_VALID_STATUS, locked, gate } : NOOP_VALID_STATUS;
       }
       const seed = seedRef.value?.[form.key];
-      if (seed !== void 0) return { ...seed, locked };
-      return locked ? { ...PENDING_STATUS, locked: true } : PENDING_STATUS;
+      if (seed !== void 0) return { ...PENDING_STATUS, ...seed, locked, gate };
+      return locked || gate !== null ? { ...PENDING_STATUS, locked, gate } : PENDING_STATUS;
     });
     statusCache.set(form.key, computedStatus);
     return computedStatus;
@@ -7343,14 +7340,16 @@ function useWizard(options) {
     submitError.value = null;
     if (mightGate) {
       clearedGates.clear();
-      seededSampled.clear();
     }
     lazyEpoch.value += 1;
     for (const step of compiledSteps.value) {
       const full = asSubmissionSource(step.form);
       if (typeof full.reset === "function") full.reset();
     }
-    if (mightGate) reconcileGates();
+    if (mightGate) {
+      reconcileGates();
+      applyGateSeed(seedRef.value);
+    }
     const firstStep = compiledSteps.value[0];
     if (firstStep !== void 0) {
       const landing = commitActiveKey(firstStep.key);
@@ -7361,6 +7360,29 @@ function useWizard(options) {
       }
     }
   }
+  async function relock(key, commit) {
+    if (!mightGate || !gatePositions.value.includes(key)) {
+      if (__DEV__) {
+        console.warn(
+          `[attaform] useWizard.relock(${JSON.stringify(key)}): no gate at that key; nothing to re-lock.`
+        );
+      }
+      return false;
+    }
+    try {
+      await commit();
+    } catch (err) {
+      if (__DEV__) {
+        console.warn(
+          `[attaform] useWizard.relock(${JSON.stringify(key)}): commit threw, so the gate was not re-sealed.`,
+          err
+        );
+      }
+      return false;
+    }
+    clearedGates.delete(key);
+    return true;
+  }
   if (mightGate) {
     watchEffect(() => {
       const key = activeKey.value;
@@ -7386,6 +7408,7 @@ function useWizard(options) {
     tryNext,
     handleSubmit,
     reset,
+    relock,
     get currentStep() {
       return currentStep.value;
     },
@@ -7566,4 +7589,4 @@ function escapeForInlineScript(json) {
 }
 
 export { AttaformErrorCode as A, DEFAULT_TIMINGS as D, defaultDisplayState as a, defineCoercion as b, injectWizard as c, defaultCoercionRules as d, escapeForInlineScript as e, isUnset as f, gate as g, useAbstractForm as h, injectForm as i, useRegister as j, useWizard as k, lazy as l, makeDefaultDisplayState as m, isPlainRecord as n, safeAssign as o, slimKindOf as p, humanize as q, getAtPath as r, safeOwnRead as s, setAtPath as t, unset as u };
-//# sourceMappingURL=attaform.DGCijpZT.mjs.map
+//# sourceMappingURL=attaform.CuUx4jWI.mjs.map