@pyreon/form 0.0.1

package/lib/types/index2.d.ts

@@ -0,0 +1,291 @@
+import { Props, VNode, VNodeChild } from "@pyreon/core";
+import { Computed, Signal } from "@pyreon/reactivity";
+
+//#region src/types.d.ts
+type ValidationError = string | undefined;
+/**
+ * A reactive value that can be read by calling it.
+ * Both `Signal<T>` and `Computed<T>` satisfy this interface.
+ */
+type Accessor<T> = Signal<T> | Computed<T>;
+/**
+ * Field validator function. Receives the field value and all current form values
+ * for cross-field validation.
+ */
+type ValidateFn<T, TValues = Record<string, unknown>> = (value: T, allValues: TValues) => ValidationError | Promise<ValidationError>;
+type SchemaValidateFn<TValues> = (values: TValues) => Partial<Record<keyof TValues, ValidationError>> | Promise<Partial<Record<keyof TValues, ValidationError>>>;
+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. */
+interface FieldRegisterProps<T> {
+  value: Signal<T>;
+  onInput: (e: Event) => void;
+  onBlur: () => void;
+  checked?: Accessor<boolean>;
+}
+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>;
+}
+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;
+}
+//#endregion
+//#region src/use-form.d.ts
+/**
+ * Create a signal-based form. Returns reactive field states, form-level
+ * signals, and handlers for submit/reset/validate.
+ *
+ * @example
+ * const form = useForm({
+ *   initialValues: { email: '', password: '', remember: false },
+ *   validators: {
+ *     email: (v) => (!v ? 'Required' : undefined),
+ *     password: (v, all) => (v.length < 8 ? 'Too short' : undefined),
+ *   },
+ *   onSubmit: async (values) => { await login(values) },
+ * })
+ *
+ * // Bind with register():
+ * // h('input', form.register('email'))
+ * // h('input', { type: 'checkbox', ...form.register('remember', { type: 'checkbox' }) })
+ */
+declare function useForm<TValues extends Record<string, unknown>>(options: UseFormOptions<TValues>): FormState<TValues>;
+//#endregion
+//#region src/use-field-array.d.ts
+interface FieldArrayItem<T> {
+  /** Stable key for keyed rendering. */
+  key: number;
+  /** Reactive value for this item. */
+  value: Signal<T>;
+}
+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
+ */
+declare function useFieldArray<T>(initial?: T[]): UseFieldArrayResult<T>;
+//#endregion
+//#region src/use-field.d.ts
+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>}
+ *     </>
+ *   )
+ * }
+ */
+declare function useField<TValues extends Record<string, unknown>, K extends keyof TValues & string>(form: FormState<TValues>, name: K): UseFieldResult<TValues[K]>;
+//#endregion
+//#region src/use-watch.d.ts
+/**
+ * Watch specific field values reactively. Returns a computed signal
+ * that re-evaluates when any of the watched fields change.
+ *
+ * @example
+ * // Watch a single field
+ * const email = useWatch(form, 'email')
+ * // email() => current email value
+ *
+ * @example
+ * // Watch multiple fields
+ * const [first, last] = useWatch(form, ['firstName', 'lastName'])
+ * // first() => firstName value, last() => lastName value
+ *
+ * @example
+ * // Watch all fields
+ * const all = useWatch(form)
+ * // all() => { email: '...', password: '...' }
+ */
+declare function useWatch<TValues extends Record<string, unknown>, K extends keyof TValues & string>(form: FormState<TValues>, name: K): Signal<TValues[K]>;
+declare function useWatch<TValues extends Record<string, unknown>, K extends (keyof TValues & string)[]>(form: FormState<TValues>, names: K): { [I in keyof K]: Signal<TValues[K[I] & keyof TValues]> };
+declare function useWatch<TValues extends Record<string, unknown>>(form: FormState<TValues>): Computed<TValues>;
+//#endregion
+//#region src/use-form-state.d.ts
+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)
+ */
+declare function useFormState<TValues extends Record<string, unknown>>(form: FormState<TValues>): Computed<FormStateSummary<TValues>>;
+declare function useFormState<TValues extends Record<string, unknown>, R>(form: FormState<TValues>, selector: (state: FormStateSummary<TValues>) => R): Computed<R>;
+//#endregion
+//#region src/context.d.ts
+interface FormProviderProps<TValues extends Record<string, unknown>> extends Props {
+  form: FormState<TValues>;
+  children?: VNodeChild;
+}
+/**
+ * Provide a form instance to the component tree so nested components
+ * can access it via `useFormContext()`.
+ *
+ * @example
+ * const form = useForm({ initialValues: { email: '' }, onSubmit: ... })
+ *
+ * <FormProvider form={form}>
+ *   <EmailField />
+ *   <SubmitButton />
+ * </FormProvider>
+ */
+declare function FormProvider<TValues extends Record<string, unknown>>(props: FormProviderProps<TValues>): VNode;
+/**
+ * Access the form instance from the nearest `FormProvider`.
+ * Must be called within a component tree wrapped by `FormProvider`.
+ *
+ * @example
+ * function EmailField() {
+ *   const form = useFormContext<{ email: string }>()
+ *   return <input {...form.register('email')} />
+ * }
+ */
+declare function useFormContext<TValues extends Record<string, unknown> = Record<string, unknown>>(): FormState<TValues>;
+//#endregion
+export { type Accessor, type FieldArrayItem, type FieldRegisterProps, type FieldState, FormProvider, type FormState, type FormStateSummary, type SchemaValidateFn, type UseFieldArrayResult, type UseFieldResult, type UseFormOptions, type ValidateFn, type ValidationError, useField, useFieldArray, useForm, useFormContext, useFormState, useWatch };
+//# sourceMappingURL=index2.d.ts.map

