feat(core): add XDSLightbox component by czarandy · Pull Request #2298 · facebook/astryx

czarandy · 2026-05-21T20:14:18Z

Summary

New XDSLightbox component — a fullscreen overlay for viewing images and videos at full resolution.

Single media mode: src, alt, caption, type props
Gallery mode: images[], index, onIndexChange with prev/next buttons and arrow key navigation
Video support: type='video' renders <video> with native controls; zoom/pan disabled for video
Zoom: opt-in via hasZoom (images only) — double-click toggles 1x/2x, drag to pan when zoomed
Built on native <dialog> with showModal() for focus trapping and top-layer
Controls use XDSIconButton with <XDSIcon>, white via --color-on-dark token
Caption hugs the media, gallery counter at top-left
Accessible: aria-label, keyboard navigation, focus restore on close
Exports: XDSLightbox, XDSLightboxProps, XDSLightboxImage, XDSLightboxMediaType

Test plan

17 unit tests pass (dialog, single image, caption, gallery nav, arrow keys, ref forwarding)
No type errors from tsc --noEmit
Pre-commit hooks pass (lint, sync check, package boundaries)
Verify single image in Storybook (Default, WithCaption stories)
Verify gallery navigation (Gallery story)
Verify zoom behavior (WithZoom story — double-click to zoom, drag to pan)
Verify video playback with native controls

vercel · 2026-05-21T20:14:25Z

@czarandy must be a member of the Meta Open Source team on Vercel to deploy.
- Click here to add @czarandy to the team.
- If you initiated this build, request access.

Learn more about collaboration on Vercel and other options here.

vercel · 2026-05-21T20:21:17Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
xds-sandbox	Error		May 24, 2026 6:27am

github-actions · 2026-05-21T20:32:51Z

PR Analysis Report

📚 Storybook Preview

View Storybook for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

🧪 Sandbox Preview

View Sandbox for this PR
GitHub Pages may take up to a minute to hydrate after deploy.

No new or modified components detected.

Bundle Size Summary

Package	Size (ESM)	Size (CJS)	Gzipped
@xds/core	20.8KB	32.1KB	4.7KB

Accessibility Audit

Status: No accessibility violations detected.

_{Generated by PR Enrichment workflow | Storybook | Sandbox | View full report}

cixzhang

The API is clean and the implementation is solid, but this needs to go through the full specification protocol before merging. Issue #1198 says "Specification protocol in progress" but it was never completed.

Specifically:

External research + use case analysis — need a proper survey of Fancybox, PhotoSwipe, Radix Dialog patterns, etc. and a decision matrix. The current API is reasonable but decisions need to be grounded.
Vibe tests — especially around the media single-vs-array overload. Does an AI naturally reach for media={{src, alt}} vs media={[{src, alt}]}? Does it correctly wire index/onIndexChange for galleries?
Missing slots — real-world lightboxes need toolbar actions (download, share, open in tab). The spec should surface this and decide on a slot/render prop pattern. Also caption should be ReactNode not just string.
Trigger pattern — XDSDialog uses useXDSDialog hook with a trigger ref. Lightbox should match: useXDSLightbox returning trigger props + state, consistent with the dialog family.
Video autoPlay — currently hardcoded to true. Should be hasAutoPlay defaulting to false per boolean conventions.

The code quality and conventions compliance are good — this is purely about running the spec protocol to validate the API surface before shipping.

czarandy · 2026-05-22T04:47:54Z

I did look at Fancybox, PhotoSwipe and Lightbox2 to base this version on. I'm not going to do the "decision matrix" or whatever.

real-world lightboxes need toolbar actions (download, share, open in tab).
seems not typical, I don't see that in other examples

XDSDialog uses useXDSDialog hook with a trigger ref. Lightbox should match: useXDSLightbox returning trigger props + state, consistent with the dialog family.
I see no reason to have a hook, that seems like not something that would come up. Lightbox is simple: it's controlled by isOpen/onOpenChange and doesn't need trigger positioning since it's a full screen overlay.

czarandy · 2026-05-22T04:48:26Z

⏺ ## Lightbox Vibe Test Results

All 3 Lightbox vibe tests completed.

Test	Result	Media prop	Index wiring	Escape hatches
fwc-12 (single image)	Pass	Array (not single object)	Yes	None
fwc-13 (gallery)	Pass	Array	Yes	None
fwc-14 (mixed media)	Pass	Array w/ `type: 'video'`	Yes	Inline styles on thumbnail grid

Key findings

The API is intuitive — all 3 tests correctly used XDSLightbox with zero escape hatches for the core viewer functionality. Nobody tried to build a custom
overlay/dialog.
Array form is the natural default — even fwc-12 (single image) used the array form with index/onIndexChange instead of media={{src, alt}}. The single-object
shorthand isn't being discovered. If you want people to use it, the doc should lead with the single-object example and explicitly call out "for a single image, pass an
object directly."
hasZoom and type: 'video' discovered correctly — fwc-14 found both without issues.
Minor escape hatch — fwc-14 used inline styles for the thumbnail grid cards instead of StyleX, but that's a general pattern issue, not Lightbox-specific.

czarandy · 2026-05-22T04:49:10Z

The single-object shorthand isn't being discovered.

This is probably fine, we don't really care that much which version gets used, it's just in case.

cixzhang · 2026-05-22T05:00:12Z

Imperative hook form is pretty typical for our layers. It's not about trigger positioning but rather so we have a way to open layers from things like menus where the items might unmount because the menu closes after showing the layer

cixzhang · 2026-05-22T05:12:49Z

