@olddevs/ui 4.3.0 → 4.4.0

package/docs/components/inputs/rich-text-editor.en.md

@@ -37,7 +37,7 @@ category: inputs
 status: stable
 source: src/editor/RichTextEditor.tsx
 story: src/editor/RichTextEditor.stories.tsx
-sourceHash: 95badb4a657c
+sourceHash: 3eaf71d10511
 ---
 
 # RichTextEditor
@@ -305,43 +305,44 @@ The `link` Tool: the "Link" button on the Toolbar and `Ctrl/⌘+K` open a popove
 
 ## Tools and Presets
 
-`preset="full"` (default) is everything in the release. `preset="basic"` is for comments and short descriptions. `tools` is an exact list and takes precedence over a Preset; descriptions of custom Tools can be mixed in with the kit's names (see the "Custom Tool" section). The type of a `tools` element is `Tool` (a kit name or a `CustomTool`), the type of a kit name is `ToolName`; both are exported from `@olddevs/ui/editor`.
+`preset="full"` (default) is everything in the release except the Table of contents `toc`: it changes the layout of the field, so it is switched on only explicitly. `preset="basic"` is for comments and short descriptions. `tools` is an exact list and takes precedence over a Preset; descriptions of custom Tools can be mixed in with the kit's names (see the "Custom Tool" section). The type of a `tools` element is `Tool` (a kit name or a `CustomTool`), the type of a kit name is `ToolName`; both are exported from `@olddevs/ui/editor`.
 
 Presets are also exported as arrays of names — `RICH_TEXT_PRESETS.full` and `RICH_TEXT_PRESETS.basic` — so that you can assemble your own set from them: `tools={[...RICH_TEXT_PRESETS.full, mergeTagTool]}`. The arrays are frozen. A Preset's content is "what the kit considers the full set", not a frozen list: a new built-in Tool arrives in a Preset in a minor version. If you need a stable set, pass an exact list of names.
 
 **A disabled Tool removes both the button and the Schema extension.** Its Block or Mark cannot be created with a keyboard shortcut, a Markdown shortcut or a paste, and from `value` they arrive without Block markup, and the text stays.
 
