@styleframe/scanner 3.0.0 → 3.1.1

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { ModifierFactory } from '@styleframe/core';
 import { Root } from '@styleframe/core';
 import { Utility } from '@styleframe/core';
 import { UtilityFactory } from '@styleframe/core';
+import { UtilitySelectorFn } from '@styleframe/core';
+import { UtilitySelectorOptions } from '@styleframe/core';
 
 /**
  * Pattern to extract the value from an arbitrary value bracket notation.
@@ -24,7 +26,7 @@ export declare interface CacheEntry {
 /**
  * Generate the raw utility class name from options (without CSS escaping).
  */
-export declare function classNameFromUtilityOptions(options: UtilitySelectorOptions): string;
+export declare function classNameFromUtilityOptions(options: UtilitySelectorOptions, selectorFn?: UtilitySelectorFn): string;
 
 /**
  * Create a scanner cache instance.
@@ -55,7 +57,7 @@ export declare function createChangeHandler(callback: (changedFiles: string[]) =
  *
  * Useful for testing or one-off scans.
  */
-export declare function createContentScanner(customExtractors?: Extractor[]): (content: string, filePath?: string) => ParsedUtility[];
+export declare function createContentScanner(customExtractors?: Extractor[], utilities?: ScannerUtilitiesConfig): (content: string, filePath?: string) => ParsedUtility[];
 
 /**
  * Create a scanner instance for detecting utility classes in content files.
@@ -79,9 +81,10 @@ export declare function createScanner(config: ScannerConfig): Scanner;
  * Create a filter function that checks if a utility is in the used set.
  *
  * @param usedClasses Set of used utility class names
+ * @param selectorFn Optional custom selector function
  * @returns Filter function for utilities
  */
-export declare function createUtilityFilter(usedClasses: Set<string>): (utility: Utility) => boolean;
+export declare function createUtilityFilter(usedClasses: Set<string>, selectorFn?: UtilitySelectorFn): (utility: Utility) => boolean;
 
 /**
  * Simple debounce utility
@@ -104,33 +107,34 @@ export declare const DEFAULT_IGNORE_PATTERNS: string[];
  * @param content The file content
  * @param filePath The file path (used to determine extractor)
  * @param customExtractors Optional custom extractors to use in addition to defaults
+ * @param utilityPattern Optional custom regex pattern for utility class extraction
  * @returns Array of unique utility class names found
  */
-export declare function extractClasses(content: string, filePath: string, customExtractors?: Extractor[]): string[];
+export declare function extractClasses(content: string, filePath: string, customExtractors?: Extractor[], utilityPattern?: RegExp): string[];
 
 /**
  * Extract utility classes from Astro content.
  * Handles both HTML-like and JSX-like patterns.
  */
