attaform 0.16.3 → 0.16.4

package/dist/shared/{attaform._EqYNPYF.d.mts → attaform.CU3JperC.d.ts}

@@ -98,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.
  */
@@ -465,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.
@@ -475,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;
@@ -1394,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
@@ -1459,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.
@@ -1473,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>`:
@@ -2075,6 +2165,51 @@ 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;
     /**
@@ -2790,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;
@@ -2905,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`.
      *
@@ -2956,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.DLnKT7wk.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._EqYNPYF.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.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.KrNw10aW.cjs → attaform.Dd_pWnmn.cjs}

@@ -2,8 +2,8 @@
 
 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');
 
@@ -787,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 {
@@ -844,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
@@ -879,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;
@@ -1547,4 +1546,4 @@ exports.isZodSchemaType = isZodSchemaType;
 exports.useForm = useForm;
 exports.withMeta = withMeta;
 exports.zodAdapter = zodAdapter;
-//# sourceMappingURL=attaform.KrNw10aW.cjs.map
+//# sourceMappingURL=attaform.Dd_pWnmn.cjs.map