@olddevs/ui 0.0.0-stage → 4.0.0

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

@@ -0,0 +1,109 @@
+---
+component: PinInput
+exports: [PinInput]
+category: inputs
+status: stable
+source: src/components/inputs/PinInput.tsx
+story: src/components/inputs/PinInput.stories.tsx
+sourceHash: 9f00cd939372
+---
+
+# PinInput
+
+## Summary for AI
+
+Entry of a verification code: N single-digit fields that report **one string** as the value.
+Pasting a whole code spreads it across the fields, Backspace on an empty field
+moves focus back to the previous one, and `autocomplete="one-time-code"` is on the first field. The code is numeric.
+
+## When to use
+
+- A code from an SMS or an email, a PIN, a two-factor authentication code.
+
+## When not to use
+
+- For a password, use `PasswordInput`: one field and a show button.
+- An alphabetic code is deliberately not supported, see below.
+
+## Minimal example
+
+```tsx
+import { PinInput } from "@olddevs/ui";
+
+const [code, setCode] = useState("");
+
+<PinInput value={code} onChange={setCode} label="SMS code" />;
+```
+
+## Props
+
+| Prop        | Default | Purpose                                                               |
+| ----------- | ------- | --------------------------------------------------------------------- |
+| `value`     | —       | The whole code, as a string.                                          |
+| `onChange`  | —       | Called with a string, not an array or an event.                       |
+| `length`    | `6`     | How many fields.                                                      |
+| `label`     | —       | The accessible name of the group. Required, enforced by the compiler. |
+| `disabled`  | —       | Disables all fields.                                                  |
+| `autoFocus` | —       | Focuses the first field when the component appears.                   |
+| `invalid`   | —       | Shows the code in an error state: the field borders turn red.         |
+
+## The value is a string, and it has no holes
+
+The consumer needs the whole code: it goes into a request as one string, and
+every caller would have to parse an array.
+
+A consequence follows: the fields are a **display of one
+value**, not N independent ones. Deleting a character in the middle shifts the
+rest to the left, as in a regular text field.
+
+Clearing a field and typing a non-digit are different events. On focus the content
+of the field is selected, so a letter typed over an occupied digit is reported as a
+replacement of the selection. If the component did not tell them apart, it would
+erase a digit because of a character it never even showed.
+
+## Paste is intercepted, not left to the browser
+
+The SMS delivers the code as a whole, and the user pastes it into the first
+field. With `maxLength=1` the browser itself trims the pasted text to the first
+digit — so the component handles the paste event: the digits are taken from
+the text and spread across the fields starting from the current one.
+
+`autocomplete="one-time-code"` is on the **first** field — this is how the browser
+and iOS offer the code from the notification; on the others it would get in the way.
+
+## The code is numeric — and that is a decision
+
+`inputMode="numeric"` and `one-time-code` are about digits, and the input filter is
+the same here: everything except digits is dropped, both on input and on paste. An
+alphabetic code would need a second axis and case rules; it will be added when a
+screen needs it, not before.
+
+## Error: `invalid`
+
+`invalid` turns the borders of all the code fields red and sets `aria-invalid` on each field.
+The validation rule stays with the consumer: the prop only shows the result.
+
+Inside a `FormField` with `error` you pass no prop — the flag arrives from the form the same way as
+for `TextControl` and `NumberInput`, and the fields turn red together with the text below them. An
+explicit `invalid={false}` clears it: the consumer knows more about their field than the form does.
+A hint without an error does not make the code invalid.
+
+## Keyboard
+
+- typing a digit — focus moves forward;
+- Backspace on an empty field — a step back **with deletion** of the previous
+  digit: otherwise focus runs into an empty field and there is nothing to erase;
+- Left Arrow and Right Arrow move between the fields;
+- focus selects the field content: with `maxLength=1`, typing over an occupied
+  field otherwise does not go through at all.
+
+Each field is named ("Digit 3 of 6"): without names the screen reader reads six
+nameless fields in a row.
+
+## Related sources and tests
+
+- Implementation: `src/components/inputs/PinInput.tsx`; the wave contents are in
+  ADR-0024.
+- Tests: `tests/pin-input.test.tsx` — paste of a whole code and from the middle,
+  the digit filter, Backspace, arrow keys, field names, trimming by length.
+- Story: `src/components/inputs/PinInput.stories.tsx`.

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

