From 21dfb40a217d6b7681643234c66fcf5c40f82bca Mon Sep 17 00:00:00 2001
From: Thomasan1999 <ahoj@tomaskudlac.sk>
Date: Sun, 15 Sep 2024 11:45:17 +0200
Subject: [PATCH] feat: add prefer-use-template-ref rule

---
 docs/rules/index.md                        |   1 +
 docs/rules/prefer-use-template-ref.md      |  54 +++++
 lib/index.js                               |   1 +
 lib/rules/prefer-use-template-ref.js       |  90 ++++++++
 tests/lib/rules/prefer-use-template-ref.js | 232 +++++++++++++++++++++
 5 files changed, 378 insertions(+)
 create mode 100644 docs/rules/prefer-use-template-ref.md
 create mode 100644 lib/rules/prefer-use-template-ref.js
 create mode 100644 tests/lib/rules/prefer-use-template-ref.js

diff --git a/docs/rules/index.md b/docs/rules/index.md
index 1ba5978d2..615729c51 100644
--- a/docs/rules/index.md
+++ b/docs/rules/index.md
@@ -270,6 +270,7 @@ For example:
 | [vue/prefer-prop-type-boolean-first](./prefer-prop-type-boolean-first.md) | enforce `Boolean` comes first in component prop types | :bulb: | :warning: |
 | [vue/prefer-separate-static-class](./prefer-separate-static-class.md) | require static class names in template to be in a separate `class` attribute | :wrench: | :hammer: |
 | [vue/prefer-true-attribute-shorthand](./prefer-true-attribute-shorthand.md) | require shorthand form attribute when `v-bind` value is `true` | :bulb: | :hammer: |
+| [vue/prefer-use-template-ref](./prefer-use-template-ref.md) | require using `useTemplateRef` over `ref` for template refs | :wrench: | :hammer: |
 | [vue/require-default-export](./require-default-export.md) | require components to be the default export |  | :warning: |
 | [vue/require-direct-export](./require-direct-export.md) | require the component to be directly exported |  | :hammer: |
 | [vue/require-emit-validator](./require-emit-validator.md) | require type definitions in emits | :bulb: | :hammer: |
