@barocss/kit 0.4.0 → 0.6.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
  */
@@ -178,6 +181,8 @@ export declare type AstNode = {
 
  export declare function comment(text: string, source?: string): AstNode;
 
+ export declare function compareKeys(a: RuleKey, b: RuleKey): number;
+
  export declare interface Config {
      prefix?: string;
      cssVarPrefix?: string;
@@ -203,6 +208,12 @@ export declare type AstNode = {
       * default: true (full preflight)
       */
      preflight?: PreflightLevel;
+     /**
+      * 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.
@@ -248,24 +259,17 @@ 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>, ctx?: Context): 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, ctx?: Context): void;
 
  export declare type FunctionalUtilityExtra = {
@@ -404,6 +408,12 @@ export declare type AstNode = {
       * handleNegativeBareValue: ({ value }) => isPositiveInteger(value) ? value : null,
       * ```
       */
+     /**
+      * #261: the utility uses the spacing scale, so a named `theme.spacing` key (`p-gutter`) resolves to
+      * `var(--spacing-<key>)` (negative: `calc(var(--spacing-<key>) * -1)`), as in Tailwind 4. Only tried
+      * after the bare-value handler rejects the value, so built-in keywords keep precedence.
+      */
+     spacingKeys?: boolean;
      handleNegativeBareValue?: (args: {
          value: string;
          ctx: Context;
@@ -536,6 +546,21 @@ export declare type AstNode = {
 
    export declare function getUtility(ctx?: Context): UtilityRegistration[];
 
+   /**
+    * #273: true when an emitted selector or at-rule prelude contains a comment opener or closer outside a CSS escape.
+    * Backslash-escape pairs are skipped, so an escaped `\/` or `\*` from a class name never counts. Used by the
+    * serializer on the final, composed string, where adjacent pieces that were each safe alone can join into one.
+    */
+   export declare function hasCommentDelimiter(text: string): boolean;
+
+   /**
+    * #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[];
    };
@@ -747,6 +772,13 @@ export declare type AstNode = {
         * @param cls - The CSS class name to mark as processed
         */
        markProcessed(cls: string): void;
+       /**
+        * Forgets that a class was processed, so a later request generates it again
+        * (used when the browser runtime reclaims an unused class's rules, #269).
+        *
+        * @param cls - The CSS class name to forget
+        */
+       unmarkProcessed(cls: string): void;
        /**
         * Process classes synchronously and update BrowserRuntime cache
         * This method is used by ChangeDetector for scan operations
@@ -763,6 +795,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.
@@ -812,6 +857,8 @@ export declare type AstNode = {
        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.
@@ -881,6 +928,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;
     }
 
@@ -926,13 +975,38 @@ export declare type AstNode = {
 
     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;
 
+    /**
+     * Tailwind-compatible cascade order for runtime-inserted rules (#254); shared by @barocss/server (#267).
+     *
+     * 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.
+     */
+    export declare type RuleKey = number[];
+
+    export declare function ruleSortKey(rule: string): RuleKey;
+
     /** 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
      *
@@ -1042,6 +1116,9 @@ export declare type AstNode = {
      */
     export declare function tokenize(className: string): Token[];
 
+    /** Index after the last key <= `key` (stable upper bound) in sorted `keys`. */
+    export declare function upperBound(keys: RuleKey[], key: RuleKey): number;
+
     /**
      * Utility cache management
      */