@@ -0,0 +1,108 @@
+---
+component: PinInput
+exports: [PinInput]
+category: inputs
+status: stable
+source: src/components/inputs/PinInput.tsx
+story: src/components/inputs/PinInput.stories.tsx
+---
+
+# PinInput
+
+## Кратко для AI
+
+Ввод кода подтверждения: N полей по цифре, значение — **одна строка**. Вставка
+целого кода раскладывается по полям, Backspace на пустом поле возвращает фокус на предыдущее,
+`autocomplete="one-time-code"` стоит на первом поле. Код цифровой.
+
+## Когда использовать
+
+- Код из СМС или письма, ПИН, код двухфакторной аутентификации.
+
+## Когда не использовать
+
+- Для пароля используйте `PasswordInput`: там одно поле и показ по кнопке.
+- Для буквенного кода этот компонент не подходит: он этого намеренно не умеет, см. ниже.
+
+## Минимальный пример
+
+```tsx
+import { PinInput } from "@olddevs/ui";
+
+const [code, setCode] = useState("");
+
+<PinInput value={code} onChange={setCode} label="Код из СМС" />;
+```
+
+## Пропы
+
+| Проп        | Умолчание | Назначение                                               |
+| ----------- | --------- | -------------------------------------------------------- |
+| `value`     | —         | Код целиком, строкой.                                    |
+| `onChange`  | —         | Отдаёт строку, а не массив и не событие.                 |
+| `length`    | `6`       | Сколько полей.                                           |
+| `label`     | —         | Доступное имя группы. Обязательно, проверяет компилятор. |
+| `disabled`  | —         | Выключает все поля.                                      |
+| `autoFocus` | —         | Ставит фокус в первое поле при появлении.                |
+| `invalid`   | —         | Показывает код в состоянии ошибки: рамки полей красные.  |
+
+## Значение — строка, и дыр в нём не бывает
+
+Потребителю нужен код целиком: он уходит в запрос одной строкой, и разбирать
+массив на стороне вызова пришлось бы каждому.
+
+Отсюда следствие: поля — это **показ одного
+значения**, а не N независимых. Удаление символа в середине сдвигает остальные
+влево, как в обычном текстовом поле.
+
+Очистка поля и ввод не-цифры — разные события. При фокусе содержимое поля
+выделено, поэтому буква поверх занятой цифры приходит как замена выделенного.
+Если их не различать, компонент стирал бы цифру из-за символа, который даже не
+показал.
+
+## Вставка перехватывается, а не доверяется браузеру
+
+Код приходит из СМС целиком, и пользователь вставляет его в первое поле. При
+`maxLength=1` браузер сам обрезает вставленное до первой цифры — поэтому
+событие вставки обрабатывается компонентом: из текста берутся цифры и
+раскладываются по полям начиная с текущего.
+
+`autocomplete="one-time-code"` стоит на **первом** поле — так браузер и iOS
+предлагают код из уведомления; на остальных он мешал бы.
+
+## Код цифровой — и это решение
+
+`inputMode="numeric"` и `one-time-code` — про цифры, и фильтр ввода здесь тот
+же: всё, кроме цифр, отбрасывается и на вводе, и на вставке. Буквенный код
+потребовал бы второй оси и правил регистра; он придёт вместе с экраном,
+которому нужен, а не раньше.
+
+## Ошибка: `invalid`
+
+`invalid` красит рамки всех полей кода и ставит `aria-invalid` на каждое поле.
+Правило проверки остаётся у потребителя: проп только показывает результат.
+
+Внутри `FormField` с `error` проп не передают — флаг приходит из
+формы тем же путём, что у `TextControl` и `NumberInput`, и поля краснеют вместе
+с текстом под ними. Явный `invalid={false}` его снимает: потребитель знает про
+своё поле больше, чем форма. Пояснение без ошибки код невалидным не делает.
+
+## Клавиатура
+
+- ввод цифры — фокус вперёд;
+- Backspace на пустом поле — шаг назад **с удалением** предыдущей цифры: иначе
+  фокус упирается в пустое поле и стереть нечем;
+- стрелки влево и вправо — переход между полями;
+- фокус выделяет содержимое поля: при `maxLength=1` набор поверх занятого поля
+  иначе не проходит вовсе.
+
+Каждое поле названо («цифра 3 из 6»): без имён скринридер читает шесть
+безымянных полей подряд.
+
+## Связанные исходники и проверка
+
+- Реализация: `src/components/inputs/PinInput.tsx`; состав волны —
+  ADR-0024.
+- Тесты: `tests/pin-input.test.tsx` — вставка целиком и с середины, фильтр
+  цифр, Backspace, стрелки, имена полей, обрезка по длине.
+- История: `src/components/inputs/PinInput.stories.tsx`.

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

