@linktr.ee/messaging-react 2.0.1 → 2.1.0

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

@@ -0,0 +1,117 @@
+import { PencilSimpleIcon, XIcon } from '@phosphor-icons/react'
+import React from 'react'
+
+import type { LinkAttachmentBaseProps } from '../../types'
+import CardBody from '../_shared/CardBody'
+import CardShell from '../_shared/CardShell'
+import CardThumbnail, {
+  AUDIO_BG_CLASS,
+  isPlayableAudio,
+} from '../_shared/CardThumbnail'
+
+export interface ComposerCardProps extends LinkAttachmentBaseProps {
+  /**
+   * When provided, renders a dismiss X in the thumbnail corner. Called when
+   * the composer clicks it to remove the attachment.
+   */
+  onDismiss?: () => void
+  /**
+   * When provided, renders a pencil button to the right of the description
+   * that the composer can use to edit the attachment metadata.
+   */
+  onEditClick?: () => void
+}
+
+/**
+ * The card the composer sees while drafting a link attachment.
+ * Matches the Composer column of the messaging design system in Figma.
+ */
+const ComposerCard: React.FC<ComposerCardProps> = ({
+  title,
+  placeholderTitle,
+  description,
+  url,
+  mimeType,
+  thumbnailUrl,
+  sourceUrl,
+  layout = 'featured',
+  appIcon,
+  cta,
+  onDismiss,
+  onEditClick,
+}) => {
+  const isClassic = layout === 'classic'
+  const isAudio = isPlayableAudio(mimeType, sourceUrl)
+  const dismissButton = onDismiss ? (
+    <button
+      type="button"
+      onClick={onDismiss}
+      aria-label="Dismiss attachment"
+      className="flex size-6 items-center justify-center rounded-full bg-[#121110] text-white"
+    >
+      <XIcon className="size-3" weight="bold" />
+    </button>
+  ) : undefined
+
+  const editButton = onEditClick ? (
+    <button
+      type="button"
+      onClick={onEditClick}
+      aria-label="Edit attachment"
+      className="flex size-10 items-center justify-center rounded-full bg-white/10 text-white hover:bg-white/15"
+    >
+      <PencilSimpleIcon className="size-5" weight="regular" />
+    </button>
+  ) : undefined
+
+  // Audio cards collapse to just the native player — render the dismiss
+  // button as an inline sibling so it always has its own space and never
+  // overlaps the audio control's volume/menu buttons.
+  if (isAudio) {
+    return (
+      <CardShell variant="dark" bgClassName={AUDIO_BG_CLASS}>
+        <div className="flex items-center gap-2 pr-3">
+          <div className="min-w-0 flex-1">
+            <CardThumbnail
+              variant="dark"
+              sourceUrl={sourceUrl}
+              title={title}
+              mimeType={mimeType}
+            />
+          </div>
+          {dismissButton && <div className="shrink-0">{dismissButton}</div>}
+        </div>
+      </CardShell>
+    )
+  }
+
+  return (
+    <CardShell
+      variant="dark"
+      topRight={isClassic ? dismissButton : undefined}
+    >
+      {!isClassic && (
+        <CardThumbnail
+          variant="dark"
+          thumbnailUrl={thumbnailUrl}
+          sourceUrl={sourceUrl}
+          title={title}
+          mimeType={mimeType}
+          topRight={dismissButton}
+        />
+      )}
+      <CardBody
+        variant="dark"
+        title={title}
+        placeholderTitle={placeholderTitle}
+        description={description}
+        url={url}
+        appIcon={appIcon}
+        cta={cta}
+        trailingAction={editButton}
+      />
+    </CardShell>
+  )
+}
+
+export default ComposerCard

package/src/components/LinkAttachment/components/Composer/index.ts

@@ -0,0 +1,2 @@
+export { default as ComposerCard } from './Card'
+export type { ComposerCardProps } from './Card'

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

