Support visible/aria label for the Expression widget (#1404)

* add inputs for labels to the expression editor

* add aria label to mobile input

* fix tests

* changeset

* rough out idea for CSS

* flow elements better

* add comment to hack

* change name of prop and tweak tests

* remove findDOMNode from render

* consolidate mobile vs desktop logic

* add more tests

* make labels serializable

* ignore errors in story

* try again with vertical-align

* use WB labels

* move styles to aphrodite

* add comments

* i18n aria label default

* add WCAG link to tooltip thing

.changeset/stupid-coats-dance.md

@@ -0,0 +1,7 @@
+---
+"@khanacademy/math-input": minor
+"@khanacademy/perseus": minor
+"@khanacademy/perseus-editor": minor
+---
+
+Add label options for Expression

packages/math-input/src/components/__tests__/integration.test.tsx

@@ -48,6 +48,7 @@ function InputWithContext({keypadConfiguration}) {
                         onBlur={() => {
                             keypadElement?.dismiss();
                         }}
+                        ariaLabel="Math input"
                     />
                 );
             }}

packages/math-input/src/components/input/__tests__/context-tracking.test.ts

@@ -11,7 +11,7 @@ describe("Cursor context", () => {
         span = document.createElement("span");
         document.body.appendChild(span);
 
-        mathField = new TestMathWrapper(span, mockStrings, "en");
+        mathField = new TestMathWrapper(span, "Math field", mockStrings, "en");
     });
 
     afterEach(() => {

packages/math-input/src/components/input/__tests__/mathquill.test.ts

@@ -21,7 +21,7 @@ describe("MathQuill", () => {
         span = document.createElement("span");
         document.body.appendChild(span);
 
-        mathField = new TestMathWrapper(span, mockStrings, "en");
+        mathField = new TestMathWrapper(span, "Math field", mockStrings, "en");
     });
 
     afterEach(() => {

packages/math-input/src/components/input/math-input.tsx

@@ -24,6 +24,7 @@ const constrainingFrictionFactor = 0.8;
 
 type Props = {
     keypadElement?: KeypadAPI;
+    ariaLabel: string;
     onBlur: () => void;
     onChange: (value: string, callback: any) => void;
     onFocus: () => void;
@@ -97,6 +98,7 @@ class MathInput extends React.Component<Props, State> {
 
         this.mathField = new MathWrapper(
             this._mathContainer,
+            this.props.ariaLabel,
             this.context.strings,
             this.context.locale,
             {

packages/math-input/src/components/input/math-wrapper.ts

@@ -38,20 +38,28 @@ class MathWrapper {
     mobileKeyTranslator: Record<Key, MathFieldUpdaterCallback>;
 
     constructor(
-        element,
+        mathFieldMount,
+        ariaLabel: string,
         strings: MathInputStrings,
         locale: string,
         callbacks = {},
     ) {
-        this.mathField = createMathField(element, locale, strings, () => {
-            return {
-                // use a span instead of a textarea so that we don't bring up the
-                // native keyboard on mobile when selecting the input
-                substituteTextarea: function () {
-                    return document.createElement("span");
-                },
-            };
-        });
+        this.mathField = createMathField(
+            mathFieldMount,
+            locale,
+            strings,
+            () => {
+                return {
+                    // use a span instead of a textarea so that we don't bring up the
+                    // native keyboard on mobile when selecting the input
+                    substituteTextarea: function () {
+                        return document.createElement("span");
+                    },
+                };
+            },
+        );
+        this.mathField?.setAriaLabel(ariaLabel);
+
         this.callbacks = callbacks;
 
         this.mobileKeyTranslator = {

packages/math-input/src/full-mobile-input.stories.tsx

@@ -84,6 +84,7 @@ const Basic = ({keypadElement, setKeypadElement}) => {
                 onBlur={() => {
                     keypadElement?.dismiss();
                 }}
+                ariaLabel="Mobile input"
             />
 
             <MobileKeypad

packages/perseus-editor/src/__stories__/article-editor.stories.tsx

@@ -0,0 +1,41 @@
+import {ApiOptions} from "@khanacademy/perseus";
+import * as React from "react";
+import {useRef, useState} from "react";
+
+import ArticleEditor from "../article-editor";
+import {registerAllWidgetsAndEditorsForTesting} from "../util/register-all-widgets-and-editors-for-testing";
+
+registerAllWidgetsAndEditorsForTesting();
+
+export default {
+    title: "PerseusEditor/ArticleEditor",
+};
+
+export const Base = (): React.ReactElement => {
+    const [state, setState] = useState();
+    const articleEditorRef = useRef();
+
+    function handleChange(value) {
+        setState(value.json);
+    }
+
+    function serialize() {
+        // eslint-disable-next-line no-console
+        console.log((articleEditorRef.current as any).serialize());
+    }
+
+    return (
+        <>
+            <button onClick={serialize}>Serialize</button>
+            <hr />
+            <ArticleEditor
+                apiOptions={ApiOptions.defaults}
+                imageUploader={() => {}}
+                json={state}
+                onChange={handleChange}
+                previewURL="/perseus/frame"
+                ref={articleEditorRef as any}
+            />
+        </>
+    );
+};

packages/perseus-editor/src/widgets/expression-editor.tsx

@@ -17,7 +17,7 @@ import SortableArea from "../components/sortable";
 
 import type {PerseusExpressionWidgetOptions} from "@khanacademy/perseus";
 
-const {InfoTip, PropCheckBox} = components;
+const {InfoTip, PropCheckBox, TextInput} = components;
 
 type Props = {
     widgetId?: any;
@@ -175,6 +175,48 @@ class ExpressionEditor extends React.Component<Props> {
             <div className="perseus-widget-expression-editor">
                 <h3 className="expression-editor-h3">Global Options</h3>
 
+                <div className="perseus-widget-row">
+                    <label>
+                        Visible label:{" "}
+                        <TextInput
+                            value={this.props.visibleLabel}
+                            onChange={this.change("visibleLabel")}
+                        />
+                    </label>
+                    <InfoTip>
+                        <p>
+                            Optional visible text; strongly encouraged to help
+                            learners using dictation software, but can be
+                            omitted if the surrounding content provides enough
+                            context.
+                        </p>
+                    </InfoTip>
+                </div>
+
+                <div className="perseus-widget-row">
+                    <label>
+                        Aria label:{" "}
+                        <TextInput
+                            value={this.props.ariaLabel}
+                            onChange={this.change("ariaLabel")}
+                        />
+                    </label>
+                    <InfoTip>
+                        <p>
+                            Label text that's read by screen readers. Highly
+                            recommend adding a label here to ensure your
+                            exercise is accessible. For more information on
+                            writting accessible labels, please see{" "}
+                            <a
+                                href="https://www.w3.org/WAI/tips/designing/#ensure-that-form-elements-include-clearly-associated-labels"
+                                target="_blank"
+                            >
+                                this article.
+                            </a>
+                        </p>
+                    </InfoTip>
+                </div>
+
                 <div>
                     <PropCheckBox
                         times={this.props.times}
@@ -254,6 +296,8 @@ class ExpressionEditor extends React.Component<Props> {
             "buttonSets",
             "functions",
             "times",
+            "visibleLabel",
+            "ariaLabel",
         ];
 
         const answerForms = this.props.answerForms.map((form) => {

packages/perseus/src/components/__stories__/math-input.stories.tsx

@@ -25,6 +25,7 @@ const defaultObject = {
     value: "",
     onChange: () => {},
     analytics: {onAnalyticsEvent: () => Promise.resolve()},
+    labelText: "Math input",
 } as const;
 
 export const DefaultWithBasicButtonSet = (
@@ -33,7 +34,7 @@ export const DefaultWithBasicButtonSet = (
     return <MathInput {...defaultObject} />;
 };
 export const DefaultWithAriaLabel = (args: StoryArgs): React.ReactElement => {
-    return <MathInput {...defaultObject} labelText="Sample label" />;
+    return <MathInput {...defaultObject} ariaLabel="Sample label" />;
 };
 
 export const KeypadOpenByDefault = (args: StoryArgs): React.ReactElement => {

packages/perseus/src/components/__tests__/math-input.test.tsx

@@ -36,7 +36,6 @@ describe("Perseus' MathInput", () => {
             <MathInput
                 onChange={() => {}}
                 keypadButtonSets={allButtonSets}
-                labelText="test"
                 analytics={{onAnalyticsEvent: () => Promise.resolve()}}
                 convertDotToTimes={false}
                 value=""
@@ -45,7 +44,48 @@ describe("Perseus' MathInput", () => {
         act(() => jest.runOnlyPendingTimers());
 
         // Assert
-        expect(screen.getByLabelText("test")).toBeInTheDocument();
+        expect(
+            screen.getByRole("textbox", {name: "Math input:"}),
+        ).toBeInTheDocument();
+    });
+
+    it("provides a default aria label", () => {
+        // Assemble
+        render(
+            <MathInput
+                onChange={() => {}}
+                keypadButtonSets={allButtonSets}
+                analytics={{onAnalyticsEvent: () => Promise.resolve()}}
+                convertDotToTimes={false}
+                value=""
+            />,
+        );
+        act(() => jest.runOnlyPendingTimers());
+
+        // Assert
+        expect(
+            screen.getByRole("textbox", {name: "Math input:"}),
+        ).toBeInTheDocument();
+    });
+
+    it("is possible to overwrite the aria label", () => {
+        // Assemble
+        render(
+            <MathInput
+                onChange={() => {}}
+                keypadButtonSets={allButtonSets}
+                analytics={{onAnalyticsEvent: () => Promise.resolve()}}
+                convertDotToTimes={false}
+                value=""
+                ariaLabel="Hello world"
+            />,
+        );
+        act(() => jest.runOnlyPendingTimers());
+
+        // Assert
+        expect(
+            screen.getByRole("textbox", {name: "Hello world:"}),
+        ).toBeInTheDocument();
     });
 
     it("is possible to type in the input", async () => {
@@ -63,7 +103,10 @@ describe("Perseus' MathInput", () => {
         act(() => jest.runOnlyPendingTimers());
 
         // Act
-        await userEvent.type(screen.getByRole("textbox"), "12345");
+        await userEvent.type(
+            screen.getByRole("textbox", {name: "Math input:"}),
+            "12345",
+        );
         act(() => jest.runOnlyPendingTimers());
 
         // Assert
@@ -150,7 +193,7 @@ describe("Perseus' MathInput", () => {
         await userEvent.click(screen.getByRole("button", {name: "1"}));
 
         // Assert
-        expect(screen.getByRole("textbox")).toHaveFocus();
+        expect(screen.getByRole("textbox", {name: /Math input/})).toHaveFocus();
     });
 
     it("does not return focus to input after button press via keyboard", async () => {
@@ -177,7 +220,9 @@ describe("Perseus' MathInput", () => {
         act(() => jest.runOnlyPendingTimers());
 
         // Assert
-        expect(screen.getByRole("textbox")).not.toHaveFocus();
+        expect(
+            screen.getByRole("textbox", {name: "Math input:"}),
+        ).not.toHaveFocus();
     });
 
     it("does not focus on the keypad button when it is clicked with the mouse", async () => {

packages/perseus/src/components/math-input.tsx

@@ -52,7 +52,7 @@ type Props = {
      * Overrides deprecated `buttonSets` prop.
      */
     keypadButtonSets?: KeypadButtonSets;
-    labelText?: string;
+    ariaLabel: string;
     onFocus?: () => void;
     onBlur?: () => void;
     hasError?: boolean;
@@ -241,6 +241,7 @@ class InnerMathInput extends React.Component<InnerProps, State> {
             );
         }
 
+        this.__mathField?.setAriaLabel(this.props.ariaLabel);
         return this.__mathField;
     };
 
@@ -322,7 +323,6 @@ class InnerMathInput extends React.Component<InnerProps, State> {
                     <span
                         className={className}
                         ref={(ref) => (this.__mathFieldWrapperRef = ref)}
-                        aria-label={this.props.labelText}
                         onFocus={() => this.focus()}
                         onBlur={() => this.blur()}
                     />
@@ -394,6 +394,10 @@ class MathInput extends React.Component<Props, State> {
     declare context: React.ContextType<typeof MathInputI18nContext>;
     inputRef = React.createRef<InnerMathInput>();
 
+    static defaultProps: Pick<Props, "ariaLabel"> = {
+        ariaLabel: "Math input",
+    };
+
     blur() {
         this.inputRef.current?.blur();
     }

packages/perseus/src/perseus-types.ts

@@ -418,6 +418,10 @@ export type PerseusExpressionWidgetOptions = {
     functions: ReadonlyArray<string>;
     // Use x for rendering multiplication instead of a center dot.
     times: boolean;
+    // visible label associated with the MathQuill field
+    visibleLabel?: string;
+    // aria label for screen readers attached to MathQuill field
+    ariaLabel?: string;
     // Controls when buttons for special characters are visible when using a
     // desktop browser.  Defaults to "focused".
     // NOTE: This isn't listed in perseus-format.js or perseus_data.go, but

packages/perseus/src/strings.ts

@@ -4,6 +4,7 @@
 export type PerseusStrings = {
     closeKeypad: string;
     openKeypad: string;
+    mathInputBox: string;
     removeHighlight: string;
     addHighlight: string;
     hintPos: ({pos}: {pos: number}) => string;
@@ -136,6 +137,7 @@ export const strings: {
 } = {
     closeKeypad: "close math keypad",
     openKeypad: "open math keypad",
+    mathInputBox: "Math input box",
     removeHighlight: "Remove highlight",
     addHighlight: "Add highlight",
     hintPos: "Hint #%(pos)s",
@@ -292,6 +294,7 @@ export const strings: {
 export const mockStrings: PerseusStrings = {
     closeKeypad: "close math keypad",
     openKeypad: "open math keypad",
+    mathInputBox: "Math input box",
     removeHighlight: "Remove highlight",
     addHighlight: "Add highlight",
     hintPos: ({pos}) => `Hint #${pos}`,

packages/perseus/src/styles/perseus-renderer.less

@@ -455,6 +455,9 @@
 
     &.widget-inline-block {
         display: inline-block;
+        // we added this to help center inline Expression widgets
+        // in the context of text/MathJax
+        vertical-align: bottom;
     }
 }