prime-ui-kit 0.7.13 → 0.9.1

package/src/components/hint/examples/sizes.tsx

@@ -1,13 +1,19 @@
-import { Hint } from "prime-ui-kit";
+/** Every size tier, matching the field above: 12/16 for xs–m, 13/20 for l and xl — `size`. */
+import { Hint, Typography } from "prime-ui-kit";
+
+const SIZES = ["xs", "s", "m", "l", "xl"] as const;
 
-/** Nominal `size` matches the field tier; hint typography is one step smaller (see styles). */
 export default function HintSizesExample() {
   return (
-    <>
-      <Hint.Root size="s">Hint size s</Hint.Root>
-      <Hint.Root size="m">Hint size m</Hint.Root>
-      <Hint.Root size="l">Hint size l</Hint.Root>
-      <Hint.Root size="xl">Hint size xl</Hint.Root>
-    </>
+    <div>
+      {SIZES.map((size) => (
+        <div key={size}>
+          <Hint.Root size={size}>Не менее 8 символов</Hint.Root>
+          <Typography as="span" variant="caption" tone="muted">
+            {size}
+          </Typography>
+        </div>
+      ))}
+    </div>
   );
 }

package/src/components/hint/examples/states.tsx

@@ -0,0 +1,27 @@
+/** Default help text next to an error and a hint under a disabled control — `invalid`, `disabled`. */
+import { Hint, Typography } from "prime-ui-kit";
+
+export default function HintStatesExample() {
+  return (
+    <div>
+      <div>
+        <Hint.Root>Формат: +7 900 000-00-00</Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          default
+        </Typography>
+      </div>
+      <div>
+        <Hint.Root invalid>Введите 10 или 12 цифр ИНН.</Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          invalid
+        </Typography>
+      </div>
+      <div>
+        <Hint.Root disabled>Лимит задаётся тарифом.</Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          disabled
+        </Typography>
+      </div>
+    </div>
+  );
+}

package/src/components/hint/examples/with-icon.tsx

@@ -1,13 +1,31 @@
-import { Hint, Icon } from "prime-ui-kit";
+/** A leading icon centred on the first line, in the default and the error state — `Hint.Icon`. */
+import { Hint, Icon, Typography } from "prime-ui-kit";
 
-/** Decorative leading icon; meaning must be repeated in text (`Hint.Icon` is `aria-hidden`). */
 export default function HintWithIconExample() {
   return (
-    <Hint.Root variant="default">
-      <Hint.Icon>
-        <Icon name="field.email" tone="subtle" />
-      </Hint.Icon>
-      We will send a confirmation code to this address.
-    </Hint.Root>
+    <div>
+      <div>
+        <Hint.Root>
+          <Hint.Icon>
+            <Icon name="field.email" />
+          </Hint.Icon>
+          На этот адрес придёт код подтверждения.
+        </Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          default
+        </Typography>
+      </div>
+      <div>
+        <Hint.Root invalid>
+          <Hint.Icon>
+            <Icon name="status.danger" />
+          </Hint.Icon>
+          Адрес уже занят другим аккаунтом.
+        </Hint.Root>
+        <Typography as="span" variant="caption" tone="muted">
+          invalid
+        </Typography>
+      </div>
+    </div>
   );
 }

package/src/components/input/COMPONENT.md

@@ -1,140 +1,232 @@
 # Input
 
