@pyreon/form 0.0.1

package/src/types.ts

@@ -0,0 +1,116 @@
+import type { Signal, Computed } from '@pyreon/reactivity'
+
+export type ValidationError = string | undefined
+
+/**
+ * A reactive value that can be read by calling it.
+ * Both `Signal<T>` and `Computed<T>` satisfy this interface.
+ */
+export type Accessor<T> = Signal<T> | Computed<T>
+
+/**
+ * Field validator function. Receives the field value and all current form values
+ * for cross-field validation.
+ */
+export type ValidateFn<T, TValues = Record<string, unknown>> = (
+  value: T,
+  allValues: TValues,
+) => ValidationError | Promise<ValidationError>
+
+export type SchemaValidateFn<TValues> = (
+  values: TValues,
+) =>
+  | Partial<Record<keyof TValues, ValidationError>>
+  | Promise<Partial<Record<keyof TValues, ValidationError>>>
+
+export interface FieldState<T = unknown> {
+  /** Current field value. */
+  value: Signal<T>
+  /** Field error message (undefined if no error). */
+  error: Signal<ValidationError>
+  /** Whether the field has been blurred at least once. */
+  touched: Signal<boolean>
+  /** Whether the field value differs from its initial value. */
+  dirty: Signal<boolean>
+  /** Set the field value. */
+  setValue: (value: T) => void
+  /** Mark the field as touched (typically on blur). */
+  setTouched: () => void
+  /** Reset the field to its initial value and clear error/touched/dirty. */
+  reset: () => void
+}
+
+/** Props returned by `register()` for binding an input element. */
+export interface FieldRegisterProps<T> {
+  value: Signal<T>
+  onInput: (e: Event) => void
+  onBlur: () => void
+  checked?: Accessor<boolean>
+}
+
+export interface FormState<TValues extends Record<string, unknown>> {
+  /** Individual field states keyed by field name. */
+  fields: { [K in keyof TValues]: FieldState<TValues[K]> }
+  /** Whether the form is currently being submitted. */
+  isSubmitting: Signal<boolean>
+  /** Whether async validation is currently running. */
+  isValidating: Signal<boolean>
+  /** Whether any field has an error (computed — read-only). */
+  isValid: Accessor<boolean>
+  /** Whether any field value differs from its initial value (computed — read-only). */
+  isDirty: Accessor<boolean>
+  /** Number of times the form has been submitted. */
+  submitCount: Signal<number>
+  /** Error thrown by onSubmit (undefined if no error). */
+  submitError: Signal<unknown>
+  /** All current form values as a plain object. */
+  values: () => TValues
+  /** All current errors as a record. */
+  errors: () => Partial<Record<keyof TValues, ValidationError>>
+  /** Set a single field's value. */
+  setFieldValue: <K extends keyof TValues>(field: K, value: TValues[K]) => void
+  /** Set a single field's error (e.g. from server-side validation). */
+  setFieldError: (field: keyof TValues, error: ValidationError) => void
+  /** Set multiple field errors at once (e.g. from server-side validation). */
+  setErrors: (errors: Partial<Record<keyof TValues, ValidationError>>) => void
+  /** Clear all field errors. */
+  clearErrors: () => void
+  /** Reset a single field to its initial value. */
+  resetField: (field: keyof TValues) => void
+  /**
+   * Returns props for binding an input element to a field.
+   * For text/select: includes `value` signal, `onInput`, and `onBlur`.
+   * For checkboxes: pass `{ type: 'checkbox' }` to also get a `checked` signal.
+   * For numbers: pass `{ type: 'number' }` to use `valueAsNumber` on input.
+   */
+  register: <K extends keyof TValues & string>(
+    field: K,
+    options?: { type?: 'checkbox' | 'number' },
+  ) => FieldRegisterProps<TValues[K]>
+  /**
+   * Submit handler — runs validation, then calls onSubmit if valid.
+   * Can be called directly or as a form event handler (calls preventDefault).
+   */
+  handleSubmit: (e?: Event) => Promise<void>
+  /** Reset all fields to initial values. */
+  reset: () => void
+  /** Validate all fields and return whether the form is valid. */
+  validate: () => Promise<boolean>
+}
+
+export interface UseFormOptions<TValues extends Record<string, unknown>> {
+  /** Initial values for each field. */
+  initialValues: TValues
+  /** Called with validated values on successful submit. */
+  onSubmit: (values: TValues) => void | Promise<void>
+  /** Per-field validators. Receives field value and all form values. */
+  validators?: Partial<{
+    [K in keyof TValues]: ValidateFn<TValues[K], TValues>
+  }>
+  /** Schema-level validator (runs after field validators). */
+  schema?: SchemaValidateFn<TValues>
+  /** When to validate: 'blur' (default), 'change', or 'submit'. */
+  validateOn?: 'blur' | 'change' | 'submit'
+  /** Debounce delay in ms for validators (useful for async validators). */
+  debounceMs?: number
+}

