@barocss/kit 0.0.3 → 0.5.0

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+/** Arbitrary property class `[prop:value]` (parser sets token.property). */
+export declare const arbitraryPropertyRegistration: UtilityRegistration;
+
 /**
  * AST cache management
  */
@@ -161,7 +164,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
@@ -204,9 +207,14 @@ 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
+      * Enable kit console diagnostics (off by default).
+      * This sets a process-wide flag (see setDebug): it affects every context, and a
+      * config without this key leaves the current flag unchanged.
+      */
+     debug?: boolean;
+     /**
+      * @deprecated Contexts now own their caches. Creating a context does not
+      * clear caches that belong to another context.
       */
      clearCacheOnContextChange?: boolean;
      [key: string]: unknown;
@@ -249,9 +257,16 @@ export declare type AstNode = {
 
  export declare function escapeClassName(className: string): string;
 
+ /**
+  * Add Tailwind-style spacing inside calc()/min()/max()/clamp():
+  * `calc(100%-2rem)` -> `calc(100% - 2rem)`. Leaves nested non-math functions
+  * (var(--x-y)), unary signs and exponents (1e-3) alone.
+  */
+ export declare function expandThemeFunctions(value: 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;
+ 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
@@ -267,7 +282,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;
@@ -524,11 +539,26 @@ 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[];
+
+   /**
+    * #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.
+    * Commas are allowed (values are not selector lists), so this is isSafeVariantValue with top-level commas allowed.
+    */
+   /** #248: a comment opener or closer anywhere in a variant (quoted or not) could leave a comment unclosed in the output. */
+   export declare function hasCommentToken(value: string): boolean;
 
    export declare type HasItems = {
        items?: AstNode[];
@@ -757,6 +787,19 @@ export declare type AstNode = {
        getProcessedClasses(): string[];
    }
 
+   export declare function isDebug(): boolean;
+
+   /**
+    * #221: isSafeVariantValue for a whole variant token, except that has-[…]/not-[…] (optionally group-/peer-) may
+    * carry a comma at the top level of their bracket value: those variants wrap the value in `:has()`/`:not()`.
+    * The value itself must still be balanced and free of `{`, `}` and `;`, so it cannot close the pseudo-class.
+    */
+   export declare function isSafeVariantToken(value: string): boolean;
+
+   export declare function isSafeVariantValue(value: string, allowTopLevelComma?: boolean): boolean;
+
+   export declare function isStructureSafeValue(value: string): boolean;
+
    /**
     * Converts a single BaroJsonInput object into an AST tree.
     * Bypasses string parsing and directly invokes utility/modifier handlers.
@@ -788,13 +831,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;
@@ -804,6 +841,16 @@ 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;
+   };
+
+   export declare function normalizeMathSpacing(value: string): string;
+
    /**
     * optimizeAst
     * Merges/organizes AST generated by parseClassToAst into an optimized AST tree based on decl-to-root path.
@@ -831,7 +878,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;
     };
@@ -873,6 +920,8 @@ export declare type AstNode = {
         opacity?: string;
         priority?: number;
         important?: boolean;
+        /** Set for an arbitrary property class (`[prop:value]`); `value` holds the raw value. */
+        property?: string;
         [key: string]: unknown;
     }
 
@@ -912,14 +961,23 @@ 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;
 
-    export declare function rootToCss(nodes: AstNode[]): string;
+    export declare function rootToCss(nodes: AstNode[], opts?: {
+        minify?: boolean;
+    }): string;
 
     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;
+
+    export declare function setDebug(enabled: boolean): void;
+
     /**
      * staticModifier: A helper that registers a modifier name and an array of CSS selectors directly to the registry
      *
@@ -934,7 +992,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
@@ -964,7 +1022,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);