@olddevs/ui 0.0.0-stage → 4.0.0

package/docs/icons.md

@@ -0,0 +1,251 @@
+---
+entrypoint: "@olddevs/ui/icons"
+source: src/icons.ts
+status: stable
+---
+
+# Иконки `@olddevs/ui/icons`
+
+## Кратко для AI
+
+Импортируйте иконки только из `@olddevs/ui/icons`, выбирая имя по смыслу действия
+или сущности: `DeleteIcon`, а не геометрию вроде `Trash`. Геометрию словаря
+даёт `lucide-react`; словарь пакета фиксирует единое системное значение.
+
+## Когда использовать
+
+- Когда у UI уже есть общеупотребимый смысл: закрыть, удалить, искать,
+  настройки, ошибка, успех, переключить тему и т. п.
+- Когда нужно единообразное обозначение одного действия во всех экранах.
+- С `Button` для иконки без текста: обязательно передайте доступное имя самой
+  кнопке (`aria-label`), а иконку сделайте декоративной через `aria-hidden`.
+
+## Когда не использовать
+
+- Не импортируйте напрямую иконки из `lucide-react` под их геометрическими
+  именами (`Trash`) для смысла, который уже есть в словаре. Иначе последующая смена метафоры не будет
+  централизованной.
+- Не выбирайте иконку по похожему контуру: `CheckIcon` означает отмеченный
+  элемент, `SuccessIcon` — успешный результат; `DeleteIcon` — удалить,
+  `CloseIcon` — закрыть.
+- Не полагайтесь на иконку как единственную подпись незнакомого действия.
+  Добавьте видимый текст, подсказку или доступное имя по контексту.
+
+## Минимальный пример
+
+```tsx
+import { Button } from "@olddevs/ui";
+import { DeleteIcon, SearchIcon } from "@olddevs/ui/icons";
+
+<Button aria-label="Удалить кампанию" tone="danger" variant="ghost">
+  <DeleteIcon aria-hidden />
+</Button>
+<SearchIcon aria-hidden size={16} />
+```
+
+## Контракт входа
+
+- Публичный вход — `@olddevs/ui/icons`; не импортируйте `src/icons.ts` или
+  `lucide-react` через внутренние пути пакета.
+- Имена словаря оканчиваются на `Icon`; тест гарантирует, что каждый экспорт
+  разрешается в компонент установленной версии `lucide-react`.
+- Размер, толщина линии и цвет не фиксируются словарём. Их задаёт потребитель
+  через props Lucide или `LucideProvider`.
+- Также экспортируется тип `IconProps` — это `LucideProps` из `lucide-react`.
+
+## Семантические различия
+
+| Нужный смысл                         | Используйте                                     | Не подменяйте                  |
+| ------------------------------------ | ----------------------------------------------- | ------------------------------ |
+| Закрыть панель, окно или тег         | `CloseIcon`                                     | `DeleteIcon`                   |
+| Удалить сущность                     | `DeleteIcon`                                    | `CloseIcon`                    |
+| Отмеченный флажок или выбор          | `CheckIcon`                                     | `SuccessIcon`                  |
+| Успешный итог операции               | `SuccessIcon`                                   | `CheckIcon`                    |
+| Сообщить об ошибке                   | `ErrorIcon`                                     | `WarningIcon`                  |
+| Найти визуально похожее              | `FindSimilarIcon`                               | общий `SearchIcon`             |
+| Внешняя ссылка                       | `ExternalLinkIcon`                              | `LinkIcon`                     |
+| Выйти из аккаунта                    | `LogoutIcon`                                    | `CloseIcon`                    |
+| Перечень записей                     | `ListIcon`                                      | `NavigationIcon`               |
+| Цель, за которую берутся             | `TargetIcon`                                    | `PlayIcon`                     |
+| Приостановить отсчёт                 | `PauseIcon`                                     | `CloseIcon`                    |
+| Приступил к работе (отметка статуса) | `FirstStepIcon`                                 | `PlayIcon`                     |
+| Здоровье как тема дела               | `HealthIcon`                                    | `FavoriteIcon`                 |
+| Письмо как тема дела                 | `MailIcon`                                      | `SendIcon`                     |
+| Поездка как тема дела                | `TripIcon`                                      | `SendIcon`                     |
+| Чтение как тема дела                 | `ReadingIcon`                                   | `LibraryIcon`                  |
+| Встреча как тема дела                | `MeetingIcon`                                   | `ProfileIcon`, `CalendarIcon`  |
+| Разработка как тема дела             | `CodeIcon`                                      | `AutomationIcon`               |
+| Срок, к которому нужно сделать       | `DeadlineIcon`                                  | `CalendarIcon`, `BellIcon`     |
+| Повторяется по правилу               | `RecurringIcon`                                 | `RefreshIcon`                  |
+| Помощь, справка                      | `HelpIcon`                                      | `InfoIcon`                     |
+| Совет                                | `TipIcon`                                       | `InfoIcon`                     |
+| Назад по истории                     | `BackIcon`                                      | `ChevronLeftIcon`              |
+| Главная, корень приложения           | `HomeIcon`                                      | `DashboardIcon`                |
+| Сортировать                          | `SortIcon`                                      | `SelectIcon`                   |
+| Отменить действие                    | `UndoIcon`                                      | `RefreshIcon`                  |
+| Повторить отменённое                 | `RedoIcon`                                      | `RecurringIcon`                |
+| Настроить вид                        | `AdjustIcon`                                    | `SettingsIcon`, `FilterIcon`   |
+| Поделиться                           | `ShareIcon`                                     | `SendIcon`, `UploadIcon`       |
+| Вложение                             | `AttachmentIcon`                                | `LinkIcon`                     |
+| Заперто, только чтение               | `LockIcon`                                      | `SecurityIcon`                 |
+| Команда, участники                   | `TeamIcon`                                      | `ProfileIcon`, `MeetingIcon`   |
+| Время вообще                         | `TimeIcon`                                      | `DeadlineIcon`                 |
+| Пометить проблему                    | `FlagIcon`                                      | `FirstStepIcon`                |
+| Запрещено                            | `BlockedIcon`                                   | `ErrorIcon`                    |
+| Строчный код (Метка в тексте)        | `InlineCodeIcon`                                | `CodeIcon`, `CodeBlockIcon`    |
+| Исходный HTML Документа              | `SourceIcon`                                    | `CodeBlockIcon`, `CodeIcon`    |
+| Маркированный список в тексте        | `ListIcon`                                      | `TaskListIcon`                 |
+| Чек-лист                             | `TaskListIcon`                                  | `ListIcon`, `SuccessIcon`      |
+| Разделитель между Блоками            | `DividerIcon`                                   | `MinusIcon`                    |
+| Снять форматирование                 | `ClearFormattingIcon`                           | `DeleteIcon`                   |
+| Цвет текста                          | `TextColorIcon`                                 | `PaletteIcon`                  |
+| Маркер (цветная заливка)             | `HighlightIcon`                                 | `TextColorIcon`                |
+| Обычный абзац, «просто текст»        | `ParagraphIcon`                                 | `HeadingIcon`                  |
+| Заголовок уровня 1–4                 | `Heading1Icon` … `Heading4Icon`                 | `HeadingIcon`                  |
+| «Текст» в меню типа Блока            | `TextIcon`                                      | `ParagraphIcon`, `HeadingIcon` |
+| Вставить строку выше / ниже          | `InsertRowAboveIcon`, `InsertRowBelowIcon`      | `AddIcon`                      |
+| Вставить столбец слева / справа      | `InsertColumnLeftIcon`, `InsertColumnRightIcon` | `ColumnsIcon`                  |
+| Объединить ячейки таблицы            | `MergeCellsIcon`                                | `TableIcon`                    |
+| Разделить объединённую ячейку        | `SplitCellIcon`                                 | `TableIcon`                    |
+| Первая строка — заголовки            | `HeaderRowIcon`                                 | `TableIcon`                    |
+| Эмодзи (сетка символов)              | `EmojiIcon`                                     | —                              |
+| «Ещё» в столбец: меню Блока          | `MoreVerticalIcon`                              | `MoreIcon`, `DragHandleIcon`   |
+| Дублировать рядом с оригиналом       | `DuplicateIcon`                                 | `CopyIcon`                     |
+| Стрелка вверх / вниз                 | `ArrowUpIcon`, `ArrowDownIcon`                  | `ChevronUpIcon`, `SortIcon`    |
+| Раскладка Документа колонками        | `ColumnLayoutIcon`                              | `ColumnsIcon`                  |
+| Обёртка: группа Блоков               | `WrapperIcon`                                   | `ColumnLayoutIcon`             |
+| Снять Обёртку, Блоки остаются        | `UnwrapIcon`                                    | `DeleteIcon`                   |
+
+## Предметные темы
+
+С 3.21.0 в словаре есть раздел, описывающий не интерфейс, а **то, о чём дело**:
+`CodeIcon`, `GameIcon`, `PurchaseIcon`, `HealthIcon`, `CallIcon`, `MailIcon`,
+`MeetingIcon`, `TripIcon`, `PaymentIcon`, `ReadingIcon`.
+
+Раздел заведён не ради одного продукта, а потому что альтернатива хуже: без него
+каждый потребитель выбирает иконку «позвонить» заново, и через полгода в двух
+приложениях одного кита она нарисована по-разному. Раздел расширяется заявкой.
+Значения «без темы» в словаре нет: отсутствие темы — это отсутствие значения, а не
+одиннадцатая иконка.
+
+Ставьте их **рядом с текстом, а не вместо него**: тема дела не выводится из
+рисунка однозначно, и `aria-hidden` здесь обязателен — доступное имя несёт
+подпись. Все десять проверены столбцом на 16 пикселях (`MeetingIcon` с новым
+рисунком — заново, в 3.29.0): по отдельности
+различимы любые иконки, а проверяется именно столбец.
+
+Полный перечень намеренно не дублируется в документации: авторитетный и
+версионируемый список — [src/icons.ts](../src/icons.ts), сгруппированный по
+навигации, настройкам, действиям, шевронам, состояниям, файлам и общению, людям и
+доступу, времени и месту, виду данных, предметным темам, форматированию текста и теме оформления.
+
+## Базовый набор и заявки
+
+С 3.29.0 в словаре есть **базовый набор**: смыслы, которые есть в наборах иконок
+почти всех крупных систем (Material Symbols, Carbon, Atlassian, Polaris, Fluent,
+Primer). Это навигация (`BackIcon`, `HomeIcon`, `SidebarIcon`), правка
+(`UndoIcon`, `PasteIcon`, `SortIcon`), файлы и общение (`AttachmentIcon`,
+`CommentIcon`), люди и доступ (`TeamIcon`, `LockIcon`, `LoginIcon`), время,
+место и вид данных. Решение и критерий отбора — ADR-0049
+(`olddevs_ui_docs/adr/0049-icon-baseline-set.md` (ADR-0049)).
+
+Всё, чего в словаре нет, по-прежнему добавляется **заявкой**: с экраном и
+сравнением с похожими иконками словаря. Брать «что-то похожее» из `lucide-react` в обход
+словаря нельзя — смысл перестанет быть общим.
+
+Вместе с базовым набором три прежние иконки приведены к виду, принятому в большинстве систем;
+имена не изменились: `HiddenIcon` — перечёркнутый глаз, `TagIcon` — ценник,
+`MeetingIcon` — рукопожатие (`Users` теперь у `TeamIcon`). А `HelpTooltip`
+по умолчанию показывает `HelpIcon` вместо `InfoIcon`. `DragIcon` устарел: это тот
+же рисунок, что `DragHandleIcon`, и в 4.0.0 он будет удалён.
+
+## Форматирование текста
+
+Раздел появился по заявке Панели `RichTextEditor`: `HeadingIcon`,
+`BoldIcon`, `ItalicIcon`, `UnderlineIcon`, `StrikethroughIcon`, `InlineCodeIcon`,
+`CodeBlockIcon`, `SuperscriptIcon`, `SubscriptIcon`, `ClearFormattingIcon`,
+`OrderedListIcon`, `TaskListIcon`, `QuoteIcon`, `DividerIcon`; цвет, маркер и
+выравнивание добавили `TextColorIcon`, `HighlightIcon`,
+`AlignLeftIcon`, `AlignCenterIcon`, `AlignRightIcon`, `AlignJustifyIcon`. Уже занятые
+смыслы не повторяются: маркированный список — `ListIcon`, отменить и повторить
+— `UndoIcon` и `RedoIcon`.
+
+Цвет текста (`TextColorIcon`, буква с полосой) и маркер (`HighlightIcon`,
+выделитель) — разные действия: первый красит буквы, второй подкладывает цвет под
+них. `PaletteIcon` — выбор цветовой схемы, не цвет текста. `AlignJustifyIcon`
+в Панели Редактора не используется («по ширине» в v1 нет), но смысл в словаре
+есть для потребителя.
+
+Два различия стоит держать в голове. Строчный код (`InlineCodeIcon`, `< >`) —
+не `CodeIcon` (`</>`): тот — предметная тема «разработка», а не действие над
+текстом. Чек-лист (`TaskListIcon`) — список с галочками; `ListIcon` флажков
+намеренно не рисует, чтобы перечень записей не читался как «выполнено».
+
+На кнопках Панели видна только иконка; имя кнопке даёт `aria-label`, а сочетание
+клавиш показывает подсказка.
+
+Меню вставки добавило `ParagraphIcon` (¶) — пункт «Превратить в
+абзац». `HeadingIcon` для него не годится: тот — заголовок вообще, без
+уровня. Кнопка «+» Меню вставки берёт уже занятый `AddIcon`.
+
+Меню типа Блока «¶» (по ADR-0049) добавило
+`Heading1Icon`–`Heading4Icon` (заголовок с цифрой уровня) и `TextIcon` (буква
+«T», пункт «Текст»). `HeadingIcon` остаётся иконкой заголовка без уровня: так он нужен пунктам
+Меню вставки. `TextIcon` не повторяет `ParagraphIcon`: тот —
+пилкроу «абзац» в Меню вставки, а этот — «Текст» в меню типа Блока. Кнопка «¶»
+на Панели показывает иконку текущего типа: иконку его пункта меню,
+`CodeBlockIcon` в Блоке кода или пилкроу `ParagraphIcon`, когда под кареткой нет
+текстового Блока (выделена картинка).
+
+Таблица добавила семь имён: `InsertRowAboveIcon`,
+`InsertRowBelowIcon`, `InsertColumnLeftIcon`, `InsertColumnRightIcon` —
+вставка строки и столбца, у каждой стороны свой рисунок (полоса со стрелкой с
+нужной стороны), — `MergeCellsIcon` и `SplitCellIcon` для слияния ячеек и
+`HeaderRowIcon` (рамка с выделенной верхней полосой). Остальное меню
+«Таблица» берёт уже занятые смыслы: вставка таблицы — `TableIcon`, удаление
+строки, столбца и таблицы — `DeleteIcon`, сортировка — `SortAscendingIcon` и
+`SortDescendingIcon`, выравнивание столбца — `AlignLeftIcon`,
+`AlignCenterIcon`, `AlignRightIcon`.
+
+Ручка Блока добавила четыре имени: `MoreVerticalIcon` — «⋮», кнопка меню действий у Блока (не `MoreIcon`: тот в ряду кнопок; не `DragHandleIcon`: за эту ручку не тянут), `ArrowUpIcon` и `ArrowDownIcon` — названы по форме, как велит ADR-0049 для голой стрелки, — и `DuplicateIcon` (копия рядом с оригиналом; не `CopyIcon` — тот про буфер обмена). «Добавить», «Формат» и «Удалить» её меню берут уже занятые `AddIcon`, `ParagraphIcon` и `DeleteIcon`.
+
+Эмодзи добавило `EmojiIcon` — лицо-смайл, кнопка сетки эмодзи в Панели. Имя по смыслу «эмодзи», а не по рисунку: лицо в другом месте означало бы настроение или оценку, и это было бы другое решение по ADR-0049.
+
+HTML-режим добавил `SourceIcon` — лист с `</>` (`FileCode`), кнопка «HTML» Панели: исходный код всего Документа. `CodeBlockIcon` уже значит Блок кода внутри Документа, а `CodeIcon` — предметную тему «разработка»; третий смысл на них не вешается (ADR-0049).
+
+Раскладка добавила `ColumnLayoutIcon` — две колонки, пункт «Раскладка» Меню вставки. `ColumnsIcon` с тремя колонками уже значит «выбор колонок таблицы данных», и второй смысл на него не вешается (ADR-0049): у Раскладки свой рисунок.
+
+Обёртка добавила пару `WrapperIcon` и `UnwrapIcon` — `Group` и `Ungroup` у lucide: рамка пунктирными углами вокруг двух Блоков и те же Блоки без рамки. Иконки стоят у пункта «Обёртка» Меню вставки и пункта «Снять обёртку» в меню Ручки Блока. Это не `ColumnLayoutIcon`: колонки ставят Блоки рядом, а Обёртка группирует их, не меняя порядка. Для снятия не подходит `DeleteIcon`: удаляется только контейнер, а не содержимое.
+
+Первый срез таблицы обходился двумя рисунками на четыре направления
+(`AddRowIcon`, `AddColumnIcon`) и иконкой отдельной кнопки «Действия с
+таблицей» (`TableEditIcon`). С меню «Таблица» кнопка ушла, а направление
+теперь передаёт сама иконка; три имени до выпуска заменены и в словаре не остались.
+
+## Две даты у записи, а не одна
+
+`CalendarIcon` означает дату вообще — и этого хватает, пока дата у записи одна.
+Когда их две и они ортогональны («когда станет актуально» и «когда горит»),
+один рисунок помечает одинаково ровно то, что различают. Поэтому у срока
+теперь своё имя — `DeadlineIcon`, песочные часы. Календарный силуэт для него не
+годится: на 14 пикселях он читается как «дата», и в соседней колонке с
+`CalendarIcon` разница исчезает.
+
+Рядом с ним `RecurringIcon` — «повторяется по правилу». Это свойство самой
+записи, а не действие: круговые стрелки `RefreshIcon` в интерфейсе означают
+«обнови то, что видишь», и один рисунок на оба смысла закрыл бы второй для всех
+потребителей.
+
+Ни тот, ни другой не описывают состояние: просрочка — вычисленное состояние, у
+неё бейдж со словом (`StatusBadge`), а не иконка.
+
+## Доступность
+
+Одна иконка почти никогда не даёт достаточного имени действию. Если она
+декоративна рядом с текстом, передайте `aria-hidden`. Если она — единственное
+содержимое кнопки, имя должно быть на `Button`, а не выведено из формы SVG.
+
+## Связанные исходники и проверка
+
+- Источник: `src/icons.ts`.
+- Совместимость экспорта и соглашение `*Icon` проверяет `tests/icons.test.ts`.

