@pikacss/core 0.0.28 → 0.0.29

package/dist/index.cjs

@@ -277,7 +277,7 @@ function keyframes() {
   return defineEnginePlugin({
     name: "core:keyframes",
     rawConfigConfigured(config) {
-      resolveKeyframesConfig = createResolveConfigFn$1({
+      resolveKeyframesConfig = createResolveConfigFn({
         pruneUnused: config.keyframes?.pruneUnused
       });
       configList = config.keyframes?.keyframes ?? [];
@@ -300,7 +300,7 @@ function keyframes() {
         }
       };
       engine.keyframes.add(...configList);
-      engine.addPreflight((engine2, isFormatted) => {
+      engine.addPreflight((engine2) => {
         const maybeUsedName = /* @__PURE__ */ new Set();
         engine2.store.atomicStyles.forEach(({ content: { property, value } }) => {
           if (property === "animationName") {
@@ -316,30 +316,22 @@ function keyframes() {
             });
           }
         });
-        return renderCSSStyleBlocks(
-          new Map(Array.from(engine2.keyframes.store.entries()).filter(([name, { pruneUnused }]) => pruneUnused === false || maybeUsedName.has(name)).map(([name, { frames }]) => [
-            `@keyframes ${name}`,
-            {
-              properties: [],
-              children: new Map(Object.entries(frames).map(([frame, properties]) => [
-                frame,
-                {
-                  properties: Object.entries(properties).filter(([_, value]) => isNotNullish(value)).flatMap(([property, value]) => {
-                    if (Array.isArray(value))
-                      return value.map((v) => ({ property, value: String(v) }));
-                    return { property, value: String(value) };
-                  })
-                }
-              ]))
-            }
-          ])),
-          isFormatted
-        );
+        const maybeUsedKeyframes = Array.from(engine2.keyframes.store.values()).filter(({ name, frames, pruneUnused }) => (pruneUnused === false || maybeUsedName.has(name)) && frames != null);
+        const preflightDefinition = {};
+        maybeUsedKeyframes.forEach(({ name, frames }) => {
+          preflightDefinition[`@keyframes ${name}`] = Object.fromEntries(
+            Object.entries(frames).map(([frame, properties]) => [
+              frame,
+              properties
+            ])
+          );
+        });
+        return preflightDefinition;
       });
     }
   });
 }
-function createResolveConfigFn$1({
+function createResolveConfigFn({
   pruneUnused: defaultPruneUnused = true
 } = {}) {
   return function resolveKeyframesConfig(config) {
@@ -686,67 +678,92 @@ function resolveShortcutConfig(config) {
 }
 
 function variables() {
-  let resolveVariableConfig;
-  let configList;
+  let resolveVariables;
+  let rawVariables;
+  let safeSet;
   return defineEnginePlugin({
     name: "core:variables",
     rawConfigConfigured(config) {
-      resolveVariableConfig = createResolveConfigFn({
+      resolveVariables = createResolveVariablesFn({
         pruneUnused: config.variables?.pruneUnused
       });
-      configList = config.variables?.variables ?? [];
+      rawVariables = config.variables?.variables ?? {};
+      safeSet = new Set(config.variables?.safeList ?? []);
     },
     configureEngine(engine) {
       engine.variables = {
         store: /* @__PURE__ */ new Map(),
-        add: (...list) => {
-          list.forEach((config) => {
-            const resolved = resolveVariableConfig(config);
-            const { name: _name, value, autocomplete: { asValueOf, asProperty } } = resolved;
-            const name = normalizeVariableName(_name);
+        add: (variables2) => {
+          const list = resolveVariables(variables2);
+          list.forEach((resolved) => {
+            const { name, value, autocomplete: { asValueOf, asProperty } } = resolved;
             asValueOf.forEach((p) => {
               if (p !== "-")
                 engine.appendAutocompleteCssPropertyValues(p, `var(${name})`);
             });
             if (asProperty)
               engine.appendAutocompleteExtraCssProperties(name);
-            if (value != null)
-              engine.variables.store.set(name, resolved);
+            if (value != null) {
+              const list2 = engine.variables.store.get(name) ?? [];
+              list2.push(resolved);
+              engine.variables.store.set(name, list2);
+            }
           });
           engine.notifyPreflightUpdated();
         }
       };
-      engine.variables.add(...configList);
-      engine.addPreflight((engine2, isFormatted) => {
+      engine.variables.add(rawVariables);
+      engine.addPreflight(async (engine2) => {
         const used = /* @__PURE__ */ new Set();
         engine2.store.atomicStyles.forEach(({ content: { value } }) => {
           value.flatMap(extractUsedVarNames).forEach((name) => used.add(normalizeVariableName(name)));
         });
-        return renderCSSStyleBlocks(
-          /* @__PURE__ */ new Map([[
-            ":root",
-            {
-              properties: Array.from(engine2.variables.store.entries()).filter(([name, { pruneUnused, value }]) => (pruneUnused === false || used.has(name)) && value != null).map(([name, { value }]) => ({ property: name, value }))
-            }
-          ]]),
-          isFormatted
-        );
+        const usedVariables = Array.from(engine2.variables.store.values()).flat().filter(({ name, pruneUnused, value }) => (safeSet.has(name) || pruneUnused === false || used.has(name)) && value != null);
+        const preflightDefinition = {};
+        for (const { name, value, selector: _selector } of usedVariables) {
+          const selector = await engine2.pluginHooks.transformSelectors(engine2.config.plugins, _selector);
+          let current = preflightDefinition;
+          selector.forEach((s) => {
+            current[s] ||= {};
+            current = current[s];
+          });
+          Object.assign(current, { [name]: value });
+        }
+        return preflightDefinition;
       });
     }
   });
 }
-function createResolveConfigFn({
+function createResolveVariablesFn({
   pruneUnused: defaultPruneUnused = true
 } = {}) {
-  return function resolveVariableConfig(config) {
-    if (typeof config === "string")
-      return { name: config, value: null, autocomplete: { asValueOf: ["*"], asProperty: true }, pruneUnused: defaultPruneUnused };
-    if (Array.isArray(config)) {
-      const [name2, value2, { asValueOf: asValueOf2 = "*", asProperty: asProperty2 = true } = {}, pruneUnused2 = defaultPruneUnused] = config;
-      return { name: name2, value: value2, autocomplete: { asValueOf: [asValueOf2].flat(), asProperty: asProperty2 }, pruneUnused: pruneUnused2 };
+  function _resolveVariables(variables2, levels, result) {
+    for (const [key, value] of Object.entries(variables2)) {
+      if (key.startsWith("--")) {
+        const isObject = typeof value === "object" && value !== null && !Array.isArray(value);
+        const {
+          value: varValue,
+          autocomplete = {},
+          pruneUnused = defaultPruneUnused
+        } = isObject ? value : { value };
+        result.push({
+          name: key,
+          value: varValue,
+          selector: levels.length > 0 ? levels : [":root"],
+          autocomplete: {
+            asValueOf: autocomplete.asValueOf ? [autocomplete.asValueOf].flat() : ["*"],
+            asProperty: autocomplete.asProperty ?? true
+          },
+          pruneUnused
+        });
+      } else {
+        _resolveVariables(value, [...levels, key], result);
+      }
     }
-    const { name, value, autocomplete: { asValueOf = "*", asProperty = true } = {}, pruneUnused = defaultPruneUnused } = config;
-    return { name, value, autocomplete: { asValueOf: [asValueOf].flat(), asProperty }, pruneUnused };
+    return result;
+  }
+  return function resolveVariables(variables2) {
+    return _resolveVariables(variables2, [], []);
   };
 }
 const VAR_NAME_RE = /var\((--[\w-]+)/g;
@@ -800,6 +817,7 @@ async function createEngine(config = {}) {
 }
 class Engine {
   config;
+  pluginHooks = hooks;
   extract;
   store = {
     atomicStyleIds: /* @__PURE__ */ new Map(),
@@ -878,13 +896,13 @@ class Engine {
   }
   async renderPreflights(isFormatted) {
     const lineEnd = isFormatted ? "\n" : "";
-    return (await Promise.all(this.config.preflights.map((p) => {
-      const result = p(this, isFormatted);
+    return (await Promise.all(this.config.preflights.map(async (p) => {
+      const result = await p(this, isFormatted);
       if (typeof result === "string")
         return result;
-      return renderPreflight({
+      return renderPreflightDefinition({
         engine: this,
-        preflight: result,
+        preflightDefinition: result,
         isFormatted
       });
     }))).join(lineEnd);
@@ -1008,7 +1026,7 @@ function renderAtomicStyles(payload) {
   });
   return renderCSSStyleBlocks(blocks, isFormatted);
 }
-async function _renderPreflight({
+async function _renderPreflightDefinition({
   engine,
   preflightDefinition,
   blocks = /* @__PURE__ */ new Map()
@@ -1041,7 +1059,7 @@ async function _renderPreflight({
       } else {
         currentBlockBody.children ||= /* @__PURE__ */ new Map();
         currentBlockBody.children.set(k, currentBlockBody.children.get(k) || { properties: [] });
-        _renderPreflight({
+        _renderPreflightDefinition({
           engine,
           preflightDefinition: { [k]: v },
           blocks: currentBlockBody.children
@@ -1051,11 +1069,11 @@ async function _renderPreflight({
   }
   return blocks;
 }
-async function renderPreflight(payload) {
-  const { engine, preflight, isFormatted } = payload;
-  const blocks = await _renderPreflight({
+async function renderPreflightDefinition(payload) {
+  const { engine, preflightDefinition, isFormatted } = payload;
+  const blocks = await _renderPreflightDefinition({
     engine,
-    preflightDefinition: preflight
+    preflightDefinition
   });
   return renderCSSStyleBlocks(blocks, isFormatted);
 }

package/dist/index.d.cts

@@ -1,3 +1,4 @@
+import * as _pikacss_core from '@pikacss/core';
 import * as CSS from 'csstype';
 
 interface ImportantConfig {
@@ -188,6 +189,8 @@ declare class ShortcutResolver extends AbstractResolver<StyleItem$1[]> {
     resolve(shortcut: string): Promise<StyleItem$1[]>;
 }
 
+type ResolvedCSSProperty = keyof ResolvedCSSProperties;
+type ResolvedCSSVarProperty = ResolvedCSSProperty extends infer T ? T extends `--${string}` ? T : never : never;
 interface VariableAutocomplete {
     /**
      * Specify the properties that the variable can be used as a value of.
@@ -202,39 +205,59 @@ interface VariableAutocomplete {
      */
     asProperty?: boolean;
 }
-type Variable = string | [name: string, value?: string, autocomplete?: VariableAutocomplete, pruneUnused?: boolean] | {
-    name: string;
-    value?: string;
+interface VariableObject {
+    value?: ResolvedCSSProperties[`--${string}`];
     autocomplete?: VariableAutocomplete;
     pruneUnused?: boolean;
+}
+type Variable = ResolvedCSSProperties[`--${string}`] | VariableObject;
+type VariablesDefinition = {
+    [key in UnionString | ResolvedSelector | (`--${string}` & {}) | ResolvedCSSVarProperty]?: Variable | VariablesDefinition;
 };
 interface VariablesConfig {
     /**
      * Define CSS variables with support for static values and autocomplete configuration.
      *
-     * @default []
+     * @default {}
      * @example
      * ```ts
      * {
-     *   variables: [
-     *     // Basic usage
-     *     ['primary', '#ff0000'],
-     *     // With autocomplete configuration
-     *     ['accent', '#00ff00', {
-     *       asValueOf: ['color', 'background-color'],
-     *       asProperty: true
-     *     }]
-     *   ]
+     *   variables: {
+     *     // The variable with value "null" will not be included in the final CSS, but can be used in autocompletion.
+     *     '--external-var': null,
+     *
+     *     '--color-bg': '#fff',
+     *     '--color-text': '#000',
+     *
+     *     '[data-theme="dark"]': {
+     *       '--color-bg': '#000',
+     *       '--color-text': '#fff',
+     *     },
+     *   },
      * }
      * ```
      */
-    variables: Variable[];
+    variables: VariablesDefinition;
     /**
      * Whether to prune unused variables from the final CSS.
      *
      * @default true
      */
     pruneUnused?: boolean;
+    /**
+     * A list of CSS variables that should always be included in the final CSS, you can use this to prevent certain variables from being pruned.
+     *
+     * @default []
+     * @example
+     * ```ts
+     * {
+     *   variables: {
+     *     safeList: ['--external-var', '--color-bg', '--color-text'],
+     *   },
+     * }
+     * ```
+     */
+    safeList?: ((`--${string}` & {}) | ResolvedCSSVarProperty)[];
 }
 declare module '@pikacss/core' {
     interface EngineConfig {
@@ -242,14 +265,15 @@ declare module '@pikacss/core' {
     }
     interface Engine {
         variables: {
-            store: Map<string, ResolvedVariableConfig>;
-            add: (...list: Variable[]) => void;
+            store: Map<string, ResolvedVariable[]>;
+            add: (variables: VariablesDefinition) => void;
         };
     }
 }
-interface ResolvedVariableConfig {
+interface ResolvedVariable {
     name: string;
-    value: string | Nullish;
+    value: PropertyValue;
+    selector: string[];
     pruneUnused: boolean;
     autocomplete: {
         asValueOf: string[];
@@ -273,42 +297,6 @@ type FromKebab<T extends string> = T extends `--${string}` ? T : T extends `-${i
 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 ResolveFrom<T, Key extends string, I, Fallback extends I> = Key extends keyof T ? T[Key] extends I ? T[Key] : Fallback : Fallback;
 
-interface PikaAugment {
-}
-type PropertyValue = string | number | [value: string | number, fallback: (string | number)[]] | Nullish;
-type Properties$1 = Record<string, PropertyValue>;
-interface StyleDefinition$1 {
-    [K: string]: PropertyValue | StyleDefinition$1 | StyleItem$1[];
-}
-type StyleItem$1 = string | StyleDefinition$1;
-interface ExtractedStyleContent {
-    selector: string[];
-    property: string;
-    value: string[] | Nullish;
-}
-interface StyleContent {
-    selector: string[];
-    property: string;
-    value: string[];
-}
-interface AtomicStyle {
-    id: string;
-    content: StyleContent;
-}
-interface CSSStyleBlockBody {
-    properties: {
-        property: string;
-        value: string;
-    }[];
-    children?: CSSStyleBlocks;
-}
-type CSSStyleBlocks = Map<string, CSSStyleBlockBody>;
-type ResolvedSelector = ResolveFrom<PikaAugment, 'Selector', string, string>;
-type ResolvedCSSProperty = ResolveFrom<PikaAugment, 'CSSProperty', string, string>;
-type ResolvedProperties = ResolveFrom<PikaAugment, 'Properties', any, Properties$1>;
-type ResolvedStyleDefinition = ResolveFrom<PikaAugment, 'StyleDefinition', any, StyleDefinition$1>;
-type ResolvedStyleItem = ResolveFrom<PikaAugment, 'StyleItem', any, StyleItem$1>;
-
 interface ResolvedAutocompleteConfig {
     selectors: Set<string>;
     styleItemStrings: Set<string>;
@@ -334,7 +322,6 @@ type EmptyAutocomplete = DefineAutocomplete<{
     PropertiesValue: never;
     CssPropertiesValue: never;
 }>;
-type ResolvedAutocomplete = ResolveFrom<PikaAugment, 'Autocomplete', _Autocomplete, EmptyAutocomplete>;
 
 type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
 type EngineHooksDefinition = DefineHooks<{
@@ -358,10 +345,48 @@ interface EnginePlugin extends EnginePluginHooksOptions {
 }
 declare function defineEnginePlugin(plugin: EnginePlugin): EnginePlugin;
 
+interface PikaAugment {
+}
+type PropertyValue = string | number | [value: string | number, fallback: (string | number)[]] | Nullish;
+type Properties$1 = Record<string, PropertyValue>;
+interface StyleDefinition$1 {
+    [K: string]: PropertyValue | StyleDefinition$1 | StyleItem$1[];
+}
+type StyleItem$1 = string | StyleDefinition$1;
+interface ExtractedStyleContent {
+    selector: string[];
+    property: string;
+    value: string[] | Nullish;
+}
+interface StyleContent {
+    selector: string[];
+    property: string;
+    value: string[];
+}
+interface AtomicStyle {
+    id: string;
+    content: StyleContent;
+}
+interface CSSStyleBlockBody {
+    properties: {
+        property: string;
+        value: string;
+    }[];
+    children?: CSSStyleBlocks;
+}
+type CSSStyleBlocks = Map<string, CSSStyleBlockBody>;
+
+type ResolvedAutocomplete = ResolveFrom<PikaAugment, 'Autocomplete', _Autocomplete, EmptyAutocomplete>;
+type ResolvedSelector = ResolveFrom<PikaAugment, 'Selector', string, string>;
+type ResolvedProperties = ResolveFrom<PikaAugment, 'Properties', any, Properties$1>;
+type ResolvedCSSProperties = Omit<ResolvedProperties, ResolvedAutocomplete['ExtraProperty']>;
+type ResolvedStyleDefinition = ResolveFrom<PikaAugment, 'StyleDefinition', any, StyleDefinition$1>;
+type ResolvedStyleItem = ResolveFrom<PikaAugment, 'StyleItem', any, StyleItem$1>;
+
 type PreflightDefinition = {
-    [selector in UnionString | ResolvedSelector]?: ResolvedProperties | PreflightDefinition;
+    [selector in UnionString | ResolvedSelector]?: ResolvedCSSProperties | PreflightDefinition;
 };
-type PreflightFn = (engine: Engine, isFormatted: boolean) => string | PreflightDefinition;
+type PreflightFn = (engine: Engine, isFormatted: boolean) => Awaitable<string | PreflightDefinition>;
 /**
  * PreflightConfig can be a string or a function that returns a string.
  *
@@ -445,6 +470,18 @@ declare function defineEngineConfig(config: EngineConfig): EngineConfig;
 declare function createEngine(config?: EngineConfig): Promise<Engine>;
 declare class Engine {
     config: ResolvedEngineConfig;
+    pluginHooks: {
+        configureRawConfig: (plugins: _pikacss_core.EnginePlugin[], payload: EngineConfig) => Promise<EngineConfig>;
+        rawConfigConfigured: (plugins: _pikacss_core.EnginePlugin[], payload: EngineConfig) => void;
+        configureResolvedConfig: (plugins: _pikacss_core.EnginePlugin[], payload: ResolvedEngineConfig) => Promise<ResolvedEngineConfig>;
+        configureEngine: (plugins: _pikacss_core.EnginePlugin[], payload: Engine) => Promise<Engine>;
+        transformSelectors: (plugins: _pikacss_core.EnginePlugin[], payload: string[]) => Promise<string[]>;
+        transformStyleItems: (plugins: _pikacss_core.EnginePlugin[], payload: StyleItem$1[]) => Promise<StyleItem$1[]>;
+        transformStyleDefinitions: (plugins: _pikacss_core.EnginePlugin[], payload: StyleDefinition$1[]) => Promise<StyleDefinition$1[]>;
+        preflightUpdated: (plugins: _pikacss_core.EnginePlugin[]) => void;
+        atomicStyleAdded: (plugins: _pikacss_core.EnginePlugin[], payload: AtomicStyle) => AtomicStyle;
+        autocompleteConfigUpdated: (plugins: _pikacss_core.EnginePlugin[]) => void;
+    };
     extract: ExtractFn;
     store: {
         atomicStyleIds: Map<string, string>;

package/dist/index.d.mts

@@ -1,3 +1,4 @@
+import * as _pikacss_core from '@pikacss/core';
 import * as CSS from 'csstype';
 
 interface ImportantConfig {
@@ -188,6 +189,8 @@ declare class ShortcutResolver extends AbstractResolver<StyleItem$1[]> {
     resolve(shortcut: string): Promise<StyleItem$1[]>;
 }
 
+type ResolvedCSSProperty = keyof ResolvedCSSProperties;
+type ResolvedCSSVarProperty = ResolvedCSSProperty extends infer T ? T extends `--${string}` ? T : never : never;
 interface VariableAutocomplete {
     /**
      * Specify the properties that the variable can be used as a value of.
@@ -202,39 +205,59 @@ interface VariableAutocomplete {
      */
     asProperty?: boolean;
 }
-type Variable = string | [name: string, value?: string, autocomplete?: VariableAutocomplete, pruneUnused?: boolean] | {
-    name: string;
-    value?: string;
+interface VariableObject {
+    value?: ResolvedCSSProperties[`--${string}`];
     autocomplete?: VariableAutocomplete;
     pruneUnused?: boolean;
+}
+type Variable = ResolvedCSSProperties[`--${string}`] | VariableObject;
+type VariablesDefinition = {
+    [key in UnionString | ResolvedSelector | (`--${string}` & {}) | ResolvedCSSVarProperty]?: Variable | VariablesDefinition;
 };
 interface VariablesConfig {
     /**
      * Define CSS variables with support for static values and autocomplete configuration.
      *
-     * @default []
+     * @default {}
      * @example
      * ```ts
      * {
-     *   variables: [
-     *     // Basic usage
-     *     ['primary', '#ff0000'],
-     *     // With autocomplete configuration
-     *     ['accent', '#00ff00', {
-     *       asValueOf: ['color', 'background-color'],
-     *       asProperty: true
-     *     }]
-     *   ]
+     *   variables: {
+     *     // The variable with value "null" will not be included in the final CSS, but can be used in autocompletion.
+     *     '--external-var': null,
+     *
+     *     '--color-bg': '#fff',
+     *     '--color-text': '#000',
+     *
+     *     '[data-theme="dark"]': {
+     *       '--color-bg': '#000',
+     *       '--color-text': '#fff',
+     *     },
+     *   },
      * }
      * ```
      */
-    variables: Variable[];
+    variables: VariablesDefinition;
     /**
      * Whether to prune unused variables from the final CSS.
      *
      * @default true
      */
     pruneUnused?: boolean;
+    /**
+     * A list of CSS variables that should always be included in the final CSS, you can use this to prevent certain variables from being pruned.
+     *
+     * @default []
+     * @example
+     * ```ts
+     * {
+     *   variables: {
+     *     safeList: ['--external-var', '--color-bg', '--color-text'],
+     *   },
+     * }
+     * ```
+     */
+    safeList?: ((`--${string}` & {}) | ResolvedCSSVarProperty)[];
 }
 declare module '@pikacss/core' {
     interface EngineConfig {
@@ -242,14 +265,15 @@ declare module '@pikacss/core' {
     }
     interface Engine {
         variables: {
-            store: Map<string, ResolvedVariableConfig>;
-            add: (...list: Variable[]) => void;
+            store: Map<string, ResolvedVariable[]>;
+            add: (variables: VariablesDefinition) => void;
         };
     }
 }
-interface ResolvedVariableConfig {
+interface ResolvedVariable {
     name: string;
-    value: string | Nullish;
+    value: PropertyValue;
+    selector: string[];
     pruneUnused: boolean;
     autocomplete: {
         asValueOf: string[];
@@ -273,42 +297,6 @@ type FromKebab<T extends string> = T extends `--${string}` ? T : T extends `-${i
 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 ResolveFrom<T, Key extends string, I, Fallback extends I> = Key extends keyof T ? T[Key] extends I ? T[Key] : Fallback : Fallback;
 
-interface PikaAugment {
-}
-type PropertyValue = string | number | [value: string | number, fallback: (string | number)[]] | Nullish;
-type Properties$1 = Record<string, PropertyValue>;
-interface StyleDefinition$1 {
-    [K: string]: PropertyValue | StyleDefinition$1 | StyleItem$1[];
-}
-type StyleItem$1 = string | StyleDefinition$1;
-interface ExtractedStyleContent {
-    selector: string[];
-    property: string;
-    value: string[] | Nullish;
-}
-interface StyleContent {
-    selector: string[];
-    property: string;
-    value: string[];
-}
-interface AtomicStyle {
-    id: string;
-    content: StyleContent;
-}
-interface CSSStyleBlockBody {
-    properties: {
-        property: string;
-        value: string;
-    }[];
-    children?: CSSStyleBlocks;
-}
-type CSSStyleBlocks = Map<string, CSSStyleBlockBody>;
-type ResolvedSelector = ResolveFrom<PikaAugment, 'Selector', string, string>;
-type ResolvedCSSProperty = ResolveFrom<PikaAugment, 'CSSProperty', string, string>;
-type ResolvedProperties = ResolveFrom<PikaAugment, 'Properties', any, Properties$1>;
-type ResolvedStyleDefinition = ResolveFrom<PikaAugment, 'StyleDefinition', any, StyleDefinition$1>;
-type ResolvedStyleItem = ResolveFrom<PikaAugment, 'StyleItem', any, StyleItem$1>;
-
 interface ResolvedAutocompleteConfig {
     selectors: Set<string>;
     styleItemStrings: Set<string>;
@@ -334,7 +322,6 @@ type EmptyAutocomplete = DefineAutocomplete<{
     PropertiesValue: never;
     CssPropertiesValue: never;
 }>;
-type ResolvedAutocomplete = ResolveFrom<PikaAugment, 'Autocomplete', _Autocomplete, EmptyAutocomplete>;
 
 type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
 type EngineHooksDefinition = DefineHooks<{
@@ -358,10 +345,48 @@ interface EnginePlugin extends EnginePluginHooksOptions {
 }
 declare function defineEnginePlugin(plugin: EnginePlugin): EnginePlugin;
 
+interface PikaAugment {
+}
+type PropertyValue = string | number | [value: string | number, fallback: (string | number)[]] | Nullish;
+type Properties$1 = Record<string, PropertyValue>;
+interface StyleDefinition$1 {
+    [K: string]: PropertyValue | StyleDefinition$1 | StyleItem$1[];
+}
+type StyleItem$1 = string | StyleDefinition$1;
+interface ExtractedStyleContent {
+    selector: string[];
+    property: string;
+    value: string[] | Nullish;
+}
+interface StyleContent {
+    selector: string[];
+    property: string;
+    value: string[];
+}
+interface AtomicStyle {
+    id: string;
+    content: StyleContent;
+}
+interface CSSStyleBlockBody {
+    properties: {
+        property: string;
+        value: string;
+    }[];
+    children?: CSSStyleBlocks;
+}
+type CSSStyleBlocks = Map<string, CSSStyleBlockBody>;
+
+type ResolvedAutocomplete = ResolveFrom<PikaAugment, 'Autocomplete', _Autocomplete, EmptyAutocomplete>;
+type ResolvedSelector = ResolveFrom<PikaAugment, 'Selector', string, string>;
+type ResolvedProperties = ResolveFrom<PikaAugment, 'Properties', any, Properties$1>;
+type ResolvedCSSProperties = Omit<ResolvedProperties, ResolvedAutocomplete['ExtraProperty']>;
+type ResolvedStyleDefinition = ResolveFrom<PikaAugment, 'StyleDefinition', any, StyleDefinition$1>;
+type ResolvedStyleItem = ResolveFrom<PikaAugment, 'StyleItem', any, StyleItem$1>;
+
 type PreflightDefinition = {
-    [selector in UnionString | ResolvedSelector]?: ResolvedProperties | PreflightDefinition;
+    [selector in UnionString | ResolvedSelector]?: ResolvedCSSProperties | PreflightDefinition;
 };
-type PreflightFn = (engine: Engine, isFormatted: boolean) => string | PreflightDefinition;
+type PreflightFn = (engine: Engine, isFormatted: boolean) => Awaitable<string | PreflightDefinition>;
 /**
  * PreflightConfig can be a string or a function that returns a string.
  *
@@ -445,6 +470,18 @@ declare function defineEngineConfig(config: EngineConfig): EngineConfig;
 declare function createEngine(config?: EngineConfig): Promise<Engine>;
 declare class Engine {
     config: ResolvedEngineConfig;
+    pluginHooks: {
+        configureRawConfig: (plugins: _pikacss_core.EnginePlugin[], payload: EngineConfig) => Promise<EngineConfig>;
+        rawConfigConfigured: (plugins: _pikacss_core.EnginePlugin[], payload: EngineConfig) => void;
+        configureResolvedConfig: (plugins: _pikacss_core.EnginePlugin[], payload: ResolvedEngineConfig) => Promise<ResolvedEngineConfig>;
+        configureEngine: (plugins: _pikacss_core.EnginePlugin[], payload: Engine) => Promise<Engine>;
+        transformSelectors: (plugins: _pikacss_core.EnginePlugin[], payload: string[]) => Promise<string[]>;
+        transformStyleItems: (plugins: _pikacss_core.EnginePlugin[], payload: StyleItem$1[]) => Promise<StyleItem$1[]>;
+        transformStyleDefinitions: (plugins: _pikacss_core.EnginePlugin[], payload: StyleDefinition$1[]) => Promise<StyleDefinition$1[]>;
+        preflightUpdated: (plugins: _pikacss_core.EnginePlugin[]) => void;
+        atomicStyleAdded: (plugins: _pikacss_core.EnginePlugin[], payload: AtomicStyle) => AtomicStyle;
+        autocompleteConfigUpdated: (plugins: _pikacss_core.EnginePlugin[]) => void;
+    };
     extract: ExtractFn;
     store: {
         atomicStyleIds: Map<string, string>;

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import * as _pikacss_core from '@pikacss/core';
 import * as CSS from 'csstype';
 
 interface ImportantConfig {
@@ -188,6 +189,8 @@ declare class ShortcutResolver extends AbstractResolver<StyleItem$1[]> {
     resolve(shortcut: string): Promise<StyleItem$1[]>;
 }
 
+type ResolvedCSSProperty = keyof ResolvedCSSProperties;
+type ResolvedCSSVarProperty = ResolvedCSSProperty extends infer T ? T extends `--${string}` ? T : never : never;
 interface VariableAutocomplete {
     /**
      * Specify the properties that the variable can be used as a value of.
@@ -202,39 +205,59 @@ interface VariableAutocomplete {
      */
     asProperty?: boolean;
 }
-type Variable = string | [name: string, value?: string, autocomplete?: VariableAutocomplete, pruneUnused?: boolean] | {
-    name: string;
-    value?: string;
+interface VariableObject {
+    value?: ResolvedCSSProperties[`--${string}`];
     autocomplete?: VariableAutocomplete;
     pruneUnused?: boolean;
+}
+type Variable = ResolvedCSSProperties[`--${string}`] | VariableObject;
+type VariablesDefinition = {
+    [key in UnionString | ResolvedSelector | (`--${string}` & {}) | ResolvedCSSVarProperty]?: Variable | VariablesDefinition;
 };
 interface VariablesConfig {
     /**
      * Define CSS variables with support for static values and autocomplete configuration.
      *
-     * @default []
+     * @default {}
      * @example
      * ```ts
      * {
-     *   variables: [
-     *     // Basic usage
-     *     ['primary', '#ff0000'],
-     *     // With autocomplete configuration
-     *     ['accent', '#00ff00', {
-     *       asValueOf: ['color', 'background-color'],
-     *       asProperty: true
-     *     }]
-     *   ]
+     *   variables: {
+     *     // The variable with value "null" will not be included in the final CSS, but can be used in autocompletion.
+     *     '--external-var': null,
+     *
+     *     '--color-bg': '#fff',
+     *     '--color-text': '#000',
+     *
+     *     '[data-theme="dark"]': {
+     *       '--color-bg': '#000',
+     *       '--color-text': '#fff',
+     *     },
+     *   },
      * }
      * ```
      */
-    variables: Variable[];
+    variables: VariablesDefinition;
     /**
      * Whether to prune unused variables from the final CSS.
      *
      * @default true
      */
     pruneUnused?: boolean;
+    /**
+     * A list of CSS variables that should always be included in the final CSS, you can use this to prevent certain variables from being pruned.
+     *
+     * @default []
+     * @example
+     * ```ts
+     * {
+     *   variables: {
+     *     safeList: ['--external-var', '--color-bg', '--color-text'],
+     *   },
+     * }
+     * ```
+     */
+    safeList?: ((`--${string}` & {}) | ResolvedCSSVarProperty)[];
 }
 declare module '@pikacss/core' {
     interface EngineConfig {
@@ -242,14 +265,15 @@ declare module '@pikacss/core' {
     }
     interface Engine {
         variables: {
-            store: Map<string, ResolvedVariableConfig>;
-            add: (...list: Variable[]) => void;
+            store: Map<string, ResolvedVariable[]>;
+            add: (variables: VariablesDefinition) => void;
         };
     }
 }
-interface ResolvedVariableConfig {
+interface ResolvedVariable {
     name: string;
-    value: string | Nullish;
+    value: PropertyValue;
+    selector: string[];
     pruneUnused: boolean;
     autocomplete: {
         asValueOf: string[];
@@ -273,42 +297,6 @@ type FromKebab<T extends string> = T extends `--${string}` ? T : T extends `-${i
 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 ResolveFrom<T, Key extends string, I, Fallback extends I> = Key extends keyof T ? T[Key] extends I ? T[Key] : Fallback : Fallback;
 
-interface PikaAugment {
-}
-type PropertyValue = string | number | [value: string | number, fallback: (string | number)[]] | Nullish;
-type Properties$1 = Record<string, PropertyValue>;
-interface StyleDefinition$1 {
-    [K: string]: PropertyValue | StyleDefinition$1 | StyleItem$1[];
-}
-type StyleItem$1 = string | StyleDefinition$1;
-interface ExtractedStyleContent {
-    selector: string[];
-    property: string;
-    value: string[] | Nullish;
-}
-interface StyleContent {
-    selector: string[];
-    property: string;
-    value: string[];
-}
-interface AtomicStyle {
-    id: string;
-    content: StyleContent;
-}
-interface CSSStyleBlockBody {
-    properties: {
-        property: string;
-        value: string;
-    }[];
-    children?: CSSStyleBlocks;
-}
-type CSSStyleBlocks = Map<string, CSSStyleBlockBody>;
-type ResolvedSelector = ResolveFrom<PikaAugment, 'Selector', string, string>;
-type ResolvedCSSProperty = ResolveFrom<PikaAugment, 'CSSProperty', string, string>;
-type ResolvedProperties = ResolveFrom<PikaAugment, 'Properties', any, Properties$1>;
-type ResolvedStyleDefinition = ResolveFrom<PikaAugment, 'StyleDefinition', any, StyleDefinition$1>;
-type ResolvedStyleItem = ResolveFrom<PikaAugment, 'StyleItem', any, StyleItem$1>;
-
 interface ResolvedAutocompleteConfig {
     selectors: Set<string>;
     styleItemStrings: Set<string>;
@@ -334,7 +322,6 @@ type EmptyAutocomplete = DefineAutocomplete<{
     PropertiesValue: never;
     CssPropertiesValue: never;
 }>;
-type ResolvedAutocomplete = ResolveFrom<PikaAugment, 'Autocomplete', _Autocomplete, EmptyAutocomplete>;
 
 type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
 type EngineHooksDefinition = DefineHooks<{
@@ -358,10 +345,48 @@ interface EnginePlugin extends EnginePluginHooksOptions {
 }
 declare function defineEnginePlugin(plugin: EnginePlugin): EnginePlugin;
 
+interface PikaAugment {
+}
+type PropertyValue = string | number | [value: string | number, fallback: (string | number)[]] | Nullish;
+type Properties$1 = Record<string, PropertyValue>;
+interface StyleDefinition$1 {
+    [K: string]: PropertyValue | StyleDefinition$1 | StyleItem$1[];
+}
+type StyleItem$1 = string | StyleDefinition$1;
+interface ExtractedStyleContent {
+    selector: string[];
+    property: string;
+    value: string[] | Nullish;
+}
+interface StyleContent {
+    selector: string[];
+    property: string;
+    value: string[];
+}
+interface AtomicStyle {
+    id: string;
+    content: StyleContent;
+}
+interface CSSStyleBlockBody {
+    properties: {
+        property: string;
+        value: string;
+    }[];
+    children?: CSSStyleBlocks;
+}
+type CSSStyleBlocks = Map<string, CSSStyleBlockBody>;
+
+type ResolvedAutocomplete = ResolveFrom<PikaAugment, 'Autocomplete', _Autocomplete, EmptyAutocomplete>;
+type ResolvedSelector = ResolveFrom<PikaAugment, 'Selector', string, string>;
+type ResolvedProperties = ResolveFrom<PikaAugment, 'Properties', any, Properties$1>;
+type ResolvedCSSProperties = Omit<ResolvedProperties, ResolvedAutocomplete['ExtraProperty']>;
+type ResolvedStyleDefinition = ResolveFrom<PikaAugment, 'StyleDefinition', any, StyleDefinition$1>;
+type ResolvedStyleItem = ResolveFrom<PikaAugment, 'StyleItem', any, StyleItem$1>;
+
 type PreflightDefinition = {
-    [selector in UnionString | ResolvedSelector]?: ResolvedProperties | PreflightDefinition;
+    [selector in UnionString | ResolvedSelector]?: ResolvedCSSProperties | PreflightDefinition;
 };
-type PreflightFn = (engine: Engine, isFormatted: boolean) => string | PreflightDefinition;
+type PreflightFn = (engine: Engine, isFormatted: boolean) => Awaitable<string | PreflightDefinition>;
 /**
  * PreflightConfig can be a string or a function that returns a string.
  *
@@ -445,6 +470,18 @@ declare function defineEngineConfig(config: EngineConfig): EngineConfig;
 declare function createEngine(config?: EngineConfig): Promise<Engine>;
 declare class Engine {
     config: ResolvedEngineConfig;
+    pluginHooks: {
+        configureRawConfig: (plugins: _pikacss_core.EnginePlugin[], payload: EngineConfig) => Promise<EngineConfig>;
+        rawConfigConfigured: (plugins: _pikacss_core.EnginePlugin[], payload: EngineConfig) => void;
+        configureResolvedConfig: (plugins: _pikacss_core.EnginePlugin[], payload: ResolvedEngineConfig) => Promise<ResolvedEngineConfig>;
+        configureEngine: (plugins: _pikacss_core.EnginePlugin[], payload: Engine) => Promise<Engine>;
+        transformSelectors: (plugins: _pikacss_core.EnginePlugin[], payload: string[]) => Promise<string[]>;
+        transformStyleItems: (plugins: _pikacss_core.EnginePlugin[], payload: StyleItem$1[]) => Promise<StyleItem$1[]>;
+        transformStyleDefinitions: (plugins: _pikacss_core.EnginePlugin[], payload: StyleDefinition$1[]) => Promise<StyleDefinition$1[]>;
+        preflightUpdated: (plugins: _pikacss_core.EnginePlugin[]) => void;
+        atomicStyleAdded: (plugins: _pikacss_core.EnginePlugin[], payload: AtomicStyle) => AtomicStyle;
+        autocompleteConfigUpdated: (plugins: _pikacss_core.EnginePlugin[]) => void;
+    };
     extract: ExtractFn;
     store: {
         atomicStyleIds: Map<string, string>;

package/dist/index.mjs

@@ -275,7 +275,7 @@ function keyframes() {
   return defineEnginePlugin({
     name: "core:keyframes",
     rawConfigConfigured(config) {
-      resolveKeyframesConfig = createResolveConfigFn$1({
+      resolveKeyframesConfig = createResolveConfigFn({
         pruneUnused: config.keyframes?.pruneUnused
       });
       configList = config.keyframes?.keyframes ?? [];
@@ -298,7 +298,7 @@ function keyframes() {
         }
       };
       engine.keyframes.add(...configList);
-      engine.addPreflight((engine2, isFormatted) => {
+      engine.addPreflight((engine2) => {
         const maybeUsedName = /* @__PURE__ */ new Set();
         engine2.store.atomicStyles.forEach(({ content: { property, value } }) => {
           if (property === "animationName") {
@@ -314,30 +314,22 @@ function keyframes() {
             });
           }
         });
-        return renderCSSStyleBlocks(
-          new Map(Array.from(engine2.keyframes.store.entries()).filter(([name, { pruneUnused }]) => pruneUnused === false || maybeUsedName.has(name)).map(([name, { frames }]) => [
-            `@keyframes ${name}`,
-            {
-              properties: [],
-              children: new Map(Object.entries(frames).map(([frame, properties]) => [
-                frame,
-                {
-                  properties: Object.entries(properties).filter(([_, value]) => isNotNullish(value)).flatMap(([property, value]) => {
-                    if (Array.isArray(value))
-                      return value.map((v) => ({ property, value: String(v) }));
-                    return { property, value: String(value) };
-                  })
-                }
-              ]))
-            }
-          ])),
-          isFormatted
-        );
+        const maybeUsedKeyframes = Array.from(engine2.keyframes.store.values()).filter(({ name, frames, pruneUnused }) => (pruneUnused === false || maybeUsedName.has(name)) && frames != null);
+        const preflightDefinition = {};
+        maybeUsedKeyframes.forEach(({ name, frames }) => {
+          preflightDefinition[`@keyframes ${name}`] = Object.fromEntries(
+            Object.entries(frames).map(([frame, properties]) => [
+              frame,
+              properties
+            ])
+          );
+        });
+        return preflightDefinition;
       });
     }
   });
 }
-function createResolveConfigFn$1({
+function createResolveConfigFn({
   pruneUnused: defaultPruneUnused = true
 } = {}) {
   return function resolveKeyframesConfig(config) {
@@ -684,67 +676,92 @@ function resolveShortcutConfig(config) {
 }
 
 function variables() {
-  let resolveVariableConfig;
-  let configList;
+  let resolveVariables;
+  let rawVariables;
+  let safeSet;
   return defineEnginePlugin({
     name: "core:variables",
     rawConfigConfigured(config) {
-      resolveVariableConfig = createResolveConfigFn({
+      resolveVariables = createResolveVariablesFn({
         pruneUnused: config.variables?.pruneUnused
       });
-      configList = config.variables?.variables ?? [];
+      rawVariables = config.variables?.variables ?? {};
+      safeSet = new Set(config.variables?.safeList ?? []);
     },
     configureEngine(engine) {
       engine.variables = {
         store: /* @__PURE__ */ new Map(),
-        add: (...list) => {
-          list.forEach((config) => {
-            const resolved = resolveVariableConfig(config);
-            const { name: _name, value, autocomplete: { asValueOf, asProperty } } = resolved;
-            const name = normalizeVariableName(_name);
+        add: (variables2) => {
+          const list = resolveVariables(variables2);
+          list.forEach((resolved) => {
+            const { name, value, autocomplete: { asValueOf, asProperty } } = resolved;
             asValueOf.forEach((p) => {
               if (p !== "-")
                 engine.appendAutocompleteCssPropertyValues(p, `var(${name})`);
             });
             if (asProperty)
               engine.appendAutocompleteExtraCssProperties(name);
-            if (value != null)
-              engine.variables.store.set(name, resolved);
+            if (value != null) {
+              const list2 = engine.variables.store.get(name) ?? [];
+              list2.push(resolved);
+              engine.variables.store.set(name, list2);
+            }
           });
           engine.notifyPreflightUpdated();
         }
       };
-      engine.variables.add(...configList);
-      engine.addPreflight((engine2, isFormatted) => {
+      engine.variables.add(rawVariables);
+      engine.addPreflight(async (engine2) => {
         const used = /* @__PURE__ */ new Set();
         engine2.store.atomicStyles.forEach(({ content: { value } }) => {
           value.flatMap(extractUsedVarNames).forEach((name) => used.add(normalizeVariableName(name)));
         });
-        return renderCSSStyleBlocks(
-          /* @__PURE__ */ new Map([[
-            ":root",
-            {
-              properties: Array.from(engine2.variables.store.entries()).filter(([name, { pruneUnused, value }]) => (pruneUnused === false || used.has(name)) && value != null).map(([name, { value }]) => ({ property: name, value }))
-            }
-          ]]),
-          isFormatted
-        );
+        const usedVariables = Array.from(engine2.variables.store.values()).flat().filter(({ name, pruneUnused, value }) => (safeSet.has(name) || pruneUnused === false || used.has(name)) && value != null);
+        const preflightDefinition = {};
+        for (const { name, value, selector: _selector } of usedVariables) {
+          const selector = await engine2.pluginHooks.transformSelectors(engine2.config.plugins, _selector);
+          let current = preflightDefinition;
+          selector.forEach((s) => {
+            current[s] ||= {};
+            current = current[s];
+          });
+          Object.assign(current, { [name]: value });
+        }
+        return preflightDefinition;
       });
     }
   });
 }
-function createResolveConfigFn({
+function createResolveVariablesFn({
   pruneUnused: defaultPruneUnused = true
 } = {}) {
-  return function resolveVariableConfig(config) {
-    if (typeof config === "string")
-      return { name: config, value: null, autocomplete: { asValueOf: ["*"], asProperty: true }, pruneUnused: defaultPruneUnused };
-    if (Array.isArray(config)) {
-      const [name2, value2, { asValueOf: asValueOf2 = "*", asProperty: asProperty2 = true } = {}, pruneUnused2 = defaultPruneUnused] = config;
-      return { name: name2, value: value2, autocomplete: { asValueOf: [asValueOf2].flat(), asProperty: asProperty2 }, pruneUnused: pruneUnused2 };
+  function _resolveVariables(variables2, levels, result) {
+    for (const [key, value] of Object.entries(variables2)) {
+      if (key.startsWith("--")) {
+        const isObject = typeof value === "object" && value !== null && !Array.isArray(value);
+        const {
+          value: varValue,
+          autocomplete = {},
+          pruneUnused = defaultPruneUnused
+        } = isObject ? value : { value };
+        result.push({
+          name: key,
+          value: varValue,
+          selector: levels.length > 0 ? levels : [":root"],
+          autocomplete: {
+            asValueOf: autocomplete.asValueOf ? [autocomplete.asValueOf].flat() : ["*"],
+            asProperty: autocomplete.asProperty ?? true
+          },
+          pruneUnused
+        });
+      } else {
+        _resolveVariables(value, [...levels, key], result);
+      }
     }
-    const { name, value, autocomplete: { asValueOf = "*", asProperty = true } = {}, pruneUnused = defaultPruneUnused } = config;
-    return { name, value, autocomplete: { asValueOf: [asValueOf].flat(), asProperty }, pruneUnused };
+    return result;
+  }
+  return function resolveVariables(variables2) {
+    return _resolveVariables(variables2, [], []);
   };
 }
 const VAR_NAME_RE = /var\((--[\w-]+)/g;
@@ -798,6 +815,7 @@ async function createEngine(config = {}) {
 }
 class Engine {
   config;
+  pluginHooks = hooks;
   extract;
   store = {
     atomicStyleIds: /* @__PURE__ */ new Map(),
@@ -876,13 +894,13 @@ class Engine {
   }
   async renderPreflights(isFormatted) {
     const lineEnd = isFormatted ? "\n" : "";
-    return (await Promise.all(this.config.preflights.map((p) => {
-      const result = p(this, isFormatted);
+    return (await Promise.all(this.config.preflights.map(async (p) => {
+      const result = await p(this, isFormatted);
       if (typeof result === "string")
         return result;
-      return renderPreflight({
+      return renderPreflightDefinition({
         engine: this,
-        preflight: result,
+        preflightDefinition: result,
         isFormatted
       });
     }))).join(lineEnd);
@@ -1006,7 +1024,7 @@ function renderAtomicStyles(payload) {
   });
   return renderCSSStyleBlocks(blocks, isFormatted);
 }
-async function _renderPreflight({
+async function _renderPreflightDefinition({
   engine,
   preflightDefinition,
   blocks = /* @__PURE__ */ new Map()
@@ -1039,7 +1057,7 @@ async function _renderPreflight({
       } else {
         currentBlockBody.children ||= /* @__PURE__ */ new Map();
         currentBlockBody.children.set(k, currentBlockBody.children.get(k) || { properties: [] });
-        _renderPreflight({
+        _renderPreflightDefinition({
           engine,
           preflightDefinition: { [k]: v },
           blocks: currentBlockBody.children
@@ -1049,11 +1067,11 @@ async function _renderPreflight({
   }
   return blocks;
 }
-async function renderPreflight(payload) {
-  const { engine, preflight, isFormatted } = payload;
-  const blocks = await _renderPreflight({
+async function renderPreflightDefinition(payload) {
+  const { engine, preflightDefinition, isFormatted } = payload;
+  const blocks = await _renderPreflightDefinition({
     engine,
-    preflightDefinition: preflight
+    preflightDefinition
   });
   return renderCSSStyleBlocks(blocks, isFormatted);
 }

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.0.28",
+  "version": "0.0.29",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
   "repository": {