CSS 是基於 DOM tree 的規則系統 — 不知道 tree 的真實結構，寫的 CSS 規則無法生效。 看 class name 的命名規則（如 __form、__drawer 看起來像 sibling）容易推錯層級；寫 CSS 之前用工具直接讀 live DOM tree、確認哪些是 grid item、哪些是 grid item 內部的子元素。

層級必須從 live DOM 讀

商業邏輯

CSS class name 是「用途標記」、不是「結構描述」。.parent__child 這種 BEM 風格在很多框架裡只是作者方便辨認用途，跟元素之間的 DOM parent-child 關係無對應。

當作者在 wrapper 裡又加一層 wrapper，class name 不一定改 — 同一個 class name 在不同框架版本可能對應不同的 DOM 巢狀。

唯一能確定 DOM 層級的方法是讀 live DOM。

看 DOM 的工具選擇

優先用 playwright — 同一段 query 可以重複跑、結果可以寫進測試。

這次任務的拓樸誤判

觀察

要把 search scope UI 放在「搜尋輸入框與結果之間」。基於 class name 推測 DOM 結構：

1.pagefind-ui
2├── .pagefind-ui__form        ← 搜尋輸入框
3└── .pagefind-ui__drawer      ← 結果（與 filter）

Class name __form 與 __drawer 都用 __ 前綴、並列在 .pagefind-ui 下、看起來是 sibling。

判讀

依此假設寫 CSS Grid：把 .pagefind-ui 設為 grid、用 display: contents 串接、把 form 放 row 2、scope 放 row 3、drawer 放 row 4。

實際渲染後：scope 跑到頁尾。

用 playwright browser_evaluate 讀 live DOM tree：

1const drawer = document.querySelector('.pagefind-ui__drawer');
2let parents = [], el = drawer;
3while (el && el !== document.body) {
4  parents.push(el.tagName + '.' + el.className);
5  el = el.parentElement;
6}

結果：

1DIV.pagefind-ui__drawer
2FORM.pagefind-ui__form        ← drawer 在 form 內！
3DIV.pagefind-ui
4DIV#search

drawer 是 form 的 child、不是 sibling。我們的 grid 規則把 form（含 drawer 全部結果）放在 row 2、scope 放 row 3 — scope 自然跑到所有結果之後。

執行

確認 DOM 後改用「scope absolute 浮在 form 上、drawer 用 margin-top 讓位」的策略 — 不再嘗試把 form 與 drawer 拆到不同 grid row。

內在屬性比較：拓樸推理的可靠性

選擇順序：Live DOM > source > 命名 > 視覺。Class name 與視覺只能形成假設、必須用前兩者驗證。

display: contents 的拓樸限制

當決定用 display: contents 串接讓子元素參與外層 grid，必須注意：contents 只能讓直接子節點上去、不能跨越多層 box。

例：要讓 form 內的 drawer 參與 search-shell 的 grid，需要 form 也設 display: contents。但 form 設 contents 後：

• form 自己的 box 消失
• 依賴 form 為 offset parent 的子元素（如 absolute 定位的 clear button）失去定位基準
• form 的 ::before / ::after 偽元素可能不渲染

display: contents 適用條件：中間層 box 沒有自己的視覺責任（背景、邊框、定位、尺寸） — 否則拆開後視覺破壞。

設計取捨：拓樸理解的方法

四種做法、各自機會成本不同。這個專案選 A（讀 live DOM）當預設、其他做法在特定情境合理。

A：讀 live DOM（playwright / DevTools）（這個專案的預設）

• 機制：用 playwright browser_evaluate 讀 ancestor chain、computed style、bounding rect；或 DevTools Elements 面板手動探索
• 選 A 的理由：反映實際渲染結果、跨 framework 都對、可寫成測試
• 適合：debug、整合外部組件、寫第一版 CSS 之前
• 代價：需要 server 跑著（可用 hugo dev / static server）

B：讀框架 source / template

• 機制：直接看 svelte / react component 的 template
• 跟 A 的取捨：B 看靜態結構、A 看 runtime 結構；B 對自家組件夠用、對動態渲染（runtime wrapper / portal）會漏
• B 比 A 好的情境：自家組件、template 跟 DOM 1:1 對應、不需要 runtime 確認

C：用 class name 命名規則推測

• 機制：看 .parent__child 推測 DOM 巢狀
• 跟 A 的取捨：C 完全不需要工具、A 需要 server；但 C 命名是慣例不是契約、容易錯
• C 才合理的情境：初步假設、必須用 A/B 驗證後才能寫 CSS — 不應作為唯一依據

D：視覺截圖推測

• 機制：看截圖猜 DOM 結構
• 成本特別高的原因：截圖看不到 wrapper、看不到 display: contents 等不可視結構
• D 是反模式：視覺上看起來相同的 DOM 可能完全不同 — 截圖驗收的盲區會在規則寫了不生效時才被發現、debug 成本指數放大

判讀徵兆

核心原則：CSS 行為與預期不符 ≥ 1 次，先回去看 DOM tree、不要繼續調 CSS 規則。先看才不會試錯。

JS 操作 framework 元件前先界定邊界、選對應的安全規則執行。 邊界 = 契約 = 安全範圍。整節點搬遷安全、改節點內部不安全、改節點 attribute 是灰區。每類操作有對應的安全規則 — 不是「能不能動」、是「動了之後 framework 會不會 revert」。

本篇焦點：framework 元件本身需要動時的安全規則。「客製 UI 該放哪」由 #5 客製 UI 留 framework 邊界外 處理 — 預設應該完全不動 framework、需要動時才參考本篇。

為什麼邊界要先界定

商業邏輯

每個元件（自家或 framework 提供）有「對外契約」與「內部實作」。對外契約包括：

JS 操作前不知道這些 = 黑箱操作。動了什麼、會觸發什麼、誰會被影響、不可預測。

邊界宣告的格式

開始 JS 操作之前、寫一段註解或 mental note：

1動什麼：filter-panel 的 parent
2邊界：filter-panel 整個節點 OK，內部子節點屬於 pagefind 管
3State：checkbox 勾選狀態存在 panel 子節點上、由 pagefind 維護
4動作：appendChild 整節點 reparent
5為什麼安全：節點 identity 不變、pagefind 在下次 patch 時看到節點還在

這段宣告把「動什麼」「不能動什麼」「為什麼安全」說清楚 — 不是儀式、是強迫自己想清楚再動。

三類操作的安全度

從最安全到最不安全：

1. 整節點 reparent（安全）

把 framework 管的整個節點搬到別處 — 節點 identity 不變、framework 在下次 patch 時仍認得它。

1// 安全 — 整節點搬位置
2sidebar.appendChild(filterPanel);
3drawer.insertBefore(filterPanel, drawer.firstChild);

2. 改節點內部子節點（不安全）

在 framework 管的節點內 appendChild / removeChild / 改子節點屬性 — framework 會 revert。

1// 不安全 — 在 framework 子樹內加東西
2filterPanel.appendChild(myCustomDiv);
3filterPanel.querySelector('.x').setAttribute('data-y', 'z');

3. 改節點自身的 attribute / inline style（灰區）

改 framework 管的節點本身的 attribute、看 framework 是否認為這屬於 reactive：

1// 灰區 — 看 framework 怎麼處理
2el.style.display = 'none';
3el.classList.add('my-state');
4el.setAttribute('aria-hidden', 'true');

下節展開三類各自的設計細節。

整節點 reparent：為什麼安全、怎麼做才安全

為什麼安全

Framework 的 reconciliation 通常以「節點 identity」為依據 — 同一個節點在哪裡不重要、節點存不存在才重要。

把 .pagefind-ui__filter-panel 從 drawer 移到外部 aside：

reconciliation 不會因為「位置變了」而重建節點 — 重建只發生在「節點消失了 + 新節點出現」的情境。

安全 reparent 的 do / don’t

核心規則：搬節點 = 操作 node 本身；不要操作 node 的 children。

跟 framework reactivity 的對齊

某些 framework 對節點的「內部值」是 reactive 的（例如 <input> 的 value），改了會被 reconcile 回來。對這類屬性：

不確定某屬性是否 reactive：讀框架 source / 文件確認、或加 fail-safe 防意外。

改節點內部：為什麼不安全、有什麼例外

為什麼不安全

在 framework 管的節點內 appendChild / removeChild — framework 不認得這些操作的結果、下次 patch 時：

1. Framework 比對 component tree 的目標狀態
2. 看到 DOM 多了不該有的節點 → 移除
3. 或看到 DOM 少了該有的節點 → 重建

