@1337exp/taoui 4.0.1 → 5.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/CHANGELOG.md +321 -220
- package/MIGRATION-5.md +133 -0
- package/README.md +828 -682
- package/README.ru.md +828 -687
- package/dist/index.d.ts +2026 -701
- package/dist/{index.mjs → index.js} +3908 -2844
- package/dist/index.js.map +1 -0
- package/dist/styles.css +1 -1
- package/package.json +100 -90
- package/skills/taoui/SKILL.md +131 -0
- package/skills/taoui/references/components.md +1106 -0
- package/src/styles/base.css +81 -81
- package/src/styles/contexts/atmosphere.css +29 -0
- package/src/styles/contexts/size.css +125 -0
- package/src/styles/{surface.css → contexts/surface.css} +68 -4
- package/src/styles/contexts/tone.css +118 -0
- package/src/styles/date-popup.css +2 -2
- package/src/styles/index.css +12 -5
- package/src/styles/palettes/index.css +11 -0
- package/src/styles/palettes/lagoon.css +105 -0
- package/src/styles/palettes/marple.css +105 -0
- package/src/styles/palettes/ocean-blue.css +105 -0
- package/src/styles/palettes/pinheiro.css +105 -0
- package/src/styles/palettes/sunset.css +105 -0
- package/src/styles/palettes/tokyo-night.css +105 -0
- package/src/styles/palettes/violet-dusk.css +105 -0
- package/src/styles/{semantic.css → themes/dark.css} +95 -93
- package/src/styles/themes/light.css +86 -74
- package/src/styles/{primitives.css → tokens/primitives.css} +162 -139
- package/src/styles/tokens/semantic.css +33 -0
- package/src/styles/typography.css +220 -0
- package/dist/index.cjs +0 -10572
- package/dist/index.cjs.map +0 -1
- package/dist/index.mjs.map +0 -1
- package/src/styles/size.css +0 -57
package/package.json
CHANGED
|
@@ -1,90 +1,100 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@1337exp/taoui",
|
|
3
|
-
"version": "
|
|
4
|
-
"description": "Design-token driven Vue 3 / Nuxt component library: one size scale, dark and light themes, built-in locales.",
|
|
5
|
-
"keywords": [
|
|
6
|
-
"vue",
|
|
7
|
-
"vue3",
|
|
8
|
-
"nuxt",
|
|
9
|
-
"ui",
|
|
10
|
-
"ui-library",
|
|
11
|
-
"components",
|
|
12
|
-
"component-library",
|
|
13
|
-
"design-system",
|
|
14
|
-
"design-tokens",
|
|
15
|
-
"theming",
|
|
16
|
-
"dark-mode",
|
|
17
|
-
"typescript",
|
|
18
|
-
"accessible",
|
|
19
|
-
"color-picker",
|
|
20
|
-
"slider",
|
|
21
|
-
"toast"
|
|
22
|
-
],
|
|
23
|
-
"homepage": "https://666.io",
|
|
24
|
-
"bugs": {
|
|
25
|
-
"url": "https://github.com/1337exp/taoui/issues"
|
|
26
|
-
},
|
|
27
|
-
"repository": {
|
|
28
|
-
"type": "git",
|
|
29
|
-
"url": "git+https://github.com/1337exp/taoui.git"
|
|
30
|
-
},
|
|
31
|
-
"author": "1337exp",
|
|
32
|
-
"license": "MIT",
|
|
33
|
-
"type": "module",
|
|
34
|
-
"
|
|
35
|
-
"
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
"./
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
"
|
|
50
|
-
"
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
"
|
|
54
|
-
|
|
55
|
-
"
|
|
56
|
-
"
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
"
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
"
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
"
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
"
|
|
71
|
-
"
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
"
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
"
|
|
80
|
-
"
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
"
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
"
|
|
87
|
-
"
|
|
88
|
-
"vue
|
|
89
|
-
|
|
90
|
-
|
|
1
|
+
{
|
|
2
|
+
"name": "@1337exp/taoui",
|
|
3
|
+
"version": "5.1.0",
|
|
4
|
+
"description": "Design-token driven Vue 3 / Nuxt component library: one size scale, dark and light themes, built-in locales.",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"vue",
|
|
7
|
+
"vue3",
|
|
8
|
+
"nuxt",
|
|
9
|
+
"ui",
|
|
10
|
+
"ui-library",
|
|
11
|
+
"components",
|
|
12
|
+
"component-library",
|
|
13
|
+
"design-system",
|
|
14
|
+
"design-tokens",
|
|
15
|
+
"theming",
|
|
16
|
+
"dark-mode",
|
|
17
|
+
"typescript",
|
|
18
|
+
"accessible",
|
|
19
|
+
"color-picker",
|
|
20
|
+
"slider",
|
|
21
|
+
"toast"
|
|
22
|
+
],
|
|
23
|
+
"homepage": "https://666.io",
|
|
24
|
+
"bugs": {
|
|
25
|
+
"url": "https://github.com/1337exp/taoui/issues"
|
|
26
|
+
},
|
|
27
|
+
"repository": {
|
|
28
|
+
"type": "git",
|
|
29
|
+
"url": "git+https://github.com/1337exp/taoui.git"
|
|
30
|
+
},
|
|
31
|
+
"author": "1337exp",
|
|
32
|
+
"license": "MIT",
|
|
33
|
+
"type": "module",
|
|
34
|
+
"types": "./dist/index.d.ts",
|
|
35
|
+
"exports": {
|
|
36
|
+
".": {
|
|
37
|
+
"types": "./dist/index.d.ts",
|
|
38
|
+
"default": "./dist/index.js"
|
|
39
|
+
},
|
|
40
|
+
"./styles.css": "./dist/styles.css",
|
|
41
|
+
"./palettes.css": "./src/styles/palettes/index.css",
|
|
42
|
+
"./styles/*": "./src/styles/*",
|
|
43
|
+
"./package.json": "./package.json"
|
|
44
|
+
},
|
|
45
|
+
"sideEffects": [
|
|
46
|
+
"**/*.css"
|
|
47
|
+
],
|
|
48
|
+
"files": [
|
|
49
|
+
"dist",
|
|
50
|
+
"src/styles",
|
|
51
|
+
"CHANGELOG.md",
|
|
52
|
+
"MIGRATION-5.md",
|
|
53
|
+
"skills"
|
|
54
|
+
],
|
|
55
|
+
"browserslist": [
|
|
56
|
+
"chrome >= 111",
|
|
57
|
+
"edge >= 111",
|
|
58
|
+
"safari >= 16.4",
|
|
59
|
+
"firefox >= 128"
|
|
60
|
+
],
|
|
61
|
+
"engines": {
|
|
62
|
+
"node": ">=18"
|
|
63
|
+
},
|
|
64
|
+
"publishConfig": {
|
|
65
|
+
"access": "public"
|
|
66
|
+
},
|
|
67
|
+
"scripts": {
|
|
68
|
+
"build": "vite build",
|
|
69
|
+
"dev": "vite build --watch",
|
|
70
|
+
"type-check": "vue-tsc --noEmit",
|
|
71
|
+
"test": "vitest run",
|
|
72
|
+
"test:watch": "vitest",
|
|
73
|
+
"showcase": "npm --prefix showcase run dev",
|
|
74
|
+
"showcase:build": "npm --prefix showcase run build",
|
|
75
|
+
"media": "node scripts/media.mjs",
|
|
76
|
+
"smoke": "node scripts/consumer-smoke.mjs",
|
|
77
|
+
"prepublishOnly": "npm run type-check && npm run test && npm run build && npm run lint:package",
|
|
78
|
+
"lint:package": "publint && attw --pack . --profile esm-only --exclude-entrypoints styles.css palettes.css",
|
|
79
|
+
"palettes": "node scripts/generate-palettes.mjs",
|
|
80
|
+
"skill": "node scripts/generate-skill.mjs"
|
|
81
|
+
},
|
|
82
|
+
"peerDependencies": {
|
|
83
|
+
"vue": "^3.4.0"
|
|
84
|
+
},
|
|
85
|
+
"devDependencies": {
|
|
86
|
+
"@arethetypeswrong/cli": "^0.18.5",
|
|
87
|
+
"@types/node": "^20.19.43",
|
|
88
|
+
"@vitejs/plugin-vue": "^5.0.0",
|
|
89
|
+
"@vue/test-utils": "^2.5.1",
|
|
90
|
+
"happy-dom": "^15.11.7",
|
|
91
|
+
"playwright-core": "^1.64.1",
|
|
92
|
+
"publint": "^0.3.25",
|
|
93
|
+
"typescript": "^5.3.0",
|
|
94
|
+
"vite": "^5.0.0",
|
|
95
|
+
"vite-plugin-dts": "^3.7.0",
|
|
96
|
+
"vitest": "^2.1.9",
|
|
97
|
+
"vue": "^3.4.0",
|
|
98
|
+
"vue-tsc": "^2.0.0"
|
|
99
|
+
}
|
|
100
|
+
}
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: taoui
|
|
3
|
+
description: Build Vue 3 interfaces with @1337exp/taoui 5 (TaoUI) — setup, themes and palettes, size / density / tone / surface contexts, the typography layer, components and their props, and the mistakes people make with them. Use when code imports @1337exp/taoui, uses Tao* components or --tao-* tokens, or the user asks for TaoUI.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# TaoUI 5
|
|
7
|
+
|
|
8
|
+
A Vue 3 component kit on design tokens. Components read **roles** (CSS custom properties `--tao-*`), never colours, so a
|
|
9
|
+
theme, a palette or a context class changes every component under it. The props of every component, with types and
|
|
10
|
+
defaults, are in [references/components.md](references/components.md); read the section you need before writing a
|
|
11
|
+
component you have not used yet.
|
|
12
|
+
|
|
13
|
+
## Setup
|
|
14
|
+
|
|
15
|
+
```js
|
|
16
|
+
import { createApp } from 'vue'
|
|
17
|
+
import TaoUI, { localeRu } from '@1337exp/taoui' // ESM-only; Vue 3.4+
|
|
18
|
+
import '@1337exp/taoui/styles.css' // required: tokens, themes, contexts, typography
|
|
19
|
+
import '@1337exp/taoui/palettes.css' // optional: the 7 ready palettes
|
|
20
|
+
|
|
21
|
+
createApp(App).use(TaoUI, { locale: localeRu }).mount('#app') // locale optional, English by default
|
|
22
|
+
```
|
|
23
|
+
|
|
24
|
+
- Nuxt 3: the same `app.use` in a plugin, the CSS in `app.vue`. Everything is SSR-safe.
|
|
25
|
+
- Components can also be imported one by one: `import { TaoButton } from '@1337exp/taoui'`.
|
|
26
|
+
- Browser floor: Chrome / Edge 111, Safari 16.4, Firefox 128 (`@property`, container queries, `color-mix()`).
|
|
27
|
+
|
|
28
|
+
## Rules that keep an app consistent
|
|
29
|
+
|
|
30
|
+
1. **Colours come from roles**, never hex: `var(--tao-color-text-muted)`, `--tao-color-accent`, `--tao-color-surface`,
|
|
31
|
+
`--tao-color-border`, `--tao-color-danger`… A hex in app CSS breaks the light mode and every palette.
|
|
32
|
+
2. **Status is `tone`**, the same everywhere: `success | danger | warning | info | neutral` (the accent when omitted) on
|
|
33
|
+
TaoButton, TaoAlert, TaoTag, the stripe of TaoCard / TaoBlock (`stripeTone`), TaoTimeline markers; `toast().danger()`. Say the status in words
|
|
34
|
+
too: colour alone is not a message.
|
|
35
|
+
3. **Size and density are contexts**, not props on every control: `class="tao-size-small"` (or `-medium`, `-large`) and
|
|
36
|
+
`class="tao-density-compact | comfortable | auto"` on any container change every control inside. An explicit `size`
|
|
37
|
+
prop wins. `comfortable` gives touch-sized controls (34 / 44 / 52px); `auto` is comfortable on `pointer: coarse`.
|
|
38
|
+
4. **A surface is a material**: `surface="flat | grain | glass"` on TaoCard / TaoBlock or `class="tao-surface-glass"` on any
|
|
39
|
+
element. Glass needs something behind it (popovers, a header over a scroll).
|
|
40
|
+
5. **Floating panels** (Select, Combobox, Date, Popover, Tooltip, menus) are teleported to `body`; they carry the size and
|
|
41
|
+
the density of where they hang from by themselves. Do not wrap them in `overflow: hidden` expecting a clip.
|
|
42
|
+
6. **Do not restyle internals by class names** (`.tao-select__panel` …) unless the reference says a class is public;
|
|
43
|
+
tune tokens instead. When you must, note that `TaoGrid` lays out on `.tao-grid__cells`, not on `.tao-grid`.
|
|
44
|
+
7. **Text content goes in `.tao-prose`**: the library never styles a bare `h1` or `p`. `<article class="tao-prose">` gives
|
|
45
|
+
headings, lists, quotes, code and links; `<h2 class="tao-heading-5">` gives any tag the look of a level.
|
|
46
|
+
|
|
47
|
+
## Themes and palettes
|
|
48
|
+
|
|
49
|
+
```html
|
|
50
|
+
<html data-tao-mode="light"> <!-- the default theme, light -->
|
|
51
|
+
<html data-tao-theme="lagoon"> <!-- a palette, dark -->
|
|
52
|
+
<html data-tao-theme="lagoon" data-tao-mode="light"> <!-- its light twin -->
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Palettes: `sunset`, `marple`, `violet-dusk`, `ocean-blue`, `pinheiro`, `tokyo-night`, `lagoon` (`taoPalettes`). Put the
|
|
56
|
+
attributes on `<html>` so teleported panels follow. Your own palette at run time:
|
|
57
|
+
`applyTaoPalette({ name, label, stops: [darkest, …, lightest] }, 'dark' | 'light', element?)` returns a function that
|
|
58
|
+
takes it off; `taoPaletteCss(def)` gives the CSS. `class="tao-atmosphere"` on `<body>` paints the soft glow behind a page.
|
|
59
|
+
|
|
60
|
+
Contrast: every palette keeps WCAG 2 numbers (4.5:1 text, 3:1 fills); the polarity of a label on a fill is chosen by APCA,
|
|
61
|
+
so light-mode fills carry white labels. `contrastRatio(a, b)` and `apcaContrast(text, bg)` are exported: use APCA to
|
|
62
|
+
choose a text colour, WCAG 2 to promise a number.
|
|
63
|
+
|
|
64
|
+
## Layout
|
|
65
|
+
|
|
66
|
+
- `TaoContainer` (page width), `TaoFlex` / `TaoSpace` (rows and stacks with `gap`), `TaoDivider`, `TaoSplit` (resizable panes).
|
|
67
|
+
- `TaoGrid min="220px"` — a catalog of equal tiles. `TaoGrid :cols` + `TaoGridItem :col :row :order` — a bento. Values can be
|
|
68
|
+
per width class **of the grid itself**: `compact` < 600px, `medium` < 840px, `expanded`:
|
|
69
|
+
`:cols="{ compact: 3, expanded: 6 }"`, `:col="{ compact: 'full', expanded: 4 }"`, `:order="{ compact: 9 }"`. A plain
|
|
70
|
+
number is one column on compact. `rowHeight` is the exact row height (a mosaic: pictures are cropped).
|
|
71
|
+
- `TaoNav` — app navigation from one list: a bottom bar, a rail or a drawer, `layout="auto"` by its own width; put the page
|
|
72
|
+
in its default slot and it lays it out. `select(id, event)` + `event.preventDefault()` to route with a router.
|
|
73
|
+
|
|
74
|
+
## Forms
|
|
75
|
+
|
|
76
|
+
- Every field takes `size`, `disabled`, `error` (a red frame). The message, the label and the hint go through
|
|
77
|
+
**`TaoFormField`** (`label`, `hint`, `error`), which also wires `id`, `aria-describedby` and `aria-invalid`.
|
|
78
|
+
- `TaoInput`, `TaoTextarea`, `TaoInputNumber`, `TaoQuantity`, `TaoSelect`, `TaoCombobox`, `TaoDate` / `TaoDateRange`
|
|
79
|
+
(`YYYY-MM-DD` strings), `TaoCalendar` (the inline month calendar, `mode="single" | "range"`), `TaoCheckbox`,
|
|
80
|
+
`TaoChecklist` (one model for a group), `TaoRadioGroup` + `TaoRadio`, `TaoSwitch`, `TaoSegmented`, `TaoSlider` /
|
|
81
|
+
`TaoRangeSlider`, `TaoPinCode` (`status="success | error"` after `complete`), `TaoColorInput` / `TaoColorPicker`,
|
|
82
|
+
`TaoFileDrop`. A form is a plain `<form>`; there is no TaoForm.
|
|
83
|
+
|
|
84
|
+
## Overlays and feedback
|
|
85
|
+
|
|
86
|
+
- `TaoModal`, `TaoDrawer` (v-model; Escape closes the top layer only), `TaoPopover`, `TaoTooltip` (`placement`).
|
|
87
|
+
- Menus share one engine: `TaoDropdownMenu`, `TaoMenubar`, `TaoContextMenu`, `TaoMenu` (the panel for your own shell).
|
|
88
|
+
Items are a data tree `TaoMenuItem[]`: `{ id, label, icon?, shortcut?, disabled?, items? }`,
|
|
89
|
+
`{ type: 'checkbox' | 'radio', checked }`, `{ type: 'label' | 'separator' }`. `@select="id => …"`. `closeOnScroll`.
|
|
90
|
+
With TaoUX, `createCommands().toMenu(layout)` builds this tree and binds the same shortcuts.
|
|
91
|
+
- `toast().success().message('Saved')`, `toast().danger().title('Network').timeout(5000).message('…')`,
|
|
92
|
+
`.action('Undo', fn)`. `await confirm().title('Delete?').message('…').danger()` resolves to a boolean.
|
|
93
|
+
Their hosts `TaoToastViewport` / `TaoConfirmHost` mount themselves on the first call; place them yourself only to control
|
|
94
|
+
where they render.
|
|
95
|
+
- `TaoAlert` (`tone`, `title`, `closable`, `collapsible` + `v-model:collapsed`), `TaoEmpty`, `TaoLoader`, `TaoSkeleton`,
|
|
96
|
+
`TaoProgress`.
|
|
97
|
+
|
|
98
|
+
## Data and display
|
|
99
|
+
|
|
100
|
+
`TaoTable` (columns, sort, row click), `TaoPagination` (`pageInput` for hundreds of pages), `TaoList` / `TaoListItem`,
|
|
101
|
+
`TaoTree` (expand, select, tri-state `checkable`, lazy `load`), `TaoStages`, `TaoTimeline` (`active` makes it a progress),
|
|
102
|
+
`TaoTag`, `TaoAvatar`, `TaoImage`, `TaoCarousel`, `TaoCard` (`#media`, `#title`, `#sub`, `#footer`, `#corner`, `closable`,
|
|
103
|
+
`stripe` + `stripeTone`), `TaoBlock`, `TaoTabs`, `TaoBreadcrumb`, `TaoLink`, `TaoSpoiler` / `TaoSpoilerGroup`, `TaoCounter`,
|
|
104
|
+
`TaoCopy`, `TaoMarquee` (one line that runs round only when it does not fit), `TaoScrubber` (play / pause + time),
|
|
105
|
+
`TaoScrollTop`, `TaoAnimatedBorder`, `TaoIcon`.
|
|
106
|
+
|
|
107
|
+
## Icons
|
|
108
|
+
|
|
109
|
+
`<TaoIcon name="tao-check" />`: 29 built-in SVG icons under the `tao-` prefix (`taoIconNames`). Your own:
|
|
110
|
+
`registerTaoIcons({ rocket: { body: '<path d="…"/>' } })` on a 24 grid with `currentColor`; add `grid: true` for icons made
|
|
111
|
+
only of straight lines through the middle (a plus), so they stay crisp when small. Any other name renders the class
|
|
112
|
+
`icon-<name>` for an icon font you bring.
|
|
113
|
+
|
|
114
|
+
## Language
|
|
115
|
+
|
|
116
|
+
`app.use(TaoUI, { locale: localeRu })`; `setTaoLocale(localeEn)` switches at run time without a reload; a prop passed by
|
|
117
|
+
hand (`placeholder`, `closeLabel`…) always wins. For SSR per request, `provideTaoLocale`.
|
|
118
|
+
|
|
119
|
+
## Mistakes to avoid
|
|
120
|
+
|
|
121
|
+
- Writing hex colours or `rgba()` in app CSS instead of roles; inventing token names (check `styles.css`).
|
|
122
|
+
- Passing `size` to every control instead of one `tao-size-*` / `tao-density-*` class on the container.
|
|
123
|
+
- Styling `.tao-grid` as a grid (it is `.tao-grid__cells`); expecting `rowHeight` to be a minimum (it is exact).
|
|
124
|
+
- Putting `TaoMarquee` in a parent without left room: the left fade takes `fade` px (22) left of the text.
|
|
125
|
+
- Using colour alone for a status; forgetting `aria-label` on an icon-only button (`TaoButton icon="tao-plus"` needs one).
|
|
126
|
+
- Global `h1 { … }` styles fighting `.tao-prose` (its rules are `:where()`, so yours win by design).
|
|
127
|
+
- Expecting `variant="danger"` on a button: the colour is `tone="danger"`, the shape is `variant`.
|
|
128
|
+
- Importing from deep paths (`@1337exp/taoui/dist/...`); only the package root, `styles.css`, `palettes.css` and
|
|
129
|
+
`styles/*` are public.
|
|
130
|
+
|
|
131
|
+
Migrating from TaoUI 4: `MIGRATION-5.md` in the package lists every rename; `CHANGELOG.md` explains each change.
|