@proteos/ui 0.77.0 → 0.79.0

package/src/components/media-player/media-player.test.tsx

@@ -0,0 +1,318 @@
+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import type { ReactNode } from 'react'
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { MediaControls } from './media-controls'
+import { decodePeaks } from './media-peaks'
+import { MediaPlayer, MediaStage, useMediaPlayer } from './media-player'
+import { fitMediaBox, MediaVideoStage } from './media-video-stage'
+import { MediaWaveform } from './media-waveform'
+
+vi.mock('wavesurfer.js', () => ({
+  default: { create: vi.fn(() => ({ destroy: vi.fn(), setOptions: vi.fn() })) },
+}))
+vi.mock('./media-peaks', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('./media-peaks')>()),
+  decodePeaks: vi.fn(async () => ({ peaks: new Float32Array([1, 1, 1, 1]), duration: 120 })),
+}))
+
+const blob = new Blob(['audio'], { type: 'audio/mpeg' })
+
+function audioElement(): HTMLAudioElement {
+  const element = document.querySelector('audio')
+  if (!element) throw new Error('no audio element')
+  return element
+}
+
+function videoElement(): HTMLVideoElement {
+  const element = document.querySelector('video')
+  if (!element) throw new Error('no video element')
+  return element
+}
+
+/** jsdom has no media pipeline: stand in for what a loaded file reports. */
+function loadMedia(duration = 120, element: HTMLMediaElement = audioElement()) {
+  Object.defineProperty(element, 'duration', { configurable: true, value: duration })
+  let paused = true
+  Object.defineProperty(element, 'paused', { configurable: true, get: () => paused })
+  element.play = vi.fn(async () => {
+    paused = false
+    fireEvent.play(element)
+  })
+  element.pause = vi.fn(() => {
+    paused = true
+    fireEvent.pause(element)
+  })
+  fireEvent.loadedMetadata(element)
+  return element
+}
+
+function renderPlayer(props: Partial<Parameters<typeof MediaWaveform>[0]> = {}) {
+  return render(
+    <MediaPlayer source={{ blob }} label="Call recording">
+      <MediaStage>
+        <MediaWaveform {...props} />
+      </MediaStage>
+      <MediaControls />
+    </MediaPlayer>,
+  )
+}
+
+beforeEach(() => {
+  URL.createObjectURL = vi.fn(() => 'blob:recording')
+  URL.revokeObjectURL = vi.fn()
+  global.ResizeObserver = class {
+    observe() {}
+    disconnect() {}
+    unobserve() {}
+  } as unknown as typeof ResizeObserver
+})
+
+describe('MediaPlayer', () => {
+  it('names its region and plays the blob locally', () => {
+    renderPlayer()
+    expect(screen.getByRole('region', { name: 'Call recording' })).toBeInTheDocument()
+    expect(audioElement()).toHaveAttribute('src', 'blob:recording')
+  })
+
+  it('keeps controls disabled until the media loads', () => {
+    renderPlayer()
+    expect(screen.getByRole('button', { name: 'Play' })).toBeDisabled()
+    loadMedia()
+    expect(screen.getByRole('button', { name: 'Play' })).toBeEnabled()
+    expect(screen.getByText('02:00')).toBeInTheDocument()
+  })
+
+  it('toggles between play and pause', async () => {
+    const user = userEvent.setup()
+    renderPlayer()
+    const element = loadMedia()
+    await user.click(screen.getByRole('button', { name: 'Play' }))
+    expect(element.play).toHaveBeenCalled()
+    await user.click(await screen.findByRole('button', { name: 'Pause' }))
+    expect(element.pause).toHaveBeenCalled()
+  })
+
+  it('stop pauses and returns to the start', async () => {
+    const user = userEvent.setup()
+    renderPlayer()
+    const element = loadMedia()
+    element.currentTime = 50
+    await user.click(screen.getByRole('button', { name: 'Stop' }))
+    expect(element.pause).toHaveBeenCalled()
+    expect(element.currentTime).toBe(0)
+  })
+
+  it('skips ten seconds, clamped to the recording', async () => {
+    const user = userEvent.setup()
+    renderPlayer()
+    const element = loadMedia(120)
+    element.currentTime = 115
+    await user.click(screen.getByRole('button', { name: 'Forward 10 seconds' }))
+    expect(element.currentTime).toBe(120)
+    element.currentTime = 5
+    await user.click(screen.getByRole('button', { name: 'Back 10 seconds' }))
+    expect(element.currentTime).toBe(0)
+  })
+
+  it('cycles the playback speed', async () => {
+    const user = userEvent.setup()
+    renderPlayer()
+    const element = loadMedia()
+    await user.click(screen.getByRole('button', { name: 'Playback speed 1 times' }))
+    expect(element.playbackRate).toBe(1.25)
+    expect(screen.getByRole('button', { name: 'Playback speed 1.25 times' })).toBeInTheDocument()
+  })
+
+  it('reports an unplayable file', () => {
+    const onError = vi.fn()
+    render(
+      <MediaPlayer source={{ blob }} label="Call recording" onError={onError}>
+        <MediaControls />
+      </MediaPlayer>,
+    )
+    fireEvent.error(audioElement())
+    expect(onError).toHaveBeenCalled()
+  })
+
+  it('releases the blob and stops when unmounted', () => {
+    const { unmount } = renderPlayer()
+    const element = loadMedia()
+    unmount()
+    expect(element.pause).toHaveBeenCalled()
+    expect(URL.revokeObjectURL).toHaveBeenCalledWith('blob:recording')
+  })
+
+  it('announces the position through the slider', () => {
+    renderPlayer()
+    const element = loadMedia(120)
+    act(() => {
+      element.currentTime = 48
+      fireEvent.timeUpdate(element)
+    })
+    expect(screen.getByRole('slider', { name: 'Seek' })).toHaveAttribute(
+      'aria-valuetext',
+      '48 seconds of 2 minutes',
+    )
+  })
+
+  it('keeps the transport without its seek row when another scrubber owns seeking', () => {
+    render(
+      <MediaPlayer source={{ blob }} label="Call recording">
+        <MediaControls hasSeek={false} />
+      </MediaPlayer>,
+    )
+    loadMedia()
+    expect(screen.queryByRole('slider', { name: 'Seek' })).not.toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Play' })).toBeInTheDocument()
+  })
+
+  it('streams a url and draws the peaks it was given', () => {
+    render(
+      <MediaPlayer
+        source={{ url: 'https://example.test/call.mp3', peaks: new Float32Array(4), duration: 90 }}
+        label="Call recording"
+      >
+        <MediaControls />
+      </MediaPlayer>,
+    )
+    expect(audioElement()).toHaveAttribute('src', 'https://example.test/call.mp3')
+    expect(URL.createObjectURL).not.toHaveBeenCalled()
+  })
+})
+
+describe('MediaWaveform', () => {
+  it('says so when the waveform library fails, and keeps playback', async () => {
+    const { default: WaveSurfer } = await import('wavesurfer.js')
+    vi.mocked(WaveSurfer.create).mockImplementationOnce(() => {
+      throw new Error('chunk failed')
+    })
+    renderPlayer()
+    loadMedia()
+    expect(await screen.findByText(/Waveform isn’t available/)).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Play' })).toBeEnabled()
+  })
+
+  const lanes = [
+    { key: 'a', label: 'Dana', meta: '00:40', segments: [[0, 10]] as const },
+    { key: 'b', label: 'You', meta: '00:20', segments: [[10, 20]] as const },
+  ]
+
+  it('names each lane with its fact', () => {
+    renderPlayer({ lanes })
+    expect(screen.getByText('Dana')).toBeInTheDocument()
+    expect(screen.getByText('00:40')).toBeInTheDocument()
+    expect(screen.getByText('You')).toBeInTheDocument()
+  })
+
+  it('marks whoever is speaking at the current time', () => {
+    renderPlayer({ lanes })
+    const element = loadMedia()
+    act(() => {
+      element.currentTime = 12
+      fireEvent.timeUpdate(element)
+    })
+    expect(screen.getByText('You').parentElement).toHaveAttribute('data-active', 'true')
+    expect(screen.getByText('Dana').parentElement).not.toHaveAttribute('data-active')
+  })
+
+  it('shows no names for the one unnamed lane', () => {
+    renderPlayer()
+    expect(screen.queryByText('Dana')).not.toBeInTheDocument()
+  })
+
+  it('reports while the waveform is being drawn', async () => {
+    renderPlayer()
+    expect(screen.getByText('Drawing waveform')).toBeInTheDocument()
+    await waitFor(() => expect(screen.queryByText('Drawing waveform')).not.toBeInTheDocument())
+  })
+
+  it('jumps to a marker', async () => {
+    const user = userEvent.setup()
+    renderPlayer({
+      markers: [{ key: 'tag', label: 'Pricing', start: 30, end: 40 }],
+      markersLabel: 'Tags',
+    })
+    const element = loadMedia()
+    await user.click(screen.getByRole('button', { name: 'Pricing, at 00:30' }))
+    expect(element.currentTime).toBe(30)
+    expect(screen.getByText('Tags')).toBeInTheDocument()
+  })
+})
+
+describe('MediaVideoStage', () => {
+  const recording = new Blob(['video'], { type: 'video/webm' })
+
+  function renderVideo(overlay?: ReactNode, probe?: ReactNode) {
+    return render(
+      <MediaPlayer source={{ blob: recording, duration: 8 }} label="Screen recording" kind="video">
+        <MediaVideoStage>{overlay}</MediaVideoStage>
+        {probe}
+        <MediaControls />
+      </MediaPlayer>,
+    )
+  }
+
+  it('plays through an inline video element instead of audio', () => {
+    renderVideo()
+    const video = videoElement()
+    expect(video).toHaveAttribute('src', 'blob:recording')
+    expect(video).toHaveAttribute('playsinline')
+    expect(document.querySelector('audio')).toBeNull()
+    expect(screen.getByRole('button', { name: 'Play' })).toBeDisabled()
+    // A MediaRecorder webm reports no length; the source's duration stands in.
+    loadMedia(Number.POSITIVE_INFINITY, video)
+    expect(screen.getByRole('button', { name: 'Play' })).toBeEnabled()
+    expect(screen.getByText('00:08')).toBeInTheDocument()
+  })
+
+  it('drives the video from the controls', async () => {
+    const user = userEvent.setup()
+    renderVideo()
+    const video = loadMedia(Number.POSITIVE_INFINITY, videoElement())
+    await user.click(screen.getByRole('button', { name: 'Play' }))
+    expect(video.play).toHaveBeenCalled()
+    video.currentTime = 5
+    await user.click(screen.getByRole('button', { name: 'Forward 10 seconds' }))
+    expect(video.currentTime).toBe(8)
+  })
+
+  it('draws the overlay in the same box as the picture', () => {
+    renderVideo(<span>ink</span>)
+    const overlay = screen.getByText('ink').parentElement
+    expect(overlay).not.toBeNull()
+    expect(overlay?.parentElement).toBe(videoElement().parentElement)
+  })
+
+  it('plays on without a waveform when the bytes hold no audio', async () => {
+    vi.mocked(decodePeaks).mockRejectedValueOnce(new Error('no audio track'))
+    const statuses: string[] = []
+    function Probe() {
+      statuses.push(useMediaPlayer().waveformStatus)
+      return null
+    }
+    renderVideo(undefined, <Probe />)
+    await waitFor(() => expect(statuses.at(-1)).toBe('unavailable'))
+    loadMedia(Number.POSITIVE_INFINITY, videoElement())
+    expect(screen.getByRole('button', { name: 'Play' })).toBeEnabled()
+  })
+})
+
+describe('fitMediaBox', () => {
+  it('is bound by height in a wide stage', () => {
+    expect(fitMediaBox(1000, 300, 2)).toEqual({ width: 600, height: 300 })
+  })
+
+  it('is bound by width in a tall stage', () => {
+    expect(fitMediaBox(400, 1000, 2)).toEqual({ width: 400, height: 200 })
+  })
+
+  it('is bound by width when the stage has no height yet', () => {
+    expect(fitMediaBox(400, 0, 2)).toEqual({ width: 400, height: 200 })
+  })
+
+  it('is empty without a width', () => {
+    expect(fitMediaBox(0, 300, 2)).toEqual({ width: 0, height: 0 })
+  })
+})