+}
+
+export const Default: Story = {
+  render: () => <SingleImageDemo />,


For these storybook examples it would be ideal to render them directly in the render methods instead of wrapping in a separate component because this obfuscates the code examples

Fullscreen overlay for viewing images and videos at full resolution. - Unified media prop: single object or array for gallery mode - Video support: type='video' renders <video> with native controls - Gallery mode: prev/next buttons and arrow key navigation - Zoom: opt-in via hasZoom (images only), double-click toggles 1x/2x, drag to pan - Built on native <dialog> with showModal() for focus trapping - Controls use XDSIconButton with XDSIcon (close, chevronLeft/Right) - Dark backdrop, white controls via --color-on-dark token - Caption hugs media, gallery counter at top-left - Accessible: aria-label, keyboard nav, focus restore on close - Exports: XDSLightbox, XDSLightboxProps, XDSLightboxMedia, XDSLightboxMediaType

czarandy · 2026-05-24T06:27:33Z

Added useXDSLightbox hook + fix the other comments

github-actions · 2026-05-24T06:32:36Z

🚀 Vercel Preview Deployment


Status	✅ Deployed
Preview	Open Preview
Commit	`f934473`
Inspect	Vercel Dashboard
Workflow	View Logs

No authentication required — anyone with the link can view the preview.

Fullscreen overlay for viewing images and videos at full resolution. - Unified media prop: single object or array for gallery mode - Video support: type='video' renders <video> with native controls - Gallery mode: prev/next buttons and arrow key navigation - Zoom: opt-in via hasZoom (images only), double-click toggles 1x/2x, drag to pan - Built on native <dialog> with showModal() for focus trapping - Controls use XDSIconButton with XDSIcon (close, chevronLeft/Right) - Dark backdrop, white controls via --color-on-dark token - Caption hugs media, gallery counter at top-left - Accessible: aria-label, keyboard nav, focus restore on close - Exports: XDSLightbox, XDSLightboxProps, XDSLightboxMedia, XDSLightboxMediaType

czarandy requested review from cixzhang and josephfarina as code owners May 21, 2026 20:14

meta-cla Bot added the CLA Signed This label is managed by the Meta Open Source bot. label May 21, 2026

czarandy force-pushed the worktree-XDSLightbox branch from b289152 to f417df3 Compare May 21, 2026 20:21

vercel Bot had a problem deploying to Preview May 21, 2026 20:21 Failure

czarandy mentioned this pull request May 21, 2026

feat: XDSLightbox + useFileUpload — media viewer and file input primitives #1198

Closed

cixzhang requested changes May 21, 2026

View reviewed changes

czarandy force-pushed the worktree-XDSLightbox branch from f417df3 to 249f0eb Compare May 22, 2026 04:12

vercel Bot had a problem deploying to Preview May 22, 2026 04:12 Failure

czarandy force-pushed the worktree-XDSLightbox branch from 249f0eb to 495bc47 Compare May 22, 2026 04:37

vercel Bot had a problem deploying to Preview May 22, 2026 04:37 Failure

czarandy force-pushed the worktree-XDSLightbox branch from 495bc47 to 9a6fa09 Compare May 22, 2026 04:48

czarandy requested a review from cixzhang May 22, 2026 04:48

vercel Bot had a problem deploying to Preview May 22, 2026 04:48 Failure

cixzhang requested changes May 22, 2026

View reviewed changes

czarandy force-pushed the worktree-XDSLightbox branch from 9a6fa09 to f934473 Compare May 24, 2026 06:27

vercel Bot had a problem deploying to Preview May 24, 2026 06:27 Failure

czarandy requested a review from cixzhang May 24, 2026 06:27

cixzhang approved these changes May 25, 2026

View reviewed changes

czarandy merged commit f0ab019 into main May 26, 2026
21 of 22 checks passed

czarandy deleted the worktree-XDSLightbox branch May 26, 2026 01:55

Navigation Menu

Uh oh!

feat(core): add XDSLightbox component - #2298

feat(core): add XDSLightbox component#2298
czarandy merged 1 commit into
mainfrom
worktree-XDSLightbox

czarandy commented May 21, 2026 •

edited

Loading

Uh oh!

vercel Bot commented May 21, 2026

Uh oh!

vercel Bot commented May 21, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented May 21, 2026 •

edited

Loading

Uh oh!

cixzhang left a comment

Uh oh!

czarandy commented May 22, 2026

Uh oh!

czarandy commented May 22, 2026

Uh oh!

czarandy commented May 22, 2026

Uh oh!

cixzhang commented May 22, 2026

Uh oh!

Uh oh!

Uh oh!

cixzhang May 22, 2026

Uh oh!

czarandy commented May 24, 2026

Uh oh!

github-actions Bot commented May 24, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

czarandy commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

vercel Bot commented May 21, 2026

Uh oh!

vercel Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented May 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR Analysis Report

📚 Storybook Preview

🧪 Sandbox Preview

Bundle Size Summary

Accessibility Audit

Uh oh!

cixzhang left a comment

Choose a reason for hiding this comment

Uh oh!

czarandy commented May 22, 2026

Uh oh!

czarandy commented May 22, 2026

Key findings

Uh oh!

czarandy commented May 22, 2026

Uh oh!

cixzhang commented May 22, 2026

Uh oh!

Uh oh!

Uh oh!

cixzhang May 22, 2026

Choose a reason for hiding this comment

Uh oh!

czarandy commented May 24, 2026

Uh oh!

github-actions Bot commented May 24, 2026

🚀 Vercel Preview Deployment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

czarandy commented May 21, 2026 •

edited

Loading

vercel Bot commented May 21, 2026 •

edited

Loading

github-actions Bot commented May 21, 2026 •

edited

Loading