@cleverbrush/react-form 0.0.0-beta-20260410073748

package/README.md

@@ -0,0 +1,624 @@
+# @cleverbrush/react-form
+
+[![CI](https://github.com/cleverbrush/framework/actions/workflows/ci.yml/badge.svg)](https://github.com/cleverbrush/framework/actions/workflows/ci.yml)
+[![License: BSD-3-Clause](https://img.shields.io/badge/license-BSD--3--Clause-blue.svg)](../../LICENSE)
+<!-- coverage-badge-start -->
+![Coverage](https://img.shields.io/badge/coverage-96.1%25-brightgreen)
+<!-- coverage-badge-end -->
+
+A headless, schema-driven form system for React based on `@cleverbrush/schema`. Uses PropertyDescriptors for type-safe field binding, supports global UI renderer configuration via a provider, and is completely UI-agnostic — works with plain HTML, MUI, Ant Design, or any component library.
+
+## Why @cleverbrush/react-form?
+
+**The problem:** Every popular React form library — React Hook Form, Formik, React Final Form — requires you to reference fields by **string names**: `register("email")`, `<Field name="address.city" />`. The moment you pass a field name as a string, you lose TypeScript's type safety. Rename a property in your data model and the compiler stays silent — your form just silently breaks at runtime. The larger your codebase, the more of these invisible string references you accumulate, and the more fragile every refactor becomes.
+
+```tsx
+// React Hook Form — field names are plain strings
+const { register } = useForm<User>();
+<input {...register("name")} />     // ← no compiler error if "name" is renamed
+<input {...register("emial")} />    // ← typo: silently fails at runtime
+
+// Formik — same problem
+<Field name="address.city" />       // ← rename "city" → "town" and nothing warns you
+```
+
+**The solution:** `@cleverbrush/react-form` binds fields via **PropertyDescriptor selectors** — actual TypeScript expressions like `(t) => t.address.city` — instead of strings. The compiler knows the exact shape of your schema, so a renamed or mistyped property is a **compile-time error**, not a runtime surprise. On top of that, the schema **IS** the validation, the type definition, **AND** the form field configuration. One source of truth.
+
+```tsx
+// @cleverbrush/react-form — fully type-safe selectors
+<Field forProperty={(t) => t.name} form={form} />           // ✓ checked at compile time
+<Field forProperty={(t) => t.address.city} form={form} />   // ✓ rename "city" → compiler error
+<Field forProperty={(t) => t.emial} form={form} />          // ✗ compile error: "emial" doesn't exist
+```
+
+**What makes it different:**
+
+| Feature | @cleverbrush/react-form | React Hook Form | Formik | React Final Form |
+| --- | --- | --- | --- | --- |
+| Schema-driven validation | ✓ built-in | ~ via resolver | ~ via plugin | ✗ |
+| Single source of truth (types + validation) | ✓ | ✗ | ✗ | ✗ |
+| Type-safe field selectors | ✓ | ~ | ✗ | ✗ |
+| Headless / UI-agnostic | ✓ | ✓ | ~ | ✓ |
+| Global renderer system | ✓ | ✗ | ✗ | ✗ |
+| Auto-field rendering by type + variant | ✓ | ✗ | ✗ | ✗ |
+| Nested objects | ✓ | ✓ | ✓ | ✓ |
+| Async validation | ✓ | ✓ | ✓ | ✓ |
+
+## Installation
+
+```bash
+npm install @cleverbrush/react-form
+```
+
+**Peer dependencies:** `react >=18`, `@cleverbrush/schema ^2.0.0`
+
+## Quick Start
+
+```tsx
+import { object, string, number } from '@cleverbrush/schema';
+import { useSchemaForm, FormSystemProvider, Field } from '@cleverbrush/react-form';
+
+// 1. Define schema — reuse across forms, API validation, mapping, etc.
+const ContactSchema = object({
+    name:  string().required('Name is required').minLength(2, 'Name must be at least 2 characters'),
+    email: string().required('Email is required'),
+    age:   number().required('Age is required').min(18, 'Must be at least 18')
+});
+
+// 2. Define renderers once per app — maps schema types to UI components
+const renderers = {
+    string: ({ value, onChange, onBlur, error, touched }) => (
+        <div>
+            <input
+                type="text"
+                value={value ?? ''}
+                onChange={(e) => onChange(e.target.value)}
+                onBlur={onBlur}
+            />
+            {touched && error && <span className="error">{error}</span>}
+        </div>
+    ),
+    number: ({ value, onChange, onBlur, error, touched }) => (
+        <div>
+            <input
+                type="number"
+                value={value ?? ''}
+                onChange={(e) => onChange(Number(e.target.value))}
+                onBlur={onBlur}
+            />
+            {touched && error && <span className="error">{error}</span>}
+        </div>
+    )
+};
+
+// 3. Each form component only picks which fields to show — no boilerplate
+function ContactForm() {
+    const form = useSchemaForm(ContactSchema);
+
+    const handleSubmit = async () => {
+        const result = await form.submit();
+        if (result.valid) {
+            console.log('Submitted:', result.object);
+        }
+    };
+
+    return (
+        <div>
+            <Field forProperty={(t) => t.name} form={form} />
+            <Field forProperty={(t) => t.email} form={form} />
+            <Field forProperty={(t) => t.age} form={form} />
+            <button onClick={handleSubmit}>Submit</button>
+        </div>
+    );
+}
+
+// 4. Wrap once at the app root — all forms below share the renderers
+function App() {
+    return (
+        <FormSystemProvider renderers={renderers}>
+            <ContactForm />
+        </FormSystemProvider>
+    );
+}
+```
+
+## How It Works — Step by Step
+
+1. **Define a schema** using `@cleverbrush/schema` — this is your single source of truth for types, validation rules, and field metadata
+2. **Register renderers** via `FormSystemProvider` — plain functions that map schema types (`"string"`, `"number"`, `"boolean"`) to your UI components (plain HTML, MUI, Ant Design, etc.)
+3. **Create a form instance** via `useSchemaForm(schema)` — returns state management, validation, submit/reset lifecycle
+4. **Render fields** via `<Field forProperty={(t) => t.name} form={form} />` — the component looks up the registered renderer for the field's schema type
+5. **Submit** — `form.submit()` runs the schema's full validation and returns a typed result
+
+## Core Concepts
+
+| Part | Responsibility | When to Use |
+|------|---------------|-------------|
+| **FormSystemProvider** | Global renderer registry via React Context | Once at the app root |
+| **useSchemaForm** | Per-schema form instance (state, validation, lifecycle) | In every component that needs a form |
+| **useField** | Descriptor-based field binding (value, dirty, touched, error) | When you want fine-grained control |
+| **Field** | UI-agnostic component that resolves renderers by schema type | For most form fields — quick and declarative |
+
+## Registering Renderers
+
+Renderers are plain functions that receive field state and return React nodes. Define a renderer map keyed by schema type (`string`, `number`, `boolean`, etc.):
+
+### Plain HTML
+
+```tsx
+import { FieldRenderProps } from '@cleverbrush/react-form';
+
+const htmlRenderers = {
+    string: ({ value, onChange, onBlur, error, touched, label, name, fieldProps }: FieldRenderProps) => (
+        <div>
+            {label && <label>{label}</label>}
+            <input
+                type="text"
+                name={name}
+                value={value ?? ''}
+                onChange={(e) => onChange(e.target.value)}
+                onBlur={onBlur}
+                {...fieldProps}
+            />
+            {touched && error && <span className="error">{error}</span>}
+        </div>
+    ),
+    number: ({ value, onChange, onBlur, error, touched, label, name, fieldProps }: FieldRenderProps) => (
+        <div>
+            {label && <label>{label}</label>}
+            <input
+                type="number"
+                name={name}
+                value={value ?? ''}
+                onChange={(e) => onChange(Number(e.target.value))}
+                onBlur={onBlur}
+                {...fieldProps}
+            />
+            {touched && error && <span className="error">{error}</span>}
+        </div>
+    ),
+    boolean: ({ value, onChange, label }: FieldRenderProps) => (
+        <label>
+            <input
+                type="checkbox"
+                checked={value ?? false}
+                onChange={(e) => onChange(e.target.checked)}
+            />
+            {label}
+        </label>
+    )
+};
+```
+
+### Variant Renderers
+
+You can register renderers for specific variants using a `"type:variant"` key.
+When `<Field variant="password" />` is rendered on a `string` field, the
+registry is checked for `"string:password"` first, then falls back to `"string"`:
+
+```tsx
+const renderers = {
+    // Default string renderer
+    string: ({ value, onChange, onBlur, error, touched, label, name, fieldProps }: FieldRenderProps) => (
+        <div>
+            {label && <label>{label}</label>}
+            <input type="text" name={name} value={value ?? ''}
+                   onChange={(e) => onChange(e.target.value)} onBlur={onBlur}
+                   {...fieldProps} />
+            {touched && error && <span className="error">{error}</span>}
+        </div>
+    ),
+    // Password variant — rendered when <Field variant="password" /> is used on a string field
+    'string:password': ({ value, onChange, onBlur, error, touched, label, name, fieldProps }: FieldRenderProps) => (
+        <div>
+            {label && <label>{label}</label>}
+            <input type="password" name={name} value={value ?? ''}
+                   onChange={(e) => onChange(e.target.value)} onBlur={onBlur}
+                   {...fieldProps} />
+            {touched && error && <span className="error">{error}</span>}
+        </div>
+    ),
+    // Textarea variant
+    'string:textarea': ({ value, onChange, onBlur, error, touched, label, name, fieldProps }: FieldRenderProps) => (
+        <div>
+            {label && <label>{label}</label>}
+            <textarea name={name} value={value ?? ''}
+                      onChange={(e) => onChange(e.target.value)} onBlur={onBlur}
+                      {...(fieldProps as any)} />
+            {touched && error && <span className="error">{error}</span>}
+        </div>
+    )
+};
+```
+
+### MUI (Material UI)
+
+```tsx
+import { TextField, Checkbox } from '@mui/material';
+
+const muiRenderers = {
+    string: ({ value, onChange, onBlur, error, touched }: FieldRenderProps) => (
+        <TextField
+            value={value ?? ''}
+            onChange={(e) => onChange(e.target.value)}
+            onBlur={onBlur}
+            error={touched && !!error}
+            helperText={touched ? error : undefined}
+        />
+    ),
+    number: ({ value, onChange, onBlur, error, touched }: FieldRenderProps) => (
+        <TextField
+            type="number"
+            value={value ?? ''}
+            onChange={(e) => onChange(Number(e.target.value))}
+            onBlur={onBlur}
+            error={touched && !!error}
+            helperText={touched ? error : undefined}
+        />
+    ),
+    boolean: ({ value, onChange }: FieldRenderProps) => (
+        <Checkbox
+            checked={value ?? false}
+            onChange={(e) => onChange(e.target.checked)}
+        />
+    )
+};
+```
+
+## FormSystemProvider
+
+Register renderers once at the top of your app. All `<Field>` components below resolve renderers by schema type automatically:
+
+```tsx
+import { FormSystemProvider } from '@cleverbrush/react-form';
+
+// Public website with plain HTML inputs
+<FormSystemProvider renderers={htmlRenderers}>
+    <PublicApp />
+</FormSystemProvider>
+
+// Admin panel using MUI
+<FormSystemProvider renderers={muiRenderers}>
+    <AdminApp />
+</FormSystemProvider>
+```
+
+### Nesting
+
+Inner providers override/extend outer providers:
+
+```tsx
+<FormSystemProvider renderers={muiRenderers}>
+    <MainApp />
+    {/* Override just the string renderer in this section */}
+    <FormSystemProvider renderers={{ string: customStringRenderer }}>
+        <SpecialSection />
+    </FormSystemProvider>
+</FormSystemProvider>
+```
+
+## useSchemaForm
+
+Creates a form instance bound to a schema. Returns field binding and form lifecycle methods:
+
+```tsx
+const form = useSchemaForm(UserSchema, {
+    createMissingStructure: true,  // default: true — auto-create parent objects when setting nested values
+    validateOnMount: false,        // default: false — set to true to show errors immediately on mount
+    validationDebounceMs: 300      // optional — debounce onChange validation (ms); validate()/submit() are always immediate
+});
+```
+
+### Returned API
+
+| Method | Description |
+|--------|-------------|
+| `form.useField(forProperty)` | Bind a field by PropertyDescriptor selector |
+| `form.submit()` | Validate and return `ValidationResult` (includes `result.object` on success) |
+| `form.validate()` | Run validation, propagate errors to fields |
+| `form.reset(values?)` | Reset all fields; optionally set new initial values |
+| `form.getValue()` | Get current form values as plain object |
+| `form.setValue(values)` | Merge values into form state |
+
+## useField
+
+Binds a single field via PropertyDescriptor selector. Can be used via `form.useField()` or the context-based standalone `useField()`:
+
+```tsx
+// Via form instance
+const name = form.useField((t) => t.name);
+const city = form.useField((t) => t.address.city);
+
+// Or via context (inside a FormProvider)
+const name = useField((t) => t.name);
+```
+
+### Returned State & API
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `value` | `T \| undefined` | Current field value |
+| `initialValue` | `T \| undefined` | Value at form init / last reset |
+| `dirty` | `boolean` | `true` if value differs from initialValue |
+| `touched` | `boolean` | `true` after `onBlur` has been called |
+| `error` | `string \| undefined` | Validation error message from schema |
+| `validating` | `boolean` | `true` during async validation |
+| `onChange(value)` | `(T) => void` | Update field value |
+| `onBlur()` | `() => void` | Mark field as touched |
+| `setValue(value)` | `(T) => void` | Alias for `onChange` |
+| `schema` | `SchemaBuilder` | The field's schema builder |
+
+## Field Component
+
+Resolves the renderer from the `FormSystemProvider` registry by schema type (and optional variant), or uses an explicit `renderer` prop:
+
+```tsx
+// Auto-resolved from FormSystemProvider (string schema → string renderer)
+<Field forProperty={(t) => t.name} form={form} />
+
+// Variant-based resolution: looks up "string:password", falls back to "string"
+<Field forProperty={(t) => t.password} form={form} variant="password" />
+
+// With label, name, and extra props for the renderer
+<Field
+    forProperty={(t) => t.email}
+    form={form}
+    label="Email address"
+    name="email"
+    fieldProps={{ placeholder: 'you@example.com', autoComplete: 'email' }}
+/>
+
+// Explicit renderer override
+<Field forProperty={(t) => t.name} form={form} renderer={customRenderer} />
+```
+
+### Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `forProperty` | `(tree) => PropertyDescriptor` | PropertyDescriptor selector for the field |
+| `form` | `SchemaFormInstance` | Form instance from `useSchemaForm` |
+| `renderer?` | `FieldRenderer` | Optional explicit renderer (overrides provider) |
+| `variant?` | `string` | Variant hint for renderer resolution and forwarded to the renderer |
+| `label?` | `string` | Visible label text forwarded to the renderer |
+| `name?` | `string` | HTML `name` attribute forwarded to the renderer |
+| `fieldProps?` | `Record<string, unknown>` | Extra renderer-specific props (e.g. `placeholder`, `autoComplete`) |
+
+## Headless Usage (without Field component)
+
+For full control over rendering, use `form.useField()` directly:
+
+```tsx
+function UserForm() {
+    const form = useSchemaForm(UserSchema);
+    const name = form.useField((t) => t.name);
+    const email = form.useField((t) => t.email);
+
+    return (
+        <>
+            <input
+                value={name.value ?? ''}
+                onChange={(e) => name.onChange(e.target.value)}
+                onBlur={name.onBlur}
+            />
+            {name.touched && name.error && <span>{name.error}</span>}
+
+            <input
+                value={email.value ?? ''}
+                onChange={(e) => email.onChange(e.target.value)}
+                onBlur={email.onBlur}
+            />
+            <button onClick={() => form.submit()}>Submit</button>
+        </>
+    );
+}
+```
+
+## FormProvider
+
+Context bridge that allows standalone `useField()` usage outside of `form.useField()`:
+
+```tsx
+import { FormProvider, useField } from '@cleverbrush/react-form';
+
+function NameInput() {
+    const name = useField((t) => t.name);
+    return <input value={name.value ?? ''} onChange={(e) => name.onChange(e.target.value)} />;
+}
+
+function UserForm() {
+    const form = useSchemaForm(UserSchema);
+
+    return (
+        <FormProvider form={form}>
+            <NameInput />
+        </FormProvider>
+    );
+}
+```
+
+## Nested Object Schemas
+
+PropertyDescriptor selectors support nested paths:
+
+```tsx
+const UserSchema = object({
+    name: string(),
+    address: object({
+        city: string(),
+        zip: number()
+    })
+});
+
+function UserForm() {
+    const form = useSchemaForm(UserSchema);
+
+    return (
+        <>
+            <Field forProperty={(t) => t.name} form={form} />
+            <Field forProperty={(t) => t.address.city} form={form} />
+            <Field forProperty={(t) => t.address.zip} form={form} />
+        </>
+    );
+}
+```
+
+## Validation
+
+Validation uses `@cleverbrush/schema` validators. Errors are automatically propagated to the corresponding field state:
+
+```tsx
+const SignupSchema = object({
+    username: string().addValidator(async (val) => {
+        if (val.length < 3) {
+            return {
+                valid: false,
+                errors: [{ message: 'Username must be at least 3 characters' }]
+            };
+        }
+        return { valid: true };
+    }),
+    email: string()
+});
+
+function SignupForm() {
+    const form = useSchemaForm(SignupSchema);
+
+    return (
+        <FormSystemProvider renderers={htmlRenderers}>
+            <Field forProperty={(t) => t.username} form={form} />
+            <Field forProperty={(t) => t.email} form={form} />
+            <button onClick={async () => {
+                const result = await form.submit();
+                if (result.valid) {
+                    console.log('Success:', result.object);
+                }
+            }}>Submit</button>
+        </FormSystemProvider>
+    );
+}
+```
+
+### How validation works
+
+1. `form.validate()` or `form.submit()` runs the schema's full validation
+2. Per-property errors are resolved via `getErrorsFor()` using PropertyDescriptors
+3. Each field's `error` state is updated automatically
+4. Renderers receive the `error` string and `touched` boolean to decide how/when to display errors
+
+## End-to-End Example
+
+Here's a complete, realistic example showing all pieces together — a registration form with nested address, custom validation, and MUI renderers:
+
+```tsx
+import { object, string, number } from '@cleverbrush/schema';
+import { useSchemaForm, FormSystemProvider, Field } from '@cleverbrush/react-form';
+import { TextField } from '@mui/material';
+
+// Schema — single source of truth for types, validation, and form fields
+const RegistrationSchema = object({
+    name:    string().required('Name is required').minLength(2, 'Too short'),
+    email:   string().required('Email is required').matches(/^[^\s@]+@[^\s@]+\.[^\s@]+$/, 'Invalid email'),
+    age:     number().required('Age is required').min(18, 'Must be 18+'),
+    address: object({
+        city:  string().required('City is required'),
+        zip:   string().required('ZIP is required').minLength(5, 'Invalid ZIP')
+    })
+});
+
+// Renderers — define once, reuse everywhere
+const renderers = {
+    string: ({ value, onChange, onBlur, error, touched }) => (
+        <TextField
+            value={value ?? ''}
+            onChange={(e) => onChange(e.target.value)}
+            onBlur={onBlur}
+            error={touched && !!error}
+            helperText={touched ? error : undefined}
+            fullWidth
+            margin="normal"
+        />
+    ),
+    number: ({ value, onChange, onBlur, error, touched }) => (
+        <TextField
+            type="number"
+            value={value ?? ''}
+            onChange={(e) => onChange(Number(e.target.value))}
+            onBlur={onBlur}
+            error={touched && !!error}
+            helperText={touched ? error : undefined}
+            fullWidth
+            margin="normal"
+        />
+    )
+};
+
+// Form component — just declare which fields to show
+function RegistrationForm() {
+    const form = useSchemaForm(RegistrationSchema);
+
+    return (
+        <div>
+            <Field forProperty={(t) => t.name} form={form} />
+            <Field forProperty={(t) => t.email} form={form} />
+            <Field forProperty={(t) => t.age} form={form} />
+            <Field forProperty={(t) => t.address.city} form={form} />
+            <Field forProperty={(t) => t.address.zip} form={form} />
+            <button onClick={async () => {
+                const result = await form.submit();
+                if (result.valid) {
+                    console.log('Registered:', result.object);
+                }
+            }}>Register</button>
+        </div>
+    );
+}
+
+// App — wrap with provider
+function App() {
+    return (
+        <FormSystemProvider renderers={renderers}>
+            <RegistrationForm />
+        </FormSystemProvider>
+    );
+}
+```
+
+## API Reference
+
+### Exports
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `FormSystemProvider` | Component | Global renderer registry provider |
+| `FormProvider` | Component | Form context bridge for standalone `useField` |
+| `Field` | Component | Auto-rendered field by schema type |
+| `useSchemaForm` | Hook | Create a form instance from schema |
+| `useField` | Hook | Context-based field binding (use inside `FormProvider`) |
+| `useFormSystem` | Hook | Access `FormSystemProvider` config |
+
+### Types
+
+| Type | Description |
+|------|-------------|
+| `FieldRenderer` | `(props: FieldRenderProps) => ReactNode` |
+| `FieldRenderProps` | Props passed to renderers: `value`, `initialValue`, `dirty`, `touched`, `error`, `validating`, `onChange`, `onBlur`, `setValue`, `schema`, `variant?`, `label?`, `name?`, `fieldProps?` |
+| `FormSystemConfig` | `{ renderers?: Record<string, FieldRenderer> }` — keys can be `"type"` or `"type:variant"` |
+| `FieldState` | `{ value, initialValue, dirty, touched, error, validating }` |
+| `UseFieldResult` | `FieldState & { onChange, onBlur, setValue, schema }` |
+| `UseSchemaFormOptions` | `{ createMissingStructure?: boolean; validateOnMount?: boolean; validationDebounceMs?: number }` |
+| `SchemaFormInstance` | Return type of `useSchemaForm` |
+| `FormSystemProviderProps` | Props for `FormSystemProvider` |
+| `FormProviderProps` | Props for `FormProvider` |
+| `FieldProps` | Props for `Field` |
+
+## Code Quality
+
+- **Linting:** [Biome](https://biomejs.dev/) — enforced on every PR via CI
+- **Type checking:** TypeScript strict mode — field selectors and form state are fully typed end-to-end
+- **Unit tests:** [Vitest](https://vitest.dev/) + [Testing Library](https://testing-library.com/) — covering form state management, validation, async validators, field rendering, and provider configuration
+- **CI:** Every pull request must pass lint + build + test before merge — see [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml)
+
+## License
+
+BSD-3-Clause

package/dist/FormStore.d.ts

@@ -0,0 +1,17 @@
+import type { FieldState } from './types.js';
+/**
+ * Internal form store — manages field state and notification.
+ * Does not depend on React; used by hooks for state management.
+ */
+export declare function createFormStore(initialValues: any): {
+    getFieldState: (path: string) => FieldState;
+    updateFieldState: (path: string, patch: Partial<FieldState>) => void;
+    subscribe: (path: string, listener: () => void) => () => void;
+    subscribeGlobal: (listener: () => void) => () => void;
+    getValues: () => any;
+    setValues: (newValues: any) => void;
+    resetAll: (newInitialValues?: any) => void;
+    notifyAll: () => void;
+    getAllFieldPaths: () => string[];
+};
+export type FormStore = ReturnType<typeof createFormStore>;

package/dist/components.d.ts

@@ -0,0 +1,92 @@
+import type { InferType, ObjectSchemaBuilder, PropertyDescriptor, PropertyDescriptorTree, SchemaBuilder } from '@cleverbrush/schema';
+import type React from 'react';
+import type { SchemaFormInstance } from './hooks.js';
+import type { FieldRenderer, FormSystemConfig, UseFieldResult } from './types.js';
+export type FormSystemProviderProps = {
+    /**
+     * Renderer registry mapping schema types to renderer functions.
+     * Example: `{ string: (props) => <input .../>, number: (props) => <input type="number" .../> }`
+     */
+    renderers?: Record<string, FieldRenderer>;
+    /**
+     * Full configuration object (for future extensibility).
+     * If both `renderers` and `config.renderers` are provided, `renderers` takes precedence.
+     */
+    config?: FormSystemConfig;
+    children: React.ReactNode;
+};
+/**
+ * Provides global renderer configuration via React Context.
+ * Supports nesting — inner provider overrides outer.
+ *
+ * @example
+ * ```tsx
+ * <FormSystemProvider renderers={htmlRenderers}>
+ *   <App />
+ * </FormSystemProvider>
+ * ```
+ */
+export declare function FormSystemProvider({ renderers, config, children }: FormSystemProviderProps): React.ReactNode;
+export type FormProviderProps<TSchema extends ObjectSchemaBuilder<any, any, any>> = {
+    form: SchemaFormInstance<TSchema>;
+    children: React.ReactNode;
+};
+/**
+ * Provides form context to children so they can use the context-based useField.
+ */
+export declare function FormProvider<TSchema extends ObjectSchemaBuilder<any, any, any>>({ form, children }: FormProviderProps<TSchema>): React.ReactNode;
+/**
+ * Context-based useField — can be used inside a FormProvider.
+ * For best IntelliSense, prefer `form.useField()` which infers field types from the schema.
+ * When using this context-based version, specify the schema type explicitly:
+ *
+ * @example
+ * ```tsx
+ * const name = useField<typeof MySchema>((t) => t.name);
+ * ```
+ */
+export declare function useField<TSchema extends ObjectSchemaBuilder<any, any, any>, TPropertySchema extends SchemaBuilder<any, any, any> = SchemaBuilder<any, any, any>>(forProperty: (tree: PropertyDescriptorTree<TSchema, TSchema>) => PropertyDescriptor<TSchema, TPropertySchema, any>): UseFieldResult<InferType<TPropertySchema>>;
+/**
+ * Hook to access FormSystem configuration.
+ */
+export declare function useFormSystem(): FormSystemConfig;
+export type FieldProps<TSchema extends ObjectSchemaBuilder<any, any, any>> = {
+    forProperty: (tree: PropertyDescriptorTree<TSchema, TSchema>) => PropertyDescriptor<TSchema, any, any>;
+    form: SchemaFormInstance<TSchema>;
+    renderer?: FieldRenderer;
+    /**
+     * Rendering variant hint. Participates in renderer resolution:
+     * the registry is checked for `"type:variant"` (e.g. `"string:password"`)
+     * before falling back to the base `"type"` key.
+     * Also forwarded to the renderer via `FieldRenderProps.variant`.
+     */
+    variant?: string;
+    /** Visible label text forwarded to the renderer via `FieldRenderProps.label`. */
+    label?: string;
+    /** HTML `name` attribute forwarded to the renderer via `FieldRenderProps.name`. */
+    name?: string;
+    /**
+     * Bag of extra renderer-specific props forwarded to the renderer via
+     * `FieldRenderProps.fieldProps` (e.g. `placeholder`, `autoComplete`).
+     */
+    fieldProps?: Record<string, unknown>;
+};
+/**
+ * UI-agnostic Field component.
+ *
+ * Resolves a renderer from:
+ * 1. Explicit `renderer` prop
+ * 2. FormSystemProvider registry — checked for `"type:variant"` first,
+ *    then for the base `"type"`
+ *
+ * All rendering hints (`variant`, `label`, `name`, `fieldProps`) are
+ * forwarded to the resolved renderer via `FieldRenderProps`.
+ *
+ * @example
+ * ```tsx
+ * <Field forProperty={(t) => t.password} form={form}
+ *        variant="password" label="Password"
+ *        fieldProps={{ placeholder: "Enter password", autoComplete: "current-password" }} />
+ * ```
+ */
+export declare function Field<TSchema extends ObjectSchemaBuilder<any, any, any>>({ forProperty, form, renderer, variant, label, name, fieldProps }: FieldProps<TSchema>): React.ReactNode;

package/dist/contexts.d.ts

@@ -0,0 +1,22 @@
+import type { ObjectSchemaBuilder, PropertyDescriptorInner, PropertyDescriptorTree } from '@cleverbrush/schema';
+import type { FormStore } from './FormStore.js';
+import type { FormSystemConfig, UseSchemaFormOptions } from './types.js';
+/**
+ * Context for global form system configuration (renderers, etc).
+ */
+export declare const FormSystemContext: import("react").Context<FormSystemConfig | null>;
+/**
+ * Internal form context value — used to bridge useSchemaForm store
+ * to the context-based useField and Field component.
+ */
+export type FormContextValue = {
+    store: FormStore;
+    descriptorTree: PropertyDescriptorTree<any, any>;
+    schema: ObjectSchemaBuilder<any, any, any>;
+    options: UseSchemaFormOptions;
+    pathMap: Map<PropertyDescriptorInner<any, any, any>, string>;
+};
+/**
+ * Context for per-form data — allows useField to work via context.
+ */
+export declare const FormContext: import("react").Context<FormContextValue | null>;

package/dist/debounce.d.ts

@@ -0,0 +1,7 @@
+/**
+ * A debounce function ensures that a function is not called too frequently.
+ * It only allows the function to be executed after a specified delay has passed since the last call.
+ * @param func The function to debounce.
+ * @param wait The delay in ms before the function is called.
+ */
+export declare function debounce<T extends (...args: any[]) => void>(func: T, wait: number): (...args: Parameters<T>) => void;

package/dist/helpers.d.ts

@@ -0,0 +1,38 @@
+import type { PropertyDescriptorInner, PropertyDescriptorTree, SchemaBuilder } from '@cleverbrush/schema';
+import { ObjectSchemaBuilder } from '@cleverbrush/schema';
+/**
+ * Builds a map from PropertyDescriptorInner identity → dot-separated path
+ * by traversing the descriptor tree recursively.
+ */
+export declare function buildDescriptorPathMap(tree: PropertyDescriptorTree<any, any>, schema: ObjectSchemaBuilder<any, any, any>): Map<PropertyDescriptorInner<any, any, any>, string>;
+/**
+ * Looks up the path for a given descriptor from the pre-built map.
+ */
+export declare function getDescriptorPath(inner: PropertyDescriptorInner<any, any, any>, pathMap: Map<PropertyDescriptorInner<any, any, any>, string>): string;
+/**
+ * Returns the schema type string (e.g. "string", "number", "object").
+ */
+export declare function getSchemaType(schema: SchemaBuilder<any, any, any>): string;
+/**
+ * Builds a selector function from a dot-separated path string.
+ * The selector traverses the PropertyDescriptorTree by property access.
+ * Example: "customer.address.city" → (tree) => tree.customer.address.city
+ */
+export declare function buildSelectorFromPath(path: string): (tree: any) => any;
+/**
+ * Checks whether a validation error path matches a field's expected error path.
+ * Matches exact path, path with nested suffix, or path with validator suffix.
+ * Example: isErrorPathMatch("$.user.name", "$.user.name") → true
+ *          isErrorPathMatch("$.user.name($validators[0])", "$.user.name") → true
+ */
+export declare function isErrorPathMatch(errPath: string, fieldErrorPath: string): boolean;
+/**
+ * Ensures all nested object structures exist in the values object
+ * by traversing the schema and creating empty objects where needed.
+ * This prevents ObjectSchemaBuilder.validate() from throwing when
+ * nested object properties are undefined.
+ *
+ * Example: ensureNestedStructure({}, OrderSchema)
+ *   → { customer: { address: {} } }
+ */
+export declare function ensureNestedStructure(values: any, schema: ObjectSchemaBuilder<any, any, any>): any;

package/dist/hooks.d.ts

@@ -0,0 +1,36 @@
+import type { InferType, PropertyDescriptor, PropertyDescriptorTree, SchemaBuilder, ValidationResult } from '@cleverbrush/schema';
+import { ObjectSchemaBuilder } from '@cleverbrush/schema';
+import type { FormContextValue } from './contexts.js';
+import type { FieldRenderer, FormSystemConfig, UseFieldResult, UseSchemaFormOptions } from './types.js';
+/**
+ * Return type for useSchemaForm — fully typed for IntelliSense.
+ * The `useField` method infers the field value type from the schema via PropertyDescriptor.
+ */
+export type SchemaFormInstance<TSchema extends ObjectSchemaBuilder<any, any, any>> = {
+    useField: <TPropertySchema extends SchemaBuilder<any, any, any>>(forProperty: (tree: PropertyDescriptorTree<TSchema, TSchema>) => PropertyDescriptor<TSchema, TPropertySchema, any>) => UseFieldResult<InferType<TPropertySchema>>;
+    submit: () => Promise<ValidationResult<InferType<TSchema>>>;
+    validate: () => Promise<ValidationResult<InferType<TSchema>>>;
+    reset: (values?: Partial<InferType<TSchema>>) => void;
+    getValue: () => InferType<TSchema>;
+    setValue: (values: Partial<InferType<TSchema>>) => void;
+    /** @internal — Used by FormProvider and Field to access internal context */
+    _getFormContext: () => FormContextValue;
+};
+/**
+ * Hook that binds a schema to a form instance.
+ * Provides field binding API, form-level validation, submit, reset.
+ */
+export declare function useSchemaForm<TSchema extends ObjectSchemaBuilder<any, any, any>>(schema: TSchema, options?: UseSchemaFormOptions): SchemaFormInstance<TSchema>;
+/**
+ * Internal useField implementation, requires FormContextValue.
+ * Returns UseFieldResult with untyped values — callers should cast to the proper generic type.
+ */
+export declare function useFieldFromContext(formContext: FormContextValue, forProperty: (tree: any) => any, triggerValidation?: (markTouched: boolean) => Promise<any>): UseFieldResult;
+/**
+ * Resolves a renderer from the FormSystem config based on schema type and optional variant.
+ *
+ * When `variant` is provided the registry is checked for `"type:variant"` first
+ * (e.g. `"string:password"`). If no match is found it falls back to the base
+ * `"type"` key (e.g. `"string"`).
+ */
+export declare function resolveRenderer(config: FormSystemConfig | null, schema: SchemaBuilder<any, any, any>, variant?: string): FieldRenderer | undefined;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { FieldProps, FormProviderProps, FormSystemProviderProps } from './components.js';
+export { Field, FormProvider, FormSystemProvider, useField, useFormSystem } from './components.js';
+export type { SchemaFormInstance } from './hooks.js';
+export { useSchemaForm } from './hooks.js';
+export type { FieldRenderer, FieldRenderProps, FieldState, FormSystemConfig, UseFieldResult, UseSchemaFormOptions } from './types.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+import{useContext as B,useMemo as ce}from"react";import{createContext as W}from"react";var b=W(null),E=W(null);import{ObjectSchemaBuilder as H,SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR as Y}from"@cleverbrush/schema";function U(t,s){let r=new Map,e=s.introspect();if(!e.properties)return r;for(let n of Object.keys(e.properties)){let i=t[n];if(!i||!(Y in i))continue;let f=i[Y];r.set(f,n);let c=e.properties[n];if(c instanceof H){let l=U(i,c);for(let[a,p]of l)r.set(a,`${n}.${p}`)}}return r}function G(t,s){return s.get(t)??""}function M(t){return t.introspect()?.type??"unknown"}function z(t){let s=t.split(".");return r=>{let e=r;for(let n of s){if(e==null)return;e=e[n]}return e}}function A(t,s){let r=s.introspect();if(!r.properties)return t??{};let e=t!=null?{...t}:{};for(let n of Object.keys(r.properties)){let i=r.properties[n];i instanceof H&&(e[n]=A(e[n],i))}return e}import{ObjectSchemaBuilder as oe,SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR as se}from"@cleverbrush/schema";import{useCallback as y,useEffect as Q,useMemo as K,useRef as h,useState as ae}from"react";function q(t,s){let r=null;return(...e)=>{r!==null&&clearTimeout(r),r=setTimeout(()=>{t(...e)},s)}}function J(t){let s=t!=null?{...t}:{},r=new Map,e=new Map,n=new Set;function i(o){return r.has(o)||r.set(o,{value:void 0,initialValue:void 0,dirty:!1,touched:!1,error:void 0,validating:!1}),r.get(o)}function f(o){return i(o)}function c(o,u){let g={...i(o),...u};r.set(o,g),l(o)}function l(o){let u=e.get(o);if(u)for(let d of u)d()}function a(){for(let[,o]of e)for(let u of o)u();for(let o of n)o()}function p(o,u){return e.has(o)||e.set(o,new Set),e.get(o).add(u),()=>{e.get(o)?.delete(u)}}function F(o){return n.add(o),()=>{n.delete(o)}}function R(){return s}function T(o){s=o!=null?{...o}:{}}function S(o){s=o!=null?{...o}:{},r.clear(),a()}function P(){return Array.from(r.keys())}return{getFieldState:f,updateFieldState:c,subscribe:p,subscribeGlobal:F,getValues:R,setValues:T,resetAll:S,notifyAll:a,getAllFieldPaths:P}}function ie(t,s){let r={createMissingStructure:!0,...s},e=h(null);e.current||(e.current=J({}));let n=e.current,i=h(null);i.current||(i.current=oe.getPropertiesFor(t));let f=i.current,c=h(null);c.current||(c.current=U(f,t));let l=c.current,a=h(t),p=h(r);p.current=r;let F=K(()=>({store:n,descriptorTree:f,schema:a.current,options:p.current,pathMap:l}),[n,f,l]),R=h(F);R.current=F;let T=h(0),S=y(async m=>{let I=++T.current,j=n.getValues(),ee=A(j,a.current),D;try{D=await a.current.validateAsync(ee,{doNotStopOnFirstError:!0})}catch{return{valid:!1}}if(I!==T.current)return D;let re=n.getAllFieldPaths();for(let w of re){let v={error:void 0};m&&(v.touched=!0),n.updateFieldState(w,v)}let $=D,te=new Set;if(typeof $.getErrorsFor=="function"){let w=$.getErrorsFor;for(let[,v]of l)try{let ne=z(v),O=w(ne);if(O&&Array.isArray(O.errors)&&O.errors.length>0){let L={error:O.errors[0]};m&&(L.touched=!0),n.updateFieldState(v,L),te.add(v)}}catch{}}return D},[n,l]),P=y(async()=>S(!0),[S]),o=y(async()=>P(),[P]),u=y(m=>{let I=m??{};n.resetAll(I)},[n]),d=y(()=>n.getValues(),[n]),g=y(m=>{let j={...n.getValues(),...m};n.setValues(j),n.notifyAll()},[n]),x=y(()=>R.current,[]),V=h(r.validateOnMount);Q(()=>{V.current&&S(!0)},[]);let C=h(null);r.validationDebounceMs!=null&&r.validationDebounceMs>0&&!C.current&&(C.current=q(m=>{S(m)},r.validationDebounceMs));let N=y(m=>C.current?(C.current(m),Promise.resolve(void 0)):S(m),[S]),_=y(m=>k(R.current,m,N),[N]);return K(()=>({useField:_,submit:o,validate:P,reset:u,getValue:d,setValue:g,_getFormContext:x}),[_,o,P,u,d,g,x])}function k(t,s,r){let{store:e,descriptorTree:n,options:i,pathMap:f}=t,l=s(n)[se],a=G(l,f),p=l.getSchema(),F=h(null);if(F.current!==a){let u=e.getValues(),{success:d,value:g}=l.getValue(u),x=e.getFieldState(a);if(x.initialValue===void 0&&!x.touched){let V=d?g:void 0;e.updateFieldState(a,{value:V,initialValue:V,dirty:!1})}F.current=a}let[,R]=ae(0);Q(()=>e.subscribe(a,()=>{R(d=>d+1)}),[e,a]);let T=y(u=>{let d=e.getValues();l.setValue(d,u,{createMissingStructure:i.createMissingStructure!==!1}),e.setValues(d);let g=e.getFieldState(a);e.updateFieldState(a,{value:u,dirty:u!==g.initialValue}),r&&r(!1)},[e,l,a,i,r]),S=y(()=>{e.updateFieldState(a,{touched:!0})},[e,a]),P=y(u=>{T(u)},[T]),o=e.getFieldState(a);return{value:o.value,initialValue:o.initialValue,dirty:o.dirty,touched:o.touched,error:o.error,validating:o.validating,onChange:T,onBlur:S,setValue:P,schema:p}}function X(t,s,r){if(!t?.renderers)return;let e=M(s);if(r){let n=t.renderers[`${e}:${r}`];if(n)return n}return t.renderers[e]}import{jsx as Z}from"react/jsx-runtime";function ue({renderers:t,config:s,children:r}){let e=B(b),n=ce(()=>{let i={...s,renderers:{...s?.renderers,...t}};return e?{...e,...i,renderers:{...e.renderers,...i.renderers}}:i},[e,s,t]);return Z(b.Provider,{value:n,children:r})}function le({form:t,children:s}){let r=t._getFormContext();return Z(E.Provider,{value:r,children:s})}function me(t){let s=B(E);if(!s)throw new Error("useField must be used within a FormProvider. Wrap your component tree with <FormProvider form={form}>.");return k(s,t)}function pe(){let t=B(b);if(!t)throw new Error("useFormSystem must be used within a FormSystemProvider");return t}function de({forProperty:t,form:s,renderer:r,variant:e,label:n,name:i,fieldProps:f}){let c=s.useField(t),l=B(b),a=r??X(l,c.schema,e);if(!a){let p=M(c.schema),F=e?`"${p}:${e}" or "${p}"`:`"${p}"`;throw new Error(`No renderer found for schema type ${F}. Provide a renderer prop or configure one in FormSystemProvider.`)}return a({value:c.value,initialValue:c.initialValue,dirty:c.dirty,touched:c.touched,error:c.error,validating:c.validating,onChange:c.onChange,onBlur:c.onBlur,setValue:c.setValue,schema:c.schema,variant:e,label:n,name:i,fieldProps:f})}export{de as Field,le as FormProvider,ue as FormSystemProvider,me as useField,pe as useFormSystem,ie as useSchemaForm};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/components.tsx","../src/contexts.ts","../src/helpers.ts","../src/hooks.ts","../src/debounce.ts","../src/FormStore.ts"],"sourcesContent":["import type {\n    InferType,\n    ObjectSchemaBuilder,\n    PropertyDescriptor,\n    PropertyDescriptorTree,\n    SchemaBuilder\n} from '@cleverbrush/schema';\nimport type React from 'react';\nimport { useContext, useMemo } from 'react';\nimport { FormContext, FormSystemContext } from './contexts.js';\nimport { getSchemaType } from './helpers.js';\nimport type { SchemaFormInstance } from './hooks.js';\nimport { resolveRenderer, useFieldFromContext } from './hooks.js';\nimport type {\n    FieldRenderer,\n    FormSystemConfig,\n    UseFieldResult\n} from './types.js';\n\n// ─── FormSystemProvider ──────────────────────────────────────────────────────\n\nexport type FormSystemProviderProps = {\n    /**\n     * Renderer registry mapping schema types to renderer functions.\n     * Example: `{ string: (props) => <input .../>, number: (props) => <input type=\"number\" .../> }`\n     */\n    renderers?: Record<string, FieldRenderer>;\n    /**\n     * Full configuration object (for future extensibility).\n     * If both `renderers` and `config.renderers` are provided, `renderers` takes precedence.\n     */\n    config?: FormSystemConfig;\n    children: React.ReactNode;\n};\n\n/**\n * Provides global renderer configuration via React Context.\n * Supports nesting — inner provider overrides outer.\n *\n * @example\n * ```tsx\n * <FormSystemProvider renderers={htmlRenderers}>\n *   <App />\n * </FormSystemProvider>\n * ```\n */\nexport function FormSystemProvider({\n    renderers,\n    config,\n    children\n}: FormSystemProviderProps): React.ReactNode {\n    const parentConfig = useContext(FormSystemContext);\n\n    const resolvedConfig: FormSystemConfig = useMemo(() => {\n        const current: FormSystemConfig = {\n            ...config,\n            renderers: {\n                ...config?.renderers,\n                ...renderers\n            }\n        };\n        if (!parentConfig) return current;\n        return {\n            ...parentConfig,\n            ...current,\n            renderers: {\n                ...parentConfig.renderers,\n                ...current.renderers\n            }\n        };\n    }, [parentConfig, config, renderers]);\n\n    return (\n        <FormSystemContext.Provider value={resolvedConfig}>\n            {children}\n        </FormSystemContext.Provider>\n    );\n}\n\n// ─── FormProvider ────────────────────────────────────────────────────────────\n\nexport type FormProviderProps<\n    TSchema extends ObjectSchemaBuilder<any, any, any>\n> = {\n    form: SchemaFormInstance<TSchema>;\n    children: React.ReactNode;\n};\n\n/**\n * Provides form context to children so they can use the context-based useField.\n */\nexport function FormProvider<\n    TSchema extends ObjectSchemaBuilder<any, any, any>\n>({ form, children }: FormProviderProps<TSchema>): React.ReactNode {\n    const formContext = form._getFormContext();\n    return (\n        <FormContext.Provider value={formContext}>\n            {children}\n        </FormContext.Provider>\n    );\n}\n\n// ─── Context-based useField ──────────────────────────────────────────────────\n\n/**\n * Context-based useField — can be used inside a FormProvider.\n * For best IntelliSense, prefer `form.useField()` which infers field types from the schema.\n * When using this context-based version, specify the schema type explicitly:\n *\n * @example\n * ```tsx\n * const name = useField<typeof MySchema>((t) => t.name);\n * ```\n */\nexport function useField<\n    TSchema extends ObjectSchemaBuilder<any, any, any>,\n    TPropertySchema extends SchemaBuilder<any, any, any> = SchemaBuilder<\n        any,\n        any,\n        any\n    >\n>(\n    forProperty: (\n        tree: PropertyDescriptorTree<TSchema, TSchema>\n    ) => PropertyDescriptor<TSchema, TPropertySchema, any>\n): UseFieldResult<InferType<TPropertySchema>> {\n    const formContext = useContext(FormContext);\n    if (!formContext) {\n        throw new Error(\n            'useField must be used within a FormProvider. ' +\n                'Wrap your component tree with <FormProvider form={form}>.'\n        );\n    }\n    return useFieldFromContext(formContext, forProperty) as UseFieldResult<\n        InferType<TPropertySchema>\n    >;\n}\n\n// ─── useFormSystem ───────────────────────────────────────────────────────────\n\n/**\n * Hook to access FormSystem configuration.\n */\nexport function useFormSystem(): FormSystemConfig {\n    const config = useContext(FormSystemContext);\n    if (!config) {\n        throw new Error(\n            'useFormSystem must be used within a FormSystemProvider'\n        );\n    }\n    return config;\n}\n\n// ─── Field Component ─────────────────────────────────────────────────────────\n\nexport type FieldProps<TSchema extends ObjectSchemaBuilder<any, any, any>> = {\n    forProperty: (\n        tree: PropertyDescriptorTree<TSchema, TSchema>\n    ) => PropertyDescriptor<TSchema, any, any>;\n    form: SchemaFormInstance<TSchema>;\n    renderer?: FieldRenderer;\n    /**\n     * Rendering variant hint. Participates in renderer resolution:\n     * the registry is checked for `\"type:variant\"` (e.g. `\"string:password\"`)\n     * before falling back to the base `\"type\"` key.\n     * Also forwarded to the renderer via `FieldRenderProps.variant`.\n     */\n    variant?: string;\n    /** Visible label text forwarded to the renderer via `FieldRenderProps.label`. */\n    label?: string;\n    /** HTML `name` attribute forwarded to the renderer via `FieldRenderProps.name`. */\n    name?: string;\n    /**\n     * Bag of extra renderer-specific props forwarded to the renderer via\n     * `FieldRenderProps.fieldProps` (e.g. `placeholder`, `autoComplete`).\n     */\n    fieldProps?: Record<string, unknown>;\n};\n\n/**\n * UI-agnostic Field component.\n *\n * Resolves a renderer from:\n * 1. Explicit `renderer` prop\n * 2. FormSystemProvider registry — checked for `\"type:variant\"` first,\n *    then for the base `\"type\"`\n *\n * All rendering hints (`variant`, `label`, `name`, `fieldProps`) are\n * forwarded to the resolved renderer via `FieldRenderProps`.\n *\n * @example\n * ```tsx\n * <Field forProperty={(t) => t.password} form={form}\n *        variant=\"password\" label=\"Password\"\n *        fieldProps={{ placeholder: \"Enter password\", autoComplete: \"current-password\" }} />\n * ```\n */\nexport function Field<TSchema extends ObjectSchemaBuilder<any, any, any>>({\n    forProperty,\n    form,\n    renderer,\n    variant,\n    label,\n    name,\n    fieldProps\n}: FieldProps<TSchema>): React.ReactNode {\n    const fieldResult = form.useField(forProperty);\n    const systemConfig = useContext(FormSystemContext);\n\n    const resolvedRenderer =\n        renderer ?? resolveRenderer(systemConfig, fieldResult.schema, variant);\n\n    if (!resolvedRenderer) {\n        const schemaType = getSchemaType(fieldResult.schema);\n        const tried = variant\n            ? `\"${schemaType}:${variant}\" or \"${schemaType}\"`\n            : `\"${schemaType}\"`;\n        throw new Error(\n            `No renderer found for schema type ${tried}. ` +\n                'Provide a renderer prop or configure one in FormSystemProvider.'\n        );\n    }\n\n    return resolvedRenderer({\n        value: fieldResult.value,\n        initialValue: fieldResult.initialValue,\n        dirty: fieldResult.dirty,\n        touched: fieldResult.touched,\n        error: fieldResult.error,\n        validating: fieldResult.validating,\n        onChange: fieldResult.onChange,\n        onBlur: fieldResult.onBlur,\n        setValue: fieldResult.setValue,\n        schema: fieldResult.schema,\n        variant,\n        label,\n        name,\n        fieldProps\n    });\n}\n","import type {\n    ObjectSchemaBuilder,\n    PropertyDescriptorInner,\n    PropertyDescriptorTree\n} from '@cleverbrush/schema';\nimport { createContext } from 'react';\nimport type { FormStore } from './FormStore.js';\nimport type { FormSystemConfig, UseSchemaFormOptions } from './types.js';\n\n/**\n * Context for global form system configuration (renderers, etc).\n */\nexport const FormSystemContext = createContext<FormSystemConfig | null>(null);\n\n/**\n * Internal form context value — used to bridge useSchemaForm store\n * to the context-based useField and Field component.\n */\nexport type FormContextValue = {\n    store: FormStore;\n    descriptorTree: PropertyDescriptorTree<any, any>;\n    schema: ObjectSchemaBuilder<any, any, any>;\n    options: UseSchemaFormOptions;\n    pathMap: Map<PropertyDescriptorInner<any, any, any>, string>;\n};\n\n/**\n * Context for per-form data — allows useField to work via context.\n */\nexport const FormContext = createContext<FormContextValue | null>(null);\n","import type {\n    PropertyDescriptorInner,\n    PropertyDescriptorTree,\n    SchemaBuilder\n} from '@cleverbrush/schema';\nimport {\n    ObjectSchemaBuilder,\n    SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n} from '@cleverbrush/schema';\n\n/**\n * Builds a map from PropertyDescriptorInner identity → dot-separated path\n * by traversing the descriptor tree recursively.\n */\nexport function buildDescriptorPathMap(\n    tree: PropertyDescriptorTree<any, any>,\n    schema: ObjectSchemaBuilder<any, any, any>\n): Map<PropertyDescriptorInner<any, any, any>, string> {\n    const map = new Map<PropertyDescriptorInner<any, any, any>, string>();\n    const introspected = schema.introspect();\n    if (!introspected.properties) return map;\n\n    for (const propName of Object.keys(introspected.properties)) {\n        const propDescriptor = (tree as any)[propName];\n        if (\n            !propDescriptor ||\n            !(SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR in propDescriptor)\n        ) {\n            continue;\n        }\n        const inner = propDescriptor[\n            SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n        ] as PropertyDescriptorInner<any, any, any>;\n        map.set(inner, propName);\n\n        // Recurse into nested objects\n        const propSchema = introspected.properties[propName];\n        if (propSchema instanceof ObjectSchemaBuilder) {\n            const childMap = buildDescriptorPathMap(propDescriptor, propSchema);\n            for (const [childInner, childPath] of childMap) {\n                map.set(childInner, `${propName}.${childPath}`);\n            }\n        }\n    }\n\n    return map;\n}\n\n/**\n * Looks up the path for a given descriptor from the pre-built map.\n */\nexport function getDescriptorPath(\n    inner: PropertyDescriptorInner<any, any, any>,\n    pathMap: Map<PropertyDescriptorInner<any, any, any>, string>\n): string {\n    return pathMap.get(inner) ?? '';\n}\n\n/**\n * Returns the schema type string (e.g. \"string\", \"number\", \"object\").\n */\nexport function getSchemaType(schema: SchemaBuilder<any, any, any>): string {\n    const introspected = schema.introspect();\n    return introspected?.type ?? 'unknown';\n}\n\n/**\n * Builds a selector function from a dot-separated path string.\n * The selector traverses the PropertyDescriptorTree by property access.\n * Example: \"customer.address.city\" → (tree) => tree.customer.address.city\n */\nexport function buildSelectorFromPath(path: string): (tree: any) => any {\n    const parts = path.split('.');\n    return (tree: any) => {\n        let current = tree;\n        for (const part of parts) {\n            if (current == null) return undefined;\n            current = current[part];\n        }\n        return current;\n    };\n}\n\n/**\n * Checks whether a validation error path matches a field's expected error path.\n * Matches exact path, path with nested suffix, or path with validator suffix.\n * Example: isErrorPathMatch(\"$.user.name\", \"$.user.name\") → true\n *          isErrorPathMatch(\"$.user.name($validators[0])\", \"$.user.name\") → true\n */\nexport function isErrorPathMatch(\n    errPath: string,\n    fieldErrorPath: string\n): boolean {\n    return (\n        errPath === fieldErrorPath ||\n        errPath.startsWith(fieldErrorPath + '.') ||\n        errPath.startsWith(fieldErrorPath + '(')\n    );\n}\n\n/**\n * Ensures all nested object structures exist in the values object\n * by traversing the schema and creating empty objects where needed.\n * This prevents ObjectSchemaBuilder.validate() from throwing when\n * nested object properties are undefined.\n *\n * Example: ensureNestedStructure({}, OrderSchema)\n *   → { customer: { address: {} } }\n */\nexport function ensureNestedStructure(\n    values: any,\n    schema: ObjectSchemaBuilder<any, any, any>\n): any {\n    const introspected = schema.introspect();\n    if (!introspected.properties) return values != null ? values : {};\n\n    const result = values != null ? { ...values } : {};\n    for (const key of Object.keys(introspected.properties)) {\n        const propSchema = introspected.properties[key];\n        if (propSchema instanceof ObjectSchemaBuilder) {\n            result[key] = ensureNestedStructure(result[key], propSchema);\n        }\n    }\n    return result;\n}\n","import type {\n    InferType,\n    PropertyDescriptor,\n    PropertyDescriptorInner,\n    PropertyDescriptorTree,\n    SchemaBuilder,\n    ValidationResult\n} from '@cleverbrush/schema';\nimport {\n    ObjectSchemaBuilder,\n    SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR\n} from '@cleverbrush/schema';\nimport { useCallback, useEffect, useMemo, useRef, useState } from 'react';\nimport type { FormContextValue } from './contexts.js';\nimport { debounce } from './debounce.js';\nimport type { FormStore } from './FormStore.js';\nimport { createFormStore } from './FormStore.js';\nimport {\n    buildDescriptorPathMap,\n    buildSelectorFromPath,\n    ensureNestedStructure,\n    getDescriptorPath,\n    getSchemaType\n} from './helpers.js';\nimport type {\n    FieldRenderer,\n    FormSystemConfig,\n    UseFieldResult,\n    UseSchemaFormOptions\n} from './types.js';\n\n// ─── SchemaFormInstance ──────────────────────────────────────────────────────\n\n/**\n * Return type for useSchemaForm — fully typed for IntelliSense.\n * The `useField` method infers the field value type from the schema via PropertyDescriptor.\n */\nexport type SchemaFormInstance<\n    TSchema extends ObjectSchemaBuilder<any, any, any>\n> = {\n    useField: <TPropertySchema extends SchemaBuilder<any, any, any>>(\n        forProperty: (\n            tree: PropertyDescriptorTree<TSchema, TSchema>\n        ) => PropertyDescriptor<TSchema, TPropertySchema, any>\n    ) => UseFieldResult<InferType<TPropertySchema>>;\n    submit: () => Promise<ValidationResult<InferType<TSchema>>>;\n    validate: () => Promise<ValidationResult<InferType<TSchema>>>;\n    reset: (values?: Partial<InferType<TSchema>>) => void;\n    getValue: () => InferType<TSchema>;\n    setValue: (values: Partial<InferType<TSchema>>) => void;\n    /** @internal — Used by FormProvider and Field to access internal context */\n    _getFormContext: () => FormContextValue;\n};\n\n// ─── useSchemaForm ───────────────────────────────────────────────────────────\n\n/**\n * Hook that binds a schema to a form instance.\n * Provides field binding API, form-level validation, submit, reset.\n */\nexport function useSchemaForm<\n    TSchema extends ObjectSchemaBuilder<any, any, any>\n>(\n    schema: TSchema,\n    options?: UseSchemaFormOptions\n): SchemaFormInstance<TSchema> {\n    const resolvedOptions: UseSchemaFormOptions = {\n        createMissingStructure: true,\n        ...options\n    };\n\n    const storeRef = useRef<FormStore | null>(null);\n    if (!storeRef.current) {\n        storeRef.current = createFormStore({});\n    }\n    const store = storeRef.current;\n\n    const descriptorTreeRef = useRef<PropertyDescriptorTree<\n        TSchema,\n        TSchema\n    > | null>(null);\n    if (!descriptorTreeRef.current) {\n        descriptorTreeRef.current = ObjectSchemaBuilder.getPropertiesFor(\n            schema\n        ) as PropertyDescriptorTree<TSchema, TSchema>;\n    }\n    const descriptorTree = descriptorTreeRef.current;\n\n    const pathMapRef = useRef<Map<\n        PropertyDescriptorInner<any, any, any>,\n        string\n    > | null>(null);\n    if (!pathMapRef.current) {\n        pathMapRef.current = buildDescriptorPathMap(descriptorTree, schema);\n    }\n    const pathMap = pathMapRef.current;\n\n    const schemaRef = useRef(schema);\n    const optionsRef = useRef(resolvedOptions);\n    optionsRef.current = resolvedOptions;\n\n    const formContextValue = useMemo<FormContextValue>(\n        () => ({\n            store,\n            descriptorTree,\n            schema: schemaRef.current,\n            options: optionsRef.current,\n            pathMap\n        }),\n        [store, descriptorTree, pathMap]\n    );\n\n    const formContextRef = useRef(formContextValue);\n    formContextRef.current = formContextValue;\n\n    // Generation counter to discard stale validation results from concurrent runs\n    const validationGenRef = useRef(0);\n\n    /**\n     * Runs full schema validation using getErrorsFor to extract per-field errors.\n     * Optionally marks all fields as touched (used by submit/explicit validate).\n     */\n    const runValidation = useCallback(\n        async (\n            markTouched: boolean\n        ): Promise<ValidationResult<InferType<TSchema>>> => {\n            const gen = ++validationGenRef.current;\n            const values = store.getValues();\n            // Ensure all nested object structures exist to prevent\n            // ObjectSchemaBuilder.validateAsync() from throwing on undefined nested objects\n            const safeValues = ensureNestedStructure(values, schemaRef.current);\n            let result: ValidationResult<InferType<TSchema>>;\n            try {\n                result = (await schemaRef.current.validateAsync(safeValues, {\n                    doNotStopOnFirstError: true\n                })) as ValidationResult<InferType<TSchema>>;\n            } catch {\n                // If validation itself throws, treat as invalid\n                return { valid: false } as ValidationResult<InferType<TSchema>>;\n            }\n\n            // Discard results if a newer validation has started since this one began\n            if (gen !== validationGenRef.current) {\n                return result as ValidationResult<InferType<TSchema>>;\n            }\n\n            // Clear all existing field errors\n            const allPaths = store.getAllFieldPaths();\n            for (const p of allPaths) {\n                const patch: Partial<{\n                    error: string | undefined;\n                    touched: boolean;\n                }> = { error: undefined };\n                if (markTouched) {\n                    patch.touched = true;\n                }\n                store.updateFieldState(p, patch);\n            }\n\n            // Use getErrorsFor to extract per-field errors via tree selectors\n            const resultWithErrors = result as ValidationResult<\n                InferType<TSchema>\n            > & {\n                getErrorsFor?: (selector: (t: any) => any) => {\n                    errors: ReadonlyArray<string>;\n                    isValid: boolean;\n                };\n                errors?: ReadonlyArray<{ message: string; path?: string }>;\n            };\n\n            // Build a map of errors found via getErrorsFor so we can detect gaps\n            const fieldsWithErrors = new Set<string>();\n\n            if (typeof resultWithErrors.getErrorsFor === 'function') {\n                const getErrorsFor = resultWithErrors.getErrorsFor;\n\n                // Extract per-field errors by building selectors from field paths\n                for (const [, path] of pathMap) {\n                    try {\n                        const selector = buildSelectorFromPath(path);\n                        const fieldResult = getErrorsFor(selector);\n                        if (\n                            fieldResult &&\n                            Array.isArray(fieldResult.errors) &&\n                            fieldResult.errors.length > 0\n                        ) {\n                            const errorMessage = fieldResult.errors[0];\n                            const patch: Partial<{\n                                error: string | undefined;\n                                touched: boolean;\n                            }> = { error: errorMessage };\n                            if (markTouched) {\n                                patch.touched = true;\n                            }\n                            store.updateFieldState(path, patch);\n                            fieldsWithErrors.add(path);\n                        }\n                    } catch {\n                        // If getErrorsFor fails for this path, skip\n                    }\n                }\n            }\n\n            return result as ValidationResult<InferType<TSchema>>;\n        },\n        [store, pathMap]\n    );\n\n    const validate = useCallback(async (): Promise<\n        ValidationResult<InferType<TSchema>>\n    > => {\n        return runValidation(true);\n    }, [runValidation]);\n\n    const submit = useCallback(async (): Promise<\n        ValidationResult<InferType<TSchema>>\n    > => {\n        return validate();\n    }, [validate]);\n\n    const reset = useCallback(\n        (values?: Partial<InferType<TSchema>>) => {\n            const newValues = values ?? {};\n            store.resetAll(newValues);\n        },\n        [store]\n    );\n\n    const getValue = useCallback((): InferType<TSchema> => {\n        return store.getValues();\n    }, [store]);\n\n    const setValueFn = useCallback(\n        (values: Partial<InferType<TSchema>>) => {\n            const currentValues = store.getValues();\n            const merged = { ...currentValues, ...values };\n            store.setValues(merged);\n            store.notifyAll();\n        },\n        [store]\n    );\n\n    const _getFormContext = useCallback(() => formContextRef.current, []);\n\n    // Validate on mount when requested — runs once after first render\n    const validateOnMountRef = useRef(resolvedOptions.validateOnMount);\n    // biome-ignore lint/correctness/useExhaustiveDependencies: We only want to check validateOnMount on the initial mount, ignoring changes to it after that\n    useEffect(() => {\n        if (validateOnMountRef.current) {\n            runValidation(true);\n        }\n    }, []);\n\n    // Create a debounced version of runValidation for onChange triggers.\n    // validate(), submit(), and validateOnMount always use runValidation directly.\n    const debouncedValidationRef = useRef<\n        ((markTouched: boolean) => void) | null\n    >(null);\n    if (\n        resolvedOptions.validationDebounceMs != null &&\n        resolvedOptions.validationDebounceMs > 0 &&\n        !debouncedValidationRef.current\n    ) {\n        debouncedValidationRef.current = debounce((markTouched: boolean) => {\n            runValidation(markTouched);\n        }, resolvedOptions.validationDebounceMs);\n    }\n\n    const triggerValidation = useCallback(\n        (markTouched: boolean) => {\n            if (debouncedValidationRef.current) {\n                debouncedValidationRef.current(markTouched);\n                return Promise.resolve(\n                    undefined as unknown as ValidationResult<InferType<TSchema>>\n                );\n            }\n            return runValidation(markTouched);\n        },\n        [runValidation]\n    );\n\n    const useFieldHook = useCallback(\n        <TPropertySchema extends SchemaBuilder<any, any, any>>(\n            forProperty: (\n                tree: PropertyDescriptorTree<TSchema, TSchema>\n            ) => PropertyDescriptor<TSchema, TPropertySchema, any>\n        ): UseFieldResult<InferType<TPropertySchema>> => {\n            return useFieldFromContext(\n                formContextRef.current,\n                forProperty,\n                triggerValidation\n            ) as UseFieldResult<InferType<TPropertySchema>>;\n        },\n        [triggerValidation]\n    );\n\n    return useMemo(\n        () => ({\n            useField: useFieldHook,\n            submit,\n            validate,\n            reset,\n            getValue,\n            setValue: setValueFn,\n            _getFormContext\n        }),\n        [\n            useFieldHook,\n            submit,\n            validate,\n            reset,\n            getValue,\n            setValueFn,\n            _getFormContext\n        ]\n    );\n}\n\n// ─── useField (from context) ─────────────────────────────────────────────────\n\n/**\n * Internal useField implementation, requires FormContextValue.\n * Returns UseFieldResult with untyped values — callers should cast to the proper generic type.\n */\nexport function useFieldFromContext(\n    formContext: FormContextValue,\n    forProperty: (tree: any) => any,\n    triggerValidation?: (markTouched: boolean) => Promise<any>\n): UseFieldResult {\n    const { store, descriptorTree, options, pathMap } = formContext;\n\n    const descriptor = forProperty(descriptorTree as any);\n    const inner = descriptor[SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR];\n    const path = getDescriptorPath(inner, pathMap);\n    const fieldSchema = inner.getSchema();\n\n    // Initialize field state from current values on first access\n    const initializedRef = useRef<string | null>(null);\n\n    if (initializedRef.current !== path) {\n        const values = store.getValues();\n        const { success, value } = inner.getValue(values);\n        const currentState = store.getFieldState(path);\n        if (currentState.initialValue === undefined && !currentState.touched) {\n            const resolvedValue = success ? value : undefined;\n            store.updateFieldState(path, {\n                value: resolvedValue,\n                initialValue: resolvedValue,\n                dirty: false\n            });\n        }\n        initializedRef.current = path;\n    }\n\n    const [, setRenderTick] = useState(0);\n\n    // Subscribe to field changes with proper cleanup on unmount/path change\n    useEffect(() => {\n        const unsub = store.subscribe(path, () => {\n            setRenderTick(c => c + 1);\n        });\n        return unsub;\n    }, [store, path]);\n\n    const onChange = useCallback(\n        (value: any) => {\n            const values = store.getValues();\n            inner.setValue(values, value, {\n                createMissingStructure: options.createMissingStructure !== false\n            });\n            store.setValues(values);\n            const currentState = store.getFieldState(path);\n            store.updateFieldState(path, {\n                value,\n                dirty: value !== currentState.initialValue\n            });\n            // Run validation on every field change (without marking all fields touched)\n            if (triggerValidation) {\n                triggerValidation(false);\n            }\n        },\n        [store, inner, path, options, triggerValidation]\n    );\n\n    const onBlur = useCallback(() => {\n        store.updateFieldState(path, { touched: true });\n    }, [store, path]);\n\n    const setValue = useCallback(\n        (value: any) => {\n            onChange(value);\n        },\n        [onChange]\n    );\n\n    const fieldState = store.getFieldState(path);\n\n    return {\n        value: fieldState.value,\n        initialValue: fieldState.initialValue,\n        dirty: fieldState.dirty,\n        touched: fieldState.touched,\n        error: fieldState.error,\n        validating: fieldState.validating,\n        onChange,\n        onBlur,\n        setValue,\n        schema: fieldSchema\n    };\n}\n\n/**\n * Resolves a renderer from the FormSystem config based on schema type and optional variant.\n *\n * When `variant` is provided the registry is checked for `\"type:variant\"` first\n * (e.g. `\"string:password\"`). If no match is found it falls back to the base\n * `\"type\"` key (e.g. `\"string\"`).\n */\nexport function resolveRenderer(\n    config: FormSystemConfig | null,\n    schema: SchemaBuilder<any, any, any>,\n    variant?: string\n): FieldRenderer | undefined {\n    if (!config?.renderers) return undefined;\n    const type = getSchemaType(schema);\n    if (variant) {\n        const variantRenderer = config.renderers[`${type}:${variant}`];\n        if (variantRenderer) return variantRenderer;\n    }\n    return config.renderers[type];\n}\n","/**\n * A debounce function ensures that a function is not called too frequently.\n * It only allows the function to be executed after a specified delay has passed since the last call.\n * @param func The function to debounce.\n * @param wait The delay in ms before the function is called.\n */\nexport function debounce<T extends (...args: any[]) => void>(\n    func: T,\n    wait: number\n): (...args: Parameters<T>) => void {\n    let timeout: ReturnType<typeof setTimeout> | null = null;\n\n    return (...args: Parameters<T>) => {\n        if (timeout !== null) {\n            clearTimeout(timeout);\n        }\n        timeout = setTimeout(() => {\n            func(...args);\n        }, wait);\n    };\n}\n","import type { FieldState } from './types.js';\n\n/**\n * Internal form store — manages field state and notification.\n * Does not depend on React; used by hooks for state management.\n */\nexport function createFormStore(initialValues: any) {\n    let values: any = initialValues != null ? { ...initialValues } : {};\n    const fieldStates = new Map<string, FieldState>();\n    const listeners = new Map<string, Set<() => void>>();\n    const globalListeners = new Set<() => void>();\n\n    function ensureFieldState(path: string): FieldState {\n        if (!fieldStates.has(path)) {\n            fieldStates.set(path, {\n                value: undefined,\n                initialValue: undefined,\n                dirty: false,\n                touched: false,\n                error: undefined,\n                validating: false\n            });\n        }\n        return fieldStates.get(path)!;\n    }\n\n    function getFieldState(path: string): FieldState {\n        return ensureFieldState(path);\n    }\n\n    function updateFieldState(path: string, patch: Partial<FieldState>) {\n        const current = ensureFieldState(path);\n        const updated = { ...current, ...patch };\n        fieldStates.set(path, updated);\n        notifyPath(path);\n    }\n\n    function notifyPath(path: string) {\n        const pathListeners = listeners.get(path);\n        if (pathListeners) {\n            for (const listener of pathListeners) {\n                listener();\n            }\n        }\n    }\n\n    function notifyAll() {\n        for (const [, pathListeners] of listeners) {\n            for (const listener of pathListeners) {\n                listener();\n            }\n        }\n        for (const listener of globalListeners) {\n            listener();\n        }\n    }\n\n    function subscribe(path: string, listener: () => void): () => void {\n        if (!listeners.has(path)) {\n            listeners.set(path, new Set());\n        }\n        listeners.get(path)!.add(listener);\n        return () => {\n            listeners.get(path)?.delete(listener);\n        };\n    }\n\n    function subscribeGlobal(listener: () => void): () => void {\n        globalListeners.add(listener);\n        return () => {\n            globalListeners.delete(listener);\n        };\n    }\n\n    function getValues(): any {\n        return values;\n    }\n\n    function setValues(newValues: any) {\n        values = newValues != null ? { ...newValues } : {};\n    }\n\n    function resetAll(newInitialValues?: any) {\n        values = newInitialValues != null ? { ...newInitialValues } : {};\n        fieldStates.clear();\n        notifyAll();\n    }\n\n    function getAllFieldPaths(): string[] {\n        return Array.from(fieldStates.keys());\n    }\n\n    return {\n        getFieldState,\n        updateFieldState,\n        subscribe,\n        subscribeGlobal,\n        getValues,\n        setValues,\n        resetAll,\n        notifyAll,\n        getAllFieldPaths\n    };\n}\n\nexport type FormStore = ReturnType<typeof createFormStore>;\n"],"mappings":"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","names":["useContext","useMemo","createContext","FormSystemContext","FormContext","ObjectSchemaBuilder","SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR","buildDescriptorPathMap","tree","schema","map","introspected","propName","propDescriptor","inner","propSchema","childMap","childInner","childPath","getDescriptorPath","pathMap","getSchemaType","buildSelectorFromPath","path","parts","current","part","ensureNestedStructure","values","schema","introspected","result","key","propSchema","ObjectSchemaBuilder","ObjectSchemaBuilder","SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR","useCallback","useEffect","useMemo","useRef","useState","debounce","func","wait","timeout","args","createFormStore","initialValues","values","fieldStates","listeners","globalListeners","ensureFieldState","path","getFieldState","updateFieldState","patch","updated","notifyPath","pathListeners","listener","notifyAll","subscribe","subscribeGlobal","getValues","setValues","newValues","resetAll","newInitialValues","getAllFieldPaths","useSchemaForm","schema","options","resolvedOptions","storeRef","useRef","createFormStore","store","descriptorTreeRef","ObjectSchemaBuilder","descriptorTree","pathMapRef","buildDescriptorPathMap","pathMap","schemaRef","optionsRef","formContextValue","useMemo","formContextRef","validationGenRef","runValidation","useCallback","markTouched","gen","values","safeValues","ensureNestedStructure","result","allPaths","p","patch","resultWithErrors","fieldsWithErrors","getErrorsFor","path","selector","buildSelectorFromPath","fieldResult","validate","submit","reset","newValues","getValue","setValueFn","merged","_getFormContext","validateOnMountRef","useEffect","debouncedValidationRef","debounce","triggerValidation","useFieldHook","forProperty","useFieldFromContext","formContext","inner","SYMBOL_SCHEMA_PROPERTY_DESCRIPTOR","getDescriptorPath","fieldSchema","initializedRef","success","value","currentState","resolvedValue","setRenderTick","useState","c","onChange","onBlur","setValue","fieldState","resolveRenderer","config","variant","type","getSchemaType","variantRenderer","jsx","FormSystemProvider","renderers","config","children","parentConfig","useContext","FormSystemContext","resolvedConfig","useMemo","current","FormProvider","form","formContext","FormContext","useField","forProperty","useFieldFromContext","useFormSystem","Field","renderer","variant","label","name","fieldProps","fieldResult","systemConfig","resolvedRenderer","resolveRenderer","schemaType","getSchemaType","tried"]}

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+import type { SchemaBuilder } from '@cleverbrush/schema';
+import type { ReactNode } from 'react';
+/**
+ * A renderer function that receives field state and returns a React node.
+ */
+export type FieldRenderer = (props: FieldRenderProps) => ReactNode;
+/**
+ * Props passed to a field renderer.
+ */
+export type FieldRenderProps = {
+    value: any;
+    initialValue: any;
+    dirty: boolean;
+    touched: boolean;
+    error: string | undefined;
+    validating: boolean;
+    onChange: (value: any) => void;
+    onBlur: () => void;
+    setValue: (value: any) => void;
+    schema: SchemaBuilder<any, any, any>;
+    /**
+     * Rendering variant hint passed from the `Field` component.
+     * Used by renderers to select a sub-variant of the base schema type
+     * (e.g. `"password"` for a string field rendered as a password input).
+     *
+     * Also participates in renderer resolution: when set, the renderer
+     * registry is first checked for `"type:variant"` (e.g. `"string:password"`)
+     * before falling back to the base `"type"` key.
+     *
+     * @example
+     * ```tsx
+     * <Field forProperty={(t) => t.secret} form={form} variant="password" />
+     * ```
+     */
+    variant?: string;
+    /**
+     * Visible label text forwarded from the `Field` component.
+     * Renderers can use this to render a `<label>` element.
+     *
+     * @example
+     * ```tsx
+     * <Field forProperty={(t) => t.name} form={form} label="Full name" />
+     * ```
+     */
+    label?: string;
+    /**
+     * HTML `name` attribute forwarded from the `Field` component.
+     * Renderers can apply this to the underlying input for `FormData` submission.
+     *
+     * @example
+     * ```tsx
+     * <Field forProperty={(t) => t.email} form={form} name="email" />
+     * ```
+     */
+    name?: string;
+    /**
+     * Bag of extra renderer-specific props forwarded from the `Field` component.
+     * Useful for passing HTML attributes (`placeholder`, `autoComplete`, `type`)
+     * or UI-library-specific options without extending `FieldRenderProps` itself.
+     *
+     * @example
+     * ```tsx
+     * <Field
+     *   forProperty={(t) => t.email}
+     *   form={form}
+     *   fieldProps={{ placeholder: "you@example.com", autoComplete: "email" }}
+     * />
+     * ```
+     */
+    fieldProps?: Record<string, unknown>;
+};
+/**
+ * Configuration for FormSystemProvider.
+ */
+export type FormSystemConfig = {
+    renderers?: Record<string, FieldRenderer>;
+};
+/**
+ * Field state tracked per-field.
+ */
+export type FieldState = {
+    value: any;
+    initialValue: any;
+    dirty: boolean;
+    touched: boolean;
+    error: string | undefined;
+    validating: boolean;
+};
+/**
+ * Return type for useField — strongly typed with the inferred property value type.
+ * When the value type cannot be inferred, falls back to `any`.
+ */
+export type UseFieldResult<T = any> = {
+    value: T | undefined;
+    initialValue: T | undefined;
+    dirty: boolean;
+    touched: boolean;
+    error: string | undefined;
+    validating: boolean;
+    onChange: (value: T) => void;
+    onBlur: () => void;
+    setValue: (value: T) => void;
+    schema: SchemaBuilder<any, any, any>;
+};
+/**
+ * Options for useSchemaForm.
+ */
+export type UseSchemaFormOptions = {
+    createMissingStructure?: boolean;
+    /**
+     * When `true`, runs full schema validation on mount and marks all fields
+     * as touched so that error messages (e.g. for required fields) are visible
+     * immediately without waiting for user interaction.
+     *
+     * @default false
+     */
+    validateOnMount?: boolean;
+    /**
+     * Debounce delay in milliseconds for onChange-triggered validation.
+     * When set, rapid field changes only trigger one validation run after
+     * the user stops typing for the specified duration.
+     *
+     * Explicit calls to `form.validate()`, `form.submit()`, and
+     * `validateOnMount` are **not** debounced — they always run immediately.
+     *
+     * @example
+     * ```tsx
+     * const form = useSchemaForm(Schema, { validationDebounceMs: 300 });
+     * ```
+     */
+    validationDebounceMs?: number;
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+    "author": "Andrew Zolotukhin <andrew_zol@cleverbrush.com>",
+    "bugs": {
+        "url": "https://github.com/cleverbrush/framework/issues",
+        "email": "andrew_zol@cleverbrush.com"
+    },
+    "dependencies": {
+        "@cleverbrush/schema": "0.0.0-beta-20260410073748"
+    },
+    "devDependencies": {
+        "@types/react": "^19.0.0",
+        "react": "^19.0.0"
+    },
+    "peerDependencies": {
+        "react": ">=18.0.0"
+    },
+    "description": "Headless, schema-driven form system for React based on @cleverbrush/schema",
+    "files": [
+        "dist"
+    ],
+    "homepage": "https://docs.cleverbrush.com/modules/_cleverbrush_react_form.html",
+    "keywords": [
+        "react forms",
+        "schema validation",
+        "form system",
+        "cleverbrush"
+    ],
+    "license": "BSD 3-Clause",
+    "main": "./dist/index.js",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        }
+    },
+    "sideEffects": false,
+    "name": "@cleverbrush/react-form",
+    "readme": "https://github.com/cleverbrush/framework/tree/master/libs/react-form#readme",
+    "repository": {
+        "type": "git",
+        "url": "github:cleverbrush/framework"
+    },
+    "scripts": {
+        "watch": "tsc --build --watch",
+        "build": "tsup && tsc --project tsconfig.build.json --emitDeclarationOnly",
+        "clean": "rm -rf dist tsconfig.tsbuildinfo"
+    },
+    "type": "module",
+    "types": "./dist/index.d.ts",
+    "version": "0.0.0-beta-20260410073748"
+}