tw-mrg 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,650 @@
+/**
+ * A class value that can be passed to tw(), twJoin(), etc.
+ * Supports strings, arrays, objects (clsx-style), and nested combinations.
+ */
+type ClassValue = string | number | bigint | boolean | null | undefined | ClassValue[] | Record<string, boolean | null | undefined>;
+/**
+ * A parsed class token representing a single Tailwind class.
+ */
+interface ClassToken {
+    /** Original class string (e.g., "hover:md:!text-red-500") */
+    raw: string;
+    /** Extracted modifiers (e.g., ["hover", "md"]) */
+    modifiers: string[];
+    /** Pre-computed sorted modifier key for conflict resolution (e.g., "hover:md") */
+    modifierKey: string;
+    /** Whether this class has an !important modifier */
+    hasImportant: boolean;
+    /** The utility part without modifiers (e.g., "text-red-500") */
+    utility: string;
+    /** The class group this belongs to, or null if unknown */
+    group: string | null;
+    /** Whether this is an arbitrary value (e.g., [color:red]) */
+    isArbitrary: boolean;
+    /** For arbitrary values, the CSS property (e.g., "color") */
+    arbitraryProperty?: string;
+    /** Specificity level for conflict resolution (higher = more specific) */
+    specificity: number;
+    /** Original position in input for stable sorting */
+    position: number;
+}
+/**
+ * Result of resolving conflicts between class tokens.
+ */
+interface ResolvedClasses {
+    /** Tokens that were kept after resolution */
+    kept: ClassToken[];
+    /** Tokens that were removed due to conflicts */
+    removed: RemovedClass[];
+}
+/**
+ * Information about a class that was removed during resolution.
+ */
+interface RemovedClass {
+    /** The removed class token */
+    token: ClassToken;
+    /** The class that overrode this one */
+    overriddenBy: ClassToken;
+    /** Reason for removal */
+    reason: string;
+}
+/**
+ * Tailwind merge mode configuration.
+ * - 'full': All Tailwind classes supported (~7KB gzipped)
+ * - 'minimal': Common classes only (~1.5KB gzipped)
+ * - false: Disable merging (just concatenate)
+ */
+type TwMergeMode = 'full' | 'minimal' | false;
+/**
+ * Configuration for createTw().
+ */
+interface TwConfig {
+    /** Tailwind prefix (e.g., "tw-") */
+    prefix?: string;
+    /** Cache size for merge results (0 to disable) */
+    cacheSize?: number;
+    /** Enable debug mode by default */
+    debug?: boolean;
+    /** Merge mode: 'full', 'minimal', or false to disable */
+    mode?: TwMergeMode;
+    /** Extensions to default configuration */
+    extend?: TwConfigExtension;
+    /** Overrides for default configuration */
+    override?: TwConfigOverride;
+}
+/**
+ * Extensions to add to the default configuration.
+ */
+interface TwConfigExtension {
+    /** Additional class groups */
+    classGroups?: Record<string, string[] | RegExp[]>;
+    /** Additional conflict mappings */
+    conflictingClassGroups?: Record<string, string[]>;
+    /** Additional prefix mappings for trie */
+    prefixes?: Record<string, {
+        groupId: string;
+        specificity?: number;
+    }>;
+}
+/**
+ * Overrides to replace parts of the default configuration.
+ */
+interface TwConfigOverride {
+    /** Replace class groups entirely */
+    classGroups?: Record<string, string[] | RegExp[]>;
+    /** Replace conflict mappings entirely */
+    conflictingClassGroups?: Record<string, string[]>;
+}
+/**
+ * Configuration for twStates().
+ */
+interface TwStatesConfig<V extends VariantsSchema = VariantsSchema> {
+    /** Base classes always applied */
+    base?: ClassValue;
+    /** Variant definitions */
+    variants?: V;
+    /** Default variant values */
+    defaultVariants?: VariantProps<V>;
+    /** Compound variants for specific combinations */
+    compoundVariants?: CompoundVariant<V>[];
+}
+/**
+ * Schema for variant definitions.
+ */
+type VariantsSchema = Record<string, Record<string, ClassValue>>;
+/**
+ * Converts variant keys to their accepted prop types.
+ * Handles boolean-like keys: 'true'/'false' accept actual booleans.
+ */
+type VariantKeyToProp<K> = K extends 'true' | 'false' ? boolean | K : K;
+/**
+ * Props derived from a variants schema.
+ */
+type VariantProps<V extends VariantsSchema> = {
+    [K in keyof V]?: VariantKeyToProp<keyof V[K]> | null | undefined;
+};
+/**
+ * A compound variant that applies when multiple variants match.
+ * Uses the same prop types as VariantProps for consistency.
+ */
+type CompoundVariant<V extends VariantsSchema> = VariantProps<V> & {
+    class?: ClassValue;
+    className?: ClassValue;
+};
+/**
+ * Return type of twStates() - a function that generates class strings.
+ */
+type TwStatesResult<V extends VariantsSchema> = (props?: VariantProps<V> & {
+    class?: ClassValue;
+    className?: ClassValue;
+}) => string;
+/**
+ * Result of twDebug() for introspection.
+ */
+interface TwDebugResult {
+    /** Final merged output string */
+    output: string;
+    /** Classes that were removed due to conflicts */
+    removed: TwDebugRemovedClass[];
+    /** Classes that were kept in the output */
+    kept: TwDebugKeptClass[];
+}
+/**
+ * Information about a removed class in debug output.
+ */
+interface TwDebugRemovedClass {
+    /** The class that was removed */
+    class: string;
+    /** Reason for removal */
+    reason: string;
+    /** The class that caused this to be removed */
+    conflictsWith: string;
+}
+/**
+ * Information about a kept class in debug output.
+ */
+interface TwDebugKeptClass {
+    /** The class that was kept */
+    class: string;
+    /** The group it belongs to, or null if unknown */
+    group: string | null;
+}
+/**
+ * Interface for the LRU cache.
+ */
+interface Cache<K, V> {
+    /** Get a value from the cache */
+    get(key: K): V | undefined;
+    /** Set a value in the cache */
+    set(key: K, value: V): void;
+    /** Check if a key exists */
+    has(key: K): boolean;
+    /** Clear all entries */
+    clear(): void;
+    /** Current number of entries */
+    readonly size: number;
+}
+
+declare function tw(...inputs: ClassValue[]): string;
+
+/**
+ * Joins class values without conflict resolution (clsx-style).
+ * Faster than `tw()` when conflicts don't need resolving.
+ *
+ * @example
+ * twJoin('base', isActive && 'active', { hidden: isHidden })
+ * twJoin('p-4', 'p-8') // => 'p-4 p-8' (both preserved, unlike tw)
+ */
+declare function twJoin(...inputs: ClassValue[]): string;
+
+declare function twPrefix(modifier: string, classes: string): string;
+declare function twPrefix(modifierMap: Record<string, string>): string;
+
+/**
+ * Creates a variant-based styling function (CVA-like) integrated with tw().
+ *
+ * @example
+ * const button = twStates({
+ *   base: 'px-4 py-2 rounded',
+ *   variants: {
+ *     variant: { primary: 'bg-blue-500', secondary: 'bg-gray-200' },
+ *     size: { sm: 'text-sm', lg: 'text-lg' },
+ *   },
+ *   defaultVariants: { variant: 'primary', size: 'sm' },
+ * })
+ *
+ * button() // uses defaults
+ * button({ variant: 'secondary', size: 'lg', className: 'mt-4' })
+ */
+declare function twStates<V extends VariantsSchema>(config: TwStatesConfig<V>): TwStatesResult<V>;
+
+/**
+ * Returns detailed information about class merging decisions.
+ * Useful for debugging why classes were removed or kept.
+ *
+ * Unlike `tw()`, this function does not cache results and provides
+ * full information about the resolution process.
+ *
+ * @param inputs - Class strings, objects, arrays, or falsy values
+ * @returns Debug result with output, removed, and kept information
+ *
+ * @example
+ * ```tsx
+ * const result = twDebug('p-4 px-2 p-8')
+ * // => {
+ * //   output: 'px-2 p-8',
+ * //   removed: [
+ * //     { class: 'p-4', reason: 'overridden by p-8', conflictsWith: 'p-8' }
+ * //   ],
+ * //   kept: [
+ * //     { class: 'px-2', group: 'padding-x' },
+ * //     { class: 'p-8', group: 'padding' }
+ * //   ]
+ * // }
+ *
+ * // Check why a class was removed
+ * const { removed } = twDebug('text-sm text-lg text-red-500')
+ * removed.forEach(r => console.log(`${r.class} was ${r.reason}`))
+ *
+ * // Inspect group assignments
+ * const { kept } = twDebug('hover:bg-blue-500 focus:ring-2')
+ * kept.forEach(k => console.log(`${k.class} -> ${k.group}`))
+ * ```
+ */
+declare function twDebug(...inputs: ClassValue[]): TwDebugResult;
+
+/**
+ * Creates a customized tw function with extended or overridden configuration.
+ *
+ * Use this when you need to:
+ * - Add custom class groups for your design system
+ * - Change conflict resolution behavior
+ * - Add a Tailwind prefix
+ * - Adjust cache size
+ * - Use minimal mode for smaller bundle
+ *
+ * @param config - Configuration options
+ * @returns A customized tw function
+ *
+ * @example
+ * ```tsx
+ * // Add custom class groups
+ * const tw = createTw({
+ *   extend: {
+ *     classGroups: {
+ *       'custom-size': ['size-xs', 'size-sm', 'size-md', 'size-lg', 'size-xl'],
+ *     },
+ *   },
+ * })
+ *
+ * tw('size-sm size-lg') // => 'size-lg'
+ *
+ * // Use minimal mode for smaller bundle
+ * const tw = createTw({
+ *   mode: 'minimal',
+ * })
+ *
+ * // With Tailwind prefix
+ * const tw = createTw({
+ *   prefix: 'tw-',
+ * })
+ *
+ * tw('tw-p-4 tw-p-8') // => 'tw-p-8'
+ *
+ * // Disable caching
+ * const tw = createTw({
+ *   cacheSize: 0,
+ * })
+ *
+ * // Disable merging entirely (just join classes)
+ * const tw = createTw({
+ *   mode: false,
+ * })
+ * ```
+ */
+declare function createTw(config?: TwConfig): (...inputs: ClassValue[]) => string;
+
+/**
+ * Specificity levels for composite class handling.
+ * Higher numbers = more specific = won't be overridden by lower.
+ */
+declare const SPECIFICITY: {
+    /** All sides (p-4, m-4, rounded) */
+    readonly ALL: 1;
+    /** Axis (px-4, my-4, rounded-t) */
+    readonly AXIS: 2;
+    /** Single side (pt-4, mr-4, rounded-tl) */
+    readonly SIDE: 3;
+    /** Arbitrary values are highly specific */
+    readonly ARBITRARY: 10;
+};
+/**
+ * A prefix entry for the trie-based classifier.
+ */
+interface PrefixEntry {
+    /** The group ID this prefix maps to */
+    groupId: string;
+    /** Specificity level for this prefix */
+    specificity: number;
+}
+/**
+ * Conflict mapping from a group ID to groups it overrides.
+ */
+type ConflictMap = Record<string, string[]>;
+/**
+ * A complete class group configuration.
+ */
+interface ClassGroupConfig {
+    /** Prefix-to-group mappings for trie lookup */
+    prefixes: Record<string, PrefixEntry>;
+    /** Exact match mappings for standalone classes */
+    exactMatches: Record<string, PrefixEntry>;
+    /** Regex patterns for complex matching (fallback) */
+    patterns: Array<{
+        pattern: RegExp;
+        groupId: string;
+        specificity: number;
+    }>;
+    /** Conflict mappings */
+    conflicts: ConflictMap;
+}
+
+/**
+ * Sets the merge mode and reinitializes the classifier.
+ */
+declare function setMergeMode(mode: TwMergeMode): void;
+/**
+ * Classifies a utility class into a group and returns its specificity.
+ *
+ * @param utility - The utility class (without modifiers)
+ * @returns The group ID (or null) and specificity level
+ */
+declare function classifyClass(utility: string): {
+    group: string | null;
+    specificity: number;
+};
+/**
+ * Gets the groups that a given group conflicts with.
+ *
+ * @param groupId - The group ID to check
+ * @returns Array of conflicting group IDs
+ */
+declare function getConflictingGroups(groupId: string): string[];
+/**
+ * Gets the current merge mode.
+ */
+declare function getMergeMode(): TwMergeMode;
+/**
+ * Resets the classifier to default state (Useful for testing).
+ */
+declare function resetClassifier(): void;
+
+/**
+ * CSS Generator using Tailwind's design system.
+ * Works with any Tailwind v4 project - no config required.
+ */
+interface CSSGeneratorOptions {
+    /**
+     * Custom CSS to initialize the design system with.
+     * Defaults to '@import "tailwindcss";' which includes full default theme.
+     */
+    css?: string;
+}
+/**
+ * Initialize the CSS generator.
+ * Call once at app startup before using twPrefix().
+ *
+ * @example
+ * // Basic usage (uses Tailwind defaults)
+ * await initCSSGenerator()
+ *
+ * @example
+ * // With custom theme
+ * await initCSSGenerator({
+ *   css: `
+ *     @import "tailwindcss";
+ *     @theme {
+ *       --color-brand: #ff6600;
+ *     }
+ *   `
+ * })
+ */
+declare function initCSSGenerator(options?: CSSGeneratorOptions): Promise<void>;
+/** Generate CSS for a single Tailwind class. Returns null if invalid or uninitialized. */
+declare function generateCSS(className: string): string | null;
+/** Generate CSS for multiple classes at once (more efficient than repeated generateCSS calls). */
+declare function generateCSSBatch(classNames: string[]): (string | null)[];
+declare function isInitialized(): boolean;
+/** Get a theme value by path (e.g., '--color-red-500' → 'oklch(63.7% 0.237 25.331)'). */
+declare function getThemeValue(path: string): string | undefined;
+/**
+ * Validates if a class is a valid Tailwind utility.
+ * Returns true if the class produces CSS output.
+ *
+ * @example
+ * isValidClass('p-4') // => true
+ * isValidClass('invalid-class') // => false
+ */
+declare function isValidClass(className: string): boolean;
+/**
+ * Validates multiple classes at once.
+ * Returns an array of booleans indicating validity.
+ *
+ * @example
+ * validateClasses(['p-4', 'invalid', 'm-2']) // => [true, false, true]
+ */
+declare function validateClasses(classNames: string[]): boolean[];
+/**
+ * Gets the sort order for classes (useful for deterministic ordering).
+ * Returns null for invalid classes.
+ *
+ * @example
+ * getClassOrder(['p-4', 'm-2']) // => [['p-4', 123n], ['m-2', 456n]]
+ */
+declare function getClassOrder(classNames: string[]): [string, bigint | null][];
+/**
+ * Canonicalizes classes by collapsing redundant utilities.
+ * For example, mt-2 mr-2 mb-2 ml-2 → m-2
+ *
+ * Note: Requires the CSS generator to be initialized.
+ *
+ * @example
+ * canonicalizeClasses(['mt-2', 'mr-2', 'mb-2', 'ml-2']) // => ['m-2']
+ */
+declare function canonicalizeClasses(classNames: string[]): string[];
+
+/** Error handler for CSS injection failures */
+type StyleInjectorErrorHandler = (error: Error, context: string) => void;
+/**
+ * Sets a custom error handler for CSS injection failures.
+ * Useful for debugging when CSS injection silently fails.
+ *
+ * @param handler - Error handler function, or null to disable
+ *
+ * @example
+ * ```ts
+ * setStyleInjectorErrorHandler((error, context) => {
+ *   console.warn(`CSS injection failed in ${context}:`, error)
+ * })
+ * ```
+ */
+declare function setStyleInjectorErrorHandler(handler: StyleInjectorErrorHandler | null): void;
+declare function getStyleElement(): HTMLStyleElement | null;
+/**
+ * Injects a CSS rule for a class.
+ * Uses insertRule for better performance when available.
+ */
+declare function injectCSS(className: string, cssRule: string): void;
+/**
+ * Batched injection for performance.
+ * Uses insertRule when available, falls back to textContent.
+ */
+declare function injectCSSBatch(classNames: string[], cssRules: (string | null)[]): void;
+declare function hasInjectedClass(className: string): boolean;
+declare function clearInjectedStyles(): void;
+declare function getInjectedClasses(): string[];
+
+/**
+ * Simplified LRU (Least Recently Used) cache using ES6 Map's insertion order.
+ *
+ * ES6 Maps maintain insertion order, so we can implement LRU by:
+ * - On get: delete and re-set to move item to end (most recent)
+ * - On set: add to end, delete from beginning if over capacity
+ *
+ * This is simpler than a doubly-linked list implementation and
+ * leverages highly optimized native Map operations.
+ *
+ * - get: O(1) amortized
+ * - set: O(1) amortized
+ * - has: O(1)
+ */
+declare class LRUCache<K, V> implements Cache<K, V> {
+    private cache;
+    private readonly maxSize;
+    constructor(maxSize?: number);
+    /** Gets a value, moving it to most recently used position. */
+    get(key: K): V | undefined;
+    /** Sets a value, evicting the oldest entry if at capacity. */
+    set(key: K, value: V): void;
+    has(key: K): boolean;
+    clear(): void;
+    get size(): number;
+}
+declare function clearCaches(): void;
+/**
+ * Returns current cache statistics for debugging/monitoring.
+ *
+ * @example
+ * ```ts
+ * const stats = getCacheStats()
+ * console.log(`Parse cache: ${stats.parseSize}, Merge cache: ${stats.mergeSize}`)
+ * ```
+ */
+declare function getCacheStats(): {
+    parseSize: number;
+    mergeSize: number;
+};
+
+/**
+ * Flattens ClassValue inputs into a single string.
+ * Handles strings, arrays, objects, and nested combinations.
+ *
+ * @example
+ * ```ts
+ * flattenClassValue('a b c') // => 'a b c'
+ * flattenClassValue(['a', 'b']) // => 'a b'
+ * flattenClassValue({ a: true, b: false }) // => 'a'
+ * flattenClassValue(['a', { b: true }, ['c', 'd']]) // => 'a b c d'
+ * ```
+ */
+declare function flattenClassValue(value: ClassValue): string;
+/**
+ * Flattens multiple ClassValue inputs into a single string.
+ *
+ * @param inputs - ClassValue inputs to flatten
+ * @returns Combined class string
+ */
+declare function flattenClassValues(...inputs: ClassValue[]): string;
+/**
+ * Splits a class string into individual class names.
+ * Handles whitespace and filters empty strings.
+ *
+ * @param classString - The class string to split
+ * @returns Array of individual class names
+ */
+declare function splitClasses(classString: string): string[];
+/**
+ * Extracts modifiers and !important flag from a class name.
+ * Modifiers are colon-separated prefixes like "hover:", "md:", etc.
+ * !important can appear as "!" modifier or "!" prefix on utility.
+ *
+ * @example
+ * ```ts
+ * extractModifiers('hover:md:text-red-500')
+ * // => { modifiers: ['hover', 'md'], utility: 'text-red-500', hasImportant: false }
+ *
+ * extractModifiers('hover:!bg-red-500')
+ * // => { modifiers: ['hover'], utility: 'bg-red-500', hasImportant: true }
+ *
+ * extractModifiers('!p-4')
+ * // => { modifiers: [], utility: 'p-4', hasImportant: true }
+ * ```
+ */
+declare function extractModifiers(className: string): {
+    modifiers: string[];
+    utility: string;
+    hasImportant: boolean;
+};
+/**
+ * Base parsing result without classification.
+ */
+interface ParsedClass {
+    raw: string;
+    modifiers: string[];
+    modifierKey: string;
+    hasImportant: boolean;
+    utility: string;
+    utilityForClassification: string;
+    isArbitrary: boolean;
+    arbitraryProperty?: string;
+    position: number;
+}
+/**
+ * Parses a single class name without classification.
+ * Used by createTw() which does its own classification.
+ *
+ * @param className - The class name to parse
+ * @param position - Original position in the input
+ * @returns Parsed class info (without group/specificity)
+ */
+declare function parseClassBase(className: string, position: number): ParsedClass;
+/**
+ * Parses a single class name into a ClassToken.
+ * Includes classification using the global classifier.
+ *
+ * @param className - The class name to parse
+ * @param position - Original position in the input
+ * @returns Parsed ClassToken with group and specificity
+ */
+declare function parseClass(className: string, position: number): ClassToken;
+/**
+ * Parses a class string into an array of ClassTokens.
+ * Results are cached for performance.
+ *
+ * @param classString - The class string to parse
+ * @returns Array of ClassTokens
+ */
+declare function parseClasses(classString: string): ClassToken[];
+
+/** Resolves conflicts with full debug info about removed classes. */
+declare function resolveConflicts(tokens: ClassToken[]): ResolvedClasses;
+/** Resolves conflicts returning only kept tokens (faster, no debug info). */
+declare function resolveConflictsSimple(tokens: ClassToken[]): ClassToken[];
+
+/**
+ * Minimal class group configuration.
+ * Covers the most commonly used Tailwind utilities:
+ * - Layout (display, position, visibility)
+ * - Spacing (padding, margin, gap)
+ * - Sizing (width, height)
+ * - Flexbox & Grid
+ * - Typography
+ * - Colors
+ * - Borders
+ *
+ * Bundle size: ~1.5KB gzipped
+ */
+declare const minimalConfig: ClassGroupConfig;
+
+/**
+ * Full class group configuration.
+ * Covers all Tailwind CSS v4 utilities.
+ *
+ * Bundle size: ~7KB gzipped
+ *
+ * Uses lazy initialization via a Proxy to defer computation until first access,
+ * reducing startup time when the full config is imported but not immediately used.
+ */
+declare const fullConfig: ClassGroupConfig;
+
+export { type CSSGeneratorOptions, type ClassGroupConfig, type ClassValue, type CompoundVariant, type ConflictMap, LRUCache, type ParsedClass, type PrefixEntry, SPECIFICITY, type TwConfig, type TwConfigExtension, type TwConfigOverride, type TwDebugKeptClass, type TwDebugRemovedClass, type TwDebugResult, type TwMergeMode, type TwStatesConfig, type TwStatesResult, type VariantProps, type VariantsSchema, canonicalizeClasses, classifyClass, clearCaches, clearInjectedStyles, createTw, extractModifiers, flattenClassValue, flattenClassValues, fullConfig, generateCSS, generateCSSBatch, getCacheStats, getClassOrder, getConflictingGroups, getInjectedClasses, getMergeMode, getStyleElement, getThemeValue, hasInjectedClass, initCSSGenerator, injectCSS, injectCSSBatch, isInitialized, isValidClass, minimalConfig, parseClass, parseClassBase, parseClasses, resetClassifier, resolveConflicts, resolveConflictsSimple, setMergeMode, setStyleInjectorErrorHandler, splitClasses, tw, twDebug, twJoin, twPrefix, twStates, validateClasses };