@qijenchen/design-system 0.1.0-beta.145 → 0.1.0-beta.147

package/dist/lib/focus-after-trigger.d.ts

@@ -0,0 +1,45 @@
+/**
+ * @internal — 「彈出框開著按 Tab:收起,焦點從觸發點往下 / 往上走一站」的**唯一**落點計算(2026-09-26 由兩份合一)。
+ *
+ * ── 規則住所 ─────────────────────────────────────────────────────────────────
+ * `ds-canonical/references/keyboard-model-canonical.md`「彈出框開著時的 Tab 與 Esc」:
+ *   「下一站一律從觸發點算」—— 彈出內容掛在 <body> 最末端(Portal),從選單項 / 選項往下走會掉到頁尾;
+ *   「觸發點在對話框 / 面板裡時,照那個框的規則在框內繞圈;頁面上已經沒有下一站時,焦點留在觸發點」。
+ * 消費者:`components/DropdownMenu/dropdown-menu-keyboard.ts`(選單,待辦總帳 B11)、
+ *        `components/SelectMenu/select-menu-keyboard.ts`(單選下拉 Tab 選定後離開、多選面板內繞圈,B11)。
+ *
+ * ── 決定來源 ─────────────────────────────────────────────────────────────────
+ * B11(`governance/planning/2026-09-25-interaction-and-hover-remediation.md`),user 逐字(附條件同意):
+ * 「你確定這個符合我們一致的設計語言且不違背世界級的設計就這樣做」;合併為一份 = 同檔〇節「09-26 同意清單回覆」
+ * 「按鍵規則合併」,user 逐字:「確保符合我們一致的設計語言且不違背世界級的設計且都有確保整個ds 是SSOT,避免漂移就照你建議做」。
+ * 批次細節 X20(同意清單):「選單在對話框裡 Tab 繞圈;無下一站時留觸發鈕」。
+ *
+ * 2026-09-26 之前兩份平行實作各差一點:選單版認正 tabindex 排序、單選鈕群組、觸發點本身不在 Tab 路上的情形,
+ * 到頁面邊緣時焦點留在觸發鈕;下拉版三者都不認,到頁面邊緣時交還瀏覽器 —— 那一下會落在 Radix 插在 <body> 首尾、
+ * 關閉動畫期間仍掛著的隱形焦點護欄上(@radix-ui/react-popover 的 PopoverContentImpl 也呼叫 useFocusGuards),
+ * 焦點消失一站。合一後兩者都照正本那一句:頁面上已經沒有下一站時,焦點留在觸發點。
+ */
+/** 呼叫端要排除的元素(例:正在關的那個彈出框本身 —— 關閉動畫期間還在 DOM 裡) */
+export type TabStopExclude = (el: HTMLElement) => boolean;
+/**
+ * 這個元素此刻在不在頁面的 Tab 路上(照瀏覽器規則;判準對齊 Radix FocusScope `getTabbableCandidates` + `isHidden`)。
+ * Radix 焦點護欄(body 首尾 tabindex=0 的隱形 span)不是頁面上的一站。
+ */
+export declare function isTabbableElement(el: HTMLElement): boolean;
+/** 範圍內的 Tab 順序:正 tabindex 先(由小到大),其餘照文件順序 */
+export declare function tabbableOrder(scope: HTMLElement, exclude?: TabStopExclude): HTMLElement[];
+/**
+ * 從觸發點往下(或往上)的那一站 —— 等於「彈出框關著時,在觸發點上按同一個鍵會到的那一格」。
+ * 觸發點在對話框 / 面板裡 → 只在那個框裡找,到頭繞回(W3C:"Like non-modal dialogs, modal dialogs contain their tab sequence."
+ * https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/dialog-modal/dialog-modal-pattern.html#L28-L31
+ * ;Radix Dialog / Popover 的 FocusScope loop);頁面層沒有下一站 → null。
+ */
+export declare function tabStopFromTrigger(trigger: HTMLElement, backward: boolean, exclude?: TabStopExclude): HTMLElement | null;
+/**
+ * 呼叫端**先把彈出框同步關掉**(flushSync:modal 的 FocusScope 焦點鎖要先解除,可打字的輸入框要先換回顯示值),
+ * 再呼叫這一支:焦點落到觸發點的下一站 / 上一站;頁面上已經沒有下一站 → 留在觸發點(X20)。
+ * 呼叫端負責 preventDefault(瀏覽器預設的 Tab 會從彈出框的位置 —— 頁尾 —— 往下走)。
+ * 回傳最後拿到焦點的元素。
+ */
+export declare function focusFromTrigger(trigger: HTMLElement, backward: boolean, exclude?: TabStopExclude): HTMLElement;
+//# sourceMappingURL=focus-after-trigger.d.ts.map

package/dist/lib/focus-after-trigger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-after-trigger.d.ts","sourceRoot":"","sources":["../../src/lib/focus-after-trigger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAQH,iDAAiD;AACjD,MAAM,MAAM,cAAc,GAAG,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAA;AAEzD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAa1D;AAED,6CAA6C;AAC7C,wBAAgB,aAAa,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,WAAW,EAAE,CAMzF;AAOD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,WAAW,GAAG,IAAI,CAiBxH;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,WAAW,CAM/G"}

package/dist/lib/focus-after-trigger.js

@@ -0,0 +1,66 @@
+const TABBABLE_CANDIDATES = [
+  "a[href]",
+  "area[href]",
+  "button",
+  "input",
+  "select",
+  "textarea",
+  "iframe",
+  "summary",
+  "audio[controls]",
+  "video[controls]",
+  '[contenteditable]:not([contenteditable="false"])',
+  "[tabindex]"
+].join(",");
+function isTabbableElement(el) {
+  if (el.tabIndex < 0) return false;
+  if (el.matches(":disabled")) return false;
+  if (el instanceof HTMLInputElement && el.type === "hidden") return false;
+  if (el.closest("[inert],[data-radix-focus-guard]")) return false;
+  if (el.getClientRects().length === 0) return false;
+  if (getComputedStyle(el).visibility === "hidden") return false;
+  if (el instanceof HTMLInputElement && el.type === "radio" && el.name && !el.checked) {
+    const group = Array.from(el.ownerDocument.getElementsByName(el.name));
+    if (group.some((n) => n instanceof HTMLInputElement && n.type === "radio" && n.form === el.form && n.checked)) return false;
+  }
+  return true;
+}
+function tabbableOrder(scope, exclude) {
+  const candidates = Array.from(scope.querySelectorAll(TABBABLE_CANDIDATES)).filter(
+    (el) => isTabbableElement(el) && !(exclude == null ? void 0 : exclude(el))
+  );
+  const positive = candidates.filter((el) => el.tabIndex > 0).sort((a, b) => a.tabIndex - b.tabIndex);
+  return [...positive, ...candidates.filter((el) => el.tabIndex === 0)];
+}
+function dialogScopeOf(trigger) {
+  var _a;
+  return ((_a = trigger.parentElement) == null ? void 0 : _a.closest('[role="dialog"],[role="alertdialog"]')) ?? null;
+}
+function tabStopFromTrigger(trigger, backward, exclude) {
+  const scope = dialogScopeOf(trigger);
+  const order = tabbableOrder(scope ?? trigger.ownerDocument.body, exclude);
+  const at = order.indexOf(trigger);
+  let target;
+  if (at !== -1) {
+    target = order[backward ? at - 1 : at + 1];
+  } else {
+    const flow = order.filter((el) => el.tabIndex === 0);
+    target = backward ? [...flow].reverse().find((el) => trigger.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_PRECEDING) : flow.find((el) => trigger.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING);
+  }
+  if (target) return target;
+  if (scope && order.length > 0) return backward ? order[order.length - 1] : order[0];
+  return null;
+}
+function focusFromTrigger(trigger, backward, exclude) {
+  const next = tabStopFromTrigger(trigger, backward, exclude) ?? trigger;
+  next.focus();
+  if (next.ownerDocument.activeElement !== next) window.setTimeout(() => next.focus(), 0);
+  return next;
+}
+export {
+  focusFromTrigger,
+  isTabbableElement,
+  tabStopFromTrigger,
+  tabbableOrder
+};
+//# sourceMappingURL=focus-after-trigger.js.map

