admin
c1fbabf5b0
整體計劃 §6.5 之前置基礎設施。把已實作功能切為兩級：
- 文本級（spacing 中西間隙、jiya 標點擠壓／鄰接）：任意文本片段皆適用。
- 段落級（jinze 禁則、longWord 斷詞、lineEdge 行端、gapTrim）：需行／段布局。
標記 API：
- 預設塊級元素 → 段落級（全功能）。
- 元素屬性 data-jz-level="text"｜"paragraph"（最近祖先勝）。
- 選項 level:{ text: "選擇器" }（如標題／按鈕一鍵降為文本級）。
實作：
- 每個 pass 加 level 元數據；Finder.levelFor／levelAllows（含快取）。
- charify 段落級 pass（longWord）於共享走訪受閘；standalone 段落級 pass
（jinze／lineEdge／gapTrim）逐元素受閘。文本級不受限。
- spacing 補單元素 root 支援：root 為行內／單一非塊元素時亦處理（標題等
之中西間隙、標點半形生效）。
6 項新單元測試（text-level 跳段落級、選擇器標記、巢狀最近勝、單元素 spacing、
預設段落級回歸）。共 76 測試全綠。
79 lines
3.8 KiB
TypeScript
79 lines
3.8 KiB
TypeScript
import type { FeatureLevel, ResolvedOptions } from "../types.js";
|
||
/** 邏輯 run 中之單一字元來源位置。 */
|
||
export interface CharPos {
|
||
textNode: Text;
|
||
offset: number;
|
||
}
|
||
/** 一段邏輯文本：剝離樣式後之連續字元，及其逐字回映射。 */
|
||
export interface LogicalRun {
|
||
text: string;
|
||
map: CharPos[];
|
||
}
|
||
/** pill 鄰接之邏輯鄰字。 */
|
||
export interface AdjacentChar {
|
||
textNode: Text;
|
||
offset: number;
|
||
ch: string;
|
||
}
|
||
export declare class Finder {
|
||
private readonly opts;
|
||
private readonly styleSet;
|
||
private readonly blockSet;
|
||
private readonly skipSet;
|
||
private readonly pillSelector;
|
||
private readonly avoidSelector;
|
||
private readonly includeSelector;
|
||
private readonly skipAttr;
|
||
private readonly userIsSkipped;
|
||
private readonly levelTextSelector;
|
||
private readonly featureCache;
|
||
private readonly levelCache;
|
||
constructor(opts: ResolvedOptions);
|
||
/** 該元素是否匹配 pill 選擇器（行內塊，如 code/kbd）。 */
|
||
pillMatches(el: Element): boolean;
|
||
/** 邏輯文本應**透明穿越**之行內元素：樣式行內標籤，以及聚珍自身之 wrap 類
|
||
* jz-*（jz-hws 間隙、jz-jinze 禁則群組）。穿越這些才能正確找到跨包裝之邏輯
|
||
* 鄰字（如 jinze 已把 pill 納入 jz-jinze 後，pill 之左鄰字仍須可達；I7）。 */
|
||
private isTransparentInline;
|
||
/** 節點是否處於 avoid 子樹（內建 skip 名單 / SVG / contentEditable /
|
||
* data-jz-skip / 使用者 avoid 選擇器 / skipAttribute / isSkipped）。 */
|
||
isAvoided(node: Node): boolean;
|
||
/** scope.include 啟用判定：未設則恆 true；設則須有命中祖先（opt-in）。 */
|
||
inScope(node: Node): boolean;
|
||
/** 走訪 root 下所有「可處理」文本節點（已過濾 avoid / 非作用域）。 */
|
||
eachTextNode(root: Element, cb: (node: Text) => void): void;
|
||
/** 走訪 root 下所有 block 元素（含 root 本身若為 block）。 */
|
||
eachBlock(root: Element, cb: (block: Element) => void): void;
|
||
/**
|
||
* 收集 block 之邏輯文本 run（架構 §4.1，I7）：樣式行內元素與 wrap 類
|
||
* jz-* 透明穿越；block／pill／avoid／間隙 marker（jz-hws）中斷 run。
|
||
* 回傳 text.length >= 2 之 run（短於 2 無間隙可言）。
|
||
*/
|
||
collectRuns(block: Element): LogicalRun[];
|
||
/**
|
||
* pill 之邏輯鄰字（架構 §4.1）：經樣式鏈遞迴，遇 pill／block／avoid／間隙
|
||
* marker 即止。direction = -1 取前鄰字，+1 取後鄰字。
|
||
*/
|
||
adjacentLogicalChar(el: Element, direction: -1 | 1): AdjacentChar | null;
|
||
/**
|
||
* 節點之功能級別（§6.5.0a）。自 node 向上找**最近**之顯式信號：元素屬性
|
||
* `data-jz-level="text|paragraph"`（最優先），或命中 `level.text` 選擇器（→ text）；
|
||
* 皆無則預設 paragraph（全功能）。結果以解析後之元素為鍵快取。
|
||
*/
|
||
levelFor(node: Node): FeatureLevel;
|
||
/**
|
||
* 某級別之 pass 是否可作用於該節點（§6.5.0a gate）。文本級 pass 不受限（恆 true）；
|
||
* 段落級 pass 僅作用於段落級元素（text-level 子樹跳過）。與 featureEnabledFor 疊加：
|
||
* level 為粗粒度語義組（先判），blocks／屬性為細粒度逐功能（後調）。
|
||
*/
|
||
levelAllows(node: Node, passLevel: FeatureLevel): boolean;
|
||
/**
|
||
* 解析節點對某功能之有效啟用狀態（§3.6，per-node 閘）。向上找最近帶
|
||
* 功能指令之祖先（data-juzhen 白名單 / data-juzhen-off 黑名單 / 命中
|
||
* blocks 選擇器），無則回退全域 features。結果以元素為鍵快取。
|
||
*/
|
||
featureEnabledFor(node: Node, name: string): boolean;
|
||
private globalFeature;
|
||
private resolveFeature;
|
||
}
|