@qijenchen/design-system 0.1.0-beta.13 → 0.1.0-beta.130

package/src/components/FileViewer/file-viewer.tsx

@@ -15,8 +15,9 @@ import {
   FileText,
 } from 'lucide-react'
 import { cn } from '@/lib/utils'
+import { OVERLAY_SIDE_OFFSET } from '@/design-system/tokens/elevation/overlay-geometry'
 import { Button } from '@/design-system/components/Button/button'
-import { Separator } from '@/design-system/components/Separator/separator'
+import { ButtonDivider } from '@/design-system/components/Button/button-group'
 import { Input } from '@/design-system/components/Input/input'
 import { Empty } from '@/design-system/components/Empty/empty'
 import { AspectRatio } from '@/design-system/components/AspectRatio/aspect-ratio'
@@ -33,18 +34,21 @@ import {
   DropdownMenuItem,
   DropdownMenuSeparator,
 } from '@/design-system/components/DropdownMenu/dropdown-menu'
-import {
+import { ARROW_BUTTON_WIDTH,
   useScrollEdges,
   useScrollByPage,
   buildFadeMask,
   OverflowScrollArrow,
 } from '@/design-system/patterns/horizontal-overflow/horizontal-overflow'
-import { ImageRenderer, canRenderImage } from './image-renderer'
+import { useControllable } from '@/design-system/hooks/use-controllable'
+import { canRenderImage } from './can-render-image'
 import type {
   FileInfo,
   FileRenderer,
   FileRendererCapabilities,
+  FileRendererProps,
 } from './file-viewer-types'
+import { surfaceMotion } from "@/design-system/tokens/motion/overlay-motion"
 
 /**
  * FileViewer — 可延伸的網頁檔案 preview shell(modal fullscreen)
@@ -56,8 +60,8 @@ import type {
  *
  * ── 實作基礎 ──
  * 自建 composite,消費 DS primitives:
- *   - Radix DialogPrimitive(焦點 trap / Esc / aria-modal,保有 shadcn 結構優勢)
- *   - `<Empty>` / `<Button>` / `<Input variant="bare">` / `<AspectRatio>` / `<Textarea>` / `<DropdownMenu>`
+ *   - Radix DialogPrimitive(焦點 trap / Esc / modal 隔離靠 hideOthers aria-hidden — react-dialog@1.1.x 不輸出 aria-modal,保有 shadcn 結構優勢)
+ *   - `<Empty>` / `<Button>` / `<Input size="sm" autoWidth>`(ZoomInput,default variant)/ `<AspectRatio>` / `<Textarea>` / `<DropdownMenu>`
  *   - `patterns/horizontal-overflow`(filmstrip 溢出捲動)
  * 不用 DS 的 `<Dialog>` wrapper:因為 FileViewer 需要 edge-to-edge fullscreen
  * (無 viewport inset / 無 rounded-lg / 無 maxWidth),Dialog 的這些預設都要覆寫。
@@ -79,26 +83,44 @@ import type {
  * Fallback renderer — 無 renderer 能處理時兜底。
  * 顯示 Empty 佈局:icon + 檔名 + 「請下載檢視」提示。
  */
-const FallbackRenderer: React.FC<{ file: FileInfo }> = ({ file }) => (
-  <div className="w-full h-full flex items-center justify-center p-8">
-    <Empty
-      icon={FileText}
-      title={file.name}
-      description={`無法在瀏覽器中預覽此檔案類型（${file.mimeType || 'unknown'}）。請下載後檢視。`}
-    />
-  </div>
-)
+const FallbackRenderer: React.FC<FileRendererProps> = ({ file, onCapabilitiesChange }) => {
+  // Contract(file-viewer-types.ts `onCapabilitiesChange` doc):「第一個 renderer mount
+  // 時必須 emit」。fallback 不支援 zoom → emit { zoom: false };不 emit 的話 shell 會沿用
+  // 上一個 renderer 的 capability(image → 未知檔切換時 toolbar 殘留 zoom controls,
+  // `+`/`-`/`0`/`F` 快捷鍵也會對不支援 zoom 的檔案生效)。同 image-renderer.tsx mount emit pattern。
+  React.useEffect(() => {
+    onCapabilitiesChange({ zoom: false })
+  }, [onCapabilitiesChange])
+
+  return (
+    <div className="w-full h-full flex items-center justify-center p-8">
+      <Empty
+        icon={FileText}
+        title={file.name}
+        description={`無法在瀏覽器中預覽此檔案類型（${file.mimeType || 'unknown'}）。請下載後檢視。`}
+      />
+    </div>
+  )
+}
 
 const fallbackRenderer: FileRenderer = {
   id: 'fallback',
   canRender: () => true,
-  component: ({ file }) => <FallbackRenderer file={file} />,
+  component: FallbackRenderer,
 }
 
+// 2026-07-06 D3 bundle fix:ImageRenderer 改 React.lazy 動態 import——FileViewer 是
+// rare-use modal overlay,react-zoom-pan-pinch(~12KB gz)不該在 viewer 從未打開時就進
+// consumer 首屏 bundle。canRenderImage(registry 判斷 + Filmstrip 分流需同步呼叫)已拆至
+// ./can-render-image 保持靜態 import。
+const LazyImageRenderer = React.lazy(() =>
+  import('./image-renderer').then((m) => ({ default: m.ImageRenderer })),
+)
+
 const imageRenderer: FileRenderer = {
   id: 'image',
   canRender: canRenderImage,
-  component: ImageRenderer,
+  component: LazyImageRenderer,
 }
 
 // Registry 是 module-singleton:新 renderer 透過 registerFileRenderer 加入。
@@ -158,14 +180,14 @@ interface ZoomInputProps {
 }
 
 /**
- * ZoomInput — [−] [% input(bare)with ⌄ menu trigger] [+]
+ * ZoomInput — [−] [% input(default variant + autoWidth)with ⌄ menu trigger] [+]
  *
  * 世界級對照:Figma zoom control / Adobe Acrobat / Google Slides zoom。
  *
  * ── 消費 DS primitive ──
  *   - `<Button>` iconOnly size="sm" 作 ±按鈕
- *   - `<Input variant="bare" size="sm">` 作 %輸入(Toolbar inline editing canonical)
- *   - Input `endAction` slot 提供 ⌄ chevron 觸發 DropdownMenu
+ *   - `<Input size="sm" autoWidth>` 作 %輸入(Toolbar inline editing canonical;autoWidth 隨文字寬)
+ *   - Input `endSlot` escape hatch 包 `<DropdownMenuTrigger asChild>` + chevron 觸發 DropdownMenu
  *   - `<DropdownMenu>` 作 preset + fit 選單(取代原先 Popover + 手刻 button list)
  *
  * ── 為什麼 inline(不抽獨立 primitive)──
@@ -212,9 +234,13 @@ const ZoomInput: React.FC<ZoomInputProps> = ({ value, onChange, onFit, labels })
           — 靠 Radix asChild + ItemInlineActionButton:視覺是 Input + endAction,行為是 chevron-as-trigger
           — 完全對齊 user AR:「只有 inline action 能觸發選單,menu 對齊 inline action」 */}
       <DropdownMenu open={menuOpen} onOpenChange={setMenuOpen}>