package/dist/lib/focus-after-trigger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"focus-after-trigger.js","sources":["../../src/lib/focus-after-trigger.ts"],"sourcesContent":["/**\n * @internal — 「彈出框開著按 Tab:收起,焦點從觸發點往下 / 往上走一站」的**唯一**落點計算(2026-09-26 由兩份合一)。\n *\n * ── 規則住所 ─────────────────────────────────────────────────────────────────\n * `ds-canonical/references/keyboard-model-canonical.md`「彈出框開著時的 Tab 與 Esc」:\n *   「下一站一律從觸發點算」—— 彈出內容掛在 <body> 最末端(Portal),從選單項 / 選項往下走會掉到頁尾;\n *   「觸發點在對話框 / 面板裡時,照那個框的規則在框內繞圈;頁面上已經沒有下一站時,焦點留在觸發點」。\n * 消費者:`components/DropdownMenu/dropdown-menu-keyboard.ts`(選單,待辦總帳 B11)、\n *        `components/SelectMenu/select-menu-keyboard.ts`(單選下拉 Tab 選定後離開、多選面板內繞圈,B11)。\n *\n * ── 決定來源 ─────────────────────────────────────────────────────────────────\n * B11(`governance/planning/2026-09-25-interaction-and-hover-remediation.md`),user 逐字(附條件同意):\n * 「你確定這個符合我們一致的設計語言且不違背世界級的設計就這樣做」;合併為一份 = 同檔〇節「09-26 同意清單回覆」\n * 「按鍵規則合併」,user 逐字:「確保符合我們一致的設計語言且不違背世界級的設計且都有確保整個ds 是SSOT,避免漂移就照你建議做」。\n * 批次細節 X20(同意清單):「選單在對話框裡 Tab 繞圈;無下一站時留觸發鈕」。\n *\n * 2026-09-26 之前兩份平行實作各差一點:選單版認正 tabindex 排序、單選鈕群組、觸發點本身不在 Tab 路上的情形,\n * 到頁面邊緣時焦點留在觸發鈕;下拉版三者都不認,到頁面邊緣時交還瀏覽器 —— 那一下會落在 Radix 插在 <body> 首尾、\n * 關閉動畫期間仍掛著的隱形焦點護欄上(@radix-ui/react-popover 的 PopoverContentImpl 也呼叫 useFocusGuards),\n * 焦點消失一站。合一後兩者都照正本那一句:頁面上已經沒有下一站時,焦點留在觸發點。\n */\n\n/** 瀏覽器可能放進 Tab 順序的元素(候選;再經 `isTabbableElement` 過濾) */\nconst TABBABLE_CANDIDATES = [\n  'a[href]', 'area[href]', 'button', 'input', 'select', 'textarea', 'iframe', 'summary',\n  'audio[controls]', 'video[controls]', '[contenteditable]:not([contenteditable=\"false\"])', '[tabindex]',\n].join(',')\n\n/** 呼叫端要排除的元素(例:正在關的那個彈出框本身 —— 關閉動畫期間還在 DOM 裡) */\nexport type TabStopExclude = (el: HTMLElement) => boolean\n\n/**\n * 這個元素此刻在不在頁面的 Tab 路上(照瀏覽器規則;判準對齊 Radix FocusScope `getTabbableCandidates` + `isHidden`)。\n * Radix 焦點護欄(body 首尾 tabindex=0 的隱形 span)不是頁面上的一站。\n */\nexport function isTabbableElement(el: HTMLElement): boolean {\n  if (el.tabIndex < 0) return false\n  if (el.matches(':disabled')) return false\n  if (el instanceof HTMLInputElement && el.type === 'hidden') return false\n  if (el.closest('[inert],[data-radix-focus-guard]')) return false\n  if (el.getClientRects().length === 0) return false\n  if (getComputedStyle(el).visibility === 'hidden') return false\n  // 同名單選鈕:有勾選的那顆才在 Tab 路上(全未勾時整組都算,往下落第一顆、往上落最後一顆 —— 瀏覽器行為)\n  if (el instanceof HTMLInputElement && el.type === 'radio' && el.name && !el.checked) {\n    const group = Array.from(el.ownerDocument.getElementsByName(el.name))\n    if (group.some((n) => n instanceof HTMLInputElement && n.type === 'radio' && n.form === el.form && n.checked)) return false\n  }\n  return true\n}\n\n/** 範圍內的 Tab 順序:正 tabindex 先(由小到大),其餘照文件順序 */\nexport function tabbableOrder(scope: HTMLElement, exclude?: TabStopExclude): HTMLElement[] {\n  const candidates = Array.from(scope.querySelectorAll<HTMLElement>(TABBABLE_CANDIDATES)).filter(\n    (el) => isTabbableElement(el) && !exclude?.(el),\n  )\n  const positive = candidates.filter((el) => el.tabIndex > 0).sort((a, b) => a.tabIndex - b.tabIndex)\n  return [...positive, ...candidates.filter((el) => el.tabIndex === 0)]\n}\n\n/** 觸發點外層的對話框 / 面板(`role=\"dialog\"` / `\"alertdialog\"`):Tab 本來就在那個框裡繞圈(W3C dialog pattern) */\nfunction dialogScopeOf(trigger: HTMLElement): HTMLElement | null {\n  return trigger.parentElement?.closest<HTMLElement>('[role=\"dialog\"],[role=\"alertdialog\"]') ?? null\n}\n\n/**\n * 從觸發點往下(或往上)的那一站 —— 等於「彈出框關著時,在觸發點上按同一個鍵會到的那一格」。\n * 觸發點在對話框 / 面板裡 → 只在那個框裡找,到頭繞回(W3C:\"Like non-modal dialogs, modal dialogs contain their tab sequence.\"\n * https://github.com/w3c/aria-practices/blob/3f094fde1c81b25dfa69162563bf28d093f854d4/content/patterns/dialog-modal/dialog-modal-pattern.html#L28-L31\n * ;Radix Dialog / Popover 的 FocusScope loop);頁面層沒有下一站 → null。\n */\nexport function tabStopFromTrigger(trigger: HTMLElement, backward: boolean, exclude?: TabStopExclude): HTMLElement | null {\n  const scope = dialogScopeOf(trigger)\n  const order = tabbableOrder(scope ?? trigger.ownerDocument.body, exclude)\n  const at = order.indexOf(trigger)\n  let target: HTMLElement | undefined\n  if (at !== -1) {\n    target = order[backward ? at - 1 : at + 1]\n  } else {\n    // 觸發點本身不在 Tab 路上(例:tabindex=-1 的列上小按鈕)→ 跟瀏覽器一樣,以它在文件裡的位置為起點\n    const flow = order.filter((el) => el.tabIndex === 0)\n    target = backward\n      ? [...flow].reverse().find((el) => trigger.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_PRECEDING)\n      : flow.find((el) => trigger.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING)\n  }\n  if (target) return target\n  if (scope && order.length > 0) return backward ? order[order.length - 1] : order[0]\n  return null\n}\n\n/**\n * 呼叫端**先把彈出框同步關掉**(flushSync:modal 的 FocusScope 焦點鎖要先解除,可打字的輸入框要先換回顯示值),\n * 再呼叫這一支:焦點落到觸發點的下一站 / 上一站;頁面上已經沒有下一站 → 留在觸發點(X20)。\n * 呼叫端負責 preventDefault(瀏覽器預設的 Tab 會從彈出框的位置 —— 頁尾 —— 往下走)。\n * 回傳最後拿到焦點的元素。\n */\nexport function focusFromTrigger(trigger: HTMLElement, backward: boolean, exclude?: TabStopExclude): HTMLElement {\n  const next = tabStopFromTrigger(trigger, backward, exclude) ?? trigger\n  next.focus()\n  // 焦點被同一個 task 裡的關閉流程拉走時(modal 選單的焦點鎖卸載),下一個 macrotask 再給一次\n  if (next.ownerDocument.activeElement !== next) window.setTimeout(() => next.focus(), 0)\n  return next\n}\n"],"names":[],"mappings":"AAuBA,MAAM,sBAAsB;AAAA,EAC1B;AAAA,EAAW;AAAA,EAAc;AAAA,EAAU;AAAA,EAAS;AAAA,EAAU;AAAA,EAAY;AAAA,EAAU;AAAA,EAC5E;AAAA,EAAmB;AAAA,EAAmB;AAAA,EAAoD;AAC5F,EAAE,KAAK,GAAG;AASH,SAAS,kBAAkB,IAA0B;AAC1D,MAAI,GAAG,WAAW,EAAG,QAAO;AAC5B,MAAI,GAAG,QAAQ,WAAW,EAAG,QAAO;AACpC,MAAI,cAAc,oBAAoB,GAAG,SAAS,SAAU,QAAO;AACnE,MAAI,GAAG,QAAQ,kCAAkC,EAAG,QAAO;AAC3D,MAAI,GAAG,eAAA,EAAiB,WAAW,EAAG,QAAO;AAC7C,MAAI,iBAAiB,EAAE,EAAE,eAAe,SAAU,QAAO;AAEzD,MAAI,cAAc,oBAAoB,GAAG,SAAS,WAAW,GAAG,QAAQ,CAAC,GAAG,SAAS;AACnF,UAAM,QAAQ,MAAM,KAAK,GAAG,cAAc,kBAAkB,GAAG,IAAI,CAAC;AACpE,QAAI,MAAM,KAAK,CAAC,MAAM,aAAa,oBAAoB,EAAE,SAAS,WAAW,EAAE,SAAS,GAAG,QAAQ,EAAE,OAAO,EAAG,QAAO;AAAA,EACxH;AACA,SAAO;AACT;AAGO,SAAS,cAAc,OAAoB,SAAyC;AACzF,QAAM,aAAa,MAAM,KAAK,MAAM,iBAA8B,mBAAmB,CAAC,EAAE;AAAA,IACtF,CAAC,OAAO,kBAAkB,EAAE,KAAK,EAAC,mCAAU;AAAA,EAAE;AAEhD,QAAM,WAAW,WAAW,OAAO,CAAC,OAAO,GAAG,WAAW,CAAC,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,WAAW,EAAE,QAAQ;AAClG,SAAO,CAAC,GAAG,UAAU,GAAG,WAAW,OAAO,CAAC,OAAO,GAAG,aAAa,CAAC,CAAC;AACtE;AAGA,SAAS,cAAc,SAA0C;AArCjE;AAsCE,WAAO,aAAQ,kBAAR,mBAAuB,QAAqB,4CAA2C;AAChG;AAQO,SAAS,mBAAmB,SAAsB,UAAmB,SAA8C;AACxH,QAAM,QAAQ,cAAc,OAAO;AACnC,QAAM,QAAQ,cAAc,SAAS,QAAQ,cAAc,MAAM,OAAO;AACxE,QAAM,KAAK,MAAM,QAAQ,OAAO;AAChC,MAAI;AACJ,MAAI,OAAO,IAAI;AACb,aAAS,MAAM,WAAW,KAAK,IAAI,KAAK,CAAC;AAAA,EAC3C,OAAO;AAEL,UAAM,OAAO,MAAM,OAAO,CAAC,OAAO,GAAG,aAAa,CAAC;AACnD,aAAS,WACL,CAAC,GAAG,IAAI,EAAE,UAAU,KAAK,CAAC,OAAO,QAAQ,wBAAwB,EAAE,IAAI,KAAK,2BAA2B,IACvG,KAAK,KAAK,CAAC,OAAO,QAAQ,wBAAwB,EAAE,IAAI,KAAK,2BAA2B;AAAA,EAC9F;AACA,MAAI,OAAQ,QAAO;AACnB,MAAI,SAAS,MAAM,SAAS,EAAG,QAAO,WAAW,MAAM,MAAM,SAAS,CAAC,IAAI,MAAM,CAAC;AAClF,SAAO;AACT;AAQO,SAAS,iBAAiB,SAAsB,UAAmB,SAAuC;AAC/G,QAAM,OAAO,mBAAmB,SAAS,UAAU,OAAO,KAAK;AAC/D,OAAK,MAAA;AAEL,MAAI,KAAK,cAAc,kBAAkB,KAAM,QAAO,WAAW,MAAM,KAAK,MAAA,GAAS,CAAC;AACtF,SAAO;AACT;"}

