prime-ui-kit 0.7.13 → 0.9.0

package/src/components/input/COMPONENT.md

@@ -1,140 +1,250 @@
 # Input
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
+**Category:** inputs
 
-## Canonical
+> Single-line text field with label, hint, error and slots for icons, affixes, a badge, a clear button and a counter.
 
-- **Назначение:** однострочное поле с опциональной подписью, обводкой вокруг нативного `input`, слотами для иконок и аффиксов; подсказка и ошибка снизу через **Hint**.
-- **Скелет:** `Input.Root` → `Input.Wrapper` → `Input.Field` (плюс при необходимости `Input.Icon` / `Input.Affix` / `Input.InlineAffix` в нужном порядке внутри обёртки).
-- **Размер:** только на **`Input.Root`**: `size` ∈ `s | m | l | xl`, по умолчанию **`m`**. На **`Input.Field`** атрибут HTML **`size` не передаётся** (зарезервирован системой).
-- **Состояние ввода:** контролируемый режим — `value` / `onChange` на **`Input.Field`**. Подпись, `hint`, `error`, `optionalLabel` — на **`Input.Root`**.
-- **Playground** (`playground/snippets/input/`, порядок как в `playground/sections/InputSection.tsx`): [sizes](../../../playground/snippets/input/sizes.tsx) — ряд `size` `s`–`xl` с иконкой; [states](../../../playground/snippets/input/states.tsx) — `hint`, `disabled`, `readOnly`, `required`, `error`; [controlled](../../../playground/snippets/input/controlled.tsx) — `value`/`onChange` на `Input.Field` и `aria-label`; [composition](../../../playground/snippets/input/composition.tsx) — `Icon`, `Affix`, `InlineAffix`; [full-width](../../../playground/snippets/input/full-width.tsx) — узкая колонка и блок на всю ширину (стили [full-width.module.css](../../../playground/snippets/input/full-width.module.css)); [features](../../../playground/snippets/input/features.tsx) — явный `id`, `optionalLabel`, одновременно `hint` и `error`.
-- **Примеры пакета** (`examples/`): [login email](./examples/login-email.tsx), [search](./examples/search.tsx), [password + hint](./examples/password-with-hint.tsx), [checkout full-width](./examples/checkout-full-width.tsx), [affix URL и сумма](./examples/affix-url-and-amount.tsx).
+## When to use
+- Any single-line value: name, e-mail, phone, search query, amount, URL, code.
+- Search fields with a leading icon and a clear button.
+- Values with a fixed prefix/suffix (`https://`, domain, `₽`, `%`).
+- As the reference field: Select, Datepicker, TagSelect and Textarea follow the same label / field / support-row contract.
+
+## When not to use
+- Multi-line text → use [Textarea](../textarea/COMPONENT.md).
+- One-time codes split into cells → use [DigitInput](../digit-input/COMPONENT.md).
+- Choosing from a fixed list → use [Select](../select/COMPONENT.md) or [TagSelect](../tag-select/COMPONENT.md).
+- Dates → use [Datepicker](../datepicker/COMPONENT.md).
+- A standalone label or message without an Input field → use [Label](../label/COMPONENT.md) / [Hint](../hint/COMPONENT.md).
+- Global search across the app in a dialog → use [CommandMenu](../command-menu/COMPONENT.md).
+
+## Import
+```tsx
+import { Input } from "prime-ui-kit";
+```
+
+## Anatomy
+```
+Input.Root            label row, field body, support row; provides size / invalid / ids
+└─ Input.Wrapper      the visible field (fill, hover, focus ring, invalid ring)
+   ├─ Input.Affix          tinted section flush with the edge (start | end)
+   ├─ Input.Icon           decorative icon (start | end)
+   ├─ Input.InlineAffix    muted text next to the value (start | end)
+   ├─ Input.Field          native <input>
+   ├─ Input.Badge          soft palette badge at the trailing edge
+   └─ Input.ClearButton    trailing clear action
+Input.Counter         goes into Input.Root `counter` (support row, right side)
+```
+The trailing side has a fixed CSS `order`, independent of JSX order: value · end inline affix · badge · end icon · clear button · end affix. All `side="start"` slots share one order before the value, so among them the JSX order decides — write them as affix, icon, inline affix.
+
+## API
+
+### Input.Root
+No ref (renders a `<div>`). Does not forward native props.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `"m"` | Tier for height, padding, radius, text, label and hint. Also provided to nested controls via the control-size context. |
+| `invalid` | `boolean` | `false` | Danger inset ring on the field, `aria-invalid` on the input. A non-empty `error` implies it. |
+| `focusRing` | `boolean` | `true` | `false` hides only the visual focus ring on `Input.Wrapper` (`data-focus-ring="false"`); focus, keyboard, ARIA and the invalid ring stay. |
+| `label` | `ReactNode` | — | Label above the field, rendered as `<label htmlFor>`. Without it, give `Input.Field` an `aria-label`. |
+| `required` | `boolean` | `false` | Red `*` after the label (`aria-hidden`) and native `required` on `Input.Field`. |
+| `optional` | `boolean` | `false` | Muted marker right after the label text (`labels.optional`). |
+| `hint` | `ReactNode` | — | Help text under the field. Hidden while `error` is shown. |
+| `error` | `ReactNode` | — | Error message in the hint slot; implies `invalid`. |
+| `counter` | `ReactNode` | — | Right side of the support row, usually `<Input.Counter />`. |
+| `reserveSupportRow` | `boolean` | `false` | Always render the support row (min height = hint line height), so an appearing error does not shift the layout. |
+| `id` | `string` | auto (`useId`) | Id of the `<input>`; hint id is `${id}-hint`, error id is `${id}-error`. |
+| `labels` | `Partial<InputLabels>` | see Accessibility | Built-in strings. |
+| `children` | `ReactNode` | — (required) | Usually `Input.Wrapper`. |
+| `className` | `string` | — | Class on the root `<div>`. |
+
+### Input.Wrapper
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | Field and slots. |
+| `className` | `string` | — | Class on the field `<div>`. |
+
+### Input.Field
+`forwardRef` to `HTMLInputElement`. + native `<input>` props except `size` (`value`, `defaultValue`, `onChange`, `type`, `disabled`, `readOnly`, `maxLength`, `placeholder`, …).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onValueChange` | `(value: string) => void` | — | Called with the new string; native `onChange` still fires first. |
+| `aria-describedby` | `string` | — | Merged with the hint/error ids from the root. |
+| `required` | `boolean` | from `Input.Root` | Explicit value overrides the root's `required`. |
+
+`id`, `aria-invalid` and `aria-describedby` are set from the root context.
+
+### Input.Icon
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `side` | `"start" \| "end"` | — (required) | Side of the value. |
+| `children` | `ReactNode` | — (required) | An icon; kit icons without an explicit `size` take the field tier. |
+| `className` | `string` | — | Class on the `<span>` (`aria-hidden`). |
+
+### Input.Affix
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `side` | `"start" \| "end"` | — (required) | Section sits flush with that edge; the wrapper drops its padding there. |
+| `children` | `ReactNode` | — (required) | Static text: protocol, domain, country code. |
+| `className` | `string` | — | Class on the `<div>` (`aria-hidden`). |
+
+### Input.InlineAffix
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `side` | `"start" \| "end"` | — (required) | Side of the value. |
+| `children` | `ReactNode` | — (required) | Short unit: `₽`, `%`, `кг`. |
+| `className` | `string` | — | Class on the `<span>` (`aria-hidden`). |
+
+### Input.Badge
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `color` | `"gray" \| "blue" \| "green" \| "orange" \| "red" \| "yellow" \| "purple" \| "sky" \| "pink" \| "teal"` | `"gray"` | Palette hue of the soft badge. |
+| `children` | `ReactNode` | — (required) | Short status text. |
+| `className` | `string` | — | Class on the badge. |
+
+### Input.ClearButton
+`forwardRef` to `HTMLButtonElement`. + native `<button>` props except `type`, `children`, `aria-label`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onClick` | `MouseEventHandler<HTMLButtonElement>` | — | Clear the value here. Afterwards focus returns to the input unless `event.preventDefault()` was called. |
+
+Renders `type="button"`, `aria-label={labels.clear}`, `aria-controls` = input id, close icon. Render it only when the field has a value.
+
+### Input.Counter
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `current` | `number` | — (required) | Current length. |
+| `max` | `number` | — (required) | Limit; `current > max` turns the counter danger (`data-invalid="true"`). |
+| `className` | `string` | — | Class on the `<span>`. |
+
+## Variants
+Input has no `variant` or `tone`: there is one field treatment (fill, no visible border).
+
+### size (Input.Root)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `xs` | 28 high, text 12/16, padX 8, radius 6, label 12/16, hint 12/16 | Dense table toolbars, inline filters | |
+| `s` | 32 high, text 13/20, padX 8, radius 8, label 12/16, hint 12/16 | Compact panels, side filters | |
+| `m` | 36 high, text 14/20, padX 12, radius 8, label 13/20, hint 12/16 | Regular forms and pages | yes |
+| `l` | 40 high, text 16/24, padX 12, radius 10, label 14/20, hint 13/20 | Spacious forms, onboarding | |
+| `xl` | 48 high, text 16/24, padX 16, radius 12, label 14/20, hint 13/20 | Hero search, landing forms | |
+
+**Sizes:** a field of size T lines up with Button, Select, Datepicker trigger, SegmentedControl and Tabs of size T in one row (same height and radius) — see [control-alignment.tsx](examples/control-alignment.tsx). Label and hint always use the same tier as the field.
+
+### side (Input.Icon / Input.Affix / Input.InlineAffix)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `start` | Before the value. Icon: muted, centered between edge and text (edge → icon = icon → text = field padX). Affix: tinted `fill-subtle` section flush with the edge. Inline affix: muted text before the value | Search icon, `https://`, currency sign before the number | — (required) |
+| `end` | After the value. Same treatments at the trailing side; numeric fields with an end inline affix align the value to the end | Lock icon on read-only, domain suffix, units `₽ % кг` | — |
+
+### color (Input.Badge)
+| Value | Looks like | Use when | Default |
+|---|---|---|---|
+| `gray` | Soft badge on a stronger neutral wash (`fill-strong`) so it stays visible on the field fill | Neutral status ("Черновик") | yes |
+| `blue` | Soft blue badge | "Новое", informational marks | |
+| `green` | Soft green badge | "Проверен", verified values | |
+| `orange` | Soft orange badge | "Не заполнено", needs attention | |
+| `red` | Soft red badge | Rejected or blocked value | |
+| `yellow` | Soft yellow badge | Pending | |
+| `purple` | Soft purple badge | Category marks | |
+| `sky` | Soft sky badge | Category marks | |
+| `pink` | Soft pink badge | Category marks | |
+| `teal` | Soft teal badge | Category marks | |
+
+### Visual flags
+| Flag | Looks like | Use when | Default |
+|---|---|---|---|
+| `focusRing={false}` | No focus ring; the field still switches to the focus fill, caret visible | A single search field where focus is obvious | `true` |
+| `reserveSupportRow` | Empty support row of hint height under the field | Fields validated on the fly; neighbouring fields in one grid row | `false` |
+| `required` / `optional` | Red `*` / muted «необязательно» after the label | Mark the minority: required when most are optional, optional when most are required | `false` |
+
+**Combinations**
+- Recommended: `Input.Icon side="start"` + `Input.ClearButton` for search; `Input.Affix` on both sides for URLs; `Input.InlineAffix side="end"` with `inputMode="decimal"` for amounts.
+- Allowed but rare: `Input.Badge` together with an end icon (badge sits before the icon).
+- Pointless: `required` and `optional` together; `hint` and `error` together (the error replaces the hint); `invalid` without any message in a form where the user needs to know what is wrong.
+- Forbidden: `focusRing={false}` on regular form fields (WCAG 2.4.7).
+
+**Hierarchy:** keep one size for all fields of a form; mark required/optional consistently; use the badge only for a status of the value, not for decoration.
+
+## States
+| State | Driven by | DOM |
+|---|---|---|
+| default / hover | — | hover darkens the fill (not when disabled, read-only or focused) |
+| focus | keyboard focus on the input | wrapper gets the focus fill and an inset focus ring (`:has(input:focus-visible)`) |
+| no focus ring | `focusRing={false}` | `data-focus-ring="false"` on the wrapper |
+| invalid | `invalid` or non-empty `error` | `data-invalid="true"` on root and wrapper, `aria-invalid="true"` on the input, danger inset ring, danger focus ring |
+| disabled | native `disabled` on `Input.Field` | disabled fill, disabled text and icons, `cursor: not-allowed`, clear button disabled look |
+| read-only | native `readOnly` on `Input.Field` | no hover, default cursor |
+| reserved support row | `reserveSupportRow` | `data-reserve="true"` on the support row |
+| counter over limit | `current > max` | `data-invalid="true"` on `Input.Counter` |
+
+Size: `data-size` on root and wrapper. Slots: `data-side="start" | "end"`.
+
+Controlled: `value` + `onChange` (or `onValueChange`) on `Input.Field`. Uncontrolled: `defaultValue`. Both are native input props.
+
+## Layout & spacing
+- Label → field gap: tier `label-gap` (`--prime-space-1` on xs/s, `--prime-space-2` on m–xl). Field → support row: `--prime-space-1`.
+- Field → field in a form: `--prime-space-5` (20); group → actions: `--prime-space-8` (32).
+- `Input.Root` is `width: 100%` and `min-width: 0`; there is no `fullWidth` prop — the width comes from the parent (grid column, flex item, capped wrapper).
+- Use `reserveSupportRow` on fields that share a grid row so their bottoms stay aligned when only one shows an error.
+- The value truncates with an ellipsis before badges, icons and affixes; the field height never changes.
+
+## Accessibility
+- `label` renders a `<label htmlFor>` bound to the input. Without `label`, set `aria-label` on `Input.Field`. A placeholder never replaces the label.
+- Hint and error are linked through `aria-describedby`; the error replaces the hint.
+- `Input.Icon`, `Input.Affix`, `Input.InlineAffix` are `aria-hidden`: put the meaning in the label (e.g. "Сумма, ₽").
+- `Input.ClearButton` is a real button with an accessible name, `aria-controls` the input, and returns focus to the input.
+- `Input.Counter` shows `14/40` visually and announces `labels.counter` through `aria-live="polite"`.
+
+| `labels` key | Default | Used for |
+|---|---|---|
+| `optional` | `"необязательно"` | Marker after the label when `optional` |
+| `clear` | `"Очистить"` | Accessible name of `Input.ClearButton` |
+| `counter` | `"{current} из {max} символов"` | Screen-reader text of `Input.Counter`; `{current}` and `{max}` are replaced |
+
+## Examples
+| File | Scenario | When to use this pattern |
+|---|---|---|
+| [anatomy.tsx](examples/anatomy.tsx) | Label, `*`, optional, placeholder, hint, error and counter on every size | Reference for assembling a field |
+| [control-alignment.tsx](examples/control-alignment.tsx) | Input, Select, Datepicker and Button of the same size in one row | Filter bars, toolbars |
+| [sizes.tsx](examples/sizes.tsx) | The same field on `xs`…`xl` | Picking a size |
+| [states.tsx](examples/states.tsx) | Empty, filled, disabled, read-only, error with text, `invalid` only | Checking all states |
+| [surfaces.tsx](examples/surfaces.tsx) | A plain field whose fill follows the surface | Fields on canvas vs inside cards/overlays |
+| [controlled.tsx](examples/controlled.tsx) | Controlled value, `Input.ClearButton`, `Input.Counter` with an error over the limit | Search and length-limited text |
+| [search-without-focus-ring.tsx](examples/search-without-focus-ring.tsx) | `focusRing={false}` search field | A single search field where focus is obvious |
+| [icons-and-affixes.tsx](examples/icons-and-affixes.tsx) | `Input.Icon`, `Input.Affix` on both sides, `Input.InlineAffix` | E-mail, URL, amount fields |
+| [with-badge.tsx](examples/with-badge.tsx) | `Input.Badge`, `Select.Badge`, `Datepicker.Badge` with palette colors | Marking a value as verified / new / missing |
+| [in-form.tsx](examples/in-form.tsx) | Company details form with required, optional, error and actions | Form spacing reference |
+| [reserved-support-row.tsx](examples/reserved-support-row.tsx) | Toggling an error with `reserveSupportRow`, custom `labels.optional`, explicit `id` | Live validation without layout shift |
+| [full-width.tsx](examples/full-width.tsx) | Capped vs full-width parent | Controlling field width from the layout |
 
 ```tsx
 import { Input } from "prime-ui-kit";
 
-export function Example() {
+export function EmailField() {
   return (
-    <Input.Root label="Поле">
+    <Input.Root label="Email" required hint="Пришлём ссылку для входа">
       <Input.Wrapper>
-        <Input.Field placeholder="Значение" />
+        <Input.Field type="email" placeholder="name@company.ru" />
       </Input.Wrapper>
     </Input.Root>
   );
 }
 ```
 
