react-form-dto 1.0.3 → 1.0.5

package/README.md

@@ -146,6 +146,148 @@ return (
 
 ---
 
+## useFormBuilderController – Controlled, Auto‑Rendered Forms
+
+`useFormBuilderController` is a hook that wraps `FormBuilder` and gives you:
+
+- An auto-rendering `Form` component (no manual mapping of sections/fields)
+- An imperative controller API for values, errors, and validation
+
+It combines the convenience of `FormBuilder` with the programmatic control of `useFormBuilder`.
+
+### When to Use
+
+- You want the form UI to be generated entirely from a DTO
+- You need to:
+  - Run validation on submit
+  - Read values/errors from outside the form
+  - Prefill fields programmatically
+  - Plug in custom field renderers
+
+### Basic Example
+
+```tsx
+import { useFormBuilderController } from 'react-form-dto';
+import { myFormDTO } from './myFormDTO';
+
+function MyFormWithController() {
+  const formController = useFormBuilderController({
+    dto: myFormDTO,
+    locale: 'en',
+  });
+
+  const handleSubmit = (e: React.FormEvent) => {
+    e.preventDefault();
+
+    const errors = formController.validateAll();
+    const hasErrors = Object.values(errors).some(
+      (err) => err && err.length > 0,
+    );
+
+    if (hasErrors) {
+      console.log('Validation errors:', errors);
+      return;
+    }
+
+    console.log('Form submitted:', formController.getValues());
+  };
+
+  return (
+    <form onSubmit={handleSubmit}>
+      {/* Auto-renders the full form from the DTO */}
+      <formController.Form />
+      <button type="submit">Submit</button>
+    </form>
+  );
+}
+```
+
+### API Overview
+
+```ts
+const controller = useFormBuilderController({
+  dto: myFormDTO,
+  locale: 'en',
+  renderers: {
+    // optional: override field types
+    text: MyTextField,
+  },
+  handleChangeCallback: (id, value) => {
+    // optional: side effects on every field change
+    console.log(id, value);
+  },
+});
+
+// Reading and validating
+controller.getValues();        // Record<string, any>
+controller.getErrors();        // Record<string, string | null>
+controller.validateAll();      // Record<string, string[] | null>
+controller.validateField('id'); // string[]
+
+// Programmatic updates
+controller.handleChange('firstName', 'Jane');
+```
+
+### Example with Prefill and Custom Renderers
+
+```tsx
+import { useFormBuilderController } from 'react-form-dto';
+import { myFormDTO } from './myFormDTO';
+import { TextInput, SelectInput } from './customFields';
+
+const renderers = {
+  text: TextInput,
+  select: SelectInput,
+};
+
+function AdvancedForm() {
+  const formController = useFormBuilderController({
+    dto: myFormDTO,
+    locale: 'en',
+    renderers,
+    handleChangeCallback: (id, value) => {
+      // sync with external store / analytics, etc.
+      console.log('Changed:', id, value);
+    },
+  });
+
+  const prefill = () => {
+    formController.handleChange('firstName', 'John');
+    formController.handleChange('lastName', 'Doe');
+  };
+
+  return (
+    <>
+      <button type="button" onClick={prefill}>
+        Prefill
+      </button>
+
+      <form
+        onSubmit={(e) => {
+          e.preventDefault();
+          const errors = formController.validateAll();
+          const hasErrors = Object.values(errors).some(
+            (err) => err && err.length > 0,
+          );
+          if (!hasErrors) {
+            console.log('Values:', formController.getValues());
+          }
+        }}
+      >
+        <formController.Form />
+        <button type="submit">Submit</button>
+      </form>
+    </>
+  );
+}
+```
+
+> For the full hook reference, see  
+> **Docs → Hooks → `useFormBuilderController`**:  
+> `docs/api/hooks/useFormBuilderController.md`
+
+---
+
 ## 📋 Example Form rendered
 
 ![Form Example](./example.png)

package/dist/components/FormBuilder.d.ts

@@ -29,20 +29,26 @@ type FormBuilderProps = {
 };
 /**
  * FormBuilder component that dynamically renders a form based on a FormDTO definition.
- * Supports custom field renderers, validation, and programmatic access via ref.
  *
- * @example
- * const formRef = useRef<FormBuilderHandle>(null);
+ * **Standalone mode** (existing behaviour, unchanged):
+ * Manage state internally and expose `getValues`, `validateAll`, etc. via a ref.
+ *
+ * **Context mode** (new):
+ * When rendered inside a `<FormProvider>` the component reads values from
+ * context and writes back through `setValue`. Errors are also stored in
+ * context so they only appear after the field is touched or `trigger()` /
+ * `handleSubmit()` is called — matching react-hook-form UX conventions.
  *
- * const handleSubmit = () => {
- *   const errors = formRef.current?.validateAll();
- *   if (Object.keys(errors || {}).length === 0) {
- *     const values = formRef.current?.getValues();
- *     // Submit form values
- *   }
- * };
+ * @example Standalone
+ * const formRef = useRef<FormBuilderHandle>(null);
+ * <FormBuilder ref={formRef} dto={myFormDTO} />
  *
- * <FormBuilder ref={formRef} dto={myFormDTO} renderers={customRenderers} />
+ * @example With FormProvider (useFormDTO)
+ * const form = useFormDTO(myFormDTO);
+ * <FormProvider value={form}>
+ *   <FormBuilder dto={myFormDTO} />
+ *   <button onClick={form.handleSubmit(onSubmit)}>Submit</button>
+ * </FormProvider>
  */
 export declare const FormBuilder: React.ForwardRefExoticComponent<FormBuilderProps & React.RefAttributes<FormBuilderHandle>>;
 export {};

package/dist/example/Demo.d.ts

@@ -0,0 +1 @@
+export declare function ReactHookFormDemo(): import("react/jsx-runtime").JSX.Element;

package/dist/form/FormContext.d.ts

@@ -0,0 +1,41 @@
+import { default as React } from 'react';
+export type FieldError = string | null | undefined;
+export interface FieldArrayHelpers {
+    fields: any[];
+    append: (value: any) => void;
+    remove: (index: number) => void;
+    prepend: (value: any) => void;
+    swap: (a: number, b: number) => void;
+    insert: (index: number, value: any) => void;
+}
+export interface FormContextType<T extends object = any> {
+    values: T;
+    errors: {
+        [K in keyof T]?: FieldError;
+    };
+    touchedFields: {
+        [K in keyof T]?: boolean;
+    };
+    register: (name: string, options?: {
+        validate?: (value: any) => FieldError;
+    }) => {
+        name: string;
+        ref: (el: HTMLInputElement | null) => void;
+        onChange: (e: React.ChangeEvent<any>) => void;
+        onBlur: () => void;
+    };
+    setValue: (name: string, value: any, shouldValidate?: boolean) => void;
+    getValues: () => T;
+    setError: (name: string, error: FieldError) => void;
+    clearError: (name: string) => void;
+    handleSubmit: (cb: (data: T, event?: React.BaseSyntheticEvent) => void) => (e?: React.SyntheticEvent) => void;
+    reset: (nextValues?: Partial<T>) => void;
+    trigger: (name?: string) => boolean;
+    /** Self-reference so child components can do `const { control } = useFormContext()` and spread `control.register(...)` */
+    control: FormContextType<T>;
+    watch: (name?: string | string[]) => any;
+}
+export declare const FormContext: React.Context<FormContextType<any> | undefined>;
+export declare function useFormContext<T extends object = any>(): FormContextType<T>;
+/** Returns the context value without throwing — useful for optional context bridges. */
+export declare function useOptionalFormContext<T extends object = any>(): FormContextType<T> | undefined;

package/dist/form/FormProvider.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+import { FormContextType } from './FormContext';
+type Props<T extends object> = {
+    value: FormContextType<T>;
+    children: React.ReactNode;
+};
+export declare function FormProvider<T extends object = {}>({ value, children, }: Props<T>): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/form/useFieldArray.d.ts

@@ -0,0 +1,10 @@
+export declare function useFieldArray<T extends object = any>(props: {
+    name: keyof T;
+}): {
+    fields: any[];
+    append: (value: any) => void;
+    prepend: (value: any) => void;
+    remove: (index: number) => void;
+    swap: (iA: number, iB: number) => void;
+    insert: (index: number, value: any) => void;
+};

package/dist/form/useForm.d.ts

@@ -0,0 +1,10 @@
+import { FormContextType, FieldError } from './FormContext';
+type FieldValidation = (value: any) => FieldError;
+type UseFormOptions<T> = {
+    defaultValues?: Partial<T>;
+    validate?: {
+        [K in keyof T]?: FieldValidation;
+    };
+};
+export declare function useForm<T extends object = any>(options?: UseFormOptions<T>): FormContextType<T>;
+export {};

package/dist/form/useWatch.d.ts

@@ -0,0 +1 @@
+export declare function useWatch<T extends object = any>(name: keyof T | (keyof T)[]): any;

package/dist/hooks/index.d.ts

@@ -1 +1,3 @@
 export * from './useFormBuilder';
+export * from './useFormBuilderController';
+export * from './useFormDTO';

package/dist/hooks/useFormBuilderController.d.ts

@@ -0,0 +1,16 @@
+import { FormDTO } from '../types';
+type FormBuilderControllerProps = {
+    dto: FormDTO;
+    locale: string;
+    renderers?: Record<string, React.ComponentType<any>>;
+    handleChangeCallback?: (id: string, val: any) => void;
+};
+export declare const useFormBuilderController: (props: FormBuilderControllerProps) => {
+    getValues: () => Record<string, any>;
+    getErrors: () => Record<string, string | null>;
+    validateAll: () => Record<string, string[]>;
+    validateField: (id: string) => string[];
+    handleChange: (id: string, val: any) => void | undefined;
+    Form: () => import("react/jsx-runtime").JSX.Element;
+};
+export {};

package/dist/hooks/useFormDTO.d.ts

@@ -0,0 +1,21 @@
+import { FormDTO } from '../types';
+/**
+ * Creates a react-hook-form–style form bound to a FormDTO.
+ *
+ * Default values are extracted from `field.defaultValue`.
+ * Validation rules come directly from `field.validations`.
+ *
+ * Use together with `<FormProvider>` and `<FormBuilder>` to get the
+ * full hook-form experience without managing a ref:
+ *
+ * @example
+ * const form = useFormDTO(myDTO);
+ *
+ * <FormProvider value={form}>
+ *   <FormBuilder dto={myDTO} />
+ *   <button onClick={form.handleSubmit(onSubmit)}>Submit</button>
+ * </FormProvider>
+ */
+export declare function useFormDTO<T extends object = Record<string, any>>(dto: FormDTO, options?: {
+    locale?: string;
+}): import('..').FormContextType<T>;

package/dist/index.d.ts

@@ -1,4 +1,11 @@
 export { FormBuilder, Section, Field, TextAreaInput, AutoCompleteField, MultiAutoCompleteField, RadioInput, SelectInput, TextInput, CheckBoxInput, } from './components';
+export type { FormBuilderHandle } from './components/FormBuilder';
+export { useFormBuilder, useFormBuilderController, useFormDTO } from './hooks';
+export { useForm } from './form/useForm';
+export { useFieldArray } from './form/useFieldArray';
+export { useWatch } from './form/useWatch';
+export { FormProvider } from './form/FormProvider';
+export { useFormContext, useOptionalFormContext, } from './form/FormContext';
+export type { FormContextType, FieldError, FieldArrayHelpers } from './form/FormContext';
 export { validateAll, validateField, validationRules } from './utils';
 export type { FieldDTO, SectionDTO, FormDTO, InputType, Validations, Condition as VisibleWhenCondition, FieldCondition as VisibleWhenFieldCondition, ConditionGroup as VisibleWhenConditionGroup, } from './types';
-export { useFormBuilder } from './hooks';