import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
import {
  PlaygroundSelect,
  DoWithLabel,
  DoWithPlaceholder,
  DoWithCaption,
  DoDisabled,
  DoLoading,
  DontLongLabel,
  DoShortLabel,
  DontNoLabel,
  DontGenericPlaceholder,
  DoSpecificPlaceholder,
  DontNoErrorFeedback,
  DoWithErrorFeedback,
  DontNoCaption,
  DoWithHelpfulCaption,
} from '../components/form/BmsSelect.stories.js';

<Meta title="Documentation/Fields/Select" />

# <img src="./BmsIcon.png" /> Select

Selects (or "dropdowns") enable users to select from a list of options within a confined area. They are essential components for forms that require users to choose from predefined options, providing a way to select single values from a list. The available options within the list may vary depending on the context. Various options can be shown with the field to communicate selection requirements and provide feedback.

## Anatomy

Select components consist of several key elements: a label that describes what information is needed, a select field that displays the selected value or placeholder, a dropdown icon to indicate it's a selectable field, placeholder text for guidance, captions for additional information, and error messages for validation feedback.

![](./fields/SelectRepresentation.png)

## Component

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

<Canvas of={PlaygroundSelect} />

### Props

<Controls of={PlaygroundSelect} />

## Usage Examples

### ✅ Do: Simple select with label

Always provide a clear, descriptive label that explains what information is expected.

<Canvas of={DoWithLabel} />

### ✅ Do: Select with placeholder

Use placeholders to provide examples or guidance on what to select. Placeholders help users understand what action is expected.

<Canvas of={DoWithPlaceholder} />

### ✅ Do: Select with caption

Use captions to provide additional context, help text, or important information about the selection.

<Canvas of={DoWithCaption} />

### ✅ Do: Disabled state

Use the disabled state when the select should not be editable, but the value should still be visible.

<Canvas of={DoDisabled} />

### ✅ Do: Loading state

Use the loading state to indicate that the select is processing data or waiting for options to load.

<Canvas of={DoLoading} />

### ✅ Do: Select 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: Long labels

Avoid overly long labels that make the form difficult to scan. Keep labels concise and clear.

**❌ Don't:**

<Canvas of={DontLongLabel} />

**✅ Do:**

<Canvas of={DoShortLabel} />

### ⛔ Don't: Missing labels

Always provide a label for accessibility and clarity. Labels help screen readers and provide context.

**❌ Don't:**

<Canvas of={DontNoLabel} />

**✅ Do:**

<Canvas of={DoWithLabel} />

### ⛔ Don't: Generic placeholders

Avoid generic placeholders like "Select" or "Choose". Use specific examples that guide the user.

**❌ Don't:**

<Canvas of={DontGenericPlaceholder} />

**✅ Do:**

<Canvas of={DoSpecificPlaceholder} />

### ⛔ 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} />

### ⛔ Don't: Missing helpful captions

When selection requirements are complex, provide captions to help users understand what's expected.

**❌ Don't:**

<Canvas of={DontNoCaption} />

**✅ Do:**

<Canvas of={DoWithHelpfulCaption} />

### ⚠️ Note: When to use Radio instead of Select

For a small number of options (especially 2 options), consider using the Radio component instead of Select. Radio buttons provide better visibility of all available options and require fewer interactions from users. Selects are better suited for longer lists of options (typically 5 or more) or when space is limited.

**❌ Don't: Use Select with only 2 options**

When you have only 2 options, a Select dropdown adds unnecessary complexity. Users have to click to see options that could be immediately visible.

**✅ Do: Use Radio for 2-3 options**

For binary choices or a small number of options, Radio buttons allow users to see all options at once and make a selection with a single click.
