postcss-ruler 1.0.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright 2025 Kurt Stubbings <kurt@homeworkclub.co>
+
+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,286 @@
+# postcss-ruler
+
+A PostCSS plugin that generates fluid CSS scales and values using the `clamp()` function. Create responsive typography and spacing that scales smoothly between viewport sizes.
+
+## Installation
+
+```bash
+npm install postcss-ruler
+```
+
+## Usage
+
+Add the plugin to your PostCSS configuration:
+
+```javascript
+// postcss.config.js
+module.exports = {
+  plugins: {
+    'postcss-ruler': {
+      minWidth: 320,    // Default minimum viewport width
+      maxWidth: 1760,   // Default maximum viewport width
+      generateAllCrossPairs: false
+    }
+  }
+}
+```
+
+Or in `.postcssrc`:
+
+```json
+{
+  "plugins": {
+    "postcss-ruler": {
+      "minWidth": 320,
+      "maxWidth": 1760,
+      "generateAllCrossPairs": false
+    }
+  }
+}
+```
+
+## Features
+
+### 1. At-Rule Mode: Generate Fluid Scale
+
+Create multiple CSS custom properties from named size pairs:
+
+```css
+@ruler scale({
+  minWidth: 320,
+  maxWidth: 1760,
+  prefix: 'space',
+  generateAllCrossPairs: false,
+  pairs: {
+    "xs": [8, 16],
+    "sm": [16, 24],
+    "md": [24, 32],
+    "lg": [32, 48],
+    "xl": [48, 64]
+  }
+});
+```
+
+**Generates:**
+
+```css
+--space-xs: clamp(0.5rem, 0.4545vw + 0.3636rem, 1rem);
+--space-sm: clamp(1rem, 0.4545vw + 0.8636rem, 1.5rem);
+--space-md: clamp(1.5rem, 0.4545vw + 1.3636rem, 2rem);
+--space-lg: clamp(2rem, 0.9091vw + 1.7273rem, 3rem);
+--space-xl: clamp(3rem, 0.9091vw + 2.7273rem, 4rem);
+```
+
+**Usage in CSS:**
+
+```css
+.container {
+  padding: var(--space-md);
+  gap: var(--space-sm);
+}
+```
+
+#### Cross Pairs
+
+Enable `generateAllCrossPairs: true` to create additional combinations between all defined pairs:
+
+```css
+@ruler scale({
+  prefix: 'space',
+  generateAllCrossPairs: true,
+  pairs: {
+    "xs": [8, 16],
+    "md": [24, 32],
+    "lg": [32, 48]
+  }
+});
+```
+
+**Generates base pairs plus cross combinations:**
+
+```css
+--space-xs: clamp(...);
+--space-md: clamp(...);
+--space-lg: clamp(...);
+--space-xs-md: clamp(0.5rem, 1.3636vw + 0.3636rem, 2rem);
+--space-xs-lg: clamp(0.5rem, 2.2727vw + 0.3636rem, 3rem);
+--space-md-lg: clamp(1.5rem, 0.9091vw + 1.3636rem, 3rem);
+```
+
+### 2. Inline Mode: Fluid Function
+
+Convert individual values directly to `clamp()` functions:
+
+```css
+.element {
+  /* Uses default minWidth/maxWidth from config */
+  font-size: ruler.fluid(16, 24);
+
+  /* Custom viewport widths */
+  padding: ruler.fluid(12, 20, 320, 1200);
+
+  /* Multiple fluid values */
+  margin: ruler.fluid(8, 16) ruler.fluid(16, 32);
+}
+```
+
+**Generates:**
+
+```css
+.element {
+  font-size: clamp(1rem, 0.4545vw + 0.8636rem, 1.5rem);
+  padding: clamp(0.75rem, 0.9091vw + 0.4773rem, 1.25rem);
+  margin: clamp(0.5rem, 0.4545vw + 0.3636rem, 1rem) clamp(1rem, 0.9091vw + 0.7273rem, 2rem);
+}
+```
+
+## 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 |
+
+### At-Rule Options
+
+All options can be overridden per `@ruler scale()` declaration:
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `minWidth` | number | `320` | Minimum viewport width for this scale |
+| `maxWidth` | number | `1760` | Maximum viewport width for this scale |
+| `prefix` | string | `"space"` | Prefix for generated CSS custom properties |
+| `generateAllCrossPairs` | boolean | `false` | Generate cross-combinations for this scale |
+| `pairs` | object | required | Size pairs as `"name": [min, max]` |
+
+### Inline Function Syntax
+
+```
+ruler.fluid(minSize, maxSize[, minWidth, maxWidth])
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `minSize` | number | Yes | Minimum size in pixels |
+| `maxSize` | number | Yes | Maximum size in pixels |
+| `minWidth` | number | No | Minimum viewport width (uses config default) |
+| `maxWidth` | number | No | Maximum viewport width (uses config default) |
+
+## How It Works
+
+The plugin uses linear interpolation to create fluid values that scale smoothly between viewport sizes:
+
+1. **Converts pixels to rem** (assumes 16px base font size)
+2. **Calculates slope**: `(maxSize - minSize) / (maxWidth - minWidth)`
+3. **Calculates y-intercept**: `-minWidth × slope + minSize`
+4. **Generates clamp**: `clamp(minRem, slopeVw + intersectRem, maxRem)`
+
+### Example Calculation
+
+For `ruler.fluid(16, 24)` with default config (320-1760px):
+
+- Slope: `(24 - 16) / (1760 - 320) = 0.005556`
+- Intercept: `-320 × 0.005556 + 16 = 14.222`
+- Result: `clamp(1rem, 0.5556vw + 0.8889rem, 1.5rem)`
+
+At 320px viewport: `1rem` (16px)
+At 1040px viewport: `1.3333rem` (≈21.3px)
+At 1760px viewport: `1.5rem` (24px)
+
+## Use Cases
+
+### Responsive Typography
+
+```css
+@ruler scale({
+  prefix: 'font',
+  pairs: {
+    "sm": [14, 16],
+    "base": [16, 18],
+    "lg": [18, 24],
+    "xl": [24, 32],
+    "2xl": [32, 48]
+  }
+});
+
+body {
+  font-size: var(--font-base);
+}
+
+h1 {
+  font-size: var(--font-2xl);
+}
+
+h2 {
+  font-size: var(--font-xl);
+}
+```
+
+### Spacing System
+
+```css
+@ruler scale({
+  prefix: 'space',
+  generateAllCrossPairs: true,
+  pairs: {
+    "2xs": [4, 8],
+    "xs": [8, 12],
+    "sm": [12, 16],
+    "md": [16, 24],
+    "lg": [24, 32],
+    "xl": [32, 48],
+    "2xl": [48, 64]
+  }
+});
+
+.section {
+  padding-block: var(--space-lg);
+  padding-inline: var(--space-md);
+}
+
+.stack > * + * {
+  margin-top: var(--space-sm);
+}
+```
+
+### One-Off Fluid Values
+
+```css
+.hero {
+  font-size: ruler.fluid(32, 72);
+  padding: ruler.fluid(24, 64);
+}
+
+.card {
+  border-radius: ruler.fluid(8, 16);
+  gap: ruler.fluid(12, 24);
+}
+```
+
+## Browser Support
+
+The `clamp()` function is supported in all modern browsers:
+- Chrome 79+
+- Firefox 75+
+- Safari 13.1+
+- Edge 79+
+
+For older browsers, consider using a fallback:
+
+```css
+.element {
+  font-size: 16px; /* Fallback */
+  font-size: ruler.fluid(16, 24);
+}
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT

package/index.js

@@ -0,0 +1,279 @@
+const CSSValueParser = require('postcss-value-parser');
+
+/**
+ * @type {import('postcss').PluginCreator}
+ */
+module.exports = opts => {
+    const DEFAULTS = {
+        minWidth: 320,
+        maxWidth: 1760,
+        generateAllCrossPairs: false,
+    };
+    const config = Object.assign(DEFAULTS, opts);
+
+    /**
+     * Converts pixels to r]em units
+     * @param {number} px - Pixel value to convert
+     * @returns {string} Rem value as string
+     */
+    const pxToRem = px => `${parseFloat((px / 16).toFixed(4))}rem`;
+
+    /**
+     * Validates that min value is less than max value
+     * @param {number} min - Minimum value
+     * @param {number} max - Maximum value
+     * @param {string} context - Context for error message
+     * @throws {Error} If min >= max
+     */
+    const validateMinMax = (min, max, context) => {
+        if (min >= max) {
+            throw new Error(
+                `[postcss-ruler] Invalid ${context}: min (${min}) must be less than max (${max})`
+            );
+        }
+    };
+
+    /**
+     * Calculates a fluid clamp() function
+     * @param {Object} params - Calculation parameters
+     * @param {number} params.minSize - Minimum size in pixels
+     * @param {number} params.maxSize - Maximum size in pixels
+     * @param {number} params.minWidth - Minimum viewport width in pixels
+     * @param {number} params.maxWidth - Maximum viewport width in pixels
+     * @returns {string} CSS clamp() function
+     */
+    const calculateClamp = ({ minSize, maxSize, minWidth, maxWidth }) => {
+        validateMinMax(minSize, maxSize, 'size');
+        validateMinMax(minWidth, maxWidth, 'width');
+
+        const slope = (maxSize - minSize) / (maxWidth - minWidth);
+        const intersect = -minWidth * slope + minSize;
+
+        return `clamp(${pxToRem(minSize)}, ${(slope * 100).toFixed(
+            4
+        )}vw + ${pxToRem(intersect)}, ${pxToRem(maxSize)})`;
+    };
+
+    /**
+     * Generates clamp values from pairs
+     * @param {Object} params - Generation parameters
+     * @param {Array<{name: string, values: [number, number]}>} params.pairs - Size pairs
+     * @param {number} params.minWidth - Minimum viewport width
+     * @param {number} params.maxWidth - Maximum viewport width
+     * @param {boolean} params.generateAllCrossPairs - Whether to generate cross pairs
+     * @returns {Array<{label: string, clamp: string}>} Array of clamp values
+     */
+    const generateClamps = ({
+        pairs,
+        minWidth,
+        maxWidth,
+        generateAllCrossPairs,
+    }) => {
+        let clampScales = pairs.map(({ name, values: [minSize, maxSize] }) => ({
+            label: name,
+            clamp: calculateClamp({
+                minSize,
+                maxSize,
+                minWidth,
+                maxWidth,
+            }),
+        }));
+
+        if (generateAllCrossPairs) {
+            let crossPairs = [];
+            for (let i = 0; i < pairs.length; i++) {
+                for (let j = i + 1; j < pairs.length; j++) {
+                    const [smaller, larger] = [pairs[i], pairs[j]].sort(
+                        (a, b) => a.values[0] - b.values[0]
+                    );
+                    crossPairs.push({
+                        label: `${smaller.name}-${larger.name}`,
+                        clamp: calculateClamp({
+                            minSize: smaller.values[0],
+                            maxSize: larger.values[1],
+                            minWidth,
+                            maxWidth,
+                        }),
+                    });
+                }
+            }
+            clampScales = [...clampScales, ...crossPairs];
+        }
+
+        return clampScales;
+    };
+
+    /**
+     * Parses parameters from @fluid at-rule
+     * @param {Array} params - Parsed parameter nodes
+     * @returns {Object} Parsed configuration object
+     */
+    const parseAtRuleParams = params => {
+        const clampsParams = {
+            minWidth: config.minWidth,
+            maxWidth: config.maxWidth,
+            pairs: {},
+            relativeTo: 'viewport',
+            prefix: 'space',
+            generateAllCrossPairs: config.generateAllCrossPairs,
+        };
+
+        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 'minWidth':
+                case 'maxWidth':
+                    clampsParams[key] = Number(value);
+                    i++;
+                    break;
+                case 'prefix':
+                    clampsParams.prefix = value.replace(/['\"]/g, '');
+                    i++;
+                    break;
+                case 'relativeTo':
+                    clampsParams.relativeTo = value.replace(/['\"]/g, '');
+                    i++;
+                    break;
+                case 'generateAllCrossPairs':
+                    clampsParams.generateAllCrossPairs = value === 'true';
+                    i++;
+                    break;
+            }
+        }
+
+        return clampsParams;
+    };
+
+    /**
+     * Extracts pairs from parsed parameters
+     * @param {Array} params - Parsed parameter nodes
+     * @returns {Object} Pairs object with name: [min, max] entries
+     */
+    const extractPairs = params => {
+        const pairs = {};
+        const pairsStartIndex = params.findIndex(x => x.value === 'pairs');
+
+        if (pairsStartIndex === -1) return pairs;
+
+        let currentName = null;
+        let currentValues = [];
+
+        for (let i = pairsStartIndex + 1; i < params.length; i++) {
+            const param = params[i];
+            const value = param.value.replace('[', '').replace(']', '');
+            if (!value || value === '[' || value === ']') continue;
+
+            if (param.type === 'string') {
+                if (currentName && currentValues.length === 2) {
+                    pairs[currentName] = currentValues;
+                }
+                currentName = value;
+                currentValues = [];
+            } else {
+                const numValue = Number(value);
+                if (!isNaN(numValue)) currentValues.push(numValue);
+            }
+
+            if (currentName && currentValues.length === 2) {
+                pairs[currentName] = currentValues;
+            }
+        }
+
+        return pairs;
+    };
+
+    /**
+     * Processes @fluid at-rule and generates CSS custom properties
+     * @param {Object} atRule - PostCSS at-rule node
+     */
+    const processFluidAtRule = atRule => {
+        const { nodes } = CSSValueParser(atRule.params);
+        const params = nodes[0].nodes.filter(
+            x =>
+                ['word', 'string'].includes(x.type) &&
+                x.value !== '{' &&
+                x.value !== '}'
+        );
+
+        const clampsParams = parseAtRuleParams(params);
+        clampsParams.pairs = extractPairs(params);
+
+        if (Object.keys(clampsParams.pairs).length === 0) {
+            throw new Error(
+                '[postcss-ruler] No pairs defined in @ruler scale()'
+            );
+        }
+
+        const clampPairs = Object.entries(clampsParams.pairs).map(
+            ([name, values]) => ({ name, values })
+        );
+        const clampScale = generateClamps({
+            ...clampsParams,
+            pairs: clampPairs,
+        });
+
+        const response = clampScale
+            .map(step => `--${clampsParams.prefix}-${step.label}: ${step.clamp};`)
+            .join('\n');
+
+        atRule.replaceWith(response);
+    };
+
+    /**
+     * Processes inline fluid functions in declarations
+     * @param {Object} decl - PostCSS declaration node
+     */
+    const processFluidDeclaration = decl => {
+        const regex = /ruler\.fluid\(([^)]+)\)/g;
+        let newValue = decl.value;
+        let match;
+
+        while ((match = regex.exec(decl.value)) !== null) {
+            const args = match[1].split(',').map(s => s.trim()).map(Number);
+            let [minSize, maxSize, minWidth, maxWidth] = args;
+
+            minWidth = minWidth || config.minWidth;
+            maxWidth = maxWidth || config.maxWidth;
+
+            if (!minSize || !maxSize) {
+                throw new Error(
+                    '[postcss-ruler] ruler.fluid() requires minSize and maxSize'
+                );
+            }
+
+            const clampValue = calculateClamp({
+                minSize,
+                maxSize,
+                minWidth,
+                maxWidth,
+            });
+
+            newValue = newValue.replace(match[0], clampValue);
+        }
+
+        if (newValue !== decl.value) {
+            decl.value = newValue;
+        }
+    };
+
+    return {
+        postcssPlugin: 'ruler',
+        AtRule: {
+            ruler: atRule => {
+                if (atRule.params.startsWith('scale(')) {
+                    return processFluidAtRule(atRule);
+                }
+            },
+        },
+        Declaration(decl) {
+            processFluidDeclaration(decl);
+        },
+    };
+};
+
+module.exports.postcss = true;

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "postcss-ruler",
+  "version": "1.0.0",
+  "description": "PostCSS plugin to generate fluid scales and values.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "postcss",
+    "css",
+    "postcss-plugin",
+    "postcss-ruler",
+    "fluid",
+    "clamp",
+    "responsive",
+    "typography"
+  ],
+  "scripts": {
+    "unit": "node --test index.test.js",
+    "test": "npm run unit && eslint ."
+  },
+  "author": "Kurt Stubbings <kurt@homeworkclub.co>",
+  "license": "MIT",
+  "repository": "homeworkclubco/postcss-ruler",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "peerDependencies": {
+    "postcss": "^8.4.27"
+  },
+  "devDependencies": {
+    "eslint": "^8.47.0",
+    "postcss": "^8.4.27"
+  },
+  "eslintConfig": {
+    "parserOptions": {
+      "ecmaVersion": 2017
+    },
+    "env": {
+      "node": true,
+      "es6": true
+    },
+    "extends": [
+      "eslint:recommended"
+    ]
+  },
+  "dependencies": {
+    "postcss-value-parser": "^4.2.0",
+    "prettier": "^3.6.2"
+  }
+}