-## Extended
-
-### About
-
-A composite single-line text field: optional label row outside the control, a bordered wrapper around the native `input`, and optional icons or text affixes inside the row. Hint and error text render below via the shared Hint primitive.
-
-**When to use**
-
-- Single-line text, email, password, search, tel, number, and other native `input` types in forms, filters, and settings.
-- Fields that need a built-in label, optional secondary header text, hint, or error line tied to the input id.
-- Dense layouts where `Input.Icon`, `Input.Affix`, or `Input.InlineAffix` clarify format (URL prefix, currency, search glyph) without extra wrappers.
-
-**When not to use**
-
-- Multiline or auto-growing text — use [Textarea](../textarea/COMPONENT.md).
-- Fixed-length codes split into cells or heavy masking — use [DigitInput](../digit-input/COMPONENT.md) or app-level logic.
-- When the label must be fully decoupled from the field chrome — consider [Label](../label/COMPONENT.md) plus a minimal field pattern instead of `label` on Root.
-
-### Composition
-
-- **`Input.Root`** — outer `div` with `data-size`, context provider, and `ControlSizeProvider`. Optional header: `label` (`htmlFor` → input id) and `optionalLabel`. Children (usually **`Input.Wrapper`**) sit between header and meta. If `hint` or `error` is set, a meta block renders **`Hint.Root`** rows for each.
-- **`Input.Wrapper`** — flex row with field border and background; `data-size` and `data-has-error` come from context. Place **`Input.Field`**, **`Input.Icon`**, **`Input.Affix`**, and **`Input.InlineAffix`** inside in the order your layout needs.
-- **`Input.Field`** — the actual `<input>`; receives `id`, merged `aria-describedby`, and `aria-invalid` from context.
-- **`Input` namespace** — `Root`, `Wrapper`, `Field`, `Icon`, `Affix`, `InlineAffix`. **`useInputContext`** is exported for custom inner pieces that must align with the same size and ids.
-
-### Rules
-
-- Use **`Input.Root`** `size` for control sizing; **`Input.Field`** omits the HTML `size` attribute (it is stripped from props) — do not rely on passing `size` to the native input.
-- Passing **`error`** on Root sets **`hasError`** internally for visuals and `aria-invalid`; you may set **`hasError`** alone for validation without message text.
-- Controlled usage: pass **`value`** / **`onChange`** (and related) on **`Input.Field`**. Uncontrolled: omit **`value`** and optionally use **`defaultValue`**.
-- Prefer Root **`label`** for the common case; if there is no visible label, set **`aria-label`** or **`aria-labelledby`** on **`Input.Field`**.
-- **`Input.Icon`**, **`Input.Affix`**, and **`Input.InlineAffix`** are **`aria-hidden`**; do not rely on them for the accessible name. You may append ids to **`aria-describedby`** on **`Input.Field`**; values merge with hint/error ids from context.
-- Set **`id`** on Root when you need a stable input id (e.g. tests or external `htmlFor`). Otherwise an id is generated in **`useFieldIds`**.
-- There is no separate **`variant`** prop: visual error state comes from **`error`** / **`hasError`**. Behavioral differences use native attributes on **`Input.Field`** (`type`, `autoComplete`, `inputMode`, `pattern`, `maxLength`, `disabled`, `readOnly`, **`required`**, etc.).
-- **Full width:** root already uses **`width: 100%`** and **`min-width: 0`**. To fill a card or form column, place **`Input.Root`** inside a parent that spans the desired width (see **`examples/checkout-full-width.tsx`**).
-
-### API
-
-#### Input.Root
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| size | `"s" \| "m" \| "l" \| "xl"` | `"m"` | no | Control size from `--prime-sys-size-control-*` tokens. |
-| hasError | `boolean` | `false` | no | Invalid state: propagates to wrapper and `aria-invalid` on the field; if `error` is set, treated as true. |
-| label | `React.ReactNode` | — | no | Label; rendered as `<label htmlFor={inputId}>`. |
-| optionalLabel | `React.ReactNode` | — | no | Secondary text in the header row. |
-| hint | `React.ReactNode` | — | no | Hint below the field. |
-| error | `React.ReactNode` | — | no | Error message; implies error styling and `hasError` behavior. |
-| id | `string` | — | no | Explicit input id; otherwise generated via `useFieldIds`. |
-| children | `React.ReactNode` | — | yes | Field body (typically `Input.Wrapper` with content). |
-| className | `string` | — | no | Class on the root element. |
-
-#### Input.Wrapper
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| children | `React.ReactNode` | — | yes | Content inside the field border. |
-| className | `string` | — | no | Extra class; `data-size` and `data-has-error` come from context. |
-
-#### Input.Field
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| className | `string` | — | no | Class on the `input`. |
-| aria-describedby | `string` | — | no | Appended to the id list from context (hint/error). |
-| …rest | `Omit<React.InputHTMLAttributes<HTMLInputElement>, "size">` | — | no | Standard `input` attributes except `size` (reserved for the design system). |
-
-#### Input.Icon
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| side | `"start" \| "end"` | — | yes | Icon position inside the wrapper. |
-| children | `React.ReactNode` | — | yes | Usually an icon component from the kit. |
-| className | `string` | — | no | Class on the wrapping `span`. |
-
-#### Input.Affix
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| side | `"start" \| "end"` | — | yes | Side of the block affix. |
-| children | `React.ReactNode` | — | yes | Static text segment (e.g. URL prefix). |
-| className | `string` | — | no | Class on the container. |
-
-#### Input.InlineAffix
-
-| Prop | Type | Default | Required | Description |
-|------|------|---------|----------|-------------|
-| side | `"start" \| "end"` | — | yes | Side of the inline affix. |
-| children | `React.ReactNode` | — | yes | Short text (e.g. currency symbol). |
-| className | `string` | — | no | Class on the `span`. |
-
-#### useInputContext()
-
-Returns `{ size, hasError, inputId, describedBy }` for building custom subcomponents that stay consistent with **`Input.Field`**.
-
-### Related
-
-- [Label](../label/COMPONENT.md)
-- [Hint](../hint/COMPONENT.md)
-- [Textarea](../textarea/COMPONENT.md)
-- [Button](../button/COMPONENT.md)
-- [DigitInput](../digit-input/COMPONENT.md)
-
-## LLM note
-
-- **Обязательная иерархия:** `Input.Root` → `Input.Wrapper` → `Input.Field`. Не подменять разметку кастомными обёртками ради внешнего вида — только публичный API и слоты.
-- **`size`:** только `Input.Root`. Не прокидывать `size` в `Input.Field` (тип его исключает).
-- **Ошибка:** `error` на Root задаёт текст и включает invalid-стили; `hasError` без `error` — только состояние без текста.
-- **Доступность:** имя поля — `label` на Root или `aria-label` / `aria-labelledby` на `Input.Field`. Иконки и аффиксы не озвучиваются (`aria-hidden`).
-- **Контроль:** состояние строки — на `Input.Field` (`value`, `onChange`, `defaultValue`).
-- **Ширина:** отдельного пропа `fullWidth` нет; корень растягивается по ширине родителя — задавай ширину контейнеру формы/карточки.
-- **Сценарии из репозитория:** `examples/login-email.tsx`, `examples/search.tsx`, `examples/password-with-hint.tsx`, `examples/checkout-full-width.tsx`, `examples/affix-url-and-amount.tsx`.
-- **Playground (порядок секции Input):** `playground/snippets/input/sizes.tsx` → `states.tsx` → `controlled.tsx` → `composition.tsx` → `full-width.tsx` (+ `full-width.module.css`) → `features.tsx`.
+## Mistakes
+- `<Input.Field placeholder="Email" />` without a label → add `label` on `Input.Root` or `aria-label` on the field.
+- `<Input.Root disabled>` → `disabled` goes on `Input.Field`.
+- `<Input.Root fullWidth>` → there is no such prop; the root already fills its parent.
+- Passing both `hint` and `error` expecting both to show → only the error is shown.
+- Rendering `Input.ClearButton` for an empty field → render it only when there is a value.
+- Setting `className` with a custom border or background on `Input.Wrapper` → the fill comes from the surface context; fields inside Card/Modal already switch.
+- `tone="danger"` / `error` as a boolean → use `invalid` or an `error` message.
+
+## Related
+- [Label](../label/COMPONENT.md), [Hint](../hint/COMPONENT.md) — the parts Input renders for `label`, `hint`, `error`.
+- [Textarea](../textarea/COMPONENT.md), [Select](../select/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md) — fields with the same contract.
+- [Badge](../badge/COMPONENT.md) — what `Input.Badge` renders.

