@windicss/plugin-utils/dist/index.d.ts

Common utils for building integrations of Windi CSS

import { FullConfig, Extractor, ExtractorResultDetailed } from 'windicss/types/interfaces';
import { generateCompletions } from 'windicss/utils';
import Processor from 'windicss';
import { WindiCssOptions, LoadConfigurationOptions } from '@windicss/config';
export * from '@windicss/config';
export { WindiCssOptions } from '@windicss/config';
import * as magic_string from 'magic-string';
import * as pug from 'pug';
export { Arrayable, partition, slash, toArray } from '@antfu/utils';

declare const defaultAlias: Record<string, TagNames>;
declare const preflightTags: string[];
declare const htmlTags: readonly ["html", "body", "div", "a", "abbr", "address", "area", "article", "aside", "audio", "base", "basefont", "bdo", "blink", "blockquote", "br", "button", "canvas", "caption", "center", "col", "colgroup", "command", "comment", "datalist", "dd", "del", "details", "dir", "dl", "dt", "embed", "fieldset", "figure", "b", "big", "i", "small", "tt", "font", "footer", "form", "frame", "frameset", "head", "header", "hgroup", "h1", "h2", "h3", "h4", "h5", "h6", "hr", "isindex", "iframe", "ilayer", "img", "input", "ins", "keygen", "keygen", "label", "layer", "legend", "li", "link", "map", "mark", "marquee", "menu", "meta", "meter", "multicol", "nav", "nobr", "noembed", "noframes", "noscript", "object", "ol", "optgroup", "option", "output", "p", "param", "cite", "code", "dfn", "em", "kbd", "samp", "strong", "var", "plaintext", "pre", "progress", "q", "ruby", "script", "section", "select", "spacer", "span", "s", "strike", "style", "sub", "sup", "svg", "table", "tbody", "td", "textarea", "tfoot", "th", "thead", "time", "title", "tr", "u", "ul", "video", "wbr", "wbr", "xmp"];
type TagNames = (typeof htmlTags)[number];

declare function defineConfig(config: FullConfig): FullConfig;

interface TransformerOptions {
    include?: RegExp[];
}
type TransformerFunction = (code: string, id: string) => string | undefined | null;
type Transformer<T extends TransformerOptions> = (options?: T) => TransformerFunction;
declare function transformGroups(code: string, sourcemap?: boolean): {
    code: string;
    map: magic_string.SourceMap | undefined;
} | null;
declare function buildAliasTransformer(alias?: Record<string, string>): (code: string, sourcemap?: boolean) => {
    code: string;
    map: magic_string.SourceMap | undefined;
} | null;

