@stratawp/stylelint-config 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,35 @@
-# Temporary Holding Version
+# @stratawp/stylelint-config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Strict, performance-minded Stylelint preset for StrataWP themes.
+
+```bash
+pnpm add -D stylelint @stratawp/stylelint-config
+```
+
+```js
+// stylelint.config.js
+export { default } from '@stratawp/stylelint-config'
+```
+
+## Rules
+
+| Rule                       | Default                                        | Why                                                  |
+| -------------------------- | ---------------------------------------------- | ---------------------------------------------------- |
+| `max-nesting-depth`        | 3 levels (pseudo-classes and at-rules ignored) | Deep nesting compiles to long, brittle selectors     |
+| `selector-max-specificity` | `0,3,1`                                        | Low specificity keeps overrides cheap; blocks ids    |
+| `custom-property-pattern`  | kebab-case, WordPress `--` ok                  | Consistent token names, compatible with `theme.json` |
+
+Nested selectors are resolved before `selector-max-specificity` is applied, so a deeply nested rule can trigger both rules.
+
+Files matching `*woocommerce*.{css,scss}` use a higher `selector-max-specificity` cap of `0,5,2`. Overrides of WooCommerce core selectors must match WooCommerce's own specificity to win the cascade, so they cannot stay under the global cap. The exception applies only to those files.
+
+`.scss` files are parsed with `postcss-scss`.
+
+## Overriding
+
+```js
+export default {
+  extends: ['@stratawp/stylelint-config'],
+  rules: { 'max-nesting-depth': [4] },
+}
+```

package/index.js

@@ -0,0 +1,48 @@
+import postcssScss from 'postcss-scss'
+
+/**
+ * Default thresholds. Override a rule in your own config to change one:
+ *   { extends: ['@stratawp/stylelint-config'], rules: { 'max-nesting-depth': [4] } }
+ */
+export const thresholds = {
+  // Deep nesting compiles to long, brittle selectors.
+  maxNestingDepth: 3,
+  // 0 ids, 3 classes, 1 type. Low specificity keeps overrides cheap and
+  // cascade layers predictable.
+  maxSpecificity: '0,3,1',
+}
+
+// Overrides of WooCommerce core selectors (e.g. `.woocommerce table.cart
+// .actions .coupon input[type="text"]`) must match WooCommerce's own
+// specificity to win, so WooCommerce override files get a higher cap.
+// Measured maximum across the shipped store theme stylesheets.
+const woocommerceMaxSpecificity = '0,5,2'
+
+export default {
+  rules: {
+    'max-nesting-depth': [
+      thresholds.maxNestingDepth,
+      {
+        ignore: ['blockless-at-rules', 'pseudo-classes'],
+        ignoreAtRules: ['media', 'supports', 'container', 'include'],
+      },
+    ],
+    'selector-max-specificity': thresholds.maxSpecificity,
+    // kebab-case, with the double-dash segments WordPress generates
+    // (--wp--preset--color--primary).
+    'custom-property-pattern': [
+      '^[a-z][a-z0-9]*(?:-{1,2}[a-z0-9]+)*$',
+      { message: 'Custom properties must be kebab-case (WordPress "--" segments allowed)' },
+    ],
+  },
+  overrides: [
+    {
+      files: ['**/*.scss'],
+      customSyntax: postcssScss,
+    },
+    {
+      files: ['**/*woocommerce*.{css,scss}'],
+      rules: { 'selector-max-specificity': woocommerceMaxSpecificity },
+    },
+  ],
+}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@stratawp/stylelint-config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Strict, performance-minded Stylelint preset for StrataWP themes",
+  "author": "Jon Imms",
+  "license": "GPL-3.0-or-later",
+  "type": "module",
+  "keywords": [
+    "stylelint",
+    "stylelint-config",
+    "wordpress",
+    "scss",
+    "stratawp"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JonImmsWordpressDev/StrataWP.git",
+    "directory": "packages/stylelint-config"
+  },
+  "main": "./index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "postcss-scss": "^4.0.9"
+  },
+  "peerDependencies": {
+    "stylelint": "^16.0.0"
+  },
+  "devDependencies": {
+    "stylelint": "^16.0.0",
+    "vitest": "^1.0.4"
+  }
+}