@embedpdf-editor/vue3-chapter-viewer 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,519 @@
+import { AnnotationCapability } from '@embedpdf/plugin-annotation';
+import { BasePluginConfig } from '@embedpdf/core';
+import { ChapterTreeNode } from '../vue/chapter-tree';
+import { default as ChapterTreePanel } from '../components/ChapterTreePanel.vue';
+import { ChapterViewerCatalog } from '../vue/chapter-tree';
+import { Command } from '@embedpdf/plugin-commands';
+import { ComponentOptionsMixin } from 'vue';
+import { ComponentProvideOptions } from 'vue';
+import { DefineComponent } from 'vue';
+import { EmbedPDF } from '@embedpdf/core/vue';
+import { default as PdfChapterViewport } from '../components/PdfChapterViewport.vue';
+import { PdfEngine } from '@embedpdf/models';
+import { PluginBatchRegistration } from '@embedpdf/core';
+import { PublicProps } from 'vue';
+import { ReactNode } from 'react';
+import { Rect } from '@embedpdf/models';
+import { SelectionCapability } from '@embedpdf/plugin-selection';
+import { ToolbarSchema } from '@embedpdf/plugin-ui';
+import { UISchema } from '@embedpdf/plugin-ui';
+import { useCapability } from '@embedpdf/core/vue';
+import { usePdfiumEngine } from '@embedpdf/engines/vue';
+
+declare const __VLS_export: DefineComponent<__VLS_Props, {}, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly<__VLS_Props> & Readonly<{}>, {}, {}, {}, {}, string, ComponentProvideOptions, false, {}, any>;
+
+declare type __VLS_Props = {
+    viewerProps: ChapterPdfViewerProps;
+};
+
+/** 对当前选区应用 PDF 划线/高亮，支持按类型自定义颜色、粗细与偏移 */
+export declare function applySelectionMarkup(documentId: string, kind: SelectionMarkupKind, annotation: AnnotationCapability, selection: SelectionCapability, styles?: MarkupStylesConfig): boolean;
+
+declare interface BookmarkMarkerUiConfig {
+    /** 自定义图标；提供时仅渲染图标，无默认蓝色背景按钮 */
+    renderIcon?: (ctx: {
+        bookmark: ParagraphBookmark;
+    }) => ReactNode;
+    iconSize?: number;
+}
+
+declare interface BookmarkMarkerUiConfig_2 {
+    /** 自定义图标；提供时仅渲染图标，无默认蓝色圆角背景 */
+    renderIcon?: (ctx: {
+        bookmark: ParagraphBookmark;
+    }) => unknown;
+    iconSize?: number;
+}
+
+export declare function buildParagraphBookmarkAnchor(chapterId: string, localPageIndex: number, rectsPdfCoord: Rect[], virtualPage?: {
+    globalPageIndex: number;
+    globalPageNumber: number;
+}): ParagraphBookmark['anchor'];
+
+/** 选区浮窗 card 内置操作 */
+declare type BuiltinSelectionToolbarAction = 'highlight' | 'underline' | 'squiggly' | 'strikeout' | 'note';
+
+/**
+ * 回调型：把决策交给业务侧异步函数（最常用）。
+ */
+export declare class CallbackPasswordProvider implements IPasswordProvider {
+    private readonly cb;
+    constructor(cb: (chapter: ChapterDescriptor, attempt: number) => Promise<string | null>);
+    resolvePassword(chapter: ChapterDescriptor, attempt: number): Promise<string | null>;
+}
+
+export declare interface ChapterDescriptor {
+    /** 业务唯一 ID；同时复用作 documentManager 的 documentId */
+    chapterId: string;
+    title: string;
+    /**
+     * 该章节在「整本」中的全局页范围（闭区间，业务页码，可 1-based 也可 0-based，
+     * 只要全局一致即可）。允许相邻章节重叠：`[a, b]` ∩ `[c, d]` ≠ ∅。
+     */
+    globalPageRange: [number, number];
+    /**
+     * 该章节 PDF 文件内部的本地页范围（0-based 闭区间）。
+     * 必须满足：`localPageRange[1] - localPageRange[0] === globalPageRange[1] - globalPageRange[0]`
+     */
+    localPageRange: [number, number];
+    /**
+     * PDF 来源。可省略：须在 ChapterManager 配置 `chapterPdfLoader` 中统一加载。
+     */
+    source?: ChapterSource;
+    encrypted?: boolean;
+    /**
+     * 仅当 OverlapOwnerStrategy = 'explicit' 时使用：
+     * 该章节"声明拥有"的全局页号集合。
+     */
+    ownedGlobalPages?: number[];
+}
+
+/**
+ * 章节级加载状态。区别于 `@embedpdf/core` 的 DocumentState：
+ * - `idle` = manifest 已注册但尚未触发 open
+ * - `password-required` = 用户取消/密码错误后停在等密码态
+ */
+export declare type ChapterLoadStatus = 'idle' | 'loading' | 'loaded' | 'error' | 'password-required' | 'closed';
+
+export declare interface ChapterManifest {
+    chapters: ChapterDescriptor[];
+    /**
+     * 整本去重后的总页数。当未提供时由 VirtualPageMap 自动推导
+     * （取所有章节 globalPageRange 的并集大小）。
+     */
+    totalGlobalPages?: number;
+}
+
+/**
+ * Backend-supplied chapter contract.
+ *
+ * 一个 PDF 整体被后端按章节切成若干独立 PDF 文件；前端将它们组装成一条
+ * 连续滚动流。相邻章节在 `globalPageRange` 上**允许重叠**（业务上下章
+ * 经常各含一个过渡页），由 OverlapResolver 决定每个全局页归属的「owner
+ * chapter」，渲染与标注都落在 owner 上以保持唯一性。
+ */
+/** 章节 PDF 解析结果 */
+export declare type ChapterPdfPayload = {
+    url: string;
+} | {
+    buffer: ArrayBuffer;
+};
+
+export declare const ChapterPdfViewer: typeof __VLS_export;
+
+/** React / Vue 共用的章节阅读器顶层 props（框架专属字段在各自入口扩展） */
+export declare interface ChapterPdfViewerProps {
+    engine: PdfEngine;
+    editorOptions: Omit<CreatePdfChapterEditorOptions, 'features'> & {
+        notes?: PdfChapterEditorNotesConfig;
+        bookmarks?: PdfChapterEditorBookmarksConfig;
+    };
+    features?: ChapterViewerFeaturesConfig;
+    className?: string;
+    viewportClassName?: string;
+}
+
+/**
+ * 章节 PDF 来源（由业务在 manifest 中提供）：
+ * - `url`：直接打开该地址
+ * - `buffer`：已取回的 PDF 二进制
+ * - `load`：按章节自定义拉取（鉴权、本地 FS 等）
+ */
+export declare type ChapterSource = {
+    url: string;
+} | {
+    buffer: ArrayBuffer;
+} | {
+    load: () => Promise<ChapterPdfPayload>;
+};
+
+export { ChapterTreeNode }
+
+export { ChapterTreePanel }
+
+export { ChapterViewerCatalog }
+
+/** 章节渲染器集成功能开关（与 demo 默认样式对齐） */
+export declare interface ChapterViewerFeaturesConfig {
+    /** 划线/高亮 */
+    markup?: {
+        enabled?: boolean;
+        styles?: MarkupStylesConfig;
+    };
+    /** 段落书签（含悬停添加） */
+    bookmarks?: {
+        enabled?: boolean;
+        marker?: BookmarkMarkerUiConfig_2;
+        hover?: HoverBookmarkUiConfig_2;
+    };
+    /** 笔记 */
+    notes?: {
+        enabled?: boolean;
+        marker?: NoteMarkerUiConfig;
+    };
+    /** 选区浮窗 */
+    selectionToolbar?: SelectionToolbarConfig;
+    /** 缩放 */
+    zoom?: ChapterViewerZoomConfig;
+}
+
+declare interface ChapterViewerZoomConfig {
+    /** 是否启用 pinch/滑块缩放容器，默认 true */
+    enabled?: boolean;
+    min?: number;
+    max?: number;
+    initial?: number;
+}
+
+/**
+ * 创建带默认划线/笔记/书签/选区 card 的章节编辑器插件包。
+ * 传入的 `features` 与默认值浅合并。
+ */
+export declare function createChapterViewerEditor(options: CreatePdfChapterEditorOptions): PdfChapterEditorBundle;
+
+export declare function createChapterViewerEditorOptions(input: CreateChapterViewerEditorOptionsInput): Omit<CreatePdfChapterEditorOptions, 'features'>;
+
+export declare type CreateChapterViewerEditorOptionsInput = {
+    manifest: ChapterManifest;
+    chapterPdfLoader?: IChapterPdfLoader;
+    bookmarks: PdfChapterEditorBookmarksConfig;
+    notes: PdfChapterEditorNotesConfig;
+};
+
+declare interface CreateEditorUiSchemaOptions {
+    /** 默认全开 */
+    enabledModes?: EditorModeId[];
+    customOperations?: OperationSpec[];
+    /** 合并进最终 schema 的额外 toolbars / menus 等 */
+    extend?: Partial<Pick<UISchema, 'toolbars' | 'menus' | 'sidebars' | 'modals' | 'selectionMenus'>>;
+}
+
+/**
+ * 组装章节 PDF 编辑器所需的插件注册列表与 UI Schema。
+ * 不挂载 `@embedpdf/plugin-scroll`；滚动由 `ChapterScrollPlugin` + `ChapterScroller` 负责。
+ */
+export declare function createPdfChapterEditor(options: CreatePdfChapterEditorOptions): PdfChapterEditorBundle;
+
+export declare interface CreatePdfChapterEditorOptions {
+    manifest: ChapterManifest;
+    overlapStrategy?: OverlapOwnerStrategy;
+    passwordProvider?: IPasswordProvider;
+    /** 章节未在 manifest 中写 source 时，由此加载 PDF */
+    chapterPdfLoader?: IChapterPdfLoader;
+    notes?: PdfChapterEditorNotesConfig;
+    bookmarks?: PdfChapterEditorBookmarksConfig;
+    toolbar?: PdfChapterEditorToolbarConfig;
+    /** 传给 chapter-manager；manifest 就绪后预取前 N 章 */
+    prefetchChapters?: number;
+    /** 为 false 时不拉取 CDN 默认图章库（@embedpdf/default-stamps） */
+    loadDefaultStampLibrary?: boolean;
+    unloadTimeoutMs?: number;
+    /** 传给 chapter-scroll */
+    placeholderPageHeight?: number;
+    placeholderPageWidth?: number;
+    /** 合并进 Commands 插件（如 mode / annotation / form 等） */
+    commands?: Record<string, Command>;
+    /**
+     * 章节阅读器集成功能（划线/笔记/书签/选区 card / 缩放）。
+     * 默认 demo 样式；各子项可单独关闭或扩展。
+     */
+    features?: ChapterViewerFeaturesConfig;
+}
+
+/** 与 demo 对齐的默认集成功能 */
+export declare const DEFAULT_CHAPTER_VIEWER_FEATURES: ChapterViewerFeaturesConfig;
+
+/** 与 snippet 主工具栏 mode tabs 对齐的编辑模式 */
+declare type EditorModeId = 'view' | 'annotate' | 'shapes' | 'insert' | 'form' | 'redact';
+
+/** Snippet-derived secondary toolbars for Annotate / Shapes / Insert / Form / Redact */
+declare const editorSecondaryToolbars: Record<string, ToolbarSchema>;
+
+export { EmbedPDF }
+
+declare interface HoverBookmarkUiConfig {
+    renderAddIcon?: () => ReactNode;
+    iconSize?: number;
+}
+
+declare interface HoverBookmarkUiConfig_2 {
+    /** 悬停行末「添加书签」自定义图标；无背景 */
+    renderAddIcon?: () => unknown;
+    iconSize?: number;
+}
+
+/**
+ * 全局章节 PDF 加载器：当 `ChapterDescriptor.source` 未提供 url/buffer/load 时使用。
+ * 适合统一走业务 API、鉴权下载等场景。
+ */
+export declare interface IChapterPdfLoader {
+    loadPdf(chapter: ChapterDescriptor): Promise<ChapterPdfPayload>;
+}
+
+/**
+ * 章节加密的抽象接口：当某章节首次或重试加载因密码失败时，
+ * `ChapterManagerPlugin` 会向 provider 询问密码。
+ *
+ * 返回 `null` 表示用户/系统放弃，对应章节进入 `password-required` 状态。
+ */
+declare interface IPasswordProvider {
+    /**
+     * @param chapter 失败章节描述
+     * @param attempt 已经尝试次数（0 = 首次），可用于实现"输错三次锁定"等策略
+     */
+    resolvePassword(chapter: ChapterDescriptor, attempt: number): Promise<string | null>;
+    /** 可选：同步快查缓存，避免显式 await */
+    getCachedPassword?(chapterId: string): string | null;
+}
+
+/** 单种划线的样式（颜色、粗细、垂直偏移，PDF 点） */
+declare interface MarkupKindStyle {
+    /** 描边/填充色，如 #facc15 */
+    color?: string;
+    /** 线宽（下划线/删除线等），PDF 点 */
+    thickness?: number;
+    /** 相对字形底边的垂直偏移，正值向下（PDF 点） */
+    offsetY?: number;
+    opacity?: number;
+}
+
+declare type MarkupStylesConfig = Partial<Record<SelectionMarkupKind, MarkupKindStyle>>;
+
+/**
+ * 一条附注（note）的位置锚点。
+ * - `rectsPdfCoord` 来自 selection.getHighlightRectsForPage 的 PDF 坐标系
+ * - `endAnchor` 用于"末尾图标"渲染：取选区最后一行 right 边缘
+ * - `noteId` 由开发者回调返回（服务端 ID），插件本身不生成
+ */
+export declare interface NoteAnchor {
+    noteId: string;
+    chapterId: string;
+    globalPageIndex: number;
+    globalPageNumber: number;
+    localPageIndex: number;
+    rectsPdfCoord: Rect[];
+    endAnchor: {
+        x: number;
+        y: number;
+    };
+    selectedText: string;
+    /** 用户填写的笔记正文（由业务持久化） */
+    content?: string;
+}
+
+export declare interface NoteCallbacks {
+    /** 初次加载已有附注 */
+    loadNotes?: () => Promise<NoteAnchor[]>;
+    /**
+     * 内置创建：持久化后返回 noteId。
+     * 与 onRequestCreateNote 二选一（至少配置其一）。
+     */
+    onCreateNote?: (draft: NoteDraft) => Promise<{
+        noteId: string;
+    } | null>;
+    /**
+     * 自定义创建弹窗：仅发出事件，由宿主 complete(noteId)。
+     * 配置后划词/默认流程不再调用 onCreateNote。
+     */
+    onRequestCreateNote?: (payload: NoteCreateRequestPayload) => void;
+    /** 自定义编辑：传出 noteId */
+    onRequestEditNote?: (noteId: string, anchor: NoteAnchor) => void;
+    onUpdateNote?: (note: NoteAnchor) => Promise<void>;
+    onDeleteNote?: (noteId: string) => Promise<void>;
+    /** 点击编辑且未配置 onRequestEditNote 时回退 */
+    onActivateNote?: (noteId: string, anchor: NoteAnchor) => void;
+}
+
+/** 自定义笔记创建：宿主打开 UI 后调用 complete(noteId) */
+declare interface NoteCreateRequestPayload {
+    draft: NoteDraft;
+    complete: (noteId: string) => Promise<void>;
+}
+
+/** 一个尚未持久化的草稿（开发者回调拿到的） */
+export declare type NoteDraft = Omit<NoteAnchor, 'noteId'>;
+
+declare interface NoteMarkerMenuActionCtx {
+    note: NoteAnchor;
+    onEdit: () => void;
+    onDelete: () => void;
+}
+
+declare interface NoteMarkerUiConfig {
+    /** 自定义笔记标识图标；提供时无圆形背景 */
+    renderIcon?: (ctx: {
+        note: NoteAnchor;
+    }) => unknown;
+    /** 完全自定义编辑/删除区域；不提供则使用默认 card */
+    renderMenuActions?: (ctx: NoteMarkerMenuActionCtx) => unknown;
+    iconSize?: number;
+    /** 笔记高亮底色的 CSS 颜色，默认 rgba(245,158,11,0.08) */
+    highlightColor?: string;
+}
+
+declare interface OperationHandlerContext {
+    documentId: string | null;
+    chapterId: string | null;
+}
+
+/**
+ * 收集开发者自定义操作，并把它们注入到 secondary toolbar 的 items 里。
+ * Commands 插件侧的 register 由宿主在引擎初始化时根据 spec.handler 完成。
+ */
+declare class OperationRegistry {
+    private readonly specs;
+    register(operation: OperationSpec): void;
+    registerAll(operations: OperationSpec[]): void;
+    list(): readonly OperationSpec[];
+    /**
+     * 返回注入了 customOperations 的 toolbar 副本（不修改原始 fragment）。
+     */
+    buildToolbars(): typeof editorSecondaryToolbars;
+}
+
+/** 自定义操作挂载到某条 secondary toolbar */
+declare interface OperationSpec {
+    id: string;
+    modeId: EditorModeId;
+    /** 对应 {@link editorSecondaryToolbars} 的 key */
+    toolbarSlot: 'annotation-toolbar' | 'shapes-toolbar' | 'insert-toolbar' | 'form-toolbar' | 'redaction-toolbar';
+    /** 插入到某 toolbar item 之后；缺省则追加到 tools group 末尾 */
+    position?: {
+        after?: string;
+        before?: string;
+    };
+    commandId: string;
+    icon?: string;
+    i18nKey?: string;
+    label?: string;
+    categories?: string[];
+    /** 注册到 Commands 插件时的执行体（由宿主在 createPdfChapterEditor 里注入） */
+    handler?: (ctx: OperationHandlerContext) => void | Promise<void>;
+}
+
+/**
+ * 决定相邻章节在重叠页上谁拥有该页（owner）。
+ * - first-wins / last-wins：按 manifest 顺序的先到/后到
+ * - explicit：依赖 `ChapterDescriptor.ownedGlobalPages`
+ * - custom：开发者完全接管
+ */
+declare type OverlapOwnerStrategy = {
+    kind: 'first-wins';
+} | {
+    kind: 'last-wins';
+} | {
+    kind: 'explicit';
+} | {
+    kind: 'custom';
+    resolve: (globalPage: number, candidates: ChapterDescriptor[]) => string;
+};
+
+export declare interface ParagraphBookmark {
+    id: string;
+    label: string;
+    /** 业务可选元数据；插件直接存不解释 */
+    metadata?: Record<string, unknown>;
+    anchor: {
+        chapterId: string;
+        localPageIndex: number;
+        /** 创建时虚拟页索引（与附注一致，避免 toGlobal 映射偏差） */
+        globalPageIndex?: number;
+        /** 创建时业务页号 */
+        globalPageNumber?: number;
+        /** PDF 坐标系包围盒（多行选区时为各行并集） */
+        rectPdfCoord: Rect;
+        /** 各行 PDF 矩形（划词书签时与选区高亮一致） */
+        rectsPdfCoord?: Rect[];
+        /** 书签图标锚点（通常为选区末行右下角，PDF 坐标） */
+        markerAnchor?: {
+            x: number;
+            y: number;
+        };
+    };
+    createdAt: number;
+}
+
+declare interface ParagraphBookmarkCallbacks {
+    /** 初次加载已有书签 */
+    load?: () => Promise<ParagraphBookmark[]>;
+    /** 任意变更（新增 / 删除 / 改名）后回调，便于持久化 */
+    persist?: (entries: ParagraphBookmark[]) => Promise<void>;
+    /**
+     * 用户请求删除书签：由外部完成持久化删除。
+     * 返回 true 时插件会从渲染层移除该书签。
+     */
+    onRequestRemove?: (bookmark: ParagraphBookmark) => Promise<boolean>;
+    /** 书签已从插件内存移除后通知（便于 UI 收尾） */
+    onRemoveSuccess?: (bookmarkId: string) => void;
+}
+
+declare interface ParagraphBookmarkPluginConfig extends BasePluginConfig {
+    callbacks?: ParagraphBookmarkCallbacks;
+    ui?: BookmarkMarkerUiConfig;
+    hover?: HoverBookmarkUiConfig;
+}
+
+export declare interface PdfChapterEditorBookmarksConfig {
+    callbacks: NonNullable<ParagraphBookmarkPluginConfig['callbacks']>;
+}
+
+declare interface PdfChapterEditorBundle {
+    plugins: PluginBatchRegistration<any, any, any, any>[];
+    uiSchema: UISchema;
+    operationRegistry: OperationRegistry;
+}
+
+export declare interface PdfChapterEditorNotesConfig {
+    callbacks: NoteCallbacks;
+}
+
+declare interface PdfChapterEditorToolbarConfig extends CreateEditorUiSchemaOptions {
+}
+
+export { PdfChapterViewport }
+
+/** 划线类型 */
+declare type SelectionMarkupKind = 'highlight' | 'underline' | 'squiggly' | 'strikeout';
+
+declare interface SelectionToolbarConfig {
+    /** 是否显示默认 card，默认 true */
+    enabled?: boolean;
+    /** 隐藏部分内置按钮 */
+    hiddenBuiltinActions?: BuiltinSelectionToolbarAction[];
+    /** 扩展操作（由宿主在 buildSelectionMenu 或 onExtraAction 中处理） */
+    extraActions?: SelectionToolbarExtraAction[];
+}
+
+/** 扩展选区操作 */
+declare interface SelectionToolbarExtraAction {
+    id: string;
+    label: string;
+    /** 排序权重，越小越靠前（在内置 markup 之后、note 之前） */
+    order?: number;
+}
+
+export { useCapability }
+
+export { usePdfiumEngine }
+
+export { }

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AACrE,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,yBAAyB,EACzB,sBAAsB,EACtB,gCAAgC,EAChC,+BAA+B,EAC/B,oBAAoB,EACpB,4BAA4B,EAC5B,wBAAwB,EACxB,QAAQ,EACR,aAAa,GACd,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,YAAY,EACV,qBAAqB,EACrB,2BAA2B,EAC3B,qCAAqC,EACrC,6BAA6B,EAC7B,2BAA2B,EAC3B,+BAA+B,EAC/B,aAAa,EACb,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,eAAe,EACf,oBAAoB,EACpB,iBAAiB,GAClB,MAAM,oCAAoC,CAAC"}