@formbar/react 0.2.0

package/dist/index.cjs

@@ -0,0 +1,157 @@
+'use strict';
+
+var react = require('react');
+var core = require('@formbar/core');
+
+// src/a11y.ts
+var DEFAULT_FIELD_PREFIX = "field";
+function fieldId(path, prefix = DEFAULT_FIELD_PREFIX) {
+  return `${prefix}-${path.replace(/[.[\]/]/g, "-").replace(/-+/g, "-").replace(/-$/, "")}`;
+}
+function descriptionId(path, prefix) {
+  return `${fieldId(path, prefix)}-description`;
+}
+function errorId(path, prefix) {
+  return `${fieldId(path, prefix)}-error`;
+}
+function getFieldProps(path, options) {
+  const id = fieldId(path);
+  const hasErrors = options?.issues?.some((i) => i.severity === "error") ?? false;
+  const describedBy = [];
+  if (options?.hasDescription) describedBy.push(descriptionId(path));
+  if (hasErrors) describedBy.push(errorId(path));
+  const props = {
+    id,
+    ...hasErrors ? { "aria-invalid": true } : {},
+    ...describedBy.length > 0 ? { "aria-describedby": describedBy.join(" ") } : {},
+    ...options?.required ? { "aria-required": true } : {},
+    ...hasErrors ? { "aria-errormessage": errorId(path) } : {}
+  };
+  return props;
+}
+function getLabelProps(path) {
+  return { htmlFor: fieldId(path) };
+}
+function getDescriptionProps(path) {
+  return { id: descriptionId(path) };
+}
+function getErrorProps(path) {
+  return { id: errorId(path), role: "alert" };
+}
+function findFirstErrorPath(issues) {
+  const firstError = issues.find((i) => i.severity === "error");
+  if (!firstError) return void 0;
+  return firstError.path.segments.join(".");
+}
+function focusFirstError(issues) {
+  const path = findFirstErrorPath(issues);
+  if (!path) return false;
+  if (typeof document === "undefined") return false;
+  const id = fieldId(path);
+  const element = document.getElementById(id);
+  if (element) {
+    element.focus();
+    return true;
+  }
+  return false;
+}
+function useFormSelector(form, selector, equalityFn) {
+  const eqRef = react.useRef(equalityFn ?? Object.is);
+  eqRef.current = equalityFn ?? Object.is;
+  const selectorRef = react.useRef(selector);
+  selectorRef.current = selector;
+  const prevRef = react.useRef({
+    value: void 0,
+    initialized: false
+  });
+  const subscribe = react.useCallback((onStoreChange) => form.subscribe(onStoreChange), [form]);
+  const getSnapshot = react.useCallback(() => {
+    const next = selectorRef.current(form.getState());
+    if (prevRef.current.initialized && eqRef.current(prevRef.current.value, next)) {
+      return prevRef.current.value;
+    }
+    prevRef.current = { value: next, initialized: true };
+    return next;
+  }, [form]);
+  return react.useSyncExternalStore(subscribe, getSnapshot);
+}
+
+// src/use-field.ts
+function fieldSnapshotEqual(a, b) {
+  return a.value === b.value && a.meta === b.meta;
+}
+function useField(form, path, config) {
+  const configRef = react.useRef(config);
+  const stableConfig = react.useMemo(() => {
+    const prev = configRef.current;
+    if (prev === config) return prev;
+    if (prev && config && JSON.stringify(prev) === JSON.stringify(config)) return prev;
+    configRef.current = config;
+    return config;
+  }, [config]);
+  const field = react.useMemo(() => form.fieldDynamic(path, stableConfig), [form, path, stableConfig]);
+  useFormSelector(
+    form,
+    () => {
+      const state = form.getState();
+      const pathKey = field.path.segments.join(".");
+      const meta = state.fieldMeta[pathKey];
+      return { value: field.get(), meta };
+    },
+    fieldSnapshotEqual
+  );
+  return field;
+}
+function useForm(options) {
+  const autoFocus = options?.autoFocusOnError ?? true;
+  const formRef = react.useRef(null);
+  const disposeTimerRef = react.useRef(null);
+  if (formRef.current === null) {
+    formRef.current = core.createForm(options);
+  }
+  const form = formRef.current;
+  const subscribe = react.useRef((onStoreChange) => {
+    return form.subscribe(onStoreChange);
+  }).current;
+  react.useSyncExternalStore(subscribe, () => form.getState());
+  react.useEffect(() => {
+    if (disposeTimerRef.current !== null) {
+      clearTimeout(disposeTimerRef.current);
+      disposeTimerRef.current = null;
+    }
+    return () => {
+      disposeTimerRef.current = setTimeout(() => {
+        formRef.current?.dispose();
+      }, 0);
+    };
+  }, []);
+  const wrappedApi = react.useMemo(() => {
+    if (!autoFocus) return form;
+    return {
+      ...form,
+      submit: async (...args) => {
+        const result = await form.submit(...args);
+        if (!result.ok && result.fieldIssues?.length) {
+          focusFirstError(result.fieldIssues);
+        }
+        return result;
+      }
+    };
+  }, [form, autoFocus]);
+  return wrappedApi;
+}
+
+exports.descriptionId = descriptionId;
+exports.errorId = errorId;
+exports.fieldId = fieldId;
+exports.findFirstErrorPath = findFirstErrorPath;
+exports.focusFirstError = focusFirstError;
+exports.getDescriptionProps = getDescriptionProps;
+exports.getErrorProps = getErrorProps;
+exports.getFieldProps = getFieldProps;
+exports.getLabelProps = getLabelProps;
+exports.useField = useField;
+exports.useForm = useForm;
+exports.useFormSelector = useFormSelector;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/a11y.ts","../src/use-form-selector.ts","../src/use-field.ts","../src/use-form.ts"],"names":["useRef","useCallback","useSyncExternalStore","useMemo","createForm","useEffect"],"mappings":"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","file":"index.cjs","sourcesContent":["import type { ValidationIssue } from \"@formbar/core\";\n\nconst DEFAULT_FIELD_PREFIX = \"field\";\n\n/** ARIA props for a form field */\nexport interface FieldA11yProps {\n\treadonly id: string;\n\treadonly \"aria-invalid\"?: boolean;\n\treadonly \"aria-describedby\"?: string;\n\treadonly \"aria-required\"?: boolean;\n\treadonly \"aria-errormessage\"?: string;\n}\n\n/** Label props for semantic association */\nexport interface LabelA11yProps {\n\treadonly htmlFor: string;\n}\n\n/** Description/error message props */\nexport interface DescriptionA11yProps {\n\treadonly id: string;\n\treadonly role?: \"alert\";\n}\n\n/** Generate a deterministic field ID from path */\nexport function fieldId(path: string, prefix: string = DEFAULT_FIELD_PREFIX): string {\n\treturn `${prefix}-${path\n\t\t.replace(/[.[\\]/]/g, \"-\")\n\t\t.replace(/-+/g, \"-\")\n\t\t.replace(/-$/, \"\")}`;\n}\n\n/** Generate description element ID */\nexport function descriptionId(path: string, prefix?: string): string {\n\treturn `${fieldId(path, prefix)}-description`;\n}\n\n/** Generate error element ID */\nexport function errorId(path: string, prefix?: string): string {\n\treturn `${fieldId(path, prefix)}-error`;\n}\n\n/** Get ARIA props for a field input element */\nexport function getFieldProps(\n\tpath: string,\n\toptions?: {\n\t\treadonly issues?: readonly ValidationIssue[];\n\t\treadonly required?: boolean;\n\t\treadonly hasDescription?: boolean;\n\t},\n): FieldA11yProps {\n\tconst id = fieldId(path);\n\tconst hasErrors = options?.issues?.some((i) => i.severity === \"error\") ?? false;\n\n\tconst describedBy: string[] = [];\n\tif (options?.hasDescription) describedBy.push(descriptionId(path));\n\tif (hasErrors) describedBy.push(errorId(path));\n\n\tconst props: FieldA11yProps = {\n\t\tid,\n\t\t...(hasErrors ? { \"aria-invalid\": true as const } : {}),\n\t\t...(describedBy.length > 0 ? { \"aria-describedby\": describedBy.join(\" \") } : {}),\n\t\t...(options?.required ? { \"aria-required\": true as const } : {}),\n\t\t...(hasErrors ? { \"aria-errormessage\": errorId(path) } : {}),\n\t};\n\n\treturn props;\n}\n\n/** Get label props for semantic association */\nexport function getLabelProps(path: string): LabelA11yProps {\n\treturn { htmlFor: fieldId(path) };\n}\n\n/** Get description element props */\nexport function getDescriptionProps(path: string): DescriptionA11yProps {\n\treturn { id: descriptionId(path) };\n}\n\n/** Get error message props */\nexport function getErrorProps(path: string): DescriptionA11yProps {\n\treturn { id: errorId(path), role: \"alert\" };\n}\n\n/** Find the first field path with errors (for focus management) */\nexport function findFirstErrorPath(issues: readonly ValidationIssue[]): string | undefined {\n\tconst firstError = issues.find((i) => i.severity === \"error\");\n\tif (!firstError) return undefined;\n\treturn firstError.path.segments.join(\".\");\n}\n\n/** Focus the first error field after submit (browser-only) */\nexport function focusFirstError(issues: readonly ValidationIssue[]): boolean {\n\tconst path = findFirstErrorPath(issues);\n\tif (!path) return false;\n\n\tif (typeof document === \"undefined\") return false;\n\n\tconst id = fieldId(path);\n\tconst element = document.getElementById(id);\n\tif (element) {\n\t\telement.focus();\n\t\treturn true;\n\t}\n\treturn false;\n}\n","import type { FormApi, FormState } from \"@formbar/core\";\nimport { useCallback, useRef, useSyncExternalStore } from \"react\";\n\n/**\n * Subscribe to a derived value from form state with fine-grained reactivity.\n * Only triggers re-render when the selected value changes (by equality function).\n *\n * @param form - The {@link FormApi} instance.\n * @param selector - Function that extracts a value from the full form state.\n * @param equalityFn - Optional equality comparator (defaults to `Object.is`).\n * @returns The current selected value, updated reactively.\n *\n * @example\n * ```typescript\n * const isValid = useFormSelector(form, (state) => state.issues.length === 0);\n * const submitCount = useFormSelector(form, (state) => state.meta.submitted);\n * ```\n */\nexport function useFormSelector<TData, TUi, T>(\n\tform: FormApi<TData, TUi>,\n\tselector: (state: FormState<TData, TUi>) => T,\n\tequalityFn?: (prev: T, next: T) => boolean,\n): T {\n\tconst eqRef = useRef(equalityFn ?? Object.is);\n\teqRef.current = equalityFn ?? Object.is;\n\n\tconst selectorRef = useRef(selector);\n\tselectorRef.current = selector;\n\n\tconst prevRef = useRef<{ readonly value: T; readonly initialized: boolean }>({\n\t\tvalue: undefined as T,\n\t\tinitialized: false,\n\t});\n\n\tconst subscribe = useCallback((onStoreChange: () => void) => form.subscribe(onStoreChange), [form]);\n\n\tconst getSnapshot = useCallback((): T => {\n\t\tconst next = selectorRef.current(form.getState());\n\t\tif (prevRef.current.initialized && eqRef.current(prevRef.current.value, next)) {\n\t\t\treturn prevRef.current.value;\n\t\t}\n\t\tprevRef.current = { value: next, initialized: true };\n\t\treturn next;\n\t}, [form]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot);\n}\n","import type { FieldApi, FieldConfig, FieldMetaEntry, FormApi } from \"@formbar/core\";\nimport { useMemo, useRef } from \"react\";\nimport { useFormSelector } from \"./use-form-selector.js\";\n\ninterface FieldSnapshot {\n\treadonly value: unknown;\n\treadonly meta: FieldMetaEntry | undefined;\n}\n\nfunction fieldSnapshotEqual(a: FieldSnapshot, b: FieldSnapshot): boolean {\n\treturn a.value === b.value && a.meta === b.meta;\n}\n\n/**\n * React hook that subscribes to a specific field with fine-grained re-rendering.\n * Only re-renders when the field's value or metadata actually changes.\n *\n * @param form - The {@link FormApi} instance (from useForm or createForm).\n * @param path - Dot-path to the field (e.g., `\"user.email\"`).\n * @param config - Optional field configuration (label, validators, triggers).\n * @returns A {@link FieldApi} with reactive get/set, validation, and touch tracking.\n *\n * @example\n * ```typescript\n * function EmailField({ form }) {\n *   const field = useField(form, \"email\");\n *   return (\n *     <div>\n *       <input\n *         value={field.get() ?? \"\"}\n *         onChange={e => field.handleChange(e.target.value)}\n *         onBlur={() => field.handleBlur()}\n *       />\n *       {field.issues().map(i => <span key={i.code}>{i.message}</span>)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useField<TData, TUi, P extends string>(\n\tform: FormApi<TData, TUi>,\n\tpath: P,\n\tconfig?: FieldConfig,\n): FieldApi<TData, TUi, P> {\n\t// Stabilize config reference — inline objects create new references every render\n\tconst configRef = useRef(config);\n\tconst stableConfig = useMemo(() => {\n\t\tconst prev = configRef.current;\n\t\tif (prev === config) return prev;\n\t\tif (prev && config && JSON.stringify(prev) === JSON.stringify(config)) return prev;\n\t\tconfigRef.current = config;\n\t\treturn config;\n\t}, [config]);\n\n\tconst field = useMemo(() => form.fieldDynamic(path, stableConfig), [form, path, stableConfig]);\n\n\t// Subscribe to field value and touched state to trigger re-renders\n\tuseFormSelector(\n\t\tform,\n\t\t() => {\n\t\t\tconst state = form.getState();\n\t\t\tconst pathKey = field.path.segments.join(\".\");\n\t\t\tconst meta = (state.fieldMeta as Readonly<Record<string, FieldMetaEntry>>)[pathKey];\n\t\t\treturn { value: field.get(), meta } as FieldSnapshot;\n\t\t},\n\t\tfieldSnapshotEqual,\n\t);\n\n\treturn field as FieldApi<TData, TUi, P>;\n}\n","import type { CreateFormOptions, FormApi, SubmitResult } from \"@formbar/core\";\nimport { createForm } from \"@formbar/core\";\nimport { useEffect, useMemo, useRef, useSyncExternalStore } from \"react\";\nimport { focusFirstError } from \"./a11y.js\";\n\n/** Options for useForm, extending core CreateFormOptions with React-specific behavior */\nexport interface UseFormOptions<TData, TUi> extends CreateFormOptions<TData, TUi> {\n\t/** Auto-focus the first error field on submit failure (default: true) */\n\treadonly autoFocusOnError?: boolean;\n}\n\n/**\n * React hook that creates and manages a form instance with automatic cleanup.\n * The form is created once on mount and disposed on unmount (StrictMode-safe).\n *\n * @param options - Form configuration (same as {@link createForm} options).\n * @returns A stable {@link FormApi} reference that persists across re-renders.\n *\n * @example\n * ```typescript\n * function ContactForm() {\n *   const form = useForm({\n *     initialData: { name: \"\", email: \"\" },\n *     onSubmit: async ({ payload }) => {\n *       await saveContact(payload);\n *       return { ok: true, submitId: \"1\" };\n *     },\n *   });\n *\n *   return <input value={form.field(\"name\").get()} onChange={e => form.field(\"name\").set(e.target.value)} />;\n * }\n * ```\n */\nexport function useForm<TData, TUi>(options?: UseFormOptions<TData, TUi>): FormApi<TData, TUi> {\n\tconst autoFocus = options?.autoFocusOnError ?? true;\n\tconst formRef = useRef<FormApi<TData, TUi> | null>(null);\n\tconst disposeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\tif (formRef.current === null) {\n\t\tformRef.current = createForm<TData, TUi>(options);\n\t}\n\n\tconst form = formRef.current;\n\n\t// Adapt form.subscribe (which passes state) to useSyncExternalStore's expected signature\n\tconst subscribe = useRef((onStoreChange: () => void) => {\n\t\treturn form.subscribe(onStoreChange);\n\t}).current;\n\n\tuseSyncExternalStore(subscribe, () => form.getState());\n\n\t// Deferred disposal: schedule dispose in a macrotask so StrictMode remount can cancel it\n\tuseEffect(() => {\n\t\tif (disposeTimerRef.current !== null) {\n\t\t\tclearTimeout(disposeTimerRef.current);\n\t\t\tdisposeTimerRef.current = null;\n\t\t}\n\t\treturn () => {\n\t\t\tdisposeTimerRef.current = setTimeout(() => {\n\t\t\t\tformRef.current?.dispose();\n\t\t\t}, 0);\n\t\t};\n\t}, []);\n\n\t// Wrap the form API to auto-focus on submit errors (ADR §12)\n\tconst wrappedApi = useMemo((): FormApi<TData, TUi> => {\n\t\tif (!autoFocus) return form;\n\n\t\treturn {\n\t\t\t...form,\n\t\t\tsubmit: async (...args: Parameters<FormApi<TData, TUi>[\"submit\"]>): Promise<SubmitResult> => {\n\t\t\t\tconst result = await form.submit(...args);\n\t\t\t\tif (!result.ok && result.fieldIssues?.length) {\n\t\t\t\t\tfocusFirstError(result.fieldIssues);\n\t\t\t\t}\n\t\t\t\treturn result;\n\t\t\t},\n\t\t};\n\t}, [form, autoFocus]);\n\n\treturn wrappedApi;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+import { ValidationIssue, FormApi, FieldConfig, FieldApi, CreateFormOptions, FormState } from '@formbar/core';
+export { CreateFormOptions, DeepKeys, DeepValue, FieldApi, FieldConfig, FormAction, FormApi, FormDispatchResult, FormState, SubmitContext, SubmitResult, ValidationIssue, ValidatorFn, ValidatorInput } from '@formbar/core';
+
+/** ARIA props for a form field */
+interface FieldA11yProps {
+    readonly id: string;
+    readonly "aria-invalid"?: boolean;
+    readonly "aria-describedby"?: string;
+    readonly "aria-required"?: boolean;
+    readonly "aria-errormessage"?: string;
+}
+/** Label props for semantic association */
+interface LabelA11yProps {
+    readonly htmlFor: string;
+}
+/** Description/error message props */
+interface DescriptionA11yProps {
+    readonly id: string;
+    readonly role?: "alert";
+}
+/** Generate a deterministic field ID from path */
+declare function fieldId(path: string, prefix?: string): string;
+/** Generate description element ID */
+declare function descriptionId(path: string, prefix?: string): string;
+/** Generate error element ID */
+declare function errorId(path: string, prefix?: string): string;
+/** Get ARIA props for a field input element */
+declare function getFieldProps(path: string, options?: {
+    readonly issues?: readonly ValidationIssue[];
+    readonly required?: boolean;
+    readonly hasDescription?: boolean;
+}): FieldA11yProps;
+/** Get label props for semantic association */
+declare function getLabelProps(path: string): LabelA11yProps;
+/** Get description element props */
+declare function getDescriptionProps(path: string): DescriptionA11yProps;
+/** Get error message props */
+declare function getErrorProps(path: string): DescriptionA11yProps;
+/** Find the first field path with errors (for focus management) */
+declare function findFirstErrorPath(issues: readonly ValidationIssue[]): string | undefined;
+/** Focus the first error field after submit (browser-only) */
+declare function focusFirstError(issues: readonly ValidationIssue[]): boolean;
+
+/**
+ * React hook that subscribes to a specific field with fine-grained re-rendering.
+ * Only re-renders when the field's value or metadata actually changes.
+ *
+ * @param form - The {@link FormApi} instance (from useForm or createForm).
+ * @param path - Dot-path to the field (e.g., `"user.email"`).
+ * @param config - Optional field configuration (label, validators, triggers).
+ * @returns A {@link FieldApi} with reactive get/set, validation, and touch tracking.
+ *
+ * @example
+ * ```typescript
+ * function EmailField({ form }) {
+ *   const field = useField(form, "email");
+ *   return (
+ *     <div>
+ *       <input
+ *         value={field.get() ?? ""}
+ *         onChange={e => field.handleChange(e.target.value)}
+ *         onBlur={() => field.handleBlur()}
+ *       />
+ *       {field.issues().map(i => <span key={i.code}>{i.message}</span>)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useField<TData, TUi, P extends string>(form: FormApi<TData, TUi>, path: P, config?: FieldConfig): FieldApi<TData, TUi, P>;
+
+/** Options for useForm, extending core CreateFormOptions with React-specific behavior */
+interface UseFormOptions<TData, TUi> extends CreateFormOptions<TData, TUi> {
+    /** Auto-focus the first error field on submit failure (default: true) */
+    readonly autoFocusOnError?: boolean;
+}
+/**
+ * React hook that creates and manages a form instance with automatic cleanup.
+ * The form is created once on mount and disposed on unmount (StrictMode-safe).
+ *
+ * @param options - Form configuration (same as {@link createForm} options).
+ * @returns A stable {@link FormApi} reference that persists across re-renders.
+ *
+ * @example
+ * ```typescript
+ * function ContactForm() {
+ *   const form = useForm({
+ *     initialData: { name: "", email: "" },
+ *     onSubmit: async ({ payload }) => {
+ *       await saveContact(payload);
+ *       return { ok: true, submitId: "1" };
+ *     },
+ *   });
+ *
+ *   return <input value={form.field("name").get()} onChange={e => form.field("name").set(e.target.value)} />;
+ * }
+ * ```
+ */
+declare function useForm<TData, TUi>(options?: UseFormOptions<TData, TUi>): FormApi<TData, TUi>;
+
+/**
+ * Subscribe to a derived value from form state with fine-grained reactivity.
+ * Only triggers re-render when the selected value changes (by equality function).
+ *
+ * @param form - The {@link FormApi} instance.
+ * @param selector - Function that extracts a value from the full form state.
+ * @param equalityFn - Optional equality comparator (defaults to `Object.is`).
+ * @returns The current selected value, updated reactively.
+ *
+ * @example
+ * ```typescript
+ * const isValid = useFormSelector(form, (state) => state.issues.length === 0);
+ * const submitCount = useFormSelector(form, (state) => state.meta.submitted);
+ * ```
+ */
+declare function useFormSelector<TData, TUi, T>(form: FormApi<TData, TUi>, selector: (state: FormState<TData, TUi>) => T, equalityFn?: (prev: T, next: T) => boolean): T;
+
+export { type DescriptionA11yProps, type FieldA11yProps, type LabelA11yProps, type UseFormOptions, descriptionId, errorId, fieldId, findFirstErrorPath, focusFirstError, getDescriptionProps, getErrorProps, getFieldProps, getLabelProps, useField, useForm, useFormSelector };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import { ValidationIssue, FormApi, FieldConfig, FieldApi, CreateFormOptions, FormState } from '@formbar/core';
+export { CreateFormOptions, DeepKeys, DeepValue, FieldApi, FieldConfig, FormAction, FormApi, FormDispatchResult, FormState, SubmitContext, SubmitResult, ValidationIssue, ValidatorFn, ValidatorInput } from '@formbar/core';
+
+/** ARIA props for a form field */
+interface FieldA11yProps {
+    readonly id: string;
+    readonly "aria-invalid"?: boolean;
+    readonly "aria-describedby"?: string;
+    readonly "aria-required"?: boolean;
+    readonly "aria-errormessage"?: string;
+}
+/** Label props for semantic association */
+interface LabelA11yProps {
+    readonly htmlFor: string;
+}
+/** Description/error message props */
+interface DescriptionA11yProps {
+    readonly id: string;
+    readonly role?: "alert";
+}
+/** Generate a deterministic field ID from path */
+declare function fieldId(path: string, prefix?: string): string;
+/** Generate description element ID */
+declare function descriptionId(path: string, prefix?: string): string;
+/** Generate error element ID */
+declare function errorId(path: string, prefix?: string): string;
+/** Get ARIA props for a field input element */
+declare function getFieldProps(path: string, options?: {
+    readonly issues?: readonly ValidationIssue[];
+    readonly required?: boolean;
+    readonly hasDescription?: boolean;
+}): FieldA11yProps;
+/** Get label props for semantic association */
+declare function getLabelProps(path: string): LabelA11yProps;
+/** Get description element props */
+declare function getDescriptionProps(path: string): DescriptionA11yProps;
+/** Get error message props */
+declare function getErrorProps(path: string): DescriptionA11yProps;
+/** Find the first field path with errors (for focus management) */
+declare function findFirstErrorPath(issues: readonly ValidationIssue[]): string | undefined;
+/** Focus the first error field after submit (browser-only) */
+declare function focusFirstError(issues: readonly ValidationIssue[]): boolean;
+
+/**
+ * React hook that subscribes to a specific field with fine-grained re-rendering.
+ * Only re-renders when the field's value or metadata actually changes.
+ *
+ * @param form - The {@link FormApi} instance (from useForm or createForm).
+ * @param path - Dot-path to the field (e.g., `"user.email"`).
+ * @param config - Optional field configuration (label, validators, triggers).
+ * @returns A {@link FieldApi} with reactive get/set, validation, and touch tracking.
+ *
+ * @example
+ * ```typescript
+ * function EmailField({ form }) {
+ *   const field = useField(form, "email");
+ *   return (
+ *     <div>
+ *       <input
+ *         value={field.get() ?? ""}
+ *         onChange={e => field.handleChange(e.target.value)}
+ *         onBlur={() => field.handleBlur()}
+ *       />
+ *       {field.issues().map(i => <span key={i.code}>{i.message}</span>)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare function useField<TData, TUi, P extends string>(form: FormApi<TData, TUi>, path: P, config?: FieldConfig): FieldApi<TData, TUi, P>;
+
+/** Options for useForm, extending core CreateFormOptions with React-specific behavior */
+interface UseFormOptions<TData, TUi> extends CreateFormOptions<TData, TUi> {
+    /** Auto-focus the first error field on submit failure (default: true) */
+    readonly autoFocusOnError?: boolean;
+}
+/**
+ * React hook that creates and manages a form instance with automatic cleanup.
+ * The form is created once on mount and disposed on unmount (StrictMode-safe).
+ *
+ * @param options - Form configuration (same as {@link createForm} options).
+ * @returns A stable {@link FormApi} reference that persists across re-renders.
+ *
+ * @example
+ * ```typescript
+ * function ContactForm() {
+ *   const form = useForm({
+ *     initialData: { name: "", email: "" },
+ *     onSubmit: async ({ payload }) => {
+ *       await saveContact(payload);
+ *       return { ok: true, submitId: "1" };
+ *     },
+ *   });
+ *
+ *   return <input value={form.field("name").get()} onChange={e => form.field("name").set(e.target.value)} />;
+ * }
+ * ```
+ */
+declare function useForm<TData, TUi>(options?: UseFormOptions<TData, TUi>): FormApi<TData, TUi>;
+
+/**
+ * Subscribe to a derived value from form state with fine-grained reactivity.
+ * Only triggers re-render when the selected value changes (by equality function).
+ *
+ * @param form - The {@link FormApi} instance.
+ * @param selector - Function that extracts a value from the full form state.
+ * @param equalityFn - Optional equality comparator (defaults to `Object.is`).
+ * @returns The current selected value, updated reactively.
+ *
+ * @example
+ * ```typescript
+ * const isValid = useFormSelector(form, (state) => state.issues.length === 0);
+ * const submitCount = useFormSelector(form, (state) => state.meta.submitted);
+ * ```
+ */
+declare function useFormSelector<TData, TUi, T>(form: FormApi<TData, TUi>, selector: (state: FormState<TData, TUi>) => T, equalityFn?: (prev: T, next: T) => boolean): T;
+
+export { type DescriptionA11yProps, type FieldA11yProps, type LabelA11yProps, type UseFormOptions, descriptionId, errorId, fieldId, findFirstErrorPath, focusFirstError, getDescriptionProps, getErrorProps, getFieldProps, getLabelProps, useField, useForm, useFormSelector };

