@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

package/src/components/FileUpload/file-upload.tsx

@@ -4,8 +4,18 @@ import { Upload as UploadIcon, X } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import { Empty } from '@/design-system/components/Empty/empty'
 import { CircularProgress } from '@/design-system/components/CircularProgress/circular-progress'
-import { FileItem } from '@/design-system/components/FileItem/file-item'
+import { FileItem, FILE_ITEM_RING_LAYER_CLASS, fileItemRingCutoutStyle } from '@/design-system/components/FileItem/file-item'
 import { Button } from '@/design-system/components/Button/button'
+// 「列上有小按鈕的一串」鍵盤路線的唯一判定與執行(與 Sidebar / TreeView / Command 共用;見下方檔案清單鍵盤段)
+import {
+  ROVING_CONTROL_SELECTOR,
+  applyRovingAction,
+  isTextEntryElement,
+  listRovingControls,
+  pickRovingTabStop,
+  removeRovingControlsFromTabOrder,
+  resolveRovingKey,
+} from '@/design-system/lib/roving-list-keyboard'
 
 /**
  * FileUpload — 拖放 / 點擊上傳區塊
@@ -105,7 +115,8 @@ export interface FileUploadProps extends Omit<React.HTMLAttributes<HTMLDivElemen
 }
 
 function focusAfterFileRemoval(current: HTMLButtonElement) {
-  const list = current.closest('ul')
+  // 清單容器兩種元素都可能(唯讀 ul / 可操作 grid div,見下方 fileListNode),用資料屬性找
+  const list = current.closest<HTMLElement>('[data-file-upload-list]')
   const buttons = list ? Array.from(list.querySelectorAll<HTMLButtonElement>('[data-collection-remove]')) : []
   const index = buttons.indexOf(current)
   const next = buttons[index + 1] ?? buttons[index - 1]
@@ -113,6 +124,22 @@ function focusAfterFileRemoval(current: HTMLButtonElement) {
   ;(next ?? owner)?.focus()
 }
 
+// ── 鍵盤:內建檔案清單 = 一個 Tab 停靠點(2026-09-25 待辦總帳 B9「路線乙」)──
+// 決策出處 = governance/planning/2026-09-25-interaction-and-hover-remediation.md B9,user 逐字(附條件同意,條件查證成立記在同列):
+// 「確定建議符合我們一致的設計語言且不違背世界級的設計就照建議」。規則 SSOT = ds-canonical/references/keyboard-model-canonical.md
+// 「列上有小按鈕的一串」;本元件的按鍵表只住 file-upload.spec.md「A11y 預設 › 檔案清單鍵盤」;判定與執行 = lib/roving-list-keyboard.ts
+// (2026-09-26 與 Sidebar / TreeView / Command 四份合一,同檔〇節「按鍵規則合併」)。2026-09-25 前:每一列的「移除」鈕各佔一站(3 個檔案 = 3 站),沒有方向鍵。
+//
+// 實作取捨(AI 推導):
+//   - 列(role=row)的 0 / -1 由 React 管(列是本元件自己渲染的);列裡的按鈕一律 -1,但用 DOM 收 ——
+//     列裡除了本元件的移除鈕,還可能有 consumer 經 `description`(ReactNode)放進來的連結,React 管不到。
+//   - 只在有 `onRemove`(= 列上有本元件自己的按鈕)時才變成一站 + 方向鍵;沒有 onRemove 的唯讀清單沒有可操作的東西,
+//     列不該是焦點站(focus-canonical「問題一」:不可操作 → 不可聚焦),維持原本的純清單。
+
+function getFileRows(list: HTMLElement): HTMLElement[] {
+  return Array.from(list.children).filter((el): el is HTMLElement => el instanceof HTMLElement && el.hasAttribute('data-file-upload-row'))
+}
+
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
   (
@@ -183,52 +210,153 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
 
     const hasFiles = Array.isArray(files) && files.length > 0
 
-    const fileListNode = hasFiles ? (
-      <ul
-        className={cn(
-          'flex flex-col w-full',
-          // 2026-06-03 gap SSOT:列間 gap + control→list gap(mt)由「item 有無邊框」單一規則決定,
-          // 同值貫穿整個垂直堆疊 — rich(form surface = border card)→ 8px;compact(borderless/bg-pill)→ 4px。
-          // 消費 FileItem「List wrapper canonical」(file-item.spec.md),取代原硬寫 gap-2 / mt-3(不分 mode)。
-          fileListMode === 'rich' ? 'gap-2 mt-2' : 'gap-1 mt-1',
-        )}
+    // ── 檔案清單鍵盤(B9 路線乙;實作取捨見上方「鍵盤:內建檔案清單 = 一個 Tab 停靠點」段)──
+    // 一站 + 方向鍵只在列上有本元件自己的按鈕(onRemove)時成立;唯讀清單維持純 ul / li。
+    const rowKeyboard = hasFiles && !!onRemove
+    const listRef = React.useRef<HTMLDivElement>(null)
+    // 從外面 Tab 回來落在上次停的那一列;沒停過(或那一列已被移除)→ 第一列
+    // (keyboard-model-canonical.md「列上有小按鈕的一串」引 W3C「the element that had focus the last time」)。
+    const [rememberedRowId, setRememberedRowId] = React.useState<string | null>(null)
+    // 停靠點判定與 Sidebar / TreeView 同一份(X1;lib/roving-list-keyboard.ts `pickRovingTabStop`):上次停的 → 第一列
+    const tabStopRowId = rowKeyboard
+      ? (pickRovingTabStop(files!, { remembered: files!.find((f) => f.id === rememberedRowId) ?? null })?.id ?? null)
+      : null
+
+    // 列裡的按鈕一律不在 Tab 路上(-1;→ 才進得去)。每次 render 後同步一次:列增減、consumer 的 description 換內容都會 re-render。
+    React.useLayoutEffect(() => {
+      const list = listRef.current
+      if (!rowKeyboard || !list) return
+      for (const row of getFileRows(list)) removeRovingControlsFromTabOrder(row.querySelectorAll<HTMLElement>(ROVING_CONTROL_SELECTOR))
+    })
+
+    // 焦點用任何方式進到某一列(Tab / 方向鍵 / 點擊 / 移除後的焦點接力)→ 記住那一列
+    const handleFileListFocus = (event: React.FocusEvent<HTMLDivElement>) => {
+      const id = (event.target as HTMLElement).closest('[data-file-upload-row]')?.getAttribute('data-file-upload-row')
+      if (id && id !== rememberedRowId) setRememberedRowId(id)
+    }
+
+    // 按鍵表 SSOT = file-upload.spec.md「A11y 預設 › 檔案清單鍵盤」(B9);判定與執行 = lib/roving-list-keyboard.ts。
+    // 用 capture:方向鍵整串歸清單,搶在列裡的按鈕 / 連結自己的處理之前(同 Sidebar;X6 全宿主一致:
+    // consumer 從 description 放進來的選單鈕按 ↓ 也是換列,開選單用 Enter / 空白鍵)。
+    const handleFileListKeyDownCapture = (event: React.KeyboardEvent<HTMLDivElement>) => {
+      const list = event.currentTarget
+      const target = event.target as HTMLElement
+      const row = target.closest<HTMLElement>('[data-file-upload-row]')
+      if (!row || row.parentElement !== list) return
+      const onRow = target === row
+      const controls = listRovingControls(row)
+      // 焦點在列裡、但不是列上可走到的東西 → 不接管
+      if (!onRow && !controls.includes(target)) return
+      const action = resolveRovingKey({
+        key: event.key,
+        focus: onRow ? 'item' : 'control',
+        controlCount: controls.length,
+        controlIndex: onRow ? -1 : controls.indexOf(target),
+        controlIsTextEntry: !onRow && isTextEntryElement(target),
+        defaultPrevented: event.defaultPrevented,
+        metaKey: event.metaKey,
+        ctrlKey: event.ctrlKey,
+        altKey: event.altKey,
+        shiftKey: event.shiftKey,
+      })
+      applyRovingAction(action, { event, item: row, controls, items: getFileRows(list) })
+    }
+
+    // 列的內容兩種清單共用(唯讀清單 ul/li、可操作清單 grid/row)—— FileItem 的 props 只寫一份
+    const renderFileRow = (f: FileUploadStatus) => (
+      <FileItem
+        // grid 的每一列只放一格,列的直接子元素是 gridcell(Fluent List 多動作列與 React Aria GridList 同構,出處見 spec)
+        role={rowKeyboard ? 'gridcell' : undefined}
+        mode={fileListMode}
+        name={f.name}
+        status={f.status}
+        progress={f.progress}
+        description={f.description ?? (f.size != null ? formatBytes(f.size) : undefined)}
+        thumbnailSrc={f.thumbnailSrc}
+        actions={
+          onRemove ? (
+            // Collection remove(per-file)— 不是 dismiss surface,故不套 `dismiss` prop。
+            // 視覺與 dismiss 一致(text variant + fg-muted dim)— 對齊 inline-action.spec.md
+            // 「Dismiss canonical — X close only」+「dismiss prop 觸發條件」段:onRemove callback 不觸發 dismiss prop。
+            <Button
+              iconOnly
+              variant="text"
+              size="xs"
+              startIcon={X}
+              aria-label={removeAriaLabel(f.name)}
+              data-collection-remove
+              onClick={(e) => {
+                e.stopPropagation()
+                focusAfterFileRemoval(e.currentTarget)
+                onRemove(f.id)
+              }}
+              className="text-fg-muted hover:text-fg-secondary"
+            />
+          ) : undefined
+        }
+      />
+    )
+
+    const fileListClassName = cn(
+      'flex flex-col w-full',
+      // 2026-06-03 gap SSOT:列間 gap + control→list gap(mt)由「item 有無邊框」單一規則決定,
+      // 同值貫穿整個垂直堆疊 — rich(form surface = border card)→ 8px;compact(borderless/bg-pill)→ 4px。
+      // 消費 FileItem「List wrapper canonical」(file-item.spec.md),取代原硬寫 gap-2 / mt-3(不分 mode)。
+      fileListMode === 'rich' ? 'gap-2 mt-2' : 'gap-1 mt-1',
+    )
+
+    const fileListNode = !hasFiles ? null : rowKeyboard ? (
+      // 列上有按鈕的清單用 grid / row / gridcell 身分(file-upload.spec.md「A11y 預設 › 檔案清單鍵盤」;W3C:listbox 的選項裡不能互動,
+      // 「To present a list of interactive elements, see the Grid Pattern」)。用 div 不用 ul / li:HTML 的 ul / li
+      // 不允許改成 grid / row 角色(W3C ARIA in HTML 允許角色表;React Aria GridList 同樣渲染 div)。
+      // 宣告了 composite 角色就得真的有方向鍵 —— 處理程式 = 上方 handleFileListKeyDownCapture
+      // (keyboard-model-canonical.md「宣告了 composite 角色,就必須真的實作那套鍵盤」)。
+      <div
+        ref={listRef}
+        role="grid"
         aria-label="已上傳的檔案"
+        data-file-upload-list=""
+        className={fileListClassName}
+        onKeyDownCapture={handleFileListKeyDownCapture}
+        onFocus={handleFileListFocus}
       >
+        {files!.map((f) => {
+          // 列底貼著 FileItem 的進度條時(compact 且有 status),框改畫在列自己的框圖層 ::before,進度條那一段挖空
+          // (file-item.spec.md「焦點框 × 貼著列底的進度條」;挖的位置由 FileItem 給,與進度條同源)。其餘列照舊畫在列上。
+          const ringCutout = fileItemRingCutoutStyle({ mode: fileListMode, status: f.status })
+          return (
+            <div
+              key={f.id}
+              role="row"
+              data-file-upload-row={f.id}
+              // 整串只有一列是 0(上次停的那列 / 第一列),其餘 -1
+              tabIndex={f.id === tabStopRowId ? 0 : -1}
+              // 列拿到焦點時的框:內描邊(focus-canonical「框怎麼畫」:撐滿容器寬度的列往內畫;與 FileItem 自己的整列焦點框
+              // 同幾何)。圓角同 FileItem 的 rounded-md,框才貼著列的圓角走。滑鼠點列不畫(:focus-visible 啟發式)。
+              className={cn(
+                'rounded-md',
+                ringCutout
+                  ? ['relative', FILE_ITEM_RING_LAYER_CLASS, 'focus-visible:before:focus-ring-inset']
+                  : 'focus-visible:focus-ring-inset',
+                // @focus-suppress C — 列自己這圈改畫在自己的 ::before 框圖層(上兩行),元素本身不再另畫全域外描邊;承擔者:file-upload.tsx:339
+                ringCutout && 'focus-visible:outline-none',
+              )}
+              style={ringCutout}
+            >
+              {renderFileRow(f)}
+            </div>
+          )
+        })}
+      </div>
+    ) : (
+      <ul className={fileListClassName} aria-label="已上傳的檔案" data-file-upload-list="">
         {files!.map((f) => (
           <li key={f.id} className="list-none">
-            <FileItem
-              mode={fileListMode}
-              name={f.name}
-              status={f.status}
-              progress={f.progress}
-              description={f.description ?? (f.size != null ? formatBytes(f.size) : undefined)}
-              thumbnailSrc={f.thumbnailSrc}
-              actions={
-                onRemove ? (
-                  // Collection remove(per-file)— 不是 dismiss surface,故不套 `dismiss` prop。
-                  // 視覺與 dismiss 一致(text variant + fg-muted dim)— 對齊 inline-action.spec.md
-                  // 「Dismiss canonical — X close only」+「dismiss prop 觸發條件」段:onRemove callback 不觸發 dismiss prop。
-                  <Button
-                    iconOnly
-                    variant="text"
-                    size="xs"
-                    startIcon={X}
-                    aria-label={removeAriaLabel(f.name)}
-                    data-collection-remove
-                    onClick={(e) => {
-                      e.stopPropagation()
-                      focusAfterFileRemoval(e.currentTarget)
-                      onRemove(f.id)
-                    }}
-                    className="text-fg-muted hover:text-fg-secondary"
-                  />
-                ) : undefined
-              }
-            />
+            {renderFileRow(f)}
           </li>
         ))}
       </ul>
-    ) : null
+    )
 
     return (
       <div ref={ref} className={cn('w-full', hasFiles && 'flex flex-col')}>
@@ -318,7 +446,9 @@ const FileUpload = React.forwardRef<HTMLDivElement, FileUploadProps>(
           // 對稱 padding p-[var(--layout-space-loose)]:四邊等距,density-aware(md=16px / lg=24px),對齊 DS chrome padding canonical。
           // 不再硬寫 px-6 py-10(不對稱+非 token)。內容物(icon + title + description)垂直堆疊由 gap-2 控制
           'rounded-md border-2 border-dashed p-[var(--layout-space-loose)]',
-          'cursor-pointer transition-colors',
+          // 滑過 / 拖進來的邊框變色瞬間切換,不做過渡(2026-09-26 待辦總帳 L9「全部瞬間」延伸到外框,user:「確定這樣才是一致設計語言就做」;
+          // 同一次滑過底色瞬間、外框卻 0.15 秒 = 兩套手感;SSOT = tokens/motion/motion.spec.md「hover 回饋不做過渡」)
+          'cursor-pointer',
           // idle:--border(元件邊框,非 --divider 分隔線 — 2026-06-03 Q2 token 修正)+ surface 底
           'border-border bg-surface',
           // hover = drag-over 統一(2026-06-03 Q2-A 純 border-driven,對齊 Ant Dragger colorPrimaryHover):
@@ -415,7 +545,7 @@ export const fileUploadMeta = {
   tokens: {
     bg: ['bg-surface', 'bg-disabled'],
     fg: [],
-    ring: ['ring-ring'],
+    ring: ['--ring'],
   },
 } as const
 

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

@@ -636,7 +636,10 @@ const Filmstrip = React.memo(function Filmstrip({ files, activeIndex, onSelect,
               data-thumb-index={i}
               onClick={() => onSelect(i)}
               className={cn(
-                'shrink-0 rounded-md bg-muted overflow-hidden',
+                // 底色不掛在按鈕上:`bg-muted` 是「靜態非互動 surface」(color.spec.md「能不能當可互動元素的靜止底」:
+                // `--muted` 不可以),縮圖鈕是可點的;它只當**佔位層**(沒有預覽圖時的檔案圖示 + 副檔名)的底,
+                // 有圖時圖填滿整格、看不到底(待辦總帳 A9③,2026-09-29;畫面不變)。
+                'shrink-0 rounded-md overflow-hidden',
                 // 2026-09-07 C14:選中與鍵盤焦點原本都是 `ring-2` + `--ring: var(--primary)`
                 // (semantic.css:337 是全 repo 唯一定義)→ 已選中的縮圖被聚焦時 **0 像素變化**,
                 // 違反 APG「selected 必須與 focus 指示器在視覺上可區分」。
@@ -649,7 +652,9 @@ const Filmstrip = React.memo(function Filmstrip({ files, activeIndex, onSelect,
                 // 不可寫 `outline-none`(它把 --tw-outline-style 設成 none,會讓下面三條靜默失效,
                 // 見 steps.tsx 同款事故)。
                 'focus-visible:focus-ring-inset',
-                'transition-shadow duration-150',
+                // 不寫 transition-shadow:滑過外框(ring-border → ring-border-hover)一律瞬間(motion.spec.md「hover 回饋不做過渡」,
+                // 2026-09-26 L9 延伸,user:「確定這樣才是一致設計語言就做」)。同一條 ring 也畫選中框,所以選中切換跟著瞬間 ——
+                // 同 Chip / SegmentedControl 的選中色(motion.spec.md「同一組屬性若也被選中改變,一併瞬間」)。
                 active
                   ? 'ring-2 ring-primary'
                   : 'ring-1 ring-border hover:ring-border-hover',
@@ -666,7 +671,7 @@ const Filmstrip = React.memo(function Filmstrip({ files, activeIndex, onSelect,
                     draggable={false}
                   />
                 ) : (
-                  <div className="w-full h-full flex flex-col items-center justify-center gap-0.5">
+                  <div className="w-full h-full flex flex-col items-center justify-center gap-0.5 bg-muted">
                     <FileText size={20} className="text-fg-muted" aria-hidden />
                     <span className="text-footnote text-fg-muted font-medium">{ext}</span>
                   </div>
@@ -1216,7 +1221,7 @@ export const fileViewerMeta = {
   tokens: {
     bg: ['bg-muted', 'bg-neutral-selected', 'bg-overlay', 'bg-surface-raised'],
     fg: ['text-fg-muted', 'text-foreground'],
-    ring: ['ring-primary', 'ring-ring'],
+    ring: ['focus-ring-inset'],
   },
 } as const
 

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

@@ -44,7 +44,7 @@ export const PersonProfileCard: Story = {
         <span className="text-caption text-fg-muted">Reviewer:</span>
         <HoverCard>
           <HoverCardTrigger asChild>
-            <button type="button" aria-label="Ada Chen 個人資訊" className="cursor-pointer rounded-full">
+            <button type="button" aria-label="Ada Chen 個人資訊" className="cursor-default rounded-full">
               <Avatar src="https://i.pravatar.cc/56?u=ada-chen" alt="Ada Chen" color="indigo" size={28} />
             </button>
           </HoverCardTrigger>
@@ -249,7 +249,7 @@ export const TriggerShowcase: Story = {
           <span className="text-footnote text-fg-muted font-mono">trigger: Avatar</span>
           <HoverCard openDelay={MOTION_DELAY_RICH_MS} closeDelay={MOTION_DELAY_CLOSE_MS}>
             <HoverCardTrigger asChild>
-              <button type="button" aria-label="Ada Chen 個人資訊" className="cursor-pointer rounded-full">
+              <button type="button" aria-label="Ada Chen 個人資訊" className="cursor-default rounded-full">
                 <Avatar src="https://i.pravatar.cc/64?u=ada-chen" alt="Ada Chen" color="indigo" size={32} />
               </button>
             </HoverCardTrigger>

package/src/components/InlineEdit/inline-edit.spec.md

@@ -72,6 +72,8 @@ InlineEdit 本體只給:**對齊盒(-mx orientation-aware)+ 委派 view 統一 f
 
 **「底色範圍 = 輸入框範圍」不變量**:view 與 edit 兩態共用同一對齊盒(同寬、同 1px 邊框盒),幾何同源(view×default = edit 幾何減 chrome),故 hover 底色與 edit 輸入框逐 pixel 對齊、態切換零位移。(舊版 read 外框 `w-full`+`-mx` 疊加 → 右側短一截、整塊左偏,已修;2026-07-16 -mx 由恆定改條件化;2026-07-17 進一步移除 fieldCtx gate → 純 orientation-aware,委派 view 統一 fieldViewGeometry field-px,standalone 也對齊。)
 
+**點得到的範圍 = 底色範圍**(2026-09-26,待辦總帳 N53⑤):隱形 Pressable 用 `-inset-px` 蓋滿外框的 border box(含那圈 1px 透明邊框),滑過底色亮到哪、點下去就進 edit 到哪。先前是 `inset-0`,只蓋到 padding box —— 外圈 1px 亮著卻點不進 edit(實測一般螢幕左 / 右 / 下三邊、Retina 8 點中 5 點),正是 `../../ds-canonical/references/hit-area-canonical.md` 要防的「看到亮起來卻點不到」。修的是命中區、不是底色:底色與 edit 輸入框逐 pixel 對齊是本條不變量,不能縮。畫面不變,只有那 1px 的游標與點擊結果改變。世界級對照:Atlassian inline-edit 的讀取態把點擊與滑過底色掛在**同一個元素**上,兩者天生同一個盒([`read-view.js#L56`](https://cdn.jsdelivr.net/npm/@atlaskit/inline-edit@16.4.5/dist/es2019/internal/read-view.js) `onClick: onReadViewClick`、同一個 div 的 `className`(#L62)帶滑過樣式)。
+
 **尺寸預設 = `sm`**（2026-07-09 user 拍板）:view 態無邊框、視覺即純文字,尺寸過大會使版面鬆散;consumer 可傳 `size` 覆寫,標題場景另用 `readClassName` 疊大字級。
 
 **在 `<Field>` 內也是 `sm`**(2026-07-28 user 拍板):Field 的預設 `md` 是「沒人決定過」的預設值,不得壓過本元件宣告的 `sm`。實作雙通道 —— 靜態 `InlineEdit.fieldPreferredSize = 'sm'` 供 Field 直接子元件同步偵測,加上掛載時的 `useRegisterFieldPreferredSize('sm')` 補位(包 wrapper / `React.memo` / HOC 會遮蔽靜態);控件自身尺寸則由 `useResolvedFieldSize` 依 `sizeExplicit` 同步解析,不等註冊。**唯有 consumer 顯式 `size`(在 Field 或 InlineEdit 上)才覆寫**。機制與失效語意 owner → `Field/field.spec.md`「Control 偏好尺寸 SSOT」。

package/src/components/InlineEdit/inline-edit.tsx

@@ -400,15 +400,20 @@ function InlineEditImpl<T = string>(
         >
           {viewNode}
           {/* 隱形 Pressable(僅 editable):提供 click + 鍵盤 Tab focus + Enter/Space 進 edit;透明疊於內容上。
-              hover 底色 + focus 藍框由外層 div 承載(Field focus 語言),故本 button 只需 outline-none 消瀏覽器預設外框。 */}
+              hover 底色 + focus 藍框由外層 div 承載(Field focus 語言),故本 button 只需 outline-none 消瀏覽器預設外框。
+              `-inset-px`(不是 inset-0):外層 div 有 1px 透明邊框,滑過底色塗滿整個 border box(含那 1px),
+              而 absolute 的 inset-0 只蓋到 padding box —— 外圈那 1px 亮著、點了卻不進 edit(待辦總帳 N53⑤;
+              一般螢幕左 / 右 / 下三邊、Retina 8 點中 5 點點不到)。往外多蓋 1px = 恰好等於外框的 border box,
+              「亮的範圍 = 點得到的範圍」(inline-edit.spec.md「點得到的範圍 = 底色範圍」;hit-area-canonical.md「看到亮起來卻點不到」)。
+              不縮滑過底色:底色與 edit 輸入框逐 pixel 對齊是既有不變量,動的只能是命中區。 */}
           {editable && (
             <button
               ref={readButtonRef}
               type="button"
               aria-label={label ? `編輯 ${label}` : '編輯'}
               onClick={enterEdit}
-              // @focus-suppress C — C 隱形整列觸發器;承擔者:指示器在外層 div(見上方 :402 註解)
-              className="absolute inset-0 cursor-text rounded-md focus-visible:outline-none"
+              // @focus-suppress C — C 隱形整列觸發器;承擔者:指示器在外層 div(見上方 :397 的 `[&:has(button:focus-visible)]:border-primary`)
+              className="absolute -inset-px cursor-text rounded-md focus-visible:outline-none"
             />
           )}
         </div>