我們手動加的節點屬於前者、被移除。我們手動移除的子節點屬於後者、被重建（且重建的 identity 不同）。

唯一的例外：靜態元件 + 確認 patch 不重設

如果該 framework 子樹「初次 mount 後不再 patch」、改內部可能安全。但這是框架實作細節、隨版本可能變動。

例：當前 pagefind 的 filter 順序在初次 mount 時生成、後續 patch 不重排 — 所以 reorder filter 子節點實際安全。但這是「當前版本碰巧」、不是「框架保證」。

操作規則：不要依賴「碰巧安全」。如果必須改內部、加 MutationObserver 監聽 framework 是否 revert、必要時補打。

改節點 attribute / inline style：灰區的 fail-safe 設計

為什麼是灰區

Framework 通常不主動管理節點的 inline style 與非 reactive attribute — 但「通常」不是「永遠」。某些 framework 會在 patch 時把 inline style 重設、或把 attribute 跟 component state 強制同步。

Fail-safe 工具 1：!important 提升優先級

1el.style.setProperty('display', 'none', 'important');

important 把 inline style 的優先級提升 — 即使 framework 套了同屬性的低優先 style、也蓋不過。

Fail-safe 工具 2：MutationObserver 補打

1function reapply() {
2  el.style.setProperty('display', 'none', 'important');
3}
4reapply();
5new MutationObserver(reapply).observe(parent, {
6  childList: true, subtree: true,
7});

Framework 在重繪後可能把 element 替換成新的 — observer 監聽到變動、立刻補套 style。

詳細設計（observer 範圍 / 觸發頻率 / self-mutation 處理）由 #29 MutationObserver 範圍與觸發頻率 處理。

Fail-safe 工具 3：CSS class toggle 取代 inline style

1// 不用 inline style
2el.classList.toggle('is-hidden');

1/* CSS 內定義行為、layered CSS 不需要 important */
2@layer base {
3  .is-hidden { display: none; }
4}

詳細展開由 #28 class toggle 取代 important 處理。

選擇順序：能用 class toggle 就用（最乾淨）；framework 會清 class 才用 inline + important + observer。

這次任務的邊界辨識實例

四個 JS 操作場景、各有不同邊界：

每個場景操作前的 mental check：「這是哪一類？該用什麼安全規則？」

設計取捨：操作 framework 元件的策略

四種策略、各自機會成本不同。預設追求「最高安全度的方式達成需求」、成本太高再降級。

A：完全不動 framework、客製留邊界外（這個專案的預設）

• 機制：把客製 UI 放在 framework sibling 位置、用 CSS 達成視覺效果
• 選 A 的理由：跟 framework 完全解耦、命運自主
• 適合：需求是「在 framework 旁加東西」（多數情境）
• 代價：CSS 定位可能複雜
• 詳細：#5 客製 UI 留 framework 邊界外

B：整節點 reparent

• 機制：把 framework 管的節點搬位置、不動內部
• 跟 A 的取捨：A 不動 framework、B 搬 framework 元件本身；B 換到的是「能改變 framework 元件位置」、付出的是「節點內部仍由 framework 管、外部行為仍可能變」
• B 比 A 好的情境：framework 元件位置決定權需要奪回（例如 sidebar 切換）

C：改節點 attribute + fail-safe

• 機制：改 inline style / class、加 important + observer 補打
• 跟 A/B 的取捨：A 不碰 framework、C 介入 framework 元件本身的視覺行為；C 比 A 侵入性高、但比直接改內部安全
• C 比 B 好的情境：需要的不是搬位置、是改顯隱 / 顏色 / state

D：改節點內部（最後手段）

• 機制：在 framework 子樹內 appendChild、改子節點屬性
• 成本特別高的原因：跟 framework reconciliation 直接競爭、bug 不可預測、升級可能徹底打破
• D 才合理的情境：當前 framework 確認「該子樹不 reconcile」+ 升級時會重新驗證 — 通常不值得

邊界宣告的實踐

寫成 JSDoc 或 inline 註解

 1/**
 2 * 把 .pagefind-ui__filter-panel 從 drawer 搬到外部 sidebar。
 3 *
 4 * 邊界：
 5 *   - 動：filter-panel 整節點的 parent
 6 *   - 不動：filter-panel 內部子節點（由 pagefind 管）
 7 *   - State：checkbox 勾選由 pagefind 維護、跟著節點走
 8 *
 9 * 為什麼安全：節點 identity 不變、pagefind 在下次 patch
10 * 時看到節點還在、繼續更新內部。
11 */
12function place() {
13  if (mql.matches) sidebar.appendChild(filter);
14  else drawer.insertBefore(filter, drawer.firstChild);
15}

註解是給未來的自己 / 同事看的「契約備忘」 — 看到操作時知道為什麼安全。

跟其他原則的關係

判讀徵兆

核心原則：JS 動 framework 元件前、邊界先界定、選對應的安全規則。預設追求「完全不動 framework」(A)、必須動時用層級遞減的策略（B / C / D）— 每往下一層付的是「跟 framework 競爭」的成本。

JS 的 DOM query 從具體開始、發現不夠用再放寬。 Selector 涵蓋「最少必要範圍」、避免誤命中其他元素、避免未來頁面結構變動讓 query 撈到不該撈的東西。精準度有三個收斂維度：起點（從哪開始找）、範圍（找多深）、過濾（哪些不要）— 三者一起設計才完整。

為什麼精準度是 default

商業邏輯

DOM selector 的範圍越寬、被誤命中的可能性越高。寬泛 selector 像「網撈」 — 當下頁面只有一個目標元素時看不出問題、未來頁面結構變動（加第二個同類元件、加 demo 區塊、加 widget）就壞。

精準度的成本是「寫 selector 時多想一點」、收益是「行為可預測、不會被未來變動打破」。這不是優化、是 sanity 防線。

寬泛 selector 的失敗模式

四種失敗都來自「query 範圍 > 真實需要的範圍」。從具體開始就避免。

三層收斂維度

Selector 精準度不是單一參數、是三個維度的組合。每個維度都該設計、不能只想其中一個。

維度 1：起點（從哪個 root 開始找）

核心定義：query 的起點決定「最大可能範圍」。從 document 起 = 全頁面；從元件根起 = 子樹內。

1// 寬：全頁面搜尋
2document.querySelector('.pagefind-ui__result');
3
4// 收斂：從元件根開始
5var shell = document.querySelector('.search-shell');
6shell.querySelector('.pagefind-ui__result');

從元件根開始等於把 selector 的作用範圍收斂到「我管的子樹」 — 即使未來頁面其他地方出現同名元素、跟我無關。

起點選擇的決策：

多元件 setup pattern：

1function setupSearchShell(shell) {
2  var ui     = shell.querySelector('.pagefind-ui');
3  var input  = shell.querySelector('.pagefind-ui__search-input');
4  var drawer = shell.querySelector('.pagefind-ui__drawer');
5  // ... 其他 setup
6}
7
8document.querySelectorAll('.search-shell').forEach(setupSearchShell);

頁面有 N 個 shell、自動 setup N 次、各自獨立。當前只一個也適用、未來加更多無痛 — 這是「起點當參數」帶來的擴展性。

例外處理：當目標元素不在元件子樹內（例如同層的 sibling），保留 document.querySelector 但加註解說明：

1// slot 是 main 的子節點、跟 shell 同層、不能從 shell 找
2var slot = document.querySelector('.search-filter-slot');

註解讓未來維護者知道這是「明知故為」的例外、不是疏忽。

維度 2：範圍（找多深）

核心定義：起點確定後、要找直接子、特定層、還是任意深度。

querySelector 預設找任意深度 — 大部分情況沒問題、但結構穩定時可以更精準：

1// 預設：任意深度
2shell.querySelector('.pagefind-ui');
3
4// 限縮：只找直接子
5shell.querySelector(':scope > .pagefind-ui');
6
7// 限縮：只找特定層
8shell.querySelector(':scope > div > .pagefind-ui');

:scope 在 querySelector 內表示 query 的起始元素 — 配合 > 就能精準匹配「直接子」。

範圍選擇的決策：

選太寬未來誤命中、選太窄未來結構微調就壞 — 預設選任意深度、結構穩定的關鍵 query 才用 :scope >。

維度 3：過濾（哪些元素不要）

核心定義：起點 + 範圍確定後、可能還是命中過多 — 用 attribute filter 與否定 selector 排除不要的。

