@orbit-work/ui 0.1.0

package/src/components/domain/chat/Attachment/index.tsx

@@ -0,0 +1,857 @@
+"use client"
+
+import { type ReactNode, useCallback, useEffect, useMemo, useRef, useState } from "react"
+import { cn } from "../../../../lib/utils"
+import { Icon, type IconName } from "../../../composite/Icons"
+import { Button } from "../../../primitives/Button"
+import { EmptyState } from "../../../primitives/EmptyState"
+import { Menu, type MenuEntry } from "../../../primitives/Menu"
+import { ProgressBar } from "../../../primitives/ProgressBar"
+import { FileIcon, resolveFileIcon } from "../../files/FileIcon"
+
+/**
+ * Attachment — 聊天附件（DS 2.0 聊天域 · 蓝图批次③「Attachment（合并 AttachmentCard /
+ * Attachments / FileReferenceCard(+s) / ImageCard）」）。
+ *
+ * 四个形态，一套状态：
+ * - `card` 横卡：FileIcon 单色字形 ＋ 文件名 ＋ meta mono 读数 ＋ 操作 Menu（旧 FileReferenceCard）；
+ * - `tile` 方片 112×112：Composer 附件条里的非图附件（旧 AttachmentCard 无缩略档）；
+ * - `image` 图片方片 112×112：缩略图 ＋ scrim 遮罩操作（旧 AttachmentCard 缩略档）；
+ * - `media` 富媒体图卡：最大 420 宽 ＋ 可选说明行（旧 ImageCard）。
+ * 行集走同目录 `AttachmentList`（strip 横排＝旧 Attachments，stack 竖列＝旧 FileReferenceCards）。
+ *
+ * 立面 §5：卡是贴地之物 —— 1px `--ow-border` ＋ 0 影，hover 走所在表面的 `--ow-hover`→`--ow-press`
+ * （不是 pop 档，卡不是弹层）；只有操作 Menu 那一层是离地之物，立面由 `Menu` 原语承担。
+ *
+ * 状态 §6：default / hover / press / focus-visible（`ow-focus-ring` 2px 环）/ disabled 逐 token /
+ * 上传中（`ProgressBar` ＋ mono 读数）/ 失败（error tint ＋「重试」，R1 双编码：色之外还有文字与按钮）/ 完成。
+ *
+ * 度量 §7：圆角 12（`--ow-radius-card`）；文件名 sans、meta 读数一律 mono ＋ tabular-nums；
+ * 文件类型图标＝单色字形 ＋ 扩展名 mono 标签（`FileIcon`），禁多彩类型底。
+ *
+ * R3 中性件：聊天里的附件没有叙事位置 —— 不带信标点、不引荧黄，品牌感只来自字体、灰阶、间距。
+ * 上传进度用 `--ow-progress-fill`（墨/月白）而不是荧黄（§4「其余角色永不荧黄」）。
+ */
+
+/* ------------------------------------------------------------------ *
+ * 数据模型
+ * ------------------------------------------------------------------ */
+
+/** 文件语义分类。旧 `FileReferenceTone` 的规范名。 */
+export type AttachmentTone =
+  | "file"
+  | "markdown"
+  | "presentation"
+  | "document"
+  | "spreadsheet"
+  | "image"
+  | "video"
+  | "pdf"
+  | "web"
+  | "code"
+
+/** 一条文件引用。旧 `FileReferenceItem` 的规范名，字段逐一保留。 */
+export type AttachmentItem = {
+  id?: string
+  name: string
+  path: string
+  /** 扩展名标签覆盖（默认从 path/name 推断），透传给 FileIcon 的右下角标签。 */
+  badge?: string
+  /** 类型文案覆盖（业务文案，如来源/价格）。 */
+  typeLabel?: string
+}
+/* R2：`tone`（V1 的多彩文件类别）从本类型摘除——DS 2.0 §7「文件类型图标＝单色字形 ＋
+   扩展名 mono 标签，禁多彩类型底」，全库没有也不会有消费方，留着是个渲不出来的承诺。
+   语义分类本身还在 `AttachmentMeta.tone`（inferAttachmentMeta 的返回），宿主要分类判断
+   直接读那里。 */
+
+/** 操作菜单里的一个应用/动作。旧 `FileReferenceOpenWithOption` 的规范名。 */
+export type AttachmentOpenOption = {
+  id: string
+  name: string
+  path?: string
+  isDefault?: boolean
+  kind?: "app" | "action"
+  icon?: string
+  iconName?: IconName
+  iconUrl?: string
+  disabled?: boolean
+}
+
+/** 操作菜单条目（含分隔线与分组标题）。旧 `FileReferenceMenuOption` 的规范名。 */
+export type AttachmentMenuOption =
+  | AttachmentOpenOption
+  | { id: string; kind: "divider"; name?: string }
+  | { id: string; kind: "header"; name: string }
+
+/** 上传生命周期。 */
+export type AttachmentStatus = "uploading" | "error" | "done"
+
+export type AttachmentVariant = "card" | "tile" | "image" | "media"
+
+type AttachmentMeta = {
+  badge: string
+  label: string
+  tone: AttachmentTone
+}
+
+/* ------------------------------------------------------------------ *
+ * 类型推断
+ * ------------------------------------------------------------------ */
+
+/** 从路径或文件名推断扩展名标签、类型文案与 tone。旧 `inferFileReferenceMeta` 的规范名。 */
+export function inferAttachmentMeta(pathOrName: string): AttachmentMeta {
+  const ext = (pathOrName.match(/\.([A-Za-z0-9]+)(?::\d+)?$/)?.[1] ?? "").toLowerCase()
+  if (ext === "md" || ext === "markdown") return { badge: "MD", label: "Markdown", tone: "markdown" }
+  if (["ppt", "pptx"].includes(ext)) return { badge: "P", label: "演示文稿", tone: "presentation" }
+  if (["doc", "docx"].includes(ext)) return { badge: "W", label: "文档", tone: "document" }
+  if (["xls", "xlsx", "csv"].includes(ext)) return { badge: "X", label: "表格", tone: "spreadsheet" }
+  if (["png", "jpg", "jpeg", "gif", "webp", "bmp", "svg", "heic", "heif", "tif", "tiff"].includes(ext))
+    return { badge: "IMG", label: "图片", tone: "image" }
+  if (["mp4", "mov", "webm", "avi", "mkv"].includes(ext)) return { badge: "VID", label: "视频", tone: "video" }
+  if (ext === "pdf") return { badge: "PDF", label: "PDF", tone: "pdf" }
+  if (ext === "html" || ext === "htm") return { badge: "HTML", label: "网页", tone: "web" }
+  if (["py", "ts", "tsx", "js", "jsx", "go", "rs", "java", "cpp", "c", "h", "css", "json", "yaml", "yml"].includes(ext))
+    return { badge: ext.toUpperCase().slice(0, 3), label: "代码", tone: "code" }
+  return { badge: ext ? ext.toUpperCase().slice(0, 3) : "FILE", label: "文件", tone: "file" }
+}
+
+function attachmentMeta(item: AttachmentItem): AttachmentMeta {
+  const inferred = inferAttachmentMeta(item.path || item.name)
+  return {
+    badge: (item.badge ?? inferred.badge).trim().toUpperCase().slice(0, 4) || "FILE",
+    label: item.typeLabel ?? inferred.label,
+    tone: inferred.tone,
+  }
+}
+
+/* ------------------------------------------------------------------ *
+ * 操作菜单（Menu 配方）
+ * ------------------------------------------------------------------ */
+
+function isOpenOption(option: AttachmentMenuOption): option is AttachmentOpenOption {
+  return option.kind !== "divider" && option.kind !== "header"
+}
+
+/** 主进程枚举应用是分两拨回的：先回名字、后补图标。图标没齐就还得再刷一次。 */
+function areOptionsComplete(options: AttachmentMenuOption[]): boolean {
+  const apps = options.filter((option): option is AttachmentOpenOption => option.kind === "app")
+  return apps.length === 0 || apps.every((option) => Boolean(option.iconUrl || option.iconName || option.icon))
+}
+
+function optionKey(option: AttachmentMenuOption, index: number): string {
+  return `${option.id}::${isOpenOption(option) ? (option.path ?? "") : index}`
+}
+
+function optionIcon(option: AttachmentOpenOption): ReactNode {
+  if (option.iconUrl)
+    return (
+      <img
+        src={option.iconUrl}
+        alt=""
+        className="w-4 h-4 object-contain [border-radius:var(--ow-radius-2xs)]"
+        aria-hidden="true"
+      />
+    )
+  if (option.iconName) return <Icon name={option.iconName} size={15} />
+  return option.icon ?? null
+}
+
+function toMenuEntries(options: AttachmentMenuOption[]): MenuEntry[] {
+  return options.map((option, index) => {
+    const key = optionKey(option, index)
+    if (option.kind === "divider") return { type: "separator", key }
+    if (option.kind === "header") return { type: "group", key, label: option.name }
+    return { key, label: option.name, icon: optionIcon(option), disabled: option.disabled }
+  })
+}
+
+/**
+ * 「打开方式」选项加载：闲时预取 ＋ 图标补齐后台重刷 ＋ 换文件即作废。
+ * 第一次点开常常在等主进程枚举可用应用，所以空闲期先跑一遍，点开时通常已经在手里了。
+ */
+function useOpenWithOptions(
+  onRequestOptions: (() => Promise<AttachmentMenuOption[]> | AttachmentMenuOption[]) | undefined,
+  optionsKey: string | undefined,
+  prefetch: boolean,
+) {
+  const [options, setOptions] = useState<AttachmentMenuOption[]>([])
+  const [loading, setLoading] = useState(false)
+  const [loaded, setLoaded] = useState(false)
+  const keyRef = useRef(optionsKey)
+  keyRef.current = optionsKey
+  const requestRef = useRef(onRequestOptions)
+  requestRef.current = onRequestOptions
+  const prefetchedRef = useRef<{ key: string | undefined; request: Promise<AttachmentMenuOption[]> } | null>(null)
+
+  // 换了文件，上一份选项就不属于当前这条了，一律作废重来。
+  useEffect(() => {
+    prefetchedRef.current = null
+    setOptions([])
+    setLoaded(false)
+    setLoading(false)
+  }, [optionsKey, onRequestOptions])
+
+  useEffect(() => {
+    if (!prefetch || !onRequestOptions) return
+    let cancelled = false
+    const run = () => {
+      if (cancelled) return
+      const key = keyRef.current
+      let request: Promise<AttachmentMenuOption[]>
+      try {
+        request = Promise.resolve(onRequestOptions())
+      } catch {
+        return
+      }
+      prefetchedRef.current = { key, request }
+      request.catch(() => {
+        if (prefetchedRef.current?.request === request) prefetchedRef.current = null
+      })
+    }
+    if (typeof window.requestIdleCallback === "function") {
+      const idleId = window.requestIdleCallback(run, { timeout: 800 })
+      return () => {
+        cancelled = true
+        window.cancelIdleCallback(idleId)
+      }
+    }
+    const timeoutId = window.setTimeout(run, 150)
+    return () => {
+      cancelled = true
+      window.clearTimeout(timeoutId)
+    }
+  }, [prefetch, onRequestOptions, optionsKey])
+
+  const load = useCallback(async () => {
+    const request = requestRef.current
+    if (!request || loaded) return
+    const requestedKey = keyRef.current
+    const apply = (next: AttachmentMenuOption[]): boolean => {
+      // 请求飞在路上时用户换了文件：结果作废，但别把 loaded 立起来。
+      if (keyRef.current !== requestedKey) return true
+      setOptions(next)
+      const complete = areOptionsComplete(next)
+      setLoaded(complete)
+      return complete
+    }
+    const refresh = () => {
+      let result: Promise<AttachmentMenuOption[]> | AttachmentMenuOption[]
+      try {
+        result = request()
+      } catch {
+        return
+      }
+      void Promise.resolve(result)
+        .then((next) => {
+          apply(next)
+        })
+        .catch(() => {
+          // 后台补图标失败就留着那份没图标的，总比把菜单清空强。
+        })
+    }
+    const prefetched = prefetchedRef.current
+    const result = prefetched && prefetched.key === requestedKey ? prefetched.request : request()
+    if (Array.isArray(result)) {
+      const complete = apply(result)
+      prefetchedRef.current = null
+      if (!complete) refresh()
+      return
+    }
+    setLoading(true)
+    try {
+      const complete = apply(await result)
+      if (prefetchedRef.current?.request === result) prefetchedRef.current = null
+      if (!complete) refresh()
+    } finally {
+      setLoading(false)
+    }
+  }, [loaded])
+
+  return { options, loading, load }
+}
+
+export type OpenWithMenuProps = {
+  /** 触发器文案，默认「打开方式」。 */
+  label?: string
+  /** 触发器左侧图标。 */
+  iconName?: IconName
+  /** 已经在手里的选项；给了 `onRequestOptions` 就以异步结果为准。 */
+  options?: AttachmentMenuOption[]
+  /** 拉取选项（点开时调用，闲时预取一次）。 */
+  onRequestOptions?: () => Promise<AttachmentMenuOption[]> | AttachmentMenuOption[]
+  /** 选项变更的身份（一般是文件 path）：变了就把缓存作废。 */
+  optionsKey?: string
+  /** 选中某项。 */
+  onSelect?: (option: AttachmentOpenOption) => void
+  /** 既没有选项也没有加载器时，触发器退化成一个直接打开的按钮。 */
+  onOpen?: () => void
+  /** 交给宿主弹原生菜单（桌面端 OS 菜单）：给了就不开 web 菜单。 */
+  onNativeMenu?: () => void
+  triggerVariant?: "secondary" | "ghost" | "text"
+  triggerSize?: "sm" | "md"
+  /** 只出图标不出文案（方片/图片形态的「…」）。 */
+  iconOnly?: boolean
+  disabled?: boolean
+  width?: number
+  className?: string
+}
+
+/**
+ * OpenWithMenu — 「打开方式」菜单配方（`Menu` 原语 ＋ 次要按钮触发器）。
+ *
+ * 蓝图裁撤了 `OpenWithButton`（工程件 →Menu 配方），这里是它的规范继任者：
+ * 弹层的立面、翻转、外点关闭、键盘导航全部由 `Menu` 原语承担（portal ＋ fixed，
+ * 视口下方放不下才向上翻，横向夹在视口内，滚动容器裁不掉它）；本配方只管
+ * 「什么时候去拉选项」这件业务事。
+ */
+export function OpenWithMenu({
+  label = "打开方式",
+  iconName,
+  options: optionsProp,
+  onRequestOptions,
+  optionsKey,
+  onSelect,
+  onOpen,
+  onNativeMenu,
+  triggerVariant = "secondary",
+  triggerSize = "sm",
+  iconOnly = false,
+  disabled = false,
+  width = 180,
+  className,
+}: OpenWithMenuProps) {
+  const [open, setOpen] = useState(false)
+  const remote = useOpenWithOptions(onRequestOptions, optionsKey, Boolean(onRequestOptions) && !onNativeMenu)
+  const options = onRequestOptions ? remote.options : (optionsProp ?? [])
+  const entries = useMemo(() => toMenuEntries(options), [options])
+  const byKey = useMemo(() => {
+    const map = new Map<string, AttachmentOpenOption>()
+    options.forEach((option, index) => {
+      if (isOpenOption(option)) map.set(optionKey(option, index), option)
+    })
+    return map
+  }, [options])
+
+  // 没有任何菜单来源就不是菜单，是一个直接打开的按钮；宿主要弹原生菜单时触发器只负责喊一声。
+  const bare = !onRequestOptions && !onNativeMenu && options.length === 0
+  const renderTrigger = (onClick?: () => void) => (
+    <Button
+      variant={triggerVariant}
+      size={triggerSize}
+      type="button"
+      data-slot="open-with"
+      data-ow-part="action"
+      disabled={disabled}
+      className={cn(iconOnly ? "w-7 h-7 p-0" : "gap-1 px-2", className)}
+      aria-label={iconOnly ? label : undefined}
+      title={iconOnly ? label : undefined}
+      onClick={onClick}
+    >
+      {iconName && <Icon name={iconName} size={14} />}
+      {iconOnly ? <Icon name="More" size={16} aria-hidden="true" /> : <span>{label}</span>}
+      {!iconOnly && !bare && <Icon name="ChevDown" size={13} aria-hidden="true" />}
+    </Button>
+  )
+
+  if (bare) return renderTrigger(onOpen)
+  if (onNativeMenu) return renderTrigger(onNativeMenu)
+
+  return (
+    <Menu
+      trigger={renderTrigger()}
+      triggerClassName="inline-flex"
+      open={open}
+      onOpenChange={(next) => {
+        setOpen(next)
+        if (next) void remote.load()
+      }}
+      items={entries}
+      onSelect={(key) => {
+        const option = byKey.get(key)
+        if (option) onSelect?.(option)
+      }}
+      empty={remote.loading ? "加载中" : "暂无打开方式"}
+      align="end"
+      width={width}
+      ariaLabel={label}
+      // 视口再矮也不许把菜单撑出屏外：280 与「视口高减两边留白」取小。
+      className="max-h-[min(280px,calc(100vh-16px))] overflow-y-auto"
+    />
+  )
+}
+
+/* ------------------------------------------------------------------ *
+ * Attachment
+ * ------------------------------------------------------------------ */
+
+export type AttachmentProps = {
+  /** 文件名（显示名）。 */
+  name: string
+  /** 完整路径：进 title 保全值，也作操作菜单缓存的身份。 */
+  path?: string
+  /** 形态，见组件说明。 */
+  variant?: AttachmentVariant
+  /** meta 读数（大小/类型/尺寸/时间）。不给就按扩展名推断类型文案。 */
+  meta?: string
+  /** 应用侧的文件分类（image/video/pdf…），扩展名认不出时兜底。 */
+  kind?: string
+  /** 类型图标右下角标签的显式覆盖（≤4 字符）；不传按文件名推断。 */
+  badge?: string
+  /** 图片/富媒体形态的图源。 */
+  thumbnail?: string
+  /** 富媒体形态的说明行。 */
+  caption?: string
+  /** 没有图源时的占位读数，如 "cover.jpg · 1600×900"。 */
+  placeholder?: string
+  status?: AttachmentStatus
+  /** 上传进度 0–100。 */
+  progress?: number
+  /** 失败的一句人话。 */
+  errorText?: string
+  disabled?: boolean
+  /** 打开这个附件（给了就整块可点）。 */
+  onOpen?: () => void
+  onRetry?: () => void
+  onRemove?: () => void
+  /** 操作菜单选项（`OpenWithMenu` 配方）。 */
+  actions?: AttachmentMenuOption[]
+  onRequestActions?: () => Promise<AttachmentMenuOption[]> | AttachmentMenuOption[]
+  onAction?: (option: AttachmentOpenOption) => void
+  /** 交给宿主弹原生菜单。 */
+  onNativeActionsMenu?: () => void
+  /** 操作菜单触发器文案，默认「打开方式」。 */
+  actionsLabel?: string
+  className?: string
+}
+
+const NAME_CLASS =
+  "min-w-0 text-[length:var(--ow-fs-ui)] font-medium leading-snug text-[color:var(--ow-text)] overflow-hidden text-ellipsis"
+/** 读数一律 mono ＋ tabular-nums（§7）。 */
+const META_TEXT_CLASS =
+  "font-[family-name:var(--ow-font-mono)] tabular-nums text-[length:var(--ow-fs-eyebrow)] leading-snug text-[color:var(--ow-text-3)]"
+const META_CLASS = `min-w-0 truncate ${META_TEXT_CLASS}`
+/** 体积/尺寸这一截是白名单：不为类型那截让位（shrink-0）；max-w-full 只是兜底，
+ *  防某个畸形长读数把方片撑破。 */
+const META_READING_CLASS = `shrink-0 max-w-full truncate ${META_TEXT_CLASS}`
+
+/**
+ * 方片 112 宽的 meta 行拆两截：末尾「· 」之后的读数（854 KB / 2.4 MB）是白名单，
+ * 前面的类型那截才承担省略号。类型那截若与 FileIcon 的扩展名标签重复（DOC/DOCX、
+ * PDF…），直接摘掉——方片里那枚字形已经在说同一件事，读数才是这行的信息。
+ *
+ * 起因：mono 读数比 R1 的 sans 宽，「DOC · 854 KB」在 84px 内容宽里被截成「85…」，
+ * 体积整段消失（三方对齐轮 R2 退化）。
+ */
+function splitTileMeta(line: string, typeLabel: string | null): { head: string; reading: string } {
+  const parts = line.split("·").map((part) => part.trim())
+  if (parts.length < 2 || parts.some((part) => !part)) return { head: "", reading: line }
+  const reading = parts[parts.length - 1] ?? line
+  const head = parts.slice(0, -1)
+  const first = (head[0] ?? "").toUpperCase()
+  if (typeLabel !== null && (first.startsWith(typeLabel) || typeLabel.startsWith(first))) head.shift()
+  return { head: head.join(" · "), reading }
+}
+
+function RemoveButton({ onClick, disabled }: { onClick: () => void; disabled?: boolean }) {
+  return (
+    <Button
+      variant="ghost"
+      size="sm"
+      type="button"
+      data-ow-part="remove"
+      className="w-7 h-7 p-0 shrink-0"
+      aria-label="移除附件"
+      title="移除附件"
+      disabled={disabled}
+      onClick={(event) => {
+        event.stopPropagation()
+        onClick()
+      }}
+      icon={<Icon name="Close" size={14} />}
+    />
+  )
+}
+
+function RetryButton({ onClick, disabled }: { onClick: () => void; disabled?: boolean }) {
+  return (
+    <Button
+      variant="text"
+      size="sm"
+      type="button"
+      data-ow-part="retry"
+      className="shrink-0"
+      disabled={disabled}
+      onClick={(event) => {
+        event.stopPropagation()
+        onClick()
+      }}
+    >
+      重试
+    </Button>
+  )
+}
+
+/** 上传中：进度条走 `--ow-progress-fill`（墨/月白），读数 mono；永不荧黄（§4）。 */
+function UploadProgress({ name, progress }: { name: string; progress: number }) {
+  return <ProgressBar value={progress} size="sm" aria-label={`${name} 上传进度`} className="mt-1" />
+}
+
+export function Attachment({
+  name,
+  path,
+  variant = "card",
+  meta,
+  kind,
+  badge,
+  thumbnail,
+  caption,
+  placeholder,
+  status = "done",
+  progress = 0,
+  errorText = "上传失败",
+  disabled = false,
+  onOpen,
+  onRetry,
+  onRemove,
+  actions,
+  onRequestActions,
+  onAction,
+  onNativeActionsMenu,
+  actionsLabel = "打开方式",
+  className,
+}: AttachmentProps) {
+  const pct = Math.max(0, Math.min(100, Math.round(progress)))
+  const inferred = attachmentMeta({ name, path: path ?? name })
+  // meta 传空串＝显式不要这行（可点的卡本身就是打开入口，推断出的类型文案只是重复扩展名）。
+  const metaText = status === "uploading" ? `上传中 ${pct}%` : (meta ?? inferred.label)
+  const metaLine = status === "error" ? errorText : metaText
+  const clickable = Boolean(onOpen) && !disabled
+  const hasMenu = Boolean(actions?.length || onRequestActions || onNativeActionsMenu)
+
+  const menu = hasMenu ? (
+    <OpenWithMenu
+      label={actionsLabel}
+      options={actions}
+      onRequestOptions={onRequestActions}
+      optionsKey={path ?? name}
+      onSelect={onAction}
+      onNativeMenu={onNativeActionsMenu}
+      disabled={disabled}
+      iconOnly={variant !== "card"}
+      triggerVariant={variant === "card" ? "secondary" : "ghost"}
+    />
+  ) : null
+
+  /* ---- 图片形态：缩略 ＋ scrim 遮罩操作 ---- */
+  if (variant === "image" || variant === "media") {
+    const media = variant === "media"
+    return (
+      <div
+        data-slot="attachment"
+        data-ow-variant={variant}
+        data-ow-state={status}
+        title={path ?? name}
+        className={cn(
+          "group relative box-border overflow-hidden border [border-radius:var(--ow-radius-card)]",
+          "bg-[var(--ow-surface)]",
+          "transition-[border-color] duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+          media ? "w-full max-w-[420px]" : "w-28 h-28 shrink-0",
+          status === "error" ? "border-[color:var(--ow-error)]" : "border-[color:var(--ow-border)]",
+          clickable && "cursor-pointer ow-focus-ring",
+          className,
+        )}
+        role={clickable ? "button" : undefined}
+        tabIndex={clickable ? 0 : undefined}
+        aria-label={clickable ? `打开 ${name}` : undefined}
+        onClick={clickable ? onOpen : undefined}
+        onKeyDown={
+          clickable
+            ? (event) => {
+                // L3-2-1：只认落在卡壳自己身上的键；卡内的钮自己处理 Enter/空格。
+                if (event.target !== event.currentTarget) return
+                if (event.key === "Enter" || event.key === " ") {
+                  event.preventDefault()
+                  onOpen?.()
+                }
+              }
+            : undefined
+        }
+      >
+        <div data-ow-part="media" className={cn("w-full overflow-hidden", media ? "h-[200px]" : "h-full")}>
+          {thumbnail ? (
+            <img src={thumbnail} alt={caption || name} className="w-full h-full object-cover" />
+          ) : (
+            <span
+              data-ow-part="placeholder"
+              className="flex w-full h-full items-center justify-center bg-[var(--ow-surface-2)] px-2 text-center"
+            >
+              <span className={META_CLASS}>{placeholder ?? name}</span>
+            </span>
+          )}
+        </div>
+        {media && caption && (
+          <div
+            data-ow-part="caption"
+            className="py-2.5 px-3.5 text-[length:var(--ow-fs-caption)] leading-snug text-[color:var(--ow-text-2)]"
+          >
+            {caption}
+          </div>
+        )}
+        {status === "uploading" && (
+          <div data-ow-part="upload" className="absolute inset-x-0 bottom-0 px-2 pb-2">
+            <span className={cn(META_CLASS, "block text-[color:var(--ow-on-fill)]")}>上传中 {pct}%</span>
+            <UploadProgress name={name} progress={pct} />
+          </div>
+        )}
+        {/* 遮罩操作：hover / 键盘聚焦才浮出，底走 --ow-scrim，字走 --ow-on-fill（实底上的字，§2）。
+            遮罩本身不吃指针 —— 图整块可点时，点在空处仍要开预览；只有按钮那一小块收指针，
+            并把点击/回车拦在自己这层，否则移除一个附件顺带把预览也开了。 */}
+        {(onRemove || (status === "error" && onRetry) || menu) && (
+          <span
+            data-ow-part="overlay"
+            className={cn(
+              "pointer-events-none absolute inset-0 flex items-start justify-end p-1.5",
+              "bg-[var(--ow-scrim)] text-[color:var(--ow-on-fill)]",
+              "opacity-0 transition-opacity duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+              "group-hover:opacity-100 group-focus-within:opacity-100",
+            )}
+          >
+            <span
+              data-ow-part="actions"
+              className="pointer-events-auto flex items-center gap-1"
+              onClick={(event) => event.stopPropagation()}
+              onKeyDown={(event) => event.stopPropagation()}
+            >
+              {status === "error" && onRetry && <RetryButton onClick={onRetry} disabled={disabled} />}
+              {menu}
+              {onRemove && <RemoveButton onClick={onRemove} disabled={disabled} />}
+            </span>
+          </span>
+        )}
+        {status === "error" && (
+          <span
+            data-ow-part="error"
+            className="absolute inset-x-0 bottom-0 truncate bg-[var(--ow-error-tint)] px-2 py-1 text-[length:var(--ow-fs-eyebrow)] leading-snug text-[color:var(--ow-error-on-tint)]"
+          >
+            {errorText}
+          </span>
+        )}
+      </div>
+    )
+  }
+
+  /* ---- 方片形态：Composer 附件条 ---- */
+  if (variant === "tile") {
+    const iconLabel = badge?.trim().toUpperCase().slice(0, 4) || resolveFileIcon(name, kind)?.label || null
+    const tileMeta = splitTileMeta(metaLine, iconLabel)
+    return (
+      <div
+        data-slot="attachment"
+        data-ow-variant="tile"
+        data-ow-state={status}
+        title={path ?? name}
+        className={cn(
+          // 卡骨架收口口径：容器 14（p-3.5），与 card 形态同一口径。
+          "group relative box-border flex w-28 h-28 shrink-0 flex-col justify-between gap-1 p-3.5",
+          "border [border-radius:var(--ow-radius-card)]",
+          "transition-[background-color,border-color] duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+          status === "error"
+            ? "border-[color:var(--ow-error-tint-border)] bg-[var(--ow-error-tint)]"
+            : "border-[color:var(--ow-border)] bg-[var(--ow-surface)]",
+          disabled && "border-[color:var(--ow-disabled-border)] bg-[var(--ow-disabled-bg)]",
+          className,
+        )}
+      >
+        <span
+          data-ow-part="name"
+          className={cn(
+            NAME_CLASS,
+            "[display:-webkit-box] [-webkit-box-orient:vertical] [-webkit-line-clamp:2] [overflow-wrap:anywhere]",
+            disabled && "text-[color:var(--ow-disabled-text)]",
+          )}
+        >
+          {name}
+        </span>
+        <span data-ow-part="meta" className="flex min-w-0 items-center gap-1 overflow-hidden">
+          <FileIcon
+            name={name}
+            kind={kind}
+            label={badge}
+            className="shrink-0 text-[color:var(--ow-text-2)]"
+            width={15}
+            height={15}
+          />
+          {tileMeta.head && (
+            <span
+              className={cn(
+                META_CLASS,
+                status === "error" && "text-[color:var(--ow-error-on-tint)]",
+                disabled && "text-[color:var(--ow-disabled-text)]",
+              )}
+            >
+              {tileMeta.head} ·
+            </span>
+          )}
+          <span
+            className={cn(
+              META_READING_CLASS,
+              status === "error" && "text-[color:var(--ow-error-on-tint)]",
+              disabled && "text-[color:var(--ow-disabled-text)]",
+            )}
+          >
+            {tileMeta.reading}
+          </span>
+        </span>
+        {status === "uploading" && <UploadProgress name={name} progress={pct} />}
+        {(onRemove || (status === "error" && onRetry) || menu) && (
+          <span
+            data-ow-part="actions"
+            className={cn(
+              "absolute top-1 right-1 flex items-center gap-0.5",
+              // 方片顶角是文件名的地盘:悬出来的操作组压字,给它一块与卡同色的实底,
+              // 读得清也不显脏(image 形态的 scrim 同款思路);错误/禁用档跟着卡底走。
+              "[border-radius:var(--ow-radius-2xs)]",
+              status === "error"
+                ? "bg-[var(--ow-error-tint)]"
+                : disabled
+                  ? "bg-[var(--ow-disabled-bg)]"
+                  : "bg-[var(--ow-surface)]",
+              "opacity-0 transition-opacity duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+              "group-hover:opacity-100 group-focus-within:opacity-100",
+            )}
+          >
+            {status === "error" && onRetry && <RetryButton onClick={onRetry} disabled={disabled} />}
+            {menu}
+            {onRemove && <RemoveButton onClick={onRemove} disabled={disabled} />}
+          </span>
+        )}
+      </div>
+    )
+  }
+
+  /* ---- 横卡形态：转录里的文件引用 ---- */
+  const body = (
+    <span data-ow-part="content" className="grid min-w-0 grid-cols-[auto_minmax(0,1fr)] items-center gap-3 text-left">
+      <FileIcon
+        name={name}
+        kind={kind}
+        label={badge}
+        className={cn("shrink-0 text-[color:var(--ow-text-2)]", disabled && "text-[color:var(--ow-disabled-text)]")}
+        width={28}
+        height={28}
+      />
+      <span className="flex min-w-0 flex-col gap-0.5">
+        <span
+          data-ow-part="name"
+          className={cn(NAME_CLASS, "whitespace-nowrap", disabled && "text-[color:var(--ow-disabled-text)]")}
+        >
+          {name}
+        </span>
+        {metaLine && (
+          <span
+            data-ow-part="meta"
+            className={cn(
+              META_CLASS,
+              status === "error" && "text-[color:var(--ow-error-on-tint)]",
+              disabled && "text-[color:var(--ow-disabled-text)]",
+            )}
+          >
+            {metaLine}
+          </span>
+        )}
+      </span>
+    </span>
+  )
+
+  return (
+    <div
+      data-slot="attachment"
+      data-ow-variant="card"
+      data-ow-state={status}
+      title={path ?? name}
+      className={cn(
+        // 卡骨架收口口径：容器 14（p-3.5）。原来是 py-2.5 px-3 ＝ 10/12，一套卡三个内距值并存
+        // （tile 12、card 10/12、同期改过的 .cronjob-card/.skcard/.site-card 都是 14）。
+        "box-border grid w-full min-h-[62px] grid-cols-[minmax(0,1fr)_auto] items-center gap-3 p-3.5",
+        // 贴地之物：1px 边 ＋ 0 影（§5）。
+        "border [border-radius:var(--ow-radius-card)] text-[color:var(--ow-text)]",
+        "transition-[background-color,border-color] duration-[var(--ow-dur-1)] ease-[var(--ow-ease-beacon)]",
+        status === "error"
+          ? "border-[color:var(--ow-error-tint-border)] bg-[var(--ow-error-tint)]"
+          : "border-[color:var(--ow-border)] bg-[var(--ow-surface)]",
+        disabled && "border-[color:var(--ow-disabled-border)] bg-[var(--ow-disabled-bg)]",
+        className,
+      )}
+    >
+      <span className="grid min-w-0 gap-1">
+        {clickable ? (
+          <Button
+            variant="unstyled"
+            type="button"
+            data-ow-part="main"
+            disabled={disabled}
+            className="ow-focus-ring grid min-w-0 cursor-pointer p-0 text-left [border-radius:var(--ow-radius-control)] hover:bg-[var(--ow-hover)] active:bg-[var(--ow-press)]"
+            onClick={onOpen}
+          >
+            {body}
+          </Button>
+        ) : (
+          body
+        )}
+        {status === "uploading" && <UploadProgress name={name} progress={pct} />}
+      </span>
+      {(menu || onRemove || (status === "error" && onRetry)) && (
+        <span data-ow-part="actions" className="inline-flex items-center gap-1.5">
+          {status === "error" && onRetry && <RetryButton onClick={onRetry} disabled={disabled} />}
+          {menu}
+          {onRemove && <RemoveButton onClick={onRemove} disabled={disabled} />}
+        </span>
+      )}
+    </div>
+  )
+}
+
+/* ------------------------------------------------------------------ *
+ * AttachmentList
+ * ------------------------------------------------------------------ */
+
+export type AttachmentListProps = {
+  /** `strip` 横排可滚（Composer 附件条）· `stack` 竖列（转录里的文件引用）。 */
+  layout?: "strip" | "stack"
+  /** 没有条目时的空态一句话；不给就整块不渲染。 */
+  empty?: ReactNode
+  children?: ReactNode
+  className?: string
+  "aria-label"?: string
+}
+
+/**
+ * AttachmentList — 附件行集（合并旧 `Attachments` 横排与 `FileReferenceCards` 竖列）。
+ * 空态母题走 `EmptyState` 原语（信标 mono 母题 ＋ 一句 text-2，禁插画禁 emoji）。
+ */
+export function AttachmentList({
+  layout = "strip",
+  empty,
+  children,
+  className,
+  "aria-label": ariaLabel,
+}: AttachmentListProps) {
+  const isEmpty = children === null || children === undefined || (Array.isArray(children) && children.length === 0)
+  if (isEmpty && !empty) return null
+  return (
+    <div
+      data-slot="attachment-list"
+      data-ow-variant={layout}
+      aria-label={ariaLabel}
+      className={cn(
+        layout === "strip"
+          ? "flex gap-2 overflow-x-auto overflow-y-hidden"
+          : "flex w-full max-w-[520px] flex-col gap-2",
+        className,
+      )}
+    >
+      {isEmpty ? <EmptyState message={empty} markSize={28} /> : children}
+    </div>
+  )
+}