@1337exp/taoui 1.13.1 → 2.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -47,9 +47,9 @@ change a handful of CSS variables and the whole kit follows.
47
47
  - **TaoFormField** — shared label / hint / error for form controls
48
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
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”
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
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. The last cell blurs and emits `complete`
52
- - **TaoSlider** — mouse, touch, and arrows. Optional precise input on right-click. `size="small"` is a thin track for seek / volume
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
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
54
 
55
55
  ### Data display
@@ -85,17 +85,44 @@ change a handful of CSS variables and the whole kit follows.
85
85
 
86
86
  ## Conventions
87
87
 
88
- Visual tones: `success` | `danger` | `warning` | `info` | `neutral`.
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
89
  `error` on Alert, Tag, and `toast()` is an alias of `danger`. Button already uses `danger`.
90
90
  Stages describe a process, not a tone: `wait` / `work` / `ok` / `bad` (`danger` is accepted as `bad`).
91
91
 
92
- Control sizes: `small` | `medium` | `large`.
93
- Avatar also accepts short `s` / `m` / `l`. Divider `gap` used to call the large size `big` — that is an alias of `large`.
94
- Container lives on another axis: `wide` / `slim` / `ultra-slim`.
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.
95
113
 
96
114
  Font size scale (primitives): `xs` 12 … `xl` 18 for controls; `2xl` 24, `3xl` 32, `4xl` 36 for titles and prose.
97
115
  There is no heading component — use `h1 { font-size: var(--tao-font-size-3xl) }`.
98
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
+
99
126
  ## Icons
100
127
 
101
128
  `TaoIcon` does not ship its own set — it renders `icon-<name>`
@@ -151,17 +178,56 @@ app.use(TaoUI)
151
178
  app.mount('#app')
152
179
  ```
153
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
+
154
218
  ### Individual components
155
219
 
156
220
  ```vue
157
221
  <script setup>
158
- import { TaoButton, TaoInput, TaoModal } from '@1337exp/taoui'
222
+ import { TaoButton, TaoFormField, TaoInput, TaoModal } from '@1337exp/taoui'
159
223
  import '@1337exp/taoui/styles.css'
160
224
  </script>
161
225
 
162
226
  <template>
163
227
  <TaoButton variant="primary">Press me</TaoButton>
164
- <TaoInput v-model="text" label="Your text" />
228
+ <TaoFormField label="Your text">
229
+ <TaoInput v-model="text" />
230
+ </TaoFormField>
165
231
  <TaoModal v-model="isOpen" title="Title">
166
232
  Modal body
167
233
  </TaoModal>
@@ -262,14 +328,14 @@ confirm.defaults({ ok: 'Yes', cancel: 'No' })
262
328
  <TaoSegmentedOption value="year">Year</TaoSegmentedOption>
263
329
  </TaoSegmented>
264
330
 
265
- <TaoAlert type="warning" title="Draft">Save before you leave.</TaoAlert>
331
+ <TaoAlert tone="warning" title="Draft">Save before you leave.</TaoAlert>
266
332
  ```
267
333
 
268
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`.
269
335
 
270
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`.
271
337
 
272
- 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` (default) / `large` and also scales the open list.
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.
273
339
 
274
340
  ```vue
275
341
  <TaoSelect v-model="step" :options="steps" size="small" :clearable="false" />
@@ -281,12 +347,12 @@ When `null` is not a valid value (a grid step, a sort order), pass `:clearable="
281
347
 
282
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.
283
349
 
284
- `TaoFormField` also wraps `TaoTextarea`, `TaoCheckbox`, `TaoSwitch`, `TaoRadioGroup`, and `TaoSegmented` — id, hint, and error are forwarded for you.
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.
285
351
 
286
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.
287
353
 
288
354
  ```vue
289
- <TaoTag type="neutral" closable @close="remove">
355
+ <TaoTag tone="neutral" closable @close="remove">
290
356
  <template #prefix>
291
357
  <TaoAvatar name="Anna Kozlova" size="small" />
292
358
  </template>
@@ -306,7 +372,7 @@ The table renders what you pass in: it does not slice or sort the data. That wor
306
372
  empty-text="No records yet"
307
373
  >
308
374
  <template #cell-status="{ row }">
309
- <TaoTag :type="row.status === 'active' ? 'success' : 'neutral'">
375
+ <TaoTag :tone="row.status === 'active' ? 'success' : 'neutral'">
310
376
  {{ row.status }}
311
377
  </TaoTag>
312
378
  </template>
@@ -491,7 +557,7 @@ document.documentElement.setAttribute('data-tao-theme', 'light')
491
557
  - `--tao-radius-control`, `--tao-radius-panel` — radii (small controls vs large panels)
492
558
  - `--tao-shadow-panel`, `--tao-shadow-overlay` — shadows
493
559
  - `--tao-font-size-*` — type scale in `primitives.css`: `xs`–`xl` controls, `2xl`–`4xl` titles / prose
494
- - `--tao-control-height-small` / `-medium` / `-large` — one height scale (26 / 36 / 44px) for every control with `size`: Button, Segmented, Select, Combobox. `--tao-field-height` (= medium) is the height of fields without `size`: Input, InputNumber, Date, DateRange, Quantity
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`
495
561
 
496
562
  The full list lives in `src/styles/semantic.css` — the only file worth opening
497
563
  to see the whole theming API.
@@ -532,6 +598,9 @@ npm run dev
532
598
 
533
599
  # Type check
534
600
  npm run type-check
601
+
602
+ # Tests (Vitest)
603
+ npm test
535
604
  ```
536
605
 
537
606
  ## Publishing to npm