postcss-ruler 1.0.1 → 1.1.0

package/README.md

@@ -37,7 +37,7 @@ module.exports = {
 
 ## Features
 
-### 1. At-Rule Mode: Generate Fluid Scale
+### 1. Scale Generation: Create Fluid Scales
 
 Create multiple CSS custom properties from named size pairs:
 ```css
@@ -106,7 +106,81 @@ For example, if you have `xs: [8, 16]` and `lg: [32, 48]`, a cross pair `xs-lg`
 }
 ```
 
-### 2. Inline Mode: Fluid Function
+### 2. Utility Class Generation: Auto-Generate Utility Classes
+
+Generate utility classes from your defined scales with complete selector flexibility:
+
+```css
+@ruler scale({
+  prefix: 'space',
+  pairs: {
+    "xs": [8, 16],
+    "sm": [16, 24],
+    "md": [24, 32]
+  }
+});
+
+/* Basic class selector */
+@ruler utility({
+  selector: '.gap',
+  property: 'gap',
+  scale: 'space'
+});
+
+/* Nested selector with & (for PostCSS nesting) */
+@ruler utility({
+  selector: '&.active',
+  property: 'padding',
+  scale: 'space'
+});
+
+/* Multiple properties */
+@ruler utility({
+  selector: '.p-block',
+  property: ['padding-top', 'padding-bottom'],
+  scale: 'space'
+});
+```
+
+**Generates:**
+```css
+--space-xs: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem);
+--space-sm: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem);
+--space-md: clamp(1.5rem, 0.5556vw + 1.3889rem, 2rem);
+
+.gap-xs { gap: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem) }
+.gap-sm { gap: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem) }
+.gap-md { gap: clamp(1.5rem, 0.5556vw + 1.3889rem, 2rem) }
+
+&.active-xs { padding: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem) }
+&.active-sm { padding: clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem) }
+&.active-md { padding: clamp(1.5rem, 0.5556vw + 1.3889rem, 2rem) }
+
+.p-block-xs {
+  padding-top: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem);
+  padding-bottom: clamp(0.5rem, 0.5556vw + 0.3889rem, 1rem)
+}
+/* ... */
+```
+
+**Supported selector patterns:**
+- **Class selectors**: `.gap` → `.gap-xs`, `.gap-sm`, `.gap-md`
+- **Nested with &**: `&.active` → `&.active-xs`, `&.active-sm` (PostCSS nesting)
+- **Multiple classes**: `.container.space` → `.container.space-xs`, etc.
+- **ID selectors**: `#section` → `#section-xs`, `#section-sm`
+- **Element selectors**: `section` → `section-xs`, `section-sm`
+- **Parent context**: `.container &` → `.container &-xs`, etc.
+
+**Utility options:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `selector` | string | Yes | Any valid CSS selector pattern (e.g., `.gap`, `&.active`, `#section`) |
+| `property` | string or array | Yes | CSS property name(s) to apply the scale values to |
+| `scale` | string | Yes | Name of a previously defined scale (the `prefix` value) |
+| `generateAllCrossPairs` | boolean | No | Include/exclude cross-pairs (overrides scale default) |
+
+### 3. Inline Mode: Fluid Function
 
 Convert individual values directly to `clamp()` functions:
 ```css
@@ -166,6 +240,15 @@ ruler.fluid(minSize, maxSize[, minWidth, maxWidth])
 | `minWidth` | number | No | Minimum viewport width (uses config default) |
 | `maxWidth` | number | No | Maximum viewport width (uses config default) |
 
+### 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) |
+
 ## How It Works
 
 The plugin uses linear interpolation to create fluid values that scale smoothly between viewport sizes:
@@ -189,6 +272,62 @@ At 1760px viewport: `1.5rem` (24px)
 
 ## Use Cases
 
+### Utility-First Workflow with Fluid Scales
+
+Generate a complete set of utility classes from your design system:
+
+```css
+@ruler scale({
+  prefix: 'space',
+  generateAllCrossPairs: true,
+  pairs: {
+    "xs": [8, 16],
+    "sm": [12, 20],
+    "md": [16, 28],
+    "lg": [24, 40],
+    "xl": [32, 56]
+  }
+});
+
+/* Gap utilities */
+@ruler utility({
+  selector: '.gap',
+  property: 'gap',
+  scale: 'space'
+});
+
+/* Padding utilities */
+@ruler utility({
+  selector: '.p',
+  property: 'padding',
+  scale: 'space'
+});
+
+/* Margin utilities */
+@ruler utility({
+  selector: '.m',
+  property: 'margin',
+  scale: 'space'
+});
+
+/* Stack spacing (for flow layout) */
+@ruler utility({
+  selector: '.stack > * + *',
+  property: 'margin-top',
+  scale: 'space'
+});
+```
+
+Use in your HTML:
+```html
+<section class="p-lg gap-md">
+  <div class="stack gap-sm">
+    <h2>Heading</h2>
+    <p>Content that scales smoothly</p>
+  </div>
+</section>
+```
+
 ### Responsive Typography
 
 ```css

package/index.js

@@ -11,6 +11,9 @@ module.exports = opts => {
     };
     const config = Object.assign(DEFAULTS, opts);
 
+    // Storage for generated scales
+    const scales = {};
+
     /**
      * Converts pixels to r]em units
      * @param {number} px - Pixel value to convert
@@ -113,7 +116,6 @@ module.exports = opts => {
             minWidth: config.minWidth,
             maxWidth: config.maxWidth,
             pairs: {},
-            relativeTo: 'viewport',
             prefix: 'space',
             generateAllCrossPairs: config.generateAllCrossPairs,
         };
@@ -132,11 +134,7 @@ module.exports = opts => {
                     i++;
                     break;
                 case 'prefix':
-                    clampsParams.prefix = value.replace(/['\"]/g, '');
-                    i++;
-                    break;
-                case 'relativeTo':
-                    clampsParams.relativeTo = value.replace(/['\"]/g, '');
+                    clampsParams.prefix = value.replace(/['"]/g, '');
                     i++;
                     break;
                 case 'generateAllCrossPairs':
@@ -187,6 +185,61 @@ module.exports = opts => {
         return pairs;
     };
 
+    /**
+     * Parses parameters from @ruler utility() at-rule
+     * @param {Array} params - Parsed parameter nodes
+     * @returns {Object} Parsed configuration object
+     */
+    const parseUtilityParams = params => {
+        const utilityParams = {
+            selector: null,
+            property: null,
+            scale: null,
+            generateAllCrossPairs: null,
+        };
+
+        for (let i = 0; i < params.length; i++) {
+            const param = params[i];
+            const nextParam = params[i + 1];
+            if (!param || !nextParam) continue;
+            const key = param.value;
+            let value = nextParam.value.replace(/[:,]/g, '');
+
+            switch (key) {
+                case 'selector':
+                case 'scale':
+                    utilityParams[key] = value.replace(/['"]/g, '');
+                    i++;
+                    break;
+                case 'property':
+                    // Check if it's an array (next token is '[')
+                    if (nextParam.value === '[') {
+                        // It's an array - collect values until we hit ']'
+                        const arrayValues = [];
+                        i += 2; // Skip 'property' and '['
+                        while (i < params.length && params[i].value !== ']') {
+                            if (params[i].type === 'string') {
+                                arrayValues.push(params[i].value);
+                            }
+                            i++;
+                        }
+                        utilityParams.property = arrayValues;
+                    } else {
+                        // Single value
+                        utilityParams.property = value.replace(/['"]/g, '');
+                        i++;
+                    }
+                    break;
+                case 'generateAllCrossPairs':
+                    utilityParams.generateAllCrossPairs = value === 'true';
+                    i++;
+                    break;
+            }
+        }
+
+        return utilityParams;
+    };
+
     /**
      * Processes @fluid at-rule and generates CSS custom properties
      * @param {Object} atRule - PostCSS at-rule node
@@ -217,11 +270,90 @@ module.exports = opts => {
             pairs: clampPairs,
         });
 
-        const response = clampScale
-            .map(step => `--${clampsParams.prefix}-${step.label}: ${step.clamp};`)
-            .join('\n');
+        // Store the scale for later use by utility classes
+        scales[clampsParams.prefix] = clampScale;
+
+        const postcss = require('postcss');
+        const root = postcss.root();
+
+        clampScale.forEach(step => {
+            root.append(
+                postcss.decl({
+                    prop: `--${clampsParams.prefix}-${step.label}`,
+                    value: step.clamp,
+                })
+            );
+        });
+
+        atRule.replaceWith(root.nodes);
+    };
+
+    /**
+     * Processes @ruler utility() at-rule and generates utility classes
+     * @param {Object} atRule - PostCSS at-rule node
+     */
+    const processUtilityAtRule = atRule => {
+        const postcss = require('postcss');
+        const { nodes } = CSSValueParser(atRule.params);
+        const params = nodes[0].nodes.filter(
+            x =>
+                ['word', 'string', 'function'].includes(x.type) &&
+                x.value !== '{' &&
+                x.value !== '}'
+        );
+
+        const utilityParams = parseUtilityParams(params);
+
+        // Validate required parameters
+        if (!utilityParams.selector) {
+            throw new Error(
+                '[postcss-ruler] @ruler utility() requires a "selector" parameter'
+            );
+        }
+        if (!utilityParams.property) {
+            throw new Error(
+                '[postcss-ruler] @ruler utility() requires a "property" parameter'
+            );
+        }
+        if (!utilityParams.scale) {
+            throw new Error(
+                '[postcss-ruler] @ruler utility() requires a "scale" parameter'
+            );
+        }
+
+        // Check if scale exists
+        const scale = scales[utilityParams.scale];
+        if (!scale) {
+            throw new Error(
+                `[postcss-ruler] Scale "${utilityParams.scale}" not found. Define it with @ruler scale() first.`
+            );
+        }
+
+        // Determine which scale items to use
+        let scaleItems = scale;
+        if (utilityParams.generateAllCrossPairs === false) {
+            // Filter out cross-pairs (items with hyphens in label)
+            scaleItems = scale.filter(item => !item.label.includes('-'));
+        }
+
+        // Normalize property to array
+        const properties = Array.isArray(utilityParams.property)
+            ? utilityParams.property
+            : [utilityParams.property];
+
+        // Generate utility classes as PostCSS nodes
+        const rules = scaleItems.map(item => {
+            const selector = `${utilityParams.selector}-${item.label}`;
+            const rule = postcss.rule({ selector });
+
+            properties.forEach(prop => {
+                rule.append(postcss.decl({ prop, value: item.clamp }));
+            });
+
+            return rule;
+        });
 
-        atRule.replaceWith(response);
+        atRule.replaceWith(rules);
     };
 
     /**
@@ -267,6 +399,8 @@ module.exports = opts => {
             ruler: atRule => {
                 if (atRule.params.startsWith('scale(')) {
                     return processFluidAtRule(atRule);
+                } else if (atRule.params.startsWith('utility(')) {
+                    return processUtilityAtRule(atRule);
                 }
             },
         },

package/package.json

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