package/src/components/media-player/media-player.tsx

@@ -0,0 +1,334 @@
+import {
+  createContext,
+  type KeyboardEvent,
+  type ReactNode,
+  type Ref,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useState,
+} from 'react'
+import { tv, type VariantProps } from 'tailwind-variants'
+
+import { cn } from '../../lib/cn'
+import { type DecodedPeaks, decodePeaks, MAX_DECODE_BYTES } from './media-peaks'
+
+/* =========================================================================
+   MediaPlayer — chrome-free root of a recording player: owns the media
+   element's state; slots compose beneath it.
+
+     <MediaPlayer source={{ blob }} label="Call recording">
+       <MediaStage><MediaWaveform lanes={lanes} markers={markers} /></MediaStage>
+       <MediaControls />
+     </MediaPlayer>
+
+     <MediaPlayer source={{ blob, duration }} label="Screen recording" kind="video">
+       <MediaVideoStage>{overlay}</MediaVideoStage>
+       <MediaTimeline markers={markers} />
+       <MediaControls />
+     </MediaPlayer>
+
+   The source is a `blob` (whole file local, bars decoded in the browser) or a
+   `url` (bytes streamed; bars only with pre-computed peaks). `duration` is
+   the consumer's authoritative length for files whose container reports
+   none — a MediaRecorder webm says Infinity until it has been played through.
+   The player knows nothing about how the bytes were authorized.
+
+   `kind` names the element. `audio` (the default) is rendered here, unseen.
+   `video` is rendered by a `MediaVideoStage` child through `mediaRef`, so the
+   picture sits wherever the consumer lays it out.
+   ========================================================================= */
+
+export const mediaPlayerStyles = tv({
+  slots: {
+    root: 'flex min-h-0 flex-1 flex-col',
+    stage: 'relative flex min-h-0 flex-1 flex-col',
+  },
+})
+
+export type MediaPlayerVariants = VariantProps<typeof mediaPlayerStyles>
+
+export type MediaPlayerSource =
+  | { blob: Blob; duration?: number }
+  | { url: string; peaks?: Float32Array; duration?: number }
+
+export type MediaPlayerKind = 'audio' | 'video'
+
+/** Whether bars can be drawn yet. `unavailable`: playable, but no waveform. */
+export type MediaWaveformStatus = 'decoding' | 'ready' | 'unavailable'
+
+export interface MediaPlayerContextValue {
+  media: HTMLMediaElement | null
+  /** Callback ref for the element that plays. `MediaVideoStage` hands it its `<video>`. */
+  mediaRef: (element: HTMLMediaElement | null) => void
+  /** What the element loads; null until a blob has its object URL. */
+  src: string | null
+  isReady: boolean
+  isPlaying: boolean
+  currentTime: number
+  duration: number
+  playbackRate: number
+  waveformStatus: MediaWaveformStatus
+  decoded: DecodedPeaks | null
+  toggle: () => void
+  stop: () => void
+  seek: (seconds: number) => void
+  skip: (seconds: number) => void
+  setPlaybackRate: (rate: number) => void
+}
+
+const MediaPlayerContext = createContext<MediaPlayerContextValue | null>(null)
+
+export function useMediaPlayer(): MediaPlayerContextValue {
+  const context = useContext(MediaPlayerContext)
+  if (!context) throw new Error('useMediaPlayer must be used inside a MediaPlayer')
+  return context
+}
+
+const HAVE_METADATA = 1
+
+export interface MediaPlayerProps {
+  source: MediaPlayerSource
+  /** Names the player's region for assistive tech. */
+  label: string
+  /** Which element plays; `video` expects a `MediaVideoStage` among the children. */
+  kind?: MediaPlayerKind
+  /** The element can't play these bytes. */
+  onError?: () => void
+  className?: string
+  children: ReactNode
+}
+
+export function MediaPlayer({
+  source,
+  label,
+  kind = 'audio',
+  onError,
+  className,
+  children,
+}: MediaPlayerProps) {
+  const [media, setMedia] = useState<HTMLMediaElement | null>(null)
+  const [src, setSrc] = useState<string | null>(null)
+  // The element whose metadata has loaded; a replacement element starts over.
+  const [loaded, setLoaded] = useState<HTMLMediaElement | null>(null)
+  const [isPlaying, setIsPlaying] = useState(false)
+  const [currentTime, setCurrentTime] = useState(0)
+  const [mediaDuration, setMediaDuration] = useState(0)
+  const [playbackRate, setPlaybackRateState] = useState(1)
+  const [waveformStatus, setWaveformStatus] = useState<MediaWaveformStatus>('decoding')
+  const [decoded, setDecoded] = useState<DecodedPeaks | null>(null)
+
+  const blob = 'blob' in source ? source.blob : null
+  const url = 'url' in source ? source.url : null
+  const givenPeaks = 'url' in source ? (source.peaks ?? null) : null
+  const givenDuration = source.duration ?? null
+
+  useEffect(() => {
+    if (!blob) {
+      setSrc(url)
+      return
+    }
+    const objectUrl = URL.createObjectURL(blob)
+    setSrc(objectUrl)
+    return () => URL.revokeObjectURL(objectUrl)
+  }, [blob, url])
+
+  useEffect(() => {
+    if (!blob) {
+      if (givenPeaks && givenDuration !== null) {
+        setDecoded({ peaks: givenPeaks, duration: givenDuration })
+        setWaveformStatus('ready')
+      } else {
+        // Streamed bytes can't be decoded here; without peaks there are no bars.
+        setDecoded(null)
+        setWaveformStatus('unavailable')
+      }
+      return
+    }
+    setDecoded(null)
+    if (blob.size > MAX_DECODE_BYTES) {
+      setWaveformStatus('unavailable')
+      return
+    }
+    setWaveformStatus('decoding')
+    let isCancelled = false
+    decodePeaks(blob)
+      .then((result) => {
+        if (isCancelled) return
+        setDecoded(result)
+        setWaveformStatus('ready')
+      })
+      .catch(() => {
+        // Bars are a convenience: bytes the decoder rejects (video without an
+        // audio track, a format it doesn't know) may still play.
+        if (!isCancelled) setWaveformStatus('unavailable')
+      })
+    return () => {
+      isCancelled = true
+    }
+  }, [blob, givenPeaks, givenDuration])
+
+  useEffect(() => {
+    if (!media) return
+    const syncTime = () => setCurrentTime(media.currentTime)
+    const syncDuration = () =>
+      setMediaDuration(Number.isFinite(media.duration) ? media.duration : 0)
+    const syncLoaded = () => {
+      setLoaded(media)
+      syncDuration()
+    }
+    const syncEmptied = () => {
+      setLoaded(null)
+      setMediaDuration(0)
+      setCurrentTime(0)
+    }
+    const syncPlaying = () => setIsPlaying(!media.paused && !media.ended)
+    const handleError = () => onError?.()
+    // A cached source may have loaded before this ran.
+    if (media.readyState >= HAVE_METADATA) syncLoaded()
+    const events: Array<[string, () => void]> = [
+      ['timeupdate', syncTime],
+      ['seeked', syncTime],
+      ['loadedmetadata', syncLoaded],
+      ['durationchange', syncDuration],
+      ['emptied', syncEmptied],
+      ['play', syncPlaying],
+      ['pause', syncPlaying],
+      ['ended', syncPlaying],
+      ['error', handleError],
+    ]
+    for (const [name, handler] of events) media.addEventListener(name, handler)
+    return () => {
+      for (const [name, handler] of events) media.removeEventListener(name, handler)
+      media.pause()
+    }
+  }, [media, onError])
+
+  // The element's own length when it has one; the consumer's word otherwise;
+  // what the decoder heard as a last resort.
+  const duration = mediaDuration || givenDuration || decoded?.duration || 0
+  const isReady = media !== null && loaded === media
+
+  const toggle = useCallback(() => {
+    if (!media) return
+    if (media.paused || media.ended) {
+      // A rejection here is a pause racing the play, or an unplayable file,
+      // which the element's own `error` event reports.
+      void media.play().catch(() => undefined)
+    } else {
+      media.pause()
+    }
+  }, [media])
+
+  const seek = useCallback(
+    (seconds: number) => {
+      if (!media) return
+      const limit = Number.isFinite(media.duration)
+        ? media.duration
+        : duration > 0
+          ? duration
+          : seconds
+      const next = Math.max(0, Math.min(limit, seconds))
+      media.currentTime = next
+      setCurrentTime(next)
+    },
+    [media, duration],
+  )
+
+  const skip = useCallback(
+    (seconds: number) => {
+      if (media) seek(media.currentTime + seconds)
+    },
+    [media, seek],
+  )
+
+  const stop = useCallback(() => {
+    media?.pause()
+    seek(0)
+  }, [media, seek])
+
+  const setPlaybackRate = useCallback(
+    (rate: number) => {
+      if (media) media.playbackRate = rate
+      setPlaybackRateState(rate)
+    },
+    [media],
+  )
+
+  const value = useMemo<MediaPlayerContextValue>(
+    () => ({
+      media,
+      mediaRef: setMedia,
+      src,
+      isReady,
+      isPlaying,
+      currentTime,
+      duration,
+      playbackRate,
+      waveformStatus,
+      decoded,
+      toggle,
+      stop,
+      seek,
+      skip,
+      setPlaybackRate,
+    }),
+    [
+      media,
+      src,
+      isReady,
+      isPlaying,
+      currentTime,
+      duration,
+      playbackRate,
+      waveformStatus,
+      decoded,
+      toggle,
+      stop,
+      seek,
+      skip,
+      setPlaybackRate,
+    ],
+  )
+
+  // Space plays from anywhere in the player; buttons and the slider keep theirs.
+  const handleKeyDown = (event: KeyboardEvent<HTMLElement>) => {
+    if (event.code !== 'Space') return
+    if ((event.target as HTMLElement).closest('button, input')) return
+    event.preventDefault()
+    toggle()
+  }
+
+  return (
+    <MediaPlayerContext.Provider value={value}>
+      <section
+        aria-label={label}
+        onKeyDown={handleKeyDown}
+        className={cn(mediaPlayerStyles().root(), className)}
+      >
+        {kind === 'audio' ? (
+          <audio ref={setMedia} preload="metadata" {...(src ? { src } : {})} />
+        ) : null}
+        {children}
+      </section>
+    </MediaPlayerContext.Provider>
+  )
+}
+
+/** Where the picture goes: waveform lanes, or a `MediaVideoStage`. */
+export function MediaStage({
+  ref,
+  className,
+  children,
+}: {
+  ref?: Ref<HTMLDivElement>
+  className?: string
+  children: ReactNode
+}) {
+  return (
+    <div ref={ref} className={cn(mediaPlayerStyles().stage(), className)}>
+      {children}
+    </div>
+  )
+}

