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

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

@@ -0,0 +1,171 @@
+import {
+  CaretLeftIcon,
+  CaretRightIcon,
+} from '@phosphor-icons/react'
+import React, { useCallback, useEffect, useMemo, useState } from 'react'
+
+import type { MediaPreloadMode } from '../types'
+
+import DownloadAction from './DownloadAction'
+import { filenameFromUrl } from './fileMeta'
+import ViewerShell from './ViewerShell'
+
+export interface VideoViewerItem {
+  src: string
+  poster?: string
+  mimeType?: string
+  filename?: string
+  /**
+   * Per-item `<video preload>` override. Defaults to `'metadata'`
+   * for the active item so duration / first-frame are available
+   * immediately. Non-active siblings aren't mounted here (we render
+   * only `items[index]` at a time via a `key` swap), so they
+   * naturally stay unloaded.
+   */
+  preload?: MediaPreloadMode
+}
+
+export interface VideoViewerProps {
+  open: boolean
+  items: VideoViewerItem[]
+  initialIndex?: number
+  onClose: () => void
+}
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(Math.max(value, min), max)
+
+/**
+ * Full-viewport video viewer used by every `MessageAttachment.Video.*`
+ * variant. Renders a single `<video controls>` element with the
+ * browser's native play / pause / seek / fullscreen / volume chrome,
+ * plus a download action in the toolbar and arrow-key navigation
+ * between stacked items.
+ */
+const VideoViewer: React.FC<VideoViewerProps> = ({
+  open,
+  items,
+  initialIndex = 0,
+  onClose,
+}) => {
+  const safeIndex = clamp(initialIndex, 0, Math.max(items.length - 1, 0))
+  const [index, setIndex] = useState(safeIndex)
+
+  useEffect(() => {
+    if (!open) return
+    setIndex(clamp(initialIndex, 0, Math.max(items.length - 1, 0)))
+  }, [open, initialIndex, items.length])
+
+  const goPrev = useCallback(
+    () => setIndex((i) => (i <= 0 ? items.length - 1 : i - 1)),
+    [items.length]
+  )
+  const goNext = useCallback(
+    () => setIndex((i) => (i >= items.length - 1 ? 0 : i + 1)),
+    [items.length]
+  )
+
+  useEffect(() => {
+    if (!open || items.length <= 1) return undefined
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'ArrowRight') {
+        e.preventDefault()
+        goNext()
+      } else if (e.key === 'ArrowLeft') {
+        e.preventDefault()
+        goPrev()
+      }
+    }
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [open, items.length, goPrev, goNext])
+
+  const item = items[index]
+  const filename = useMemo(
+    () => item?.filename ?? (item ? filenameFromUrl(item.src) : 'video'),
+    [item]
+  )
+
+  if (!item) return null
+
+  const totalLabel = items.length > 1 ? ` (${index + 1} / ${items.length})` : ''
+
+  return (
+    <ViewerShell
+      open={open}
+      onClose={onClose}
+      title={`${filename}${totalLabel}`}
+      actions={
+        <DownloadAction
+          url={item.src}
+          filename={filename}
+          variant="overlay"
+          label={`Download ${filename}`}
+        />
+      }
+      data-testid="video-viewer"
+    >
+      <div className="flex h-full w-full items-center justify-center px-6 py-16">
+        {/* No `<track>` is rendered — we don't author caption sidecars
+            for chat attachments, and an empty `<track kind="captions" />`
+            emits a runtime warning. Re-add a real track (with `src`,
+            `srcLang`, and `default`) once caption support ships. The
+            `jsx-a11y/media-has-caption` rule is suppressed for the
+            same reason. */}
+        {/* eslint-disable-next-line jsx-a11y/media-has-caption */}
+        <video
+          // Forcing a key swap on item change ensures the new source
+          // mounts a fresh element instead of reusing the previous
+          // playback state — keeps the video paused-at-start when
+          // navigating between stacked items.
+          key={`${index}:${item.src}`}
+          src={item.src}
+          poster={item.poster}
+          controls
+          // `autoPlay` without `muted` is blocked by Chrome / Safari /
+          // Firefox autoplay policies — the click that opens the viewer
+          // doesn't count as a user-gesture for the new `<video>`
+          // element after the `key` remount. Defaulting to muted means
+          // playback actually starts (matches how IG / Slack handle
+          // video lightboxes); the user can unmute via the native
+          // controls if they want sound.
+          autoPlay
+          muted
+          playsInline
+          // The active video defaults to `'metadata'` so duration /
+          // first-frame appear immediately. Honor an explicit per-item
+          // override (e.g. `'auto'` for a hero clip the caller wants
+          // pre-warmed). Non-active siblings aren't mounted at all
+          // because the `key` above swaps the element on navigation.
+          preload={item.preload ?? 'metadata'}
+          className="max-h-full max-w-full bg-black"
+        >
+          {item.mimeType ? <source src={item.src} type={item.mimeType} /> : null}
+        </video>
+      </div>
+
+      {items.length > 1 ? (
+        <>
+          <button
+            type="button"
+            onClick={goPrev}
+            aria-label="Previous video"
+            className="absolute left-4 top-1/2 z-10 flex size-12 -translate-y-1/2 items-center justify-center rounded-full bg-white/10 text-white transition-colors hover:bg-white/20"
+          >
+            <CaretLeftIcon className="size-5" weight="bold" aria-hidden />
+          </button>
+          <button
+            type="button"
+            onClick={goNext}
+            aria-label="Next video"
+            className="absolute right-4 top-1/2 z-10 flex size-12 -translate-y-1/2 items-center justify-center rounded-full bg-white/10 text-white transition-colors hover:bg-white/20"
+          >
+            <CaretRightIcon className="size-5" weight="bold" aria-hidden />
+          </button>
+        </>
+      ) : null}
+    </ViewerShell>
+  )
+}
+
+export default VideoViewer

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