@@ -0,0 +1,132 @@
+import React from 'react'
+
+import type { LinkAttachmentBaseProps } from '../../types'
+import CardBody from '../_shared/CardBody'
+import CardShell from '../_shared/CardShell'
+import CardThumbnail, {
+  AUDIO_BG_CLASS,
+  isPlayableAudio,
+  isPlayableMedia,
+} from '../_shared/CardThumbnail'
+import { normalizeExternalHref } from '../_shared/normalizeExternalHref'
+
+export interface ReceivedCardProps extends LinkAttachmentBaseProps {
+  /**
+   * Fired when the recipient activates the card. Behavior depends on how
+   * the card is configured:
+   *   - **Link app with a CTA** (FAQ / Form): the CTA owns navigation;
+   *     `onClick` fires when the recipient taps the CTA itself, alongside
+   *     `cta.onClick` (use for analytics).
+   *   - **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.
+   */
+  onClick?: () => void
+}
+
+/**
+ * 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,
+  description,
+  url,
+  mimeType,
+  thumbnailUrl,
+  sourceUrl,
+  layout = 'featured',
+  appIcon,
+  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.
+  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
+  // 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 audioBg = isPlayableAudio(mimeType, sourceUrl)
+    ? AUDIO_BG_CLASS
+    : undefined
+
+  // When a CTA is set the shell isn't interactive — the CTA owns the
+  // click target. Forward the card-level `onClick` to the CTA so
+  // analytics / side-effect consumers still fire on activation while
+  // preserving the CTA's own `onClick` callback.
+  const wrappedCta =
+    cta && onClick
+      ? {
+          ...cta,
+          onClick: () => {
+            onClick()
+            cta.onClick?.()
+          },
+        }
+      : cta
+
+  return (
+    <CardShell
+      variant="light"
+      href={shellHref}
+      onClick={shellOnClick}
+      ariaLabel={title ?? 'Open attachment preview'}
+      bgClassName={audioBg}
+      data-testid="link-attachment"
+    >
+      {layout === 'featured' && (
+        <CardThumbnail
+          variant="light"
+          thumbnailUrl={thumbnailUrl}
+          sourceUrl={sourceUrl}
+          title={title}
+          mimeType={mimeType}
+        />
+      )}
+      <CardBody
+        variant="light"
+        title={title}
+        description={description}
+        url={url}
+        appIcon={appIcon}
+        cta={wrappedCta}
+      />
+    </CardShell>
+  )
+}
+
+export default ReceivedCard

package/src/components/LinkAttachment/components/Received/index.ts

@@ -0,0 +1,2 @@
+export { default as ReceivedCard } from './Card'
+export type { ReceivedCardProps } from './Card'

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

@@ -0,0 +1,57 @@
+import React from 'react'
+
+import type { LinkAttachmentBaseProps } from '../../types'
+import CardBody from '../_shared/CardBody'
+import CardShell from '../_shared/CardShell'
+import CardThumbnail, {
+  AUDIO_BG_CLASS,
+  isPlayableAudio,
+} from '../_shared/CardThumbnail'
+
+export interface SentCardProps extends LinkAttachmentBaseProps {}
+
+/**
+ * The card the sender sees in chat after a link attachment has been posted.
+ * Matches the Sent column of the messaging design system in Figma — same
+ * dark chrome as the Composer card minus the dismiss / edit affordances.
+ */
+const SentCard: React.FC<SentCardProps> = ({
+  title,
+  placeholderTitle,
+  description,
+  url,
+  mimeType,
+  thumbnailUrl,
+  sourceUrl,
+  layout = 'featured',
+  appIcon,
+  cta,
+}) => (
+  <CardShell
+    variant="dark"
+    bgClassName={
+      isPlayableAudio(mimeType, sourceUrl) ? AUDIO_BG_CLASS : undefined
+    }
+  >
+    {layout === 'featured' && (
+      <CardThumbnail
+        variant="dark"
+        thumbnailUrl={thumbnailUrl}
+        sourceUrl={sourceUrl}
+        title={title}
+        mimeType={mimeType}
+      />
+    )}
+    <CardBody
+      variant="dark"
+      title={title}
+      placeholderTitle={placeholderTitle}
+      description={description}
+      url={url}
+      appIcon={appIcon}
+      cta={cta}
+    />
+  </CardShell>
+)
+
+export default SentCard

package/src/components/LinkAttachment/components/Sent/index.ts

@@ -0,0 +1,2 @@
+export { default as SentCard } from './Card'
+export type { SentCardProps } from './Card'

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

