attaform 0.20.2 → 0.21.1

package/dist/shared/{attaform.sWm8B15V.d.mts → attaform.BWfliRIK.d.cts}

@@ -1,4 +1,4 @@
-import { t as FormKey, ae as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, T as PathKey, S as Path, am as ValidationError, A as AbstractSchema, x as GetDisplayState, aq as WriteMeta, D as DeepPartial, ar as WriteShape, ak as ValidateOn, Y as PersistOptInRegistry, f as AttaformDefaults, aj as UseFormReturnType, a8 as RegisterValue } from './attaform.99cfHcIt.mjs';
+import { v as FormKey, V as PathKey, m as DisplayCtx, z as GetDisplayState, n as DisplayMachine, ag as SlimPrimitiveKind, C as CoercionEntry, g as CoercionRegistry, G as GenericForm, U as Path, ap as ValidationError, A as AbstractSchema, at as WriteMeta, D as DeepPartial, au as WriteShape, aj as TransformAbortHolder, an as ValidateOn, _ as PersistOptInRegistry, f as AttaformDefaults, am as UseFormReturnType, aa as RegisterValue } from './attaform.D0dWZsJt.cjs';
 import { Ref, ComputedRef, App, InjectionKey } from 'vue';
 
 /**
@@ -414,6 +414,13 @@ type WizardForms<S> = FormsRecordOf<S> & Readonly<Record<FormKey, AnyForm>>;
  *  - `submissionAttempts` — count of `wizard.handleSubmit` invocations
  *                    (success or failure). Always bumps, including on
  *                    noop-form steps.
+ *  - `submitError` — the error thrown by the most recent
+ *                    `wizard.handleSubmit` callback (or its `onError`),
+ *                    coerced to a real `Error`. Mirrors
+ *                    `form.meta.submitError`: cleared at submit entry and
+ *                    by `reset()`, parked here rather than re-thrown, so
+ *                    the handler resolves and never manufactures a
+ *                    `window` unhandledrejection. `null` on success.
  *  - `visited`     — append-only breadcrumb of navigated step keys.
  *                    `back()` does not pop; the trail is the audit
  *                    log, not the back-stack.
@@ -447,6 +454,7 @@ type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepS
     readonly done: boolean;
     readonly submitting: boolean;
     readonly submissionAttempts: number;
+    readonly submitError: Error | null;
     readonly visited: readonly FormKey[];
     readonly next: () => Promise<void>;
     readonly back: () => void;
@@ -455,6 +463,68 @@ type UseWizardReturnType<S extends ReadonlyArray<StepSlot> = ReadonlyArray<StepS
     readonly reset: () => void;
 };
 
+/**
+ * Per-form display engine: owns the clock and the timers that the pure
+ * `getDisplayState` reducer policy needs, so the reducer itself stays a
+ * deterministic `(prev, ctx) => next` function.
+ *
+ * It keeps a `Map` of the machines that are still *active* (a spinner is
+ * showing, a verdict is being held, or a `reviewAt` deadline is pending),
+ * a single reactive `tick` ref, and a single `setTimeout` aimed at the
+ * nearest `reviewAt` across every active field. When a field-state
+ * computed reads `resolve`, it subscribes to `tick`; when the timer
+ * fires, `tick` bumps and every dependent computed re-runs the reducer,
+ * so a field whose deadline elapsed transitions (verdict → spinner, or
+ * spinner → settled verdict) without any per-field watcher.
+ *
+ * Eviction: a machine is dropped once it reaches a terminal *idle* state
+ * with no pending review. Error / success / pending machines are retained
+ * so the reducer can hold the prior verdict under the show-delay window of
+ * the *next* validation streak (no success → idle → success flicker). The
+ * retained set is bounded by the rendered non-idle fields; none of them
+ * arm a timer, so retention costs memory, never CPU.
+ *
+ * Untrusted reducer: `getDisplayState` is consumer-overridable, so the
+ * engine treats the returned `reviewAt` as untrusted. A non-finite deadline
+ * (NaN / ±Infinity from a custom predicate's bad arithmetic) is ignored
+ * rather than handed to `setTimeout`, where it coerces to 0 and spins; an
+ * over-large finite deadline is clamped below the 32-bit `setTimeout`
+ * overflow; and the timer refuses to re-arm for the exact deadline it just
+ * fired, so a predicate re-emitting a fixed or past `reviewAt` can't drive an
+ * infinite fire loop. None of these arise from the library default, which
+ * always advances its deadline or drops it.
+ *
+ * Background tabs: `setTimeout` is throttled to >= 1s while a tab is hidden,
+ * so a min-visible hold can overshoot. A `visibilitychange` listener bumps
+ * the clock on return to the foreground, so any overdue deadline resolves at
+ * once instead of lingering.
+ *
+ * SSR: no clock, no timers, no listener. With `now` frozen and nothing
+ * validating at render, the reducer returns the plain verdict (never
+ * pending) and the engine stores nothing, so the server HTML and the
+ * client's first render agree — no hydration mismatch on the display
+ * projection.
+ */
+type DisplayEngine = {
+    /**
+     * Resolve a path's next `DisplayMachine`. Subscribes the calling
+     * computed to the engine clock, threads the path's previous machine
+     * through `reducer`, persists or evicts the result, and re-arms the
+     * single timer to the nearest deadline.
+     */
+    resolve(key: PathKey, ctx: DisplayCtx, reducer: GetDisplayState): DisplayMachine;
+    /** Drop every retained machine and cancel the timer (used by `reset()`). */
+    clear(): void;
+    /** Tear down for good: `clear()` plus detaching the visibility listener. */
+    dispose(): void;
+    /** Introspection for tests: count of retained machines. */
+    size(): number;
+    /** Introspection for tests: whether a path currently has a retained machine. */
+    has(key: PathKey): boolean;
+    /** Introspection for tests: whether a deadline timer is currently armed. */
+    hasTimer(): boolean;
+};
+
 /**
  * Schema-driven coercion of user-typed DOM values at the v-register
  * directive layer. When the slim schema declares a numeric or
@@ -669,6 +739,16 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * read.
      */
     readonly getDisplayState: GetDisplayState;
