@linktr.ee/messaging-react 2.2.3 → 2.3.0-rc-1779486690

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

@@ -11,16 +11,20 @@ import { triggerDownload } from './triggerDownload'
 export type DownloadActionVariant =
   /** Solid pill button used inside compact / file rows. */
   | 'pill'
-  /** Round translucent overlay button used over media (image / video viewers). */
-  | 'overlay'
-  /** Flat icon button used in viewer toolbars. */
-  | 'toolbar'
   /**
    * Compact round icon button sized for the trailing slot of a
    * `CompactDocumentRow` (PDF / File rows). Adopts the row's tone so
    * it sits inline next to the filename without competing with it.
    */
   | 'inline'
+  /**
+   * Round icon button sized to match the close action in the
+   * `ViewerShell` chrome — used by `ImageViewer` for in-viewer
+   * downloads. Styled with plain CSS (`.mes-media-viewer__action`) so
+   * it renders correctly without a Tailwind dependency in the
+   * consumer's app.
+   */
+  | 'viewer'
 
 export interface DownloadActionProps {
   url: string
@@ -28,7 +32,8 @@ export interface DownloadActionProps {
   variant?: DownloadActionVariant
   /**
    * Override the visible label on `pill` variants. Defaults to
-   * `'Download'`. Hidden on `overlay` / `toolbar` variants.
+   * `'Download'`. On `inline` / `viewer` variants the label is
+   * hidden visually and surfaced as the button's `aria-label`.
    */
   label?: string
   /** Hide the label, keeping just the icon. Defaults to `true` for non-pill variants. */
@@ -117,57 +122,52 @@ const DownloadAction: React.FC<DownloadActionProps> = ({
     )
   }
 
-  if (variant === 'pill') {
+  if (variant === 'viewer') {
+    // Styled entirely through `.mes-media-viewer__action` (plain CSS
+    // in `styles.css`) so the button renders correctly when consumed
+    // outside this repo without a Tailwind setup. Sits next to the
+    // close action inside `ViewerShell`'s top-right chrome.
     return (
       <button
         type="button"
         onClick={handleClick}
         disabled={busy}
-        aria-label={showIconOnly ? label : undefined}
-        className={classNames(
-          'mt-3 inline-flex h-10 w-full items-center justify-center gap-2 rounded-full px-4 text-sm font-medium leading-none transition-colors disabled:opacity-70',
-          tone === 'dark'
-            ? 'bg-[#121110] text-white hover:bg-[#2a2928]'
-            : 'bg-white text-[#121110] hover:bg-white/90'
-        )}
+        aria-label={label}
+        className="mes-media-viewer__action"
       >
         {busy ? (
-          <CircleNotchIcon
-            className="size-4 animate-spin"
-            weight="bold"
-            aria-hidden
-          />
+          <CircleNotchIcon size={20} weight="bold" aria-hidden />
         ) : (
-          <DownloadSimpleIcon {...iconProps} aria-hidden />
+          <DownloadSimpleIcon size={20} weight="bold" aria-hidden />
         )}
-        {showIconOnly ? null : label}
       </button>
     )
   }
 
-  // overlay / toolbar — round translucent button with just the icon
+  // pill — only remaining variant
   return (
     <button
       type="button"
       onClick={handleClick}
       disabled={busy}
-      aria-label={label}
+      aria-label={showIconOnly ? label : undefined}
       className={classNames(
-        'flex size-10 shrink-0 items-center justify-center rounded-full text-white transition-colors disabled:opacity-70',
-        variant === 'overlay'
-          ? 'bg-black/55 backdrop-blur hover:bg-black/70'
-          : 'bg-white/10 hover:bg-white/20'
+        'mt-3 inline-flex h-10 w-full items-center justify-center gap-2 rounded-full px-4 text-sm font-medium leading-none transition-colors disabled:opacity-70',
+        tone === 'dark'
+          ? 'bg-[#121110] text-white hover:bg-[#2a2928]'
+          : 'bg-white text-[#121110] hover:bg-white/90'
       )}
     >
       {busy ? (
         <CircleNotchIcon
-          className="size-5 animate-spin"
+          className="size-4 animate-spin"
           weight="bold"
           aria-hidden
         />
       ) : (
         <DownloadSimpleIcon {...iconProps} aria-hidden />
       )}
+      {showIconOnly ? null : label}
     </button>
   )
 }

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

@@ -1,28 +1,18 @@
-import {
-  CaretLeftIcon,
-  CaretRightIcon,
-  MagnifyingGlassMinusIcon,
-  MagnifyingGlassPlusIcon,
-} from '@phosphor-icons/react'
-import classNames from 'classnames'
-import React, {
-  useCallback,
-  useEffect,
-  useMemo,
-  useRef,
-  useState,
-} from 'react'
+import React, { useMemo } from 'react'
 
+import CarouselNav from './CarouselNav'
 import DownloadAction from './DownloadAction'
 import { filenameFromUrl } from './fileMeta'
+import { useCarousel } from './useCarousel'
 import ViewerShell from './ViewerShell'
 
 export interface ImageViewerItem {
   src: string
   alt?: string
   /**
-   * Filename used by the download action. Falls back to the last
-   * pathname segment of `src` when omitted.
+   * Filename used by the download action and as the dialog's
+   * accessible name. Falls back to the last pathname segment of
+   * `src` when omitted.
    */
   filename?: string
 }
@@ -30,34 +20,27 @@ export interface ImageViewerItem {
 export interface ImageViewerProps {
   open: boolean
   items: ImageViewerItem[]
-  /** Currently active item. Defaults to `0`. */
+  /** Index to display when the viewer first opens. Defaults to `0`. */
   initialIndex?: number
   onClose: () => void
 }
 
-const MIN_SCALE = 1
-const MAX_SCALE = 8
-const ZOOM_STEP = 1.25
-
-const clamp = (value: number, min: number, max: number) =>
-  Math.min(Math.max(value, min), max)
-
-interface ViewportState {
-  scale: number
-  x: number
-  y: number
-}
-
-const RESET_STATE: ViewportState = { scale: 1, x: 0, y: 0 }
-
 /**
- * Native lightbox-style image viewer with mouse-wheel zoom, drag-to-pan,
- * double-click toggle (1× ↔ 2×), keyboard arrow navigation between
- * stacked items, and built-in download.
+ * Native lightbox-style image viewer — full-viewport `<dialog>` with
+ * the image centered at reasonable max dimensions, a single close
+ * button, and a download action in the chrome.
+ *
+ * When `items.length > 1` the viewer becomes a carousel:
  *
- * Used by every `MessageAttachment.Image.*` variant — Composer / Sent /
- * Received all open this viewer when activated, so admins can preview
- * attachments before sending and recipients can preview after receipt.
+ *   - Prev / next on-screen controls hug the viewport sides.
+ *   - `ArrowLeft` / `ArrowRight` step between siblings (the keyboard
+ *     listener is parked while a `<video>` / `<audio>` element is
+ *     focused so native media seek still works in mixed contexts).
+ *   - A `current / total` counter sits in the top-left chrome.
+ *
+ * Used by every `MessageAttachment.Image.*` variant
+ * (Composer / Sent / Received) so admins can preview attachments
+ * before sending and recipients can preview after receipt.
  */
 const ImageViewer: React.FC<ImageViewerProps> = ({
   open,
@@ -65,247 +48,62 @@ const ImageViewer: React.FC<ImageViewerProps> = ({
   initialIndex = 0,
   onClose,
 }) => {
-  const safeIndex = clamp(initialIndex, 0, Math.max(items.length - 1, 0))
-  const [index, setIndex] = useState(safeIndex)
-  const [view, setView] = useState<ViewportState>(RESET_STATE)
-  const [dragging, setDragging] = useState(false)
-  const dragStart = useRef<{
-    x: number
-    y: number
-    panX: number
-    panY: number
-  } | null>(null)
-  const stageRef = useRef<HTMLDivElement | null>(null)
-
-  // Reset zoom whenever the viewer opens or the active item changes.
-  useEffect(() => {
-    if (!open) return
-    setIndex(clamp(initialIndex, 0, Math.max(items.length - 1, 0)))
-    setView(RESET_STATE)
-  }, [open, initialIndex, items.length])
-
-  useEffect(() => {
-    setView(RESET_STATE)
-  }, [index])
-
-  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])
-
-  // Arrow-key navigation between items in the stack.
-  useEffect(() => {
-    if (!open) return undefined
-    const onKey = (e: KeyboardEvent) => {
-      if (items.length <= 1) return
-      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 zoomBy = useCallback((factor: number) => {
-    setView((prev) => {
-      const nextScale = clamp(prev.scale * factor, MIN_SCALE, MAX_SCALE)
-      // Re-center when we hit 1× so the image is never offset off-screen.
-      if (nextScale === MIN_SCALE) return RESET_STATE
-      return { scale: nextScale, x: prev.x, y: prev.y }
-    })
-  }, [])
-
-  // React's synthetic `onWheel` is registered as a passive listener
-  // (since React 17), so `e.preventDefault()` is a no-op inside an
-  // `onWheel` handler — the page scrolls behind the viewer regardless.
-  // Attach the listener manually on the stage element with
-  // `{ passive: false }` so we can actually stop the page scroll
-  // while the user zooms.
-  useEffect(() => {
-    if (!open) return undefined
-    const stage = stageRef.current
-    if (!stage) return undefined
-
-    const handleWheel = (e: WheelEvent) => {
-      e.preventDefault()
-      const factor = e.deltaY < 0 ? ZOOM_STEP : 1 / ZOOM_STEP
-      zoomBy(factor)
-    }
-
-    stage.addEventListener('wheel', handleWheel, { passive: false })
-    return () => stage.removeEventListener('wheel', handleWheel)
-  }, [open, zoomBy])
-
-  const handleDoubleClick = useCallback(() => {
-    setView((prev) =>
-      prev.scale > 1
-        ? RESET_STATE
-        : { scale: 2, x: prev.x, y: prev.y }
-    )
-  }, [])
-
-  const handleMouseDown = useCallback(
-    (e: React.MouseEvent<HTMLDivElement>) => {
-      // Only allow drag-pan once the user has zoomed in.
-      if (view.scale <= 1) return
-      e.preventDefault()
-      setDragging(true)
-      dragStart.current = {
-        x: e.clientX,
-        y: e.clientY,
-        panX: view.x,
-        panY: view.y,
-      }
-    },
-    [view.scale, view.x, view.y]
-  )
-
-  useEffect(() => {
-    if (!dragging) return undefined
-
-    const onMove = (e: MouseEvent) => {
-      const start = dragStart.current
-      if (!start) return
-      setView((prev) => ({
-        scale: prev.scale,
-        x: start.panX + (e.clientX - start.x),
-        y: start.panY + (e.clientY - start.y),
-      }))
-    }
-    const onUp = () => {
-      dragStart.current = null
-      setDragging(false)
-    }
-    window.addEventListener('mousemove', onMove)
-    window.addEventListener('mouseup', onUp)
-    return () => {
-      window.removeEventListener('mousemove', onMove)
-      window.removeEventListener('mouseup', onUp)
-    }
-  }, [dragging])
+  const { index, prev, next } = useCarousel({
+    length: items.length,
+    initialIndex,
+    open,
+  })
 
   const item = items[index]
   const filename = useMemo(
-    () =>
-      item?.filename ?? (item ? filenameFromUrl(item.src) : 'image'),
+    () => item?.filename ?? (item ? filenameFromUrl(item.src) : 'image'),
     [item]
   )
 
-  const cursorClass = useMemo(() => {
-    if (view.scale <= 1) return 'cursor-zoom-in'
-    return dragging ? 'cursor-grabbing' : 'cursor-grab'
-  }, [view.scale, dragging])
-
   if (!item) return null
 
-  const totalLabel = items.length > 1 ? ` (${index + 1} / ${items.length})` : ''
-
   return (
     <ViewerShell
       open={open}
       onClose={onClose}
-      title={`${filename}${totalLabel}`}
+      ariaLabel={filename}
+      counter={
+        items.length > 1 ? `${index + 1} / ${items.length}` : undefined
+      }
       actions={
-        <>
-          <button
-            type="button"
-            onClick={() => zoomBy(1 / ZOOM_STEP)}
-            disabled={view.scale <= MIN_SCALE}
-            aria-label="Zoom out"
-            className="flex size-10 items-center justify-center rounded-full bg-white/10 text-white transition-colors hover:bg-white/20 disabled:opacity-40"
-          >
-            <MagnifyingGlassMinusIcon
-              className="size-5"
-              weight="bold"
-              aria-hidden
-            />
-          </button>
-          <button
-            type="button"
-            onClick={() => zoomBy(ZOOM_STEP)}
-            disabled={view.scale >= MAX_SCALE}
-            aria-label="Zoom in"
-            className="flex size-10 items-center justify-center rounded-full bg-white/10 text-white transition-colors hover:bg-white/20 disabled:opacity-40"
-          >
-            <MagnifyingGlassPlusIcon
-              className="size-5"
-              weight="bold"
-              aria-hidden
-            />
-          </button>
-          <DownloadAction
-            url={item.src}
-            filename={filename}
-            variant="overlay"
-            label={`Download ${filename}`}
-          />
-        </>
+        <DownloadAction
+          url={item.src}
+          filename={filename}
+          variant="viewer"
+          label={`Download ${filename}`}
+        />
       }
       data-testid="image-viewer"
     >
-      <div
-        ref={stageRef}
-        // The stage swallows wheel / double-click / drag gestures to
-        // implement the zoom + pan controls. It's not a button (clicks
-        // don't have a single discrete action), so suppress the
-        // a11y/no-static-element-interactions rule here — the discrete
-        // zoom / download actions live in the toolbar above. The wheel
-        // listener is attached manually (non-passive) in the effect
-        // above so `preventDefault()` actually stops page scroll.
-        // eslint-disable-next-line jsx-a11y/no-static-element-interactions
-        role="presentation"
-        onDoubleClick={handleDoubleClick}
-        onMouseDown={handleMouseDown}
-        className={classNames(
-          'relative flex h-full w-full select-none items-center justify-center overflow-hidden',
-          cursorClass
-        )}
-      >
-        <img
-          src={item.src}
-          alt={item.alt ?? filename}
-          draggable={false}
-          // Once the user has explicitly opened the viewer the active
-          // image needs to appear immediately, so we eager-load it.
-          // Adjacent / off-screen viewer images aren't rendered here
-          // (we only mount `items[index]`), so the lazy default on
-          // siblings is automatic.
-          loading="eager"
-          decoding="async"
-          style={{
-            transform: `translate3d(${view.x}px, ${view.y}px, 0) scale(${view.scale})`,
-            transition: dragging ? 'none' : 'transform 120ms ease-out',
-          }}
-          className="max-h-full max-w-full object-contain"
-        />
-      </div>
+      <img
+        // Forcing a key swap on item change ensures React replaces the
+        // `<img>` cleanly between siblings — otherwise the previous
+        // image stays painted for a frame while the new `src`
+        // decodes, which reads as a stutter at carousel pace.
+        key={`${index}:${item.src}`}
+        src={item.src}
+        alt={item.alt ?? filename}
+        draggable={false}
+        // The user has explicitly opened the viewer, so we want the
+        // active image to appear immediately rather than fall to the
+        // browser's lazy-load heuristics.
+        loading="eager"
+        decoding="async"
+        className="mes-media-viewer__image"
+      />
 
       {items.length > 1 ? (
-        <>
-          <button
-            type="button"
-            onClick={goPrev}
-            aria-label="Previous image"
-            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 image"
-            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>
-        </>
+        <CarouselNav
+          onPrev={prev}
+          onNext={next}
+          prevLabel="Previous image"
+          nextLabel="Next image"
+        />
       ) : null}
     </ViewerShell>
   )

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

@@ -1,67 +1,84 @@
 import React, { useMemo } from 'react'
 
-import DownloadAction from './DownloadAction'
+import CarouselNav from './CarouselNav'
 import { filenameFromUrl } from './fileMeta'
+import { useCarousel } from './useCarousel'
 import ViewerShell from './ViewerShell'
 
-export interface PdfViewerProps {
-  open: boolean
+export interface PdfViewerItem {
   /** Source URL of the PDF document. */
   src: string
-  /** Filename used by the toolbar title and the download action. */
+  /** Filename used as the dialog's accessible name. */
   filename?: string
+}
+
+export interface PdfViewerProps {
+  open: boolean
+  items: PdfViewerItem[]
+  /** Index to display when the viewer first opens. Defaults to `0`. */
+  initialIndex?: number
   onClose: () => void
 }
 
 /**
- * Modal PDF viewer that hosts the document inside a sandboxed
- * `<iframe>`, leaving native PDF rendering, scroll, and zoom to the
- * browser. Adds a thin top toolbar with the filename + a download
- * action so users get the same `download / close` affordances as the
- * `ImageViewer` and the inline audio / video players.
+ * Modal PDF viewer that hosts the active document inside a sandboxed
+ * `<iframe>`, leaving native rendering, scroll, search, and the
+ * browser's built-in download controls to the browser. The lightbox
+ * chrome is intentionally just a close button plus, for stacked
+ * attachments, carousel prev/next + counter.
  */
 const PdfViewer: React.FC<PdfViewerProps> = ({
   open,
-  src,
-  filename,
+  items,
+  initialIndex = 0,
   onClose,
 }) => {
-  const resolvedFilename = useMemo(
-    () => filename ?? filenameFromUrl(src),
-    [filename, src]
+  const { index, prev, next } = useCarousel({
+    length: items.length,
+    initialIndex,
+    open,
+  })
+
+  const item = items[index]
+  const filename = useMemo(
+    () => item?.filename ?? (item ? filenameFromUrl(item.src) : 'document'),
+    [item]
   )
 
   // `#toolbar=0` is honored by Chromium-family browsers and hides the
-  // built-in PDF toolbar so our own toolbar reads as the single source
-  // of truth (otherwise the user sees two stacked toolbars). Firefox /
-  // Safari ignore it and keep their native toolbars, which is fine —
-  // the user gets a familiar experience either way.
+  // built-in PDF toolbar's redundant controls. Firefox / Safari ignore
+  // it and keep their native toolbars, which is fine — the user gets a
+  // familiar experience either way.
   //
   // Preserve any existing fragment the caller supplied (e.g.
   // `#page=3`) by merging our params into it rather than naively
   // appending a second `#…` segment.
-  const iframeSrc = useMemo(() => withPdfViewerParams(src), [src])
+  const iframeSrc = useMemo(
+    () => (item ? withPdfViewerParams(item.src) : undefined),
+    [item]
+  )
+
+  if (!item || !iframeSrc) return null
 
   return (
     <ViewerShell
       open={open}
       onClose={onClose}
-      title={resolvedFilename}
-      actions={
-        <DownloadAction
-          url={src}
-          filename={resolvedFilename}
-          variant="overlay"
-          label={`Download ${resolvedFilename}`}
-        />
+      ariaLabel={filename}
+      counter={
+        items.length > 1 ? `${index + 1} / ${items.length}` : undefined
       }
-      contentClassName="bg-[#1f1e1d]"
       data-testid="pdf-viewer"
     >
       <iframe
+        // Force a key swap on item change so the iframe remounts a
+        // fresh document rather than re-using the previous scroll
+        // position / search state when the user navigates between
+        // siblings.
+        key={`${index}:${item.src}`}
         src={iframeSrc}
-        title={resolvedFilename}
-        className="absolute inset-0 size-full bg-white"
+        title={filename}
+        className="mes-media-viewer__iframe"
         // Sandbox the iframe to stop the embedded document from
         // reaching parent context. We intentionally omit
         // `allow-same-origin`: even when the PDF host happens to share
@@ -74,6 +91,15 @@ const PdfViewer: React.FC<PdfViewerProps> = ({
         // new tab.
         sandbox="allow-scripts allow-forms allow-popups allow-downloads"
       />
+
+      {items.length > 1 ? (
+        <CarouselNav
+          onPrev={prev}
+          onNext={next}
+          prevLabel="Previous document"
+          nextLabel="Next document"
+        />
+      ) : null}
     </ViewerShell>
   )
 }