stylelint-plugin-defensive-css 0.9.2 → 0.10.1

package/README.md

@@ -35,7 +35,8 @@ The plugin provides multiple rules that can be toggled on and off as needed.
 3. [Custom Property Fallbacks](#custom-property-fallbacks)
 4. [Flex Wrapping](#flex-wrapping)
 5. [Scroll Chaining](#scroll-chaining)
-6. [Vendor Prefix Grouping](#vendor-prefix-grouping)
+6. [Scrollbar Gutter](#scrollbar-gutter)
+7. [Vendor Prefix Grouping](#vendor-prefix-grouping)
 
 ---
 
@@ -328,6 +329,66 @@ div {
 }
 ```
 
+### Scrollbar Gutter
+
+> [Read more about this pattern in Defensive CSS](https://defensivecss.dev/tip/scrollbar-gutter/)
+
+Imagine a container with only a small amount of content with no need to scroll.
+The content would be aligned evenly within the boundaries of its container. Now,
+if that container has more content added, and a scrollbar appears, that
+scrollbar will cause a layout shift, forcing the content to reflow and jump.
+This behavior can be jarring.
+
+To avoid layout shifting with variable content, enforce that a
+`scrollbar-gutter` property is defined for any scrollable container.
+
+```json
+{
+  "rules": {
+    "plugin/use-defensive-css": [true, { "scrollbar-gutter": true }]
+  }
+}
+```
+
+#### ✅ Passing Examples
+
+```css
+div {
+  overflow-x: auto;
+  scrollbar-gutter: auto;
+}
+
+div {
+  overflow: hidden scroll;
+  scrollbar-gutter: stable;
+}
+
+div {
+  overflow: hidden; /* No scrollbar-gutter is needed in the case of hidden */
+}
+
+div {
+  overflow-block: auto;
+  scrollbar-gutter: stable both-edges;
+}
+```
+
+#### ❌ 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.9.2",
+  "version": "0.10.1",
   "description": "A Stylelint plugin to enforce defensive CSS best practices.",
   "main": "src/index.js",
   "files": [

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

@@ -17,6 +17,9 @@ const ruleMessages = stylelint.utils.ruleMessages(ruleName, {
   flexWrapping() {
     return 'Flex rows must have a `flex-wrap` value defined.`';
   },
+  scrollbarGutter() {
+    return `Containers with an auto or scroll 'overflow' must also have a 'scrollbar-gutter' property defined.`;
+  },
   scrollChaining() {
     return `Containers with an auto or scroll 'overflow' must also have an 'overscroll-behavior' property defined.`;
   },

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

@@ -20,6 +20,11 @@ const defaultFlexWrappingProps = {
   isMissingFlexWrap: true,
   nodeToReport: undefined,
 };
+const defaultScrollbarGutterProps = {
+  hasOverflow: false,
+  hasScrollbarGutter: false,
+  nodeToReport: undefined,
+};
 const defaultScrollChainingProps = {
   hasOverflow: false,
   hasOverscrollBehavior: false,
@@ -28,10 +33,19 @@ const defaultScrollChainingProps = {
 
 let backgroundRepeatProps = { ...defaultBackgroundRepeatProps };
 let flexWrappingProps = { ...defaultFlexWrappingProps };
+let scrollbarGutterProps = { ...defaultScrollbarGutterProps };
 let scrollChainingProps = { ...defaultScrollChainingProps };
 let isLastStyleDeclaration = false;
 let isWrappedInHoverAtRule = false;
 
+const overflowProperties = [
+  'overflow',
+  'overflow-x',
+  'overflow-y',
+  'overflow-inline',
+  'overflow-block',
+];
+
 function traverseParentRules(parent) {
   if (parent.parent.type === 'root') {
     return;
@@ -184,15 +198,39 @@ const ruleFunction = (_, options) => {
         }
       }
 
+      /* SCROLLBAR GUTTER */
+      if (options?.['scrollbar-gutter']) {
+        if (
+          overflowProperties.includes(decl.prop) &&
+          (decl.value.includes('auto') || decl.value.includes('scroll'))
+        ) {
+          scrollbarGutterProps.hasOverflow = true;
+          scrollbarGutterProps.nodeToReport = decl;
+        }
+
+        if (decl.prop.includes('scrollbar-gutter')) {
+          scrollbarGutterProps.hasScrollbarGutter = true;
+        }
+
+        if (isLastStyleDeclaration) {
+          if (
+            scrollbarGutterProps.hasOverflow &&
+            !scrollbarGutterProps.hasScrollbarGutter
+          ) {
+            stylelint.utils.report({
+              message: ruleMessages.scrollbarGutter(),
+              node: scrollbarGutterProps.nodeToReport,
+              result,
+              ruleName,
+            });
+          }
+
+          scrollbarGutterProps = { ...defaultScrollbarGutterProps };
+        }
+      }
+
       /* 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'))