@linktr.ee/messaging-react 2.1.0 → 2.2.0

package/src/components/LinkAttachment/LinkAttachment.stories.tsx

@@ -10,10 +10,6 @@ import React from 'react'
 import LinkAttachment from '.'
 
 const IMAGE_THUMBNAIL = '/image-thumbnail.jpg'
-const VIDEO_SOURCE = '/video-source.mp4'
-const VIDEO_POSTER = '/video-thumbnail.jpg'
-const AUDIO_SOURCE = '/audio-source.mp3'
-const PDF_SOURCE = '/document-source.pdf'
 
 const meta: Meta = {
   title: 'LinkAttachment',
@@ -130,90 +126,6 @@ const LINK_APPS: Array<{
   },
 ]
 
-/**
- * "Attachments" section of the Figma board — image / video / audio /
- * file attachments shown across the three messaging states. These are
- * pure media cards: the hero fills the card and there's no title /
- * description / link metadata. Playable types use inline native controls:
- *   - **Image** — full-bleed thumbnail; Received opens an image preview.
- *   - **Video** — inline `<video controls>` with a poster.
- *   - **Audio** — inline `<audio controls>` over the audio type-icon.
- *   - **PDF** — type-icon placeholder; Received opens the PDF in the
- *     browser's native viewer.
- *   - **File** — generic file type-icon; Received opens a preview.
- *   - **Placeholder** — empty draft state with the image type-icon.
- */
-const ATTACHMENT_ROWS: Array<{
-  label: string
-  /** Drives the placeholder type-icon and the inline player switch. */
-  mimeType?: string
-  /** Thumbnail (image source or video poster). */
-  thumbnailUrl?: string
-  /** Playable media URL — when set with a video/audio mime, renders inline. */
-  sourceUrl?: string
-  /**
-   * Override the Received `onClick` handler. Used by the PDF row to open
-   * the PDF in the browser's native viewer.
-   */
-  onReceivedClick?: () => void
-}> = [
-  { label: 'Image', mimeType: 'image/jpeg', thumbnailUrl: IMAGE_THUMBNAIL },
-  {
-    label: 'Video',
-    mimeType: 'video/mp4',
-    thumbnailUrl: VIDEO_POSTER,
-    sourceUrl: VIDEO_SOURCE,
-  },
-  { label: 'Audio', mimeType: 'audio/mpeg', sourceUrl: AUDIO_SOURCE },
-  {
-    label: 'PDF',
-    mimeType: 'application/pdf',
-    onReceivedClick: () => window.open(PDF_SOURCE, '_blank', 'noopener'),
-  },
-  { label: 'File', mimeType: 'application/octet-stream' },
-  { label: 'Placeholder' },
-]
-
-export const Attachments: StoryFn = () => (
-  <Table>
-    <TableHead columns={['Composer', 'Sent', 'Received']} />
-    <tbody>
-      {ATTACHMENT_ROWS.map(
-        ({ label, mimeType, thumbnailUrl, sourceUrl, onReceivedClick }) => (
-          <tr key={label}>
-            <RowLabel>{label}</RowLabel>
-            <td className="align-top">
-              <LinkAttachment.Composer
-                mimeType={mimeType}
-                thumbnailUrl={thumbnailUrl}
-                sourceUrl={sourceUrl}
-                onDismiss={() => alert(`Dismissed ${label}`)}
-              />
-            </td>
-            <td className="align-top">
-              <LinkAttachment.Sent
-                mimeType={mimeType}
-                thumbnailUrl={thumbnailUrl}
-                sourceUrl={sourceUrl}
-              />
-            </td>
-            <td className="align-top">
-              <LinkAttachment.Received
-                mimeType={mimeType}
-                thumbnailUrl={thumbnailUrl}
-                sourceUrl={sourceUrl}
-                onClick={
-                  onReceivedClick ?? (() => alert(`Open ${label} preview`))
-                }
-              />
-            </td>
-          </tr>
-        )
-      )}
-    </tbody>
-  </Table>
-)
-
 type LinkAppLayout = 'featured' | 'classic'
 type LinkAppState = 'Received' | 'Sent' | 'Composer'
 
