import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
import {
  PlaygroundInputText,
  DoWithLabel,
  DoWithPlaceholder,
  DoWithCaption,
  DoWithIconStart,
  DoWithIconEnd,
  DoWithIcons,
  DoDisabled,
  DoLoading,
  DoWithMaxLength,
  DoWithMinMaxLength,
  DontLongLabel,
  DoShortLabel,
  DontNoLabel,
  DontGenericPlaceholder,
  DoSpecificPlaceholder,
  DontTooManyIcons,
  DoOneIcon,
  DontNoErrorFeedback,
  DoWithErrorFeedback,
  DontNoCaption,
  DoWithHelpfulCaption,
} from '../components/form/BmsInputText.stories.js';

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

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

Text fields allow users to input custom text entries with a keyboard. They are essential components for forms and data collection, providing a way for users to enter text, numbers, dates, and other information. Various options can be shown with the field to communicate input requirements and provide feedback.

## Anatomy

Text inputs consist of several key elements: a label that describes what information is needed, an input field where users type, optional icons for visual cues, placeholder text for guidance, captions for additional information, and error messages for validation feedback.

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

## Component

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

<Canvas of={PlaygroundInputText} />

### Props

<Controls of={PlaygroundInputText} />

## Usage Examples

### ✅ Do: Simple input with label

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

<Canvas of={DoWithLabel} />

### ✅ Do: Input with placeholder

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

<Canvas of={DoWithPlaceholder} />

### ✅ Do: Input with caption

Use captions to provide additional context, help text, or format requirements.

<Canvas of={DoWithCaption} />

### ✅ Do: Input with icon at start

Icons at the start can help clarify the type of information expected or provide visual context.

<Canvas of={DoWithIconStart} />

### ✅ Do: Input with icon at end

Icons at the end are useful for actions like clearing the field, showing/hiding passwords, or indicating status.

<Canvas of={DoWithIconEnd} />

### ✅ Do: Input with both icons

Use both icons when you need to provide context at the start and an action at the end.

<Canvas of={DoWithIcons} />

### ✅ Do: Disabled state

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

<Canvas of={DoLoading} />

### ✅ Do: Input with max length

Use maxlength to limit the number of characters. The component will show a warning when the limit is reached.

<Canvas of={DoWithMaxLength} />

### ✅ Do: Input with min and max length

Use both minlength and maxlength to enforce a specific range of characters.

<Canvas of={DoWithMinMaxLength} />

## 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: Overuse of icons

Don't overload inputs with multiple icons that don't add value. Use icons purposefully.

**❌ Don't:**

<Canvas of={DontTooManyIcons} />

**✅ Do:**

<Canvas of={DoOneIcon} />

### ⛔ 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 input requirements are complex, provide captions to help users understand what's expected.

**❌ Don't:**

<Canvas of={DontNoCaption} />

**✅ Do:**

<Canvas of={DoWithHelpfulCaption} />