+        {/* maxLength 限縮(2026-07-09 user 要求「找合理最大值避免無限輸入」):autoWidth 下輸入框寬度隨字數長,
+            無上限則可無限打字撐爆 toolbar。max 合法值「400%」= 4 字(對齊 ZOOM_PRESETS / ImageRenderer MAX_SCALE 400;
+            commitDraft 另 clamp 10–400),留 1 字編輯緩衝 → maxLength={5}。 */}
         <Input
           size="sm"
           autoWidth
+          maxLength={5}
           aria-label={labels.zoomInput}
           value={draft}
           onChange={(e) => setDraft(e.target.value)}
@@ -244,7 +270,7 @@ const ZoomInput: React.FC<ZoomInputProps> = ({ value, onChange, onFit, labels })
             Tailwind 條件 class + CSS variable 都要一起帶) */}
         <DropdownMenuContent
           align="end"
-          sideOffset={8}
+          sideOffset={OVERLAY_SIDE_OFFSET}  // 2026-07-04:M17 — elevation.spec「primitive default 必 import 該 const」
           // minWidth 對齊 trigger(Input autoWidth),menu 寬度 fit-content 更貼近觸發點視覺中心
           className="min-w-[9rem] w-auto bg-surface-raised text-foreground border-divider"
           data-theme="dark"
@@ -266,11 +292,11 @@ const ZoomInput: React.FC<ZoomInputProps> = ({ value, onChange, onFit, labels })
                 <DropdownMenuItem
                   key={p}
                   onSelect={() => onChange(p)}
