postcss-custom-supports 0.1.3 → 1.0.0

package/README.md

@@ -54,6 +54,8 @@ npm install --save-dev postcss-custom-supports
 
 ## Usage
 
+**CommonJS**
+
 ```js
 const postcss = require('postcss');
 const customSupports = require('postcss-custom-supports');
@@ -61,6 +63,66 @@ const customSupports = require('postcss-custom-supports');
 postcss([customSupports(/* options */)]).process(css);
 ```
 
+**Vite** — add to `css.postcss` in `vite.config.js` / `vite.config.ts`:
+
+```js
+import { defineConfig } from 'vite';
+import customSupports from 'postcss-custom-supports';
+
+export default defineConfig({
+  css: {
+    postcss: {
+      plugins: [customSupports(/* options */)],
+    },
+  },
+});
+```
+
+**Tailwind CSS v3** — add to `postcss.config.mjs` alongside your other PostCSS plugins:
+
+```js
+import tailwindcss from 'tailwindcss';
+import customSupports from 'postcss-custom-supports';
+
+export default {
+  plugins: [
+    tailwindcss,
+    customSupports(/* options */),
+  ],
+};
+```
+
+**Tailwind CSS v4 + Vite** — Tailwind ships as a Vite plugin in v4; add this plugin to `css.postcss` in `vite.config.js`:
+
+```js
+import { defineConfig } from 'vite';
+import tailwindcss from '@tailwindcss/vite';
+import customSupports from 'postcss-custom-supports';
+
+export default defineConfig({
+  plugins: [tailwindcss()],
+  css: {
+    postcss: {
+      plugins: [customSupports(/* options */)],
+    },
+  },
+});
+```
+
+**Tailwind CSS v4 + PostCSS** (non-Vite) — use `@tailwindcss/postcss` in `postcss.config.mjs`:
+
+```js
+import tailwindcss from '@tailwindcss/postcss';
+import customSupports from 'postcss-custom-supports';
+
+export default {
+  plugins: [
+    tailwindcss,
+    customSupports(/* options */),
+  ],
+};
+```
+
 ### Options
 
 | Option | Type | Default | Description |
@@ -87,6 +149,8 @@ A reference is the literal token `(--<name>)`, used anywhere a parenthesized sup
 
 References inside function calls (`var(--name)`, `attr(--name)`, etc.) are **not** rewritten, so it is safe to reference custom properties in supports conditions.
 
+_Note: When we call a custom supports token, we wrap it in parentheses. This follows the structure of postcss-custom-media, but it also gives an easier visual indicator of the token, compared to without parentheses. It’s a taste thing, but it made sense to me._
+
 ## Warnings
 
 The plugin emits PostCSS warnings (not errors) for:

package/index.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const valueParser = require('postcss-value-parser');
+
 // Matches a single @custom-supports declaration:
 //   @custom-supports --name <condition>;
 // PostCSS strips the trailing semicolon and normalizes whitespace before
@@ -7,47 +9,86 @@
 // is all we need to require here.
 const DEFINITION_RE = /^(--[\w-]+)\s+(.+)$/;
 
