vue-uno-style 0.1.0 → 0.2.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/README.md +454 -188
- package/dist/breakpoints.d.mts +0 -2
- package/dist/breakpoints.mjs +25 -0
- package/dist/devtools-client.d.mts +1 -0
- package/dist/devtools-client.mjs +553 -0
- package/dist/devtools.d.mts +110 -0
- package/dist/devtools.mjs +368 -0
- package/dist/directive.d.mts +50 -0
- package/dist/directive.mjs +147 -0
- package/dist/eslint.d.mts +5 -3
- package/dist/eslint.mjs +36 -14
- package/dist/getStyle.mjs +14 -57
- package/dist/index.d.mts +48 -33
- package/dist/index.mjs +7 -68
- package/dist/inspect.mjs +61 -0
- package/dist/nuxt.d.mts +12 -2
- package/dist/nuxt.mjs +472 -20
- package/dist/preset.d.mts +15 -5
- package/dist/preset.mjs +1 -58
- package/dist/preset2.mjs +81 -0
- package/dist/properties.d.mts +29 -0
- package/dist/properties.mjs +31 -0
- package/dist/varsClasses.mjs +2 -28
- package/dist/web-types.json +27 -0
- package/dist/webTypes.mjs +33 -0
- package/package.json +31 -26
package/README.md
CHANGED
|
@@ -1,29 +1,88 @@
|
|
|
1
1
|
# vue-uno-style
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Let data from your CMS or API style an element differently on phones, tablets
|
|
4
|
+
and desktops, with plain CSS that UnoCSS generates at build time.
|
|
4
5
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
the pieces together.
|
|
6
|
+
```vue
|
|
7
|
+
<h1 v-uno-style:c="{ sm: '#111827', md: '#4f46e5' }">Responsive heading</h1>
|
|
8
|
+
```
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
This heading is dark grey on phones and indigo from 768px up. The two colours
|
|
11
|
+
can come from anywhere: a CMS field, an API response, a user's settings.
|
|
11
12
|
|
|
12
|
-
|
|
13
|
-
any media query):
|
|
13
|
+
## Why this exists
|
|
14
14
|
|
|
15
|
-
|
|
16
|
-
-
|
|
17
|
-
|
|
15
|
+
Utility CSS such as UnoCSS works when you know the values while you write the
|
|
16
|
+
code. You write `md:c-indigo-600`, the build finds that class in your files, and
|
|
17
|
+
it generates the CSS for it.
|
|
18
18
|
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
zero-valued breakpoint. The package throws instead of guessing.
|
|
19
|
+
That stops working when a value only arrives once the page runs. Say a CMS
|
|
20
|
+
editor picks a heading colour per screen size:
|
|
22
21
|
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
22
|
+
- **A utility class for the value**, such as `md:c-[#4f46e5]`, appears nowhere
|
|
23
|
+
in your source, so the build never generated CSS for it.
|
|
24
|
+
- **An inline style** (`style="color: #4f46e5"`) works, but inline styles have no
|
|
25
|
+
media queries. You get one value for every screen.
|
|
26
|
+
- **Runtime CSS-in-JS** works, but ships a styling engine to the browser and
|
|
27
|
+
writes new CSS rules while the page runs.
|
|
28
|
+
|
|
29
|
+
## How it works
|
|
30
|
+
|
|
31
|
+
The value goes into a CSS variable. A small, fixed set of classes, generated at
|
|
32
|
+
build time, decides which variable applies at which screen width:
|
|
33
|
+
|
|
34
|
+
```html
|
|
35
|
+
<!-- what the directive renders -->
|
|
36
|
+
<h1 class="o:c-$c o:md:c-$c-md" style="--c: #111827; --c-md: #4f46e5">Responsive heading</h1>
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
```css
|
|
40
|
+
/* what the preset generated at build time */
|
|
41
|
+
.o\:c-\$c { color: var(--c); }
|
|
42
|
+
@media (min-width: 768px) {
|
|
43
|
+
.o\:md\:c-\$c-md { color: var(--c-md); }
|
|
44
|
+
}
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
The classes depend only on the properties and breakpoints you configure, never
|
|
48
|
+
on the values. Three properties and three breakpoints give nine classes, whatever
|
|
49
|
+
the CMS sends. When a value changes, only a CSS variable changes: nothing is
|
|
50
|
+
generated in the browser.
|
|
51
|
+
|
|
52
|
+
What that buys you:
|
|
53
|
+
|
|
54
|
+
- **Any value from data, per breakpoint.**
|
|
55
|
+
- **Static CSS.** There is no styling engine in the browser. The directive only
|
|
56
|
+
sets classes and CSS variables, and it works with server rendering.
|
|
57
|
+
- **Defaults stay in the template.** A value from data overrides the element's
|
|
58
|
+
own utility classes. When the data has no value, the template's class applies:
|
|
59
|
+
|
|
60
|
+
```vue
|
|
61
|
+
<h1 class="c-gray-900" v-uno-style:c="cms.headingColor">Responsive heading</h1>
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## When to use it
|
|
65
|
+
|
|
66
|
+
| Your values are | Use |
|
|
67
|
+
|-----------------|-----|
|
|
68
|
+
| known while you write the code | plain utility classes |
|
|
69
|
+
| from data, and the same on every screen | a plain `:style` binding |
|
|
70
|
+
| from data, and different per screen size | `vue-uno-style` |
|
|
71
|
+
|
|
72
|
+
## What's in the package
|
|
73
|
+
|
|
74
|
+
- **A Vue directive**, `v-uno-style`, that writes the classes and variables.
|
|
75
|
+
- **A UnoCSS preset** that generates their CSS at build time. You always need it:
|
|
76
|
+
see [Properties](#properties).
|
|
77
|
+
- **An ESLint rule** that catches a second directive on the same element and,
|
|
78
|
+
given your properties, a property you have not configured.
|
|
79
|
+
- **A Nuxt module** that wires them together.
|
|
80
|
+
|
|
81
|
+
Next on the [roadmap](https://github.com/AndrewBogdanovTSS/vue-uno-style/blob/main/ROADMAP.md):
|
|
82
|
+
`presetWind4`, values taken from your design system (`c: 'red-300'`), and a
|
|
83
|
+
Tailwind CSS 4 version.
|
|
84
|
+
|
|
85
|
+
See every behaviour live in the [playground](https://andrewbogdanovtss.github.io/vue-uno-style/).
|
|
27
86
|
|
|
28
87
|
## Install
|
|
29
88
|
|
|
@@ -32,234 +91,441 @@ npm install vue-uno-style unocss vue
|
|
|
32
91
|
```
|
|
33
92
|
|
|
34
93
|
Requires Node 24 or newer, Vue 3.4 or newer, and UnoCSS 66 or newer. The Nuxt
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
94
|
+
module also needs Nuxt 3.17 and `@unocss/nuxt` 66 or newer; the ESLint rule
|
|
95
|
+
needs ESLint 9 and `vue-eslint-parser`.
|
|
96
|
+
|
|
97
|
+
### Base presets
|
|
98
|
+
|
|
99
|
+
Any of the three UnoCSS presets with breakpoints works as the base:
|
|
100
|
+
|
|
101
|
+
| Preset | Breakpoints live in | Default `sm` | Rules you add |
|
|
102
|
+
|--------|---------------------|--------------|---------------|
|
|
103
|
+
| `presetMini` | `theme.breakpoints` | `640px` | `object`, `blur`, `columns`, `col-span`, if you use them |
|
|
104
|
+
| `presetWind3` | `theme.breakpoints` | `640px` | `col-span`, if you use it |
|
|
105
|
+
| `presetWind4` | `theme.breakpoint` | `40rem` | none |
|
|
106
|
+
|
|
107
|
+
The missing rules are listed under [Custom rules](#custom-rules). None of the
|
|
108
|
+
three defaults has a zero-valued `sm`, so each needs `baseBreakpoint: 'sm'` or
|
|
109
|
+
breakpoints of your own: see [Breakpoints](#breakpoints).
|
|
38
110
|
|
|
39
|
-
##
|
|
111
|
+
## Properties
|
|
40
112
|
|
|
41
|
-
The
|
|
42
|
-
`
|
|
113
|
+
The package predefines no properties: you list the ones your app uses.
|
|
114
|
+
`properties` is required, and the build fails without it.
|
|
43
115
|
|
|
44
116
|
```ts
|
|
45
|
-
//
|
|
46
|
-
export default
|
|
47
|
-
modules: ['@unocss/nuxt', 'vue-uno-style/nuxt'],
|
|
48
|
-
vUnoStyle: {
|
|
49
|
-
baseBreakpoint: 'sm',
|
|
50
|
-
},
|
|
51
|
-
})
|
|
117
|
+
// vue-uno-style.properties.js (plain JS, so eslint.config.js can import it too)
|
|
118
|
+
export default ['c', 'bg', 'p', 'gap', { name: 'bgi', format: 'url' }]
|
|
52
119
|
```
|
|
53
120
|
|
|
54
|
-
|
|
55
|
-
|
|
121
|
+
Each entry is a UnoCSS utility prefix whose rule accepts a `<prefix>-$<variable>`
|
|
122
|
+
value. `presetMini`, `presetWind3` and `presetWind4` already do for most
|
|
123
|
+
utilities (`c`, `bg`, `p`, `m`, `w`, `h`, `gap`, ...). For anything else, add the
|
|
124
|
+
rule yourself: see [Custom rules](#custom-rules).
|
|
125
|
+
|
|
126
|
+
`format: 'url'` wraps each value as `url(<value>)`, for properties fed plain
|
|
127
|
+
image URLs.
|
|
128
|
+
|
|
129
|
+
> [!IMPORTANT]
|
|
130
|
+
> The directive creates class names at runtime, so source scanning cannot find
|
|
131
|
+
> them. Always install `presetVUnoStyle()` as well: it safelists the classes for
|
|
132
|
+
> every configured property and adds the `o:` variant and override layer.
|
|
133
|
+
|
|
134
|
+
### Custom rules
|
|
135
|
+
|
|
136
|
+
A property needs a UnoCSS rule that turns `<prefix>-$<variable>` into CSS.
|
|
137
|
+
Without one, its classes get no CSS, and nothing reports it: neither UnoCSS nor
|
|
138
|
+
the preset warns. When you add a property, check its CSS once.
|
|
139
|
+
|
|
140
|
+
Every rule has the same shape. The preset's variants remove `o:` and the
|
|
141
|
+
breakpoint before the rule runs, so the rule only ever sees
|
|
142
|
+
`<prefix>-$<variable>`, and `name` is the variable without its `--`:
|
|
56
143
|
|
|
57
144
|
```ts
|
|
58
|
-
|
|
59
|
-
modules: ['@unocss/nuxt', 'vue-uno-style/nuxt'],
|
|
60
|
-
vUnoStyle: {
|
|
61
|
-
directiveName: 'style',
|
|
62
|
-
baseBreakpoint: 'sm',
|
|
63
|
-
},
|
|
64
|
-
})
|
|
145
|
+
[/^<prefix>-\$([\w-]+)$/, ([, name]) => ({ '<css-property>': `var(--${name})` })]
|
|
65
146
|
```
|
|
66
147
|
|
|
67
|
-
|
|
68
|
-
|
|
148
|
+
Match the variable name with `[\w-]+` rather than `.+`: UnoCSS scans every file, and
|
|
149
|
+
text such as `bgi-$*` would otherwise produce `var(--*)`, which fails CSS minification.
|
|
69
150
|
|
|
70
|
-
|
|
151
|
+
For a property fed plain image URLs, give its entry `format: 'url'`. The
|
|
152
|
+
directive then writes `url(<value>)` into the variable, so the rule stays a plain
|
|
153
|
+
`var()`:
|
|
71
154
|
|
|
72
|
-
|
|
155
|
+
```ts
|
|
156
|
+
// vue-uno-style.properties.js
|
|
157
|
+
export default [{ name: 'bgi', format: 'url' }]
|
|
158
|
+
```
|
|
73
159
|
|
|
74
160
|
```ts
|
|
75
|
-
//
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
161
|
+
// uno.config.ts
|
|
162
|
+
rules: [
|
|
163
|
+
[/^bgi-\$([\w-]+)$/, ([, name]) => ({ 'background-image': `var(--${name})` })]
|
|
164
|
+
]
|
|
165
|
+
```
|
|
79
166
|
|
|
80
|
-
|
|
167
|
+
#### Prefixes your preset lacks
|
|
81
168
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
169
|
+
`presetWind3` builds on `presetMini` and adds rules of its own; `presetWind4`
|
|
170
|
+
ships all four below. Among the common utilities, these prefixes need a rule
|
|
171
|
+
from you:
|
|
172
|
+
|
|
173
|
+
| Prefix | `presetMini` | `presetWind3` | `presetWind4` |
|
|
174
|
+
|--------|--------------|---------------|---------------|
|
|
175
|
+
| `object` | add the rule | built in | built in |
|
|
176
|
+
| `blur` | add the rule | built in | built in |
|
|
177
|
+
| `columns` | add the rule | built in | built in |
|
|
178
|
+
| `col-span` | add the rule | add the rule | built in |
|
|
85
179
|
|
|
86
|
-
|
|
180
|
+
```ts
|
|
181
|
+
// uno.config.ts - add only the rules your preset lacks
|
|
182
|
+
rules: [
|
|
183
|
+
[/^object-\$([\w-]+)$/, ([, name]) => ({ 'object-fit': `var(--${name})` })],
|
|
184
|
+
// The value can sit inside a CSS function...
|
|
185
|
+
[/^blur-\$([\w-]+)$/, ([, name]) => ({ filter: `blur(var(--${name}))` })],
|
|
186
|
+
[/^columns-\$([\w-]+)$/, ([, name]) => ({ columns: `var(--${name})` })],
|
|
187
|
+
// ...or appear more than once.
|
|
188
|
+
[/^col-span-\$([\w-]+)$/, ([, name]) => ({ 'grid-column': `span var(--${name}) / span var(--${name})` })]
|
|
189
|
+
]
|
|
87
190
|
```
|
|
88
191
|
|
|
89
|
-
|
|
90
|
-
|
|
192
|
+
> [!WARNING]
|
|
193
|
+
> A rule in your config replaces your preset's own rule for the same class, so
|
|
194
|
+
> add only the rules your preset lacks. Under `presetWind3`, for example, a custom
|
|
195
|
+
> `blur` rule sets `filter` on its own, which drops any other filter utility on
|
|
196
|
+
> the element.
|
|
91
197
|
|
|
92
|
-
|
|
198
|
+
## Breakpoints
|
|
93
199
|
|
|
94
|
-
|
|
95
|
-
<template>
|
|
96
|
-
<h1 v-uno-style:c="{ sm: '#111827', md: '#4f46e5' }">
|
|
97
|
-
Responsive heading
|
|
98
|
-
</h1>
|
|
99
|
-
</template>
|
|
100
|
-
```
|
|
200
|
+
One breakpoint is the unprefixed base, used before any media query:
|
|
101
201
|
|
|
102
|
-
|
|
202
|
+
- A breakpoint valued `0`, `"0"`, `"0px"`, or `""` is selected automatically.
|
|
203
|
+
- If none has a zero value, `baseBreakpoint` is required.
|
|
204
|
+
- An explicit `baseBreakpoint` always wins.
|
|
103
205
|
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
p: { sm: '1rem', md: '2rem' },
|
|
111
|
-
}"
|
|
112
|
-
>
|
|
113
|
-
Responsive card
|
|
114
|
-
</article>
|
|
115
|
-
</template>
|
|
116
|
-
```
|
|
206
|
+
The presets' own defaults start at `sm: 640px` (`presetMini`, `presetWind3`) or
|
|
207
|
+
`sm: 40rem` (`presetWind4`), so they need `baseBreakpoint: 'sm'` or a zero-valued
|
|
208
|
+
breakpoint. The package throws instead of guessing.
|
|
209
|
+
|
|
210
|
+
The package reads breakpoints where the base preset keeps them, the way
|
|
211
|
+
UnoCSS's own variants do:
|
|
117
212
|
|
|
118
|
-
|
|
119
|
-
|
|
213
|
+
- **The theme key** is `theme.breakpoint` under `presetWind4` and
|
|
214
|
+
`theme.breakpoints` under the others.
|
|
215
|
+
- **Your theme value replaces the preset's defaults.** It is not merged with
|
|
216
|
+
them: set `sm`, `md` and `lg`, and the defaults' `xl` and `2xl` are gone.
|
|
217
|
+
- **The `breakpoints` option replaces that theme key**, so the base preset's own
|
|
218
|
+
variants use the same values. Set breakpoints in one place. If your theme sets
|
|
219
|
+
them too, UnoCSS's variants follow the theme while the package follows the
|
|
220
|
+
option, and the two must not disagree.
|
|
221
|
+
- **Theme values must be strings** (`'0px'`, not `0`): UnoCSS's own variants fail
|
|
222
|
+
on numbers. The `breakpoints` option accepts numbers and converts them.
|
|
223
|
+
|
|
224
|
+
## Nuxt
|
|
225
|
+
|
|
226
|
+
```ts
|
|
227
|
+
// nuxt.config.ts
|
|
228
|
+
import properties from './vue-uno-style.properties.js'
|
|
120
229
|
|
|
121
|
-
|
|
230
|
+
export default defineNuxtConfig({
|
|
231
|
+
modules: ['@unocss/nuxt', 'vue-uno-style/nuxt'],
|
|
232
|
+
vUnoStyle: {
|
|
233
|
+
properties,
|
|
234
|
+
baseBreakpoint: 'sm',
|
|
235
|
+
// directiveName: 'style', // register as v-style instead of v-uno-style
|
|
236
|
+
}
|
|
237
|
+
})
|
|
238
|
+
```
|
|
122
239
|
|
|
123
|
-
The preset
|
|
240
|
+
The module adds the preset, reads breakpoints from the UnoCSS theme (or
|
|
241
|
+
`breakpoints`, when given) and registers the directive.
|
|
242
|
+
|
|
243
|
+
### Nuxt DevTools
|
|
244
|
+
|
|
245
|
+
During `nuxt dev`, the module adds a **vue-uno-style** tab to Nuxt DevTools:
|
|
246
|
+
|
|
247
|
+
- **Overview**: the resolved directive name, properties, formats and
|
|
248
|
+
breakpoints, and where the breakpoints and the preset came from: the option or
|
|
249
|
+
the theme key (`theme.breakpoint` or `theme.breakpoints`), and your other
|
|
250
|
+
UnoCSS presets.
|
|
251
|
+
- **Rule coverage.** It checks every safelisted class against your UnoCSS
|
|
252
|
+
config, flags a property with no matching rule and suggests the rule to add.
|
|
253
|
+
For a prefix from [Prefixes your preset lacks](#prefixes-your-preset-lacks),
|
|
254
|
+
that is the tested rule from the table. For any other prefix, it is the
|
|
255
|
+
general shape with the CSS property left for you to fill in.
|
|
256
|
+
- **Status.** It also shows the safelist size, the web-types status, and which
|
|
257
|
+
properties no page has used yet this session.
|
|
258
|
+
- **Elements**: every element on the current page that carries the directive.
|
|
259
|
+
For each one it shows the owning component, the value per breakpoint with the
|
|
260
|
+
active breakpoint marked, each binding's classes and variables, and what one
|
|
261
|
+
binding overrides in another. You also see the final `class` and `style` on
|
|
262
|
+
the element and how often it updated. Hover a row to outline the element on
|
|
263
|
+
the page. Turn on **Highlight active** to keep the selected element outlined
|
|
264
|
+
while you work in the tab; the outline follows the element as the page
|
|
265
|
+
scrolls.
|
|
266
|
+
- **Warnings**: values that give no CSS or the wrong CSS without an error. That
|
|
267
|
+
covers a property you did not configure, a breakpoint key that does not
|
|
268
|
+
exist, a numeric `0` (use `'0'`), and a value that is neither a string nor a
|
|
269
|
+
number. See [Warnings tab](#warnings-tab) for each kind and
|
|
270
|
+
[Values that produce no CSS](#values-that-produce-no-css) for what the
|
|
271
|
+
directive does with them.
|
|
272
|
+
- **Timeline**: the last 200 mounts, updates and unmounts, with the variables
|
|
273
|
+
each one changed and how long the directive took. The timing covers every
|
|
274
|
+
binding on the element and leaves out the tab's own bookkeeping. Browsers
|
|
275
|
+
round it to 0.1 ms, so most events read `< 0.1 ms`; 1 ms or more is marked.
|
|
276
|
+
- **REPL**: runs a value through the directive and your UnoCSS generator and
|
|
277
|
+
shows the classes, variables and CSS.
|
|
278
|
+
|
|
279
|
+
#### Warnings tab
|
|
280
|
+
|
|
281
|
+
The tab checks every binding when its element mounts and each time it updates.
|
|
282
|
+
It lists the warnings of the elements on the current page, one row per warning:
|
|
283
|
+
the element, the kind and a message. Click the element to open it in
|
|
284
|
+
**Elements**. The number of warnings shows next to the tab name.
|
|
285
|
+
|
|
286
|
+
| Kind | When | Example |
|
|
287
|
+
|------|------|---------|
|
|
288
|
+
| `unknown-property` | The property is not in `properties`. The preset does not safelist its classes. | `v-uno-style:mt="'1rem'"` |
|
|
289
|
+
| `unknown-breakpoint` | A key is not one of your breakpoints. The directive drops its value. | `{ sm: '1rem', tablet: '2rem' }` |
|
|
290
|
+
| `dropped-value` | A value is the number `0`. The directive skips it. | `{ sm: 0 }` |
|
|
291
|
+
| `invalid-value` | A value is neither a string nor a number, or the directive has no argument and the value is not an object. | `v-uno-style:c="true"`, `v-uno-style="'red'"` |
|
|
292
|
+
|
|
293
|
+
An empty value (`''`, `null` or `undefined`) gives no warning. It is the normal
|
|
294
|
+
way to leave a property or a breakpoint unset.
|
|
295
|
+
|
|
296
|
+
In development the directive is wrapped to report to the tab, on the client
|
|
297
|
+
only. Production builds and server rendering use the plain directive.
|
|
298
|
+
`devtools: false` leaves the tab out.
|
|
299
|
+
|
|
300
|
+
## Vue and UnoCSS without Nuxt
|
|
301
|
+
|
|
302
|
+
Give the preset and the directive the same properties and breakpoints:
|
|
124
303
|
|
|
125
304
|
```ts
|
|
126
305
|
// uno.config.ts
|
|
127
306
|
import { defineConfig, presetWind3 } from 'unocss'
|
|
128
307
|
import { presetVUnoStyle } from 'vue-uno-style/preset'
|
|
129
|
-
|
|
130
|
-
const breakpoints = { sm: 0, md: '768px', lg: '1024px' }
|
|
308
|
+
import properties from './vue-uno-style.properties.js'
|
|
131
309
|
|
|
132
310
|
export default defineConfig({
|
|
311
|
+
// The same with presetMini() or presetWind4(): the option writes the
|
|
312
|
+
// breakpoints into the theme key the base preset reads.
|
|
133
313
|
presets: [
|
|
134
314
|
presetWind3(),
|
|
135
|
-
presetVUnoStyle({ breakpoints })
|
|
136
|
-
]
|
|
137
|
-
theme: { breakpoints },
|
|
315
|
+
presetVUnoStyle({ properties, breakpoints: { sm: 0, md: '768px', lg: '1024px' } })
|
|
316
|
+
]
|
|
138
317
|
})
|
|
139
318
|
```
|
|
140
319
|
|
|
141
|
-
If the theme already contains the breakpoints, omit `breakpoints` from the
|
|
142
|
-
preset. For a stock non-zero theme, pass `baseBreakpoint`:
|
|
143
|
-
|
|
144
320
|
```ts
|
|
145
|
-
|
|
321
|
+
// main.ts
|
|
322
|
+
import { createVUnoStyle } from 'vue-uno-style'
|
|
323
|
+
import properties from './vue-uno-style.properties.js'
|
|
324
|
+
|
|
325
|
+
app.directive('uno-style', createVUnoStyle({
|
|
326
|
+
properties,
|
|
327
|
+
breakpoints: { sm: 0, md: '768px', lg: '1024px' }
|
|
328
|
+
}))
|
|
146
329
|
```
|
|
147
330
|
|
|
148
|
-
|
|
149
|
-
|
|
331
|
+
Passing `properties` to the directive applies their formats and warns in
|
|
332
|
+
development about a property the preset does not safelist.
|
|
150
333
|
|
|
151
|
-
##
|
|
334
|
+
## Usage
|
|
152
335
|
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
336
|
+
Use an argument for one property, or an object for several:
|
|
337
|
+
|
|
338
|
+
```vue
|
|
339
|
+
<template>
|
|
340
|
+
<article
|
|
341
|
+
v-uno-style="{
|
|
342
|
+
c: { sm: '#111827', md: '#ffffff' },
|
|
343
|
+
bg: { sm: '#ffffff', md: '#4f46e5' }
|
|
344
|
+
}"
|
|
345
|
+
>
|
|
346
|
+
<p v-uno-style:p="'1rem'">Body</p>
|
|
347
|
+
</article>
|
|
348
|
+
</template>
|
|
349
|
+
```
|
|
350
|
+
|
|
351
|
+
A scalar applies to the base breakpoint. Adjacent breakpoints with the same
|
|
352
|
+
value collapse into one class.
|
|
353
|
+
|
|
354
|
+
A single-root component may carry the directive on its root while its usage
|
|
355
|
+
site applies another. Both apply, and the usage site wins a shared property.
|
|
356
|
+
|
|
357
|
+
### Values that produce no CSS
|
|
358
|
+
|
|
359
|
+
The directive does not throw on a value it cannot use. What it does instead:
|
|
360
|
+
|
|
361
|
+
- **Empty values.** `''`, `null` and `undefined` write nothing. Use them to
|
|
362
|
+
leave a property or a breakpoint unset.
|
|
363
|
+
- **The number `0`.** It is skipped like an empty value, as a scalar or at a
|
|
364
|
+
breakpoint. Write `'0'`, which sets `--p: 0`.
|
|
365
|
+
- **A key that is not a breakpoint.** With `sm`, `md` and `lg`, the value for
|
|
366
|
+
`tablet` in `{ sm: '1rem', tablet: '2rem' }` is dropped. Only your
|
|
367
|
+
breakpoints are read.
|
|
368
|
+
- **A property outside `properties`.** The class and the variable are still
|
|
369
|
+
written (`o:mt-$mt`, `--mt`), but the preset does not safelist the class, so
|
|
370
|
+
it has no CSS. When the directive has `properties`, development builds log
|
|
371
|
+
`[vue-uno-style] Property "mt" is not configured, so its classes are not safelisted.`
|
|
372
|
+
- **A value that is neither a string nor a number.** It is written as text:
|
|
373
|
+
`true` sets `--c: true`, and an object sets `[object Object]`. The CSS gets a
|
|
374
|
+
value it cannot use.
|
|
375
|
+
- **No argument and a value that is not an object.** `v-uno-style="'red'"`
|
|
376
|
+
reads the string as an object of characters. It writes the classes
|
|
377
|
+
`o:0-$0 o:1-$1 o:2-$2` and the variables `--0: r`, `--1: e`, `--2: d`. With
|
|
378
|
+
`properties`, development builds also log the unconfigured-property warning
|
|
379
|
+
for `0`, `1` and `2`.
|
|
380
|
+
|
|
381
|
+
In `nuxt dev`, the [Warnings tab](#warnings-tab) of Nuxt DevTools lists each of
|
|
382
|
+
these except empty values, with the element they came from.
|
|
383
|
+
|
|
384
|
+
## ESLint
|
|
385
|
+
|
|
386
|
+
`vue-uno-style/no-multiple-v-style` reports more than one directive on a tag
|
|
387
|
+
and autofixes adjacent ones into the object form. Given `properties`, it also
|
|
388
|
+
reports arguments outside them.
|
|
157
389
|
|
|
158
390
|
```js
|
|
159
391
|
// eslint.config.js
|
|
160
392
|
import vUnoStyle from 'vue-uno-style/eslint'
|
|
161
393
|
import vueParser from 'vue-eslint-parser'
|
|
394
|
+
import properties from './vue-uno-style.properties.js'
|
|
162
395
|
|
|
163
396
|
export default [
|
|
164
397
|
...vUnoStyle.configs.recommended,
|
|
165
398
|
{
|
|
166
399
|
files: ['**/*.vue'],
|
|
167
400
|
languageOptions: { parser: vueParser },
|
|
168
|
-
|
|
401
|
+
rules: {
|
|
402
|
+
'vue-uno-style/no-multiple-v-style': ['error', { properties }]
|
|
403
|
+
}
|
|
404
|
+
}
|
|
169
405
|
]
|
|
170
406
|
```
|
|
171
407
|
|
|
172
|
-
|
|
173
|
-
|
|
408
|
+
Pass `directiveName` as well when the directive is registered under another
|
|
409
|
+
name.
|
|
174
410
|
|
|
175
|
-
|
|
176
|
-
export default [{
|
|
177
|
-
files: ['**/*.vue'],
|
|
178
|
-
languageOptions: { parser: vueParser },
|
|
179
|
-
plugins: { 'vue-uno-style': vUnoStyle },
|
|
180
|
-
rules: {
|
|
181
|
-
'vue-uno-style/no-multiple-v-style': ['error', { directiveName: 'style' }],
|
|
182
|
-
},
|
|
183
|
-
}]
|
|
184
|
-
```
|
|
411
|
+
## WebStorm completion
|
|
185
412
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
| Property | CSS intent |
|
|
192
|
-
| --- | --- |
|
|
193
|
-
| `aspect-ratio` | Aspect ratio |
|
|
194
|
-
| `b` | Border colour |
|
|
195
|
-
| `bg` | Background colour |
|
|
196
|
-
| `bgi` | Background image; values are wrapped in `url(...)` |
|
|
197
|
-
| `bgv` | Raw `background` value, including gradients |
|
|
198
|
-
| `c` | Text colour |
|
|
199
|
-
| `display` | Display mode |
|
|
200
|
-
| `gap` | Grid or flex gap |
|
|
201
|
-
| `gap-x` | Column gap |
|
|
202
|
-
| `gap-y` | Row gap |
|
|
203
|
-
| `grid-area` | Grid area |
|
|
204
|
-
| `grid-col` | Grid column |
|
|
205
|
-
| `cols` | Grid template columns |
|
|
206
|
-
| `grid-row` | Grid row |
|
|
207
|
-
| `rows` | Grid template rows |
|
|
208
|
-
| `h` | Height |
|
|
209
|
-
| `inset` | Inset offsets |
|
|
210
|
-
| `lh` | Line height |
|
|
211
|
-
| `max-h` | Maximum height |
|
|
212
|
-
| `max-w` | Maximum width |
|
|
213
|
-
| `min-h` | Minimum height |
|
|
214
|
-
| `min-w` | Minimum width |
|
|
215
|
-
| `m` | Margin |
|
|
216
|
-
| `mb` | Bottom margin |
|
|
217
|
-
| `mt` | Top margin |
|
|
218
|
-
| `ml` | Left margin |
|
|
219
|
-
| `mr` | Right margin |
|
|
220
|
-
| `mx` | Horizontal margins |
|
|
221
|
-
| `my` | Vertical margins |
|
|
222
|
-
| `object-position` | Replaced-element object position |
|
|
223
|
-
| `p` | Padding |
|
|
224
|
-
| `pb` | Bottom padding |
|
|
225
|
-
| `pr` | Right padding |
|
|
226
|
-
| `pt` | Top padding |
|
|
227
|
-
| `px` | Horizontal padding |
|
|
228
|
-
| `py` | Vertical padding |
|
|
229
|
-
| `row-start` | Grid row start |
|
|
230
|
-
| `text-size` | Font size |
|
|
231
|
-
| `top` | Top offset |
|
|
232
|
-
| `w` | Width |
|
|
233
|
-
|
|
234
|
-
Adjacent breakpoints with the same value are collapsed. Missing breakpoint
|
|
235
|
-
values are omitted. A property not listed above is reported by the ESLint rule
|
|
236
|
-
and warned about by development builds of the runtime.
|
|
237
|
-
|
|
238
|
-
## Direct API
|
|
239
|
-
|
|
240
|
-
The root entry also exports the pure helpers and their types:
|
|
413
|
+
The package ships a [web-types](https://github.com/JetBrains/web-types) file,
|
|
414
|
+
so WebStorm completes `v-uno-style`. The Nuxt module rewrites it inside the
|
|
415
|
+
installed package with your `directiveName` and `properties`, so completion
|
|
416
|
+
offers exactly your properties. Nothing is written to your project.
|
|
241
417
|
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
resolveBreakpoints,
|
|
248
|
-
styleProps,
|
|
249
|
-
} from 'vue-uno-style'
|
|
250
|
-
```
|
|
418
|
+
The file is replaced rather than edited, so pnpm's shared store stays intact.
|
|
419
|
+
A read-only or missing `node_modules` (Yarn PnP) only logs a warning. Two apps
|
|
420
|
+
sharing one installed copy overwrite each other's file. `webTypes: false`
|
|
421
|
+
turns the rewrite off; `createWebTypes()` builds the file for setups without
|
|
422
|
+
Nuxt.
|
|
251
423
|
|
|
252
|
-
##
|
|
424
|
+
## Options
|
|
253
425
|
|
|
254
|
-
|
|
255
|
-
|
|
426
|
+
Every option each entry accepts. The Nuxt module passes `properties`,
|
|
427
|
+
`breakpoints` and `baseBreakpoint` on to the preset and the directive, so a
|
|
428
|
+
Nuxt app sets them once.
|
|
256
429
|
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
430
|
+
### Property entries
|
|
431
|
+
|
|
432
|
+
Each item in `properties` is a string or an object. `'c'` is the same as
|
|
433
|
+
`{ name: 'c' }`.
|
|
434
|
+
|
|
435
|
+
| Field | Type | Default | Description |
|
|
436
|
+
|-------|------|---------|-------------|
|
|
437
|
+
| `name` | `string` | required | UnoCSS utility prefix: a letter, then letters, digits or dashes. Each name may appear once. |
|
|
438
|
+
| `format` | `'url'` | none | `url` writes each value as `url(<value>)`. No other format exists. |
|
|
439
|
+
|
|
440
|
+
A missing or empty list, an invalid name, a repeated name or an unknown format
|
|
441
|
+
throws.
|
|
442
|
+
|
|
443
|
+
### Breakpoint values
|
|
444
|
+
|
|
445
|
+
`breakpoints` maps names to minimum widths, smallest first, for example
|
|
446
|
+
`{ sm: 0, md: '768px', lg: '1024px' }`. A number means pixels. A string is used
|
|
447
|
+
as written, so `'48rem'` works. Collapsing of repeated values follows this
|
|
448
|
+
order.
|
|
449
|
+
|
|
450
|
+
### Nuxt module
|
|
451
|
+
|
|
452
|
+
Set under `vUnoStyle` in `nuxt.config.ts`. The module needs `@unocss/nuxt`
|
|
453
|
+
registered, and fails the build without it.
|
|
454
|
+
|
|
455
|
+
| Option | Type | Default | Description |
|
|
456
|
+
|--------|------|---------|-------------|
|
|
457
|
+
| `properties` | `PropertyConfig[]` | required | The properties the directive may set. See [Property entries](#property-entries). |
|
|
458
|
+
| `breakpoints` | `Record<string, number \| string>` | the UnoCSS theme's | Breakpoints for the preset and the directive. They replace the theme's breakpoints, so the base preset's own variants use them too. |
|
|
459
|
+
| `baseBreakpoint` | `string` | the zero-valued breakpoint | The unprefixed breakpoint. See [Breakpoints](#breakpoints). |
|
|
460
|
+
| `directiveName` | `string` | `'uno-style'` | Registration name without `v-`. `'style'` registers `v-style`. |
|
|
461
|
+
| `webTypes` | `boolean` | `true` | Rewrites the installed package's `web-types.json` with `directiveName` and `properties`. `false` keeps the shipped file. |
|
|
462
|
+
| `devtools` | `boolean` | `true` | Adds the [Nuxt DevTools](#nuxt-devtools) tab during `nuxt dev`. It has no effect in production or when Nuxt DevTools is off. |
|
|
463
|
+
|
|
464
|
+
Without `breakpoints`, the module reads `theme.breakpoints` (`theme.breakpoint`
|
|
465
|
+
under `presetWind4`) from the same UnoCSS config that `@unocss/nuxt` loads: `uno.config.*`, the file named in
|
|
466
|
+
`unocss.configFile`, and the inline `unocss` options.
|
|
467
|
+
|
|
468
|
+
### UnoCSS preset
|
|
469
|
+
|
|
470
|
+
`presetVUnoStyle(options)` from `vue-uno-style/preset`.
|
|
471
|
+
|
|
472
|
+
| Option | Type | Default | Description |
|
|
473
|
+
|--------|------|---------|-------------|
|
|
474
|
+
| `properties` | `PropertyConfig[]` | required | Safelists every class the directive can write for these properties. |
|
|
475
|
+
| `breakpoints` | `Record<string, number \| string>` | `theme.breakpoints`, or `theme.breakpoint` under `presetWind4` | Breakpoints for the media queries and the safelist. They replace that theme key, so the base preset's own variants use them too. |
|
|
476
|
+
| `baseBreakpoint` | `string` | the zero-valued breakpoint | The unprefixed breakpoint. |
|
|
477
|
+
|
|
478
|
+
The preset throws when it finds neither `breakpoints` nor breakpoints in the theme.
|
|
479
|
+
|
|
480
|
+
### Directive
|
|
481
|
+
|
|
482
|
+
`createVUnoStyle(options)` from `vue-uno-style`. Give it the same values as the
|
|
483
|
+
preset.
|
|
484
|
+
|
|
485
|
+
| Option | Type | Default | Description |
|
|
486
|
+
|--------|------|---------|-------------|
|
|
487
|
+
| `breakpoints` | `Record<string, number \| string>` | required | Only the names, their order and the base are used; widths live in the CSS. |
|
|
488
|
+
| `baseBreakpoint` | `string` | the zero-valued breakpoint | The unprefixed breakpoint. |
|
|
489
|
+
| `properties` | `PropertyConfig[]` | none | Applies value formats. In development, warns about a property that is not listed. |
|
|
490
|
+
|
|
491
|
+
`vUnoStyle` is `createVUnoStyle({ breakpoints: { sm: 0, md: 768, lg: 1024 } })`,
|
|
492
|
+
with no properties, so it applies no formats.
|
|
493
|
+
|
|
494
|
+
### ESLint rule
|
|
495
|
+
|
|
496
|
+
Options for `vue-uno-style/no-multiple-v-style`.
|
|
497
|
+
|
|
498
|
+
| Option | Type | Default | Description |
|
|
499
|
+
|--------|------|---------|-------------|
|
|
500
|
+
| `directiveName` | `string` | `'uno-style'` | Directive name without `v-`. |
|
|
501
|
+
| `properties` | `PropertyConfig[]` | none | Reports a static argument (`v-uno-style:x`) that is not listed. Object keys and dynamic arguments are not checked. |
|
|
502
|
+
|
|
503
|
+
`configs.recommended` turns the rule on as `error` for `**/*.vue`, without
|
|
504
|
+
options and without a parser. The autofix is skipped when another attribute
|
|
505
|
+
sits between the directives.
|
|
506
|
+
|
|
507
|
+
### Web-types
|
|
508
|
+
|
|
509
|
+
`createWebTypes(options)` from `vue-uno-style`. `serializeWebTypes()` turns the
|
|
510
|
+
result into the file's text.
|
|
511
|
+
|
|
512
|
+
| Option | Type | Default | Description |
|
|
513
|
+
|--------|------|---------|-------------|
|
|
514
|
+
| `directiveName` | `string` | required | Directive name without `v-`. |
|
|
515
|
+
| `version` | `string` | required | Version recorded in the file. WebStorm uses it to tell revisions apart. |
|
|
516
|
+
| `properties` | `PropertyConfig[]` | none | Arguments offered for completion. Without them, any argument is accepted. |
|
|
517
|
+
|
|
518
|
+
## API
|
|
519
|
+
|
|
520
|
+
The root entry exports the directive and the pure helpers behind it:
|
|
521
|
+
`createVUnoStyle`, `vUnoStyle`, `getStyle`, `getStyleProps`,
|
|
522
|
+
`getVarsClasses`, `formatValue`, `resolveBreakpoints`, `resolveProperties`,
|
|
523
|
+
`createWebTypes`, `serializeWebTypes`, `getDirectiveContext` and their types.
|
|
524
|
+
|
|
525
|
+
`vue-uno-style/devtools` exports what the DevTools tab runs on:
|
|
526
|
+
`createDevtoolsRegistry`, which records every element the directive writes,
|
|
527
|
+
and `inspectValue`, which lists what in a value the directive ignores. The Nuxt
|
|
528
|
+
module wires both for you.
|
|
263
529
|
|
|
264
530
|
## Development
|
|
265
531
|
|
|
@@ -271,13 +537,13 @@ pnpm test:unit
|
|
|
271
537
|
pnpm build
|
|
272
538
|
pnpm smoke
|
|
273
539
|
pnpm check:docs
|
|
540
|
+
pnpm playground:install && pnpm playground:verify
|
|
274
541
|
```
|
|
275
542
|
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
|
|
280
|
-
CI so npm can attach provenance.
|
|
543
|
+
`playground/` is a Nuxt app using every entry, including custom `bgi` and `bgv`
|
|
544
|
+
properties, and is deployed to GitHub Pages from `main`. `pnpm release` bumps, tags and pushes; the tag starts the release
|
|
545
|
+
workflow, which publishes through npm trusted publishing (OIDC, no token) with
|
|
546
|
+
provenance.
|
|
281
547
|
|
|
282
548
|
## Licence
|
|
283
549
|
|