@estiva-app/ui 0.12.10 → 0.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@estiva-app/ui",
-  "version": "0.12.10",
+  "version": "0.13.1",
   "description": "Estiva's design tokens (the contract) and a small set of primitives (a convenience) for every Estiva app.",
   "type": "module",
   "license": "MIT",

package/src/AttachmentCard.mdx

@@ -0,0 +1,62 @@
+import { Meta, Canvas, Controls } from '@storybook/addon-docs/blocks'
+import * as AttachmentCardStories from './AttachmentCard.stories'
+
+<Meta of={AttachmentCardStories} />
+
+# AttachmentCard
+
+Something attached — a document or an image — drawn as a card: posted, or
+waiting to be sent.
+
+<Canvas of={AttachmentCardStories.SeveralTogether} />
+
+## When
+
+The file decides the shape:
+
+- **an image with a picture** (`src`) — a 180px thumbnail; `onOpen` is what a
+  click on the picture does.
+- **anything else** — a 240px row: a type tile, the name, the type and size.
+  `href` opens it in a new tab; without one the row is dimmed.
+- `onDownload` — a download control that fades in on hover or keyboard focus.
+- `state="loading"` — an image on its way. `state="unreadable"` — it could not
+  be read: said, with a dashed hairline, never left as a gap.
+- **`pending`** — waiting to be sent: a 200px row with a remove control on its
+  corner (`onRemove`). `state` says what is happening to it: `ready` (its size),
+  `uploading`, `failed` (the reason, in `note`), `warning` (something the sender
+  should know, in `note`, with the full words in `noteHint`).
+
+<Canvas of={AttachmentCardStories.Pending} />
+
+## When not
+
+- A whole thing standing for itself, not a file → **Card**.
+- A word in a sentence that names a file → **InlineChip**.
+- A value picked into a field → **InputChip**, inside **ChipInput**.
+
+## How
+
+```tsx
+import { AttachmentCard } from '@estiva-app/ui'
+
+// Posted: the app fetched the picture, and opens it full screen itself.
+<AttachmentCard name={name} size={bytes} contentType={type} src={pictureUrl} onOpen={openFullScreen} onDownload={save} />
+
+// Waiting to be sent.
+<AttachmentCard pending name={name} size={bytes} state={uploading ? 'uploading' : 'ready'} src={localPreview} onRemove={remove} />
+```
+
+- The card fetches nothing. Reading a file may need the reader's own permission,
+  and only the app has it: pass the result — `src`, `href`, `state`.
+- A click on the picture, the download control and the remove control each stop
+  there, so they never also click the card or row the attachment sits in.
+- The name truncates. When it is cut off, the full name is on hover; a name
+  that fits, and a size, show nothing extra. `noteHint` is always on hover, since
+  it says more than the line.
+- The remove control is Peek's 20px round badge on the card's corner, a button
+  on Base UI's `Button` like InputChip's ✕ — not an `IconButton`, the 24px
+  square that fills on hover.
+
+## Props
+
+<Controls of={AttachmentCardStories.Document} />

package/src/AttachmentCard.stories.tsx

