book-index-ui 0.6.4 → 0.7.2

package/dist/index.d.ts

@@ -141,7 +141,7 @@ export declare interface BookDetailLayoutProps {
     onNavigate?: (id: string) => void;
     onBack?: () => void;
     backLabel?: string;
-    renderLink?: (id: string, label?: string) => default_2.ReactNode;
+    renderLink?: RenderLink;
     /** 加载 detail 后的额外加工（如注入 digital_assets） */
     enrichDetail?: (entry: IndexEntry, detail: IndexDetailData) => void;
     /** 当前 tab 的源文件链接解析器 */
@@ -151,23 +151,20 @@ export declare interface BookDetailLayoutProps {
     } | null;
     /** 注入额外 tab（如 kyg 的「数字化」） */
     extraTabs?: ExtraTab[];
-    /** 是否显示内置反馈 tab，默认 true。设为 false 时调用方可用 extraTabs 自定义。 */
     showFeedbackTab?: boolean;
-    /** 反馈 API 端点（默认 `/api/feedback`） */
     feedbackApiUrl?: string | (() => string);
-    /** 整个组件的外层高度（默认 100vh） */
+    /**
+     * 最小高度。旧版这里是「固定高度 + 内滚动」，现已改为文档流，
+     * 只用来保证短内容时页面不塌陷。
+     */
     height?: string;
-    /** 桌面侧边栏宽度（默认 144 — 对应 Tailwind w-36） */
-    sideNavWidth?: number;
-    /** 内容区域最大宽度（默认 1024） */
-    contentMaxWidth?: number;
-    /** 是否在加载/未找到状态下隐藏整体导航（默认 false：仍显示返回链接） */
-    hideNavWhenLoading?: boolean;
+    /** 页脚左侧附加内容（如站点的引用信息条） */
+    footerExtra?: default_2.ReactNode;
     className?: string;
     style?: default_2.CSSProperties;
 }
 
-export declare type BookDetailTabKey = 'basic' | 'collated' | 'fulltext' | 'lineage' | 'emendated' | 'feedback' | string;
+export declare type BookDetailTabKey = 'basic' | 'collated' | 'fulltext' | 'lineage' | 'feedback' | string;
 
 /**
  * Book 全文 viewer：左侧章节列表 + 右侧 markdown 渲染。
@@ -371,6 +368,55 @@ export declare interface BookLineage {
     note?: string;
 }
 
+export declare const BookPage: default_2.FC<BookPageProps>;
+
+export declare interface BookPageProps {
+    data: BookDetailData;
+    transport?: IndexStorage;
+    onNavigate?: (id: string) => void;
+    renderLink?: RenderLink;
+}
+
+export declare function Breadcrumb({ items }: {
+    items: {
+        label: string;
+        onClick?: () => void;
+        href?: string;
+    }[];
+}): JSX.Element;
+
+export declare interface BucketedResources {
+    buckets: ResourceBucket[];
+    mirrors: MirrorGroup[];
+    /** 合并分册后的总数，用于「N 个资源」计数 */
+    total: number;
+}
+
+/**
+ * 把资源按类型分桶（文字全文库 / 影印资源 / 图文对照 / 馆藏），
+ * 并把同源镜像组（resource_groups）单独拎出来。
+ *
+ * 先合并分册系列——御定佩文韻府 23 条「第N冊」在分桶前必须先并成 1 条，
+ * 否则「影印資源」栏会出现 23 行一模一样的名字。
+ */
+export declare function bucketResources(items: ResourceEntry[] | undefined, groups?: Record<string, ResourceGroupInfo>): BucketedResources;
+
+/**
+ * 构造丛编「收錄書籍」表。
+ *
+ * 三级数据源，按信息量降序：
+ *   1. volume_book_mapping.json —— 含部类/册次/缺册/附属子目，但生产仓只有 7 份
+ *   2. contained_works[] —— 含标题与册次，29 部丛编有（其中 16 部带 volume_index）
+ *   3. books[] —— 只有 ID，需逐条 getItem 才能拿标题
+ *
+ * 优先级很重要：武英殿聚珍版有 144 条 contained_works（自带标题+册次），
+ * 走第 2 级就能直接渲染，不必对 books[] 发 144 次请求。
+ */
+export declare function buildCollectionTable(coll: CollectionDetailData, catalog?: VolumeBookMapping | null, resolvedBooks?: Map<string, {
+    title?: string;
+    edition?: string;
+}>): CollectionTable;
+
 export declare function buildId(status: IndexStatus, type: IndexType, timestamp: bigint, machineId: number, sequence: number): bigint;
 
 /**
@@ -384,12 +430,19 @@ export declare function buildId(status: IndexStatus, type: IndexType, timestamp:
  */
 export declare function buildLineageGraph(work: WorkDetailData, books: BookDetailData[], collection?: string): LineageGraph;
 
+/** 构造跳到指定页的 URL（目前只有 Wikimedia Commons 支持页内导航） */
+export declare function buildPageUrl(baseUrl: string, pageNum: number): string;
+
 /**
  * 把原始 JSON 转成 draft_id → production_id 的扁平 Map，用于 redirect 查表。
  * 容错：缺字段、版本号不匹配都按空映射处理（log 一条 warn）。
  */
 export declare function buildPromotionMap(raw: unknown): Map<string, string>;
 