1// 寬：所有 result
2shell.querySelectorAll('.pagefind-ui__result');
3
4// 過濾：只取已 rank 過的（排除初始化中的）
5shell.querySelectorAll('.pagefind-ui__result[data-pagefind-rank]');
6
7// 過濾：排除已處理過的
8shell.querySelectorAll('.pagefind-ui__result:not([data-scoped])');

過濾技巧：

「處理後標記」是 idempotency 工具：apply 函式可能被多次呼叫（observer 觸發、event 觸發），標記 + :not() 過濾確保每個元素只處理一次。

三維度的組合範例

完整的精準 selector 設計：

 1var shell = document.querySelector('.search-shell');           // 維度 1：起點
 2if (!shell) return;
 3
 4var results = shell.querySelectorAll(                          // 維度 2：任意深度
 5  '.pagefind-ui__result[data-pagefind-rank]:not([data-scoped])'  // 維度 3：過濾
 6);
 7
 8results.forEach(function (el) {
 9  // ... 處理
10  el.setAttribute('data-scoped', 'true');                      // 處理後標記
11});

每個維度都有意識地選擇 — 不是把所有預設值疊一起。

內在屬性比較：四種 selector 設計

推薦：起點當參數 + 過濾。:scope > 只在「結構保證穩定」的關鍵 query 用。

進階技巧

1. 把元件根存成變數一次

1var shell = document.querySelector('.search-shell');
2if (!shell) return;
3// 之後所有 query 都從 shell 開始

避免每次 query 都重新從 document 找元件根 — 一是效能（小）、二是 query 範圍仍維持在 shell 內。

2. 用 closest 反向找根

1function getShell(el) {
2  return el.closest('.search-shell');
3}
4
5document.addEventListener('click', function (e) {
6  var shell = getShell(e.target);
7  if (!shell) return;
8  // 在這個 shell 內處理
9});

事件委派 + closest 適合「多元件實例 + 動態事件處理」 — 各 shell 不需要各自綁 listener、共用一個 listener 用 closest 區分。

3. 起點不存在時提早 return

1var shell = document.querySelector('.search-shell');
2if (!shell) return;

頁面可能沒有 shell（不是搜尋頁），所有後續 query 都會失敗。提早 return 比後續一連串 null check 乾淨。

4. WeakMap 替代 attribute 標記

當不想污染 DOM attribute 時、用 WeakMap 紀錄已處理的元素：

1var processed = new WeakMap();
2
3shell.querySelectorAll('.pagefind-ui__result').forEach(function (el) {
4  if (processed.has(el)) return;
5  // ... 處理
6  processed.set(el, true);
7});

WeakMap 在元素 GC 時自動清理、不留下 DOM 痕跡。適合短生命週期的 idempotency。

設計取捨：起點選擇

Selector 的「起點」有四種做法、各自機會成本不同。這個專案選 B（元件根存變數）當預設、其他做法在特定情境也合理。每張卡片獨立展開該做法的設計細節。

A：document.querySelector 全文件搜

• 機制：每處 query 都從 document 開始、靠 class name 唯一性命中目標
• 適合：原型階段、demo 程式碼、確定全頁只有一個目標且未來不會變
• 代價：未來頁面結構變動（加同類 widget、加 demo 區塊）就壞、且失敗模式是安靜地操作錯元素、不報錯
• 選 A 的時機：「快速看會不會動」的探索期

B：元件根存變數、之後從變數 query（這個專案的預設）

• 機制：var shell = document.querySelector('.search-shell') 一次、之後所有 query 用 shell.querySelector(...)
• 選 B 的理由：當前頁面只有一個 shell、未來可能加（站內搜尋 widget、相關搜尋）— 用變數隔離成本低、提早預防
• 適合：一般客製情境、預期未來結構可能擴展
• 代價：多一個變數、多一次 query;函式內邏輯變得依賴外部變數

C：函式接受元件根當參數

• 機制：function setup(shell) { shell.querySelector(...) }、外部呼叫 document.querySelectorAll('.shell').forEach(setup)
• 跟 B 的取捨：B 假設只有一個 shell、C 直接支援多 shell；C 的設計成本前期較高（每函式多一個參數）、但多實例支援是免費的
• C 比 B 好的情境：頁面同時有多個 shell（例如多語切換頁面）、或計劃中要重用組件到不同頁面

D：事件 + closest 反向找根

• 機制：監聽全域事件、事件處理時 e.target.closest('.shell') 反向找元件根
• 跟 B/C 的取捨：B/C 是「初始化時綁定」、D 是「事件發生時動態判斷」— D 適合元件動態出現 / 消失（SPA 路由切換、AJAX 注入）
• D 比 C 好的情境：元件實例在 runtime 動態增減、用 mutation observer 補打成本反而更高
• 代價：事件委派的調試比直接綁定難（不知道事件實際從哪傳上來）

設計取捨：範圍深度

querySelector 預設找任意深度、可以收緊到直接子。三種做法：

A：任意深度（這個專案的預設）

• 機制：shell.querySelector('.target') — 子樹任何深度都接受
• 選 A 的理由：結構可能因 framework 升級微調、容忍微調換取維護彈性
• 代價：深層結構意外多出同名元素時可能誤命中

B：直接子 :scope > X

• 機制：shell.querySelector(':scope > .target') — 只找直接子
• 跟 A 的取捨：A 容忍結構微調、B 強制結構穩定 — B 帶來「結構變動立即報錯」的早期偵測
• B 比 A 好的情境：自家完全控制的結構、想用 selector 失敗當回歸測試訊號

C：特定路徑 :scope > A > B

• 機制：強制一條精確路徑
• 代價：結構任何微調都壞、維護成本高
• C 才合理的情境：寫整合測試的結構斷言、不是 production query

設計取捨：過濾與 idempotency

apply 函式可能被多次觸發（observer / event / 初始化）、過濾保證每元素只處理一次。三種做法：

A：DOM attribute 標記（這個專案的預設）

• 機制：:not([data-scoped]) 過濾 + 處理後 el.setAttribute('data-scoped', 'true')
• 選 A 的理由：標記跟著 DOM 元素走、元素被移除時自動清理；標記在 devtools 可見、debug 直接
• 代價：DOM 上多了一個自家用的 attribute（命名衝突風險小）

B：WeakMap 紀錄

• 機制：var processed = new WeakMap(); processed.set(el, true)
• 跟 A 的取捨：B 不污染 DOM、適合「不想留 attribute 痕跡」的場景；A 在 devtools 可見、debug 較直接
• B 比 A 好的情境：寫成第三方函式庫、不想對使用者 DOM 加屬性

C：依賴外部呼叫者保證只呼叫一次

• 機制：apply 內不防護、依賴 init 時只綁一次 listener
• 成本特別高的原因：observer 觸發 / 事件觸發 / 初始化任一處多呼叫、就產生重複處理 bug；錯誤難以追蹤
• C 才合理的情境：apply 本身是 idempotent 的（例如 set class 設成已是的值、無副作用）— 此時不需過濾

判讀徵兆

核心原則：Selector 精準度不是極致最佳化、是 sanity 防線。三維度（起點 / 範圍 / 過濾）一起設計、每個維度都顯式選擇 — 比從寬泛開始一路追 bug 容易得多。

寬 selector（querySelectorAll('.title')）是「便利位置」、窄 selector 是「對齊位置」 — 這個反相關的更高層原則見 #67 寫作便利度跟意圖對齊反相關。

MutationObserver 監聽最少必要的變動 — 從「監聽哪個 root」「觀察什麼類型」「多久觸發一次」三維度收斂。 範圍寬會頻繁觸發、option 勾多會在不關心的變動上跑邏輯、apply 自己改 DOM 會引發無限循環。三維度都該顯式設計、不能只丟預設。

為什麼 observer 需要獨立議題

跟 selector 的差異

Observer 與 selector 都涉及「DOM 範圍」、機制完全不同：

把 selector 與 observer 綁同一篇討論會混淆 — 兩者解決的是不同問題、有不同失敗模式、需要不同的設計工具。

Observer 寬範圍的失敗模式

四種都來自「沒精細設計 observer 的監聽形狀」。

三維度收斂

維度 1：監聽哪個 root（範圍）

核心定義：observer 的 root 元素決定「哪些範圍內的變動會被看到」。

1// 寬：監聽整個 .pagefind-ui
2new MutationObserver(apply).observe(ui, { childList: true, subtree: true });
3
4// 收斂：只監聽結果列表
5var results = shell.querySelector('.pagefind-ui__results');
6new MutationObserver(apply).observe(results, { childList: true });

