@qijenchen/design-system 0.1.0-beta.3

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

@@ -0,0 +1,256 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import * as React from 'react'
+import {
+  TransformWrapper,
+  TransformComponent,
+  type ReactZoomPanPinchRef,
+} from 'react-zoom-pan-pinch'
+import type { FileRendererProps } from './file-viewer-types'
+
+/**
+ * ImageRenderer — FileViewer 的圖片 renderer。
+ *
+ * ── 世界級 zoom semantic canonical(2026-04-21 重寫)──
+ * Figma / Preview.app / Adobe Acrobat / Google Drive 共通:
+ *   - `100%` = image natural pixel size(**非** CSS contain-scaled)
+ *   - 開圖預設 fit-to-page(image 自動 fit,zoom input 顯示 fit % 如 40%)
+ *   - `fit-to-width` = image width 填滿 container width(portrait 會 overflow 垂直)
+ *   - `fit-to-page` = image 完整可見(contain semantic)
+ *   - `+/-` preset 改 zoom 對應 natural 倍率,精準
+ *
+ * ── 實作細節 ──
+ * image 不走 CSS `object-contain`(那會 pre-scale,導致 transform.scale 解讀錯誤);
+ * 改走 **natural size + transform scale 管實際顯示**。onLoad 時算 fit-page scale
+ * 再 `onZoomChange(fitPct)` 將 UI zoom 同步到真實倍率。
+ *
+ * ── 為什麼消費 react-zoom-pan-pinch ──
+ * Zoom + pan 是行為 primitive;自寫 pinch / wheel 踩大量 edge case
+ * (trackpad vs mouse / momentum / bounds),library 是 canonical 解法
+ * (世界級 Figma Community / Miro embed / PhotoSwipe 同類流派)。
+ */
+
+const MIN_SCALE = 0.1 // 10%
+const MAX_SCALE = 4.0 // 400%
+
+type FitMode = 'fit-width' | 'fit-page'
+
+export const ImageRenderer: React.FC<FileRendererProps> = ({
+  file,
+  zoom,
+  onZoomChange,
+  fitRequest,
+  onCapabilitiesChange,
+}) => {
+  const apiRef = React.useRef<ReactZoomPanPinchRef | null>(null)
+  const imgRef = React.useRef<HTMLImageElement | null>(null)
+  const containerRef = React.useRef<HTMLDivElement | null>(null)
+  const [loaded, setLoaded] = React.useState(false)
+  // 2026-05-16 Round 5 codex audit fix:capture image-load rAF ID + cancel on unmount
+  // (原 uncancelled rAF 可能 unmount 後 fire onZoomChange → setState 後 component 已 gone)
+  const handleImageLoadRafIdRef = React.useRef<number>(0)
+  React.useEffect(() => () => { if (handleImageLoadRafIdRef.current) cancelAnimationFrame(handleImageLoadRafIdRef.current) }, [])
+  // Q2 RWD:track「user 最後一次的 zoom 意圖」— fit-page / fit-width 自動 reflow,manual 不動。
+  // 對齊 Apple Photos / Drive canonical:resize 時若 user 在 fit mode → recompute,manual zoom → 維持。
+  const lastFitModeRef = React.useRef<FitMode | 'manual'>('fit-page')
+  // 區分「user wheel/pinch」vs「programmatic centerView」— lib onTransform 兩者都觸發,
+  // 用 flag 防 programmatic 的 onTransform 誤標 mode = manual。
+  const programmaticZoomRef = React.useRef(false)
+
+  // 宣告 capability — shell 用此決定 toolbar 內容。
+  React.useEffect(() => {
+    onCapabilitiesChange({ zoom: true })
+  }, [onCapabilitiesChange])
+
+  // file.url 切換 → reset state,等 onLoad 重 fit。
+  // 原本 bug:cache 命中時 onLoad 不 fire → handleImageLoad 不跑 → zoom 卡上一張的值
+  // (或 shell 設的 100%)→ user 看到「同一張圖每次切過來尺寸不一致」。
+  React.useEffect(() => {
+    setLoaded(false)
+    lastFitModeRef.current = 'fit-page'
+    // cache 命中(<img complete>)→ onLoad 可能不 fire,直接觸發 handleImageLoad 邏輯
+    const img = imgRef.current
+    if (img && img.complete && img.naturalWidth > 0) {
+      // 等下一個 microtask,確保 ref / state 都到位
+      Promise.resolve().then(() => handleImageLoad())
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [file.url])
+
+  // 算 fit scale(container 寬高 / image natural 寬高)
+  const computeFitScale = React.useCallback((fit: FitMode): number | null => {
+    const img = imgRef.current
+    const container = containerRef.current
+    if (!img || !container) return null
+    if (!img.naturalWidth || !img.naturalHeight) return null
+    const cw = container.clientWidth
+    const ch = container.clientHeight
+    if (cw <= 0 || ch <= 0) return null
+    const widthRatio = cw / img.naturalWidth
+    const heightRatio = ch / img.naturalHeight
+    // fit-width = 寬填滿;fit-page = 完整可見(取較小 scale)
+    return fit === 'fit-width' ? widthRatio : Math.min(widthRatio, heightRatio)
+  }, [])
+
+  const clampToPct = React.useCallback((scale: number): number => {
+    const clamped = Math.min(MAX_SCALE, Math.max(MIN_SCALE, scale))
+    // Floor 而非 round:fit-to-page / fit-to-width 時 scale 是 float(e.g. 0.8356)。
+    // round(0.8356 * 100) = 84 → 實際 scale 0.84 → image 比 canvas 大 4px,垂直溢出破壞
+    // 對稱置中(user 抓:「上下邊距不對稱」)。Floor → 0.83 → image 比 canvas 小,永遠
+    // 完整可見 + 視覺 symmetric padding。代價是最多 ~1% 的空間餘量,視覺幾乎看不出。
+    return Math.floor(clamped * 100)
+  }, [])
+
+  // Image onLoad → 自動 fit-to-page(世界級開圖預設)
+  const handleImageLoad = React.useCallback(() => {
+    setLoaded(true)
+    const scale = computeFitScale('fit-page')
+    if (scale == null) return
+    const pct = clampToPct(scale)
+    lastFitModeRef.current = 'fit-page'
+    // 等 transform 就緒再更新(避免 initialScale=1 → fit 過程跳兩段)
+    if (handleImageLoadRafIdRef.current) cancelAnimationFrame(handleImageLoadRafIdRef.current)
+    handleImageLoadRafIdRef.current = requestAnimationFrame(() => {
+      handleImageLoadRafIdRef.current = 0
+      onZoomChange(pct)
+    })
+  }, [computeFitScale, clampToPct, onZoomChange])
+
+  // Q2 RWD:container resize 時若在 fit mode 重算 — 對齊 Apple Photos / Drive canonical
+  // rAF debounce:drag window edge 期間 ResizeObserver 連續 fire 數十次,
+  // 合併到下一 frame 只觸發一次 → 避免 race / 過多 centerView animation 互相打斷。
+  React.useEffect(() => {
+    if (!loaded) return
+    const container = containerRef.current
+    if (!container) return
+    let rafId = 0
+    const obs = new ResizeObserver(() => {
+      if (rafId) cancelAnimationFrame(rafId)
+      rafId = requestAnimationFrame(() => {
+        rafId = 0
+        const mode = lastFitModeRef.current
+        if (mode === 'manual') return
+        const scale = computeFitScale(mode)
+        if (scale == null) return
+        onZoomChange(clampToPct(scale))
+      })
+    })
+    obs.observe(container)
+    return () => {
+      obs.disconnect()
+      if (rafId) cancelAnimationFrame(rafId)
+    }
+  }, [loaded, computeFitScale, clampToPct, onZoomChange])
+
+  // Q3 雙擊 toggle fit ↔ 100%(對齊 Apple Photos / Preview.app / Imgur / PhotoSwipe canonical)
+  const handleDoubleClick = React.useCallback(() => {
+    if (!loaded) return
+    const fitScale = computeFitScale('fit-page')
+    if (fitScale == null) return
+    const fitPct = clampToPct(fitScale)
+    // 在 fit-page 附近(±5pt)→ 跳 100% natural;否則 → 回 fit-page
+    const atFit = Math.abs(zoom - fitPct) < 5
+    const targetPct = atFit ? 100 : fitPct
+    lastFitModeRef.current = atFit ? 'manual' : 'fit-page'  // 跳 100% = manual,回 fit = fit mode
+    onZoomChange(targetPct)
+  }, [loaded, zoom, computeFitScale, clampToPct, onZoomChange])
+
+  // 外部 zoom 變動(preset / ± / 打字 / fit request)→ centerView 重定位
+  // library canonical `centerView` 同時處理 scale + 置中 + animation + bounds。
+  React.useEffect(() => {
+    const api = apiRef.current
+    if (!api || !loaded) return
+    const currentScale = api.state.scale
+    const targetScale = zoom / 100
+    if (Math.abs(currentScale - targetScale) < 0.005) return
+    // 標記 programmatic — onTransform 期間不要被誤標 manual mode
+    programmaticZoomRef.current = true
+    api.centerView(targetScale, 200)
+    // 動畫 ~200ms + buffer 後解 flag
+    const t = setTimeout(() => { programmaticZoomRef.current = false }, 280)
+    return () => clearTimeout(t)
+  }, [zoom, loaded])
+
+  // Fit request(toolbar 菜單點 fit-width / fit-page)→ 算 scale emit 回 shell
+  React.useEffect(() => {
+    if (!fitRequest || !loaded) return
+    const scale = computeFitScale(fitRequest.fit)
+    if (scale == null) return
+    lastFitModeRef.current = fitRequest.fit  // 記 fit mode 給 ResizeObserver 用
+    onZoomChange(clampToPct(scale))
+  }, [fitRequest, loaded, computeFitScale, clampToPct, onZoomChange])
+
+  // 內部 wheel / pinch zoom → 同步回 shell + 標記為 manual mode(打破 fit auto-reflow)
+  // programmatic centerView 期間 lib 也會 fire onTransform → 用 flag 跳過,避免誤標 manual。
+  const handleTransformed = React.useCallback(
+    (_ref: ReactZoomPanPinchRef, state: { scale: number }) => {
+      if (programmaticZoomRef.current) return  // programmatic update,不標 manual
+      const nextZoom = Math.round(state.scale * 100)
+      if (nextZoom !== zoom) {
+        lastFitModeRef.current = 'manual'
+        onZoomChange(nextZoom)
+      }
+    },
+    [zoom, onZoomChange],
+  )
+
+  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}
+        initialScale={1}
+        minScale={MIN_SCALE}
+        maxScale={MAX_SCALE}
+        centerOnInit
+        centerZoomedOut
+        // Teams 對標(2026-04-23):image viewer 走 chat-app lightbox 慣例 —
+        // drag 時 image 保持在 canvas bounds 內(zoom-fit 時 drag 無意義,zoom-in 時 drag pan 有限制)。
+        // `limitToBounds=true` 跟 Microsoft Teams / Slack / iOS Photos 等 chat-lightbox 互動一致,
+        // 避免 Figma-canvas 式「可 drag 到任意位置」的無界體驗混淆 viewer 語境。
+        limitToBounds={true}
+        // 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={{ step: 0.03 }}
+        // Q3 雙擊改自定 handler:lib `mode: 'reset'` 永遠 reset 到 initialScale=1 → 100%,
+        // 失去 fit ↔ 100% toggle UX(Apple Photos / Drive canonical)。disabled lib 預設 + 自定 onDoubleClick。
+        doubleClick={{ disabled: true }}
+        onTransform={handleTransformed}
+      >
+        {/* 2026-04-23 debug fix:contentClass 不設 `!w-full !h-full`。
+            設 `!w-full !h-full` 會讓 `.react-transform-component` 強制 1280×752 容器尺寸,
+            但 image 是 natural 1440×900(自然溢出 container)。Library `centerView(scale)`
+            基於 component 尺寸計算 translate → 計算偏 61px(視 image 被 WRAPPER 框住而非
+            自然 size)。
+            移除 content fixed size 後:component 自然 size = image natural → library 以
+            image 實際尺寸計算置中,translate 正確(42.4, 2.5)得到 symmetric padding。
+            wrapper 保留 `!w-full !h-full` 作 interaction capture bounds。 */}
+        <TransformComponent wrapperClass="!w-full !h-full">
+          <img
+            ref={imgRef}
+            src={file.url}
+            alt={file.name}
+            onLoad={handleImageLoad}
+            draggable={false}
+            // natural size(**不走 object-contain**)— transform scale 管實際顯示大小
+            className="max-w-none max-h-none select-none"
+            style={{ pointerEvents: 'none' }}
+          />
+        </TransformComponent>
+      </TransformWrapper>
+    </div>
+  )
+}
+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
+}

