@linktr.ee/messaging-react 3.34.0 → 3.35.0-rc-1786104411

package/src/components/RichCard/RichCard.test.tsx

@@ -0,0 +1,116 @@
+import React from 'react'
+import { describe, expect, it, vi } from 'vitest'
+
+import { renderWithProviders, screen, fireEvent } from '../../test/utils'
+
+import RichCard from '.'
+
+const HERO = 'https://cdn.example.com/hero.jpg'
+const IMG_2 = 'https://cdn.example.com/two.jpg'
+const IMG_3 = 'https://cdn.example.com/three.jpg'
+
+describe('RichCard', () => {
+  it('renders the title and subtitle', async () => {
+    renderWithProviders(
+      <RichCard.Received
+        title="Set up your welcome message"
+        subtitle="Automatically greet new followers."
+        images={[HERO]}
+      />
+    )
+    expect(await screen.findByTestId('rich-card')).toBeInTheDocument()
+    expect(screen.getByText('Set up your welcome message')).toBeInTheDocument()
+    expect(screen.getByText('Automatically greet new followers.')).toBeInTheDocument()
+  })
+
+  it('renders a single hero image for the hero presentation', async () => {
+    renderWithProviders(
+      <RichCard.Received
+        title="Welcome"
+        images={[HERO]}
+        imagePresentation="hero"
+      />
+    )
+    await screen.findByTestId('rich-card')
+    const images = screen.getAllByRole('img')
+    expect(images).toHaveLength(1)
+    expect(images[0]).toHaveAttribute('alt', 'Welcome')
+  })
+
+  it('renders up to three fanned images for the fan presentation', async () => {
+    const { container } = renderWithProviders(
+      <RichCard.Received
+        title="Collection"
+        images={[HERO, IMG_2, IMG_3]}
+        imagePresentation="fan"
+      />
+    )
+    await screen.findByTestId('rich-card')
+    // Three <img> nodes render; only the first is labelled (the rest are
+    // decorative, alt="" + aria-hidden, so they're out of the a11y tree).
+    expect(container.querySelectorAll('img')).toHaveLength(3)
+    expect(screen.getByAltText('Collection')).toBeInTheDocument()
+  })
+
+  it('defaults presentation from image count (>=2 fans)', async () => {
+    const { container } = renderWithProviders(
+      <RichCard.Sent title="Two" images={[HERO, IMG_2]} />
+    )
+    await screen.findByTestId('rich-card')
+    expect(container.querySelectorAll('img')).toHaveLength(2)
+  })
+
+  it('renders no image region when there are no images', async () => {
+    renderWithProviders(
+      <RichCard.Received title="Text only" subtitle="No hero here." />
+    )
+    await screen.findByTestId('rich-card')
+    expect(screen.queryAllByRole('img')).toHaveLength(0)
+    expect(screen.getByText('Text only')).toBeInTheDocument()
+  })
+
+  it('renders a url action as an external anchor, others as buttons', async () => {
+    const onClick = vi.fn()
+    renderWithProviders(
+      <RichCard.Received
+        title="Card"
+        images={[HERO]}
+        actions={[
+          { label: 'Shop now', href: 'tr.ee/x', variant: 'secondary' },
+          { label: 'Set up', onClick, variant: 'secondary' },
+        ]}
+      />
+    )
+    const link = await screen.findByText('Shop now')
+    expect(link.tagName).toBe('A')
+    expect(link).toHaveAttribute('href', 'https://tr.ee/x')
+    expect(link).toHaveAttribute('target', '_blank')
+
+    const button = screen.getByText('Set up')
+    expect(button.tagName).toBe('BUTTON')
+    fireEvent.click(button)
+    expect(onClick).toHaveBeenCalledTimes(1)
+  })
+
+  it('stacks a primary footer full-width and lays a secondary footer inline', async () => {
+    const { rerender } = renderWithProviders(
+      <RichCard.Received
+        title="Card"
+        images={[HERO]}
+        actions={[{ label: 'Set up welcome message', variant: 'primary' }]}
+      />
+    )
+    // Primary → stacked, full-width button.
+    expect(await screen.findByText('Set up welcome message')).toHaveClass('w-full')
+
+    rerender(
+      <RichCard.Received
+        title="Card"
+        images={[HERO]}
+        actions={[{ label: 'Shop now', href: 'tr.ee/x', variant: 'secondary' }]}
+      />
+    )
+    // Secondary → inline, content-width button (no w-full).
+    expect(screen.getByText('Shop now')).not.toHaveClass('w-full')
+  })
+})

