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

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

# AppRadioGroup

## Overview

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

---

## Types

### AppRadioGroupOption

```ts
export interface AppRadioGroupOption {
  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`         | `AppRadioGroupOption[]`          | **required** | Array of radio options                         |
| `value`           | `string`                         | `undefined`  | Controlled value                               |
| `defaultValue`    | `string`                         | `undefined`  | Uncontrolled default value                     |
| `onValueChange`   | `(value: string) => void`        | `undefined`  | Callback when value changes                    |
| `label`           | `string \| React.ReactNode`      | `undefined`  | Label for the radio 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                             |
| `loop`            | `boolean`                        | `true`       | Enable keyboard navigation looping             |
| `className`       | `string`                         | `""`         | Additional classes for radio 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
- **Keyboard Navigation**: Full keyboard support with arrow keys and looping
- **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 { AppRadioGroup } from "laif-ds";
import { useState } from "react";

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

  return (
    <AppRadioGroup
      label="Choose an option"
      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 { AppRadioGroup } from "laif-ds";
import { useState } from "react";

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

  return (
    <AppRadioGroup
      label="Notification Method"
      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 { AppRadioGroup } from "laif-ds";
import { useState } from "react";

export function CardRadioGroup() {
  const [value, setValue] = useState("basic");

  return (
    <AppRadioGroup
      label="Choose a plan"
      layout="card"
      options={[
        {
          value: "basic",
          label: "Basic",
          description: "$9/month - Essential features",
          icon: "Package",
        },
        {
          value: "pro",
          label: "Pro",
          description: "$29/month - Advanced features",
          icon: "Zap",
        },
        {
          value: "enterprise",
          label: "Enterprise",
          description: "Custom pricing - All features",
          icon: "Building",
        },
      ]}
      value={value}
      onValueChange={setValue}
    />
  );
}
```

### Horizontal Orientation

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

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

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

### With Error State

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

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

  return (
    <AppRadioGroup
      label="Choose an option"
      required
      options={[
        { value: "option1", label: "Option 1" },
        { value: "option2", label: "Option 2" },
      ]}
      value={value}
      onValueChange={setValue}
      error={!value ? "Please select an 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