attaform 0.25.0 → 0.26.0

package/dist/shared/{attaform.xBDo0Ko0.cjs → attaform.D51IwDtP.cjs}

@@ -1,6 +1,6 @@
 'use strict';
 
-const paths = require('./attaform.3heDHayA.cjs');
+const paths = require('./attaform.BPl-ECRT.cjs');
 
 function renderAttaformState(app) {
   const registry = paths.getRegistryFromApp(app);
@@ -36,4 +36,4 @@ const DEVTOOLS_WINDOW_KEY = "__attaform_devtools__";
 exports.DEVTOOLS_WINDOW_KEY = DEVTOOLS_WINDOW_KEY;
 exports.hydrateAttaformState = hydrateAttaformState;
 exports.renderAttaformState = renderAttaformState;
-//# sourceMappingURL=attaform.xBDo0Ko0.cjs.map
+//# sourceMappingURL=attaform.D51IwDtP.cjs.map

package/dist/shared/{attaform.xBDo0Ko0.cjs.map → attaform.D51IwDtP.cjs.map}

@@ -1 +1 @@
-{"version":3,"file":"attaform.xBDo0Ko0.cjs","sources":["../../src/runtime/core/serialize.ts","../../src/runtime/core/devtools-shared.ts"],"sourcesContent":["import type { App } from 'vue'\nimport type { FormKey } from '../types/types-api'\nimport { pathKeyToDotted, type PathKey } from './paths'\nimport { getRegistryFromApp, type SerializedFormData } from './registry'\n\n/**\n * Serialised snapshot of every form in a Vue app, produced by\n * `renderAttaformState` and consumed by `hydrateAttaformState`.\n *\n * JSON-safe — pass to `JSON.stringify`, `devalue`, or any other\n * serialiser before embedding in your SSR payload.\n */\nexport type SerializedAttaformState = {\n  /** Tuples of `[formKey, snapshot]` for every form in the app. */\n  readonly forms: ReadonlyArray<readonly [FormKey, SerializedFormData]>\n}\n\n/**\n * Snapshot every form on a Vue app for SSR. Call from your server\n * entry after rendering the app:\n *\n * ```ts\n * import { renderToString } from '@vue/server-renderer'\n * import { renderAttaformState, escapeForInlineScript } from 'attaform'\n *\n * const html = await renderToString(app)\n * const state = renderAttaformState(app)\n * const payload = escapeForInlineScript(JSON.stringify(state))\n *\n * return `\n *   ${html}\n *   <script>window.__ATTAFORM_STATE__ = ${payload}</script>\n * `\n * ```\n *\n * Pair with `hydrateAttaformState` on the client to restore the\n * forms in their server-rendered state. Nuxt users don't need this —\n * `attaform/nuxt` wires SSR automatically.\n */\nexport function renderAttaformState(app: App): SerializedAttaformState {\n  const registry = getRegistryFromApp(app)\n  const forms: Array<readonly [FormKey, SerializedFormData]> = []\n  for (const [key, state] of registry.forms) {\n    // Skip the blank field when the set is empty so the\n    // wire payload stays minimal for forms that don't use it. The\n    // optional shape on the consuming side handles the absence\n    // cleanly (defaults to \"no blank paths\"). PathKey → dotted at\n    // the boundary so the wire shape matches the rest of the\n    // public path notation.\n    const transientList: string[] = []\n    for (const pk of state.blankPaths) {\n      const d = pathKeyToDotted(pk as PathKey)\n      if (d !== null) transientList.push(d)\n    }\n    forms.push([\n      key,\n      {\n        form: state.form.value,\n        schemaErrors: Array.from(state.schemaErrors.entries()),\n        userErrors: Array.from(state.userErrors.entries()),\n        fields: Array.from(state.fields.entries()),\n        ...(transientList.length > 0 ? { blankPaths: transientList } : {}),\n      },\n    ])\n  }\n  return { forms }\n}\n\n/**\n * Restore forms from a server-rendered snapshot on the client. Call\n * from your client entry before mounting:\n *\n * ```ts\n * import { createApp } from 'vue'\n * import { createAttaform, hydrateAttaformState } from 'attaform'\n *\n * const app = createApp(App).use(createAttaform())\n * hydrateAttaformState(app, window.__ATTAFORM_STATE__)\n * app.mount('#app')\n * ```\n *\n * The next `useForm({ key })` call for each serialised form picks up\n * the snapshot transparently — no further action is required.\n */\nexport function hydrateAttaformState(app: App, payload: SerializedAttaformState): void {\n  const registry = getRegistryFromApp(app)\n  for (const [key, data] of payload.forms) {\n    registry.pendingHydration.set(key, data)\n  }\n}\n","/**\n * Shared building blocks for Attaform's two devtools surfaces — the Vue\n * DevTools (Chrome-extension) inspector wired up in `./devtools.ts`, and\n * the Nuxt DevTools (overlay) panel wired up via `../../nuxt.ts` +\n * `../pages/_attaform_devtools.vue`.\n *\n * Houses the window-bridge contract both surfaces consume so a new\n * bridge field lands in one file. Both surfaces render RAW form values\n * by design — DevTools is a dev-only surface, and redaction across every\n * place a value surfaces is impractical security theater rather than a\n * real safeguard.\n */\nimport type { AttaformRegistry } from './registry'\n\n/**\n * Property key on `window` that the Nuxt-side dev plugin attaches the\n * bridge object to. The iframe-mounted overlay panel reads\n * `window.parent[DEVTOOLS_WINDOW_KEY]` to reach the host app's registry.\n *\n * Underscored + namespaced to make accidental collision with consumer\n * globals vanishingly unlikely. Stable across versions — bumping it\n * would silently disconnect older library builds from newer overlay\n * panels in the same browser tab during a library upgrade.\n */\nexport const DEVTOOLS_WINDOW_KEY = '__attaform_devtools__'\n\n/**\n * Shape of the object the host plugin attaches to `window` in dev mode.\n * The iframe overlay panel reads this to discover the live registry and\n * render its forms.\n *\n * Single-registry assumption: the latest `createAttaform()` install\n * wins. Multi-app pages (rare; typically only seen in micro-frontend\n * setups) will only see one app's forms in the panel. Documented but\n * not actively supported — the alternative (a Set of registries with\n * union-rendering) is a future call if a real consumer hits it.\n */\nexport interface AttaformDevtoolsBridge {\n  registry: AttaformRegistry\n  /**\n   * The library version, surfaced in the panel's footer for support /\n   * bug-report context. Read from `package.json` at host-plugin init.\n   */\n  version: string\n}\n\ndeclare global {\n  interface Window {\n    [DEVTOOLS_WINDOW_KEY]?: AttaformDevtoolsBridge\n  }\n}\n"],"names":["getRegistryFromApp","pathKeyToDotted"],"mappings":";;;;AAuCO,SAAS,oBAAoB,GAAA,EAAmC;AACrE,EAAA,MAAM,QAAA,GAAWA,yBAAmB,GAAG,CAAA;AACvC,EAAA,MAAM,QAAuD,EAAC;AAC9D,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,CAAA,IAAK,SAAS,KAAA,EAAO;AAOzC,IAAA,MAAM,gBAA0B,EAAC;AACjC,IAAA,KAAA,MAAW,EAAA,IAAM,MAAM,UAAA,EAAY;AACjC,MAAA,MAAM,CAAA,GAAIC,sBAAgB,EAAa,CAAA;AACvC,MAAA,IAAI,CAAA,KAAM,IAAA,EAAM,aAAA,CAAc,IAAA,CAAK,CAAC,CAAA;AAAA,IACtC;AACA,IAAA,KAAA,CAAM,IAAA,CAAK;AAAA,MACT,GAAA;AAAA,MACA;AAAA,QACE,IAAA,EAAM,MAAM,IAAA,CAAK,KAAA;AAAA,QACjB,cAAc,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,YAAA,CAAa,SAAS,CAAA;AAAA,QACrD,YAAY,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,UAAA,CAAW,SAAS,CAAA;AAAA,QACjD,QAAQ,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,SAAS,CAAA;AAAA,QACzC,GAAI,cAAc,MAAA,GAAS,CAAA,GAAI,EAAE,UAAA,EAAY,aAAA,KAAkB;AAAC;AAClE,KACD,CAAA;AAAA,EACH;AACA,EAAA,OAAO,EAAE,KAAA,EAAM;AACjB;AAkBO,SAAS,oBAAA,CAAqB,KAAU,OAAA,EAAwC;AACrF,EAAA,MAAM,QAAA,GAAWD,yBAAmB,GAAG,CAAA;AACvC,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,IAAI,CAAA,IAAK,QAAQ,KAAA,EAAO;AACvC,IAAA,QAAA,CAAS,gBAAA,CAAiB,GAAA,CAAI,GAAA,EAAK,IAAI,CAAA;AAAA,EACzC;AACF;;ACjEO,MAAM,mBAAA,GAAsB;;;;;;"}
+{"version":3,"file":"attaform.D51IwDtP.cjs","sources":["../../src/runtime/core/serialize.ts","../../src/runtime/core/devtools-shared.ts"],"sourcesContent":["import type { App } from 'vue'\nimport type { FormKey } from '../types/types-api'\nimport { pathKeyToDotted, type PathKey } from './paths'\nimport { getRegistryFromApp, type SerializedFormData } from './registry'\n\n/**\n * Serialised snapshot of every form in a Vue app, produced by\n * `renderAttaformState` and consumed by `hydrateAttaformState`.\n *\n * JSON-safe — pass to `JSON.stringify`, `devalue`, or any other\n * serialiser before embedding in your SSR payload.\n */\nexport type SerializedAttaformState = {\n  /** Tuples of `[formKey, snapshot]` for every form in the app. */\n  readonly forms: ReadonlyArray<readonly [FormKey, SerializedFormData]>\n}\n\n/**\n * Snapshot every form on a Vue app for SSR. Call from your server\n * entry after rendering the app:\n *\n * ```ts\n * import { renderToString } from '@vue/server-renderer'\n * import { renderAttaformState, escapeForInlineScript } from 'attaform'\n *\n * const html = await renderToString(app)\n * const state = renderAttaformState(app)\n * const payload = escapeForInlineScript(JSON.stringify(state))\n *\n * return `\n *   ${html}\n *   <script>window.__ATTAFORM_STATE__ = ${payload}</script>\n * `\n * ```\n *\n * Pair with `hydrateAttaformState` on the client to restore the\n * forms in their server-rendered state. Nuxt users don't need this —\n * `attaform/nuxt` wires SSR automatically.\n */\nexport function renderAttaformState(app: App): SerializedAttaformState {\n  const registry = getRegistryFromApp(app)\n  const forms: Array<readonly [FormKey, SerializedFormData]> = []\n  for (const [key, state] of registry.forms) {\n    // Skip the blank field when the set is empty so the\n    // wire payload stays minimal for forms that don't use it. The\n    // optional shape on the consuming side handles the absence\n    // cleanly (defaults to \"no blank paths\"). PathKey → dotted at\n    // the boundary so the wire shape matches the rest of the\n    // public path notation.\n    const transientList: string[] = []\n    for (const pk of state.blankPaths) {\n      const d = pathKeyToDotted(pk as PathKey)\n      if (d !== null) transientList.push(d)\n    }\n    forms.push([\n      key,\n      {\n        form: state.form.value,\n        schemaErrors: Array.from(state.schemaErrors.entries()),\n        userErrors: Array.from(state.userErrors.entries()),\n        fields: Array.from(state.fields.entries()),\n        ...(transientList.length > 0 ? { blankPaths: transientList } : {}),\n      },\n    ])\n  }\n  return { forms }\n}\n\n/**\n * Restore forms from a server-rendered snapshot on the client. Call\n * from your client entry before mounting:\n *\n * ```ts\n * import { createApp } from 'vue'\n * import { createAttaform, hydrateAttaformState } from 'attaform'\n *\n * const app = createApp(App).use(createAttaform())\n * hydrateAttaformState(app, window.__ATTAFORM_STATE__)\n * app.mount('#app')\n * ```\n *\n * The next `useForm({ key })` call for each serialised form picks up\n * the snapshot transparently — no further action is required.\n */\nexport function hydrateAttaformState(app: App, payload: SerializedAttaformState): void {\n  const registry = getRegistryFromApp(app)\n  for (const [key, data] of payload.forms) {\n    registry.pendingHydration.set(key, data)\n  }\n}\n","/**\n * Shared building blocks for Attaform's two devtools surfaces — the Vue\n * DevTools (Chrome-extension) inspector wired up in `./devtools.ts`, and\n * the Nuxt DevTools (overlay) panel wired up via `../../nuxt.ts` +\n * `../pages/_attaform_devtools.vue`.\n *\n * Houses the window-bridge contract both surfaces consume so a new\n * bridge field lands in one file. Both surfaces render RAW form values\n * by design — DevTools is a dev-only surface, and redaction across every\n * place a value surfaces is impractical security theater rather than a\n * real safeguard.\n */\nimport type { AttaformRegistry } from './registry'\n\n/**\n * Property key on `window` that the Nuxt-side dev plugin attaches the\n * bridge object to. The iframe-mounted overlay panel reads\n * `window.parent[DEVTOOLS_WINDOW_KEY]` to reach the host app's registry.\n *\n * Underscored + namespaced to make accidental collision with consumer\n * globals vanishingly unlikely. Stable across versions — bumping it\n * would silently disconnect older library builds from newer overlay\n * panels in the same browser tab during a library upgrade.\n */\nexport const DEVTOOLS_WINDOW_KEY = '__attaform_devtools__'\n\n/**\n * Shape of the object the host plugin attaches to `window` in dev mode.\n * The iframe overlay panel reads this to discover the live registry and\n * render its forms.\n *\n * Single-registry assumption: the latest `createAttaform()` install\n * wins. Multi-app pages (rare; typically only seen in micro-frontend\n * setups) will only see one app's forms in the panel. Documented but\n * not actively supported — the alternative (a Set of registries with\n * union-rendering) is a future call if a real consumer hits it.\n */\nexport interface AttaformDevtoolsBridge {\n  registry: AttaformRegistry\n  /**\n   * The library version, surfaced in the panel's footer for support /\n   * bug-report context. Read from `package.json` at host-plugin init.\n   */\n  version: string\n}\n\ndeclare global {\n  interface Window {\n    [DEVTOOLS_WINDOW_KEY]?: AttaformDevtoolsBridge\n  }\n}\n"],"names":["getRegistryFromApp","pathKeyToDotted"],"mappings":";;;;AAuCO,SAAS,oBAAoB,GAAA,EAAmC;AACrE,EAAA,MAAM,QAAA,GAAWA,yBAAmB,GAAG,CAAA;AACvC,EAAA,MAAM,QAAuD,EAAC;AAC9D,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,KAAK,CAAA,IAAK,SAAS,KAAA,EAAO;AAOzC,IAAA,MAAM,gBAA0B,EAAC;AACjC,IAAA,KAAA,MAAW,EAAA,IAAM,MAAM,UAAA,EAAY;AACjC,MAAA,MAAM,CAAA,GAAIC,sBAAgB,EAAa,CAAA;AACvC,MAAA,IAAI,CAAA,KAAM,IAAA,EAAM,aAAA,CAAc,IAAA,CAAK,CAAC,CAAA;AAAA,IACtC;AACA,IAAA,KAAA,CAAM,IAAA,CAAK;AAAA,MACT,GAAA;AAAA,MACA;AAAA,QACE,IAAA,EAAM,MAAM,IAAA,CAAK,KAAA;AAAA,QACjB,cAAc,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,YAAA,CAAa,SAAS,CAAA;AAAA,QACrD,YAAY,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,UAAA,CAAW,SAAS,CAAA;AAAA,QACjD,QAAQ,KAAA,CAAM,IAAA,CAAK,KAAA,CAAM,MAAA,CAAO,SAAS,CAAA;AAAA,QACzC,GAAI,cAAc,MAAA,GAAS,CAAA,GAAI,EAAE,UAAA,EAAY,aAAA,KAAkB;AAAC;AAClE,KACD,CAAA;AAAA,EACH;AACA,EAAA,OAAO,EAAE,KAAA,EAAM;AACjB;AAkBO,SAAS,oBAAA,CAAqB,KAAU,OAAA,EAAwC;AACrF,EAAA,MAAM,QAAA,GAAWD,yBAAmB,GAAG,CAAA;AACvC,EAAA,KAAA,MAAW,CAAC,GAAA,EAAK,IAAI,CAAA,IAAK,QAAQ,KAAA,EAAO;AACvC,IAAA,QAAA,CAAS,gBAAA,CAAiB,GAAA,CAAI,GAAA,EAAK,IAAI,CAAA;AAAA,EACzC;AACF;;ACjEO,MAAM,mBAAA,GAAsB;;;;;;"}

package/dist/shared/{attaform.i_LA3X9o.d.cts → attaform.DBNjHgNj.d.cts}

@@ -137,8 +137,8 @@ declare function canonicalizePath(input: string | Path): {
  * `Path` to address the form value as a whole, and the home for
  * form-level (global) errors: root `.refine()` messages, hydration
  * failures, and `setErrors` entries with no path all live at `[]`. Aggregate
- * reads (`errors()`, `meta.errors`) surface them alongside field
- * errors; `errors([])` returns the global bucket alone.
+ * reads (`errors()`, `errors([])`, `meta.errors`) surface them alongside
+ * field errors; `meta.ownErrors` returns the root bucket alone.
  *
  * The empty SEGMENT tuple `[]` is structurally unconstructible as a
  * field path, so it can never collide with a schema key, unlike the
@@ -2074,14 +2074,15 @@ type OnError = (error: ValidationError[]) => void | Promise<void>;
 type DisplayState = 'idle' | 'pending' | 'error' | 'success';
 /**
  * Keys on `FieldState` layered on FROM the display-state predicate
- * (plus `firstError`, computed alongside them). `Omit`'d from the
- * predicate's arguments so a predicate cannot read its own output and
- * form a cycle — enforced at the type level AND at runtime: the base
- * objects passed in literally lack these keys, so an `as` cast in TS
- * or a vanilla-JS caller still can't reach them. `FieldStateBase` /
- * `FormMetaBase` (field-state-api.ts) omit the same set in lockstep.
+ * (plus `firstError` / `firstOwnError`, computed alongside them).
+ * `Omit`'d from the predicate's arguments so a predicate cannot read
+ * its own output and form a cycle — enforced at the type level AND at
+ * runtime: the base objects passed in literally lack these keys, so an
+ * `as` cast in TS or a vanilla-JS caller still can't reach them.
+ * `FieldStateBase` / `FormMetaBase` (field-state-api.ts) omit the same
+ * set in lockstep.
  */
-type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
+type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError' | 'firstOwnError';
 /**
  * One step of the display state machine: the verdict the field should
  * render right now (`display`, projected to `displayState` and the
@@ -3114,7 +3115,40 @@ type FieldState<Value = unknown> = {
      */
     readonly elements: readonly HTMLElement[];
     readonly updatedAt: string | null;
+    /**
+     * Every `ValidationError` in this path's SUBTREE: the node's own
+     * bucket plus every descendant's, sorted by schema-declaration order.
+     * On a leaf (no descendants) this equals `ownErrors`. On a container
+     * it rolls up the whole fieldset, so a parent's `errors` is non-empty
+     * whenever any child is invalid.
+     *
+     * For the errors pinned at THIS path alone (a container's own
+     * cross-field `.refine()`, or `setErrors` at this path), read
+     * `ownErrors`.
+     */
     readonly errors: readonly ValidationError[];
+    /**
+     * Every `ValidationError` at THIS exact path's own bucket, excluding
+     * descendants: schema errors, blank-required errors, and `setErrors`
+     * pinned here, in `schema`, `blank`, `user` order. The exact-path
+     * counterpart to the subtree-scoped `errors`.
+     *
+     * On a leaf this is the same array as `errors` (a leaf has no
+     * descendants). On a container it holds only the container's OWN
+     * errors, a cross-field `.refine()` on the fieldset or a path-less
+     * `setErrors` at this node, without dragging in any child error:
+     *
+     * ```vue
+     * <p v-if="form.fields.address.firstOwnError">
+     *   {{ form.fields.address.firstOwnError.message }}
+     * </p>
+     * ```
+     *
+     * On `form.meta` this is the root `[]` bucket: form-level errors from
+     * a root `.refine()` or a path-less `setErrors`. `form.meta.ownErrors`
+     * (with `firstOwnError`) is the banner accessor for those.
+     */
+    readonly ownErrors: readonly ValidationError[];
     /**
      * `true` while a per-field validation run is in flight at this path.
      * Reflects field-level debounced runs (`validate-on-change`) and
@@ -3235,9 +3269,28 @@ type FieldState<Value = unknown> = {
      * decides when to render it.
      *
      * On container paths, the first error in the aggregated subtree
-     * (descendants sorted by `pathOrdinal`).
+     * (descendants sorted by `pathOrdinal`). For the container's OWN
+     * first error only, read `firstOwnError`.
      */
     readonly firstError: ValidationError | undefined;
+    /**
+     * The first `ValidationError` in `ownErrors` (this exact path's own
+     * bucket), or `undefined` when that bucket is empty. Equivalent to
+     * `ownErrors[0]`, the exact-path counterpart to `firstError`.
+     *
+     * On a leaf this equals `firstError`. On a container it is the
+     * container's own cross-field error (a fieldset `.refine()`), never a
+     * child's. `form.meta.firstOwnError` is the form-level banner: the
+     * first root `[]` error from a root `.refine()` or a path-less
+     * `setErrors`:
+     *
+     * ```vue
+     * <p v-if="form.meta.firstOwnError" role="alert">
+     *   {{ form.meta.firstOwnError.message }}
+     * </p>
+     * ```
+     */
+    readonly firstOwnError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
     /**
      * Stable, SSR-safe DOM id for this field, unique across every mount
@@ -3601,11 +3654,13 @@ type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
     <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[];
     (segments: ReadonlyArray<string | number>): readonly ValidationError[];
     /**
-     * No-arg call returns the whole-form error aggregate — same as
-     * `form.meta.errors`: every field error plus the global bucket.
-     * Distinct from `form.errors([])`, which returns ONLY the global
-     * (root) bucket. Always a readonly array; empty when the form has no
-     * errors.
+     * No-arg call returns the whole-form error aggregate, the same as
+     * `form.meta.errors` and `form.errors([])`: every field error plus
+     * the root bucket. `form.errors(path)` is uniform at every depth,
+     * including `[]`, so the root is no exception. For the root bucket
+     * alone (a root `.refine()`, a path-less `setErrors`), read
+     * `form.meta.ownErrors`. Always a readonly array; empty when the form
+     * has no errors.
      */
     (): readonly ValidationError[];
 };

package/dist/shared/{attaform.i_LA3X9o.d.mts → attaform.DBNjHgNj.d.mts}

@@ -137,8 +137,8 @@ declare function canonicalizePath(input: string | Path): {
  * `Path` to address the form value as a whole, and the home for
  * form-level (global) errors: root `.refine()` messages, hydration
  * failures, and `setErrors` entries with no path all live at `[]`. Aggregate
- * reads (`errors()`, `meta.errors`) surface them alongside field
- * errors; `errors([])` returns the global bucket alone.
+ * reads (`errors()`, `errors([])`, `meta.errors`) surface them alongside
+ * field errors; `meta.ownErrors` returns the root bucket alone.
  *
  * The empty SEGMENT tuple `[]` is structurally unconstructible as a
  * field path, so it can never collide with a schema key, unlike the
@@ -2074,14 +2074,15 @@ type OnError = (error: ValidationError[]) => void | Promise<void>;
 type DisplayState = 'idle' | 'pending' | 'error' | 'success';
 /**
  * Keys on `FieldState` layered on FROM the display-state predicate
- * (plus `firstError`, computed alongside them). `Omit`'d from the
- * predicate's arguments so a predicate cannot read its own output and
- * form a cycle — enforced at the type level AND at runtime: the base
- * objects passed in literally lack these keys, so an `as` cast in TS
- * or a vanilla-JS caller still can't reach them. `FieldStateBase` /
- * `FormMetaBase` (field-state-api.ts) omit the same set in lockstep.
+ * (plus `firstError` / `firstOwnError`, computed alongside them).
+ * `Omit`'d from the predicate's arguments so a predicate cannot read
+ * its own output and form a cycle — enforced at the type level AND at
+ * runtime: the base objects passed in literally lack these keys, so an
+ * `as` cast in TS or a vanilla-JS caller still can't reach them.
+ * `FieldStateBase` / `FormMetaBase` (field-state-api.ts) omit the same
+ * set in lockstep.
  */
-type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
+type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError' | 'firstOwnError';
 /**
  * One step of the display state machine: the verdict the field should
  * render right now (`display`, projected to `displayState` and the
@@ -3114,7 +3115,40 @@ type FieldState<Value = unknown> = {
      */
     readonly elements: readonly HTMLElement[];
     readonly updatedAt: string | null;
+    /**
+     * Every `ValidationError` in this path's SUBTREE: the node's own
+     * bucket plus every descendant's, sorted by schema-declaration order.
+     * On a leaf (no descendants) this equals `ownErrors`. On a container
+     * it rolls up the whole fieldset, so a parent's `errors` is non-empty
+     * whenever any child is invalid.
+     *
+     * For the errors pinned at THIS path alone (a container's own
+     * cross-field `.refine()`, or `setErrors` at this path), read
+     * `ownErrors`.
+     */
     readonly errors: readonly ValidationError[];
+    /**
+     * Every `ValidationError` at THIS exact path's own bucket, excluding
+     * descendants: schema errors, blank-required errors, and `setErrors`
+     * pinned here, in `schema`, `blank`, `user` order. The exact-path
+     * counterpart to the subtree-scoped `errors`.
+     *
+     * On a leaf this is the same array as `errors` (a leaf has no
+     * descendants). On a container it holds only the container's OWN
+     * errors, a cross-field `.refine()` on the fieldset or a path-less
+     * `setErrors` at this node, without dragging in any child error:
+     *
+     * ```vue
+     * <p v-if="form.fields.address.firstOwnError">
+     *   {{ form.fields.address.firstOwnError.message }}
+     * </p>
+     * ```
+     *
+     * On `form.meta` this is the root `[]` bucket: form-level errors from
+     * a root `.refine()` or a path-less `setErrors`. `form.meta.ownErrors`
+     * (with `firstOwnError`) is the banner accessor for those.
+     */
+    readonly ownErrors: readonly ValidationError[];
     /**
      * `true` while a per-field validation run is in flight at this path.
      * Reflects field-level debounced runs (`validate-on-change`) and
@@ -3235,9 +3269,28 @@ type FieldState<Value = unknown> = {
      * decides when to render it.
      *
      * On container paths, the first error in the aggregated subtree
-     * (descendants sorted by `pathOrdinal`).
+     * (descendants sorted by `pathOrdinal`). For the container's OWN
+     * first error only, read `firstOwnError`.
      */
     readonly firstError: ValidationError | undefined;
+    /**
+     * The first `ValidationError` in `ownErrors` (this exact path's own
+     * bucket), or `undefined` when that bucket is empty. Equivalent to
+     * `ownErrors[0]`, the exact-path counterpart to `firstError`.
+     *
+     * On a leaf this equals `firstError`. On a container it is the
+     * container's own cross-field error (a fieldset `.refine()`), never a
+     * child's. `form.meta.firstOwnError` is the form-level banner: the
+     * first root `[]` error from a root `.refine()` or a path-less
+     * `setErrors`:
+     *
+     * ```vue
+     * <p v-if="form.meta.firstOwnError" role="alert">
+     *   {{ form.meta.firstOwnError.message }}
+     * </p>
+     * ```
+     */
+    readonly firstOwnError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
     /**
      * Stable, SSR-safe DOM id for this field, unique across every mount
@@ -3601,11 +3654,13 @@ type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
     <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[];
     (segments: ReadonlyArray<string | number>): readonly ValidationError[];
     /**
-     * No-arg call returns the whole-form error aggregate — same as
-     * `form.meta.errors`: every field error plus the global bucket.
-     * Distinct from `form.errors([])`, which returns ONLY the global
-     * (root) bucket. Always a readonly array; empty when the form has no
-     * errors.
+     * No-arg call returns the whole-form error aggregate, the same as
+     * `form.meta.errors` and `form.errors([])`: every field error plus
+     * the root bucket. `form.errors(path)` is uniform at every depth,
+     * including `[]`, so the root is no exception. For the root bucket
+     * alone (a root `.refine()`, a path-less `setErrors`), read
+     * `form.meta.ownErrors`. Always a readonly array; empty when the form
+     * has no errors.
      */
     (): readonly ValidationError[];
 };

package/dist/shared/{attaform.i_LA3X9o.d.ts → attaform.DBNjHgNj.d.ts}

@@ -137,8 +137,8 @@ declare function canonicalizePath(input: string | Path): {
  * `Path` to address the form value as a whole, and the home for
  * form-level (global) errors: root `.refine()` messages, hydration
  * failures, and `setErrors` entries with no path all live at `[]`. Aggregate
- * reads (`errors()`, `meta.errors`) surface them alongside field
- * errors; `errors([])` returns the global bucket alone.
+ * reads (`errors()`, `errors([])`, `meta.errors`) surface them alongside
+ * field errors; `meta.ownErrors` returns the root bucket alone.
  *
  * The empty SEGMENT tuple `[]` is structurally unconstructible as a
  * field path, so it can never collide with a schema key, unlike the
@@ -2074,14 +2074,15 @@ type OnError = (error: ValidationError[]) => void | Promise<void>;
 type DisplayState = 'idle' | 'pending' | 'error' | 'success';
 /**
  * Keys on `FieldState` layered on FROM the display-state predicate
- * (plus `firstError`, computed alongside them). `Omit`'d from the
- * predicate's arguments so a predicate cannot read its own output and
- * form a cycle — enforced at the type level AND at runtime: the base
- * objects passed in literally lack these keys, so an `as` cast in TS
- * or a vanilla-JS caller still can't reach them. `FieldStateBase` /
- * `FormMetaBase` (field-state-api.ts) omit the same set in lockstep.
+ * (plus `firstError` / `firstOwnError`, computed alongside them).
+ * `Omit`'d from the predicate's arguments so a predicate cannot read
+ * its own output and form a cycle — enforced at the type level AND at
+ * runtime: the base objects passed in literally lack these keys, so an
+ * `as` cast in TS or a vanilla-JS caller still can't reach them.
+ * `FieldStateBase` / `FormMetaBase` (field-state-api.ts) omit the same
+ * set in lockstep.
  */
-type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError';
+type FieldStateDerivedKey = 'displayState' | 'showErrors' | 'showPending' | 'showSuccess' | 'showIdle' | 'firstError' | 'firstOwnError';
 /**
  * One step of the display state machine: the verdict the field should
  * render right now (`display`, projected to `displayState` and the
@@ -3114,7 +3115,40 @@ type FieldState<Value = unknown> = {
      */
     readonly elements: readonly HTMLElement[];
     readonly updatedAt: string | null;
+    /**
+     * Every `ValidationError` in this path's SUBTREE: the node's own
+     * bucket plus every descendant's, sorted by schema-declaration order.
+     * On a leaf (no descendants) this equals `ownErrors`. On a container
+     * it rolls up the whole fieldset, so a parent's `errors` is non-empty
+     * whenever any child is invalid.
+     *
+     * For the errors pinned at THIS path alone (a container's own
+     * cross-field `.refine()`, or `setErrors` at this path), read
+     * `ownErrors`.
+     */
     readonly errors: readonly ValidationError[];
+    /**
+     * Every `ValidationError` at THIS exact path's own bucket, excluding
+     * descendants: schema errors, blank-required errors, and `setErrors`
+     * pinned here, in `schema`, `blank`, `user` order. The exact-path
+     * counterpart to the subtree-scoped `errors`.
+     *
+     * On a leaf this is the same array as `errors` (a leaf has no
+     * descendants). On a container it holds only the container's OWN
+     * errors, a cross-field `.refine()` on the fieldset or a path-less
+     * `setErrors` at this node, without dragging in any child error:
+     *
+     * ```vue
+     * <p v-if="form.fields.address.firstOwnError">
+     *   {{ form.fields.address.firstOwnError.message }}
+     * </p>
+     * ```
+     *
+     * On `form.meta` this is the root `[]` bucket: form-level errors from
+     * a root `.refine()` or a path-less `setErrors`. `form.meta.ownErrors`
+     * (with `firstOwnError`) is the banner accessor for those.
+     */
+    readonly ownErrors: readonly ValidationError[];
     /**
      * `true` while a per-field validation run is in flight at this path.
      * Reflects field-level debounced runs (`validate-on-change`) and
@@ -3235,9 +3269,28 @@ type FieldState<Value = unknown> = {
      * decides when to render it.
      *
      * On container paths, the first error in the aggregated subtree
-     * (descendants sorted by `pathOrdinal`).
+     * (descendants sorted by `pathOrdinal`). For the container's OWN
+     * first error only, read `firstOwnError`.
      */
     readonly firstError: ValidationError | undefined;
+    /**
+     * The first `ValidationError` in `ownErrors` (this exact path's own
+     * bucket), or `undefined` when that bucket is empty. Equivalent to
+     * `ownErrors[0]`, the exact-path counterpart to `firstError`.
+     *
+     * On a leaf this equals `firstError`. On a container it is the
+     * container's own cross-field error (a fieldset `.refine()`), never a
+     * child's. `form.meta.firstOwnError` is the form-level banner: the
+     * first root `[]` error from a root `.refine()` or a path-less
+     * `setErrors`:
+     *
+     * ```vue
+     * <p v-if="form.meta.firstOwnError" role="alert">
+     *   {{ form.meta.firstOwnError.message }}
+     * </p>
+     * ```
+     */
+    readonly firstOwnError: ValidationError | undefined;
     readonly path: ReadonlyArray<string | number>;
     /**
      * Stable, SSR-safe DOM id for this field, unique across every mount
@@ -3601,11 +3654,13 @@ type FormErrorsSurface<Form> = ErrorsProxyShape<Form> & {
     <const S extends ReadonlyArray<string | number>>(segments: S & ([JoinSegments<S>] extends [FlatPath<Form>] ? unknown : never)): readonly ValidationError[];
     (segments: ReadonlyArray<string | number>): readonly ValidationError[];
     /**
-     * No-arg call returns the whole-form error aggregate — same as
-     * `form.meta.errors`: every field error plus the global bucket.
-     * Distinct from `form.errors([])`, which returns ONLY the global
-     * (root) bucket. Always a readonly array; empty when the form has no
-     * errors.
+     * No-arg call returns the whole-form error aggregate, the same as
+     * `form.meta.errors` and `form.errors([])`: every field error plus
+     * the root bucket. `form.errors(path)` is uniform at every depth,
+     * including `[]`, so the root is no exception. For the root bucket
+     * alone (a root `.refine()`, a path-less `setErrors`), read
+     * `form.meta.ownErrors`. Always a readonly array; empty when the form
+     * has no errors.
      */
     (): readonly ValidationError[];
 };

package/dist/shared/{attaform.CqwcTExO.mjs → attaform.DGhIix5D.mjs}

@@ -25,6 +25,28 @@ function toError(value) {
   const message = typeof value === "string" && value.length > 0 ? value : `Submit callback threw a non-Error value (${typeof value})`;
   return new Error(message, { cause: value });
 }
+function normalizeErrorInput(item, scope, formKey, defaultCode) {
+  if (item instanceof Error) {
+    return {
+      message: item.message.length > 0 ? item.message : "Unknown error",
+      path: scope !== void 0 ? [...scope] : [],
+      formKey,
+      code: defaultCode
+    };
+  }
+  const entry = {
+    message: typeof item.message === "string" && item.message.length > 0 ? item.message : "Unknown error",
+    path: scope !== void 0 ? [...scope] : Array.isArray(item.path) ? [...item.path] : [],
+    formKey,
+    code: typeof item.code === "string" && item.code.length > 0 ? item.code : defaultCode
+  };
+  if (item.data !== void 0) entry.data = item.data;
+  return entry;
+}
+function normalizeErrorInputs(input, scope, formKey, defaultCode) {
+  const items = Array.isArray(input) ? input : [input];
+  return items.map((item) => normalizeErrorInput(item, scope, formKey, defaultCode));
+}
 class RegistryNotInstalledError extends AttaformError {
   constructor() {
     super(
@@ -1592,5 +1614,5 @@ function pathsEqual(a, b) {
   return true;
 }
 
-export { AttaformError as A, InvalidPathError as I, OutsideSetupError as O, ROOT_PATH as R, SubmitErrorHandlerError as S, __DEV__ as _, InvalidUseFormConfigError as a, ROOT_PATH_KEY as b, RegistryNotInstalledError as c, ReservedFormKeyError as d, assignKey as e, canonicalizePath as f, createAttaform as g, createRegistry as h, getRegistryFromApp as i, isPathPrefix as j, kAttaformRegistry as k, kAttaformWizardActiveStepResolver as l, pathKeyToDotted as m, pathsEqual as n, keyForSegments as o, parseDottedPath as p, INTERACTIVE_TAG_NAMES as q, coerceToPathKey as r, segmentsForPathKey as s, toError as t, useRegistry as u, vRegister as v, ensureAttaformInstalled as w, kFormContext as x, kFormInstanceId as y, kAttaformAncestorWizard as z };
-//# sourceMappingURL=attaform.CqwcTExO.mjs.map
+export { AttaformError as A, kFormInstanceId as B, kAttaformAncestorWizard as C, InvalidPathError as I, OutsideSetupError as O, ROOT_PATH as R, SubmitErrorHandlerError as S, __DEV__ as _, InvalidUseFormConfigError as a, ROOT_PATH_KEY as b, RegistryNotInstalledError as c, ReservedFormKeyError as d, assignKey as e, canonicalizePath as f, createAttaform as g, createRegistry as h, getRegistryFromApp as i, isPathPrefix as j, kAttaformRegistry as k, kAttaformWizardActiveStepResolver as l, pathKeyToDotted as m, pathsEqual as n, keyForSegments as o, parseDottedPath as p, normalizeErrorInput as q, INTERACTIVE_TAG_NAMES as r, segmentsForPathKey as s, toError as t, useRegistry as u, vRegister as v, normalizeErrorInputs as w, coerceToPathKey as x, ensureAttaformInstalled as y, kFormContext as z };
+//# sourceMappingURL=attaform.DGhIix5D.mjs.map