postcss-preset-env : array options (#1304)

Author: romainmenke

e2e/typescript/esm--node-next/index.ts

@@ -1,6 +1,16 @@
 import assert from 'assert';
 import plugin from 'postcss-preset-env';
-plugin({ preserve: true });
+plugin({
+	preserve: true,
+	features: {
+		'all-property': [true, { preserve: true }],
+		'any-link-pseudo-class': [false, { preserve: true }],
+		'cascade-layers': ['auto', { onImportLayerRule: 'warn' }],
+		'color-function': { preserve: true, enableProgressiveCustomProperties: false },
+		'color-mix': false,
+		'light-dark-function': true,
+	},
+});
 
 assert.ok(plugin.postcss, 'should have "postcss flag"');
 assert.equal(typeof plugin, 'function', 'should return a function');

plugin-packs/postcss-preset-env/CHANGELOG.md

@@ -1,7 +1,8 @@
 # Changes to PostCSS Preset Env
 
-### Unreleased (patch)
+### Unreleased (minor)
 
+- Add support for array options, e.g. `{ 'nesting-rules': ['auto', { noIsPseudoSelector: false }] }`
 - Updated [`@csstools/postcss-gradients-interpolation-method`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-gradients-interpolation-method) to [`4.0.11`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-gradients-interpolation-method/CHANGELOG.md#4011) (patch)
 - Updated [`postcss-nesting`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting) to [`12.0.4`](https://github.com/csstools/postcss-plugins/tree/main/plugins/postcss-nesting/CHANGELOG.md#1204) (patch)
 

plugin-packs/postcss-preset-env/README.md

@@ -28,9 +28,9 @@ const yourConfig = {
 		postcssPresetEnv({
 			/* pluginOptions */
 			features: {
-				'nesting-rules': {
+				'nesting-rules': ['auto', {
 					noIsPseudoSelector: false,
-				},
+				}],
 			},
 		})
 	]
@@ -266,6 +266,20 @@ postcssPresetEnv({
 })
 ```
 
+If you want to preserve automatic enabling of features  
+based on the stage, implementations and or browserslist,  
+you can pass an array: `['auto', { /* plugin options */ }]`.
+
+```js
+postcssPresetEnv({
+  /* use stage 3 features + custom-selectors (preserving the original CSS) */
+  stage: 3,
+  features: {
+    'custom-selectors': ['auto', { preserve: true }]
+  }
+})
+```
+
 Any polyfills not explicitly enabled or disabled through `features` are
 determined by the [`stage`](#stage) option.
 

plugin-packs/postcss-preset-env/dist/index.cjs

@@ -149,119 +149,119 @@ export declare type pluginOptions = {
 
 export declare type pluginsOptions = {
     /** plugin options for "@csstools/postcss-initial" */
-    'all-property'?: pluginOptions_2 | boolean;
+    'all-property'?: subPluginOptions<pluginOptions_2>;
     /** plugin options for "postcss-pseudo-class-any-link" */
-    'any-link-pseudo-class'?: pluginOptions_3 | boolean;
+    'any-link-pseudo-class'?: subPluginOptions<pluginOptions_3>;
     /** plugin options for "css-blank-pseudo" */
-    'blank-pseudo-class'?: pluginOptions_4 | boolean;
+    'blank-pseudo-class'?: subPluginOptions<pluginOptions_4>;
     /** plugin options for "postcss-page-break" */
-    'break-properties'?: postcssPageBreakOptions | boolean;
+    'break-properties'?: subPluginOptions<postcssPageBreakOptions>;
     /** plugin options for "@csstools/postcss-cascade-layers" */
-    'cascade-layers'?: pluginOptions_5 | boolean;
+    'cascade-layers'?: subPluginOptions<pluginOptions_5>;
     /** plugin options for "postcss-attribute-case-insensitive" */
-    'case-insensitive-attributes'?: pluginOptions_6 | boolean;
+    'case-insensitive-attributes'?: subPluginOptions<pluginOptions_6>;
     /** plugin options for "postcss-clamp" */
-    'clamp'?: postcssClampOptions | boolean;
+    'clamp'?: subPluginOptions<postcssClampOptions>;
     /** plugin options for "@csstools/postcss-color-function" */
-    'color-function'?: pluginOptions_7 | boolean;
+    'color-function'?: subPluginOptions<pluginOptions_7>;
     /** plugin options for "postcss-color-functional-notation" */
-    'color-functional-notation'?: pluginOptions_8 | boolean;
+    'color-functional-notation'?: subPluginOptions<pluginOptions_8>;
     /** plugin options for "@csstools/postcss-color-mix-function" */
-    'color-mix'?: pluginOptions_9 | boolean;
+    'color-mix'?: subPluginOptions<pluginOptions_9>;
     /** plugin options for "postcss-custom-media" */
-    'custom-media-queries'?: pluginOptions_10 | boolean;
+    'custom-media-queries'?: subPluginOptions<pluginOptions_10>;
     /** plugin options for "postcss-custom-properties" */
-    'custom-properties'?: pluginOptions_11 | boolean;
+    'custom-properties'?: subPluginOptions<pluginOptions_11>;
     /** plugin options for "postcss-custom-selectors" */
-    'custom-selectors'?: pluginOptions_12 | boolean;
+    'custom-selectors'?: subPluginOptions<pluginOptions_12>;
     /** plugin options for "postcss-dir-pseudo-class" */
-    'dir-pseudo-class'?: pluginOptions_13 | boolean;
+    'dir-pseudo-class'?: subPluginOptions<pluginOptions_13>;
     /** plugin options for "@csstools/postcss-normalize-display-values" */
-    'display-two-values'?: pluginOptions_14 | boolean;
+    'display-two-values'?: subPluginOptions<pluginOptions_14>;
     /** plugin options for "postcss-double-position-gradients" */
-    'double-position-gradients'?: pluginOptions_15 | boolean;
+    'double-position-gradients'?: subPluginOptions<pluginOptions_15>;
     /** plugin options for "@csstools/postcss-exponential-functions" */
-    'exponential-functions'?: pluginOptions_16 | boolean;
+    'exponential-functions'?: subPluginOptions<pluginOptions_16>;
     /** plugin options for "@csstools/postcss-logical-float-and-clear" */
-    'float-clear-logical-values'?: pluginOptions_17 | boolean;
+    'float-clear-logical-values'?: subPluginOptions<pluginOptions_17>;
     /** plugin options for "postcss-focus-visible" */
-    'focus-visible-pseudo-class'?: pluginOptions_18 | boolean;
+    'focus-visible-pseudo-class'?: subPluginOptions<pluginOptions_18>;
     /** plugin options for "postcss-focus-within" */
-    'focus-within-pseudo-class'?: pluginOptions_19 | boolean;
+    'focus-within-pseudo-class'?: subPluginOptions<pluginOptions_19>;
     /** plugin options for "@csstools/postcss-font-format-keywords" */
-    'font-format-keywords'?: pluginOptions_20 | boolean;
+    'font-format-keywords'?: subPluginOptions<pluginOptions_20>;
     /** plugin options for "postcss-font-variant" */
-    'font-variant-property'?: postcssFontVariantOptions | boolean;
+    'font-variant-property'?: subPluginOptions<postcssFontVariantOptions>;
     /** plugin options for "@csstools/postcss-gamut-mapping" */
-    'gamut-mapping'?: pluginOptions_21 | boolean;
+    'gamut-mapping'?: subPluginOptions<pluginOptions_21>;
     /** plugin options for "postcss-gap-properties" */
-    'gap-properties'?: pluginOptions_22 | boolean;
+    'gap-properties'?: subPluginOptions<pluginOptions_22>;
     /** plugin options for "@csstools/postcss-gradients-interpolation-method" */
-    'gradients-interpolation-method'?: pluginOptions_23 | boolean;
+    'gradients-interpolation-method'?: subPluginOptions<pluginOptions_23>;
     /** plugin options for "css-has-pseudo" */
-    'has-pseudo-class'?: pluginOptions_24 | boolean;
+    'has-pseudo-class'?: subPluginOptions<pluginOptions_24>;
     /** plugin options for "postcss-color-hex-alpha" */
-    'hexadecimal-alpha-notation'?: pluginOptions_25 | boolean;
+    'hexadecimal-alpha-notation'?: subPluginOptions<pluginOptions_25>;
     /** plugin options for "@csstools/postcss-hwb-function" */
-    'hwb-function'?: pluginOptions_26 | boolean;
+    'hwb-function'?: subPluginOptions<pluginOptions_26>;
     /** plugin options for "@csstools/postcss-ic-unit" */
-    'ic-unit'?: pluginOptions_27 | boolean;
+    'ic-unit'?: subPluginOptions<pluginOptions_27>;
     /** plugin options for "postcss-image-set-function" */
-    'image-set-function'?: pluginOptions_28 | boolean;
+    'image-set-function'?: subPluginOptions<pluginOptions_28>;
     /** plugin options for "@csstools/postcss-is-pseudo-class" */
-    'is-pseudo-class'?: pluginOptions_29 | boolean;
+    'is-pseudo-class'?: subPluginOptions<pluginOptions_29>;
     /** plugin options for "postcss-lab-function" */
-    'lab-function'?: pluginOptions_30 | boolean;
+    'lab-function'?: subPluginOptions<pluginOptions_30>;
     /** plugin options for "@csstools/postcss-light-dark-function" */
-    'light-dark-function'?: pluginOptions_31 | boolean;
+    'light-dark-function'?: subPluginOptions<pluginOptions_31>;
     /** plugin options for "@csstools/postcss-logical-overflow" */
-    'logical-overflow'?: pluginOptions_32 | boolean;
+    'logical-overflow'?: subPluginOptions<pluginOptions_32>;
     /** plugin options for "@csstools/postcss-logical-overscroll-behavior" */
-    'logical-overscroll-behavior'?: pluginOptions_33 | boolean;
+    'logical-overscroll-behavior'?: subPluginOptions<pluginOptions_33>;
     /** plugin options for "postcss-logical" */
-    'logical-properties-and-values'?: pluginOptions_34 | boolean;
+    'logical-properties-and-values'?: subPluginOptions<pluginOptions_34>;
     /** plugin options for "@csstools/postcss-logical-resize" */
-    'logical-resize'?: pluginOptions_35 | boolean;
+    'logical-resize'?: subPluginOptions<pluginOptions_35>;
     /** plugin options for "@csstools/postcss-logical-viewport-units" */
-    'logical-viewport-units'?: pluginOptions_36 | boolean;
+    'logical-viewport-units'?: subPluginOptions<pluginOptions_36>;
     /** plugin options for "@csstools/postcss-media-queries-aspect-ratio-number-values" */
-    'media-queries-aspect-ratio-number-values'?: pluginOptions_37 | boolean;
+    'media-queries-aspect-ratio-number-values'?: subPluginOptions<pluginOptions_37>;
     /** plugin options for "@csstools/postcss-media-minmax" */
-    'media-query-ranges'?: pluginOptions_38 | boolean;
+    'media-query-ranges'?: subPluginOptions<pluginOptions_38>;
     /** plugin options for "@csstools/postcss-nested-calc" */
-    'nested-calc'?: pluginOptions_39 | boolean;
+    'nested-calc'?: subPluginOptions<pluginOptions_39>;
     /** plugin options for "postcss-nesting" */
-    'nesting-rules'?: pluginOptions_40 | boolean;
+    'nesting-rules'?: subPluginOptions<pluginOptions_40>;
     /** plugin options for "postcss-selector-not" */
-    'not-pseudo-class'?: pluginOptions_41 | boolean;
+    'not-pseudo-class'?: subPluginOptions<pluginOptions_41>;
     /** plugin options for "@csstools/postcss-oklab-function" */
-    'oklab-function'?: pluginOptions_42 | boolean;
+    'oklab-function'?: subPluginOptions<pluginOptions_42>;
     /** plugin options for "postcss-opacity-percentage" */
-    'opacity-percentage'?: postcssOpacityPercentageOptions | boolean;
+    'opacity-percentage'?: subPluginOptions<postcssOpacityPercentageOptions>;
     /** plugin options for "postcss-overflow-shorthand" */
-    'overflow-property'?: pluginOptions_43 | boolean;
+    'overflow-property'?: subPluginOptions<pluginOptions_43>;
     /** plugin options for "postcss-replace-overflow-wrap" */
-    'overflow-wrap-property'?: postcssReplaceOverflowWrapOptions | boolean;
+    'overflow-wrap-property'?: subPluginOptions<postcssReplaceOverflowWrapOptions>;
     /** plugin options for "postcss-place" */
-    'place-properties'?: pluginOptions_44 | boolean;
+    'place-properties'?: subPluginOptions<pluginOptions_44>;
     /** plugin options for "css-prefers-color-scheme" */
-    'prefers-color-scheme-query'?: pluginOptions_45 | boolean;
+    'prefers-color-scheme-query'?: subPluginOptions<pluginOptions_45>;
     /** plugin options for "postcss-color-rebeccapurple" */
-    'rebeccapurple-color'?: pluginOptions_46 | boolean;
+    'rebeccapurple-color'?: subPluginOptions<pluginOptions_46>;
     /** plugin options for "@csstools/postcss-relative-color-syntax" */
-    'relative-color-syntax'?: pluginOptions_47 | boolean;
+    'relative-color-syntax'?: subPluginOptions<pluginOptions_47>;
     /** plugin options for "@csstools/postcss-scope-pseudo-class" */
-    'scope-pseudo-class'?: pluginOptions_48 | boolean;
+    'scope-pseudo-class'?: subPluginOptions<pluginOptions_48>;
     /** plugin options for "@csstools/postcss-stepped-value-functions" */
-    'stepped-value-functions'?: pluginOptions_49 | boolean;
+    'stepped-value-functions'?: subPluginOptions<pluginOptions_49>;
     /** plugin options for "postcss-system-ui-font-family" */
-    'system-ui-font-family'?: postcssFontFamilySystemUIOptions | boolean;
+    'system-ui-font-family'?: subPluginOptions<postcssFontFamilySystemUIOptions>;
     /** plugin options for "@csstools/postcss-text-decoration-shorthand" */
-    'text-decoration-shorthand'?: pluginOptions_50 | boolean;
+    'text-decoration-shorthand'?: subPluginOptions<pluginOptions_50>;
     /** plugin options for "@csstools/postcss-trigonometric-functions" */
-    'trigonometric-functions'?: pluginOptions_51 | boolean;
+    'trigonometric-functions'?: subPluginOptions<pluginOptions_51>;
     /** plugin options for "@csstools/postcss-unset-value" */
-    'unset-value'?: pluginOptions_52 | boolean;
+    'unset-value'?: subPluginOptions<pluginOptions_52>;
 };
 
 /** postcss-clamp plugin options */
@@ -296,4 +296,6 @@ export declare type postcssReplaceOverflowWrapOptions = {
     preserve?: boolean;
 };
 
+export declare type subPluginOptions<T> = ['auto' | boolean, T] | T | boolean;
+
 export { }

plugin-packs/postcss-preset-env/dist/index.d.ts

@@ -44,12 +44,13 @@ function generatePluginOptions(data) {
 		}
 	}
 
+	result += '\nexport type subPluginOptions<T> = [\'auto\' | boolean, T] | T | boolean;\n';
 	result += '\nexport type pluginsOptions = {\n';
 
 	for (let i = 0; i < plugins.length; i++) {
 		const plugin = plugins[i];
 		result += `\t/** plugin options for "${plugin.packageName}" */\n`;
-		result += `\t'${plugin.id}'?: ${plugin.importName}Options | boolean\n`;
+		result += `\t'${plugin.id}'?: subPluginOptions<${plugin.importName}Options>\n`;
 	}
 
 	result += '};\n';

plugin-packs/postcss-preset-env/dist/index.mjs

@@ -8,7 +8,7 @@ import { pluginIdHelp } from './plugins/plugin-id-help.mjs';
 import type { pluginOptions } from './options';
 import type { PluginCreator } from 'postcss';
 export type { pluginOptions, DirectionFlow } from './options';
-export type { pluginsOptions } from './plugins/plugins-options';
+export type { pluginsOptions, subPluginOptions } from './plugins/plugins-options';
 export type { postcssClampOptions } from './types/postcss-clamp/plugin-options';
 export type { postcssFontFamilySystemUIOptions } from './types/postcss-system-ui-font-family/plugin-options';
 export type { postcssFontVariantOptions } from './types/postcss-font-variant/plugin-options';

plugin-packs/postcss-preset-env/scripts/generate-plugins-data.mjs

@@ -39,16 +39,10 @@ export function formatStagedFeature(cssdbList, supportedBrowsers, features, feat
 
 	pluginOption = getOptionsForBrowsersByFeature(supportedBrowsers, feature, cssdbList, options, logger);
 
-	if (features[feature.id] === true) {
-		if (sharedOptions) {
-			pluginOption = Object.assign({}, pluginOption, sharedOptions);
-		}
+	if (sharedOptions) {
+		pluginOption = Object.assign({}, pluginOption, sharedOptions, featureOptions(features, feature.id));
 	} else {
-		if (sharedOptions) {
-			pluginOption = Object.assign({}, pluginOption, sharedOptions, features[feature.id]);
-		} else {
-			pluginOption = Object.assign({}, pluginOption, features[feature.id]);
-		}
+		pluginOption = Object.assign({}, pluginOption, featureOptions(features, feature.id));
 	}
 
 	// postcss-preset-env : option overrides
@@ -77,3 +71,16 @@ export function formatStagedFeature(cssdbList, supportedBrowsers, features, feat
 		id: feature.id,
 	};
 }
+
+function featureOptions(features, featureId) {
+	if (!(featureId in features)) {
+		return undefined;
+	}
+
+	const value = features[featureId];
+	if (Array.isArray(value)) {
+		return value[1];
+	}
+
+	return value;
+}

plugin-packs/postcss-preset-env/src/index.ts

@@ -62,7 +62,7 @@ export function listFeatures(cssdbList, options, sharedOptions, logger) {
 			return true;
 		}
 
-		if (features[feature.id]) {
+		if (featureEnabledByOptions(features, feature.id) === true) {
 			// feature is explicitly enabled
 			logger.log(`  ${feature.id} does not meet the required vendor implementations but has been enabled by options`);
 			return true;
@@ -86,8 +86,9 @@ export function listFeatures(cssdbList, options, sharedOptions, logger) {
 		// TODO : this filter needs to be split up.
 		const isAllowedStage = feature.stage >= stage;
 		const isAllowedByType = enableClientSidePolyfills || !featuresWithClientSide.includes(feature.id);
-		const isDisabled = features[feature.id] === false;
-		const isAllowedFeature = features[feature.id] ? features[feature.id] : isAllowedStage && isAllowedByType;
+		const enabledByOptions = featureEnabledByOptions(features, feature.id);
+		const isDisabled = enabledByOptions === false;
+		const isAllowedFeature = enabledByOptions === true ? true : isAllowedStage && isAllowedByType;
 
 		if (isDisabled) {
 			logger.log(`  ${feature.id} has been disabled by options`);
@@ -101,7 +102,7 @@ export function listFeatures(cssdbList, options, sharedOptions, logger) {
 			logger.log(`  ${feature.id} has been disabled by "enableClientSidePolyfills: false".`);
 		}
 
-		return isAllowedFeature;
+		return !isDisabled && isAllowedFeature;
 	}).map((feature) => {
 		return formatStagedFeature(cssdbList, supportedBrowsers, features, feature, sharedOptions, options, logger);
 	});
@@ -114,8 +115,9 @@ export function listFeatures(cssdbList, options, sharedOptions, logger) {
 			return true;
 		}
 
-		if (feature.id in features) {
-			return features[feature.id];
+		const enabledByOptions = featureEnabledByOptions(features, feature.id);
+		if (enabledByOptions === true || enabledByOptions === false) {
+			return enabledByOptions;
 		}
 
 		const unsupportedBrowsers = browserslist(feature.browsers, {
@@ -135,3 +137,24 @@ export function listFeatures(cssdbList, options, sharedOptions, logger) {
 
 	return supportedFeatures;
 }
+
+function featureEnabledByOptions(features, featureId) {
+	if (!(featureId in features)) {
+		return 'auto';
+	}
+
+	const value = features[featureId];
+	if (Array.isArray(value)) {
+		if (value[0] === true) {
+			return true;
+		}
+
+		if (value[0] === false) {
+			return false;
+		}
+
+		return 'auto';
+	}
+
+	return Boolean(value);
+}

plugin-packs/postcss-preset-env/src/lib/format-feature.mjs

@@ -2,11 +2,15 @@ export default function postcssSystemUiFont() {
 	return {
 		postcssPlugin: 'postcss-system-ui-font',
 		Declaration(/** @type {import('postcss').Declaration} */ node) {
-			if (PROPERTY_REGEX.test(node.prop)) {
-				if (!node.value.includes(systemUIFamilies)) {
-					node.value = node.value.replace(SYSTEM_UI_MATCH, systemUiReplace);
-				}
+			if (!PROPERTY_REGEX.test(node.prop)) {
+				return;
 			}
+
+			if (node.value.includes(systemUIFamilies)) {
+				return;
+			}
+
+			node.value = node.value.replace(SYSTEM_UI_MATCH, systemUiReplace);
 		},
 	};
 }