@@ -0,0 +1,159 @@
+import { XIcon } from '@phosphor-icons/react'
+import classNames from 'classnames'
+import React, { useEffect, useRef } from 'react'
+import { createPortal } from 'react-dom'
+
+export interface ViewerShellProps {
+  open: boolean
+  onClose: () => void
+  /** Toolbar title — usually the filename. */
+  title?: string
+  /** Buttons rendered to the right of the title in the toolbar. */
+  actions?: React.ReactNode
+  /** Extra classes for the content slot wrapper. */
+  contentClassName?: string
+  children: React.ReactNode
+  'data-testid'?: string
+}
+
+// Module-scoped counter coordinates the body-scroll lock across
+// concurrently mounted viewers. Without it, the inner viewer's
+// unmount cleanup would restore `overflow` while the outer viewer is
+// still up — the page would scroll behind the still-open dialog.
+//
+// We snapshot the original `overflow` on the *first* lock and restore
+// it on the *last* unlock. Anything in between is a no-op.
+let activeLockCount = 0
+let previousBodyOverflow: string | null = null
+
+const lockBodyScroll = () => {
+  if (typeof document === 'undefined') return
+  if (activeLockCount === 0) {
+    previousBodyOverflow = document.body.style.overflow
+    document.body.style.overflow = 'hidden'
+  }
+  activeLockCount += 1
+}
+
+const unlockBodyScroll = () => {
+  if (typeof document === 'undefined') return
+  if (activeLockCount === 0) return
+  activeLockCount -= 1
+  if (activeLockCount === 0) {
+    document.body.style.overflow = previousBodyOverflow ?? ''
+    previousBodyOverflow = null
+  }
+}
+
+/**
+ * Full-viewport modal portal shared by `ImageViewer`, `VideoViewer`,
+ * and `PdfViewer`.
+ *
+ * Responsibilities:
+ *   - Locks body scroll while open (reference-counted so stacked
+ *     viewers don't tear each other's locks down).
+ *   - Closes on `Escape`.
+ *   - Moves focus into the dialog on mount (the close button by
+ *     default) and restores it to the previously-focused element on
+ *     unmount, so opening + closing a viewer via the keyboard returns
+ *     the user to where they were.
+ *   - Renders a thin top toolbar (title + actions + close) layered
+ *     over the content.
+ */
+const ViewerShell: React.FC<ViewerShellProps> = ({
+  open,
+  onClose,
+  title,
+  actions,
+  contentClassName,
+  children,
+  'data-testid': dataTestId,
+}) => {
+  const dialogRef = useRef<HTMLDivElement | null>(null)
+  const closeButtonRef = useRef<HTMLButtonElement | null>(null)
+
+  useEffect(() => {
+    if (!open) return undefined
+
+    lockBodyScroll()
+
+    // Remember what was focused before the viewer opened so we can
+    // hand focus back on close. Cast through `Element` because
+    // `activeElement` is typed as `Element | null` and we only call
+    // `.focus()` when it's actually an `HTMLElement`.
+    const previouslyFocused =
+      typeof document !== 'undefined'
+        ? (document.activeElement as HTMLElement | null)
+        : null
+
+    // Move focus into the dialog so keyboard users land inside the
+    // modal. Prefer the close button (most common deliberate action);
+    // fall back to the dialog itself when the button isn't rendered
+    // yet for some reason.
+    const focusTarget = closeButtonRef.current ?? dialogRef.current
+    focusTarget?.focus()
+
+    const handleKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') {
+        e.preventDefault()
+        onClose()
+      }
+    }
+    window.addEventListener('keydown', handleKey)
+
+    return () => {
+      unlockBodyScroll()
+      window.removeEventListener('keydown', handleKey)
+      // Restore focus to whatever was focused before we mounted. If
+      // that element is gone (e.g. removed from the DOM) we skip
+      // silently — focusing a stale node would throw.
+      if (previouslyFocused && document.body.contains(previouslyFocused)) {
+        previouslyFocused.focus()
+      }
+    }
+  }, [open, onClose])
+
+  if (!open || typeof document === 'undefined') return null
+
+  return createPortal(
+    <div
+      ref={dialogRef}
+      role="dialog"
+      aria-modal="true"
+      aria-label={title ?? 'Attachment viewer'}
+      data-testid={dataTestId}
+      tabIndex={-1}
+      className="fixed inset-0 z-[1000] flex flex-col bg-black/90 outline-none"
+    >
+      <div className="pointer-events-none absolute inset-x-0 top-0 z-10 flex items-center gap-3 bg-gradient-to-b from-black/70 to-transparent px-4 py-3 text-white">
+        <p className="pointer-events-auto min-w-0 flex-1 truncate text-sm font-medium">
+          {title}
+        </p>
+        <div className="pointer-events-auto flex shrink-0 items-center gap-2">
+          {actions}
+          <button
+            ref={closeButtonRef}
+            type="button"
+            onClick={onClose}
+            aria-label="Close viewer"
+            className="flex size-10 items-center justify-center rounded-full bg-white/10 text-white transition-colors hover:bg-white/20"
+          >
+            <XIcon className="size-5" weight="bold" aria-hidden />
+          </button>
+        </div>
+      </div>
+
+      <div
+        className={classNames(
+          'relative z-0 flex h-full w-full flex-1 items-center justify-center overflow-hidden',
+          contentClassName
+        )}
+      >
+        {children}
+      </div>
+    </div>,
+    document.body
+  )
+}
+
+export default ViewerShell

