npm - @barocss/browser - Versions diffs - 0.6.0 → 0.7.0 - Mend

@barocss/browser 0.6.0 → 0.7.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.

Files changed (9) hide show

package/README.md +23 -1
package/dist/cdn/barocss.js +187 -42
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 +2 -2

package/README.md CHANGED Viewed

@@ -21,6 +21,8 @@ const runtime = getRuntime({
   config: {
     cssVarPrefix: 'tw',             // share --tw-* composite variables with the Tailwind build
     theme: { extend: shadcnTheme }, // use the shadcn :root tokens (primary, muted-foreground, ...)
+    darkMode: 'class',              // dark: follows the page's dark class, not the OS setting
+    darkModeSelector: '.dark &',    // mirrors shadcn v4's `@custom-variant dark (&:is(.dark *))`
     // preflight: leave unset. The layered preflight (@layer base) is the default and should stay on.
   },
 });
@@ -31,10 +33,22 @@ preloadJsonRenderClasses(spec, runtime);  // BEFORE mounting, so there is no uns
 renderJsonUi(spec);                       // mount your json-render Renderer
 ```
-The five settings: `skipExisting: true`, `cssVarPrefix: 'tw'`, `theme: { extend: shadcnTheme }`, `preloadJsonRenderClasses(spec, runtime)` before mount, and the default layered preflight (don't set `preflight: false`).
+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`).
+**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:
+| build CSS | companion config |
+|---|---|
+| `@custom-variant dark (&:is(.dark *));` (shadcn v4) | `darkMode: 'class', darkModeSelector: '.dark &'` |
+| `@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));` (e.g. AstroPaper) | `darkMode: 'class', darkModeSelector: '[data-theme=dark] &'` |
+| no `@custom-variant dark` (OS setting) | leave `darkMode` unset (`'media'`) |
+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.
 **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.
+**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.
 **Verify it rendered** (DevTools console, after mount):
 ```js
@@ -45,6 +59,14 @@ document.querySelectorAll('style[id^="barocss-runtime"]').length; // > 0
 **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.
+## Server-rendered pages (SSR)
+> 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.
+>
+> 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`).
+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).
 ## ✨ Key Features
 - **🚀 Real-time DOM Detection** - Automatically detects and processes class changes

package/dist/cdn/barocss.js CHANGED Viewed

