attaform 0.16.2 → 0.16.4

package/dist/shared/{attaform.0Gxd_OOx.d.ts → attaform.CU3JperC.d.ts}

@@ -2,14 +2,22 @@ import { Ref, ObjectDirective, ComputedRef } from 'vue';
 
 /**
  * Schema-attached field metadata — the shared types used by both Zod
- * adapters (`attaform/zod` for v4 and `attaform/zod-v3` for v3) so a
- * consumer's data flow reads the same shape regardless of adapter.
- *
- * The Zod 4 adapter creates a typed `z.registry<FieldMetaPayload>()`
- * and writes through `schema.register(fieldMeta, payload)` (native) or
- * the `withMeta(schema, payload)` helper. The Zod 3 adapter has no
- * native registry — it shims a `WeakMap<ZodTypeAny, FieldMetaPayload>`
- * with the same write API via `withMeta`.
+ * adapters and the unified `attaform/zod` entry so a consumer's data
+ * flow reads the same shape regardless of which path runs at lookup.
+ *
+ * Storage lives in the cross-adapter `field-meta-store` core: a pair
+ * of WeakMaps (single-payload for last-write-wins reads, list-of-
+ * payloads for shared-schema disambiguation). Every entry's
+ * `fieldMeta` re-exports the same registry-shaped object, so
+ * `withMeta`/`fieldMeta.add` writes from one entry surface at lookup
+ * through any other.
+ *
+ * `withMeta(schema, payload)` clones the schema before registering,
+ * so each call gets fresh identity (the WeakMap keys on reference).
+ * The cloning strategy depends on the major: Zod 4 schemas use the
+ * native `.clone()`, Zod 3 schemas reconstruct via constructor +
+ * `_def`. The unified entry's `withMeta` runtime-branches on which
+ * one is in play.
  *
  * Reads are unified through `AbstractSchema.getFieldMetaAtPath(path)`,
  * which returns a fully-resolved `ResolvedFieldMeta` (label /
@@ -90,10 +98,15 @@ type Path = readonly Segment[];
  * ```ts
  * parseDottedPath('user.address.line1')   // ['user', 'address', 'line1']
  * parseDottedPath('items.0.name')         // ['items', 0, 'name']
- * parseDottedPath('')                     // [] (root)
+ * parseDottedPath('')                     // ['']  (the empty-string key)
  * ```
  *
- * Throws `InvalidPathError` for paths with empty segments
+ * The empty-string input `''` is the **literal empty-key path**, not
+ * the root. Use the array form `[]` for root. Form-level errors
+ * (root `.refine()`) live at the empty-string path bucket so
+ * `errors('')` returns them without sweeping every field error too.
+ *
+ * Throws `InvalidPathError` for paths with empty INTERNAL segments
  * (`'a..b'`, leading or trailing dots). For keys containing literal
  * dots, pass an array form (`['user.name']`) instead.
  */
@@ -457,9 +470,10 @@ type FormKey = string;
 /**
  * One validation failure. `path` points at the offending field as a
  * structured array — `['user', 'address', 0, 'line1']` for a nested
- * field, `[]` for a form-level error. `formKey` identifies which
- * form produced the error so a single error list can be routed to
- * multiple forms.
+ * field, `['']` (the empty-string path) for a form-level error
+ * (root `.refine()` messages, `setFormErrors()` entries, server-
+ * emitted form banners). `formKey` identifies which form produced
+ * the error so a single error list can be routed to multiple forms.
  *
  * Returned by `validate()` / `validateAsync()` / `handleSubmit`'s
  * `onError` callback, and by `parseApiErrors` for server responses.
@@ -467,7 +481,12 @@ type FormKey = string;
 type ValidationError = {
     /** Human-readable message describing the failure. */
     message: string;
-    /** Structured path of the offending field. Empty array means a form-level error. */
+    /**
+     * Structured path of the offending field. The empty-string path
+     * `['']` is the form-level bucket — the dedicated home for errors
+     * that don't belong to any specific field, distinct from the
+     * whole-form subtree address `[]`.
+     */
     path: (string | number)[];
     /** Identifies which form produced this error. */
     formKey: FormKey;
@@ -844,8 +863,8 @@ type AbstractSchema<Form, GetValueFormType> = {
      * Return the resolved field metadata for the schema node at `path`
      * — label, description, placeholder, plus the full registered
      * payload as `meta` for consumer-augmented keys. Reads through the
-     * adapter's metadata mechanism (Zod 4: `z.registry()`; Zod 3:
-     * a WeakMap shim) and applies these one-way fallbacks:
+     * shared cross-adapter field-meta store and applies these one-way
+     * fallbacks:
      *
      *   - `label`:       registry payload → `humanize(lastSegment)`
      *   - `description`: registry payload → `schema.description`
@@ -1386,6 +1405,17 @@ type UseFormConfiguration<Form extends GenericForm, GetValueFormType, Schema ext
      * coerced.
      */
     coerce?: boolean | CoercionRegistry;
