@1337exp/taoui 5.50.0 → 5.51.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 +26 -0
- package/README.md +5 -5
- package/README.ru.md +5 -5
- package/dist/index.d.ts +234 -4
- package/dist/index.js +942 -126
- package/dist/index.js.map +1 -1
- package/dist/styles.css +1 -1
- package/package.json +2 -2
- package/skills/taoui/SKILL.md +10 -5
- package/skills/taoui/references/components.md +14 -6
- package/skills/taoui/references/patterns.md +273 -273
- package/skills/taoui/references/starters.md +435 -0
- package/src/styles/base.css +4 -4
- package/src/styles/tokens/primitives.css +8 -5
- package/src/styles/tokens/semantic.css +8 -2
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@1337exp/taoui",
|
|
3
|
-
"version": "5.
|
|
3
|
+
"version": "5.51.0",
|
|
4
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
5
|
"keywords": [
|
|
6
6
|
"vue",
|
|
@@ -82,7 +82,7 @@
|
|
|
82
82
|
"prepublishOnly": "npm run type-check && npm run test && npm run build && npm run lint:package",
|
|
83
83
|
"lint:package": "publint && attw --pack . --profile esm-only --exclude-entrypoints styles.css palettes.css",
|
|
84
84
|
"palettes": "node scripts/generate-palettes.mjs",
|
|
85
|
-
"skill": "node scripts/generate-skill.mjs && node scripts/generate-patterns.mjs"
|
|
85
|
+
"skill": "node scripts/generate-skill.mjs && node scripts/generate-patterns.mjs && node scripts/generate-starters.mjs"
|
|
86
86
|
},
|
|
87
87
|
"peerDependencies": {
|
|
88
88
|
"vue": "^3.4.0"
|
package/skills/taoui/SKILL.md
CHANGED
|
@@ -10,7 +10,9 @@ theme, a palette or a context class changes every component under it. The props
|
|
|
10
10
|
defaults, are in [references/components.md](references/components.md); read the section you need before writing a
|
|
11
11
|
component you have not used yet. **How to put them together** (the accent budget, choosing a size: small / medium / large and
|
|
12
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.
|
|
13
|
+
it before you compose a screen. **A new app starts from a starter** (a whole screen in one file, with the decisions it makes
|
|
14
|
+
and why: the app shell with a side menu, `TaoNav fill`) in [references/starters.md](references/starters.md); copy the one
|
|
15
|
+
that fits instead of composing the shell from scratch.
|
|
14
16
|
|
|
15
17
|
## Setup
|
|
16
18
|
|
|
@@ -78,7 +80,10 @@ choose a text colour, WCAG 2 to promise a number.
|
|
|
78
80
|
number is one column on compact. `rowHeight` is the exact row height (a mosaic: pictures are cropped).
|
|
79
81
|
- `TaoNav` — app navigation from one list: a bottom bar, a rail or a drawer, `layout="auto"` by its own width; put the page
|
|
80
82
|
in its default slot and it lays it out. `floating` makes the bar a detached pill (the FAB is your own button beside
|
|
81
|
-
it). `
|
|
83
|
+
it). `fill` makes it the shell of an app: it takes its parent's height (`html, body, #app { height: 100% }`), the
|
|
84
|
+
page scrolls inside `.tao-nav__content` and the footer stands at the bottom of the side panel; more than one child of
|
|
85
|
+
`#action` stack one under the other; `--tao-nav-compact` (1 on the bar and the rail, 0 on the side panel) is there for
|
|
86
|
+
your own pieces in the slots. `select(id, event)` + `event.preventDefault()` to route with a router. Widths `--tao-nav-rail-width` /
|
|
82
87
|
`--tao-nav-drawer-width`; the action button may take `shortcut="N"` (shown in the side panel, hidden when round). `surface="glass"` for a
|
|
83
88
|
translucent bar over the page (as on TaoCard; it turns solid where blur is off). `#footer`: a small line under the
|
|
84
89
|
items (version, About) in the rail and the side panel. `badgeTone="neutral"`: grey counters, the accent on the
|
|
@@ -102,7 +107,7 @@ choose a text colour, WCAG 2 to promise a number.
|
|
|
102
107
|
|
|
103
108
|
- `TaoDocTabs` (the tabs of open documents: `items` `{ value, label, dirty?, preview?, closable? }`, `v-model` the active one; it only draws the row: `@close`, `@pin`, `@reorder(from, to)`, `@menu` are requests the app carries out), `TaoCommandList` (the field and the list of the palette with no window, for a page, a panel or a `TaoPopover`; `@select` closes nothing), `TaoCommandPalette` (a dialog, `modal="false"` for a panel with no dimming, the whole screen on a phone by default, that searches `items` `{ id, label, group?, shortcut?, keywords?, disabled? }`, `Ctrl+K` style: you open it from your own key with `v-model`, `@select` runs the pick; the search alone is `matchCommands`), `TaoModal` (`fullscreen`, `fullscreen="narrow"` for a page on a phone), `TaoDrawer` (`side="bottom"` is the phone's
|
|
104
109
|
bottom sheet) — v-model; Escape closes the top layer only. `TaoPopover`, `TaoTooltip` (`placement`; the tip is the opposite of the theme; `shortcut` adds the key as a key cap; `bold` is on, semi-bold text; `animated` is the fade, off by default: a share of the base duration, `0` off, `1` base, `2` twice, or the token `--tao-tooltip-motion`). `TaoKbd` is the one look for a key (`variant` `cap` / `plain`): do not draw your own `<kbd>`.
|
|
105
|
-
- Menus share one engine: `TaoDropdownMenu`, `TaoMenubar`, `TaoContextMenu`, `TaoMenu` (the panel for your own shell). `TaoMenu` and `TaoPopover` take `anchor` as an element or a point `{ x, y }` of the screen (a menu at a drop point or at the pointer; recipe for a context menu: on `contextmenu` prevent the default and open at `clientX` / `clientY`, or just use `TaoContextMenu`).
|
|
110
|
+
- Menus share one engine: `TaoDropdownMenu`, `TaoMenubar`, `TaoContextMenu`, `TaoMenu` (the panel for your own shell). `TaoMenu` and `TaoPopover` take `anchor` as an element or a point `{ x, y }` of the screen (a menu at a drop point or at the pointer; recipe for a context menu: on `contextmenu` prevent the default and open at `clientX` / `clientY`, or just use `TaoContextMenu`). `TaoDropdownMenu block`: the button fills its place and draws nothing, for a whole chip of yours in `#button` (never style `.tao-dropdown-menu__button` from outside).
|
|
106
111
|
Items are a data tree `TaoMenuItem[]`: `{ id, label, icon?, shortcut?, disabled?, items? }`,
|
|
107
112
|
`{ type: 'checkbox' | 'radio', checked }`, `{ type: 'label' | 'separator' }`. `@select="id => …"`. `closeOnScroll`.
|
|
108
113
|
With TaoUX, `createCommands().toMenu(layout)` builds this tree and binds the same shortcuts.
|
|
@@ -119,7 +124,7 @@ choose a text colour, WCAG 2 to promise a number.
|
|
|
119
124
|
## Data and display
|
|
120
125
|
|
|
121
126
|
`TaoTable` (columns, sort, row click), `TaoPagination` (`pageInput` for hundreds of pages), `TaoList` / `TaoListItem` (`roving`: one Tab stop, arrows between the rows),
|
|
122
|
-
`TaoTree` (expand, select, tri-state `checkable`, lazy `load`), `TaoStages`, `TaoTimeline` (`active` makes it a progress),
|
|
127
|
+
`TaoTree` (expand, select, tri-state `checkable`, lazy `load`, a row context `menu`, `hint` / `tone` on a node, rows moved by drag and Ctrl+X / Ctrl+V through `@move` + `moveTreeNodes`), `TaoStages`, `TaoTimeline` (`active` makes it a progress),
|
|
123
128
|
`TaoTag`, `TaoAvatar`, `TaoImage`, `TaoCarousel`, `TaoCard` (`#media`, `#title`, `#sub`, `#footer`, `#corner`, `closable`,
|
|
124
129
|
`stripe` + `stripeTone`), `TaoBlock`, `TaoTabs`, `TaoBreadcrumb`, `TaoLink`, `TaoStretchedLink` (a whole card or row as one link, the buttons inside still work: `tao-stretched` on the container, `tao-stretched-raise` on a control that must click by itself; never `filter` / `transform` on the link), `TaoSpoiler` / `TaoSpoilerGroup`, `TaoCounter`,
|
|
125
130
|
`TaoCopy`, `TaoTour` (a guided tour: `:step` / `:index` / `:count`, events `next` / `prev` / `skip`; it only draws, the state is yours or TaoUX `useTour`; a step is `{ id, target?, title?, text?, placement? }`), `TaoThemeToggle` (the light / dark switch as an icon button: flips `data-tao-mode` of `<html>`, or `v-model` with `:apply="false"`; `system` adds a third state, «follow the OS» (click: system → light → dark; `v-model` then holds `'system'` too, resolve it with `resolveTaoMode()`); `#icon="{ mode, choice, next }"` for your own glyph), `TaoLanguageSwitch` (the language of the interface: a globe that opens a list of `:languages="['ru', 'en']"`, each under its own name from `Intl.DisplayNames` (`taoLanguageName(code)`); `v-model` is the code; it writes `<html lang>` unless `:apply="false"`; `icon-only` for a phone; the texts, the storage and `setTaoLocale` are the app's; not flags, not `RU | EN` in a `TaoSegmented`), `TaoMarquee` (one line that runs round only when it does not fit), `TaoScrubber` (play / pause + time),
|
|
@@ -142,7 +147,7 @@ only of straight lines through the middle (a plus), so they stay crisp when smal
|
|
|
142
147
|
`app.use(TaoUI, { locale: localeRu })`; `setTaoLocale(localeEn)` switches at run time without a reload; a prop passed by
|
|
143
148
|
hand (`placeholder`, `closeLabel`…) always wins. For SSR per request, `provideTaoLocale`.
|
|
144
149
|
|
|
145
|
-
Scrollbars: thin (
|
|
150
|
+
Scrollbars: thin (6px) by default; `--tao-scrollbar-size` / `-thumb` / `-track` / `-width` (Firefox) change them on the page or on a block, the class `tao-native-scrollbars` (on `<html>` or a block) gives the browser's own back.
|
|
146
151
|
|
|
147
152
|
Which language to start with: `detectTaoLanguage(['en', 'ru'], { fallback?, requested? })` returns one of your languages by `navigator.languages` (`parseAcceptLanguage(header)` for a server); it only answers, `setTaoLocale` sets. A locale text may be plural forms `{ one, few, many, other }` (`formatTaoText(text, { count }, code)` does it for your own texts); a plain string stays the same for every number.
|
|
148
153
|
|
|
@@ -790,8 +790,8 @@ Showcase section: `#tree`
|
|
|
790
790
|
|
|
791
791
|
| Prop | Type | Default | Notes |
|
|
792
792
|
|---|---|---|---|
|
|
793
|
-
| `nodes` | `TaoTreeNode[]` | — | { id, label, icon?, children?, hasChildren?, disabled? }. hasChildren without children — the children come from load when it opens |
|
|
794
|
-
| `v-model:expanded` | `string[]` | own | Ids of the expanded nodes. Without a model the tree keeps them itself |
|
|
793
|
+
| `nodes` | `TaoTreeNode[]` | — | { id, label, icon?, children?, hasChildren?, disabled?, hint?, tone? }. hasChildren without children — the children come from load when it opens. hint — a quiet note after the label («library root»). tone — the colour of the label: 'muted' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger' |
|
|
794
|
+
| `v-model:expanded` | `string[]` | own | Ids of the expanded nodes. Without a model the tree keeps them itself. A saved view can be put back: open lazy folders load by themselves, level by level; a failed load closes the folder (load-error) |
|
|
795
795
|
| `selection` | `'none' \| 'single' \| 'multiple'` | 'single' | Selection mode. none — a click on a folder toggles it |
|
|
796
796
|
| `v-model:selected` | `string \| string[] \| null` | own | An id (single) or a list of ids (multiple) |
|
|
797
797
|
| `checkable` | `boolean` | false | Checkboxes. A parent is checked, unchecked or mixed by its leaves; a click on a parent toggles the whole branch |
|
|
@@ -800,8 +800,14 @@ Showcase section: `#tree`
|
|
|
800
800
|
| `size` | `'small' \| 'medium' \| 'large'` | inherited | Row height, as for the controls; the density works too |
|
|
801
801
|
| `ariaLabel` | `string` | 'Tree' | Accessible name of the tree |
|
|
802
802
|
| `loadingLabel` | `string` | 'Loading…' | The hint of the spinner |
|
|
803
|
+
| `menu` | `TaoMenuItem[] \| (node, selected) => TaoMenuItem[]` | — | The context menu of a row: right click, the Menu key, Shift+F10. A right click outside the selection selects the row first (no select event), inside it keeps the selection. An empty list leaves the browser's menu |
|
|
804
|
+
| `menuLabel` | `string` | 'Context menu' | Accessible name of the menu |
|
|
805
|
+
| `@move` | `(move: TaoTreeMove) => void \| Promise` | — | Turns moving rows on: dragging and Ctrl+X / Ctrl+C / Ctrl+V. move = { ids, parentId, index, targetId, position, copy }; index is the place among the children of parentId once the moved ones are taken out. The tree changes nothing: make the move yourself (moveTreeNodes(nodes, move)); return a promise and the rows wait, a rejected one comes as move-error |
|
|
806
|
+
| `sort` | `'none' \| 'name' \| (a, b) => number` | 'none' | The order of the rows. none — the data's, a drag puts a row between others. name — folders first, by name, numbers as numbers («file 2» before «file 10»); a function — your own compare. With a sort a drag only changes the folder: onto a folder puts the rows in it, onto any other row into its folder, no line between rows. nodes is not changed |
|
|
807
|
+
| `movable` | `boolean \| (node) => boolean` | true | Which rows can be moved (disabled ones never) |
|
|
808
|
+
| `canDrop` | `(move) => boolean` | — | May the rows go there: false shows a «no» cursor and no mark. Into itself and its descendants the tree refuses anyway |
|
|
803
809
|
|
|
804
|
-
**Slots, events, notes.** #icon, #label, #actions — { node, level, expanded, selected }; the actions show on hover and focus (always on a touch screen). Events: update:expanded / selected / checked, select(node) — a click, Enter, Space without checkboxes; load-error(node, error) — the node stays closed. Keys: ↑ ↓, → opens or goes in, ← closes or goes to the parent, Home / End, * opens the siblings, letters search, Enter selects, Space checks.
|
|
810
|
+
**Slots, events, notes.** #icon, #label, #actions — { node, level, expanded, selected }; the actions show on hover and focus (always on a touch screen). Events: update:expanded / selected / checked, select(node) — a click, Enter, Space without checkboxes; open(node) — a double click or Enter on a node without children (on a branch they open and close it); load-error(node, error) — the node stays closed; menu(node, event) — a menu was asked for on a row (preventDefault — a menu of your own instead of ours and the browser's); menu-select(id, node, selected) — an item of menu; move-error(move, error) — the promise of @move was rejected. Moving by the pointer: the middle of a folder puts the rows inside, between rows there, and below the last row of a folder going left takes them out of it; a closed folder under the pointer opens, the list scrolls at its edge, Ctrl or Alt makes a copy, Esc cancels; a selected row takes the whole selection. The selection of a tree without the focus is grey, with the focus the accent. Keys: ↑ ↓, → opens or goes in, ← closes or goes to the parent, Home / End, * opens the siblings, letters search, Enter selects and acts as a double click, Space checks, Menu / Shift+F10 — the menu, with @move: Ctrl+X / Ctrl+C — cut / copy, Ctrl+V on a folder — to its end, on a row — after it, Esc — forget.
|
|
805
811
|
|
|
806
812
|
## TaoList
|
|
807
813
|
|
|
@@ -1114,6 +1120,7 @@ Showcase section: `#dropdown`
|
|
|
1114
1120
|
| `size` | `'small' \| 'medium' \| 'large'` | — | The button becomes a square of that control height: a compact kebab for a list row. Without it — the padding round the icon |
|
|
1115
1121
|
| `dots` | `'vertical' \| 'horizontal'` | 'vertical' | The three dots of the button: upright ⋮ (a narrow column, a toolbar) or lying ⋯ (a row of a table or a list, the corner of a card). Ignored when #icon or #button is given |
|
|
1116
1122
|
| `tabbable` | `boolean` | true | The button is a Tab stop. Off: it leaves the Tab order (the row has its own menu key) and still opens by a click |
|
|
1123
|
+
| `block` | `boolean` | false | The button fills the width and the height of its place and draws nothing of its own (no padding, no background, the corners of its parent): for a trigger that is a whole chip of yours in #button, the project under the main action of TaoNav, an account in a header. The hover and the focus ring go round the chip, the ring inside, so a clipping box does not cut it |
|
|
1117
1124
|
|
|
1118
1125
|
**Slots, events, notes.** #icon — the trigger icon, #button — the whole button content, #item="{ item, id, label, icon }" — your own item face. The select event — the item id. shortcut is a ready string to show: the menu neither parses nor listens to it.
|
|
1119
1126
|
|
|
@@ -1127,7 +1134,7 @@ Showcase section: `#dropdown`
|
|
|
1127
1134
|
| `open` | `boolean` | | Whether it is open. The owner closes it on the close event |
|
|
1128
1135
|
| `anchor` | `HTMLElement \| { x, y, width?, height? } \| null` | | What the panel hangs from: an element, or a point of the screen in viewport coordinates (a menu at the pointer, no anchor element). A point follows nothing: the panel is fixed, flips and shifts at the edges, and on close the focus goes back to where it was before opening. Change the point and the menu moves; an element can be swapped for a point and back |
|
|
1129
1136
|
| `placement` | `TaoPlacement` | 'bottom-end'; 'bottom-start' at a point | Side and alignment. At a point the default puts the top-left corner at it, 4px below (the point is not covered by the first item) |
|
|
1130
|
-
| `closeOnScroll` | `boolean` | false | Close when the page or a scroll container scrolls. Off: a panel on an element follows it, a panel at a point stays at its screen point |
|
|
1137
|
+
| `closeOnScroll` | `boolean` | false | Close when the page or a scroll container that holds the anchor scrolls (for a point, the element under it); a scroll elsewhere (a carousel) does not close it. Off: a panel on an element follows it, a panel at a point stays at its screen point |
|
|
1131
1138
|
| `label` | `string` | — | Accessible name of the menu |
|
|
1132
1139
|
|
|
1133
1140
|
**Slots, events, notes.** Event select — the item id, close(reason) — the menu asks to be closed (escape / select / outside / tab). The panel for your own shells: a button, a context menu, a menu bar.
|
|
@@ -1189,7 +1196,7 @@ Showcase section: `#menubar`
|
|
|
1189
1196
|
| `items` | `TaoMenuItem[]` | — | The entries, as in TaoMenu |
|
|
1190
1197
|
| `disabled` | `boolean` | false | Leave the browser menu alone |
|
|
1191
1198
|
| `menuLabel` | `string` | 'Context menu' | Accessible name of the menu |
|
|
1192
|
-
| `closeOnScroll` | `boolean` | true | Close when the page or a scroll container scrolls (the point moves away from under the menu). false keeps it at the screen point. Scrolling inside the menu never closes it |
|
|
1199
|
+
| `closeOnScroll` | `boolean` | true | Close when the page or a scroll container with the point of the menu scrolls (the point moves away from under the menu); a scroll elsewhere does not close it. false keeps it at the screen point. Scrolling inside the menu never closes it |
|
|
1193
1200
|
|
|
1194
1201
|
**Slots, events, notes.** default — the area where the right click (or the Menu key / Shift+F10) opens the menu; the wrapper does not take part in the layout (display: contents). #item — your own item face. Events select — the item id, open({ x, y }) — where it opened. On iOS a long press sends no contextmenu: give it a button there.
|
|
1195
1202
|
|
|
@@ -1232,10 +1239,11 @@ Showcase section: `#tao-nav`
|
|
|
1232
1239
|
| `moreLabel` | `string` | 'More' | The label of «More» |
|
|
1233
1240
|
| `indicator` | `'pill' \| 'line'` | 'pill' | How the current section is marked: a tint behind the item, or the accent colour and a short line (under the item in the bar, along its start edge on the side; auto moves it) |
|
|
1234
1241
|
| `floating` | `boolean` | false | In the bar look, a detached pill above the page: inset from the edges and above the safe area, round, with a shadow; the active item is a pill too. The rail and the side panel do not change. The main action of the screen goes beside it as your own round button, not into the bar |
|
|
1242
|
+
| `fill` | `boolean` | false | The shell of an app: TaoNav takes the height of its parent (give it one: html, body, #app { height: 100% }), the page scrolls inside .tao-nav__content or its own panes instead of the document, and the footer stands at the bottom of the side panel. No page scrollbar comes and goes, nothing shifts. A ready shell is in the Guide, «Starters» |
|
|
1235
1243
|
| `badgeTone` | `'accent' \| 'neutral'` | 'accent' | The counters: accent on every item, or neutral — grey, the accent on the current item only. A dot (badge: true) stays the accent |
|
|
1236
1244
|
| `surface` | `'flat' \| 'glass' \| 'grain'` | 'flat' | What the panel is made of, as on TaoCard: glass lets the page show blurred through the bar as it scrolls under it (solid where blur is not supported or less transparency is asked) |
|
|
1237
1245
|
|
|
1238
|
-
**Slots, events, notes.** default — the page: TaoNav lays it out next to the navigation (the bar sticks to the bottom, on the side the list sticks to the top; env(safe-area-inset-bottom) is kept). Without the slot it is a standalone panel with a border. #label — your own item label ({ item, active }). Structure: .tao-nav is the whole layout (the navigation and the page), .tao-nav__panel the navigation, .tao-nav__content the page; a style for the menu goes on the panel (or use surface), not on the root. #footer — a small line under the items in the rail and the side panel (the version, «About», a link); the bar does not show it. #action — the main action of the screen: a TaoButton with icon and its text in <span class="tao-nav__action-label">; the bar puts it round above itself at the end side (above the pill with floating), the rail round at the top, the side panel extended with the text at the top; in the round looks the text is hidden but stays the name of the button (a shortcut on it too). The side panel gives the button its own corners; --tao-nav-action-radius: var(--tao-radius-full) makes it a pill. --tao-nav-rail-width (80px) and --tao-nav-drawer-width (240px) set the widths. Events: update:modelValue, select(id, event) — event.preventDefault() keeps a link from navigating, to route it yourself.
|
|
1246
|
+
**Slots, events, notes.** default — the page: TaoNav lays it out next to the navigation (the bar sticks to the bottom, on the side the list sticks to the top; env(safe-area-inset-bottom) is kept). Without the slot it is a standalone panel with a border. #label — your own item label ({ item, active }). Structure: .tao-nav is the whole layout (the navigation and the page), .tao-nav__panel the navigation, .tao-nav__content the page; a style for the menu goes on the panel (or use surface), not on the root. #footer — a small line under the items in the rail and the side panel (the version, «About», a link); the bar does not show it. #action — the main action of the screen: a TaoButton with icon and its text in <span class="tao-nav__action-label">; the bar puts it round above itself at the end side (above the pill with floating), the rail round at the top, the side panel extended with the text at the top; in the round looks the text is hidden but stays the name of the button (a shortcut on it too). Several children of #action stand one under the other (the action, then a project chip). --tao-nav-compact is 1 on the bar and the rail and 0 on the side panel, for your own pieces in the slots. The side panel gives the button its own corners; --tao-nav-action-radius: var(--tao-radius-full) makes it a pill. --tao-nav-rail-width (80px) and --tao-nav-drawer-width (240px) set the widths. Events: update:modelValue, select(id, event) — event.preventDefault() keeps a link from navigating, to route it yourself.
|
|
1239
1247
|
|
|
1240
1248
|
## TaoTabs
|
|
1241
1249
|
|