package/lib/types/index2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index2.d.ts","names":[],"sources":["../../src/types.ts","../../src/use-form.ts","../../src/use-field-array.ts","../../src/use-field.ts","../../src/use-watch.ts","../../src/use-form-state.ts","../../src/context.ts"],"mappings":"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"}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@pyreon/form",
+  "version": "0.0.1",
+  "description": "Signal-based form management for Pyreon",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pyreon/fundamentals.git",
+    "directory": "packages/form"
+  },
+  "homepage": "https://github.com/pyreon/fundamentals/tree/main/packages/form#readme",
+  "bugs": {
+    "url": "https://github.com/pyreon/fundamentals/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "lib",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./lib/index.js",
+  "module": "./lib/index.js",
+  "types": "./lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./lib/index.js",
+      "types": "./lib/types/index.d.ts"
+    },
+    "./devtools": {
+      "bun": "./src/devtools.ts",
+      "import": "./lib/devtools.js",
+      "types": "./lib/types/devtools.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "vl_rolldown_build",
+    "dev": "vl_rolldown_build-watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@pyreon/core": "^0.2.1",
+    "@pyreon/reactivity": "^0.2.1"
+  },
+  "devDependencies": {
+    "@happy-dom/global-registrator": "^20.8.3",
+    "@pyreon/core": "^0.2.1",
+    "@pyreon/reactivity": "^0.2.1",
+    "@pyreon/runtime-dom": "^0.2.1"
+  }
+}

package/src/context.ts

@@ -0,0 +1,67 @@
+import {
+  createContext,
+  pushContext,
+  popContext,
+  onUnmount,
+  useContext,
+} from '@pyreon/core'
+import type { VNodeChild, VNode, Props } from '@pyreon/core'
+import type { FormState } from './types'
+
+const FormContext = createContext<FormState<Record<string, unknown>> | null>(
+  null,
+)
+
+export interface FormProviderProps<TValues extends Record<string, unknown>>
+  extends Props {
+  form: FormState<TValues>
+  children?: VNodeChild
+}
+
+/**
+ * Provide a form instance to the component tree so nested components
+ * can access it via `useFormContext()`.
+ *
+ * @example
+ * const form = useForm({ initialValues: { email: '' }, onSubmit: ... })
+ *
+ * <FormProvider form={form}>
+ *   <EmailField />
+ *   <SubmitButton />
+ * </FormProvider>
+ */
+export function FormProvider<TValues extends Record<string, unknown>>(
+  props: FormProviderProps<TValues>,
+): VNode {
+  const frame = new Map([[FormContext.id, props.form]])
+  pushContext(frame)
+
+  onUnmount(() => popContext())
+
+  const ch = props.children
+  return (typeof ch === 'function' ? (ch as () => VNodeChild)() : ch) as VNode
+}
+
+/**
+ * Access the form instance from the nearest `FormProvider`.
+ * Must be called within a component tree wrapped by `FormProvider`.
+ *
+ * @example
+ * function EmailField() {
+ *   const form = useFormContext<{ email: string }>()
+ *   return <input {...form.register('email')} />
+ * }
+ */
+export function useFormContext<
+  TValues extends Record<string, unknown> = Record<string, unknown>,
+>(): FormState<TValues> {
+  const form = useContext(FormContext)
+  if (!form) {
+    throw new Error(
+      '[@pyreon/form] useFormContext() must be used within a <FormProvider>.',
+    )
+  }
+  // Generic narrowing: context stores FormState<Record<string, unknown>>
+  // but callers narrow to their specific TValues at the call site.
+  return form as FormState<TValues>
+}

