@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/inputs/form-layout.md

@@ -0,0 +1,97 @@
+---
+component: FormLayout
+exports: [FormLayout, FieldRow]
+category: inputs
+status: stable
+source: src/components/inputs/FormLayout.tsx
+story: src/components/inputs/FormLayout.stories.tsx
+---
+
+# FormLayout и FieldRow
+
+## Кратко для AI
+
+Раскладка формы: `columns` (1 или 2) и `labels` (`top` или `side`), плюс
+`FieldRow` для поля во всю ширину. Только позиция узлов — ни валидации, ни
+состава полей, ни состояния. Подписи слева поддерживает только `FormField`:
+подпись рисует он.
+
+## Когда использовать
+
+- Форма из нескольких полей: настройки, редактирование сущности, регистрация.
+- Нужны подписи в колонке слева или две колонки полей.
+
+## Когда не использовать
+
+- Для отправки и блокировки на время запроса — это `Form`; их используют вместе.
+- Для группы полей с общим заголовком — родные `<fieldset>` и `<legend>`.
+  Отдельного `Fieldset` в ките нет намеренно: обёртка вокруг них не добавила бы
+  ничего, кроме имени в экспорте.
+
+## Минимальный пример
+
+```tsx
+import { FieldRow, FormField, FormLayout, TextControl } from "@olddevs/ui";
+
+<FormLayout columns={2} labels="side" labelWidth="8rem">
+  <FormField label="Имя" htmlFor="name">
+    <TextControl id="name" shellClassName="w-full" />
+  </FormField>
+  <FormField label="Фамилия" htmlFor="surname">
+    <TextControl id="surname" shellClassName="w-full" />
+  </FormField>
+  <FieldRow>
+    <FormField label="Адрес" htmlFor="address">
+      <TextControl id="address" shellClassName="w-full" />
+    </FormField>
+  </FieldRow>
+</FormLayout>;
+```
+
+## Пропы
+
+| Проп         | Умолчание | Назначение                                              |
+| ------------ | --------- | ------------------------------------------------------- |
+| `columns`    | `1`       | Число колонок. На узких экранах колонка всегда одна.    |
+| `labels`     | `"top"`   | Где стоят подписи полей: над полем или в колонке слева. |
+| `labelWidth` | `12rem`   | Ширина колонки подписей — любая длина CSS.              |
+
+`FieldRow` пропов не имеет: это `div` с `col-span-full`.
+
+## Сетка на CSS, а не расчёт в JS
+
+Одна колонка на узких экранах включается медиазапросом (`sm:grid-cols-2`), а не
+`matchMedia`. Раскладка, зависящая от JS, до гидратации неверна, и
+первый кадр формы приходится именно на этот момент.
+
+`FieldRow` занимает **все** колонки (`col-span-full`), а не фиксированные две:
+`col-span-2` в одноколоночной раскладке создал бы неявную вторую колонку, и
+форма разъехалась бы там, где ничего не меняли.
+
+## `labels="side"` действует на `FormField`, а не на любых детей
+
+Это следствие того, что подпись рисует само поле: перенести её в левую колонку
+снаружи невозможно, и раскладка лишь передаёт ось контекстом
+(ADR-0025).
+
+Позицию раскладка задаёт **любому** ребёнку — чужому `<input>`, полю другой
+библиотеки, целому блоку. Но подписи этих детей раскладка не видит, и `labels="side"` для
+них молча ничего не меняет. Явный `layout` на поле сильнее раскладки.
+
+Ширина колонки живёт в переменной `--form-label-w`; `labelWidth` — отдельный
+проп для этого, и он сильнее той же переменной, переданной через `style`.
+
+## Чего компонент не делает
+
+Ни валидации, ни состава полей, ни состояния — `Form` отказался от собственной
+валидации осознанно, и раскладка этого не пересматривает. Признак нарушения
+границы проверяемый: проп, который влияет не на позицию узлов, а на их состав.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/inputs/FormLayout.tsx`, ось подписи — в
+  `src/components/inputs/FormField.tsx`.
+- Тесты: `tests/form-layout.test.tsx` — обе оси, приоритет пропа поля,
+  `FieldRow` в обеих раскладках, чужие дети; `tests/form-field.test.tsx` —
+  тождественность разметки поля без оси.
+- Истории витрины: `src/components/inputs/FormLayout.stories.tsx`.

package/docs/components/inputs/form.en.md

@@ -0,0 +1,87 @@
+---
+component: Form and FormField
+exports: [Form, FormField]
+category: inputs
+status: stable
+source: src/components/inputs/Form.tsx
+story: src/components/inputs/Form.stories.tsx
+sourceHash: aea08fad91f4
+---
+
+# Form and FormField
+
+## Summary for AI
+
+`Form` standardizes submit and locking during a request, but does not create a validation system. `FormField` combines label, control, hint and error; the rules and the error state belong to the consumer.
+
+## When to use
+
+- You need to prevent a repeated form submission through `pending`.
+- Ordinary controls need an associated label, a hint and a consistent way to show errors.
+
+## When not to use
+
+- Do not look for a global `validationErrors` prop: there is no such public API.
+- Do not expect `FormField` to replace the `label` of components built on React Aria: `NumberInput` still requires its own `label`.
+
+## Minimal example
+
+```tsx
+<Form pending={saving} onSubmit={submit}>
+  <FormField label="Name" htmlFor="name" required error={errors.name} hint="Up to 80 characters">
+    <TextControl id="name" value={name} onChange={(e) => setName(e.target.value)} required />
+  </FormField>
+  <Button type="submit">Save</Button>
+</Form>
+```
+
+## Public API
+
+- `Form.onSubmit` is required; the component prevents native submit and does not call the callback while `pending`.
+- `pending` disables the children through a fieldset, including fields added later. A `RichTextEditor` inside `<fieldset disabled>` (including one set by the consumer, not only `Form pending`) is disabled the same way as a native field.
+- `Form` sets `noValidate` (`validationBehavior="aria"`): the browser's native validation does not work in it, and a required `RichTextEditor`, like a native `required`, does not block submission — the consumer shows the error through `FormField error`.
+- `FormField`: `label` is required, `htmlFor` ties it to the control's `id`, `error` replaces `hint`, `required` renders only a visual asterisk. `hintPersistent` keeps a rule hint ("8–64 characters, a digit and a letter") under the field even with an error. The error goes under it, and both describe the field; an explanatory hint ("how should we address you") is still replaced by the error (ADR-0065).
+- `error` is carried all the way **to the field**: kit fields read the invalid flag from context and set `aria-invalid` themselves, so the border turns red too, not only the text under the field. An explicit `aria-invalid` on the field wins — the consumer knows more about their field than the form does.
+
+## The `layout` axis on `FormField`
+
+`layout="stack"` (the default) — the label above the field, as it always was;
+`layout="side"` — the label in the left column, the field, the note and the error on the right.
+
+The axis lives **on the field, not on the layout**: `FormField` renders the label,
+and the layout cannot move it into the left column — it sits inside
+its own flex. The analysis is in
+ADR-0025.
+
+Without the prop, the field takes the axis from the nearest `FormLayout`; without
+a layout it is `stack`, and the markup does not change by a single node (this is
+checked by a test on the whole markup). An explicit prop wins over context.
+
+The width of the label column is the `--form-label-w` variable with a default of
+`12rem`; `subgrid` is not used, because it requires an outer grid with a known
+number of tracks, and the field must also work on its own:
+
+```tsx
+<div style={{ "--form-label-w": "8rem" }}>
+  <FormField label="Narrow column" htmlFor="x" layout="side">
+    <TextControl id="x" />
+  </FormField>
+</div>
+```
+
+A long label wraps inside its column and does not move the field.
+
+In the side layout, the field, the note and the error sit in **one** column as a
+whole, not one cell per node. A grid places children into cells, not by meaning,
+and a second child (a "from" and "to" range, a field with a button next to it)
+would otherwise land in the next row under the label.
+
+## Accessibility and forms
+
+- Set both `htmlFor` and `id`; a placeholder does not replace a label.
+- The FormField error is announced with `role="alert"`; the field itself must also be marked as required, through `required` or `aria-required`.
+- **The hint and error are tied to the field through `aria-describedby`.** `FormField` generates the `id`, and the kit fields pick it up — `TextControl` and everything built on it (`MaskedInput`, `PhoneInput`, `PasswordInput`, `SearchControl`), `NumberInput`, `Select`, `Combobox`, `DatePicker`, `TagInput` and others. This does not override the field's own description: a description passed as a prop is extended, not replaced.
+- The role and the description share the duties: `role="alert"` announces the error the moment it appears (it appears after submit, when focus has already moved away), while the description is read on returning to the field. The analysis is in ADR-0026.
+- The value format is a hint, not a placeholder: a placeholder disappears at the first character, that is, exactly when it is needed to check what was typed.
+- **The label publishes its own `id` through context.** `<label for>` names only the native `input`, `textarea`, `select`; a field that is not among them (the `contenteditable` of `RichTextEditor`) refers to the label through `aria-labelledby`. So `FormField` puts a stable `id` (from `useId`) on the `<label>` and hands it to the fields the same way as the description and the invalid state. Only `RichTextEditor` reads it; the consumer does not need to know the label's `id`, and `htmlFor` is still set — native fields need it. The `FormField` markup changes by one attribute — the label's `id`.
+- Sources: `src/components/inputs/Form.tsx`, `src/components/inputs/FormField.tsx`; tests `form.test.tsx`, `form-field.test.tsx`.

package/docs/components/inputs/form.md

@@ -0,0 +1,86 @@
+---
+component: Form and FormField
+exports: [Form, FormField]
+category: inputs
+status: stable
+source: src/components/inputs/Form.tsx
+story: src/components/inputs/Form.stories.tsx
+---
+
+# Form и FormField
+
+## Кратко для AI
+
+`Form` стандартизирует submit и блокировку на время запроса, но не создаёт систему валидации. `FormField` объединяет label, контрол, пояснение и error; правила и состояние ошибок принадлежат потребителю.
+
+## Когда использовать
+
+- Нужно предотвратить повторную отправку формы через `pending`.
+- Для обычных контролов нужен связанный label, пояснение и единый вывод ошибки.
+
+## Когда не использовать
+
+- Не ищите глобальный проп `validationErrors`: такого публичного API нет.
+- Не рассчитывайте, что `FormField` заменит собственный `label` у компонентов на React Aria: `NumberInput` всё равно требует свой `label`.
+
+## Минимальный пример
+
+```tsx
+<Form pending={saving} onSubmit={submit}>
+  <FormField label="Название" htmlFor="name" required error={errors.name} hint="До 80 символов">
+    <TextControl id="name" value={name} onChange={(e) => setName(e.target.value)} required />
+  </FormField>
+  <Button type="submit">Сохранить</Button>
+</Form>
+```
+
+## Public API
+
+- `Form.onSubmit` обязателен; компонент предотвращает native submit и не вызывает callback во время `pending`.
+- `pending` отключает children через fieldset, включая добавленные позднее поля. `RichTextEditor` внутри `<fieldset disabled>` (в том числе заданного потребителем, не только `Form pending`) выключается так же, как нативное поле.
+- `Form` ставит `noValidate` (`validationBehavior="aria"`): родная проверка браузера в нём не работает, и обязательный `RichTextEditor`, как и нативное `required`, отправку не блокирует — ошибку показывает потребитель через `FormField error`.
+- `FormField`: `label` обязателен, `htmlFor` связывает его с `id` контрола, `error` заменяет `hint`, `required` рисует только визуальную звёздочку. `hintPersistent` оставляет пояснение-правило («8–64 символа, цифра и буква») под полем и при ошибке. Ошибка встаёт под ним, обе описывают поле; обычное пояснение («как к вам обращаться») по-прежнему заменяет ошибка (ADR-0065).
+- `error` доводится **до поля**: поля кита читают признак невалидности из контекста и сами ставят `aria-invalid`, отчего краснеет и рамка, а не только текст под полем. Явный `aria-invalid` на поле сильнее — потребитель знает про своё поле больше, чем форма.
+
+## Ось `layout` у `FormField`
+
+`layout="stack"` (умолчание) — подпись над полем, как было всегда;
+`layout="side"` — подпись в колонке слева, поле, пояснение и ошибка справа.
+
+Ось живёт **у поля, а не у раскладки**: подпись рисует `FormField`, и
+перенести её в левую колонку снаружи невозможно — она лежит внутри его
+собственного флекса. Разбор —
+ADR-0025.
+
+Без пропа поле берёт ось у ближайшего `FormLayout`; без раскладки — `stack`, и
+разметка не меняется ни на узел (это проверяется тестом на разметку целиком).
+Явный проп сильнее контекста.
+
+Ширина колонки подписей — переменная `--form-label-w` со значением по умолчанию
+`12rem`; `subgrid` не используется, потому что он требует внешнего грида с
+известным числом дорожек, а поле обязано работать и само по себе:
+
+```tsx
+<div style={{ "--form-label-w": "8rem" }}>
+  <FormField label="Узкая колонка" htmlFor="x" layout="side">
+    <TextControl id="x" />
+  </FormField>
+</div>
+```
+
+Длинная подпись переносится внутри своей колонки и не двигает поле.
+
+В боковой раскладке поле, пояснение и ошибка лежат в **одной** колонке целиком,
+а не по ячейке на узел. Грид раскладывает детей по ячейкам, а не по смыслу, и
+второй ребёнок (диапазон «от» и «до», поле с кнопкой рядом) иначе попадал бы в
+следующий ряд под подпись.
+
+## Доступность и форма
+
+- Проставляйте и `htmlFor`, и `id`; плейсхолдер не заменяет label.
+- Ошибка FormField объявляется `role="alert"`; признак обязательности нужно продублировать на самом поле: `required` или `aria-required`.
+- **Пояснение и ошибка связаны с полем через `aria-describedby`.** `id` создаёт `FormField`, забирают его поля кита — `TextControl` и всё, что на нём стоит (`MaskedInput`, `PhoneInput`, `PasswordInput`, `SearchControl`), `NumberInput`, `Select`, `Combobox`, `DatePicker`, `TagInput` и другие. Своего описания это не отменяет: переданное пропом дополняется, а не вытесняется.
+- Роль и описание делят обязанности: `role="alert"` объявляет ошибку в момент появления (она возникает после отправки, когда фокус уже ушёл), а описание читается при возврате в поле. Разбор — ADR-0026.
+- Формат значения — это пояснение, а не плейсхолдер: плейсхолдер исчезает при первом символе, то есть ровно тогда, когда нужен для проверки набранного.
+- **Подпись публикует свой `id` контекстом.** `<label for>` называет только нативные `input`, `textarea`, `select`; поле, не относящееся к ним (`contenteditable` у `RichTextEditor`), ссылается на подпись через `aria-labelledby`. Поэтому `FormField` ставит на `<label>` стабильный `id` (из `useId`) и отдаёт его полям тем же приёмом, что описание и невалидность. Читает его только `RichTextEditor`; потребителю `id` подписи знать не нужно, а `htmlFor` проставляется по-прежнему — он нужен нативным полям. Разметка `FormField` от этого меняется на один атрибут — `id` подписи.
+- Источники: `src/components/inputs/Form.tsx`, `src/components/inputs/FormField.tsx`; тесты `form.test.tsx`, `form-field.test.tsx`.

package/docs/components/inputs/inline-edit.en.md

@@ -0,0 +1,93 @@
+---
+component: InlineEdit
+exports: [InlineEdit]
+category: inputs
+status: stable
+source: src/components/inputs/InlineEdit.tsx
+story: src/components/inputs/InlineEdit.stories.tsx
+sourceHash: b0f02517df86
+---
+
+# InlineEdit
+
+## Summary for AI
+
+Edit a value in place: value button → field → confirmation.
+The confirmed value arrives as a prop and the component does **not store** it.
+Escape restores both the value and the focus on the button.
+
+## When to use
+
+- A field that is read more often than edited: a title in a card, the properties
+  of an object, a cell of a settings list.
+
+## When not to use
+
+- In a form that is filled in as a whole, use a regular field in `FormField` instead.
+- When the edit has to be confirmed with a "Save" button together with the other
+  fields: `InlineEdit` confirms by itself, on Enter or when focus leaves.
+
+## Minimal example
+
+```tsx
+import { InlineEdit } from "@olddevs/ui";
+
+const [title, setTitle] = useState("Daily digest");
+
+<InlineEdit value={title} onChange={setTitle} label="Title" />;
+```
+
+## Props
+
+| Prop              | Default         | Purpose                                                                 |
+| ----------------- | --------------- | ----------------------------------------------------------------------- |
+| `value`           | —               | The confirmed value. The component does not store it.                   |
+| `onChange`        | —               | Confirmation. Called **only** when the value has changed.               |
+| `label`           | —               | The accessible name of the field. Required, enforced by the compiler.   |
+| `editing`         | —               | Controlled edit mode. Without the prop the component manages it itself. |
+| `onEditingChange` | —               | Reports the intent to open or close editing.                            |
+| `placeholder`     | message catalog | What to show on the button when the value is empty.                     |
+| `disabled`        | —               | Disables both the button and the field.                                 |
+
+## The confirmed value is not stored
+
+Only the draft lives inside — what is being typed right now. The confirmation is passed to the parent, and in the next frame the value comes back as a prop.
+
+The difference shows where it matters: if the server refused to save and the
+consumer did not change `value`, the component shows the **previous** one, not an
+invented one of its own. The draft also starts from the current value on every
+open — between edits it may have been changed by the parent.
+
+## Focus handling is the core of this component
+
+- **Opening** puts the focus in the field instead of leaving it on the button:
+  otherwise a keyboard user would open the field and type into nothing.
+- **Escape** restores the previous value **and** the focus on the button. This is
+  a requirement: without a way to cancel, someone who started editing by
+  mistake cannot leave without saving — a click elsewhere confirms, Enter confirms.
+- **Enter** confirms and also returns focus: the field disappears, and without
+  returning focus it would have gone to `<body>`.
+- **A click elsewhere** confirms and does **not** take the focus: the user went
+  where they wanted.
+
+Cancel clears its flag **when editing opens**, not only in the blur handler: after
+Escape the field unmounts and `blur` never arrives — the flag would stay raised,
+and the next edit would silently not be confirmed by a click elsewhere.
+
+This is checked in a live browser (`tests-visual/interactions.spec.ts`): in jsdom
+`document.activeElement` after unmounting behaves differently, and the test would
+pass on a broken component.
+
+## The button name is built from the content
+
+The value has to be in the accessible name: "Daily digest, edit". An `aria-label`
+would override it, and the screen reader would announce "edit title" without
+reading what is written there.
+
+## Related sources and tests
+
+- Implementation: `src/components/inputs/InlineEdit.tsx`; the scope of the wave is in
+  ADR-0024.
+- Tests: `tests/inline-edit.test.tsx` — the three transitions, cancel, no storing,
+  controlled mode; browser ones — focus return and a click elsewhere.
+- Showcase stories: `src/components/inputs/InlineEdit.stories.tsx`.

package/docs/components/inputs/inline-edit.md

@@ -0,0 +1,94 @@
+---
+component: InlineEdit
+exports: [InlineEdit]
+category: inputs
+status: stable
+source: src/components/inputs/InlineEdit.tsx
+story: src/components/inputs/InlineEdit.stories.tsx
+---
+
+# InlineEdit
+
+## Кратко для AI
+
+Правка значения по месту: кнопка-значение → поле → подтверждение.
+Подтверждённое значение приходит пропом и компонентом **не хранится**. Escape
+возвращает и значение, и фокус на кнопку.
+
+## Когда использовать
+
+- Поле, которое чаще читают, чем правят: название в карточке, свойства
+  объекта, ячейка списка настроек.
+
+## Когда не использовать
+
+- В форме, которую заполняют целиком, берите обычное поле в `FormField`.
+- Когда правку нужно подтверждать кнопкой «Сохранить» вместе с остальными
+  полями: `InlineEdit` подтверждает сам, по Enter или уходу фокуса.
+
+## Минимальный пример
+
+```tsx
+import { InlineEdit } from "@olddevs/ui";
+
+const [title, setTitle] = useState("Ежедневная подборка");
+
+<InlineEdit value={title} onChange={setTitle} label="Название" />;
+```
+
+## Пропы
+
+| Проп              | Умолчание         | Назначение                                                       |
+| ----------------- | ----------------- | ---------------------------------------------------------------- |
+| `value`           | —                 | Подтверждённое значение. Компонент его не хранит.                |
+| `onChange`        | —                 | Подтверждение. Вызывается, **только** когда значение изменилось. |
+| `label`           | —                 | Доступное имя поля. Обязательно, проверяет компилятор.           |
+| `editing`         | —                 | Режим правки снаружи. Без пропа компонент ведёт его сам.         |
+| `onEditingChange` | —                 | Сообщает о намерении открыть или закрыть правку.                 |
+| `placeholder`     | каталог сообщений | Что показать на кнопке при пустом значении.                      |
+| `disabled`        | —                 | Выключает и кнопку, и поле.                                      |
+
+## Подтверждённое значение не хранится
+
+Внутри живёт только черновик — то, что набирают прямо сейчас. Подтверждение
+уходит наружу, и следующим кадром значение приходит пропом.
+
+Разница видна там, где важна: если сервер отказался сохранить и потребитель не
+поменял `value`, компонент показывает **прежнее**, а не выдуманное своё.
+Черновик к тому же начинается с текущего значения при каждом открытии — между
+правками оно могло измениться снаружи.
+
+## Переходы фокуса — главное, что здесь есть
+
+- **Открытие** ставит фокус в поле, а не оставляет его на кнопке: иначе
+  пользователь клавиатуры открыл поле и печатает в никуда.
+- **Escape** возвращает прежнее значение **и** фокус на кнопку. Это
+  требование: без отмены начавший править по ошибке не может
+  выйти, не сохранив — щелчок мимо подтверждает, Enter подтверждает.
+- **Enter** подтверждает и тоже возвращает фокус: поле исчезает, и без
+  возврата фокус уехал бы на `<body>`.
+- **Щелчок мимо** подтверждает и фокус **не** забирает: пользователь ушёл
+  туда, куда хотел.
+
+Отмена сбрасывает свой флаг **при открытии** правки, а не только в обработчике
+потери фокуса: после Escape поле размонтируется и `blur` не приходит вовсе —
+флаг оставался бы поднятым, и следующая правка молча не подтверждалась бы по
+щелчку мимо.
+
+Проверяется в живом браузере (`tests-visual/interactions.spec.ts`): в jsdom
+`document.activeElement` после размонтирования ведёт себя иначе, и тест
+проходил бы на сломанном компоненте.
+
+## Имя кнопки строится из содержимого
+
+Значение обязано быть в доступном имени: «Ежедневная подборка, изменить».
+`aria-label` вытеснил бы его, и скринридер объявлял бы «изменить название», не
+читая того, что там написано.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/inputs/InlineEdit.tsx`; состав волны —
+  ADR-0024.
+- Тесты: `tests/inline-edit.test.tsx` — три перехода, отмена, отсутствие
+  хранения, контролируемый режим; браузерные — возврат фокуса и щелчок мимо.
+- Истории витрины: `src/components/inputs/InlineEdit.stories.tsx`.

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

