laif-ds/dist/agent-docs/components/FormComposer.md

Design System di Laif con componenti React basati su principi di Atomic Design

# FormComposer

## Overview

Declarative form builder using `react-hook-form` (with optional Zod). Renders inputs, selects, textareas, and checkboxes from a simple items config, handles validation, and provides a submit button with loading state.

---

## Types

### FormComposerItem

```ts
interface FormComposerItem {
  label: string;
  component: "input" | "select" | "textarea" | "checkbox";
  name: string;
  defaultValue?: string | boolean | number;
  options?: AppSelectOption[]; // only for "select"
  disabled?: boolean;
  placeholder?: string;
}
```

---

## Props

| Prop            | Type                  | Default      | Description                                        |
| --------------- | --------------------- | ------------ | -------------------------------------------------- | ----- | --------------------------- |
| `cols`          | `"1"                  | "2"          | "3"`                                               | `"2"` | Grid columns for the items. |
| `items`         | `FormComposerItem[]`  | **required** | Field configuration list.                          |
| `schema`        | `ZodTypeAny`          | `undefined`  | Optional Zod schema to enable validation/resolver. |
| `defaultValues` | `Record<string, any>` | `undefined`  | RHF default values; overrides item `defaultValue`. |
| `submitText`    | `string`              | `"Invia"`    | Submit button label.                               |
| `onSubmit`      | `(data: any) => void` | `undefined`  | Called with valid form values.                     |
| `isSubmitting`  | `boolean`             | `false`      | Controls submit button loading/disabled state.     |

---

## Behavior

- **Validation**: If `schema` is provided, a Zod resolver is attached; otherwise native validity is used.
- **Defaults**: Each `item.defaultValue` is merged into RHF defaults, unless `defaultValues` is passed.
- **Components**:
  - `component: "input"` → `Input` with `label` and `placeholder`.
  - `component: "textarea"` → `Textarea` with `label`.
  - `component: "select"` → `AppSelect` with `options`.
  - `component: "checkbox"` → `Checkbox` + `Label` inline.
- **Errors**: Zod error messages are rendered under each field.
- **Layout**: Items are placed in a responsive grid with `cols` columns; last item may span full width.

---

## Examples

### With Zod Schema

```tsx
import { z } from "zod";
import { FormComposer } from "laif-ds";

const formSchema = z.object({
  name: z.string().min(2, "Il nome è troppo corto"),
  email: z.string().email("Email non valida"),
  message: z.string().min(10, "Almeno 10 caratteri"),
  select: z.string().min(1, "Seleziona una opzione"),
  checkbox: z.boolean().default(false),
});

export function ContactForm() {
  return (
    <div className="w-[800px]">
      <FormComposer
        schema={formSchema}
        items={[
          {
            label: "Name",
            component: "input",
            name: "name",
            placeholder: "Inserisci il tuo nome",
            defaultValue: "ciao",
          },
          {
            label: "Select",
            component: "select",
            name: "select",
            defaultValue: "1",
            options: [
              { value: "1", label: "Option 1" },
              { value: "2", label: "Option 2" },
              { value: "3", label: "Option 3" },
            ],
          },
          {
            label: "Email",
            component: "input",
            name: "email",
            placeholder: "Inserisci la tua email",
          },
          {
            label: "Checkbox",
            component: "checkbox",
            name: "checkbox",
            defaultValue: true,
          },
          {
            label: "Message",
            component: "textarea",
            name: "message",
            placeholder: "Inserisci il tuo messaggio",
          },
        ]}
        onSubmit={(data) => console.log(data)}
      />
    </div>
  );
}
```

### Submit State

```tsx
import * as React from "react";
import { z } from "zod";
import { FormComposer } from "laif-ds";

const schema = z.object({ name: z.string().min(2), email: z.string().email() });

export function SubmitExample() {
  const [values, setValues] = React.useState({});
  const [isSubmitting, setSubmitting] = React.useState(false);

  const onSubmit = (data: any) => {
    setSubmitting(true);
    setTimeout(() => setSubmitting(false), 2000);
    setValues(data);
  };

  return (
    <div className="w-[800px]">
      <FormComposer
        schema={schema}
        items={[
          { label: "Name", component: "input", name: "name" },
          { label: "Email", component: "input", name: "email" },
        ]}
        onSubmit={onSubmit}
        isSubmitting={isSubmitting}
      />
      <pre>{JSON.stringify(values, null, 2)}</pre>
    </div>
  );
}
```

---

## Notes

- **Extensibility**: Use `startContent`, `endContent`, `iconLeft`, `iconRight` props of `Input` for richer fields.
- **Select**: Provide `options` for `component: "select"` (`AppSelectOption[]`).
- **Accessibility**: Labels are wired via `htmlFor`/`id`; errors use `role="alert"` and `aria-live` when relevant.