package/src/devtools.ts

@@ -0,0 +1,100 @@
+/**
+ * @pyreon/form devtools introspection API.
+ * Import: `import { ... } from "@pyreon/form/devtools"`
+ */
+
+const _activeForms = new Map<string, WeakRef<object>>()
+const _listeners = new Set<() => void>()
+
+function _notify(): void {
+  for (const listener of _listeners) listener()
+}
+
+/**
+ * Register a form instance for devtools inspection.
+ *
+ * @example
+ * const form = useForm({ ... })
+ * registerForm("login-form", form)
+ */
+export function registerForm(name: string, form: object): void {
+  _activeForms.set(name, new WeakRef(form))
+  _notify()
+}
+
+/** Unregister a form instance. */
+export function unregisterForm(name: string): void {
+  _activeForms.delete(name)
+  _notify()
+}
+
+/** Get all registered form names. Cleans up garbage-collected instances. */
+export function getActiveForms(): string[] {
+  for (const [name, ref] of _activeForms) {
+    if (ref.deref() === undefined) _activeForms.delete(name)
+  }
+  return [..._activeForms.keys()]
+}
+
+/** Get a form instance by name (or undefined if GC'd or not registered). */
+export function getFormInstance(name: string): object | undefined {
+  const ref = _activeForms.get(name)
+  if (!ref) return undefined
+  const instance = ref.deref()
+  if (!instance) {
+    _activeForms.delete(name)
+    return undefined
+  }
+  return instance
+}
+
+/**
+ * Get a snapshot of a registered form's current state.
+ * Returns values, errors, and form-level status signals.
+ */
+export function getFormSnapshot(
+  name: string,
+): Record<string, unknown> | undefined {
+  const form = getFormInstance(name) as Record<string, unknown> | undefined
+  if (!form) return undefined
+  return {
+    values:
+      typeof form.values === 'function'
+        ? (form.values as () => unknown)()
+        : undefined,
+    errors:
+      typeof form.errors === 'function'
+        ? (form.errors as () => unknown)()
+        : undefined,
+    isSubmitting:
+      typeof form.isSubmitting === 'function'
+        ? (form.isSubmitting as () => unknown)()
+        : undefined,
+    isValid:
+      typeof form.isValid === 'function'
+        ? (form.isValid as () => unknown)()
+        : undefined,
+    isDirty:
+      typeof form.isDirty === 'function'
+        ? (form.isDirty as () => unknown)()
+        : undefined,
+    submitCount:
+      typeof form.submitCount === 'function'
+        ? (form.submitCount as () => unknown)()
+        : undefined,
+  }
+}
+
+/** Subscribe to form registry changes. Returns unsubscribe function. */
+export function onFormChange(listener: () => void): () => void {
+  _listeners.add(listener)
+  return () => {
+    _listeners.delete(listener)
+  }
+}
+
+/** @internal — reset devtools registry (for tests). */
+export function _resetDevtools(): void {
+  _activeForms.clear()
+  _listeners.clear()
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+export { useForm } from './use-form'
+export { useFieldArray } from './use-field-array'
+export { useField } from './use-field'
+export { useWatch } from './use-watch'
+export { useFormState } from './use-form-state'
+export { FormProvider, useFormContext } from './context'
+
+export type {
+  Accessor,
+  FieldState,
+  FieldRegisterProps,
+  FormState,
+  UseFormOptions,
+  ValidationError,
+  ValidateFn,
+  SchemaValidateFn,
+} from './types'
+
+export type {
+  FieldArrayItem,
+  UseFieldArrayResult,
+} from './use-field-array'
+
+export type { UseFieldResult } from './use-field'
+
+export type { FormStateSummary } from './use-form-state'