[Image] | (UX) | Show image in explore modal even when size is undefined

[nishasy]

Summary:

We have a number of images in our content that are saved without a size.
If the image has a long description, it makes the "explore image" button available.
If the "explore image" button is clicked and then image has no size, the modal
shows up as completely empty.

The image should show up in the modal even if there is no size. Updating that here.

Issue: https://khanacademy.atlassian.net/browse/LEMS-3990

Test plan:

pnpm jest packages/perseus/src/widgets/image/components/explore-image-modal.test.tsx

Storybook

• /?path=/story/widgets-image-visual-regression-tests-interactions--long-description-clicked-state-with-no-size
• /?path=/story/widgets-image-visual-regression-tests-interactions--long-description-clicked-state-with-no-size-large-image
• /?path=/story/widgets-image-widget-demo--large-image-with-no-size-saved
• /?path=/story/widgets-image-widget-demo--large-image-with-no-size-saved-scale-flag

Before	After
Before - scale feature flag	after - scale feature flag

[github-actions]

🗄️ Schema Change: No Changes ✅

[github-actions]

Size Change: +11 B (0%)

Total Size: 486 kB

Filename	Size	Change
packages/perseus/dist/es/index.js	188 kB	+11 B (+0.01%)

ℹ️ View Unchanged

Filename	Size
packages/kas/dist/es/index.js	20.5 kB
packages/keypad-context/dist/es/index.js	1 kB
packages/kmath/dist/es/index.js	5.96 kB
packages/math-input/dist/es/index.js	98.5 kB
packages/math-input/dist/es/strings.js	1.61 kB
packages/perseus-core/dist/es/index.item-splitting.js	11.8 kB
packages/perseus-core/dist/es/index.js	24.9 kB
packages/perseus-editor/dist/es/index.js	100 kB
packages/perseus-linter/dist/es/index.js	8.82 kB
packages/perseus-score/dist/es/index.js	9.4 kB
packages/perseus-utils/dist/es/index.js	403 B
packages/perseus/dist/es/strings.js	7.47 kB
packages/pure-markdown/dist/es/index.js	1.39 kB
packages/simple-markdown/dist/es/index.js	6.71 kB

_{compressed-size-action}

[github-actions]

🛠️ Item Splitting: No Changes ✅

[github-actions]

npm Snapshot: Published

Good news!! We've packaged up the latest commit from this PR (dfbab76) and published it to npm. You
can install it using the tag PR3367.

Example:

pnpm add @khanacademy/perseus@PR3367

If you are working in Khan Academy's frontend, you can run the below command.

./dev/tools/bump_perseus_version.ts -t PR3367

If you are working in Khan Academy's webapp, you can run the below command.

./dev/tools/bump_perseus_version.js -t PR3367

[nishasy]

I considered removing this block entirely, since the sizing just works with undefined now. However, I opted to keep this block here since it will be useful for the work in my other branch on scaled graphie labels.

[nishasy]

This file has a lot of changes because of the boilerplate code that had to be updated to allow the image to actually load for testing.

[nishasy]

The culprit

[nishasy]

Large images would overflow and cover the long description without this CSS.

[mark-fitzgerald]

This CSS looks appropriate. However, I would prefer some changes to how the CSS variables are handled. I realize that this may be beyond the intent of this PR, but these changes will help to avoid potential conflicts.

1. Namespace the CSS variables
   • Instead of --modal-panel-height, I recommend using --perseus-image-modal-panel-height
   • This will prevent naming conflicts with other parts of the application that have a modal panel height variable of the same name.
2. Attach the CSS variables to .modal-container instead of :root
   • Even if variables are namespaced, adding them to the :root element overloads that element with variables that don't apply anywhere else other than the image widget.
   • If the variables are NOT namespaced, then this runs the risk of overriding the variable if it exists anywhere else in frontend, or of being overridden by a setting elsewhere in frontend.

[nishasy]

Thank you!

[claude]

Claude Code Review

This repository is configured for manual code reviews. Comment @claude review to trigger a review.

[nishasy]

Tested it in my local server with a PR tag using the exercise that I first noticed this issue in:

Before	After

[nishasy]

@mark-fitzgerald Is it okay for .modal-container to be defined in two spots like this to separate out where the variables are defined?

