@pikacss/core 0.0.1

package/dist/index.d.cts

@@ -0,0 +1,410 @@
+import * as CSS from 'csstype';
+
+type ExtractFn = (styleDefinition: StyleDefinition$1) => Promise<ExtractedAtomicStyleContent[]>;
+
+declare function createEngine(config?: EngineConfig): Promise<Engine>;
+declare class Engine {
+    config: ResolvedEngineConfig;
+    extract: ExtractFn;
+    store: {
+        atomicNames: Map<string, string>;
+        atomicRules: Map<string, AtomicStyle>;
+    };
+    constructor(config: ResolvedEngineConfig);
+    notifyPreflightUpdated(): void;
+    notifyAtomicRuleAdded(): void;
+    notifyAutocompleteConfigUpdated(): void;
+    appendAutocompleteSelectors(...selectors: string[]): void;
+    appendAutocompleteStyleItemStrings(...styleItemStrings: string[]): void;
+    appendAutocompleteExtraProperties(...properties: string[]): void;
+    appendAutocompleteExtraCssProperties(...properties: string[]): void;
+    appendAutocompletePropertyValues(property: string, ...tsTypes: string[]): void;
+    appendAutocompleteCssPropertyValues(property: string, ...values: (string | number)[]): void;
+    use(...itemList: StyleItem$1[]): Promise<string[]>;
+    renderPreviewStyles(...itemList: StyleItem$1[]): Promise<string>;
+    renderStyles(): string;
+    renderPreflights(): string;
+    renderAtomicStyles(): string;
+}
+
+type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
+type EngineHooksDefinition<_CustomConfig, _Selector extends string, _CSSProperty extends string, _Properties, _StyleDefinition, _StyleItem> = DefineHooks<{
+    config: ['async', config: EngineConfig<EnginePlugin[], _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem> & _CustomConfig];
+    beforeConfigResolving: ['sync', config: EngineConfig<EnginePlugin[], _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem> & _CustomConfig, void];
+    configResolved: ['async', resolvedConfig: ResolvedEngineConfig];
+    engineInitialized: ['sync', engine: Engine];
+    transformSelectors: ['async', selectors: string[]];
+    transformStyleItems: ['async', styleItems: _StyleItem[]];
+    transformStyleDefinitions: ['async', styleDefinitions: _StyleDefinition[]];
+    preflightUpdated: ['sync', void];
+    atomicRuleAdded: ['sync', void];
+    autocompleteConfigUpdated: ['sync', void];
+}>;
+type EnginePluginHooksOptions<_CustomConfig, _Selector extends string, _CSSProperty extends string, _Properties, _StyleDefinition, _StyleItem> = {
+    [K in keyof EngineHooksDefinition<_CustomConfig, _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem>]?: EngineHooksDefinition<_CustomConfig, _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem>[K][0] extends 'async' ? (...params: EngineHooksDefinition<_CustomConfig, _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem>[K][1] extends void ? [] : [payload: EngineHooksDefinition<_CustomConfig, _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem>[K][1]]) => Awaitable<EngineHooksDefinition<_CustomConfig, _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem>[K][1] | void> : (...params: EngineHooksDefinition<_CustomConfig, _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem>[K][1] extends void ? [] : [payload: EngineHooksDefinition<_CustomConfig, _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem>[K][1]]) => EngineHooksDefinition<_CustomConfig, _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem>[K][1] | void;
+};
+interface EnginePlugin<_CustomConfig = any, _Selector extends string = string, _CSSProperty extends string = string, _Properties = Properties$1, _StyleDefinition = StyleDefinition$1, _StyleItem = StyleItem$1> extends EnginePluginHooksOptions<_CustomConfig, _Selector, _CSSProperty, _Properties, _StyleDefinition, _StyleItem> {
+    name: string;
+    order?: 'pre' | 'post';
+}
+
+type UnionString = string & {};
+type UnionNumber = number & {};
+type Arrayable<T> = T | T[];
+type Awaitable<T> = T | Promise<T>;
+type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends ((k: infer I) => void) ? I : never;
+type IsEqual<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
+type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+type ToKebab<T extends string> = T extends `${infer A}${infer B}` ? [A extends Uppercase<A> ? 1 : 0, A extends Lowercase<A> ? 1 : 0] extends [1, 0] ? `-${Lowercase<A>}${ToKebab<`${B}`>}` : `${A}${ToKebab<`${B}`>}` : T;
+type FromKebab<T extends string> = T extends `--${string}` ? T : T extends `-${infer A}${infer B}` ? `${Uppercase<A>}${FromKebab<`${B}`>}` : T extends `${infer A}${infer B}` ? `${A}${FromKebab<`${B}`>}` : T;
+type GetValue<Obj extends Record<string, any>, K extends string> = (IsEqual<Obj, object> | IsEqual<Obj, {}> | IsEqual<Obj[K], unknown>) extends false ? Obj[K] : never;
+type PluginsCustomConfig<Plugins extends EnginePlugin[], Result extends Record<string, any> = {}> = Plugins extends [infer Plugin extends EnginePlugin, ...infer Rest extends EnginePlugin[]] ? PluginsCustomConfig<Rest, Plugin extends EnginePlugin<infer PluginConfig> ? Simplify<Result & PluginConfig> : Result> : Result;
+
+interface AutocompleteConfig {
+    selectors?: string[];
+    styleItemStrings?: string[];
+    extraProperties?: string[];
+    extraCssProperties?: string[];
+    properties?: [property: string, tsType: Arrayable<string>][];
+    cssProperties?: [property: string, value: Arrayable<string | number>][];
+}
+interface ResolvedAutocompleteConfig {
+    selectors: Set<string>;
+    styleItemStrings: Set<string>;
+    extraProperties: Set<string>;
+    extraCssProperties: Set<string>;
+    properties: Map<string, string[]>;
+    cssProperties: Map<string, (string | number)[]>;
+}
+
+interface ImportantConfig {
+    default?: boolean;
+}
+
+type PropertyValue = string | number | [value: string | number, fallback: (string | number)[]] | null | undefined;
+type Properties$1 = Record<string, PropertyValue>;
+interface StyleDefinition$1 {
+    [K: string]: PropertyValue | StyleDefinition$1 | StyleItem$1[];
+}
+type StyleItem$1 = string | StyleDefinition$1;
+interface ExtractedAtomicStyleContent {
+    selector: string[];
+    property: string;
+    value: string[] | null | undefined;
+}
+interface AtomicStyleContent {
+    selector: string[];
+    property: string;
+    value: string[];
+}
+interface AtomicStyle {
+    name: string;
+    content: AtomicStyleContent;
+}
+
+interface Frames<_Properties = Properties$1> {
+    from: _Properties;
+    to: _Properties;
+    [K: `${number}%`]: _Properties;
+}
+type KeyframesConfig<_Properties = Properties$1> = string | [name: string, frames?: Frames<_Properties>, autocomplete?: string[]] | {
+    name: string;
+    frames?: Frames<_Properties>;
+    autocomplete?: string[];
+};
+
+type PreflightFn = (engine: Engine) => string;
+/**
+ * PreflightConfig can be a string or a function that returns a string.
+ *
+ * 1. A string is a static preflight style.
+ * 2. A function is a dynamic preflight style that can use the engine instance to generate styles.
+ */
+type PreflightConfig = string | PreflightFn;
+
+type SelectorConfig<_Selector extends string = string> = string | [selector: RegExp, value: (matched: RegExpMatchArray) => Awaitable<Arrayable<UnionString | _Selector>>, autocomplete?: Arrayable<string>] | [selector: string, value: Arrayable<UnionString | _Selector>] | {
+    selector: RegExp;
+    value: (matched: RegExpMatchArray) => Awaitable<Arrayable<UnionString | _Selector>>;
+    autocomplete?: Arrayable<string>;
+} | {
+    selector: string;
+    value: Arrayable<UnionString | _Selector>;
+};
+
+type ShortcutConfig<_StyleItem = StyleItem$1> = string | [shortcut: RegExp, value: (matched: RegExpMatchArray) => Awaitable<Arrayable<_StyleItem>>, autocomplete?: Arrayable<string>] | {
+    shortcut: RegExp;
+    value: (matched: RegExpMatchArray) => Awaitable<Arrayable<_StyleItem>>;
+    autocomplete?: Arrayable<string>;
+} | [shortcut: string, value: Arrayable<_StyleItem>] | {
+    shortcut: string;
+    value: Arrayable<_StyleItem>;
+};
+
+interface VariableAutocomplete<_CSSProperty extends string = string> {
+    /**
+     * Specify the properties that the variable can be used as a value of.
+     *
+     * @default ['*']
+     */
+    asValueOf?: Arrayable<UnionString | '*' | _CSSProperty>;
+    /**
+     * Whether to add the variable as a CSS property.
+     *
+     * @default true
+     */
+    asProperty?: boolean;
+}
+type VariableConfig<_CSSProperty extends string = string> = string | [name: string, value?: string, autocomplete?: VariableAutocomplete<_CSSProperty>] | {
+    name: string;
+    value?: string;
+    autocomplete?: VariableAutocomplete<_CSSProperty>;
+};
+
+interface EngineConfig<_Plugins extends EnginePlugin[] = EnginePlugin[], _Selector extends string = string, _CSSProperty extends string = string, _Properties = Properties$1, _StyleDefinition = StyleDefinition$1, _StyleItem = StyleItem$1> {
+    /**
+     * Register plugins to extend PikaCSS functionality.
+     *
+     * @example
+     * ```ts
+     * {
+     *   plugins: [
+     *     icons(), // Add icon support
+     *     customPlugin() // Custom plugin
+     *   ]
+     * }
+     * ```
+     */
+    plugins?: [..._Plugins];
+    /**
+     * Set the prefix for generated atomic class names.
+     *
+     * @default ''
+     * @example
+     * ```ts
+     * {
+     *   prefix: 'pika-' // Generated class names will be like 'pika-xxx'
+     * }
+     * ```
+     */
+    prefix?: string;
+    /**
+     * Set the default selector format. '&&' will be replaced with the atomic style name.
+     *
+     * @default '.&&'
+     * @example
+     * ```ts
+     * {
+     *   defaultSelector: '.&&' // Use class attribute: <div class="a b c">
+     *   // or
+     *   defaultSelector: '[data-pika~="&&"]' // Use attribute selector: <div data-pika="a b c">
+     * }
+     * ```
+     */
+    defaultSelector?: string;
+    /**
+     * Define global CSS styles that will be injected before atomic styles.
+     * Can be used for CSS variables, global animations, base styles, etc.
+     *
+     * @default []
+     * @example
+     * ```ts
+     * {
+     *   preflights: [
+     *     // Use CSS string directly
+     *     ':root { --color: blue }',
+     *     // Or use function to generate dynamically
+     *     (engine) => ':root { --theme: dark }'
+     *   ]
+     * }
+     * ```
+     */
+    preflights?: PreflightConfig[];
+    /**
+     * Configure autocomplete functionality, including suggestions for selectors,
+     * style item strings, extra properties, etc.
+     *
+     * @example
+     * ```ts
+     * {
+     *   autocomplete: {
+     *     selectors: ['hover', 'focus'],
+     *     styleItemStrings: ['flex-center'],
+     *     extraProperties: ['customProp'],
+     *     properties: [['color', 'string']]
+     *   }
+     * }
+     * ```
+     */
+    autocomplete?: AutocompleteConfig;
+    /**
+     * Configure !important usage.
+     *
+     * @default { default: false }
+     * @example
+     * ```ts
+     * {
+     *   important: {
+     *     default: true // All styles will be marked as !important
+     *   }
+     * }
+     * ```
+     */
+    important?: ImportantConfig;
+    /**
+     * Set the prefix for CSS variables.
+     *
+     * @example
+     * ```ts
+     * {
+     *   variablesPrefix: 'theme',
+     *   variables: [['color', 'blue']] // Generates: --theme-color: blue
+     * }
+     * ```
+     */
+    variablesPrefix?: string;
+    /**
+     * Define CSS variables with support for static values and autocomplete configuration.
+     *
+     * @default []
+     * @example
+     * ```ts
+     * {
+     *   variables: [
+     *     // Basic usage
+     *     ['primary', '#ff0000'],
+     *     // With autocomplete configuration
+     *     ['accent', '#00ff00', {
+     *       asValueOf: ['color', 'background-color'],
+     *       asProperty: true
+     *     }]
+     *   ]
+     * }
+     * ```
+     */
+    variables?: VariableConfig<_CSSProperty>[];
+    /**
+     * Define CSS @keyframes animations with support for frame definitions
+     * and autocomplete suggestions.
+     *
+     * @default []
+     * @example
+     * ```ts
+     * {
+     *   keyframes: [
+     *     // Basic animation
+     *     ['fade', {
+     *       from: { opacity: 0 },
+     *       to: { opacity: 1 }
+     *     }],
+     *     // With autocomplete suggestions
+     *     ['slide', {
+     *       from: { transform: 'translateX(-100%)' },
+     *       to: { transform: 'translateX(0)' }
+     *     }, ['slide 0.3s ease']]
+     *   ]
+     * }
+     * ```
+     */
+    keyframes?: KeyframesConfig<_Properties>[];
+    /**
+     * Define selector transformation rules with support for static and dynamic rules.
+     *
+     * @default []
+     * @example
+     * ```ts
+     * {
+     *   selectors: [
+     *     // Static selector
+     *     ['hover', '&:hover'],
+     *     // Dynamic selector
+     *     [/^screen-(\d+)$/, m => `@media (min-width: ${m[1]}px)`,
+     *       ['screen-768', 'screen-1024']], // Autocomplete suggestions
+     *   ]
+     * }
+     * ```
+     */
+    selectors?: SelectorConfig<_Selector>[];
+    /**
+     * Define style shortcuts for reusable style combinations.
+     *
+     * @default []
+     * @example
+     * ```ts
+     * {
+     *   shortcuts: [
+     *     // Static shortcut
+     *     ['flex-center', {
+     *       display: 'flex',
+     *       alignItems: 'center',
+     *       justifyContent: 'center'
+     *     }],
+     *     // Dynamic shortcut
+     *     [/^m-(\d+)$/, m => ({ margin: `${m[1]}px` }),
+     *       ['m-4', 'm-8']] // Autocomplete suggestions
+     *   ]
+     * }
+     * ```
+     */
+    shortcuts?: ShortcutConfig<_StyleItem>[];
+    [key: string]: any;
+}
+interface ResolvedEngineConfig {
+    rawConfig: EngineConfig;
+    prefix: string;
+    defaultSelector: string;
+    plugins: EnginePlugin[];
+    preflights: PreflightFn[];
+    autocomplete: ResolvedAutocompleteConfig;
+}
+
+interface Autocomplete {
+    Selector: UnionString;
+    StyleItemString: UnionString;
+    ExtraProperty: UnionString;
+    ExtraCssProperty: UnionString;
+    PropertiesValue: Record<string, unknown>;
+    CssPropertiesValue: Record<string, UnionString | UnionNumber>;
+}
+interface EmptyAutocomplete extends Autocomplete {
+    Selector: never;
+    StyleItemString: never;
+    ExtraProperty: never;
+    ExtraCssProperty: never;
+    PropertiesValue: never;
+    CssPropertiesValue: never;
+}
+interface CSSVariables {
+    [K: (`--${string}` & {})]: UnionString | UnionNumber;
+}
+interface CSSProperties extends CSS.Properties, CSS.PropertiesHyphen, CSSVariables {
+}
+type CSSProperty = keyof CSSProperties;
+type MakePropertyValue<T> = T | [value: T, fallback: T[]] | null | undefined;
+type Properties<Autocomplete_ extends Autocomplete = EmptyAutocomplete> = {
+    [Key in keyof CSSProperties | Autocomplete_['ExtraCssProperty'] | Autocomplete_['ExtraProperty']]?: Key extends Autocomplete_['ExtraProperty'] ? GetValue<Autocomplete_['PropertiesValue'], Key> : MakePropertyValue<Exclude<UnionString | UnionNumber | GetValue<CSSProperties, Key> | GetValue<Autocomplete_['CssPropertiesValue'], ToKebab<Key>> | GetValue<Autocomplete_['CssPropertiesValue'], FromKebab<Key>> | GetValue<Autocomplete_['CssPropertiesValue'], '*'>, undefined | null>>;
+};
+type CSSPseudos = `${'&'}${CSS.Pseudos}`;
+type CSSBlockAtRules = Exclude<CSS.AtRules, '@charset' | 'import' | '@namespace'>;
+type CSSSelectors = CSSBlockAtRules | CSSPseudos;
+type WrapWithSelector<Autocomplete_ extends Autocomplete, T> = {
+    [S in UnionString | Autocomplete_['Selector'] | CSSSelectors]?: T | StyleItem<Autocomplete_>[];
+};
+type MakeStyleDefinition<Autocomplete_ extends Autocomplete, MaxDepth extends number, Tuple extends any[] = []> = Tuple['length'] extends MaxDepth ? Tuple[number] : Tuple['length'] extends 0 ? MakeStyleDefinition<Autocomplete_, MaxDepth, [Properties<Autocomplete_>]> : MakeStyleDefinition<Autocomplete_, MaxDepth, [...Tuple, WrapWithSelector<Autocomplete_, [0, ...Tuple][Tuple['length']]>]>;
+type StyleDefinition<Autocomplete_ extends Autocomplete = EmptyAutocomplete> = MakeStyleDefinition<Autocomplete_, 5>;
+type StyleItem<Autocomplete_ extends Autocomplete = EmptyAutocomplete> = UnionString | Autocomplete_['StyleItemString'] | StyleDefinition<Autocomplete_>;
+
+declare function appendAutocompleteSelectors(config: Pick<ResolvedEngineConfig, 'autocomplete'>, ...selectors: string[]): void;
+declare function appendAutocompleteStyleItemStrings(config: Pick<ResolvedEngineConfig, 'autocomplete'>, ...styleItemStrings: string[]): void;
+declare function appendAutocompleteExtraProperties(config: Pick<ResolvedEngineConfig, 'autocomplete'>, ...properties: string[]): void;
+declare function appendAutocompleteExtraCssProperties(config: Pick<ResolvedEngineConfig, 'autocomplete'>, ...properties: string[]): void;
+declare function appendAutocompletePropertyValues(config: Pick<ResolvedEngineConfig, 'autocomplete'>, property: string, ...tsTypes: string[]): void;
+declare function appendAutocompleteCssPropertyValues(config: Pick<ResolvedEngineConfig, 'autocomplete'>, property: string, ...values: (string | number)[]): void;
+
+declare function createDefineEnginePluginFn<A extends Autocomplete = EmptyAutocomplete>(): <C extends Record<string, any>>(plugin: EnginePlugin<C, A["Selector"] | CSSSelectors, A["ExtraCssProperty"] | CSSProperty, Properties<A>, StyleDefinition<A>, StyleItem<A>>) => EnginePlugin<C>;
+declare const defineEnginePlugin: <C extends Record<string, any>>(plugin: EnginePlugin<C, CSSSelectors, keyof CSSProperties, Properties<EmptyAutocomplete>, StyleDefinition<EmptyAutocomplete>, StyleItem<EmptyAutocomplete>>) => EnginePlugin<C, string, string, Properties$1, StyleDefinition$1, StyleItem$1>;
+declare function createDefineEngineConfigFn<A extends Autocomplete = EmptyAutocomplete>(): <P extends EnginePlugin[] = []>(config: EngineConfig<P, A["Selector"] | CSSSelectors, A["ExtraCssProperty"] | CSSProperty, Properties<A>, StyleDefinition<A>, StyleItem<A>> & PluginsCustomConfig<P>) => EngineConfig<P> & PluginsCustomConfig<P>;
+declare const defineEngineConfig: <P extends EnginePlugin[] = []>(config: EngineConfig<P, CSSSelectors, keyof CSSProperties, Properties<EmptyAutocomplete>, StyleDefinition<EmptyAutocomplete>, StyleItem<EmptyAutocomplete>> & PluginsCustomConfig<P, {}>) => EngineConfig<P, string, string, Properties$1, StyleDefinition$1, StyleItem$1> & PluginsCustomConfig<P, {}>;
+
+export { type Arrayable, type Autocomplete, type Awaitable, type EmptyAutocomplete, Engine, type EngineConfig, type EnginePlugin, type FromKebab, type GetValue, type IsEqual, type PluginsCustomConfig, type Properties, type Simplify, type StyleDefinition, type StyleItem, type ToKebab, type UnionNumber, type UnionString, type UnionToIntersection, appendAutocompleteCssPropertyValues, appendAutocompleteExtraCssProperties, appendAutocompleteExtraProperties, appendAutocompletePropertyValues, appendAutocompleteSelectors, appendAutocompleteStyleItemStrings, createDefineEngineConfigFn, createDefineEnginePluginFn, createEngine, defineEngineConfig, defineEnginePlugin };