@gitlab/eslint-plugin 21.4.0 → 21.5.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @gitlab/eslint-plugin
 
+## 21.5.0
+
+### Minor Changes
+
+- 8fa643e: Add `vue-no-popover-target-dollar-el` rule to flag and autofix unnecessary `.$el` in `:target` callbacks on `<gl-popover>` and `<gl-tooltip>`.
+
+## 21.4.1
+
+### Patch Changes
+
+- cd391b5: No changes.
+
 ## 21.4.0
 
 ### Minor Changes

package/docs/rules/vue-no-popover-target-dollar-el.md

@@ -0,0 +1,69 @@
+# @gitlab/vue-no-popover-target-dollar-el
+
+Disallows function-form `:target` bindings on `<gl-popover>` and `<gl-tooltip>` where
+the callback body ends in `.$el`.
+
+`GlPopover` and `GlTooltip` accept a `:target` prop that is either a reference or a
+zero-argument function returning one. The reference can be a plain DOM element
+[or a Vue component instance](https://gitlab.com/gitlab-org/gitlab-services/design.gitlab.com/-/merge_requests/6006).
+The components use `.$el` automatically when it exists, so accessing it
+manually is unnecessary. This helps to avoid reference errors during teardown,
+or other cases where the ref does not exist at the time the `target` function
+is called.
+
+## Rule Details
+
+### Examples of **incorrect** code for this rule
+
+```html
+<!-- Arrow function returning .$el -->
+<gl-popover :target="() => $refs.myButton.$el" />
+
+<!-- Arrow function with explicit this -->
+<gl-tooltip :target="() => this.$refs.myButton.$el" />
+
+<!-- Function expression -->
+<gl-popover :target="function() { return $refs.myButton.$el; }" />
+
+<!-- PascalCase component names -->
+<GlPopover :target="() => $refs.myButton.$el" />
+<GlTooltip :target="() => $refs.myButton.$el" />
+
+<!-- v-bind: long-form syntax -->
+<gl-popover v-bind:target="() => $refs.myButton.$el" />
+
+<!-- Detection is not limited to `$refs`: any callback returning a
+     component instance's `.$el` is flagged -->
+<gl-popover :target="() => this.myButton.$el" />
+```
+
+### Examples of **correct** code for this rule
+
+```html
+<!-- Plain ref (no function) — always fine -->
+<gl-popover :target="$refs.myButton" />
+
+<!-- Arrow function without .$el — already correct -->
+<gl-popover :target="() => $refs.myButton" />
+
+<!-- DOM query — no .$el needed -->
+<gl-popover :target="() => document.querySelector('#my-button')" />
+
+<!-- .:target on an unrelated component — not flagged -->
+<my-component :target="() => $refs.foo.$el" />
+```
+
+## Options
+
+Nothing
+
+## Related rules
+
+- [`vue-no-data-toggle`](./vue-no-data-toggle.md)
+
+## When Not To Use It
+
+If your project is still using a version of `@gitlab/ui` that has **not** yet received the
+companion fix (design.gitlab.com!6006), enabling this rule as `error` may cause runtime
+issues. In that case, land the rule as `warn` or keep it off until the updated `@gitlab/ui`
+version is deployed.

package/docs/rules.md

@@ -16,6 +16,7 @@ Available rules:
 - [vue-no-data-toggle](./rules/vue-no-data-toggle.md): Restrict the use of `data-toggle` bootstrap behaviors within Vue templates
 - [vue-no-hardcoded-urls](./rules/vue-no-hardcoded-urls.md): Disallow hardcoded URLs in Vue templates
 - [vue-no-new-non-primitive-in-template](./rules/vue-no-new-non-primitive-in-template.md): Prevents non-primitive values from being declared in templates
+- [vue-no-popover-target-dollar-el](./rules/vue-no-popover-target-dollar-el.md): Disallow function-form `:target` bindings ending in `.$el` on `<gl-popover>` and `<gl-tooltip>`
 - [vue-no-undef-apollo-properties](./rules/vue-no-undef-apollo-properties.md): Require Apollo query properties to be initialized in component data.
 - [vue-prefer-dollar-scopedslots](./rules/vue-prefer-dollar-scopedslots.md): Prefer $scopedSlots over $slots for Vue 2.x.
 - [vue-require-i18n-attribute-strings](./rules/vue-require-i18n-attribute-strings.md): Detect non externalized strings in vue `<template>` attributes

package/lib/configs/vue.js

@@ -45,6 +45,7 @@ module.exports = {
       },
     ],
     '@gitlab/vue-no-data-toggle': 'error',
