import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
import * as SearchInputStories from './SearchInput.stories'

<Meta of={SearchInputStories} />

# SearchInput

An inset field with a hairline border that strengthens on hover and on
focus, and an optional keyboard hint at the right edge.

<Canvas of={SearchInputStories.WithShortcut} />

## When

- Filtering a list, live, above the list it filters.

## When not

- The way into a launcher from the top bar → **TopBar**'s `onSearch`. The
  bar draws this look as a button, 290px, and answers Ctrl+K itself.
- General text entry → **TextInput**.
- Picking entries from a directory → **ChipInput** or **Select**.

## How

```tsx
import { SearchInput } from '@estiva-app/ui'

<SearchInput value={query} onChange={(e) => setQuery(e.target.value)} shortcut="Ctrl+K" />
```

- The default placeholder is "Search…" — override it with your own.
- Every native input prop passes through. The field inside is Base UI's
  `Input` since stage 3; the border, the focus-within rule and the `Kbd`
  hint are this component's.
- **Give it an `aria-label` ("Search")** — the placeholder is not a name,
  and this usually stands alone above its list rather than in a `Field`.
  Inside one, the label names it and you add nothing.

## What it owns

It does these by itself. Write none of them around it.

| It does | So you never write | Refused when written by hand |
|---|---|---|
| Inside a `Field`, takes its name from the Field's label | an `id` / `htmlFor` pair |  |
| Shows its focus ring while anything inside it has focus | a focus style of your own |  |

## Props

<Controls of={SearchInputStories.Default} />