package/src/components/input/examples/anatomy.tsx

@@ -0,0 +1,70 @@
+/** Field anatomy on every size: label, required/optional markers, placeholder, hint, error and counter. Use it as the reference for how a field is assembled. */
+import { Input, Typography } from "prime-ui-kit";
+import type * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+type Size = (typeof SIZES)[number];
+
+const ROWS: { title: string; render: (size: Size) => React.ReactNode }[] = [
+  {
+    title: "Обязательное: подпись, *, плейсхолдер, подсказка",
+    render: (size) => (
+      <Input.Root size={size} label="Email" required hint="Пришлём ссылку для входа">
+        <Input.Wrapper>
+          <Input.Field type="email" placeholder="name@company.ru" />
+        </Input.Wrapper>
+      </Input.Root>
+    ),
+  },
+  {
+    title: "Необязательное и счётчик",
+    render: (size) => (
+      <Input.Root
+        size={size}
+        label="Должность"
+        optional
+        counter={<Input.Counter current={14} max={40} />}
+      >
+        <Input.Wrapper>
+          <Input.Field defaultValue="Менеджер по ИТ" maxLength={40} />
+        </Input.Wrapper>
+      </Input.Root>
+    ),
+  },
+  {
+    title: "Ошибка вместо подсказки",
+    render: (size) => (
+      <Input.Root size={size} label="ИНН" required error="ИНН состоит из 10 или 12 цифр">
+        <Input.Wrapper>
+          <Input.Field defaultValue="77010" inputMode="numeric" />
+        </Input.Wrapper>
+      </Input.Root>
+    ),
+  },
+];
+
+export default function InputAnatomyExample() {
+  return (
+    <div className={styles.anatomyScroller}>
+      <div className={styles.anatomyGrid}>
+        {SIZES.map((size) => (
+          <Typography.Root key={size} variant="code" tone="muted">
+            size="{size}"
+          </Typography.Root>
+        ))}
+        {ROWS.map((row) => (
+          <div key={row.title} className={styles.anatomyRow}>
+            <Typography.Root variant="caption" tone="muted" className={styles.anatomyRowHead}>
+              {row.title}
+            </Typography.Root>
+            {SIZES.map((size) => (
+              <div key={size}>{row.render(size)}</div>
+            ))}
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}

package/src/components/input/examples/control-alignment.tsx

@@ -0,0 +1,57 @@
+/** Button, Input, Select and Datepicker of the same size share height and radius. Use it for filter bars and toolbars that mix controls in one row. */
+import { Button, Datepicker, Icon, Input, Select, Typography } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
+
+function FilterRow({ size }: { size: (typeof SIZES)[number] }) {
+  const [date, setDate] = React.useState<Date | null>(null);
+  return (
+    <div className={styles.alignRow}>
+      <Typography.Root as="span" variant="code" tone="muted" className={styles.alignSize}>
+        {size}
+      </Typography.Root>
+      <div className={styles.alignField}>
+        <Input.Root size={size}>
+          <Input.Wrapper>
+            <Input.Icon side="start">
+              <Icon name="action.search" tone="secondary" />
+            </Input.Icon>
+            <Input.Field placeholder="Поиск заказа" aria-label="Поиск заказа" />
+          </Input.Wrapper>
+        </Input.Root>
+      </div>
+      <Select.Root size={size} placeholder="Статус">
+        <Select.Trigger aria-label="Статус">
+          <Select.Value />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="new">Новый</Select.Item>
+          <Select.Item value="paid">Оплачен</Select.Item>
+          <Select.Item value="shipped">Отправлен</Select.Item>
+        </Select.Content>
+      </Select.Root>
+      <Datepicker.Root
+        size={size}
+        mode="single"
+        value={date}
+        onValueChange={setDate}
+        placeholder="Дата"
+        aria-label="Дата заказа"
+      />
+      <Button.Root size={size}>Найти</Button.Root>
+    </div>
+  );
+}
+
+export default function InputControlAlignmentExample() {
+  return (
+    <div className={styles.alignStack}>
+      {SIZES.map((size) => (
+        <FilterRow key={size} size={size} />
+      ))}
+    </div>
+  );
+}

package/src/components/input/examples/controlled.tsx

@@ -0,0 +1,40 @@
+/** Controlled value with a clear button and a character counter in the support row. Use it for search fields and length-limited text. */
+import { Icon, Input } from "prime-ui-kit";
+import * as React from "react";
+
+import styles from "./examples.module.css";
+
+const MAX = 60;
+
+export default function InputControlledExample() {
+  const [query, setQuery] = React.useState("");
+  const [title, setTitle] = React.useState("Еженедельный отчёт по продажам");
+
+  return (
+    <div className={styles.stack}>
+      <Input.Root label="Поиск по каталогу">
+        <Input.Wrapper>
+          <Input.Icon side="start">
+            <Icon name="action.search" tone="secondary" />
+          </Input.Icon>
+          <Input.Field
+            placeholder="Название или артикул"
+            value={query}
+            onChange={(e) => setQuery(e.target.value)}
+          />
+          {query ? <Input.ClearButton onClick={() => setQuery("")} /> : null}
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root
+        label="Название отчёта"
+        hint="Видно всем участникам"
+        error={title.length > MAX ? "Слишком длинное название" : undefined}
+        counter={<Input.Counter current={title.length} max={MAX} />}
+      >
+        <Input.Wrapper>
+          <Input.Field value={title} onChange={(e) => setTitle(e.target.value)} />
+        </Input.Wrapper>
+      </Input.Root>
+    </div>
+  );
+}