@1337exp/taoui 5.4.0 → 5.6.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +41 -0
- package/README.md +834 -833
- package/README.ru.md +834 -833
- package/dist/index.d.ts +113 -7
- package/dist/index.js +399 -147
- package/dist/index.js.map +1 -1
- package/dist/styles.css +1 -1
- package/package.json +105 -105
- package/skills/taoui/SKILL.md +4 -3
- package/skills/taoui/references/components.md +7 -3
- package/src/styles/contexts/surface.css +7 -1
- package/src/styles/themes/dark.css +1 -1
- package/src/styles/themes/light.css +4 -3
- package/src/styles/tokens/primitives.css +5 -5
package/README.ru.md
CHANGED
|
@@ -1,833 +1,834 @@
|
|
|
1
|
-
<h1 align="center">Tao UI</h1>
|
|
2
|
-
|
|
3
|
-
<p align="center">
|
|
4
|
-
<b>Библиотека Vue 3 компонентов на дизайн-токенах.</b><br>
|
|
5
|
-
Поменял несколько CSS-переменных — поменялась тема всего набора.
|
|
6
|
-
</p>
|
|
7
|
-
|
|
8
|
-
<p align="center">
|
|
9
|
-
<a href="https://www.npmjs.com/package/@1337exp/taoui"><img src="https://img.shields.io/npm/v/@1337exp/taoui?color=cb3837&logo=npm" alt="npm"></a>
|
|
10
|
-
<a href="https://github.com/1337exp/taoui/actions/workflows/ci.yml"><img src="https://github.com/1337exp/taoui/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
11
|
-
<a href="https://github.com/1337exp/taoui/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@1337exp/taoui" alt="license"></a>
|
|
12
|
-
<img src="https://img.shields.io/badge/Vue-3-42b883?logo=vuedotjs&logoColor=white" alt="Vue 3">
|
|
13
|
-
<img src="https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white" alt="TypeScript">
|
|
14
|
-
</p>
|
|
15
|
-
|
|
16
|
-
<p align="center">
|
|
17
|
-
<a href="https://github.com/1337exp/taoui/blob/master/README.md">English</a> · <b>Русский</b> ·
|
|
18
|
-
<a href="#установка">Установка</a> ·
|
|
19
|
-
<a href="#демонстрация">Демонстрация</a> ·
|
|
20
|
-
<a href="CHANGELOG.md">Список изменений</a>
|
|
21
|
-
</p>
|
|
22
|
-
|
|
23
|
-
<p align="center">
|
|
24
|
-
<img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/overview-dark.webp" alt="Компоненты Tao UI в тёмной теме" width="860">
|
|
25
|
-
</p>
|
|
26
|
-
|
|
27
|
-
## Почему Tao UI
|
|
28
|
-
|
|
29
|
-
- **Сначала токены.** Цвета, радиусы, отступы и шрифты — CSS-переменные в три слоя (примитивы, семантика, тема). Перекрасить набор или одну панель можно, не трогая компоненты. Размер и плотность — тоже контексты: задайте их один раз на панели, и всё внутри последует.
|
|
30
|
-
- **Палитры.** Семь готовых палитр, каждая из четырёх цветов, или своя в рантайме (`applyTaoPalette`). Статусные цвета сами отходят от акцента, а графики перекрашиваются вместе с темой.
|
|
31
|
-
- **Контраст, которому можно верить.** Цветовые пары тем и палитр проверяются тестами по WCAG 2 (4.5:1 для текста, 3:1 для подписи на заливке); тёмной или белой быть подписи, решает APCA.
|
|
32
|
-
- **Подстраивается без JS.** `TaoNav` превращается из нижней панели в рейку и боковую панель, bento-сетка перестраивается, главное действие переезжает вместе с навигацией — по ширине своего контейнера (container queries), а не окна. После гидратации ничего не прыгает.
|
|
33
|
-
- **Клавиатура и скринридеры.** Меню, полоса меню, панель инструментов, дерево и навигация сделаны по шаблонам WAI-ARIA: одна остановка Tab и стрелки внутри (roving tabindex), переключатели с `aria-pressed`, `role="meter"`, ловушки фокуса в оверлеях.
|
|
34
|
-
- **Графики по-честному.** Маленькие `TaoSparkline` / `TaoMeter` / `TaoDonut` для карточек и строк текста; для настоящих графиков `taoChartTheme()` отдаёт цвета темы в Chart.js, ECharts или uPlot.
|
|
35
|
-
- **Встроенные языки.** Плейсхолдеры, даты и aria-подписи на русском и английском, переключаются на лету без перезагрузки.
|
|
36
|
-
- **Nuxt и чистый Vue.** `TaoLink` сам выбирает `NuxtLink`, `RouterLink` или `<a>`. Полные типы, ESM, рендер каждого компонента на сервере проверен тестами.
|
|
37
|
-
- **Готов для ИИ-ассистентов.** В пакете есть skill со справочником всех компонентов, он генерируется из этой документации, поэтому ассистент пишет код на Tao UI, а не угадывает.
|
|
38
|
-
|
|
39
|
-
<table>
|
|
40
|
-
<tr>
|
|
41
|
-
<td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/color-picker.webp" alt="TaoColorPicker: квадрат, полоса тона, режимы HEX / RGB / HSL"><br><sub><b>TaoColorPicker</b> — HEX / RGB / HSL, пипетка, <code>v-model</code> — строка hex</sub></td>
|
|
42
|
-
<td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/themes.webp" alt="Переключение тёмной и светлой тем"><br><sub><b>Темы</b> — один атрибут, все компоненты следуют</sub></td>
|
|
43
|
-
</tr>
|
|
44
|
-
<tr>
|
|
45
|
-
<td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/slider.webp" alt="TaoRangeSlider с метками"><br><sub><b>TaoSlider / TaoRangeSlider</b> — метки, дискретные шкалы, вертикаль</sub></td>
|
|
46
|
-
<td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/surfaces-dark.webp" alt="Поверхности flat, grain и glass"><br><sub><b>Поверхности</b> — flat, grain, glass</sub></td>
|
|
47
|
-
</tr>
|
|
48
|
-
</table>
|
|
49
|
-
|
|
50
|
-
## Компоненты
|
|
51
|
-
|
|
52
|
-
### Базовые
|
|
53
|
-
|
|
54
|
-
- **TaoBlock** — базовый контейнер с настраиваемыми отступами и скруглением
|
|
55
|
-
- **TaoButton** — кнопка. `variant`: `primary` / `secondary` / `ghost` / `text`; `tone` красит любой из них (по умолчанию акцент, neutral, success, danger, warning, info). `v-model:pressed` делает её переключателем (`aria-pressed`)
|
|
56
|
-
- **TaoCard** — карточка со слотами media / header / title / footer и `#corner` (тег, кнопка меню). В `#media` — фото или `TaoCarousel`; `closable` добавляет крестик и событие `close`. `flush` — плитка без padding/тени на всю ячейку; `#overlay` — scrim на media; `stripe="top | left | bottom"` со `stripeTone` (тон или `gradient` палитры) рисует цветную полосу, которую обрезают углы
|
|
57
|
-
- **TaoCopy** — иконка копирования в буфер. После клика сверху тултип «Скопировано»; если кнопку убрали — тултип тоже
|
|
58
|
-
- **TaoMarquee** — одна строка без переносов: не помещается — бежит по кругу с гаснущими краями и паузой в начале каждого круга, помещается — стоит. Останавливается при наведении, фокусе и тапе (WCAG 2.2.2); при «уменьшить движение» переносится; скринридер читает один раз. `text` или строчное содержимое в слоте, `speed`, `gap`, `fade` (левое затухание занимает столько места слева от текста: дайте родителю такой padding), `paused`
|
|
59
|
-
- **TaoInput** — поле ввода с поддержкой v-model, валидации и слотов `#prefix` / `#suffix` (иконка или текст внутри рамки)
|
|
60
|
-
- **TaoInputGroup** — склейка снаружи: `#before` | поле | `#after` (протокол, единица, кнопка)
|
|
61
|
-
- **TaoModal** — модальное окно с анимацией и
|
|
62
|
-
- **TaoDrawer** — боковая панель (фильтры, настройки)
|
|
63
|
-
- **TaoSpoiler** — раскрывающийся блок. `v-model` и `aria-expanded`. Несколько подряд сами друг друга не закрывают
|
|
64
|
-
- **TaoSpoilerGroup** — аккордеон: `v-model` — ключ открытой панели (`null` — все закрыты), у спойлера `name`. Без `v-model` группа помнит ключ сама
|
|
65
|
-
- **TaoTabs** — вкладки для переключения между секциями контента
|
|
66
|
-
- **TaoNav** — навигация между разделами приложения: один список пунктов (`icon`, `href`, `badge`), три вида. `layout="auto"` выбирает по ширине самого TaoNav (container queries, без JS): нижняя панель до 600px (больше пяти пунктов: «Ещё» с меню), рейка с иконками до 840px, боковая панель с подписями от 840px. Со страницей в слоте раскладывает её сам: панель прилипает к низу (с учётом безопасной зоны), боковой список к верху. `floating` отрывает нижнюю панель в отдельную «пилюлю» с тенью (рейка и боковая панель не меняются). Слот `#action` — главное действие экрана, оно идёт за навигацией: круглое над панелью у конечного края, наверху рейки, широкое с текстом наверху боковой панели. `select(id, event)` даёт роутеру перехватить ссылку
|
|
67
|
-
- **TaoTooltip** — всплывающая подсказка при наведении. `placement`: `top` / `bottom` / `left` / `right`, у каждого `-start` / `-end`; у края экрана переворачивается
|
|
68
|
-
- **TaoPopover** — панель по клику: слот с любым контентом, Esc и клик снаружи; `placement` как у Tooltip. Не тултип и не меню действий
|
|
69
|
-
|
|
70
|
-
### Layout
|
|
71
|
-
|
|
72
|
-
- **TaoContainer** — контейнер с ограничением ширины (wide/slim/ultra-slim) и авто-центровкой
|
|
73
|
-
- **TaoFlex** — обёртка над flexbox с пропами justify/align/direction/wrap/gap
|
|
74
|
-
- **TaoSpace** — авто-расстановка дочерних элементов с равномерным gap
|
|
75
|
-
- **TaoGrid** / **TaoGridItem** — плитки: `min` — каталог (auto-fill), `cols` — bento. Адаптивный bento берёт значения по классам ширины самой сетки (compact < 600px, medium < 840px, expanded): `:cols="{ compact: 3, expanded: 6 }"`, `:col="{ compact: 'full', expanded: 4 }"`, `:order="{ compact: 9 }"` — на телефоне крупные блоки занимают ряд, мелкие плитки остаются по три, боковой уходит вниз. Простое число — одна колонка на телефоне. `rowHeight` задаёт высоту ряда, как нужно мозаике. Не masonry
|
|
76
|
-
- **TaoDivider** — `solid` (обычный border) / `dashed` / `colored` (акцент) / `gap`. Подпись — опциональный `text` на любом варианте; `fade` — плавные края линии; `size` только у `gap` (small / medium / large)
|
|
77
|
-
- **TaoSplit** — две панели и полоса. `row` / `column` как у Flex. `v-model` — размер start в `%` или `px`; `resizable="false"` фиксирует полосу. Не Divider.
|
|
78
|
-
- **TaoFieldset** — рамка-группа: `legend` сидит на верхней границе, `align` — start / center / end
|
|
79
|
-
- **TaoAnimatedBorder** — контейнер с анимированной рамкой: радуга, цвета `tone` (следует теме) или свои `colors`; при `prefers-reduced-motion` градиент стоит на месте
|
|
80
|
-
|
|
81
|
-
### Формы и ввод
|
|
82
|
-
|
|
83
|
-
- **TaoCheckbox** — чекбокс с v-model, слотами pre/post и `indeterminate` (частично выбран)
|
|
84
|
-
- **TaoChecklist** — чекбоксы с одной моделью (отмеченные значения): `select-all` с промежуточным состоянием, `counter` «3 из 5», `strike` для списка дел (только вид, состояние говорит чекбокс), `description` у пункта. Это fieldset: в `TaoFormField` группа берёт подпись и ошибку
|
|
85
|
-
- **TaoSwitch** — переключатель для булевых настроек (`role="switch"`)
|
|
86
|
-
- **TaoRadio** / **TaoRadioGroup** — классические радиокнопки: длинные подписи, можно столбиком
|
|
87
|
-
- **TaoSegmented** / **TaoSegmentedOption** — компактный выбор из 2–5 коротких вариантов. Не вкладки
|
|
88
|
-
- **TaoSelect** — выпадающий список с клавиатурой, тот же визуал, что у Input. `size` (`small` / `medium` / `large`, та же шкала, что у Button). Сброс — «Очистить» в списке или Delete; `clearable="false"` отключает сброс, слот `#clear` заменяет содержимое строки
|
|
89
|
-
- **TaoCombobox** — Select с полем: фильтр по вводу, `allow-create` пишет своё в `v-model`, `create` — чтобы родитель дополнил список. Те же `size`, `clearable` и `#clear`, что у `TaoSelect`
|
|
90
|
-
- **TaoDate** — один день: `YYYY-MM-DD`, без часов и пояса. Календарь как у Select
|
|
91
|
-
- **TaoDateRange** — период: `v-model` — `{ start, end }` или `null`. Первый клик — начало, второй — конец (если конец раньше — меняются местами). Неполный выбор в модель не пишется
|
|
92
|
-
- **TaoCalendar** — сам календарь на месяц, встроенный (без всплывающего окна): `mode="single"` (`YYYY-MM-DD`) или `"range"` (`{ start, end }`), `min` / `max`, стрелки / PageUp / PageDown / Home / End. `TaoDate` и `TaoDateRange` — поле с этим календарём во всплывающем окне
|
|
93
|
-
- **TaoFormField** — общие label / hint / error для полей формы
|
|
94
|
-
- **TaoInputNumber** — число с min/max/step и кнопками ± справа. Пустое значение — `null`. `@commit` срабатывает один раз, когда правка закончена (blur, Enter, ±, стрелка), в отличие от `v-model`, который обновляется на каждую клавишу
|
|
95
|
-
- **TaoQuantity** — количество в корзине: `− | поле | +`, целые штуки, сток, минус на минимуме может убрать строку
|
|
96
|
-
- **TaoTextarea** — многострочное поле с авто-высотой. `maxlength` ограничивает ввод, `count` показывает «введено / максимум». `variant`: `bar` (по умолчанию) / `outline` (рамка как у Input) / `filled` / `plain`; `readonly`; `align`; `blurOnEnter`
|
|
97
|
-
- **TaoPinCode** — пин-код из N полей. По умолчанию клик стирает ячейку и все справа (`clear-on="focus"`); `clear-on="input"` заменяет цифру только при вводе. `format="#-##-##"` рисует визуальные разделители (в значение не входят; вставка в таком виде или чистым кодом раскладывается по ячейкам). Последняя ячейка снимает фокус и эмитит `complete`; `status="success | error"` (после `complete`) подсвечивает или встряхивает ячейки и говорит об этом скринридеру
|
|
98
|
-
- **TaoSlider** / **TaoRangeSlider** — один бегунок (`v-model` — число) или два (`[от, до]`, `minGap`). Мышь, тач, стрелки. `marks` (деления, числа, `{ value, label }`), `discrete` для ступенчатых шкал, `vertical`, `flat`, `format`; `variant="thin"` — тонкий трек для seek / громкости
|
|
99
|
-
- **TaoColorPicker** — квадрат насыщенности и яркости, полосы тона и прозрачности, образцы, пипетка (где есть `EyeDropper`), режимы ввода HEX / RGB / HSL. `v-model` — строка hex; `colorModel()` подключает ваше собственное хранилище цвета
|
|
100
|
-
- **TaoColorInput** — поле с образцом и hex-текстом; палитра открывается в поповере
|
|
101
|
-
- **TaoFileDrop** — зона загрузки (drag & drop + клик). Список имён под зоной, `v-model` — `File[]`. Очистку всей пачки решает родитель (`clear-request`)
|
|
102
|
-
|
|
103
|
-
### Отображение данных
|
|
104
|
-
|
|
105
|
-
- **TaoTable** — простая таблица: колонки, empty, loading, сортировка через `v-model:sort`. `head` — подсветка шапки, `lines` — линии между рядами (оба по умолчанию включены). `striped` — зебра с первой строки, `striped="even"` — со второй. Не datagrid.
|
|
106
|
-
- **TaoSparkline** / **TaoMeter** / **TaoDonut** — маленькие графики для карточки или строки текста: тренд (`values` с разрывами `null`, `area`, `dot`), измеренное значение в диапазоне (`role="meter"`, цвет по `low` / `high` / `optimum`, как у HTML `<meter>`), доля целого (`segments` или одно `value` из `max`, `legend`, слот в центре). Цвета серий — роли `--tao-color-chart-1…6` (первый — акцент, поэтому палитры их перекрашивают). Для осей и подсказок берите библиотеку графиков: `taoChartTheme()` отдаёт ей цвета темы в `rgb()`, `watchTaoChartTheme(apply)` применяет их заново при смене темы или палитры
|
|
107
|
-
- **TaoPagination** — страницы с многоточием. Клик по «…» прыгает на `jump` страниц (5 по умолчанию)
|
|
108
|
-
- **TaoEmpty** — пустой список, нет результатов, нет прав
|
|
109
|
-
- **TaoList** / **TaoListItem** — строка списка: иконка, заголовок, подпись, действие по ховеру. Не Select и не таблица
|
|
110
|
-
- **TaoTree** — файлы или объекты деревом: `v-model:expanded`, выбор `none | single | multiple` (`v-model:selected`), чекбоксы с промежуточным состоянием родителя (`checkable`, `v-model:checked`), ленивая подгрузка (`hasChildren` + `load`). ARIA tree: одна остановка Tab, стрелки, `→` / `←` внутрь и наружу, Home / End, `*`, поиск по буквам. Слоты `#icon`, `#label`, `#actions`; строки на токенах контролов (размер и плотность)
|
|
111
|
-
- **TaoStages** — список стадий: `wait` / `work` / `ok` / `bad`. Не линейный степпер
|
|
112
|
-
- **TaoTimeline** — вертикальная лента событий: шаги заказа, релизы, журнал. `active` заливает линию до текущего события (`aria-current="step"`), без него лента — журнал прошедшего; `tone` и `icon` у маркера, слоты `#marker` / `#title` / `#content`; `align="alternate"` раскладывает события по обе стороны и складывается в одну уже 480px своей ширины
|
|
113
|
-
- **TaoSkeleton** — плейсхолдер загрузки (text / title / circle / rect)
|
|
114
|
-
- **TaoCounter** — витрина числа с переворотом цифр (не инпут)
|
|
115
|
-
- **TaoCarousel** — лента: целый слайд с `autoplay`, карточка с `peek`, полоса с `per-view`. Стрелки через `controls` или `#prev` / `#next`; метки под лентой — `indicator` (`dots`, `bars` или `progress`). С `autoplay` текущая метка заполняется за интервал, по заполнении слайд меняется; hover, фокус с клавиатуры, касание, скрытая вкладка и кнопка паузы останавливают, `prefers-reduced-motion` выключает
|
|
116
|
-
- **TaoAvatar** — фото или инициалы, размеры `small` / `medium` / `large`. Точка `dot` и счётчик `count`
|
|
117
|
-
- **TaoTag** — тег/бейдж со статусами. `#prefix` (аватар), `closable` убирает чип, `flat` — без рамки
|
|
118
|
-
- **TaoAlert** — инлайн-баннер страницы или ошибки формы (success / error / warning / info); `collapsible` сворачивает тело под заголовок (поиск по странице его всё равно находит)
|
|
119
|
-
- **TaoProgress** — статичная полоса (`progress` в %). Проценты сверху по центру или `showPercentage="right"` справа; слоты `#left` / `#right` — подписи, тогда процент справа в скобках. `false` прячет. Ширина — `minWidth` / `maxWidth`, не диапазон значения
|
|
120
|
-
- **TaoScrubber** — play / pause, слайдер по времени с метками событий, подпись «время / длина». Время сама не двигает: ведите `v-model` своими часами
|
|
121
|
-
- **TaoLoader** — анимированный лоадер (четыре точки)
|
|
122
|
-
- **TaoImage** — обёртка над `<img>`: fade-in и плейсхолдер. `lazy` включает нативный `loading="lazy"`
|
|
123
|
-
- **TaoIcon** — SVG-иконки (
|
|
124
|
-
|
|
125
|
-
### Навигация и взаимодействие
|
|
126
|
-
|
|
127
|
-
- **TaoLink** — `<NuxtLink>` в Nuxt, `<RouterLink>` при vue-router, иначе обычный `<a>` — без дополнительной настройки
|
|
128
|
-
- **TaoBreadcrumb** — крошки: последний пункт — текущая страница
|
|
129
|
-
- **TaoDropdownMenu** / **TaoMenu** — меню из простого дерева данных `items`: подменю, чекбоксы, радио, разделители, подписи групп, сочетания для показа, недоступные пункты. Стрелки, Home / End, быстрый поиск по букве, `→` / `←` для подменю, Esc закрывает верхний уровень первым. `TaoMenu` — сама панель для своих оболочек (полоса меню, контекстное меню); у края экрана переворачивается
|
|
130
|
-
- **TaoMenubar** / **TaoContextMenu** — полоса меню редактора и меню по правой кнопке, на `TaoMenu`. Полоса — одна остановка Tab (`role="menubar"`): `←` / `→` ходят по ней, `↓` / Enter открывают, при открытом меню `←` / `→` и указатель переходят к соседнему; пункт без `items` — обычное действие. Контекстное меню открывается у указателя (или у элемента для клавиши Menu / Shift+F10) и оборачивает содержимое без своей коробки
|
|
131
|
-
- **TaoToolbar** / **TaoToolbarGroup** / **TaoToolbarSeparator** — панель инструментов (`role="toolbar"`): одна остановка Tab, `←` / `→` (или `↑` / `↓` при `orientation="vertical"`) ходят по элементам, Home / End; внутри `TaoSegmented` стрелки выбирают вариант и идут дальше с его края. Группы делит тонкая черта поперёк панели; `inset` кладёт под группу утопленную подложку. Переключатели — `TaoButton` с `v-model:pressed`
|
|
132
|
-
- **TaoScrollTop** — плавающая кнопка «наверх»: виды `solid` / `ghost` / `text`, `side`, подпись `label` при наведении мыши. Появляется при обратном скролле после `boundary`
|
|
133
|
-
|
|
134
|
-
### Обратная связь
|
|
135
|
-
|
|
136
|
-
- **toast()** — fluent-уведомления: `toast().success().message('Сохранено')`
|
|
137
|
-
- **confirm()** — вопрос с оверлеем: тот же fluent + `await`. Не тост — ждёт ответ, не исчезает сам.
|
|
138
|
-
- **TaoToastViewport** / **TaoConfirmHost** — контейнеры; если их нет в разметке, первый вызов сам монтирует их в `body`
|
|
139
|
-
|
|
140
|
-
## Соглашения
|
|
141
|
-
|
|
142
|
-
Тоны визуала: `success` | `danger` | `warning` | `info` | `neutral` (тип `TaoTone`), всегда через проп `tone`: Button, Alert, Tag (`toast.danger()` для тостов). Акцент — тоже тон и тон по умолчанию. Тон — контекстный класс, как размер: `.tao-tone-danger` на любом элементе выставляет `--tao-tone`, `--tao-tone-on`, `--tao-tone-text`, … (см. `styles/tone.css`). В отличие от размера, он **не** наследуется: кнопка внутри красного alert остаётся акцентной.
|
|
143
|
-
Stages — это процесс, не тон: `wait` / `work` / `ok` / `bad` (`danger` принимается как `bad`).
|
|
144
|
-
|
|
145
|
-
Размеры контролов: `small` | `medium` | `large` (тип `TaoSize`). Одна шкала для Button, Input, InputNumber, Quantity, Textarea, Select, Combobox, Date, DateRange, Segmented, InputGroup и FormField — контролы одного размера встают в ряд ровно. Checkbox, Radio / RadioGroup и Switch масштабируют индикатор (14 / 18 / 22px) и подпись; Tag — высоту (18 / 20 / 24px); Tabs, кнопки Pagination и строки List берут высоту Button; Table масштабирует отступы ячеек (`size="small"` для плотной); FileDrop — зону и строки файлов; Slider — трек и бегунок.
|
|
146
|
-
Без `size` контрол берёт размер предков, в корне — `medium`. На целый блок размер задаётся классом `tao-size-small` / `-medium` / `-large` на любом элементе или `size` у `TaoFormField` / `TaoInputGroup`. Явный `size` у контрола главнее.
|
|
147
|
-
|
|
148
|
-
```vue
|
|
149
|
-
<div class="tao-size-small">
|
|
150
|
-
<TaoInput v-model="q" />
|
|
151
|
-
<TaoButton>Найти</TaoButton>
|
|
152
|
-
</div>
|
|
153
|
-
```
|
|
154
|
-
|
|
155
|
-
Контент и раскладка держат свою шкалу и не наследуют: Avatar (24 / 32 / 48px), Divider `gap`, Loader / Icon / ScrollTop (пиксели).
|
|
156
|
-
Container живёт на другой оси — ширина: `width="wide" | "slim" | "ultra-slim"`.
|
|
157
|
-
|
|
158
|
-
**Плотность** — вторая ось контролов поверх размера: класс `tao-density-compact` / `-comfortable` / `-auto` на контейнере (или на `<html>`) меняет высоту и отступы любого размера в нём, но не шрифт. `comfortable` даёт 34 / 44 / 52px (строки под палец), `compact` 22 / 32 / 40px (плотные инструменты и таблицы), `auto` — comfortable на сенсорном экране (`pointer: coarse`) и обычная с мышью. Select и Combobox переносят её в свои панели. Тип `TaoDensity`; шаги — токены `--tao-density-height-*` / `--tao-density-padding-x-*` / `-y-*`.
|
|
159
|
-
|
|
160
|
-
```html
|
|
161
|
-
<html class="tao-density-auto">
|
|
162
|
-
```
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
Поверхности — из чего «сделана» панель: `flat` — заливка (по умолчанию), `grain` — статичное плёночное зерно, `glass` —
|
|
166
|
-
полупрозрачное стекло с размытием того, что позади. Проп `surface` у TaoCard / TaoBlock или класс `tao-surface-grain` /
|
|
167
|
-
`-glass` на любом элементе — HUD в игре, секция лендинга, сайдбар. Вид настраивается один раз токенами темы
|
|
168
|
-
(`--tao-surface-grain-image` / `-size`, `--tao-glass-fill` / `-border` / `-blur`). Поверхность принадлежит одному элементу:
|
|
169
|
-
вложенные панели её не наследуют. Стеклу нужно что-то позади — используйте его для того, что лежит поверх контента; над
|
|
170
|
-
ровным фоном это просто серая заливка, над анимацией размытие пересчитывается каждый кадр. Toast и confirm стеклянные по
|
|
171
|
-
умолчанию, с оттенком своего тона; `toast.defaults({ surface: 'flat' })` и `confirm.defaults({ surface: 'flat' })`
|
|
172
|
-
выключают стекло, `.surface('flat')` — для одного. Без поддержки размытия или при `prefers-reduced-transparency` стекло
|
|
173
|
-
становится сплошной панелью.
|
|
174
|
-
|
|
175
|
-
Шкала кегля (примитивы): `xs` 12 … `xl` 18 для контролов; `2xl` 24, `3xl` 32, `4xl` 36 для заголовков и прозы.
|
|
176
|
-
Отдельного компонента заголовка нет — `h1 { font-size: var(--tao-font-size-3xl) }`.
|
|
177
|
-
|
|
178
|
-
Правила API — им следуют все компоненты:
|
|
179
|
-
|
|
180
|
-
- **Поля** принимают `v-model`, `disabled`, `error` (красная рамка) и `size`. Подпись, подсказка и текст ошибки — через `TaoFormField`.
|
|
181
|
-
- **События**: `update:X` для v-model плюс `change`, когда пользователь закончил изменение (Slider, Split — по отпусканию). Остальные события — глаголы в настоящем времени: `select`, `close`, `create`.
|
|
182
|
-
- **Тексты**: видимые — `*Text` (`clearText`, `successText`), для скринридера — `*Label` (`closeLabel`).
|
|
183
|
-
- **Списки**: массивы данных — `items`; выбираемые элементы несут `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Идентификаторы обычных данных (колонки таблицы, стадии) остаются `key`.
|
|
184
|
-
- **Булевы** — прилагательные без `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Ось раскладки — `direction: 'row' | 'column'`, не `vertical`.
|
|
185
|
-
- **Длины** (`padding`, `radius`, `gap`, `maxHeight`): число — пиксели, строка уходит в CSS как есть (тип `TaoLength`).
|
|
186
|
-
|
|
187
|
-
## Типографика
|
|
188
|
-
|
|
189
|
-
Слой включается явно: библиотека не оформляет голые `h1` и `p`. Поставьте `.tao-prose` на обёртку — и текст внутри
|
|
190
|
-
получит заголовки, абзацы, списки, цитаты, код, линии и ссылки в ролях темы, с отступами по близости (заголовок ближе
|
|
191
|
-
к своему тексту и дальше от блока перед ним). Все правила внутри в `:where()`, поэтому ваш CSS всегда главнее.
|
|
192
|
-
|
|
193
|
-
```html
|
|
194
|
-
<article class="tao-prose">
|
|
195
|
-
<h1>Заголовок</h1>
|
|
196
|
-
<p>Текст со <a href="/docs">ссылкой</a>.</p>
|
|
197
|
-
</article>
|
|
198
|
-
|
|
199
|
-
<h2 class="tao-heading-5">h2 размером с уровень 5</h2>
|
|
200
|
-
```
|
|
201
|
-
|
|
202
|
-
Шкала заголовков — из двух чисел: `--tao-text-base` (16px, текст и h6) и `--tao-text-ratio` (1.25), каждый уровень выше —
|
|
203
|
-
ещё один шаг: 16 / 20 / 25 / 31 / 39 / 49. Поставьте коэффициент на `:root` или на одну обёртку (1.2 спокойнее, 1.333
|
|
204
|
-
смелее) — шкала под ней последует; h1 и h2 уменьшаются на узком экране, но не ниже h3 / h4. Шаги — токены
|
|
205
|
-
`--tao-heading-1…6` для своих правил. `.tao-heading-1…6` даёт вид уровня любому тегу: тег говорит, что это, класс —
|
|
206
|
-
какого размера.
|
|
207
|
-
|
|
208
|
-
### Для ИИ-ассистентов
|
|
209
|
-
|
|
210
|
-
В пакете есть skill, `skills/taoui/SKILL.md` с `references/components.md`: подключение, правила (роли, а не цвета; контексты, а не пропсы), каждый компонент и его пропсы, типичные ошибки. Покажите его ассистенту; для Claude Code скопируйте `node_modules/@1337exp/taoui/skills/taoui` в `.claude/skills/` проекта. Справочник компонентов генерируется из таблиц пропсов шоукейса (`npm run skill`), а тест следит, чтобы skill называл каждый компонент.
|
|
211
|
-
|
|
212
|
-
## Иконки
|
|
213
|
-
|
|
214
|
-
Библиотека поставляет **
|
|
215
|
-
play, pause, skip-back, копия, календарь, info, alert, кружки, папка,
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
<TaoIcon name="
|
|
221
|
-
<
|
|
222
|
-
<TaoButton icon="tao-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
|
|
234
|
-
|
|
235
|
-
|
|
236
|
-
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
import
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
import
|
|
284
|
-
import
|
|
285
|
-
import '@1337exp/taoui
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
app
|
|
289
|
-
app.
|
|
290
|
-
|
|
291
|
-
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
|
|
308
|
-
|
|
309
|
-
`
|
|
310
|
-
|
|
311
|
-
|
|
312
|
-
|
|
313
|
-
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
321
|
-
|
|
322
|
-
|
|
323
|
-
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
337
|
-
|
|
338
|
-
|
|
339
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
343
|
-
import '@1337exp/taoui
|
|
344
|
-
|
|
345
|
-
|
|
346
|
-
|
|
347
|
-
|
|
348
|
-
<
|
|
349
|
-
|
|
350
|
-
|
|
351
|
-
|
|
352
|
-
|
|
353
|
-
|
|
354
|
-
</
|
|
355
|
-
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
|
|
360
|
-
|
|
361
|
-
|
|
362
|
-
|
|
363
|
-
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
|
|
367
|
-
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
<template #
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
toast().
|
|
383
|
-
toast.
|
|
384
|
-
toast.
|
|
385
|
-
|
|
386
|
-
|
|
387
|
-
|
|
388
|
-
|
|
389
|
-
|
|
390
|
-
|
|
391
|
-
toast.
|
|
392
|
-
|
|
393
|
-
|
|
394
|
-
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
400
|
-
|
|
401
|
-
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
419
|
-
|
|
420
|
-
|
|
421
|
-
|
|
422
|
-
|
|
423
|
-
|
|
424
|
-
|
|
425
|
-
|
|
426
|
-
|
|
427
|
-
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
|
|
432
|
-
|
|
433
|
-
|
|
434
|
-
|
|
435
|
-
|
|
436
|
-
|
|
437
|
-
|
|
438
|
-
|
|
439
|
-
|
|
440
|
-
|
|
441
|
-
|
|
442
|
-
<TaoRadio value="
|
|
443
|
-
|
|
444
|
-
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
<TaoSegmentedOption value="
|
|
448
|
-
<TaoSegmentedOption value="
|
|
449
|
-
|
|
450
|
-
|
|
451
|
-
|
|
452
|
-
|
|
453
|
-
|
|
454
|
-
|
|
455
|
-
|
|
456
|
-
|
|
457
|
-
|
|
458
|
-
|
|
459
|
-
|
|
460
|
-
|
|
461
|
-
|
|
462
|
-
|
|
463
|
-
|
|
464
|
-
|
|
465
|
-
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
|
|
490
|
-
:
|
|
491
|
-
|
|
492
|
-
|
|
493
|
-
|
|
494
|
-
|
|
495
|
-
|
|
496
|
-
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
</
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
{ key: '
|
|
508
|
-
{ key: '
|
|
509
|
-
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
</
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
<TaoSkeleton
|
|
526
|
-
<TaoSkeleton
|
|
527
|
-
|
|
528
|
-
|
|
529
|
-
|
|
530
|
-
{ key: '
|
|
531
|
-
{ key: '
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
535
|
-
|
|
536
|
-
|
|
537
|
-
|
|
538
|
-
|
|
539
|
-
|
|
540
|
-
|
|
541
|
-
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
</
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
|
|
553
|
-
|
|
554
|
-
|
|
555
|
-
|
|
556
|
-
<
|
|
557
|
-
<
|
|
558
|
-
|
|
559
|
-
|
|
560
|
-
</
|
|
561
|
-
|
|
562
|
-
|
|
563
|
-
|
|
564
|
-
|
|
565
|
-
|
|
566
|
-
|
|
567
|
-
|
|
568
|
-
|
|
569
|
-
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
579
|
-
|
|
580
|
-
|
|
581
|
-
|
|
582
|
-
|
|
583
|
-
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
<
|
|
589
|
-
|
|
590
|
-
</
|
|
591
|
-
|
|
592
|
-
<TaoCarousel
|
|
593
|
-
|
|
594
|
-
<template #
|
|
595
|
-
|
|
596
|
-
|
|
597
|
-
|
|
598
|
-
|
|
599
|
-
|
|
600
|
-
|
|
601
|
-
|
|
602
|
-
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
607
|
-
|
|
608
|
-
|
|
609
|
-
|
|
610
|
-
|
|
611
|
-
|
|
612
|
-
|
|
613
|
-
|
|
614
|
-
|
|
615
|
-
|
|
616
|
-
|
|
617
|
-
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
621
|
-
|
|
622
|
-
|
|
623
|
-
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
| `tokens/
|
|
628
|
-
| `
|
|
629
|
-
| `themes/
|
|
630
|
-
| `
|
|
631
|
-
| `
|
|
632
|
-
|
|
633
|
-
|
|
634
|
-
|
|
635
|
-
|
|
636
|
-
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
|
|
640
|
-
|
|
641
|
-
|
|
642
|
-
|
|
643
|
-
|
|
644
|
-
|
|
645
|
-
--tao-color-accent
|
|
646
|
-
--tao-color-
|
|
647
|
-
--tao-color-
|
|
648
|
-
--tao-color-surface
|
|
649
|
-
--tao-color-
|
|
650
|
-
--tao-color-text
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
|
|
655
|
-
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
661
|
-
</
|
|
662
|
-
|
|
663
|
-
|
|
664
|
-
|
|
665
|
-
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
|
|
669
|
-
|
|
670
|
-
|
|
671
|
-
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
- `--tao-color-
|
|
675
|
-
- `--tao-color-
|
|
676
|
-
- `--tao-color-
|
|
677
|
-
- `--tao-color-
|
|
678
|
-
- `--tao-color-
|
|
679
|
-
- `--tao-color-
|
|
680
|
-
- `--tao-color-
|
|
681
|
-
- `--tao-
|
|
682
|
-
- `--tao-
|
|
683
|
-
- `--tao-
|
|
684
|
-
- `--tao-
|
|
685
|
-
|
|
686
|
-
|
|
687
|
-
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
|
|
696
|
-
import '@1337exp/taoui/
|
|
697
|
-
|
|
698
|
-
|
|
699
|
-
|
|
700
|
-
|
|
701
|
-
<html data-tao-theme="sunset"
|
|
702
|
-
|
|
703
|
-
|
|
704
|
-
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
709
|
-
|
|
710
|
-
-
|
|
711
|
-
-
|
|
712
|
-
-
|
|
713
|
-
|
|
714
|
-
|
|
715
|
-
|
|
716
|
-
|
|
717
|
-
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
721
|
-
|
|
722
|
-
stop(
|
|
723
|
-
|
|
724
|
-
|
|
725
|
-
|
|
726
|
-
|
|
727
|
-
|
|
728
|
-
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
|
|
736
|
-
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
|
|
741
|
-
|
|
742
|
-
|
|
743
|
-
|
|
744
|
-
|
|
745
|
-
|
|
|
746
|
-
|
|
747
|
-
|
|
748
|
-
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
import '@1337exp/taoui/styles/tokens/
|
|
764
|
-
import '
|
|
765
|
-
import '
|
|
766
|
-
import '@1337exp/taoui/styles/contexts/
|
|
767
|
-
import '@1337exp/taoui/styles/contexts/
|
|
768
|
-
import '@1337exp/taoui/styles/
|
|
769
|
-
|
|
770
|
-
|
|
771
|
-
|
|
772
|
-
|
|
773
|
-
|
|
774
|
-
|
|
775
|
-
|
|
776
|
-
|
|
777
|
-
|
|
778
|
-
npm
|
|
779
|
-
|
|
780
|
-
|
|
781
|
-
|
|
782
|
-
|
|
783
|
-
|
|
784
|
-
|
|
785
|
-
|
|
786
|
-
|
|
787
|
-
|
|
788
|
-
|
|
789
|
-
|
|
790
|
-
|
|
791
|
-
|
|
792
|
-
|
|
793
|
-
|
|
794
|
-
|
|
795
|
-
|
|
796
|
-
|
|
797
|
-
|
|
798
|
-
|
|
799
|
-
|
|
800
|
-
|
|
801
|
-
|
|
802
|
-
|
|
803
|
-
|
|
804
|
-
|
|
805
|
-
|
|
806
|
-
|
|
807
|
-
|
|
808
|
-
|
|
809
|
-
|
|
810
|
-
|
|
811
|
-
|
|
812
|
-
|
|
813
|
-
|
|
814
|
-
|
|
815
|
-
|
|
816
|
-
|
|
817
|
-
|
|
818
|
-
|
|
819
|
-
|
|
820
|
-
|
|
821
|
-
|
|
822
|
-
|
|
823
|
-
|
|
824
|
-
|
|
825
|
-
|
|
826
|
-
|
|
827
|
-
|
|
828
|
-
|
|
829
|
-
|
|
830
|
-
|
|
831
|
-
|
|
832
|
-
|
|
833
|
-
|
|
1
|
+
<h1 align="center">Tao UI</h1>
|
|
2
|
+
|
|
3
|
+
<p align="center">
|
|
4
|
+
<b>Библиотека Vue 3 компонентов на дизайн-токенах.</b><br>
|
|
5
|
+
Поменял несколько CSS-переменных — поменялась тема всего набора.
|
|
6
|
+
</p>
|
|
7
|
+
|
|
8
|
+
<p align="center">
|
|
9
|
+
<a href="https://www.npmjs.com/package/@1337exp/taoui"><img src="https://img.shields.io/npm/v/@1337exp/taoui?color=cb3837&logo=npm" alt="npm"></a>
|
|
10
|
+
<a href="https://github.com/1337exp/taoui/actions/workflows/ci.yml"><img src="https://github.com/1337exp/taoui/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
|
|
11
|
+
<a href="https://github.com/1337exp/taoui/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@1337exp/taoui" alt="license"></a>
|
|
12
|
+
<img src="https://img.shields.io/badge/Vue-3-42b883?logo=vuedotjs&logoColor=white" alt="Vue 3">
|
|
13
|
+
<img src="https://img.shields.io/badge/types-included-3178c6?logo=typescript&logoColor=white" alt="TypeScript">
|
|
14
|
+
</p>
|
|
15
|
+
|
|
16
|
+
<p align="center">
|
|
17
|
+
<a href="https://github.com/1337exp/taoui/blob/master/README.md">English</a> · <b>Русский</b> ·
|
|
18
|
+
<a href="#установка">Установка</a> ·
|
|
19
|
+
<a href="#демонстрация">Демонстрация</a> ·
|
|
20
|
+
<a href="CHANGELOG.md">Список изменений</a>
|
|
21
|
+
</p>
|
|
22
|
+
|
|
23
|
+
<p align="center">
|
|
24
|
+
<img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/overview-dark.webp" alt="Компоненты Tao UI в тёмной теме" width="860">
|
|
25
|
+
</p>
|
|
26
|
+
|
|
27
|
+
## Почему Tao UI
|
|
28
|
+
|
|
29
|
+
- **Сначала токены.** Цвета, радиусы, отступы и шрифты — CSS-переменные в три слоя (примитивы, семантика, тема). Перекрасить набор или одну панель можно, не трогая компоненты. Размер и плотность — тоже контексты: задайте их один раз на панели, и всё внутри последует.
|
|
30
|
+
- **Палитры.** Семь готовых палитр, каждая из четырёх цветов, или своя в рантайме (`applyTaoPalette`). Статусные цвета сами отходят от акцента, а графики перекрашиваются вместе с темой.
|
|
31
|
+
- **Контраст, которому можно верить.** Цветовые пары тем и палитр проверяются тестами по WCAG 2 (4.5:1 для текста, 3:1 для подписи на заливке); тёмной или белой быть подписи, решает APCA.
|
|
32
|
+
- **Подстраивается без JS.** `TaoNav` превращается из нижней панели в рейку и боковую панель, bento-сетка перестраивается, главное действие переезжает вместе с навигацией — по ширине своего контейнера (container queries), а не окна. После гидратации ничего не прыгает.
|
|
33
|
+
- **Клавиатура и скринридеры.** Меню, полоса меню, панель инструментов, дерево и навигация сделаны по шаблонам WAI-ARIA: одна остановка Tab и стрелки внутри (roving tabindex), переключатели с `aria-pressed`, `role="meter"`, ловушки фокуса в оверлеях.
|
|
34
|
+
- **Графики по-честному.** Маленькие `TaoSparkline` / `TaoMeter` / `TaoDonut` для карточек и строк текста; для настоящих графиков `taoChartTheme()` отдаёт цвета темы в Chart.js, ECharts или uPlot.
|
|
35
|
+
- **Встроенные языки.** Плейсхолдеры, даты и aria-подписи на русском и английском, переключаются на лету без перезагрузки.
|
|
36
|
+
- **Nuxt и чистый Vue.** `TaoLink` сам выбирает `NuxtLink`, `RouterLink` или `<a>`. Полные типы, ESM, рендер каждого компонента на сервере проверен тестами.
|
|
37
|
+
- **Готов для ИИ-ассистентов.** В пакете есть skill со справочником всех компонентов, он генерируется из этой документации, поэтому ассистент пишет код на Tao UI, а не угадывает.
|
|
38
|
+
|
|
39
|
+
<table>
|
|
40
|
+
<tr>
|
|
41
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/color-picker.webp" alt="TaoColorPicker: квадрат, полоса тона, режимы HEX / RGB / HSL"><br><sub><b>TaoColorPicker</b> — HEX / RGB / HSL, пипетка, <code>v-model</code> — строка hex</sub></td>
|
|
42
|
+
<td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/themes.webp" alt="Переключение тёмной и светлой тем"><br><sub><b>Темы</b> — один атрибут, все компоненты следуют</sub></td>
|
|
43
|
+
</tr>
|
|
44
|
+
<tr>
|
|
45
|
+
<td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/slider.webp" alt="TaoRangeSlider с метками"><br><sub><b>TaoSlider / TaoRangeSlider</b> — метки, дискретные шкалы, вертикаль</sub></td>
|
|
46
|
+
<td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/surfaces-dark.webp" alt="Поверхности flat, grain и glass"><br><sub><b>Поверхности</b> — flat, grain, glass</sub></td>
|
|
47
|
+
</tr>
|
|
48
|
+
</table>
|
|
49
|
+
|
|
50
|
+
## Компоненты
|
|
51
|
+
|
|
52
|
+
### Базовые
|
|
53
|
+
|
|
54
|
+
- **TaoBlock** — базовый контейнер с настраиваемыми отступами и скруглением
|
|
55
|
+
- **TaoButton** — кнопка. `variant`: `primary` / `secondary` / `ghost` / `text`; `tone` красит любой из них (по умолчанию акцент, neutral, success, danger, warning, info). `v-model:pressed` делает её переключателем (`aria-pressed`)
|
|
56
|
+
- **TaoCard** — карточка со слотами media / header / title / footer и `#corner` (тег, кнопка меню). В `#media` — фото или `TaoCarousel`; `closable` добавляет крестик и событие `close`. `flush` — плитка без padding/тени на всю ячейку; `#overlay` — scrim на media; `stripe="top | left | bottom"` со `stripeTone` (тон или `gradient` палитры) рисует цветную полосу, которую обрезают углы
|
|
57
|
+
- **TaoCopy** — иконка копирования в буфер. После клика сверху тултип «Скопировано»; если кнопку убрали — тултип тоже
|
|
58
|
+
- **TaoMarquee** — одна строка без переносов: не помещается — бежит по кругу с гаснущими краями и паузой в начале каждого круга, помещается — стоит. Останавливается при наведении, фокусе и тапе (WCAG 2.2.2); при «уменьшить движение» переносится; скринридер читает один раз. `text` или строчное содержимое в слоте, `speed`, `gap`, `fade` (левое затухание занимает столько места слева от текста: дайте родителю такой padding), `paused`
|
|
59
|
+
- **TaoInput** — поле ввода с поддержкой v-model, валидации и слотов `#prefix` / `#suffix` (иконка или текст внутри рамки)
|
|
60
|
+
- **TaoInputGroup** — склейка снаружи: `#before` | поле | `#after` (протокол, единица, кнопка)
|
|
61
|
+
- **TaoModal** — модальное окно с анимацией и слотами; `fullscreen` (или `fullscreen="narrow"`: страница на телефоне, окно на компьютере)
|
|
62
|
+
- **TaoDrawer** — боковая панель (фильтры, настройки) или нижний лист с `side="bottom"`. Esc, клик по фону, ловушка фокуса — как у модалки
|
|
63
|
+
- **TaoSpoiler** — раскрывающийся блок. `v-model` и `aria-expanded`. Несколько подряд сами друг друга не закрывают
|
|
64
|
+
- **TaoSpoilerGroup** — аккордеон: `v-model` — ключ открытой панели (`null` — все закрыты), у спойлера `name`. Без `v-model` группа помнит ключ сама
|
|
65
|
+
- **TaoTabs** — вкладки для переключения между секциями контента
|
|
66
|
+
- **TaoNav** — навигация между разделами приложения: один список пунктов (`icon`, `href`, `badge`), три вида. `layout="auto"` выбирает по ширине самого TaoNav (container queries, без JS): нижняя панель до 600px (больше пяти пунктов: «Ещё» с меню), рейка с иконками до 840px, боковая панель с подписями от 840px. Со страницей в слоте раскладывает её сам: панель прилипает к низу (с учётом безопасной зоны), боковой список к верху. `floating` отрывает нижнюю панель в отдельную «пилюлю» с тенью (рейка и боковая панель не меняются). Слот `#action` — главное действие экрана, оно идёт за навигацией: круглое над панелью у конечного края, наверху рейки, широкое с текстом наверху боковой панели. `select(id, event)` даёт роутеру перехватить ссылку
|
|
67
|
+
- **TaoTooltip** — всплывающая подсказка при наведении. `placement`: `top` / `bottom` / `left` / `right`, у каждого `-start` / `-end`; у края экрана переворачивается
|
|
68
|
+
- **TaoPopover** — панель по клику: слот с любым контентом, Esc и клик снаружи; `placement` как у Tooltip. Не тултип и не меню действий
|
|
69
|
+
|
|
70
|
+
### Layout
|
|
71
|
+
|
|
72
|
+
- **TaoContainer** — контейнер с ограничением ширины (wide/slim/ultra-slim) и авто-центровкой
|
|
73
|
+
- **TaoFlex** — обёртка над flexbox с пропами justify/align/direction/wrap/gap
|
|
74
|
+
- **TaoSpace** — авто-расстановка дочерних элементов с равномерным gap
|
|
75
|
+
- **TaoGrid** / **TaoGridItem** — плитки: `min` — каталог (auto-fill), `cols` — bento. Адаптивный bento берёт значения по классам ширины самой сетки (compact < 600px, medium < 840px, expanded): `:cols="{ compact: 3, expanded: 6 }"`, `:col="{ compact: 'full', expanded: 4 }"`, `:order="{ compact: 9 }"` — на телефоне крупные блоки занимают ряд, мелкие плитки остаются по три, боковой уходит вниз. Простое число — одна колонка на телефоне. `rowHeight` задаёт высоту ряда, как нужно мозаике. Не masonry
|
|
76
|
+
- **TaoDivider** — `solid` (обычный border) / `dashed` / `colored` (акцент) / `gap`. Подпись — опциональный `text` на любом варианте; `fade` — плавные края линии; `size` только у `gap` (small / medium / large)
|
|
77
|
+
- **TaoSplit** — две панели и полоса. `row` / `column` как у Flex. `v-model` — размер start в `%` или `px`; `resizable="false"` фиксирует полосу. Не Divider.
|
|
78
|
+
- **TaoFieldset** — рамка-группа: `legend` сидит на верхней границе, `align` — start / center / end
|
|
79
|
+
- **TaoAnimatedBorder** — контейнер с анимированной рамкой: радуга, цвета `tone` (следует теме) или свои `colors`; при `prefers-reduced-motion` градиент стоит на месте
|
|
80
|
+
|
|
81
|
+
### Формы и ввод
|
|
82
|
+
|
|
83
|
+
- **TaoCheckbox** — чекбокс с v-model, слотами pre/post и `indeterminate` (частично выбран)
|
|
84
|
+
- **TaoChecklist** — чекбоксы с одной моделью (отмеченные значения): `select-all` с промежуточным состоянием, `counter` «3 из 5», `strike` для списка дел (только вид, состояние говорит чекбокс), `description` у пункта. Это fieldset: в `TaoFormField` группа берёт подпись и ошибку
|
|
85
|
+
- **TaoSwitch** — переключатель для булевых настроек (`role="switch"`)
|
|
86
|
+
- **TaoRadio** / **TaoRadioGroup** — классические радиокнопки: длинные подписи, можно столбиком
|
|
87
|
+
- **TaoSegmented** / **TaoSegmentedOption** — компактный выбор из 2–5 коротких вариантов. Не вкладки
|
|
88
|
+
- **TaoSelect** — выпадающий список с клавиатурой, тот же визуал, что у Input. `size` (`small` / `medium` / `large`, та же шкала, что у Button). Сброс — «Очистить» в списке или Delete; `clearable="false"` отключает сброс, слот `#clear` заменяет содержимое строки
|
|
89
|
+
- **TaoCombobox** — Select с полем: фильтр по вводу, `allow-create` пишет своё в `v-model`, `create` — чтобы родитель дополнил список. Те же `size`, `clearable` и `#clear`, что у `TaoSelect`
|
|
90
|
+
- **TaoDate** — один день: `YYYY-MM-DD`, без часов и пояса. Календарь как у Select. `editable` делает его полем для ввода: `5`, `5.3`, `05.03.26` в порядке дня и месяца языка (`parseTaoDateInput` экспортируется, `parse` / `format` принимают свои)
|
|
91
|
+
- **TaoDateRange** — период: `v-model` — `{ start, end }` или `null`. Первый клик — начало, второй — конец (если конец раньше — меняются местами). Неполный выбор в модель не пишется
|
|
92
|
+
- **TaoCalendar** — сам календарь на месяц, встроенный (без всплывающего окна): `mode="single"` (`YYYY-MM-DD`) или `"range"` (`{ start, end }`), `min` / `max`, стрелки / PageUp / PageDown / Home / End. `TaoDate` и `TaoDateRange` — поле с этим календарём во всплывающем окне
|
|
93
|
+
- **TaoFormField** — общие label / hint / error для полей формы
|
|
94
|
+
- **TaoInputNumber** — число с min/max/step и кнопками ± справа. Пустое значение — `null`. `@commit` срабатывает один раз, когда правка закончена (blur, Enter, ±, стрелка), в отличие от `v-model`, который обновляется на каждую клавишу
|
|
95
|
+
- **TaoQuantity** — количество в корзине: `− | поле | +`, целые штуки, сток, минус на минимуме может убрать строку
|
|
96
|
+
- **TaoTextarea** — многострочное поле с авто-высотой. `maxlength` ограничивает ввод, `count` показывает «введено / максимум». `variant`: `bar` (по умолчанию) / `outline` (рамка как у Input) / `filled` / `plain`; `readonly`; `align`; `blurOnEnter`
|
|
97
|
+
- **TaoPinCode** — пин-код из N полей. По умолчанию клик стирает ячейку и все справа (`clear-on="focus"`); `clear-on="input"` заменяет цифру только при вводе. `format="#-##-##"` рисует визуальные разделители (в значение не входят; вставка в таком виде или чистым кодом раскладывается по ячейкам). Последняя ячейка снимает фокус и эмитит `complete`; `status="success | error"` (после `complete`) подсвечивает или встряхивает ячейки и говорит об этом скринридеру
|
|
98
|
+
- **TaoSlider** / **TaoRangeSlider** — один бегунок (`v-model` — число) или два (`[от, до]`, `minGap`). Мышь, тач, стрелки. `marks` (деления, числа, `{ value, label }`), `discrete` для ступенчатых шкал, `vertical`, `flat`, `format`; `variant="thin"` — тонкий трек для seek / громкости
|
|
99
|
+
- **TaoColorPicker** — квадрат насыщенности и яркости, полосы тона и прозрачности, образцы, пипетка (где есть `EyeDropper`), режимы ввода HEX / RGB / HSL. `v-model` — строка hex; `colorModel()` подключает ваше собственное хранилище цвета
|
|
100
|
+
- **TaoColorInput** — поле с образцом и hex-текстом; палитра открывается в поповере
|
|
101
|
+
- **TaoFileDrop** — зона загрузки (drag & drop + клик). Список имён под зоной, `v-model` — `File[]`. Очистку всей пачки решает родитель (`clear-request`)
|
|
102
|
+
|
|
103
|
+
### Отображение данных
|
|
104
|
+
|
|
105
|
+
- **TaoTable** — простая таблица: колонки, empty, loading, сортировка через `v-model:sort`. `head` — подсветка шапки, `lines` — линии между рядами (оба по умолчанию включены). `striped` — зебра с первой строки, `striped="even"` — со второй. Не datagrid.
|
|
106
|
+
- **TaoSparkline** / **TaoMeter** / **TaoDonut** — маленькие графики для карточки или строки текста: тренд (`values` с разрывами `null`, `area`, `dot`), измеренное значение в диапазоне (`role="meter"`, цвет по `low` / `high` / `optimum`, как у HTML `<meter>`), доля целого (`segments` или одно `value` из `max`, `legend`, слот в центре). Цвета серий — роли `--tao-color-chart-1…6` (первый — акцент, поэтому палитры их перекрашивают). Для осей и подсказок берите библиотеку графиков: `taoChartTheme()` отдаёт ей цвета темы в `rgb()`, `watchTaoChartTheme(apply)` применяет их заново при смене темы или палитры
|
|
107
|
+
- **TaoPagination** — страницы с многоточием. Клик по «…» прыгает на `jump` страниц (5 по умолчанию)
|
|
108
|
+
- **TaoEmpty** — пустой список, нет результатов, нет прав
|
|
109
|
+
- **TaoList** / **TaoListItem** — строка списка: иконка, заголовок, подпись, действие по ховеру. Не Select и не таблица
|
|
110
|
+
- **TaoTree** — файлы или объекты деревом: `v-model:expanded`, выбор `none | single | multiple` (`v-model:selected`), чекбоксы с промежуточным состоянием родителя (`checkable`, `v-model:checked`), ленивая подгрузка (`hasChildren` + `load`). ARIA tree: одна остановка Tab, стрелки, `→` / `←` внутрь и наружу, Home / End, `*`, поиск по буквам. Слоты `#icon`, `#label`, `#actions`; строки на токенах контролов (размер и плотность)
|
|
111
|
+
- **TaoStages** — список стадий: `wait` / `work` / `ok` / `bad`. Не линейный степпер
|
|
112
|
+
- **TaoTimeline** — вертикальная лента событий: шаги заказа, релизы, журнал. `active` заливает линию до текущего события (`aria-current="step"`), без него лента — журнал прошедшего; `tone` и `icon` у маркера, слоты `#marker` / `#title` / `#content`; `align="alternate"` раскладывает события по обе стороны и складывается в одну уже 480px своей ширины
|
|
113
|
+
- **TaoSkeleton** — плейсхолдер загрузки (text / title / circle / rect)
|
|
114
|
+
- **TaoCounter** — витрина числа с переворотом цифр (не инпут)
|
|
115
|
+
- **TaoCarousel** — лента: целый слайд с `autoplay`, карточка с `peek`, полоса с `per-view`. Стрелки через `controls` или `#prev` / `#next`; метки под лентой — `indicator` (`dots`, `bars` или `progress`). С `autoplay` текущая метка заполняется за интервал, по заполнении слайд меняется; hover, фокус с клавиатуры, касание, скрытая вкладка и кнопка паузы останавливают, `prefers-reduced-motion` выключает
|
|
116
|
+
- **TaoAvatar** — фото или инициалы, размеры `small` / `medium` / `large`. Точка `dot` и счётчик `count`
|
|
117
|
+
- **TaoTag** — тег/бейдж со статусами. `#prefix` (аватар), `closable` убирает чип, `flat` — без рамки
|
|
118
|
+
- **TaoAlert** — инлайн-баннер страницы или ошибки формы (success / error / warning / info); `collapsible` сворачивает тело под заголовок (поиск по странице его всё равно находит)
|
|
119
|
+
- **TaoProgress** — статичная полоса (`progress` в %). Проценты сверху по центру или `showPercentage="right"` справа; слоты `#left` / `#right` — подписи, тогда процент справа в скобках. `false` прячет. Ширина — `minWidth` / `maxWidth`, не диапазон значения
|
|
120
|
+
- **TaoScrubber** — play / pause, слайдер по времени с метками событий, подпись «время / длина». Время сама не двигает: ведите `v-model` своими часами
|
|
121
|
+
- **TaoLoader** — анимированный лоадер (четыре точки)
|
|
122
|
+
- **TaoImage** — обёртка над `<img>`: fade-in и плейсхолдер. `lazy` включает нативный `loading="lazy"`
|
|
123
|
+
- **TaoIcon** — SVG-иконки (40 встроенных, свои через `registerTaoIcons`) или icon-шрифт (см. раздел «Иконки» ниже)
|
|
124
|
+
|
|
125
|
+
### Навигация и взаимодействие
|
|
126
|
+
|
|
127
|
+
- **TaoLink** — `<NuxtLink>` в Nuxt, `<RouterLink>` при vue-router, иначе обычный `<a>` — без дополнительной настройки
|
|
128
|
+
- **TaoBreadcrumb** — крошки: последний пункт — текущая страница
|
|
129
|
+
- **TaoDropdownMenu** / **TaoMenu** — меню из простого дерева данных `items`: подменю, чекбоксы, радио, разделители, подписи групп, сочетания для показа, недоступные пункты. Стрелки, Home / End, быстрый поиск по букве, `→` / `←` для подменю, Esc закрывает верхний уровень первым. `TaoMenu` — сама панель для своих оболочек (полоса меню, контекстное меню); у края экрана переворачивается
|
|
130
|
+
- **TaoMenubar** / **TaoContextMenu** — полоса меню редактора и меню по правой кнопке, на `TaoMenu`. Полоса — одна остановка Tab (`role="menubar"`): `←` / `→` ходят по ней, `↓` / Enter открывают, при открытом меню `←` / `→` и указатель переходят к соседнему; пункт без `items` — обычное действие. Контекстное меню открывается у указателя (или у элемента для клавиши Menu / Shift+F10) и оборачивает содержимое без своей коробки
|
|
131
|
+
- **TaoToolbar** / **TaoToolbarGroup** / **TaoToolbarSeparator** — панель инструментов (`role="toolbar"`): одна остановка Tab, `←` / `→` (или `↑` / `↓` при `orientation="vertical"`) ходят по элементам, Home / End; внутри `TaoSegmented` стрелки выбирают вариант и идут дальше с его края. Группы делит тонкая черта поперёк панели; `inset` кладёт под группу утопленную подложку. Переключатели — `TaoButton` с `v-model:pressed`
|
|
132
|
+
- **TaoScrollTop** — плавающая кнопка «наверх»: виды `solid` / `ghost` / `text`, `side`, подпись `label` при наведении мыши. Появляется при обратном скролле после `boundary`
|
|
133
|
+
|
|
134
|
+
### Обратная связь
|
|
135
|
+
|
|
136
|
+
- **toast()** — fluent-уведомления: `toast().success().message('Сохранено')`
|
|
137
|
+
- **confirm()** — вопрос с оверлеем: тот же fluent + `await`. Не тост — ждёт ответ, не исчезает сам.
|
|
138
|
+
- **TaoToastViewport** / **TaoConfirmHost** — контейнеры; если их нет в разметке, первый вызов сам монтирует их в `body`
|
|
139
|
+
|
|
140
|
+
## Соглашения
|
|
141
|
+
|
|
142
|
+
Тоны визуала: `success` | `danger` | `warning` | `info` | `neutral` (тип `TaoTone`), всегда через проп `tone`: Button, Alert, Tag (`toast.danger()` для тостов). Акцент — тоже тон и тон по умолчанию. Тон — контекстный класс, как размер: `.tao-tone-danger` на любом элементе выставляет `--tao-tone`, `--tao-tone-on`, `--tao-tone-text`, … (см. `styles/tone.css`). В отличие от размера, он **не** наследуется: кнопка внутри красного alert остаётся акцентной.
|
|
143
|
+
Stages — это процесс, не тон: `wait` / `work` / `ok` / `bad` (`danger` принимается как `bad`).
|
|
144
|
+
|
|
145
|
+
Размеры контролов: `small` | `medium` | `large` (тип `TaoSize`). Одна шкала для Button, Input, InputNumber, Quantity, Textarea, Select, Combobox, Date, DateRange, Segmented, InputGroup и FormField — контролы одного размера встают в ряд ровно. Checkbox, Radio / RadioGroup и Switch масштабируют индикатор (14 / 18 / 22px) и подпись; Tag — высоту (18 / 20 / 24px); Tabs, кнопки Pagination и строки List берут высоту Button; Table масштабирует отступы ячеек (`size="small"` для плотной); FileDrop — зону и строки файлов; Slider — трек и бегунок.
|
|
146
|
+
Без `size` контрол берёт размер предков, в корне — `medium`. На целый блок размер задаётся классом `tao-size-small` / `-medium` / `-large` на любом элементе или `size` у `TaoFormField` / `TaoInputGroup`. Явный `size` у контрола главнее.
|
|
147
|
+
|
|
148
|
+
```vue
|
|
149
|
+
<div class="tao-size-small">
|
|
150
|
+
<TaoInput v-model="q" />
|
|
151
|
+
<TaoButton>Найти</TaoButton>
|
|
152
|
+
</div>
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
Контент и раскладка держат свою шкалу и не наследуют: Avatar (24 / 32 / 48px), Divider `gap`, Loader / Icon / ScrollTop (пиксели).
|
|
156
|
+
Container живёт на другой оси — ширина: `width="wide" | "slim" | "ultra-slim"`.
|
|
157
|
+
|
|
158
|
+
**Плотность** — вторая ось контролов поверх размера: класс `tao-density-compact` / `-comfortable` / `-auto` на контейнере (или на `<html>`) меняет высоту и отступы любого размера в нём, но не шрифт. `comfortable` даёт 34 / 44 / 52px (строки под палец), `compact` 22 / 32 / 40px (плотные инструменты и таблицы), `auto` — comfortable на сенсорном экране (`pointer: coarse`) и обычная с мышью. Select и Combobox переносят её в свои панели. Тип `TaoDensity`; шаги — токены `--tao-density-height-*` / `--tao-density-padding-x-*` / `-y-*`.
|
|
159
|
+
|
|
160
|
+
```html
|
|
161
|
+
<html class="tao-density-auto">
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
Поверхности — из чего «сделана» панель: `flat` — заливка (по умолчанию), `grain` — статичное плёночное зерно, `glass` —
|
|
166
|
+
полупрозрачное стекло с размытием того, что позади. Проп `surface` у TaoCard / TaoBlock или класс `tao-surface-grain` /
|
|
167
|
+
`-glass` на любом элементе — HUD в игре, секция лендинга, сайдбар. Вид настраивается один раз токенами темы
|
|
168
|
+
(`--tao-surface-grain-image` / `-size`, `--tao-glass-fill` / `-border` / `-blur`). Поверхность принадлежит одному элементу:
|
|
169
|
+
вложенные панели её не наследуют. Стеклу нужно что-то позади — используйте его для того, что лежит поверх контента; над
|
|
170
|
+
ровным фоном это просто серая заливка, над анимацией размытие пересчитывается каждый кадр. Toast и confirm стеклянные по
|
|
171
|
+
умолчанию, с оттенком своего тона; `toast.defaults({ surface: 'flat' })` и `confirm.defaults({ surface: 'flat' })`
|
|
172
|
+
выключают стекло, `.surface('flat')` — для одного. Без поддержки размытия или при `prefers-reduced-transparency` стекло
|
|
173
|
+
становится сплошной панелью.
|
|
174
|
+
|
|
175
|
+
Шкала кегля (примитивы): `xs` 12 … `xl` 18 для контролов; `2xl` 24, `3xl` 32, `4xl` 36 для заголовков и прозы.
|
|
176
|
+
Отдельного компонента заголовка нет — `h1 { font-size: var(--tao-font-size-3xl) }`.
|
|
177
|
+
|
|
178
|
+
Правила API — им следуют все компоненты:
|
|
179
|
+
|
|
180
|
+
- **Поля** принимают `v-model`, `disabled`, `error` (красная рамка) и `size`. Подпись, подсказка и текст ошибки — через `TaoFormField`.
|
|
181
|
+
- **События**: `update:X` для v-model плюс `change`, когда пользователь закончил изменение (Slider, Split — по отпусканию). Остальные события — глаголы в настоящем времени: `select`, `close`, `create`.
|
|
182
|
+
- **Тексты**: видимые — `*Text` (`clearText`, `successText`), для скринридера — `*Label` (`closeLabel`).
|
|
183
|
+
- **Списки**: массивы данных — `items`; выбираемые элементы несут `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Идентификаторы обычных данных (колонки таблицы, стадии) остаются `key`.
|
|
184
|
+
- **Булевы** — прилагательные без `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Ось раскладки — `direction: 'row' | 'column'`, не `vertical`.
|
|
185
|
+
- **Длины** (`padding`, `radius`, `gap`, `maxHeight`): число — пиксели, строка уходит в CSS как есть (тип `TaoLength`).
|
|
186
|
+
|
|
187
|
+
## Типографика
|
|
188
|
+
|
|
189
|
+
Слой включается явно: библиотека не оформляет голые `h1` и `p`. Поставьте `.tao-prose` на обёртку — и текст внутри
|
|
190
|
+
получит заголовки, абзацы, списки, цитаты, код, линии и ссылки в ролях темы, с отступами по близости (заголовок ближе
|
|
191
|
+
к своему тексту и дальше от блока перед ним). Все правила внутри в `:where()`, поэтому ваш CSS всегда главнее.
|
|
192
|
+
|
|
193
|
+
```html
|
|
194
|
+
<article class="tao-prose">
|
|
195
|
+
<h1>Заголовок</h1>
|
|
196
|
+
<p>Текст со <a href="/docs">ссылкой</a>.</p>
|
|
197
|
+
</article>
|
|
198
|
+
|
|
199
|
+
<h2 class="tao-heading-5">h2 размером с уровень 5</h2>
|
|
200
|
+
```
|
|
201
|
+
|
|
202
|
+
Шкала заголовков — из двух чисел: `--tao-text-base` (16px, текст и h6) и `--tao-text-ratio` (1.25), каждый уровень выше —
|
|
203
|
+
ещё один шаг: 16 / 20 / 25 / 31 / 39 / 49. Поставьте коэффициент на `:root` или на одну обёртку (1.2 спокойнее, 1.333
|
|
204
|
+
смелее) — шкала под ней последует; h1 и h2 уменьшаются на узком экране, но не ниже h3 / h4. Шаги — токены
|
|
205
|
+
`--tao-heading-1…6` для своих правил. `.tao-heading-1…6` даёт вид уровня любому тегу: тег говорит, что это, класс —
|
|
206
|
+
какого размера.
|
|
207
|
+
|
|
208
|
+
### Для ИИ-ассистентов
|
|
209
|
+
|
|
210
|
+
В пакете есть skill, `skills/taoui/SKILL.md` с `references/components.md`: подключение, правила (роли, а не цвета; контексты, а не пропсы), каждый компонент и его пропсы, типичные ошибки. Покажите его ассистенту; для Claude Code скопируйте `node_modules/@1337exp/taoui/skills/taoui` в `.claude/skills/` проекта. Справочник компонентов генерируется из таблиц пропсов шоукейса (`npm run skill`), а тест следит, чтобы skill называл каждый компонент.
|
|
211
|
+
|
|
212
|
+
## Иконки
|
|
213
|
+
|
|
214
|
+
Библиотека поставляет **40 SVG-иконок** (галочка, крестик, плюс, минус, шевроны, стрелки, поиск, глаз, «ещё», ручка,
|
|
215
|
+
play, pause, skip-back, копия, календарь, info, alert, кружки, папка, файл, выравнивание и действия приложения: настройки,
|
|
216
|
+
правка, корзина, колокольчик, тег, повтор, отменить, повторить). Они рисуются через `currentColor`: иконка берёт цвет и
|
|
217
|
+
размер текста. Имена с зарезервированной приставкой `tao-`: `<TaoIcon name="tao-check" />`, список — `taoIconNames`.
|
|
218
|
+
|
|
219
|
+
```vue
|
|
220
|
+
<TaoIcon name="tao-check" /> <!-- встроенная -->
|
|
221
|
+
<TaoIcon name="rocket" /> <!-- из registerTaoIcons или `icon-rocket` вашего шрифта -->
|
|
222
|
+
<TaoButton icon="tao-plus">Добавить</TaoButton>
|
|
223
|
+
<TaoButton icon="tao-close" aria-label="Закрыть" /> <!-- только иконка: квадрат, aria-label обязателен -->
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
```ts
|
|
227
|
+
registerTaoIcons({ rocket: { body: '<path d="M12 3l4 8-4 10-4-10z"/>' } }); // сетка 24x24, если не задан viewBox
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
Имя без приставки `tao-` ищется среди зарегистрированных вами иконок, а затем рендерится классом `icon-<name>` для
|
|
231
|
+
внешнего icon-шрифта (IcoMoon / Fontello и т. п.), который приложение подключает само. Все встроенные части (крестики,
|
|
232
|
+
степперы, стрелки пагинации, тосты…) используют встроенные иконки, а слоты `#…-icon` позволяют заменить их чем угодно.
|
|
233
|
+
|
|
234
|
+
## Установка
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
npm install @1337exp/taoui
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
Нужен Vue 3.4+. Пакет **только ESM** (Vite, Nuxt 3, webpack 5 и Node 18+ с `import` работают; голый `require('@1337exp/taoui')` — нет: используйте `import()`).
|
|
241
|
+
|
|
242
|
+
### Поддержка браузеров
|
|
243
|
+
|
|
244
|
+
CSS использует `color-mix()`, контейнерные запросы и зарегистрированные свойства (`@property`), поэтому планка —
|
|
245
|
+
**Chrome / Edge 111, Safari 16.4, Firefox 128**: браузеры 2023–2024 годов. Ограничивает Firefox 128 (`@property`).
|
|
246
|
+
В более старом браузере всё остаётся читаемым, теряется мелочь: именно зарегистрированное свойство не даёт тону
|
|
247
|
+
(`.tao-tone-*`) и поверхности «протекать» в детей, поэтому без него Button внутри красного Alert может покраснеть.
|
|
248
|
+
Тот же список — поле `browserslist` пакета и целевая платформа сборки.
|
|
249
|
+
|
|
250
|
+
Или локально из папки:
|
|
251
|
+
|
|
252
|
+
```bash
|
|
253
|
+
npm install ../path-to-tao-ui
|
|
254
|
+
```
|
|
255
|
+
|
|
256
|
+
## Использование
|
|
257
|
+
|
|
258
|
+
### Подключение в Nuxt 3
|
|
259
|
+
|
|
260
|
+
Создайте плагин `plugins/tao-ui.ts`:
|
|
261
|
+
|
|
262
|
+
```typescript
|
|
263
|
+
import { defineNuxtPlugin } from '#app'
|
|
264
|
+
import TaoUI from '@1337exp/taoui'
|
|
265
|
+
|
|
266
|
+
export default defineNuxtPlugin((nuxtApp) => {
|
|
267
|
+
nuxtApp.vueApp.use(TaoUI)
|
|
268
|
+
})
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
Импортируйте стили в `app.vue` или layout:
|
|
272
|
+
|
|
273
|
+
```vue
|
|
274
|
+
<script setup>
|
|
275
|
+
import '@1337exp/taoui/styles.css'
|
|
276
|
+
</script>
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
### Подключение в Vue 3 проекте
|
|
280
|
+
|
|
281
|
+
```javascript
|
|
282
|
+
// main.js
|
|
283
|
+
import { createApp } from 'vue'
|
|
284
|
+
import App from './App.vue'
|
|
285
|
+
import TaoUI from '@1337exp/taoui'
|
|
286
|
+
import '@1337exp/taoui/styles.css'
|
|
287
|
+
|
|
288
|
+
const app = createApp(App)
|
|
289
|
+
app.use(TaoUI)
|
|
290
|
+
app.mount('#app')
|
|
291
|
+
```
|
|
292
|
+
|
|
293
|
+
### Язык
|
|
294
|
+
|
|
295
|
+
Встроенные тексты (плейсхолдеры, «Очистить», aria-подписи, даты) по умолчанию английские. Русский идёт в комплекте:
|
|
296
|
+
|
|
297
|
+
```javascript
|
|
298
|
+
import TaoUI, { localeRu } from '@1337exp/taoui'
|
|
299
|
+
|
|
300
|
+
app.use(TaoUI, { locale: localeRu })
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
Поменять отдельные тексты — остальное останется от локали по умолчанию:
|
|
304
|
+
|
|
305
|
+
```javascript
|
|
306
|
+
app.use(TaoUI, { locale: { select: { placeholder: 'Выберите город' } } })
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
Другой язык: скопируйте `localeEn` (или `localeRu`), переведите и передайте так же (тип `TaoLocale`). Ключи повторяют имена пропсов —
|
|
310
|
+
`locale.select.placeholder` — значение по умолчанию для `placeholder` у TaoSelect, а переданный руками проп всегда главнее.
|
|
311
|
+
|
|
312
|
+
Язык можно переключать в любой момент — из настроек, переключателя языка, по маршруту. Уже показанные компоненты
|
|
313
|
+
обновятся сразу, без перезагрузки и без потери введённого:
|
|
314
|
+
|
|
315
|
+
```javascript
|
|
316
|
+
import { setTaoLocale, localeEn, localeRu } from '@1337exp/taoui'
|
|
317
|
+
|
|
318
|
+
function onLanguageChange(lang) {
|
|
319
|
+
setTaoLocale(lang === 'ru' ? localeRu : localeEn)
|
|
320
|
+
}
|
|
321
|
+
```
|
|
322
|
+
|
|
323
|
+
Без плагина (отдельные компоненты) достаточно одного вызова `setTaoLocale()`.
|
|
324
|
+
|
|
325
|
+
### Переход на 5.0
|
|
326
|
+
|
|
327
|
+
5.0 удаляет все имена, которые устарели в 2.0 (и алиас тона `error`), таблица «старое → новое» в [MIGRATION-5.md](MIGRATION-5.md).
|
|
328
|
+
|
|
329
|
+
### Переход с 3.x
|
|
330
|
+
|
|
331
|
+
В 4.0 поменялся один умолчательный параметр: встроенные тексты теперь английские (раньше были русские). Чтобы остаться
|
|
332
|
+
на русском, передайте локаль один раз: `app.use(TaoUI, { locale: localeRu })`, а без плагина — `setTaoLocale(localeRu)`.
|
|
333
|
+
Хелперы дат и компоненты дат следуют локали и по умолчанию тоже `en-US`.
|
|
334
|
+
|
|
335
|
+
### Переход с 1.x
|
|
336
|
+
|
|
337
|
+
Смотрите запись 2.0.0 в [CHANGELOG.md](CHANGELOG.md): что сломалось. Старые имена удалены в 5.0.
|
|
338
|
+
|
|
339
|
+
### Использование отдельных компонентов
|
|
340
|
+
|
|
341
|
+
```vue
|
|
342
|
+
<script setup>
|
|
343
|
+
import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
|
|
344
|
+
import '@1337exp/taoui/styles.css'
|
|
345
|
+
</script>
|
|
346
|
+
|
|
347
|
+
<template>
|
|
348
|
+
<TaoButton variant="primary">Нажми меня</TaoButton>
|
|
349
|
+
<TaoFormField label="Введите текст">
|
|
350
|
+
<TaoInput v-model="text" />
|
|
351
|
+
</TaoFormField>
|
|
352
|
+
<TaoModal v-model="isOpen" title="Заголовок">
|
|
353
|
+
Содержимое модального окна
|
|
354
|
+
</TaoModal>
|
|
355
|
+
</template>
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
## Split
|
|
359
|
+
|
|
360
|
+
`TaoSplit` — две панели и полоса между ними. Это не `TaoDivider` (там только линия) и не раскладка на N панелей: три колонки — два вложенных сплита.
|
|
361
|
+
|
|
362
|
+
`direction` как у Flex: `row` (start | end) или `column` (start над end). Слоты `#start` / `#end`.
|
|
363
|
+
|
|
364
|
+
`v-model` — размер панели start. `unit` — `%` (по умолчанию, доля живёт при ресайзе контейнера) или `px` (сайдбар; вторая панель забирает остаток). Для `px` размер нужно задать явно: дефолт `50` — это 50px. `min` / `max` ограничивают start, `min-end` — минимум второй панели, все в той же единице. `resizable="false"` оставляет полосу, но без перетаскивания.
|
|
365
|
+
|
|
366
|
+
Сплит заполняет родителя (`width` / `height: 100%`). Родитель должен ограничить размер по оси сплита: у `column` без высоты не из чего считать `%`. Панели с `min-width` / `min-height: 0` и `overflow: hidden`, чтобы контент не мешал сжатию. Скролл — на внутренней обёртке (`overflow: auto; height: 100%; min-height: 0`). Вложенный `TaoSplit` прямым ребёнком панели растягивается сам.
|
|
367
|
+
|
|
368
|
+
```vue
|
|
369
|
+
<TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
|
|
370
|
+
<template #start>Навигация</template>
|
|
371
|
+
<template #end>Основное</template>
|
|
372
|
+
</TaoSplit>
|
|
373
|
+
```
|
|
374
|
+
|
|
375
|
+
## Toast
|
|
376
|
+
|
|
377
|
+
Вызов — цепочка в одном тике, `setTimeout(0)` отправляет уведомление.
|
|
378
|
+
|
|
379
|
+
```javascript
|
|
380
|
+
import { toast } from '@1337exp/taoui'
|
|
381
|
+
|
|
382
|
+
toast().success().message('Сохранено')
|
|
383
|
+
toast().danger().title('Сеть').timeout(5000).message('Нет соединения')
|
|
384
|
+
toast.success('Сохранено')
|
|
385
|
+
toast.warning('Черновик', { timeout: 1000 })
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
Позиция по умолчанию — `topCenter`. Глобально:
|
|
389
|
+
|
|
390
|
+
```javascript
|
|
391
|
+
toast.defaults({ position: 'bottomRight' })
|
|
392
|
+
toast.byBottomRight()
|
|
393
|
+
```
|
|
394
|
+
|
|
395
|
+
`question` с оверлеем в kit нет — это confirm, не toast. Кнопки в тосте, если нужны:
|
|
396
|
+
|
|
397
|
+
```javascript
|
|
398
|
+
toast().info().message('Удалить файл?').action('Удалить', onRemove)
|
|
399
|
+
```
|
|
400
|
+
|
|
401
|
+
Viewport можно не вставлять: первый вызов сам создаст его. Если нужен явный контроль (тесты, свой layout):
|
|
402
|
+
|
|
403
|
+
```vue
|
|
404
|
+
<TaoToastViewport />
|
|
405
|
+
```
|
|
406
|
+
|
|
407
|
+
## Confirm
|
|
408
|
+
|
|
409
|
+
Вопрос с оверлеем: всплывает по центру и спрашивает. Это не toast — нет прогресс-бара и автозакрытия, есть `await`, Esc и клик по оверлею = отмена.
|
|
410
|
+
|
|
411
|
+
```javascript
|
|
412
|
+
import { confirm } from '@1337exp/taoui'
|
|
413
|
+
|
|
414
|
+
if (await confirm().title('Удалить файл?').message('Это нельзя отменить').danger()) {
|
|
415
|
+
remove()
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
const ok = await confirm('Выйти без сохранения?', {
|
|
419
|
+
ok: 'Выйти',
|
|
420
|
+
cancel: 'Остаться',
|
|
421
|
+
})
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
Очередь: второй `confirm()`, пока открыт первый, подождёт. Подписи по умолчанию — «ОК» / «Отмена»:
|
|
425
|
+
|
|
426
|
+
```javascript
|
|
427
|
+
confirm.defaults({ ok: 'Yes', cancel: 'No' })
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
## Формы
|
|
431
|
+
|
|
432
|
+
`TaoFormField` вешает общий label / hint / error и прокидывает `id` во вложенный контрол.
|
|
433
|
+
|
|
434
|
+
```vue
|
|
435
|
+
<TaoFormField label="Город" hint="Необязательно">
|
|
436
|
+
<TaoSelect v-model="city" :options="cities" />
|
|
437
|
+
</TaoFormField>
|
|
438
|
+
|
|
439
|
+
<TaoSwitch v-model="dark" label="Тёмная тема" />
|
|
440
|
+
|
|
441
|
+
<TaoRadioGroup v-model="plan" legend="Тариф">
|
|
442
|
+
<TaoRadio value="free" label="Free" />
|
|
443
|
+
<TaoRadio value="pro" label="Pro" />
|
|
444
|
+
</TaoRadioGroup>
|
|
445
|
+
|
|
446
|
+
<TaoSegmented v-model="period" legend="Период">
|
|
447
|
+
<TaoSegmentedOption value="week">Неделя</TaoSegmentedOption>
|
|
448
|
+
<TaoSegmentedOption value="month">Месяц</TaoSegmentedOption>
|
|
449
|
+
<TaoSegmentedOption value="year">Год</TaoSegmentedOption>
|
|
450
|
+
</TaoSegmented>
|
|
451
|
+
|
|
452
|
+
<TaoAlert tone="warning" title="Черновик">Сохраните, прежде чем уйти.</TaoAlert>
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
`TaoSegmented` — короткий взаимоисключающий выбор, все варианты видны сразу. Не для навигации по страницам: это `TaoTabs`. Длинные подписи или больше 5–6 пунктов — `TaoRadioGroup` или `TaoSelect`.
|
|
456
|
+
|
|
457
|
+
`TaoSelect` открывается с клавиатуры (стрелки, Enter, Esc), список переворачивается у края экрана. Delete или «Очистить» внизу списка сбрасывает значение в `null`.
|
|
458
|
+
|
|
459
|
+
Если `null` не допустим (шаг сетки, порядок сортировки), передайте `:clearable="false"`: строка сброса и Delete / Backspace пропадут. Подпись строки сброса — `clear-text`, для иконки или своей разметки есть слот `#clear`. `size` — `small` / `medium` / `large` (без него — от предков), масштабирует и раскрытый список.
|
|
460
|
+
|
|
461
|
+
```vue
|
|
462
|
+
<TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
|
|
463
|
+
|
|
464
|
+
<TaoSelect v-model="city" :options="cities">
|
|
465
|
+
<template #clear><TaoIcon name="close" /> Сбросить</template>
|
|
466
|
+
</TaoSelect>
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
`TaoCombobox` — то же меню, но с полем. Печатаете — варианты режутся. `allow-create` пишет введённое в `v-model`, если точного совпадения нет. Список сам не меняется: слушайте `create` и добавьте option снаружи.
|
|
470
|
+
|
|
471
|
+
Подпись, подсказка и текст ошибки всегда идут через `TaoFormField`. `TaoFormField` также оборачивает `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup` и `TaoSegmented` — id, hint и error прокидываются сами.
|
|
472
|
+
|
|
473
|
+
`TaoTag` может быть чипом: `#prefix` слева (обычно `TaoAvatar`), `closable` рисует крестик и эмитит `close`. Клик по крестику наружу не всплывает. `flat` снимает рамку, заливка остаётся.
|
|
474
|
+
|
|
475
|
+
```vue
|
|
476
|
+
<TaoTag tone="neutral" closable @close="remove">
|
|
477
|
+
<template #prefix>
|
|
478
|
+
<TaoAvatar name="Анна Козлова" size="small" />
|
|
479
|
+
</template>
|
|
480
|
+
Анна Козлова
|
|
481
|
+
</TaoTag>
|
|
482
|
+
```
|
|
483
|
+
|
|
484
|
+
## Таблица и пагинация
|
|
485
|
+
|
|
486
|
+
Таблица рендерит то, что передали: сама данные не режет и не сортирует. Это удобно и для серверной выборки, и для клиентской — страница режется снаружи.
|
|
487
|
+
|
|
488
|
+
```vue
|
|
489
|
+
<TaoTable
|
|
490
|
+
:columns="columns"
|
|
491
|
+
:rows="pageRows"
|
|
492
|
+
v-model:sort="sort"
|
|
493
|
+
empty-text="Пока нет записей"
|
|
494
|
+
>
|
|
495
|
+
<template #cell-status="{ row }">
|
|
496
|
+
<TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
|
|
497
|
+
{{ row.status }}
|
|
498
|
+
</TaoTag>
|
|
499
|
+
</template>
|
|
500
|
+
</TaoTable>
|
|
501
|
+
|
|
502
|
+
<TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
|
|
503
|
+
```
|
|
504
|
+
|
|
505
|
+
```javascript
|
|
506
|
+
const columns = [
|
|
507
|
+
{ key: 'name', label: 'Имя', sortable: true },
|
|
508
|
+
{ key: 'city', label: 'Город' },
|
|
509
|
+
{ key: 'status', label: 'Статус' },
|
|
510
|
+
]
|
|
511
|
+
```
|
|
512
|
+
|
|
513
|
+
Слот `cell-<ключ>` перекрывает ячейку. `loading` показывает оверлей, пустой список — текст или слот `#empty`. Клик по шапке с `sortable` крутит `asc → desc → сброс`.
|
|
514
|
+
|
|
515
|
+
## Пустые состояния и загрузка
|
|
516
|
+
|
|
517
|
+
```vue
|
|
518
|
+
<TaoEmpty title="Ничего не нашлось">
|
|
519
|
+
Измените фильтр или сбросьте поиск.
|
|
520
|
+
<template #action>
|
|
521
|
+
<TaoButton variant="secondary">Сбросить</TaoButton>
|
|
522
|
+
</template>
|
|
523
|
+
</TaoEmpty>
|
|
524
|
+
|
|
525
|
+
<TaoSkeleton variant="title" />
|
|
526
|
+
<TaoSkeleton :lines="3" />
|
|
527
|
+
<TaoSkeleton variant="circle" />
|
|
528
|
+
|
|
529
|
+
<TaoStages :items="[
|
|
530
|
+
{ key: 'pay', label: 'Оплата', status: 'ok' },
|
|
531
|
+
{ key: 'pack', label: 'Сборка', status: 'work' },
|
|
532
|
+
{ key: 'ship', label: 'Доставка', status: 'wait' },
|
|
533
|
+
]" />
|
|
534
|
+
|
|
535
|
+
<TaoList>
|
|
536
|
+
<TaoListItem
|
|
537
|
+
title="Анна Козлова"
|
|
538
|
+
description="Дизайн · Москва"
|
|
539
|
+
clickable
|
|
540
|
+
:selected="picked === 'anna'"
|
|
541
|
+
@click="picked = 'anna'"
|
|
542
|
+
>
|
|
543
|
+
<template #prefix>
|
|
544
|
+
<TaoAvatar name="Анна Козлова" size="small" />
|
|
545
|
+
</template>
|
|
546
|
+
</TaoListItem>
|
|
547
|
+
</TaoList>
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
```vue
|
|
551
|
+
<TaoInput v-model="q" placeholder="Найти…">
|
|
552
|
+
<template #prefix>⌕</template>
|
|
553
|
+
</TaoInput>
|
|
554
|
+
|
|
555
|
+
<TaoInputGroup>
|
|
556
|
+
<template #before>https://</template>
|
|
557
|
+
<TaoInput v-model="host" placeholder="example.com" />
|
|
558
|
+
<template #after>
|
|
559
|
+
<TaoButton>Проверить</TaoButton>
|
|
560
|
+
</template>
|
|
561
|
+
</TaoInputGroup>
|
|
562
|
+
|
|
563
|
+
<form @submit.prevent="onSave">
|
|
564
|
+
<TaoFormField label="Email">
|
|
565
|
+
<TaoInput v-model="email" type="email" />
|
|
566
|
+
</TaoFormField>
|
|
567
|
+
<TaoButton type="submit">Сохранить</TaoButton>
|
|
568
|
+
</form>
|
|
569
|
+
|
|
570
|
+
<TaoFormField label="Количество">
|
|
571
|
+
<TaoInputNumber v-model="qty" :min="1" :max="99" />
|
|
572
|
+
</TaoFormField>
|
|
573
|
+
|
|
574
|
+
<TaoQuantity v-model="qty" :max="12" @dec="onDec" />
|
|
575
|
+
|
|
576
|
+
<TaoFormField label="День доставки" hint="В модели всегда YYYY-MM-DD">
|
|
577
|
+
<TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
|
|
578
|
+
</TaoFormField>
|
|
579
|
+
|
|
580
|
+
<TaoFormField label="Даты поездки">
|
|
581
|
+
<TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
|
|
582
|
+
</TaoFormField>
|
|
583
|
+
|
|
584
|
+
<TaoCounter :value="score" :max-digits="6" />
|
|
585
|
+
|
|
586
|
+
<TaoCarousel :autoplay="4000" loop indicator="bars">
|
|
587
|
+
<article v-for="item in banners" :key="item.id" class="hero">
|
|
588
|
+
<strong>{{ item.title }}</strong>
|
|
589
|
+
<span>{{ item.text }}</span>
|
|
590
|
+
</article>
|
|
591
|
+
</TaoCarousel>
|
|
592
|
+
<TaoCarousel :peek="72" :controls="false" indicator="dots">…</TaoCarousel>
|
|
593
|
+
<TaoCarousel v-model="slide" :per-view="5" :peek="28">
|
|
594
|
+
<template #prev></template>
|
|
595
|
+
<template #next="{ go, disabled }">
|
|
596
|
+
<button type="button" :disabled="disabled" @click="go">вперёд</button>
|
|
597
|
+
</template>
|
|
598
|
+
<article v-for="item in products" :key="item.id">…</article>
|
|
599
|
+
</TaoCarousel>
|
|
600
|
+
```
|
|
601
|
+
|
|
602
|
+
`TaoDrawer` — лист сбоку, не модалка по центру:
|
|
603
|
+
|
|
604
|
+
```vue
|
|
605
|
+
<TaoDrawer v-model="open" title="Фильтры">
|
|
606
|
+
...
|
|
607
|
+
</TaoDrawer>
|
|
608
|
+
```
|
|
609
|
+
|
|
610
|
+
## Дизайн-токены и темизация
|
|
611
|
+
|
|
612
|
+
Стили библиотеки построены слоями. Компоненты **никогда** не обращаются к цветам/размерам
|
|
613
|
+
напрямую: они читают семантические роли и контексты на них (размер, тон, поверхность).
|
|
614
|
+
Это и есть механизм темизации: переопределяете 20-30 переменных — меняется
|
|
615
|
+
внешний вид всех компонентов сразу, без правок самих компонентов.
|
|
616
|
+
|
|
617
|
+
```
|
|
618
|
+
tokens/primitives.css → tokens/semantic.css → themes/*.css → contexts/*.css → base.css
|
|
619
|
+
сырые цвета, шкалы скругления, тени, цветовые роли классы размера, сброс
|
|
620
|
+
не трогать шрифт, движение каждой темы тона, поверхности
|
|
621
|
+
```
|
|
622
|
+
|
|
623
|
+
### Слои
|
|
624
|
+
|
|
625
|
+
| Файл (в `src/styles/`) | Назначение | Трогать? |
|
|
626
|
+
|---|---|---|
|
|
627
|
+
| `tokens/primitives.css` | Сырая палитра, шкалы отступов/радиусов/теней (`--tao-orange-400`, `--tao-space-3`...) | Обычно нет |
|
|
628
|
+
| `tokens/semantic.css` | Роли, не зависящие от темы: скругления, тени, шрифт, движение | Редко |
|
|
629
|
+
| `themes/dark.css` | Цветовые роли темы по умолчанию (dark): `--tao-color-accent`, `--tao-color-surface`, ... | **Да — это и есть API темизации** |
|
|
630
|
+
| `themes/light.css` | Те же роли под `[data-tao-theme="light"]` | Да, как образец |
|
|
631
|
+
| `contexts/size.css`, `tone.css`, `surface.css` | `.tao-size-*` и `.tao-density-*`, `.tao-tone-*`, `.tao-surface-*`: что контрол читает, чтобы знать размер, цвет и материал | Редко |
|
|
632
|
+
| `base.css` | Глобальный reset (скроллбар, ссылки, box-sizing) | Редко |
|
|
633
|
+
|
|
634
|
+
Всё подключается одним файлом `@1337exp/taoui/styles.css` (и dark, и light: light включается атрибутом `data-tao-theme="light"`).
|
|
635
|
+
Сырые файлы доступны как `@1337exp/taoui/styles/tokens/primitives.css` и так далее.
|
|
636
|
+
|
|
637
|
+
### Как сделать свою тему
|
|
638
|
+
|
|
639
|
+
Тема — это просто переопределение семантических токенов под своим селектором.
|
|
640
|
+
Ничего в компонентах менять не нужно:
|
|
641
|
+
|
|
642
|
+
```css
|
|
643
|
+
/* my-brand-theme.css */
|
|
644
|
+
[data-tao-theme="my-brand"] {
|
|
645
|
+
--tao-color-accent: #6c5ce7;
|
|
646
|
+
--tao-color-accent-hover: #5a4bd1;
|
|
647
|
+
--tao-color-bg: #0f0f1a;
|
|
648
|
+
--tao-color-surface: #0f0f1a;
|
|
649
|
+
--tao-color-surface-raised: #1a1a2e;
|
|
650
|
+
--tao-color-text: #d6d6e8;
|
|
651
|
+
--tao-color-text-strong: #ffffff;
|
|
652
|
+
/* остальные роли см. themes/dark.css */
|
|
653
|
+
}
|
|
654
|
+
```
|
|
655
|
+
|
|
656
|
+
```vue
|
|
657
|
+
<!-- app.vue -->
|
|
658
|
+
<template>
|
|
659
|
+
<div data-tao-theme="my-brand">
|
|
660
|
+
<NuxtPage />
|
|
661
|
+
</div>
|
|
662
|
+
</template>
|
|
663
|
+
```
|
|
664
|
+
|
|
665
|
+
Или переключайте тему целиком на `<html>`, чтобы стилизовать модалки/тултипы,
|
|
666
|
+
которые телепортируются в `body`:
|
|
667
|
+
|
|
668
|
+
```javascript
|
|
669
|
+
document.documentElement.setAttribute('data-tao-theme', 'light')
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
### Ключевые группы токенов
|
|
673
|
+
|
|
674
|
+
- `--tao-color-accent*` — акцентный/брендовый цвет (кнопки primary, активные вкладки, ссылки)
|
|
675
|
+
- `--tao-color-on-accent` — текст на акцентном фоне
|
|
676
|
+
- `--tao-color-selection`, `--tao-color-selection-text` — выделение текста (`::selection`)
|
|
677
|
+
- `--tao-color-surface*` — фоны контейнеров (обычный / приподнятый / утопленный / hover)
|
|
678
|
+
- `--tao-color-border*` — границы
|
|
679
|
+
- `--tao-color-text*` — текст (обычный / усиленный / subtle / приглушённый / disabled)
|
|
680
|
+
- `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — статусные цвета
|
|
681
|
+
- `--tao-color-input-*` — поля ввода отдельно, т.к. фон/текст полей часто не совпадают с surface/text
|
|
682
|
+
- `--tao-radius-control`, `--tao-radius-panel` — скругления (мелкие контролы vs крупные панели)
|
|
683
|
+
- `--tao-shadow-panel`, `--tao-shadow-overlay` — тени
|
|
684
|
+
- `--tao-font-size-*` — шкала кегля в `primitives.css`: `xs`–`xl` контролы, `2xl`–`4xl` заголовки / проза
|
|
685
|
+
- `--tao-control-height-*` (26 / 36 / 44px), `--tao-control-padding-x-*`, `--tao-control-padding-y-*`, `--tao-control-font-size-*`, `--tao-control-font-size-secondary-*`, `--tao-button-padding-x-*`, `--tao-indicator-size-*`, `--tao-tag-height-*` / `-padding-x-*` / `-font-size-*` — шкала размеров в `primitives.css`. Компоненты читают текущие значения из `contexts/size.css`: `--tao-control-height`, `--tao-control-padding-x` / `-y`, `--tao-control-font-size`, `--tao-control-font-size-secondary`, `--tao-button-padding-x`, `--tao-indicator-size`, `--tao-tag-height` / `-padding-x` / `-font-size`. Используйте их в своих контролах, чтобы попасть в размер окружения.
|
|
686
|
+
|
|
687
|
+
Полный список цветовых ролей — в `src/styles/themes/dark.css`, это файл,
|
|
688
|
+
который стоит открыть, чтобы понять весь доступный API темизации.
|
|
689
|
+
|
|
690
|
+
### Палитры
|
|
691
|
+
|
|
692
|
+
Палитра — это четыре цвета от самого тёмного к самому светлому: из них получается целый набор ролей для тёмного и светлого режимов.
|
|
693
|
+
Готовы семь (`sunset`, `marple`, `violet-dusk`, `ocean-blue`, `pinheiro`, `tokyo-night`, `lagoon`; список — `taoPalettes`).
|
|
694
|
+
|
|
695
|
+
```javascript
|
|
696
|
+
import '@1337exp/taoui/styles.css'
|
|
697
|
+
import '@1337exp/taoui/palettes.css' // все сразу, или '@1337exp/taoui/styles/palettes/sunset.css' для одной
|
|
698
|
+
```
|
|
699
|
+
|
|
700
|
+
```html
|
|
701
|
+
<html data-tao-theme="sunset"> <!-- тёмная -->
|
|
702
|
+
<html data-tao-theme="sunset" data-tao-mode="light"> <!-- её светлая версия -->
|
|
703
|
+
```
|
|
704
|
+
|
|
705
|
+
`data-tao-mode="light" | "dark"` работает и сам по себе, с цветами по умолчанию; `data-tao-theme="light"` — старая запись того же.
|
|
706
|
+
Ставьте на `<html>` (чтобы модалки и тултипы, вынесенные в `body`, следовали) или на любой элемент для части страницы.
|
|
707
|
+
|
|
708
|
+
Что палитра решает за вас:
|
|
709
|
+
|
|
710
|
+
- **Акцент** — стоп, чья яркость подходит режиму (укажите `accent: 1`, если автоматический выбор не тот), сдвинутый только по яркости, пока он виден на странице (3:1), несёт читаемый текст (4.5:1) и сам читается как текст (`--tao-color-accent-text`, 4.5:1).
|
|
711
|
+
- **Страница и поверхности** — очень тёмный (или очень светлый) оттенок самого глубокого цвета палитры.
|
|
712
|
+
- **Статусы** (`danger`, `warning`, `success`, `info`) остаются в своём узнаваемом секторе оттенка, но делят с палитрой яркость и насыщенность, а статус, который спутали бы с акцентом, отодвигается (палитра может назвать свой цвет: `status: { success: '#7fbf2f' }`). У каждого статуса 4.5:1 для текста, как заливка и как текст.
|
|
713
|
+
- **`--tao-color-accent-2`, `--tao-glow`, `--tao-gradient`, `--tao-bg-atmosphere`:** второй акцент, цвет свечения, градиент через четыре стопа и мягкое свечение за страницей (рисует `class="tao-atmosphere"` на `<body>` или корне приложения; статичный слой, без blur).
|
|
714
|
+
|
|
715
|
+
Контраст — не обещание в README: `tests/palette.test.ts` держит каждую палитру в обоих режимах на этих числах.
|
|
716
|
+
|
|
717
|
+
Своя палитра в рантайме (редактор тем, цвет, выбранный пользователем):
|
|
718
|
+
|
|
719
|
+
```javascript
|
|
720
|
+
import { applyTaoPalette } from '@1337exp/taoui'
|
|
721
|
+
|
|
722
|
+
const stop = applyTaoPalette({ name: 'mine', label: 'Mine', stops: ['#102030', '#306090', '#60c0f0', '#e0f4ff'] }, 'dark')
|
|
723
|
+
stop() // снимает её; третий аргумент кладёт палитру на один элемент вместо страницы
|
|
724
|
+
```
|
|
725
|
+
|
|
726
|
+
или файлом: `taoPaletteCss(def)` возвращает CSS, из которого сделаны файлы пресетов. Чтобы добавить пресет в библиотеку, допишите его в `src/palettes.ts` и запустите `npm run palettes`.
|
|
727
|
+
|
|
728
|
+
#### Контраст: WCAG 2 и APCA
|
|
729
|
+
|
|
730
|
+
У каждой пары цветов два вопроса, и на них отвечают две разные модели.
|
|
731
|
+
|
|
732
|
+
**Допустимо ли?** Контраст WCAG 2: `(L1 + 0.05) / (L2 + 0.05)` от относительных яркостей, от 1 до 21. Это действующий
|
|
733
|
+
стандарт (его проверяют аудиты доступности), поэтому все числа, которые обещают палитры, — по WCAG 2: 4.5:1 для текста,
|
|
734
|
+
3:1 для заливки, видимой на странице. Считает `contrastRatio(a, b)`.
|
|
735
|
+
|
|
736
|
+
**Что читается лучше?** У WCAG 2 известное слепое пятно: светлое и тёмное для неё симметричны, и на цветах средней
|
|
737
|
+
яркости она переоценивает чёрный. На зелёном `#2ea85c` она говорит «чёрный 6.4:1 против белого 3.1:1», хотя глаз явно
|
|
738
|
+
лучше читает белый. APCA (Accessible Perceptual Contrast Algorithm, модель черновика WCAG 3) следует тому, как мы видим:
|
|
739
|
+
светлый текст на тёмном и тёмный на светлом не симметричны, тонкому тексту нужно больше. Она даёт контраст яркости
|
|
740
|
+
**Lc** примерно от −108 до 106 (знак — полярность: минус — светлый текст на тёмном); около 75 — основной текст, 60 —
|
|
741
|
+
подпись, 45 — крупный заголовок. Считает `apcaContrast(text, background)`.
|
|
742
|
+
|
|
743
|
+
| На `#2ea85c` | WCAG 2 | APCA Lc |
|
|
744
|
+
|---|---|---|
|
|
745
|
+
| чёрный текст | **6.4 : 1** | 47 |
|
|
746
|
+
| белый текст | 3.1 : 1 | **62** |
|
|
747
|
+
|
|
748
|
+
Поэтому палитры берут обе модели, каждую для своего:
|
|
749
|
+
|
|
750
|
+
1. **Полярность по APCA.** В светлом режиме подпись на заливке (акцент, статус) — тот цвет, который APCA читает лучше;
|
|
751
|
+
на средних тонах это белый.
|
|
752
|
+
2. **Числа по WCAG 2.** Потом заливка сдвигается по яркости, пока подпись не наберёт 4.5:1: белая подпись на среднем
|
|
753
|
+
тоне получает чуть более глубокую заливку, а не слабую подпись.
|
|
754
|
+
3. **В тёмном режиме подпись тёмная.** Там заливки светлые нарочно (чтобы их было видно на тёмной странице), а на
|
|
755
|
+
светлой заливке тёмный текст лучше в обеих моделях.
|
|
756
|
+
|
|
757
|
+
Проверки — в `tests/palette.test.ts`: каждая палитра, оба режима, каждая заливка. Если подбираете свои цвета, обе функции
|
|
758
|
+
экспортированы — пользуйтесь так же: APCA, чтобы выбрать, WCAG 2, чтобы обещать.
|
|
759
|
+
|
|
760
|
+
### Если нужна тема с нуля, без primitives
|
|
761
|
+
|
|
762
|
+
```javascript
|
|
763
|
+
import '@1337exp/taoui/styles/tokens/primitives.css' // шкалы можно оставить
|
|
764
|
+
import '@1337exp/taoui/styles/tokens/semantic.css' // скругления, тени, шрифт, движение
|
|
765
|
+
import './my-colour-roles.css' // ваши цветовые роли вместо themes/dark.css
|
|
766
|
+
import '@1337exp/taoui/styles/contexts/size.css' // контексты, которые читают компоненты
|
|
767
|
+
import '@1337exp/taoui/styles/contexts/tone.css'
|
|
768
|
+
import '@1337exp/taoui/styles/contexts/surface.css'
|
|
769
|
+
import '@1337exp/taoui/styles/base.css'
|
|
770
|
+
```
|
|
771
|
+
|
|
772
|
+
## Демонстрация
|
|
773
|
+
|
|
774
|
+
Все компоненты с живыми примерами, таблицами пропсов и готовыми сниппетами. Язык (EN / RU) и тема (dark / light) переключаются в шапке.
|
|
775
|
+
|
|
776
|
+
```bash
|
|
777
|
+
cd showcase
|
|
778
|
+
npm install
|
|
779
|
+
npm run dev # или из корня репозитория: npm run showcase
|
|
780
|
+
```
|
|
781
|
+
|
|
782
|
+
Showcase смотрит прямо в `src/`, поэтому правки компонентов видны без
|
|
783
|
+
`npm run build`. `npm run showcase:build` собирает статический сайт с относительными
|
|
784
|
+
путями — его можно положить в любую папку (например, `/sandbox/taoui/`).
|
|
785
|
+
|
|
786
|
+
Скриншоты и ролики в этом README сняты с showcase: см. [docs/media](docs/media/README.md).
|
|
787
|
+
|
|
788
|
+
## Разработка
|
|
789
|
+
|
|
790
|
+
```bash
|
|
791
|
+
# Сборка библиотеки
|
|
792
|
+
npm run build
|
|
793
|
+
|
|
794
|
+
# Режим разработки (watch)
|
|
795
|
+
npm run dev
|
|
796
|
+
|
|
797
|
+
# Проверка типов
|
|
798
|
+
npm run type-check
|
|
799
|
+
|
|
800
|
+
# Тесты (Vitest)
|
|
801
|
+
npm test
|
|
802
|
+
```
|
|
803
|
+
|
|
804
|
+
## Публикация в npm
|
|
805
|
+
|
|
806
|
+
Публикуется только `dist/` (собранная библиотека) и `src/styles/` (сырые
|
|
807
|
+
токены — чтобы можно было подключить `tokens/primitives.css` отдельно при
|
|
808
|
+
кастомной теме), плюс `README.md`, `LICENSE`, `CHANGELOG.md` и `MIGRATION-5.md`. Исходники компонентов (`src/components/*.vue`),
|
|
809
|
+
конфиги сборки и `showcase/` в пакет не попадают — они остаются в
|
|
810
|
+
репозитории; чтобы их получить, репозиторий клонируют.
|
|
811
|
+
|
|
812
|
+
`npm publish` **сам** прогоняет проверку типов, тесты и полную пересборку перед
|
|
813
|
+
публикацией (хук `prepublishOnly` в `package.json`) — так в реестр не
|
|
814
|
+
уедет пакет со старым или отсутствующим `dist/`. Собирать вручную перед
|
|
815
|
+
`npm publish` не нужно.
|
|
816
|
+
|
|
817
|
+
Проверить, что именно попадёт в пакет, без реальной публикации:
|
|
818
|
+
|
|
819
|
+
```bash
|
|
820
|
+
npm pack --dry-run
|
|
821
|
+
```
|
|
822
|
+
|
|
823
|
+
Токен публикации не должен лежать в репозитории: в `.npmrc` ссылайтесь на него как
|
|
824
|
+
`//registry.npmjs.org/:_authToken=${NPM_TOKEN}` и задайте `NPM_TOKEN` в окружении.
|
|
825
|
+
`.npmrc` в любом случае в `.gitignore`.
|
|
826
|
+
|
|
827
|
+
## Участие в проекте
|
|
828
|
+
|
|
829
|
+
Issues и pull request'ы приветствуются — см. [CONTRIBUTING.md](CONTRIBUTING.md).
|
|
830
|
+
Об уязвимостях: [SECURITY.md](SECURITY.md).
|
|
831
|
+
|
|
832
|
+
## Лицензия
|
|
833
|
+
|
|
834
|
+
[MIT](LICENSE) © 2026 1337exp
|