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

<Meta of={TextInputStories} />

# TextInput

The single-line field: inset surface, 8px radius, 14px text, a stronger
border on hover, the focus border in every theme.

<Canvas of={TextInputStories.Filled} />

## When

- One line of text in a form or dialog — a name, a title, a URL. Label it
  with a **Field**.
- **`size="small"`** in a dense row beside small **Select**s: 24px tall,
  12px text, the small Select's padding. Default is 38px.

<Canvas of={TextInputStories.BesideSmallSelects} />

## When not

- Several lines → **Textarea**.
- Filtering a list → **SearchInput**.
- Editing text where it is displayed → **EditableText**.

## How

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

<TextInput value={name} onChange={(e) => setName(e.target.value)} placeholder="Untitled" />
```

- It is a native `<input>` with a ref — every native prop passes through.
  Base UI's `Input` since stage 3, which is what finds a surrounding
  `Field`.
- **Inside a `Field`, the label names it. Add nothing.** This page said the
  opposite until stage 3 — "a Field's label is visual, so give the input an
  `aria-label` too" — and that advice was already stale at SHA-17. An
  `aria-label` there is now ignored, because the label wins.
- **Outside a `Field`, name it yourself** with `aria-label`: a placeholder
  is not a name.
- `disabled` gets the disabled surface and text; say why with a tooltip.
- `size` is this component's (`default` or `small`), not the native attribute
  that counts characters. Set a width with the layout around it.

## 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, and its error state | an `id` / `htmlFor` pair, or `aria-invalid` |  |
| Keeps its height in a scrolling column | `shrink-0` |  |

## Props

<Controls of={TextInputStories.Empty} />