postcss-ruler 1.2.0 → 1.4.0

package/README.md

@@ -230,15 +230,108 @@ 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 |
 
 ### At-Rule Options
 
@@ -308,12 +401,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,7 @@ module.exports = (opts) => {
     minWidth: 320,
     maxWidth: 1760,
     generateAllCrossPairs: false,
+    lowSpecificity: false,
   };
   const config = Object.assign(DEFAULTS, opts);
 
@@ -201,6 +202,8 @@ module.exports = (opts) => {
       property: null,
       scale: null,
       generateAllCrossPairs: null,
+      attribute: null,
+      lowSpecificity: null,
     };
 
     for (let i = 0; i < params.length; i++) {
@@ -213,6 +216,7 @@ module.exports = (opts) => {
       switch (key) {
         case "selector":
         case "scale":
+        case "attribute":
           utilityParams[key] = value.replace(/['"]/g, "");
           i++;
           break;
@@ -239,6 +243,10 @@ module.exports = (opts) => {
           utilityParams.generateAllCrossPairs = value === "true";
           i++;
           break;
+        case "lowSpecificity":
+          utilityParams.lowSpecificity = value === "true";
+          i++;
+          break;
       }
     }
 
@@ -307,10 +315,29 @@ 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",
+        );
+      }
+      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",
+        );
+      }
+    }
+
     // Validate required parameters
-    if (!utilityParams.selector) {
+    if (!utilityParams.selector && !utilityParams.attribute) {
       throw new Error(
-        '[postcss-ruler] @ruler utility() requires a "selector" parameter',
+        '[postcss-ruler] @ruler utility() requires either "selector" or "attribute" parameter',
       );
     }
     if (!utilityParams.property) {
@@ -346,11 +373,44 @@ module.exports = (opts) => {
 
     // Generate utility classes as PostCSS nodes
     const rules = scaleItems.map((item) => {
-      const selector = `${utilityParams.selector}-${item.label}`;
-      const rule = postcss.rule({ selector });
+      let ruleSelector;
+      let ruleValue;
+
+      if (utilityParams.attribute) {
+        // Attribute mode: [data-attr="value"] or .class[data-attr="value"]
+        const attrSelector = `[${utilityParams.attribute}="${item.label}"]`;
+        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)
+        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;
+      }
+
+      const rule = postcss.rule({ selector: ruleSelector });
 
       properties.forEach((prop) => {
-        rule.append(postcss.decl({ prop, value: item.clamp }));
+        rule.append(postcss.decl({ prop, value: ruleValue }));
       });
 
       return rule;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "postcss-ruler",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "description": "PostCSS plugin to generate fluid scales and values.",
   "main": "index.js",
   "files": [