book-index-ui 0.2.20 → 0.2.22
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 +123 -0
- package/dist/index.cjs +3 -3
- package/dist/index.d.ts +24 -0
- package/dist/index.js +1847 -1808
- package/dist/storage-entry-C7sHSk4U.cjs +1 -0
- package/dist/{storage-entry-Ysz_rfdh.js → storage-entry-Cn1-iEHv.js} +13 -8
- package/dist/storage.cjs +1 -1
- package/dist/storage.d.ts +3 -0
- package/dist/storage.js +1 -1
- package/package.json +11 -2
- package/dist/storage-entry-D6KFK-rC.cjs +0 -1
package/README.md
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
# book-index-ui
|
|
2
|
+
|
|
3
|
+
`book-index-manager` 的 React 组件库 + 存储客户端，发布为 npm 包 `book-index-ui`。
|
|
4
|
+
配合 [book-index-manager](https://github.com/open-guji/book-index-manager) 的 Python CLI 一起使用。
|
|
5
|
+
|
|
6
|
+
```bash
|
|
7
|
+
npm install book-index-ui
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## 包结构
|
|
11
|
+
|
|
12
|
+
两个独立入口：
|
|
13
|
+
|
|
14
|
+
```ts
|
|
15
|
+
import { ... } from 'book-index-ui' // React 组件 + 类型 + 数据层
|
|
16
|
+
import { ... } from 'book-index-ui/storage' // 仅数据层（无 React，体积小，适合 Node/Worker）
|
|
17
|
+
import 'book-index-ui/styles' // CSS（用到组件时引入）
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## 主要 export
|
|
21
|
+
|
|
22
|
+
### React 组件
|
|
23
|
+
|
|
24
|
+
| 组件 | 用途 |
|
|
25
|
+
|---|---|
|
|
26
|
+
| `IndexBrowser` | 完整索引浏览器：搜索框 + 分类 tab + 推荐 + 最近浏览 |
|
|
27
|
+
| `IndexView` | 单条目详情视图（基于 ID 拉数据 + 渲染） |
|
|
28
|
+
| `IndexDetail` | 详情视图的纯渲染（已有 detailData 时用） |
|
|
29
|
+
| `IndexEditor` | 详情编辑器（写入需 storage 实现 saveItem） |
|
|
30
|
+
| `HomePage` | 首页：推荐丛编 + 经典作品（kaiyuanguji-web 用） |
|
|
31
|
+
| `CollatedEdition` | 整理本（collated_edition）阅读 + 全文搜索 |
|
|
32
|
+
| `CollectionCatalog` | 丛编目录（按册/卷分组） |
|
|
33
|
+
| `EmendatedBySection` | "校勘自" 引用列表 |
|
|
34
|
+
| `VersionLineageView` / `VersionLineageGraph` | 版本传承图（dagre + xyflow） |
|
|
35
|
+
| `FeedbackButton` / `FeedbackList` / `FeedbackForm` | 反馈组件 |
|
|
36
|
+
| `LocaleProvider` / `LocaleToggle` | 繁简切换 |
|
|
37
|
+
| `useT` / `useConvert` | 繁简 hook |
|
|
38
|
+
|
|
39
|
+
### 数据层（`book-index-ui/storage`）
|
|
40
|
+
|
|
41
|
+
| 类 | 用途 |
|
|
42
|
+
|---|---|
|
|
43
|
+
| `BookIndexManager` | Facade：统一 `getItem/saveItem/deleteItem/generateId/...` |
|
|
44
|
+
| `BookIndexStorage` | 本地文件系统实现（Node / Electron） |
|
|
45
|
+
| `GithubStorage` | GitHub 只读 + jsdelivr CDN fallback（浏览器/CI 用） |
|
|
46
|
+
| `BundleStorage` | 同域预打包数据读取（kaiyuanguji-web 生产模式） |
|
|
47
|
+
| `LocalStorage` | `BookIndexStorage` 的薄包装（兼容历史 API） |
|
|
48
|
+
| `IndexStorage` | 接口（自实现自定义后端时实现它） |
|
|
49
|
+
|
|
50
|
+
数据层还导出 `encodeId / decodeId / smartDecode / extractType / shardOf / scoreEntry / rankByRelevance / cleanName` 等纯函数工具。
|
|
51
|
+
|
|
52
|
+
### 类型
|
|
53
|
+
|
|
54
|
+
`IndexEntry` / `IndexDetailData` / `WorkDetailData` / `BookDetailData` / `CollectionDetailData` / `EntityDetailData` / `IndexType` / `IndexStatus` / `LineageGraph` / `CollatedEditionIndex` / `ResourceCatalog` 等。
|
|
55
|
+
|
|
56
|
+
## 最小用法
|
|
57
|
+
|
|
58
|
+
### 1. 用 GithubStorage 直接渲染索引（浏览器）
|
|
59
|
+
|
|
60
|
+
```tsx
|
|
61
|
+
import { IndexBrowser, GithubStorage, LocaleProvider } from 'book-index-ui';
|
|
62
|
+
import 'book-index-ui/styles';
|
|
63
|
+
|
|
64
|
+
const transport = new GithubStorage({
|
|
65
|
+
org: 'open-guji',
|
|
66
|
+
repos: { draft: 'book-index-draft', official: 'book-index' },
|
|
67
|
+
});
|
|
68
|
+
|
|
69
|
+
export default function App() {
|
|
70
|
+
return (
|
|
71
|
+
<LocaleProvider>
|
|
72
|
+
<IndexBrowser
|
|
73
|
+
transport={transport}
|
|
74
|
+
onEntryClick={entry => console.log('clicked', entry.id)}
|
|
75
|
+
/>
|
|
76
|
+
</LocaleProvider>
|
|
77
|
+
);
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### 2. 仅用数据层（Node 环境，例如 build script）
|
|
82
|
+
|
|
83
|
+
```ts
|
|
84
|
+
import { BookIndexManager } from 'book-index-ui/storage';
|
|
85
|
+
|
|
86
|
+
const mgr = new BookIndexManager('/workspace');
|
|
87
|
+
const item = await mgr.getItem('1evgowbkc2qyo');
|
|
88
|
+
console.log(item?.title);
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
### 3. 自定义 storage 后端（VS Code 扩展、Electron 等）
|
|
92
|
+
|
|
93
|
+
```ts
|
|
94
|
+
import type { IndexStorage, IndexEntry, PageResult, LoadOptions } from 'book-index-ui';
|
|
95
|
+
|
|
96
|
+
class MyStorage implements IndexStorage {
|
|
97
|
+
async loadEntries(type, options): Promise<PageResult<IndexEntry>> { ... }
|
|
98
|
+
async getItem(id): Promise<Record<string, unknown> | null> { ... }
|
|
99
|
+
// ... 实现 IndexStorage 全部必选方法
|
|
100
|
+
}
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
参考 `kaiyuanguji-web/nextjs/src/lib/local-api-storage.ts`（浏览器 → Next.js API 路由）和 `guji-platform/src/storage/VscodeStorage.ts`（VS Code 文件系统）。
|
|
104
|
+
|
|
105
|
+
## 数据约定
|
|
106
|
+
|
|
107
|
+
`book-index-ui` 读写的数据格式与 Python 端 `book-index-manager` CLI 完全一致。详见 [根 README](../README.md) 的"存储结构"和"Manager API 对照表"。
|
|
108
|
+
|
|
109
|
+
**关键约束**：文件名清洗（`cleanName`）的 CJK 范围 TS/Python 必须一致——见 [tests/unit/cleanName.test.ts](tests/unit/cleanName.test.ts) 的跨语言 fixture。
|
|
110
|
+
|
|
111
|
+
## 开发
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
npm install
|
|
115
|
+
npm run dev # vite dev server（开发组件）
|
|
116
|
+
npm run test # vitest 单元测试
|
|
117
|
+
npm run test:e2e # Playwright E2E
|
|
118
|
+
npm run build:lib # 输出 dist/ 给 npm 发布
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## 许可
|
|
122
|
+
|
|
123
|
+
Apache 2.0
|