package/dist/index.js

@@ -0,0 +1,144 @@
+import { useRef, useCallback, useSyncExternalStore, useMemo, useEffect } from 'react';
+import { createForm } from '@formbar/core';
+
+// src/a11y.ts
+var DEFAULT_FIELD_PREFIX = "field";
+function fieldId(path, prefix = DEFAULT_FIELD_PREFIX) {
+  return `${prefix}-${path.replace(/[.[\]/]/g, "-").replace(/-+/g, "-").replace(/-$/, "")}`;
+}
+function descriptionId(path, prefix) {
+  return `${fieldId(path, prefix)}-description`;
+}
+function errorId(path, prefix) {
+  return `${fieldId(path, prefix)}-error`;
+}
+function getFieldProps(path, options) {
+  const id = fieldId(path);
+  const hasErrors = options?.issues?.some((i) => i.severity === "error") ?? false;
+  const describedBy = [];
+  if (options?.hasDescription) describedBy.push(descriptionId(path));
+  if (hasErrors) describedBy.push(errorId(path));
+  const props = {
+    id,
+    ...hasErrors ? { "aria-invalid": true } : {},
+    ...describedBy.length > 0 ? { "aria-describedby": describedBy.join(" ") } : {},
+    ...options?.required ? { "aria-required": true } : {},
+    ...hasErrors ? { "aria-errormessage": errorId(path) } : {}
+  };
+  return props;
+}
+function getLabelProps(path) {
+  return { htmlFor: fieldId(path) };
+}
+function getDescriptionProps(path) {
+  return { id: descriptionId(path) };
+}
+function getErrorProps(path) {
+  return { id: errorId(path), role: "alert" };
+}
+function findFirstErrorPath(issues) {
+  const firstError = issues.find((i) => i.severity === "error");
+  if (!firstError) return void 0;
+  return firstError.path.segments.join(".");
+}
+function focusFirstError(issues) {
+  const path = findFirstErrorPath(issues);
+  if (!path) return false;
+  if (typeof document === "undefined") return false;
+  const id = fieldId(path);
+  const element = document.getElementById(id);
+  if (element) {
+    element.focus();
+    return true;
+  }
+  return false;
+}
+function useFormSelector(form, selector, equalityFn) {
+  const eqRef = useRef(equalityFn ?? Object.is);
+  eqRef.current = equalityFn ?? Object.is;
+  const selectorRef = useRef(selector);
+  selectorRef.current = selector;
+  const prevRef = useRef({
+    value: void 0,
+    initialized: false
+  });
+  const subscribe = useCallback((onStoreChange) => form.subscribe(onStoreChange), [form]);
+  const getSnapshot = useCallback(() => {
+    const next = selectorRef.current(form.getState());
+    if (prevRef.current.initialized && eqRef.current(prevRef.current.value, next)) {
+      return prevRef.current.value;
+    }
+    prevRef.current = { value: next, initialized: true };
+    return next;
+  }, [form]);
+  return useSyncExternalStore(subscribe, getSnapshot);
+}
+
+// src/use-field.ts
+function fieldSnapshotEqual(a, b) {
+  return a.value === b.value && a.meta === b.meta;
+}
+function useField(form, path, config) {
+  const configRef = useRef(config);
+  const stableConfig = useMemo(() => {
+    const prev = configRef.current;
+    if (prev === config) return prev;
+    if (prev && config && JSON.stringify(prev) === JSON.stringify(config)) return prev;
+    configRef.current = config;
+    return config;
+  }, [config]);
+  const field = useMemo(() => form.fieldDynamic(path, stableConfig), [form, path, stableConfig]);
+  useFormSelector(
+    form,
+    () => {
+      const state = form.getState();
+      const pathKey = field.path.segments.join(".");
+      const meta = state.fieldMeta[pathKey];
+      return { value: field.get(), meta };
+    },
+    fieldSnapshotEqual
+  );
+  return field;
+}
+function useForm(options) {
+  const autoFocus = options?.autoFocusOnError ?? true;
+  const formRef = useRef(null);
+  const disposeTimerRef = useRef(null);
+  if (formRef.current === null) {
+    formRef.current = createForm(options);
+  }
+  const form = formRef.current;
+  const subscribe = useRef((onStoreChange) => {
+    return form.subscribe(onStoreChange);
+  }).current;
+  useSyncExternalStore(subscribe, () => form.getState());
+  useEffect(() => {
+    if (disposeTimerRef.current !== null) {
+      clearTimeout(disposeTimerRef.current);
+      disposeTimerRef.current = null;
+    }
+    return () => {
+      disposeTimerRef.current = setTimeout(() => {
+        formRef.current?.dispose();
+      }, 0);
+    };
+  }, []);
+  const wrappedApi = useMemo(() => {
+    if (!autoFocus) return form;
+    return {
+      ...form,
+      submit: async (...args) => {
+        const result = await form.submit(...args);
+        if (!result.ok && result.fieldIssues?.length) {
+          focusFirstError(result.fieldIssues);
+        }
+        return result;
+      }
+    };
+  }, [form, autoFocus]);
+  return wrappedApi;
+}
+
+export { descriptionId, errorId, fieldId, findFirstErrorPath, focusFirstError, getDescriptionProps, getErrorProps, getFieldProps, getLabelProps, useField, useForm, useFormSelector };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/a11y.ts","../src/use-form-selector.ts","../src/use-field.ts","../src/use-form.ts"],"names":["useRef","useSyncExternalStore","useMemo"],"mappings":"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","file":"index.js","sourcesContent":["import type { ValidationIssue } from \"@formbar/core\";\n\nconst DEFAULT_FIELD_PREFIX = \"field\";\n\n/** ARIA props for a form field */\nexport interface FieldA11yProps {\n\treadonly id: string;\n\treadonly \"aria-invalid\"?: boolean;\n\treadonly \"aria-describedby\"?: string;\n\treadonly \"aria-required\"?: boolean;\n\treadonly \"aria-errormessage\"?: string;\n}\n\n/** Label props for semantic association */\nexport interface LabelA11yProps {\n\treadonly htmlFor: string;\n}\n\n/** Description/error message props */\nexport interface DescriptionA11yProps {\n\treadonly id: string;\n\treadonly role?: \"alert\";\n}\n\n/** Generate a deterministic field ID from path */\nexport function fieldId(path: string, prefix: string = DEFAULT_FIELD_PREFIX): string {\n\treturn `${prefix}-${path\n\t\t.replace(/[.[\\]/]/g, \"-\")\n\t\t.replace(/-+/g, \"-\")\n\t\t.replace(/-$/, \"\")}`;\n}\n\n/** Generate description element ID */\nexport function descriptionId(path: string, prefix?: string): string {\n\treturn `${fieldId(path, prefix)}-description`;\n}\n\n/** Generate error element ID */\nexport function errorId(path: string, prefix?: string): string {\n\treturn `${fieldId(path, prefix)}-error`;\n}\n\n/** Get ARIA props for a field input element */\nexport function getFieldProps(\n\tpath: string,\n\toptions?: {\n\t\treadonly issues?: readonly ValidationIssue[];\n\t\treadonly required?: boolean;\n\t\treadonly hasDescription?: boolean;\n\t},\n): FieldA11yProps {\n\tconst id = fieldId(path);\n\tconst hasErrors = options?.issues?.some((i) => i.severity === \"error\") ?? false;\n\n\tconst describedBy: string[] = [];\n\tif (options?.hasDescription) describedBy.push(descriptionId(path));\n\tif (hasErrors) describedBy.push(errorId(path));\n\n\tconst props: FieldA11yProps = {\n\t\tid,\n\t\t...(hasErrors ? { \"aria-invalid\": true as const } : {}),\n\t\t...(describedBy.length > 0 ? { \"aria-describedby\": describedBy.join(\" \") } : {}),\n\t\t...(options?.required ? { \"aria-required\": true as const } : {}),\n\t\t...(hasErrors ? { \"aria-errormessage\": errorId(path) } : {}),\n\t};\n\n\treturn props;\n}\n\n/** Get label props for semantic association */\nexport function getLabelProps(path: string): LabelA11yProps {\n\treturn { htmlFor: fieldId(path) };\n}\n\n/** Get description element props */\nexport function getDescriptionProps(path: string): DescriptionA11yProps {\n\treturn { id: descriptionId(path) };\n}\n\n/** Get error message props */\nexport function getErrorProps(path: string): DescriptionA11yProps {\n\treturn { id: errorId(path), role: \"alert\" };\n}\n\n/** Find the first field path with errors (for focus management) */\nexport function findFirstErrorPath(issues: readonly ValidationIssue[]): string | undefined {\n\tconst firstError = issues.find((i) => i.severity === \"error\");\n\tif (!firstError) return undefined;\n\treturn firstError.path.segments.join(\".\");\n}\n\n/** Focus the first error field after submit (browser-only) */\nexport function focusFirstError(issues: readonly ValidationIssue[]): boolean {\n\tconst path = findFirstErrorPath(issues);\n\tif (!path) return false;\n\n\tif (typeof document === \"undefined\") return false;\n\n\tconst id = fieldId(path);\n\tconst element = document.getElementById(id);\n\tif (element) {\n\t\telement.focus();\n\t\treturn true;\n\t}\n\treturn false;\n}\n","import type { FormApi, FormState } from \"@formbar/core\";\nimport { useCallback, useRef, useSyncExternalStore } from \"react\";\n\n/**\n * Subscribe to a derived value from form state with fine-grained reactivity.\n * Only triggers re-render when the selected value changes (by equality function).\n *\n * @param form - The {@link FormApi} instance.\n * @param selector - Function that extracts a value from the full form state.\n * @param equalityFn - Optional equality comparator (defaults to `Object.is`).\n * @returns The current selected value, updated reactively.\n *\n * @example\n * ```typescript\n * const isValid = useFormSelector(form, (state) => state.issues.length === 0);\n * const submitCount = useFormSelector(form, (state) => state.meta.submitted);\n * ```\n */\nexport function useFormSelector<TData, TUi, T>(\n\tform: FormApi<TData, TUi>,\n\tselector: (state: FormState<TData, TUi>) => T,\n\tequalityFn?: (prev: T, next: T) => boolean,\n): T {\n\tconst eqRef = useRef(equalityFn ?? Object.is);\n\teqRef.current = equalityFn ?? Object.is;\n\n\tconst selectorRef = useRef(selector);\n\tselectorRef.current = selector;\n\n\tconst prevRef = useRef<{ readonly value: T; readonly initialized: boolean }>({\n\t\tvalue: undefined as T,\n\t\tinitialized: false,\n\t});\n\n\tconst subscribe = useCallback((onStoreChange: () => void) => form.subscribe(onStoreChange), [form]);\n\n\tconst getSnapshot = useCallback((): T => {\n\t\tconst next = selectorRef.current(form.getState());\n\t\tif (prevRef.current.initialized && eqRef.current(prevRef.current.value, next)) {\n\t\t\treturn prevRef.current.value;\n\t\t}\n\t\tprevRef.current = { value: next, initialized: true };\n\t\treturn next;\n\t}, [form]);\n\n\treturn useSyncExternalStore(subscribe, getSnapshot);\n}\n","import type { FieldApi, FieldConfig, FieldMetaEntry, FormApi } from \"@formbar/core\";\nimport { useMemo, useRef } from \"react\";\nimport { useFormSelector } from \"./use-form-selector.js\";\n\ninterface FieldSnapshot {\n\treadonly value: unknown;\n\treadonly meta: FieldMetaEntry | undefined;\n}\n\nfunction fieldSnapshotEqual(a: FieldSnapshot, b: FieldSnapshot): boolean {\n\treturn a.value === b.value && a.meta === b.meta;\n}\n\n/**\n * React hook that subscribes to a specific field with fine-grained re-rendering.\n * Only re-renders when the field's value or metadata actually changes.\n *\n * @param form - The {@link FormApi} instance (from useForm or createForm).\n * @param path - Dot-path to the field (e.g., `\"user.email\"`).\n * @param config - Optional field configuration (label, validators, triggers).\n * @returns A {@link FieldApi} with reactive get/set, validation, and touch tracking.\n *\n * @example\n * ```typescript\n * function EmailField({ form }) {\n *   const field = useField(form, \"email\");\n *   return (\n *     <div>\n *       <input\n *         value={field.get() ?? \"\"}\n *         onChange={e => field.handleChange(e.target.value)}\n *         onBlur={() => field.handleBlur()}\n *       />\n *       {field.issues().map(i => <span key={i.code}>{i.message}</span>)}\n *     </div>\n *   );\n * }\n * ```\n */\nexport function useField<TData, TUi, P extends string>(\n\tform: FormApi<TData, TUi>,\n\tpath: P,\n\tconfig?: FieldConfig,\n): FieldApi<TData, TUi, P> {\n\t// Stabilize config reference — inline objects create new references every render\n\tconst configRef = useRef(config);\n\tconst stableConfig = useMemo(() => {\n\t\tconst prev = configRef.current;\n\t\tif (prev === config) return prev;\n\t\tif (prev && config && JSON.stringify(prev) === JSON.stringify(config)) return prev;\n\t\tconfigRef.current = config;\n\t\treturn config;\n\t}, [config]);\n\n\tconst field = useMemo(() => form.fieldDynamic(path, stableConfig), [form, path, stableConfig]);\n\n\t// Subscribe to field value and touched state to trigger re-renders\n\tuseFormSelector(\n\t\tform,\n\t\t() => {\n\t\t\tconst state = form.getState();\n\t\t\tconst pathKey = field.path.segments.join(\".\");\n\t\t\tconst meta = (state.fieldMeta as Readonly<Record<string, FieldMetaEntry>>)[pathKey];\n\t\t\treturn { value: field.get(), meta } as FieldSnapshot;\n\t\t},\n\t\tfieldSnapshotEqual,\n\t);\n\n\treturn field as FieldApi<TData, TUi, P>;\n}\n","import type { CreateFormOptions, FormApi, SubmitResult } from \"@formbar/core\";\nimport { createForm } from \"@formbar/core\";\nimport { useEffect, useMemo, useRef, useSyncExternalStore } from \"react\";\nimport { focusFirstError } from \"./a11y.js\";\n\n/** Options for useForm, extending core CreateFormOptions with React-specific behavior */\nexport interface UseFormOptions<TData, TUi> extends CreateFormOptions<TData, TUi> {\n\t/** Auto-focus the first error field on submit failure (default: true) */\n\treadonly autoFocusOnError?: boolean;\n}\n\n/**\n * React hook that creates and manages a form instance with automatic cleanup.\n * The form is created once on mount and disposed on unmount (StrictMode-safe).\n *\n * @param options - Form configuration (same as {@link createForm} options).\n * @returns A stable {@link FormApi} reference that persists across re-renders.\n *\n * @example\n * ```typescript\n * function ContactForm() {\n *   const form = useForm({\n *     initialData: { name: \"\", email: \"\" },\n *     onSubmit: async ({ payload }) => {\n *       await saveContact(payload);\n *       return { ok: true, submitId: \"1\" };\n *     },\n *   });\n *\n *   return <input value={form.field(\"name\").get()} onChange={e => form.field(\"name\").set(e.target.value)} />;\n * }\n * ```\n */\nexport function useForm<TData, TUi>(options?: UseFormOptions<TData, TUi>): FormApi<TData, TUi> {\n\tconst autoFocus = options?.autoFocusOnError ?? true;\n\tconst formRef = useRef<FormApi<TData, TUi> | null>(null);\n\tconst disposeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);\n\n\tif (formRef.current === null) {\n\t\tformRef.current = createForm<TData, TUi>(options);\n\t}\n\n\tconst form = formRef.current;\n\n\t// Adapt form.subscribe (which passes state) to useSyncExternalStore's expected signature\n\tconst subscribe = useRef((onStoreChange: () => void) => {\n\t\treturn form.subscribe(onStoreChange);\n\t}).current;\n\n\tuseSyncExternalStore(subscribe, () => form.getState());\n\n\t// Deferred disposal: schedule dispose in a macrotask so StrictMode remount can cancel it\n\tuseEffect(() => {\n\t\tif (disposeTimerRef.current !== null) {\n\t\t\tclearTimeout(disposeTimerRef.current);\n\t\t\tdisposeTimerRef.current = null;\n\t\t}\n\t\treturn () => {\n\t\t\tdisposeTimerRef.current = setTimeout(() => {\n\t\t\t\tformRef.current?.dispose();\n\t\t\t}, 0);\n\t\t};\n\t}, []);\n\n\t// Wrap the form API to auto-focus on submit errors (ADR §12)\n\tconst wrappedApi = useMemo((): FormApi<TData, TUi> => {\n\t\tif (!autoFocus) return form;\n\n\t\treturn {\n\t\t\t...form,\n\t\t\tsubmit: async (...args: Parameters<FormApi<TData, TUi>[\"submit\"]>): Promise<SubmitResult> => {\n\t\t\t\tconst result = await form.submit(...args);\n\t\t\t\tif (!result.ok && result.fieldIssues?.length) {\n\t\t\t\t\tfocusFirstError(result.fieldIssues);\n\t\t\t\t}\n\t\t\t\treturn result;\n\t\t\t},\n\t\t};\n\t}, [form, autoFocus]);\n\n\treturn wrappedApi;\n}\n"]}

