@linktr.ee/messaging-react 4.1.5 → 4.2.0-rc-1787083791

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

@@ -1,4 +1,9 @@
 import React from 'react'
+import {
+  ChatProvider,
+  WithAudioPlayback,
+  type ChatContextValue,
+} from 'stream-chat-react'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { renderWithProviders, screen, fireEvent } from '../../test/utils'
@@ -7,6 +12,21 @@ import { triggerDownload } from './_shared/triggerDownload'
 
 import MessageAttachment, { bubbleGroupPositionFromStream } from '.'
 
+// `MessageAttachment.Audio`'s playback comes from `stream-chat-react`'s
+// pooled `AudioPlayer`, which `<Channel>` mounts in production. Mounting
+// the pool directly is the same contract without needing a channel that
+// can `watch()`. The player reads only `client` off the chat context —
+// optional-chained, for error notifications — so a stub is enough; its
+// presence is what stops `useChatContext` warning.
+const AUDIO_CHAT_CONTEXT = {} as ChatContextValue
+
+const renderAudio = (ui: React.ReactElement) =>
+  renderWithProviders(
+    <ChatProvider value={AUDIO_CHAT_CONTEXT}>
+      <WithAudioPlayback>{ui}</WithAudioPlayback>
+    </ChatProvider>
+  )
+
 vi.mock('./_shared/triggerDownload', () => ({
   triggerDownload: vi.fn(() => Promise.resolve()),
 }))
