@estiva-app/ui 0.25.0 → 0.26.0

package/src/AttachmentCard.tsx

@@ -1,4 +1,4 @@
-import { useLayoutEffect, useRef, useState, type ComponentPropsWithRef, type FC } from 'react'
+import { useEffect, useLayoutEffect, useRef, useState, type ComponentPropsWithRef, type FC } from 'react'
 import { Button as BaseButton } from '@base-ui/react/button'
 import {
   IconAlertCircle,
@@ -19,6 +19,7 @@ import {
 } from '@tabler/icons-react'
 import { Card } from './Card'
 import { IconButton } from './IconButton'
+import { Lightbox } from './Lightbox'
 import { Link } from './Link'
 import { WithTooltip, type WithTooltipProps } from './Tooltip'
 import { cn } from './cn'
@@ -29,10 +30,17 @@ import { cn } from './cn'
  * Peek's two attachment components, class for class (UIG-27, Katerina's ruling
  * of 14 September that both apps draw one): `FileAttachmentCard`, the card on
  * something already posted, and `PendingAttachmentChip`, the card in a composer
- * waiting to go. What stays in each app is what only the app can do: fetch the
- * bytes with the reader's own permission, open an image full screen, save a
- * file. The card is told the result — a `src`, an `href`, a `state` — and hands
- * a click back through `onOpen`, `onDownload` and `onRemove`.
+ * waiting to go. The card is told the result — a `src`, an `href`, a `state` —
+ * and hands a click back through `onOpen`, `onDownload` and `onRemove`.
+ *
+ * **It now does the rest of the job too** (UIG-35, Katerina 20 September):
+ * given a `remoteSrc` and the app's `fetchImage`, it fetches a file the reader
+ * needs permission for and draws the wait and the refusal; it opens a picture
+ * full screen in the package's `Lightbox`; and with `download` it saves the
+ * file. Peek and Ship had each written those three around it, 174 and 181 lines
+ * that did the same things differently — Ship's pictures never opened at all.
+ * What stays an app's is the one thing only it knows: how to fetch with its own
+ * authorization.
  *
  * Two shapes, decided by the file: an **image** with a picture is a 180px
  * thumbnail you can open; anything else is a 240px **row** — a type tile, the
@@ -144,10 +152,45 @@ export interface AttachmentCardProps extends Omit<ComponentPropsWithRef<'div'>,
   href?: string
   /** The picture an image card draws. Without it an image is drawn as a row. */
   src?: string
-  /** What a click on an image's picture does — the app's full-screen view. */
+  /**
+   * What the picture shows, where the sender said — Ship carries one on every
+   * `imeta`. It is what a screen reader reads and what the viewer is named
+   * with; `name` is still the file's name, under the thumbnail. Without it the
+   * name does both jobs.
+   */
+  alt?: string
+  /**
+   * A file the app has to *fetch* before it can be used — one on a relay, where
+   * reading it needs the reader's own authorization (UIG-35). Give `fetchImage`
+   * with it. For a picture the card waits, draws it, and says so if it cannot
+   * be read, so no app writes that state machine again; for a document the
+   * result is where the row opens, and until it lands the row is dimmed rather
+   * than pretending to open. Ignored when `src` is set.
+   */
+  remoteSrc?: string
+  /**
+   * The full-size picture, fetched only when someone opens it. A thread of
+   * screenshots would otherwise pull every original at full size to draw them
+   * at 112px. Until it arrives the viewer shows the thumbnail.
+   */
+  remoteFullSrc?: string
+  /** How this app fetches a picture it is allowed to read: a URL in, a URL the
+   *  browser can draw out (an object URL, usually). */
+  fetchImage?: (url: string) => Promise<string>
+  /**
+   * What a click on an image's picture does. Without it the card **opens the
+   * picture itself**, full screen, in the package's `Lightbox` — which is what
+   * both apps wanted and one of them had written by hand.
+   */
   onOpen?: () => void
   /** Shows a download control on hover or focus, and calls this. */
   onDownload?: () => void