寬範圍把無關變動也帶進來 — pagefind 重繪 input、調整 filter、重排 chip 都會觸發 apply、但 apply 只關心結果變動。

Root 選擇的決策：找到「包含所有目標變動、但不包含其他無關變動的最小元素」。

• 太大 → 帶進無關變動、過度觸發
• 太小 → 漏掉真正關心的變動
• 剛好 → 只關心的變動觸發

問自己：「我關心的變動發生在哪些元素？這些元素的最小共同 ancestor 是誰？」答案就是 observer root。

維度 2：觀察什麼類型（option flag）

核心定義：MutationObserver 提供四種 option、每種對應不同類型變動：

1{
2  childList: true,        // 子節點增 / 減 / 重排
3  attributes: true,       // 屬性變動
4  attributeFilter: ['data-state'],  // 只看特定屬性
5  characterData: true,    // 文字內容變動
6  subtree: true,          // 上面三種往子樹深處看
7  attributeOldValue: true,  // 屬性變動時記錄舊值
8  characterDataOldValue: true,
9}

預設只勾需要的、不要全部 true：

避免勾 subtree：subtree 把監聽從「直接子」擴展到「整個子樹」、觸發頻率可能爆炸。只在「真的需要看深層變動」時用。

避免無 filter 的 attributes：DOM 屬性變動很頻繁（class 改、style 改、aria-* 改），不過濾會被淹沒。用 attributeFilter: [...] 縮到只看你關心的屬性。

維度 3：多久觸發一次（頻率）

核心定義：observer 的回呼可能短時間內被連續呼叫、用 debounce 把多次合併成一次。

1var timer;
2function schedule() {
3  clearTimeout(timer);
4  timer = setTimeout(apply, 80);
5}
6new MutationObserver(schedule).observe(root, { childList: true });

Debounce 80ms 表示「最後一次變動後 80ms 沒再變、才跑 apply」 — 把連續變動合併。

Debounce vs Throttle：

大部分 observer 場景適合 debounce — framework patch 是突發性、不是持續的。

Debounce 時間選擇：

預設 50-100ms — 比一個 frame 寬、又不會讓使用者感受延遲。

Self-mutation 循環的處理

問題場景

apply 函式自己也改 DOM 時、會再次觸發 observer：

1function apply() {
2  // 改了某個元素的 class（attribute 變動）
3  someEl.classList.add('processed');
4}
5new MutationObserver(apply).observe(root, {
6  attributes: true, subtree: true,
7});
8// → apply 改 class 觸發 observer → observer 又呼叫 apply → 無限循環

這不是邏輯錯、是 observer 機制的特性：observer 不會區分「是不是 apply 自己改的」。

解法：disconnect / observe 配對

1var observer = new MutationObserver(function () {
2  observer.disconnect();      // 暫停監聽
3  apply();                    // 自己改 DOM 不會觸發
4  observer.observe(root, options);  // 恢復監聽
5});
6observer.observe(root, options);

apply 期間 observer 暫停、apply 結束後恢復 — 自己的改動不會觸發自己。

解法替代：用 attribute 標記區分

1function apply() {
2  isApplying = true;
3  someEl.classList.add('processed');
4  isApplying = false;
5}
6new MutationObserver(function () {
7  if (isApplying) return;
8  apply();
9}).observe(root, options);

但這個解法有時序風險 — observer 是非同步、isApplying 可能在錯時間被讀。disconnect/observe 配對更穩。

解法替代：root 與目標分離

如果 apply 改的是 A、observer 監聽的是 B（A 跟 B 沒交集），自然不循環：

1new MutationObserver(apply).observe(resultsEl, { childList: true });
2function apply() {
3  // 改的是 input 而不是 results — 不會觸發 observer
4  inputEl.value = '...';
5}

設計時讓 observer 看的範圍跟 apply 改的範圍結構上分離 — 是最乾淨的解法、不需要 disconnect 配對。

觀察的時機問題

Observer 跟 framework 渲染週期競爭

Observer 在 framework 連續 patch 中段觸發、可能在 layout 還沒穩時就跑 apply、造成短暫視覺錯位：

1// framework 連續 patch：
2//   patch 1 → observer 觸發 → apply 跑 → 視覺 A
3//   patch 2 → observer 觸發 → apply 跑 → 視覺 B
4//   patch 3 → observer 觸發 → apply 跑 → 視覺 C（最終）
5// 使用者看到 A → B → C 的閃爍

Debounce 是這個問題的解 — 讓 observer 等 patch 完成才跑 apply。

確認時機正確

寫 observer 時自問：

每個問題都該有顯式答案、不能丟預設。

內在屬性比較：四種 observer 設計

推薦：收斂 root + 必要 option + debounce。apply 不改 DOM 時不需要 disconnect；改的話用結構分離優先、退而求其次用 disconnect。

進階技巧

1. 動態調整 observer 範圍

當監聽目標可能還沒 mount 時、用兩階段 observer：

 1// 階段 1：等目標 mount
 2var bootstrap = new MutationObserver(function () {
 3  var target = shell.querySelector('.pagefind-ui__results');
 4  if (!target) return;
 5  bootstrap.disconnect();
 6
 7  // 階段 2：mount 後監聽目標
 8  new MutationObserver(apply).observe(target, { childList: true });
 9});
10bootstrap.observe(shell, { childList: true, subtree: true });

階段 1 用寬範圍找到目標、階段 2 切到精準範圍 — 把寬範圍的觸發限制在「找目標」這個短時間。

2. 用 takeRecords 主動取出累積變動

1var observer = new MutationObserver(function () { /* ... */ });
2observer.observe(root, options);
3
4// 之後某時間點、想立刻處理累積的變動
5var records = observer.takeRecords();
6processRecords(records);

takeRecords 取出尚未觸發回呼的變動記錄、主動處理 — 適合「我想在某時間點同步處理累積變動」場景。

3. 多 observer 各管一塊

不要用一個 observer 監聽全部、各分一個：

1new MutationObserver(applyA).observe(elA, { childList: true });
2new MutationObserver(applyB).observe(elB, { attributes: true });

各自獨立 — 一個 observer 出錯不影響另一個、debug 範圍小、option 各自最佳化。

設計取捨：MutationObserver 的設計策略

四種做法、各自機會成本不同。這個專案選 A（收斂 root + 必要 option + debounce）當預設、其他做法在特定情境合理。

A：收斂 root + 必要 option + debounce + 結構分離（這個專案的預設）

• 機制：root 取最小共同 ancestor、option 只勾真正關心的變動、加 50-100ms debounce、apply 改的範圍跟 observer 看的範圍結構上分離
• 選 A 的理由：觸發頻率最低、layout 穩定、無 self-mutation 循環風險
• 適合：絕大多數 observer 設計
• 代價：前期設計成本中（要思考 root / option / 結構）

B：收斂 root + 必要 option（無 debounce）

• 機制：縮範圍與 option、但不加 debounce
• 跟 A 的取捨：B 即時反應、A 等 debounce；但 B 在 framework patch 中段觸發、layout 不穩時跑 apply 結果不可靠
• B 比 A 好的情境：apply 不依賴 layout（純改 attribute、不讀 bounding rect）

C：寬範圍 + subtree + 全勾 option（預設配置）

• 機制：observe(elem, { childList: true, subtree: true, attributes: true, …})
• C 是反模式：「以防萬一全勾」會觸發數十倍頻率的 callback、framework 環境必撞效能 / 競態 bug
• 看起來吸引人的原因：寫法簡單、不用想要監聽什麼、「全部都看就不會漏」
• 實際發生的代價：CPU 100%、layout thrashing、self-mutation 引發無限迴圈

D：disconnect / observe 配對處理 self-mutation

• 機制：apply 前 disconnect、apply 後 reconnect
• 跟 A（結構分離）的取捨：D 處理 callback 必須改 observer 監聽範圍的情境、A 從設計上避免；A 更乾淨
• D 比 A 好的情境：無法做結構分離（apply 必須改 observer 看的範圍）— 唯一情境

判讀徵兆

核心原則：MutationObserver 是非同步監聽、跟同步 selector 設計工具完全不同。範圍 / option / 頻率三維度都要顯式設計 — 預設組合會在 framework 環境中過度觸發、且難以 debug。

subtree: true + attributes: true 是「監聽全部」的便利、窄 root + 最少 option 是「精準監聽」的對齊 — 同 #43 最小必要範圍 跟 #67 便利 vs 對齊反相關。

1document.querySelector('.target');
2document.querySelectorAll('.target');

從整個頁面找元素、不指定 ancestor scope。

