@1337exp/taoui 5.29.1 → 5.30.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/package.json CHANGED
@@ -1,105 +1,105 @@
1
- {
2
- "name": "@1337exp/taoui",
3
- "version": "5.29.1",
4
- "description": "Design-token driven Vue 3 / Nuxt component library: palettes with tested contrast, accessible menus and toolbars, navigation that adapts without JS, small charts, 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
- "a11y",
20
- "palette",
21
- "toolbar",
22
- "navigation",
23
- "sparkline",
24
- "color-picker",
25
- "slider",
26
- "toast"
27
- ],
28
- "homepage": "https://666.io",
29
- "bugs": {
30
- "url": "https://github.com/1337exp/taoui/issues"
31
- },
32
- "repository": {
33
- "type": "git",
34
- "url": "git+https://github.com/1337exp/taoui.git"
35
- },
36
- "author": "1337exp",
37
- "license": "MIT",
38
- "type": "module",
39
- "types": "./dist/index.d.ts",
40
- "exports": {
41
- ".": {
42
- "types": "./dist/index.d.ts",
43
- "default": "./dist/index.js"
44
- },
45
- "./styles.css": "./dist/styles.css",
46
- "./palettes.css": "./src/styles/palettes/index.css",
47
- "./styles/*": "./src/styles/*",
48
- "./package.json": "./package.json"
49
- },
50
- "sideEffects": [
51
- "**/*.css"
52
- ],
53
- "files": [
54
- "dist",
55
- "src/styles",
56
- "CHANGELOG.md",
57
- "MIGRATION-5.md",
58
- "skills"
59
- ],
60
- "browserslist": [
61
- "chrome >= 111",
62
- "edge >= 111",
63
- "safari >= 16.4",
64
- "firefox >= 128"
65
- ],
66
- "engines": {
67
- "node": ">=18"
68
- },
69
- "publishConfig": {
70
- "access": "public"
71
- },
72
- "scripts": {
73
- "build": "vite build",
74
- "dev": "vite build --watch",
75
- "type-check": "vue-tsc --noEmit",
76
- "test": "vitest run",
77
- "test:watch": "vitest",
78
- "showcase": "npm --prefix showcase run dev",
79
- "showcase:build": "npm --prefix showcase run build",
80
- "media": "node scripts/media.mjs",
81
- "smoke": "node scripts/consumer-smoke.mjs",
82
- "prepublishOnly": "npm run type-check && npm run test && npm run build && npm run lint:package",
83
- "lint:package": "publint && attw --pack . --profile esm-only --exclude-entrypoints styles.css palettes.css",
84
- "palettes": "node scripts/generate-palettes.mjs",
85
- "skill": "node scripts/generate-skill.mjs"
86
- },
87
- "peerDependencies": {
88
- "vue": "^3.4.0"
89
- },
90
- "devDependencies": {
91
- "@arethetypeswrong/cli": "^0.18.5",
92
- "@types/node": "^20.19.43",
93
- "@vitejs/plugin-vue": "^5.0.0",
94
- "@vue/test-utils": "^2.5.1",
95
- "happy-dom": "^15.11.7",
96
- "playwright-core": "^1.64.1",
97
- "publint": "^0.3.25",
98
- "typescript": "^5.3.0",
99
- "vite": "^5.0.0",
100
- "vite-plugin-dts": "^3.7.0",
101
- "vitest": "^2.1.9",
102
- "vue": "^3.4.0",
103
- "vue-tsc": "^2.0.0"
104
- }
105
- }
1
+ {
2
+ "name": "@1337exp/taoui",
3
+ "version": "5.30.1",
4
+ "description": "Design-token driven Vue 3 / Nuxt component library: palettes with tested contrast, accessible menus and toolbars, navigation that adapts without JS, small charts, 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
+ "a11y",
20
+ "palette",
21
+ "toolbar",
22
+ "navigation",
23
+ "sparkline",
24
+ "color-picker",
25
+ "slider",
26
+ "toast"
27
+ ],
28
+ "homepage": "https://666.io",
29
+ "bugs": {
30
+ "url": "https://github.com/1337exp/taoui/issues"
31
+ },
32
+ "repository": {
33
+ "type": "git",
34
+ "url": "git+https://github.com/1337exp/taoui.git"
35
+ },
36
+ "author": "1337exp",
37
+ "license": "MIT",
38
+ "type": "module",
39
+ "types": "./dist/index.d.ts",
40
+ "exports": {
41
+ ".": {
42
+ "types": "./dist/index.d.ts",
43
+ "default": "./dist/index.js"
44
+ },
45
+ "./styles.css": "./dist/styles.css",
46
+ "./palettes.css": "./src/styles/palettes/index.css",
47
+ "./styles/*": "./src/styles/*",
48
+ "./package.json": "./package.json"
49
+ },
50
+ "sideEffects": [
51
+ "**/*.css"
52
+ ],
53
+ "files": [
54
+ "dist",
55
+ "src/styles",
56
+ "CHANGELOG.md",
57
+ "MIGRATION-5.md",
58
+ "skills"
59
+ ],
60
+ "browserslist": [
61
+ "chrome >= 111",
62
+ "edge >= 111",
63
+ "safari >= 16.4",
64
+ "firefox >= 128"
65
+ ],
66
+ "engines": {
67
+ "node": ">=18"
68
+ },
69
+ "publishConfig": {
70
+ "access": "public"
71
+ },
72
+ "scripts": {
73
+ "build": "vite build",
74
+ "dev": "vite build --watch",
75
+ "type-check": "vue-tsc --noEmit",
76
+ "test": "vitest run",
77
+ "test:watch": "vitest",
78
+ "showcase": "npm --prefix showcase run dev",
79
+ "showcase:build": "npm --prefix showcase run build",
80
+ "media": "node scripts/media.mjs",
81
+ "smoke": "node scripts/consumer-smoke.mjs",
82
+ "prepublishOnly": "npm run type-check && npm run test && npm run build && npm run lint:package",
83
+ "lint:package": "publint && attw --pack . --profile esm-only --exclude-entrypoints styles.css palettes.css",
84
+ "palettes": "node scripts/generate-palettes.mjs",
85
+ "skill": "node scripts/generate-skill.mjs && node scripts/generate-patterns.mjs"
86
+ },
87
+ "peerDependencies": {
88
+ "vue": "^3.4.0"
89
+ },
90
+ "devDependencies": {
91
+ "@arethetypeswrong/cli": "^0.18.5",
92
+ "@types/node": "^20.19.43",
93
+ "@vitejs/plugin-vue": "^5.0.0",
94
+ "@vue/test-utils": "^2.5.1",
95
+ "happy-dom": "^15.11.7",
96
+ "playwright-core": "^1.64.1",
97
+ "publint": "^0.3.25",
98
+ "typescript": "^5.3.0",
99
+ "vite": "^5.0.0",
100
+ "vite-plugin-dts": "^3.7.0",
101
+ "vitest": "^2.1.9",
102
+ "vue": "^3.4.0",
103
+ "vue-tsc": "^2.0.0"
104
+ }
105
+ }
@@ -8,7 +8,9 @@ description: Build Vue 3 interfaces with @1337exp/taoui 5 (TaoUI) — setup, the
8
8
  A Vue 3 component kit on design tokens. Components read **roles** (CSS custom properties `--tao-*`), never colours, so a
