From 911f3d47bc5cb1bc293028fb5ceb79d7a4f0f1f8 Mon Sep 17 00:00:00 2001
From: Bea Esguerra <beaesguerra@khanacademy.org>
Date: Tue, 5 Nov 2024 16:46:49 -0700
Subject: [PATCH 1/8] Add instantValidation prop so there is an option to
 validate on blur. If instantValidation is false, the error is cleared on
 change

---
 .../wonder-blocks-form/text-area.stories.tsx  |  48 ++++
 .../components/__tests__/text-area.test.tsx   | 247 +++++++++++++++++-
 .../src/components/text-area.tsx              |  44 +++-
 3 files changed, 336 insertions(+), 3 deletions(-)

diff --git a/__docs__/wonder-blocks-form/text-area.stories.tsx b/__docs__/wonder-blocks-form/text-area.stories.tsx
index d8cd44312..0c545291c 100644
--- a/__docs__/wonder-blocks-form/text-area.stories.tsx
+++ b/__docs__/wonder-blocks-form/text-area.stories.tsx
@@ -293,6 +293,54 @@ ErrorFromPropAndValidation.parameters = {
     },
 };
 
+/**
+ * The `instantValidation` prop controls when validation is triggered. Validation
+ * is only triggered if the `validate` or `required` props are set.
+ *
+ * Validation is triggered:
+ * 1. On mount if the `value` prop is not empty
+ * 2. If `instantValidation` is `true`, validation occurs `onChange` (default)
+ * 3. If `instantValidation` is `false`, validation occurs `onBlur`
+ */
+export const InstantValidation: StoryComponentType = {
+    args: {
+        validate(value: string) {
+            const emailRegex = /^[^@\s]+@[^@\s.]+\.[^@.\s]+$/;
+            if (!emailRegex.test(value)) {
+                return "Please enter a valid email";
+            }
+        },
+    },
+    render: (args) => {
+        return (
+            <View style={{gap: spacing.small_12}}>
+                <LabelSmall htmlFor="instant-validation-true">
+                    Instant Validation: true
+                </LabelSmall>
+                <ControlledTextArea
+                    {...args}
+                    id="instant-validation-true"
+                    instantValidation={true}
+                />
+                <LabelSmall htmlFor="instant-validation-false">
+                    Instant Validation: false
+                </LabelSmall>
+                <ControlledTextArea
+                    {...args}
+                    id="instant-validation-false"
+                    instantValidation={false}
+                />
+            </View>
+        );
+    },
+    parameters: {
+        chromatic: {
+            // Disabling because this doesn't test anything visual.
+            disableSnapshot: true,
+        },
+    },
+};
+
 /**
  * A required field will have error styling if the field is left blank. To
  * observe this, type something into the field, backspace all the way,
diff --git a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
index 7d89d0a93..6d6d7b719 100644
--- a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
+++ b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
@@ -2,7 +2,7 @@
 import * as React from "react";
 import {render, screen} from "@testing-library/react";
 
-import {RenderStateRoot} from "@khanacademy/wonder-blocks-core";
+import {PropsFor, RenderStateRoot} from "@khanacademy/wonder-blocks-core";
 import {userEvent} from "@testing-library/user-event";
 import TextArea from "../text-area";
 
@@ -12,6 +12,11 @@ const defaultOptions = {
 
 const wrapOptions: Array<"soft" | "hard" | "off"> = ["soft", "hard", "off"];
 
+const ControlledTextArea = (props: Partial<PropsFor<typeof TextArea>>) => {
+    const [value, setValue] = React.useState(props.value || "");
+    return <TextArea {...props} value={value} onChange={setValue} />;
+};
+
 describe("TextArea", () => {
     describe("Attributes", () => {
         it("should use the id prop for the textarea", async () => {
@@ -1324,5 +1329,245 @@ describe("TextArea", () => {
                 );
             });
         });
+
+        describe("instantValidation prop", () => {
+            it("should call validate each time the value changes if the instantValidation prop is not provided", async () => {
+                // Arrange
+                const validate = jest.fn();
+                render(
+                    <ControlledTextArea validate={validate} />,
+                    defaultOptions,
+                );
+
+                // Act
+                const field = screen.getByRole("textbox");
+                await userEvent.type(field, "test");
+                await userEvent.tab();
+
+                // Assert
+                expect(validate.mock.calls).toStrictEqual([
+                    ["t"],
+                    ["te"],
+                    ["tes"],
+                    ["test"],
+                ]);
+            });
+
+            describe("instantValidation=true", () => {
+                it("should call validate each time the value changes if the instantValidation prop is true", async () => {
+                    // Arrange
+                    const validate = jest.fn();
+                    render(
+                        <ControlledTextArea
+                            validate={validate}
+                            instantValidation={true}
+                        />,
+                        defaultOptions,
+                    );
+
+                    // Act
+                    const field = screen.getByRole("textbox");
+                    await userEvent.type(field, "test");
+                    await userEvent.tab();
+
+                    // Assert
+                    expect(validate.mock.calls).toStrictEqual([
+                        ["t"],
+                        ["te"],
+                        ["tes"],
+                        ["test"],
+                    ]);
+                });
+
+                it("should call onValidate with the error message each time the value changes", async () => {
+                    // Arrange
+                    const onValidate = jest.fn();
+                    const errorMessage = "Error";
+                    render(
+                        <ControlledTextArea
+                            validate={() => errorMessage}
+                            onValidate={onValidate}
+                            instantValidation={true}
+                        />,
+                        defaultOptions,
+                    );
+
+                    // Act
+                    const field = screen.getByRole("textbox");
+                    await userEvent.type(field, "test");
+                    await userEvent.tab();
+
+                    // Assert
+                    expect(onValidate.mock.calls).toStrictEqual([
+                        [errorMessage],
+                        [errorMessage],
+                        [errorMessage],
+                        [errorMessage],
+                    ]);
+                });
+
+                it("should have the textarea in an error state after validation fails without waiting for the user to tab away", async () => {
+                    // Arrange
+                    render(
+                        <ControlledTextArea
+                            instantValidation={true}
+                            validate={() => "Error message"}
+                        />,
+                        defaultOptions,
+                    );
+                    // Act
+                    const field = screen.getByRole("textbox");
+                    await userEvent.type(field, "test");
+
+                    // Assert
+                    expect(field).toHaveAttribute("aria-invalid", "true");
+                });
+            });
+            describe("instantValidation=false", () => {
+                it("should call validate once the user leaves the field if the instantValidation prop is false", async () => {
+                    // Arrange
+                    const validate = jest.fn();
+                    render(
+                        <ControlledTextArea
+                            validate={validate}
+                            instantValidation={false}
+                        />,
+                        defaultOptions,
+                    );
+
+                    // Act
+                    const field = screen.getByRole("textbox");
+                    await userEvent.type(field, "test");
+                    await userEvent.tab();
+
+                    // Assert
+                    expect(validate).toHaveBeenCalledExactlyOnceWith("test");
+                });
+
+                it("should call onValidate once the user leaves the field if the instantValidation prop is false", async () => {
+                    // Arrange
+                    const handleValidate = jest.fn();
+                    const errorMsg = "error message";
+                    render(
+                        <ControlledTextArea
+                            validate={() => errorMsg}
+                            onValidate={handleValidate}
+                            instantValidation={false}
+                        />,
+                        defaultOptions,
+                    );
+
+                    // Act
+                    const field = screen.getByRole("textbox");
+                    await userEvent.type(field, "test");
+                    await userEvent.tab();
+
+                    // Assert
+                    expect(handleValidate).toHaveBeenCalledExactlyOnceWith(
+                        errorMsg,
+                    );
+                });
+
+                it("should not have the textarea in an error state before the field is blurred", async () => {
+                    // Arrange
+                    render(
+                        <ControlledTextArea
+                            instantValidation={false}
+                            validate={() => "Error message"}
+                        />,
+                        defaultOptions,
+                    );
+                    // Act
+                    const field = screen.getByRole("textbox");
+                    await userEvent.type(field, "test");
+
+                    // Assert
+                    expect(field).toHaveAttribute("aria-invalid", "false");
+                });
+
+                it("should have the textarea in an error state after validation fails and the field is blurred", async () => {
+                    // Arrange
+                    render(
+                        <ControlledTextArea
+                            instantValidation={false}
+                            validate={() => "Error message"}
+                        />,
+                        defaultOptions,
+                    );
+                    // Act
+                    const field = screen.getByRole("textbox");
+                    await userEvent.type(field, "test");
+                    await userEvent.tab();
+
+                    // Assert
+                    expect(field).toHaveAttribute("aria-invalid", "true");
+                });
+
+                it("should not be in an error state after a user updates the value after there was an error", async () => {
+                    // Arrange
+                    render(
+                        <ControlledTextArea
+                            validate={() => "Error message"}
+                            instantValidation={false}
+                        />,
+                        defaultOptions,
+                    );
+                    // Act
+                    const field = await screen.findByRole("textbox");
+                    await userEvent.type(field, "t");
+                    // Trigger blur so error is shown
+                    await userEvent.tab();
+                    // Updating the value should clear the error
+                    await userEvent.type(field, "te");
+
+                    // Assert
+                    expect(field).toHaveAttribute("aria-invalid", "false");
+                });
+
+                it("should call onValidate with an empty string when the user changes the value after there was an error", async () => {
+                    // Arrange
+                    const handleValidate = jest.fn();
+                    const errorMsg = "error message";
+                    render(
+                        <ControlledTextArea
+                            validate={() => errorMsg}
+                            onValidate={handleValidate}
+                            instantValidation={false}
+                        />,
+                        defaultOptions,
+                    );
+
+                    // Act
+                    const field = screen.getByRole("textbox");
+                    await userEvent.type(field, "test");
+                    // Blur will trigger error to be shown
+                    await userEvent.tab();
+                    // Updating the value should clear the error using the onValidate prop
+                    await userEvent.type(field, "tests");
+
+                    // Assert
+                    expect(handleValidate).toHaveBeenLastCalledWith("");
+                });
+
+                it("should not call the validate prop on blur if it is disabled", async () => {
+                    // Arrange
+                    const validate = jest.fn();
+                    render(
+                        <ControlledTextArea
+                            value="test"
+                            validate={validate}
+                            disabled={true}
+                        />,
+                        defaultOptions,
+                    );
+                    // Act
+                    await userEvent.tab();
+                    await userEvent.tab();
+
+                    // Assert
+                    expect(validate).not.toHaveBeenCalled();
+                });
+            });
+        });
     });
 });
diff --git a/packages/wonder-blocks-form/src/components/text-area.tsx b/packages/wonder-blocks-form/src/components/text-area.tsx
index 15c439c95..ab25be966 100644
--- a/packages/wonder-blocks-form/src/components/text-area.tsx
+++ b/packages/wonder-blocks-form/src/components/text-area.tsx
@@ -142,6 +142,13 @@ type TextAreaProps = AriaProps & {
      * Called right after the textarea is validated.
      */
     onValidate?: (errorMessage?: string | null | undefined) => unknown;
