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

@barocss/browser 0.5.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 +25 -1
package/dist/cdn/barocss.js +455 -47
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 +124 -19
package/dist/index.es.js +298 -148
package/dist/index.umd.js +7 -5
package/package.json +2 -2

package/dist/index.d.ts CHANGED Viewed

@@ -1,6 +1,7 @@
 import { Config } from '@barocss/kit';
 import { GenerateCssRulesResult } from '@barocss/kit';
 import { IncrementalParser } from '@barocss/kit';
+import { RuleKey } from '@barocss/kit';
 export declare function baroBoot({ loadingClassName, ...options }?: BaroBootOptions): void;
@@ -17,7 +18,17 @@ export declare class BrowserRuntime {
     private options;
     private isDestroyed;
     private existing;
+    /** #274: @keyframes names the page's own sheets define (filled with `existing`). */
+    private existingKeyframes;
     private existingSheetCount;
+    /** #269: classes requested explicitly through addClass(); never reclaimed. */
+    private pinned;
+    private gc;
+    private reclaimedCount;
+    /** #268: class rules adopted from `<style data-barocss-ssr>`, in sheet order, and the classes they lead. */
+    private ssrRules;
+    private ssrClasses;
+    private observedOnce;
     private incrementalParser;
     private changeDetector;
     private stylePartitionManager;
@@ -28,6 +39,15 @@ export declare class BrowserRuntime {
      */
     private debugLog;
     private init;
+    /**
+     * #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.
+     */
+    private adoptSsrSheets;
+    private insertSsrRules;
     private injectPreflightCSS;
     private ensureCssVars;
     private getInsertionPoint;
@@ -49,6 +69,13 @@ export declare class BrowserRuntime {
     applyParseResults(results: Array<GenerateCssRulesResult>, _opts?: {
         isBrowser?: boolean;
     }): void;
+    /** #269: a class that must never be reclaimed. */
+    private isPermanent;
+    /**
+     * #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.
+     */
+    private reclaim;
     /** Class names defined by the page's own stylesheets (BaroCSS's sheets and cross-origin sheets excluded). */
     getExistingClasses(): Set<string>;
     /**
@@ -70,6 +97,12 @@ export declare class BrowserRuntime {
         runtime: {
             cachedClasses: number;
             rootCacheSize: number;
+            ruleCount: number;
+            reclaimedClasses: number;
+            gc: {
+                trackedClasses: number;
+                candidates: number;
+            } | null;
         };
         ast: {
             size: number;
@@ -106,6 +139,12 @@ export declare class BrowserRuntime {
             runtime: {
                 cachedClasses: number;
                 rootCacheSize: number;
+                ruleCount: number;
+                reclaimedClasses: number;
+                gc: {
+                    trackedClasses: number;
+                    candidates: number;
+                } | null;
             };
             ast: {
                 size: number;
@@ -142,6 +181,21 @@ export declare interface BrowserRuntimeOptions {
      * with the same name is treated as covered, and rules added later to an already-indexed sheet aren't seen.
      */
     skipExisting?: boolean;
+    /**
+     * #269: reclaim the rules of classes that no element inside the observed root carries any more.
+     * On by default; it only acts on classes seen through `observe()`. A class is deleted only after
+     * its refcount has stayed 0 for `gcGraceMs` and a live-DOM re-check finds no element with it.
+     * Never reclaimed: classes passed to `addClass()`, classes any pre-existing (non-BaroCSS) sheet
+     * defines (build output, server sheet), root/@property/preflight rules. `false` disables it.
+     */
+    gc?: boolean;
+    /** #269: how long a class must stay unused before its rules are deleted (default 3000 ms). */
+    gcGraceMs?: number;
+    /**
+     * #269: soft cap on cached classes. When exceeded, unused (refcount 0) classes are evicted
+     * oldest-first without waiting for the grace period; classes in use are never evicted. Default: no cap.
+     */
+    maxRules?: number;
 }
 /**
@@ -174,6 +228,9 @@ export declare class ChangeDetector {
      * @param BrowserRuntime - Optional BrowserRuntime instance for CSS injection
      */
     constructor(incrementalParser: IncrementalParser, BrowserRuntime?: BrowserRuntime, getCategory?: (cls: string) => string | undefined);
+    /** #269: refcount/GC tracker, when the runtime has GC enabled. */
+    private gc;
+    setGc(gc: ClassGc | null): void;
     setParser(parser: IncrementalParser): void;
     /**
      * Starts observing DOM changes for new CSS classes
@@ -221,6 +278,61 @@ export declare class ChangeDetector {
     disconnect(): void;
 }
+declare class ClassGc {
+    private host;
+    private graceMs;
+    private maxRules;
+    private now;
+    private counts;
+    private counted;
+    /** class -> time its count reached 0 (insertion order = oldest first). */
+    private candidates;
+    private timer;
+    private root;
+    constructor(host: ClassGcHost, graceMs: number, maxRules: number, now?: () => number);
+    /** Start counting for a new root: count every element currently inside it. */
+    setRoot(root: Element): void;
+    count(cls: string): number;
+    /** Re-count `el` and (optionally) all its descendants from their current state. */
+    reconcileTree(node: Node): void;
+    reconcile(el: Element): void;
+    /** Call after a mutation batch has been counted and its classes inserted. */
+    afterBatch(): void;
+    private schedule;
+    /** Reclaim candidates whose grace period elapsed (plus LRU overflow). Public for tests. */
+    sweep(): void;
+    private inDom;
+    cancel(): void;
+    stats(): {
+        trackedClasses: number;
+        candidates: number;
+    };
+}
+/**
+ * #269: per-class refcount over the observed root, plus a delayed sweep that
+ * reclaims classes no live element carries any more.
+ *
+ * Counting is reconciliation, not delta arithmetic: for every element a
+ * mutation batch touches (attribute target, added subtree, removed subtree) we
+ * compare the classes we last counted for it with what it carries *now*
+ * (nothing if it is no longer inside the root). That makes the count
+ * independent of record order, so remove-then-re-add in one batch, moves
+ * between parents and edits made while detached all settle to the true state.
+ * An element we miss can only leak a count (rule kept), never drop one.
+ *
+ * Before a class is reclaimed the sweep re-checks the live DOM
+ * (`getElementsByClassName`), so even a miscount cannot unstyle a live element.
+ */
+declare interface ClassGcHost {
+    /** Delete the rules of these classes. */
+    reclaim(classes: string[]): void;
+    /** Whether a class must never be reclaimed (pinned, found in a pre-existing sheet, ...). */
+    isPermanent(cls: string): boolean;
+    /** Number of generated rules/classes currently cached (for the LRU cap). */
+    cachedCount(): number;
+}
 /** Collect literal className tokens from a json-render Spec's flat elements map. */
 export declare function collectJsonRenderClassNames(spec: unknown): string[];
@@ -242,30 +354,14 @@ export declare function normalizeClassNameList(className: any): string[];
 /** Submit literal classes synchronously before UI mount; the caller validates class support. */
 export declare function preloadJsonRenderClasses(spec: unknown, runtime: Pick<BrowserRuntime, 'addClass'>): void;
-/**
- * Tailwind-compatible cascade order for runtime-inserted rules (#254).
- *
- * 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.
- */
-declare type RuleKey = number[];
 export declare const shadcnTheme: {
     colors: Record<string, string>;
     borderRadius: Record<string, string>;
 };
+/** #268: marks a server-rendered sheet (`@barocss/server` `ssrStyleTag()`); the runtime adopts its class rules. */
+export declare const SSR_STYLE_SELECTOR = "style[data-barocss-ssr]";
 export declare interface StylePartition {
     id: string;
     styles: string[];
@@ -316,6 +412,15 @@ export declare class StylePartitionManager {
         success: number;
         failed: number;
     };
+    /**
+     * 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(rule: string, category?: string): boolean;
+    /** Number of generated (non-root, non-preflight) rules currently held. */
+    get ruleCount(): number;
     /**
      * 특정 규칙이 어느 파티션에 있는지 찾기
      */