9
9
  theme, a palette or a context class changes every component under it. The props of every component, with types and
10
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.
11
+ component you have not used yet. **How to put them together** (the accent budget, choosing a size: small / medium / large and
12
+ density, a toolbar, the footer of a form, a destructive action: what to use when, with a do and a don't) is in [references/patterns.md](references/patterns.md); read
13
+ it before you compose a screen.
12
14
 
13
15
  ## Setup
14
16
 
@@ -143,12 +145,16 @@ Which language to start with: `detectTaoLanguage(['en', 'ru'], { fallback?, requ
143
145
  ## Mistakes to avoid
144
146
 
145
147
  - Writing hex colours or `rgba()` in app CSS instead of roles; inventing token names (check `styles.css`).
146
- - Passing `size` to every control instead of one `tao-size-*` / `tao-density-*` class on the container.
148
+ - Passing `size` to every control instead of one `tao-size-*` / `tao-density-*` class on the container; worse, to some of them
149
+ only (the rest stay medium and the row comes out uneven), or pinning `--tao-control-height` on one (patterns.md, "Controls
150
+ side by side").
147
151
  - Styling `.tao-grid` as a grid (it is `.tao-grid__cells`); expecting `rowHeight` to be a minimum (it is exact).
148
152
  - Putting `TaoMarquee` in a parent without left room: the left fade takes `fade` px (22) left of the text.
149
153
  - Using colour alone for a status; forgetting `aria-label` on an icon-only button (`TaoButton icon="tao-plus"` needs one).
150
154
  - Global `h1 { … }` styles fighting `.tao-prose` (its rules are `:where()`, so yours win by design).
151
155
  - Expecting `variant="danger"` on a button: the colour is `tone="danger"`, the shape is `variant`.
156
+ - A `ghost` or `text` button without `tone` is accent-coloured (amber): in a toolbar, a row or a header it must be
157
+ `tone="neutral"`. The accent is for the one main action, the selected item and the focus (patterns.md, the accent budget).
152
158
  - Importing from deep paths (`@1337exp/taoui/dist/...`); only the package root, `styles.css`, `palettes.css` and
153
159
  `styles/*` are public.
154
160
 
@@ -36,7 +36,7 @@ Showcase section: `#button`
36
36
  | `icon` | `string` | '' | An icon before the text: a name for TaoIcon (tao-plus, your own or a font one). Without text and slot the button is a square of the control height and needs aria-label |
37
37
  | `iconEnd` | `string` | '' | An icon after the text |
38
38
  | `v-model:pressed` | `boolean` | — | A toggle button (Bold, a filter): aria-pressed and the tone tint while pressed. Without it the button is an ordinary one |
39
- | `shortcut` | `string` | — | The key that does the same (N, Ctrl+K): shown at the end of the button, given as aria-keyshortcuts. It only shows the key; listening to it is the app's job |
39
+ | `shortcut` | `string` | — | The key that does the same (N, Ctrl+K): shown at the end of the button, given as aria-keyshortcuts. On an icon-only button it is not printed (no room in the square): it goes to the tooltip, "Label (key)", and to aria-keyshortcuts; your own title wins. It only shows the key; listening to it is the app's job |
40
40
 
41
41
  **Slots, events, notes.** default — the button caption.
42
42
 
@@ -0,0 +1,163 @@
1
+ # TaoUI patterns: what to use when, and why
2
+
3
+ Generated from the Guide of the showcase (`showcase/guide/patterns/`) by `npm run skill`; do not edit by hand.
4
+ Read it before you compose a screen. The page with the live examples: showcase `#patterns` (the Guide book).
5
+ The examples use your own icons (`bold`, `italic`) registered with `registerTaoIcons`; `tao-*` icons are built in.
6
+
7
+ ## The accent budget
8
+
9
+ The accent colour (amber by default) is a signal, and a signal that is on everywhere says nothing. Spend it on three things only: the one main action of a region, the current or selected item, the focus ring.
10
+
11
+ 1. One filled accent button (`variant="primary"`) per region. Next to it: `secondary`, or `ghost` with `tone="neutral"`, or `text`.
12
+ 2. Quiet tools (a toolbar, the actions of a row, icon buttons in a header) are `variant="ghost" tone="neutral"`. A `ghost` or `text` button without `tone` is accent-coloured: use it only for an action that really is the main one in its place.
13
+ 3. Status is `tone` (`success`, `danger`, `warning`, `info`), always with words, never colour alone. A destructive action is `tone="danger"` on the button that destroys; the safe button stays quiet.
14
+ 4. Colours come from roles (`var(--tao-color-…)`), never a hex or an `rgba()` in app CSS.
15
+
16
+ ## Choosing a size
17
+
18
+ Medium is the default, and the right answer unless there is a reason. A size is a decision about a region of the screen, not about a button: how many controls sit close together, how much they matter, and what presses them (a mouse or a finger).
19
+
20
+ | Size | Height | Text | Side padding | Use it for | What it costs |
21
+ |---|---|---|---|---|---|
22
+ | `small` | 26px | 12px | 12px | Tools that serve the content, not the task itself: a toolbar or an editor panel, a filter or settings bar, the actions in a table or list row. Many controls close together, a mouse first. A popover or a menu with a few controls is not that: it stays medium, small ones stick together there. | A small hit area (26px: above the 24px WCAG 2.2 minimum, below the 44px a finger needs) and 12px text. Not for the main action of a screen, not where the only pointer is a finger. |
23
+ | `medium` | 36px | 14px | 16px | Forms and the content of the page. The default: do not set `size` at all. | None; it is the scale everything else is drawn for. |
24
+ | `large` | 44px | 16px | 24px | The one thing the screen is for: a sign-in or checkout button, a call to action on a landing page, a kiosk, a form people fill in on a phone, a reader who needs bigger targets. | Takes room and is loud: in a dense panel it pushes the rest out. |
25
+
26
+ Density is added on top of the size (the height and the padding, not the font), as a class on a container or on `<html>`:
27
+
28
+ | Density | small | medium | large | |
29
+ |---|---|---|---|---|
30
+ | `tao-density-compact` | 22px | 32px | 40px | dense tools and tables |
31
+ | `tao-density-default` | 26px | 36px | 44px | the default |
32
+ | `tao-density-comfortable` | 34px | 44px | 52px | a touch-sized row |
33
+ | `tao-density-auto` | comfortable under a finger (`pointer: coarse`), default with a mouse | | | |
34
+
35
+ 1. Do not change the size unless you know exactly why. Leave medium: it is the scale everything is drawn for. A small control is a deliberate choice for a dense region, and you should be able to name the region and what is crowded in it; "it looks big" is not a reason, and neither is "it is a utility thing".
36
+ 2. Decide for a region, with one class on the container (`class="tao-size-small"`), never for a control (see "Controls side by side").
37
+ 3. Importance is `variant` and `tone`, not size. Inside one region the main action is as tall as its neighbours; a bigger control belongs to a different region (a hero block), not to emphasis in a row.
38
+ 4. Small is for the supporting cast. If the control is why the person came to the screen, it is medium or large.
39
+ 5. A phone is a question of density, not of size: put `tao-density-auto` on `<html>`. The same medium becomes 44px under a finger and stays 36px with a mouse; the font does not change. `large` on a phone is for the hero action only.
40
+ 6. Do not shrink to fit. If it does not fit, wrap, scroll or move the rest into a menu: small controls that are cramped are still cramped.
41
+ 7. Where did the small come from? The size is inherited. In DevTools read the computed `--tao-size` and `--tao-density` on the element, then walk up to the ancestor that sets `tao-size-*` / `tao-density-*` (or a `size` on a `TaoFormField` / `TaoInputGroup`, or a pinned `--tao-control-height`). Nothing else changes the size of a control.
42
+
43
+ ## A toolbar of tools
44
+
45
+ **When.** A bar of formatting or editing tools: text style toggles, undo and redo, a few actions.
46
+
47
+ **Rule.** Every button is `variant="ghost" tone="neutral"`, an icon with an `aria-label`. A toggle is `v-model:pressed`. Group related tools with `TaoToolbarGroup` and split the groups with `TaoToolbarSeparator`.
48
+
49
+ **Do:**
50
+
51
+ ```vue
52
+ <TaoToolbar label="Formatting">
53
+ <TaoToolbarGroup label="Text style">
54
+ <TaoButton v-model:pressed="bold" variant="ghost" tone="neutral" icon="bold" aria-label="Bold" />
55
+ <TaoButton v-model:pressed="italic" variant="ghost" tone="neutral" icon="italic" aria-label="Italic" />
56
+ </TaoToolbarGroup>
57
+ <TaoToolbarSeparator />
58
+ <TaoButton variant="ghost" tone="neutral" icon="tao-undo" aria-label="Undo" />
59
+ <TaoButton variant="ghost" tone="neutral" icon="tao-redo" aria-label="Redo" />
60
+ </TaoToolbar>
61
+ ```
62
+
63
+ **Don't** (No `tone`: every tool is amber):
64
+
65
+ ```vue
66
+ <TaoToolbar label="Formatting">
67
+ <TaoToolbarGroup label="Text style">
68
+ <TaoButton v-model:pressed="bold" variant="ghost" icon="bold" aria-label="Bold" />
69
+ <TaoButton v-model:pressed="italic" variant="ghost" icon="italic" aria-label="Italic" />
70
+ </TaoToolbarGroup>
71
+ <TaoToolbarSeparator />
72
+ <TaoButton variant="ghost" icon="tao-undo" aria-label="Undo" />
73
+ <TaoButton variant="ghost" icon="tao-redo" aria-label="Redo" />
74
+ </TaoToolbar>
75
+ ```
76
+
77
+ **Why.** In a toolbar every button is a tool and none is the main one, so none may take the accent. Left amber, the bar shouts, and the one thing that must stand out, which toggles are on, is lost: it is the same colour as the rest. In neutral the pressed toggle is the only lit thing.
78
+
79
+ ## The footer of a form or dialog
80
+
81
+ **When.** The buttons at the bottom of a form, a modal or a drawer: confirm and cancel.
82
+
83
+ **Rule.** The confirming action is the one primary button, at the end. Cancel is `secondary` (or `ghost` with `tone="neutral"`), before it.
84
+
85
+ **Do:**
86
+
87
+ ```vue
88
+ <TaoFlex justify="flex-end" :gap="8">
89
+ <TaoButton variant="secondary">Cancel</TaoButton>
90
+ <TaoButton>Save</TaoButton>
91
+ </TaoFlex>
92
+ ```
93
+
94
+ **Don't** (Two filled accent buttons: Cancel looks as important as Save):
95
+
96
+ ```vue
97
+ <TaoFlex justify="flex-end" :gap="8">
98
+ <TaoButton>Cancel</TaoButton>
99
+ <TaoButton>Save</TaoButton>
100
+ </TaoFlex>
101
+ ```
102
+
103
+ **Why.** Two filled accent buttons side by side make the eye choose between them. The footer has one answer the user is expected to give; the other button is the way out, and it looks like one.
104
+
105
+ ## Controls side by side: one size
106
+
107
+ **When.** A row or a panel with several controls: a segmented switch, a select, buttons, inputs. Also the content of a popover.
108
+
109
+ **Rule.** Put one context class on the container: `class="tao-size-small"` (and `tao-density-*`). Do not pass `size` to some of the controls, and do not pin a height (`--tao-control-height: 32px`, `height: 32px`) on one of them. An explicit `size` is for the one control that must stand out. A `TaoPopover` panel, a select list and a combobox list carry the size and the density of where they hang from.
110
+
111
+ **Do:**
112
+
113
+ ```vue
114
+ <TaoFlex class="tao-size-small" align="center" :gap="8">
115
+ <TaoSegmented v-model="mode" aria-label="Mode">
116
+ <TaoSegmentedOption value="grid">Grid</TaoSegmentedOption>
117
+ <TaoSegmentedOption value="list">List</TaoSegmentedOption>
118
+ </TaoSegmented>
119
+ <TaoSelect v-model="palette" :options="palettes" :clearable="false" aria-label="Palette" />
120
+ <TaoButton variant="secondary">Apply</TaoButton>
121
+ </TaoFlex>
122
+ ```
123
+
124
+ **Don't** (On purpose: `size="small"` on the switch only, so it is shorter than the select and the button beside it):
125
+
126
+ ```vue
127
+ <TaoFlex align="center" :gap="8">
128
+ <TaoSegmented v-model="mode" size="small" aria-label="Mode">
129
+ <TaoSegmentedOption value="grid">Grid</TaoSegmentedOption>
130
+ <TaoSegmentedOption value="list">List</TaoSegmentedOption>
131
+ </TaoSegmented>
132
+ <TaoSelect v-model="palette" :options="palettes" :clearable="false" aria-label="Palette" />
133
+ <TaoButton variant="secondary">Apply</TaoButton>
134
+ </TaoFlex>
135
+ ```
136
+
137
+ **Why.** `size` is a prop with a default of medium. Set it on the controls you remember and the rest stay medium: the row comes out uneven, a small switch beside a tall select. A pinned height is the same thing by hand. The class makes them one by construction, also for the controls added later and for a panel in the body.
138
+
139
+ ## A destructive action
140
+
141
+ **When.** Delete, discard, reset: something that cannot be taken back.
142
+
143
+ **Rule.** `tone="danger"` on the button that destroys, the safe choice quiet (`secondary`). For a question in its own window use `await confirm().title(…).message(…).danger()`: it resolves to a boolean.
144
+
145
+ **Do:**
146
+
147
+ ```vue
148
+ <TaoFlex justify="flex-end" :gap="8">
149
+ <TaoButton variant="secondary">Keep</TaoButton>
150
+ <TaoButton tone="danger" icon="tao-trash">Delete</TaoButton>
151
+ </TaoFlex>
152
+ ```
153
+
154
+ **Don't** (Red on the safe button, the accent on the one that deletes):
155
+
156
+ ```vue
157
+ <TaoFlex justify="flex-end" :gap="8">
158
+ <TaoButton variant="secondary" tone="danger">Keep</TaoButton>
159
+ <TaoButton icon="tao-trash">Delete</TaoButton>
160
+ </TaoFlex>
161
+ ```
162
+
163
+ **Why.** The accent says "the normal main thing", and a delete wearing it looks like any other action. Red on the safe button inverts the warning: the colour then points at the wrong choice.