package/package.json

@@ -0,0 +1,37 @@
+{
+	"name": "@formbar/react",
+	"version": "0.2.0",
+	"type": "module",
+	"description": "React hooks and a11y utilities for @formbar/core",
+	"license": "MIT",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist",
+		"src"
+	],
+	"sideEffects": false,
+	"scripts": {
+		"build": "tsc --noEmit",
+		"build:dist": "tsup",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@formbar/core": "workspace:*"
+	},
+	"peerDependencies": {
+		"react": ">=18.0.0"
+	},
+	"devDependencies": {
+		"@types/react": "^19.0.0",
+		"react": "^19.0.0"
+	}
+}

package/src/__tests__/a11y.test.ts

@@ -0,0 +1,114 @@
+import { describe, expect, test } from "vitest";
+import {
+	descriptionId,
+	errorId,
+	fieldId,
+	findFirstErrorPath,
+	getDescriptionProps,
+	getErrorProps,
+	getFieldProps,
+	getLabelProps,
+} from "../index.js";
+
+describe("a11y helpers", () => {
+	test("fieldId generates deterministic ID from path", () => {
+		expect(fieldId("name")).toBe("field-name");
+		expect(fieldId("address.city")).toBe("field-address-city");
+		expect(fieldId("items[0].name")).toBe("field-items-0-name");
+	});
+
+	test("descriptionId derives from fieldId", () => {
+		expect(descriptionId("name")).toBe("field-name-description");
+	});
+
+	test("errorId derives from fieldId", () => {
+		expect(errorId("name")).toBe("field-name-error");
+	});
+
+	test("getFieldProps without issues", () => {
+		const props = getFieldProps("name");
+		expect(props.id).toBe("field-name");
+		expect(props["aria-invalid"]).toBeUndefined();
+	});
+
+	test("getFieldProps with error issues sets aria-invalid", () => {
+		const issues = [
+			{
+				code: "required",
+				message: "Required",
+				severity: "error" as const,
+				stage: "draft",
+				path: { namespace: "data" as const, segments: ["name"] },
+				source: { origin: "function-validator" as const, validatorId: "test" },
+			},
+		];
+		const props = getFieldProps("name", { issues });
+		expect(props["aria-invalid"]).toBe(true);
+		expect(props["aria-describedby"]).toBe("field-name-error");
+	});
+
+	test("getFieldProps with description and errors", () => {
+		const issues = [
+			{
+				code: "required",
+				message: "Required",
+				severity: "error" as const,
+				stage: "draft",
+				path: { namespace: "data" as const, segments: ["name"] },
+				source: { origin: "function-validator" as const, validatorId: "test" },
+			},
+		];
+		const props = getFieldProps("name", { issues, hasDescription: true });
+		expect(props["aria-describedby"]).toBe("field-name-description field-name-error");
+	});
+
+	test("getFieldProps with required", () => {
+		const props = getFieldProps("name", { required: true });
+		expect(props["aria-required"]).toBe(true);
+	});
+
+	test("getLabelProps generates htmlFor", () => {
+		expect(getLabelProps("name").htmlFor).toBe("field-name");
+	});
+
+	test("getDescriptionProps generates id", () => {
+		expect(getDescriptionProps("name").id).toBe("field-name-description");
+	});
+
+	test("getErrorProps generates id with alert role", () => {
+		const props = getErrorProps("name");
+		expect(props.id).toBe("field-name-error");
+		expect(props.role).toBe("alert");
+	});
+
+	test("findFirstErrorPath returns first error path", () => {
+		const issues = [
+			{
+				code: "required",
+				message: "Required",
+				severity: "warning" as const,
+				stage: "draft",
+				path: { namespace: "data" as const, segments: ["email"] },
+				source: { origin: "function-validator" as const, validatorId: "test" },
+			},
+			{
+				code: "required",
+				message: "Required",
+				severity: "error" as const,
+				stage: "draft",
+				path: { namespace: "data" as const, segments: ["name"] },
+				source: { origin: "function-validator" as const, validatorId: "test" },
+			},
+		];
+		expect(findFirstErrorPath(issues)).toBe("name");
+	});
+
+	test("findFirstErrorPath returns undefined when no errors", () => {
+		expect(findFirstErrorPath([])).toBeUndefined();
+	});
+
+	test("focusFirstError returns false without document", async () => {
+		const { focusFirstError } = await import("../a11y.js");
+		expect(focusFirstError([])).toBe(false);
+	});
+});

