@1337exp/taoui 1.13.0 → 2.0.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/README.ru.md CHANGED
@@ -1,561 +1,621 @@
1
- # Tao UI
2
-
3
- [English](README.md) · **Русский**
4
-
5
- Библиотека Vue 3 компонентов для Nuxt/Vue проектов с системой дизайн-токенов:
6
- поменял несколько CSS-переменных — поменялась тема всего набора компонентов.
7
-
8
- ## Компоненты
9
-
10
- ### Базовые
11
-
12
- - **TaoBlock** — базовый контейнер с настраиваемыми отступами и скруглением
13
- - **TaoButton** — кнопка: `primary` / `secondary` / `ghost` / `text` / `danger`. `tone` красит ghost и text (danger, success, warning, info)
14
- - **TaoCard** — карточка со слотами cover / header / footer. В `#cover` — фото или `TaoCarousel`. `flush` — плитка без padding/тени на всю ячейку; `#overlay` — scrim на обложке
15
- - **TaoCopy** — иконка копирования в буфер. После клика сверху тултип «Скопировано»; если кнопку убрали — тултип тоже
16
- - **TaoInput** — поле ввода с поддержкой v-model, валидации и слотов `#prefix` / `#suffix` (иконка или текст внутри рамки)
17
- - **TaoInputGroup** — склейка снаружи: `#before` | поле | `#after` (протокол, единица, кнопка)
18
- - **TaoModal** — модальное окно с анимацией и слотами
19
- - **TaoDrawer** — боковая панель (фильтры, настройки). Esc, клик по фону, ловушка фокуса — как у модалки
20
- - **TaoSpoiler** — раскрывающийся блок. `v-model` и `aria-expanded`. Несколько подряд сами друг друга не закрывают
21
- - **TaoSpoilerGroup** — аккордеон: `v-model` — ключ открытой панели (`null` — все закрыты), у спойлера `name`. Без `v-model` группа помнит ключ сама
22
- - **TaoTabs** — вкладки для переключения между секциями контента
23
- - **TaoTooltip** — всплывающая подсказка при наведении. `top` / `bottom` / `left` / `right`, у края экрана переворачивается
24
- - **TaoPopover** — панель по клику: слот с любым контентом, Esc и клик снаружи. Не тултип и не меню действий
25
-
26
- ### Layout
27
-
28
- - **TaoContainer** — контейнер с ограничением ширины (wide/slim/ultra-slim) и авто-центровкой
29
- - **TaoFlex** — обёртка над flexbox с пропами justify/align/direction/wrap/gap
30
- - **TaoSpace** — авто-расстановка дочерних элементов с равномерным gap
31
- - **TaoGrid** / **TaoGridItem** — плитки: `min` — каталог (auto-fill), `cols` — bento. У item `col` / `row`; уже ~560px span сбрасывается. Не masonry
32
- - **TaoDivider** — `solid` (обычный border) / `dashed` / `colored` (акцент) / `gap`. Подпись — опциональный `text` на любом варианте; `fade` — плавные края линии; `size` только у `gap` (small / medium / large)
33
- - **TaoSplit** — две панели и полоса. `row` / `column` как у Flex. `v-model` — размер start в `%` или `px`; `resizable="false"` фиксирует полосу. Не Divider.
34
- - **TaoFieldset** — рамка-группа: `legend` сидит на верхней границе, `align` — start / center / end
35
- - **TaoAnimatedBorder** — контейнер с анимированной радужной рамкой (декоративный, не завязан на тему)
36
-
37
- ### Формы и ввод
38
-
39
- - **TaoCheckbox** — чекбокс с v-model, слотами pre/post и `indeterminate` (частично выбран)
40
- - **TaoSwitch** — переключатель для булевых настроек (`role="switch"`)
41
- - **TaoRadio** / **TaoRadioGroup** — классические радиокнопки: длинные подписи, можно столбиком
42
- - **TaoSegmented** / **TaoSegmentedOption** — компактный выбор из 2–5 коротких вариантов. Не вкладки
43
- - **TaoSelect** — выпадающий список с клавиатурой, тот же визуал, что у Input. `size` (`small` / `medium` / `large`, та же шкала, что у Button). Сброс — «Очистить» в списке или Delete; `clearable="false"` отключает сброс, слот `#clear` заменяет содержимое строки
44
- - **TaoCombobox** — Select с полем: фильтр по вводу, `allow-create` пишет своё в `v-model`, `create` — чтобы родитель дополнил список. Те же `size`, `clearable` и `#clear`, что у `TaoSelect`
45
- - **TaoDate** — один день: `YYYY-MM-DD`, без часов и пояса. Календарь как у Select
46
- - **TaoDateRange** — период: `v-model` — `{ start, end }` или `null`. Первый клик — начало, второй — конец (если конец раньше — меняются местами). Неполный выбор в модель не пишется
47
- - **TaoFormField** — общие label / hint / error для полей формы
48
- - **TaoInputNumber** — число с min/max/step и кнопками ± справа. Пустое значение — `null`. `@commit` срабатывает один раз, когда правка закончена (blur, Enter, ±, стрелка), в отличие от `v-model`, который обновляется на каждую клавишу
49
- - **TaoQuantity** — количество в корзине: `− | поле | +`, целые штуки, сток, минус на минимуме может убрать строку
50
- - **TaoTextarea** — многострочное поле с авто-высотой. `maxlength` ограничивает ввод, `count` показывает «введено / максимум»
51
- - **TaoPinCode** — пин-код из N полей. По умолчанию клик стирает ячейку и все справа (`clear-on="focus"`); `clear-on="input"` заменяет цифру только при вводе. Последняя ячейка снимает фокус и эмитит `complete`
52
- - **TaoSlider** — слайдер: мышь, тач и стрелки. Опциональный точный ввод по правому клику. `size="small"` — тонкий трек для seek / громкости
53
- - **TaoFileDrop** — зона загрузки (drag & drop + клик). Список имён под зоной, `v-model` — `File[]`. Очистку всей пачки решает родитель (`clear-request`)
54
-
55
- ### Отображение данных
56
-
57
- - **TaoTable** — простая таблица: колонки, empty, loading, сортировка через `v-model:sort`. `head` — подсветка шапки, `lines` — линии между рядами (оба по умолчанию включены). `striped` — зебра с первой строки, `striped="even"` — со второй. Не datagrid.
58
- - **TaoPagination** — страницы с многоточием. Клик по «…» прыгает на `jump` страниц (5 по умолчанию)
59
- - **TaoEmpty** — пустой список, нет результатов, нет прав
60
- - **TaoList** / **TaoListItem** — строка списка: иконка, заголовок, подпись, действие по ховеру. Не Select и не таблица
61
- - **TaoStages** — список стадий: `wait` / `work` / `ok` / `bad`. Не линейный степпер
62
- - **TaoSkeleton** — плейсхолдер загрузки (text / title / circle / rect)
63
- - **TaoCounter** — витрина числа с переворотом цифр (не инпут)
64
- - **TaoCarousel** — лента: целый слайд с `autoplay`, карточка с `peek`, полоса с `per-view`. Стрелки через `controls` или `#prev` / `#next`, точки — `dots`
65
- - **TaoAvatar** — фото или инициалы, размеры `small` / `medium` / `large`. Точка `dot` и счётчик `count`
66
- - **TaoTag** — тег/бейдж со статусами. `#prefix` (аватар), `closable` убирает чип, `flat` — без рамки
67
- - **TaoAlert** — инлайн-баннер страницы или ошибки формы (success / error / warning / info)
68
- - **TaoProgress** — статичная полоса (`progress` в %). Проценты сверху по центру или `showPercentage="right"` справа; слоты `#left` / `#right` — подписи, тогда процент справа в скобках. `false` прячет. Ширина — `minWidth` / `maxWidth`, не диапазон значения
69
- - **TaoLoader** — анимированный лоадер (четыре точки)
70
- - **TaoImage** — обёртка над `<img>`: fade-in и плейсхолдер. `lazy` включает нативный `loading="lazy"`
71
- - **TaoIcon** — обёртка для icon-шрифта (см. раздел «Иконки» ниже)
72
-
73
- ### Навигация и взаимодействие
74
-
75
- - **TaoLink** — `<NuxtLink>` в Nuxt, `<RouterLink>` при vue-router, иначе обычный `<a>` — без дополнительной настройки
76
- - **TaoBreadcrumb** — крошки: последний пункт — текущая страница
77
- - **TaoDropdownMenu** — выпадающее меню с авто-позиционированием у края экрана
78
- - **TaoScrollTop** — плавающая кнопка «наверх» с ripple. Появляется при обратном скролле после `boundary`
79
-
80
- ### Обратная связь
81
-
82
- - **toast()** — fluent-уведомления: `toast().success().message('Сохранено')`
83
- - **confirm()** — вопрос с оверлеем: тот же fluent + `await`. Не тост — ждёт ответ, не исчезает сам.
84
- - **TaoToastViewport** / **TaoConfirmHost** — контейнеры; если их нет в разметке, первый вызов сам монтирует их в `body`
85
-
86
- ## Соглашения
87
-
88
- Тоны визуала: `success` | `danger` | `warning` | `info` | `neutral`.
89
- `error` у Alert, Tag и `toast()` — синоним `danger`. Button уже `danger`.
90
- Stages — это процесс, не тон: `wait` / `work` / `ok` / `bad` (`danger` принимается как `bad`).
91
-
92
- Размеры контролов: `small` | `medium` | `large`.
93
- Avatar понимает и короткие `s` / `m` / `l`. Divider `gap` раньше называл крупный размер `big` — это алиас `large`.
94
- Container живёт на другой оси: `wide` / `slim` / `ultra-slim`.
95
-
96
- Шкала кегля (примитивы): `xs` 12 … `xl` 18 для контролов; `2xl` 24, `3xl` 32, `4xl` 36 для заголовков и прозы.
97
- Отдельного компонента заголовка нет — `h1 { font-size: var(--tao-font-size-3xl) }`.
98
-
99
- ## Иконки
100
-
101
- `TaoIcon` не поставляет собственный набор иконок — он рендерит класс `icon-<name>`
102
- по соглашению, рассчитанному на подключение внешнего icon-шрифта (например,
103
- собранного через IcoMoon/Fontello). Чтобы иконки отображались, подключите
104
- свой шрифт с классами вида `.icon-arrow-up { ... }` в проекте.
105
-
106
- ## Установка
107
-
108
- ```bash
109
- npm install @1337exp/taoui
110
- ```
111
-
112
- Или локально из папки:
113
-
114
- ```bash
115
- npm install ../path-to-tao-ui
116
- ```
117
-
118
- ## Использование
119
-
120
- ### Подключение в Nuxt 3
121
-
122
- Создайте плагин `plugins/tao-ui.ts`:
123
-
124
- ```typescript
125
- import { defineNuxtPlugin } from '#app'
126
- import TaoUI from '@1337exp/taoui'
127
-
128
- export default defineNuxtPlugin((nuxtApp) => {
129
- nuxtApp.vueApp.use(TaoUI)
130
- })
131
- ```
132
-
133
- Импортируйте стили в `app.vue` или layout:
134
-
135
- ```vue
136
- <script setup>
137
- import '@1337exp/taoui/styles.css'
138
- </script>
139
- ```
140
-
141
- ### Подключение в Vue 3 проекте
142
-
143
- ```javascript
144
- // main.js
145
- import { createApp } from 'vue'
146
- import App from './App.vue'
147
- import TaoUI from '@1337exp/taoui'
148
- import '@1337exp/taoui/styles.css'
149
-
150
- const app = createApp(App)
151
- app.use(TaoUI)
152
- app.mount('#app')
153
- ```
154
-
155
- ### Использование отдельных компонентов
156
-
157
- ```vue
158
- <script setup>
159
- import { TaoButton, TaoInput, TaoModal } from '@1337exp/taoui'
160
- import '@1337exp/taoui/styles.css'
161
- </script>
162
-
163
- <template>
164
- <TaoButton variant="primary">Нажми меня</TaoButton>
165
- <TaoInput v-model="text" label="Введите текст" />
166
- <TaoModal v-model="isOpen" title="Заголовок">
167
- Содержимое модального окна
168
- </TaoModal>
169
- </template>
170
- ```
171
-
172
- ## Split
173
-
174
- `TaoSplit` — две панели и полоса между ними. Это не `TaoDivider` (там только линия) и не раскладка на N панелей: три колонки — два вложенных сплита.
175
-
176
- `direction` как у Flex: `row` (start | end) или `column` (start над end). Слоты `#start` / `#end`.
177
-
178
- `v-model` — размер панели start. `unit` — `%` (по умолчанию, доля живёт при ресайзе контейнера) или `px` (сайдбар; вторая панель забирает остаток). Для `px` размер нужно задать явно: дефолт `50` — это 50px. `min` / `max` ограничивают start, `min-end` — минимум второй панели, все в той же единице. `resizable="false"` оставляет полосу, но без перетаскивания.
179
-
180
- Сплит заполняет родителя (`width` / `height: 100%`). Родитель должен ограничить размер по оси сплита: у `column` без высоты не из чего считать `%`. Панели с `min-width` / `min-height: 0` и `overflow: hidden`, чтобы контент не мешал сжатию. Скролл — на внутренней обёртке (`overflow: auto; height: 100%; min-height: 0`). Вложенный `TaoSplit` прямым ребёнком панели растягивается сам.
181
-
182
- ```vue
183
- <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
184
- <template #start>Навигация</template>
185
- <template #end>Основное</template>
186
- </TaoSplit>
187
- ```
188
-
189
- ## Toast
190
-
191
- Вызов — цепочка в одном тике, `setTimeout(0)` отправляет уведомление.
192
-
193
- ```javascript
194
- import { toast } from '@1337exp/taoui'
195
-
196
- toast().success().message('Сохранено')
197
- toast().error().title('Сеть').timeout(5000).message('Нет соединения')
198
- toast.success('Сохранено')
199
- toast.warning('Черновик', { timeout: 1000 })
200
- ```
201
-
202
- Позиция по умолчанию — `topCenter`. Глобально:
203
-
204
- ```javascript
205
- toast.defaults({ position: 'bottomRight' })
206
- toast.byBottomRight()
207
- ```
208
-
209
- `question` с оверлеем в kit нет — это confirm, не toast. Кнопки в тосте, если нужны:
210
-
211
- ```javascript
212
- toast().info().message('Удалить файл?').action('Удалить', onRemove)
213
- ```
214
-
215
- Viewport можно не вставлять: первый вызов сам создаст его. Если нужен явный контроль (тесты, свой layout):
216
-
217
- ```vue
218
- <TaoToastViewport />
219
- ```
220
-
221
- ## Confirm
222
-
223
- Вопрос с оверлеем: всплывает по центру и спрашивает. Это не toast — нет прогресс-бара и автозакрытия, есть `await`, Esc и клик по оверлею = отмена.
224
-
225
- ```javascript
226
- import { confirm } from '@1337exp/taoui'
227
-
228
- if (await confirm().title('Удалить файл?').message('Это нельзя отменить').danger()) {
229
- remove()
230
- }
231
-
232
- const ok = await confirm('Выйти без сохранения?', {
233
- ok: 'Выйти',
234
- cancel: 'Остаться',
235
- })
236
- ```
237
-
238
- Очередь: второй `confirm()`, пока открыт первый, подождёт. Подписи по умолчанию — «ОК» / «Отмена»:
239
-
240
- ```javascript
241
- confirm.defaults({ ok: 'Yes', cancel: 'No' })
242
- ```
243
-
244
- ## Формы
245
-
246
- `TaoFormField` вешает общий label / hint / error и прокидывает `id` во вложенный контрол.
247
-
248
- ```vue
249
- <TaoFormField label="Город" hint="Необязательно">
250
- <TaoSelect v-model="city" :options="cities" />
251
- </TaoFormField>
252
-
253
- <TaoSwitch v-model="dark" label="Тёмная тема" />
254
-
255
- <TaoRadioGroup v-model="plan" legend="Тариф">
256
- <TaoRadio value="free" label="Free" />
257
- <TaoRadio value="pro" label="Pro" />
258
- </TaoRadioGroup>
259
-
260
- <TaoSegmented v-model="period" legend="Период">
261
- <TaoSegmentedOption value="week">Неделя</TaoSegmentedOption>
262
- <TaoSegmentedOption value="month">Месяц</TaoSegmentedOption>
263
- <TaoSegmentedOption value="year">Год</TaoSegmentedOption>
264
- </TaoSegmented>
265
-
266
- <TaoAlert type="warning" title="Черновик">Сохраните, прежде чем уйти.</TaoAlert>
267
- ```
268
-
269
- `TaoSegmented` — короткий взаимоисключающий выбор, все варианты видны сразу. Не для навигации по страницам: это `TaoTabs`. Длинные подписи или больше 5–6 пунктов — `TaoRadioGroup` или `TaoSelect`.
270
-
271
- `TaoSelect` открывается с клавиатуры (стрелки, Enter, Esc), список переворачивается у края экрана. Delete или «Очистить» внизу списка сбрасывает значение в `null`.
272
-
273
- Если `null` не допустим (шаг сетки, порядок сортировки), передайте `:clearable="false"`: строка сброса и Delete / Backspace пропадут. Подпись строки сброса — `clear-text`, для иконки или своей разметки есть слот `#clear`. `size` — `small` / `medium` (по умолчанию) / `large`, масштабирует и раскрытый список.
274
-
275
- ```vue
276
- <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
277
-
278
- <TaoSelect v-model="city" :options="cities">
279
- <template #clear><TaoIcon name="close" /> Сбросить</template>
280
- </TaoSelect>
281
- ```
282
-
283
- `TaoCombobox` — то же меню, но с полем. Печатаете — варианты режутся. `allow-create` пишет введённое в `v-model`, если точного совпадения нет. Список сам не меняется: слушайте `create` и добавьте option снаружи.
284
-
285
- `TaoFormField` также оборачивает `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup` и `TaoSegmented` — id, hint и error прокидываются сами.
286
-
287
- `TaoTag` может быть чипом: `#prefix` слева (обычно `TaoAvatar`), `closable` рисует крестик и эмитит `close`. Клик по крестику наружу не всплывает. `flat` снимает рамку, заливка остаётся.
288
-
289
- ```vue
290
- <TaoTag type="neutral" closable @close="remove">
291
- <template #prefix>
292
- <TaoAvatar name="Анна Козлова" size="small" />
293
- </template>
294
- Анна Козлова
295
- </TaoTag>
296
- ```
297
-
298
- ## Таблица и пагинация
299
-
300
- Таблица рендерит то, что передали: сама данные не режет и не сортирует. Это удобно и для серверной выборки, и для клиентской — страница режется снаружи.
301
-
302
- ```vue
303
- <TaoTable
304
- :columns="columns"
305
- :rows="pageRows"
306
- v-model:sort="sort"
307
- empty-text="Пока нет записей"
308
- >
309
- <template #cell-status="{ row }">
310
- <TaoTag :type="row.status === 'active' ? 'success' : 'neutral'">
311
- {{ row.status }}
312
- </TaoTag>
313
- </template>
314
- </TaoTable>
315
-
316
- <TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
317
- ```
318
-
319
- ```javascript
320
- const columns = [
321
- { key: 'name', label: 'Имя', sortable: true },
322
- { key: 'city', label: 'Город' },
323
- { key: 'status', label: 'Статус' },
324
- ]
325
- ```
326
-
327
- Слот `cell-<ключ>` перекрывает ячейку. `loading` показывает оверлей, пустой список — текст или слот `#empty`. Клик по шапке с `sortable` крутит `asc → desc → сброс`.
328
-
329
- ## Пустые состояния и загрузка
330
-
331
- ```vue
332
- <TaoEmpty title="Ничего не нашлось">
333
- Измените фильтр или сбросьте поиск.
334
- <template #action>
335
- <TaoButton variant="secondary">Сбросить</TaoButton>
336
- </template>
337
- </TaoEmpty>
338
-
339
- <TaoSkeleton variant="title" />
340
- <TaoSkeleton :lines="3" />
341
- <TaoSkeleton variant="circle" />
342
-
343
- <TaoStages :items="[
344
- { key: 'pay', label: 'Оплата', status: 'ok' },
345
- { key: 'pack', label: 'Сборка', status: 'work' },
346
- { key: 'ship', label: 'Доставка', status: 'wait' },
347
- ]" />
348
-
349
- <TaoList>
350
- <TaoListItem
351
- title="Анна Козлова"
352
- description="Дизайн · Москва"
353
- clickable
354
- :selected="picked === 'anna'"
355
- @click="picked = 'anna'"
356
- >
357
- <template #prefix>
358
- <TaoAvatar name="Анна Козлова" size="small" />
359
- </template>
360
- </TaoListItem>
361
- </TaoList>
362
- ```
363
-
364
- ```vue
365
- <TaoInput v-model="q" placeholder="Найти…">
366
- <template #prefix>⌕</template>
367
- </TaoInput>
368
-
369
- <TaoInputGroup>
370
- <template #before>https://</template>
371
- <TaoInput v-model="host" placeholder="example.com" />
372
- <template #after>
373
- <TaoButton>Проверить</TaoButton>
374
- </template>
375
- </TaoInputGroup>
376
-
377
- <form @submit.prevent="onSave">
378
- <TaoFormField label="Email">
379
- <TaoInput v-model="email" type="email" />
380
- </TaoFormField>
381
- <TaoButton type="submit">Сохранить</TaoButton>
382
- </form>
383
-
384
- <TaoFormField label="Количество">
385
- <TaoInputNumber v-model="qty" :min="1" :max="99" />
386
- </TaoFormField>
387
-
388
- <TaoQuantity v-model="qty" :max="12" @dec="onDec" />
389
-
390
- <TaoFormField label="День доставки" hint="В модели всегда YYYY-MM-DD">
391
- <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
392
- </TaoFormField>
393
-
394
- <TaoFormField label="Даты поездки">
395
- <TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
396
- </TaoFormField>
397
-
398
- <TaoCounter :value="score" :max-digits="6" />
399
-
400
- <TaoCarousel :autoplay="4000" loop dots>
401
- <article v-for="item in banners" :key="item.id" class="hero">
402
- <strong>{{ item.title }}</strong>
403
- <span>{{ item.text }}</span>
404
- </article>
405
- </TaoCarousel>
406
- <TaoCarousel :peek="72" :controls="false" dots>…</TaoCarousel>
407
- <TaoCarousel v-model="slide" :per-view="5" :peek="28">
408
- <template #prev></template>
409
- <template #next="{ go, disabled }">
410
- <button type="button" :disabled="disabled" @click="go">вперёд</button>
411
- </template>
412
- <article v-for="item in products" :key="item.id">…</article>
413
- </TaoCarousel>
414
- ```
415
-
416
- `TaoDrawer` — лист сбоку, не модалка по центру:
417
-
418
- ```vue
419
- <TaoDrawer v-model="open" title="Фильтры">
420
- ...
421
- </TaoDrawer>
422
- ```
423
-
424
- ## Дизайн-токены и темизация
425
-
426
- Стили библиотеки построены в три слоя. Компоненты **никогда** не обращаются
427
- к цветам/размерам напрямую — только через переменные из семантического слоя.
428
- Это и есть механизм темизации: переопределяете 20-30 переменных — меняется
429
- внешний вид всех компонентов сразу, без правок самих компонентов.
430
-
431
- ```
432
- primitives.css → semantic.css → themes/*.css (опционально)
433
- сырые цвета публичный API готовые темы поверх
434
- и размеры, темизации: semantic — пример: light
435
- не трогать вот что менять
436
- ```
437
-
438
- ### Слои
439
-
440
- | Файл | Назначение | Трогать? |
441
- |---|---|---|
442
- | `primitives.css` | Сырая палитра, шкалы отступов/радиусов/теней (`--tao-orange-400`, `--tao-space-3`...) | Обычно нет |
443
- | `semantic.css` | Токены темы по умолчанию (dark): `--tao-color-accent`, `--tao-color-surface`, `--tao-color-danger` и т.д. | **Да — это и есть API темизации** |
444
- | `themes/light.css` | Пример альтернативной темы через `[data-tao-theme="light"]` | Да, как образец |
445
- | `base.css` | Глобальный reset (скроллбар, ссылки, box-sizing) | Редко |
446
-
447
- Все четыре подключаются одним файлом `@1337exp/taoui/styles.css`.
448
-
449
- ### Как сделать свою тему
450
-
451
- Тема — это просто переопределение семантических токенов под своим селектором.
452
- Ничего в компонентах менять не нужно:
453
-
454
- ```css
455
- /* my-brand-theme.css */
456
- [data-tao-theme="my-brand"] {
457
- --tao-color-accent: #6c5ce7;
458
- --tao-color-accent-hover: #5a4bd1;
459
- --tao-color-bg: #0f0f1a;
460
- --tao-color-surface: #0f0f1a;
461
- --tao-color-surface-raised: #1a1a2e;
462
- --tao-color-text: #d6d6e8;
463
- --tao-color-text-strong: #ffffff;
464
- /* остальные токены см. semantic.css */
465
- }
466
- ```
467
-
468
- ```vue
469
- <!-- app.vue -->
470
- <template>
471
- <div data-tao-theme="my-brand">
472
- <NuxtPage />
473
- </div>
474
- </template>
475
- ```
476
-
477
- Или переключайте тему целиком на `<html>`, чтобы стилизовать модалки/тултипы,
478
- которые телепортируются в `body`:
479
-
480
- ```javascript
481
- document.documentElement.setAttribute('data-tao-theme', 'light')
482
- ```
483
-
484
- ### Ключевые группы токенов
485
-
486
- - `--tao-color-accent*` — акцентный/брендовый цвет (кнопки primary, активные вкладки, ссылки)
487
- - `--tao-color-on-accent` — текст на акцентном фоне (`--tao-color-text-on-accent` — алиас)
488
- - `--tao-color-selection`, `--tao-color-selection-text` — выделение текста (`::selection`)
489
- - `--tao-color-surface*` — фоны контейнеров (обычный / приподнятый / утопленный / hover)
490
- - `--tao-color-border*` — границы
491
- - `--tao-color-text*` — текст (обычный / усиленный / subtle / приглушённый / disabled)
492
- - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — статусные цвета
493
- - `--tao-color-input-*` — поля ввода отдельно, т.к. фон/текст полей часто не совпадают с surface/text
494
- - `--tao-radius-control`, `--tao-radius-panel` — скругления (мелкие контролы vs крупные панели)
495
- - `--tao-shadow-panel`, `--tao-shadow-overlay` — тени
496
- - `--tao-font-size-*` — шкала кегля в `primitives.css`: `xs`–`xl` контролы, `2xl`–`4xl` заголовки / проза
497
- - `--tao-control-height-small` / `-medium` / `-large` — единая шкала высот (26 / 36 / 44px) для всех контролов с `size`: Button, Segmented, Select, Combobox. `--tao-field-height` (= medium) — высота полей без `size`: Input, InputNumber, Date, DateRange, Quantity
498
-
499
- Полный список — в `src/styles/semantic.css`, он же единственный файл,
500
- который стоит открыть, чтобы понять весь доступный API темизации.
501
-
502
- ### Если нужна тема с нуля, без primitives
503
-
504
- ```javascript
505
- import '@1337exp/taoui/styles/primitives.css' // шкалы можно оставить
506
- import './my-semantic.css' // свой семантический слой вместо @1337exp/taoui/styles/semantic.css
507
- import '@1337exp/taoui/styles/base.css'
508
- ```
509
-
510
- ## Демонстрация
511
-
512
- Для просмотра всех компонентов запустите showcase:
513
-
514
- ```bash
515
- cd showcase
516
- npm install
517
- npm run dev
518
- ```
519
-
520
- В showcase есть переключатель темы (dark / light) в шапке — так виден
521
- эффект переопределения токенов без правок кода компонентов.
522
-
523
- Showcase смотрит прямо в `src/`, поэтому правки компонентов видны без
524
- `npm run build`. Сборка `dist/` нужна для публикации и для чужих проектов,
525
- которые ставят пакет.
526
-
527
- ## Разработка
528
-
529
- ```bash
530
- # Сборка библиотеки
531
- npm run build
532
-
533
- # Режим разработки (watch)
534
- npm run dev
535
-
536
- # Проверка типов
537
- npm run type-check
538
- ```
539
-
540
- ## Публикация в npm
541
-
542
- Публикуется только `dist/` (собранная библиотека) и `src/styles/` (сырые
543
- токены — чтобы можно было подключить `primitives.css` отдельно при
544
- кастомной теме). Исходники компонентов (`src/components/*.vue`),
545
- конфиги сборки и `showcase/` в пакет не попадают — они остаются в
546
- репозитории; чтобы их получить, репозиторий клонируют.
547
-
548
- `npm publish` **сам** прогоняет проверку типов и полную пересборку перед
549
- публикацией (хук `prepublishOnly` в `package.json`) — так в реестр не
550
- уедет пакет со старым или отсутствующим `dist/`. Собирать вручную перед
551
- `npm publish` не нужно.
552
-
553
- Проверить, что именно попадёт в пакет, без реальной публикации:
554
-
555
- ```bash
556
- npm pack --dry-run
557
- ```
558
-
559
- ## Лицензия
560
-
561
- MIT
1
+ # Tao UI
2
+
3
+ [English](README.md) · **Русский**
4
+
5
+ Библиотека Vue 3 компонентов для Nuxt/Vue проектов с системой дизайн-токенов:
6
+ поменял несколько CSS-переменных — поменялась тема всего набора компонентов.
7
+
8
+ ## Компоненты
9
+
10
+ ### Базовые
11
+
12
+ - **TaoBlock** — базовый контейнер с настраиваемыми отступами и скруглением
13
+ - **TaoButton** — кнопка: `primary` / `secondary` / `ghost` / `text` / `danger`. `tone` красит ghost и text (danger, success, warning, info)
14
+ - **TaoCard** — карточка со слотами cover / header / footer. В `#cover` — фото или `TaoCarousel`. `flush` — плитка без padding/тени на всю ячейку; `#overlay` — scrim на обложке
15
+ - **TaoCopy** — иконка копирования в буфер. После клика сверху тултип «Скопировано»; если кнопку убрали — тултип тоже
16
+ - **TaoInput** — поле ввода с поддержкой v-model, валидации и слотов `#prefix` / `#suffix` (иконка или текст внутри рамки)
17
+ - **TaoInputGroup** — склейка снаружи: `#before` | поле | `#after` (протокол, единица, кнопка)
18
+ - **TaoModal** — модальное окно с анимацией и слотами
19
+ - **TaoDrawer** — боковая панель (фильтры, настройки). Esc, клик по фону, ловушка фокуса — как у модалки
20
+ - **TaoSpoiler** — раскрывающийся блок. `v-model` и `aria-expanded`. Несколько подряд сами друг друга не закрывают
21
+ - **TaoSpoilerGroup** — аккордеон: `v-model` — ключ открытой панели (`null` — все закрыты), у спойлера `name`. Без `v-model` группа помнит ключ сама
22
+ - **TaoTabs** — вкладки для переключения между секциями контента
23
+ - **TaoTooltip** — всплывающая подсказка при наведении. `top` / `bottom` / `left` / `right`, у края экрана переворачивается
24
+ - **TaoPopover** — панель по клику: слот с любым контентом, Esc и клик снаружи. Не тултип и не меню действий
25
+
26
+ ### Layout
27
+
28
+ - **TaoContainer** — контейнер с ограничением ширины (wide/slim/ultra-slim) и авто-центровкой
29
+ - **TaoFlex** — обёртка над flexbox с пропами justify/align/direction/wrap/gap
30
+ - **TaoSpace** — авто-расстановка дочерних элементов с равномерным gap
31
+ - **TaoGrid** / **TaoGridItem** — плитки: `min` — каталог (auto-fill), `cols` — bento. У item `col` / `row`; уже ~560px span сбрасывается. Не masonry
32
+ - **TaoDivider** — `solid` (обычный border) / `dashed` / `colored` (акцент) / `gap`. Подпись — опциональный `text` на любом варианте; `fade` — плавные края линии; `size` только у `gap` (small / medium / large)
33
+ - **TaoSplit** — две панели и полоса. `row` / `column` как у Flex. `v-model` — размер start в `%` или `px`; `resizable="false"` фиксирует полосу. Не Divider.
34
+ - **TaoFieldset** — рамка-группа: `legend` сидит на верхней границе, `align` — start / center / end
35
+ - **TaoAnimatedBorder** — контейнер с анимированной радужной рамкой (декоративный, не завязан на тему)
36
+
37
+ ### Формы и ввод
38
+
39
+ - **TaoCheckbox** — чекбокс с v-model, слотами pre/post и `indeterminate` (частично выбран)
40
+ - **TaoSwitch** — переключатель для булевых настроек (`role="switch"`)
41
+ - **TaoRadio** / **TaoRadioGroup** — классические радиокнопки: длинные подписи, можно столбиком
42
+ - **TaoSegmented** / **TaoSegmentedOption** — компактный выбор из 2–5 коротких вариантов. Не вкладки
43
+ - **TaoSelect** — выпадающий список с клавиатурой, тот же визуал, что у Input. `size` (`small` / `medium` / `large`, та же шкала, что у Button). Сброс — «Очистить» в списке или Delete; `clearable="false"` отключает сброс, слот `#clear` заменяет содержимое строки
44
+ - **TaoCombobox** — Select с полем: фильтр по вводу, `allow-create` пишет своё в `v-model`, `create` — чтобы родитель дополнил список. Те же `size`, `clearable` и `#clear`, что у `TaoSelect`
45
+ - **TaoDate** — один день: `YYYY-MM-DD`, без часов и пояса. Календарь как у Select
46
+ - **TaoDateRange** — период: `v-model` — `{ start, end }` или `null`. Первый клик — начало, второй — конец (если конец раньше — меняются местами). Неполный выбор в модель не пишется
47
+ - **TaoFormField** — общие label / hint / error для полей формы
48
+ - **TaoInputNumber** — число с min/max/step и кнопками ± справа. Пустое значение — `null`. `@commit` срабатывает один раз, когда правка закончена (blur, Enter, ±, стрелка), в отличие от `v-model`, который обновляется на каждую клавишу
49
+ - **TaoQuantity** — количество в корзине: `− | поле | +`, целые штуки, сток, минус на минимуме может убрать строку
50
+ - **TaoTextarea** — многострочное поле с авто-высотой. `maxlength` ограничивает ввод, `count` показывает «введено / максимум». `variant`: `bar` (по умолчанию) / `outline` (рамка как у Input) / `filled` / `plain`; `readonly`. `noBorder`, `noBackground`, `borderInverse`, `dummy` устарели
51
+ - **TaoPinCode** — пин-код из N полей. По умолчанию клик стирает ячейку и все справа (`clear-on="focus"`); `clear-on="input"` заменяет цифру только при вводе. Последняя ячейка снимает фокус и эмитит `complete`
52
+ - **TaoSlider** — слайдер: мышь, тач и стрелки. Опциональный точный ввод по правому клику. `variant="thin"` — тонкий трек для seek / громкости; `size` масштабирует любой трек
53
+ - **TaoFileDrop** — зона загрузки (drag & drop + клик). Список имён под зоной, `v-model` — `File[]`. Очистку всей пачки решает родитель (`clear-request`)
54
+
55
+ ### Отображение данных
56
+
57
+ - **TaoTable** — простая таблица: колонки, empty, loading, сортировка через `v-model:sort`. `head` — подсветка шапки, `lines` — линии между рядами (оба по умолчанию включены). `striped` — зебра с первой строки, `striped="even"` — со второй. Не datagrid.
58
+ - **TaoPagination** — страницы с многоточием. Клик по «…» прыгает на `jump` страниц (5 по умолчанию)
59
+ - **TaoEmpty** — пустой список, нет результатов, нет прав
60
+ - **TaoList** / **TaoListItem** — строка списка: иконка, заголовок, подпись, действие по ховеру. Не Select и не таблица
61
+ - **TaoStages** — список стадий: `wait` / `work` / `ok` / `bad`. Не линейный степпер
62
+ - **TaoSkeleton** — плейсхолдер загрузки (text / title / circle / rect)
63
+ - **TaoCounter** — витрина числа с переворотом цифр (не инпут)
64
+ - **TaoCarousel** — лента: целый слайд с `autoplay`, карточка с `peek`, полоса с `per-view`. Стрелки через `controls` или `#prev` / `#next`, точки — `dots`
65
+ - **TaoAvatar** — фото или инициалы, размеры `small` / `medium` / `large`. Точка `dot` и счётчик `count`
66
+ - **TaoTag** — тег/бейдж со статусами. `#prefix` (аватар), `closable` убирает чип, `flat` — без рамки
67
+ - **TaoAlert** — инлайн-баннер страницы или ошибки формы (success / error / warning / info)
68
+ - **TaoProgress** — статичная полоса (`progress` в %). Проценты сверху по центру или `showPercentage="right"` справа; слоты `#left` / `#right` — подписи, тогда процент справа в скобках. `false` прячет. Ширина — `minWidth` / `maxWidth`, не диапазон значения
69
+ - **TaoLoader** — анимированный лоадер (четыре точки)
70
+ - **TaoImage** — обёртка над `<img>`: fade-in и плейсхолдер. `lazy` включает нативный `loading="lazy"`
71
+ - **TaoIcon** — обёртка для icon-шрифта (см. раздел «Иконки» ниже)
72
+
73
+ ### Навигация и взаимодействие
74
+
75
+ - **TaoLink** — `<NuxtLink>` в Nuxt, `<RouterLink>` при vue-router, иначе обычный `<a>` — без дополнительной настройки
76
+ - **TaoBreadcrumb** — крошки: последний пункт — текущая страница
77
+ - **TaoDropdownMenu** — выпадающее меню с авто-позиционированием у края экрана
78
+ - **TaoScrollTop** — плавающая кнопка «наверх» с ripple. Появляется при обратном скролле после `boundary`
79
+
80
+ ### Обратная связь
81
+
82
+ - **toast()** — fluent-уведомления: `toast().success().message('Сохранено')`
83
+ - **confirm()** — вопрос с оверлеем: тот же fluent + `await`. Не тост — ждёт ответ, не исчезает сам.
84
+ - **TaoToastViewport** / **TaoConfirmHost** — контейнеры; если их нет в разметке, первый вызов сам монтирует их в `body`
85
+
86
+ ## Соглашения
87
+
88
+ Тоны визуала: `success` | `danger` | `warning` | `info` | `neutral` (тип `TaoTone`), всегда через проп `tone`: Button, Alert, Tag. `type` у Alert / Tag — устаревший алиас.
89
+ `error` у Alert, Tag и `toast()` — синоним `danger`. Button уже `danger`.
90
+ Stages — это процесс, не тон: `wait` / `work` / `ok` / `bad` (`danger` принимается как `bad`).
91
+
92
+ Размеры контролов: `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"` вместо `compact`); FileDrop — зону и строки файлов; Slider — трек и бегунок.
93
+ Без `size` контрол берёт размер предков, в корне — `medium`. На целый блок размер задаётся классом `tao-size-small` / `-medium` / `-large` на любом элементе или `size` у `TaoFormField` / `TaoInputGroup`. Явный `size` у контрола главнее.
94
+
95
+ ```vue
96
+ <div class="tao-size-small">
97
+ <TaoInput v-model="q" />
98
+ <TaoButton>Найти</TaoButton>
99
+ </div>
100
+ ```
101
+
102
+ Контент и раскладка держат свою шкалу и не наследуют: Avatar (24 / 32 / 48px; `s` / `m` / `l` устарели), Divider `gap` (`big` — устаревший алиас `large`), Loader / Icon / ScrollTop (пиксели).
103
+ Container живёт на другой оси — ширина: `width="wide" | "slim" | "ultra-slim"` (`size` — устаревший алиас).
104
+
105
+ Шкала кегля (примитивы): `xs` 12 … `xl` 18 для контролов; `2xl` 24, `3xl` 32, `4xl` 36 для заголовков и прозы.
106
+ Отдельного компонента заголовка нет — `h1 { font-size: var(--tao-font-size-3xl) }`.
107
+
108
+ Правила API — им следуют все компоненты; старые имена остаются устаревшими алиасами:
109
+
110
+ - **Поля** принимают `v-model`, `disabled`, `error` (красная рамка) и `size`. Подпись, подсказка и текст ошибки — через `TaoFormField`.
111
+ - **События**: `update:X` для v-model плюс `change`, когда пользователь закончил изменение (Slider, Split — по отпусканию). Остальные события — глаголы в настоящем времени: `select`, `close`, `create`.
112
+ - **Тексты**: видимые — `*Text` (`clearText`, `successText`), для скринридера — `*Label` (`closeLabel`).
113
+ - **Списки**: массивы данных — `items`; выбираемые элементы несут `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Идентификаторы обычных данных (колонки таблицы, стадии) остаются `key`.
114
+ - **Булевы** — прилагательные без `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Ось раскладки — `direction: 'row' | 'column'`, не `vertical`.
115
+ - **Длины** (`padding`, `radius`, `gap`, `maxHeight`): число — пиксели, строка уходит в CSS как есть (тип `TaoLength`).
116
+
117
+ ## Иконки
118
+
119
+ `TaoIcon` не поставляет собственный набор иконок — он рендерит класс `icon-<name>`
120
+ по соглашению, рассчитанному на подключение внешнего icon-шрифта (например,
121
+ собранного через IcoMoon/Fontello). Чтобы иконки отображались, подключите
122
+ свой шрифт с классами вида `.icon-arrow-up { ... }` в проекте.
123
+
124
+ ## Установка
125
+
126
+ ```bash
127
+ npm install @1337exp/taoui
128
+ ```
129
+
130
+ Или локально из папки:
131
+
132
+ ```bash
133
+ npm install ../path-to-tao-ui
134
+ ```
135
+
136
+ ## Использование
137
+
138
+ ### Подключение в Nuxt 3
139
+
140
+ Создайте плагин `plugins/tao-ui.ts`:
141
+
142
+ ```typescript
143
+ import { defineNuxtPlugin } from '#app'
144
+ import TaoUI from '@1337exp/taoui'
145
+
146
+ export default defineNuxtPlugin((nuxtApp) => {
147
+ nuxtApp.vueApp.use(TaoUI)
148
+ })
149
+ ```
150
+
151
+ Импортируйте стили в `app.vue` или layout:
152
+
153
+ ```vue
154
+ <script setup>
155
+ import '@1337exp/taoui/styles.css'
156
+ </script>
157
+ ```
158
+
159
+ ### Подключение в Vue 3 проекте
160
+
161
+ ```javascript
162
+ // main.js
163
+ import { createApp } from 'vue'
164
+ import App from './App.vue'
165
+ import TaoUI from '@1337exp/taoui'
166
+ import '@1337exp/taoui/styles.css'
167
+
168
+ const app = createApp(App)
169
+ app.use(TaoUI)
170
+ app.mount('#app')
171
+ ```
172
+
173
+ ### Язык
174
+
175
+ Встроенные тексты (плейсхолдеры, «Очистить», aria-подписи, даты) по умолчанию русские. Английский идёт в комплекте:
176
+
177
+ ```javascript
178
+ import TaoUI, { localeEn } from '@1337exp/taoui'
179
+
180
+ app.use(TaoUI, { locale: localeEn })
181
+ ```
182
+
183
+ Поменять отдельные тексты — остальное останется от локали по умолчанию:
184
+
185
+ ```javascript
186
+ app.use(TaoUI, { locale: { select: { placeholder: 'Выберите город' } } })
187
+ ```
188
+
189
+ Другой язык: скопируйте `localeEn`, переведите и передайте так же (тип `TaoLocale`). Ключи повторяют имена пропсов —
190
+ `locale.select.placeholder` — значение по умолчанию для `placeholder` у TaoSelect, а переданный руками проп всегда главнее.
191
+
192
+ Язык можно переключать в любой момент — из настроек, переключателя языка, по маршруту. Уже показанные компоненты
193
+ обновятся сразу, без перезагрузки и без потери введённого:
194
+
195
+ ```javascript
196
+ import { setTaoLocale, localeEn, localeRu } from '@1337exp/taoui'
197
+
198
+ function onLanguageChange(lang) {
199
+ setTaoLocale(lang === 'en' ? localeEn : localeRu)
200
+ }
201
+ ```
202
+
203
+ Без плагина (отдельные компоненты) достаточно одного вызова `setTaoLocale()`.
204
+
205
+ ### Переход с 1.x
206
+
207
+ Смотрите [CHANGELOG.md](CHANGELOG.md): что сломалось и таблица «старое имя → новое». В 2.x старые имена ещё работают
208
+ и в режиме разработки пишут предупреждение в консоль.
209
+
210
+ ### Использование отдельных компонентов
211
+
212
+ ```vue
213
+ <script setup>
214
+ import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
215
+ import '@1337exp/taoui/styles.css'
216
+ </script>
217
+
218
+ <template>
219
+ <TaoButton variant="primary">Нажми меня</TaoButton>
220
+ <TaoFormField label="Введите текст">
221
+ <TaoInput v-model="text" />
222
+ </TaoFormField>
223
+ <TaoModal v-model="isOpen" title="Заголовок">
224
+ Содержимое модального окна
225
+ </TaoModal>
226
+ </template>
227
+ ```
228
+
229
+ ## Split
230
+
231
+ `TaoSplit` — две панели и полоса между ними. Это не `TaoDivider` (там только линия) и не раскладка на N панелей: три колонки — два вложенных сплита.
232
+
233
+ `direction` как у Flex: `row` (start | end) или `column` (start над end). Слоты `#start` / `#end`.
234
+
235
+ `v-model` — размер панели start. `unit` — `%` (по умолчанию, доля живёт при ресайзе контейнера) или `px` (сайдбар; вторая панель забирает остаток). Для `px` размер нужно задать явно: дефолт `50` — это 50px. `min` / `max` ограничивают start, `min-end` — минимум второй панели, все в той же единице. `resizable="false"` оставляет полосу, но без перетаскивания.
236
+
237
+ Сплит заполняет родителя (`width` / `height: 100%`). Родитель должен ограничить размер по оси сплита: у `column` без высоты не из чего считать `%`. Панели с `min-width` / `min-height: 0` и `overflow: hidden`, чтобы контент не мешал сжатию. Скролл — на внутренней обёртке (`overflow: auto; height: 100%; min-height: 0`). Вложенный `TaoSplit` прямым ребёнком панели растягивается сам.
238
+
239
+ ```vue
240
+ <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
241
+ <template #start>Навигация</template>
242
+ <template #end>Основное</template>
243
+ </TaoSplit>
244
+ ```
245
+
246
+ ## Toast
247
+
248
+ Вызов — цепочка в одном тике, `setTimeout(0)` отправляет уведомление.
249
+
250
+ ```javascript
251
+ import { toast } from '@1337exp/taoui'
252
+
253
+ toast().success().message('Сохранено')
254
+ toast().error().title('Сеть').timeout(5000).message('Нет соединения')
255
+ toast.success('Сохранено')
256
+ toast.warning('Черновик', { timeout: 1000 })
257
+ ```
258
+
259
+ Позиция по умолчанию — `topCenter`. Глобально:
260
+
261
+ ```javascript
262
+ toast.defaults({ position: 'bottomRight' })
263
+ toast.byBottomRight()
264
+ ```
265
+
266
+ `question` с оверлеем в kit нет — это confirm, не toast. Кнопки в тосте, если нужны:
267
+
268
+ ```javascript
269
+ toast().info().message('Удалить файл?').action('Удалить', onRemove)
270
+ ```
271
+
272
+ Viewport можно не вставлять: первый вызов сам создаст его. Если нужен явный контроль (тесты, свой layout):
273
+
274
+ ```vue
275
+ <TaoToastViewport />
276
+ ```
277
+
278
+ ## Confirm
279
+
280
+ Вопрос с оверлеем: всплывает по центру и спрашивает. Это не toast — нет прогресс-бара и автозакрытия, есть `await`, Esc и клик по оверлею = отмена.
281
+
282
+ ```javascript
283
+ import { confirm } from '@1337exp/taoui'
284
+
285
+ if (await confirm().title('Удалить файл?').message('Это нельзя отменить').danger()) {
286
+ remove()
287
+ }
288
+
289
+ const ok = await confirm('Выйти без сохранения?', {
290
+ ok: 'Выйти',
291
+ cancel: 'Остаться',
292
+ })
293
+ ```
294
+
295
+ Очередь: второй `confirm()`, пока открыт первый, подождёт. Подписи по умолчанию — «ОК» / «Отмена»:
296
+
297
+ ```javascript
298
+ confirm.defaults({ ok: 'Yes', cancel: 'No' })
299
+ ```
300
+
301
+ ## Формы
302
+
303
+ `TaoFormField` вешает общий label / hint / error и прокидывает `id` во вложенный контрол.
304
+
305
+ ```vue
306
+ <TaoFormField label="Город" hint="Необязательно">
307
+ <TaoSelect v-model="city" :options="cities" />
308
+ </TaoFormField>
309
+
310
+ <TaoSwitch v-model="dark" label="Тёмная тема" />
311
+
312
+ <TaoRadioGroup v-model="plan" legend="Тариф">
313
+ <TaoRadio value="free" label="Free" />
314
+ <TaoRadio value="pro" label="Pro" />
315
+ </TaoRadioGroup>
316
+
317
+ <TaoSegmented v-model="period" legend="Период">
318
+ <TaoSegmentedOption value="week">Неделя</TaoSegmentedOption>
319
+ <TaoSegmentedOption value="month">Месяц</TaoSegmentedOption>
320
+ <TaoSegmentedOption value="year">Год</TaoSegmentedOption>
321
+ </TaoSegmented>
322
+
323
+ <TaoAlert tone="warning" title="Черновик">Сохраните, прежде чем уйти.</TaoAlert>
324
+ ```
325
+
326
+ `TaoSegmented` — короткий взаимоисключающий выбор, все варианты видны сразу. Не для навигации по страницам: это `TaoTabs`. Длинные подписи или больше 5–6 пунктов — `TaoRadioGroup` или `TaoSelect`.
327
+
328
+ `TaoSelect` открывается с клавиатуры (стрелки, Enter, Esc), список переворачивается у края экрана. Delete или «Очистить» внизу списка сбрасывает значение в `null`.
329
+
330
+ Если `null` не допустим (шаг сетки, порядок сортировки), передайте `:clearable="false"`: строка сброса и Delete / Backspace пропадут. Подпись строки сброса — `clear-text`, для иконки или своей разметки есть слот `#clear`. `size` — `small` / `medium` / `large` (без него — от предков), масштабирует и раскрытый список.
331
+
332
+ ```vue
333
+ <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
334
+
335
+ <TaoSelect v-model="city" :options="cities">
336
+ <template #clear><TaoIcon name="close" /> Сбросить</template>
337
+ </TaoSelect>
338
+ ```
339
+
340
+ `TaoCombobox` — то же меню, но с полем. Печатаете — варианты режутся. `allow-create` пишет введённое в `v-model`, если точного совпадения нет. Список сам не меняется: слушайте `create` и добавьте option снаружи.
341
+
342
+ Подпись, подсказка и текст ошибки всегда идут через `TaoFormField`; `label` / `error-message` у `TaoInput` устарели. `TaoFormField` также оборачивает `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup` и `TaoSegmented` — id, hint и error прокидываются сами.
343
+
344
+ `TaoTag` может быть чипом: `#prefix` слева (обычно `TaoAvatar`), `closable` рисует крестик и эмитит `close`. Клик по крестику наружу не всплывает. `flat` снимает рамку, заливка остаётся.
345
+
346
+ ```vue
347
+ <TaoTag tone="neutral" closable @close="remove">
348
+ <template #prefix>
349
+ <TaoAvatar name="Анна Козлова" size="small" />
350
+ </template>
351
+ Анна Козлова
352
+ </TaoTag>
353
+ ```
354
+
355
+ ## Таблица и пагинация
356
+
357
+ Таблица рендерит то, что передали: сама данные не режет и не сортирует. Это удобно и для серверной выборки, и для клиентской — страница режется снаружи.
358
+
359
+ ```vue
360
+ <TaoTable
361
+ :columns="columns"
362
+ :rows="pageRows"
363
+ v-model:sort="sort"
364
+ empty-text="Пока нет записей"
365
+ >
366
+ <template #cell-status="{ row }">
367
+ <TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
368
+ {{ row.status }}
369
+ </TaoTag>
370
+ </template>
371
+ </TaoTable>
372
+
373
+ <TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
374
+ ```
375
+
376
+ ```javascript
377
+ const columns = [
378
+ { key: 'name', label: 'Имя', sortable: true },
379
+ { key: 'city', label: 'Город' },
380
+ { key: 'status', label: 'Статус' },
381
+ ]
382
+ ```
383
+
384
+ Слот `cell-<ключ>` перекрывает ячейку. `loading` показывает оверлей, пустой список — текст или слот `#empty`. Клик по шапке с `sortable` крутит `asc → desc → сброс`.
385
+
386
+ ## Пустые состояния и загрузка
387
+
388
+ ```vue
389
+ <TaoEmpty title="Ничего не нашлось">
390
+ Измените фильтр или сбросьте поиск.
391
+ <template #action>
392
+ <TaoButton variant="secondary">Сбросить</TaoButton>
393
+ </template>
394
+ </TaoEmpty>
395
+
396
+ <TaoSkeleton variant="title" />
397
+ <TaoSkeleton :lines="3" />
398
+ <TaoSkeleton variant="circle" />
399
+
400
+ <TaoStages :items="[
401
+ { key: 'pay', label: 'Оплата', status: 'ok' },
402
+ { key: 'pack', label: 'Сборка', status: 'work' },
403
+ { key: 'ship', label: 'Доставка', status: 'wait' },
404
+ ]" />
405
+
406
+ <TaoList>
407
+ <TaoListItem
408
+ title="Анна Козлова"
409
+ description="Дизайн · Москва"
410
+ clickable
411
+ :selected="picked === 'anna'"
412
+ @click="picked = 'anna'"
413
+ >
414
+ <template #prefix>
415
+ <TaoAvatar name="Анна Козлова" size="small" />
416
+ </template>
417
+ </TaoListItem>
418
+ </TaoList>
419
+ ```
420
+
421
+ ```vue
422
+ <TaoInput v-model="q" placeholder="Найти…">
423
+ <template #prefix>⌕</template>
424
+ </TaoInput>
425
+
426
+ <TaoInputGroup>
427
+ <template #before>https://</template>
428
+ <TaoInput v-model="host" placeholder="example.com" />
429
+ <template #after>
430
+ <TaoButton>Проверить</TaoButton>
431
+ </template>
432
+ </TaoInputGroup>
433
+
434
+ <form @submit.prevent="onSave">
435
+ <TaoFormField label="Email">
436
+ <TaoInput v-model="email" type="email" />
437
+ </TaoFormField>
438
+ <TaoButton type="submit">Сохранить</TaoButton>
439
+ </form>
440
+
441
+ <TaoFormField label="Количество">
442
+ <TaoInputNumber v-model="qty" :min="1" :max="99" />
443
+ </TaoFormField>
444
+
445
+ <TaoQuantity v-model="qty" :max="12" @dec="onDec" />
446
+
447
+ <TaoFormField label="День доставки" hint="В модели всегда YYYY-MM-DD">
448
+ <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
449
+ </TaoFormField>
450
+
451
+ <TaoFormField label="Даты поездки">
452
+ <TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
453
+ </TaoFormField>
454
+
455
+ <TaoCounter :value="score" :max-digits="6" />
456
+
457
+ <TaoCarousel :autoplay="4000" loop dots>
458
+ <article v-for="item in banners" :key="item.id" class="hero">
459
+ <strong>{{ item.title }}</strong>
460
+ <span>{{ item.text }}</span>
461
+ </article>
462
+ </TaoCarousel>
463
+ <TaoCarousel :peek="72" :controls="false" dots>…</TaoCarousel>
464
+ <TaoCarousel v-model="slide" :per-view="5" :peek="28">
465
+ <template #prev></template>
466
+ <template #next="{ go, disabled }">
467
+ <button type="button" :disabled="disabled" @click="go">вперёд</button>
468
+ </template>
469
+ <article v-for="item in products" :key="item.id">…</article>
470
+ </TaoCarousel>
471
+ ```
472
+
473
+ `TaoDrawer` — лист сбоку, не модалка по центру:
474
+
475
+ ```vue
476
+ <TaoDrawer v-model="open" title="Фильтры">
477
+ ...
478
+ </TaoDrawer>
479
+ ```
480
+
481
+ ## Дизайн-токены и темизация
482
+
483
+ Стили библиотеки построены в три слоя. Компоненты **никогда** не обращаются
484
+ к цветам/размерам напрямую — только через переменные из семантического слоя.
485
+ Это и есть механизм темизации: переопределяете 20-30 переменных — меняется
486
+ внешний вид всех компонентов сразу, без правок самих компонентов.
487
+
488
+ ```
489
+ primitives.css → semantic.css → themes/*.css (опционально)
490
+ сырые цвета публичный API готовые темы поверх
491
+ и размеры, темизации: semantic — пример: light
492
+ не трогать вот что менять
493
+ ```
494
+
495
+ ### Слои
496
+
497
+ | Файл | Назначение | Трогать? |
498
+ |---|---|---|
499
+ | `primitives.css` | Сырая палитра, шкалы отступов/радиусов/теней (`--tao-orange-400`, `--tao-space-3`...) | Обычно нет |
500
+ | `semantic.css` | Токены темы по умолчанию (dark): `--tao-color-accent`, `--tao-color-surface`, `--tao-color-danger` и т.д. | **Да — это и есть API темизации** |
501
+ | `themes/light.css` | Пример альтернативной темы через `[data-tao-theme="light"]` | Да, как образец |
502
+ | `base.css` | Глобальный reset (скроллбар, ссылки, box-sizing) | Редко |
503
+
504
+ Все четыре подключаются одним файлом `@1337exp/taoui/styles.css`.
505
+
506
+ ### Как сделать свою тему
507
+
508
+ Тема — это просто переопределение семантических токенов под своим селектором.
509
+ Ничего в компонентах менять не нужно:
510
+
511
+ ```css
512
+ /* my-brand-theme.css */
513
+ [data-tao-theme="my-brand"] {
514
+ --tao-color-accent: #6c5ce7;
515
+ --tao-color-accent-hover: #5a4bd1;
516
+ --tao-color-bg: #0f0f1a;
517
+ --tao-color-surface: #0f0f1a;
518
+ --tao-color-surface-raised: #1a1a2e;
519
+ --tao-color-text: #d6d6e8;
520
+ --tao-color-text-strong: #ffffff;
521
+ /* остальные токены см. semantic.css */
522
+ }
523
+ ```
524
+
525
+ ```vue
526
+ <!-- app.vue -->
527
+ <template>
528
+ <div data-tao-theme="my-brand">
529
+ <NuxtPage />
530
+ </div>
531
+ </template>
532
+ ```
533
+
534
+ Или переключайте тему целиком на `<html>`, чтобы стилизовать модалки/тултипы,
535
+ которые телепортируются в `body`:
536
+
537
+ ```javascript
538
+ document.documentElement.setAttribute('data-tao-theme', 'light')
539
+ ```
540
+
541
+ ### Ключевые группы токенов
542
+
543
+ - `--tao-color-accent*` — акцентный/брендовый цвет (кнопки primary, активные вкладки, ссылки)
544
+ - `--tao-color-on-accent` — текст на акцентном фоне (`--tao-color-text-on-accent` — алиас)
545
+ - `--tao-color-selection`, `--tao-color-selection-text` — выделение текста (`::selection`)
546
+ - `--tao-color-surface*` — фоны контейнеров (обычный / приподнятый / утопленный / hover)
547
+ - `--tao-color-border*` — границы
548
+ - `--tao-color-text*` — текст (обычный / усиленный / subtle / приглушённый / disabled)
549
+ - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — статусные цвета
550
+ - `--tao-color-input-*` — поля ввода отдельно, т.к. фон/текст полей часто не совпадают с surface/text
551
+ - `--tao-radius-control`, `--tao-radius-panel` — скругления (мелкие контролы vs крупные панели)
552
+ - `--tao-shadow-panel`, `--tao-shadow-overlay` — тени
553
+ - `--tao-font-size-*` — шкала кегля в `primitives.css`: `xs`–`xl` контролы, `2xl`–`4xl` заголовки / проза
554
+ - `--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`. Компоненты читают текущие значения из `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`. Используйте их в своих контролах, чтобы попасть в размер окружения. `--tao-field-height` — устаревший алиас `--tao-control-height`
555
+
556
+ Полный список — в `src/styles/semantic.css`, он же единственный файл,
557
+ который стоит открыть, чтобы понять весь доступный API темизации.
558
+
559
+ ### Если нужна тема с нуля, без primitives
560
+
561
+ ```javascript
562
+ import '@1337exp/taoui/styles/primitives.css' // шкалы можно оставить
563
+ import './my-semantic.css' // свой семантический слой вместо @1337exp/taoui/styles/semantic.css
564
+ import '@1337exp/taoui/styles/base.css'
565
+ ```
566
+
567
+ ## Демонстрация
568
+
569
+ Для просмотра всех компонентов запустите showcase:
570
+
571
+ ```bash
572
+ cd showcase
573
+ npm install
574
+ npm run dev
575
+ ```
576
+
577
+ В showcase есть переключатель темы (dark / light) в шапке — так виден
578
+ эффект переопределения токенов без правок кода компонентов.
579
+
580
+ Showcase смотрит прямо в `src/`, поэтому правки компонентов видны без
581
+ `npm run build`. Сборка `dist/` нужна для публикации и для чужих проектов,
582
+ которые ставят пакет.
583
+
584
+ ## Разработка
585
+
586
+ ```bash
587
+ # Сборка библиотеки
588
+ npm run build
589
+
590
+ # Режим разработки (watch)
591
+ npm run dev
592
+
593
+ # Проверка типов
594
+ npm run type-check
595
+
596
+ # Тесты (Vitest)
597
+ npm test
598
+ ```
599
+
600
+ ## Публикация в npm
601
+
602
+ Публикуется только `dist/` (собранная библиотека) и `src/styles/` (сырые
603
+ токены — чтобы можно было подключить `primitives.css` отдельно при
604
+ кастомной теме). Исходники компонентов (`src/components/*.vue`),
605
+ конфиги сборки и `showcase/` в пакет не попадают — они остаются в
606
+ репозитории; чтобы их получить, репозиторий клонируют.
607
+
608
+ `npm publish` **сам** прогоняет проверку типов и полную пересборку перед
609
+ публикацией (хук `prepublishOnly` в `package.json`) — так в реестр не
610
+ уедет пакет со старым или отсутствующим `dist/`. Собирать вручную перед
611
+ `npm publish` не нужно.
612
+
613
+ Проверить, что именно попадёт в пакет, без реальной публикации:
614
+
615
+ ```bash
616
+ npm pack --dry-run
617
+ ```
618
+
619
+ ## Лицензия
620
+
621
+ MIT