# 聚珍（Juzhen）

> 現代簡／繁中文網頁排版套件。Han.css 之現代化重寫，沿其功能版圖，並針對
> 數種情況作調整：**複製乾淨**（中西間隙不入剪貼板）、**依 `lang` 全角／開明
> 自動切換**、**`justify` 下句末標點只佔一份間距**、**跨瀏覽器一致**
> （Chrome／Edge／Safari／WebKit／Firefox）。

倉庫名仍為 `cjk-autospace`；公開 API 為 `createJuzhen` / 全域 `Juzhen`；注入之
自訂元素前綴 `jz-`。完整設計見 [`ARCHITECTURE.md`](./ARCHITECTURE.md)。

> 本版（2.x）為從零重寫。v1 之 `createCjkAutospace` API 由相容層保留（見下），
> 既有消費端不需改碼即可運行；v1 原始碼保存於 `v1-autospace` 分支。

---

## 安裝與構建

```sh
npm install
npm run build   # esbuild → dist/juzhen.{mjs,iife.js,css}；tsc → dist/index.d.ts
npm test        # jsdom DOM 正確性測試
```

產物（`dist/`，已入庫）：

| 檔 | 用途 |
|---|---|
| `dist/juzhen.mjs` | ESM，供打包器／TypeScript |
| `dist/juzhen.iife.js` | IIFE，全域 `Juzhen`，原生 `<script>` 直跑 |
| `dist/juzhen.css` | 合併樣式（**必須引入**，視覺尺寸全在此） |
| `dist/index.d.ts` | TypeScript 型別宣告 |

---

## 用法

### 原生 `<script>`

```html
<link rel="stylesheet" href="dist/juzhen.css">
<script src="dist/juzhen.iife.js"></script>
<script>
    const jz = Juzhen.createJuzhen({ scope: { include: ".prose" } });
    jz.render();          // 對 document.body 套用（僅命中 .prose 子樹）
    // jz.revert();        // 還原
</script>
```

### ESM／TypeScript

```ts
import { createJuzhen } from "cjk-autospace";
import "cjk-autospace/css";

const jz = createJuzhen({ lang: { default: "zh-Hant" } });
jz.render(document.querySelector("main"));
```

**JS 與 CSS 缺一不可**：JS 只注入 `jz-*` 結構，所有視覺尺寸（間隙寬度、擠壓量、
`justify` 原子化、字體堆疊）都在 `juzhen.css`。

---

## 切片 1 已實作功能

| 功能 | 說明 |
|---|---|
| **中西間隙** `spacing` | CJK↔西文邊界插入 copy-clean 之 `jz-hws`（`user-select:none`，剪貼板跳過）。含跨樣式行內邊界與 `code`／`kbd` pill 邊界。 |
| **長英文詞** `longWord` | `[A-Za-z]{6,}` 包入 `<span lang="en">`，配合 CSS `hyphens:auto` 原生斷詞（DOM 無連字符 → 複製不污染）。 |
| **標點擠壓** `jiya` | 標點 charify 為 `jz-char`＋`bd-*` class。三機制：①baseline 政策（全角式不擠／開明式擠句內點號＋括號引號／半角式全擠）；②行內連續擠壓（相鄰標點對向側收）；③行端擠壓（`lineedge` layout pass）。半形以字型 `halt` 渲染（按字形正確定位，居中字形如 `！？`／繁體 `。，` 不重疊；不依賴 `text-spacing-trim`）。 |
| **禁則** `jinze` | 行首行末避頭尾：閉類／點號綁前一字（不置行首）、開類綁後一字（不置行末），只隔離邊界字故長引文中段仍可斷。亦為 `justify` 綁定載體。 |
| **justify 單份間距** | 每個 `jz-char` 為 `inline-block` 原子項，句末標點只貢獻一份對齊伸縮量。 |

後續（架構已預留，不返工）：標點懸掛、標點修正（簡↔繁）、著重號、注音／Ruby。

---

## 選項

```ts
createJuzhen({
    lang: {
        default: "zh-Hant",                                  // 無 lang 祖先時之預設
        policy: { "zh-Hant": "quanjiao", "zh-Hans": "kaiming" }, // 全角／開明／半角
    },
    scope: {
        root: document.body,        // 處理根；render(root) 可逐次覆寫
        include: ".prose",          // 啟用選擇器（opt-in）：僅處理命中子樹
        avoid: "blockquote.raw",    // 追加排除選擇器
    },
    spacing: true,
    longWord: { minLength: 6, lang: "en" },
    jiya: true,
    jinze: true,
    blocks: [                       // 分塊功能選擇
        { selector: ".code-comment", features: [ "spacing" ] },
    ],
});
```

### 分塊功能選擇（HTML 屬性，就近繼承）

```html
<p data-juzhen="spacing jiya">…</p>     <!-- 白名單：僅此二功能 -->
<p data-juzhen-off="jiya">…</p>          <!-- 黑名單：停用 jiya，其餘繼承 -->
<div lang="zh-Hans">…</div>              <!-- lang 驅動全角／開明 -->
```

---

## v1 向下相容

```js
// 既有消費端零改動：
const cjk = createCjkAutospace({ pillSelector: "code, kbd" });
cjk.apply(document.body);
```

IIFE 構建另掛 `globalThis.createCjkAutospace` 別名。**與 v1 之差異**（行為等價、
不要求逐位一致）：

- 間隙標記由 `<span class="cjk-autospace">` 變為 `<jz-hws class="cjk-autospace">`
  （仍帶原 class，既有 `.cjk-autospace{user-select:none}` CSS 仍命中）。
- 標點擠壓由消費端 `font-feature-settings:"halt"` 改為 `juzhen.css` 之負 `margin`
  （需改用 `juzhen.css`；機制不同，同為開明式「句內點號半形」之效果）。

---

## 目視驗證

`demo/index.html` 載入 `dist/` 產物，簡繁並列、可切 `justify`、附 copy-clean 測試區。
版面相關結論（justify 單份間距、擠壓視覺量、行端、`inline-block` 基線）須於
Chrome／Safari／Firefox 三引擎目視核對——jsdom 僅驗證 DOM 結構正確性。

---

## 授權

MIT。借鑑 Han.css／Heti 之思路與分類表（MIT），成品自含、不依賴其執行期程式碼。