@seanyeh77/ui 0.0.0-stage → 0.3.0

package/docs/IconButton.md

@@ -0,0 +1,12 @@
+# IconButton
+
+只有圖示的按鈕，一定要有 `label`。
+
+- `label` 會成為 `aria-label` 與提示（Tooltip），寫成動作：「收合側邊欄」、「關閉」。不需要提示時設 `tooltip={false}`。
+- 外框 `line-strong`，尺寸與 Button 同高（40 px）。
+- 側邊欄的收合按鈕是例外：放在側邊欄左下角，無外框，收合後圖示左右翻轉。
+- `icon`（必填）：Phosphor 圖示名稱，例如 `'trash'`；或自訂圖示的 24 px path。
+
+```tsx
+<IconButton icon="pencil-simple" label="編輯 api-gateway" onClick={edit} />
+```

package/docs/InlineCode.md

@@ -0,0 +1,35 @@
+# InlineCode
+
+句子裡的程式碼、檔案路徑和 ID。
+
+- 外觀：淺灰底（`surface-sub`）、Geist Mono、字級是周圍文字的 0.875 倍，圓角 4 px，左右 5 px 內距。
+- 指向某個地方的（例如檔案和行號 `child.c:86`）是連結：強調文字色（`accent-text`）加底線，給 `href` 或 `onClick`。
+- 24 個字元以內的不會從中間斷行（例如 `h->post_send` 不會斷成 `h-` 和 `>post_send`）；更長的路徑才會換行。
+- Geist Mono 只用在程式碼本身，周圍的中文句子維持一般字體。
+
+```js
+h(UI.InlineCode, null, 'IBTRACE_SHM');
+h(UI.InlineCode, { href: '/code/child.c#L86' }, 'child.c:86');
+```
+
+## CodeText
+
+把含有反引號的文字（例如來自 Markdown 的筆記）轉成一般文字加 InlineCode，畫面上不會出現反引號。
+
+```js
+h(UI.CodeText, {
+  text: '`ibmon_spawn` 在 `child.c:86` 設定 `IBTRACE_SHM`',
+  refHref: function (ref) {
+    return '/code/' + ref;
+  }, // 或 onRef(ref)
+});
+```
+
+- 看起來像「檔名:行號」或「檔名:起-迄」的片段（`trace.c:321-322`）會變成連結；其他片段是一般的行內程式碼。用 `isRef` 可以改判斷方式。
+- 沒有給 `refHref` 或 `onRef` 時，全部都是一般的行內程式碼。
+
+引用連結：
+
+- `refHref(ref)` 回傳網址就是連結；回傳 `undefined` 表示這個引用沒有目標，顯示成一般的行內程式碼。
+- `onRef(ref, event)`：點擊時呼叫，元件會先 `preventDefault()`，網址和 hash 不會改變；按住 Ctrl、⌘、Shift 或用滑鼠中鍵時仍照 `href` 開新分頁。
+- `isRef(span)`：決定哪些反引號內容算引用，預設是 `檔名.副檔名:行號`。`UI.Suggestion` 和 `UI.Term` 也接受同樣的 `refHref`、`onRef`、`isRef`。

package/docs/KpiCard.md

@@ -0,0 +1,11 @@
+# KpiCard
+
+KPI 卡片，放在 Dashboard 最上方。
+
+- 由上到下：標籤、大數字加單位、迷你折線、變化。
+- 數字 31 px、Geist Mono、等寬數字；單位寫在數字後面（人、ms、%）。
+- 大數字縮寫只出現在 KPI 卡片：1 萬以上寫成「1,284 萬」（`compact={false}` 可以關掉）。金額用 `format="money"`，顯示成「NT$ 1,284 萬」。
+- 數字進場時從 0 數上來（900 ms）。跳動途中用和最終值相同的單位和小數位數，寬度先保留給最終值，所以不會忽寬忽窄。
+- 卡片太窄、最終數字放不下時，字級自動從 31 px 縮小，最小 20 px。
+- 變化：▲／▼ 加百分比，後面接灰色「較上週」（`compareLabel` 可改）。顏色看好壞：`good` 預設為 `delta > 0`，像錯誤率這種上升是壞事的指標要設 `good={false}`；回應時間下降是好事，設 `good`。
+- 百分比的指標，變化用 `deltaUnit="pt"` 顯示「個百分點」。

package/docs/LayerGraph.md

