import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
import {
  PlaygroundCheckboxCaptionGroup,
  DoWithClearLabels,
  DoWithHelpfulCaptions,
  DoWithColumnLayout,
  DontNoLabel,
  DoWithLabel,
  DontNoCaptions,
  DoWithErrorFeedback,
} from '../components/form/BmsInputCheckboxCaptionGroup.stories.js';

<Meta title="Documentation/Fields/Checkbox Caption Group" />

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

A checkbox caption group consists of a set of interconnected checkboxes where each option can have its own caption. This allows you to provide specific information or descriptions for each individual choice. Checkbox caption groups are ideal when each option needs its own contextual information, such as pricing details, feature descriptions, or specific instructions for each choice. Unlike radio groups, checkboxes allow users to select multiple options.

## Anatomy

Checkbox caption groups consist of a label that describes the overall choice, multiple checkbox options, and individual captions under each option that provide specific information about that choice. The group can be displayed in a row or column layout.

## Component

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

<Canvas of={PlaygroundCheckboxCaptionGroup} />

### Props

<Controls of={PlaygroundCheckboxCaptionGroup} />

## Usage Examples

### ✅ Do: Checkbox caption group with clear labels

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

<Canvas of={DoWithClearLabels} />

### ✅ Do: Checkbox caption group with helpful captions

Use captions to provide specific information for each option, such as pricing, features, or additional context that helps users make an informed decision.

<Canvas of={DoWithHelpfulCaptions} />

### ✅ Do: Checkbox caption group in column layout

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

<Canvas of={DoWithColumnLayout} />

### ✅ Do: Checkbox caption 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 choices are expected.

**❌ Don't:**

<Canvas of={DontNoLabel} />

**✅ Do:**

<Canvas of={DoWithLabel} />

### ⛔ Don't: No captions when needed

When each option has specific information that users need to know (pricing, features, descriptions), provide captions for each option. Without captions, users may not have enough information to make an informed choice.

**❌ Don't:**

<Canvas of={DontNoCaptions} />

**✅ Do:**

<Canvas of={DoWithHelpfulCaptions} />

## When to use Checkbox Caption Group vs Checkbox Group

**Use Checkbox 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

**Use Checkbox 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

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