+export declare function buildVersionRow(v: ResolvedVersion, vg?: VersionGraph): VersionRow;
+
+export declare function buildVersionTable(versions: ResolvedVersion[], vg: VersionGraph | undefined, opts?: VersionTableOptions): VersionTable;
+
 /**
  * Bundle 只读 Storage 实现
  *
@@ -538,6 +591,19 @@ declare interface CatalogDivision {
     categories: CatalogCategory[];
 }
 
+/** 条目 chip（关联作品、别名、同作品其他版本…） */
+export declare function Chip({ children, href, onClick, title }: {
+    children: default_2.ReactNode;
+    href?: string;
+    onClick?: () => void;
+    title?: string;
+}): JSX.Element;
+
+/** chip 牆：自动换行 + 「更多 N」 */
+export declare function ChipWall({ children }: {
+    children: default_2.ReactNode;
+}): JSX.Element;
+
 /**
  * 文件名清洗：保留 ASCII 字母数字 + CJK 全范围。
  *
@@ -688,6 +754,11 @@ export declare interface CollectionCatalogProps {
 /** Collection 详情 */
 export declare interface CollectionDetailData extends BaseDetailData {
     type: 'collection';
+    /**
+     * 丛编子类：book_collection（书籍汇编，60 部）/ work_collection（作品集，15 部）。
+     * 数据里一直有，此前没在类型里声明。
+     */
+    subtype?: 'book_collection' | 'work_collection' | string;
     work_id?: string;
     contained_in?: string[];
     history?: string[];
@@ -699,6 +770,47 @@ export declare interface CollectionDetailData extends BaseDetailData {
     }[];
 }
 
+export declare const CollectionPage: default_2.FC<CollectionPageProps>;
+
+export declare interface CollectionPageProps {
+    data: CollectionDetailData;
+    /** 丛编目录档（由 layout 预加载，生产仓只有 7 部丛编有） */
+    catalog?: VolumeBookMapping | null;
+    transport?: IndexStorage;
+    onNavigate?: (id: string) => void;
+    renderLink?: RenderLink;
+    /** 完整目录 tab 的入口（由 layout 注入） */
+    catalogAction?: default_2.ReactNode;
+}
+
+export declare interface CollectionRow {
+    /** 链接目标（work_id 或 book_id）；无匹配时为空 */
+    id?: string;
+    title: string;
+    /** 部类（经史子集等），仅目录档有 */
+    section?: string;
+    /** 册号列表 */
+    volumes: number[];
+    /** 附属子目（如「附錄一卷」） */
+    subItems?: string[];
+    edition?: string;
+    /** 缺册统计（目录档有） */
+    found?: number;
+    expected?: number;
+}
+
+export declare interface CollectionTable {
+    rows: CollectionRow[];
+    /** 数据来源：catalog = 目录档（最全）；works = contained_works；books = 仅 ID */
+    source: 'catalog' | 'works' | 'books';
+    /** 可用的部类筛选项 */
+    sections: string[];
+    /** 全帙册数（目录档有） */
+    totalVolumes?: number;
+}
+
+export declare function computeVersionPartition(ids: string[], vg?: VersionGraph): VersionPartition;
+
 export declare class ConfigError extends BookIndexError {
     constructor(message?: string);
 }
@@ -752,17 +864,81 @@ export declare interface CreateEntityParams {
     inheritData?: Record<string, unknown>;
 }
 
+/** 空值占位「—」 */
+export declare function Dash(): JSX.Element;
+
+/** 表格容器：顶部墨线 */
+export declare function DataTable({ children }: {
+    children: default_2.ReactNode;
+}): JSX.Element;
+
 export declare const decodeId: typeof base36Decode;
 
 /** Decode an ID string and extract its components. Supports both base36 and legacy base58. */
 export declare function decodeIdString(encoded: string): IdComponents;
 
+export declare interface DerivedEra {
+    /** 朝代名（繁体），如「宋」「清」「日本」；推不出时为空串 */
+    era: string;
+    /** 年号或纪年文本，如「乾隆」「慶元」「1773」；推不出时为空串 */
+    reign: string;
+    source: EraSource;
+}
+
+/**
+ * 版本类型推断（写本 / 刻本 / 活字本…）。
+ * lineage.category 只有 1% 有，其余从题名尾缀猜。
+ */
+export declare function deriveEditionType(book: EraInferable): string;
+
+/**
+ * 推断一个版本的朝代 / 纪年。
+ *
+ * 三级回退，越靠前越可信：
+ *   1. lineage.year_text —— 人工整理的版本传承信息（仅 1% 有）
+ *   2. publication_info.year —— 著录的出版年（仅 2% 有）
+ *   3. edition ∥ title 的题名前缀与特征词 —— 覆盖约 96%，但是**推断**
+ *
+ * UI 必须依 source 区分显示（推断的加 hover 提示），不要让读者误以为
+ * 「宋 · 慶元」是著录事实。
+ */
+export declare function deriveEra(book: EraInferable): DerivedEra;
+
+/**
+ * 推断可排序的公元年份。
+ *
+ * 优先 lineage.year（人工著录），其次文本里的 4 位公元年，
+ * 最后用年号表折算「乾隆四十三年」→ 1736 + 43 - 1 = 1778。
+ */
+export declare function deriveYear(book: EraInferable): number | undefined;
+
 /** 描述信息 */
 export declare interface DescriptionInfo {
     text: string;
     sources?: string[];
 }
 