@@ -0,0 +1,32 @@
+# LayerGraph
+
+架構圖：項目（元件、服務、模組）分層排列，箭頭表示關係。給資料就會自己排版和畫線，不用自己畫 SVG。
+
+- 分層：`layer` 0 在最上面，同一層由左到右照資料順序，置中排列。
+- 共用項目（`shared: true`，幾乎每個項目都會用到的，例如 `src/common`）不畫在圖上，改在圖的下方列出，預設寫「N 個項目使用，共 M 次」（`sharedMeta`，`{a}` 是項目數、`{b}` 是次數），標題預設「共用項目」（`sharedLabel`）。
+- 方框：淡灰底，左側一條灰色色條；第一行是名稱（Geist Mono），第二行是大小長條和文字，長條長度和最大的項目相比。大小給 `size`（函式數、檔案數、端點數），文字用 `sizeLabel` 換成專案的單位，預設「{n} 個項目」。
+- 線：直角轉彎、轉角是圓的，每條線接在方框上不同的位置。線的粗細依次數（`count`），全部灰色。推測的關係（`inferred`）是細虛線，箭頭旁寫 `label`。一個方框收到兩條以上有標籤的線時，左半邊箭頭的標籤寫在箭頭左側、右半邊的寫在右側，只有一條時寫在右側；仍會碰到已經放好的標籤或其他箭頭時往上移一行（18 px）。標籤不會超出圖的左右邊界：放不下時改放另一側。選取時的「N 次」（`countLabel`）也一樣。
+- 選取（`selected`、`onSelect`）：點方框選取，再點一次取消。選取時相關的方框和線維持原樣、線變強調色並在箭頭旁寫「N 次」，其他淡到 40%。
+- 層與層之間 56 px。圖比畫面寬時左右捲動，手機也一樣。
+- 圖例預設放在下方：「次數越多線越粗」和「推測的關係」；`inferredText` 是推測的說明（Term），`inferredLabel` 換掉「推測」這個詞。
+- 放在卡片上。直接放在頁面底色上時，外層加 `style: { '--ui-graph-bg': 'var(--bg)' }`。
+
+```tsx
+<LayerGraph
+  nodes={[
+    { id: 'web', name: 'web', layer: 0, size: 91 },
+    { id: 'api', name: 'api', layer: 1, size: 114 },
+    { id: 'common', name: 'common', shared: true },
+  ]}
+  edges={[
+    { from: 'web', to: 'api', count: 18 },
+    { from: 'web', to: 'common', count: 6 },
+  ]}
+  sizeLabel="{n} 個端點"
+  countLabel="{n} 次請求"
+  selected={selected}
+  onSelect={setSelected}
+/>
+```
+
+從舊版升級：`fns` 改名 `size`，原本寫死的「N 個函式」「被 N 個元件呼叫」改用 `sizeLabel`、`sharedMeta` 傳入。

package/docs/LineChart.md

@@ -0,0 +1,10 @@
+# LineChart
+
+折線圖。
+
+- 平滑曲線，線寬 2.5 px，不填色。
+- 多組資料依序用 `chart-1`、`chart-2`、`chart-3`；超過一組時上方顯示圖例。
+- 格線為淡色虛線，底線實線；數字刻度用等寬字。
+- 滑過時出現垂直參考線、各組的點，以及浮起卡片顯示日期和數值（加單位）。
+- 進場時一條接一條畫出，間隔 150 ms。
+- `label` 必填，作為圖表的 `aria-label`。

package/docs/LoadingBar.md

@@ -0,0 +1,7 @@
+# LoadingBar
+
+水滴載入條，用於不知道要多久的載入。
+
+- 高度 8 px，和進度條相同的軌道。
+- 一段強調色流過去：前端先衝、後端跟上，所以中間會拉長，和導覽的水滴動畫一致。
+- 減少動態效果時改成靜止的半透明條。

package/docs/LoginCard.md

@@ -0,0 +1,8 @@
+# LoginCard
+
+登入頁：淺灰底上置中的白色卡片。
+
+- 只有帳號密碼登入。密碼欄右邊有眼睛按鈕可以顯示密碼。
+- 「忘記密碼？」放在密碼標籤右邊（`forgotHref`）。
+- 錯誤寫在各欄位下方：空著送出顯示「請輸入帳號／請輸入密碼」；帳密錯誤時把 `error.password` 設成「帳號或密碼不正確，請再試一次。」。
+- 按 Enter 也會送出。

package/docs/Menu.md

