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 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
- # Temporary Holding Version
1
+ # vue-uno-style
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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 {}