@@ -0,0 +1,117 @@
+import classNames from 'classnames'
+import React from 'react'
+
+import type { LinkAttachmentCta } from '../../types'
+
+import CardCta from './CardCta'
+import type { LinkAttachmentVariant } from './CardShell'
+
+export interface CardBodyProps {
+  variant: LinkAttachmentVariant
+  title?: string
+  /** Placeholder shown in the title slot when no title is set (dark variants only). */
+  placeholderTitle?: string
+  description?: string
+  /** Footer URL shown below the description. Ignored when `cta` is set. */
+  url?: string
+  /**
+   * Optional 16x16 brand badge rendered before the title (used by Link Apps:
+   * Spotify, TikTok, FAQ, Form, etc.).
+   */
+  appIcon?: React.ReactNode
+  /** Optional CTA rendered in place of the URL footer. */
+  cta?: LinkAttachmentCta
+  /** Trailing action rendered on the right of the title/description block. */
+  trailingAction?: React.ReactNode
+}
+
+const TITLE_CLASS_BY_VARIANT: Record<LinkAttachmentVariant, string> = {
+  dark: 'text-white',
+  light: 'text-black/90',
+}
+
+const TITLE_DIMMED_CLASS = 'text-white/30'
+
+const SECONDARY_CLASS_BY_VARIANT: Record<LinkAttachmentVariant, string> = {
+  dark: 'text-white/55',
+  light: 'text-black/55',
+}
+
+/**
+ * Body of a `LinkAttachment.*` card. Matches the Figma `Container > Labels`
+ * group: 16px horizontal padding, 12px vertical padding, 8px gap between
+ * the title/description group and the URL/CTA footer, 4px gap within the
+ * title group.
+ *
+ * Returns `null` when there's nothing to render so plain image / file
+ * attachments collapse to a thumbnail-only card.
+ */
+const CardBody: React.FC<CardBodyProps> = ({
+  variant,
+  title,
+  placeholderTitle,
+  description,
+  url,
+  appIcon,
+  cta,
+  trailingAction,
+}) => {
+  const isDark = variant === 'dark'
+  const displayTitle = title ?? (isDark ? placeholderTitle : undefined) ?? ''
+  const hasTitle = displayTitle.trim() !== ''
+  const hasDescription =
+    description != null && description.trim() !== ''
+  // Mirror the trimming applied by `ReceivedCard` so a whitespace-only
+  // `url` collapses the body footer (and the whole body, for media-only
+  // cards) instead of rendering an empty line.
+  const trimmedUrl = typeof url === 'string' ? url.trim() : ''
+  const hasUrl = trimmedUrl !== ''
+  const hasCta = cta != null
+
+  if (!hasTitle && !hasDescription && !hasUrl && !hasCta) return null
+
+  const titleDimmed = isDark && !title
+
+  const titleClass = classNames(
+    'truncate text-base font-medium leading-6',
+    titleDimmed ? TITLE_DIMMED_CLASS : TITLE_CLASS_BY_VARIANT[variant]
+  )
+
+  const secondaryClass = classNames(
+    'truncate text-xs leading-4',
+    SECONDARY_CLASS_BY_VARIANT[variant]
+  )
+
+  return (
+    <div className="px-4 py-3">
+      <div className="flex items-end gap-3">
+        <div className="flex min-w-0 flex-1 flex-col gap-2">
+          <div className="flex min-w-0 flex-col gap-1">
+            {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', titleClass)}>
+                  {displayTitle}
+                </p>
+              </div>
+            )}
+
+            {hasDescription && (
+              <p className={secondaryClass}>{description}</p>
+            )}
+          </div>
+
+          {!hasCta && hasUrl && (
+            <p className={secondaryClass}>{trimmedUrl}</p>
+          )}
+        </div>
+
+        {trailingAction && <div className="shrink-0">{trailingAction}</div>}
+      </div>
+
+      {cta && <CardCta variant={variant} cta={cta} />}
+    </div>
+  )
+}
+
+export default CardBody

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

@@ -0,0 +1,69 @@
+import classNames from 'classnames'
+import React from 'react'
+
+import type { LinkAttachmentCta } from '../../types'
+
+import type { LinkAttachmentVariant } from './CardShell'
+import { normalizeExternalHref } from './normalizeExternalHref'
+
+export interface CardCtaProps {
+  variant: LinkAttachmentVariant
+  cta: LinkAttachmentCta
+}
+
+const BUTTON_CLASS_BY_VARIANT: Record<LinkAttachmentVariant, string> = {
+  dark: 'bg-white text-[#121110] hover:bg-white/90',
+  light: 'bg-[#121110] text-white hover:bg-[#2a2928]',
+}
+
+/**
+ * Pill-shaped CTA rendered below the description on Link App cards that
+ * surface an action instead of a URL (e.g. FAQ "View FAQs", Form "Complete form").
+ * Renders as `<a target="_blank">` when `cta.href` is set, otherwise as a
+ * plain `<button>`.
+ */
+const CardCta: React.FC<CardCtaProps> = ({ variant, cta }) => {
+  const className = classNames(
+    'mt-2 inline-flex h-10 w-full items-center justify-center rounded-full px-4 text-sm font-medium leading-none transition-colors',
+    BUTTON_CLASS_BY_VARIANT[variant]
+  )
+
+  // Mirror the URL normalization used by the shell anchor so bare
+  // hostnames (e.g. `tr.ee/foo`) open as external links rather than
+  // resolving against the current host.
+  const normalizedHref = normalizeExternalHref(cta.href)
+
+  if (normalizedHref) {
+    return (
+      <a
+        href={normalizedHref}
+        target="_blank"
+        rel="noopener noreferrer"
+        onClick={(e) => {
+          // Stop the click from bubbling up to the card's anchor wrapper
+          // (Received variant) so we don't navigate twice.
+          e.stopPropagation()
+          cta.onClick?.()
+        }}
+        className={`${className} no-underline`}
+      >
+        {cta.label}
+      </a>
+    )
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={(e) => {
+        e.stopPropagation()
+        cta.onClick?.()
+      }}
+      className={className}
+    >
+      {cta.label}
+    </button>
+  )
+}
+
+export default CardCta

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

