Rename diagnostic WithAccessibleName to WithName and property `ac…

…cessibleName` to `name` (#1537)

* Rename `accessibleName` to `name`

* Extract API

* Add changeset

.changeset/few-ravens-shave.md

@@ -0,0 +1,7 @@
+---
+"@siteimprove/alfa-rules": minor
+---
+
+**Breaking:** Diagnostic `WithAccessibleName` has been renamed to `WithName` and the property `accessibleName` to `name`.
+
+This is to conform to existing diagnostics that refer to accessible name as name and clients that are expecting this convention.

docs/review/api/alfa-rules.api.md

@@ -83,7 +83,7 @@ export namespace Diagnostic {
     import TextSpacing = diagnostic.TextSpacing;
     import WithBadElements = diagnostic.WithBadElements;
     import WithRole = diagnostic.WithRole;
-    import WithAccessibleName = diagnostic.WithAccessibleName;
+    import WithName = diagnostic.WithName;
     import WithOtherHeading = diagnostic.WithOtherHeading;
 }
 

packages/alfa-rules/src/common/act/diagnostic.ts

@@ -36,6 +36,6 @@ export namespace Diagnostic {
   export import TextSpacing = diagnostic.TextSpacing;
   export import WithBadElements = diagnostic.WithBadElements;
   export import WithRole = diagnostic.WithRole;
-  export import WithAccessibleName = diagnostic.WithAccessibleName;
+  export import WithName = diagnostic.WithName;
   export import WithOtherHeading = diagnostic.WithOtherHeading;
 }

packages/alfa-rules/src/common/diagnostic.ts

@@ -5,5 +5,5 @@ export * from "./diagnostic/contrast";
 export * from "./diagnostic/text-spacing";
 export * from "./diagnostic/with-bad-elements";
 export * from "./diagnostic/with-role";
-export * from "./diagnostic/with-accessible-name";
+export * from "./diagnostic/with-name";
 export * from "./diagnostic/with-other-heading";

packages/alfa-rules/src/common/diagnostic/with-name.ts

@@ -0,0 +1,62 @@
+import { Diagnostic } from "@siteimprove/alfa-act";
+import { Device } from "@siteimprove/alfa-device";
+import { Node } from "@siteimprove/alfa-aria";
+import { Element } from "@siteimprove/alfa-dom";
+import { Option } from "@siteimprove/alfa-option";
+
+/**
+ * @public
+ */
+export class WithName extends Diagnostic {
+  public static of(message: string): Diagnostic;
+
+  public static of(message: string, name: string): Diagnostic;
+
+  public static of(message: string, name?: string): Diagnostic {
+    return name === undefined
+      ? new Diagnostic(message)
+      : new WithName(message, name);
+  }
+
+  private readonly _name: string;
+
+  protected constructor(message: string, name: string) {
+    super(message);
+    this._name = name;
+  }
+
+  public get name(): string {
+    return this._name;
+  }
+
+  public toJSON(): WithName.JSON {
+    return {
+      ...super.toJSON(),
+      name: this._name,
+    };
+  }
+}
+
+/**
+ * @public
+ */
+export namespace WithName {
+  export interface JSON extends Diagnostic.JSON {
+    name: string;
+  }
+
+  export function isWithName(value: Diagnostic): value is WithName;
+
+  export function isWithName(value: unknown): value is WithName;
+
+  /**
+   * @public
+   */
+  export function isWithName(value: unknown): value is WithName {
+    return value instanceof WithName;
+  }
+
+  export function getName(element: Element, device: Device): Option<string> {
+    return Node.from(element, device).name.map((x) => x.value);
+  }
+}

packages/alfa-rules/src/sia-r15/rule.ts

@@ -16,7 +16,7 @@ import { Question } from "../common/act/question";
 import { referenceSameResource } from "../common/predicate";
 import { Scope, Stability } from "../tags";
 
-import { WithAccessibleName } from "../common/diagnostic";
+import { WithName } from "../common/diagnostic";
 import { normalize } from "../common/normalize";
 
 const { hasNonEmptyAccessibleName, isIncludedInTheAccessibilityTree } = DOM;
@@ -58,7 +58,7 @@ export default Rule.Atomic.of<Page, Group<Element>, Question.Metadata>({
             referenceSameResource(response.url)(element, elements[i - 1]),
         );
 
-        const name = WithAccessibleName.getAccessibleName(
+        const name = WithName.getName(
           Iterable.first(target).getUnsafe(), // Existence of first element is guaranteed by applicability
           device,
         ).getUnsafe(); // Existence of accessible name is guaranteed by applicability
@@ -73,7 +73,7 @@ export default Rule.Atomic.of<Page, Group<Element>, Question.Metadata>({
                 target,
                 "Do the <iframe> elements embed equivalent resources?",
                 {
-                  diagnostic: WithAccessibleName.of(
+                  diagnostic: WithName.of(
                     "Do the <iframe> elements embed equivalent resources?",
                     name,
                   ),
@@ -96,27 +96,21 @@ export default Rule.Atomic.of<Page, Group<Element>, Question.Metadata>({
  * @public
  */
 export namespace Outcomes {
-  export const EmbedSameResources = (accessibleName: string) =>
+  export const EmbedSameResources = (name: string) =>
     Ok.of(
-      WithAccessibleName.of(
-        `The \`<iframe>\` elements embed the same resource`,
-        accessibleName,
-      ),
+      WithName.of(`The \`<iframe>\` elements embed the same resource`, name),
     );
 
-  export const EmbedEquivalentResources = (accessibleName: string) =>
+  export const EmbedEquivalentResources = (name: string) =>
     Ok.of(
-      WithAccessibleName.of(
-        `The \`<iframe>\` elements embed equivalent resources`,
-        accessibleName,
-      ),
+      WithName.of(`The \`<iframe>\` elements embed equivalent resources`, name),
     );
 
-  export const EmbedDifferentResources = (accessibleName: string) =>
+  export const EmbedDifferentResources = (name: string) =>
     Err.of(
-      WithAccessibleName.of(
+      WithName.of(
         `The \`<iframe>\` elements do not embed the same or equivalent resources`,
-        accessibleName,
+        name,
       ),
     );
 }

packages/alfa-rules/src/sia-r39/rule.ts

@@ -9,7 +9,7 @@ import { Page } from "@siteimprove/alfa-web";
 import { expectation } from "../common/act/expectation";
 import { Question } from "../common/act/question";
 
-import { WithAccessibleName } from "../common/diagnostic";
+import { WithName } from "../common/diagnostic";
 import { Scope, Stability } from "../tags";
 
 const { hasAccessibleName, isIncludedInTheAccessibilityTree } = DOM;
@@ -52,18 +52,15 @@ export default Rule.Atomic.of<Page, Element, Question.Metadata>({
       },
 
       expectations(target) {
-        const accName = WithAccessibleName.getAccessibleName(
-          target,
-          device,
-        ).getUnsafe(); // Existence of accessible name is guaranteed by applicability
+        const accName = WithName.getName(target, device).getUnsafe(); // Existence of accessible name is guaranteed by applicability
 
         return {
           1: Question.of(
             "name-describes-purpose",
             target,
             `Does the accessible name of the \`<${target.name}>\` element describe its purpose?`,
             {
-              diagnostic: WithAccessibleName.of(
+              diagnostic: WithName.of(
                 `Does the accessible name of the \`<${target.name}>\` element describe its purpose?`,
                 accName,
               ),
@@ -96,19 +93,19 @@ function getFilename(path: string): string {
  * @public
  */
 export namespace Outcomes {
-  export const NameIsDescriptive = (name: string, accessibleName: string) =>
+  export const NameIsDescriptive = (name: string, accName: string) =>
     Ok.of(
-      WithAccessibleName.of(
+      WithName.of(
         `The accessible name of the \`<${name}>\` element describes its purpose`,
-        accessibleName,
+        accName,
       ),
     );
 
-  export const NameIsNotDescriptive = (name: string, accessibleName: string) =>
+  export const NameIsNotDescriptive = (name: string, accName: string) =>
     Err.of(
-      WithAccessibleName.of(
+      WithName.of(
         `The accessible name of the \`<${name}>\` element does not describe its purpose`,
-        accessibleName,
+        accName,
       ),
     );
 }

packages/alfa-rules/src/sia-r41/rule.ts

@@ -17,7 +17,7 @@ import { referenceSameResource } from "../common/predicate";
 
 import { normalize } from "../common/normalize";
 
-import { WithAccessibleName } from "../common/diagnostic";
+import { WithName } from "../common/diagnostic";
 import { Scope, Stability } from "../tags";
 
 const { hasNonEmptyAccessibleName, hasRole, isIncludedInTheAccessibilityTree } =
@@ -53,7 +53,7 @@ export default Rule.Atomic.of<Page, Group<Element>, Question.Metadata>({
       },
 
       expectations(target) {
-        const name = WithAccessibleName.getAccessibleName(
+        const name = WithName.getName(
           Iterable.first(target).getUnsafe(), // Existence of first element is guaranteed by applicability
           device,
         ).getUnsafe(); // Existence of accessible name is guaranteed by applicability
@@ -78,7 +78,7 @@ export default Rule.Atomic.of<Page, Group<Element>, Question.Metadata>({
                 target,
                 `Do the links resolve to equivalent resources?`,
                 {
-                  diagnostic: WithAccessibleName.of(
+                  diagnostic: WithName.of(
                     `Do the links resolve to equivalent resources?`,
                     name,
                   ),
@@ -101,27 +101,17 @@ export default Rule.Atomic.of<Page, Group<Element>, Question.Metadata>({
  * @public
  */
 export namespace Outcomes {
-  export const ResolveSameResource = (accessibleName: string) =>
-    Ok.of(
-      WithAccessibleName.of(
-        `The links resolve to the same resource`,
-        accessibleName,
-      ),
-    );
+  export const ResolveSameResource = (name: string) =>
+    Ok.of(WithName.of(`The links resolve to the same resource`, name));
 
-  export const ResolveEquivalentResource = (accessibleName: string) =>
-    Ok.of(
-      WithAccessibleName.of(
-        `The links resolve to equivalent resources`,
-        accessibleName,
-      ),
-    );
+  export const ResolveEquivalentResource = (name: string) =>
+    Ok.of(WithName.of(`The links resolve to equivalent resources`, name));
 
-  export const ResolveDifferentResource = (accessibleName: string) =>
+  export const ResolveDifferentResource = (name: string) =>
     Err.of(
-      WithAccessibleName.of(
+      WithName.of(
         `The links do not resolve to the same or equivalent resources`,
-        accessibleName,
+        name,
       ),
     );
 }