package/src/components/Input/input.anatomy.stories.tsx

@@ -2,6 +2,7 @@ import type { Meta } from '@storybook/react'
 import { useState, useEffect } from 'react'
 import { Search, Mail, X, Eye, EyeOff } from 'lucide-react'
 import { Input } from './input'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
 
 const meta: Meta = {
   title: 'Design System/Components/Input/設計規格',
@@ -115,18 +116,6 @@ const TokenAnnotation = ({ colors }: { colors: ColorSpec }) => (
   </div>
 )
 
-const Tab = ({ active, onClick, disabled, children }: { active: boolean; onClick: () => void; disabled?: boolean; children: React.ReactNode }) => {
-  if (disabled) return <span className="px-2.5 py-1 text-[12px] font-mono rounded-md text-fg-disabled bg-neutral-hover cursor-not-allowed">{children}</span>
-  return (
-    <button type="button" onClick={onClick}
-      className={`px-2.5 py-1 text-[12px] font-mono rounded-md cursor-pointer transition-colors ${
-        active ? 'bg-primary text-white font-semibold' : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
-      }`}>
-      {children}
-    </button>
-  )
-}
-
 const PropRow = ({ label, dot, children }: { label: string; dot?: string; children: React.ReactNode }) => (
   <div className="flex items-start gap-3 py-2 border-b border-divider last:border-b-0">
     <span className="text-[11px] text-fg-muted font-medium w-[72px] shrink-0 pt-0.5 flex items-center gap-1.5">
@@ -284,41 +273,44 @@ const InspectorInner = () => {
 
   return (
     <div className="flex flex-col gap-6">
-      {/* Controls */}
+      {/* Controls — 互斥切換消費 SegmentedControl(segmented-control.spec.md「何時用」2–5 個互斥選項;
+          取代手刻 Tab:它靜止借 neutral-hover、hover 借 neutral-active,是 color.spec.md 成對 token 的錯配) */}
       <div className="flex flex-col gap-2.5">
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">Mode</span>
-          <div className="flex flex-wrap gap-1.5">
-            {MODES.map((m) => <Tab key={m} active={mode === m} onClick={() => setMode(m)}>{m}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="Mode" value={mode} onValueChange={(v) => setMode(v as ModeKey)}>
+            {MODES.map((m) => <SegmentedControlItem key={m} value={m}>{m}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">Size</span>
-          <div className="flex gap-1.5">
-            {SIZES.map((sz) => <Tab key={sz} active={size === sz} onClick={() => setSize(sz)}>{sz}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="Size" value={size} onValueChange={(v) => setSize(v as SizeKey)}>
+            {SIZES.map((sz) => <SegmentedControlItem key={sz} value={sz}>{sz}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">Error</span>
-          <div className="flex gap-1.5">
-            <Tab active={!error} onClick={() => setError(false)}>off</Tab>
-            <Tab active={error} onClick={() => setError(true)} disabled={!isEdit}>on</Tab>
-          </div>
+          {/* 停用項用元件自身 disabled(segmented-control.spec.md「disabled」);停用項不得是當前值 → value 取實際生效值 */}
+          <SegmentedControl size="sm" aria-label="Error" value={error && isEdit ? 'on' : 'off'} onValueChange={(v) => setError(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on" disabled={!isEdit}>on</SegmentedControlItem>
+          </SegmentedControl>
           {!isEdit && <span className="text-[11px] text-fg-muted">僅 edit 模式</span>}
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">startIcon</span>
-          <div className="flex gap-1.5">
-            <Tab active={!hasStartIcon} onClick={() => setHasStartIcon(false)}>off</Tab>
-            <Tab active={hasStartIcon} onClick={() => setHasStartIcon(true)}>on</Tab>
-          </div>
+          <SegmentedControl size="sm" aria-label="startIcon" value={hasStartIcon ? 'on' : 'off'} onValueChange={(v) => setHasStartIcon(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on">on</SegmentedControlItem>
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">endAction</span>
-          <div className="flex gap-1.5">
-            <Tab active={!hasEndAction} onClick={() => setHasEndAction(false)}>off</Tab>
-            <Tab active={hasEndAction} onClick={() => setHasEndAction(true)} disabled={!isEdit}>on</Tab>
-          </div>
+          {/* 同上:停用項不得是當前值 → value 取實際生效值(預覽也是 hasEndAction && isEdit) */}
+          <SegmentedControl size="sm" aria-label="endAction" value={hasEndAction && isEdit ? 'on' : 'off'} onValueChange={(v) => setHasEndAction(v === 'on')}>
+            <SegmentedControlItem value="off">off</SegmentedControlItem>
+            <SegmentedControlItem value="on" disabled={!isEdit}>on</SegmentedControlItem>
+          </SegmentedControl>
           {!isEdit && <span className="text-[11px] text-fg-muted">僅 edit 模式</span>}
         </div>
       </div>

package/src/components/Input/input.spec.md

@@ -142,6 +142,17 @@ Input 有**一個公開** visual chrome variant `default`(+ 一個 `@internal`
 
 ---
 
+## 點外框 = 點輸入處(2026-09-26,待辦總帳 N53③)
+
+`default` 外框「明確邀請輸入」(上表),所以**外框裡任何不是按鈕 / 連結的地方,點下去都聚焦輸入處**:外框內距(N53 實測左 13px、上 5.5px,含 1px 邊框)、1px 邊框本身、前置 `startIcon`。`endAction` / `endSlot` 的按鈕照它自己的行為走,不搶焦點。外框用文字游標(`cursor-text`);停用時不掛(停用自有 `cursor-not-allowed`)。
+
+- **為什麼是 bug 不是新規則**:規則早就寫在 `../Field/field-controls.spec.md`「點擊與游標原則」——「讓點擊穿透到底層的 input/select,確保使用者點擊 Field 內任何位置都能 focus/activate」、游標「input → `cursor-text`」。缺的是外框自己的內距與邊框:底下沒有 input 可以穿透,指到時外框變色(`hover:border-border-hover`),點下去卻不聚焦 —— 正是 `../../ds-canonical/references/hit-area-canonical.md` 要防的「看到亮起來卻點不到」。同家族 Select / Combobox / TimePicker / PeoplePicker / Textarea 的外框本身就是點擊目標,本來就沒有這個缺口。
+- **實作只有一份**:`../Field/field-wrapper.tsx` 的 `focusFieldInputFromChrome`(外框 `onMouseDown`)+ `FIELD_TEXT_ENTRY_CURSOR`。所有「外框包著一個 `<input>`」的可打字控件(Input、NumberInput、LinkInput 編輯態)消費同一支,不各寫一份。用 mousedown 而不是 click:click 之前焦點會先離開輸入處(blur → focus 閃一下、`onBlur` 驗證誤觸)。插入點落在點的那一側:點在輸入處右邊放最後、左邊放最前。
+- **畫面**:外框顏色、焦點框都不變(聚焦後的藍框與直接點輸入處相同);只有游標與點擊結果改變。
+- **世界級對照**:[MUI InputBase `InputBase.js#L478-L481`](https://github.com/mui/material-ui/blob/v9.4.0/packages/mui-material/src/InputBase/InputBase.js#L478-L481)(點根元素 → `inputRef.current.focus()`)、根元素 [`cursor: 'text'`(#L105)](https://github.com/mui/material-ui/blob/v9.4.0/packages/mui-material/src/InputBase/InputBase.js#L105);[Primer `TextInput.tsx#L150-L154`](https://github.com/primer/react/blob/%40primer/react%4038.40.0/packages/react/src/TextInput/TextInput.tsx#L150-L154)(外框 `onClick={focusInput}`,[#L217](https://github.com/primer/react/blob/%40primer/react%4038.40.0/packages/react/src/TextInput/TextInput.tsx#L217));[rc-input(Ant Design)`BaseInput.tsx#L48-L51`](https://github.com/react-component/input/blob/v1.8.0/src/BaseInput.tsx#L48-L51)(容器內任何點擊 → `triggerFocus`)。
+
+---
+
 ## Auto-width(AR46,2026-04-21)
 
 `autoWidth` prop:Input 寬度自動等於「內容寬(value / placeholder)+ startIcon + endAction + padding」,基於 CSS `field-sizing: content`(Chrome 123+ / Safari 17.4+)。

package/src/components/Input/input.tsx

@@ -4,7 +4,7 @@ import { type VariantProps } from 'class-variance-authority'
 import type { LucideIcon } from 'lucide-react'
 import { cn } from '@/lib/utils'
 import type { FieldMode, FieldVariant, FieldVariantInternal } from '@/design-system/components/Field/field-types'
-import { fieldWrapperStyles, bareInputStyles } from '@/design-system/components/Field/field-wrapper'
+import { fieldWrapperStyles, bareInputStyles, focusFieldInputFromChrome, FIELD_TEXT_ENTRY_CURSOR } from '@/design-system/components/Field/field-wrapper'
 import { useFieldContext, useResolvedFieldSize, useResolvedFieldDisabled, useResolvedFieldMode, useResolvedFieldVariant, useResolvedFieldInvalid, useFieldEmptyDisplay, fieldEmptyColorClass } from '@/design-system/components/Field/field-context'
 import { useControllable } from '@/design-system/hooks/use-controllable'
 import { ItemInlineAction, ItemPrefix, type InlineActionConfig } from '@/design-system/patterns/element-anatomy/item-anatomy'
@@ -203,10 +203,15 @@ const Input = React.forwardRef<HTMLInputElement, InputProps>(
       <div
         className={cn(
           fieldWrapperStyles({ mode: resolvedMode, variant: variant, size, error: resolvedError }),
+          // 整個外框都是輸入處:文字游標 + 點內距 / 邊框 / 前置圖示就聚焦 input(待辦總帳 N53③;
+          // 規則 owner field-controls.spec.md「點擊與游標原則」;共用實作 field-wrapper.tsx focusFieldInputFromChrome)。
+          // 停用不掛:停用的外框自己是 cursor-not-allowed(field-wrapper disabled compound),而且不接受焦點。
+          resolvedMode !== 'disabled' && FIELD_TEXT_ENTRY_CURSOR,
           // autoWidth:wrapper 縮到 inline-flex + w-auto,讓寬度由 startIcon + input(field-sizing: content)+ endAction 自然累加
           autoWidth && 'inline-flex w-auto',
           className,
         )}
+        onMouseDown={focusFieldInputFromChrome}
         data-field-mode={resolvedMode}
         data-error={isEditable && resolvedError ? '' : undefined}
         aria-busy={loading || undefined}

package/src/components/LinkInput/link-input.anatomy.stories.tsx

@@ -6,6 +6,7 @@
 import type { Meta } from '@storybook/react'
 import { useState, useEffect } from 'react'
 import { LinkInput } from './link-input'
+import { SegmentedControl, SegmentedControlItem } from '@/design-system/components/SegmentedControl/segmented-control'
 
 const meta: Meta = {
   title: 'Design System/Components/LinkInput/設計規格',
@@ -148,15 +149,6 @@ const TokenAnnotation = ({ colors }: { colors: ColorSpec }) => (
   </div>
 )
 
-const Tab = ({ active, onClick, children }: { active: boolean; onClick: () => void; children: React.ReactNode }) => (
-  <button type="button" onClick={onClick}
-    className={`px-2.5 py-1 text-[12px] font-mono rounded-md cursor-pointer transition-colors ${
-      active ? 'bg-primary text-white font-semibold' : 'bg-neutral-hover text-fg-secondary hover:bg-neutral-active'
-    }`}>
-    {children}
-  </button>
-)
-
 const PropRow = ({ label, dot, children }: { label: string; dot?: string; children: React.ReactNode }) => (
   <div className="flex items-start gap-3 py-2 border-b border-divider last:border-b-0">
     <span className="text-[11px] text-fg-muted font-medium w-[72px] shrink-0 pt-0.5 flex items-center gap-1.5">
@@ -277,7 +269,7 @@ export const Overview = {
       {/* Interaction flow */}
       <div className="flex flex-col gap-3">
         <H3>互動流程</H3>
-        <Desc>edit 模式下的狀態轉換。核心差異：點擊 value 開啟連結，不是進入編輯——編輯由 Pencil 觸發。</Desc>
+        <Desc>edit 模式下的狀態轉換。核心差異：點擊 value（網址文字）開啟連結，不是進入編輯——編輯由 Pencil 或點外框裡文字以外的空白處觸發。</Desc>
         <div className="overflow-x-auto">
           <table className="text-caption border-collapse">
             <thead><tr><Th>觸發</Th><Th>效果</Th></tr></thead>
@@ -285,6 +277,8 @@ export const Overview = {
               {[
                 ['點擊 link text', '開啟連結（target="_blank"）'],
                 ['點擊 Pencil', '切換到 input 狀態，自動 focus'],
+                ['點擊外框空白處（網址文字以外）', '同 Pencil：切換到 input 狀態，自動 focus'],
+                ['從空白處拖過網址文字（選字）', '不進入編輯，保留選取'],
                 ['blur（合法 URL）', '切回 link 狀態，觸發 onChange'],
                 ['blur（不合法 URL）', '維持 input 狀態 + error 邊框'],
                 ['blur（空值）', '清除值，顯示 placeholder'],
@@ -322,30 +316,33 @@ const InspectorInner = () => {
 
   return (
     <div className="flex flex-col gap-6">
-      {/* Controls */}
+      {/* Controls — 互斥切換消費 SegmentedControl(segmented-control.spec.md「何時用」2–5 個互斥選項;
+          取代手刻 Tab:它靜止借 neutral-hover、hover 借 neutral-active,是 color.spec.md 成對 token 的錯配) */}
       <div className="flex flex-col gap-2.5">
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">Mode</span>
-          <div className="flex gap-1.5">
-            {MODES.map((m) => <Tab key={m} active={mode === m} onClick={() => setMode(m)}>{m}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="Mode" value={mode} onValueChange={(v) => setMode(v as ModeKey)}>
+            {MODES.map((m) => <SegmentedControlItem key={m} value={m}>{m}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">State</span>
-          <div className="flex gap-1.5">
+          {/* 非 edit 模式只有 link 狀態:原本是「點了沒反應」的靜默 no-op,改用元件自身的個別 item disabled
+              (segmented-control.spec.md「disabled」);當前值恆為 link,不會落在停用項上 */}
+          <SegmentedControl size="sm" aria-label="State" value={editState} onValueChange={(v) => setEditState(v as EditStateKey)}>
             {EDIT_STATES.map((st) => (
-              <Tab key={st} active={editState === st} onClick={() => { if (mode === 'edit') setEditState(st) }}>
+              <SegmentedControlItem key={st} value={st} disabled={mode !== 'edit' && st !== 'link'}>
                 {st}
-              </Tab>
+              </SegmentedControlItem>
             ))}
-          </div>
+          </SegmentedControl>
           {mode !== 'edit' && <span className="text-[11px] text-fg-muted">readonly / disabled 只有 link 狀態</span>}
         </div>
         <div className="flex items-center gap-2">
           <span className="text-[11px] text-fg-muted w-16 shrink-0">Size</span>
-          <div className="flex gap-1.5">
-            {SIZES.map((sz) => <Tab key={sz} active={size === sz} onClick={() => setSize(sz)}>{sz}</Tab>)}
-          </div>
+          <SegmentedControl size="sm" aria-label="Size" value={size} onValueChange={(v) => setSize(v as SizeKey)}>
+            {SIZES.map((sz) => <SegmentedControlItem key={sz} value={sz}>{sz}</SegmentedControlItem>)}
+          </SegmentedControl>
         </div>
       </div>
 

package/src/components/LinkInput/link-input.principles.stories.tsx

@@ -69,7 +69,7 @@ export const UsageGuidance: Story = {
       <div>
         <Rule
           title="LinkInput — 有合法 URL 時變藍色連結，點擊開啟新分頁"
-          note="個人資料的 website、文件參考連結、專案 repo URL 等場景。儲存後使用者可直接點擊連結開啟,不需要 copy + paste。右側 Pencil 才是編輯入口,點 value 永遠是開連結"
+          note="個人資料的 website、文件參考連結、專案 repo URL 等場景。儲存後使用者可直接點擊連結開啟,不需要 copy + paste。點網址文字永遠是開連結;要改就按右側 Pencil,或點欄位裡文字以外的空白處"
         >
           <div>
             <Label>✅ 個人資料：Website（儲存後可直接點擊開啟）</Label>
@@ -105,10 +105,10 @@ export const DisplayStateRule: Story = {
     <div>
       <Rule
         title="有合法 URL 且未編輯 → 藍色連結 + Pencil"
-        note="主要顯示狀態。使用者一眼看到可點擊的連結,想改才按 Pencil。對照 Notion / Linear 的 URL field——value 展示為 link,編輯是次要動作"
+        note="主要顯示狀態。使用者一眼看到可點擊的連結,想改才按 Pencil(或點欄位空白處)。對照 Notion 的 URL 屬性——點網址開啟、不進入編輯,編輯另有按鈕(https://www.notion.com/releases/2021-09-08)"
       >
         <LinkInput value="https://react.dev/reference" onChange={() => {}} aria-label="參考連結" />
-        <Label>↑ 可直接點文字開啟,Pencil 進入編輯</Label>
+        <Label>↑ 點網址文字開啟;Pencil 或欄位裡文字以外的空白處進入編輯</Label>
       </Rule>
 
       <Rule
@@ -125,7 +125,7 @@ export const DisplayStateRule: Story = {
         title="❌ 點 value 進入編輯（而不是開連結）"
         note="LinkInput 跟 Input 的核心互動差異就在這——點 value 永遠是開連結。若使用者預期點 value 進入編輯,那該用 Input 不用 LinkInput"
       >
-        <Label warn>（設計規則）點連結 = 開啟連結,編輯 = 按 Pencil。兩者動作路徑分離</Label>
+        <Label warn>（設計規則）點網址文字 = 開啟連結,編輯 = 按 Pencil 或點欄位空白處。兩者動作路徑分離</Label>
       </Rule>
     </div>
   ),