@qijenchen/design-system 0.1.0-beta.83 → 0.1.0-beta.85

package/src/components/Tooltip/tooltip.principles.stories.tsx

@@ -109,7 +109,7 @@ export const UsageGuidance: Story = {
       <Section title="vs 近親 — Tooltip vs HoverCard">
         <Rule
           title="Tooltip — 純文字、語意為描述、不放互動元素"
-          note="適合一句話的提示。語意是純描述（role=tooltip / aria-describedby），不該放可點擊元素。離開 trigger 後有短暫關閉延遲讓滑鼠可移入。"
+          note="適合一句話的提示。語意是純描述（role=tooltip / aria-describedby），不該放可點擊元素。離開 trigger 往浮層移動時，靠 Radix 的 grace 區維持開啟（讓滑鼠可移入），非計時延遲。"
         >
           <Tooltip>
             <TooltipTrigger asChild>
@@ -117,7 +117,7 @@ export const UsageGuidance: Story = {
             </TooltipTrigger>
             <TooltipContent>這個設定會影響所有專案的預設值</TooltipContent>
           </Tooltip>
-          <Label>↑ 純文字說明、滑鼠離開即消失</Label>
+          <Label>↑ 純文字說明；滑鼠離開觸發器即關閉（移入浮層內容則保持開啟）</Label>
         </Rule>
 
         <Rule
@@ -197,7 +197,7 @@ export const NeedsTooltipRule: Story = {
           </TooltipTrigger>
           <TooltipContent>非常長的專案名稱會被截斷顯示完整版</TooltipContent>
         </Tooltip>
-        <Label>↑ 只在 `text-overflow: ellipsis` 觸發時才顯示 tooltip</Label>
+        <Label>↑ 模式示意（此靜態範例恆顯示；實務上應偵測文字真被截斷 `scrollWidth &gt; clientWidth` 時才掛 tooltip）</Label>
       </Rule>
     </div>
   ),

package/src/components/Tooltip/tooltip.spec.md

@@ -41,7 +41,7 @@ Tooltip 的判斷標準是：**畫面上的資訊是否已經足夠讓使用者
 2. Tooltip 出現後，使用者移到下一個觸發器 → 在掃描窗口期內，tooltip 即時切換，不再等待（toolbar 逐一掃描場景）
 3. 使用者離開所有觸發器超過掃描窗口期 → 系統冷卻，下次 hover 重新等待初始延遲
 
-這是一個行為的兩個階段,不是兩種不同的延遲。所有 tooltip(包括 Button icon-only 自動產生的)共享同一組參數——初始延遲由 DS shared constant `HOVER_DELAY_PLAIN_MS`(Tooltip Root wrapper 預設 `delayDuration`;Radix Root prop 優先於 Provider 同名設定)統一,warm-up 掃描窗口(`skipDelayDuration`)由全域 `TooltipProvider` 控制。
+這是一個行為的兩個階段,不是兩種不同的延遲。所有 tooltip(包括 Button icon-only 自動產生的)共享同一組參數——初始延遲由 DS shared constant `MOTION_DELAY_PLAIN_MS`(Tooltip Root wrapper 預設 `delayDuration`;Radix Root prop 優先於 Provider 同名設定)統一,warm-up 掃描窗口(`skipDelayDuration`)由全域 `TooltipProvider` 控制。
 
 ## 何時不用
 

package/src/components/Tooltip/tooltip.stories.tsx

@@ -58,45 +58,10 @@ export const NonButtonTrigger: Story = {
   ),
 }
 
-/* ── 四個方向 ── */
-export const Placement: Story = {
-  name: '方向',
-  render: () => (
-    <div className="grid grid-cols-3 gap-4 items-center justify-items-center w-[300px]">
-      <div />
-      <Tooltip defaultOpen>
-        <TooltipTrigger asChild>
-          <Button variant="secondary" size="sm">Top</Button>
-        </TooltipTrigger>
-        <TooltipContent side="top">上方提示</TooltipContent>
-      </Tooltip>
-      <div />
-
-      <Tooltip defaultOpen>
-        <TooltipTrigger asChild>
-          <Button variant="secondary" size="sm">Left</Button>
-        </TooltipTrigger>
-        <TooltipContent side="left">左方提示</TooltipContent>
-      </Tooltip>
-      <div />
-      <Tooltip defaultOpen>
-        <TooltipTrigger asChild>
-          <Button variant="secondary" size="sm">Right</Button>
-        </TooltipTrigger>
-        <TooltipContent side="right">右方提示</TooltipContent>
-      </Tooltip>
-
-      <div />
-      <Tooltip defaultOpen>
-        <TooltipTrigger asChild>
-          <Button variant="secondary" size="sm">Bottom</Button>
-        </TooltipTrigger>
-        <TooltipContent side="bottom">下方提示</TooltipContent>
-      </Tooltip>
-      <div />
-    </div>
-  ),
-}
+// Retired 2026-07-14 audit Dim 24:`Placement` 四方向展示是 anatomy PlacementReference
+// (tooltip.anatomy.stories.tsx)的完整子集(同 top/right/bottom/left grid,anatomy 版含
+// 動畫方向 + placement 選擇規則),無額外內容或限制 → retire(earn-existence 2-test 雙 NO)。
+// Placement canonical home = anatomy `PlacementReference`。
 
 /* ── 長文字（測試換行） ── */
 export const LongText: Story = {

package/src/components/Tooltip/tooltip.tsx

@@ -3,17 +3,18 @@ import * as TooltipPrimitive from "@radix-ui/react-tooltip"
 
 import { cn } from "@/lib/utils"
 import { OVERLAY_SIDE_OFFSET, OVERLAY_COLLISION_PADDING } from "@/design-system/tokens/elevation/overlay-geometry"
-import { HOVER_DELAY_PLAIN_MS } from "@/design-system/tokens/motion/motion"
+import { MOTION_DELAY_PLAIN_MS } from "@/design-system/tokens/motion/motion"
+import { overlayMotion } from "@/design-system/tokens/motion/overlay-motion"
 
 // 2026-05-18 ship per user 拍板 #3A:Tooltip Provider 預設 delayDuration 對齊 motion token SSOT。
 // Radix 預設 700ms 過保守(被 Material 150-200 / MUI 100 / Atlassian 300 集體驗證),DS 統一用
-// `--hover-delay-plain` (500ms,JS mirror `HOVER_DELAY_PLAIN_MS`)。Consumer 仍可 per-instance override。
+// `--motion-delay-plain` (500ms,JS mirror `MOTION_DELAY_PLAIN_MS`)。Consumer 仍可 per-instance override。
 // 2026-05-21 D5 Phase B codex 抓 comment 200 vs token 500 drift → 註解 500ms 對齊 motion.css:27 SSOT。
-const TooltipProvider = ({ delayDuration = HOVER_DELAY_PLAIN_MS, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>) => (
+const TooltipProvider = ({ delayDuration = MOTION_DELAY_PLAIN_MS, ...props }: React.ComponentProps<typeof TooltipPrimitive.Provider>) => (
   <TooltipPrimitive.Provider delayDuration={delayDuration} {...props} />
 )
 
-const Tooltip = ({ delayDuration = HOVER_DELAY_PLAIN_MS, ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) => (
+const Tooltip = ({ delayDuration = MOTION_DELAY_PLAIN_MS, ...props }: React.ComponentProps<typeof TooltipPrimitive.Root>) => (
   <TooltipPrimitive.Root delayDuration={delayDuration} {...props} />
 )
 
@@ -34,8 +35,9 @@ const TooltipContent = React.forwardRef<
       // 不消費任何 density / layout-space token → 鎖 density 對它是 inert(原 data-density="md" 是 409b91da
       // a11y 批次「對齊 Popover」順手加,非設計決策)→ 移除,讓全浮層行為一致(全繼承 page)。
       className={cn(
-        "z-50 overflow-hidden rounded-md px-3 py-2 text-body font-normal text-on-emphasis bg-tooltip max-w-[280px]",
-        "animate-in fade-in-0 zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 motion-reduce:animate-none motion-reduce:zoom-in-100",
+        "z-50 overflow-hidden rounded-md px-3 py-2 text-body font-normal text-on-emphasis bg-tooltip max-w-[280px] break-words",
+        overlayMotion,
+        "data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:zoom-in-95 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-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-tooltip-content-transform-origin)]",
         className

package/src/components/TreeView/tree-view.anatomy.stories.tsx

@@ -36,7 +36,7 @@ export const Overview: Story = {
 
       <div>
         <H3>TreeItem 內部結構</H3>
-        <Desc>[chevron placeholder] [icon?] [label] [suffix? (hover inline action / badge)] ——遵循 item-layout pattern。葉節點(無 children)自動填入透明 chevron placeholder 保持 column 對齊。</Desc>
+        <Desc>[chevron placeholder] [checkbox? (多選模式)] [indicator | icon?] [label] [suffix? (hover inline action / badge)] ——遵循 item-layout pattern;checkbox 位於 chevron 之後、icon 之前(對齊 tsx render 順序)。葉節點(無 children)自動填入透明 chevron placeholder 保持 column 對齊。</Desc>
       </div>
 
       <div>
@@ -400,7 +400,7 @@ export const KeyboardMatrix: Story = {
     <div className="flex flex-col gap-6">
       <div>
         <H3>鍵盤操作對照</H3>
-        <Desc>TreeView 的 ARIA tree 鍵盤導覽是自建實作(Radix 沒有 Tree primitive)。</Desc>
+        <Desc>TreeView 的 ARIA tree 鍵盤導覽是自建實作(Radix 沒有 Tree primitive)。重排鍵位(最後三列)僅在 `draggable` 時生效,每按一下立即 commit(發出 onDragEnd,同 pointer 契約)。</Desc>
         <div className="overflow-x-auto">
           <table className="text-caption border-collapse">
             <thead><tr><Th>按鍵</Th><Th>行為</Th></tr></thead>
@@ -410,6 +410,9 @@ export const KeyboardMatrix: Story = {
               <tr><Td mono>←</Td><Td>若 expanded 則收合;若 collapsed 或 leaf 則移到 parent</Td></tr>
               <tr><Td mono>Enter / Space</Td><Td>選取當前 focus 的 node</Td></tr>
               <tr><Td mono>Home / End</Td><Td>跳到第一個 / 最後一個可見 node</Td></tr>
+              <tr><Td mono>Cmd/Ctrl+Shift+↑ / ↓</Td><Td>重排:同層上移 / 下移(需 draggable;整個子樹一起動,結果經 SR live region 播報)</Td></tr>
+              <tr><Td mono>Cmd/Ctrl+Shift+→</Td><Td>重排:移入上一個 sibling(需為 folder;收合時自動展開)</Td></tr>
+              <tr><Td mono>Cmd/Ctrl+Shift+←</Td><Td>重排:移出,成為 parent 的下一個 sibling</Td></tr>
             </tbody>
           </table>
         </div>
@@ -425,7 +428,7 @@ export const Accessibility = {
   render: () => (
     <div className="max-w-3xl text-body text-fg-secondary">
       <h3 className="text-h5 text-foreground mb-2">無障礙設計</h3>
-      <p className="whitespace-pre-line">{"TreeView 的無障礙是元件自建的,不是沿用第三方套件的預設。\n\n  角色與屬性  :外層容器標記為 role=\"tree\",每個節點標記為 role=\"treeitem\",並逐一寫上目前展開狀態、是否選取、所在層級;多選時容器再加上「允許多選」標記。展開/收合的動畫是借用 Radix Collapsible,但樹的角色、屬性、鍵盤導覽都是元件自己實作的(Radix 沒有 Tree 元件)。\n\n  鍵盤操作  :\n\n- Tab — 焦點進入整棵樹\n- 上 / 下 — 在可見節點之間移動\n- 右 — 展開資料夾,已展開時移到第一個子節點\n- 左 — 收合資料夾,葉節點時跳回上層\n- Home / End — 跳到第一個 / 最後一個可見節點\n- Enter / 空白鍵 — 選取目前節點\n\n  焦點  :焦點由元件自己管理——整棵樹是單一 Tab 停靠點,鍵盤移動時用一圈內描邊高亮(ring-2 ring-ring)標示目前位置。沒有焦點鎖定、也沒有焦點還原,因為樹不是浮層。\n\n  驗證  :Storybook a11y 面板應為 0 項嚴重問題;不靠滑鼠也能完整操作。文字對比度達 WCAG AA(內文 4.5:1、介面元素 3:1)。"}</p>
+      <p className="whitespace-pre-line">{"TreeView 的無障礙是元件自建的,不是沿用第三方套件的預設。\n\n  角色與屬性  :外層容器標記為 role=\"tree\",每個節點標記為 role=\"treeitem\",並逐一寫上目前展開狀態、是否選取、所在層級;多選時容器再加上「允許多選」標記。展開/收合的動畫是借用 Radix Collapsible,但樹的角色、屬性、鍵盤導覽都是元件自己實作的(Radix 沒有 Tree 元件)。\n\n  鍵盤操作  :\n\n- Tab — 焦點進入整棵樹\n- 上 / 下 — 在可見節點之間移動\n- 右 — 展開資料夾,已展開時移到第一個子節點\n- 左 — 收合資料夾,葉節點時跳回上層\n- Home / End — 跳到第一個 / 最後一個可見節點\n- Enter / 空白鍵 — 選取目前節點\n- Cmd(Ctrl)+Shift+方向鍵 — 重新排列節點(啟用拖曳時:上下=同層移動、右=移入資料夾、左=移出到上層,每按一下立即生效)\n\n  焦點  :焦點由元件自己管理——整棵樹是單一 Tab 停靠點,鍵盤移動時用一圈內描邊高亮(ring-2 ring-ring)標示目前位置。沒有焦點鎖定、也沒有焦點還原,因為樹不是浮層。\n\n  播報  :鍵盤重排的結果(移到第幾項、移入哪個資料夾)會透過隱藏的即時播報區域唸給螢幕閱讀器;無法移動時(已在最上方、不是資料夾等)也會說明原因。文案預設繁體中文,可用 reorderAnnouncements 屬性覆寫。\n\n  驗證  :Storybook a11y 面板應為 0 項嚴重問題;不靠滑鼠也能完整操作(含拖曳重排)。文字對比度達 WCAG AA(內文 4.5:1、介面元素 3:1)。"}</p>
     </div>
   ),
 }

package/src/components/TreeView/tree-view.spec.md

@@ -2,7 +2,10 @@
 component: TreeView
 family: 1
 variants: {}
-sizes: {}
+sizes:
+  sm: { when: "緊湊清單(與 md 同視覺:text-body、indent 24;保留供密度語意)" }
+  md: { when: "default 一般導覽樹" }   # ★ default
+  lg: { when: "touch / 大字級(text-body-lg、px-4 py-2、indent 28)" }
 traits:
   - hasInteractiveStates
   - isStructural
@@ -114,7 +117,7 @@ Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover
 
 **行為**:點整行(label / icon / 空白)→ select(預設所有 node 可選);點 chevron → toggle expand,不 select;鍵盤 `→`(收合 expandable)→ expand;`←`(展開 expandable)→ collapse;`←`(leaf / 收合 node)→ 焦點到 parent。
 
-**預設 label 不 expand**——chevron 是展開唯一控件。理由:select / expand 語意獨立(sidebar「Documents」點 label 進頁面,點 chevron 才展開子列表)。Consumer `expandOnSelect` prop 可讓整行同時 select + expand(適合 stepper)。
+**預設 label 不 expand**——chevron 是展開唯一控件。理由:select / expand 語意獨立(sidebar「Documents」點 label 進頁面,點 chevron 才展開子列表)。Consumer `expandOnSelect` prop 可讓整行同時 select + expand(適合 stepper)——**此連帶展開僅限指標點擊(`handleRowClick`)**;鍵盤 `Enter` / `Space` 只觸發 select,展開 / 收合一律走 `→` / `←`(對齊 WAI-ARIA treeview「Enter 啟用、方向鍵展開收合」慣例)。
 
 **動畫**:children 用 Radix `Collapsible` height animation(0 → auto);chevron `transition-all duration-150 rotate-0 → rotate-90`(`transition-all` 同時涵蓋 hover 色彩過渡)。
 
@@ -166,9 +169,12 @@ Chevron 是**展開/收合控件**,不是 prefix icon:`fg-muted`(指示色,hover
 | `←` | 收合(若展開);移到 parent(若已收合或是 leaf) |
 | `Home` | 焦點移到第一個 node |
 | `End` | 焦點移到最後一個可見 node |
-| `Enter` / `Space` | 觸發 selection(跟點擊 label 同效果) |
+| `Enter` / `Space` | 觸發 selection(等同點擊 label 的 select;`expandOnSelect` 的連帶展開僅限指標點擊,鍵盤展開 / 收合用 `→` / `←`) |
+| `Cmd/Ctrl+Shift+↑` / `↓` | 重排:同層上移 / 下移(僅 `draggable` 時;詳「Drag and Drop → 鍵盤重排」) |
+| `Cmd/Ctrl+Shift+→` | 重排:移入上一個 sibling(需為 folder;收合時自動展開) |
+| `Cmd/Ctrl+Shift+←` | 重排:移出,成為 parent 的下一個 sibling |
 
-遵循 [WAI-ARIA TreeView pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)。
+遵循 [WAI-ARIA TreeView pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)。重排鍵位在 modifier 層,與 APG 導覽鍵完全正交(APG 無 drag-and-drop pattern,重排屬 application-level 鍵位)。
 
 ---
 
@@ -248,7 +254,7 @@ Sidebar 是頁面級容器,padding 應該跟其他頁面區塊的間距一致(
 
 ## Hover-only Inline Actions
 
-TreeItem 右側 `actions` slot 只在 hover 該列時出現(opacity 0→1 transition)。**為什麼**:(a) 視覺清潔(10+ node × 2-3 icon = 20-30 灰 icon 同屏噪音極大);(b) 業界一致(Notion / VS Code / Figma 都 hover-only);(c) 不影響操作(要操作自然會 hover)。
+TreeItem 右側 inline actions（宣告式 `inlineActions: InlineActionConfig[]` 或 escape-hatch `inlineActionsSlot`，**非** `actions` prop）預設在 hover 該列**或鍵盤 focus-visible 該列**時出現(opacity 0→1 transition)；`actionsReveal={false}` 則常駐不 hover-reveal。**為什麼**:(a) 視覺清潔(10+ node × 2-3 icon = 20-30 灰 icon 同屏噪音極大);(b) 業界一致(Notion / VS Code / Figma 都 hover-only);(c) 不影響操作(要操作自然會 hover)。
 
 **Uniform 規則**:同類型 node 的 hover action 必須完全一致,否則 discovery 失敗。
 - **⋯ (more menu)**:所有 node 統一有,menu 內容由 consumer 依 node type 動態(rename / delete / duplicate)
@@ -277,6 +283,26 @@ Icon 尺寸跟 size tier(sm/md=16, lg=20);色 `fg-muted` → hover `foreground`;
 
 **視覺**(2026-05-06 v14.5 SSOT 抽 `lib/drag-visual.ts`):被拖 node 原位 `opacity-disabled`(45%)半透明殘影 / before-after drop indicator 為 2px primary 細線(`bg-primary` `h-0.5`,left 跟 indent 深度)/ inside drop target `bg-primary-subtle` 全行背景 / DragOverlay ghost 圓角 + icon + label + **不透明 `bg-surface`** + elevation shadow(跟 surface 拉開的視覺距離靠 shadow 不靠 opacity;半透明只用在上述原位殘影)。**TreeView 是 DS 內最早 codified 的 drag canonical**,DataTable row drag + column reorder 都 inherit 此 pattern via `drag-visual.ts` SSOT module。視覺校驗見 story `DragAndDrop`。
 
+**結構安全(2026-07-14 修)**:`handleDragOver` / `handleDragEnd` 有 descendant guard(`isInSubtree`)——drop target 落在被拖 node 自己的子樹內時視同無效目標(原實作只擋 `over.id === active.id` 未擋 descendants,會發出 `targetId ∈ source 子樹` 的非法事件;consumer 按 remove→insert 實作時整個子樹會靜默消失)。鍵盤重排路徑共用同一 guard。
+
+### 鍵盤重排(2026-07-14 v1)
+
+`draggable` 啟用後,鍵盤與指標同樣可重排(WCAG 2.1.1 keyboard parity——四鍵可組合出任何 pointer 可達的合法樹位置)。鍵位 `Cmd/Ctrl+Shift+方向鍵`(對齊 [Notion 移動 block 鍵位](https://www.notion.com/help/keyboard-shortcuts),WebFetch 驗證紀錄 `.claude/logs/treeview-keyboard-dnd-design.md#L25`;[Asana](https://keycombiner.com/collections/asana/) / [Todoist](https://www.todoist.com/help/articles/use-keyboard-shortcuts-in-todoist-Wyovn2) 同「modifier+方向鍵直接移動」派),對虛擬焦點(`aria-activedescendant`)節點操作,**每按一下立即 commit**——無 grab-mode、無預覽、無 cancel(反向鍵即 undo)。**不用** dnd-kit `KeyboardSensor`:其 activator 需可接收 DOM focus([dnd-kit sensors 文件](https://dndkit.com/api-documentation/sensors/keyboard)),與單一 tab stop 虛擬焦點模型(2026-07-05 D4 拍板)結構性不相容,故為容器 `handleKeyDown` 的自建分支。
+
+| 按鍵 | 行為 | 發出事件 |
+|---|---|---|
+| `Cmd/Ctrl+Shift+↑` | 同層上移(整個子樹一起動) | `{sourceId, targetId: prevSibling, position: 'before'}` |
+| `Cmd/Ctrl+Shift+↓` | 同層下移(跳過 sibling 的子樹,不會鑽進去) | `{sourceId, targetId: nextSibling, position: 'after'}` |
+| `Cmd/Ctrl+Shift+→` | 移入上一個 sibling(需為 folder;collapsed 時自動展開——pointer 500ms hover auto-expand 的鍵盤對應物) | `{sourceId, targetId: prevSibling, position: 'inside'}` |
+| `Cmd/Ctrl+Shift+←` | 移出,成為 parent 的下一個 sibling | `{sourceId, targetId: parentId, position: 'after'}` |
+
+- **契約同 pointer**:同一個 `onDragEnd` + `TreeDragEndEvent`,consumer API 零改動。**頻率差異**:pointer 一手勢一次、keyboard 每步一次——有伺服器持久化的 consumer 建議 optimistic update(不建議 debounce batch,會破壞每按即 commit 語意)。
+- **邊界 no-op**:已在最上方 / 最下方 / 最外層、無可移入的 folder → 不發事件,只 SR 播報原因。
+- **disabled**:disabled node 不可移動,也不可當 target 錨點——相鄰 sibling disabled 時錨到最近 enabled sibling 表達同一插槽(可達位置與 pointer 一致;pointer 的 `useDroppable` 同樣 disable disabled node)。
+- **視覺**:每按即 commit,節點真實移動即回饋——**不用** dropIndicator / DragOverlay(那是「預覽中」的視覺語言,用在已 commit 的操作上會說謊);保留 keyboard focus ring 跟隨(`focusedId` 是 node id,移動後 `aria-activedescendant` 自動指向新位置)+ 移動後 `scrollIntoView`。
+- **互斥**:pointer 拖曳進行中忽略鍵盤重排;`draggable` 未啟用時整組鍵位 no-op(不落入導覽)。
+- **SR 播報**:TreeView 自有 sr-only `role="status"` polite live region(消費 `select-menu.tsx` `SelectMenuLiveStatus` 先例;單一節點覆寫式更新,快速連按只播最新)。文案 zh-TW 預設(「已將『X』移到『Y』之後,第 n 項,共 m 項」/「已將『X』移入『Y』」/「已在最上方」等),`reorderAnnouncements` prop per-key 覆寫(i18n 覆寫點),含 `instructions` sr-only 操作說明(tree 容器 `aria-describedby` 指向,僅 `draggable` 渲染)。播報為 optimistic(事件發出即播,假設 consumer 依約 reorder);移入原本收合的 folder 時序數不可知,播報省略序數。
+
 ---
 
 ## Checkbox(多選模式)
@@ -284,10 +310,10 @@ Icon 尺寸跟 size tier(sm/md=16, lg=20);色 `fg-muted` → hover `foreground`;
 多選 tree(如 file browser、permission picker)在 label 前方加 checkbox:
 
 ```
-[indent][chevron][icon?][checkbox][label][suffix?]
+[indent][chevron][checkbox?][indicator|icon?][label][suffix?]
 ```
 
-Checkbox 位於 icon 之後、label 之前。跟 MenuItem 的多選 checkbox 位置對齊。
+Checkbox 位於 chevron 之後、indicator / icon / label 之前（`tree-view.tsx` render 順序:chevron → checkbox → indicator / icon → label,見 tsx 內「Checkbox 在 icon 前」註解）。對齊 SelectMenu 多選 checkbox 慣例。
 
 單選模式不需要 checkbox——用 `bg-neutral-selected` 背景色表達選中。
 
@@ -338,7 +364,7 @@ TreeItem props slots(consumer 決定 node 視覺):
 
 ## Anatomy story 涵蓋
 
-TreeView 是**階層樹元件**,關鍵決策維度是 selection × expanded × indent × size × context(sidebar / panel / dialog)。`Inspector` 提供互動式 Controls(size / context / selectionMode / expandOnSelect)即時切換,搭配 `SizeMatrix` / `ColorMatrix` / 元件特有 `IndentMatrix`(縮排規則) / `StateBehavior`(selected vs expanded 語意分離) / `KeyboardMatrix` / `Accessibility` 完整覆蓋。
+TreeView 是**階層樹元件**,關鍵決策維度是 selection × expanded × indent × size × context(`'sidebar'` / `'menu'`——`tree-view.tsx` `TreeContext` 僅此兩值)。`Inspector` 提供互動式 Controls(size / context / selectionMode / expandOnSelect)即時切換,搭配 `SizeMatrix` / `ColorMatrix` / 元件特有 `IndentMatrix`(縮排規則) / `StateBehavior`(selected vs expanded 語意分離) / `KeyboardMatrix` / `Accessibility` 完整覆蓋。
 
 TreeView 真實展示需要**多層巢狀結構**才有意義(單節點無法體現樹形設計),故 `Inspector` 以真實的 Engineering 團隊檔案樹為 render 對象;`IndentMatrix`(縮排與 guide line 規則)、`StateBehavior`(selected + expanded 正交語意)這類需要完整樹形視覺才能傳達的設計則另以靜態矩陣呈現。
 
@@ -365,9 +391,9 @@ TreeView 真實展示需要**多層巢狀結構**才有意義(單節點無法體
 
 ## A11y 預設
 
-**ARIA / Pattern**:自建 ARIA tree(非沿用 Radix 預設)。容器 `role="tree"`(多選時加 `aria-multiselectable`),每個 node `role="treeitem"` + `aria-expanded`(expandable 才有)/ `aria-selected` / `aria-level`,皆由元件手動設定(`tree-view.tsx` L901-905)。Radix `collapsible` 僅用於 children 展開 / 收合的高度動畫,**不提供** tree 的 role / aria / 鍵盤導覽(Radix 沒有 Tree primitive,見「定位」段)。對齊 [WAI-ARIA TreeView pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)。`aria-setsize` / `aria-posinset` **刻意省略**:APG 規定只有當節點未全數 render 進 DOM(lazy load)或 DOM 序 ≠ 閱讀序時才必需;本元件全可見節點皆在 DOM(`querySelectorAll('[role="treeitem"]:not([hidden])')`)且 DOM 序 = 閱讀序,故非必需。
+**ARIA / Pattern**:自建 ARIA tree(非沿用 Radix 預設)。容器 `role="tree"`(多選時加 `aria-multiselectable`),每個 node `role="treeitem"` + `aria-expanded`(expandable 才有)/ `aria-selected` / `aria-level`,皆由元件手動設定(`tree-view.tsx` TreeItem render)。Radix `collapsible` 僅用於 children 展開 / 收合的高度動畫,**不提供** tree 的 role / aria / 鍵盤導覽(Radix 沒有 Tree primitive,見「定位」段)。對齊 [WAI-ARIA TreeView pattern](https://www.w3.org/WAI/ARIA/apg/patterns/treeview/)。`aria-setsize` / `aria-posinset` **刻意省略**:APG 規定只有當節點未全數 render 進 DOM(lazy load)或 DOM 序 ≠ 閱讀序時才必需;本元件全可見節點皆在 DOM(`querySelectorAll('[role="treeitem"]:not([hidden])')`)且 DOM 序 = 閱讀序,故非必需。
 
-**Keyboard 行為**(自建 handler,`tree-view.tsx` L516-585):
+**Keyboard 行為**(自建 handler,`tree-view.tsx` handleKeyDown):
 
 - Tab — 焦點進入整棵 tree(單一 tab stop)
 - ↑/↓ — 在可見 node 之間移動
@@ -375,10 +401,15 @@ TreeView 真實展示需要**多層巢狀結構**才有意義(單節點無法體
 - ← — 收合 node,leaf 則跳回 parent
 - Home / End — 跳到第一個 / 最後一個可見 node
 - Enter / Space — 選取目前 node
+- Cmd/Ctrl+Shift+↑/↓/→/← — 重排目前 node(僅 `draggable` 時;上下 = 同層移動、→ = 移入 folder、← = 移出到上層,詳「鍵盤重排」段)
 
 **Focus**:焦點由元件自管(`aria-activedescendant` virtual focus,非 roving tabindex)——DOM focus 固定停在 tree 容器(單一 tab stop,root `tabIndex={0}`),鍵盤移動時 `aria-activedescendant` 指向目前 node,並用內描邊高亮標示(`ring-2 ring-ring ring-inset`,非 `outline`)。**無** focus trap、**無** focus restoration(tree 不是浮層,不需要)。
 
-**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作(無需滑鼠)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
+**「單一 tab stop」範圍限樹的 node 導覽**:auto-render checkbox 已 `tabIndex={-1}` 收進虛擬焦點(不佔 tab 序);但公開 `inlineActions` / `inlineActionsSlot` 經 `ItemInlineAction` 渲染的原生 `<button>` 是各自獨立的 tab stop(對齊 GitHub / VS Code 檔案樹「row action 可 Tab」慣例)。故當某列有 inline actions 時,整頁 Tab 序會依序停在這些按鈕上——「單一 tab stop」指的是**樹形節點導覽**進出點,非「整棵樹含 action 只有一個 tab 停靠」。
+
+**SR 播報(重排)**:鍵盤重排結果經 TreeView 自有 sr-only `role="status"` polite live region 播報,tree 容器 `aria-describedby` 指向 sr-only 操作說明(兩者僅 `draggable` 時渲染、皆在 `role="tree"` 之外——tree 的合法 children 只有 treeitem / group);文案可經 `reorderAnnouncements` prop 覆寫,詳「鍵盤重排」段。
+
+**驗證**:Storybook a11y addon panel 應 0 critical violation;鍵盤完整可操作導覽 / 選取 / 展開收合 / **拖曳重排**(無需滑鼠;2026-07-14 v1 補齊——重排走容器 handleKeyDown 的 `Cmd/Ctrl+Shift+方向鍵` 分支,非 dnd-kit `KeyboardSensor`,sensors 仍僅 `PointerSensor`,見「鍵盤重排」段)。WCAG AA contrast ≥ 4.5:1(text)/ 3:1(UI)。
 
 ## 被引用(auto-maintained,Dim 3 reciprocal audit)
 

package/src/components/TreeView/tree-view.stories.tsx

@@ -227,6 +227,7 @@ export const DragAndDrop: Story = {
         <div className="flex flex-col gap-2">
           <p className="text-caption text-fg-muted max-w-xs">
             Figma 風格:整列拖曳,items 真的會移動。拖到其他 node 上方(before) / 下方(after) / 中間(inside 成為子項)。
+            鍵盤同樣可重排:Tab 聚焦樹、↑↓ 移到目標後,Cmd/Ctrl+Shift+↑↓ 同層移動、→ 移入資料夾、← 移出到上層(每按一下立即生效,結果會播報給螢幕閱讀器)。
           </p>
           <div className="w-[280px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
             <TreeView