book-index-ui

book-index-manager 的 React 组件库 + 存储客户端，发布为 npm 包 book-index-ui。 配合 book-index-manager 的 Python CLI 一起使用。

npm install book-index-ui

包结构

两个独立入口：

import { ... } from 'book-index-ui'          // React 组件 + 类型 + 数据层
import { ... } from 'book-index-ui/storage'  // 仅数据层（无 React，体积小，适合 Node/Worker）
import 'book-index-ui/styles'                // CSS（用到组件时引入）

主要 export

React 组件

统一阅读器（TextReader，overview#307）

<TextReader
  id={workOrBookId} transport={storage}
  versionKey={key}  chapter={chapterKey}          // 受控（可不传，自己管）
  onLocationChange={(loc, cause) => router.push(urlFor(loc))}  // loc: { key, chapter, isDefault }；cause: 'auto' | 'chapter' | 'version'
  onNavigate={id => router.push(entryUrl(id))}
/>

• 数据模型（规格 overview 项目进展/古籍索引网站/设计/阅读文本.md）：items/<id>/manifest.json 列全部版本（versions[0] 是 default），<key>/index.json 是章目录（chapters[{ n, file:'001', title, has_json }]），章正文 <key>/001.txt，整理本的章另有 001.json。IndexStorage 新增可选 getTextManifest / getTextIndex / getChapter，BundleStorage 已实现。
• 只认新结构（用户 09-30 定）：条目没有 manifest.json（含旧的 collated_edition/、full_text/… 目录）就显示「暂无文本」，不从旧目录合成。旧的 CollatedEdition／BookFullText 暂留给还没迁移的页面，迁移在正式站验完后清掉。
• 界面：工具条一个「版本」下拉按 manifest 顺序列全部版本（含整理本），只有一份时只在书名后标来源名；正文末尾显示所选版本的出处与授权；章有 json 用结构化渲染（条目、作品链接、跨章搜索），否则按 md；切版本尽量停在同一章号，对不上回第一章。
• 组件不改 URL：宿主在 onLocationChange 里改地址（新 URL：/read/<id>[/<key>][/<章>]，主版本不写 key）。versionKey／chapter 传了就受控；传了无效值时组件回落并以 auto 通知。
• 工具条另有上一章／下一章（窄屏隐去，翻卷交给正文底部的翻页卡片）、书名链接回条目页；窄屏（右栏藏起来）时正文末尾有「报告错字」入口。

阅读器（components/Reader/，2026-09 N5a）

整理本与全文共用一个外壳 ReaderShell：

• 布局：书影在正文左边，目录在最左。宽屏（≥1100px）目录是可收起的侧栏（默认展开）；更窄时是抽屉（默认收起，选卷后自动合上，Esc 关闭，打开时 Tab 圈在抽屉内）；窄屏（≤719px）书影区不显示，只留正文。
• 工具条（吸顶）只用文字与图标：目录、繁｜简、A− A+、「阅读设置」键（overview#463）。其余偏好收进右侧「阅读设置」侧栏（≥860px 右侧可折叠栏；窄屏是底栏「设置」打开的底部抽屉），分三组：文字（字体、字号、繁简）、标注（专名线，对读时加标点）、版面（自然段、标出作品链接、书影、对读留白，竖排预留 allowVertical）。宿主可用 settingsAnnotate / settingsLayout 往侧栏塞自己的控件。字体选项只有宋体（默认，沿用 --bim-font-reading）／楷体／系统默认（无衬线），全是系统已装字体，不加载网络字体；楷体栈 Kaiti SC → Kaiti TC → STKaiti → KaiTi → AR PL UKai CN → Noto Serif CJK SC → serif。
• 正文：--bim-font-reading（宋体，默认接 --bim-font-serif，宿主覆盖后者即可）18px、行高 2.05（手机端同样），line-break: strict 避头尾；界面黑体。
• 无障碍：第一个可聚焦元素是「跳到正文」；目录用游走 tabindex，几百卷也只有当前卷进 Tab 序列（↑↓ Home End 移动）。
• 偏好（字号、字体、自然段、专名线…）存 localStorage['bim-reader-prefs']，首帧用默认值，SSR 安全。
• 宿主若有吸顶导航，设 --bim-reader-top（如 60px）。