package/dist/lib/overlay-coexistence.js

@@ -1,5 +1,5 @@
 import * as React from "react";
-import { suppressOthers } from "../node_modules/aria-hidden/dist/es2015/index.js";
+import { suppressOthers } from "aria-hidden";
 import { cn } from "./utils.js";
 function useOverlayCoexistence(active, keep) {
   React.useEffect(() => {

package/dist/lib/roving-list-keyboard.d.ts

@@ -0,0 +1,208 @@
+/**
+ * @internal — 「列上有小按鈕的一串」鍵盤路線的**唯一**判定與執行(2026-09-26 由四份合一)。
+ *
+ * ── 規則住所 ─────────────────────────────────────────────────────────────────
+ * 規則(Tab 換區、方向鍵在區裡走、Esc 退一步)= `ds-canonical/references/keyboard-model-canonical.md`
+ * 「列上有小按鈕的一串」;本檔是那張按鍵表**唯一的程式版**,四個宿主只讀自己的 DOM、執行結果:
+ *   - `components/Sidebar/sidebar.tsx`        SidebarMenu(真焦點,roving tabindex)
+ *   - `components/FileUpload/file-upload.tsx` 內建檔案清單(真焦點,roving tabindex)
+ *   - `components/TreeView/tree-view.tsx`      樹狀表格(真焦點 + 樹的展開 / 收合 / 回上一層 + 鍵盤重排)
+ *   - `components/Command/command.tsx`         cmdk 清單(「這一項」= 反白列,焦點停在搜尋框 / 清單 = home)
+ *
+ * ── 決定來源 ─────────────────────────────────────────────────────────────────
+ * 路線乙:待辦總帳 `governance/planning/2026-09-25-interaction-and-hover-remediation.md` B9,user 逐字(附條件同意,
+ * 條件查證成立記在同列):「確定建議符合我們一致的設計語言且不違背世界級的設計就照建議」。
+ * 合併與 X1–X7 統一:同檔〇節「09-26 同意清單回覆」,user 逐字:「確保符合我們一致的設計語言且不違背世界級的設計且都有
+ * 確保整個ds 是SSOT,避免漂移就照你建議做」—— 同意的清單含「按鍵規則合併」與批次細節 X1–X35,其中
+ * X4(按鈕上 Home / End)、X6(列上選單鈕按 ↓)、X7(樹在按鈕上 Shift+Tab)三處「統一成側欄做法」。
+ * 2026-09-26 之前這張表有四份平行實作(側欄 / 檔案清單 / 樹 `tree-keyboard-route.ts` / Command),三處互相不一致:
+ *   X4 側欄與檔案清單的按鈕上 Home / End 換到頭尾項,樹不處理;
+ *   X6 側欄的選單鈕按 ↓ 換下一項,樹讓給按鈕開選單;
+ *   X7 側欄在按鈕上 Shift+Tab 一下離開,樹要兩下(先落回本列)—— 違反 B9「Tab 一下離開」。
+ *
+ * ── 本檔兩層 ─────────────────────────────────────────────────────────────────
+ *   (一) 判定(純函式,不碰 DOM):`resolveRovingKey` / `pickRovingTarget` / `pickRovingTabStop`
+ *        —— 判定表 `scripts/test-roving-list-keyboard.mjs`(含舊路線對照組)逐格驗。
+ *   (二) 宿主共用的 DOM 小工具:列裡可走到的東西、把它們收出 Tab 路、真焦點宿主的執行器 `applyRovingAction`。
+ *        Command 是虛擬游標(cmdk 自己搬反白),執行方式不同,在 command.tsx 自己對應 —— 判定仍只讀本檔。
+ */
+/** 按鍵發生時,焦點在「這一項」本身,還是這一項裡的某一個東西(小按鈕 / 連結 / 名片頭像…) */
+export type RovingFocus = 'item' | 'control';
+/** 樹才有的三個狀態;平面清單不傳 = 沒有「先展開」「回上一層」這兩步 */
+export interface RovingTreeState {
+    hasChildren: boolean;
+    expanded: boolean;
+    hasParent: boolean;
+}
+export interface RovingKeyInput {
+    /** KeyboardEvent.key */
+    key: string;
+    focus: RovingFocus;
+    /** 這一項可以用 → 走到的東西數(宿主以 `listRovingControls` 數出來) */
+    controlCount: number;
+    /** focus === 'control' 時焦點在第幾個(0 起算);focus === 'item' 時不讀 */
+    controlIndex: number;
+    /** 焦點所在的東西是文字輸入(輸入框 / 多行框 / 下拉 / 可編輯區):方向鍵、Home / End、Enter / 空白鍵都屬於它自己 */
+    controlIsTextEntry?: boolean;
+    /** 「這一項」本身是文字輸入(只有 Command 的搜尋框):← / Home / End / 打字屬於插入點 */
+    itemIsTextEntry?: boolean;
+    /** itemIsTextEntry 時:插入點已在字尾(且沒有選取範圍)。不在字尾時 → 要留給插入點移動 */
+    caretAtEnd?: boolean;
+    /** 樹的狀態;平面清單不傳 */
+    tree?: RovingTreeState;
+    /** 可以用 Cmd / Ctrl + Shift + 方向鍵重排(只有 draggable 的樹) */
+    reorderable?: boolean;
+    /**
+     * 這一串有「打字跳位」(只有樹:keyboard-model-canonical.md 五條判準第 2 條「需要 tree 那一整套鍵盤模型(打字前導、…)」)。
+     * 焦點在項目上打一個可見字元 → 回 `typeahead`,由宿主找下一個名字以該字開頭的項目;平面清單(側欄 / 檔案清單)不傳 = 不處理。
+     * 出處:W3C APG Tree View 逐字 "Type a character: focus moves to the next node with a name that starts with the typed character."
+     * (<https://www.w3.org/WAI/ARIA/apg/patterns/treeview/>)。
+     */
+    typeahead?: boolean;
+    /** 事件已被更外層的捕獲處理程式 preventDefault */
+    defaultPrevented: boolean;
+    metaKey: boolean;
+    ctrlKey: boolean;
+    altKey: boolean;
+    shiftKey: boolean;
+}
+export type RovingReorderKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight';
+export type RovingMove = 'item-prev' | 'item-next' | 'item-first' | 'item-last';
+export type RovingKeyAction = 
+/** 不處理 —— 交給瀏覽器、插入點或那個東西自己 */
+{
+    type: 'none';
+}
+/** 吃掉按鍵(preventDefault)但不動焦點 —— 例:已在最後一顆按鈕上再按 → */
+ | {
+    type: 'consume';
+}
+/** 換到上 / 下 / 第一 / 最後一項(焦點落在項目上;不繞回) */
+ | {
+    type: RovingMove;
+} | {
+    type: 'expand';
+} | {
+    type: 'collapse';
+} | {
+    type: 'parent';
+}
+/** 把焦點放到這一項第 index 個東西 */
+ | {
+    type: 'control';
+    index: number;
+}
+/** 焦點回到這一項本身 */
+ | {
+    type: 'item';
+}
+/** Tab / Shift+Tab:焦點先回到這一項(整串唯一的 Tab 停靠點),**不擋預設** —— 瀏覽器接著往下 / 往上走一站 = 一下離開這一串 */
+ | {
+    type: 'leave';
+}
+/** Enter / 空白鍵在項目上:這一項自己的預設動作(樹 = 選取;原生按鈕 = 瀏覽器自己點) */
+ | {
+    type: 'activate-item';
+}
+/** Enter / 空白鍵在項目裡的按鈕 / 連結上:那個東西自己的動作,**不是**「選這一項」 */
+ | {
+    type: 'activate-control';
+}
+/** 鍵盤重排(樹;修飾鍵層,與導覽鍵正交) */
+ | {
+    type: 'reorder';
+    key: RovingReorderKey;
+}
+/** 打字跳位(只有 `typeahead: true` 的宿主):焦點在項目上打了一個可見字元,由宿主找下一個名字以它開頭的項目 */
+ | {
+    type: 'typeahead';
+    char: string;
+};
+/**
+ * 按鍵表(規格 SSOT = keyboard-model-canonical.md「列上有小按鈕的一串」;每一格的來歷寫在該格旁):
+ *
+ * | 鍵 | 焦點在項目上 | 焦點在這一項的東西上 |
+ * |---|---|---|
+ * | ↑ ↓ | 上 / 下一項 | 回到上 / 下一項(X3,依 Adobe 方向鍵模式;選單鈕也一樣 —— X6 統一成側欄做法) |
+ * | Home End | 第一 / 最後一項 | 同左(X4 統一成側欄做法) |
+ * | → | 樹裡收著的資料夾先展開;否則進第一個東西;沒有就不動 | 下一個;最後一個停住 |
+ * | ← | 樹:展開的先收合、否則回上一層;平面清單:不動 | 上一個;第一個 → 回項目 |
+ * | Tab / Shift+Tab | 一下離開這一串 | 同左(X7:先回項目、再由瀏覽器往外走) |
+ * | Enter / 空白鍵 | 這一項自己的預設動作 | 那個東西自己的動作 |
+ * | 可見字元(只有 `typeahead` 宿主 = 樹)| 打字跳位:下一個名字以它開頭的項目(W3C APG Tree View) | 不處理(按鈕上打字沒有意義) |
+ */
+export declare function resolveRovingKey(input: RovingKeyInput): RovingKeyAction;
+/**
+ * 上 / 下 / 第一 / 最後一項落在哪 —— **不繞回**(同 W3C grid / tree;X2)。
+ * `items` 依畫面順序、含走不到的項目(停用、看不見);`isNavigable` 決定哪些能當落點。
+ * 目前這一項本身走不到(例:樹裡用 ← 回到停用的上一層)時,仍從它的位置往前 / 往後找。
+ */
+export declare function pickRovingTarget<T>(move: RovingMove, items: readonly T[], current: T | null, isNavigable?: (item: T) => boolean): T | null;
+export interface RovingTabStopOptions<T> {
+    /** 上次焦點停過的那一項 */
+    remembered?: T | null;
+    /** 「目前這一頁 / 選中」那一項(側欄 aria-current="page";樹 aria-selected) */
+    isCurrent?: (item: T) => boolean;
+    /** 能不能當「目前」或「第一項」的落點(停用、看不見的不算) */
+    isNavigable?: (item: T) => boolean;
+    /** 上次停過的那一項還能不能拿焦點(預設同 isNavigable;樹的停用列仍可經 ← 拿到焦點,傳 () => true) */
+    canHoldFocus?: (item: T) => boolean;
+}
+/**
+ * 整串唯一的 Tab 停靠點(X1):上次停過的那一項 → 目前這一頁 / 選中那一項 → 第一個可用項。
+ * 出處:W3C「the element that had focus the last time the composite contained focus」+ 導覽樹範例
+ * 「focus always lands on the item representing the current page」(keyboard-model-canonical.md 同節引文)。
+ */
+export declare function pickRovingTabStop<T>(items: readonly T[], options?: RovingTabStopOptions<T>): T | null;
+/**
+ * 項目裡「可以走到的東西」的候選(再經 `isRovingControlReachable` 過濾)。
+ * 2026-09-26 之前四份各寫一份、各差一點(樹多認 contenteditable、側欄只認按鈕類),合成這一份;
+ * 側欄另有自己的範圍(只認動作鈕的兩個出口),以參數傳入。
+ */
+export declare const ROVING_CONTROL_SELECTOR = "a[href], button, input, select, textarea, [contenteditable]:not([contenteditable=\"false\"]), [tabindex]";
+/** 把候選 selector 限定在某個範圍裡(`[cmdk-item] a[href], [cmdk-item] button, …`)。不用 `:is()`:舊版 jsdom 不認得。 */
+export declare function scopeRovingSelector(scope: string, selector?: string): string;
+export declare function isTextEntryElement(el: Element): boolean;
+/**
+ * 此刻走得到:沒有停用、不在 inert / aria-hidden 裡(例:多選列的勾選框是 inert + aria-hidden 的純視覺)、
+ * 畫得出來(display:none 不算;opacity 0 的「滑過才出現」按鈕算 —— 鍵盤走到時它會浮出)。
+ */
+export declare function isRovingControlReachable(el: HTMLElement): boolean;
+/** 某一項裡可以走到的東西,依畫面(文件)順序。 */
+export declare function listRovingControls(root: Element, selector?: string): HTMLElement[];
+/** 只在值不同時才寫:同值 setAttribute 也會產生 mutation record,會讓宿主的 MutationObserver 自我觸發。 */
+export declare function setRovingTabIndex(el: HTMLElement, value: 0 | -1): void;
+/**
+ * 項目裡的東西一律不在 Tab 路上(-1,→ 才進得去;別項與本項的都一樣)。
+ * 用 DOM 設而不是逐一傳 prop:consumer 的插槽(inlineActionsSlot / description / 名片頭像)是任意 ReactNode,拿不到它們的 props。
+ */
+export declare function removeRovingControlsFromTabOrder(elements: Iterable<HTMLElement>): void;
+/** 真焦點宿主(側欄 / 檔案清單 / 樹)執行判定結果時要的東西 */
+export interface RovingDomHost {
+    event: {
+        preventDefault(): void;
+    };
+    /** 目前這一項(整串唯一的 Tab 停靠點就在這種元素上) */
+    item: HTMLElement;
+    /** 這一項可以走到的東西(已過濾,`listRovingControls`) */
+    controls: readonly HTMLElement[];
+    /** 整串的項目,依畫面順序(含走不到的;由 isNavigable 篩) */
+    items: readonly HTMLElement[];
+    isNavigable?: (item: HTMLElement) => boolean;
+    /** 樹傳 { preventScroll: true }(捲動由列自己的 scrollIntoView 以 block:nearest 處理) */
+    focusOptions?: FocusOptions;
+    /** 樹才有:展開 / 收合 / 回上一層 */
+    onExpand?: () => void;
+    onCollapse?: () => void;
+    onParent?: () => void;
+    /** 項目本身的預設動作要由宿主執行時才傳(樹 = 選取);不傳 = 項目是原生按鈕,交給瀏覽器 */
+    onActivateItem?: () => void;
+    /** 打字跳位(只有 `typeahead: true` 的宿主):宿主自己累積字串、找項目、搬焦點 */
+    onTypeahead?: (char: string) => void;
+}
+/**
+ * 真焦點宿主的執行器:判定之外只剩「焦點怎麼搬、要不要擋預設」,三個宿主完全相同,所以也只寫一份。
+ * `reorder` 不在這裡(樹自己處理:要看是否正在用滑鼠拖曳)。
+ */
+export declare function applyRovingAction(action: RovingKeyAction, host: RovingDomHost): void;
+//# sourceMappingURL=roving-list-keyboard.d.ts.map

package/dist/lib/roving-list-keyboard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roving-list-keyboard.d.ts","sourceRoot":"","sources":["../../src/lib/roving-list-keyboard.ts"],"names":[],"mappings":"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"}

package/dist/lib/roving-list-keyboard.js

@@ -0,0 +1,174 @@
+const REORDER_KEYS = ["ArrowUp", "ArrowDown", "ArrowLeft", "ArrowRight"];
+const isReorderKey = (key) => REORDER_KEYS.includes(key);
+function resolveRovingKey(input) {
+  const { key } = input;
+  if (input.defaultPrevented) return { type: "none" };
+  if (input.focus === "item" && input.reorderable && (input.metaKey || input.ctrlKey) && input.shiftKey && isReorderKey(key)) {
+    return { type: "reorder", key };
+  }
+  if (input.metaKey || input.ctrlKey || input.altKey) return { type: "none" };
+  if (key === "Tab") return { type: "leave" };
+  if (input.focus === "control") {
+    if (input.controlIsTextEntry) return { type: "none" };
+    switch (key) {
+      case "ArrowRight":
+        return input.controlIndex < input.controlCount - 1 ? { type: "control", index: input.controlIndex + 1 } : { type: "consume" };
+      case "ArrowLeft":
+        return input.controlIndex > 0 ? { type: "control", index: input.controlIndex - 1 } : { type: "item" };
+      case "ArrowDown":
+        return { type: "item-next" };
+      case "ArrowUp":
+        return { type: "item-prev" };
+      case "Home":
+        return { type: "item-first" };
+      case "End":
+        return { type: "item-last" };
+      case "Enter":
+      case " ":
+        return { type: "activate-control" };
+      default:
+        return { type: "none" };
+    }
+  }
+  if (input.itemIsTextEntry) {
+    if (key === "ArrowRight") {
+      return !input.shiftKey && input.caretAtEnd !== false && input.controlCount > 0 ? { type: "control", index: 0 } : { type: "none" };
+    }
+    if (key === "ArrowDown") return { type: "item-next" };
+    if (key === "ArrowUp") return { type: "item-prev" };
+    return { type: "none" };
+  }
+  switch (key) {
+    case "ArrowDown":
+      return { type: "item-next" };
+    case "ArrowUp":
+      return { type: "item-prev" };
+    case "Home":
+      return { type: "item-first" };
+    case "End":
+      return { type: "item-last" };
+    case "ArrowRight": {
+      const tree = input.tree;
+      if (tree && tree.hasChildren && !tree.expanded) return { type: "expand" };
+      return input.controlCount > 0 ? { type: "control", index: 0 } : { type: "consume" };
+    }
+    case "ArrowLeft": {
+      const tree = input.tree;
+      if (tree && tree.hasChildren && tree.expanded) return { type: "collapse" };
+      return tree && tree.hasParent ? { type: "parent" } : { type: "consume" };
+    }
+    case "Enter":
+    case " ":
+      return { type: "activate-item" };
+    default:
+      if (input.typeahead && key.length === 1 && key !== " ") return { type: "typeahead", char: key };
+      return { type: "none" };
+  }
+}
+function pickRovingTarget(move, items, current, isNavigable = () => true) {
+  if (move === "item-first") return items.find(isNavigable) ?? null;
+  if (move === "item-last") {
+    for (let i = items.length - 1; i >= 0; i--) if (isNavigable(items[i])) return items[i];
+    return null;
+  }
+  const start = current == null ? -1 : items.indexOf(current);
+  if (start < 0) return null;
+  const dir = move === "item-next" ? 1 : -1;
+  for (let i = start + dir; i >= 0 && i < items.length; i += dir) {
+    if (isNavigable(items[i])) return items[i];
+  }
+  return null;
+}
+function pickRovingTabStop(items, options = {}) {
+  const isNavigable = options.isNavigable ?? (() => true);
+  const canHoldFocus = options.canHoldFocus ?? isNavigable;
+  const { remembered, isCurrent } = options;
+  if (remembered != null && items.includes(remembered) && canHoldFocus(remembered)) return remembered;
+  const current = isCurrent ? items.find((item) => isNavigable(item) && isCurrent(item)) : void 0;
+  return current ?? items.find(isNavigable) ?? null;
+}
+const ROVING_CONTROL_SELECTOR = 'a[href], button, input, select, textarea, [contenteditable]:not([contenteditable="false"]), [tabindex]';
+function scopeRovingSelector(scope, selector = ROVING_CONTROL_SELECTOR) {
+  return selector.split(",").map((part) => `${scope} ${part.trim()}`).join(", ");
+}
+const NON_TEXT_INPUT_TYPES = /* @__PURE__ */ new Set(["checkbox", "radio", "range", "color", "file", "image", "button", "submit", "reset", "hidden"]);
+function isTextEntryElement(el) {
+  if (el.tagName === "TEXTAREA" || el.tagName === "SELECT") return true;
+  if (el.tagName === "INPUT") return !NON_TEXT_INPUT_TYPES.has(el.type);
+  return el.isContentEditable === true;
+}
+function isRovingControlReachable(el) {
+  return !el.disabled && !el.closest('[inert], [aria-hidden="true"]') && el.getClientRects().length > 0;
+}
+function listRovingControls(root, selector = ROVING_CONTROL_SELECTOR) {
+  return Array.from(root.querySelectorAll(selector)).filter(isRovingControlReachable);
+}
+function setRovingTabIndex(el, value) {
+  if (el.getAttribute("tabindex") !== String(value)) el.setAttribute("tabindex", String(value));
+}
+function removeRovingControlsFromTabOrder(elements) {
+  for (const el of elements) setRovingTabIndex(el, -1);
+}
+function applyRovingAction(action, host) {
+  var _a, _b, _c, _d, _e;
+  const { event, item, controls, focusOptions } = host;
+  switch (action.type) {
+    case "none":
+    case "reorder":
+    case "activate-control":
+      return;
+    case "leave":
+      item.focus(focusOptions);
+      return;
+    case "activate-item":
+      if (!host.onActivateItem) return;
+      event.preventDefault();
+      host.onActivateItem();
+      return;
+    case "typeahead":
+      if (!host.onTypeahead) return;
+      event.preventDefault();
+      host.onTypeahead(action.char);
+      return;
+  }
+  event.preventDefault();
+  switch (action.type) {
+    case "consume":
+      return;
+    case "item-prev":
+    case "item-next":
+    case "item-first":
+    case "item-last":
+      (_a = pickRovingTarget(action.type, host.items, item, host.isNavigable)) == null ? void 0 : _a.focus(focusOptions);
+      return;
+    case "control":
+      (_b = controls[action.index]) == null ? void 0 : _b.focus(focusOptions);
+      return;
+    case "item":
+      item.focus(focusOptions);
+      return;
+    case "expand":
+      (_c = host.onExpand) == null ? void 0 : _c.call(host);
+      return;
+    case "collapse":
+      (_d = host.onCollapse) == null ? void 0 : _d.call(host);
+      return;
+    case "parent":
+      (_e = host.onParent) == null ? void 0 : _e.call(host);
+      return;
+  }
+}
+export {
+  ROVING_CONTROL_SELECTOR,
+  applyRovingAction,
+  isRovingControlReachable,
+  isTextEntryElement,
+  listRovingControls,
+  pickRovingTabStop,
+  pickRovingTarget,
+  removeRovingControlsFromTabOrder,
+  resolveRovingKey,
+  scopeRovingSelector,
+  setRovingTabIndex
+};
+//# sourceMappingURL=roving-list-keyboard.js.map

package/dist/lib/roving-list-keyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"roving-list-keyboard.js","sources":["../../src/lib/roving-list-keyboard.ts"],"sourcesContent":["/**\n * @internal — 「列上有小按鈕的一串」鍵盤路線的**唯一**判定與執行(2026-09-26 由四份合一)。\n *\n * ── 規則住所 ─────────────────────────────────────────────────────────────────\n * 規則(Tab 換區、方向鍵在區裡走、Esc 退一步)= `ds-canonical/references/keyboard-model-canonical.md`\n * 「列上有小按鈕的一串」;本檔是那張按鍵表**唯一的程式版**,四個宿主只讀自己的 DOM、執行結果:\n *   - `components/Sidebar/sidebar.tsx`        SidebarMenu(真焦點,roving tabindex)\n *   - `components/FileUpload/file-upload.tsx` 內建檔案清單(真焦點,roving tabindex)\n *   - `components/TreeView/tree-view.tsx`      樹狀表格(真焦點 + 樹的展開 / 收合 / 回上一層 + 鍵盤重排)\n *   - `components/Command/command.tsx`         cmdk 清單(「這一項」= 反白列,焦點停在搜尋框 / 清單 = home)\n *\n * ── 決定來源 ─────────────────────────────────────────────────────────────────\n * 路線乙:待辦總帳 `governance/planning/2026-09-25-interaction-and-hover-remediation.md` B9,user 逐字(附條件同意,\n * 條件查證成立記在同列):「確定建議符合我們一致的設計語言且不違背世界級的設計就照建議」。\n * 合併與 X1–X7 統一:同檔〇節「09-26 同意清單回覆」,user 逐字:「確保符合我們一致的設計語言且不違背世界級的設計且都有\n * 確保整個ds 是SSOT,避免漂移就照你建議做」—— 同意的清單含「按鍵規則合併」與批次細節 X1–X35,其中\n * X4(按鈕上 Home / End)、X6(列上選單鈕按 ↓)、X7(樹在按鈕上 Shift+Tab)三處「統一成側欄做法」。\n * 2026-09-26 之前這張表有四份平行實作(側欄 / 檔案清單 / 樹 `tree-keyboard-route.ts` / Command),三處互相不一致:\n *   X4 側欄與檔案清單的按鈕上 Home / End 換到頭尾項,樹不處理;\n *   X6 側欄的選單鈕按 ↓ 換下一項,樹讓給按鈕開選單;\n *   X7 側欄在按鈕上 Shift+Tab 一下離開,樹要兩下(先落回本列)—— 違反 B9「Tab 一下離開」。\n *\n * ── 本檔兩層 ─────────────────────────────────────────────────────────────────\n *   (一) 判定(純函式,不碰 DOM):`resolveRovingKey` / `pickRovingTarget` / `pickRovingTabStop`\n *        —— 判定表 `scripts/test-roving-list-keyboard.mjs`(含舊路線對照組)逐格驗。\n *   (二) 宿主共用的 DOM 小工具:列裡可走到的東西、把它們收出 Tab 路、真焦點宿主的執行器 `applyRovingAction`。\n *        Command 是虛擬游標(cmdk 自己搬反白),執行方式不同,在 command.tsx 自己對應 —— 判定仍只讀本檔。\n */\n\n// ════════════════════════════════════════════════════════════════════════════\n// (一) 判定\n// ════════════════════════════════════════════════════════════════════════════\n\n/** 按鍵發生時,焦點在「這一項」本身,還是這一項裡的某一個東西(小按鈕 / 連結 / 名片頭像…) */\nexport type RovingFocus = 'item' | 'control'\n\n/** 樹才有的三個狀態;平面清單不傳 = 沒有「先展開」「回上一層」這兩步 */\nexport interface RovingTreeState {\n  hasChildren: boolean\n  expanded: boolean\n  hasParent: boolean\n}\n\nexport interface RovingKeyInput {\n  /** KeyboardEvent.key */\n  key: string\n  focus: RovingFocus\n  /** 這一項可以用 → 走到的東西數(宿主以 `listRovingControls` 數出來) */\n  controlCount: number\n  /** focus === 'control' 時焦點在第幾個(0 起算);focus === 'item' 時不讀 */\n  controlIndex: number\n  /** 焦點所在的東西是文字輸入(輸入框 / 多行框 / 下拉 / 可編輯區):方向鍵、Home / End、Enter / 空白鍵都屬於它自己 */\n  controlIsTextEntry?: boolean\n  /** 「這一項」本身是文字輸入(只有 Command 的搜尋框):← / Home / End / 打字屬於插入點 */\n  itemIsTextEntry?: boolean\n  /** itemIsTextEntry 時:插入點已在字尾(且沒有選取範圍)。不在字尾時 → 要留給插入點移動 */\n  caretAtEnd?: boolean\n  /** 樹的狀態;平面清單不傳 */\n  tree?: RovingTreeState\n  /** 可以用 Cmd / Ctrl + Shift + 方向鍵重排(只有 draggable 的樹) */\n  reorderable?: boolean\n  /**\n   * 這一串有「打字跳位」(只有樹:keyboard-model-canonical.md 五條判準第 2 條「需要 tree 那一整套鍵盤模型(打字前導、…)」)。\n   * 焦點在項目上打一個可見字元 → 回 `typeahead`,由宿主找下一個名字以該字開頭的項目;平面清單(側欄 / 檔案清單)不傳 = 不處理。\n   * 出處:W3C APG Tree View 逐字 \"Type a character: focus moves to the next node with a name that starts with the typed character.\"\n   * (<https://www.w3.org/WAI/ARIA/apg/patterns/treeview/>)。\n   */\n  typeahead?: boolean\n  /** 事件已被更外層的捕獲處理程式 preventDefault */\n  defaultPrevented: boolean\n  metaKey: boolean\n  ctrlKey: boolean\n  altKey: boolean\n  shiftKey: boolean\n}\n\nexport type RovingReorderKey = 'ArrowUp' | 'ArrowDown' | 'ArrowLeft' | 'ArrowRight'\nexport type RovingMove = 'item-prev' | 'item-next' | 'item-first' | 'item-last'\n\nexport type RovingKeyAction =\n  /** 不處理 —— 交給瀏覽器、插入點或那個東西自己 */\n  | { type: 'none' }\n  /** 吃掉按鍵(preventDefault)但不動焦點 —— 例:已在最後一顆按鈕上再按 → */\n  | { type: 'consume' }\n  /** 換到上 / 下 / 第一 / 最後一項(焦點落在項目上;不繞回) */\n  | { type: RovingMove }\n  | { type: 'expand' }\n  | { type: 'collapse' }\n  | { type: 'parent' }\n  /** 把焦點放到這一項第 index 個東西 */\n  | { type: 'control'; index: number }\n  /** 焦點回到這一項本身 */\n  | { type: 'item' }\n  /** Tab / Shift+Tab:焦點先回到這一項(整串唯一的 Tab 停靠點),**不擋預設** —— 瀏覽器接著往下 / 往上走一站 = 一下離開這一串 */\n  | { type: 'leave' }\n  /** Enter / 空白鍵在項目上:這一項自己的預設動作(樹 = 選取;原生按鈕 = 瀏覽器自己點) */\n  | { type: 'activate-item' }\n  /** Enter / 空白鍵在項目裡的按鈕 / 連結上:那個東西自己的動作,**不是**「選這一項」 */\n  | { type: 'activate-control' }\n  /** 鍵盤重排(樹;修飾鍵層,與導覽鍵正交) */\n  | { type: 'reorder'; key: RovingReorderKey }\n  /** 打字跳位(只有 `typeahead: true` 的宿主):焦點在項目上打了一個可見字元,由宿主找下一個名字以它開頭的項目 */\n  | { type: 'typeahead'; char: string }\n\nconst REORDER_KEYS: readonly string[] = ['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight']\nconst isReorderKey = (key: string): key is RovingReorderKey => REORDER_KEYS.includes(key)\n\n/**\n * 按鍵表(規格 SSOT = keyboard-model-canonical.md「列上有小按鈕的一串」;每一格的來歷寫在該格旁):\n *\n * | 鍵 | 焦點在項目上 | 焦點在這一項的東西上 |\n * |---|---|---|\n * | ↑ ↓ | 上 / 下一項 | 回到上 / 下一項(X3,依 Adobe 方向鍵模式;選單鈕也一樣 —— X6 統一成側欄做法) |\n * | Home End | 第一 / 最後一項 | 同左(X4 統一成側欄做法) |\n * | → | 樹裡收著的資料夾先展開;否則進第一個東西;沒有就不動 | 下一個;最後一個停住 |\n * | ← | 樹:展開的先收合、否則回上一層;平面清單:不動 | 上一個;第一個 → 回項目 |\n * | Tab / Shift+Tab | 一下離開這一串 | 同左(X7:先回項目、再由瀏覽器往外走) |\n * | Enter / 空白鍵 | 這一項自己的預設動作 | 那個東西自己的動作 |\n * | 可見字元(只有 `typeahead` 宿主 = 樹)| 打字跳位:下一個名字以它開頭的項目(W3C APG Tree View) | 不處理(按鈕上打字沒有意義) |\n */\nexport function resolveRovingKey(input: RovingKeyInput): RovingKeyAction {\n  const { key } = input\n  if (input.defaultPrevented) return { type: 'none' }\n\n  // 鍵盤重排:修飾鍵層,只從項目上發動(tree-view.spec.md「鍵盤重排」,行為不變)\n  if (input.focus === 'item' && input.reorderable && (input.metaKey || input.ctrlKey) && input.shiftKey && isReorderKey(key)) {\n    return { type: 'reorder', key }\n  }\n  // 帶 Cmd / Ctrl / Alt 的組合留給瀏覽器、輔助科技與按鈕自己(例:Alt+↓)。Shift 不在內:Shift+Tab 是導覽鍵。\n  if (input.metaKey || input.ctrlKey || input.altKey) return { type: 'none' }\n\n  // Tab / Shift+Tab:不論焦點在項目或項目裡的東西上,都是一下離開這一串(B9;X7)\n  if (key === 'Tab') return { type: 'leave' }\n\n  // ── 焦點在這一項裡的東西上 ──\n  if (input.focus === 'control') {\n    // 文字輸入:方向鍵移插入點、Enter / 空白鍵是打字,全部屬於它(原樹的 isButtonLike 例外,現全宿主一致)\n    if (input.controlIsTextEntry) return { type: 'none' }\n    switch (key) {\n      case 'ArrowRight':\n        // 已是最後一個 → 不動(W3C 樹狀表格:最右一格按 → 焦點不移動)\n        return input.controlIndex < input.controlCount - 1\n          ? { type: 'control', index: input.controlIndex + 1 }\n          : { type: 'consume' }\n      case 'ArrowLeft':\n        // 已是第一個 → 回到這一項(B9「← 回項目」)\n        return input.controlIndex > 0 ? { type: 'control', index: input.controlIndex - 1 } : { type: 'item' }\n      case 'ArrowDown':\n        // X6:選單鈕(aria-haspopup)也一樣換下一項 —— 開選單用 Enter / 空白鍵(同側欄帳號列,sidebar.spec.md)\n        return { type: 'item-next' }\n      case 'ArrowUp':\n        return { type: 'item-prev' }\n      case 'Home':\n        // X4:同側欄 / 檔案清單 —— 換到第一 / 最後一項\n        return { type: 'item-first' }\n      case 'End':\n        return { type: 'item-last' }\n      case 'Enter':\n      case ' ':\n        return { type: 'activate-control' }\n      default:\n        return { type: 'none' }\n    }\n  }\n\n  // ── 焦點在項目本身(Command:焦點在 home、反白在這一列)──\n  if (input.itemIsTextEntry) {\n    // 搜尋框:插入點已在字尾、沒有按 Shift(Shift+→ 是選取文字)時,→ 才進反白列的第一個東西(AI 推導,command.spec.md「A11y」)\n    if (key === 'ArrowRight') {\n      return !input.shiftKey && input.caretAtEnd !== false && input.controlCount > 0\n        ? { type: 'control', index: 0 }\n        : { type: 'none' }\n    }\n    if (key === 'ArrowDown') return { type: 'item-next' }\n    if (key === 'ArrowUp') return { type: 'item-prev' }\n    // ← / Home / End / Enter / 空白鍵 / 打字:屬於搜尋框與清單函式庫\n    return { type: 'none' }\n  }\n  switch (key) {\n    case 'ArrowDown':\n      return { type: 'item-next' }\n    case 'ArrowUp':\n      return { type: 'item-prev' }\n    case 'Home':\n      return { type: 'item-first' }\n    case 'End':\n      return { type: 'item-last' }\n    case 'ArrowRight': {\n      // 樹裡收著的資料夾 → 先展開(B9);已展開的資料夾或葉節點、平面清單 → 進第一個東西;沒有就不動\n      const tree = input.tree\n      if (tree && tree.hasChildren && !tree.expanded) return { type: 'expand' }\n      return input.controlCount > 0 ? { type: 'control', index: 0 } : { type: 'consume' }\n    }\n    case 'ArrowLeft': {\n      // 樹:展開的資料夾 → 收合;否則 → 回上一層;最外層不動。平面清單:不動(B9「← 在列上維持樹的語意」)\n      const tree = input.tree\n      if (tree && tree.hasChildren && tree.expanded) return { type: 'collapse' }\n      return tree && tree.hasParent ? { type: 'parent' } : { type: 'consume' }\n    }\n    case 'Enter':\n    case ' ':\n      return { type: 'activate-item' }\n    default:\n      // 打字跳位(樹):單一可見字元(空白鍵已在上面 = 選取;Shift+字母 也是一個可見字元,大小寫由宿主比對時折疊)\n      if (input.typeahead && key.length === 1 && key !== ' ') return { type: 'typeahead', char: key }\n      return { type: 'none' }\n  }\n}\n\n/**\n * 上 / 下 / 第一 / 最後一項落在哪 —— **不繞回**(同 W3C grid / tree;X2)。\n * `items` 依畫面順序、含走不到的項目(停用、看不見);`isNavigable` 決定哪些能當落點。\n * 目前這一項本身走不到(例:樹裡用 ← 回到停用的上一層)時,仍從它的位置往前 / 往後找。\n */\nexport function pickRovingTarget<T>(\n  move: RovingMove,\n  items: readonly T[],\n  current: T | null,\n  isNavigable: (item: T) => boolean = () => true,\n): T | null {\n  if (move === 'item-first') return items.find(isNavigable) ?? null\n  if (move === 'item-last') {\n    for (let i = items.length - 1; i >= 0; i--) if (isNavigable(items[i])) return items[i]\n    return null\n  }\n  const start = current == null ? -1 : items.indexOf(current)\n  if (start < 0) return null\n  const dir = move === 'item-next' ? 1 : -1\n  for (let i = start + dir; i >= 0 && i < items.length; i += dir) {\n    if (isNavigable(items[i])) return items[i]\n  }\n  return null\n}\n\nexport interface RovingTabStopOptions<T> {\n  /** 上次焦點停過的那一項 */\n  remembered?: T | null\n  /** 「目前這一頁 / 選中」那一項(側欄 aria-current=\"page\";樹 aria-selected) */\n  isCurrent?: (item: T) => boolean\n  /** 能不能當「目前」或「第一項」的落點(停用、看不見的不算) */\n  isNavigable?: (item: T) => boolean\n  /** 上次停過的那一項還能不能拿焦點(預設同 isNavigable;樹的停用列仍可經 ← 拿到焦點,傳 () => true) */\n  canHoldFocus?: (item: T) => boolean\n}\n\n/**\n * 整串唯一的 Tab 停靠點(X1):上次停過的那一項 → 目前這一頁 / 選中那一項 → 第一個可用項。\n * 出處:W3C「the element that had focus the last time the composite contained focus」+ 導覽樹範例\n * 「focus always lands on the item representing the current page」(keyboard-model-canonical.md 同節引文)。\n */\nexport function pickRovingTabStop<T>(items: readonly T[], options: RovingTabStopOptions<T> = {}): T | null {\n  const isNavigable = options.isNavigable ?? (() => true)\n  const canHoldFocus = options.canHoldFocus ?? isNavigable\n  const { remembered, isCurrent } = options\n  if (remembered != null && items.includes(remembered) && canHoldFocus(remembered)) return remembered\n  const current = isCurrent ? items.find((item) => isNavigable(item) && isCurrent(item)) : undefined\n  return current ?? items.find(isNavigable) ?? null\n}\n\n// ════════════════════════════════════════════════════════════════════════════\n// (二) 宿主共用的 DOM 小工具\n// ════════════════════════════════════════════════════════════════════════════\n\n/**\n * 項目裡「可以走到的東西」的候選(再經 `isRovingControlReachable` 過濾)。\n * 2026-09-26 之前四份各寫一份、各差一點(樹多認 contenteditable、側欄只認按鈕類),合成這一份;\n * 側欄另有自己的範圍(只認動作鈕的兩個出口),以參數傳入。\n */\nexport const ROVING_CONTROL_SELECTOR =\n  'a[href], button, input, select, textarea, [contenteditable]:not([contenteditable=\"false\"]), [tabindex]'\n\n/** 把候選 selector 限定在某個範圍裡(`[cmdk-item] a[href], [cmdk-item] button, …`)。不用 `:is()`:舊版 jsdom 不認得。 */\nexport function scopeRovingSelector(scope: string, selector: string = ROVING_CONTROL_SELECTOR): string {\n  return selector.split(',').map((part) => `${scope} ${part.trim()}`).join(', ')\n}\n\n/**\n * 文字輸入(方向鍵、Home / End、打字屬於它自己)。沒有插入點的 input type 不算(同 React Aria `nonTextInputTypes`)。\n * 全 DS 只有這一份:清單鍵盤(本檔)、反白來歷(hooks/use-input-modality.ts)、下拉的空白鍵(SelectMenu/select-menu-keyboard.ts)\n * 都讀它(2026-09-26 之前各寫一份)。\n */\nconst NON_TEXT_INPUT_TYPES = new Set(['checkbox', 'radio', 'range', 'color', 'file', 'image', 'button', 'submit', 'reset', 'hidden'])\nexport function isTextEntryElement(el: Element): boolean {\n  if (el.tagName === 'TEXTAREA' || el.tagName === 'SELECT') return true\n  if (el.tagName === 'INPUT') return !NON_TEXT_INPUT_TYPES.has((el as HTMLInputElement).type)\n  return (el as HTMLElement).isContentEditable === true\n}\n\n/**\n * 此刻走得到:沒有停用、不在 inert / aria-hidden 裡(例:多選列的勾選框是 inert + aria-hidden 的純視覺)、\n * 畫得出來(display:none 不算;opacity 0 的「滑過才出現」按鈕算 —— 鍵盤走到時它會浮出)。\n */\nexport function isRovingControlReachable(el: HTMLElement): boolean {\n  return (\n    !(el as HTMLButtonElement).disabled &&\n    !el.closest('[inert], [aria-hidden=\"true\"]') &&\n    el.getClientRects().length > 0\n  )\n}\n\n/** 某一項裡可以走到的東西,依畫面(文件)順序。 */\nexport function listRovingControls(root: Element, selector: string = ROVING_CONTROL_SELECTOR): HTMLElement[] {\n  return Array.from(root.querySelectorAll<HTMLElement>(selector)).filter(isRovingControlReachable)\n}\n\n/** 只在值不同時才寫:同值 setAttribute 也會產生 mutation record,會讓宿主的 MutationObserver 自我觸發。 */\nexport function setRovingTabIndex(el: HTMLElement, value: 0 | -1): void {\n  if (el.getAttribute('tabindex') !== String(value)) el.setAttribute('tabindex', String(value))\n}\n\n/**\n * 項目裡的東西一律不在 Tab 路上(-1,→ 才進得去;別項與本項的都一樣)。\n * 用 DOM 設而不是逐一傳 prop:consumer 的插槽(inlineActionsSlot / description / 名片頭像)是任意 ReactNode,拿不到它們的 props。\n */\nexport function removeRovingControlsFromTabOrder(elements: Iterable<HTMLElement>): void {\n  for (const el of elements) setRovingTabIndex(el, -1)\n}\n\n/** 真焦點宿主(側欄 / 檔案清單 / 樹)執行判定結果時要的東西 */\nexport interface RovingDomHost {\n  event: { preventDefault(): void }\n  /** 目前這一項(整串唯一的 Tab 停靠點就在這種元素上) */\n  item: HTMLElement\n  /** 這一項可以走到的東西(已過濾,`listRovingControls`) */\n  controls: readonly HTMLElement[]\n  /** 整串的項目,依畫面順序(含走不到的;由 isNavigable 篩) */\n  items: readonly HTMLElement[]\n  isNavigable?: (item: HTMLElement) => boolean\n  /** 樹傳 { preventScroll: true }(捲動由列自己的 scrollIntoView 以 block:nearest 處理) */\n  focusOptions?: FocusOptions\n  /** 樹才有:展開 / 收合 / 回上一層 */\n  onExpand?: () => void\n  onCollapse?: () => void\n  onParent?: () => void\n  /** 項目本身的預設動作要由宿主執行時才傳(樹 = 選取);不傳 = 項目是原生按鈕,交給瀏覽器 */\n  onActivateItem?: () => void\n  /** 打字跳位(只有 `typeahead: true` 的宿主):宿主自己累積字串、找項目、搬焦點 */\n  onTypeahead?: (char: string) => void\n}\n\n/**\n * 真焦點宿主的執行器:判定之外只剩「焦點怎麼搬、要不要擋預設」,三個宿主完全相同,所以也只寫一份。\n * `reorder` 不在這裡(樹自己處理:要看是否正在用滑鼠拖曳)。\n */\nexport function applyRovingAction(action: RovingKeyAction, host: RovingDomHost): void {\n  const { event, item, controls, focusOptions } = host\n  switch (action.type) {\n    case 'none':\n    case 'reorder':\n    case 'activate-control':\n      // 按鈕 / 連結的 Enter、空白鍵是瀏覽器原生行為;這裡不擋也不代點\n      return\n    case 'leave':\n      // 焦點在項目裡的東西上時先放回這一項(整串唯一那顆 0),**不擋預設**:瀏覽器接著從這一項往下 / 往上走 = 一下離開。\n      // 往前若不先放回,Shift+Tab 會先落回本項(X7 修的就是這個);往後在焦點鎖(手機抽屜 = Radix FocusScope)裡,\n      // 鎖判斷「是不是最後一顆」看的是 tabindex≥0 的元素,-1 的按鈕永遠不是它 → 不先放回就繞不回開頭\n      //(@radix-ui/react-focus-scope@1.1.7 dist/index.mjs:106-121)。焦點已在這一項上時 focus() 不做任何事。\n      item.focus(focusOptions)\n      return\n    case 'activate-item':\n      if (!host.onActivateItem) return\n      event.preventDefault()\n      host.onActivateItem()\n      return\n    case 'typeahead':\n      // 判定只在 typeahead 宿主才會回這格;擋預設是為了不讓 Firefox「輸入時搜尋」之類的瀏覽器功能吃掉字元\n      if (!host.onTypeahead) return\n      event.preventDefault()\n      host.onTypeahead(action.char)\n      return\n    default:\n      break\n  }\n  event.preventDefault()\n  switch (action.type) {\n    case 'consume':\n      return\n    case 'item-prev':\n    case 'item-next':\n    case 'item-first':\n    case 'item-last':\n      pickRovingTarget(action.type, host.items, item, host.isNavigable)?.focus(focusOptions)\n      return\n    case 'control':\n      controls[action.index]?.focus(focusOptions)\n      return\n    case 'item':\n      item.focus(focusOptions)\n      return\n    case 'expand':\n      host.onExpand?.()\n      return\n    case 'collapse':\n      host.onCollapse?.()\n      return\n    case 'parent':\n      host.onParent?.()\n      return\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/lib/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/lib/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,MAAM,CAAA;AAkF5C;;;;;;;;GAQG;AACH,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,UAEzC;AAUD,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAS/E"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/lib/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAQ,KAAK,UAAU,EAAE,MAAM,MAAM,CAAA;AAuF5C;;;;;;;;GAQG;AACH,wBAAgB,EAAE,CAAC,GAAG,MAAM,EAAE,UAAU,EAAE,UAEzC;AAUD,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,SAAS,CAS/E"}

package/dist/lib/utils.js

@@ -68,7 +68,12 @@ const twMerge = extendTailwindMerge({
       ],
       // Custom opacity utility(對應 tokens/opacity/opacity.css `@utility opacity-disabled`)。
       // 不註冊 group → tailwind-merge 用 default opacity-N heuristic,可能誤判 class 衝突。
-      "opacity": ["opacity-disabled"]
+      "opacity": ["opacity-disabled"],
+      // 「底」的滑過 / 按住疊層(對應 tokens/color/semantic.css `@utility bg-interaction-hover / -active`;
+      // color.spec.md「Hover 換色配對總則」,待辦總帳 B8)。它們寫的是 background-image,不是底色 ——
+      // 不註冊的話 tailwind-merge 把 `bg-*` 一律猜成 bg-color,`cn('bg-surface', 'bg-interaction-hover')`
+      // 會把 bg-surface 刪掉,底色整個消失(2026-09-25 以 tailwind-merge 3.5 實測)。登記在 bg-image 才對得上它真正寫的屬性。
+      "bg-image": ["bg-interaction-hover", "bg-interaction-active", "bg-interaction-selected", "bg-interaction-selected-hover", "bg-interaction-selected-active"]
     }
   }
 });