@kontsedal/olas-core 0.0.5 → 0.1.0

package/src/forms/field.ts

@@ -10,7 +10,55 @@ import {
   signal,
 } from '../signals'
 import { isAbortError } from '../utils'
-import type { Validator } from './types'
+import type { Validator, ValidatorResult } from './types'
+
+/**
+ * Flatten a single validator result to plain message strings for a leaf field.
+ * A leaf has no descendants, so a `FormIssue[]`'s paths don't route anywhere —
+ * every issue's `message` applies to this field. `null` → no messages.
+ */
+function messagesFromResult(result: ValidatorResult): string[] {
+  if (result == null) return []
+  if (typeof result === 'string') return [result]
+  return result.map((issue) => issue.message)
+}
+
+/**
+ * Structural equality used by `Field.set` to decide whether a write returns
+ * the field to its initial value (clearing `isDirty`). Cheap path for
+ * primitives + `Object.is`; deep walk for arrays and plain objects. Class
+ * instances, Map, Set, Date fall back to reference identity — same trade-off
+ * `structural-share.ts` makes for cache data.
+ */
+function isStructurallyEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b) || a.length !== b.length) return false
+    for (let i = 0; i < a.length; i++) {
+      if (!isStructurallyEqual(a[i], b[i])) return false
+    }
+    return true
+  }
+  if (Array.isArray(b)) return false
+  const protoA = Object.getPrototypeOf(a)
+  const protoB = Object.getPrototypeOf(b)
+  // Plain-object guard only — class instances aren't safe to walk by keys.
+  if (protoA !== Object.prototype && protoA !== null) return false
+  if (protoB !== Object.prototype && protoB !== null) return false
+  const keysA = Object.keys(a as Record<string, unknown>)
+  const keysB = Object.keys(b as Record<string, unknown>)
+  if (keysA.length !== keysB.length) return false
+  for (const k of keysA) {
+    if (!Object.hasOwn(b as object, k)) return false
+    if (
+      !isStructurallyEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k])
+    ) {
+      return false
+    }
+  }
+  return true
+}
 
 /**
  * Hook attached by `ctx.form` (or `createForm`) so a Field can publish
@@ -34,12 +82,34 @@ export type FieldDevtoolsOwner = {
  */
 export type ValidatorErrorReporter = (err: unknown) => void
 
