stylelint-plugin-use-baseline 0.5.0 → 0.6.1

package/README.md

@@ -1,5 +1,7 @@
 # stylelint-plugin-use-baseline
 
+[![npm version][npm-version-img]][npm] [![npm downloads last month][npm-downloads-img]][npm]
+
 Disallow CSS features not in [Baseline](https://web.dev/baseline).
 
 ![Example output](https://github.com/user-attachments/assets/8c66b5ce-ec20-4641-bec3-41b784244277)
@@ -28,7 +30,7 @@ export default {
     "plugin/use-baseline": [
       true,
       {
-        // "available" can be "widely" (default) or "newly"
+        // "widely" (default), "newly", or YYYY (e.g. 2023)
         available: "widely",
       },
     ],
@@ -51,67 +53,266 @@ This rule reports the following cases:
 
 The data is sourced from [`web-features`](https://npmjs.com/package/web-features).
 
-### Note
-
-Although `cursor` is not yet labeled as Baseline, it has broad support. By default, **this plugin does not flag `cursor`** because it is [expected to be added to Baseline soon](https://github.com/web-platform-dx/web-features/issues/1038).
+**Note:** Although `cursor` is not yet labeled as Baseline, it has broad support. By default, **this plugin does not flag `cursor`** because it is [expected to be added to Baseline soon](https://github.com/web-platform-dx/web-features/issues/1038).
 
 ## Options
 
-### `available`: `"widely" | "newly"` | `YYYY`
-
-_Default_: `"widely"`
+### `true`
 
-- `"widely"` (default) – Allows features supported in all Baseline browsers for at least 30 months.
-- `"newly"` – Allows features supported in all Baseline browsers for less than 30 months. Limited availability features still trigger warnings.
-- `YYYY` – Allows features that became Baseline newly available that year, or earlier. For example, `2023`.
+```json
+{
+  "plugin/use-baseline": true
+}
+```
 
-## Examples
+The following patterns are considered problems:
 
 ```css
-/* invalid - accent-color is not widely available */
+/* accent-color is not widely available */
 a {
   accent-color: red;
 }
+```
+
+```css
+/* abs() is not widely available */
+.box {
+  width: abs(20% - 100px);
+}
+```
+
+```css
+/* :has() is not widely available */
+h1:has(+ h2) {
+  margin: 0;
+}
+```
 
-/* valid - using @supports for accent-color */
+```css
+/* property value doesn't match @supports indicator */
 @supports (accent-color: auto) {
   a {
-    accent-color: auto;
+    accent-color: abs(20% - 10px);
   }
 }
+```
 
-/* invalid - abs() is not widely available */
-.box {
-  width: abs(20% - 100px);
+```css
+/* device-posture is not widely available */
+@media (device-posture: folded) {
+  a {
+    color: red;
+  }
 }
+```
 
-/* invalid - :has() is not widely available */
-h1:has(+ h2) {
-  margin: 0;
+The following patterns are _not_ considered problems:
+
+```css
+/* using @supports for accent-color */
+@supports (accent-color: auto) {
+  a {
+    accent-color: auto;
+  }
 }
+```
 
-/* valid - @supports indicates limited availability */
+```css
+/* @supports indicates limited availability */
 @supports selector(:has()) {
   h1:has(+ h2) {
     margin: 0;
   }
 }
+```
 
-/* invalid - property value doesn't match @supports indicator */
-@supports (accent-color: auto) {
+```css
+/* widely supported properties */
+a {
+  color: red;
+  background-color: blue;
+  transition: none;
+}
+```
+
+## Optional secondary options
+
+### `available`
+
+Specify which level of Baseline availability to enforce.
+
+- `"widely"` (default) – Allows features supported in all Baseline browsers for at least 30 months.
+- `"newly"` – Allows features supported in all Baseline browsers for less than 30 months. Limited availability features still trigger warnings.
+- `YYYY` – Allows features that became Baseline newly available that year, or earlier. For example, `2023`.
+
+#### `"widely"` (default)
+
+Allows features supported in all Baseline browsers for at least 30 months.
+
+Given:
+
+```json
+{
+  "plugin/use-baseline": [true, { "available": "widely" }]
+}
+```
+
+#### `"newly"`
+
+Allows features supported in all Baseline browsers for less than 30 months. Limited availability features still trigger warnings.
+
+Given:
+
+```json
+{
+  "plugin/use-baseline": [true, { "available": "newly" }]
+}
+```
+
+The following patterns are _not_ considered problems:
+
+```css
+h1:has(+ h2) {
+  margin: 0;
+}
+```
+
+#### `YYYY`
+
+Allows features that became Baseline newly available that year, or earlier. For example, `2023`.
+
+Given:
+
+```json
+{
+  "plugin/use-baseline": [true, { "available": 2023 }]
+}
+```
+
+The following patterns are _not_ considered problems:
+
+```css
+div {
+  @starting-style {
+    opacity: 0;
+  }
+}
+```
+
+### `ignoreSelectors`
+
+```json
+{ "ignoreSelectors": ["array", "of", "selectors", "/regex/"] }
+```
+
+Given:
+
+```json
+{
+  "plugin/use-baseline": [true, { "ignoreSelectors": ["nesting", "/^has/"] }]
+}
+```
+
+The following patterns are _not_ considered problems:
+
+```css
+a {
+  img {
+    width: 100%;
+  }
+}
+```
+
+```css
+h1:has(+ h2) {
+  margin: 0;
+}
+```
+
+```css
+h1:has-slotted {
+  color: red;
+}
+```
+
+### `ignoreProperties`
+
+```json
+{ "ignoreProperties": ["array", "of", "properties", "/regex/"] }
+```
+
+Given:
+
+```json
+{
+  "plugin/use-baseline": [
+    true,
+    { "ignoreProperties": ["accent-color", "/^animation-/"] }
+  ]
+}
+```
+
+The following patterns are _not_ considered problems:
+
+```css
+a {
+  accent-color: red;
+}
+```
+
+```css
+div {
+  animation-composition: add;
+}
+```
+
+```css
+div {
+  animation-range: 20%;
+}
+```
+
+### `ignoreAtRules`
+
+```json
+{ "ignoreAtRules": ["array", "of", "at-rules", "/regex/"] }
+```
+
+Given:
+
+```json
+{
+  "plugin/use-baseline": [true, { "ignoreAtRules": ["container", "/^font-/"] }]
+}
+```
+
+The following patterns are _not_ considered problems:
+
+```css
+@container (min-width: 800px) {
   a {
-    accent-color: abs(20% - 10px); /* mismatch */
+    color: red;
   }
 }
+```
 
-/* invalid - device-posture is not widely available */
-@media (device-posture: folded) {
-  .foldable {
-    padding: 1rem;
+```css
+@font-feature-values Font One {
+  @styleset {
+    nice-style: 12;
   }
 }
 ```
 
+```css
+@font-palette-values --foo {
+  font-family: Bixa;
+  override-colors:
+    0 red,
+    1 blue;
+}
+```
+
 ## Prior art
 
 [eslint/css use-baseline](https://github.com/eslint/css/blob/main/docs/rules/use-baseline.md)
@@ -119,3 +320,8 @@ h1:has(+ h2) {
 ## License
 
 [MIT](LICENSE)
+
+
+[npm]: https://www.npmjs.com/package/stylelint-plugin-use-baseline
+[npm-version-img]: https://img.shields.io/npm/v/stylelint-plugin-use-baseline.svg
+[npm-downloads-img]: https://img.shields.io/npm/dm/stylelint-plugin-use-baseline.svg