@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/components/inputs/transfer.md

@@ -0,0 +1,114 @@
+---
+component: Transfer
+exports: [Transfer, TransferItem]
+category: inputs
+status: stable
+source: src/components/inputs/Transfer.tsx
+story: src/components/inputs/Transfer.stories.tsx
+---
+
+# Transfer
+
+## Кратко для AI
+
+`Transfer` — две колонки и перенос между ними: слева то, что можно выбрать, справа — выбранное. Управляемый: `items` — все элементы разом, `value` — ключи тех, что оказались справа. Порядок `value` значим и сохраняется.
+
+## Когда использовать
+
+- Назначение прав, ролей, участников, территорий — всё, где «есть» и «выдано» надо видеть рядом.
+- Выбранных много, и порядок назначения важен.
+- Пользователю нужно видеть, что осталось невыбранным, а не только что выбрано.
+
+## Когда не использовать
+
+- Если выбирают одно значение или несколько из короткого списка, используйте `Select` с `multiple`.
+- Если значения набираются свободным вводом, используйте `TagInput`.
+- Если выбор идёт по иерархии, используйте `TreeSelect`.
+
+## Минимальный пример
+
+```tsx
+<Transfer
+  items={allPermissions}
+  value={granted}
+  onChange={setGranted}
+  sourceLabel="Все права"
+  targetLabel="Выданы роли"
+  searchable
+/>
+```
+
+## Public API
+
+- `items` — **все** элементы разом, независимо от колонки. Один список, а не два: два разъехались бы при первой правке, и элемент, забытый в обоих или пропавший из обоих, никак себя не проявит. `id` обязан быть уникальным: коллекция react-aria схлопывает дубликаты, и один из элементов молча пропадает с экрана.
+- `value` + `onChange` — ключи правой колонки. Порядок значим: это порядок назначения. Ключ, которого нет в `items`, кит не показывает, не считает и **не выбрасывает** — он переживает переносы нетронутым. Выбросить его значило бы молча править значение потребителя.
+- `sourceLabel` / `targetLabel` — подписи колонок; без них берутся из каталога сообщений.
+- `searchable` добавляет поле поиска над каждым списком. Кнопка переносит **только видимое**, то есть то, что пользователь видит; выделение, спрятанное фильтром, с места не двигается.
+- `disabled` гасит весь контрол: обе колонки и обе кнопки. Отличается от `TransferItem.disabled`, который про один показанный, но непереносимый элемент.
+- `aria-label` даёт паре колонок имя, и тогда она объявляется группой. Без имени группа не объявляется: безымянная группа — лишнее объявление для скринридера, за которым не следует ничего. То же правило, что у `ButtonGroup`.
+- `TransferItem.disabled` — элемент показан, но не переносится и не выбирается.
+
+## Потолок размера
+
+Виртуализации нет: каждый элемент получает DOM-узел. Замер задержки одного
+нажатия в поле поиска — 200 элементов — около 16 мс, 1000 — около 56 мс, 3000 — около
+187 мс. До нескольких сотен компонент комфортен, дальше ввод начинает
+ощущаться.
+
+Мемоизация здесь не помогает и намеренно не добавлена: тело рендера даже на
+20 000 элементов стоит около миллисекунды, а тратится всё в React и в
+пересборке коллекции. Нужны тысячи — это не проп, а решение о виртуализации.
+
+## Выделение и значение — разные вещи
+
+Подсветка внутри колонки живёт в компоненте и перенос не переживает. Значение —
+что в какой колонке — приходит и уходит пропами. Компонент их не смешивает:
+иначе «подсвечено» и «выдано» стали бы одним состоянием, и снять подсветку было
+бы нельзя, не отобрав право.
+
+## Счётчик считает колонку, а не фильтр
+
+Число в шапке — количество всего, что лежит в колонке, независимо от поиска: оно отвечает на
+вопрос «сколько всего прав доступно», а фильтр — это лишь взгляд на них. Оно же
+входит в доступное имя списка — иначе число на экране есть, а для скринридера его нет.
+
+## Выделить всё
+
+`Ctrl` / `Cmd` + `A` внутри колонки — штатное сочетание клавиш react-aria, и она отдаёт
+особое значение «всё», а не набор ключей. Кит раскрывает его в ключи своей
+колонки: иначе самый частый сценарий (выделить всё и перенести) гасил бы обе
+кнопки. Недоступные элементы при этом не переносятся: выделить всё не значит
+обойти запрет.
+
+## Фокус после переноса
+
+Единственное собственное решение компонента. После переноса выделенные элементы
+из списка исчезают — вместе с тем, на котором стоял фокус. react-aria на этот
+случай ответа не даёт: коллекция сменилась, и фокус уходит на `body`, то есть в
+начало документа.
+
+**Правило: фокус идёт за элементами.** Он встаёт на первый перенесённый элемент, а
+все перенесённые становятся там выделением — поэтому вернуть их можно, не
+выделяя заново.
+
+Фокус ставится кадром позже коммита, и это не оптимизация: `ListBox` строит свою
+коллекцию отдельным проходом, и сразу после коммита в ней ещё нет перенесённого
+элемента — зато есть тот, что был в колонке раньше. Синхронная установка фокуса
+попадала именно в него.
+
+Альтернатива «оставить фокус на кнопке» ломается на первом же полном переносе:
+кнопка гаснет, потому что переносить больше нечего, и фокус теряется всё равно.
+
+## Недоступный элемент
+
+Показан, но не переносится. Скрыть его значило бы соврать про состав прав —
+пользователь не увидит, что право вообще существует; перенести — обойти запрет.
+Кнопка переноса остаётся выключенной, если выделены только недоступные элементы.
+
+## Доступность и семантика
+
+- Каждая колонка — `listbox`, имя которого складывается из подписи и счётчика; элементы — `option` с множественным выделением. Клавиатура, поиск набором по первым буквам и роли приходят из `ListBox` react-aria.
+- Кнопки переноса названы по смыслу действия («Перенести в выбранное»), а не стрелкой: «вправо» ничего не говорит о смысле.
+- Имя поля поиска параметризовано подписью колонки: полей два, и «Поиск» у обоих не различает их ничем.
+- Пустая колонка говорит «Пусто», пустой результат поиска — «Ничего не найдено»; обе строки из `common`, своих ключей компонент на них не заводит.
+- См. `src/components/inputs/Transfer.tsx`, `src/components/inputs/Transfer.stories.tsx`, `tests/transfer.test.tsx`.

