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

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

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

A checkbox group consists of a set of interconnected checkboxes with a single caption that applies to all options. Checkbox 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. Unlike radio groups, checkboxes allow users to select multiple options.

## Anatomy

Checkbox groups consist of a label that describes the overall choice, multiple checkbox options, and a single caption that provides information applicable to all options. 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={PlaygroundCheckboxGroup} />

### Props

<Controls of={PlaygroundCheckboxGroup} />

## Usage Examples

### ✅ Do: Checkbox group with clear labels

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

<Canvas of={DoWithClearLabels} />

### ✅ Do: Checkbox 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: Checkbox 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: Checkbox 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 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 Checkbox Group vs Checkbox Caption Group

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

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

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