這個做法存在的價值

簡潔。一行就能取到目標、不需要先建立元件根變數。在「我只想快速確認某個元素在不在 / 取它的某個屬性」這類情境下、寫一個 import shell 變數 + null check 是過度工程。

適合的情境

核心特徵：這段程式不會在多元件 / 動態 DOM 環境長期存活。

不適合的情境

安靜失敗是最危險的特徵 — 不報錯、操作了錯元素、bug 表現遠離 root cause。

跟其他起點做法的關係

#14 Selector 精準度 的「起點」維度有四種做法、document query 是其中之一：

選擇順序：production 客製預設用「元件根變數」、原型 / 探索 / 一次性才用 document query。

邊界：什麼時候 document query 在 production 也合理

幾個常見的 production 例外：

 1// 例外 1：操作的目標就是「全頁面唯一單例」
 2document.body.classList.add('page-search');
 3document.documentElement.setAttribute('data-theme', 'dark');
 4
 5// 例外 2：跨元件邊界的元素（不在任何元件內）
 6var slot = document.querySelector('.search-filter-slot');
 7// (slot 是 main 的子節點、不在 search-shell 內、不能從 shell 找)
 8
 9// 例外 3：頁面層級的 meta 元素
10document.querySelector('meta[name="description"]');

例外都共享一個特徵：目標元素本質上就在「頁面層級」、不是任何元件的內部。

不是例外的場景、即使「當前頁面只有一個」、也用元件根變數 — 預防未來擴展。

判讀徵兆

核心原則：document query 不是反模式、是有適用範圍的工具。判斷「這段程式預期活多久」 — 短命用 document、長命用元件根。

1var shell = document.querySelector('.search-shell');
2if (!shell) return;
3
4var input  = shell.querySelector('.pagefind-ui__search-input');
5var drawer = shell.querySelector('.pagefind-ui__drawer');
6// ... 之後所有 query 都從 shell 開始

把元件根 query 一次存變數、所有後續 query 都從這個變數開始。

這個做法存在的價值

把 selector 的作用範圍從「全頁面」收斂到「元件內部」。即使未來頁面其他地方出現同名元素、跟我無關。成本只多一行 query + 一個 null check、防護收益大。

適合的情境

核心特徵：寫的時候只有一個元件、但希望程式碼能容忍未來頁面結構變動。

不適合的情境

設計細節

Null check 的時機

1var shell = document.querySelector('.search-shell');
2if (!shell) return;

頁面可能沒有 shell（不是搜尋頁），所有後續 query 都會 null pointer。提早 return 比後續一連串 if (drawer) 乾淨。

等同於宣告：「這段程式只在有 shell 的頁面執行」。

變數的宣告位置

避免全域變數 — window.shell 容易跟其他 script 撞。

等待 shell mount 的處理

如果 script 跑得太早（shell 還沒 mount），shell 會是 null：

 1// 解法 1：等 DOMContentLoaded
 2document.addEventListener('DOMContentLoaded', function () {
 3  var shell = document.querySelector('.search-shell');
 4  if (!shell) return;
 5  // ...
 6});
 7
 8// 解法 2：MutationObserver 等 mount
 9var bootstrap = new MutationObserver(function () {
10  var shell = document.querySelector('.search-shell');
11  if (!shell) return;
12  bootstrap.disconnect();
13  // ...
14});
15bootstrap.observe(document.body, { childList: true, subtree: true });

選擇取決於 shell 是 server-render 還是 client-render：server-render 用 DOMContentLoaded、client-render 用 observer。

跟其他起點做法的關係

#14 Selector 精準度 的「起點」維度有四種做法：

預設用本卡片、需要多實例升級到「起點當參數」、需要動態升級到「closest」。

應用範例：完整 setup

 1function init() {
 2  var shell = document.querySelector('.search-shell');
 3  if (!shell) return;
 4
 5  var ui     = shell.querySelector('.pagefind-ui');
 6  var input  = shell.querySelector('.pagefind-ui__search-input');
 7  var drawer = shell.querySelector('.pagefind-ui__drawer');
 8
 9  if (!input || !drawer) return;  // 元件未完整 mount
10
11  syncScopeHeight(shell.querySelector('.search-scope'));
12  setupFilterSlotSwap(shell, drawer);
13  setupScopeFilter(shell, input);
14}
15
16document.addEventListener('DOMContentLoaded', init);

shell 取一次、各 setup 函式從 shell 派生需要的子節點。

判讀徵兆

核心原則：本 pattern 是 production 客製的預設、不是極致最佳化。當當前情境不複雜（一個元件、靜態 mount）、用本 pattern 即可；情境變複雜時再升級到對應做法。

1function setupSearchShell(shell) {
2  var ui     = shell.querySelector('.pagefind-ui');
3  var input  = shell.querySelector('.pagefind-ui__search-input');
4  var drawer = shell.querySelector('.pagefind-ui__drawer');
5  // ... 所有 query 從參數 shell 開始
6}
7
8document.querySelectorAll('.search-shell').forEach(setupSearchShell);

元件根不在函式內 query、由呼叫者傳入。函式支援任意數量的元件實例。

這個做法存在的價值

兩件事：

1. 多實例支援免費：forEach(setup) 自動處理多個 shell
2. 純函式特性：函式行為只依賴參數、不依賴外部狀態 — 可單獨測試、可重用、副作用集中

跟元件根變數的關鍵差異：那個 pattern 假設「shell 唯一」、本 pattern 把這個假設外移到呼叫端、函式本身不假設。

適合的情境

核心特徵：把「shell 從哪來」這個責任明確交給呼叫端、函式自己不關心。

不適合的情境

設計細節

函式簽名的設計

 1// 好：shell 是必填參數
 2function setupSearchShell(shell) { ... }
 3
 4// 較差：依賴外部變數
 5var shell;  // module scope
 6function setupSearchShell() {
 7  // 用了外部 shell
 8}
 9
10// 更差：mega object
11function setupSearchShell(allElements) {
12  var shell = allElements.shell;  // 不知道實際依賴什麼
13  // ...
14}

明確參數 = 明確依賴 = 容易測試、容易讀。

內部子函式也接受 shell

 1function setupSearchShell(shell) {
 2  syncScopeHeight(shell);
 3  setupFilterSlot(shell);
 4  setupScopeFilter(shell);
 5}
 6
 7function syncScopeHeight(shell) {
 8  var scope = shell.querySelector('.search-scope');
 9  // ...
10}

每層都明確接受 shell — 不依賴外層 closure。整套函式族都是純函式。

預先抓子節點 vs 每次重 query

 1// 方式 A：函式入口抓所有子節點
 2function setupSearchShell(shell) {
 3  var els = {
 4    ui:     shell.querySelector('.pagefind-ui'),
 5    input:  shell.querySelector('.pagefind-ui__search-input'),
 6    drawer: shell.querySelector('.pagefind-ui__drawer'),
 7  };
 8  // 後續用 els.ui / els.input / els.drawer
 9}
10
11// 方式 B：各子函式自己 query
12function setupSearchShell(shell) {
13  syncScopeHeight(shell);  // 內部自己 querySelector
14  setupFilterSlot(shell);
15}

A 比較有效率（只 query 一次）、B 比較解耦（子函式自包含）。選 B 為預設、效能瓶頸時才考慮 A。

跟其他起點做法的關係

#14 Selector 精準度 的「起點」維度有四種做法：

升級階梯：document → 元件根變數 → 起點當參數 → closest。複雜度遞增、能處理的情境也遞增。

應用範例：多實例 setup

1// 頁面有 N 個 search-shell（例如多語版面切換）
2document.querySelectorAll('.search-shell').forEach(setupSearchShell);
3
4// 跑完之後：每個 shell 各自獨立 setup、互不干擾

當前頁只一個 shell、上面這行也適用 —forEach 對 1 個元素跑一次、跟 hardcode 單例沒差。做了多實例設計、未來不需要重寫。

應用範例：單元測試

純函式可以對 mock DOM 測試：

1test('setupSearchShell 把 filter 移到 sidebar', function () {
2  var shell = createMockShell();  // 建立測試用 DOM
3  setupSearchShell(shell);
4
5  expect(shell.querySelector('.search-filter-slot').children.length).toBe(1);
6});

不需要全頁面 mount、只需要 mock 一個 shell — 測試成本低。

判讀徵兆

核心原則：本 pattern 把「我從哪取得 shell」的答案從函式內搬到呼叫端 — 換到「函式可重用」+「測試容易」+「多實例免費」三個收益、代價是函式簽名多一個參數。當前情境只一個實例也適用、未來擴展不需重寫。

