|
| 1 | +// Copyright (c) Microsoft Corporation. |
| 2 | +// Licensed under the MIT License. |
| 3 | + |
| 4 | +import { TSESLint, TSESTree } from "@typescript-eslint/utils"; |
| 5 | +import { hasNonEmptyProp } from "./hasNonEmptyProp"; |
| 6 | +import { hasAssociatedLabelViaAriaLabelledBy, isInsideLabelTag, hasAssociatedLabelViaHtmlFor } from "./labelUtils"; |
| 7 | +import { hasFieldParent } from "./hasFieldParent"; |
| 8 | +import { elementType } from "jsx-ast-utils"; |
| 9 | +import { JSXOpeningElement } from "estree-jsx"; |
| 10 | + |
| 11 | +export type LabeledControlConfig = { |
| 12 | + component: string | RegExp; |
| 13 | + labelProps: string[]; // e.g. ["label", "aria-label"] |
| 14 | + allowFieldParent?: boolean; // e.g. <Field label=...><RadioGroup/></Field> |
| 15 | + allowFor?: boolean; // htmlFor |
| 16 | + allowLabelledBy?: boolean; // aria-labelledby |
| 17 | + allowWrappingLabel?: boolean; // <label>...</label> |
| 18 | +}; |
| 19 | + |
| 20 | +/** |
| 21 | + * Returns `true` if the JSX opening element is considered **accessibly labelled** |
| 22 | + * per the rule configuration. This function centralizes all supported labelling |
| 23 | + * strategies so the rule stays small and testable. |
| 24 | + * |
| 25 | + * The supported strategies (gated by `config` flags) are: |
| 26 | + * 1) A parent `<Field>`-like wrapper that provides the label context (`allowFieldParent`). |
| 27 | + * 2) A non-empty inline prop such as `aria-label` or `title` (`labelProps`). |
| 28 | + * 3) Being wrapped by a `<label>` element (`allowWrappingLabel`). |
| 29 | + * 4) Associated `<label for="...">` / `htmlFor` relation (`allowFor`). |
| 30 | + * 5) `aria-labelledby` association to an element with textual content (`allowLabelledBy`). |
| 31 | + * |
| 32 | + * Note: This does not validate contrast or UX; it only checks the existence of |
| 33 | + * an accessible **name** via common HTML/ARIA labelling patterns. |
| 34 | + * |
| 35 | + * @param node - The JSX opening element we’re inspecting (e.g., `<Input ...>` opening node). |
| 36 | + * @param context - ESLint rule context or tree-walker context used by helper functions to |
| 37 | + * resolve scope/ancestors and collect referenced nodes. |
| 38 | + * @param config - Rule configuration describing which components/props/associations count as labelled. |
| 39 | + * Expected shape: |
| 40 | + * - `component: string | RegExp` — component tag name or regex to match. |
| 41 | + * - `labelProps: string[]` — prop names that, when non-empty, count as labels (e.g., `["aria-label","title"]`). |
| 42 | + * - `allowFieldParent?: boolean` — if true, a recognized parent “Field” wrapper satisfies labelling. |
| 43 | + * - `allowWrappingLabel?: boolean` — if true, being inside a `<label>` satisfies labelling. |
| 44 | + * - `allowFor?: boolean` — if true, `<label htmlFor>` association is considered. |
| 45 | + * - `allowLabelledBy?: boolean` — if true, `aria-labelledby` association is considered. |
| 46 | + * @returns `true` if any configured labelling strategy succeeds; otherwise `false`. |
| 47 | + */ |
| 48 | +export function hasAccessibleLabel(node: TSESTree.JSXOpeningElement, context: any, config: LabeledControlConfig): boolean { |
| 49 | + if (config.allowFieldParent && hasFieldParent(context)) return true; |
| 50 | + if (config.labelProps.some(p => hasNonEmptyProp(node.attributes, p))) return true; |
| 51 | + if (config.allowWrappingLabel && isInsideLabelTag(context)) return true; |
| 52 | + if (config.allowFor && hasAssociatedLabelViaHtmlFor(node, context)) return true; |
| 53 | + if (config.allowLabelledBy && hasAssociatedLabelViaAriaLabelledBy(node, context)) return true; |
| 54 | + return false; |
| 55 | +} |
| 56 | + |
| 57 | +/** |
| 58 | + * Factory for a minimal, strongly-configurable ESLint rule that enforces |
| 59 | + * accessible labelling on a specific JSX element/component. |
| 60 | + * |
| 61 | + * The rule: |
| 62 | + * • Matches opening elements by `config.component` (exact name or RegExp). |
| 63 | + * • Uses `hasAccessibleLabel` to decide whether the element is labelled. |
| 64 | + * • Reports with `messageId` if no labelling strategy succeeds. |
| 65 | + * |
| 66 | + * Example: |
| 67 | + * ```ts |
| 68 | + * export default makeLabeledControlRule( |
| 69 | + * { |
| 70 | + * component: /^(?:input|textarea|Select|ComboBox)$/i, |
| 71 | + * labelProps: ["aria-label", "aria-labelledby", "title"], |
| 72 | + * allowFieldParent: true, |
| 73 | + * allowWrappingLabel: true, |
| 74 | + * allowFor: true, |
| 75 | + * allowLabelledBy: true, |
| 76 | + * }, |
| 77 | + * "missingLabel", |
| 78 | + * "Provide an accessible label (e.g., via <label>, htmlFor, aria-label, or aria-labelledby)." |
| 79 | + * ); |
| 80 | + * ``` |
| 81 | + * |
| 82 | + * @param config - See `hasAccessibleLabel` for the configuration fields and semantics. |
| 83 | + * @param messageId - The message key used in `meta.messages` (e.g., "missingLabel"). |
| 84 | + * @param description - Human-readable rule description and the text displayed for `messageId`. |
| 85 | + * @returns An ESLint `RuleModule` that reports when the configured component lacks an accessible label. |
| 86 | + */ |
| 87 | +export function makeLabeledControlRule( |
| 88 | + config: LabeledControlConfig, |
| 89 | + messageId: string, |
| 90 | + description: string |
| 91 | +): TSESLint.RuleModule<string, []> { |
| 92 | + return { |
| 93 | + meta: { |
| 94 | + type: "problem" as const, |
| 95 | + messages: { [messageId]: description }, |
| 96 | + docs: { |
| 97 | + description, |
| 98 | + recommended: "strict" as const, // not `true` |
| 99 | + url: "https://www.w3.org/TR/html-aria/" |
| 100 | + }, |
| 101 | + schema: [] |
| 102 | + }, |
| 103 | + defaultOptions: [] as const, |
| 104 | + |
| 105 | + create(context: TSESLint.RuleContext<string, []>) { |
| 106 | + return { |
| 107 | + JSXOpeningElement(node: TSESTree.JSXOpeningElement) { |
| 108 | + // elementType expects an ESTree JSX node — cast is fine |
| 109 | + const name = elementType(node as unknown as JSXOpeningElement); |
| 110 | + const matches = typeof config.component === "string" ? name === config.component : config.component.test(name); |
| 111 | + |
| 112 | + if (!matches) return; |
| 113 | + |
| 114 | + if (!hasAccessibleLabel(node, context, config)) { |
| 115 | + context.report({ node, messageId }); |
| 116 | + } |
| 117 | + } |
| 118 | + }; |
| 119 | + } |
| 120 | + }; |
| 121 | +} |
0 commit comments