+  /**
+   * Shows the download control and **saves the file itself**, under `name`:
+   * the original where there is one (`remoteFullSrc`), otherwise what the card
+   * is drawing. Use `onDownload` instead when the app must do it another way.
+   */
+  download?: boolean
   /** Waiting to be sent: the composer's 200px row, with a remove control on its corner. */
   pending?: boolean
   /** Removes a pending card. */
@@ -163,14 +206,89 @@ export interface AttachmentCardProps extends Omit<ComponentPropsWithRef<'div'>,
   noteHint?: string
 }
 
+/**
+ * A picture that has to be fetched before it can be drawn.
+ *
+ * The result remembers which URL it is *about*, so an answer about a file this
+ * card is no longer showing is ignored during render rather than erased in an
+ * effect afterwards — setting state synchronously in an effect is a second
+ * render every time the card is handed a different file. Peek and Ship had
+ * written this hook once each; it lives here now (UIG-35).
+ */
+function useRemoteImage(url: string | undefined, fetchImage?: (url: string) => Promise<string>) {
+  const [result, setResult] = useState<{ for?: string; src?: string; failed?: boolean }>({})
+  // The fetcher is an app's function and is usually written inline, so it is
+  // read through a ref: a new identity on every render must not re-fetch.
+  const fetcher = useRef(fetchImage)
+  fetcher.current = fetchImage
+  useEffect(() => {
+    if (!url || !fetcher.current) return
+    let live = true
+    fetcher.current(url).then(
+      (src) => {
+        if (live) setResult({ for: url, src })
+      },
+      () => {
+        if (live) setResult({ for: url, failed: true })
+      },
+    )
+    return () => {
+      live = false
+    }
+  }, [url])
+  const current = result.for === url
+  return { src: current ? result.src : undefined, failed: current ? !!result.failed : false }
+}
+
+/** Save a file under its own name: its bytes' object URL, handed to a
+ *  temporary `<a download>`. Falls back to opening it when the fetch is
+ *  refused — a cross-origin file the browser will not hand over. */
+async function saveFile(source: string, name: string): Promise<void> {
+  /*
+    Bytes already in hand — an object URL from the app's own fetch, or a data
+    URL — go straight to the anchor. Fetching them again would ask the browser
+    to re-read a blob it is already holding, and `fetch` on a `blob:` URL is
+    exactly what a jsdom test cannot do either.
+  */
+  if (source.startsWith('blob:') || source.startsWith('data:')) {
+    handToAnchor(source, name)
+    return
+  }
+  try {
+    const res = await fetch(source)
+    if (!res.ok) throw new Error(String(res.status))
+    const objectUrl = URL.createObjectURL(await res.blob())
+    handToAnchor(objectUrl, name)
+    URL.revokeObjectURL(objectUrl)
+  } catch {
+    // A file the browser will not hand over is opened instead, which is the
+    // only other thing a person can do with it.
+    window.open(source, '_blank', 'noopener')
+  }
+}
+
+function handToAnchor(url: string, name: string) {
+  const a = document.createElement('a')
+  a.href = url
+  a.download = name
+  document.body.appendChild(a)
+  a.click()
+  a.remove()
+}
+
 export function AttachmentCard({
   name,
   size,
   contentType,
   href,
   src,
+  alt,
+  remoteSrc,
+  remoteFullSrc,
+  fetchImage,
   onOpen,
   onDownload,
+  download = false,
   pending = false,
   onRemove,
   state = 'ready',
@@ -182,6 +300,60 @@ export function AttachmentCard({
   const image = isImage(name, contentType)
   const sizeText = size === undefined ? '' : formatBytes(size)
 
+  /*
+    The picture, and the state that goes with fetching one. A `src` the app
+    already has needs none of this; `remoteSrc` is the case where reading the
+    file is a request, with a wait and a way to fail.
+  */
+  const remote = useRemoteImage(src ? undefined : remoteSrc, fetchImage)
+  const picture = image ? (src ?? remote.src) : undefined
+  const fetching = !src && !!remoteSrc && !!fetchImage
+  /*
+    The wait and the refusal are drawn for a **picture**. A document that has to
+    be fetched keeps the row it always had and simply has nowhere to open yet:
+    its name, its type and its size are already on screen and are what the
+    reader is looking at, where an image without its bytes is a blank card.
+  */
+  const drawnState: AttachmentCardState =
+    state !== 'ready' ? state : image && fetching ? (remote.failed ? 'unreadable' : picture ? 'ready' : 'loading') : state
+  // Where a document opens: what the app passed, or the bytes it fetched.
+  const address = href ?? (!image && fetching ? remote.src : undefined)
+
+  // Full screen. The original is fetched only once somebody opens it, and the
+  // thumbnail stands in until it arrives: a moment of a smaller picture beats a
+  // moment of an empty screen.
+  const [opened, setOpened] = useState(false)
+  const full = useRemoteImage(opened ? remoteFullSrc : undefined, fetchImage)
+  const openable = image && !!picture && !pending
+  const openPicture = onOpen ?? (openable ? () => setOpened(true) : undefined)
+  const viewer =
+    opened && picture ? <Lightbox src={full.src ?? picture} alt={alt ?? name} onClose={() => setOpened(false)} /> : null
+
+  /*
+    Saving. `download` is the card doing it, which is what both apps were doing
+    around it; `onDownload` stays for an app that must do it another way. The
+    original is saved where there is one — never the thumbnail on screen — and
+    it is fetched here rather than reusing the viewer's copy, so a file can be
+    saved without ever being opened.
+  */
+  const saveHere = download
+    ? () => {
+        const source = remoteFullSrc ?? remoteSrc
+        if (source && fetchImage) {
+          void fetchImage(source).then(
+            (resolved) => saveFile(resolved, name),
+            // Without this a refused read is an unhandled rejection in the page
+            // rather than a download that did not happen.
+            () => {},
+          )
+          return
+        }
+        const local = address ?? picture
+        if (local) void saveFile(local, name)
+      }
+    : undefined
+  const saving = onDownload ?? saveHere
+
   if (pending) {
     const failed = state === 'failed'
     const warning = state === 'warning'
@@ -236,7 +408,7 @@ export function AttachmentCard({
   }
 
   // Fades in with the card's hover or keyboard focus, and keeps its slot when hidden, so revealing it never shifts the row.
-  const download = onDownload ? (
+  const downloadControl = saving ? (
     // @estiva-escape: Download shows when its card is pointed at or focused, AttachmentCard's own action; IconButton has no reveal on its card's hover (UIG-9, Katerina 17 September)
     <IconButton
       variant="muted"
@@ -245,14 +417,14 @@ export function AttachmentCard({
       className="opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 focus-visible:opacity-100 transition-opacity"
       onClick={(event) => {
         event.stopPropagation()
-        onDownload()
+        saving()
       }}
     >
       <IconDownload size={16} stroke={1.5} />
     </IconButton>
   ) : null
 
-  if (state === 'loading') {
+  if (drawnState === 'loading') {
     return (
       // `role="status"`: a plain box may not carry a name (axe, aria-prohibited-attr), and a
       // status says what it is doing — loading — to a reader that cannot see the pulse.
@@ -263,7 +435,7 @@ export function AttachmentCard({
     )
   }
 
-  if (state === 'unreadable') {
+  if (drawnState === 'unreadable') {
     return (
       // @estiva-escape: a file that could not be read is faded as well as dashed, AttachmentCard's own state; Card has no faded state (UIG-9, Katerina 17 September)
       <Card fill="inset" unreadable className={cn('flex items-center gap-2 w-[240px] p-1.5 opacity-70', className)} {...props}>
@@ -278,30 +450,33 @@ export function AttachmentCard({
     )
   }
 
-  if (image && src) {
-    const picture = <img src={src} alt={name} className="w-full h-28 object-cover" />
+  if (image && picture) {
+    const thumbnail = <img src={picture} alt={alt ?? name} className="w-full h-28 object-cover" />
     return (
-      <Card fill="inset" hover="hairline" clip className={cn('group relative flex flex-col w-[180px]', className)} {...props}>
-        {onOpen ? (
-          <BaseButton
-            type="button"
-            className="block w-full"
-            aria-label={`Preview ${name}`}
-            onClick={(event) => {
-              event.stopPropagation()
-              onOpen()
-            }}
-          >
-            {picture}
-          </BaseButton>
-        ) : (
-          <div className="block w-full">{picture}</div>
-        )}
-        <div className="flex items-center gap-1 pl-2 pr-1 py-1 min-w-0">
-          <Truncating text={name} className="flex-1 text-caption text-text-primary truncate" wrapperClassName="flex-1" />
-          {download}
-        </div>
-      </Card>
+      <>
+        <Card fill="inset" hover="hairline" clip className={cn('group relative flex flex-col w-[180px]', className)} {...props}>
+          {openPicture ? (
+            <BaseButton
+              type="button"
+              className="block w-full"
+              aria-label={`Preview ${name}`}
+              onClick={(event) => {
+                event.stopPropagation()
+                openPicture()
+              }}
+            >
+              {thumbnail}
+            </BaseButton>
+          ) : (
+            <div className="block w-full">{thumbnail}</div>
+          )}
+          <div className="flex items-center gap-1 pl-2 pr-1 py-1 min-w-0">
+            <Truncating text={name} className="flex-1 text-caption text-text-primary truncate" wrapperClassName="flex-1" />
+            {downloadControl}
+          </div>
+        </Card>
+        {viewer}
+      </>
     )
   }
 
@@ -318,15 +493,15 @@ export function AttachmentCard({
   )
   return (
     // @estiva-escape: a file that cannot be opened is faded, AttachmentCard's own state; Card has no faded state (UIG-9, Katerina 17 September)
-    <Card fill="inset" hover={href ? 'hairline' : 'none'} className={cn('group flex items-center gap-2 w-[240px] p-1.5 pr-1', !href && 'opacity-70', className)} {...props}>
-      {href ? (
-        <Link href={href} external variant="plain" className="flex items-center gap-2 min-w-0 flex-1" onClick={(event) => event.stopPropagation()}>
+    <Card fill="inset" hover={address ? 'hairline' : 'none'} className={cn('group flex items-center gap-2 w-[240px] p-1.5 pr-1', !address && 'opacity-70', className)} {...props}>
+      {address ? (
+        <Link href={address} external variant="plain" className="flex items-center gap-2 min-w-0 flex-1" onClick={(event) => event.stopPropagation()}>
           {body}
         </Link>
       ) : (
         <div className="flex items-center gap-2 min-w-0 flex-1">{body}</div>
       )}
-      {download}
+      {downloadControl}
     </Card>
   )
 }

package/src/Lightbox.mdx

@@ -0,0 +1,71 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as LightboxStories from './Lightbox.stories'
+
+<Meta of={LightboxStories} />
+
+# Lightbox
+
+A picture, full screen, on a scrim — what a thumbnail opens into. Built on
+Base UI's `Dialog`, like DialogShell.
+
+<Canvas of={LightboxStories.APicture} />
+
+## When
+
+- Somebody presses a picture that is cropped or scaled down where it sits — a
+  screenshot on a message, a photo in a thread — and wants to see the whole of
+  it.
+- **AttachmentCard opens one by itself**, so an image attachment needs nothing
+  here: this is for a picture that is not an attachment card.
+
+## When not
+
+- Anything that is not a picture → **DialogShell**.
+- A picture small enough to read where it is — don't; an overlay that shows the
+  same thing at the same size is a click that did nothing.
+- A gallery of several pictures with next and previous. This shows one. Ask for
+  the part rather than building the arrows around it.
+
+## How
+
+```tsx
+import { Lightbox } from '@estiva-app/ui'
+
+{opened && <Lightbox src={pictureUrl} alt={name} onClose={() => setOpened(false)} />}
+```
+
+- It is mounted while it is open: there is no `open` prop, and a caller renders
+  it or does not — DialogShell's rule.
+- **Swapping `src` swaps the picture**, with no flash of nothing. That is how a
+  thumbnail stands in while the original is still being fetched.
+- The picture is contained: as large as the screen allows, never cropped, never
+  stretched.
+- `alt` names the picture, and names the viewer itself to assistive technology.
+
+## What it owns
+
+It does these by itself. Write none of them around it.
+
+| It does | So you never write | Refused when written by hand |
+|---|---|---|
+| Floats on top of the page, over its own scrim | a portal, a fixed layer, a `z-index` to win | ✓ |
+| Takes its keys by itself — Escape closes it | a `keydown` listener on the page | ✓ |
+| Holds focus inside while open, and gives it back to whatever opened it | focus code, Tab compared by hand | ✓ |
+| Stops the page behind it scrolling | `overflow` written onto the body | ✓ |
+| Closes on a press on the scrim, and **not** on a press on the picture | a click handler that tests the target |  |
+| Carries its own close button, sized to be findable on a photograph | an IconButton on a corner |  |
+
+## Keys
+
+| Input | What happens |
+|---|---|
+| Escape | closes |
+| scrim click | closes |
+| picture click | nothing — clicking what you opened should not close it |
+| close button | closes |
+| Tab / Shift+Tab | stays inside the viewer |
+| on close | focus returns to the picture that opened it |
+
+## Props
+
+<Controls of={LightboxStories.APicture} />

package/src/Lightbox.stories.tsx

@@ -0,0 +1,72 @@
+import { useState } from 'react'
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { Button } from './Button'
+import { Lightbox } from './Lightbox'
+
+/** A drawn picture rather than a photograph, so the story needs no network. */
+const svg = (w: number, h: number, body: string) =>
+  `data:image/svg+xml;utf8,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}"><rect width="${w}" height="${h}" fill="#0f1720"/>${body}</svg>`,
+  )}`
+
+const WIDE = svg(
+  960,
+  540,
+  `<circle cx="240" cy="180" r="104" fill="#56c8ff"/><rect x="392" y="300" width="440" height="140" rx="24" fill="#4ade8c"/>`,
+)
+
+const TALL = svg(
+  540,
+  960,
+  `<rect x="80" y="120" width="380" height="380" rx="32" fill="#b18cff"/><circle cx="270" cy="740" r="140" fill="#ffc94d"/>`,
+)
+
+const meta = {
+  title: 'Overlays/Lightbox',
+  component: Lightbox,
+  parameters: {
+    layout: 'fullscreen',
+    // Portals a full-screen overlay to document.body — render in an iframe on
+    // the Docs page so it does not cover the docs.
+    docs: { story: { inline: false, height: '520px' } },
+  },
+  args: {
+    src: WIDE,
+    alt: 'checkout-flow.png',
+    onClose: () => {},
+  },
+} satisfies Meta<typeof Lightbox>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/**
+ * A wide picture, as large as the screen allows and never larger: it is
+ * contained, so nothing is cropped and nothing is stretched.
+ */
+export const APicture: Story = {}
+
+/** A tall one in the same viewer — the height is what runs out first. */
+export const ATallPicture: Story = { args: { src: TALL, alt: 'signup-screen.png' } }
+
+/**
+ * **Open it and close it**, which is the whole point of the part.
+ *
+ * Escape closes it, so does the ✕ and so does a press on the scrim — a press on
+ * the picture does not. Focus is trapped while it is open and returns to the
+ * button that opened it, which is what neither hand-built viewer did.
+ */
+export const OpenAndClose: Story = {
+  parameters: { controls: { disable: true } },
+  render: (args) => {
+    const [open, setOpen] = useState(false)
+    return (
+      <div className="flex h-screen items-center justify-center">
+        <Button variant="primary" onClick={() => setOpen(true)}>
+          Open the picture
+        </Button>
+        {open && <Lightbox {...args} onClose={() => setOpen(false)} />}
+      </div>
+    )
+  },
+}

package/src/Lightbox.test.tsx

@@ -0,0 +1,65 @@
+// @vitest-environment jsdom
+/**
+ * What the Lightbox page claims, pinned: it floats over the page on its own
+ * scrim, it names itself, Escape closes it, a press on the scrim closes it and
+ * a press on the picture does not, and the close button closes it.
+ *
+ * The behaviours the two hand-built viewers never had are Base UI's, so what
+ * is tested here is that this part is wired to them — not Base UI itself.
+ */
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { Lightbox } from './Lightbox'
+
+afterEach(cleanup)
+
+const PICTURE = 'data:image/svg+xml;utf8,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%2F%3E'
+
+describe('Lightbox', () => {
+  it('floats over the page: it portals out of its parent, and carries the strong scrim', () => {
+    const { container } = render(<Lightbox src={PICTURE} alt="checkout-flow.png" onClose={() => {}} />)
+    // Nothing is left where it was written.
+    expect(container.firstElementChild).toBeNull()
+    const picture = screen.getByAltText('checkout-flow.png')
+    expect(document.body.contains(picture)).toBe(true)
+    expect(document.querySelector('.bg-scrim-strong')).toBeTruthy()
+  })
+
+  it('names itself with the picture, so a reader is told what opened', () => {
+    render(<Lightbox src={PICTURE} alt="signup-screen.png" onClose={() => {}} />)
+    expect(screen.getByRole('dialog', { name: 'signup-screen.png' })).toBeTruthy()
+  })
+
+  it('Escape closes it', async () => {
+    const onClose = vi.fn()
+    render(<Lightbox src={PICTURE} alt="a.png" onClose={onClose} />)
+    await userEvent.keyboard('{Escape}')
+    expect(onClose).toHaveBeenCalled()
+  })
+
+  it('the close button closes it', async () => {
+    const onClose = vi.fn()
+    render(<Lightbox src={PICTURE} alt="a.png" onClose={onClose} />)
+    await userEvent.click(screen.getByRole('button', { name: 'Close' }))
+    expect(onClose).toHaveBeenCalled()
+  })
+
+  it('a press on the scrim closes it; a press on the picture does not', async () => {
+    const onClose = vi.fn()
+    render(<Lightbox src={PICTURE} alt="a.png" onClose={onClose} />)
+
+    await userEvent.click(screen.getByAltText('a.png'))
+    expect(onClose).not.toHaveBeenCalled()
+
+    await userEvent.click(screen.getByRole('dialog'))
+    expect(onClose).toHaveBeenCalledTimes(1)
+  })
+
+  it('swapping the picture swaps what is on screen — a thumbnail, then the original', () => {
+    const { rerender } = render(<Lightbox src={PICTURE} alt="a.png" onClose={() => {}} />)
+    expect(screen.getByAltText('a.png').getAttribute('src')).toBe(PICTURE)
+    rerender(<Lightbox src="blob:original" alt="a.png" onClose={() => {}} />)
+    expect(screen.getByAltText('a.png').getAttribute('src')).toBe('blob:original')
+  })
+})

package/src/Lightbox.tsx

@@ -0,0 +1,87 @@
+import { useRef } from 'react'
+import { Dialog } from '@base-ui/react/dialog'
+import { IconX } from '@tabler/icons-react'
+import { cn } from './cn'
+
+/**
+ * A picture, full screen, on a scrim — the thing a thumbnail opens into.
+ *
+ * Both apps had written this by hand and neither had got it right: Peek's
+ * `ImageLightbox` and the `FrameLightbox` before it were `createPortal` plus a
+ * fixed `<div>`, with no Escape, no focus trap and nothing to return focus to
+ * (Peek scan F5, P4; migration B22, Katerina 10 September). Ship never had one
+ * at all, so a screenshot in an issue could not be looked at.
+ *
+ * On Base UI's `Dialog`, like `DialogShell`: the portal, the backdrop, Escape,
+ * the outside press and the focus trap are its, and what is written here is the
+ * picture, the scrim and the close button.
+ *
+ * **The close button is this component's own**, not an `IconButton`: a 26px
+ * square with no fill is hard to find on top of a photograph, which is why Peek
+ * had written an escape note beside its own. A 32px round button on an elevated
+ * fill with a hairline reads on any picture.
+ */
+export interface LightboxProps {
+  /** The picture to show. Swapping it — a thumbnail for the original, once it
+   *  arrives — swaps what is on screen, with no flash of nothing. */
+  src: string
+  /** What the picture is. Names the viewer for assistive tech too. */
+  alt: string
+  onClose: () => void
+  /** Extra classes on the picture itself. */
+  className?: string
+}
+
+export function Lightbox({ src, alt, onClose, className }: LightboxProps) {
+  const popupRef = useRef<HTMLDivElement>(null)
+  return (
+    <Dialog.Root
+      open
+      onOpenChange={(open) => {
+        if (!open) onClose()
+      }}
+    >
+      <Dialog.Portal>
+        <Dialog.Backdrop className="fixed inset-0 z-40 bg-scrim-strong" />
+        <Dialog.Popup
+          ref={popupRef}
+          /*
+            Focus the layer, not the ✕ — DialogShell's rule, for the same
+            reason: Base UI's default is the first tabbable element, which here
+            would open every picture with a ring drawn on its close button. The
+            trap is armed either way, and Tab reaches the ✕ first.
+          */
+          initialFocus={popupRef}
+          aria-label={alt}
+          /*
+            The popup IS the layer: a picture viewer has no card, so the popup
+            fills the screen and centres what it holds. `outline-none` because
+            it is a programmatic focus target rather than something tabbed to —
+            the same reason DialogShell gives.
+
+            A press anywhere on the layer closes it, which is what a full-screen
+            picture teaches people to expect. Base UI's outside-press cannot do
+            that here: there is no outside.
+          */
+          className="fixed inset-0 z-50 flex items-center justify-center p-8 outline-none"
+          onClick={onClose}
+        >
+          <img
+            src={src}
+            alt={alt}
+            /* The press on the picture is not a press on the scrim: clicking
+               the thing you opened should not close it. */
+            onClick={(e) => e.stopPropagation()}
+            className={cn('max-w-full max-h-full object-contain rounded-lg', className)}
+          />
+          <Dialog.Close
+            aria-label="Close"
+            className="absolute top-4 right-4 size-8 rounded-full bg-bg-elevated border border-border-strong flex items-center justify-center text-text-secondary hover:text-text-primary"
+          >
+            <IconX size={16} stroke={1.5} />
+          </Dialog.Close>
+        </Dialog.Popup>
+      </Dialog.Portal>
+    </Dialog.Root>
+  )
+}

package/src/eslint/no-rebuilt-behaviour.ts

@@ -190,7 +190,7 @@ export const OWNED_BEHAVIOURS: OwnedBehaviour[] = [
     id: 'portal',
     behaviour: 'Floats on top of the page',
     baseUi: ['Dialog', 'AlertDialog', 'Popover', 'Menu', 'Select', 'Combobox', 'Autocomplete', 'Tooltip', 'PreviewCard', 'Toast'],
-    owners: ['DialogShell', 'ConfirmDialog', 'CommandPalette', 'Popover', 'Menu', 'Select', 'ChipInput', 'Tooltip', 'PreviewCard', 'Toast'],
+    owners: ['DialogShell', 'ConfirmDialog', 'CommandPalette', 'Lightbox', 'Popover', 'Menu', 'Select', 'ChipInput', 'Tooltip', 'PreviewCard', 'Toast'],
     reads: 'createPortal, called, or imported and never called',
   },
   {
@@ -204,21 +204,21 @@ export const OWNED_BEHAVIOURS: OwnedBehaviour[] = [
     id: 'page-keys',
     behaviour: 'Takes its keys by itself',
     baseUi: ['Dialog', 'AlertDialog', 'Popover', 'Menu', 'Select', 'Combobox', 'Tooltip', 'PreviewCard', 'Toast'],
-    owners: ['DialogShell', 'Popover', 'Menu', 'Select', 'Tabs', 'Toolbar'],
+    owners: ['DialogShell', 'Lightbox', 'Popover', 'Menu', 'Select', 'Tabs', 'Toolbar'],
     reads: 'a keydown, keyup or keypress listener on window or document',
   },
   {
     id: 'focus',
     behaviour: 'Holds focus inside while open, and gives it back',
     baseUi: ['Dialog', 'AlertDialog', 'Popover', 'Menu', 'Select', 'Combobox'],
-    owners: ['DialogShell', 'CommandPalette'],
+    owners: ['DialogShell', 'CommandPalette', 'Lightbox'],
     reads: 'a focusin or focusout listener on window or document; the Tab key compared by hand',
   },
   {
     id: 'scroll-lock',
     behaviour: 'Stops the page behind it scrolling',
     baseUi: ['Dialog', 'AlertDialog'],
-    owners: ['DialogShell'],
+    owners: ['DialogShell', 'Lightbox'],
     reads: 'overflow written into the style of document.body or document.documentElement',
   },
   {