@pikacss/core 0.0.41 → 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

@@ -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,7 +325,9 @@ 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
 type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
@@ -355,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'>;
@@ -374,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;
@@ -395,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']>;
@@ -404,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 {
@@ -472,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
@@ -587,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

@@ -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,7 +325,9 @@ 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
 type DefineHooks<Hooks extends Record<string, [type: 'sync' | 'async', payload: any, returnValue?: any]>> = Hooks;
@@ -355,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'>;
@@ -374,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;
@@ -395,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']>;
@@ -404,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 {
@@ -472,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
@@ -587,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,7 +1,7 @@
 {
   "name": "@pikacss/core",
   "type": "module",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "author": "DevilTea <ch19980814@gmail.com>",
   "license": "MIT",
   "repository": {