package/src/components/media-player/media-time.ts

@@ -0,0 +1,27 @@
+const pad = (value: number) => String(value).padStart(2, '0')
+
+/** `02:36`, or `1:02:36` past the hour. */
+export function formatMediaTime(seconds: number): string {
+  const total = Math.max(0, Math.floor(Number.isFinite(seconds) ? seconds : 0))
+  const hours = Math.floor(total / 3600)
+  const minutes = Math.floor((total % 3600) / 60)
+  const rest = total % 60
+  return hours > 0 ? `${hours}:${pad(minutes)}:${pad(rest)}` : `${pad(minutes)}:${pad(rest)}`
+}
+
+const unit = (value: number, name: string) => `${value} ${name}${value === 1 ? '' : 's'}`
+
+/** `2 minutes 36 seconds`, for screen readers. */
+export function spokenMediaTime(seconds: number): string {
+  const total = Math.max(0, Math.floor(Number.isFinite(seconds) ? seconds : 0))
+  const hours = Math.floor(total / 3600)
+  const minutes = Math.floor((total % 3600) / 60)
+  const rest = total % 60
+  return [
+    hours > 0 ? unit(hours, 'hour') : '',
+    minutes > 0 ? unit(minutes, 'minute') : '',
+    rest > 0 || total === 0 ? unit(rest, 'second') : '',
+  ]
+    .filter(Boolean)
+    .join(' ')
+}