+    /**
+     * Per-form override of the `shouldShowErrors` heuristic that drives
+     * `field.showErrors` and `form.meta.showErrors`. Falls back to
+     * `AttaformDefaults.shouldShowErrors`, then to the library default
+     * (`defaultShouldShowErrors`). See `AttaformDefaults.shouldShowErrors`
+     * for the resolution rules and predicate signature.
+     *
+     * Boolean shorthand: `true` → always show *when errors exist*;
+     * `false` → never show.
+     */
+    shouldShowErrors?: ShouldShowErrorsConfig;
 };
 /**
  * App-level defaults applied to every `useForm` call. Set these once
@@ -1451,6 +1481,34 @@ type AttaformDefaults = {
      * authoritative writes whose strict typing is on the caller.
      */
     coerce?: boolean | CoercionRegistry;
+    /**
+     * Default for `useForm({ shouldShowErrors })`. Centralised heuristic
+     * that drives `field.showErrors` (and `form.meta.showErrors`) — a
+     * boolean that gates whether a path's errors are *ready* to render.
+     *
+     * Resolution order (per-form wins):
+     *
+     *   useForm({ shouldShowErrors })  >  AttaformDefaults  >  library default
+     *
+     * The library default reads "show after the first submit attempt OR
+     * after the field has been interacted with AND changed":
+     *
+     * ```ts
+     * (field, formMeta) =>
+     *   formMeta.submitCount > 0 || (field.touched === true && field.dirty)
+     * ```
+     *
+     * Compose with the library default via the public
+     * `defaultShouldShowErrors` export. Boolean shorthand is supported:
+     * `true` → always show *when errors exist*; `false` → never show. The
+     * predicate is invoked only when `errors.length > 0`, so authors
+     * don't re-check inside.
+     *
+     * The predicate's args are `Omit`'d of `showErrors` / `firstError`
+     * to prevent recursive predicates — those are derived FROM this
+     * predicate, so reading them inside would be a self-reference.
+     */
+    shouldShowErrors?: ShouldShowErrorsConfig;
 };
 /**
  * Callback invoked by `handleSubmit` after the form parses successfully.
@@ -1465,6 +1523,46 @@ type OnSubmit<Form extends GenericForm> = (form: Form) => void | Promise<void>;
  * automatic `onInvalidSubmit` UI nudge).
  */
 type OnError = (error: ValidationError[]) => void | Promise<void>;
+/**
+ * Predicate that drives `field.showErrors` (and `form.meta.showErrors`).
+ * Receives the field's reactive state plus the form's reactive meta;
+ * returns `true` to render the field's errors, `false` to keep them
+ * hidden. The framework gates the call on `errors.length > 0`, so
+ * authors don't re-check error presence inside.
+ *
+ * Both arguments are `Omit`'d of `showErrors` / `firstError` — those
+ * are derived FROM this predicate, so reading them inside would be a
+ * self-reference. The omit is enforced at the type level AND at
+ * runtime: the keys literally are not present on the objects passed
+ * in, so `as` casting in TS or vanilla-JS bypass cannot create a
+ * cycle.
+ *
+ * The library default — `defaultShouldShowErrors` — is publicly
+ * exported so a layered predicate can compose with it:
+ *
+ * ```ts
+ * import { defaultShouldShowErrors } from 'attaform'
+ *
+ * useForm({
+ *   schema,
+ *   shouldShowErrors: (field, formMeta) =>
+ *     field.path[0] === 'urgent' || defaultShouldShowErrors(field, formMeta),
+ * })
+ * ```
+ */
+type ShouldShowErrors = (field: Omit<FieldState, 'showErrors' | 'firstError'>, formMeta: Omit<FormMeta, 'showErrors' | 'firstError'>) => boolean;
+/**
+ * Configuration shape for `shouldShowErrors`. A predicate function or
+ * a boolean shorthand:
+ *
+ * - `true` — always show errors (when any exist).
+ * - `false` — never show errors.
+ * - function — custom predicate, see `ShouldShowErrors`.
+ *
+ * Resolved through three tiers (per-form > plugin defaults > library
+ * default).
+ */
+type ShouldShowErrorsConfig = ShouldShowErrors | boolean;
 /**
  * Submit handler returned by `handleSubmit(onSubmit, onError)`. Bind
  * it to a `<form>`:
@@ -2067,13 +2165,58 @@ type FieldState<Value = unknown> = {
      * green-checkmark / `aria-invalid` UX.
      */
     readonly valid: boolean;
