@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/package.json CHANGED
@@ -1,90 +1,100 @@
1
- {
2
- "name": "@1337exp/taoui",
3
- "version": "4.0.1",
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
- "main": "./dist/index.cjs",
35
- "module": "./dist/index.mjs",
36
- "types": "./dist/index.d.ts",
37
- "exports": {
38
- ".": {
39
- "types": "./dist/index.d.ts",
40
- "import": "./dist/index.mjs",
41
- "require": "./dist/index.cjs"
42
- },
43
- "./styles.css": "./dist/styles.css",
44
- "./styles/*": "./src/styles/*",
45
- "./package.json": "./package.json"
46
- },
47
- "files": [
48
- "dist",
49
- "src/styles",
50
- "CHANGELOG.md"
51
- ],
52
- "engines": {
53
- "node": ">=18"
54
- },
55
- "publishConfig": {
56
- "access": "public"
57
- },
58
- "scripts": {
59
- "build": "vite build",
60
- "dev": "vite build --watch",
61
- "type-check": "vue-tsc --noEmit",
62
- "test": "vitest run",
63
- "test:watch": "vitest",
64
- "showcase": "npm --prefix showcase run dev",
65
- "showcase:build": "npm --prefix showcase run build",
66
- "media": "node scripts/media.mjs",
67
- "prepublishOnly": "npm run type-check && npm run test && npm run build"
68
- },
69
- "peerDependencies": {
70
- "nuxt": "^3.0.0",
71
- "vue": "^3.4.0"
72
- },
73
- "peerDependenciesMeta": {
74
- "nuxt": {
75
- "optional": true
76
- }
77
- },
78
- "devDependencies": {
79
- "@vitejs/plugin-vue": "^5.0.0",
80
- "@vue/test-utils": "^2.5.1",
81
- "happy-dom": "^15.11.7",
82
- "playwright-core": "^1.64.1",
83
- "typescript": "^5.3.0",
84
- "vite": "^5.0.0",
85
- "vite-plugin-dts": "^3.7.0",
86
- "vitest": "^2.1.9",
87
- "vue": "^3.4.0",
88
- "vue-tsc": "^2.0.0"
89
- }
90
- }
1
+ {
2
+ "name": "@1337exp/taoui",
3
+ "version": "5.0.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.