-export declare function extractFromAstro(content: string): string[];
+export declare function extractFromAstro(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from HTML-like content.
  * Handles class="..." attributes.
  */
-export declare function extractFromHTML(content: string): string[];
+export declare function extractFromHTML(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from JSX/TSX content.
  * Handles className="..." and className={...} patterns.
  */
-export declare function extractFromJSX(content: string): string[];
+export declare function extractFromJSX(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from MDX content.
  * Handles both Markdown and JSX patterns.
  */
-export declare function extractFromMDX(content: string): string[];
+export declare function extractFromMDX(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from string literals in JavaScript/TypeScript code.
@@ -140,19 +144,19 @@ export declare function extractFromMDX(content: string): string[];
  * extract the static portions. Dynamic class names cannot be statically analyzed.
  * For full coverage, use explicit string arrays or safelist patterns.
  */
-export declare function extractFromStringLiterals(content: string): string[];
+export declare function extractFromStringLiterals(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from Svelte content.
  * Handles class="...", class:directive={condition}, and class={...} patterns.
  */
-export declare function extractFromSvelte(content: string): string[];
+export declare function extractFromSvelte(content: string, pattern?: RegExp): string[];
 
 /**
  * Extract utility classes from Vue SFC content.
  * Handles class="...", :class="...", and :class="{...}" patterns.
  */
-export declare function extractFromVue(content: string): string[];
+export declare function extractFromVue(content: string, pattern?: RegExp): string[];
 
 /**
  * Custom extractor function type
@@ -163,9 +167,10 @@ export declare type Extractor = (content: string, filePath: string) => string[];
  * Extract all utility class names from a content string.
  *
  * @param content The content to search
+ * @param pattern Optional custom regex pattern (must use global flag). Defaults to UTILITY_CLASS_PATTERN.
  * @returns Array of unique utility class names found
  */
-export declare function extractUtilityClasses(content: string): string[];
+export declare function extractUtilityClasses(content: string, pattern?: RegExp): string[];
 
 /**
  * Scan result for a single file
@@ -186,9 +191,10 @@ export declare interface FileScanResult {
  *
  * @param root The Styleframe root instance
  * @param usedClasses Set of used utility class names
+ * @param selectorFn Optional custom selector function
  * @returns Array of used children (utilities are filtered, other types pass through)
  */
-export declare function filterUtilities(root: Root, usedClasses: Set<string>): Root["children"];
+export declare function filterUtilities(root: Root, usedClasses: Set<string>, selectorFn?: UtilitySelectorFn): Root["children"];
 
 /**
  * Generate a utility selector string from components.
@@ -204,9 +210,9 @@ export declare function generateUtilityClassName(name: string, value: string, mo
 /**
  * Generate the CSS selector for a utility instance.
  *
- * This mirrors the logic from @styleframe/transpiler/defaults.ts
+ * Derives the selector from the class name by adding a `.` prefix and escaping special characters.
  */
-export declare function generateUtilitySelector(options: UtilitySelectorOptions): string;
+export declare function generateUtilitySelector(options: UtilitySelectorOptions, selectorFn?: UtilitySelectorFn): string;
 
 /**
  * Get matches for arbitrary values.
@@ -292,9 +298,10 @@ export declare function parseUtilityClass(className: string): ParsedUtility | nu
  *
  * @param content Content string to scan
  * @param filePath Optional file path hint for extractor selection
+ * @param utilities Optional custom utility syntax configuration
  * @returns Array of parsed utilities
  */
-export declare function quickScan(content: string, filePath?: string): ParsedUtility[];
+export declare function quickScan(content: string, filePath?: string, utilities?: ScannerUtilitiesConfig): ParsedUtility[];
 
 /**
  * Scanner instance interface
@@ -342,6 +349,21 @@ export declare interface ScannerConfig {
     extractors?: Extractor[];
     /** Base directory for glob resolution (defaults to process.cwd()) */
     cwd?: string;
+    /** Custom utility class syntax configuration */
+    utilities?: ScannerUtilitiesConfig;
+}
+
+/**
+ * Configuration for custom utility class syntax.
+ * All fields are optional — defaults match the `_modifier:property:value` format.
+ */
+export declare interface ScannerUtilitiesConfig {
+    /** Regex pattern to extract utility class candidates from content strings. Must use the global (`g`) flag. */
+    pattern?: RegExp;
+    /** Parse a matched class name into its components (name, value, modifiers) */
+    parse?: UtilityClassParseFn;
+    /** Generate a raw class name from components (inverse of parse) */
+    selector?: UtilitySelectorFn;
 }
 
 /**
@@ -375,6 +397,12 @@ export declare interface ScanResult {
  */
 export declare const UTILITY_CLASS_PATTERN: RegExp;
 
+/**
+ * Function that parses a class name string into its structured components.
+ * Returns null if the string is not a valid utility class.
+ */
+export declare type UtilityClassParseFn = (className: string) => ParsedUtility | null;
+
 /**
  * Filter function for utilities
  */
@@ -394,14 +422,9 @@ export declare interface UtilityMatch {
     exists: boolean;
 }
 
-/**
- * Utility selector generation options
- */
-export declare interface UtilitySelectorOptions {
-    name: string;
-    value: string;
-    modifiers: string[];
-}
+export { UtilitySelectorFn }
+
+export { UtilitySelectorOptions }
 
 /**
  * Callback type for file change events