stylelint-plugin-defensive-css 0.3.0 → 0.5.0

package/README.md

@@ -39,6 +39,75 @@ configuration.
 
 The plugin provides multiple rules that can be toggled on and off as needed.
 
+[Accidental Hover](#accidental-hover) -
+[Background-Repeat](#background-repeat) -
+[Custom Property Fallbacks](#custom-property-fallbacks) -
+[Flex Wrapping](#flex-wrapping) - [Scroll Chaining](#scroll-chaining) -
+[Vendor Prefix Grouping](#vendor-prefix-grouping)
+
+### Accidental Hover
+
+> [Read more about this pattern in Defensive CSS](https://defensivecss.dev/tip/hover-media/)
+
+We use hover effects to provide an indication to the user that an element is
+clickable or active. That is fine for devices that have a mouse or a trackpad.
+However, for mobile browsing hover effects can get confusing.
+
+Enable this rule in order to prevent unintentional hover effects on mobile
+devices.
+
+```json
+{
+  "rules": {
+    "plugin/use-defensive-css": [true, { "accidental-hover": true }]
+  }
+}
+```
+
+#### ✅ Passing Examples
+
+```css
+@media (hover: hover) {
+  .btn:hover {
+    color: black;
+  }
+}
+
+/* Will traverse nested media queries */
+@media (hover: hover) {
+  @media (min-width: 1px) {
+    .btn:hover {
+      color: black;
+    }
+  }
+}
+
+/* Will traverse nested media queries */
+@media (min-width: 1px) {
+  @media (hover: hover) {
+    @media (min-width: 100px) {
+      .btn:hover {
+        color: black;
+      }
+    }
+  }
+}
+```
+
+#### ❌ Failing Examples
+
+```css
+.fail-btn:hover {
+  color: black;
+}
+
+@media (min-width: 1px) {
+  .fail-btn:hover {
+    color: black;
+  }
+}
+```
+
 ### Background Repeat
 
 > [Read more about this pattern in Defensive CSS](https://defensivecss.dev/tip/bg-repeat/)
@@ -191,6 +260,64 @@ div {
 }
 ```
 
+### Scroll Chaining
+
+> [Read more about this pattern in Defensive CSS](https://defensivecss.dev/tip/scroll-chain/)
+
+Have you ever opened a modal and started scrolling, and then when you reach the
+end and keep scrolling, the content underneath the modal (the body element) will
+scroll? This is called scroll chaining.
+
+Enable this rule in order to require all scrollable overflow properties to have
+an overscroll-behavior value.
+
+```json
+{
+  "rules": {
+    "plugin/use-defensive-css": [true, { "scroll-chaining": true }]
+  }
+}
+```
+
+#### ✅ Passing Examples
+
+```css
+div {
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+}
+
+div {
+  overflow: hidden scroll;
+  overscroll-behavior: contain;
+}
+
+div {
+  overflow: hidden; /* No overscroll-behavior is needed in the case of hidden */
+}
+
+div {
+  overflow-block: auto;
+  overscroll-behavior: none;
+}
+```
+
+#### ❌ Failing Examples
+
+```css
+div {
+  overflow-x: auto;
+}
+
+div {
+  overflow: hidden scroll;
+}
+
+div {
+  overflow-block: auto;
+}
+```
+
 ### Vendor Prefix Grouping
 
 > [Read more about this pattern in Defensive CSS](https://defensivecss.dev/tip/grouping-selectors/)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stylelint-plugin-defensive-css",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "A Stylelint plugin to enforce defensive CSS best practices.",
   "main": "src/index.js",
   "files": [

package/src/rules/use-defensive-css/base.js

@@ -5,6 +5,9 @@ const stylelint = require('stylelint');
 const ruleName = 'plugin/use-defensive-css';
 
 const ruleMessages = stylelint.utils.ruleMessages(ruleName, {
+  accidentalHover() {
+    return 'To prevent accidental hover states on mobile devices, wrap :hover selectors inside a @media (hover: hover) { ...your styles } query.';
+  },
   backgroundRepeat() {
     return 'Ensure a background-repeat property is defined when using a background image.';
   },
@@ -14,6 +17,9 @@ const ruleMessages = stylelint.utils.ruleMessages(ruleName, {
   flexWrapping() {
     return 'Flex rows must have a `flex-wrap: wrap;` or `flex-wrap: wrap-reverse` declaration.';
   },
+  scrollChaining() {
+    return `Containers with an auto or scroll 'overflow' must also have an 'overscroll-behavior' property defined.`;
+  },
   vendorPrefixWGrouping() {
     return `Separate different vendor prefixes into their own rules.`;
   },

package/src/rules/use-defensive-css/index.js

@@ -20,10 +20,32 @@ const defaultFlexWrappingProps = {
   isMissingFlexWrap: true,
   nodeToReport: undefined,
 };
+const defaultScrollChainingProps = {
+  hasOverflow: false,
+  hasOverscrollBehavior: false,
+  nodeToReport: undefined,
+};
 
 let backgroundRepeatProps = { ...defaultBackgroundRepeatProps };
 let flexWrappingProps = { ...defaultFlexWrappingProps };
+let scrollChainingProps = { ...defaultScrollChainingProps };
 let isLastStyleDeclaration = false;
+let isWrappedInHoverAtRule = false;
+
+function traverseParentRules(parent) {
+  console.log({ parent });
+  if (parent.parent.type === 'root') {
+    return;
+  }
+
+  if (parent.parent.type === 'atrule') {
+    if (parent.parent.params.includes('hover: hover')) {
+      isWrappedInHoverAtRule = true;
+    } else {
+      traverseParentRules(parent.parent);
+    }
+  }
+}
 
 const ruleFunction = (_, options) => {
   return (root, result) => {
@@ -38,6 +60,27 @@ const ruleFunction = (_, options) => {
         JSON.stringify(decl) ===
         JSON.stringify(decl.parent.nodes[decl.parent.nodes.length - 1]);
 
+      /* ACCIDENTAL HOVER */
+      if (options?.['accidental-hover']) {
+        const parent = decl.parent;
+        const selector = parent.selector;
+        const isHoverSelector = selector.includes(':hover');
+        isWrappedInHoverAtRule = false;
+
+        if (isHoverSelector) {
+          traverseParentRules(parent);
+
+          if (!isWrappedInHoverAtRule) {
+            stylelint.utils.report({
+              message: ruleMessages.accidentalHover(),
+              node: decl.parent,
+              result,
+              ruleName,
+            });
+          }
+        }
+      }
+
       /* BACKGROUND REPEAT  */
       if (options?.['background-repeat']) {
         if (decl.prop === 'background' && decl.value.includes('url(')) {
@@ -134,7 +177,45 @@ const ruleFunction = (_, options) => {
         }
       }
 
-      /* GROUPING VENDOR PREFIXES */
+      /* SCROLL CHAINING */
+      if (options?.['scroll-chaining']) {
+        const overflowProperties = [
+          'overflow',
+          'overflow-x',
+          'overflow-y',
+          'overflow-inline',
+          'overflow-block',
+        ];
+        if (
+          overflowProperties.includes(decl.prop) &&
+          (decl.value.includes('auto') || decl.value.includes('scroll'))
+        ) {
+          scrollChainingProps.hasOverflow = true;
+          scrollChainingProps.nodeToReport = decl;
+        }
+
+        if (decl.prop.includes('overscroll-behavior')) {
+          scrollChainingProps.hasOverscrollBehavior = true;
+        }
+
+        if (isLastStyleDeclaration) {
+          if (
+            scrollChainingProps.hasOverflow &&
+            !scrollChainingProps.hasOverscrollBehavior
+          ) {
+            stylelint.utils.report({
+              message: ruleMessages.scrollChaining(),
+              node: scrollChainingProps.nodeToReport,
+              result,
+              ruleName,
+            });
+          }
+
+          scrollChainingProps = { ...defaultScrollChainingProps };
+        }
+      }
+
+      /* VENDOR PREFIX GROUPING */
       if (options?.['vendor-prefix-grouping']) {
         const hasMultiplePrefixes = findVendorPrefixes(decl.parent.selector);