這是一份根據您提供的原始碼與測試案例整理出來的 lit-xpath 函式庫使用說明。本函式庫結合了 XPath / CSS 選擇器與 JavaScript 標籤模板字串 (Tagged Template Literals)，讓你在瀏覽器環境中查詢 DOM 節點時能寫出極具宣告性（Declarative）且精簡的程式碼。

lit-xpath 使用說明 (README)

lit-xpath 是一個輕量、靈活的 DOM 查詢輔助工具。它允許你直接使用標籤模板字串（Tagged Templates）來執行 XPath 或 CSS 選擇器，並內建強型別轉換（如自動轉成 Element、Array、String、Number 或 Boolean），同時支援上下文（Context）鏈式查詢與 DOM 內容/屬性的快速讀寫。

🚀 核心特色

• 標籤模板字串支援：直接寫出變數內插的查詢語句，如 xp.e//*[@id="${id}"] 。
• 強型別快捷字元：內建 e (Element)、a (Array)、s (String)、n (Number)、b (Boolean) 與 r (Raw XPathResult)。
• CSS 選擇器雙軌支援：不只 XPath，也能無縫切換到 xp.css(...) 使用標準 CSS 選擇器。
• 鏈式上下文查詢：透過 .ctx() 凍結目前節點，並基於該節點繼續向下深入查詢。
• 雙向讀寫：.s 屬性與 .attr() 方法不僅能讀取值，還能直接指派（Setter）來修改 DOM 內容與屬性。

📖 快速上手與基礎查詢

1. 取得單一元素 (Element / e)

當你確定查詢結果是單一 DOM 節點時，可以使用 element 或縮寫 e。

// 使用標籤模板字串查詢
const container = xp.e`//*[@id="control-pane"]`;

// 也可以像一般函式一樣傳參
const body = xp.element('//body'); 

2. 取得元素陣列 (Array / a)

會將 XPathResult 的節點快照自動轉換為標準的 JavaScript Array，方便使用 forEach、every、map 等陣列方法。

// 找出 body 下所有的 input 元素
const inputs = xp.a`//body//input`;
inputs.forEach(el => console.log(el.value));

// 鏈式寫法
const allDivs = xp.q`//div`.array;

3. 取得基本資料型別 (s, n, b)

直接呼叫 XPath 的內建函數（例如 count()、local-name()），並直接拿到轉換後的 JS 屬性值。

// String (s): 取得標籤名稱或屬性字串
const tagName = xp.s`local-name(//html)`; // 回傳 'html'
const idStr = xp.s`//*[@id="control-pane"]/@id`; // 回傳 'control-pane'

// Number (n): 取得計算數量
const inputCount = xp.n`count(//input)`; // 回傳數字，例如 5

// Boolean (b): 判斷條件是否成立
const hasId = xp.q`//*[@id]`.ctx().b`.[@id]`; // 回傳 true 或 false

🎯 鏈式操作與上下文 (Context) 查詢

當你查到一個節點後，可以透過 .ctx() 或 .toContext() 將其轉換為新的查詢起點。

// 1. 尋找父節點
const parent = xp.q('//body').ctx().e('..');

// 2. 基於某個區塊（如 aside）繼續深入查詢裡面的文字
const asideCtx = xp.q`//aside`.ctx();
const headingText = asideCtx.s`.//h1`; // 注意 '.' 代表當前上下文節點

你也可以直接在初始查詢時傳入上下文節點當作第二個參數：

const myButton = document.querySelector('#btn');
const parentOfButton = xp.e('..', myButton); // 傳入原生 DOM 節點作為 Context

🎨 使用 CSS 選擇器 (css)

如果你不想用 XPath，函式庫也提供了 css 模式，且同樣支援 e、a、s 等型別修飾器。

// 取得單一元素
const root = xp.css`:root`.e;

// 取得陣列
const dynamicInputs = xp.css`label > input`.a;

// 取得文字內容 (等同於選取元素的 textContent)
const title = xp.css`title`.s;

// CSS 上下文綜合查詢
const paneCtx = xp.css`#control-pane`.ctx();
const subInputs = paneCtx.css`input`.a; // 只找 #control-pane 內部的 input

✍️ 進階：修改 DOM 內容與屬性 (Setter)

1. 修改元素的文字內容

對查詢結果的 .s (或 .string) 屬性直接賦值，即可動態修改該節點的 textContent。

const heading = xp.q`//h1`.ctx().q`.`;
heading.s = '新標題文字'; // 畫面上 h1 的內容會被改變

// 清空某個節點內的所有子節點
xp.q('//main', document).s = ''; 

2. 讀取與設定屬性 (attr)

attr 方法模擬了原生的屬性操作，並支援標籤字串與傳參兩種寫法。

// 讀取屬性
const scriptSrc = xp.q`//script[@src]`.attr`src`;
const normalSrc = xp.q`//script[@src]`.attr('src');

// 設定屬性
const mainElement = xp.q`//main`;
mainElement.attr('data-node-name', 'primary-content'); // 寫入屬性

🛠️ 型別字典對照表 (Dictionary)

不論是在 方法名、縮寫方法名、還是鏈式操作的 屬性名，皆嚴格對照以下規則：

| 快捷字元 (Char) | 完整名稱 (Name) | 返回類型 | 映射之 XPathResult 屬性 / 處理機制 | | --- | --- | --- | --- | | e | element | DOM 元素 | FIRST_ORDERED_NODE_TYPE -> singleNodeValue | | a | array | JS 陣列 | ORDERED_NODE_SNAPSHOT_TYPE -> 遍歷轉為 Array | | s | string | 字串 | STRING_TYPE -> stringValue (支援 Setter) | | n | number | 數字 | NUMBER_TYPE -> numberValue | | b | boolean | 布林值 | BOOLEAN_TYPE -> booleanValue | | r | raw | 原生結果 | ANY_TYPE -> 直接回傳原始的 XPathResult 物件 |