[mark-fitzgerald]

Technically it is OK, but I find it confusing. Is there a reason that it is split up?

[nishasy]

It's just split up so the variables can be at the top, and the styles can be further down with the other modal styles. Maybe I should move the modal styles to their own file so that the modal container can be at the top with the variables AND the style?

[mark-fitzgerald]

There's no requirement for the variables to be at the top of the file. It's not like JavaScript.

[nishasy]

@claude review

[claude]

🟡 When the scale feature flag is OFF (the default path) and the image has no saved dimensions, zoomSize is [0, 0], producing modalImageHeight = 0 and width = NaN (from 0/0 * 0) at lines 52-58. These values make the image invisible in the modal. The scaleFF path handles this correctly (lines 72-77 fall back to undefined), but the non-scaleFF path needs the same guard -- e.g. set width and modalImageHeight to undefined when zoomHeight is 0.

Extended reasoning...

What the bug is

In explore-image-modal-content.tsx, lines 52-58 compute the modal image dimensions for the non-scaleFF (legacy/default) path:

let modalImageHeight = Math.min(MODAL_HEIGHT, zoomHeight);  // Math.min(568, 0) = 0
let width = (zoomWidth / zoomHeight) * modalImageHeight;     // (0 / 0) * 0 = NaN

When the image has no saved width/height, zoomSize is initialized to [0, 0] in image.tsx:42-44 (backgroundImage.width || 0, backgroundImage.height || 0). This means zoomHeight = 0 and zoomWidth = 0, yielding modalImageHeight = 0 and width = NaN.

Why this PR introduced it

Before this PR, there was an early return guard that checked !backgroundImage.height || !backgroundImage.width || !backgroundImage.url. If the image had no saved dimensions, the component returned null and never reached the dimension calculation. This PR correctly removed the height/width checks from the guard (to allow images without saved dimensions to display), and the scaleFF path was updated with a proper fallback (lines 72-77 set width = undefined and modalImageHeight = undefined when dimensions are missing). However, the non-scaleFF path at lines 52-58 was not given the same fallback treatment.

Step-by-step proof

1. Content has an image with no saved width/height but has a url and longDescription.
2. image.tsx:42-44 initializes zoomSize to [0, 0].
3. useEffect at line 68 fires getImageSizeModern() asynchronously.
4. Before the async resolution completes, or if getImageSizeModern rejects (note: there is no .catch() handler at line 75), zoomSize remains [0, 0].
5. If the user opens the Explore Image modal during this window, ExploreImageModalContent receives zoomSize = [0, 0].
6. Line 52: modalImageHeight = Math.min(568, 0) = 0.
7. Line 58: width = (0 / 0) * 0 = NaN.
8. These are passed to SvgImage as height={0} and width={NaN}, resulting in an invisible image.

Practical impact and addressing the refutation

One verifier refuted this bug, arguing the scenario cannot occur because getImageSizeModern resolves before the user can click. This is largely correct for the happy path: the image is typically cached from the initial display, so async resolution is near-instant. However, there are two edge cases: (1) if the image load is slow or fails, there is no .catch() on the promise at image.tsx:75, so zoomSize stays [0, 0] permanently; (2) it is a transient state that exists between initial render and async resolution. Additionally, the non-scaleFF path is legacy code marked for removal (TODO LEMS-3912), further reducing the practical impact.

How to fix

Add the same fallback used in the scaleFF path. Before the if (scaleFF) block, add a guard:

if (!zoomHeight || !zoomWidth) {
    width = undefined;
    modalImageHeight = undefined;
}

This lets the CSS max-width/max-height rules (newly added in this PR) handle the sizing naturally, consistent with the scaleFF approach.

[nishasy]

In image.tsx, the zoomSize is determined in a useEffect on load and then passed down into ImageInfoArea => ExploreImageModal => ExploreImageModalContent. So it would never actually be 0 in practice.

[nishasy]

Plus I'd prefer to avoid changing the non-flag code for now. We haven't had issues in production code, so there's no need to update this yet.

[catandthemachines]

I'm not familiar with this state. Could you explain a little more on the case where we would expect this? This seems like a state we should ward against.

[nishasy]

I don't think it's actually possible to ever reach this case.

[catandthemachines]

Approved, thank you!