stylelint-plugin-defensive-css 0.3.0 → 0.4.0

package/README.md

@@ -191,6 +191,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.4.0",
   "description": "A Stylelint plugin to enforce defensive CSS best practices.",
   "main": "src/index.js",
   "files": [

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

@@ -14,6 +14,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,9 +20,15 @@ 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;
 
 const ruleFunction = (_, options) => {
@@ -134,7 +140,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);