vectis-ui 0.8.0 → 0.8.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/README.md +67 -333
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,48 +1,79 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<a href="https://vectis-ui.com">
|
|
3
|
+
<img src="https://vectis-ui.com/favicon.svg" alt="Vectis UI logo" width="96" />
|
|
4
|
+
</a>
|
|
5
|
+
</p>
|
|
2
6
|
|
|
3
|
-
|
|
7
|
+
<h1 align="center">Vectis UI</h1>
|
|
4
8
|
|
|
5
|
-
|
|
9
|
+
<p align="center">
|
|
10
|
+
A Vue 3 component library built for modern browsers.
|
|
11
|
+
</p>
|
|
6
12
|
|
|
7
|
-
|
|
8
|
-
-
|
|
9
|
-
-
|
|
10
|
-
-
|
|
13
|
+
<p align="center">
|
|
14
|
+
<a href="https://www.npmjs.com/package/vectis-ui"><img src="https://img.shields.io/npm/v/vectis-ui" alt="npm version" /></a>
|
|
15
|
+
<a href="https://github.com/Jypyx/vectis-ui/actions/workflows/ci.yml"><img src="https://github.com/Jypyx/vectis-ui/actions/workflows/ci.yml/badge.svg" alt="CI status" /></a>
|
|
16
|
+
<a href="https://github.com/Jypyx/vectis-ui/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/vectis-ui" alt="MIT license" /></a>
|
|
17
|
+
</p>
|
|
11
18
|
|
|
12
|
-
|
|
19
|
+
<p align="center">
|
|
20
|
+
<a href="https://vectis-ui.com">Documentation</a> ·
|
|
21
|
+
<a href="https://vectis-ui.com/docs/installation/">Installation</a> ·
|
|
22
|
+
<a href="https://github.com/Jypyx/vectis-ui/blob/main/CHANGELOG.md">Changelog</a> ·
|
|
23
|
+
<a href="https://github.com/Jypyx/vectis-ui">GitHub</a>
|
|
24
|
+
</p>
|
|
25
|
+
|
|
26
|
+
## Introduction
|
|
27
|
+
|
|
28
|
+
Vectis UI is a set of Vue 3 components written in TypeScript.
|
|
29
|
+
The whole look is driven by CSS custom properties (`--vectis-*`), so you can retheme the library, or a single part of a page, without rebuilding anything. Styles live in cascade layers, which means your own CSS wins without fighting over specificity.
|
|
30
|
+
|
|
31
|
+
A few things you get out of the box:
|
|
32
|
+
|
|
33
|
+
- **No runtime dependency** other than Vue itself.
|
|
34
|
+
- **Pay for what you import.** Each component ships as its own module with its own stylesheet.
|
|
35
|
+
- **SSR-safe**, so it works with Nuxt 3 and 4 without a module or a plugin.
|
|
36
|
+
- **Accessible by default.** Keyboard support and ARIA semantics on every component, with axe checks run in CI against both the light and the dark theme.
|
|
37
|
+
- **Light and dark themes**, switchable on any DOM subtree with a `data-theme` attribute.
|
|
38
|
+
- **English and French** built in, and any other language can be added from your app.
|
|
39
|
+
- **No icon font required.** The icons the library draws are embedded SVGs, and you can plug in your own icon set.
|
|
40
|
+
|
|
41
|
+
## Quick start
|
|
42
|
+
|
|
43
|
+
Install the package:
|
|
13
44
|
|
|
14
45
|
```bash
|
|
15
|
-
|
|
46
|
+
npm install vectis-ui
|
|
47
|
+
# or
|
|
48
|
+
pnpm add vectis-ui
|
|
49
|
+
# or
|
|
50
|
+
yarn add vectis-ui
|
|
16
51
|
```
|
|
17
52
|
|
|
53
|
+
Import the global stylesheet once, in your app's entry point:
|
|
54
|
+
|
|
18
55
|
```ts
|
|
19
56
|
// main.ts
|
|
20
57
|
import 'vectis-ui/styles.css'
|
|
21
58
|
```
|
|
22
59
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
Those figures are measured, not estimated: `pnpm --filter vectis-ui bench:size` prints them from the built artefact and holds them to a committed baseline, so they cannot drift out of step with the library again.
|
|
60
|
+
Then import the components you need:
|
|
26
61
|
|
|
27
62
|
```vue
|
|
28
63
|
<script setup lang="ts">
|
|
29
64
|
import { ref } from 'vue'
|
|
30
|
-
import { VButton, VInput
|
|
65
|
+
import { VButton, VInput } from 'vectis-ui'
|
|
31
66
|
|
|
32
67
|
const email = ref('')
|
|
33
68
|
</script>
|
|
34
69
|
|
|
35
70
|
<template>
|
|
36
|
-
<VInput v-model="email" type="email"
|
|
37
|
-
<VButton
|
|
38
|
-
Subscribe
|
|
39
|
-
</VButton>
|
|
71
|
+
<VInput v-model="email" type="email" label="Email" />
|
|
72
|
+
<VButton>Subscribe</VButton>
|
|
40
73
|
</template>
|
|
41
74
|
```
|
|
42
75
|
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
The library is pre-built as ESM and SSR-safe (no `window`/`document` access outside the client lifecycle). No module and no plugin needed:
|
|
76
|
+
Using Nuxt? Declare the stylesheet in `nuxt.config.ts` instead, so it's injected during server rendering:
|
|
46
77
|
|
|
47
78
|
```ts
|
|
48
79
|
// nuxt.config.ts
|
|
@@ -51,338 +82,41 @@ export default defineNuxtConfig({
|
|
|
51
82
|
})
|
|
52
83
|
```
|
|
53
84
|
|
|
54
|
-
|
|
55
|
-
<script setup lang="ts">
|
|
56
|
-
import { VButton, VBadge } from 'vectis-ui'
|
|
57
|
-
</script>
|
|
58
|
-
```
|
|
59
|
-
|
|
60
|
-
Named imports are tree-shaken by Vite/Nitro. No `build.transpile` required.
|
|
61
|
-
|
|
62
|
-
Component CSS travels with the component as a plain static `import`, which Vite, Nitro and webpack all turn into a render-blocking `<link>` — including for a lazily loaded route, whose stylesheet is awaited before the chunk runs. The one setup that would flash is a hand-rolled SSR server that injects its client CSS **through JavaScript** (`vite-plugin-css-injected-by-js`, webpack's `style-loader`): there, the first paint carries the core (tokens, layout, hidden popovers) but not the components' internal rules. Keep the client CSS extracted to a file and the question does not arise.
|
|
63
|
-
|
|
64
|
-
For the locale and the icons, put the configuration in a **universal** plugin — `plugins/vectis.ts`, never `plugins/vectis.client.ts`: a client-only configuration would make the server and client renders diverge, hence a hydration mismatch. See [Internationalization](#internationalization).
|
|
65
|
-
|
|
66
|
-
## Theming
|
|
67
|
-
|
|
68
|
-
### Token architecture
|
|
69
|
-
|
|
70
|
-
Two levels of custom properties, generated from a typed TypeScript source (a format inspired by the [W3C DTCG](https://design-tokens.github.io/community-group/format/)):
|
|
71
|
-
|
|
72
|
-
- **Primitives**: OKLCH palettes (`--vectis-color-indigo-500`), spacing scales (`--vectis-space-4`), type, radii, shadows, durations/easings.
|
|
73
|
-
- **Semantics** — the only ones components consume: `--vectis-color-surface`, `--vectis-color-text-muted`, `--vectis-color-accent`, `--vectis-radius-interactive`, `--vectis-focus-ring-color`…
|
|
74
|
-
|
|
75
|
-
### Dark mode
|
|
76
|
-
|
|
77
|
-
```html
|
|
78
|
-
<html data-theme="dark"></html>
|
|
79
|
-
```
|
|
80
|
-
|
|
81
|
-
`data-theme` works on **any DOM subtree** (a dark panel inside a light page, or the reverse) and also drives `color-scheme` (scrollbars, native controls).
|
|
82
|
-
|
|
83
|
-
### Runtime overrides — no rebuild
|
|
84
|
-
|
|
85
|
-
Every customization is a redefinition of custom properties, in CSS:
|
|
86
|
-
|
|
87
|
-
```css
|
|
88
|
-
/* a "coral" theme: accent + pill radii */
|
|
89
|
-
:root {
|
|
90
|
-
--vectis-color-accent: oklch(58% 0.2 25);
|
|
91
|
-
--vectis-color-accent-hover: oklch(51% 0.19 25);
|
|
92
|
-
--vectis-radius-interactive: 9999px;
|
|
93
|
-
}
|
|
94
|
-
```
|
|
95
|
-
|
|
96
|
-
…or in JavaScript, on a subtree included:
|
|
97
|
-
|
|
98
|
-
```ts
|
|
99
|
-
panel.style.setProperty('--vectis-color-accent', 'oklch(58% 0.2 25)')
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
The design system's CSS lives in layers (`vectis.reset < vectis.tokens < vectis.components < vectis.utilities`): **any non-layered consumer style wins automatically** — overriding a component never calls for a specificity war. Every sheet the library emits re-declares that order, so it holds whichever one your bundler happens to place first.
|
|
103
|
-
|
|
104
|
-
### Programmatic access to the tokens
|
|
105
|
-
|
|
106
|
-
```ts
|
|
107
|
-
import { tokens, flattenTokens } from 'vectis-ui/tokens'
|
|
108
|
-
|
|
109
|
-
// [{ path: ['color', 'surface'], cssName: '--vectis-color-surface', token: {...} }, …]
|
|
110
|
-
const semanticColors = flattenTokens(tokens.semantic.color, ['color'])
|
|
111
|
-
```
|
|
112
|
-
|
|
113
|
-
`vectis-ui/tokens.json` exposes the same source as raw JSON (tooling, configuration export). It is the foundation of the theming app to come: modify the object, inject the variables, export the config.
|
|
114
|
-
|
|
115
|
-
## Icons
|
|
116
|
-
|
|
117
|
-
**No icon font is required.** The icons the library renders itself — `VDialog`'s cross, `VDatePicker`'s and `VMenu`'s chevrons, the toasts' tone icons, `VDataTable`'s sorting… — are **embedded SVGs**, exact replicas of Material Symbols Rounded (wght 400 · GRAD 0 · opsz 24, Apache-2.0 © Google). There are 34 of them and **each is a module of its own**, imported by the components that draw it: you pay for the icons your components actually render and for nothing else. A lone `VButton` ships none at all, which is most of why its JavaScript comes to 4.62 kB gzip with `VIcon`, `VSpinner` and the dictionary pulled in alongside it.
|
|
118
|
-
|
|
119
|
-
Reach for one directly through the `vectis-ui/icons` subpath, and pass it where a name would go:
|
|
120
|
-
|
|
121
|
-
```ts
|
|
122
|
-
import { close, search } from 'vectis-ui/icons'
|
|
123
|
-
```
|
|
124
|
-
|
|
125
|
-
The `VIcon` component resolves its source in this order: **an explicit `render` → `src` → `name` (the consumer resolver first, then the drawing the icon brought along, then the ligature) → the slot**.
|
|
126
|
-
|
|
127
|
-
```vue
|
|
128
|
-
<VIcon :name="close" />
|
|
129
|
-
<!-- one of the DS's own icons: SVG, no font needed -->
|
|
130
|
-
<VIcon name="favorite" />
|
|
131
|
-
<!-- a bare NAME: your resolver, then a ligature from YOUR icon font -->
|
|
132
|
-
<VIcon src="/logo.svg" label="Logo" />
|
|
133
|
-
<!-- an image -->
|
|
134
|
-
<VIcon><svg …/></VIcon>
|
|
135
|
-
<!-- an inline SVG (the slot) -->
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
A **bare string is always a NAME**, and it no longer reaches the library's own drawings: an icon is in your bundle because a module imported it, never because a string might one day ask for it.
|
|
139
|
-
|
|
140
|
-
- **Decorative by default** (`aria-hidden`); the `label` prop makes it informative (`role="img"` + `aria-label`).
|
|
141
|
-
- The **`data-icon`** attribute carries the requested name whatever the source — a stable hook for consumer CSS and for tests.
|
|
142
|
-
- Size: **1em by default** — the icon follows the surrounding text. Override freely in pixels through `:size="32"`. With no prop, any parent can drive the context by setting the **`--vectis-icon-size`** and **`--vectis-icon-opsz`** custom properties (which is what the shared `v-control` class does — VButton, VInput, VTextarea, VInputOTP, VChip… — according to the control's size); the numeric prop wins over the context. `VSpinner` follows the same principle (1em + `:size` in px), with no context API.
|
|
143
|
-
- **`--vectis-icon-opsz` only applies to the ligature**: it is a font variable axis, with no hold on a built-in SVG, an image or a third-party component. The size, by contrast, applies to every source.
|
|
144
|
-
|
|
145
|
-
### Every icon prop takes a name **or** an explicit rendering
|
|
146
|
-
|
|
147
|
-
```vue
|
|
148
|
-
<VButton icon-start="download">Export</VButton>
|
|
149
|
-
<VButton :icon-start="cloud_upload">Upload</VButton>
|
|
150
|
-
<VBreadcrumb :separator-icon="{ src: '/chevron.svg' }" :items="items" />
|
|
151
|
-
<VMenuItem label="Open" :icon-start="{ component: FolderIcon }" />
|
|
152
|
-
```
|
|
153
|
-
|
|
154
|
-
A string is **always** an icon name; one of the design system's own icons is imported from `vectis-ui/icons`; an image or a component is declared as an object (`{ src }`, `{ component }`, `{ path }`, `{ text }`, `{ class }`). That is what lets Iconify-style naming conventions (`mdi:close`, `fa6-solid:xmark`) work.
|
|
155
|
-
|
|
156
|
-
### Wiring your own icon library
|
|
157
|
-
|
|
158
|
-
`setIconResolver` is consulted **before** the icon's own drawing; returning `undefined` means "I do not know this name" and hands over to that drawing, then to the ligature. **Partial** mappings are therefore usable. The `IconName` type enumerates the names to cover.
|
|
159
|
-
|
|
160
|
-
An imported icon carries its **name** as well as its paths, which is what keeps a single `setIconResolver` call enough to move the design system's own internals onto your icon set — exactly as it was when those defaults were plain strings.
|
|
161
|
-
|
|
162
|
-
```ts
|
|
163
|
-
// main.ts / plugins/icons.ts — at MODULE level, never inside a setup()
|
|
164
|
-
import { setIconResolver, classIconResolver } from 'vectis-ui'
|
|
165
|
-
|
|
166
|
-
// Font Awesome, Phosphor, Bootstrap Icons… (class-based fonts + ::before)
|
|
167
|
-
// `fa-solid` unconditionally: the Free tier only draws a small fraction of the
|
|
168
|
-
// catalogue in Regular, so mapping `filled: false` onto it would render empty
|
|
169
|
-
// squares. FA's outline/filled pair requires the Pro tier.
|
|
170
|
-
setIconResolver(
|
|
171
|
-
classIconResolver({
|
|
172
|
-
aliases: { close: 'xmark', expand_more: 'angle-down', check_circle: 'circle-check' },
|
|
173
|
-
className: (name) => `fa-solid fa-${name}`,
|
|
174
|
-
}),
|
|
175
|
-
)
|
|
176
|
-
|
|
177
|
-
// Lucide, Untitled UI… (SVG sets as Vue components, a single <svg> root)
|
|
178
|
-
import { componentIconResolver } from 'vectis-ui'
|
|
179
|
-
import { X, Check, ChevronDown } from 'lucide-vue-next'
|
|
180
|
-
setIconResolver(
|
|
181
|
-
componentIconResolver({
|
|
182
|
-
components: { close: X, check: Check, expand_more: ChevronDown },
|
|
183
|
-
props: () => ({ strokeWidth: 1.75 }),
|
|
184
|
-
}),
|
|
185
|
-
)
|
|
186
|
-
|
|
187
|
-
// Material Symbols, ligature-based IcoMoon… — ALSO renders the design system's 20
|
|
188
|
-
// icons through the font, which restores the --vectis-icon-opsz optical axis
|
|
189
|
-
// (20 at xs/sm/md).
|
|
190
|
-
import { ligatureIconResolver } from 'vectis-ui'
|
|
191
|
-
setIconResolver(ligatureIconResolver())
|
|
192
|
-
```
|
|
85
|
+
The [installation guide](https://vectis-ui.com/docs/installation/) covers both setups in more detail.
|
|
193
86
|
|
|
194
|
-
|
|
87
|
+
## Documentation
|
|
195
88
|
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
> **SSR** — set the resolver at module level (a Nuxt plugin, `main.ts`), never inside a `setup()`: the state lives in the process, which is correct for configuration and wrong for per-request state. Above all, **do not install it client-only** (`plugins/*.client.ts`): the server would render the built-in SVG and the client your library — a hydration mismatch. Font Awesome in "SVG with JS" mode (which replaces elements in the DOM) is not supported: use its CSS mode.
|
|
199
|
-
|
|
200
|
-
**Loading an icon font stays useful** for your own names. An example with Material Symbols Rounded through Google Fonts:
|
|
201
|
-
|
|
202
|
-
```html
|
|
203
|
-
<link rel="preconnect" href="https://fonts.googleapis.com" />
|
|
204
|
-
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
|
|
205
|
-
<link
|
|
206
|
-
rel="stylesheet"
|
|
207
|
-
href="https://fonts.googleapis.com/css2?family=Material+Symbols+Rounded:opsz,wght,FILL,GRAD@20..48,100..700,0..1,-50..200&display=block"
|
|
208
|
-
/>
|
|
209
|
-
```
|
|
210
|
-
|
|
211
|
-
(or self-host the variable woff2, e.g. the `material-symbols` npm package). `display=block` avoids flashing the icon name in full. With no font loaded, the layout is preserved (the textual name stays inside the icon's box). Overriding the `--vectis-font-family-icon` token is enough to switch to another **ligature-based** font (Material Symbols Outlined/Sharp, an IcoMoon build) — with no resolver.
|
|
212
|
-
|
|
213
|
-
On `VButton`: the `icon-start` / `icon-end` props take an icon name or an explicit rendering (the `#start`/`#end` slots stay available for custom content and win over the props). `VButton` also accepts `href` (rendered as `<a>`; `disabled`/`loading` produce an inert link: `href` removed + `aria-disabled`) and `compact` (height reduced by 4px: 20/28/36/44/52px depending on the `xs`–`xl` size).
|
|
214
|
-
|
|
215
|
-
The `xs`–`xl` scale is not exposed by every component: those embedding a text input (`VInput`, `VTextarea`, `VInputOTP`, `VCombobox`, `VDateInput`, `VTimeInput`) restrict themselves to **`sm` / `md` / `lg`** (32/40/48px, default `md`), `compact` remaining available; `VChip` restricts itself to `xs`/`sm`.
|
|
216
|
-
|
|
217
|
-
## Internationalization
|
|
218
|
-
|
|
219
|
-
No user-facing text is hardcoded in the components: everything comes from a dictionary. The design system is **English by default** and ships French; any other language is added on the consumer side.
|
|
220
|
-
|
|
221
|
-
Two things are settled separately: the **words** come from the dictionary, the **formats** (month and day names, date field order, hour cycle, first day of the week) derive from `Intl` from the locale tag. Setting a locale with no matching dictionary therefore already gives correct dates, with labels left in English.
|
|
222
|
-
|
|
223
|
-
### Switching the design system to French
|
|
224
|
-
|
|
225
|
-
```ts
|
|
226
|
-
// main.ts
|
|
227
|
-
import { fr, registerMessages, setLocale } from 'vectis-ui'
|
|
228
|
-
|
|
229
|
-
registerMessages('fr', fr)
|
|
230
|
-
setLocale('fr-FR')
|
|
231
|
-
```
|
|
232
|
-
|
|
233
|
-
French is **opt-in**: it only enters your bundle if you import it.
|
|
234
|
-
|
|
235
|
-
Set a **complete** BCP 47 tag. `Intl` accepts `'en'`, but applies the language's default conventions to it — `'en'` means 12 h and a week starting on Sunday, which is not `'en-GB'`.
|
|
236
|
-
|
|
237
|
-
### Adjusting a few words
|
|
238
|
-
|
|
239
|
-
An override is **partial**: what you do not write stays unchanged, and successive calls on the same language accumulate.
|
|
240
|
-
|
|
241
|
-
```ts
|
|
242
|
-
import { registerMessages } from 'vectis-ui'
|
|
243
|
-
|
|
244
|
-
registerMessages('en', {
|
|
245
|
-
dataTable: { empty: 'Nothing to display' },
|
|
246
|
-
common: { close: 'Quit' },
|
|
247
|
-
})
|
|
248
|
-
```
|
|
249
|
-
|
|
250
|
-
### Adding a language the design system does not ship
|
|
251
|
-
|
|
252
|
-
The same gesture as enabling French — there are not two categories of dictionary. What you do not write falls back to English, never to an empty string: a partial dictionary is usable from its very first key.
|
|
253
|
-
|
|
254
|
-
```ts
|
|
255
|
-
import { registerMessages, setLocale, type MessagesInput } from 'vectis-ui'
|
|
256
|
-
|
|
257
|
-
const de: MessagesInput = {
|
|
258
|
-
common: { loading: 'Wird geladen…', close: 'Schließen' },
|
|
259
|
-
pagination: { previous: 'Vorherige Seite', next: 'Nächste Seite', page: (p) => `Seite ${p}` },
|
|
260
|
-
}
|
|
261
|
-
|
|
262
|
-
registerMessages('de', de)
|
|
263
|
-
setLocale('de-DE')
|
|
264
|
-
```
|
|
265
|
-
|
|
266
|
-
An entry depending on a value is a **TypeScript function**, not a placeholder string: no plural engine and no ICU syntax to learn. Type the constant as `MessagesInput` for key autocompletion, or as `Messages` to have the compiler require full coverage.
|
|
267
|
-
|
|
268
|
-
The key is the **language subtag** alone: `registerMessages('de', …)` covers `de-DE`, `de-AT` and `de-CH`.
|
|
269
|
-
|
|
270
|
-
### Precedence
|
|
271
|
-
|
|
272
|
-
A text prop set on a component stays **authoritative**: the global translation only changes the defaults. For containers' accessible names, the full chain is `aria-labelledby` › `aria-label` › the `label` prop › the dictionary › English.
|
|
273
|
-
|
|
274
|
-
`VDatePicker`, `VDateInput`, `VTimePicker` and `VTimeInput` keep their `locale` prop, which takes precedence; without it, they follow the global locale.
|
|
275
|
-
|
|
276
|
-
```vue
|
|
277
|
-
<VDateInput />
|
|
278
|
-
<!-- the global locale -->
|
|
279
|
-
<VDateInput locale="ja-JP" />
|
|
280
|
-
<!-- forced -->
|
|
281
|
-
```
|
|
282
|
-
|
|
283
|
-
### Limit: one locale per process
|
|
284
|
-
|
|
285
|
-
The configuration lives at module level, like the icons': **a single locale per process**. A server-rendered site serving `/fr` and `/en` from the same Node process cannot rely on it to vary the language per request — it must pass the text props explicitly.
|
|
286
|
-
|
|
287
|
-
## Components
|
|
288
|
-
|
|
289
|
-
| Area | Components |
|
|
290
|
-
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
291
|
-
| Actions | `VButton`, `VIconButton`, `VChip` (selectable, dismissible) |
|
|
292
|
-
| Forms | `VInput`, `VTextarea`, `VCheckbox`, `VRadio`, `VSwitch`, `VSlider` (single/range), `VInputOTP`, `VCombobox` (search, multi) |
|
|
293
|
-
| Overlays | `VTooltip`, `VMenu` + `VMenuItem`/`VMenuGroup`/`VMenuSeparator` (recursive submenus) |
|
|
294
|
-
| Structure | `VAccordion` + `VAccordionItem`, `VDataTable` (sorting, responsive), `VBreadcrumb` (data-driven, truncation) |
|
|
295
|
-
| Feedback | `VToaster` + `toast()` (notifications), `VBadge`, `VAvatar`, `VSpinner`, `VSkeletonLoader` (loading silhouettes), `VProgressLinear`, `VProgressCircular`, `VIcon` (built-in SVGs, a font, an image or an inline SVG) |
|
|
296
|
-
|
|
297
|
-
Implementation notes worth knowing:
|
|
298
|
-
|
|
299
|
-
- **VSlider range** superimposes two native `<input type="range">` (each thumb stays a real keyboard/ARIA slider); the JS only prevents them crossing.
|
|
300
|
-
- **VDataTable responsive**: the `stack` mode is pure CSS (container queries) — under a 640px container, rows become cards and the headers are re-injected through `::before + data-label`.
|
|
301
|
-
- **VCombobox** follows the ARIA combobox/listbox pattern (`aria-activedescendant`, focus stays in the input); the panel is aligned on the control through `anchor-size(width)`.
|
|
302
|
-
- **VToast**: mount `<VToaster />` once (at the app root), then call `toast({ message, tone, ... })` from anywhere — a component, a store, an API response (client only, never during SSR). Placements as Popover API stacks (the top layer), auto-dismiss (5 s by default, `duration: 0` = persistent, paused on hover), `dismissToast(id?)` to close programmatically.
|
|
303
|
-
|
|
304
|
-
Cross-cutting conventions:
|
|
305
|
-
|
|
306
|
-
- Prop-driven variants → `data-variant` / `data-tone` / `data-size` attributes (targetable in CSS).
|
|
307
|
-
- `v-model` wherever state exists (`v-model:open` for VMenu).
|
|
308
|
-
- Floating elements take their trigger from a scoped slot: `<template #trigger="{ triggerProps }"><VButton v-bind="triggerProps">…</VButton></template>` — `popovertarget` and the ARIA attributes are set for you.
|
|
309
|
-
- Forms: the visual error state comes from native `:user-invalid` (zero validation JS); the `invalid` prop forces the state for server-side validation.
|
|
310
|
-
|
|
311
|
-
The living documentation (stories, tokens page, theme switch): `pnpm storybook`.
|
|
89
|
+
Everything lives on **[vectis-ui.com](https://vectis-ui.com)**, a page per component with live examples and API tables, plus guides on [theming](https://vectis-ui.com/docs/theming/), [iconography](https://vectis-ui.com/docs/iconography/), [internationalization](https://vectis-ui.com/docs/i18n/) and [accessibility](https://vectis-ui.com/docs/accessibility/).
|
|
312
90
|
|
|
313
91
|
## Browser support
|
|
314
92
|
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
- Baseline, no compromise: the Popover API, `<dialog>`, `<details name>`, `:user-invalid`, `:has()`, `color-mix()`, `@layer`, custom properties.
|
|
318
|
-
- **CSS Anchor Positioning** (VTooltip, VMenu and its submenus, VCombobox): shipped with no JS fallback, a deliberate choice — every engine above the floor implements it, Firefox from 147.
|
|
319
|
-
- Pure progressive enhancement (clean degradation when unsupported): `@starting-style`/`allow-discrete` animations, `field-sizing: content` (VTextarea `auto-grow`), `::details-content` + `interpolate-size` (the VAccordion animation), and the scroll shadows of `VDialog` (`container-type: scroll-state`, Chrome/Edge 133+ — elsewhere the hairlines simply stay invisible).
|
|
93
|
+
Vectis UI targets recent browsers only:
|
|
320
94
|
|
|
321
|
-
|
|
95
|
+
| Chrome / Edge | Safari | Firefox |
|
|
96
|
+
| ------------- | ------ | ------- |
|
|
97
|
+
| 125+ | 26+ | 147+ |
|
|
322
98
|
|
|
323
|
-
|
|
324
|
-
aimed at older browsers **rewrites** part of what they contain. One of those rewrites is not a
|
|
325
|
-
fallback but a change of meaning: **Lightning CSS** — the default CSS minifier of **Vite 8**, and
|
|
326
|
-
Parcel's — replaces `:dir(rtl)` with an `:is(:lang(ae), :lang(ar), …, :lang(yi))` approximation as
|
|
327
|
-
soon as its targets predate Chrome 120. That list matches on the document's **language** where the
|
|
328
|
-
library flips on its **direction**, so on an `<html dir="rtl" lang="en">` page the rule never
|
|
329
|
-
applies at all.
|
|
99
|
+
CSS anchor positioning is used without a JavaScript fallback, which is what sets this floor. Some effects, like entry animations, are progressive enhancements and simply don't play on engines that lack them.
|
|
330
100
|
|
|
331
|
-
|
|
332
|
-
VPagination, VTabs, VBreadcrumb, VMenu, VCalendar, VDatePicker and VCarousel, VBadge's overlay
|
|
333
|
-
corner, VProgressCircular's direction of travel, VProgressLinear's clipped text copy and
|
|
334
|
-
VSkeletonLoader's wave. Nothing errors, and a dev server shows none of it: only a production build
|
|
335
|
-
minifies.
|
|
336
|
-
|
|
337
|
-
Vite derives `build.cssTarget` from `build.target`, whose `'modules'` default stands for Chrome 87.
|
|
338
|
-
Pin it to the floor above, and the modern CSS goes through untouched:
|
|
101
|
+
If your bundler targets older browsers, it may rewrite part of the library's CSS during minification. Set `build.cssTarget` to the versions above in your Vite (or Nuxt) config to keep it intact:
|
|
339
102
|
|
|
340
103
|
```ts
|
|
341
104
|
// vite.config.ts
|
|
342
105
|
export default defineConfig({
|
|
343
106
|
build: { cssTarget: ['chrome125', 'edge125', 'safari26', 'firefox147'] },
|
|
344
107
|
})
|
|
345
|
-
|
|
346
|
-
// nuxt.config.ts — the same value, one level down
|
|
347
|
-
export default defineNuxtConfig({
|
|
348
|
-
vite: { build: { cssTarget: ['chrome125', 'edge125', 'safari26', 'firefox147'] } },
|
|
349
|
-
})
|
|
350
108
|
```
|
|
351
109
|
|
|
352
|
-
|
|
353
|
-
once as an sRGB hex fallback and once as `lab()`.
|
|
110
|
+
## Versioning
|
|
354
111
|
|
|
355
|
-
|
|
112
|
+
Vectis UI follows [Semantic Versioning](https://semver.org/). While the version is still 0.x, a minor release can include breaking changes, so read the [changelog](https://github.com/Jypyx/vectis-ui/blob/main/CHANGELOG.md) before upgrading.
|
|
356
113
|
|
|
357
|
-
|
|
358
|
-
|
|
359
|
-
## Security model
|
|
360
|
-
|
|
361
|
-
The package has **no runtime dependency** beyond Vue, makes **no network request**, and reads no
|
|
362
|
-
storage. It renders no consumer string as HTML: there is no `v-html` anywhere in the library.
|
|
114
|
+
## Contributing
|
|
363
115
|
|
|
364
|
-
|
|
365
|
-
not filter URL schemes.** `href` (`VButton`, `VChip`, `VAvatar`, `VMenuItem`, `VSideNavigationItem`,
|
|
366
|
-
`VBreadcrumb`) and `src` (`VIcon`, `VAvatar`) are passed through untouched, so a `javascript:` URL
|
|
367
|
-
coming from your data runs on click. Validate it where the data enters your application — with
|
|
368
|
-
particular care for `VBreadcrumb`, whose `items[].href` is typically built from a CMS or an API
|
|
369
|
-
rather than written by hand.
|
|
116
|
+
Bug reports and feature requests are welcome in the [issue tracker](https://github.com/Jypyx/vectis-ui/issues). To work on the library itself, see the [repository](https://github.com/Jypyx/vectis-ui).
|
|
370
117
|
|
|
371
|
-
|
|
372
|
-
custom properties through `style.setProperty`, so they cannot escape the `style` attribute — but a
|
|
373
|
-
hostile value can still be a valid `url(…)`, i.e. a tracking beacon. Treat them as data to validate
|
|
374
|
-
if they come from outside your application.
|
|
118
|
+
## License
|
|
375
119
|
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
```bash
|
|
379
|
-
corepack enable pnpm
|
|
380
|
-
pnpm install
|
|
381
|
-
pnpm storybook # development
|
|
382
|
-
pnpm lint && pnpm format && pnpm typecheck && pnpm test && pnpm build && pnpm build-storybook
|
|
383
|
-
```
|
|
120
|
+
Vectis UI is released under the [MIT license](https://github.com/Jypyx/vectis-ui/blob/main/LICENSE).
|
|
384
121
|
|
|
385
|
-
-
|
|
386
|
-
- **A new component**: a `src/components/VX/` folder with `VX.vue` (non-scoped styles in `@layer vectis.components`, semantic tokens only, variants through `data-*`), `VX.stories.ts` (default, variants, states, edge cases, play functions), `VX.test.ts` (logic only — browser behaviour is tested in the play functions), and the named export in `src/index.ts`. The Storybook `title` and the `.mdx` heading are written **without the `V`** — the only exception to the prefix.
|
|
387
|
-
- **Its CSS ships as `dist/components/VX/VX.css`, imported by `VX.js`.** No rule may depend on where another component's sheet lands: a declaration that would collide with another component's at equal specificity is qualified (`[data-size]`, a compound class, a descendant) or routed through the custom property the target reads. `pnpm build` checks the mechanism.
|
|
388
|
-
- Any behavioural JS must be justified by a comment: "can modern HTML/CSS do it?" comes first.
|
|
122
|
+
The built-in icons are drawn from [Material Symbols](https://github.com/google/material-design-icons) by Google, used under the Apache License 2.0. See [NOTICE](https://github.com/Jypyx/vectis-ui/blob/main/NOTICE) for details.
|