package/src/components/HoverCard/hover-card.tsx

@@ -0,0 +1,79 @@
+import * as React from "react"
+import * as HoverCardPrimitive from "@radix-ui/react-hover-card"
+
+import { cn } from "@/lib/utils"
+import { OVERLAY_SIDE_OFFSET } from "@/design-system/tokens/elevation/overlay-geometry"
+
+/**
+ * HoverCard — hover 顯示可互動內容的浮層（行為 primitive）
+ *
+ * 跟 Tooltip 的差異：內容可互動（按鈕、連結、hover 子元素）。
+ *
+ * **不含視覺樣式**——bg、border、shadow、padding 由 consumer 決定：
+ * - OverflowIndicator：深色 Tooltip 樣式（bg-tooltip + data-theme="dark"）
+ * - NameCard：亮色 Card 樣式（bg-surface-raised + elevation-200）
+ *
+ * 只提供：z-index、動畫、sideOffset。
+ */
+
+const HoverCard = HoverCardPrimitive.Root
+
+const HoverCardTrigger = HoverCardPrimitive.Trigger
+
+const HoverCardContent = React.forwardRef<
+  React.ElementRef<typeof HoverCardPrimitive.Content>,
+  React.ComponentPropsWithoutRef<typeof HoverCardPrimitive.Content>
+>(({ className, align = "center", sideOffset = OVERLAY_SIDE_OFFSET, collisionPadding = 12, ...props }, ref) => (
+  // HoverCardPrimitive.Portal(2026-04-23):把 Content 搬到 `document.body`。
+  // 不 Portal 時 Content 會 DOM-nested 在 trigger subtree,如 trigger 位於 OverflowIndicator
+  // `data-theme="dark"` tooltip 內部 → Avatar 自帶 HoverCard 的 Content 也卡在 dark subtree,
+  // CSS var(--foreground) 繼承 dark 值 → NameCard 內部文字變 white 看不見(user 抓的 bug)。
+  // Portal 到 body 讓 CSS 繼承 chain 從 app root data-theme 起算,不受 trigger subtree 污染。
+  //
+  // collisionPadding=12:Radix / browser 內部 1-2px rounding 讓 visual padding 比 prop 值少 1-2px。
+  // 提高到 12 保證使用者實際看到 ≥ 8px viewport edge gap(overlay-surface「靠邊 8px」canonical)。
+  <HoverCardPrimitive.Portal>
+    <HoverCardPrimitive.Content
+      ref={ref}
+      align={align}
+      sideOffset={sideOffset}
+      collisionPadding={collisionPadding}
+      className={cn(
+        "z-50 outline-none",
+        // 2026-05-04 viewport-aware max-h SSOT(對齊 Popover):header/footer 永遠 in-viewport,body 壓縮 scroll
+        // 2026-05-05 audit dim 35 fix:加 `min-h-0` 完成 M25 chain invariant
+        "max-h-[var(--radix-hover-card-content-available-height,100vh)] flex flex-col overflow-hidden min-h-0",
+        "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",
+        "data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2",
+        "data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2",
+        "origin-[var(--radix-hover-card-content-transform-origin)]",
+        className,
+      )}
+      {...props}
+    />
+  </HoverCardPrimitive.Portal>
+))
+HoverCardContent.displayName = HoverCardPrimitive.Content.displayName
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const hoverCardMeta = {
+  component: 'HoverCard',
+  family: null, // non-family composite / overlay / layout
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-surface-raised'],
+    fg: ['--foreground'],
+    ring: [],
+  },
+} as const
+
+export { HoverCard, HoverCardTrigger, HoverCardContent }

