fix: prevent expandable image hydration mismatch

[qiancai]

Background

MDX wraps a Markdown image in <p>, while ExpandableImage previously rendered a block-level <div> at its root. The resulting <p><div>...</div></p> SSR markup is invalid, so browsers repair the DOM before React 17 hydrates it.

That tree mismatch can make later headings and code blocks associate with the wrong nodes, causing the issue as follows:

What changed

• New Features
  • Expanded images now open in a modal within the document content area.
  • Added close controls and Escape-key support for dismissing expanded images.
• Bug Fixes
  • Improved modal rendering to preserve valid image markup and surrounding content.
  • Refined image sizing, centering, spacing, and overflow behavior for a better viewing experience.

Before (the close icon is embedded in the graph):

After (the close icon is displayed as an independent icon):

• Tests
  • Added coverage for image expansion, modal structure, controls, and preserved attributes.

User impact

Documentation pages containing expandable images no longer corrupt later headings or code blocks during initial hydration. The expanded-image modal retains its styling, keeps the image centered with balanced spacing, and uses a smaller close icon positioned in the top-right reserved space without covering image content.

Validation

• pnpm exec jest gatsby/__tests__/expandable-image.test.tsx --runInBand --coverage=false
• Verified the compiled nested CSS contains the balanced image-modal spacing and close-button overrides in the correct cascade order.
• git diff --check
• The selected-page preview matched only dashboard/dashboard-ops-deploy.md; bundle compilation was stopped so the requester can continue the local build.
• The full Gatsby Jest suite still has unrelated existing TypeScript/configuration failures on upstream/master.

[coderabbitai]

📝 Walkthrough

Walkthrough

Changes

Expandable image modal

Layer / File(s)	Summary
Portal modal flow src/components/MDXComponents/ExpandableImage.tsx	ExpandableImage locates the nearest .PingCAP-Doc .doc-content container and renders ExpandableImageModal through a portal. Escape and close actions clear the container state.
Modal layout and sizing src/styles/docTemplate.css	The modal uses configurable padding, calculated height limits, centered flex content, smaller close controls, and bounded image sizing.
SSR structure validation gatsby/__tests__/expandable-image.test.tsx, package.json	SSR tests verify image nesting, preserved sibling elements, modal structure, accessibility attributes, and image attributes. The tests add parse5 and its type declarations.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Poem

I’m a rabbit with a modal to show,
Through the doc-content portal I go.
Close with Escape,
Keep images in place,
And test every HTML row.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: preventing hydration mismatches in expandable images.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[vercel]

@qiancai is attempting to deploy a commit to the test-vi Team on Vercel.

A member of the Team first needs to authorize it.

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

src/components/MDXComponents/ExpandableImage.tsx (1)

3-3: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Use the configured absolute import paths.

• src/components/MDXComponents/ExpandableImage.tsx#L3-L3: replace ./ExpandIcons with components/MDXComponents/ExpandIcons.
• gatsby/__tests__/expandable-image.test.tsx#L10-L13: replace ../../src/components/MDXComponents/ExpandableImage with components/MDXComponents/ExpandableImage.

As per coding guidelines, prefer absolute imports configured by tsconfig.json with baseUrl: "./src".

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/components/MDXComponents/ExpandableImage.tsx` at line 3, Update the
import in src/components/MDXComponents/ExpandableImage.tsx at lines 3-3 to use
the configured absolute components/MDXComponents/ExpandIcons path, and update
the import in gatsby/__tests__/expandable-image.test.tsx at lines 10-13 to use
components/MDXComponents/ExpandableImage instead of the relative path.

Source: Coding guidelines

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@src/components/MDXComponents/ExpandableImage.tsx`:
- Around line 15-35: Update the ExpandableImage trigger and modal flow to
support keyboard activation and focus management: make the trigger at the image
click handler keyboard-operable for Enter and Space, focus the close button when
the dialog opens, trap Tab navigation within the dialog, close on Escape, and
restore focus to the trigger on close. Add an accessible dialog name and tests
covering Enter, Space, Tab, Escape, and focus restoration.

In `@src/styles/docTemplate.css`:
- Around line 259-265: Update the --expandable-image-modal-body-max-height calc
expression to place each subtraction operator on the following line’s start or
otherwise avoid newlines immediately after “-”, satisfying
scss/operator-no-newline-after while preserving the existing height calculation.

---

Nitpick comments:
In `@src/components/MDXComponents/ExpandableImage.tsx`:
- Line 3: Update the import in src/components/MDXComponents/ExpandableImage.tsx
at lines 3-3 to use the configured absolute components/MDXComponents/ExpandIcons
path, and update the import in gatsby/__tests__/expandable-image.test.tsx at
lines 10-13 to use components/MDXComponents/ExpandableImage instead of the
relative path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 5db1ef87-8d75-49b3-ab17-5303163b2c6d

📥 Commits

Reviewing files that changed from the base of the PR and between d1e6619 and 5c54abd.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (4)

• gatsby/__tests__/expandable-image.test.tsx
• package.json
• src/components/MDXComponents/ExpandableImage.tsx
• src/styles/docTemplate.css