@kontsedal/olas-core 0.0.1-rc.0

package/src/forms/field.ts

@@ -0,0 +1,303 @@
+import type { Field } from '../controller/types'
+import type { DevtoolsEmitter } from '../devtools'
+import {
+  batch,
+  type Computed,
+  computed,
+  effect,
+  type ReadSignal,
+  type Signal,
+  signal,
+} from '../signals'
+import { isAbortError } from '../utils'
+import type { Validator } from './types'
+
+/**
+ * Hook attached by `ctx.form` (or `createForm`) so a Field can publish
+ * `field:validated` devtools events with its owning controller path + the
+ * field's name within the form schema. See devtools §20.9 and FieldImpl.bind.
+ */
+export type FieldDevtoolsOwner = {
+  controllerPath: readonly string[]
+  fieldName: string
+  emitter: DevtoolsEmitter
+}
+
+class FieldImpl<T> implements Field<T> {
+  private readonly value$: Signal<T>
+  private readonly errors$: Signal<string[]>
+  private readonly touched$: Signal<boolean>
+  private readonly dirty$: Signal<boolean>
+  private readonly validating$: Signal<boolean>
+  private readonly isValid$: Computed<boolean>
+  private readonly revalidateTrigger$: Signal<number>
+
+  private readonly validators: ReadonlyArray<Validator<T>>
+  /** The value `reset()` returns to. Mutated by `setAsInitial()` so a form
+   * initialized from server data resets to *that* data, not the empty seed. */
+  private initial: T
+  private validatorDispose: (() => void) | null = null
+  private currentAbort: AbortController | null = null
+  private runId = 0
+  private disposed = false
+  private devtoolsOwner: FieldDevtoolsOwner | null = null
+
+  constructor(initial: T, validators: ReadonlyArray<Validator<T>> = []) {
+    this.initial = initial
+    this.validators = validators
+    this.value$ = signal(initial)
+    this.errors$ = signal<string[]>([])
+    this.touched$ = signal(false)
+    this.dirty$ = signal(false)
+    this.validating$ = signal(false)
+    this.revalidateTrigger$ = signal(0)
+    this.isValid$ = computed(() => this.errors$.value.length === 0 && !this.validating$.value)
+
+    if (validators.length > 0) {
+      this.validatorDispose = effect(() => {
+        this.runValidators()
+      })
+    }
+  }
+
+  // --- ReadSignal<T> ---
+  get value(): T {
+    return this.value$.value
+  }
+
+  peek(): T {
+    return this.value$.peek()
+  }
+
+  subscribe(handler: (value: T) => void): () => void {
+    return this.value$.subscribe(handler)
+  }
+
+  // --- Field-only signals ---
+  get errors(): ReadSignal<string[]> {
+    return this.errors$
+  }
+
+  get isValid(): ReadSignal<boolean> {
+    return this.isValid$
+  }
+
+  get isDirty(): ReadSignal<boolean> {
+    return this.dirty$
+  }
+
+  get touched(): ReadSignal<boolean> {
+    return this.touched$
+  }
+
+  get isValidating(): ReadSignal<boolean> {
+    return this.validating$
+  }
+
+  // --- mutating methods ---
+  set(value: T): void {
+    if (this.disposed) return
+    this.value$.set(value)
+    this.dirty$.set(true)
+  }
+
+  /**
+   * 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.
+   * Used by `Form` when applying its own `initial` (in the constructor and
+   * on `reset()`), so server-loaded forms don't start dirty. Internal-ish —
+   * exposed for `Form`'s use, not for user code that just wants to write.
+   */
+  setAsInitial(value: T): void {
+    if (this.disposed) return
+    this.initial = value
+    batch(() => {
+      this.value$.set(value)
+      this.dirty$.set(false)
+    })
+  }
+
+  reset(): void {
+    if (this.disposed) return
+    this.currentAbort?.abort()
+    this.currentAbort = null
+    batch(() => {
+      this.value$.set(this.initial)
+      this.dirty$.set(false)
+      this.touched$.set(false)
+      this.errors$.set([])
+      this.validating$.set(false)
+    })
+  }
+
+  markTouched(): void {
+    if (this.disposed) return
+    this.touched$.set(true)
+  }
+
+  async revalidate(): Promise<boolean> {
+    if (this.disposed) return this.isValid$.peek()
+    // Bump the trigger to force re-run.
+    this.revalidateTrigger$.update((n) => n + 1)
+    await this.waitUntilSettled()
+    return this.isValid$.peek()
+  }
+
+  dispose(): void {
+    if (this.disposed) return
+    this.disposed = true
+    this.validatorDispose?.()
+    this.validatorDispose = null
+    this.currentAbort?.abort()
+    this.currentAbort = null
+    this.devtoolsOwner = null
+  }
+
+  /**
+   * Bind this field to a devtools owner. Each subsequent validation pass
+   * publishes a `field:validated` event with the supplied path + name.
+   * Idempotent — calling again replaces the owner. Internal: called by
+   * `createForm` / `createFieldArray` so the form's keys reach the panel.
+   */
+  bindDevtoolsOwner(owner: FieldDevtoolsOwner | null): void {
+    this.devtoolsOwner = owner
+  }
+
+  private emitValidated(valid: boolean, errors: readonly string[]): void {
+    if (!__DEV__) return
+    const owner = this.devtoolsOwner
+    if (owner === null) return
+    owner.emitter.emit({
+      type: 'field:validated',
+      path: owner.controllerPath,
+      field: owner.fieldName,
+      valid,
+      errors: [...errors],
+    })
+  }
+
+  // --- internal ---
+  private async waitUntilSettled(): Promise<void> {
+    // If a validation pass is in progress, wait for validating$ to become false.
+    if (!this.validating$.peek()) return
+    await new Promise<void>((resolve) => {
+      const unsub = this.validating$.subscribe((v) => {
+        if (!v) {
+          unsub()
+          resolve()
+        }
+      })
+    })
+  }
+
+  private runValidators(): void {
+    if (this.disposed) return
+
+    // Track value and revalidate trigger.
+    const value = this.value$.value
+    void this.revalidateTrigger$.value
+
+    // Abort previous in-flight run.
+    this.currentAbort?.abort()
+    const abort = new AbortController()
+    this.currentAbort = abort
+    const myId = ++this.runId
+
+    const syncErrors: string[] = []
+    const asyncPromises: Promise<string | null>[] = []
+
+    for (const validator of this.validators) {
+      const result = validator(value, abort.signal)
+      if (result instanceof Promise) {
+        asyncPromises.push(result)
+      } else if (result != null) {
+        syncErrors.push(result)
+      }
+    }
+
+    if (syncErrors.length > 0) {
+      batch(() => {
+        this.errors$.set(syncErrors)
+        this.validating$.set(false)
+      })
+      this.emitValidated(false, syncErrors)
+      return
+    }
+
+    if (asyncPromises.length === 0) {
+      batch(() => {
+        this.errors$.set([])
+        this.validating$.set(false)
+      })
+      this.emitValidated(true, [])
+      return
+    }
+
+    batch(() => {
+      this.errors$.set([])
+      this.validating$.set(true)
+    })
+
+    Promise.allSettled(asyncPromises).then((results) => {
+      if (myId !== this.runId || this.disposed) return
+      const asyncErrors: string[] = []
+      for (const r of results) {
+        if (r.status === 'fulfilled') {
+          if (r.value != null) asyncErrors.push(r.value)
+        } else if (!isAbortError(r.reason)) {
+          const msg = r.reason instanceof Error ? r.reason.message : String(r.reason)
+          asyncErrors.push(msg)
+        }
+      }
+      batch(() => {
+        this.errors$.set(asyncErrors)
+        this.validating$.set(false)
+      })
+      this.emitValidated(asyncErrors.length === 0, asyncErrors)
+    })
+  }
+}
+
+/**
+ * Internal — type guard / accessor for the binding hook. Avoids exposing
+ * `bindDevtoolsOwner` on the public `Field<T>` type while letting `createForm`
+ * call it via a structural check.
+ */
+export function bindFieldDevtoolsOwner<T>(field: Field<T>, owner: FieldDevtoolsOwner | null): void {
+  const impl = field as { bindDevtoolsOwner?: (o: FieldDevtoolsOwner | null) => void }
+  if (typeof impl.bindDevtoolsOwner === 'function') {
+    impl.bindDevtoolsOwner(owner)
+  }
+}
+
+export function createField<T>(initial: T, validators?: ReadonlyArray<Validator<T>>): Field<T> {
+  return new FieldImpl(initial, validators)
+}
+
+/**
+ * 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).
+ */
+export function debouncedValidator<T>(
+  fn: (value: T, signal: AbortSignal) => Promise<string | null>,
+  ms: number,
+): Validator<T> {
+  return (value, signal) =>
+    new Promise<string | null>((resolve, reject) => {
+      if (signal.aborted) {
+        reject(new DOMException('Aborted', 'AbortError'))
+        return
+      }
+      const timer = setTimeout(() => {
+        signal.removeEventListener('abort', onAbort)
+        fn(value, signal).then(resolve, reject)
+      }, ms)
+      const onAbort = () => {
+        clearTimeout(timer)
+        signal.removeEventListener('abort', onAbort)
+        reject(new DOMException('Aborted', 'AbortError'))
+      }
+      signal.addEventListener('abort', onAbort, { once: true })
+    })
+}

