arto
Version:
Arto is a flexible and type-safe class name management library for building scalable UIs with variants, states, and conditional styling.
259 lines • 10.2 kB
TypeScript
import { ArtoConfig, VariantValue } from './types';
import { Plugin } from './plugin-interface';
/**
* A builder that organizes plugins by stage ('before', 'core', 'after'),
* collects classes into buckets, then merges them in a final array (no dedup).
*
* **Build Sequence**:
* 1) Run 'before' plugins (in ascending `order`)
* 2) Run 'core' plugins
* 3) Execute any post-core callbacks
* 4) Run 'after' plugins
* 5) Execute any final build callbacks
* 6) Combine all class buckets into the final list
*
* @template TVariants - A record of variant keys & possible values.
* @template TStates - A union of valid state names.
* @template TContext - Optional context type for plugins or logic.
*/
export declare class ClassNameBuilder<TVariants extends Record<string, VariantValue> = Record<string, VariantValue>, TStates extends string = string, TContext = unknown> {
private artoConfig;
private selectedVariants;
private activeStates;
private context?;
/**
* Base class names, applied before any variant or state classes.
*/
private baseClassNames;
/**
* A mapping of each variant key to an array of classes. These classes are applied
* after `baseClassNames` and can be overridden by state-level classes or subsequent rules.
*/
private variantClassNames;
/**
* A nested mapping of `[variantKey][stateName] => string[]` for variant-level states.
* Classes here are applied after standard variant classes if the corresponding state is active.
*/
private variantStateClassNames;
/**
* A mapping of global state names to an array of classes. Applied if the state is active.
* These classes override or supplement existing classes from base or variants.
*/
private globalStateClassNames;
/**
* A set of callbacks to run **after** 'core' plugins but **before** 'after' plugins.
*/
private postCoreCallbacks;
/**
* A new set of callbacks that run truly "post-build," i.e. after the 'after' stage.
*/
private finalBuildCallbacks;
/**
* An array of all plugins (local + global + internal), unsorted by default. Sorting
* occurs by stage -> order when applying them sequentially in `build()`.
*/
private readonly allPlugins;
/**
* Maps each plugin stage to a numeric value used for sorting:
* - 'before' -> 0
* - 'core' -> 1
* - 'after' -> 2
*/
private static stagePriority;
/**
* @param artoConfig - The main Arto configuration object describing base classes, variants, states, and rules.
* @param selectedVariants - The user-selected variants. Keys match `TVariants`, values are chosen at runtime.
* @param activeStates - A set of currently active states (e.g., 'disabled').
* @param context - An optional context object (e.g., user data, environment).
* @param plugins - A list of plugins that modify or extend class building logic.
*/
constructor(artoConfig: Readonly<ArtoConfig<TVariants, TStates, TContext>>, selectedVariants: TVariants, activeStates: Set<TStates>, context?: TContext | undefined, plugins?: Plugin<TVariants, TStates, TContext>[]);
/**
* Builds and returns the final array of class names by:
* 1) Running 'before' plugins.
* 2) Running 'core' plugins.
* 3) Executing any `postCoreCallbacks`.
* 4) Running 'after' plugins.
* 5) Executing any `finalBuildCallbacks`
* 6) Combining and returning all class buckets.
*
* @returns The combined list of classes (no deduplication), typically joined by spaces.
*
* @example
* ```ts
* const builder = new ClassNameBuilder(config, { size: 'small' }, new Set(['disabled']), ...)
* const classArray = builder.build()
* // => ['base-class', 'small-class', 'disabled-class']
* ```
*/
build(): string[];
/**
* Adds a callback to run immediately after 'core' plugins but before 'after' plugins.
*
* @param callback - A function to run after the core logic has completed.
*
* @example
* ```ts
* builder.addPostCoreCallback(() => {
* console.log('Classes have been generated!')
* })
* ```
*/
addPostCoreCallback(callback: () => void): void;
/**
* Adds a callback to run after all plugins have completed, including 'after' stage.
*
* @param callback - A function to run after all plugins have completed.
*
* @example
* ```ts
* builder.addFinalBuildCallback(() => {
* console.log('All classes have been generated!')
* })
* ```
*/
addFinalBuildCallback(callback: () => void): void;
/**
* Appends an array of classes to the base bucket.
*
* @param classNames - An array of class names (e.g. `['btn', 'btn-primary']`).
*/
addBaseClasses(classNames: string[]): void;
/**
* Clears all previously added base classes.
*/
clearBaseClasses(): void;
/**
* Retrieves a copy of the current base classes for inspection or debugging.
*
* @returns A new array containing all base class names.
*/
getBaseClasses(): string[];
/**
* Appends classes for a specific variant key.
*
* @param variantKey - The name of the variant (e.g. `'size'`).
* @param classNames - The classes to add (e.g. `['text-sm', 'py-1']`).
*/
addVariantClasses(variantKey: keyof TVariants, classNames: string[]): void;
/**
* Replaces all classes for the given variant with a new array of classes.
*
* @param variantKey - The variant name to replace.
* @param classNames - The new classes.
*/
replaceVariantClasses(variantKey: keyof TVariants, classNames: string[]): void;
/**
* Clears any existing classes assigned to a given variant.
*
* @param variantKey - The variant name.
*/
clearVariantClasses(variantKey: keyof TVariants): void;
/**
* Retrieves a read-only copy of the full map of variant classes.
*
* @returns An object with each variant key mapped to an array of class names.
*/
getVariantClassMap(): Readonly<Record<keyof TVariants, string[]>>;
/**
* Adds classes to the global state bucket. If `state` is active, these classes
* will be appended to the final output (after variant classes).
*
* @param state - The state name (e.g. `'disabled'`).
* @param classNames - The classes to add (e.g. `['opacity-50', 'pointer-events-none']`).
*/
addGlobalStateClasses(state: TStates, classNames: string[]): void;
/**
* Replaces existing global state classes for the given `state` with a new array.
*
* @param state - The state name.
* @param classNames - The new array of classes.
*/
replaceGlobalStateClasses(state: TStates, classNames: string[]): void;
/**
* Clears any global state classes registered under the specified `state`.
*
* @param state - The state name to clear (e.g., 'hover').
*/
clearGlobalStateClasses(state: TStates): void;
/**
* Returns a copy of the classes for a specific global state, for inspection or debugging.
*
* @param state - The state name.
* @returns An array of class names, which may be empty if none are set.
*/
getGlobalStateClassesFor(state: TStates): string[];
/**
* Appends classes for a combination of variant key + state name.
* These will only be applied if the corresponding variant value is selected and the state is active.
*
* @param variantKey - The variant key (e.g. 'size').
* @param state - The state name (e.g. 'disabled').
* @param classNames - An array of classes to add.
*/
addVariantStateClasses(variantKey: keyof TVariants, state: TStates, classNames: string[]): void;
/**
* Replaces all classes for a specific `(variantKey, state)` pair.
*
* @param variantKey - The variant key.
* @param state - The state name.
* @param classNames - The new array of classes.
*/
replaceVariantStateClasses(variantKey: keyof TVariants, state: TStates, classNames: string[]): void;
/**
* Clears all classes for a specific `(variantKey, state)` pair.
*
* @param variantKey - The variant key to clear.
* @param state - The state name to clear.
*/
clearVariantStateClasses(variantKey: keyof TVariants, state: TStates): void;
/**
* Retrieves classes for a given `(variantKey, state)` combination.
*
* @param variantKey - The variant key (e.g. 'color').
* @param state - The state name (e.g. 'hover').
* @returns An array of classes if they exist; otherwise an empty array.
*/
getVariantStateClasses(variantKey: keyof TVariants, state: TStates): string[];
/**
* Returns the original Arto configuration provided to this builder.
*
* @returns A readonly version of `ArtoConfig`.
*/
getArtoConfig(): Readonly<ArtoConfig<TVariants, TStates, TContext>>;
/**
* Retrieves the user-selected variants (merged with any default variants).
*
* @returns An object mapping each variant key to the selected value.
*/
getSelectedVariants(): TVariants;
/**
* Replaces the current selection of variants with a new mapping.
*
* @param variants - The new variant key/value mapping.
*/
setSelectedVariants(variants: TVariants): void;
/**
* Retrieves the set of currently active states.
*
* @returns A `Set` of active state names.
*/
getActiveStates(): Set<TStates>;
/**
* Replaces the set of active states.
*
* @param states - The new set of states (e.g. `new Set(['disabled', 'hover'])`).
*/
setActiveStates(states: Set<TStates>): void;
/**
* Returns the optional context object, if any, used by plugins or class generation callbacks.
*/
getContext(): TContext | undefined;
/**
* Retrieves all classes from base, variants, global states, and variant-level states.
*
* @returns An array containing all classes.
*/
getAllClasses(): string[];
}
//# sourceMappingURL=classname-builder.d.ts.map