feat(eslint-plugin-dialtone): DLT-3365 add deprecated-stack-flow-classes rule (#1247)

Author: francisrupert

apps/dialtone-documentation/docs/guides/migration/flex-to-stack/index.md

@@ -213,7 +213,7 @@ The migration tool intelligently handles various edge cases:
 **Skipped (with warnings):**
 
 - `d-fl-col*` - Deprecated flex column system
-- `d-stack*`, `d-flow*` - Auto-spacing utilities (margin-based, incompatible with gap)
+- `d-stack*`, `d-flow*` - Auto-spacing utilities (margin-based, incompatible with gap). Also flagged by the [`deprecated-stack-flow-classes`](https://github.com/dialpad/dialtone/blob/staging/packages/eslint-plugin-dialtone/docs/rules/deprecated-stack-flow-classes.md) ESLint rule, which suggests `<dt-stack>` with the equivalent `gap` prop. The rule's docs include a px → `gap` prop mapping table.
 - `d-d-inline-flex` - Inline flex containers (DtStack is block-level only)
 - Elements with `ref` attributes used for DOM manipulation (see [Ref Attributes](#ref-attributes) below)
 - Dynamic `:class` bindings containing flex utilities (see [Dynamic Class Bindings](#dynamic-class-bindings))

apps/dialtone-documentation/docs/utilities/spacing/auto-spacing.md

@@ -5,7 +5,7 @@ keywords: ["margin","padding","gap","whitespace"]
 ---
 
 > [!CRITICAL] Deprecated
-> `d-stack` and `d-flow` utilities are deprecated. Please use the [Stack](/components/stack) component instead.
+> `d-stack` and `d-flow` utilities are deprecated. Please use the [Stack](/components/stack) component with the equivalent `gap` prop instead. New usages are flagged by the [`deprecated-stack-flow-classes`](https://github.com/dialpad/dialtone/blob/staging/packages/eslint-plugin-dialtone/docs/rules/deprecated-stack-flow-classes.md) ESLint rule, which includes a px to `gap` prop mapping.
 
 ## Adding Space Vertically
 

packages/dialtone-vue/components/combobox_multi_select/combobox_multi_select_default.story.vue

@@ -39,6 +39,7 @@
       <span v-html="$attrs.header" />
     </template>
     <template #list>
+      <!-- eslint-disable-next-line dialtone/deprecated-stack-flow-classes -->
       <ul
         class="d-ps-relative d-stack2 d-m-50 d-px-0"
       >

packages/dialtone-vue/components/dropdown/dropdown_list.vue

@@ -16,7 +16,7 @@
         {{ heading }}
       </dt-text>
     </dt-stack>
-    <!-- eslint-disable-next-line vuejs-accessibility/mouse-events-have-key-events -->
+    <!-- eslint-disable-next-line vuejs-accessibility/mouse-events-have-key-events, dialtone/deprecated-stack-flow-classes -->
     <ul
       :class="['d-ps-relative', 'd-stack2', 'd-px-0', listClass]"
       data-qa="dt-dropdown-list-wrapper"

packages/eslint-plugin-dialtone/docs/rules/deprecated-stack-flow-classes.md

@@ -0,0 +1,100 @@
+# deprecated-stack-flow-classes
+
+Flags `d-stack*` and `d-flow*` sibling-margin utility classes and recommends [`<dt-stack>`](https://dialtone.dialpad.com/components/stack.html) with the equivalent `gap` prop.
+
+## Rule Details
+
+`d-stack*` and `d-flow*` apply spacing between adjacent siblings via a `> * + *` margin selector. They predate `<dt-stack>`, which provides the same vertical/horizontal spacing through native flexbox `gap` and exposes it via a typed prop with responsive support.
+
+### Examples of incorrect code
+
+```vue
+<div class="d-stack16">
+  <p>One</p>
+  <p>Two</p>
+</div>
+
+<div class="d-flow24">
+  <span>One</span>
+  <span>Two</span>
+</div>
+
+<ul class="d-ps-relative d-stack2 d-px-0">
+  <li>...</li>
+</ul>
+
+<ul :class="['d-ps-relative', 'd-stack2', listClass]">
+  <li>...</li>
+</ul>
+
+<div :class="{ 'd-stack16': isCompact }">...</div>
+```
+
+### Examples of correct code
+
+```vue
+<dt-stack gap="200">
+  <p>One</p>
+  <p>Two</p>
+</dt-stack>
+
+<dt-stack direction="row" gap="300">
+  <span>One</span>
+  <span>Two</span>
+</dt-stack>
+
+<dt-stack :gap="{ default: '200', md: '400' }">
+  <p>One</p>
+  <p>Two</p>
+</dt-stack>
+```
+
+## Px to `gap` Prop Mapping
+
+The pixel suffix on the deprecated class maps to a Dialtone spacing token, which is what `<dt-stack>`'s `gap` prop accepts. Use `direction="column"` (the default) to replace `d-stack*`; use `direction="row"` to replace `d-flow*`.
+
+| Deprecated class | DtStack gap prop |
+| --- | --- |
+| `d-stack0` / `d-flow0` | `gap="0"` |
+| `d-stack1` / `d-flow1` | `gap="1"` |
+| `d-stack2` / `d-flow2` | `gap="25"` |
+| `d-stack4` / `d-flow4` | `gap="50"` |
+| `d-stack6` / `d-flow6` | `gap="75"` |
+| `d-stack8` / `d-flow8` | `gap="100"` |
+| `d-stack12` / `d-flow12` | `gap="150"` |
+| `d-stack16` / `d-flow16` | `gap="200"` |
+| `d-stack20` / `d-flow20` | `gap="250"` |
+| `d-stack24` / `d-flow24` | `gap="300"` |
+| `d-stack32` / `d-flow32` | `gap="400"` |
+| `d-stack48` / `d-flow48` | `gap="600"` |
+| `d-stack64` / `d-flow64` | `gap="800"` |
+
+`d-stack72` and larger sizes have no exact `gap` value in DtStack's prop scale — use the closest available `gap` and fall back to a custom CSS rule on the parent if a larger gap is genuinely required.
+
+## Dynamic Bindings
+
+The rule flags `d-stack*` / `d-flow*` string literals inside `:class` bindings (array, object, or single-string forms). These can't be safely auto-rewritten — the surrounding logic typically needs to move to a `:gap` prop binding:
+
+```vue
+<!-- Before -->
+<div :class="{ 'd-stack16': isCompact, 'd-stack8': !isCompact }">
+
+<!-- After -->
+<dt-stack :gap="isCompact ? '200' : '100'">
+```
+
+## When Not To Use
+
+Only `d-stack*` / `d-flow*` are flagged. Other layout utility classes (`d-d-flex`, `d-ai-*`, `d-jc-*`, etc.) are out of scope — see [`prefer-stack-over-flex`](./prefer-stack-over-flex.md) and [`deprecated-stack-alignment-classes`](./deprecated-stack-alignment-classes.md) for those.
+
+If a specific occurrence cannot be migrated yet, disable the rule on that line:
+
+```vue
+<!-- eslint-disable-next-line dialtone/deprecated-stack-flow-classes -- legacy code path -->
+<ul :class="['d-ps-relative', 'd-stack2', listClass]">
+```
+
+## Further Reading
+
+- [DtStack component documentation](https://dialtone.dialpad.com/components/stack.html)
+- [Migrating from Flex CSS Utilities to DtStack](https://dialtone.dialpad.com/guides/migration/flex-to-stack/)

packages/eslint-plugin-dialtone/lib/rules/deprecated-stack-flow-classes.js

@@ -0,0 +1,104 @@
+/**
+ * @fileoverview Detect deprecated `d-stack*` / `d-flow*` sibling-margin classes;
+ * recommend `<dt-stack>` with the equivalent `gap` prop.
+ */
+'use strict';
+
+// Word boundaries handle responsive prefixes (`md:d-stack16`) and adjacent classes.
+// Capture group 1 is the px size; used to map to the equivalent `<dt-stack>` `gap` token.
+const DEPRECATED_AUTO_SPACING_RE = /\bd-(?:stack|flow)(\d+)\b/;
+
+// Same pattern as a quoted string literal anywhere inside a `:class` binding.
+// Scans the whole quoted span so multi-class strings (`'d-ps-relative d-stack2 d-px-0'`)
+// and responsive prefixes (`'md:d-stack16'`) both match.
+const DEPRECATED_IN_BINDING_RE = /['"][^'"]*\bd-(?:stack|flow)\d+\b[^'"]*['"]/;
+
+// Mirrors the table in docs/rules/deprecated-stack-flow-classes.md.
+const PX_TO_GAP = {
+  0: '0',
+  1: '1',
+  2: '25',
+  4: '50',
+  6: '75',
+  8: '100',
+  12: '150',
+  16: '200',
+  20: '250',
+  24: '300',
+  32: '400',
+  48: '600',
+  64: '800',
+};
+
+function describeMatch(text) {
+  const match = DEPRECATED_AUTO_SPACING_RE.exec(text);
+  if (!match) return null;
+  const px = match[1];
+  const gap = PX_TO_GAP[px];
+  return { className: match[0], px, gap };
+}
+
+/** @type {import('eslint').Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'Detect deprecated `d-stack*` / `d-flow*` sibling-margin utilities; prefer `<dt-stack>` with the equivalent `gap` prop',
+      recommended: false,
+      url: 'https://github.com/dialpad/dialtone/blob/staging/packages/eslint-plugin-dialtone/docs/rules/deprecated-stack-flow-classes.md',
+    },
+    fixable: null,
+    schema: [],
+    messages: {
+      preferStack: '`{{className}}` is deprecated. Use `<dt-stack>` with `gap="{{gap}}"` instead.',
+      preferStackUnmapped: '`{{className}}` is deprecated. No exact `gap` equivalent for {{px}}px — use the closest `<dt-stack>` `gap` value (see rule docs).',
+      preferStackInBinding: '`{{className}}` detected in dynamic `:class` binding. Use `<dt-stack>` with `gap="{{gap}}"`. Manual migration required.',
+      preferStackInBindingUnmapped: '`{{className}}` detected in dynamic `:class` binding. No exact `gap` equivalent for {{px}}px — use the closest `<dt-stack>` `gap` value (see rule docs). Manual migration required.',
+    },
+  },
+
+  create(context) {
+    const sourceCode = context.sourceCode ?? context.getSourceCode();
+    const defineTemplateBodyVisitor = sourceCode.parserServices?.defineTemplateBodyVisitor;
+    if (!defineTemplateBodyVisitor) return {};
+
+    return defineTemplateBodyVisitor({
+
+      VElement(node) {
+        const classAttr = node.startTag.attributes.find(
+          attr => attr.key && attr.key.name === 'class' && !attr.directive,
+        );
+
+        if (classAttr && classAttr.value && classAttr.value.value) {
+          const info = describeMatch(classAttr.value.value);
+          if (info) {
+            context.report({
+              node: classAttr,
+              messageId: info.gap ? 'preferStack' : 'preferStackUnmapped',
+              data: info,
+            });
+          }
+        }
+      },
+
+      VAttribute(node) {
+        if (node.directive &&
+            node.key.name.name === 'bind' &&
+            node.key.argument?.name === 'class' &&
+            node.value) {
+          const bindingText = sourceCode.getText(node.value);
+          if (DEPRECATED_IN_BINDING_RE.test(bindingText)) {
+            const info = describeMatch(bindingText);
+            if (info) {
+              context.report({
+                node: node,
+                messageId: info.gap ? 'preferStackInBinding' : 'preferStackInBindingUnmapped',
+                data: info,
+              });
+            }
+          }
+        }
+      },
+    });
+  },
+};

packages/eslint-plugin-dialtone/tests/lib/rules/deprecated-stack-flow-classes.js

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Tests for deprecated-stack-flow-classes rule.
+ */
+'use strict';
+
+const rule = require('../../../lib/rules/deprecated-stack-flow-classes'),
+  RuleTester = require('eslint').RuleTester;
+
+const ruleTester = new RuleTester({
+  languageOptions: {
+    // eslint-disable-next-line n/no-extraneous-require
+    parser: require('vue-eslint-parser'),
+    ecmaVersion: 'latest',
+  },
+});
+
+ruleTester.run('deprecated-stack-flow-classes', rule, {
+  valid: [
+    { code: '<template><div>...</div></template>' },
+    { code: '<template><div class="">...</div></template>' },
+    { code: '<template><div class="d-p-200 d-bgc-primary">...</div></template>' },
+    { code: '<template><dt-stack gap="200">...</dt-stack></template>' },
+    // Word-boundary check: tokens that contain "stack"/"flow" but aren't the deprecated pattern
+    { code: '<template><div class="my-stack-thing flow-chart">...</div></template>' },
+    // Word-boundary check: deprecated stem without the digit suffix is not flagged
+    { code: '<template><div class="d-stack d-flow">...</div></template>' },
+    { code: '<template><div :class="[\'d-p-200\', someClass]">...</div></template>' },
+    { code: '<template><div :class="{ \'d-bgc-primary\': active }">...</div></template>' },
+    // Identifier (not a string literal) referencing a similarly-named variable is not flagged
+    { code: '<template><div :class="dStack16">...</div></template>' },
+  ],
+
+  invalid: [
+    // Carries the data assertion that pins the px → gap mapping in the message.
+    {
+      code: '<template><div class="d-stack16">...</div></template>',
+      errors: [{
+        messageId: 'preferStack',
+        data: { className: 'd-stack16', px: '16', gap: '200' },
+      }],
+    },
+    {
+      code: '<template><div class="d-flow24">...</div></template>',
+      errors: [{ messageId: 'preferStack' }],
+    },
+    // Mirrors a real OOS site: deprecated class alongside other utilities
+    {
+      code: '<template><ul class="d-ps-relative d-stack2 d-m-50 d-px-0">...</ul></template>',
+      errors: [{ messageId: 'preferStack' }],
+    },
+    {
+      code: '<template><div class="md:d-stack16">...</div></template>',
+      errors: [{ messageId: 'preferStack' }],
+    },
+    // Pin: rule does NOT whitelist <dt-stack> — using deprecated classes there is still flagged
+    {
+      code: '<template><dt-stack class="d-stack16">...</dt-stack></template>',
+      errors: [{ messageId: 'preferStack' }],
+    },
+    {
+      code: '<template><ul :class="[\'d-ps-relative\', \'d-stack2\', \'d-px-0\', listClass]">...</ul></template>',
+      errors: [{ messageId: 'preferStackInBinding' }],
+    },
+    {
+      code: '<template><div :class="{ \'d-stack16\': condition }">...</div></template>',
+      errors: [{ messageId: 'preferStackInBinding' }],
+    },
+    // Carries the data assertion for binding messages.
+    {
+      code: '<template><div :class="\'d-flow24\'">...</div></template>',
+      errors: [{
+        messageId: 'preferStackInBinding',
+        data: { className: 'd-flow24', px: '24', gap: '300' },
+      }],
+    },
+    {
+      code: '<template><div v-bind:class="[\'d-stack8\']">...</div></template>',
+      errors: [{ messageId: 'preferStackInBinding' }],
+    },
+    // Responsive-prefixed deprecated class inside a binding string literal
+    {
+      code: '<template><div :class="[\'md:d-stack16\']">...</div></template>',
+      errors: [{ messageId: 'preferStackInBinding' }],
+    },
+    // Multi-class quoted string literal: deprecated token alongside other classes
+    {
+      code: '<template><div :class="\'d-ps-relative d-stack2 d-px-0\'">...</div></template>',
+      errors: [{ messageId: 'preferStackInBinding' }],
+    },
+    // Static and dynamic on the same element each report independently
+    {
+      code: '<template><div class="d-stack16" :class="[\'d-flow24\']">...</div></template>',
+      errors: [
+        { messageId: 'preferStack' },
+        { messageId: 'preferStackInBinding' },
+      ],
+    },
+    // Template literal binding: outer attribute quotes wrap the backtick-delimited
+    // expression, so the binding regex still matches and the rule fires.
+    {
+      code: '<template><div :class="`d-stack16`">...</div></template>',
+      errors: [{ messageId: 'preferStackInBinding' }],
+    },
+    // Sizes outside the gap-token scale (>= 72) fall back to the unmapped message.
+    {
+      code: '<template><div class="d-stack72">...</div></template>',
+      errors: [{ messageId: 'preferStackUnmapped' }],
+    },
+    {
+      code: '<template><div :class="\'d-stack72\'">...</div></template>',
+      errors: [{ messageId: 'preferStackInBindingUnmapped' }],
+    },
+  ],
+});