From ef819ea959fbab0849724529538f9a9912173aa3 Mon Sep 17 00:00:00 2001
From: Mark Fitzgerald <13896410+mark-fitzgerald@users.noreply.github.com>
Date: Tue, 3 Dec 2024 13:52:05 -0800
Subject: [PATCH] [Numeric Input] - Link tooltip content to input field for
 assistive technologies (#1891)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## Summary:
Currently, the format options tooltip for the input field is only available to sighted users. People using assistive technologies (like braille or screen readers) are unaware of any formatting options for their answers. This change will add an element adjacent to the input field that includes the content of the tooltip, and an association between the two so that assistive technologies can make use of the format options.

Issue: LEMS-2458

## Test plan:
1. Launch Storybook
1. Navigate to Perseus Editor => Editor => [Demo](http://localhost:6006/?path=/story/perseuseditor-editorpage--demo)
1. Add a Numeric Input widget
1. Configure the widget to have any number of format options
![Storybook - 1 Format Option](https://github.com/user-attachments/assets/a46af08c-cc6d-48a6-b20f-4b48c560023d)
1. Using the keyboard, tab to the close icon in the top right of the preview area
![Storybook - Close Icon](https://github.com/user-attachments/assets/a75b4447-4015-460f-8e91-76a71d46de6f)
1. Launch VoiceOver (or your preferred screen reader)
1. Tab to the input field in the preview
1. The screen reader should read the same content as what shows in the tooltip
![VoiceOver - 1 Format Option](https://github.com/user-attachments/assets/fa6bed95-5446-44f7-8cd5-7ec68b860495)
1. Multiple format options should be read with an "or" conjunction in the phrase
![VoiceOver - 3 Format Option](https://github.com/user-attachments/assets/16fc3ef9-bd53-4b65-a355-777919779600)

## Affected behavior:
### Before
![VoiceOver - Before](https://github.com/user-attachments/assets/12ee2a44-ef61-4d80-8120-600d4aa143f4)

### After
![VoiceOver - 1 Format Option](https://github.com/user-attachments/assets/911d1b53-9ea3-4758-bbd5-4a6f04aae901)

Author: mark-fitzgerald

Reviewers: SonicScrewdriver

Required Reviewers:

Approved By: SonicScrewdriver

Checks: ✅ Publish npm snapshot (ubuntu-latest, 20.x), ✅ Lint, Typecheck, Format, and Test (ubuntu-latest, 20.x), ✅ Cypress (ubuntu-latest, 20.x), ✅ Check for .changeset entries for all changed files (ubuntu-latest, 20.x), ✅ Check builds for changes in size (ubuntu-latest, 20.x), ✅ Publish Storybook to Chromatic (ubuntu-latest, 20.x), ✅ gerald

Pull Request URL: https://github.com/Khan/perseus/pull/1891
---
 .changeset/odd-moons-remember.md              |  5 +++
 .../server-item-renderer.test.tsx.snap        | 13 ++++++
 .../src/components/input-with-examples.tsx    | 23 +++++++++-
 .../perseus/src/components/text-input.tsx     |  2 +
 packages/perseus/src/components/tooltip.tsx   |  1 +
 .../multi-renderer.test.tsx.snap              | 13 ++++++
 .../graded-group-set-jipt.test.ts.snap        | 18 ++++++++
 .../graded-group-set.test.ts.snap             |  6 +++
 .../group/__snapshots__/group.test.tsx.snap   | 12 +++++
 .../__snapshots__/numeric-input.test.ts.snap  | 32 +++++++++++++
 .../numeric-input/numeric-input.test.ts       | 45 +++++++++++++++++++
 11 files changed, 168 insertions(+), 2 deletions(-)
 create mode 100644 .changeset/odd-moons-remember.md

diff --git a/.changeset/odd-moons-remember.md b/.changeset/odd-moons-remember.md
new file mode 100644
index 0000000000..3ff9692b33
--- /dev/null
+++ b/.changeset/odd-moons-remember.md
@@ -0,0 +1,5 @@
+---
+"@khanacademy/perseus": patch
+---
+
+[Numeric Input] - Associate format options tooltip content with input field for assistive technologies
diff --git a/packages/perseus/src/__tests__/__snapshots__/server-item-renderer.test.tsx.snap b/packages/perseus/src/__tests__/__snapshots__/server-item-renderer.test.tsx.snap
index 8e79ffdd65..a1c1828e6c 100644
--- a/packages/perseus/src/__tests__/__snapshots__/server-item-renderer.test.tsx.snap
+++ b/packages/perseus/src/__tests__/__snapshots__/server-item-renderer.test.tsx.snap
@@ -41,6 +41,7 @@ exports[`server item renderer should snapshot: initial render 1`] = `
               <span>
                 <div>
                   <input
+                    aria-describedby="aria-for-input-with-examples-aW5wdXQtbnVtYmVyIDE"
                     aria-invalid="false"
                     autocapitalize="off"
                     autocomplete="off"
@@ -50,12 +51,24 @@ exports[`server item renderer should snapshot: initial render 1`] = `
                     type="text"
                     value=""
                   />
+                  <span
+                    id="aria-for-input-with-examples-aW5wdXQtbnVtYmVyIDE"
+                    style="display: none;"
+                  >
+                    Your answer should be 
+                   an integer, like 6, or
+an exact decimal, like 0.75, or
+a simplified proper fraction, like 3/5, or
+a simplified improper fraction, like 7/4, or
+a mixed number, like 1 and 3/4
+                  </span>
                 </div>
                 <div
                   style="position: relative; height: 0px; display: none;"
                 >
                   <div
                     class="tooltipContainer"
+                    role="tooltip"
                     style="position: absolute; left: 0px;"
                   >
                     <div
diff --git a/packages/perseus/src/components/input-with-examples.tsx b/packages/perseus/src/components/input-with-examples.tsx
index 6208a55d83..1b8b70645e 100644
--- a/packages/perseus/src/components/input-with-examples.tsx
+++ b/packages/perseus/src/components/input-with-examples.tsx
@@ -83,9 +83,21 @@ class InputWithExamples extends React.Component<Props, State> {
 
     _renderInput: () => any = () => {
         const id = this._getUniqueId();
+        const ariaId = `aria-for-${id}`;
+        // Generate text from a known set of format options that will read well in a screen reader
+        const examplesAria =
+            this.props.examples.length === 7
+                ? ""
+                : `${this.props.examples[0]}
+                   ${this.props.examples.slice(1).join(", or\n")}`
+                      // @ts-expect-error TS2550: Property replaceAll does not exist on type string.
+                      .replaceAll("*", "")
+                      .replaceAll("$", "")
+                      .replaceAll("\\ \\text{pi}", " pi")
+                      .replaceAll("\\ ", " and ");
         const inputProps = {
             id: id,
-            "aria-describedby": id,
+            "aria-describedby": ariaId,
             ref: "input",
             className: this._getInputClassName(),
             labelText: this.props.labelText,
@@ -101,7 +113,14 @@ class InputWithExamples extends React.Component<Props, State> {
             autoCorrect: "off",
             spellCheck: "false",
         };
-        return <TextInput {...inputProps} />;
+        return (
+            <>
+                <TextInput {...inputProps} />
+                <span id={ariaId} style={{display: "none"}}>
+                    {examplesAria}
+                </span>
+            </>
+        );
     };
 
     _handleFocus: () => void = () => {
diff --git a/packages/perseus/src/components/text-input.tsx b/packages/perseus/src/components/text-input.tsx
index 83ad468395..048d780707 100644
--- a/packages/perseus/src/components/text-input.tsx
+++ b/packages/perseus/src/components/text-input.tsx
@@ -17,6 +17,7 @@ type Props = {
     placeholder?: string;
     onKeyDown?: () => void;
     style?: StyleType;
+    "aria-describedby"?: string;
 };
 
 type DefaultProps = {
@@ -113,6 +114,7 @@ class TextInput extends React.Component<Props> {
                 value={formattedValue}
                 type="text"
                 aria-label={labelText}
+                aria-describedby={this.props["aria-describedby"]}
                 onChange={(value) => this.props.onChange(value)}
                 placeholder={placeholder}
                 onFocus={onFocus}
diff --git a/packages/perseus/src/components/tooltip.tsx b/packages/perseus/src/components/tooltip.tsx
index c795f76491..21756dcf70 100644
--- a/packages/perseus/src/components/tooltip.tsx
+++ b/packages/perseus/src/components/tooltip.tsx
@@ -340,6 +340,7 @@ class Tooltip extends React.Component<Props, State> {
                 <div
                     ref={this.tooltipContainerRef}
                     className="tooltipContainer"
+                    role="tooltip"
                     style={{
                         position: "absolute",
                         // height must start out undefined, not null, so that
diff --git a/packages/perseus/src/multi-items/__tests__/__snapshots__/multi-renderer.test.tsx.snap b/packages/perseus/src/multi-items/__tests__/__snapshots__/multi-renderer.test.tsx.snap
index d2cda3f5fa..286f99fa5e 100644
--- a/packages/perseus/src/multi-items/__tests__/__snapshots__/multi-renderer.test.tsx.snap
+++ b/packages/perseus/src/multi-items/__tests__/__snapshots__/multi-renderer.test.tsx.snap
@@ -975,6 +975,7 @@ exports[`multi-item renderer should snapshot: initial render 1`] = `
               <span>
                 <div>
                   <input
+                    aria-describedby="aria-for-input-with-examples-aW5wdXQtbnVtYmVyIDE"
                     aria-invalid="false"
                     autocapitalize="off"
                     autocomplete="off"
@@ -984,12 +985,24 @@ exports[`multi-item renderer should snapshot: initial render 1`] = `
                     type="text"
                     value=""
                   />
+                  <span
+                    id="aria-for-input-with-examples-aW5wdXQtbnVtYmVyIDE"
+                    style="display: none;"
+                  >
+                    Your answer should be 
+                   an integer, like 6, or
+an exact decimal, like 0.75, or
+a simplified proper fraction, like 3/5, or
+a simplified improper fraction, like 7/4, or
+a mixed number, like 1 and 3/4
+                  </span>
                 </div>
                 <div
                   style="position: relative; height: 0px; display: none;"
                 >
                   <div
                     class="tooltipContainer"
+                    role="tooltip"
                     style="position: absolute; left: 0px;"
                   >
                     <div
diff --git a/packages/perseus/src/widgets/graded-group-set/__snapshots__/graded-group-set-jipt.test.ts.snap b/packages/perseus/src/widgets/graded-group-set/__snapshots__/graded-group-set-jipt.test.ts.snap
index 0b1f5c6cb2..e51a4f4ad5 100644
--- a/packages/perseus/src/widgets/graded-group-set/__snapshots__/graded-group-set-jipt.test.ts.snap
+++ b/packages/perseus/src/widgets/graded-group-set/__snapshots__/graded-group-set-jipt.test.ts.snap
@@ -62,6 +62,7 @@ exports[`graded-group-set should render all graded groups 1`] = `
                       <span>
                         <div>
                           <input
+                            aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
                             aria-invalid="false"
                             aria-label="Your answer:"
                             autocapitalize="off"
@@ -72,12 +73,17 @@ exports[`graded-group-set should render all graded groups 1`] = `
                             type="text"
                             value=""
                           />
+                          <span
+                            id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
+                            style="display: none;"
+                          />
                         </div>
                         <div
                           style="position: relative; height: 0px; display: none;"
                         >
                           <div
                             class="tooltipContainer"
+                            role="tooltip"
                             style="position: absolute; left: 0px;"
                           >
                             <div
@@ -297,6 +303,7 @@ exports[`graded-group-set should render all graded groups 1`] = `
                       <span>
                         <div>
                           <input
+                            aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
                             aria-invalid="false"
                             aria-label="Your answer:"
                             autocapitalize="off"
@@ -307,12 +314,17 @@ exports[`graded-group-set should render all graded groups 1`] = `
                             type="text"
                             value=""
                           />
+                          <span
+                            id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
+                            style="display: none;"
+                          />
                         </div>
                         <div
                           style="position: relative; height: 0px; display: none;"
                         >
                           <div
                             class="tooltipContainer"
+                            role="tooltip"
                             style="position: absolute; left: 0px;"
                           >
                             <div
@@ -532,6 +544,7 @@ exports[`graded-group-set should render all graded groups 1`] = `
                       <span>
                         <div>
                           <input
+                            aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
                             aria-invalid="false"
                             aria-label="Your answer:"
                             autocapitalize="off"
@@ -542,12 +555,17 @@ exports[`graded-group-set should render all graded groups 1`] = `
                             type="text"
                             value=""
                           />
+                          <span
+                            id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
+                            style="display: none;"
+                          />
                         </div>
                         <div
                           style="position: relative; height: 0px; display: none;"
                         >
                           <div
                             class="tooltipContainer"
+                            role="tooltip"
                             style="position: absolute; left: 0px;"
                           >
                             <div
diff --git a/packages/perseus/src/widgets/graded-group-set/__snapshots__/graded-group-set.test.ts.snap b/packages/perseus/src/widgets/graded-group-set/__snapshots__/graded-group-set.test.ts.snap
index 9f7beac312..71dc3fcabb 100644
--- a/packages/perseus/src/widgets/graded-group-set/__snapshots__/graded-group-set.test.ts.snap
+++ b/packages/perseus/src/widgets/graded-group-set/__snapshots__/graded-group-set.test.ts.snap
@@ -128,6 +128,7 @@ exports[`graded group widget should snapshot 1`] = `
                       <span>
                         <div>
                           <input
+                            aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
                             aria-invalid="false"
                             aria-label="Your answer:"
                             autocapitalize="off"
@@ -138,12 +139,17 @@ exports[`graded group widget should snapshot 1`] = `
                             type="text"
                             value=""
                           />
+                          <span
+                            id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
+                            style="display: none;"
+                          />
                         </div>
                         <div
                           style="position: relative; height: 0px; display: none;"
                         >
                           <div
                             class="tooltipContainer"
+                            role="tooltip"
                             style="position: absolute; left: 0px;"
                           >
                             <div
diff --git a/packages/perseus/src/widgets/group/__snapshots__/group.test.tsx.snap b/packages/perseus/src/widgets/group/__snapshots__/group.test.tsx.snap
index cb2a080016..c21cb1f87c 100644
--- a/packages/perseus/src/widgets/group/__snapshots__/group.test.tsx.snap
+++ b/packages/perseus/src/widgets/group/__snapshots__/group.test.tsx.snap
@@ -755,6 +755,7 @@ exports[`group widget should snapshot: initial render 1`] = `
                           <span>
                             <div>
                               <input
+                                aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
                                 aria-invalid="false"
                                 aria-label="value rounded to the nearest ten"
                                 autocapitalize="off"
@@ -765,12 +766,17 @@ exports[`group widget should snapshot: initial render 1`] = `
                                 type="text"
                                 value=""
                               />
+                              <span
+                                id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
+                                style="display: none;"
+                              />
                             </div>
                             <div
                               style="position: relative; height: 0px; display: none;"
                             >
                               <div
                                 class="tooltipContainer"
+                                role="tooltip"
                                 style="position: absolute; left: 0px;"
                               >
                                 <div
@@ -968,6 +974,7 @@ exports[`group widget should snapshot: initial render 1`] = `
                           <span>
                             <div>
                               <input
+                                aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAy"
                                 aria-invalid="false"
                                 aria-label="value rounded to the nearest hundred"
                                 autocapitalize="off"
@@ -978,12 +985,17 @@ exports[`group widget should snapshot: initial render 1`] = `
                                 type="text"
                                 value=""
                               />
+                              <span
+                                id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAy"
+                                style="display: none;"
+                              />
                             </div>
                             <div
                               style="position: relative; height: 0px; display: none;"
                             >
                               <div
                                 class="tooltipContainer"
+                                role="tooltip"
                                 style="position: absolute; left: 0px;"
                               >
                                 <div
diff --git a/packages/perseus/src/widgets/numeric-input/__snapshots__/numeric-input.test.ts.snap b/packages/perseus/src/widgets/numeric-input/__snapshots__/numeric-input.test.ts.snap
index c632f27d1d..7eeae17bd6 100644
--- a/packages/perseus/src/widgets/numeric-input/__snapshots__/numeric-input.test.ts.snap
+++ b/packages/perseus/src/widgets/numeric-input/__snapshots__/numeric-input.test.ts.snap
@@ -93,6 +93,7 @@ exports[`numeric-input widget Should render predictably: after interaction 1`] =
           <span>
             <div>
               <input
+                aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
                 aria-invalid="false"
                 aria-label="Your answer:"
                 autocapitalize="off"
@@ -103,12 +104,17 @@ exports[`numeric-input widget Should render predictably: after interaction 1`] =
                 type="text"
                 value="1252"
               />
+              <span
+                id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
+                style="display: none;"
+              />
             </div>
             <div
               style="position: relative; height: 0px; display: none;"
             >
               <div
                 class="tooltipContainer"
+                role="tooltip"
                 style="position: absolute; left: 0px;"
               >
                 <div
@@ -303,6 +309,7 @@ exports[`numeric-input widget Should render predictably: first render 1`] = `
           <span>
             <div>
               <input
+                aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
                 aria-invalid="false"
                 aria-label="Your answer:"
                 autocapitalize="off"
@@ -313,12 +320,17 @@ exports[`numeric-input widget Should render predictably: first render 1`] = `
                 type="text"
                 value=""
               />
+              <span
+                id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
+                style="display: none;"
+              />
             </div>
             <div
               style="position: relative; height: 0px; display: none;"
             >
               <div
                 class="tooltipContainer"
+                role="tooltip"
                 style="position: absolute; left: 0px;"
               >
                 <div
@@ -513,6 +525,7 @@ exports[`numeric-input widget Should render tooltip as list when multiple format
           <span>
             <div>
               <input
+                aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
                 aria-invalid="false"
                 aria-label="Your answer:"
                 autocapitalize="off"
@@ -523,12 +536,22 @@ exports[`numeric-input widget Should render tooltip as list when multiple format
                 type="text"
                 value=""
               />
+              <span
+                id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
+                style="display: none;"
+              >
+                Your answer should be 
+                   a simplified proper fraction, like 3/5, or
+a simplified improper fraction, like 7/4, or
+a mixed number, like 1 and 3/4
+              </span>
             </div>
             <div
               style="position: relative; height: 0px; display: none;"
             >
               <div
                 class="tooltipContainer"
+                role="tooltip"
                 style="position: absolute; left: 0px;"
               >
                 <div
@@ -665,6 +688,7 @@ exports[`numeric-input widget Should render tooltip when format option is given:
           <span>
             <div>
               <input
+                aria-describedby="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
                 aria-invalid="false"
                 aria-label="Your answer:"
                 autocapitalize="off"
@@ -675,12 +699,20 @@ exports[`numeric-input widget Should render tooltip when format option is given:
                 type="text"
                 value=""
               />
+              <span
+                id="aria-for-input-with-examples-bnVtZXJpYy1pbnB1dCAx"
+                style="display: none;"
+              >
+                Your answer should be 
+                   a simplified proper fraction, like 3/5
+              </span>
             </div>
             <div
               style="position: relative; height: 0px; display: none;"
             >
               <div
                 class="tooltipContainer"
+                role="tooltip"
                 style="position: absolute; left: 0px;"
               >
                 <div
diff --git a/packages/perseus/src/widgets/numeric-input/numeric-input.test.ts b/packages/perseus/src/widgets/numeric-input/numeric-input.test.ts
index 7a36eaa481..f7ce454974 100644
--- a/packages/perseus/src/widgets/numeric-input/numeric-input.test.ts
+++ b/packages/perseus/src/widgets/numeric-input/numeric-input.test.ts
@@ -103,6 +103,51 @@ describe("numeric-input widget", () => {
         // Assert
         expect(container).toMatchSnapshot("render with format list tooltip");
     });
+
+    it("Should render an element with format options as text for use by assistive technologies", async () => {
+        // Arrange - Fractions
+        const questionWithFormatOptions = JSON.parse(JSON.stringify(question1));
+        questionWithFormatOptions.widgets[
+            "numeric-input 1"
+        ].options.answers[0].answerForms = ["proper", "improper", "mixed"];
+
+        // Act
+        const fractionsContainer = renderQuestion(
+            questionWithFormatOptions,
+        ).container;
+        // eslint-disable-next-line testing-library/no-node-access
+        const fractionTextContainer = fractionsContainer.querySelector(
+            "[id*='aria-for-input-with-examples-']",
+        );
+
+        // Assert
+        expect(fractionTextContainer).toHaveTextContent(
+            "a simplified proper fraction",
+        );
+        expect(fractionTextContainer).toHaveTextContent(
+            "a simplified improper fraction",
+        );
+        expect(fractionTextContainer).toHaveTextContent("a mixed number");
+
+        // Arrange - Non-Fractions
+        questionWithFormatOptions.widgets[
+            "numeric-input 1"
+        ].options.answers[0].answerForms = ["integer", "decimal", "pi"];
+
+        // Act
+        const othersContainer = renderQuestion(
+            questionWithFormatOptions,
+        ).container;
+        // eslint-disable-next-line testing-library/no-node-access
+        const othersTextContainer = othersContainer.querySelector(
+            "[id*='aria-for-input-with-examples-']",
+        );
+
+        // Assert
+        expect(othersTextContainer).toHaveTextContent("an integer");
+        expect(othersTextContainer).toHaveTextContent("an exact decimal");
+        expect(othersTextContainer).toHaveTextContent("a multiple of pi");
+    });
 });
 
 describe("static function getOneCorrectAnswerFromRubric", () => {