+    /**
+     * Per-form display engine: owns the clock and the single timer the timed
+     * `getDisplayState` reducer policy needs, keeping the reducer itself a
+     * pure `(prev, ctx) => next` function. The field-state computeds route
+     * every `displayState` read through `displayEngine.resolve(...)`, which
+     * threads the path's previous machine, persists or evicts the result, and
+     * re-arms the nearest-deadline timer. Constructed once at form
+     * construction; torn down via `registerCleanup` on store eviction.
+     */
+    readonly displayEngine: DisplayEngine;
     readonly submitting: Ref<boolean>;
     readonly activeSubmissions: Ref<number>;
     readonly submissionAttempts: Ref<number>;
@@ -679,7 +759,7 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * alongside the rest of the submission surface.
      */
     readonly submitted: Ref<boolean>;
-    readonly submitError: Ref<unknown>;
+    readonly submitError: Ref<Error | null>;
     readonly departAttempts: Ref<number>;
     /**
      * `true` while a function-form `defaultValues` factory is in flight.
@@ -838,6 +918,61 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * computed only re-runs when the count for ITS key changes.
      */
     readonly fieldValidationCounts: Map<PathKey, number>;
+    /**
+     * Per-path `Date.now()` stamp marking when the field's LATEST validation
+     * run started, re-anchored on every run start (every increment), deleted
+     * on the `→ 0` edge. The display reducer reads it as `ctx.validatingSince`
+     * to time the anti-flash spinner, which measures `now - validatingSince`:
+     * re-anchoring on each run means a burst of keystrokes (each aborting the
+     * prior run and starting a new one) keeps pushing the stamp forward, so the
+     * spinner stays suppressed until the user pauses rather than surfacing
+     * mid-typing. Anchoring only at the streak start would pin it to the first
+     * keystroke, because with `debounceMs: 0` the aborted run's decrement lands
+     * after the next run's increment and the count never returns to 0 between
+     * fast keystrokes. The field-state container walk takes the descendant-min
+     * so a row spinner anchors at its earliest still-active leaf. Runtime-only,
+     * never hydrated, like the counts. REACTIVE: the display computed reads this
+     * (as `ctx.validatingSince`) but not the `validating` flag, and a long
+     * validation that settles with an unchanged verdict (same error, still
+     * invalid) leaves `errors` / `valid` untouched — so a non-reactive map would
+     * leave a held `pending` spinner stranded after the run ends, until some
+     * unrelated reactive change happened to re-run the computed. Reactivity ties
+     * the computed to both the streak start (set) and end (delete).
+     */
+    readonly fieldValidatingSince: Map<PathKey, number>;
+    /**
+     * Per-path counter of in-flight async-transform runs (the async
+     * branch of the `register({ transforms })` pipeline). `> 0` drives
+     * `field.transforming` / `field.busy`. Counter, not flag, for the
+     * same overlap reason as `fieldValidationCounts`, except a superseding
+     * input releases the prior run synchronously before incrementing the
+     * new one — so the count is the live in-flight depth at the path
+     * (effectively 0 or 1). Reactive Map, like the validation counters.
+     */
+    readonly fieldTransformCounts: Map<PathKey, number>;
+    /**
+     * Per-path `ssr ? 0 : Date.now()` stamp marking when the path's latest
+     * async transform opened; the display reducer reads it (as
+     * `ctx.transformingSince`) to time the gated busy spinner. Mirrors
+     * `fieldValidatingSince` exactly: re-anchored on each run start,
+     * deleted on the `→ 0` edge, reactive for the held-spinner reason.
+     */
+    readonly fieldTransformingSince: Map<PathKey, number>;
+    /**
+     * Per-path latest async-transform failure (a rejected transform, or a
+     * resolved value the write gate refused), surfaced as
+     * `field.transformError`. Cleared when a fresh run opens at the path
+     * and on `reset()`. A channel separate from validation `errors`.
+     */
+    readonly transformErrors: Map<PathKey, Error | null>;
+    /**
+     * Form-wide count of in-flight async-transform runs. Drives the
+     * `settleTransforms` quiescence guard and the `handleSubmit` drain
+     * barrier. `Math.max(0, …)`-clamped on release so a doubled decrement
+     * (a run's own `endTransform` after a synchronous cancel release)
+     * can't drive it negative.
+     */
+    readonly activeTransforms: Ref<number>;
     /**
      * Replace the form value wholesale. Optional `meta` is forwarded to
      * every `onFormChange` listener so they can decide whether THIS write
@@ -1005,6 +1140,41 @@ type FormStore<F extends GenericForm, G extends GenericForm = F> = {
      * at entry (submit validation is authoritative) and by `reset()`.
      */
     cancelFieldValidation(): void;
