@karlhillx/css-rules-sorter 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Karl Hill <karlhillx@gmail.com>
+
+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,129 @@
+# CSS Rules Sorter
+
+✨ A PostCSS plugin to automatically sort CSS selectors and media queries for cleaner, more maintainable stylesheets.
+
+[![npm version](https://badge.fury.io/js/@karlhillx/css-rules-sorter.svg)](https://badge.fury.io/js/@karlhillx/css-rules-sorter)
+[![MIT License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![PostCSS 8+](https://img.shields.io/badge/PostCSS-8%2B-787CB5)](https://github.com/postcss/postcss)
+[![GitHub Actions CI](https://github.com/karlhillx/@karlhillx/css-rules-sorter/actions/workflows/ci.yml/badge.svg)](https://github.com/karlhillx/@karlhillx/css-rules-sorter/actions/workflows/ci.yml)
+[![Jest Tests](https://img.shields.io/badge/Tests-Jest-8854d6)](https://github.com/karlhillx/@karlhillx/css-rules-sorter/tree/main/test)
+
+## Key Features
+
+- **Alphabetical Selector Sorting**: Automatically sorts top-level selectors and rules within media queries for consistent code.
+- **Intelligent Media Query Management**: Flexible ordering (mobile-first or desktop-first) and grouping using `postcss-sort-media-queries`.
+- **Advanced Methodologies**: Built-in support for BEM-aware sorting.
+- **Cascade Layer Support**: Automatically reorders `@layer` blocks to match your defined priority.
+- **Modern PostCSS Support**: Fully compatible with the latest PostCSS 8+ API.
+- **Developer-Focused**: Includes TypeScript definitions, comprehensive tests, and linting.
+
+## Installation
+
+```bash
+npm install @karlhillx/css-rules-sorter postcss --save-dev
+```
+
+## Usage
+
+Add `@karlhillx/css-rules-sorter` to your PostCSS configuration (e.g., `postcss.config.js`):
+
+```javascript
+// postcss.config.js
+module.exports = {
+  plugins: [
+    require('@karlhillx/css-rules-sorter')({
+      sort: 'mobile-first', // or 'desktop-first'
+      selectorSort: 'natural', // or 'bem' or 'specificity'
+      propertyShorthand: 'expand', // or 'collapse'
+    }),
+  ],
+};
+```
+
+## Configuration Options
+
+| Option             | Type      | Default          | Description                                                                    |
+| ------------------ | --------- | ---------------- | ------------------------------------------------------------------------------ |
+| `sort`             | `string`  | `'mobile-first'` | Sets the media query order: `'mobile-first'` or `'desktop-first'`.             |
+| `selectorSort`     | `string`  | `'natural'`      | Defines the method for sorting selectors: `'natural'`, `'specificity'`, or `'bem'`. |
+| `propertySort`     | `string`  | `'none'`         | Sorts properties within each rule: `'none'` or `'alphabetical'`.               |
+| `propertyShorthand`| `string`  | `'none'`         | Manages shorthand properties: `'none'`, `'expand'`, or `'collapse'`.           |
+| `sortLayers`       | `boolean` | `true`           | Sorts CSS cascade layers based on the first `@layer` definition.                 |
+| `groupByMediaType` | `boolean` | `true`           | Groups media queries by their type (e.g., `screen`, `print`).                  |
+
+## Advanced Features
+
+### BEM Selector Sorting
+
+Set `selectorSort: 'bem'` to sort selectors based on the Block, Element, Modifier (BEM) methodology. This ensures your component structures stay logically grouped.
+
+**Before:**
+```css
+.card__header--small { font-size: 0.8em; }
+.card--featured { border: 1px solid blue; }
+.card { color: black; }
+.card__header { font-weight: bold; }
+```
+
+**After:**
+```css
+.card { color: black; }
+.card--featured { border: 1px solid blue; }
+.card__header { font-weight: bold; }
+.card__header--small { font-size: 0.8em; }
+```
+
+### Shorthand Property Management
+
+Use `propertyShorthand` to enforce a specific style for `margin` and `padding`.
+
+- **`'expand'`**: Breaks down shorthands like `margin: 10px 20px;` into four longhand properties. Excellent for preventing accidental overrides.
+- **`'collapse'`**: Combines longhand properties into a single shorthand when all four sides are present.
+
+### Cascade Layer Sorting
+
+Set `sortLayers: true` to automatically reorder your `@layer` blocks to match the priority defined in your first `@layer` rule.
+
+**Before:**
+```css
+@layer components, base, reset;
+
+@layer base { body { color: red; } }
+@layer reset { * { margin: 0; } }
+@layer components { .btn { padding: 1em; } }
+```
+
+**After:**
+```css
+@layer reset { * { margin: 0; } }
+@layer base { body { color: red; } }
+@layer components { .btn { padding: 1em; } }
+```
+
+## Development
+
+```bash
+# Install all dependencies
+npm install
+
+# Run tests
+npm test
+
+# Lint code
+npm run lint
+
+# Format code
+npm run format
+```
+
+## Contributing
+
+1.  Fork the repository.
+2.  Create a new feature branch (`git checkout -b feature/your-feature`).
+3.  Commit your changes (`git commit -m 'Add your feature'`).
+4.  Push to the branch (`git push origin feature/your-feature`).
+5.  Create a Pull Request.
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.

package/index.js

@@ -0,0 +1,286 @@
+const sortMediaQueries = require('postcss-sort-media-queries');
+
+/**
+ * Parses a BEM selector into its parts.
+ * .block__element--modifier
+ */
+function parseBEM(selector) {
+  // Support both .block__element and .block--modifier and .block__element--modifier
+  // and simple .block
+  const match = selector.match(/^\.([a-zA-Z0-9-]+?)(?:__([a-zA-Z0-9-]+?))?(?:--([a-zA-Z0-9-]+?))?$/);
+  if (!match) return { block: selector, element: '', modifier: '', original: selector };
+  return {
+    block: match[1],
+    element: match[2] || '',
+    modifier: match[3] || '',
+    original: selector
+  };
+}
+
+/**
+ * Compare two BEM selectors.
+ */
+function compareBEM(a, b) {
+  const bemA = parseBEM(a);
+  const bemB = parseBEM(b);
+
+  if (bemA.block !== bemB.block) {
+    return bemA.block.localeCompare(bemB.block);
+  }
+
+  // Same block.
+  // Desired order: 
+  // 1. Block itself (.card)
+  // 2. Block modifiers (.card--featured)
+  // 3. Elements (.card__header)
+  // 4. Element modifiers (.card__header--active)
+
+  // Case 1: Both are the base block
+  if (!bemA.element && !bemA.modifier && !bemB.element && !bemB.modifier) return 0;
+
+  // Case 2: One is base block
+  if (!bemA.element && !bemA.modifier) return -1;
+  if (!bemB.element && !bemB.modifier) return 1;
+
+  // Case 3: Both are block modifiers (no element)
+  if (bemA.modifier && !bemA.element && bemB.modifier && !bemB.element) {
+    return bemA.modifier.localeCompare(bemB.modifier);
+  }
+
+  // Case 4: One is block modifier, other is element (or element modifier)
+  if (bemA.modifier && !bemA.element && bemB.element) return -1;
+  if (bemB.modifier && !bemB.element && bemA.element) return 1;
+
+  // Case 5: Both are elements
+  if (bemA.element && bemB.element) {
+    if (bemA.element !== bemB.element) {
+      return bemA.element.localeCompare(bemB.element);
+    }
+    // Same element, check modifiers
+    if (!bemA.modifier && bemB.modifier) return -1;
+    if (bemA.modifier && !bemB.modifier) return 1;
+    return (bemA.modifier || '').localeCompare(bemB.modifier || '');
+  }
+
+  return a.localeCompare(b);
+}
+
+/**
+ * Expand shorthand properties.
+ */
+function expandShorthand(decl) {
+  if (decl.prop === 'border') {
+    const values = decl.value.split(/\s+/);
+    const width = values.find(v => v.match(/^\d|thin|medium|thick/)) || 'medium';
+    const style = values.find(v => v.match(/none|hidden|dotted|dashed|solid|double|groove|ridge|inset|outset/)) || 'none';
+    const color = values.find(v => !v.match(/^\d|thin|medium|thick|none|hidden|dotted|dashed|solid|double|groove|ridge|inset|outset/)) || 'black';
+
+    decl.cloneBefore({ prop: 'border-width', value: width });
+    decl.cloneBefore({ prop: 'border-style', value: style });
+    decl.cloneBefore({ prop: 'border-color', value: color });
+    decl.remove();
+  } else if (decl.prop === 'margin' || decl.prop === 'padding') {
+    const values = decl.value.split(/\s+/);
+    let top, right, bottom, left;
+
+    if (values.length === 1) {
+      top = right = bottom = left = values[0];
+    } else if (values.length === 2) {
+      top = bottom = values[0];
+      right = left = values[1];
+    } else if (values.length === 3) {
+      top = values[0];
+      right = left = values[1];
+      bottom = values[2];
+    } else {
+      top = values[0];
+      right = values[1];
+      bottom = values[2];
+      left = values[3];
+    }
+
+    decl.cloneBefore({ prop: `${decl.prop}-top`, value: top });
+    decl.cloneBefore({ prop: `${decl.prop}-right`, value: right });
+    decl.cloneBefore({ prop: `${decl.prop}-bottom`, value: bottom });
+    decl.cloneBefore({ prop: `${decl.prop}-left`, value: left });
+    decl.remove();
+  }
+}
+
+/**
+ * Collapse longhand properties.
+ */
+function collapseLonghands(rule) {
+  const properties = {};
+  rule.walkDecls(decl => {
+    properties[decl.prop] = decl;
+  });
+
+  // Border collapse
+  if (properties['border-width'] && properties['border-style'] && properties['border-color']) {
+    properties['border-width'].cloneBefore({
+      prop: 'border',
+      value: `${properties['border-width'].value} ${properties['border-style'].value} ${properties['border-color'].value}`
+    });
+    properties['border-width'].remove();
+    properties['border-style'].remove();
+    properties['border-color'].remove();
+  }
+
+  // Margin/Padding collapse
+  ['margin', 'padding'].forEach(type => {
+    const top = properties[`${type}-top`];
+    const right = properties[`${type}-right`];
+    const bottom = properties[`${type}-bottom`];
+    const left = properties[`${type}-left`];
+
+    if (top && right && bottom && left) {
+      let value;
+      if (top.value === right.value && top.value === bottom.value && top.value === left.value) {
+        value = top.value;
+      } else if (top.value === bottom.value && right.value === left.value) {
+        value = `${top.value} ${right.value}`;
+      } else if (right.value === left.value) {
+        value = `${top.value} ${right.value} ${bottom.value}`;
+      } else {
+        value = `${top.value} ${right.value} ${bottom.value} ${left.value}`;
+      }
+
+      top.cloneBefore({ prop: type, value });
+      top.remove();
+      right.remove();
+      bottom.remove();
+      left.remove();
+    }
+  });
+}
+
+const specificity = (selector) => {
+  const selectorWithoutPseudoElements = selector.replace(/::?[a-zA-Z-]+/g, '');
+  const ids = (selectorWithoutPseudoElements.match(/#/g) || []).length;
+  const classesAndAttributes = (selectorWithoutPseudoElements.match(/\.|\[/g) || []).length;
+  const elements = (selectorWithoutPseudoElements.match(/[a-zA-Z-]+\b(?!#|\.)/g) || []).length;
+  return ids * 100 + classesAndAttributes * 10 + elements;
+};
+
+/**
+ * PostCSS plugin to sort CSS rules
+ * @param {Object} opts
+ * @returns {import('postcss').Plugin}
+ */
+const cssRulesSorterPlugin = (opts = {}) => {
+  const defaultOptions = {
+    sort: 'mobile-first',
+    selectorSort: 'natural',
+    propertySort: 'natural',
+    propertyShorthand: 'none',
+    sortLayers: false,
+    groupByMediaType: true,
+  };
+
+  const config = { ...defaultOptions, ...opts };
+
+  return {
+    postcssPlugin: 'css-rules-sorter',
+    Once(root) {
+      // 0. Layer sorting
+      if (config.sortLayers) {
+        const layerOrderAtRule = root.nodes.find(node => node.type === 'atrule' && node.name === 'layer' && node.params.includes(','));
+        if (layerOrderAtRule) {
+          const order = layerOrderAtRule.params.split(',').map(s => s.trim());
+          const layerBlocks = root.nodes.filter(node => node.type === 'atrule' && node.name === 'layer' && !node.params.includes(','));
+
+          const sortedLayers = [...layerBlocks].sort((a, b) => {
+            return order.indexOf(a.params.trim()) - order.indexOf(b.params.trim());
+          });
+
+          // Re-insert in order after the definition
+          let lastNode = layerOrderAtRule;
+          sortedLayers.forEach(layer => {
+            const clone = layer.clone();
+            layer.remove();
+            lastNode.after(clone);
+            lastNode = clone;
+          });
+        }
+      }
+
+      // 1. Property Management
+      root.walkRules(rule => {
+        if (config.propertyShorthand === 'expand') {
+          rule.walkDecls(expandShorthand);
+        } else if (config.propertyShorthand === 'collapse') {
+          collapseLonghands(rule);
+        }
+
+        // Property Sorting
+        if (config.propertySort === 'natural') {
+          const decls = rule.nodes.filter(node => node.type === 'decl');
+          if (decls.length > 1) {
+            const sorted = [...decls].sort((a, b) => a.prop.localeCompare(b.prop));
+            decls.forEach((decl, idx) => {
+              decl.replaceWith(sorted[idx].clone());
+            });
+          }
+        }
+      });
+
+      const sortSelectors = (a, b) => {
+        if (config.selectorSort === 'bem') {
+          return compareBEM(a.selector, b.selector);
+        }
+        if (config.selectorSort === 'specificity') {
+          return specificity(a.selector) - specificity(b.selector);
+        }
+        return a.selector.toLowerCase().localeCompare(b.selector.toLowerCase());
+      };
+
+      // 2. Sort rules within media queries
+      root.walkAtRules('media', (atRule) => {
+        const rules = atRule.nodes.filter((node) => node.type === 'rule');
+        if (rules.length === 0) return;
+
+        const sorted = [...rules].sort(sortSelectors);
+
+        // Replace rules in place
+        rules.forEach((rule, idx) => {
+          rule.replaceWith(sorted[idx].clone());
+        });
+      });
+
+      // 3. Sort top-level rules
+      const topRules = root.nodes.filter((node) => node.type === 'rule');
+
+      if (topRules.length > 0) {
+        const sortedTopRules = [...topRules].sort(sortSelectors);
+
+        topRules.forEach((rule, idx) => {
+          rule.replaceWith(sortedTopRules[idx].clone());
+        });
+      }
+    },
+    async OnceExit(root, { postcss }) {
+      await postcss([sortMediaQueries(config)]).process(root, { from: undefined });
+    },
+  };
+};
+
+cssRulesSorterPlugin.postcss = true;
+
+/**
+ * Main export as a function that can also be used as a standalone processor
+ */
+function main(opts = {}) {
+  const plugin = cssRulesSorterPlugin(opts);
+
+  // Attach process method for standalone usage (backward compatibility)
+  plugin.process = async (css) => {
+    const postcss = require('postcss');
+    const result = await postcss([plugin]).process(css, { from: undefined });
+    return result.css;
+  };
+
+  return plugin;
+}
+
+module.exports = main;

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@karlhillx/css-rules-sorter",
+  "version": "1.1.0",
+  "description": "PostCSS-based CSS rules sorter that alphabetically sorts selectors and media queries",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "files": [
+    "index.js",
+    "README.md",
+    "LICENSE",
+    "test/"
+  ],
+  "scripts": {
+    "test": "jest --coverage",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "prepare": "npm test"
+  },
+  "keywords": [
+    "css",
+    "postcss",
+    "sorter",
+    "css-sorter",
+    "stylesheet"
+  ],
+  "author": "Karl Hill",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/karlhillx/css-rules-sorter.git"
+  },
+  "dependencies": {
+    "postcss": "^8.4.0",
+    "postcss-sort-media-queries": "^4.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jest": "^29.15.0",
+    "globals": "^17.4.0",
+    "jest": "^29.0.0",
+    "prettier": "^3.8.1"
+  }
+}

package/test/css-rules-sorter.test.js

@@ -0,0 +1,122 @@
+const cssRulesSorter = require('../index');
+const postcss = require('postcss');
+
+async function run(input, opts = {}) {
+  const result = await postcss([cssRulesSorter(opts)]).process(input, { from: undefined });
+  return result.css;
+}
+
+describe('css-rules-sorter', () => {
+  test('works with standalone process method', async () => {
+    const input = `.z { color: 0; } .a { color: 1; }`;
+    const sorter = cssRulesSorter();
+    const output = await sorter.process(input);
+    expect(output).toMatch(/\.a[\s\S]*\.z/);
+  });
+
+  describe('Basic Sorting', () => {
+    test('sorts top-level selectors alphabetically', async () => {
+      const input = `
+        .zebra { color: black; }
+        .apple { color: red; }
+        .banana { color: yellow; }
+      `;
+      const output = await run(input);
+      expect(output).toMatch(/\.apple[\s\S]*\.banana[\s\S]*\.zebra/);
+    });
+
+    test('sorts selectors within media queries alphabetically', async () => {
+      const input = `
+        @media (min-width: 768px) {
+          .zebra { color: black; }
+          .apple { color: red; }
+        }
+      `;
+      const output = await run(input);
+      expect(output).toMatch(/@media[\s\S]*\.apple[\s\S]*\.zebra/);
+    });
+
+    test('organizes media queries (mobile-first by default)', async () => {
+      const input = `
+        @media (min-width: 1024px) { .large { color: blue; } }
+        @media (min-width: 768px) { .medium { color: green; } }
+        .top { color: red; }
+      `;
+      const output = await run(input);
+      const mediumIndex = output.indexOf('min-width: 768px');
+      const largeIndex = output.indexOf('min-width: 1024px');
+      expect(mediumIndex).toBeLessThan(largeIndex);
+    });
+  });
+
+  describe('Architectural Features', () => {
+    test('BEM sorting groups modifiers and elements correctly', async () => {
+      const input = `
+        .card__header { color: grey; }
+        .card--featured { color: gold; }
+        .card { color: black; }
+      `;
+      const output = await run(input, { selectorSort: 'bem' });
+      const card = output.indexOf('.card {');
+      const featured = output.indexOf('.card--featured');
+      const header = output.indexOf('.card__header');
+      expect(card).toBeLessThan(featured);
+      expect(featured).toBeLessThan(header);
+    });
+
+    test('Specificity sorting orders low to high', async () => {
+      const input = `
+        #id { color: red; }
+        .class { color: blue; }
+        element { color: green; }
+      `;
+      const output = await run(input, { selectorSort: 'specificity' });
+      const el = output.indexOf('element {');
+      const cl = output.indexOf('.class {');
+      const id = output.indexOf('#id {');
+      expect(el).toBeLessThan(cl);
+      expect(cl).toBeLessThan(id);
+    });
+
+    test('Shorthand expansion (expand)', async () => {
+      const input = `.box { margin: 10px 20px; }`;
+      const output = await run(input, { propertyShorthand: 'expand' });
+      expect(output).toContain('margin-top: 10px');
+      expect(output).toContain('margin-right: 20px');
+      expect(output).toContain('margin-bottom: 10px');
+      expect(output).toContain('margin-left: 20px');
+    });
+
+    test('Shorthand collapsing (collapse)', async () => {
+      const input = `.box { margin-top: 10px; margin-right: 20px; margin-bottom: 10px; margin-left: 20px; }`;
+      const output = await run(input, { propertyShorthand: 'collapse' });
+      expect(output).toContain('margin: 10px 20px');
+    });
+
+    test('Cascade Layer reordering', async () => {
+      const input = `
+        @layer components, reset, base;
+        @layer base { body { margin: 0; } }
+        @layer reset { * { box-sizing: border-box; } }
+        @layer components { .card { padding: 1rem; } }
+      `;
+      const output = await run(input, { sortLayers: true });
+      const comp = output.indexOf('@layer components {');
+      const reset = output.indexOf('@layer reset {');
+      const base = output.indexOf('@layer base {');
+      expect(comp).toBeLessThan(reset);
+      expect(reset).toBeLessThan(base);
+    });
+
+    test('Property sorting alphabetically by default', async () => {
+      const input = `.box { z-index: 10; color: red; background: blue; }`;
+      const output = await run(input);
+      const background = output.indexOf('background: blue');
+      const color = output.indexOf('color: red');
+      const zIndex = output.indexOf('z-index: 10');
+
+      expect(background).toBeLessThan(color);
+      expect(color).toBeLessThan(zIndex);
+    });
+  });
+});