package/src/components/Input/input.tsx

@@ -0,0 +1,233 @@
+// @benchmark-unverified-blanket: file-level retraction per M22 (d) — claims herein not individually URL-cited; treat as unverified visual/usage rumor unless retrofit per-claim. Hook escape preserved.
+import * as React from 'react'
+import { type VariantProps } from 'class-variance-authority'
+import type { LucideIcon } from 'lucide-react'
+import { cn } from '@/lib/utils'
+import type { FieldMode, FieldVariant } from '@/design-system/components/Field/field-types'
+import { fieldWrapperStyles, bareInputStyles, EMPTY_DISPLAY } from '@/design-system/components/Field/field-wrapper'
+import { useFieldContext } from '@/design-system/components/Field/field-context'
+import { ItemInlineAction, ItemPrefix, type InlineActionConfig } from '@/design-system/patterns/element-anatomy/item-anatomy'
+import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
+import { ICON_SIZE } from '@/design-system/tokens/uiSize/icon-size'
+
+// ── Types ───────────────────────────────────────────────────────────────────
+
+export interface InputProps
+  extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'>,
+    Omit<VariantProps<typeof fieldWrapperStyles>, 'mode' | 'variant'> {
+  /** Field display mode */
+  mode?: FieldMode
+  /**
+   * Visual chrome(正交於 mode);Phase B1(2026-05-05)從 `variant` 改名 `chrome`,對齊 FieldContext.variant 透傳。
+   * - `'default'`(預設)— Field wrapper 完整 variant:bg-surface + 明顯 border + hover/focus 回饋。適用表單、Field 內嵌。
+   * - `'bare'` — 透明 variant,hover / focus 才出現 border。適用 Toolbar inline editing(如 FileViewer zoom input / chart config toolbar / rich text toolbar number input)+ DataTable cell-as-input。保留 padding / typography / height,只拿掉背景和常態 border。
+   *
+   * 透傳:在 `<Field variant="bare">` 內自動繼承 context.variant;per-prop override context。
+   * 世界級對照(bare):VS Code settings input / Figma toolbar number / Notion prop input。
+   */
+  variant?: FieldVariant
+  /** Error 狀態（正交於 mode）。border-error + aria-invalid。 */
+  error?: boolean
+  /** 左側靜態 icon — 輔助理解 input 用途（如 Search）。fg-muted。 */
+  startIcon?: LucideIcon
+  /** 右側 inline action — 宣告式 API，Field 根據 size 自動渲染。 */
+  endAction?: InlineActionConfig
+  /**
+   * 右側 slot(ReactNode)— escape hatch 供 consumer 放自訂元素(如 DropdownMenuTrigger asChild + ItemInlineActionButton)。
+   * 跟 `endAction` 互斥(同時傳 endSlot 會優先,endAction 被忽略)。
+   *
+   * **使用情境**:ZoomInput 需要 chevron 作 DropdownMenuTrigger anchor,config-only API 無法做到。
+   * **禁止情境**:表單欄位 / 一般 inline action → 用 `endAction` 宣告式 API。
+   */
+  endSlot?: React.ReactNode
+  /**
+   * Loading 狀態(async 驗證 / debounce fetch 中)。
+   * - **input 保持可編輯**(user 可以邊改邊讀,debounce 場景 UX 最好)
+   * - 世界級對照:Ant Input.Search 派(input editable during loading);非 Material readonly 派
+   * - 自動在 endAction slot 塞 `<CircularProgress size={iconSize}/>`(與 endAction prop 互斥)
+   * - 宣告 `aria-busy="true"` 讓 screen reader 感知處理中
+   */
+  loading?: boolean
+  /**
+   * Auto-width:Input 寬度 = 內容寬(value / placeholder 文字寬)+ startIcon + endAction + padding。
+   * 使用 CSS `field-sizing: content`(Chrome 123+ / Safari 17.4+;Firefox 還在實驗)。
+   *
+   * **使用情境**:
+   * - Inline edit(VS Code setting row / Figma property toolbar number input)
+   * - ZoomInput(FileViewer 縮放比例:輸入「100%」自動縮到三位數寬)
+   * - Tag / Chip 內 inline rename
+   *
+   * **不要用在**:表單 Field(Field 需要欄寬對齊,不該隨值跳動)
+   *
+   * **fallback**:不支援 `field-sizing` 的瀏覽器會退化為 `w-auto`(wrapper 縮到 content 尺寸,
+   * input 本身有 min-width 避免消失)。UX 上稍不一致但不致斷;若必須精準對齊所有瀏覽器,
+   * consumer 可自行傳 `style={{ width: ... }}` 顯式寬度,不走 auto。
+   */
+  autoWidth?: boolean
+}
+
+// ── Component ───────────────────────────────────────────────────────────────
+
+// code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
+const Input = React.forwardRef<HTMLInputElement, InputProps>(
+  (
+    {
+      mode: modeProp,
+      variant: variantProp,
+      error = false,
+      size,
+      startIcon: StartIcon,
+      endAction,
+      endSlot,
+      loading = false,
+      autoWidth = false,
+      className,
+      disabled,
+      readOnly,
+      value,
+      id: idProp,
+      'aria-describedby': ariaDescribedByProp,
+      'aria-errormessage': ariaErrorMessageProp,
+      ...props
+    },
+    ref
+  ) => {
+    // ── FieldContext 自動讀取(在 <Field> 內時,invalid / disabled / mode / chrome 由 context 接管) ──
+    const fieldCtx = useFieldContext()
+    // chrome 透傳:per-prop override context;context 沒值則 'default'
+    const variant: FieldVariant = variantProp ?? fieldCtx?.variant ?? 'default'
+    // mode resolve order(Phase B1 2026-05-05):
+    //   prop > fieldCtx.mode > (readOnly → 'readonly') > (disabled → 'disabled') > 'edit'
+    // loading 期間 input 保持可編輯(Ant Input.Search 派,UX「邊改邊讀」)
+    // 只用 aria-busy + endAction Spinner 標示狀態,不動 mode
+    const resolvedMode: FieldMode = modeProp
+      ?? fieldCtx?.mode
+      ?? (readOnly ? 'readonly' : disabled ? 'disabled' : 'edit')
+    const isEditable = resolvedMode === 'edit'
+    const isDisplay = resolvedMode === 'display'
+    // error 合併:自身 error prop OR Field context invalid
+    const resolvedError = error || (fieldCtx?.invalid ?? false)
+    // 2026-05-18 改 import ICON_SIZE SSOT(per user『做完』approval,消除 M17 違反 7+ 重複 ternary)
+  const iconSize = ICON_SIZE[size as 'sm' | 'md' | 'lg']
+    const iconColor = resolvedMode === 'disabled' ? 'text-fg-disabled' : 'text-fg-muted'
+
+    // ── display mode:純展示,渲染 <span> 取代 <input> ──
+    // 對齊 Carbon read-only / PatternFly inline-edit hidden-input / Cloudscape display-mode
+    if (isDisplay) {
+      const displayValue = value != null && value !== '' ? String(value) : null
+      return (
+        <div
+          className={cn(
+            fieldWrapperStyles({ mode: 'display', variant: variant, size }),
+            autoWidth && 'inline-flex w-auto',
+            className,
+          )}
+          data-field-mode="display"
+        >
+          {StartIcon && (
+            <ItemPrefix>
+              <StartIcon
+                size={iconSize}
+                className={cn('pointer-events-none', iconColor)}
+                aria-hidden
+              />
+            </ItemPrefix>
+          )}
+          <span
+            className={cn(
+              bareInputStyles,
+              // B1 fix(2026-05-05):display mode 單行 ellipsis 截斷(對齊 Notion / Airtable / Linear
+              //   cell display canonical:single-line value 過長 → ellipsis。Textarea display 走 wrap path,
+              //   不在此處;Input display 永遠 single-line。)
+              'truncate',
+              displayValue == null && 'text-fg-muted',
+            )}
+          >
+            {displayValue ?? EMPTY_DISPLAY}
+          </span>
+        </div>
+      )
+    }
+
+    return (
+      <div
+        className={cn(
+          fieldWrapperStyles({ mode: resolvedMode, variant: variant, size }),
+          isEditable && resolvedError && [
+            'border-error hover:border-error-hover',
+            'focus-within:border-error focus-within:hover:border-error',
+          ],
+          // autoWidth:wrapper 縮到 inline-flex + w-auto,讓寬度由 startIcon + input(field-sizing: content)+ endAction 自然累加
+          autoWidth && 'inline-flex w-auto',
+          className,
+        )}
+        data-field-mode={resolvedMode}
+        data-error={isEditable && resolvedError ? '' : undefined}
+        aria-busy={loading || undefined}
+      >
+        {StartIcon && (
+          <ItemPrefix>
+            <StartIcon
+              size={iconSize}
+              className={cn('pointer-events-none', iconColor)}
+              aria-hidden
+            />
+          </ItemPrefix>
+        )}
+        <input
+          ref={ref}
+          type="text"
+          id={idProp ?? fieldCtx?.id}
+          value={value as string | number | readonly string[] | undefined}
+          readOnly={resolvedMode === 'readonly'}
+          disabled={resolvedMode === 'disabled'}
+          aria-invalid={resolvedError || undefined}
+          aria-required={fieldCtx?.required || undefined}
+          aria-describedby={ariaDescribedByProp ?? fieldCtx?.descriptionId}
+          aria-errormessage={ariaErrorMessageProp ?? (resolvedError ? fieldCtx?.errorId : undefined)}
+          className={cn(
+            bareInputStyles,
+            resolvedMode === 'disabled' && 'text-fg-disabled placeholder:text-fg-disabled cursor-not-allowed',
+            // autoWidth:input 本身 field-sizing:content(Chrome 123+ / Safari 17.4+),寬度跟 value 文字寬。
+            // w-auto 關掉預設 w-full;min-w-0 讓 flex shrink 不卡住。
+            autoWidth && '[field-sizing:content] w-auto min-w-0',
+          )}
+          {...props}
+        />
+        {loading ? (
+          <CircularProgress size={iconSize} className="shrink-0" />
+        ) : endSlot && isEditable ? (
+          // endSlot escape hatch:consumer 自控右側 slot(如 DropdownMenuTrigger asChild wrap)
+          endSlot
+        ) : endAction && isEditable ? (
+          <ItemInlineAction action={endAction} size={size ?? 'md'} />
+        ) : null}
+      </div>
+    )
+  }
+)
+Input.displayName = 'Input'
+
+// Phase B1(2026-05-05):InputDisplay 退場。改用 `<Input mode="display" value={...} />`
+// 對齊 Carbon read-only / PatternFly inline-edit hidden-input / Cloudscape display-mode 統一 mode 模型。
+
+// Story auto-compile metadata — Phase 1 mechanical migration(2026-04-24)
+// Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
+export const inputMeta = {
+  component: 'Input',
+  family: 4,
+  variants: {
+
+  },
+  sizes: {
+
+  },
+  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  tokens: {
+    bg: ['bg-surface'],
+    fg: ['text-fg-disabled', 'text-fg-muted'],
+    ring: [],
+  },
+} as const
+
+export { Input }