@pikacss/core 0.0.40 → 0.0.42

package/dist/index.cjs

@@ -752,6 +752,12 @@ function normalizeVariableName(name) {
 
 //#endregion
 //#region src/internal/engine.ts
+const DEFAULT_PREFLIGHTS_LAYER = "preflights";
+const DEFAULT_UTILITIES_LAYER = "utilities";
+const DEFAULT_LAYERS = {
+	[DEFAULT_PREFLIGHTS_LAYER]: 1,
+	[DEFAULT_UTILITIES_LAYER]: 10
+};
 async function createEngine(config = {}) {
 	log.debug("Creating engine with config:", config);
 	const corePlugins = [
@@ -771,6 +777,8 @@ async function createEngine(config = {}) {
 	log.debug("Engine config resolved with prefix:", resolvedConfig.prefix);
 	resolvedConfig = await hooks.configureResolvedConfig(resolvedConfig.plugins, resolvedConfig);
 	let engine = new Engine(resolvedConfig);
+	engine.appendAutocompleteExtraProperties("__layer");
+	engine.appendAutocompletePropertyValues("__layer", "Autocomplete['Layer']");
 	log.debug("Engine instance created");
 	engine = await hooks.configureEngine(engine.config.plugins, engine);
 	log.debug("Engine initialized successfully");
@@ -863,17 +871,39 @@ var Engine = class {
 	async renderPreflights(isFormatted) {
 		log.debug("Rendering preflights...");
 		const lineEnd = isFormatted ? "\n" : "";
-		const results = await Promise.all(this.config.preflights.map(async (p) => {
-			const result = await p(this, isFormatted);
-			if (typeof result === "string") return result;
-			return renderPreflightDefinition({
-				engine: this,
-				preflightDefinition: result,
-				isFormatted
-			});
+		const rendered = await Promise.all(this.config.preflights.map(async ({ layer, fn }) => {
+			const result = await fn(this, isFormatted);
+			return {
+				layer,
+				css: typeof result === "string" ? result : await renderPreflightDefinition({
+					engine: this,
+					preflightDefinition: result,
+					isFormatted
+				})
+			};
 		}));
-		log.debug(`Rendered ${results.length} preflights`);
-		return results.join(lineEnd);
+		log.debug(`Rendered ${rendered.length} preflights`);
+		const unlayeredParts = [];
+		const layerGroups = /* @__PURE__ */ new Map();
+		for (const { layer, css } of rendered) if (layer == null) unlayeredParts.push(css);
+		else {
+			if (!layerGroups.has(layer)) layerGroups.set(layer, []);
+			layerGroups.get(layer).push(css);
+		}
+		const outputParts = [];
+		if (unlayeredParts.length > 0) {
+			const unlayeredContent = unlayeredParts.join(lineEnd);
+			const { defaultPreflightsLayer } = this.config;
+			if (defaultPreflightsLayer in this.config.layers) outputParts.push(`@layer ${defaultPreflightsLayer} {${lineEnd}${unlayeredContent}${lineEnd}}`);
+			else outputParts.push(unlayeredContent);
+		}
+		const configLayerOrder = sortLayerNames(this.config.layers);
+		const orderedLayerNames = [...configLayerOrder.filter((name) => layerGroups.has(name)), ...[...layerGroups.keys()].filter((name) => !configLayerOrder.includes(name))];
+		for (const layerName of orderedLayerNames) {
+			const content = layerGroups.get(layerName).join(lineEnd);
+			outputParts.push(`@layer ${layerName} {${lineEnd}${content}${lineEnd}}`);
+		}
+		return outputParts.join(lineEnd);
 	}
 	async renderAtomicStyles(isFormatted, options = {}) {
 		log.debug("Rendering atomic styles...");
@@ -884,19 +914,45 @@ var Engine = class {
 			atomicStyles,
 			isPreview,
 			isFormatted,
-			defaultSelector: this.config.defaultSelector
+			defaultSelector: this.config.defaultSelector,
+			layers: this.config.layers,
+			defaultUtilitiesLayer: this.config.defaultUtilitiesLayer
 		});
 	}
+	renderLayerOrderDeclaration() {
+		const { layers } = this.config;
+		if (Object.keys(layers).length === 0) return "";
+		return `@layer ${sortLayerNames(layers).join(", ")};`;
+	}
 };
 function calcAtomicStyleRenderingWeight(style, defaultSelector) {
 	const { selector } = style.content;
 	return selector.length === 1 && selector[0] === defaultSelector ? 0 : selector.length;
 }
+function sortLayerNames(layers) {
+	return Object.entries(layers).sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0])).map(([name]) => name);
+}
+function isWithLayer(p) {
+	if (typeof p !== "object" || p === null) return false;
+	const record = p;
+	return typeof record.layer === "string" && "preflight" in record;
+}
 function resolvePreflight(preflight) {
-	return typeof preflight === "function" ? preflight : () => preflight;
+	if (isWithLayer(preflight)) {
+		const inner = preflight.preflight;
+		const fn = typeof inner === "function" ? inner : () => inner;
+		return {
+			layer: preflight.layer,
+			fn
+		};
+	}
+	return { fn: typeof preflight === "function" ? preflight : () => preflight };
 }
 async function resolveEngineConfig(config) {
 	const { prefix = "", defaultSelector = `.${ATOMIC_STYLE_ID_PLACEHOLDER}`, plugins = [], preflights = [] } = config;
+	const layers = Object.assign({}, DEFAULT_LAYERS, config.layers);
+	const defaultPreflightsLayer = config.defaultPreflightsLayer ?? DEFAULT_PREFLIGHTS_LAYER;
+	const defaultUtilitiesLayer = config.defaultUtilitiesLayer ?? DEFAULT_UTILITIES_LAYER;
 	log.debug(`Resolving engine config with prefix: "${prefix}", plugins: ${plugins.length}, preflights: ${preflights.length}`);
 	const resolvedConfig = {
 		rawConfig: config,
@@ -904,6 +960,9 @@ async function resolveEngineConfig(config) {
 		prefix,
 		defaultSelector,
 		preflights: [],
+		layers,
+		defaultPreflightsLayer,
+		defaultUtilitiesLayer,
 		autocomplete: {
 			selectors: /* @__PURE__ */ new Set(),
 			styleItemStrings: /* @__PURE__ */ new Set(),
@@ -922,7 +981,8 @@ function getAtomicStyleId({ content, prefix, stored }) {
 	const key = serialize([
 		content.selector,
 		content.property,
-		content.value
+		content.value,
+		content.layer
 	]);
 	const cached = stored.get(key);
 	if (cached != null) {
@@ -938,29 +998,51 @@ function getAtomicStyleId({ content, prefix, stored }) {
 function optimizeAtomicStyleContents(list) {
 	const map = /* @__PURE__ */ new Map();
 	list.forEach((content) => {
-		const key = serialize([content.selector, content.property]);
+		const key = serialize([
+			content.selector,
+			content.property,
+			content.layer
+		]);
 		map.delete(key);
 		if (content.value == null) return;
-		map.set(key, content);
+		map.set(key, { ...content });
 	});
 	return [...map.values()];
 }
+function extractLayerFromStyleItem(item) {
+	const record = item;
+	const layer = typeof record.__layer === "string" ? record.__layer : void 0;
+	if (layer == null) return {
+		layer: void 0,
+		definition: item
+	};
+	const { __layer: _, ...rest } = record;
+	return {
+		layer,
+		definition: rest
+	};
+}
 async function resolveStyleItemList({ itemList, transformStyleItems, extractStyleDefinition }) {
 	const unknown = /* @__PURE__ */ new Set();
 	const list = [];
 	for (const styleItem of await transformStyleItems(itemList)) if (typeof styleItem === "string") unknown.add(styleItem);
-	else list.push(...await extractStyleDefinition(styleItem));
+	else {
+		const { layer, definition } = extractLayerFromStyleItem(styleItem);
+		const extracted = await extractStyleDefinition(definition);
+		if (layer != null) extracted.forEach((c) => c.layer = layer);
+		list.push(...extracted);
+	}
 	return {
 		unknown,
 		contents: optimizeAtomicStyleContents(list)
 	};
 }
-function renderAtomicStyles(payload) {
-	const { atomicStyles, isPreview, isFormatted, defaultSelector } = payload;
+function sortAtomicStyles(styles, defaultSelector) {
+	return [...styles].sort((a, b) => calcAtomicStyleRenderingWeight(a, defaultSelector) - calcAtomicStyleRenderingWeight(b, defaultSelector));
+}
+function renderAtomicStylesCss({ atomicStyles, isPreview, isFormatted }) {
 	const blocks = /* @__PURE__ */ new Map();
-	Array.from(atomicStyles).sort((a, b) => {
-		return calcAtomicStyleRenderingWeight(a, defaultSelector) - calcAtomicStyleRenderingWeight(b, defaultSelector);
-	}).forEach(({ id, content: { selector, property, value } }) => {
+	atomicStyles.forEach(({ id, content: { selector, property, value } }) => {
 		if (selector.some((s) => s.includes(ATOMIC_STYLE_ID_PLACEHOLDER)) === false || value == null) return;
 		const renderObject = {
 			selector: isPreview ? selector : selector.map((s) => s.replace(ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL, id)),
@@ -982,6 +1064,47 @@ function renderAtomicStyles(payload) {
 	});
 	return renderCSSStyleBlocks(blocks, isFormatted);
 }
+function renderAtomicStyles(payload) {
+	const { atomicStyles, isPreview, isFormatted, defaultSelector, layers, defaultUtilitiesLayer } = payload;
+	const sortedStyles = sortAtomicStyles(atomicStyles, defaultSelector);
+	if (layers == null) return renderAtomicStylesCss({
+		atomicStyles: sortedStyles,
+		isPreview,
+		isFormatted
+	});
+	const layerOrder = sortLayerNames(layers);
+	const lineEnd = isFormatted ? "\n" : "";
+	const unlayeredStyles = [];
+	const layerGroups = new Map(layerOrder.map((name) => [name, []]));
+	const candidateDefaultLayer = defaultUtilitiesLayer ?? layerOrder[layerOrder.length - 1];
+	const defaultLayer = candidateDefaultLayer != null && layerGroups.has(candidateDefaultLayer) ? candidateDefaultLayer : layerOrder[layerOrder.length - 1];
+	for (const style of sortedStyles) {
+		const layer = style.content.layer;
+		if (layer != null && layerGroups.has(layer)) layerGroups.get(layer).push(style);
+		else if (layer != null) {
+			log.warn(`Unknown layer "${layer}" encountered in atomic style; falling back to unlayered output.`);
+			unlayeredStyles.push(style);
+		} else if (defaultLayer != null) layerGroups.get(defaultLayer).push(style);
+		else unlayeredStyles.push(style);
+	}
+	const parts = [];
+	if (unlayeredStyles.length > 0) parts.push(renderAtomicStylesCss({
+		atomicStyles: unlayeredStyles,
+		isPreview,
+		isFormatted
+	}));
+	for (const layerName of layerOrder) {
+		const styles = layerGroups.get(layerName);
+		if (styles.length === 0) continue;
+		const innerCss = renderAtomicStylesCss({
+			atomicStyles: styles,
+			isPreview,
+			isFormatted
+		});
+		parts.push(`@layer ${layerName} {${lineEnd}${innerCss}${lineEnd}}`);
+	}
+	return parts.join(lineEnd);
+}
 async function _renderPreflightDefinition({ engine, preflightDefinition, blocks = /* @__PURE__ */ new Map() }) {
 	for (const [selector, propertiesOrDefinition] of Object.entries(preflightDefinition)) {
 		if (propertiesOrDefinition == null) continue;
@@ -1070,4 +1193,5 @@ exports.defineShortcut = defineShortcut;
 exports.defineStyleDefinition = defineStyleDefinition;
 exports.defineVariables = defineVariables;
 exports.log = log;
-exports.renderCSSStyleBlocks = renderCSSStyleBlocks;
+exports.renderCSSStyleBlocks = renderCSSStyleBlocks;
+exports.sortLayerNames = sortLayerNames;

package/dist/index.d.cts

@@ -26,7 +26,7 @@ interface DynamicRule<T> {
   createResolved: (matched: RegExpMatchArray) => Awaitable<T>;
 }
 declare abstract class AbstractResolver<T> {
-  protected _resolvedResultsMap: Map<string, ResolvedResult<T>>;
+  _resolvedResultsMap: Map<string, ResolvedResult<T>>;
   staticRulesMap: Map<string, StaticRule<T>>;
   dynamicRulesMap: Map<string, DynamicRule<T>>;
   onResolved: (string: string, type: 'static' | 'dynamic', result: ResolvedResult<T>) => void;
@@ -269,6 +269,7 @@ interface _Autocomplete {
   StyleItemString: UnionString;
   ExtraProperty: UnionString;
   ExtraCssProperty: UnionString;
+  Layer: UnionString;
   PropertiesValue: Record<string, unknown>;
   CssPropertiesValue: Record<string, UnionString | UnionNumber>;
 }
@@ -278,6 +279,7 @@ type EmptyAutocomplete = DefineAutocomplete<{
   StyleItemString: never;
   ExtraProperty: never;
   ExtraCssProperty: never;
+  Layer: never;
   PropertiesValue: never;
   CssPropertiesValue: never;
 }>;
@@ -323,21 +325,25 @@ declare class Engine {
     atomicStyleIds?: string[];
     isPreview?: boolean;
   }): Promise<string>;
+  renderLayerOrderDeclaration(): string;
 }
+declare function sortLayerNames(layers: Record<string, number>): string[];
 //#endregion
 //#region src/internal/plugin.d.ts
-interface EnginePluginHooksOptions {
-  configureRawConfig?: (config: EngineConfig$1) => Awaitable<EngineConfig$1 | void>;
-  rawConfigConfigured?: (config: EngineConfig$1) => void;
-  configureResolvedConfig?: (resolvedConfig: ResolvedEngineConfig) => Awaitable<ResolvedEngineConfig | void>;
-  configureEngine?: (engine: Engine) => Awaitable<void>;
-  transformSelectors?: (selectors: string[]) => Awaitable<string[] | void>;
-  transformStyleItems?: (styleItems: ResolvedStyleItem[]) => Awaitable<ResolvedStyleItem[] | void>;
-  transformStyleDefinitions?: (styleDefinitions: ResolvedStyleDefinition[]) => Awaitable<ResolvedStyleDefinition[] | void>;
-  preflightUpdated?: () => void;
-  atomicStyleAdded?: (atomicStyle: AtomicStyle) => void;
-  autocompleteConfigUpdated?: () => void;
-}
+type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
+type EngineHooksDefinition = DefineHooks<{
+  configureRawConfig: ['async', config: EngineConfig$1];
+  rawConfigConfigured: ['sync', config: EngineConfig$1, void];
+  configureResolvedConfig: ['async', resolvedConfig: ResolvedEngineConfig];
+  configureEngine: ['async', engine: Engine];
+  transformSelectors: ['async', selectors: string[]];
+  transformStyleItems: ['async', styleItems: ResolvedStyleItem[]];
+  transformStyleDefinitions: ['async', styleDefinitions: ResolvedStyleDefinition[]];
+  preflightUpdated: ['sync', void];
+  atomicStyleAdded: ['sync', AtomicStyle];
+  autocompleteConfigUpdated: ['sync', void];
+}>;
+type EnginePluginHooksOptions = { [K in keyof EngineHooksDefinition]?: EngineHooksDefinition[K][0] extends 'async' ? (...params: EngineHooksDefinition[K][1] extends void ? [] : [payload: EngineHooksDefinition[K][1]]) => Awaitable<EngineHooksDefinition[K][1] | void> : (...params: EngineHooksDefinition[K][1] extends void ? [] : [payload: EngineHooksDefinition[K][1]]) => EngineHooksDefinition[K][1] | void };
 interface EnginePlugin extends EnginePluginHooksOptions {
   name: string;
   order?: 'pre' | 'post';
@@ -353,7 +359,7 @@ type CSSProperty = keyof CSSProperties;
 type PropertyValue<T> = T | [value: T, fallback: T[]] | Nullish;
 type Properties_CSS = { [Key in keyof CSSProperties]?: PropertyValue<Exclude<UnionString | UnionNumber | GetValue<CSSProperties, Key> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], ToKebab<Key>> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], FromKebab<Key>> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], '*'>, Nullish>> };
 type Properties_ExtraCSS = { [Key in keyof ResolvedAutocomplete['ExtraCssProperty']]?: PropertyValue<Exclude<UnionString | UnionNumber | GetValue<CSSProperties, Key & string> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], ToKebab<Key & string>> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], FromKebab<Key & string>> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], '*'>, Nullish>> };
-type Properties_Extra = { [Key in keyof ResolvedAutocomplete['ExtraProperty']]?: GetValue<ResolvedAutocomplete['PropertiesValue'], Key & string> };
+type Properties_Extra = { [Key in ResolvedAutocomplete['ExtraProperty']]?: GetValue<ResolvedAutocomplete['PropertiesValue'], Key & string> };
 interface Properties extends Properties_CSS, Properties_ExtraCSS, Properties_Extra {}
 type CSSPseudos = `${'$'}${CSS.Pseudos}`;
 type CSSBlockAtRules = Exclude<CSS.AtRules, '@charset' | 'import' | '@namespace'>;
@@ -372,11 +378,13 @@ interface ExtractedStyleContent {
   selector: string[];
   property: string;
   value: string[] | Nullish;
+  layer?: string;
 }
 interface StyleContent {
   selector: string[];
   property: string;
   value: string[];
+  layer?: string;
 }
 interface AtomicStyle {
   id: string;
@@ -393,6 +401,7 @@ type CSSStyleBlocks = Map<string, CSSStyleBlockBody>;
 //#endregion
 //#region src/internal/types/resolved.d.ts
 type ResolvedAutocomplete = ResolveFrom<PikaAugment, 'Autocomplete', _Autocomplete, EmptyAutocomplete>;
+type ResolvedLayerName = IsNever<ResolvedAutocomplete['Layer']> extends true ? UnionString : ResolvedAutocomplete['Layer'];
 type ResolvedSelector = ResolveFrom<PikaAugment, 'Selector', string, string>;
 type ResolvedProperties = ResolveFrom<PikaAugment, 'Properties', any, InternalProperties>;
 type ResolvedCSSProperties = Omit<ResolvedProperties, ResolvedAutocomplete['ExtraProperty']>;
@@ -402,13 +411,23 @@ type ResolvedStyleItem = ResolveFrom<PikaAugment, 'StyleItem', any, InternalStyl
 //#region src/internal/types/preflight.d.ts
 type PreflightDefinition = { [selector in UnionString | ResolvedSelector]?: ResolvedCSSProperties | PreflightDefinition };
 type PreflightFn = (engine: Engine, isFormatted: boolean) => Awaitable<string | PreflightDefinition>;
+interface WithLayer<T extends string | PreflightDefinition | PreflightFn> {
+  layer: string;
+  preflight: T;
+}
+interface ResolvedPreflight {
+  layer?: string;
+  fn: PreflightFn;
+}
 /**
- * PreflightConfig can be a string or a function that returns a string.
+ * Preflight can be a string, object, function, or a layer-wrapped variant.
  *
- * 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.
+ * 1. A `string` is a static preflight style injected verbatim.
+ * 2. A `PreflightDefinition` is a JS object describing CSS rules.
+ * 3. A `PreflightFn` is a dynamic preflight that receives the engine instance.
+ * 4. A `WithLayer` wrapper assigns any of the above to a specific CSS `@layer`.
  */
-type Preflight = string | PreflightDefinition | PreflightFn;
+type Preflight = string | PreflightDefinition | PreflightFn | WithLayer<string | PreflightDefinition | PreflightFn>;
 //#endregion
 //#region src/internal/types/engine.d.ts
 interface EngineConfig$1 {
@@ -470,14 +489,44 @@ interface EngineConfig$1 {
    * ```
    */
   preflights?: Preflight[];
+  /**
+   * Configure CSS @layer order. Keys are layer names, values are order numbers (lower = earlier).
+   * Merged on top of the default layers `{ preflights: 1, utilities: 10 }`, so any keys not
+   * specified here will keep their default order values.
+   *
+   * @default { preflights: 1, utilities: 10 }
+   * @example
+   * ```ts
+   * {
+   *   layers: { base: 0, components: 5, utilities: 10 }
+   * }
+   * ```
+   */
+  layers?: Record<string, number>;
+  /**
+   * The layer name that unlayered preflights are automatically wrapped into.
+   *
+   * @default 'preflights'
+   */
+  defaultPreflightsLayer?: string;
+  /**
+   * The layer name that atomic styles without an explicit `__layer` are placed into.
+   *
+   * @default 'utilities'
+   */
+  defaultUtilitiesLayer?: string;
 }
 interface ResolvedEngineConfig {
   rawConfig: EngineConfig$1;
   prefix: string;
   defaultSelector: string;
   plugins: EnginePlugin[];
-  preflights: PreflightFn[];
+  preflights: ResolvedPreflight[];
   autocomplete: ResolvedAutocompleteConfig;
+  /** Always contains at least the default layers (`preflights` and `utilities`). */
+  layers: Record<string, number>;
+  defaultPreflightsLayer: string;
+  defaultUtilitiesLayer: string;
 }
 //#endregion
 //#region src/internal/plugins/keyframes.d.ts
@@ -585,4 +634,4 @@ declare function defineSelector(selector: Selector): Selector;
 declare function defineShortcut(shortcut: Shortcut): Shortcut;
 declare function defineVariables(variables: VariablesDefinition): VariablesDefinition;
 //#endregion
-export { Arrayable, Awaitable, type CSSProperty, type CSSSelector, type CSSStyleBlockBody, type CSSStyleBlocks, type DefineAutocomplete, type Engine, type EngineConfig$1 as EngineConfig, type EnginePlugin, FromKebab, GetValue, IsEqual, IsNever, Keyframes, KeyframesConfig, KeyframesProgress, Nullish, type PikaAugment, type Properties, ResolveFrom, Selector, SelectorsConfig, Shortcut, ShortcutsConfig, Simplify, type StyleDefinition, type StyleItem, ToKebab, UnionNumber, UnionString, UnionToIntersection, Variable, VariableAutocomplete, VariableObject, VariablesConfig, VariablesDefinition, appendAutocompleteCssPropertyValues, appendAutocompleteExtraCssProperties, appendAutocompleteExtraProperties, appendAutocompletePropertyValues, appendAutocompleteSelectors, appendAutocompleteStyleItemStrings, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, defineKeyframes, definePreflight, defineSelector, defineShortcut, defineStyleDefinition, defineVariables, extractUsedVarNames, important, keyframes, log, normalizeVariableName, renderCSSStyleBlocks, resolveSelectorConfig, selectors$1 as selectors, shortcuts, variables };
+export { Arrayable, Awaitable, type CSSProperty, type CSSSelector, type CSSStyleBlockBody, type CSSStyleBlocks, type DefineAutocomplete, type Engine, type EngineConfig$1 as EngineConfig, type EnginePlugin, FromKebab, GetValue, IsEqual, IsNever, Keyframes, KeyframesConfig, KeyframesProgress, Nullish, type PikaAugment, type Preflight, type PreflightDefinition, type PreflightFn, type Properties, ResolveFrom, type ResolvedLayerName, type ResolvedPreflight, Selector, SelectorsConfig, Shortcut, ShortcutsConfig, Simplify, type StyleDefinition, type StyleItem, ToKebab, UnionNumber, UnionString, UnionToIntersection, Variable, VariableAutocomplete, VariableObject, VariablesConfig, VariablesDefinition, type WithLayer, appendAutocompleteCssPropertyValues, appendAutocompleteExtraCssProperties, appendAutocompleteExtraProperties, appendAutocompletePropertyValues, appendAutocompleteSelectors, appendAutocompleteStyleItemStrings, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, defineKeyframes, definePreflight, defineSelector, defineShortcut, defineStyleDefinition, defineVariables, extractUsedVarNames, important, keyframes, log, normalizeVariableName, renderCSSStyleBlocks, resolveSelectorConfig, selectors$1 as selectors, shortcuts, sortLayerNames, variables };

package/dist/index.d.mts

@@ -26,7 +26,7 @@ interface DynamicRule<T> {
   createResolved: (matched: RegExpMatchArray) => Awaitable<T>;
 }
 declare abstract class AbstractResolver<T> {
-  protected _resolvedResultsMap: Map<string, ResolvedResult<T>>;
+  _resolvedResultsMap: Map<string, ResolvedResult<T>>;
   staticRulesMap: Map<string, StaticRule<T>>;
   dynamicRulesMap: Map<string, DynamicRule<T>>;
   onResolved: (string: string, type: 'static' | 'dynamic', result: ResolvedResult<T>) => void;
@@ -269,6 +269,7 @@ interface _Autocomplete {
   StyleItemString: UnionString;
   ExtraProperty: UnionString;
   ExtraCssProperty: UnionString;
+  Layer: UnionString;
   PropertiesValue: Record<string, unknown>;
   CssPropertiesValue: Record<string, UnionString | UnionNumber>;
 }
@@ -278,6 +279,7 @@ type EmptyAutocomplete = DefineAutocomplete<{
   StyleItemString: never;
   ExtraProperty: never;
   ExtraCssProperty: never;
+  Layer: never;
   PropertiesValue: never;
   CssPropertiesValue: never;
 }>;
@@ -323,21 +325,25 @@ declare class Engine {
     atomicStyleIds?: string[];
     isPreview?: boolean;
   }): Promise<string>;
+  renderLayerOrderDeclaration(): string;
 }
+declare function sortLayerNames(layers: Record<string, number>): string[];
 //#endregion
 //#region src/internal/plugin.d.ts
-interface EnginePluginHooksOptions {
-  configureRawConfig?: (config: EngineConfig$1) => Awaitable<EngineConfig$1 | void>;
-  rawConfigConfigured?: (config: EngineConfig$1) => void;
-  configureResolvedConfig?: (resolvedConfig: ResolvedEngineConfig) => Awaitable<ResolvedEngineConfig | void>;
-  configureEngine?: (engine: Engine) => Awaitable<void>;
-  transformSelectors?: (selectors: string[]) => Awaitable<string[] | void>;
-  transformStyleItems?: (styleItems: ResolvedStyleItem[]) => Awaitable<ResolvedStyleItem[] | void>;
-  transformStyleDefinitions?: (styleDefinitions: ResolvedStyleDefinition[]) => Awaitable<ResolvedStyleDefinition[] | void>;
-  preflightUpdated?: () => void;
-  atomicStyleAdded?: (atomicStyle: AtomicStyle) => void;
-  autocompleteConfigUpdated?: () => void;
-}
+type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
+type EngineHooksDefinition = DefineHooks<{
+  configureRawConfig: ['async', config: EngineConfig$1];
+  rawConfigConfigured: ['sync', config: EngineConfig$1, void];
+  configureResolvedConfig: ['async', resolvedConfig: ResolvedEngineConfig];
+  configureEngine: ['async', engine: Engine];
+  transformSelectors: ['async', selectors: string[]];
+  transformStyleItems: ['async', styleItems: ResolvedStyleItem[]];
+  transformStyleDefinitions: ['async', styleDefinitions: ResolvedStyleDefinition[]];
+  preflightUpdated: ['sync', void];
+  atomicStyleAdded: ['sync', AtomicStyle];
+  autocompleteConfigUpdated: ['sync', void];
+}>;
+type EnginePluginHooksOptions = { [K in keyof EngineHooksDefinition]?: EngineHooksDefinition[K][0] extends 'async' ? (...params: EngineHooksDefinition[K][1] extends void ? [] : [payload: EngineHooksDefinition[K][1]]) => Awaitable<EngineHooksDefinition[K][1] | void> : (...params: EngineHooksDefinition[K][1] extends void ? [] : [payload: EngineHooksDefinition[K][1]]) => EngineHooksDefinition[K][1] | void };
 interface EnginePlugin extends EnginePluginHooksOptions {
   name: string;
   order?: 'pre' | 'post';
@@ -353,7 +359,7 @@ type CSSProperty = keyof CSSProperties;
 type PropertyValue<T> = T | [value: T, fallback: T[]] | Nullish;
 type Properties_CSS = { [Key in keyof CSSProperties]?: PropertyValue<Exclude<UnionString | UnionNumber | GetValue<CSSProperties, Key> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], ToKebab<Key>> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], FromKebab<Key>> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], '*'>, Nullish>> };
 type Properties_ExtraCSS = { [Key in keyof ResolvedAutocomplete['ExtraCssProperty']]?: PropertyValue<Exclude<UnionString | UnionNumber | GetValue<CSSProperties, Key & string> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], ToKebab<Key & string>> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], FromKebab<Key & string>> | GetValue<ResolvedAutocomplete['CssPropertiesValue'], '*'>, Nullish>> };
-type Properties_Extra = { [Key in keyof ResolvedAutocomplete['ExtraProperty']]?: GetValue<ResolvedAutocomplete['PropertiesValue'], Key & string> };
+type Properties_Extra = { [Key in ResolvedAutocomplete['ExtraProperty']]?: GetValue<ResolvedAutocomplete['PropertiesValue'], Key & string> };
 interface Properties extends Properties_CSS, Properties_ExtraCSS, Properties_Extra {}
 type CSSPseudos = `${'$'}${CSS.Pseudos}`;
 type CSSBlockAtRules = Exclude<CSS.AtRules, '@charset' | 'import' | '@namespace'>;
@@ -372,11 +378,13 @@ interface ExtractedStyleContent {
   selector: string[];
   property: string;
   value: string[] | Nullish;
+  layer?: string;
 }
 interface StyleContent {
   selector: string[];
   property: string;
   value: string[];
+  layer?: string;
 }
 interface AtomicStyle {
   id: string;
@@ -393,6 +401,7 @@ type CSSStyleBlocks = Map<string, CSSStyleBlockBody>;
 //#endregion
 //#region src/internal/types/resolved.d.ts
 type ResolvedAutocomplete = ResolveFrom<PikaAugment, 'Autocomplete', _Autocomplete, EmptyAutocomplete>;
+type ResolvedLayerName = IsNever<ResolvedAutocomplete['Layer']> extends true ? UnionString : ResolvedAutocomplete['Layer'];
 type ResolvedSelector = ResolveFrom<PikaAugment, 'Selector', string, string>;
 type ResolvedProperties = ResolveFrom<PikaAugment, 'Properties', any, InternalProperties>;
 type ResolvedCSSProperties = Omit<ResolvedProperties, ResolvedAutocomplete['ExtraProperty']>;
@@ -402,13 +411,23 @@ type ResolvedStyleItem = ResolveFrom<PikaAugment, 'StyleItem', any, InternalStyl
 //#region src/internal/types/preflight.d.ts
 type PreflightDefinition = { [selector in UnionString | ResolvedSelector]?: ResolvedCSSProperties | PreflightDefinition };
 type PreflightFn = (engine: Engine, isFormatted: boolean) => Awaitable<string | PreflightDefinition>;
+interface WithLayer<T extends string | PreflightDefinition | PreflightFn> {
+  layer: string;
+  preflight: T;
+}
+interface ResolvedPreflight {
+  layer?: string;
+  fn: PreflightFn;
+}
 /**
- * PreflightConfig can be a string or a function that returns a string.
+ * Preflight can be a string, object, function, or a layer-wrapped variant.
  *
- * 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.
+ * 1. A `string` is a static preflight style injected verbatim.
+ * 2. A `PreflightDefinition` is a JS object describing CSS rules.
+ * 3. A `PreflightFn` is a dynamic preflight that receives the engine instance.
+ * 4. A `WithLayer` wrapper assigns any of the above to a specific CSS `@layer`.
  */
-type Preflight = string | PreflightDefinition | PreflightFn;
+type Preflight = string | PreflightDefinition | PreflightFn | WithLayer<string | PreflightDefinition | PreflightFn>;
 //#endregion
 //#region src/internal/types/engine.d.ts
 interface EngineConfig$1 {
@@ -470,14 +489,44 @@ interface EngineConfig$1 {
    * ```
    */
   preflights?: Preflight[];
+  /**
+   * Configure CSS @layer order. Keys are layer names, values are order numbers (lower = earlier).
+   * Merged on top of the default layers `{ preflights: 1, utilities: 10 }`, so any keys not
+   * specified here will keep their default order values.
+   *
+   * @default { preflights: 1, utilities: 10 }
+   * @example
+   * ```ts
+   * {
+   *   layers: { base: 0, components: 5, utilities: 10 }
+   * }
+   * ```
+   */
+  layers?: Record<string, number>;
+  /**
+   * The layer name that unlayered preflights are automatically wrapped into.
+   *
+   * @default 'preflights'
+   */
+  defaultPreflightsLayer?: string;
+  /**
+   * The layer name that atomic styles without an explicit `__layer` are placed into.
+   *
+   * @default 'utilities'
+   */
+  defaultUtilitiesLayer?: string;
 }
 interface ResolvedEngineConfig {
   rawConfig: EngineConfig$1;
   prefix: string;
   defaultSelector: string;
   plugins: EnginePlugin[];
-  preflights: PreflightFn[];
+  preflights: ResolvedPreflight[];
   autocomplete: ResolvedAutocompleteConfig;
+  /** Always contains at least the default layers (`preflights` and `utilities`). */
+  layers: Record<string, number>;
+  defaultPreflightsLayer: string;
+  defaultUtilitiesLayer: string;
 }
 //#endregion
 //#region src/internal/plugins/keyframes.d.ts
@@ -585,4 +634,4 @@ declare function defineSelector(selector: Selector): Selector;
 declare function defineShortcut(shortcut: Shortcut): Shortcut;
 declare function defineVariables(variables: VariablesDefinition): VariablesDefinition;
 //#endregion
-export { Arrayable, Awaitable, type CSSProperty, type CSSSelector, type CSSStyleBlockBody, type CSSStyleBlocks, type DefineAutocomplete, type Engine, type EngineConfig$1 as EngineConfig, type EnginePlugin, FromKebab, GetValue, IsEqual, IsNever, Keyframes, KeyframesConfig, KeyframesProgress, Nullish, type PikaAugment, type Properties, ResolveFrom, Selector, SelectorsConfig, Shortcut, ShortcutsConfig, Simplify, type StyleDefinition, type StyleItem, ToKebab, UnionNumber, UnionString, UnionToIntersection, Variable, VariableAutocomplete, VariableObject, VariablesConfig, VariablesDefinition, appendAutocompleteCssPropertyValues, appendAutocompleteExtraCssProperties, appendAutocompleteExtraProperties, appendAutocompletePropertyValues, appendAutocompleteSelectors, appendAutocompleteStyleItemStrings, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, defineKeyframes, definePreflight, defineSelector, defineShortcut, defineStyleDefinition, defineVariables, extractUsedVarNames, important, keyframes, log, normalizeVariableName, renderCSSStyleBlocks, resolveSelectorConfig, selectors$1 as selectors, shortcuts, variables };
+export { Arrayable, Awaitable, type CSSProperty, type CSSSelector, type CSSStyleBlockBody, type CSSStyleBlocks, type DefineAutocomplete, type Engine, type EngineConfig$1 as EngineConfig, type EnginePlugin, FromKebab, GetValue, IsEqual, IsNever, Keyframes, KeyframesConfig, KeyframesProgress, Nullish, type PikaAugment, type Preflight, type PreflightDefinition, type PreflightFn, type Properties, ResolveFrom, type ResolvedLayerName, type ResolvedPreflight, Selector, SelectorsConfig, Shortcut, ShortcutsConfig, Simplify, type StyleDefinition, type StyleItem, ToKebab, UnionNumber, UnionString, UnionToIntersection, Variable, VariableAutocomplete, VariableObject, VariablesConfig, VariablesDefinition, type WithLayer, appendAutocompleteCssPropertyValues, appendAutocompleteExtraCssProperties, appendAutocompleteExtraProperties, appendAutocompletePropertyValues, appendAutocompleteSelectors, appendAutocompleteStyleItemStrings, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, defineKeyframes, definePreflight, defineSelector, defineShortcut, defineStyleDefinition, defineVariables, extractUsedVarNames, important, keyframes, log, normalizeVariableName, renderCSSStyleBlocks, resolveSelectorConfig, selectors$1 as selectors, shortcuts, sortLayerNames, variables };

package/dist/index.mjs

@@ -751,6 +751,12 @@ function normalizeVariableName(name) {
 
 //#endregion
 //#region src/internal/engine.ts
+const DEFAULT_PREFLIGHTS_LAYER = "preflights";
+const DEFAULT_UTILITIES_LAYER = "utilities";
+const DEFAULT_LAYERS = {
+	[DEFAULT_PREFLIGHTS_LAYER]: 1,
+	[DEFAULT_UTILITIES_LAYER]: 10
+};
 async function createEngine(config = {}) {
 	log.debug("Creating engine with config:", config);
 	const corePlugins = [
@@ -770,6 +776,8 @@ async function createEngine(config = {}) {
 	log.debug("Engine config resolved with prefix:", resolvedConfig.prefix);
 	resolvedConfig = await hooks.configureResolvedConfig(resolvedConfig.plugins, resolvedConfig);
 	let engine = new Engine(resolvedConfig);
+	engine.appendAutocompleteExtraProperties("__layer");
+	engine.appendAutocompletePropertyValues("__layer", "Autocomplete['Layer']");
 	log.debug("Engine instance created");
 	engine = await hooks.configureEngine(engine.config.plugins, engine);
 	log.debug("Engine initialized successfully");
@@ -862,17 +870,39 @@ var Engine = class {
 	async renderPreflights(isFormatted) {
 		log.debug("Rendering preflights...");
 		const lineEnd = isFormatted ? "\n" : "";
-		const results = await Promise.all(this.config.preflights.map(async (p) => {
-			const result = await p(this, isFormatted);
-			if (typeof result === "string") return result;
-			return renderPreflightDefinition({
-				engine: this,
-				preflightDefinition: result,
-				isFormatted
-			});
+		const rendered = await Promise.all(this.config.preflights.map(async ({ layer, fn }) => {
+			const result = await fn(this, isFormatted);
+			return {
+				layer,
+				css: typeof result === "string" ? result : await renderPreflightDefinition({
+					engine: this,
+					preflightDefinition: result,
+					isFormatted
+				})
+			};
 		}));
-		log.debug(`Rendered ${results.length} preflights`);
-		return results.join(lineEnd);
+		log.debug(`Rendered ${rendered.length} preflights`);
+		const unlayeredParts = [];
+		const layerGroups = /* @__PURE__ */ new Map();
+		for (const { layer, css } of rendered) if (layer == null) unlayeredParts.push(css);
+		else {
+			if (!layerGroups.has(layer)) layerGroups.set(layer, []);
+			layerGroups.get(layer).push(css);
+		}
+		const outputParts = [];
+		if (unlayeredParts.length > 0) {
+			const unlayeredContent = unlayeredParts.join(lineEnd);
+			const { defaultPreflightsLayer } = this.config;
+			if (defaultPreflightsLayer in this.config.layers) outputParts.push(`@layer ${defaultPreflightsLayer} {${lineEnd}${unlayeredContent}${lineEnd}}`);
+			else outputParts.push(unlayeredContent);
+		}
+		const configLayerOrder = sortLayerNames(this.config.layers);
+		const orderedLayerNames = [...configLayerOrder.filter((name) => layerGroups.has(name)), ...[...layerGroups.keys()].filter((name) => !configLayerOrder.includes(name))];
+		for (const layerName of orderedLayerNames) {
+			const content = layerGroups.get(layerName).join(lineEnd);
+			outputParts.push(`@layer ${layerName} {${lineEnd}${content}${lineEnd}}`);
+		}
+		return outputParts.join(lineEnd);
 	}
 	async renderAtomicStyles(isFormatted, options = {}) {
 		log.debug("Rendering atomic styles...");
@@ -883,19 +913,45 @@ var Engine = class {
 			atomicStyles,
 			isPreview,
 			isFormatted,
-			defaultSelector: this.config.defaultSelector
+			defaultSelector: this.config.defaultSelector,
+			layers: this.config.layers,
+			defaultUtilitiesLayer: this.config.defaultUtilitiesLayer
 		});
 	}
+	renderLayerOrderDeclaration() {
+		const { layers } = this.config;
+		if (Object.keys(layers).length === 0) return "";
+		return `@layer ${sortLayerNames(layers).join(", ")};`;
+	}
 };
 function calcAtomicStyleRenderingWeight(style, defaultSelector) {
 	const { selector } = style.content;
 	return selector.length === 1 && selector[0] === defaultSelector ? 0 : selector.length;
 }
+function sortLayerNames(layers) {
+	return Object.entries(layers).sort((a, b) => a[1] - b[1] || a[0].localeCompare(b[0])).map(([name]) => name);
+}
+function isWithLayer(p) {
+	if (typeof p !== "object" || p === null) return false;
+	const record = p;
+	return typeof record.layer === "string" && "preflight" in record;
+}
 function resolvePreflight(preflight) {
-	return typeof preflight === "function" ? preflight : () => preflight;
+	if (isWithLayer(preflight)) {
+		const inner = preflight.preflight;
+		const fn = typeof inner === "function" ? inner : () => inner;
+		return {
+			layer: preflight.layer,
+			fn
+		};
+	}
+	return { fn: typeof preflight === "function" ? preflight : () => preflight };
 }
 async function resolveEngineConfig(config) {
 	const { prefix = "", defaultSelector = `.${ATOMIC_STYLE_ID_PLACEHOLDER}`, plugins = [], preflights = [] } = config;
+	const layers = Object.assign({}, DEFAULT_LAYERS, config.layers);
+	const defaultPreflightsLayer = config.defaultPreflightsLayer ?? DEFAULT_PREFLIGHTS_LAYER;
+	const defaultUtilitiesLayer = config.defaultUtilitiesLayer ?? DEFAULT_UTILITIES_LAYER;
 	log.debug(`Resolving engine config with prefix: "${prefix}", plugins: ${plugins.length}, preflights: ${preflights.length}`);
 	const resolvedConfig = {
 		rawConfig: config,
@@ -903,6 +959,9 @@ async function resolveEngineConfig(config) {
 		prefix,
 		defaultSelector,
 		preflights: [],
+		layers,
+		defaultPreflightsLayer,
+		defaultUtilitiesLayer,
 		autocomplete: {
 			selectors: /* @__PURE__ */ new Set(),
 			styleItemStrings: /* @__PURE__ */ new Set(),
@@ -921,7 +980,8 @@ function getAtomicStyleId({ content, prefix, stored }) {
 	const key = serialize([
 		content.selector,
 		content.property,
-		content.value
+		content.value,
+		content.layer
 	]);
 	const cached = stored.get(key);
 	if (cached != null) {
@@ -937,29 +997,51 @@ function getAtomicStyleId({ content, prefix, stored }) {
 function optimizeAtomicStyleContents(list) {
 	const map = /* @__PURE__ */ new Map();
 	list.forEach((content) => {
-		const key = serialize([content.selector, content.property]);
+		const key = serialize([
+			content.selector,
+			content.property,
+			content.layer
+		]);
 		map.delete(key);
 		if (content.value == null) return;
-		map.set(key, content);
+		map.set(key, { ...content });
 	});
 	return [...map.values()];
 }
+function extractLayerFromStyleItem(item) {
+	const record = item;
+	const layer = typeof record.__layer === "string" ? record.__layer : void 0;
+	if (layer == null) return {
+		layer: void 0,
+		definition: item
+	};
+	const { __layer: _, ...rest } = record;
+	return {
+		layer,
+		definition: rest
+	};
+}
 async function resolveStyleItemList({ itemList, transformStyleItems, extractStyleDefinition }) {
 	const unknown = /* @__PURE__ */ new Set();
 	const list = [];
 	for (const styleItem of await transformStyleItems(itemList)) if (typeof styleItem === "string") unknown.add(styleItem);
-	else list.push(...await extractStyleDefinition(styleItem));
+	else {
+		const { layer, definition } = extractLayerFromStyleItem(styleItem);
+		const extracted = await extractStyleDefinition(definition);
+		if (layer != null) extracted.forEach((c) => c.layer = layer);
+		list.push(...extracted);
+	}
 	return {
 		unknown,
 		contents: optimizeAtomicStyleContents(list)
 	};
 }
-function renderAtomicStyles(payload) {
-	const { atomicStyles, isPreview, isFormatted, defaultSelector } = payload;
+function sortAtomicStyles(styles, defaultSelector) {
+	return [...styles].sort((a, b) => calcAtomicStyleRenderingWeight(a, defaultSelector) - calcAtomicStyleRenderingWeight(b, defaultSelector));
+}
+function renderAtomicStylesCss({ atomicStyles, isPreview, isFormatted }) {
 	const blocks = /* @__PURE__ */ new Map();
-	Array.from(atomicStyles).sort((a, b) => {
-		return calcAtomicStyleRenderingWeight(a, defaultSelector) - calcAtomicStyleRenderingWeight(b, defaultSelector);
-	}).forEach(({ id, content: { selector, property, value } }) => {
+	atomicStyles.forEach(({ id, content: { selector, property, value } }) => {
 		if (selector.some((s) => s.includes(ATOMIC_STYLE_ID_PLACEHOLDER)) === false || value == null) return;
 		const renderObject = {
 			selector: isPreview ? selector : selector.map((s) => s.replace(ATOMIC_STYLE_ID_PLACEHOLDER_RE_GLOBAL, id)),
@@ -981,6 +1063,47 @@ function renderAtomicStyles(payload) {
 	});
 	return renderCSSStyleBlocks(blocks, isFormatted);
 }
+function renderAtomicStyles(payload) {
+	const { atomicStyles, isPreview, isFormatted, defaultSelector, layers, defaultUtilitiesLayer } = payload;
+	const sortedStyles = sortAtomicStyles(atomicStyles, defaultSelector);
+	if (layers == null) return renderAtomicStylesCss({
+		atomicStyles: sortedStyles,
+		isPreview,
+		isFormatted
+	});
+	const layerOrder = sortLayerNames(layers);
+	const lineEnd = isFormatted ? "\n" : "";
+	const unlayeredStyles = [];
+	const layerGroups = new Map(layerOrder.map((name) => [name, []]));
+	const candidateDefaultLayer = defaultUtilitiesLayer ?? layerOrder[layerOrder.length - 1];
+	const defaultLayer = candidateDefaultLayer != null && layerGroups.has(candidateDefaultLayer) ? candidateDefaultLayer : layerOrder[layerOrder.length - 1];
+	for (const style of sortedStyles) {
+		const layer = style.content.layer;
+		if (layer != null && layerGroups.has(layer)) layerGroups.get(layer).push(style);
+		else if (layer != null) {
+			log.warn(`Unknown layer "${layer}" encountered in atomic style; falling back to unlayered output.`);
+			unlayeredStyles.push(style);
+		} else if (defaultLayer != null) layerGroups.get(defaultLayer).push(style);
+		else unlayeredStyles.push(style);
+	}
+	const parts = [];
+	if (unlayeredStyles.length > 0) parts.push(renderAtomicStylesCss({
+		atomicStyles: unlayeredStyles,
+		isPreview,
+		isFormatted
+	}));
+	for (const layerName of layerOrder) {
+		const styles = layerGroups.get(layerName);
+		if (styles.length === 0) continue;
+		const innerCss = renderAtomicStylesCss({
+			atomicStyles: styles,
+			isPreview,
+			isFormatted
+		});
+		parts.push(`@layer ${layerName} {${lineEnd}${innerCss}${lineEnd}}`);
+	}
+	return parts.join(lineEnd);
+}
 async function _renderPreflightDefinition({ engine, preflightDefinition, blocks = /* @__PURE__ */ new Map() }) {
 	for (const [selector, propertiesOrDefinition] of Object.entries(preflightDefinition)) {
 		if (propertiesOrDefinition == null) continue;
@@ -1052,4 +1175,4 @@ function defineVariables(variables$1) {
 /* c8 ignore end */
 
 //#endregion
-export { appendAutocompleteCssPropertyValues, appendAutocompleteExtraCssProperties, appendAutocompleteExtraProperties, appendAutocompletePropertyValues, appendAutocompleteSelectors, appendAutocompleteStyleItemStrings, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, defineKeyframes, definePreflight, defineSelector, defineShortcut, defineStyleDefinition, defineVariables, log, renderCSSStyleBlocks };
+export { appendAutocompleteCssPropertyValues, appendAutocompleteExtraCssProperties, appendAutocompleteExtraProperties, appendAutocompletePropertyValues, appendAutocompleteSelectors, appendAutocompleteStyleItemStrings, createEngine, createLogger, defineEngineConfig, defineEnginePlugin, defineKeyframes, definePreflight, defineSelector, defineShortcut, defineStyleDefinition, defineVariables, log, renderCSSStyleBlocks, sortLayerNames };

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@pikacss/core",
   "type": "module",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://github.com/pikacss/pikacss.github.io.git",
+    "url": "https://github.com/pikacss/pikacss.git",
     "directory": "packages/core"
   },
   "bugs": {
-    "url": "https://github.com/pikacss/pikacss.github.io/issues"
+    "url": "https://github.com/pikacss/pikacss/issues"
   },
   "keywords": [
     "pikacss",

package/README.md

@@ -1,238 +0,0 @@
-# @pikacss/core
-
-The core Atomic CSS-in-JS engine of PikaCSS.
-
-## Installation
-
-```bash
-pnpm add @pikacss/core
-```
-
-## Quick Start
-
-```typescript
-import { createEngine, defineEngineConfig } from '@pikacss/core'
-
-const config = defineEngineConfig({
-	// Engine configuration
-	prefix: 'pk-',
-	defaultSelector: '.%',
-	plugins: []
-})
-
-// createEngine is async and returns a fully initialized engine
-const engine = await createEngine(config)
-```
-
-## Features
-
-- ⚡ High-performance Atomic CSS-in-JS engine
-- 🎯 Type-safe with full TypeScript support
-- 🔌 Extensible plugin system with hooks
-- 🎨 Built-in support for shortcuts, selectors, variables, keyframes, and important rules
-- 🔧 Fully configurable with type-safe helpers
-- 🌐 Framework-agnostic core (zero dependencies except csstype)
-
-## Usage for Integration Developers
-
-### Creating an Engine
-
-```typescript
-import { createEngine, defineEngineConfig } from '@pikacss/core'
-
-const config = defineEngineConfig({
-	// Prefix for generated atomic CSS class names
-	prefix: 'pk-',
-
-	// Default selector format (% will be replaced with atomic ID)
-	defaultSelector: '.%',
-
-	// Plugins to extend functionality
-	plugins: [],
-
-	// Global CSS preflights
-	preflights: [],
-})
-
-// createEngine is async - it returns a fully initialized engine
-const engine = await createEngine(config)
-```
-
-### Engine Methods and Properties
-
-The `Engine` instance provides methods and sub-systems for managing CSS generation:
-
-```typescript
-// Add global CSS preflight
-engine.addPreflight('* { box-sizing: border-box; }')
-
-// Process style items and get atomic class IDs
-const classNames = await engine.use({ color: 'red' }, { display: 'flex' })
-
-// Render generated preflights
-const preflightCSS = await engine.renderPreflights(true)
-
-// Render generated atomic styles
-const atomicCSS = await engine.renderAtomicStyles(true)
-
-// Access sub-systems (provided by built-in plugins)
-engine.variables // { store: Map, add: (variables) => void }
-engine.keyframes // { store: Map, add: (...keyframes) => void }
-engine.selectors // { resolver: SelectorResolver, add: (...selectors) => void }
-engine.shortcuts // { resolver: ShortcutResolver, add: (...shortcuts) => void }
-
-// Access configuration
-engine.config // ResolvedEngineConfig
-
-// Autocomplete helpers
-engine.appendAutocompleteSelectors('hover', 'focus')
-engine.appendAutocompleteStyleItemStrings('flex-center')
-```
-
-### Configuration
-
-Use `defineEngineConfig` for type-safe configuration:
-
-```typescript
-import { defineEngineConfig } from '@pikacss/core'
-
-export default defineEngineConfig({
-	// Prefix for atomic class IDs
-	prefix: 'pk-',
-
-	// Default selector format (% = atomic ID)
-	defaultSelector: '.%',
-
-	// Global CSS preflights (string or function)
-	preflights: [
-		':root { --primary: #3b82f6; }',
-		// Or function:
-		(engine, isFormatted) => '/* Generated CSS */'
-	],
-
-	// Shortcuts configuration
-	shortcuts: {
-		shortcuts: [
-			['flex-center', {
-				display: 'flex',
-				alignItems: 'center',
-				justifyContent: 'center'
-			}],
-		]
-	},
-
-	// Plugins to extend functionality
-	plugins: []
-})
-```
-
-## API
-
-### Main Exports
-
-```typescript
-// Engine creation (async)
-export function createEngine(config?: EngineConfig): Promise<Engine>
-
-// Type-safe config helpers
-export function defineEngineConfig(config: EngineConfig): EngineConfig
-export function defineEnginePlugin(plugin: EnginePlugin): EnginePlugin
-export function defineStyleDefinition(def: StyleDefinition): StyleDefinition
-export function definePreflight(preflight: Preflight): Preflight
-export function defineKeyframes(keyframes: Keyframes): Keyframes
-export function defineSelector(selector: Selector): Selector
-export function defineShortcut(shortcut: Shortcut): Shortcut
-export function defineVariables(variables: VariablesDefinition): VariablesDefinition
-
-// Utilities
-export {
-	appendAutocompleteCssPropertyValues,
-	appendAutocompleteExtraCssProperties,
-	appendAutocompleteExtraProperties,
-	appendAutocompletePropertyValues,
-	appendAutocompleteSelectors,
-	appendAutocompleteStyleItemStrings,
-	createLogger,
-	log,
-	renderCSSStyleBlocks,
-}
-```
-
-### Engine Instance
-
-The `Engine` instance provides:
-
-**Core methods:**
-- `engine.addPreflight(css)` - Add global CSS preflight
-- `engine.use(...styleItems)` - Process style items and return atomic class IDs
-- `engine.renderPreflights(isFormatted)` - Render all preflight CSS
-- `engine.renderAtomicStyles(isFormatted, options?)` - Render atomic style CSS
-
-**Sub-systems (provided by built-in plugins):**
-- `engine.variables` - CSS variables management with `store` and `add()`
-- `engine.keyframes` - CSS keyframes management with `store` and `add()`
-- `engine.selectors` - CSS selectors management with `resolver` and `add()`
-- `engine.shortcuts` - CSS shortcuts management with `resolver` and `add()`
-
-**Properties:**
-- `engine.config` - Resolved engine configuration
-- `engine.store` - Internal storage for atomic styles and IDs
-- `engine.extract` - Style extraction function
-
-## Plugin Development
-
-Create custom plugins to extend PikaCSS using the `EnginePlugin` interface:
-
-```typescript
-/* eslint-disable pikacss/pika-module-augmentation */
-import type { EnginePlugin } from '@pikacss/core'
-import { defineEnginePlugin } from '@pikacss/core'
-
-export function myPlugin(): EnginePlugin {
-	return defineEnginePlugin({
-		name: 'my-plugin',
-
-		// Optional: Control execution order ('pre' | 'post')
-		order: 'pre',
-
-		// Hook into engine lifecycle
-		async configureEngine(engine) {
-			// Add global CSS
-			engine.addPreflight('/* plugin styles */')
-
-			// Add custom shortcuts
-			engine.shortcuts.add([
-				'my-shortcut',
-				{ display: 'flex', gap: '1rem' }
-			])
-
-			// Add custom selectors
-			engine.selectors.add(['hover', '$:hover'])
-		},
-
-		// Transform style definitions
-		async transformStyleDefinitions(definitions) {
-			// Modify or add style definitions
-			return definitions
-		},
-
-		// Other available hooks:
-		// - configureRawConfig(config)
-		// - rawConfigConfigured(config)
-		// - configureResolvedConfig(config)
-		// - transformSelectors(selectors)
-		// - transformStyleItems(styleItems)
-		// - preflightUpdated()
-		// - atomicStyleAdded(atomicStyle)
-		// - autocompleteConfigUpdated()
-	})
-}
-```
-
-## Documentation
-
-For complete documentation, visit: [PikaCSS Documentation](https://pikacss.github.io/pikacss/)
-
-## License
-
-MIT © DevilTea