@rt-tools/ui-kit-v2 0.11.0 → 0.13.0

package/README.md

@@ -14,19 +14,30 @@
 pnpm add @rt-tools/ui-kit-v2 @rt-tools/core @rt-tools/utils
 ```
 
-`quill` нужен только тем, кто ставит `rt-rich-editor`: редактор грузит его динамически, и без
-пакета остальной кит работает.
+`quill` нужен только тем, кто ставит редактор текста. Он и два компонента на нём — поле ввода
+сообщения и чат — стоят отдельным входом `@rt-tools/ui-kit-v2/rich-editor`:
+
+```typescript
+import { RtChatComponent, RtMessageComposerComponent, RtRichEditorComponent } from '@rt-tools/ui-kit-v2/rich-editor';
+```
+
+Основной вход quill не называет, и приложение без этих трёх компонентов собирается без него.
 
 ## Подключение
 
 ```typescript
+import { provideRtIDBStorage } from '@rt-tools/core';
 import { provideRtIcons } from '@rt-tools/ui-kit-v2';
 
 export const appConfig: ApplicationConfig = {
-    providers: [provideHttpClient(), provideRtIcons()],
+    providers: [provideHttpClient(), provideRtIcons(), provideRtIDBStorage()],
 };
 ```
 
+`provideRtIDBStorage()` нужен `rt-data-table`, `rt-data-list` и `rt-table`: они хранят настройку
+колонок в базе браузера. Без него страница с ними пустая, а в консоли стоит
+`NG0201: No provider found for _IDBStorageService`.
+
 Оформление — одной строкой в точке входа приложения; в пакете лежит и собранный CSS со всеми
 свойствами, и исходники партиалов:
 
@@ -41,6 +52,39 @@ export const appConfig: ApplicationConfig = {
 Объявления свойств на корне страницы в слой не уходят — их приложение перебивает порядком,
 объявляя своё после `tokens.css`.
 
+Тёмная тема кита включается только признаком на корне: `[data-theme='dark']` или класс
+`html.rt-theme-dark`. Системную настройку CSS кита не читает: по ней признак ставит `ThemeService`
+в режиме `auto`. Своя тема Material или класс тёмной темы приложения кит не переключают.
+На узле ниже корня `[data-theme='dark']` даёт тёмный кусок страницы.
+
+Под материальным набором тёмная тема не перебивает цвета, которые набор берёт из `--mat-sys-*`.
+Поиск, поля отбора и пагинация следуют теме Material приложения, а она отвечает тёмной сама.
+Без темы Material на странице набор рисует тёмные цвета кита.
+
+Оба признака на корне ставят на `body` фон-градиент тёмной темы. Приложению со своим фоном
+страницы его нужно перебить своим правилом `body`.
+
+Приложение, которое переезжает с `@rt-tools/ui-kit` и пока держит оба кита, подключает ещё один
+файл — файл совместимости, он лежит рядом с `tokens.css`:
+
+```scss
+@use '@rt-tools/ui-kit-v2/styles/tokens.coexist.css';
+```
+
+Первый кит объявляет на корне страницы десять ступеней с теми же именами — `--rt-radius-*` и
+`--rt-shadow-sm/md/lg` — и своими значениями. Его файл подключается позже, и внутри компонентов
+второго кита действуют его ступени: скругление поля отбора выходит 8px вместо 4px. Файл
+совместимости ставит значения второго кита на узел материального набора (`.rt-preset-material`,
+`[data-preset='material']`), и такой узел рисуется своей шкалой, что бы ни лежало на корне. Набор
+может стоять и на самом корне страницы: селектор файла весит на ступень больше корня первого кита,
+и порядок подключения ничего не решает.
+
+С этим файлом приложению не нужны свои скругления поверх кита: поле отбора, поле поиска и кнопки
+страниц берут значения второго кита сами.
+
+Файл удаляется вместе с первым китом. Он повторяет значения шкалы второго кита, поэтому без первого
+кита вид от его удаления не меняется.
+
 Подслой `vendor` — для чужого CSS, который чинит кит. Тема редактора текста подключается в
 него, иначе она выигрывает у правил кита и панель редактора перестраивается:
 
@@ -48,6 +92,25 @@ export const appConfig: ApplicationConfig = {
 @import 'quill/dist/quill.snow.css' layer(rt-kit.vendor);
 ```
 
+Сброс приложения вида `* { margin: 0; padding: 0; }` вне слоя выигрывает у кита по тому же
+правилу. Он обнуляет поля компонентов: ячейки таблицы, пункты меню и кнопки теряют отступы.
+Сброс кладётся в тот же подслой `vendor`. Подслой нижний, и кит перебивает сброс своими
+правилами, а остальная вёрстка приложения получает его как прежде:
+
+```scss
+@layer rt-kit.vendor {
+    * {
+        margin: 0;
+        padding: 0;
+    }
+}
+```
+
+Полосу прокрутки кит рисует только своим узлам — с классом на `rt-`. Узлы приложения он не
+трогает, и их `::-webkit-scrollbar` работает и в Chrome. Своя полоса приложения, поставленная всем
+узлам, кладётся в тот же подслой `vendor`: вне слоя она перебивает полосы кита, и таблица
+перестаёт прятать полосу, которую человек выключил в настройке колонок.
+
 Иконки лежат отдельными файлами в `node_modules/@rt-tools/ui-kit-v2/src/assets/icons`: сборка
 копирует каталог в свою статику, а `provideRtIcons('/icons')` называет адрес, по которому он
 опубликован. Файл забирается тогда, когда значок с этим именем попросила разметка, и дальше