interface UserOptions {
    /**
     * Options for windicss/tailwindcss.
     * Also accepts string as config file path.
     *
     * @default auto searching for `windi.config.ts` / `tailwind.config.js`
     */
    config?: WindiCssOptions | string;
    /**
     * A list of filename of paths to search of config files
     */
    configFiles?: string[];
    /**
     * Safe class names to be always included.
     *
     * @deprecated define this field in the windicss.config.ts instead
     */
    safelist?: string | (string | string[])[];
    /**
     * Class names to be always excluded.
     *
     * @deprecated define this field in the windicss.config.ts instead
     */
    blocklist?: string | (string | string[])[];
    /**
     * Enabled windicss preflight (a.k.a TailwindCSS style reset)
     *
     * @deprecated define this field in the windicss.config.ts instead
     * @default true
     */
    preflight?: boolean | {
        /**
         * Enable all the preflight regardless the template
         *
         * @deprecated define this field in the windicss.config.ts instead
         */
        enableAll?: boolean;
        /**
         * Enable all the preflight regardless the template
         *
         * @deprecated define this field in the windicss.config.ts instead
         */
        includeAll?: boolean;
        /**
         * Safelist to always included
         *
         * @deprecated define this field in the windicss.config.ts instead
         */
        safelist?: string | (string | string[])[];
        /**
         * Blocklist to always excluded
         *
         * @deprecated define this field in the windicss.config.ts instead
         */
        blocklist?: string | (string | string[])[];
        /**
          * Alias for resolving preflight
          */
        alias?: Record<string, TagNames>;
        /**
         * @default true
         * @deprecated define this field in the windicss.config.ts instead
         */
        includeBase?: boolean;
        /**
         * @default true
         * @deprecated define this field in the windicss.config.ts instead
         */
        includeGlobal?: boolean;
        /**
         * @default true
         * @deprecated define this field in the windicss.config.ts instead
         */
        includePlugin?: boolean;
    };
    /**
      * File paths will be resolved against this directory.
      *
      * @default process.cwd
      * @internal
      */
    root?: string;
    /**
     * Scan the files and extract the usage
     *
     * @default true
     */
    scan?: boolean | {
        /**
         * Auto scan on startup
         *
         * @default true
         */
        runOnStartup?: boolean;
        /**
         * Directories to search for classnames
         *
         * @default 'src'
         * @deprecated use `extract.include` in the windicss.config.ts instead
         */
        dirs?: string | string[];
        /**
         * File extension to search for classnames
         *
         * @default 'html', 'vue', 'md', 'mdx', 'pug', 'jsx', 'tsx', 'svelte', 'js', 'ts'
         * @deprecated use `extract.include` in the windicss.config.ts instead
         */
        fileExtensions?: string | string[];
        /**
         * Exclude globs
         *
         * @default []
         */
        exclude?: string | string[];
        /**
         * Include globs
         *
         * @default []
         */
        include?: string | string[];
        /**
         * Transformers to apply before doing extraction
         *
         * @default []
         */
        transformers?: TransformerFunction[];
    };
    /**
     * Transform CSS for `@apply` directive
     *
     * @default true
     */
    transformCSS?: boolean | 'pre' | 'post';
    /**
     * Transform groups like `hover:(bg-gray-100 font-medium)`
     *
     * @default true
     */
    transformGroups?: boolean;
    /**
     * Sort the genrate utilities
     *
     * @default true
     */
    sortUtilities?: boolean;
    /**
     * Callback before classes css generated
     */
    onBeforeGenerate?: (ctx: {
        classesPending: Set<string>;
        tagsPending: Set<string>;
    }) => void;
    /**
     * Callback when classes and/or tags are generated/changed
     */
    onGenerated?: (ctx: {
        classes: Set<string>;
        tags: Set<string>;
    }) => void;
    /**
     * Callback when the options are resolved. These are the plugin options and contain the windi config
     */
    onOptionsResolved?: (options: ResolvedOptions) => ResolvedOptions | void | Promise<ResolvedOptions | void>;
    /**
     * Callback when the windi config is resolved. Not to be confused with the options which are the top level way to
     * configure the util package
     */
    onConfigResolved?: (config: WindiCssOptions, configFilePath?: string) => WindiCssOptions | void | Promise<WindiCssOptions | void>;
    /**
     * Callback when the utils is initialized
     */
    onInitialized?: (utils: WindiPluginUtils) => void;
}
type WindiPluginUtilsOptions = Omit<LoadConfigurationOptions, 'config' | 'configFiles'> & {
    /**
     * Reuse existing plugin instance
     */
    utils?: WindiPluginUtils;
};
interface ResolvedOptions {
    config: WindiCssOptions;
    configFilePath: string | undefined;
    enableScan: boolean;
    enablePreflight: boolean;
    transformCSS: boolean | 'pre' | 'auto' | 'post';
    transformGroups: boolean;
    scanOptions: {
        fileExtensions: string[];
        dirs: string[];
        exclude: string[];
        include: string[];
        runOnStartup: boolean;
        transformers: TransformerFunction[];
        extractors: Extractor[];
        extraTransformTargets: {
            css: (string | ((path: string) => boolean))[];
            detect: (string | ((path: string) => boolean))[];
        };
    };
    preflightOptions: {
        includeBase: boolean;
        includeGlobal: boolean;
        includePlugin: boolean;
        includeAll: boolean;
        /**
         * @deprecated use includeAll
         */
        enableAll: boolean;
        safelist: Set<string>;
        blocklist: Set<string>;
        alias: Record<string, string>;
    };
    root: string;
    sortUtilities: boolean;
    safelist: Set<string>;
    blocklist: Set<string>;
    onBeforeGenerate: UserOptions['onBeforeGenerate'];
    onGenerated: UserOptions['onGenerated'];
    onConfigResolved: UserOptions['onConfigResolved'];
    onOptionsResolved: UserOptions['onOptionsResolved'];
    onInitialized: UserOptions['onInitialized'];
}

