postcss-units-to-px 0.0.0 → 0.1.0

package/README.md

@@ -59,6 +59,25 @@ Type: `(value, unit, context) => number`
 
 Global conversion function used when a unit does not have a per-unit rule (or when that rule is `null`).
 
+Signature:
+
+```ts
+type Transform = (value: number, unit: string, context: TransformContext) => number
+```
+
+Example:
+
+```ts
+const plugin = unitsToPx({
+  transform(value, unit, context) {
+    if (unit === 'em' && context.prop === 'letter-spacing') {
+      return value * 12
+    }
+    return value * 16
+  },
+})
+```
+
 ### unitPrecision
 
 Type: `number`

package/dist/index.cjs

@@ -1,9 +1,5 @@
 let postcss_plugin_shared = require("postcss-plugin-shared");
 
-//#region package.json
-var name = "postcss-units-to-px";
-
-//#endregion
 //#region src/defaults.ts
 const defaultUnitMap = {
 	rem: 16,
@@ -26,11 +22,35 @@ const defaultOptions = {
 	disabled: false
 };
 
+//#endregion
+//#region package.json
+var name = "postcss-units-to-px";
+
 //#endregion
 //#region src/shared.ts
+/**
+* PostCSS plugin name used by this package.
+*
+* @default package.json name
+*/
 const postcssPlugin = name;
+/**
+* Merge user options with defaults for postcss-units-to-px.
+*
+* Defaults:
+* - unitMap: { rem: 16, em: 16, vw: 3.75, vh: 6.67, vmin: 3.75, vmax: 6.67, rpx: 0.5 }
+* - unitPrecision: 5
+* - propList: ['*']
+* - replace: true
+* - mediaQuery: false
+* - minValue: 0
+* - exclude: [/node_modules/i]
+* - disabled: false
+*
+* @example
+* const config = getConfig({ unitPrecision: 4 })
+*/
 const getConfig = (0, postcss_plugin_shared.createConfigGetter)(defaultOptions);
-const blacklistedSelector = postcss_plugin_shared.maybeBlacklistedSelector;
 
 //#endregion
 //#region src/plugin.ts
@@ -66,62 +86,54 @@ function createReplace(unitMap, unitPrecision, minValue, transform, context) {
 		return `${roundedValue}px`;
 	};
 }
