feat: modifyPreflightStyles option to hook into the preflight styles

Roman86 · Roman86 · commit cf6bfb5c367d · 2024-03-28T00:56:55.000+01:00
diff --git a/README.md b/README.md
@@ -21,7 +21,7 @@ Starting from version 3 it provides a powerful configuration to (optionally):
 
 - 🤌 precisely control CSS selectors;
 - 💨 flexibly remove some CSS rules, if you need;
-- 🔎 or even remove particular CSS properties (if you have some specific conflicts).
+- 🔎 or even remove (or change) particular CSS properties (if you have some specific conflicts).
 
 For ease of use, there are 3 pre-bundled isolation strategies available (as named imports) that cover 99% cases:
 
@@ -92,15 +92,36 @@ const config = {
       // it's also possible to filter out some properties:
       // return false to remove the property,
       // any other value (including true and undefined) will leave the prop intact
+      // (propsFilter is DEPRECATED - prefer using modifyPreflightStyles instead of propFilter)
       propsFilter: ({ selectorSet, property, value }) =>
+        // return false to remove the property. Any other value (including true and undefined) will leave the prop intact
         ![
           // removes the margin reset from a body rule
           selectorSet.has('body') && ['margin'].includes(property),
           // removes the box-sizing: border-box whenever it's found
           property === 'box-sizing' && value === 'border-box',
           // removes the font-family (except inherit) from all the rules
           property === 'font-family' && value !== 'inherit',
-        ].some(Boolean), // yep, "some" approach is a bit slower because it will evaluate all array conditions anyway, but it's more readable without || operators
+        ].some(Boolean),
+      // preferred way to modify the preflight styles
+      modifyPreflightStyles: ({ selectorSet, property, value }) => {
+        // let's say you want to override the font family
+        if (property === 'font-family' && value !== 'inherit') {
+          return '"Open Sans", sans-serif';
+        }
+        // or body margin
+        if (selectorSet.has('body') && property === 'margin') {
+          return '0 4px';
+        }
+        // if you want to remove some property - return null
+        if (selectorSet.has('html') && property === 'line-height') {
+          return null;
+        }
+        // to keep the property as it is - you may return the original value;
+        // but returning undefined would have the same effect,
+        // so you may just omit such default return
+        return value;
+      },
     }),
   ],
 };
@@ -199,16 +220,13 @@ const config = {
             ? `${ruleSelector} .twp` // some custom transformation for html, :host and body
             : isolateForComponents('.twp')(ruleSelector), // otherwise, transform it as per components strategy (just for example)
 
-      // just for demo purpose - let's also filter out some properties
-      propsFilter: ({ selectorSet, property, value }) =>
-        ![
-          // removes the margin reset from a body rule
-          selectorSet.has('body') && ['margin'].includes(property),
-          // removes the box-sizing: border-box whenever it's found
-          property === 'box-sizing' && value === 'border-box',
-          // removes the font-family (except inherit) from all the rules
-          property === 'font-family' && value !== 'inherit',
-        ].some(Boolean), // yep, "some" approach is a bit slower because it will evaluate all array conditions anyway, but it's more readable without || operators
+      // just for demo purpose
+      modifyPreflightStyles: ({ selectorSet, property, value }) => {
+        // let's say you want to override the font family
+        if (property === 'font-family' && value !== 'inherit') {
+          return '"Open Sans", sans-serif';
+        }
+      },
     }),
   ],
 };
diff --git a/demo/index.html b/demo/index.html
@@ -9,7 +9,7 @@
 </head>
 <body>
 <div class="twp bg-zinc-300 text-sky-700 m-2">
-    <div class="border rounded border-black/50 p-4">
+    <div class="font-mono border rounded border-black/50 p-4">
         <h1 class="text-3xl font-bold">Inside</h1>
     </div>
 </div>
