@barocss/kit 0.0.2 → 0.4.0

package/README.md

@@ -13,10 +13,10 @@
 - **🚀 JIT Parsing** - Parse Tailwind syntax and generate CSS instantly
 - **🔍 AST Processing** - Advanced Abstract Syntax Tree manipulation
 - **⚡ Incremental Parsing** - Efficient parsing with caching
-- **🎯 Tailwind Compatible** - Full Tailwind CSS syntax support
+- **🎯 Tailwind-style syntax** - See the [versioned compatibility baseline](docs/tailwind-compatibility.md)
 - **🌐 Universal** - Works in browsers, Node.js, and any JavaScript environment
-- **🎨 Complete Utility Support** - Layout, spacing, colors, typography, and more
-- **📱 Responsive & Interactive** - All variants work out of the box
+- **🎨 Utility presets** - Layout, spacing, colors, typography, and more
+- **📱 Responsive & interactive variants** - See the measured examples below
 - **🧠 Smart Caching** - Caching system for performance optimization
 
 ## 🚀 Quick Start
@@ -234,7 +234,7 @@ const stats = parser.getStats();
 
 ## 📱 Supported Utilities
 
-BaroCSS supports **most Tailwind CSS utilities**:
+BaroCSS supports the utilities listed below. See the [compatibility baseline](docs/tailwind-compatibility.md) for measured examples.
 
 ### Layout
 - `container`, `columns`, `break-after`, `break-before`

package/dist/index.d.ts