+    /**
+     * If true, textarea is validated as the user types (onChange). If false,
+     * it is validated when the user's focus moves out of the field (onBlur).
+     * It is preferred that instantValidation is set to `false`, however, it
+     * defaults to `true` for backwards compatibility with existing implementations.
+     */
+    instantValidation?: boolean;
     /**
      * Whether the textarea is in an error state.
      *
@@ -222,6 +229,7 @@ const TextArea = React.forwardRef<HTMLTextAreaElement, TextAreaProps>(
             light,
             rootStyle,
             error,
+            instantValidation = true,
             // Should only include aria related props
             ...otherProps
         } = props;
@@ -240,10 +248,42 @@ const TextArea = React.forwardRef<HTMLTextAreaElement, TextAreaProps>(
         ) => {
             const newValue = event.target.value;
             onChange(newValue);
-            handleValidation(newValue);
+            if (instantValidation) {
+                handleValidation(newValue);
+            } else {
+                if (errorMessage) {
+                    // If instantValidation is false and there is an error
+                    // message, error needs to be cleared when the user updates
+                    // the value
+                    setErrorMessage("");
+                    if (onValidate) {
+                        onValidate("");
+                    }
+                }
+            }
+        };
+
+        const handleBlur = (event: React.FocusEvent<HTMLTextAreaElement>) => {
+            // Only handle validation on blur if instantValidation is false
+            if (!instantValidation) {
+                // Only handle validation when there is a value in the field so
+                // a user tabbing through fields doesn't trigger the error state
+                // when the field is left empty
+                if (event.target.value) {
+                    handleValidation(event.target.value);
+                }
+            }
+
+            if (onBlur) {
+                onBlur(event);
+            }
         };
 
         const handleValidation = (newValue: string) => {
+            // Should not handle validation if it is disabled
+            if (disabled) {
+                return;
+            }
             if (validate) {
                 const error = validate(newValue) || null;
                 setErrorMessage(error);
@@ -317,7 +357,7 @@ const TextArea = React.forwardRef<HTMLTextAreaElement, TextAreaProps>(
                     onKeyDown={disabled ? undefined : onKeyDown}
                     onKeyUp={disabled ? undefined : onKeyUp}
                     onFocus={onFocus} // TextArea can be focused on if it is disabled
-                    onBlur={onBlur} // TextArea can be blurred if it is disabled
+                    onBlur={handleBlur} // TextArea can be blurred if it is disabled
                     required={!!required}
                     {...otherProps}
                     aria-invalid={hasError}

From ff4b525409f4d3786c403f9347774e99c31fd5e6 Mon Sep 17 00:00:00 2001
From: Bea Esguerra <beaesguerra@khanacademy.org>
Date: Tue, 5 Nov 2024 17:33:58 -0700
Subject: [PATCH 2/8] If textarea is required, validate whenever the user tabs
 away from the field

---
 .../wonder-blocks-form/text-area.stories.tsx  |  65 +++++--
 .../components/__tests__/text-area.test.tsx   | 168 ++++++++++++++++++
 .../src/components/text-area.tsx              |  11 +-
 3 files changed, 230 insertions(+), 14 deletions(-)

diff --git a/__docs__/wonder-blocks-form/text-area.stories.tsx b/__docs__/wonder-blocks-form/text-area.stories.tsx
index 0c545291c..65e0e0e3b 100644
--- a/__docs__/wonder-blocks-form/text-area.stories.tsx
+++ b/__docs__/wonder-blocks-form/text-area.stories.tsx
@@ -295,12 +295,23 @@ ErrorFromPropAndValidation.parameters = {
 
 /**
  * The `instantValidation` prop controls when validation is triggered. Validation
- * is only triggered if the `validate` or `required` props are set.
+ * is triggered if the `validate` or `required` props are set.
+ *
+ * It is preferred to set `instantValidation` to `false` so that the user isn't
+ * shown an error until they are done with a field. Note: if `instantValidation`
+ * is not explicitly set, it defaults to `true` since this is the current
+ * behaviour of existing usage. Validation on blur needs to be opted in.
  *
  * Validation is triggered:
- * 1. On mount if the `value` prop is not empty
- * 2. If `instantValidation` is `true`, validation occurs `onChange` (default)
- * 3. If `instantValidation` is `false`, validation occurs `onBlur`
+ * - On mount if the `value` prop is not empty
+ * - If `instantValidation` is `true`, validation occurs `onChange` (default)
+ * - If `instantValidation` is `false`, validation occurs `onBlur`
+ *
+ * When `required` is set to `true`:
+ * - If `instantValidation` is `true`, the required error message is shown after
+ * a value is cleared
+ * - If `instantValidation` is `false`, the required error message is shown
+ * whenever the user tabs away from the required field
  */
 export const InstantValidation: StoryComponentType = {
     args: {
@@ -314,21 +325,55 @@ export const InstantValidation: StoryComponentType = {
     render: (args) => {
         return (
             <View style={{gap: spacing.small_12}}>
-                <LabelSmall htmlFor="instant-validation-true">
-                    Instant Validation: true
+                <LabelSmall htmlFor="instant-validation-true-not-required">
+                    Validation on mount if there is a value
+                </LabelSmall>
+                <ControlledTextArea
+                    {...args}
+                    id="instant-validation-true-not-required"
+                    value="invalid"
+                />
+                <LabelSmall htmlFor="instant-validation-true-not-required">
+                    Error shown immediately (instantValidation: true, required:
+                    false)
+                </LabelSmall>
+                <ControlledTextArea
+                    {...args}
+                    id="instant-validation-true-not-required"
+                    instantValidation={true}
+                />
+                <LabelSmall htmlFor="instant-validation-false-not-required">
+                    Error shown onBlur (instantValidation: false, required:
+                    false)
+                </LabelSmall>
+                <ControlledTextArea
+                    {...args}
+                    id="instant-validation-false-not-required"
+                    instantValidation={false}
+                />
+
+                <LabelSmall htmlFor="instant-validation-true-required">
+                    Error shown immediately after clearing the value
+                    (instantValidation: true, required: true)
                 </LabelSmall>
                 <ControlledTextArea
                     {...args}
-                    id="instant-validation-true"
+                    validate={undefined}
+                    value="T"
+                    id="instant-validation-true-required"
                     instantValidation={true}
+                    required="Required"
                 />
-                <LabelSmall htmlFor="instant-validation-false">
-                    Instant Validation: false
+                <LabelSmall htmlFor="instant-validation-false-required">
+                    Error shown on blur if it is empty (instantValidation:
+                    false, required: true)
                 </LabelSmall>
                 <ControlledTextArea
                     {...args}
-                    id="instant-validation-false"
+                    validate={undefined}
+                    id="instant-validation-false-required"
                     instantValidation={false}
+                    required="Required"
                 />
             </View>
         );
diff --git a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
index 6d6d7b719..bf71dc822 100644
--- a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
+++ b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
@@ -1160,6 +1160,28 @@ describe("TextArea", () => {
                 expect(textArea).toHaveAttribute("aria-invalid", "false");
             });
 
+            it("should not be in an error state if it is required, the field is empty, and a user tabs through the field", async () => {
+                // Arrange
+                render(
+                    <TextArea
+                        value=""
+                        onChange={() => {}}
+                        required="Required"
+                    />,
+                    defaultOptions,
+                );
+
+                // Act
+                // Tab into field
+                await userEvent.tab();
+                // Tab out of field
+                await userEvent.tab();
+
+                // Assert
+                const textArea = await screen.findByRole("textbox");
+                expect(textArea).toHaveAttribute("aria-invalid", "false");
+            });
+
             it("shound update with error if it is required and the value changes to an empty string", async () => {
                 // Arrange
                 render(
@@ -1567,6 +1589,152 @@ describe("TextArea", () => {
                     // Assert
                     expect(validate).not.toHaveBeenCalled();
                 });
+
+                describe("required", () => {
+                    it("shound be in error state if it is required, the value changes to an empty string, and the user tabs away", async () => {
+                        // Arrange
+                        render(
+                            <ControlledTextArea
+                                value="T"
+                                required="Required"
+                                instantValidation={false}
+                            />,
+                            defaultOptions,
+                        );
+
+                        // Act
+                        const field = await screen.findByRole("textbox");
+                        await userEvent.type(field, "{backspace}");
+                        await userEvent.tab();
+
+                        // Assert
+                        const textArea = await screen.findByRole("textbox");
+                        expect(textArea).toHaveAttribute(
+                            "aria-invalid",
+                            "true",
+                        );
+                    });
+
+                    it("shound call onValidate with the required message if it is required, the value changes to an empty string, and the user tabs away", async () => {
+                        // Arrange
+                        const onValidate = jest.fn();
+                        const requiredMessage = "Required";
+                        render(
+                            <ControlledTextArea
+                                value="T"
+                                required={requiredMessage}
+                                instantValidation={false}
+                                onValidate={onValidate}
+                            />,
+                            defaultOptions,
+                        );
+
+                        // Act
+                        const field = await screen.findByRole("textbox");
+                        await userEvent.type(field, "{backspace}");
+                        await userEvent.tab();
+
+                        // Assert
+                        expect(onValidate).toHaveBeenLastCalledWith(
+                            requiredMessage,
+                        );
+                    });
+
+                    it("shound be in error state if it is required, the value is empty, and the user tabs away", async () => {
+                        // Arrange
+                        render(
+                            <ControlledTextArea
+                                required="Required"
+                                instantValidation={false}
+                            />,
+                            defaultOptions,
+                        );
+
+                        // Act
+                        // Tab into field
+                        await userEvent.tab();
+                        // Tab out of field
+                        await userEvent.tab();
+
+                        // Assert
+                        const textArea = await screen.findByRole("textbox");
+                        expect(textArea).toHaveAttribute(
+                            "aria-invalid",
+                            "true",
+                        );
+                    });
+
+                    it("shound call onValidate with the required message if it is required, the value is empty, and the user tabs away", async () => {
+                        // Arrange
+                        const onValidate = jest.fn();
+                        const requiredMessage = "Required";
+                        render(
+                            <ControlledTextArea
+                                required={requiredMessage}
+                                onValidate={onValidate}
+                                instantValidation={false}
+                            />,
+                            defaultOptions,
+                        );
+
+                        // Act
+                        // Tab into field
+                        await userEvent.tab();
+                        // Tab out of field
+                        await userEvent.tab();
+
+                        // Assert
+                        expect(onValidate).toHaveBeenCalledExactlyOnceWith(
+                            requiredMessage,
+                        );
+                    });
+
+                    it("should not be in error state if it is not required, the value is empty, and the user tabs away", async () => {
+                        // Arrange
+                        render(
+                            <ControlledTextArea
+                                required={undefined}
+                                instantValidation={false}
+                            />,
+                            defaultOptions,
+                        );
+
+                        // Act
+                        // Tab into field
+                        await userEvent.tab();
+                        // Tab out of field
+                        await userEvent.tab();
+
+                        // Assert
+                        const textArea = await screen.findByRole("textbox");
+                        expect(textArea).toHaveAttribute(
+                            "aria-invalid",
+                            "false",
+                        );
+                    });
+
+                    it("should not call onValidate if it is not required, the value is empty, and the user tabs away", async () => {
+                        // Arrange
+                        const onValidate = jest.fn();
+                        render(
+                            <ControlledTextArea
+                                required={undefined}
+                                instantValidation={false}
+                                onValidate={onValidate}
+                            />,
+                            defaultOptions,
+                        );
+
+                        // Act
+                        // Tab into field
+                        await userEvent.tab();
+                        // Tab out of field
+                        await userEvent.tab();
+
+                        // Assert
+                        expect(onValidate).not.toHaveBeenCalled();
+                    });
+                });
             });
         });
     });
diff --git a/packages/wonder-blocks-form/src/components/text-area.tsx b/packages/wonder-blocks-form/src/components/text-area.tsx
index ab25be966..67171e61f 100644
--- a/packages/wonder-blocks-form/src/components/text-area.tsx
+++ b/packages/wonder-blocks-form/src/components/text-area.tsx
@@ -266,10 +266,13 @@ const TextArea = React.forwardRef<HTMLTextAreaElement, TextAreaProps>(
         const handleBlur = (event: React.FocusEvent<HTMLTextAreaElement>) => {
             // Only handle validation on blur if instantValidation is false
             if (!instantValidation) {
-                // Only handle validation when there is a value in the field so
-                // a user tabbing through fields doesn't trigger the error state
-                // when the field is left empty
-                if (event.target.value) {
+                // Handle validation on blur if:
+                // 1. There is a value in the field so a user tabbing through
+                // fields doesn't trigger the error state when the field is left
+                // empty. Or,
+                // 2. The field is required. Tabbing through an empty field that
+                // is required will trigger the error state
+                if (event.target.value || required) {
                     handleValidation(event.target.value);
                 }
             }

From 08dd8ed20bff17e0a850e850bfc688f026b7b931 Mon Sep 17 00:00:00 2001
From: Bea Esguerra <beaesguerra@khanacademy.org>
Date: Wed, 6 Nov 2024 10:13:50 -0700
Subject: [PATCH 3/8] add changeset

---
 .changeset/chatty-moles-brush.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/chatty-moles-brush.md

diff --git a/.changeset/chatty-moles-brush.md b/.changeset/chatty-moles-brush.md
new file mode 100644
index 000000000..7e37f5615
--- /dev/null
+++ b/.changeset/chatty-moles-brush.md
@@ -0,0 +1,5 @@
+---
+"@khanacademy/wonder-blocks-form": minor
+---
+
+Adds `instantValidation` prop for TextArea

From 5c5e69983f245ddf31ecf9619eb430edbc042dc9 Mon Sep 17 00:00:00 2001
From: Bea Esguerra <beaesguerra@khanacademy.org>
Date: Wed, 6 Nov 2024 11:52:05 -0700
Subject: [PATCH 4/8] update tests

---
 .../components/__tests__/text-area.test.tsx   | 24 +++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
index bf71dc822..a85e4acc3 100644
--- a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
+++ b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
@@ -1579,6 +1579,7 @@ describe("TextArea", () => {
                             value="test"
                             validate={validate}
                             disabled={true}
+                            instantValidation={false}
                         />,
                         defaultOptions,
                     );
@@ -1615,6 +1616,29 @@ describe("TextArea", () => {
                         );
                     });
 
+                    it("shound not be in error state if it is required, the value changes to an empty string, and the user has not tabbed away", async () => {
+                        // Arrange
+                        render(
+                            <ControlledTextArea
+                                value="T"
+                                required="Required"
+                                instantValidation={false}
+                            />,
+                            defaultOptions,
+                        );
+
+                        // Act
+                        const field = await screen.findByRole("textbox");
+                        await userEvent.type(field, "{backspace}");
+
+                        // Assert
+                        const textArea = await screen.findByRole("textbox");
+                        expect(textArea).toHaveAttribute(
+                            "aria-invalid",
+                            "false",
+                        );
+                    });
+
                     it("shound call onValidate with the required message if it is required, the value changes to an empty string, and the user tabs away", async () => {
                         // Arrange
                         const onValidate = jest.fn();

From 9c89a8dcf167a954981d1e61e6477a73082008e9 Mon Sep 17 00:00:00 2001
From: Bea Esguerra <beaesguerra@khanacademy.org>
Date: Wed, 6 Nov 2024 13:21:11 -0700
Subject: [PATCH 5/8] remove redundant description in test cases since the
 describe block includes that info already

---
 .../src/components/__tests__/text-area.test.tsx             | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
index a85e4acc3..7b1a4607a 100644
--- a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
+++ b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
@@ -1376,7 +1376,7 @@ describe("TextArea", () => {
             });
 
             describe("instantValidation=true", () => {
-                it("should call validate each time the value changes if the instantValidation prop is true", async () => {
+                it("should call validate each time the value changes", async () => {
                     // Arrange
                     const validate = jest.fn();
                     render(
@@ -1446,7 +1446,7 @@ describe("TextArea", () => {
                 });
             });
             describe("instantValidation=false", () => {
-                it("should call validate once the user leaves the field if the instantValidation prop is false", async () => {
+                it("should call validate once the user leaves the field", async () => {
                     // Arrange
                     const validate = jest.fn();
                     render(
@@ -1466,7 +1466,7 @@ describe("TextArea", () => {
                     expect(validate).toHaveBeenCalledExactlyOnceWith("test");
                 });
 
-                it("should call onValidate once the user leaves the field if the instantValidation prop is false", async () => {
+                it("should call onValidate once the user leaves the field", async () => {
                     // Arrange
                     const handleValidate = jest.fn();
                     const errorMsg = "error message";

From a2649eab9d8f73005991cee30d480d820317eb54 Mon Sep 17 00:00:00 2001
From: Bea Esguerra <beaesguerra@khanacademy.org>
Date: Wed, 6 Nov 2024 13:30:09 -0700
Subject: [PATCH 6/8] update test assertion to verify all calls to the mock
 instead of just checking the last one

---
 .../src/components/__tests__/text-area.test.tsx      | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
index 7b1a4607a..b93c6b823 100644
--- a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
+++ b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
@@ -1568,7 +1568,10 @@ describe("TextArea", () => {
                     await userEvent.type(field, "tests");
 
                     // Assert
-                    expect(handleValidate).toHaveBeenLastCalledWith("");
+                    expect(handleValidate.mock.calls).toStrictEqual([
+                        [errorMsg],
+                        [""],
+                    ]);
                 });
 
                 it("should not call the validate prop on blur if it is disabled", async () => {
@@ -1659,9 +1662,10 @@ describe("TextArea", () => {
                         await userEvent.tab();
 
                         // Assert
-                        expect(onValidate).toHaveBeenLastCalledWith(
-                            requiredMessage,
-                        );
+                        expect(onValidate.mock.calls).toStrictEqual([
+                            [null],
+                            [requiredMessage],
+                        ]);
                     });
 
                     it("shound be in error state if it is required, the value is empty, and the user tabs away", async () => {

From 8e1fdbfada4bb149ca88e1c76b69ddfca351b646 Mon Sep 17 00:00:00 2001
From: Bea Esguerra <beaesguerra@khanacademy.org>
Date: Wed, 6 Nov 2024 13:32:07 -0700
Subject: [PATCH 7/8] set error message to null instead of empty string when
 clearing the error

---
 .../src/components/__tests__/text-area.test.tsx               | 4 ++--
 packages/wonder-blocks-form/src/components/text-area.tsx      | 4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
index b93c6b823..7fcd2b973 100644
--- a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
+++ b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
@@ -1546,7 +1546,7 @@ describe("TextArea", () => {
                     expect(field).toHaveAttribute("aria-invalid", "false");
                 });
 
-                it("should call onValidate with an empty string when the user changes the value after there was an error", async () => {
+                it("should call onValidate with an null when the user changes the value after there was an error", async () => {
                     // Arrange
                     const handleValidate = jest.fn();
                     const errorMsg = "error message";
@@ -1570,7 +1570,7 @@ describe("TextArea", () => {
                     // Assert
                     expect(handleValidate.mock.calls).toStrictEqual([
                         [errorMsg],
-                        [""],
+                        [null],
                     ]);
                 });
 
diff --git a/packages/wonder-blocks-form/src/components/text-area.tsx b/packages/wonder-blocks-form/src/components/text-area.tsx
index 67171e61f..fcab8d600 100644
--- a/packages/wonder-blocks-form/src/components/text-area.tsx
+++ b/packages/wonder-blocks-form/src/components/text-area.tsx
@@ -255,9 +255,9 @@ const TextArea = React.forwardRef<HTMLTextAreaElement, TextAreaProps>(
                     // If instantValidation is false and there is an error
                     // message, error needs to be cleared when the user updates
                     // the value
-                    setErrorMessage("");
+                    setErrorMessage(null);
                     if (onValidate) {
-                        onValidate("");
+                        onValidate(null);
                     }
                 }
             }

From bee2c9796ceca194f163db595650aa7724eb0533 Mon Sep 17 00:00:00 2001
From: Bea Esguerra <beaesguerra@users.noreply.github.com>
Date: Fri, 8 Nov 2024 15:28:34 -0700
Subject: [PATCH 8/8] Fix test description typo

Co-authored-by: Marcy Sutton-Todd <marcytodd@khanacademy.org>
---
 .../src/components/__tests__/text-area.test.tsx                 | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
index 7fcd2b973..880643224 100644
--- a/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
+++ b/packages/wonder-blocks-form/src/components/__tests__/text-area.test.tsx
@@ -1546,7 +1546,7 @@ describe("TextArea", () => {
                     expect(field).toHaveAttribute("aria-invalid", "false");
                 });
 
-                it("should call onValidate with an null when the user changes the value after there was an error", async () => {
+                it("should call onValidate with null when the user changes the value after there was an error", async () => {
                     // Arrange
                     const handleValidate = jest.fn();
                     const errorMsg = "error message";