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

package/dist/index.d.ts

@@ -37,37 +37,24 @@ export declare type AttachmentSourceType = 'image' | 'audio' | 'video' | 'docume
 declare interface AudioAttachmentSharedProps extends MessageAttachmentBaseProps {
     /** Audio source URL (`mp3`, `aac`, `wav`, …). */
     src?: string;
-    /** MIME type hint — typed onto the inline `<source>` element. */
+    /** MIME type hint — gates playability via the player's `canPlayType` probe. */
     mimeType?: string;
     /**
-     * Filename — used as the download default name (consumed by the
-     * native player's kebab menu). The HTML `<audio>` element doesn't
-     * expose a built-in title slot, so we don't render the filename
-     * inside the bubble itself.
+     * Filename — the download default name for the trailing action, and
+     * part of each control's accessible name.
      */
     filename?: string;
     /**
      * Stacked audio. Takes precedence over `src` when set. Each item
-     * renders its own native `<audio controls>` player, vertically
-     * stacked inside the same bubble with an 8px gap between players.
-     * Sent + Received only — the composer surface accepts a single
-     * attachment at a time.
+     * renders its own waveform row, vertically stacked inside the same
+     * bubble with an 8px gap. Sent + Received only — the composer surface
+     * accepts a single attachment at a time.
      */
     items?: MessageAttachmentAudioItem[];
-    /**
-     * `<audio preload>` hint applied to every player on the bubble.
-     * When omitted, the default depends on the rendered shape:
-     *
-     *   - Single audio (no `items`, or `items.length === 1`) →
-     *     `'metadata'` so the native player surfaces duration
-     *     immediately.
-     *   - Stacked audio (`items.length > 1`) → `'none'` so a thread
-     *     of voice memos doesn't fan out N parallel metadata requests
-     *     on first paint.
-     *
-     * Per-track overrides live on `AudioItem.preload`.
-     */
-    preload?: MediaPreloadMode;
+    /** See `AudioItem.durationSeconds`. Applies to the single-`src` shape. */
+    durationSeconds?: number;
+    /** See `AudioItem.waveformData`. Applies to the single-`src` shape. */
+    waveformData?: number[];
 }
 
 /**
@@ -985,7 +972,7 @@ declare type MediaPreloadMode = 'none' | 'metadata' | 'auto';
  *   - 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 carousel-aware
- *     `PdfViewer` at that index, Audio gets its own native player,
+ *     `PdfViewer` at that index, Audio gets its own waveform player,
  *     and File downloads the asset for that row.
  *
  * The Composer surface accepts only a single attachment at a time,
@@ -1003,12 +990,29 @@ declare type MediaPreloadMode = 'none' | 'metadata' | 'auto';
  * 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
+ * buttons on Pdf / File and the Audio card's trailing action 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.
  *
+ * # Audio requires a `<Channel>` ancestor
+ *
+ * `MessageAttachment.Audio.*` renders the waveform player card —
+ * a 32px play toggle, a 35-bar waveform with a progress fill and a
+ * native seek control, the duration, and a 32px trailing action
+ * (Remove in the composer, Download once sent). Playback is
+ * `stream-chat-react`'s pooled `AudioPlayer`, which is what supplies
+ * single-player-at-a-time across a thread, pause-on-navigation and
+ * saved-position restore across virtualized remounts.
+ *
+ * That pool is provided by `<Channel>`. Rendered outside one the card
+ * still draws in full, but its play and seek controls are disabled —
+ * so a story or a new consumer surface must mount `<Channel>` (or
+ * `stream-chat-react`'s `WithAudioPlayback`) for the card to be
+ * playable. The waveform bars themselves are styled with plain CSS
+ * (`.mes-audio-wave*`), so the shipped stylesheet is enough.
+ *
  * # Lazy-loading defaults
  *
  * Media attachments bake in network-friendly defaults for long chat
@@ -1029,13 +1033,12 @@ declare type MediaPreloadMode = 'none' | 'metadata' | 'auto';
  *     `VideoItem.preload` per item). Once the viewer is open the
  *     active item bumps to `preload="metadata"` so duration / the
  *     first frame appear immediately.
- *   - **Audio** — a single audio bubble defaults to
- *     `preload="metadata"` so the native player surfaces duration
- *     immediately. A stacked audio bubble (`items.length > 1`)
- *     defaults to `preload="none"` for every player so a thread of
- *     voice memos doesn't fan out N parallel metadata requests on
- *     first paint. Override via the attachment's `preload` prop
- *     (or `AudioItem.preload` per track).
+ *   - **Audio** — no audio bytes are fetched until the user presses
+ *     play: the pooled `AudioPlayer` acquires the shared `<audio>`
+ *     element lazily. A card whose `durationSeconds` is unknown makes
+ *     one `preload="metadata"` header request to fill the duration
+ *     slot; supplying `durationSeconds` (which `StreamAttachmentMessage`
+ *     maps from the attachment's persisted `duration`) avoids even that.
  *   - **Pdf** / **File** — no inline media element to throttle; the
  *     bubble renders compact rows that download / open lazily on
  *     activation. No `loading` / `preload` props on these surfaces.
@@ -1080,28 +1083,40 @@ export declare interface MessageAttachmentAudioComposerProps extends ComposerExt
     src?: string;
     mimeType?: string;
     filename?: string;
-    /** See `AudioAttachmentSharedProps.preload`. */
-    preload?: MediaPreloadMode;
+    /** See `AudioItem.durationSeconds`. */
+    durationSeconds?: number;
+    /** See `AudioItem.waveformData`. */
+    waveformData?: number[];
 }
 
 /** A single audio file inside an Audio attachment (single or stacked). */
 export declare interface MessageAttachmentAudioItem {
     src: string;
-    /** MIME type hint — typed onto the inline `<source>` element. */
+    /** MIME type hint — gates playability via the player's `canPlayType` probe. */
     mimeType?: string;
     /**
-     * Filename — used as the download default name (consumed by the
-     * native player's kebab menu).
+     * Filename — the download default name for the card's trailing
+     * action, and part of the card's accessible name.
      */
     filename?: string;
     /**
-     * Per-track override for the `<audio preload>` hint. Defaults to
-     * the parent attachment's `preload` value, which itself defaults
-     * to `'metadata'` for a single audio (so the native player can
-     * surface duration immediately) and `'none'` for a stacked thread
-     * (so a fan-out of metadata requests doesn't happen on first paint).
+     * Track length in seconds. Rendered as `MM:SS` before playback
+     * starts, so the duration is correct on first paint with no network
+     * request. Sourced from the Stream attachment's `duration` field,
+     * which the composer writes at send time. When omitted the card
+     * shows `--:--` until a one-shot `loadedmetadata` probe resolves.
      */
-    preload?: MediaPreloadMode;
+    durationSeconds?: number;
+    /**
+     * Waveform amplitudes, each `0..1`, in track order. Resampled to the
+     * rendered bar count, so any length is accepted. Sourced from the
+     * Stream attachment's `waveform_data`, which the composer computes
+     * from the local file and writes at send time.
+     *
+     * When omitted, the card renders a flat placeholder row: every bar at
+     * the minimum height, with the progress fill still tracking playback.
+     */
+    waveformData?: number[];
 }
 
 export declare type MessageAttachmentAudioReceivedProps = AudioAttachmentSharedProps;