diff --git a/docs/rules/prefer-use-template-ref.md b/docs/rules/prefer-use-template-ref.md
new file mode 100644
index 000000000..5bf139de4
--- /dev/null
+++ b/docs/rules/prefer-use-template-ref.md
@@ -0,0 +1,54 @@
+---
+pageClass: rule-details
+sidebarDepth: 0
+title: vue/prefer-use-template-ref
+description: require using `useTemplateRef` over `ref` for template refs
+---
+
+# vue/prefer-use-template-ref
+
+> require using `useTemplateRef` over `ref` for template refs
+
+- :exclamation: <badge text="This rule has not been released yet." vertical="middle" type="error"> _**This rule has not been released yet.**_ </badge>
+- :wrench: The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) can automatically fix some of the problems reported by this rule.
+
+## :book: Rule Details
+
+Vue 3.5 introduced a new way of obtaining template refs via
+the [useTemplateRef()](https://vuejs.org/guide/essentials/template-refs.html#accessing-the-refs) API.
+
+This rule enforces using the new `useTemplateRef` function over `ref` for template refs.
+
+<eslint-code-block fix :rules="{'vue/prefer-use-template-ref': ['error']}">
+
+```vue
+
+<template>
+  <div ref="divRef"></div>
+  <button ref="submitter">Submit</button>
+</template>
+
+<script>
+  import { ref, useTemplateRef } from 'vue';
+
+  /* ✓ GOOD */
+  const divRef = useTemplateRef('divRef');
+  const div = useTemplateRef('divRef');
+  const loremIpsum = useTemplateRef('divRef');
+  const submitButton = useTemplateRef('submitter');
+  /* ✗ BAD */
+  const divRef = ref();
+  const submitter = ref();
+</script>
+```
+
+</eslint-code-block>
+
+## :wrench: Options
+
+Nothing.
+
+## :mag: Implementation
+
+- [Rule source](https://github.com/vuejs/eslint-plugin-vue/blob/master/lib/rules/prefer-use-template-ref.js)
+- [Test source](https://github.com/vuejs/eslint-plugin-vue/blob/master/tests/lib/rules/prefer-use-template-ref.js)
diff --git a/lib/index.js b/lib/index.js
index bb4abf40f..b09e247d5 100644
--- a/lib/index.js
+++ b/lib/index.js
@@ -208,6 +208,7 @@ const plugin = {
     'prefer-separate-static-class': require('./rules/prefer-separate-static-class'),
     'prefer-template': require('./rules/prefer-template'),
     'prefer-true-attribute-shorthand': require('./rules/prefer-true-attribute-shorthand'),
+    'prefer-use-template-ref': require('./rules/prefer-use-template-ref'),
     'prop-name-casing': require('./rules/prop-name-casing'),
     'quote-props': require('./rules/quote-props'),
     'require-component-is': require('./rules/require-component-is'),
diff --git a/lib/rules/prefer-use-template-ref.js b/lib/rules/prefer-use-template-ref.js
new file mode 100644
index 000000000..7b5999a87
--- /dev/null
+++ b/lib/rules/prefer-use-template-ref.js
@@ -0,0 +1,90 @@
+/**
+ * @author Thomasan1999
+ * See LICENSE file in root directory for full license.
+ */
+'use strict'
+
+const utils = require('../utils')
+
+/** @type {import("eslint").Rule.RuleModule} */
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'require using `useTemplateRef` over `ref` for template refs',
+      categories: undefined,
+      url: 'https://eslint.vuejs.org/rules/prefer-use-template-ref.html'
+    },
+    fixable: 'code',
+    schema: [],
+    messages: {
+      preferUseTemplateRef: "Replace 'ref' with 'useTemplateRef'."
+    }
+  },
+  /** @param {RuleContext} context */
+  create(context) {
+    /** @type Set<string> */
+    const templateRefs = new Set()
+
+    /**
+     * @typedef ScriptRef
+     * @type {{node: Expression, ref: string}}
+     */
+
+    /**
+     * @type ScriptRef[] */
+    const scriptRefs = []
+
+    return utils.compositingVisitors(
+      utils.defineTemplateBodyVisitor(
+        context,
+        {
+          'VAttribute[directive=false]'(node) {
+            if (node.key.name === 'ref' && node.value?.value) {
+              templateRefs.add(node.value.value)
+            }
+          }
+        },
+        {
+          VariableDeclarator(declarator) {
+            // @ts-ignore
+            if (declarator.init?.callee?.name !== 'ref') {
+              return
+            }
+
+            scriptRefs.push({
+              node: declarator.init,
+              // @ts-ignore
+              ref: declarator.id.name
+            })
+          }
+        }
+      ),
+      {
+        'Program:exit'() {
+          for (const templateRef of templateRefs) {
+            const scriptRef = scriptRefs.find(
+              (scriptRef) => scriptRef.ref === templateRef
+            )
+
+            if (!scriptRef) {
+              continue
+            }
+
+            context.report({
+              node: scriptRef.node,
+              messageId: 'preferUseTemplateRef',
+              fix(fixer) {
+                return fixer.replaceText(
+                  scriptRef.node,
+                  `useTemplateRef('${scriptRef.ref}')`
+                )
+              }
+            })
+          }
+        }
+      }
+    )
+  }
+}
diff --git a/tests/lib/rules/prefer-use-template-ref.js b/tests/lib/rules/prefer-use-template-ref.js
new file mode 100644
index 000000000..db60ae627
--- /dev/null
+++ b/tests/lib/rules/prefer-use-template-ref.js
@@ -0,0 +1,232 @@
+/**
+ * @author Thomasan1999
+ * See LICENSE file in root directory for full license.
+ */
+'use strict'
+
+const RuleTester = require('../../eslint-compat').RuleTester
+const rule = require('../../../lib/rules/prefer-use-template-ref')
+
+const tester = new RuleTester({
+  languageOptions: {
+    parser: require('vue-eslint-parser'),
+    ecmaVersion: 2020,
+    sourceType: 'module'
+  }
+})
+
+tester.run('prefer-use-template-ref', rule, {
+  valid: [
+    {
+      filename: 'single-use-template-ref.vue',
+      code: `
+      <template>
+          <div ref="root" />
+      </template>
+
+      <script>
+        import { useTemplateRef } from 'vue';
+
+        const root = useTemplateRef('root');
+      </script>
+      `
+    },
+    {
+      filename: 'multiple-use-template-refs.vue',
+      code: `
+      <template>
+          <button ref="button">Content</button>
+          <a href="" ref="link">Link</a>
+      </template>
+
+      <script>
+        import { useTemplateRef } from 'vue';
+
+        const buttonRef = useTemplateRef('button');
+        const link = useTemplateRef('link');
+      </script>
+      `
+    },
+    {
+      filename: 'use-template-ref-in-block.vue',
+      code: `
+      <template>
+          <div>
+            <ul>
+              <li ref="firstListItem">Morning</li>
+              <li>Afternoon</li>
+              <li>Evening</li>
+            </ul>
+          </div>
+      </template>
+
+      <script>
+        import { useTemplateRef } from 'vue';
+
+        function getFirstListItemElement() {
+          const firstListItem = useTemplateRef('firstListItem');
+        }
+      </script>
+      `
+    }
+  ],
+  invalid: [
+    {
+      filename: 'single-ref.vue',
+      code: `
+      <template>
+          <div ref="root"/>
+      </template>
+
+      <script>
+        import { ref } from 'vue';
+
+        const root = ref();
+      </script>
+      `,
+      output: `
+      <template>
+          <div ref="root"/>
+      </template>
+
+      <script>
+        import { ref } from 'vue';
+
+        const root = useTemplateRef('root');
+      </script>
+      `,
+      errors: [
+        {
+          messageId: 'preferUseTemplateRef',
+          line: 9,
+          column: 22
+        }
+      ]
+    },
+    {
+      filename: 'one-ref-unused-in-script.vue',
+      code: `
+      <template>
+          <button ref="button">Content</button>
+          <a href="" ref="link">Link</a>
+      </template>
+
+      <script>
+        import { ref } from 'vue';
+
+        const buttonRef = ref();
+        const link = ref();
+      </script>
+      `,
+      output: `
+      <template>
+          <button ref="button">Content</button>
+          <a href="" ref="link">Link</a>
+      </template>
+
+      <script>
+        import { ref } from 'vue';
+
+        const buttonRef = ref();
+        const link = useTemplateRef('link');
+      </script>
+      `,
+      errors: [
+        {
+          messageId: 'preferUseTemplateRef',
+          line: 11,
+          column: 22
+        }
+      ]
+    },
+    {
+      filename: 'multiple-refs.vue',
+      code: `
+      <template>
+          <h1 ref="heading">Heading</h1>
+          <a href="" ref="link">Link</a>
+      </template>
+
+      <script>
+        import { ref } from 'vue';
+
+        const heading = ref();
+        const link = ref();
+      </script>
+      `,
+      output: `
+      <template>
+          <h1 ref="heading">Heading</h1>
+          <a href="" ref="link">Link</a>
+      </template>
+
+      <script>
+        import { ref } from 'vue';
+
+        const heading = useTemplateRef('heading');
+        const link = useTemplateRef('link');
+      </script>
+      `,
+      errors: [
+        {
+          messageId: 'preferUseTemplateRef',
+          line: 10,
+          column: 25
+        },
+        {
+          messageId: 'preferUseTemplateRef',
+          line: 11,
+          column: 22
+        }
+      ]
+    },
+    {
+      filename: 'ref-in-block.vue',
+      code: `
+      <template>
+          <div>
+            <ul>
+              <li ref="firstListItem">Morning</li>
+              <li>Afternoon</li>
+              <li>Evening</li>
+            </ul>
+          </div>
+      </template>
+
+      <script>
+        import { ref } from 'vue';
+
+        function getFirstListItemElement() {
+          const firstListItem = ref();
+        }
+      </script>
+      `,
+      output: `
+      <template>
+          <div>
+            <ul>
+              <li ref="firstListItem">Morning</li>
+              <li>Afternoon</li>
+              <li>Evening</li>
+            </ul>
+          </div>
+      </template>
+
+      <script>
+        import { ref } from 'vue';
+
+        function getFirstListItemElement() {
+          const firstListItem = useTemplateRef('firstListItem');
+        }
+      </script>
+      `,
+      errors: [
+        {
+          messageId: 'preferUseTemplateRef',
+          line: 16,
+          column: 33
+        }
+      ]
+    }
+  ]
+})