@linktr.ee/messaging-react 2.3.0-rc-1779427772 → 2.3.0

package/src/components/MessageAttachment/MessageAttachment.test.tsx

@@ -17,6 +17,21 @@ beforeEach(() => {
   mockTriggerDownload.mockClear()
 })
 
+// The viewer's `<dialog>` stays mounted across open/close so the
+// platform open / close transitions (via `@starting-style` +
+// `allow-discrete`) can play. That means we can't gate openness on
+// "is the dialog in the DOM" — we have to look at the `[open]`
+// attribute the platform sets on a `<dialog>` while it's visible.
+const expectViewerClosed = (testId: string) => {
+  const dialog = screen.queryByTestId(testId)
+  if (dialog) expect(dialog).not.toHaveAttribute('open')
+}
+const expectViewerOpen = (testId: string) => {
+  const dialog = screen.getByTestId(testId)
+  expect(dialog).toHaveAttribute('open')
+  return dialog
+}
+
 describe('MessageAttachment.Image', () => {
   it('renders an image bubble with caption', () => {
     renderWithProviders(
@@ -43,11 +58,11 @@ describe('MessageAttachment.Image', () => {
       />
     )
 
-    expect(screen.queryByTestId('image-viewer')).toBeNull()
+    expectViewerClosed('image-viewer')
 
     fireEvent.click(screen.getByLabelText('Open image 1 of 1'))
 
-    expect(screen.getByTestId('image-viewer')).toBeInTheDocument()
+    expectViewerOpen('image-viewer')
   })
 
   it('renders the dismiss button only on Composer state', () => {
@@ -81,6 +96,104 @@ describe('MessageAttachment.Image', () => {
     expect(screen.getByLabelText('Open image 3 of 3')).toBeInTheDocument()
   })
 
+  it('renders a download button inside the image viewer', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Received
+        src="https://cdn.example.com/photo.jpg"
+        alt="Photo"
+        filename="photo.jpg"
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open image 1 of 1'))
+    const viewer = expectViewerOpen('image-viewer')
+    // The viewer chrome carries its own download action — separate
+    // from any sibling download button on the bubble surface — so the
+    // user can grab the image without leaving the lightbox.
+    expect(
+      viewer.querySelector('button[aria-label="Download photo.jpg"]')
+    ).not.toBeNull()
+  })
+
+  it('does not render carousel nav controls for a single image', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Received
+        src="https://cdn.example.com/photo.jpg"
+        filename="photo.jpg"
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open image 1 of 1'))
+    expectViewerOpen('image-viewer')
+    expect(screen.queryByLabelText('Next image')).toBeNull()
+    expect(screen.queryByLabelText('Previous image')).toBeNull()
+  })
+
+  it('renders the stacked images as a carousel inside the viewer', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Sent
+        filename="album"
+        items={[
+          { src: 'https://cdn.example.com/a.jpg', alt: 'A' },
+          { src: 'https://cdn.example.com/b.jpg', alt: 'B' },
+          { src: 'https://cdn.example.com/c.jpg', alt: 'C' },
+        ]}
+      />
+    )
+
+    // Open the second tile — the viewer should land on image 2.
+    fireEvent.click(screen.getByLabelText('Open image 2 of 3'))
+    const viewer = expectViewerOpen('image-viewer')
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/b.jpg'
+    )
+    // Counter + nav chrome only appear on multi-item viewers.
+    expect(viewer.textContent).toContain('2 / 3')
+
+    // Next button advances by one.
+    fireEvent.click(screen.getByLabelText('Next image'))
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/c.jpg'
+    )
+    expect(viewer.textContent).toContain('3 / 3')
+
+    // Next wraps from the last item back to the first.
+    fireEvent.click(screen.getByLabelText('Next image'))
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/a.jpg'
+    )
+
+    // Previous wraps from the first item to the last.
+    fireEvent.click(screen.getByLabelText('Previous image'))
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/c.jpg'
+    )
+  })
+
+  it('uses ArrowRight / ArrowLeft to navigate stacked images', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Sent
+        items={[
+          { src: 'https://cdn.example.com/a.jpg', alt: 'A' },
+          { src: 'https://cdn.example.com/b.jpg', alt: 'B' },
+        ]}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open image 1 of 2'))
+    const viewer = expectViewerOpen('image-viewer')
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/a.jpg'
+    )
+
+    fireEvent.keyDown(window, { key: 'ArrowRight' })
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/b.jpg'
+    )
+
+    fireEvent.keyDown(window, { key: 'ArrowLeft' })
+    expect(viewer.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/a.jpg'
+    )
+  })
+
   it('shows a +N overflow tile for 5+ items', () => {
     renderWithProviders(
       <MessageAttachment.Image.Sent
@@ -113,9 +226,9 @@ describe('MessageAttachment.Pdf', () => {
         filename="doc.pdf"
       />
     )
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
     fireEvent.click(screen.getByLabelText('Open doc.pdf'))
-    expect(screen.getByTestId('pdf-viewer')).toBeInTheDocument()
+    expectViewerOpen('pdf-viewer')
   })
 
   it('forwards the onClick handler before opening the viewer', () => {
@@ -167,11 +280,42 @@ describe('MessageAttachment.Pdf', () => {
         ]}
       />
     )
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
     fireEvent.click(screen.getByLabelText('Open b.pdf'))
-    const viewer = screen.getByTestId('pdf-viewer')
-    expect(viewer).toBeInTheDocument()
-    expect(viewer.textContent).toContain('b.pdf')
+    const viewer = expectViewerOpen('pdf-viewer')
+    // The active filename surfaces as the dialog's accessible name —
+    // the lightbox chrome is intentionally just close + carousel chrome
+    // so the filename isn't rendered as visible text inside the modal.
+    expect(viewer.getAttribute('aria-label')).toBe('b.pdf')
+    // Carousel chrome is present because items.length > 1.
+    expect(screen.getByLabelText('Next document')).toBeInTheDocument()
+    expect(screen.getByLabelText('Previous document')).toBeInTheDocument()
+    expect(viewer.textContent).toContain('2 / 2')
+  })
+
+  it('navigates between stacked PDFs via the carousel controls', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Received
+        items={[
+          { src: 'https://cdn.example.com/a.pdf', filename: 'a.pdf' },
+          { src: 'https://cdn.example.com/b.pdf', filename: 'b.pdf' },
+          { src: 'https://cdn.example.com/c.pdf', filename: 'c.pdf' },
+        ]}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open a.pdf'))
+    const viewer = expectViewerOpen('pdf-viewer')
+    expect(viewer.getAttribute('aria-label')).toBe('a.pdf')
+
+    fireEvent.click(screen.getByLabelText('Next document'))
+    expect(viewer.getAttribute('aria-label')).toBe('b.pdf')
+
+    fireEvent.click(screen.getByLabelText('Next document'))
+    expect(viewer.getAttribute('aria-label')).toBe('c.pdf')
+
+    // Wraps back to the start.
+    fireEvent.click(screen.getByLabelText('Next document'))
+    expect(viewer.getAttribute('aria-label')).toBe('a.pdf')
   })
 
   it('renders a sibling Download button on Sent / Received rows', () => {
@@ -214,11 +358,11 @@ describe('MessageAttachment.Pdf', () => {
         filename="notes.pdf"
       />
     )
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
     fireEvent.click(screen.getByLabelText('Download notes.pdf'))
     // Download should fire on its own without bubbling up to the row
     // activation that opens the viewer.
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
   })
 
   it('hides the Download button on the Composer state (dismiss takes its place)', () => {
@@ -249,7 +393,7 @@ describe('MessageAttachment.Pdf', () => {
       />
     )
     fireEvent.click(screen.getByLabelText('Open c.pdf'))
-    expect(screen.getByTestId('pdf-viewer')).toBeInTheDocument()
+    expectViewerOpen('pdf-viewer')
 
     expect(() =>
       rerender(
@@ -263,8 +407,12 @@ describe('MessageAttachment.Pdf', () => {
 
     // Bubble still renders the surviving row instead of blowing up.
     expect(screen.getByLabelText('Open a.pdf')).toBeInTheDocument()
-    // Viewer falls back to the last available item (the surviving one).
-    expect(screen.getByTestId('pdf-viewer').textContent).toContain('a.pdf')
+    // Viewer falls back to the last available item (the surviving one)
+    // — surfaced as the dialog's aria-label since the chrome no longer
+    // renders the filename as visible text.
+    expect(screen.getByTestId('pdf-viewer').getAttribute('aria-label')).toBe(
+      'a.pdf'
+    )
   })
 
   it('does not open the viewer when onClick returns false', () => {
@@ -278,7 +426,7 @@ describe('MessageAttachment.Pdf', () => {
     )
     fireEvent.click(screen.getByLabelText('Open doc.pdf'))
     expect(onClick).toHaveBeenCalledTimes(1)
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    expectViewerClosed('pdf-viewer')
   })
 })
 
@@ -450,9 +598,41 @@ describe('MessageAttachment.Video', () => {
         filename="clip.mp4"
       />
     )
-    expect(screen.queryByTestId('video-viewer')).toBeNull()
+    expectViewerClosed('video-viewer')
     fireEvent.click(screen.getByLabelText('Play video 1 of 1'))
-    expect(screen.getByTestId('video-viewer')).toBeInTheDocument()
+    expectViewerOpen('video-viewer')
+    // Single-item viewer has no carousel chrome.
+    expect(screen.queryByLabelText('Next video')).toBeNull()
+  })
+
+  it('navigates between stacked videos via the carousel controls', () => {
+    renderWithProviders(
+      <MessageAttachment.Video.Sent
+        filename="clip"
+        items={[
+          {
+            src: 'https://cdn.example.com/a.mp4',
+            poster: 'https://cdn.example.com/a.jpg',
+            mimeType: 'video/mp4',
+          },
+          {
+            src: 'https://cdn.example.com/b.mp4',
+            poster: 'https://cdn.example.com/b.jpg',
+            mimeType: 'video/mp4',
+          },
+        ]}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Play video 1 of 2'))
+    const viewer = expectViewerOpen('video-viewer')
+    expect(viewer.querySelector('video')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/a.mp4'
+    )
+
+    fireEvent.click(screen.getByLabelText('Next video'))
+    expect(viewer.querySelector('video')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/b.mp4'
+    )
   })
 })
 
@@ -485,13 +665,14 @@ describe('ViewerShell focus management', () => {
     expect(document.activeElement).toBe(opener)
 
     fireEvent.click(opener)
-    expect(screen.getByTestId('pdf-viewer')).toBeInTheDocument()
+    expectViewerOpen('pdf-viewer')
 
     fireEvent.click(screen.getByLabelText('Close viewer'))
 
     // After close, focus should hop back to whatever was focused
-    // before the viewer mounted (the row's Open button).
-    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    // before the viewer mounted (the row's Open button), and the
+    // dialog should no longer carry the `[open]` attribute.
+    expectViewerClosed('pdf-viewer')
     expect(document.activeElement).toBe(opener)
   })
 })

package/src/components/MessageAttachment/Pdf/index.tsx

@@ -5,7 +5,7 @@ import CompactDocumentRow from '../_shared/CompactDocumentRow'
 import DismissButton from '../_shared/DismissButton'
 import DownloadAction from '../_shared/DownloadAction'
 import { filenameFromUrl } from '../_shared/fileMeta'
-import PdfViewer from '../_shared/PdfViewer'
+import PdfViewer, { type PdfViewerItem } from '../_shared/PdfViewer'
 import { useViewer } from '../_shared/useViewer'
 import {
   bubbleVariantForState,
@@ -19,7 +19,7 @@ import {
 export interface PdfAttachmentSharedProps extends MessageAttachmentBaseProps {
   /** Single PDF — convenience for the most common case. */
   src?: string
-  /** Filename — drives the title + the meta line + the viewer toolbar. */
+  /** Filename — drives the row title + the meta line + the viewer dialog's accessible name. */
   filename?: string
   /** File size in bytes — formatted into the `EXT · SIZE` meta line. */
   fileSize?: number
@@ -128,15 +128,13 @@ const PdfAttachmentRow: React.FC<InternalPdfRowProps> = ({
     return null
   }
 
-  // Clamp the viewer index defensively: if `items` shrinks between
-  // the open click and the next render (server push, optimistic
-  // update, etc.) `viewerIndex` may point past the new array.
-  // Dereferencing `undefined` would crash the whole bubble, so fall
-  // back to the last available row instead.
-  const safeIndex = Math.min(viewerIndex, resolvedItems.length - 1)
-  const activeItem = resolvedItems[safeIndex]
-  const activeFilename =
-    activeItem.filename ?? filenameFromUrl(activeItem.src)
+  // Project the bubble's `PdfItem`s onto the viewer's carousel-aware
+  // shape. The viewer clamps its own active index defensively, so we
+  // don't need to second-guess `viewerIndex` here.
+  const viewerItems: PdfViewerItem[] = resolvedItems.map((item) => ({
+    src: item.src,
+    filename: item.filename ?? filenameFromUrl(item.src),
+  }))
 
   return (
     <Bubble
@@ -154,8 +152,9 @@ const PdfAttachmentRow: React.FC<InternalPdfRowProps> = ({
           // Composer only supports a single attachment so the dismiss
           // control sits on the only row. Sent / Received rows expose
           // a download icon button so the user can grab the PDF
-          // without opening the viewer first (the viewer also has a
-          // download in its toolbar — this is the quick-grab shortcut).
+          // without opening the viewer first — the viewer dialog is
+          // intentionally just the document + a close button, so this
+          // sibling action is the only one-click download surface.
           const trailingAction =
             showDismiss && index === 0 ? (
               <DismissButton onClick={onDismiss!} variant="inline" />
@@ -183,8 +182,8 @@ const PdfAttachmentRow: React.FC<InternalPdfRowProps> = ({
 
       <PdfViewer
         open={viewerOpen}
-        src={activeItem.src}
-        filename={activeFilename}
+        items={viewerItems}
+        initialIndex={viewerIndex}
         onClose={closeViewer}
       />
     </Bubble>

package/src/components/MessageAttachment/Video/VideoAttachment.stories.tsx

@@ -53,13 +53,13 @@ const handleDismiss = () => {
 /**
  * Single video — the bubble shows the poster with a play overlay.
  * Clicking opens the full-viewport `VideoViewer` with native controls
- * (play / pause / seek / fullscreen / volume) and a download action.
+ * (play / pause / seek / fullscreen / volume / download).
  */
 export const Single: StoryFn = () => (
   <StoryPage>
     <StoryHeading
       title="Single video"
-      description="Click any bubble to open the full-screen video viewer with native controls and a download action."
+      description="Click any bubble to open the full-screen video viewer with the browser's native controls (play / pause / seek / fullscreen / volume / download)."
     />
     <StoryGrid>
       <StoryRow

package/src/components/MessageAttachment/Video/index.tsx

@@ -23,7 +23,7 @@ export interface VideoAttachmentSharedProps extends MessageAttachmentBaseProps {
   poster?: string
   /** MIME type hint — typed onto the inline `<source>` element. */
   mimeType?: string
-  /** Filename surfaced in the viewer toolbar + download default name. */
+  /** Filename used as the viewer dialog's accessible name. */
   filename?: string
   /**
    * Stacked videos. Takes precedence over `src` when set. Renders a
@@ -121,6 +121,12 @@ interface InternalVideoRowProps extends VideoAttachmentSharedProps {
   state: MessageAttachmentState
 }
 
+/**
+ * Project the bubble's `VideoItem`s onto the carousel-aware viewer's
+ * `VideoViewerItem` shape. When a shared outer `filename` is supplied
+ * for a stacked bubble, suffix `(N)` per sibling so each carousel page
+ * still gets a distinct accessible name.
+ */
 const buildViewerItems = (
   resolvedItems: VideoItem[],
   filename?: string
@@ -177,7 +183,10 @@ const VideoComposerInner: React.FC<{
 
       <VideoViewer
         open={viewerOpen}
-        items={buildViewerItems([{ src, poster, mimeType, preload }], filename)}
+        items={buildViewerItems(
+          [{ src, poster, mimeType, preload }],
+          filename
+        )}
         initialIndex={viewerIndex}
         onClose={closeViewer}
       />

package/src/components/MessageAttachment/_shared/CarouselNav.tsx

@@ -0,0 +1,47 @@
+import { CaretLeftIcon, CaretRightIcon } from '@phosphor-icons/react'
+import React from 'react'
+
+export interface CarouselNavProps {
+  onPrev: () => void
+  onNext: () => void
+  /** Accessible label for the previous-item button. */
+  prevLabel?: string
+  /** Accessible label for the next-item button. */
+  nextLabel?: string
+}
+
+/**
+ * Prev / next chrome shared by every carousel-aware viewer. Rendered
+ * inside the dialog body so the buttons sit absolutely positioned
+ * against the viewer (`.mes-media-viewer__nav--{prev,next}`).
+ *
+ * Styling lives as plain CSS in `styles.css` so the buttons render
+ * correctly regardless of whether the consumer has Tailwind wired up.
+ */
+const CarouselNav: React.FC<CarouselNavProps> = ({
+  onPrev,
+  onNext,
+  prevLabel = 'Previous',
+  nextLabel = 'Next',
+}) => (
+  <>
+    <button
+      type="button"
+      onClick={onPrev}
+      aria-label={prevLabel}
+      className="mes-media-viewer__nav mes-media-viewer__nav--prev"
+    >
+      <CaretLeftIcon size={20} weight="bold" aria-hidden />
+    </button>
+    <button
+      type="button"
+      onClick={onNext}
+      aria-label={nextLabel}
+      className="mes-media-viewer__nav mes-media-viewer__nav--next"
+    >
+      <CaretRightIcon size={20} weight="bold" aria-hidden />
+    </button>
+  </>
+)
+
+export default CarouselNav

package/src/components/MessageAttachment/_shared/DownloadAction.tsx

@@ -11,16 +11,20 @@ import { triggerDownload } from './triggerDownload'
 export type DownloadActionVariant =
   /** Solid pill button used inside compact / file rows. */
   | 'pill'
-  /** Round translucent overlay button used over media (image / video viewers). */
-  | 'overlay'
-  /** Flat icon button used in viewer toolbars. */
-  | 'toolbar'
   /**
    * Compact round icon button sized for the trailing slot of a
    * `CompactDocumentRow` (PDF / File rows). Adopts the row's tone so
    * it sits inline next to the filename without competing with it.
    */
   | 'inline'
+  /**
+   * Round icon button sized to match the close action in the
+   * `ViewerShell` chrome — used by `ImageViewer` for in-viewer
+   * downloads. Styled with plain CSS (`.mes-media-viewer__action`) so
+   * it renders correctly without a Tailwind dependency in the
+   * consumer's app.
+   */
+  | 'viewer'
 
 export interface DownloadActionProps {
   url: string
@@ -28,7 +32,8 @@ export interface DownloadActionProps {
   variant?: DownloadActionVariant
   /**
    * Override the visible label on `pill` variants. Defaults to
-   * `'Download'`. Hidden on `overlay` / `toolbar` variants.
+   * `'Download'`. On `inline` / `viewer` variants the label is
+   * hidden visually and surfaced as the button's `aria-label`.
    */
   label?: string
   /** Hide the label, keeping just the icon. Defaults to `true` for non-pill variants. */
@@ -117,57 +122,52 @@ const DownloadAction: React.FC<DownloadActionProps> = ({
     )
   }
 
-  if (variant === 'pill') {
+  if (variant === 'viewer') {
+    // Styled entirely through `.mes-media-viewer__action` (plain CSS
+    // in `styles.css`) so the button renders correctly when consumed
+    // outside this repo without a Tailwind setup. Sits next to the
+    // close action inside `ViewerShell`'s top-right chrome.
     return (
       <button
         type="button"
         onClick={handleClick}
         disabled={busy}
-        aria-label={showIconOnly ? label : undefined}
-        className={classNames(
-          'mt-3 inline-flex h-10 w-full items-center justify-center gap-2 rounded-full px-4 text-sm font-medium leading-none transition-colors disabled:opacity-70',
-          tone === 'dark'
-            ? 'bg-[#121110] text-white hover:bg-[#2a2928]'
-            : 'bg-white text-[#121110] hover:bg-white/90'
-        )}
+        aria-label={label}
+        className="mes-media-viewer__action"
       >
         {busy ? (
-          <CircleNotchIcon
-            className="size-4 animate-spin"
-            weight="bold"
-            aria-hidden
-          />
+          <CircleNotchIcon size={20} weight="bold" aria-hidden />
         ) : (
-          <DownloadSimpleIcon {...iconProps} aria-hidden />
+          <DownloadSimpleIcon size={20} weight="bold" aria-hidden />
         )}
-        {showIconOnly ? null : label}
       </button>
     )
   }
 
-  // overlay / toolbar — round translucent button with just the icon
+  // pill — only remaining variant
   return (
     <button
       type="button"
       onClick={handleClick}
       disabled={busy}
-      aria-label={label}
+      aria-label={showIconOnly ? label : undefined}
       className={classNames(
-        'flex size-10 shrink-0 items-center justify-center rounded-full text-white transition-colors disabled:opacity-70',
-        variant === 'overlay'
-          ? 'bg-black/55 backdrop-blur hover:bg-black/70'
-          : 'bg-white/10 hover:bg-white/20'
+        'mt-3 inline-flex h-10 w-full items-center justify-center gap-2 rounded-full px-4 text-sm font-medium leading-none transition-colors disabled:opacity-70',
+        tone === 'dark'
+          ? 'bg-[#121110] text-white hover:bg-[#2a2928]'
+          : 'bg-white text-[#121110] hover:bg-white/90'
       )}
     >
       {busy ? (
         <CircleNotchIcon
-          className="size-5 animate-spin"
+          className="size-4 animate-spin"
           weight="bold"
           aria-hidden
         />
       ) : (
         <DownloadSimpleIcon {...iconProps} aria-hidden />
       )}
+      {showIconOnly ? null : label}
     </button>
   )
 }