@@ -72,6 +72,87 @@ export declare type AstNode = {
 
  export declare function atRule(name: string, params: string, nodes: AstNode[], source?: string): AstNode;
 
+ /**
+  * The structured input format for BaroCSS engine.
+  * Designed to be easily generated by AI models.
+  */
+ export declare type BaroJsonInput = {
+     /**
+      * The core utility to apply.
+      * Corresponds to the utility class name in Tailwind (e.g., 'bg-red-500', 'p-4').
+      */
+     utility: {
+         /**
+          * The utility prefix.
+          * @example 'bg', 'text', 'p', 'm', 'flex', 'hidden'
+          */
+         name: string;
+         /**
+          * The value of the utility.
+          * Optional for boolean utilities like 'flex', 'hidden'.
+          * @example 'red-500', '4', 'lg', '#123456'
+          */
+         value?: string;
+         /**
+          * Whether the value is an arbitrary value (JIT).
+          * @default false
+          * @example true for 'bg-[#123456]'
+          */
+         arbitrary?: boolean;
+         /**
+          * Whether the value is negative.
+          * @default false
+          * @example true for '-m-4'
+          */
+         negative?: boolean;
+         /**
+          * Opacity modifier for colors.
+          * @example '50' for 'bg-red-500/50'
+          */
+         opacity?: string;
+         /**
+          * Whether the value is a custom property.
+          * @default false
+          * @example true for 'bg-(--my-bg)'
+          */
+         customProperty?: boolean;
+         /**
+          * Whether the utility is marked as important (!).
+          * @default false
+          * @example true for '!bg-red-500'
+          */
+         important?: boolean;
+     };
+     /**
+      * List of variants/modifiers to apply.
+      * Applied from outside to inside (left to right in string format).
+      * @example ['hover', 'focus'] for 'hover:focus:bg-red-500'
+      */
+     variants?: Array<string | BaroVariant>;
+ };
+
+ /**
+  * Detailed configuration for a variant.
+  */
+ export declare type BaroVariant = {
+     /**
+      * The name of the variant.
+      * @example 'hover', 'focus', 'sm', 'data', 'group-hover'
+      */
+     name: string;
+     /**
+      * The value for parameterized variants.
+      * @example 'open' for 'data-[state=open]'
+      */
+     value?: string;
+     /**
+      * Whether the variant is arbitrary.
+      * @default false
+      * @example true for 'min-[320px]'
+      */
+     arbitrary?: boolean;
+ };
+
  /**
   * Clear all caches (for context changes or testing)
   */
@@ -80,7 +161,7 @@ export declare type AstNode = {
  /**
   * Clear all AST caches (mainly for testing)
   */
- export declare function clearAstCache(): void;
+ export declare function clearAstCache(ctx?: Context): void;
 
  /**
   * collectDeclPaths
@@ -123,9 +204,8 @@ export declare type AstNode = {
       */
      preflight?: PreflightLevel;
      /**
-      * Whether to clear all caches when context is created/changed
-      * - true (default): Clear all caches on context change
-      * - false: Keep existing caches
+      * @deprecated Contexts now own their caches. Creating a context does not
+      * clear caches that belong to another context.
       */
      clearCacheOnContextChange?: boolean;
      [key: string]: unknown;
@@ -170,7 +250,7 @@ export declare type AstNode = {
 
  declare type Function_2 = (...args: unknown[]) => unknown;
 
- export declare function functionalModifier(match: ModifierRegistration['match'], modifySelector: ModifierRegistration['modifySelector'], wrap?: ModifierRegistration['wrap'], options?: Partial<ModifierRegistration>): void;
+ 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
@@ -186,7 +266,7 @@ export declare type AstNode = {
   *     category: 'layout',
   *   });
   */
- export declare function functionalUtility(opts: FunctionalUtilityOptions): void;
+ export declare function functionalUtility(opts: FunctionalUtilityOptions, ctx?: Context): void;
 
  export declare type FunctionalUtilityExtra = {
      opacity?: string;
@@ -407,6 +487,18 @@ export declare type AstNode = {
       dedup?: boolean;
   }): string;
 
+  /**
+   * Generates CSS from a list of BaroJsonInput objects.
+   *
+   * @param inputs Array of BaroJsonInput
+   * @param ctx Context
+   * @param opts Options (minify, etc.)
+   * @returns CSS string
+   */
+  export declare function generateCssFromJson(inputs: BaroJsonInput[], ctx: Context, opts?: {
+      minify?: boolean;
+  }): string;
+
   /**
    * Returns an array of optimized results for multiple class names with dedup/filter.
    * - Each object: { cls, ast, css }
@@ -431,11 +523,18 @@ export declare type AstNode = {
        rootCssList: string[];
    };
 
-   export declare function getModifier(): ModifierRegistration[];
+   /** Read AST cache statistics for one context, or the legacy global cache. */
+   export declare function getAstCacheStats(ctx?: Context): {
+       size: number;
+       maxSize: number;
+       hitRate: number;
+   };
+
+   export declare function getModifier(ctx?: Context): ModifierRegistration[];
 
    export declare function getPreflightCSS(level?: PreflightLevel): string;
 
-   export declare function getUtility(): UtilityRegistration[];
+   export declare function getUtility(ctx?: Context): UtilityRegistration[];
 
    export declare type HasItems = {
        items?: AstNode[];
@@ -664,6 +763,16 @@ export declare type AstNode = {
        getProcessedClasses(): string[];
    }
 
+   /**
+    * Converts a single BaroJsonInput object into an AST tree.
+    * Bypasses string parsing and directly invokes utility/modifier handlers.
+    *
+    * @param input BaroJsonInput object
+    * @param ctx Context
+    * @returns AstNode[]
+    */
+   export declare function jsonToAst(input: BaroJsonInput, ctx: Context): AstNode[];
+
    /**
     * mergeAstTreeList
     * Takes a list of declPathToAst results (AstNode[][]), merges same at-rule(name, params) etc., and returns the final AST tree.
@@ -685,13 +794,7 @@ export declare type AstNode = {
            context: Context;
            variantChain?: ParsedModifier[];
            index?: number;
-       }) => string | {
-           selector: string;
-           flatten?: boolean;
-           wrappingType?: 'rule' | 'style-rule' | 'at-rule';
-           override?: boolean;
-           source?: string;
-       };
+       }) => string | ModifierSelector | ModifierSelector[];
        wrap?: (mod: ParsedModifier, context: Context) => AstNode[];
        astHandler?: (ast: AstNode[], mod: ParsedModifier, context: Context, variantChain?: ParsedModifier[], index?: number) => AstNode[];
        sort?: number;
@@ -701,6 +804,14 @@ export declare type AstNode = {
 
    export declare const modifierRegistry: ModifierRegistration[];
 
+   export declare type ModifierSelector = {
+       selector: string;
+       flatten?: boolean;
+       wrappingType?: 'rule' | 'style-rule' | 'at-rule';
+       override?: boolean;
+       source?: string;
+   };
+
    /**
     * optimizeAst
     * Merges/organizes AST generated by parseClassToAst into an optimized AST tree based on decl-to-root path.
@@ -728,7 +839,7 @@ export declare type AstNode = {
     * @param className e.g. 'group-hover:sm:bg-[red]', 'text-[color:var(--foo)]'
     * @returns { modifiers, utility }
         */
-    export declare function parseClassName(className: string): {
+    export declare function parseClassName(className: string, ctx?: Context): {
         modifiers: ParsedModifier[];
         utility: ParsedUtility | null;
     };
@@ -809,7 +920,9 @@ export declare type AstNode = {
 
     export declare function raw(value: string, source?: string): AstNode;
 
-    export declare function registerUtility(util: UtilityRegistration): void;
+    export declare function registerModifier(modifier: ModifierRegistration, ctx?: Context): void;
+
+    export declare function registerUtility(util: UtilityRegistration, ctx?: Context): void;
 
     export declare function resolveTheme(config: Config): Theme;
 
@@ -817,6 +930,9 @@ export declare type AstNode = {
 
     export declare function rule(selector: string, nodes: AstNode[], source?: string): AstNode;
 
+    /** Internal hook for caches owned by contexts. */
+    export declare function setContextCacheReset(reset: () => void): void;
+
     /**
      * staticModifier: A helper that registers a modifier name and an array of CSS selectors directly to the registry
      *
@@ -831,7 +947,7 @@ export declare type AstNode = {
      *
      * @returns {void}
      */
-    export declare function staticModifier(name: string, selectors: string[], options?: any): void;
+    export declare function staticModifier(name: string, selectors: string[], options?: any, ctx?: Context): void;
 
     /**
      * staticUtility: A helper that registers a utility name and an array of CSS declaration pairs directly to the registry
@@ -861,7 +977,7 @@ export declare type AstNode = {
         description?: string;
         category?: string;
         priority?: number;
-    }): void;
+    }, ctx?: Context): void;
 
     declare type StaticUtilityValue = AstNode | [string, string] | [string, [string, string][]] | ((value: string) => AstNode);