@@ -0,0 +1,20 @@
+# Menu
+
+「⋯」選單：一列或一個項目的更多操作。
+
+- 按鈕是無外框的「⋯」IconButton，打開時灰底。
+- 選單預設在按鈕下方、右緣對齊；往左超出視窗時改成左緣對齊，下方放不下時改到上方。
+- 每個選項：圖示、文字、右邊的鍵盤快捷鍵（等寬字）。
+- 危險選項（`danger: true`）自動移到最後，前面加分隔線，紅字（`danger-text`）。一定要給 `confirm`：按下時先跳確認對話框，確認後才執行 `onSelect`。
+- 打開動畫：從按鈕所在的角落放大，180 ms。
+- 鍵盤：打開後焦點在第一個選項，↑ ↓ 移動，打字跳到開頭相符的選項，Esc 關閉並回到按鈕；點外面也會關閉。
+
+```tsx
+<Menu
+  label="api-gateway 的更多操作"
+  items={[
+    { label: '重新命名', icon: 'pencil-simple', onSelect: rename },
+    { label: '刪除', icon: 'trash', danger: true, confirm: { title: '刪除 api-gateway？' }, onSelect: remove },
+  ]}
+/>
+```

package/docs/MobileTabBar.md

@@ -0,0 +1,8 @@
+# MobileTabBar
+
+手機寬度（小於 600 px）時的底部分頁列。
+
+- 只有圖示，不顯示文字；每個按鈕都有 `aria-label`。
+- 按下已選中的分頁也會呼叫 `onChange`（例如「更多」每次都要打開）；只在頁面真的改變時才做事的話，先比對目前的值。
+- 選中：圖示後方一塊 `accent-soft` 圓角矩形（`radius-md`），圖示變 `accent-text`。
+- 切換動畫：水滴膠囊，和 Tabs 相同的拉伸方式（前端 120 ms、後端 440 ms）。

package/docs/MultiSelect.md

@@ -0,0 +1,9 @@
+# MultiSelect
+
+多選：選中的項目變成框內的標籤。
+
+- 框內顯示前 2 個標籤，其餘寫成「+n」（滑過可看全部）；`maxChips` 可以改數量。
+- 輸入文字篩選選單；選單裡每個選項前面有勾選框。
+- 依情況決定能不能新增：`creatable` 時，輸入清單裡沒有的名字會出現「新增「…」」，也可以按 Enter；不能新增時顯示「找不到符合的選項」。
+- Backspace 移除最後一個標籤，Esc 關閉選單。
+- 選項固定、使用者不該自己加的（例如狀態、權限）不要開 `creatable`；名稱或標籤這類可以自由增加的才開。

package/docs/NotificationBell.md

@@ -0,0 +1,9 @@
+# NotificationBell
+
+頂部列的通知鈴鐺與通知中心。
+
+- 鈴鐺上有紅色數字角標（`danger`），超過 99 顯示 99+；沒有未讀時不顯示。
+- 點鈴鐺從下方彈出 360 px 的面板，點外面或按 Esc 關閉。
+- 通知依時間分組（`group`，例如「今天」、「更早」），由新到舊。
+- 未讀通知左側有強調色圓點；點一則通知交給 `onOpen` 處理（通常是標成已讀並前往）。
+- 「全部標為已讀」在面板標題列右側，有未讀時才出現。

package/docs/Popover.md

@@ -0,0 +1,9 @@
+# Popover
+
+彈出框：按鈕旁邊浮出的小面板，放篩選條件、說明或少量設定。
+
+- 滑過按鈕就打開，滑鼠移到面板上會保持打開；移開 150 ms 後關閉。點擊或用鍵盤 focus 按鈕也能打開，觸控裝置靠點擊。
+- 點外面或按 Esc 關閉，右上角不放 ×。
+- 有指向按鈕的箭頭；預設在按鈕下方、右緣對齊，放不下時換邊。
+- 白底（`surface`）、`radius-lg`、`shadow-overlay`，出現時淡入 150 ms。
+- 內容要用完整表單或很多欄位時，改用 Drawer。

package/docs/ProgressBar.md

@@ -0,0 +1,7 @@
+# ProgressBar
+
+進度條，用於知道進度的工作（例如上傳）。
+
+- 高度 8 px，軌道 `surface-sub`，填色 `accent`。
+- 百分比寫在條的下方，等寬字。
+- 到 100% 時條變 `success`，文字變「完成 ✓」。

package/docs/ProgressRing.md

@@ -0,0 +1,7 @@
+# ProgressRing
+
+達成率圓環，放在卡片裡顯示「完成多少」。
+
+- 預設 72 px，線寬 8 px，軌道 `surface-sub`，填色 `accent`，端點圓頭。
+- 中間放百分比（等寬字）；旁邊可以寫實際數量，例如「72 / 100 個專案」。
+- 進場時和數字一起從 0 跑到目標值。

