book-index-ui 0.66.1 → 0.66.2-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -25,7 +25,9 @@ import 'book-index-ui/styles' // 旧入口=tokens.css + theme
25
25
 
26
26
  1. 先 `import 'book-index-ui/tokens.css'`;
27
27
  2. 再在自己的 `:root` 里**只覆盖品牌相关的变量**(朱色一族、字体、页面底色等);覆盖声明须在 tokens.css 之后加载;
28
- 3. 不要重写整套 `--bim-*`,也不要写 `.bim-*` 结构选择器去改组件内部——要调的东西都应该有变量,没有就提需求加变量。
28
+ 3. (有调色板时,第 2 步改为覆盖 `--bim-palette-*`,见下)不要重写整套 `--bim-*`,也不要写 `.bim-*` 结构选择器去改组件内部——要调的东西都应该有变量,没有就提需求加变量。
29
+
30
+ **调色板(推荐给有自己品牌色的宿主)**:`tokens.css` 之后再 `import 'book-index-ui/palette.css'`,然后在 `:root` 里**只覆盖约 20 个 `--bim-palette-*`**(`paper` `raise` `tint` `tint-2` `ink` `ink-2` `ink-3` `aux` `accent` `accent-deep` `gold` `gold-ink` `blue` `blue-soft` `purple` `purple-soft` `green` `amber` `red` `book` `shade`)。语义变量(链接、类型徽章、警告条、高亮、分隔线……)全部由调色板推出,不必逐个重写;宿主有自己的令牌体系时把调色板接过去,换主题自动跟随。不引 `palette.css` 则保持 `tokens.css` 的默认值(VS Code 扩展等不受影响)。调色板的名字与默认值、推导关系见 `src/styles/tokens.ts` 的 `BIM_PALETTE` / `BIM_PALETTE_MAP`。
29
31
 
30
32
  内置主题(indigo、ink)在 `themes.css`,用 `<html data-theme="…">` 切换;宿主自己用品牌色接管的,不必引。版式(`data-layout="boxed"`,界栏)在 tokens.css 里。
31
33
 
@@ -49,19 +51,16 @@ import 'book-index-ui/styles' // 旧入口=tokens.css + theme
49
51
  | 组件 | 用途 |
50
52
  |---|---|
51
53
  | `IndexBrowser` | 完整索引浏览器:搜索框 + 分类 tab + 推荐 + 最近浏览 |
52
- | `IndexView`(`book-index-ui/editor`) | **已弃用**:旧版查看/编辑合一视图,随编辑态拆到 `book-index-ui/editor` |
53
- | `IndexDetail` | **已弃用**:旧版详情纯渲染(2026-09 重构前),仅为兼容旧宿主,不再维护 |
54
54
  | `BookDetailLayout` | 详情页外壳:Tab(基本信息/整理本/全文/反馈)+ 路由到下面四个 Page;kaiyuanguji-web 用它 |
55
55
  | `WorkPage` / `BookPage` / `CollectionPage` / `EntityPage` | **现行详情页**(2026-09 版式重构):作品 / 版本 / 丛编 / 人物 |
56
56
  | `primitives`(`PageFrame`、`SectionHead`、`DataTable`、`Chip` …) | 四个 Page 共用的版式原语与 `DETAIL_CSS` |
57
57
  | `deriveEra` / `deriveDating` / `buildVersionTable` … | `core/detail-model.ts` 的数据派生层(刊刻年代、角色归一、版本表) |
58
+ | `MetaHomeView` / `ReadHomeView` | 元数据首页/阅读首页(取代已删除的旧 `HomePage`) |
58
59
  | `WorkCatalog` | 作品目录 |
59
60
  | `IndexEditor`、`ResourceEditor`、`SourceEditor`、`RelationPanel`、`EntitySelector`、`CreateEntityDialog`、`EntityPickerDialog` | 编辑态,**在子入口 `book-index-ui/editor`**(0.66 起不再从主入口导出;写入需 storage 实现 saveItem) |