package/docs/components/inputs/tree-select.en.md

@@ -0,0 +1,91 @@
+---
+component: TreeSelect
+exports: [TreeSelect]
+category: inputs
+status: stable
+source: src/components/inputs/TreeSelect.tsx
+story: src/components/inputs/TreeSelect.stories.tsx
+sourceHash: 992d056f99b6
+---
+
+# TreeSelect
+
+## Summary for AI
+
+`TreeSelect` is a field that picks a node of a hierarchy: a [`TreeView`](../navigation/tree-view.md) inside a [`Popover`](../overlays/popover.md). Controlled; `value` is **always an array**, even for a single selection. Checking a branch does not check its descendants.
+
+## When to use
+
+- The value is picked from a tree: a division, a folder, a category, a permissions scope.
+- The tree is long and there is no reason to keep it expanded on the screen.
+
+## When not to use
+
+- If there is no hierarchy and the list is flat, use `Select`.
+- If the tree is the content of the screen rather than the value of a field, use `TreeView`.
+- If the number of levels is fixed and the whole path matters, you need a cascading field; the kit has none, and ADR-0038 explains why.
+
+## Minimal example
+
+```tsx
+<TreeSelect
+  items={divisions}
+  value={value}
+  onChange={setValue}
+  aria-label="Division"
+  defaultExpandedKeys={["company"]}
+/>
+```
+
+## Public API
+
+- `items` are nodes in the `TreeNode` format; it is the same format as in `TreeView`, not a copy of it. A node encountered a second time during the traversal is not expanded further: a cycle in the data must not turn into a stack overflow.
+- `value` and `onChange` always work with an **array of keys**, both with `multiple` and without it.
+- `multiple` turns on multiple selection and changes the look of the closed field: chips instead of a label.
+- `placeholder` is the text shown in an empty field. Defaults to the text from the message catalog.
+- `defaultExpandedKeys` — which nodes are expanded on first render; `expandedKeys` + `onExpandedChange` — controlled expansion. The second is for consumers who expand the tree to the current value or load branches on demand (lazy loading): without it a deeply nested selected node opens on a collapsed tree where nothing points to it.
+- `clearable` shows a clear button when something is selected; `clearLabel` sets its accessible name, as in `Select`.
+- `disabled` keeps the field from opening and closes one that is already open.
+- `aria-label` is required: for an unnamed field a screen reader announces only the value and "button", not what the field is for. `aria-label` becomes part of the field name together with the value, not instead of it.
+- A key that is not in `items` is shown **as the key itself**. Hiding it would give a field that says "nothing selected" while reporting a non-empty value to the consumer; dropping it would silently edit the consumer's value.
+- With `multiple` no more than three chips are shown; the rest collapse into "+N more": a field that grows by five rows stops being a field. To see exactly what is selected, open the tree.
+
+## Composition, not a second tree
+
+This implements ADR-0024,
+which postponed `TreeSelect` until the first screen needed it and described it as a `Tree` inside a `Popover`.
+The component adds no node traversal of its own, no keyboard of its own and no
+roles of its own — `TreeView` already has all of that. The `treegrid` role inside
+the popover comes from there too.
+
+A divergence between two trees would be noticeable only to someone who puts them
+side by side. It would be discovered late and at great cost.
+
+## The value is always an array
+
+A union type `Key | Key[]` would make the consumer parse the shape of the value in
+every handler. The only gain would be a shorter-looking example.
+
+## Checking a branch does not check descendants
+
+This is a decision, not an oversight. Checking descendants would mean the kit decided
+for the consumer whether a "department" includes all its employees — and in access
+rights those are exactly opposite policies. `TreeView` keeps the selection by keys,
+and expanding a branch into its descendants in the consumer's code is one function over
+`items`; inside the kit it would be a decision that cannot be undone.
+
+## Keyboard
+
+- The field is a regular button: Enter and Space open it, Escape closes it and returns focus to the field.
+- Inside, the `TreeView` keyboard support applies: arrow keys, `Home`, `End`, typeahead.
+- Delete and Backspace on the field clear it when `clearable` is set — shorter than tabbing to the clear button, which is also a tab stop.
+- A single selection closes the popover; a multiple one leaves it open: the selection is not finished yet, and every close would force the user to reopen the popover after each node.
+
+## Accessibility and semantics
+
+- The field name is assembled from a hidden label and the content through `aria-labelledby`, not taken from `aria-label` on the button. `aria-label` wins over the content when the name is computed, and the field would be announced as "Division, button" — without a single word about what is selected. For a selection field that is a failure of the main function, and an axe audit does not catch it: the button has a name.
+- The clear button is a **sibling** of the trigger, not its descendant; the technique is the same as in `Select`. A button inside a button is `nested-interactive`, and an `aria-hidden` clear button inside drops out of the accessibility tree entirely: a user of assistive technology (AT) does not learn that clearing exists.
+- The tree inside the popover gets the same name as the field: otherwise a screen reader would announce "Division" followed by an unnamed tree.
+- An empty tree says `common.empty` — "Empty", not `notFound`: the field has no search of its own, and the user has not entered any query that could return "nothing found".
+- `aria-haspopup` is declared as `grid`: the popover contains `TreeView`, which renders a `treegrid` with `row` nodes. The declared type must match what is really there.
+- See `src/components/inputs/TreeSelect.tsx`, `src/components/inputs/TreeSelect.stories.tsx`, `tests/tree-select.test.tsx`, [TreeView](../navigation/tree-view.md).

