@linktr.ee/messaging-react 2.0.1 → 2.1.0

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

@@ -0,0 +1,156 @@
+import classNames from 'classnames'
+import React from 'react'
+
+import { renderTypeIcon } from '../../../AttachmentCard'
+import { getSourceType } from '../../../AttachmentCard/utils/mimeType'
+
+import type { LinkAttachmentVariant } from './CardShell'
+
+export interface CardThumbnailProps {
+  variant: LinkAttachmentVariant
+  /** Source URL of the hero image (or poster for video). */
+  thumbnailUrl?: string
+  /**
+   * Playable media URL. When provided alongside a video / audio `mimeType`,
+   * the hero region renders a native HTML5 player with controls instead of
+   * the static thumbnail / placeholder.
+   */
+  sourceUrl?: string
+  /** Alt text — typically the card's title. */
+  title?: string
+  /**
+   * Drives the placeholder type icon when no `thumbnailUrl` is provided,
+   * and selects between image / video / audio rendering when `sourceUrl`
+   * is set. Defaults to a generic image icon when unset.
+   */
+  mimeType?: string
+  /** Optional decorations layered into the top corners of the thumbnail. */
+  topLeft?: React.ReactNode
+  topRight?: React.ReactNode
+}
+
+const PLACEHOLDER_BG: Record<LinkAttachmentVariant, string> = {
+  dark: 'bg-white/10',
+  light: 'bg-black/5',
+}
+
+const PLACEHOLDER_ICON: Record<LinkAttachmentVariant, string> = {
+  dark: 'size-16 text-white/25',
+  light: 'size-16 text-black/25',
+}
+
+/**
+ * 180px hero region shown above the card body. Renders, in priority order:
+ *   1. A native `<video controls>` when `sourceUrl` is set and the mime is
+ *      video — `thumbnailUrl` acts as the poster.
+ *   2. A native `<audio controls>` when `sourceUrl` is set and the mime is
+ *      audio — laid over the audio type-icon backdrop.
+ *   3. The supplied `thumbnailUrl` image.
+ *   4. A placeholder type-icon derived from `mimeType`.
+ */
+/** Mime + sourceUrl gives us a playable audio attachment. */
+export const isPlayableAudio = (mimeType?: string, sourceUrl?: string) =>
+  !!sourceUrl && !!mimeType && getSourceType(mimeType) === 'audio'
+
+/**
+ * Mime + sourceUrl gives us a playable video or audio attachment. Used by
+ * Received to skip wrapping the shell in an interactive `<button>` so the
+ * native media controls remain operable.
+ */
+export const isPlayableMedia = (mimeType?: string, sourceUrl?: string) => {
+  if (!sourceUrl || !mimeType) return false
+  const source = getSourceType(mimeType)
+  return source === 'video' || source === 'audio'
+}
+
+/**
+ * Background colour the LinkAttachment cards switch to when the source is
+ * audio — flat neutral around the native `<audio>` chrome regardless of
+ * the dark / light variant.
+ */
+export const AUDIO_BG_CLASS = 'bg-[#F2F3F4]'
+
+const CardThumbnail: React.FC<CardThumbnailProps> = ({
+  variant,
+  thumbnailUrl,
+  sourceUrl,
+  title,
+  mimeType = 'image/*',
+  topLeft,
+  topRight,
+}) => {
+  const sourceType = getSourceType(mimeType)
+  const isPlayableVideo = !!sourceUrl && sourceType === 'video'
+
+  if (isPlayableAudio(mimeType, sourceUrl)) {
+    // Audio collapses the hero entirely — the native player sits inside
+    // the card chrome with a bit of padding so the card background
+    // (typically `bg-[#F2F3F4]`) is visible around it.
+    return (
+      <div className="p-3">
+        <audio
+          src={sourceUrl}
+          controls
+          preload="metadata"
+          className="block w-full"
+        >
+          <track kind="captions" />
+        </audio>
+      </div>
+    )
+  }
+
+  return (
+    <div
+      className={classNames(
+        'relative h-[180px] w-full overflow-hidden',
+        isPlayableVideo && 'bg-black'
+      )}
+    >
+      {isPlayableVideo ? (
+        <video
+          src={sourceUrl}
+          poster={thumbnailUrl}
+          controls
+          playsInline
+          preload="metadata"
+          className="absolute inset-0 h-full w-full object-contain"
+        >
+          <track kind="captions" />
+        </video>
+      ) : thumbnailUrl ? (
+        <img
+          src={thumbnailUrl}
+          alt={title ?? ''}
+          draggable={false}
+          className="absolute inset-0 h-full w-full object-cover"
+        />
+      ) : (
+        <div
+          className={classNames(
+            'flex h-full w-full items-center justify-center',
+            PLACEHOLDER_BG[variant]
+          )}
+        >
+          {renderTypeIcon(mimeType, {
+            className: PLACEHOLDER_ICON[variant],
+            weight: 'regular',
+          })}
+        </div>
+      )}
+
+      {topLeft ? (
+        <div className="pointer-events-auto absolute left-3 top-3 z-10">
+          {topLeft}
+        </div>
+      ) : null}
+      {topRight ? (
+        <div className="pointer-events-auto absolute right-3 top-3 z-10">
+          {topRight}
+        </div>
+      ) : null}
+    </div>
+  )
+}
+
+export default CardThumbnail

package/src/components/LinkAttachment/components/_shared/normalizeExternalHref.ts

