feat: 功能分級(文本級 vs 段落級)+ data-jz-level 標記(§6.5.0a)

整體計劃 §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 測試全綠。
This commit is contained in:
2026-06-09 16:52:00 +08:00
parent a00b35577e
commit c1fbabf5b0
15 changed files with 309 additions and 7 deletions
+45 -1
View File
@@ -4,7 +4,7 @@
// 行內元素透明、pillblockavoid 中斷)、pill 鄰字查找、per-node 功能閘
// featureEnabledFor)。finder 不知具體排版規則,只提供遍歷與安全變更原語。
import type { ResolvedOptions } from "../types.js";
import type { FeatureLevel, ResolvedOptions } from "../types.js";
/** 邏輯 run 中之單一字元來源位置。 */
export interface CharPos
@@ -41,7 +41,9 @@ export class Finder
private readonly includeSelector: string | null;
private readonly skipAttr: string | null;
private readonly userIsSkipped: ((node: Node) => boolean) | null;
private readonly levelTextSelector: string | null;
private readonly featureCache: WeakMap<Element, Record<string, boolean>>;
private readonly levelCache: WeakMap<Element, FeatureLevel>;
constructor(opts: ResolvedOptions)
{
@@ -52,9 +54,11 @@ export class Finder
this.pillSelector = opts.finder.pillSelector;
this.skipAttr = opts.finder.skipAttribute;
this.userIsSkipped = opts.finder.isSkipped;
this.levelTextSelector = opts.levelText;
this.avoidSelector = opts.scope.avoid;
this.includeSelector = opts.scope.include;
this.featureCache = new WeakMap();
this.levelCache = new WeakMap();
}
/** 該元素是否匹配 pill 選擇器(行內塊,如 code/kbd)。 */
@@ -278,6 +282,46 @@ export class Finder
}
}
/**
* 節點之功能級別(§6.5.0a)。自 node 向上找**最近**之顯式信號:元素屬性
* `data-jz-level="text|paragraph"`(最優先),或命中 `level.text` 選擇器(→ text);
* 皆無則預設 paragraph(全功能)。結果以解析後之元素為鍵快取。
*/
levelFor(node: Node): FeatureLevel
{
const start = node.nodeType === 1 ? (node as Element) : node.parentElement;
if (!start) { return "paragraph"; }
const cached = this.levelCache.get(start);
if (cached) { return cached; }
let el: Element | null = start;
let result: FeatureLevel = "paragraph";
while (el)
{
const attr = el.getAttribute ? el.getAttribute("data-jz-level") : null;
if (attr === "text" || attr === "paragraph") { result = attr; break; }
if (this.levelTextSelector && el.matches && el.matches(this.levelTextSelector))
{
result = "text";
break;
}
el = el.parentElement;
}
this.levelCache.set(start, result);
return result;
}
/**
* 某級別之 pass 是否可作用於該節點(§6.5.0a gate)。文本級 pass 不受限(恆 true);
* 段落級 pass 僅作用於段落級元素(text-level 子樹跳過)。與 featureEnabledFor 疊加:
* level 為粗粒度語義組(先判),blocks/屬性為細粒度逐功能(後調)。
*/
levelAllows(node: Node, passLevel: FeatureLevel): boolean
{
if (passLevel === "text") { return true; }
return this.levelFor(node) === "paragraph";
}
/**
* 解析節點對某功能之有效啟用狀態(§3.6,per-node 閘)。向上找最近帶
* 功能指令之祖先(data-juzhen 白名單 / data-juzhen-off 黑名單 / 命中
+3
View File
@@ -49,6 +49,9 @@ function runCharify(passes: CharifyPass[], ctx: RenderContext): void
let requests: WrapRequest[] = [];
for (const p of passes)
{
// 功能分級閘(§6.5.0a):段落級 charify pass(如 longWord)對 text-level
// 子樹跳過;文本級(如 jiya)不受限。
if (!ctx.finder.levelAllows(node, p.level)) { continue; }
const got = p.collect(node, ctx);
if (got.length > 0) { requests = requests.concat(got); }
}