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 CHANGED
@@ -1,29 +1,88 @@
1
1
  # vue-uno-style
2
2
 
3
- Responsive runtime styles for Vue, backed by UnoCSS custom properties.
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
- `vue-uno-style` turns API- or CMS-provided responsive values into CSS variables and
6
- UnoCSS classes. The package includes the Vue directive, the UnoCSS preset that
7
- makes its generated classes work, an ESLint rule, and a Nuxt module that wires
8
- the pieces together.
6
+ ```vue
7
+ <h1 v-uno-style:c="{ sm: '#111827', md: '#4f46e5' }">Responsive heading</h1>
8
+ ```
9
9
 
10
- ## Breakpoints: choose the base explicitly
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
- The directive needs one breakpoint to mean “unprefixed” (the value used before
13
- any media query):
13
+ ## Why this exists
14
14
 
15
- - A breakpoint valued `0`, `"0"`, `"0px"`, or `""` is selected automatically.
16
- - If none has a zero value, `baseBreakpoint` is required.
17
- - An explicit `baseBreakpoint` always wins.
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
- This matters with the stock UnoCSS theme, where `sm` is `640px`, not a base
20
- breakpoint. In that case configure `baseBreakpoint: 'sm'` deliberately, or add a
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
- > [!IMPORTANT]
24
- > The directive creates class names at runtime, so source scanning cannot find
25
- > them. Always install `presetVUnoStyle()` as well. It supplies the safelist,
26
- > `o:` variant, variable rules, and override layer used by the directive.
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
- integration additionally requires Nuxt 3.17 or newer and `@unocss/nuxt` 66 or
36
- newer. The ESLint integration requires ESLint 9 or newer and
37
- `vue-eslint-parser`.
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
- ## Nuxt module
111
+ ## Properties
40
112
 
41
- The Nuxt module is the shortest setup. Register UnoCSS first, then
42
- `vue-uno-style/nuxt`:
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
- // nuxt.config.ts
46
- export default defineNuxtConfig({
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
- The module reads the resolved UnoCSS theme, adds the preset, and registers the
55
- directive as `v-uno-style`. To keep an existing `v-style` API:
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
- export default defineNuxtConfig({
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
- The same options can provide `breakpoints` directly when they should not come
68
- from the UnoCSS theme.
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
- ## Vue directive
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
- For plain Vue, create the directive with the same breakpoints used by UnoCSS:
155
+ ```ts
156
+ // vue-uno-style.properties.js
157
+ export default [{ name: 'bgi', format: 'url' }]
158
+ ```
73
159
 
74
160
  ```ts
75
- // main.ts
76
- import { createApp } from 'vue'
77
- import { createVUnoStyle } from 'vue-uno-style'
78
- import App from './App.vue'
161
+ // uno.config.ts
162
+ rules: [
163
+ [/^bgi-\$([\w-]+)$/, ([, name]) => ({ 'background-image': `var(--${name})` })]
164
+ ]
165
+ ```
79
166
 
80
- const app = createApp(App)
167
+ #### Prefixes your preset lacks
81
168
 
82
- app.directive('uno-style', createVUnoStyle({
83
- breakpoints: { sm: 0, md: '768px', lg: '1024px' },
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
- app.mount('#app')
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
- The package also exports `vUnoStyle`, preconfigured with the Canvas-compatible
90
- `{ sm: 0, md: 768, lg: 1024 }` breakpoints.
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
- Use an argument for one property:
198
+ ## Breakpoints
93
199
 
94
- ```vue
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
- Use the object form for several properties on one element:
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
- ```vue
105
- <template>
106
- <article
107
- v-uno-style="{
108
- c: { sm: '#111827', md: '#ffffff' },
109
- bg: { sm: '#ffffff', md: '#4f46e5' },
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
- Values may also be scalar. A scalar is assigned to the resolved base
119
- breakpoint: `v-uno-style:p="'1rem'"`.
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
- ## UnoCSS preset
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 and directive must use the same breakpoints:
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
- presetVUnoStyle({ baseBreakpoint: 'sm' })
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
- The preset declares the `override` layer after UnoCSS’s default layer, so
149
- runtime values win over ordinary utilities on the same element.
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
- ## ESLint plugin
334
+ ## Usage
152
335
 
153
- The directive merges its output into one class and style binding. Multiple
154
- instances on the same element are therefore rejected by
155
- `vue-uno-style/no-multiple-v-style`, which can autofix adjacent directives into
156
- the object form. It also reports unsupported argument names.
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
- When the directive is registered under another name, configure the rule with
173
- the same name:
408
+ Pass `directiveName` as well when the directive is registered under another
409
+ name.
174
410
 
175
- ```js
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
- ## Supported properties
187
-
188
- Property names follow UnoCSS utility prefixes. Each responsive value becomes a
189
- CSS custom property consumed by that utility.
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
- ```ts
243
- import {
244
- getStyle,
245
- getStyleProps,
246
- getVarsClasses,
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
- ## Demo
424
+ ## Options
253
425
 
254
- `demo/` is a minimal Nuxt app exercising the module, preset, directive, ESLint
255
- plugin, argument and object syntaxes, `bgi`, `bgv`, and server-rendered output:
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
- ```bash
258
- pnpm build
259
- pnpm demo:install
260
- pnpm demo:verify
261
- pnpm demo:dev
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
- ## Releasing
277
-
278
- `pnpm release` validates the repository, bumps and tags the version, and pushes
279
- the tag. The tag starts the GitHub Actions release workflow; publishing stays in
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