attaform 0.27.0 → 0.27.2

package/dist/shared/{attaform.CyQxTOdX.mjs → attaform.DGCijpZT.mjs}

@@ -1,5 +1,5 @@
-import { computed, ref, watchEffect, getCurrentScope, onScopeDispose, shallowReadonly, nextTick, warn, readonly, toRaw, reactive, watch, markRaw, triggerRef, shallowRef, getCurrentInstance, onServerPrefetch, provide, useId, inject, onBeforeMount, onBeforeUpdate, onMounted, effectScope } from 'vue';
-import { n as pathsEqual, k as isPathPrefix, _ as __DEV__, f as canonicalizePath, s as segmentsForPathKey, o as keyForSegments, b as ROOT_PATH_KEY, S as SubmitErrorHandlerError, t as toError, q as normalizeErrorInput, w as INTERACTIVE_TAG_NAMES, R as ROOT_PATH, x as normalizeErrorInputs, y as coerceToPathKey, a as InvalidUseFormConfigError, z as ensureAttaformInstalled, u as useRegistry, B as kFormContext, C as kFormInstanceId, d as ReservedFormKeyError, m as kAttaformWizardActiveStepResolver, E as kAttaformAncestorWizard } from './attaform.Da8EdI2t.mjs';
+import { computed, ref, watchEffect, getCurrentScope, onScopeDispose, shallowReadonly, nextTick, warn, readonly, toRaw, reactive, toValue, watch, markRaw, triggerRef, shallowRef, getCurrentInstance, onServerPrefetch, provide, useId, inject, onBeforeMount, onBeforeUpdate, onMounted, effectScope } from 'vue';
+import { n as pathsEqual, k as isPathPrefix, _ as __DEV__, f as canonicalizePath, s as segmentsForPathKey, o as keyForSegments, b as ROOT_PATH_KEY, S as SubmitErrorHandlerError, t as toError, q as normalizeErrorInput, w as INTERACTIVE_TAG_NAMES, R as ROOT_PATH, x as normalizeErrorInputs, y as coerceToPathKey, a as InvalidUseFormConfigError, z as ensureAttaformInstalled, u as useRegistry, B as kFormContext, C as kFormInstanceId, d as ReservedFormKeyError, m as kAttaformWizardActiveStepResolver, E as kAttaformAncestorWizard } from './attaform.CgsQZdy1.mjs';
 import { R as REGISTER_OWNER_MARKER, b as V_REGISTER_MARKER } from './attaform.KvlEedlF.mjs';
 
 function safeAssign(target, key, value) {
@@ -593,7 +593,17 @@ const AttaformErrorCode = {
    * keeps them; a bare `Error` or a non-Error throw defaults here at the
    * form-level path `[]`.
    */
-  SubmitError: "atta:submit-error"
+  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.
+   */
+  GateNotCleared: "atta:gate-not-cleared"
 };
 function makeBlankRequiredError(segments, formKey) {
   return {
@@ -608,6 +618,7 @@ function isGateOpen(field, formMeta) {
   return formMeta.submissionAttempts > 0 || field.blurredAfterInteraction === true;
 }
 function computeVerdict(field, formMeta) {
+  if (field.disabled === true) return "idle";
   if (!isGateOpen(field, formMeta)) return "idle";
   const hasOwnError = field.errors.some(
     (e) => e.path.length === field.path.length && e.path.every((s, i) => s === field.path[i])
@@ -815,6 +826,7 @@ function buildLeafFieldStateBase(state, segments, key, formInstanceId) {
     ...computeFieldIdentity(formInstanceId, state.formKey, key),
     key: state.arrayElementKey(segments),
     blank: state.blankPaths.has(key),
+    disabled: state.effectiveDisabled.value,
     label,
     description: resolved.description,
     placeholder: resolved.placeholder,
@@ -1002,6 +1014,7 @@ function buildContainerFieldStateBase(state, segments, key, formInstanceId) {
       ...computeFieldIdentity(formInstanceId, state.formKey, key),
       key: state.arrayElementKey(segments),
       blank,
+      disabled: state.effectiveDisabled.value,
       label,
       description: resolved.description,
       placeholder: resolved.placeholder,
@@ -1056,7 +1069,8 @@ function decorateWithDerivedProps(base, state, getFormMetaBase, key, validatingS
     rollupApplies = true;
   }
   const submitValidating = rollupApplies && isRoot && state.submitting.value && state.activeValidations.value > 0;
-  const displayState = machine.display === "pending" || submitValidating ? "pending" : rollupApplies && revealedDescendantError ? "error" : machine.display;
+  const resolvedDisplayState = machine.display === "pending" || submitValidating ? "pending" : rollupApplies && revealedDescendantError ? "error" : machine.display;
+  const displayState = base.disabled === true ? "idle" : resolvedDisplayState;
   return {
     ...base,
     displayState,
@@ -1644,6 +1658,7 @@ const FIELD_STATE_KEYS = /* @__PURE__ */ new Set([
   "aria",
   "key",
   "blank",
+  "disabled",
   "label",
   "description",
   "placeholder",
@@ -2413,6 +2428,9 @@ function buildRegister(state, formInstanceId, instanceConfig) {
         return Object.prototype.toString.call(raw);
       }
     });
+    const hostModelValue = computed(
+      () => state.blankPaths.has(pathKey) ? void 0 : innerRef.value
+    );
     const slimDefault = state.schema.getDefaultAtPath(segments);
     const slimTypes = state.schema.getSlimPrimitiveTypesAtPath(segments);
     const acceptsUndefined = slimTypes.has("undefined");
@@ -2432,19 +2450,18 @@ function buildRegister(state, formInstanceId, instanceConfig) {
     const isRequired = state.schema.isRequiredAtPath(segments);
     const ariaEnabled = options?.autoAria ?? formAutoAria;
     const ariaDisplayState = getDisplayStateAt !== void 0 ? computed(() => getDisplayStateAt(segments)) : void 0;
+    const markBlank = () => state.setValueAtPath(segments, slimDefault, withInstanceMeta({ blank: true }));
     const internalRv = {
       innerRef,
       displayValue,
+      hostModelValue,
+      // Live form-freeze flag for the compile-time transforms' `:disabled`
+      // bind (native attribute + component-host prop) and custom
+      // `useRegister` integrations. Reads the form-level effective freeze,
+      // so every binding on a disabled form reports `true`.
+      disabled: computed(() => state.effectiveDisabled.value),
       lastTypedForm,
-      markBlank: () => {
-        return state.setValueAtPath(
-          segments,
-          slimDefault,
-          withInstanceMeta({
-            blank: true
-          })
-        );
-      },
+      markBlank,
       markInteracted: () => {
         state.markInteracted(segments);
       },
@@ -2462,7 +2479,8 @@ function buildRegister(state, formInstanceId, instanceConfig) {
       },
       setValueFromHost: (value) => {
         state.markInteracted(segments);
-        const accepted = state.setValueAtPath(segments, value, withInstanceMeta(void 0));
+        const isBlankSignal = value === "" && !acceptsString || value === null && !slimTypes.has("null") || value === void 0 && !acceptsUndefined;
+        const accepted = isBlankSignal ? markBlank() : state.setValueAtPath(segments, value, withInstanceMeta(void 0));
         if (__DEV__) {
           const dedupeKey = `${formInstanceId}:${pathKey}`;
           const isWired = () => (state.elements.get(pathKey)?.elements.size ?? 0) > 0 || state.getFieldRecord(segments)?.connected === true;
@@ -2909,6 +2927,9 @@ function buildFormApi(state, formInstanceId, options = {}) {
       get blank() {
         return rootBase().blank;
       },
+      get disabled() {
+        return rootBase().disabled;
+      },
       get label() {
         return rootBase().label;
       },
@@ -3227,6 +3248,9 @@ function buildFormApi(state, formInstanceId, options = {}) {
       get blank() {
         return rootFieldState.value.blank;
       },
+      get disabled() {
+        return rootFieldState.value.disabled;
+      },
       get label() {
         return rootFieldState.value.label;
       },
@@ -4269,6 +4293,24 @@ function createFormStore(options) {
   const submitted = ref(false);
   const submitError = ref(null);
   const departAttempts = ref(0);
+  const externalLock = ref(false);
+  let warnedDisabledThrow = false;
+  let warnedDisabledWrite = false;
+  const effectiveDisabled = computed(() => {
+    let own = false;
+    try {
+      own = Boolean(toValue(options.disabled));
+    } catch (err) {
+      if (__DEV__ && !warnedDisabledThrow) {
+        warnedDisabledThrow = true;
+        console.warn(
+          `[attaform] useForm({ disabled }) getter threw for form "${String(formKey)}"; treating its config as enabled. Fix the getter to clear this warning.`,
+          err
+        );
+      }
+    }
+    return own || externalLock.value;
+  });
   const submissionGeneration = ref(0);
   const activeValidations = ref(0);
   const pathSnapshots = /* @__PURE__ */ new Map();
@@ -4562,6 +4604,15 @@ function createFormStore(options) {
     commitWritePatches(patches, meta);
   }
   function setValueAtPath(path, value, meta) {
+    if (effectiveDisabled.value) {
+      if (__DEV__ && !warnedDisabledWrite) {
+        warnedDisabledWrite = true;
+        console.warn(
+          `[attaform] Ignored a write to a disabled form ("${String(formKey)}"). Value writes no-op while \`disabled\` resolves truthy. This warning fires once.`
+        );
+      }
+      return false;
+    }
     if (meta?.arrayOp !== void 0 && Array.isArray(value)) {
       for (const idx of freshElementIndices(meta.arrayOp)) {
         value[idx] = stripSymbolsDeep(value[idx]);
@@ -5125,6 +5176,7 @@ function createFormStore(options) {
     }
   }
   function markFocused(path, focused, meta) {
+    if (effectiveDisabled.value) return;
     const { key } = canonicalizePath(path);
     const current = fields.get(key);
     touchFieldRecord(key, path, {
@@ -5172,6 +5224,7 @@ function createFormStore(options) {
     }
   }
   function markInteracted(path) {
+    if (effectiveDisabled.value) return;
     const { key } = canonicalizePath(path);
     if (fields.get(key)?.interacted === true) return;
     touchFieldRecord(key, path, { interacted: true });
@@ -5488,6 +5541,8 @@ function createFormStore(options) {
     submitted,
     submitError,
     departAttempts,
+    effectiveDisabled,
+    externalLock,
     hydrating,
     hydrateError,
     defaultValuesFactory,
@@ -5875,6 +5930,7 @@ function mergeWithDefaults(defaults, configuration) {
   const onInvalidSubmit = configuration.onInvalidSubmit ?? defaults.onInvalidSubmit;
   const history = configuration.history ?? defaults.history;
   const rememberVariants = configuration.rememberVariants ?? defaults.rememberVariants;
+  const disabled = configuration.disabled ?? defaults.disabled;
   const coerce = configuration.coerce ?? defaults.coerce;
   const validateOn = configuration.validateOn ?? defaults.validateOn;
   const debounceMs = configuration.debounceMs ?? defaults.debounceMs;
@@ -5887,6 +5943,7 @@ function mergeWithDefaults(defaults, configuration) {
     ...onInvalidSubmit === void 0 ? {} : { onInvalidSubmit },
     ...history === void 0 ? {} : { history },
     ...rememberVariants === void 0 ? {} : { rememberVariants },
+    ...disabled === void 0 ? {} : { disabled },
     ...coerce === void 0 ? {} : { coerce },
     ...validateOn === void 0 ? {} : { validateOn },
     ...debounceMs === void 0 ? {} : { debounceMs },
@@ -5932,6 +5989,7 @@ function buildFreshState(key, schema, configuration, registry) {
       }
     } : {},
     ...configuration.rememberVariants !== void 0 ? { rememberVariants: configuration.rememberVariants } : {},
+    ...configuration.disabled !== void 0 ? { disabled: configuration.disabled } : {},
     ...configuration.coerce !== void 0 ? { coerce: configuration.coerce } : {},
     ...configuration.getDisplayState !== void 0 ? { getDisplayState: configuration.getDisplayState } : {},
     ...initialBlankPaths !== void 0 ? { initialBlankPaths } : {}
@@ -6156,6 +6214,14 @@ function isLazyMarker(value) {
   return typeof value === "object" && value !== null && LAZY_BRAND in value;
 }
 
+const GATE_BRAND = /* @__PURE__ */ Symbol.for("attaform/wizard-gate");
+function gate(step) {
+  return { [GATE_BRAND]: true, inner: step };
+}
+function isGateMarker(value) {
+  return typeof value === "object" && value !== null && GATE_BRAND in value;
+}
+
 const NOOP_WIZARD_HISTORY = {
   push() {
   },
@@ -6279,14 +6345,17 @@ const PENDING_STATUS = {
   valid: false,
   dirty: false,
   submitted: false,
-  errorCount: 0
+  errorCount: 0,
+  locked: false
 };
 const NOOP_VALID_STATUS = {
   valid: true,
   dirty: false,
   submitted: false,
-  errorCount: 0
+  errorCount: 0,
+  locked: false
 };
+const EMPTY_LOCK_SET = /* @__PURE__ */ new Set();
 function asStatusSource(form) {
   return form;
 }
@@ -6353,7 +6422,7 @@ function useWizard(options) {
     }
   }
   const lazyEpoch = ref(0);
-  const lazyComputeds = /* @__PURE__ */ new Map();
+  const lazyComputeds = /* @__PURE__ */ new WeakMap();
   const activeKey = ref("");
   const formsAccumulator = /* @__PURE__ */ new Map();
   for (const slot of rawSteps) {
@@ -6389,50 +6458,44 @@ function useWizard(options) {
       return activeKey.value === "" ? void 0 : activeKey.value;
     }
   };
-  function resolveSlot(slot, index, ctx) {
-    if (slot === void 0 || slot === null) return void 0;
-    if (typeof slot === "string") {
-      return getOrBuildNoop(slot);
-    }
-    if (isLazyMarker(slot)) {
-      const c = lazyComputeds.get(index);
-      return c === void 0 ? void 0 : resolveSlotResult(c.value);
+  function lazyComputedFor(marker) {
+    const cached = lazyComputeds.get(marker);
+    if (cached !== void 0) return cached;
+    const c = computed(() => {
+      void lazyEpoch.value;
+      return marker.resolve(slotCtx);
+    });
+    lazyComputeds.set(marker, c);
+    return c;
+  }
+  const MAX_SLOT_DEPTH = 32;
+  function normalizeSlot(slot, ctx, gated, depth) {
+    if (depth > MAX_SLOT_DEPTH) {
+      if (__DEV__) {
+        console.warn(
+          `[attaform] useWizard: a step slot nested past ${MAX_SLOT_DEPTH} levels (gate / lazy / function); dropping it. Check for a resolver that returns itself.`
+        );
+      }
+      return void 0;
     }
+    if (slot === void 0 || slot === null) return void 0;
+    if (typeof slot === "string") return { form: getOrBuildNoop(slot), gated };
+    if (isGateMarker(slot)) return normalizeSlot(slot.inner, ctx, true, depth + 1);
+    if (isLazyMarker(slot)) return normalizeSlot(lazyComputedFor(slot).value, ctx, gated, depth + 1);
     if (typeof slot === "function") {
       const result = slot(ctx);
-      return resolveSlotResult(result);
+      return normalizeSlot(result, ctx, gated, depth + 1);
     }
-    if (isAnyForm(slot)) return slot;
+    if (isAnyForm(slot)) return { form: slot, gated };
     return void 0;
   }
-  function resolveSlotResult(result) {
-    if (result === void 0 || result === null) return void 0;
-    if (typeof result === "string") {
-      return getOrBuildNoop(result);
-    }
-    return result;
-  }
-  for (let i = 0; i < rawSteps.length; i++) {
-    const slot = rawSteps[i];
-    if (isLazyMarker(slot)) {
-      const idx = i;
-      const marker = slot;
-      lazyComputeds.set(
-        idx,
-        computed(() => {
-          void lazyEpoch.value;
-          return marker.resolve(slotCtx);
-        })
-      );
-    }
-  }
   const compiledSteps = computed(() => {
     const out = [];
     const seen = /* @__PURE__ */ new Set();
     for (let i = 0; i < rawSteps.length; i++) {
-      const slot = rawSteps[i];
-      const form = resolveSlot(slot, i, slotCtx);
-      if (form === void 0) continue;
+      const norm = normalizeSlot(rawSteps[i], slotCtx, false, 0);
+      if (norm === void 0) continue;
+      const { form, gated } = norm;
       if (seen.has(form.key)) {
         if (__DEV__) {
           console.warn(
@@ -6443,7 +6506,7 @@ function useWizard(options) {
       }
       seen.add(form.key);
       trackOnce(form);
-      out.push({ key: form.key, form });
+      out.push({ key: form.key, form, isGate: gated });
     }
     return out;
   });
@@ -6479,12 +6542,12 @@ function useWizard(options) {
     if (key === "") return;
     if (list.some((step) => step.key === key)) return;
     if (list.length === 0) {
-      activeKey.value = "";
+      commitActiveKey("");
       return;
     }
     const oldIndex = prevList.findIndex((step) => step.key === key);
     const slid = list[oldIndex < 0 ? 0 : Math.min(oldIndex, list.length - 1)];
-    if (slid !== void 0) activeKey.value = slid.key;
+    if (slid !== void 0) commitActiveKey(slid.key);
   });
   const activeFormFacade = new Proxy({}, {
     get(_target, prop) {
@@ -6618,6 +6681,136 @@ function useWizard(options) {
       };
     }
   });
+  const mightGate = rawSteps.some(
+    (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();
+    for (const step of compiledSteps.value) if (step.isGate) gateKeys.add(step.key);
+    for (const key of gateKeys) {
+      if (!gateSubs.has(key)) {
+        const store = registry.forms.get(key);
+        if (store !== void 0) {
+          gateSubs.set(
+            key,
+            store.onSubmitSuccess(() => {
+              clearedGates.add(key);
+            })
+          );
+        }
+      }
+      sampleSeededGate(key);
+    }
+    for (const [key, unsub] of gateSubs) {
+      if (!gateKeys.has(key)) {
+        unsub();
+        gateSubs.delete(key);
+      }
+    }
+  }
+  const gatePositions = computed(
+    () => compiledSteps.value.filter((step) => step.isGate).map((step) => step.key)
+  );
+  const navLockSet = computed(() => {
+    const out = /* @__PURE__ */ new Set();
+    let sealed = false;
+    for (const step of compiledSteps.value) {
+      if (sealed) {
+        out.add(step.key);
+        continue;
+      }
+      if (step.isGate && !clearedGates.has(step.key)) sealed = true;
+    }
+    return out.size === 0 ? EMPTY_LOCK_SET : out;
+  });
+  const freezeSet = computed(() => {
+    const out = new Set(navLockSet.value);
+    for (const key of gatePositions.value) if (clearedGates.has(key)) out.add(key);
+    return out.size === 0 ? EMPTY_LOCK_SET : out;
+  });
+  function lastReachableKey() {
+    const list = compiledSteps.value;
+    const locked = navLockSet.value;
+    let last;
+    for (const step of list) {
+      if (locked.has(step.key)) break;
+      last = step.key;
+    }
+    return last;
+  }
+  function resolveLandingKey(target) {
+    if (!navLockSet.value.has(target)) return target;
+    const redirect = lastReachableKey();
+    if (redirect === void 0) return target;
+    if (!isFormReady(redirect)) return target;
+    return redirect;
+  }
+  function commitActiveKey(target) {
+    const landing = target === "" ? "" : resolveLandingKey(target);
+    if (activeKey.value !== landing) activeKey.value = landing;
+    return landing;
+  }
+  if (mightGate) {
+    watch(
+      () => {
+        const parts = [];
+        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}`);
+        }
+        return parts.join("|");
+      },
+      reconcileGates,
+      { immediate: true }
+    );
+    let previouslyFrozen = [];
+    watchEffect(() => {
+      const frozen = freezeSet.value;
+      for (const key of previouslyFrozen) {
+        if (!frozen.has(key)) {
+          const store = registry.forms.get(key);
+          if (store !== void 0) store.externalLock.value = false;
+        }
+      }
+      for (const key of frozen) {
+        const store = registry.forms.get(key);
+        if (store !== void 0) store.externalLock.value = true;
+      }
+      previouslyFrozen = [...frozen];
+    });
+    if (getCurrentScope() !== void 0) {
+      onScopeDispose(() => {
+        for (const key of previouslyFrozen) {
+          const store = registry.forms.get(key);
+          if (store !== void 0) store.externalLock.value = false;
+        }
+        for (const unsub of gateSubs.values()) unsub();
+        gateSubs.clear();
+      });
+    }
+  }
   const seedRef = ref(void 0);
   const seedInput = options.defaultStatuses;
   if (seedInput !== void 0) {
@@ -6641,6 +6834,7 @@ function useWizard(options) {
     if (cached !== void 0) return cached;
     const source = asStatusSource(form);
     const computedStatus = computed(() => {
+      const locked = navLockSet.value.has(form.key);
       if (isFormReady(form.key)) {
         const meta = source.meta;
         if (meta !== void 0 && meta !== null) {
@@ -6648,16 +6842,17 @@ function useWizard(options) {
             valid: meta.valid,
             dirty: meta.dirty,
             submitted: meta.submitted,
-            errorCount: meta.errorCount
+            errorCount: meta.errorCount,
+            locked
           };
         }
       }
-      if (noopForms.has(form.key)) return NOOP_VALID_STATUS;
-      const seedMap = seedRef.value;
-      if (seedMap !== void 0 && Object.hasOwn(seedMap, form.key)) {
-        return seedMap[form.key];
+      if (noopForms.has(form.key)) {
+        return locked ? { ...NOOP_VALID_STATUS, locked: true } : NOOP_VALID_STATUS;
       }
-      return PENDING_STATUS;
+      const seed = seedRef.value?.[form.key];
+      if (seed !== void 0) return { ...seed, locked };
+      return locked ? { ...PENDING_STATUS, locked: true } : PENDING_STATUS;
     });
     statusCache.set(form.key, computedStatus);
     return computedStatus;
@@ -6773,8 +6968,8 @@ function useWizard(options) {
     initialKey = firstKey();
   }
   if (initialKey !== void 0) {
-    activeKey.value = initialKey;
-    visited.value = [initialKey];
+    const landing = commitActiveKey(initialKey);
+    visited.value = [landing];
   }
   if (registry.ssr) {
     for (const step of compiledSteps.value) {
@@ -6806,8 +7001,8 @@ function useWizard(options) {
           return;
         }
         if (step === activeKey.value) return;
-        activeKey.value = step;
-        if (!visited.value.includes(step)) visited.value.push(step);
+        const landing = commitActiveKey(step);
+        if (!visited.value.includes(landing)) visited.value.push(landing);
       }
     );
   }
@@ -6839,11 +7034,11 @@ function useWizard(options) {
   }
   function moveTo(key, options2) {
     if (activeKey.value === key) return;
-    activeKey.value = key;
-    if (!visited.value.includes(key)) visited.value.push(key);
+    const landing = commitActiveKey(key);
+    if (!visited.value.includes(landing)) visited.value.push(landing);
     const list = compiledSteps.value;
     for (const step of list) {
-      if (step.key === key) {
+      if (step.key === landing) {
         activateForm(step.form);
         return;
       }
@@ -6853,6 +7048,14 @@ function useWizard(options) {
     const store = registry.forms.get(key);
     if (store !== void 0) store.departAttempts.value += 1;
   }
+  function advanceOne() {
+    const list = compiledSteps.value;
+    const idx = activeIndex.value;
+    if (idx < 0 || idx >= list.length - 1) return;
+    recordDeparture(activeKey.value);
+    const target = list[idx + 1];
+    moveTo(target.key);
+  }
   async function next() {
     if (submitting.value) {
       if (__DEV__) {
@@ -6878,9 +7081,12 @@ function useWizard(options) {
       }
       return;
     }
-    recordDeparture(activeKey.value);
-    const target = list[idx + 1];
-    moveTo(target.key);
+    const active = list[idx];
+    if (active !== void 0 && active.isGate) {
+      await tryNext();
+      return;
+    }
+    advanceOne();
   }
   async function tryNext() {
     if (submitting.value) {
@@ -6907,13 +7113,13 @@ function useWizard(options) {
     }
     const form = activeForm.value;
     if (form === void 0) return false;
-    let advanced = false;
+    const before = activeKey.value;
+    let ranClean = false;
     await asHandleSubmitSource(form).handleSubmit(() => {
-      const before = activeKey.value;
-      next();
-      advanced = activeKey.value !== before;
+      ranClean = true;
     })();
-    return advanced;
+    if (ranClean) advanceOne();
+    return activeKey.value !== before;
   }
   function back() {
     if (submitting.value) {
@@ -6953,6 +7159,11 @@ function useWizard(options) {
       }
       return;
     }
+    if (__DEV__ && navLockSet.value.has(key)) {
+      console.warn(
+        `[attaform] wizard.goTo("${key}"): that step sits behind an uncleared gate(); the navigation was refused. Clear the gate before navigating here.`
+      );
+    }
     if (key !== activeKey.value) recordDeparture(activeKey.value);
     moveTo(key);
   }
@@ -7012,6 +7223,20 @@ function useWizard(options) {
     }
     return out;
   }
+  function collectUnclearedGateErrors() {
+    const out = [];
+    for (const step of compiledSteps.value) {
+      if (step.isGate && !clearedGates.has(step.key)) {
+        out.push({
+          formKey: step.key,
+          path: [],
+          message: `Step "${step.key}" is a gate that has not been cleared. Submit it to continue.`,
+          code: AttaformErrorCode.GateNotCleared
+        });
+      }
+    }
+    return out;
+  }
   async function focusFirstWizardError(errors) {
     if (options.focusFirstError === false) return;
     const firstFailedKey = errors[0]?.formKey;
@@ -7068,7 +7293,9 @@ function useWizard(options) {
         }
         submissionAttempts.value += 1;
         const errors = collectErrors(results);
-        if (errors.length === 0) {
+        const gateErrors = mightGate ? collectUnclearedGateErrors() : [];
+        const blocking = gateErrors.length > 0 ? [...errors, ...gateErrors] : errors;
+        if (blocking.length === 0) {
           const valuesMap = {};
           for (const step of list) {
             const processed = results.get(step.key);
@@ -7094,10 +7321,10 @@ function useWizard(options) {
           }
           done.value = true;
         } else {
-          await focusFirstWizardError(errors);
+          await focusFirstWizardError(blocking);
           if (onError !== void 0) {
             try {
-              await onError(errors);
+              await onError(blocking);
             } catch (cause) {
               throw new SubmitErrorHandlerError("User-provided onError threw", { cause });
             }
@@ -7114,21 +7341,35 @@ function useWizard(options) {
     submissionAttempts.value = 0;
     done.value = false;
     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();
     const firstStep = compiledSteps.value[0];
     if (firstStep !== void 0) {
-      activeKey.value = firstStep.key;
-      visited.value = [firstStep.key];
+      const landing = commitActiveKey(firstStep.key);
+      visited.value = [landing];
       if (persistCallback !== void 0) {
-        lastPersisted = firstStep.key;
-        persistCallback({ step: firstStep.key });
+        lastPersisted = landing;
+        persistCallback({ step: landing });
       }
     }
   }
+  if (mightGate) {
+    watchEffect(() => {
+      const key = activeKey.value;
+      if (key === "" || !navLockSet.value.has(key)) return;
+      const redirect = lastReachableKey();
+      if (redirect === void 0 || redirect === key || !isFormReady(redirect)) return;
+      moveTo(redirect);
+    });
+  }
   if (getCurrentScope() !== void 0) {
     onScopeDispose(() => {
       historyHandle.dispose();
@@ -7324,5 +7565,5 @@ 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, useAbstractForm as g, useRegister as h, injectForm as i, useWizard as j, isPlainRecord as k, lazy as l, makeDefaultDisplayState as m, safeAssign as n, slimKindOf as o, humanize as p, getAtPath as q, setAtPath as r, safeOwnRead as s, unset as u };
-//# sourceMappingURL=attaform.CyQxTOdX.mjs.map
+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