1document.addEventListener('click', function (e) {
2  var shell = e.target.closest('.search-shell');
3  if (!shell) return;
4  // 在這個 shell 內處理
5  handleSearchClick(shell, e);
6});

不在初始化時綁定 listener、而是頁面層級委派事件、事件處理時從 e.target 反向找元件根。

這個做法存在的價值

把「找元件根」從「初始化時綁定」延後到「事件發生時動態判斷」 — 換到三個能力：

1. 元件動態增減免處理：新加的元件不需要重新綁 listener
2. 多實例不需要 forEach setup：所有實例共用一個 listener
3. 記憶體效率：N 個元件只綁 1 個 listener、不是 N 個

代價是事件處理邏輯多一層（每次都要 closest 反向找）。

適合的情境

核心特徵：元件的 mount 時機 / 數量 runtime 才知道、不是初始化時固定。

不適合的情境

設計細節

Closest 失敗的處理

1document.addEventListener('click', function (e) {
2  var shell = e.target.closest('.search-shell');
3  if (!shell) return;  // 點擊不在任何 shell 內
4  // ...
5});

closest 找不到時回 null、提早 return 是必要防護。沒這個 check 會在頁面其他地方點擊時報錯。

從 closest 結果再往下 query

1var shell = e.target.closest('.search-shell');
2var input = shell.querySelector('.pagefind-ui__search-input');

closest 找到 shell 後、可以從 shell 往下 query 同元件內的其他元素 — 這是「事件 + closest + 局部 query」的組合。

事件類型的選擇

注意 focus / blur 不會 bubble — 事件委派要用 focusin / focusout。

委派的根節點選擇

1// 選項 1：document（最寬）
2document.addEventListener('click', handler);
3
4// 選項 2：特定容器（縮範圍）
5var pageContainer = document.querySelector('main');
6pageContainer.addEventListener('click', handler);

縮範圍的好處是「跟其他頁面區域的 listener 不互相干擾」。預設用 document、有干擾風險才縮。

跟其他起點做法的關係

#14 Selector 精準度 的「起點」維度有四種做法：

複雜度遞增、能處理的動態程度也遞增。最動態的場景才用本 pattern。

應用範例：跨多 shell 的 scope filter

 1function setupGlobalScopeFilter() {
 2  document.addEventListener('change', function (e) {
 3    var shell = e.target.closest('.search-shell');
 4    if (!shell) return;
 5
 6    var scope = e.target.closest('.search-scope');
 7    if (!scope) return;  // 不是 scope 控制的 change
 8
 9    applyScope(shell, scope);
10  });
11}
12setupGlobalScopeFilter();

一個 listener 處理所有 shell 的 scope 變動 — 不論 shell 是初始 mount 的、還是 runtime 注入的。

應用範例：與 起點當參數 組合

 1// 初始化階段：對已存在的 shell 做 setup
 2document.querySelectorAll('.search-shell').forEach(setupSearchShell);
 3
 4// 事件階段：用 closest 處理可能新加的 shell
 5document.addEventListener('click', function (e) {
 6  var shell = e.target.closest('.search-shell');
 7  if (!shell) return;
 8  // 處理事件、不論 shell 是初始的還是後加的
 9});
10
11// MutationObserver：捕捉新加的 shell 做 setup
12new MutationObserver(function (mutations) {
13  mutations.forEach(function (m) {
14    m.addedNodes.forEach(function (node) {
15      if (node.matches && node.matches('.search-shell')) {
16        setupSearchShell(node);
17      }
18    });
19  });
20}).observe(document.body, { childList: true, subtree: true });

三個 pattern 組合：「靜態 setup」+「事件動態」+「mount 時 setup」 — 各 pattern 補不同時間點的需求。

判讀徵兆

核心原則：closest 反向找根把「定位元件」從綁定時延後到事件發生時 — 換到動態能力、付出的是事件處理多一層判斷。靜態場景用更簡單的做法、動態場景才升級到本 pattern。

1shell.querySelectorAll('.pagefind-ui__result:not([data-scoped])').forEach(function (el) {
2  // ... 處理
3  el.setAttribute('data-scoped', 'true');
4});

apply 函式入口用 :not([data-x]) 過濾掉已處理元素、處理完後設 attribute 標記。下次 apply 被觸發時、已處理的元素不會被命中。

這個做法存在的價值

把「保證只處理一次」的責任從呼叫端（要記得只呼叫一次）轉到元素本身（看自己有沒有被處理過）。

apply 函式可能被多個源觸發：

• 初始化時呼叫
• MutationObserver 偵測到變動觸發
• 使用者事件觸發
• Framework 重繪後重新呼叫

任一個源多呼叫就重複處理 — 無法靠呼叫端紀律避免。Idempotency 標記讓 apply 自己防護。

適合的情境

核心特徵：元素的 attribute 跟著元素 DOM 生命週期、元素移除時標記自動消失。

不適合的情境

設計細節

Attribute 命名規範

1// 好：明確 namespace + 用途
2el.setAttribute('data-search-scoped', 'true');
3el.setAttribute('data-myapp-processed', 'true');
4
5// 較差：通用名、容易跟其他程式撞
6el.setAttribute('data-processed', 'true');
7el.setAttribute('processed', 'true');  // 不是 data-* 開頭、可能不被 HTML spec 接受

預設用 data-{appname}-{purpose} 格式 — 即使引入第三方 library 加 attribute、也不會撞名。

Attribute 值的選擇

 1// 用法 1：固定 'true'（最簡）
 2el.setAttribute('data-scoped', 'true');
 3
 4// 用法 2：紀錄處理時間 / 版本（debug 友善）
 5el.setAttribute('data-scoped', String(Date.now()));
 6el.setAttribute('data-scoped', 'v2');
 7
 8// 用法 3：boolean attribute（無值）
 9el.setAttribute('data-scoped', '');
10// CSS 用 [data-scoped] 即可選中

預設用 'true'、debug 困難時改 timestamp 看處理順序。

跟 framework 重繪共處

Svelte / React / Vue 重繪元素時、自家 attribute 通常會被保留（framework 只管自己的 attribute）— 但有例外：

核心觀察：自家 attribute 跟著元素走 — 元素還在就有、元素被換就沒。這是「正確」行為、不是 bug。

例外：framework 主動清自家 attribute

少數 framework 會 strict 清非預期的 attribute（例如某些 Web Component lib）。檢查方式：

1el.setAttribute('data-scoped', 'true');
2// ... 等 framework patch 一次後
3console.log(el.getAttribute('data-scoped'));  // 還在嗎？

如果消失、改用 WeakMap 紀錄。

跟其他 idempotency 做法的關係

#14 Selector 精準度 的「過濾」維度有三種做法：

預設用本卡片、第三方 library / framework 衝突情境升級到 WeakMap。

應用範例：完整 apply

 1function apply(shell) {
 2  var newResults = shell.querySelectorAll(
 3    '.pagefind-ui__result:not([data-search-scoped])'
 4  );
 5
 6  newResults.forEach(function (el) {
 7    bindClickHandler(el);
 8    addCustomBadge(el);
 9    el.setAttribute('data-search-scoped', 'true');
10  });
11}
12
13// 多源觸發都安全
14init.addEventListener('click', () => apply(shell));
15observer.observe(shell, ...);  // 觀察到變動觸發 apply
16apply(shell);  // 初始化時跑一次

三個觸發點任一個多跑、:not([data-search-scoped]) 都會過濾掉已處理元素。

應用範例：多維度標記

 1// 三個獨立 idempotency 維度、各自 attribute
 2el.setAttribute('data-search-scoped', 'true');     // scope filter 處理過
 3el.setAttribute('data-search-bound', 'true');      // event listener 綁過
 4el.setAttribute('data-search-decorated', 'true');  // 視覺裝飾加過
 5
 6// 各 apply 函式只看自己的 attribute
 7function applyScope(shell) {
 8  shell.querySelectorAll('.x:not([data-search-scoped])').forEach(...)
 9}
10function applyBindings(shell) {
11  shell.querySelectorAll('.x:not([data-search-bound])').forEach(...)
12}

每個 idempotency 維度獨立 — 互相不干擾。

判讀徵兆

核心原則：把 idempotency 責任從呼叫端搬到元素本身、attribute 是「便宜可見的旗標」。Production apply 預設用本 pattern、特殊情境（library / framework 衝突）才升級到 WeakMap。