package/docs/components/inputs/tree-select.md

@@ -0,0 +1,89 @@
+---
+component: TreeSelect
+exports: [TreeSelect]
+category: inputs
+status: stable
+source: src/components/inputs/TreeSelect.tsx
+story: src/components/inputs/TreeSelect.stories.tsx
+---
+
+# TreeSelect
+
+## Кратко для AI
+
+`TreeSelect` — поле, выбирающее узел иерархии: [`TreeView`](../navigation/tree-view.md) внутри [`Popover`](../overlays/popover.md). Управляемый; `value` — **всегда массив**, даже при одиночном выборе. Отметка ветки потомков не отмечает.
+
+## Когда использовать
+
+- Значение выбирают из дерева: подразделение, папка, категория, область прав.
+- Дерево длинное, и держать его развёрнутым на экране незачем.
+
+## Когда не использовать
+
+- Если иерархии нет и список плоский, используйте `Select`.
+- Если дерево и есть содержимое экрана, а не значение поля, используйте `TreeView`.
+- Если уровней фиксированное число и важен путь целиком, нужно каскадное поле; в ките его нет, и ADR-0038 объясняет, почему.
+
+## Минимальный пример
+
+```tsx
+<TreeSelect
+  items={divisions}
+  value={value}
+  onChange={setValue}
+  aria-label="Подразделение"
+  defaultExpandedKeys={["company"]}
+/>
+```
+
+## Public API
+
+- `items` — узлы в формате `TreeNode`; это тот же формат, что у `TreeView`, а не его копия. Узел, встреченный в обходе второй раз, дальше не разворачивается: цикл в данных не должен превращаться в переполнение стека.
+- `value` + `onChange` — **массив ключей всегда**, и при `multiple`, и без него.
+- `multiple` включает множественный выбор и меняет вид закрытого поля: чипы вместо подписи.
+- `placeholder` — текст в пустом поле; без неё берётся из каталога сообщений.
+- `defaultExpandedKeys` — что раскрыто при первом показе; `expandedKeys` + `onExpandedChange` — управляемое раскрытие. Второе нужно тому, кто раскрывает дерево до текущего значения или подгружает ветки по мере раскрытия (lazy loading): без него глубоко лежащий выбранный узел открывается на свёрнутом дереве, где на него ничто не указывает.
+- `clearable` показывает кнопку очистки, когда что-то выбрано; `clearLabel` даёт ей своё имя — как у `Select`.
+- `disabled` не даёт полю раскрыться и закрывает уже открытое.
+- `aria-label` обязателен: у безымянного поля скринридер назовёт только значение и «кнопка», но не то, о чём поле. `aria-label` входит в имя поля вместе со значением, а не вместо него.
+- Ключ, которого нет в `items`, показывается **самим ключом**. Спрятать его значило бы дать поле, которое говорит «ничего не выбрано» и отдаёт потребителю непустое значение; выбросить — молча править значение потребителя.
+- При `multiple` показывается не больше трёх чипов, остальные сворачиваются в «ещё N»: поле, вырастающее на пять строк, перестаёт быть полем. Точный состав смотрят в раскрытом дереве.
+
+## Композиция, а не второе дерево
+
+Исполняет ADR-0024: тот
+отложил `TreeSelect` до первого экрана-заказчика и описал его как `Tree` внутри `Popover`. Своего
+обхода узлов, своей клавиатуры и своих ролей компонент не заводит — всё это уже
+есть у `TreeView`. Роль `treegrid` внутри поповера приходит оттуда же.
+
+Расхождение двух деревьев заметил бы только тот, кто поставит их рядом.
+Обнаружилось бы оно поздно и дорого.
+
+## Значение всегда массив
+
+Тип-объединение `Key | Key[]` заставил бы потребителя разбирать форму значения в
+каждом обработчике. Выигрыш был бы один: в примере код короче.
+
+## Отметка ветки не отмечает потомков
+
+Это решение: отмечать потомков значило бы, что кит решил за
+потребителя, включает ли «отдел» всех его сотрудников. А в правах доступа это
+противоположные политики. `TreeView` ведёт выбор ключами, и раскрыть ветку
+в потомков в коде потребителя — одна функция над `items`; внутри кита это было бы решение,
+которое нельзя отменить.
+
+## Клавиатура
+
+- Поле — обычная кнопка: Enter и Space раскрывают, Escape закрывает и возвращает фокус полю.
+- Внутри работает клавиатура `TreeView`: стрелки, `Home`, `End`, поиск набором.
+- Delete и Backspace на поле очищают его при `clearable` — короче, чем переходить клавишей Tab до кнопки очистки, которая тоже табстоп.
+- Одиночный выбор закрывает поповер, множественный оставляет открытым: выбор ещё не закончен, и каждое закрытие заставляло бы открывать поповер заново после каждого узла.
+
+## Доступность и семантика
+
+- Имя поля собирается из скрытой подписи и содержимого через `aria-labelledby`, а не берётся из `aria-label` на кнопке. `aria-label` побеждает содержимое при вычислении имени, и поле объявлялось бы «Подразделение, кнопка» — без единого слова о том, что выбрано. Для поля выбора это отказ основной функции, и аудит axe его не ловит: имя у кнопки есть.
+- Кнопка очистки — **сосед** триггера, а не его потомок; приём тот же, что у `Select`. Кнопка внутри кнопки — это `nested-interactive`, а `aria-hidden`-крестик внутри выпадает из дерева доступности целиком: пользователь вспомогательных технологий (AT) не узнаёт, что очистка есть.
+- Дерево внутри поповера получает то же имя, что и поле: иначе после «Подразделение» скринридер читал бы безымянное дерево.
+- Пустое дерево говорит `common.empty` — «Пусто», а не `notFound`: своего поиска у поля нет, и запроса, по которому «ничего не найдено», пользователь не делал.
+- `aria-haspopup` объявлен как `grid`: внутри `TreeView`, а он рендерит `treegrid` с узлами-`row`. Объявленный тип обязан совпадать с тем, что там на самом деле.
+- См. `src/components/inputs/TreeSelect.tsx`, `src/components/inputs/TreeSelect.stories.tsx`, `tests/tree-select.test.tsx`, [TreeView](../navigation/tree-view.md).

