@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/i18n.en.md

@@ -0,0 +1,147 @@
+---
+sourceHash: 937d4d336a89
+---
+
+# Localization: provider and message catalog
+
+Since 2.0.0 the kit defaults to English and supports other languages. Before 2.0.0
+Russian labels were hard-coded into prop defaults, and another language meant passing a
+label at every call site.
+
+## How a string is resolved
+
+```
+component prop  →  provider message  →  English fallback in code
+```
+
+The prop always wins: it is a targeted override, not the only way.
+The fallback lives in the code and in the bundle — without it a component with no provider would render
+nothing instead of a label.
+
+## Setup
+
+The kit **does not load message catalogs automatically** — otherwise Russian would end up in everyone's bundle,
+including those who only need English. A message catalog is imported explicitly:
+
+```tsx
+import { UiProvider } from "@olddevs/ui";
+import ru from "@olddevs/ui/locales/ru";
+
+<UiProvider locale="ru-RU" messages={ru}>
+  <App />
+</UiProvider>;
+```
+
+Both props are needed, and each does a different job:
+
+| Prop       | What it is responsible for                              | Without it                             |
+| ---------- | ------------------------------------------------------- | -------------------------------------- |
+| `messages` | the kit's labels                                        | English strings from the fallback      |
+| `locale`   | date, number and unit formats and plural form selection | the locale comes from above, see below |
+
+`messages` without `locale` produces Russian labels with dates in the browser's format — almost
+certainly not what you need.
+
+You do not need to set up English: it is the fallback. `@olddevs/ui/locales/en`
+exists for symmetry — code that picks a message catalog by the user's language
+should not stumble on one language having an import and another not.
+
+## Partial override
+
+A message catalog can be supplied in pieces: the fallback fills in any branches you omit.
+
+```tsx
+<UiProvider messages={{ confirmDialog: { confirm: "Yes, delete" } }}>
+```
+
+A nested `UiProvider` inherits everything from the outer one and overrides what it sets
+itself, so a dialog can have its own locale inside an app that uses another language.
+
+## If you already have an `I18nProvider` from react-aria
+
+A common case: the app has its own `I18nProvider` because it uses
+react-aria directly. The kit does not conflict with it.
+
+**Without `locale` the kit does not mount its own `I18nProvider` at all** — the locale is taken
+from yours. This is deliberate: a kit that forced `en-US` would make
+date pickers use a different language from the rest of the app.
+
+```tsx
+<I18nProvider locale="de-DE">
+  <UiProvider messages={de}>…</UiProvider>
+</I18nProvider>
+```
+
+Here dates and calendars are German, and labels come from your message catalog. Pass
+`locale` to `UiProvider` only if you want to override the outer locale for a subtree.
+
+## Without a provider
+
+The kit works this way too: all strings are English, date formats come from the browser's locale.
+You do not need to wrap a single button separately.
+
+## What does not count as translation
+
+Three things bypass the message catalog on purpose:
+
+- **The `Keyboard` layout.** The array `["Й","Ц","У",…]` defines which characters the
+  keyboard enters, not which language it is labeled in. `layout="ru"` works
+  with `locale="en"` and vice versa.
+- **Units of measure.** File size is formatted with `Intl.NumberFormat` and
+  `style: "unit"`: "МБ" and "MB" are one unit by the rules of the locale, not two
+  strings to translate.
+- **Exception messages.** `throw new Error("Unknown period")` is read by a developer
+  in a stack trace, not by a user on screen.
+
+## How to add a string
+
+1. A key in [`src/i18n/messages.ts`](../src/i18n/messages.ts) — in the namespace
+   of its family; if a label means the same thing in two places, it goes to
+   `common` and is not duplicated.
+2. A value in [`src/i18n/defaults.ts`](../src/i18n/defaults.ts) (English) and in
+   [`src/locales/ru.ts`](../src/locales/ru.ts).
+3. In the component — `useMessages()`, and `prop ?? messages.family.key`.
+
+A parameterized message is a **function**, not an ICU MessageFormat template:
+`collapsed: ({ count }) => …`. `Intl.PluralRules` handles pluralization inside the locale
+file: the locale knows the rules, not the component. A component that counts word endings
+supports only one language.
+
+The gate [`tests/i18n-gate.test.ts`](../tests/i18n-gate.test.ts) fails on both a
+literal that bypasses the message catalog and a key missing from the Russian locale.
+
+## Hooks
+
+| Hook            | What it returns                                                              |
+| --------------- | ---------------------------------------------------------------------------- |
+| `useMessages()` | the whole message catalog; read `messages.pagination.next`, not a string key |
+| `useUiLocale()` | the locale for `Intl`: explicit → the consumer's `I18nProvider` → browser    |
+| `useUiConfig()` | `dir`, the portal container and the default density                          |
+
+## Density
+
+Since 2.2.0 `UiProvider` accepts `density` — `"comfortable"` or `"compact"`.
+This is a **default, not a mode**: the `DataTable` prop and the table state override the value, while the
+provider saves an app with five tables from five identical props.
+
+The resolution chain works the same way as for message catalog strings:
+
+```
+DataTable prop → table state → provider → kit default (comfortable)
+```
+
+The prop appeared only in 2.2.0, although it was promised as early as 2.0.0:
+ADR-0002
+postponed it until a reader appeared, and `DataTable` became one. Details —
+ADR-0023.
+
+## RTL
+
+`UiProvider` accepts `dir` and exposes it, but **the kit has no component-level RTL (right-to-left writing) support**:
+no component mirrors its layout. The prop exists so that the contract
+does not have to be broken when a requesting screen appears. Until then, `dir="rtl"` changes
+only what you do with that value yourself.
+
+## See also
+
+- [Full catalog of keys](api/messages.md) — part of the public API.