书影接口：TextReader 的 resolveImages(chapterKey) 返回当卷的 ReaderPageImage[]（可异步）——每页一张图，URL 由宿主给，可带 width/height 与逐字框 boxes（暂定格式 bim-charbox-v0：原图像素坐标 x/y/w/h，可选 char/textOffset/confidence）。其他格式的框设 boxFormat 并用 renderImageOverlay 自己画，这是与 CV 交付格式对齐前的扩展点。没有影像时书影区默认收起（imagePanel="auto"），点工具条「书影」可看占位。

版本下拉框（overview#235，同一 owner 有多份全文时用）：ReaderShell 的四个 props——

配套两个导出（book-index-ui 根入口与 components/Reader）：readerVersionsFromFullText(entries) 把 book-text 的 WorkFullTextEntry[] 换成 ReaderVersion[]（顺序不变，清单已按「哪份最好」排好）；pickReaderVersion(versions, key?) 给出当前选中的一份（key 有效用它，否则 primary，再否则第一份），宿主用它决定该载入哪份 toc / 正文。

resolveImages 要用 useCallback（或模块级函数）包一层：组件按 [resolveImages, 当前卷] 重新取书影，每次渲染都传一个新函数会反复请求。

正文实体标注（EntityText，overview#389）

给一段正文和实体区间：人名、地名、官职等画直线专名线，书名画波浪线（书名号样式）；已收录的实体是 /item/<id> 链接，悬停或聚焦弹出摘要卡（取法同详情页 transport.getItem），Esc 收起。

import { EntityText, adaptEntityJson } from 'book-index-ui';

const spans = adaptEntityJson(entityJson);   // entity.json → EntitySpan[]；格式定稿后只改这一层
<EntityText text={paragraph} entities={spans} offsets="plain" plainBase={0}
            transport={storage} onNavigate={(id, e) => { e.preventDefault(); router.push(`/item/${id}`); }} />

entity.json 的 span 是纯字偏移（不计标点空白），配 offsets="plain"；正文只是整卷一段时用 plainBase 给出本段起点。book-index://Work/<id> 等 URI 由 bookIndexUriToId 转站内 id。一页铺很多段时设 injectStyles={false}，在页面上放一次 <style>{ENTITY_TEXT_CSS}</style>。

数据层（book-index-ui/storage）

数据层还导出 encodeId / decodeId / smartDecode / extractType / shardOf / scoreEntry / rankByRelevance / cleanName 等纯函数工具。

界面文字与繁简（overview#337）

两类文字，两条路：

• 字典按区域分文件：src/i18n/messages/<区域>.ts，defineMessages(繁体栏, 简体栏, 英文栏?)，繁简两栏键必须一一对应（tsc 检查）；早期的整块字典 locales/zh-Hant.ts／zh-Hans.ts 仍可用。
• 键是带类型的点路径（MessageKey），写错 tsc 报错；当前语言缺键回落到繁体。
• 没包 LocaleProvider 时按繁体。网站务必在最外层包 LocaleProvider（或网站的 BimLocaleProvider），否则组件一律显示繁体。
• 组件外（Next.js generateMetadata 等服务端）：getT(locale)('…')，数据文字用同一个转换函数（LocaleProvider 的 converter 或内置 opencc）。
• 加英文：Locale 加 'en'，各字典填英文栏（可部分，缺的回落繁体）；数据文字的英文另议。
• 检测：tests/unit/zh-hans-leak.test.tsx 在简体模式下渲染各页，用 findTraditionalChars（常用繁体字表 + 专名白名单）断言正文无繁体残留；tests/unit/i18n-dictionaries.test.ts 检查字典繁简同形、简体栏无繁体。

类型

IndexEntry / IndexDetailData / WorkDetailData / BookDetailData / CollectionDetailData / EntityDetailData / IndexType / IndexStatus / LineageGraph / CollatedEditionIndex / ResourceCatalog 等。