diff --git a/demo/tailwind.config.js b/demo/tailwind.config.js
@@ -23,16 +23,37 @@ module.exports = {
       //       ? ruleSelector // keeps the original selector
       //       : enableForSelector(".twp")(ruleSelector), // otherwise, transforms selector as per selected behaviour (scoped to .twp)
 
-      // it's also possible to filter out some properties - return false to remove the property. Any other value (including true and undefined) will leave the prop intact
+      // it's also possible to filter out some properties
+      // (deprecated - prefer using modifyPreflightStyles instead of propFilter)
       propsFilter: ({ selectorSet, property, value }) =>
+        // return false to remove the property. Any other value (including true and undefined) will leave the prop intact
         ![
           // removes the margin reset from a body rule
           selectorSet.has('body') && ['margin'].includes(property),
           // removes the box-sizing: border-box whenever it's found
           property === 'box-sizing' && value === 'border-box',
           // removes the font-family (except inherit) from all the rules
           property === 'font-family' && value !== 'inherit',
-        ].some(Boolean), // yep, "some" approach is a bit slower because it will evaluate all array conditions anyway, but it's more readable without || operators
+        ].some(Boolean),
+      // preferred way to modify the preflight styles
+      modifyPreflightStyles: ({ selectorSet, property, value }) => {
+        // let's say you want to override the font family
+        if (property === 'font-family' && value !== 'inherit') {
+          return '"Open Sans", sans-serif';
+        }
+        // or body margin
+        if (selectorSet.has('body') && property === 'margin') {
+          return '0 4px';
+        }
+        // if you want to remove some property - return null
+        if (selectorSet.has('html') && property === 'line-height') {
+          return null;
+        }
+        // to keep the property as it is - you may return the original value;
+        // but returning undefined would have the same effect,
+        // so you may just omit such default return
+        return value;
+      },
     }),
   ],
 };
diff --git a/src/index.ts b/src/index.ts
@@ -13,7 +13,9 @@ export type CSSRuleSelectorTransformer = (info: { ruleSelector: string }) => str
 
 interface PluginOptions {
   isolationStrategy: CSSRuleSelectorTransformer;
+  /** @deprecated prefer using modifyPreflightStyles */
   propsFilter?: (input: PropsFilterInput) => boolean | undefined;
+  modifyPreflightStyles?: (input: PropsFilterInput) => string | null | undefined;
 }
 
 /**
@@ -22,11 +24,13 @@ interface PluginOptions {
  *  import {@link https://www.npmjs.com/package/tailwindcss-scoped-preflight#isolate-inside-of-container isolateInsideOfContainer},
  *  {@link https://www.npmjs.com/package/tailwindcss-scoped-preflight#isolate-outside-of-container isolateOutsideOfContainer},
  *  {@link https://www.npmjs.com/package/tailwindcss-scoped-preflight#update-your-tailwind-css-configuration isolateForComponents} or write {@link https://www.npmjs.com/package/tailwindcss-scoped-preflight#your-owncustom-isolation-strategy your own}
+ * @deprecated prefer using modifyPreflightStyles
  * @param propsFilter - function to filter the preflight CSS properties and values, return false to remove the property. Any other value (including true and undefined) will leave the prop intact
+ * @param modifyPreflightStyles - function to modify the preflight CSS properties and their values, return null to remove the property. Any other returned value will be used as a new value for the property. If you don't want to change it - return the old value (provided in argument object as `value`).
  * @link https://www.npmjs.com/package/tailwindcss-scoped-preflight (documentation)
  */
 export const scopedPreflightStyles = withOptions<PluginOptions>(
-  ({ isolationStrategy, propsFilter }) =>
+  ({ isolationStrategy, propsFilter, modifyPreflightStyles }) =>
     ({ addBase, corePlugins }) => {
       const baseCssPath = require.resolve('tailwindcss/lib/css/preflight.css');
       const baseCssStyles = postcss.parse(readFileSync(baseCssPath, 'utf8'));
@@ -44,21 +48,31 @@ export const scopedPreflightStyles = withOptions<PluginOptions>(
       }
 
       baseCssStyles.walkRules((rule) => {
-        if (propsFilter) {
+        if (propsFilter || modifyPreflightStyles) {
           const selectorSet = new Set(rule.selectors);
-
           rule.nodes = rule.nodes?.map((node) => {
             if (node instanceof postcss.Declaration) {
-              if (
-                propsFilter({
-                  selectorSet,
-                  property: node.prop,
-                  value: node.value,
-                }) === false
-              ) {
+              const newValue = modifyPreflightStyles
+                ? modifyPreflightStyles({
+                    selectorSet,
+                    property: node.prop,
+                    value: node.value,
+                  })
+                : node.value;
+
+              const filterValue = propsFilter
+                ? propsFilter({
+                    selectorSet,
+                    property: node.prop,
+                    value: node.value,
+                  })
+                : true;
+              if (filterValue === false || newValue === null) {
                 return postcss.comment({
                   text: node.toString(),
                 });
+              } else if (typeof newValue !== 'undefined' && newValue !== node.value) {
+                node.value = newValue;
               }
             }
             return node;
