@kontsedal/olas-core 0.0.5 → 0.1.0

package/src/forms/form.ts

@@ -22,6 +22,7 @@ import type {
   FormValue,
   ItemInitial,
 } from './form-types'
+import type { FormIssue, ValidatorResult } from './types'
 
 const FORM_BRAND = Symbol.for('olas.form')
 const FIELD_ARRAY_BRAND = Symbol.for('olas.fieldArray')
@@ -35,6 +36,87 @@ const isFieldArray = (x: unknown): x is FieldArray<Field<unknown> | Form<FormSch
 const isField = (x: unknown): x is Field<unknown> =>
   typeof x === 'object' && x !== null && !isForm(x) && !isFieldArray(x)
 
+/** Any node that can receive parent-form-validator-routed errors (T5.2). */
+type FormErrorTarget = { setFormErrors?: (msgs: ReadonlyArray<string>) => void }
+
+/**
+ * Walk a form tree from `root` following `FormIssue.path` segments. Forms walk
+ * keys; field-arrays walk numeric indices. Returns the resolved node, or
+ * `undefined` if the path runs off the tree (bad index, or a leaf reached with
+ * an unconsumed path segment). Reads are untracked (`fields` is a static object;
+ * `at()` peeks) so calling this inside a validator effect adds no dependencies.
+ */
+function resolveNode(root: unknown, segments: ReadonlyArray<string | number>): unknown {
+  let cursor: unknown = root
+  for (const seg of segments) {
+    if (cursor === undefined || cursor === null) return undefined
+    if (isForm(cursor)) {
+      cursor = (cursor.fields as Record<string, unknown>)[String(seg)]
+    } else if (isFieldArray(cursor)) {
+      const idx = Number(seg)
+      if (!Number.isInteger(idx) || idx < 0) return undefined
+      cursor = (cursor as { at(i: number): unknown }).at(idx)
+    } else {
+      return undefined
+    }
+  }
+  return cursor
+}
+
+/**
+ * Normalize one validator result into the shared `FormIssue[]` shape. A plain
+ * string is a message on the node itself (empty path); `null` contributes
+ * nothing; a `FormIssue[]` is appended verbatim.
+ */
+function appendIssues(out: FormIssue[], result: ValidatorResult): void {
+  if (result == null) return
+  if (typeof result === 'string') {
+    out.push({ path: [], message: result })
+    return
+  }
+  for (const issue of result) out.push(issue)
+}
+
+/**
+ * Route a fully-collected issue set for one form-level validation run:
+ *  - empty-path (and unresolvable) issues → `topLevelErrors$` on the owning node
+ *  - path issues → the resolved descendant's `setFormErrors`
+ *
+ * Targets that received an error last run but not this one are cleared, so a
+ * fixed cross-field rule removes its message from the field it landed on.
+ * Returns the new target set for the caller to retain. MUST run inside a batch.
+ */
+function routeFormIssues(
+  root: unknown,
+  issues: FormIssue[],
+  topLevelErrors$: Signal<string[]>,
+  lastTargets: Set<FormErrorTarget>,
+): Set<FormErrorTarget> {
+  const topLevel: string[] = []
+  const byTarget = new Map<FormErrorTarget, string[]>()
+  for (const issue of issues) {
+    if (issue.path.length === 0) {
+      topLevel.push(issue.message)
+      continue
+    }
+    const target = resolveNode(root, issue.path) as FormErrorTarget | undefined
+    if (target === undefined || typeof target.setFormErrors !== 'function') {
+      // Unresolvable path — surface at the top level rather than dropping it.
+      topLevel.push(issue.message)
+      continue
+    }
+    const list = byTarget.get(target)
+    if (list) list.push(issue.message)
+    else byTarget.set(target, [issue.message])
+  }
+  topLevelErrors$.set(topLevel)
+  for (const t of lastTargets) {
+    if (!byTarget.has(t)) t.setFormErrors?.([])
+  }
+  for (const [t, msgs] of byTarget) t.setFormErrors?.(msgs)
+  return new Set(byTarget.keys())
+}
+
 class FormImpl<S extends FormSchema> implements Form<S> {
   readonly [FORM_BRAND] = true
 
@@ -46,10 +128,34 @@ class FormImpl<S extends FormSchema> implements Form<S> {
   readonly touched: ReadSignal<boolean>
   readonly isValidating: ReadSignal<boolean>
   readonly flatErrors: ReadSignal<Array<{ path: string; errors: string[] }>>
+  /**
+   * Dotted paths of every leaf whose `isDirty` is `true`. Recomputes when
+   * any child's dirty state flips; ordered by depth-first traversal so two
+   * snapshots of a stable tree compare with `===`-friendly references on
+   * unchanged subsets. Useful for partial-update PATCH payloads and
+   * "highlight the changed inputs" UIs.
+   */
+  readonly dirtyFields: ReadSignal<string[]>
 
   private readonly topLevelErrors$: Signal<string[]> = signal([])
-  readonly topLevelErrors: ReadSignal<string[]> = this.topLevelErrors$
+  /**
+   * Errors routed to THIS form by an ancestor form-level validator (a
+   * `FormIssue` whose path resolves to this node). Merged into `topLevelErrors`
+   * beside this form's own validator output, so `topLevelErrors` means "errors
+   * attached to this node itself, whatever their source". Owned by the ancestor
+   * router (T5.2) — see `setFormErrors`.
+   */
+  private readonly parentFormErrors$: Signal<string[]> = signal([])
+  readonly topLevelErrors: ReadSignal<string[]> = computed(() => {
+    const own = this.topLevelErrors$.value
+    const parent = this.parentFormErrors$.value
+    if (parent.length === 0) return own
+    if (own.length === 0) return parent
+    return [...own, ...parent]
+  })
   private readonly topLevelValidating$: Signal<boolean> = signal(false)
+  /** Targets written by the last form-level run — cleared next run if absent. */
+  private lastFormErrorTargets: Set<FormErrorTarget> = new Set()
 
   // Submission lifecycle.
   private readonly isSubmitting$: Signal<boolean> = signal(false)
@@ -129,7 +235,9 @@ class FormImpl<S extends FormSchema> implements Form<S> {
       return false
     })
     this.isValid = computed(() => {
-      if (this.topLevelErrors$.value.length > 0) return false
+      // Merged view: this form's own top-level validators AND any errors an
+      // ancestor form-level validator routed onto this node (T5.2).
+      if (this.topLevelErrors.value.length > 0) return false
       if (this.isValidating.value) return false
       for (const child of Object.values(this.fields)) {
         if (!(child as { isValid: ReadSignal<boolean> }).isValid.value) return false
@@ -137,6 +245,11 @@ class FormImpl<S extends FormSchema> implements Form<S> {
       return true
     })
     this.flatErrors = computed(() => this.computeFlatErrors())
+    this.dirtyFields = computed(() => {
+      const out: string[] = []
+      collectDirtyFields(this.fields, '', out)
+      return out
+    })
 
     if (this.validators.length > 0) {
       this.validatorDispose = effect(() => this.runTopLevelValidators())
@@ -181,7 +294,7 @@ class FormImpl<S extends FormSchema> implements Form<S> {
 
   private computeFlatErrors(): Array<{ path: string; errors: string[] }> {
     const out: Array<{ path: string; errors: string[] }> = []
-    const tle = this.topLevelErrors$.value
+    const tle = this.topLevelErrors.value
     if (tle.length > 0) out.push({ path: '', errors: tle })
     walkErrors(this.fields, '', out)
     return out
@@ -272,13 +385,24 @@ class FormImpl<S extends FormSchema> implements Form<S> {
         }
       }
       this.topLevelErrors$.set([])
+      this.parentFormErrors$.set([])
+      // Submission lifecycle is conceptually part of "form state"; resetting
+      // a form means the user is starting over. Without these clears, a UI
+      // bound to `submitCount`/`submitError` would show stale state after
+      // `reset()`. `isSubmitting` is deliberately NOT cleared — only the
+      // owning submit() flow can flip it back.
+      this.submitCount$.set(0)
+      this.submitError$.set(undefined)
+      // Re-apply initial (as initial, no dirty bump) INSIDE the batch — a
+      // separate pass would fire a second notification and briefly expose the
+      // "reset to construction seed, then re-seat to current initial" tearing
+      // (visible with a reactive `initial: () => …` whose deps changed) (T5.3).
+      if (this.options?.initial !== undefined) {
+        const ini =
+          typeof this.options.initial === 'function' ? this.options.initial() : this.options.initial
+        if (ini !== undefined) this.applyPartial(ini as DeepPartial<FormValue<S>>, true)
+      }
     })
-    // Re-apply initial if provided — as initial (no dirty bump).
-    if (this.options?.initial !== undefined) {
-      const ini =
-        typeof this.options.initial === 'function' ? this.options.initial() : this.options.initial
-      if (ini !== undefined) this.applyPartial(ini as DeepPartial<FormValue<S>>, true)
-    }
   }
 
   markAllTouched(): void {
@@ -336,14 +460,14 @@ class FormImpl<S extends FormSchema> implements Form<S> {
    * unless `onError: 'rethrow'`. A `resetOnSuccess: true` option calls
    * `reset()` after the handler resolves successfully.
    */
-  async submit(
-    handler: (value: FormValue<S>) => unknown | Promise<unknown>,
+  async submit<R = unknown>(
+    handler: (value: FormValue<S>) => R | Promise<R>,
     options?: {
       validateBeforeSubmit?: boolean
       resetOnSuccess?: boolean
       onError?: 'rethrow' | 'capture'
     },
-  ): Promise<{ ok: boolean; data?: unknown; error?: unknown }> {
+  ): Promise<{ ok: boolean; data?: Awaited<R>; error?: unknown }> {
     if (this.disposed) return { ok: false, error: new Error('form is disposed') }
 
     // Double-submit guard — refusing to start a second submission while one
@@ -371,7 +495,7 @@ class FormImpl<S extends FormSchema> implements Form<S> {
           return { ok: false }
         }
       }
-      const result = await handler(this.value.peek())
+      const result = (await handler(this.value.peek())) as Awaited<R>
       if (options?.resetOnSuccess) this.reset()
       this.isSubmitting$.set(false)
       return { ok: true, data: result }
@@ -405,9 +529,45 @@ class FormImpl<S extends FormSchema> implements Form<S> {
     })
   }
 
+  /**
+   * Internal — receive errors routed here by an ancestor form-level validator
+   * (a `FormIssue` whose path resolved to this nested form). Guards against
+   * spurious writes so a whole-tree clear pass doesn't wake subscribers. See
+   * `routeFormIssues`.
+   */
+  setFormErrors(errors: ReadonlyArray<string>): void {
+    if (this.disposed) return
+    if (this.parentFormErrors$.peek().length === 0 && errors.length === 0) return
+    this.parentFormErrors$.set(errors.length === 0 ? [] : [...errors])
+  }
+
+  /**
+   * Reset a named subtree to its initial. `path` uses the same dotted /
+   * bracket notation as `setErrors` / `flatErrors`. Useful when
+   * `Form.set({foo: undefined})` would be ambiguous ("clear" vs "leave
+   * alone" — the latter is what `set` does today).
+   *
+   * Walks via `resolvePath`; the resolved target must expose `reset()`
+   * (Field, Form, or FieldArray all do). Unknown paths are silently
+   * ignored — `flatErrors`-shaped paths from upstream code shouldn't
+   * crash this. Pass an empty string to reset the whole form (same as
+   * `form.reset()`).
+   */
+  clearSubtree(path: string): void {
+    if (this.disposed) return
+    if (path === '') {
+      this.reset()
+      return
+    }
+    const target = this.resolvePath(path) as { reset?: () => void } | undefined
+    if (target === undefined) return
+    if (typeof target.reset === 'function') target.reset()
+  }
+
   private resolvePath(path: string): unknown {
     if (path === '') return undefined
-    const segments = path.split('.')
+    const segments = splitPath(path)
+    if (segments === null) return undefined
     let cursor: unknown = this
     for (const seg of segments) {
       if (cursor === undefined || cursor === null) return undefined
@@ -450,26 +610,40 @@ class FormImpl<S extends FormSchema> implements Form<S> {
     this.currentValidatorAbort = abort
     const myId = ++this.currentValidatorRun
 
-    const syncErrors: string[] = []
-    const asyncPromises: Promise<string | null>[] = []
+    const syncIssues: FormIssue[] = []
+    const asyncPromises: Promise<ValidatorResult>[] = []
     for (const v of this.validators) {
       try {
         const r = v(value, abort.signal)
         if (r instanceof Promise) asyncPromises.push(r)
-        else if (r != null) syncErrors.push(r)
+        else appendIssues(syncIssues, r)
       } catch (err) {
         try {
           this.onValidatorError?.(err)
         } catch {
           // The reporter must not propagate.
         }
-        syncErrors.push(err instanceof Error ? err.message : String(err))
+        // Prod shows a generic message (don't leak internal error text into
+        // form errors); the real error still reaches `onValidatorError` (T5.3).
+        syncIssues.push({
+          path: [],
+          message: __DEV__
+            ? err instanceof Error
+              ? err.message
+              : String(err)
+            : 'Validation failed',
+        })
       }
     }
 
-    if (syncErrors.length > 0) {
+    if (syncIssues.length > 0) {
       batch(() => {
-        this.topLevelErrors$.set(syncErrors)
+        this.lastFormErrorTargets = routeFormIssues(
+          this,
+          syncIssues,
+          this.topLevelErrors$,
+          this.lastFormErrorTargets,
+        )
         this.topLevelValidating$.set(false)
       })
       return
@@ -477,31 +651,105 @@ class FormImpl<S extends FormSchema> implements Form<S> {
 
     if (asyncPromises.length === 0) {
       batch(() => {
-        this.topLevelErrors$.set([])
+        this.lastFormErrorTargets = routeFormIssues(
+          this,
+          [],
+          this.topLevelErrors$,
+          this.lastFormErrorTargets,
+        )
         this.topLevelValidating$.set(false)
       })
       return
     }
 
     batch(() => {
-      this.topLevelErrors$.set([])
+      this.lastFormErrorTargets = routeFormIssues(
+        this,
+        [],
+        this.topLevelErrors$,
+        this.lastFormErrorTargets,
+      )
       this.topLevelValidating$.set(true)
     })
 
     Promise.allSettled(asyncPromises).then((results) => {
       if (myId !== this.currentValidatorRun || this.disposed) return
-      const errs: string[] = []
+      const issues: FormIssue[] = []
       for (const r of results) {
-        if (r.status === 'fulfilled' && r.value != null) errs.push(r.value)
+        if (r.status === 'fulfilled') appendIssues(issues, r.value)
       }
       batch(() => {
-        this.topLevelErrors$.set(errs)
+        this.lastFormErrorTargets = routeFormIssues(
+          this,
+          issues,
+          this.topLevelErrors$,
+          this.lastFormErrorTargets,
+        )
         this.topLevelValidating$.set(false)
       })
     })
   }
 }
 
+/**
+ * Split a path string into segments, accepting both dot syntax (`users.0.name`)
+ * and the bracket syntax `walkErrors` emits for array items (`users[0].name`).
+ * Returns `null` if the path is malformed (unclosed bracket, empty bracket,
+ * non-numeric bracket index).
+ */
+function splitPath(path: string): string[] | null {
+  const out: string[] = []
+  let current = ''
+  for (let i = 0; i < path.length; i++) {
+    const ch = path[i]
+    if (ch === '.') {
+      if (current !== '') {
+        out.push(current)
+        current = ''
+      }
+      continue
+    }
+    if (ch === '[') {
+      if (current !== '') {
+        out.push(current)
+        current = ''
+      }
+      const close = path.indexOf(']', i + 1)
+      if (close === -1) return null
+      const idx = path.slice(i + 1, close)
+      if (idx === '' || !/^\d+$/.test(idx)) return null
+      out.push(idx)
+      i = close
+      continue
+    }
+    if (ch === ']') return null
+    current += ch
+  }
+  if (current !== '') out.push(current)
+  return out
+}
+
+function collectDirtyFields(fields: FormSchema, prefix: string, out: string[]): void {
+  for (const [k, child] of Object.entries(fields)) {
+    const path = prefix ? `${prefix}.${k}` : k
+    if (isForm(child)) {
+      collectDirtyFields(child.fields, path, out)
+    } else if (isFieldArray(child)) {
+      const items = child.items.value
+      items.forEach((item, idx) => {
+        const itemPath = `${path}[${idx}]`
+        if (isForm(item)) {
+          collectDirtyFields(item.fields, itemPath, out)
+        } else if ((item as Field<unknown>).isDirty.value) {
+          out.push(itemPath)
+        }
+      })
+    } else if ((child as Field<unknown>).isDirty.value) {
+      out.push(path)
+    }
+  }
+}
+
 function walkErrors(
   fields: FormSchema,
   prefix: string,
@@ -548,9 +796,28 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
   readonly isValidating: ReadSignal<boolean>
 
   private readonly items$: Signal<I[]>
+  /**
+   * Structural dirtiness — flipped by `add`/`insert`/`remove`/`move`/`clear`.
+   * Item-level `isDirty` alone misses these, so a reactive `initial` + the
+   * default `resetOnInitialChange: 'when-clean'` would re-seat the array on a
+   * background refetch and delete rows the user just added (T5.1). Reset by
+   * `reset()` and by an initial-driven re-anchor (`replaceInitialItems`).
+   */
+  private readonly structurallyDirty$: Signal<boolean> = signal(false)
   private readonly topLevelErrors$: Signal<string[]> = signal([])
-  readonly topLevelErrors: ReadSignal<string[]> = this.topLevelErrors$
+  /** Errors routed to this array by an ancestor form-level validator (T5.2) —
+   *  merged into `topLevelErrors` beside the array's own validator output. */
+  private readonly parentFormErrors$: Signal<string[]> = signal([])
+  readonly topLevelErrors: ReadSignal<string[]> = computed(() => {
+    const own = this.topLevelErrors$.value
+    const parent = this.parentFormErrors$.value
+    if (parent.length === 0) return own
+    if (own.length === 0) return parent
+    return [...own, ...parent]
+  })
   private readonly topLevelValidating$: Signal<boolean> = signal(false)
+  /** Targets written by the last array-level run — cleared next run if absent. */
+  private lastFormErrorTargets: Set<FormErrorTarget> = new Set()
 
   private readonly itemFactory: (initial?: ItemInitial<I>) => I
   private initialItems: Array<ItemInitial<I>> = []
@@ -602,6 +869,7 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
       }),
     )
     this.isDirty = computed(() => {
+      if (this.structurallyDirty$.value) return true // add/remove/move/clear
       for (const item of this.items$.value) {
         if ((item as { isDirty: ReadSignal<boolean> }).isDirty.value) return true
       }
@@ -621,7 +889,9 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
       return false
     })
     this.isValid = computed(() => {
-      if (this.topLevelErrors$.value.length > 0) return false
+      // Merged view: the array's own top-level validators AND any errors an
+      // ancestor form-level validator routed onto this node (T5.2).
+      if (this.topLevelErrors.value.length > 0) return false
       if (this.isValidating.value) return false
       for (const item of this.items$.value) {
         if (!(item as { isValid: ReadSignal<boolean> }).isValid.value) return false
@@ -638,10 +908,21 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
     return this.items$.peek()[index]
   }
 
+  /**
+   * Internal — receive errors routed here by an ancestor form-level validator
+   * (a `FormIssue` whose path resolved to this array). See `routeFormIssues`.
+   */
+  setFormErrors(errors: ReadonlyArray<string>): void {
+    if (this.disposed) return
+    if (this.parentFormErrors$.peek().length === 0 && errors.length === 0) return
+    this.parentFormErrors$.set(errors.length === 0 ? [] : [...errors])
+  }
+
   add(initial?: ItemInitial<I>): void {
     if (this.disposed) return
     const item = this.itemFactory(initial)
     this.items$.set([...this.items$.peek(), item])
+    this.structurallyDirty$.set(true)
   }
 
   insert(index: number, initial?: ItemInitial<I>): void {
@@ -650,6 +931,7 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
     const next = [...this.items$.peek()]
     next.splice(index, 0, item)
     this.items$.set(next)
+    this.structurallyDirty$.set(true)
   }
 
   remove(index: number): void {
@@ -660,6 +942,7 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
       ;(removed as { dispose?: () => void }).dispose?.()
     }
     this.items$.set(next)
+    this.structurallyDirty$.set(true)
   }
 
   move(from: number, to: number): void {
@@ -668,6 +951,7 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
     const [item] = next.splice(from, 1)
     if (item) next.splice(to, 0, item)
     this.items$.set(next)
+    this.structurallyDirty$.set(true)
   }
 
   clear(): void {
@@ -676,6 +960,7 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
       ;(item as { dispose?: () => void }).dispose?.()
     }
     this.items$.set([])
+    this.structurallyDirty$.set(true)
   }
 
   /**
@@ -686,6 +971,10 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
    */
   replaceInitialItems(items: ReadonlyArray<ItemInitial<I>>): void {
     this.initialItems = [...items]
+    // The array was just re-seated from `initial` (reactive-initial re-apply or
+    // `resetWithInitial`) — this is the new clean baseline, so the clear()/add()
+    // that drove it must not leave the array structurally dirty (T5.1).
+    this.structurallyDirty$.set(false)
   }
 
   reset(): void {
@@ -696,6 +985,10 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
         this.add(ini)
       }
       this.topLevelErrors$.set([])
+      this.parentFormErrors$.set([])
+      // clear()/add() above flipped structural dirt; reset() lands on the
+      // clean initial baseline (T5.1).
+      this.structurallyDirty$.set(false)
     })
   }
 
@@ -749,26 +1042,40 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
     this.currentValidatorAbort = abort
     const myId = ++this.currentValidatorRun
 
-    const syncErrors: string[] = []
-    const asyncPromises: Promise<string | null>[] = []
+    const syncIssues: FormIssue[] = []
+    const asyncPromises: Promise<ValidatorResult>[] = []
     for (const v of this.validators) {
       try {
         const r = v(value, abort.signal)
         if (r instanceof Promise) asyncPromises.push(r)
-        else if (r != null) syncErrors.push(r)
+        else appendIssues(syncIssues, r)
       } catch (err) {
         try {
           this.onValidatorError?.(err)
         } catch {
           // The reporter must not propagate.
         }
-        syncErrors.push(err instanceof Error ? err.message : String(err))
+        // Prod shows a generic message (don't leak internal error text into
+        // form errors); the real error still reaches `onValidatorError` (T5.3).
+        syncIssues.push({
+          path: [],
+          message: __DEV__
+            ? err instanceof Error
+              ? err.message
+              : String(err)
+            : 'Validation failed',
+        })
       }
     }
 
-    if (syncErrors.length > 0) {
+    if (syncIssues.length > 0) {
       batch(() => {
-        this.topLevelErrors$.set(syncErrors)
+        this.lastFormErrorTargets = routeFormIssues(
+          this,
+          syncIssues,
+          this.topLevelErrors$,
+          this.lastFormErrorTargets,
+        )
         this.topLevelValidating$.set(false)
       })
       return
@@ -776,25 +1083,40 @@ class FieldArrayImpl<I extends Field<any> | Form<any>> implements FieldArray<I>
 
     if (asyncPromises.length === 0) {
       batch(() => {
-        this.topLevelErrors$.set([])
+        this.lastFormErrorTargets = routeFormIssues(
+          this,
+          [],
+          this.topLevelErrors$,
+          this.lastFormErrorTargets,
+        )
         this.topLevelValidating$.set(false)
       })
       return
     }
 
     batch(() => {
-      this.topLevelErrors$.set([])
+      this.lastFormErrorTargets = routeFormIssues(
+        this,
+        [],
+        this.topLevelErrors$,
+        this.lastFormErrorTargets,
+      )
       this.topLevelValidating$.set(true)
     })
 
     Promise.allSettled(asyncPromises).then((results) => {
       if (myId !== this.currentValidatorRun || this.disposed) return
-      const errs: string[] = []
+      const issues: FormIssue[] = []
       for (const r of results) {
-        if (r.status === 'fulfilled' && r.value != null) errs.push(r.value)
+        if (r.status === 'fulfilled') appendIssues(issues, r.value)
       }
       batch(() => {
-        this.topLevelErrors$.set(errs)
+        this.lastFormErrorTargets = routeFormIssues(
+          this,
+          issues,
+          this.topLevelErrors$,
+          this.lastFormErrorTargets,
+        )
         this.topLevelValidating$.set(false)
       })
     })

package/src/forms/index.ts

@@ -1,12 +1,14 @@
+export type { FieldTransform, ValidateOn } from './field'
 export type { StandardSchemaV1 } from './standard-schema'
 export { isStandardSchema } from './standard-schema'
-export type { Validator } from './types'
+export type { FormIssue, Validator, ValidatorResult } from './types'
 export {
   email,
   max,
   maxLength,
   min,
   minLength,
+  mustBeTrue,
   pattern,
   required,
   validator,

package/src/forms/types.ts

@@ -1 +1,27 @@
-export type Validator<T> = (value: T, signal: AbortSignal) => string | null | Promise<string | null>
+/**
+ * A single validation issue, optionally targeting a descendant of a form tree.
+ *
+ * - An **empty** `path` means the node the validator is attached to itself —
+ *   for a leaf `Field` that's the field; for a `Form` / `FieldArray` it's the
+ *   node's `topLevelErrors`.
+ * - A **non-empty** `path` routes the `message` to the matching descendant
+ *   (`Form` walks keys, `FieldArray` walks numeric indices). Unresolvable
+ *   paths fall back to the owning node's `topLevelErrors` rather than vanishing.
+ *
+ * Segments are object keys (`string`) or array indices (`number`). Returned by
+ * form-level validators (cross-field rules) and by the Standard-Schema
+ * `validator(...)` adapter, which maps each `issue.path` here. See SPEC §8.3.
+ */
+export type FormIssue = { path: (string | number)[]; message: string }
+
+/**
+ * What a {@link Validator} may return synchronously. A plain `string` is a
+ * message on the node itself (equivalent to a `FormIssue` with an empty path);
+ * `null` means "no error"; a `FormIssue[]` targets specific descendants.
+ */
+export type ValidatorResult = string | null | FormIssue[]
+
+export type Validator<T> = (
+  value: T,
+  signal: AbortSignal,
+) => ValidatorResult | Promise<ValidatorResult>