@barocss/browser 0.5.0 → 0.6.0

package/README.md

@@ -33,6 +33,8 @@ 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`).
 
+**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.
+
 **Verify it rendered** (DevTools console, after mount):
 
 ```js

package/dist/cdn/barocss.js

@@ -275,6 +275,11 @@ function staticUtility(name, decls, opts, ctx) {
     priority: opts?.priority
   });
 }
+function spacingKeyValue(ctx, key, negative) {
+  if (key === "px" || !/^[a-zA-Z][\w-]*$/.test(key) || ctx.theme("spacing", key) == null) return null;
+  const ref = `var(--spacing-${key})`;
+  return negative ? `calc(${ref} * -1)` : ref;
+}
 function functionalUtility(opts, ctx) {
   registerUtility({
     name: opts.name,
@@ -343,14 +348,17 @@ function functionalUtility(opts, ctx) {
       if (opts.supportsFraction && /^-?\d+\/\d+$/.test(value)) {
         finalValue = value;
       }
+      const spacingKey = opts.spacingKeys ? spacingKeyValue(ctx2, String(finalValue).replace(/^-/, ""), !!parsedUtility.negative) : null;
       if (parsedUtility.negative && opts.supportsNegative && opts.handleNegativeBareValue) {
-        const bare = opts.handleNegativeBareValue({ value: String(finalValue).replace(/^-/, ""), ctx: ctx2, token, extra });
+        const bare = opts.handleNegativeBareValue({ value: String(finalValue).replace(/^-/, ""), ctx: ctx2, token, extra }) ?? spacingKey;
         if (bare == null) return [];
         finalValue = bare;
       } else if (opts.handleBareValue) {
-        const bare = opts.handleBareValue({ value: finalValue, ctx: ctx2, token, extra });
+        const bare = opts.handleBareValue({ value: finalValue, ctx: ctx2, token, extra }) ?? spacingKey;
         if (bare == null) return [];
         finalValue = bare;
+      } else if (spacingKey) {
+        finalValue = spacingKey;
       } else if (!/^-?(\d|\.\d)/.test(String(finalValue))) {
         return [];
       }
@@ -561,6 +569,18 @@ function isSafeVariantToken(value) {
 function hasCommentToken(value) {
   return value.includes("/*") || value.includes("*/");
 }
+function hasCommentDelimiter(text) {
+  for (let i = 0; i < text.length - 1; i++) {
+    const c = text[i];
+    if (c === "\\") {
+      i++;
+      continue;
+    }
+    const n = text[i + 1];
+    if (c === "/" && n === "*" || c === "*" && n === "/") return true;
+  }
+  return false;
+}
 function isStructureSafeValue(value) {
   if (hasCommentToken(value)) return false;
   return isSafeVariantValue(value, true);
@@ -708,6 +728,7 @@ function parseUtility(value, ctx) {
     priority
   };
 }
+const isSafePrelude = (text) => !hasCommentDelimiter(String(text ?? ""));
 const isSafeDecl = (prop, value) => isStructureSafeValue(String(prop)) && isStructureSafeValue(String(value ?? ""));
 const importantPrefix = "!important";
 function astToCss(ast, baseSelector, opts, _indent = "") {
@@ -771,6 +792,7 @@ function astToCss(ast, baseSelector, opts, _indent = "") {
             }).join(", ");
           }
         }
+        if (!isSafePrelude(selector)) return "";
         if (minify) {
           const css = `${indent}${selector}{${astToCss(
             node.nodes,
@@ -795,6 +817,7 @@ ${astToCss(
         }
       }
       case "style-rule": {
+        if (!isSafePrelude(node.selector)) return "";
         if (minify) {
           const css = `${indent}${node.selector} {${astToCss(
             node.nodes,
@@ -819,6 +842,7 @@ ${astToCss(
         }
       }
       case "at-rule": {
+        if (!isSafePrelude(node.name) || !isSafePrelude(node.params)) return "";
         if (minify) {
           const css = `${indent}@${node.name} ${node.params}{${astToCss(
             node.nodes,
@@ -871,7 +895,7 @@ function rootToCss(nodes, opts) {
       if (isSafeDecl(node.prop, node.value)) {
         list.push(`${node.prop}: ${node.value};`);
       }
-    } else if (node.type === "at-rule") {
+    } else if (node.type === "at-rule" && isSafePrelude(node.name) && isSafePrelude(node.params)) {
       {
         list.push(
           `@${node.name} ${node.params} {
@@ -1099,8 +1123,13 @@ function themeToCssVarsAll(theme) {
     // keyframes handled separately
   };
 }
+function isSelfReferencingVar(name, value) {
+  if (typeof value !== "string") return false;
+  const m = /^var\(\s*(--[\w-]+)\s*(?:,[\s\S]*)?\)$/.exec(value.trim());
+  return !!m && m[1] === name.trim();
+}
 function toCssVarsBlock(vars, extra = "") {
-  return ":root,:host {\n" + Object.entries(vars).map(([k, v2]) => `  ${k}: ${v2};`).join("\n") + "\n}\n" + extra + "\n";
+  return ":root,:host {\n" + Object.entries(vars).filter(([k, v2]) => !isSelfReferencingVar(k, v2)).map(([k, v2]) => `  ${k}: ${v2};`).join("\n") + "\n}\n" + extra + "\n";
 }
 const BARO_VAR = /--baro-/g;
 const PREFIXED_KEYS = /* @__PURE__ */ new Set(["prop", "value", "params", "selector", "nodes", "items"]);
@@ -1713,6 +1742,15 @@ class IncrementalParser {
   markProcessed(cls) {
     this.processedClasses.add(cls);
   }
+  /**
+   * Forgets that a class was processed, so a later request generates it again
+   * (used when the browser runtime reclaims an unused class's rules, #269).
+   *
+   * @param cls - The CSS class name to forget
+   */
+  unmarkProcessed(cls) {
+    this.processedClasses.delete(cls);
+  }
   /**
    * Process classes synchronously and update BrowserRuntime cache
    * This method is used by ChangeDetector for scan operations
@@ -3682,6 +3720,7 @@ staticUtility("snap-proximity", [["--baro-scroll-snap-strictness", "proximity"]]
 ].forEach(([name, prop]) => {
   functionalUtility({
     name: `scroll-${name}`,
+    spacingKeys: true,
     prop,
     supportsArbitrary: true,
     supportsCustomProperty: true,
@@ -3709,6 +3748,7 @@ staticUtility("snap-proximity", [["--baro-scroll-snap-strictness", "proximity"]]
 ].forEach(([name, prop]) => {
   functionalUtility({
     name: `scroll-${name}`,
+    spacingKeys: true,
     prop,
     supportsArbitrary: true,
     supportsCustomProperty: true,
@@ -5242,6 +5282,7 @@ staticUtility("sticky", [["position", "sticky"]], { category: "layout" });
   staticUtility(`-${name}-px`, [[prop, "-1px"]], { category: "layout" });
   functionalUtility({
     name,
+    spacingKeys: true,
     prop,
     supportsNegative: true,
     supportsFraction: true,
@@ -5272,6 +5313,7 @@ staticUtility("invisible", [["visibility", "hidden"]], { category: "layout" });
 staticUtility("collapse", [["visibility", "collapse"]], { category: "layout" });
 functionalUtility({
   name: "gap-x",
+  spacingKeys: true,
   prop: "column-gap",
   supportsArbitrary: true,
   // gap-x-[10vw]
@@ -5288,6 +5330,7 @@ functionalUtility({
 });
 functionalUtility({
   name: "gap-y",
+  spacingKeys: true,
   prop: "row-gap",
   supportsArbitrary: true,
   // gap-y-[10vw]
@@ -5304,6 +5347,7 @@ functionalUtility({
 });
 functionalUtility({
   name: "gap",
+  spacingKeys: true,
   prop: "gap",
   supportsArbitrary: true,
   // gap-[10vw]
@@ -5821,6 +5865,7 @@ functionalUtility({
 ].forEach(([name, prop]) => {
   staticUtility(`${name}-px`, [[prop, "1px"]], { category: "spacing" });
   functionalUtility({
+    spacingKeys: true,
     name,
     prop,
     supportsArbitrary: true,
@@ -5845,6 +5890,7 @@ functionalUtility({
   staticUtility(`${name}-px`, [[prop, "1px"]], { category: "spacing" });
   staticUtility(`-${name}-px`, [[prop, "-1px"]], { category: "spacing" });
   functionalUtility({
+    spacingKeys: true,
     name,
     prop,
     supportsNegative: true,
@@ -5875,6 +5921,7 @@ const SPACE_SELECTOR = ":where(& > :not(:last-child))";
     () => rule(SPACE_SELECTOR, [decl(rev, "1")])
   ], { category: "spacing" });
   functionalUtility({
+    spacingKeys: true,
     name,
     supportsNegative: true,
     supportsArbitrary: true,
@@ -5924,6 +5971,7 @@ const SPACE_SELECTOR = ":where(& > :not(:last-child))";
   staticUtility(name, [["width", value]]);
 });
 functionalUtility({
+  spacingKeys: true,
   name: "w",
   prop: "width",
   supportsArbitrary: true,
@@ -5956,6 +6004,7 @@ functionalUtility({
   staticUtility(name, [["width", w], ["height", h]]);
 });
 functionalUtility({
+  spacingKeys: true,
   name: "size",
   supportsArbitrary: true,
   supportsCustomProperty: true,
@@ -5995,6 +6044,7 @@ functionalUtility({
   staticUtility(name, [["height", value]]);
 });
 functionalUtility({
+  spacingKeys: true,
   name: "h",
   prop: "height",
   supportsArbitrary: true,
@@ -6025,6 +6075,7 @@ functionalUtility({
   staticUtility(name, [["min-height", value]], { category: "sizing" });
 });
 functionalUtility({
+  spacingKeys: true,
   name: "min-h",
   prop: "min-height",
   supportsArbitrary: true,
@@ -6055,6 +6106,7 @@ functionalUtility({
   staticUtility(name, [["max-height", value]], { category: "sizing" });
 });
 functionalUtility({
+  spacingKeys: true,
   name: "max-h",
   prop: "max-height",
   supportsArbitrary: true,
@@ -6101,6 +6153,7 @@ functionalUtility({
   staticUtility(name, [["min-width", value]], { category: "sizing" });
 });
 functionalUtility({
+  spacingKeys: true,
   name: "min-w",
   prop: "min-width",
   supportsArbitrary: true,
@@ -6136,6 +6189,7 @@ functionalUtility({
   staticUtility(name, [["max-width", value]], { category: "sizing" });
 });
 functionalUtility({
+  spacingKeys: true,
   name: "max-w",
   prop: "max-width",
   supportsArbitrary: true,
@@ -8795,6 +8849,41 @@ class StylePartitionManager {
     }
     return { success, failed };
   }
+  /**
+   * Remove one generated rule (#269 GC). Keeps `styles`, the #254 `keys` and the
+   * sheet's cssRules parallel: one deleteRule at the rule's index, or a text
+   * rebuild when the sheet isn't solely ours / has no CSSOM. Returns whether
+   * the rule was found.
+   */
+  removeRule(rule2, category) {
+    let partition;
+    if (category) {
+      if (this.classToCategoryPartitionMap.get(rule2) !== category) return false;
+      partition = this.categoryPartitions.get(category);
+    } else {
+      const partitionIndex = this.classToPartitionMap.get(rule2);
+      partition = partitionIndex === void 0 ? void 0 : this.partitions[partitionIndex];
+    }
+    if (!partition) return false;
+    const index = partition.styles.indexOf(rule2);
+    if (index === -1) return false;
+    const sheet = partition.styleElement.sheet;
+    const inSync = !!sheet && sheet.cssRules.length === partition.styles.length;
+    partition.styles.splice(index, 1);
+    partition.keys?.splice(index, 1);
+    if (inSync && sheet) {
+      sheet.deleteRule(index);
+    } else {
+      partition.styleElement.textContent = partition.styles.length ? partition.styles.join("\n") + "\n" : "";
+    }
+    if (category) this.classToCategoryPartitionMap.delete(rule2);
+    else this.classToPartitionMap.delete(rule2);
+    return true;
+  }
+  /** Number of generated (non-root, non-preflight) rules currently held. */
+  get ruleCount() {
+    return this.classToPartitionMap.size + this.classToCategoryPartitionMap.size;
+  }
   /**
    * 특정 규칙이 어느 파티션에 있는지 찾기
    */
@@ -8860,10 +8949,14 @@ class ChangeDetector {
    */
   constructor(incrementalParser, BrowserRuntime2, getCategory = (cls) => parseClassName(cls).utility?.category) {
     this.observer = null;
+    this.gc = null;
     this.incrementalParser = incrementalParser;
     this.BrowserRuntime = BrowserRuntime2;
     this.getCategory = getCategory;
   }
+  setGc(gc) {
+    this.gc = gc;
+  }
   setParser(parser) {
     this.incrementalParser = parser;
   }
@@ -8890,9 +8983,19 @@ class ChangeDetector {
     if (this.observer) {
       this.observer.disconnect();
     }
+    this.gc?.setRoot(root);
     this.observer = new MutationObserver((mutations) => {
       const newClasses = /* @__PURE__ */ new Set();
+      const gc = this.gc;
       mutations.forEach((mutation) => {
+        if (gc) {
+          if (mutation.type === "attributes") {
+            gc.reconcile(mutation.target);
+          } else if (mutation.type === "childList") {
+            mutation.removedNodes.forEach((node) => gc.reconcileTree(node));
+            mutation.addedNodes.forEach((node) => gc.reconcileTree(node));
+          }
+        }
         if (mutation.type === "attributes" && mutation.attributeName === "class" && root.contains(mutation.target)) {
           const target = mutation.target;
           if (target.className) {
@@ -8923,6 +9026,7 @@ class ChangeDetector {
       } else {
         this.BrowserRuntime?.applyParseResults([]);
       }
+      gc?.afterBatch();
     });
     this.observer.observe(root, {
       attributes: true,
@@ -9041,6 +9145,115 @@ function collectLeadingClasses(rules, out = /* @__PURE__ */ new Set()) {
   }
   return out;
 }
+class ClassGc {
+  constructor(host, graceMs, maxRules, now = () => Date.now()) {
+    this.host = host;
+    this.graceMs = graceMs;
+    this.maxRules = maxRules;
+    this.now = now;
+    this.counts = /* @__PURE__ */ new Map();
+    this.counted = /* @__PURE__ */ new WeakMap();
+    this.candidates = /* @__PURE__ */ new Map();
+    this.timer = null;
+    this.root = null;
+  }
+  /** Start counting for a new root: count every element currently inside it. */
+  setRoot(root) {
+    this.counts.clear();
+    this.counted = /* @__PURE__ */ new WeakMap();
+    this.candidates.clear();
+    this.cancel();
+    this.root = root;
+    this.reconcileTree(root);
+  }
+  count(cls) {
+    return this.counts.get(cls) ?? 0;
+  }
+  /** Re-count `el` and (optionally) all its descendants from their current state. */
+  reconcileTree(node) {
+    if (node.nodeType !== 1) return;
+    const el = node;
+    this.reconcile(el);
+    el.querySelectorAll("[class]").forEach((child) => this.reconcile(child));
+  }
+  reconcile(el) {
+    const root = this.root;
+    const live = !!root && root.contains(el);
+    const next = live ? Array.from(new Set(normalizeClassNameList(el.getAttribute("class")))) : [];
+    const prev = this.counted.get(el);
+    if (!prev && next.length === 0) return;
+    const prevSet = new Set(prev ?? []);
+    const nextSet = new Set(next);
+    for (const cls of nextSet) {
+      if (prevSet.has(cls)) continue;
+      const c = (this.counts.get(cls) ?? 0) + 1;
+      this.counts.set(cls, c);
+      this.candidates.delete(cls);
+    }
+    for (const cls of prevSet) {
+      if (nextSet.has(cls)) continue;
+      const c = (this.counts.get(cls) ?? 0) - 1;
+      if (c > 0) {
+        this.counts.set(cls, c);
+      } else {
+        this.counts.delete(cls);
+        this.candidates.delete(cls);
+        this.candidates.set(cls, this.now());
+      }
+    }
+    if (next.length) this.counted.set(el, next);
+    else this.counted.delete(el);
+  }
+  /** Call after a mutation batch has been counted and its classes inserted. */
+  afterBatch() {
+    if (this.candidates.size === 0) return;
+    if (this.host.cachedCount() > this.maxRules) {
+      this.schedule(0);
+    } else {
+      this.schedule(this.graceMs);
+    }
+  }
+  schedule(delay) {
+    if (this.timer !== null) {
+      if (delay > 0) return;
+      clearTimeout(this.timer);
+    }
+    this.timer = setTimeout(() => {
+      this.timer = null;
+      this.sweep();
+    }, delay);
+  }
+  /** Reclaim candidates whose grace period elapsed (plus LRU overflow). Public for tests. */
+  sweep() {
+    const now = this.now();
+    const overflow = Math.max(0, this.host.cachedCount() - this.maxRules);
+    const doomed = [];
+    let evicted = 0;
+    for (const [cls, since] of this.candidates) {
+      const expired = now - since >= this.graceMs;
+      if (!expired && evicted >= overflow) continue;
+      this.candidates.delete(cls);
+      if (this.count(cls) > 0 || this.inDom(cls) || this.host.isPermanent(cls)) continue;
+      doomed.push(cls);
+      if (!expired) evicted++;
+    }
+    if (doomed.length) this.host.reclaim(doomed);
+    if (this.candidates.size) this.schedule(this.graceMs);
+  }
+  inDom(cls) {
+    const root = this.root;
+    if (!root) return false;
+    const doc = root.ownerDocument ?? document;
+    return root.classList.contains(cls) || doc.documentElement.classList.contains(cls) || doc.getElementsByClassName(cls).length > 0;
+  }
+  cancel() {
+    if (this.timer !== null) clearTimeout(this.timer);
+    this.timer = null;
+  }
+  stats() {
+    return { trackedClasses: this.counts.size, candidates: this.candidates.size };
+  }
+}
 const LAYER_ORDER = "@layer theme, base, components, utilities;";
 class BrowserRuntime {
   constructor(options = {}) {
@@ -9049,6 +9262,9 @@ class BrowserRuntime {
     this.isDestroyed = false;
     this.existing = null;
     this.existingSheetCount = -1;
+    this.pinned = /* @__PURE__ */ new Set();
+    this.gc = null;
+    this.reclaimedCount = 0;
     this.getCategory = (cls) => parseClassName(cls, this.context).utility?.category;
     const defaultConfig = {};
     this.options = {
@@ -9056,12 +9272,23 @@ class BrowserRuntime {
       styleId: options.styleId || "barocss-runtime",
       insertionPoint: options.insertionPoint || "head",
       maxRulesPerPartition: options.maxRulesPerPartition || 50,
-      skipExisting: options.skipExisting ?? false
+      skipExisting: options.skipExisting ?? false,
+      gc: options.gc ?? true,
+      gcGraceMs: options.gcGraceMs ?? 3e3,
+      maxRules: options.maxRules ?? Infinity
     };
     this.context = createContext(this.options.config);
     this.incrementalParser = new IncrementalParser(this.context);
     this.changeDetector = new ChangeDetector(this.incrementalParser, this, this.getCategory);
     this.stylePartitionManager = new StylePartitionManager(this.getInsertionPoint(), this.options.maxRulesPerPartition, `${this.options.styleId}-partition`, this.getCategory);
+    if (this.options.gc) {
+      this.gc = new ClassGc({
+        reclaim: (classes) => this.reclaim(classes),
+        isPermanent: (cls) => this.isPermanent(cls),
+        cachedCount: () => this.cache.size
+      }, this.options.gcGraceMs, this.options.maxRules);
+      this.changeDetector.setGc(this.gc);
+    }
     this.init();
   }
   // Debugging and logging helpers
@@ -9113,7 +9340,8 @@ ${preflightCSS}
    */
   addClass(classes) {
     if (this.isDestroyed) return;
-    const classList = this.normalizeClasses(classes);
+    const classList = this.normalizeClasses(classes).filter(Boolean);
+    classList.forEach((cls) => this.pinned.add(cls));
     this.processClasses(classList);
   }
   /**
@@ -9174,9 +9402,40 @@ ${preflightCSS}
       rootCssCount: rootCssRules.length
     });
   }
+  /** #269: a class that must never be reclaimed. */
+  isPermanent(cls) {
+    if (this.pinned.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
+   * (they are shared and harmless); a rule text another cached class still emits is kept.
+   */
+  reclaim(classes) {
+    if (this.isDestroyed) return;
+    const victims = classes.filter((cls) => this.cache.has(cls));
+    if (victims.length === 0) return;
+    const results = victims.map((cls) => this.cache.get(cls));
+    victims.forEach((cls) => {
+      this.cache.delete(cls);
+      this.incrementalParser.unmarkProcessed(cls);
+    });
+    const stillUsed = /* @__PURE__ */ new Set();
+    for (const result of this.cache.values()) result.cssList.forEach((css) => stillUsed.add(css));
+    for (const result of results) {
+      const category = this.getCategory(result.cls);
+      for (const css of result.cssList) {
+        if (!stillUsed.has(css)) this.stylePartitionManager.removeRule(css, category);
+      }
+    }
+    this.reclaimedCount += victims.length;
+  }
   /** Class names defined by the page's own stylesheets (BaroCSS's sheets and cross-origin sheets excluded). */
   getExistingClasses() {
+    const own = new Set(Array.from(document.querySelectorAll("style[data-barocss]"), (s) => s.sheet));
     const sheets = Array.from(document.styleSheets).filter((sheet) => {
+      if (own.has(sheet)) return false;
       const owner = sheet.ownerNode;
       return !(owner && typeof owner.hasAttribute === "function" && (owner.hasAttribute("data-barocss") || (owner.id || "").startsWith(this.options.styleId)));
     });
@@ -9228,7 +9487,10 @@ ${preflightCSS}
     return {
       runtime: {
         cachedClasses: this.cache.size,
-        rootCacheSize: this.rootCache.size
+        rootCacheSize: this.rootCache.size,
+        ruleCount: this.stylePartitionManager.ruleCount,
+        reclaimedClasses: this.reclaimedCount,
+        gc: this.gc?.stats() ?? null
       },
       ast: incremental.cacheStats.ast,
       incremental
@@ -9282,6 +9544,7 @@ ${preflightCSS}
   destroy() {
     if (this.isDestroyed) return;
     this.changeDetector.disconnect();
+    this.gc?.cancel();
     this.stylePartitionManager.cleanup();
     this.cache.clear();
     this.rootCache.clear();