@1337exp/taoui 4.0.1 → 5.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.
Files changed (35) hide show
  1. package/CHANGELOG.md +314 -220
  2. package/MIGRATION-5.md +133 -0
  3. package/README.md +828 -682
  4. package/README.ru.md +828 -687
  5. package/dist/index.d.ts +2009 -701
  6. package/dist/{index.mjs → index.js} +3867 -2808
  7. package/dist/index.js.map +1 -0
  8. package/dist/styles.css +1 -1
  9. package/package.json +100 -90
  10. package/skills/taoui/SKILL.md +131 -0
  11. package/skills/taoui/references/components.md +1105 -0
  12. package/src/styles/base.css +81 -81
  13. package/src/styles/contexts/atmosphere.css +29 -0
  14. package/src/styles/contexts/size.css +125 -0
  15. package/src/styles/{surface.css → contexts/surface.css} +68 -4
  16. package/src/styles/contexts/tone.css +118 -0
  17. package/src/styles/date-popup.css +2 -2
  18. package/src/styles/index.css +12 -5
  19. package/src/styles/palettes/index.css +11 -0
  20. package/src/styles/palettes/lagoon.css +105 -0
  21. package/src/styles/palettes/marple.css +105 -0
  22. package/src/styles/palettes/ocean-blue.css +105 -0
  23. package/src/styles/palettes/pinheiro.css +105 -0
  24. package/src/styles/palettes/sunset.css +105 -0
  25. package/src/styles/palettes/tokyo-night.css +105 -0
  26. package/src/styles/palettes/violet-dusk.css +105 -0
  27. package/src/styles/{semantic.css → themes/dark.css} +95 -93
  28. package/src/styles/themes/light.css +86 -74
  29. package/src/styles/{primitives.css → tokens/primitives.css} +162 -139
  30. package/src/styles/tokens/semantic.css +33 -0
  31. package/src/styles/typography.css +220 -0
  32. package/dist/index.cjs +0 -10572
  33. package/dist/index.cjs.map +0 -1
  34. package/dist/index.mjs.map +0 -1
  35. package/src/styles/size.css +0 -57
