@olddevs/ui 0.0.0-stage → 4.0.1

package/docs/getting-started.md

@@ -0,0 +1,381 @@
+# Подключение `@olddevs/ui`
+
+## Установка
+
+```bash
+npm install @olddevs/ui react clsx tailwind-merge lucide-react sonner \
+  react-aria-components @internationalized/date \
+  @radix-ui/react-dialog @radix-ui/react-popover @radix-ui/react-tooltip \
+  @radix-ui/react-context-menu @radix-ui/react-slot
+```
+
+Всё после `@olddevs/ui` — его обязательные peer-зависимости
+(ADR-0004): кит их
+не приносит, потребитель держит их в своём `package.json`. В списке есть
+`@internationalized/date`: календари принимают ISO-строки, поэтому импортировать
+пакет не нужно. Но типы пропсов календарей описаны через объекты
+`@internationalized/date`, так что без него типы не соберутся.
+
+Движка Редактора в списке нет: его ставит только тот, кто импортирует
+`@olddevs/ui/editor`, — команда на [странице Редактора](components/inputs/rich-text-editor.md#установка).
+
+## Импорт компонентов
+
+```tsx
+import { Button, TextControl } from "@olddevs/ui";
+import { AddIcon } from "@olddevs/ui/icons";
+```
+
+Импортируйте только публичные входы пакета — все они перечислены в `exports`
+файла `package.json` и в [словаре](glossary.md) (`.`, `/icons`, `/color`, `/editor`,
+`/editor/schema`, `/editor/highlight`, `/locales/ru`, `/locales/en`, а также
+`styles.css`). Не импортируйте `@olddevs/ui/src/components/...`: такой путь не входит в контракт пакета и может
+измениться без миграции.
+
+## Подключение CSS
+
+В CSS потребителя обязательны все три строки:
+
+```css
+@import "tailwindcss";
+@import "@olddevs/ui/styles.css";
+@source "./node_modules/@olddevs/ui/dist";
+```
+
+`@import "tailwindcss"` принадлежит приложению-потребителю, а не пакету. Не
+импортируйте Tailwind вторично. `@source` обязателен: Tailwind 4 не сканирует
+`node_modules` автоматически, поэтому без него сборка может успешно завершиться
+без классов компонентов в итоговом CSS.
+
+Если Редактор (`@olddevs/ui/editor`) в приложении не используется, добавьте
+четвёртую строку:
+
+```css
+@source not "./node_modules/@olddevs/ui/dist/editor";
+```
+
+`@source` по всему `dist` сканирует и Редактор, поэтому его классы (Панель, меню,
+`.ProseMirror`) попадают в CSS, даже когда вход нигде не импортируется. Замер
+на приложении Next.js 16 без Редактора: 160 кБ CSS без строки, 113 кБ с ней.
+Импортировали Редактор — уберите строку: иначе его классы не попадут в CSS, а
+сборка, как и без `@source`, пройдёт молча.
+
+## Пакет в серверных компонентах
+
+Компоненты кита импортируются **прямо в серверный компонент** Next.js App
+Router — оборачивать их своим файлом с `"use client"` не нужно: директива стоит
+в самом пакете, по файлам.
+
+Но в конфигурации потребителя обязательна ещё одна строка:
+
+```js
+// next.config.mjs
+export default { experimental: { optimizePackageImports: ["@olddevs/ui"] } };
+```
+
+Она обязательна ровно в том же смысле, что и `@source` для Tailwind: без неё
+сборка проходит успешно, а результат негодный. Замер на приложении Next.js 15.5
+(`First Load JS`, пакет установлен из tarball):
+
+| Что импортирует страница         | Без строки | Со строкой |
+| -------------------------------- | ---------- | ---------- |
+| ничего из кита (базовая линия)   | 102 кБ     | 103 кБ     |
+| `AddIcon` из `@olddevs/ui/icons` | 103 кБ     | 103 кБ     |
+| одна `Button` из корня           | **408 кБ** | 114 кБ     |
+| `cn` и `tableStateToParams`      | **408 кБ** | 103 кБ     |
+
+Третья строка читается так: импорт одной кнопки приносил пользователю **весь
+кит целиком**. Четвёртая — что серверный компонент, которому нужны две чистые
+функции и ни одного компонента, отгружал те же 306 кБ клиентского кода.
+
+Причина не в упаковке пакета, а в границе клиентского графа: корневой
+вход реэкспортирует сотню клиентских модулей, и tree shaking через эту
+границу не работает. `optimizePackageImports` переписывает импорт из
+корневого входа в набор точечных, и цена возвращается к разумной. Разбор —
+ADR-0029.
+
+**Subpath Редактора — своей строкой.** Вход `@olddevs/ui/editor` — такой же
+barrel-файл: рядом с серверным `RichTextView` он реэкспортирует клиентский
+`RichTextEditor`. Корневая строка subpath не покрывает, и страница, которой
+нужен один Просмотр Документа, отгружает весь Редактор вместе с движком:
+
+```js
+// next.config.mjs — если импортируете @olddevs/ui/editor
+export default {
+  experimental: { optimizePackageImports: ["@olddevs/ui", "@olddevs/ui/editor"] },
+};
+```
+
+Замер фикстуры потребителя (`RichTextView` с Блоком кода в серверном
+компоненте): **435 кБ** `First Load JS` без второй строки и 137 кБ с ней — в
+клиент едет только Остров кнопки «Копировать». Входы `@olddevs/ui/editor/schema`
+и `@olddevs/ui/editor/highlight` — не barrel-файлы и клиентских модулей не содержат,
+строка им не нужна.
+
+Утилиты (`cn`, `tableStateToParams`, `formatMask` и остальные из
+[api/utilities.md](api/utilities.md)) серверно-безопасны: React они не
+импортируют и в клиентский граф не тянут. Отдельного входа вроде
+`@olddevs/ui/server` у пакета нет и не планируется — со строкой выше он не
+нужен.
+
+## Размер импорта
+
+Пакет поставляется с исходниками, неиспользуемый код отбрасывается (tree shaking):
+в бандл потребителя попадает только то, что он импортировал. Замер на 3.47.3 — вклад **самого пакета**,
+peer-зависимости внешние, метрика gzip:
+
+| Что импортирует потребитель                                                                                 | gzip     |
+| ----------------------------------------------------------------------------------------------------------- | -------- |
+| `cn` и `tableStateToParams`                                                                                 | 0,6 кБ   |
+| одна `Button`                                                                                               | 1,6 кБ   |
+| `DataTable`                                                                                                 | 9,0 кБ   |
+| весь кит целиком (`import *`)                                                                               | 71,1 кБ  |
+| `RichTextEditor` из `@olddevs/ui/editor`, без движка, «старт»                                               | 70,4 кБ  |
+| `RichTextEditor` вместе с движком Tiptap, «старт» (статический граф, `basic`)                               | 295,1 кБ |
+| `RichTextEditor` вместе с движком Tiptap, «полный» (со всеми ленивыми чанками, `full`)                      | 338,9 кБ |
+| `RichTextView` из `@olddevs/ui/editor`, движок Tiptap в замер включён                                       | 12,0 кБ  |
+| `sanitizeRichText` и `richTextSanitizeConfig` из `@olddevs/ui/editor/schema`, движок Tiptap в замер включён | 3,6 кБ   |
+| `highlightCodeBlocks` из `@olddevs/ui/editor/highlight`, вместе с lowlight                                  | 22,6 кБ  |
+| `highlightCodeNodes` из `@olddevs/ui/editor/highlight`, вместе с lowlight                                   | 22,6 кБ  |
+
+Семь последних строк — отдельные входы Редактора со своими бюджетами
+(ADR-0050). У Редактора три строки, и две из
+них — сценарии (ADR-0058, п. 11.7):
+**«старт»** — статический граф, то, что едет сразу и что платит Пресет `basic`; **«полный»** — он же
+плюс все ленивые чанки входа, то, что в итоге грузит `full`. Блок кода и таблица (их нет в `basic`,
+а их Часть для движка тяжелее 10 кБ) грузятся лениво; до их прихода Редактор, в котором они есть,
+показывает Скелет. `npm run size` проверяет, что их модулей в «старте» нет. Код кита меряется на «старте».
+
+В сценариях движок **внесён в замер** намеренно: Tiptap ставит потребитель, но набор его расширений
+выбирает кит. С подсветкой Блока кода в замер входят ещё lowlight и восемь грамматик highlight.js
+(ADR-0051). Числа в таблице сняты тем же
+конвейером, что и остальные (vite в режиме библиотеки, где пробелы при минификации остаются);
+бандлер приложения с полной минификацией давал около 133 кБ (замер до Панели).
+
+У `RichTextView` Tiptap и lowlight внесены в замер ради проверки. В его строку входят только
+типографика и Остров кнопки «Копировать» у Блоков кода (кнопка и подсказка кита, каталог сообщений),
+и замер доказывает, что в графе нет ни движка, ни подсветчика. Так же меряется лёгкий вход
+`@olddevs/ui/editor/schema` (3,6 кБ): Схема, `richTextSchema`, очистка `sanitizeRichText` с хуками для
+DOMPurify, в том числе по правилам своих Инструментов, и `markRange`.
+
+Серверная подсветка `@olddevs/ui/editor/highlight` (22,6 кБ — почти целиком ядро highlight.js и
+грамматики) стоит только тому, кто её импортировал, и обычно только на сервере. Хелпер
+`highlightCodeNodes` для `CodeView` весит столько же: React в замер не входит, он peer кита
+(ADR-0052). Кто вход
+`@olddevs/ui/editor` не импортирует, не платит ни за движок, ни за код Редактора; в основной вход
+попадают только английские подписи Редактора в общем каталоге сообщений, около 1 кБ gzip (ADR-0050, п. 5).
+
+Поповер своего цвета в Редакторе (`ColorPicker` и цветовая подсистема `react-aria-components`, около
+51 кБ gzip) грузится лениво при первом «Свой цвет…»: в «старт» он не входит, а в «полный» входит только
+код кита, react-aria — peer-зависимость. Ленивые чанки скрипт не отбрасывает молча: их вес сверх
+«старта» он печатает у каждой строки. Чанки можно подгрузить заранее: `modulepreload` на них ставит потребитель.
+
+Числа сторожатся в CI и сверяются с этой таблицей: `npm run size` меряет вклад
+пакета и падает, если документация разошлась с замером, а
+`npm run check:consumer` меряет `First Load JS` страницы
+приложения-потребителя. Бюджеты обеих величин лежат в
+`scripts/bundle-size.budgets.mjs`.
+
+Если компонент вырос по делу, бюджет поднимается — **отдельной строкой в
+merge request и с объяснением, что именно выросло**. Бюджет, который двигают
+заодно с правкой компонента, перестаёт что-либо сторожить уже через пару
+релизов.
+
+### Что лежит в пакете
+
+Разбор решения — ADR-0042.
+
+Кроме `dist` и `styles.css` публикуются **исходники** (`src`, без историй) и
+карты к ним. На бандл потребителя это не влияет ни на байт: в браузер уезжает
+только импортированный код из `dist`, а исходники и карты нужны инструментам —
+отладчику и редактору. Цена — вес установки: на 3.47.3 пакет весит около 9,2 МБ
+распакованным (tarball — около 2,4 МБ), из них исходники — около 2,7 МБ
+(`npm pack --dry-run`).
+
+Покупается на них рабочая отладка. Без `src` карты в пакете лежали мёртвым
+грузом: они ссылаются на исходник относительным путём, файла рядом не было, и
+отладчик молча показывал скомпилированный код. Теперь брейкпоинт внутри кита
+открывает настоящий `.tsx` — с комментариями, в которых объяснено, почему
+компонент устроен именно так, — а «перейти к определению» ведёт туда же, а не
+в `.d.ts`.
+
+Публичный вход это не расширяет: `exports` — закрытая карта, и
+`import "@olddevs/ui/src/components/content/Link.tsx"` Node и любой уважающий
+`exports` бандлер отвергают с `ERR_PACKAGE_PATH_NOT_EXPORTED`. Исходники в
+пакете — материал для инструментов, а не второй способ импортировать кит.
+
+С 3.8.0 рядом с ними едет **справочник** — `docs/` целиком и указатель
+`llms.txt` в корне пакета (ADR-0044).
+Тот же обмен, что и с исходниками: в браузер не уезжает ни байта, вес установки
+растёт на 2,5 МБ распакованным (на 3.47.3). Смысл — в читателе: комментарий в коде объясняет, почему
+компонент устроен так, а страница справочника отвечает, что брать и когда, и до
+3.8.0 второго вопроса в пакете не существовало вовсе.
+
+Открывайте справочник прямо из `node_modules/@olddevs/ui/`: начните с `llms.txt` —
+это указатель на все страницы справочника, — дальше по ссылкам. Импортировать справочник, как и
+исходники, нельзя: `import "@olddevs/ui/docs/index.md"` отвергается тем же
+`ERR_PACKAGE_PATH_NOT_EXPORTED`.
+
+## Быстрый пример
+
+```tsx
+import { Button, FormField, TextControl } from "@olddevs/ui";
+import { AddIcon } from "@olddevs/ui/icons";
+
+export function CreateProjectForm() {
+  return (
+    <form>
+      <FormField label="Название проекта" htmlFor="name">
+        <TextControl id="name" name="name" />
+      </FormField>
+      <Button type="submit" icon={<AddIcon aria-hidden />}>
+        Создать
+      </Button>
+    </form>
+  );
+}
+```
+
+Следующий шаг — [выбрать компонент по задаче](component-selection.md), а затем
+открыть его страницу в [каталоге](components/index.md).
+
+## Страница в каркасе
+
+С 2.1.0 каркас приложения не нужно писать заново: боковая навигация, шапка и раскладка
+приходят из кита.
+
+```tsx
+import { AppShell, NavGroup, NavItem, SideNav, TopBar } from "@olddevs/ui";
+import { DashboardIcon } from "@olddevs/ui/icons";
+import Link from "next/link";
+import { usePathname } from "next/navigation";
+
+export function Layout({ children }: { children: React.ReactNode }) {
+  const pathname = usePathname();
+
+  return (
+    <AppShell
+      routeKey={pathname}
+      sidebar={
+        <SideNav>
+          <NavGroup label="Работа">
+            <NavItem
+              label="Дашборд"
+              icon={<DashboardIcon />}
+              active={pathname.startsWith("/dashboard")}
+              asChild
+            >
+              <Link href="/dashboard" />
+            </NavItem>
+          </NavGroup>
+        </SideNav>
+      }
+      header={<TopBar brand={<Logo />} />}
+    >
+      {children}
+    </AppShell>
+  );
+}
+```
+
+Три вещи, которые кит осознанно оставляет вам: **сравнение маршрутов**
+(`active` — проп), **сохранение схлопнутости** сайдбара и **применение темы**.
+Подробности — на страницах [AppShell](components/app-shell/app-shell.md) и
+[SideNav](components/app-shell/side-nav.md).
+
+## Язык интерфейса
+
+Кит говорит по-английски по умолчанию. Русские подписи подключаются одной
+строкой:
+
+```tsx
+import { UiProvider } from "@olddevs/ui";
+import ru from "@olddevs/ui/locales/ru";
+
+<UiProvider locale="ru-RU" messages={ru}>
+  <App />
+</UiProvider>;
+```
+
+Каталог сообщений не грузится сам: иначе он оказался бы в бандле у всех, включая тех, кому
+нужен только английский. Порядок разрешения строки, частичные каталоги и
+стыковка с `I18nProvider` из react-aria — [i18n.md](i18n.md).
+
+## Частые проблемы
+
+### Escape из выпадающего списка закрывает и окно
+
+**Симптом.** `Dialog` открыт, внутри раскрыт `Select`, `TimePicker` или календарь.
+Нажатие Escape должно закрыть только верхний слой — список, — а закрывает ещё и
+окно, вместе с несохранённой формой.
+
+**Причина** — в приложении две и более копии пакета `@radix-ui/react-dismissable-layer`.
+Стек открытых слоёв Radix хранит в переменной модуля: сколько копий модуля, столько
+независимых стеков, и каждый слой считает себя верхним. Внутренние пакеты Radix
+пинит **точными** версиями, без каретки, поэтому `dialog`, `popover` и `tooltip`,
+выпущенные в разное время, тянут разные копии, и npm обязан их продублировать. В вёрстке это
+не видно — только в поведении.
+
+**Проверка.** Копия должна быть одна:
+
+```bash
+npm ls @radix-ui/react-dismissable-layer
+find node_modules -name "react-dismissable-layer" -type d   # ровно одно совпадение
+```
+
+В выводе `npm ls` одна версия, остальные вхождения помечены `deduped`.
+
+**Лечение.** Сначала подберите версии `@radix-ui/react-dialog`, `-popover`,
+`-tooltip` и `-context-menu` так, чтобы все четыре тянули одну копию `react-dismissable-layer`. В `devDependencies`
+кита сейчас `dialog@1.1.23`, `popover@1.1.23`, `tooltip@1.2.16` и
+`context-menu@2.3.7` — все они сходятся на `react-dismissable-layer@1.1.19`.
+Если свести версиями не выходит, закрепите одну копию через `overrides` в
+`package.json` приложения:
+
+```json
+{
+  "overrides": {
+    "@radix-ui/react-dismissable-layer": "1.1.19"
+  }
+}
+```
+
+В pnpm то же самое называется `pnpm.overrides`, в Yarn — `resolutions`. Диапазоны в
+`peerDependencies` кита здесь не помогают: пакет не видит, какие внутренние версии
+выберет менеджер пакетов у вас. Повторяйте проверку после каждого обновления
+Radix. Тот же механизм с модульным состоянием у `react-focus-scope` и
+`react-presence`, и их копии стоит проверять так же.
+
+### «Invalid hook call» после `npm i file:` или `npm link`
+
+**Симптом.** Пакет подключён локальным путём — `npm i file:../olddevs_ui` или
+`npm link`, — а приложение падает с ошибкой «Invalid hook call» без внятной причины.
+
+**Причина.** Так подключённый пакет — симлинк на рабочую копию кита. Он резолвит React
+из **своего** `node_modules`, куда React попал как зависимость разработки. В
+приложении получается два экземпляра React. `peerDependencies` от этого не
+спасают: они работают при установке из реестра, а не по симлинку.
+
+**Проверка.** Оба пути должны вести в один файл:
+
+```bash
+node -p "require.resolve('react')"
+node -p "require.resolve('react', { paths: [require('fs').realpathSync('node_modules/@olddevs/ui')] })"
+```
+
+**Лучше ставить опубликованную версию:** `npm i @olddevs/ui@X.Y.Z`, точная версия
+без каретки. Нужна локальная сборка — соберите tarball (`npm pack` в репозитории кита)
+и установите его: `npm i ../olddevs_ui/olddevs-ui-X.Y.Z.tgz`. Установка из tarball
+кладёт настоящую копию, а не симлинк, и второго React нет.
+
+Если без симлинка не обойтись, сведите React к одной копии в сборщике приложения.
+В Vite:
+
+```ts
+// vite.config.ts
+export default { resolve: { dedupe: ["react", "react-dom"] } };
+```
+
+В остальных сборщиках то же делает алиас `react` и `react-dom` на копии из
+`node_modules` приложения (в Next.js — `resolve.alias` в функции `webpack`
+в `next.config.js`). Перед коммитом верните в `package.json` версию из реестра.