package/src/use-field-array.ts

@@ -0,0 +1,117 @@
+import { signal, computed } from '@pyreon/reactivity'
+import type { Signal, Computed } from '@pyreon/reactivity'
+
+export interface FieldArrayItem<T> {
+  /** Stable key for keyed rendering. */
+  key: number
+  /** Reactive value for this item. */
+  value: Signal<T>
+}
+
+export interface UseFieldArrayResult<T> {
+  /** Reactive list of items with stable keys. */
+  items: Signal<FieldArrayItem<T>[]>
+  /** Number of items. */
+  length: Computed<number>
+  /** Append a new item to the end. */
+  append: (value: T) => void
+  /** Prepend a new item to the start. */
+  prepend: (value: T) => void
+  /** Insert an item at the given index. */
+  insert: (index: number, value: T) => void
+  /** Remove the item at the given index. */
+  remove: (index: number) => void
+  /** Update the value of an item at the given index. */
+  update: (index: number, value: T) => void
+  /** Move an item from one index to another. */
+  move: (from: number, to: number) => void
+  /** Swap two items by index. */
+  swap: (indexA: number, indexB: number) => void
+  /** Replace all items. */
+  replace: (values: T[]) => void
+  /** Get all current values as a plain array. */
+  values: () => T[]
+}
+
+/**
+ * Manage a dynamic array of form fields with stable keys.
+ *
+ * @example
+ * const tags = useFieldArray<string>([])
+ * tags.append('typescript')
+ * tags.append('pyreon')
+ * // tags.items() — array of { key, value } for keyed rendering
+ */
+export function useFieldArray<T>(initial: T[] = []): UseFieldArrayResult<T> {
+  let nextKey = 0
+  const makeItem = (value: T): FieldArrayItem<T> => ({
+    key: nextKey++,
+    value: signal(value),
+  })
+
+  const items = signal<FieldArrayItem<T>[]>(initial.map(makeItem))
+  const length = computed(() => items().length)
+
+  return {
+    items,
+    length,
+
+    append(value: T) {
+      items.update((arr) => [...arr, makeItem(value)])
+    },
+
+    prepend(value: T) {
+      items.update((arr) => [makeItem(value), ...arr])
+    },
+
+    insert(index: number, value: T) {
+      items.update((arr) => {
+        const next = [...arr]
+        next.splice(index, 0, makeItem(value))
+        return next
+      })
+    },
+
+    remove(index: number) {
+      items.update((arr) => arr.filter((_, i) => i !== index))
+    },
+
+    update(index: number, value: T) {
+      const current = items.peek()
+      const item = current[index]
+      if (item) {
+        item.value.set(value)
+      }
+    },
+
+    move(from: number, to: number) {
+      items.update((arr) => {
+        const next = [...arr]
+        const [item] = next.splice(from, 1)
+        if (item) next.splice(to, 0, item)
+        return next
+      })
+    },
+
+    swap(indexA: number, indexB: number) {
+      items.update((arr) => {
+        const next = [...arr]
+        const a = next[indexA]
+        const b = next[indexB]
+        if (a && b) {
+          next[indexA] = b
+          next[indexB] = a
+        }
+        return next
+      })
+    },
+
+    replace(values: T[]) {
+      items.set(values.map(makeItem))
+    },
+
+    values() {
+      return items.peek().map((item) => item.value.peek())
+    },
+  }
+}

package/src/use-field.ts