package/src/forms/form-types.ts

@@ -0,0 +1,130 @@
+import type { Field } from '../controller/types'
+import type { ReadSignal } from '../signals/types'
+import type { Validator } from './types'
+
+export type FormSchema = {
+  [key: string]: Field<any> | Form<any> | FieldArray<any>
+}
+
+export type FormValue<S extends FormSchema> = {
+  [K in keyof S]: S[K] extends Field<infer T>
+    ? T
+    : S[K] extends Form<infer SS>
+      ? FormValue<SS>
+      : S[K] extends FieldArray<infer I>
+        ? FieldArrayValue<I>
+        : never
+}
+
+export type FormErrors<S extends FormSchema> = {
+  [K in keyof S]?: S[K] extends Field<any>
+    ? string[] | undefined
+    : S[K] extends Form<infer SS>
+      ? FormErrors<SS>
+      : S[K] extends FieldArray<infer I>
+        ? Array<FieldArrayItemErrors<I> | undefined>
+        : never
+}
+
+export type FieldArrayValue<I> =
+  I extends Field<infer T> ? T[] : I extends Form<infer S> ? FormValue<S>[] : never
+
+export type FieldArrayItemErrors<I> =
+  I extends Field<any> ? string[] : I extends Form<infer S> ? FormErrors<S> : never
+
+export type ItemInitial<I> =
+  I extends Field<infer T> ? T : I extends Form<infer S> ? DeepPartial<FormValue<S>> : never
+
+export type DeepPartial<T> = T extends object
+  ? T extends ReadonlyArray<infer U>
+    ? ReadonlyArray<DeepPartial<U>>
+    : { [K in keyof T]?: DeepPartial<T[K]> }
+  : T
+
+export type FormValidator<S extends FormSchema> = Validator<FormValue<S>>
+export type FieldArrayValidator<I> = Validator<FieldArrayValue<I>>
+
+export type FormOptions<S extends FormSchema> = {
+  initial?: (() => DeepPartial<FormValue<S>> | undefined) | DeepPartial<FormValue<S>>
+  validators?: FormValidator<S>[]
+}
+
+export type FieldArrayOptions<I> = {
+  initial?: Array<ItemInitial<I>>
+  validators?: FieldArrayValidator<I>[]
+}
+
+/**
+ * A nested form. Created via `ctx.form(schema, options?)`. `value` aggregates
+ * every leaf into the structurally-typed `FormValue<S>`; `errors` mirrors that
+ * shape with `string[] | undefined`. `flatErrors` is a flattened view useful
+ * for rendering a single error summary. Spec §8, §20.7.
+ *
+ * IMPORTANT: `Form.value` is a `ReadSignal<FormValue<S>>` while `Field.value`
+ * is `T` directly — different shapes. See `.wiki/pitfalls/field-value-shape.md`.
+ */
+export type Form<S extends FormSchema> = {
+  readonly fields: { [K in keyof S]: S[K] }
+  readonly value: ReadSignal<FormValue<S>>
+  readonly errors: ReadSignal<FormErrors<S>>
+  readonly topLevelErrors: ReadSignal<string[]>
+  readonly flatErrors: ReadSignal<Array<{ path: string; errors: string[] }>>
+  readonly isValid: ReadSignal<boolean>
+  readonly isDirty: ReadSignal<boolean>
+  readonly touched: ReadSignal<boolean>
+  readonly isValidating: ReadSignal<boolean>
+
+  /** Deep-merge a partial value into the form, batched. */
+  set(partial: DeepPartial<FormValue<S>>): void
+  /**
+   * Re-seat the form's leaves from `partial` as their new initials —
+   * each leaf calls `setAsInitial(value)`, so `isDirty` stays false and a
+   * subsequent `reset()` returns *here*. Internal-ish but exported for
+   * `Form`-traversal code (nested-form initial application).
+   */
+  resetWithInitial(partial: DeepPartial<FormValue<S>>): void
+  /** Reset every leaf to its initial value. */
+  reset(): 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. */
+  validate(): Promise<boolean>
+  /** Idempotent. Called by the owning controller's dispose. */
+  dispose(): void
+}
+
+/**
+ * A dynamically-sized list of `Field` or `Form` items. Created via
+ * `ctx.fieldArray(itemFactory, options?)`. The factory is invoked per
+ * insertion. Spec §8, §20.7.
+ */
+export type FieldArray<I extends Field<any> | Form<any>> = {
+  readonly items: ReadSignal<ReadonlyArray<I>>
+  readonly value: ReadSignal<FieldArrayValue<I>>
+  readonly errors: ReadSignal<Array<FieldArrayItemErrors<I> | undefined>>
+  readonly topLevelErrors: ReadSignal<string[]>
+  readonly isValid: ReadSignal<boolean>
+  readonly isDirty: ReadSignal<boolean>
+  readonly touched: ReadSignal<boolean>
+  readonly isValidating: ReadSignal<boolean>
+  readonly size: ReadSignal<number>
+
+  add(initial?: ItemInitial<I>): void
+  insert(index: number, initial?: ItemInitial<I>): void
+  remove(index: number): void
+  move(from: number, to: number): void
+  at(index: number): I | undefined
+  clear(): void
+
+  reset(): void
+  markAllTouched(): void
+  validate(): Promise<boolean>
+  dispose(): void
+}
+
+// Brand markers used by traversal logic to distinguish primitive types.
+export const FORM_BRAND = Symbol.for('olas.form')
+export const FIELD_ARRAY_BRAND = Symbol.for('olas.fieldArray')
+
+export type FormBranded = { readonly [FORM_BRAND]: true }
+export type FieldArrayBranded = { readonly [FIELD_ARRAY_BRAND]: true }