1var processed = new WeakMap();
2
3shell.querySelectorAll('.pagefind-ui__result').forEach(function (el) {
4  if (processed.has(el)) return;
5  // ... 處理
6  processed.set(el, true);
7});

把「已處理」狀態紀錄在 JS 的 WeakMap 裡、不寫到 DOM 上。WeakMap key 是元素本身、元素被 GC 時自動清理。

這個做法存在的價值

兩件事 DOM attribute 標記 做不到：

1. 不污染 DOM：使用者 DOM 不會被加自家 attribute、適合第三方 library
2. 跟 framework 完全解耦：framework 怎麼操作 DOM 都不影響 WeakMap 紀錄

代價是 debug 不便（看不到狀態）、紀錄跟 JS context 綁定（換頁就消失）。

適合的情境

核心特徵：紀錄獨立於 DOM 之外、跟 JS 物件 lifetime 綁定。

不適合的情境

設計細節

為什麼用 WeakMap 不用 Map / Set

1// WeakMap：key 是元素、元素被 GC 時 entry 自動消失
2var processedW = new WeakMap();
3processedW.set(el, true);
4// el 從 DOM 移除 + 沒其他 reference → GC → WeakMap entry 消失
5
6// Map / Set：強引用、阻止 GC
7var processedS = new Set();
8processedS.add(el);
9// el 從 DOM 移除、但 Set 還抓著 → 永久 leak

DOM 元素可能動態移除（filter、SPA 路由切換、framework 重繪）— Map / Set 會造成 memory leak。處理 DOM 元素 idempotency 預設用 WeakMap。

Value 的設計

 1// 用法 1：純 boolean（最簡）
 2processed.set(el, true);
 3
 4// 用法 2：紀錄處理版本（升級時偵測 stale 紀錄）
 5processed.set(el, { version: 2, time: Date.now() });
 6if (processed.has(el) && processed.get(el).version === currentVersion) return;
 7
 8// 用法 3：紀錄相關 metadata（避免重複查詢）
 9processed.set(el, {
10  bindingsId: registerListener(el),
11  initialClass: el.className,
12});

WeakMap value 可以儲任何資料 — 比 attribute（只能存字串）更彈性。

Debug 替代方案

attribute 標記可以在 devtools inspector 直接看；WeakMap 看不到。debug 時的替代：

1// 開發模式同步寫一份 attribute（production build 時拿掉）
2function markProcessed(el) {
3  processed.set(el, true);
4  if (DEV_MODE) {
5    el.setAttribute('data-debug-processed', 'true');
6  }
7}

或暴露到 console：

1window.__debug_processed = processed;
2// console: __debug_processed.has($0)  // 檢查當前選中元素

這些都是 workaround、不如 attribute 標記直觀。選 WeakMap 的人通常已經接受這個 debug 成本。

Reset 紀錄

1// WeakMap 整批 reset
2processed = new WeakMap();
3
4// 對比 attribute 整批 reset 要遍歷
5shell.querySelectorAll('[data-scoped]').forEach(el => {
6  el.removeAttribute('data-scoped');
7});

需要週期性 reset（例如 user 切換 mode、所有元素該重新處理）— WeakMap 一行解決、attribute 要遍歷。

跟其他 idempotency 做法的關係

#14 Selector 精準度 的「過濾」維度有三種做法：

選擇順序：自家 application → attribute；library / framework 衝突 → WeakMap；反模式不選。

應用範例：library 設計

 1// 第三方 library export 的 init 函式
 2function initSearchEnhancement(shell) {
 3  var processed = new WeakMap();
 4
 5  function apply() {
 6    shell.querySelectorAll('.search-result').forEach(function (el) {
 7      if (processed.has(el)) return;
 8      enhanceResult(el);
 9      processed.set(el, true);
10    });
11  }
12
13  apply();
14  new MutationObserver(apply).observe(shell, { childList: true, subtree: true });
15}
16
17// 使用者：
18initSearchEnhancement(document.querySelector('.my-search'));
19// 不會在使用者 DOM 上加任何 data-* attribute

使用者 DOM 完全乾淨、library 行為內聚。

應用範例：版本化處理

 1var processed = new WeakMap();
 2var CURRENT_VERSION = 3;
 3
 4function apply() {
 5  shell.querySelectorAll('.x').forEach(function (el) {
 6    var record = processed.get(el);
 7    if (record && record.version === CURRENT_VERSION) return;
 8
 9    // 升級到新版本（可能需要清舊綁定）
10    if (record) cleanup(el, record);
11    enhance(el, CURRENT_VERSION);
12    processed.set(el, { version: CURRENT_VERSION, time: Date.now() });
13  });
14}

版本變動時 — 不需要遍歷 DOM 清舊 attribute、直接用 WeakMap value 比對。

判讀徵兆

核心原則：WeakMap idempotency 是 attribute 標記的「不污染 DOM 替代品」 — 在 library / framework 衝突情境必要、在自家 application 通常用 attribute 即可。GC 自動清理是 WeakMap 的特性、預設不用 Map / Set 是因為它們會 memory leak。

 1var mql = window.matchMedia('(min-width: 1400px)');
 2function place() {
 3  if (mql.matches) {
 4    desktopSlot.appendChild(filter);
 5  } else {
 6    drawer.insertBefore(filter, drawer.firstChild);
 7  }
 8}
 9mql.addEventListener('change', place);
10place();  // 初始化

同一個 DOM 節點在兩個 slot 之間搬移、不複製成兩份。

這個做法存在的價值

Stateful UI（內含 checkbox 勾選、表單值、scroll 位置等 state）跨兩個顯示位置切換時、複製兩份會造成 state 分歧 — 使用者在 desktop 勾的 filter、切到 mobile 看不到勾選狀態。

搬同一份節點 = state 永遠跟著節點走 = 切換無感。

適合的情境

核心特徵：UI 內含 state、兩個位置展示的是「同一個邏輯單位」、不是「兩個獨立元件」。

不適合的情境

設計細節

appendChild 是搬遷、不是複製

1parentA.appendChild(node);  // node 從原位置消失、出現在 parentA

DOM API 的 appendChild / insertBefore 是 move、不是 copy — 同一個節點不能同時存在於多個位置。這個特性正是搬遷 pattern 的基礎。

初始放在哪

1<!-- 預設位置（mobile / fallback）-->
2<div class="pagefind-ui">
3  <div class="drawer">
4    <div class="filter-panel">...</div>  <!-- 初始在這 -->
5  </div>
6</div>
7
8<!-- 桌面 slot（空、等待搬入）-->
9<aside class="desktop-filter-slot"></aside>

預設放在 fallback 位置 — 當 JS 失敗時仍可見。

跨 slot 切換的時機

matchMedia event 是 viewport 跨過 breakpoint 的瞬間：

1var mql = window.matchMedia('(min-width: 1400px)');
2mql.addEventListener('change', place);
3place();  // 初始也跑一次

不要用 resize event — 太頻繁、會在 breakpoint 邊界震盪。matchMedia 只在 cross 的瞬間觸發。

搬遷時 framework 的 reactivity

如果搬遷的節點是 framework 管的（如 Pagefind 的 svelte 元件）— 整節點搬通常安全、framework 在下次 patch 時看到節點還在、繼續更新內部。

詳細安全規則由 #13 JS 操作 framework 元件：邊界辨識與安全規則 處理。

Focus 跟著搬

搬遷可能讓鍵盤 focus 暫時失去（視瀏覽器）— 加 save/restore：

1function place() {
2  var activeBefore = document.activeElement;
3  if (mql.matches) desktopSlot.appendChild(filter);
4  else drawer.insertBefore(filter, drawer.firstChild);
5  if (activeBefore && filter.contains(activeBefore)) {
6    activeBefore.focus();
7  }
8}

詳細處理由 #37 動態 DOM 移動時的 focus 管理 處理。

設計取捨：兩個 slot 的 stateful UI 共用

四種做法、各自機會成本不同。預設選 A（搬同節點）、其他做法在特定情境合理。

A：搬同一節點（這個專案的預設）

• 機制：matchMedia + appendChild 在兩 slot 間搬同一份節點
• 選 A 的理由：state 跟著節點、切換無感、不需要 sync 邏輯
• 適合：stateful UI、需要在兩個位置展示同樣內容
• 代價：搬遷 callback 在 viewport 跨 breakpoint 時觸發、需要處理 focus / 動畫
• 詳細：本卡片

B：CSS-only 雙顯示 + display 切換

