@linktr.ee/messaging-react 2.1.0 → 2.2.0-rc-1778753733

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

@@ -0,0 +1,783 @@
+import React from 'react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { renderWithProviders, screen, fireEvent } from '../../test/utils'
+
+import { triggerDownload } from './_shared/triggerDownload'
+
+import MessageAttachment, { bubbleGroupPositionFromStream } from '.'
+
+vi.mock('./_shared/triggerDownload', () => ({
+  triggerDownload: vi.fn(() => Promise.resolve()),
+}))
+
+const mockTriggerDownload = vi.mocked(triggerDownload)
+
+beforeEach(() => {
+  mockTriggerDownload.mockClear()
+})
+
+describe('MessageAttachment.Image', () => {
+  it('renders an image bubble with caption', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Sent
+        src="https://cdn.example.com/photo.jpg"
+        alt="Photo"
+        text="Here is the image"
+      />
+    )
+    const bubble = screen.getByTestId('image-attachment')
+    expect(bubble).toBeInTheDocument()
+    expect(screen.getByText('Here is the image')).toBeInTheDocument()
+    expect(bubble.querySelector('img')?.getAttribute('src')).toBe(
+      'https://cdn.example.com/photo.jpg'
+    )
+  })
+
+  it('opens the ImageViewer lightbox when clicked', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Received
+        src="https://cdn.example.com/photo.jpg"
+        alt="Photo"
+        filename="photo.jpg"
+      />
+    )
+
+    expect(screen.queryByTestId('image-viewer')).toBeNull()
+
+    fireEvent.click(screen.getByLabelText('Open image 1 of 1'))
+
+    expect(screen.getByTestId('image-viewer')).toBeInTheDocument()
+  })
+
+  it('renders the dismiss button only on Composer state', () => {
+    const onDismiss = vi.fn()
+    const { rerender } = renderWithProviders(
+      <MessageAttachment.Image.Composer
+        src="https://cdn.example.com/photo.jpg"
+        onDismiss={onDismiss}
+      />
+    )
+    expect(screen.getByLabelText('Dismiss attachment')).toBeInTheDocument()
+
+    rerender(
+      <MessageAttachment.Image.Sent src="https://cdn.example.com/photo.jpg" />
+    )
+    expect(screen.queryByLabelText('Dismiss attachment')).toBeNull()
+  })
+
+  it('renders a stacked grid for multiple items', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Sent
+        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' },
+        ]}
+      />
+    )
+    expect(screen.getByLabelText('Open image 1 of 3')).toBeInTheDocument()
+    expect(screen.getByLabelText('Open image 2 of 3')).toBeInTheDocument()
+    expect(screen.getByLabelText('Open image 3 of 3')).toBeInTheDocument()
+  })
+
+  it('shows a +N overflow tile for 5+ items', () => {
+    renderWithProviders(
+      <MessageAttachment.Image.Sent
+        items={Array.from({ length: 6 }, (_, i) => ({
+          src: `https://cdn.example.com/${i}.jpg`,
+        }))}
+      />
+    )
+    expect(screen.getByText('+2')).toBeInTheDocument()
+  })
+})
+
+describe('MessageAttachment.Pdf', () => {
+  it('renders the compact row with filename + meta', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Received
+        src="https://cdn.example.com/doc.pdf"
+        filename="ESOP-summary.pdf"
+        fileSize={388_658}
+      />
+    )
+    expect(screen.getByText('ESOP-summary.pdf')).toBeInTheDocument()
+    expect(screen.getByText('PDF · 379.5 KB')).toBeInTheDocument()
+  })
+
+  it('opens the PdfViewer when clicked', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Sent
+        src="https://cdn.example.com/doc.pdf"
+        filename="doc.pdf"
+      />
+    )
+    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    fireEvent.click(screen.getByLabelText('Open doc.pdf'))
+    expect(screen.getByTestId('pdf-viewer')).toBeInTheDocument()
+  })
+
+  it('forwards the onClick handler before opening the viewer', () => {
+    const onClick = vi.fn()
+    renderWithProviders(
+      <MessageAttachment.Pdf.Received
+        src="https://cdn.example.com/doc.pdf"
+        filename="doc.pdf"
+        onClick={onClick}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open doc.pdf'))
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders caption inside the same bubble', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Sent
+        src="https://cdn.example.com/doc.pdf"
+        filename="doc.pdf"
+        text="Here is the file"
+      />
+    )
+    const bubble = screen.getByTestId('pdf-attachment')
+    expect(bubble.textContent).toContain('Here is the file')
+  })
+
+  it('renders a row per item for stacked PDFs', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Sent
+        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' },
+        ]}
+      />
+    )
+    expect(screen.getByLabelText('Open a.pdf')).toBeInTheDocument()
+    expect(screen.getByLabelText('Open b.pdf')).toBeInTheDocument()
+    expect(screen.getByLabelText('Open c.pdf')).toBeInTheDocument()
+  })
+
+  it('opens the viewer on the activated row in a stacked PDF bubble', () => {
+    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' },
+        ]}
+      />
+    )
+    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    fireEvent.click(screen.getByLabelText('Open b.pdf'))
+    const viewer = screen.getByTestId('pdf-viewer')
+    expect(viewer).toBeInTheDocument()
+    expect(viewer.textContent).toContain('b.pdf')
+  })
+
+  it('renders a sibling Download button on Sent / Received rows', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Received
+        src="https://cdn.example.com/notes.pdf"
+        filename="notes.pdf"
+        fileSize={1_024}
+      />
+    )
+    const open = screen.getByLabelText('Open notes.pdf')
+    const download = screen.getByLabelText('Download notes.pdf')
+    expect(open).toBeInTheDocument()
+    expect(download).toBeInTheDocument()
+    // The download button must be a real sibling button — not nested
+    // inside the open button — so the two activations are independent.
+    expect(open.contains(download)).toBe(false)
+    expect(download.contains(open)).toBe(false)
+  })
+
+  it('renders one Download button per row for stacked PDFs', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Sent
+        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' },
+        ]}
+      />
+    )
+    expect(screen.getByLabelText('Download a.pdf')).toBeInTheDocument()
+    expect(screen.getByLabelText('Download b.pdf')).toBeInTheDocument()
+    expect(screen.getByLabelText('Download c.pdf')).toBeInTheDocument()
+  })
+
+  it('does not open the viewer when the Download button is clicked', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Sent
+        src="https://cdn.example.com/notes.pdf"
+        filename="notes.pdf"
+      />
+    )
+    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+    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()
+  })
+
+  it('hides the Download button on the Composer state (dismiss takes its place)', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Composer
+        src="https://cdn.example.com/notes.pdf"
+        filename="notes.pdf"
+        onDismiss={() => undefined}
+      />
+    )
+    expect(screen.queryByLabelText('Download notes.pdf')).toBeNull()
+    expect(screen.getByLabelText('Dismiss attachment')).toBeInTheDocument()
+  })
+
+  it('does not crash when items shrinks after the viewer opens (P1 regression)', () => {
+    // Regression test for the PR #151 P1 reviewer finding:
+    // `viewerIndex` was dereferenced directly against `resolvedItems`,
+    // so a re-render with fewer items than the open index would crash
+    // with "Cannot read properties of undefined". The component now
+    // clamps the index defensively.
+    const { rerender } = 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 c.pdf'))
+    expect(screen.getByTestId('pdf-viewer')).toBeInTheDocument()
+
+    expect(() =>
+      rerender(
+        <MessageAttachment.Pdf.Received
+          items={[
+            { src: 'https://cdn.example.com/a.pdf', filename: 'a.pdf' },
+          ]}
+        />
+      )
+    ).not.toThrow()
+
+    // 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')
+  })
+
+  it('does not open the viewer when onClick returns false', () => {
+    const onClick = vi.fn(() => false as const)
+    renderWithProviders(
+      <MessageAttachment.Pdf.Received
+        src="https://cdn.example.com/doc.pdf"
+        filename="doc.pdf"
+        onClick={onClick}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open doc.pdf'))
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(screen.queryByTestId('pdf-viewer')).toBeNull()
+  })
+})
+
+describe('MessageAttachment.File', () => {
+  it('renders the row with the trailing download icon', () => {
+    renderWithProviders(
+      <MessageAttachment.File.Received
+        src="https://cdn.example.com/file.zip"
+        filename="workout-plan.zip"
+        mimeType="application/zip"
+        fileSize={2_457_600}
+      />
+    )
+    expect(screen.getByText('workout-plan.zip')).toBeInTheDocument()
+    expect(screen.getByText('ZIP · 2.34 MB')).toBeInTheDocument()
+    expect(
+      screen.getByLabelText('Download workout-plan.zip')
+    ).toBeInTheDocument()
+  })
+
+  it('falls back to the URL filename when none is provided', () => {
+    renderWithProviders(
+      <MessageAttachment.File.Sent src="https://cdn.example.com/notes.pdf" />
+    )
+    expect(screen.getByText('notes.pdf')).toBeInTheDocument()
+  })
+
+  it('renders one row per item for stacked files', () => {
+    renderWithProviders(
+      <MessageAttachment.File.Sent
+        items={[
+          {
+            src: 'https://cdn.example.com/a.zip',
+            filename: 'a.zip',
+            mimeType: 'application/zip',
+            fileSize: 1_024,
+          },
+          {
+            src: 'https://cdn.example.com/b.docx',
+            filename: 'b.docx',
+            mimeType:
+              'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+            fileSize: 2_048,
+          },
+          {
+            src: 'https://cdn.example.com/c.pdf',
+            filename: 'c.pdf',
+            mimeType: 'application/pdf',
+            fileSize: 4_096,
+          },
+        ]}
+      />
+    )
+    expect(screen.getByLabelText('Download a.zip')).toBeInTheDocument()
+    expect(screen.getByLabelText('Download b.docx')).toBeInTheDocument()
+    expect(screen.getByLabelText('Download c.pdf')).toBeInTheDocument()
+  })
+
+  it('downloads the file when the row is clicked and onClick allows it', () => {
+    const onClick = vi.fn()
+    renderWithProviders(
+      <MessageAttachment.File.Received
+        src="https://cdn.example.com/file.zip"
+        filename="workout-plan.zip"
+        onClick={onClick}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Download workout-plan.zip'))
+    expect(onClick).toHaveBeenCalledWith(0)
+    expect(mockTriggerDownload).toHaveBeenCalledTimes(1)
+    expect(mockTriggerDownload).toHaveBeenCalledWith(
+      'https://cdn.example.com/file.zip',
+      'workout-plan.zip'
+    )
+  })
+
+  it('lets onClick cancel the automatic download by returning false (P2 regression)', () => {
+    // Regression test for the PR #151 P2 reviewer finding:
+    // the docs advertised `onClick` as a hook for intercepting the
+    // download (e.g. confirmation modal), but the handler used to fire
+    // the default download unconditionally. Returning `false` from
+    // `onClick` now suppresses the built-in trigger.
+    const onClick = vi.fn(() => false as const)
+    renderWithProviders(
+      <MessageAttachment.File.Received
+        src="https://cdn.example.com/file.zip"
+        filename="workout-plan.zip"
+        onClick={onClick}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Download workout-plan.zip'))
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(mockTriggerDownload).not.toHaveBeenCalled()
+  })
+
+  it('still downloads when onClick returns void', () => {
+    // Belt-and-braces: void / undefined returns must not be confused
+    // with `false` (the only cancellation sentinel).
+    const onClick = vi.fn(() => undefined)
+    renderWithProviders(
+      <MessageAttachment.File.Received
+        src="https://cdn.example.com/file.zip"
+        filename="workout-plan.zip"
+        onClick={onClick}
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Download workout-plan.zip'))
+    expect(mockTriggerDownload).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('MessageAttachment.Audio', () => {
+  it('renders the native audio player only (no title, no extra download)', () => {
+    renderWithProviders(
+      <MessageAttachment.Audio.Sent
+        src="https://cdn.example.com/song.mp3"
+        mimeType="audio/mpeg"
+        filename="song.mp3"
+      />
+    )
+    const bubble = screen.getByTestId('audio-attachment')
+    expect(bubble.querySelector('audio')).not.toBeNull()
+    // No filename title — the native `<audio>` element doesn't expose
+    // a title slot, so we render just the player.
+    expect(screen.queryByText('song.mp3')).toBeNull()
+    // Native player handles its own download in the kebab menu, so
+    // no extra Download button should be rendered.
+    expect(
+      screen.queryByRole('button', { name: /download/i })
+    ).toBeNull()
+  })
+
+  it('shows an inline dismiss button next to the player on Composer state', () => {
+    const onDismiss = vi.fn()
+    renderWithProviders(
+      <MessageAttachment.Audio.Composer
+        src="https://cdn.example.com/song.mp3"
+        onDismiss={onDismiss}
+      />
+    )
+    const dismiss = screen.getByLabelText('Dismiss attachment')
+    expect(dismiss).toBeInTheDocument()
+    fireEvent.click(dismiss)
+    expect(onDismiss).toHaveBeenCalledTimes(1)
+  })
+
+  it('renders one native player per item for stacked audio', () => {
+    renderWithProviders(
+      <MessageAttachment.Audio.Sent
+        items={[
+          { src: 'https://cdn.example.com/a.mp3', mimeType: 'audio/mpeg' },
+          { src: 'https://cdn.example.com/b.mp3', mimeType: 'audio/mpeg' },
+          { src: 'https://cdn.example.com/c.mp3', mimeType: 'audio/mpeg' },
+        ]}
+      />
+    )
+    const bubble = screen.getByTestId('audio-attachment')
+    expect(bubble.querySelectorAll('audio')).toHaveLength(3)
+  })
+})
+
+describe('MessageAttachment.Video', () => {
+  it('opens the VideoViewer when clicked', () => {
+    renderWithProviders(
+      <MessageAttachment.Video.Received
+        src="https://cdn.example.com/clip.mp4"
+        poster="https://cdn.example.com/poster.jpg"
+        mimeType="video/mp4"
+        filename="clip.mp4"
+      />
+    )
+    expect(screen.queryByTestId('video-viewer')).toBeNull()
+    fireEvent.click(screen.getByLabelText('Play video 1 of 1'))
+    expect(screen.getByTestId('video-viewer')).toBeInTheDocument()
+  })
+})
+
+describe('ViewerShell focus management', () => {
+  it('moves focus into the dialog when a viewer opens', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Received
+        src="https://cdn.example.com/doc.pdf"
+        filename="doc.pdf"
+      />
+    )
+    fireEvent.click(screen.getByLabelText('Open doc.pdf'))
+
+    // The close button is the primary focus target in the viewer
+    // toolbar — keyboard users should land on it on open so Escape
+    // / Tab work without an extra click.
+    const close = screen.getByLabelText('Close viewer')
+    expect(document.activeElement).toBe(close)
+  })
+
+  it('restores focus to the opener when the viewer closes', () => {
+    renderWithProviders(
+      <MessageAttachment.Pdf.Received
+        src="https://cdn.example.com/doc.pdf"
+        filename="doc.pdf"
+      />
+    )
+    const opener = screen.getByLabelText('Open doc.pdf')
+    opener.focus()
+    expect(document.activeElement).toBe(opener)
+
+    fireEvent.click(opener)
+    expect(screen.getByTestId('pdf-viewer')).toBeInTheDocument()
+
+    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()
+    expect(document.activeElement).toBe(opener)
+  })
+})
+
+describe('MessageAttachment lazy-loading defaults', () => {
+  describe('Image', () => {
+    it('renders every `<img>` with loading="lazy" decoding="async" by default', () => {
+      renderWithProviders(
+        <MessageAttachment.Image.Sent
+          src="https://cdn.example.com/photo.jpg"
+          alt="Photo"
+        />
+      )
+      const img = screen.getByTestId('image-attachment').querySelector('img')
+      expect(img?.getAttribute('loading')).toBe('lazy')
+      expect(img?.getAttribute('decoding')).toBe('async')
+    })
+
+    it('honors loading="eager" when passed at the attachment level', () => {
+      renderWithProviders(
+        <MessageAttachment.Image.Received
+          src="https://cdn.example.com/photo.jpg"
+          alt="Photo"
+          loading="eager"
+        />
+      )
+      const img = screen.getByTestId('image-attachment').querySelector('img')
+      expect(img?.getAttribute('loading')).toBe('eager')
+      expect(img?.getAttribute('decoding')).toBe('async')
+    })
+
+    it('honors per-tile ImageItem.loading overrides in a stack', () => {
+      renderWithProviders(
+        <MessageAttachment.Image.Sent
+          items={[
+            { src: 'https://cdn.example.com/a.jpg', alt: 'A', loading: 'eager' },
+            { src: 'https://cdn.example.com/b.jpg', alt: 'B' },
+          ]}
+        />
+      )
+      const [first, second] = Array.from(
+        screen.getByTestId('image-attachment').querySelectorAll('img')
+      )
+      expect(first?.getAttribute('loading')).toBe('eager')
+      expect(second?.getAttribute('loading')).toBe('lazy')
+    })
+  })
+
+  describe('Video', () => {
+    it('renders the poster `<img>` with loading="lazy" decoding="async"', () => {
+      renderWithProviders(
+        <MessageAttachment.Video.Received
+          src="https://cdn.example.com/clip.mp4"
+          poster="https://cdn.example.com/poster.jpg"
+          mimeType="video/mp4"
+        />
+      )
+      const poster = screen
+        .getByTestId('video-attachment')
+        .querySelector('img')
+      expect(poster?.getAttribute('src')).toBe(
+        'https://cdn.example.com/poster.jpg'
+      )
+      expect(poster?.getAttribute('loading')).toBe('lazy')
+      expect(poster?.getAttribute('decoding')).toBe('async')
+    })
+
+    it('opens the viewer with `<video preload="metadata">` for the active item', () => {
+      renderWithProviders(
+        <MessageAttachment.Video.Sent
+          src="https://cdn.example.com/clip.mp4"
+          poster="https://cdn.example.com/poster.jpg"
+          mimeType="video/mp4"
+          filename="clip.mp4"
+        />
+      )
+      fireEvent.click(screen.getByLabelText('Play video 1 of 1'))
+      const video = screen
+        .getByTestId('video-viewer')
+        .querySelector('video')
+      expect(video?.getAttribute('preload')).toBe('metadata')
+    })
+  })
+
+  describe('Audio', () => {
+    it('defaults a single-track bubble to preload="metadata"', () => {
+      renderWithProviders(
+        <MessageAttachment.Audio.Received
+          src="https://cdn.example.com/song.mp3"
+          mimeType="audio/mpeg"
+        />
+      )
+      const audio = screen
+        .getByTestId('audio-attachment')
+        .querySelector('audio')
+      expect(audio?.getAttribute('preload')).toBe('metadata')
+    })
+
+    it('defaults a stacked (3-track) bubble to preload="none" on every player', () => {
+      renderWithProviders(
+        <MessageAttachment.Audio.Sent
+          items={[
+            { src: 'https://cdn.example.com/a.mp3', mimeType: 'audio/mpeg' },
+            { src: 'https://cdn.example.com/b.mp3', mimeType: 'audio/mpeg' },
+            { src: 'https://cdn.example.com/c.mp3', mimeType: 'audio/mpeg' },
+          ]}
+        />
+      )
+      const audios = Array.from(
+        screen.getByTestId('audio-attachment').querySelectorAll('audio')
+      )
+      expect(audios).toHaveLength(3)
+      audios.forEach((audio) => {
+        expect(audio.getAttribute('preload')).toBe('none')
+      })
+    })
+
+    it('honors a per-track AudioItem.preload override', () => {
+      renderWithProviders(
+        <MessageAttachment.Audio.Sent
+          items={[
+            { src: 'https://cdn.example.com/a.mp3', mimeType: 'audio/mpeg' },
+            {
+              src: 'https://cdn.example.com/b.mp3',
+              mimeType: 'audio/mpeg',
+              preload: 'metadata',
+            },
+          ]}
+        />
+      )
+      const audios = Array.from(
+        screen.getByTestId('audio-attachment').querySelectorAll('audio')
+      )
+      expect(audios[0]?.getAttribute('preload')).toBe('none')
+      expect(audios[1]?.getAttribute('preload')).toBe('metadata')
+    })
+  })
+})
+
+describe('bubbleGroupPositionFromStream', () => {
+  it('returns "single" when not grouped', () => {
+    expect(
+      bubbleGroupPositionFromStream({
+        groupedByUser: false,
+        firstOfGroup: true,
+        endOfGroup: true,
+      })
+    ).toBe('single')
+  })
+
+  it('returns "single" when both first and end are true (run of one)', () => {
+    expect(
+      bubbleGroupPositionFromStream({
+        groupedByUser: true,
+        firstOfGroup: true,
+        endOfGroup: true,
+      })
+    ).toBe('single')
+  })
+
+  it('returns "first" when firstOfGroup is the only flag set', () => {
+    expect(
+      bubbleGroupPositionFromStream({
+        groupedByUser: true,
+        firstOfGroup: true,
+        endOfGroup: false,
+      })
+    ).toBe('first')
+  })
+
+  it('returns "end" when endOfGroup is the only flag set', () => {
+    expect(
+      bubbleGroupPositionFromStream({
+        groupedByUser: true,
+        firstOfGroup: false,
+        endOfGroup: true,
+      })
+    ).toBe('end')
+  })
+
+  it('returns "middle" when grouped but neither first nor end', () => {
+    expect(
+      bubbleGroupPositionFromStream({
+        groupedByUser: true,
+        firstOfGroup: false,
+        endOfGroup: false,
+      })
+    ).toBe('middle')
+  })
+})
+
+describe('MessageAttachment.Bubble grouping', () => {
+  // Sender bubbles (Sent) cluster against the right edge — the corner
+  // facing the previous bubble in a run is `top-right`, the corner
+  // facing the next bubble is `bottom-right`. Receiver bubbles
+  // (Received) mirror those onto the left edge.
+  //
+  // We assert on the `data-group-position` attribute the Bubble
+  // serializes, not on the Tailwind class strings. The class strings
+  // encode the same intent, but asserting on them ties the test to
+  // the current `rounded-tr-[Xpx]` token format — if the bubble ever
+  // migrates to a CSS variable / theme token (see `Bubble.tsx` TODO),
+  // every one of those assertions would break for an implementation
+  // detail. `data-group-position` is the documented contract.
+  const FILE_PROPS = {
+    src: 'https://cdn.example.com/notes.pdf',
+    filename: 'notes.pdf',
+    fileSize: 1_024,
+    mimeType: 'application/pdf',
+  }
+
+  it('serializes groupPosition="single" for a standalone bubble', () => {
+    renderWithProviders(
+      <MessageAttachment.File.Sent {...FILE_PROPS} groupPosition="single" />
+    )
+    expect(
+      screen.getByTestId('file-attachment').getAttribute('data-group-position')
+    ).toBe('single')
+  })
+
+  it('serializes groupPosition="first" for the first bubble in a run', () => {
+    renderWithProviders(
+      <MessageAttachment.File.Sent {...FILE_PROPS} groupPosition="first" />
+    )
+    expect(
+      screen.getByTestId('file-attachment').getAttribute('data-group-position')
+    ).toBe('first')
+  })
+
+  it('serializes groupPosition="middle" for an interior bubble in a run', () => {
+    renderWithProviders(
+      <MessageAttachment.File.Sent {...FILE_PROPS} groupPosition="middle" />
+    )
+    expect(
+      screen.getByTestId('file-attachment').getAttribute('data-group-position')
+    ).toBe('middle')
+  })
+
+  it('serializes groupPosition="end" for the last bubble in a run', () => {
+    renderWithProviders(
+      <MessageAttachment.File.Sent {...FILE_PROPS} groupPosition="end" />
+    )
+    expect(
+      screen.getByTestId('file-attachment').getAttribute('data-group-position')
+    ).toBe('end')
+  })
+
+  it('serializes groupPosition on receiver-side bubbles too', () => {
+    renderWithProviders(
+      <MessageAttachment.File.Received {...FILE_PROPS} groupPosition="middle" />
+    )
+    expect(
+      screen.getByTestId('file-attachment').getAttribute('data-group-position')
+    ).toBe('middle')
+  })
+
+  it('forwards groupPosition through every attachment type', () => {
+    const { rerender } = renderWithProviders(
+      <MessageAttachment.Audio.Sent
+        src="https://cdn.example.com/song.mp3"
+        groupPosition="middle"
+      />
+    )
+    expect(
+      screen.getByTestId('audio-attachment').getAttribute('data-group-position')
+    ).toBe('middle')
+
+    rerender(
+      <MessageAttachment.Pdf.Sent
+        src="https://cdn.example.com/notes.pdf"
+        filename="notes.pdf"
+        groupPosition="end"
+      />
+    )
+    expect(
+      screen.getByTestId('pdf-attachment').getAttribute('data-group-position')
+    ).toBe('end')
+
+    rerender(
+      <MessageAttachment.Image.Sent
+        src="https://cdn.example.com/photo.jpg"
+        groupPosition="first"
+      />
+    )
+    expect(
+      screen.getByTestId('image-attachment').getAttribute('data-group-position')
+    ).toBe('first')
+  })
+})