package/src/__tests__/boundary-exports.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+
+describe("@formbar/react public API surface", () => {
+	it("exports expected symbols from main entry", async () => {
+		const mod = await import("../index.js");
+		const exports = Object.keys(mod).sort();
+
+		expect(exports).toEqual(
+			expect.arrayContaining(["useForm", "useField", "useFormSelector", "getFieldProps", "getLabelProps"]),
+		);
+	});
+
+	it("does not export schema-driven symbols (moved to @formbar/react-schema)", async () => {
+		const mod = await import("../index.js");
+		const exports = Object.keys(mod);
+
+		expect(exports).not.toContain("useSchemaForm");
+		expect(exports).not.toContain("RendererRegistry");
+		expect(exports).not.toContain("renderLayoutTree");
+	});
+});

package/src/__tests__/selector.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "vitest";
+import { useField, useFormSelector } from "../index.js";
+
+describe("useFormSelector", () => {
+	test("is exported as a function", () => {
+		expect(typeof useFormSelector).toBe("function");
+	});
+});
+
+describe("useField", () => {
+	test("is exported as a function", () => {
+		expect(typeof useField).toBe("function");
+	});
+});

package/src/__tests__/use-form.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, test } from "vitest";
+import { type UseFormOptions, useForm } from "../index.js";
+
+describe("useForm", () => {
+	test("is exported as a function", () => {
+		expect(typeof useForm).toBe("function");
+	});
+
+	test("accepts an optional options parameter", () => {
+		expect(useForm.length).toBe(1);
+	});
+
+	test("UseFormOptions type is exported", () => {
+		// Type-level check: UseFormOptions should be importable
+		const opts: UseFormOptions = { autoFocusOnError: false };
+		expect(opts.autoFocusOnError).toBe(false);
+	});
+
+	test("UseFormOptions defaults autoFocusOnError to true", () => {
+		const opts: UseFormOptions = {};
+		expect(opts.autoFocusOnError).toBeUndefined();
+		// The hook defaults undefined to true internally
+	});
+});