+    '@gitlab/vue-no-popover-target-dollar-el': 'warn',
     '@gitlab/vue-prefer-dollar-scopedslots': 'error',
     '@gitlab/vue-slot-name-casing': 'error',
     '@gitlab/no-runtime-template-compiler': 'error',

package/lib/index.js

@@ -15,6 +15,7 @@ module.exports = {
     'vue-no-data-toggle': require('./rules/vue-no-data-toggle.js'),
     'vue-no-hardcoded-urls': require('./rules/vue-no-hardcoded-urls.js'),
     'vue-no-new-non-primitive-in-template': require('./rules/vue-no-new-non-primitive-in-template.js'),
+    'vue-no-popover-target-dollar-el': require('./rules/vue-no-popover-target-dollar-el.js'),
     'vue-no-undef-apollo-properties': require('./rules/vue-no-undef-apollo-properties.js'),
     'vue-prefer-dollar-scopedslots': require('./rules/vue-prefer-dollar-scopedslots.js'),
     'vue-require-i18n-attribute-strings': require('./rules/vue-require-i18n-attribute-strings.js'),

package/lib/rules/vue-no-popover-target-dollar-el.js

@@ -0,0 +1,156 @@
+// ------------------------------------------------------------------------------
+// Requirements
+// ------------------------------------------------------------------------------
+
+const { DOCS_BASE_URL } = require('../constants');
+const { defineTemplateBodyVisitor } = require('../utils/index');
+
+// ------------------------------------------------------------------------------
+//   Constants
+// ------------------------------------------------------------------------------
+
+/**
+ * Component names (both kebab-case and PascalCase) that use a `:target` prop
+ * and where passing a function returning `.$el` is unnecessary.
+ */
+const TARGET_COMPONENT_NAMES = new Set(['gl-popover', 'gl-tooltip', 'GlPopover', 'GlTooltip']);
+
+const MESSAGE_ID = 'noPopoverTargetDollarEl';
+
+// ------------------------------------------------------------------------------
+//   Helpers
+// ------------------------------------------------------------------------------
+
+/**
+ * Returns true if the given VAttribute node is a `:target` or `v-bind:target`
+ * directive binding.
+ *
+ * @param {import('vue-eslint-parser').AST.VAttribute | import('vue-eslint-parser').AST.VDirective} node
+ * @returns {boolean}
+ */
+function isTargetBinding(node) {
+  if (!node.directive) return false;
+  // Must be a v-bind directive
+  if (node.key.name.name !== 'bind') return false;
+  // Argument must be the identifier "target"
+  const arg = node.key.argument;
+  return arg != null && arg.type === 'VIdentifier' && arg.name === 'target';
+}
+
+/**
+ * Returns true if the given VElement node is a gl-popover, gl-tooltip,
+ * GlPopover, or GlTooltip component.
+ *
+ * @param {import('vue-eslint-parser').AST.VElement} element
+ * @returns {boolean}
+ */
+function isTargetComponent(element) {
+  return TARGET_COMPONENT_NAMES.has(element.rawName);
+}
+
+/**
+ * Given an expression node (the value of the `:target` binding), returns the
+ * MemberExpression node for the trailing `.$el` access if one exists, or null.
+ *
+ * Handles:
+ *   - `() => $refs.foo.$el`
+ *   - `() => this.$refs.foo.$el`
+ *   - `() => { return $refs.foo.$el; }`
+ *   - `function() { return $refs.foo.$el; }`
+ *   - `function() { doSomething(); return this.$refs.foo.$el; }`
+ *
+ * @param {import('eslint').Rule.Node} expr
+ * @returns {import('eslint').Rule.Node | null}
+ */
+function getDollarElMemberExpression(expr) {
+  if (expr.type !== 'ArrowFunctionExpression' && expr.type !== 'FunctionExpression') {
+    return null;
+  }
+
+  let body = expr.body;
+
+  // This doesn't need to catch every case, just the most common ways of
+  // writing the target function, which is why this is simple/naive.
+  if (body.type === 'BlockStatement') {
+    const lastStatement = body.body.at(-1);
+    if (!lastStatement || lastStatement.type !== 'ReturnStatement') {
+      return null;
+    }
+    body = lastStatement.argument;
+  }
+
+  if (!body) return null;
+
+  // The body (or return value) must be a MemberExpression ending in `.$el`
+  if (
+    body.type === 'MemberExpression' &&
+    !body.computed &&
+    body.property.type === 'Identifier' &&
+    body.property.name === '$el'
+  ) {
+    return body;
+  }
+
+  return null;
+}
+
+// ------------------------------------------------------------------------------
+// Rule Definition
+// ------------------------------------------------------------------------------
+
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Disallow function-form `:target` bindings ending in `.$el` on `<gl-popover>` and `<gl-tooltip>`',
+      category: undefined,
+      url: DOCS_BASE_URL + '/vue-no-popover-target-dollar-el.md',
+    },
+    fixable: 'code',
+    messages: {
+      [MESSAGE_ID]:
+        'Return the component ref from the `:target` callback on {{component}} instead of its .$el.',
+    },
+    schema: [],
+  },
+
+  create(context) {
+    return defineTemplateBodyVisitor(context, {
+      VElement(element) {
+        // Must be a gl-popover or gl-tooltip component
+        if (!isTargetComponent(element)) return;
+
+        // Find the `:target` / `v-bind:target` binding among its attributes
+        const node = element.startTag.attributes.find(isTargetBinding);
+        if (!node) return;
+
+        // The binding value must be an expression container
+        const exprContainer = node.value;
+        if (!exprContainer || exprContainer.type !== 'VExpressionContainer') return;
+
+        const expr = exprContainer.expression;
+        if (!expr) return;
+
+        // Check whether the expression is a function/arrow whose body ends in `.$el`
+        const dollarElMember = getDollarElMemberExpression(expr);
+        if (!dollarElMember) return;
+
+        // `dollarElMember` is the full `$refs.foo.$el` MemberExpression.
+        // The object part (`$refs.foo`) is what we want to keep.
+        const objectNode = dollarElMember.object;
+
+        context.report({
+          node,
+          loc: node.loc,
+          messageId: MESSAGE_ID,
+          data: { component: element.rawName },
+          fix(fixer) {
+            // Remove the `.$el` suffix: from end of objectNode to end of dollarElMember
+            return fixer.removeRange([objectNode.range[1], dollarElMember.range[1]]);
+          },
+        });
+      },
+    });
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gitlab/eslint-plugin",
-  "version": "21.4.0",
+  "version": "21.5.0",
   "description": "GitLab package for our custom eslint rules",
   "main": "lib/index.js",
   "scripts": {

package/scripts/integration_test/bootstrap.sh

@@ -35,7 +35,7 @@ else
 fi
 
 echo "Installing $CI_REPOSITORY_URL#$SHA"
-yarn add --dev "${CI_REPOSITORY_URL}#${SHA}"
+yarn add --dev --ignore-workspace-root-check "${CI_REPOSITORY_URL}#${SHA}"
 
 echo "Deduplicate dependencies"
 # Yarn doesn't seem to be smart enough when using URL installs and might