package/docs/ProjectSwitcher.md

@@ -0,0 +1,22 @@
+# ProjectSwitcher
+
+頂部列右邊的專案狀態：現在看的是哪個專案、資料是不是即時的，點了可以切換專案或環境。
+
+- 外框 Chip：高度 40 px，和按鈕、輸入框一致，`line-strong` 外框，`radius-md`；內容是狀態圓點、「專案 · 狀態」，右邊下拉箭頭。
+- 圓點：`live` 即時（`success`）、`stale` 已過期（`warning`）、`offline` 離線（`neutral-500`）。狀態文字可以用 `statusLabel` 改寫。
+- 點了打開清單：每個選項是名稱加說明（例如環境），目前的選項是 `accent-soft` 底加勾；最下方可以放 `footer`，例如「所有資料來源設定」連結。點外面或按 Esc 關閉。
+- 沒有 `options` 或 `onChange` 時只是顯示狀態，不能點。
+
+```js
+h(UI.ProjectSwitcher, {
+  project: 'ibtrace',
+  status: 'live',
+  value: env,
+  onChange: setEnv,
+  options: [
+    { id: 'ib-build', label: 'ibtrace', detail: 'build 環境' },
+    { id: 'ib-rt', label: 'ibtrace', detail: 'runtime 環境' },
+  ],
+  footer: h('a', { href: '/settings/sources' }, '所有資料來源設定'),
+});
+```

package/docs/RadioGroup.md

@@ -0,0 +1,7 @@
+# RadioGroup
+
+單選群組。
+
+- 外圈 22 px 圓形，2 px `line-strong` 邊框；選中時外圈變 `accent`，中間出現 10 px 圓點（彈出動畫）。
+- `role="radiogroup"`，每個選項 `role="radio"`。
+- 整列可點，高度 40 px。

package/docs/SearchField.md

@@ -0,0 +1,7 @@
+# SearchField
+
+搜尋欄。
+
+- 外框輸入框，左邊放大鏡圖示。
+- 有內容時右邊出現清除鈕；瀏覽器內建的清除鈕已隱藏，不會出現兩個叉。
+- `label` 預設為「搜尋」，作為 `aria-label`。

package/docs/Select.md

@@ -0,0 +1,7 @@
+# Select
+
+下拉選單。一律不用瀏覽器原生 `<select>`。
+
+- 依內容決定類型：選項超過 8 個時自動加上搜尋框，8 個以內是一般自訂選單；用 `searchable` 可手動指定。
+- 選單向下展開（200 ms），按 Esc 關閉；選中項目用 `accent-soft` 底加勾。
+- 搜尋沒有結果時只顯示一句話：「找不到符合的選項」。

package/docs/SettingsLayout.md

@@ -0,0 +1,8 @@
+# SettingsLayout
+
+設定頁：左側分類，右側內容。
+
+- 分類清單 180 px，選中的分類有左側強調色指示條；手機寬度時改成上方橫向分類。
+- 每個分類的內容用 `SettingsSection` 分成卡片。
+- 自動儲存：使用者改完就存，右下角出現 Toast「已儲存」（`toast`），3 s 後消失。沒有「儲存」按鈕。
+- 刪除帳號這類操作放在最後一個分類的最下方，用 `DangerZone` 紅框隔開，按下後先跳確認對話框。

package/docs/SideNav.md

@@ -0,0 +1,11 @@
+# SideNav
+
+Dashboard 類頁面的左側導覽，可以收合。
+
+- 寬度：展開 240 px（`sidebar-width`），收合 72 px（`sidebar-collapsed`），底色 `surface-chrome`，右邊一條 `line`。
+- 由上到下：品牌（文字名稱加 `accent` 色方塊）、選單項目、收合按鈕。品牌和收合按鈕固定大小；項目太多時，中間的選單自己捲動。
+- 項目高度 40 px，滑過灰底（`surface-sub`），組與組之間用分隔線。
+- 選中：左側 3 px 強調色指示條，用水滴方式移動到新項目；文字變粗、圖示變 `accent-text`。
+- 子選單：點父項目展開，子項目縮排；收起時選中的子項目會標在父項目上。收合時，有子項目的父項目點了直接進第一個子頁面，頁面內再切換其他子頁面（例如用 Tabs）。
+- 收合按鈕在左下角，只有圖示、沒有文字。收合後只剩圖示，滑過顯示名稱提示。
+- `label` 是導覽的 `aria-label`，預設「主要導覽」。

