@linktr.ee/messaging-react 4.4.7 → 4.5.0-rc-1788297811

package/src/components/MessageAttachment/Audio/WaveformAudioRow.tsx

@@ -0,0 +1,455 @@
+import {
+  DownloadSimpleIcon,
+  PauseIcon,
+  PlayIcon,
+  XIcon,
+} from '@phosphor-icons/react'
+import classNames from 'classnames'
+import React from 'react'
+import {
+  displayDuration,
+  resampleWaveformData,
+  useAudioPlayer,
+  useStateStore,
+  type AudioPlayerState,
+} from 'stream-chat-react'
+
+import { triggerDownload } from '../_shared/triggerDownload'
+import { useIsClient } from '../_shared/useIsClient'
+import type { AudioItem, BubbleVariant } from '../types'
+
+/**
+ * Bar count in the design's waveform (Figma `2754:17710`, nodes
+ * `…;2754:8066` – `…;2754:8100`). The 138px track is exactly
+ * `35 × 2px bars + 34 × 2px gaps`, so the count is derived from the
+ * drawn geometry rather than picked.
+ */
+const WAVEFORM_BAR_COUNT = 35
+
+/**
+ * Total fallback for every case where no amplitudes exist: a decode
+ * failure, an unsupported codec, a re-staged zero-byte placeholder, a
+ * file over the composer's decode ceiling, or any attachment sent
+ * before `waveform_data` was persisted (legacy web, the mobile app, a
+ * visitor).
+ *
+ * `.mes-audio-wave__bar` floors every bar at the design's 4px minimum,
+ * so all 35 bars render as the shortest bar the design already draws:
+ * the card's silhouette, height and geometry are identical to a real
+ * waveform, and the progress fill still sweeps left to right during
+ * playback. A shape-changing degraded state (e.g. a plain progress
+ * bar) would read as a different feature.
+ */
+const FLAT_WAVEFORM: readonly number[] = Object.freeze(
+  new Array<number>(WAVEFORM_BAR_COUNT).fill(0)
+)
+
+/** Shown in the fixed duration slot until a duration is known. */
+const UNKNOWN_DURATION = '--:--'
+
+/**
+ * `displayDuration` splits the total into hour / minute buckets and only
+ * then `Math.ceil`s the seconds left over, so any fractional value in
+ * the last second of a minute formats as a sixtieth second: 59.5 renders
+ * `00:60`, and a playing clip flashes it at every minute boundary.
+ * Durations off an attachment and `secondsElapsed` off the player are
+ * both routinely fractional, so every call site floors first.
+ *
+ * Flooring (rather than rounding) is what the native `<audio>` element
+ * this card replaces did with `currentTime`: a clip reads `00:59` until
+ * the full minute has actually elapsed (MES-1360).
+ */
+const formatSeconds = (seconds: number): string =>
+  displayDuration(Math.floor(seconds))
+
+const AUDIO_PLAYER_STATE_SELECTOR = (state: AudioPlayerState) => ({
+  canPlayRecord: state.canPlayRecord,
+  isPlaying: state.isPlaying,
+  progressPercent: state.progressPercent,
+  secondsElapsed: state.secondsElapsed,
+})
+
+// Both of Figma's `content-control-buttons` instances (`…;2754:8063`
+// play, `…;2754:8102` trailing) are the same 32×32 pill with a 6px inset
+// around a 12px glyph and a 20px background blur; only the fill differs.
+const CONTROL_CLASS =
+  'flex size-8 shrink-0 items-center justify-center rounded-full backdrop-blur-[20px]'
+
+// Figma draws only the dark sender card (`fill:#1E2330`), with every
+// control in white. The light (`Received`) variant — the one visitors see
+// on linktr.ee-profiles — is undrawn, so it inverts the same treatment
+// against the `#f2f1ef` bubble. Ratios below were measured off the
+// composited render, not estimated:
+//
+//                          played  unplayed  played:unplayed  play button
+//   dark   on #1E2330      15.69      3.71             4.24        15.69
+//   light  on #F2F1EF      18.17      3.78             4.81        15.16
+//
+// Both unplayed fills clear WCAG 1.4.11's 3:1 floor for non-text contrast,
+// and the played/unplayed step is well past it so progress is legible on
+// its own. The light variant needs `#040403` at 0.5 where dark needs white
+// at 0.4, because it composites towards a lighter backdrop.
+const PLAY_BUTTON_BY_VARIANT: Record<BubbleVariant, string> = {
+  dark: 'bg-white text-black/90 disabled:bg-white/40',
+  light: 'bg-[#040403]/90 text-white disabled:bg-[#040403]/30',
+}
+
+const TRAILING_BUTTON_BY_VARIANT: Record<BubbleVariant, string> = {
+  dark: 'bg-[#040403]/80 text-white hover:bg-[#040403]',
+  light: 'bg-black/10 text-black/90 hover:bg-black/20',
+}
+
+/**
+ * What the design's trailing 32px control does. The ticket asks to
+ * "keep the same options as current production", and production has no
+ * product-owned menu on an audio attachment — the only menu was the
+ * native `<audio controls>` kebab, which disappears with the native
+ * player. So each surface carries forward the single action it already
+ * had: the composer removes the draft, and a sent / received card
+ * downloads the file (the capability the browser kebab provided).
+ */
+export type AudioRowTrailingAction =
+  { kind: 'dismiss'; onDismiss: () => void } | { kind: 'download' }
+
+export interface WaveformAudioRowProps {
+  item: AudioItem
+  variant: BubbleVariant
+  /**
+   * Omitted when a surface has no action to offer — a composer draft
+   * mounted without `onDismiss`. The row then renders no trailing
+   * control at all rather than falling through to the sent-only
+   * download, which is what the native player it replaces did.
+   */
+  trailingAction?: AudioRowTrailingAction
+  /**
+   * Namespaces the pooled `AudioPlayer`. Stream keys a pooled player by
+   * requester + source URL alone, so this has to be unique per rendered
+   * row, not just per message: two rows carrying the same `src` — a
+   * stacked bubble, or several cards in one story — otherwise share one
+   * player and move together. See `audioRowRequester`.
+   */
+  requester?: string
+}
+
+/**
+ * Resolves the track length. `durationSeconds` (persisted on the Stream
+ * attachment at send time) is authoritative and correct on first paint.
+ * Without it — legacy sends, mobile-app sends, visitor sends — a single
+ * detached `preload="metadata"` element resolves it from the response
+ * headers, which is exactly what the native player it replaces did.
+ */
+const useResolvedDuration = (
+  src: string,
+  durationSeconds?: number
+): number | undefined => {
+  const [probed, setProbed] = React.useState<number>()
+
+  React.useEffect(() => {
+    if (durationSeconds != null || !src) return
+
+    const probe = document.createElement('audio')
+    probe.preload = 'metadata'
+    const handleLoadedMetadata = () => {
+      if (Number.isFinite(probe.duration) && probe.duration > 0) {
+        setProbed(probe.duration)
+      }
+    }
+    probe.addEventListener('loadedmetadata', handleLoadedMetadata)
+    probe.src = src
+
+    return () => {
+      probe.removeEventListener('loadedmetadata', handleLoadedMetadata)
+      probe.removeAttribute('src')
+      setProbed(undefined)
+    }
+  }, [src, durationSeconds])
+
+  return durationSeconds ?? probed
+}
+
+/**
+ * One waveform player row: 32px play toggle, 35-bar waveform with a
+ * progress fill and a native seek control, the duration, and the 32px
+ * trailing action. A single-item bubble is the design's 299×72 card;
+ * a stacked bubble repeats the row.
+ *
+ * Playback is `stream-chat-react`'s pooled `AudioPlayer`, which gives
+ * single-player-at-a-time across the thread, pause-on-unmount and
+ * saved-position restore. That pool lives on `<Channel>`, so outside
+ * one the card still renders in full with its controls disabled rather
+ * than vanishing.
+ *
+ * Split in two on purpose. Every `stream-chat-react` playback hook
+ * lives in `LiveAudioRow`, which mounts only in the browser:
+ * `useAudioPlayer` constructs the pooled player during render and its
+ * constructor evaluates `new Audio().canPlayType(mimeType)`, while
+ * `useStateStore` calls `useSyncExternalStore` with no
+ * `getServerSnapshot`. Both throw under Node, so a host that
+ * server-renders a channel — profiles is Next.js — got an exception
+ * instead of markup. `AudioRowView` carries the markup and renders with
+ * inert playback on the server, which is the same card the component
+ * already shows outside a `<Channel>` (MES-1360).
+ */
+const WaveformAudioRow: React.FC<WaveformAudioRowProps> = (props) => {
+  const isClient = useIsClient()
+
+  return isClient ? (
+    <LiveAudioRow {...props} />
+  ) : (
+    <AudioRowView {...props} playback={INERT_PLAYBACK} />
+  )
+}
+
+/** Everything the view needs from a playback source, real or not. */
+interface RowPlayback {
+  playable: boolean
+  showPause: boolean
+  isStarting: boolean
+  /** 0–100. */
+  progress: number
+  secondsElapsed: number
+  /**
+   * Resolved by the live row, which may have probed for it. The view
+   * falls back to the attachment's own value, which is what the server
+   * render has.
+   */
+  durationSeconds?: number
+  trackRef?: React.Ref<HTMLDivElement>
+  onTogglePlay?: () => void
+  onSeek?: (event: React.ChangeEvent<HTMLInputElement>) => void
+}
+
+/**
+ * A card with no player behind it: what the server renders, and what a
+ * card mounted outside `<Channel>` degrades to.
+ */
+const INERT_PLAYBACK: RowPlayback = {
+  playable: false,
+  showPause: false,
+  isStarting: false,
+  progress: 0,
+  secondsElapsed: 0,
+}
+
+const LiveAudioRow: React.FC<WaveformAudioRowProps> = (props) => {
+  const { item, requester } = props
+  const trackRef = React.useRef<HTMLDivElement>(null)
+  const [isStarting, setIsStarting] = React.useState(false)
+  const durationSeconds = useResolvedDuration(item.src, item.durationSeconds)
+
+  const audioPlayer = useAudioPlayer({
+    durationSeconds,
+    mimeType: item.mimeType,
+    requester,
+    src: item.src,
+    title: item.filename,
+  })
+
+  const {
+    canPlayRecord = false,
+    isPlaying = false,
+    progressPercent = 0,
+    secondsElapsed = 0,
+  } = useStateStore(audioPlayer?.state, AUDIO_PLAYER_STATE_SELECTOR) ?? {}
+
+  const handleTogglePlay = () => {
+    if (!audioPlayer || isStarting) return
+    setIsStarting(true)
+    void audioPlayer.togglePlay().finally(() => setIsStarting(false))
+  }
+
+  // One seek code path for pointer, keyboard and drag: the native range
+  // input owns the interaction, and its value is translated into the
+  // `SeekFn` contract from the bar track's own rect. Going through
+  // `AudioPlayer.seek` inherits its lazy element acquisition (so
+  // seeking before the first play works), its seekable-range check and
+  // its 16ms throttle — `setSecondsElapsed` alone would not, because
+  // no `<audio>` element exists until the pool hands one over.
+  const handleSeek = (event: React.ChangeEvent<HTMLInputElement>) => {
+    const track = trackRef.current
+    if (!audioPlayer || !track) return
+    const ratio = Math.min(Math.max(Number(event.target.value) / 100, 0), 1)
+    const rect = track.getBoundingClientRect()
+    void audioPlayer.seek({
+      clientX: rect.x + ratio * rect.width,
+      currentTarget: track,
+    })
+  }
+
+  return (
+    <AudioRowView
+      {...props}
+      playback={{
+        playable: !!audioPlayer && canPlayRecord,
+        // Strictly `isPlaying`. Flipping to Pause on `isStarting` gave a
+        // slow load a Pause control that looked live but swallowed every
+        // press, because `handleTogglePlay` returns early while a toggle
+        // is in flight — and assistive tech announced "Pause audio" for
+        // it. The start is advertised through `aria-busy` instead
+        // (MES-1360).
+        showPause: isPlaying,
+        isStarting,
+        progress: Math.min(Math.max(progressPercent, 0), 100),
+        secondsElapsed,
+        durationSeconds,
+        trackRef,
+        onTogglePlay: handleTogglePlay,
+        onSeek: handleSeek,
+      }}
+    />
+  )
+}
+
+/**
+ * The card's markup, with no playback source of its own. Rendered
+ * directly (with `INERT_PLAYBACK`) wherever Stream's hooks can't run.
+ */
+const AudioRowView: React.FC<
+  WaveformAudioRowProps & { playback: RowPlayback }
+> = ({ item, variant, trailingAction, playback }) => {
+  const {
+    isStarting,
+    onSeek,
+    onTogglePlay,
+    playable,
+    progress,
+    secondsElapsed,
+    showPause,
+    trackRef,
+  } = playback
+
+  // An empty array must never reach `resampleWaveformData` — its
+  // `upSample` branch `console.warn`s and returns `[]`, which renders no
+  // bars at all (and trips consumers whose tests fail on console output).
+  const amplitudes = React.useMemo<readonly number[]>(() => {
+    const data = item.waveformData
+    if (!data || data.length === 0) return FLAT_WAVEFORM
+    if (data.length === WAVEFORM_BAR_COUNT) return data
+    return resampleWaveformData(data, WAVEFORM_BAR_COUNT)
+  }, [item.waveformData])
+
+  const durationSeconds = playback.durationSeconds ?? item.durationSeconds
+  const totalLabel =
+    durationSeconds == null ? UNKNOWN_DURATION : formatSeconds(durationSeconds)
+  // Mirrors the native player: the slot counts up while playing and
+  // holds the elapsed position when paused, falling back to the total.
+  const displayedLabel =
+    secondsElapsed > 0 ? formatSeconds(secondsElapsed) : totalLabel
+
+  // Suffixed onto each control's accessible name so a thread of stacked
+  // clips reads as "Play audio — take-2.mp3", not three identical labels.
+  const label = item.filename ? ` \u2014 ${item.filename}` : ''
+
+  return (
+    <div
+      role="group"
+      aria-label={item.filename ?? 'Audio attachment'}
+      className="flex items-center"
+      data-testid="audio-attachment-row"
+    >
+      <button
+        type="button"
+        onClick={onTogglePlay}
+        disabled={!playable}
+        aria-busy={isStarting || undefined}
+        aria-label={`${showPause ? 'Pause audio' : 'Play audio'}${label}`}
+        className={classNames(CONTROL_CLASS, PLAY_BUTTON_BY_VARIANT[variant])}
+      >
+        {showPause ? (
+          <PauseIcon className="size-3" weight="fill" aria-hidden />
+        ) : (
+          <PlayIcon className="size-3" weight="fill" aria-hidden />
+        )}
+      </button>
+
+      {/* Figma `soundwave-container` (…;2754:8064): 203×30, 10px gap,
+          12px horizontal inset, waveform flexing against a fixed
+          duration slot. */}
+      <div className="flex min-w-0 flex-1 items-center gap-2.5 px-3">
+        <div
+          className={classNames(
+            'mes-audio-wave',
+            variant === 'light' && 'mes-audio-wave--light'
+          )}
+        >
+          {/* The bars carry no information a screen reader can use —
+              elapsed / total is announced by the range input below —
+              so they stay out of the accessibility tree entirely. */}
+          <div
+            ref={trackRef}
+            className="mes-audio-wave__track"
+            aria-hidden
+            data-testid="audio-waveform-track"
+          >
+            {amplitudes.map((amplitude, index) => (
+              <span
+                // Bars are positional, and the array is a fixed-length
+                // resample of the same track — index is the identity.
+                key={index}
+                data-testid="amplitude-bar"
+                className={classNames(
+                  'mes-audio-wave__bar',
+                  progress > (index / amplitudes.length) * 100 &&
+                    'mes-audio-wave__bar--played'
+                )}
+                style={
+                  {
+                    '--mes-audio-wave-bar': `${
+                      Math.min(Math.max(amplitude, 0), 1) * 100
+                    }%`,
+                  } as React.CSSProperties
+                }
+              />
+            ))}
+          </div>
+          <input
+            type="range"
+            className="mes-audio-wave__seek"
+            min={0}
+            max={100}
+            step={0.1}
+            value={progress}
+            onChange={onSeek}
+            disabled={!playable}
+            aria-label={`Seek audio${label}`}
+            aria-valuetext={`${formatSeconds(secondsElapsed)} of ${totalLabel}`}
+          />
+        </div>
+
+        <span className="shrink-0 text-xs leading-4 tracking-[0.24px] tabular-nums">
+          {displayedLabel}
+        </span>
+      </div>
+
+      {trailingAction ? (
+        <button
+          type="button"
+          onClick={
+            trailingAction.kind === 'dismiss'
+              ? trailingAction.onDismiss
+              : () => {
+                  void triggerDownload(item.src, item.filename)
+                }
+          }
+          aria-label={
+            trailingAction.kind === 'dismiss'
+              ? 'Remove attachment'
+              : `Download audio${label}`
+          }
+          className={classNames(
+            CONTROL_CLASS,
+            TRAILING_BUTTON_BY_VARIANT[variant]
+          )}
+        >
+          {trailingAction.kind === 'dismiss' ? (
+            <XIcon className="size-3" weight="bold" aria-hidden />
+          ) : (
+            <DownloadSimpleIcon className="size-3" weight="bold" aria-hidden />
+          )}
+        </button>
+      ) : null}
+    </div>
+  )
+}
+
+export default WaveformAudioRow