+    /**
+     * Centralised "should I render this field's errors right now?"
+     * gate. Wraps `errors.length > 0 && shouldShowErrors(field, formMeta)`
+     * so templates avoid re-spelling the heuristic at every error site:
+     *
+     * ```vue
+     * <span v-if="form.fields.email.showErrors">
+     *   {{ form.fields.email.firstError?.message }}
+     * </span>
+     * ```
+     *
+     * The heuristic itself comes from `useForm({ shouldShowErrors })` →
+     * `createAttaform({ defaults: { shouldShowErrors } })` → library
+     * default (`defaultShouldShowErrors` — show after first submit OR
+     * after touched-and-dirty). Override per form, app-wide, or
+     * compose with `defaultShouldShowErrors` for a layered predicate.
+     *
+     * Falls back to `false` whenever there are no errors — the gate
+     * skips the predicate entirely in that case.
+     *
+     * Available on container paths too: `form.fields.users[0].showErrors`
+     * aggregates over the row's descendants (any descendant with a
+     * qualifying error flips the container on).
+     */
+    readonly showErrors: boolean;
+    /**
+     * The first `ValidationError` at this path in the deterministic
+     * schema-declaration order — equivalent to `errors[0]`, exposed as
+     * a sugar accessor for the common case of "show the highest-priority
+     * error message and ignore the rest":
+     *
+     * ```vue
+     * <span v-if="form.fields.email.showErrors">
+     *   {{ form.fields.email.firstError?.message }}
+     * </span>
+     * ```
+     *
+     * `undefined` when no errors exist. Independent of `showErrors` —
+     * the data primitive is always available; the heuristic only
+     * decides when to render it.
+     *
+     * On container paths, the first error in the aggregated subtree
+     * (descendants sorted by `pathOrdinal`).
+     */
+    readonly firstError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
     readonly blank: boolean;
     /**
      * Presentational label for this field. Resolves through the
-     * adapter's metadata mechanism — Zod 4's `z.registry()` (typed
-     * payload via `schema.register(fieldMeta, {...})` or the
-     * `withMeta()` helper); Zod 3's WeakMap shim — and falls back to
+     * shared cross-adapter field-meta store — written via
+     * `schema.register(fieldMeta, {...})` (Zod 4 native chain) or the
+     * `withMeta()` helper (works on both majors) — and falls back to
      * a humanized form of the path's last segment when nothing has
      * been registered. Always a string.
      *
@@ -2782,12 +2925,15 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * if (result.ok) form.setFormErrors(result.errors)
      * ```
      *
-     * Form-level errors surface in `form.meta.errors` (alongside field
-     * errors) but are intentionally excluded from the path-keyed
-     * `form.errors` proxy (no key represents `[]` in a nested object) —
-     * read them via `meta.errors.filter(e => e.path.length === 0)` or
-     * `form.errors([])` (the call-form aggregates everywhere, including
-     * form-level errors at `path: []`).
+     * Form-level errors land at the empty-string path bucket
+     * (`path: ['']`). They surface in `form.meta.errors` (alongside
+     * field errors), in `form.errors()` / `form.errors([])` (whole-form
+     * subtree aggregates), and — uniquely — in `form.errors('')`,
+     * which returns ONLY the form-level bucket. They're excluded from
+     * the path-keyed `form.errors` drill proxy because no nested-object
+     * key represents the empty-string path. Read them via
+     * `meta.errors.filter(e => e.path.length === 1 && e.path[0] === '')`
+     * if you need a programmatic split.
      */
     setFormErrors: (errors: ReadonlyArray<Partial<ValidationError> & {
         message: string;
@@ -2897,6 +3043,26 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
      * `options` is forwarded to `Element.scrollIntoView` unchanged.
      */
     scrollToFirstError: (options?: ScrollIntoViewOptions) => boolean;
+    /**
+     * Programmatically mark fields as touched — the sticky flag the
+     * standard "show errors after interaction" pattern reads. Closes
+     * the gap when fields are populated without a DOM gesture (post-
+     * import, paste, autofill, server-seeded values you want to
+     * validate immediately).
+     *
+     * ```ts
+     * form.touch('email')                 // one leaf
+     * form.touch('profile')               // every leaf under profile
+     * form.touch(['profile', 'name'])     // segment-array form
+     * form.touch()                        // every leaf in the form
+     * ```
+     *
+     * Pure flag write — does not mutate value, focused, blurred, or
+     * trigger validation. Idempotent: re-calling on an already-touched
+     * field is a no-op. Touched is sticky-true; pair with
+     * `form.reset()` / `form.resetField()` to clear.
+     */
+    touch: (path?: FlatPath<Form> | (string | number)[]) => void;
     /**
      * Append `value` to the array at `path`.
      *
@@ -2948,5 +3114,5 @@ type UseFormReturnType<Form extends GenericForm, GetValueFormType extends Generi
     blankPaths: ComputedRef<ReadonlySet<string>>;
 };
 
-export { ROOT_PATH as Z, ROOT_PATH_KEY as _, canonicalizePath as ak, isPathPrefix as al, isUnset as am, parseDottedPath as an, unset as ao };
-export type { ReactiveValidationStatus as $, AttaformDefaults as A, OnInvalidSubmitPolicy as B, CoercionRegistry as C, DeepPartial as D, OnSubmit as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, Path as P, PathKey as Q, RegisterValue as R, SlimPrimitiveKind as S, PendingValidationStatus as T, UseFormConfiguration as U, ValidationError as V, PersistConfig as W, PersistConfigOptions as X, PersistIncludeMode as Y, CoercionEntry as a, RegisterDirective as a0, RegisterFlatPath as a1, RegisterOptions as a2, RegisterSelectModifier as a3, RegisterTextModifier as a4, RegisterTransform as a5, Segment as a6, SetValueCallback as a7, SetValuePayload as a8, SettledValidationStatus as a9, SlimRuntimeOf as aa, SubmitHandler as ab, Unset as ac, ValidateOn as ad, ValidateOnConfig as ae, ValidationResponse as af, ValidationResponseWithoutValue as ag, ValueOfUnion as ah, WriteMeta as ai, WriteShape as aj, AbstractSchema as b, DefaultValuesShape as c, UseFormReturnType as d, RegisterModelDynamicCustomDirective as e, ApiErrorEnvelope as f, ApiErrorDetails as g, ApiErrorEntry as h, ArrayItem as i, ArrayPath as j, CoercionResult as k, CustomDirectiveRegisterAssignerFn as l, DefaultValuesResponse as m, FieldMetaPayload as n, FieldState as o, FieldStateMap as p, FieldStateMapEntry as q, FlatPath as r, FormErrorRecord as s, FormErrorsSurface as t, FormMeta as u, FormStorage as v, FormStorageKind as w, HistoryConfig as x, IsUnion as y, NestedType as z };
+export { ROOT_PATH_KEY as $, ROOT_PATH as _, canonicalizePath as am, isPathPrefix as an, isUnset as ao, parseDottedPath as ap, unset as aq };
+export type { AttaformDefaults as A, NestedType as B, CoercionRegistry as C, DeepPartial as D, OnInvalidSubmitPolicy as E, FormKey as F, GenericForm as G, HandleSubmit as H, IsTuple as I, JoinSegments as J, KeyofUnion as K, LiftedValueShape as L, MetaTrackerValue as M, NestedReadType as N, OnError as O, OnSubmit as P, Path as Q, RegisterValue as R, SlimPrimitiveKind as S, PathKey as T, UseFormConfiguration as U, ValidationError as V, PendingValidationStatus as W, PersistConfig as X, PersistConfigOptions as Y, PersistIncludeMode as Z, CoercionEntry as a, ReactiveValidationStatus as a0, RegisterDirective as a1, RegisterFlatPath as a2, RegisterOptions as a3, RegisterSelectModifier as a4, RegisterTextModifier as a5, RegisterTransform as a6, Segment as a7, SetValueCallback as a8, SetValuePayload as a9, SettledValidationStatus as aa, ShouldShowErrorsConfig as ab, SlimRuntimeOf as ac, SubmitHandler as ad, Unset as ae, ValidateOn as af, ValidateOnConfig as ag, ValidationResponse as ah, ValidationResponseWithoutValue as ai, ValueOfUnion as aj, WriteMeta as ak, WriteShape as al, AbstractSchema as b, DefaultValuesShape as c, UseFormReturnType as d, RegisterModelDynamicCustomDirective as e, ShouldShowErrors as f, ApiErrorEnvelope as g, ApiErrorDetails as h, ApiErrorEntry as i, ArrayItem as j, ArrayPath as k, CoercionResult as l, CustomDirectiveRegisterAssignerFn as m, DefaultValuesResponse as n, FieldMetaPayload as o, FieldState as p, FieldStateMap as q, FieldStateMapEntry as r, FlatPath as s, FormErrorRecord as t, FormErrorsSurface as u, FormMeta as v, FormStorage as w, FormStorageKind as x, HistoryConfig as y, IsUnion as z };

package/dist/shared/{attaform.Dq5BabH1.d.cts → attaform.CXMOheyZ.d.mts}

@@ -1,4 +1,4 @@
-import { G as GenericForm, F as FormKey, d as UseFormReturnType, R as RegisterValue } from './attaform.0Gxd_OOx.cjs';
+import { G as GenericForm, F as FormKey, d as UseFormReturnType, R as RegisterValue } from './attaform.CU3JperC.mjs';
 import { Ref } from 'vue';
 
 /**

package/dist/shared/attaform.D13GMFgK.mjs

@@ -0,0 +1,32 @@
+const store = /* @__PURE__ */ new WeakMap();
+const lists = /* @__PURE__ */ new WeakMap();
+const registry = {
+  add(schema, payload) {
+    store.set(schema, payload);
+    const list = lists.get(schema) ?? [];
+    list.push(payload);
+    lists.set(schema, list);
+    return registry;
+  },
+  get(schema) {
+    return store.get(schema);
+  },
+  has(schema) {
+    return store.has(schema);
+  },
+  remove(schema) {
+    store.delete(schema);
+    lists.delete(schema);
+    return registry;
+  }
+};
+const fieldMetaStore = registry;
+function getFieldMetaForSchema(schema) {
+  return store.get(schema);
+}
+function getFieldMetaListForSchema(schema) {
+  return lists.get(schema) ?? [];
+}
+
+export { getFieldMetaListForSchema as a, fieldMetaStore as f, getFieldMetaForSchema as g };
+//# sourceMappingURL=attaform.D13GMFgK.mjs.map

package/dist/shared/attaform.D13GMFgK.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"attaform.D13GMFgK.mjs","sources":["../../src/runtime/core/field-meta-store.ts"],"sourcesContent":["/**\n * Shared field-metadata storage. Both Zod adapters (v3 and v4) and the\n * unified `attaform/zod` entry read from the same `WeakMap`s so a\n * payload written via any entry's `withMeta` / `fieldMeta.add` is\n * visible to whichever adapter actually runs at lookup time.\n *\n * No `zod` runtime import — pure JavaScript primitives. The previous\n * v4 adapter built `fieldMeta` via `z.registry<FieldMetaPayload>()`,\n * which left a `z.registry` namespace reference reachable from\n * `attaform/zod`'s module graph; bundlers analysing a `zod@^3` consumer\n * resolved that against zod 3's exports map (no `registry` export) and\n * emitted an `IMPORT_IS_UNDEFINED` warning. Lifting storage here drops\n * that reference entirely so the unified entry behaves cleanly on any\n * Zod major.\n *\n * The native v4 chain `schema.register(fieldMeta, payload)` still\n * works against this shim — Zod 4's `.register()` only calls\n * `registry.add(this, payload)` and returns the schema; structural\n * matching is enough.\n *\n * Two parallel maps:\n * - `store` — last-write-wins single payload per schema reference.\n *   Backs `fieldMeta.get(schema)` and the adapter's\n *   `getFieldMetaAtPath` single-payload fallback.\n * - `lists` — every registration in order, per schema reference.\n *   Backs the v4 adapter's path-walker disambiguation when the same\n *   schema instance is bound at multiple form paths.\n */\n\nimport type { FieldMetaPayload } from './field-meta'\n\n/**\n * Minimal registry shape the shared store satisfies — `.add` / `.get`\n * / `.has` / `.remove`. Cast to `z.$ZodRegistry<FieldMetaPayload>` at\n * the v4 adapter's re-export so the native `schema.register(fieldMeta,\n * payload)` chain type-checks; the v3 adapter exports it as its own\n * registry-shaped surface.\n */\nexport type FieldMetaStore = {\n  add(schema: object, payload: FieldMetaPayload): FieldMetaStore\n  get(schema: object): FieldMetaPayload | undefined\n  has(schema: object): boolean\n  remove(schema: object): FieldMetaStore\n}\n\nconst store = new WeakMap<object, FieldMetaPayload>()\nconst lists = new WeakMap<object, FieldMetaPayload[]>()\n\nconst registry: FieldMetaStore = {\n  add(schema, payload) {\n    store.set(schema, payload)\n    const list = lists.get(schema) ?? []\n    list.push(payload)\n    lists.set(schema, list)\n    return registry\n  },\n  get(schema) {\n    return store.get(schema)\n  },\n  has(schema) {\n    return store.has(schema)\n  },\n  remove(schema) {\n    store.delete(schema)\n    lists.delete(schema)\n    return registry\n  },\n}\n\n/**\n * The shared registry every Attaform-aware Zod schema can register\n * field metadata against, regardless of Zod major. One module-scoped\n * instance — every adapter entry re-exports this same object so\n * writes from one entry are visible at lookup through any other.\n */\nexport const fieldMetaStore: FieldMetaStore = registry\n\n/**\n * Last-write-wins payload lookup for a schema reference. Returns\n * `undefined` if nothing has been registered.\n */\nexport function getFieldMetaForSchema(schema: object): FieldMetaPayload | undefined {\n  return store.get(schema)\n}\n\n/**\n * Read every payload registered against `schema` in registration\n * order. Empty list when nothing has been registered. Used by the v4\n * adapter's path-resolver to disambiguate per occurrence when one\n * schema instance is bound at multiple form paths.\n */\nexport function getFieldMetaListForSchema(schema: object): readonly FieldMetaPayload[] {\n  return lists.get(schema) ?? []\n}\n"],"names":[],"mappings":"AA6CA,MAAM,KAAA,uBAAY,OAAA,EAAkC;AACpD,MAAM,KAAA,uBAAY,OAAA,EAAoC;AAEtD,MAAM,QAAA,GAA2B;AAAA,EAC/B,GAAA,CAAI,QAAQ,OAAA,EAAS;AACnB,IAAA,KAAA,CAAM,GAAA,CAAI,QAAQ,OAAO,CAAA;AACzB,IAAA,MAAM,IAAA,GAAO,KAAA,CAAM,GAAA,CAAI,MAAM,KAAK,EAAC;AACnC,IAAA,IAAA,CAAK,KAAK,OAAO,CAAA;AACjB,IAAA,KAAA,CAAM,GAAA,CAAI,QAAQ,IAAI,CAAA;AACtB,IAAA,OAAO,QAAA;AAAA,EACT,CAAA;AAAA,EACA,IAAI,MAAA,EAAQ;AACV,IAAA,OAAO,KAAA,CAAM,IAAI,MAAM,CAAA;AAAA,EACzB,CAAA;AAAA,EACA,IAAI,MAAA,EAAQ;AACV,IAAA,OAAO,KAAA,CAAM,IAAI,MAAM,CAAA;AAAA,EACzB,CAAA;AAAA,EACA,OAAO,MAAA,EAAQ;AACb,IAAA,KAAA,CAAM,OAAO,MAAM,CAAA;AACnB,IAAA,KAAA,CAAM,OAAO,MAAM,CAAA;AACnB,IAAA,OAAO,QAAA;AAAA,EACT;AACF,CAAA;AAQO,MAAM,cAAA,GAAiC;AAMvC,SAAS,sBAAsB,MAAA,EAA8C;AAClF,EAAA,OAAO,KAAA,CAAM,IAAI,MAAM,CAAA;AACzB;AAQO,SAAS,0BAA0B,MAAA,EAA6C;AACrF,EAAA,OAAO,KAAA,CAAM,GAAA,CAAI,MAAM,CAAA,IAAK,EAAC;AAC/B;;;;"}

package/dist/shared/{attaform.jrxE_xZw.mjs → attaform.DZRj9s0s.mjs}

@@ -14,7 +14,7 @@ function normalizeSegment(raw) {
   return raw;
 }
 function parseDottedPath(path) {
-  if (path.length === 0) return [];
+  if (path.length === 0) return [""];
   const rawSegments = path.split(".");
   const segments = [];
   for (const raw of rawSegments) {
@@ -78,6 +78,8 @@ function canonicalizePath(input) {
 }
 const ROOT_PATH = Object.freeze([]);
 const ROOT_PATH_KEY = "[]";
+const FORM_ERRORS_PATH = Object.freeze([""]);
+const FORM_ERRORS_PATH_KEY = '[""]';
 function isPathPrefix(prefix, path) {
   if (path.length < prefix.length) return false;
   for (let i = 0; i < prefix.length; i++) {
@@ -86,5 +88,5 @@ function isPathPrefix(prefix, path) {
   return true;
 }
 
-export { ROOT_PATH as R, ROOT_PATH_KEY as a, canonicalizePath as c, isPathPrefix as i, parseDottedPath as p, segmentsForPathKey as s };
-//# sourceMappingURL=attaform.jrxE_xZw.mjs.map
+export { FORM_ERRORS_PATH_KEY as F, ROOT_PATH as R, ROOT_PATH_KEY as a, FORM_ERRORS_PATH as b, canonicalizePath as c, isPathPrefix as i, parseDottedPath as p, segmentsForPathKey as s };
+//# sourceMappingURL=attaform.DZRj9s0s.mjs.map

package/dist/shared/attaform.DZRj9s0s.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"attaform.DZRj9s0s.mjs","sources":["../../src/runtime/core/paths.ts"],"sourcesContent":["import { InvalidPathError } from './errors'\n\n/**\n * Path primitives for advanced integrations. The form library accepts\n * paths in dotted-string form (`'user.email'`) at every public API.\n * These primitives are exposed for adapter authors who need to\n * canonicalise user-provided paths.\n */\n\ndeclare const pathKeyBrand: unique symbol\n\n/**\n * Branded string identifier for a canonicalised path. Useful as a\n * `Map` key — two paths that resolve to the same canonical form\n * produce the same `PathKey`. Treat as opaque; don't try to parse.\n */\nexport type PathKey = string & { readonly [pathKeyBrand]: 'PathKey' }\n\n/** A single path segment — a property name or array index. */\nexport type Segment = string | number\n/** A structured path as a read-only sequence of segments. */\nexport type Path = readonly Segment[]\n\n/** Tests an integer-like string without leading zeros. `'0'` | `'1'` | `'42'` pass; `'01'`, `'-1'`, `'1.5'` do not. */\nconst INTEGER_SEGMENT = /^(?:0|[1-9]\\d*)$/\n\nfunction normalizeSegment(raw: Segment): Segment {\n  if (typeof raw === 'number') {\n    if (!Number.isInteger(raw) || raw < 0) {\n      throw new InvalidPathError(\n        `Path segments must be non-negative integers when numeric; got ${String(raw)}`\n      )\n    }\n    return raw\n  }\n  // Integer-looking strings normalise to numbers so that dotted-form\n  // `'items.0.name'` and array-form `['items', 0, 'name']` yield the same\n  // canonical path (and PathKey).\n  if (INTEGER_SEGMENT.test(raw)) return Number(raw)\n  return raw\n}\n\n/**\n * Parse a dotted-string path into structured segments.\n *\n * ```ts\n * parseDottedPath('user.address.line1')   // ['user', 'address', 'line1']\n * parseDottedPath('items.0.name')         // ['items', 0, 'name']\n * parseDottedPath('')                     // ['']  (the empty-string key)\n * ```\n *\n * The empty-string input `''` is the **literal empty-key path**, not\n * the root. Use the array form `[]` for root. Form-level errors\n * (root `.refine()`) live at the empty-string path bucket so\n * `errors('')` returns them without sweeping every field error too.\n *\n * Throws `InvalidPathError` for paths with empty INTERNAL segments\n * (`'a..b'`, leading or trailing dots). For keys containing literal\n * dots, pass an array form (`['user.name']`) instead.\n */\nexport function parseDottedPath(path: string): Segment[] {\n  if (path.length === 0) return ['']\n  const rawSegments = path.split('.')\n  const segments: Segment[] = []\n  for (const raw of rawSegments) {\n    if (raw.length === 0) {\n      throw new InvalidPathError(\n        `Path '${path}' has an empty segment; use the array form for empty keys.`\n      )\n    }\n    segments.push(normalizeSegment(raw))\n  }\n  return segments\n}\n\n/**\n * Bounded FIFO cache for canonicalizePath on dotted-string inputs.\n * Real forms re-canonicalise a small working-set of paths thousands\n * of times per session (every keystroke on a registered field, every\n * validate, every getValue), so a small cache amortises the parse +\n * stringify cost across repeat calls without pinning memory as apps\n * accumulate fields.\n *\n * Eviction is FIFO (oldest insertion wins), not LRU. The 128-entry\n * cap is generous relative to a typical form's working set\n * (playground: ~15 paths; the entire test suite: 45 unique register\n * patterns) — overflow doesn't fire in practice. On the rare overflow\n * a re-canonicalisation hit is still O(segments) and lands back in\n * the cache. Bumping recency on every hit (`delete` + `set`) costs\n * two Map operations per cache hit, in the hottest read-side loop in\n * the library, with no observable benefit at this cap — so we don't.\n *\n * Array inputs are not cached: callers in the runtime (unset-walker's\n * recursive `[...segments, i]`, devtools' inspector `payload.path.slice(...)`)\n * overwhelmingly pass freshly-allocated arrays per call, so a\n * WeakMap-keyed cache would miss on every call and pay the\n * lookup-then-set cost without benefit.\n */\nconst CANONICAL_STRING_CACHE_MAX = 128\nconst canonicalStringCache = new Map<string, { segments: readonly Segment[]; key: PathKey }>()\n\n/**\n * Inverse cache: PathKey → segments. Populated by `canonicalizePath`\n * (string and array branches) so any consumer holding a PathKey\n * produced through the canonical pipeline can recover its structured\n * segments without `JSON.parse`. Callers reach this through\n * `segmentsForPathKey` below.\n *\n * The store-side data structures keyed by PathKey (form-store error\n * maps, blank-paths set, variant-memory map, persistence opt-in\n * registry) all source their keys from `canonicalizePath`, so reads\n * are dominantly cache hits. Cold paths (PathKeys round-tripped from\n * a persisted payload that came from disk) still hit a single\n * `JSON.parse` on first lookup, then warm the cache.\n *\n * Bounded FIFO at 4096 entries — generous relative to a typical form's\n * working set (~tens to ~hundreds of paths per form) but small enough\n * that long-running multi-form apps don't accumulate unbounded\n * references. Eviction only fires on net-new entries; idempotent\n * overwrites (same key, same segments) don't count toward the cap.\n */\nconst PATHKEY_TO_SEGMENTS_MAX = 4096\nconst pathKeyToSegments = new Map<PathKey, readonly Segment[]>()\n\nfunction rememberSegmentsForPathKey(key: PathKey, segments: readonly Segment[]): void {\n  if (!pathKeyToSegments.has(key) && pathKeyToSegments.size >= PATHKEY_TO_SEGMENTS_MAX) {\n    const oldest = pathKeyToSegments.keys().next().value\n    if (oldest !== undefined) pathKeyToSegments.delete(oldest)\n  }\n  pathKeyToSegments.set(key, segments)\n}\n\n/**\n * Recover the structured `Segment[]` for a `PathKey` produced by\n * `canonicalizePath`. O(1) on the hot path (cache hit); cold keys\n * fall back to `JSON.parse(key)` plus segment normalization, then\n * warm the cache so subsequent lookups hit.\n *\n * Returns `null` for malformed PathKeys (non-JSON, non-array, or\n * containing values that aren't strings/numbers). Keys produced by\n * `canonicalizePath` never trip this — corrupt persistence payloads\n * (or test fixtures crafting raw strings) are the only realistic\n * sources.\n */\nexport function segmentsForPathKey(key: PathKey): readonly Segment[] | null {\n  const cached = pathKeyToSegments.get(key)\n  if (cached !== undefined) return cached\n  let parsed: unknown\n  try {\n    parsed = JSON.parse(key)\n  } catch {\n    return null\n  }\n  if (!Array.isArray(parsed)) return null\n  const segments: Segment[] = []\n  for (const raw of parsed) {\n    if (typeof raw !== 'string' && typeof raw !== 'number') return null\n    segments.push(normalizeSegment(raw))\n  }\n  rememberSegmentsForPathKey(key, segments)\n  return segments\n}\n\n/**\n * Canonicalise a path into structured segments plus a stable string\n * key. Accepts either dotted-string or array form; integer-looking\n * segments normalise to numbers.\n *\n * ```ts\n * canonicalizePath('items.0.name')\n * // { segments: ['items', 0, 'name'], key: '[\"items\",0,\"name\"]' as PathKey }\n *\n * canonicalizePath(['items', 0, 'name'])\n * // → same result\n * ```\n *\n * The returned `key` is suitable as a `Map`/`Set` key — equal paths\n * produce equal keys regardless of input form.\n */\nexport function canonicalizePath(input: string | Path): {\n  segments: readonly Segment[]\n  key: PathKey\n} {\n  if (typeof input === 'string') {\n    const cached = canonicalStringCache.get(input)\n    if (cached !== undefined) return cached\n    // `parseDottedPath` already normalises each segment; the previous\n    // `.map(normalizeSegment)` second pass was a no-op. We drop it here.\n    const segments: readonly Segment[] = parseDottedPath(input)\n    const key = JSON.stringify(segments) as PathKey\n    const entry = { segments, key }\n    if (canonicalStringCache.size >= CANONICAL_STRING_CACHE_MAX) {\n      const oldest = canonicalStringCache.keys().next().value\n      if (oldest !== undefined) canonicalStringCache.delete(oldest)\n    }\n    canonicalStringCache.set(input, entry)\n    rememberSegmentsForPathKey(key, segments)\n    return entry\n  }\n  const segments = Array.from(input).map(normalizeSegment)\n  const key = JSON.stringify(segments) as PathKey\n  rememberSegmentsForPathKey(key, segments)\n  return { segments, key }\n}\n\n/**\n * The root path — an empty segment tuple. Pass to APIs that accept\n * a `Path` to address the form value as a whole.\n */\nexport const ROOT_PATH: Path = Object.freeze([])\n/** Stable string key for the root path. */\nexport const ROOT_PATH_KEY = '[]' as PathKey\n\n/**\n * The form-level path — a one-segment path with the empty-string\n * key. Conventionally home for errors that don't belong to any\n * specific field: root `.refine()` messages, server-emitted form\n * errors, capacity / availability / cross-field-summary banners.\n *\n * Distinct from `ROOT_PATH` (`[]`): the root is the whole-form\n * subtree address (e.g. `errors([])` returns every error). The\n * form-level path is a sibling-of-no-field path that aggregation\n * walks DON'T sweep into per-field reads — `errors('field')`\n * returns only the field's errors, never the form-level bucket,\n * and `errors('')` returns only the form-level bucket, never the\n * field errors.\n */\nexport const FORM_ERRORS_PATH: Path = Object.freeze([''])\n/** Stable string key for the form-level errors path. */\nexport const FORM_ERRORS_PATH_KEY = '[\"\"]' as PathKey\n\n/**\n * `true` when `path` starts with every segment of `prefix` (in order).\n * The empty `prefix` matches every path — ROOT prefix is universal.\n *\n * Walks segments rather than `PathKey` strings because the data this\n * helper operates on (e.g. `meta.errors[].path`) carries segment\n * arrays directly.\n *\n * ```ts\n * isPathPrefix(['cargo'], ['cargo', 'items', 0, 'sku'])  // true\n * isPathPrefix(['cargo', 'items'], ['cargo'])             // false (path shorter)\n * isPathPrefix([], ['anything'])                          // true (root prefix)\n * ```\n */\nexport function isPathPrefix(prefix: readonly Segment[], path: readonly Segment[]): boolean {\n  if (path.length < prefix.length) return false\n  for (let i = 0; i < prefix.length; i++) {\n    if (path[i] !== prefix[i]) return false\n  }\n  return true\n}\n"],"names":["segments","key"],"mappings":"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"}

package/dist/shared/{attaform.Bp1c-uGF.cjs → attaform.Dd_pWnmn.cjs}

@@ -2,32 +2,21 @@
 
 const lodashEs = require('lodash-es');
 const zod = require('zod');
-const useFormContext = require('./attaform.C9Ph2SMx.cjs');
-const paths = require('./attaform.c_NzdRyc.cjs');
+const useFormContext = require('./attaform.fegmBJaq.cjs');
+const paths = require('./attaform.CIwZtbGV.cjs');
+const fieldMetaStore = require('./attaform.C8CyvYa_.cjs');
 const plugin = require('./attaform.rIRYSUI1.cjs');
 
-const store = /* @__PURE__ */ new WeakMap();
-const fieldMeta = {
-  add(schema, payload) {
-    store.set(schema, payload);
-    return fieldMeta;
-  },
-  get(schema) {
-    return store.get(schema);
-  },
-  has(schema) {
-    return store.has(schema);
-  }
-};
+const fieldMeta = fieldMetaStore.fieldMetaStore;
 function withMeta(schema, payload) {
-  const existing = store.get(schema) ?? {};
+  const existing = fieldMetaStore.getFieldMetaForSchema(schema) ?? {};
   const Ctor = schema.constructor;
   const cloned = new Ctor(schema._def);
-  store.set(cloned, { ...existing, ...payload });
+  fieldMetaStore.fieldMetaStore.add(cloned, { ...existing, ...payload });
   return cloned;
 }
 function getFieldMeta(schema) {
-  return store.get(schema);
+  return fieldMetaStore.getFieldMetaForSchema(schema);
 }
 
 class UnsupportedSchemaError extends plugin.AttaformError {
@@ -798,16 +787,7 @@ function zodAdapter(zodSchema) {
           return aggregatedFailure(accumulatedErrors);
         }
         function nestedSchemasAtPath(p) {
-          const [strippedSchema] = stripRootSchema(_zodSchema, {
-            stripDefaultValues: true,
-            stripNullable: true,
-            stripOptional: true
-          });
-          const slimSchema = getSlimSchema({
-            schema: strippedSchema,
-            stripConfig: { stripDefaultValues: true }
-          });
-          return getNestedZodSchemasAtPath(slimSchema, p);
+          return getNestedZodSchemasAtPath(_zodSchema, p);
         }
         function pathNotFound(p) {
           return {
@@ -855,6 +835,11 @@ function zodIssuesToValidationErrors(issues, formKey) {
       // can smuggle a Symbol through — the public surface promised
       // strings/numbers, so coerce defensively to keep the contract.
       // Mirrors v4's behaviour at the same site.
+      //
+      // Adapter-side paths stay schema-relative — the validation
+      // pipeline in `create-form-store.ts` prepends the parent path
+      // to absolutise, then routes form-level (absolute path length 0)
+      // entries to the empty-string bucket at storage time.
       path: coercePathSegments(issue.path),
       formKey,
       code
@@ -890,6 +875,9 @@ function getNestedZodSchemasAtPath(zodSchema, segments) {
   let currentSchema = zodSchema;
   for (let index = 0; index < segments.length; index++) {
     const key = String(segments[index] ?? "");
+    if (currentSchema !== void 0) {
+      currentSchema = peelV3Wrappers(currentSchema);
+    }
     if (isZodSchemaType(currentSchema, "ZodObject")) {
       const shape = currentSchema._def.shape();
       currentSchema = Object.hasOwn(shape, key) ? shape[key] : void 0;
@@ -1558,4 +1546,4 @@ exports.isZodSchemaType = isZodSchemaType;
 exports.useForm = useForm;
 exports.withMeta = withMeta;
 exports.zodAdapter = zodAdapter;
-//# sourceMappingURL=attaform.Bp1c-uGF.cjs.map
+//# sourceMappingURL=attaform.Dd_pWnmn.cjs.map