package/docs/i18n.md

@@ -0,0 +1,143 @@
+# Локализация: провайдер и каталог сообщений
+
+С 2.0.0 кит говорит по-английски по умолчанию и знает про другие языки. До 2.0.0
+русские подписи были зашиты в дефолты пропсов, и другой язык означал передать
+подпись в каждом месте вызова.
+
+## Порядок разрешения строки
+
+```
+проп компонента  →  сообщение провайдера  →  английский фолбэк в коде
+```
+
+Проп побеждает всегда: он точечное переопределение, а не единственный способ.
+Фолбэк лежит в коде и в бандле — без него компонент без провайдера рисовал бы
+пустоту вместо подписи.
+
+## Подключение
+
+Кит **не грузит каталоги сам** — иначе русский оказался бы в бандле у всех,
+включая тех, кому нужен только английский. Каталог импортируется явно:
+
+```tsx
+import { UiProvider } from "@olddevs/ui";
+import ru from "@olddevs/ui/locales/ru";
+
+<UiProvider locale="ru-RU" messages={ru}>
+  <App />
+</UiProvider>;
+```
+
+Оба пропа нужны и отвечают за разное:
+
+| Проп       | За что отвечает                                   | Без него                         |
+| ---------- | ------------------------------------------------- | -------------------------------- |
+| `messages` | подписи кита                                      | английские строки из фолбэка     |
+| `locale`   | формат дат, чисел, единиц и выбор формы склонения | локаль приходит сверху, см. ниже |
+
+`messages` без `locale` даёт русские подписи с датами в формате браузера — почти
+наверняка не то, что нужно.
+
+Английский подключать не требуется: он и есть фолбэк. `@olddevs/ui/locales/en`
+существует ради симметрии — код, выбирающий каталог по языку пользователя, не
+должен спотыкаться на том, что для одного языка импорт есть, а для другого нет.
+
+## Частичное переопределение
+
+Каталог можно донести кусками: недоданные ветки берутся из фолбэка.
+
+```tsx
+<UiProvider messages={{ confirmDialog: { confirm: "Yes, delete" } }}>
+```
+
+Вложенный `UiProvider` наследует всё от внешнего и переопределяет то, что задал
+сам, поэтому окно со своей локалью работает внутри приложения на другом языке.
+
+## Если у вас уже есть `I18nProvider` из react-aria
+
+Обычный случай: приложение держит свой `I18nProvider`, потому что использует
+react-aria напрямую. Кит с ним не спорит.
+
+**Без `locale` кит не разворачивает свой `I18nProvider` вовсе** — локаль берётся
+у вашего. Это сделано намеренно: кит, навязывающий `en-US`, заставил бы
+датапикеры говорить не на языке остального приложения.
+
+```tsx
+<I18nProvider locale="de-DE">
+  <UiProvider messages={de}>…</UiProvider>
+</I18nProvider>
+```
+
+Здесь даты и календари будут немецкими, подписи — из вашего каталога. Передайте
+`locale` в `UiProvider`, только если хотите перебить внешнюю локаль для поддерева.
+
+## Без провайдера
+
+Кит работает и так: все строки английские, форматы дат — из локали браузера.
+Отдельно оборачивать одну кнопку не нужно.
+
+## Что не считается переводом
+
+Три вещи проходят мимо каталога намеренно:
+
+- **Раскладка `Keyboard`.** Массив `["Й","Ц","У",…]` говорит, какие символы
+  клавиатура вводит, а не на каком языке она подписана. `layout="ru"` работает
+  при `locale="en"` и наоборот.
+- **Единицы измерения.** Размер файла форматируется `Intl.NumberFormat` со
+  `style: "unit"`: «МБ» и «MB» — одна единица по правилам локали, а не две
+  строки для перевода.
+- **Тексты исключений.** `throw new Error("Unknown period")` читает разработчик
+  в стектрейсе, а не пользователь на экране.
+
+## Как добавить строку
+
+1. Ключ в [`src/i18n/messages.ts`](../src/i18n/messages.ts) — в пространство
+   имён своей семьи; если подпись значит то же самое в двух местах, она идёт в
+   `common` и не дублируется.
+2. Значение в [`src/i18n/defaults.ts`](../src/i18n/defaults.ts) (английское) и в
+   [`src/locales/ru.ts`](../src/locales/ru.ts).
+3. В компоненте — `useMessages()`, и `проп ?? messages.семья.ключ`.
+
+Параметризованное сообщение — **функция**, а не шаблон в формате ICU MessageFormat:
+`collapsed: ({ count }) => …`. Склонение делает `Intl.PluralRules` внутри файла
+локали: правила знает локаль, а не компонент. Компонент, считающий окончания,
+умеет ровно один язык.
+
+Гейт [`tests/i18n-gate.test.ts`](../tests/i18n-gate.test.ts) падает и на
+литерале мимо каталога, и на ключе, забытом в русской локали.
+
+## Хуки
+
+| Хук             | Что даёт                                                              |
+| --------------- | --------------------------------------------------------------------- |
+| `useMessages()` | весь каталог; читайте `messages.pagination.next`, а не строковый ключ |
+| `useUiLocale()` | локаль для `Intl`: явная → `I18nProvider` потребителя → браузер       |
+| `useUiConfig()` | `dir`, контейнер порталов и плотность по умолчанию                    |
+
+## Плотность
+
+С 2.2.0 `UiProvider` принимает `density` — `"comfortable"` или `"compact"`.
+Это **умолчание, а не режим**: проп `DataTable` и состояние таблицы значение перекрывают, а
+провайдер избавляет приложение с пятью таблицами от пяти одинаковых пропов.
+
+Цепочка разрешения устроена так же, как у строк каталога:
+
+```
+проп DataTable → состояние таблицы → провайдер → умолчание кита (comfortable)
+```
+
+Проп `density` появился только в 2.2.0, хотя обещан был ещё в 2.0.0:
+ADR-0002
+откладывал его до появления читателя, и `DataTable` им стал. Разбор —
+ADR-0023.
+
+## RTL
+
+`UiProvider` принимает `dir` и публикует его, но **компонентной поддержки RTL (письма
+справа налево) в ките нет**: ни один компонент не отражает раскладку. Проп заведён, чтобы контракт
+не пришлось ломать, когда заказчик появится. Пока его нет, `dir="rtl"` изменит
+только то, что вы сделаете с этим значением сами.
+
+## См. также
+
+- [Полный каталог ключей](api/messages.md) — часть публичного API.

