@rt-tools/ui-kit-v2 0.5.0 → 0.7.0

package/README.md

@@ -34,10 +34,24 @@ export const appConfig: ApplicationConfig = {
 @use '@rt-tools/ui-kit-v2/styles/tokens.css';
 ```
 
+Стили кита объявлены слоем каскада `rt-kit` — тремя подслоями в порядке `vendor`, `base`,
+`components`. Правило приложения, объявленное вне слоя, выигрывает у любого правила кита
+независимо от специфичности: перебирать её счётом и обходить чужую вёрстку больше не нужно.
+
+Объявления свойств на корне страницы в слой не уходят — их приложение перебивает порядком,
+объявляя своё после `tokens.css`.
+
+Подслой `vendor` — для чужого CSS, который чинит кит. Тема редактора текста подключается в
+него, иначе она выигрывает у правил кита и панель редактора перестраивается:
+
+```scss
+@import 'quill/dist/quill.snow.css' layer(rt-kit.vendor);
+```
+
 Иконки лежат отдельными файлами в `node_modules/@rt-tools/ui-kit-v2/src/assets/icons`: сборка
 копирует каталог в свою статику, а `provideRtIcons('/icons')` называет адрес, по которому он
-опубликован. Реестр забирает их одним проходом на подъёме и склеивает в inline-sprite, поэтому
-дальше `<rt-icon>` рисуется без запросов.
+опубликован. Файл забирается тогда, когда значок с этим именем попросила разметка, и дальше
+живёт в inline-sprite: страница платит за те значки, которые нарисовала, а не за весь набор.
 
 ```json
 {
@@ -49,16 +63,25 @@ export const appConfig: ApplicationConfig = {
 
 ## Что внутри
 
-**Компоненты** — 72 семейства: поля формы (`rt-input`, `rt-select`, `rt-multiselect`,
+**Компоненты** — 73 семейства: поля формы (`rt-input`, `rt-select`, `rt-multiselect`,
 `rt-date-picker`, `rt-file-input`, `rt-rich-editor`, `rt-field`), таблица с настройкой колонок и
 пагинацией, панель правки записи с маршрутом и защитой несохранённого, диалоги, чат с композером,
-календарь, шапка страницы с навигацией, тосты, просмотрщик фотографий и остальное.
+календарь, шапка страницы с навигацией, тосты, просмотрщик фотографий, показ размеченного текста
+(`rt-markdown-text`) и остальное.
 
 **Дизайн-система** — `src/styles`:
 
+- `tokens.source.mjs` — вход источника: ступени шкал, назначения и ответ тёмной темы рядом со
+  своим назначением. Сами узлы лежат частями рядом — `tokens.scale-*.mjs` для шкал,
+  `tokens.light-*.mjs` для назначений, `tokens.dark-layout.mjs` и `tokens.coarse-pointer.mjs`
+  для порядка тёмного файла и грубого указателя, — а вход складывает их в два ряда. Три файла
+  ниже и имена в `src/lib/tokens/rt-design-tokens.ts` собираются отсюда командой
+  `pnpm run build:tokens-source` и руками не правятся;
 - `_primitives.scss` — шкалы: нейтральные и цветные ряды, отступы, радиусы, тени, типографика;
 - `_semantic.scss` — назначения поверх шкал (`--rt-color-bg-surface`, `--rt-color-text-muted`);
 - `_theme-dark.scss` — переопределения назначений для `[data-theme='dark']`;
+- `_theme-dark-rules.scss` — правила тёмной темы, которые свойств не объявляют: подложка экранов
+  входа и инверсия логотипа;
 - `_scrollbar.scss` — оформление полос прокрутки;
 - `_breakpoints.scss` — SCSS-переменные порогов: свойства оформления в `@media` не работают,
   поэтому пороги остаются переменными препроцессора;
@@ -84,19 +107,60 @@ export const appConfig: ApplicationConfig = {
 отдаёт функцией-переводчиком:
 
 ```typescript
-import { provideRtKitLabels, RtKitLabelKey, RtKitLabelParams } from '@rt-tools/ui-kit-v2';
+import { provideRtKitLabels, TRtKitLabelKey, TRtKitLabelParams } from '@rt-tools/ui-kit-v2';
 
 provideRtKitLabels({
-    translator: computed(() => (key: RtKitLabelKey, params?: RtKitLabelParams) => myDictionary(key, params)),
+    translator: computed(() => (key: TRtKitLabelKey, params?: TRtKitLabelParams) => myDictionary(key, params)),
     locale: myLocale, // Signal<string>; ею кит форматирует даты
 });
 ```
 
 Способ доставки — дело приложения: Transloco, `$localize`, собственный словарь. Кит знает
-только ключи (`RtKitLabelKey` — перечень выводится из английского набора, поэтому опечатка не
+только ключи (`TRtKitLabelKey` — перечень выводится из английского набора, поэтому опечатка не
 доживает до рантайма) и то, что на них отвечают готовой строкой: подстановки вида `{{name}}`
 переводчик делает сам. Подпись, которой он не дал, берётся английской — поштучно, не набором.
 
+## Настройка компонента снаружи
+
+Компонент не берёт ступень шкалы там, где рисует себя: между ступенью и местом употребления
+стоит своё свойство компонента — `--rt-<блок>-<что>`. Объявлено оно в корне блока, значением по
+умолчанию стоит та самая ступень, поэтому без единой строки от приложения кит выглядит так же,
+как выглядел.
+
+Своими свойствами покрыты четыре рода назначений:
+
+| Род           | Имя свойства                        | Где применяется                                                 |
+| ------------- | ----------------------------------- | --------------------------------------------------------------- |
+| скругление    | `--rt-<блок>-*-radius`              | рамка блока, пузырь, значок, плашка, кольцо аватара             |
+| тень          | `--rt-<блок>-*-shadow`              | карточка, панель в перекрытии, кольцо фокуса, приподнятая точка |
+| толщина рамки | `--rt-<блок>-*-border-width`        | обводка, разделитель строк, дорожка, полоса под вкладкой        |
+| длительность  | `--rt-<блок>-*-transition-duration` | переход цвета, фона, размера и сдвига                           |
+
+Отступ, кегль и габариты остаются на ступенях намеренно: роль отступа одним словом не
+называется, и свойство под неё вышло бы именем места, а не именем роли.
+
+Приложение переопределяет свойство правилом той же цели и большей силы — наследования тут мало,
+объявление живёт на самом блоке:
+
+```css
+.my-app .rt-button {
+    --rt-btn-radius: 0;
+}
+```
+
+Часть, которую браузер уносит из поддерева блока — панель списка, меню, перетаскиваемая
+строка, — объявляет свойство на себе, и целиться в неё надо тоже отдельно:
+
+```css
+.my-app .rt-select__panel {
+    --rt-select-panel-shadow: none;
+}
+```
+
+Что ни один компонент этот порядок не обошёл, проверяет `pnpm run check:tokens-styles`: ступень,
+взятая в стилях компонента напрямую, роняет прогон. Показ на витрине — страница
+`Foundation / Design Tokens / Component Props`.
+
 ## Свой логотип
 
 `rt-logo` рисует то, что даст приложение: своих начертаний кит не везёт.
@@ -121,3 +185,19 @@ pnpm exec nx test @rt-tools/ui-kit-v2
 pnpm exec nx lint @rt-tools/ui-kit-v2
 pnpm exec stylelint "projects/ui-kit-v2/**/*.scss"
 ```
+
+## Переход на слой каскада
+
+Стили кита переехали в слой `rt-kit`, и это меняет вид у тех, кто настраивал кит поверх. Ошибки
+сборки не будет — узнаётся глазами, поэтому названо здесь прямо.
+
+- **Правило приложения теперь выигрывает у правила кита независимо от специфичности.** Место,
+  где кит перебивали поднятой специфичностью или обходом чужой вёрстки, продолжит работать, но
+  надобности в этом больше нет: обычное правило сильнее любого правила из слоя.
+- **Правило кита теперь проигрывает и чужой библиотеке, чей CSS объявлен вне слоя.** Тема
+  редактора текста подключается в подслой `vendor` — импортом с именем подслоя; подключённая
+  мимо, она перестраивает панель редактора.
+- **Кит больше не настаивает на своём восклицательным знаком.** Таблица в карточном виде
+  перестала перебивать `min-width` приложения: приложению, которому нужен и горизонтальный
+  скролл, и карточный вид, остаётся сузить свой селектор до широкого экрана.
+