package/src/components/MessageAttachment/Audio/audioRowRequester.test.ts

@@ -0,0 +1,24 @@
+import { describe, expect, it } from 'vitest'
+
+import { audioRowRequester } from './audioRowRequester'
+
+describe('audioRowRequester', () => {
+  it('gives each row in a message its own namespace', () => {
+    // Stream keys a pooled player by requester + src, so rows sharing a
+    // src under one message id would otherwise be the same player and
+    // move together.
+    expect(audioRowRequester('msg-1', 0)).not.toBe(
+      audioRowRequester('msg-1', 1)
+    )
+  })
+
+  it('keeps separate messages apart', () => {
+    expect(audioRowRequester('msg-1', 0)).not.toBe(
+      audioRowRequester('msg-2', 0)
+    )
+  })
+
+  it('is stable for the same row, so a remount restores its position', () => {
+    expect(audioRowRequester('msg-1', 2)).toBe(audioRowRequester('msg-1', 2))
+  })
+})

package/src/components/MessageAttachment/Audio/audioRowRequester.ts

@@ -0,0 +1,16 @@
+/**
+ * Namespace for one rendered audio row's pooled player.
+ *
+ * Stream keys a pooled `AudioPlayer` by requester + source URL alone
+ * (`makeAudioPlayerId`), so two rows showing the same asset under the
+ * same requester resolve to a single player and share play state,
+ * progress and elapsed time. That is reachable today: a stacked bubble
+ * repeating a clip, several cards for one attachment, or the `Single`
+ * story, which renders the same URL three times.
+ *
+ * The row index disambiguates them and is stable across re-renders and
+ * remounts, so a message-scoped base still restores its saved position
+ * when a virtualized thread scrolls the row away and back (MES-1360).
+ */
+export const audioRowRequester = (base: string, index: number): string =>
+  `${base}:${index}`