laif-ds

# AppForm ## Overview Dynamic form component that integrates with React Hook Form to provide a configurable form with multiple field types including input, textarea, select, multiselect, datepicker, radio, checkbox, switch, and slider. Automatically handles validation errors and form state. --- ## Types ### AppFormItem ```ts export type AppFormItem<TAsyncOption = unknown> = { /** Field label displayed above the component. */ label: string; /** The type of form component to render. */ component: | "input" | "select" | "textarea" | "checkbox" | "multiselect" | "datepicker" | "radio" | "switch" | "slider" | "async" | "async-multiple" | "custom"; /** Field name used for React Hook Form state binding and validation. */ name: string; /** * HTML input type. Only applies when `component` is `"input"`. * @example "text" | "email" | "password" | "number" | "url" | "search" | "tel" */ inputType?: ComponentProps<"input">["type"]; /** Initial value for the field. */ defaultValue?: string | boolean | number | string[] | Date | number[]; /** Options list for `select`, `multiselect`, and `radio` components. */ options?: AppSelectOption[]; /** Disables the field, preventing user interaction. @default false */ disabled?: boolean; /** Placeholder text shown when no value is selected or entered. */ placeholder?: string; /** Helper text displayed below the field. */ caption?: string; /** * Enables range mode on the `datepicker` component when provided. * The two dates define the selectable calendar boundaries. */ calendarRange?: [Date, Date]; /** Minimum value for the `slider` component. @default 0 */ min?: number; /** Maximum value for the `slider` component. @default 100 */ max?: number; /** Step increment for the `slider` component. @default 1 */ step?: number; /** * Async data loader for `async` and `async-multiple` components. * Called with the current search query; must return a promise of options. */ fetcher?: (query?: string) => Promise<TAsyncOption[]>; /** * Custom render function for each option item in the async dropdown. * Required for `async` and `async-multiple` components. */ renderOptionItem?: (option: TAsyncOption) => React.ReactNode; /** * Extracts the unique string value from an async option object. * Required for `async` and `async-multiple` components. */ resolveOptionValue?: (option: TAsyncOption) => string; /** * Custom render function for the selected value chip/label. * Required for `async` and `async-multiple` components. */ renderSelectedValue?: (option: TAsyncOption) => React.ReactNode; /** * Pre-loaded options used to hydrate the async select on mount, * avoiding an initial fetch when the value is already known. */ initialOptions?: TAsyncOption[]; /** Custom node displayed when the async fetcher returns no results at all. */ notFound?: React.ReactNode; /** Message shown when the async search query returns no matching results. */ noResultsMessage?: string; /** Debounce delay in milliseconds for the async search input. @default 300 */ debounce?: number; /** Allows the user to clear the selected value in the async select. @default false */ clearable?: boolean; /** Extra props forwarded directly to the `DatePicker` component. */ datePickerProps?: Partial<DatePickerProps>; /** Column span for the item in the grid. @default undefined (auto, or "full" for the last item) */ colSpan?: "1" | "2" | "3" | "full"; /** Icon on the left side. Only applies when `component` is `"input"`. */ iconLeft?: IconName; /** Icon on the right side. Only applies when `component` is `"input"`. */ iconRight?: IconName; /** Enables search/filter inside `select` and `multiselect` dropdowns. @default true */ searchable?: boolean; /** Hides the label above the field. @default false */ hideLabel?: boolean; /** Additional CSS class name applied to the item container div. */ className?: string; /** * Additional props forwarded to the underlying UI component. * Strongly typed based on the chosen `component` value. */ componentProps?: AppFormItemComponentProps[TComponent]; /** * Custom render function for the component. * Required when `component` is `"custom"`. */ render?: (props: { field: ControllerRenderProps<FieldValues, string>; error?: string; label: React.ReactNode; }) => React.ReactNode; }; ``` ### Submit Button Inside vs Outside ```tsx import { AppForm, Button } from "laif-ds"; import { useForm } from "react-hook-form"; export function SubmitInsideVsOutside() { const formInside = useForm({ mode: "onChange" }); const formOutside = useForm({ mode: "onChange" }); const onSubmitInside = (data: any) => console.log("inside", data); const onSubmitOutside = (data: any) => console.log("outside", data); return ( <div className="grid grid-cols-2 gap-6"> <div> {/* Internal submit button rendered by AppForm */} <AppForm form={formInside} items={[{ label: "Name", component: "input", name: "name" }]} onSubmit={onSubmitInside} showSubmitButton /> </div> <div> {/* External submit button managed outside */} <AppForm form={formOutside} items={[{ label: "Name", component: "input", name: "name" }]} onSubmit={onSubmitOutside} /> <div className="mt-4 flex justify-end"> <Button type="button" disabled={ !formOutside.formState.isValid || !formOutside.formState.isDirty } onClick={formOutside.handleSubmit(onSubmitOutside)} > Submit (external) </Button> </div> </div> </div> ); } ``` --- ## Props | Prop | Type | Default | Description | | ------------------ | --------------------- | ------------ | -------------------------------------------------------- | | `items` | `AppFormItem[]` | **required** | Array of field configurations | | `form` | `UseFormReturn<any>` | **required** | React Hook Form instance returned by `useForm` | | `cols` | `"1" \| "2" \| "3"` | `"2"` | Number of grid columns | | `submitText` | `string` | `"Invia"` | Text label for the internal submit button | | `onSubmit` | `(data: any) => void` | `undefined` | Callback fired with validated form data on submission | | `isSubmitting` | `boolean` | `false` | Shows loading spinner on the submit button | | `showSubmitButton` | `boolean` | `false` | Renders an internal submit button at the end of the form | --- ## Behavior - **React Hook Form Integration**: Uses `Controller` from React Hook Form for each field - **Validation Display**: Shows validation errors inline with each field - **Grid Layout**: Automatically arranges fields in a responsive grid based on `cols` prop. Use `colSpan` on items for fine-grained control. - **Submit Button**: Rendered only when `showSubmitButton` is `true`. When shown, it is disabled when the form is invalid or pristine. Otherwise, manage submit externally with `form.handleSubmit(...)`. - **Last Field Spanning**: The last field automatically spans full width unless `colSpan` is explicitly set. - **Error Highlighting**: Fields with errors get red border styling --- ## Field Types ### input Standard text input field. Supports `iconLeft` and `iconRight`. When `component: "input"`, use the `inputType` property to control the underlying HTML input type (e.g. `"text"`, `"email"`, `"password"`, `"number"`, `"url"`). ### select / multiselect Single or multiple selection dropdown using `AppSelect`. Supports `searchable: true`. ### custom Allows rendering any arbitrary content within the form grid. Requires the `render` function. ```tsx { label: "Custom Section", component: "custom", name: "customInfo", render: ({ field, error, label }) => ( <div className="p-4 border rounded"> {label} <input {...field} className="border p-2" /> {error && <span className="text-red-500">{error}</span>} </div> ), colSpan: "full" } ``` ### async / async-multiple Use `AsyncSelect` for server-side driven selects. `async` handles a single string value, `async-multiple` an array of strings. Required props for both: `fetcher`, `renderOptionItem`, `resolveOptionValue`, `renderSelectedValue`. ### datepicker Date picker component with optional range selection via `calendarRange`. Pass `datePickerProps` for locale, format, or other `DatePicker` customisation. ### radio / checkbox / switch / slider Standard form components for various input types. --- ## Examples ### Grid and Icons Example ```tsx const items: AppFormItem[] = [ { label: "First Name", component: "input", name: "firstName", colSpan: "1", }, { label: "Last Name", component: "input", name: "lastName", colSpan: "1", }, { label: "Email", component: "input", name: "email", iconLeft: "Mail", colSpan: "full", }, { label: "Department", component: "select", name: "dept", options: [ /* ... */ ], colSpan: "full", }, ]; return <AppForm form={form} items={items} cols="2" showSubmitButton />; ``` ### Advanced componentProps Use `componentProps` to pass specific properties to the underlying UI components that are not exposed directly in `AppFormItem`. ```tsx { label: "Bio", component: "textarea", name: "bio", componentProps: { rows: 10, className: "resize-none" } } ``` --- ## Notes - **React Hook Form Required**: This component requires React Hook Form to be installed and configured - **Grid Layout**: The grid uses Tailwind's grid system with `grid-cols-{n}` classes - **Type Safety**: `componentProps` is strictly typed based on the `component` chosen.