import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
import {
  PlaygroundRadioGroup,
  DoWithClearLabels,
  DoWithCaption,
  DoWithColumnLayout,
  DontNoLabel,
  DoWithLabel,
  DontNoErrorFeedback,
  DoWithErrorFeedback,
} from '../components/form/BmsInputRadioGroup.stories.js';

<Meta title="Documentation/Fields/Radio Group" />

# <img src="./BmsIcon.png" /> Radio Group

A radio group consists of a set of interconnected radio buttons with a single caption that applies to all options. Radio groups are ideal when all options share the same context or when you need to provide general information that applies to the entire group rather than individual options.

## Anatomy

Radio groups consist of a label that describes the overall choice, multiple radio button options, and a single caption that provides information applicable to all options. The group can be displayed in a row or column layout.

![Radio Group representation](./fields/RadioGroupRepresentation.png)

## Component

Use the controls below to interact with the component and see how it behaves with different configurations.

<Canvas of={PlaygroundRadioGroup} />

### Props

<Controls of={PlaygroundRadioGroup} />

## Usage Examples

### ✅ Do: Radio group with clear labels

Always provide clear, descriptive labels for each option that explain what the choice represents.

<Canvas of={DoWithClearLabels} />

### ✅ Do: Radio group with caption

Use a caption to provide general information that applies to all options, such as instructions, requirements, or context that helps users understand the choice.

<Canvas of={DoWithCaption} />

### ✅ Do: Radio group in column layout

Use the column layout when you have longer option labels, or when you want to display options vertically for better readability or when space is limited horizontally.

<Canvas of={DoWithColumnLayout} />

### ✅ Do: Radio group with error feedback

Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix it.

<Canvas of={DoWithErrorFeedback} />

## Rules

### ⛔ Don't: Missing labels

Always provide a label for accessibility and clarity. Labels help screen readers and provide context about what choice is expected.

**❌ Don't:**

<Canvas of={DontNoLabel} />

**✅ Do:**

<Canvas of={DoWithLabel} />

### ⛔ Don't: No error feedback

Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix it.

**❌ Don't:**

<Canvas of={DontNoErrorFeedback} />

**✅ Do:**

<Canvas of={DoWithErrorFeedback} />

## When to use Radio Group vs Radio Caption Group

**Use Radio Group** when:

- All options share the same context or information
- You only need a single caption that applies to all options
- Options are simple and self-explanatory without individual descriptions

**Use Radio Caption Group** when:

- Each option needs its own specific information or description
- You need to display different details for each choice (e.g., pricing, features, delivery times)
- Options have distinct characteristics that require individual explanation

The key difference is that Radio Group provides **one caption for the entire group**, while Radio Caption Group allows you to provide **individual captions for each option**.