package/docs/icons.en.md

@@ -0,0 +1,252 @@
+---
+entrypoint: "@olddevs/ui/icons"
+source: src/icons.ts
+status: stable
+sourceHash: 8278117a8e97
+---
+
+# Icons `@olddevs/ui/icons`
+
+## Summary for AI
+
+Import icons only from `@olddevs/ui/icons`, choosing the name by the meaning of the action
+or entity: `DeleteIcon`, not a shape such as `Trash`. The vocabulary's geometry
+comes from `lucide-react`; the package vocabulary fixes one system-wide meaning.
+
+## When to use
+
+- When the UI already has a commonly understood meaning: close, delete, search,
+  settings, error, success, switch theme, and so on.
+- When you need one consistent symbol for one action across all screens.
+- With `Button` for an icon without text: be sure to give the button itself an accessible
+  name (`aria-label`) and make the icon decorative with `aria-hidden`.
+
+## When not to use
+
+- Do not import icons from `lucide-react` under their shape names (`Trash`) for a meaning
+  the vocabulary already has. Otherwise a later change of metaphor will not be
+  centralized.
+- Do not pick an icon by a similar outline: `CheckIcon` means a checked
+  item, `SuccessIcon` a successful result; `DeleteIcon` means delete,
+  `CloseIcon` means close.
+- Do not rely on an icon as the only label of an unfamiliar action.
+  Add visible text, a tooltip or an accessible name suited to the context.
+
+## Minimal example
+
+```tsx
+import { Button } from "@olddevs/ui";
+import { DeleteIcon, SearchIcon } from "@olddevs/ui/icons";
+
+<Button aria-label="Delete campaign" tone="danger" variant="ghost">
+  <DeleteIcon aria-hidden />
+</Button>
+<SearchIcon aria-hidden size={16} />
+```
+
+## Entry point contract
+
+- The public entry point is `@olddevs/ui/icons`; do not import `src/icons.ts` or
+  `lucide-react` through the package's internal paths.
+- Vocabulary names end in `Icon`; a test guarantees that every export
+  resolves to a component of the installed `lucide-react` version.
+- Size, stroke width and color are not fixed by the vocabulary. The consumer sets them
+  through Lucide props or `LucideProvider`.
+- The `IconProps` type is also exported — it is `LucideProps` from `lucide-react`.
+
+## Semantic differences
+
+| Meaning needed                      | Use                                             | Do not substitute              |
+| ----------------------------------- | ----------------------------------------------- | ------------------------------ |
+| Close a panel, dialog or tag        | `CloseIcon`                                     | `DeleteIcon`                   |
+| Delete an entity                    | `DeleteIcon`                                    | `CloseIcon`                    |
+| Checked checkbox or choice          | `CheckIcon`                                     | `SuccessIcon`                  |
+| Successful outcome of an operation  | `SuccessIcon`                                   | `CheckIcon`                    |
+| Report an error                     | `ErrorIcon`                                     | `WarningIcon`                  |
+| Find visually similar               | `FindSimilarIcon`                               | the generic `SearchIcon`       |
+| External link                       | `ExternalLinkIcon`                              | `LinkIcon`                     |
+| Sign out of the account             | `LogoutIcon`                                    | `CloseIcon`                    |
+| List of records                     | `ListIcon`                                      | `NavigationIcon`               |
+| A goal being pursued                | `TargetIcon`                                    | `PlayIcon`                     |
+| Pause the countdown                 | `PauseIcon`                                     | `CloseIcon`                    |
+| Started work (a status flag)        | `FirstStepIcon`                                 | `PlayIcon`                     |
+| Health as a task topic              | `HealthIcon`                                    | `FavoriteIcon`                 |
+| A letter as a task topic            | `MailIcon`                                      | `SendIcon`                     |
+| A trip as a task topic              | `TripIcon`                                      | `SendIcon`                     |
+| Reading as a task topic             | `ReadingIcon`                                   | `LibraryIcon`                  |
+| A meeting as a task topic           | `MeetingIcon`                                   | `ProfileIcon`, `CalendarIcon`  |
+| Development as a task topic         | `CodeIcon`                                      | `AutomationIcon`               |
+| A due date to meet                  | `DeadlineIcon`                                  | `CalendarIcon`, `BellIcon`     |
+| Repeats according to a rule         | `RecurringIcon`                                 | `RefreshIcon`                  |
+| Help, reference                     | `HelpIcon`                                      | `InfoIcon`                     |
+| Tip                                 | `TipIcon`                                       | `InfoIcon`                     |
+| Back through history                | `BackIcon`                                      | `ChevronLeftIcon`              |
+| Home, the app root                  | `HomeIcon`                                      | `DashboardIcon`                |
+| Sort                                | `SortIcon`                                      | `SelectIcon`                   |
+| Undo an action                      | `UndoIcon`                                      | `RefreshIcon`                  |
+| Redo what was undone                | `RedoIcon`                                      | `RecurringIcon`                |
+| Adjust the view                     | `AdjustIcon`                                    | `SettingsIcon`, `FilterIcon`   |
+| Share                               | `ShareIcon`                                     | `SendIcon`, `UploadIcon`       |
+| Attachment                          | `AttachmentIcon`                                | `LinkIcon`                     |
+| Locked, read-only                   | `LockIcon`                                      | `SecurityIcon`                 |
+| Team, members                       | `TeamIcon`                                      | `ProfileIcon`, `MeetingIcon`   |
+| Time in general                     | `TimeIcon`                                      | `DeadlineIcon`                 |
+| Flag a problem                      | `FlagIcon`                                      | `FirstStepIcon`                |
+| Forbidden                           | `BlockedIcon`                                   | `ErrorIcon`                    |
+| Inline code (a Mark in text)        | `InlineCodeIcon`                                | `CodeIcon`, `CodeBlockIcon`    |
+| The Document's source HTML          | `SourceIcon`                                    | `CodeBlockIcon`, `CodeIcon`    |
+| Bulleted list in text               | `ListIcon`                                      | `TaskListIcon`                 |
+| Checklist                           | `TaskListIcon`                                  | `ListIcon`, `SuccessIcon`      |
+| Divider between Blocks              | `DividerIcon`                                   | `MinusIcon`                    |
+| Clear formatting                    | `ClearFormattingIcon`                           | `DeleteIcon`                   |
+| Text color                          | `TextColorIcon`                                 | `PaletteIcon`                  |
+| Marker (colored fill)               | `HighlightIcon`                                 | `TextColorIcon`                |
+| Plain paragraph, "just text"        | `ParagraphIcon`                                 | `HeadingIcon`                  |
+| Heading of level 1–4                | `Heading1Icon` … `Heading4Icon`                 | `HeadingIcon`                  |
+| "Text" in the Block type menu       | `TextIcon`                                      | `ParagraphIcon`, `HeadingIcon` |
+| Insert a row above / below          | `InsertRowAboveIcon`, `InsertRowBelowIcon`      | `AddIcon`                      |
+| Insert a column left / right        | `InsertColumnLeftIcon`, `InsertColumnRightIcon` | `ColumnsIcon`                  |
+| Merge table cells                   | `MergeCellsIcon`                                | `TableIcon`                    |
+| Split a merged cell                 | `SplitCellIcon`                                 | `TableIcon`                    |
+| First row is headings               | `HeaderRowIcon`                                 | `TableIcon`                    |
+| Emoji (symbol grid)                 | `EmojiIcon`                                     | —                              |
+| Vertical "more": the Block menu     | `MoreVerticalIcon`                              | `MoreIcon`, `DragHandleIcon`   |
+| Duplicate next to the original      | `DuplicateIcon`                                 | `CopyIcon`                     |
+| Arrow up / down                     | `ArrowUpIcon`, `ArrowDownIcon`                  | `ChevronUpIcon`, `SortIcon`    |
+| Document Layout in columns          | `ColumnLayoutIcon`                              | `ColumnsIcon`                  |
+| Wrapper: a group of Blocks          | `WrapperIcon`                                   | `ColumnLayoutIcon`             |
+| Remove the Wrapper, keep the Blocks | `UnwrapIcon`                                    | `DeleteIcon`                   |
+
+## Subject topics
+
+Since 3.21.0 the vocabulary has a section that describes not the interface but **what a task
+is about**: `CodeIcon`, `GameIcon`, `PurchaseIcon`, `HealthIcon`, `CallIcon`, `MailIcon`,
+`MeetingIcon`, `TripIcon`, `PaymentIcon`, `ReadingIcon`.
+
+The section was created not for one product but because the alternative is worse: without it
+every consumer picks the "call" icon anew, and half a year later it looks different in two
+apps of the same kit. The section grows by request.
+There is no "no topic" value in the vocabulary: the absence of a topic is the absence of a value, not
+an eleventh icon.
+
+Place them **next to text, not instead of it**: the topic of a task cannot be unambiguously inferred from
+the picture, and `aria-hidden` is mandatory here — the label carries the accessible name. All ten were checked as a
+column at 16 pixels (`MeetingIcon` with its new
+glyph — again, in 3.29.0): any icons can be told apart
+one at a time, and it is the column that is checked.
+
+The full list is intentionally not duplicated in the documentation: the authoritative and
+versioned list is [src/icons.ts](../src/icons.ts), grouped by
+navigation, settings, actions, chevrons, states, files and communication, people and
+access, time and place, data view, subject topics, text formatting and theme.
+
+## Baseline set and requests
+
+Since 3.29.0 the vocabulary has a **baseline set**: meanings found in the icon sets of
+almost all major systems (Material Symbols, Carbon, Atlassian, Polaris, Fluent,
+Primer). These are navigation (`BackIcon`, `HomeIcon`, `SidebarIcon`), editing
+(`UndoIcon`, `PasteIcon`, `SortIcon`), files and communication (`AttachmentIcon`,
+`CommentIcon`), people and access (`TeamIcon`, `LockIcon`, `LoginIcon`), time,
+place and data view. The decision and the selection criterion are in ADR-0049
+(`olddevs_ui_docs/adr/0049-icon-baseline-set.md` (ADR-0049)).
+
+Anything the vocabulary lacks is still added **by request**: with a screen and
+a comparison with similar existing icons. Taking "something similar" from `lucide-react` bypassing the
+vocabulary is not allowed — the meaning would stop being shared.
+
+Together with the baseline set, three earlier icons were brought in line with most systems;
+the names did not change: `HiddenIcon` is a crossed-out eye, `TagIcon` is a price tag,
+`MeetingIcon` is a handshake (`Users` now belongs to `TeamIcon`). And `HelpTooltip`
+now renders `HelpIcon` by default instead of `InfoIcon`. `DragIcon` is deprecated: it is the same
+glyph as `DragHandleIcon`, and it will be removed in 4.0.0.
+
+## Text formatting
+
+The section was added at the request of the `RichTextEditor` Toolbar: `HeadingIcon`,
+`BoldIcon`, `ItalicIcon`, `UnderlineIcon`, `StrikethroughIcon`, `InlineCodeIcon`,
+`CodeBlockIcon`, `SuperscriptIcon`, `SubscriptIcon`, `ClearFormattingIcon`,
+`OrderedListIcon`, `TaskListIcon`, `QuoteIcon`, `DividerIcon`; color, marker and
+alignment added `TextColorIcon`, `HighlightIcon`,
+`AlignLeftIcon`, `AlignCenterIcon`, `AlignRightIcon`, `AlignJustifyIcon`. Existing meanings
+are not repeated: a bulleted list is `ListIcon`, undo and redo
+are `UndoIcon` and `RedoIcon`.
+
+Text color (`TextColorIcon`, a letter with a bar) and marker (`HighlightIcon`,
+a highlighter) are different actions: the first colors the letters, the second puts color under
+them. `PaletteIcon` is the choice of a color scheme, not a text color. `AlignJustifyIcon`
+is not used in the Editor Toolbar ("justify" is absent in v1), but the meaning is in the vocabulary
+for the consumer.
+
+Two distinctions are worth keeping in mind. Inline code (`InlineCodeIcon`, `< >`) is
+not `CodeIcon` (`</>`): that one is the subject topic "development", not an action on
+text. A checklist (`TaskListIcon`) is a list with checkmarks; `ListIcon` deliberately
+has no checkboxes, so that a list of records does not read as "done".
+
+The only visible label on the Toolbar buttons is the icon; the button's name
+comes from `aria-label`, and the keyboard shortcut is shown by a tooltip.
+
+The Insert menu added `ParagraphIcon` (¶) — the "Turn into
+paragraph" item. `HeadingIcon` does not fit it: that one is a heading in general, with no
+level. The "+" button of the Insert menu reuses the existing `AddIcon`.
+
+The Block type menu "¶" (under ADR-0049) added
+`Heading1Icon`–`Heading4Icon` (a heading with the level digit) and `TextIcon` (the letter
+"T", the "Text" item). `HeadingIcon` remains the icon of a heading without a level: the items of the
+Insert menu need it that way. `TextIcon` does not repeat `ParagraphIcon`: that one is
+the "paragraph" pilcrow in the Insert menu, and this one is "Text" in the Block type menu. The "¶" button
+on the Toolbar shows the icon of the current type: the icon of its menu item,
+`CodeBlockIcon` in a code Block, or the pilcrow `ParagraphIcon` when there is no text
+Block under the caret (an image is selected).
+
+The table added seven names: `InsertRowAboveIcon`,
+`InsertRowBelowIcon`, `InsertColumnLeftIcon`, `InsertColumnRightIcon` —
+inserting a row and a column, each side with its own glyph (a bar with an arrow on the
+matching side) — `MergeCellsIcon` and `SplitCellIcon` for merging cells, and
+`HeaderRowIcon` (a frame with a highlighted top bar). The rest of the "Table" menu reuses
+existing meanings: inserting a table is `TableIcon`, deleting
+a row, column and table is `DeleteIcon`, sorting is `SortAscendingIcon` and
+`SortDescendingIcon`, column alignment is `AlignLeftIcon`,
+`AlignCenterIcon`, `AlignRightIcon`.
+
+The Block handle added four names: `MoreVerticalIcon` — "⋮", the button of the Block's action menu (not `MoreIcon`: that one is in a row of buttons; not `DragHandleIcon`: this handle is not dragged), `ArrowUpIcon` and `ArrowDownIcon` — named by shape, as ADR-0049 requires for a bare arrow — and `DuplicateIcon` (a copy next to the original; not `CopyIcon` — that one is about the clipboard). "Add", "Format" and "Delete" in its menu reuse the existing `AddIcon`, `ParagraphIcon` and `DeleteIcon`.
+
+Emoji added `EmojiIcon` — a smiley face, the button of the emoji grid in the Toolbar. The name is by the meaning "emoji", not by the glyph: a face elsewhere would mean mood or rating, and that would be a different decision under ADR-0049.
+
+HTML mode added `SourceIcon` — a sheet with `</>` (`FileCode`), the "HTML" button of the Toolbar: the source code of the whole Document. `CodeBlockIcon` already means a code Block inside a Document, and `CodeIcon` the subject topic "development"; a third meaning is not attached to them (ADR-0049).
+
+Layout added `ColumnLayoutIcon` — two columns, the "Layout" item of the Insert menu. `ColumnsIcon` with three columns already means "choosing the columns of a data table", and a second meaning is not attached to it (ADR-0049): the Layout has its own glyph.
+
+Wrapper added the pair `WrapperIcon` and `UnwrapIcon` — lucide's `Group` and `Ungroup`: a frame with dashed corners around two Blocks and the same Blocks without a frame. The icons sit at the "Wrapper" item of the Insert menu and the "Remove Wrapper" item in the Block handle menu. This is not `ColumnLayoutIcon`: columns put Blocks side by side, while a Wrapper groups them without changing their order. `DeleteIcon` does not fit removal: only the container is deleted, not the content.
+
+The first iteration of the table made do with two icons for four directions
+(`AddRowIcon`, `AddColumnIcon`) and an icon for the separate "Table
+actions" button (`TableEditIcon`). With the "Table" menu the button went away, and the direction
+is now conveyed by the icon itself; the three names were replaced before release and did not stay in the vocabulary.
+
+## Two dates on a record, not one
+
+`CalendarIcon` means a date in general — and that is enough while a record has one date.
+When there are two and they are orthogonal ("when it becomes relevant" and "when it is due"),
+one icon would mark identically the very things that need to be told apart. That is why a due date
+now has its own name — `DeadlineIcon`, an hourglass. A calendar silhouette does not
+fit it: at 14 pixels it reads as "date", and in a neighboring column with
+`CalendarIcon` the difference disappears.
+
+Next to it is `RecurringIcon` — "repeats according to a rule". It is a property of the record itself,
+not an action: the circular arrows of `RefreshIcon` in the interface mean
+"refresh what you see", and one icon for both meanings would make the second unavailable to all
+consumers.
+
+Neither describes a state: being overdue is a computed state, and it
+gets a badge with a word, not an icon.
+
+## Accessibility
+
+An icon alone is almost never enough to name an action. If it is decorative
+next to text, pass `aria-hidden`. If it is the only content of a button, the name
+must be on `Button` and not derived from the SVG shape.
+
+## Related sources and tests
+
+- Source: `src/icons.ts`.
+- Export compatibility and the `*Icon` convention are checked by `tests/icons.test.ts`.