import { Canvas, Meta, Controls } from '@storybook/addon-docs/blocks';
import {
  PlaygroundSearch,
  DoWithClearPlaceholder,
  DoWithValue,
  DoDisabled,
  DontGenericPlaceholder,
  DoSpecificPlaceholder,
  DontNoErrorFeedback,
  DoWithErrorFeedback,
  DontNoPlaceholder,
} from '../components/form/BmsSearch.stories.js';

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

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

Search components allow users to enter text to perform a search among the data, content, or elements present in the interface they are viewing or the system. They provide a dedicated input field with a search icon, making it easy for users to find and filter information. Search components are essential for interfaces with large amounts of data or content that needs to be discoverable.

![Search representation](./fields/CoverSearch.png)

## Anatomy

Search components consist of several key elements: a search icon at the start to indicate the field's purpose, an input field where users type their search query, a clear button that appears when there is text to allow users to quickly reset the search, and placeholder text to guide users on what to search for.

![Search representation](./fields/InputSearchRepresentation.png)

## Component

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

<Canvas of={PlaygroundSearch} />

### Props

<Controls of={PlaygroundSearch} />

## Usage Examples

### ✅ Do: Search with clear placeholder

Always provide a clear, descriptive placeholder that explains what users can search for. This helps users understand the scope of the search.

<Canvas of={DoWithClearPlaceholder} />

### ✅ Do: Search with value and clear button

When users type a search query, a clear button appears automatically, allowing them to quickly reset the search. This improves the user experience.

<Canvas of={DoWithValue} />

### ✅ Do: Disabled state

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

<Canvas of={DoDisabled} />

### ✅ Do: Search with error feedback

Always provide clear error messages when validation fails. Help users understand what went wrong and how to fix their search query.

<Canvas of={DoWithErrorFeedback} />

## Rules

### ⛔ Don't: Generic placeholder

Avoid generic placeholders like "Type here" or "Enter text". Use specific examples that guide users on what they can search for.

**❌ Don't:**

<Canvas of={DontGenericPlaceholder} />

**✅ Do:**

<Canvas of={DoSpecificPlaceholder} />

### ⛔ Don't: No error feedback

Always provide clear error messages when search validation fails. Help users understand what went wrong and how to fix their search query.

**❌ Don't:**

<Canvas of={DontNoErrorFeedback} />

**✅ Do:**

<Canvas of={DoWithErrorFeedback} />

### ⛔ Don't: Search without placeholder

Always provide a placeholder to guide users on what they can search for. By default we offer "Rechercher...".

**❌ Don't:**

<Canvas of={DontNoPlaceholder} />

**✅ Do:**

<Canvas of={DoWithClearPlaceholder} />