@@ -0,0 +1,100 @@
+---
+component: Rating
+exports: [Rating]
+category: inputs
+status: stable
+source: src/components/inputs/Rating.tsx
+story: src/components/inputs/Rating.stories.tsx
+sourceHash: 7c58e6f3588f
+---
+
+# Rating
+
+## Summary for AI
+
+`Rating` is a star rating. `value` and `onChange` work with a **number**, not a set of stars. The keyboard model is a radio group: the whole rating is one tab stop. There are no fractional ratings (half stars).
+
+## When to use
+
+- The user gives a rating: the quality of ticket handling, a review, a priority.
+- A rating has to be shown: the average score of a card, the result of a check.
+
+## When not to use
+
+- For a "mine" mark, use `FavoriteIcon` in a separate button, not a rating: a favorite is a "mine" mark, a rating is a quantity.
+- If the quantity is continuous or the range is wide, use `Slider`.
+- If there are only two values, use `Toggle`.
+
+## Minimal example
+
+```tsx
+<Rating value={value} onChange={setValue} aria-label="Quality" />
+```
+
+## Public API
+
+- `value` and `onChange` work with a number. Without `onChange` the component only shows the rating and does not enter the tab order.
+- `max` — how many stars in total, five by default. The value is coerced to an integer of at least one: a scale of zero divisions is not a scale, and the number comes from the consumer's data, so the component must not crash on it.
+- The component tolerates a fractional `value` (see below); `NaN` is treated as zero: no stars are filled and the announcement is "Rated 0 out of N".
+- `onChange` is **not called** when the value has not changed: an arrow key at the edge and a click on an already selected star stay silent — the handler would read a call without a change as an edit.
+- `size`: `sm` for a table row, `md` by default.
+- `readOnly` — display without input; `disabled` — an unavailable action. These are **different** states, see below.
+- `caption` — a label next to it ("4.2 · 128 ratings"). The kit does not compute it: the average and the number of votes are known to the consumer.
+- `aria-label` is required.
+
+## Keyboard — a radio group, not a set of buttons
+
+Arrow keys change the value, `Home` goes to zero, `End` to the maximum, Tab leaves
+the group as a whole. Five tab stops for one question is five stops where the
+answer is one; hence the `radiogroup` role.
+
+Exactly one star is in the tab order — the selected one, and with a zero rating
+the first (roving `tabindex`). Focus follows the value: otherwise the next arrow key
+would count from the previous star while the new value has already been announced.
+
+Zero is a legitimate value: the rating can be cleared by decreasing it from one with an arrow key,
+and with `Home`.
+
+## `readOnly` and `disabled` are different states
+
+Read-only is **displayed data**: dimming it would hide what is shown on purpose. A
+disabled control is an **action unavailable right now**, and it is dimmed. The
+first stays bright and leaves the tab order, the second fades.
+
+The role does not change: a disabled rating stays a `radiogroup` and is marked
+`aria-disabled`. `role="img"` would be read as a picture, not as an unavailable
+action. The role is a property of the control, not of its availability right now.
+
+## There are no fractional ratings — but the component tolerates a fractional value
+
+The `allowHalf` axis was not introduced, yet the type of `value` is a plain
+number, and the component accepts a fractional one for the fill: at `4.2` four
+stars are filled. So the tab stop is set by the **rounded** value. Without
+rounding no star would match, the roving `tabindex` would put the tab stop nowhere, and the
+radio group would become unreachable from the keyboard altogether — silently,
+without a single red check.
+
+## There are no fractional ratings
+
+Half a star is needed for displaying an average, not for input. Displaying an
+average is solved by a label ("4.2 · 128 ratings"), which is more precise than
+half a star and does not require explaining what a half-filled star means when it is used for input.
+
+## The star color is its own token
+
+It is the `--rating-star` token of the component layer
+(ADR-0040), not
+`--warning`. Today they point to the same amber palette primitive, and that is the trap:
+changing the warning color would silently repaint all the ratings in the product,
+and people would look for the cause in `Rating`.
+
+An unfilled star takes `--fg-3` (`text/muted-2`): it reads as "not selected", not
+as "unavailable". The `npm run contrast` gate checks two pairs against the non-text threshold: the filled star
+(`--rating-star`) on `--bg-1` and the empty star (`--fg-3`) on `--bg-1`. The row of stars carries the quantity visually.
+
+## Accessibility and semantics
+
+- The group name is **composed** of the consumer's label and the quantity ("Quality Rated 4 out of 5" — `aria-labelledby` joins the parts with a space), and not replaced by one of the two: a quantity without a subject does not answer "of what", and a subject without a quantity does not state the value.
+- In an interactive rating each star is a `radio` with its own name "N of M" and its own `aria-checked`; in the display-only mode the whole group is an `img` with the same composite name.
+- Color is not the only cue: the number of filled stars and the announced text say the same thing.
+- See `src/components/inputs/Rating.tsx`, `src/components/inputs/Rating.stories.tsx`, `tests/rating.test.tsx`.

