18s 0.1.5 → 0.2.9

package/README.md

@@ -1,5 +1,223 @@
-# 18s
+[English](#en) | [中文](#zh)
 
-i18n.site self
+---
 
-see [https://atomgit.com/i18n/site/tree/dev](https://atomgit.com/i18n/site/tree/dev) for more
+<a id="en"></a>
+# 18s : High-performance subsetted font packages for the WebC component library
+
+Online Preview: [https://webc-zh.github.io](https://webc-zh.github.io)
+
+* [Features](#features)
+* [Directory Structure](#directory-structure)
+* [Design & Process](#design--process)
+* [Tech Stack](#tech-stack)
+* [Usage](#usage)
+* [History & Background](#history--background)
+
+## Features
+
+- **Dynamic Subsetting**: Splits large CJK fonts into small WOFF2 chunks (typically 128KB) to minimize browser loading times.
+- **Cache Busting**: Uses MD5 hashes of chunk content as filenames to prevent cache collision and maximize caching efficiency.
+- **Font Varieties**: Includes variable font versions of Source Han Sans SC (`t`) and JetBrains Mono (`c`).
+- **Clean CSS**: Output minimized CSS containing subsetted `@font-face` rules mapping local character ranges to the respective chunks.
+
+## Directory Structure
+
+```
+.
+├── gen/                 # Generation workspace containing raw TTF files and processing scripts
+│   ├── lib/             # Processing modules (font splitting, CSS minification)
+│   ├── ttf/             # Source TrueType Font (.ttf) files and configurations
+│   ├── gen.js           # Subsetting execution script
+│   └── gen.sh           # Setup and FFI dependencies download script
+├── woff2/               # Output distribution directory containing published assets
+│   ├── *.woff2          # Content-addressed subset font chunks
+│   ├── t.css            # Source Han Sans SC Font-face mappings
+│   ├── c.css            # JetBrains Mono Font-face mappings
+│   └── _.css            # Merged Font-face mappings for all fonts
+├── readme/              # Project documentation
+│   ├── en.md            # English README
+│   └── zh.md            # Chinese README
+├── package.json         # Project configuration metadata
+└── README.mdt           # Compilation template for root README
+```
+
+## Design & Process
+
+The compiler processes fonts defined in `gen/ttf/gen.yml`, splitting them and preparing production-ready CSS and font chunks.
+
+```mermaid
+graph TD
+    A[Font TTF Source files: SourceHanSansSC / JetBrainsMono] --> B[fontSplit / cn-font-split]
+    B --> C[Generate WOFF2 character subsets & result.css]
+    C --> D[Rename WOFF2 subsets to unique MD5 Base64url hashes]
+    D --> E[Rewrite result.css font-family & subset URLs]
+    E --> F[Output optimized woff2/t.css, woff2/c.css & woff2/_.css]
+```
+
+1. **Splitting**: Fonts are subsetted using `cn-font-split` into WOFF2 chunks.
+2. **Hashing**: Each chunk filename is renamed to its MD5 base64url hash prefix (starting at length 4, resolving conflicts by expanding length).
+3. **Rewriting**: The generated CSS file is parsed to replace original font-family names with short aliases (`t` and `c`), omit local search paths, and update chunk URLs.
+4. **Publishing**: Minimized CSS (both individual files and the merged `_.css`) and hashed WOFF2 chunks are output to `woff2/` for direct npm publication.
+
+## Tech Stack
+
+- **Runtime**: Bun
+- **Font Splitter**: `cn-font-split`
+- **CSS Minifier**: `lightningcss`
+- **Hash Function**: `@3-/base64url`
+
+## Usage
+
+### Installation
+
+```bash
+npm install 18s
+```
+
+### Importing Fonts
+
+Import the required CSS file in web components or application entries:
+
+```javascript
+// Import all fonts at once (merged CSS)
+import '18s/_.css';
+
+// Or import individual fonts as needed
+// Import Source Han Sans SC
+import '18s/t.css';
+
+// Import JetBrains Mono
+import '18s/c.css';
+```
+
+Apply in CSS stylesheets:
+
+```css
+body {
+  font-family: t, sans-serif;
+}
+
+code {
+  font-family: c, monospace;
+}
+```
+
+## History & Background
+
+CJK (Chinese, Japanese, Korean) font files are traditionally large (often 10MB to 50MB) because they contain tens of thousands of glyphs. Directly loading them in browsers causes severe rendering latency. Historically, developers embedded static, hand-selected character subsets or relied on system defaults, limiting design options.
+
+Source Han Sans, introduced jointly by Adobe and Google in 2014, solved the CJK typeface quality problem but still suffered from file size issues. The advent of modern dynamic subsetting, exemplified by tools like `cn-font-split`, split these typefaces into hundreds of micro-chunks based on character frequency. Browsers only fetch chunks containing characters actually present on the page, unlocking high-fidelity, performant CJK web typography.
+
+JetBrains Mono, released in 2020, focuses on readability for developers. Project `18s` bundles these optimized typefaces as variable fonts, ensuring lightweight integration for the WebC component library.
+
+---
+
+<a id="zh"></a>
+# 18s : 面向 WebC 组件库的高性能分片字体包
+
+组件库在线浏览地址：[https://webc-zh.github.io](https://webc-zh.github.io)
+
+* [功能特性](#功能特性)
+* [目录结构](#目录结构)
+* [设计思路与调用流程](#设计思路与调用流程)
+* [技术堆栈](#技术堆栈)
+* [使用指南](#使用指南)
+* [历史背景](#历史背景)
+
+## 功能特性
+
+- **动态分片**：将庞大 CJK 字体切分为微小 WOFF2 分片（默认 128KB），大幅降低首屏字体加载时延。
+- **防止冲突**：基于分片内容生成 MD5 哈希作为文件名，解决缓存冲突并提升缓存命中率。
+- **可变字重**：提供思源黑体（`t`）与 JetBrains Mono（`c`）可变字重版本。
+- **轻量 CSS**：输出压缩后的 CSS 代码，内置 `@font-face` 规则，精确映射字符区间至对应字体分片。
+
+## 目录结构
+
+```
+.
+├── gen/                 # 字体构建工作区，包含原始 TTF 文件与处理脚本
+│   ├── lib/             # 分片处理与 CSS 压缩模块
+│   ├── ttf/             # 原始字体文件及配置
+│   ├── gen.js           # 字体分片执行脚本
+│   └── gen.sh           # 依赖拉取与构建脚本
+├── woff2/               # 编译分发目录，包含最终发布资源
+│   ├── *.woff2          # 内容寻址的 WOFF2 字体分片
+│   ├── t.css            # 思源黑体字体映射表
+│   ├── c.css            # JetBrains Mono 字体映射表
+│   └── _.css            # 合并所有字体的映射表
+├── readme/              # 文档目录
+│   ├── en.md            # 英文文档
+│   └── zh.md            # 中文文档
+├── package.json         # 项目元数据配置
+└── README.mdt           # 主 README 模板文件
+```
+
+## 设计思路与调用流程
+
+构建系统读取 `gen/ttf/gen.yml` 配置，处理字体并生成发布资源。
+
+```mermaid
+graph TD
+    A[字体 TTF 源文件: SourceHanSansSC / JetBrainsMono] --> B[fontSplit / cn-font-split]
+    B --> C[生成 WOFF2 字符分片与 result.css]
+    C --> D[将 WOFF2 分片重命名为唯一 MD5 Base64url 哈希]
+    D --> E[重写 CSS 字体族名称与分片路径]
+    E --> F[输出压缩后的 woff2/t.css、woff2/c.css 与 woff2/_.css]
+```
+
+1. **分片处理**：调用 `cn-font-split` 工具，将原始字体切分为 WOFF2 格式片段。
+2. **哈希映射**：计算各分片内容的 MD5 base64url 哈希值，以此作为文件名（初始长度 4，遇冲突时递增长度），实现内容寻址。
+3. **样式重写**：解析 CSS，将默认 font-family 替换为简短别名（`t` 或 `c`），移除本地路径（`local`）查询，更新字体分片 URL 引用。
+4. **资源输出**：将 CSS（包含各字体独立文件以及合并后的 `_.css`）及字体分片写入发布目录 `woff2/`，以便独立进行 npm 发布。
+
+## 技术堆栈
+
+- **运行环境**：Bun
+- **分片工具**：`cn-font-split`
+- **样式压缩**：`lightningcss`
+- **哈希算法**：`@3-/base64url`
+
+## 使用指南
+
+### 安装依赖
+
+```bash
+npm install 18s
+```
+
+### 导入字体
+
+在 Web 组件或应用入口中引入 CSS 文件：
+
+```javascript
+// 一次性引入所有字体（合并后的 CSS）
+import '18s/_.css';
+
+// 或者按需引入单个字体
+// 引入思源黑体
+import '18s/t.css';
+
+// 引入 JetBrains Mono
+import '18s/c.css';
+```
+
+在样式表中应用对应的字体族：
+
+```css
+body {
+  font-family: t, sans-serif;
+}
+
+code {
+  font-family: c, monospace;
+}
+```
+
+## 历史背景
+
+汉字、日文和韩文（CJK）字体由于字符繁多，文件大小通常在 10MB 至 50MB 之间。直接在网页中加载此类字体会导致严重的白屏或字体闪烁问题。早期 Web 开发多采用系统默认字体，或通过繁琐的静态抽字工具仅保留特定字词，限制了动态内容的展示。
+
+2014 年，Adobe 与 Google 联合推出开源 CJK 字体思源黑体（Source Han Sans），解决了多语种排版设计问题，但体积瓶颈依旧存在。随着动态分片技术（如 `cn-font-split`）出现，字体文件能按字符使用频率和字符集关联动态切分为数百个微小分片。浏览器仅按需下载当前页面渲染所需的字型分片，极大地优化了中文字体在 Web 端的加载体验。
+
+JetBrains Mono 是 JetBrains 于 2020 年发布的专为代码阅读设计的开源编程字体。本项目 `18s` 将思源黑体与 JetBrains Mono 作为可变字体整合分片，旨在为 WebC 组件库提供轻量、美观、一致的视觉呈现。