@@ -280,10 +192,13 @@ const renderLinkAppCard = (
 
 /**
  * "LinkApps" section of the Figma board — link previews with a brand
- * badge prefixing the title and either a URL footer (Spotify, TikTok) or
- * a CTA button (FAQ, Form). Each app is shown in both the **Featured**
- * (hero image) and **Classic** (compact, no hero) layouts across all
- * three messaging states.
+ * badge prefixing the title and either a URL footer (Spotify, TikTok)
+ * or a CTA button (FAQ, Form). Each app is shown in both the
+ * **Featured** (hero image) and **Classic** (compact, no hero) layouts
+ * across all three messaging states.
+ *
+ * For chat **document / image / video / audio attachments**, see the
+ * `MessageAttachment` stories instead.
  */
 export const LinkApps: StoryFn = () => (
   <Table>

package/src/components/LinkAttachment/LinkAttachment.test.tsx

@@ -0,0 +1,69 @@
+import React from 'react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { renderWithProviders, screen, fireEvent } from '../../test/utils'
+
+import LinkAttachment from '.'
+
+describe('LinkAttachment.Received (link previews)', () => {
+  it('renders link previews with the hairline border treatment', async () => {
+    renderWithProviders(
+      <LinkAttachment.Received
+        title="Brie’s FAQ"
+        description="Get answers"
+        url="tr.ee/briemix"
+      />
+    )
+    const root = await screen.findByTestId('link-attachment')
+    expect(root.className).toContain('border')
+    expect(root.tagName).toBe('A')
+    expect(root.getAttribute('href')).toBe('https://tr.ee/briemix')
+    expect(root.getAttribute('target')).toBe('_blank')
+  })
+
+  it('renders as a button when no URL is set and onClick is provided', async () => {
+    const handleClick = vi.fn()
+    renderWithProviders(
+      <LinkAttachment.Received
+        title="Featured image"
+        thumbnailUrl="https://cdn.example.com/picture.jpg"
+        onClick={handleClick}
+      />
+    )
+    const root = await screen.findByTestId('link-attachment')
+    expect(root.tagName).toBe('BUTTON')
+    fireEvent.click(root)
+    expect(handleClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('routes the card-level onClick through the CTA when one is set', async () => {
+    const onClick = vi.fn()
+    const ctaOnClick = vi.fn()
+    renderWithProviders(
+      <LinkAttachment.Received
+        title="FAQ"
+        description="Get answers"
+        cta={{ label: 'View FAQs', onClick: ctaOnClick }}
+        onClick={onClick}
+      />
+    )
+    fireEvent.click(await screen.findByText('View FAQs'))
+    expect(onClick).toHaveBeenCalledTimes(1)
+    expect(ctaOnClick).toHaveBeenCalledTimes(1)
+  })
+})
+
+describe('LinkAttachment.Sent', () => {
+  it('renders the dark variant non-interactively', async () => {
+    renderWithProviders(
+      <LinkAttachment.Sent
+        title="My Playlist"
+        description="A handpicked workout mix"
+        url="tr.ee/briemix"
+      />
+    )
+    expect(await screen.findByText('My Playlist')).toBeInTheDocument()
+    expect(screen.queryByRole('button')).toBeNull()
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+})

package/src/components/LinkAttachment/components/Received/Card.tsx

@@ -20,12 +20,11 @@ export interface ReceivedCardProps extends LinkAttachmentBaseProps {
    *   - **Link app with a URL** (Spotify / TikTok / generic link): the card
    *     chrome is an `<a target="_blank">` opening `url` — `onClick` fires
    *     alongside the navigation (use for analytics).
-   *   - **Image / file / placeholder attachment**: the card has no URL, so
-   *     it renders as a button. `onClick` is the consumer's hook for
-   *     opening an image / file preview (lightbox).
-   *   - **Video / audio attachment**: the shell stays non-interactive so
-   *     the native media controls remain operable — `onClick` is ignored
-   *     in this configuration.
+   *   - **Hero-image only card**: the card has no URL, so it renders as
+   *     a button. `onClick` is the consumer's hook for opening a preview.
+   *   - **Video / audio link previews**: the shell stays non-interactive
+   *     so the native media controls remain operable — `onClick` is
+   *     ignored in this configuration.
    */
   onClick?: () => void
 }
@@ -33,14 +32,6 @@ export interface ReceivedCardProps extends LinkAttachmentBaseProps {
 /**
  * The card the recipient sees in chat for a link attachment. Matches the
  * Received column of the messaging design system in Figma.
- *
- * The chrome adapts to its content:
- *   - Link previews / link apps render the light card body and either
- *     navigate via `url` or surface a CTA button when `cta` is set.
- *   - Image / file attachments render as media-only cards — the 180px
- *     thumbnail (or type-icon placeholder) fills the card with no title /
- *     description body. `onClick` fires when the recipient taps the card
- *     so consumers can open an image preview / lightbox.
  */
 const ReceivedCard: React.FC<ReceivedCardProps> = ({
   title,
@@ -54,32 +45,21 @@ const ReceivedCard: React.FC<ReceivedCardProps> = ({
   cta,
   onClick,
 }) => {
-  // The Received card is opened by either the CTA (FAQ / Form), the URL
-  // (link previews / Spotify / TikTok), or — for media-only attachments —
-  // by tapping the entire card chrome to open a preview. We hand the
-  // anchor behavior off to CardShell only when there's no CTA so we don't
-  // end up with nested anchors when a CTA is present.
-  //
-  // Video / audio attachments are an exception: wrapping the shell in
-  // either a `<button>` or an `<a>` around `<video controls>` /
-  // `<audio controls>` creates nested interactive elements, and clicks on
-  // the native media controls can bubble up to fire the outer card
-  // action (preview / link navigation). For those, we render a plain
-  // non-interactive shell and let the media element own clicks — both
-  // `shellHref` and `shellOnClick` are suppressed even when `url` is set.
+  // Video / audio link previews wrap the native media element — render a
+  // plain non-interactive shell and let the media controls own clicks so
+  // taps on play/pause/scrubber don't fire the outer card action.
   const isPlayingMedia = isPlayableMedia(mimeType, sourceUrl)
   // Normalize the URL so a bare hostname like `tr.ee/briemix` (used in
   // our own docs / stories) is treated as an external link instead of a
   // relative path. Returns `undefined` for empty / whitespace-only
-  // values, so those fall through to the media-preview path instead of
+  // values, so those fall through to the preview path instead of
   // producing an empty `href` on the shell anchor.
   const normalizedUrl = normalizeExternalHref(url)
   const shellHref =
     cta == null && normalizedUrl != null && !isPlayingMedia
       ? normalizedUrl
       : undefined
-  const shellOnClick =
-    cta == null && !isPlayingMedia ? onClick : undefined
+  const shellOnClick = cta == null && !isPlayingMedia ? onClick : undefined
   const audioBg = isPlayableAudio(mimeType, sourceUrl)
     ? AUDIO_BG_CLASS
     : undefined

package/src/components/LinkAttachment/components/_shared/CardShell.tsx

@@ -38,7 +38,11 @@ export interface CardShellProps {
 
 const SHELL_CLASS = classNames(
   'relative block w-[280px] select-none overflow-hidden rounded-md',
-  'shadow-[0_0_0_1px_rgba(0,0,0,0.04),0_1px_2px_rgba(0,0,0,0.04),0_8px_32px_rgba(0,0,0,0.1)]'
+  // 1px hairline border that sits flush with the card chrome — matches
+  // the messaging design system's "small border around link attachments"
+  // treatment from the mobile spec. The drop shadow remains for depth.
+  'border border-black/[0.08]',
+  'shadow-[0_1px_2px_rgba(0,0,0,0.04),0_8px_32px_rgba(0,0,0,0.1)]'
 )
 
 /**

package/src/components/LinkAttachment/index.tsx

@@ -1,63 +1,37 @@
-import React, { Suspense } from 'react'
-
-import type { ComposerCardProps } from './components/Composer/Card'
-import type { ReceivedCardProps } from './components/Received/Card'
-import type { SentCardProps } from './components/Sent/Card'
-
-const ComposerCardLazy = React.lazy(
-  () => import('./components/Composer/Card')
-)
-const SentCardLazy = React.lazy(() => import('./components/Sent/Card'))
-const ReceivedCardLazy = React.lazy(
-  () => import('./components/Received/Card')
-)
-
-const LinkAttachmentFallback = () => (
-  <div
-    className="h-[280px] w-[280px] animate-pulse rounded-md bg-black/[0.06] shadow-[0_0_0_1px_rgba(0,0,0,0.04),0_1px_2px_rgba(0,0,0,0.04),0_8px_32px_rgba(0,0,0,0.1)]"
-    aria-hidden
-  />
-)
-
-const Composer = (props: ComposerCardProps) => (
-  <Suspense fallback={<LinkAttachmentFallback />}>
-    <ComposerCardLazy {...props} />
-  </Suspense>
-)
-
-const Sent = (props: SentCardProps) => (
-  <Suspense fallback={<LinkAttachmentFallback />}>
-    <SentCardLazy {...props} />
-  </Suspense>
-)
-
-const Received = (props: ReceivedCardProps) => (
-  <Suspense fallback={<LinkAttachmentFallback />}>
-    <ReceivedCardLazy {...props} />
-  </Suspense>
-)
+import ComposerCard, {
+  type ComposerCardProps,
+} from './components/Composer/Card'
+import ReceivedCard, {
+  type ReceivedCardProps,
+} from './components/Received/Card'
+import SentCard, { type SentCardProps } from './components/Sent/Card'
 
 /**
- * Link attachments (image / file media + 1P/3P Link Apps) shown in the chat
- * thread. Mirrors the `LockedAttachment` API — render `LinkAttachment.Composer`
- * while drafting, `LinkAttachment.Sent` after posting, and
+ * Link previews (1P / 3P Link Apps) shown in the chat thread. Mirrors
+ * the `LockedAttachment` API — render `LinkAttachment.Composer` while
+ * drafting, `LinkAttachment.Sent` after posting, and
  * `LinkAttachment.Received` in the recipient's thread. Maps to the
- * "Attachments" and "LinkApps" sections of the messaging design system.
+ * "LinkApps" section of the messaging design system.
  *
  * Two visual layouts via the `layout` prop:
- *   - **Featured** (default) — 180px hero thumbnail above the body. Used by
- *     image / file Attachments and by hero-image LinkApps (Spotify with
- *     cover art, TikTok with a frame, etc.).
+ *   - **Featured** (default) — 180px hero thumbnail above the body. Used
+ *     by hero-image LinkApps (Spotify with cover art, TikTok with a
+ *     frame, etc.).
  *   - **Classic** — compact card with no hero thumbnail; title /
  *     description / URL / CTA only. Used for LinkApp embeds without
  *     artwork (FAQ, Form) and any link preview that lacks OG imagery.
  *
- * Image / file Attachments use `layout="featured"` and skip the title /
- * description / URL body entirely (`CardBody` collapses to nothing when no
- * text content is provided). LinkApps always carry a title + description
- * and prefix the title with an `appIcon` brand badge.
+ * For chat **document / image / video / audio attachments**, reach for
+ * `MessageAttachment.{Image,Video,Audio,Pdf,File}` instead — those
+ * render as bubbles with built-in viewers (zoom-capable image
+ * lightbox, native PDF viewer, video / audio with download) and a
+ * caption slot for accompanying text.
  */
-const LinkAttachment = { Composer, Sent, Received }
+const LinkAttachment = {
+  Composer: ComposerCard,
+  Sent: SentCard,
+  Received: ReceivedCard,
+}
 
 export default LinkAttachment
 export type { ComposerCardProps, SentCardProps, ReceivedCardProps }

package/src/components/LinkAttachment/types.ts

@@ -4,11 +4,16 @@ import type React from 'react'
  * Visual layout for a `LinkAttachment.*` card.
  *
  * - `featured` — full card with a 180px hero thumbnail above the body.
- *   The default; matches the "Attachments" frames and the hero-image
- *   "LinkApps" frames in Figma.
+ *   The default; matches the hero-image "LinkApps" frames in Figma
+ *   (Spotify with cover art, TikTok with a frame, etc.).
  * - `classic` — compact card without a hero thumbnail. Title /
  *   description / URL / CTA only. Used for Link App embeds that don't
  *   carry artwork (and for plain link previews without OG imagery).
+ *
+ * For document / image / video / audio chat attachments, reach for
+ * `MessageAttachment.{Image,Video,Audio,Pdf,File}` instead — those
+ * render as bubbles with built-in viewers and download support and
+ * carry a `text` slot for accompanying captions.
  */
 export type LinkAttachmentLayout = 'featured' | 'classic'
 
@@ -36,9 +41,11 @@ export interface LinkAttachmentBaseProps {
   /** Hero thumbnail (180px tall) shown above the title block. */
   thumbnailUrl?: string
   /**
-   * Source URL for playable media (video, audio). When provided alongside a
-   * video / audio `mimeType`, the hero region renders an inline player with
-   * native controls instead of the static thumbnail / type-icon.
+   * Source URL for playable media in the hero region. When provided
+   * alongside a video / audio `mimeType`, the hero renders an inline
+   * native player (used by media-rich link previews that embed a
+   * preview clip). For chat document / file attachments, reach for
+   * `MessageAttachment.{Pdf,File}` instead.
    */
   sourceUrl?: string
   /**

package/src/components/MessageAttachment/Audio/AudioAttachment.stories.tsx

@@ -0,0 +1,203 @@
+import type { Meta, StoryFn } from '@storybook/react'
+import React from 'react'
+
+import {
+  StoryGrid,
+  StoryHeading,
+  StoryPage,
+  StoryRow,
+} from '../stories/StoryTable'
+import type { AudioItem } from '../types'
+
+import AudioAttachment from '.'
+
+const AUDIO_SRC =
+  'https://www.soundhelix.com/examples/mp3/SoundHelix-Song-1.mp3'
+
+const STACK_AUDIO: AudioItem[] = [
+  {
+    src: AUDIO_SRC,
+    mimeType: 'audio/mpeg',
+    filename: 'Take 1 — full mix.mp3',
+  },
+  {
+    src: AUDIO_SRC,
+    mimeType: 'audio/mpeg',
+    filename: 'Take 2 — vocals isolated.mp3',
+  },
+  {
+    src: AUDIO_SRC,
+    mimeType: 'audio/mpeg',
+    filename: 'Take 3 — instrumental only.mp3',
+  },
+]
+
+const meta: Meta = {
+  title: 'MessageAttachment/Audio',
+  parameters: { layout: 'fullscreen' },
+}
+export default meta
+
+const handleDismiss = () => {
+  // eslint-disable-next-line no-console
+  console.log('Dismissed audio attachment')
+}
+
+/**
+ * Native `<audio controls>` player inside a chat bubble. The browser
+ * chrome provides play / scrub / volume / kebab-menu (which already
+ * includes a download), so we don't render any extra controls.
+ * Composer adds an inline dismiss `×` to the right of the player.
+ */
+export const Single: StoryFn = () => (
+  <StoryPage>
+    <StoryHeading
+      title="Audio attachment"
+      description="Native browser audio chrome — play, scrub, volume, and the built-in download in the kebab menu. Composer renders an inline dismiss button next to the player."
+    />
+    <StoryGrid>
+      <StoryRow
+        label="Default"
+        composer={
+          <AudioAttachment.Composer
+            src={AUDIO_SRC}
+            mimeType="audio/mpeg"
+            filename="Morning meditation.mp3"
+            onDismiss={handleDismiss}
+          />
+        }
+        sent={
+          <AudioAttachment.Sent
+            src={AUDIO_SRC}
+            mimeType="audio/mpeg"
+            filename="Morning meditation.mp3"
+          />
+        }
+        received={
+          <AudioAttachment.Received
+            src={AUDIO_SRC}
+            mimeType="audio/mpeg"
+            filename="Morning meditation.mp3"
+          />
+        }
+      />
+    </StoryGrid>
+  </StoryPage>
+)
+
+export const SingleWithText: StoryFn = () => (
+  <StoryPage>
+    <StoryHeading
+      title="Audio with caption"
+      description="Caption sits below the player, inside the same bubble."
+    />
+    <StoryGrid>
+      <StoryRow
+        label="Caption"
+        composer={
+          <AudioAttachment.Composer
+            src={AUDIO_SRC}
+            mimeType="audio/mpeg"
+            filename="Morning meditation.mp3"
+            onDismiss={handleDismiss}
+          />
+        }
+        sent={
+          <AudioAttachment.Sent
+            src={AUDIO_SRC}
+            mimeType="audio/mpeg"
+            filename="Morning meditation.mp3"
+            text="Recorded this morning before training"
+          />
+        }
+        received={
+          <AudioAttachment.Received
+            src={AUDIO_SRC}
+            mimeType="audio/mpeg"
+            filename="Morning meditation.mp3"
+            text="Recorded this morning before training"
+          />
+        }
+      />
+    </StoryGrid>
+  </StoryPage>
+)
+
+/**
+ * Stacked audio attachments — multiple clips inside one bubble. Each
+ * clip renders its own native `<audio controls>` player, vertically
+ * stacked with a hairline separator.
+ *
+ * Sent + Received only — the composer surface accepts a single
+ * attachment at a time.
+ */
+export const Stacked: StoryFn = () => (
+  <StoryPage>
+    <StoryHeading
+      title="Stacked audio"
+      description="Each clip plays independently with its own native controls. Composer column is intentionally blank — the composer accepts a single attachment at a time."
+    />
+    <StoryGrid>
+      <StoryRow
+        label="2 clips"
+        composer={
+          <AudioAttachment.Composer
+            src={AUDIO_SRC}
+            mimeType="audio/mpeg"
+            filename="Morning meditation.mp3"
+            onDismiss={handleDismiss}
+          />}
+        sent={<AudioAttachment.Sent items={STACK_AUDIO.slice(0, 2)} />}
+        received={<AudioAttachment.Received items={STACK_AUDIO.slice(0, 2)} />}
+      />
+      <StoryRow
+        label="3 clips"
+        composer={
+          <AudioAttachment.Composer
+            src={AUDIO_SRC}
+            mimeType="audio/mpeg"
+            filename="Morning meditation.mp3"
+            onDismiss={handleDismiss}
+          />}
+        sent={<AudioAttachment.Sent items={STACK_AUDIO} />}
+        received={<AudioAttachment.Received items={STACK_AUDIO} />}
+      />
+    </StoryGrid>
+  </StoryPage>
+)
+
+/** Stacked audio with an accompanying caption.
+ *  Sent + Received only — see `Stacked` for the rationale. */
+export const StackedWithText: StoryFn = () => (
+  <StoryPage>
+    <StoryHeading
+      title="Stacked audio with caption"
+      description="Caption sits inside the same bubble, below the player stack. Composer column is intentionally blank — the composer accepts a single attachment at a time."
+    />
+    <StoryGrid>
+      <StoryRow
+        label="3 clips + caption"
+        composer={
+          <AudioAttachment.Composer
+            src={AUDIO_SRC}
+            mimeType="audio/mpeg"
+            filename="Morning meditation.mp3"
+            onDismiss={handleDismiss}
+          />
+        }
+        sent={
+          <AudioAttachment.Sent
+            items={STACK_AUDIO}
+            text="Three takes from the studio — let me know which mix you prefer."
+          />
+        }
+        received={
+          <AudioAttachment.Received
+            items={STACK_AUDIO}
+            text="Three takes from the studio — let me know which mix you prefer."
+          />
+        }
+      />
+    </StoryGrid>
+  </StoryPage>
+)