postcss-ruler 1.3.0 → 2.0.0

package/README.md

@@ -33,6 +33,16 @@ module.exports = {
       minWidth: 320, // Default minimum viewport width
       maxWidth: 1760, // Default maximum viewport width
       generateAllCrossPairs: false,
+      // Optional: Pre-define scales for cross-file usage (Astro, Vite, etc.)
+      scales: {
+        space: {
+          pairs: {
+            xs: [8, 16],
+            sm: [16, 24],
+            md: [24, 32],
+          },
+        },
+      },
     },
   },
 };
@@ -230,15 +240,157 @@ Convert individual values directly to `clamp()` functions:
 }
 ```
 
+### 4. Low Specificity Mode: Zero-Specificity Utilities
+
+Wrap generated selectors in `:where()` to reduce their specificity to 0, making them easier to override:
+
+```css
+@ruler scale({
+  prefix: 'space',
+  pairs: {
+    "xs": [8, 16],
+    "sm": [16, 24]
+  }
+});
+
+/* Enable lowSpecificity per utility */
+@ruler utility({
+  selector: '.gap',
+  property: 'gap',
+  scale: 'space',
+  lowSpecificity: true
+});
+```
+
+**Generates:**
+
+```css
+--space-xs: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem);
+--space-sm: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem);
+
+:where(.gap-xs) {
+  gap: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem);
+}
+:where(.gap-sm) {
+  gap: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem);
+}
+```
+
+**Specificity comparison:**
+
+- `.gap-xs` → specificity (0,1,0)
+- `:where(.gap-xs)` → specificity (0,0,0)
+
+**Use case:** Design system utilities that should be easily overridable without `!important`:
+
+```css
+/* Utility with zero specificity */
+:where(.gap-md) {
+  gap: clamp(1.5rem, 0.5556vw + 1.3889rem, 2rem);
+}
+
+/* Easy to override with a simple class */
+.custom-layout {
+  gap: 2rem; /* This wins without !important */
+}
+```
+
+**Works with attribute mode:**
+
+```css
+@ruler utility({
+  attribute: 'data-size',
+  property: 'font-size',
+  scale: 'size',
+  lowSpecificity: true
+});
+```
+
+**Generates:**
+
+```css
+:where([data-size="xs"]) {
+  font-size: var(--size-xs);
+}
+:where([data-size="sm"]) {
+  font-size: var(--size-sm);
+}
+```
+
+**Global configuration:**
+
+```javascript
+// postcss.config.js
+module.exports = {
+  plugins: {
+    "postcss-ruler": {
+      lowSpecificity: true, // All utilities use :where() by default
+    },
+  },
+};
+```
+
+You can override the global setting per utility by explicitly setting `lowSpecificity: false`.
+
 ## Configuration Options
 
 ### Plugin Options
 
-| Option                  | Type    | Default | Description                               |
-| ----------------------- | ------- | ------- | ----------------------------------------- |
-| `minWidth`              | number  | `320`   | Default minimum viewport width in pixels  |
-| `maxWidth`              | number  | `1760`  | Default maximum viewport width in pixels  |
-| `generateAllCrossPairs` | boolean | `false` | Generate cross-combinations in scale mode |
+| Option                  | Type    | Default | Description                                                    |
+| ----------------------- | ------- | ------- | -------------------------------------------------------------- |
+| `minWidth`              | number  | `320`   | Default minimum viewport width in pixels                       |
+| `maxWidth`              | number  | `1760`  | Default maximum viewport width in pixels                       |
+| `generateAllCrossPairs` | boolean | `false` | Generate cross-combinations in scale mode                      |
+| `lowSpecificity`        | boolean | `false` | Wrap utility selectors in `:where()` to lower specificity to 0 |
+| `scales`                | object  | `{}`    | Pre-defined scales for cross-file usage (see below)            |
+
+### Pre-defined Scales (for Astro, Vite, etc.)
+
+When using bundlers like Astro or Vite that process CSS files in unpredictable order, you may encounter issues where `@ruler utility()` in one file can't reference a scale defined with `@ruler scale()` in another file.
+
+To solve this, define your scales in the plugin config:
+
+```javascript
+// postcss.config.js
+module.exports = {
+  plugins: {
+    "postcss-ruler": {
+      scales: {
+        space: {
+          pairs: {
+            xs: [8, 16],
+            sm: [16, 24],
+            md: [24, 32],
+            lg: [32, 48],
+          },
+        },
+        size: {
+          minWidth: 400,
+          maxWidth: 1200,
+          generateAllCrossPairs: true,
+          pairs: {
+            sm: [100, 200],
+            md: [200, 400],
+          },
+        },
+      },
+    },
+  },
+};
+```
+
+Now you can use `@ruler utility()` in any file without needing `@ruler scale()` first:
+
+```css
+/* Component.astro or any CSS file */
+@ruler utility({
+  selector: '.gap',
+  property: 'gap',
+  scale: 'space'
+});
+```
+
+**Note:** If you use `@ruler scale()` with the same prefix as a config-defined scale, the inline scale will override the config scale for that file.
 
 ### At-Rule Options
 
@@ -308,12 +460,13 @@ When min and max values are equal, postcss-ruler outputs a simple rem value inst
 
 ### Utility Options
 
-| Option                  | Type            | Default  | Description                                                           |
-| ----------------------- | --------------- | -------- | --------------------------------------------------------------------- |
-| `selector`              | string          | required | Any valid CSS selector pattern (e.g., `.gap`, `&.active`, `#section`) |
-| `property`              | string or array | required | CSS property name(s) to apply the scale values to                     |
-| `scale`                 | string          | required | Name of a previously defined scale (the `prefix` value)               |
-| `generateAllCrossPairs` | boolean         | No       | Include/exclude cross-pairs (overrides scale default)                 |
+| Option                  | Type            | Default  | Description                                                                       |
+| ----------------------- | --------------- | -------- | --------------------------------------------------------------------------------- |
+| `selector`              | string          | required | Any valid CSS selector pattern (e.g., `.gap`, `&.active`, `#section`)             |
+| `property`              | string or array | required | CSS property name(s) to apply the scale values to                                 |
+| `scale`                 | string          | required | Name of a previously defined scale (the `prefix` value)                           |
+| `generateAllCrossPairs` | boolean         | No       | Include/exclude cross-pairs (overrides scale default)                             |
+| `lowSpecificity`        | boolean         | No       | Wrap selectors in `:where()` to reduce specificity to 0 (overrides global config) |
 
 ## How It Works
 

