@qijenchen/design-system 0.1.0-beta.8 → 0.1.0-beta.80

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

@@ -0,0 +1,299 @@
+// @story-trait-rationale: hasInteractiveStates trait — TreeView interactive states(hover / focus / selected / disabled)由 TreeItem 內部處理(spec.md state machine + anatomy StateBehavior story 已 cover),showcase 層 manual Disabled/States story retired per F migration(2026-05-15)— anatomy.stories.tsx auto-compile owns StateBehavior 6-canonical。AllSizes 同理 retired(SizeMatrix anatomy auto-compile owns)。
+import * as React from 'react'
+import type { Meta, StoryObj } from '@storybook/react'
+import {
+  Folder, FileText, FileCode, Image, Settings,
+  CheckCircle2, Circle, Minus,
+  type LucideIcon,
+} from 'lucide-react'
+import { TreeView, TreeItem } from './tree-view'
+import { Checkbox } from '@/design-system/components/Checkbox/checkbox'
+
+const meta: Meta = {
+  title: 'Design System/Components/TreeView/展示',
+  parameters: { layout: 'padded' },
+}
+export default meta
+
+type Story = StoryObj
+
+// ── File Browser ────────────────────────────────────────────────────────
+
+export const FileBrowser: Story = {
+  name: '檔案瀏覽',
+  render: () => (
+    <div className="w-[300px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
+      <TreeView aria-label="檔案瀏覽" defaultExpandedIds={['src', 'components']}>
+        <TreeItem id="src" icon={Folder} label="src">
+          <TreeItem id="components" icon={Folder} label="components">
+            <TreeItem id="button" icon={FileCode} label="Button.tsx" />
+            <TreeItem id="input" icon={FileCode} label="Input.tsx" />
+            <TreeItem id="dialog" icon={FileCode} label="Dialog.tsx" />
+          </TreeItem>
+          <TreeItem id="utils" icon={Folder} label="utils">
+            <TreeItem id="cn" icon={FileCode} label="cn.ts" />
+          </TreeItem>
+          <TreeItem id="app" icon={FileCode} label="App.tsx" />
+          <TreeItem id="main" icon={FileCode} label="main.tsx" />
+        </TreeItem>
+        <TreeItem id="public" icon={Folder} label="public">
+          <TreeItem id="favicon" icon={Image} label="favicon.svg" />
+        </TreeItem>
+        <TreeItem id="pkg" icon={FileText} label="package.json" />
+        <TreeItem id="readme" icon={FileText} label="README.md" />
+      </TreeView>
+    </div>
+  ),
+}
+
+// ── Stepper ─────────────────────────────────────────────────────────────
+
+const StepDone = () => <CheckCircle2 size={16} className="text-success" />
+const StepActive = () => <Circle size={16} className="text-primary" />
+const StepPending = () => <Minus size={16} className="text-fg-muted" />
+
+export const Stepper: Story = {
+  name: '步驟引導',
+  render: () => (
+    <div className="w-[300px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
+      <TreeView
+        aria-label="申請流程"
+        expandOnSelect
+        defaultExpandedIds={['step1', 'step2']}
+        defaultSelectedIds={['step2-card']}
+      >
+        <TreeItem id="step1" indicator={<StepDone />} label="1. 個人資料">
+          <TreeItem id="step1-name" indicator={<StepDone />} label="姓名" />
+          <TreeItem id="step1-addr" indicator={<StepDone />} label="地址" />
+          <TreeItem id="step1-contact" indicator={<StepDone />} label="聯絡方式" />
+        </TreeItem>
+        <TreeItem id="step2" indicator={<StepActive />} label="2. 付款方式">
+          <TreeItem id="step2-card" indicator={<StepActive />} label="信用卡號碼" />
+          <TreeItem id="step2-billing" indicator={<StepPending />} label="帳單地址" />
+        </TreeItem>
+        <TreeItem id="step3" indicator={<StepPending />} label="3. 確認送出" />
+      </TreeView>
+    </div>
+  ),
+}
+
+// ── Multi-select with Checkbox ───────────────────────────────────────────
+
+const CheckboxTree = () => {
+  const [checked, setChecked] = React.useState<Record<string, boolean>>({
+    'read': true, 'read-docs': true, 'read-media': true,
+    'write': false, 'write-docs': true, 'write-media': false,
+  })
+
+  const toggle = (id: string) => {
+    setChecked((prev) => ({ ...prev, [id]: !prev[id] }))
+  }
+
+  // parent 的 indeterminate 邏輯
+  const readAll = checked['read-docs'] && checked['read-media']
+  const readNone = !checked['read-docs'] && !checked['read-media']
+  const writeAll = checked['write-docs'] && checked['write-media']
+  const writeNone = !checked['write-docs'] && !checked['write-media']
+
+  return (
+    <div className="w-[300px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
+      <TreeView selectionMode="multiple" aria-label="權限選擇" defaultExpandedIds={['read', 'write']}>
+        <TreeItem
+          id="read"
+          icon={Folder}
+          label="讀取權限"
+          checkbox={<Checkbox size="md" checked={readAll ? true : readNone ? false : 'indeterminate'} />}
+          onClick={() => { const next = !readAll; setChecked((p) => ({ ...p, read: next, 'read-docs': next, 'read-media': next })) }}
+        >
+          <TreeItem id="read-docs" icon={FileText} label="文件" checkbox={<Checkbox size="md" checked={checked['read-docs']} />} onClick={() => toggle('read-docs')} />
+          <TreeItem id="read-media" icon={Image} label="媒體檔案" checkbox={<Checkbox size="md" checked={checked['read-media']} />} onClick={() => toggle('read-media')} />
+        </TreeItem>
+        <TreeItem
+          id="write"
+          icon={Folder}
+          label="寫入權限"
+          checkbox={<Checkbox size="md" checked={writeAll ? true : writeNone ? false : 'indeterminate'} />}
+          onClick={() => { const next = !writeAll; setChecked((p) => ({ ...p, write: next, 'write-docs': next, 'write-media': next })) }}
+        >
+          <TreeItem id="write-docs" icon={FileText} label="文件" checkbox={<Checkbox size="md" checked={checked['write-docs']} />} onClick={() => toggle('write-docs')} />
+          <TreeItem id="write-media" icon={Image} label="媒體檔案" checkbox={<Checkbox size="md" checked={checked['write-media']} />} onClick={() => toggle('write-media')} />
+        </TreeItem>
+      </TreeView>
+    </div>
+  )
+}
+
+export const WithCheckbox: Story = {
+  name: '多選',
+  render: () => <CheckboxTree />,
+}
+
+// ── Long label (wrap test) ──────────────────────────────────────────────
+
+export const LongLabel: Story = {
+  name: '長標籤',
+  render: () => (
+    <div className="flex gap-8 items-start">
+      <div className="flex flex-col gap-2">
+        <span className="text-caption font-medium text-fg-muted">預設 truncate</span>
+        <div className="w-[220px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
+          <TreeView aria-label="truncate test" defaultExpandedIds={['proj']}>
+            <TreeItem id="proj" icon={Folder} label="這是一個很長的專案名稱會被截斷">
+              <TreeItem id="f1" icon={FileText} label="這是一個很長的檔案名稱也會被截斷.tsx" />
+              <TreeItem id="f2" icon={FileText} label="短檔名.ts" />
+            </TreeItem>
+          </TreeView>
+        </div>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-caption font-medium text-fg-muted">label 換行（移除 truncate）</span>
+        <div className="w-[220px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
+          <TreeView aria-label="wrap test" defaultExpandedIds={['proj2']}>
+            <TreeItem id="proj2" icon={Folder} label={<span className="break-words whitespace-normal">這是一個很長的專案名稱會自然換行到下一行</span>}>
+              <TreeItem id="f3" icon={FileText} label={<span className="break-words whitespace-normal">這是一個很長的檔案名稱也會自然換行到下一行顯示完整內容.tsx</span>} />
+              <TreeItem id="f4" icon={FileText} label="短檔名.ts" />
+            </TreeItem>
+          </TreeView>
+        </div>
+      </div>
+    </div>
+  ),
+}
+
+// ── Drag and Drop (functional — items actually move) ────────────────────
+
+interface DemoNode { id: string; label: string; icon: LucideIcon; children?: DemoNode[] }
+
+function removeNode(nodes: DemoNode[], id: string): [DemoNode[], DemoNode | null] {
+  let removed: DemoNode | null = null
+  const result = nodes.filter(n => {
+    if (n.id === id) { removed = n; return false }
+    return true
+  }).map(n => {
+    if (!n.children) return n
+    const [newChildren, found] = removeNode(n.children, id)
+    if (found) removed = found
+    return { ...n, children: newChildren }
+  })
+  return [result, removed]
+}
+
+function insertNode(nodes: DemoNode[], targetId: string, node: DemoNode, position: 'before' | 'after' | 'inside'): DemoNode[] {
+  if (position === 'inside') {
+    return nodes.map(n => {
+      if (n.id === targetId) return { ...n, children: [...(n.children ?? []), node] }
+      if (!n.children) return n
+      return { ...n, children: insertNode(n.children, targetId, node, position) }
+    })
+  }
+  const result: DemoNode[] = []
+  for (const n of nodes) {
+    if (n.id === targetId && position === 'before') result.push(node)
+    result.push(n.children ? { ...n, children: insertNode(n.children, targetId, node, position) } : n)
+    if (n.id === targetId && position === 'after') result.push(node)
+  }
+  return result
+}
+
+function renderNodes(nodes: DemoNode[]) {
+  return nodes.map(n => (
+    <TreeItem key={n.id} id={n.id} icon={n.icon} label={n.label}>
+      {n.children && n.children.length > 0 && renderNodes(n.children)}
+    </TreeItem>
+  ))
+}
+
+const INITIAL_TREE: DemoNode[] = [
+  { id: 'pages', label: 'Pages', icon: Folder, children: [
+    { id: 'home', label: 'Home', icon: FileText },
+    { id: 'about', label: 'About', icon: FileText },
+    { id: 'contact', label: 'Contact', icon: FileText },
+  ]},
+  { id: 'docs', label: 'Docs', icon: Folder, children: [
+    { id: 'intro', label: 'Introduction', icon: FileCode },
+    { id: 'guide', label: 'Getting Started', icon: FileCode },
+  ]},
+  { id: 'settings', label: 'Settings', icon: Settings },
+]
+
+export const DragAndDrop: Story = {
+  name: '拖曳重排',
+  render: () => {
+    const [tree, setTree] = React.useState(INITIAL_TREE)
+    const [log, setLog] = React.useState<string[]>([])
+
+    return (
+      <div className="flex gap-6 items-start">
+        <div className="flex flex-col gap-2">
+          <p className="text-caption text-fg-muted max-w-xs">
+            Figma 風格:整列拖曳,items 真的會移動。拖到其他 node 上方(before) / 下方(after) / 中間(inside 成為子項)。
+          </p>
+          <div className="w-[280px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
+            <TreeView
+              aria-label="拖曳排序"
+              draggable
+              defaultExpandedIds={['pages', 'docs']}
+              onDragEnd={(e) => {
+                setTree(prev => {
+                  const [without, node] = removeNode(prev, e.sourceId)
+                  if (!node) return prev
+                  return insertNode(without, e.targetId, node, e.position)
+                })
+                setLog(prev => [`${e.sourceId} → ${e.targetId} (${e.position})`, ...prev].slice(0, 10))
+              }}
+            >
+              {renderNodes(tree)}
+            </TreeView>
+          </div>
+          <button type="button" onClick={() => setTree(INITIAL_TREE)} className="text-caption text-primary hover:text-primary-hover cursor-pointer self-start">
+            重設
+          </button>
+        </div>
+        <div className="w-[240px]">
+          <p className="text-caption font-medium text-fg-muted mb-2">移動紀錄</p>
+          <div className="flex flex-col gap-1 text-[11px] font-mono text-fg-secondary">
+            {log.length === 0 && <span className="text-fg-muted">拖曳 node 後這裡會顯示</span>}
+            {log.map((l, i) => <span key={i}>{l}</span>)}
+          </div>
+        </div>
+      </div>
+    )
+  },
+}
+
+// @story-trait-rationale: AllSizes retired per F migration(2026-05-15)— anatomy.stories.tsx SizeMatrix auto-compile owns size showcase。
+// ── Indent 結構對齊驗證 ─────────────────────────────────────────────────
+
+export const IndentAlignment: Story = {
+  name: '縮排結構對齊驗證',
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <div className="flex flex-col gap-1">
+        <h3 className="text-h6 font-semibold">indentStep = chevronSize + gap-2</h3>
+        <p className="text-caption text-fg-muted max-w-xl">
+          子 chevron 應對齊父 icon 的起始位置,子 icon 應對齊父 label 的起始位置。
+          這裡混合有 / 無 children 的 node 驗證 chevron placeholder 佔位(leaf 無條件留等寬空白);
+          icon 無自動佔位——無 icon 的 node(README.md / public)label 起點前移,屬「Icon 使用策略」
+          的混用反例,此處僅作 indent 結構驗證。
+        </p>
+      </div>
+      <div className="w-[300px] border border-divider rounded-lg bg-surface overflow-hidden py-2">
+        <TreeView aria-label="專案檔案樹" defaultExpandedIds={['src', 'components', 'public']}>
+          <TreeItem id="src" icon={Folder} label="src">
+            <TreeItem id="app" icon={FileCode} label="App.tsx" />
+            <TreeItem id="readme" label="README.md" />
+          </TreeItem>
+          <TreeItem id="public" label="public">
+            <TreeItem id="favicon" icon={Image} label="favicon.ico" />
+          </TreeItem>
+          <TreeItem id="components" icon={Folder} label="components">
+            <TreeItem id="button" icon={Folder} label="Button">
+              <TreeItem id="button-tsx" icon={FileCode} label="Button.tsx" />
+              <TreeItem id="button-test" label="Button.test.tsx" />
+            </TreeItem>
+          </TreeItem>
+        </TreeView>
+      </div>
+    </div>
+  ),
+}

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,7 @@ export interface TreeDragEndEvent {
   /** 目標 node id */
   targetId: string
   /** 放置位置:before(同層上方)/ after(同層下方)/ inside(成為子 node) */
-  position: DropPosition
+  position: TreeDropPosition
 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -89,10 +90,11 @@ 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`(L808 inline calc 需 number)+ drop-indicator
+// pointer 數學(L352,需 number 做 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 }
 
 // ═══════════════════════════════════════════════════════════════════════════
@@ -106,13 +108,19 @@ 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
@@ -173,7 +181,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,7 +203,7 @@ 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。
    */
@@ -273,13 +281,19 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
     // ── Focus state ──
     const [focusedId, setFocusedId] = React.useState<string | null>(null)
 
+    // ── 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()
+
     // ── Keyboard vs mouse detection ──
     // focus ring 只在鍵盤操作時顯示,滑鼠點擊用 bg-neutral-selected 表達選中,不顯示 ring
     const isKeyboardRef = React.useRef(false)
 
     // ── 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) }, [])
@@ -339,7 +353,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) {
@@ -456,6 +470,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         expandOnSelect,
         draggable,
         isKeyboardRef,
+        activeDescendantPrefix,
         draggingId,
         dropTarget,
         expandedIds,
@@ -475,6 +490,7 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         expandOnSelect,
         draggable,
         isKeyboardRef,
+        activeDescendantPrefix,
         draggingId,
         dropTarget,
         expandedIds,
@@ -590,6 +606,9 @@ const TreeView = React.forwardRef<HTMLDivElement, TreeViewProps>(
         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}
         className={cn(
           // TreeView root 不加任何 py——呼吸空間由外層容器負責:
           //   - 在 SidebarGroup 內: SidebarGroup py-2 提供
@@ -696,14 +715,14 @@ export interface TreeItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
    */
   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 +751,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 +763,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
   /** 是否停用 */
@@ -775,6 +794,7 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
       registerNode,
       unregisterNode,
       isKeyboardRef,
+      activeDescendantPrefix,
     } = ctx
 
     const hasChildren = React.Children.count(children) > 0
@@ -876,6 +896,9 @@ 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}
@@ -907,11 +930,16 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
             className={cn(
               'group/tree-item',
               treeItemVariants({ size }),
-              // 預設文字色 neutral-8 (fg-secondary),選中後變 neutral-9 (foreground)
-              // icon 透過 currentColor 繼承,不需要另外設
+              // 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)
               !disabled && !isSelected && 'text-fg-secondary',
-              !disabled && isSelected && 'text-foreground',
-              // inside: 資料夾背景高亮(Figma 風格),不用 ring/border
+              !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',
@@ -931,10 +959,16 @@ const TreeItem = React.forwardRef<HTMLDivElement, TreeItemProps>(
           >
             {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}
+                {checkbox || <Checkbox checked={isSelected} disabled={disabled} aria-hidden="true" />}
               </ItemPrefix>
             )}
 
@@ -959,7 +993,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>
@@ -1012,7 +1049,7 @@ 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: {
 
   },
@@ -1021,7 +1058,7 @@ export const treeViewMeta = {
   },
   states: ['default', 'hover', 'active', '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'],
   },

package/src/hooks/use-overflow-items.ts

@@ -11,12 +11,16 @@ import * as React from 'react'
  *      使用 `useScrollEdges()`：回傳 atStart / atEnd / canScroll，讓消費端
  *      決定 mask-image / scroll arrow 的顯示。
  *
- *   2. **Menu 模式**（Ant Design / Atlassian 作法）
- *      塞不下的 items 收進 DropdownMenu。**所有 items 都渲染在 DOM 中**
- *      （只視覺隱藏溢出的）以保留 Radix 的 roving tabindex / roving focus 等
- *      a11y 語意。使用 `useOverflowIndices()`：回傳 overflowIndices
- *      供消費端渲染對應的 menu items（通常是 click proxy，觸發同一個
- *      onValueChange）。
+ *   2. **Menu 模式**（Ant Design / Atlassian「動態 collapse-overflow」作法）
+ *      塞不下的 items 收進 DropdownMenu。`useOverflowIndices()` 回傳 overflowIndices
+ *      供消費端動態計算哪些 items 塞不下、渲染對應的 menu items。
+ *
+ *      ⚠️ **目前 0 consumer（reserved primitive）**：DS 內現有 menu 模式實作（Tabs / Chip）走的是
+ *      「**show-all navigator**」派 — dropdown 永遠列**全部** items（不需動態 overflow 計算），各自用
+ *      local registerItem，**刻意不用** `useOverflowIndices`（見 tabs.tsx:256 / chip.tsx:219 註解）。
+ *      本 hook 保留給未來真正需要「collapse-overflow：只把塞不下的收進選單」的 consumer。
+ *      **roving tabindex / a11y 語意由 consumer 的渲染方式決定**（hook 只回傳 indices，不操作
+ *      DOM / tabindex），非 hook 本身保證。
  *
  * ── 為什麼分兩個 hook，不合一 ──
  *   Scroll 的計算依據是 scroll 事件與 client/scroll width；Menu 的計算依據是