@@ -61,6 +124,36 @@ export const appConfig: ApplicationConfig = {
 }
 ```
 
+Приложение, которое объявляет материальный набор оформления, публикует и второй набор значков —
+рисунки Material из `src/assets/icons-material`. Его адрес по умолчанию `/icons-material`, свой
+называется вторым аргументом: `provideRtIcons('/icons', '/icons-material')`. Без этой записи
+кит рисует свои значки и под материальным набором: пустого места не будет, но и рисунка Material
+тоже.
+
+```json
+{
+    "glob": "**/*.svg",
+    "input": "node_modules/@rt-tools/ui-kit-v2/src/assets/icons-material",
+    "output": "icons-material"
+}
+```
+
+Шрифт кит везёт сам. Начертания Montserrat лежат в
+`node_modules/@rt-tools/ui-kit-v2/src/assets/fonts`, объявления `@font-face` — в слое оформления,
+и адрес в них относительный: сборка приложения разрешает его от места файла стилей и уносит
+файлы в свою статику сама. Отдельной настройки это не просит — в отличие от значков, которые
+публикуются по адресу.
+
+Начертание переменное, одно на все насыщенности: кит объявляет веса 400, 500, 600 и 700 и берёт
+их из одной оси. Подмножеств четыре — кириллица, кириллическое расширение, латиница и латинское
+расширение, каждое в прямом и наклонном начертании; браузер качает только те, чьи знаки на
+странице встретились. Всего 332 КБ, русской странице достаются два файла из восьми.
+
+Письменностей, которых в Montserrat нет, кит не везёт: тайская, хангыль и деванагари добавляются
+приложением — своим `@font-face` и своим именем в конце `--rt-font-family-sans`. Именовать
+семейство, которого кит не везёт, он не будет: названное и не привезённое рисуется тем, что
+случайно стоит на машине читателя, а отступы и высоты строк кита рассчитаны под Montserrat.
+
 ## Что внутри
 
 **Компоненты** — 73 семейства: поля формы (`rt-input`, `rt-select`, `rt-multiselect`,
@@ -79,16 +172,24 @@ export const appConfig: ApplicationConfig = {
   `pnpm run build:tokens-source` и руками не правятся;
 - `_primitives.scss` — шкалы: нейтральные и цветные ряды, отступы, радиусы, тени, типографика;
 - `_semantic.scss` — назначения поверх шкал (`--rt-color-bg-surface`, `--rt-color-text-muted`);
+- `_coarse-pointer.scss` — поправка назначений для сенсорного экрана: поле ввода не мельче 16px;
 - `_theme-dark.scss` — переопределения назначений для `[data-theme='dark']`;
 - `_theme-dark-rules.scss` — правила тёмной темы, которые свойств не объявляют: подложка экранов
   входа и инверсия логотипа;
+- `_theme-scope.scss` — те же назначения для узла, а не для корня: под ними живёт метка
+  `rtTheme`, и каждое правило объявляет весь набор целиком;
 - `_scrollbar.scss` — оформление полос прокрутки;
 - `_breakpoints.scss` — SCSS-переменные порогов: свойства оформления в `@media` не работают,
   поэтому пороги остаются переменными препроцессора;
 - `_mixins.scss` — миксины поверхности карточки и её заголовка;
 - `_login.scss` — раскладка страницы входа.
 
-Всё, кроме `_breakpoints.scss`, собирает `_index.scss` — из него и собран `tokens.css`. Пороги и
+`_coexist.scss` — ступени второго кита на узле материального набора на время переезда с первого
+кита. Его собирает тот же генератор из источника шкалы, а файл совместимости собран из него
+отдельно.
+
+Всё, кроме `_breakpoints.scss` и `_coexist.scss`, собирает `_index.scss` — из него и собран
+`tokens.css`. Пороги и
 миксины подключаются партиалами напрямую:
 
 ```scss
@@ -96,9 +197,13 @@ export const appConfig: ApplicationConfig = {
 @use 'pkg:@rt-tools/ui-kit-v2/styles/mixins';
 ```
 
-**Среда исполнения** — `ThemeService` (тема на `<html data-theme>`, переживает перезагрузку),
+**Среда исполнения** — `ThemeService` (три состояния темы, признак на `<html data-theme>`,
+переживает перезагрузку), `RtThemeScopeDirective` (метка `rtTheme`: своя тема у узла),
 `BreakpointsService` (сигналы совпадения по ширине), `NotificationBus` (шина тостов).
 
+**Умолчания кита** — `provideRtKit`: приложение одной раздачей задаёт тему старта и вид кнопки и
+шторы. Раздача необязательна, а вход, написанный в разметке, её перебивает.
+
 **Подписи** — 131 ключ: кнопки диалогов, тексты ошибок поля, расшифровки иконок для
 скринридера. Своего языка у кита нет и быть не может — его знает приложение.