+/**
+* Convert multiple CSS units to px based on a unit map and optional transform.
+*
+* Defaults:
+* - unitMap: { rem: 16, em: 16, vw: 3.75, vh: 6.67, vmin: 3.75, vmax: 6.67, rpx: 0.5 }
+* - unitPrecision: 5
+* - propList: ['*']
+* - replace: true
+* - mediaQuery: false
+* - minValue: 0
+* - exclude: [/node_modules/i]
+* - disabled: false
+*
+* @example
+* import postcss from 'postcss'
+* import unitsToPx from 'postcss-units-to-px'
+*
+* const result = await postcss([unitsToPx({
+*   unitMap: { rem: 16, vw: 3.75 },
+*   transform: (value, unit) => (unit === 'em' ? value * 12 : value * 16),
+* })]).process('.a{margin:1rem 1vw}', { from: undefined })
+*/
 const plugin = (options = {}) => {
-	const { unitMap: mergedUnitMap, transform, unitPrecision, minValue, selectorBlackList, propList, replace, mediaQuery, exclude, disabled } = getConfig(options);
+	const { transform, unitPrecision, minValue, selectorBlackList, propList, replace, mediaQuery, exclude, disabled } = getConfig(options);
+	const mergedUnitMap = {
+		...defaultUnitMap,
+		...options.unitMap ?? {}
+	};
 	if (disabled) return { postcssPlugin };
 	const normalizedUnitMap = normalizeUnitMap(mergedUnitMap);
 	const units = getUnitsForRegex(normalizedUnitMap);
 	if (units.length === 0) return { postcssPlugin };
 	const unitRegex = (0, postcss_plugin_shared.createUnitRegex)({ units });
-	const unitTestRegex = new RegExp(unitRegex.source, unitRegex.flags.replace("g", ""));
-	const satisfyPropList = (0, postcss_plugin_shared.createPropListMatcher)(propList);
-	const excludeFn = (0, postcss_plugin_shared.createExcludeMatcher)(exclude);
-	const hasSelectorBlacklist = selectorBlackList.length > 0;
 	return {
 		postcssPlugin,
 		Once(css) {
-			const input = css.source.input;
-			const filePath = input.file;
-			if (excludeFn(filePath)) return;
-			const selectorBlacklistCache = hasSelectorBlacklist ? /* @__PURE__ */ new WeakMap() : void 0;
-			css.walkDecls((decl) => {
-				if (!satisfyPropList(decl.prop) || !unitTestRegex.test(decl.value)) return;
-				const rule = decl.parent;
-				if (selectorBlacklistCache) {
-					const cached = selectorBlacklistCache.get(rule);
-					const isBlacklisted = cached ?? Boolean(blacklistedSelector(selectorBlackList, rule.selector));
-					if (cached === void 0) selectorBlacklistCache.set(rule, isBlacklisted);
-					if (isBlacklisted) return;
-				}
-				const replacer = createReplace(normalizedUnitMap, unitPrecision, minValue, transform, {
-					root: css,
-					input,
-					filePath,
-					decl,
-					rule,
-					atRule: rule.parent?.type === "atrule" ? rule.parent : void 0,
-					prop: decl.prop,
-					selector: rule.selector
-				});
-				const value = decl.value.replace(unitRegex, replacer);
-				if (value === decl.value) return;
-				if ((rule.nodes?.length ?? 0) > 1 && (0, postcss_plugin_shared.declarationExists)(rule, decl.prop, value)) return;
-				if (replace) {
-					decl.value = value;
-					return;
-				}
-				decl.cloneAfter({ value });
-			});
-			css.walkAtRules((atRule) => {
-				if (!mediaQuery || atRule.name !== "media") return;
-				if (!unitTestRegex.test(atRule.params)) return;
-				const replacer = createReplace(normalizedUnitMap, unitPrecision, minValue, transform, {
-					root: css,
-					input,
-					filePath,
-					atRule
-				});
-				atRule.params = atRule.params.replace(unitRegex, replacer);
+			(0, postcss_plugin_shared.walkAndReplaceValues)({
+				root: css,
+				unitRegex,
+				propList,
+				selectorBlackList,
+				exclude,
+				replace,
+				mediaQuery,
+				createReplacer: (context) => {
+					return createReplace(normalizedUnitMap, unitPrecision, minValue, transform, context);
+				},
+				shouldProcessAtRule: (atRule) => atRule.name === "media"
 			});
 		}
 	};

package/dist/index.d.cts

@@ -1,34 +1,166 @@
-import { AtRule, Declaration, Input, PluginCreator, Root, Rule } from "postcss";
+import { PluginCreator } from "postcss";
+import { ReplaceContext } from "postcss-plugin-shared";
 
 //#region src/types.d.ts
-interface TransformContext {
-  root: Root;
-  input: Input;
-  filePath?: string;
-  decl?: Declaration;
-  rule?: Rule;
-  atRule?: AtRule;
-  prop?: string;
-  selector?: string;
-}
+/**
+ * Context provided to conversion callbacks.
+ *
+ * @example
+ * const transform = (value, unit, context) => {
+ *   if (context.prop === 'letter-spacing') return value * 12
+ *   return value * 16
+ * }
+ */
+type TransformContext = ReplaceContext;
+/**
+ * Per-unit conversion callback.
+ *
+ * @example
+ * const unitMap = {
+ *   rem: (value, context) => value * 16,
+ * }
+ */
 type UnitTransform = (value: number, context: TransformContext) => number;
+/**
+ * Global conversion callback when no per-unit rule is available.
+ *
+ * @example
+ * const transform = (value, unit, context) => {
+ *   return unit === 'vw' ? value * 3.75 : value * 16
+ * }
+ */
 type GlobalTransform = (value: number, unit: string, context: TransformContext) => number;
+/**
+ * Per-unit conversion rules.
+ *
+ * @default
+ * {
+ *   rem: 16,
+ *   em: 16,
+ *   vw: 3.75,
+ *   vh: 6.67,
+ *   vmin: 3.75,
+ *   vmax: 6.67,
+ *   rpx: 0.5
+ * }
+ *
+ * @example
+ * const unitMap = {
+ *   rem: 16,
+ *   px: null,
+ *   vh: (value) => value * 6.67,
+ * }
+ */
 type UnitMap = Record<string, number | UnitTransform | null>;
 interface UserDefinedOptions {
+  /**
+   * Per-unit conversion rules. Numeric values are multipliers.
+   *
+   * @default
+   * {
+   *   rem: 16,
+   *   em: 16,
+   *   vw: 3.75,
+   *   vh: 6.67,
+   *   vmin: 3.75,
+   *   vmax: 6.67,
+   *   rpx: 0.5
+   * }
+   *
+   * @example
+   * unitMap: { rem: 10, vw: 3.2, px: null }
+   */
   unitMap?: UnitMap;
+  /**
+   * Global conversion callback when a unit has no rule or is set to null.
+   *
+   * @example
+   * transform: (value, unit) => (unit === 'em' ? value * 12 : value * 16)
+   */
   transform?: GlobalTransform;
+  /**
+   * Decimal precision for generated px values.
+   *
+   * @default 5
+   */
   unitPrecision?: number;
+  /**
+   * Minimum source value to convert.
+   *
+   * @default 0
+   */
   minValue?: number;
+  /**
+   * Selectors to ignore.
+   *
+   * @default []
+   */
   selectorBlackList?: (string | RegExp)[];
+  /**
+   * Only declarations with matching properties are processed.
+   *
+   * @default ['*']
+   */
   propList?: (string | RegExp)[];
+  /**
+   * Replace the original declaration value.
+   *
+   * @default true
+   */
   replace?: boolean;
+  /**
+   * Enable unit conversion inside @media params.
+   *
+   * @default false
+   */
   mediaQuery?: boolean;
+  /**
+   * Exclude files by path.
+   *
+   * @default [/node_modules/i]
+   */
   exclude?: (string | RegExp)[] | ((filePath: string) => boolean);
+  /**
+   * Disable this plugin.
+   *
+   * @default false
+   */
   disabled?: boolean;
 }
+/**
+ * PostCSS plugin creator for postcss-units-to-px.
+ *
+ * @example
+ * import postcss from 'postcss'
+ * import unitsToPx from 'postcss-units-to-px'
+ *
+ * const result = await postcss([unitsToPx()]).process('.a{margin:1rem}', { from: undefined })
+ */
 type PostcssUnitsToPx = PluginCreator<UserDefinedOptions>;
 //#endregion
 //#region src/plugin.d.ts
+/**
+ * Convert multiple CSS units to px based on a unit map and optional transform.
+ *
+ * Defaults:
+ * - unitMap: { rem: 16, em: 16, vw: 3.75, vh: 6.67, vmin: 3.75, vmax: 6.67, rpx: 0.5 }
+ * - unitPrecision: 5
+ * - propList: ['*']
+ * - replace: true
+ * - mediaQuery: false
+ * - minValue: 0
+ * - exclude: [/node_modules/i]
+ * - disabled: false
+ *
+ * @example
+ * import postcss from 'postcss'
+ * import unitsToPx from 'postcss-units-to-px'
+ *
+ * const result = await postcss([unitsToPx({
+ *   unitMap: { rem: 16, vw: 3.75 },
+ *   transform: (value, unit) => (unit === 'em' ? value * 12 : value * 16),
+ * })]).process('.a{margin:1rem 1vw}', { from: undefined })
+ */
 declare const plugin: PostcssUnitsToPx;
 //#endregion
 export { GlobalTransform, PostcssUnitsToPx, TransformContext, UnitMap, UnitTransform, UserDefinedOptions, plugin as default };

package/dist/index.d.mts

@@ -1,34 +1,166 @@
-import { AtRule, Declaration, Input, PluginCreator, Root, Rule } from "postcss";
+import { ReplaceContext } from "postcss-plugin-shared";
+import { PluginCreator } from "postcss";
 
 //#region src/types.d.ts
-interface TransformContext {
-  root: Root;
-  input: Input;
-  filePath?: string;
-  decl?: Declaration;
-  rule?: Rule;
-  atRule?: AtRule;
-  prop?: string;
-  selector?: string;
-}
+/**
+ * Context provided to conversion callbacks.
+ *
+ * @example
+ * const transform = (value, unit, context) => {
+ *   if (context.prop === 'letter-spacing') return value * 12
+ *   return value * 16
+ * }
+ */
+type TransformContext = ReplaceContext;
+/**
+ * Per-unit conversion callback.
+ *
+ * @example
+ * const unitMap = {
+ *   rem: (value, context) => value * 16,
+ * }
+ */
 type UnitTransform = (value: number, context: TransformContext) => number;
+/**
+ * Global conversion callback when no per-unit rule is available.
+ *
+ * @example
+ * const transform = (value, unit, context) => {
+ *   return unit === 'vw' ? value * 3.75 : value * 16
+ * }
+ */
 type GlobalTransform = (value: number, unit: string, context: TransformContext) => number;
+/**
+ * Per-unit conversion rules.
+ *
+ * @default
+ * {
+ *   rem: 16,
+ *   em: 16,
+ *   vw: 3.75,
+ *   vh: 6.67,
+ *   vmin: 3.75,
+ *   vmax: 6.67,
+ *   rpx: 0.5
+ * }
+ *
+ * @example
+ * const unitMap = {
+ *   rem: 16,
+ *   px: null,
+ *   vh: (value) => value * 6.67,
+ * }
+ */
 type UnitMap = Record<string, number | UnitTransform | null>;
 interface UserDefinedOptions {
+  /**
+   * Per-unit conversion rules. Numeric values are multipliers.
+   *
+   * @default
+   * {
+   *   rem: 16,
+   *   em: 16,
+   *   vw: 3.75,
+   *   vh: 6.67,
+   *   vmin: 3.75,
+   *   vmax: 6.67,
+   *   rpx: 0.5
+   * }
+   *
+   * @example
+   * unitMap: { rem: 10, vw: 3.2, px: null }
+   */
   unitMap?: UnitMap;
+  /**
+   * Global conversion callback when a unit has no rule or is set to null.
+   *
+   * @example
+   * transform: (value, unit) => (unit === 'em' ? value * 12 : value * 16)
+   */
   transform?: GlobalTransform;
+  /**
+   * Decimal precision for generated px values.
+   *
+   * @default 5
+   */
   unitPrecision?: number;
+  /**
+   * Minimum source value to convert.
+   *
+   * @default 0
+   */
   minValue?: number;
+  /**
+   * Selectors to ignore.
+   *
+   * @default []
+   */
   selectorBlackList?: (string | RegExp)[];
+  /**
+   * Only declarations with matching properties are processed.
+   *
+   * @default ['*']
+   */
   propList?: (string | RegExp)[];
+  /**
+   * Replace the original declaration value.
+   *
+   * @default true
+   */
   replace?: boolean;
+  /**
+   * Enable unit conversion inside @media params.
+   *
+   * @default false
+   */
   mediaQuery?: boolean;
+  /**
+   * Exclude files by path.
+   *
+   * @default [/node_modules/i]
+   */
   exclude?: (string | RegExp)[] | ((filePath: string) => boolean);
+  /**
+   * Disable this plugin.
+   *
+   * @default false
+   */
   disabled?: boolean;
 }
+/**
+ * PostCSS plugin creator for postcss-units-to-px.
+ *
+ * @example
+ * import postcss from 'postcss'
+ * import unitsToPx from 'postcss-units-to-px'
+ *
+ * const result = await postcss([unitsToPx()]).process('.a{margin:1rem}', { from: undefined })
+ */
 type PostcssUnitsToPx = PluginCreator<UserDefinedOptions>;
 //#endregion
 //#region src/plugin.d.ts
+/**
+ * Convert multiple CSS units to px based on a unit map and optional transform.
+ *
+ * Defaults:
+ * - unitMap: { rem: 16, em: 16, vw: 3.75, vh: 6.67, vmin: 3.75, vmax: 6.67, rpx: 0.5 }
+ * - unitPrecision: 5
+ * - propList: ['*']
+ * - replace: true
+ * - mediaQuery: false
+ * - minValue: 0
+ * - exclude: [/node_modules/i]
+ * - disabled: false
+ *
+ * @example
+ * import postcss from 'postcss'
+ * import unitsToPx from 'postcss-units-to-px'
+ *
+ * const result = await postcss([unitsToPx({
+ *   unitMap: { rem: 16, vw: 3.75 },
+ *   transform: (value, unit) => (unit === 'em' ? value * 12 : value * 16),
+ * })]).process('.a{margin:1rem 1vw}', { from: undefined })
+ */
 declare const plugin: PostcssUnitsToPx;
 //#endregion
 export { GlobalTransform, PostcssUnitsToPx, TransformContext, UnitMap, UnitTransform, UserDefinedOptions, plugin as default };

package/dist/index.mjs

@@ -1,9 +1,5 @@
-import { createConfigGetter, createExcludeMatcher, createPropListMatcher, createUnitRegex, declarationExists, maybeBlacklistedSelector, toFixed } from "postcss-plugin-shared";
+import { createConfigGetter, createUnitRegex, toFixed, walkAndReplaceValues } from "postcss-plugin-shared";
 
-//#region package.json
-var name = "postcss-units-to-px";
-
-//#endregion
 //#region src/defaults.ts
 const defaultUnitMap = {
 	rem: 16,
@@ -26,11 +22,35 @@ const defaultOptions = {
 	disabled: false
 };
 
+//#endregion
+//#region package.json
+var name = "postcss-units-to-px";
+
 //#endregion
 //#region src/shared.ts
+/**
+* PostCSS plugin name used by this package.
+*
+* @default package.json name
+*/
 const postcssPlugin = name;
+/**
+* Merge user options with defaults for postcss-units-to-px.
+*
+* Defaults:
+* - unitMap: { rem: 16, em: 16, vw: 3.75, vh: 6.67, vmin: 3.75, vmax: 6.67, rpx: 0.5 }
+* - unitPrecision: 5
+* - propList: ['*']
+* - replace: true
+* - mediaQuery: false
+* - minValue: 0
+* - exclude: [/node_modules/i]
+* - disabled: false
+*
+* @example
+* const config = getConfig({ unitPrecision: 4 })
+*/
 const getConfig = createConfigGetter(defaultOptions);
-const blacklistedSelector = maybeBlacklistedSelector;
 
 //#endregion
 //#region src/plugin.ts
@@ -66,62 +86,54 @@ function createReplace(unitMap, unitPrecision, minValue, transform, context) {
 		return `${roundedValue}px`;
 	};
 }
+/**
+* Convert multiple CSS units to px based on a unit map and optional transform.
+*
+* Defaults:
+* - unitMap: { rem: 16, em: 16, vw: 3.75, vh: 6.67, vmin: 3.75, vmax: 6.67, rpx: 0.5 }
+* - unitPrecision: 5
+* - propList: ['*']
+* - replace: true
+* - mediaQuery: false
+* - minValue: 0
+* - exclude: [/node_modules/i]
+* - disabled: false
+*
+* @example
+* import postcss from 'postcss'
+* import unitsToPx from 'postcss-units-to-px'
+*
+* const result = await postcss([unitsToPx({
+*   unitMap: { rem: 16, vw: 3.75 },
+*   transform: (value, unit) => (unit === 'em' ? value * 12 : value * 16),
+* })]).process('.a{margin:1rem 1vw}', { from: undefined })
+*/
 const plugin = (options = {}) => {
-	const { unitMap: mergedUnitMap, transform, unitPrecision, minValue, selectorBlackList, propList, replace, mediaQuery, exclude, disabled } = getConfig(options);
+	const { transform, unitPrecision, minValue, selectorBlackList, propList, replace, mediaQuery, exclude, disabled } = getConfig(options);
+	const mergedUnitMap = {
+		...defaultUnitMap,
+		...options.unitMap ?? {}
+	};
 	if (disabled) return { postcssPlugin };
 	const normalizedUnitMap = normalizeUnitMap(mergedUnitMap);
 	const units = getUnitsForRegex(normalizedUnitMap);
 	if (units.length === 0) return { postcssPlugin };
 	const unitRegex = createUnitRegex({ units });
-	const unitTestRegex = new RegExp(unitRegex.source, unitRegex.flags.replace("g", ""));
-	const satisfyPropList = createPropListMatcher(propList);
-	const excludeFn = createExcludeMatcher(exclude);
-	const hasSelectorBlacklist = selectorBlackList.length > 0;
 	return {
 		postcssPlugin,
 		Once(css) {
-			const input = css.source.input;
-			const filePath = input.file;
-			if (excludeFn(filePath)) return;
-			const selectorBlacklistCache = hasSelectorBlacklist ? /* @__PURE__ */ new WeakMap() : void 0;
-			css.walkDecls((decl) => {
-				if (!satisfyPropList(decl.prop) || !unitTestRegex.test(decl.value)) return;
-				const rule = decl.parent;
-				if (selectorBlacklistCache) {
-					const cached = selectorBlacklistCache.get(rule);
-					const isBlacklisted = cached ?? Boolean(blacklistedSelector(selectorBlackList, rule.selector));
-					if (cached === void 0) selectorBlacklistCache.set(rule, isBlacklisted);
-					if (isBlacklisted) return;
-				}
-				const replacer = createReplace(normalizedUnitMap, unitPrecision, minValue, transform, {
-					root: css,
-					input,
-					filePath,
-					decl,
-					rule,
-					atRule: rule.parent?.type === "atrule" ? rule.parent : void 0,
-					prop: decl.prop,
-					selector: rule.selector
-				});
-				const value = decl.value.replace(unitRegex, replacer);
-				if (value === decl.value) return;
-				if ((rule.nodes?.length ?? 0) > 1 && declarationExists(rule, decl.prop, value)) return;
-				if (replace) {
-					decl.value = value;
-					return;
-				}
-				decl.cloneAfter({ value });
-			});
-			css.walkAtRules((atRule) => {
-				if (!mediaQuery || atRule.name !== "media") return;
-				if (!unitTestRegex.test(atRule.params)) return;
-				const replacer = createReplace(normalizedUnitMap, unitPrecision, minValue, transform, {
-					root: css,
-					input,
-					filePath,
-					atRule
-				});
-				atRule.params = atRule.params.replace(unitRegex, replacer);
+			walkAndReplaceValues({
+				root: css,
+				unitRegex,
+				propList,
+				selectorBlackList,
+				exclude,
+				replace,
+				mediaQuery,
+				createReplacer: (context) => {
+					return createReplace(normalizedUnitMap, unitPrecision, minValue, transform, context);
+				},
+				shouldProcessAtRule: (atRule) => atRule.name === "media"
 			});
 		}
 	};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "postcss-units-to-px",
   "type": "module",
-  "version": "0.0.0",
+  "version": "0.1.0",
   "description": "Convert multiple CSS units to px with PostCSS.",
   "author": "ice breaker <1324318532@qq.com>",
   "license": "MIT",
@@ -25,20 +25,25 @@
   "sideEffects": false,
   "exports": {
     ".": {
-      "types": "./dist/index.d.mts",
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
+      "types": {
+        "import": "./dist/index.d.mts",
+        "require": "./dist/index.d.cts"
       },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
     }
   },
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
+  "typesVersions": {
+    "<4.7": {
+      "*": [
+        "./dist/*",
+        "./dist/index.d.cts"
+      ]
+    }
+  },
   "files": [
     "dist"
   ],
@@ -46,7 +51,7 @@
     "postcss": "^8"
   },
   "dependencies": {
-    "postcss-plugin-shared": "^1.0.0"
+    "postcss-plugin-shared": "^1.1.0"
   },
   "scripts": {
     "dev": "tsdown -w",