@barocss/kit 0.5.0 → 0.6.0

package/dist/index.d.ts

@@ -181,6 +181,8 @@ export declare type AstNode = {
 
  export declare function comment(text: string, source?: string): AstNode;
 
+ export declare function compareKeys(a: RuleKey, b: RuleKey): number;
+
  export declare interface Config {
      prefix?: string;
      cssVarPrefix?: string;
@@ -268,20 +270,6 @@ export declare type AstNode = {
 
  export declare function functionalModifier(match: ModifierRegistration['match'], modifySelector: ModifierRegistration['modifySelector'], wrap?: ModifierRegistration['wrap'], options?: Partial<ModifierRegistration>, ctx?: Context): void;
 
- /**
-  * functionalUtility: A helper that registers dynamic utilities (theme, arbitrary, custom, negative, fraction, etc.) directly
-  *
-  * Example:
-  *   functionalUtility({
-  *     name: 'z',
-  *     supportsNegative: true,
-  *     themeKeys: ['--z-index'],
-  *     handleBareValue: ({ value }) => isPositiveInteger(value) ? value : null,
-  *     handle: (value) => [decl('z-index', value)],
-  *     description: 'z-index utility',
-  *     category: 'layout',
-  *   });
-  */
  export declare function functionalUtility(opts: FunctionalUtilityOptions, ctx?: Context): void;
 
  export declare type FunctionalUtilityExtra = {
@@ -420,6 +408,12 @@ export declare type AstNode = {
       * handleNegativeBareValue: ({ value }) => isPositiveInteger(value) ? value : null,
       * ```
       */
+     /**
+      * #261: the utility uses the spacing scale, so a named `theme.spacing` key (`p-gutter`) resolves to
+      * `var(--spacing-<key>)` (negative: `calc(var(--spacing-<key>) * -1)`), as in Tailwind 4. Only tried
+      * after the bare-value handler rejects the value, so built-in keywords keep precedence.
+      */
+     spacingKeys?: boolean;
      handleNegativeBareValue?: (args: {
          value: string;
          ctx: Context;
@@ -552,6 +546,13 @@ export declare type AstNode = {
 
    export declare function getUtility(ctx?: Context): UtilityRegistration[];
 
+   /**
+    * #273: true when an emitted selector or at-rule prelude contains a comment opener or closer outside a CSS escape.
+    * Backslash-escape pairs are skipped, so an escaped `\/` or `\*` from a class name never counts. Used by the
+    * serializer on the final, composed string, where adjacent pieces that were each safe alone can join into one.
+    */
+   export declare function hasCommentDelimiter(text: string): boolean;
+
    /**
     * #224: true when a utility value (or a whole utility token) cannot change the structure of the declaration block it
     * is pasted into. Rejects, outside quotes: `{`, `}`, `;`, unbalanced or mismatched ()/[], and a quote left open.
@@ -771,6 +772,13 @@ export declare type AstNode = {
         * @param cls - The CSS class name to mark as processed
         */
        markProcessed(cls: string): void;
+       /**
+        * 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: string): void;
        /**
         * Process classes synchronously and update BrowserRuntime cache
         * This method is used by ChangeDetector for scan operations
@@ -973,6 +981,27 @@ export declare type AstNode = {
 
     export declare function rule(selector: string, nodes: AstNode[], source?: string): AstNode;
 
+    /**
+     * Tailwind-compatible cascade order for runtime-inserted rules (#254); shared by @barocss/server (#267).
+     *
+     * The runtime discovers classes in DOM order, so without sorting `lg:px-8`
+     * seen before `sm:px-6` would land earlier and lose at >= 1024px. Each rule
+     * gets a sort key derived from its leading `@media` / `@container` preludes:
+     *
+     *   0  base, state media (hover), motion/contrast, unknown
+     *   1  max-* breakpoints        (larger width first)
+     *   2  min-* breakpoints        (smaller width first)
+     *   3  @max-* container queries (larger width first)
+     *   4  @min-* container queries (smaller width first)
+     *   5  orientation, dark (prefers-color-scheme), print, forced-colors
+     *
+     * Nested at-rules (e.g. `sm:dark:`) contribute one key pair per level, so
+     * `sm:` < `sm:dark:` < `md:`. Equal keys keep discovery order.
+     */
+    export declare type RuleKey = number[];
+
+    export declare function ruleSortKey(rule: string): RuleKey;
+
     /** Internal hook for caches owned by contexts. */
     export declare function setContextCacheReset(reset: () => void): void;
 
@@ -1087,6 +1116,9 @@ export declare type AstNode = {
      */
     export declare function tokenize(className: string): Token[];
 
+    /** Index after the last key <= `key` (stable upper bound) in sorted `keys`. */
+    export declare function upperBound(keys: RuleKey[], key: RuleKey): number;
+
     /**
      * Utility cache management
      */

package/dist/index.js

@@ -337,6 +337,11 @@ function staticUtility(name, decls, opts, ctx) {
     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;
+  const ref = `var(--spacing-${key})`;
+  return negative ? `calc(${ref} * -1)` : ref;
+}
 function functionalUtility(opts, ctx) {
   registerUtility({
     name: opts.name,
@@ -405,14 +410,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 [];
       }
@@ -623,6 +631,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);
@@ -770,6 +790,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 = "") {
@@ -833,6 +854,7 @@ function astToCss(ast, baseSelector, opts, _indent = "") {
             }).join(", ");
           }
         }
+        if (!isSafePrelude(selector)) return "";
         if (minify) {
           const css = `${indent}${selector}{${astToCss(
             node.nodes,
@@ -857,6 +879,7 @@ ${astToCss(
         }
       }
       case "style-rule": {
+        if (!isSafePrelude(node.selector)) return "";
         if (minify) {
           const css = `${indent}${node.selector} {${astToCss(
             node.nodes,
@@ -881,6 +904,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,
@@ -934,7 +958,7 @@ function rootToCss(nodes, opts) {
       if (isSafeDecl(node.prop, node.value)) {
         list.push(minify ? `${node.prop}:${node.value};` : `${node.prop}: ${node.value};`);
       }
-    } else if (node.type === "at-rule") {
+    } else if (node.type === "at-rule" && isSafePrelude(node.name) && isSafePrelude(node.params)) {
       if (minify) {
         const body = node.nodes.filter((child) => child.type === "decl" && isSafeDecl(child.prop, child.value)).map((child) => child.type === "decl" ? `${child.prop}:${child.value};` : "").join("");
         list.push(`@${node.name} ${node.params}{${body}}`);
@@ -1165,8 +1189,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"]);
@@ -1841,6 +1870,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
@@ -3387,6 +3425,7 @@ staticUtility("snap-proximity", [["--baro-scroll-snap-strictness", "proximity"]]
 ].forEach(([name, prop]) => {
   functionalUtility({
     name: `scroll-${name}`,
+    spacingKeys: true,
     prop,
     supportsArbitrary: true,
     supportsCustomProperty: true,
@@ -3414,6 +3453,7 @@ staticUtility("snap-proximity", [["--baro-scroll-snap-strictness", "proximity"]]
 ].forEach(([name, prop]) => {
   functionalUtility({
     name: `scroll-${name}`,
+    spacingKeys: true,
     prop,
     supportsArbitrary: true,
     supportsCustomProperty: true,
@@ -4947,6 +4987,7 @@ staticUtility("sticky", [["position", "sticky"]], { category: "layout" });
   staticUtility(`-${name}-px`, [[prop, "-1px"]], { category: "layout" });
   functionalUtility({
     name,
+    spacingKeys: true,
     prop,
     supportsNegative: true,
     supportsFraction: true,
@@ -4977,6 +5018,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]
@@ -4993,6 +5035,7 @@ functionalUtility({
 });
 functionalUtility({
   name: "gap-y",
+  spacingKeys: true,
   prop: "row-gap",
   supportsArbitrary: true,
   // gap-y-[10vw]
@@ -5009,6 +5052,7 @@ functionalUtility({
 });
 functionalUtility({
   name: "gap",
+  spacingKeys: true,
   prop: "gap",
   supportsArbitrary: true,
   // gap-[10vw]
@@ -5526,6 +5570,7 @@ functionalUtility({
 ].forEach(([name, prop]) => {
   staticUtility(`${name}-px`, [[prop, "1px"]], { category: "spacing" });
   functionalUtility({
+    spacingKeys: true,
     name,
     prop,
     supportsArbitrary: true,
@@ -5550,6 +5595,7 @@ functionalUtility({
   staticUtility(`${name}-px`, [[prop, "1px"]], { category: "spacing" });
   staticUtility(`-${name}-px`, [[prop, "-1px"]], { category: "spacing" });
   functionalUtility({
+    spacingKeys: true,
     name,
     prop,
     supportsNegative: true,
@@ -5580,6 +5626,7 @@ const SPACE_SELECTOR = ":where(& > :not(:last-child))";
     () => rule(SPACE_SELECTOR, [decl(rev, "1")])
   ], { category: "spacing" });
   functionalUtility({
+    spacingKeys: true,
     name,
     supportsNegative: true,
     supportsArbitrary: true,
@@ -5629,6 +5676,7 @@ const SPACE_SELECTOR = ":where(& > :not(:last-child))";
   staticUtility(name, [["width", value]]);
 });
 functionalUtility({
+  spacingKeys: true,
   name: "w",
   prop: "width",
   supportsArbitrary: true,
@@ -5661,6 +5709,7 @@ functionalUtility({
   staticUtility(name, [["width", w], ["height", h]]);
 });
 functionalUtility({
+  spacingKeys: true,
   name: "size",
   supportsArbitrary: true,
   supportsCustomProperty: true,
@@ -5700,6 +5749,7 @@ functionalUtility({
   staticUtility(name, [["height", value]]);
 });
 functionalUtility({
+  spacingKeys: true,
   name: "h",
   prop: "height",
   supportsArbitrary: true,
@@ -5730,6 +5780,7 @@ functionalUtility({
   staticUtility(name, [["min-height", value]], { category: "sizing" });
 });
 functionalUtility({
+  spacingKeys: true,
   name: "min-h",
   prop: "min-height",
   supportsArbitrary: true,
@@ -5760,6 +5811,7 @@ functionalUtility({
   staticUtility(name, [["max-height", value]], { category: "sizing" });
 });
 functionalUtility({
+  spacingKeys: true,
   name: "max-h",
   prop: "max-height",
   supportsArbitrary: true,
@@ -5806,6 +5858,7 @@ functionalUtility({
   staticUtility(name, [["min-width", value]], { category: "sizing" });
 });
 functionalUtility({
+  spacingKeys: true,
   name: "min-w",
   prop: "min-width",
   supportsArbitrary: true,
@@ -5841,6 +5894,7 @@ functionalUtility({
   staticUtility(name, [["max-width", value]], { category: "sizing" });
 });
 functionalUtility({
+  spacingKeys: true,
   name: "max-w",
   prop: "max-width",
   supportsArbitrary: true,
@@ -8264,6 +8318,51 @@ functionalModifier(
   },
   void 0
 );
+const LEADING_AT = /^\s*@(media|container)\s+([^{]*)\{/;
+const LATE_MEDIA = /prefers-color-scheme|\bprint\b|forced-colors|orientation/;
+const MIN_W = /(?:min-width\s*:\s*|width\s*>=?\s*)([\d.]+)(px|rem|em)?/;
+const MAX_W = /(?:max-width\s*:\s*|width\s*<=?\s*)([\d.]+)(px|rem|em)?/;
+function toPx(n, unit) {
+  const v = parseFloat(n);
+  return unit === "rem" || unit === "em" ? v * 16 : v;
+}
+function preludeKey(kind, prelude) {
+  const container = kind === "container";
+  const min = MIN_W.exec(prelude);
+  if (min) return [container ? 4 : 2, toPx(min[1], min[2])];
+  const max = MAX_W.exec(prelude);
+  if (max) return [container ? 3 : 1, -toPx(max[1], max[2])];
+  if (!container && LATE_MEDIA.test(prelude)) return [5, 0];
+  return [0, 0];
+}
+function ruleSortKey(rule2) {
+  const key = [];
+  let rest = rule2;
+  let m;
+  while (m = LEADING_AT.exec(rest)) {
+    const [g, v] = preludeKey(m[1], m[2]);
+    key.push(g, v);
+    rest = rest.slice(m[0].length);
+  }
+  return key;
+}
+function compareKeys(a, b) {
+  const n = Math.min(a.length, b.length);
+  for (let i = 0; i < n; i++) {
+    if (a[i] !== b[i]) return a[i] - b[i];
+  }
+  return a.length - b.length;
+}
+function upperBound(keys, key) {
+  let lo = 0;
+  let hi = keys.length;
+  while (lo < hi) {
+    const mid = lo + hi >> 1;
+    if (compareKeys(keys[mid], key) <= 0) lo = mid + 1;
+    else hi = mid;
+  }
+  return lo;
+}
 export {
   AstCache,
   IncrementalParser,
@@ -8279,6 +8378,7 @@ export {
   clearAstCache,
   collectDeclPaths,
   comment,
+  compareKeys,
   configGetter,
   createContext,
   decl,
@@ -8296,6 +8396,7 @@ export {
   getModifier,
   getPreflightCSS,
   getUtility,
+  hasCommentDelimiter,
   hasCommentToken,
   hasPreset,
   isDebug,
@@ -8317,6 +8418,7 @@ export {
   resolveTheme,
   rootToCss,
   rule,
+  ruleSortKey,
   setContextCacheReset,
   setDebug,
   staticModifier,
@@ -8325,6 +8427,7 @@ export {
   themeGetter,
   themeToCssVars,
   tokenize,
+  upperBound,
   utilityCache
 };
 //# sourceMappingURL=index.js.map