package/src/components/MessageAttachment/_shared/fileMeta.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  buildCompactMetaLabel,
+  filenameFromUrl,
+  formatFileSize,
+  getFileExtensionLabel,
+} from './fileMeta'
+
+describe('formatFileSize', () => {
+  it('formats sub-kilobyte sizes as bytes', () => {
+    expect(formatFileSize(0)).toBe('0 B')
+    expect(formatFileSize(512)).toBe('512 B')
+  })
+
+  it('formats kilobytes / megabytes / gigabytes with sensible precision', () => {
+    expect(formatFileSize(1024)).toBe('1.0 KB')
+    expect(formatFileSize(388_658)).toBe('379.5 KB')
+    expect(formatFileSize(2_457_600)).toBe('2.34 MB')
+    expect(formatFileSize(1024 ** 3)).toBe('1.00 GB')
+  })
+
+  it('returns empty string for invalid input', () => {
+    expect(formatFileSize(NaN)).toBe('')
+    expect(formatFileSize(Infinity)).toBe('')
+    expect(formatFileSize(-1)).toBe('')
+  })
+})
+
+describe('getFileExtensionLabel', () => {
+  it('prefers the filename extension when present', () => {
+    expect(getFileExtensionLabel(undefined, 'notes.pdf')).toBe('PDF')
+    expect(getFileExtensionLabel('application/pdf', 'oops.docx')).toBe(
+      'DOCX'
+    )
+  })
+
+  it('falls back to MIME-derived label when filename has no extension', () => {
+    expect(getFileExtensionLabel('application/pdf')).toBe('PDF')
+    expect(getFileExtensionLabel('application/zip')).toBe('ZIP')
+    expect(getFileExtensionLabel('application/json')).toBe('JSON')
+  })
+
+  it('returns undefined for unknown / generic MIME without filename', () => {
+    expect(getFileExtensionLabel('application/octet-stream')).toBeUndefined()
+    expect(getFileExtensionLabel()).toBeUndefined()
+  })
+})
+
+describe('buildCompactMetaLabel', () => {
+  it('joins extension and size with a middle dot', () => {
+    expect(
+      buildCompactMetaLabel('application/pdf', 'notes.pdf', 388_658)
+    ).toBe('PDF · 379.5 KB')
+  })
+
+  it('drops the size when missing', () => {
+    expect(buildCompactMetaLabel('application/pdf', 'notes.pdf')).toBe('PDF')
+  })
+
+  it('returns undefined when nothing is renderable', () => {
+    expect(buildCompactMetaLabel()).toBeUndefined()
+  })
+})
+
+describe('filenameFromUrl', () => {
+  it('extracts the last path segment', () => {
+    expect(filenameFromUrl('https://cdn.example.com/folder/notes.pdf')).toBe(
+      'notes.pdf'
+    )
+  })
+
+  it('decodes URI-encoded segments', () => {
+    expect(
+      filenameFromUrl('https://cdn.example.com/folder/My%20Notes.pdf')
+    ).toBe('My Notes.pdf')
+  })
+
+  it('falls back to a default when the URL cannot be parsed', () => {
+    expect(filenameFromUrl('not a url at all')).toBe('download')
+  })
+})