@@ -178,8 +178,12 @@ function clearContextCaches(ctx) {
 }
 const utilityRegistry = [];
 function registerUtility(util, ctx) {
-  utilityRegistry.push(util);
-  {
+  const state = ctx && getContextState(ctx);
+  if (ctx && !state) throw new Error("Utility registration requires a context from createContext");
+  (state?.utilities || utilityRegistry).push(util);
+  if (ctx) {
+    clearContextCaches(ctx);
+  } else {
     parseResultCache.clear();
     utilityCache.clear();
   }
@@ -273,7 +277,7 @@ function staticUtility(name, decls, opts, ctx) {
     description: opts?.description,
     category: opts?.category,
     priority: opts?.priority
-  });
+  }, ctx);
 }
 function spacingKeyValue(ctx, key, negative) {
   if (key === "px" || !/^[a-zA-Z][\w-]*$/.test(key) || ctx.theme("spacing", key) == null) return null;
@@ -374,7 +378,7 @@ function functionalUtility(opts, ctx) {
     description: opts.description,
     category: opts.category,
     priority: opts.priority
-  });
+  }, ctx);
 }
 const MATH_FNS = /* @__PURE__ */ new Set(["calc", "min", "max", "clamp"]);
 function expandThemeFunctions(value) {
@@ -493,14 +497,23 @@ function parseClassName(className, ctx) {
   if (cache.has(className)) {
     return cache.get(className);
   }
-  let important = false;
   let realClassName = className;
-  if (className.startsWith("!")) {
+  const classPrefix = ctx ? configuredClassPrefix(ctx) : "";
+  if (classPrefix) {
+    if (!className.startsWith(classPrefix + ":")) {
+      const none = { modifiers: [], utility: null };
+      cache.set(className, none);
+      return none;
+    }
+    realClassName = className.slice(classPrefix.length + 1);
+  }
+  let important = false;
+  if (realClassName.startsWith("!")) {
     important = true;
-    realClassName = className.slice(1);
-  } else if (className.length > 1 && className.endsWith("!")) {
+    realClassName = realClassName.slice(1);
+  } else if (realClassName.length > 1 && realClassName.endsWith("!")) {
     important = true;
-    realClassName = className.slice(0, -1);
+    realClassName = realClassName.slice(0, -1);
   }
   const tokens = tokenize(realClassName);
   const result = parseTokens(tokens, ctx);
@@ -510,6 +523,10 @@ function parseClassName(className, ctx) {
   cache.set(className, result);
   return result;
 }
+function configuredClassPrefix(ctx) {
+  const configured = ctx.config("prefix");
+  return typeof configured === "string" && /^[a-z]+$/.test(configured) ? configured : "";
+}
 function parseTokens(tokens, ctx) {
   const modifiers = [];
   let utility = null;
@@ -1029,24 +1046,41 @@ function animationToCssVars(animations2) {
   }
   return result;
 }
-function keyframesToCss(keyframes2) {
-  if (!keyframes2) return "";
-  let css = "";
-  for (const name in keyframes2) {
-    const frames = keyframes2[name];
-    css += `@keyframes ${name} {
+const COMMENT_OR_BLOCK = /\/\*|\*\/|[{};]/;
+function keyframesBlock(name, frames) {
+  if (!name || COMMENT_OR_BLOCK.test(name) || /\s/.test(name) || !frames || typeof frames !== "object") return "";
+  let body = "";
+  for (const [step, props] of Object.entries(frames)) {
+    if (COMMENT_OR_BLOCK.test(step) || !props || typeof props !== "object") return "";
+    let decls = "";
+    for (const [prop, value] of Object.entries(props)) {
+      const v2 = String(value);
+      if (COMMENT_OR_BLOCK.test(prop) || COMMENT_OR_BLOCK.test(v2)) return "";
+      decls += `    ${prop}: ${v2};
 `;
-    for (const step in frames) {
-      css += `  ${step} {`;
-      const props = frames[step];
-      for (const prop in props) {
-        css += ` ${prop}: ${props[prop]};`;
-      }
-      css += " }\n";
     }
-    css += "}\n";
+    body += `  ${step} {
+${decls}  }
+`;
+  }
+  return `@keyframes ${name} {
+${body}}`;
+}
+function referencedKeyframes(css, ctx) {
+  if (!css.includes("animation")) return [];
+  const all = ctx.theme("keyframes");
+  if (!all || typeof all !== "object") return [];
+  const names = /* @__PURE__ */ new Set();
+  for (const m of css.matchAll(/(?:^|[\s;{])animation(?:-name)?\s*:\s*([^;}]+)/g)) {
+    const value = m[1].replace(/var\(--animate-([\w-]+)\)/g, (whole, key) => {
+      const v2 = ctx.theme("animations", key) ?? ctx.theme("animation", key);
+      return typeof v2 === "string" ? v2 : whole;
+    });
+    for (const word of value.split(/[\s,()]+/)) {
+      if (word && Object.prototype.hasOwnProperty.call(all, word)) names.add(word);
+    }
   }
-  return css;
+  return [...names].map((n) => keyframesBlock(n, all[n])).filter(Boolean);
 }
 function transitionTimingFunctionToCssVars(transition) {
   const result = {};
@@ -1114,7 +1148,7 @@ function themeToCssVarsAll(theme) {
     ...borderRadiusToCssVars(theme.borderRadius),
     ...zIndexToCssVars(theme.zIndex),
     ...opacityToCssVars(theme.opacity),
-    ...animationToCssVars(theme.animations),
+    ...animationToCssVars({ ...theme.animations, ...theme.animation }),
     ...transitionTimingFunctionToCssVars(theme.transitionTimingFunction),
     ...transitionDurationToCssVars(theme.transitionDuration),
     ...transitionDelayToCssVars(theme.transitionDelay),
@@ -1480,6 +1514,7 @@ function generateCssRules(classList, ctx, opts) {
       const css = rootToCss([node]);
       rootCssList.push(css);
     }
+    rootCssList.push(...referencedKeyframes(cssList.join("\n"), ctx));
     return {
       cls,
       ast: allCleanAst,
@@ -2276,11 +2311,7 @@ const keyframes = {
     }
   },
   ping: {
-    "75%": {
-      transform: "scale(2)",
-      opacity: "0"
-    },
-    "100%": {
+    "75%, 100%": {
       transform: "scale(2)",
       opacity: "0"
     }
@@ -2290,14 +2321,15 @@ const keyframes = {
       opacity: "0.5"
     }
   },
+  // #274: Tailwind 4.1.13's frames (0%/100% share the up position; 50% is the floor).
   bounce: {
-    "0%": {
+    "0%, 100%": {
       transform: "translateY(-25%)",
-      "animation-timing-function": "cubic-bezier(0.8,0,1,1)"
+      "animation-timing-function": "cubic-bezier(0.8, 0, 1, 1)"
     },
-    "100%": {
+    "50%": {
       transform: "none",
-      "animation-timing-function": "cubic-bezier(0,0,0.2,1)"
+      "animation-timing-function": "cubic-bezier(0, 0, 0.2, 1)"
     }
   }
 };
@@ -2372,6 +2404,48 @@ const defaultTheme = {
   // Tailwind 4.1.13 --aspect-* (aspect-video → var(--aspect-video))
   aspect: { video: "16 / 9" }
 };
+const customUtilityName = /^[A-Za-z_][A-Za-z0-9_-]*$/;
+const customUtilityProp = /^(--[A-Za-z0-9_-]+|-?[A-Za-z][A-Za-z0-9-]*)$/;
+function validateCustomUtility(name, decls) {
+  if (typeof name !== "string" || !customUtilityName.test(name)) return null;
+  if (!decls || typeof decls !== "object" || Array.isArray(decls)) return null;
+  const out = [];
+  for (const [prop, raw] of Object.entries(decls)) {
+    if (typeof raw !== "string" && typeof raw !== "number") return null;
+    const value = String(raw).trim();
+    if (!customUtilityProp.test(prop) || !value || !isStructureSafeValue(value) || hasCommentDelimiter(value)) return null;
+    out.push([prop, value]);
+  }
+  return out.length ? out : null;
+}
+function registerCustomUtilities(ctx, utilities) {
+  if (!utilities || typeof utilities !== "object" || Array.isArray(utilities)) return;
+  const list = getUtility(ctx);
+  const builtins = [...list];
+  const before = list.length;
+  for (const [name, decls] of Object.entries(utilities)) {
+    const safe = validateCustomUtility(name, decls);
+    if (!safe) {
+      debugWarn(`[BAROCSS] Ignoring invalid custom utility "${name}"`);
+      continue;
+    }
+    const shadowed = builtins.filter((u) => u.match(name));
+    registerUtility({
+      name,
+      category: "custom",
+      match: (className) => className === name,
+      handler: (value, c, token) => {
+        let base = [];
+        for (const reg of shadowed) {
+          base = reg.handler(value, c, token, reg) || [];
+          if (base.length > 0) break;
+        }
+        return [...base, ...safe.map(([prop, v]) => decl(prop, v))];
+      }
+    }, ctx);
+  }
+  if (list.length > before) list.unshift(...list.splice(before));
+}
 const preflightMinimalCSS = `
 /* BaroCSS Preflight - Minimal Reset */
 /* ================================= */
@@ -3254,9 +3328,7 @@ function resolveTheme(config) {
 }
 function themeToCssVars(theme) {
   const vars = themeToCssVarsAll(theme);
-  const result = toCssVarsBlock(vars, `
-${keyframesToCss(theme.keyframes || {})}
-`);
+  const result = toCssVarsBlock(vars);
   return result;
 }
 function createContext(configObj) {
@@ -3310,6 +3382,7 @@ function createContext(configObj) {
     }
   };
   initializeContextState(ctx, getUtility(), getModifier());
+  registerCustomUtilities(ctx, configObj.utilities);
   return ctx;
 }
 function parseFraction(input) {
@@ -3907,10 +3980,12 @@ staticUtility("animate-bounce", [["animation", "var(--animate-bounce)"]], { cate
 staticUtility("animate-none", [["animation", "none"]], { category: "transitions" });
 functionalUtility({
   name: "animate",
-  prop: "animation",
+  // #274: theme.animations (and Tailwind's theme.animation) names, e.g. theme.extend.animation.wiggle.
+  themeKeys: ["animations", "animation"],
   supportsArbitrary: true,
   supportsCustomProperty: true,
-  handle: (value, ctx, token) => {
+  handle: (value, ctx, token, extra) => {
+    if (extra?.realThemeValue) return [decl("animation", `var(--animate-${extra.realThemeValue})`)];
     if (token.customProperty) {
       return [decl("animation", `var(${value})`)];
     }
@@ -9114,7 +9189,7 @@ class ChangeDetector {
 function unescapeCssIdent(s) {
   return s.replace(/\\([0-9a-fA-F]{1,6})\s?|\\(.)/g, (_m, hex, ch) => hex ? String.fromCodePoint(parseInt(hex, 16)) : ch);
 }
-const LEADING_CLASS = /^\s*\.((?:\\[0-9a-fA-F]{1,6}\s?|\\.|[\w-]|[^\x00-\x7F])+)/;
+const LEADING_CLASS = /^\s*(?::(?:where|is)\(\s*)?\.((?:\\[0-9a-fA-F]{1,6}\s?|\\.|[\w-]|[^\x00-\x7F])+)/;
 function splitTopLevel(sel) {
   const parts = [];
   let depth = 0, start = 0;
@@ -9131,6 +9206,17 @@ function splitTopLevel(sel) {
   parts.push(sel.slice(start));
   return parts;
 }
+function collectKeyframeNames(rules, out = /* @__PURE__ */ new Set()) {
+  for (const rule2 of Array.from(rules)) {
+    if (rule2.type === 7 && typeof rule2.name === "string") {
+      out.add(rule2.name);
+      continue;
+    }
+    const inner = rule2.cssRules;
+    if (inner && inner.length) collectKeyframeNames(inner, out);
+  }
+  return out;
+}
 function collectLeadingClasses(rules, out = /* @__PURE__ */ new Set()) {
   for (const rule2 of Array.from(rules)) {
     const selectorText = rule2.selectorText;
@@ -9254,6 +9340,7 @@ class ClassGc {
     return { trackedClasses: this.counts.size, candidates: this.candidates.size };
   }
 }
+const SSR_STYLE_SELECTOR = "style[data-barocss-ssr]";
 const LAYER_ORDER = "@layer theme, base, components, utilities;";
 class BrowserRuntime {
   constructor(options = {}) {
@@ -9261,10 +9348,14 @@ class BrowserRuntime {
     this.rootCache = /* @__PURE__ */ new Set();
     this.isDestroyed = false;
     this.existing = null;
+    this.existingKeyframes = /* @__PURE__ */ new Set();
     this.existingSheetCount = -1;
     this.pinned = /* @__PURE__ */ new Set();
     this.gc = null;
     this.reclaimedCount = 0;
+    this.ssrRules = [];
+    this.ssrClasses = /* @__PURE__ */ new Set();
+    this.observedOnce = false;
     this.getCategory = (cls) => parseClassName(cls, this.context).utility?.category;
     const defaultConfig = {};
     this.options = {
@@ -9303,6 +9394,44 @@ class BrowserRuntime {
     console.log("[BrowserRuntime] init");
     this.injectPreflightCSS();
     this.ensureCssVars();
+    this.adoptSsrSheets();
+  }
+  /**
+   * #268: adopt the class rules of server-rendered `<style data-barocss-ssr>` sheets in <head>, at startup
+   * (constructor and the first observe()). Each rule moves
+   * (same task, so no paint in between) into the partition its class would get if generated here, at
+   * its #254 sorted position, so a later client `sm:` rule lands before a server `lg:` rule. Its classes
+   * are never regenerated and never reclaimed. `:root`, `@property` and `@keyframes` stay in the sheet.
+   */
+  adoptSsrSheets() {
+    if (typeof document === "undefined") return;
+    const adopted = [];
+    if (!document.head) return;
+    for (const el of Array.from(document.head.querySelectorAll(`${SSR_STYLE_SELECTOR}:not([data-barocss-adopted])`))) {
+      const sheet = el.sheet;
+      if (!sheet) continue;
+      el.setAttribute("data-barocss-adopted", "");
+      const moved = [];
+      for (let i = sheet.cssRules.length - 1; i >= 0; i--) {
+        const rule2 = sheet.cssRules[i];
+        const classes = collectLeadingClasses([rule2]);
+        if (classes.size === 0) continue;
+        classes.forEach((cls) => this.ssrClasses.add(cls));
+        moved.unshift({ css: rule2.cssText, cls: classes.values().next().value });
+        sheet.deleteRule(i);
+      }
+      adopted.push(...moved);
+    }
+    if (adopted.length === 0) return;
+    this.ssrRules.push(...adopted);
+    this.insertSsrRules(adopted);
+  }
+  insertSsrRules(rules) {
+    for (const { css, cls } of rules) {
+      const category = this.getCategory(cls);
+      if (category) this.stylePartitionManager.addCategoryRule(css, category);
+      else this.stylePartitionManager.addRule(css);
+    }
   }
   injectPreflightCSS() {
     const level = this.options.config.preflight ?? true;
@@ -9370,6 +9499,7 @@ ${preflightCSS}
       results = [...existingResults, ...results];
       results.forEach((result) => this.incrementalParser.markProcessed(result.cls));
     }
+    if (this.ssrClasses.size > 0) results = results.filter((result) => !this.ssrClasses.has(result.cls));
     if (this.options.skipExisting && results.length > 0 && typeof document !== "undefined") {
       const existing = this.getExistingClasses();
       results = results.filter((result) => !existing.has(result.cls));
@@ -9377,6 +9507,7 @@ ${preflightCSS}
     if (results.length === 0) return;
     const cssRules = [];
     const rootCssRules = [];
+    const pageKeyframes = this.options.skipExisting && typeof document !== "undefined" ? (this.getExistingClasses(), this.existingKeyframes) : null;
     for (const result of results) {
       if (result.css && Array.isArray(result.cssList)) {
         cssRules.push(result);
@@ -9384,6 +9515,10 @@ ${preflightCSS}
       }
       if (result.rootCss && Array.isArray(result.rootCssList)) {
         for (const rootCss of result.rootCssList) {
+          if (pageKeyframes?.size) {
+            const kf = /^\s*@keyframes\s+([^\s{]+)/.exec(rootCss)?.[1];
+            if (kf && pageKeyframes.has(kf)) continue;
+          }
           if (!this.rootCache.has(rootCss)) {
             this.rootCache.add(rootCss);
             rootCssRules.push(rootCss);
@@ -9404,12 +9539,12 @@ ${preflightCSS}
   }
   /** #269: a class that must never be reclaimed. */
   isPermanent(cls) {
-    if (this.pinned.has(cls)) return true;
+    if (this.pinned.has(cls) || this.ssrClasses.has(cls)) return true;
     if (typeof document === "undefined") return true;
     return this.getExistingClasses().has(cls);
   }
   /**
-   * #269: delete the generated rules of classes no live element uses. Root/@property rules stay
+   * #269: delete the generated rules of classes no live element uses. Root/@property/@keyframes rules stay
    * (they are shared and harmless); a rule text another cached class still emits is kept.
    */
   reclaim(classes) {
@@ -9441,6 +9576,7 @@ ${preflightCSS}
     });
     if (this.existing && sheets.length === this.existingSheetCount) return this.existing;
     const out = /* @__PURE__ */ new Set();
+    const keyframes2 = /* @__PURE__ */ new Set();
     for (const sheet of sheets) {
       let rules;
       try {
@@ -9449,7 +9585,9 @@ ${preflightCSS}
         continue;
       }
       collectLeadingClasses(rules, out);
+      collectKeyframeNames(rules, keyframes2);
     }
+    this.existingKeyframes = keyframes2;
     this.existing = out;
     this.existingSheetCount = sheets.length;
     return out;
@@ -9458,6 +9596,10 @@ ${preflightCSS}
    * MutationObserver instance method to automatically call addClass when class attributes change in DOM
    */
   observe(root = document.body, options) {
+    if (!this.observedOnce) {
+      this.observedOnce = true;
+      this.adoptSsrSheets();
+    }
     return this.changeDetector.observe(root, options);
   }
   normalizeClasses(classes) {
@@ -9509,6 +9651,7 @@ ${preflightCSS}
     this.stylePartitionManager = new StylePartitionManager(this.getInsertionPoint(), this.options.maxRulesPerPartition, `${this.options.styleId}-partition`, this.getCategory);
     this.injectPreflightCSS();
     this.ensureCssVars();
+    this.insertSsrRules(this.ssrRules);
   }
   reset() {
     if (this.isDestroyed) return;
@@ -9519,6 +9662,7 @@ ${preflightCSS}
     this.stylePartitionManager = new StylePartitionManager(this.getInsertionPoint(), this.options.maxRulesPerPartition, `${this.options.styleId}-partition`, this.getCategory);
     this.injectPreflightCSS();
     this.ensureCssVars();
+    this.insertSsrRules(this.ssrRules);
   }
   updateConfig(newConfig) {
     if (this.isDestroyed) return;
@@ -9661,6 +9805,7 @@ export {
   BrowserRuntime,
   ChangeDetector,
   LAYER_ORDER,
+  SSR_STYLE_SELECTOR,
   StylePartitionManager,
   baroBoot,
   baroStart,