@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/conventions.md

@@ -0,0 +1,358 @@
+# Общие соглашения `@olddevs/ui`
+
+## Публичный контракт
+
+Публичный API — экспорты времени выполнения из [`src/index.ts`](../src/index.ts), типы,
+описанные в документации входы и `styles.css`. Исходники в `src/components/` —
+доказательство поведения, но не разрешённый путь импорта для потребителя.
+
+## Семантический словарь пропсов
+
+Если конкретная страница не говорит иначе, примитивы используют три независимые
+оси:
+
+| Prop      | Значения                                            | Вопрос, на который отвечает     |
+| --------- | --------------------------------------------------- | ------------------------------- |
+| `size`    | `sm`, `md`, `lg`                                    | Насколько крупен элемент?       |
+| `tone`    | `neutral`, `accent`, `success`, `warning`, `danger` | Что означает состояние?         |
+| `variant` | `solid`, `soft`, `outline`, `ghost`                 | Насколько заметно это значение? |
+
+Состояния называются положительно: `selected`, `disabled`, `loading`. Нативное
+ARIA-состояние может использовать своё корректное имя, например `checked` у
+switch. Не создавайте альтернативы вроде `kind`, `status` или отрицательные
+булевы пропсы без отдельного публичного решения; `active` занят одним смыслом —
+ниже.
+
+Пропсы вне трёх осей повторяются в нескольких компонентах. Одно
+понятие — одно имя: второй компонент с тем же смыслом берёт имя отсюда, а не
+придумывает своё.
+
+| Prop         | Смысл                                                                           | Где                                   |
+| ------------ | ------------------------------------------------------------------------------- | ------------------------------------- |
+| `appearance` | Форма варианта — меняется разметка, а не заметность тона                        | `RadioGroup`, `CheckboxGroup`         |
+| `active`     | Текущий пункт навигации: `aria-current="page"`                                  | `NavItem`, `MobileTabBarItem`         |
+| `activeKey`  | То же для коллекции данных: ключ текущего узла, `aria-current="page"`           | `TreeView`                            |
+| `level`      | Уровень заголовка, `2`–`4`: компонент рисует настоящий `<h2>`–`<h4>`            | `SectionHeader`, `NotificationCenter` |
+| `kind`       | Вид **данных**, а не элемента: что за значение поле описывает и как его вводить | `FilterField` (ADR-0063)              |
+
+- **`kind` у `FilterField` — публичное решение ADR-0063, а не обход оси.**
+  `FilterField` — описание поля данных, а не элемент интерфейса: `"values"`,
+  `"number-range"`, `"date-range"` говорят, что за значение у поля и каким
+  вводом его задать. Это не подача (`variant`) и не форма варианта
+  (`appearance`) — у описания данных нет ни тона, ни разметки. Компонентам,
+  которые рисуют элемент, `kind` по-прежнему не заводится.
+- **`appearance`, а не `variant`.** `variant` — ось подачи тона с закрытым
+  набором `solid|soft|outline|ghost` на весь кит. `appearance="card"` меняет
+  саму форму варианта: рамка, индикатор, описание внутри подписи. Под `variant`
+  такое значение дало бы оси второй смысл, и `variant="card"` у одного
+  компонента соседствовал бы с `variant="soft"` у другого.
+- **`active`, а не `selected`.** `selected` — выбор в наборе (`aria-selected`,
+  `aria-checked`): его меняет пользователь. Текущий раздел — это `aria-current`:
+  его задаёт маршрут, а пункт остаётся ссылкой. Других значений у `active` нет —
+  синонимом `selected` он не становится. Там, где пунктов-элементов нет, а есть
+  данные по ключам (`TreeView`), то же понятие называется `activeKey` — по
+  образцу `selectedKeys` и `expandedKeys`, одно значение вместо набора.
+- **`level`, а не `headingLevel`.** Уровень зависит от того, куда компонент
+  встал, и знает его потребитель. У `SectionHeader` проп назывался `level`
+  раньше, второе имя для того же понятия разошлось бы с ним молча.
+
+## Доступное имя
+
+Правило выведено на `Toolbar`, `Carousel`, `MobileTabBar` и `TagGroup`: до него обязательное имя было устроено в этих компонентах по-разному, а `label` в одном выводился на экран, а в соседнем уходил в атрибут.
+
+- **`label` — только видимая подпись.** Проп с этим именем рисует текст на
+  экране. Имя, которое не рисуется, называется своим ARIA-атрибутом.
+- **Без видимой подписи — ровно одно из `aria-label` и `aria-labelledby`.** Тип
+  — [`AccessibleName`](../src/lib/accessible-name.ts), объединение с `never`:
+  без имени и с обоими сразу TypeScript вызов не пропускает. Два источника
+  одного имени при правке расходятся молча.
+- **Имя с умолчанием из каталога** — `Partial<AccessibleName>`: можно не
+  передавать ничего, но не оба сразу (`MobileTabBar`). Умолчание звучит и тогда,
+  когда передана пустая строка.
+- **Видимая подпись или атрибут** — `{ label; "aria-label"?: never;
+"aria-labelledby"?: never } | ({ label?: never } & AccessibleName)` (`TagGroup`).
+  Подпись вместе с атрибутом запрещена: атрибут перекрыл бы видимый текст, и на
+  слух компонент назывался бы иначе, чем на экране.
+- Тест закрепляет форму через `@ts-expect-error` — на «нет имени» и на «оба
+  сразу».
+
+Компоненты, выпущенные до правила, используют `label` как строку имени без
+видимой подписи (`SideNav`, `TopBar`, `FilterBar`, `ScrollArea` и другие).
+Переименование там — breaking change и отдельное решение; новый компонент
+следует правилу.
+
+## Пустое значение
+
+Пустая строка — не подпись и не имя. Правило и его история — в
+[`src/lib/empty.ts`](../src/lib/empty.ts): для пропа типа `string` фолбэк
+пишется через `||`, а не `??`; для `ReactNode` — через `hasContent`, а не
+`!= null`. `??` и `!= null` пропускают `""` — и компонент рисует пустой узел,
+остаётся без имени или называет кнопку «Удалить: ». Каждая такая ветка
+закрепляется тестом с пустой строкой.
+
+## Что проверяют тесты
+
+Тест рендерит компонент как потребитель (Testing Library и user-event) и
+проверяет наблюдаемое: роли, имена, aria-атрибуты, фокус, вызовы обработчиков,
+текст. Внутреннее состояние и хуки не проверяются.
+
+**Класс проверяется, только когда он и есть наблюдаемый контракт, которого jsdom
+иначе не увидит**: jsdom не считает каскад, раскладку и `env()`. Таковы тон из
+словаря (`TONE_TOKENS`, `CHOICE_CARD_SELECTED_BORDER`), ширина слайда и число
+колонок из словаря компонента, фон полосы в слоте и вне его
+(`BACKDROP_CLASS` у `MobileTabBar`). Ожидание берут **из словаря, а не
+пишут литералом**: литерал проверяет, что строку никто не трогал, а словарь — что
+компонент взял нужную клетку.
+
+Произвольные классы вёрстки (`h-7`, `rounded-full`, `ring-bg-1`) тестом не
+закрепляются: их стерегут визуальные снимки, а попадание каждого класса в CSS —
+[`tests/class-coverage.test.ts`](../tests/class-coverage.test.ts) через матрицу.
+Если у такого класса есть наблюдаемое следствие (описание внутри подписи, узел в
+DOM, атрибут), проверяется следствие.
+
+## Управление состоянием
+
+Преимущественно компоненты принимают значение и callback от потребителя.
+Потребитель — единственный владелец доменного состояния, запроса, маршрута и
+валидации. На странице компонента всегда уточняйте:
+
+- форму значения и пустого значения (`null`, массив, строка и т. п.);
+- controlled props и callback;
+- допустимые переходы состояния;
+- поведение disabled/loading;
+- интеграцию с нативной формой, если она есть.
+
+Не выводите API из внешнего вида истории: сверяйте тип и исходник.
+
+## Как читать страницу компонента
+
+Каждая страница обязана содержать:
+
+1. Краткий ответ для AI и границу применения.
+2. Ближайшие альтернативы и запреты на неправильное применение.
+3. Минимальный рабочий пример с корректным импортом.
+4. Интерпретацию публичных пропсов, состояний и событий.
+5. Доступность, клавиатуру, фокус и границу формы.
+6. Антипаттерны, особые случаи и ссылки на source/Storybook.
+
+## Раскладка исходников
+
+Папка компонента в `src/components/<категория>/` совпадает с папкой его страницы
+в `docs/components/<категория>/`: категорий восемь (`actions`, `inputs`,
+`date-time`, `overlays`, `navigation`, `content`, `table`, `app-shell`), в корне
+`src/components/` файлов нет. Внутри категории файлы плоские, внутренняя часть
+лежит рядом с владельцем. Компонент меняет категорию вместе со страницей.
+
+В `src/editor/` в корне остаются только точки входа, `RichTextEditor`,
+`RichTextView` и их истории. Остальное: `core/` — движок и реестр Инструментов,
+`ui/` — общая обвязка, `styles/` — оформление, `hooks/` — хуки, `features/<фича>/`
+— узел, команды, Инструмент и UI одной фичи.
+
+Файлы `index.ts` в категориях, слоях и фичах запрещены: импорт идёт напрямую по
+файлу, barrel-файлы допустимы только как точки входа пакета. Раскладку проверяет
+`tests/structure.test.ts`.
+
+## Изменение API
+
+При добавлении или изменении экспорта времени выполнения обновите его страницу, запись в
+каталоге и реестр в том же наборе изменений. Breaking change также требует записи в
+`docs/api/migration-notes.md` с действием для потребителя; не скрывайте
+изменение за визуально похожим поведением.
+
+## Строки, видимые пользователю
+
+Каждая подпись, которую видит или слышит пользователь, идёт через каталог
+сообщений: `проп ?? messages.семья.ключ`. Проп остаётся — он точечное
+переопределение, а не единственный способ.
+
+Литерал в JSX или в дефолте пропа роняет `npm test`
+([`tests/i18n-gate.test.ts`](../tests/i18n-gate.test.ts)). Исключения —
+перечисление с обоснованием в самом гейте (три причины описаны ниже), а не
+regexp.
+
+Как завести ключ — [i18n.md](i18n.md).
+
+## Язык: что по-русски, что по-английски
+
+Граница проходит по адресату, а не по типу файла — решение
+ADR-0034.
+
+| По-русски — кит объясняет себе | По-английски — кит показывает наружу                        |
+| ------------------------------ | ----------------------------------------------------------- |
+| Комментарии в исходниках       | Витрина: разделы, имена историй, демо-контент, `aria-label` |
+| Эта документация и ADR         | Тесты: имена, фикстуры, данные                              |
+| Текст в макетах Figma          | Вывод скриптов в консоль                                    |
+
+Комментарии остаются русскими намеренно, и гейт i18n их не смотрит. Русский
+комментарий над английской историей — норма, а не недоделка.
+
+Русский законен в тестах там, где он **предмет** проверки: формы склонения и
+слова каталога живут в `tests/locale-ru.test.tsx`. В остальных тестах ожидания
+берутся из английского фолбэка.
+
+Белый список гейта — **три причины, а не три файла**: раскладка как данные ввода
+(`Keyboard.tsx` и его тест), русский каталог (`locales/ru.ts`) и русское слово
+как предмет проверки (`locale-ru.test.tsx`, плюс сценарий `SortableList` в
+`tests-visual/interactions.spec.ts`, где объявления локализует сама react-aria).
+Четвёртая причина — повод для разбора, а не для правки числа.
+
+## Имена историй витрины
+
+Разделы и имена историй — латиницей. Из них складывается `id` истории, а из
+`id` — имя файла снимка и адрес в `tests-visual`; переименование стоит
+перегенерации бейзлайна, поэтому имя выбирается один раз.
+
+Раздел компонента — его категория, то есть папка его страницы в справочнике
+и его исходника (ADR-0060): история `src/components/overlays/Dialog.stories.tsx`
+называется `Overlays/Dialog`. Истории Редактора берут раздел по папке своей
+страницы: `Inputs/RichTextEditor`, `Content/RichTextView`.
+
+| Раздел           | Что внутри                                                   |
+| ---------------- | ------------------------------------------------------------ |
+| `Actions/`       | Действия и обратная связь: `Actions/Button`, `Actions/Alert` |
+| `Inputs/`        | Поля и выбор: `Inputs/Select`, `Inputs/RichTextEditor`       |
+| `Date and time/` | Календари и выбор даты и времени                             |
+| `Overlays/`      | Окна, ящики, поповеры, меню, подсказки                       |
+| `Navigation/`    | Вкладки, хлебные крошки, шапки страниц и разделов            |
+| `Content/`       | Типографика, карточки, данные, состояния, раскладка          |
+| `Table/`         | Таблица данных и её панели                                   |
+| `App shell/`     | Оболочка приложения: `AppShell`, `SideNav`, `TopBar`         |
+| `Foundations/`   | Основы: иконки, движение                                     |
+| `Screens/`       | Собранные экраны                                             |
+
+**Словарь повторяющихся имён.** Имя, встретившееся во второй раз, обязано
+попасть сюда: иначе один и тот же случай в двух файлах назовётся по-разному, и
+разойдутся они молча.
+
+| Имя               | Когда                                            |
+| ----------------- | ------------------------------------------------ |
+| `Playground`      | Основная история с контролами                    |
+| `Matrix`          | Все варианты рядом; снимается визуальным тестом  |
+| `Empty`           | Пустое состояние                                 |
+| `Disabled`        | Выключенное состояние                            |
+| `WithError`       | Ошибка валидации                                 |
+| `WithAction`      | С кнопкой действия                               |
+| `WithSelection`   | С выбором                                        |
+| `Sizes`           | Размерная линейка                                |
+| `Horizontal`      | Горизонтальная раскладка                         |
+| `Compact`         | Плотная раскладка                                |
+| `SizesAndStates`  | Размеры и состояния рядом                        |
+| `Collapsed`       | Схлопнутое состояние навигации                   |
+| `Submitting`      | Идёт отправка формы                              |
+| `InForm`          | Компонент внутри формы                           |
+| `AsPage`          | Вариант во весь экран                            |
+| `WithoutTitle`    | Без заголовка                                    |
+| `States`          | Набор состояний рядом                            |
+| `Filled`          | Поле заполнено целиком                           |
+| `Open`            | Раскрытый список или календарь                   |
+| `Tones`           | Тоновая линейка                                  |
+| `WithLabel`       | С видимой подписью                               |
+| `Cards`           | Варианты выбора карточками (`appearance="card"`) |
+| `CardsHorizontal` | Карточки выбора в строку                         |
+| `CardsStates`     | Состояния карточек выбора рядом                  |
+| `CardsTones`      | Тоновая линейка карточек выбора                  |
+| `Controlled`      | Управляемый режим: значение хранит история       |
+| `Wrapping`        | Перенос на узкой ширине                          |
+| `Vertical`        | Вертикальная раскладка                           |
+| `Badges`          | Все виды значка рядом                            |
+
+Одиночные имена описывают **случай**, а не переводят слово: история про то, чем
+компонент отличается от соседей, называется `VersusNeighbours`, а не
+транслитерацией русского заголовка.
+
+**Ширина снимка — тегом истории.** Визуальный тест снимает историю на
+1280×900. История, которая показывает узкий экран, ставит себе тег
+`tags: ["viewport-phone"]` — и снимается на 375×812 с эмулированным вырезом
+экрана снизу (34px). Тег, а не параметр: спек читает истории из
+`storybook-static/index.json`, где параметров нет. Первая такая история —
+`AppShell` → `WithBottomBar`: на 1280px слот полосу прячет.
+
+**Ленивый чанк после показа — тоже тегом.** Снимок ждёт двух одинаковых кадров
+подряд, а пока чанк в пути, экран неподвижен — и снимок принимает недогруженную
+историю за готовую. История, часть которой приходит ленивым чанком уже после
+показа, ставит тег `tags: ["network-idle"]`: снимок и аудит axe ждут тишины в
+сети. Первые такие истории — `RichTextEditor` → `TextCardOpen` и
+`TextCardRussian`: чанк Карточки у текста запрашивается только после
+Готовности движка.
+
+**Имя истории не должно совпадать с именем импортированного компонента.**
+История про `Separator` в `Separator.stories.tsx` не называется `Separator`:
+экспорт затенит импорт, и `tsc` упадёт на `cannot be used as a JSX component` —
+причём только там, где компонент используется как JSX. Отсюда `Separators`,
+`Scrolling`, `HiddenContent`, `BasicTable`.
+
+## Предупреждения в режиме разработки
+
+Первое такое предупреждение — `NotificationItem` с одновременными `onAction` и
+`actions`. Правила выведены на нём и записаны здесь, чтобы следующий автор не
+изобретал свои.
+
+**Когда предупреждать.** Только когда нарушен контракт, который **типы ловят, а
+потребитель на JS — нет**, и компонент при этом молча выбирает одну из
+трактовок (взаимоисключающие пропы, где один проигрывает). Не предупреждаем
+о стиле, о неоптимальном использовании, об устаревании (для него —
+`migration-notes.md`) и о том, что ловит сам React или `react-aria`. Нарушение,
+после которого компонент не может работать, — не предупреждение, а исключение
+(как `HoverCardContent` вне `HoverCard`).
+
+**Как.**
+
+- Через [`devWarn(message)`](../src/lib/dev-warn.ts), а не голым `console.warn`:
+  хелпер показывает сообщение **один раз** (ключ — текст) и **не пишет в
+  продакшне**. Вызов стоит в теле рендера, поэтому «один раз» обязателен —
+  строка списка рендерится сотни раз, `StrictMode` вызывает рендер дважды.
+- Текст — **по-английски**, это вывод в консоль потребителя
+  (ADR-0034); в каталог
+  сообщений он не идёт, это не строка интерфейса. Называет компонент, переданное значение,
+  победившее значение и способ исправления. Без меняющихся данных: ключ дедупликации
+  — сам текст.
+- Режим читается как `process.env.NODE_ENV !== "production"` внутри `try/catch`
+  при каждом вызове. Пакет выходит голым `tsc`, значение в `dist` не вшито — его
+  подставляет сборка потребителя (Vite, Next, webpack) и вырезает мёртвую ветку
+  в продакшне. Без бандлера `process` не определён, ссылка на него бросает
+  `ReferenceError`, и хелпер молчит. Проверка `typeof process !== "undefined"`
+  не годится: бандлер её не заменяет, и в браузерной сборке Vite предупреждение
+  не сработало бы никогда.
+- Тест: `vi.spyOn(console, "warn")`, `resetDevWarnings()` в `beforeEach` (состояние
+  «уже показано» живёт на уровне модуля) и четыре случая — предупреждает в
+  разработке, один раз, молчит в продакшне (`vi.stubEnv`) и молчит при корректном
+  вызове.
+
+**Ошибка вместо предупреждения — `devError(message, cause?)`.** Когда нарушение
+ломает компонент целиком, но не страницу: набор Инструментов `RichTextEditor`
+собран с ошибкой, Загрузчик Части для движка упал, `rangeAt` Карточки бросил
+исключение. Поле само показывает автору строку каталога (`editor.toolsFailed`),
+а причина уходит разработчику через `console.error` — с теми же правилами, что у
+`devWarn`: в разработке, один раз на текст, по-английски.
+
+- Текст начинается с имени компонента (`RichTextEditor: …`): консоль общая для
+  всей страницы. Имя Инструмента или записи в тексте допустимо — оно из
+  описания и от вызова к вызову не меняется.
+- Пойманное исключение — вторым аргументом (`cause`), а не в тексте: его
+  сообщение сделало бы каждую ошибку новой для ключа «один раз», а консоль у
+  объекта `Error` покажет и стек.
+- Тест — тот же регламент на `vi.spyOn(console, "error")`: ошибка в разработке
+  с исключением отдельным аргументом, один раз, тишина в продакшне
+  (`vi.stubEnv`) и при корректном вызове
+  (`tests/rich-text-editor-dev-errors.test.tsx`).
+
+## `readOnly` и `disabled` — разные оси, а не оттенки одной
+
+Правило выведено на `Rating` (волна 25) и записано здесь, потому что в докстроке
+одного компонента следующий автор его не найдёт — и второй `readOnly` в ките
+будет значить что-то своё.
+
+- **`readOnly` — показанные данные.** Значение видно, изменить его нельзя.
+  Приглушать такое нельзя: это значит прятать то, что показано специально.
+  Контрол уходит из табуляции, но остаётся ярким.
+- **`disabled` — недоступное сейчас действие.** Его приглушают, потому что
+  приглушённость и есть сигнал недоступности.
+
+**Роль при этом не меняется.** Выключенный контрол остаётся тем, чем был, и
+помечается `aria-disabled`; подмена роли (например, на `img`) прочиталась бы как
+картинка, а не как недоступное действие. Роль — свойство контрола, а не его
+доступности прямо сейчас.
+
+## Словарь Редактора
+
+Термины Редактора переехали в общий [словарь кита](glossary.md#редактор).