-| `Tool`            | Button                                 | Markup                                    | Shortcut                                          | Markdown while typing  | `basic` |
-| ----------------- | -------------------------------------- | ----------------------------------------- | ------------------------------------------------- | ---------------------- | ------- |
-| `heading`         | "¶": Heading 2–4                       | `h2`, `h3`, `h4`                          | `Ctrl/⌘+Alt+2…4`                                  | `## `, `### `, `#### ` | —       |
-| `heading1`        | "¶": adds Heading 1                    | `h1`                                      | `Ctrl/⌘+Alt+1`                                    | `# `                   | —       |
-| `history`         | Undo, Redo                             | —                                         | `Ctrl/⌘+Z`, `+Shift+Z`                            | —                      | yes     |
-| `bold`            | Bold                                   | `strong`                                  | `Ctrl/⌘+B`                                        | `**text**`             | yes     |
-| `italic`          | Italic                                 | `em`                                      | `Ctrl/⌘+I`                                        | `*text*`               | yes     |
-| `underline`       | "…": Underline                         | `u`                                       | `Ctrl/⌘+U`                                        | —                      | —       |
-| `strike`          | Strikethrough                          | `s`                                       | `Ctrl/⌘+Shift+S`                                  | `~~text~~`             | yes     |
-| `code`            | "…": Inline code                       | `code`                                    | `Ctrl/⌘+E`                                        | `` `text` ``           | yes     |
-| `superscript`     | "…": Superscript                       | `sup`                                     | `Ctrl/⌘+.`                                        | —                      | —       |
-| `subscript`       | "…": Subscript                         | `sub`                                     | `Ctrl/⌘+,`                                        | —                      | —       |
-| `clearFormatting` | "…": Clear formatting                  | — (removes Marks)                         | `Ctrl/⌘+\`                                        | —                      | —       |
-| `link`            | Link (address popover)                 | `a[href]`                                 | `Ctrl/⌘+K`                                        | `[text](url)` on paste | yes     |
-| `color`           | Color ▾ (Selection menu): "Text color" | `span[data-color]`, `span[style]`         | —                                                 | —                      | —       |
-| `highlight`       | Highlight ▾ (Toolbar), "Color ▾"       | `mark[data-color]`, `mark[style]`         | —                                                 | —                      | —       |
-| `align`           | Alignment ▾ (menu)                     | `p`, `h2`–`h4` with `data-align`          | `Ctrl/⌘+Shift+L`, `+E`, `+R`                      | —                      | —       |
-| `bulletList`      | Lists ▾: Bulleted list                 | `ul`, `li`                                | `Ctrl/⌘+Shift+8`                                  | `- ` or `* `           | yes     |
-| `orderedList`     | Lists ▾: Numbered list                 | `ol`, `li`                                | `Ctrl/⌘+Shift+7`                                  | `1. `                  | yes     |
-| `taskList`        | Lists ▾: Checklist                     | `ul[data-type=taskList]` and items        | `Ctrl/⌘+Shift+9`                                  | `[ ] ` or `[x] `       | —       |
-| `blockquote`      | "…": Quote                             | `blockquote`                              | `Ctrl/⌘+Shift+B`                                  | `> `                   | yes     |
-| `codeBlock`       | "…": Code block                        | `pre`, `code class="language-*"`          | `Ctrl/⌘+Alt+C`                                    | ` ``` `                | —       |
-| `horizontalRule`  | "+": Divider                           | `hr`                                      | —                                                 | `---`                  | —       |
-| `table`           | Table ▾ (menu)                         | `table`, `tbody`, `tr`, `th`, `td`        | `Tab`, `Shift+Tab`, `Alt+↓` in a table            | —                      | —       |
-| `image`           | Image (address popover)                | `figure`, `img`, `figcaption`             | —                                                 | `![alt](url)` on paste | —       |
-| `emoji`           | Emoji (popover with a grid)            | — (plain text)                            | —                                                 | —                      | —       |
-| `source`          | HTML (mode toggle)                     | — (edits the Document's HTML)             | —                                                 | —                      | —       |
-| `search`          | Find (find and replace panel)          | — (searches the Document)                 | `Ctrl/⌘+F`, `Ctrl/⌘+Alt+F`                        | —                      | yes     |
-| `layout`          | "+": Layout                            | `div` with `data-block` and `data-layout` | `Tab`, `Shift+Tab`, arrow keys at the column edge | —                      | —       |
-| `wrapper`         | "+": Wrapper                           | `div[data-block=wrapper]`                 | `Enter` in an empty last paragraph — exit         | —                      | —       |
-| `insertMenu`      | "+" Insert menu                        | — (Blocks of other Tools)                 | —                                                 | `/`                    | —       |
+| `Tool`            | Button                                               | Markup                                    | Shortcut                                          | Markdown while typing  | `basic` |
+| ----------------- | ---------------------------------------------------- | ----------------------------------------- | ------------------------------------------------- | ---------------------- | ------- |
+| `heading`         | "¶": Heading 2–4                                     | `h2`, `h3`, `h4`                          | `Ctrl/⌘+Alt+2…4`                                  | `## `, `### `, `#### ` | —       |
+| `heading1`        | "¶": adds Heading 1                                  | `h1`                                      | `Ctrl/⌘+Alt+1`                                    | `# `                   | —       |
+| `history`         | Undo, Redo                                           | —                                         | `Ctrl/⌘+Z`, `+Shift+Z`                            | —                      | yes     |
+| `bold`            | Bold                                                 | `strong`                                  | `Ctrl/⌘+B`                                        | `**text**`             | yes     |
+| `italic`          | Italic                                               | `em`                                      | `Ctrl/⌘+I`                                        | `*text*`               | yes     |
+| `underline`       | "…": Underline                                       | `u`                                       | `Ctrl/⌘+U`                                        | —                      | —       |
+| `strike`          | Strikethrough                                        | `s`                                       | `Ctrl/⌘+Shift+S`                                  | `~~text~~`             | yes     |
+| `code`            | "…": Inline code                                     | `code`                                    | `Ctrl/⌘+E`                                        | `` `text` ``           | yes     |
+| `superscript`     | "…": Superscript                                     | `sup`                                     | `Ctrl/⌘+.`                                        | —                      | —       |
+| `subscript`       | "…": Subscript                                       | `sub`                                     | `Ctrl/⌘+,`                                        | —                      | —       |
+| `clearFormatting` | "…": Clear formatting                                | — (removes Marks)                         | `Ctrl/⌘+\`                                        | —                      | —       |
+| `link`            | Link (address popover)                               | `a[href]`                                 | `Ctrl/⌘+K`                                        | `[text](url)` on paste | yes     |
+| `color`           | Color ▾ (Selection menu): "Text color"               | `span[data-color]`, `span[style]`         | —                                                 | —                      | —       |
+| `highlight`       | Highlight ▾ (Toolbar), "Color ▾"                     | `mark[data-color]`, `mark[style]`         | —                                                 | —                      | —       |
+| `align`           | Alignment ▾ (menu)                                   | `p`, `h2`–`h4` with `data-align`          | `Ctrl/⌘+Shift+L`, `+E`, `+R`                      | —                      | —       |
+| `bulletList`      | Lists ▾: Bulleted list                               | `ul`, `li`                                | `Ctrl/⌘+Shift+8`                                  | `- ` or `* `           | yes     |
+| `orderedList`     | Lists ▾: Numbered list                               | `ol`, `li`                                | `Ctrl/⌘+Shift+7`                                  | `1. `                  | yes     |
+| `taskList`        | Lists ▾: Checklist                                   | `ul[data-type=taskList]` and items        | `Ctrl/⌘+Shift+9`                                  | `[ ] ` or `[x] `       | —       |
+| `blockquote`      | "…": Quote                                           | `blockquote`                              | `Ctrl/⌘+Shift+B`                                  | `> `                   | yes     |
+| `codeBlock`       | "…": Code block                                      | `pre`, `code class="language-*"`          | `Ctrl/⌘+Alt+C`                                    | ` ``` `                | —       |
+| `horizontalRule`  | "+": Divider                                         | `hr`                                      | —                                                 | `---`                  | —       |
+| `table`           | Table ▾ (menu)                                       | `table`, `tbody`, `tr`, `th`, `td`        | `Tab`, `Shift+Tab`, `Alt+↓` in a table            | —                      | —       |
+| `image`           | Image (address popover)                              | `figure`, `img`, `figcaption`             | —                                                 | `![alt](url)` on paste | —       |
+| `emoji`           | Emoji (popover with a grid)                          | — (plain text)                            | —                                                 | —                      | —       |
+| `source`          | HTML (mode toggle)                                   | — (edits the Document's HTML)             | —                                                 | —                      | —       |
+| `search`          | Find (find and replace panel)                        | — (searches the Document)                 | `Ctrl/⌘+F`, `Ctrl/⌘+Alt+F`                        | —                      | yes     |
+| `layout`          | "+": Layout                                          | `div` with `data-block` and `data-layout` | `Tab`, `Shift+Tab`, arrow keys at the column edge | —                      | —       |
+| `wrapper`         | "+": Wrapper                                         | `div[data-block=wrapper]`                 | `Enter` in an empty last paragraph — exit         | —                      | —       |
+| `insertMenu`      | "+" Insert menu                                      | — (Blocks of other Tools)                 | —                                                 | `/`                    | —       |
+| `toc`             | Table of contents in the left gutter (not in `full`) | — (reads the headings)                    | —                                                 | —                      | —       |
 
 A paragraph is always there; a soft line break is `Shift+Enter`. `insertMenu` and `emoji`, like `clearFormatting`, have no markup of their own: `insertMenu` provides access to other Tools' Blocks, and it is disabled where `/` is an ordinary character (paths, "and/or"); `basic` lacks it for the same reason. `emoji` inserts plain text — the Schema, the sanitizer and Markdown do not change because of it (see the "Emoji" section); `basic` lacks it: in a comment the OS's own palette is easier to reach, and a button would take up room in a short row. `source` is the HTML mode (see the "HTML mode" section): it has no markup of its own either, an HTML edit goes through the same Schema as `value`, and it cannot be used to get around the set of Tools; `basic` lacks it — in a comment an "HTML" button is superfluous unless the screen explicitly asks for it.
 
@@ -349,7 +350,7 @@ A paragraph is always there; a soft line break is `Shift+Enter`. `insertMenu` an
 
 Earlier, "no H1 in the Document" was a kit decision (the page heading sits outside the Editor); now it is the screen's decision — ADR-0053 revises the earlier decision, and ADR-0050 links to ADR-0053.
 
-A name enters the `Tool` type together with the Tool itself, not earlier: widening the input type does not break the consumer, whereas a name without an implementation would compile and do nothing. That is how `link` arrived — straight into the `basic` Preset too — and `color`, `highlight`, `align`, `table`, `image`, `emoji`, `layout`, `wrapper`, `source`; there are no reserved names now. Unknown names in `tools` (from JS without types) are dropped silently.
+A name enters the `Tool` type together with the Tool itself, not earlier: widening the input type does not break the consumer, whereas a name without an implementation would compile and do nothing. That is how `link` arrived — straight into the `basic` Preset too — and `color`, `highlight`, `align`, `table`, `image`, `emoji`, `layout`, `wrapper`, `source`, `toc`; there are no reserved names now. Unknown names in `tools` (from JS without types) are dropped silently.
 
 `preset` and `tools` are read **when the engine is created**: the Schema of a live ProseMirror cannot be changed. To change the set on a mounted field, remount it with a key (`key`) — the edit history is lost in the process.
 
@@ -1170,6 +1171,23 @@ The `search` Tool (present in `full` and in `basic`) is find and replace over th
 
 Message catalog strings: `editor.search` (the button and the `Ctrl/⌘+F` Shortcuts reference row), `searchReplace` (`Ctrl/⌘+Alt+F`), `searchPanel`, `searchField`, `replaceField`, `searchPrevious`, `searchNext`, `searchClose`, `searchMatchCase`, `searchWholeWord`, `searchRegex`, `replaceOne`, `replaceAll`, `searchCount({ current, total })`, `searchNoMatches`, `searchInvalid`.
 
+## Table of contents
+
+The `toc` Tool puts the Table of contents of the Document in the Editor's left gutter: the same strip of strokes and the same list as [`RichTextToc`](../content/rich-text-toc.md), but the Editor holds the place itself (ADR-0068). It is in neither Preset, `full` or `basic`: the Table of contents moves the text, and a kit update does not change the layout of screens that did not ask for it. Switch it on by name:
+
+```tsx
+<RichTextEditor tools={[...RICH_TEXT_PRESETS.full, "toc"]} defaultValue={html} />
+```
+
+- **Place.** A column to the left of the Document, inside the field frame. It exists only while there is a strip, from two `h1`–`h4` headings at the top level and in Wrappers: with the second heading the text moves right; without it the text stays at the edge, as without the Tool. The first stroke is level with the first line of the first heading.
+- **Stickiness.** The strip sticks under the fixed Toolbar (and under the app header: `--topbar-h`, ADR-0016); without a Toolbar, to the edge of the window. In a field with `maxHeight` or `resizable` it sticks to the top of the scrolling area, and the highlight and the jump count from there; the page does not scroll.
+- **The list** works as in `RichTextToc`: hover opens it to the right of the strip, Enter and Space open it from the keyboard, arrows move between items, Escape closes it; the current section is highlighted in the strip and in the list; the width is 240px, and a long heading is cut with an ellipsis. A click on an item does not close the list: moving the pointer away does.
+- **A jump while editing** puts the caret at the end of the heading, so you can type right away, as in the document outline of Google Docs; the Table of contents does the scrolling, and the heading flashes a fading background. In `readOnly` there is no caret, so focus goes to the heading itself.
+- **A live Document.** The list is rebuilt shortly after each edit: a new, renamed or removed heading shows in the strip. In HTML mode there is no Table of contents, because the Document is hidden.
+- **No Toolbar button.** To show or hide the Table of contents, the screen changes `tools` (and remounts the field with a `key`, as for any set of Tools).
+
+Message catalog string: `editor.toc` ("Table of contents"), the name of the strip and the label of the list.
+
 ## Status line and Field notice
 
 Under the field inside the frame there are two independent areas. The **Status line** is what the screen puts there itself: "Saved", a word count, a co-author. The **Field notice** is what the kit and Tools report: an upload result, a paste rejection. The first is a React node in the `status` prop, the second is data and an engine command.

package/docs/components/inputs/rich-text-editor.md

@@ -304,7 +304,7 @@ import { RichTextEditor } from "@olddevs/ui/editor";
 
 ## Инструменты и Пресеты
 
-`preset="full"` (по умолчанию) — всё, что есть в выпуске. `preset="basic"` — для комментариев и коротких описаний. `tools` — точный список, сильнее Пресета; в нём вперемешку с именами кита стоят описания своих Инструментов (раздел «Свой Инструмент»). Тип элемента `tools` — `Tool` (имя кита или `CustomTool`), тип имени кита — `ToolName`; оба экспортируются из `@olddevs/ui/editor`.
+`preset="full"` (по умолчанию) — всё, что есть в выпуске, кроме Оглавления `toc`: оно меняет раскладку поля, и его включают только явно. `preset="basic"` — для комментариев и коротких описаний. `tools` — точный список, сильнее Пресета; в нём вперемешку с именами кита стоят описания своих Инструментов (раздел «Свой Инструмент»). Тип элемента `tools` — `Tool` (имя кита или `CustomTool`), тип имени кита — `ToolName`; оба экспортируются из `@olddevs/ui/editor`.
 
 Пресеты экспортируются и массивами имён — `RICH_TEXT_PRESETS.full` и `RICH_TEXT_PRESETS.basic`, чтобы собирать из них свой набор: `tools={[...RICH_TEXT_PRESETS.full, mergeTagTool]}`. Массивы заморожены. Состав Пресета — «то, что кит считает полным набором», а не замороженный список: новый встроенный Инструмент приходит в Пресет minor-версией. Нужен стабильный состав — передайте точный список имён.
 
@@ -341,6 +341,7 @@ import { RichTextEditor } from "@olddevs/ui/editor";
 | `layout`          | «+»: Раскладка                         | `div` с `data-block` и `data-layout` | `Tab`, `Shift+Tab`, стрелки у края колонки | —                            | —       |
 | `wrapper`         | «+»: Обёртка                           | `div[data-block=wrapper]`            | `Enter` в пустом последнем абзаце — выход  | —                            | —       |
 | `insertMenu`      | «+» Меню вставки                       | — (Блоки других Инструментов)        | —                                          | `/`                          | —       |
+| `toc`             | Оглавление в левом поле (не в `full`)  | — (читает заголовки)                 | —                                          | —                            | —       |
 
 Абзац есть всегда, мягкий перенос строки — `Shift+Enter`. `insertMenu` и `emoji`, как и `clearFormatting`, своей разметки не имеют: `insertMenu` даёт доступ к Блокам других Инструментов, а выключают его там, где `/` — обычный символ (пути, «и/или»); в `basic` его нет по той же причине. `emoji` вставляет обычный текст — Схема, санитайзер и Markdown от него не меняются (раздел «Эмодзи»); в `basic` его нет: в комментарии системная палитра ОС удобнее, а кнопка занимала бы место у короткого ряда. `source` — HTML-режим (раздел «HTML-режим»): своей разметки у него тоже нет, правка HTML проходит ту же Схему, что `value`, и обойти набор Инструментов им нельзя; в `basic` его нет — в комментарии кнопка «HTML» лишняя, если экран её не просил.
 
@@ -348,7 +349,7 @@ import { RichTextEditor } from "@olddevs/ui/editor";
 
 Раньше «H1 в Документе нет» было решением кита (заголовок страницы стоит вне Редактора); теперь это решение экрана — ADR-0053 пересматривает прежнее решение; ссылка на ADR-0053 стоит в ADR-0050.
 
-Имя приходит в тип `Tool` вместе с самим Инструментом, не раньше: расширение входного типа потребителя не ломает, а имя без реализации компилировалось бы и ничего не давало. Так пришли `link` — сразу и в Пресет `basic` — и `color`, `highlight`, `align`, `table`, `image`, `emoji`, `layout`, `wrapper`, `source`; зарезервированных имён сейчас нет. Неизвестные имена в `tools` (из JS без типов) отбрасываются молча.
+Имя приходит в тип `Tool` вместе с самим Инструментом, не раньше: расширение входного типа потребителя не ломает, а имя без реализации компилировалось бы и ничего не давало. Так пришли `link` — сразу и в Пресет `basic` — и `color`, `highlight`, `align`, `table`, `image`, `emoji`, `layout`, `wrapper`, `source`, `toc`; зарезервированных имён сейчас нет. Неизвестные имена в `tools` (из JS без типов) отбрасываются молча.
 
 `preset` и `tools` читаются **при создании движка**: Схему живого ProseMirror не поменять. Чтобы сменить набор у смонтированного поля, перемонтируйте его ключом (`key`) — история правок при этом теряется.
 
@@ -1169,6 +1170,23 @@ ARIA сетки — шаблон `grid` из APG: `role="grid"` → `row` → `g
 
 Строки каталога сообщений: `editor.search` (кнопка и строка Справочника сочетаний `Ctrl/⌘+F`), `searchReplace` (`Ctrl/⌘+Alt+F`), `searchPanel`, `searchField`, `replaceField`, `searchPrevious`, `searchNext`, `searchClose`, `searchMatchCase`, `searchWholeWord`, `searchRegex`, `replaceOne`, `replaceAll`, `searchCount({ current, total })`, `searchNoMatches`, `searchInvalid`.
 
+## Оглавление
+
+Инструмент `toc` — Оглавление Документа в левом поле Редактора: та же полоса штрихов и тот же список, что у [`RichTextToc`](../content/rich-text-toc.md), но место держит сам Редактор (ADR-0068). В Пресеты он не входит — ни в `full`, ни в `basic`: Оглавление сдвигает текст, и обновление кита не меняет раскладку экранов, которые его не просили. Включают его именем:
+
+```tsx
+<RichTextEditor tools={[...RICH_TEXT_PRESETS.full, "toc"]} defaultValue={html} />
+```
+
+- **Место.** Колонка слева от Документа внутри рамки поля. Она есть, только пока есть полоса — от двух заголовков `h1`–`h4` на верхнем уровне и в Обёртке: со вторым заголовком текст сдвигается вправо, без него стоит у края, как без Инструмента. Первый штрих стоит на уровне первой строки первого заголовка.
+- **Липкость.** Полоса липнет под фиксированной Панелью (и под шапкой приложения: `--topbar-h`, ADR-0016), без Панели — к краю окна. В поле с `maxHeight` или `resizable` она липнет к верху прокручиваемой области, а подсветка и переход считают от неё — страница при этом не прокручивается.
+- **Список** — как у `RichTextToc`: наведение раскрывает его справа от полосы, Enter и Space — с клавиатуры, стрелки ходят по пунктам, Escape закрывает; текущий раздел подсвечен в полосе и в списке; ширина 240px, длинный заголовок обрезан многоточием. Клик по пункту список не закрывает: его закрывает уход курсора.
+- **Переход в правке** ставит каретку в конец заголовка — можно сразу писать, как в структуре документа Google Docs; прокрутку делает Оглавление, заголовок подсвечивается гаснущим фоном. В `readOnly` каретки нет — фокус встаёт на сам заголовок.
+- **Живой Документ.** Список пересобирается на правке с короткой задержкой: новый заголовок, переименование и удаление видны в полосе. В HTML-режиме Оглавления нет — Документ скрыт.
+- **Кнопки на Панели нет.** Показать или спрятать Оглавление — смена `tools` экраном (с перемонтажом ключом, как у любого набора Инструментов).
+
+Строка каталога сообщений — `editor.toc` («Оглавление»): имя полосы и подпись списка.
+
 ## Строка статуса и Сообщение поля
 
 Под полем внутри рамки две независимые области. **Строка статуса** — то, что экран кладёт сам: «Сохранено», число слов, соавтор. **Сообщение поля** — то, что сообщают кит и Инструменты: результат загрузки, отказ вставки. Первое — React-узел пропа `status`, второе — данные и команда движка.

package/docs/conventions.en.md

@@ -0,0 +1,318 @@
+---
+sourceHash: 84104315608a
+---
+
+# General conventions for `@olddevs/ui`
+
+## Public contract
+
+The public API is the runtime exports from [`src/index.ts`](../src/index.ts), the types, the entry points
+described in the documentation, and `styles.css`. The sources in `src/components/` prove the behavior, but they
+are not an import path that consumers may use.
+
+## Semantic prop vocabulary
+
+Unless a specific page says otherwise, primitives use three independent axes:
+
+| Prop      | Values                                              | Question it answers          |
+| --------- | --------------------------------------------------- | ---------------------------- |
+| `size`    | `sm`, `md`, `lg`                                    | How large is the element?    |
+| `tone`    | `neutral`, `accent`, `success`, `warning`, `danger` | What does the state mean?    |
+| `variant` | `solid`, `soft`, `outline`, `ghost`                 | How prominent is this value? |
+
+States are named positively: `selected`, `disabled`, `loading`. A native ARIA state may use its own correct name,
+for example `checked` on a switch. Do not create alternatives such as `kind`, `status` or negative boolean props
+without a separate public decision. `active` already has one meaning, see below.
+
+Props outside the three axes repeat across several components. One concept, one name: a second component with the
+same meaning takes the name from here, and does not invent its own.
+
+| Prop         | Meaning                                                                                     | Where                                 |
+| ------------ | ------------------------------------------------------------------------------------------- | ------------------------------------- |
+| `appearance` | The form of a variant: the markup changes, not the prominence of the tone                   | `RadioGroup`, `CheckboxGroup`         |
+| `active`     | The current navigation item: `aria-current="page"`                                          | `NavItem`, `MobileTabBarItem`         |
+| `activeKey`  | The same for a data collection: the key of the current node, `aria-current="page"`          | `TreeView`                            |
+| `level`      | Heading level, `2`–`4`: the component renders a real `<h2>`–`<h4>`                          | `SectionHeader`, `NotificationCenter` |
+| `kind`       | The kind of **data**, not of an element: what value the field describes and how to enter it | `FilterField` (ADR-0063)              |
+
+- **`kind` on `FilterField` is a public decision (ADR-0063), not a workaround for the axis.**
+  `FilterField` describes a data field, not a UI element: `"values"`, `"number-range"` and `"date-range"` say
+  what value the field holds and what input sets it. It is not a presentation (`variant`) or a variant form
+  (`appearance`): a description of data has no tone and no markup. Components that draw an element still do not
+  get `kind`.
+- **`appearance`, not `variant`.** `variant` is the axis for how a tone is presented, with a closed set
+  `solid|soft|outline|ghost` across the whole kit. `appearance="card"` changes the form of the variant itself:
+  the border, the indicator and the description inside the label. Under `variant`, such a value would give the
+  axis a second meaning: `variant="card"` on one component would sit next to `variant="soft"` on another.
+- **`active`, not `selected`.** `selected` is a choice in a set (`aria-selected`, `aria-checked`): the user
+  changes it. The current section is `aria-current`: the route sets it, and the item stays a link. `active` has
+  no other values, and it does not become a synonym for `selected`. Where there are no item elements but keyed
+  data (`TreeView`), the same concept is called `activeKey`, after `selectedKeys` and `expandedKeys`: one value
+  instead of a set.
+- **`level`, not `headingLevel`.** The level depends on where the component is placed, and the consumer knows
+  that. `SectionHeader` already had a prop called `level`. A second name for the same concept would silently
+  drift from it.
+
+## Accessible name
+
+The rule comes from `Toolbar`, `Carousel`, `MobileTabBar` and `TagGroup`. Before it, these components handled the
+required name in different ways: in one, `label` was shown on screen, and in another it went into an attribute.
+
+- **`label` is only a visible caption.** A prop with this name draws text on screen. A name that is not drawn is
+  set with its own ARIA attribute.
+- **Without a visible caption, use exactly one of `aria-label` and `aria-labelledby`.** The type is
+  [`AccessibleName`](../src/lib/accessible-name.ts), a union with `never`: TypeScript rejects a call with no name
+  and a call with both. Two sources of one name drift apart silently when you edit.
+- **A name with a default from the catalog** uses `Partial<AccessibleName>`: you can pass nothing, but not both
+  (`MobileTabBar`). The default is announced even when an empty string is passed.
+- **Visible caption or attribute:** `{ label; "aria-label"?: never;
+"aria-labelledby"?: never } | ({ label?: never } & AccessibleName)` (`TagGroup`). A caption together with an
+  attribute is not allowed: the attribute would override the visible text, and a screen reader would give the
+  component a different name than the one on screen.
+- The test locks the shape with `@ts-expect-error`: for "no name" and for "both at once".
+
+Components released before this rule use `label` as the name string without a visible caption (`SideNav`,
+`TopBar`, `FilterBar`, `ScrollArea` and others). Renaming it there is a breaking change and a separate decision.
+A new component follows the rule.
+
+## Empty value
+
+An empty string is neither a caption nor a name. The rule and its history are in
+[`src/lib/empty.ts`](../src/lib/empty.ts). For a prop of type `string`, write the fallback with `||`, not `??`.
+For `ReactNode`, use `hasContent`, not `!= null`. `??` and `!= null` let `""` through: the component renders an
+empty node, stays without a name, or labels a button "Удалить: ". Each such branch is covered by a test with an
+empty string.
+
+## What the tests check
+
+A test renders the component as a consumer does (Testing Library and user-event), and checks what can be observed:
+roles, names, ARIA attributes, focus, handler calls and text. Internal state and hooks are not tested.
+
+**A class is tested only when it is the observable contract that jsdom would not otherwise see**: jsdom does not
+compute the cascade, the layout or `env()`. Examples are the tone from the dictionary (`TONE_TOKENS`,
+`CHOICE_CARD_SELECTED_BORDER`), the slide width and column count from the component dictionary, and the bar
+background inside and outside the slot (`BACKDROP_CLASS` of `MobileTabBar`). Take the expected value **from the
+dictionary, not as a literal**: a literal checks that nobody touched the string, while the dictionary checks that
+the component picked the right cell.
+
+Arbitrary layout classes (`h-7`, `rounded-full`, `ring-bg-1`) are not locked by a test. Visual snapshots guard
+them, and [`tests/class-coverage.test.ts`](../tests/class-coverage.test.ts) checks through a matrix that each
+class reaches the CSS. If such a class has an observable effect (a description inside the label, a node in the
+DOM, an attribute), test the effect.
+
+## State management
+
+Components mostly take the value and the callback from the consumer. The consumer is the only owner of domain
+state, the request, the route and validation. On a component page, always state:
+
+- the shape of the value and of the empty value (`null`, an array, a string, and so on);
+- controlled props and the callback;
+- allowed state transitions;
+- the behavior of disabled and loading;
+- the integration with a native form, if there is one.
+
+Do not infer the API from how a story looks: check the type and the source.
+
+## How to read a component page
+
+Every page must contain:
+
+1. A short answer for AI and the limits of use.
+2. The closest alternatives and what not to do.
+3. A minimal working example with the correct import.
+4. An explanation of the public props, states and events.
+5. Accessibility, the keyboard, focus and the boundary with forms.
+6. Anti-patterns, special cases and links to the source and Storybook.
+
+## Source layout
+
+A component folder in `src/components/<category>/` matches its page folder in `docs/components/<category>/`.
+There are eight categories (`actions`, `inputs`, `date-time`, `overlays`, `navigation`, `content`, `table`,
+`app-shell`). There are no files at the root of `src/components/`. Inside a category, files are flat: an internal
+part lives next to its owner. When a component changes its category, its page changes with it.
+
+In `src/editor/`, only the entry points stay at the root: `RichTextEditor`, `RichTextView` and their stories.
+Everything else is in subfolders: `core/` holds the engine and the Tool registry, `ui/` holds the shared glue code,
+`styles/` holds the styling, `hooks/` holds the hooks, and `features/<feature>/` holds the node, commands, Tool and
+UI of one feature.
+
+`index.ts` files are not allowed in categories, layers or features: imports go directly to the file. Barrel files
+are allowed only as entry points of the package. `tests/structure.test.ts` checks the layout.
+
+## Changing the API
+
+When you add or change a runtime export, update its page, its entry in the catalog and the registry in the same
+change set. A breaking change also needs an entry in `docs/api/migration-notes.md` with the action for the
+consumer. Do not hide a change behind behavior that looks similar.
+
+## User-visible strings
+
+Every label that a user sees or hears goes through the message catalog: `prop ?? messages.family.key`. The prop
+stays: it is a targeted override, not the only way.
+
+A string literal in JSX or in a prop default fails `npm test`
+([`tests/i18n-gate.test.ts`](../tests/i18n-gate.test.ts)). The exceptions are an explicit list, with the reason
+given in the gate itself (three reasons are described below), not a regexp.
+
+To add a key, see [i18n.md](i18n.md).
+
+## Language: what is in Russian, what is in English
+
+The boundary follows the audience, not the file type: this is the decision in ADR-0034.
+
+| In Russian: the kit explains to itself | In English: the kit shows to the outside                    |
+| -------------------------------------- | ----------------------------------------------------------- |
+| Comments in the sources                | Showcase: sections, story names, demo content, `aria-label` |
+| This documentation and the ADRs        | Tests: names, fixtures, data                                |
+| Text in the Figma mockups              | Script output to the console                                |
+
+Comments stay in Russian on purpose, and the i18n gate does not check them. A Russian comment above an English
+story is normal, not unfinished work.
+
+Russian is legitimate in tests where it is the **subject** of the check: the plural and case forms and the catalog
+words live in `tests/locale-ru.test.tsx`. In other tests, the expected values come from the English fallback.
+
+The gate's allowlist covers **three reasons, not three files**: the keyboard layout as input data (`Keyboard.tsx`
+and its test), the Russian catalog (`locales/ru.ts`), and a Russian word as the subject of a check
+(`locale-ru.test.tsx`, plus the `SortableList` scenario in `tests-visual/interactions.spec.ts`, where react-aria
+localizes the announcements itself). A fourth reason is a case for review, not a reason to change the number.
+
+## Showcase story names
+
+Section and story names are in Latin script. They make up the story `id`, and the `id` gives the name of the
+snapshot file and its address in `tests-visual`. Renaming costs a baseline regeneration, so pick the name once.
+
+A component's section is its category: the folder of its page in the Reference and of its source (ADR-0060). The
+story `src/components/overlays/Dialog.stories.tsx` is named `Overlays/Dialog`. Editor stories take their section
+from the folder of their own page: `Inputs/RichTextEditor`, `Content/RichTextView`.
+
+| Section          | What is inside                                              |
+| ---------------- | ----------------------------------------------------------- |
+| `Actions/`       | Actions and feedback: `Actions/Button`, `Actions/Alert`     |
+| `Inputs/`        | Fields and choice: `Inputs/Select`, `Inputs/RichTextEditor` |
+| `Date and time/` | Calendars and date and time pickers                         |
+| `Overlays/`      | Dialogs, drawers, popovers, menus, tooltips                 |
+| `Navigation/`    | Tabs, breadcrumbs, page and section headers                 |
+| `Content/`       | Typography, cards, data, states, layout                     |
+| `Table/`         | The data table and its panels                               |
+| `App shell/`     | App shell: `AppShell`, `SideNav`, `TopBar`                  |
+| `Foundations/`   | Basics: icons, motion                                       |
+| `Screens/`       | Assembled screens                                           |
+
+**Dictionary of repeated names.** A name that appears a second time must be added here. Otherwise the same case
+gets two different names in two files, and they drift apart silently.
+
+| Name              | When                                                   |
+| ----------------- | ------------------------------------------------------ |
+| `Playground`      | The main story with controls                           |
+| `Matrix`          | All variants side by side; captured by the visual test |
+| `Empty`           | Empty state                                            |
+| `Disabled`        | Disabled state                                         |
+| `WithError`       | Validation error                                       |
+| `WithAction`      | With an action button                                  |
+| `WithSelection`   | With a selection                                       |
+| `Sizes`           | Size scale                                             |
+| `Horizontal`      | Horizontal layout                                      |
+| `Compact`         | Dense layout                                           |
+| `SizesAndStates`  | Sizes and states side by side                          |
+| `Collapsed`       | Collapsed navigation state                             |
+| `Submitting`      | The form is being submitted                            |
+| `InForm`          | The component inside a form                            |
+| `AsPage`          | Full-screen variant                                    |
+| `WithoutTitle`    | Without a title                                        |
+| `States`          | A set of states side by side                           |
+| `Filled`          | The field is completely filled                         |
+| `Open`            | An expanded list or calendar                           |
+| `Tones`           | Tone scale                                             |
+| `WithLabel`       | With a visible label                                   |
+| `Cards`           | Choice variants shown as cards (`appearance="card"`)   |
+| `CardsHorizontal` | Choice cards in a row                                  |
+| `CardsStates`     | States of choice cards side by side                    |
+| `CardsTones`      | Tone scale of choice cards                             |
+| `Controlled`      | Controlled mode: the story holds the value             |
+| `Wrapping`        | Wrapping at a narrow width                             |
+| `Vertical`        | Vertical layout                                        |
+| `Badges`          | All kinds of badge side by side                        |
+
+Single-word names describe the **case**, not translate a word: a story about how a component differs from its
+neighbors is called `VersusNeighbours`, not a transliteration of a Russian heading.
+
+**Snapshot width is set by a story tag.** The visual test takes a snapshot of a story at 1280×900. A story that
+shows a narrow screen sets the tag `tags: ["viewport-phone"]` on itself, and it is captured at 375×812 with an
+emulated screen cutout at the bottom (34px). It is a tag, not a parameter: the spec reads stories from
+`storybook-static/index.json`, which has no parameters. The first such story is `AppShell` → `WithBottomBar`: at
+1280px the slot hides the bar.
+
+**A lazy chunk that loads after the story is shown is also set by a tag.** The snapshot waits for two identical
+frames in a row. While a chunk is in transit, the screen does not change, and the snapshot takes a story that is
+not fully loaded for a finished one. A story part of which arrives as a lazy chunk after it is shown sets the tag
+`tags: ["network-idle"]`: the snapshot and the axe audit wait for the network to be quiet. The first such stories
+are `RichTextEditor` → `TextCardOpen` and `TextCardRussian`: the chunk of the Text card is requested only after the
+engine reaches Readiness.
+
+**A story name must not match the name of the imported component.** A story about `Separator` in
+`Separator.stories.tsx` must not be called `Separator`: the export shadows the import, and `tsc` fails with
+`cannot be used as a JSX component`. It fails only where the component is used as JSX. Hence the names
+`Separators`, `Scrolling`, `HiddenContent`, `BasicTable`.
+
+## Warnings in development mode
+
+The first such warning is on `NotificationItem`, which gets both `onAction` and `actions`. The rules come from it,
+and they are written here so the next author does not invent their own.
+
+**When to warn.** Only when a contract is broken that **types catch but a consumer in JS does not**, and the
+component silently picks one reading of it (mutually exclusive props, where one of them is ignored). Do not warn
+about style, non-optimal use, deprecation (for that, use `migration-notes.md`), or what React or `react-aria`
+already catches itself. A violation after which the component cannot work is not a warning but an exception (like
+`HoverCardContent` outside `HoverCard`).
+
+**How.**
+
+- Through [`devWarn(message)`](../src/lib/dev-warn.ts), not a bare `console.warn`. The helper shows the message
+  **once** (the key is the text) and **does not write in production**. The call sits in the render body, so
+  showing once is required: a list row renders hundreds of times, and `StrictMode` calls the render twice.
+- The text is **in English**, because it is output to the consumer's console (ADR-0034). It does not go into the
+  message catalog, because it is not an interface string. The text names the component, the value that was
+  passed, the value that won, and how to fix it. Keep changing data out of it: the deduplication key is the text
+  itself.
+- The mode is read as `process.env.NODE_ENV !== "production"` inside `try/catch`, on every call. The package
+  ships as plain `tsc` output, and the value is not baked into `dist`. The consumer's build sets it (Vite, Next,
+  webpack) and removes the dead branch in production. Without a bundler, `process` is not defined: a reference to
+  it throws a `ReferenceError`, and the helper stays silent. The check `typeof process !== "undefined"` does not
+  work: the bundler does not replace it, so in a Vite browser build the warning would never fire.
+- Test: `vi.spyOn(console, "warn")`, `resetDevWarnings()` in `beforeEach` (the "already shown" state lives at
+  module level), and four cases: it warns in development, it warns once, it stays silent in production
+  (`vi.stubEnv`), and it stays silent on a correct call.
+
+**An error instead of a warning: `devError(message, cause?)`.** Use it when a violation breaks the whole component
+but not the page: the Tool set of `RichTextEditor` is built incorrectly, the loader of an engine part failed,
+`rangeAt` of the Text card threw an exception. The field shows the author a catalog string on its own, and the
+cause goes to the developer through `console.error`, with the same rules as `devWarn`: in development, once per
+text, in English.
+
+- The text starts with the component name (`RichTextEditor: …`), because the console is shared by the whole page.
+  A Tool name or an entry name in the text is allowed: it comes from the Tool's description and does not change
+  from call to call.
+- A caught exception goes in as the second argument (`cause`), not in the text. Its message would make every error
+  new for the once-per-text key. The console also shows the stack for an `Error` object.
+- The test follows the same pattern with `vi.spyOn(console, "error")`: an error in development with the exception
+  as a separate argument, once; silence in production (`vi.stubEnv`); and silence on a correct call
+  (`tests/rich-text-editor-dev-errors.test.tsx`).
+
+## `readOnly` and `disabled` are separate axes, not shades of one
+
+The rule comes from `Rating` (wave 25). It is written here because the next author would not find it in one
+component's docstring, and a second `readOnly` in the kit would then mean something of its own.
+
+- **`readOnly` is data on display.** The value is visible, and it cannot be changed. Such a value must not be
+  dimmed: that would hide what is shown on purpose. The control leaves the tab order, but stays at full strength.
+- **`disabled` is an action that is unavailable right now.** It is dimmed, because dimming is the signal that it
+  is unavailable.
+
+**The role does not change.** A disabled control stays what it was and is marked with `aria-disabled`. Swapping the
+role (for example, to `img`) would be read as a picture, not as an unavailable action. The role is a property of
+the control, not of its availability right now.
+
+## Editor glossary
+
+The Editor terms moved to the kit's shared [glossary](glossary.md#редактор).

package/docs/getting-started.en.md

@@ -1,5 +1,5 @@
 ---
-sourceHash: fdfa8cd8c38b
+sourceHash: d61bd1f3cca7
 ---
 
 # Setting up `@olddevs/ui`
@@ -133,9 +133,9 @@ peer dependencies are treated as external, and the metric is gzip:
 | one `Button`                                                                                             | 1.6 kB   |
 | `DataTable`                                                                                              | 9.0 kB   |
 | the whole kit (`import *`)                                                                               | 77.1 kB  |
-| `RichTextEditor` from `@olddevs/ui/editor`, without the engine, "start"                                  | 70.6 kB  |
-| `RichTextEditor` with the Tiptap engine, "start" (static graph, `basic`)                                 | 295.3 kB |
-| `RichTextEditor` with the Tiptap engine, "full" (with all lazy chunks, `full`)                           | 339.1 kB |
+| `RichTextEditor` from `@olddevs/ui/editor`, without the engine, "start"                                  | 71.3 kB  |
+| `RichTextEditor` with the Tiptap engine, "start" (static graph, `basic`)                                 | 296 kB   |
+| `RichTextEditor` with the Tiptap engine, "full" (with all lazy chunks, `full`)                           | 344.2 kB |
 | `RichTextView` from `@olddevs/ui/editor`, Tiptap engine included in the measurement                      | 12.0 kB  |
 | `sanitizeRichText` and `richTextSanitizeConfig` from `@olddevs/ui/editor/schema`, Tiptap engine included | 3.6 kB   |
 | `highlightCodeBlocks` from `@olddevs/ui/editor/highlight`, with lowlight                                 | 22.6 kB  |

package/docs/getting-started.md

@@ -130,9 +130,9 @@ peer-зависимости внешние, метрика gzip:
 | одна `Button`                                                                                               | 1,6 кБ   |
 | `DataTable`                                                                                                 | 9,0 кБ   |
 | весь кит целиком (`import *`)                                                                               | 77,1 кБ  |
-| `RichTextEditor` из `@olddevs/ui/editor`, без движка, «старт»                                               | 70,6 кБ  |
-| `RichTextEditor` вместе с движком Tiptap, «старт» (статический граф, `basic`)                               | 295,3 кБ |
-| `RichTextEditor` вместе с движком Tiptap, «полный» (со всеми ленивыми чанками, `full`)                      | 339,1 кБ |
+| `RichTextEditor` из `@olddevs/ui/editor`, без движка, «старт»                                               | 71,3 кБ  |
+| `RichTextEditor` вместе с движком Tiptap, «старт» (статический граф, `basic`)                               | 296 кБ   |
+| `RichTextEditor` вместе с движком Tiptap, «полный» (со всеми ленивыми чанками, `full`)                      | 344,2 кБ |
 | `RichTextView` из `@olddevs/ui/editor`, движок Tiptap в замер включён                                       | 12,0 кБ  |
 | `sanitizeRichText` и `richTextSanitizeConfig` из `@olddevs/ui/editor/schema`, движок Tiptap в замер включён | 3,6 кБ   |
 | `highlightCodeBlocks` из `@olddevs/ui/editor/highlight`, вместе с lowlight                                  | 22,6 кБ  |

package/docs/glossary.en.md

@@ -1,5 +1,5 @@
 ---
-sourceHash: eb21f7a757f6
+sourceHash: 88701a1373b4
 ---
 
 # Glossary of `@olddevs/ui`
@@ -140,6 +140,7 @@ introduces a second meaning.
 | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Editor**               | `RichTextEditor` — a rich text input field                                                                                                                                                                                                                                                                                                                     | A code editor: the kit has none, code is displayed with `CodeView`                                                                                                            |
 | **View**                 | `RichTextView` — read-only display of a saved Document                                                                                                                                                                                                                                                                                                         | The Editor's `readOnly` mode: that one carries the engine, the View does not                                                                                                  |
+| **Table of contents**    | `RichTextToc`: the list of a Document's headings next to the View or the Editor. Collapsed, it is a strip of strokes; expanded, a list; a click on an item goes to the heading                                                                                                                                                                                 | The kit's `Heading` and the navigation of the documentation site                                                                                                              |
 | **Document**             | The Editor's value: an HTML string constrained by the Schema                                                                                                                                                                                                                                                                                                   | The ProseMirror JSON tree in the engine — it is internal; it comes out only as a JSON envelope                                                                                |
 | **JSON envelope**        | A Document as JSON for a file and a template: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), lossless and through the Schema                                                                                                                                                                                      | The Editor's value — the value stays HTML; the bare tree `editor.getJSON()` without an envelope                                                                               |
 | **Schema**               | An allowlist of Blocks, Marks and attributes that the Editor accepts and returns                                                                                                                                                                                                                                                                               | Server-side sanitization — the consumer does it (`sanitizeRichText`)                                                                                                          |

package/docs/glossary.md

@@ -135,6 +135,7 @@
 | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Редактор**             | `RichTextEditor` — поле ввода форматированного текста                                                                                                                                                                                                                                                                                              | Редактором кода: его в ките нет, показ кода — `CodeView`                                                                                                             |
 | **Просмотр**             | `RichTextView` — только чтение сохранённого Документа                                                                                                                                                                                                                                                                                              | `readOnly`-режимом Редактора: тот держит движок, Просмотр — нет                                                                                                      |
+| **Оглавление**           | `RichTextToc`: список заголовков Документа рядом с Просмотром или Редактором. Свёрнуто — полоса штрихов, раскрыто — список, клик по пункту ведёт к заголовку                                                                                                                                                                                       | `Heading` кита и навигацией сайта документации                                                                                                                       |
 | **Документ**             | Значение Редактора: HTML-строка, ограниченная Схемой                                                                                                                                                                                                                                                                                               | JSON-деревом ProseMirror в движке — оно внутреннее; наружу оно выходит только JSON-конвертом                                                                         |
 | **JSON-конверт**         | Документ как JSON для файла и шаблона: `{ format: "olddevs-rich-text", version, doc }` (`getJSON()`, `setJSON()`, `defaultValue`), без потерь и через Схему                                                                                                                                                                                        | Значением Редактора — значение остаётся HTML; голым деревом `editor.getJSON()` без конверта                                                                          |
 | **Схема**                | Белый список Блоков, Меток и атрибутов, которые Редактор принимает и отдаёт                                                                                                                                                                                                                                                                        | Санитизацией на сервере — её делает потребитель (`sanitizeRichText`)                                                                                                 |