[Image] | (CX) (a11y) | Add long description field to Image widget editor (#2908)

nishasy · web-flow · commit d60a7197855d · 2025-09-17T11:25:43.000-07:00
## Summary: Now that the `longDescription` field has been added to the Image widget, we can add the text field for it within the Image widget editor. Making sure to add it behind a feature flag. Issue: https://khanacademy.atlassian.net/browse/LEMS-3378 ## Test plan: `pnpm jest packages/perseus-editor/src/widgets/__tests__/image-editor.test.tsx` Storybook `/?path=/docs/widgets-image-editor-demo--docs#populated-within-editor-page` ## Screenshots and demos: <img width="368" height="633" alt="Screenshot 2025-09-16 at 4 24 29 PM" src="https://github.com/user-attachments/assets/4aa28574-5d62-41a3-aa0f-a1f7bf6714f8" /> https://github.com/user-attachments/assets/2c276193-ca29-491e-a956-55eea5895ff3 Author: nishasy Reviewers: nishasy, ivyolamit, catandthemachines Required Reviewers: Approved By: ivyolamit Checks: ✅ 10 checks were successful Pull Request URL: #2908
diff --git a/.changeset/lazy-pugs-teach.md b/.changeset/lazy-pugs-teach.md
@@ -0,0 +1,6 @@
+---
+"@khanacademy/perseus": minor
+"@khanacademy/perseus-editor": minor
+---
+
+[Image] | (CX) (a11y) | Add long description field to Image widget editor
diff --git a/packages/perseus-editor/src/widgets/__docs__/image-editor.stories.tsx b/packages/perseus-editor/src/widgets/__docs__/image-editor.stories.tsx
@@ -1,10 +1,12 @@
+import {ApiOptions} from "@khanacademy/perseus";
 import {
     generateImageOptions,
     generateImageWidget,
     generateTestPerseusRenderer,
 } from "@khanacademy/perseus-core";
 import * as React from "react";
 
+import {getFeatureFlags} from "../../../../../testing/feature-flags-util";
 import EditorPageWithStorybookPreview from "../../__docs__/editor-page-with-storybook-preview";
 import {registerAllWidgetsAndEditorsForTesting} from "../../util/register-all-widgets-and-editors-for-testing";
 import ImageEditor from "../image-editor/image-editor";
@@ -17,6 +19,12 @@ const withinEditorPageDecorator = (_, {args}) => {
     return (
         <div style={{width: PROD_EDITOR_WIDTH}}>
             <EditorPageWithStorybookPreview
+                apiOptions={{
+                    ...ApiOptions.defaults,
+                    flags: getFeatureFlags({
+                        "image-widget-upgrade": true,
+                    }),
+                }}
                 question={generateTestPerseusRenderer({
                     content: "[[☃ image 1]]",
                     widgets: {
diff --git a/packages/perseus-editor/src/widgets/__tests__/image-editor.test.tsx b/packages/perseus-editor/src/widgets/__tests__/image-editor.test.tsx
@@ -3,6 +3,7 @@ import {render, screen} from "@testing-library/react";
 import {userEvent as userEventLib} from "@testing-library/user-event";
 import * as React from "react";
 
+import {getFeatureFlags} from "../../../../../testing/feature-flags-util";
 import {testDependencies} from "../../../../../testing/test-dependencies";
 import ImageEditor from "../image-editor/image-editor";
 
@@ -13,7 +14,10 @@ const realKhanImageUrl =
 const nonKhanImageWarning =
     "Images must be from sites hosted by Khan Academy. Please input a Khan Academy-owned address, or use the Add Image tool to rehost an existing image";
 
-const apiOptions = ApiOptions.defaults;
+const apiOptions = {
+    ...ApiOptions.defaults,
+    flags: getFeatureFlags({"image-widget-upgrade": true}),
+};
 
 describe("image editor", () => {
     let userEvent: UserEvent;
@@ -43,6 +47,7 @@ describe("image editor", () => {
         expect(screen.queryByText("Preview:")).not.toBeInTheDocument();
         expect(screen.queryByText("Dimensions:")).not.toBeInTheDocument();
         expect(screen.queryByText("Alt text:")).not.toBeInTheDocument();
+        expect(screen.queryByText("Long Description:")).not.toBeInTheDocument();
         expect(screen.queryByText("Caption:")).not.toBeInTheDocument();
     });
 
@@ -55,6 +60,7 @@ describe("image editor", () => {
                 apiOptions={apiOptions}
                 backgroundImage={{url: realKhanImageUrl}}
                 alt="Earth and moon alt"
+                longDescription="Earth and moon long description"
                 caption="Earth and moon caption"
                 title="Earth and moon title"
                 onChange={() => {}}
@@ -64,19 +70,26 @@ describe("image editor", () => {
         const dimensionsLabel = screen.getByText("Dimensions:");
         const urlField = screen.getByRole("textbox", {name: "Image url:"});
         const altField = screen.getByRole("textbox", {name: "Alt text:"});
+        const longDescriptionField = screen.getByRole("textbox", {
+            name: "Long Description:",
+        });
         const captionField = screen.getByRole("textbox", {name: "Caption:"});
         const titleField = screen.getByRole("textbox", {name: "Title:"});
 
         // Assert
         expect(dimensionsLabel).toBeInTheDocument();
         expect(urlField).toBeInTheDocument();
         expect(altField).toBeInTheDocument();
+        expect(longDescriptionField).toBeInTheDocument();
         expect(captionField).toBeInTheDocument();
         expect(titleField).toBeInTheDocument();
 
         expect(screen.getByText("unknown")).toBeInTheDocument();
         expect(urlField).toHaveValue(realKhanImageUrl);
         expect(altField).toHaveValue("Earth and moon alt");
+        expect(longDescriptionField).toHaveValue(
+            "Earth and moon long description",
+        );
         expect(captionField).toHaveValue("Earth and moon caption");
         expect(titleField).toHaveValue("Earth and moon title");
     });
@@ -258,6 +271,71 @@ describe("image editor", () => {
         });
     });
 
+    it("should call onChange with new long description", async () => {
+        // Arrange
+        const onChangeMock = jest.fn();
+        render(
+            <ImageEditor
+                apiOptions={apiOptions}
+                backgroundImage={{url: realKhanImageUrl}}
+                onChange={onChangeMock}
+            />,
+        );
+
+        // Act
+        const altField = screen.getByRole("textbox", {
+            name: "Long Description:",
+        });
+        altField.focus();
+        await userEvent.paste("Earth and moon long description");
+
+        // Assert
+        expect(onChangeMock).toHaveBeenCalledWith({
+            longDescription: "Earth and moon long description",
+        });
+    });
+
+    it("should call onChange with empty long description", async () => {
+        // Arrange
+        const onChangeMock = jest.fn();
+        render(
+            <ImageEditor
+                apiOptions={apiOptions}
+                backgroundImage={{url: realKhanImageUrl}}
+                longDescription="Earth and moon long description"
+                onChange={onChangeMock}
+            />,
+        );
+
+        // Act
+        const altField = screen.getByRole("textbox", {
+            name: "Long Description:",
+        });
+        await userEvent.clear(altField);
+
+        // Assert
+        expect(onChangeMock).toHaveBeenCalledWith({
+            longDescription: "",
+        });
+    });
+
+    it("should not render long description field if the feature flag is off", () => {
+        // Arrange
+        const onChangeMock = jest.fn();
+        render(
+            <ImageEditor
+                apiOptions={{
+                    ...ApiOptions.defaults,
+                    flags: getFeatureFlags({"image-widget-upgrade": false}),
+                }}
+                onChange={onChangeMock}
+            />,
+        );
+
+        // Assert
+        expect(screen.queryByText("Long Description:")).not.toBeInTheDocument();
+    });
+
     it("should call onChange with new caption", async () => {
         // Arrange
         const onChangeMock = jest.fn();
diff --git a/packages/perseus-editor/src/widgets/image-editor/image-settings.tsx b/packages/perseus-editor/src/widgets/image-editor/image-settings.tsx
@@ -1,4 +1,5 @@
 import {Util, components} from "@khanacademy/perseus";
+import {isFeatureOn} from "@khanacademy/perseus-core";
 import {sizing} from "@khanacademy/wonder-blocks-tokens";
 import {HeadingXSmall} from "@khanacademy/wonder-blocks-typography";
 import * as React from "react";
@@ -14,14 +15,19 @@ const {InfoTip} = components;
 export default function ImageSettings({
     alt,
     backgroundImage,
+    apiOptions,
     caption,
+    longDescription,
     title,
     onChange,
 }: Props) {
     const uniqueId = React.useId();
     const altId = `${uniqueId}-alt`;
     const titleId = `${uniqueId}-title`;
     const captionId = `${uniqueId}-caption`;
+    const longDescriptionId = `${uniqueId}-long-description`;
+
+    const imageUpgradeFF = isFeatureOn({apiOptions}, "image-widget-upgrade");
 
     if (!backgroundImage.url) {
         return null;
@@ -93,6 +99,21 @@ export default function ImageSettings({
                 style={textAreaStyle}
             />
 
+            {imageUpgradeFF && (
+                <>
+                    {/* Long Description */}
+                    <HeadingXSmall tag="label" htmlFor={longDescriptionId}>
+                        Long Description:
+                    </HeadingXSmall>
+                    <AutoResizingTextArea
+                        id={longDescriptionId}
+                        value={longDescription ?? ""}
+                        onChange={(value) => onChange({longDescription: value})}
+                        style={textAreaStyle}
+                    />
+                </>
+            )}
+
             {/* Title */}
             <HeadingXSmall tag="label" htmlFor={titleId}>
                 Title:
diff --git a/packages/perseus/src/widgets/image/image.tsx b/packages/perseus/src/widgets/image/image.tsx
@@ -1,3 +1,4 @@
+import {isFeatureOn} from "@khanacademy/perseus-core";
 import * as React from "react";
 
 import AssetContext from "../../asset-context";
@@ -25,6 +26,7 @@ export const ImageComponent = (props: ImageWidgetProps) => {
         trackInteraction,
     } = props;
     const context = React.useContext(PerseusI18nContext);
+    const imageUpgradeFF = isFeatureOn({apiOptions}, "image-widget-upgrade");
 
     if (!backgroundImage.url) {
         return null;
@@ -76,7 +78,7 @@ export const ImageComponent = (props: ImageWidgetProps) => {
             </AssetContext.Consumer>
 
             {/* Description & Caption */}
-            {(caption || longDescription) && (
+            {(caption || (imageUpgradeFF && longDescription)) && (
                 <ImageDescriptionAndCaption {...props} />
             )}
         </figure>
