@cssxio/compiler 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,356 @@
+/** Style groups that one utility writes and clears. */
+interface UtilityConflictRecord {
+    /** Variant and importance scope where this record applies. */
+    readonly scope: string;
+    /** Semantic write group owned by the utility. */
+    readonly group: string;
+    /** Groups cleared when this utility is applied later. */
+    readonly conflicts: readonly string[];
+}
+/**
+ * A utility record created by the compiler.
+ *
+ * A null class name clears related style groups without adding CSS.
+ */
+type CompiledUtility = readonly [
+    className: string | null,
+    scope: string,
+    group: string,
+    ...conflicts: readonly string[]
+];
+/** A compiled style that contains utility records. */
+interface CompiledStyle {
+    /** Marker used to identify a compiled CSSX style. */
+    readonly $$css: 2;
+    /** Composite class used when this style can be applied as one unit. */
+    readonly c: string;
+    /** Ordered utility records used by the runtime merge operation. */
+    readonly _: readonly CompiledUtility[];
+}
+/** A compiled style map and its generated class names. */
+interface CompiledStyleRecordMap {
+    /** Compiled styles keyed by input style name. */
+    readonly styles: Readonly<Record<string, CompiledStyle>>;
+    /** Generated classes keyed by utility candidate. */
+    readonly classes: Readonly<Record<string, string>>;
+    /** Source candidates keyed by input style name. */
+    readonly candidates: Readonly<Record<string, readonly string[]>>;
+    /** Composite class names keyed by input style name. */
+    readonly classNames: Readonly<Record<string, string>>;
+    /** Winning atomic classes keyed by composite class name. */
+    readonly composites: Readonly<Record<string, readonly string[]>>;
+}
+/** Several compiled style maps that share generated class names. */
+interface CompiledStyleRecordMaps {
+    /** Compiled style maps keyed by map name. */
+    readonly styleMaps: Readonly<Record<string, CompiledStyleRecordMap>>;
+    /** Generated classes shared by every map. */
+    readonly classes: Readonly<Record<string, string>>;
+    /** Winning atomic classes shared by every composite class. */
+    readonly composites: Readonly<Record<string, readonly string[]>>;
+}
+/** Options for creating compiled style records. */
+interface StyleCompilerOptions {
+    /** CSS theme input used when generating class names. */
+    readonly theme?: string;
+    /** Options that control generated atomic and composite class names. */
+    readonly className?: ClassNameOptions;
+    /** Shared allocator used to keep class names unique across compiler calls. */
+    readonly classNameAllocator?: ClassNameAllocator;
+    /** Controls how aggressively static styles share generated class fragments. */
+    readonly reusabilityBudget?: ReusabilityBudget;
+}
+/** Percentage of winning atomic occurrences eligible for reusable fragments. */
+type ReusabilityBudget = number | 'auto';
+/** Options that control generated CSS class names. */
+interface ClassNameOptions {
+    /** Naming algorithm. Defaults to `serial`; `random` is a stable content hash. */
+    readonly variant?: 'random' | 'serial';
+    /** Text prepended to every generated class. Defaults to `s`. */
+    readonly prefix?: string;
+    /** Text appended to every generated class. Defaults to `x`. */
+    readonly suffix?: string;
+    /** Length of the hash fragment when `variant` is `random`. */
+    readonly length?: number;
+}
+/** Stateful allocator that keeps generated classes unique across compiler calls. */
+interface ClassNameAllocator {
+    /** Allocates one unique class for every supplied identity. */
+    allocate(identities: readonly string[]): ReadonlyMap<string, string>;
+    /** Reserves class names that were allocated outside this allocator. */
+    reserve(classNames: readonly string[]): void;
+}
+/**
+ * Finds the style groups used by one static utility.
+ *
+ * @param candidate A static utility string.
+ * @returns Its style groups, or null when CSSX does not support it.
+ */
+declare function classifyUtility(candidate: string): UtilityConflictRecord | null;
+/**
+ * Compiles one static style map to records for the runtime.
+ *
+ * @param input Style names and their utility strings.
+ * @param options Compiler options.
+ * @returns The compiled styles, class names, and source candidates.
+ */
+declare function compileStyleRecords(input: Readonly<Record<string, string>>, options?: StyleCompilerOptions): CompiledStyleRecordMap;
+/**
+ * Compiles several static style maps with shared class names.
+ *
+ * @param inputs Map names and their utility maps.
+ * @param options Compiler options.
+ * @returns The compiled maps and their shared class names.
+ */
+declare function compileStyleRecordMaps(inputs: Readonly<Record<string, Readonly<Record<string, string>>>>, options?: StyleCompilerOptions): CompiledStyleRecordMaps;
+/**
+ * Assigns unique names to identities in one compilation namespace.
+ *
+ * Serial names use a compact case-sensitive base-62 counter. Random names use
+ * a stable hash and deterministic probing, so choosing a shorter hash cannot
+ * silently collide.
+ *
+ * @param options User-supplied naming options.
+ * @returns A stateful class-name allocator.
+ */
+declare function createClassNameAllocator(options?: ClassNameOptions): ClassNameAllocator;
+/**
+ * Merges compiled styles from left to right.
+ *
+ * @param styles Compiled styles to merge.
+ * @returns The final class string.
+ */
+declare function mergeCompiledStyles(styles: readonly CompiledStyle[]): string;
+/** A composite class and the atomic classes that implement it. */
+interface StyleComposition {
+    /** Stable class for the complete reduced style. */
+    readonly className: string;
+    /** Winning atomic classes in their source order. */
+    readonly atomicClasses: readonly string[];
+}
+/**
+ * Creates one composite class for a list of compiled styles.
+ *
+ * @param styles Compiled styles to compose from left to right.
+ * @param classNameAllocator Optional allocator shared with the styles' compilation.
+ * @returns The composite class and its winning atomic classes.
+ */
+declare function composeCompiledStyles(styles: readonly CompiledStyle[], classNameAllocator?: ClassNameAllocator): StyleComposition;
+
+/** One CSS declaration emitted by a utility recipe. */
+interface UtilityDeclaration {
+    /** CSS property to emit. */
+    readonly property: string;
+    /** CSS value to emit. */
+    value: string;
+    /** Optional selector suffix shared by declarations in one atom. */
+    readonly selectorSuffix?: string;
+    /** Optional at-rule that wraps this declaration. */
+    readonly atRule?: string;
+    /** Semantic write group used when compiled styles are merged. */
+    readonly semanticGroup?: string;
+    /** Semantic groups cleared before this declaration is applied. */
+    readonly semanticConflicts?: readonly string[];
+}
+
+/** Resolved theme data used while compiling utilities. */
+interface CssxTheme {
+    /** Token values, including default values and user overrides. */
+    readonly tokens: Readonly<Record<string, string>>;
+    /** Complete keyframe rules keyed by animation name. */
+    readonly keyframes: Readonly<Record<string, string>>;
+    /** Controls whether utility values are inlined or emitted as variables. */
+    readonly mode: ThemeOutputMode;
+    /** Optional variable prefix used by reference output. */
+    readonly prefix: string;
+}
+/** Controls how resolved theme tokens appear in generated CSS. */
+type ThemeOutputMode = 'inline' | 'reference' | 'static';
+
+/**
+ * Parses CSSX `@theme` blocks and combines them with the built-in theme.
+ *
+ * Parsing is deliberately narrow: only top-level theme blocks, declarations,
+ * namespace resets, and validated keyframes are accepted. The result is frozen
+ * so every later compilation phase reads one stable theme snapshot.
+ *
+ * @param source Optional CSSX theme source.
+ * @returns Resolved immutable theme data.
+ */
+declare function parseTheme(source?: string): CssxTheme;
+
+/** Controls how the `dark` variant is activated. */
+type DarkMode = 'media' | 'selector';
+/** Options that affect how variants are rendered. */
+interface VariantOptions {
+    /** Activates `dark` variants with a media query or a `[data-theme=dark]` selector. */
+    readonly darkMode?: DarkMode;
+}
+
+/** CSS and metadata created from utility strings. */
+interface UtilityCompilation {
+    /** Complete generated CSS, including prefix CSS. */
+    readonly css: string;
+    /** Theme CSS and shared CSS resources. */
+    readonly prefixCss: string;
+    /** Utility CSS entries in output order. */
+    readonly entries: readonly UtilityCssEntry[];
+    /** Generated class string keyed by source candidate. */
+    readonly classes: Readonly<Record<string, string>>;
+}
+/** One utility string and its generated CSS. */
+interface UtilityCssEntry {
+    /** Source utility candidate. */
+    readonly candidate: string;
+    /** CSS emitted for this candidate and one generated class. */
+    readonly css: string;
+}
+/** Shared CSS resources needed by a utility. */
+interface UtilityRecipeResources {
+    /** Keyframe names required by the utility. */
+    readonly keyframes: readonly string[];
+    /** Custom properties that must be registered before emitting CSS. */
+    readonly properties: readonly string[];
+}
+/** Style groups written by one utility part. */
+interface UtilityWriteSet {
+    /** Semantic group written by this atom. */
+    readonly group: string;
+    /** Semantic groups cleared by this atom. */
+    readonly conflicts: readonly string[];
+}
+/** The compiled parts and metadata for one utility. */
+interface UtilityRecipe {
+    /** Source utility candidate. */
+    readonly candidate: string;
+    /** Separate declaration atoms that can receive separate class names. */
+    readonly atoms: readonly (readonly UtilityDeclaration[])[];
+    /** Shared CSS resources required by the utility. */
+    readonly resources: UtilityRecipeResources;
+    /** Semantic write behavior for each declaration atom. */
+    readonly writes: readonly UtilityWriteSet[];
+}
+/**
+ * Describes the CSS created for one utility.
+ *
+ * @param candidateSource A static utility string.
+ * @param theme The active CSSX theme.
+ * @returns Its CSS declaration groups, resources, and style groups.
+ */
+declare function describeUtilityRecipe(candidateSource: string, theme: CssxTheme): UtilityRecipe;
+/**
+ * Compiles static utility strings to CSS.
+ *
+ * @param candidates The utility strings to compile.
+ * @param className Creates class names for utility strings.
+ * @param themeCss Optional CSS theme input.
+ * @returns The generated CSS, class names, and CSS entries.
+ *
+ * The function rejects unsupported utilities, unsafe class names, and more
+ * than 50,000 utility strings.
+ */
+declare function compileUtilities(candidates: readonly string[], className: (candidate: string) => string, themeCss?: string, selectorAliases?: Readonly<Record<string, readonly string[]>>, includedClasses?: ReadonlySet<string>, variantOptions?: VariantOptions): Promise<UtilityCompilation>;
+/**
+ * Compiles utilities using their original source class names as selectors.
+ *
+ * @param candidates The utility strings to compile.
+ * @param themeCss Optional CSS theme input.
+ * @param variantOptions Options that affect variant rendering.
+ * @returns Generated CSS whose selectors match the source utility strings.
+ */
+declare function compileSourceUtilities(candidates: readonly string[], themeCss?: string, variantOptions?: VariantOptions): Promise<UtilityCompilation>;
+/**
+ * Checks that a utility has CSS for the active theme.
+ *
+ * @param candidate A static utility string.
+ * @param theme The active CSSX theme.
+ * @returns Nothing.
+ */
+declare function validateUtilityCandidate(candidate: string, theme: CssxTheme): void;
+
+/**
+ * Splits a static utility list without treating whitespace in brackets as separators.
+ *
+ * @param source Whitespace-separated utility source.
+ * @returns Individual utility candidates.
+ */
+declare function splitCandidateList(source: string): readonly string[];
+
+/** One generated class name and the CSS rule it identifies. */
+interface CssxRule {
+    /** Stable class name for this generated CSS payload. */
+    readonly className: string;
+    /** Complete CSS emitted for the class name. */
+    readonly css: string;
+}
+/** Options for compiling style maps. */
+interface CompilerOptions {
+    /** CSS theme input added to the default theme before compilation. */
+    readonly theme?: string;
+    /** Options that control generated atomic and composite class names. */
+    readonly className?: ClassNameOptions;
+    /** Shared allocator used to keep class names unique across compiler calls. */
+    readonly classNameAllocator?: ClassNameAllocator;
+    /** Controls how aggressively static styles share generated class fragments. */
+    readonly reusabilityBudget?: ReusabilityBudget;
+    /** Controls how the `dark` variant is activated. */
+    readonly darkMode?: DarkMode;
+}
+/** The output from one compiled style map. */
+interface CompileResult {
+    /** Compiled runtime styles keyed by the input style name. */
+    readonly styles: Readonly<Record<string, CompiledStyle>>;
+    /** CSS rules generated for all candidates in this input. */
+    readonly rules: readonly CssxRule[];
+    /** Generated class names keyed by source candidate. */
+    readonly classes: Readonly<Record<string, string>>;
+    /** Parsed source candidates keyed by input style name. */
+    readonly candidates: Readonly<Record<string, readonly string[]>>;
+    /** Composite class names keyed by input style name. */
+    readonly classNames: Readonly<Record<string, string>>;
+    /** Winning atomic classes keyed by composite class name. */
+    readonly composites: Readonly<Record<string, readonly string[]>>;
+}
+/** The output from several compiled style maps. */
+interface CompileMapsResult {
+    /** Compiled results keyed by the input map name. */
+    readonly styleMaps: Readonly<Record<string, CompiledStyleRecordMap>>;
+    /** Shared CSS rules generated across every input map. */
+    readonly rules: readonly CssxRule[];
+}
+/**
+ * Compiles one map of static utility strings.
+ *
+ * @param input Style names and their utility strings.
+ * @param options Compiler options.
+ * @returns The compiled styles, class names, candidates, and CSS rules.
+ *
+ * The function rejects invalid utilities and invalid theme input.
+ */
+declare function compileStyleMap(input: Readonly<Record<string, string>>, options?: CompilerOptions): Promise<CompileResult>;
+/**
+ * Compiles several style maps as one set of CSS.
+ *
+ * @param inputs Map names and their static utility maps.
+ * @param options Compiler options.
+ * @returns A compiled map for each input and the shared CSS rules.
+ *
+ * Shared resources, such as keyframes, are added once. The function rejects
+ * invalid utilities and invalid theme input.
+ */
+declare function compileStyleMaps(inputs: Readonly<Record<string, Readonly<Record<string, string>>>>, options?: CompilerOptions): Promise<CompileMapsResult>;
+/**
+ * Joins unique CSS rules in a stable order.
+ *
+ * @param rules Generated CSS rules.
+ * @param options Optional CSS layer settings.
+ * @param options.layer CSS layer that wraps the generated rules.
+ * @returns The final CSS string.
+ */
+declare function serializeCss(rules: readonly CssxRule[], options?: {
+    readonly layer?: string;
+}): string;
+/** Inverts composite-to-atom metadata for selector serialization. */
+declare function createSelectorAliases(composites: Readonly<Record<string, readonly string[]>>): Readonly<Record<string, readonly string[]>>;
+
+export { type ClassNameAllocator, type ClassNameOptions, type CompileMapsResult, type CompileResult, type CompiledStyle, type CompiledStyleRecordMap, type CompiledStyleRecordMaps, type CompiledUtility, type CompilerOptions, type CssxRule, type CssxTheme, type DarkMode, type ReusabilityBudget, type StyleCompilerOptions, type StyleComposition, type ThemeOutputMode, type UtilityCompilation, type UtilityConflictRecord, type UtilityCssEntry, type UtilityDeclaration, type UtilityRecipe, type UtilityRecipeResources, type UtilityWriteSet, classifyUtility, compileSourceUtilities, compileStyleMap, compileStyleMaps, compileStyleRecordMaps, compileStyleRecords, compileUtilities, composeCompiledStyles, createClassNameAllocator, createSelectorAliases, describeUtilityRecipe, mergeCompiledStyles, parseTheme, serializeCss, splitCandidateList, validateUtilityCandidate };