package/src/components/MessageAttachment/_shared/fileMeta.ts

@@ -0,0 +1,95 @@
+import {
+  getDocumentIconType,
+  getSourceType,
+} from '../../AttachmentCard/utils/mimeType'
+
+/**
+ * Format a byte count as a short human-readable string (`'379.5 KB'`).
+ * Mirrors the meta line shown next to file attachments in the mobile chat
+ * design — `EXT · SIZE`, e.g. `PDF · 379.5 KB`.
+ */
+export function formatFileSize(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return ''
+  if (bytes < 1024) return `${bytes} B`
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`
+  if (bytes < 1024 * 1024 * 1024)
+    return `${(bytes / (1024 * 1024)).toFixed(2)} MB`
+  return `${(bytes / (1024 * 1024 * 1024)).toFixed(2)} GB`
+}
+
+const EXTENSION_LABEL_BY_DOCUMENT_TYPE: Record<string, string> = {
+  pdf: 'PDF',
+  doc: 'DOC',
+  xls: 'XLS',
+  csv: 'CSV',
+  ppt: 'PPT',
+  zip: 'ZIP',
+  text: 'TXT',
+  markdown: 'MD',
+}
+
+/**
+ * Returns the short uppercase extension label shown in the meta line of
+ * compact document / file attachments. Prefers the filename extension
+ * when present (matches the mobile design which trusts the filename),
+ * and falls back to a label derived from the MIME type.
+ */
+export function getFileExtensionLabel(
+  mimeType?: string,
+  filename?: string
+): string | undefined {
+  if (filename) {
+    const lastDot = filename.lastIndexOf('.')
+    if (lastDot > 0 && lastDot < filename.length - 1) {
+      const ext = filename.slice(lastDot + 1)
+      if (ext && ext.length <= 5) return ext.toUpperCase()
+    }
+  }
+
+  if (!mimeType) return undefined
+
+  const sourceType = getSourceType(mimeType)
+  if (sourceType === 'document') {
+    const docType = getDocumentIconType(mimeType)
+    const docLabel = EXTENSION_LABEL_BY_DOCUMENT_TYPE[docType]
+    if (docLabel) return docLabel
+    if (mimeType === 'application/octet-stream') return undefined
+  }
+
+  const subtype = mimeType.split('/')[1]
+  if (!subtype || subtype === '*') return undefined
+  return subtype.toUpperCase()
+}
+
+/**
+ * Build the meta line shown under the title in compact document / file
+ * attachments — `EXT · SIZE` (`PDF · 379.5 KB`). Either part is dropped
+ * when not available so audio / generic files still get a useful label.
+ */
+export function buildCompactMetaLabel(
+  mimeType?: string,
+  filename?: string,
+  fileSize?: number
+): string | undefined {
+  const ext = getFileExtensionLabel(mimeType, filename)
+  const size =
+    typeof fileSize === 'number' && fileSize > 0
+      ? formatFileSize(fileSize)
+      : undefined
+  return [ext, size].filter(Boolean).join(' · ') || undefined
+}
+
+/**
+ * Derive a sensible filename from a URL — used as the fallback save name
+ * when the attachment has no `filename` set. Returns `'download'` for
+ * URLs we can't parse.
+ */
+export function filenameFromUrl(url: string): string {
+  try {
+    const parsed = new URL(url)
+    const last = parsed.pathname.split('/').pop()
+    return last && last.length > 0 ? decodeURIComponent(last) : 'download'
+  } catch {
+    return 'download'
+  }
+}

package/src/components/MessageAttachment/_shared/triggerDownload.ts

@@ -0,0 +1,54 @@
+import { filenameFromUrl } from './fileMeta'
+
+/**
+ * Download a remote asset with the desired filename.
+ *
+ * Tries the same-origin `fetch` → `Blob` → invisible-`<a>.download`
+ * route first so the file lands on disk under `filename` instead of
+ * navigating the tab to it. When CORS / network errors trip us up we
+ * fall back to `window.open` and then to a no-window anchor — the
+ * popup-blocker fallback ensures the download still fires even when
+ * a browser blocks the `_blank` window.
+ *
+ * Shared by `DownloadAction` (rendered as an explicit Download button
+ * in PDF / image / video viewers) and `MessageAttachment.File` rows
+ * (where the entire row is the download trigger). Centralizing here
+ * keeps one source of truth for the fallback chain.
+ */
+export async function triggerDownload(
+  url: string,
+  filename?: string
+): Promise<void> {
+  const name = filename ?? filenameFromUrl(url)
+
+  try {
+    const res = await fetch(url, { mode: 'cors' })
+    if (!res.ok) throw new Error(`HTTP ${res.status}`)
+    const blob = await res.blob()
+    const objectUrl = URL.createObjectURL(blob)
+    const a = document.createElement('a')
+    a.href = objectUrl
+    a.download = name
+    a.style.display = 'none'
+    document.body.appendChild(a)
+    a.click()
+    document.body.removeChild(a)
+    URL.revokeObjectURL(objectUrl)
+  } catch {
+    const fallback = window.open(url, '_blank', 'noopener,noreferrer')
+    if (!fallback) {
+      // popup blocked — fall back to a non-windowed anchor
+      const a = document.createElement('a')
+      a.href = url
+      a.download = name
+      a.target = '_blank'
+      a.rel = 'noopener noreferrer'
+      a.style.display = 'none'
+      document.body.appendChild(a)
+      a.click()
+      document.body.removeChild(a)
+    }
+  }
+}
+
+export default triggerDownload

package/src/components/MessageAttachment/_shared/useViewer.ts

@@ -0,0 +1,53 @@
+import { useCallback, useState } from 'react'
+
+/**
+ * Optional click handler used by every viewer-backed attachment.
+ *
+ * Return `false` to cancel the default open behavior — useful for
+ * route-based viewers or confirmation modals. Any other return value
+ * (including `void`/`undefined`) lets the built-in viewer open as
+ * normal. The `index` argument identifies the row in stacked
+ * attachments and is `0` for the single-attachment shape.
+ */
+export type ViewerClickHandler = (index: number) => boolean | void
+
+export interface UseViewerResult {
+  viewerOpen: boolean
+  viewerIndex: number
+  /**
+   * Open the viewer at the given index. Forwards to the caller's
+   * `onClick` first so analytics + intercept logic can fire before
+   * the viewer mounts; if `onClick` returns `false` the open is
+   * skipped entirely.
+   */
+  handleActivate: (index: number) => void
+  closeViewer: () => void
+}
+
+/**
+ * Tiny piece of state shared by every `MessageAttachment` that opens
+ * a fullscreen viewer (`Image`, `Video`, `Pdf`). Tracks the open flag
+ * + the active index, and threads the caller's `onClick` callback
+ * through `handleActivate` so consumers can intercept the open
+ * (e.g. analytics) or cancel it (return `false` to swap in a
+ * route-based viewer / confirmation modal).
+ */
+export const useViewer = (onClick?: ViewerClickHandler): UseViewerResult => {
+  const [viewerOpen, setViewerOpen] = useState(false)
+  const [viewerIndex, setViewerIndex] = useState(0)
+
+  const handleActivate = useCallback(
+    (index: number) => {
+      if (onClick?.(index) === false) return
+      setViewerIndex(index)
+      setViewerOpen(true)
+    },
+    [onClick]
+  )
+
+  const closeViewer = useCallback(() => setViewerOpen(false), [])
+
+  return { viewerOpen, viewerIndex, handleActivate, closeViewer }
+}
+
+export default useViewer