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

package/dist/components/TreeView/tree-view.js

@@ -1,4 +1,4 @@
-import { jsx, jsxs } from "react/jsx-runtime";
+import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import * as React from "react";
 import * as CollapsiblePrimitive from "@radix-ui/react-collapsible";
 import { useDraggable, useDroppable, useSensors, useSensor, PointerSensor, DndContext, DragOverlay } from "@dnd-kit/core";
@@ -6,7 +6,8 @@ import { ChevronRight } from "lucide-react";
 import { cva } from "class-variance-authority";
 import { dropIndicatorRow, dropIndicatorInside, dragSourceClass } from "../../lib/drag-visual.js";
 import { cn } from "../../lib/utils.js";
-import { ItemPrefix, ICON_SIZE, ItemIcon, ItemSuffix, ItemInlineAction, RowSizeProvider, ROW_PADDING_BY_SIZE } from "../../patterns/element-anatomy/item-anatomy.js";
+import { Checkbox } from "../Checkbox/checkbox.js";
+import { ICON_SIZE, ItemPrefix, ItemIcon, ItemSuffix, ItemInlineAction, RowSizeProvider, ROW_PADDING_BY_SIZE } from "../../patterns/element-anatomy/item-anatomy.js";
 const CONTEXT_PX_VAR = {
   sidebar: "var(--layout-space-loose)",
   // md=16px, lg=24px(density 連動)
@@ -14,6 +15,25 @@ const CONTEXT_PX_VAR = {
   // px-3,對齊 MenuItem / DropdownMenu
 };
 const INDENT_STEP = { sm: 24, md: 24, lg: 28 };
+const REORDER_ARROW_KEYS = ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"];
+const DEFAULT_REORDER_ANNOUNCEMENTS = {
+  moved: ({ label, targetLabel, position, index, count }) => `已將『${label}』移到『${targetLabel}』${position === "before" ? "之前" : "之後"},第 ${index} 項,共 ${count} 項`,
+  movedInside: ({ label, folderLabel, index, count }) => index !== void 0 && count !== void 0 ? `已將『${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+方向鍵可重新排列項目"
+};
 const TreeViewContext = React.createContext(null);
 function useTreeView() {
   const ctx = React.useContext(TreeViewContext);
@@ -43,6 +63,7 @@ const TreeView = React.forwardRef(
     expandOnSelect = false,
     draggable = false,
     onDragEnd: onDragEndProp,
+    reorderAnnouncements: reorderAnnouncementsProp,
     expandedIds: controlledExpanded,
     onExpandedChange,
     selectedIds: controlledSelected,
@@ -53,6 +74,15 @@ const TreeView = React.forwardRef(
     children,
     ...props
   }, ref) => {
+    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]);
     const [internalExpanded, setInternalExpanded] = React.useState(
       () => new Set(defaultExpandedIds)
     );
@@ -92,6 +122,19 @@ const TreeView = React.forwardRef(
       [controlledSelected, onSelectedChange]
     );
     const [focusedId, setFocusedId] = React.useState(null);
+    const treeRef = React.useRef(null);
+    React.useImperativeHandle(ref, () => treeRef.current);
+    const focusTree = React.useCallback(() => {
+      var _a;
+      (_a = treeRef.current) == null ? void 0 : _a.focus({ preventScroll: true });
+    }, []);
+    const activeDescendantPrefix = React.useId();
+    const [reorderAnnouncement, setReorderAnnouncement] = React.useState("");
+    const announcements = React.useMemo(
+      () => ({ ...DEFAULT_REORDER_ANNOUNCEMENTS, ...reorderAnnouncementsProp }),
+      [reorderAnnouncementsProp]
+    );
+    const reorderInstructionsId = `${activeDescendantPrefix}tree-reorder-instructions`;
     const isKeyboardRef = React.useRef(false);
     const [draggingId, setDraggingId] = React.useState(null);
     const [dropTarget, setDropTarget] = React.useState(null);
@@ -101,6 +144,19 @@ const TreeView = React.forwardRef(
     }, []);
     const toggleExpandRef = React.useRef(() => {
     });
+    const { registerNode, unregisterNode, getNodeInfo } = useNodeRegistry();
+    const isInSubtree = React.useCallback(
+      (candidateId, rootId) => {
+        var _a;
+        let cur = candidateId;
+        while (cur != null) {
+          if (cur === rootId) return true;
+          cur = ((_a = getNodeInfo(cur)) == null ? void 0 : _a.parentId) ?? null;
+        }
+        return false;
+      },
+      [getNodeInfo]
+    );
     const sensors = useSensors(
       useSensor(PointerSensor, { activationConstraint: { distance: 5 } })
     );
@@ -110,7 +166,7 @@ const TreeView = React.forwardRef(
     const handleDragOver = React.useCallback((event) => {
       var _a, _b, _c, _d, _e;
       const { over, active } = event;
-      if (!over || over.id === active.id) {
+      if (!over || isInSubtree(String(over.id), String(active.id))) {
         if (autoExpandTimerRef.current) {
           clearTimeout(autoExpandTimerRef.current);
           autoExpandTimerRef.current = null;
@@ -160,13 +216,16 @@ const TreeView = React.forwardRef(
             if (parentId && parentId !== String(active.id)) {
               const parentDepth = Number((parentTreeItem == null ? void 0 : 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 });
+      setDropTarget((prev) => {
+        const id = String(over.id);
+        return prev && prev.id === id && prev.position === position && prev.depth === finalDepth ? prev : { id, position, depth: finalDepth };
+      });
       if (position === "inside" && hasChildren && !expandedIds.has(String(over.id))) {
         if (autoExpandTimerRef.current) clearTimeout(autoExpandTimerRef.current);
         autoExpandTimerRef.current = setTimeout(() => {
@@ -178,7 +237,7 @@ const TreeView = React.forwardRef(
           autoExpandTimerRef.current = null;
         }
       }
-    }, [expandedIds]);
+    }, [expandedIds, isInSubtree]);
     const dropTargetRef = React.useRef(dropTarget);
     dropTargetRef.current = dropTarget;
     const handleDragEnd = React.useCallback((event) => {
@@ -188,7 +247,7 @@ const TreeView = React.forwardRef(
       }
       const { active, over } = event;
       const dt = dropTargetRef.current;
-      if (over && active.id !== over.id && dt) {
+      if (over && !isInSubtree(String(over.id), String(active.id)) && dt) {
         onDragEndProp == null ? void 0 : onDragEndProp({
           sourceId: String(active.id),
           targetId: String(over.id),
@@ -197,7 +256,7 @@ const TreeView = React.forwardRef(
       }
       setDraggingId(null);
       setDropTarget(null);
-    }, [onDragEndProp]);
+    }, [onDragEndProp, isInSubtree]);
     const handleDragCancel = React.useCallback(() => {
       if (autoExpandTimerRef.current) {
         clearTimeout(autoExpandTimerRef.current);
@@ -206,7 +265,6 @@ const TreeView = React.forwardRef(
       setDraggingId(null);
       setDropTarget(null);
     }, []);
-    const { registerNode, unregisterNode, getNodeInfo } = useNodeRegistry();
     const toggleExpand = React.useCallback(
       (id) => {
         setExpandedIds((prev) => {
@@ -234,6 +292,139 @@ const TreeView = React.forwardRef(
       },
       [selectionMode, setSelectedIds]
     );
+    const getNodeLabelText = React.useCallback(
+      (id) => {
+        var _a, _b;
+        const info = getNodeInfo(id);
+        if (typeof (info == null ? void 0 : info.label) === "string") return info.label;
+        const rowEl = (_a = treeRef.current) == null ? void 0 : _a.querySelector(`[data-tree-row="${id}"]`);
+        return ((_b = rowEl == null ? void 0 : rowEl.textContent) == null ? void 0 : _b.trim()) || id;
+      },
+      [getNodeInfo]
+    );
+    const handleKeyboardReorder = React.useCallback(
+      (key) => {
+        const tree = treeRef.current;
+        if (!tree || !focusedId) return;
+        const sourceId = focusedId;
+        const sourceEl = tree.querySelector(`[data-tree-id="${sourceId}"]`);
+        if (!sourceEl || sourceEl.getAttribute("aria-disabled") === "true") return;
+        const label = getNodeLabelText(sourceId);
+        const parentId = sourceEl.dataset.treeParentId || null;
+        const visibleItems = Array.from(
+          tree.querySelectorAll('[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) => el.getAttribute("aria-disabled") !== "true";
+        const commit = (targetId, position) => {
+          if (targetId === sourceId || isInSubtree(targetId, sourceId)) return false;
+          onDragEndProp == null ? void 0 : onDragEndProp({ sourceId, targetId, position });
+          requestAnimationFrame(() => {
+            var _a, _b;
+            (_b = (_a = treeRef.current) == null ? void 0 : _a.querySelector(`[data-tree-id="${sourceId}"]`)) == null ? void 0 : _b.scrollIntoView({ block: "nearest" });
+          });
+          return true;
+        };
+        const movedIndex = (targetId, position) => {
+          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": {
+            const dir = key === "ArrowUp" ? -1 : 1;
+            const boundary = dir < 0 ? "top" : "bottom";
+            const adjacent = siblings[sourceIndex + dir];
+            if (!adjacent) {
+              setReorderAnnouncement(announcements.blocked({ reason: boundary, label }));
+              return;
+            }
+            let target;
+            let position = 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";
+            }
+            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": {
+            let target;
+            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")) {
+              if (!wasExpanded) toggleExpand(targetId);
+              const childCount = wasExpanded ? visibleItems.filter((el) => el.dataset.treeParentId === targetId).length : void 0;
+              setReorderAnnouncement(
+                announcements.movedInside({
+                  label,
+                  folderLabel: getNodeLabelText(targetId),
+                  index: childCount !== void 0 ? childCount + 1 : void 0,
+                  count: childCount !== void 0 ? childCount + 1 : void 0
+                })
+              );
+            }
+            return;
+          }
+          case "ArrowLeft": {
+            if (!parentId) {
+              setReorderAnnouncement(announcements.blocked({ reason: "root", label }));
+              return;
+            }
+            const parentEl = tree.querySelector(`[data-tree-id="${parentId}"]`);
+            const level = Number((parentEl == null ? void 0 : 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]
+    );
     const contextValue = React.useMemo(
       () => ({
         size,
@@ -242,6 +433,7 @@ const TreeView = React.forwardRef(
         expandOnSelect,
         draggable,
         isKeyboardRef,
+        activeDescendantPrefix,
         draggingId,
         dropTarget,
         expandedIds,
@@ -250,6 +442,7 @@ const TreeView = React.forwardRef(
         toggleExpand,
         select,
         setFocusedId,
+        focusTree,
         registerNode,
         unregisterNode,
         getNodeInfo
@@ -261,6 +454,7 @@ const TreeView = React.forwardRef(
         expandOnSelect,
         draggable,
         isKeyboardRef,
+        activeDescendantPrefix,
         draggingId,
         dropTarget,
         expandedIds,
@@ -269,13 +463,12 @@ const TreeView = React.forwardRef(
         toggleExpand,
         select,
         setFocusedId,
+        focusTree,
         registerNode,
         unregisterNode,
         getNodeInfo
       ]
     );
-    const treeRef = React.useRef(null);
-    React.useImperativeHandle(ref, () => treeRef.current);
     const handleMouseDown = React.useCallback(() => {
       isKeyboardRef.current = false;
     }, []);
@@ -283,13 +476,28 @@ const TreeView = React.forwardRef(
       (e) => {
         isKeyboardRef.current = true;
         if (!treeRef.current) return;
+        const keyTarget = e.target;
+        if (keyTarget && keyTarget !== e.currentTarget) {
+          const interactive = keyTarget.closest(
+            'a[href], button, input, select, textarea, [contenteditable="true"], [tabindex]:not([tabindex="-1"])'
+          );
+          if (interactive && interactive !== e.currentTarget) return;
+        }
+        if ((e.metaKey || e.ctrlKey) && e.shiftKey && REORDER_ARROW_KEYS.includes(e.key)) {
+          if (!draggable) return;
+          e.preventDefault();
+          if (draggingId !== null) return;
+          handleKeyboardReorder(e.key);
+          return;
+        }
         const items = Array.from(
-          treeRef.current.querySelectorAll('[role="treeitem"]:not([hidden])')
+          // a11y:排除 disabled 節點 → 鍵盤導覽/選取/展開全跳過(APG:disabled 不可鍵盤操作)
+          treeRef.current.querySelectorAll('[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)) {
+        if (currentIndex < 0 && items.length > 0 && ["ArrowDown", "ArrowUp", "ArrowLeft", "ArrowRight", "Home", "End"].includes(e.key)) {
           setFocusedId(items[0].dataset.treeId ?? null);
           e.preventDefault();
           return;
@@ -356,14 +564,17 @@ const TreeView = React.forwardRef(
           }
         }
       },
-      [focusedId, expandedIds, toggleExpand, select, setFocusedId]
+      [focusedId, expandedIds, toggleExpand, select, setFocusedId, draggable, draggingId, handleKeyboardReorder]
     );
     const treeEl = /* @__PURE__ */ jsx(
       "div",
       {
+        ...props,
         ref: treeRef,
         role: "tree",
         "aria-multiselectable": selectionMode === "multiple" || void 0,
+        "aria-activedescendant": focusedId ? `${activeDescendantPrefix}treeitem-${focusedId}` : void 0,
+        "aria-describedby": [props["aria-describedby"], draggable ? reorderInstructionsId : void 0].filter(Boolean).join(" ") || void 0,
         className: cn(
           // TreeView root 不加任何 py——呼吸空間由外層容器負責:
           //   - 在 SidebarGroup 內: SidebarGroup py-2 提供
@@ -379,8 +590,15 @@ const TreeView = React.forwardRef(
         },
         onKeyDown: handleKeyDown,
         onMouseDown: handleMouseDown,
+        onFocus: (e) => {
+          var _a;
+          (_a = props.onFocus) == null ? void 0 : _a.call(props, e);
+          if (e.target === e.currentTarget && !focusedId && treeRef.current) {
+            const first = treeRef.current.querySelector('[role="treeitem"][aria-selected="true"]:not([hidden]):not([aria-disabled="true"])') ?? treeRef.current.querySelector('[role="treeitem"]:not([hidden]):not([aria-disabled="true"])');
+            if (first) setFocusedId(first.dataset.treeId ?? null);
+          }
+        },
         tabIndex: 0,
-        ...props,
         children
       }
     );
@@ -394,6 +612,10 @@ const TreeView = React.forwardRef(
         onDragCancel: handleDragCancel,
         children: [
           treeEl,
+          draggable && /* @__PURE__ */ jsxs(Fragment, { children: [
+            /* @__PURE__ */ jsx("div", { role: "status", "aria-live": "polite", className: "sr-only", children: reorderAnnouncement }),
+            /* @__PURE__ */ jsx("div", { id: reorderInstructionsId, className: "sr-only", children: announcements.instructions })
+          ] }),
           draggable && /* @__PURE__ */ jsx(DragOverlay, { dropAnimation: null, children: draggingId ? (() => {
             const info = getNodeInfo(draggingId);
             const IconComp = info == null ? void 0 : info.icon;
@@ -433,7 +655,7 @@ const treeItemVariants = cva(
   }
 );
 const TreeItem = React.forwardRef(
-  ({ 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 {
@@ -449,9 +671,11 @@ const TreeItem = React.forwardRef(
       toggleExpand,
       select,
       setFocusedId,
+      focusTree,
       registerNode,
       unregisterNode,
-      isKeyboardRef
+      isKeyboardRef,
+      activeDescendantPrefix
     } = ctx;
     const hasChildren = React.Children.count(children) > 0;
     const isExpanded = expandedIds.has(id);
@@ -460,6 +684,7 @@ const TreeItem = React.forwardRef(
     const showRing = isFocused && isKeyboardRef.current;
     const isDragging = draggingId === id;
     const isDropTarget = (dropTarget == null ? void 0 : dropTarget.id) === id;
+    const visualCheckbox = checkbox && React.isValidElement(checkbox) ? React.cloneElement(checkbox, { "aria-hidden": true, tabIndex: -1 }) : checkbox;
     const iconPx = ICON_SIZE[size];
     const indentPx = depth * INDENT_STEP[size];
     const { attributes: dragAttrs, listeners: dragListeners, setNodeRef: setDragRef } = useDraggable({
@@ -484,24 +709,42 @@ const TreeItem = React.forwardRef(
     }, [isFocused]);
     const handleRowClick = React.useCallback(
       (e) => {
-        if (disabled) return;
+        onClick == null ? void 0 : onClick(e);
+        if (e.defaultPrevented || disabled) return;
         e.stopPropagation();
+        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) => {
         e.stopPropagation();
         if (disabled) return;
+        focusTree();
+        setFocusedId(id);
         toggleExpand(id);
       },
-      [id, disabled, toggleExpand]
+      [id, disabled, focusTree, setFocusedId, toggleExpand]
     );
+    const composedDragListeners = dragListeners ? Object.fromEntries(
+      Object.entries(dragListeners).map(([eventName, internalHandler]) => [
+        eventName,
+        (event) => {
+          const consumerHandler = props[eventName];
+          if (typeof consumerHandler === "function") {
+            consumerHandler(event);
+          }
+          if (!event.defaultPrevented) {
+            internalHandler(event);
+          }
+        }
+      ])
+    ) : void 0;
     const chevronSlot = /* @__PURE__ */ jsx(ItemPrefix, { style: { width: iconPx }, children: hasChildren ? /* @__PURE__ */ jsx(
       "button",
       {
@@ -510,8 +753,8 @@ const TreeItem = React.forwardRef(
         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"
         ),
@@ -531,11 +774,13 @@ const TreeItem = React.forwardRef(
           if (typeof ref === "function") ref(node);
           else if (ref) ref.current = node;
         },
+        id: `${activeDescendantPrefix}treeitem-${id}`,
         role: "treeitem",
         "aria-expanded": hasChildren ? isExpanded : void 0,
         "aria-selected": selectionMode !== "none" ? isSelected : void 0,
         "aria-level": depth + 1,
         "aria-disabled": disabled || void 0,
+        "aria-roledescription": draggable && !disabled ? dragAttrs["aria-roledescription"] : void 0,
         "data-tree-id": id,
         "data-tree-parent-id": parentId ?? "",
         "data-tree-has-children": hasChildren,
@@ -552,6 +797,7 @@ const TreeItem = React.forwardRef(
           /* @__PURE__ */ jsxs(
             "div",
             {
+              ...props,
               ref: (node) => {
                 if (draggable) setDragRef(node);
                 setDropRef(node);
@@ -560,31 +806,41 @@ const TreeItem = React.forwardRef(
               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 == null ? void 0 : 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)"
               },
+              ...draggable ? composedDragListeners : {},
               onClick: handleRowClick,
-              ...draggable ? { ...dragListeners, ...dragAttrs } : {},
-              ...props,
               children: [
                 chevronSlot,
-                checkbox && /* @__PURE__ */ jsx(ItemPrefix, { className: "pointer-events-none", children: checkbox }),
+                (checkbox || selectionMode === "multiple") && /* @__PURE__ */ jsx(ItemPrefix, { className: "pointer-events-none", children: visualCheckbox || /* @__PURE__ */ jsx(Checkbox, { checked: isSelected, disabled, "aria-hidden": "true", tabIndex: -1 }) }),
                 indicator ? /* @__PURE__ */ jsx(ItemPrefix, { style: { width: iconPx }, children: indicator }) : Icon ? /* @__PURE__ */ jsx(ItemIcon, { icon: Icon, className: disabled ? "text-fg-disabled" : void 0 }) : null,
                 /* @__PURE__ */ jsx("span", { className: cn("flex-1 min-w-0 truncate", disabled && "text-fg-disabled"), children: label }),
-                inlineActionsSlot ? /* @__PURE__ */ jsx(ItemSuffix, { hoverReveal: actionsReveal === "hover", hoverGroup: "tree-item", children: inlineActionsSlot }) : inlineActions && inlineActions.length > 0 ? /* @__PURE__ */ jsx(ItemSuffix, { hoverReveal: actionsReveal === "hover", hoverGroup: "tree-item", children: inlineActions.map((action, i) => /* @__PURE__ */ jsx(ItemInlineAction, { action }, action.label + i)) }) : null
+                disabled ? null : inlineActionsSlot ? /* @__PURE__ */ jsx(ItemSuffix, { hoverReveal: actionsReveal === "hover", hoverGroup: "tree-item", children: inlineActionsSlot }) : inlineActions && inlineActions.length > 0 ? /* @__PURE__ */ jsx(ItemSuffix, { hoverReveal: actionsReveal === "hover", hoverGroup: "tree-item", children: inlineActions.map((action, i) => /* @__PURE__ */ jsx(ItemInlineAction, { action }, action.label + i)) }) : null
               ]
             }
           ),
@@ -598,7 +854,7 @@ const TreeItem = React.forwardRef(
           hasChildren && /* @__PURE__ */ jsx(CollapsiblePrimitive.Root, { open: isExpanded, children: /* @__PURE__ */ jsx(
             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",
               children: /* @__PURE__ */ jsx(DepthContext.Provider, { value: depth + 1, children: /* @__PURE__ */ jsx("div", { role: "group", className: "flex flex-col w-full", children }) })
             }
           ) })
@@ -609,9 +865,32 @@ const TreeItem = React.forwardRef(
 );
 TreeItem.displayName = "TreeItem";
 const ParentIdContext = React.createContext(null);
+const treeViewMeta = {
+  component: "TreeView",
+  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 }
+  },
+  // '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-neutral-selected", "bg-surface"],
+    fg: ["text-fg-disabled", "text-fg-muted", "text-fg-secondary", "text-foreground"],
+    ring: ["ring-ring"]
+  },
+  defaultSize: "md"
+};
 export {
   TreeItem,
   TreeView,
-  treeItemVariants
+  treeItemVariants,
+  treeViewMeta
 };
 //# sourceMappingURL=tree-view.js.map