package/src/a11y.ts

@@ -0,0 +1,106 @@
+import type { ValidationIssue } from "@formbar/core";
+
+const DEFAULT_FIELD_PREFIX = "field";
+
+/** ARIA props for a form field */
+export interface FieldA11yProps {
+	readonly id: string;
+	readonly "aria-invalid"?: boolean;
+	readonly "aria-describedby"?: string;
+	readonly "aria-required"?: boolean;
+	readonly "aria-errormessage"?: string;
+}
+
+/** Label props for semantic association */
+export interface LabelA11yProps {
+	readonly htmlFor: string;
+}
+
+/** Description/error message props */
+export interface DescriptionA11yProps {
+	readonly id: string;
+	readonly role?: "alert";
+}
+
+/** Generate a deterministic field ID from path */
+export function fieldId(path: string, prefix: string = DEFAULT_FIELD_PREFIX): string {
+	return `${prefix}-${path
+		.replace(/[.[\]/]/g, "-")
+		.replace(/-+/g, "-")
+		.replace(/-$/, "")}`;
+}
+
+/** Generate description element ID */
+export function descriptionId(path: string, prefix?: string): string {
+	return `${fieldId(path, prefix)}-description`;
+}
+
+/** Generate error element ID */
+export function errorId(path: string, prefix?: string): string {
+	return `${fieldId(path, prefix)}-error`;
+}
+
+/** Get ARIA props for a field input element */
+export function getFieldProps(
+	path: string,
+	options?: {
+		readonly issues?: readonly ValidationIssue[];
+		readonly required?: boolean;
+		readonly hasDescription?: boolean;
+	},
+): FieldA11yProps {
+	const id = fieldId(path);
+	const hasErrors = options?.issues?.some((i) => i.severity === "error") ?? false;
+
+	const describedBy: string[] = [];
+	if (options?.hasDescription) describedBy.push(descriptionId(path));
+	if (hasErrors) describedBy.push(errorId(path));
+
+	const props: FieldA11yProps = {
+		id,
+		...(hasErrors ? { "aria-invalid": true as const } : {}),
+		...(describedBy.length > 0 ? { "aria-describedby": describedBy.join(" ") } : {}),
+		...(options?.required ? { "aria-required": true as const } : {}),
+		...(hasErrors ? { "aria-errormessage": errorId(path) } : {}),
+	};
+
+	return props;
+}
+
+/** Get label props for semantic association */
+export function getLabelProps(path: string): LabelA11yProps {
+	return { htmlFor: fieldId(path) };
+}
+
+/** Get description element props */
+export function getDescriptionProps(path: string): DescriptionA11yProps {
+	return { id: descriptionId(path) };
+}
+
+/** Get error message props */
+export function getErrorProps(path: string): DescriptionA11yProps {
+	return { id: errorId(path), role: "alert" };
+}
+
+/** Find the first field path with errors (for focus management) */
+export function findFirstErrorPath(issues: readonly ValidationIssue[]): string | undefined {
+	const firstError = issues.find((i) => i.severity === "error");
+	if (!firstError) return undefined;
+	return firstError.path.segments.join(".");
+}
+
+/** Focus the first error field after submit (browser-only) */
+export function focusFirstError(issues: readonly ValidationIssue[]): boolean {
+	const path = findFirstErrorPath(issues);
+	if (!path) return false;
+
+	if (typeof document === "undefined") return false;
+
+	const id = fieldId(path);
+	const element = document.getElementById(id);
+	if (element) {
+		element.focus();
+		return true;
+	}
+	return false;
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+// Re-export core types that React consumers need
+export type {
+	CreateFormOptions,
+	DeepKeys,
+	DeepValue,
+	FieldApi,
+	FieldConfig,
+	FormAction,
+	FormApi,
+	FormDispatchResult,
+	FormState,
+	SubmitContext,
+	SubmitResult,
+	ValidationIssue,
+	ValidatorFn,
+	ValidatorInput,
+} from "@formbar/core";
+export {
+	type DescriptionA11yProps,
+	descriptionId,
+	errorId,
+	type FieldA11yProps,
+	fieldId,
+	findFirstErrorPath,
+	focusFirstError,
+	getDescriptionProps,
+	getErrorProps,
+	getFieldProps,
+	getLabelProps,
+	type LabelA11yProps,
+} from "./a11y.js";
+export { useField } from "./use-field.js";
+export { type UseFormOptions, useForm } from "./use-form.js";
+export { useFormSelector } from "./use-form-selector.js";

package/src/use-field.ts

@@ -0,0 +1,70 @@
+import type { FieldApi, FieldConfig, FieldMetaEntry, FormApi } from "@formbar/core";
+import { useMemo, useRef } from "react";
+import { useFormSelector } from "./use-form-selector.js";
+
+interface FieldSnapshot {
+	readonly value: unknown;
+	readonly meta: FieldMetaEntry | undefined;
+}
+
+function fieldSnapshotEqual(a: FieldSnapshot, b: FieldSnapshot): boolean {
+	return a.value === b.value && a.meta === b.meta;
+}
+
+/**
+ * React hook that subscribes to a specific field with fine-grained re-rendering.
+ * Only re-renders when the field's value or metadata actually changes.
+ *
+ * @param form - The {@link FormApi} instance (from useForm or createForm).
+ * @param path - Dot-path to the field (e.g., `"user.email"`).
+ * @param config - Optional field configuration (label, validators, triggers).
+ * @returns A {@link FieldApi} with reactive get/set, validation, and touch tracking.
+ *
+ * @example
+ * ```typescript
+ * function EmailField({ form }) {
+ *   const field = useField(form, "email");
+ *   return (
+ *     <div>
+ *       <input
+ *         value={field.get() ?? ""}
+ *         onChange={e => field.handleChange(e.target.value)}
+ *         onBlur={() => field.handleBlur()}
+ *       />
+ *       {field.issues().map(i => <span key={i.code}>{i.message}</span>)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export function useField<TData, TUi, P extends string>(
+	form: FormApi<TData, TUi>,
+	path: P,
+	config?: FieldConfig,
+): FieldApi<TData, TUi, P> {
+	// Stabilize config reference — inline objects create new references every render
+	const configRef = useRef(config);
+	const stableConfig = useMemo(() => {
+		const prev = configRef.current;
+		if (prev === config) return prev;
+		if (prev && config && JSON.stringify(prev) === JSON.stringify(config)) return prev;
+		configRef.current = config;
+		return config;
+	}, [config]);
+
+	const field = useMemo(() => form.fieldDynamic(path, stableConfig), [form, path, stableConfig]);
+
+	// Subscribe to field value and touched state to trigger re-renders
+	useFormSelector(
+		form,
+		() => {
+			const state = form.getState();
+			const pathKey = field.path.segments.join(".");
+			const meta = (state.fieldMeta as Readonly<Record<string, FieldMetaEntry>>)[pathKey];
+			return { value: field.get(), meta } as FieldSnapshot;
+		},
+		fieldSnapshotEqual,
+	);
+
+	return field as FieldApi<TData, TUi, P>;
+}

package/src/use-form-selector.ts

@@ -0,0 +1,47 @@
+import type { FormApi, FormState } from "@formbar/core";
+import { useCallback, useRef, useSyncExternalStore } from "react";
+
+/**
+ * Subscribe to a derived value from form state with fine-grained reactivity.
+ * Only triggers re-render when the selected value changes (by equality function).
+ *
+ * @param form - The {@link FormApi} instance.
+ * @param selector - Function that extracts a value from the full form state.
+ * @param equalityFn - Optional equality comparator (defaults to `Object.is`).
+ * @returns The current selected value, updated reactively.
+ *
+ * @example
+ * ```typescript
+ * const isValid = useFormSelector(form, (state) => state.issues.length === 0);
+ * const submitCount = useFormSelector(form, (state) => state.meta.submitted);
+ * ```
+ */
+export function useFormSelector<TData, TUi, T>(
+	form: FormApi<TData, TUi>,
+	selector: (state: FormState<TData, TUi>) => T,
+	equalityFn?: (prev: T, next: T) => boolean,
+): T {
+	const eqRef = useRef(equalityFn ?? Object.is);
+	eqRef.current = equalityFn ?? Object.is;
+
+	const selectorRef = useRef(selector);
+	selectorRef.current = selector;
+
+	const prevRef = useRef<{ readonly value: T; readonly initialized: boolean }>({
+		value: undefined as T,
+		initialized: false,
+	});
+
+	const subscribe = useCallback((onStoreChange: () => void) => form.subscribe(onStoreChange), [form]);
+
+	const getSnapshot = useCallback((): T => {
+		const next = selectorRef.current(form.getState());
+		if (prevRef.current.initialized && eqRef.current(prevRef.current.value, next)) {
+			return prevRef.current.value;
+		}
+		prevRef.current = { value: next, initialized: true };
+		return next;
+	}, [form]);
+
+	return useSyncExternalStore(subscribe, getSnapshot);
+}

package/src/use-form.ts

@@ -0,0 +1,82 @@
+import type { CreateFormOptions, FormApi, SubmitResult } from "@formbar/core";
+import { createForm } from "@formbar/core";
+import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+import { focusFirstError } from "./a11y.js";
+
+/** Options for useForm, extending core CreateFormOptions with React-specific behavior */
+export interface UseFormOptions<TData, TUi> extends CreateFormOptions<TData, TUi> {
+	/** Auto-focus the first error field on submit failure (default: true) */
+	readonly autoFocusOnError?: boolean;
+}
+
+/**
+ * React hook that creates and manages a form instance with automatic cleanup.
+ * The form is created once on mount and disposed on unmount (StrictMode-safe).
+ *
+ * @param options - Form configuration (same as {@link createForm} options).
+ * @returns A stable {@link FormApi} reference that persists across re-renders.
+ *
+ * @example
+ * ```typescript
+ * function ContactForm() {
+ *   const form = useForm({
+ *     initialData: { name: "", email: "" },
+ *     onSubmit: async ({ payload }) => {
+ *       await saveContact(payload);
+ *       return { ok: true, submitId: "1" };
+ *     },
+ *   });
+ *
+ *   return <input value={form.field("name").get()} onChange={e => form.field("name").set(e.target.value)} />;
+ * }
+ * ```
+ */
+export function useForm<TData, TUi>(options?: UseFormOptions<TData, TUi>): FormApi<TData, TUi> {
+	const autoFocus = options?.autoFocusOnError ?? true;
+	const formRef = useRef<FormApi<TData, TUi> | null>(null);
+	const disposeTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+	if (formRef.current === null) {
+		formRef.current = createForm<TData, TUi>(options);
+	}
+
+	const form = formRef.current;
+
+	// Adapt form.subscribe (which passes state) to useSyncExternalStore's expected signature
+	const subscribe = useRef((onStoreChange: () => void) => {
+		return form.subscribe(onStoreChange);
+	}).current;
+
+	useSyncExternalStore(subscribe, () => form.getState());
+
+	// Deferred disposal: schedule dispose in a macrotask so StrictMode remount can cancel it
+	useEffect(() => {
+		if (disposeTimerRef.current !== null) {
+			clearTimeout(disposeTimerRef.current);
+			disposeTimerRef.current = null;
+		}
+		return () => {
+			disposeTimerRef.current = setTimeout(() => {
+				formRef.current?.dispose();
+			}, 0);
+		};
+	}, []);
+
+	// Wrap the form API to auto-focus on submit errors (ADR §12)
+	const wrappedApi = useMemo((): FormApi<TData, TUi> => {
+		if (!autoFocus) return form;
+
+		return {
+			...form,
+			submit: async (...args: Parameters<FormApi<TData, TUi>["submit"]>): Promise<SubmitResult> => {
+				const result = await form.submit(...args);
+				if (!result.ok && result.fieldIssues?.length) {
+					focusFirstError(result.fieldIssues);
+				}
+				return result;
+			},
+		};
+	}, [form, autoFocus]);
+
+	return wrappedApi;
+}