@@ -0,0 +1,149 @@
+---
+component: MaskedInput
+exports: [MaskedInput, formatMask, unmask, maskCapacity]
+category: inputs
+status: stable
+source: src/components/inputs/MaskedInput.tsx
+story: src/components/inputs/MaskedInput.stories.tsx
+sourceHash: 9fcb60e26838
+---
+
+# MaskedInput
+
+## Summary for AI
+
+A field with an input mask, built on `TextControl`. The mask comes as a prop — the
+kit knows nothing about the domain. The value is **raw**; the display is
+formatted; both are passed to the consumer. The caret is what the component exists for.
+
+## When to use
+
+- Input in a fixed format: a date, a document series and number, a code, an account number.
+- A phone number — there is a ready-made `PhoneInput` built on the same engine.
+
+## When not to use
+
+- For amounts and any other numbers, use `NumberInput` with `formatOptions`: there
+  the grouping separators and the decimal separator come from the locale, and a mask would
+  hard-wire them.
+- For a date with a calendar, use `DatePicker`.
+
+## Minimal example
+
+```tsx
+import { MaskedInput } from "@olddevs/ui";
+
+const [value, setValue] = useState("");
+
+<MaskedInput mask="99.99.9999" value={value} onChange={(raw) => setValue(raw)} aria-label="Date" />;
+```
+
+## Props
+
+| Prop             | Default | Purpose                                                                 |
+| ---------------- | ------- | ----------------------------------------------------------------------- |
+| `mask`           | —       | The pattern: `9` is a digit, `a` is a letter, `*` is a digit or letter. |
+| `value`          | —       | The raw value, without the mask literals.                               |
+| `onChange`       | —       | `(raw, formatted)` — both representations at once.                      |
+| `showMask`       | `true`  | Show the format in the field itself: `+7 (___) ___-__-__`.              |
+| `shellClassName` | —       | Classes for the shell with the border.                                  |
+| the rest         | —       | Passed straight through to the `input`.                                 |
+
+## How the user learns the format
+
+Two ways at once, and they do not replace each other.
+
+**A mask guide in the field itself.** An empty field shows the whole mask,
+literals included: `+7 (___) ___-__-__`; as you type, it is consumed from left to
+right. Before kit version 2.4.0 the format was **not** communicated **at all**: `formatMask` stops
+where the value ends, so an empty field was an empty rectangle, and a half-filled
+one a stump with no remainder.
+
+The mask guide is decoration: it is `aria-hidden` and does not reach the screen
+reader. Turn it off with `showMask={false}` where the format is already stated
+nearby and repeating it in the field is noise: a short well-known mask in a dense
+table, a field under a label with an example.
+
+**The `FormField` hint.** It is the format for the screen reader: tied to the field
+through `aria-describedby`, so it is read on entering the field and stays available
+when the user checks what they typed. By then the mask guide has already been replaced
+by the input, and the hint has not.
+
+The format is not set with a placeholder: it disappears at the very first character,
+that is, exactly when it is needed for checking. The analysis and sources are in ADR-0026.
+
+## A character that does not fit is announced
+
+A character that did not fit its token is dropped — but not silently: a live region
+next to the field says what was expected here ("A digit is expected here"), and a
+filled mask answers that there is no more room.
+
+Exactly one typed character is parsed: per-character announcements for fifteen
+characters are noise, and text in the wrong format is caught by value validation,
+not by the input field.
+
+When text is pasted, what is counted is not which characters it contains but how
+many did not fit. A value that did not fit the mask is truncated — and the
+truncation is announced aloud, because the result looks plausible and therefore
+goes unnoticed: `89161234567`, a common form of a Russian phone number on the
+clipboard, with the mask `+7 (999) 999-99-99` turns into `+7 (891) 612-34-56`,
+that is, into someone else's number. The mask takes the leading "8" as the first
+digit, everything shifts and the last digit falls off.
+Neither the component nor the eye notices this, so the live region does.
+
+Silent dropping is not a minor thing: the reference implementation of
+[USWDS](https://designsystem.digital.gov/components/input-mask/accessibility-tests/)
+failed the WCAG 3.3.3 test on it (there, a mismatched character also cuts off the
+whole rest of the input).
+
+## The value is raw, the display is formatted
+
+Storing the format means storing a display decision: the mask can change, while
+the brackets recorded with it stay in the database forever.
+
+**Both** representations are passed to the consumer: the raw one is needed by a
+request, the shown one by whoever stores the text as is. Passing only one forces
+many consumers to reformat.
+
+Parsing is positional, together with the mask, not "throw out everything that
+looks like a literal": in the mask `+7 (999)` the literal `7` is also a digit, and
+a naive filter would carry it into the value, making the number eleven digits long.
+
+## The caret and Backspace
+
+Formatting redraws the whole string, and after that the browser puts the caret at
+the end — editing the middle of a number becomes impossible. The position is
+computed from the mask: the caret stays after the same number of value
+characters that were to its left.
+
+**Backspace across a literal deletes a value character, not the literal.**
+Otherwise the caret runs into `)`: the literal is deleted, comes right back with
+the formatting, and the keypress changes nothing — the defect looks like a stuck key.
+
+A paste needs no separate handler: the pasted text arrives in the same input event
+and is fitted to the mask in the same way as typed text.
+
+This is checked in a live browser (`tests-visual/interactions.spec.ts`): the caret
+position after a redraw is native mechanics that jsdom does not have.
+
+## There is no escaping in the mask
+
+There is no way to express the literal `9`. This is a limitation, not an
+oversight: none of the kit's formats needs a mandatory literal digit, and
+`\` would turn the mask into a syntax that needs separate documentation. If such a
+format appears, escaping will appear too.
+
+## The pure mask functions are available separately
+
+`formatMask(raw, mask)`, `unmask(display, mask)` and `maskCapacity(mask)` are
+exported: they are handy for preparing a value before sending or for checking
+completeness without mounting the component.
+
+## Related sources and tests
+
+- Implementation: `src/components/inputs/MaskedInput.tsx`, mechanics in `src/lib/mask.ts`;
+  the scope of the wave is in ADR-0024.
+- Tests: `tests/mask.test.ts` — formatting, parsing, the caret on strings;
+  `tests/masked-input.test.tsx` — input, paste, Backspace across a literal, both
+  representations; browser one — the caret after a redraw.
+- Showcase stories: `src/components/inputs/MaskedInput.stories.tsx`.