@barocss/browser 0.0.3 → 0.5.0

package/dist/index.d.ts

@@ -1,5 +1,330 @@
-export * from './browser-runtime';
-export * from './change-detector';
-export * from './style-partition-manager';
-export * from './utils';
-export * from './baro-boot';
+import { Config } from '@barocss/kit';
+import { GenerateCssRulesResult } from '@barocss/kit';
+import { IncrementalParser } from '@barocss/kit';
+
+export declare function baroBoot({ loadingClassName, ...options }?: BaroBootOptions): void;
+
+declare type BaroBootOptions = BrowserRuntimeOptions & {
+    loadingClassName?: string;
+};
+
+export declare const baroStart: typeof baroBoot;
+
+export declare class BrowserRuntime {
+    private cache;
+    private rootCache;
+    private context;
+    private options;
+    private isDestroyed;
+    private existing;
+    private existingSheetCount;
+    private incrementalParser;
+    private changeDetector;
+    private stylePartitionManager;
+    private getCategory;
+    constructor(options?: BrowserRuntimeOptions);
+    /**
+     * Add debug logs (by level)
+     */
+    private debugLog;
+    private init;
+    private injectPreflightCSS;
+    private ensureCssVars;
+    private getInsertionPoint;
+    /**
+     * Dynamically add one or more class names and generate/insert CSS
+     */
+    addClass(classes: string | string[]): void;
+    /**
+     * Process classes
+     */
+    private processClasses;
+    /**
+     * Process classes using incremental parsing
+     */
+    private processClassesIncremental;
+    /**
+     * Public method to apply parser results, update internal caches, and inject CSS
+     */
+    applyParseResults(results: Array<GenerateCssRulesResult>, _opts?: {
+        isBrowser?: boolean;
+    }): void;
+    /** Class names defined by the page's own stylesheets (BaroCSS's sheets and cross-origin sheets excluded). */
+    getExistingClasses(): Set<string>;
+    /**
+     * MutationObserver instance method to automatically call addClass when class attributes change in DOM
+     */
+    observe(root?: HTMLElement, options?: {
+        scan?: boolean;
+        onReady?: () => void;
+    }): MutationObserver;
+    private normalizeClasses;
+    has(cls: string): boolean;
+    getCss(cls: string): string | undefined;
+    getAllCss(): string;
+    getClasses(): string[];
+    /**
+     * Get comprehensive cache statistics
+     */
+    getCacheStats(): {
+        runtime: {
+            cachedClasses: number;
+            rootCacheSize: number;
+        };
+        ast: {
+            size: number;
+            maxSize: number;
+            hitRate: number;
+        };
+        incremental: {
+            processedClasses: number;
+            pendingClasses: number;
+            cacheStats: {
+                ast: {
+                    size: number;
+                    maxSize: number;
+                    hitRate: number;
+                };
+                css: {};
+            };
+        };
+    };
+    /**
+     * Clear all caches (useful for debugging or memory management)
+     */
+    clearCaches(): void;
+    reset(): void;
+    updateConfig(newConfig: Config): void;
+    removeClass(classes: string | string[]): void;
+    destroy(): void;
+    getStats(): {
+        cachedClasses: number;
+        styleElementId: string;
+        isDestroyed: boolean;
+        config: Config;
+        cacheStats: {
+            runtime: {
+                cachedClasses: number;
+                rootCacheSize: number;
+            };
+            ast: {
+                size: number;
+                maxSize: number;
+                hitRate: number;
+            };
+            incremental: {
+                processedClasses: number;
+                pendingClasses: number;
+                cacheStats: {
+                    ast: {
+                        size: number;
+                        maxSize: number;
+                        hitRate: number;
+                    };
+                    css: {};
+                };
+            };
+        };
+    };
+}
+
+export declare interface BrowserRuntimeOptions {
+    config?: Config;
+    styleId?: string;
+    insertionPoint?: 'head' | 'body' | HTMLElement;
+    maxRulesPerPartition?: number;
+    /**
+     * #210: skip classes the page's existing (non-BaroCSS, same-origin) stylesheets already define,
+     * so a built app plus the runtime injects only what the build is missing. Opt-in. A class counts
+     * as covered only when a rule's selector starts with it (e.g. `.p-4`, `.md\:p-4` inside @media,
+     * `.hover\:x:hover`), so a class seen only as a descendant (`.group:hover .x`) is not skipped.
+     * The index is rebuilt when `document.styleSheets.length` changes. A page class that leads a selector
+     * with the same name is treated as covered, and rules added later to an already-indexed sheet aren't seen.
+     */
+    skipExisting?: boolean;
+}
+
+/**
+ * Change detection system for DOM mutations
+ *
+ * ⚠️ BROWSER-ONLY: This class is designed for browser environments only.
+ * It uses MutationObserver and DOM APIs that are not available in Node.js.
+ *
+ * This class monitors DOM changes and automatically processes new CSS classes
+ * that are added to elements. It uses MutationObserver to detect:
+ * - Class attribute changes on existing elements
+ * - New elements being added to the DOM
+ * - Changes in child elements
+ *
+ * For server-side usage, use IncrementalParser directly with processClassesSync()
+ * or processClasses() methods.
+ */
+export declare class ChangeDetector {
+    /** MutationObserver instance for DOM change detection */
+    private observer;
+    /** Reference to IncrementalParser for class processing */
+    private incrementalParser;
+    /** Reference to BrowserRuntime for CSS injection (optional) */
+    private BrowserRuntime?;
+    private getCategory;
+    /**
+     * Create a new ChangeDetector instance
+     *
+     * @param incrementalParser - IncrementalParser instance for class processing
+     * @param BrowserRuntime - Optional BrowserRuntime instance for CSS injection
+     */
+    constructor(incrementalParser: IncrementalParser, BrowserRuntime?: BrowserRuntime, getCategory?: (cls: string) => string | undefined);
+    setParser(parser: IncrementalParser): void;
+    /**
+     * Starts observing DOM changes for new CSS classes
+     *
+     * This method sets up a MutationObserver that monitors:
+     * - Attribute changes (specifically class attribute modifications)
+     * - Child list changes (new elements being added)
+     * - Subtree changes (changes in descendant elements)
+     *
+     * The observer automatically processes any new classes it discovers
+     * by adding them to the IncrementalParser's pending queue.
+     *
+     * @param root - The root element to observe (defaults to document.body)
+     * @param options - Configuration options including initial scan and onReady callback
+     * @returns The MutationObserver instance for external control
+     */
+    observe(root?: HTMLElement, options?: {
+        scan?: boolean;
+        onReady?: () => void;
+    }): MutationObserver;
+    /**
+     * Scan existing classes in the DOM and process them
+     */
+    private scanExistingClasses;
+    /**
+     * Processes an individual element and extracts new classes
+     *
+     * This method is called for each element discovered during DOM mutations.
+     * It:
+     * - Extracts all class names from the element's className
+     * - Filters out already processed classes
+     * - Adds new classes to the collection for batch processing
+     *
+     * @param element - The HTML element to process
+     * @param newClasses - Set to collect newly discovered class names
+     */
+    private processElement;
+    /**
+     * Stops observing DOM changes and cleans up resources
+     *
+     * This method disconnects the MutationObserver and clears the
+     * observer reference to prevent memory leaks and allow the
+     * ChangeDetector to be properly garbage collected.
+     */
+    disconnect(): void;
+}
+
+/** Collect literal className tokens from a json-render Spec's flat elements map. */
+export declare function collectJsonRenderClassNames(spec: unknown): string[];
+
+/**
+ * Returns the shared runtime, creating it on first use. If a live runtime
+ * already exists and `options.config` is a different config object, it is
+ * applied via `updateConfig` (which replaces the whole config), so an early
+ * `getRuntime()` never makes a later `baroStart({ config })` lose its config.
+ */
+export declare function getRuntime(options?: BrowserRuntimeOptions): BrowserRuntime;
+
+/** Tailwind 4 layer order, declared by BaroCSS's first <style> in <head>. */
+export declare const LAYER_ORDER = "@layer theme, base, components, utilities;";
+
+export declare function normalizeClassName(className: any): string;
+
+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>;
+};
+
+export declare interface StylePartition {
+    id: string;
+    styles: string[];
+    styleElement: HTMLStyleElement;
+    /** Sort keys parallel to `styles` / the sheet's cssRules (#254). */
+    keys?: RuleKey[];
+}
+
+export declare class StylePartitionManager {
+    /**
+     * Insert `rule` at its Tailwind variant position within `partition` (#254):
+     * one insertRule at a binary-searched index, no sheet rewrite.
+     */
+    private insertSorted;
+    private partitions;
+    private categoryPartitions;
+    private partitionCounter;
+    private maxRulesPerPartition;
+    private insertionPoint;
+    private classToPartitionMap;
+    private classToCategoryPartitionMap;
+    private styleIdPrefix;
+    private getCategory;
+    constructor(insertionPoint: HTMLElement, maxRulesPerPartition?: number, styleIdPrefix?: string, getCategory?: (cls: string) => string | undefined);
+    private initializeDefaultPartition;
+    private createNewCategoryPartition;
+    private createNewPartition;
+    hasRule(rule: string): boolean;
+    hasCategoryRule(rule: string, category: string): boolean;
+    setRuleCache(rule: string, partitionIndex: number): void;
+    setCategoryRuleCache(rule: string, category: string): void;
+    get currentPartition(): StylePartition;
+    getCategoryPartition(category: string): StylePartition | undefined;
+    hasDetachedPartitions(): boolean;
+    /**
+     * Escape CSS rule text
+     * - Properly escape special characters
+     * - Prevent CSS syntax errors
+     */
+    private escapeCssRule;
+    addRule(rule: string): boolean;
+    addCategoryRule(rule: string, category: string): boolean;
+    addRootRules(rules: string[]): {
+        success: number;
+        failed: number;
+    };
+    addRules(rules: GenerateCssRulesResult[]): {
+        success: number;
+        failed: number;
+    };
+    /**
+     * 특정 규칙이 어느 파티션에 있는지 찾기
+     */
+    findRulePartition(rule: string): StylePartition | null;
+    updateRuleContent(category: string, ruleContent: string, atDocumentStart?: boolean): void;
+    /**
+     * 모든 파티션 정리
+     */
+    cleanup(): void;
+}
+
+export { }