@@ -0,0 +1,120 @@
+import classNames from 'classnames'
+import React from 'react'
+
+export type LinkAttachmentVariant = 'dark' | 'light'
+
+export interface CardShellProps {
+  variant: LinkAttachmentVariant
+  children: React.ReactNode
+  /**
+   * When provided, the entire card chrome is rendered as an anchor (used by
+   * the Received card to open the link target on click). Falls back to a
+   * `<div>` when omitted so Composer / Sent cards stay non-navigational.
+   */
+  href?: string
+  /**
+   * Click handler for the card chrome. When `href` is set the shell is an
+   * anchor and `onClick` is invoked in addition to navigation. When `href`
+   * is omitted but `onClick` is set, the shell renders as a clickable
+   * button (used by media-only Received cards to open an image preview).
+   */
+  onClick?: () => void
+  /** Accessible label for the clickable variant (when `onClick` is set without `href`). */
+  ariaLabel?: string
+  rootRef?: React.Ref<HTMLElement>
+  /**
+   * Absolutely-positioned slot rendered in the top-right corner of the
+   * shell. Used by the Composer card to surface its dismiss affordance
+   * when there's no hero thumbnail to anchor it to.
+   */
+  topRight?: React.ReactNode
+  /**
+   * Overrides the variant-derived background colour (e.g. audio cards
+   * use `bg-[#F2F3F4]` regardless of the dark/light variant).
+   */
+  bgClassName?: string
+  'data-testid'?: string
+}
+
+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)]'
+)
+
+/**
+ * Outer chrome for every `LinkAttachment.*` card. Matches the 280px width,
+ * 16px corner radius, and shadow-400 treatment from the Figma design system.
+ */
+const CardShell: React.FC<CardShellProps> = ({
+  variant,
+  children,
+  href,
+  onClick,
+  ariaLabel,
+  rootRef,
+  topRight,
+  bgClassName,
+  'data-testid': dataTestId,
+}) => {
+  const isInteractive = href != null || onClick != null
+  const className = classNames(
+    SHELL_CLASS,
+    bgClassName ?? (variant === 'dark' ? 'bg-[#121110]' : 'bg-white'),
+    // `focus-ring` is a design-system utility from the component-library
+    // tailwind preset — outline-none + a black 2px focus-visible ring
+    // with offset, so keyboard users can see the focused card.
+    isInteractive ? 'cursor-pointer no-underline focus-ring' : null
+  )
+
+  const corner = topRight ? (
+    <div className="pointer-events-auto absolute right-3 top-3 z-10">
+      {topRight}
+    </div>
+  ) : null
+
+  if (href) {
+    return (
+      <a
+        ref={rootRef as React.Ref<HTMLAnchorElement>}
+        href={href}
+        target="_blank"
+        rel="noopener noreferrer"
+        onClick={onClick}
+        data-testid={dataTestId}
+        className={className}
+      >
+        {children}
+        {corner}
+      </a>
+    )
+  }
+
+  if (onClick) {
+    return (
+      <button
+        ref={rootRef as React.Ref<HTMLButtonElement>}
+        type="button"
+        onClick={onClick}
+        aria-label={ariaLabel}
+        data-testid={dataTestId}
+        className={classNames(className, 'text-left')}
+      >
+        {children}
+        {corner}
+      </button>
+    )
+  }
+
+  return (
+    <div
+      ref={rootRef as React.Ref<HTMLDivElement>}
+      data-testid={dataTestId}
+      className={className}
+    >
+      {children}
+      {corner}
+    </div>
+  )
+}
+
+export default CardShell