-                  data-state={selected ? 'checked' : undefined}
-                  className={cn(
-                    'tabular-nums',
-                    selected && 'bg-neutral-selected',
-                  )}
+                  // 2026-08-11 修偏移:原手刻 data-state + bg-neutral-selected(plain class 被 base
+                  // highlighted 洗淺 = drift)→ 消費 DropdownMenuItem 既有 selected prop,
+                  // 疊加行為(滑鼠釘住/鍵盤 -focus)隨 canonical SSOT 走(M23)。
+                  selected={selected}
+                  className="tabular-nums"
                 >
                   {p}%
                 </DropdownMenuItem>
@@ -326,7 +352,9 @@ const Toolbar: React.FC<ToolbarProps> = ({
 }) => {
   return (
     <ChromeHeader
-      lockDensity="lg"
+      // Density:繼承 page(2026-06-15 canonical)。原 lockDensity="lg" 只鎖在 header、沒鎖 body →
+      // InfoPanel header(px-loose@lg=24)與其 body(px-loose@page=16)左緣不對齊(圖二 bug)。移除 lock
+      // → header + body 全繼承 page density,左緣對齊;FileViewer 全 surface 同一密度(non-special)。
       className={cn(
         // Chrome layer — `bg-surface-raised` 對齊 token semantic「遮蓋型浮層必須不透明」。
         // FileViewer 整體是 overlay,chrome 屬其 raised surface(同 DropdownMenuContent line 244)。
@@ -355,16 +383,17 @@ const Toolbar: React.FC<ToolbarProps> = ({
 
           ── gap-2 canonical(2026-04-21 follow-up)──
           按鈕間距 **8px**(gap-2),對齊 Dialog footer `gap-2` / CLAUDE 按鈕間距 SSOT。
-          zoom group 內部例外 gap-0.5(見 ZoomInput) — 那是「連緊 segmented pill」語意,
-          跟這裡 action-group-to-action-group 的 gap-2 不同層級。 */}
+          zoom group(ZoomInput)內部同樣是 gap-2(見 `ZoomInput` L197),
+          與這裡 action-group-to-action-group 的 gap-2 一致。 */}
       <div className="flex items-center gap-2 shrink-0">
         {capabilities.zoom && (
           <>
             {/* Zoom group:-/%/+/▼ 屬同類「縮放」操作,群組並在右側加分隔線跟其他動作分群 */}
             <ZoomInput value={zoom} onChange={onZoomChange} onFit={onFit} labels={labels} />
-            {/* zoom group → next action group divider(action-bar canonical;v11 升級成 Separator
-                元件,對齊 separator.spec.md「consumer 手動放置 toolbar 群組分隔線 = 用 Separator」)*/}
-            <Separator orientation="vertical" className="h-6 mx-1" />
+            {/* zoom group → next action group divider。幾何 SSOT = action-bar.spec.md「分隔線幾何」:
+                線長由 ButtonDivider 依「該列最高元件 − inset」自動算,不再手寫高度(舊 h-6 是寫死值,
+                與 DS 主要實作的 ButtonDivider 形成兩套機制)。*/}
+            <ButtonDivider />
           </>
         )}
         <Button
@@ -387,8 +416,8 @@ const Toolbar: React.FC<ToolbarProps> = ({
           />
         )}
         {/* action-bar canonical:dismiss 前加分隔線跟其他動作分群(info/download = action group,
-            close = dismiss group;v11 升級成 Separator,對齊 separator.spec.md canonical)*/}
-        <Separator orientation="vertical" className="h-6 mx-1" />
+            close = dismiss group)。幾何同上,由 ButtonDivider 自動算。*/}
+        <ButtonDivider />
         {/* Close X 走 dismiss canonical(`<Button iconOnly dismiss />`)——對齊 CLAUDE.md
             `button.spec.md`「Dismiss 視覺類」+ `patterns/element-anatomy/item-anatomy.spec.md`
             「Dismiss canonical」:chrome corner close X = Button dismiss,不是 Inline Action。 */}
@@ -424,13 +453,16 @@ function formatBytes(bytes: number | undefined): string | undefined {
   return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`
 }
 
-const InfoPanel: React.FC<InfoPanelProps> = ({
+// React.memo(2026-07-06 D3):同 Filmstrip——wheel-zoom 每 tick 全 chrome re-render,InfoPanel
+// 開啟時(Field/Textarea/DescriptionList subtree)白付。onClose 走 shell handleInfoClose
+// useCallback;file(files[activeIndex] identity 穩定)/readOnly/onDescriptionChange/labels 本已穩定。
+const InfoPanel = React.memo(function InfoPanel({
   file,
   readOnly,
   onDescriptionChange,
   onClose,
   labels,
-}) => {
+}: InfoPanelProps) {
   const [draft, setDraft] = React.useState(file.description ?? '')
 
   React.useEffect(() => {
@@ -455,8 +487,9 @@ const InfoPanel: React.FC<InfoPanelProps> = ({
       )}
       aria-label={labels.detailPanel}
     >
-      {/* Panel header — 與 Toolbar 等高(consume ChromeHeader lockDensity="lg"),視覺一致 */}
-      <ChromeHeader lockDensity="lg" className="justify-between">
+      {/* Panel header — 與 Toolbar 同 ChromeHeader,繼承 page density(2026-06-15:移除 lockDensity,
+          修 header(原 px-loose@lg=24)與 body(px-loose@page=16)左緣不對齊 = 圖二 bug;全 surface 同密度)。 */}
+      <ChromeHeader className="justify-between">
         <h3 className="text-body-lg font-medium text-foreground">{labels.detailsHeading}</h3>
         {/* InfoPanel close 走 dismiss canonical `<Button iconOnly dismiss />`,對齊 button.spec.md
             「Dismiss 視覺類」+ inline-action.spec.md「Dismiss canonical — X close only」。 */}
@@ -498,15 +531,15 @@ const InfoPanel: React.FC<InfoPanelProps> = ({
         {/* 檔案資訊 — 用 DS DescriptionList horizontal + divided(Google Drive /
             Notion file info panel 模式):
             - section header 用 FieldLabel 同款 typography 保視覺一致
-            - DescriptionList direction="horizontal" divided 提供 row 下底線
+            - DescriptionList orientation="horizontal" divided 提供 row 下底線
               對齊格線,key 長度不一也易讀
             - 不再手刻 dl/dt/dd — canonical 由 DS primitive own */}
         {/* heading → first-item gap = item → item gap(Gestalt proximity,見 description-list.spec.md) */}
         <div className="flex flex-col gap-[var(--layout-space-tight)]">
           <span className="text-body font-normal text-foreground">{labels.fileInfoHeading}</span>
-          <DescriptionList direction="horizontal" divided>
+          <DescriptionList orientation="horizontal" divided>
             <DescriptionItem label="檔名">{file.name}</DescriptionItem>
-            <DescriptionItem label="類型">{file.mimeType || '—'}</DescriptionItem>
+            <DescriptionItem label="類型">{file.mimeType || '-'}</DescriptionItem>
             {sizeText && (
               <DescriptionItem label="大小">
                 <span className="tabular-nums">{sizeText}</span>
@@ -522,7 +555,7 @@ const InfoPanel: React.FC<InfoPanelProps> = ({
       </ScrollArea>
     </aside>
   )
-}
+})
 
 // ─── Filmstrip ────────────────────────────────────────────────────────────────
 
@@ -536,10 +569,13 @@ interface FilmstripProps {
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const THUMB_SIZE = 64 // px, 固定
 
-const Filmstrip: React.FC<FilmstripProps> = ({ files, activeIndex, onSelect, labels }) => {
+// React.memo(2026-07-06 D3):wheel-zoom 每 tick(trackpad 60Hz+)setZoom → shell 全 chrome
+// re-render,Filmstrip(N thumbs × cn + buildFadeMask)是最貴的無關 subtree。props 已全穩定
+// (files=prop / activeIndex=primitive / onSelect=setIndex useCallback / labels=useMemo)→ memo 真命中。
+const Filmstrip = React.memo(function Filmstrip({ files, activeIndex, onSelect, labels }: FilmstripProps) {
   const { scrollRef, atStart, atEnd, canScroll } = useScrollEdges<HTMLDivElement>()
   const scrollByPage = useScrollByPage(scrollRef)
-  const maskImage = buildFadeMask({ canScroll, atStart, atEnd, reserveArrowWidth: 32 })
+  const maskImage = buildFadeMask({ canScroll, atStart, atEnd, reserveArrowWidth: ARROW_BUTTON_WIDTH })  // 2026-07-04:消 SSOT 硬寫(spec 禁止重新定義 ARROW_BUTTON_WIDTH)
 
   // 切換當前檔案時,自動 scroll 讓 active thumb 可見
   React.useEffect(() => {
@@ -578,9 +614,11 @@ const Filmstrip: React.FC<FilmstripProps> = ({ files, activeIndex, onSelect, lab
             gap-[var(--layout-space-tight)] 走 DS density-aware token(不用 raw gap-1)——
             世界級 idiom:Google Drive / Dropbox / Notion file preview 的 filmstrip 都是
             少量置中 / 多量靠 start scroll。
-            role="tablist" 擺在 tabs 的直接父元件,符合 ARIA tab pattern 語意。 */}
+            ARIA role="group"(非 tablist):filmstrip 是「選圖導航」不是「切換 N 個 tabpanel」——
+            lightbox 縮圖膠卷只有單一 viewport,不符 W3C tabs pattern(tab MUST 對應自己的 tabpanel + roving tabindex)。
+            對齊 APG grouped-carousel + PhotoSwipe / codeaccessible.com lightbox 共識:group + button + aria-current。 */}
         <div
-          role="tablist"
+          role="group"
           aria-label={labels.filmstripLabel}
           className="flex items-center gap-[var(--layout-space-tight)] mx-auto shrink-0"
         >
@@ -592,8 +630,7 @@ const Filmstrip: React.FC<FilmstripProps> = ({ files, activeIndex, onSelect, lab
             <button
               key={file.id}
               type="button"
-              role="tab"
-              aria-selected={active}
+              aria-current={active ? 'true' : undefined}
               aria-label={`${i + 1} / ${files.length}:${file.name}`}
               data-thumb-index={i}
               onClick={() => onSelect(i)}
@@ -633,7 +670,7 @@ const Filmstrip: React.FC<FilmstripProps> = ({ files, activeIndex, onSelect, lab
       )}
     </div>
   )
-}
+})
 
 // ─── FileViewer (shell) ───────────────────────────────────────────────────────
 
@@ -669,7 +706,7 @@ export interface FileViewerLabels {
   descriptionPlaceholderEdit?: string
   /** Detail section — file info section heading */
   fileInfoHeading?: string
-  /** Filmstrip tablist ARIA label */
+  /** Filmstrip group ARIA label（role="group" + thumb button + aria-current,非 tablist）*/
   filmstripLabel?: string
   /** Previous-file nav button ARIA label */
   previousFile?: string
@@ -699,7 +736,7 @@ const DEFAULT_LABELS: Required<FileViewerLabels> = {
 export interface FileViewerProps
   extends Omit<
     React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content>,
-    'onOpenChange'
+    'onOpenChange' | 'tabIndex'
   > {
   files: FileInfo[]
   initialIndex?: number
@@ -728,7 +765,7 @@ export interface FileViewerProps
 const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function FileViewer({
   files,
   initialIndex = 0,
-  open,
+  open: openProp,
   defaultOpen,
   onOpenChange,
   index: indexProp,
@@ -739,12 +776,35 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
   allowDownload = true,
   onDownload,
   labels: labelsOverride,
+  className,
+  onOpenAutoFocus,
   ...props
 }, ref) {
   const labels = React.useMemo(
     () => ({ ...DEFAULT_LABELS, ...labelsOverride }) satisfies Required<FileViewerLabels>,
     [labelsOverride],
   )
+  // Open:受控/非受控雙模式鏡像(消費 DS useControllable;select-menu.tsx 2026-06-11 同修先例)。
+  // 原本 keyboard shortcuts effect 與 index-reset effect 直接讀 `open` prop ——
+  // uncontrolled(defaultOpen)場景 open === undefined,兩 effect 永遠不啟動(快捷鍵全失效
+  // + 重開不重置 index),Toolbar X / backdrop click 的 onOpenChange?.(false) 也是 no-op。
+  // 鏡像後 effect / close 都走 mirror:controlled 時純 passthrough,
+  // uncontrolled 時 internal state 為準 + onOpenChange 僅通知。
+  const [open, setOpen] = useControllable<boolean>({
+    value: openProp,
+    defaultValue: defaultOpen ?? false,
+    onChange: onOpenChange,
+  })
+  const contentRef = React.useRef<HTMLDivElement | null>(null)
+  const setContentRef = React.useCallback(
+    (node: HTMLDivElement | null) => {
+      contentRef.current = node
+      if (typeof ref === 'function') ref(node)
+      else if (ref) ref.current = node
+    },
+    [ref],
+  )
+
   // Index:uncontrolled fallback
   const [internalIndex, setInternalIndex] = React.useState(initialIndex)
   const activeIndex = indexProp ?? internalIndex
@@ -767,6 +827,10 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
 
   // Info panel open state(shell own)
   const [infoOpen, setInfoOpen] = React.useState(false)
+  // 2026-07-06 D3 perf:抽 useCallback 穩定 identity——InfoPanel 上了 React.memo(見上),
+  // inline arrow 每 render 新 identity 會打穿 memo shallow-compare。
+  const handleInfoToggle = React.useCallback(() => setInfoOpen((o) => !o), [])
+  const handleInfoClose = React.useCallback(() => setInfoOpen(false), [])
 
   // Zoom state(shell own,renderer 消費 + 回報)
   const [zoom, setZoom] = React.useState(100)
@@ -876,8 +940,10 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
   const showFilmstripResolved = showFilmstrip && files.length > 1
   const showArrows = files.length > 1
 
+  // Root 永遠餵 mirror(Radix 視角 controlled);uncontrolled 的 defaultOpen 由
+  // useControllable internal state 承載,Radix Esc / dismiss 經 setOpen 同步回 mirror。
   return (
-    <DialogPrimitive.Root open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
+    <DialogPrimitive.Root open={open} onOpenChange={setOpen}>
       <DialogPrimitive.Portal>
         {/* Overlay — FileViewer 固定深色氛圍,與 Dialog 共用 bg-overlay。
             **data-theme="dark"**(2026-04-30):Overlay 在 Portal 內、是 Content 的 sibling,
@@ -888,21 +954,33 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
           data-theme="dark"
           className={cn(
             'fixed inset-0 z-50 bg-overlay',
+            surfaceMotion,
             'data-[state=open]:animate-in data-[state=closed]:animate-out',
             'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
           )}
         />
         <DialogPrimitive.Content
-          ref={ref}
+          ref={setContentRef}
+          {...props}
+          tabIndex={-1}
           className={cn(
             // Edge-to-edge fullscreen,無 inset / 無 radius(與一般 Dialog 差別的所在)
             'fixed inset-0 z-50 outline-none',
+            surfaceMotion,
             'data-[state=open]:animate-in data-[state=closed]:animate-out',
             'data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0',
+            'data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95',
+            className,
           )}
-          // 避免 Radix 自動把焦點送進 Content 的第一個 tabbable —— 我們要留給 viewport
-          onOpenAutoFocus={(e) => e.preventDefault()}
-          {...props}
+          // FileViewer 是 fullscreen content-consumption dialog：開啟即把焦點放到 shell，
+          // 讓 Radix FocusScope 立即接管、但不誤觸第一個 toolbar control/Tooltip。
+          // Consumer handler 可先取消；未取消時由本元件阻止 Radix default 並聚焦 Content。
+          onOpenAutoFocus={(event) => {
+            onOpenAutoFocus?.(event)
+            if (event.defaultPrevented) return
+            event.preventDefault()
+            contentRef.current?.focus({ preventScroll: true })
+          }}
         >
           {/* 鎖 dark subtree。Density 繼承 page(不另設 data-density)。
               header 高度透過 `--chrome-header-height` 自動 density-aware(md=48 / lg=56)。
@@ -930,10 +1008,10 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
               onZoomChange={setZoom}
               onFit={handleFit}
               infoOpen={infoOpen}
-              onInfoToggle={() => setInfoOpen((o) => !o)}
+              onInfoToggle={handleInfoToggle}
               onDownload={handleDownload}
               allowDownload={allowDownload}
-              onClose={() => onOpenChange?.(false)}
+              onClose={() => setOpen(false)}
               labels={labels}
             />
 
@@ -962,15 +1040,15 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
                     const r = img.getBoundingClientRect()
                     if (e.clientX >= r.left && e.clientX <= r.right && e.clientY >= r.top && e.clientY <= r.bottom) return
                   }
-                  // 否則 = 點到 backdrop(image-renderer TransformComponent 透出的 bg-canvas)→ close
-                  onOpenChange?.(false)
+                  // 否則 = 點到 backdrop(outer 不設 bg,半透明 bg-overlay 透出 — 見 Q1 註解)→ close
+                  setOpen(false)
                 }}
               >
                 {showArrows && activeIndex > 0 && (
                   <div
                     className={cn(
                       'absolute left-[var(--layout-space-loose)] top-1/2 -translate-y-1/2 z-10',
-                      'transition-opacity duration-150',
+                      'transition-opacity duration-150 motion-reduce:duration-0',
                       // armVisible state 控制,或 focus-within 時 a11y 強制顯示
                       armVisible ? 'opacity-100' : 'opacity-0 pointer-events-none',
                       'focus-within:opacity-100 focus-within:pointer-events-auto',
@@ -987,19 +1065,24 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
                   </div>
                 )}
                 <div className="w-full h-full">
-                  <Renderer.component
-                    file={file}
-                    zoom={zoom}
-                    onZoomChange={setZoom}
-                    fitRequest={fitRequest}
-                    onCapabilitiesChange={setCapabilities}
-                  />
+                  {/* Suspense 兜 React.lazy renderer(ImageRenderer)chunk 載入。fallback=null
+                      = 既有 loading 行為——spec「Loading」段:shell 不提供全頁 loading state,
+                      loading 由 renderer 自理;chunk 載入期間的空 viewport 與 <img> 載入期間視覺一致。 */}
+                  <React.Suspense fallback={null}>
+                    <Renderer.component
+                      file={file}
+                      zoom={zoom}
+                      onZoomChange={setZoom}
+                      fitRequest={fitRequest}
+                      onCapabilitiesChange={setCapabilities}
+                    />
+                  </React.Suspense>
                 </div>
                 {showArrows && activeIndex < files.length - 1 && (
                   <div
                     className={cn(
                       'absolute right-[var(--layout-space-loose)] top-1/2 -translate-y-1/2 z-10',
-                      'transition-opacity duration-150',
+                      'transition-opacity duration-150 motion-reduce:duration-0',
                       armVisible ? 'opacity-100' : 'opacity-0 pointer-events-none',
                       'focus-within:opacity-100 focus-within:pointer-events-auto',
                     )}
@@ -1020,7 +1103,7 @@ const FileViewer = React.forwardRef<HTMLDivElement, FileViewerProps>(function Fi
                   file={file}
                   readOnly={readOnly}
                   onDescriptionChange={onDescriptionChange}
-                  onClose={() => setInfoOpen(false)}
+                  onClose={handleInfoClose}
                   labels={labels}
                 />
               )}
@@ -1053,9 +1136,11 @@ export const fileViewerMeta = {
   sizes: {
 
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = 縮圖列當前頁持續選中(bg-neutral-selected);'active' 移除 — 全檔無按壓視覺
+  // (工具列按壓屬內嵌 Button meta;2026-07-07 詞彙統一 DS-wide 交叉掃補修)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-muted', 'bg-surface', 'bg-surface-raised'],
+    bg: ['bg-muted', 'bg-neutral-selected', 'bg-overlay', 'bg-surface-raised'],
     fg: ['text-fg-muted', 'text-foreground'],
     ring: ['ring-primary', 'ring-ring'],
   },

package/src/components/FileViewer/image-renderer.tsx

@@ -4,6 +4,7 @@ import {
   TransformWrapper,
   TransformComponent,
   type ReactZoomPanPinchRef,
+  type ReactZoomPanPinchContentRef,
 } from 'react-zoom-pan-pinch'
 import type { FileRendererProps } from './file-viewer-types'
 
@@ -41,7 +42,7 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
   fitRequest,
   onCapabilitiesChange,
 }) => {
-  const apiRef = React.useRef<ReactZoomPanPinchRef | null>(null)
+  const apiRef = React.useRef<ReactZoomPanPinchContentRef | null>(null)
   const imgRef = React.useRef<HTMLImageElement | null>(null)
   const containerRef = React.useRef<HTMLDivElement | null>(null)
   const [loaded, setLoaded] = React.useState(false)
@@ -123,12 +124,38 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
     const container = containerRef.current
     if (!container) return
     let rafId = 0
+    // manual mode 視覺中心保持需要前次容器尺寸(比對 delta 反推新 position)
+    let prevW = container.clientWidth
+    let prevH = container.clientHeight
     const obs = new ResizeObserver(() => {
       if (rafId) cancelAnimationFrame(rafId)
       rafId = requestAnimationFrame(() => {
         rafId = 0
         const mode = lastFitModeRef.current
-        if (mode === 'manual') return
+        const newW = container.clientWidth
+        const newH = container.clientHeight
+        if (mode === 'manual') {
+          // 2026-07-08 Q2 補洞(user「畫布在各種情況都能完美適應」):manual zoom 下容器 resize
+          //(InfoPanel 開合 / Filmstrip 增減 / 視窗 RWD / 裝置旋轉 — 同一咽喉點全涵蓋)
+          // = **scale 不變、視覺中心點保持**(Figma / Photoshop canonical;原本 early-return
+          // 什麼都不做 → transform 座標絕對值,容器變窄內容偏移)。
+          // 幾何:舊容器中心對到的內容點 (cx,cy),resize 後把同一內容點放到新容器中心。
+          const api = apiRef.current
+          if (api && (newW !== prevW || newH !== prevH)) {
+            const { positionX, positionY, scale } = api.state
+            const cx = (prevW / 2 - positionX) / scale
+            const cy = (prevH / 2 - positionY) / scale
+            programmaticZoomRef.current = true
+            api.setTransform(newW / 2 - cx * scale, newH / 2 - cy * scale, scale, 0)
+            // setTransform 同步無動畫;下一 frame 解 flag(防 onTransform 誤標 manual→已是 manual,保守處理)
+            requestAnimationFrame(() => { programmaticZoomRef.current = false })
+          }
+          prevW = newW
+          prevH = newH
+          return
+        }
+        prevW = newW
+        prevH = newH
         const scale = computeFitScale(mode)
         if (scale == null) return
         onZoomChange(clampToPct(scale))
@@ -196,8 +223,8 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
   return (
     <div ref={containerRef} className="w-full h-full overflow-hidden" onDoubleClick={handleDoubleClick}>
       <TransformWrapper
-        // any-allow: react-zoom-pan-pinch TransformWrapper ref type not exported; API surface stable per lib docs
-        ref={apiRef as any}
+        // TransformWrapper ref = ReactZoomPanPinchContentRef(dist/index.d.ts:351 + export L399);型別有 export → 用真型別,不需 as any
+        ref={apiRef}
         initialScale={1}
         minScale={MIN_SCALE}
         maxScale={MAX_SCALE}
@@ -211,9 +238,10 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
         // Wheel zoom canonical:
         // - `step: 0.03` = 每 tick ~3% scale,對齊 Figma / Preview.app 細緻度
         //   (原 0.1 = 10% 太粗,接近 Google Slides 離散慣例)
-        // - multiplicative 等距:library 內部 scale factor 乘算,log 視覺等距
-        // 註:原本用 `smoothStep: 0.005` 但當前 lib type 不含該 key;若需 trackpad 細緻,
-        // 升級 react-zoom-pan-pinch 到有此 prop 的版本或切到 `smoothScroll` API
+        // - wheel zoom = `scale + delta × step` 加法線性(handleCalculateWheelZoom,
+        //   dist/index.esm.js:1265;非 multiplicative/log —— 乘算 exp 只用於 setup smooth 的按鈕 zoom path)
+        // 註:lib 型別無 `smoothStep` / `smoothScroll` key(僅 setup `smooth?:boolean` 走按鈕 exp、
+        // 不影響 wheel);trackpad 平滑度目前無對應 wheel prop 可調
         wheel={{ step: 0.03 }}
         // Q3 雙擊改自定 handler:lib `mode: 'reset'` 永遠 reset 到 initialScale=1 → 100%,
         // 失去 fit ↔ 100% toggle UX(Apple Photos / Drive canonical)。disabled lib 預設 + 自定 onDoubleClick。
@@ -246,11 +274,6 @@ export const ImageRenderer: React.FC<FileRendererProps> = ({
 }
 ImageRenderer.displayName = 'ImageRenderer'
 
-const IMAGE_EXTS = new Set(['jpg', 'jpeg', 'png', 'gif', 'webp', 'svg', 'avif', 'bmp', 'ico'])
-
-/** 判斷檔案是否可用 ImageRenderer 渲染。 */
-export function canRenderImage(file: { mimeType: string; name: string }): boolean {
-  if (file.mimeType.startsWith('image/')) return true
-  const ext = file.name.split('.').pop()?.toLowerCase()
-  return ext ? IMAGE_EXTS.has(ext) : false
-}
+// canRenderImage 已拆至 ./can-render-image(2026-07-06 D3 bundle fix)——
+// shell 需同步呼叫它,而本檔頂層 import react-zoom-pan-pinch;留在本檔會把整個 lib
+// 拉進 shell 的靜態 import graph,React.lazy 切分就失效。

package/src/components/FileViewer/index.ts

@@ -0,0 +1,5 @@
+// AUTO-GENERATED by scripts/gen-component-indexes.mjs — DO NOT EDIT MANUALLY.
+// Re-export pattern enables package.json exports map subpath:
+//   import { ... } from '@qijenchen/design-system/{components,patterns}/<Dir>'
+// Regenerate: node scripts/gen-component-indexes.mjs
+export * from './file-viewer'