-**Проектирование по умолчанию:** при проектировании экранов и примеров изначально выбирай **`m`** для `size` (где есть ось размера), если явно не оговорено иное.
-
-## Canonical
-
-- **Назначение:** однострочное поле с опциональной подписью, обводкой вокруг нативного `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).
-
+**Category:** inputs
+**Kind:** field
+
+> Single-line text field with label, hint, error and slots for icons, affixes, a clear button and a counter.
+
+## 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";
-
-export function Example() {
-  return (
-    <Input.Root label="Поле">
-      <Input.Wrapper>
-        <Input.Field placeholder="Значение" />
-      </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`.
+## 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.ClearButton    trailing clear action: a full-height segment at the end edge
+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 · 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
+
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+### Input.Root
+`ref` → `HTMLDivElement` (the field frame). Size, label, support row and the context for `Wrapper` and `Field`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `size` | `"xs" \| "s" \| "m" \| "l" \| "xl"` | `host tier, else "m"` | Tier for height, padding, radius, text, label and hint. Without it the field takes the tier of its host (LoginForm, Popover, a panel with a size), else `m`. Also provided to nested controls via the control-size context. |
+| `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`. |
+| `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. |
+| `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` | — | Id of the `<input>` (auto-generated when omitted); hint id is `<id>-hint`, error id is `<id>-error`. |
+| `labels` | `Partial<InputLabels>` | — | Built-in strings, see Labels. |
+| `children` | `ReactNode` | — (required) | Usually `Input.Wrapper`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "id" \| "children" \| "defaultValue" \| "defaultChecked" \| "onChange">` | — | `className`, `data-*` and the other attributes of the field frame `<div>` (field-root rule: `className`, `ref` and the rest → frame, `id` → control). |
+
+### Input.Wrapper
+`ref` → `HTMLDivElement`. The visible field: fill, hover, focus ring, invalid ring; `data-size` and `data-invalid` come from the root.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `ReactNode` | — (required) | `Field` and the slots: `Icon`, `Affix`, `InlineAffix`, `ClearButton`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the `<div>`. |
+
+### Input.Field
+`ref` → `HTMLInputElement`. The native `<input>`; `id`, `aria-invalid` and `aria-describedby` come from the root.
+
+| 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` | — | Overrides the root's `required` for the native input. |
+| `…rest` | `Omit<InputHTMLAttributes<HTMLInputElement>, "size" \| "id">` | — | `value`, `defaultValue`, `onChange`, `type`, `disabled`, `readOnly`, `maxLength`, `placeholder`… |
+
+### Input.Icon
+`ref` → `HTMLSpanElement`. Decorative icon (`aria-hidden`), centered between the edge and the text.
+
+| 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. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the `<span>`. |
+
+### Input.Affix
+`ref` → `HTMLDivElement`. Tinted section flush with the edge (`aria-hidden`); the wrapper drops its padding there.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `side` | `"start" \| "end"` | — (required) | Edge the section sits on. |
+| `children` | `ReactNode` | — (required) | Static text: protocol, domain, country code. |
+| `…rest` | `Omit<HTMLAttributes<HTMLDivElement>, "children">` | — | `className` and the other attributes of the `<div>`. |
+
+### Input.InlineAffix
+`ref` → `HTMLSpanElement`. Muted unit next to the value (`aria-hidden`).
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `side` | `"start" \| "end"` | — (required) | Side of the value. |
+| `children` | `ReactNode` | — (required) | Short unit: `₽`, `%`, `кг`. |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of the `<span>`. |
+
+### Input.ClearButton
+`ref` → `HTMLButtonElement`. A full-height clear segment at the end edge, named by `labels.clear`, with `aria-controls` on the input. Render it only while the field has a value.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `onClick` | `MouseEventHandler<HTMLButtonElement>` | — | Clear the value here. Afterwards focus returns to the input unless `event.preventDefault()` was called. |
+| `…rest` | `Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" \| "children" \| "aria-label">` | — | The other button attributes. |
+
+### Input.Counter
+`ref` → `HTMLSpanElement`. Character counter for the support row; shows `14/40` and announces `labels.counter`.
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `current` | `number` | — (required) | Current length. |
+| `max` | `number` | — (required) | Limit; `current > max` turns the counter danger (`data-invalid="true"`). |
+| `…rest` | `Omit<HTMLAttributes<HTMLSpanElement>, "children">` | — | `className` and the other attributes of 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). 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 `₽ % кг` | — |
+
+### Flags
+| Value | 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: an end icon together with the clear button (the icon sits before the button).
+- 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; a status of the value goes into the hint, not into the field.
+
+## 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 icons and affixes; the field height never changes.
+
+## Accessibility
+
+### Keyboard
+| Key | Action |
+|---|---|
+| `Tab` | Focuses the field, then the clear button when it is shown. |
+| `Enter` · `Space` | On the clear button: clears the value and returns focus to the field. |
+
+### ARIA
+- `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 and sets `aria-invalid="true"`.
+- `Input.Icon`, `Input.Affix`, `Input.InlineAffix` are `aria-hidden`: put the meaning in the label (e.g. "Сумма, ₽").
+- `Input.ClearButton` is a real button named by `labels.clear`, with `aria-controls` on the input.
+- `Input.Counter` shows `14/40` visually and announces `labels.counter` through `aria-live="polite"`.
+
+### Labels
+<!-- Generated from api.ts by `bun run docs:build`. Edit api.ts, not this section. -->
+
+| 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
+| Example | Shows |
+|---|---|
+| [overview.tsx](examples/overview.tsx) | A labelled field with a hint under it — `label`, `hint`. |
+| [sizes.tsx](examples/sizes.tsx) | Every size tier; the label and the hint follow the field tier — `size`. |
+| [states.tsx](examples/states.tsx) | A default field next to a disabled and a read-only one — `disabled`, `readOnly`. |
+| [validation.tsx](examples/validation.tsx) | Required and optional markers, a hint, an error and a support row that does not shift — `required`, `optional`, `hint`, `error`, `reserveSupportRow`. |
+| [with-icon.tsx](examples/with-icon.tsx) | A decorative icon at either end of the value — `Input.Icon`, `side`. |
+| [affixes.tsx](examples/affixes.tsx) | A fixed prefix and suffix flush with the edges and a unit next to the value — `Input.Affix`, `Input.InlineAffix`. |
+| [without-focus-ring.tsx](examples/without-focus-ring.tsx) | A single search field where the caret and the lighter fill show focus — `focusRing`. |
+| [controlled.tsx](examples/controlled.tsx) | The parent owns the value: a clear button and a character counter follow it — `value`, `onValueChange`, `Input.ClearButton`, `Input.Counter`. |
+| [in-form.tsx](examples/in-form.tsx) | Company details form: required fields checked on submit, neighbours keep their bottoms aligned — `required`, `error`, `reserveSupportRow`. |
+
+## 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
+- **Built from:** [Label](../label/COMPONENT.md) (`label`), [Hint](../hint/COMPONENT.md) (`hint`, `error`), `Icon` (`Input.ClearButton`)
+- **See also:** [Textarea](../textarea/COMPONENT.md), [Select](../select/COMPONENT.md), [Datepicker](../datepicker/COMPONENT.md), [TagSelect](../tag-select/COMPONENT.md) — fields with the same contract

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

@@ -0,0 +1,22 @@
+/** A fixed prefix and suffix flush with the edges and a unit next to the value — `Input.Affix`, `Input.InlineAffix`. */
+import { Input } from "prime-ui-kit";
+
+export default function InputAffixesExample() {
+  return (
+    <>
+      <Input.Root label="Адрес магазина" hint="Адрес: https://moy-magazin.shop.ru">
+        <Input.Wrapper>
+          <Input.Affix side="start">https://</Input.Affix>
+          <Input.Field placeholder="moy-magazin" />
+          <Input.Affix side="end">.shop.ru</Input.Affix>
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root label="Сумма платежа, ₽">
+        <Input.Wrapper>
+          <Input.Field placeholder="0,00" inputMode="decimal" />
+          <Input.InlineAffix side="end">₽</Input.InlineAffix>
+        </Input.Wrapper>
+      </Input.Root>
+    </>
+  );
+}

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

@@ -0,0 +1,39 @@
+/** The parent owns the value: a clear button and a character counter follow it — `value`, `onValueChange`, `Input.ClearButton`, `Input.Counter`. */
+import { Icon, Input } from "prime-ui-kit";
+import * as React from "react";
+
+const TITLE_LIMIT = 60;
+
+export default function InputControlledExample() {
+  const [query, setQuery] = React.useState("");
+  const [title, setTitle] = React.useState("Еженедельный отчёт по продажам");
+
+  return (
+    <>
+      <Input.Root label="Поиск по каталогу">
+        <Input.Wrapper>
+          <Input.Icon side="start">
+            <Icon name="action.search" tone="secondary" />
+          </Input.Icon>
+          <Input.Field
+            type="search"
+            placeholder="Название или артикул"
+            value={query}
+            onValueChange={setQuery}
+          />
+          {query ? <Input.ClearButton onClick={() => setQuery("")} /> : null}
+        </Input.Wrapper>
+      </Input.Root>
+      <Input.Root
+        label="Название отчёта"
+        hint="Видно всем участникам"
+        error={title.length > TITLE_LIMIT ? "Сократите название до 60 символов" : undefined}
+        counter={<Input.Counter current={title.length} max={TITLE_LIMIT} />}
+      >
+        <Input.Wrapper>
+          <Input.Field value={title} onValueChange={setTitle} />
+        </Input.Wrapper>
+      </Input.Root>
+    </>
+  );
+}

package/src/components/input/examples/examples.module.css

@@ -0,0 +1,38 @@
+/* Layout of the Input scenarios: semantic tokens only. */
+
+/* in-form.tsx: field → field 20, group → actions 32 (foundation §1). */
+.form {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-8);
+  width: min(100%, var(--prime-modal-width-m));
+}
+
+.formHeader {
+  display: flex;
+  flex-direction: column;
+  gap: var(--prime-space-1);
+}
+
+.formFields {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  align-items: start;
+  gap: var(--prime-space-5) var(--prime-space-4);
+}
+
+.formWide {
+  grid-column: 1 / -1;
+}
+
+.formActions {
+  display: flex;
+  justify-content: flex-end;
+  gap: var(--prime-space-2);
+}
+
+@media (max-width: 639px) {
+  .formFields {
+    grid-template-columns: minmax(0, 1fr);
+  }
+}