postcss-custom-supports 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chloe Burroughs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,96 @@
+# postcss-custom-supports
+
+_Note: I created this plugin for a specific project because I was tired of remembering the advanced attributes @supports query and fighting VS Code's parser. I'm releasing it because I hope it’s helpful. It was built with Claude Opus 4.6._
+
+A [PostCSS](https://postcss.org/) plugin that brings the [`@custom-media`](https://www.w3.org/TR/mediaqueries-5/#custom-mq) authoring pattern to `@supports` queries. Define a feature-detection condition once, give it a `--name`, and reference it from any number of `@supports` rules.
+
+```css
+@custom-supports --inert interactivity: inert;
+@custom-supports --scroll animation-timeline: scroll();
+@custom-supports --attr x: attr(x type(*));
+
+@supports (--inert) {
+  [hidden-while-animating] { interactivity: inert; }
+}
+
+@supports not (--scroll) {
+  /* IntersectionObserver fallback */
+}
+
+@supports (--attr) and (--inert) {
+  /* combined */
+}
+```
+
+becomes
+
+```css
+@supports (interactivity: inert) {
+  [hidden-while-animating] { interactivity: inert; }
+}
+
+@supports not (animation-timeline: scroll()) {
+  /* IntersectionObserver fallback */
+}
+
+@supports (x: attr(x type(*))) and (interactivity: inert) {
+  /* combined */
+}
+```
+
+## Why
+
+Real-world `@supports` conditions are often verbose (`x: attr(x type(*))`), brittle to type, and visually noisy when repeated across a stylesheet. They also confuse some editor parsers when the value uses bleeding-edge syntax. Aliasing them behind a stable `--name` mirrors how `@custom-media` keeps breakpoints readable.
+
+## Install
+
+```sh
+npm install --save-dev postcss-custom-supports
+```
+
+## Usage
+
+```js
+const postcss = require('postcss');
+const customSupports = require('postcss-custom-supports');
+
+postcss([customSupports(/* options */)]).process(css);
+```
+
+### Options
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `preserve` | `boolean` | `false` | Keep `@custom-supports` declarations in the output (useful for downstream tools that consume the source CSS). |
+
+## Syntax
+
+A declaration:
+
+```
+@custom-supports --<name> <condition>;
+```
+
+`<condition>` is any string that would be valid inside the parentheses of a normal `@supports` query — typically `property: value`, but also `selector(...)`, `font-tech(...)`, etc.
+
+A reference is the literal token `(--<name>)`, used anywhere a parenthesized supports condition is allowed:
+
+```css
+@supports (--name) { … }
+@supports not (--name) { … }
+@supports (--a) and (--b) { … }
+```
+
+References inside function calls (`var(--name)`, `attr(--name)`, etc.) are **not** rewritten, so it is safe to reference custom properties in supports conditions.
+
+## Warnings
+
+The plugin emits PostCSS warnings (not errors) for:
+
+- Malformed `@custom-supports` declarations (missing condition).
+- Redefinition of a name (the last definition wins).
+- References to undefined names (left untouched in the output).
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,57 @@
+'use strict';
+
+// Matches a single @custom-supports declaration:
+//   @custom-supports --name <condition>;
+// PostCSS strips the trailing semicolon and normalizes whitespace before
+// handing us `rule.params`, so a single space between name and condition
+// 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 }) {
+      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})`;
+        });
+      });
+    },
+  };
+};
+
+creator.postcss = true;
+
+module.exports = creator;

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "postcss-custom-supports",
+  "version": "0.1.0",
+  "description": "PostCSS plugin that mirrors @custom-media for @supports queries, letting you alias verbose or experimental feature-detection conditions behind a custom name.",
+  "main": "index.js",
+  "files": [
+    "index.js"
+  ],
+  "scripts": {
+    "test": "node --test index.test.js"
+  },
+  "keywords": [
+    "postcss",
+    "postcss-plugin",
+    "css",
+    "supports",
+    "custom-supports",
+    "feature-queries"
+  ],
+  "peerDependencies": {
+    "postcss": "^8.4.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT"
+}