package/docs/index.md

@@ -0,0 +1,62 @@
+# Справочник `@olddevs/ui`
+
+Этот справочник — контракт для разработчиков и AI-агентов, которые используют
+публичный API пакета. Исходник правды для экспортов —
+[`src/index.ts`](../src/index.ts); исходники компонентов, тесты и Storybook
+подтверждают поведенческие утверждения на страницах.
+
+## Начать здесь
+
+1. [Подключение пакета](getting-started.md) — импорт, CSS и Tailwind 4.
+2. [Выбор компонента](component-selection.md) — сначала выберите семантику, а
+   не похожий внешний вид.
+3. [Общие соглашения](conventions.md) — словарь пропсов, controlled state и
+   границы публичного API.
+4. [Словарь](glossary.md) — термины кита и Редактора и с чем их не путать.
+5. [Доступность](accessibility.md) — обязательные требования к имени, фокусу и
+   клавиатуре.
+6. [Темы, токены и бренды](theming.md) — четыре слоя токенов и как завести
+   собственный бренд одним блоком CSS.
+7. [Палитра](palette.md) — значения примитивов палитры и ролей по темам одной
+   таблицей.
+8. [Локализация](i18n.md) — провайдер, каталог сообщений и стыковка с
+   `I18nProvider` потребителя.
+9. [Каталог компонентов](components/index.md) — полный указатель по публичным
+   компонентам.
+
+## Правила для AI
+
+- **Начните с `llms.txt`** в корне пакета: это указатель на все страницы
+  справочника с описанием каждой. Он собирается из `docs/` скриптом, то есть
+  отстать от них не может.
+- Импортируйте только публичные входы пакета (список — в [словаре](glossary.md)); не
+  импортируйте файлы из `src/` пакета напрямую.
+- До чтения API страницы прочитайте «Когда использовать» и «Когда не
+  использовать»: компоненты с похожим видом могут выражать разные действия.
+- Не заменяйте семантический компонент ручной разметкой, если пакет уже
+  предоставляет подходящий публичный экспорт.
+- Соблюдайте описанный в справочнике контракт controlled/uncontrolled и требования
+  к подписи (`label`), фокусу и Escape. Внешний вид на скриншоте этих контрактов
+  не заменяет.
+- Документируйте изменение публичного API в том же изменении, что и код; полные
+  правила сопровождения лежат в `CLAUDE.md` репозитория кита — в пакет он не
+  едет, и ссылки на него здесь нет намеренно.
+
+## Область действия
+
+Документы находятся в репозитории пакета и **с 3.8.0 едут вместе с ним в
+реестр**: `docs/` целиком плюс указатель `llms.txt` в корне пакета
+(ADR-0044).
+Агенту в чужом репозитории больше не нужны ни ссылка на этот репозиторий, ни
+доступ к нему: справочник лежит в `node_modules/@olddevs/ui/docs/` и той самой
+версии, которая установлена, — а не той, что сейчас в `main`.
+
+У кита есть публичный сайт документации, но указатель на него не ссылается:
+ссылок вида `https://…` в нём нет, все пути относительные и ведут внутрь пакета.
+
+**Чего в пакете нет — это ADR.** Страницы справочника ссылаются на решения
+номером, `ADR-NNNN`, множество раз, но сами решения ведутся отдельно от кода
+и в пакет не входят. Справочник от этого читается
+полностью — контракт, API и доступность описаны на самих страницах, — но
+«почему решено так» остаётся в репозитории решений. Цена принята осознанно
+(ADR-0044); если довод нужен, спросите в issues репозитория.