+    /**
+     * Open an async-transform run at `key` — bump the run token, increment
+     * the in-flight counters, stamp `transformingSince`, clear any prior
+     * `transformError`, register `holder` for later abort. Returns the run
+     * token. See `InternalRegisterValue.beginTransform`.
+     */
+    beginTransform(key: PathKey, holder: TransformAbortHolder): number;
+    /** `true` while `token` is the live async-transform run at `key`. */
+    isCurrentTransform(key: PathKey, token: number): boolean;
+    /**
+     * Close the run `token` at `key`: release the counters (no-op if the
+     * run was already released by a supersede / cancel) and flush settled
+     * `settleTransforms` waiters.
+     */
+    endTransform(key: PathKey, token: number): void;
+    /** Record a per-field normalization failure at `key` (`field.transformError`). */
+    setTransformError(key: PathKey, err: Error): void;
+    /**
+     * Abort + release every in-flight async-transform run (all paths) and
+     * clear `transformErrors`. Mirrors `cancelFieldValidation`; called by
+     * `reset()` and store teardown.
+     */
+    cancelTransforms(): void;
+    /**
+     * Path-scoped counterpart to `cancelTransforms`: abort + release only
+     * the runs at-or-under `prefix`, clearing their `transformError`.
+     * Called by `resetField`.
+     */
+    cancelTransformsUnder(prefix: Path): void;
+    /**
+     * Resolve once async transforms are quiescent — globally (`path`
+     * omitted) or at-or-under `path`. Resolve-never-reject. See
+     * `UseFormReturnType.settleTransforms`.
+     */
+    settleTransforms(path?: string | Path): Promise<void>;
     /**
      * Kick off (or schedule) a field-level validation run for `path`. Pass
      * `path = []` to cover the whole form; `applySchemaErrorsForSubtree`

package/dist/shared/{attaform.BGk8cfw2.mjs → attaform.Be8NZG9M.mjs}

@@ -1,5 +1,5 @@
-import { A as AttaformErrorCode, e as isPlainRecord, j as safeOwnRead, s as safeAssign, m as slimKindOf } from './attaform.tiWEVznj.mjs';
-import { j as canonicalizePath } from './attaform.QG5TG8lB.mjs';
+import { A as AttaformErrorCode, m as isPlainRecord, v as safeOwnRead, u as safeAssign, x as slimKindOf } from './attaform.DR6RmxWZ.mjs';
+import { j as canonicalizePath } from './attaform.pmtahXKy.mjs';
 
 const PATH_SEPARATOR = ".";
 function createAbstractSchema(rootSchema, intro, services, formKey, options) {
@@ -90,6 +90,12 @@ function createAbstractSchema(rootSchema, intro, services, formKey, options) {
       if (kind === "array") return null;
       return void 0;
     },
+    isFixedObjectAtPath(path) {
+      if (path.length === 0) return true;
+      const resolved = services.getNestedSchemasAtPath(rootSchema, path, maxRecursionDepth);
+      if (resolved.length === 0) return false;
+      return resolved.every((s) => intro.kindOf(services.peelAllWrappers(s)) === "object");
+    },
     getSchemasAtPath(path) {
       const resolved = services.getNestedSchemasInSlimMode(rootSchema, path, maxRecursionDepth);
       if (resolved.length === 0) return [];
@@ -271,6 +277,23 @@ function createAbstractSchema(rootSchema, intro, services, formKey, options) {
   return abstractSchema;
 }
 
+function mergeDeep(base, override) {
+  if (override === void 0) return base;
+  if (!isPlainRecord(override)) return override;
+  if (!isPlainRecord(base)) return override;
+  const result = { ...base };
+  for (const key of Object.keys(override)) {
+    const oVal = safeOwnRead(override, key);
+    const bVal = safeOwnRead(base, key);
+    if (isPlainRecord(oVal) && isPlainRecord(bVal)) {
+      safeAssign(result, key, mergeDeep(bVal, oVal));
+    } else {
+      safeAssign(result, key, oVal);
+    }
+  }
+  return result;
+}
+
 function walkPathSegments(schema, segments, intro, maxDepth, lazyDepth) {
   if (segments.length === 0) return [schema];
   const [head, ...rest] = segments;
@@ -358,23 +381,6 @@ function walkPathSegments(schema, segments, intro, maxDepth, lazyDepth) {
   }
 }
 
-function mergeDeep(base, override) {
-  if (override === void 0) return base;
-  if (!isPlainRecord(override)) return override;
-  if (!isPlainRecord(base)) return override;
-  const result = { ...base };
-  for (const key of Object.keys(override)) {
-    const oVal = safeOwnRead(override, key);
-    const bVal = safeOwnRead(base, key);
-    if (isPlainRecord(oVal) && isPlainRecord(bVal)) {
-      safeAssign(result, key, mergeDeep(bVal, oVal));
-    } else {
-      safeAssign(result, key, oVal);
-    }
-  }
-  return result;
-}
-
 const NO_EMBEDDED_DEFAULT = Symbol("atta:no-embedded-default");
 function peelEmbeddedDefault(schema, intro) {
   let current = schema;
@@ -770,5 +776,156 @@ function slimPrimitivesWalk(schema, intro, maxDepth, lazyDepth = 0) {
   }
 }
 
-export { NO_EMBEDDED_DEFAULT as N, getFieldMetaListForSchema as a, createAbstractSchema as c, deriveDefaultWalk as d, fieldMetaStore as f, getFieldMetaForSchema as g, mergeDeep as m, peelEmbeddedDefault as p, slimPrimitivesWalk as s, walkPathSegments as w };
-//# sourceMappingURL=attaform.BGk8cfw2.mjs.map
+const pathMetaCache = /* @__PURE__ */ new WeakMap();
+function getFieldMetaPathMap(rootSchema, services) {
+  const cached = pathMetaCache.get(rootSchema);
+  if (cached !== void 0) return cached;
+  const map = /* @__PURE__ */ new Map();
+  const counters = /* @__PURE__ */ new Map();
+  const lastPathPerSchema = /* @__PURE__ */ new Map();
+  const inProgress = /* @__PURE__ */ new WeakSet();
+  walkForMeta(rootSchema, [], map, counters, lastPathPerSchema, inProgress, services);
+  for (const [schema, lastPath] of lastPathPerSchema) {
+    const list = services.getFieldMetaList(schema);
+    const consumed = counters.get(schema) ?? 0;
+    if (list.length <= consumed) continue;
+    const surplus = list.slice(consumed).reduce((acc, p) => ({ ...acc, ...p }), {});
+    const existing = map.get(lastPath) ?? {};
+    map.set(lastPath, { ...existing, ...surplus });
+  }
+  pathMetaCache.set(rootSchema, map);
+  return map;
+}
+function consumePayload(schema, counters, getFieldMetaList) {
+  const list = getFieldMetaList(schema);
+  if (list.length === 0) return void 0;
+  const idx = counters.get(schema) ?? 0;
+  const payload = list[Math.min(idx, list.length - 1)];
+  counters.set(schema, idx + 1);
+  return payload;
+}
+function walkForMeta(schema, path, map, counters, lastPathPerSchema, inProgress, services) {
+  if (inProgress.has(schema)) return;
+  inProgress.add(schema);
+  try {
+    const { intro, peelAllWrappers, getFieldMetaList } = services;
+    const pathKey = canonicalizePath(path).key;
+    if (!map.has(pathKey)) {
+      const payload = consumePayload(schema, counters, getFieldMetaList);
+      if (payload !== void 0) {
+        map.set(pathKey, payload);
+        lastPathPerSchema.set(schema, pathKey);
+      }
+    }
+    const peeled = peelAllWrappers(schema);
+    if (peeled !== schema && !map.has(pathKey)) {
+      const payload = consumePayload(peeled, counters, getFieldMetaList);
+      if (payload !== void 0) {
+        map.set(pathKey, payload);
+        lastPathPerSchema.set(peeled, pathKey);
+      }
+    }
+    const kind = intro.kindOf(schema);
+    switch (kind) {
+      case "object": {
+        for (const [key, child] of Object.entries(intro.getObjectShape(schema))) {
+          walkForMeta(child, [...path, key], map, counters, lastPathPerSchema, inProgress, services);
+        }
+        return;
+      }
+      case "array": {
+        const inner = intro.getArrayElement(schema);
+        if (inner !== void 0)
+          walkForMeta(inner, [...path, 0], map, counters, lastPathPerSchema, inProgress, services);
+        return;
+      }
+      case "tuple": {
+        const items = intro.getTupleItems(schema);
+        for (let i = 0; i < items.length; i++) {
+          const item = items[i];
+          if (item !== void 0)
+            walkForMeta(item, [...path, i], map, counters, lastPathPerSchema, inProgress, services);
+        }
+        return;
+      }
+      case "set": {
+        const inner = intro.getSetValueType(schema);
+        if (inner !== void 0)
+          walkForMeta(inner, [...path, 0], map, counters, lastPathPerSchema, inProgress, services);
+        return;
+      }
+      case "record": {
+        const inner = intro.getRecordValueType(schema);
+        if (inner !== void 0)
+          walkForMeta(inner, [...path, "*"], map, counters, lastPathPerSchema, inProgress, services);
+        return;
+      }
+      case "union": {
+        for (const opt of intro.getUnionOptions(schema)) {
+          walkForMeta(opt, path, map, counters, lastPathPerSchema, inProgress, services);
+        }
+        return;
+      }
+      case "discriminated-union": {
+        for (const opt of intro.getDiscriminatedOptions(schema)) {
+          walkForMeta(opt, path, map, counters, lastPathPerSchema, inProgress, services);
+        }
+        return;
+      }
+      case "optional":
+      case "nullable":
+      case "default":
+      case "readonly":
+      case "catch": {
+        const inner = intro.unwrapInner(schema);
+        if (inner !== void 0)
+          walkForMeta(inner, path, map, counters, lastPathPerSchema, inProgress, services);
+        return;
+      }
+      case "pipe":
+      case "pipeline": {
+        const inner = intro.unwrapPipeIn(schema);
+        if (inner !== void 0)
+          walkForMeta(inner, path, map, counters, lastPathPerSchema, inProgress, services);
+        return;
+      }
+      case "effects": {
+        const inner = intro.unwrapEffectsSource(schema);
+        if (inner !== void 0)
+          walkForMeta(inner, path, map, counters, lastPathPerSchema, inProgress, services);
+        return;
+      }
+      case "branded": {
+        const inner = intro.unwrapBranded(schema);
+        if (inner !== void 0)
+          walkForMeta(inner, path, map, counters, lastPathPerSchema, inProgress, services);
+        return;
+      }
+      case "lazy": {
+        try {
+          const inner = intro.unwrapLazy(schema);
+          if (inner !== void 0)
+            walkForMeta(inner, path, map, counters, lastPathPerSchema, inProgress, services);
+        } catch {
+        }
+        return;
+      }
+      case "intersection": {
+        const left = intro.getIntersectionLeft(schema);
+        const right = intro.getIntersectionRight(schema);
+        if (left !== void 0)
+          walkForMeta(left, path, map, counters, lastPathPerSchema, inProgress, services);
+        if (right !== void 0)
+          walkForMeta(right, path, map, counters, lastPathPerSchema, inProgress, services);
+        return;
+      }
+      default:
+        return;
+    }
+  } finally {
+    inProgress.delete(schema);
+  }
+}
+
+export { NO_EMBEDDED_DEFAULT as N, getFieldMetaListForSchema as a, getFieldMetaPathMap as b, createAbstractSchema as c, deriveDefaultWalk as d, fieldMetaStore as f, getFieldMetaForSchema as g, mergeDeep as m, peelEmbeddedDefault as p, slimPrimitivesWalk as s, walkPathSegments as w };
+//# sourceMappingURL=attaform.Be8NZG9M.mjs.map