@@ -716,50 +736,186 @@ describe('MessageAttachment.File', () => {
 })
 
 describe('MessageAttachment.Audio', () => {
-  it('renders the native audio player only (no title, no extra download)', () => {
-    renderWithProviders(
+  // 12 samples so the resample path is exercised on the way to the
+  // design's 35 bars.
+  const WAVEFORM = [
+    0.1, 0.8, 0.65, 0.2, 0.3, 0.45, 0.5, 0.7, 1, 0.85, 0.4, 0.15,
+  ]
+
+  it('renders the waveform card: bars, play toggle, duration and seek', () => {
+    renderAudio(
       <MessageAttachment.Audio.Sent
         src="https://cdn.example.com/song.mp3"
         mimeType="audio/mpeg"
         filename="song.mp3"
+        durationSeconds={12}
+        waveformData={WAVEFORM}
       />
     )
+
     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()
+    expect(bubble.querySelectorAll('[data-testid="amplitude-bar"]')).toHaveLength(
+      35
+    )
+    // The native player is gone — playback is our own control set now.
+    expect(bubble.querySelector('audio')).toBeNull()
+    expect(
+      screen.getByRole('button', { name: 'Play audio — song.mp3' })
+    ).toBeInTheDocument()
+    expect(screen.getByText('00:12')).toBeInTheDocument()
+
+    const seek = screen.getByRole('slider', { name: 'Seek audio — song.mp3' })
+    expect(seek).toHaveAttribute('aria-valuetext', '00:00 of 00:12')
+    expect(seek).toHaveValue('0')
+
+    // The bars duplicate what the slider already announces, so they
+    // must stay out of the accessibility tree — otherwise they read as
+    // 35 unnamed nodes and (in Stream's own version of this widget) as
+    // an unnamed `progressbar`.
+    const track = bubble.querySelector('.mes-audio-wave__track')
+    expect(track).toHaveAttribute('aria-hidden', 'true')
+  })
+
+  it('renders the full bar count as a flat placeholder when no waveform exists', () => {
+    // The total fallback: a decode failure, an unsupported codec, a
+    // re-staged zero-byte placeholder, or anything sent before
+    // `waveform_data` was persisted. Passing `[]` straight through
+    // would render no bars at all, so the card must supply its own
+    // all-zero row — the card's silhouette has to be unchanged.
+    renderAudio(
+      <MessageAttachment.Audio.Received src="https://cdn.example.com/legacy.mp3" />
+    )
+
+    const bars = screen.getAllByTestId('amplitude-bar')
+    expect(bars).toHaveLength(35)
+    bars.forEach((bar) => {
+      expect(bar).not.toHaveClass('mes-audio-wave__bar--played')
+    })
   })
 
-  it('shows an inline dismiss button next to the player on Composer state', () => {
+  it.each([3, 12, 35, 200])(
+    'resamples a %i-sample waveform to the rendered bar count',
+    (sampleCount) => {
+      const data = Array.from({ length: sampleCount }, (_, i) =>
+        Math.abs(Math.sin(i))
+      )
+      renderAudio(
+        <MessageAttachment.Audio.Sent
+          src="https://cdn.example.com/song.mp3"
+          waveformData={data}
+        />
+      )
+      expect(screen.getAllByTestId('amplitude-bar')).toHaveLength(35)
+    }
+  )
+
+  it('shows an unknown duration without collapsing the slot', () => {
+    renderAudio(
+      <MessageAttachment.Audio.Sent src="https://cdn.example.com/legacy.mp3" />
+    )
+
+    expect(screen.getByText('--:--')).toBeInTheDocument()
+    expect(screen.getByRole('slider', { name: 'Seek audio' })).toHaveAttribute(
+      'aria-valuetext',
+      '00:00 of --:--'
+    )
+  })
+
+  it('removes the draft from the composer trailing action', () => {
+    // There is no product-owned overflow menu on audio attachments in
+    // production, so the design's trailing control carries forward the
+    // one action each surface already had: Remove in the composer…
     const onDismiss = vi.fn()
-    renderWithProviders(
+    renderAudio(
       <MessageAttachment.Audio.Composer
         src="https://cdn.example.com/song.mp3"
+        filename="song.mp3"
         onDismiss={onDismiss}
       />
     )
-    const dismiss = screen.getByLabelText('Dismiss attachment')
-    expect(dismiss).toBeInTheDocument()
-    fireEvent.click(dismiss)
+
+    expect(
+      screen.queryByRole('button', { name: /download/i })
+    ).not.toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Remove attachment' }))
     expect(onDismiss).toHaveBeenCalledTimes(1)
   })
 
-  it('renders one native player per item for stacked audio', () => {
-    renderWithProviders(
+  it('downloads from the sent trailing action', () => {
+    // …and Download once sent, preserving the capability the native
+    // `<audio controls>` kebab used to provide.
+    renderAudio(
+      <MessageAttachment.Audio.Sent
+        src="https://cdn.example.com/song.mp3"
+        filename="song.mp3"
+      />
+    )
+
+    fireEvent.click(
+      screen.getByRole('button', { name: 'Download audio — song.mp3' })
+    )
+    expect(mockTriggerDownload).toHaveBeenCalledWith(
+      'https://cdn.example.com/song.mp3',
+      'song.mp3'
+    )
+  })
+
+  it('renders one waveform row per item for stacked audio', () => {
+    renderAudio(
       <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' },
+          { src: 'https://cdn.example.com/a.mp3', durationSeconds: 12 },
+          { src: 'https://cdn.example.com/b.mp3', durationSeconds: 30 },
+          { src: 'https://cdn.example.com/c.mp3', durationSeconds: 65 },
         ]}
       />
     )
+
     const bubble = screen.getByTestId('audio-attachment')
-    expect(bubble.querySelectorAll('audio')).toHaveLength(3)
+    expect(
+      bubble.querySelectorAll('[data-testid="audio-attachment-row"]')
+    ).toHaveLength(3)
+    expect(screen.getByText('01:05')).toBeInTheDocument()
+  })
+
+  it('disables playback for a MIME type the browser cannot play, but keeps the download', () => {
+    // `canPlayType` gates playback, and clicking play on an unplayable
+    // track is a no-op inside the player anyway — so the control says
+    // so. The file must still be retrievable.
+    renderAudio(
+      <MessageAttachment.Audio.Received
+        src="https://cdn.example.com/master.flac"
+        mimeType="audio/flac"
+        filename="master.flac"
+      />
+    )
+
+    expect(
+      screen.getByRole('button', { name: /^Play audio/ })
+    ).toBeDisabled()
+    expect(screen.getByRole('slider', { name: /^Seek audio/ })).toBeDisabled()
+    expect(
+      screen.getByRole('button', { name: /^Download audio/ })
+    ).toBeEnabled()
+  })
+
+  it('still renders the card without the audio-playback provider', () => {
+    // The pooled player lives on `<Channel>`. Outside one the card must
+    // degrade to an inert card rather than rendering nothing — a blank
+    // bubble is undiagnosable, and it would silently break every
+    // consumer that mounts an attachment outside a channel.
+    renderWithProviders(
+      <MessageAttachment.Audio.Sent
+        src="https://cdn.example.com/song.mp3"
+        durationSeconds={12}
+        waveformData={WAVEFORM}
+      />
+    )
+
+    expect(screen.getByTestId('audio-attachment')).toBeInTheDocument()
+    expect(screen.getAllByTestId('amplitude-bar')).toHaveLength(35)
+    expect(screen.getByText('00:12')).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: /^Play audio/ })).toBeDisabled()
   })
 })
 
@@ -951,60 +1107,6 @@ describe('MessageAttachment lazy-loading defaults', () => {
       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', () => {

package/src/components/MessageAttachment/index.tsx

@@ -56,7 +56,7 @@ import VideoAttachment, {
  *   - Pdf / Audio / File render their compact rows / players in a
  *     vertical stack with an 8px gap between rows. Each row keeps
  *     its own activation target — Pdf opens the carousel-aware
- *     `PdfViewer` at that index, Audio gets its own native player,
+ *     `PdfViewer` at that index, Audio gets its own waveform player,
  *     and File downloads the asset for that row.
  *
  * The Composer surface accepts only a single attachment at a time,
@@ -74,12 +74,29 @@ import VideoAttachment, {
  * download button to the chrome; the Video viewer relies on the
  * native `<video controls>` download menu, and the Pdf viewer
  * inherits the browser's built-in PDF download. Sibling-row Download
- * buttons on Pdf / File and the native `<audio>` controls expose
+ * buttons on Pdf / File and the Audio card's trailing action expose
  * downloads outside the viewer too. The lightbox chrome is styled
  * with plain CSS (`.mes-media-viewer*`) so the package's shipped
  * stylesheet is enough to render the viewer correctly without a
  * Tailwind dependency in the consumer.
  *
+ * # Audio requires a `<Channel>` ancestor
+ *
+ * `MessageAttachment.Audio.*` renders the waveform player card —
+ * a 32px play toggle, a 35-bar waveform with a progress fill and a
+ * native seek control, the duration, and a 32px trailing action
+ * (Remove in the composer, Download once sent). Playback is
+ * `stream-chat-react`'s pooled `AudioPlayer`, which is what supplies
+ * single-player-at-a-time across a thread, pause-on-navigation and
+ * saved-position restore across virtualized remounts.
+ *
+ * That pool is provided by `<Channel>`. Rendered outside one the card
+ * still draws in full, but its play and seek controls are disabled —
+ * so a story or a new consumer surface must mount `<Channel>` (or
+ * `stream-chat-react`'s `WithAudioPlayback`) for the card to be
+ * playable. The waveform bars themselves are styled with plain CSS
+ * (`.mes-audio-wave*`), so the shipped stylesheet is enough.
+ *
  * # Lazy-loading defaults
  *
  * Media attachments bake in network-friendly defaults for long chat
@@ -100,13 +117,12 @@ import VideoAttachment, {
  *     `VideoItem.preload` per item). Once the viewer is open the
  *     active item bumps to `preload="metadata"` so duration / the
  *     first frame appear immediately.
- *   - **Audio** — a single audio bubble defaults to
- *     `preload="metadata"` so the native player surfaces duration
- *     immediately. A stacked audio bubble (`items.length > 1`)
- *     defaults to `preload="none"` for every player so a thread of
- *     voice memos doesn't fan out N parallel metadata requests on
- *     first paint. Override via the attachment's `preload` prop
- *     (or `AudioItem.preload` per track).
+ *   - **Audio** — no audio bytes are fetched until the user presses
+ *     play: the pooled `AudioPlayer` acquires the shared `<audio>`
+ *     element lazily. A card whose `durationSeconds` is unknown makes
+ *     one `preload="metadata"` header request to fill the duration
+ *     slot; supplying `durationSeconds` (which `StreamAttachmentMessage`
+ *     maps from the attachment's persisted `duration`) avoids even that.
  *   - **Pdf** / **File** — no inline media element to throttle; the
  *     bubble renders compact rows that download / open lazily on
  *     activation. No `loading` / `preload` props on these surfaces.

package/src/components/MessageAttachment/types.ts

@@ -119,21 +119,31 @@ export interface PdfItem {
 /** A single audio file inside an Audio attachment (single or stacked). */
 export interface AudioItem {
   src: string
-  /** MIME type hint — typed onto the inline `<source>` element. */
+  /** MIME type hint — gates playability via the player's `canPlayType` probe. */
   mimeType?: string
   /**
-   * Filename — used as the download default name (consumed by the
-   * native player's kebab menu).
+   * Filename — the download default name for the card's trailing
+   * action, and part of the card's accessible name.
    */
   filename?: string
   /**
-   * Per-track override for the `<audio preload>` hint. Defaults to
-   * the parent attachment's `preload` value, which itself defaults
-   * to `'metadata'` for a single audio (so the native player can
-   * surface duration immediately) and `'none'` for a stacked thread
-   * (so a fan-out of metadata requests doesn't happen on first paint).
+   * Track length in seconds. Rendered as `MM:SS` before playback
+   * starts, so the duration is correct on first paint with no network
+   * request. Sourced from the Stream attachment's `duration` field,
+   * which the composer writes at send time. When omitted the card
+   * shows `--:--` until a one-shot `loadedmetadata` probe resolves.
    */
-  preload?: MediaPreloadMode
+  durationSeconds?: number
+  /**
+   * Waveform amplitudes, each `0..1`, in track order. Resampled to the
+   * rendered bar count, so any length is accepted. Sourced from the
+   * Stream attachment's `waveform_data`, which the composer computes
+   * from the local file and writes at send time.
+   *
+   * When omitted, the card renders a flat placeholder row: every bar at
+   * the minimum height, with the progress fill still tracking playback.
+   */
+  waveformData?: number[]
 }
 
 /** A single generic file inside a File attachment (single or stacked). */

package/src/styles.css

@@ -941,3 +941,123 @@
 .message-locked-attachment-text .str-chat__message-text-inner {
   color: inherit;
 }
+
+/* Audio attachment waveform — `MessageAttachment.Audio` (MES-1360).
+
+   Plain CSS rather than Tailwind utilities for two reasons: the per-bar
+   height is a floored custom property that has to be authored once
+   rather than repeated on 35 elements, and the played / unplayed fills
+   are the one design decision Figma left open (it draws the idle state
+   only), so keeping them in a single place is what makes them reviewable.
+   Follows the existing `.mes-media-viewer*` / `.mes-dialog` convention:
+   the package's shipped stylesheet is enough, with no Tailwind
+   dependency in the consumer.
+
+   Geometry is Figma `2754:17710` → `sound-wave` (`…;2754:8065`): a
+   138×30 track holding 35 bars at 2px with 2px gaps
+   (35 x 2 + 34 x 2 = 138). Bars flex from a zero basis, so the exact
+   2px falls out of the 138px track and a narrower container degrades
+   proportionally instead of clipping. */
+.mes-audio-wave {
+  position: relative;
+  display: flex;
+  flex: 1 1 0;
+  min-width: 0;
+  align-items: center;
+  height: 30px;
+}
+
+.mes-audio-wave__track {
+  display: flex;
+  width: 100%;
+  height: 100%;
+  align-items: center;
+  gap: 2px;
+}
+
+/* Figma's bars run 4px..30px on a 30px track, so the amplitude
+   percentage is floored at that 4px minimum: a silent sample — or the
+   all-zero fallback used when no waveform could be produced — still
+   draws the shortest bar the design already contains, keeping the
+   card's silhouette identical instead of collapsing it. */
+.mes-audio-wave__bar {
+  flex: 1 1 0;
+  min-width: 0;
+  height: max(4px, var(--mes-audio-wave-bar, 0%));
+  border-radius: 9999px;
+  background: rgb(255 255 255 / 0.4);
+}
+
+.mes-audio-wave__bar--played {
+  background: #ffffff;
+}
+
+.mes-audio-wave--light .mes-audio-wave__bar {
+  background: rgb(4 4 3 / 0.5);
+}
+
+.mes-audio-wave--light .mes-audio-wave__bar--played {
+  background: #040403;
+}
+
+/* Seek is a real `<input type="range">` stretched over the bars, which
+   supplies click, drag, arrow keys, Home / End and a screen-reader
+   slider role natively. The bars are the visible track, so the input
+   itself must not paint — but it must stay focusable, which is why the
+   thumb and track are cleared individually rather than the whole input
+   being given `opacity: 0`. */
+.mes-audio-wave__seek {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  cursor: pointer;
+  background: transparent;
+  -webkit-appearance: none;
+  appearance: none;
+}
+
+.mes-audio-wave__seek:disabled {
+  cursor: default;
+}
+
+.mes-audio-wave__seek::-webkit-slider-runnable-track {
+  background: transparent;
+}
+
+.mes-audio-wave__seek::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  width: 1px;
+  height: 100%;
+  opacity: 0;
+}
+
+.mes-audio-wave__seek::-moz-range-track {
+  background: transparent;
+}
+
+.mes-audio-wave__seek::-moz-range-thumb {
+  width: 1px;
+  height: 100%;
+  border: 0;
+  opacity: 0;
+}
+
+.mes-audio-wave__seek:focus {
+  outline: none;
+}
+
+/* The input is transparent, so the focus ring has to render on the
+   wrapper that actually has pixels. */
+.mes-audio-wave:has(.mes-audio-wave__seek:focus-visible) {
+  outline: 2px solid rgb(255 255 255 / 0.6);
+  outline-offset: 4px;
+  border-radius: 4px;
+}
+
+.mes-audio-wave--light:has(.mes-audio-wave__seek:focus-visible) {
+  outline-color: rgb(4 4 3 / 0.6);
+}