+/**
+ * 全局样式。用 class 前缀 bim-d- 避免与消费者站点冲突。
+ *
+ * 响应式全部在这里用 media query 表达：JS 侧不读 window 宽度，
+ * 于是 Next.js 服务端渲染出的 HTML 与客户端首帧完全一致。
+ */
+export declare const DETAIL_CSS = "\n.bim-d-page {\n  background: var(--bim-page-bg, #fbf9f3);\n  color: var(--bim-ink, #2a231c);\n  font-family: var(--bim-font-body, system-ui, sans-serif);\n  min-height: 100%;\n  padding-bottom: 64px;\n}\n.bim-d-main {\n  max-width: 1000px;\n  margin: 0 auto;\n  padding: 24px clamp(16px, 4vw, 28px) 0;\n}\n.bim-d-ui { font-family: var(--bim-font-ui, system-ui, sans-serif); }\n\n.bim-d-page a { color: var(--bim-accent, #9c3a2c); text-decoration: none; }\n.bim-d-page a:hover {\n  color: var(--bim-accent-deep, #6f2a20);\n  text-decoration: underline;\n  text-decoration-thickness: 1px;\n  text-underline-offset: 3px;\n}\n.bim-d-page ::selection { background: var(--bim-selection-bg, #ecdcbc); }\n\n/* \u8868\u683C\u884C */\n.bim-d-row { display: grid; align-items: center; padding: 9px 4px;\n  border-bottom: 1px solid var(--bim-rule, #eae2d0); font-size: 14px; }\n.bim-d-row:hover { background: var(--bim-row-hover-bg, #f5f1e5); }\n\n/* intro / \u6210\u5BF9\u533A\u5757\uFF1A\u5BBD\u5C4F\u4E24\u680F\uFF0C\u7A84\u5C4F\u5355\u680F */\n.bim-d-intro { display: grid; grid-template-columns: minmax(0, 1fr) 244px; gap: 30px;\n  padding: 20px 0 26px; border-bottom: 1px solid var(--bim-rule, #e4dbc9);\n  margin-bottom: 40px; align-items: start; }\n.bim-d-pair { display: grid; grid-template-columns: 1fr 1fr; gap: 34px;\n  align-items: start; margin-bottom: 48px; }\n.bim-d-pair-wide { grid-template-columns: 1fr 1.2fr; }\n\n@media (max-width: 719px) {\n  .bim-d-intro { grid-template-columns: 1fr; gap: 20px; margin-bottom: 32px; }\n  .bim-d-pair, .bim-d-pair-wide { grid-template-columns: 1fr; gap: 40px; }\n  /* \u8868\u683C\uFF1Ameta \u5217\u6298\u5230\u7B2C\u4E8C\u884C\uFF0C\u8868\u5934\u9690\u85CF */\n  .bim-d-thead { display: none !important; }\n  .bim-d-row { grid-template-columns: 22px 1fr !important; gap: 5px 10px !important;\n    align-items: baseline; padding: 10px 2px; }\n  .bim-d-row-meta { grid-column: 2; display: flex !important; flex-wrap: wrap;\n    gap: 4px 14px; font-size: 12px; }\n  .bim-d-h1 { font-size: 32px !important; }\n}\n";
+
+export declare function DetailFooter({ left, right }: {
+    left?: default_2.ReactNode;
+    right?: default_2.ReactNode;
+}): JSX.Element;
+
+/** 页头：大标题 + 副题 + 右上小字 + （可选）第二行 */
+export declare function DetailHeader({ title, subtitle, aside, secondLine }: {
+    title: default_2.ReactNode;
+    subtitle?: default_2.ReactNode;
+    aside?: default_2.ReactNode;
+    secondLine?: default_2.ReactNode;
+}): JSX.Element;
+
 /** IndexDetailData (结构化) → IndexEditorData (扁平化) */
 export declare function detailToEditor(data: IndexDetailData): IndexEditorData;
 
@@ -799,6 +975,12 @@ export declare function EmendatedBySection({ items, onNavigate, renderLink }: {
     renderLink?: (id: string, label?: string) => default_2.ReactNode;
 }): JSX.Element;
 
+/** 空状态说明（如「暫無版本著錄」） */
+export declare function EmptyNote({ children, action }: {
+    children: default_2.ReactNode;
+    action?: default_2.ReactNode;
+}): JSX.Element;
+
 export declare const encodeId: typeof base36Encode;
 
 export declare const EntityDetail: default_2.FC<EntityDetailProps>;
@@ -834,6 +1016,12 @@ export declare interface EntityDetailProps {
     onNavigate?: (id: string) => void;
     renderLink?: (id: string, label?: string) => default_2.ReactNode;
     headerExtra?: default_2.ReactNode;
+    /**
+     * 隐藏自带的标题块。
+     * 详情页外壳（BookDetailLayout）已经在 DetailHeader 里渲染了
+     * 姓名 / 朝代 / 生卒 / 类型，这里再渲一遍就是同一个名字出现两次。
+     */
+    hideHeader?: boolean;
 }
 
 /** 实体选项（搜索结果、最近使用等） */
@@ -846,6 +1034,15 @@ export declare interface EntityOption {
     dynasty?: string;
 }
 
