@justanarthur/modo-ui 0.6.0-canary.8 → 0.6.0

package/components/card/index.tsx

@@ -1,1070 +0,0 @@
-// biome-ignore-all lint: vendored upstream code keeps its own patterns (see the header)
-/*
- * Ported from Fluid Functionalism — github.com/mickadesign/fluid-functionalism
- * `registry/default/card.tsx` @ b3587bdbd83fc66c2a6aae3817ffb856cb09260b
- * MIT License © 2026 Micka Touillaud — fluidfunctionalism.com (notice: LICENSE.fluid-functionalism)
- * Local modifications:
- * - `"use client"` dropped; `@/lib/*`, `@/hooks/*` and
- *   `@/components/ui/fluid-hover-highlight` → `../../lib/*`, except
- *   `SizeProvider` → `../../primitives/sizes`.
- * - `next/link` replaced with plain anchors (no Next.js in modo) — the
- *   stretched card link and CardButton's `href` form.
- * - Prop JSDoc on CardProps rewritten from the FF docs API table (`children`
- *   re-declared so it is documented); modo TSDoc and examples on `Card`.
- * - Compound statics `Card.Group/.Header/.Title/.Description/.Action/
- *   .Content/.Footer/.Media/.Image/.Eyebrow/.Feature/.Button` attached with
- *   `Object.assign`, typed through a `CardComponent` cast on the forwardRef.
- *   Upstream's named exports are kept.
- * - Styling reads DS tokens (AGENTS.md styling): `text-[Npx]` →
- *   `text-<role>[-compact]`; inline `fontVariationSettings` → `weight-*`; the
- *   hex focus-ring fallback → `ring-focus-ring` / `border-focus-ring`;
- *   `rounded-[Npx]` → radius tokens; `duration-80|120|160` and tier-length JS
- *   durations → `duration-<tier>` / `spring.*`.
- * - `border` on a standalone Card (local): `"outlined"` draws the same hairline
- *   frame an outlined Card.Group gives its tiles; inside a group the group's
- *   `border` still decides. Borderless stays the default.
- * - `Card.Divider` / `CardDivider` (local): a hairline across the card between
- *   its parts (full-bleed, spaced like the parts), vertical in an inline card;
- *   the Separator primitive in the card's divider tone.
- * - `CardTitle` takes `as` (a heading level or another tag; a `span` by default)
- *   and `CardContent` takes `bodyText` (the ladder's body size instead of the
- *   inherited one), both local and opt-in.
- */
-
-import {
-  Children,
-  cloneElement,
-  createContext,
-  type ForwardRefExoticComponent,
-  forwardRef,
-  type HTMLAttributes,
-  isValidElement,
-  type MouseEventHandler,
-  type ReactElement,
-  type ReactNode,
-  type Ref,
-  type RefAttributes,
-  useContext,
-  useMemo,
-  useRef,
-} from 'react'
-import { FluidHoverHighlight } from '../../lib/fluid-hover-highlight'
-import { type IconComponent, useIcon } from '../../lib/icon-context'
-import { useShape } from '../../lib/shape-context'
-import { type SizeVariant, useSize } from '../../lib/size-context'
-import { useFluidHover, useRegisterFluidHoverItem } from '../../lib/use-fluid-hover'
-import { cn } from '../../lib/utils'
-import Separator, { type SeparatorProps } from '../../primitives/separator'
-import { SizeProvider } from '../../primitives/sizes'
-
-// ---------------------------------------------------------------------------
-// Card is shadcn/ui's compositional card — the same parts and `data-slot`
-// contract (Card, CardHeader, CardTitle, CardDescription, CardAction,
-// CardContent, CardFooter) — with the Fluid Functionalism layer on top:
-// design tokens, a weight-animated title, and a sibling CardGroup that owns
-// layout (stacked list, inline rows, or grid) plus the magnetic fluid hover
-// highlight that previews where a click will land.
-//
-// Unlike stock shadcn, the surface is transparent and borderless by default:
-// cards inherit whatever substrate their parent provides (see the Surfaces
-// system) and lean on hairline dividers / the fluid hover highlight rather than
-// a drawn frame. A Card renders fine on its own; inside a CardGroup it
-// registers itself so the group's highlight can find it.
-// ---------------------------------------------------------------------------
-
-type CardOrientation = 'card' | 'inline'
-type CardBorder = 'none' | 'outlined'
-
-// ── Group context ────────────────────────────────────────
-
-interface CardGroupContextValue {
-  registerItem: (index: number, element: HTMLElement | null) => void
-  activeIndex: number | null
-  /** Index of the persistently-selected card, or -1. Its neighbours drop the
-   *  hairline that would otherwise cut across the selection fill. */
-  selectedIndex: number
-  orientation: CardOrientation
-  columns: number
-  count: number
-  /** Individual cards carry their own border/tile shape (separated grids). */
-  separated: boolean
-  /** Inner hairline dividers are drawn between adjacent cards. */
-  divided: boolean
-  outlined: boolean
-}
-
-const CardGroupContext = createContext<CardGroupContextValue | null>(null)
-
-// ── Per-card context ─────────────────────────────────────
-// Lets the compositional parts (title, header, footer…) adapt to the card
-// they're inside without threading props: the title reads `emphasized` to
-// animate its weight; parts read `orientation` to switch padding/flow.
-
-interface CardContextValue {
-  emphasized: boolean
-  orientation: CardOrientation
-  clickable: boolean
-  /** An inline card holding a full CardImage centres its text + actions in a
-   *  column beside the image, so the footer drops below the text (hugged and
-   *  vertically centred) instead of trailing to the right. */
-  hasImage: boolean
-}
-
-const CardContext = createContext<CardContextValue>({
-  emphasized: false,
-  orientation: 'card',
-  clickable: false,
-  hasImage: false,
-})
-
-// ── CardGroup ────────────────────────────────────────────
-
-interface CardGroupProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onDrag'> {
-  /** How each card lays its own content out.
-   *  "card" — stacked vertically (media/header on top). "inline" — a
-   *  horizontal row (leading media, trailing footer), like a Table row.
-   *  @default "card" */
-  orientation?: CardOrientation
-  /** Number of grid columns. >1 enables 2-D fluid hover across rows and columns.
-   *  @default 1 */
-  columns?: number
-  /** "none" — borderless (default), separated only by subtle dividers.
-   *  "outlined" — draws a border: one shared frame when grouped, or one per
-   *  card when `separated`. @default "none" */
-  border?: CardBorder
-  /** Split the group into individually-shaped cards with a gap between them
-   *  (a grid of tiles) instead of one continuous divided block. @default false */
-  separated?: boolean
-  /** Enable the magnetic fluid-hover highlight. @default true */
-  fluidHover?: boolean
-}
-
-const CardGroup = forwardRef<HTMLDivElement, CardGroupProps>(
-  (
-    {
-      orientation = 'card',
-      columns = 1,
-      border = 'none',
-      separated = false,
-      fluidHover = true,
-      className,
-      children,
-      ...props
-    },
-    ref,
-  ) => {
-    const containerRef = useRef<HTMLDivElement>(null)
-    const shape = useShape()
-
-    // >1 column wraps into a grid, where nearest-item must be resolved in two
-    // dimensions; a single column is a plain vertical list.
-    const axis = columns > 1 ? 'xy' : 'y'
-    // A card grid has generous whitespace, so a gap click only routes when it
-    // lands within a hand's width of the highlighted card.
-    const hover = useFluidHover(containerRef, { axis, gapClick: { maxDistance: 16 } })
-    const { activeIndex, handlers, registerItem } = hover
-
-    // Assign each valid child a stable fluid hover index so callers never thread
-    // one through by hand (Table asks for it; here the group owns it).
-    const childArray = Children.toArray(children).filter(isValidElement)
-    const count = childArray.length
-    const indexed = childArray.map((child, i) => cloneElement(child as ReactElement<{ index?: number }>, { index: i }))
-    // Which card is selected — so its neighbours can drop the divider that
-    // would otherwise slice through the selection fill.
-    const selectedIndex = childArray.findIndex(child => (child.props as { selected?: boolean }).selected)
-
-    const outlined = border === 'outlined'
-    const divided = !separated
-
-    const contextValue = useMemo<CardGroupContextValue>(
-      () => ({
-        registerItem,
-        activeIndex,
-        selectedIndex,
-        orientation,
-        columns,
-        count,
-        separated,
-        divided,
-        outlined,
-      }),
-      [registerItem, activeIndex, selectedIndex, orientation, columns, count, separated, divided, outlined],
-    )
-
-    return (
-      <CardGroupContext.Provider value={contextValue}>
-        <div
-          ref={node => {
-            ;(containerRef as React.MutableRefObject<HTMLDivElement | null>).current = node
-            if (typeof ref === 'function') ref(node)
-            else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = node
-          }}
-          {...props}
-          data-slot="card-group"
-          data-orientation={orientation}
-          className={cn(
-            'relative grid',
-            // A shared frame clips the highlight + dividers to its rounded
-            // corners; separated tiles clip themselves.
-            outlined && !separated && `border border-border/60 overflow-hidden ${shape.container}`,
-            separated ? 'gap-2' : 'gap-0',
-            className,
-          )}
-          style={{
-            gridTemplateColumns: `repeat(${Math.max(1, columns)}, minmax(0, 1fr))`,
-          }}
-          onMouseEnter={fluidHover ? handlers.onMouseEnter : undefined}
-          onMouseMove={fluidHover ? handlers.onMouseMove : undefined}
-          onMouseLeave={fluidHover ? handlers.onMouseLeave : undefined}
-          onClick={fluidHover ? handlers.onClick : undefined}
-        >
-          {/* Fluid hover highlight — a single magnetic layer that springs to the
-              card nearest the cursor, previewing where a click will land. */}
-          <FluidHoverHighlight hover={hover} hidden={!fluidHover} className={cn('z-0', shape.container)} />
-
-          {indexed}
-        </div>
-      </CardGroupContext.Provider>
-    )
-  },
-)
-
-CardGroup.displayName = 'CardGroup'
-
-// ── Card ─────────────────────────────────────────────────
-
-interface CardProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onClick'> {
-  /** Compositional parts: Card.Image, Card.Media, Card.Header, Card.Content, Card.Footer. */
-  children?: ReactNode
-  /** Makes the whole card a clickable target (stretched button); fluid hover previews it. Receives the click event, or takes no argument. */
-  onClick?: MouseEventHandler<HTMLElement>
-  /** Makes the whole card a link (stretched anchor). */
-  href?: string
-  /** Opens href in a new tab. Defaults to `false`. */
-  external?: boolean
-  /** Accessible name for the stretched link/button when the whole card is clickable (the visible title isn't wired up automatically). */
-  label?: string
-  /** Persistent selected fill + title emphasis, on top of fluid hover. The group drops the hairline dividers around the selected card so the fill reads clean. Defaults to `false`. */
-  selected?: boolean
-  /** Dims and disables the card. Defaults to `false`. */
-  disabled?: boolean
-  /** Shows a dismiss (✕) button, revealed on hover or focus by default. Defaults to `false`. */
-  dismissible?: boolean
-  /** Keeps the dismiss control hidden until the card is hovered or holds focus. Pass false for an always-visible ✕. Defaults to `true`. */
-  dismissOnHover?: boolean
-  /** Called when the dismiss button is pressed. */
-  onDismiss?: () => void
-  /** Pins the card to one step of the size ladder — compact tightens type and padding. Omitted, it follows the surrounding SizeProvider. */
-  size?: SizeVariant
-  /** Frame of a standalone card: `"outlined"` draws a hairline around it, like an outlined group's tiles. Inside a Card.Group the group's `border` decides. Defaults to `"none"`. */
-  border?: CardBorder
-  /** Injected by Card.Group — do not set by hand. */
-  index?: number
-}
-
-type CardComponent = ForwardRefExoticComponent<CardProps & RefAttributes<HTMLDivElement>> & {
-  Group: typeof CardGroup
-  Header: typeof CardHeader
-  Title: typeof CardTitle
-  Description: typeof CardDescription
-  Action: typeof CardAction
-  Content: typeof CardContent
-  Footer: typeof CardFooter
-  Divider: typeof CardDivider
-  Media: typeof CardMedia
-  Image: typeof CardImage
-  Eyebrow: typeof CardEyebrow
-  Feature: typeof CardFeature
-  Button: typeof CardButton
-}
-
-/**
- * shadcn's compositional card, dressed in Fluid Functionalism. Stacked,
- * inline, or grid — borderless by default with fluid hover that previews
- * where a click will land.
- *
- * The same parts and data-slot contract as shadcn's Card, on a transparent,
- * borderless surface: a card inherits its parent's substrate and leans on
- * hairline dividers rather than a drawn frame (a standalone card opts into
- * one with `border="outlined"`). Card.Group owns the layout (a
- * stacked list, inline rows or a grid) and assigns every child its fluid
- * hover index; only a clickable card (`onClick` or `href`) joins the magnetic
- * highlight. A clickable card is one stretched button or link, while footer
- * actions and Card.Action stay independently clickable above it.
- *
- * Statics: Card.Group (orientation "card" | "inline", columns, border "none"
- * | "outlined", separated, fluidHover), Card.Header (title + description
- * grid, pins Card.Action top-right), Card.Title (weight-animates when the card
- * is selected; `as` renders it as a heading level), Card.Description,
- * Card.Action, Card.Content (`bodyText` sets the body size), Card.Footer (the
- * actions row; it wraps), Card.Divider (a hairline across the card between
- * its parts, vertical in an inline card), Card.Media (an icon tile, a logo or a [logoA, logoB] pair),
- * Card.Image (full-bleed banner, or a leading image when inline),
- * Card.Eyebrow (small uppercase label), Card.Feature (icon + title +
- * description row) and Card.Button (primary | secondary | ghost | link
- * action; an anchor when given `href`).
- *
- * @example {@include ./examples.mdx}
- */
-const Card = forwardRef<HTMLDivElement, CardProps>(
-  (
-    {
-      onClick,
-      href,
-      external,
-      label,
-      selected = false,
-      disabled = false,
-      dismissible = false,
-      dismissOnHover = true,
-      onDismiss,
-      size,
-      border = 'none',
-      index,
-      className,
-      children,
-      ...props
-    },
-    ref,
-  ) => {
-    const internalRef = useRef<HTMLDivElement>(null)
-    const shape = useShape()
-    // Resolve against the explicit prop first so this card's own padding and
-    // gaps agree with the SizeProvider it renders for its children.
-    const sizeClasses = useSize(size)
-    const compact = sizeClasses.variant === 'compact'
-    const group = useContext(CardGroupContext)
-    const XIcon = useIcon('x')
-
-    const orientation = group?.orientation ?? 'card'
-    const columns = group?.columns ?? 1
-    const count = group?.count ?? 1
-    const separated = group?.separated ?? true
-    const divided = group?.divided ?? false
-    const outlined = group?.outlined ?? false
-    const activeIndex = group?.activeIndex ?? null
-    const selectedIndex = group?.selectedIndex ?? -1
-
-    // Depend on the stable registerItem callback, not the whole group context —
-    // the context object's identity changes on every hover/selection frame,
-    // which would otherwise re-register every card each frame.
-    // Only a card that can be clicked joins the highlight: a highlight on an
-    // informational card would promise a click that has nowhere to land.
-    const registerItem = href || onClick ? group?.registerItem : undefined
-    useRegisterFluidHoverItem(registerItem, index, internalRef)
-
-    // Divider geometry: draw a hairline toward the neighbour below / to the
-    // right, but drop it next to the active OR selected card so the highlight
-    // and selection fill read clean (the same trick Table uses on row borders).
-    const col = index !== undefined ? index % columns : 0
-    const hasBelow = index !== undefined && index + columns < count
-    const hasRight = index !== undefined && col < columns - 1 && index + 1 < count
-    const self = index ?? -1
-    const touchesBelow = (i: number) => i === self || i === self + columns
-    const touchesRight = (i: number) => i === self || i === self + 1
-    const showBottom = divided && hasBelow && !(touchesBelow(activeIndex ?? -1) || touchesBelow(selectedIndex))
-    const showRight = divided && hasRight && !(touchesRight(activeIndex ?? -1) || touchesRight(selectedIndex))
-
-    const isInline = orientation === 'inline'
-    // An inline card with a full-bleed image reflows so its actions stack under
-    // the text (see the body wrapper below + CardHeader/CardFooter). Match the
-    // image child by identity OR displayName so detection and the split below
-    // agree even when module identity drifts (e.g. HMR duplication).
-    const isCardImage = (child: ReactNode) =>
-      isValidElement(child) &&
-      (child.type === CardImage || (child.type as { displayName?: string })?.displayName === 'CardImage')
-    const hasImage = Children.toArray(children).some(isCardImage)
-    const inlineImage = isInline && hasImage
-    const clickable = !!href || !!onClick
-    // Title weight follows the persistent selected state only — fluid hover
-    // previews via the highlight fill, not by bolding the label.
-    const emphasized = selected
-
-    // A standalone card (no group) is its own tile — always rounded + clipped.
-    // Inside a group, a separated tile carries its own rounding + clip only when
-    // it draws a visible frame; a borderless separated tile has no surface to
-    // hug, so it stays unclipped and its media reads as a plain square, and a
-    // card in a continuous block leans on the shared group frame for both.
-    const tileShape = !group
-      ? cn(shape.container, 'overflow-hidden', border === 'outlined' && 'border border-border/60')
-      : separated && outlined
-        ? cn(shape.container, 'overflow-hidden border border-border/60')
-        : ''
-
-    // Stretched overlay makes the whole card the click target while keeping
-    // action buttons (higher z) independently clickable — the accessible
-    // alternative to nesting interactive elements inside a button/anchor. A
-    // disabled card drops the overlay entirely so it can't be tabbed to or
-    // activated by keyboard (pointer-events-none only blocks the mouse).
-    const overlay =
-      clickable && !disabled ? (
-        href ? (
-          <a
-            href={href}
-            onClick={onClick}
-            target={external ? '_blank' : undefined}
-            rel={external ? 'noopener noreferrer' : undefined}
-            aria-label={label}
-            className="absolute inset-0 z-20 outline-none focus-visible:ring-1 focus-visible:ring-focus-ring rounded-[inherit]"
-          />
-        ) : (
-          <button
-            type="button"
-            onClick={onClick}
-            aria-label={label}
-            aria-pressed={selected || undefined}
-            className="absolute inset-0 z-20 outline-none focus-visible:ring-1 focus-visible:ring-focus-ring rounded-[inherit]"
-          />
-        )
-      ) : null
-
-    const cardContext = useMemo<CardContextValue>(
-      () => ({ emphasized, orientation, clickable, hasImage }),
-      [emphasized, orientation, clickable, hasImage],
-    )
-
-    // Inline image cards wrap their non-image parts in a centred column so the
-    // title, description, and actions hug together and sit vertically centred
-    // against the image instead of stretching to its full height.
-    let body: ReactNode = children
-    if (inlineImage) {
-      const parts = Children.toArray(children)
-      const image = parts.find(isCardImage)
-      const rest = parts.filter(part => part !== image)
-      body = (
-        <>
-          {image}
-          <div
-            className={cn('flex min-w-0 flex-1 flex-col justify-center gap-2', compact ? 'py-2.5 pr-3' : 'py-3.5 pr-4')}
-          >
-            {rest}
-          </div>
-        </>
-      )
-    }
-
-    const card = (
-      <CardContext.Provider value={cardContext}>
-        <div
-          ref={node => {
-            ;(internalRef as React.MutableRefObject<HTMLDivElement | null>).current = node
-            if (typeof ref === 'function') ref(node)
-            else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = node
-          }}
-          data-slot="card"
-          data-fluid-hover-index={index}
-          data-selected={selected || undefined}
-          data-orientation={orientation}
-          aria-disabled={disabled || undefined}
-          className={cn(
-            'group/card relative z-10 min-w-0 min-h-[60px]',
-            inlineImage
-              ? // Image on the left; the text + actions ride in a centred
-                // column beside it (see the wrapper in the body below).
-                cn('flex flex-row items-center', compact ? 'gap-2.5' : 'gap-3')
-              : isInline
-                ? cn('flex flex-row items-center', compact ? 'gap-2.5 pl-3' : 'gap-3 pl-4')
-                : cn('flex flex-col', compact ? 'pb-3' : 'pb-4'),
-            // Standalone (no group) cards can't lean on the group highlight, so
-            // they carry their own hover tint when interactive.
-            !group && clickable && !disabled && 'transition-colors duration-fast hover:bg-hover',
-            // Inline rows are single-line, so the corner dismiss would sit on
-            // the title's tail: the header yields right padding whenever the
-            // control is present — only while it's revealed in the on-hover
-            // case, so the resting text keeps the full row (the group-header
-            // gutter-swap pattern; instant, not transitioned).
-            dismissible &&
-              isInline &&
-              (dismissOnHover
-                ? '[&:hover_[data-slot=card-header]]:pr-10 [&:focus-within_[data-slot=card-header]]:pr-10'
-                : '[&_[data-slot=card-header]]:pr-10'),
-            tileShape,
-            disabled && 'opacity-50 pointer-events-none',
-            className,
-          )}
-          {...props}
-        >
-          {/* Persistent selected fill + dividers sit behind the static content
-              (-z-10); the stretched overlay (z-20) sits above content so the
-              whole card is clickable, and actions/dismiss (z-30) rise above the
-              overlay to stay independently interactive. */}
-          {selected && (
-            <span aria-hidden className={cn('absolute inset-0 -z-10 bg-active pointer-events-none', shape.container)} />
-          )}
-
-          {/* Dividers between borderless neighbours. Where both hairlines meet,
-              the vertical one stops 1px short so the horizontal hairline owns
-              the crossing pixel — two 60% lines would otherwise stack there and
-              read brighter than the rest of the grid. */}
-          {showBottom && (
-            <span aria-hidden className="absolute inset-x-0 bottom-0 h-px bg-border/60 pointer-events-none -z-10" />
-          )}
-          {showRight && (
-            <span
-              aria-hidden
-              className={cn(
-                'absolute top-0 right-0 w-px bg-border/60 pointer-events-none -z-10',
-                showBottom ? 'bottom-px' : 'bottom-0',
-              )}
-            />
-          )}
-
-          {overlay}
-
-          {body}
-
-          {/* Dismiss control sits above the stretched overlay. */}
-          {dismissible && (
-            <button
-              type="button"
-              onClick={onDismiss}
-              aria-label="Dismiss"
-              className={cn(
-                'absolute right-2 top-2 z-30 flex h-7 w-7 items-center justify-center text-muted-foreground hover:text-foreground cursor-pointer outline-none transition-colors duration-fast focus-visible:ring-1 focus-visible:ring-focus-ring',
-                // Over media the control needs its own ground, or the icon
-                // reads against whatever the image happens to be. Elsewhere
-                // the usual hover fill is enough. The chip takes the button
-                // radius either way.
-                hasImage ? 'bg-card/70 backdrop-blur-sm hover:bg-card' : 'hover:bg-hover',
-                // Revealed on hover / focus. focus-visible covers the keyboard
-                // path, since the control is the only way to dismiss.
-                // pointer-events gates alongside opacity: an invisible
-                // control must not swallow taps meant for the card (touch has
-                // no hover to reveal it). Keyboard focus still reaches it —
-                // pointer-events never blocks tabbing.
-                dismissOnHover &&
-                  'pointer-events-none opacity-0 transition-opacity duration-fast group-hover/card:pointer-events-auto group-hover/card:opacity-100 group-focus-within/card:pointer-events-auto group-focus-within/card:opacity-100 focus-visible:pointer-events-auto focus-visible:opacity-100',
-                shape.button,
-              )}
-            >
-              <XIcon size={compact ? 13 : 15} strokeWidth={1.5} />
-            </button>
-          )}
-        </div>
-      </CardContext.Provider>
-    )
-
-    // A size prop pins the card (and everything ladder-aware inside it) to one
-    // ladder step; the parts read the context.
-    return size ? <SizeProvider size={size}>{card}</SizeProvider> : card
-  },
-) as CardComponent
-
-Card.displayName = 'Card'
-
-// ── CardHeader ───────────────────────────────────────────
-// shadcn's header grid: title + description stack, with CardAction pinned to
-// the top-right column. In an inline card it becomes the flexible text column
-// between the leading media and trailing footer.
-
-const CardHeader = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(({ className, ...props }, ref) => {
-  const { orientation, hasImage } = useContext(CardContext)
-  const inlineImage = orientation === 'inline' && hasImage
-  const sizeClasses = useSize()
-  const compact = sizeClasses.variant === 'compact'
-  return (
-    <div
-      ref={ref}
-      data-slot="card-header"
-      className={cn(
-        'grid auto-rows-min items-start gap-1 has-data-[slot=card-action]:grid-cols-[1fr_auto]',
-        inlineImage
-          ? 'min-w-0'
-          : orientation === 'inline'
-            ? cn('min-w-0 flex-1', compact ? 'py-2.5' : 'py-3.5')
-            : compact
-              ? 'px-3 pt-3'
-              : 'px-4 pt-4',
-        className,
-      )}
-      {...props}
-    />
-  )
-})
-
-CardHeader.displayName = 'CardHeader'
-
-// ── CardTitle ────────────────────────────────────────────
-
-type CardTitleTag = 'span' | 'div' | 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6'
-
-interface CardTitleProps extends HTMLAttributes<HTMLSpanElement> {
-  /** The element the title renders as: a heading level (`'h2'`, `'h3'`, …) for a page outline, or another tag. The title keeps its look whatever the tag. Defaults to `'span'`. */
-  as?: CardTitleTag
-}
-
-const CardTitle = forwardRef<HTMLSpanElement, CardTitleProps>(
-  ({ as: Tag = 'span', className, children, ...props }, ref) => {
-    const { emphasized, orientation } = useContext(CardContext)
-    const sizeClasses = useSize()
-    const compact = sizeClasses.variant === 'compact'
-    // Inline rows trim the title to cap height so it centres tightly against
-    // the media/actions; stacked cards keep the natural line box.
-    const trim = orientation === 'inline' ? '[text-box:trim-both_cap_alphabetic]' : ''
-    // Ghost-span pattern: an invisible semibold copy reserves the width so the
-    // resting→active weight animation never reflows the row.
-    //
-    // Truncation support: a consumer's `truncate` lands on this grid, whose
-    // text-overflow can't ellipsize (only a block's own line boxes can — grid
-    // children just clip). The nowrap it sets inherits into the cell spans,
-    // so giving those spans overflow-hidden + ellipsis renders the … there
-    // instead; minmax(0,1fr) clamps the implicit track to the clipped grid's
-    // width so the ellipsis falls inside the visible box. All of it is inert
-    // while titles wrap normally.
-    return (
-      <Tag
-        ref={ref as Ref<HTMLHeadingElement>}
-        data-slot="card-title"
-        className={cn(
-          'inline-grid grid-cols-[minmax(0,1fr)] leading-snug',
-          Tag !== 'span' && 'm-0',
-          compact ? 'text-subtitle-compact' : 'text-subtitle',
-          className,
-        )}
-        {...props}
-      >
-        <span
-          className={cn(
-            'col-start-1 row-start-1 invisible min-w-0 overflow-hidden text-ellipsis',
-            trim,
-            'weight-semibold',
-          )}
-          aria-hidden="true"
-        >
-          {children}
-        </span>
-        <span
-          className={cn(
-            'col-start-1 row-start-1 min-w-0 overflow-hidden text-ellipsis text-foreground transition-[font-variation-settings] duration-fast',
-            trim,
-            // normal → semibold on emphasis, matching nav-item / menu-item /
-            // table (the opsz-paired tokens keep the advance width ~constant).
-            emphasized ? 'weight-semibold' : 'weight-normal',
-          )}
-        >
-          {children}
-        </span>
-      </Tag>
-    )
-  },
-)
-
-CardTitle.displayName = 'CardTitle'
-
-// ── CardDescription ──────────────────────────────────────
-
-const CardDescription = forwardRef<HTMLParagraphElement, HTMLAttributes<HTMLParagraphElement>>(
-  ({ className, ...props }, ref) => {
-    const sizeClasses = useSize()
-    const compact = sizeClasses.variant === 'compact'
-    return (
-      <p
-        ref={ref}
-        data-slot="card-description"
-        className={cn(
-          'leading-normal text-muted-foreground',
-          compact ? 'text-subtitle-compact' : 'text-subtitle',
-          className,
-        )}
-        {...props}
-      />
-    )
-  },
-)
-
-CardDescription.displayName = 'CardDescription'
-
-// ── CardAction ───────────────────────────────────────────
-// Pinned to the header's top-right column (shadcn's slot). Sits above the
-// stretched overlay so any control inside stays independently clickable.
-
-const CardAction = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(({ className, ...props }, ref) => (
-  <div
-    ref={ref}
-    data-slot="card-action"
-    className={cn('relative z-30 col-start-2 row-span-2 row-start-1 self-start justify-self-end', className)}
-    {...props}
-  />
-))
-
-CardAction.displayName = 'CardAction'
-
-// ── CardContent ──────────────────────────────────────────
-
-interface CardContentProps extends HTMLAttributes<HTMLDivElement> {
-  /** Sets the size ladder's body text (`text-body`, one step down in a compact region) on the content, so plain text there no longer takes the size of whatever surrounds the card. Off, the content inherits it, as before. Defaults to `false`. */
-  bodyText?: boolean
-}
-
-const CardContent = forwardRef<HTMLDivElement, CardContentProps>(({ bodyText = false, className, ...props }, ref) => {
-  const { orientation } = useContext(CardContext)
-  const sizeClasses = useSize()
-  const compact = sizeClasses.variant === 'compact'
-  return (
-    <div
-      ref={ref}
-      data-slot="card-content"
-      className={cn(
-        orientation === 'inline' ? '' : compact ? 'px-3 pt-2.5' : 'px-4 pt-3',
-        bodyText && sizeClasses.text,
-        className,
-      )}
-      {...props}
-    />
-  )
-})
-
-CardContent.displayName = 'CardContent'
-
-// ── CardFooter ───────────────────────────────────────────
-// Actions row. Rises above the stretched overlay (z-30) so buttons stay
-// clickable. In an inline card it becomes the trailing, right-aligned slot.
-
-const CardFooter = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(({ className, ...props }, ref) => {
-  const { orientation, hasImage } = useContext(CardContext)
-  const inlineImage = orientation === 'inline' && hasImage
-  const sizeClasses = useSize()
-  const compact = sizeClasses.variant === 'compact'
-  return (
-    <div
-      ref={ref}
-      data-slot="card-footer"
-      className={cn(
-        'relative z-30 flex items-center gap-1',
-        inlineImage
-          ? // Under the text, left-aligned in natural order (the inline
-            // wrapper owns the spacing).
-            'flex-wrap'
-          : orientation === 'inline'
-            ? cn('shrink-0 ml-auto', compact ? 'pr-3' : 'pr-4')
-            : cn('flex-wrap', compact ? 'px-3 pt-2.5' : 'px-4 pt-3'),
-        className,
-      )}
-      {...props}
-    />
-  )
-})
-
-CardFooter.displayName = 'CardFooter'
-
-// ── CardDivider ──────────────────────────────────────────
-// Local: a hairline across the card between two parts. The card has no
-// padding of its own, so a direct child runs edge to edge; its top margin
-// matches the parts' top padding, so the gap reads the same on both sides.
-
-const CardDivider = forwardRef<HTMLDivElement, SeparatorProps>(({ className, orientation, ...props }, ref) => {
-  const { orientation: cardOrientation } = useContext(CardContext)
-  const compact = useSize().variant === 'compact'
-  const vertical = (orientation ?? (cardOrientation === 'inline' ? 'vertical' : 'horizontal')) === 'vertical'
-  return (
-    <Separator
-      ref={ref}
-      data-slot="card-divider"
-      {...props}
-      orientation={vertical ? 'vertical' : 'horizontal'}
-      className={cn(
-        'bg-border/60',
-        vertical ? (compact ? 'my-2.5' : 'my-3.5') : compact ? 'mt-2.5' : 'mt-3',
-        className,
-      )}
-    />
-  )
-})
-
-CardDivider.displayName = 'CardDivider'
-
-// ── CardMedia ────────────────────────────────────────────
-// FF addition: a leading icon or brand logo(s). Not part of shadcn's anatomy,
-// but the connective tissue most product cards need. A tuple renders a
-// connected logo pair (e.g. a trigger — target).
-
-type CardLogo = string | [string, string]
-
-interface CardMediaProps {
-  logo?: CardLogo
-  logoAlt?: string
-  icon?: IconComponent
-  size?: number
-  className?: string
-}
-
-function CardMedia({ logo, logoAlt, icon: Icon, size = 22, className }: CardMediaProps) {
-  const { orientation } = useContext(CardContext)
-  const shape = useShape()
-  const sizeClasses = useSize()
-  const compact = sizeClasses.variant === 'compact'
-  // Stacked: sits in the header grid; add an extra 8px so the gap below the
-  // icon reads 12px (header gap-1 + mb-2). Inline: leading slot — the card owns
-  // the left inset, so no extra padding here.
-  const wrap = cn(orientation === 'inline' ? '' : 'mb-2', className)
-
-  if (logo) {
-    const logos = Array.isArray(logo) ? logo : [logo]
-    return (
-      <span data-slot="card-media" className={cn('inline-flex items-center gap-1.5 shrink-0', wrap)}>
-        {logos.map((src, i) => (
-          <span key={i} className="inline-flex items-center gap-1.5">
-            {i > 0 && <span aria-hidden className="w-2 h-px bg-border" />}
-            {/* eslint-disable-next-line @next/next/no-img-element */}
-            <img
-              src={src}
-              alt={logoAlt ?? ''}
-              width={size}
-              height={size}
-              className={cn('object-contain', shape.bg)}
-              style={{ width: size, height: size }}
-            />
-          </span>
-        ))}
-      </span>
-    )
-  }
-  if (Icon) {
-    // The icon sits in a 32×32 tinted tile so it reads as a media slot rather
-    // than a bare glyph. The tile is an overlay tint (not a solid surface) so it
-    // blends over whatever is behind it — the substrate or the hover highlight.
-    return (
-      <span
-        data-slot="card-media"
-        className={cn('inline-flex items-center justify-center shrink-0 size-8 bg-hover', shape.bg, wrap)}
-      >
-        <Icon size={compact ? 16 : 18} strokeWidth={1.5} className="text-muted-foreground" />
-      </span>
-    )
-  }
-  return null
-}
-
-// ── CardImage ────────────────────────────────────────────
-// FF addition: the prominent, full-bleed image (distinct from a small logo).
-// Stacked → a top banner; inline → a full-height leading image on the left that
-// bleeds past the card's left inset to sit flush against the edge.
-
-interface CardImageProps {
-  src: string
-  alt?: string
-  className?: string
-}
-
-function CardImage({ src, alt, className }: CardImageProps) {
-  const { orientation } = useContext(CardContext)
-  return (
-    // eslint-disable-next-line @next/next/no-img-element
-    <img
-      src={src}
-      alt={alt ?? ''}
-      data-slot="card-image"
-      // The image keeps a fixed 2px corner radius in every state — stacked or
-      // inline, framed or borderless — rather than inheriting a frame's larger
-      // clip. (A framed tile still clips the surrounding surface as before.)
-      className={cn(
-        'object-cover rounded-xs',
-        orientation === 'inline' ? 'size-40 shrink-0' : 'w-full aspect-[16/9]',
-        className,
-      )}
-    />
-  )
-}
-
-// A stable marker so the Card can recognise an image child by name, surviving
-// module-identity mismatches (e.g. HMR duplication) that break `type ===`.
-CardImage.displayName = 'CardImage'
-
-// ── CardEyebrow ──────────────────────────────────────────
-// Small uppercase label above the title (e.g. "New Model"). Typographically
-// it's the caption role of the type scale in uppercase — see /docs/sizes.
-
-const CardEyebrow = forwardRef<HTMLSpanElement, HTMLAttributes<HTMLSpanElement>>(({ className, ...props }, ref) => {
-  const compact = useSize().variant === 'compact'
-  return (
-    <span
-      ref={ref}
-      data-slot="card-eyebrow"
-      className={cn(
-        compact ? 'text-caption-compact' : 'text-caption',
-        'uppercase tracking-wide text-muted-foreground',
-        'weight-semibold',
-        className,
-      )}
-      {...props}
-    />
-  )
-})
-
-CardEyebrow.displayName = 'CardEyebrow'
-
-// ── CardFeature ──────────────────────────────────────────
-// FF addition: an icon + title + description row, for feature lists inside
-// CardContent.
-
-interface CardFeatureProps {
-  icon?: IconComponent
-  title: string
-  description?: string
-}
-
-function CardFeature({ icon: Icon, title, description }: CardFeatureProps) {
-  const sizeClasses = useSize()
-  const compact = sizeClasses.variant === 'compact'
-  return (
-    <div data-slot="card-feature" className={cn('flex items-start', sizeClasses.gap)}>
-      {Icon && <Icon size={sizeClasses.icon} strokeWidth={1.5} className="mt-0.5 shrink-0 text-muted-foreground" />}
-      <div className="flex flex-col gap-0.5 min-w-0">
-        <span className={cn('text-foreground [text-box:trim-both_cap_alphabetic]', sizeClasses.text, 'weight-medium')}>
-          {title}
-        </span>
-        {description && (
-          <span
-            className={cn('leading-relaxed text-muted-foreground', compact ? 'text-caption-compact' : 'text-caption')}
-          >
-            {description}
-          </span>
-        )}
-      </div>
-    </div>
-  )
-}
-
-// ── CardButton ───────────────────────────────────────────
-// Self-contained action button for the footer (keeps Card free of a Button
-// dependency, so it installs standalone). Renders an anchor when `href` is set.
-
-type CardButtonVariant = 'primary' | 'secondary' | 'ghost' | 'link'
-
-const CARD_BUTTON_VARIANTS: Record<CardButtonVariant, string> = {
-  primary: 'bg-foreground text-background hover:bg-foreground/90 active:bg-foreground/80',
-  secondary: 'bg-accent text-foreground hover:bg-accent/80 active:bg-accent',
-  ghost: 'text-muted-foreground hover:text-foreground hover:bg-hover active:bg-active',
-  link: 'text-foreground underline-offset-4 hover:underline !px-0 !h-auto',
-}
-
-interface CardButtonProps {
-  children: React.ReactNode
-  onClick?: () => void
-  href?: string
-  variant?: CardButtonVariant
-  icon?: IconComponent
-  iconPosition?: 'start' | 'end'
-  /** Opens the href in a new tab and appends an outward arrow glyph. */
-  external?: boolean
-  disabled?: boolean
-}
-
-function CardButton({
-  children,
-  onClick,
-  href,
-  variant = 'ghost',
-  icon: Icon,
-  iconPosition,
-  external = false,
-  disabled = false,
-}: CardButtonProps) {
-  const shape = useShape()
-  const ArrowRight = useIcon('arrow-right')
-  const sizeClasses = useSize()
-  const compact = sizeClasses.variant === 'compact'
-  const position = iconPosition ?? (external ? 'end' : 'start')
-
-  const glyph = Icon ? (
-    <Icon
-      size={compact ? 12 : 14}
-      strokeWidth={1.5}
-      className="shrink-0 transition-[stroke-width] duration-fast group-hover/action:stroke-[2]"
-    />
-  ) : null
-  const externalGlyph = external ? (
-    <ArrowRight
-      size={13}
-      strokeWidth={1.5}
-      className="shrink-0 -rotate-45 transition-[stroke-width] duration-fast group-hover/action:stroke-[2]"
-    />
-  ) : null
-
-  const inner = (
-    <>
-      {position === 'start' && glyph}
-      <span className="[text-box:trim-both_cap_alphabetic]">{children}</span>
-      {position === 'end' && glyph}
-      {externalGlyph}
-    </>
-  )
-
-  const classes = cn(
-    'group/action relative z-30 inline-flex items-center justify-center gap-1.5 h-7 px-2.5 cursor-pointer outline-none',
-    compact ? 'text-caption-compact' : 'text-caption',
-    'weight-medium',
-    'transition-colors duration-fast',
-    'focus-visible:ring-1 focus-visible:ring-focus-ring',
-    'disabled:opacity-50 disabled:pointer-events-none',
-    shape.button,
-    CARD_BUTTON_VARIANTS[variant],
-  )
-
-  if (href) {
-    return (
-      <a
-        href={href}
-        onClick={onClick}
-        target={external ? '_blank' : undefined}
-        rel={external ? 'noopener noreferrer' : undefined}
-        className={classes}
-      >
-        {inner}
-      </a>
-    )
-  }
-
-  return (
-    <button type="button" onClick={onClick} disabled={disabled} className={classes}>
-      {inner}
-    </button>
-  )
-}
-
-// Compound statics: `<Card.Group>`, `<Card.Header>`, … (typed by the
-// CardComponent cast on the forwardRef above).
-Object.assign(Card, {
-  Group: CardGroup,
-  Header: CardHeader,
-  Title: CardTitle,
-  Description: CardDescription,
-  Action: CardAction,
-  Content: CardContent,
-  Footer: CardFooter,
-  Divider: CardDivider,
-  Media: CardMedia,
-  Image: CardImage,
-  Eyebrow: CardEyebrow,
-  Feature: CardFeature,
-  Button: CardButton,
-})
-
-export type {
-  CardBorder,
-  CardButtonProps,
-  CardButtonVariant,
-  CardContentProps,
-  CardGroupProps,
-  CardLogo,
-  CardProps,
-  CardTitleProps,
-  CardTitleTag,
-}
-export {
-  Card,
-  CardAction,
-  CardButton,
-  CardContent,
-  CardDescription,
-  CardDivider,
-  CardEyebrow,
-  CardFeature,
-  CardFooter,
-  CardGroup,
-  CardHeader,
-  CardImage,
-  CardMedia,
-  CardTitle,
-}
-export default Card