60
- | `HomePage` | **已弃用**:旧版五页签首页,请用 `MetaHomeView`/`ReadHomeView` |
61
61
  | `TextReader` | **统一阅读器**(overview#307):整理本与全文合一,版本下拉含全部版本,取数走 `core/text-api`(只认新结构),见下「统一阅读器」 |
62
62
  | `ReaderShell` / `ReaderToc` / `ImagePanel` / `ReaderMdText` | 阅读器(整理本与全文共用),见下「阅读器」 |
63
63
  | `CollectionCatalog` | 丛编目录(按册/卷分组) |
64
- | `EmendatedBySection` | "校勘自" 引用列表 |
65
64
  | `VersionLineageView` / `VersionLineageGraph` | 版本传承图(dagre + xyflow) |
66
65
  | `FeedbackButton` / `FeedbackList` / `FeedbackForm` / `FeedbackTab` | 反馈组件。`FeedbackTab` 不直接发请求:走 `IndexStorage.listFeedback/submitFeedback`,没有就按 `feedbackApiUrl` 用 `createFeedbackTransport(url)` |
67
66
  | `LocaleProvider` / `LocaleToggle` | 繁简切换 |
@@ -69,6 +68,10 @@ import 'book-index-ui/styles' // 旧入口=tokens.css + theme
69
68
  | `useT` / `useConvert` | 旧 hook(整本字典 / 繁简转换),新代码用 `useI18n` |
70
69
  | `findTraditionalChars` | 简体模式残留繁体字检测(vitest 与网站 e2e 共用) |
71
70
 
71
+ ### 阅读器插件(`TextReader` 的 `plugins`)
72
+
73
+ 宿主把站点功能写成 `ReaderPlugin` 对象传给 `TextReader`,不要再用选择器抓阅读器 DOM。钩子:`onChapter`、`settings`、`toolbar`、`decorate`、`onCell`、`selectionActions`、`overlay`;`ReaderApi` 提供 `locate/scrollTo/rectOf/refresh/prefs/t/convert`。`decorate`/`onCell`/`selectionActions`/`locate({cp})` 只对有逐字格位的对读章生效。完整接口见 `src/components/Reader/plugins.ts` 与 DESIGN.md。
74
+
72
75
  ### 统一阅读器(`TextReader`,overview#307)
73
76
 
74
77
  ```tsx
@@ -81,7 +84,7 @@ import 'book-index-ui/styles' // 旧入口=tokens.css + theme
81
84
  ```
82
85
 
83
86
  - 数据模型(规格 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` 已实现。
84
- - **只认新结构**(用户 09-30 定):条目没有 `manifest.json`(含旧的 `collated_edition/`、`full_text/…` 目录)就显示「暂无文本」,不从旧目录合成。旧的 `CollatedEdition`/`BookFullText` 暂留给还没迁移的页面,迁移在正式站验完后清掉。
87
+ - **只认新结构**(用户 09-30 定):条目没有 `manifest.json`(含旧的 `collated_edition/`、`full_text/…` 目录)就显示「暂无文本」,不从旧目录合成。旧的 `BookFullText` 已删;`CollatedEdition.tsx` 现在只是整理本章渲染模块(`JuanReading`/`JuanRail`/`useCrossJuanSearch`),不导出整页组件。
85
88
  - 界面:工具条一个「版本」下拉按 manifest 顺序列全部版本(含整理本),只有一份时只在书名后标来源名;正文末尾显示所选版本的出处与授权;章有 json 用结构化渲染(条目、作品链接、跨章搜索),否则按 md;切版本尽量停在同一章号,对不上回第一章。
86
89
  - 组件不改 URL:宿主在 `onLocationChange` 里改地址(新 URL:`/read/<id>[/<key>][/<章>]`,主版本不写 key)。`versionKey/chapter` 传了就受控;传了无效值时组件回落并以 `auto` 通知。
87
90
  - 工具条另有上一章/下一章(窄屏隐去,翻卷交给正文底部的翻页卡片)、书名链接回条目页;窄屏(右栏藏起来)时正文末尾有「报告错字」入口。
@@ -91,13 +94,15 @@ import 'book-index-ui/styles' // 旧入口=tokens.css + theme
91
94
  整理本与全文共用一个外壳 `ReaderShell`:
92
95
 
93
96
  - 布局:**书影在正文左边**,目录在最左。宽屏(≥1100px)目录是可收起的侧栏(默认展开);更窄时是抽屉(默认收起,选卷后自动合上,Esc 关闭,打开时 Tab 圈在抽屉内);窄屏(≤719px)书影区不显示,只留正文。
94
- - 工具条(吸顶)只用文字与图标:目录、繁|简、A− A+、「阅读设置」键(overview#463)。其余偏好收进**右侧「阅读设置」侧栏**(≥860px 右侧可折叠栏;窄屏是底栏「设置」打开的底部抽屉),分三组:文字(字体、字号、繁简)、标注(专名线,对读时加标点)、版面(自然段、标出作品链接、书影、对读留白,竖排预留 `allowVertical`)。宿主通过阅读器插件(`TextReader` 的 `plugins`,`ReaderPlugin.settings`)往侧栏塞自己的控件;0.66 已删旧插槽 `settingsExtra`/`settingsAnnotate`/`settingsLayout`/`toolbarExtra`。字体选项只有宋体(默认,沿用 `--bim-font-reading`)/楷体/系统默认(无衬线),全是系统已装字体,不加载网络字体;楷体栈 `Kaiti SC → Kaiti TC → STKaiti → KaiTi → AR PL UKai CN → Noto Serif CJK SC → serif`。
97
+ - 工具条(吸顶)只用文字与图标:目录、繁|简、A− A+、「阅读设置」键(overview#463)。其余偏好收进**右侧「阅读设置」侧栏**(≥860px 右侧可折叠栏;窄屏是底栏「设置」打开的底部抽屉),分三组:文字(字体、字号、繁简)、标注(专名线,对读时加标点)、版面(自然段、标出作品链接、书影、对读留白,竖排预留 `allowVertical`)。宿主通过阅读器插件(`TextReader` 的 `plugins`,`ReaderPlugin.settings`)往侧栏塞自己的控件,接口说明见 DESIGN.md「阅读器」;0.66 已删旧插槽 `settingsExtra`/`settingsAnnotate`/`settingsLayout`/`toolbarExtra`。字体选项只有宋体(默认,沿用 `--bim-font-reading`)/楷体/系统默认(无衬线),全是系统已装字体,不加载网络字体;楷体栈 `Kaiti SC → Kaiti TC → STKaiti → KaiTi → AR PL UKai CN → Noto Serif CJK SC → serif`。
95
98
  - 正文:`--bim-font-reading`(宋体,默认接 `--bim-font-serif`,宿主覆盖后者即可)18px、行高 2.05(手机端同样),`line-break: strict` 避头尾;界面黑体。
96
99
  - 无障碍:第一个可聚焦元素是「跳到正文」;目录用游走 tabindex,几百卷也只有当前卷进 Tab 序列(↑↓ Home End 移动)。
97
100
  - 偏好(字号、字体、自然段、专名线…)存 `localStorage['bim-reader-prefs']`,首帧用默认值,SSR 安全。
98
101
  - 宿主若有吸顶导航,设 `--bim-reader-top`(如 `60px`)。
99
102
 
100
- 书影接口:`TextReader` 的 `resolveImages(chapterKey)` 返回当卷的 `ReaderPageImage[]`(可异步)——每页一张图,URL 由宿主给,可带 `width/height` 与逐字框 `boxes`(暂定格式 `bim-charbox-v0`:原图像素坐标 `x/y/w/h`,可选 `char`/`textOffset`/`confidence`)。其他格式的框设 `boxFormat` 并用 `renderImageOverlay` 自己画,这是与 CV 交付格式对齐前的扩展点。没有影像时书影区默认收起(`imagePanel="auto"`),点工具条「书影」可看占位。
103
+ 书影接口(推荐):给 `TextReader` 一个 `resolveFacsimile(bookId, vol)`,返回该 IIIF 册的 `ReaderPageImage[]`——阅读器自己按章条目的 cord 找出册号再调它,宿主不必碰 `loadReaderFiles`/`iiifVolumeOf`。需要完全接管时用下面的 `resolveImages`(优先于 `resolveFacsimile`)。
104
+
105
+ 书影接口(接管):`TextReader` 的 `resolveImages(chapterKey)` 返回当卷的 `ReaderPageImage[]`(可异步)——每页一张图,URL 由宿主给,可带 `width/height` 与逐字框 `boxes`(暂定格式 `bim-charbox-v0`:原图像素坐标 `x/y/w/h`,可选 `char`/`textOffset`/`confidence`)。其他格式的框设 `boxFormat` 并用 `renderImageOverlay` 自己画,这是与 CV 交付格式对齐前的扩展点。没有影像时书影区默认收起(`imagePanel="auto"`),点工具条「书影」可看占位。
101
106
 
102
107
  版本下拉框(overview#235,同一 owner 有多份全文时用):`ReaderShell` 的四个 props——
103
108
 
@@ -110,7 +115,9 @@ import 'book-index-ui/styles' // 旧入口=tokens.css + theme
110
115
 
111
116
  配套两个导出(`book-index-ui` 根入口与 `components/Reader`):`readerVersionsFromFullText(entries)` 把 book-text 的 `WorkFullTextEntry[]` 换成 `ReaderVersion[]`(顺序不变,清单已按「哪份最好」排好);`pickReaderVersion(versions, key?)` 给出当前选中的一份(key 有效用它,否则 primary,再否则第一份),宿主用它决定该载入哪份 toc / 正文。
112
117
 
113
- **`resolveImages` 要用 `useCallback`(或模块级函数)包一层**:组件按 `[resolveImages, 当前卷]` 重新取书影,每次渲染都传一个新函数会反复请求。
118
+ 插件接口里的定位与修饰(`ReaderApi`):`locate({ cp })` 的 `cp` 是**格序**(`api.cells` 的下标,阅读顺序,从 0 数),不是全章码点偏移(网站旧版 DOM 的 `data-ft-cp`);按内容定位用 `locate({ text })`。整理本、Markdown 等无逐字格位的章,`api.cells` 为空,`api.textCells` 给出按渲染文字数出的格(anchor `t:<序>:1`),`decorate` 以它为 key 即可修饰(`tone`/`bg`/`fg`/`underline`/`focus`,经 CSS Custom Highlight API 画,不改 DOM;`sub`/`insertAfter`/`title` 在这类章里不支持)。
119
+
120
+ **`resolveImages`/`resolveFacsimile` 要用 `useCallback`(或模块级函数)包一层**:组件按 `[resolveImages, 当前卷]` 重新取书影,每次渲染都传一个新函数会反复请求。
114
121
 
115
122
  ### 正文实体标注(`EntityText`,overview#389)
116
123