+export declare const EntityPage: default_2.FC<EntityPageProps>;
+
+export declare interface EntityPageProps {
+    data: EntityDetailData;
+    transport?: IndexStorage;
+    onNavigate?: (id: string) => void;
+    renderLink?: RenderLink;
+}
+
 export declare const EntityPickerDialog: default_2.FC<EntityPickerDialogProps>;
 
 declare interface EntityPickerDialogProps {
@@ -886,6 +1083,34 @@ export declare interface EntityWorkRef {
     role?: string;
 }
 
+/**
+ * 推断函数只读这几个字段，故用结构类型而非完整 BookDetailData——
+ * 这样 ResolvedVersion（version 表的轻量投影）也能直接传进来。
+ */
+export declare interface EraInferable {
+    title?: string;
+    edition?: string;
+    lineage?: BookDetailData['lineage'];
+    publication_info?: BookDetailData['publication_info'];
+}
+
+export declare function eraRank(era: string): number;
+
+/** 推断出的朝代及其可信来源 */
+export declare type EraSource = 'lineage' | 'publication' | 'edition' | 'none';
+
+/**
+ * 可展开行（书目收录 / 考证）：＋/－ 方块 + 主行 + 展开内容。
+ * 展开内容缩进对齐主行文字，带浅色左线。
+ */
+export declare function ExpandRow({ open, onToggle, main, action, children }: {
+    open: boolean;
+    onToggle: () => void;
+    main: default_2.ReactNode;
+    action?: default_2.ReactNode;
+    children?: default_2.ReactNode;
+}): JSX.Element;
+
 /** Entity.external_ids —— 外部数据库引用 */
 export declare interface ExternalIds {
     cbdb_id?: number;
@@ -893,6 +1118,12 @@ export declare interface ExternalIds {
     cbdb_source?: string;
 }
 
+/** 外部链接（资源、机构） */
+export declare function ExtLink({ href, children }: {
+    href: string;
+    children: default_2.ReactNode;
+}): JSX.Element;
+
 /**
  * 从 URL 的域名中提取简短标识符
  */
@@ -924,6 +1155,39 @@ export declare interface ExtraTabContext {
     onNavigate?: (id: string) => void;
 }
 
+export declare interface Fact {
+    key: string;
+    label: string;
+    value: string;
+    /** 点击跳转（如「收入」跳父丛编、「著錄」滚到书目区） */
+    href?: string;
+    /** 内部条目 ID（渲染成 BidLink） */
+    linkId?: string;
+    /** 锚点（页内滚动） */
+    anchor?: string;
+    /** hover 提示（如「據版本題名推斷」） */
+    title?: string;
+}
+
+export declare interface FactItem {
+    label: string;
+    value: default_2.ReactNode;
+    /** hover 提示（如「據版本題名推斷」） */
+    title?: string;
+}
+
+/** facts 列表：左标签右值，带朱色左线 */
+export declare function FactList({ items, horizontal }: {
+    items: FactItem[];
+    /**
+     * 横排模式：没有简介正文时用（Book 的 description 只有 2.5% 有）。
+     * 此时标签与值改为上下堆叠——横排还左右对齐的话，标签和值之间会被
+     * 拉开一大段空白，读者要横扫半个屏幕才能把「冊次」和「第 321–343 冊」
+     * 对上号。
+     */
+    horizontal?: boolean;
+}): JSX.Element | null;
+
 export declare const FeedbackButton: default_2.FC<FeedbackButtonProps>;
 
 export declare interface FeedbackButtonProps {
@@ -1018,12 +1282,31 @@ declare interface FileSystem_2 {
 }
 export { FileSystem_2 as FileSystem }
 
+/** 筛选 chip（朝代、部类、分组）。选中态为朱红实心。 */
+export declare function FilterChip({ label, active, onClick, dashed }: {
+    label: string;
+    active?: boolean;
+    onClick?: () => void;
+    dashed?: boolean;
+}): JSX.Element;
+
+/**
+ * 把 `additional_titles` / `attached_texts` 这类
+ * `(string | { book_title })[]` 摊平成字符串数组。
+ */
+export declare function flattenTitles(items?: (string | {
+    book_title: string;
+})[]): string[];
+
 /**
  * 简单模板替换
  * formatTemplate('共 {n} 册', { n: 100 }) → '共 100 册'
  */
 export declare function formatTemplate(template: string, values: Record<string, string | number>): string;
 
+/** 格式化册号范围：连续用「321–343」，零散用逗号，过多用「a–b (N 冊)」 */
+export declare function formatVolumeRange(volumes: number[], unitVolume?: string): string;
+
 export declare const FormInput: default_2.FC<FormInputProps>;
 
 declare interface FormInputProps {
@@ -1042,6 +1325,14 @@ declare interface FormTextAreaProps {
     placeholder?: string;
 }
 
+/** 从 URL 提取域名并映射为显示名称 */
+export declare function getDisplayNameFromUrl(url: string): string | undefined;
+
+/** Extract the start page number from metadata (page_range or file_page_range) */
+export declare function getStartPage(metadata?: Record<string, unknown>): number | undefined;
+
+export declare function getTypeGroupKey(types: ResourceTypeAtom[]): string;
+
 /**
  * GitHub 只读 Storage 实现
  *
@@ -1135,6 +1426,12 @@ export declare interface GithubStorageConfig {
     timeout?: number;
 }
 
+/** 方形字形徽章（版·源·目·考·續·叢·收·作） */
+export declare function GlyphBadge({ char, tone }: {
+    char: string;
+    tone?: 'accent' | 'ink';
+}): JSX.Element;
+
 /** 统一搜索结果（按类型分组） */
 export declare interface GroupedSearchResult {
     works: IndexEntry[];
@@ -1148,6 +1445,15 @@ export declare interface GroupedSearchResult {
     totalEntities?: number;
 }
 
+/**
+ * 把 related_works 按 relation 分成 5 桶。
+ *
+ * 现有 IndexDetail 只识别 4 种 relation，剩下 8 种（contains_text_of 4231 条、
+ * collected_in 3376 条、studies 304 条…）全落进「相關作品」兜底桶，
+ * 语义全丢。这里覆盖生产仓里出现过的全部 12 种。
+ */
+export declare function groupRelatedWorks(items: RelatedWorkRef[]): RelatedGroup[];
+
 export declare const HomePage: default_2.FC<HomePageProps>;
 
 export declare interface HomePageProps {
@@ -1289,6 +1595,16 @@ export declare interface IndexedByEntry {
     author_info?: string;
     /** 收录时的版本信息，如"內府藏本" */
     edition?: string;
+    /**
+     * 在该书目中的门类，如"六藝略／春秋"。
+     * 抽样 2480 部作品中 21.6% 有此字段，此前一直没在类型里声明，
+     * 于是详情页读不到、也就从没展示过。
+     */
+    section?: string;
+    /** section 的判定依据（整理时记录的推理过程，一般不展示） */
+    section_basis?: string;
+    /** 出处页码，如"KR2a0007_WYG_030-12b"（抽样 8.6% 有） */
+    page?: string;
     /** 提要/摘要 */
     summary?: string;
     /** 编者评论 */
@@ -1584,6 +1900,12 @@ export declare interface IndexViewProps {
     style?: default_2.CSSProperties;
 }
 
+/** intro 区：左正文 + 右 facts */
+export declare function IntroGrid({ children, facts }: {
+    children?: default_2.ReactNode;
+    facts?: default_2.ReactNode;
+}): JSX.Element;
+
 /** 卷数 */
 export declare interface JuanCount {
     number?: number;
@@ -1695,6 +2017,12 @@ export declare type LineageSiblingRelation = '兄弟本' | '同源' | '互校' |
 /** 版本现存状态 */
 export declare type LineageStatus = 'extant' | 'fragment' | 'lost';
 
+/** 链接渲染上下文。消费者可据此调整样式，如表格里不显示类型图标。 */
+export declare interface LinkContext {
+    /** 位于成列的表格/列表中——整列同类型时图标只是噪音 */
+    dense?: boolean;
+}
+
 /** 加载选项 */
 export declare interface LoadOptions {
     page?: number;
@@ -1845,6 +2173,8 @@ export declare interface LocaleMessages {
         containedWorks: string;
         adaptations: string;
         derivativeWorks: string;
+        /** 本作品所研究/注解的对象（relation: studies / preceded_by） */
+        studies: string;
     };
     relation: {
         belongsToWork: string;
@@ -1908,6 +2238,13 @@ export declare interface LocaleMessages {
         collectionCatalog: string;
         collatedEdition: string;
         catalogSuffix: string;
+        fullText: string;
+        lineage: string;
+        feedback: string;
+        dataSource: string;
+        backToIndex: string;
+        submitVersion: string;
+        dataLicense: string;
     };
     metadata: Record<string, string>;
     editor: {
@@ -2099,10 +2436,31 @@ declare interface Measure {
     note?: string;
 }
 
+/** 计量文本：measure_info 优先（70% 有），回退 juan_count */
+export declare function measureText(detail: Partial<IndexDetailData>, juanUnit?: string): string;
+
+/**
+ * 将同名模式的分册资源自动合并为一条带 volumes 的资源。
+ *
+ * 匹配「XXX·第N冊」与「XXX (N)」「XXX·N」两种命名；≥2 册才合并，
+ * 免得把「史記 (1)」这种孤例也变成一个空壳分册组。
+ *
+ * 御定佩文韻府就是典型：23 条「摛藻堂四庫全書薈要·第321冊」…「第343冊」
+ * 合成一条「摛藻堂四庫全書薈要」+ 23 个册号。
+ */
+export declare function mergeVolumeResources(items: ResourceEntry[]): ResourceEntry[];
+
 export declare class MigrationError extends BookIndexError {
     constructor(message?: string);
 }
 
+export declare interface MirrorGroup {
+    key: string;
+    label: string;
+    description?: string;
+    items: ResourceEntry[];
+}
+
 /**
  * 模式指示器
  * 显示和切换本地模式/同步模式、draft/official 切换
@@ -2119,17 +2477,48 @@ declare interface ModeIndicatorProps {
     onSelectFolder?: () => void;
 }
 
+/** 整行宽的虚线「展开其余 N 条」按钮 */
+export declare function MoreButton({ label, onClick, inline }: {
+    label: string;
+    onClick: () => void;
+    /** inline = chip 牆里的「更多 N 種」，非整行 */
+    inline?: boolean;
+}): JSX.Element;
+
 /**
  * 将任意格式的 volume_book_mapping.json 归一化为统一的 VolumeBookMapping。
  */
 export declare function normalizeCatalog(raw: unknown): VolumeBookMapping;
 
+export declare function normalizeEra(era: string): string;
+
+/**
+ * 把原始 role 歸到粗類。
+ * 空值歸「撰」——802 條 null + 121 條空串，絕大多數是錄入時省略的作者本人著作。
+ */
+export declare function normalizeRole(role?: string | null): RoleClass;
+
+/** volume_index 有 int / number[] / string 三种形态（生产仓实测），统一成 number[] */
+export declare function normalizeVolumeIndex(vi: unknown): number[];
+
+/** 归一化 volumes：补齐 URL */
+export declare function normalizeVolumes(item: ResourceEntry): ResourceVolume[] | null;
+
+export declare function numberToChinese(n: number): string;
+
+export declare const PAGE_MAX_WIDTH = 1000;
+
 /** 页数 */
 export declare interface PageCount {
     number?: number;
     description?: string;
 }
 
+export declare function PageFrame({ children, style }: {
+    children: default_2.ReactNode;
+    style?: default_2.CSSProperties;
+}): JSX.Element;
+
 /** 分页结果 */
 export declare interface PageResult<T> {
     entries: T[];
@@ -2138,6 +2527,9 @@ export declare interface PageResult<T> {
     pageSize: number;
 }
 
+/** 解析「四十三」「廿四」「元」这类中文序数 */
+export declare function parseChineseNumber(s: string): number | undefined;
+
 export declare function parseId(id: bigint): IdComponents;
 
 /** 解析 JSON 格式的来源数组 */
@@ -2168,6 +2560,12 @@ export declare interface PublicationInfo {
     details?: string;
 }
 
+/** 展开区里的引文块（提要 / 按语 / 附按） */
+export declare function Quote({ label, children }: {
+    label?: string;
+    children: default_2.ReactNode;
+}): JSX.Element;
+
 /** 推荐数据 */
 export declare interface RecommendedData {
     groups: RecommendedGroup[];
@@ -2221,6 +2619,19 @@ export declare interface RelatedEntity {
     type: IndexType;
 }
 
+export declare interface RelatedGroup {
+    key: string;
+    /** i18n key，UI 侧翻译 */
+    labelKey: 'belongsToWork' | 'containedWorks' | 'derivativeWorks' | 'studies' | 'relatedWorks';
+    items: RelatedWorkRef[];
+}
+
+export declare interface RelatedWorkRef {
+    id: string;
+    title: string;
+    relation?: string;
+}
+
 /** 关联关系数据 */
 export declare interface RelationData {
     parentWork?: RelatedEntity;
@@ -2254,6 +2665,8 @@ declare interface RelationPanelProps {
     onSaveRelations?: () => void;
 }
 
+export declare type RenderLink = (id: string, label?: string, ctx?: LinkContext) => default_2.ReactNode;
+
 /**
  * 指向开源数据源文件的 GitHub icon 链接。
  * 库内不感知具体仓库，由调用方传入 href。
@@ -2271,6 +2684,24 @@ export declare interface RepoSourceLinkProps {
     style?: default_2.CSSProperties;
 }
 
+/** 已解析的版本条目（BookDetailData 的子集 + 派生字段） */
+export declare interface ResolvedVersion {
+    id: string;
+    title?: string;
+    edition?: string;
+    type?: string;
+    resources?: ResourceEntry[];
+    resource_groups?: Record<string, ResourceGroupInfo>;
+    publication_info?: BookDetailData['publication_info'];
+    current_location?: BookDetailData['current_location'];
+    lineage?: BookDetailData['lineage'];
+}
+
+export declare interface ResourceBucket {
+    key: 'text' | 'image' | 'textImage' | 'physical';
+    items: ResourceEntry[];
+}
+
 /** 带资源信息的丛编目录 */
 export declare interface ResourceCatalog {
     resource_id: string;
@@ -2319,18 +2750,46 @@ export declare interface ResourceEntry {
     group_role?: 'origin' | 'mirror';
 }
 
+/** 资源分组：标题 + 右上标签 + 若干行 */
+export declare function ResourceGroup({ title, tag, children }: {
+    title: string;
+    tag?: string;
+    children: default_2.ReactNode;
+}): JSX.Element;
+
 /** Book/Work 上的资源组元数据：每个 group key 对应一组同源镜像的展示信息 */
 declare interface ResourceGroupInfo {
     label?: string;
     description?: string;
 }
 
+/** 资源的最终跳转地址（有页码范围时直达起始页） */
+export declare function resourceHref(item: ResourceEntry): string | undefined;
+
 /** 资源导入状态 */
 export declare type ResourceImportStatus = 'todo' | 'in_progress' | 'done';
 
 /** 资源导入类型 */
 export declare type ResourceImportType = 'catalog' | 'collection';
 
+/**
+ * 资源行（含分册展开）。
+ *
+ * 三张页面原先各写了一份：作品页 ResourceLine、版本页 BookResourceLine、
+ * 丛编页 CollectionResourceLine —— 名称解析、note 拼接、分册展开按钮、
+ * 缺册划线的样式全都是复制过去的，其中版本页那份连 VolumeLinks 都内联了
+ * 一遍。合成一个，差异用 props 表达。
+ */
+export declare function ResourceLine({ item, siblings, showVolumes, fallbackNote, }: {
+    item: ResourceEntry;
+    /** 同组资源，用于给重名条目加区分后缀（史記在 CText 上三条同名） */
+    siblings?: ResourceEntry[];
+    /** 关掉分册展开：册号已在别处逐个列出时（版本页的「收入叢編」） */
+    showVolumes?: boolean;
+    /** note 为空时的兜底（丛编页用 details 补） */
+    fallbackNote?: string;
+}): JSX.Element;
+
 /**
  * 只读资源列表
  * 用于 kaiyuanguji-web 等场景的资源展示
@@ -2349,6 +2808,12 @@ declare interface ResourceListProps {
     renderLink?: (id: string, label?: string) => default_2.ReactNode;
 }
 
+/**
+ * 资源的一行说明文字（设计稿里名称下方的小字）。
+ * 例：「原卷掃描 · 23 / 23 冊」「精校版 · 圖文對照」「文淵閣本 · v224」
+ */
+export declare function resourceNote(item: ResourceEntry): string;
+
 /** 资源导入进度数据 */
 export declare interface ResourceProgress {
     resources: ResourceProgressItem[];
@@ -2376,6 +2841,15 @@ export declare interface ResourceProgressItem {
     notes?: string;
 }
 
+/** 资源行：名称 + note + 外链箭头 */
+export declare function ResourceRow({ name, note, href, extra }: {
+    name: default_2.ReactNode;
+    note?: string;
+    href?: string;
+    /** 行尾附加内容（如分册展开按钮） */
+    extra?: default_2.ReactNode;
+}): JSX.Element;
+
 /** 资源类型（旧版兼容：可单值或组合）。新数据应用 `types: ResourceTypeAtom[]` */
 export declare type ResourceType = ResourceTypeAtom | 'text+image';
 
@@ -2396,6 +2870,34 @@ export declare interface ResourceVolume {
     [key: string]: unknown;
 }
 
+export declare const ROLE_CLASS_ORDER: RoleClass[];
+
+/**
+ * 職任歸一。
+ *
+ * 生產倉全量 62,068 條人物—作品關聯裡出現了 **307 種不同寫法**：
+ * 撰 51,247（82.6%）· 作 2,440 · 編 2,008 · 注 1,003 · 修 927 · 纂修 876 …
+ * 長尾則是「等奉敕撰」「舊題撰」「集解」「校正並音釋」這類，
+ * 還混著繁簡兩寫（輯/辑、註/注、刪/删、傳/传、贊/赞）與私用區壞字。
+ *
+ * 不歸一的話篩選 chips 會炸出上百個按鈕，且「撰」與「等奉敕撰」分屬兩組。
+ * 這裡只歸「篩選用的粗類」，原始寫法仍原樣顯示在「職任」列裡——
+ * 「等奉敕撰」與「撰」的區別對版本學是有意義的，不能真的抹掉。
+ */
+export declare type RoleClass = '撰' | '編' | '注' | '校' | '譯' | '繪' | '其他';
+
+export declare interface RoleFacet {
+    cls: RoleClass | '全部';
+    label: string;
+    count: number;
+}
+
+/** 統計各粗類條數，供篩選 chips 用；空類不出現 */
+export declare function roleFacets(roles: (string | null | undefined)[]): RoleFacet[];
+
+/** 行号：统一补零到两位 */
+export declare function rowNo(i: number): string;
+
 export declare const SearchInput: default_2.FC<SearchInputProps>;
 
 export declare interface SearchInputProps {
@@ -2411,6 +2913,16 @@ export declare interface SearchInputProps {
 
 export declare const Section: default_2.FC<SectionProps>;
 
+/** 区块头：徽章 + 标题 + 计数 ｜ 右侧动作 */
+export declare function SectionHead({ glyph, tone, title, count, actions, id }: {
+    glyph: string;
+    tone?: 'accent' | 'ink';
+    title: string;
+    count?: default_2.ReactNode;
+    actions?: default_2.ReactNode;
+    id?: string;
+}): JSX.Element;
+
 declare interface SectionProps {
     title: string;
     /** 保存按钮回调 */
@@ -2482,9 +2994,73 @@ export declare interface SyncConfig {
 
 declare type TabKey = 'recommend' | 'catalog' | 'collection' | 'site' | 'feedback';
 
+/** 表头。窄屏由 CSS 隐藏（meta 折到第二行后表头就没意义了）。 */
+export declare function TableHead({ spec }: {
+    spec: TableSpec;
+}): JSX.Element;
+
+/** 表格行：行号 + 主内容 + meta 组合列。宽度取自与表头同一份 spec。 */
+export declare function TableRow({ no, main, meta, spec }: {
+    no: default_2.ReactNode;
+    main: default_2.ReactNode;
+    meta: default_2.ReactNode;
+    spec: TableSpec;
+}): JSX.Element;
+
+/**
+ * 表格列规格。
+ *
+ * 表头与每一行必须用同一份宽度，否则列会错位。原先三张页面各自把
+ * leadWidth / metaWidth / metaColumns 手抄进 TableHead 和 TableRow 两处
+ * （作品页 22/424、丛编页 26/300、人物页 26/300），改一处忘一处就错位。
+ * 现在一处声明、两处消费。
+ */
+export declare interface TableSpec {
+    /** 行号列宽 */
+    leadWidth: number;
+    /** meta 区总宽 */
+    metaWidth: number;
+    /** meta 区各子列：表头文案 + 宽度 */
+    columns: {
+        label: string;
+        width: string;
+    }[];
+    /** 主列表头文案 */
+    mainLabel: string;
+}
+
+/**
+ * 标签 + chip 的一行（别名 / 附载篇目 / 附录）。
+ * 作品页的 TagRows 与版本页的 AliasRow 原是同一段样式的两份拷贝。
+ */
+export declare function TagRow({ label, items }: {
+    label: string;
+    items: string[];
+}): JSX.Element | null;
+
+/** 若干 TagRow 竖排 */
+export declare function TagRows({ rows }: {
+    rows: {
+        label: string;
+        items: string[];
+    }[];
+}): JSX.Element | null;
+
+/** 文字按钮（排序切换等），带下划线 */
+export declare function TextButton({ label, onClick }: {
+    label: string;
+    onClick?: () => void;
+}): JSX.Element;
+
 /** 整理本文本质量等级 */
 declare type TextQualityGrade = 'published' | 'fine' | 'rough' | 'ocr';
 
+/** 顶条：品牌/面包屑 ｜ 右侧动作 */
+export declare function TopStrip({ breadcrumb, actions }: {
+    breadcrumb: default_2.ReactNode;
+    actions?: default_2.ReactNode;
+}): JSX.Element;
+
 export declare function useBidUrl(): BidUrlBuilder;
 
 /**
@@ -2661,6 +3237,59 @@ export declare interface VersionLineageViewProps {
     style?: default_2.CSSProperties;
 }
 
+/**
+ * 版本分组：核心集直接展开，其余按 group 折叠。
+ * （从 IndexDetail.computeVersionPartition 迁入，逻辑不变）
+ */
+export declare interface VersionPartition {
+    useGrouping: boolean;
+    coreIds: string[];
+    groupedIds: {
+        id: string;
+        label: string;
+        description?: string;
+        ids: string[];
+    }[];
+}
+
+export declare interface VersionRow {
+    id: string;
+    /** 显示名：edition 优先（96.4% 有），回退 title */
+    name: string;
+    era: DerivedEra;
+    year?: number;
+    /** 影印图源（types 含 image 的资源） */
+    images: ResourceEntry[];
+    /** 收藏机构（types 含 physical 的资源 + current_location） */
+    holders: ResourceEntry[];
+    /** current_location.name —— 没有 physical 资源时的回退 */
+    locationName?: string;
+    /** 是否重点版本（在 version_graph 核心集内） */
+    important: boolean;
+    /** 所属分组 id（version_graph.node_groups） */
+    group?: string;
+    hasImage: boolean;
+}
+
+export declare interface VersionTable {
+    rows: VersionRow[];
+    /** 全部行（未筛选），用于计数 */
+    allRows: VersionRow[];
+    /** 可用的朝代筛选项（按历史顺序） */
+    eras: string[];
+    /** 是否有任何一行的年代是推断出来的（UI 据此显示说明） */
+    hasInferredEra: boolean;
+}
+
+export declare interface VersionTableOptions {
+    /** 朝代筛选，空串或 undefined = 全部 */
+    era?: string;
+    /** 仅看有影印 */
+    scanOnly?: boolean;
+    /** 排序：default = 录入序（人工排的重要程度）；year = 年代先后 */
+    sort?: 'default' | 'year';
+}
+
 /** 丛编目录中的书目条目（统一格式，归一化后） */
 export declare interface VolumeBookEntry {
     title: string;
@@ -2701,6 +3330,13 @@ export declare interface VolumeBookStats {
     total_found_volumes?: number;
 }
 
+/** 册次方块（版本页「收入叢編」的 321…343） */
+export declare function VolumeChips({ volumes, unit, max }: {
+    volumes: number[];
+    unit?: string;
+    max?: number;
+}): JSX.Element | null;
+
 /** 册级详细信息（来源 URL、状态等） */
 export declare interface VolumeDetail {
     volume: number;
@@ -2709,12 +3345,26 @@ export declare interface VolumeDetail {
     file?: string;
 }
 
+/** 分册链接网格：缺册划线，无链接的册号显示为灰字 */
+export declare function VolumeLinks({ item }: {
+    item: ResourceEntry;
+}): JSX.Element;
+
 /** 丛编分部 */
 export declare interface VolumeSection {
     name: string;
     volume_range: [number, number];
 }
 
+/** 分册统计（按册号去重——同一册可在多个 group 中出现，如跨 Work 共册） */
+export declare interface VolumeStats {
+    found: number;
+    missing: number;
+    expected: number;
+}
+
+export declare function volumeStats(item: ResourceEntry): VolumeStats | null;
+
 export declare const WorkCatalog: default_2.FC<WorkCatalogProps>;
 
 export declare interface WorkCatalogProps {
@@ -2746,4 +3396,15 @@ export declare interface WorkDetailData extends BaseDetailData {
     version_graph?: VersionGraph;
 }
 
+export declare const WorkPage: default_2.FC<WorkPageProps>;
+
+export declare interface WorkPageProps {
+    data: WorkDetailData;
+    transport?: IndexStorage;
+    onNavigate?: (id: string) => void;
+    renderLink?: RenderLink;
+    /** 版本传承入口（由 layout 注入，渲染在版本区块头右侧） */
+    lineageAction?: default_2.ReactNode;
+}
+
 export { }