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

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

# AppCheckbox

## Overview

Enhanced checkbox group component with support for icons, descriptions, card layout, horizontal/vertical orientation, and comprehensive error handling. Built on top of the base Checkbox component with additional styling and features.

---

## Types

### AppCheckboxOption

```ts
export interface AppCheckboxOption {
  value: string; // Unique value for the option
  label: string | React.ReactNode; // Display label (can be JSX)
  description?: string | React.ReactNode; // Optional description text
  disabled?: boolean; // Disables this specific option
  icon?: IconName; // Optional icon name
}
```

---

## Props

| Prop              | Type                         | Default      | Description                                     |
| ----------------- | ---------------------------- | ------------ | ----------------------------------------------- |
| `options`         | `AppCheckboxOption[]`        | **required** | Array of checkbox options                       |
| `value`           | `string[]`                   | `undefined`  | Controlled value (array of selected values)     |
| `defaultValue`    | `string[]`                   | `undefined`  | Uncontrolled default value                      |
| `onValueChange`   | `(value: string[]) => void`  | `undefined`  | Callback when value changes                     |
| `label`           | `string \| React.ReactNode`  | `undefined`  | Label for the checkbox group                    |
| `description`     | `string \| React.ReactNode`  | `undefined`  | Description text below label                    |
| `disabled`        | `boolean`                    | `false`      | Disables all options                            |
| `required`        | `boolean`                    | `false`      | Shows required asterisk                         |
| `name`            | `string`                     | `undefined`  | Form name attribute                             |
| `orientation`     | `"horizontal" \| "vertical"` | `"vertical"` | Layout orientation                              |
| `className`       | `string`                     | `""`         | Additional classes for checkbox group container |
| `wrpClassName`    | `string`                     | `""`         | Additional classes for outer wrapper            |
| `optionClassName` | `string`                     | `""`         | Additional classes for each option              |
| `layout`          | `"default" \| "card"`        | `"default"`  | Visual layout style                             |
| `error`           | `string`                     | `undefined`  | Error message to display                        |

---

## Behavior

- **Controlled/Uncontrolled**: Supports both controlled (`value` + `onValueChange`) and uncontrolled (`defaultValue`) modes
- **Multiple Selection**: Users can select multiple options simultaneously
- **Icons**: Automatically renders icons when provided in options
- **Card Layout**: In card mode, options have border, shadow, and background styling
- **Error State**: Red text for label and error message display when `error` prop is provided
- **Disabled State**: Applies opacity and cursor changes to disabled options

---

## Examples

### Basic Usage

```tsx
import { AppCheckbox } from "laif-ds";
import { useState } from "react";

export function BasicCheckbox() {
  const [value, setValue] = useState(["option1"]);

  return (
    <AppCheckbox
      label="Choose options"
      options={[
        { value: "option1", label: "Option 1" },
        { value: "option2", label: "Option 2" },
        { value: "option3", label: "Option 3" },
      ]}
      value={value}
      onValueChange={setValue}
    />
  );
}
```

### With Icons and Descriptions

```tsx
import { AppCheckbox } from "laif-ds";
import { useState } from "react";

export function CheckboxWithIcons() {
  const [value, setValue] = useState(["email"]);

  return (
    <AppCheckbox
      label="Notification Preferences"
      description="Choose how you want to receive notifications"
      options={[
        {
          value: "email",
          label: "Email",
          description: "Receive notifications via email",
          icon: "Mail",
        },
        {
          value: "sms",
          label: "SMS",
          description: "Receive notifications via text message",
          icon: "MessageSquare",
        },
        {
          value: "push",
          label: "Push",
          description: "Receive push notifications",
          icon: "Bell",
        },
      ]}
      value={value}
      onValueChange={setValue}
    />
  );
}
```

### Card Layout

```tsx
import { AppCheckbox } from "laif-ds";
import { useState } from "react";

export function CardCheckbox() {
  const [value, setValue] = useState(["feature1"]);

  return (
    <AppCheckbox
      label="Select features"
      layout="card"
      options={[
        {
          value: "feature1",
          label: "Advanced Analytics",
          description: "Detailed insights and reports",
          icon: "BarChart",
        },
        {
          value: "feature2",
          label: "Team Collaboration",
          description: "Work together in real-time",
          icon: "Users",
        },
        {
          value: "feature3",
          label: "Priority Support",
          description: "24/7 dedicated support",
          icon: "Headphones",
        },
      ]}
      value={value}
      onValueChange={setValue}
    />
  );
}
```

### Horizontal Orientation

```tsx
import { AppCheckbox } from "laif-ds";
import { useState } from "react";

export function HorizontalCheckbox() {
  const [value, setValue] = useState(["small"]);

  return (
    <AppCheckbox
      label="Available Sizes"
      orientation="horizontal"
      options={[
        { value: "small", label: "Small" },
        { value: "medium", label: "Medium" },
        { value: "large", label: "Large" },
      ]}
      value={value}
      onValueChange={setValue}
    />
  );
}
```

### With Error State

```tsx
import { AppCheckbox } from "laif-ds";
import { useState } from "react";

export function CheckboxWithError() {
  const [value, setValue] = useState<string[]>([]);

  return (
    <AppCheckbox
      label="Terms and Conditions"
      required
      options={[
        { value: "terms", label: "I accept the terms and conditions" },
        { value: "privacy", label: "I accept the privacy policy" },
      ]}
      value={value}
      onValueChange={setValue}
      error={
        value.length === 0 ? "You must accept at least one option" : undefined
      }
    />
  );
}
```

---

## Notes

- **JSX Labels**: Both `label` and option labels support JSX for custom rendering
- **Icon Support**: Uses the Icon component from laif-ds (Feather Icons)
- **Accessibility**: Includes proper ARIA attributes and keyboard navigation
- **Card Styling**: Card layout includes hover effects and focus states
- **Disabled Options**: Individual options can be disabled while keeping others enabled
- **Multiple Selection**: Unlike radio groups, checkboxes allow selecting multiple options