@@ -0,0 +1,92 @@
+import type { Meta, StoryObj } from '@storybook/react-vite'
+import { AttachmentCard } from './AttachmentCard'
+
+const svg = (w: number, h: number, body: string) =>
+  `data:image/svg+xml;utf8,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}"><rect width="${w}" height="${h}" fill="#0f1720"/>${body}</svg>`,
+  )}`
+
+/** Placeholder pictures — no real data in a story. */
+const WIDE = svg(480, 270, `<circle cx="120" cy="90" r="52" fill="#56c8ff"/><rect x="196" y="150" width="220" height="70" rx="12" fill="#4ade8c"/>`)
+const TALL = svg(270, 480, `<rect x="40" y="60" width="190" height="190" rx="16" fill="#b18cff"/><circle cx="135" cy="370" r="70" fill="#ffc94d"/>`)
+const SHOT = svg(
+  480,
+  270,
+  `<rect x="24" y="24" width="200" height="80" rx="10" fill="#56c8ff"/><rect x="24" y="128" width="320" height="26" rx="8" fill="#39414f"/><rect x="24" y="172" width="240" height="26" rx="8" fill="#39414f"/><circle cx="404" cy="196" r="46" fill="#4ade8c"/>`,
+)
+
+const noop = () => {}
+
+const meta = {
+  title: 'Components/AttachmentCard',
+  component: AttachmentCard,
+  parameters: { layout: 'padded' },
+  args: { name: 'Q3-billing-summary.pdf', size: 2_412_000, href: 'https://example.com/f', onDownload: noop },
+  argTypes: {
+    state: { control: 'inline-radio', options: ['ready', 'loading', 'unreadable', 'uploading', 'failed', 'warning'] },
+  },
+} satisfies Meta<typeof AttachmentCard>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+/** A document: a type tile, the name, and what it is. Hover it for the download control. */
+export const Document: Story = {}
+
+/** An image: its own picture, 180px wide, opening full screen on a click. */
+export const Image: Story = { args: { name: 'checkout-flow.png', size: 840_000, contentType: 'image/png', src: WIDE, onOpen: noop, href: undefined } }
+
+/** A tall picture keeps the card's height: it is cropped to fit, not stretched. */
+export const TallImage: Story = { args: { name: 'signup-screen.png', size: 1_180_000, contentType: 'image/png', src: TALL, onOpen: noop, href: undefined } }
+
+/** Without an address it is dimmed and opens nothing. */
+export const WithoutAnAddress: Story = { args: { name: 'annual-report.pdf', size: 4_800_000, href: undefined, onDownload: undefined } }
+
+/** Tabler's file-type icons at stroke 1.5. A type with no icon of its own lands on the plain file glyph rather than a wrong one. */
+export const EveryType: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-start gap-2">
+      {['proposal.pdf', 'contract.docx', 'forecast.xlsx', 'kickoff.pptx', 'export.csv', 'notes.txt', 'README.md', 'manifest.json', 'assets.zip', 'photo.heic'].map((name) => (
+        <AttachmentCard key={name} name={name} size={300_000} href="https://example.com/f" onDownload={noop} />
+      ))}
+    </div>
+  ),
+}
+
+/** A name longer than the card truncates, so every card in a row keeps the same two lines. The full name is on hover, because it is cut off. */
+export const LongName: Story = { args: { name: '2026-Q3-billing-reconciliation-and-invoice-summary-FINAL-v4.xlsx', size: 3_100_000 } }
+
+/** Several together, in one flow: images and rows are different widths on purpose. */
+export const SeveralTogether: Story = {
+  parameters: { controls: { disable: true } },
+  render: () => (
+    <div className="flex flex-wrap items-start gap-2">
+      <AttachmentCard name="checkout-flow.png" size={840_000} contentType="image/png" src={WIDE} onOpen={noop} onDownload={noop} />
+      <AttachmentCard name="Q3-billing-summary.pdf" size={2_412_000} href="https://example.com/f" onDownload={noop} />
+      <AttachmentCard name="raw-events.csv" size={96_000} href="https://example.com/f" onDownload={noop} />
+    </div>
+  ),
+}
+
+/** An image on its way. */
+export const Loading: Story = { args: { name: 'checkout-flow.png', contentType: 'image/png', state: 'loading', href: undefined } }
+
+/** It could not be read: said, not left as a gap, with the dashed hairline every unreadable card has. */
+export const Unreadable: Story = { args: { name: 'checkout-flow.png', contentType: 'image/png', state: 'unreadable', href: undefined } }
+
+/** Waiting to be sent, and ready: its own thumbnail and its size. Hover it for the remove control. */
+export const Pending: Story = {
+  args: { pending: true, name: 'Screenshot 2026-09-07 14-32-05.png', size: 248_000, contentType: 'image/png', src: SHOT, onRemove: noop, href: undefined, onDownload: undefined },
+}
+
+/** Waiting to be sent: a document shows its type in the tile. */
+export const PendingDocument: Story = { args: { ...Pending.args, name: 'Q3-billing-summary.pdf', contentType: 'application/pdf', size: 2_412_000, src: undefined } }
+
+export const Uploading: Story = { args: { ...Pending.args, state: 'uploading', src: undefined } }
+
+/** It could not be attached: the reason, in place of the size. */
+export const Failed: Story = { args: { ...Pending.args, state: 'failed', name: 'Screenshot 2026-09-07 14-32-05.tiff', note: "TIFF files aren't supported.", src: undefined } }
+
+/** Attached, with something the sender should know: a warning, not an error — nothing failed. The full words are on hover. */
+export const Warning: Story = { args: { ...Pending.args, state: 'warning', note: 'Not everyone can see this', noteHint: 'Only this app has a copy of this file.' } }

package/src/AttachmentCard.test.tsx

@@ -0,0 +1,172 @@
+// @vitest-environment jsdom
+/**
+ * What the AttachmentCard page claims, pinned: the file decides the shape (an
+ * image with a picture is a thumbnail, anything else a row); a row with an href
+ * opens in a new tab and a row without one is dimmed; the picture hands its
+ * click to the app; download and remove are the app's too, and neither click
+ * reaches what the card sits in; a pending card says what is happening to it;
+ * and a file that could not be read is dashed.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, render, screen } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { AttachmentCard } from './AttachmentCard'
+
+afterEach(cleanup)
+
+const classesOf = (el: Element | null) => el?.getAttribute('class')?.split(' ').filter(Boolean) ?? []
+const rootOf = (container: HTMLElement) => container.firstElementChild!
+
+describe('AttachmentCard', () => {
+  it('a document is a row: its type, its name, and what it is', () => {
+    const { container } = render(<AttachmentCard name="report.pdf" size={2_412_000} href="https://example.com/r" />)
+    expect(classesOf(rootOf(container))).toContain('w-[240px]')
+    expect(screen.getByText('report.pdf')).toBeTruthy()
+    // 2,412,000 bytes is 2.3 MB by the 1024 steps Peek's own story shows.
+    expect(screen.getByText('PDF · 2.3 MB')).toBeTruthy()
+  })
+
+  it('a row with an href opens it in a new tab, and its click stays out of what the card sits in', async () => {
+    const outside = vi.fn()
+    render(
+      <div onClick={outside}>
+        <AttachmentCard name="report.pdf" size={1000} href="https://example.com/r" />
+      </div>,
+    )
+    const link = screen.getByRole('link')
+    expect(link.getAttribute('href')).toBe('https://example.com/r')
+    expect(link.getAttribute('target')).toBe('_blank')
+    expect(link.getAttribute('rel')).toBe('noopener noreferrer')
+    link.addEventListener('click', (event) => event.preventDefault())
+    await userEvent.click(link)
+    expect(outside).not.toHaveBeenCalled()
+  })
+
+  it('a row without an href is dimmed and opens nothing', () => {
+    const { container } = render(<AttachmentCard name="report.pdf" size={1000} />)
+    expect(classesOf(rootOf(container))).toContain('opacity-70')
+    expect(screen.queryByRole('link')).toBeNull()
+  })
+
+  it('an image with a picture is a thumbnail, and its click is the app’s', async () => {
+    const onOpen = vi.fn()
+    const { container } = render(<AttachmentCard name="shot.png" src="data:image/png;base64,AA" onOpen={onOpen} />)
+    expect(classesOf(rootOf(container))).toContain('w-[180px]')
+    await userEvent.click(screen.getByRole('button', { name: 'Preview shot.png' }))
+    expect(onOpen).toHaveBeenCalledTimes(1)
+  })
+
+  it('an image type wins over a name with no extension', () => {
+    const { container } = render(<AttachmentCard name="clipboard" contentType="image/png" src="data:image/png;base64,AA" />)
+    expect(classesOf(rootOf(container))).toContain('w-[180px]')
+  })
+
+  it('download shows only when the app can do it, and its click is the app’s alone', async () => {
+    const onDownload = vi.fn()
+    const outside = vi.fn()
+    render(<AttachmentCard name="report.pdf" size={1000} href="#" />)
+    expect(screen.queryByRole('button', { name: 'Download report.pdf' })).toBeNull()
+    cleanup()
+    render(
+      <div onClick={outside}>
+        <AttachmentCard name="report.pdf" size={1000} href="#" onDownload={onDownload} />
+      </div>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Download report.pdf' }))
+    expect(onDownload).toHaveBeenCalledTimes(1)
+    expect(outside).not.toHaveBeenCalled()
+  })
+
+  describe('the full words on hover, only when they are cut off', () => {
+    // jsdom lays nothing out: a line is "cut off" here when its words are longer than 20 characters.
+    beforeEach(() => {
+      vi.spyOn(HTMLElement.prototype, 'scrollWidth', 'get').mockImplementation(function (this: HTMLElement) {
+        return (this.textContent?.length ?? 0) * 7
+      })
+      vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockReturnValue(140)
+    })
+    afterEach(() => vi.restoreAllMocks())
+    // Longer than the tooltip's 300ms wait, so "nothing" means nothing opened.
+    const pastTheWait = () => new Promise((resolve) => setTimeout(resolve, 600))
+
+    it.each([
+      ['a document', (name: string) => <AttachmentCard name={name} size={1000} href="#" />],
+      ['a document without an address', (name: string) => <AttachmentCard name={name} size={1000} />],
+      ['an image', (name: string) => <AttachmentCard name={`${name}.png`} src="data:image/png;base64,AA" />],
+      ['a file that could not be read', (name: string) => <AttachmentCard name={`${name}.png`} state="unreadable" />],
+      ['a pending card', (name: string) => <AttachmentCard pending name={`${name}.png`} size={1} />],
+    ])('%s: a name that is cut off shows in full; one that fits shows nothing', async (_, card) => {
+      const user = userEvent.setup()
+      render(card('2026-Q3-billing-reconciliation-FINAL-v4.xlsx'))
+      const long = screen.getByText(/^2026-Q3-billing-reconciliation-FINAL-v4/)
+      expect(long.className).toContain('truncate')
+      await user.hover(long)
+      expect((await screen.findByRole('tooltip')).textContent).toBe(long.textContent)
+      cleanup()
+
+      render(card('notes'))
+      await user.hover(screen.getByText(/^notes/))
+      await pastTheWait()
+      expect(screen.queryByRole('tooltip')).toBeNull()
+    })
+
+    it('the size never has one', async () => {
+      const user = userEvent.setup()
+      render(<AttachmentCard pending name="a.png" size={248_000} />)
+      await user.hover(screen.getByText('242 KB'))
+      await pastTheWait()
+      expect(screen.queryByRole('tooltip')).toBeNull()
+    })
+
+    it('a note’s hint is always on hover: it says more than the line', async () => {
+      const user = userEvent.setup()
+      render(<AttachmentCard pending name="a.png" size={1} state="warning" note="Not shared" noteHint="Only this app has a copy of this file." />)
+      await user.hover(screen.getByText('Not shared'))
+      expect((await screen.findByRole('tooltip')).textContent).toBe('Only this app has a copy of this file.')
+    })
+  })
+
+  it('an image on its way is a busy placeholder, named as a status', () => {
+    const { container } = render(<AttachmentCard name="shot.png" state="loading" />)
+    const root = rootOf(container)
+    // A name needs a role to hang on: a plain div may not carry aria-label.
+    expect(screen.getByRole('status', { name: 'Loading shot.png' })).toBe(root)
+    expect(root.getAttribute('aria-busy')).toBe('true')
+    expect(classesOf(root)).toContain('animate-pulse')
+  })
+
+  it('a file that could not be read says so, with a dashed hairline', () => {
+    const { container } = render(<AttachmentCard name="shot.png" state="unreadable" />)
+    expect(classesOf(rootOf(container))).toContain('border-dashed')
+    expect(screen.getByText('Could not be loaded')).toBeTruthy()
+  })
+
+  it('pending: the size when ready, "Uploading…" while not, the reason when it failed, the warning when it is one', () => {
+    render(<AttachmentCard pending name="a.png" size={248_000} />)
+    expect(screen.getByText('242 KB')).toBeTruthy()
+    cleanup()
+    render(<AttachmentCard pending name="a.png" size={248_000} state="uploading" />)
+    expect(screen.getByText('Uploading…')).toBeTruthy()
+    cleanup()
+    const failed = render(<AttachmentCard pending name="a.tiff" size={1} state="failed" note="TIFF files aren't supported." />)
+    expect(screen.getByText("TIFF files aren't supported.").className).toContain('text-error-default')
+    expect(classesOf(rootOf(failed.container))).toContain('border-error-default')
+    cleanup()
+    const warning = render(<AttachmentCard pending name="a.png" size={1} state="warning" note="Not everyone can see this" />)
+    expect(screen.getByText('Not everyone can see this').className).toContain('text-warning-default')
+    expect(classesOf(rootOf(warning.container))).toContain('border-warning-default')
+  })
+
+  it('a pending card is removed by the app, and the click stays out of what it sits in', async () => {
+    const onRemove = vi.fn()
+    const outside = vi.fn()
+    render(
+      <div onClick={outside}>
+        <AttachmentCard pending name="a.png" size={1} onRemove={onRemove} />
+      </div>,
+    )
+    await userEvent.click(screen.getByRole('button', { name: 'Remove a.png' }))
+    expect(onRemove).toHaveBeenCalledTimes(1)
+    expect(outside).not.toHaveBeenCalled()
+  })
+})

package/src/AttachmentCard.tsx

@@ -0,0 +1,324 @@
+import { useLayoutEffect, useRef, useState, type ComponentPropsWithRef, type FC } from 'react'
+import { Button as BaseButton } from '@base-ui/react/button'
+import {
+  IconAlertCircle,
+  IconAlertTriangle,
+  IconDownload,
+  IconFile,
+  IconFileTypeCsv,
+  IconFileTypeDocx,
+  IconFileTypePdf,
+  IconFileTypePpt,
+  IconFileTypeTxt,
+  IconFileTypeXls,
+  IconFileTypeZip,
+  IconJson,
+  IconLoader2,
+  IconMarkdown,
+  IconX,
+} from '@tabler/icons-react'
+import { Card } from './Card'
+import { IconButton } from './IconButton'
+import { Link } from './Link'
+import { WithTooltip } from './Tooltip'
+import { cn } from './cn'
+
+/**
+ * Something attached — a document or an image — drawn as a card.
+ *
+ * Peek's two attachment components, class for class (UIG-27, Katerina's ruling
+ * of 14 September that both apps draw one): `FileAttachmentCard`, the card on
+ * something already posted, and `PendingAttachmentChip`, the card in a composer
+ * waiting to go. What stays in each app is what only the app can do: fetch the
+ * bytes with the reader's own permission, open an image full screen, save a
+ * file. The card is told the result — a `src`, an `href`, a `state` — and hands
+ * a click back through `onOpen`, `onDownload` and `onRemove`.
+ *
+ * Two shapes, decided by the file: an **image** with a picture is a 180px
+ * thumbnail you can open; anything else is a 240px **row** — a type tile, the
+ * name, and what it is. Waiting to be sent (`pending`) it is a 200px row with a
+ * remove control on its corner.
+ *
+ * One change from Peek, by ruling: a file that could not be read has a dashed
+ * hairline, as every card that cannot be read does.
+ */
+export type AttachmentCardState = 'ready' | 'loading' | 'unreadable' | 'uploading' | 'failed' | 'warning'
+
+const ICON_BY_EXTENSION: Record<string, FC<{ size?: number; stroke?: number; className?: string }>> = {
+  pdf: IconFileTypePdf,
+  doc: IconFileTypeDocx,
+  docx: IconFileTypeDocx,
+  xls: IconFileTypeXls,
+  xlsx: IconFileTypeXls,
+  ppt: IconFileTypePpt,
+  pptx: IconFileTypePpt,
+  csv: IconFileTypeCsv,
+  txt: IconFileTypeTxt,
+  rtf: IconFileTypeTxt,
+  zip: IconFileTypeZip,
+  json: IconJson,
+  md: IconMarkdown,
+}
+
+const IMAGE_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'heic', 'heif', 'svg'])
+
+const extensionOf = (name: string) => {
+  const dot = name.lastIndexOf('.')
+  return dot >= 0 ? name.slice(dot + 1).toLowerCase() : ''
+}
+
+const isImage = (name: string, contentType?: string) => IMAGE_EXTENSIONS.has(extensionOf(name)) || (contentType?.startsWith('image/') ?? false)
+
+/** `'2.4 MB'`, `'812 KB'`, `'340 bytes'`. */
+const formatBytes = (bytes: number) => {
+  if (bytes < 1024) return `${bytes} bytes`
+  const kb = bytes / 1024
+  if (kb < 1024) return `${Math.round(kb)} KB`
+  return `${(kb / 1024).toFixed(1)} MB`
+}
+
+/** `'PDF'`, `'ZIP'`, `'DOCX'`, `'FILE'`. */
+const typeLabelOf = (name: string) => extensionOf(name).toUpperCase() || 'FILE'
+
+const TILE = 'size-9 rounded-md bg-bg-active flex items-center justify-center shrink-0 text-text-secondary'
+const NAME = 'text-[12px] font-medium leading-[1.3] text-text-primary truncate'
+const NOTE = 'text-[10px] leading-[1.2] truncate'
+
+function TypeIcon({ name }: { name: string }) {
+  const Icon = ICON_BY_EXTENSION[extensionOf(name)] ?? IconFile
+  return <Icon size={20} stroke={1.5} />
+}
+
+/**
+ * A line that truncates, with its full words on hover only when they are cut off — a name that fits, or a size,
+ * shows nothing extra (Katerina, 2026-09-14; Breadcrumb's rule, 2026-09-01). `hint`, when given, is always on hover:
+ * it says more than the line, not the same words again.
+ *
+ * Measured like Breadcrumb's crumbs: on mount, when the line resizes, and when the fonts arrive — a name set in
+ * the fallback face can fit and then not, in a line whose box never changes. The wrapper is `flex-col` so the
+ * text stretches across it, as wide as it is without one.
+ */
+function Truncating({ text, hint, className, wrapperClassName }: { text: string; hint?: string; className: string; wrapperClassName?: string }) {
+  const ref = useRef<HTMLSpanElement>(null)
+  const [cut, setCut] = useState(false)
+  useLayoutEffect(() => {
+    const el = ref.current
+    if (!el) return
+    let live = true
+    const measure = () => {
+      if (live) setCut(el.scrollWidth > el.clientWidth)
+    }
+    measure()
+    void document.fonts?.ready.then(measure)
+    // jsdom has neither layout nor ResizeObserver; without this guard an app cannot render a card in its tests.
+    if (typeof ResizeObserver === 'undefined') return () => void (live = false)
+    const observer = new ResizeObserver(measure)
+    observer.observe(el)
+    return () => {
+      live = false
+      observer.disconnect()
+    }
+    // `cut` re-runs it: wrapping the line mounts a new element, and that one is the one to watch.
+  }, [text, cut])
+  const line = (
+    <span ref={ref} className={className}>
+      {text}
+    </span>
+  )
+  if (!hint && !cut) return line
+  return (
+    <WithTooltip label={hint ?? text} wrapperClassName={cn('min-w-0 flex-col', wrapperClassName)}>
+      {line}
+    </WithTooltip>
+  )
+}
+
+export interface AttachmentCardProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+  /** The name it was attached under, extension included: it decides the icon and the type label. */
+  name: string
+  /** In bytes. */
+  size?: number
+  /** Its MIME type, where known: an `image/…` type is an image whatever its name. */
+  contentType?: string
+  /** Where a document opens, in a new tab. Without it the row is dimmed and opens nothing. */
+  href?: string
+  /** The picture an image card draws. Without it an image is drawn as a row. */
+  src?: string
+  /** What a click on an image's picture does — the app's full-screen view. */
+  onOpen?: () => void
+  /** Shows a download control on hover or focus, and calls this. */
+  onDownload?: () => void
+  /** Waiting to be sent: the composer's 200px row, with a remove control on its corner. */
+  pending?: boolean
+  /** Removes a pending card. */
+  onRemove?: () => void
+  /**
+   * `ready` · `loading` (an image on its way) · `unreadable` (it could not be read) ·
+   * `uploading`, `failed`, `warning` (while pending). Default `ready`.
+   */
+  state?: AttachmentCardState
+  /** The line under the name, in place of its type and size — why it failed, or what the warning is. */
+  note?: string
+  /** The note's full words, on hover, where the line is short. */
+  noteHint?: string
+}
+
+export function AttachmentCard({
+  name,
+  size,
+  contentType,
+  href,
+  src,
+  onOpen,
+  onDownload,
+  pending = false,
+  onRemove,
+  state = 'ready',
+  note,
+  noteHint,
+  className,
+  ...props
+}: AttachmentCardProps) {
+  const image = isImage(name, contentType)
+  const sizeText = size === undefined ? '' : formatBytes(size)
+
+  if (pending) {
+    const failed = state === 'failed'
+    const warning = state === 'warning'
+    return (
+      <Card
+        fill="elevated"
+        className={cn('group relative flex items-center gap-2 w-[200px] p-1.5 pr-3', failed ? 'border-error-default' : warning && 'border-warning-default', className)}
+        {...props}
+      >
+        <div className={cn(TILE, 'overflow-hidden')}>
+          {state === 'uploading' ? (
+            <IconLoader2 size={16} stroke={1.5} className="animate-spin" />
+          ) : failed ? (
+            <IconAlertCircle size={16} stroke={1.5} className="text-error-default" />
+          ) : warning ? (
+            <IconAlertTriangle size={16} stroke={1.5} className="text-warning-default" />
+          ) : image && src ? (
+            <img src={src} alt={name} className="size-full object-cover" />
+          ) : (
+            <span className="text-[9px] font-semibold">{typeLabelOf(name)}</span>
+          )}
+        </div>
+        <div className="flex flex-col gap-[1px] min-w-0">
+          <Truncating text={name} className={NAME} />
+          <Truncating
+            text={(failed || warning ? note : state === 'uploading' ? (note ?? 'Uploading…') : (note ?? sizeText)) ?? ''}
+            hint={noteHint}
+            className={cn(NOTE, failed ? 'text-error-default' : warning ? 'text-warning-default' : 'text-text-secondary')}
+          />
+        </div>
+        {/* On Base UI's Button, as InputChip's ✕ is (Katerina, 2026-09-14): IconButton is a 24px square
+            that fills on hover, and this is Peek's 20px round badge on the card's corner. */}
+        {onRemove && (
+          <BaseButton
+            type="button"
+            aria-label={`Remove ${name}`}
+            className="absolute -top-1.5 -right-1.5 size-5 rounded-full bg-bg-elevated border border-border-strong flex items-center justify-center text-text-secondary hover:text-text-primary opacity-0 group-hover:opacity-100 transition-opacity"
+            onClick={(event) => {
+              event.stopPropagation()
+              onRemove()
+            }}
+          >
+            <IconX size={11} stroke={1.75} />
+          </BaseButton>
+        )}
+      </Card>
+    )
+  }
+
+  // Fades in with the card's hover or keyboard focus, and keeps its slot when hidden, so revealing it never shifts the row.
+  const download = onDownload ? (
+    <IconButton
+      variant="muted"
+      tooltip="Download"
+      aria-label={`Download ${name}`}
+      className="opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 focus-visible:opacity-100 transition-opacity"
+      onClick={(event) => {
+        event.stopPropagation()
+        onDownload()
+      }}
+    >
+      <IconDownload size={16} stroke={1.5} />
+    </IconButton>
+  ) : null
+
+  if (state === 'loading') {
+    return (
+      // `role="status"`: a plain box may not carry a name (axe, aria-prohibited-attr), and a
+      // status says what it is doing — loading — to a reader that cannot see the pulse.
+      <Card role="status" fill="inset" aria-busy="true" aria-label={`Loading ${name}`} className={cn('w-[180px] h-28 animate-pulse', className)} {...props}>
+        {null}
+      </Card>
+    )
+  }
+
+  if (state === 'unreadable') {
+    return (
+      <Card fill="inset" unreadable className={cn('flex items-center gap-2 w-[240px] p-1.5 opacity-70', className)} {...props}>
+        <div className={TILE}>
+          <TypeIcon name={name} />
+        </div>
+        <div className="flex flex-col gap-[1px] min-w-0 text-left">
+          <Truncating text={name} className={NAME} />
+          <span className={cn(NOTE, 'text-text-secondary')}>{note ?? 'Could not be loaded'}</span>
+        </div>
+      </Card>
+    )
+  }
+
+  if (image && src) {
+    const picture = <img src={src} alt={name} className="w-full h-28 object-cover" />
+    return (
+      <Card fill="inset" hover="hairline" className={cn('group relative flex flex-col w-[180px] overflow-hidden', className)} {...props}>
+        {onOpen ? (
+          <BaseButton
+            type="button"
+            className="block w-full"
+            aria-label={`Preview ${name}`}
+            onClick={(event) => {
+              event.stopPropagation()
+              onOpen()
+            }}
+          >
+            {picture}
+          </BaseButton>
+        ) : (
+          <div className="block w-full">{picture}</div>
+        )}
+        <div className="flex items-center gap-1 pl-2 pr-1 py-1 min-w-0">
+          <Truncating text={name} className="flex-1 text-[12px] leading-[1.3] text-text-primary truncate" wrapperClassName="flex-1" />
+          {download}
+        </div>
+      </Card>
+    )
+  }
+
+  const body = (
+    <>
+      <div className={TILE}>
+        <TypeIcon name={name} />
+      </div>
+      <div className="flex flex-col gap-[1px] min-w-0 text-left">
+        <Truncating text={name} className={NAME} />
+        <span className={cn(NOTE, 'text-text-secondary')}>{note ?? `${typeLabelOf(name)} · ${sizeText}`}</span>
+      </div>
+    </>
+  )
+  return (
+    <Card fill="inset" hover={href ? 'hairline' : 'none'} className={cn('group flex items-center gap-2 w-[240px] p-1.5 pr-1', !href && 'opacity-70', className)} {...props}>
+      {href ? (
+        <Link href={href} external variant="plain" className="flex items-center gap-2 min-w-0 flex-1 cursor-pointer" onClick={(event) => event.stopPropagation()}>
+          {body}
+        </Link>
+      ) : (
+        <div className="flex items-center gap-2 min-w-0 flex-1">{body}</div>
+      )}
+      {download}
+    </Card>
+  )
+}