declare function DefaultExtractor(code: string, id?: string): ExtractorResultDetailed;

declare function getDefaultExtractors(): Extractor[];
declare function applyExtractors(code: string, id?: string, extractors?: Extractor[], defaultExtract?: typeof DefaultExtractor): Promise<ExtractorResultDetailed>;

type CompletionsResult = ReturnType<typeof generateCompletions>;
type LayerName = 'base' | 'utilities' | 'components';
declare const SupportedLayers: readonly ["base", "utilities", "components"];
interface LayerMeta {
    cssCache?: string;
    timestamp?: number;
}
interface TransformCssOptions {
    onLayerUpdated?: () => void;
    globaliseKeyframes?: boolean;
}
interface WindiPluginUtils {
    init(): Promise<Processor>;
    ensureInit(): Promise<Processor>;
    extractFile(code: string, id?: string, applyTransform?: boolean): Promise<boolean>;
    applyExtractors: typeof applyExtractors;
    generateCSS(layer?: LayerName): Promise<string>;
    getFiles(): Promise<string[]>;
    clearCache(clearAll?: boolean): void;
    transformCSS(css: string, id: string, transformOptions?: TransformCssOptions): string;
    transformGroups: typeof transformGroups;
    transformAlias: ReturnType<typeof buildAliasTransformer>;
    buildPendingStyles(): void;
    isDetectTarget(id: string): boolean;
    isScanTarget(id: string): boolean;
    isCssTransformTarget(id: string): boolean;
    isExcluded(id: string): boolean;
    scan(): Promise<void>;
    classesGenerated: Set<string>;
    classesPending: Set<string>;
    tagsGenerated: Set<string>;
    tagsPending: Set<string>;
    tagsAvailable: Set<string>;
    layersMeta: Record<LayerName, LayerMeta>;
    addClasses(classes: string[]): boolean;
    addTags(tags: string[]): boolean;
    getCompletions(): ReturnType<typeof generateCompletions>;
    lock(fn: () => Promise<void>): Promise<void>;
    waitLocks(): Promise<void>;
    initialized: boolean;
    options: ResolvedOptions;
    files: string[];
    globs: string[];
    processor: Processor;
    scanned: boolean;
    configFilePath: string | undefined;
    hasPending: boolean;
}
declare function createUtils(userOptions?: UserOptions | ResolvedOptions, utilsOptions?: WindiPluginUtilsOptions): WindiPluginUtils;

declare function getPug(): typeof pug | undefined;
declare function setPug(_pug: typeof pug): void;
declare function PugExtractor(code: string, id?: string): ExtractorResultDetailed;

declare function SvelteExtractor(code: string, id?: string): ExtractorResultDetailed;

type NestedArrayable<T> = T | (T | T[])[];
declare function flattenArray<T>(v: NestedArrayable<T>): T[];
declare function mergeArrays<T>(...args: (NestedArrayable<T> | undefined)[]): T[];
declare function kebabCase(str: string): string;
declare function include<T>(set: Set<T>, v: T[] | Set<T>): void;
declare function exclude<T>(set: Set<T>, v: T[] | Set<T>): void;
declare function escapeRegExp(str: string): string;

declare function isResolvedOptions(options: UserOptions | ResolvedOptions): options is ResolvedOptions;
declare function resolveOptions(options?: UserOptions | ResolvedOptions, utilsOptions?: WindiPluginUtilsOptions, loadConfigFile?: boolean): Promise<ResolvedOptions>;

declare function mergeWindicssConfig(a: FullConfig, b: FullConfig): any;

export { CompletionsResult, DefaultExtractor, LayerMeta, LayerName, NestedArrayable, PugExtractor, ResolvedOptions, SupportedLayers, SvelteExtractor, TagNames, TransformCssOptions, Transformer, TransformerFunction, TransformerOptions, UserOptions, WindiPluginUtils, WindiPluginUtilsOptions, applyExtractors, buildAliasTransformer, createUtils, defaultAlias, defineConfig, escapeRegExp, exclude, flattenArray, getDefaultExtractors, getPug, htmlTags, include, isResolvedOptions, kebabCase, mergeArrays, mergeWindicssConfig, preflightTags, resolveOptions, setPug, transformGroups };