@barocss/browser 0.8.2 → 0.10.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 +25 -0
- package/dist/cdn/barocss.js +1 -1
- 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.cjs +9 -3
- package/dist/index.d.cts +56 -5
- package/dist/index.d.ts +56 -5
- package/dist/index.es.js +321 -62
- package/dist/index.umd.js +9 -3
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,5 +1,7 @@
|
|
|
1
1
|
# @barocss/browser
|
|
2
2
|
|
|
3
|
+
> **Rendering untrusted class strings (AI output, CMS, users)?** See the [security guide](../../apps/barocss-docs/docs/guide/security.md).
|
|
4
|
+
|
|
3
5
|
[](https://www.npmjs.com/package/@barocss/browser)
|
|
4
6
|
[](https://opensource.org/licenses/MIT)
|
|
5
7
|
[](https://www.typescriptlang.org/)
|
|
@@ -61,6 +63,29 @@ document.querySelectorAll('style[id^="barocss-runtime"]').length; // > 0
|
|
|
61
63
|
|
|
62
64
|
**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.
|
|
63
65
|
|
|
66
|
+
## Recipe: Embedding AI widgets (Shadow DOM)
|
|
67
|
+
|
|
68
|
+
A widget in a shadow root is isolated from the host page's CSS, but a `<head>` stylesheet cannot reach it either. Pass the root:
|
|
69
|
+
|
|
70
|
+
```ts
|
|
71
|
+
import { BrowserRuntime } from '@barocss/browser';
|
|
72
|
+
|
|
73
|
+
const host = document.querySelector('ai-widget')!;
|
|
74
|
+
const root = host.attachShadow({ mode: 'open' }); // 'closed' works too: the embedder holds the reference
|
|
75
|
+
root.innerHTML = modelHtml;
|
|
76
|
+
const runtime = new BrowserRuntime({ root, config }); // or baroStart({ root, config })
|
|
77
|
+
// later: runtime.destroy() when the widget is removed
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
**Call `runtime.destroy()` when the widget unmounts** (for example in a custom element's `disconnectedCallback`). Otherwise a removed host keeps its rule references and its shared-sheet registry entry, so those rules are never reclaimed.
|
|
81
|
+
|
|
82
|
+
- The runtime observes `root` (with an initial scan) and puts all of its CSS inside it: utilities, theme variables (`:root,:host`), `@property`, `@keyframes` and preflight. Nothing goes to `document.head`, and the host page is not changed.
|
|
83
|
+
- **Preflight is scoped to the root.** `html`/`:root` selectors become `:host`. `body` rules are dropped and their declarations are re-emitted last on `:host`, without `min-height: 100vh` and `scroll-behavior`. So the widget gets the preflight font (it no longer inherits the host's `font-family`) and border reset, as in a Tailwind 4 build. Like Tailwind, preflight does not set `color`, so the host's text colour still inherits into the widget unless you set one (for example `text-gray-900` on the widget's wrapper).
|
|
84
|
+
- **Shared sheets.** Runtimes with the same config (and prefix) share one constructable stylesheet that every root adopts through `root.adoptedStyleSheets`. Each class is generated once, whichever root uses it first. Rules keep Tailwind's variant order (#254). GC (#269) counts per root and across roots: a rule is deleted only when no root still uses its class. `runtime.getStats().sharedSheet` reports roots, rules and generations of the shared sheet.
|
|
85
|
+
- **Fallback.** Without constructable stylesheets, each root gets two `<style data-barocss>` elements (prologue and rules) at its start, which mirror the same shared rule list.
|
|
86
|
+
- `insertionPoint`, `styleId` and `maxRulesPerPartition` do not apply in this mode, and a server-rendered `<style data-barocss-ssr>` sheet (#268) is adopted only in document mode.
|
|
87
|
+
- `root` must be a `ShadowRoot` (or `document`, which is the normal document mode). For a widget in a plain `<div>`, use the document mode (`getRuntime().observe(container)`): the host's CSS and the widget's CSS then cascade together, so use a shadow root when you need isolation.
|
|
88
|
+
|
|
64
89
|
## Server-rendered pages (SSR)
|
|
65
90
|
|
|
66
91
|
> 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.
|