package/src/components/RichCard/RichCardBody.tsx

@@ -0,0 +1,123 @@
+import classNames from 'classnames'
+import React from 'react'
+
+import CardCta from '../LinkAttachment/components/_shared/CardCta'
+import type { LinkAttachmentVariant } from '../LinkAttachment/components/_shared/CardShell'
+
+import type { RichCardActionButton } from './types'
+
+export interface RichCardBodyProps {
+  /** Surface the action buttons paint against (from `useChinPalette().surface`). */
+  ctaSurface: LinkAttachmentVariant
+  /** Ink for the title + subtitle, from `useChinPalette` — fixed per surface. */
+  chinTextColor: string
+  title?: string
+  subtitle?: string
+  subtitleLines?: number
+  appIcon?: React.ReactNode
+  actions?: RichCardActionButton[]
+}
+
+// Mirror LinkAttachment's `CardBody` type scales so the two cards read
+// identically (14/20 medium title, 12/16 subtitle). Colour is always supplied
+// via `chinTextColor`, so no per-variant text class is needed here.
+const TITLE_CLASS = 'line-clamp-2 text-[14px] font-medium leading-5 tracking-[0.28px]'
+const SUBTITLE_CLASS = 'text-[12px] leading-4 tracking-[0.24px]'
+
+/**
+ * Footer of action buttons. The **first** action's `variant` picks the layout:
+ * `primary` → stacked full-width buttons; `secondary` → an inline compact row.
+ * Each button still paints in its own emphasis. Returns `null` when there are
+ * no actions.
+ */
+const RichCardFooter: React.FC<{
+  surface: LinkAttachmentVariant
+  actions?: RichCardActionButton[]
+}> = ({ surface, actions }) => {
+  if (actions == null || actions.length === 0) return null
+
+  const inline = (actions[0].variant ?? 'primary') === 'secondary'
+
+  return (
+    <div
+      className={classNames(
+        'mt-3 flex gap-2',
+        inline ? 'flex-row flex-wrap' : 'flex-col'
+      )}
+    >
+      {actions.map((action, index) => (
+        <CardCta
+          key={`${action.label}-${index}`}
+          variant={surface}
+          cta={action}
+          fullWidth={!inline}
+          standalone
+        />
+      ))}
+    </div>
+  )
+}
+
+/**
+ * The rich card's "chin": title, subtitle (prose, multi-line by default), and
+ * the action footer. Padding matches `CardBody` (16px x, 12px y) so a rich card
+ * lines up with the link cards around it.
+ */
+const RichCardBody: React.FC<RichCardBodyProps> = ({
+  ctaSurface,
+  chinTextColor,
+  title,
+  subtitle,
+  subtitleLines = 3,
+  appIcon,
+  actions,
+}) => {
+  const hasTitle = title != null && title.trim() !== ''
+  const hasSubtitle = subtitle != null && subtitle.trim() !== ''
+  const hasActions = actions != null && actions.length > 0
+
+  if (!hasTitle && !hasSubtitle && !hasActions) return null
+
+  const chinTextStyle: React.CSSProperties = { color: chinTextColor }
+  const subtitleStyle: React.CSSProperties =
+    subtitleLines > 1
+      ? {
+          ...chinTextStyle,
+          display: '-webkit-box',
+          WebkitBoxOrient: 'vertical',
+          WebkitLineClamp: subtitleLines,
+          overflow: 'hidden',
+        }
+      : chinTextStyle
+
+  return (
+    <div className="shrink-0 px-4 py-3">
+      <div className="flex min-w-0 flex-col gap-[2px]">
+        {hasTitle && (
+          <div className="flex min-w-0 items-center gap-2">
+            {appIcon ? <span className="shrink-0">{appIcon}</span> : null}
+            <p className={classNames('min-w-0', TITLE_CLASS)} style={chinTextStyle}>
+              {title}
+            </p>
+          </div>
+        )}
+
+        {hasSubtitle && (
+          <p
+            className={classNames(
+              SUBTITLE_CLASS,
+              subtitleLines <= 1 && 'truncate'
+            )}
+            style={subtitleStyle}
+          >
+            {subtitle}
+          </p>
+        )}
+      </div>
+
+      <RichCardFooter surface={ctaSurface} actions={actions} />
+    </div>
+  )
+}
+
+export default RichCardBody

