@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/inputs/masked-input.md

@@ -0,0 +1,147 @@
+---
+component: MaskedInput
+exports: [MaskedInput, formatMask, unmask, maskCapacity]
+category: inputs
+status: stable
+source: src/components/inputs/MaskedInput.tsx
+story: src/components/inputs/MaskedInput.stories.tsx
+---
+
+# MaskedInput
+
+## Кратко для AI
+
+Поле с маской ввода на `TextControl`. Маска приходит пропом — кит о предметной
+области не знает. Значение **сырое**, показ отформатированный; наружу уходят
+оба. Каретка — то, ради чего компонент нужен.
+
+## Когда использовать
+
+- Ввод в жёстком формате: дата, серия и номер документа, код, номер счёта.
+- Телефон — есть готовый `PhoneInput` на этом же движке.
+
+## Когда не использовать
+
+- Для суммы и любых чисел — это `NumberInput` с `formatOptions`: там
+  разделители разрядов и десятичный знак берутся из локали, а маска их зашила
+  бы намертво.
+- Для даты с календарём — это `DatePicker`.
+
+## Минимальный пример
+
+```tsx
+import { MaskedInput } from "@olddevs/ui";
+
+const [value, setValue] = useState("");
+
+<MaskedInput mask="99.99.9999" value={value} onChange={(raw) => setValue(raw)} aria-label="Дата" />;
+```
+
+## Пропы
+
+| Проп             | Умолчание | Назначение                                               |
+| ---------------- | --------- | -------------------------------------------------------- |
+| `mask`           | —         | Шаблон: `9` — цифра, `a` — буква, `*` — цифра или буква. |
+| `value`          | —         | Сырое значение, без литералов маски.                     |
+| `onChange`       | —         | `(raw, formatted)` — оба представления сразу.            |
+| `showMask`       | `true`    | Показывать формат в самом поле: `+7 (___) ___-__-__`.    |
+| `shellClassName` | —         | Классы на оболочку с рамкой.                             |
+| остальное        | —         | Уходит на `input` насквозь.                              |
+
+## Как пользователь узнаёт формат
+
+Двумя способами сразу, и они не заменяют друг друга.
+
+**Трафарет маски в самом поле.** Пустое поле показывает маску целиком,
+вместе с литералами: `+7 (___) ___-__-__`; по мере ввода она расходуется слева
+направо. До версии кита 2.4.0 формат не сообщался **вообще**: `formatMask` обрывается там, где
+кончилось значение, поэтому пустое поле было пустым прямоугольником, а
+наполовину заполненное — обрубком без остатка.
+
+Трафарет маски — украшение: он `aria-hidden` и скринридеру не достаётся. Выключается
+`showMask={false}` там, где формат уже сказан рядом и повторять его в поле — шум:
+короткая известная маска в плотной таблице, поле под подписью с примером.
+
+**Пояснение `FormField`.** Она и есть формат для скринридера: связана с полем
+через `aria-describedby`, поэтому читается при входе в поле и остаётся доступной,
+когда пользователь проверяет набранное. Трафарет маски к этому моменту уже заменён вводом,
+а пояснение — нет.
+
+Плейсхолдером формат не задаётся: плейсхолдер исчезает при первом же символе, то есть
+ровно тогда, когда нужен для проверки. Разбор и источники — ADR-0026.
+
+## Неподходящий символ объявляется
+
+Символ, не подошедший под токен, отбрасывается — но не молча: живая область
+рядом с полем говорит, чего здесь ждали («здесь нужна цифра»), а заполненная
+маска отвечает, что места больше нет.
+
+Разбирается ровно один набранный символ: посимвольные объявления на пятнадцать
+символов — шум, а текст не в том формате ловится проверкой значения, а не полем
+ввода.
+
+При вставке считается не то, какие символы пришли, а сколько их не влезло. Значение, которое в маску не влезло,
+обрезается — и об обрезке говорится вслух, потому что результат выходит
+правдоподобным, а значит незаметным: `89161234567`, частая форма
+российского телефонного номера в буфере обмена, под маской `+7 (999) 999-99-99`
+превращается в `+7 (891) 612-34-56`, то есть в чужой номер. Ведущую «8» маска
+принимает за первую цифру, всё сдвигается, последняя цифра выпадает. Ни
+компонент, ни глаз этого не замечают, поэтому замечает живая область.
+
+Молчаливое отбрасывание — не мелочь: на нём эталонная реализация
+[USWDS](https://designsystem.digital.gov/components/input-mask/accessibility-tests/)
+провалила тест WCAG 3.3.3 (у неё несовпавший символ вдобавок обрывает весь
+остаток ввода).
+
+## Значение сырое, показ отформатированный
+
+Хранить формат — значит хранить решение о показе: маску можно поменять, а
+записанные с ней скобки останутся в базе навсегда.
+
+Наружу уходят **оба** представления: сырое нужно запросу, показанное — тому,
+кто хранит текст как есть. Отдать одно — значит заставить многих потребителей
+форматировать заново.
+
+Разбор идёт позиционно, вместе с маской, а не «выбросим всё, что похоже на
+литерал»: в маске `+7 (999)` литерал `7` — тоже цифра, и наивный фильтр утащил
+бы его в значение, сделав номер одиннадцатизначным.
+
+## Каретка и Backspace
+
+Форматирование перерисовывает строку целиком, и браузер после этого ставит
+каретку в конец — править середину номера становится невозможно. Позиция
+считается по маске: сколько символов значения стояло левее, столько и
+останется.
+
+**Backspace через литерал удаляет символ значения, а не литерал.** Иначе
+каретка упирается в `)`: литерал удаляется, тут же возвращается
+форматированием, и нажатие ничего не меняет — дефект выглядит как зависшая
+клавиша.
+
+Вставка отдельного обработчика не требует: вставленное приходит тем же
+событием ввода и раскладывается по маске так же, как набранное.
+
+Проверяется в живом браузере (`tests-visual/interactions.spec.ts`): позиция
+каретки после перерисовки — родная механика, которой в jsdom нет.
+
+## Экранирования в маске нет
+
+Литерал `9` выразить нечем. Это ограничение, а не недосмотр: форматов с
+обязательной цифрой-литералом среди форматов кита не нашлось, а `\` сделал бы маску
+синтаксисом, который надо документировать отдельно. Появится такой формат —
+появится и экранирование.
+
+## Чистые функции маски доступны отдельно
+
+`formatMask(raw, mask)`, `unmask(display, mask)` и `maskCapacity(mask)`
+экспортируются: ими удобно готовить значение до отправки или проверять
+заполненность, не поднимая компонент.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/inputs/MaskedInput.tsx`, механика — `src/lib/mask.ts`;
+  состав волны — ADR-0024.
+- Тесты: `tests/mask.test.ts` — форматирование, разбор, каретка на строках;
+  `tests/masked-input.test.tsx` — ввод, вставка, Backspace через литерал, оба
+  представления; браузерный — каретка после перерисовки.
+- Истории витрины: `src/components/inputs/MaskedInput.stories.tsx`.

package/docs/components/inputs/number-input.en.md

@@ -0,0 +1,81 @@
+---
+component: NumberInput
+exports: [NumberInput]
+category: inputs
+status: stable
+source: src/components/inputs/NumberInput.tsx
+story: src/components/inputs/NumberInput.stories.tsx
+sourceHash: e9b0a093db1d
+---
+
+# NumberInput
+
+## Summary for AI
+
+`NumberInput` is a controlled numeric field with step buttons. An empty field returns `null`, not `0` and not `NaN`.
+
+## When to use
+
+- You need numeric input with `min`, `max`, `step` or `Intl.NumberFormat` formatting.
+- A form needs a field with an accessible name and "less/more" steps.
+
+## When not to use
+
+- For a free-text identifier or code, use `TextControl`; for a phone number there is `PhoneInput`.
+- For continuous selection on a visual scale, use `Slider`/`RangeSlider`.
+
+## Minimal example
+
+```tsx
+<NumberInput
+  label="Publication limit"
+  value={limit}
+  onChange={setLimit}
+  min={0}
+  max={100}
+  step={1}
+/>
+```
+
+## Public API
+
+- `value` and `onChange` are required; the value `null` means an empty input.
+- `label` is required and ties the name to the inner React Aria input; the `FormField` wrapper does not replace it.
+- `formatOptions` is passed to `Intl.NumberFormat`; `invalid` only shows the invalid state; the validation rule stays with the consumer. Inside a `FormField` with `error` the flag arrives from the form on its own; an explicit `invalid={false}` clears it.
+- `shellClassName` applies to the border, `className` to the root NumberField.
+
+## Currency is a `NumberInput`, not a separate component
+
+`CurrencyInput` **does not exist** in the kit, and this is a decision
+(ADR-0024), not a gap.
+A currency field comes down to `formatOptions`:
+
+```tsx
+<NumberInput
+  label="Amount"
+  value={amount}
+  onChange={setAmount}
+  formatOptions={{ style: "currency", currency: "RUB" }}
+/>
+```
+
+`Intl.NumberFormat` inside react-aria formats the currency, parses the input and
+takes the grouping separators and the decimal separator **from the locale**: in `ru-RU`
+that is `1 234,56 ₽`, in `en-US` — `$1,234.56`. A separate component would be a
+wrapper with no logic of its own, like a `ThemeSwitcher` over `Segmented`.
+
+Percentages and units of measure are handled by `Intl.NumberFormat` too:
+
+```tsx
+<NumberInput label="Discount" formatOptions={{ style: "percent" }} />
+<NumberInput label="Weight" formatOptions={{ style: "unit", unit: "kilogram" }} />
+```
+
+A mask is no help here: `MaskedInput` would hard-wire the separators, and in
+another locale the field would show the format of another locale.
+
+## Accessibility and forms
+
+- The step buttons get their names from `label` automatically.
+- Do not turn emptiness into zero: it changes the meaning of the data.
+- Source: `src/components/inputs/NumberInput.tsx`; checks — `tests/number-input.test.tsx`.

package/docs/components/inputs/number-input.md

@@ -0,0 +1,80 @@
+---
+component: NumberInput
+exports: [NumberInput]
+category: inputs
+status: stable
+source: src/components/inputs/NumberInput.tsx
+story: src/components/inputs/NumberInput.stories.tsx
+---
+
+# NumberInput
+
+## Кратко для AI
+
+`NumberInput` — управляемое числовое поле с кнопками шага. Пустое поле возвращает `null`, а не `0` и не `NaN`.
+
+## Когда использовать
+
+- Нужен числовой ввод с `min`, `max`, `step` или форматированием `Intl.NumberFormat`.
+- В форме требуется поле с доступным именем и шагами «меньше/больше».
+
+## Когда не использовать
+
+- Для свободного текстового идентификатора или кода — `TextControl`; для телефона есть `PhoneInput`.
+- Для непрерывного выбора на визуальной шкале — `Slider`/`RangeSlider`.
+
+## Минимальный пример
+
+```tsx
+<NumberInput
+  label="Лимит публикаций"
+  value={limit}
+  onChange={setLimit}
+  min={0}
+  max={100}
+  step={1}
+/>
+```
+
+## Public API
+
+- `value` и `onChange` обязательны; значение `null` означает пустой input.
+- `label` обязателен и связывает имя с внутренним React Aria input; обёртка `FormField` этого не заменяет.
+- `formatOptions` передаётся в `Intl.NumberFormat`; `invalid` только показывает невалидное состояние, правило проверки остаётся у потребителя. Внутри `FormField` с `error` признак приходит из формы сам; явный `invalid={false}` его снимает.
+- `shellClassName` относится к рамке, `className` — к корневому NumberField.
+
+## Валюта — это `NumberInput`, а не отдельный компонент
+
+`CurrencyInput` в ките **не существует**, и это решение
+(ADR-0024), а не
+пробел. Валютное поле — это `formatOptions`:
+
+```tsx
+<NumberInput
+  label="Сумма"
+  value={amount}
+  onChange={setAmount}
+  formatOptions={{ style: "currency", currency: "RUB" }}
+/>
+```
+
+`Intl.NumberFormat` внутри react-aria форматирует валюту, разбирает ввод и
+берёт разделители разрядов и десятичный знак **из локали**: в `ru-RU` это
+`1 234,56 ₽`, в `en-US` — `$1,234.56`. Отдельный компонент был бы
+обёрткой без собственной логики, вроде `ThemeSwitcher` над `Segmented`.
+
+Проценты и единицы измерения тоже даёт `Intl.NumberFormat`:
+
+```tsx
+<NumberInput label="Скидка" formatOptions={{ style: "percent" }} />
+<NumberInput label="Вес" formatOptions={{ style: "unit", unit: "kilogram" }} />
+```
+
+Маска здесь не помощник: `MaskedInput` зашил бы разделители намертво, и в
+другой локали поле показывало бы формат другой локали.
+
+## Доступность и форма
+
+- Кнопки шага автоматически получают имена от `label`.
+- Не превращайте пустоту в ноль: это меняет смысл данных.
+- Источник: `src/components/inputs/NumberInput.tsx`; проверки — `tests/number-input.test.tsx`.

package/docs/components/inputs/password-input.en.md

@@ -0,0 +1,101 @@
+---
+component: PasswordInput
+exports: [PasswordInput]
+category: inputs
+status: stable
+source: src/components/inputs/PasswordInput.tsx
+story: src/components/inputs/PasswordInput.stories.tsx
+sourceHash: 5a5f6ae9aba8
+---
+
+# PasswordInput
+
+## Summary for AI
+
+A password field built on the slots of `TextControl`: a show button in `trailing`,
+a Caps Lock warning under the field. It renders no border of its own. `autocomplete`
+is **required** and comes as a prop — the kit does not know whether this is a
+sign-in or a password change.
+
+## When to use
+
+- Any password field: sign-in, sign-up, password change, confirming an action.
+
+## When not to use
+
+- For an SMS code, use `PinInput`: it has N short fields and accepts a whole pasted code.
+- For a secret that must never be shown (a token on a settings screen), use a
+  regular `TextControl` with `type="password"` and no show button.
+
+## Minimal example
+
+```tsx
+import { FormField, PasswordInput } from "@olddevs/ui";
+
+<FormField label="Password" htmlFor="pwd">
+  <PasswordInput id="pwd" autoComplete="current-password" />
+</FormField>;
+```
+
+## Props
+
+| Prop              | Default         | Purpose                                                                         |
+| ----------------- | --------------- | ------------------------------------------------------------------------------- |
+| `toggleLabel`     | message catalog | The label of the show button. One for both states.                              |
+| `capsLockWarning` | `true`          | A warning under the field that Caps Lock is on.                                 |
+| `shellClassName`  | —               | Classes for the shell with the border: width, corner radius, spacing.           |
+| the rest          | —               | Passed straight through to the `input`: `autoComplete`, `required`, `disabled`. |
+
+## `autocomplete` has no default value
+
+The missing default is a decision, not an omission. The right value depends on what kind of
+form it is: `current-password` on sign-in, `new-password` on password change and
+on sign-up. The kit does not know this, and a wrong value is worse than a missing
+one — the password manager would offer to fill the old password into the new
+password field.
+
+```tsx
+<PasswordInput autoComplete="current-password" />  {/* sign-in */}
+<PasswordInput autoComplete="new-password" />      {/* password change and sign-up */}
+```
+
+## The show button: a constant label plus `aria-pressed`
+
+The state is announced by the `aria-pressed` attribute, not by the name. A button
+whose label and state both change reads as contradictory — "Hide password,
+pressed"; the ARIA Authoring Practices Guide (APG) rule for toggles is the
+opposite: the name is constant, `aria-pressed` changes.
+
+Without the attribute, a screen reader does not announce that the password is
+currently visible on the screen. That is a security state.
+
+**The caret is preserved on toggling.** Changing `type` resets the selection to the
+end of the value, and a user who revealed the password in the middle of an edit
+loses their place. The position is saved before the toggle and restored after it —
+**without moving focus**: the button was pressed on purpose, and taking focus away
+from it would break pressing it again from the keyboard.
+
+## Caps Lock is read from the keyboard, not guessed
+
+Whether Caps Lock is on comes from `getModifierState("CapsLock")` on the keyboard
+event. The common trick "the character comes in uppercase without Shift" fails
+here for two reasons: in a password field the characters are not visible, and a
+password made of capitals only is legitimate.
+
+The warning area (`role="status"`) exists in the markup **before** the text
+appears: a live region inserted together with its content is not announced by the
+screen reader. While there is no text, it is hidden from the layout and takes no
+space.
+
+The warning is cleared when leaving the field: it concerns typing in the field, not the
+keyboard state in general.
+
+## Related sources and tests
+
+- Implementation: `src/components/inputs/PasswordInput.tsx`. The composition on `TextControl` is
+  ADR-0009,
+  the decision on the component is in ADR-0025,
+  the wave contents are in ADR-0024.
+- Tests: `tests/password-input.test.tsx` — state announcement, a constant
+  label, the caret, Caps Lock, the single border.
+- Story: `src/components/inputs/PasswordInput.stories.tsx`.

package/docs/components/inputs/password-input.md

@@ -0,0 +1,97 @@
+---
+component: PasswordInput
+exports: [PasswordInput]
+category: inputs
+status: stable
+source: src/components/inputs/PasswordInput.tsx
+story: src/components/inputs/PasswordInput.stories.tsx
+---
+
+# PasswordInput
+
+## Кратко для AI
+
+Поле пароля на слотах `TextControl`: кнопка показа в `trailing`, предупреждение
+о Caps Lock под полем. Своей рамки не рисует. `autocomplete` **обязателен** и
+приходит пропом — кит не знает, вход это или смена пароля.
+
+## Когда использовать
+
+- Любое поле пароля: вход, регистрация, смена пароля, подтверждение действия.
+
+## Когда не использовать
+
+- Для кода из СМС используйте `PinInput`: там N коротких полей и вставка целого кода.
+- Для секрета, который нельзя показывать (токен на экране настроек), используйте
+  обычный `TextControl` с `type="password"` и без кнопки показа.
+
+## Минимальный пример
+
+```tsx
+import { FormField, PasswordInput } from "@olddevs/ui";
+
+<FormField label="Пароль" htmlFor="pwd">
+  <PasswordInput id="pwd" autoComplete="current-password" />
+</FormField>;
+```
+
+## Пропы
+
+| Проп              | Умолчание         | Назначение                                                          |
+| ----------------- | ----------------- | ------------------------------------------------------------------- |
+| `toggleLabel`     | каталог сообщений | Подпись кнопки показа. Одна на оба состояния.                       |
+| `capsLockWarning` | `true`            | Предупреждение о включённом Caps Lock под полем.                    |
+| `shellClassName`  | —                 | Классы на оболочку с рамкой: ширина, скругление, отступы.           |
+| остальное         | —                 | Уходит на `input` насквозь: `autoComplete`, `required`, `disabled`. |
+
+## `autocomplete` не имеет значения по умолчанию
+
+Отсутствие умолчания — решение, а не пропуск. Правильное значение зависит от того, что за форма:
+`current-password` на входе, `new-password` в смене пароля и в регистрации.
+Кит этого не знает, а неверное значение хуже отсутствующего — менеджер паролей
+предложит подставить старый пароль в поле нового.
+
+```tsx
+<PasswordInput autoComplete="current-password" />  {/* вход */}
+<PasswordInput autoComplete="new-password" />      {/* смена и регистрация */}
+```
+
+## Кнопка показа: постоянная подпись плюс `aria-pressed`
+
+Состояние объявляет атрибут `aria-pressed`, а не имя. Кнопка, у которой меняется
+и подпись, и состояние, читается противоречиво — «Скрыть пароль, нажато»;
+правило ARIA Authoring Practices Guide (APG) для переключателей обратное: имя
+постоянно, меняется `aria-pressed`.
+
+Без атрибута скринридер вообще не сообщит, что пароль сейчас открыт на экране.
+Это состояние безопасности.
+
+**Каретка при переключении сохраняется.** Смена `type` сбрасывает выделение в
+конец значения, и пользователь, открывший пароль посреди правки, теряет место.
+Позиция снимается до переключения и возвращается после — **без переноса
+фокуса**: кнопку нажали намеренно, и увозить с неё фокус — значит ломать
+повторное нажатие с клавиатуры.
+
+## Caps Lock читается у клавиатуры, а не угадывается
+
+Включён ли Caps Lock, берётся из `getModifierState("CapsLock")` на клавиатурном
+событии. Распространённый приём «символ пришёл заглавным без Shift» здесь не
+работает по двум причинам: в поле пароля символов не видно, а пароль из одних
+заглавных — законный.
+
+Область предупреждения (`role="status"`) существует в разметке **до** появления
+текста: живой регион, вставленный вместе со своим содержимым, скринридер не
+объявляет. Пока текста нет, она скрыта из раскладки и место не занимает.
+
+Предупреждение снимается при уходе из поля: оно относится к набору текста в
+поле, а не к состоянию клавиатуры вообще.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/inputs/PasswordInput.tsx`. Композиция на `TextControl` —
+  ADR-0009,
+  решение по компоненту — ADR-0025,
+  состав волны — ADR-0024.
+- Тесты: `tests/password-input.test.tsx` — объявление состояния, постоянство
+  подписи, каретка, Caps Lock, единственная рамка.
+- История: `src/components/inputs/PasswordInput.stories.tsx`.

package/docs/components/inputs/phone-input.en.md

@@ -0,0 +1,78 @@
+---
+component: PhoneInput
+exports: [PhoneInput, RU_PHONE_MASK]
+category: inputs
+status: stable
+source: src/components/inputs/PhoneInput.tsx
+story: src/components/inputs/PhoneInput.stories.tsx
+sourceHash: 5f7ba3f7a6ad
+---
+
+# PhoneInput
+
+## Summary for AI
+
+`MaskedInput` with a phone mask, `inputMode="tel"` and `autocomplete="tel"`.
+There is **one fixed format**, set by a prop. The number is not parsed, the
+country is not detected, there is no validation.
+
+## When to use
+
+- A phone field in a form where the format is known in advance.
+
+## When not to use
+
+- For international input with country detection, this component is the wrong choice:
+  it cannot do this and never will, see below.
+- For any other format, use `MaskedInput` with your mask.
+
+## Minimal example
+
+```tsx
+import { PhoneInput } from "@olddevs/ui";
+
+const [phone, setPhone] = useState("");
+
+<PhoneInput value={phone} onChange={(raw) => setPhone(raw)} aria-label="Phone" />;
+```
+
+## Props
+
+| Prop       | Default              | Purpose                                                               |
+| ---------- | -------------------- | --------------------------------------------------------------------- |
+| `mask`     | `+7 (999) 999-99-99` | The number format. `RU_PHONE_MASK` is exported.                       |
+| `value`    | —                    | Raw digits without literals.                                          |
+| `onChange` | —                    | `(raw, formatted)` — as in `MaskedInput`.                             |
+| `showMask` | `true`               | The format is visible in the field itself: `+7 (___) ___-__-__`.      |
+| the rest   | —                    | Passed to the `input`; `inputMode` and `autoComplete` are overridden. |
+
+## The "format from the locale" promise is withdrawn
+
+The kit's original specification introduced `PhoneInput` with a locale-based format. The promise was withdrawn
+deliberately (ADR-0024):
+
+- `Intl` does **not format** phone numbers at all — there is nothing in the locale to
+  take a format from;
+- proper parsing means `libphonenumber`, which weighs hundreds of kilobytes and would be a
+  peer dependency that an admin panel without phone numbers has no reason to pull in;
+- a mask for one format is wrong for other countries, and this page states that
+  limitation.
+
+So the format is a prop with a default, not a derived value. A default is a
+choice, not the truth.
+
+## What the component does not do
+
+It does not parse the number, does not keep a list of countries, **does not
+validate**. This is the first time the kit deals with a specific domain, and the
+boundary is drawn narrowly: a mask and two attributes. `Form` deliberately declines
+to validate, and `PhoneInput` does not reconsider that: the rules for deciding
+whether a number is real stay with whoever submits it.
+
+## Related sources and tests
+
+- Implementation: `src/components/inputs/PhoneInput.tsx` — a thin layer over
+  [MaskedInput](masked-input.md).
+- Tests: `tests/phone-input.test.tsx` — the default mask, a non-default format, both
+  representations passed to `onChange`, overridden attributes, no validation.
+- Story: `src/components/inputs/PhoneInput.stories.tsx`.

package/docs/components/inputs/phone-input.md

@@ -0,0 +1,76 @@
+---
+component: PhoneInput
+exports: [PhoneInput, RU_PHONE_MASK]
+category: inputs
+status: stable
+source: src/components/inputs/PhoneInput.tsx
+story: src/components/inputs/PhoneInput.stories.tsx
+---
+
+# PhoneInput
+
+## Кратко для AI
+
+`MaskedInput` с телефонной маской, `inputMode="tel"` и `autocomplete="tel"`.
+Формат **один и фиксированный**, задаётся пропом. Номер не разбирается, страна
+не определяется, валидации нет.
+
+## Когда использовать
+
+- Поле телефона в форме, где формат известен заранее.
+
+## Когда не использовать
+
+- Для международного ввода с определением страны этот компонент не подходит: он
+  этого не умеет и не будет уметь, см. ниже.
+- Для любого другого формата используйте `MaskedInput` с вашей маской.
+
+## Минимальный пример
+
+```tsx
+import { PhoneInput } from "@olddevs/ui";
+
+const [phone, setPhone] = useState("");
+
+<PhoneInput value={phone} onChange={(raw) => setPhone(raw)} aria-label="Телефон" />;
+```
+
+## Пропы
+
+| Проп       | Умолчание            | Назначение                                                     |
+| ---------- | -------------------- | -------------------------------------------------------------- |
+| `mask`     | `+7 (999) 999-99-99` | Формат номера. `RU_PHONE_MASK` экспортирован.                  |
+| `value`    | —                    | Сырые цифры без литералов.                                     |
+| `onChange` | —                    | `(raw, formatted)` — как у `MaskedInput`.                      |
+| `showMask` | `true`               | Формат виден в самом поле: `+7 (___) ___-__-__`.               |
+| остальное  | —                    | Уходит на `input`; `inputMode` и `autoComplete` перекрываются. |
+
+## Обещание «формат из локали» снято
+
+Исходная спецификация кита вводила `PhoneInput` с форматом по локали. Обещание снято сознательно
+(ADR-0024):
+
+- `Intl` телефоны **не форматирует** вовсе — брать формат из локали нечем;
+- настоящий разбор — это `libphonenumber` весом в сотни килобайт, то есть
+  peer-зависимость, которую админке без телефонов тащить не за что;
+- маска под один формат неверна для остальных стран, и страница оговаривает
+  это ограничение.
+
+Поэтому формат — проп с умолчанием, а не выведенное значение. Умолчание — это
+выбор, а не истина.
+
+## Чего компонент не делает
+
+Не разбирает номер, не хранит справочник стран, **не валидирует**. Кит здесь
+впервые знает о предметной области, и граница проведена узко: маска и два
+атрибута. `Form` от валидации отказался осознанно, и `PhoneInput` этого не
+меняет — правила «настоящий ли это номер» остаются у того, кто его
+отправляет.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/inputs/PhoneInput.tsx` — тонкий слой над
+  [MaskedInput](masked-input.md).
+- Тесты: `tests/phone-input.test.tsx` — маска по умолчанию, другой формат, оба
+  представления в `onChange`, перекрываемые атрибуты, отсутствие валидации.
+- История: `src/components/inputs/PhoneInput.stories.tsx`.