package/README.md CHANGED
@@ -1,682 +1,828 @@
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”: `solid` / `ghost` / `text` looks, `side`, a mouse-hover `label`. 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 English by default. Russian ships with the library:
226
-
227
- ```javascript
228
- import TaoUI, { localeRu } from '@1337exp/taoui'
229
-
230
- app.use(TaoUI, { locale: localeRu })
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` (or `localeRu`), 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 === 'ru' ? localeRu : localeEn)
250
- }
251
- ```
252
-
253
- Without the plugin (individual components) `setTaoLocale()` is the only call you need.
254
-
255
- ### Upgrading from 3.x
256
-
257
- 4.0 changes one default: the built-in texts are now English (they were Russian). To stay on Russian, pass the locale
258
- once — `app.use(TaoUI, { locale: localeRu })`, or `setTaoLocale(localeRu)` without the plugin. The date helpers and
259
- the date components follow the locale and default to `en-US` as well.
260
-
261
- ### Upgrading from 1.x
262
-
263
- See [CHANGELOG.md](CHANGELOG.md): what broke, and a table of old names → new ones. Old names still work in 2.x and
264
- warn in the console during development.
265
-
266
- ### Individual components
267
-
268
- ```vue
269
- <script setup>
270
- import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
271
- import '@1337exp/taoui/styles.css'
272
- </script>
273
-
274
- <template>
275
- <TaoButton variant="primary">Press me</TaoButton>
276
- <TaoFormField label="Your text">
277
- <TaoInput v-model="text" />
278
- </TaoFormField>
279
- <TaoModal v-model="isOpen" title="Title">
280
- Modal body
281
- </TaoModal>
282
- </template>
283
- ```
284
-
285
- ## Split
286
-
287
- `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.
288
-
289
- `direction` matches Flex: `row` (start | end) or `column` (start above end). Slots are `#start` / `#end`.
290
-
291
- `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.
292
-
293
- 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.
294
-
295
- ```vue
296
- <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
297
- <template #start>Nav</template>
298
- <template #end>Main</template>
299
- </TaoSplit>
300
- ```
301
-
302
- ## Toast
303
-
304
- The chain runs in the same tick; `setTimeout(0)` actually shows the toast.
305
-
306
- ```javascript
307
- import { toast } from '@1337exp/taoui'
308
-
309
- toast().success().message('Saved')
310
- toast().error().title('Network').timeout(5000).message('No connection')
311
- toast.success('Saved')
312
- toast.warning('Draft', { timeout: 1000 })
313
- ```
314
-
315
- Default position is `topCenter`. Globally:
316
-
317
- ```javascript
318
- toast.defaults({ position: 'bottomRight' })
319
- toast.byBottomRight()
320
- ```
321
-
322
- There is no overlay `question` in this kit — that is confirm, not toast. Buttons on a toast, if needed:
323
-
324
- ```javascript
325
- toast().info().message('Delete the file?').action('Delete', onRemove)
326
- ```
327
-
328
- You can skip the viewport: the first call creates it. For explicit control (tests, a custom layout):
329
-
330
- ```vue
331
- <TaoToastViewport />
332
- ```
333
-
334
- ## Confirm
335
-
336
- 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.
337
-
338
- ```javascript
339
- import { confirm } from '@1337exp/taoui'
340
-
341
- if (await confirm().title('Delete the file?').message('This cannot be undone').danger()) {
342
- remove()
343
- }
344
-
345
- const ok = await confirm('Leave without saving?', {
346
- ok: 'Leave',
347
- cancel: 'Stay',
348
- })
349
- ```
350
-
351
- Queue: a second `confirm()` while the first is open will wait. Default labels are “OK” / “Cancel”:
352
-
353
- ```javascript
354
- confirm.defaults({ ok: 'Yes', cancel: 'No' })
355
- ```
356
-
357
- ## Forms
358
-
359
- `TaoFormField` attaches a shared label / hint / error and forwards `id` to the nested control.
360
-
361
- ```vue
362
- <TaoFormField label="City" hint="Optional">
363
- <TaoSelect v-model="city" :options="cities" />
364
- </TaoFormField>
365
-
366
- <TaoSwitch v-model="dark" label="Dark theme" />
367
-
368
- <TaoRadioGroup v-model="plan" legend="Plan">
369
- <TaoRadio value="free" label="Free" />
370
- <TaoRadio value="pro" label="Pro" />
371
- </TaoRadioGroup>
372
-
373
- <TaoSegmented v-model="period" legend="Period">
374
- <TaoSegmentedOption value="week">Week</TaoSegmentedOption>
375
- <TaoSegmentedOption value="month">Month</TaoSegmentedOption>
376
- <TaoSegmentedOption value="year">Year</TaoSegmentedOption>
377
- </TaoSegmented>
378
-
379
- <TaoAlert tone="warning" title="Draft">Save before you leave.</TaoAlert>
380
- ```
381
-
382
- `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`.
383
-
384
- `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`.
385
-
386
- 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.
387
-
388
- ```vue
389
- <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
390
-
391
- <TaoSelect v-model="city" :options="cities">
392
- <template #clear><TaoIcon name="close" /> Reset</template>
393
- </TaoSelect>
394
- ```
395
-
396
- `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.
397
-
398
- 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.
399
-
400
- `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.
401
-
402
- ```vue
403
- <TaoTag tone="neutral" closable @close="remove">
404
- <template #prefix>
405
- <TaoAvatar name="Anna Kozlova" size="small" />
406
- </template>
407
- Anna Kozlova
408
- </TaoTag>
409
- ```
410
-
411
- ## Table and pagination
412
-
413
- 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.
414
-
415
- ```vue
416
- <TaoTable
417
- :columns="columns"
418
- :rows="pageRows"
419
- v-model:sort="sort"
420
- empty-text="No records yet"
421
- >
422
- <template #cell-status="{ row }">
423
- <TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
424
- {{ row.status }}
425
- </TaoTag>
426
- </template>
427
- </TaoTable>
428
-
429
- <TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
430
- ```
431
-
432
- ```javascript
433
- const columns = [
434
- { key: 'name', label: 'Name', sortable: true },
435
- { key: 'city', label: 'City' },
436
- { key: 'status', label: 'Status' },
437
- ]
438
- ```
439
-
440
- 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`.
441
-
442
- ## Empty states and loading
443
-
444
- ```vue
445
- <TaoEmpty title="Nothing found">
446
- Change the filter or reset search.
447
- <template #action>
448
- <TaoButton variant="secondary">Reset</TaoButton>
449
- </template>
450
- </TaoEmpty>
451
-
452
- <TaoSkeleton variant="title" />
453
- <TaoSkeleton :lines="3" />
454
- <TaoSkeleton variant="circle" />
455
-
456
- <TaoStages :items="[
457
- { key: 'pay', label: 'Payment', status: 'ok' },
458
- { key: 'pack', label: 'Packing', status: 'work' },
459
- { key: 'ship', label: 'Shipping', status: 'wait' },
460
- ]" />
461
-
462
- <TaoList>
463
- <TaoListItem
464
- title="Ann Kozlova"
465
- description="Design · Moscow"
466
- clickable
467
- :selected="picked === 'ann'"
468
- @click="picked = 'ann'"
469
- >
470
- <template #prefix>
471
- <TaoAvatar name="Ann Kozlova" size="small" />
472
- </template>
473
- </TaoListItem>
474
- </TaoList>
475
- ```
476
-
477
- ```vue
478
- <TaoInput v-model="q" placeholder="Search…">
479
- <template #prefix>⌕</template>
480
- </TaoInput>
481
-
482
- <TaoInputGroup>
483
- <template #before>https://</template>
484
- <TaoInput v-model="host" placeholder="example.com" />
485
- <template #after>
486
- <TaoButton>Check</TaoButton>
487
- </template>
488
- </TaoInputGroup>
489
-
490
- <form @submit.prevent="onSave">
491
- <TaoFormField label="Email">
492
- <TaoInput v-model="email" type="email" />
493
- </TaoFormField>
494
- <TaoButton type="submit">Save</TaoButton>
495
- </form>
496
-
497
- <TaoFormField label="Quantity">
498
- <TaoInputNumber v-model="qty" :min="1" :max="99" />
499
- </TaoFormField>
500
-
501
- <TaoQuantity v-model="qty" :max="12" @dec="onDec" />
502
-
503
- <TaoFormField label="Delivery day" hint="The model is always YYYY-MM-DD">
504
- <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
505
- </TaoFormField>
506
-
507
- <TaoFormField label="Stay">
508
- <TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
509
- </TaoFormField>
510
-
511
- <TaoCounter :value="score" :max-digits="6" />
512
-
513
- <TaoCarousel :autoplay="4000" loop dots>
514
- <article v-for="item in banners" :key="item.id" class="hero">
515
- <strong>{{ item.title }}</strong>
516
- <span>{{ item.text }}</span>
517
- </article>
518
- </TaoCarousel>
519
- <TaoCarousel :peek="72" :controls="false" dots>…</TaoCarousel>
520
- <TaoCarousel v-model="slide" :per-view="5" :peek="28">
521
- <template #prev></template>
522
- <template #next="{ go, disabled }">
523
- <button type="button" :disabled="disabled" @click="go">next</button>
524
- </template>
525
- <article v-for="item in products" :key="item.id">…</article>
526
- </TaoCarousel>
527
- ```
528
-
529
- `TaoDrawer` is a side sheet, not a centered modal:
530
-
531
- ```vue
532
- <TaoDrawer v-model="open" title="Filters">
533
- ...
534
- </TaoDrawer>
535
- ```
536
-
537
- ## Design tokens and theming
538
-
539
- Library styles are three layers. Components **never** touch raw colors or sizes —
540
- only semantic variables. That is the theming mechanism: override 20–30 variables
541
- and every component follows, with no edits inside the components themselves.
542
-
543
- ```
544
- primitives.css → semantic.css → themes/*.css (optional)
545
- raw colors public theming ready-made themes on top
546
- and scales, API: this is of semantic — light is
547
- leave them alone what you change the example
548
- ```
549
-
550
- ### Layers
551
-
552
- | File | Role | Touch it? |
553
- |---|---|---|
554
- | `primitives.css` | Raw palette, space / radius / shadow scales (`--tao-orange-400`, `--tao-space-3`…) | Usually no |
555
- | `semantic.css` | Default (dark) theme tokens: `--tao-color-accent`, `--tao-color-surface`, `--tao-color-danger`, etc. | **Yes — this is the theming API** |
556
- | `themes/light.css` | Alternate theme via `[data-tao-theme="light"]` | Yes, as a sample |
557
- | `base.css` | Global reset (scrollbar, links, box-sizing) | Rarely |
558
-
559
- All four come in through `@1337exp/taoui/styles.css`.
560
-
561
- ### Your own theme
562
-
563
- A theme is just semantic tokens under your selector.
564
- Nothing in the components needs to change:
565
-
566
- ```css
567
- /* my-brand-theme.css */
568
- [data-tao-theme="my-brand"] {
569
- --tao-color-accent: #6c5ce7;
570
- --tao-color-accent-hover: #5a4bd1;
571
- --tao-color-bg: #0f0f1a;
572
- --tao-color-surface: #0f0f1a;
573
- --tao-color-surface-raised: #1a1a2e;
574
- --tao-color-text: #d6d6e8;
575
- --tao-color-text-strong: #ffffff;
576
- /* remaining tokens: see semantic.css */
577
- }
578
- ```
579
-
580
- ```vue
581
- <!-- app.vue -->
582
- <template>
583
- <div data-tao-theme="my-brand">
584
- <NuxtPage />
585
- </div>
586
- </template>
587
- ```
588
-
589
- Or switch the theme on `<html>` so modals/tooltips teleported to `body` pick it up:
590
-
591
- ```javascript
592
- document.documentElement.setAttribute('data-tao-theme', 'light')
593
- ```
594
-
595
- ### Token groups
596
-
597
- - `--tao-color-accent*` — brand/accent (primary buttons, active tabs, links)
598
- - `--tao-color-on-accent` — text on the accent (`--tao-color-text-on-accent` is an alias)
599
- - `--tao-color-selection`, `--tao-color-selection-text` — text selection (`::selection`)
600
- - `--tao-color-surface*` — container backgrounds (default / raised / sunken / hover)
601
- - `--tao-color-border*` — borders
602
- - `--tao-color-text*` — text (default / strong / subtle / muted / disabled)
603
- - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — status colors
604
- - `--tao-color-input-*` — fields, because input bg/text often differs from surface/text
605
- - `--tao-radius-control`, `--tao-radius-panel` — radii (small controls vs large panels)
606
- - `--tao-shadow-panel`, `--tao-shadow-overlay` — shadows
607
- - `--tao-font-size-*` — type scale in `primitives.css`: `xs`–`xl` controls, `2xl`–`4xl` titles / prose
608
- - `--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`
609
-
610
- The full list lives in `src/styles/semantic.css` — the only file worth opening
611
- to see the whole theming API.
612
-
613
- ### A theme from scratch, without primitives
614
-
615
- ```javascript
616
- import '@1337exp/taoui/styles/primitives.css' // keep the scales if you want
617
- import './my-semantic.css' // your semantic layer instead of @1337exp/taoui/styles/semantic.css
618
- import '@1337exp/taoui/styles/base.css'
619
- ```
620
-
621
- ## Showcase
622
-
623
- Every component with live examples, prop tables and copy-ready snippets. Language (EN / RU) and theme (dark / light) switch in the header.
624
-
625
- ```bash
626
- cd showcase
627
- npm install
628
- npm run dev # or, from the repo root: npm run showcase
629
- ```
630
-
631
- The showcase points at `src/` directly, so component edits show up without
632
- `npm run build`. `npm run showcase:build` produces a static site with relative
633
- paths, ready to drop into any folder (for example `/sandbox/taoui/`).
634
-
635
- Screenshots and clips in this README come from the showcase: see [docs/media](docs/media/README.md).
636
-
637
- ## Development
638
-
639
- ```bash
640
- # Build the library
641
- npm run build
642
-
643
- # Watch mode
644
- npm run dev
645
-
646
- # Type check
647
- npm run type-check
648
-
649
- # Tests (Vitest)
650
- npm test
651
- ```
652
-
653
- ## Publishing to npm
654
-
655
- Only `dist/` (the built library) and `src/styles/` (raw tokens, so you can
656
- import `primitives.css` on its own for a custom theme) are published, plus
657
- `README.md`, `LICENSE` and `CHANGELOG.md`.
658
- Component sources (`src/components/*.vue`), build configs, and `showcase/`
659
- stay in the repo — clone it to get them.
660
-
661
- `npm publish` **itself** runs the type check, the tests and a full rebuild first
662
- (`prepublishOnly` in `package.json`), so a stale or missing `dist/` cannot
663
- reach the registry. You do not need to build by hand before `npm publish`.
664
-
665
- See what would go into the tarball, without publishing:
666
-
667
- ```bash
668
- npm pack --dry-run
669
- ```
670
-
671
- Keep the publish token out of the repository: reference it from `.npmrc` as
672
- `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` and set `NPM_TOKEN` in your shell.
673
- `.npmrc` is git-ignored either way.
674
-
675
- ## Contributing
676
-
677
- Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
678
- Security reports: [SECURITY.md](SECURITY.md).
679
-
680
- ## License
681
-
682
- [MIT](LICENSE) © 2026 1337exp
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** — `variant`: `primary` / `secondary` / `ghost` / `text`; `tone` colours any of them (accent by default, neutral, success, danger, warning, info)
53
+ - **TaoCard** — card with media / header / title / footer slots and a `#corner` (a tag, a menu button). `#media` can be a photo or `TaoCarousel`; `closable` adds a cross and the `close` event. `flush` is a tile (no padding/shadow, fills the cell); `#overlay` is a scrim on the media; `stripe="top | left | bottom"` with `stripeTone` (a tone or the palette `gradient`) draws a coloured stripe the corners clip
54
+ - **TaoCopy** — clipboard icon. After a click, a “Copied” tooltip; if the trigger is gone, the tooltip is too
55
+ - **TaoMarquee** — one line that never wraps: when it does not fit it runs round with fading edges and a pause at the start of every round, when it fits it stands still. Stops on hover, on focus and on a tap (WCAG 2.2.2); wraps with «reduce motion»; a screen reader reads it once. `text` or inline content in the slot, `speed`, `gap`, `fade` (the left fade takes that much room left of the text: give the parent the padding), `paused`
56
+ - **TaoInput** — text field with v-model, validation, and `#prefix` / `#suffix` slots (icon or text inside the frame)
57
+ - **TaoInputGroup** — outer glue: `#before` | field | `#after` (protocol, unit, button)
58
+ - **TaoModal** — modal with animation and slots
59
+ - **TaoDrawer** — side panel (filters, settings). Esc, backdrop click, focus trap — same as the modal
60
+ - **TaoSpoiler** — disclosure. `v-model` and `aria-expanded`. Neighbours do not close each other
61
+ - **TaoSpoilerGroup** — accordion: `v-model` is the open panel key (`null` = all closed); spoilers take `name`. Without `v-model` the group keeps that key itself
62
+ - **TaoTabs** — tabbed sections
63
+ - **TaoNav** — navigation between the sections of an app: one list of items (`icon`, `href`, `badge`), three looks. `layout="auto"` picks by the width of TaoNav itself (container queries, no JS): a bottom bar below 600px (more than five items: «More» with a menu), a rail with icons below 840px, a side panel with labels from 840px. With the page in its slot it lays the page out: the bar sticks to the bottom (safe area kept), the side list to the top. `select(id, event)` lets a router take over a link
64
+ - **TaoTooltip** — hover hint. `placement`: `top` / `bottom` / `left` / `right`, each with `-start` / `-end`; flips at the viewport edge
65
+ - **TaoPopover** — click panel with any slot content, Esc and outside click; `placement` as Tooltip. Not a tooltip, not an action menu
66
+
67
+ ### Layout
68
+
69
+ - **TaoContainer** — max-width (wide / slim / ultra-slim) and centering
70
+ - **TaoFlex** — flexbox wrapper: justify / align / direction / wrap / gap
71
+ - **TaoSpace** — even gap between children
72
+ - **TaoGrid** / **TaoGridItem** — tiles: `min` is a catalog (auto-fill), `cols` is a bento. An adaptive bento takes values per width class of the grid itself (compact < 600px, medium < 840px, expanded): `:cols="{ compact: 3, expanded: 6 }"`, `:col="{ compact: 'full', expanded: 4 }"`, `:order="{ compact: 9 }"` — on a phone the big blocks take the row, small tiles stay three in a row, a side block goes down. A plain number keeps one column on a phone. `rowHeight` fixes the row height, as a mosaic wants. Not masonry
73
+ - **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)
74
+ - **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.
75
+ - **TaoFieldset** — grouped frame: `legend` sits on the top border, `align` is start / center / end
76
+ - **TaoAnimatedBorder** — animated border wrapper: the rainbow, the colours of a `tone` (follows the theme) or your own `colors`; a still gradient with `prefers-reduced-motion`
77
+
78
+ ### Forms
79
+
80
+ - **TaoCheckbox** — checkbox with v-model, pre/post slots, and `indeterminate`
81
+ - **TaoChecklist** — checkboxes with one model (the checked values): `select-all` with a mixed state, a `counter` «3 of 5», `strike` for a to-do list (a look only, the checkbox tells the state), `description` per item. A fieldset: in a `TaoFormField` the group takes the label and the error
82
+ - **TaoSwitch** — boolean toggle (`role="switch"`)
83
+ - **TaoRadio** / **TaoRadioGroup** — classic radios: longer labels, can stack vertically
84
+ - **TaoSegmented** / **TaoSegmentedOption** — compact exclusive choice among 2–5 short options. Not tabs
85
+ - **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
86
+ - **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`
87
+ - **TaoDate** — a single day: `YYYY-MM-DD`, no time, no timezone. Calendar popup like Select
88
+ - **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
89
+ - **TaoCalendar** — the month calendar itself, inline (no popup): `mode="single"` (`YYYY-MM-DD`) or `"range"` (`{ start, end }`), `min` / `max`, arrows / PageUp / PageDown / Home / End. `TaoDate` and `TaoDateRange` are a field with this calendar in a popup
90
+ - **TaoFormField** — shared label / hint / error for form controls
91
+ - **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
92
+ - **TaoQuantity** — cart quantity: `− | field | +`, integers, stock; minus at the minimum can remove the row
93
+ - **TaoTextarea** — autosizing multiline. `maxlength` caps input, `count` shows “entered / max”. `variant`: `bar` (default) / `outline` (frame like Input) / `filled` / `plain`; `readonly`; `align`; `blurOnEnter`
94
+ - **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`; `status="success | error"` (set after `complete`) glows or shakes the cells and says it to a screen reader
95
+ - **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
96
+ - **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
97
+ - **TaoColorInput** — a field with a swatch and the hex text; the picker opens in a popover
98
+ - **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`)
99
+
100
+ ### Data display
101
+
102
+ - **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.
103
+ - **TaoPagination** — pages with ellipsis. Clicking “…” jumps `jump` pages (5 by default)
104
+ - **TaoEmpty** — empty list, no results, no access
105
+ - **TaoList** / **TaoListItem** — list row: icon, title, caption, hover action. Not Select, not a table
106
+ - **TaoTree** — files or objects as a tree: `v-model:expanded`, selection `none | single | multiple` (`v-model:selected`), checkboxes with mixed parents (`checkable`, `v-model:checked`), lazy children (`hasChildren` + `load`). ARIA tree: one tab stop, arrows, `→` / `←` in and out, Home / End, `*`, type-ahead. Slots `#icon`, `#label`, `#actions`; rows on the control tokens (size and density)
107
+ - **TaoStages** — stage list: `wait` / `work` / `ok` / `bad`. Not a linear stepper
108
+ - **TaoTimeline** — a vertical feed of events: order steps, releases, a log. `active` fills the line up to the current event (`aria-current="step"`), without it the feed is a log of the past; `tone` and `icon` per marker, `#marker` / `#title` / `#content` slots; `align="alternate"` puts events on both sides and folds into one below 480px of its own width
109
+ - **TaoSkeleton** — loading placeholder (text / title / circle / rect)
110
+ - **TaoCounter** — flipping digits (not an input)
111
+ - **TaoCarousel** — strip: full slide with `autoplay`, card with `peek`, row with `per-view`. Arrows via `controls` or `#prev` / `#next`; marks under the strip via `indicator` (`dots`, `bars` or `progress`). With `autoplay` the current mark fills over the interval and the slide changes when it is full; hover, keyboard focus, touch, a hidden tab and the pause button stop it, `prefers-reduced-motion` turns it off
112
+ - **TaoAvatar** — photo or initials, sizes `small` / `medium` / `large`. Status `dot` and `count`
113
+ - **TaoTag** — badge with tones. `#prefix` (avatar), `closable` dismisses the chip, `flat` drops the border
114
+ - **TaoAlert** — inline page/form banner (success / error / warning / info); `collapsible` folds the body under the title (find-in-page still finds it)
115
+ - **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
116
+ - **TaoScrubber** — 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
117
+ - **TaoLoader** — four-dot spinner
118
+ - **TaoImage** — `<img>` wrapper: fade-in and placeholder. `lazy` turns on native `loading="lazy"`
119
+ - **TaoIcon** — SVG icons (29 built in, your own via `registerTaoIcons`) or an icon font (see Icons below)
120
+
121
+ ### Navigation
122
+
123
+ - **TaoLink** — `<NuxtLink>` in Nuxt, `<RouterLink>` with vue-router, otherwise a plain `<a>` — no extra setup
124
+ - **TaoBreadcrumb** — crumbs: the last item is the current page
125
+ - **TaoDropdownMenu** / **TaoMenu** — a menu from a plain data tree `items`: submenus, checkboxes, radios, separators, group labels, shortcuts to show, disabled items. Arrows, Home / End, type-ahead, `→` / `←` for submenus, Esc closes the top level first. `TaoMenu` is the panel itself, for your own shells (a menu bar, a context menu); flips at the viewport edge
126
+ - **TaoMenubar** / **TaoContextMenu** — the menu bar of an editor and the menu on the right click, on `TaoMenu`. The bar is one tab stop (`role="menubar"`): `←` / `→` walk it, `↓` / Enter open, with a menu open `←` / `→` and the pointer move to the neighbour menu; an entry without `items` is a plain action. The context menu opens at the pointer (or at the element for the Menu key / Shift+F10) and wraps its content without a box of its own
127
+ - **TaoScrollTop** — floating “back to top”: `solid` / `ghost` / `text` looks, `side`, a mouse-hover `label`. Appears on reverse scroll after `boundary`
128
+
129
+ ### Feedback
130
+
131
+ - **toast()** — fluent toasts: `toast().success().message('Saved')`
132
+ - **confirm()** — overlay question: the same fluent API plus `await`. Not a toast — it waits for an answer and does not dismiss itself.
133
+ - **TaoToastViewport** / **TaoConfirmHost** — hosts; if they are missing from the tree, the first call mounts them on `body`
134
+
135
+ ## Conventions
136
+
137
+ Visual tones: `success` | `danger` | `warning` | `info` | `neutral` (type `TaoTone`), always the `tone` prop: Button, Alert, Tag (`toast.danger()` for toasts). The accent is a tone too and the default one. A tone is a context class like a size: `.tao-tone-danger` on any element sets `--tao-tone`, `--tao-tone-on`, `--tao-tone-text`, … (see `styles/tone.css`). Unlike a size it does **not** inherit, so a button inside a red alert stays an accent button.
138
+ Stages describe a process, not a tone: `wait` / `work` / `ok` / `bad` (`danger` is accepted as `bad`).
139
+
140
+ 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"` for the dense one); FileDrop scales the zone and file rows; Slider scales the track and thumb.
141
+ 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.
142
+
143
+ ```vue
144
+ <div class="tao-size-small">
145
+ <TaoInput v-model="q" />
146
+ <TaoButton>Find</TaoButton>
147
+ </div>
148
+ ```
149
+
150
+ Content and layout keep their own scale and do not inherit: Avatar (24 / 32 / 48px), Divider `gap`, Loader / Icon / ScrollTop (pixels).
151
+ Container lives on another axis — width: `width="wide" | "slim" | "ultra-slim"`.
152
+
153
+ **Density** is the second axis of the controls, on top of the size: the class `tao-density-compact` / `-comfortable` / `-auto` on a container (or on `<html>`) changes the height and the padding of every size in it, not the font. `comfortable` gives 34 / 44 / 52px (touch-sized rows), `compact` 22 / 32 / 40px (dense tools and tables), `auto` is comfortable on a touch screen (`pointer: coarse`) and the default with a mouse. Select and Combobox carry it into their panels. Type `TaoDensity`; the steps are tokens `--tao-density-height-*` / `--tao-density-padding-x-*` / `-y-*`.
154
+
155
+ ```html
156
+ <html class="tao-density-auto">
157
+ ```
158
+
159
+
160
+ Surfaces — what a panel is made of: `flat` fill (default), `grain` (static film grain), `glass` (translucent, blurs what is
161
+ behind). Use `surface` on TaoCard / TaoBlock or the class `tao-surface-grain` / `-glass` on any element — a game HUD, a
162
+ landing section, a sidebar. Tune the look once with theme tokens (`--tao-surface-grain-image` / `-size`, `--tao-glass-fill`
163
+ / `-border` / `-blur`). A surface belongs to one element: nested panels do not inherit it. Glass needs something behind
164
+ it — keep it for things that float over content; over a flat background it is just a grey fill, over animation it is
165
+ re-blurred every frame. Toast and confirm are glass by default, tinted by their tone; `toast.defaults({ surface: 'flat' })`
166
+ and `confirm.defaults({ surface: 'flat' })` turn it off, `.surface('flat')` does it for one. Without blur support or with
167
+ `prefers-reduced-transparency` glass falls back to a solid panel.
168
+
169
+ Font size scale (primitives): `xs` 12 … `xl` 18 for controls; `2xl` 24, `3xl` 32, `4xl` 36 for titles and prose.
170
+ There is no heading component — use `h1 { font-size: var(--tao-font-size-3xl) }`.
171
+
172
+ API rules — every component follows them:
173
+
174
+ - **Fields** take `v-model`, `disabled`, `error` (red frame) and `size`. Label, hint and error text come from `TaoFormField`.
175
+ - **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`.
176
+ - **Texts**: visible ones are `*Text` (`clearText`, `successText`), screen-reader ones are `*Label` (`closeLabel`).
177
+ - **Lists**: data arrays are `items`; selectable items carry `value` + `label` (`TaoSelectOption`, `TaoTabItem`). Identifiers of plain data (table columns, stages) stay `key`.
178
+ - **Booleans** are adjectives without `is` / `has` / `as`: `closable`, `clickable`, `masked`, `newTab`. Layout axis is `direction: 'row' | 'column'`, not `vertical`.
179
+ - **Lengths** (`padding`, `radius`, `gap`, `maxHeight`): a number is pixels, a string goes to CSS as is (type `TaoLength`).
180
+
181
+ ## Typography
182
+
183
+ An opt-in layer: the library never styles a bare `h1` or `p`. Put `.tao-prose` on a wrapper and the text inside gets
184
+ headings, paragraphs, lists, quotes, code, rules and links in the theme roles, spaced by proximity (a heading close to
185
+ its text, far from the block before). Every rule inside is `:where()`, so your CSS always wins.
186
+
187
+ ```html
188
+ <article class="tao-prose">
189
+ <h1>Title</h1>
190
+ <p>Text with a <a href="/docs">link</a>.</p>
191
+ </article>
192
+
193
+ <h2 class="tao-heading-5">An h2 the size of level 5</h2>
194
+ ```
195
+
196
+ The heading scale comes from two numbers: `--tao-text-base` (16px, the text and h6) and `--tao-text-ratio` (1.25), each
197
+ level up one more step: 16 / 20 / 25 / 31 / 39 / 49. Set the ratio on `:root` or on one wrapper (1.2 calmer, 1.333
198
+ bolder) and the scale under it follows; h1 and h2 shrink on a narrow screen, never below h3 / h4. The steps are tokens
199
+ `--tao-heading-1…6` for your own rules. `.tao-heading-1…6` gives the look of a level to any tag: the tag says what it is,
200
+ the class how big.
201
+
202
+ ### For AI assistants
203
+
204
+ The package ships a skill, `skills/taoui/SKILL.md` with `references/components.md`: the setup, the rules (roles not colours, contexts not props), every component and its props, and the mistakes people make. Point your assistant at it; for Claude Code, copy `node_modules/@1337exp/taoui/skills/taoui` into your project's `.claude/skills/`. The component reference is generated from the showcase prop tables (`npm run skill`), and a test keeps the skill naming every component.
205
+
206
+ ## Icons
207
+
208
+ The library ships **29 SVG icons** (check, close, plus, minus, chevrons, arrows, search, eye, more, grip, play, pause,
209
+ skip-back, copy, calendar, info, alert, circles, folder, file). They draw on `currentColor`, so an icon takes the text colour and the
210
+ font size, and live under the reserved prefix `tao-`: `<TaoIcon name="tao-check" />`, the list is `taoIconNames`.
211
+
212
+ ```vue
213
+ <TaoIcon name="tao-check" /> <!-- built-in -->
214
+ <TaoIcon name="rocket" /> <!-- registered with registerTaoIcons, or `icon-rocket` of your own font -->
215
+ <TaoButton icon="tao-plus">Add</TaoButton>
216
+ <TaoButton icon="tao-close" aria-label="Close" /> <!-- only an icon: a square, aria-label is required -->
217
+ ```
218
+
219
+ ```ts
220
+ registerTaoIcons({ rocket: { body: '<path d="M12 3l4 8-4 10-4-10z"/>' } }); // 24x24 grid unless you pass viewBox
221
+ ```
222
+
223
+ A name without the `tao-` prefix is looked up among the icons you registered, and then rendered as the class
224
+ `icon-<name>` for an external icon font (IcoMoon / Fontello and the like) that the host app connects itself. All
225
+ built-in parts (close buttons, steppers, pagination arrows, toasts…) use the built-in icons and their `#…-icon` slots
226
+ let you replace them with anything.
227
+
228
+ ## Install
229
+
230
+ ```bash
231
+ npm install @1337exp/taoui
232
+ ```
233
+
234
+ Requires Vue 3.4+. The package is **ESM-only** (Vite, Nuxt 3, webpack 5 and Node 18+ with `import` all work; a plain `require('@1337exp/taoui')` does not: use `import()`).
235
+
236
+ ### Browser support
237
+
238
+ The CSS uses `color-mix()`, container queries and registered custom properties (`@property`), so the floor is
239
+ **Chrome / Edge 111, Safari 16.4, Firefox 128**: the browsers of 2023–2024. Firefox 128 is the limiting one (`@property`).
240
+ On an older browser everything stays readable; what you lose is small: a registered property is what keeps a tone
241
+ (`.tao-tone-*`) and a surface from leaking into the children, so without it a Button inside a red Alert may turn red.
242
+ The same list is the `browserslist` field of the package and the build target.
243
+
244
+ From a local folder:
245
+
246
+ ```bash
247
+ npm install ../path-to-tao-ui
248
+ ```
249
+
250
+ ## Usage
251
+
252
+ ### Nuxt 3
253
+
254
+ Create `plugins/tao-ui.ts`:
255
+
256
+ ```typescript
257
+ import { defineNuxtPlugin } from '#app'
258
+ import TaoUI from '@1337exp/taoui'
259
+
260
+ export default defineNuxtPlugin((nuxtApp) => {
261
+ nuxtApp.vueApp.use(TaoUI)
262
+ })
263
+ ```
264
+
265
+ Import styles in `app.vue` or a layout:
266
+
267
+ ```vue
268
+ <script setup>
269
+ import '@1337exp/taoui/styles.css'
270
+ </script>
271
+ ```
272
+
273
+ ### Vue 3
274
+
275
+ ```javascript
276
+ // main.js
277
+ import { createApp } from 'vue'
278
+ import App from './App.vue'
279
+ import TaoUI from '@1337exp/taoui'
280
+ import '@1337exp/taoui/styles.css'
281
+
282
+ const app = createApp(App)
283
+ app.use(TaoUI)
284
+ app.mount('#app')
285
+ ```
286
+
287
+ ### Language
288
+
289
+ Built-in texts (placeholders, “Clear”, aria labels, dates) are English by default. Russian ships with the library:
290
+
291
+ ```javascript
292
+ import TaoUI, { localeRu } from '@1337exp/taoui'
293
+
294
+ app.use(TaoUI, { locale: localeRu })
295
+ ```
296
+
297
+ Change single texts — the rest stays from the default:
298
+
299
+ ```javascript
300
+ app.use(TaoUI, { locale: { select: { placeholder: 'Pick one' } } })
301
+ ```
302
+
303
+ Another language: copy `localeEn` (or `localeRu`), translate, pass it the same way (type `TaoLocale`). Keys repeat prop names —
304
+ `locale.select.placeholder` is the default of TaoSelect `placeholder`, and a prop passed by hand always wins.
305
+
306
+ Switch the language at any moment — from your settings, a language picker, a route. Components already on the page
307
+ update at once, without a reload and without losing what users typed:
308
+
309
+ ```javascript
310
+ import { setTaoLocale, localeEn, localeRu } from '@1337exp/taoui'
311
+
312
+ function onLanguageChange(lang) {
313
+ setTaoLocale(lang === 'ru' ? localeRu : localeEn)
314
+ }
315
+ ```
316
+
317
+ Without the plugin (individual components) `setTaoLocale()` is the only call you need.
318
+
319
+ ### Upgrading to 5.0
320
+
321
+ 5.0 deletes every name that 2.0 deprecated (plus the `error` tone alias), see [MIGRATION-5.md](MIGRATION-5.md) for the table old → new.
322
+
323
+ ### Upgrading from 3.x
324
+
325
+ 4.0 changes one default: the built-in texts are now English (they were Russian). To stay on Russian, pass the locale
326
+ once — `app.use(TaoUI, { locale: localeRu })`, or `setTaoLocale(localeRu)` without the plugin. The date helpers and
327
+ the date components follow the locale and default to `en-US` as well.
328
+
329
+ ### Upgrading from 1.x
330
+
331
+ See the 2.0.0 entry of [CHANGELOG.md](CHANGELOG.md) for what broke. Old names were removed in 5.0.
332
+
333
+ ### Individual components
334
+
335
+ ```vue
336
+ <script setup>
337
+ import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
338
+ import '@1337exp/taoui/styles.css'
339
+ </script>
340
+
341
+ <template>
342
+ <TaoButton variant="primary">Press me</TaoButton>
343
+ <TaoFormField label="Your text">
344
+ <TaoInput v-model="text" />
345
+ </TaoFormField>
346
+ <TaoModal v-model="isOpen" title="Title">
347
+ Modal body
348
+ </TaoModal>
349
+ </template>
350
+ ```
351
+
352
+ ## Split
353
+
354
+ `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.
355
+
356
+ `direction` matches Flex: `row` (start | end) or `column` (start above end). Slots are `#start` / `#end`.
357
+
358
+ `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.
359
+
360
+ 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.
361
+
362
+ ```vue
363
+ <TaoSplit v-model="side" unit="px" :min="160" :max="480" :min-end="240">
364
+ <template #start>Nav</template>
365
+ <template #end>Main</template>
366
+ </TaoSplit>
367
+ ```
368
+
369
+ ## Toast
370
+
371
+ The chain runs in the same tick; `setTimeout(0)` actually shows the toast.
372
+
373
+ ```javascript
374
+ import { toast } from '@1337exp/taoui'
375
+
376
+ toast().success().message('Saved')
377
+ toast().danger().title('Network').timeout(5000).message('No connection')
378
+ toast.success('Saved')
379
+ toast.warning('Draft', { timeout: 1000 })
380
+ ```
381
+
382
+ Default position is `topCenter`. Globally:
383
+
384
+ ```javascript
385
+ toast.defaults({ position: 'bottomRight' })
386
+ toast.byBottomRight()
387
+ ```
388
+
389
+ There is no overlay `question` in this kit — that is confirm, not toast. Buttons on a toast, if needed:
390
+
391
+ ```javascript
392
+ toast().info().message('Delete the file?').action('Delete', onRemove)
393
+ ```
394
+
395
+ You can skip the viewport: the first call creates it. For explicit control (tests, a custom layout):
396
+
397
+ ```vue
398
+ <TaoToastViewport />
399
+ ```
400
+
401
+ ## Confirm
402
+
403
+ 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.
404
+
405
+ ```javascript
406
+ import { confirm } from '@1337exp/taoui'
407
+
408
+ if (await confirm().title('Delete the file?').message('This cannot be undone').danger()) {
409
+ remove()
410
+ }
411
+
412
+ const ok = await confirm('Leave without saving?', {
413
+ ok: 'Leave',
414
+ cancel: 'Stay',
415
+ })
416
+ ```
417
+
418
+ Queue: a second `confirm()` while the first is open will wait. Default labels are “OK” / “Cancel”:
419
+
420
+ ```javascript
421
+ confirm.defaults({ ok: 'Yes', cancel: 'No' })
422
+ ```
423
+
424
+ ## Forms
425
+
426
+ `TaoFormField` attaches a shared label / hint / error and forwards `id` to the nested control.
427
+
428
+ ```vue
429
+ <TaoFormField label="City" hint="Optional">
430
+ <TaoSelect v-model="city" :options="cities" />
431
+ </TaoFormField>
432
+
433
+ <TaoSwitch v-model="dark" label="Dark theme" />
434
+
435
+ <TaoRadioGroup v-model="plan" legend="Plan">
436
+ <TaoRadio value="free" label="Free" />
437
+ <TaoRadio value="pro" label="Pro" />
438
+ </TaoRadioGroup>
439
+
440
+ <TaoSegmented v-model="period" legend="Period">
441
+ <TaoSegmentedOption value="week">Week</TaoSegmentedOption>
442
+ <TaoSegmentedOption value="month">Month</TaoSegmentedOption>
443
+ <TaoSegmentedOption value="year">Year</TaoSegmentedOption>
444
+ </TaoSegmented>
445
+
446
+ <TaoAlert tone="warning" title="Draft">Save before you leave.</TaoAlert>
447
+ ```
448
+
449
+ `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`.
450
+
451
+ `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`.
452
+
453
+ 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.
454
+
455
+ ```vue
456
+ <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
457
+
458
+ <TaoSelect v-model="city" :options="cities">
459
+ <template #clear><TaoIcon name="close" /> Reset</template>
460
+ </TaoSelect>
461
+ ```
462
+
463
+ `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.
464
+
465
+ Label, hint and error text always come from `TaoFormField`. `TaoFormField` also wraps `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup`, and `TaoSegmented` — id, hint, and error are forwarded for you.
466
+
467
+ `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.
468
+
469
+ ```vue
470
+ <TaoTag tone="neutral" closable @close="remove">
471
+ <template #prefix>
472
+ <TaoAvatar name="Anna Kozlova" size="small" />
473
+ </template>
474
+ Anna Kozlova
475
+ </TaoTag>
476
+ ```
477
+
478
+ ## Table and pagination
479
+
480
+ 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.
481
+
482
+ ```vue
483
+ <TaoTable
484
+ :columns="columns"
485
+ :rows="pageRows"
486
+ v-model:sort="sort"
487
+ empty-text="No records yet"
488
+ >
489
+ <template #cell-status="{ row }">
490
+ <TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
491
+ {{ row.status }}
492
+ </TaoTag>
493
+ </template>
494
+ </TaoTable>
495
+
496
+ <TaoPagination v-model:page="page" :total="rows.length" :page-size="8" />
497
+ ```
498
+
499
+ ```javascript
500
+ const columns = [
501
+ { key: 'name', label: 'Name', sortable: true },
502
+ { key: 'city', label: 'City' },
503
+ { key: 'status', label: 'Status' },
504
+ ]
505
+ ```
506
+
507
+ 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`.
508
+
509
+ ## Empty states and loading
510
+
511
+ ```vue
512
+ <TaoEmpty title="Nothing found">
513
+ Change the filter or reset search.
514
+ <template #action>
515
+ <TaoButton variant="secondary">Reset</TaoButton>
516
+ </template>
517
+ </TaoEmpty>
518
+
519
+ <TaoSkeleton variant="title" />
520
+ <TaoSkeleton :lines="3" />
521
+ <TaoSkeleton variant="circle" />
522
+
523
+ <TaoStages :items="[
524
+ { key: 'pay', label: 'Payment', status: 'ok' },
525
+ { key: 'pack', label: 'Packing', status: 'work' },
526
+ { key: 'ship', label: 'Shipping', status: 'wait' },
527
+ ]" />
528
+
529
+ <TaoList>
530
+ <TaoListItem
531
+ title="Ann Kozlova"
532
+ description="Design · Moscow"
533
+ clickable
534
+ :selected="picked === 'ann'"
535
+ @click="picked = 'ann'"
536
+ >
537
+ <template #prefix>
538
+ <TaoAvatar name="Ann Kozlova" size="small" />
539
+ </template>
540
+ </TaoListItem>
541
+ </TaoList>
542
+ ```
543
+
544
+ ```vue
545
+ <TaoInput v-model="q" placeholder="Search…">
546
+ <template #prefix>⌕</template>
547
+ </TaoInput>
548
+
549
+ <TaoInputGroup>
550
+ <template #before>https://</template>
551
+ <TaoInput v-model="host" placeholder="example.com" />
552
+ <template #after>
553
+ <TaoButton>Check</TaoButton>
554
+ </template>
555
+ </TaoInputGroup>
556
+
557
+ <form @submit.prevent="onSave">
558
+ <TaoFormField label="Email">
559
+ <TaoInput v-model="email" type="email" />
560
+ </TaoFormField>
561
+ <TaoButton type="submit">Save</TaoButton>
562
+ </form>
563
+
564
+ <TaoFormField label="Quantity">
565
+ <TaoInputNumber v-model="qty" :min="1" :max="99" />
566
+ </TaoFormField>
567
+
568
+ <TaoQuantity v-model="qty" :max="12" @dec="onDec" />
569
+
570
+ <TaoFormField label="Delivery day" hint="The model is always YYYY-MM-DD">
571
+ <TaoDate v-model="day" min="2026-09-01" max="2026-09-30" />
572
+ </TaoFormField>
573
+
574
+ <TaoFormField label="Stay">
575
+ <TaoDateRange v-model="stay" min="2026-09-01" max="2026-09-30" />
576
+ </TaoFormField>
577
+
578
+ <TaoCounter :value="score" :max-digits="6" />
579
+
580
+ <TaoCarousel :autoplay="4000" loop indicator="bars">
581
+ <article v-for="item in banners" :key="item.id" class="hero">
582
+ <strong>{{ item.title }}</strong>
583
+ <span>{{ item.text }}</span>
584
+ </article>
585
+ </TaoCarousel>
586
+ <TaoCarousel :peek="72" :controls="false" indicator="dots">…</TaoCarousel>
587
+ <TaoCarousel v-model="slide" :per-view="5" :peek="28">
588
+ <template #prev></template>
589
+ <template #next="{ go, disabled }">
590
+ <button type="button" :disabled="disabled" @click="go">next</button>
591
+ </template>
592
+ <article v-for="item in products" :key="item.id">…</article>
593
+ </TaoCarousel>
594
+ ```
595
+
596
+ `TaoDrawer` is a side sheet, not a centered modal:
597
+
598
+ ```vue
599
+ <TaoDrawer v-model="open" title="Filters">
600
+ ...
601
+ </TaoDrawer>
602
+ ```
603
+
604
+ ## Design tokens and theming
605
+
606
+ Library styles are layers. Components **never** touch raw colors or sizes: they read semantic roles, and
607
+ the contexts built on them (size, tone, surface). That is the theming mechanism: override 20–30 variables
608
+ and every component follows, with no edits inside the components themselves.
609
+
610
+ ```
611
+ tokens/primitives.css → tokens/semantic.css → themes/*.css → contexts/*.css → base.css
612
+ raw colors, scales radii, shadows, colour roles size, tone, reset
613
+ leave them alone type, motion per theme surface classes
614
+ ```
615
+
616
+ ### Layers
617
+
618
+ | File (in `src/styles/`) | Role | Touch it? |
619
+ |---|---|---|
620
+ | `tokens/primitives.css` | Raw palette, space / radius / shadow scales (`--tao-orange-400`, `--tao-space-3`…) | Usually no |
621
+ | `tokens/semantic.css` | Theme-independent roles: radii, shadows, type, motion | Rarely |
622
+ | `themes/dark.css` | The colour roles of the default (dark) theme: `--tao-color-accent`, `--tao-color-surface`, … | **Yes — this is the theming API** |
623
+ | `themes/light.css` | The same roles under `[data-tao-theme="light"]` | Yes, as a sample |
624
+ | `contexts/size.css`, `tone.css`, `surface.css` | `.tao-size-*` and `.tao-density-*`, `.tao-tone-*`, `.tao-surface-*`: what a control reads to know its size, colour and material | Rarely |
625
+ | `base.css` | Global reset (scrollbar, links, box-sizing) | Rarely |
626
+
627
+ Everything comes in through `@1337exp/taoui/styles.css` (dark and light both: light turns on with `data-tao-theme="light"`).
628
+ The raw files are importable as `@1337exp/taoui/styles/tokens/primitives.css` and so on.
629
+
630
+ ### Your own theme
631
+
632
+ A theme is just semantic tokens under your selector.
633
+ Nothing in the components needs to change:
634
+
635
+ ```css
636
+ /* my-brand-theme.css */
637
+ [data-tao-theme="my-brand"] {
638
+ --tao-color-accent: #6c5ce7;
639
+ --tao-color-accent-hover: #5a4bd1;
640
+ --tao-color-bg: #0f0f1a;
641
+ --tao-color-surface: #0f0f1a;
642
+ --tao-color-surface-raised: #1a1a2e;
643
+ --tao-color-text: #d6d6e8;
644
+ --tao-color-text-strong: #ffffff;
645
+ /* remaining roles: see themes/dark.css */
646
+ }
647
+ ```
648
+
649
+ ```vue
650
+ <!-- app.vue -->
651
+ <template>
652
+ <div data-tao-theme="my-brand">
653
+ <NuxtPage />
654
+ </div>
655
+ </template>
656
+ ```
657
+
658
+ Or switch the theme on `<html>` so modals/tooltips teleported to `body` pick it up:
659
+
660
+ ```javascript
661
+ document.documentElement.setAttribute('data-tao-theme', 'light')
662
+ ```
663
+
664
+ ### Token groups
665
+
666
+ - `--tao-color-accent*` — brand/accent (primary buttons, active tabs, links)
667
+ - `--tao-color-on-accent` — text on the accent
668
+ - `--tao-color-selection`, `--tao-color-selection-text` — text selection (`::selection`)
669
+ - `--tao-color-surface*` — container backgrounds (default / raised / sunken / hover)
670
+ - `--tao-color-border*` — borders
671
+ - `--tao-color-text*` — text (default / strong / subtle / muted / disabled)
672
+ - `--tao-color-danger*`, `--tao-color-success*`, `--tao-color-warning*`, `--tao-color-info*` — status colors
673
+ - `--tao-color-input-*` — fields, because input bg/text often differs from surface/text
674
+ - `--tao-radius-control`, `--tao-radius-panel` — radii (small controls vs large panels)
675
+ - `--tao-shadow-panel`, `--tao-shadow-overlay` — shadows
676
+ - `--tao-font-size-*` — type scale in `primitives.css`: `xs`–`xl` controls, `2xl`–`4xl` titles / prose
677
+ - `--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 `contexts/size.css`: `--tao-control-height`, `--tao-control-padding-x` / `-y`, `--tao-control-font-size`, `--tao-control-font-size-secondary`, `--tao-button-padding-x`, `--tao-indicator-size`, `--tao-tag-height` / `-padding-x` / `-font-size`. Use them in your own controls to match the size around them.
678
+
679
+ The full list of colour roles lives in `src/styles/themes/dark.css` — the file worth opening
680
+ to see the whole theming API.
681
+
682
+ ### Palettes
683
+
684
+ A palette is four colours, from the darkest to the lightest: a whole set of roles comes out, for a dark and a light mode.
685
+ Seven are ready (`sunset`, `marple`, `violet-dusk`, `ocean-blue`, `pinheiro`, `tokyo-night`, `lagoon`; the list is `taoPalettes`).
686
+
687
+ ```javascript
688
+ import '@1337exp/taoui/styles.css'
689
+ import '@1337exp/taoui/palettes.css' // all of them, or '@1337exp/taoui/styles/palettes/sunset.css' for one
690
+ ```
691
+
692
+ ```html
693
+ <html data-tao-theme="sunset"> <!-- dark -->
694
+ <html data-tao-theme="sunset" data-tao-mode="light"> <!-- its light twin -->
695
+ ```
696
+
697
+ `data-tao-mode="light" | "dark"` also works on its own, with the default colours; `data-tao-theme="light"` is the old spelling of the same.
698
+ Put it on `<html>` (so modals and tooltips teleported to `body` follow) or on any element for a part of the page.
699
+
700
+ What a palette decides, so you do not have to:
701
+
702
+ - **The accent** is the stop whose lightness suits the mode (name it with `accent: 1` when the automatic choice is not the one you meant), moved along lightness only until it is seen on the page (3:1), carries a readable text (4.5:1) and reads as text itself (`--tao-color-accent-text`, 4.5:1).
703
+ - **The page and the surfaces** are a very dark (or very light) tint of the palette's deepest hue.
704
+ - **The statuses** (`danger`, `warning`, `success`, `info`) keep their recognisable hue sector but share the lightness and the chroma of the palette, and a status that would be mistaken for the accent is pushed away (a palette may name its own colour: `status: { success: '#7fbf2f' }`). Every status keeps 4.5:1 for its text, as a fill and as text.
705
+ - **`--tao-color-accent-2`, `--tao-glow`, `--tao-gradient`, `--tao-bg-atmosphere`:** the second accent, the glow colour, a gradient through the four stops, and the soft glow behind the page (`class="tao-atmosphere"` on `<body>` or the app root paints it; a static layer, no blur).
706
+
707
+ The contrast is not a promise in the README: `tests/palette.test.ts` holds every palette in both modes to these numbers.
708
+
709
+ A palette of your own, at run time (a theme editor, a colour the user picked):
710
+
711
+ ```javascript
712
+ import { applyTaoPalette } from '@1337exp/taoui'
713
+
714
+ const stop = applyTaoPalette({ name: 'mine', label: 'Mine', stops: ['#102030', '#306090', '#60c0f0', '#e0f4ff'] }, 'dark')
715
+ stop() // takes it off again; a third argument puts it on one element instead of the page
716
+ ```
717
+
718
+ or as a file: `taoPaletteCss(def)` returns the CSS the preset files are made of. To add a preset to the library, add it to `src/palettes.ts` and run `npm run palettes`.
719
+
720
+ #### Contrast: WCAG 2 and APCA
721
+
722
+ Two questions are asked of every colour pair, and they are answered by two different models.
723
+
724
+ **Is it allowed?** WCAG 2 contrast ratio: `(L1 + 0.05) / (L2 + 0.05)` of the relative luminances, from 1 to 21. It is the
725
+ legal standard (and the one accessibility audits check), so every number the palettes promise is a WCAG 2 ratio: 4.5:1
726
+ for text, 3:1 for a fill seen on the page. `contrastRatio(a, b)` computes it.
727
+
728
+ **Which reads better?** WCAG 2 has a known blind spot: it treats light and dark the same way, and on mid-tone colours it
729
+ overrates black. On the green `#2ea85c` it says black 6.4:1 against white 3.1:1, while the eye clearly reads white better.
730
+ APCA (Accessible Perceptual Contrast Algorithm, the model behind the WCAG 3 draft) follows how we see: it knows that
731
+ light text on a dark background and dark text on a light one are not symmetric, and that thin text needs more. It gives
732
+ a lightness contrast **Lc** from about −108 to 106 (the sign is the polarity: negative is light text on dark); about 75 is
733
+ body text, 60 a label, 45 a large heading. `apcaContrast(text, background)` computes it.
734
+
735
+ | On `#2ea85c` | WCAG 2 | APCA Lc |
736
+ |---|---|---|
737
+ | black text | **6.4 : 1** | 47 |
738
+ | white text | 3.1 : 1 | **62** |
739
+
740
+ So the palettes use both, each for what it is good at:
741
+
742
+ 1. **The polarity by APCA.** In light mode the label on a fill (the accent, a status) is the colour APCA reads better;
743
+ on mid-tones that is white.
744
+ 2. **The numbers by WCAG 2.** The fill is then moved along lightness until that label reaches 4.5:1, so a white label
745
+ on a mid-tone gets a slightly deeper fill, never a weaker label.
746
+ 3. **Dark mode keeps a dark label.** There the fills are light on purpose (to be seen on a dark page), and a light fill
747
+ carries dark text in both models.
748
+
749
+ The checks are in `tests/palette.test.ts`: every palette, both modes, every fill. If you build your own colours, the two
750
+ functions are exported, use them the same way: APCA to choose, WCAG 2 to promise.
751
+
752
+ ### A theme from scratch, without primitives
753
+
754
+ ```javascript
755
+ import '@1337exp/taoui/styles/tokens/primitives.css' // keep the scales if you want
756
+ import '@1337exp/taoui/styles/tokens/semantic.css' // radii, shadows, type, motion
757
+ import './my-colour-roles.css' // your colour roles instead of themes/dark.css
758
+ import '@1337exp/taoui/styles/contexts/size.css' // the contexts the components read
759
+ import '@1337exp/taoui/styles/contexts/tone.css'
760
+ import '@1337exp/taoui/styles/contexts/surface.css'
761
+ import '@1337exp/taoui/styles/base.css'
762
+ ```
763
+
764
+ ## Showcase
765
+
766
+ Every component with live examples, prop tables and copy-ready snippets. Language (EN / RU) and theme (dark / light) switch in the header.
767
+
768
+ ```bash
769
+ cd showcase
770
+ npm install
771
+ npm run dev # or, from the repo root: npm run showcase
772
+ ```
773
+
774
+ The showcase points at `src/` directly, so component edits show up without
775
+ `npm run build`. `npm run showcase:build` produces a static site with relative
776
+ paths, ready to drop into any folder (for example `/sandbox/taoui/`).
777
+
778
+ Screenshots and clips in this README come from the showcase: see [docs/media](docs/media/README.md).
779
+
780
+ ## Development
781
+
782
+ ```bash
783
+ # Build the library
784
+ npm run build
785
+
786
+ # Watch mode
787
+ npm run dev
788
+
789
+ # Type check
790
+ npm run type-check
791
+
792
+ # Tests (Vitest)
793
+ npm test
794
+ ```
795
+
796
+ ## Publishing to npm
797
+
798
+ Only `dist/` (the built library) and `src/styles/` (raw tokens, so you can
799
+ import `tokens/primitives.css` on its own for a custom theme) are published, plus
800
+ `README.md`, `LICENSE`, `CHANGELOG.md` and `MIGRATION-5.md`.
801
+ Component sources (`src/components/*.vue`), build configs, and `showcase/`
802
+ stay in the repo — clone it to get them.
803
+
804
+ `npm publish` **itself** runs the type check, the tests and a full rebuild first
805
+ (`prepublishOnly` in `package.json`), so a stale or missing `dist/` cannot
806
+ reach the registry. You do not need to build by hand before `npm publish`.
807
+
808
+ See what would go into the tarball, without publishing, and check the package the way a consumer meets it
809
+ (`publint` for the manifest, `attw` for the type resolution):
810
+
811
+ ```bash
812
+ npm pack --dry-run
813
+ npm run lint:package
814
+ npm run smoke # installs the packed tarball into a clean Vite project and builds it
815
+ ```
816
+
817
+ Keep the publish token out of the repository: reference it from `.npmrc` as
818
+ `//registry.npmjs.org/:_authToken=${NPM_TOKEN}` and set `NPM_TOKEN` in your shell.
819
+ `.npmrc` is git-ignored either way.
820
+
821
+ ## Contributing
822
+
823
+ Issues and pull requests are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).
824
+ Security reports: [SECURITY.md](SECURITY.md).
825
+
826
+ ## License
827
+
828
+ [MIT](LICENSE) © 2026 1337exp