@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/api/migration-notes.md

@@ -0,0 +1,890 @@
+---
+category: api
+status: stable
+source: src/index.ts
+---
+
+# Совместимость и заметки о миграции
+
+## Кратко для AI
+
+Публичный контракт `@olddevs/ui` — это входы из `exports` пакета (`@olddevs/ui`,
+`/icons`, `/color`, `/editor`, `/editor/schema`, `/editor/highlight`, `/locales/ru`,
+`/locales/en`), их runtime exports и экспортируемые TypeScript types. При
+изменении этого контракта заметка о миграции обязана объяснить потребителю,
+что изменилось, почему, как заменить старый код и в какой версии это стало
+актуально.
+
+## Когда использовать
+
+- При удалении, переименовании или изменении значения публичного export/prop.
+- При изменении default, доступности, клавиатурного поведения или формы
+  контролируемого значения: TypeScript может не обнаружить такую миграцию.
+- При замене компонента на другой, например, когда старый API исчезает в пользу
+  существующего семейства.
+
+## Когда не использовать
+
+- Не заводите заметку о миграции для исправления внутреннего файла, не
+  затрагивающего входы пакета, поведение или типы потребителя.
+- Не объявляйте изменение «breaking» только потому, что переименован внутренний
+  файл или функция: сначала проверьте, входят ли они в `src/index.ts`, и реальные
+  сценарии использования.
+- Не оставляйте двусмысленную замену вроде «используйте новый Select» без
+  таблицы старого и нового поведения.
+
+## Минимальный шаблон заметки
+
+Добавьте раздел в release notes или CHANGELOG репозитория и при необходимости
+добавьте в этот файл ссылку на заметку. Каждая заметка содержит:
+
+````md
+## X.Y.Z — краткое название
+
+**Статус:** breaking change | deprecation | behavior change
+
+### Что изменилось
+
+Точный export, prop или поведение.
+
+### Кого затрагивает
+
+Какие импорты/сценарии потребителя нужно найти.
+
+### До → после
+
+```tsx
+// старый код
+// новый код
+```
+
+### Семантика и доступность
+
+Что меняется для клавиатуры, фокуса, доступного имени или формы значения.
+
+### Действие до обновления
+
+Конкретная проверка или код-мод.
+````
+
+## Обязательная процедура изменения public API
+
+1. Сверьте изменение с файлом нужного входа (`src/index.ts`, `src/icons.ts`,
+   `src/color.ts`, `src/editor/index.ts` и остальные из `exports` пакета) и
+   экспортным типом. Внутренний путь — не альтернатива публичному API.
+2. Обновите страницу компонента: `Кратко для AI`, «Когда не использовать»,
+   минимальный пример, таблицу API и раздел доступности, если затронуты.
+3. Обновите каталог компонентов, если добавился или исчез runtime
+   component export. Полные правила описаны в `AGENTS.md` репозитория кита.
+4. Добавьте заметку о миграции или release note с версией и однозначным до/после. Если
+   замена возможна поэтапно, опишите срок/версию удаления и предупреждение.
+5. Добавьте или обновите тест для прежней границы и нового контракта; для
+   взаимодействия проверяйте фокус, клавиатуру и доступные имена.
+
+## 4.0.0 — первый публичный выпуск
+
+**Статус:** breaking change — смена лицензии и реестра; API без изменений.
+
+### Что изменилось
+
+- Лицензия — MIT (была `UNLICENSED`); сторонние лицензии по-прежнему в `NOTICE`.
+- Пакет публикуется на npmjs.com, исходники — на GitHub.
+- С этого выпуска версии следуют строгому semver: ломающие изменения — только в мажоре; переименование
+  публичного API идёт через deprecated-алиас, который живёт один мажор.
+- `CHANGELOG.md` начинается с этого выпуска.
+
+### Кого затрагивает
+
+Всех, кто ставил пакет из другого реестра: строка `@olddevs:registry=…` в `.npmrc` проекта или
+пользователя направляет установку скоупа мимо npmjs.
+
+### До → после
+
+```ini
+# .npmrc — было
+@olddevs:registry=https://<прежний реестр>/
+# стало: строки нет, пакет ставится с npmjs.com
+```
+
+```bash
+npm i @olddevs/ui@4
+```
+
+### Семантика и доступность
+
+Не меняются: код, экспорты, пропсы, стили и поведение 4.0.0 совпадают с 3.49.
+
+### Действие до обновления
+
+Удалите привязку скоупа `@olddevs` к прежнему реестру из `.npmrc`, пересоздайте lock-файл и проверьте, что в
+нём `resolved` у `@olddevs/ui` ведёт на `registry.npmjs.org`.
+
+## 3.48.0 — «Карточка у текста»: `callouts` → `textCards`
+
+**Статус:** breaking change — minor, псевдонима нет. Потребитель у API был один (приложение-источник), и
+он заменил имена у себя; правило ADR-0058, п. 12.2 («сначала пометка, потом удаление»)
+здесь не применяется.
+
+### Что изменилось
+
+«Callout» у GitHub и Notion — блок-заметка, а в ките так называлась карточка под диапазоном текста.
+Публичные имена переименованы, поведение не менялось:
+
+- поле `callouts` у `CustomTool` → `textCards`;
+- типы `CustomCallout` → `CustomTextCard`, `CustomCalloutRender` → `CustomTextCardRender`,
+  `CalloutRange` → `TextCardRange`, `CalloutRangeAt` → `TextCardRangeAt`;
+- строка каталога `editor.calloutShown` → `editor.textCardShown`.
+
+Заметка у Обёртки с тоном (`wrapper`, GitHub alert) этого не касается. Запись 3.37.0 ниже называет
+прежние имена как исторические.
+
+### Кого затрагивает
+
+Всех, кто описывает свой Инструмент с полем `callouts`, импортирует перечисленные типы или переопределяет
+строку `calloutShown` в своём каталоге.
+
+### До → после
+
+```tsx
+// было
+const tool: CustomTool = {
+  name: "acme_comment",
+  engine: [],
+  callouts: [{ label, rangeAt, render }],
+};
+// стало
+const tool: CustomTool = {
+  name: "acme_comment",
+  engine: [],
+  textCards: [{ label, rangeAt, render }],
+};
+```
+
+### Действие до обновления
+
+Найти в коде и тестах `callouts`, `CustomCallout`, `CalloutRange` и `calloutShown` (без `-webkit-touch-callout`)
+и заменить по таблице. Проверка массива `tools` называет поле `textCards` в сообщениях об ошибках:
+тесты, сверяющие тексты ошибок, обновить.
+
+## 3.47.0 — `VirtualGrid` на `GridList`: роли `grid`/`row`/`gridcell`
+
+**Статус:** behavior change — minor. Пропы прежние, прежний код собирается и
+работает; меняются роли в DOM и второй аргумент `onAction`.
+
+### Что изменилось
+
+Сетка построена на `GridList` react-aria, а не на `ListBox`
+(ADR-0028,
+дополнение). Сетка — `grid` вместо `listbox`, ячейка — `row` с
+`gridcell` внутри вместо `option`. `onAction` теперь получает второй аргумент
+`{ rect }`. `minItemHeight` теперь задаёт наименьшую высоту ячейки: раньше ячейка
+принимала высоту содержимого.
+
+### Кого затрагивает
+
+Тесты потребителя, которые ищут сетку по ролям: `getByRole("listbox")`,
+`getAllByRole("option")`. Проверки `onAction`, сверяющие точный список аргументов
+(`toHaveBeenCalledWith(id)`). Ячейки, содержимое которых ниже `minItemHeight`:
+теперь такие ячейки выше.
+
+### До → после
+
+```tsx
+// было
+screen.getByRole("listbox", { name: "Кадры" });
+screen.getAllByRole("option");
+expect(onAction).toHaveBeenCalledWith("7");
+// стало
+screen.getByRole("grid", { name: "Кадры" });
+screen.getAllByRole("row");
+expect(onAction).toHaveBeenCalledWith("7", expect.objectContaining({ rect: expect.anything() }));
+```
+
+### Семантика и доступность
+
+Клавиатура прежняя: стрелки двигают по сетке, Space выбирает, Enter открывает,
+Shift+F10 — меню ячейки. Новое: кнопки внутри ячейки допустимы; в `option` они
+давали нарушение `nested-interactive` уровня serious. Кружок выбора —
+`<Checkbox slot="selection" />` в содержимом ячейки.
+
+### Действие до обновления
+
+Найти в тестах `"listbox"` и `"option"` рядом с `VirtualGrid` и заменить на
+`"grid"` и `"row"`; ослабить проверки аргументов `onAction`. Проверить вид
+ячеек ниже `minItemHeight`.
+
+## 3.46.0 — движок Редактора не в манифесте кита
+
+**Статус:** behavior change — minor. API прежнее; меняется то, что npm ставит
+вместе с китом.
+
+### Что изменилось
+
+21 пакет движка Редактора (`@tiptap/*`, `lowlight`, `highlight.js`, `marked`)
+убран из `peerDependencies`, поле `peerDependenciesMeta` удалено. Они были
+опциональными peer-зависимостями, но при установке из прежнего реестра npm
+ставил движок каждому потребителю — даже приложению, которое Редактор не
+импортирует.
+
+### Кого затрагивает
+
+Только тех, кто импортирует `@olddevs/ui/editor` и не ставил движок явно: пакеты
+приходили сами. После обновления сборка упадёт
+на неразрешимом `@tiptap/…`. Приложениям без Редактора делать ничего не нужно —
+из их lock-файла уйдёт около 60 пакетов.
+
+### Действие до обновления
+
+Поставить движок командой из раздела «Установка» страницы
+[RichTextEditor](../components/inputs/rich-text-editor.md#установка). О
+несовпадении версий Tiptap npm больше не предупредит: диапазон `^3.31.4` указан
+там же.
+
+## 3.37.0 — Редактор, открытый для расширения
+
+**Статус:** behavior change — minor по разделу «Стабильность»
+[API расширения Редактора](editor-extension.md#стабильность): сохранённый HTML,
+`onChange`, `onUploadImage` и `focus()` не меняются, прежний код собирается.
+Заметка нужна потому, что пять изменений видны нынешним потребителям
+`@olddevs/ui/editor`, а одно требует установки пакетов у pnpm. Новый API
+(свой Инструмент, Хэндл, события, Строка статуса) действий не требует — оно на
+[странице API расширения](editor-extension.md).
+
+### 1. Два новых peer-пакета
+
+Цитата и разделитель берут Часть для движка из `@tiptap/extension-blockquote` и
+`@tiptap/extension-horizontal-rule` — опциональных peer-зависимостей входа
+`@olddevs/ui/editor` с тем же диапазоном `^3.31.4` (с 3.46.0 пакеты движка из
+манифеста кита убраны, см. запись выше).
+
+**Кого затрагивает.** Только pnpm (строгий `node_modules`) и установки с
+`--omit=optional`: npm и yarn ставят оба пакета зависимостями
+`@tiptap/starter-kit`, и импорт разрешается.
+
+**Действие до обновления.**
+
+```bash
+pnpm add @tiptap/extension-blockquote @tiptap/extension-horizontal-rule
+```
+
+Полная команда — на странице [RichTextEditor](../components/inputs/rich-text-editor.md#установка).
+
+### 2. Разделитель не весит символ в `maxLength`
+
+**Что изменилось.** Раньше счётчик подставлял пробел вместо листового узла, и
+каждый `<hr>` отнимал у предела один символ. Теперь вес Атома — длина его Текста
+Атома (`renderText`): разделитель весит 0, мягкий перенос — 1, картинка — длину
+подписи. Счётчик совпадает с `getText()` без разделителей Блоков.
+
+**Кого затрагивает.** Экраны с `maxLength` и разделителями в Документе. Документ
+с N разделителями вмещает на N символов больше, а Документ, который раньше был
+«превышен» на число разделителей, теперь укладывается в предел. Если сервер
+проверяет длину тем же пределом и считает `<hr>` символом, он отвергнет то, что
+Редактор пропустил.
+
+**До → после.**
+
+| Документ                  | Было       | Стало      |
+| ------------------------- | ---------- | ---------- |
+| `<p>abc</p><hr><p>de</p>` | 6 символов | 5 символов |
+| `<p>a<br>b</p>`           | 3          | 3          |
+
+**Вставка за пределом** срезает хвост по символам, а не по позициям; Атом, который
+не поместился, уходит целиком вместе со всем, что после него.
+
+**Действие до обновления.** Серверную проверку длины сверьте с правилом кита:
+текст Документа без разметки и разделителей Блоков, Атом — длиной своего текста.
+Серверного счётчика у кита нет: вес своего Атома зависит от его Части для движка.
+
+### 3. Скелет до Готовности
+
+**Что изменилось.** До Готовности Редактор показывает Скелет: рамку поля, место
+Панели и Документ, очищенный Схемой, статичным HTML без ввода. Раньше на этом
+месте была пустая область; теперь высота поля не прыгает. На сервере и до
+гидратации Скелет — только рамка, Документ появляется после монтирования в
+браузере. В `full` блок кода и таблица теперь приходят отдельным чанком, поэтому
+Готовность наступает после их загрузки, а до неё виден Скелет (в нём блок кода
+показан с шапкой, а таблица — ячейками). Пресет `basic` эти чанки не грузит и
+готов сразу. Сценарий «старт» (статический граф подпути с движком, то, что платит
+`basic`) стал легче: 312,3 → 286,6 кБ gzip. Сценарий «полный» (со всеми ленивыми
+чанками, `full`) весит 327,7 кБ (замер 3.37.0; актуальная таблица —
+[«Размер импорта»](../getting-started.md#размер-импорта)).
+
+**Кого затрагивает.**
+
+- Код, который обращается к `ref.current.editor` или зовёт `ref.current.focus()`,
+  `insertHTML()` сразу после монтажа: в `full` движок появляется позже, а до
+  Готовности `editor` — `null`, а методы Хэндла ничего не делают и не бросают
+  ошибок.
+- Тесты потребителя с `full`, которые ищут `role="textbox"` синхронно сразу после
+  `render`: редактируемая область появляется после загрузки чанков. У Скелета роли
+  `textbox` нет.
+- Визуальные снимки страниц с Редактором: на месте пустой области — рамка и
+  Документ.
+
+**До → после.**
+
+```tsx
+// было — фокус в эффекте монтажа: в `full` движка в этот момент ещё нет, вызов ничего не делает
+useEffect(() => ref.current?.focus(), []);
+
+// стало — момент Готовности сообщает колбэк
+<RichTextEditor ref={ref} onReady={() => ref.current?.focus()} />;
+```
+
+```tsx
+// тест: ждать редактируемую область, а не брать её синхронно
+expect(await screen.findByRole("textbox")).toBeInTheDocument();
+```
+
+**Действие до обновления.** Найдите обращения к `ref.current.editor` и методам
+Хэндла в эффектах монтажа и перенесите их в `onReady`; в тестах замените
+`getByRole("textbox")` у Редактора с `full` на `await findByRole`. Чтобы чанки
+пришли вместе со страницей, поставьте на них `modulepreload`
+([рецепт](editor-extension.md#modulepreload-для-ленивых-чанков)).
+
+### 4. Сообщения о картинках — на канале Сообщения поля
+
+**Что изменилось.** «Загружается…», «загружен», отказ загрузки, «не картинка» и
+«файлы не принимаются» идут тем же каналом, что новая команда движка
+`showNotice`: одно место под полем, новое сообщение заменяет прежнее, ошибка
+(`role="alert"`) держится до следующей Правки автора. Тексты и роли прежние, но
+живой регион `role="status"` теперь есть в **каждом** Редакторе, а не только с
+Инструментом `image`.
+
+**Кого затрагивает.** Тесты, которые проверяли отсутствие `role="status"` у
+Редактора без `image` или считали живые регионы на странице, и экраны, которые
+рисовали свою строку ошибки вставки рядом с полем.
+
+**Действие до обновления.** Ищите регион по тексту сообщения, а не по одному
+факту его наличия. Свою строку ошибки вставки и загрузки замените командой
+`ref.current?.editor?.commands.showNotice({ tone: "error", text })`: иначе
+ошибка прозвучала бы дважды.
+
+### 5. Тип `Tool` принимает описания своих Инструментов
+
+**Что изменилось.** Тип `Tool` (элемент `tools`) теперь `ToolName | CustomTool`;
+имя встроенного Инструмента — новый тип `ToolName`. Прежний `Tool` был строкой
+имени.
+
+**Кого затрагивает.** TypeScript-код, который обращался с `Tool` как со строкой:
+`tool.startsWith(…)`, ключи `Record<Tool, …>`, сравнение в `switch`.
+
+**До → после.**
+
+```ts
+// было
+import type { Tool } from "@olddevs/ui/editor";
+const labels: Record<Tool, string> = { … };
+
+// стало
+import type { ToolName } from "@olddevs/ui/editor";
+const labels: Record<ToolName, string> = { … };
+```
+
+**Действие до обновления.** `tsc` найдёт такие места сам; замените в них `Tool` на
+`ToolName`. Массивы имён для `tools` менять не нужно.
+
+### Что ещё видно — действий не требует
+
+- «Снять обёртку» в меню Ручки Блока стоит отдельной секцией Инструмента перед
+  «Удалить»: свои Действия над Блоком встают туда же.
+- Новые строки каталога сообщений, пространство `editor`: `toolsFailed`, `retry`, `calloutShown`. Если вы
+  передаёте свой полный каталог, добавьте их; частичный каталог берёт фолбэк кита.
+
+## 3.1.0 — выбор в `VirtualGrid` переехал на сетку
+
+**Статус:** deprecation — старый код продолжает собираться. Но он
+и порождает нарушение доступности, поэтому заметка здесь, а не
+только в `CHANGELOG.md`.
+
+### Что изменилось
+
+`VirtualGrid` получил собственную ось выбора: `selectionMode`, `selectedKeys`,
+`onSelectionChange`. Прежде документация советовала включать выбор внутри
+ячейки, у `MediaCard`. Этот совет отменён.
+
+### Почему
+
+Ячейка сетки — это `option` (сетка построена на `ListBox` из react-aria). Кнопка
+выбора внутри `option` даёт вложенный интерактивный элемент: axe зовёт это
+нарушением уровня serious, и оно воспроизводилось на всех темах. Подписью или
+атрибутом это не лечится — лечится только тем, что выбирается сама ячейка.
+
+### Как заменить
+
+```tsx
+// было — кнопка выбора внутри ячейки
+<VirtualGrid
+  items={items.map((it) => ({
+    id: it.id,
+    textValue: it.name,
+    content: (
+      <MediaCard
+        preview={preview}
+        selected={selected[it.id] ?? false}
+        onSelectedChange={(next) => setSelected({ ...selected, [it.id]: next })}
+      />
+    ),
+  }))}
+  aria-label="Кадры"
+/>;
+
+// стало — выбирается ячейка, карточка только рисует состояние
+const [keys, setKeys] = useState<Selection>(new Set());
+
+<VirtualGrid
+  items={items.map((it) => ({
+    id: it.id,
+    textValue: it.name,
+    content: <MediaCard preview={preview} selected={keys === "all" || keys.has(it.id)} />,
+  }))}
+  aria-label="Кадры"
+  selectionMode="multiple"
+  selectedKeys={keys}
+  onSelectionChange={setKeys}
+/>;
+```
+
+`Selection` и `Key` — типы `react-aria-components`, она и так в
+`peerDependencies`. Множество выбранных по-прежнему держит потребитель: кит даёт
+форму, а состояние остаётся у потребителя
+(ADR-0023).
+
+Вне сетки `MediaCard` менять не нужно: своя ось выбора у карточки осталась и
+нарушения не даёт — `option` вокруг неё там нет.
+
+## 3.0.0 — один словарь состояний
+
+**Статус:** breaking change. Ломается ровно одно и в одном месте: два словаря
+состояний сведены в один. Ничего кроме этого мажор не несёт, и это решение
+(ADR-0031).
+
+### Что изменилось
+
+`UploadState` и `TimelineStatus` описывали одну и ту же сущность — состояние
+работы — под двумя именами, с двумя идентичными построчно таблицами тонов. Долг
+нашло ревью 2.5.0; свести его патчем было нельзя, оба типа входили в публичный
+API.
+
+Теперь тип один: **`ProgressStatus`**. Старые имена **удалены**, алиасов не
+осталось: `@deprecated`-алиас в мажоре — это второй словарь, ради устранения
+которого всё и затевалось.
+
+### Кого затрагивает
+
+Всех, кто импортирует `UploadState` или `TimelineStatus`, и всех, кто передаёт
+`state` в `UploadQueue` — **включая тех, кто не импортирует типы вовсе**.
+Значения `UploadQueue` изменились, и на JavaScript это не увидит ни компилятор,
+ни линтер.
+
+Найдите у себя:
+
+```bash
+grep -rn "UploadState\|TimelineStatus" src/
+grep -rn "state: *[\"']\(done\|error\)[\"']" src/
+```
+
+`Timeline` не затронут ничем, кроме имени типа: его значения победили.
+
+### До → после
+
+| Понятие       | `TimelineStatus` | `UploadState` | `ProgressStatus` |
+| ------------- | ---------------- | ------------- | ---------------- |
+| не начиналось | `pending`        | `pending`     | `pending`        |
+| идёт          | `running`        | `running`     | `running`        |
+| успех         | `success`        | **`done`**    | **`success`**    |
+| провал        | `failed`         | **`error`**   | **`failed`**     |
+
+```tsx
+// было
+import type { UploadState, TimelineStatus } from "@olddevs/ui";
+<UploadQueue items={[{ id: "1", name: "смета.xlsx", state: "done" }]} />;
+
+// стало
+import type { ProgressStatus } from "@olddevs/ui";
+<UploadQueue items={[{ id: "1", name: "смета.xlsx", state: "success" }]} />;
+```
+
+Победили значения `Timeline`: `success` и `failed` описывают **исход** и
+симметричны друг другу. Пара `done` и `error` несимметрична: первое про
+завершённость, второе про событие, и вместе они читаются так, будто «завершено с
+ошибкой» тоже возможное состояние.
+
+Имя типа нейтральное намеренно: `TimelineStatus` у очереди загрузок врал бы —
+никакого timeline у неё нет.
+
+### Семантика и доступность
+
+Для клавиатуры, фокуса и доступных имён не меняется ничего. Тона состояний те
+же: таблица `pending → neutral`, `running → accent`, успех `→ success`,
+провал `→ danger` действовала в обоих компонентах и до сведения — менялись
+только имена ключей.
+
+**Незнакомое значение по-прежнему не роняет экран**: оно даёт нейтральный тон.
+Защита была у обоих компонентов и раньше, теперь она описана в самом словаре, а
+не повторена дважды. Начиная с 3.0.0 её стерегут тесты в обоих компонентах — до
+этого тест был только у `Timeline`.
+
+### Действие до обновления
+
+1. Замените импорты типов на `ProgressStatus`.
+2. Замените значения `done` → `success` и `error` → `failed` **в данных**, а не
+   только в типах. Если состояния приходят с бэкенда, сопоставление делайте
+   в своём адаптере: кит доменных словарей не знает и не угадывает.
+3. Прогоните сборку. На TypeScript ошибки будут точными; на JavaScript
+   сломанного значения не увидит никто, кроме тона — упавший файл нарисуется
+   нейтральным вместо красного.
+
+### Что ещё появилось — действий не требует
+
+Всё ниже — добавления: старый код продолжает работать без правок.
+
+**`SavedViews`** — переключатель именованных снимков состояния. Форма вида
+параметризована вашим состоянием (`SavedView<T>`), а не привязана к
+`TableState`; хранение, шаринг и URL остаются у вас целиком. Подробности — на
+[странице компонента](../components/table/saved-views.md).
+
+**Подсказка и ошибка `FormField` доходят до семей react-aria.** У
+`Select`, `Combobox`, `DatePicker` и `TagInput` описание от `FormField` теперь
+связано с полем через `aria-describedby`. **Это исправление доступности, и оно меняет
+объявляемое:** там, где подсказка была видна на экране, но скринридеру не
+доставалась, она начнёт читаться. Ваши тесты на доступное описание этих полей
+могут потребовать обновления — раньше его не было вовсе.
+
+У `Select`, `DatePicker` и `TagInput` заодно появился публичный проп
+`aria-describedby`; своё значение не вытесняет описание от `FormField`, а
+сливается с ним.
+
+**Figma Code Connect** — 16 основных компонентов зеркала привязаны к компонентам кита.
+Потребителя не касается: привязки в пакет не уезжают.
+
+### Чего в 3.0.0 нет
+
+Ни одного изменения, кроме описанного выше. Сознательно **не** вошли в мажор:
+
+- **RTL** — открытый вопрос спеки; `dir` в провайдере остаётся необъявленным;
+- **peer React 18** — остаётся `react: ^19`; расширение удваивает сборку
+  потребителя в CI и решается отдельно;
+- **компоненты графиков** — не появятся: графики остаются у потребителя
+  (ADR-0032);
+- **виртуализация `Table`, экспорт CSV, `JsonViewer`, `LogViewer`** — сняты за
+  отсутствием экрана-заказчика (ADR-0031).
+
+Мажор ломает контракт один раз и в одном месте. Если сгрузить в него всё
+накопленное, пришлось бы перечитывать свой код и тем, кого словарь состояний не
+касается вовсе.
+
+## 2.6.0 — пакет проверяется у потребителя
+
+Ломающего нет: один новый компонент и одно новое требование к сборке
+потребителя. Действие требуется ровно одно — см. пункт 2.
+
+**1. `ContextualSaveBar`.** Полоса несохранённых изменений: появляется с первой
+правкой формы, показывает число правок и две кнопки. Долг, оставшийся от волны 20. Чем он отличается
+от `SelectionBar` и `Banner`, сказано на
+[странице компонента](../components/navigation/contextual-save-bar.md).
+
+**2. `optimizePackageImports` становится обязательным в Next.js.** Одна строка в
+конфигурации потребителя:
+
+```js
+// next.config.mjs
+export default { experimental: { optimizePackageImports: ["@olddevs/ui"] } };
+```
+
+Формально это не ломающее изменение: пакет и без неё собирается и работает.
+Но **цена без неё непозволительная**: страница с одной `Button` весит 408 кБ
+вместо 117 при базовой линии 102 (замер выпуска 2.6.0), а серверный компонент с двумя чистыми
+функциями и без единого компонента кита — столько же. Причина в границе
+клиентского графа, а не в упаковке пакета: тот же `dist` на обычном rollup
+отдаёт `Button` за 6 кБ. Обоснование и отвергнутые альтернативы — в
+ADR-0029.
+
+Проверьте свою конфигурацию при обновлении. Если приложение не на Next.js,
+измерьте цену импорта у себя: кит этот случай пока не проверял.
+
+**3. Отдельного входа `@olddevs/ui/server` не появилось и не появится.** Чистые
+утилиты (`cn`, `tableStateToParams`, `formatMask` и прочие) импортируются из
+корня и в клиентский граф не тянут — со строкой из пункта 2.
+
+**4. Новые проверки пакета** потребителя не касаются, но объясняют, откуда
+взялись числа выше: `npm run check:dist`, `npm run check:consumer`,
+`npm run size`, `npm run release:check`. Версия и `CHANGELOG.md` теперь ведутся
+changesets.
+
+**Отложено сознательно:** Figma Code Connect (приоритет P2 из спецификации,
+только после стабилизации имён и осей); привязка описания у семей react-aria (`Select`,
+`Combobox`, `DatePicker`, `TagInput`) — у них свои слоты описания; сведение
+`UploadState` и `TimelineStatus` — ломает публичный тип и ждёт мажора;
+расширение peer до React 18 — удваивает сборку потребителя в CI.
+
+## 2.5.1 — две правки по ревью 2.5.0
+
+Ломающего нет; действий от потребителя не требуется.
+
+**1. `Truncate` снова следит за размером после первой обрезки.** Обёртка в
+`Tooltip` пересоздавала узел, а `ResizeObserver` оставался на старом: колонка,
+расширенная после обрезки, не снимала ни `tabIndex`, ни подсказку.
+
+**2. `SortableList` не теряет строку при сбросе «на себя».** Когда ключ цели
+оказывался среди перемещаемых, перестановка выбрасывала последний элемент
+списка и передавала потребителю испорченный порядок. Теперь такой сброс ничего не
+меняет и потребителю не передаётся. Механика перестановки вынесена в чистую функцию и
+проверена на массивах.
+
+**Долг, названный, но не закрытый:** `UploadState` (`done`/`error`) и
+`TimelineStatus` (`success`/`failed`) — два словаря одного понятия. Сведение к
+одному ломает публичный тип, выпущенный в 2.5.0, и ждёт следующего мажора.
+
+## 2.5.0 — данные, загрузки, уведомления
+
+Ломающего нет: всё новое — добавления, у `AppShell` прибавился один слот.
+
+**1. Восемь новых семей компонентов.** `Banner`, `UploadQueue`, `NotificationItem` /
+`NotificationList` / `NotificationCenter`, `MediaCard`, `SortableList`,
+`VirtualGrid`, `CopyButton`, `Truncate`.
+
+**2. У `AppShell` появился слот `banners`** — сообщения уровня приложения над
+шапкой. Без пропа разметка каркаса не меняется ни на узел. Баннеры не липкие, и
+`--topbar-h` продолжает означать ровно высоту шапки: контракт липкости не
+трогается.
+
+**3. Новых зависимостей нет.** Перетаскивание и виртуализация стоят на
+`react-aria-components`, уже объявленном peer-зависимостью, а не на `@dnd-kit`
+и `@tanstack/react-virtual`, как во фронтенде приложения-источника
+(ADR-0028).
+
+Два следствия для тех, кто переезжает с этого фронтенда:
+
+- `SortableList` рисует **ручку перетаскивания** в каждой строке. Без неё
+  react-aria не даёт таскать с клавиатуры вовсе — она лишь предупреждает в
+  консоль. Ручка обязательна.
+- `VirtualGrid` **прокручивает свой контейнер, а не окно**. Задайте контейнеру
+  высоту: без неё виртуализация не включится, и сетка отрисует все ячейки разом.
+  Сетка этого фронтенда построена на `useWindowVirtualizer` и прокручивает
+  страницу.
+
+**4. Новые пространства каталога сообщений:** `banner`, `uploadQueue`,
+`notifications`, `mediaCard`, `sortableList`, `copyButton`. Ключи аддитивные —
+`PartialUiMessages` глубоко частичный, ломающим это не считается.
+
+**5. Отложено:** `ContextualSaveBar` — в волну 21. `SortableGrid` не заводится:
+сетка получит перетаскивание, когда появится экран-заказчик. Графики,
+`JsonViewer`, `LogViewer` — приоритет P2, берутся под конкретный экран.
+
+Состав волны подробно — ADR-0027.
+
+## 2.4.0 — формат поля виден и объявлен
+
+Ломающего нет, но **вид двух выпущенных компонентов изменился** — прочитайте
+пункт 1, даже если ничего не обновляли в коде.
+
+**1. `MaskedInput` и `PhoneInput` показывают формат прямо в поле.** Пустое
+телефонное поле теперь читается `+7 (___) ___-__-__`, и трафарет маски исчезает по мере
+ввода. До 2.4.0 формат не сообщался ничем: пустое поле было пустым
+прямоугольником, а наполовину заполненное обрывалось на последней цифре.
+
+Умолчание включено сознательно — отсутствие формата было дефектом. Выключается пропом:
+
+```tsx
+<MaskedInput mask="99.99.9999" value={value} onChange={setValue} showMask={false} />
+```
+
+Выключать стоит там, где формат уже сказан рядом и повторять его в поле — шум:
+короткая известная маска в плотной таблице, поле под подписью с примером.
+
+**2. Подсказка и ошибка `FormField` объявляются скринридером.** Раньше они были
+видны только на экране: `FormField` рисовал их `<div>` без `id`, и связать их с
+полем было нечем. Теперь `id` создаёт `FormField`, а поля кита
+забирают его в `aria-describedby`.
+
+Действий от потребителя не требуется. Если вы описывали поле своим узлом —
+описание **дополняется, а не вытесняется**: атрибут хранит список.
+
+Забирают описание `TextControl` и всё, что на нём стоит (`MaskedInput`,
+`PhoneInput`, `PasswordInput`, `SearchControl`), плюс `NumberInput`. Семьи на
+react-aria (`Select`, `Combobox`, `DatePicker`, `TagInput`) несут свои слоты
+описания и подсказку `FormField` пока не забирают.
+
+**3. Неподходящий символ объявляется.** Символ, не подошедший под токен маски,
+по-прежнему отбрасывается, но рядом с полем появляется живая область с тем, чего
+здесь ждали. Разбирается ровно один набранный символ; вставка не разбирается.
+Новое пространство каталога — `maskedInput`; ключей два, и в локали `ru` они
+есть.
+
+**4. У `TextControl` появился слот `underlay`** — подложка под значением, на той
+же строке. На нём построен трафарет маски. Компонент сам вешает на подложку
+`aria-hidden` и снимает с неё события указателя (`pointer-events: none`): читать
+там нечего.
+
+Обоснование решений и источники — в ADR-0026.
+
+## 2.3.0 — продвинутые поля ввода
+
+Ломающего нет: всё новое — добавления, а у `FormField` прибавилась одна ось,
+которая включается наличием пропа или контекста.
+
+**1. Новые компоненты:** `PasswordInput`, `FormLayout` с `FieldRow`,
+`PinInput`, `InlineEdit`, `TreeView`, `MaskedInput`, `PhoneInput`. Новые
+утилиты: `formatMask`, `unmask`, `maskCapacity`, константа `RU_PHONE_MASK`.
+
+**2. `FormField` умеет боковую подпись.** `layout="stack" | "side"`; без пропа
+и без `FormLayout` разметка не меняется ни на узел — это проверяется тестом на
+разметку целиком. Ось живёт у поля, а не у раскладки, потому что подпись рисует
+`FormField` (ADR-0025). Ширина колонки подписей — переменная `--form-label-w`.
+
+**3. `CurrencyInput` не появится.** Это `NumberInput` с `formatOptions`:
+react-aria форматирует валюту, разбирает ввод и берёт разделители разрядов и
+десятичный знак из локали. Отдельный компонент дублировал бы существующий:
+
+```tsx
+<NumberInput label="Сумма" formatOptions={{ style: "currency", currency: "RUB" }} />
+```
+
+**4. `TreeSelect` отложен до заказчика.** Он собирается из `TreeView` и
+`Popover`; заводить его без единого экрана — значит проектировать вслепую —
+ровно то, за что волна 18 заплатила переделкой `TablePreferences` из меню в
+панель. Появится экран с выбором из иерархии — вернётся и вопрос.
+
+**5. У `PhoneInput` формат один и фиксированный.** Обещание «формат из локали»
+снято: `Intl` телефоны не форматирует вовсе, а честный разбор — это
+`libphonenumber` весом в сотни килобайт. Формат приходит пропом с умолчанием
+`RU_PHONE_MASK`. Компонент не разбирает номер, не хранит справочник стран и не
+валидирует.
+
+**6. `PinInput` отдаёт строку, и дыр в ней не бывает.** Поля — показ одного
+значения, а не N независимых: удаление символа в середине сдвигает остальные
+влево, как в обычном текстовом поле.
+
+**7. Роль `TreeView` — `treegrid`, а узлы `row`.** Так устроена react-aria: в
+строке живут кнопка раскрытия и флажок, а `treeitem` второго интерактивного
+элемента внутри себя не предполагает. Если вы ищете узлы в тестах — ищите по
+роли `row`. `useTreeData` кит не реэкспортирует: это хранилище, а состоянием
+кит не владеет.
+
+## 2.2.0 — продуктовая таблица
+
+Ломающего нет: всё новое — добавления, а у `Table` прибавилась одна ось, которая
+включается наличием пропа.
+
+**1. `Table` умеет раскрытие строки.** `renderDetail` плюс `expandedKeys` /
+`onExpandedChange`. Без `renderDetail` разметка не меняется ни на узел — это
+проверяется тестом. Раскрытые строки задаются множеством ключей, как выделение: переключателя «одна
+строка или несколько» нет, потому что состояние таблица не хранит и поддержать
+такой проп не может.
+
+**2. `rowLabel` стоит передавать вместе с раскрытием.** Без него у всех
+раскрывателей одинаковое имя, и скринридер в режиме перечисления кнопок читает
+двадцать одинаковых «Показать подробности».
+
+**3. `UiProvider` принимает `density`.** Умолчание, а не режим: таблица и её
+шестерёнка перекрывают. Проп обещан в 2.0.0 и отложен ADR-0002 до
+появления читателя; им стал `DataTable`.
+
+**4. Новые компоненты:** `DataTable`, `TableToolbar`, `TablePreferences`,
+`FilterBar`, `FilterBarAdd`. Новые утилиты: `useTableState`,
+`tableStateToParams`, `tableStateFromParams`, `DEFAULT_TABLE_STATE`.
+
+**5. Выделение — в пределах страницы.** «Выделить всё» отмечает пришедшие
+`items`; выделения всей выборки кит не поддерживает, и подписи об этом не врут.
+Если вам нужно выделение за пределами страницы — это ваш код, а не кит.
+
+**6. Состояние переносится в URL без выделения и раскрытия.** Список ключей
+ничем не ограничен по длине, а ссылка, открытая назавтра, отметила бы записи,
+которых уже нет.
+
+## 2.1.2 — навигация в ящике мобильного режима
+
+Ломающего нет. `SideNav`, показанная `AppShell` в `Drawer`, больше не
+схлопывается: кнопки сворачивания там нет, а `collapsed` и `defaultCollapsed` в
+оверлее не действуют. Иконочный режим отдаёт ширину содержимому страницы —
+рядом с ящиком отдавать её некому.
+
+Если вы держите состояние свёрнутости у себя и оно пережило перезагрузку, поведение
+изменится к лучшему: раньше ящик открывался иконками без способа их развернуть.
+Колонка на широком экране работает как прежде; `onCollapsedChange` из ящика не
+вызывается.
+
+### Две иконки изменили вид
+
+`lucide-react` перерисовала `Calendar` и `CircleCheck` между 1.27 и 1.41 —
+у кита это `CalendarIcon` и `SuccessIcon`. Диапазон peer-зависимости
+(`^1.27.0`) не менялся, то есть **это произойдёт и без обновления кита**: любой
+потребитель, у которого `lucide-react` разрешилась в 1.41, увидит новые глифы.
+
+Действий не требуется. Строка здесь потому, что вид иконок — часть визуального
+контракта: `icons.ts` решает, какой иконкой обозначен смысл, и когда сама иконка
+перерисована, знать об этом полезно. Имена экспортов при этом целы — сторожит
+`tests/icons.test.ts`.
+
+Заодно `@playwright/test` привёз более новый Chromium, и тот иначе рисует ручку
+изменения размера у `<textarea>`. На кит это не влияет никак: элемент рисует
+браузер. Упомянуто, потому что вместе с иконками это объясняет все 38
+переписанных снимков витрины.
+
+## 2.1.1 — правки по ревью 2.1.0
+
+Четыре дефекта, найденных ревью сразу после выпуска. Ломающего нет.
+
+**1. `TopBar` терял подложку**, если потребитель передавал свой `style`:
+атрибут перезаписывался целиком, и липкая шапка с блюром показывала уезжающий
+контент насквозь. Теперь `style` потребителя дополняет подложку, а заданный
+им `background` её осознанно переопределяет.
+
+**2. `themeInitScript` не экранировал `<`.** Ключ хранилища с `</script>`
+закрывал инлайновый тег на месте. Живого XSS не было (ключ задаёт
+разработчик), но кит генерирует код под `dangerouslySetInnerHTML`, и защита
+здесь ставится по умолчанию.
+
+**3. `useAppShell` стал публичным.** Раньше `openNavigation` умел читать только
+китовый `TopBar`, и потребитель со своей шапкой получал навигацию, которую ниже
+`md` **нечем открыть**. Если у вас своя шапка — возьмите хук и нарисуйте кнопку;
+пример на странице [AppShell](../components/app-shell/app-shell.md).
+
+**4. Гейт покрытия классов** теперь видит компоненты оболочки. Попутно снят
+мёртвый класс `group` у `NavItem` — вариантов `group-*` у него нет.
+
+## 2.1.0 — оболочка приложения
+
+**Ломающего нет.** Волна только добавляет: `AppShell`, `SideNav`, `NavGroup`,
+`NavItem`, `TopBar`, реестр тем и два токена ширины. Существующий код
+продолжает работать без правок.
+
+Что стоит знать при переходе.
+
+**1. `--topbar-h` теперь может публиковать кит.** Раньше переменную объявляло
+только приложение. Если вы поставите `TopBar` кита рядом со своей шапкой,
+обе начнут писать в одну переменную. Разведите их: `heightVar="--my-topbar-h"`
+или `heightVar={null}` у той, что публиковать не должна. Приложение без `TopBar`
+кита не задето вовсе.
+
+**2. Списки тем можно перестать переписывать у себя.** `UI_THEMES`,
+`UI_ACCENTS`, `UI_BRANDS`, `normalizeTheme`, `applyTheme` и
+`themeInitScript` теперь приходят из кита. Свои константы вида
+`["light","dark","dim"]` заменяйте на них: разойтись с `styles.css` они больше
+не могут — это сторожит тест.
+
+**3. Компонента переключателя темы кит не даёт и не даст.** Готовый код двух вариантов
+переключателя — в [рецепте](../theming.md#переключатель-темы). Решение и его причины —
+ADR-0020.
+
+**4. Ширины сайдбара — токены, а не пропы.** `--sidenav-w` (240px) и
+`--sidenav-w-collapsed` (72px). Меняются в одном месте, см.
+[theming.md](../theming.md).
+
+**5. Иконка `NavigationIcon`** добавлена в `@olddevs/ui/icons` — «гамбургер»
+шапки.
+
+## Проверка перед выпуском
+
+- Проверьте, что страница компонента и каталог компонентов обновлены согласно `AGENTS.md`.
+- `npm run typecheck`, `npm test`, `npm run format:check` — API и примеры не
+  расходятся с пакетом.
+- Для изменённого взаимодействия — Storybook и целевой a11y/interaction test.
+
+## Связанные исходники
+
+- Корневой вход пакета: `src/index.ts`.
+- Иконки: `src/icons.ts`.
+- Каталог страниц компонентов: `docs/components/index.md`.