@barocss/kit 0.0.2

package/dist/index.d.ts

@@ -0,0 +1,1012 @@
+/**
+ * AST cache management
+ */
+export declare class AstCache {
+    private cache;
+    private maxSize;
+    set(key: string, ast: AstNode[]): void;
+    get(key: string): AstNode[] | undefined;
+    has(key: string): boolean;
+    clear(): void;
+    getStats(): {
+        size: number;
+        maxSize: number;
+        hitRate: number;
+    };
+}
+
+export declare const astCache: AstCache;
+
+export declare type AstNode = {
+    type: "wrap";
+    items: AstNode[];
+    source?: string;
+} | {
+    type: "decl";
+    prop: string;
+    value: string | [string, string][];
+    source?: string;
+} | {
+    type: "at-rule";
+    name: string;
+    params: string;
+    nodes: AstNode[];
+    source?: string;
+} | {
+    type: "style-rule";
+    selector: string;
+    nodes: AstNode[];
+    source?: string;
+} | {
+    type: "rule";
+    selector: string;
+    nodes: AstNode[];
+    source?: string;
+} | {
+    type: "at-root";
+    nodes: AstNode[];
+    source?: string;
+} | {
+    type: "comment";
+    text: string;
+    source?: string;
+} | {
+    type: "raw";
+    value: string;
+    source?: string;
+};
+
+/**
+ * Converts AST nodes to CSS string
+ * @param ast { AstNode[] } - Array of AST nodes to convert
+ * @param baseSelector { string } - Base selector for nested rules (e.g., ".parent" for ".parent .child")
+ * @param opts { minify?: boolean } - Options for CSS generation
+     * @param _indent { string } - Current indentation level for pretty formatting
+     */
+ export declare function astToCss(ast: AstNode[], baseSelector?: string, opts?: {
+     minify?: boolean;
+     important?: boolean;
+ }, _indent?: string): string;
+
+ export declare function atRoot(nodes: AstNode[], source?: string): AstNode;
+
+ export declare function atRule(name: string, params: string, nodes: AstNode[], source?: string): AstNode;
+
+ /**
+  * Clear all caches (for context changes or testing)
+  */
+ export declare function clearAllCaches(): void;
+
+ /**
+  * Clear all AST caches (mainly for testing)
+  */
+ export declare function clearAstCache(): void;
+
+ /**
+  * collectDeclPaths
+  * Collects all paths from AST tree to decl(leaf) (including variant chains).
+  * - Input: AST node array
+  * - Output: decl-to-root path(variant chain) array
+  * - Usage: Used for path extraction for AST optimization/merging in optimizeAst, declPathToAst, etc.
+  *
+  * @param nodes AstNode[] - AST tree
+  * @param path PathNode[] - Recursive use (initial value omitted)
+  * @returns DeclPath[] - Array of paths to decl (variant chains)
+  */
+ export declare function collectDeclPaths(nodes?: AstNode[], path?: PathNode[]): DeclPath[];
+
+ export declare function comment(text: string, source?: string): AstNode;
+
+ export declare interface Config {
+     prefix?: string;
+     cssVarPrefix?: string;
+     /**
+      * Modern dark mode strategy
+      * - 'media': uses @media (prefers-color-scheme: dark)
+      * - 'class': uses .dark selector
+      * - string[]: custom selectors (e.g. ['class', '[data-theme="dark"]'])
+      */
+     darkMode?: 'media' | 'class' | string[];
+     theme?: Theme;
+     presets?: {
+         theme: Theme;
+     }[];
+     /**
+      * Whether to include preflight CSS
+      * - 'minimal': Minimal preflight CSS
+      * - 'standard': Standard preflight CSS
+      * - 'full': Full preflight CSS
+      * - true: Full preflight CSS (default)
+      * - false: No preflight CSS
+      *
+      * default: true (full preflight)
+      */
+     preflight?: PreflightLevel;
+     /**
+      * Whether to clear all caches when context is created/changed
+      * - true (default): Clear all caches on context change
+      * - false: Keep existing caches
+      */
+     clearCacheOnContextChange?: boolean;
+     [key: string]: unknown;
+ }
+
+ export declare function configGetter(config: ContextRecord, ...path: (string | number)[]): unknown;
+
+ export declare interface Context {
+     hasPreset: (category: string, preset: string) => boolean;
+     theme: (...path: (string | number)[]) => unknown;
+     config: (...path: (string | number)[]) => unknown;
+     themeToCssVars: (prefix?: string) => string;
+     extendTheme: (category: string, values: Record<string, unknown> | Function_2) => void;
+     getPreflightCSS: (level?: PreflightLevel) => string;
+ }
+
+ declare type ContextRecord = Record<string, unknown>;
+
+ export declare function createContext(configObj: Config): Context;
+
+ export declare function decl(prop: string, value: string | [string, string][], source?: string): AstNode;
+
+ export declare type DeclPath = PathNode[];
+
+ /**
+  * declPathToAst
+  * Converts decl-to-root path(variant chain) to actual nested AST.
+  * - Input: DeclPath(variant chain)
+  * - Output: Nested AstNode[]
+  * - Consecutive same variants (same key) are merged, nested in outside→inside order
+  *
+  * @param declPath DeclPath
+  * @returns AstNode[]
+  */
+ export declare function declPathToAst(declPath: DeclPath): AstNode[];
+
+ export declare function deepMerge<T extends Record<string, unknown>>(base: T, override: Partial<T>): T;
+
+ export declare const defaultConfig: Config;
+
+ export declare function escapeClassName(className: string): string;
+
+ declare type Function_2 = (...args: unknown[]) => unknown;
+
+ export declare function functionalModifier(match: ModifierRegistration['match'], modifySelector: ModifierRegistration['modifySelector'], wrap?: ModifierRegistration['wrap'], options?: Partial<ModifierRegistration>): 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): void;
+
+ export declare type FunctionalUtilityExtra = {
+     opacity?: string;
+     realThemeValue?: string;
+ };
+
+ export declare type FunctionalUtilityOptions = {
+     /**
+      * The name of the utility
+      *
+      * prefix is automatically added to the name
+      */
+     name: string;
+     /**
+      * The CSS property to set
+      *
+      * css property is automatically added to the prop
+      */
+     prop?: string;
+     /**
+      * The theme key to look up values
+      *
+      * theme key is automatically added to the themeKey
+      *
+      * @example
+      * ```
+      * themeKey: 'colors'
+      * ```
+      */
+     themeKey?: string;
+     /**
+      * The theme keys to look up values
+      *
+      * theme keys are automatically added to the themeKeys
+      *
+      * @example
+      * ```
+      * themeKeys: ['colors', 'spacing']
+      * ```
+      */
+     themeKeys?: string[];
+     /**
+      * Whether to support arbitrary values
+      *
+      * `bg-[#ff0000]`
+      *
+      * @example
+      * ```
+      * supportsArbitrary: true
+      * ```
+      */
+     supportsArbitrary?: boolean;
+     /**
+      * Whether to support fraction values
+      *
+      * `m-4`
+      *
+      * @example
+      * ```
+      * supportsFraction: true
+      * ```
+      */
+     supportsFraction?: boolean;
+     /**
+      * Whether to support custom properties
+      *
+      * `bg-(--my-bg)`
+      *
+      * @example
+      * ```
+      * supportsCustomProperty: true
+      * ```
+      */
+     supportsCustomProperty?: boolean;
+     /**
+      * Whether to support negative values
+      *
+      * `-m-4`
+      *
+      * @example
+      * ```
+      * supportsNegative: true
+      * ```
+      */
+     supportsNegative?: boolean;
+     /**
+      * Whether to support opacity values
+      */
+     supportsOpacity?: boolean;
+     /**
+      * The handler function that processes values
+      *
+      * @example
+      * ```
+      * handle: (value, ctx, token, extra) => {
+      *  return [decl('background-color', value)];
+      * }
+      * ```
+      *
+      * @param value The value to process
+      * @param ctx The context
+      * @param token The parsed utility
+      * @param extra The extra metadata
+      *
+      * @returns {AstNode[] | null | undefined} The AST nodes or null | undefined
+      */
+     handle?: (value: string, ctx: Context, token: ParsedUtility, extra?: FunctionalUtilityExtra) => AstNode[] | null | undefined;
+     /**
+      * The handler function that processes bare values
+      *
+      * @example
+      * ```
+      * handleBareValue: ({ value }) => isPositiveInteger(value) ? value : null,
+      * ```
+      *
+      * @param args The arguments
+      * @param args.value The value to process
+      * @param args.ctx The context
+      * @param args.token The parsed utility
+      * @param args.extra The extra metadata
+      *
+      * @returns {string | null | undefined} The processed value or null | undefined
+      */
+     handleBareValue?: (args: {
+         value: string;
+         ctx: Context;
+         token: ParsedUtility;
+         extra?: FunctionalUtilityExtra;
+     }) => string | null | undefined;
+     /**
+      * The handler function that processes negative bare values
+      *
+      * @example
+      * ```
+      * handleNegativeBareValue: ({ value }) => isPositiveInteger(value) ? value : null,
+      * ```
+      */
+     handleNegativeBareValue?: (args: {
+         value: string;
+         ctx: Context;
+         token: ParsedUtility;
+         extra?: FunctionalUtilityExtra;
+     }) => string | null | undefined;
+     /**
+      * The handler function that processes custom property values
+      *
+      *
+      * @example
+      * ```
+      * handleCustomProperty: (value, ctx, token, extra) => [decl('background-color', value)],
+      * ```
+      *
+      * @param args The arguments
+      * @param args.value The value to process
+      * @param args.ctx The context
+      * @param args.token The parsed utility
+      * @param args.extra The extra metadata
+      *
+      * @returns {AstNode[] | null | undefined} The AST nodes or null | undefined
+      */
+     handleCustomProperty?: (value: string, ctx: Context, token: ParsedUtility, extra?: FunctionalUtilityExtra) => AstNode[] | null | undefined;
+     /**
+      * The description of the utility
+      *
+      * @example
+      * ```
+      * description: 'Custom utility description',
+      * ```
+      */
+     description?: string;
+     /**
+      * The category of the utility
+      *
+      * It is used to group utilities in the documentation and styles
+      *
+      *
+      * @example
+      * ```
+      * category: 'background',
+      * ```
+      */
+     category?: string;
+     /**
+      * The priority of the utility
+      *
+      * It is used to sort utilities in the styles
+      *
+      * @example
+      * ```
+      * priority: 10,
+      * ```
+      *
+      * The higher the number, the higher the priority
+      *
+      * @default 0
+      */
+     priority?: number;
+ };
+
+ /**
+  * generateCss
+  * Takes multiple classNames and generates CSS for each, joining them.
+  * - Input: classList(string), Context, options
+  * - Output: string (result of joining multiple CSS blocks)
+  * - Processes internally parseClassToAst → optimizeAst → astToCss in sequence
+  * - Supports options like dedup, minify
+  *
+  * @param classList string (e.g., 'bg-red-500 text-lg hover:bg-blue-500')
+  * @param ctx Context
+  * @param opts { minify?: boolean, dedup?: boolean }
+      * @returns string
+      *
+      * @example
+      *   const css = generateCss('sm:dark:hover:bg-red-500 sm:focus:bg-blue-500', ctx);
+      */
+  export declare function generateCss(classList: string, ctx: Context, opts?: {
+      minify?: boolean;
+      dedup?: boolean;
+  }): string;
+
+  /**
+   * Returns an array of optimized results for multiple class names with dedup/filter.
+   * - Each object: { cls, ast, css }
+   * - Supports minify, dedup options
+   * - Applies astToCss(cleanAst, cls, opts) per class
+   * @param classList string (space-separated)
+   * @param ctx Context
+   * @param opts { minify?: boolean; dedup?: boolean }
+       * @returns Array<{ cls: string; ast: AstNode[]; css: string }>
+       */
+   export declare function generateCssRules(classList: string, ctx: Context, opts?: {
+       minify?: boolean;
+       dedup?: boolean;
+   }): Array<GenerateCssRulesResult>;
+
+   export declare type GenerateCssRulesResult = {
+       cls: string;
+       ast: AstNode[];
+       css: string;
+       cssList: string[];
+       rootCss: string;
+       rootCssList: string[];
+   };
+
+   export declare function getModifier(): ModifierRegistration[];
+
+   export declare function getPreflightCSS(level?: PreflightLevel): string;
+
+   export declare function getUtility(): UtilityRegistration[];
+
+   export declare type HasItems = {
+       items?: AstNode[];
+   };
+
+   export declare type HasName = {
+       name?: string;
+   };
+
+   export declare type HasNodes = {
+       nodes?: AstNode[];
+   };
+
+   export declare type HasParams = {
+       params?: string;
+   };
+
+   export declare function hasPreset(themeObj: Theme, category: string, preset: string): boolean;
+
+   export declare type HasProp = {
+       prop?: string;
+   };
+
+   export declare type HasSelector = {
+       selector?: string;
+   };
+
+   export declare type HasSource = {
+       source?: string;
+   };
+
+   export declare type HasText = {
+       text?: string;
+   };
+
+   export declare type HasValue = {
+       value?: string | [string, string][];
+   };
+
+   /**
+    * Incremental parsing system for efficient class processing
+    *
+    * This class provides an optimized approach to CSS class processing by:
+    * - Tracking processed classes to avoid redundant work
+    * - Batching multiple class operations for better performance
+    * - Supporting both synchronous and asynchronous processing modes
+    *
+    * ## Usage Patterns
+    *
+    * ### Universal Usage (Node.js & Browser)
+    * ```typescript
+    * const parser = new IncrementalParser(ctx);
+    *
+    * // Process classes synchronously
+    * const results = parser.processClasses(['bg-blue-500', 'text-lg']);
+    *
+    * // Process single class
+    * const result = parser.processClass('bg-red-500');
+    *
+    * // Get statistics
+    * const stats = parser.getStats();
+    * ```
+    *
+    * ### Browser Integration
+    * ```typescript
+    * const parser = new IncrementalParser(ctx);
+    * const BrowserRuntime = new BrowserRuntime();
+    *
+    * // Process classes and manually inject CSS
+    * const results = parser.processClasses(['bg-blue-500', 'text-lg']);
+    * results.forEach(result => {
+    *   if (result.css) {
+    *     BrowserRuntime.insertRule(result.css);
+    *   }
+    * });
+    *
+    * // Use with ChangeDetector for automatic DOM monitoring
+    * const detector = new ChangeDetector(parser);
+    * detector.observe(document.body, { scan: true });
+    * ```
+    *
+    * ## Architecture
+    *
+    * - **IncrementalParser**: Pure CSS processing (works in Node.js and browser)
+    * - **ChangeDetector**: Browser-only DOM monitoring (uses MutationObserver)
+    * - **BrowserRuntime**: Browser-only CSS injection (uses DOM APIs)
+    */
+   export declare class IncrementalParser {
+       /** Set of class names that have already been processed to avoid duplicates */
+       private processedClasses;
+       /** BAROCSS context for theme and utility resolution */
+       private ctx;
+       /** Maximum number of classes to process in a single batch */
+       private batchSize;
+       /** Debounce delay for batch processing in milliseconds */
+       private debounceMs;
+       /** Set of classes waiting to be processed */
+       private pendingClasses;
+       /** Timer for debounced batch processing */
+       private batchTimer;
+       /**
+        * Create a new IncrementalParser instance
+        *
+        * @param ctx - BAROCSS context for theme and utility resolution
+        */
+       constructor(ctx: Context);
+       /**
+        * Processes a single CSS class and generates its AST and CSS representation
+        *
+        * This method performs the complete pipeline for a single class:
+        * 1. Checks if the class has already been processed
+        * 2. Parses the class name to extract utility information
+        * 3. Generates the Abstract Syntax Tree (AST)
+        * 4. Converts the AST to CSS rules
+        * 5. Marks the class as processed to avoid future duplicates
+        *
+        * @param className - The CSS class name to process (e.g., 'bg-blue-500')
+        * @returns Object containing AST and CSS, or null if processing failed or class was already processed
+        */
+       processClass(className: string): GenerateCssRulesResult | null;
+       /**
+        * Processes multiple CSS classes in batches for optimal performance
+        *
+        * This method handles multiple classes efficiently by:
+        * - Filtering out already processed classes to avoid redundant work
+        * - Processing classes in configurable batch sizes
+        * - Returning comprehensive results for each processed class
+        *
+        * @param classes - Array of CSS class names to process
+        * @returns Array of processing results, each containing className, AST, and CSS
+        */
+       processClasses(classes: string[]): Array<GenerateCssRulesResult>;
+       /**
+        * Adds classes to the pending queue for asynchronous batch processing
+        *
+        * This method is used by the ChangeDetector when new classes are discovered
+        * in the DOM. Classes are queued and processed together to minimize
+        * performance impact from frequent DOM mutations.
+        *
+        * @param classes - Array of CSS class names to queue for processing
+        */
+       addToPending(classes: string[]): void;
+       /**
+        * Schedule batch processing with debouncing
+        *
+        * This method uses setTimeout to debounce rapid class additions
+        * and process them in batches for better performance.
+        */
+       private scheduleBatchProcessing;
+       /**
+        * Process pending classes from the queue
+        *
+        * This method is called by the debounced timer to process
+        * all classes that have been added to the pending queue.
+        */
+       private processPendingClasses;
+       /**
+        * Core method that processes classes and marks them as processed
+        *
+        * This is the common processing logic used by both pending and synchronous
+        * processing methods. It:
+        * 1. Processes the provided classes using the batch processor
+        * 2. Marks classes as processed to prevent duplicates
+        *
+        * @param classes - Array of CSS class names to process
+        */
+       private applyClasses;
+       /**
+        * Returns comprehensive statistics about the incremental parser's state
+        *
+        * This method provides detailed metrics including:
+        * - Number of processed classes
+        * - Number of pending classes
+        * - Cache statistics from AST and CSS caches
+        *
+        * @returns Object containing processing statistics and cache information
+        */
+       getStats(): {
+           processedClasses: number;
+           pendingClasses: number;
+           cacheStats: {
+               ast: {
+                   size: number;
+                   maxSize: number;
+                   hitRate: number;
+               };
+               css: {};
+           };
+       };
+       /**
+        * Clears all processed classes and pending queue
+        *
+        * This method is useful when the theme or configuration changes,
+        * requiring all classes to be reprocessed. It:
+        * - Clears the processed classes set
+        * - Clears the pending classes queue
+        * - Cancels any pending batch processing timer
+        */
+       clearProcessed(): void;
+       /**
+        * Checks if a specific class has been processed
+        *
+        * @param cls - The CSS class name to check
+        * @returns True if the class has been processed, false otherwise
+        */
+       isProcessed(cls: string): boolean;
+       /**
+        * Marks a class as processed to prevent future duplicate processing
+        *
+        * @param cls - The CSS class name to mark as processed
+        */
+       markProcessed(cls: string): void;
+       /**
+        * Process classes synchronously and update BrowserRuntime cache
+        * This method is used by ChangeDetector for scan operations
+        */
+       processClassesSync(classes: string[]): void;
+       /**
+        * Returns all currently processed class names
+        *
+        * This method is useful for debugging and monitoring purposes,
+        * providing visibility into which classes have been processed.
+        *
+        * @returns Array of all processed class names
+        */
+       getProcessedClasses(): string[];
+   }
+
+   /**
+    * mergeAstTreeList
+    * Takes a list of declPathToAst results (AstNode[][]), merges same at-rule(name, params) etc., and returns the final AST tree.
+    * - Input: AstNode[][] (nested ASTs of multiple decl-to-root paths)
+    * @returns AstNode[]
+    * - Usage: Used in optimizeAst for final AST merging/optimization
+    *
+    * @param astList AstNode[][]
+    * @returns AstNode[]
+    */
+   export declare function mergeAstTreeList(astList: AstNode[][]): AstNode[];
+
+   export declare type ModifierRegistration = {
+       match: (mod: string, context: Context) => boolean;
+       modifySelector?: (params: {
+           selector: string;
+           fullClassName: string;
+           mod: ParsedModifier;
+           context: Context;
+           variantChain?: ParsedModifier[];
+           index?: number;
+       }) => string | {
+           selector: string;
+           flatten?: boolean;
+           wrappingType?: 'rule' | 'style-rule' | 'at-rule';
+           override?: boolean;
+           source?: string;
+       };
+       wrap?: (mod: ParsedModifier, context: Context) => AstNode[];
+       astHandler?: (ast: AstNode[], mod: ParsedModifier, context: Context, variantChain?: ParsedModifier[], index?: number) => AstNode[];
+       sort?: number;
+       description?: string;
+       source?: string;
+   };
+
+   export declare const modifierRegistry: ModifierRegistration[];
+
+   /**
+    * optimizeAst
+    * Merges/organizes AST generated by parseClassToAst into an optimized AST tree based on decl-to-root path.
+    * - Input: AstNode[] (result of parseClassToAst)
+    * - Output: Optimized AST tree (AstNode[])
+    * - Uses collectDeclPaths, declPathToAst, mergeAstTreeList internally
+    * - Reflects all variant wrapping structures (nesting, siblings, merging, etc.)
+    *
+    * @param ast AstNode[]
+    * @returns AstNode[]
+    */
+   export declare function optimizeAst(ast: AstNode[]): AstNode[];
+
+   /**
+    * Parses a class name string into modifiers and utility using tokenization
+    * Supports both directions:
+    * - modifier:utility (traditional CSS)
+    * - utility:modifier (Master CSS style)
+    *
+    * Examples:
+    * - 'group-hover:sm:bg-[red]' → modifier:utility
+    * - 'bg-red-500:hover' → utility:modifier
+    * - 'text-[color:var(--foo)]' → utility only
+    *
+    * @param className e.g. 'group-hover:sm:bg-[red]', 'text-[color:var(--foo)]'
+    * @returns { modifiers, utility }
+        */
+    export declare function parseClassName(className: string): {
+        modifiers: ParsedModifier[];
+        utility: ParsedUtility | null;
+    };
+
+    /**
+     * parseClassToAst
+     * Parses className(including variant chain) to generate AST tree.
+     * - Input: className(string), Context
+     * - Output: AstNode[] (multiple roots possible for variant wrapping path)
+     * - Perfectly supports variant wrapping structure (Cartesian product, nesting, siblings, etc.)
+     * - Accumulates wrappers in wrappers and applies them from right to left.
+     * - Can return multiple root asts.
+     *
+     * @param fullClassName string (e.g., 'sm:dark:hover:bg-red-500')
+     * @param ctx Context
+     * @returns AstNode[]
+     *
+     * @example
+     *   const ast = parseClassToAst('sm:dark:hover:bg-red-500', ctx);
+     *   // ast is an AST tree with sm, dark, hover variants nested
+     */
+    export declare function parseClassToAst(fullClassName: string, ctx: Context): AstNode[];
+
+    export declare interface ParsedModifier {
+        type: string;
+        value?: string;
+        negative?: boolean;
+        arbitrary?: boolean;
+        [key: string]: unknown;
+    }
+
+    export declare interface ParsedUtility {
+        category?: string;
+        prefix: string;
+        value?: string;
+        arbitrary?: boolean;
+        customProperty?: boolean;
+        negative?: boolean;
+        opacity?: string;
+        priority?: number;
+        important?: boolean;
+        [key: string]: unknown;
+    }
+
+    /**
+     * Parse result cache management
+     */
+    export declare class ParseResultCache {
+        private cache;
+        private maxSize;
+        set(key: string, result: {
+            modifiers: ParsedModifier[];
+            utility: ParsedUtility | null;
+        }): void;
+        get(key: string): {
+            modifiers: ParsedModifier[];
+            utility: ParsedUtility | null;
+        } | undefined;
+        has(key: string): boolean;
+        clear(): void;
+        getStats(): {
+            size: number;
+            maxSize: number;
+            hitRate: number;
+        };
+    }
+
+    export declare const parseResultCache: ParseResultCache;
+
+    /**
+     * decl-to-root path collection function (reused in normalizeAstOrder, etc.)
+     */
+    export declare type PathNode = Partial<AstNode>;
+
+    declare type PreflightLevel = 'minimal' | 'standard' | 'full' | true | false;
+
+    export declare function property(name: string, initialValue?: string, syntax?: string, source?: string): AstNode;
+
+    export declare function raw(value: string, source?: string): AstNode;
+
+    export declare function registerUtility(util: UtilityRegistration): void;
+
+    export declare function resolveTheme(config: Config): Theme;
+
+    export declare function rootToCss(nodes: AstNode[]): string;
+
+    export declare function rule(selector: string, nodes: AstNode[], source?: string): AstNode;
+
+    /**
+     * staticModifier: A helper that registers a modifier name and an array of CSS selectors directly to the registry
+     *
+     * @example
+     * ```
+     * staticModifier('disabled', ['&:disabled'], { source: 'pseudo' });
+     * ```
+     *
+     * @param name The name of the modifier
+     * @param selectors The selectors of the modifier
+     * @param options The options of the modifier
+     *
+     * @returns {void}
+     */
+    export declare function staticModifier(name: string, selectors: string[], options?: any): void;
+
+    /**
+     * staticUtility: A helper that registers a utility name and an array of CSS declaration pairs directly to the registry
+     *
+     * @example
+     * ```
+     *   staticUtility('block', [['display', 'block']]);
+     *   staticUtility('hidden', [['display', 'none']]);
+     *   staticUtility('space-x-px', [
+     *     [
+     *       '& > :not([hidden]) ~ :not([hidden])', // selector
+     *       [
+     *         ['margin-inline-start', '1px'], // [prop, value]
+     *         ['margin-inline-end', '1px'], // [prop, value]
+     *       ],
+     *     ],
+     *   ]);
+     * ```
+     *
+     * @param name The name of the utility
+     * @param decls The declarations of the utility
+     * @param opts The options of the utility
+     *
+     * @returns {void}
+     */
+    export declare function staticUtility(name: string, decls: StaticUtilityValue[], opts?: {
+        description?: string;
+        category?: string;
+        priority?: number;
+    }): void;
+
+    declare type StaticUtilityValue = AstNode | [string, string] | [string, [string, string][]] | ((value: string) => AstNode);
+
+    export declare function styleRule(selector: string, nodes: AstNode[], source?: string): AstNode;
+
+    export declare interface Theme {
+        extend?: Theme;
+        [namespace: string]: unknown;
+    }
+
+    export declare type ThemeGetter = (...path: (string | number)[]) => unknown;
+
+    /**
+     * Modern theme getter for BAROCSS
+     *
+     * - Supports category-level (first path segment) function values only.
+     *   - If the category (e.g., 'spacing', 'colors') is a function, it will be executed with the theme getter as argument.
+     *   - This allows dynamic theme extension and plugin-style patterns, e.g.:
+     *     spacing: (theme) => ({ ...theme('spacing'), '72': '18rem' })
+     * - Leaf (property) functions are NOT supported and will be ignored (returns undefined).
+     * - Infinite recursion is prevented: If the exact same path is being resolved recursively (directly or indirectly), undefined is returned for that call.
+     *   - Category-level functions can safely call theme('category.otherKey') for dynamic references.
+     *   - Only true recursion on the same path is blocked.
+     * - All theme lookups (theme('category.key')) will always re-execute the category function if present, ensuring dynamic resolution.
+     *
+     * @param themeObj - The theme object (possibly with category functions)
+     * @param path - Path segments (string or number), or dot-path string (e.g. 'colors.red.500')
+     * @returns The resolved theme value, or undefined if not found or if a leaf function is encountered
+     *
+     * @example
+     *   const theme = {
+     *     spacing: (theme) => ({ 1: '0.25rem', 2: theme('spacing.1') }),
+     *   };
+     *   themeGetter(theme, 'spacing.2'); // '0.25rem'
+     *
+     * @example
+     *   // Infinite recursion is prevented:
+     *   const theme = {
+     *     spacing: (theme) => theme('spacing.1'),
+     *   };
+     *   themeGetter(theme, 'spacing.1'); // undefined
+     */
+    export declare function themeGetter(themeObj: Theme, ...path: (string | number)[]): unknown;
+
+    export declare function themeToCssVars(theme: Theme): string;
+
+    export declare interface Token {
+        value: string;
+        start: number;
+        end: number;
+    }
+
+    /**
+     * Tokenizes a class name string into an array of tokens
+     * Only handles separation by ':' while respecting brackets and parentheses
+     *
+     * Examples:
+     * - 'hover:bg-red-500' → [{ value: 'hover' }, { value: 'bg-red-500' }]
+     * - 'bg-[#ff0000]:hover' → [{ value: 'bg-[#ff0000]' }, { value: 'hover' }]
+     * - 'text-[color:var(--foo)]' → [{ value: 'text-[color:var(--foo)]' }]
+     * - '!bg-[red]' → [{ value: '!bg-[red]' }]
+     */
+    export declare function tokenize(className: string): Token[];
+
+    /**
+     * Utility cache management
+     */
+    export declare class UtilityCache {
+        private cache;
+        private maxSize;
+        set(key: string, value: boolean): void;
+        get(key: string): boolean | undefined;
+        has(key: string): boolean;
+        clear(): void;
+        getStats(): {
+            size: number;
+            maxSize: number;
+            hitRate: number;
+        };
+    }
+
+    export declare const utilityCache: UtilityCache;
+
+    export declare interface UtilityRegistration {
+        /**
+         * The name of the utility
+         */
+        name: string;
+        /**
+         * The match function for the utility
+         * @param className The class name of the utility
+         * @returns {boolean} Whether the utility matches the class name
+         */
+        match: (className: string) => boolean;
+        /**
+         * Handler for utility value
+         * @param value Utility value (e.g. 'red-500')
+         * @param ctx Context
+         * @param token Parsed token
+         * @param options Registration options
+         */
+        handler: (value: string, ctx: Context, token: ParsedUtility, options: UtilityRegistration) => AstNode[] | null | undefined;
+        /**
+         * The description of the utility
+         * @example
+         * ```
+         * description: 'Custom utility description',
+         * ```
+         */
+        description?: string;
+        /**
+         * The category of the utility
+         * @example
+         * ```
+         * category: 'background',
+         * ```
+         */
+        category?: string;
+        /**
+         * The priority of the utility
+         * @example
+         * ```
+         * priority: 10,
+         * ```
+         */
+        priority?: number;
+        [key: string]: unknown;
+    }
+
+    /**
+     * WeakMap-based cache for memory optimization
+     */
+    export declare class WeakCache<T> {
+        private cache;
+        private keyMap;
+        private maxSize;
+        set(key: string, value: T): void;
+        get(key: string): T | undefined;
+        has(key: string): boolean;
+        clear(): void;
+        getStats(): {
+            size: number;
+            maxSize: number;
+            hitRate: number;
+        };
+    }
+
+    export { }