@@ -0,0 +1,56 @@
+/**
+ * Scheme detector: `protocol:` per RFC 3986 — a letter followed by any
+ * combination of letters, digits, `+`, `.`, or `-` then `:`.
+ */
+const SCHEME_PATTERN = /^([a-z][a-z0-9+.-]*):/i
+
+/**
+ * Allowlist of schemes that are safe to forward into `<a href>` for
+ * external navigation. `javascript:` / `data:` / `vbscript:` etc. are
+ * intentionally **not** on this list — link-attachment data is
+ * effectively user-controlled, so passing them through would let a
+ * recipient click execute attacker-supplied code or markup.
+ */
+const SAFE_SCHEMES = new Set(['http', 'https', 'mailto', 'tel', 'sms'])
+
+/**
+ * Normalize a user-supplied URL into something safe to assign to
+ * `<a href>` for external navigation.
+ *
+ * Link attachments / link apps always point at external destinations
+ * (Spotify, TikTok, FAQ links, bare-hostname Linktree URLs like
+ * `tr.ee/briemix`, etc.). Without normalization, a bare hostname is
+ * treated as a relative path by the browser and clicks navigate within
+ * the host site (e.g. `https://linktr.ee/admin/tr.ee/briemix`) instead
+ * of opening the intended destination.
+ *
+ * Rules:
+ *   - Empty / whitespace-only → returns `undefined` (no href).
+ *   - Explicit scheme in the safe allowlist (`http`, `https`, `mailto`,
+ *     `tel`, `sms`) → returned trimmed.
+ *   - Explicit scheme **not** on the allowlist (`javascript:`, `data:`,
+ *     `vbscript:`, custom protocols, …) → returns `undefined` so the
+ *     shell falls back to a non-navigational chrome instead of letting
+ *     an attacker-controlled URL execute on click.
+ *   - Protocol-relative (`//example.com/…`) → returned as-is; browsers
+ *     resolve these against the current page's scheme.
+ *   - Site-relative path (`/admin/…`) → returned as-is so consumers can
+ *     still opt into in-app navigation if they really want to.
+ *   - Bare hostname or anything else → `https://` is prepended so the
+ *     browser treats it as an external URL.
+ */
+export function normalizeExternalHref(value?: string): string | undefined {
+  if (typeof value !== 'string') return undefined
+  const trimmed = value.trim()
+  if (trimmed === '') return undefined
+
+  const schemeMatch = SCHEME_PATTERN.exec(trimmed)
+  if (schemeMatch) {
+    const scheme = schemeMatch[1].toLowerCase()
+    return SAFE_SCHEMES.has(scheme) ? trimmed : undefined
+  }
+
+  if (trimmed.startsWith('//')) return trimmed
+  if (trimmed.startsWith('/')) return trimmed
+  return `https://${trimmed}`
+}

package/src/components/LinkAttachment/index.tsx

@@ -0,0 +1,68 @@
+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>
+)
+
+/**
+ * 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
+ * `LinkAttachment.Received` in the recipient's thread. Maps to the
+ * "Attachments" and "LinkApps" sections 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.).
+ *   - **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.
+ */
+const LinkAttachment = { Composer, Sent, Received }
+
+export default LinkAttachment
+export type { ComposerCardProps, SentCardProps, ReceivedCardProps }
+export type {
+  LinkAttachmentBaseProps,
+  LinkAttachmentCta,
+  LinkAttachmentLayout,
+} from './types'

package/src/components/LinkAttachment/types.ts

@@ -0,0 +1,69 @@
+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.
+ * - `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).
+ */
+export type LinkAttachmentLayout = 'featured' | 'classic'
+
+/**
+ * Shared props for the three `LinkAttachment.*` variants (Composer, Sent,
+ * Received). Maps to the "Attachments" + "LinkApps" sections of the messaging
+ * design system in Figma — a 280px-wide card with an optional 180px hero
+ * thumbnail, a title (optionally prefixed with a brand badge for Link Apps),
+ * a description, and either a URL footer or a CTA button.
+ */
+export interface LinkAttachmentBaseProps {
+  title?: string
+  /** Placeholder shown in the title slot before one is configured (dark variants only). */
+  placeholderTitle?: string
+  /** Secondary description rendered below the title. */
+  description?: string
+  /**
+   * Optional URL displayed at the bottom of the card (e.g. `tr.ee/briemix`).
+   * Ignored when `cta` is provided. Also used as the navigation target for
+   * the Received card when no `cta` is set.
+   */
+  url?: string
+  /** MIME type of the hero thumbnail — drives the type icon for empty states. */
+  mimeType?: string
+  /** 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.
+   */
+  sourceUrl?: string
+  /**
+   * Visual layout — `'featured'` keeps the 180px hero thumbnail above the
+   * body, `'classic'` drops the hero entirely for a compact text-only
+   * card. Defaults to `'featured'`.
+   */
+  layout?: LinkAttachmentLayout
+  /**
+   * Optional 16x16 brand badge rendered before the title (used by Link Apps:
+   * Spotify, TikTok, FAQ, Form, etc.). Consumers render whatever they want
+   * — typically a colored 4px-rounded square containing a glyph or `<img>`.
+   */
+  appIcon?: React.ReactNode
+  /**
+   * Optional call-to-action rendered below the description. When set,
+   * replaces the URL footer (e.g. FAQ "View FAQs", Form "Complete form").
+   */
+  cta?: LinkAttachmentCta
+}
+
+export interface LinkAttachmentCta {
+  label: string
+  /** When set, the CTA renders as an `<a>` opening in a new tab. */
+  href?: string
+  /** When set, called on click (in addition to `href` navigation if provided). */
+  onClick?: () => void
+}