feat(eslint-plugin-template): add rule accessibility-label-has-associ…

…ated-control (#392)

packages/eslint-plugin-template/src/configs/all.json

@@ -4,6 +4,7 @@
     "@angular-eslint/template/accessibility-alt-text": "error",
     "@angular-eslint/template/accessibility-elements-content": "error",
     "@angular-eslint/template/accessibility-label-for": "error",
+    "@angular-eslint/template/accessibility-label-has-associated-control": "error",
     "@angular-eslint/template/accessibility-table-scope": "error",
     "@angular-eslint/template/accessibility-valid-aria": "error",
     "@angular-eslint/template/banana-in-box": "error",

packages/eslint-plugin-template/src/index.ts

@@ -12,6 +12,9 @@ import accessibilityElementsContent, {
 import accessibilityLabelFor, {
   RULE_NAME as accessibilityLabelForRuleName,
 } from './rules/accessibility-label-for';
+import accessibilityLabelHasAssociatedControl, {
+  RULE_NAME as accessibilityLabelHasAssociatedControlRuleName,
+} from './rules/accessibility-label-has-associated-control';
 import accessibilityTableScope, {
   RULE_NAME as accessibilityTableScopeRuleName,
 } from './rules/accessibility-table-scope';
@@ -69,6 +72,7 @@ export default {
     [accessibilityAltTextRuleName]: accessibilityAltText,
     [accessibilityElementsContentRuleName]: accessibilityElementsContent,
     [accessibilityLabelForRuleName]: accessibilityLabelFor,
+    [accessibilityLabelHasAssociatedControlRuleName]: accessibilityLabelHasAssociatedControl,
     [accessibilityTableScopeRuleName]: accessibilityTableScope,
     [accessibilityValidAriaRuleName]: accessibilityValidAria,
     [bananaInBoxRuleName]: bananaInBox,

packages/eslint-plugin-template/src/rules/accessibility-label-for.ts

@@ -34,6 +34,8 @@ const DEFAULT_LABEL_COMPONENTS = ['label'] as const;
 export default createESLintRule<Options, MessageIds>({
   name: RULE_NAME,
   meta: {
+    deprecated: true,
+    replacedBy: ['accessibility-label-has-associated-control'],
     type: 'suggestion',
     docs: {
       description:

packages/eslint-plugin-template/src/rules/accessibility-label-has-associated-control.ts

@@ -0,0 +1,126 @@
+import type { TmplAstElement } from '@angular/compiler';
+import {
+  createESLintRule,
+  getTemplateParserServices,
+} from '../utils/create-eslint-rule';
+import { isChildNodeOf } from '../utils/is-child-node-of';
+
+type LabelComponent = {
+  readonly inputs?: readonly string[];
+  readonly selector: string;
+};
+type Options = [
+  {
+    readonly controlComponents?: readonly string[];
+    readonly labelComponents?: readonly LabelComponent[];
+  },
+];
+export type MessageIds = 'accessibilityLabelHasAssociatedControl';
+export const RULE_NAME = 'accessibility-label-has-associated-control';
+const DEFAULT_CONTROL_COMPONENTS = [
+  'input',
+  'meter',
+  'output',
+  'progress',
+  'select',
+  'textarea',
+];
+const DEFAULT_LABEL_COMPONENTS: readonly LabelComponent[] = [
+  { inputs: ['for', 'htmlFor'], selector: 'label' },
+];
+const DEFAULT_OPTIONS: Options[0] = {
+  controlComponents: DEFAULT_CONTROL_COMPONENTS,
+  labelComponents: DEFAULT_LABEL_COMPONENTS,
+};
+
+export default createESLintRule<Options, MessageIds>({
+  name: RULE_NAME,
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description:
+        'Ensures that a label element/component is associated with a form element',
+      category: 'Best Practices',
+      recommended: false,
+    },
+    schema: [
+      {
+        additionalProperties: false,
+        properties: {
+          controlComponents: {
+            items: { type: 'string' },
+            type: 'array',
+            uniqueItems: true,
+          },
+          labelComponents: {
+            items: { required: ['selector'], type: 'object' },
+            type: 'array',
+            uniqueItems: true,
+          },
+        },
+        type: 'object',
+      },
+    ],
+    messages: {
+      accessibilityLabelHasAssociatedControl:
+        'A label component must be associated with a form element',
+    },
+  },
+  defaultOptions: [DEFAULT_OPTIONS],
+  create(context, [{ controlComponents, labelComponents }]) {
+    const parserServices = getTemplateParserServices(context);
+    const allControlComponents: ReadonlySet<string> = new Set([
+      ...DEFAULT_CONTROL_COMPONENTS,
+      ...(controlComponents ?? []),
+    ]);
+    const allLabelComponents = [
+      ...DEFAULT_LABEL_COMPONENTS,
+      ...(labelComponents ?? []),
+    ] as const;
+    const labelSelectors = allLabelComponents.map(({ selector }) => selector);
+    const labelComponentsPattern = toPattern(labelSelectors);
+
+    return {
+      [`Element[name=${labelComponentsPattern}]`](node: TmplAstElement) {
+        const element = allLabelComponents.find(
+          ({ selector }) => selector === node.name,
+        );
+
+        if (!element) return;
+
+        const attributesInputs: ReadonlySet<string> = new Set(
+          [...node.attributes, ...node.inputs].map(({ name }) => name),
+        );
+        const hasInput = element.inputs?.some((input) =>
+          attributesInputs.has(input),
+        );
+
+        if (hasInput || hasControlComponentIn(allControlComponents, node)) {
+          return;
+        }
+
+        const loc = parserServices.convertNodeSourceSpanToLoc(node.sourceSpan);
+
+        context.report({
+          loc,
+          messageId: 'accessibilityLabelHasAssociatedControl',
+        });
+      },
+    };
+  },
+});
+
+function hasControlComponentIn(
+  controlComponents: ReadonlySet<string>,
+  element: TmplAstElement,
+): boolean {
+  return Boolean(
+    [...controlComponents].some((controlComponent) =>
+      isChildNodeOf(element, controlComponent),
+    ),
+  );
+}
+
+function toPattern(value: readonly unknown[]): RegExp {
+  return RegExp(`^(${value.join('|')})$`);
+}

packages/eslint-plugin-template/tests/rules/accessibility-label-has-associated-control.test.ts

@@ -0,0 +1,99 @@
+import {
+  convertAnnotatedSourceToFailureCase,
+  RuleTester,
+} from '@angular-eslint/utils';
+import type { MessageIds } from '../../src/rules/accessibility-label-has-associated-control';
+import rule, {
+  RULE_NAME,
+} from '../../src/rules/accessibility-label-has-associated-control';
+
+//------------------------------------------------------------------------------
+// Tests
+//------------------------------------------------------------------------------
+
+const ruleTester = new RuleTester({
+  parser: '@angular-eslint/template-parser',
+});
+
+const messageId: MessageIds = 'accessibilityLabelHasAssociatedControl';
+
+ruleTester.run(RULE_NAME, rule, {
+  valid: [
+    `
+    <ng-container *ngFor="let item of items; index as index">
+      <label for="item-{{index}}">Label #{{index}</label>
+      <input id="item-{{index}}" [(ngModel)]="item.name">
+    </ng-container>
+    <label for="id"></label>
+    <label for="{{id}}"></label>
+    <label [attr.for]="id"></label>
+    <label [htmlFor]="id"></label>
+    `,
+    {
+      code: `
+      <app-label id="name"></app-label>
+      <app-label id="{{name}}"></app-label>
+      <app-label [id]="name"></app-label>
+      <label [htmlFor]="id"></label>
+      `,
+      options: [
+        {
+          controlComponents: ['app-input'],
+          labelComponents: [{ inputs: ['id'], selector: 'app-label' }],
+        },
+      ],
+    },
+    {
+      code: `
+      <label><input type="radio"></label>
+      <label><meter></meter></label>
+      <label><output></output></label>
+      <label><progress></progress></label>
+      <label><select><option>1</option></select></label>
+      <label><textarea></textarea></label>
+      <a-label><input></a-label>
+      <label>
+        Label
+        <input>
+      </label>
+      <label>
+        Label
+        <span><input></span>
+      </label>
+      <app-label>
+        <span>
+          <app-input></app-input>
+        </span>
+      </app-label>
+      `,
+      options: [
+        {
+          controlComponents: ['app-input'],
+          labelComponents: [{ inputs: ['id'], selector: 'app-label' }],
+        },
+      ],
+    },
+  ],
+  invalid: [
+    convertAnnotatedSourceToFailureCase({
+      messageId,
+      description: 'should fail if a label does not have a "for" attribute',
+      annotatedSource: `
+        <label>Label</label>
+        ~~~~~~~~~~~~~~~~~~~~
+      `,
+    }),
+    convertAnnotatedSourceToFailureCase({
+      messageId,
+      description:
+        'should fail if a label component does not have a label attribute',
+      annotatedSource: `
+        <app-label anotherAttribute="id"></app-label>
+        ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+      `,
+      options: [
+        { labelComponents: [{ inputs: ['id'], selector: 'app-label' }] },
+      ],
+    }),
+  ],
+});