package/index.js

@@ -8,6 +8,8 @@ module.exports = (opts) => {
     minWidth: 320,
     maxWidth: 1760,
     generateAllCrossPairs: false,
+    lowSpecificity: false,
+    scales: {},
   };
   const config = Object.assign(DEFAULTS, opts);
 
@@ -111,6 +113,35 @@ module.exports = (opts) => {
     return clampScales;
   };
 
+  /**
+   * Pre-processes scales defined in plugin config
+   * @param {Object} configScales - Scales object from plugin options
+   */
+  const initializeConfigScales = (configScales) => {
+    Object.entries(configScales).forEach(([prefix, scaleConfig]) => {
+      const scaleOpts = {
+        minWidth: scaleConfig.minWidth || config.minWidth,
+        maxWidth: scaleConfig.maxWidth || config.maxWidth,
+        generateAllCrossPairs:
+          scaleConfig.generateAllCrossPairs ?? config.generateAllCrossPairs,
+      };
+
+      const clampPairs = Object.entries(scaleConfig.pairs).map(
+        ([name, values]) => ({ name, values }),
+      );
+
+      scales[prefix] = generateClamps({
+        pairs: clampPairs,
+        ...scaleOpts,
+      });
+    });
+  };
+
+  // Initialize scales from config (if any)
+  if (Object.keys(config.scales).length > 0) {
+    initializeConfigScales(config.scales);
+  }
+
   /**
    * Parses parameters from @fluid at-rule
    * @param {Array} params - Parsed parameter nodes
@@ -202,6 +233,7 @@ module.exports = (opts) => {
       scale: null,
       generateAllCrossPairs: null,
       attribute: null,
+      lowSpecificity: null,
     };
 
     for (let i = 0; i < params.length; i++) {
@@ -241,6 +273,10 @@ module.exports = (opts) => {
           utilityParams.generateAllCrossPairs = value === "true";
           i++;
           break;
+        case "lowSpecificity":
+          utilityParams.lowSpecificity = value === "true";
+          i++;
+          break;
       }
     }
 
@@ -309,16 +345,21 @@ module.exports = (opts) => {
 
     const utilityParams = parseUtilityParams(params);
 
+    // Resolve lowSpecificity from config if not explicitly set
+    if (utilityParams.lowSpecificity === null) {
+      utilityParams.lowSpecificity = config.lowSpecificity;
+    }
+
     // Validate attribute-specific constraints first
     if (utilityParams.attribute !== null) {
       if (utilityParams.attribute === "") {
         throw new Error(
-          '[postcss-ruler] @ruler utility() attribute parameter cannot be empty',
+          "[postcss-ruler] @ruler utility() attribute parameter cannot be empty",
         );
       }
       if (!/^[a-zA-Z0-9_-]+$/.test(utilityParams.attribute)) {
         throw new Error(
-          '[postcss-ruler] @ruler utility() attribute parameter must contain only letters, numbers, hyphens, and underscores',
+          "[postcss-ruler] @ruler utility() attribute parameter must contain only letters, numbers, hyphens, and underscores",
         );
       }
     }
@@ -368,13 +409,31 @@ module.exports = (opts) => {
       if (utilityParams.attribute) {
         // Attribute mode: [data-attr="value"] or .class[data-attr="value"]
         const attrSelector = `[${utilityParams.attribute}="${item.label}"]`;
-        ruleSelector = utilityParams.selector
+        const baseSelector = utilityParams.selector
           ? `${utilityParams.selector}${attrSelector}`
           : attrSelector;
+        ruleSelector = utilityParams.lowSpecificity
+          ? `:where(${baseSelector})`
+          : baseSelector;
         ruleValue = `var(--${utilityParams.scale}-${item.label})`;
       } else {
         // Class mode (existing behavior)
-        ruleSelector = `${utilityParams.selector}-${item.label}`;
+        const baseSelector = `${utilityParams.selector}-${item.label}`;
+
+        // Handle parent context selectors (e.g., ".container &")
+        if (utilityParams.lowSpecificity) {
+          if (utilityParams.selector.endsWith(" &")) {
+            // Parent context: ".container &" -> ".container :where(&-xs)"
+            const parentPart = utilityParams.selector.slice(0, -1); // Remove trailing "&"
+            ruleSelector = `${parentPart}:where(&-${item.label})`;
+          } else {
+            // Regular selector: wrap entire selector
+            ruleSelector = `:where(${baseSelector})`;
+          }
+        } else {
+          ruleSelector = baseSelector;
+        }
+
         ruleValue = item.clamp;
       }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-ruler",
-  "version": "1.3.0",
+  "version": "2.0.0",
   "description": "PostCSS plugin to generate fluid scales and values.",
   "main": "index.js",
   "files": [
@@ -37,7 +37,7 @@
   },
   "eslintConfig": {
     "parserOptions": {
-      "ecmaVersion": 2018
+      "ecmaVersion": 2020
     },
     "env": {
       "node": true,