react-form-dto 0.0.1 → 0.0.2

package/README.md

@@ -18,6 +18,14 @@ This library lets you define forms declaratively using JSON DTOs (`FormDTO`, `Se
 
 ---
 
+📘 Documentation
+
+Comprehensive documentation is available here
+
+👉 [Documentation](https://shakir-afridi.github.io/react-form-dto/)
+
+---
+
 ## 📦 Installation
 
 Clone the repo and install dependencies:

package/dist/components/Field.d.ts

@@ -0,0 +1,34 @@
+import { default as React } from 'react';
+import { FieldDTO } from '../types';
+/**
+ * Props passed to field renderer components.
+ */
+export interface FieldRendererProps {
+    /** The field definition containing type, label, validation rules, etc. */
+    field: FieldDTO;
+    /** The current value of the field */
+    value: any;
+    /** Callback function to update the field value */
+    onChange: (val: any) => void;
+    error?: string | null;
+}
+/**
+ * Props for the Field component.
+ */
+interface FieldProps extends FieldRendererProps {
+    renderers?: Record<string, React.ComponentType<FieldRendererProps>>;
+}
+/**
+ * Field component that renders the appropriate input component based on field type.
+ * Supports both default renderers and custom renderers provided via props.
+ *
+ * @example
+ * <Field
+ *   field={fieldDTO}
+ *   value={currentValue}
+ *   onChange={handleChange}
+ *   renderers={{ customType: CustomRenderer }}
+ * />
+ */
+export declare const Field: React.FC<FieldProps>;
+export {};

package/dist/components/FormBuilder.d.ts

@@ -0,0 +1,45 @@
+import { default as React } from 'react';
+import { FormDTO } from '../types';
+/**
+ * Handle interface exposed by FormBuilder via ref.
+ * Provides methods to interact with the form programmatically.
+ */
+export type FormBuilderHandle = {
+    /** Returns all current form values */
+    getValues: () => Record<string, any>;
+    /** Returns all current form errors */
+    getErrors: () => Record<string, string | null>;
+    /** Validates all fields and returns errors */
+    validateAll: () => Record<string, string[]>;
+    /** Validates a specific field by ID and returns errors */
+    validateField: (id: string) => string[];
+    handleChange?: (id: string, val: any) => void;
+};
+/**
+ * Props for the FormBuilder component.
+ */
+type FormBuilderProps = {
+    /** The form DTO definition containing all sections and fields */
+    dto: FormDTO;
+    /** Optional custom renderers for specific field types */
+    renderers?: Record<string, React.ComponentType<any>>;
+};
+/**
+ * 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);
+ *
+ * const handleSubmit = () => {
+ *   const errors = formRef.current?.validateAll();
+ *   if (Object.keys(errors || {}).length === 0) {
+ *     const values = formRef.current?.getValues();
+ *     // Submit form values
+ *   }
+ * };
+ *
+ * <FormBuilder ref={formRef} dto={myFormDTO} renderers={customRenderers} />
+ */
+export declare const FormBuilder: React.ForwardRefExoticComponent<FormBuilderProps & React.RefAttributes<FormBuilderHandle>>;
+export {};

package/dist/components/Section.d.ts

@@ -0,0 +1,30 @@
+import { default as React } from 'react';
+import { SectionDTO } from '../types';
+/**
+ * Props for the Section component.
+ */
+type SectionProps = {
+    /** The section definition containing heading, description, and fields */
+    section: SectionDTO;
+    /** Current form values keyed by field ID */
+    values: Record<string, any>;
+    /** Callback function to handle field value changes */
+    onChange: (id: string, val: any) => void;
+    /** Optional custom renderers for specific field types */
+    renderers?: Record<string, React.ComponentType<any>>;
+    validateField: (id: string) => string[];
+};
+/**
+ * Section component that renders a form section with its heading, description, and fields.
+ * Automatically arranges fields in a responsive grid layout based on their column span configuration.
+ *
+ * @example
+ * <Section
+ *   section={sectionDTO}
+ *   values={formValues}
+ *   onChange={handleFieldChange}
+ *   renderers={customRenderers}
+ * />
+ */
+export declare const Section: React.FC<SectionProps>;
+export {};

package/dist/components/index.d.ts

@@ -0,0 +1,4 @@
+export * from './Field';
+export * from './FormBuilder';
+export * from './Section';
+export * from './renderers';

package/dist/components/renderers/AutoComplete.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+import { FieldDTO } from '../../types';
+type AutoCompleteFieldProps = {
+    field: FieldDTO;
+    value: any;
+    onChange: (val: any) => void;
+    error?: string | null;
+};
+export declare const AutoCompleteField: React.FC<AutoCompleteFieldProps>;
+export {};

package/dist/components/renderers/CheckBoxInput.d.ts

@@ -0,0 +1,16 @@
+import { FieldRendererProps } from '../../components/Field';
+/**
+ * Checkbox input renderer for boolean/checkbox field types.
+ * Renders a Material-UI Checkbox wrapped in a FormControlLabel.
+ *
+ * @param props - Field renderer props containing field definition, value, and onChange handler
+ * @returns A configured Checkbox component with label
+ *
+ * @example
+ * <CheckBoxInput
+ *   field={fieldDTO}
+ *   value={isChecked}
+ *   onChange={handleChange}
+ * />
+ */
+export declare function CheckBoxInput({ field, value, onChange, error, }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/renderers/MultiAutoComplete.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+import { FieldDTO } from '../../types';
+type MultiAutoCompleteFieldProps = {
+    field: FieldDTO;
+    value: any[];
+    onChange: (val: any) => void;
+    error?: string | null;
+};
+export declare const MultiAutoCompleteField: React.FC<MultiAutoCompleteFieldProps>;
+export {};

package/dist/components/renderers/RadioInput.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+import { FieldDTO } from '../../types';
+type RadioInputProps = {
+    field: FieldDTO;
+    value: any;
+    onChange: (val: any) => void;
+    error?: string | null;
+};
+export declare const RadioInput: React.FC<RadioInputProps>;
+export {};

package/dist/components/renderers/SelectInput.d.ts

@@ -0,0 +1,16 @@
+import { FieldRendererProps } from '../../components/Field';
+/**
+ * Select input renderer for dropdown/select field types.
+ * Renders a Material-UI Select component with options from the field definition.
+ *
+ * @param props - Field renderer props containing field definition, value, and onChange handler
+ * @returns A configured Select component with MenuItems for each option
+ *
+ * @example
+ * <SelectInput
+ *   field={fieldDTO}
+ *   value={selectedValue}
+ *   onChange={handleChange}
+ * />
+ */
+export declare function SelectInput({ field, value, onChange, error, }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/renderers/TextInput.d.ts

@@ -0,0 +1,16 @@
+import { FieldRendererProps } from '../../components/Field';
+/**
+ * Text input renderer for text, number, and date field types.
+ * Renders a Material-UI TextField with appropriate configuration based on field properties.
+ *
+ * @param props - Field renderer props containing field definition, value, and onChange handler
+ * @returns A configured TextField component
+ *
+ * @example
+ * <TextInput
+ *   field={fieldDTO}
+ *   value={currentValue}
+ *   onChange={handleChange}
+ * />
+ */
+export declare function TextInput({ field, value, onChange, error, }: FieldRendererProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/renderers/TextareaInput.d.ts

@@ -0,0 +1,10 @@
+import { default as React } from 'react';
+import { FieldDTO } from '../../types';
+type TextAreaInputProps = {
+    field: FieldDTO;
+    value: any;
+    onChange: (val: any) => void;
+    error?: string | null;
+};
+export declare const TextAreaInput: React.FC<TextAreaInputProps>;
+export {};

package/dist/components/renderers/index.d.ts

@@ -0,0 +1,7 @@
+export * from './AutoComplete';
+export * from './CheckBoxInput';
+export * from './MultiAutoComplete';
+export * from './RadioInput';
+export * from './SelectInput';
+export * from './TextareaInput';
+export * from './TextInput';

package/dist/examples/profileForm.d.ts

@@ -0,0 +1,2 @@
+import { FormDTO } from '../types';
+export declare const profileForm: FormDTO;

package/dist/hooks/index.d.ts

@@ -0,0 +1 @@
+export * from './useFormBuilder';

package/dist/hooks/useFormBuilder.d.ts

@@ -0,0 +1,29 @@
+import { FormDTO } from '../types';
+type Errors = Record<string, string | null>;
+/**
+ * A custom React hook for building and managing form state with validation.
+ * Provides form values, errors, and validation utilities for a given FormDTO.
+ *
+ * @param dto - The form DTO definition containing sections and fields
+ * @returns An object containing form state and utility functions
+ *
+ * @example
+ * const form = useFormBuilder(myFormDTO);
+ * form.handleChange('email', 'user@example.com');
+ * const errors = form.validateAll();
+ */
+export declare function useFormBuilder(dto: FormDTO): {
+    /** Current form values for all fields */
+    values: Record<string, any>;
+    /** Function to update a field value */
+    handleChange: (id: string, val: any) => void;
+    /** Function to validate all fields */
+    validateAll: () => Record<string, string[]>;
+    /** Function to get all current form values */
+    getValues: () => Record<string, any>;
+    /** Function to get all current form errors */
+    getErrors: () => Errors;
+    /** Function to validate a specific field */
+    validateField: (id: string) => string[];
+};
+export {};

package/dist/index.d.ts

@@ -1 +1,4 @@
-export {}
+export { FormBuilder, Section, Field, TextAreaInput, AutoCompleteField, MultiAutoCompleteField, RadioInput, SelectInput, TextInput, CheckBoxInput, } from './components';
+export { validateAll, validateField, validationRules } from './utils';
+export type { FieldDTO, SectionDTO, FormDTO, InputType, Validations, } from './types';
+export { useFormBuilder } from './hooks';