[SR] Add aria labels to interactive Circle graph

.changeset/cool-bulldogs-dance.md

@@ -0,0 +1,5 @@
+---
+"@khanacademy/perseus": patch
+---
+
+[SR] Add screenreader support for circle graph

packages/perseus/src/strings.ts

@@ -133,6 +133,8 @@ export type PerseusStrings = {
     addPoint: string;
     removePoint: string;
     graphKeyboardPrompt: string;
+    selectAnAnswer: string;
+    // The following strings are used for interactive graph SR descriptions.
     closePolygon: string;
     openPolygon: string;
     srPointAtCoordinates: ({
@@ -146,7 +148,42 @@ export type PerseusStrings = {
     }) => string;
     srInteractiveElements: ({elements}: {elements: string}) => string;
     srNoInteractiveElements: string;
-    selectAnAnswer: string;
+    circleGraphAriaLabel: string;
+    circleShapeAriaLabel: ({
+        centerX,
+        centerY,
+    }: {
+        centerX: number;
+        centerY: number;
+    }) => string;
+    circleRadiusPointAriaLabel: ({
+        radiusPointX,
+        radiusPointY,
+    }: {
+        radiusPointX: number;
+        radiusPointY: number;
+    }) => string;
+    circleRadiusDescription: ({radius}: {radius: number}) => string;
+    circleOuterPointsDescription: ({
+        point1X,
+        point1Y,
+        point2X,
+        point2Y,
+        point3X,
+        point3Y,
+        point4X,
+        point4Y,
+    }: {
+        point1X: number;
+        point1Y: number;
+        point2X: number;
+        point2Y: number;
+        point3X: number;
+        point3Y: number;
+        point4X: number;
+        point4Y: number;
+    }) => string;
+    // The above strings are used for interactive graph SR descriptions.
 };
 
 /**
@@ -326,6 +363,7 @@ export const strings: {
     openPolygon: "Re-open shape",
     srInteractiveElements: "Interactive elements: %(elements)s",
     srNoInteractiveElements: "No interactive elements",
+    selectAnAnswer: "Select an answer",
 
     // TODO(LEMS-2660): The following strings are ones that will need
     // translation tickets after all interactive graph SR strings have
@@ -335,7 +373,33 @@ export const strings: {
         context: "Screenreader-accessible description of a point on a graph",
         message: "Point %(num)s at %(x)s comma %(y)s",
     },
-    selectAnAnswer: "Select an answer",
+    circleGraphAriaLabel: {
+        context: "Aria label for the circle graph as a whole.",
+        message: "A circle on a coordinate plane.",
+    },
+    circleShapeAriaLabel: {
+        context:
+            "Aria label for the interactive circle shape in a circle graph.",
+        message:
+            "Circle. The center point is at %(centerX)s comma %(centerY)s.",
+    },
+    circleRadiusPointAriaLabel: {
+        context:
+            "Aria label for the interactive point that sits on the edge of the circle in a circle graph. Moving this point updates the radius of the circle",
+        message: "Radius point at %(radiusPointX)s comma %(radiusPointY)s.",
+    },
+    circleRadiusDescription: {
+        context:
+            "Screenreader-only description of the radius of a circle in a circle graph.",
+        message: "Circle radius is %(radius)s.",
+    },
+    circleOuterPointsDescription: {
+        context:
+            "Screenreader-only description of key points on a circle in a circle graph.",
+        message:
+            "Points on the circle at %(point1X)s comma %(point1Y)s, %(point2X)s comma %(point2Y)s, %(point3X)s comma %(point3Y)s, %(point4X)s comma %(point4Y)s.",
+    },
+    // The above strings are used for interactive graph SR descriptions.
 };
 
 /**
@@ -495,10 +559,30 @@ export const mockStrings: PerseusStrings = {
     addPoint: "Add Point",
     removePoint: "Remove Point",
     graphKeyboardPrompt: "Press Shift + Enter to interact with the graph",
+    selectAnAnswer: "Select an answer",
+
+    // The following strings are used for interactive graph SR descriptions.
     closePolygon: "Close shape",
     openPolygon: "Re-open shape",
     srPointAtCoordinates: ({num, x, y}) => `Point ${num} at ${x} comma ${y}`,
     srInteractiveElements: ({elements}) => `Interactive elements: ${elements}`,
     srNoInteractiveElements: "No interactive elements",
-    selectAnAnswer: "Select an answer",
+    circleGraphAriaLabel: "A circle on a coordinate plane.",
+    circleShapeAriaLabel: ({centerX, centerY}) =>
+        `Circle. The center point is at ${centerX} comma ${centerY}.`,
+    circleRadiusPointAriaLabel: ({radiusPointX, radiusPointY}) =>
+        `Radius point at ${radiusPointX} comma ${radiusPointY}.`,
+    circleRadiusDescription: ({radius}) => `Circle radius is ${radius}.`,
+    circleOuterPointsDescription: ({
+        point1X,
+        point1Y,
+        point2X,
+        point2Y,
+        point3X,
+        point3Y,
+        point4X,
+        point4Y,
+    }) =>
+        `Points on the circle at ${point1X} comma ${point1Y}, ${point2X} comma ${point2Y}, ${point3X} comma ${point3Y}, ${point4X} comma ${point4Y}.`,
+    // The above strings are used for interactive graph SR descriptions.
 };

packages/perseus/src/widgets/interactive-graphs/graphs/circle.test.tsx

@@ -0,0 +1,71 @@
+import {render, screen} from "@testing-library/react";
+import * as React from "react";
+
+import {Dependencies} from "@khanacademy/perseus";
+
+import {testDependencies} from "../../../../../../testing/test-dependencies";
+import {MafsGraph} from "../mafs-graph";
+import {getBaseMafsGraphPropsForTests} from "../utils";
+
+import type {InteractiveGraphState} from "../types";
+
+const baseMafsGraphProps = getBaseMafsGraphPropsForTests();
+const baseCircleState: InteractiveGraphState = {
+    type: "circle",
+    center: [0, 0],
+    radiusPoint: [1, 0],
+    hasBeenInteractedWith: true,
+    range: [
+        [-10, 10],
+        [-10, 10],
+    ],
+    snapStep: [1, 1],
+};
+
+describe("Circle graph screen reader", () => {
+    beforeEach(() => {
+        jest.spyOn(Dependencies, "getDependencies").mockReturnValue(
+            testDependencies,
+        );
+    });
+
+    test("should have aria label for circle graph", () => {
+        // Arrange
+        render(<MafsGraph {...baseMafsGraphProps} state={baseCircleState} />);
+
+        // Act
+        // eslint-disable-next-line testing-library/no-node-access
+        const circleGraph = document.querySelector(".movable-circle");
+        const radiusPoint = screen.getByTestId(
+            "movable-point__focusable-handle",
+        );
+
+        // Assert
+        // Check aria-label, aria-describedby, and aria-live
+        // for circle and radius point.
+        expect(circleGraph).toHaveAttribute(
+            "aria-label",
+            "Circle. The center point is at 0 comma 0.",
+        );
+        expect(circleGraph).toHaveAttribute(
+            "aria-describedby",
+            // IDs for the radius and outer points hidden description elements
+            ":r1:-radius :r1:-outer-points",
+        );
+        expect(circleGraph).toHaveAttribute("aria-live", "polite");
+
+        expect(radiusPoint).toHaveAttribute(
+            "aria-label",
+            "Radius point at 1 comma 0. Circle radius is 1.",
+        );
+        expect(radiusPoint).toHaveAttribute(
+            "aria-describedby",
+            // ID for the outer points hidden description elements
+            ":r1:-outer-points",
+        );
+        // Radius point's aria-live is off by default so that it doesn't
+        // override the circle's aria-live when the circle is moved (since
+        // the radius point also moves when the circle moves).
+        expect(radiusPoint).toHaveAttribute("aria-live", "off");
+    });
+});

packages/perseus/src/widgets/interactive-graphs/graphs/circle.tsx

@@ -2,6 +2,7 @@ import {vec} from "mafs";
 import * as React from "react";
 import {useRef} from "react";
 
+import {usePerseusI18n} from "../../../components/i18n-context";
 import {snap, X, Y} from "../math";
 import {actions} from "../reducer/interactive-graph-action";
 import {getRadius} from "../reducer/interactive-graph-state";
@@ -37,31 +38,101 @@ function CircleGraph(props: CircleGraphProps) {
     const {dispatch, graphState} = props;
     const {center, radiusPoint} = graphState;
 
+    const {strings} = usePerseusI18n();
+    const [radiusPointAriaLive, setRadiusPointAriaLive] = React.useState<
+        "off" | "polite"
+    >("off");
+
+    const radius = getRadius(graphState);
+    const id = React.useId();
+    const circleId = id + "-circle";
+    const radiusId = id + "-radius";
+    const outerPointsId = id + "-outer-points";
+
+    // Aria label strings
+    const circleGraphAriaLabel = strings.circleGraphAriaLabel;
+    const circleShapeAriaLabel = strings.circleShapeAriaLabel({
+        centerX: center[0],
+        centerY: center[1],
+    });
+    const circleRadiusPointAriaLabel = strings.circleRadiusPointAriaLabel({
+        radiusPointX: radiusPoint[0],
+        radiusPointY: radiusPoint[1],
+    });
+    const circleRadiusDescription = strings.circleRadiusDescription({
+        radius,
+    });
+    const circleOuterPointsDescription = strings.circleOuterPointsDescription({
+        point1X: center[0] + radius,
+        point1Y: center[1],
+        point2X: center[0],
+        point2Y: center[1] + radius,
+        point3X: center[0] - radius,
+        point3Y: center[1],
+        point4X: center[0],
+        point4Y: center[1] - radius,
+    });
+
     return (
-        <>
+        <g
+            // Outer circle minimal description
+            aria-label={circleGraphAriaLabel}
+            aria-describedby={`${circleId} ${radiusId} ${outerPointsId}`}
+        >
             <MovableCircle
+                id={circleId}
+                // Focusable circle aria label reads with every update
+                // because of the aria-live property in the circle <g>.
+                ariaLabel={circleShapeAriaLabel}
+                // Aria-describedby describes additional info on focus.
+                ariaDescribedBy={`${radiusId} ${outerPointsId}`}
                 center={center}
-                radius={getRadius(graphState)}
-                onMove={(c) => dispatch(actions.circle.moveCenter(c))}
+                radius={radius}
+                onMove={(c) => {
+                    setRadiusPointAriaLive("off");
+                    dispatch(actions.circle.moveCenter(c));
+                }}
             />
             <MovablePoint
+                // Radius point aria label reads with every update.
+                ariaLabel={`${circleRadiusPointAriaLabel} ${circleRadiusDescription}`}
+                // Aria-describedby describes additional info on focus.
+                ariaDescribedBy={`${outerPointsId}`}
+                // The radius point's aria-live property is set to "off" when
+                // the circle is moved, so that it doesn't override the circle's
+                // aria-live (since the point is moved along with the circle).
+                // When the radius point is moved, the aria-live is set to
+                // "polite" so that the radius is read out.
+                ariaLive={radiusPointAriaLive}
                 point={radiusPoint}
                 sequenceNumber={1}
                 cursor="ew-resize"
                 onMove={(newRadiusPoint) => {
+                    setRadiusPointAriaLive("polite");
                     dispatch(actions.circle.moveRadiusPoint(newRadiusPoint));
                 }}
             />
-        </>
+            {/* Hidden elements to provide the descriptions for the
+                circle and radius point's `aria-describedby` properties. */}
+            <g id={radiusId} style={{display: "hidden"}}>
+                {circleRadiusDescription}
+            </g>
+            <g id={outerPointsId} style={{display: "hidden"}}>
+                {circleOuterPointsDescription}
+            </g>
+        </g>
     );
 }
 
 function MovableCircle(props: {
+    id?: string;
+    ariaLabel?: string;
+    ariaDescribedBy?: string;
     center: vec.Vector2;
     radius: number;
     onMove: (newCenter: vec.Vector2) => unknown;
 }) {
-    const {center, radius, onMove} = props;
+    const {id, ariaLabel, ariaDescribedBy, center, radius, onMove} = props;
     const {snapStep, disableKeyboardInteraction} = useGraphConfig();
 
     const draggableRef = useRef<SVGGElement>(null);
@@ -78,7 +149,11 @@ function MovableCircle(props: {
 
     return (
         <g
+            aria-label={ariaLabel}
+            aria-describedby={ariaDescribedBy}
+            aria-live="polite"
             ref={draggableRef}
+            role="button"
             tabIndex={disableKeyboardInteraction ? -1 : 0}
             className={`movable-circle ${dragging ? "movable-circle--dragging" : ""}`}
         >
@@ -90,6 +165,7 @@ function MovableCircle(props: {
                 ry={radiiPx[Y] + 3}
             />
             <ellipse
+                id={id}
                 className="circle"
                 cx={centerPx[X]}
                 cy={centerPx[Y]}