package/src/components/RichCard/RichCardCard.tsx

@@ -0,0 +1,93 @@
+import { resolveRichCardImagePresentation } from '@linktr.ee/messaging-taxonomy'
+import React from 'react'
+
+
+import BubbleTail from '../LinkAttachment/components/_shared/BubbleTail'
+import CardShell from '../LinkAttachment/components/_shared/CardShell'
+import type { LinkAttachmentVariant } from '../LinkAttachment/components/_shared/CardShell'
+import { useChinPalette } from '../LinkAttachment/components/_shared/useChinPalette'
+
+import RichCardBody from './RichCardBody'
+import RichCardImages from './RichCardImages'
+import type { RichCardBaseProps } from './types'
+
+export interface RichCardCardProps extends RichCardBaseProps {
+  variant: LinkAttachmentVariant
+}
+
+/**
+ * The shared internal rich-card renderer, parameterised by surface. `Sent`
+ * (dark) and `Received` (light) are thin wrappers over it. Composes
+ * LinkAttachment's card chrome primitives (`CardShell`, `useChinPalette`,
+ * `BubbleTail`) with the rich-card-specific image region + multi-action chin.
+ */
+const RichCardCard: React.FC<RichCardCardProps> = ({
+  variant,
+  title,
+  subtitle,
+  subtitleLines,
+  images = [],
+  imagePresentation,
+  actions,
+  appIcon,
+  accentColor,
+  groupPosition = 'single',
+}) => {
+  const presentation = resolveRichCardImagePresentation({
+    imagePresentation,
+    images,
+  })
+  const hasImages = images.length > 0
+  const isHero = hasImages && presentation === 'hero'
+
+  // Accent derives only from a single on-screen hero image — a `fan` (or
+  // image-less) card keeps the plain fill. Passing the hero URL through
+  // `useChinPalette` reuses its hero-failure tracking so a broken hero drops
+  // the accent with it, exactly as LinkAttachment does.
+  const chin = useChinPalette({
+    variant,
+    accentColor,
+    layout: 'featured',
+    thumbnailUrl: isHero ? images[0] : undefined,
+  })
+
+  const tailVisible =
+    groupPosition === 'single' || groupPosition === 'end'
+
+  return (
+    <BubbleTail
+      accentHex={chin.accentHex}
+      side={variant === 'dark' ? 'sender' : 'receiver'}
+      visible={tailVisible}
+    >
+      <CardShell
+        variant={variant}
+        accentHex={chin.accentHex}
+        fixedHeight={hasImages}
+        data-testid="rich-card"
+      >
+        {hasImages && (
+          <RichCardImages
+            variant={variant}
+            presentation={presentation}
+            images={images}
+            title={title}
+            heroUrl={isHero ? chin.thumbnailUrl : undefined}
+            onHeroError={chin.onImageError}
+          />
+        )}
+        <RichCardBody
+          ctaSurface={chin.surface}
+          chinTextColor={chin.chinTextColor}
+          title={title}
+          subtitle={subtitle}
+          subtitleLines={subtitleLines}
+          appIcon={appIcon}
+          actions={actions}
+        />
+      </CardShell>
+    </BubbleTail>
+  )
+}
+
+export default RichCardCard

package/src/components/RichCard/RichCardImages.tsx