• 機制：兩個位置都放同一份節點 (寫兩遍 HTML)、用 @media + display: none 切換顯示
• 跟 A 的取捨：B 純 CSS 簡單、A 需要 JS；但 B 對 stateful UI 失敗（兩份 state 各自獨立）
• B 比 A 好的情境：UI 純 stateless（純圖示）、純 CSS 解就夠

C：CSS-only + JS 同步 state

• 機制：兩份節點 + JS 監聽 state 變動同步
• 跟 A 的取捨：C 比 B 解 state 問題、但同步邏輯複雜（雙向更新、避免循環）
• C 比 A 好的情境：兩個位置的 UI 視覺需要差異（不只是位置不同）

D：JS 完全重建 UI

• 機制：viewport 變動時拆掉舊 UI、在新位置重建一份
• 成本特別高的原因：state 在重建時遺失、UI 閃爍、輸入中斷
• D 才合理的情境：UI 是 stateless 的、且重建成本低

跟其他 pattern 的關係

#14 Selector 精準度 的「起點」維度有四種做法、本卡片是「跨 slot 搬遷」這個專門情境的補充：

應用範例：跨 viewport filter 切換

 1function setupResponsiveFilter(shell, breakpoint) {
 2  var filter = shell.querySelector('.pagefind-ui__filter-panel');
 3  var drawer = shell.querySelector('.pagefind-ui__drawer');
 4  var desktopSlot = document.querySelector('.search-filter-slot');
 5
 6  if (!filter || !drawer || !desktopSlot) return;
 7
 8  var mql = window.matchMedia('(min-width: ' + breakpoint + 'px)');
 9
10  function place() {
11    var activeBefore = document.activeElement;
12
13    if (mql.matches) {
14      desktopSlot.appendChild(filter);
15    } else {
16      drawer.insertBefore(filter, drawer.firstChild);
17    }
18
19    if (activeBefore && filter.contains(activeBefore)) {
20      activeBefore.focus();
21    }
22  }
23
24  place();
25  mql.addEventListener('change', place);
26}

完整 pattern：取元件根 + matchMedia + 搬遷 + focus 處理。

判讀徵兆

核心原則：Stateful UI 的兩個展示位置共用同一份節點、state 自然跟著走 — 比「兩份節點 + sync 邏輯」乾淨。複製兩份是「state 來源從一變二」的隱形多源（違反 #44 SSoT）。

適用：寫 / 改 CSS 規則、設計 JS query selector、判斷是否該改 layout 結構。 不適用：純邏輯演算法（沒有 DOM）。

自包含聲明：閱讀本文件不需要先讀其他 reference。本文件涵蓋 DOM 量測方法、selector 三維度設計、四種起點的取捨。

何時參閱本文件

為什麼 DOM topology 要先確認

CSS 行為由「規則 + DOM tree + 樣式繼承 + 框架渲染」四個變數共同決定。靜態推理只能基於假設的 DOM tree — 假設錯了、推理就錯。

Class name 是命名約定 — pagefind-ui__drawer 看起來像 .pagefind-ui 的 child，但實際可能是 pagefind-ui__form 的 child。命名告訴你「這是 drawer」、不告訴你「在哪一層」。

跳過 DOM 確認的代價：寫了 N 條 CSS 規則、推理為什麼不生效、加 specificity / !important / display: contents — 全部基於錯假設。

量 DOM 的最小 query

 1// ancestor chain
 2async () => {
 3  const el = document.querySelector('.target');
 4  let chain = []; let n = el;
 5  while (n && n !== document.body) {
 6    chain.push(`${n.tagName}.${n.className}`);
 7    n = n.parentElement;
 8  }
 9  return chain;
10}

返回值告訴你目標元素在 DOM tree 哪個位置、parent / sibling 是誰。寫 CSS 規則前 30 秒能省掉後續 30 分鐘推理。

Selector 設計三維度

精準的 selector = 起點 + 範圍 + 過濾 三維度顯式設計、不是「能命中就好」。

起點四選一（依情境）

起點 A：Document 全文件 query

1document.querySelector('.target');

用：原型期、單例（整頁只一個）、跨元件邊界元素。 不用：production 客製、可能多實例、效能敏感（大頁面）。

起點 B：元件根變數 query

1const root = document.querySelector('.pagefind-ui');
2root.querySelector('.target');  // 從 root 起

用：production 客製、客製只該影響該元件、避免命中其他頁面同名元素。 不用：跨多元件邊界的 query。

起點 C：起點當函式參數

1function decorate(root) {
2  return root.querySelector('.target');
3}

用：library / utility function、需要支援多實例、純函式設計。 不用：一次性腳本（多餘的抽象）。

起點 D：closest() 反向找根

1button.addEventListener('click', e => {
2  const card = e.target.closest('.result-card');
3  card.classList.add('expanded');
4});

用：動態 / 多實例元件、event delegation、不知道事件源在哪一層。 不用：靜態起點已知（用 B 或 C 更直接）。

範圍：> 還是空格

預設 >、有證據（多層 nested 結構都該 match）才放寬到空格。

過濾：idempotency 標記

JS 處理元素時、避免重複處理。兩種做法：

A：DOM attribute 標記

1function decorate(root) {
2  const targets = root.querySelectorAll('.target:not([data-decorated])');
3  targets.forEach(el => {
4    // ... 處理
5    el.setAttribute('data-decorated', '');
6  });
7}

用：production 預設、devtools 可見、跨 page reload 也保留（如果元素持久）。 不用：library 設計（不該污染使用者 DOM）。

B：WeakMap 紀錄

1const decorated = new WeakMap();
2function decorate(root) {
3  root.querySelectorAll('.target').forEach(el => {
4    if (decorated.has(el)) return;
5    // ... 處理
6    decorated.set(el, true);
7  });
8}

用：library 設計、不污染 DOM、元素 GC 後紀錄自動清。 不用：跨頁面、需要 devtools debug、需要 CSS selector 過濾（CSS 看不到 WeakMap）。

Wrong vs Right 對照

範例 1：寫 CSS 前沒看 DOM

任務：把 pagefind-ui__drawer 排到 pagefind-ui__form 下方

錯（基於 class 命名假設）：

1.pagefind-ui {
2  display: grid;
3  grid-template-rows: auto auto;
4}
5.pagefind-ui__form { grid-row: 1; }
6.pagefind-ui__drawer { grid-row: 2; }

跑出來 drawer 跑到頁尾、grid-row 完全沒生效。

對（先量 DOM）：

1async () => {
2  const drawer = document.querySelector('.pagefind-ui__drawer');
3  let chain = []; let n = drawer;
4  while (n && n !== document.body) { chain.push(`${n.tagName}.${n.className}`); n = n.parentElement; }
5  return chain;
6}
7// 返回：[DIV.pagefind-ui__drawer, FORM.pagefind-ui__form, DIV.pagefind-ui]
8// → drawer 是 form 的 child、不是 sibling
9// → grid-row 在 .pagefind-ui 上設、無法控制 form 的 child

→ 換方向：drawer 改 absolute、form 加 margin-bottom 留 spacer。

範例 2：selector 過寬命中無關元素

錯：

1document.querySelectorAll('.title').forEach(el => el.classList.add('search-title'));
2// 命中 page header 的 .title、navbar 的 .title、結果卡的 .title — 全變色

對：

1const root = document.querySelector('.pagefind-ui');
2root.querySelectorAll(':scope > .results > .result > .title').forEach(el => el.classList.add('search-title'));
3// 起點 = .pagefind-ui、範圍 = 確切三層、過濾 = 不需要（已精準）

自檢清單（dogfooding）

寫 CSS 規則或 JS query 前：

• 我有沒有量過真實 DOM tree（playwright browser_evaluate 或 DevTools）？
• Selector 的「起點」明確嗎？是 document / 元件根 / 函式參數 / closest 哪一個？
• Selector 的「範圍」明確嗎？是 > 直接子還是空格子孫？
• Selector 的「過濾」明確嗎？需要 idempotency 標記嗎？
• 過寬的 selector（document.querySelectorAll('*')、[class*="x"]）能不能換成更精準的？

任一項打勾失敗 → 補上、再寫規則。

延伸閱讀

對應的事後檢討（在 content/report/）：

• dom-topology-before-css — 拓樸理解先行於 CSS 規則
• dom-selector-precision — Selector 精準度三維度
• pattern-document-query / pattern-component-root / pattern-root-as-parameter / pattern-closest-lookup — 起點四選一 pattern 卡片
• pattern-attribute-idempotency-marker / pattern-weakmap-idempotency-record — Idempotency 兩選一

Last Updated: 2026-04-26 Version: 0.1.0