@@ -0,0 +1,69 @@
+import { computed } from '@pyreon/reactivity'
+import type { Signal, Computed } from '@pyreon/reactivity'
+import type {
+  FieldState,
+  FormState,
+  ValidationError,
+  FieldRegisterProps,
+} from './types'
+
+export interface UseFieldResult<T> {
+  /** Current field value (reactive signal). */
+  value: Signal<T>
+  /** Field error message (reactive signal). */
+  error: Signal<ValidationError>
+  /** Whether the field has been touched (reactive signal). */
+  touched: Signal<boolean>
+  /** Whether the field value differs from initial (reactive signal). */
+  dirty: Signal<boolean>
+  /** Set the field value. */
+  setValue: (value: T) => void
+  /** Mark the field as touched. */
+  setTouched: () => void
+  /** Reset the field to its initial value. */
+  reset: () => void
+  /** Register props for input binding. */
+  register: (opts?: { type?: 'checkbox' }) => FieldRegisterProps<T>
+  /** Whether the field has an error (computed). */
+  hasError: Computed<boolean>
+  /** Whether the field should show its error (touched + has error). */
+  showError: Computed<boolean>
+}
+
+/**
+ * Extract a single field's state and helpers from a form instance.
+ * Useful for building isolated field components.
+ *
+ * @example
+ * function EmailField({ form }: { form: FormState<{ email: string }> }) {
+ *   const field = useField(form, 'email')
+ *   return (
+ *     <>
+ *       <input {...field.register()} />
+ *       {field.showError() && <span>{field.error()}</span>}
+ *     </>
+ *   )
+ * }
+ */
+export function useField<
+  TValues extends Record<string, unknown>,
+  K extends keyof TValues & string,
+>(form: FormState<TValues>, name: K): UseFieldResult<TValues[K]> {
+  const fieldState: FieldState<TValues[K]> = form.fields[name]
+
+  const hasError = computed(() => fieldState.error() !== undefined)
+  const showError = computed(() => fieldState.touched() && hasError())
+
+  return {
+    value: fieldState.value,
+    error: fieldState.error,
+    touched: fieldState.touched,
+    dirty: fieldState.dirty,
+    setValue: fieldState.setValue,
+    setTouched: fieldState.setTouched,
+    reset: fieldState.reset,
+    register: (opts?) => form.register(name, opts),
+    hasError,
+    showError,
+  }
+}

package/src/use-form-state.ts

@@ -0,0 +1,74 @@
+import { computed } from '@pyreon/reactivity'
+import type { Computed } from '@pyreon/reactivity'
+import type { FormState, ValidationError } from './types'
+
+export interface FormStateSummary<TValues extends Record<string, unknown>> {
+  isSubmitting: boolean
+  isValidating: boolean
+  isValid: boolean
+  isDirty: boolean
+  submitCount: number
+  submitError: unknown
+  touchedFields: Partial<Record<keyof TValues, boolean>>
+  dirtyFields: Partial<Record<keyof TValues, boolean>>
+  errors: Partial<Record<keyof TValues, ValidationError>>
+}
+
+/**
+ * Subscribe to the full form state as a single computed signal.
+ * Useful for rendering form-level UI (submit button disabled state,
+ * error summaries, progress indicators).
+ *
+ * @example
+ * const state = useFormState(form)
+ * // state() => { isSubmitting, isValid, isDirty, errors, ... }
+ *
+ * @example
+ * // Use a selector for fine-grained reactivity
+ * const canSubmit = useFormState(form, (s) => s.isValid && !s.isSubmitting)
+ */
+export function useFormState<TValues extends Record<string, unknown>>(
+  form: FormState<TValues>,
+): Computed<FormStateSummary<TValues>>
+
+export function useFormState<TValues extends Record<string, unknown>, R>(
+  form: FormState<TValues>,
+  selector: (state: FormStateSummary<TValues>) => R,
+): Computed<R>
+
+export function useFormState<TValues extends Record<string, unknown>, R>(
+  form: FormState<TValues>,
+  selector?: (state: FormStateSummary<TValues>) => R,
+): Computed<FormStateSummary<TValues>> | Computed<R> {
+  const buildSummary = (): FormStateSummary<TValues> => {
+    const touchedFields = {} as Partial<Record<keyof TValues, boolean>>
+    const dirtyFields = {} as Partial<Record<keyof TValues, boolean>>
+    const errors = {} as Partial<Record<keyof TValues, ValidationError>>
+
+    for (const key of Object.keys(form.fields) as (keyof TValues & string)[]) {
+      const field = form.fields[key]
+      if (field.touched()) touchedFields[key] = true
+      if (field.dirty()) dirtyFields[key] = true
+      const err = field.error()
+      if (err !== undefined) errors[key] = err
+    }
+
+    return {
+      isSubmitting: form.isSubmitting(),
+      isValidating: form.isValidating(),
+      isValid: form.isValid(),
+      isDirty: form.isDirty(),
+      submitCount: form.submitCount(),
+      submitError: form.submitError(),
+      touchedFields,
+      dirtyFields,
+      errors,
+    }
+  }
+
+  if (selector) {
+    return computed(() => selector(buildSummary()))
+  }
+
+  return computed(buildSummary)
+}