package/docs/Skeleton.md

@@ -0,0 +1,5 @@
+# Skeleton
+
+資料載入中時顯示的骨架，用 `surface-sub` 底色。
+
+- 開始載入就立即顯示（延遲 0 ms）。

package/docs/Suggestion.md

@@ -0,0 +1,15 @@
+# Suggestion
+
+修正建議：發現寫錯的地方時，直接給出建議的寫法，可以一鍵複製。
+
+- 上下兩行：舊的在上，前面「−」，淡紅底（`danger-soft`）；新的在下，前面「+」，淡綠底（`success-soft`）。螢幕閱讀器會念「原本：」和「改成：」。
+- 文字用一般字體，反引號包起來的部分是行內程式碼；檔案和行號可以用 `refHref` 或 `onRef` 變成連結（同 CodeText，也可以給 `isRef`）。
+- 右上角是複製圖示（提示「複製修正」）。按了把 `copyText`（預設是 `after` 原文，保留反引號，方便貼回 Markdown）複製到剪貼簿，圖示變成綠色的勾、提示寫「已複製」，2 秒後恢復。
+- 只有新的寫法、沒有舊的時，不給 `before`。
+
+```js
+h(UI.Suggestion, {
+  before: '`flush_ring` 在 `ring.c:96` 把資料寫回檔案。',
+  after: '`flush_ring` 在 `ring.c:104` 把資料寫回檔案。',
+});
+```

package/docs/Switch.md

@@ -0,0 +1,8 @@
+# Switch
+
+開關，用於立即生效的設定。
+
+- Material 3 樣式：52 × 32 px，2 px 邊框。
+- 圓鈕：關 16 px 灰色帶叉、開 24 px 白色帶勾、按住時 28 px。
+- 滑動用水滴動畫（與導覽相同的 `MOTION`）。
+- `label` 必填，作為 `aria-label`；畫面上的文字放在開關旁邊。

package/docs/Tabs.md

@@ -0,0 +1,10 @@
+# Tabs
+
+同一頁裡切換不同檢視：分段控制。
+
+- 每一項可以加 `count`，顯示在名稱右邊（Geist Mono、次要文字色）。結果清單的摘要用這種寫法，例如「全部 6 · 錯誤 2 · 要確認 1」。
+- 手機上當作摘要使用時，各項平均分配寬度，不換行。
+
+- `surface-sub` 灰底軌道，選中的是浮起的 `surface` 白塊，圓角 `radius-md` 10 px。
+- 切換動畫：水滴。靠近目標的一端先移動（120 ms），另一端慢 2.2 倍才跟上（440 ms），移動中略為變細，到位後恢復；全程是同一塊，邊緣清晰。
+- 內容切換：新內容的卡片依序浮起（外層加 `ui-rise-in`，並在切換時換 `key` 重新掛載）。

package/docs/Tag.md

@@ -0,0 +1,11 @@
+# Tag
+
+說明一個項目「是什麼」的分類標籤，例如「編譯器」、「外部」、「規則：經由指標」。
+
+- 只有小字：12 px、粗體、`ink-muted`，沒有框也沒有底色。
+- 一律灰色，不用顏色區分類別；要表示進度或結果（完成、失敗、要確認）用 Badge。
+- 放在名稱後面，同一列可以有多個。
+
+```js
+h(UI.Tag, null, '編譯器');
+```

package/docs/Term.md

@@ -0,0 +1,30 @@
+# Term
+
+名詞或關係標籤的說明：讀者可能看不懂的詞（例如「translation unit」、「LD_PRELOAD 攔截」）和關係標籤（例如「推測（規則）」）。
+
+- 記號：詞的後面加一個小問號，滑過或打開時問號變強調色。文字本身維持周圍的字體和顏色，所以可以放在句子裡，也可以放在 `UI.Tag` 裡。
+- 點一次打開，再點一次關閉；右上角也有 ×，按 Esc 或點外面也會關閉。
+- 觸控範圍：放在句子裡時不擴大（WCAG 2.2 行內例外）；單獨出現時（Tag 裡、圖例）自動擴大到 48 px，不用另外處理。
+- 寬度 600 px 以上：詞的下方浮起小卡，寬 340 px。小於 600 px：從畫面下方打開，字比較大，按鈕至少 48 px。
+- 說明裡的檔案和行號可以用 `refHref`、`onRef`、`isRef` 變成連結（同 CodeText）。
+- 內容：標題（預設是詞本身）、一兩句說明（`text`，反引號變行內程式碼）；關係的說明可以加證據那一行程式碼（`code`）和一個動作（`action`，例如「看這一行」）。
+- 同一頁同一個詞出現很多次時，每次都可以加；說明要短，長篇的解釋改連到文件。
+
+```js
+h('p', null, '起點經過 2 個 ', h(UI.Term, { text: '一個 `.c` 檔加上它 include 的標頭檔，編譯器一次處理的單位。' }, 'translation unit'), '。');
+
+h(
+  UI.Tag,
+  null,
+  h(
+    UI.Term,
+    {
+      title: '推測（規則）',
+      text: '經由 `h->post_send` 呼叫，由規則推得，編譯器無法確認。',
+      code: ' 74 │ ret = h->post_send(qp, wr, bad_wr);',
+      action: { label: '看這一行', onClick: () => openLine('ops.c', 74) },
+    },
+    '推測（規則）',
+  ),
+);
+```

