{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "attachment", "type": "registry:ui", "title": "Attachment", "description": "File and image attachment chips with thumbnails, upload progress rings, error/retry, remove, a “+N” overflow stack and a dropzone.", "dependencies": [ "lucide-react", "motion" ], "registryDependencies": [ "https://kuro.abstergo.fyi/r/kura-theme.json", "https://kuro.abstergo.fyi/r/kura-motion.json", "https://kuro.abstergo.fyi/r/use-reduced-motion.json", "utils" ], "files": [ { "path": "registry/kura/attachment/attachment-utils.ts", "type": "registry:ui", "target": "components/kura/attachment/attachment-utils.ts", "content": "/** Upload lifecycle of one attachment. */\nexport type AttachmentStatus = \"ready\" | \"uploading\" | \"error\";\n\n/** Broad file family, used to pick an icon and a label. */\nexport type AttachmentKind =\n | \"image\"\n | \"pdf\"\n | \"code\"\n | \"text\"\n | \"sheet\"\n | \"audio\"\n | \"video\"\n | \"archive\"\n | \"file\";\n\n/** Plain-data description of an attachment, as stored in app or composer state. */\nexport interface AttachmentItem {\n /** Stable id, unique within the list. */\n id: string;\n /** File name shown on the chip, e.g. \"q3-report.pdf\". */\n name: string;\n /** Size in bytes. */\n size?: number;\n /** MIME type, e.g. \"image/png\". Used for the icon and the thumbnail decision. */\n type?: string;\n /** Preview URL (object URL or remote) for images. */\n url?: string;\n /** Default \"ready\". */\n status?: AttachmentStatus;\n /** Upload progress 0..1 while `status` is \"uploading\". Omit for indeterminate. */\n progress?: number;\n /** Error message shown when `status` is \"error\". */\n error?: string;\n /** The original File, when the attachment came from a picker, paste or drop. */\n file?: File;\n}\n\nconst CODE_EXT =\n /\\.(m?[jt]sx?|py|rb|go|rs|java|kt|swift|c|cc|cpp|h|hpp|cs|php|sh|zsh|sql|html?|css|scss|vue|svelte|json|ya?ml|toml|xml)$/i;\n\n/** Classify a file by MIME type, falling back to its extension. */\nexport function attachmentKind(name: string, type = \"\"): AttachmentKind {\n const t = type.toLowerCase();\n const n = name.toLowerCase();\n if (t.startsWith(\"image/\") || /\\.(png|jpe?g|gif|webp|avif|svg|heic)$/.test(n)) return \"image\";\n if (t === \"application/pdf\" || n.endsWith(\".pdf\")) return \"pdf\";\n if (t.startsWith(\"audio/\") || /\\.(mp3|wav|m4a|ogg|flac|webm)$/.test(n)) return \"audio\";\n if (t.startsWith(\"video/\") || /\\.(mp4|mov|mkv|avi)$/.test(n)) return \"video\";\n if (/zip|tar|gzip|rar|7z/.test(t) || /\\.(zip|tar|gz|tgz|rar|7z)$/.test(n)) return \"archive\";\n if (/spreadsheet|excel|csv/.test(t) || /\\.(csv|tsv|xlsx?|numbers)$/.test(n)) return \"sheet\";\n if (CODE_EXT.test(n)) return \"code\";\n if (t.startsWith(\"text/\") || /\\.(md|mdx|txt|rtf|docx?)$/.test(n)) return \"text\";\n return \"file\";\n}\n\n/** Short uppercase extension (\"PDF\", \"TSX\") or the kind when there is none. */\nexport function attachmentExtension(name: string): string {\n const match = /\\.([a-z0-9]{1,5})$/i.exec(name);\n return match?.[1] ? match[1].toUpperCase() : \"\";\n}\n\n/** 1536 → \"1.5 KB\". Uses binary units and at most one decimal, like Finder. */\nexport function formatBytes(bytes: number): string {\n if (!Number.isFinite(bytes) || bytes < 0) return \"\";\n if (bytes < 1024) return `${bytes} B`;\n const units = [\"KB\", \"MB\", \"GB\", \"TB\"];\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 ? Math.round(value) : Math.round(value * 10) / 10} ${units[unit]}`;\n}\n\n/**\n * Does `file` match an `accept` string like \"image/*,.pdf,text/csv\"? An empty or missing accept\n * string accepts everything (same semantics as ``).\n */\nexport function acceptsFile(file: Pick, accept?: string): boolean {\n if (!accept) return true;\n const name = file.name.toLowerCase();\n const type = (file.type || \"\").toLowerCase();\n return accept\n .split(\",\")\n .map((s) => s.trim().toLowerCase())\n .filter(Boolean)\n .some((rule) => {\n if (rule.startsWith(\".\")) return name.endsWith(rule);\n if (rule.endsWith(\"/*\")) return type.startsWith(rule.slice(0, -1));\n return type === rule;\n });\n}\n\nlet counter = 0;\n\n/**\n * Turn a File into an AttachmentItem. Images get an object URL preview — call\n * `URL.revokeObjectURL(item.url)` when you discard the item.\n */\nexport function createAttachment(\n file: File,\n overrides: Partial = {},\n): AttachmentItem {\n counter += 1;\n const isImage = attachmentKind(file.name, file.type) === \"image\";\n const url =\n isImage && typeof URL !== \"undefined\" && typeof URL.createObjectURL === \"function\"\n ? URL.createObjectURL(file)\n : undefined;\n return {\n id: `att-${Date.now().toString(36)}-${counter}`,\n name: file.name,\n size: file.size,\n type: file.type,\n url,\n status: \"ready\",\n file,\n ...overrides,\n };\n}\n\n/** Files from a DataTransfer (drop or paste). Ignores non-file items such as dragged text. */\nexport function filesFromDataTransfer(data: DataTransfer | null): File[] {\n if (!data) return [];\n if (data.files && data.files.length > 0) return Array.from(data.files);\n const out: File[] = [];\n for (const item of Array.from(data.items ?? [])) {\n if (item.kind === \"file\") {\n const f = item.getAsFile();\n if (f) out.push(f);\n }\n }\n return out;\n}\n\n/** True when a drag carries files (not text or links). Safe to call during dragenter/dragover. */\nexport function dragHasFiles(data: DataTransfer | null): boolean {\n if (!data) return false;\n return Array.from(data.types ?? []).includes(\"Files\");\n}\n" }, { "path": "registry/kura/attachment/attachment.tsx", "type": "registry:ui", "target": "components/kura/attachment/attachment.tsx", "content": "\"use client\";\n\nimport {\n CircleAlert,\n CloudUpload,\n FileArchive,\n FileAudio,\n FileCode,\n File as FileIcon,\n FileImage,\n FileSpreadsheet,\n FileText,\n FileVideo,\n X,\n} from \"lucide-react\";\nimport { AnimatePresence, motion } from \"motion/react\";\nimport * as React from \"react\";\nimport { useReducedMotion } from \"@/hooks/kura/use-reduced-motion\";\nimport { cn } from \"@/lib/utils\";\nimport { springs } from \"@/lib/kura/motion\";\nimport {\n type AttachmentItem,\n type AttachmentKind,\n type AttachmentStatus,\n acceptsFile,\n attachmentExtension,\n attachmentKind,\n dragHasFiles,\n filesFromDataTransfer,\n formatBytes,\n} from \"./attachment-utils\";\n\nconst KIND_ICON: Record> = {\n image: FileImage,\n pdf: FileText,\n code: FileCode,\n text: FileText,\n sheet: FileSpreadsheet,\n audio: FileAudio,\n video: FileVideo,\n archive: FileArchive,\n file: FileIcon,\n};\n\n// ---------------------------------------------------------------------------------------------\n// Progress ring\n// ---------------------------------------------------------------------------------------------\n\nexport interface AttachmentProgressRingProps extends Omit, \"children\"> {\n /** 0..1. Omit for an indeterminate spinning arc. */\n progress?: number;\n /** Stroke width in px. Default 2. */\n thickness?: number;\n}\n\n/** Circular upload progress. Inherits `currentColor`; the track is the same color at 20%. */\nexport function AttachmentProgressRing({\n progress,\n thickness = 2,\n className,\n ...props\n}: AttachmentProgressRingProps) {\n const determinate = typeof progress === \"number\" && Number.isFinite(progress);\n const value = determinate ? Math.min(1, Math.max(0, progress)) : 0.28;\n const r = 12 - thickness / 2;\n return (\n \n \n \n \n );\n}\n\n// ---------------------------------------------------------------------------------------------\n// Attachment chip / tile\n// ---------------------------------------------------------------------------------------------\n\nexport interface AttachmentProps extends Omit, \"children\"> {\n /** File name, e.g. \"q3-report.pdf\". Truncated in the middle of long names via CSS ellipsis. */\n name: string;\n /** Size in bytes; shown as \"2.4 MB\". */\n size?: number;\n /** MIME type. Picks the file-type icon and decides whether `previewUrl` renders as a thumbnail. */\n type?: string;\n /** Image preview URL. With an image type (or `variant=\"tile\"`) the chip renders as a thumbnail. */\n previewUrl?: string;\n /** Upload state. Default \"ready\". */\n status?: AttachmentStatus;\n /** Upload progress 0..1 while uploading. Omit for an indeterminate ring. */\n progress?: number;\n /** Error message for `status=\"error\"`. Shown in the tooltip and to screen readers. */\n error?: string;\n /** `auto` = thumbnail tile for images with a preview, chip otherwise. Default \"auto\". */\n variant?: \"auto\" | \"chip\" | \"tile\";\n /** Show a remove (×) button and call this when pressed. */\n onRemove?: () => void;\n /** Show a \"Retry\" action while `status=\"error\"`. */\n onRetry?: () => void;\n}\n\n/**\n * One attached file: a chip with a file-type icon, name and size, or a square thumbnail for\n * images. Shows upload progress as a ring, errors with a retry action, and a remove button.\n */\nexport function Attachment({\n name,\n size,\n type,\n previewUrl,\n status = \"ready\",\n progress,\n error,\n variant = \"auto\",\n onRemove,\n onRetry,\n className,\n title,\n ...props\n}: AttachmentProps) {\n const kind = attachmentKind(name, type);\n const tile = variant === \"tile\" || (variant === \"auto\" && kind === \"image\" && !!previewUrl);\n const Icon = KIND_ICON[kind];\n const ext = attachmentExtension(name);\n const sizeLabel = typeof size === \"number\" ? formatBytes(size) : \"\";\n const pct =\n typeof progress === \"number\" ? Math.round(Math.min(1, Math.max(0, progress)) * 100) : null;\n\n let meta: React.ReactNode;\n if (status === \"uploading\") meta = pct === null ? \"Uploading…\" : `Uploading · ${pct}%`;\n else if (status === \"error\") meta = error ? \"Failed\" : \"Upload failed\";\n else meta = [ext, sizeLabel].filter(Boolean).join(\" · \") || \"File\";\n\n const description = `${name}${status === \"uploading\" ? `, uploading${pct !== null ? ` ${pct}%` : \"\"}` : \"\"}${\n status === \"error\" ? `, upload failed${error ? `: ${error}` : \"\"}` : \"\"\n }`;\n\n const removeButton = onRemove && (\n \n \n \n );\n\n if (tile) {\n return (\n \n \n {previewUrl ? (\n \n ) : (\n \n \n {name}\n \n )}\n {/* inner hairline so light images keep an edge */}\n \n {status === \"uploading\" && (\n \n \n \n )}\n {status === \"error\" && (\n \n {onRetry ? (\n \n \n \n ) : (\n \n )}\n \n )}\n \n \n {status !== \"ready\" ? description : \"\"}\n \n {removeButton}\n \n );\n }\n\n return (\n \n \n {status === \"uploading\" ? (\n <>\n \n \n \n ) : status === \"error\" ? (\n \n ) : (\n \n )}\n \n \n \n {name}\n \n \n {meta}\n \n {status === \"error\" ? `Upload failed${error ? `: ${error}` : \"\"}` : \"\"}\n \n {status === \"error\" && onRetry && (\n <>\n ·\n \n Retry\n \n \n )}\n \n \n {removeButton}\n \n );\n}\n\n// ---------------------------------------------------------------------------------------------\n// List with \"+N\" overflow stack\n// ---------------------------------------------------------------------------------------------\n\nexport interface AttachmentListProps extends Omit, \"children\"> {\n /** The attachments to render, in order. */\n items: readonly AttachmentItem[];\n /** Show a remove button on each item. */\n onRemove?: (id: string) => void;\n /** Show \"Retry\" on items whose status is \"error\". */\n onRetry?: (id: string) => void;\n /** Show at most this many, then a \"+N\" stack. Clicking the stack reveals the rest. */\n max?: number;\n /** Forwarded to every Attachment. Default \"auto\". */\n variant?: \"auto\" | \"chip\" | \"tile\";\n /** Accessible name of the list. Default \"Attachments\". */\n label?: string;\n}\n\n/**\n * A wrapping row of attachments. Items pop in, and the row closes the gap smoothly when one is\n * removed. Overflow beyond `max` collapses into a \"+N\" stack.\n */\nexport function AttachmentList({\n items,\n onRemove,\n onRetry,\n max,\n variant = \"auto\",\n label = \"Attachments\",\n className,\n ...props\n}: AttachmentListProps) {\n const reduced = useReducedMotion();\n const [expanded, setExpanded] = React.useState(false);\n const limit = !expanded && typeof max === \"number\" && items.length > max ? max : items.length;\n const visible = items.slice(0, limit);\n const hidden = items.length - limit;\n\n const motionProps = reduced\n ? {\n initial: { opacity: 0 },\n animate: { opacity: 1 },\n exit: { opacity: 0, transition: { duration: 0.09 } },\n transition: { duration: 0.15 },\n }\n : {\n layout: \"position\" as const,\n initial: { opacity: 0, scale: 0.92, filter: \"blur(2px)\" },\n animate: { opacity: 1, scale: 1, filter: \"blur(0px)\" },\n exit: { opacity: 0, scale: 0.92, filter: \"blur(2px)\", transition: { duration: 0.12 } },\n transition: springs.snappy,\n };\n\n return (\n \n \n {visible.map((item) => (\n \n onRemove(item.id) : undefined}\n onRetry={onRetry ? () => onRetry(item.id) : undefined}\n />\n \n ))}\n {hidden > 0 && (\n \n setExpanded(true)}\n aria-label={`Show ${hidden} more ${hidden === 1 ? \"attachment\" : \"attachments\"}`}\n title={items\n .slice(limit)\n .map((i) => i.name)\n .join(\"\\n\")}\n className={cn(\n \"group/overflow relative isolate mr-2.5 flex h-11 min-w-11 cursor-pointer items-center justify-center rounded-kura-lg px-2.5 font-kura-sans font-medium text-[13px] text-kura-fg-muted tabular-nums outline-none\",\n \"transition-[color,transform] duration-(--kura-duration-fast) ease-kura-out hover:text-kura-fg focus-visible:shadow-kura-focus active:scale-[0.97] motion-reduce:active:scale-100\",\n )}\n >\n {/* the \"deck\": two cards peeking out behind the counter's face */}\n \n \n \n +{hidden}\n \n \n )}\n \n \n );\n}\n\n// ---------------------------------------------------------------------------------------------\n// Dropzone\n// ---------------------------------------------------------------------------------------------\n\nexport interface AttachmentDropzoneProps\n extends Omit, \"title\" | \"onDrop\"> {\n /** Called with accepted files, and the files rejected by `accept` / `maxSize`. */\n onFiles: (files: File[], rejected: File[]) => void;\n /** Same syntax as ``, e.g. \"image/*,.pdf\". */\n accept?: string;\n /** Allow several files. Default true. */\n multiple?: boolean;\n /** Reject files larger than this many bytes. */\n maxSize?: number;\n disabled?: boolean;\n /** Headline. Default \"Drop files or browse\". */\n title?: React.ReactNode;\n /** Hint under the headline, e.g. \"PNG, PDF or CSV up to 10 MB\". */\n description?: React.ReactNode;\n}\n\n/**\n * A drop target and file picker in one: click or press Enter to browse, or drop files onto it.\n * Highlights only when a drag actually carries files.\n */\nexport function AttachmentDropzone({\n onFiles,\n accept,\n multiple = true,\n maxSize,\n disabled = false,\n title = \"Drop files or browse\",\n description,\n className,\n ...props\n}: AttachmentDropzoneProps) {\n const inputRef = React.useRef(null);\n const depth = React.useRef(0);\n const [dragging, setDragging] = React.useState(false);\n const descId = React.useId();\n\n const deliver = (list: File[]) => {\n const files = multiple ? list : list.slice(0, 1);\n const ok: File[] = [];\n const bad: File[] = [];\n for (const f of files) {\n if (acceptsFile(f, accept) && (maxSize === undefined || f.size <= maxSize)) ok.push(f);\n else bad.push(f);\n }\n if (ok.length || bad.length) onFiles(ok, bad);\n };\n\n return (\n // biome-ignore lint/a11y/noStaticElementInteractions: drag events only; the inner \n {\n deliver(Array.from(e.currentTarget.files ?? []));\n e.currentTarget.value = \"\";\n }}\n />\n \n );\n}\n" }, { "path": "registry/kura/attachment/index.ts", "type": "registry:ui", "target": "components/kura/attachment/index.ts", "content": "export {\n Attachment,\n AttachmentDropzone,\n type AttachmentDropzoneProps,\n AttachmentList,\n type AttachmentListProps,\n AttachmentProgressRing,\n type AttachmentProgressRingProps,\n type AttachmentProps,\n} from \"./attachment\";\nexport {\n type AttachmentItem,\n type AttachmentKind,\n type AttachmentStatus,\n acceptsFile,\n attachmentExtension,\n attachmentKind,\n createAttachment,\n dragHasFiles,\n filesFromDataTransfer,\n formatBytes,\n} from \"./attachment-utils\";\n" } ], "categories": [ "input", "file", "upload", "attachment", "image" ], "docs": "Docs: https://kuro.abstergo.fyi/components/attachment · Markdown for agents: https://kuro.abstergo.fyi/components/attachment.md", "meta": { "kura": { "status": "beta", "whenToUse": [ "Show files the user attached to a prompt before sending (inside or above a composer).", "Display upload progress, failures and a retry action for files sent to a model.", "Render the files that belong to a sent message or an agent artifact list.", "A standalone drop area for documents to index, e.g. “Add files to this project”." ], "whenNotToUse": [ "A complete prompt input with paste and drag-drop built in — use composer (it renders attachment for you).", "Rich previews of generated documents or code — use artifact-card or code-block.", "Audio recordings with playback — use audio-waveform with `peaks`." ] } } }