@linktr.ee/messaging-react 2.3.0-rc-1779427772 → 2.3.0

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

@@ -1,13 +1,10 @@
-import {
-  CaretLeftIcon,
-  CaretRightIcon,
-} from '@phosphor-icons/react'
-import React, { useCallback, useEffect, useMemo, useState } from 'react'
+import React, { useMemo } from 'react'
 
 import type { MediaPreloadMode } from '../types'
 
-import DownloadAction from './DownloadAction'
+import CarouselNav from './CarouselNav'
 import { filenameFromUrl } from './fileMeta'
+import { useCarousel } from './useCarousel'
 import ViewerShell from './ViewerShell'
 
 export interface VideoViewerItem {
@@ -28,19 +25,20 @@ export interface VideoViewerItem {
 export interface VideoViewerProps {
   open: boolean
   items: VideoViewerItem[]
+  /** Index to display when the viewer first opens. Defaults to `0`. */
   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.
+ * browser's native chrome (play / pause / seek / fullscreen / volume /
+ * download).
+ *
+ * When `items.length > 1` the viewer becomes a carousel — see
+ * `ImageViewer` for the same behavior; arrow-key navigation yields to
+ * the focused `<video>` so the native seek shortcuts still work.
  */
 const VideoViewer: React.FC<VideoViewerProps> = ({
   open,
@@ -48,37 +46,11 @@ const VideoViewer: React.FC<VideoViewerProps> = ({
   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 { index, prev, next } = useCarousel({
+    length: items.length,
+    initialIndex,
+    open,
+  })
 
   const item = items[index]
   const filename = useMemo(
@@ -88,81 +60,53 @@ const VideoViewer: React.FC<VideoViewerProps> = ({
 
   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}`}
-        />
+      ariaLabel={filename}
+      counter={
+        items.length > 1 ? `${index + 1} / ${items.length}` : undefined
       }
       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>
+      {/* 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. */}
+      {/* 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 freshly-mounted
+        // `<video>` element. Defaulting to muted means playback
+        // actually starts (matches how IG / Slack handle their video
+        // lightboxes); the user can unmute via the native controls if
+        // they want sound.
+        autoPlay
+        muted
+        playsInline
+        preload={item.preload ?? 'metadata'}
+        className="mes-media-viewer__video"
+      >
+        {item.mimeType ? <source src={item.src} type={item.mimeType} /> : null}
+      </video>
 
       {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>
-        </>
+        <CarouselNav
+          onPrev={prev}
+          onNext={next}
+          prevLabel="Previous video"
+          nextLabel="Next video"
+        />
       ) : null}
     </ViewerShell>
   )

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

@@ -1,158 +1,178 @@
 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. */
+  /**
+   * Accessible label for the dialog — usually the media's filename. We
+   * intentionally don't render a visible title bar (the chrome is a
+   * single close button + optional actions so the media stays the
+   * focus), so this is the only way assistive tech gets a name for
+   * the modal.
+   */
+  ariaLabel?: string
+  /**
+   * Optional counter rendered in the top-left chrome (e.g. `2 / 6`).
+   * Carousel-aware viewers set this when their items array has more
+   * than one entry; omit it for single-item viewers.
+   */
+  counter?: React.ReactNode
+  /**
+   * Extra buttons rendered alongside the close button in the top-right
+   * chrome (e.g. a download action). They share `.mes-media-viewer__action`
+   * styling so the row reads as one consistent button group.
+   */
   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`.
+ * Full-viewport lightbox shell shared by `ImageViewer`, `VideoViewer`,
+ * and `PdfViewer`. Built on a native `<dialog>` so the package ships
+ * without a Tailwind dependency for the load-bearing chrome:
  *
- * 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.
+ *   - Top-layer + body-scroll lock come for free from `showModal()`.
+ *   - `Escape` to close is wired by the platform.
+ *   - Focus management (move-in on open, restore on close) is handled
+ *     by the browser; we explicitly focus the close button as a
+ *     fallback for environments where `showModal` is unavailable
+ *     (jsdom under tests).
+ *
+ * The structural styling lives as plain CSS under `.mes-media-viewer*`
+ * in `styles.css` so a consumer who imports
+ * `@linktr.ee/messaging-react/styles.css` gets a working lightbox even
+ * if their Tailwind pipeline isn't scanning our `dist`.
  */
 const ViewerShell: React.FC<ViewerShellProps> = ({
   open,
   onClose,
-  title,
+  ariaLabel,
+  counter,
   actions,
-  contentClassName,
   children,
   'data-testid': dataTestId,
 }) => {
-  const dialogRef = useRef<HTMLDivElement | null>(null)
+  const dialogRef = useRef<HTMLDialogElement | null>(null)
   const closeButtonRef = useRef<HTMLButtonElement | null>(null)
 
+  // Drive `<dialog>` open/close imperatively from the React `open` prop.
+  // We guard `showModal` / `close` because jsdom 23 ships the element
+  // without those methods — falling back to the `[open]` attribute
+  // keeps tests (and any other non-DOM environment) functional even if
+  // the true top-layer modal behavior isn't available there.
   useEffect(() => {
-    if (!open) return undefined
+    const dialog = dialogRef.current
+    if (!dialog) return undefined
 
-    lockBodyScroll()
+    if (open) {
+      if (!dialog.open) {
+        if (typeof dialog.showModal === 'function') {
+          try {
+            dialog.showModal()
+          } catch {
+            dialog.setAttribute('open', '')
+          }
+        } else {
+          dialog.setAttribute('open', '')
+        }
+      }
 
-    // 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
+      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()
+      // Explicitly focus the close button. In a real browser
+      // `showModal()` would already focus the first sequentially
+      // focusable child (which is the close button), but doing it
+      // ourselves guarantees the same behavior in jsdom and in any
+      // browser where focus heuristics differ.
+      closeButtonRef.current?.focus()
 
-    const handleKey = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') {
-        e.preventDefault()
-        onClose()
+      return () => {
+        if (dialog.open) {
+          if (typeof dialog.close === 'function') {
+            try {
+              dialog.close()
+            } catch {
+              dialog.removeAttribute('open')
+            }
+          } else {
+            dialog.removeAttribute('open')
+          }
+        }
+        if (previouslyFocused && document.body.contains(previouslyFocused)) {
+          previouslyFocused.focus()
+        }
       }
     }
-    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()
+    if (dialog.open) {
+      if (typeof dialog.close === 'function') {
+        try {
+          dialog.close()
+        } catch {
+          dialog.removeAttribute('open')
+        }
+      } else {
+        dialog.removeAttribute('open')
       }
     }
-  }, [open, onClose])
+    return undefined
+  }, [open])
 
-  if (!open || typeof document === 'undefined') return null
+  // The platform fires `close` when the user dismisses via Escape or
+  // any other native path. Mirror that into React state so the parent's
+  // `open` flag stays in sync — otherwise the dialog would close
+  // visually but our effect would re-open it on the next render.
+  const handleDialogClose = () => {
+    onClose()
+  }
 
-  return createPortal(
-    <div
+  // Backdrop click closes the viewer. The click lands on the `<dialog>`
+  // itself (not its children) because the body sits inside an inner
+  // wrapper — the easiest reliable check.
+  const handleDialogClick = (e: React.MouseEvent<HTMLDialogElement>) => {
+    if (e.target === dialogRef.current) onClose()
+  }
+
+  return (
+    // The native `<dialog>` element ships its own keyboard dismissal
+    // (Escape, handled by the platform and surfaced through `onClose`),
+    // so the `onClick` on the backdrop doesn't need a paired keyboard
+    // listener — that's the whole point of using `<dialog>`. The
+    // `jsx-a11y` rules below don't model `<dialog>` as interactive, so
+    // we silence them locally with the rationale captured here.
+    // eslint-disable-next-line jsx-a11y/click-events-have-key-events, jsx-a11y/no-noninteractive-element-interactions
+    <dialog
       ref={dialogRef}
-      role="dialog"
-      aria-modal="true"
-      aria-label={title ?? 'Attachment viewer'}
+      className="mes-media-viewer"
+      aria-label={ariaLabel ?? 'Attachment viewer'}
       data-testid={dataTestId}
-      tabIndex={-1}
-      className="fixed inset-0 z-[1000] flex flex-col bg-black/90 outline-none"
+      onClose={handleDialogClose}
+      onClick={handleDialogClick}
     >
-      <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">
+      <div className="mes-media-viewer__chrome">
+        {counter ? (
+          <span className="mes-media-viewer__counter">{counter}</span>
+        ) : null}
+        <div className="mes-media-viewer__actions">
           {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"
+            className="mes-media-viewer__action"
           >
-            <XIcon className="size-5" weight="bold" aria-hidden />
+            <XIcon size={20} 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
+      <div className="mes-media-viewer__body">{children}</div>
+    </dialog>
   )
 }
 

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

@@ -0,0 +1,103 @@
+import { useCallback, useEffect, useState } from 'react'
+
+const clamp = (value: number, min: number, max: number) =>
+  Math.min(Math.max(value, min), max)
+
+export interface UseCarouselOptions {
+  /** Total number of items in the carousel. */
+  length: number
+  /** Index to display when the carousel first opens / re-opens. */
+  initialIndex: number
+  /** When `false`, the keyboard listener is detached. */
+  open: boolean
+}
+
+export interface UseCarouselResult {
+  /** Currently displayed index (clamped to `[0, length - 1]`). */
+  index: number
+  /** Step one item back, wrapping at the start. */
+  prev: () => void
+  /** Step one item forward, wrapping at the end. */
+  next: () => void
+}
+
+/**
+ * Tiny carousel state used by `ImageViewer`, `VideoViewer`, and
+ * `PdfViewer` when their items array has more than one entry.
+ *
+ *   - Resets to `initialIndex` whenever the viewer (re-)opens, so
+ *     clicking a different tile on the bubble surface lands on that
+ *     item rather than restoring the last-viewed position.
+ *   - Clamps defensively when `length` shrinks below the active index
+ *     (server push / optimistic update / stack edit) so the viewer
+ *     gracefully falls back instead of dereferencing `undefined`.
+ *   - Listens for `ArrowLeft` / `ArrowRight` while the viewer is open,
+ *     but yields when the focused element is a `<video>` / `<audio>`
+ *     element so the native media controls can use the same keys for
+ *     seek / volume.
+ */
+export const useCarousel = ({
+  length,
+  initialIndex,
+  open,
+}: UseCarouselOptions): UseCarouselResult => {
+  const safeInitial = clamp(initialIndex, 0, Math.max(length - 1, 0))
+  const [index, setIndex] = useState(safeInitial)
+
+  // Snap the active index back to whatever the caller asked for every
+  // time the viewer (re)opens or its initial target / length changes.
+  // Without this the viewer would remember the last index across
+  // open/close cycles, which is wrong for a chat lightbox where each
+  // tile click should land on that tile.
+  useEffect(() => {
+    if (!open) return
+    setIndex(clamp(initialIndex, 0, Math.max(length - 1, 0)))
+  }, [open, initialIndex, length])
+
+  // Re-clamp on length change so a stale index doesn't dereference
+  // past the new array bounds (e.g. items shrank while the viewer is
+  // open). The `Math.max(..., 0)` keeps the index at `0` when the
+  // array empties out so callers can render an empty-state instead of
+  // a runtime crash.
+  useEffect(() => {
+    setIndex((i) => clamp(i, 0, Math.max(length - 1, 0)))
+  }, [length])
+
+  const prev = useCallback(() => {
+    if (length <= 1) return
+    setIndex((i) => (i <= 0 ? length - 1 : i - 1))
+  }, [length])
+
+  const next = useCallback(() => {
+    if (length <= 1) return
+    setIndex((i) => (i >= length - 1 ? 0 : i + 1))
+  }, [length])
+
+  useEffect(() => {
+    if (!open || length <= 1) return undefined
+
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key !== 'ArrowLeft' && e.key !== 'ArrowRight') return
+      // Don't hijack arrow keys when a native media element is
+      // focused — the browser's own controls already use them for
+      // seek / volume, and stealing them would feel broken.
+      const active = document.activeElement
+      if (
+        active &&
+        (active.tagName === 'VIDEO' || active.tagName === 'AUDIO')
+      ) {
+        return
+      }
+      e.preventDefault()
+      if (e.key === 'ArrowLeft') prev()
+      else next()
+    }
+
+    window.addEventListener('keydown', onKey)
+    return () => window.removeEventListener('keydown', onKey)
+  }, [open, length, prev, next])
+
+  return { index, prev, next }
+}
+
+export default useCarousel

package/src/components/MessageAttachment/index.tsx

@@ -49,13 +49,15 @@ import VideoAttachment, {
  *
  *   - Image / Video render a 1 / 2 / 3 / 4-tile grid (5+ collapse
  *     into a `+N` overflow tile). Activating any tile opens the
- *     built-in `ImageViewer` / `VideoViewer` at that index, with
- *     arrow-key navigation between siblings.
+ *     built-in `ImageViewer` / `VideoViewer` at that index; when
+ *     `items.length > 1` the lightbox becomes a carousel (prev / next
+ *     chrome, ArrowLeft / ArrowRight, current / total counter) so the
+ *     user can browse siblings without closing the modal.
  *   - 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 viewer at that
- *     index, Audio gets its own native player, and File downloads
- *     the asset for that row.
+ *     its own activation target — Pdf opens the carousel-aware
+ *     `PdfViewer` at that index, Audio gets its own native player,
+ *     and File downloads the asset for that row.
  *
  * The Composer surface accepts only a single attachment at a time,
  * so its props omit `items` / `text`.
@@ -66,10 +68,17 @@ import VideoAttachment, {
  * message. Sent / Received wrap the media in the shared bubble chrome.
  *
  * Image / Video / Pdf are interactive in every state (Composer, Sent,
- * Received) — clicks open the corresponding native viewer with built-in
- * download. File rows download the asset directly. Audio renders a
- * native `<audio controls>` player which exposes its own download in
- * the kebab menu, so we don't render a separate Download affordance.
+ * Received) — clicks open the corresponding native lightbox `<dialog>`,
+ * which centers the media at reasonable max dimensions (Escape and
+ * backdrop click also dismiss). The Image viewer adds an explicit
+ * 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
+ * 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.
  *
  * # Lazy-loading defaults
  *

package/src/components/MessageAttachment/types.ts

@@ -108,7 +108,7 @@ export interface VideoItem {
 /** A single PDF inside a Pdf attachment (single or stacked). */
 export interface PdfItem {
   src: string
-  /** Filename — drives the title + the meta line + the viewer toolbar. */
+  /** Filename — drives the row title + the meta line + the viewer dialog's accessible name. */
   filename?: string
   /** File size in bytes — formatted into the `EXT · SIZE` meta line. */
   fileSize?: number