package/docs/TextArea.md

@@ -0,0 +1,7 @@
+# TextArea
+
+多行輸入。
+
+- 隨內容自動長高，從 3 行開始，最多 8 行，之後在框內捲動。
+- 右下角顯示字數 `n / 200`（等寬字）；`maxLength` 可改上限。
+- 樣式與 TextField 相同；`required` 加紅色星號。

package/docs/TextField.md

@@ -0,0 +1,10 @@
+# TextField
+
+單行文字輸入，標籤在上、說明或錯誤在下。
+
+- 外框樣式：`surface-input` 底色、`line-strong` 邊框、`radius-md`。
+- focus：邊框變 `accent` 並加 3 px `focus-ring` 光暈。
+- 錯誤：`error` 給一句原因加修正方式；邊框變 `danger`，欄位內右側出現警示圖示，訊息用 `danger-text`。輸入框帶 `aria-invalid` 與 `aria-describedby`。
+- 停用：`surface-sub` 灰底、`ink-muted` 灰字、無邊框。
+- 標籤一定要有，不要只靠 placeholder。
+- 必填：`required` 會在標籤後加紅色星號（`danger`）。

package/docs/ThemePicker.md

@@ -0,0 +1,9 @@
+# ThemePicker
+
+主題選擇：自動、淺色、深色三張預覽卡片，放在設定頁的「外觀」。
+
+- 每張卡片有一張小縮圖：自動是左上淺色、右下深色。
+- 選中的卡片用 2 px 強調色外框，文字變粗。
+- 不傳 `onChange` 時會直接呼叫 `UI.setTheme()`：在根元素設 `data-theme`，選擇存在 localStorage。
+- 自動：跟著系統的 `prefers-color-scheme`，系統改變時也會跟著換。
+- 切換時所有顏色用 300 ms 漸變；減少動態效果時直接切換。頁面載入時呼叫一次 `UI.initTheme()`。

package/docs/Toast.md

@@ -0,0 +1,7 @@
+# Toast
+
+操作完成後的短暫提示，出現在畫面右下角。
+
+- 卡片樣式：`surface` 底色、`line` 細框、`shadow-overlay` 陰影。
+- 出現 3 s 後自動消失。
+- 附「復原」（`actionLabel="復原"`）。

package/docs/Tooltip.md

@@ -0,0 +1,9 @@
+# Tooltip
+
+提示：滑過或用鍵盤移到元素上時出現的短文字。
+
+- 深色（`ink` 底、`bg` 字），圓角 `radius-chip`，13 px 粗體。
+- 預設在元素上方，有指向元素的箭頭；上方放不下時改到下方。
+- 延遲 0 ms：滑過或 focus 立刻出現；移開、失焦或按 Esc 消失。
+- 出現動畫：從箭頭那一側放大，220 ms，稍微回彈。減少動態效果時只淡入。
+- IconButton 會自動用 `label` 加上 Tooltip；其他元素用 `<Tooltip label>` 包起來。只放短文字，不放按鈕或連結。

package/docs/TopBar.md

@@ -0,0 +1,9 @@
+# TopBar
+
+Dashboard 類頁面的頂部列，高 64 px（`header-height`）。
+
+- 左側放頁面標題（`title`，20 px、字重 700）。
+- 麵包屑放在內容區、頁面內容的最上方，不放在頂部列。
+- 右側：填色搜尋框（`surface-sub` 灰底、無外框，附 Ctrl K 提示，Mac 上寫 ⌘K），接著放頭像或其他元素（`children`）。
+- 寬度小於 600 px 時，搜尋框換成搜尋圖示（觸控區 48 px）。兩者都呼叫 `onSearch`，通常接到 CommandPalette，也都有 `data-tour="search"`，Tour 可以直接用 `target: 'search'`。
+- 頁首行為依版面規則：往下捲時隱藏，往上捲時出現。

