@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/components/content/sortable-list.en.md

@@ -0,0 +1,212 @@
+---
+component: SortableList
+exports: [SortableList, SortableItem, SortableMove]
+category: content
+status: stable
+source: src/components/content/SortableList.tsx
+story: src/components/content/SortableList.stories.tsx
+sourceHash: 8d78d4e55246
+---
+
+# SortableList
+
+## Summary for AI
+
+A list whose order the user sets by dragging. It is built on react-aria's
+`useDragAndDrop`: announcements, keyboard and the insertion point come from
+there. The component does not store the order. Lists that share a `group`
+exchange rows — that is how a board is built: a move arrives in `onMove` of the
+receiving list, and the screen holds what each column contains.
+
+## When to use
+
+- The order matters and is set by a person: menu sections, scenario steps,
+  priority.
+- There are few items and they fit on the screen.
+- A board: column lists sharing a `group`, between which a row moves with the
+  mouse and from the keyboard.
+
+## When not to use
+
+- For sorting by a column value — that is `Table`: there the order is computed,
+  not assigned.
+- For hundreds of items: virtualization and dragging together are not verified
+  in the kit. A virtualized grid is `VirtualGrid`, and it has no dragging.
+- For a tree — that is `TreeView`.
+
+## Minimal example
+
+```tsx
+import { SortableList } from "@olddevs/ui";
+
+const [items, setItems] = useState([
+  { id: "1", label: "Overview" },
+  { id: "2", label: "Campaigns" },
+]);
+
+<SortableList
+  items={items}
+  aria-label="Section order"
+  onReorder={(ids) => setItems(ids.map((id) => items.find((i) => i.id === id)!))}
+/>;
+```
+
+## Props
+
+| Prop         | Default | Purpose                                                         |
+| ------------ | ------- | --------------------------------------------------------------- |
+| `items`      | —       | Rows: `id`, `label`, `textValue`.                               |
+| `onReorder`  | —       | The whole new order — a list of identifiers.                    |
+| `aria-label` | —       | **Required.** A nameless list is announced as empty.            |
+| `emptyText`  | —       | What to show when there are no rows.                            |
+| `group`      | —       | A group of lists that exchange rows.                            |
+| `id`         | —       | The list name in the group for `onMove`; not in the DOM.        |
+| `onMove`     | —       | Called when a row is brought in from another list of the group. |
+
+## The drag handle is required
+
+Every row has a handle button, and the component itself renders it rather than leaving it to the
+consumer. This was established by measurement: without
+`<Button slot="drag">`, the row gets `draggable="true"` and can be dragged with
+a mouse, **but cannot be picked up from the keyboard at all**. react-aria does
+not crash — it writes a warning to the console. So an inaccessible list looks
+like a working one.
+
+The handle name is only a verb ("Drag" in the default message catalog, `sortableList.drag`): the library appends the row label
+itself, and if we repeated it, we would hear it twice.
+
+## Keyboard
+
+| Key                   | What it does                           |
+| --------------------- | -------------------------------------- |
+| `→`                   | Moves focus from the row to the handle |
+| `Enter` on the handle | Starts the drag                        |
+| `↑` / `↓`             | Chooses the insertion point            |
+| `Enter`               | Applies                                |
+| `Escape`              | Cancels                                |
+| `Tab`                 | Goes to another list of the group      |
+
+The react-aria announcement suggests choosing a target with `Tab`. In a single
+short list, `Tab` moves focus out of the ring of targets and **cancels** the
+drag — verified in a browser; use the arrow keys. In a group, `Tab` goes to the
+next list, and `Enter` drops the row there — also verified in a browser.
+
+## There is no live region of its own
+
+react-aria announces the drag by itself and localizes the announcements. With the Russian locale,
+a measurement returned these announcements (translated): "Drag started. Press Tab to choose a
+target…", "Insert between Overview and Campaigns", "Drag finished".
+
+A live region of our own would duplicate these messages and conflict with them. The
+`DragAnnouncer` from the source app is not carried into the kit: it is
+written for `@dnd-kit`, which stays silent
+(ADR-0028).
+
+For the announcements to come in Russian, `UiProvider` must have `locale` set:
+it is what sets up react-aria's `I18nProvider`.
+
+## The order is not stored inside
+
+`onReorder` hands over the **whole new order**, not "what moved where": applying
+a ready list is simpler than rebuilding it from an event, and there is nowhere
+to go wrong. Responsibilities are split the same way as in table sorting
+(ADR-0023).
+
+## Moving between lists
+
+Lists that share a `group` exchange rows: board columns, "available" and
+"selected". A list without a group, as before, only reorders its own rows.
+
+```tsx
+import { SortableList, type SortableMove } from "@olddevs/ui";
+
+// What the columns contain is one piece of screen state: the row leaves `from`
+// and lands in `to` at `index` in a single step.
+const move = ({ id, from, to, index }: SortableMove) =>
+  setBoard((board) => moveRow(board, id, from, to, index));
+
+{
+  columns.map((column) => (
+    <SortableList
+      key={column.id}
+      id={column.id}
+      group="board"
+      aria-label={column.label}
+      items={column.items}
+      onReorder={(ids) => reorderIn(column.id, ids)}
+      onMove={move}
+    />
+  ));
+}
+```
+
+- Only a list with `onMove` takes rows; any list of the group can give them
+  away.
+- `onMove` is called on the **receiving** list and reports the row `id`, `from`,
+  `to` and `index` — the position in the receiving list. Within its own list `onReorder`
+  still works.
+- The component does not store what the lists contain, just as it does not store
+  the order: updating both lists is the screen's job: the board state is a single piece of
+  state, so the row must be removed from one list and added to the other in one
+  step.
+- An empty list takes a row dropped on the list itself — show `emptyText` in it
+  so it is clear where to drop.
+- Another group does not take the row: each group has its own drag data type.
+  The list does not take a file from the desktop either.
+- The list `id` is a state key, not an element `id`: it does not reach the DOM
+  and does not clash with the page.
+
+## The copy icon in WebKit: a known issue that cannot be fixed here
+
+In Safari and other WebKit builds, at the very start of a drag a system icon meaning "a copy
+will be made" — a green circle with a plus — appears for a fraction of a
+second. The list cannot copy rows, and nothing is copied: the icon is misleading.
+
+This cannot be fixed on the kit's or the consumer's side. The
+component declares the only allowed operation — `getAllowedDropOperations: () =>
+["move"]`. Measurements of both engines show that the declaration is applied:
+`effectAllowed` is written and read back as `move`, and react-aria additionally
+writes `dropEffect: move` on every `dragover` — 24 writes per drag, and both engines
+accept them. Chromium honors it: the target sees `move`, the drag ends with `move`,
+there is no icon.
+
+WebKit loses the declaration at the drag-session level and hands the target
+`all` — [bug 178058](https://bugs.webkit.org/show_bug.cgi?id=178058), known
+since 2017. `all` includes copying, and the operating system shows the "plus"
+until the first target overrides it. Hence the flicker: it is the gap between
+the platform's default and the first correction.
+
+**The reordering is still correct.** react-aria keeps the real set of operations
+in its own variable and intersects it with what the browser returned; this is
+its standard workaround for the same bug. Measured in WebKit: five rows before
+the drop, five after, and the order changed exactly as in Chromium. The row is
+not duplicated.
+
+What does not help (so you need not check it again):
+
+- **a custom drag preview** (`renderDragPreview`). The wrong value is visible in
+  the data contract, in the target's `effectAllowed`, not in the picture. The
+  preview does not affect the operation mask;
+- **not using `text/plain`**. The icon appears on the very first `dragenter` over
+  the list itself, before any text field on the page, and in Chromium it is
+  absent with the same `text/plain`;
+- **removing `getAllowedDropOperations`**. It makes things worse: copying would
+  then really be allowed, and the icon would become accurate.
+
+## Anti-patterns
+
+- Hiding the handle "to look cleaner": without it the list is inaccessible from
+  the keyboard.
+- Adding a live region of your own on top of the react-aria announcements.
+- Storing the order inside the component.
+- Moving a row between columns with your own menu instead of `group`: a menu is
+  fine as a fallback, but not as the only way.
+- Updating only the receiving list in `onMove`: the row ends up in two columns
+  at once.
+
+## Related sources and tests
+
+- Source: `src/components/content/SortableList.tsx`
+- Tests: `tests/sortable-list.test.tsx`; browser —
+  `tests-visual/interactions.spec.ts`
+- Showcase: `src/components/content/SortableList.stories.tsx`

package/docs/components/content/sortable-list.md

@@ -0,0 +1,206 @@
+---
+component: SortableList
+exports: [SortableList, SortableItem, SortableMove]
+category: content
+status: stable
+source: src/components/content/SortableList.tsx
+story: src/components/content/SortableList.stories.tsx
+---
+
+# SortableList
+
+## Кратко для AI
+
+Список, порядок которого задаёт пользователь перетаскиванием. Стоит на
+`useDragAndDrop` из react-aria: объявления, клавиатура и точка вставки — оттуда.
+Порядок компонент не хранит. Списки одной `group` обмениваются строками — так
+собирается доска: переезд приходит в `onMove` списка-приёмника, состав колонок
+держит экран.
+
+## Когда использовать
+
+- Порядок значим и задаётся человеком: разделы меню, шаги сценария, приоритет.
+- Элементов немного, и они помещаются на экран.
+- Доска: колонки-списки одной `group`, между которыми строку переносят мышью и с
+  клавиатуры.
+
+## Когда не использовать
+
+- Для сортировки по значению колонки — это `Table`: там порядок вычисляется, а
+  не назначается.
+- Для сотен элементов: виртуализация и перетаскивание вместе в ките не
+  проверены. Сетка с виртуализацией — `VirtualGrid`, перетаскивания в ней нет.
+- Для дерева — это `TreeView`.
+
+## Минимальный пример
+
+```tsx
+import { SortableList } from "@olddevs/ui";
+
+const [items, setItems] = useState([
+  { id: "1", label: "Обзор" },
+  { id: "2", label: "Кампании" },
+]);
+
+<SortableList
+  items={items}
+  aria-label="Порядок разделов"
+  onReorder={(ids) => setItems(ids.map((id) => items.find((i) => i.id === id)!))}
+/>;
+```
+
+## Пропы
+
+| Проп         | Умолчание | Назначение                                            |
+| ------------ | --------- | ----------------------------------------------------- |
+| `items`      | —         | Строки: `id`, `label`, `textValue`.                   |
+| `onReorder`  | —         | Новый порядок целиком — список идентификаторов.       |
+| `aria-label` | —         | **Обязателен.** Безымянный список объявляется пустым. |
+| `emptyText`  | —         | Что показать, когда строк нет.                        |
+| `group`      | —         | Группа списков, которые обмениваются строками.        |
+| `id`         | —         | Имя списка в группе для `onMove`; в DOM не попадает.  |
+| `onMove`     | —         | Строку принесли из другого списка группы.             |
+
+## Ручка перетаскивания обязательна
+
+У каждой строки есть кнопка-ручка, и её рисует сам компонент, а не потребитель
+по желанию. Причина измерена: без `<Button slot="drag">` строка
+получает `draggable="true"` и таскается мышью, **а с клавиатуры не берётся
+вообще**. react-aria при этом не падает — она пишет предупреждение в консоль. То
+есть недоступный список выглядит рабочим.
+
+Имя ручки — только глагол (в русском каталоге «Перетащить», `sortableList.drag`): подпись строки библиотека дописывает
+сама, и повторив её, мы услышали бы её дважды.
+
+## Клавиатура
+
+| Клавиша          | Что делает                         |
+| ---------------- | ---------------------------------- |
+| `→`              | Переводит фокус со строки на ручку |
+| `Enter` на ручке | Начинает перетаскивание            |
+| `↑` / `↓`        | Выбирает точку вставки             |
+| `Enter`          | Применяет                          |
+| `Escape`         | Отменяет                           |
+| `Tab`            | Переходит к другому списку группы  |
+
+Объявление react-aria предлагает выбирать цель по `Tab`. В одиночном коротком
+списке `Tab` уводит фокус из кольца целей и **отменяет** перетаскивание —
+проверено в браузере; ходите стрелками. В группе `Tab` ведёт к следующему
+списку, и `Enter` кладёт строку туда — это тоже проверено в браузере.
+
+## Своей живой области нет
+
+react-aria объявляет перетаскивание сама и локализованно. Под русской локалью
+замер дал: «Начато перетаскивание. Нажмите клавишу Tab для выбора цели…»,
+«Вставить между Обзор и Кампании», «Перетаскивание завершено».
+
+Своя живая область дублировала бы эти строки и спорила бы с ними. `DragAnnouncer`
+из приложения-источника в кит не поднимается: он написан под `@dnd-kit`,
+который молчит
+(ADR-0028).
+
+Чтобы объявления пришли по-русски, у `UiProvider` должна быть задана `locale`:
+именно она разворачивает `I18nProvider` react-aria.
+
+## Порядок не хранится внутри
+
+`onReorder` отдаёт **весь новый порядок**, а не «что куда переехало»: применить
+готовый список проще, чем восстановить его из события, и ошибиться негде. Обязанности
+разделены так же, как у сортировки таблицы
+(ADR-0023).
+
+## Перенос между списками
+
+Списки с одной `group` обмениваются строками: колонки доски, «доступные» и
+«выбранные». Список без группы, как и прежде, только переставляет свои строки.
+
+```tsx
+import { SortableList, type SortableMove } from "@olddevs/ui";
+
+// Состав колонок — одно состояние экрана: строка уходит из `from`
+// и встаёт в `to` на `index` за один шаг.
+const move = ({ id, from, to, index }: SortableMove) =>
+  setBoard((board) => moveRow(board, id, from, to, index));
+
+{
+  columns.map((column) => (
+    <SortableList
+      key={column.id}
+      id={column.id}
+      group="board"
+      aria-label={column.label}
+      items={column.items}
+      onReorder={(ids) => reorderIn(column.id, ids)}
+      onMove={move}
+    />
+  ));
+}
+```
+
+- Принимает строки только список с `onMove`; отдавать их умеет любой список
+  группы.
+- `onMove` вызывается у списка-**приёмника** и сообщает `id` строки, `from`,
+  `to` и `index` — место в приёмнике. Внутри своего списка по-прежнему работает
+  `onReorder`.
+- Состав списков компонент не хранит, как и порядок: обновлять оба списка — дело
+  экрана: состояние доски одно, поэтому строку нужно убрать из одного списка и
+  поставить в другой за один шаг.
+- Пустой список принимает строку броском на сам список — покажите в нём
+  `emptyText`, чтобы было видно, куда бросать.
+- Чужая группа строку не примет: у каждой группы свой тип данных
+  перетаскивания. Файл с рабочего стола список тоже не возьмёт.
+- `id` списка — ключ состояния, а не `id` элемента: в DOM он не попадает и со
+  страницей не столкнётся.
+
+## Значок копирования в WebKit: известное, чинить нечем
+
+В Safari и других сборках WebKit в самом начале перетаскивания на долю секунды
+появляется системная иконка «будет создана копия» — зелёный кружок с плюсом.
+Список копировать строки не умеет, и ничего не копируется: иконка врёт.
+
+Починить это со стороны кита или потребителя нельзя. Компонент
+объявляет единственную разрешённую операцию — `getAllowedDropOperations: () =>
+["move"]`. Замер обоих движков показывает, что объявление применяется:
+`effectAllowed` записывается и читается обратно как `move`, а react-aria вдобавок
+пишет `dropEffect: move` на каждом `dragover` — 24 записи за одно перетаскивание,
+и в обоих движках они принимаются. Chromium это соблюдает: приёмник видит `move`, перетаскивание
+заканчивается с `move`, иконки нет.
+
+WebKit теряет объявление на уровне сессии перетаскивания и отдаёт приёмнику
+`all` — [баг 178058](https://bugs.webkit.org/show_bug.cgi?id=178058), известный
+с 2017 года. `all` включает копирование, и операционная система рисует «плюс»,
+пока первый же приёмник не переубедит её обратно. Отсюда и мелькание: это окно
+между чужим умолчанием и первой поправкой.
+
+**Перестановка при этом верна.** react-aria держит настоящий набор операций в
+своей переменной и пересекает его с тем, что вернул браузер; это его штатный
+обход того же бага. Замер в WebKit: пять строк до броска, пять после, порядок
+изменился ровно так же, как в Chromium. Строка не удваивается.
+
+Что не помогает (проверять заново не нужно):
+
+- **своё превью перетаскивания** (`renderDragPreview`). Неверное значение видно
+  в контракте данных, в `effectAllowed` у приёмника, а не в картинке. Превью
+  на маску операций не влияет;
+- **отказ от `text/plain`**. Значок появляется на первом же `dragenter` по самому
+  списку, до любого текстового поля на странице, а в Chromium с тем же
+  `text/plain` его нет;
+- **снятие `getAllowedDropOperations`**. Сделает хуже: тогда копирование будет
+  разрешено уже по-настоящему, и иконка станет правдой.
+
+## Антипаттерны
+
+- Прятать ручку «чтобы было чище»: без неё список недоступен с клавиатуры.
+- Заводить свою живую область поверх объявлений react-aria.
+- Хранить порядок внутри компонента.
+- Переносить строку между колонками своим меню вместо `group`: меню годится как
+  запасной путь, но не как единственный.
+- Обновлять в `onMove` только список-приёмник: строка окажется в двух колонках
+  сразу.
+
+## Связанные исходники и проверка
+
+- Исходник: `src/components/content/SortableList.tsx`
+- Тесты: `tests/sortable-list.test.tsx`; браузер —
+  `tests-visual/interactions.spec.ts`
+- Витрина: `src/components/content/SortableList.stories.tsx`

package/docs/components/content/tag-group.en.md

@@ -0,0 +1,158 @@
+---
+component: TagGroup
+exports: [TagGroup, Tag, TagGroupProps, TagProps, TagKey]
+category: content
+status: stable
+source: src/components/content/TagGroup.tsx
+story: src/components/content/TagGroup.stories.tsx
+sourceHash: 013dd9293b63
+---
+
+# TagGroup and Tag
+
+## Summary for AI
+
+A set of tags **for display**: post categories, projects, labels. A tag can be
+given a palette hue (`hue` — a dot next to the label), turned into a link (`href`)
+and made removable through a single handler (`onRemove`). It is built on `TagGroup` from
+`react-aria-components`: arrow keys between tags, Delete and Backspace, and focus
+after removal all come from it. There is no selection.
+
+## When to use
+
+- To show the categories, projects or labels of a post next to its content.
+- A tag is a link to the list of posts in that category.
+- An edit form where the user removes tags and another element adds them.
+- A hue from the tag palette (`LABEL_HUES`) is needed next to the label.
+
+## When not to use
+
+- The tag is chosen or toggled, like a filter — that is `Chip` or `Segmented`.
+  `selectionMode` is intentionally not passed through on `TagGroup`.
+- The tag expresses the state of an object (active, error, draft) — that is
+  `StatusBadge` or `Badge`: with a tag the meaning is supplied by a person, with a
+  status by the system.
+- The user types new tags as text — that is `TagInput`. They share the tag's look.
+- You only need a color swatch with no label — that is `SwatchGroup`.
+
+## Minimal example
+
+```tsx
+import { Tag, TagGroup } from "@olddevs/ui";
+
+<TagGroup label="Categories">
+  <Tag id="design" hue="teal">
+    Design
+  </Tag>
+  <Tag id="docs" href="/posts?category=docs">
+    Documentation
+  </Tag>
+</TagGroup>;
+```
+
+Removal and an empty group:
+
+```tsx
+const [tags, setTags] = useState(["design", "docs"]);
+
+<TagGroup
+  aria-label="Post categories"
+  onRemove={(keys) => setTags((current) => current.filter((tag) => !keys.has(tag)))}
+  empty="No categories"
+>
+  {tags.map((tag) => (
+    <Tag key={tag} id={tag}>
+      {NAMES[tag]}
+    </Tag>
+  ))}
+</TagGroup>;
+```
+
+## Public API
+
+`TagGroup`:
+
+| Prop              | Default | Purpose                                                                                                                                                                                                                                                                      |
+| ----------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`           | —       | The visible label of the group. **The name comes from exactly one source**: `label`, `aria-label` or `aria-labelledby` — TypeScript does not accept a group without a name (including one with `label` equal to `undefined`, `null` or `false`) or with two sources at once. |
+| `aria-label`      | —       | The group's name without a visible label.                                                                                                                                                                                                                                    |
+| `aria-labelledby` | —       | A name taken from a heading elsewhere on the page — the heading's `id`.                                                                                                                                                                                                      |
+| `onRemove`        | —       | `(keys: Set<TagKey>) => void`. When set, tags have remove buttons and Delete/Backspace work.                                                                                                                                                                                 |
+| `empty`           | —       | What to show when there are no tags. Without it an empty group looks like a failure.                                                                                                                                                                                         |
+| `className`       | —       | The root class; `ref` goes to the group's root.                                                                                                                                                                                                                              |
+
+`Tag`:
+
+| Prop        | Default | Purpose                                                                                |
+| ----------- | ------- | -------------------------------------------------------------------------------------- |
+| `id`        | —       | The tag's key: `onRemove` receives it. Set it for removable sets.                      |
+| `hue`       | —       | A hue from `LABEL_HUES`: a dot next to the label. If not set, there is no dot.         |
+| `href`      | —       | The tag becomes a link. Also `target` and `rel`.                                       |
+| `textValue` | —       | The tag's text for its name. Required if the content is neither a string nor a number. |
+| `children`  | —       | The tag's label.                                                                       |
+
+Tags wrap to a new line one whole tag at a time. The group does not store state
+(the set of tags): the consumer removes a tag by re-rendering the group.
+
+## The hue is a dot next to the label
+
+`hue` renders a 10-pixel circle to the left of the label. There is no fill under
+the text, and this is a decision of the tag palette: eight hues that are
+readable under text in all three themes would require twice as many colors, and
+the consumer's request explicitly allowed the "dot and label side by side"
+pair. A fill class from outside is not accepted — the hue is taken from a closed
+vocabulary.
+
+The dot is invisible to the screen reader (`aria-hidden`): a hue does not replace
+a word. The meaning of the tag is carried by its text — otherwise a person with a
+color vision deficiency could not tell tags apart.
+
+## A tag as a link
+
+`href` makes the tag a link: Enter and a click open the URL. react-aria does
+not render an `<a>` — it stores the URL in `data-href` and opens it on press,
+so that the tag stays a row of the group with arrow keys and removal. The trade-off: there is
+no "Open in a new tab" context menu. For client-side routing, wrap the app in
+`RouterProvider` from `react-aria-components`.
+
+## Accessibility and keyboard
+
+| Key                    | What it does                                  |
+| ---------------------- | --------------------------------------------- |
+| `←` / `→`              | Move between tags                             |
+| `Delete` / `Backspace` | Remove the focused tag (if `onRemove` is set) |
+| `Enter`                | Opens the link of a tag with `href`           |
+
+- After removal, focus stays in the group, on a neighboring tag.
+- The group's role is `grid`, the tags' is `row`; the group's name is required. A
+  visible label together with `aria-label` is forbidden by the type: the
+  attribute would override the on-screen text, and a screen reader would announce a different
+  group name
+  ([naming rule](../../conventions.md#доступное-имя)).
+- **The remove button's name comes from the message catalog, with the tag's
+  label inside** (`Remove: Design`; the key is `tagGroup.remove`). The label
+  is written into the string because word order depends on the language; that is
+  why the button has an empty `aria-labelledby` — otherwise react-aria would
+  append the tag's label a second time.
+- The remove button is a react-aria `Button` with `slot="remove"`, not a
+  `<button>`: the behavior comes through react-aria's context.
+
+## Anti-patterns
+
+- Filling the tag with the hue color under the text: contrast in the three themes
+  is not guaranteed.
+- Making tags selectable: `Chip` and `Segmented` are for that.
+- Passing non-text content without `textValue`: the tag and its remove button have
+  no name.
+- Conveying meaning by hue ("red means error"): palette hues are not tones, and
+  status is `StatusBadge`.
+- Building the remove button by hand: Delete/Backspace and focus return are lost.
+
+## Related sources and tests
+
+- Source: `src/components/content/TagGroup.tsx`; the shared tag look is in
+  `src/lib/tag.ts` (`TagInput` uses it too)
+- Hue palette: `LABEL_HUES`, `LABEL_BG_CLASS` — [`docs/palette.md`](../../palette.md)
+- Tests: `tests/tag-group.test.tsx`
+- Showcase: `src/components/content/TagGroup.stories.tsx`
+- Neighbors: [TagInput](../inputs/tag-input.md), [SwatchGroup](../inputs/swatch-group.md), [Chip](../actions/chip.md)