最小用法

1. 用 GithubStorage 直接渲染索引（浏览器）

import { IndexBrowser, GithubStorage, LocaleProvider } from 'book-index-ui';
import 'book-index-ui/styles';

const transport = new GithubStorage({
    org: 'open-guji',
    repos: { draft: 'book-index-draft', official: 'book-index' },
});

export default function App() {
    return (
        <LocaleProvider>
            <IndexBrowser
                transport={transport}
                onEntryClick={entry => console.log('clicked', entry.id)}
            />
        </LocaleProvider>
    );
}

2. 仅用数据层（Node 环境，例如 build script）

import { BookIndexManager } from 'book-index-ui/storage';

const mgr = new BookIndexManager('/workspace');
const item = await mgr.getItem('1evgowbkc2qyo');
console.log(item?.title);

3. 自定义 storage 后端（VS Code 扩展、Electron 等）

import type { IndexStorage, IndexEntry, PageResult, LoadOptions } from 'book-index-ui';

class MyStorage implements IndexStorage {
    async loadEntries(type, options): Promise<PageResult<IndexEntry>> { ... }
    async getItem(id): Promise<Record<string, unknown> | null> { ... }
    // ... 实现 IndexStorage 全部必选方法
}

参考 kaiyuanguji-web/nextjs/src/lib/local-api-storage.ts（浏览器 → Next.js API 路由）和 guji-platform/src/storage/VscodeStorage.ts（VS Code 文件系统）。

4. 宿主接入要点（手机 / 无障碍，2026-09-28）

• 搜索结果是真链接：IndexBrowser 的结果卡片是 <a href>，href 由 BidUrlProvider 的 buildUrl 生成（默认 /book-index?id=…），站点路由不同时务必包一层 Provider。普通左键点击仍调 onEntryClick 走客户端路由；Ctrl / Cmd / Shift / 中键交给浏览器（新标签、复制链接）。不传 onEntryClick 则按 href 整页跳转。
• 反馈浮钮 FeedbackButton：
  • 层级取 --bim-feedback-fab-z（默认 40），低于抽屉与弹层；也可传 zIndex prop。
  • 挂载且未隐藏时在 <html> 上写 --bim-feedback-fab-offset（浮钮占掉的底部高度）。正文容器写 padding-bottom: var(--bim-feedback-fab-offset, 0px)，右下角内容就不会被盖住。
  • hidden prop：移动端菜单 / 抽屉打开时传 true，浮钮与留白一起撤掉。

数据约定

book-index-ui 读写的数据格式与 Python 端 book-index-manager CLI 完全一致。详见 根 README 的"存储结构"和"Manager API 对照表"。

关键约束：文件名清洗（cleanName）的 CJK 范围 TS/Python 必须一致——见 tests/unit/cleanName.test.ts 的跨语言 fixture。

开发

npm install
npm run dev          # vite dev server（开发组件）
npm run test         # vitest 单元测试
npm run test:e2e     # Playwright E2E
npm run build:lib    # 输出 dist/ 给 npm 发布

许可

Apache 2.0

schema-v2 派生字段（overview#458）

详情页（BookDetailLayout 及其下各页）直接读 build 产物的 _ 字段，没有中间的归一／兼容层：

卡片里 {id, h:1} 的枢纽引用没有 title，名称取自 _hubs.json：IndexStorage.getHubs?() 提供（BundleStorage 默认读 ${basePath}/_hubs.json，可用 hubsPath 改相对路径）；不提供时枢纽引用无名，页面回退显示 ID。BookDetailLayout 会给传入的 transport 套一层 withHubTitles（只补枢纽卡的 title，不改字段形状）。夹具取自 book-index schema-v2 的 build/contract-sample/（tests/unit/fixtures/contract-sample/）。

tests/unit/DerivedGolden.test.tsx 用 tests/unit/fixtures/derived-golden/（真实 build 产物里挑的 47 个样本）逐字节比对整页渲染，改页面后输出有意变化时才重新生成（见该测试文件头部）。