package/docs/Tour.md

@@ -0,0 +1,24 @@
+# Tour
+
+第一次使用的導覽：一次介紹一個地方，整頁變暗，只亮出要介紹的地方。
+
+- 亮出的地方加 3 px 強調色框；說明卡放在它下方（放不下時換到上方），寬 320 px，寫「1 / 3」、標題和一兩句說明（說明裡的反引號會變成行內程式碼）。
+- 按鈕：左邊「略過」，右邊「上一步」和主要按鈕「下一步」，最後一步是「完成」。按 Esc 等於略過。導覽進行時頁面不能操作。
+- 用 `UI.useTour(key)` 記住這個瀏覽器看過了沒有：沒看過會自動打開，看完或略過後不再出現。
+- 頁面上要有「重看導覽」（例如說明選單或頁面底部的連結），呼叫 `tour.start()`。
+- `target` 最好用名稱：在要介紹的元素上加 `data-tour="tree"`，`target` 寫 `'tree'`。TopBar 的搜尋框和手機的搜尋圖示都已經有 `data-tour="search"`，會用看得到的那一個。也可以給 CSS selector、ref 或元素。找不到時說明卡放在畫面中間。
+- 步驟最多 3 到 5 步，只介紹第一次看不出用法的地方。
+
+```js
+const tour = UI.useTour('codemap-flow');
+h(UI.Tour, {
+  open: tour.open, onClose: tour.close,
+  steps: [
+    { target: 'search', title: '搜尋', text: '搜尋函式、檔案、元件與環境變數。快捷鍵 Ctrl K。' },
+    { target: 'tree', title: '流程樹', text: '名稱旁的標籤是關係的來源，點選問號查看依據。' },
+    { target: 'notes', title: '檢查筆記', text: '錯誤的位置附有修正建議，可直接複製。' }
+  ]
+}),
+h('section', { 'data-tour': 'tree' }, …),
+h('button', { className: 'ui-link-btn', onClick: tour.start }, '重看導覽')
+```

package/docs/TreeList.md