package/docs/components/inputs/rating.md

@@ -0,0 +1,99 @@
+---
+component: Rating
+exports: [Rating]
+category: inputs
+status: stable
+source: src/components/inputs/Rating.tsx
+story: src/components/inputs/Rating.stories.tsx
+---
+
+# Rating
+
+## Кратко для AI
+
+`Rating` — оценка звёздами. В `value` и `onChange` идёт **число**, а не набор звёзд. Клавиатурная модель — радиогруппа: вся оценка — это один табстоп. Дробных оценок (половины звезды) нет.
+
+## Когда использовать
+
+- Пользователь ставит оценку: качество обращения, отзыв, приоритет.
+- Оценку надо показать: средний балл карточки, результат проверки.
+
+## Когда не использовать
+
+- Для отметки «моё» берите `FavoriteIcon` в отдельной кнопке, а не оценку: избранное — отметка «моё», оценка — величина.
+- Если величина непрерывная или диапазон широкий, используйте `Slider`.
+- Если значений два, используйте `Toggle`.
+
+## Минимальный пример
+
+```tsx
+<Rating value={value} onChange={setValue} aria-label="Качество" />
+```
+
+## Public API
+
+- `value` + `onChange` — число. Без `onChange` компонент только показывает оценку и в табуляцию не попадает.
+- `max` — сколько звёзд всего, по умолчанию пять. Значение приводится к целому не меньше единицы: шкала из нуля делений — не шкала, к тому же число приходит из данных потребителя, и падать на нём компонент не должен.
+- Дробное `value` компонент выдерживает (см. ниже), `NaN` принимается за ноль: звёзды не закрашены, объявляется «Оценка 0 из N».
+- `onChange` **не вызывается**, когда значение не изменилось: стрелка у края и щелчок по уже выбранной звезде молчат — вызов без изменения обработчик принял бы за правку.
+- `size`: `sm` для строки таблицы, `md` по умолчанию.
+- `readOnly` — показ без ввода; `disabled` — недоступное действие. Это **разные** состояния, см. ниже.
+- `caption` — подпись рядом («4,2 · 128 оценок»). Кит её не считает: среднее и число голосов знает потребитель.
+- `aria-label` обязателен.
+
+## Клавиатура — радиогруппа, а не набор кнопок
+
+Стрелки меняют значение, `Home` уводит на ноль, `End` — на максимум, Tab выводит
+из группы целиком. Пять табстопов на один вопрос — это пять остановок там, где
+ответ один; отсюда и роль `radiogroup`.
+
+В табуляции ровно одна звезда — выбранная, а при нулевой оценке — первая (roving
+`tabindex`). Фокус идёт за значением: иначе следующая стрелка отсчитывала бы от
+прежней звезды, а объявлено было бы новое значение.
+
+Ноль — законное значение: снять оценку можно и стрелкой назад с единицы, и
+`Home`.
+
+## `readOnly` и `disabled` — разные состояния
+
+Только для чтения — это **показанные данные**: приглушить их — значит спрятать то,
+что показано специально. Выключенный контрол — это **недоступное сейчас
+действие**, и его приглушают. Первое остаётся ярким и уходит из табуляции,
+второе гаснет.
+
+Роль при этом не меняется: выключенная оценка остаётся `radiogroup` и помечается
+`aria-disabled`. `role="img"` прочитался бы как картинка, а не как недоступное
+действие. Роль — свойство контрола, а не его доступности прямо сейчас.
+
+## Дробных оценок нет — но дробное значение компонент выдерживает
+
+Ось `allowHalf` не заведена, однако тип `value` — обычное число, и дробное
+значение даёт закраску: при `4.2` закрашены четыре звезды. Поэтому
+табстоп ставится по **округлённому** значению. Без округления не совпадала бы ни
+одна звезда, роуминг не поставил бы табстоп никуда, и радиогруппа стала бы
+недостижимой с клавиатуры целиком — молча, без единой красной проверки.
+
+## Дробных оценок нет
+
+Половина звезды нужна показу среднего значения, а не вводу. Показ среднего
+решается подписью «4,2 · 128 оценок»: она точнее половины звезды и не
+требует объяснять, что означает наполовину закрашенная звезда при вводе.
+
+## Цвет звезды — свой токен
+
+Цвет звезды берёт `--rating-star` компонентного слоя
+(ADR-0040), а не
+`--warning`. Сегодня они указывают на один и тот же янтарный примитив палитры, и в этом
+ловушка: правка цвета предупреждения молча перекрасила бы все оценки в продукте,
+а причину искали бы в `Rating`.
+
+Незакрашенная звезда берёт `--fg-3` (`text/muted-2`): она читается как «не
+выбрано», а не как «недоступно». Под гейтом `npm run contrast` две пары: закрашенная звезда (`--rating-star`) на `--bg-1` и
+пустая звезда (`--fg-3`) на `--bg-1`; порог нетекстовый. Ряд звёзд несёт величину визуально.
+
+## Доступность и семантика
+
+- Имя группы **склеивается** из подписи потребителя и величины («Качество Оценка 4 из 5» — `aria-labelledby` соединяет части пробелом), а не подменяется одним из двух: величина без предмета не отвечает на вопрос «чего», а предмет без величины не говорит о значении.
+- У интерактивной оценки каждая звезда — `radio` со своим именем «N из M» и своим `aria-checked`; у показа вся группа — `img` с тем же составным именем.
+- Цвет не единственный носитель: число закрашенных звёзд и объявленная строка говорят то же самое.
+- См. `src/components/inputs/Rating.tsx`, `src/components/inputs/Rating.stories.tsx`, `tests/rating.test.tsx`.