jsonisch 0.1.0

package/dist/react/index.d.ts

@@ -0,0 +1,476 @@
+import { C as FieldErrors, G as JsonSchema, K as Path, M as ControlKind, S as FieldElement, a as InternalFormStore, i as FormValidator, r as FormConfig } from "../form-ref-D_xHSaqL.js";
+import { t as SubmitHandler } from "../handle-submit-Dk7QW3_q.js";
+import { ComponentType, FormHTMLAttributes, ReactElement, ReactNode } from "react";
+
+//#region src/react/types.d.ts
+
+/**
+ * The public form store returned by `useForm`/`useAppForm`: an immutable
+ * snapshot whose identity changes when any observed form-level value
+ * changes — reactivity rides on the object, not on property reads, so it
+ * composes with React Compiler memoization. The internal store is
+ * reachable for the methods layer — every method accepts this wrapper
+ * directly.
+ */
+interface FormStore {
+  /**
+   * The internal form store (the methods layer unwraps it).
+   */
+  readonly internal: InternalFormStore;
+  /**
+   * Whether the form is currently submitting.
+   */
+  readonly isSubmitting: boolean;
+  /**
+   * Whether the form has been submitted.
+   */
+  readonly isSubmitted: boolean;
+  /**
+   * Whether the form is currently validating.
+   */
+  readonly isValidating: boolean;
+  /**
+   * Whether any field in the form has been touched.
+   */
+  readonly isTouched: boolean;
+  /**
+   * Whether any field in the form has been edited.
+   */
+  readonly isEdited: boolean;
+  /**
+   * Whether any field in the form differs from its start input.
+   */
+  readonly isDirty: boolean;
+  /**
+   * Whether no field in the form has errors.
+   */
+  readonly isValid: boolean;
+  /**
+   * The form-level (root) errors. Use `getDeepErrors` for all field errors.
+   */
+  readonly errors: FieldErrors;
+}
+/**
+ * The props a field store provides for binding a DOM element.
+ */
+interface FieldElementProps {
+  /**
+   * The name attribute of the field element.
+   */
+  readonly name: string;
+  /**
+   * Whether to autofocus the element (set while the field has errors).
+   */
+  readonly autoFocus: boolean;
+  /**
+   * The ref callback registering the element on the field store.
+   */
+  readonly ref: (element: FieldElement | null) => void;
+  /**
+   * The focus handler (marks the field touched). Takes no arguments so it
+   * assigns to any element's focus handler type.
+   */
+  readonly onFocus: () => void;
+  /**
+   * The blur handler (triggers blur-mode validation). Takes no arguments so
+   * it assigns to any element's blur handler type.
+   */
+  readonly onBlur: () => void;
+}
+/**
+ * The plugin-contributed members of `FieldStore` — an empty marker each
+ * plugin merges its `fieldSnapshot` keys into via `declare module`
+ * augmentation IN ITS OWN FILE (fastify's decorate pattern), so widgets
+ * type-check flat members (`field.mode`, `field.setEntryMode(...)`) with
+ * no generics anywhere and ownership stays greppable. The react adapter
+ * itself knows no plugin's vocabulary; the runtime twin of this contract
+ * is `dispatchFieldSnapshot`'s collision throw.
+ */
+interface FieldStoreSlots {}
+/**
+ * The public field store returned by `useField`: an immutable snapshot —
+ * a new object identity whenever any observed value changes, stable
+ * otherwise. Widgets are plain controlled components that render `input`
+ * and call `onChange` with the new value; no signal hook, no directive.
+ * Plugin-contributed members ride `FieldStoreSlots`.
+ */
+interface FieldStore extends FieldStoreSlots {
+  /**
+   * The path to the field within the form.
+   */
+  readonly path: Path;
+  /**
+   * The property name of the field (last path segment).
+   */
+  readonly name: string;
+  /**
+   * The JSON-Schema node of the field (title, enum options, formats, …).
+   */
+  readonly schema: JsonSchema;
+  /**
+   * The widget kind the field renders as (resolved at walk time).
+   */
+  readonly control: ControlKind;
+  /**
+   * The current input value of the field.
+   */
+  readonly input: unknown;
+  /**
+   * The current error messages of the field.
+   */
+  readonly errors: FieldErrors;
+  /**
+   * Whether the field (or a descendant) has been touched.
+   */
+  readonly isTouched: boolean;
+  /**
+   * Whether the field (or a descendant) has been edited.
+   */
+  readonly isEdited: boolean;
+  /**
+   * Whether the field (or a descendant) differs from its start input.
+   */
+  readonly isDirty: boolean;
+  /**
+   * Whether the field and its descendants have no errors.
+   */
+  readonly isValid: boolean;
+  /**
+   * Whether the field currently renders: `false` for a `hidden` control or
+   * while a conditional-visibility rule (`visibleWhen`) is unsatisfied.
+   * Registry dispatch skips invisible fields; headless layouts decide
+   * themselves. A hidden field keeps its state, dirtiness, and place in
+   * the payload.
+   */
+  readonly visible: boolean;
+  /**
+   * Sets the field input (controlled-component change handler).
+   */
+  readonly onChange: (value: unknown) => void;
+  /**
+   * The props to spread onto the field element.
+   */
+  readonly props: FieldElementProps;
+}
+/**
+ * The public field array store returned by `useFieldArray`.
+ */
+interface FieldArrayStore {
+  /**
+   * The path to the array field within the form.
+   */
+  readonly path: Path;
+  /**
+   * The stable item IDs, one per row — use them as React keys so state
+   * follows its row across reorders.
+   */
+  readonly items: string[];
+  /**
+   * The current error messages of the array field itself.
+   */
+  readonly errors: FieldErrors;
+  /**
+   * Whether the array (or a descendant) has been touched.
+   */
+  readonly isTouched: boolean;
+  /**
+   * Whether the array (or a descendant) has been edited.
+   */
+  readonly isEdited: boolean;
+  /**
+   * Whether the array (or a descendant) differs from its start input.
+   */
+  readonly isDirty: boolean;
+  /**
+   * Whether the array and its descendants have no errors.
+   */
+  readonly isValid: boolean;
+}
+/**
+ * The props every registry widget receives.
+ */
+interface WidgetProps {
+  /**
+   * The field store the widget renders.
+   */
+  readonly field: FieldStore;
+  /**
+   * The form store the field belongs to.
+   */
+  readonly form: FormStore;
+}
+/**
+ * The configuration of `createFormHook`: the registry mapping widget kinds
+ * to components, plus the injected validator compiler.
+ */
+interface FormHookConfig {
+  /**
+   * The widget registry, keyed by `ControlKind`. A kind without an entry
+   * renders the `fallback`.
+   */
+  readonly widgets: Partial<Record<ControlKind, ComponentType<WidgetProps>>>;
+  /**
+   * The widget rendered for a kind without a registry entry. Without one, a
+   * built-in placeholder names the unsupported kind visibly.
+   */
+  readonly fallback?: ComponentType<WidgetProps> | undefined;
+  /**
+   * Compiles the injected validator for a schema, called ONCE per form
+   * (memoized by `useAppForm`). Omit for forms without enforcement.
+   */
+  readonly validate?: ((schema: JsonSchema) => FormValidator) | undefined;
+}
+/**
+ * The configuration of `useAppForm`: the store config minus the validator,
+ * which the hook compiles itself via the registry's `validate`.
+ */
+type UseAppFormConfig = Omit<FormConfig, "validator">;
+//#endregion
+//#region src/react/components.d.ts
+/**
+ * Props of the headless `Form` component.
+ */
+interface FormProps extends Omit<FormHTMLAttributes<HTMLFormElement>, "onSubmit" | "noValidate"> {
+  /**
+   * The form store instance.
+   */
+  readonly of: FormStore;
+  /**
+   * The submit handler called with the validated output when validation
+   * succeeds.
+   */
+  readonly onSubmit: SubmitHandler;
+  /**
+   * The form contents.
+   */
+  readonly children?: ReactNode;
+}
+/**
+ * Headless form component: a native `<form noValidate>` wired to
+ * `handleSubmit` — an invalid submit blocks the handler and focuses the
+ * first erroring field. The registry-aware `Form` from `createFormHook`
+ * builds on this and adds whole-form auto-rendering.
+ *
+ * @param props The form component props.
+ *
+ * @returns A native form element.
+ */
+declare function Form({
+  of,
+  onSubmit,
+  ...other
+}: FormProps): ReactElement;
+/**
+ * Props of the headless `Field` component.
+ */
+interface FieldProps {
+  /**
+   * The form store the field belongs to.
+   */
+  readonly of: FormStore;
+  /**
+   * The path to the field.
+   */
+  readonly path: Path;
+  /**
+   * The render function receiving the field store.
+   */
+  readonly children: (field: FieldStore) => ReactNode;
+}
+/**
+ * Headless field component — the escape hatch for custom layouts: takes a
+ * form store and a path, and calls the render function with the reactive
+ * field store.
+ *
+ * @param props The field component props.
+ *
+ * @returns The rendered field UI.
+ */
+declare function Field({
+  of,
+  path,
+  children
+}: FieldProps): ReactNode;
+/**
+ * Props of the headless `FieldArray` component.
+ */
+interface FieldArrayProps {
+  /**
+   * The form store the array field belongs to.
+   */
+  readonly of: FormStore;
+  /**
+   * The path to the array field.
+   */
+  readonly path: Path;
+  /**
+   * The render function receiving the field array store.
+   */
+  readonly children: (fieldArray: FieldArrayStore) => ReactNode;
+}
+/**
+ * Headless field array component: calls the render function with the
+ * reactive field array store (stable item IDs for React keys).
+ *
+ * @param props The field array component props.
+ *
+ * @returns The rendered field array UI.
+ */
+declare function FieldArray({
+  of,
+  path,
+  children
+}: FieldArrayProps): ReactNode;
+//#endregion
+//#region src/react/create-form-hook.d.ts
+/**
+ * Props of the registry-aware `Field` component returned by
+ * `createFormHook`.
+ */
+interface AppFieldProps {
+  /**
+   * The form store the field belongs to.
+   */
+  readonly of: FormStore;
+  /**
+   * The path to the field.
+   */
+  readonly path: Path;
+  /**
+   * Optional render function for a custom layout (headless mode). Without
+   * it the field renders its registry widget.
+   */
+  readonly children?: ((field: FieldStore) => ReactNode) | undefined;
+}
+/**
+ * The bound form API returned by `createFormHook`.
+ */
+interface FormHook {
+  /**
+   * Creates a form store, compiling the injected validator once for the
+   * form's schema.
+   */
+  readonly useAppForm: (config: UseAppFormConfig) => FormStore;
+  /**
+   * The form component. Without children it renders the WHOLE form from
+   * the schema via the widget registry — no hand-written field components.
+   */
+  readonly Form: (props: FormProps) => ReactElement;
+  /**
+   * The field component: registry-dispatched without children, headless
+   * with a render function.
+   */
+  readonly Field: (props: AppFieldProps) => ReactNode;
+  /**
+   * The auto-rendered field list (every non-hidden root field through its
+   * registry widget). `Form` renders it when given no children; use it
+   * directly to compose auto fields with custom chrome (e.g. a footer).
+   */
+  readonly Fields: (props: {
+    readonly of: FormStore;
+  }) => ReactElement;
+}
+/**
+ * Creates the app's form API around a widget registry (the TanStack
+ * `createFormHook` borrow): widgets are registered ONCE at module level,
+ * and every form derives its fields from the schema through them.
+ *
+ * @param config The registry and injected validator compiler.
+ *
+ * @returns The bound `useAppForm`, `Form` and `Field`.
+ */
+declare function createFormHook(config: FormHookConfig): FormHook;
+//#endregion
+//#region src/react/use-field.d.ts
+/**
+ * Creates a reactive field store for the field at the given path. Widgets
+ * are controlled components: render `field.input`, call
+ * `field.onChange(value)`, and spread `field.props` onto the DOM element so
+ * focus/blur validation modes and focus-on-error work.
+ *
+ * The returned store is an immutable SNAPSHOT: its identity changes when
+ * any observed value changes and is stable otherwise, so it composes with
+ * React Compiler memoization instead of fighting it (the LOS-567/LOS-602
+ * rewrite). Callbacks and DOM plumbing keep a stable identity for the
+ * field's lifetime.
+ *
+ * @param form The form store the field belongs to.
+ * @param path The path to the field.
+ *
+ * @returns The field store snapshot.
+ */
+declare function useField(form: FormStore, path: Path): FieldStore;
+//#endregion
+//#region src/react/use-field-array.d.ts
+/**
+ * Creates a reactive field array store for the array field at the given
+ * path. Render one row per `items` entry and use the item ID as the React
+ * key so row state and DOM follow their row across reorders.
+ *
+ * The returned store is an immutable SNAPSHOT (see `useField` for the
+ * model).
+ *
+ * @param form The form store the array field belongs to.
+ * @param path The path to the array field.
+ *
+ * @returns The field array store snapshot.
+ */
+declare function useFieldArray(form: FormStore, path: Path): FieldArrayStore;
+//#endregion
+//#region src/react/use-form.d.ts
+/**
+ * Creates a reactive form store from a form configuration. The store is
+ * created once for the component's lifetime — config changes after mount
+ * are ignored (`applyBaseline` rebases on a fresh server record; `reset`
+ * with a new `initialInput` discards in-flight edits with it).
+ *
+ * The returned store is an immutable SNAPSHOT over the stable `internal`
+ * store: its identity changes when any observed form-level value changes
+ * (see `useField` for the model).
+ *
+ * @param config The form configuration.
+ *
+ * @returns The form store snapshot.
+ */
+declare function useForm(config: FormConfig): FormStore;
+//#endregion
+//#region src/react/use-signal-snapshot.d.ts
+/**
+ * Value-level equality for snapshot objects: top-level keys compared with
+ * `Object.is`, with ONE extra level for plain arrays and plain objects —
+ * computed results (a `DerivedState`, an errors array) are rebuilt with a
+ * fresh identity on every recompute, and without the value compare every
+ * notification would produce a render even when nothing visible changed.
+ * Deeper nesting falls back to "not equal" (re-render), never the other
+ * way — a false negative costs one render, a false positive would cost a
+ * stale UI.
+ */
+declare function snapshotEqual(a: unknown, b: unknown): boolean;
+/**
+ * Subscribes the component to exactly the signals `compute` reads and
+ * returns the computed snapshot. THE reactive primitive of the react
+ * adapter — every jsonisch hook reads through it, and it is the public
+ * escape hatch for a component that needs a narrower subscription than
+ * `useField` provides.
+ *
+ * React-Compiler-safe by construction: the tracked reads happen inside a
+ * closure the library invokes — the compiler can only elide expressions
+ * whose call sites it memoized, never a call made from a hook's internals —
+ * and the returned snapshot is an immutable value whose identity changes
+ * when any observed value changes, so compiler memo caches keyed on it
+ * invalidate correctly instead of freezing.
+ *
+ * `useMemo` semantics apply to `deps`: the compute closure is captured when
+ * `deps` change, so everything it reads must be a signal (tracked) or
+ * listed in `deps` (recreates the store). `isEqual` gates re-renders by
+ * value; it defaults to `snapshotEqual`.
+ *
+ * @param compute The tracked read producing the snapshot.
+ * @param deps The non-signal inputs of `compute` (useMemo contract).
+ * @param isEqual The snapshot equality gate.
+ *
+ * @returns The current snapshot.
+ */
+declare function useSignalSnapshot<T>(compute: () => T, deps: readonly unknown[], isEqual?: (a: T, b: T) => boolean): T;
+//#endregion
+export { type AppFieldProps, Field, FieldArray, type FieldArrayProps, type FieldArrayStore, type FieldElementProps, type FieldProps, type FieldStore, type FieldStoreSlots, Form, type FormHook, type FormHookConfig, type FormProps, type FormStore, type UseAppFormConfig, type WidgetProps, createFormHook, snapshotEqual, useField, useFieldArray, useForm, useSignalSnapshot };