@olddevs/ui 0.0.0-stage → 4.0.1

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

@@ -0,0 +1,418 @@
+---
+component: EditableList
+exports: [EditableList, EditableListItem]
+category: content
+status: stable
+source: src/components/content/EditableList.tsx
+story: src/components/content/EditableList.stories.tsx
+---
+
+# EditableList
+
+## Кратко для AI
+
+Список, в котором строки правят по месту и переставляют перетаскиванием, а новые
+добавляют снизу. Ни порядок, ни значения компонент **не хранит**: черновики
+живут в самих полях, значения меняются только при выходе из режима правки.
+
+## Когда использовать
+
+- Список, который человек и правит, и пополняет, не выходя из него: задачи,
+  чек-лист, пункты сценария.
+- Порядок значим и задаётся человеком, а не вычисляется.
+
+## Когда не использовать
+
+- Нужен **только** порядок — это `SortableList`: он проще, и его строка не
+  умеет ничего лишнего.
+- Порядок вычисляется из значения колонки — это `Table` и `DataTable`
+  (ADR-0023).
+- Нужна вложенность — это `TreeView`.
+- Сотни строк: виртуализация и перетаскивание вместе в ките не проверены
+  (ADR-0028).
+
+## Минимальный пример
+
+```tsx
+import { EditableList } from "@olddevs/ui";
+
+const [items, setItems] = useState([
+  { id: "1", value: "Согласовать смету" },
+  { id: "2", value: "Оплатить хостинг" },
+]);
+
+<EditableList
+  items={items}
+  aria-label="Задачи"
+  editLabel={(item) => `Изменить «${item.value}»`}
+  onReorder={(ids) => setItems(ids.map((id) => items.find((i) => i.id === id)!))}
+  onValueChange={(id, value) =>
+    setItems(items.map((item) => (item.id === id ? { ...item, value } : item)))
+  }
+  add={{
+    label: "Новая задача",
+    placeholder: "Что нужно сделать?",
+    onAdd: (value) => setItems([...items, { id: crypto.randomUUID(), value }]),
+  }}
+/>;
+```
+
+## Пропы
+
+| Проп            | Умолчание | Назначение                                                                                                                                                                                |
+| --------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `items`         | —         | Строки: `id`, `value`, `textValue`, `disabled`.                                                                                                                                           |
+| `onReorder`     | —         | Новый порядок целиком — список идентификаторов.                                                                                                                                           |
+| `onValueChange` | —         | Подтверждение правки. Вызывается, **только** когда значение изменилось.                                                                                                                   |
+| `editLabel`     | —         | Доступное имя поля правки. **Обязателен**, проверяет компилятор.                                                                                                                          |
+| `aria-label`    | —         | **Обязателен.** У списка без названия скринридер объявит просто «список».                                                                                                                 |
+| `add`           | —         | Строка добавления: `label`, `placeholder`, `onAdd`, `pending`, `leading`. `pending` объявляет занятость через `aria-busy` и поле **не** выключает; `leading` — ведущие колонки, см. ниже. |
+| `leading`       | —         | Слот слева от названия: флажок, аватар.                                                                                                                                                   |
+| `trailing`      | —         | Слот справа: бейдж состояния, кнопки действий строки.                                                                                                                                     |
+| `onRowAction`   | —         | Щелчок по строке и пробел на ней. Компонент их не трактует.                                                                                                                               |
+| `divided`       | —         | Волосяная линия между строками.                                                                                                                                                           |
+| `emptyText`     | —         | Что показать при пустом списке.                                                                                                                                                           |
+
+## Почему это отдельный компонент, а не `SortableList` с полем внутри
+
+Разбор — ADR-0045.
+
+Строка `SortableList` — `GridListItem`, и клавиатура принадлежит ей: стрелки,
+Enter, пробел, набор по первым буквам. Поле внутри строки забирает те же клавиши
+себе. Владелец контракта должен быть один, и композицией его не получить.
+
+Вторая причина — строка добавления: она **не элемент коллекции**, у неё нет ни
+ключа, ни места в порядке. Переход фокуса в неё с последней строки и обратно —
+поведение, у которого при композиции не остаётся хозяина.
+
+## Хэндл фокуса
+
+Компонент отдаёт наружу один императивный хэндл:
+
+```tsx
+const list = useRef<EditableListHandle>(null);
+
+<EditableList ref={list} add={{ label, placeholder, onAdd }} … />;
+
+list.current?.focusAdd();                  // курсор в строку добавления
+list.current?.focusAdd({ select: true });  // и выделить набранное
+```
+
+Он нужен, когда курсор ставят снаружи: палитра команд, горячая клавиша
+«новый элемент», шаг мастера «исправьте вот это поле».
+
+**Строки добавления нет — вызов молча ничего не делает.** Молча, а не
+исключением: вызывающий приходит из палитры и как раз не хочет знать, в каком
+состоянии список; исключение здесь означало бы проверку в каждом
+вызове.
+
+**Хэндл узкий намеренно.** Сам `HTMLInputElement` наружу не отдаётся: отдай его
+— и разметка строки добавления станет публичным контрактом, а потребитель
+начнёт читать `value` и вешать обработчики.
+
+**При монтировании его вызывать нельзя.** Автофокус при открытии экрана
+неожиданно уводит пользователя скринридера. Вызов по команде человека такой
+проблемы не создаёт.
+
+Прокрутка отдельным пропом не управляется: `focus()` сам приводит поле на
+экран, и умолчание здесь правильное.
+
+## Разделение строк
+
+По умолчанию ряд держится отступами. На плотном списке этого мало: строки
+читаются сплошным полотном, и опорой остаются только плашки ручек.
+
+`divided` ставит между строками волосяную линию `line-soft`. Линия идёт
+**между** строками, а не под каждой: под последней она подчеркнула бы список,
+которого никто не подчёркивал. Скругление строки при этом снимается — под
+скруглённой строкой прямая линия загибается по углам и перестаёт быть прямой, —
+а подсветка по наведению становится полосой во всю ширину, как и принято у
+разделённого списка.
+
+Подложки с рамкой у строки компонент не умеет, хотя способ разбить ряд есть и
+такой. Этот способ рассмотрели и отклонили: строки-карточки читаются тяжелее,
+восемь задач превращаются в восемь карточек. Новый проп на будущее не заводится:
+API, который никто не просил, всё равно придётся поддерживать
+(ADR-0031).
+
+## Уход строки
+
+Строка, пропавшая из `items`, не снимается с экрана в тот же кадр: она доживает
+свой уход, и место под ней освобождается **тем же движением**. Ступень `base`,
+кривая `ease-exit` — то же, чем уходят оверлеи кита с 3.23.
+
+Довод тот же, что и у оверлеев: исчезновение за один кадр читается как сбой. У строки
+списка цена выше — она исчезает не одна: соседние смыкаются мгновенно, и вместе
+с ними подпрыгивает всё, что ниже. Человек отметил задачу выполненной, а список
+под курсором дёрнулся, и следующая строка оказалась под указателем
+раньше, чем он понял, какая ушла.
+
+**Пропа у этого нет и не предполагается.** Уход включён всегда, как у оверлеев:
+проп вида «анимировать удаление» означал бы, что у кита есть мнение, в каких
+списках строка может пропадать рывком. Длительность и кривая наружу тоже не
+выносятся — они принадлежат шкале движения
+(ADR-0047).
+
+**Уходящая строка неживая с первого кадра.** На ней стоит
+`inert`, и это снимает разом всё: она не перетаскивается и не принимает
+перетаскиваемое, не получает фокус, не реагирует на щелчок и `Enter`, не
+попадает в дерево доступности. В `onReorder` её идентификатор не приходит — для
+порядка она уже не существует. Для незрячего запись исчезла в момент действия, и
+держать её в дереве лишние 150 мс незачем.
+
+**Фокус уходит вперёд.** Если фокус стоял на уходящей строке, он переходит на
+ту, что заняла её место; если такой нет — на предыдущую; если списка не
+осталось — в строку добавления. Оставить фокус на уходящей строке нельзя: она
+`inert`, фокус провалился бы в `body`, и клавиатурная работа обрывалась бы на
+каждой выполненной задаче.
+
+**Несколько строк уходят одновременно**, без волны с задержками: массовое
+действие снимает десяток, и волна превратилась бы в заметное ожидание, ничего
+при этом не сообщая.
+
+**При `prefers-reduced-motion: reduce` уход остаётся, смыкание снимается.**
+Остаётся прозрачность, а место освобождается в один кадр: смыкание — это
+движение всего, что ниже строки, то есть то, от чего настройка и защищает.
+Совсем гасить уход нельзя по общему доводу
+ADR-0043: `animation: none` даёт не
+покой, а рывок.
+
+Две оговорки на случай гонок у потребителя:
+
+- **Вернувшийся идентификатор немедленно снимает свою уходящую строку** — двух
+  строк с одним `id` в коллекции не бывает. Отмена удаления, пришедшая в те же
+  150 мс, показывает строку, а не её копию.
+- **Сброс ровно на место уходящей строки не делает ничего.** Цель сброса — ключ,
+  которого в `items` уже нет, и `onReorder` не вызывается: порядок не меняется
+  вместо того, чтобы измениться неверно.
+
+Уход **не парный**: приход строки не анимируется. Добавление идёт из строки
+добавления, человек смотрит на неё, и движение в списке там было бы шумом.
+
+## Выравнивание строки добавления
+
+Поле добавления должно начинаться там же, где начинаются названия строк. Место
+ручки перетаскивания компонент резервирует сам — для списка без `leading` этого
+достаточно, и рамка поля совпадает с названиями из коробки.
+
+Со слотом `leading` выравнивание разъезжается: флажок или аватар сдвигают названия
+вправо, а поле за ними не идёт. Ширину `leading` кит знать не может — её задаёт
+потребитель, и замерять чужую разметку значило бы читать раскладку в каждом
+рендере и всё равно промахиваться на первом кадре. Поэтому колонку сообщает
+тот, кто её создал: `add.leading`.
+
+```tsx
+add={{
+  label: "Новая задача",
+  onAdd: create,
+  // Тот же флажок, что в строке, но невидимый.
+  leading: (
+    <span className="invisible shrink-0">
+      <Checkbox size="sm" checked={false} label="" onCheckedChange={() => {}} />
+    </span>
+  ),
+}}
+leading={(item) => <Checkbox size="sm" checked={item.done} … />}
+```
+
+**Зеркало надёжнее распорки на глаз.** Соблазн поставить `<span
+className="size-4" />` под флажок `sm` понятен, но такая распорка промахивается на 8 пикселей:
+рамка у флажка действительно 16 пикселей, но занимает он 24 — подпись-обёртка добавляет
+свои отступы. Невидимая копия того же контрола держит геометрию сама и не
+разъедется, когда контрол в ките изменится.
+
+**`invisible`, а не `opacity-0` и не `aria-hidden` на живом контроле.**
+`visibility: hidden` сохраняет коробку целиком, но убирает элемент и из порядка
+обхода, и из дерева доступности. Живой флажок в строке добавления — это флажок
+у задачи, которой ещё нет: отмечать нечего, а фокус он бы забирал.
+
+Распорка фиксированной ширины тоже годится — когда ширина известна точно и
+на её месте не контрол кита: `<span aria-hidden className="size-6 shrink-0" />`.
+
+## Строка — группа: содержимое слотов видит наведение и фокус
+
+Строка выставляет Tailwind-маркер `group`. Это **часть контракта**: содержимое `leading` и `trailing` вправе опираться на `group-hover:` —
+кит обещает, что маркер на строке есть и останется
+(ADR-0046). Снять или
+переименовать его теперь можно только мажором.
+
+Рецепт целиком — история `HoverActions` в витрине; она же и проверяется
+браузерным тестом, чтобы пример здесь не испортился молча.
+
+```tsx
+<EditableList
+  items={tasks}
+  trailing={(item) => (
+    <span className="flex items-center gap-1 transition-opacity duration-150 pointer-fine:opacity-0 pointer-fine:group-hover:opacity-100 pointer-fine:focus-within:opacity-100">
+      <Button size="xs" iconOnly icon={<TrashIcon />} aria-label={`Удалить ${item.value}`} />
+    </span>
+  )}
+  {...rest}
+/>
+```
+
+**`focus-within:` — на вашей обёртке, без `group-`.** Это единственный
+работающий вариант, и стоит он здесь вместо `group-focus-within:`, который в
+рецепте до 3.17.2 не срабатывал никогда. Причина: строка — компонент react-aria
+и несёт `data-rac`. Плагин `tailwindcss-react-aria-components` метит такие
+элементы не псевдоклассом, а атрибутом: `:where([data-rac])[data-focus-within]`. Атрибута `data-focus-within`
+строка не выставляет: при фокусе внутри себя она ставит `data-focused` и
+`data-focus-visible-within`. Обёртка вокруг кнопок `data-rac` не несёт, попадает
+в ветку селектора для элементов без `data-rac` и работает обычным CSS.
+
+На `data-focused` рецепт опираться не стал намеренно: атрибут появляется не при
+всяком способе привести фокус внутрь строки, а признак, который иногда есть, для
+такой задачи хуже, чем никакого.
+
+**Реакция на фокус обязательна, наведение — в дополнение к ней.** Одно наведение
+прячет кнопку от клавиатуры: фокус придёт на невидимый элемент, и человек будет
+нажимать вслепую. Если из пары остаётся одна утилита, это `focus-within:`.
+
+**`pointer-fine:` обязателен.** Там, где нет точного указателя, `:hover` либо не
+случается вовсе, либо залипает после касания. Спрятанная за наведением кнопка на
+таком устройстве становится недостижимой. Прячьте только при точном указателе,
+на касании оставляйте видимой.
+
+Вариант встроен в Tailwind, заводить его у себя не нужно: проверено на сборке
+Tailwind 4.3.3 без единого `@custom-variant` — правила выходят обёрнутыми в
+`@media (pointer: fine)`. Если в вашей сборке они пропадают, дело в версии
+Tailwind, а не в поставке кита: неизвестный вариант Tailwind не порождает, и
+класс исчезает молча, а сборка остаётся зелёной.
+
+**Свой `group` внутри слота затеняет строку.** Безымянный `group-hover:`
+реагирует на ближайшего предка с маркером, и если этот предок ваш, на строку он
+уже не реагирует. Кит маркер не именует намеренно — переименование сломало бы то, что
+обещано, — поэтому имя заводите у себя: `group/actions` плюс
+`group-hover/actions:`.
+
+Умолчание кит не меняет: содержимое слотов видно всегда. Прятать действия —
+продуктовое решение, его принимает потребитель, а не проп
+компонента.
+
+## Клавиатура
+
+| Клавиша                     | Что делает                                            |
+| --------------------------- | ----------------------------------------------------- |
+| `↑` / `↓`                   | Фокус по строкам                                      |
+| набор букв                  | Переход к строке по началу названия                   |
+| `→`                         | Фокус со строки на ручку                              |
+| `Enter` на ручке            | Начинает перенос; `↑`/`↓` — цель, `Enter` — применить |
+| `Enter` на строке           | Открывает правку; текст выделен целиком               |
+| двойной щелчок              | То же мышью                                           |
+| `Enter` в поле              | Подтверждает и возвращает фокус на строку             |
+| `Escape` в поле             | Возвращает прежнее значение **и** фокус на строку     |
+| щелчок мимо                 | Подтверждает и фокус **не** забирает                  |
+| `↓` с последней строки      | Переводит фокус в строку добавления                   |
+| `↑` в строке добавления     | Возвращает фокус на последнюю строку                  |
+| `Enter` в строке добавления | Подтверждает и **оставляет поле открытым**            |
+
+Пока строка в правке, ручка выключена и тащить строку нельзя: стрелки
+принадлежат каретке.
+
+`Enter` разбирается компонентом, только когда в фокусе **сама строка**. На
+ручке, на флажке в `leading` и на кнопках в `trailing` он принадлежит им: до
+3.10.2 перехват ловил его на любом потомке строки, и перенос с клавиатуры не
+начинался никогда.
+
+## Мышь
+
+| Элемент             | Что происходит                                           |
+| ------------------- | -------------------------------------------------------- |
+| ручка (шесть точек) | Курсор «схватить»; зажать и вести — перенос              |
+| название            | Двойной щелчок открывает правку; одиночный не трактуется |
+| строка              | Щелчок и пробел — `onRowAction`, если он задан           |
+
+Курсор захвата стоит на **обёртке** ручки, а не на самой кнопке переноса.
+react-aria ставит кнопке `pointer-events: none` (она цель для клавиатуры и
+скринридера, а не для указателя), и курсор на ней не применялся бы никогда.
+По той же причине обёртка гасит щелчок: сквозь выключенную для указателя
+кнопку он попадал в строку и звал `onRowAction`.
+
+### Чего компонент не умеет при работе мышью
+
+**Тащится вся строка, а не ручка, и название мышью не выделяется.** Причина у
+обоих одна: перенос ведёт react-aria нативным `draggable` на самой строке
+(ADR-0028), а браузер применяет к `[draggable=true]` правило
+`user-select: none`. Поэтому протяжка по названию не выделяет его, а
+переставляет строку; `user-select: text` на названии не помогает, пока
+`draggable` стоит на предке.
+
+Обойти это, не отказавшись от react-aria в переносе, нечем: цена — своя
+реализация перетаскивания в ките. Никто эту реализацию не просил, и список живёт так
+с 3.10.0, с первого выпуска.
+
+## Три вещи, которые видно только в браузере
+
+Все три найдены при сборке компонента, и все тихие: в jsdom коллекция
+react-aria ведёт себя иначе, и тест прошёл бы на сломанном компоненте.
+
+- **`dependencies={[editingId, leaving]}` у `GridList` обязателен.** Коллекция кеширует
+  строки и не перерисовывает их на смену внешнего состояния — без этого правка
+  не открывалась вовсе, при исправно отрабатывающем обработчике клавиш.
+- **Фокус ставится в callback-ref, а не в эффекте.** Содержимое строки
+  монтируется отдельным проходом, позже коммита: к моменту `useLayoutEffect`
+  реф поля ещё пуст.
+- **Черновики живут в самих полях.** Черновик в состоянии означал бы рендер на
+  каждое нажатие, а значит — перемонтирование строки и возврат исходного
+  значения: набранное стиралось прямо во время набора.
+
+## Доступность
+
+- Список — `GridList` из react-aria. Объявления о переносе даёт она сама и
+  локализованно; своей живой области у компонента нет.
+- Строка с пустым значением получает имя из подписи-заглушки: пустое
+  `textValue` react-aria встречает предупреждением в консоль, и до такой строки
+  не добраться набором по первым буквам.
+- Появление добавленной строки компонент **не объявляет** — строка приходит
+  пропом из коллекции, и объявление остаётся за потребителем.
+
+## Иконка копирования в WebKit: известная проблема, исправить нечем
+
+В Safari и других сборках WebKit в самом начале перетаскивания на долю секунды
+появляется системная иконка «будет создана копия» — зелёный кружок с плюсом.
+Список копировать строки не умеет, и ничего не копируется: иконка врёт.
+
+Ни кит, ни потребитель починить это не могут, и вот почему. Компонент
+объявляет единственную разрешённую операцию — `getAllowedDropOperations: () =>
+["move"]`. Замер обоих движков показывает, что объявление применяется:
+`effectAllowed` записывается и читается обратно как `move`, а react-aria вдобавок
+пишет `dropEffect: move` на каждом `dragover` — 24 записи за одно перетаскивание,
+и принимаются обе: и `effectAllowed`, и `dropEffect`. Chromium это соблюдает: приёмник видит `move`, перетаскивание
+заканчивается с `move`, иконки нет.
+
+WebKit теряет объявление на уровне сессии перетаскивания и отдаёт приёмнику
+`all` — [баг 178058](https://bugs.webkit.org/show_bug.cgi?id=178058), известный
+с 2017 года. `all` включает копирование, и операционная система рисует «плюс»,
+пока первый же приёмник не переубедит её обратно. Отсюда и мелькание: это окно
+между умолчанием WebKit и первой поправкой.
+
+**Перестановка при этом верна.** react-aria держит настоящий набор операций в
+своей переменной и пересекает его с тем, что вернул браузер. Это штатный
+обход react-aria для того же бага. Замер в WebKit: пять строк до сброса, пять после, порядок
+изменился ровно так же, как в Chromium. Строка не удваивается.
+
+Что не помогает, чтобы не проверять заново:
+
+- **своё превью перетаскивания** (`renderDragPreview`). Неверное значение видно
+  в контракте данных — в `effectAllowed` у приёмника, — а не в картинке. Превью
+  на маску операций не влияет.
+- **отказ от `text/plain`**. Иконка появляется на первом же `dragenter` по самому
+  списку, до любого текстового поля на странице, а в Chromium с тем же
+  `text/plain` её нет.
+- **снятие `getAllowedDropOperations`** сделает хуже: тогда копирование будет
+  разрешено уже по-настоящему, и иконка станет правдой.
+
+## Антипаттерны
+
+- Хранить порядок или значения внутри компонента.
+- Открывать правку одиночным щелчком: тогда строке нечем открыть подробности.
+- Прятать ручку «чтобы было чище»: без неё список недоступен с клавиатуры.
+- Показывать доменное состояние средствами компонента — оно живёт в слотах.
+
+## Связанные исходники и проверка
+
+- Исходник: `src/components/content/EditableList.tsx`
+- Решение: ADR-0045
+- Тесты: `tests/editable-list.test.tsx`; браузер —
+  `tests-visual/interactions.spec.ts` (клавиатура, фокус и уход строки)
+- Витрина: `src/components/content/EditableList.stories.tsx`

package/docs/components/content/empty-and-loading.en.md

@@ -0,0 +1,149 @@
+---
+component: EmptyAndLoading
+exports: [EmptyState, ErrorState, Skeleton]
+category: content
+status: stable
+source: src/components/content/EmptyState.tsx, src/components/content/ErrorState.tsx, src/components/content/Skeleton.tsx
+story: src/components/content/EmptyState.stories.tsx, src/components/content/ErrorState.stories.tsx, src/components/content/Skeleton.stories.tsx
+sourceHash: aed9dc05fd60
+---
+
+# EmptyState, ErrorState and Skeleton
+
+## Summary for AI
+
+Three screen states that have no content, and they are not interchangeable:
+Show `Skeleton` while the result is not known yet, `EmptyState` when the request
+succeeded and returned nothing, and `ErrorState` when the request failed. Do not show "Nothing
+found" while the request is still running, and do not show it in place of a
+failure: an empty list is a result, a failure is an event.
+
+## When to use
+
+- `EmptyState` — after a successful load of an empty list, no results, or a
+  first launch with no objects yet.
+- `ErrorState` — the request ended in failure: a network failure, a 5xx response,
+  an unavailable backend. Almost always together with a "Try again" action.
+- `Skeleton` — while the result is unknown and it is already clear where the future data will
+  appear. Match its shape to the future content: a line, an avatar, a
+  button, a preview.
+
+## When not to use
+
+- Do not use `EmptyState` for a network error — `ErrorState` exists for that.
+- Do not use `ErrorState` for a message inside an already rendered screen: an
+  `Alert` fits better there (it lives in the content flow), while `ErrorState`
+  takes the place **of** the content.
+- Do not use `ErrorState` for a field validation error — that is `FormField`.
+- Do not use `Skeleton` as a permanent decorative block or as a progress
+  indicator. For short work of unknown length use `Spinner`, and for known
+  progress use `Progress`.
+- Do not add business logic to `EmptyState`: `action` takes a ready-made node,
+  usually a `Button`, not a callback.
+
+## Minimal example
+
+```tsx
+import { Button, EmptyState, Skeleton } from "@olddevs/ui";
+
+{
+  isLoading ? (
+    <Skeleton width={240} height={16} borderRadius={4} />
+  ) : items.length === 0 ? (
+    <EmptyState
+      title="Nothing found"
+      description="Try changing your query or resetting the filters."
+      action={
+        <Button variant="soft" onPress={resetFilters}>
+          Reset filters
+        </Button>
+      }
+    />
+  ) : (
+    <Results items={items} />
+  );
+}
+```
+
+## Public API
+
+### `EmptyState`
+
+| Prop          | Default | Meaning                                                                      |
+| ------------- | ------- | ---------------------------------------------------------------------------- |
+| `title`       | —       | A required short description of the empty state.                             |
+| `description` | —       | An extra explanation or the next step.                                       |
+| `icon`        | —       | A ready-made decorative node; the component hides it from the screen reader. |
+| `action`      | —       | A ready-made action node, for example a `Button`.                            |
+| `size`        | `md`    | `sm` — a picker or dropdown; `md` — a page or section.                       |
+
+### `ErrorState`
+
+| Prop          | Default                  | Meaning                                                                                                                                         |
+| ------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`       | from the message catalog | A general wording of the failure; the default (`errorState.title`) is "Failed to load" without a provider, "Ошибка загрузки" with `locales/ru`. |
+| `description` | —                        | What exactly failed: "Could not load the collections".                                                                                          |
+| `action`      | —                        | A ready-made node, usually a `Button` with "Try again".                                                                                         |
+| `icon`        | `ErrorIcon`              | A custom icon; `null` removes it entirely.                                                                                                      |
+| `size`        | `md`                     | `sm` — a panel or picker; `md` — in place of the page content.                                                                                  |
+
+`EmptyState` and `ErrorState` share their geometry, which lives in
+`src/lib/state.ts`; they differ in tone and in their role in the accessibility
+tree.
+
+### `Skeleton`
+
+| Prop                 | Default       | Meaning                                                               |
+| -------------------- | ------------- | --------------------------------------------------------------------- |
+| `width`, `height`    | —             | A number is pixels, a string is a CSS value.                          |
+| `borderRadius`       | `var(--r-md)` | A number or a CSS value. For example, `"50%"` for an avatar.          |
+| `className`, `style` | —             | Standard `div` attributes; `style` is merged with the computed sizes. |
+
+## Accessibility and state
+
+`EmptyState` renders its text as ordinary visible content: an empty list is a
+result, and there is no need to announce it immediately. The icon is always
+decorative.
+
+`ErrorState`, by contrast, has `role="alert"`: a failure has to be announced,
+otherwise a screen reader user is left with silence instead of an answer. Hence
+the rule of use: do not keep `ErrorState` in the markup permanently and hide it
+with CSS: it must appear at the moment of the failure, otherwise the
+announcement does not fire. `Skeleton` does not report the end of loading on its
+own: the owner of the state must switch it to the actual data or a status for the screen reader.
+
+## Anti-patterns
+
+```tsx
+// Bad: the user is told there is nothing, though the request is still running.
+return <EmptyState title="Nothing found" />;
+
+// Good: the shape of the future data comes first.
+return isLoading ? <Skeleton width="100%" height={120} /> : <EmptyState title="Nothing found" />;
+```
+
+```tsx
+// Bad: a failure is presented as an empty result — the user thinks there is no data.
+if (isError) return <EmptyState title="Nothing found" />;
+
+// Good: a failure is called a failure and offers a retry.
+if (isError)
+  return (
+    <ErrorState
+      description="Could not load the collections."
+      action={
+        <Button icon={<RefreshIcon />} onClick={refetch}>
+          Try again
+        </Button>
+      }
+    />
+  );
+```
+
+## Related sources and Storybook
+
+- Sources: `src/components/content/EmptyState.tsx`, `src/components/content/ErrorState.tsx`,
+  `src/components/content/Skeleton.tsx`.
+- Stories: `src/components/content/EmptyState.stories.tsx`, `src/components/content/ErrorState.stories.tsx`,
+  `src/components/content/Skeleton.stories.tsx`.
+- Tests: `tests/error-state.test.tsx`.