package/docs/components/inputs/upload-queue.en.md

@@ -0,0 +1,160 @@
+---
+component: UploadQueue
+exports: [UploadQueue, UploadItem, ProgressStatus]
+category: inputs
+status: stable
+source: src/components/inputs/UploadQueue.tsx
+story: src/components/inputs/UploadQueue.stories.tsx
+sourceHash: 53ff777f44ef
+---
+
+# UploadQueue
+
+## Summary for AI
+
+An upload manager: what has been sent, what is in progress and what failed. **Presentation
+only** — the kit has no transport. Items and handlers come as props; the outcome of the
+queue is announced to the screen reader through a live region.
+
+## When to use
+
+- The user sends several files and has to see what happened to each.
+- Some files may fail while others go through: partial success must be possible.
+- You need actions on an item: retry, cancel, remove from the queue.
+
+## When not to use
+
+- To **choose** a file, use `FileDropzone`. The boundary is simple: the area
+  supplies files, the queue shows what happened to them. On the screen they sit
+  side by side, and that is exactly why they get confused.
+- For a single file without progress and without errors — a queue of one row says
+  nothing that the file name next to the field would not say.
+- For a feed of already completed events, use `Timeline`: there a step has no
+  actions, and the order is set by the process, not by the user.
+
+## Minimal example
+
+```tsx
+import { UploadQueue, type UploadItem } from "@olddevs/ui";
+
+const [items, setItems] = useState<UploadItem[]>([]);
+
+<UploadQueue items={items} empty={<EmptyState title="The queue is empty" />} />;
+```
+
+## Props
+
+| Prop         | Default        | Purpose                                                        |
+| ------------ | -------------- | -------------------------------------------------------------- |
+| `items`      | —              | The queue items. The consumer keeps the state.                 |
+| `empty`      | —              | What to show for an empty queue. If omitted, nothing is shown. |
+| `aria-label` | "Upload queue" | The accessible name of the list.                               |
+
+An `UploadItem` has these fields: `id`, `name`, `size`, `preview`, `state`, `progress`,
+`statusLabel`, `tone`, `meta`, `actions`.
+
+## The kit has no transport
+
+Sending, retrying, canceling and polling jobs on the server are the consumer's
+concern: URLs, response formats and retry rules belong to the application.
+The kit provides the item shape, progress, states and the announcement of the outcome.
+
+This is the same division of responsibilities as with the table
+(ADR-0023): the kit
+provides the shape of the state; the consumer owns it. The decision on the queue is
+ADR-0027.
+
+## State is mechanics, label and tone are domain
+
+`state` takes four values: `pending`, `running`, `success`, `failed`. This
+describes what happened to the job, not the application domain — the same vocabulary as in `Timeline`. An
+unknown value (the backend added a fifth) does not break the queue: the
+tone falls back to neutral.
+
+"Duplicate", "Pending moderation", "Limit exceeded" are consumer labels; they arrive in
+`statusLabel` and are rendered as a badge. Making them kit states is not allowed: the
+kit does not know the application's domain (photos, publications). `StatusBadge` is built the same
+way: it was brought into the kit from the source app without a dictionary of 11 domain statuses.
+
+**`statusLabel` changes only the badge text, not its color.** The color is derived
+from `state`: `pending` is neutral, `running` is accent, `success` is green, `failed`
+is red. As long as the label agrees with the state ("Done" on `success`, "Queued" on
+`pending`), this is enough.
+
+### A domain status over the mechanical one: `tone`
+
+The label and the state diverge where the application knows more than the transport.
+An example is "Duplicate": the file reached the server, that is `state="success"`, but
+there is no good news, and a green badge would be misleading. For this an item
+has `tone` (`neutral | accent | success | warning | danger`) — it overrides the tone
+derived from `state`:
+
+```tsx
+const items: UploadItem[] = [
+  { id: "1", name: "report.pdf", state: "success", statusLabel: "Done" },
+  {
+    id: "2",
+    name: "report-copy.pdf",
+    state: "success",
+    statusLabel: "Duplicate",
+    tone: "warning",
+  },
+];
+```
+
+- **Without `tone` nothing changes:** the color still comes from `state`.
+- **`tone` colors the badge and the progress bar.** They sit in one row, and a
+  green bar next to a yellow "Duplicate" would send two different messages about one item.
+- **The `meta` text of a failed item ignores `tone`** — it follows `state`: the
+  sending failed, whatever the domain says. And conversely, a red `tone` on a
+  `success` item does not make it count as a failure: the outcome in the live region is
+  computed from `state`.
+- **The tone does not replace the label.** Color without a word is read neither by a
+  screen reader nor by a color-blind person: "Duplicate" stays in `statusLabel`, and
+  `tone` only decides which color it is shown in.
+- An unknown `tone` value (a typo, or a consumer dictionary that has drifted from the kit)
+  is ignored, as if it were not set: the tone is derived from `state`.
+
+The file size also comes **already formatted**: "2,4 МБ" and "2.4 MB" differ by more
+than the decimal separator, and the choice of units (MB or MiB) is the application's
+decision.
+
+## The outcome is announced, not only shown
+
+A partial success — "9 of 12 uploaded, 1 failed" — is visible to the eye by the color
+of the rows. A screen reader user who sent a dozen files will not learn about the
+single failed one at all unless it is announced.
+
+That is why under the list there is a live region that is **always mounted**: a region
+inserted into the document together with its message is announced unreliably — some
+screen readers manage to miss it. This is the same technique, used for the same reason, as in
+`FileDropzone`.
+
+Pluralization ("1 error", "2 errors") is done by the locale file through
+`Intl.PluralRules`: the locale knows the rules, not the component.
+
+## Progress: `null` is not zero
+
+`progress: null` means "the total amount of work is unknown": the bar shows indeterminate
+progress and `aria-valuenow` is absent. `progress: 0` means "started and nothing done yet".
+If `progress` is not set, there is no bar at all.
+
+The bar name is built from the file name: in a queue of a dozen rows the same
+"Uploading" on every row does not say which file it refers to.
+
+## Anti-patterns
+
+- Keeping the queue inside the component. It does not keep it — and will not:
+  the state belongs to whoever runs the sending.
+- Introducing a new `state` for a domain case instead of `statusLabel` and `tone`.
+- Leaving `statusLabel` empty so that a "Duplicate" badge does not turn green:
+  the color is set by `tone`, the label does not need to be touched for that.
+- Expressing meaning by color only: `tone` without `statusLabel` renders no badge at all,
+  and the color of the bar does not replace words.
+- Showing `progress: 0` where the length of the response is unknown: that is untrue.
+
+## Related sources and tests
+
+- Source: `src/components/inputs/UploadQueue.tsx`
+- Tests: `tests/upload-queue.test.tsx`
+- Showcase: `src/components/inputs/UploadQueue.stories.tsx`

