# Radio group

## Overview

_[Design to fill]_

- **When to use**: _[Design to fill]_
- **When not to use**: _[Design to fill]_

## Anatomy

_[Design to fill]_

## Variants

| Prop           | Effect                                                                     |
| -------------- | -------------------------------------------------------------------------- |
| `isHorizontal` | Lays the radio options out in a row instead of the default vertical stack. |
| `isSmall`      | Renders the smaller radios with `text-200` label sizing.                   |

## Props / API

`RadioGroup` is a compound component: the group is composed with `RadioGroup` and one `RadioGroup.Input` per option.

### `RadioGroup`

| Prop           | Type                      | Default | Description                                                      |
| -------------- | ------------------------- | ------- | ---------------------------------------------------------------- |
| `name`         | `string`                  | -       | Shared name applied to every radio input in the group.           |
| `value`        | `string`                  | -       | The currently selected option's value (controlled).              |
| `onChange`     | `(value: string) => void` | -       | Called with the newly selected value when the selection changes. |
| `disabled`     | `boolean`                 | `false` | Disables every radio in the group.                               |
| `isHorizontal` | `boolean`                 | `false` | Lays the options out horizontally.                               |
| `isSmall`      | `boolean`                 | `false` | Renders the smaller size with `text-200` label sizing.           |

Extends `HTMLAttributes<HTMLFieldSetElement>`. Renders a `<fieldset role="radiogroup">`. All standard fieldset attributes are forwarded via `...rest`. `name`, `value`, `onChange`, `disabled`, and `isSmall` are shared with each `RadioGroup.Input` through context.

### `RadioGroup.Input`

| Prop       | Type      | Default | Description                                                        |
| ---------- | --------- | ------- | ------------------------------------------------------------------ |
| `value`    | `string`  | -       | This option's value. Selected when it matches the group's `value`. |
| `disabled` | `boolean` | `false` | Disables this individual option.                                   |

Extends `HTMLAttributes<HTMLLabelElement>`. Renders a `<label>` wrapping a native `<input type="radio">`; `children` become the visible label text. All standard label attributes are forwarded via `...rest`. Must be used within a `RadioGroup` parent.

## States

- Default (idle)
- Hover
- Focus-visible
- Selected (checked)
- Disabled

## Code examples

```tsx
import { useState } from "react";
import { RadioGroup } from "@mylighthouse/prism-react";

export default function RadioGroupExample(): React.JSX.Element {
  const [plan, setPlan] = useState("monthly");

  return (
    <RadioGroup name="plan" value={plan} onChange={setPlan}>
      <RadioGroup.Input value="monthly">Monthly</RadioGroup.Input>
      <RadioGroup.Input value="annual">Annual</RadioGroup.Input>
      <RadioGroup.Input value="lifetime" disabled>
        Lifetime
      </RadioGroup.Input>
    </RadioGroup>
  );
}
```

## A11y intent

_[Design to fill]_

- The group renders a `<fieldset role="radiogroup">`, so options are announced as a single set with a shared purpose.
- Each option is a real native `<input type="radio">`, so selection, arrow-key navigation between options, and focus are handled correctly.
- Each option is wrapped in a `<label>` so its purpose is announced.
- The `disabled` inputs stay in the accessibility tree so their state is announced.

## Cross-references

_[Design to fill]_