-// Matches a (--name) reference inside an @supports condition. The negative
-// lookbehind prevents accidental rewrites of identifiers like var(--foo) or
-// attr(--bar), where the leading character before "(" is an ident-char.
-const REFERENCE_RE = /(?<![\w-])\(--[\w-]+\)/g;
-
 const creator = (opts = {}) => {
   const preserve = opts.preserve === true;
 
   return {
     postcssPlugin: 'postcss-custom-supports',
-    Once(root, { result }) {
+    // prepare() gives us per-process state isolation: a fresh Map per file.
+    // Collection runs as a typed AtRule visitor (joins the main walk for free),
+    // and replacement defers to OnceExit so all definitions — including ones
+    // declared after their first reference — are resolved before rewriting.
+    prepare() {
       const customs = new Map();
 
-      root.walkAtRules('custom-supports', rule => {
-        const match = rule.params.match(DEFINITION_RE);
-        if (!match) {
-          rule.warn(result, `Invalid @custom-supports declaration: "${rule.params}"`);
-          if (!preserve) rule.remove();
-          return;
-        }
-
-        const [, name, condition] = match;
-        if (customs.has(name)) {
-          rule.warn(result, `@custom-supports ${name} is redefined; the last definition wins`);
-        }
-        customs.set(name, condition.trim());
-
-        if (!preserve) rule.remove();
-      });
-
-      root.walkAtRules('supports', rule => {
-        rule.params = rule.params.replace(REFERENCE_RE, token => {
-          const name = token.slice(1, -1);
-          const value = customs.get(name);
-          if (value === undefined) {
-            rule.warn(result, `Unknown @custom-supports reference: ${name}`);
-            return token;
-          }
-          return `(${value})`;
-        });
-      });
+      return {
+        AtRule: {
+          'custom-supports'(rule, { result }) {
+            const match = rule.params.match(DEFINITION_RE);
+            if (!match) {
+              rule.warn(result, `Invalid @custom-supports declaration: "${rule.params}"`);
+              if (!preserve) rule.remove();
+              return;
+            }
+
+            const [, name, condition] = match;
+            if (customs.has(name)) {
+              rule.warn(result, `@custom-supports ${name} is redefined; the last definition wins`);
+            }
+            customs.set(name, condition.trim());
+
+            if (!preserve) rule.remove();
+          },
+        },
+
+        OnceExit(root, { result }) {
+          // Recurse bottom-up so that inner @supports rules are rewritten
+          // before the outer rule is cloned. If we used root.walkAtRules()
+          // instead, replaceWith(clone) would cause the walker to descend into
+          // the detached original rather than the clone, leaving inner
+          // references unexpanded.
+          const processContainer = container => {
+            container.each(node => {
+              if (node.nodes) processContainer(node);
+              if (node.type !== 'atrule' || node.name !== 'supports') return;
+
+              const parsed = valueParser(node.params);
+              let changed = false;
+
+              parsed.walk(valueNode => {
+                // value-parser gives bare parentheses type 'function' with an
+                // empty value string, which naturally excludes named functions
+                // like var(--x) or attr(--x) — cleaner than the lookbehind
+                // regex this replaces.
+                if (valueNode.type !== 'function' || valueNode.value !== '') return;
+                if (valueNode.nodes.length !== 1 || valueNode.nodes[0].type !== 'word') return;
+                const name = valueNode.nodes[0].value;
+                if (!/^--[\w-]+$/.test(name)) return;
+
+                const condition = customs.get(name);
+                if (condition === undefined) {
+                  node.warn(result, `Unknown @custom-supports reference: ${name}`);
+                  return false;
+                }
+
+                // Expand the condition into this paren node; stop descending
+                // so we never re-process the freshly substituted nodes.
+                valueNode.nodes = valueParser(condition).nodes;
+                changed = true;
+                return false;
+              });
+
+              if (changed) {
+                // .clone() preserves the original node's source position so
+                // PostCSS can emit accurate source maps for the rewritten rule.
+                node.replaceWith(node.clone({ params: valueParser.stringify(parsed) }));
+              }
+            });
+          };
+
+          processContainer(root);
+        },
+      };
     },
   };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-custom-supports",
-  "version": "0.1.3",
+  "version": "1.0.0",
   "description": "PostCSS plugin that mirrors @custom-media for @supports queries, letting you alias verbose or experimental feature-detection conditions behind a custom name.",
   "author": "Chloe Burroughs <chloe@pfr.wtf>",
   "repository": {
@@ -16,7 +16,7 @@
     "index.js"
   ],
   "scripts": {
-    "test": "node --test index.test.js"
+    "test": "c8 node --test index.test.js"
   },
   "keywords": [
     "postcss",
@@ -24,13 +24,21 @@
     "css",
     "supports",
     "custom-supports",
-    "feature-queries"
+    "feature-queries",
+    "atRules"
   ],
   "peerDependencies": {
     "postcss": "^8.4.0"
   },
+  "devDependencies": {
+    "c8": "^11.0.0",
+    "postcss": "^8.4.0"
+  },
   "engines": {
     "node": ">=18.0.0"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "dependencies": {
+    "postcss-value-parser": "^4.2.0"
+  }
 }