vue-uno-style 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +549 -2
- package/dist/breakpoints.d.mts +16 -0
- 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 +23 -0
- package/dist/eslint.mjs +126 -0
- package/dist/getStyle.mjs +52 -0
- package/dist/index.d.mts +62 -0
- package/dist/index.mjs +7 -0
- package/dist/inspect.mjs +61 -0
- package/dist/nuxt.d.mts +22 -0
- package/dist/nuxt.mjs +542 -0
- package/dist/preset.d.mts +23 -0
- package/dist/preset.mjs +1 -0
- package/dist/preset2.mjs +81 -0
- package/dist/properties.d.mts +29 -0
- package/dist/properties.mjs +31 -0
- package/dist/varsClasses.mjs +10 -0
- package/dist/web-types.json +27 -0
- package/dist/webTypes.mjs +33 -0
- package/package.json +130 -4
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Andrii Bohdanov
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,550 @@
|
|
|
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.
|
|
5
|
+
|
|
6
|
+
```vue
|
|
7
|
+
<h1 v-uno-style:c="{ sm: '#111827', md: '#4f46e5' }">Responsive heading</h1>
|
|
8
|
+
```
|
|
9
|
+
|
|
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.
|
|
12
|
+
|
|
13
|
+
## Why this exists
|
|
14
|
+
|
|
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
|
+
|
|
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:
|
|
21
|
+
|
|
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/).
|
|
86
|
+
|
|
87
|
+
## Install
|
|
88
|
+
|
|
89
|
+
```bash
|
|
90
|
+
npm install vue-uno-style unocss vue
|
|
91
|
+
```
|
|
92
|
+
|
|
93
|
+
Requires Node 24 or newer, Vue 3.4 or newer, and UnoCSS 66 or newer. The Nuxt
|
|
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).
|
|
110
|
+
|
|
111
|
+
## Properties
|
|
112
|
+
|
|
113
|
+
The package predefines no properties: you list the ones your app uses.
|
|
114
|
+
`properties` is required, and the build fails without it.
|
|
115
|
+
|
|
116
|
+
```ts
|
|
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' }]
|
|
119
|
+
```
|
|
120
|
+
|
|
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 `--`:
|
|
143
|
+
|
|
144
|
+
```ts
|
|
145
|
+
[/^<prefix>-\$([\w-]+)$/, ([, name]) => ({ '<css-property>': `var(--${name})` })]
|
|
146
|
+
```
|
|
147
|
+
|
|
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.
|
|
150
|
+
|
|
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()`:
|
|
154
|
+
|
|
155
|
+
```ts
|
|
156
|
+
// vue-uno-style.properties.js
|
|
157
|
+
export default [{ name: 'bgi', format: 'url' }]
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
```ts
|
|
161
|
+
// uno.config.ts
|
|
162
|
+
rules: [
|
|
163
|
+
[/^bgi-\$([\w-]+)$/, ([, name]) => ({ 'background-image': `var(--${name})` })]
|
|
164
|
+
]
|
|
165
|
+
```
|
|
166
|
+
|
|
167
|
+
#### Prefixes your preset lacks
|
|
168
|
+
|
|
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 |
|
|
179
|
+
|
|
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
|
+
]
|
|
190
|
+
```
|
|
191
|
+
|
|
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.
|
|
197
|
+
|
|
198
|
+
## Breakpoints
|
|
199
|
+
|
|
200
|
+
One breakpoint is the unprefixed base, used before any media query:
|
|
201
|
+
|
|
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.
|
|
205
|
+
|
|
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:
|
|
212
|
+
|
|
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'
|
|
229
|
+
|
|
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
|
+
```
|
|
239
|
+
|
|
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:
|
|
303
|
+
|
|
304
|
+
```ts
|
|
305
|
+
// uno.config.ts
|
|
306
|
+
import { defineConfig, presetWind3 } from 'unocss'
|
|
307
|
+
import { presetVUnoStyle } from 'vue-uno-style/preset'
|
|
308
|
+
import properties from './vue-uno-style.properties.js'
|
|
309
|
+
|
|
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.
|
|
313
|
+
presets: [
|
|
314
|
+
presetWind3(),
|
|
315
|
+
presetVUnoStyle({ properties, breakpoints: { sm: 0, md: '768px', lg: '1024px' } })
|
|
316
|
+
]
|
|
317
|
+
})
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
```ts
|
|
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
|
+
}))
|
|
329
|
+
```
|
|
330
|
+
|
|
331
|
+
Passing `properties` to the directive applies their formats and warns in
|
|
332
|
+
development about a property the preset does not safelist.
|
|
333
|
+
|
|
334
|
+
## Usage
|
|
335
|
+
|
|
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.
|
|
389
|
+
|
|
390
|
+
```js
|
|
391
|
+
// eslint.config.js
|
|
392
|
+
import vUnoStyle from 'vue-uno-style/eslint'
|
|
393
|
+
import vueParser from 'vue-eslint-parser'
|
|
394
|
+
import properties from './vue-uno-style.properties.js'
|
|
395
|
+
|
|
396
|
+
export default [
|
|
397
|
+
...vUnoStyle.configs.recommended,
|
|
398
|
+
{
|
|
399
|
+
files: ['**/*.vue'],
|
|
400
|
+
languageOptions: { parser: vueParser },
|
|
401
|
+
rules: {
|
|
402
|
+
'vue-uno-style/no-multiple-v-style': ['error', { properties }]
|
|
403
|
+
}
|
|
404
|
+
}
|
|
405
|
+
]
|
|
406
|
+
```
|
|
407
|
+
|
|
408
|
+
Pass `directiveName` as well when the directive is registered under another
|
|
409
|
+
name.
|
|
410
|
+
|
|
411
|
+
## WebStorm completion
|
|
412
|
+
|
|
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.
|
|
417
|
+
|
|
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.
|
|
423
|
+
|
|
424
|
+
## Options
|
|
425
|
+
|
|
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.
|
|
429
|
+
|
|
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.
|
|
529
|
+
|
|
530
|
+
## Development
|
|
531
|
+
|
|
532
|
+
```bash
|
|
533
|
+
pnpm install
|
|
534
|
+
pnpm lint
|
|
535
|
+
pnpm typecheck
|
|
536
|
+
pnpm test:unit
|
|
537
|
+
pnpm build
|
|
538
|
+
pnpm smoke
|
|
539
|
+
pnpm check:docs
|
|
540
|
+
pnpm playground:install && pnpm playground:verify
|
|
541
|
+
```
|
|
542
|
+
|
|
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.
|
|
547
|
+
|
|
548
|
+
## Licence
|
|
549
|
+
|
|
550
|
+
MIT
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
type BreakpointValue = number | string;
|
|
2
|
+
type BreakpointConfig = Readonly<Record<string, BreakpointValue>>;
|
|
3
|
+
interface ResolveBreakpointsOptions {
|
|
4
|
+
breakpoints: BreakpointConfig;
|
|
5
|
+
baseBreakpoint?: string;
|
|
6
|
+
}
|
|
7
|
+
interface ResolvedBreakpoints {
|
|
8
|
+
base: string;
|
|
9
|
+
prefixed: string[];
|
|
10
|
+
}
|
|
11
|
+
/**
|
|
12
|
+
* Resolves the unprefixed base breakpoint and the ordered prefixed breakpoints.
|
|
13
|
+
* An explicit base wins; otherwise a zero-valued breakpoint is required.
|
|
14
|
+
*/
|
|
15
|
+
declare const resolveBreakpoints: ({ breakpoints, baseBreakpoint }: ResolveBreakpointsOptions) => ResolvedBreakpoints;
|
|
16
|
+
export { resolveBreakpoints as a, ResolvedBreakpoints as i, BreakpointValue as n, ResolveBreakpointsOptions as r, BreakpointConfig as t };
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
// src/core/breakpoints.ts
|
|
2
|
+
const isBaseValue = (value) => {
|
|
3
|
+
if (value === 0) return true;
|
|
4
|
+
if (typeof value !== "string") return false;
|
|
5
|
+
return [
|
|
6
|
+
"",
|
|
7
|
+
"0",
|
|
8
|
+
"0px"
|
|
9
|
+
].includes(value.trim().toLowerCase());
|
|
10
|
+
};
|
|
11
|
+
/**
|
|
12
|
+
* Resolves the unprefixed base breakpoint and the ordered prefixed breakpoints.
|
|
13
|
+
* An explicit base wins; otherwise a zero-valued breakpoint is required.
|
|
14
|
+
*/
|
|
15
|
+
const resolveBreakpoints = ({ breakpoints, baseBreakpoint }) => {
|
|
16
|
+
const names = Object.keys(breakpoints);
|
|
17
|
+
if (baseBreakpoint && !names.includes(baseBreakpoint)) throw new Error(`[vue-uno-style] Base breakpoint "${baseBreakpoint}" does not exist in the configured breakpoints.`);
|
|
18
|
+
const base = baseBreakpoint ?? names.find((name) => isBaseValue(breakpoints[name]));
|
|
19
|
+
if (!base) throw new Error("[vue-uno-style] Unable to resolve a base breakpoint. Set baseBreakpoint or configure a breakpoint with the value 0, \"0\", \"0px\", or an empty string.");
|
|
20
|
+
return {
|
|
21
|
+
base,
|
|
22
|
+
prefixed: names.filter((name) => name !== base)
|
|
23
|
+
};
|
|
24
|
+
};
|
|
25
|
+
export { resolveBreakpoints as t };
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {}
|