@1337exp/taoui 3.2.0 → 3.3.1

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.md CHANGED
@@ -1,625 +1,676 @@
1
- # Tao UI
2
-
3
- **English** · [Русский](README.ru.md)
4
-
5
- A Vue 3 component library for Nuxt/Vue apps, driven by design tokens:
6
- change a handful of CSS variables and the whole kit follows.
7
-
8
- ## Components
9
-
10
- ### Basics
11
-
12
- - **TaoBlock** — container with padding and radius
13
- - **TaoButton** — `primary` / `secondary` / `ghost` / `text` / `danger`. `tone` tints ghost and text (danger, success, warning, info)
14
- - **TaoCard** — card with cover / header / footer slots. `#cover` can be a photo or `TaoCarousel`. `flush` is a tile (no padding/shadow, fills the cell); `#overlay` is a scrim on the cover
15
- - **TaoCopy** — clipboard icon. After a click, a “Copied” tooltip; if the trigger is gone, the tooltip is too
16
- - **TaoInput** — text field with v-model, validation, and `#prefix` / `#suffix` slots (icon or text inside the frame)
17
- - **TaoInputGroup** — outer glue: `#before` | field | `#after` (protocol, unit, button)
18
- - **TaoModal** — modal with animation and slots
19
- - **TaoDrawer** — side panel (filters, settings). Esc, backdrop click, focus trap — same as the modal
20
- - **TaoSpoiler** — disclosure. `v-model` and `aria-expanded`. Neighbours do not close each other
21
- - **TaoSpoilerGroup** — accordion: `v-model` is the open panel key (`null` = all closed); spoilers take `name`. Without `v-model` the group keeps that key itself
22
- - **TaoTabs** — tabbed sections
23
- - **TaoTooltip** — hover hint. `top` / `bottom` / `left` / `right`, flips at the viewport edge
24
- - **TaoPopover** — click panel with any slot content, Esc and outside click. Not a tooltip, not an action menu
25
-
26
- ### Layout
27
-
28
- - **TaoContainer** — max-width (wide / slim / ultra-slim) and centering
29
- - **TaoFlex** — flexbox wrapper: justify / align / direction / wrap / gap
30
- - **TaoSpace** — even gap between children
31
- - **TaoGrid** / **TaoGridItem** — tiles: `min` is a catalog (auto-fill), `cols` is bento. Item `col` / `row` span; below ~560px span resets. Not masonry
32
- - **TaoDivider** — `solid` (plain border) / `dashed` / `colored` (accent) / `gap`. Optional `text` sits in the middle of any of them; `fade` softens the line ends; `size` is for `gap` (small / medium / large)
33
- - **TaoSplit** — two panes and a gutter. `row` / `column` like Flex. `v-model` is the start size in `%` or `px`; `resizable="false"` locks the gutter. Not Divider.
34
- - **TaoFieldset** — grouped frame: `legend` sits on the top border, `align` is start / center / end
35
- - **TaoAnimatedBorder** — rainbow border wrapper (decorative, not tied to the theme)
36
-
37
- ### Forms
38
-
39
- - **TaoCheckbox** — checkbox with v-model, pre/post slots, and `indeterminate`
40
- - **TaoSwitch** — boolean toggle (`role="switch"`)
41
- - **TaoRadio** / **TaoRadioGroup** — classic radios: longer labels, can stack vertically
42
- - **TaoSegmented** / **TaoSegmentedOption** — compact exclusive choice among 2–5 short options. Not tabs
43
- - **TaoSelect** — dropdown with keyboard, same chrome as Input. `size` (`small` / `medium` / `large`, same scale as Button). Clear via “Clear” in the list or Delete; `clearable="false"` turns clearing off, `#clear` replaces the row content
44
- - **TaoCombobox** — Select with a field: type to filter, `allow-create` writes a custom value into `v-model`, `create` lets the parent append the list. Takes the same `size`, `clearable` and `#clear` as `TaoSelect`
45
- - **TaoDate** — a single day: `YYYY-MM-DD`, no time, no timezone. Calendar popup like Select
46
- - **TaoDateRange** — a period: `v-model` is `{ start, end }` or `null`. First click is start, second is end (they swap if end is earlier). An incomplete pick is not written to the model
47
- - **TaoFormField** — shared label / hint / error for form controls
48
- - **TaoInputNumber** — number with min/max/step and ± on the right. Empty value is `null`. `@commit` fires once when an edit is finished (blur, Enter, ±, arrow), unlike `v-model`, which updates on every keystroke
49
- - **TaoQuantity** — cart quantity: `− | field | +`, integers, stock; minus at the minimum can remove the row
50
- - **TaoTextarea** — autosizing multiline. `maxlength` caps input, `count` shows “entered / max”. `variant`: `bar` (default) / `outline` (frame like Input) / `filled` / `plain`; `readonly`. `noBorder`, `noBackground`, `borderInverse`, `dummy` are deprecated
51
- - **TaoPinCode** — N cells. By default a click clears the cell and everything to the right (`clear-on="focus"`); `clear-on="input"` replaces the digit only when typing. `format="#-##-##"` draws visual separators (not part of the value; a paste in that shape or as a clean code is split into cells). The last cell blurs and emits `complete`
52
- - **TaoSlider** — mouse, touch, and arrows. Optional precise input on right-click. `variant="thin"` is a thin track for seek / volume; `size` scales either track
53
- - **TaoFileDrop** — drop zone (drag & drop + click). File names listed under the zone, `v-model` is `File[]`. Clearing the whole batch is the parent’s job (`clear-request`)
54
-
55
- ### Data display
56
-
57
- - **TaoTable** — simple table: columns, empty, loading, sort via `v-model:sort`. `head` tints the header, `lines` draws row rules (both on by default). `striped` starts on the first row; `striped="even"` starts on the second. Not a datagrid.
58
- - **TaoPagination** — pages with ellipsis. Clicking “…” jumps `jump` pages (5 by default)
59
- - **TaoEmpty** — empty list, no results, no access
60
- - **TaoList** / **TaoListItem** — list row: icon, title, caption, hover action. Not Select, not a table
61
- - **TaoStages** — stage list: `wait` / `work` / `ok` / `bad`. Not a linear stepper
62
- - **TaoSkeleton** — loading placeholder (text / title / circle / rect)
63
- - **TaoCounter** — flipping digits (not an input)
64
- - **TaoCarousel** — strip: full slide with `autoplay`, card with `peek`, row with `per-view`. Arrows via `controls` or `#prev` / `#next`, dots via `dots`
65
- - **TaoAvatar** — photo or initials, sizes `small` / `medium` / `large`. Status `dot` and `count`
66
- - **TaoTag** — badge with tones. `#prefix` (avatar), `closable` dismisses the chip, `flat` drops the border
67
- - **TaoAlert** — inline page/form banner (success / error / warning / info)
68
- - **TaoProgress** — static bar (`progress` in %). Percent centered on top, or `showPercentage="right"`; `#left` / `#right` slots are captions, then the percent sits in parentheses on the right. `false` hides it. Width is `minWidth` / `maxWidth`, not the value domain
69
- - **TaoLoader** — four-dot spinner
70
- - **TaoImage** — `<img>` wrapper: fade-in and placeholder. `lazy` turns on native `loading="lazy"`
71
- - **TaoIcon** — icon-font wrapper (see Icons below)
72
-
73
- ### Navigation
74
-
75
- - **TaoLink** — `<NuxtLink>` in Nuxt, `<RouterLink>` with vue-router, otherwise a plain `<a>` — no extra setup
76
- - **TaoBreadcrumb** — crumbs: the last item is the current page
77
- - **TaoDropdownMenu** — dropdown that flips at the viewport edge
78
- - **TaoScrollTop** — floating “back to top” with a ripple. Appears on reverse scroll after `boundary`
79
-
80
- ### Feedback
81
-
82
- - **toast()** — fluent toasts: `toast().success().message('Saved')`
83
- - **confirm()** — overlay question: the same fluent API plus `await`. Not a toast — it waits for an answer and does not dismiss itself.
84
- - **TaoToastViewport** / **TaoConfirmHost** — hosts; if they are missing from the tree, the first call mounts them on `body`
85
-
86
- ## Conventions
87
-
88
- Visual tones: `success` | `danger` | `warning` | `info` | `neutral` (type `TaoTone`), always the `tone` prop: Button, Alert, Tag. `type` on Alert / Tag is a deprecated alias.
89
- `error` on Alert, Tag, and `toast()` is an alias of `danger`. Button already uses `danger`.
90
- Stages describe a process, not a tone: `wait` / `work` / `ok` / `bad` (`danger` is accepted as `bad`).
91
-
92
- Control sizes: `small` | `medium` | `large` (type `TaoSize`). One scale for Button, Input, InputNumber, Quantity, Textarea, Select, Combobox, Date, DateRange, Segmented, InputGroup and FormField — controls of one size line up in a row. Checkbox, Radio / RadioGroup and Switch scale the indicator (14 / 18 / 22px) and the label; Tag scales its height (18 / 20 / 24px); Tabs, Pagination buttons and List rows take the Button height; Table scales cell padding (`size="small"` replaces `compact`); FileDrop scales the zone and file rows; Slider scales the track and thumb.
93
- Without `size` a control takes the size of its ancestors, `medium` at the root. Set it for a whole block with the class `tao-size-small` / `-medium` / `-large` on any element, or with `size` on `TaoFormField` / `TaoInputGroup`. An explicit `size` on a control wins.
94
-
95
- ```vue
96
- <div class="tao-size-small">
97
- <TaoInput v-model="q" />
98
- <TaoButton>Find</TaoButton>
99
- </div>
100
- ```
101
-
102
- Content and layout keep their own scale and do not inherit: Avatar (24 / 32 / 48px; `s` / `m` / `l` are deprecated), Divider `gap` (`big` is a deprecated alias of `large`), Loader / Icon / ScrollTop (pixels).
103
- Container lives on another axis — width: `width="wide" | "slim" | "ultra-slim"` (`size` is a deprecated alias).
104
-
105
- Surfaces — what a panel is made of: `flat` fill (default), `grain` (static film grain), `glass` (translucent, blurs what is
106
- behind). Use `surface` on TaoCard / TaoBlock or the class `tao-surface-grain` / `-glass` on any element — a game HUD, a
107
- landing section, a sidebar. Tune the look once with theme tokens (`--tao-surface-grain-image` / `-size`, `--tao-glass-fill`
108
- / `-border` / `-blur`). A surface belongs to one element: nested panels do not inherit it. Glass needs something behind
109
- it — keep it for things that float over content; over a flat background it is just a grey fill, over animation it is
110
- re-blurred every frame. Toast and confirm are glass by default, tinted by their tone; `toast.defaults({ surface: 'flat' })`
111
- and `confirm.defaults({ surface: 'flat' })` turn it off, `.surface('flat')` does it for one. Without blur support or with
112
- `prefers-reduced-transparency` glass falls back to a solid panel.
113
-
114
- Font size scale (primitives): `xs` 12 … `xl` 18 for controls; `2xl` 24, `3xl` 32, `4xl` 36 for titles and prose.
115
- There is no heading component — use `h1 { font-size: var(--tao-font-size-3xl) }`.
116
-
117
- API rules — every component follows them; old names stay as deprecated aliases:
118
-
119
- - **Fields** take `v-model`, `disabled`, `error` (red frame) and `size`. Label, hint and error text come from `TaoFormField`.
120
- - **Events**: `update:X` for v-model plus `change` when the user finished a change (Slider, Split — on release). Other events are verbs in the present tense: `select`, `close`, `create`.
121
- - **Texts**: visible ones are `*Text` (`clearText`, `successText`), screen-reader ones are `*Label` (`closeLabel`).
122
- - **Lists**: data arrays are `items`; selectable items carry `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Identifiers of plain data (table columns, stages) stay `key`.
123
- - **Booleans** are adjectives without `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Layout axis is `direction: 'row' | 'column'`, not `vertical`.
124
- - **Lengths** (`padding`, `radius`, `gap`, `maxHeight`): a number is pixels, a string goes to CSS as is (type `TaoLength`).
125
-
126
- ## Icons
127
-
128
- `TaoIcon` does not ship its own set — it renders `icon-<name>`
129
- for an external icon font (IcoMoon / Fontello and the like). Connect a font
130
- with classes such as `.icon-arrow-up { ... }` in the host app.
131
-
132
- ## Install
133
-
134
- ```bash
135
- npm install @1337exp/taoui
136
- ```
137
-
138
- From a local folder:
139
-
140
- ```bash
141
- npm install ../path-to-tao-ui
142
- ```
143
-
144
- ## Usage
145
-
146
- ### Nuxt 3
147
-
148
- Create `plugins/tao-ui.ts`:
149
-
150
- ```typescript
151
- import { defineNuxtPlugin } from '#app'
152
- import TaoUI from '@1337exp/taoui'
153
-
154
- export default defineNuxtPlugin((nuxtApp) => {
155
- nuxtApp.vueApp.use(TaoUI)
156
- })
157
- ```
158
-
159
- Import styles in `app.vue` or a layout:
160
-
161
- ```vue
162
- <script setup>
163
- import '@1337exp/taoui/styles.css'
164
- </script>
165
- ```
166
-
167
- ### Vue 3
168
-
169
- ```javascript
170
- // main.js
171
- import { createApp } from 'vue'
172
- import App from './App.vue'
173
- import TaoUI from '@1337exp/taoui'
174
- import '@1337exp/taoui/styles.css'
175
-
176
- const app = createApp(App)
177
- app.use(TaoUI)
178
- app.mount('#app')
179
- ```
180
-
181
- ### Language
182
-
183
- Built-in texts (placeholders, “Clear”, aria labels, dates) are Russian by default. English ships with the library:
184
-
185
- ```javascript
186
- import TaoUI, { localeEn } from '@1337exp/taoui'
187
-
188
- app.use(TaoUI, { locale: localeEn })
189
- ```
190
-
191
- Change single texts — the rest stays from the default:
192
-
193
- ```javascript
194
- app.use(TaoUI, { locale: { select: { placeholder: 'Pick one' } } })
195
- ```
196
-
197
- Another language: copy `localeEn`, translate, pass it the same way (type `TaoLocale`). Keys repeat prop names —
198
- `locale.select.placeholder` is the default of TaoSelect `placeholder`, and a prop passed by hand always wins.
199
-
200
- Switch the language at any moment — from your settings, a language picker, a route. Components already on the page
201
- update at once, without a reload and without losing what users typed:
202
-
203
- ```javascript
204
- import { setTaoLocale, localeEn, localeRu } from '@1337exp/taoui'
205
-
206
- function onLanguageChange(lang) {
207
- setTaoLocale(lang === 'en' ? localeEn : localeRu)
208
- }
209
- ```
210
-
211
- Without the plugin (individual components) `setTaoLocale()` is the only call you need.
212
-
213
- ### Upgrading from 1.x
214
-
215
- See [CHANGELOG.md](CHANGELOG.md): what broke, and a table of old names → new ones. Old names still work in 2.x and
216
- warn in the console during development.
217
-
218
- ### Individual components
219
-
220
- ```vue
221
- <script setup>
222
- import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
223
- import '@1337exp/taoui/styles.css'
224
- </script>
225
-
226
- <template>
227
- <TaoButton variant="primary">Press me</TaoButton>
228
- <TaoFormField label="Your text">
229
- <TaoInput v-model="text" />
230
- </TaoFormField>
231
- <TaoModal v-model="isOpen" title="Title">
232
- Modal body
233
- </TaoModal>
234
- </template>
235
- ```
236
-
237
- ## Split
238
-
239
- `TaoSplit` is two panes and a gutter. It is not `TaoDivider` (a line) and not an n-pane layout: three columns are two nested splits.
240
-
241
- `direction` matches Flex: `row` (start | end) or `column` (start above end). Slots are `#start` / `#end`.
242
-
243
- `v-model` is the start pane size. `unit` is `%` (default — the ratio survives a container resize) or `px` (a sidebar; the end pane takes the rest). With `px`, pass an explicit size — the default `50` is 50px. `min` / `max` apply to start; `min-end` is the other pane's floor; all three use the same unit. `resizable="false"` keeps the gutter but locks it.
244
-
245
- The split fills the parent (`width` / `height: 100%`). Give the parent a bounded size on the split axis — a `column` split without a height has no `%` to compute. Panes use `min-width` / `min-height: 0` and `overflow: hidden`, so content cannot block shrinking. Scroll belongs on an inner wrapper (`overflow: auto; height: 100%; min-height: 0`). A nested `TaoSplit` as a direct child of a pane stretches on its own.
246
-
247
- ```vue
248
- <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
249
- <template #start>Nav</template>
250
- <template #end>Main</template>
251
- </TaoSplit>
252
- ```
253
-
254
- ## Toast
255
-
256
- The chain runs in the same tick; `setTimeout(0)` actually shows the toast.
257
-
258
- ```javascript
259
- import { toast } from '@1337exp/taoui'
260
-
261
- toast().success().message('Saved')
262
- toast().error().title('Network').timeout(5000).message('No connection')
263
- toast.success('Saved')
264
- toast.warning('Draft', { timeout: 1000 })
265
- ```
266
-
267
- Default position is `topCenter`. Globally:
268
-
269
- ```javascript
270
- toast.defaults({ position: 'bottomRight' })
271
- toast.byBottomRight()
272
- ```
273
-
274
- There is no overlay `question` in this kit — that is confirm, not toast. Buttons on a toast, if needed:
275
-
276
- ```javascript
277
- toast().info().message('Delete the file?').action('Delete', onRemove)
278
- ```
279
-
280
- You can skip the viewport: the first call creates it. For explicit control (tests, a custom layout):
281
-
282
- ```vue
283
- <TaoToastViewport />
284
- ```
285
-
286
- ## Confirm
287
-
288
- An overlay question in the center of the screen. This is not a toast: no progress bar, no auto-close, `await`, Esc and overlay click = cancel.
289
-
290
- ```javascript
291
- import { confirm } from '@1337exp/taoui'
292
-
293
- if (await confirm().title('Delete the file?').message('This cannot be undone').danger()) {
294
- remove()
295
- }
296
-
297
- const ok = await confirm('Leave without saving?', {
298
- ok: 'Leave',
299
- cancel: 'Stay',
300
- })
301
- ```
302
-
303
- Queue: a second `confirm()` while the first is open will wait. Default labels are “OK” / “Cancel”:
304
-
305
- ```javascript
306
- confirm.defaults({ ok: 'Yes', cancel: 'No' })
307
- ```
308
-
309
- ## Forms
310
-
311
- `TaoFormField` attaches a shared label / hint / error and forwards `id` to the nested control.
312
-
313
- ```vue
314
- <TaoFormField label="City" hint="Optional">
315
- <TaoSelect v-model="city" :options="cities" />
316
- </TaoFormField>
317
-
318
- <TaoSwitch v-model="dark" label="Dark theme" />
319
-
320
- <TaoRadioGroup v-model="plan" legend="Plan">
321
- <TaoRadio value="free" label="Free" />
322
- <TaoRadio value="pro" label="Pro" />
323
- </TaoRadioGroup>
324
-
325
- <TaoSegmented v-model="period" legend="Period">
326
- <TaoSegmentedOption value="week">Week</TaoSegmentedOption>
327
- <TaoSegmentedOption value="month">Month</TaoSegmentedOption>
328
- <TaoSegmentedOption value="year">Year</TaoSegmentedOption>
329
- </TaoSegmented>
330
-
331
- <TaoAlert tone="warning" title="Draft">Save before you leave.</TaoAlert>
332
- ```
333
-
334
- `TaoSegmented` is a short exclusive choice with every option visible. It is not page navigation — that is `TaoTabs`. Longer labels or more than 5–6 items belong in `TaoRadioGroup` or `TaoSelect`.
335
-
336
- `TaoSelect` opens from the keyboard (arrows, Enter, Esc); the list flips at the viewport edge. Delete or “Clear” at the bottom of the list resets the value to `null`.
337
-
338
- When `null` is not a valid value (a grid step, a sort order), pass `:clearable="false"`: the clear row and the Delete / Backspace shortcut disappear. The clear row label is `clear-text`; for an icon or any markup use the `#clear` slot. `size` is `small` / `medium` / `large` (inherited from ancestors when not set) and also scales the open list.
339
-
340
- ```vue
341
- <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
342
-
343
- <TaoSelect v-model="city" :options="cities">
344
- <template #clear><TaoIcon name="close" /> Reset</template>
345
- </TaoSelect>
346
- ```
347
-
348
- `TaoCombobox` is the same menu with a field. Typing filters options. `allow-create` writes the typed string into `v-model` when there is no exact match. The list does not mutate itself: listen to `create` and append an option from the parent.
349
-
350
- Label, hint and error text always come from `TaoFormField`; `label` / `error-message` on `TaoInput` are deprecated. `TaoFormField` also wraps `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup`, and `TaoSegmented` — id, hint, and error are forwarded for you.
351
-
352
- `TaoTag` can be a chip: `#prefix` on the left (usually `TaoAvatar`), `closable` draws a cross and emits `close`. The close click does not bubble. `flat` drops the border and keeps the fill.
353
-
354
- ```vue
355
- <TaoTag tone="neutral" closable @close="remove">
356
- <template #prefix>
357
- <TaoAvatar name="Anna Kozlova" size="small" />
358
- </template>
359
- Anna Kozlova
360
- </TaoTag>
361
- ```
362
-
363
- ## Table and pagination
364
-
365
- The table renders what you pass in: it does not slice or sort the data. That works for both server-side and client-side paging — the page is cut outside.
366
-
367
- ```vue
368
- <TaoTable
369
- :columns="columns"
370
- :rows="pageRows"
371
- v-model:sort="sort"
372
- empty-text="No records yet"
373
- >
374
- <template #cell-status="{ row }">
375
- <TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
376
- {{ row.status }}
377
- </TaoTag>
378
- </template>
379
- </TaoTable>
380
-
381
- <TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
382
- ```
383
-
384
- ```javascript
385
- const columns = [
386
- { key: 'name', label: 'Name', sortable: true },
387
- { key: 'city', label: 'City' },
388
- { key: 'status', label: 'Status' },
389
- ]
390
- ```
391
-
392
- The `cell-<key>` slot replaces a cell. `loading` shows an overlay; an empty list shows text or the `#empty` slot. Clicking a `sortable` header cycles `asc → desc → off`.
393
-
394
- ## Empty states and loading
395
-
396
- ```vue
397
- <TaoEmpty title="Nothing found">
398
- Change the filter or reset search.
399
- <template #action>
400
- <TaoButton variant="secondary">Reset</TaoButton>
401
- </template>
402
- </TaoEmpty>
403
-
404
- <TaoSkeleton variant="title" />
405
- <TaoSkeleton :lines="3" />
406
- <TaoSkeleton variant="circle" />
407
-
408
- <TaoStages :items="[
409
- { key: 'pay', label: 'Payment', status: 'ok' },
410
- { key: 'pack', label: 'Packing', status: 'work' },
411
- { key: 'ship', label: 'Shipping', status: 'wait' },
412
- ]" />
413
-
414
- <TaoList>
415
- <TaoListItem
416
- title="Ann Kozlova"
417
- description="Design · Moscow"
418
- clickable
419
- :selected="picked === 'ann'"
420
- @click="picked = 'ann'"
421
- >
422
- <template #prefix>
423
- <TaoAvatar name="Ann Kozlova" size="small" />
424
- </template>
425
- </TaoListItem>
426
- </TaoList>
427
- ```
428
-
429
- ```vue
430
- <TaoInput v-model="q" placeholder="Search…">
431
- <template #prefix>⌕</template>
432
- </TaoInput>
433
-
434
- <TaoInputGroup>
435
- <template #before>https://</template>
436
- <TaoInput v-model="host" placeholder="example.com" />
437
- <template #after>
438
- <TaoButton>Check</TaoButton>
439
- </template>
440
- </TaoInputGroup>
441
-
442
- <form @submit.prevent="onSave">
443
- <TaoFormField label="Email">
444
- <TaoInput v-model="email" type="email" />
445
- </TaoFormField>
446
- <TaoButton type="submit">Save</TaoButton>
447
- </form>
448
-
449
- <TaoFormField label="Quantity">
450
- <TaoInputNumber v-model="qty" :min="1" :max="99" />
451
- </TaoFormField>
452
-
453
- <TaoQuantity v-model="qty" :max="12" @dec="onDec" />
454
-
455
- <TaoFormField label="Delivery day" hint="The model is always YYYY-MM-DD">
456
- <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
457
- </TaoFormField>
458
-
459
- <TaoFormField label="Stay">
460
- <TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
461
- </TaoFormField>
462
-
463
- <TaoCounter :value="score" :max-digits="6" />
464
-
465
- <TaoCarousel :autoplay="4000" loop dots>
466
- <article v-for="item in banners" :key="item.id" class="hero">
467
- <strong>{{ item.title }}</strong>
468
- <span>{{ item.text }}</span>
469
- </article>
470
- </TaoCarousel>
471
- <TaoCarousel :peek="72" :controls="false" dots>…</TaoCarousel>
472
- <TaoCarousel v-model="slide" :per-view="5" :peek="28">
473
- <template #prev></template>
474
- <template #next="{ go, disabled }">
475
- <button type="button" :disabled="disabled" @click="go">next</button>
476
- </template>
477
- <article v-for="item in products" :key="item.id">…</article>
478
- </TaoCarousel>
479
- ```
480
-
481
- `TaoDrawer` is a side sheet, not a centered modal:
482
-
483
- ```vue
484
- <TaoDrawer v-model="open" title="Filters">
485
- ...
486
- </TaoDrawer>
487
- ```
488
-
489
- ## Design tokens and theming
490
-
491
- Library styles are three layers. Components **never** touch raw colors or sizes —
492
- only semantic variables. That is the theming mechanism: override 20–30 variables
493
- and every component follows, with no edits inside the components themselves.
494
-
495
- ```
496
- primitives.css → semantic.css → themes/*.css (optional)
497
- raw colors public theming ready-made themes on top
498
- and scales, API: this is of semantic — light is
499
- leave them alone what you change the example
500
- ```
501
-
502
- ### Layers
503
-
504
- | File | Role | Touch it? |
505
- |---|---|---|
506
- | `primitives.css` | Raw palette, space / radius / shadow scales (`--tao-orange-400`, `--tao-space-3`…) | Usually no |
507
- | `semantic.css` | Default (dark) theme tokens: `--tao-color-accent`, `--tao-color-surface`, `--tao-color-danger`, etc. | **Yes — this is the theming API** |
508
- | `themes/light.css` | Alternate theme via `[data-tao-theme="light"]` | Yes, as a sample |
509
- | `base.css` | Global reset (scrollbar, links, box-sizing) | Rarely |
510
-
511
- All four come in through `@1337exp/taoui/styles.css`.
512
-
513
- ### Your own theme
514
-
515
- A theme is just semantic tokens under your selector.
516
- Nothing in the components needs to change:
517
-
518
- ```css
519
- /* my-brand-theme.css */
520
- [data-tao-theme="my-brand"] {
521
- --tao-color-accent: #6c5ce7;
522
- --tao-color-accent-hover: #5a4bd1;
523
- --tao-color-bg: #0f0f1a;
524
- --tao-color-surface: #0f0f1a;
525
- --tao-color-surface-raised: #1a1a2e;
526
- --tao-color-text: #d6d6e8;
527
- --tao-color-text-strong: #ffffff;
528
- /* remaining tokens: see semantic.css */
529
- }
530
- ```
531
-
532
- ```vue
533
- <!-- app.vue -->
534
- <template>
535
- <div data-tao-theme="my-brand">
536
- <NuxtPage />
537
- </div>
538
- </template>
539
- ```
540
-
541
- Or switch the theme on `<html>` so modals/tooltips teleported to `body` pick it up:
542
-
543
- ```javascript
544
- document.documentElement.setAttribute('data-tao-theme', 'light')
545
- ```
546
-
547
- ### Token groups
548
-
549
- - `--tao-color-accent*` — brand/accent (primary buttons, active tabs, links)
550
- - `--tao-color-on-accent` — text on the accent (`--tao-color-text-on-accent` is an alias)
551
- - `--tao-color-selection`, `--tao-color-selection-text` — text selection (`::selection`)
552
- - `--tao-color-surface*` — container backgrounds (default / raised / sunken / hover)
553
- - `--tao-color-border*` — borders
554
- - `--tao-color-text*` — text (default / strong / subtle / muted / disabled)
555
- - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — status colors
556
- - `--tao-color-input-*` — fields, because input bg/text often differs from surface/text
557
- - `--tao-radius-control`, `--tao-radius-panel` — radii (small controls vs large panels)
558
- - `--tao-shadow-panel`, `--tao-shadow-overlay` — shadows
559
- - `--tao-font-size-*` — type scale in `primitives.css`: `xs`–`xl` controls, `2xl`–`4xl` titles / prose
560
- - `--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-*` — the size scale in `primitives.css`. Components read the current values from `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`. Use them in your own controls to match the size around them. `--tao-field-height` is a deprecated alias of `--tao-control-height`
561
-
562
- The full list lives in `src/styles/semantic.css` — the only file worth opening
563
- to see the whole theming API.
564
-
565
- ### A theme from scratch, without primitives
566
-
567
- ```javascript
568
- import '@1337exp/taoui/styles/primitives.css' // keep the scales if you want
569
- import './my-semantic.css' // your semantic layer instead of @1337exp/taoui/styles/semantic.css
570
- import '@1337exp/taoui/styles/base.css'
571
- ```
572
-
573
- ## Showcase
574
-
575
- To browse every component:
576
-
577
- ```bash
578
- cd showcase
579
- npm install
580
- npm run dev
581
- ```
582
-
583
- The showcase has a dark / light switch in the header, so you can see token
584
- overrides without editing component code.
585
-
586
- The showcase points at `src/` directly, so component edits show up without
587
- `npm run build`. Building `dist/` is for publishing and for other projects
588
- that install the package.
589
-
590
- ## Development
591
-
592
- ```bash
593
- # Build the library
594
- npm run build
595
-
596
- # Watch mode
597
- npm run dev
598
-
599
- # Type check
600
- npm run type-check
601
-
602
- # Tests (Vitest)
603
- npm test
604
- ```
605
-
606
- ## Publishing to npm
607
-
608
- Only `dist/` (the built library) and `src/styles/` (raw tokens, so you can
609
- import `primitives.css` on its own for a custom theme) are published.
610
- Component sources (`src/components/*.vue`), build configs, and `showcase/`
611
- stay in the repo — clone it to get them.
612
-
613
- `npm publish` **itself** runs the type check and a full rebuild first
614
- (`prepublishOnly` in `package.json`), so a stale or missing `dist/` cannot
615
- reach the registry. You do not need to build by hand before `npm publish`.
616
-
617
- See what would go into the tarball, without publishing:
618
-
619
- ```bash
620
- npm pack --dry-run
621
- ```
622
-
623
- ## License
624
-
625
- MIT
1
+ <h1 align="center">Tao UI</h1>
2
+
3
+ <p align="center">
4
+ <b>A Vue 3 component library driven by design tokens.</b><br>
5
+ Change a handful of CSS variables and the whole kit follows.
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
+ <b>English</b> · <a href="https://github.com/1337exp/taoui/blob/master/README.ru.md">Русский</a> ·
18
+ <a href="#install">Install</a> ·
19
+ <a href="#showcase">Showcase</a> ·
20
+ <a href="CHANGELOG.md">Changelog</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 components in the dark theme" width="860">
25
+ </p>
26
+
27
+ ## Why Tao UI
28
+
29
+ - **Tokens first.** Colours, radii, spacing and type come from CSS variables in three layers (primitives, semantic, theme). Re-theme the kit, or one panel of it, without touching a component.
30
+ - **One scale, one API.** `small` / `medium` / `large` everywhere, the same `v-model` / `change` / `*Text` / `*Label` rules for every field, tones instead of ad-hoc colours.
31
+ - **Dark and light** out of the box, plus surfaces (`flat` / `grain` / `glass`) for HUDs and landing pages.
32
+ - **Built-in languages.** Placeholders, dates and aria labels in English and Russian, switchable at runtime without a reload.
33
+ - **Nuxt and plain Vue.** `TaoLink` picks `NuxtLink`, `RouterLink` or `<a>` by itself. Fully typed, ES and CJS builds.
34
+ - **Keyboard friendly.** Focus traps, `role` / `aria-*` on the controls.
35
+
36
+ <table>
37
+ <tr>
38
+ <td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/color-picker.webp" alt="TaoColorPicker: square, hue strip, HEX / RGB / HSL modes"><br><sub><b>TaoColorPicker</b> — HEX / RGB / HSL, eyedropper, <code>v-model</code> is a hex string</sub></td>
39
+ <td width="50%"><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/themes.webp" alt="Dark and light themes switching"><br><sub><b>Themes</b> — one attribute, every component follows</sub></td>
40
+ </tr>
41
+ <tr>
42
+ <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/clips/slider.webp" alt="TaoRangeSlider with marks"><br><sub><b>TaoSlider / TaoRangeSlider</b> — marks, discrete scales, vertical</sub></td>
43
+ <td><img src="https://raw.githubusercontent.com/1337exp/taoui/master/docs/media/screenshots/surfaces-dark.webp" alt="flat, grain and glass surfaces"><br><sub><b>Surfaces</b> — flat, grain, glass</sub></td>
44
+ </tr>
45
+ </table>
46
+
47
+ ## Components
48
+
49
+ ### Basics
50
+
51
+ - **TaoBlock** — container with padding and radius
52
+ - **TaoButton** — `primary` / `secondary` / `ghost` / `text` / `danger`. `tone` tints ghost and text (danger, success, warning, info, neutral)
53
+ - **TaoCard** — card with cover / header / footer slots. `#cover` can be a photo or `TaoCarousel`. `flush` is a tile (no padding/shadow, fills the cell); `#overlay` is a scrim on the cover
54
+ - **TaoCopy** — clipboard icon. After a click, a “Copied” tooltip; if the trigger is gone, the tooltip is too
55
+ - **TaoInput** — text field with v-model, validation, and `#prefix` / `#suffix` slots (icon or text inside the frame)
56
+ - **TaoInputGroup** — outer glue: `#before` | field | `#after` (protocol, unit, button)
57
+ - **TaoModal** — modal with animation and slots
58
+ - **TaoDrawer** — side panel (filters, settings). Esc, backdrop click, focus trap — same as the modal
59
+ - **TaoSpoiler** — disclosure. `v-model` and `aria-expanded`. Neighbours do not close each other
60
+ - **TaoSpoilerGroup** — accordion: `v-model` is the open panel key (`null` = all closed); spoilers take `name`. Without `v-model` the group keeps that key itself
61
+ - **TaoTabs** — tabbed sections
62
+ - **TaoTooltip** — hover hint. `top` / `bottom` / `left` / `right`, flips at the viewport edge
63
+ - **TaoPopover** — click panel with any slot content, Esc and outside click. Not a tooltip, not an action menu
64
+
65
+ ### Layout
66
+
67
+ - **TaoContainer** — max-width (wide / slim / ultra-slim) and centering
68
+ - **TaoFlex** — flexbox wrapper: justify / align / direction / wrap / gap
69
+ - **TaoSpace** — even gap between children
70
+ - **TaoGrid** / **TaoGridItem** — tiles: `min` is a catalog (auto-fill), `cols` is bento. Item `col` / `row` span; below ~560px span resets. Not masonry
71
+ - **TaoDivider** — `solid` (plain border) / `dashed` / `colored` (accent) / `gap`. Optional `text` sits in the middle of any of them; `fade` softens the line ends; `size` is for `gap` (small / medium / large)
72
+ - **TaoSplit** — two panes and a gutter. `row` / `column` like Flex. `v-model` is the start size in `%` or `px`; `resizable="false"` locks the gutter. Not Divider.
73
+ - **TaoFieldset** — grouped frame: `legend` sits on the top border, `align` is start / center / end
74
+ - **TaoAnimatedBorder** — rainbow border wrapper (decorative, not tied to the theme)
75
+
76
+ ### Forms
77
+
78
+ - **TaoCheckbox** — checkbox with v-model, pre/post slots, and `indeterminate`
79
+ - **TaoSwitch** — boolean toggle (`role="switch"`)
80
+ - **TaoRadio** / **TaoRadioGroup** — classic radios: longer labels, can stack vertically
81
+ - **TaoSegmented** / **TaoSegmentedOption** — compact exclusive choice among 2–5 short options. Not tabs
82
+ - **TaoSelect** — dropdown with keyboard, same chrome as Input. `size` (`small` / `medium` / `large`, same scale as Button). Clear via “Clear” in the list or Delete; `clearable="false"` turns clearing off, `#clear` replaces the row content
83
+ - **TaoCombobox** — Select with a field: type to filter, `allow-create` writes a custom value into `v-model`, `create` lets the parent append the list. Takes the same `size`, `clearable` and `#clear` as `TaoSelect`
84
+ - **TaoDate** — a single day: `YYYY-MM-DD`, no time, no timezone. Calendar popup like Select
85
+ - **TaoDateRange** — a period: `v-model` is `{ start, end }` or `null`. First click is start, second is end (they swap if end is earlier). An incomplete pick is not written to the model
86
+ - **TaoFormField** — shared label / hint / error for form controls
87
+ - **TaoInputNumber** — number with min/max/step and ± on the right. Empty value is `null`. `@commit` fires once when an edit is finished (blur, Enter, ±, arrow), unlike `v-model`, which updates on every keystroke
88
+ - **TaoQuantity** — cart quantity: `− | field | +`, integers, stock; minus at the minimum can remove the row
89
+ - **TaoTextarea** — autosizing multiline. `maxlength` caps input, `count` shows “entered / max”. `variant`: `bar` (default) / `outline` (frame like Input) / `filled` / `plain`; `readonly`. `noBorder`, `noBackground`, `borderInverse`, `dummy` are deprecated
90
+ - **TaoPinCode** — N cells. By default a click clears the cell and everything to the right (`clear-on="focus"`); `clear-on="input"` replaces the digit only when typing. `format="#-##-##"` draws visual separators (not part of the value; a paste in that shape or as a clean code is split into cells). The last cell blurs and emits `complete`
91
+ - **TaoSlider** / **TaoRangeSlider** — one thumb (`v-model` is a number) or two (`[from, to]`, `minGap`). Mouse, touch, arrows. `marks` (ticks, numbers, `{ value, label }`), `discrete` for stepped scales, `vertical`, `flat`, `format`; `variant="thin"` is a thin track for seek / volume
92
+ - **TaoColorPicker** — saturation / brightness square, hue and opacity strips, swatches, eyedropper (where the browser has `EyeDropper`), HEX / RGB / HSL input modes. `v-model` is a hex string; `colorModel()` adapts your own colour storage
93
+ - **TaoColorInput** — a field with a swatch and the hex text; the picker opens in a popover
94
+ - **TaoFileDrop** — drop zone (drag & drop + click). File names listed under the zone, `v-model` is `File[]`. Clearing the whole batch is the parent’s job (`clear-request`)
95
+
96
+ ### Data display
97
+
98
+ - **TaoTable** — simple table: columns, empty, loading, sort via `v-model:sort`. `head` tints the header, `lines` draws row rules (both on by default). `striped` starts on the first row; `striped="even"` starts on the second. Not a datagrid.
99
+ - **TaoPagination** — pages with ellipsis. Clicking “…” jumps `jump` pages (5 by default)
100
+ - **TaoEmpty** — empty list, no results, no access
101
+ - **TaoList** / **TaoListItem** — list row: icon, title, caption, hover action. Not Select, not a table
102
+ - **TaoStages** — stage list: `wait` / `work` / `ok` / `bad`. Not a linear stepper
103
+ - **TaoSkeleton** — loading placeholder (text / title / circle / rect)
104
+ - **TaoCounter** — flipping digits (not an input)
105
+ - **TaoCarousel** — strip: full slide with `autoplay`, card with `peek`, row with `per-view`. Arrows via `controls` or `#prev` / `#next`, dots via `dots`
106
+ - **TaoAvatar** — photo or initials, sizes `small` / `medium` / `large`. Status `dot` and `count`
107
+ - **TaoTag** — badge with tones. `#prefix` (avatar), `closable` dismisses the chip, `flat` drops the border
108
+ - **TaoAlert** — inline page/form banner (success / error / warning / info)
109
+ - **TaoProgress** — static bar (`progress` in %). Percent centered on top, or `showPercentage="right"`; `#left` / `#right` slots are captions, then the percent sits in parentheses on the right. `false` hides it. Width is `minWidth` / `maxWidth`, not the value domain
110
+ - **TaoTimeline** — play / pause, a slider over time with event marks, a “time / length” label. Does not advance time by itself: drive `v-model` with your own clock
111
+ - **TaoLoader** — four-dot spinner
112
+ - **TaoImage** — `<img>` wrapper: fade-in and placeholder. `lazy` turns on native `loading="lazy"`
113
+ - **TaoIcon** — icon-font wrapper (see Icons below)
114
+
115
+ ### Navigation
116
+
117
+ - **TaoLink** — `<NuxtLink>` in Nuxt, `<RouterLink>` with vue-router, otherwise a plain `<a>` — no extra setup
118
+ - **TaoBreadcrumb** — crumbs: the last item is the current page
119
+ - **TaoDropdownMenu** — dropdown that flips at the viewport edge
120
+ - **TaoScrollTop** — floating “back to top” with a ripple. Appears on reverse scroll after `boundary`
121
+
122
+ ### Feedback
123
+
124
+ - **toast()** — fluent toasts: `toast().success().message('Saved')`
125
+ - **confirm()** — overlay question: the same fluent API plus `await`. Not a toast — it waits for an answer and does not dismiss itself.
126
+ - **TaoToastViewport** / **TaoConfirmHost** — hosts; if they are missing from the tree, the first call mounts them on `body`
127
+
128
+ ## Conventions
129
+
130
+ Visual tones: `success` | `danger` | `warning` | `info` | `neutral` (type `TaoTone`), always the `tone` prop: Button, Alert, Tag. `type` on Alert / Tag is a deprecated alias.
131
+ `error` on Alert, Tag, and `toast()` is an alias of `danger`. Button already uses `danger`.
132
+ Stages describe a process, not a tone: `wait` / `work` / `ok` / `bad` (`danger` is accepted as `bad`).
133
+
134
+ Control sizes: `small` | `medium` | `large` (type `TaoSize`). One scale for Button, Input, InputNumber, Quantity, Textarea, Select, Combobox, Date, DateRange, Segmented, InputGroup and FormField — controls of one size line up in a row. Checkbox, Radio / RadioGroup and Switch scale the indicator (14 / 18 / 22px) and the label; Tag scales its height (18 / 20 / 24px); Tabs, Pagination buttons and List rows take the Button height; Table scales cell padding (`size="small"` replaces `compact`); FileDrop scales the zone and file rows; Slider scales the track and thumb.
135
+ Without `size` a control takes the size of its ancestors, `medium` at the root. Set it for a whole block with the class `tao-size-small` / `-medium` / `-large` on any element, or with `size` on `TaoFormField` / `TaoInputGroup`. An explicit `size` on a control wins.
136
+
137
+ ```vue
138
+ <div class="tao-size-small">
139
+ <TaoInput v-model="q" />
140
+ <TaoButton>Find</TaoButton>
141
+ </div>
142
+ ```
143
+
144
+ Content and layout keep their own scale and do not inherit: Avatar (24 / 32 / 48px; `s` / `m` / `l` are deprecated), Divider `gap` (`big` is a deprecated alias of `large`), Loader / Icon / ScrollTop (pixels).
145
+ Container lives on another axis — width: `width="wide" | "slim" | "ultra-slim"` (`size` is a deprecated alias).
146
+
147
+ Surfaces — what a panel is made of: `flat` fill (default), `grain` (static film grain), `glass` (translucent, blurs what is
148
+ behind). Use `surface` on TaoCard / TaoBlock or the class `tao-surface-grain` / `-glass` on any element — a game HUD, a
149
+ landing section, a sidebar. Tune the look once with theme tokens (`--tao-surface-grain-image` / `-size`, `--tao-glass-fill`
150
+ / `-border` / `-blur`). A surface belongs to one element: nested panels do not inherit it. Glass needs something behind
151
+ it — keep it for things that float over content; over a flat background it is just a grey fill, over animation it is
152
+ re-blurred every frame. Toast and confirm are glass by default, tinted by their tone; `toast.defaults({ surface: 'flat' })`
153
+ and `confirm.defaults({ surface: 'flat' })` turn it off, `.surface('flat')` does it for one. Without blur support or with
154
+ `prefers-reduced-transparency` glass falls back to a solid panel.
155
+
156
+ Font size scale (primitives): `xs` 12 … `xl` 18 for controls; `2xl` 24, `3xl` 32, `4xl` 36 for titles and prose.
157
+ There is no heading component — use `h1 { font-size: var(--tao-font-size-3xl) }`.
158
+
159
+ API rules — every component follows them; old names stay as deprecated aliases:
160
+
161
+ - **Fields** take `v-model`, `disabled`, `error` (red frame) and `size`. Label, hint and error text come from `TaoFormField`.
162
+ - **Events**: `update:X` for v-model plus `change` when the user finished a change (Slider, Split — on release). Other events are verbs in the present tense: `select`, `close`, `create`.
163
+ - **Texts**: visible ones are `*Text` (`clearText`, `successText`), screen-reader ones are `*Label` (`closeLabel`).
164
+ - **Lists**: data arrays are `items`; selectable items carry `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Identifiers of plain data (table columns, stages) stay `key`.
165
+ - **Booleans** are adjectives without `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Layout axis is `direction: 'row' | 'column'`, not `vertical`.
166
+ - **Lengths** (`padding`, `radius`, `gap`, `maxHeight`): a number is pixels, a string goes to CSS as is (type `TaoLength`).
167
+
168
+ ## Icons
169
+
170
+ `TaoIcon` does not ship its own set — it renders `icon-<name>`
171
+ for an external icon font (IcoMoon / Fontello and the like). Connect a font
172
+ with classes such as `.icon-arrow-up { ... }` in the host app.
173
+
174
+ ## Install
175
+
176
+ ```bash
177
+ npm install @1337exp/taoui
178
+ ```
179
+
180
+ From a local folder:
181
+
182
+ ```bash
183
+ npm install ../path-to-tao-ui
184
+ ```
185
+
186
+ ## Usage
187
+
188
+ ### Nuxt 3
189
+
190
+ Create `plugins/tao-ui.ts`:
191
+
192
+ ```typescript
193
+ import { defineNuxtPlugin } from '#app'
194
+ import TaoUI from '@1337exp/taoui'
195
+
196
+ export default defineNuxtPlugin((nuxtApp) => {
197
+ nuxtApp.vueApp.use(TaoUI)
198
+ })
199
+ ```
200
+
201
+ Import styles in `app.vue` or a layout:
202
+
203
+ ```vue
204
+ <script setup>
205
+ import '@1337exp/taoui/styles.css'
206
+ </script>
207
+ ```
208
+
209
+ ### Vue 3
210
+
211
+ ```javascript
212
+ // main.js
213
+ import { createApp } from 'vue'
214
+ import App from './App.vue'
215
+ import TaoUI from '@1337exp/taoui'
216
+ import '@1337exp/taoui/styles.css'
217
+
218
+ const app = createApp(App)
219
+ app.use(TaoUI)
220
+ app.mount('#app')
221
+ ```
222
+
223
+ ### Language
224
+
225
+ Built-in texts (placeholders, “Clear”, aria labels, dates) are Russian by default. English ships with the library:
226
+
227
+ ```javascript
228
+ import TaoUI, { localeEn } from '@1337exp/taoui'
229
+
230
+ app.use(TaoUI, { locale: localeEn })
231
+ ```
232
+
233
+ Change single texts — the rest stays from the default:
234
+
235
+ ```javascript
236
+ app.use(TaoUI, { locale: { select: { placeholder: 'Pick one' } } })
237
+ ```
238
+
239
+ Another language: copy `localeEn`, translate, pass it the same way (type `TaoLocale`). Keys repeat prop names —
240
+ `locale.select.placeholder` is the default of TaoSelect `placeholder`, and a prop passed by hand always wins.
241
+
242
+ Switch the language at any moment — from your settings, a language picker, a route. Components already on the page
243
+ update at once, without a reload and without losing what users typed:
244
+
245
+ ```javascript
246
+ import { setTaoLocale, localeEn, localeRu } from '@1337exp/taoui'
247
+
248
+ function onLanguageChange(lang) {
249
+ setTaoLocale(lang === 'en' ? localeEn : localeRu)
250
+ }
251
+ ```
252
+
253
+ Without the plugin (individual components) `setTaoLocale()` is the only call you need.
254
+
255
+ ### Upgrading from 1.x
256
+
257
+ See [CHANGELOG.md](CHANGELOG.md): what broke, and a table of old names → new ones. Old names still work in 2.x and
258
+ warn in the console during development.
259
+
260
+ ### Individual components
261
+
262
+ ```vue
263
+ <script setup>
264
+ import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
265
+ import '@1337exp/taoui/styles.css'
266
+ </script>
267
+
268
+ <template>
269
+ <TaoButton variant="primary">Press me</TaoButton>
270
+ <TaoFormField label="Your text">
271
+ <TaoInput v-model="text" />
272
+ </TaoFormField>
273
+ <TaoModal v-model="isOpen" title="Title">
274
+ Modal body
275
+ </TaoModal>
276
+ </template>
277
+ ```
278
+
279
+ ## Split
280
+
281
+ `TaoSplit` is two panes and a gutter. It is not `TaoDivider` (a line) and not an n-pane layout: three columns are two nested splits.
282
+
283
+ `direction` matches Flex: `row` (start | end) or `column` (start above end). Slots are `#start` / `#end`.
284
+
285
+ `v-model` is the start pane size. `unit` is `%` (default — the ratio survives a container resize) or `px` (a sidebar; the end pane takes the rest). With `px`, pass an explicit size — the default `50` is 50px. `min` / `max` apply to start; `min-end` is the other pane's floor; all three use the same unit. `resizable="false"` keeps the gutter but locks it.
286
+
287
+ The split fills the parent (`width` / `height: 100%`). Give the parent a bounded size on the split axis — a `column` split without a height has no `%` to compute. Panes use `min-width` / `min-height: 0` and `overflow: hidden`, so content cannot block shrinking. Scroll belongs on an inner wrapper (`overflow: auto; height: 100%; min-height: 0`). A nested `TaoSplit` as a direct child of a pane stretches on its own.
288
+
289
+ ```vue
290
+ <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
291
+ <template #start>Nav</template>
292
+ <template #end>Main</template>
293
+ </TaoSplit>
294
+ ```
295
+
296
+ ## Toast
297
+
298
+ The chain runs in the same tick; `setTimeout(0)` actually shows the toast.
299
+
300
+ ```javascript
301
+ import { toast } from '@1337exp/taoui'
302
+
303
+ toast().success().message('Saved')
304
+ toast().error().title('Network').timeout(5000).message('No connection')
305
+ toast.success('Saved')
306
+ toast.warning('Draft', { timeout: 1000 })
307
+ ```
308
+
309
+ Default position is `topCenter`. Globally:
310
+
311
+ ```javascript
312
+ toast.defaults({ position: 'bottomRight' })
313
+ toast.byBottomRight()
314
+ ```
315
+
316
+ There is no overlay `question` in this kit — that is confirm, not toast. Buttons on a toast, if needed:
317
+
318
+ ```javascript
319
+ toast().info().message('Delete the file?').action('Delete', onRemove)
320
+ ```
321
+
322
+ You can skip the viewport: the first call creates it. For explicit control (tests, a custom layout):
323
+
324
+ ```vue
325
+ <TaoToastViewport />
326
+ ```
327
+
328
+ ## Confirm
329
+
330
+ An overlay question in the center of the screen. This is not a toast: no progress bar, no auto-close, `await`, Esc and overlay click = cancel.
331
+
332
+ ```javascript
333
+ import { confirm } from '@1337exp/taoui'
334
+
335
+ if (await confirm().title('Delete the file?').message('This cannot be undone').danger()) {
336
+ remove()
337
+ }
338
+
339
+ const ok = await confirm('Leave without saving?', {
340
+ ok: 'Leave',
341
+ cancel: 'Stay',
342
+ })
343
+ ```
344
+
345
+ Queue: a second `confirm()` while the first is open will wait. Default labels are “OK” / “Cancel”:
346
+
347
+ ```javascript
348
+ confirm.defaults({ ok: 'Yes', cancel: 'No' })
349
+ ```
350
+
351
+ ## Forms
352
+
353
+ `TaoFormField` attaches a shared label / hint / error and forwards `id` to the nested control.
354
+
355
+ ```vue
356
+ <TaoFormField label="City" hint="Optional">
357
+ <TaoSelect v-model="city" :options="cities" />
358
+ </TaoFormField>
359
+
360
+ <TaoSwitch v-model="dark" label="Dark theme" />
361
+
362
+ <TaoRadioGroup v-model="plan" legend="Plan">
363
+ <TaoRadio value="free" label="Free" />
364
+ <TaoRadio value="pro" label="Pro" />
365
+ </TaoRadioGroup>
366
+
367
+ <TaoSegmented v-model="period" legend="Period">
368
+ <TaoSegmentedOption value="week">Week</TaoSegmentedOption>
369
+ <TaoSegmentedOption value="month">Month</TaoSegmentedOption>
370
+ <TaoSegmentedOption value="year">Year</TaoSegmentedOption>
371
+ </TaoSegmented>
372
+
373
+ <TaoAlert tone="warning" title="Draft">Save before you leave.</TaoAlert>
374
+ ```
375
+
376
+ `TaoSegmented` is a short exclusive choice with every option visible. It is not page navigation — that is `TaoTabs`. Longer labels or more than 5–6 items belong in `TaoRadioGroup` or `TaoSelect`.
377
+
378
+ `TaoSelect` opens from the keyboard (arrows, Enter, Esc); the list flips at the viewport edge. Delete or “Clear” at the bottom of the list resets the value to `null`.
379
+
380
+ When `null` is not a valid value (a grid step, a sort order), pass `:clearable="false"`: the clear row and the Delete / Backspace shortcut disappear. The clear row label is `clear-text`; for an icon or any markup use the `#clear` slot. `size` is `small` / `medium` / `large` (inherited from ancestors when not set) and also scales the open list.
381
+
382
+ ```vue
383
+ <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
384
+
385
+ <TaoSelect v-model="city" :options="cities">
386
+ <template #clear><TaoIcon name="close" /> Reset</template>
387
+ </TaoSelect>
388
+ ```
389
+
390
+ `TaoCombobox` is the same menu with a field. Typing filters options. `allow-create` writes the typed string into `v-model` when there is no exact match. The list does not mutate itself: listen to `create` and append an option from the parent.
391
+
392
+ Label, hint and error text always come from `TaoFormField`; `label` / `error-message` on `TaoInput` are deprecated. `TaoFormField` also wraps `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup`, and `TaoSegmented` — id, hint, and error are forwarded for you.
393
+
394
+ `TaoTag` can be a chip: `#prefix` on the left (usually `TaoAvatar`), `closable` draws a cross and emits `close`. The close click does not bubble. `flat` drops the border and keeps the fill.
395
+
396
+ ```vue
397
+ <TaoTag tone="neutral" closable @close="remove">
398
+ <template #prefix>
399
+ <TaoAvatar name="Anna Kozlova" size="small" />
400
+ </template>
401
+ Anna Kozlova
402
+ </TaoTag>
403
+ ```
404
+
405
+ ## Table and pagination
406
+
407
+ The table renders what you pass in: it does not slice or sort the data. That works for both server-side and client-side paging — the page is cut outside.
408
+
409
+ ```vue
410
+ <TaoTable
411
+ :columns="columns"
412
+ :rows="pageRows"
413
+ v-model:sort="sort"
414
+ empty-text="No records yet"
415
+ >
416
+ <template #cell-status="{ row }">
417
+ <TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
418
+ {{ row.status }}
419
+ </TaoTag>
420
+ </template>
421
+ </TaoTable>
422
+
423
+ <TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
424
+ ```
425
+
426
+ ```javascript
427
+ const columns = [
428
+ { key: 'name', label: 'Name', sortable: true },
429
+ { key: 'city', label: 'City' },
430
+ { key: 'status', label: 'Status' },
431
+ ]
432
+ ```
433
+
434
+ The `cell-<key>` slot replaces a cell. `loading` shows an overlay; an empty list shows text or the `#empty` slot. Clicking a `sortable` header cycles `asc → desc → off`.
435
+
436
+ ## Empty states and loading
437
+
438
+ ```vue
439
+ <TaoEmpty title="Nothing found">
440
+ Change the filter or reset search.
441
+ <template #action>
442
+ <TaoButton variant="secondary">Reset</TaoButton>
443
+ </template>
444
+ </TaoEmpty>
445
+
446
+ <TaoSkeleton variant="title" />
447
+ <TaoSkeleton :lines="3" />
448
+ <TaoSkeleton variant="circle" />
449
+
450
+ <TaoStages :items="[
451
+ { key: 'pay', label: 'Payment', status: 'ok' },
452
+ { key: 'pack', label: 'Packing', status: 'work' },
453
+ { key: 'ship', label: 'Shipping', status: 'wait' },
454
+ ]" />
455
+
456
+ <TaoList>
457
+ <TaoListItem
458
+ title="Ann Kozlova"
459
+ description="Design · Moscow"
460
+ clickable
461
+ :selected="picked === 'ann'"
462
+ @click="picked = 'ann'"
463
+ >
464
+ <template #prefix>
465
+ <TaoAvatar name="Ann Kozlova" size="small" />
466
+ </template>
467
+ </TaoListItem>
468
+ </TaoList>
469
+ ```
470
+
471
+ ```vue
472
+ <TaoInput v-model="q" placeholder="Search…">
473
+ <template #prefix>⌕</template>
474
+ </TaoInput>
475
+
476
+ <TaoInputGroup>
477
+ <template #before>https://</template>
478
+ <TaoInput v-model="host" placeholder="example.com" />
479
+ <template #after>
480
+ <TaoButton>Check</TaoButton>
481
+ </template>
482
+ </TaoInputGroup>
483
+
484
+ <form @submit.prevent="onSave">
485
+ <TaoFormField label="Email">
486
+ <TaoInput v-model="email" type="email" />
487
+ </TaoFormField>
488
+ <TaoButton type="submit">Save</TaoButton>
489
+ </form>
490
+
491
+ <TaoFormField label="Quantity">
492
+ <TaoInputNumber v-model="qty" :min="1" :max="99" />
493
+ </TaoFormField>
494
+
495
+ <TaoQuantity v-model="qty" :max="12" @dec="onDec" />
496
+
497
+ <TaoFormField label="Delivery day" hint="The model is always YYYY-MM-DD">
498
+ <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
499
+ </TaoFormField>
500
+
501
+ <TaoFormField label="Stay">
502
+ <TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
503
+ </TaoFormField>
504
+
505
+ <TaoCounter :value="score" :max-digits="6" />
506
+
507
+ <TaoCarousel :autoplay="4000" loop dots>
508
+ <article v-for="item in banners" :key="item.id" class="hero">
509
+ <strong>{{ item.title }}</strong>
510
+ <span>{{ item.text }}</span>
511
+ </article>
512
+ </TaoCarousel>
513
+ <TaoCarousel :peek="72" :controls="false" dots>…</TaoCarousel>
514
+ <TaoCarousel v-model="slide" :per-view="5" :peek="28">
515
+ <template #prev></template>
516
+ <template #next="{ go, disabled }">
517
+ <button type="button" :disabled="disabled" @click="go">next</button>
518
+ </template>
519
+ <article v-for="item in products" :key="item.id">…</article>
520
+ </TaoCarousel>
521
+ ```
522
+
523
+ `TaoDrawer` is a side sheet, not a centered modal:
524
+
525
+ ```vue
526
+ <TaoDrawer v-model="open" title="Filters">
527
+ ...
528
+ </TaoDrawer>
529
+ ```
530
+
531
+ ## Design tokens and theming
532
+
533
+ Library styles are three layers. Components **never** touch raw colors or sizes —
534
+ only semantic variables. That is the theming mechanism: override 20–30 variables
535
+ and every component follows, with no edits inside the components themselves.
536
+
537
+ ```
538
+ primitives.css → semantic.css → themes/*.css (optional)
539
+ raw colors public theming ready-made themes on top
540
+ and scales, API: this is of semantic — light is
541
+ leave them alone what you change the example
542
+ ```
543
+
544
+ ### Layers
545
+
546
+ | File | Role | Touch it? |
547
+ |---|---|---|
548
+ | `primitives.css` | Raw palette, space / radius / shadow scales (`--tao-orange-400`, `--tao-space-3`…) | Usually no |
549
+ | `semantic.css` | Default (dark) theme tokens: `--tao-color-accent`, `--tao-color-surface`, `--tao-color-danger`, etc. | **Yes — this is the theming API** |
550
+ | `themes/light.css` | Alternate theme via `[data-tao-theme="light"]` | Yes, as a sample |
551
+ | `base.css` | Global reset (scrollbar, links, box-sizing) | Rarely |
552
+
553
+ All four come in through `@1337exp/taoui/styles.css`.
554
+
555
+ ### Your own theme
556
+
557
+ A theme is just semantic tokens under your selector.
558
+ Nothing in the components needs to change:
559
+
560
+ ```css
561
+ /* my-brand-theme.css */
562
+ [data-tao-theme="my-brand"] {
563
+ --tao-color-accent: #6c5ce7;
564
+ --tao-color-accent-hover: #5a4bd1;
565
+ --tao-color-bg: #0f0f1a;
566
+ --tao-color-surface: #0f0f1a;
567
+ --tao-color-surface-raised: #1a1a2e;
568
+ --tao-color-text: #d6d6e8;
569
+ --tao-color-text-strong: #ffffff;
570
+ /* remaining tokens: see semantic.css */
571
+ }
572
+ ```
573
+
574
+ ```vue
575
+ <!-- app.vue -->
576
+ <template>
577
+ <div data-tao-theme="my-brand">
578
+ <NuxtPage />
579
+ </div>
580
+ </template>
581
+ ```
582
+
583
+ Or switch the theme on `<html>` so modals/tooltips teleported to `body` pick it up:
584
+
585
+ ```javascript
586
+ document.documentElement.setAttribute('data-tao-theme', 'light')
587
+ ```
588
+
589
+ ### Token groups
590
+
591
+ - `--tao-color-accent*` — brand/accent (primary buttons, active tabs, links)
592
+ - `--tao-color-on-accent` — text on the accent (`--tao-color-text-on-accent` is an alias)
593
+ - `--tao-color-selection`, `--tao-color-selection-text` — text selection (`::selection`)
594
+ - `--tao-color-surface*` — container backgrounds (default / raised / sunken / hover)
595
+ - `--tao-color-border*` — borders
596
+ - `--tao-color-text*` — text (default / strong / subtle / muted / disabled)
597
+ - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — status colors
598
+ - `--tao-color-input-*` — fields, because input bg/text often differs from surface/text
599
+ - `--tao-radius-control`, `--tao-radius-panel` — radii (small controls vs large panels)
600
+ - `--tao-shadow-panel`, `--tao-shadow-overlay` — shadows
601
+ - `--tao-font-size-*` — type scale in `primitives.css`: `xs`–`xl` controls, `2xl`–`4xl` titles / prose
602
+ - `--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-*` — the size scale in `primitives.css`. Components read the current values from `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`. Use them in your own controls to match the size around them. `--tao-field-height` is a deprecated alias of `--tao-control-height`
603
+
604
+ The full list lives in `src/styles/semantic.css` — the only file worth opening
605
+ to see the whole theming API.
606
+
607
+ ### A theme from scratch, without primitives
608
+
609
+ ```javascript
610
+ import '@1337exp/taoui/styles/primitives.css' // keep the scales if you want
611
+ import './my-semantic.css' // your semantic layer instead of @1337exp/taoui/styles/semantic.css
612
+ import '@1337exp/taoui/styles/base.css'
613
+ ```
614
+
615
+ ## Showcase
616
+
617
+ Every component with live examples, prop tables and copy-ready snippets. Language (EN / RU) and theme (dark / light) switch in the header.
618
+
619
+ ```bash
620
+ cd showcase
621
+ npm install
622
+ npm run dev # or, from the repo root: npm run showcase
623
+ ```
624
+
625
+ The showcase points at `src/` directly, so component edits show up without
626
+ `npm run build`. `npm run showcase:build` produces a static site with relative
627
+ paths, ready to drop into any folder (for example `/sandbox/taoui/`).
628
+
629
+ Screenshots and clips in this README come from the showcase: see [docs/media](docs/media/README.md).
630
+
631
+ ## Development
632
+
633
+ ```bash
634
+ # Build the library
635
+ npm run build
636
+
637
+ # Watch mode
638
+ npm run dev
639
+
640
+ # Type check
641
+ npm run type-check
642
+
643
+ # Tests (Vitest)
644
+ npm test
645
+ ```
646
+
647
+ ## Publishing to npm
648
+
649
+ Only `dist/` (the built library) and `src/styles/` (raw tokens, so you can
650
+ import `primitives.css` on its own for a custom theme) are published, plus
651
+ `README.md`, `LICENSE` and `CHANGELOG.md`.
652
+ Component sources (`src/components/*.vue`), build configs, and `showcase/`
653
+ stay in the repo — clone it to get them.
654
+
655
+ `npm publish` **itself** runs the type check, the tests and a full rebuild first
656
+ (`prepublishOnly` in `package.json`), so a stale or missing `dist/` cannot
657
+ reach the registry. You do not need to build by hand before `npm publish`.
658
+
659
+ See what would go into the tarball, without publishing:
660
+
661
+ ```bash
662
+ npm pack --dry-run
663
+ ```
664
+
665
+ Keep the publish token out of the repository: reference it from `.npmrc` as
666
+ `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` and set `NPM_TOKEN` in your shell.
667
+ `.npmrc` is git-ignored either way.
668
+
669
+ ## Contributing
670
+
671
+ Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
672
+ Security reports: [SECURITY.md](SECURITY.md).
673
+
674
+ ## License
675
+
676
+ [MIT](LICENSE) © 2026 1337exp