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

package/dist/components/TreeView/tree-view.d.ts

@@ -36,6 +36,42 @@ export interface TreeDragEndEvent {
     /** 放置位置:before(同層上方)/ after(同層下方)/ inside(成為子 node) */
     position: TreeDropPosition;
 }
+/**
+ * 鍵盤重排(`Cmd/Ctrl+Shift+方向鍵`,2026-07-14 v1)的 SR 播報文案 — zh-TW 預設,
+ * per-key merge 覆寫(i18n 覆寫點)。詳 tree-view.spec.md「鍵盤重排」。
+ * @public
+ */
+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;
+}
 export interface TreeViewProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onDragEnd'> {
     /** 元件尺寸,影響 node 高度、icon 大小、indent 寬度 */
     size?: SizeKey;
@@ -70,6 +106,12 @@ export interface TreeViewProps extends Omit<React.HTMLAttributes<HTMLDivElement>
     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;
 }
@@ -153,7 +195,20 @@ export declare const treeViewMeta: {
     readonly component: "TreeView";
     readonly family: 1;
     readonly variants: {};
-    readonly sizes: {};
+    readonly sizes: {
+        readonly sm: {
+            readonly typography: "body";
+            readonly indent: 24;
+        };
+        readonly md: {
+            readonly typography: "body";
+            readonly indent: 24;
+        };
+        readonly lg: {
+            readonly typography: "body-lg";
+            readonly indent: 28;
+        };
+    };
     readonly states: readonly ["default", "hover", "selected", "focus-visible", "disabled"];
     readonly tokens: {
         readonly bg: readonly ["bg-neutral-hover", "bg-neutral-selected", "bg-surface"];

package/dist/components/TreeView/tree-view.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tree-view.d.ts","sourceRoot":"","sources":["../../../src/components/TreeView/tree-view.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"tree-view.d.ts","sourceRoot":"","sources":["../../../src/components/TreeView/tree-view.tsx"],"names":[],"mappings":"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"}

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";
@@ -15,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);
@@ -44,6 +63,7 @@ const TreeView = React.forwardRef(
     expandOnSelect = false,
     draggable = false,
     onDragEnd: onDragEndProp,
+    reorderAnnouncements: reorderAnnouncementsProp,
     expandedIds: controlledExpanded,
     onExpandedChange,
     selectedIds: controlledSelected,
@@ -94,6 +114,12 @@ const TreeView = React.forwardRef(
     );
     const [focusedId, setFocusedId] = React.useState(null);
     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);
@@ -103,6 +129,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 } })
     );
@@ -112,7 +151,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;
@@ -183,7 +222,7 @@ const TreeView = React.forwardRef(
           autoExpandTimerRef.current = null;
         }
       }
-    }, [expandedIds]);
+    }, [expandedIds, isInSubtree]);
     const dropTargetRef = React.useRef(dropTarget);
     dropTargetRef.current = dropTarget;
     const handleDragEnd = React.useCallback((event) => {
@@ -193,7 +232,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),
@@ -202,7 +241,7 @@ const TreeView = React.forwardRef(
       }
       setDraggingId(null);
       setDropTarget(null);
-    }, [onDragEndProp]);
+    }, [onDragEndProp, isInSubtree]);
     const handleDragCancel = React.useCallback(() => {
       if (autoExpandTimerRef.current) {
         clearTimeout(autoExpandTimerRef.current);
@@ -211,7 +250,6 @@ const TreeView = React.forwardRef(
       setDraggingId(null);
       setDropTarget(null);
     }, []);
-    const { registerNode, unregisterNode, getNodeInfo } = useNodeRegistry();
     const toggleExpand = React.useCallback(
       (id) => {
         setExpandedIds((prev) => {
@@ -239,6 +277,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,
@@ -290,13 +461,21 @@ const TreeView = React.forwardRef(
       (e) => {
         isKeyboardRef.current = true;
         if (!treeRef.current) 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;
@@ -363,15 +542,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 提供
@@ -387,8 +568,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
       }
     );
@@ -402,6 +590,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;
@@ -579,7 +771,8 @@ const TreeItem = React.forwardRef(
                 //   - 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",
+                // 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",
@@ -630,7 +823,13 @@ const treeViewMeta = {
   family: 1,
   // Family 1(Menu item layout)消費者 — 對齊 tree-view.spec.md frontmatter family: 1
   variants: {},
-  sizes: {},
+  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"],