@barocss/browser 0.6.0 → 0.8.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 +27 -1
- package/dist/cdn/barocss.js +688 -306
- package/dist/cdn/barocss.js.map +1 -1
- package/dist/cdn/barocss.umd.cjs +1 -1
- package/dist/cdn/barocss.umd.cjs.map +1 -1
- package/dist/index.d.ts +19 -1
- package/dist/index.es.js +153 -105
- package/dist/index.umd.js +5 -5
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -8,6 +8,8 @@
|
|
|
8
8
|
|
|
9
9
|
@barocss/browser provides a browser-specific runtime that automatically detects DOM changes and generates CSS in real-time. It includes DOM change detection, style injection, and performance optimizations for browser environments.
|
|
10
10
|
|
|
11
|
+
> **Need styled first paint on server-rendered pages?** Use the [`@barocss/server` recipe](../barocss-server/README.md#recipe-ssr-with-a-tailwind-build-nextjs-app-router-astro) (Astro: [docs guide](../../apps/barocss-docs/docs/guide/integration/astro.md)). The recipe below is client-only.
|
|
12
|
+
|
|
11
13
|
## Recipe: BaroCSS next to a Tailwind/shadcn build (json-render)
|
|
12
14
|
|
|
13
15
|
Use this when the page already links a Tailwind 4 / shadcn build and a model sends json-render specs whose `className` values the build never saw. Copy it as is:
|
|
@@ -21,6 +23,8 @@ const runtime = getRuntime({
|
|
|
21
23
|
config: {
|
|
22
24
|
cssVarPrefix: 'tw', // share --tw-* composite variables with the Tailwind build
|
|
23
25
|
theme: { extend: shadcnTheme }, // use the shadcn :root tokens (primary, muted-foreground, ...)
|
|
26
|
+
darkMode: 'class', // dark: follows the page's dark class, not the OS setting
|
|
27
|
+
darkModeSelector: '.dark &', // mirrors shadcn v4's `@custom-variant dark (&:is(.dark *))`
|
|
24
28
|
// preflight: leave unset. The layered preflight (@layer base) is the default and should stay on.
|
|
25
29
|
},
|
|
26
30
|
});
|
|
@@ -31,10 +35,22 @@ preloadJsonRenderClasses(spec, runtime); // BEFORE mounting, so there is no uns
|
|
|
31
35
|
renderJsonUi(spec); // mount your json-render Renderer
|
|
32
36
|
```
|
|
33
37
|
|
|
34
|
-
The
|
|
38
|
+
The six settings: `skipExisting: true`, `cssVarPrefix: 'tw'`, `theme: { extend: shadcnTheme }`, `darkMode: 'class'` with `darkModeSelector` copied from the build, `preloadJsonRenderClasses(spec, runtime)` before mount, and the default layered preflight (don't set `preflight: false`).
|
|
39
|
+
|
|
40
|
+
**Dark mode:** set `darkModeSelector` to the selector inside your CSS's `@custom-variant dark (...)`, so runtime `dark:` classes switch at the same moment as the build's:
|
|
41
|
+
|
|
42
|
+
| build CSS | companion config |
|
|
43
|
+
|---|---|
|
|
44
|
+
| `@custom-variant dark (&:is(.dark *));` (shadcn v4) | `darkMode: 'class', darkModeSelector: '.dark &'` |
|
|
45
|
+
| `@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));` (e.g. AstroPaper) | `darkMode: 'class', darkModeSelector: '[data-theme=dark] &'` |
|
|
46
|
+
| no `@custom-variant dark` (OS setting) | leave `darkMode` unset (`'media'`) |
|
|
47
|
+
|
|
48
|
+
Don't use `darkMode: 'class'` without a selector here: it matches `.dark` on the same element only, so `<html class="dark">` does not switch runtime classes.
|
|
35
49
|
|
|
36
50
|
**Non-shadcn site theme:** put the site's own tokens in `theme.extend` (e.g. `colors: { brand: { 600: '#2563eb' } }`). Literal values are safe. Pointing a token at the build's own var name (`brand: { 600: 'var(--color-brand-600)' }`) is also fine: BaroCSS skips that self-referencing `:root` var, so the build's value wins and `bg-brand-600` still uses it.
|
|
37
51
|
|
|
52
|
+
**Custom utilities:** mirror each static `@utility name { ... }` from your CSS in `utilities`, so runtime content that reuses it (with variants and `!`) matches the build: `utilities: { 'max-w-app': { 'max-width': '72rem', 'margin-inline': 'auto' } }`. A name that equals a built-in extends it as `@utility` does in Tailwind 4: the built-in declarations come first, then yours, so a repeated property takes your value. Names must be plain class idents; invalid names or unsafe declarations are skipped. Functional `@utility name-*` is not supported.
|
|
53
|
+
|
|
38
54
|
**Verify it rendered** (DevTools console, after mount):
|
|
39
55
|
|
|
40
56
|
```js
|
|
@@ -45,6 +61,14 @@ document.querySelectorAll('style[id^="barocss-runtime"]').length; // > 0
|
|
|
45
61
|
|
|
46
62
|
**Browser support:** Chrome/Edge 85+, Safari/iOS 16.4+, Firefox 128+. The runtime needs CSS `@property`; composite utilities (shadows, rings, transforms, filters) may not render on older engines.
|
|
47
63
|
|
|
64
|
+
## Server-rendered pages (SSR)
|
|
65
|
+
|
|
66
|
+
> BaroCSS is JS-only: there is no CSS entry, so never `@import "@barocss/kit"` in CSS. `generateCssForHtml`/`ssrStyleTag` are available from `@barocss/server` 0.7.0.
|
|
67
|
+
>
|
|
68
|
+
> Use the same config as the server: `darkModeSelector` from the build's `@custom-variant dark`, `utilities` mirroring static `@utility` rules (functional `@utility name-*` unsupported), both `prefix: 'tw'` and `cssVarPrefix: 'tw'` for a `prefix(tw)` build, and literal values in `theme.extend` for your own theme (next to `shadcnTheme`).
|
|
69
|
+
|
|
70
|
+
The runtime adopts a `<style data-barocss-ssr>` sheet from `@barocss/server` (`ssrStyleTag(runtime.generateCssForHtml(html, { skip: buildCss }))`), but only one that is in `<head>` when the runtime starts (at construction or the first `observe()`). A marked sheet added later or placed in `<body>` is treated as an ordinary sheet. It never regenerates those classes and GC never reclaims them. Their rules move into the runtime's ordered partitions, so later client rules keep Tailwind's variant order. For the Next.js App Router and Astro recipe, see the [`@barocss/server` README](../barocss-server/README.md#recipe-ssr-with-a-tailwind-build-nextjs-app-router-astro).
|
|
71
|
+
|
|
48
72
|
## ✨ Key Features
|
|
49
73
|
|
|
50
74
|
- **🚀 Real-time DOM Detection** - Automatically detects and processes class changes
|
|
@@ -109,6 +133,8 @@ The helper reads literal `props.className` strings in the flat `spec.elements` m
|
|
|
109
133
|
|
|
110
134
|
### CDN Usage
|
|
111
135
|
|
|
136
|
+
> **CDN global is browser-only.** The CDN UMD script's `window.BaroCSS` exposes only `@barocss/browser`: `BrowserRuntime`, `getRuntime`, `baroBoot`/`baroStart`, `ChangeDetector`, `StylePartitionManager`, `shadcnTheme`, `preloadJsonRenderClasses`, `collectJsonRenderClassNames`, `normalizeClassName(List)`, `SSR_STYLE_SELECTOR`, `LAYER_ORDER`. There is no `generateCss`/`generateCssForHtml`/`ServerRuntime` in it: server-side generation needs `@barocss/server` in Node.
|
|
137
|
+
|
|
112
138
|
```html
|
|
113
139
|
<!DOCTYPE html>
|
|
114
140
|
<html>
|