@@ -0,0 +1,93 @@
+# TreeList
+
+資料夾裡放檔案、可以一層層展開的清單。
+
+```js
+h(UI.TreeList, {
+  title: '課程教材',
+  items: [
+    { id: 'rec', name: '上課錄影', children: [{ id: 'r4', name: 'SDNFV_20261029_1.mp4', date: '2026-11-05T01:16', size: 144284057, unseen: true }] },
+    { id: 'f1', name: '課程評分方式.docx', date: '2026-09-22', size: 53248 },
+  ],
+  defaultOpen: ['rec'],
+  onDownload: function (files) {
+    /* 一個或多個檔案 */
+  },
+});
+```
+
+## 資料
+
+- 資料夾有 `children`（可以是空陣列），檔案沒有。每個項目都要有唯一的 `id`。
+- 檔案：`name`（副檔名從檔名取，也可以另外給 `ext`）、`date`（Date、時間戳或日期字串）、`size`（位元組）、`unseen`（使用者還沒打開或下載過）。
+- 資料夾的檔案數和最新時間自動從裡面的檔案算出來，沒有資料就不顯示。
+- 子項目很多時（例如呼叫關係）可以延遲載入：項目給 `hasChildren: true`、不給 `children`，再給 `loadChildren(node)`，回傳子項目陣列或 Promise。展開時才載入，載入中顯示一列骨架；失敗時寫「無法載入 X 的子項目：原因。」和「重試」。載入過的不會重複載入。
+- `tags` 可以放文字或元件，例如 `h(UI.Term, …)`。
+
+## 選項
+
+- `sort`：`'newest'`（預設）、`'oldest'`、`'name'`，或 `false` 照資料原本的順序。資料夾一律排在檔案前面。看情況選。
+- `expand`：`'multi'`（預設，點資料夾展開或收合，標題列有「全部展開」）或 `'single'`（一次只開一個，同層的其他資料夾自動收合）。需要一次看到全部時用 `'multi'`，資料夾又多又雜時用 `'single'`。
+- `meta`：名稱下方的次要文字（例如「2 個 caller」），一般字體、數字用 Geist Mono；沒有 `meta` 時顯示 `path`，整行 Geist Mono。
+- `title` 加 `subtitle`：標題和下方一行次要文字（例如「17 個檔案」）。
+- `height`：固定高度（例如 `'100%'` 填滿外層、或 `520`），標題列不動，清單在裡面捲動。放在固定高度的版面（例如側邊面板）時一定要給，不然下面的項目看不到。
+- TreeList 本身就是一張卡片，不要再包進另一張卡片。真的要放進現有的卡片或面板時給 `bare`：沒有底色、陰影和圓角。
+- `defaultOpen`：一開始展開的資料夾 `id`。
+- `open` 加 `onToggle(node, isOpen, openIds)`：由外部控制展開，例如寫進網址。給了 `open` 時，請在 `onToggle` 裡更新它。
+- `selectable`：顯示勾選框（滑過才出現，勾了一個之後全部顯示；觸控裝置一直顯示）。勾資料夾等於全選裡面的檔案。勾選後標題列換成「已選 n 個檔案 共 x MB」、「清除選取」和「下載」。`selected` 加 `onSelectChange` 可以由外部控制（只會有檔案的 `id`）。`bulkActions(files, clear)` 可以再加按鈕。
+- `onDownload(files)`：每個檔案右邊的下載按鈕和批次下載都會呼叫它。
+- `onOpen(file)`：點檔案列或按 Enter；沒給時改成下載。打開或下載後，請把那個檔案的 `unseen` 改成 `false`。
+- `title`、`actions`：標題列的文字和右邊的按鈕。沒有標題時用 `label` 給螢幕閱讀器。
+- `emptyText`：沒有任何項目時的文字，預設「這裡還沒有檔案」。
+
+## 外觀
+
+- 每層縮排 28 px，左側細線（`line`）。資料夾用 Phosphor 的 folder／folder-open，前面有會轉 90° 的箭頭。
+- 檔案圖示：文件形狀，底部色塊寫副檔名。PDF 紅、影片紫、音訊桃紅、簡報橘、文件藍、試算表綠、圖片青、程式碼深灰、壓縮檔和其他灰。
+- 清單寬 640 px 以上：日期和大小在右側排成欄（Geist Mono）。比較窄：放在名稱下方，檔名最多兩行。
+- 新檔案（`unseen`）：日期變 `accent-text` 粗體；資料夾旁寫「2 個新」。
+- 滑過列 `surface-sub`，勾選中的列 `accent-soft`。
+- 展開時子項目往下長出 260 ms；減少動態效果時改成淡入。
+
+## 一般的樹
+
+`kind="plain"` 用在不是檔案的階層，例如呼叫關係、元件結構。
+
+```js
+h(UI.TreeList, {
+  kind: 'plain',
+  label: '呼叫流程',
+  items: [
+    {
+      id: 'root',
+      name: 'trace_post_send',
+      path: 'src/libibtrace/hooks/ops.c:55',
+      children: [
+        { id: 'hook_of', name: 'hook_of', path: 'src/libibtrace/hooks/ops.c:58', tags: ['編譯器'] },
+        { id: 'gettime', name: 'clock_gettime', meta: 'libc.so.6', tags: ['外部'], muted: true },
+      ],
+    },
+  ],
+  defaultOpen: ['root'],
+  selectedId: sel,
+  onSelect: function (n) {
+    setSel(n.id);
+  },
+});
+```
+
+- 每一列：名稱、分類標籤（`tags`，用 `UI.Tag` 顯示），名稱下方是位置：`meta` 直接顯示，或 `path` 用 `UI.format.path()` 保留頭尾、中間省略。
+- 照資料原本的順序；有子項目的不會被排到前面。`sort` 仍然可以指定。
+- 點一列呼叫 `onSelect`，選中的列是 `accent-soft` 底；點左邊的箭頭才展開或收合。Enter 選取，→ ← 展開收合。
+- `muted: true` 的項目名稱用次要文字色（例如外部函式）。`icon` 可以放 Phosphor 圖示名稱。
+- 預設不顯示「全部展開」；需要時加 `toggleAll: true`。沒有勾選和下載。
+
+## 手機上的縮排
+
+清單寬度小於 600 px 時（看清單本身的寬度），每層縮 16 px，最多縮 3 層；更深的不再縮排，名稱前加層數「L5」。檔案清單和一般的樹都適用。
+
+## 鍵盤
+
+一次只有一列能用 Tab 進入。↑ ↓ 移動，Home／End 到頭尾，→ 展開（已展開就到第一個子項目），← 收合或回到上一層，Enter 打開檔案或切換資料夾，空白鍵勾選。
+
+`UI.format.fileSize(bytes)` 可以把位元組寫成「186 KB」、「54.9 MB」。