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

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

@@ -18,6 +18,7 @@ import { cva } from 'class-variance-authority'
 import type { LucideIcon } from 'lucide-react'
 import { dragSourceClass, dropIndicatorRow, dropIndicatorInside } from '@/design-system/lib/drag-visual'
 import { cn } from '@/lib/utils'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
 // Row primitive 共用常數——單一 source of truth
 import {
   ICON_SIZE,
@@ -69,7 +70,7 @@ const CONTEXT_PX_VAR: Record<TreeContext, string> = {
 
 /** Drag drop position — 拖放目標的三種位置 */
 // code-quality-allow: dead-export — public event/state type — consumer event handler parameter type
-export type DropPosition = 'before' | 'after' | 'inside'
+export type TreeDropPosition = 'before' | 'after' | 'inside'
 
 /** onDragEnd callback 的參數 */
 // code-quality-allow: dead-export — public event/state type — consumer event handler parameter type
@@ -79,7 +80,26 @@ export interface TreeDragEndEvent {
   /** 目標 node id */
   targetId: string
   /** 放置位置:before(同層上方)/ after(同層下方)/ inside(成為子 node) */
-  position: DropPosition
+  position: TreeDropPosition
+}
+
+/**
+ * 鍵盤重排(`Cmd/Ctrl+Shift+方向鍵`,2026-07-14 v1)的 SR 播報文案 — zh-TW 預設,
+ * per-key merge 覆寫(i18n 覆寫點)。詳 tree-view.spec.md「鍵盤重排」。
+ * @public
+ */
+// code-quality-allow: dead-export — public prop type — consumer 覆寫播報文案的參數型別
+export interface TreeReorderAnnouncements {
+  /** 同層上/下移完成。`index` / `count` = 移動後在同層的 1-based 序數 / 同層總數 */
+  moved?: (args: { label: string; targetLabel: string; position: 'before' | 'after'; index: number; count: number }) => string
+  /** 移入 folder 完成。folder 原本收合(children 尚未 mount)時序數不可知 → `index` / `count` 為 undefined */
+  movedInside?: (args: { label: string; folderLabel: string; index?: number; count?: number }) => string
+  /** 移出到上層完成。`level` = 移動後所在層(1-based,同 aria-level 語意) */
+  movedOut?: (args: { label: string; parentLabel: string; level: number }) => string
+  /** 邊界 no-op:top(已在最上方)/ bottom(已在最下方)/ not-folder(無可移入的 folder)/ root(已在最外層) */
+  blocked?: (args: { reason: 'top' | 'bottom' | 'not-folder' | 'root'; label: string; targetLabel?: string }) => string
+  /** sr-only 操作說明(tree 容器 `aria-describedby` 指向;僅 `draggable` 時渲染) */
+  instructions?: string
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -89,12 +109,44 @@ export interface TreeDragEndEvent {
 // Icon / chevron 尺寸——從 item-layout pattern module 引入(在檔頂 import),
 // 這裡本地不再宣告。所有 row primitives 共用同一個常數。
 
-// indentStep = chevronSize + gap-2(8px)— 2026-05-04 升 SSOT 為 token `--tree-indent-{sm,md,lg}`
-// 在 `tokens/uiSize/uiSize.css`。DataTable nested rows 共用此 SSOT,跨元件視覺一致。
-// 結構對齊:子 chevron 對齊父 icon,子 icon 對齊父 label。
-// Numeric value 此處保留(drop indicator JS px 計算需 number),Tailwind class 走 token。
+// indentStep = chevronSize + gap-2(8px)。值 {24,24,28} 與 CSS token `--tree-indent-{sm,md,lg}`
+// (`tokens/uiSize/uiSize.css`)**完全一致、必須同步維護**(改一處要兩處一起改;非「token 取代 literal」)。
+// 為何兩源並存:本元件 render 用此 JS literal 算 `indentPx`(TreeItem inline calc 需 number)+ drop-indicator
+// pointer 數學(handleDragOver px 命中判斷,CSS var 在 JS 計算層拿不到);DataTable nested rows
+// 則走 CSS token 的 Tailwind class(跨元件視覺一致)。結構對齊:子 chevron 對齊父 icon,子 icon 對齊父 label。
 const INDENT_STEP: Record<SizeKey, number> = { sm: 24, md: 24, lg: 28 }
 
+// ── 鍵盤重排(keyboard reorder,2026-07-14 v1)常數 ──
+// 鍵位 = Cmd/Ctrl+Shift+方向鍵,對齊 Notion 移動 block 鍵位(https://www.notion.com/help/keyboard-shortcuts,
+// WebFetch 驗證紀錄 .claude/logs/treeview-keyboard-dnd-design.md#L25);
+// modifier 層與 APG tree 導覽鍵(無 modifier 的 ↑↓→←)完全正交,零衝突。
+const REORDER_ARROW_KEYS = ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight']
+type ReorderArrowKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight'
+
+// 鍵盤重排 SR 播報預設文案(zh-TW;consumer 經 `reorderAnnouncements` prop per-key 覆寫)。
+// 格式 =「結果 + 序數位置」— 非視覺使用者靠「第 n 項,共 m 項」建立位置模型
+// (世界級 cite 詳 tree-view.spec.md「鍵盤重排」段,M22)。
+// i18n-allow-block: DS default SR-only 播報文案,prop 可覆寫(同 select-menu.tsx SelectMenuLiveStatus 先例)
+const DEFAULT_REORDER_ANNOUNCEMENTS: Required<TreeReorderAnnouncements> = {
+  moved: ({ label, targetLabel, position, index, count }) =>
+    `已將『${label}』移到『${targetLabel}』${position === 'before' ? '之前' : '之後'},第 ${index} 項,共 ${count} 項`,
+  movedInside: ({ label, folderLabel, index, count }) =>
+    index !== undefined && count !== undefined
+      ? `已將『${label}』移入『${folderLabel}』,第 ${index} 項,共 ${count} 項`
+      : `已將『${label}』移入『${folderLabel}』`,
+  movedOut: ({ label, parentLabel, level }) =>
+    `已將『${label}』移出到『${parentLabel}』之後,第 ${level} 層`,
+  blocked: ({ reason, targetLabel }) => {
+    switch (reason) {
+      case 'top': return '已在最上方'
+      case 'bottom': return '已在最下方'
+      case 'not-folder': return targetLabel ? `無法移入:『${targetLabel}』不是資料夾` : '無法移入'
+      case 'root': return '已在最外層'
+    }
+  },
+  instructions: '按 Cmd(Ctrl)+Shift+方向鍵可重新排列項目',
+}
+
 // ═══════════════════════════════════════════════════════════════════════════
 // Context
 // ═══════════════════════════════════════════════════════════════════════════
@@ -106,16 +158,24 @@ interface TreeViewContextValue {
   expandOnSelect: boolean
   draggable: boolean
   isKeyboardRef: React.RefObject<boolean>
+  /**
+   * Per-tree instance 前綴(React.useId),用來組每個 treeitem 的 DOM `id`
+   * (`${prefix}treeitem-${nodeId}`),讓容器的 `aria-activedescendant` 能指向目前 focused node。
+   * 多棵 TreeView 同頁 / node id 跨樹重複時不會撞 DOM id。
+   */
+  activeDescendantPrefix: string
   expandedIds: Set<string>
   selectedIds: Set<string>
   focusedId: string | null
   /** 目前拖曳中的 node id(null = 沒在拖) */
   draggingId: string | null
   /** 目前 drop indicator 的位置 + depth(用於 line indent) */
-  dropTarget: { id: string; position: DropPosition; depth: number } | null
+  dropTarget: { id: string; position: TreeDropPosition; depth: number } | null
   toggleExpand: (id: string) => void
   select: (id: string) => void
   setFocusedId: (id: string | null) => void
+  /** Pointer activation 後把 DOM focus 還給 virtual-focus tree root。 */
+  focusTree: () => void
   registerNode: (id: string, parentId: string | null, hasChildren: boolean, label?: React.ReactNode, icon?: LucideIcon) => void
   getNodeInfo: (id: string) => NodeInfo | undefined
   unregisterNode: (id: string) => void
@@ -173,7 +233,7 @@ export interface TreeViewProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   size?: SizeKey
   /**
    * 使用脈絡,決定 item 的水平 padding:
-   * - `'sidebar'`(預設):頁面側邊欄,px-2(8px)
+   * - `'sidebar'`(預設):頁面側邊欄,`--layout-space-loose`(md=16px / lg=24px,隨 density 連動)
    * - `'menu'`:浮層選單 / dropdown,px-3(12px),對齊 MenuItem
    */
   context?: TreeContext
@@ -195,13 +255,19 @@ export interface TreeViewProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   defaultSelectedIds?: string[]
   /**
    * 啟用拖曳排序。預設 false。
-   * 啟用後每個 TreeItem 左側出現 drag handle(GripVertical icon),
+   * 啟用後整列可拖(Figma 風格,無 grip handle;靠 distance:5 區分 click vs drag),
    * 拖曳時顯示 drop indicator(before / after / inside 三種位置)。
    * Consumer 透過 `onDragEnd` callback 接收 reorder 事件,自行更新 data。
    */
   draggable?: boolean
   /** Drag 結束時觸發,提供 sourceId、targetId、position。Consumer 負責 reorder。 */
   onDragEnd?: (event: TreeDragEndEvent) => void
+  /**
+   * 鍵盤重排(`Cmd/Ctrl+Shift+方向鍵`)的 SR 播報文案覆寫(per-key merge;zh-TW 預設)。
+   * 僅在 `draggable` 時生效;含 `instructions`(sr-only 操作說明)。
+   * @public
+   */
+  reorderAnnouncements?: TreeReorderAnnouncements
   /** ARIA label */
   'aria-label'?: string
 }
@@ -216,6 +282,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
       expandOnSelect = false,
       draggable = false,
       onDragEnd: onDragEndProp,
+      reorderAnnouncements: reorderAnnouncementsProp,
       expandedIds: controlledExpanded,
       onExpandedChange,
       selectedIds: controlledSelected,
@@ -228,6 +295,25 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
     },
     ref
   ) => {
+    // ── Accessible name dev-warn(2026-07-18:兌現 spec「Accessible name 必填契約」段承諾 —
+    //    原 spec 宣稱有此 console.warn 但 code 缺,spec-code drift;補上使兩者一致)──
+    //    role="tree" 名稱無法從子節點推導,缺 aria-label / aria-labelledby → SR 只讀「tree」。
+    //    對齊 Button / Tag 的 dev-only 誤用警告 idiom;production 不觸發。
+    const ariaLabel = props['aria-label']
+    const ariaLabelledby = props['aria-labelledby']
+    React.useEffect(() => {
+      if (
+        process.env.NODE_ENV !== 'production' &&
+        ariaLabel == null &&
+        ariaLabelledby == null
+      ) {
+        console.warn(
+          '[DS] TreeView:role="tree" 缺 accessible name — 請傳 aria-label(直接字串)或 aria-labelledby(指向可見標題 id)其一。' +
+            '兩者皆缺時螢幕閱讀器只讀出「tree」無法辨識用途(WAI-ARIA APG 要求 role="tree" 具 accessible name)。',
+        )
+      }
+    }, [ariaLabel, ariaLabelledby])
+
     // ── Expand state(受控 / 非受控) ──
     const [internalExpanded, setInternalExpanded] = React.useState(
       () => new Set(defaultExpandedIds)
@@ -272,6 +358,29 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
 
     // ── Focus state ──
     const [focusedId, setFocusedId] = React.useState<string | null>(null)
+    const treeRef = React.useRef<HTMLDivElement>(null)
+    React.useImperativeHandle(ref, () => treeRef.current!)
+    const focusTree = React.useCallback(() => {
+      treeRef.current?.focus({ preventScroll: true })
+    }, [])
+
+    // ── Virtual focus id prefix ──
+    // DOM focus 永遠停在 role=tree 容器(單一 tab stop);目前 node 透過 aria-activedescendant
+    // 告知 AT(對齊 DS 既有 cmdk virtual-focus canonical:SelectMenu / Command listbox)。
+    // useId 確保多棵 TreeView 同頁 / node id 跨樹重複時 DOM id 不撞。
+    const activeDescendantPrefix = React.useId()
+
+    // ── 鍵盤重排 SR 播報(2026-07-14 v1;詳 spec「鍵盤重排」)──
+    // 單一 polite live region 覆寫式更新(textContent 替換非 append → 快速連按天然只播最新)。
+    // 不可借 dnd-kit DndContext 內建 live region — 它只播 dnd-kit 管理的 drag session,
+    // 自建鍵盤路徑觸不到。消費 select-menu.tsx SelectMenuLiveStatus role="status" 先例。
+    const [reorderAnnouncement, setReorderAnnouncement] = React.useState('')
+    const announcements = React.useMemo(
+      () => ({ ...DEFAULT_REORDER_ANNOUNCEMENTS, ...reorderAnnouncementsProp }),
+      [reorderAnnouncementsProp]
+    )
+    // sr-only 操作說明節點 id(tree 容器 aria-describedby 指向;僅 draggable 渲染)
+    const reorderInstructionsId = `${activeDescendantPrefix}tree-reorder-instructions`
 
     // ── Keyboard vs mouse detection ──
     // focus ring 只在鍵盤操作時顯示,滑鼠點擊用 bg-neutral-selected 表達選中,不顯示 ring
@@ -279,7 +388,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
 
     // ── Drag state ──
     const [draggingId, setDraggingId] = React.useState<string | null>(null)
-    const [dropTarget, setDropTarget] = React.useState<{ id: string; position: DropPosition; depth: number } | null>(null)
+    const [dropTarget, setDropTarget] = React.useState<{ id: string; position: TreeDropPosition; depth: number } | null>(null)
     const autoExpandTimerRef = React.useRef<ReturnType<typeof setTimeout> | null>(null)
     // 2026-05-16 audit codex Round 6:unmount cleanup(原 cleanup 只在 dragEnd/dragCancel,unmount-during-drag 漏 cancel)
     React.useEffect(() => () => { if (autoExpandTimerRef.current) clearTimeout(autoExpandTimerRef.current) }, [])
@@ -287,6 +396,26 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
     // 用 ref 打斷 temporal dead zone。
     const toggleExpandRef = React.useRef<(id: string) => void>(() => {})
 
+    // ── Node registry ──(2026-07-14 上移至 drag handlers 之前:isInSubtree 消費 getNodeInfo,
+    // 而 handleDragOver / handleDragEnd / 鍵盤 reorder 都消費 isInSubtree)
+    const { registerNode, unregisterNode, getNodeInfo } = useNodeRegistry()
+
+    // 子樹判定:candidate 是否位於 rootId 的子樹內(含相等)。沿 registry parentId 鏈上溯。
+    // 雙路共用 SSOT:pointer 路徑 descendant drop guard(2026-07-14 R6 修:原 handleDragOver 只擋
+    // `over.id === active.id` 未擋 descendants → 可發出 targetId ∈ source 子樹的非法事件,
+    // consumer 按 remove→insert 實作會讓整個子樹靜默消失)+ 鍵盤 reorder commit 前防禦 assert。
+    const isInSubtree = React.useCallback(
+      (candidateId: string, rootId: string): boolean => {
+        let cur: string | null = candidateId
+        while (cur != null) {
+          if (cur === rootId) return true
+          cur = getNodeInfo(cur)?.parentId ?? null
+        }
+        return false
+      },
+      [getNodeInfo]
+    )
+
     const sensors = useSensors(
       useSensor(PointerSensor, { activationConstraint: { distance: 5 } })
     )
@@ -309,7 +438,10 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
     //
     const handleDragOver = React.useCallback((event: DragOverEvent) => {
       const { over, active } = event
-      if (!over || over.id === active.id) {
+      // 2026-07-14 R6 descendant guard:over 是 active 自己「或其子樹內節點」→ 無效目標,
+      // 不設 dropTarget(拖 folder 進自己子樹會發出非法 TreeDragEndEvent;guard SSOT = isInSubtree,
+      // 鍵盤 reorder 路徑共用同一 helper)。
+      if (!over || isInSubtree(String(over.id), String(active.id))) {
         if (autoExpandTimerRef.current) { clearTimeout(autoExpandTimerRef.current); autoExpandTimerRef.current = null }
         setDropTarget(null)
         return
@@ -339,7 +471,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
       const indentStep = INDENT_STEP[size]
       const pointerIndentLevel = Math.max(0, Math.floor((currentX - treeLeft) / indentStep))
 
-      let position: DropPosition
+      let position: TreeDropPosition
       let finalDepth = targetDepth
 
       if (hasChildren) {
@@ -369,14 +501,19 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
             if (parentId && parentId !== String(active.id)) {
               const parentDepth = Number(parentTreeItem?.getAttribute('aria-level') ?? 1) - 1
               finalDepth = parentDepth
-              setDropTarget({ id: parentId, position: 'after', depth: parentDepth })
+              setDropTarget(prev => prev && prev.id === parentId && prev.position === 'after' && prev.depth === parentDepth ? prev : { id: parentId, position: 'after', depth: parentDepth })
               return
             }
           }
         }
       }
 
-      setDropTarget({ id: String(over.id), position, depth: finalDepth })
+      // 2026-07-06 D3 perf:bail-out — drop target 未變(每 dragOver 跨 row 才變)時回傳 prev,
+      // React 對相同 reference bail out,避免每次 over 事件重建 contextValue → 全樹 TreeItem re-render。
+      setDropTarget(prev => {
+        const id = String(over.id)
+        return prev && prev.id === id && prev.position === position && prev.depth === finalDepth ? prev : { id, position, depth: finalDepth }
+      })
 
       // Auto-expand collapsed folder after 500ms hover (Figma behavior)
       if (position === 'inside' && hasChildren && !expandedIds.has(String(over.id))) {
@@ -387,7 +524,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
       } else {
         if (autoExpandTimerRef.current) { clearTimeout(autoExpandTimerRef.current); autoExpandTimerRef.current = null }
       }
-    }, [expandedIds])
+    }, [expandedIds, isInSubtree])
 
     const dropTargetRef = React.useRef(dropTarget)
     dropTargetRef.current = dropTarget
@@ -396,7 +533,8 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
       if (autoExpandTimerRef.current) { clearTimeout(autoExpandTimerRef.current); autoExpandTimerRef.current = null }
       const { active, over } = event
       const dt = dropTargetRef.current
-      if (over && active.id !== over.id && dt) {
+      // descendant guard 同 handleDragOver(dt 已由 dragOver guard 保證為 null,此為 belt-and-braces)
+      if (over && !isInSubtree(String(over.id), String(active.id)) && dt) {
         onDragEndProp?.({
           sourceId: String(active.id),
           targetId: String(over.id),
@@ -405,7 +543,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
       }
       setDraggingId(null)
       setDropTarget(null)
-    }, [onDragEndProp])
+    }, [onDragEndProp, isInSubtree])
 
     const handleDragCancel = React.useCallback(() => {
       if (autoExpandTimerRef.current) { clearTimeout(autoExpandTimerRef.current); autoExpandTimerRef.current = null }
@@ -413,9 +551,6 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
       setDropTarget(null)
     }, [])
 
-    // ── Node registry ──
-    const { registerNode, unregisterNode, getNodeInfo } = useNodeRegistry()
-
     // ── Actions ──
     const toggleExpand = React.useCallback(
       (id: string) => {
@@ -447,6 +582,168 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
       [selectionMode, setSelectedIds]
     )
 
+    // ── Keyboard reorder(Cmd/Ctrl+Shift+方向鍵,2026-07-14 v1)──
+    // 設計 SSOT:tree-view.spec.md「鍵盤重排」。與 pointer 路徑共用 TreeDragEndEvent 契約 +
+    // onDragEnd prop + registry(consumer API 零改動);每按一下立即 commit(無 grab-mode /
+    // 無預覽,對齊 Notion Cmd/Ctrl+Shift+Arrow 移動 block:https://www.notion.com/help/keyboard-shortcuts,
+    // WebFetch 驗證紀錄 .claude/logs/treeview-keyboard-dnd-design.md#L25)。
+    // 不用 dnd-kit KeyboardSensor — 其 activator 需可接收 DOM focus
+    // (https://dndkit.com/api-documentation/sensors/keyboard),與 row tabIndex={-1} +
+    // aria-activedescendant 虛擬焦點模型結構性不相容(2026-07-05 D4 拍板不翻案)。
+
+    // 播報用 label 文字:registry label 是 ReactNode — string 直接用,否則退 DOM row textContent。
+    const getNodeLabelText = React.useCallback(
+      (id: string): string => {
+        const info = getNodeInfo(id)
+        if (typeof info?.label === 'string') return info.label
+        const rowEl = treeRef.current?.querySelector<HTMLElement>(`[data-tree-row="${id}"]`)
+        return rowEl?.textContent?.trim() || id
+      },
+      [getNodeInfo]
+    )
+
+    // code-quality-allow: long-function — 四鍵語意(同層上下 / 移入 / 移出)+ 邊界播報結構緊密,
+    // 拆 sub-fn 會跨 fn 傳 siblings / announce state 反而複雜(同 handleKeyDown 先例)
+    const handleKeyboardReorder = React.useCallback(
+      (key: ReorderArrowKey) => {
+        const tree = treeRef.current
+        if (!tree || !focusedId) return
+        const sourceId = focusedId
+        const sourceEl = tree.querySelector<HTMLElement>(`[data-tree-id="${sourceId}"]`)
+        // disabled node 不可移(鍵盤導覽本就跳過 disabled,此為防禦 guard)
+        if (!sourceEl || sourceEl.getAttribute('aria-disabled') === 'true') return
+
+        const label = getNodeLabelText(sourceId)
+        // 同層 siblings(DOM 序)。focused node 可見 ⇒ 其 parent 已展開 ⇒ 全 siblings 已 mount。
+        const parentId = sourceEl.dataset.treeParentId || null
+        const visibleItems = Array.from(
+          tree.querySelectorAll<HTMLElement>('[role="treeitem"]:not([hidden])')
+        )
+        const siblings = visibleItems.filter((el) => (el.dataset.treeParentId || null) === parentId)
+        const sourceIndex = siblings.findIndex((el) => el.dataset.treeId === sourceId)
+        if (sourceIndex < 0) return
+        const isEnabled = (el: HTMLElement) => el.getAttribute('aria-disabled') !== 'true'
+
+        // 發出與 pointer 路徑同型的 TreeDragEndEvent,並排定 re-render 後 scrollIntoView
+        // (既有 effect 只在 isFocused 變化時跑;同 id 移動不 re-fire,故此處補)。
+        const commit = (targetId: string, position: TreeDropPosition): boolean => {
+          // 結構安全 assert:四鍵語意(sibling 間 / 進 prev sibling / 出 parent)結構上
+          // 不可能移進自己子樹;防禦性仍擋(與 pointer descendant guard 共用 isInSubtree SSOT)。
+          if (targetId === sourceId || isInSubtree(targetId, sourceId)) return false
+          onDragEndProp?.({ sourceId, targetId, position })
+          requestAnimationFrame(() => {
+            treeRef.current
+              ?.querySelector<HTMLElement>(`[data-tree-id="${sourceId}"]`)
+              ?.scrollIntoView({ block: 'nearest' })
+          })
+          return true
+        }
+
+        // 同層移動後的 1-based 新序數(播報用):移除 source 再插入的模擬;同層總數不變。
+        const movedIndex = (targetId: string, position: 'before' | 'after'): number => {
+          const order = siblings.map((el) => el.dataset.treeId).filter((id) => id !== sourceId)
+          const tIdx = order.indexOf(targetId)
+          return (position === 'before' ? tIdx : tIdx + 1) + 1
+        }
+
+        switch (key) {
+          case 'ArrowUp':
+          case 'ArrowDown': {
+            // disabled sibling 不可當 target 錨點(pointer useDroppable 同樣 disable)——
+            // 相鄰 sibling disabled 時錨到最近 enabled sibling 並翻轉 before/after 表達同一插槽
+            // (可達位置與 pointer 一致);整個方向皆無 enabled sibling → 視同邊界。
+            const dir = key === 'ArrowUp' ? -1 : 1
+            const boundary = dir < 0 ? ('top' as const) : ('bottom' as const)
+            const adjacent = siblings[sourceIndex + dir]
+            if (!adjacent) {
+              setReorderAnnouncement(announcements.blocked({ reason: boundary, label }))
+              return
+            }
+            let target: HTMLElement | undefined
+            let position: 'before' | 'after' = dir < 0 ? 'before' : 'after'
+            if (isEnabled(adjacent)) {
+              target = adjacent
+            } else {
+              for (let i = sourceIndex + dir; i >= 0 && i < siblings.length; i += dir) {
+                if (isEnabled(siblings[i])) { target = siblings[i]; break }
+              }
+              position = dir < 0 ? 'after' : 'before' // 錨到最近 enabled sibling 的另一側 = 相鄰插槽
+            }
+            if (!target) {
+              setReorderAnnouncement(announcements.blocked({ reason: boundary, label }))
+              return
+            }
+            const targetId = target.dataset.treeId!
+            if (commit(targetId, position)) {
+              setReorderAnnouncement(
+                announcements.moved({
+                  label,
+                  targetLabel: getNodeLabelText(targetId),
+                  position,
+                  index: movedIndex(targetId, position),
+                  count: siblings.length,
+                })
+              )
+            }
+            return
+          }
+          case 'ArrowRight': {
+            // 移入:成為最近 enabled 上一 sibling 的子項(沿用 pointer「inside 限 folder」規則)
+            let target: HTMLElement | undefined
+            for (let i = sourceIndex - 1; i >= 0; i--) {
+              if (isEnabled(siblings[i])) { target = siblings[i]; break }
+            }
+            if (!target) {
+              setReorderAnnouncement(announcements.blocked({ reason: 'not-folder', label }))
+              return
+            }
+            const targetId = target.dataset.treeId!
+            if (target.dataset.treeHasChildren !== 'true') {
+              setReorderAnnouncement(
+                announcements.blocked({ reason: 'not-folder', label, targetLabel: getNodeLabelText(targetId) })
+              )
+              return
+            }
+            const wasExpanded = expandedIds.has(targetId)
+            if (commit(targetId, 'inside')) {
+              // 移入 collapsed folder:允許 + 自動展開(pointer 500ms hover auto-expand 的鍵盤對應物)
+              if (!wasExpanded) toggleExpand(targetId)
+              // 序數:consumer 對 inside 的慣例語意 = append 到 children 尾端;
+              // folder 原收合 → children 未 mount 無從計數 → 播報省略序數(誠實不猜)。
+              const childCount = wasExpanded
+                ? visibleItems.filter((el) => el.dataset.treeParentId === targetId).length
+                : undefined
+              setReorderAnnouncement(
+                announcements.movedInside({
+                  label,
+                  folderLabel: getNodeLabelText(targetId),
+                  index: childCount !== undefined ? childCount + 1 : undefined,
+                  count: childCount !== undefined ? childCount + 1 : undefined,
+                })
+              )
+            }
+            return
+          }
+          case 'ArrowLeft': {
+            // 移出:成為 parent 的下一個 sibling(outdent)
+            if (!parentId) {
+              setReorderAnnouncement(announcements.blocked({ reason: 'root', label }))
+              return
+            }
+            const parentEl = tree.querySelector<HTMLElement>(`[data-tree-id="${parentId}"]`)
+            const level = Number(parentEl?.getAttribute('aria-level') ?? '1')
+            if (commit(parentId, 'after')) {
+              setReorderAnnouncement(
+                announcements.movedOut({ label, parentLabel: getNodeLabelText(parentId), level })
+              )
+            }
+            return
+          }
+        }
+      },
+      [focusedId, expandedIds, toggleExpand, onDragEndProp, getNodeLabelText, isInSubtree, announcements]
+    )
+
     // ── Context value ──
     const contextValue = React.useMemo<TreeViewContextValue>(
       () => ({
@@ -456,6 +753,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         expandOnSelect,
         draggable,
         isKeyboardRef,
+        activeDescendantPrefix,
         draggingId,
         dropTarget,
         expandedIds,
@@ -464,6 +762,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         toggleExpand,
         select,
         setFocusedId,
+        focusTree,
         registerNode,
         unregisterNode,
         getNodeInfo,
@@ -475,6 +774,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         expandOnSelect,
         draggable,
         isKeyboardRef,
+        activeDescendantPrefix,
         draggingId,
         dropTarget,
         expandedIds,
@@ -483,6 +783,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         toggleExpand,
         select,
         setFocusedId,
+        focusTree,
         registerNode,
         unregisterNode,
         getNodeInfo,
@@ -490,9 +791,6 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
     )
 
     // ── Keyboard handler ──
-    const treeRef = React.useRef<HTMLDivElement>(null)
-    React.useImperativeHandle(ref, () => treeRef.current!)
-
     const handleMouseDown = React.useCallback(() => {
       isKeyboardRef.current = false
     }, [])
@@ -503,14 +801,44 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         isKeyboardRef.current = true
         if (!treeRef.current) return
 
+        // ── 互動 descendant 自理鍵盤(先於導覽 / 重排分支)──
+        // 公開 inlineActions / inlineActionsSlot 經 <ItemInlineAction> 渲染的原生 <button>
+        // (及 consumer slot 內的 link / field / role=button)是各自獨立的 tab stop(spec
+        // A11y「單一 tab stop」段)。其 Enter/Space/方向鍵應由該控件自理——若冒泡到容器
+        // handleKeyDown,下方 Enter/Space 分支的 e.preventDefault()+select() 會吃掉 button
+        // 原生啟動並誤選 tree node。虛擬焦點模型下 tree 導覽/重排只在事件來自容器本身時處理
+        // (DOM focus 停在 tree 容器;treeitem row / chevron / checkbox 皆 tabIndex=-1)。
+        const keyTarget = e.target as HTMLElement | null
+        if (keyTarget && keyTarget !== e.currentTarget) {
+          const interactive = keyTarget.closest<HTMLElement>(
+            'a[href], button, input, select, textarea, [contenteditable="true"], [tabindex]:not([tabindex="-1"])'
+          )
+          // interactive === e.currentTarget:唯一可聚焦祖先是 tree 容器(tabIndex=0 單一 tab
+          // stop 進出點)→ 屬非互動 descendant,照常走 tree 導覽。
+          if (interactive && interactive !== e.currentTarget) return
+        }
+
+        // ── 鍵盤重排:Cmd/Ctrl+Shift+方向鍵(2026-07-14 v1,詳 spec「鍵盤重排」)──
+        // 必排在下方「無焦點時方向鍵先聚焦第一項」分支之前(該分支不分 modifier 攔 Arrow*);
+        // 非 modifier 導覽路徑(下方 switch)完全不變。
+        if ((e.metaKey || e.ctrlKey) && e.shiftKey && REORDER_ARROW_KEYS.includes(e.key)) {
+          if (!draggable) return // 未啟用拖曳 → 整組 no-op(modifier 組合不落入導覽 switch)
+          e.preventDefault() // 阻止瀏覽器原生行為(捲動 / 文字選取)
+          if (draggingId !== null) return // pointer 拖曳進行中 → 互斥,忽略鍵盤重排
+          handleKeyboardReorder(e.key as ReorderArrowKey)
+          return
+        }
+
         // 取得所有可見的 treeitem
         const items = Array.from(
-          treeRef.current.querySelectorAll<HTMLElement>('[role="treeitem"]:not([hidden])')
+          // a11y:排除 disabled 節點 → 鍵盤導覽/選取/展開全跳過(APG:disabled 不可鍵盤操作)
+          treeRef.current.querySelectorAll<HTMLElement>('[role="treeitem"]:not([hidden]):not([aria-disabled="true"])')
         )
         const currentIndex = items.findIndex(
           (el) => el.dataset.treeId === focusedId
         )
-        if (currentIndex < 0 && items.length > 0 && ['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(e.key)) {
+        // a11y:沒焦點時任一方向鍵先聚焦第一個(含 ArrowLeft/Right,原漏 → AT 無 activedescendant 可讀)
+        if (currentIndex < 0 && items.length > 0 && ['ArrowDown', 'ArrowUp', 'ArrowLeft', 'ArrowRight', 'Home', 'End'].includes(e.key)) {
           // 沒有焦點時,任何方向鍵先聚焦第一個
           setFocusedId(items[0].dataset.treeId ?? null)
           e.preventDefault()
@@ -582,14 +910,26 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
           }
         }
       },
-      [focusedId, expandedIds, toggleExpand, select, setFocusedId]
+      [focusedId, expandedIds, toggleExpand, select, setFocusedId, draggable, draggingId, handleKeyboardReorder]
     )
 
     const treeEl = (
       <div
+        // {...props} 在最前:內部 role/style(--tree-px)/onKeyDown/tabIndex 必須勝過 consumer
+        // 誤傳(原 spread 在最後 → consumer style 會整組蓋掉 --tree-px、onKeyDown 蓋掉鍵盤導覽)
+        {...props}
         ref={treeRef}
         role="tree"
         aria-multiselectable={selectionMode === 'multiple' || undefined}
+        // Virtual focus:DOM focus 停在容器(單一 tab stop),aria-activedescendant 指向目前 node
+        // 的 DOM id,讓 AT 朗讀目前焦點 node(對齊 WAI-ARIA TreeView APG aria-activedescendant 模式)。
+        aria-activedescendant={focusedId ? `${activeDescendantPrefix}treeitem-${focusedId}` : undefined}
+        // 鍵盤重排操作說明(sr-only,僅 draggable;與 consumer 傳入的 aria-describedby 合併)
+        aria-describedby={
+          [props['aria-describedby'], draggable ? reorderInstructionsId : undefined]
+            .filter(Boolean)
+            .join(' ') || undefined
+        }
         className={cn(
           // TreeView root 不加任何 py——呼吸空間由外層容器負責:
           //   - 在 SidebarGroup 內: SidebarGroup py-2 提供
@@ -605,8 +945,18 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         } as React.CSSProperties}
         onKeyDown={handleKeyDown}
         onMouseDown={handleMouseDown}
+        // a11y APG:Tab 進入時初始化 virtual focus(優先 selected,其次第一個可用節點);
+        // 原本無 onFocus init → focusedId=null → aria-activedescendant undefined,AT 讀不到目前節點
+        onFocus={(e) => {
+          ;(props as React.HTMLAttributes<HTMLDivElement>).onFocus?.(e)
+          if (e.target === e.currentTarget && !focusedId && treeRef.current) {
+            const first =
+              treeRef.current.querySelector<HTMLElement>('[role="treeitem"][aria-selected="true"]:not([hidden]):not([aria-disabled="true"])') ??
+              treeRef.current.querySelector<HTMLElement>('[role="treeitem"]:not([hidden]):not([aria-disabled="true"])')
+            if (first) setFocusedId(first.dataset.treeId ?? null)
+          }
+        }}
         tabIndex={0}
-        {...props}
       >
         {children}
       </div>
@@ -616,7 +966,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
       <TreeViewContext.Provider value={contextValue}>
         {/* RowSizeProvider:讓 TreeView 子樹內任何 <ItemIcon> / <ItemAvatar> /
             <ItemInlineAction> 自動讀到對的 size,跟 SidebarProvider 同一條規則。
-            未來 TreeView 接 inlineActions API 後也吃這個 context。 */}
+            inlineActions API 也吃這個 context。 */}
         <RowSizeProvider value={size}>
         {/* 永遠包 DndContext(hooks 不能 conditional call)。不 draggable 時無 sensors = 不可拖 */}
         <DndContext
@@ -627,6 +977,22 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
           onDragCancel={handleDragCancel}
         >
           {treeEl}
+          {draggable && (
+            <>
+              {/* 鍵盤重排 SR 播報 — TreeView 自有 sr-only polite live region(單一節點覆寫式更新;
+                  消費 select-menu.tsx SelectMenuLiveStatus 先例)。渲染在 role="tree" 之外
+                  (tree 的合法 children 只有 treeitem / group);dnd-kit DndContext 內建 live region
+                  只播 dnd-kit drag session,自建鍵盤路徑觸不到,故必須自有。 */}
+              <div role="status" aria-live="polite" className="sr-only">
+                {reorderAnnouncement}
+              </div>
+              {/* 鍵盤重排操作說明 — tree 容器 aria-describedby 指向(對齊 dnd-kit
+                  screenReaderInstructions 慣例:https://dndkit.com/guides/accessibility) */}
+              <div id={reorderInstructionsId} className="sr-only">
+                {announcements.instructions}
+              </div>
+            </>
+          )}
           {draggable && (
             <DragOverlay dropAnimation={null}>
               {draggingId ? (() => {
@@ -691,19 +1057,21 @@ export interface TreeItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   icon?: LucideIcon
   /**
    * Checkbox(多選模式,label 前方)。傳入 ReactNode(Checkbox 元件)。
-   * 位置:在 icon 之後、label 之前。
+   * 位置:在 chevron 之後、indicator/icon 之前。
+   * 此 slot 僅是 treeitem selection 的視覺鏡像；有效 React element 會由 TreeItem
+   * 強制正規化為 `aria-hidden` + `tabIndex=-1`，不形成第二個 node tab stop。
    * 單選模式通常不需要(用 bg-neutral-selected 表達選中)。
    */
   checkbox?: React.ReactNode
   /**
-   * 右側 inline actions(suffix slot,宣告式 API)。對齊 `uiSize.spec.md`「Inline Action」
+   * 右側 inline actions(suffix slot,宣告式 API)。對齊 `patterns/element-anatomy/inline-action.spec.md`
    * 與 `SidebarMenuButton.inlineActions` 的同一條規格——TreeItem / SidebarMenuButton /
    * 未來的 row primitive 全部用同一個 declarative API。
    *
    * Consumer 只宣告 intent,TreeItem 用 `<ItemInlineAction>` 自動渲染:
    * - Icon 尺寸 = `ICON_SIZE[treeViewSize]`(自動)
    * - Hover bg、tooltip、aria-label、cursor-pointer 自動處理
-   * - **不可以**手刻 button JSX(canonical 實作在 `item-layout.tsx`)
+   * - **不可以**手刻 button JSX(canonical 實作在 `patterns/element-anatomy/item-anatomy.tsx` `ItemInlineAction`)
    *
    * ```tsx
    * <TreeItem
@@ -732,7 +1100,7 @@ export interface TreeItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
    *
    * 規則對齊 Input.endSlot canonical:90% case 用 `inlineActions` 宣告式 API,
    * 10% config 表達不出時走 slot。視覺一致性由 consumer 負責(可使用 host 內部 helper
-   * — 但禁止 app-code 直接 import L3 primitive,見 `check_l3_primitive_import.sh`)。
+   * — 但禁止 app-code 直接 import L3 primitive,見 `check_canonical_propagation.sh` E.2,原 `check_l3_primitive_import` 已 folded)。
    */
   inlineActionsSlot?: React.ReactNode
   /**
@@ -744,8 +1112,8 @@ export interface TreeItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
    */
   actionsReveal?: false | "hover"
   /**
-   * 取代 chevron 的位置。用於 stepper 的 status indicator(●/○/✓)。
-   * 設定後 chevron 不渲染,改渲染 indicator。
+   * 取代 icon 的位置。用於 stepper 的 status indicator(●/○/✓)。
+   * 設定後 icon 不渲染、改渲染 indicator;chevron 永遠保留(expandable=旋轉箭頭 / leaf=placeholder)。
    */
   indicator?: React.ReactNode
   /** 是否停用 */
@@ -756,7 +1124,7 @@ export interface TreeItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
 
 // code-quality-allow: long-function — foundational composite main body — 拆 sub-fn 會複雜化 local state / ref / context binding
 const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
-  ({ id, label, icon: Icon, checkbox, inlineActions, inlineActionsSlot, actionsReveal = 'hover', indicator, disabled, children, className, ...props }, ref) => {
+  ({ id, label, icon: Icon, checkbox, inlineActions, inlineActionsSlot, actionsReveal = 'hover', indicator, disabled, children, className, style, onClick, ...props }, ref) => {
     const ctx = useTreeView()
     const depth = React.useContext(DepthContext)
     const {
@@ -772,9 +1140,11 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
       toggleExpand,
       select,
       setFocusedId,
+      focusTree,
       registerNode,
       unregisterNode,
       isKeyboardRef,
+      activeDescendantPrefix,
     } = ctx
 
     const hasChildren = React.Children.count(children) > 0
@@ -784,6 +1154,9 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
     const showRing = isFocused && isKeyboardRef.current
     const isDragging = draggingId === id
     const isDropTarget = dropTarget?.id === id
+    const visualCheckbox = checkbox && React.isValidElement<Record<string, unknown>>(checkbox)
+      ? React.cloneElement(checkbox, { 'aria-hidden': true, tabIndex: -1 })
+      : checkbox
 
     const iconPx = ICON_SIZE[size]
     const indentPx = depth * INDENT_STEP[size]
@@ -818,27 +1191,53 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
 
     // ── Handlers ──
     const handleRowClick = React.useCallback(
-      (e: React.MouseEvent) => {
-        if (disabled) return
+      (e: React.MouseEvent<HTMLDivElement>) => {
+        onClick?.(e)
+        if (e.defaultPrevented || disabled) return
         e.stopPropagation()
+        // Virtual-focus contract:DOM focus 必留在 tree root。先 focus 再設定 clicked id，
+        // 避免 root onFocus 的「初次進入選第一項」初始化覆寫 pointer target。
+        focusTree()
         setFocusedId(id)
         select(id)
         if (expandOnSelect && hasChildren) {
           toggleExpand(id)
         }
       },
-      [id, disabled, select, setFocusedId, expandOnSelect, hasChildren, toggleExpand]
+      [id, disabled, onClick, focusTree, select, setFocusedId, expandOnSelect, hasChildren, toggleExpand]
     )
 
     const handleChevronClick = React.useCallback(
       (e: React.MouseEvent) => {
         e.stopPropagation()
         if (disabled) return
+        focusTree()
+        setFocusedId(id)
         toggleExpand(id)
       },
-      [id, disabled, toggleExpand]
+      [id, disabled, focusTree, setFocusedId, toggleExpand]
     )
 
+    // dnd-kit PointerSensor listener 與 consumer DOM callback 必安全 compose：consumer 先收到
+    // event，可用 preventDefault 取消 drag；未取消才執行 internal listener。`...props` 會先
+    // spread，這份 composed map 隨後覆蓋同名 pointer listener，避免任一方被靜默吃掉。
+    const composedDragListeners = dragListeners
+      ? Object.fromEntries(
+          Object.entries(dragListeners).map(([eventName, internalHandler]) => [
+            eventName,
+            (event: React.SyntheticEvent<HTMLElement>) => {
+              const consumerHandler = (props as Record<string, unknown>)[eventName]
+              if (typeof consumerHandler === 'function') {
+                ;(consumerHandler as (event: React.SyntheticEvent<HTMLElement>) => void)(event)
+              }
+              if (!event.defaultPrevented) {
+                ;(internalHandler as (event: React.SyntheticEvent<HTMLElement>) => void)(event)
+              }
+            },
+          ])
+        ) as typeof dragListeners
+      : undefined
+
     // ── Chevron(永遠存在:expandable = 旋轉箭頭;leaf = placeholder 佔位) ──
     // 消費 `<ItemPrefix>` SSOT — 永遠 h-[1lh] 對齊 label 第一行中線(item-anatomy 對應)。
     // forced width 透過 style 鎖 chevron 槽寬,讓 sibling label 起點水平對齊(無 chevron leaf 佔位同寬)。
@@ -851,8 +1250,8 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
             onClick={handleChevronClick}
             className={cn(
               'flex items-center justify-center rounded-md',
-              'text-fg-muted hover:text-foreground hover:bg-neutral-hover',
-              'transition-all duration-150',
+              'text-fg-muted hover:text-fg-secondary hover:bg-neutral-hover',
+              'transition-all duration-150 motion-reduce:duration-0',
               isExpanded && 'rotate-90',
               disabled && 'text-fg-disabled pointer-events-none',
             )}
@@ -876,11 +1275,17 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
             if (typeof ref === 'function') ref(node)
             else if (ref) (ref as React.MutableRefObject<HTMLDivElement | null>).current = node
           }}
+          // DOM id 供容器 aria-activedescendant 指向(virtual focus);與 data-tree-id 並存
+          // (data-tree-id 給內部 querySelector / drag,id 給 AT)。
+          id={`${activeDescendantPrefix}treeitem-${id}`}
           role="treeitem"
           aria-expanded={hasChildren ? isExpanded : undefined}
           aria-selected={selectionMode !== 'none' ? isSelected : undefined}
           aria-level={depth + 1}
           aria-disabled={disabled || undefined}
+          // 2026-07-05 D4 修:aria-roledescription 移到 treeitem(有 role 的元素才合法)—
+          // 供 AT 提示此 node 可拖曳;值消費 dnd-kit attributes SSOT(預設 'draggable')。
+          aria-roledescription={draggable && !disabled ? dragAttrs['aria-roledescription'] : undefined}
           data-tree-id={id}
           data-tree-parent-id={parentId ?? ''}
           data-tree-has-children={hasChildren}
@@ -898,6 +1303,7 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
 
           {/* Row: draggable + droppable 都在這一行(合併 ref),確保碰撞偵測只看行高 */}
           <div
+            {...props}
             ref={(node) => {
               // 合併 drag + drop ref 到同一個 element
               if (draggable) setDragRef(node)
@@ -907,34 +1313,63 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
             className={cn(
               'group/tree-item',
               treeItemVariants({ size }),
-              // 預設文字色 neutral-8 (fg-secondary),選中後變 neutral-9 (foreground)
-              // icon 透過 currentColor 繼承,不需要另外設
-              !disabled && !isSelected && 'text-fg-secondary',
-              !disabled && isSelected && 'text-foreground',
-              // inside: 資料夾背景高亮(Figma 風格),不用 ring/border
+              // 2026-05-26 SSOT lock(user explicit「multi 已有 checkbox 強信號,text 不該再變色」):
+              // ── Single mode ──
+              //   - default text 預設 fg-secondary muted(hierarchy navigation 慣例,跟 Sidebar 一致)
+              //   - selected → text-foreground emphasis + bg-neutral-selected(無 checkbox,需 text+bg 雙信號)
+              // ── Multi mode ──
+              //   - default text 維持 fg-secondary muted(跟 single 對齊 hierarchy)
+              //   - selected → 視覺信號只在 checkbox(auto-render below),text 不變、bg 不變
+              //   - 對齊 SelectMenu multi pattern(menu-item.tsx:194-195 selected → bg only;multi → checkbox only)
+              // multi-selected 也維持 fg-secondary(上方註解「text 不變」;原 !isSelected 條件讓 multi-selected 掉到繼承色)
+              !disabled && (!isSelected || selectionMode === 'multiple') && 'text-fg-secondary',
+              !disabled && isSelected && selectionMode === 'single' && 'text-foreground',
               isDropTarget && dropTarget?.position === 'inside' && dropIndicatorInside,
               !disabled && 'hover:bg-neutral-hover hover:text-foreground',
-              !disabled && isSelected && selectionMode === 'single' && 'bg-neutral-selected',
+              // 2026-08-11 修偏移(SSOT = item-anatomy「選中 × 互動疊加」):先前 hover:bg-neutral-hover
+              //(0,2,0)蓋掉無修飾的 bg-neutral-selected(0,1,0)→ 選中列 hover 反而變淺 = bug。
+              // 釘住 hover 不變(twMerge 同組後者勝)+ 鍵盤焦點深一階 -focus。
+              !disabled && isSelected && selectionMode === 'single' && 'bg-neutral-selected hover:bg-neutral-selected focus-visible:bg-neutral-selected-focus',
               showRing && 'ring-2 ring-ring ring-inset',
               disabled && 'pointer-events-none text-fg-disabled cursor-default',
               className,
             )}
             style={{
+              ...style,
+              // Structural indent 由 TreeView SSOT 最終擁有，consumer style 不得抹掉。
               paddingLeft: indentPx > 0
                 ? `calc(var(--tree-px) + ${indentPx}px)`
                 : 'var(--tree-px)',
               paddingRight: 'var(--tree-px)',
             }}
+            // 2026-07-05 D4 修:只 spread listeners,不 spread dnd-kit attributes —
+            // useDraggable 預設 attributes 注入 role="button" + tabIndex=0 + aria-pressed +
+            // aria-describedby(鍵盤拖曳指示):role=button 污染 treeitem 語意、tabIndex=0
+            // 讓每 row 變 DOM tab stop 破壞單一 tab stop 虛擬焦點模型(DOM focus 在 row 上按
+            // Enter 會 bubble 到容器 handleKeyDown 但 handler 操作 state focusedId → 錯位);
+            // sensors 僅 PointerSensor(無 KeyboardSensor),這些 attrs 換不到鍵盤拖曳能力;
+            // 鍵盤重排(2026-07-14 v1)走容器 handleKeyDown 的 Cmd/Ctrl+Shift+Arrow 分支,非 dnd-kit sensor。
+            // aria-roledescription 保留在上方 treeitem 元素(有 role 才合法)。
+            {...(draggable ? composedDragListeners : {})}
             onClick={handleRowClick}
-            {...(draggable ? { ...dragListeners, ...dragAttrs } : {})}
-            {...props}
           >
             {chevronSlot}
 
-            {/* Checkbox 在 icon 前——消費 `<ItemPrefix>` 對齊第一行 */}
-            {checkbox && (
+            {/* Checkbox 在 icon 前——消費 `<ItemPrefix>` 對齊第一行
+              * 2026-05-26 SSOT lock(user explicit「多選的方式應該也是要跟 menu 一樣是出現 checkbox」):
+              *   - selectionMode='multiple' + 無 consumer checkbox prop → auto-render `<Checkbox>` reflect selectedIds
+              *     (對齊 SelectMenu multi pattern;consumer 不用手寫 checkbox)
+              *   - selectionMode='multiple' + consumer 傳 checkbox → 用 consumer 的(parent-child cascade 等 advanced)
+              *   - selectionMode='single' / 'none' → 不 render checkbox(text-foreground + bg 雙信號表 selected)
+              * 對齊 cite:menu-item.tsx:194-195(MenuItem selected bg)+ select-menu.tsx:352-354(SelectMenu multi=checkbox) */}
+            {(checkbox || selectionMode === 'multiple') && (
               <ItemPrefix className="pointer-events-none">
-                {checkbox}
+                {/* 2026-07-05 D4 修:auto-render Checkbox 補 tabIndex={-1} — Radix Checkbox root
+                  * 是原生 button(預設可聚焦),aria-hidden + 可聚焦 = axe aria-hidden-focus,且
+                  * 破壞 tree 單一 tab stop 虛擬焦點模型(tree-view.spec.md「Focus」段);
+                  * ItemPrefix pointer-events-none 只擋滑鼠不擋鍵盤。選取語意由 treeitem
+                  * aria-selected 承載,checkbox 純視覺反映。 */}
+                {visualCheckbox || <Checkbox checked={isSelected} disabled={disabled} aria-hidden="true" tabIndex={-1} />}
               </ItemPrefix>
             )}
 
@@ -959,7 +1394,10 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
                 actionsReveal="hover"(預設):row hover 或 keyboard focus-visible 才顯示;
                 actionsReveal=false:常駐顯示。跟 SidebarMenuButton 共用同一條規則,行為一致。
                 inlineActionsSlot escape hatch 優先(consumer 自控 JSX,reveal 一樣套外層 group)。 */}
-            {inlineActionsSlot ? (
+            {/* 2026-06-12 R2(同 sidebar.tsx 修):宿主 disabled 時 render 層擋 inline actions —
+                inline-action.spec.md「宿主 disabled | 不渲染」;row pointer-events 蓋不住
+                actionsReveal=false 常駐顯示的視覺暗示,必須 render 層 guard。 */}
+            {disabled ? null : inlineActionsSlot ? (
               <ItemSuffix hoverReveal={actionsReveal === 'hover'} hoverGroup="tree-item">
                 {inlineActionsSlot}
               </ItemSuffix>
@@ -984,7 +1422,7 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
           {hasChildren && (
             <CollapsiblePrimitive.Root open={isExpanded}>
               <CollapsiblePrimitive.Content
-                className="overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down"
+                className="overflow-hidden data-[state=closed]:animate-collapsible-up data-[state=open]:animate-collapsible-down motion-reduce:animate-none"
               >
                 <DepthContext.Provider value={depth + 1}>
                   <div role="group" className="flex flex-col w-full">
@@ -1012,16 +1450,21 @@ const ParentIdContext = React.createContext<string | null>(null)
 // Phase 2 fill needed: purpose descriptions + when rationale + world-class refs
 export const treeViewMeta = {
   component: 'TreeView',
-  family: null, // non-family composite / overlay / layout
+  family: 1, // Family 1(Menu item layout)消費者 — 對齊 tree-view.spec.md frontmatter family: 1
   variants: {
 
   },
   sizes: {
-
+    // 對齊 tree-view.spec.md frontmatter(compile-stories --check 驗 key 一致)
+    sm: { typography: 'body', indent: 24 },
+    md: { typography: 'body', indent: 24 }, // default
+    lg: { typography: 'body-lg', indent: 28 },
   },
-  states: ['default', 'hover', 'active', 'focus-visible', 'disabled'],
+  // 'selected' = single-selection 持續選中(bg-neutral-selected + aria-selected);'active' 移除 —
+  // 全檔無 Tailwind 按壓 utility,無按壓專屬視覺態(2026-07-07 詞彙統一對抗稽核補修)。
+  states: ['default', 'hover', 'selected', 'focus-visible', 'disabled'],
   tokens: {
-    bg: ['bg-neutral-hover', 'bg-primary', 'bg-primary-subtle', 'bg-surface'],
+    bg: ['bg-neutral-hover', 'bg-neutral-selected', 'bg-surface'],
     fg: ['text-fg-disabled', 'text-fg-muted', 'text-fg-secondary', 'text-foreground'],
     ring: ['ring-ring'],
   },