@@ -0,0 +1,108 @@
+import type { RichCardImagePresentation } from '@linktr.ee/messaging-taxonomy'
+import classNames from 'classnames'
+import React from 'react'
+
+
+import { optimizeMessagingAttachmentUrl } from '../../utils/cdnImageUrl'
+// Reuse LinkAttachment's card chrome primitives — the rich card is a sibling
+// renderer over the same building blocks, not a from-scratch card.
+import type { LinkAttachmentVariant } from '../LinkAttachment/components/_shared/CardShell'
+import CardThumbnail from '../LinkAttachment/components/_shared/CardThumbnail'
+
+export interface RichCardImagesProps {
+  variant: LinkAttachmentVariant
+  presentation: RichCardImagePresentation
+  images: string[]
+  title?: string
+  /** Hero-only: the palette-tracked URL (cleared when the hero image errors). */
+  heroUrl?: string
+  onHeroError?: () => void
+}
+
+/** Placeholder fill behind the fanned images, per surface. */
+const FAN_BG: Record<LinkAttachmentVariant, string> = {
+  dark: 'bg-white/[0.06]',
+  light: 'bg-black/[0.04]',
+}
+
+// Deterministic fan geometry (no randomness — Chromatic snapshots must be
+// stable). Rotation + horizontal offset per image, keyed on how many there are.
+const FAN_ROTATION: Record<2 | 3, number[]> = {
+  2: [-6, 6],
+  3: [-9, 0, 9],
+}
+const FAN_OFFSET_PX: Record<2 | 3, number[]> = {
+  2: [-28, 28],
+  3: [-52, 0, 52],
+}
+
+/**
+ * A fanned stack of 2–3 thumbnails for the `fan` presentation (collection
+ * cards). An initial visual interpretation — the exact fan geometry should be
+ * reconciled against the Figma collection frames when they land.
+ */
+const RichCardFan: React.FC<{
+  variant: LinkAttachmentVariant
+  images: string[]
+  title?: string
+}> = ({ variant, images, title }) => {
+  const shown = images.slice(0, 3)
+  const count = shown.length >= 3 ? 3 : 2
+  const rotations = FAN_ROTATION[count]
+  const offsets = FAN_OFFSET_PX[count]
+
+  return (
+    <div
+      className={classNames(
+        'relative flex min-h-0 w-full flex-1 items-center justify-center overflow-hidden',
+        FAN_BG[variant]
+      )}
+    >
+      {shown.map((src, index) => (
+        <img
+          key={`${src}-${index}`}
+          src={optimizeMessagingAttachmentUrl(src) ?? src}
+          alt={index === 0 ? (title ?? '') : ''}
+          aria-hidden={index !== 0}
+          draggable={false}
+          loading="lazy"
+          decoding="async"
+          className="absolute h-[68%] w-[52%] rounded-xl object-cover shadow-lg ring-1 ring-black/10"
+          style={{
+            transform: `translateX(${offsets[index]}px) rotate(${rotations[index]}deg)`,
+            zIndex: index,
+          }}
+        />
+      ))}
+    </div>
+  )
+}
+
+/**
+ * The rich card's hero region. `hero` reuses `CardThumbnail` (single image, the
+ * official/link-share card); `fan` renders the fanned stack (collection card).
+ */
+const RichCardImages: React.FC<RichCardImagesProps> = ({
+  variant,
+  presentation,
+  images,
+  title,
+  heroUrl,
+  onHeroError,
+}) => {
+  if (presentation === 'fan') {
+    return <RichCardFan variant={variant} images={images} title={title} />
+  }
+
+  return (
+    <CardThumbnail
+      variant={variant}
+      thumbnailUrl={heroUrl ?? images[0]}
+      title={title}
+      mimeType="image/*"
+      onImageError={onHeroError}
+    />
+  )
+}
+
+export default RichCardImages

package/src/components/RichCard/index.tsx

@@ -0,0 +1,44 @@
+import React from 'react'
+
+import RichCardCard from './RichCardCard'
+import type { RichCardBaseProps } from './types'
+
+/** Props for `RichCard.Sent` / `RichCard.Received`. */
+export type RichCardSentCardProps = RichCardBaseProps
+export type RichCardReceivedCardProps = RichCardBaseProps
+
+const SentCard: React.FC<RichCardSentCardProps> = (props) => (
+  <RichCardCard {...props} variant="dark" />
+)
+
+const ReceivedCard: React.FC<RichCardReceivedCardProps> = (props) => (
+  <RichCardCard {...props} variant="light" />
+)
+
+/**
+ * The generic rich message card (`linktree_rich_card`) — the shared render
+ * primitive for rich message surfaces. Render `RichCard.Sent` for the sender's
+ * own copy (dark chrome) and `RichCard.Received` in the recipient's thread
+ * (light chrome). The official welcome card and broadcast link/collection cards
+ * are all this one card at different knobs:
+ *
+ *   - `hero` + `primary` action → the official welcome card (stacked button)
+ *   - `hero` + `secondary` action → a single-link broadcast (inline button)
+ *   - `fan` + `secondary` action → a collection broadcast
+ *
+ * A standalone renderer, not tied to Stream's `Attachment`: the dispatching
+ * consumer narrows an attachment with the taxonomy's `isRichCard`, then maps
+ * the taxonomy `RichCard` fields onto these props (resolving each action's
+ * `kind` to an `href` / `onClick`).
+ */
+const RichCard = {
+  Sent: SentCard,
+  Received: ReceivedCard,
+}
+
+export default RichCard
+export type {
+  RichCardBaseProps,
+  RichCardActionButton,
+  RichCardImagePresentation,
+} from './types'

