{
  "schemaVersion": 1,
  "target": "react",
  "name": "attachment",
  "version": "0.1.0",
  "category": "ai-elements",
  "title": "Attachment",
  "description": "File attachment chips and tiles with an image thumbnail or file type icon, name, size, upload progress, retry, and remove, for messages and composers.",
  "tags": [
    "ai",
    "chat",
    "attachment",
    "upload",
    "file",
    "composer",
    "base-ui"
  ],
  "requires": {
    "projectTypes": [
      "next",
      "vite-react"
    ],
    "styling": "tailwind-v4"
  },
  "npmDependencies": {
    "@base-ui/react": "^1.9.0"
  },
  "registryDependencies": [],
  "docsPath": "/components/attachment",
  "props": [
    {
      "name": "name / size / type / previewUrl",
      "type": "string / number / string / string",
      "description": "The file. type and the extension pick the icon; previewUrl shows an image thumbnail."
    },
    {
      "name": "status",
      "type": "\"uploading\" | \"ready\" | \"error\"",
      "default": "\"ready\"",
      "description": "Uploading shows a thin progress bar and percentage; error turns the border red and shows the reason."
    },
    {
      "name": "progress",
      "type": "number",
      "description": "0 to 100. Unset while uploading means indeterminate."
    },
    {
      "name": "error",
      "type": "string",
      "description": "Reason shown when the upload failed."
    },
    {
      "name": "onRemove / onRetry",
      "type": "() => void",
      "description": "Show the remove and retry buttons."
    },
    {
      "name": "variant",
      "type": "\"chip\" | \"tile\"",
      "default": "\"chip\"",
      "description": "A compact row for composers, or a square tile for grids."
    },
    {
      "name": "AttachmentList",
      "type": "({ layout: \"row\" | \"grid\" }) => JSX",
      "description": "Lays attachments out as wrapping chips or a tile grid, as a labelled list."
    }
  ],
  "accessibility": [
    "Upload progress uses Base UI Progress (role progressbar with aria-valuenow, labelled Uploading and the file name); it is indeterminate when progress is unknown.",
    "Remove and retry are buttons named with the file, such as Remove q3-retention.csv; on tiles they appear on hover and focus and are always visible on touch screens.",
    "Upload errors are announced as alerts and shown in text, not only by the red border. Thumbnails are decorative; the name is the label.",
    "New attachments scale in from 96% in 200ms and the progress bar moves with transform; both are instant with reduced motion."
  ],
  "states": [
    "ready",
    "uploading",
    "error",
    "image",
    "file"
  ],
  "files": [
    {
      "path": "agent/attachment.tsx",
      "content": "\"use client\";\n\nimport { Progress } from \"@base-ui/react/progress\";\nimport { Children, type ComponentProps, type ReactNode } from \"react\";\n\nfunction cx(...classes: (string | false | null | undefined)[]) {\n  return classes.filter(Boolean).join(\" \");\n}\n\nconst ease = \"ease-[cubic-bezier(0.23,1,0.32,1)]\";\n\nexport type AttachmentStatus = \"uploading\" | \"ready\" | \"error\";\nexport type AttachmentKind = \"image\" | \"pdf\" | \"document\" | \"spreadsheet\" | \"code\" | \"archive\" | \"audio\" | \"video\" | \"file\";\n\nexport interface AttachmentFile {\n  /** File name with its extension. */\n  name: string;\n  /** Size in bytes. */\n  size?: number;\n  /** MIME type. Used with the extension to pick the icon. */\n  type?: string;\n  /** Thumbnail URL for images, for example from `URL.createObjectURL`. */\n  previewUrl?: string;\n}\n\nexport interface AttachmentProps extends AttachmentFile, Omit<ComponentProps<\"div\">, \"children\"> {\n  status?: AttachmentStatus;\n  /** Upload progress from 0 to 100 while uploading. Leave unset for an indeterminate upload. */\n  progress?: number;\n  /** Shown instead of the size when the upload failed. */\n  error?: string;\n  /** Shows a remove button. */\n  onRemove?: () => void;\n  /** Shows a retry button when the upload failed. */\n  onRetry?: () => void;\n  /** chip is a compact row for composers and messages; tile is a square for grids. */\n  variant?: \"chip\" | \"tile\";\n}\n\nconst extensions: Record<string, AttachmentKind> = {\n  png: \"image\", jpg: \"image\", jpeg: \"image\", gif: \"image\", webp: \"image\", svg: \"image\", avif: \"image\", heic: \"image\",\n  pdf: \"pdf\",\n  doc: \"document\", docx: \"document\", md: \"document\", txt: \"document\", rtf: \"document\", pages: \"document\",\n  csv: \"spreadsheet\", xls: \"spreadsheet\", xlsx: \"spreadsheet\", numbers: \"spreadsheet\", tsv: \"spreadsheet\",\n  ts: \"code\", tsx: \"code\", js: \"code\", jsx: \"code\", json: \"code\", py: \"code\", go: \"code\", rs: \"code\", css: \"code\", html: \"code\", sql: \"code\", yml: \"code\", yaml: \"code\", sh: \"code\",\n  zip: \"archive\", gz: \"archive\", tar: \"archive\", rar: \"archive\", \"7z\": \"archive\",\n  mp3: \"audio\", wav: \"audio\", m4a: \"audio\", ogg: \"audio\", flac: \"audio\",\n  mp4: \"video\", mov: \"video\", webm: \"video\", mkv: \"video\",\n};\n\nfunction extensionOf(name: string): string {\n  const dot = name.lastIndexOf(\".\");\n  return dot > 0 ? name.slice(dot + 1).toLowerCase() : \"\";\n}\n\n/** Picks the icon family for a file from its MIME type, then its extension. */\nexport function attachmentKind(file: Pick<AttachmentFile, \"name\" | \"type\">): AttachmentKind {\n  const type = file.type ?? \"\";\n  if (type.startsWith(\"image/\")) return \"image\";\n  if (type.startsWith(\"audio/\")) return \"audio\";\n  if (type.startsWith(\"video/\")) return \"video\";\n  if (type === \"application/pdf\") return \"pdf\";\n  return extensions[extensionOf(file.name)] ?? \"file\";\n}\n\n/** Bytes as a short size, e.g. 2.4 MB. */\nexport function formatBytes(bytes: number): string {\n  if (bytes < 1024) return `${bytes} B`;\n  const units = [\"KB\", \"MB\", \"GB\"];\n  let value = bytes / 1024;\n  let unit = 0;\n  while (value >= 1024 && unit < units.length - 1) {\n    value /= 1024;\n    unit++;\n  }\n  return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;\n}\n\n/**\n * One attached file: an image thumbnail or a file type icon, the name, the size, and while\n * uploading a thin progress bar. A remove button sits on the chip, and a failed upload offers retry.\n */\nexport function Attachment({\n  name,\n  size,\n  type,\n  previewUrl,\n  status = \"ready\",\n  progress,\n  error,\n  onRemove,\n  onRetry,\n  variant = \"chip\",\n  className,\n  ...props\n}: AttachmentProps) {\n  const kind = attachmentKind({ name, type });\n  const extension = extensionOf(name).toUpperCase();\n  const uploading = status === \"uploading\";\n  const failed = status === \"error\";\n  const meta = failed\n    ? (error ?? \"Upload failed\")\n    : uploading\n      ? progress != null\n        ? `Uploading ${Math.round(progress)}%`\n        : \"Uploading\"\n      : [extension || null, size != null ? formatBytes(size) : null].filter(Boolean).join(\", \");\n\n  const thumb =\n    kind === \"image\" && previewUrl ? (\n      <img src={previewUrl} alt=\"\" className={cx(\"size-full object-cover\", uploading && \"opacity-60\")} />\n    ) : (\n      <FileIcon kind={kind} />\n    );\n\n  const actions = (\n    <>\n      {failed && onRetry ? <IconButton label={`Retry uploading ${name}`} onClick={onRetry} icon=\"retry\" tile={variant === \"tile\"} /> : null}\n      {onRemove ? <IconButton label={`Remove ${name}`} onClick={onRemove} icon=\"remove\" tile={variant === \"tile\"} /> : null}\n    </>\n  );\n\n  if (variant === \"tile\") {\n    return (\n      <div\n        data-status={status}\n        className={cx(\"group relative w-28 transition-[opacity,scale] duration-200 starting:scale-96 starting:opacity-0 motion-reduce:transition-none\", ease, className)}\n        {...props}\n      >\n        <div\n          className={cx(\n            \"relative flex aspect-square items-center justify-center overflow-hidden rounded-xl border bg-white text-zinc-500 dark:bg-black dark:text-zinc-400\",\n            \"transition-[border-color] duration-150 motion-reduce:transition-none\",\n            failed ? \"border-red-500/35\" : \"border-zinc-950/10 dark:border-white/10\",\n            kind !== \"image\" || !previewUrl ? \"[&>svg]:size-7\" : \"\",\n          )}\n        >\n          {thumb}\n          {kind !== \"image\" || !previewUrl ? (\n            <span className=\"absolute bottom-2 font-mono text-[10px] font-medium text-zinc-500\">{extension || \"FILE\"}</span>\n          ) : null}\n          {uploading ? <UploadBar progress={progress} name={name} className=\"absolute inset-x-2 bottom-2\" /> : null}\n          <div\n            className={cx(\n              \"absolute top-1.5 right-1.5 flex gap-1\",\n              \"transition-opacity duration-150 ease-out motion-reduce:transition-none\",\n              \"opacity-0 group-focus-within:opacity-100 group-hover:opacity-100 [@media(hover:none)]:opacity-100\",\n              failed && \"opacity-100\",\n            )}\n          >\n            {actions}\n          </div>\n        </div>\n        <p className=\"mt-1.5 truncate text-xs font-medium text-zinc-950 dark:text-white\" title={name}>\n          {name}\n        </p>\n        <p className={cx(\"truncate text-[11px] tabular-nums\", failed ? \"text-red-600 dark:text-red-400\" : \"text-zinc-500\")} role={failed ? \"alert\" : undefined}>\n          {meta}\n        </p>\n      </div>\n    );\n  }\n\n  return (\n    <div\n      data-status={status}\n      className={cx(\n        \"relative flex h-11 w-64 max-w-full items-center gap-2.5 overflow-hidden rounded-lg border bg-white py-1.5 pr-1.5 pl-1.5 text-left dark:bg-black\",\n        \"shadow-[0_1px_2px_rgb(0_0_0/0.04)] dark:shadow-none\",\n        `transition-[border-color,opacity,scale] duration-200 ${ease} starting:scale-96 starting:opacity-0 motion-reduce:transition-none`,\n        failed ? \"border-red-500/35\" : \"border-zinc-950/10 dark:border-white/12\",\n        className,\n      )}\n      {...props}\n    >\n      <span\n        className={cx(\n          \"flex size-8 shrink-0 items-center justify-center overflow-hidden rounded-md text-zinc-500 dark:text-zinc-400\",\n          \"shadow-[inset_0_0_0_1px_rgb(9_9_11/0.07)] dark:shadow-[inset_0_0_0_1px_rgb(255_255_255/0.1)]\",\n          \"[&>svg]:size-4\",\n        )}\n      >\n        {thumb}\n      </span>\n      <span className=\"min-w-0 flex-1\">\n        <span className=\"block truncate text-[13px] leading-4 font-medium text-zinc-950 dark:text-white\" title={name}>\n          {name}\n        </span>\n        <span\n          role={failed ? \"alert\" : undefined}\n          className={cx(\"mt-0.5 block truncate text-[11px] leading-4 tabular-nums\", failed ? \"text-red-600 dark:text-red-400\" : \"text-zinc-500\")}\n        >\n          {meta}\n        </span>\n      </span>\n      {onRemove || (failed && onRetry) ? <span className=\"flex shrink-0 items-center\">{actions}</span> : null}\n      {uploading ? <UploadBar progress={progress} name={name} className=\"absolute inset-x-0 bottom-0\" flush /> : null}\n    </div>\n  );\n}\n\nexport interface AttachmentListProps extends ComponentProps<\"ul\"> {\n  /** row wraps chips (composers, messages); grid lays out tiles. */\n  layout?: \"row\" | \"grid\";\n  children: ReactNode;\n}\n\n/** Lays out attachments as wrapping chips or a grid of tiles, as a labelled list. */\nexport function AttachmentList({ layout = \"row\", className, children, \"aria-label\": label = \"Attachments\", ...props }: AttachmentListProps) {\n  return (\n    <ul\n      aria-label={label}\n      className={cx(layout === \"grid\" ? \"grid grid-cols-[repeat(auto-fill,7rem)] gap-3\" : \"flex flex-wrap gap-2\", className)}\n      {...props}\n    >\n      {Children.map(children, (child) => (child == null || child === false ? null : <li>{child}</li>))}\n    </ul>\n  );\n}\n\n/** A thin progress bar. Indeterminate (a still, faint track) when progress is unknown. */\nfunction UploadBar({ progress, name, className, flush = false }: { progress?: number; name: string; className?: string; flush?: boolean }) {\n  return (\n    <Progress.Root value={progress ?? null} aria-label={`Uploading ${name}`} className={className}>\n      <Progress.Track className={cx(\"h-0.5 overflow-hidden bg-zinc-950/[0.08] dark:bg-white/[0.12]\", !flush && \"rounded-full\")}>\n        <span\n          className={cx(\n            \"block h-full origin-left bg-sky-500 transition-transform duration-300 ease-out motion-reduce:transition-none\",\n            progress == null && \"opacity-40\",\n          )}\n          style={{ transform: `scaleX(${progress == null ? 1 : Math.max(0, Math.min(100, progress)) / 100})` }}\n        />\n      </Progress.Track>\n    </Progress.Root>\n  );\n}\n\nfunction IconButton({ label, onClick, icon, tile }: { label: string; onClick: () => void; icon: \"remove\" | \"retry\"; tile: boolean }) {\n  return (\n    <button\n      type=\"button\"\n      aria-label={label}\n      onClick={onClick}\n      className={cx(\n        \"inline-flex size-7 cursor-pointer items-center justify-center rounded-md text-zinc-500\",\n        \"transition-[background-color,color,scale] duration-150 ease-out active:duration-100 motion-safe:active:scale-[0.97] motion-reduce:transition-none\",\n        \"focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500\",\n        tile\n          ? \"size-6 rounded-full border border-zinc-950/10 bg-white text-zinc-600 shadow-[0_1px_2px_rgb(0_0_0/0.08)] hover:text-zinc-950 dark:border-white/15 dark:bg-black dark:text-zinc-300 dark:hover:text-white\"\n          : \"hover:bg-zinc-950/[0.04] hover:text-zinc-950 dark:hover:bg-white/[0.06] dark:hover:text-white\",\n      )}\n    >\n      <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\" fill=\"none\" stroke=\"currentColor\" strokeWidth=\"1.5\" strokeLinecap=\"round\" strokeLinejoin=\"round\" className={tile ? \"size-3\" : \"size-3.5\"}>\n        {icon === \"remove\" ? <path d=\"m4.5 4.5 7 7m0-7-7 7\" /> : <path d=\"M12.5 8a4.5 4.5 0 1 1-1.32-3.18M12.5 2.75v2.5H10\" />}\n      </svg>\n    </button>\n  );\n}\n\n/** Stroke file icons, one per kind, at 16px in a 16 unit box. */\nexport function FileIcon({ kind, className }: { kind: AttachmentKind; className?: string }) {\n  return (\n    <svg\n      aria-hidden=\"true\"\n      viewBox=\"0 0 16 16\"\n      fill=\"none\"\n      stroke=\"currentColor\"\n      strokeWidth=\"1.25\"\n      strokeLinecap=\"round\"\n      strokeLinejoin=\"round\"\n      data-kind={kind}\n      className={cx(\"size-4 shrink-0\", className)}\n    >\n      {kind === \"image\" ? (\n        <>\n          <rect x=\"2\" y=\"2.5\" width=\"12\" height=\"11\" rx=\"1.75\" />\n          <circle cx=\"6\" cy=\"6.25\" r=\"1.1\" />\n          <path d=\"m2.5 12 3.6-3.6a1 1 0 0 1 1.4 0L13.5 14\" />\n        </>\n      ) : kind === \"audio\" ? (\n        <path d=\"M6 12.25V3.5l7-1.25v8.5M6 12.25a1.75 1.75 0 1 1-3.5 0 1.75 1.75 0 0 1 3.5 0Zm7-1.5a1.75 1.75 0 1 1-3.5 0 1.75 1.75 0 0 1 3.5 0Z\" />\n      ) : kind === \"video\" ? (\n        <>\n          <rect x=\"1.75\" y=\"3.5\" width=\"9\" height=\"9\" rx=\"1.75\" />\n          <path d=\"m10.75 7 3.5-2v6l-3.5-2\" />\n        </>\n      ) : kind === \"archive\" ? (\n        <>\n          <path d=\"M3.5 1.75h9v12.5h-9z\" />\n          <path d=\"M8 1.75v1.5m0 1.5v1.5m0 1.5v1.5\" />\n          <rect x=\"6.75\" y=\"9.75\" width=\"2.5\" height=\"2.25\" rx=\".5\" />\n        </>\n      ) : (\n        <>\n          <path d=\"M4 1.75h5l3 3v9.5H4V1.75Z\" />\n          <path d=\"M9 1.75v3h3\" />\n          {kind === \"pdf\" || kind === \"document\" ? <path d=\"M6.25 8.25h3.5M6.25 10.75h3.5\" /> : null}\n          {kind === \"spreadsheet\" ? <path d=\"M6 8h4v4H6zM8 8v4M6 10h4\" /> : null}\n          {kind === \"code\" ? <path d=\"m6.75 8.25-1.25 1.5 1.25 1.5m2.5-3 1.25 1.5-1.25 1.5\" /> : null}\n        </>\n      )}\n    </svg>\n  );\n}\n"
    }
  ],
  "example": {
    "content": "\"use client\";\n\nimport { useState } from \"react\";\nimport { Attachment, AttachmentList } from \"@/components/shaken/agent/attachment\";\n\n// A small inline screenshot so the example has a real thumbnail without network requests.\nconst screenshot = `data:image/svg+xml,${encodeURIComponent(\n  `<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 160 160\"><rect width=\"160\" height=\"160\" fill=\"#f4f4f5\"/><rect x=\"12\" y=\"14\" width=\"56\" height=\"8\" rx=\"4\" fill=\"#18181b\"/><rect x=\"12\" y=\"34\" width=\"136\" height=\"54\" rx=\"6\" fill=\"#fff\" stroke=\"#e4e4e7\"/><path d=\"M22 76l18-14 16 8 20-20 18 12 16-10 22 16\" fill=\"none\" stroke=\"#0ea5e9\" stroke-width=\"3\" stroke-linecap=\"round\" stroke-linejoin=\"round\"/><rect x=\"12\" y=\"98\" width=\"64\" height=\"48\" rx=\"6\" fill=\"#fff\" stroke=\"#e4e4e7\"/><rect x=\"84\" y=\"98\" width=\"64\" height=\"48\" rx=\"6\" fill=\"#fff\" stroke=\"#e4e4e7\"/><rect x=\"22\" y=\"110\" width=\"28\" height=\"6\" rx=\"3\" fill=\"#a1a1aa\"/><rect x=\"22\" y=\"124\" width=\"40\" height=\"10\" rx=\"3\" fill=\"#18181b\"/><rect x=\"94\" y=\"110\" width=\"28\" height=\"6\" rx=\"3\" fill=\"#a1a1aa\"/><rect x=\"94\" y=\"124\" width=\"36\" height=\"10\" rx=\"3\" fill=\"#10b981\"/></svg>`,\n)}`;\n\nconst initial = [\n  { id: \"1\", name: \"churn-dashboard.png\", type: \"image/png\", size: 482_113, previewUrl: screenshot },\n  { id: \"2\", name: \"q3-retention.csv\", type: \"text/csv\", size: 1_920_448 },\n  { id: \"3\", name: \"pricing-experiment.pdf\", type: \"application/pdf\", size: 3_404_002, status: \"uploading\" as const, progress: 64 },\n  { id: \"4\", name: \"cohorts.sql\", size: 7_210, status: \"error\" as const, error: \"Over the 5 MB limit\" },\n];\n\nexport default function AttachmentExample() {\n  const [files, setFiles] = useState(initial);\n  const remove = (id: string) => setFiles((current) => current.filter((file) => file.id !== id));\n\n  return (\n    <div className=\"grid w-full max-w-xl gap-8\">\n      <div className=\"grid gap-2\">\n        <p className=\"text-xs font-medium text-zinc-500\">In the composer</p>\n        <AttachmentList>\n          {files.map(({ id, ...file }) => (\n            <Attachment key={id} {...file} onRemove={() => remove(id)} onRetry={file.status === \"error\" ? () => remove(id) : undefined} />\n          ))}\n        </AttachmentList>\n        {files.length < initial.length ? (\n          <button\n            type=\"button\"\n            onClick={() => setFiles(initial)}\n            className=\"justify-self-start rounded-md text-xs text-zinc-500 underline-offset-2 hover:text-zinc-950 hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-sky-500 dark:hover:text-white\"\n          >\n            Restore attachments\n          </button>\n        ) : null}\n      </div>\n      <div className=\"grid gap-2\">\n        <p className=\"text-xs font-medium text-zinc-500\">In a sent message</p>\n        <AttachmentList layout=\"grid\">\n          <Attachment variant=\"tile\" name=\"churn-dashboard.png\" type=\"image/png\" size={482_113} previewUrl={screenshot} />\n          <Attachment variant=\"tile\" name=\"q3-retention.csv\" type=\"text/csv\" size={1_920_448} />\n          <Attachment variant=\"tile\" name=\"pricing-experiment.pdf\" type=\"application/pdf\" size={3_404_002} />\n          <Attachment variant=\"tile\" name=\"cohorts.sql\" size={7_210} />\n        </AttachmentList>\n      </div>\n    </div>\n  );\n}\n"
  }
}