package/docs/components/inputs/upload-queue.md

@@ -0,0 +1,158 @@
+---
+component: UploadQueue
+exports: [UploadQueue, UploadItem, ProgressStatus]
+category: inputs
+status: stable
+source: src/components/inputs/UploadQueue.tsx
+story: src/components/inputs/UploadQueue.stories.tsx
+---
+
+# UploadQueue
+
+## Кратко для AI
+
+Менеджер загрузок: что уже отправлено, что идёт и что упало. **Только
+представление** — транспорта в ките нет. Элементы и обработчики приходят
+пропами; итог очереди объявляется скринридеру живой областью.
+
+## Когда использовать
+
+- Пользователь отправляет несколько файлов и должен видеть, что стало с каждым.
+- Часть файлов может упасть, а часть — пройти: нужен частичный успех.
+- Нужны действия над элементом: повтор, отмена, убрать из очереди.
+
+## Когда не использовать
+
+- Для **выбора** файла используйте `FileDropzone`. Граница простая: область даёт
+  файлы, очередь показывает, что с ними стало. На экране они стоят рядом, и
+  путают их именно поэтому.
+- Для одного файла без прогресса и без ошибок — очередь из одной строки не
+  сообщает ничего, чего не сказало бы имя файла рядом с полем.
+- Для ленты уже завершённых событий используйте `Timeline`: там у шага нет действий,
+  а порядок задаёт процесс, а не пользователь.
+
+## Минимальный пример
+
+```tsx
+import { UploadQueue, type UploadItem } from "@olddevs/ui";
+
+const [items, setItems] = useState<UploadItem[]>([]);
+
+<UploadQueue items={items} empty={<EmptyState title="Очередь пуста" />} />;
+```
+
+## Пропы
+
+| Проп         | Умолчание          | Назначение                                                              |
+| ------------ | ------------------ | ----------------------------------------------------------------------- |
+| `items`      | —                  | Элементы очереди. Состояние хранит потребитель.                         |
+| `empty`      | —                  | Что показать при пустой очереди. Если не задан, ничего не показывается. |
+| `aria-label` | «Очередь загрузки» | Доступное имя списка.                                                   |
+
+Элемент (`UploadItem`): `id`, `name`, `size`, `preview`, `state`, `progress`,
+`statusLabel`, `tone`, `meta`, `actions`.
+
+## Транспорта в ките нет
+
+Отправка, повтор, отмена и опрос задач на сервере — знание потребителя: URL,
+формат ответов и правила повтора принадлежат приложению. Кит даёт форму
+элемента, прогресс, состояния и объявление итога.
+
+Это то же разделение обязанностей, что у таблицы
+(ADR-0023): кит
+даёт форму состояния, владеет им потребитель. Решение по очереди —
+ADR-0027.
+
+## Состояние — механика, подпись и тон — домен
+
+`state` принимает четыре значения: `pending`, `running`, `success`, `failed`.
+Это исход работы, а не предметная область — тот же словарь, что у `Timeline`.
+Незнакомое значение (бэкенд завёл пятое) не роняет очередь: тон выводится
+нейтральным.
+
+«Дубль», «На модерации», «Превышен лимит» — подписи потребителя, они приходят в
+`statusLabel` и рисуются бейджем. Заводить их состояниями кита нельзя: кит не знает
+предметной области приложения (фото, публикации). Так же устроен `StatusBadge`: его
+перенесли в кит из приложения-источника без словаря из 11 доменных статусов.
+
+**`statusLabel` меняет только текст бейджа, а не его цвет.** Цвет выводится из
+`state`: `pending` — нейтральный, `running` — акцентный, `success` — зелёный,
+`failed` — красный. Пока подпись согласуется с состоянием («Готово» на
+`success`, «В очереди» на `pending`), этого достаточно.
+
+### Доменный статус поверх механического: `tone`
+
+Подпись и состояние расходятся там, где приложение знает больше транспорта.
+Пример — «Дубль»: файл дошёл до сервера, то есть `state="success"`, но радоваться
+нечему, и зелёный бейдж был бы неправдой. Для этого у элемента есть `tone`
+(`neutral | accent | success | warning | danger`) — он перекрывает тон,
+выведенный из `state`:
+
+```tsx
+const items: UploadItem[] = [
+  { id: "1", name: "report.pdf", state: "success", statusLabel: "Готово" },
+  {
+    id: "2",
+    name: "report-copy.pdf",
+    state: "success",
+    statusLabel: "Дубль",
+    tone: "warning",
+  },
+];
+```
+
+- **Без `tone` ничего не меняется:** цвет по-прежнему идёт от `state`.
+- **`tone` красит бейдж и полосу прогресса.** Они стоят в одной строке, и
+  зелёная полоса рядом с жёлтым «Дубль» говорила бы об одном элементе два
+  разных слова.
+- **Текст `meta` упавшего элемента `tone` не учитывает** — он следует `state`:
+  отправка упала, что бы ни говорил домен. И наоборот, красный `tone` у
+  `success` не делает элемент сбоем: итог в живой области считается по `state`.
+- **Тон не заменяет подпись.** Цвет без слова не читается ни скринридером, ни
+  дальтоником: «Дубль» остаётся в `statusLabel`, а `tone` лишь решает, каким цветом он
+  показан.
+- Неизвестное значение `tone` (опечатка, словарь потребителя разошёлся с китом)
+  игнорируется, как незаданное: тон выводится из `state`.
+
+Размер файла тоже приходит **уже отформатированным**: «2,4 МБ» и «2.4 MB»
+отличаются не только разделителем, но и единицами (МБ или МиБ), а выбор единиц — решение приложения.
+
+## Итог объявляется, а не только показывается
+
+Частичный успех — «загружено 9 из 12, 1 ошибка» — виден глазами по цвету строк.
+Пользователь скринридера, отправив дюжину файлов, о единственной упавшей загрузке не
+узнает вовсе, если её не назвать.
+
+Поэтому под списком стоит живая область, **смонтированная всегда**: область,
+вставленная в документ вместе с сообщением, объявляется ненадёжно — часть
+скринридеров успевает её пропустить. Тот же приём и по той же причине, что в
+`FileDropzone`.
+
+Склонение («1 ошибка», «2 ошибки», «5 ошибок») делает файл локали через
+`Intl.PluralRules`: правила знает локаль, а не компонент.
+
+## Прогресс: `null` — не ноль
+
+`progress: null` означает «общий объём работы неизвестен»: полоса показывает неопределённый прогресс, а
+`aria-valuenow` отсутствует. `progress: 0` означает «начали и пока ничего не
+сделали». `progress` не задан — полосы нет вовсе.
+
+Имя полосы собирается из имени файла: в очереди из дюжины строк одинаковые
+«Загрузка» не говорят, о каком файле речь.
+
+## Антипаттерны
+
+- Хранить очередь внутри компонента. Он её не хранит — и не будет: состояние
+  принадлежит тому, кто ведёт отправку.
+- Заводить новое `state` под доменный случай вместо `statusLabel` и `tone`.
+- Не заполнять `statusLabel`, чтобы бейдж не стал зелёным у «Дубля»: цвет
+  задаёт `tone`, подпись для этого трогать не нужно.
+- Выражать смысл только цветом: `tone` без `statusLabel` бейджа не рисует вовсе,
+  а цвет полосы не заменяет слова.
+- Показывать `progress: 0` там, где длина ответа неизвестна: это неправда.
+
+## Связанные исходники и проверка
+
+- Исходник: `src/components/inputs/UploadQueue.tsx`
+- Тесты: `tests/upload-queue.test.tsx`
+- Витрина: `src/components/inputs/UploadQueue.stories.tsx`