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

<Meta title="Documentation/Fields/Text Area" />

# <img src="./BmsIcon.png" /> Text Area

Text area allows users to input and edit multiple lines of text such as paragraphs, comments, or descriptions. They are essential components for forms that require longer text entries, providing a way for users to enter detailed information, feedback, or multi-line content. Various options can be shown with the field to communicate input requirements and provide feedback.

## Anatomy

Text areas consist of several key elements: a label that describes what information is needed, a textarea field where users type multiple lines of text, placeholder text for guidance, captions for additional information, and error messages for validation feedback.

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

## Component

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

<Canvas of={PlaygroundTextArea} />

### Props

<Controls of={PlaygroundTextArea} />

## Usage Examples

### ✅ Do: Simple textarea with label

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

<Canvas of={DoWithLabel} />

### ✅ Do: Textarea with placeholder

Use placeholders to provide examples or format hints. Placeholders disappear when the user starts typing.

<Canvas of={DoWithPlaceholder} />

### ✅ Do: Textarea with caption

Use captions to provide additional context, help text, or format requirements such as character limits.

<Canvas of={DoWithCaption} />

### ✅ Do: Disabled state

Use the disabled state when the textarea 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 textarea is processing data or waiting for a response.

<Canvas of={DoLoading} />

### ✅ Do: Textarea 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 "Enter text" or "Type here". 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 textarea requirements are complex, provide captions to help users understand what's expected.

**❌ Don't:**

<Canvas of={DontNoCaption} />

**✅ Do:**

<Canvas of={DoWithHelpfulCaption} />