package/src/components/RichCard/types.ts

@@ -0,0 +1,72 @@
+import type { RichCardImagePresentation } from '@linktr.ee/messaging-taxonomy'
+import type React from 'react'
+
+import type { BubbleGroupPosition } from '../MessageAttachment/types'
+
+export type { RichCardImagePresentation }
+
+/**
+ * A single footer action button — the **presentational** half of a taxonomy
+ * `RichCardAction`. The dispatching consumer resolves the action's `kind` to a
+ * behaviour before handing it here: `open_external_url` → `href`; a `launch_*`
+ * / `post_to_socials` kind → an `onClick` that opens its client surface. A kind
+ * the consumer does not recognise is dropped (no button) rather than mapped, so
+ * the card stands on its own image/title/subtitle — exactly the taxonomy's
+ * unknown-kind rule.
+ */
+export interface RichCardActionButton {
+  label: string
+  /** Renders the button as an `<a target="_blank">` (for `open_external_url`). */
+  href?: string
+  /** Called on activation (in addition to `href` navigation when both are set). */
+  onClick?: () => void
+  /**
+   * Button emphasis. The **first** action's variant drives the footer layout:
+   * `primary` → a stacked full-width button; `secondary` → an inline compact
+   * row. Defaults to `primary`.
+   */
+  variant?: 'primary' | 'secondary'
+}
+
+/**
+ * Shared props for the `RichCard.*` variants (Sent, Received). The generic
+ * rich message card: a `hero` or `fan` image region, a title + subtitle, and a
+ * `variant`-driven footer of action buttons. The official welcome card and
+ * broadcast link/collection cards are all this one card at different knobs.
+ */
+export interface RichCardBaseProps {
+  title?: string
+  /** Subtitle / body copy — the base attachment's `text`. */
+  subtitle?: string
+  /**
+   * Max lines the subtitle wraps before clamping. Defaults to `3` — rich cards
+   * carry prose, unlike the single-line link-preview default.
+   */
+  subtitleLines?: number
+  /** SAFE public thumbnail URLs. `hero` shows the first; `fan` shows up to 3. */
+  images?: string[]
+  /**
+   * Image layout. Defaults from {@link images} length (≤1 → `hero`, ≥2 →
+   * `fan`) via the taxonomy's `resolveRichCardImagePresentation`.
+   */
+  imagePresentation?: RichCardImagePresentation
+  /**
+   * Footer actions. Empty / absent → no footer. Clients pass one today; the
+   * shape is future-proof for several.
+   */
+  actions?: RichCardActionButton[]
+  /** Optional 16×16 brand badge rendered before the title. */
+  appIcon?: React.ReactNode
+  /**
+   * Dominant colour of the hero image (`#RRGGBB` or bare hex), painted as the
+   * card + tail surface. Only applied for a single on-screen `hero` image (a
+   * `fan` card keeps the plain fill) — the same gate LinkAttachment uses.
+   */
+  accentColor?: string
+  /**
+   * Position of this card inside its same-author run. `'single'` / `'end'`
+   * paint the accent-coloured bubble tail; `'first'` / `'middle'` omit it.
+   * Defaults to `'single'`.
+   */
+  groupPosition?: BubbleGroupPosition
+}

package/src/index.ts

@@ -8,6 +8,7 @@ export { ChannelView } from './components/ChannelView'
 export { default as ActionButton } from './components/ActionButton'
 export { default as LockedAttachment } from './components/CustomMessage/LockedAttachment'
 export { default as LinkAttachment } from './components/LinkAttachment'
+export { default as RichCard } from './components/RichCard'
 export { default as MessageAttachment } from './components/MessageAttachment'
 export { Avatar } from './components/Avatar'
 export { default as MessageBubble } from './components/MessageBubble'
@@ -93,6 +94,13 @@ export type {
   LinkAttachmentLayout,
   LinkAttachmentStatus,
 } from './components/LinkAttachment'
+export type {
+  RichCardBaseProps,
+  RichCardActionButton,
+  RichCardImagePresentation,
+  RichCardSentCardProps,
+  RichCardReceivedCardProps,
+} from './components/RichCard'
 export type {
   ImageComposerProps as MessageAttachmentImageComposerProps,
   ImageSentProps as MessageAttachmentImageSentProps,