+/**
+ * When a field's validators are first allowed to run.
+ *
+ * - `'change'` (default) — validators run on every `set()`. Matches the
+ *   current behavior, ideal for "type and see errors live."
+ * - `'blur'` — first run is gated on `markTouched()`. After that, subsequent
+ *   value changes do trigger re-validation. UI binding should call
+ *   `markTouched()` on `onBlur`.
+ * - `'submit'` — first run is gated on `revalidate()` / `Form.submit()`.
+ *   After that, subsequent value changes re-validate. Use when you want
+ *   "show errors only after the user explicitly tried to submit."
+ *
+ * `revalidate()` always unlocks the field regardless of mode.
+ */
+export type ValidateOn = 'change' | 'blur' | 'submit'
+
+export type FieldOptions = {
+  onValidatorError?: ValidatorErrorReporter
+  validateOn?: ValidateOn
+}
+
 class FieldImpl<T> implements Field<T> {
   private readonly value$: Signal<T>
   /**
    * Validator-produced errors. The public `errors` getter merges this with
-   * `serverErrors$` so consumers see a single flat array. Kept separate so a
-   * re-run of validators (after a new value) doesn't clobber server errors.
+   * `serverErrors$` and `formErrors$` so consumers see a single flat array.
+   * Kept separate so a re-run of validators (after a new value) doesn't clobber
+   * the other two channels.
    */
   private readonly validatorErrors$: Signal<string[]>
   /**
@@ -47,11 +117,29 @@ class FieldImpl<T> implements Field<T> {
    * `set()`, on `reset()`, or via an explicit `setErrors([])`.
    */
   private readonly serverErrors$: Signal<string[]>
+  /**
+   * Errors routed here by a parent (or ancestor) form-level validator that
+   * targeted this field via a `FormIssue` path — the third error channel
+   * beside validator + server errors (T5.2). Owned by the routing form: cleared
+   * and re-applied on every form-level validation run, so it does NOT clear on
+   * the field's own `set()` (a stale cross-field error survives until the next
+   * form-level run recomputes it). Cleared by `reset()` / `setAsInitial()`.
+   */
+  private readonly formErrors$: Signal<string[]>
   private readonly errors$: Computed<string[]>
   private readonly touched$: Signal<boolean>
   private readonly dirty$: Signal<boolean>
   private readonly validating$: Signal<boolean>
   private readonly isValid$: Computed<boolean>
+  /**
+   * Validity as of the last *settled* validation pass. While a pass is in
+   * flight (`validating$`), `isValid` reads this instead of the live `errors`
+   * — otherwise a `debouncedValidator` would flip `isValid` to `false` on every
+   * keystroke (the async-start clears `validatorErrors$`), strobing a submit
+   * button. Updated only when a pass completes (T5.3). Defaults `true` (an
+   * untouched field with a pending first run reads valid, not invalid).
+   */
+  private readonly lastValid$: Signal<boolean>
   private readonly revalidateTrigger$: Signal<number>
 
   private readonly validators: ReadonlyArray<Validator<T>>
@@ -64,12 +152,15 @@ class FieldImpl<T> implements Field<T> {
   private disposed = false
   private devtoolsOwner: FieldDevtoolsOwner | null = null
   private onValidatorError: ValidatorErrorReporter | null = null
-
-  constructor(
-    initial: T,
-    validators: ReadonlyArray<Validator<T>> = [],
-    options?: { onValidatorError?: ValidatorErrorReporter },
-  ) {
+  private readonly validateOn: ValidateOn
+  /** Reactive gate — when false, the validator effect skips its run. Flipped
+   * on by the relevant trigger for the field's `validateOn` mode. Once on,
+   * stays on for the lifetime of the field (matches RHF's `mode + reValidateMode`
+   * default semantics: after the first activation, subsequent changes
+   * re-validate). `reset()` flips it back to false. */
+  private readonly validateUnlocked$: Signal<boolean>
+
+  constructor(initial: T, validators: ReadonlyArray<Validator<T>> = [], options?: FieldOptions) {
     this.initial = initial
     this.validators = validators
     // Capture the reporter BEFORE the validator effect kicks off so a sync
@@ -77,21 +168,33 @@ class FieldImpl<T> implements Field<T> {
     // disappearing into the effect (`bindValidatorErrorReporter` is a
     // post-construct hook so it can't catch the first run).
     this.onValidatorError = options?.onValidatorError ?? null
+    this.validateOn = options?.validateOn ?? 'change'
     this.value$ = signal(initial)
     this.validatorErrors$ = signal<string[]>([])
     this.serverErrors$ = signal<string[]>([])
+    this.formErrors$ = signal<string[]>([])
     this.touched$ = signal(false)
     this.dirty$ = signal(false)
     this.validating$ = signal(false)
+    this.lastValid$ = signal(true)
     this.revalidateTrigger$ = signal(0)
+    // 'change' mode is unlocked from construction; 'blur' / 'submit' wait
+    // for their trigger so initial typing doesn't surface errors.
+    this.validateUnlocked$ = signal(this.validateOn === 'change')
     this.errors$ = computed(() => {
       const v = this.validatorErrors$.value
       const s = this.serverErrors$.value
-      if (s.length === 0) return v
-      if (v.length === 0) return s
-      return [...v, ...s]
+      const f = this.formErrors$.value
+      if (s.length === 0 && f.length === 0) return v
+      if (v.length === 0 && f.length === 0) return s
+      if (v.length === 0 && s.length === 0) return f
+      return [...v, ...s, ...f]
     })
-    this.isValid$ = computed(() => this.errors$.value.length === 0 && !this.validating$.value)
+    this.isValid$ = computed(() =>
+      // While a validation pass is in flight, hold the last settled validity so
+      // the field doesn't strobe invalid mid-check (T5.3). Otherwise it's live.
+      this.validating$.value ? this.lastValid$.value : this.errors$.value.length === 0,
+    )
 
     if (validators.length > 0) {
       this.validatorDispose = effect(() => {
@@ -121,6 +224,10 @@ class FieldImpl<T> implements Field<T> {
     return this.value$.subscribe(handler)
   }
 
+  subscribeChanges(handler: (value: T) => void): () => void {
+    return this.value$.subscribeChanges(handler)
+  }
+
   // --- Field-only signals ---
   get errors(): ReadSignal<string[]> {
     return this.errors$
@@ -147,7 +254,11 @@ class FieldImpl<T> implements Field<T> {
     if (this.disposed) return
     batch(() => {
       this.value$.set(value)
-      this.dirty$.set(true)
+      // Equality-aware dirty: setting back to initial clears dirty, so
+      // "Disable Save when unchanged" UIs work without consumer code. Uses
+      // a structural comparison for primitive / shallow-object / array
+      // payloads; falls back to reference identity for class instances.
+      this.dirty$.set(!isStructurallyEqual(value, this.initial))
       // Server errors are pinned externally and survive validator re-runs,
       // but they MUST clear when the user edits the field — otherwise a
       // server error like "username taken" would persist after the user
@@ -162,6 +273,19 @@ class FieldImpl<T> implements Field<T> {
     this.serverErrors$.set(next)
   }
 
+  /**
+   * Internal — set the parent-form-validator error channel (`formErrors$`).
+   * Called by the owning form's issue router when a `FormIssue` path resolves
+   * to this field. Guards against churning the signal when nothing changes so
+   * a whole-tree clear pass doesn't wake unrelated subscribers. See T5.2 /
+   * `routeFormIssues` in `form.ts`.
+   */
+  setFormErrors(errors: ReadonlyArray<string>): void {
+    if (this.disposed) return
+    if (this.formErrors$.peek().length === 0 && errors.length === 0) return
+    this.formErrors$.set(errors.length === 0 ? [] : [...errors])
+  }
+
   /**
    * Reseat the field as if this value had been its constructor `initial`.
    * Sets the value, re-anchors `reset()`'s target, and does NOT mark dirty.
@@ -175,6 +299,13 @@ class FieldImpl<T> implements Field<T> {
     batch(() => {
       this.value$.set(value)
       this.dirty$.set(false)
+      // Re-seating from a fresh server payload means the previous server
+      // response is no longer relevant. Without clearing, errors like
+      // "username taken" persist across a successful re-hydrate.
+      if (this.serverErrors$.peek().length > 0) this.serverErrors$.set([])
+      // A stale cross-field error from the old value is likewise irrelevant;
+      // the next form-level run recomputes it against the fresh value.
+      if (this.formErrors$.peek().length > 0) this.formErrors$.set([])
     })
   }
 
@@ -188,17 +319,30 @@ class FieldImpl<T> implements Field<T> {
       this.touched$.set(false)
       this.validatorErrors$.set([])
       this.serverErrors$.set([])
+      this.formErrors$.set([])
       this.validating$.set(false)
+      // Re-lock validation if the field was in blur/submit mode — a reset
+      // means we're back to a clean slate, so the user shouldn't immediately
+      // see errors again until they re-trigger.
+      if (this.validateOn !== 'change') this.validateUnlocked$.set(false)
     })
   }
 
   markTouched(): void {
     if (this.disposed) return
     this.touched$.set(true)
+    // 'blur' mode unlocks validation on first blur. Subsequent set() calls
+    // then re-validate live (matches RHF `reValidateMode: onChange` default).
+    if (this.validateOn === 'blur' && !this.validateUnlocked$.peek()) {
+      this.validateUnlocked$.set(true)
+    }
   }
 
   async revalidate(): Promise<boolean> {
     if (this.disposed) return this.isValid$.peek()
+    // `revalidate()` always unlocks the field — same trigger as a successful
+    // submit attempt. 'submit' mode uses this as its first activation.
+    if (!this.validateUnlocked$.peek()) this.validateUnlocked$.set(true)
     // Bump the trigger to force re-run.
     this.revalidateTrigger$.update((n) => n + 1)
     await this.waitUntilSettled()
@@ -258,6 +402,17 @@ class FieldImpl<T> implements Field<T> {
     // Track value and revalidate trigger.
     const value = this.value$.value
     void this.revalidateTrigger$.value
+    // Track the gate so the effect re-runs when the field becomes unlocked.
+    // While locked, skip the pass entirely — errors stay empty, the field
+    // reads as valid, no async work starts.
+    if (!this.validateUnlocked$.value) {
+      batch(() => {
+        if (this.validatorErrors$.peek().length > 0) this.validatorErrors$.set([])
+        if (this.validating$.peek()) this.validating$.set(false)
+        this.lastValid$.set(this.errors$.peek().length === 0)
+      })
+      return
+    }
 
     // Abort previous in-flight run.
     this.currentAbort?.abort()
@@ -266,7 +421,7 @@ class FieldImpl<T> implements Field<T> {
     const myId = ++this.runId
 
     const syncErrors: string[] = []
-    const asyncPromises: Promise<string | null>[] = []
+    const asyncPromises: Promise<ValidatorResult>[] = []
 
     for (const validator of this.validators) {
       try {
@@ -276,20 +431,28 @@ class FieldImpl<T> implements Field<T> {
           // with a thrown error (rare but legal) — the catch-handler in
           // `Promise.allSettled` covers true async rejection.
           asyncPromises.push(result)
-        } else if (result != null) {
-          syncErrors.push(result)
+        } else {
+          // A Standard-Schema validator returns `FormIssue[]`; a stdlib one
+          // returns `string | null`. Flatten both to messages (a leaf field
+          // has no descendants to route issue paths to).
+          const msgs = messagesFromResult(result)
+          if (msgs.length > 0) syncErrors.push(...msgs)
         }
       } catch (err) {
         // A buggy validator that throws synchronously: surface it twice.
-        // (1) Route through `onError` so the user knows something is wrong.
-        // (2) Convert to a validation error string so the field reads invalid
-        //     until the bug is fixed (don't pretend everything's OK).
+        // (1) Route through `onError` so the developer knows something is wrong.
+        // (2) Mark the field invalid until the bug is fixed (don't pretend OK).
+        // In prod the user-visible message is generic — leaking an internal
+        // error's text into form errors is a footgun; the real error still
+        // reaches `onValidatorError` (T5.3). Dev keeps the message for DX.
         try {
           this.onValidatorError?.(err)
         } catch {
           // The reporter must not propagate.
         }
-        syncErrors.push(err instanceof Error ? err.message : String(err))
+        syncErrors.push(
+          __DEV__ ? (err instanceof Error ? err.message : String(err)) : 'Validation failed',
+        )
       }
     }
 
@@ -297,6 +460,7 @@ class FieldImpl<T> implements Field<T> {
       batch(() => {
         this.validatorErrors$.set(syncErrors)
         this.validating$.set(false)
+        this.lastValid$.set(this.errors$.peek().length === 0)
       })
       this.emitValidated(false, syncErrors)
       return
@@ -306,6 +470,7 @@ class FieldImpl<T> implements Field<T> {
       batch(() => {
         this.validatorErrors$.set([])
         this.validating$.set(false)
+        this.lastValid$.set(this.errors$.peek().length === 0)
       })
       this.emitValidated(true, [])
       return
@@ -321,7 +486,7 @@ class FieldImpl<T> implements Field<T> {
       const asyncErrors: string[] = []
       for (const r of results) {
         if (r.status === 'fulfilled') {
-          if (r.value != null) asyncErrors.push(r.value)
+          asyncErrors.push(...messagesFromResult(r.value))
         } else if (!isAbortError(r.reason)) {
           const msg = r.reason instanceof Error ? r.reason.message : String(r.reason)
           asyncErrors.push(msg)
@@ -330,6 +495,7 @@ class FieldImpl<T> implements Field<T> {
       batch(() => {
         this.validatorErrors$.set(asyncErrors)
         this.validating$.set(false)
+        this.lastValid$.set(this.errors$.peek().length === 0)
       })
       this.emitValidated(asyncErrors.length === 0, asyncErrors)
     })
@@ -367,20 +533,48 @@ export function bindFieldValidatorErrorReporter<T>(
 export function createField<T>(
   initial: T,
   validators?: ReadonlyArray<Validator<T>>,
-  options?: { onValidatorError?: ValidatorErrorReporter },
+  options?: FieldOptions,
 ): Field<T> {
   return new FieldImpl(initial, validators, options)
 }
 
+/**
+ * A bidirectional `T ↔ string` transform, suitable for HTML input bindings
+ * where DOM values are always strings.
+ *
+ * `parse(raw)` converts the input's string value into the field's type;
+ * `format(value)` converts the field's typed value back into a string for
+ * the input. Both must be pure — `useFieldInput` calls them on every
+ * render and every input event respectively.
+ *
+ * ```ts
+ * const numberTransform: FieldTransform<number> = {
+ *   parse: (raw) => Number(raw),
+ *   format: (v) => String(v),
+ * }
+ * ```
+ */
+export type FieldTransform<T> = {
+  parse: (raw: string) => T
+  format: (value: T) => string
+}
+
 /**
  * Wrap an async validator with a debounce. The debounce timer resets on every
  * value change. While debouncing or the request is in flight, the field's
- * `isValidating` is true and `isValid` is false (treat-as-invalid-until-proven-valid).
+ * `isValidating` is true and `isValid` HOLDS its last settled value (T5.3) — so
+ * editing an already-valid field doesn't strobe a submit button to disabled on
+ * every keystroke. A field with no prior settled validation defaults to valid.
  */
 export function debouncedValidator<T>(
   fn: (value: T, signal: AbortSignal) => Promise<string | null>,
   ms: number,
-): Validator<T> {
+): (value: T, signal: AbortSignal) => Promise<string | null> {
+  // Precise return (not the wide `Validator<T>`): the wrapped `fn` only ever
+  // yields `string | null`, so callers that invoke the debounced validator
+  // directly — e.g. surfacing its result in a signal — keep that narrow type
+  // after `Validator<T>` was widened to allow `FormIssue[]` (T5.2). Still
+  // assignable wherever a `Validator<T>` is expected.
   return (value, signal) =>
     new Promise<string | null>((resolve, reject) => {
       if (signal.aborted) {

package/src/forms/form-types.ts

@@ -89,6 +89,12 @@ export type Form<S extends FormSchema> = {
   readonly isDirty: ReadSignal<boolean>
   readonly touched: ReadSignal<boolean>
   readonly isValidating: ReadSignal<boolean>
+  /**
+   * Dotted paths of every leaf whose `isDirty` is true. Useful for PATCH
+   * payloads and "highlight changed inputs" UIs. Field paths use dot
+   * notation; array items use bracket notation (`items[0].title`).
+   */
+  readonly dirtyFields: ReadSignal<string[]>
 
   /**
    * `true` while a `submit(...)` is in flight. Clears when the handler
@@ -117,6 +123,13 @@ export type Form<S extends FormSchema> = {
   resetWithInitial(partial: DeepPartial<FormValue<S>>): void
   /** Reset every leaf to its initial value. */
   reset(): void
+  /**
+   * Reset a named subtree to its initial. Path uses the same dotted /
+   * bracket notation as `setErrors` / `flatErrors`. Unlike `Form.set({foo:
+   * undefined})` (which is "leave alone"), this is the explicit
+   * "clear this subtree" gesture. Pass `''` to reset the whole form.
+   */
+  clearSubtree(path: string): void
   /** Mark every leaf as touched (so error messages appear). */
   markAllTouched(): void
   /** Re-run every leaf's validators. Resolves with true if all leaves are valid. */
@@ -127,14 +140,14 @@ export type Form<S extends FormSchema> = {
    * `submitError`. Returns `{ ok, data?, error? }` — see `FormImpl.submit`
    * for the full contract.
    */
-  submit(
-    handler: (value: FormValue<S>) => unknown | Promise<unknown>,
+  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 }>
   /**
    * Pin externally-sourced errors on specific fields. Keys are dot-separated
    * paths through nested forms / field arrays (numeric segments are array