@hmg-report-editor/core 1.0.0

package/dist/types/index.d.ts

@@ -0,0 +1,401 @@
+/** core 包共享类型，定义报告文档、模板、编辑器实例和扩展协议。 */
+import type { Editor, Extensions } from '@tiptap/core';
+import type { ReportEditorGroupManager } from '../group/ReportEditorGroupManager.js';
+/** HTML 导出模式：编辑、预览和打印。 */
+export type HtmlOutputMode = 'edit' | 'preview' | 'print';
+/** 纯文本导出配置。 */
+export type ReportPlainTextOptions = {
+    hideVisibilityGroups?: boolean;
+};
+/** 条件隐藏组当前支持的判定语义。 */
+export type VisibilityGroupCondition = 'all-controls-empty';
+/** 运行时 visibilityGroup mark 的稳定身份与判定条件。 */
+export type VisibilityGroupMarkAttrs = {
+    groupId: string;
+    condition: VisibilityGroupCondition;
+};
+/** 结构化控件可保存的基础值类型。 */
+export type StructuredFieldValue = string | number | boolean | null;
+/** 报告控件值的语义别名。 */
+export type ReportControlValue = StructuredFieldValue;
+/** 结构化控件的键盘快捷键配置。 */
+export type ReportControlShortcutOptions = {
+    enabled?: boolean;
+    nextControl?: string;
+    previousControl?: string;
+    openDropdown?: string;
+    closeDropdown?: string;
+    nextDropdownOption?: string;
+    previousDropdownOption?: string;
+    selectDropdownOption?: string;
+    submitInput?: string;
+    autoFocusNextOnEnter?: boolean;
+};
+/** 结构化控件规则条件配置。 */
+export type ReportControlRulePremise = {
+    condition: string;
+    conditionDes?: string;
+    conditionRange?: {
+        symbol1?: string;
+        symbol2?: string;
+        number1?: string | number;
+        number2?: string | number;
+    };
+    entryType: 'input' | 'math';
+    inputSerialMath: string;
+};
+/** 结构化控件规则结果配置。 */
+export type ReportControlRuleResult = {
+    type: 'content' | 'math' | string;
+    value: string;
+    style?: boolean;
+    bStyle?: boolean;
+    styleValue?: string;
+    exact?: boolean;
+    exactNum?: number;
+    exactType?: '1' | '2' | '3' | string;
+};
+/** 一组前提条件和对应结果。兼容历史 premiss 命名。 */
+export type ReportControlRuleContent = {
+    premises?: ReportControlRulePremise[];
+    premiss?: ReportControlRulePremise[];
+    result: ReportControlRuleResult;
+};
+/** 单个结构化控件规则。兼容历史 list 命名。 */
+export type ReportControlRule = {
+    title: string;
+    contents?: ReportControlRuleContent[];
+    list?: ReportControlRuleContent[];
+};
+/** ProseMirror mark 的序列化形态。 */
+export type ProseMirrorMark = {
+    type: string;
+    attrs?: Record<string, unknown>;
+};
+/** 结构化控件内部富文本分段。 */
+export type ReportControlTextSegment = {
+    text: string;
+    marks?: ProseMirrorMark[];
+};
+/** ProseMirror node 的轻量 JSON 形态。 */
+export type ProseMirrorNode = {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: ProseMirrorNode[];
+    text?: string;
+    marks?: ProseMirrorMark[];
+};
+/** 报告编辑器对外保存的权威 JSON 文档。 */
+export type ReportDocument = {
+    version: string;
+    type: 'doc';
+    content: ProseMirrorNode[];
+};
+/** 下拉控件的选项项。 */
+export type DropdownOption = {
+    label: string;
+    value: string;
+};
+/** 所有结构化控件共享的属性。 */
+export type ReportControlAttrs = {
+    controlId?: string;
+    batchId?: string;
+    templateId?: string;
+    widgetNumber?: string;
+    fieldId: string;
+    fieldName: string;
+    value: StructuredFieldValue;
+    defaultValue?: StructuredFieldValue;
+    placeholder?: string;
+    required?: boolean;
+    hideWhenEmpty?: boolean;
+    noMatchDefault?: boolean;
+    rules?: ReportControlRule[];
+    nextWidgetNumber?: string;
+    ruleStyleColor?: string | null;
+} & Record<string, unknown>;
+export type StructuredFieldAttrs = ReportControlAttrs;
+/** 下拉控件属性，扩展共享控件属性并携带可选项。 */
+export type DropdownFieldAttrs = StructuredFieldAttrs & {
+    options: DropdownOption[];
+    allowCustomText?: boolean;
+};
+/** 隐藏段落的节点属性。 */
+export type HiddenParagraphAttrs = {
+    hidden: boolean;
+};
+/** 编号块的节点属性。 */
+export type NumberedBlockAttrs = {
+    number?: string;
+    manualNumber?: boolean;
+};
+/** 手动分页符持久化属性。 */
+export type ReportPageBreakAttrs = {
+    id: string;
+};
+/** 手动分页符在当前文档中的定位快照。 */
+export type ReportPageBreakSnapshot = {
+    id: string;
+    pos: number;
+};
+/** 模板段落节点。 */
+export type TemplateParagraphNode = {
+    type: 'paragraph';
+    hidden?: boolean;
+    content?: TemplateNode[];
+};
+/** 模板文本节点。 */
+export type TemplateTextNode = {
+    type: 'text';
+    text: string;
+    marks?: ProseMirrorMark[];
+};
+/** 模板结构化输入控件节点。 */
+export type TemplateStructuredFieldNode = {
+    type: 'structuredField';
+    attrs: StructuredFieldAttrs;
+};
+/** 模板下拉控件节点。 */
+export type TemplateDropdownFieldNode = {
+    type: 'dropdownField';
+    attrs: DropdownFieldAttrs;
+};
+/** 模板编号块节点。 */
+export type TemplateNumberedBlockNode = {
+    type: 'numberedBlock';
+    attrs?: NumberedBlockAttrs;
+    content?: TemplateNode[];
+};
+/** 模板期条件隐藏组；编译后展平为带 visibilityGroup mark 的行内节点。 */
+export type TemplateVisibilityGroupNode = {
+    type: 'visibilityGroup';
+    attrs?: {
+        condition?: VisibilityGroupCondition;
+    };
+    content: TemplateNode[];
+};
+/** 模板中的手动分页符，每次应用时生成新的实例 ID。 */
+export type TemplatePageBreakNode = {
+    type: 'pageBreak';
+};
+/** 业务方通过 feature 扩展的自定义模板节点。 */
+export type TemplateCustomNode<TAttrs extends Record<string, unknown> = Record<string, unknown>> = {
+    type: string;
+    attrs?: TAttrs;
+    content?: TemplateNode[];
+    text?: string;
+    marks?: ProseMirrorMark[];
+};
+/** 当前模板支持的节点联合类型。 */
+export type TemplateNode = TemplateParagraphNode | TemplateTextNode | TemplateStructuredFieldNode | TemplateDropdownFieldNode | TemplateNumberedBlockNode | TemplateVisibilityGroupNode | TemplatePageBreakNode | TemplateCustomNode;
+/** 后端或业务系统传入编辑器的报告模板。 */
+export type ReportTemplate = {
+    version: string;
+    title?: string;
+    content: TemplateNode[];
+};
+/** 编辑器内部和对外事件使用的错误码。 */
+export type ReportEditorErrorCode = 'INVALID_DOCUMENT' | 'TEMPLATE_PARSE_FAILED' | 'INVALID_FIELD_CONFIG' | 'DROPDOWN_OPTION_NOT_FOUND' | 'PASTE_SANITIZE_FAILED' | 'SELECTION_RESTORE_FAILED' | 'UNSUPPORTED_SERIALIZATION' | 'CONTROL_PLUGIN_FAILED' | 'CONTROL_RULE_FAILED' | 'COMMAND_FAILED';
+/** 编辑器错误或警告事件。 */
+export type ReportEditorError = {
+    code: ReportEditorErrorCode;
+    level: 'warning' | 'error';
+    message: string;
+    detail?: unknown;
+};
+/** 文档变更时对外派发的数据。 */
+export type ReportChangePayload = {
+    json: ReportDocument;
+    html: string;
+    tiptapEditor: Editor;
+};
+/** 选区变更时对外派发的数据。 */
+export type ReportSelectionPayload = {
+    from: number;
+    to: number;
+    empty: boolean;
+};
+/** 编辑器内单个结构化控件的快照。 */
+export type ReportControlSnapshot = {
+    editorId: string;
+    nodeType: string;
+    controlId: string;
+    attrs: ReportControlAttrs;
+    pos: number;
+};
+/** 控件生命周期插件可使用的编辑器上下文。 */
+export type ReportControlPluginContext = {
+    editorId: string;
+    editor: Editor;
+    getControl(controlId: string): ReportControlSnapshot | undefined;
+    getControls(): ReportControlSnapshot[];
+    updateControlAttrs(controlId: string, attrs: Partial<ReportControlAttrs>): boolean;
+    warn(code: ReportEditorErrorCode, message: string, detail?: unknown): void;
+};
+/** 控件生命周期插件收到的变更信息。 */
+export type ReportControlChangePayload = {
+    previous: ReportControlSnapshot;
+    current: ReportControlSnapshot;
+};
+/** 结构化控件插件协议。 */
+export type ReportControlPlugin = {
+    name?: string;
+    getCurrentBatchId?: () => string | undefined;
+    onEditorReady?: (context: ReportControlPluginContext) => void;
+    onEditorDestroyed?: (context: ReportControlPluginContext) => void;
+    onControlAdded?: (control: ReportControlSnapshot, context: ReportControlPluginContext) => void;
+    onControlRemoved?: (control: ReportControlSnapshot, context: ReportControlPluginContext) => void;
+    onControlValueChanged?: (change: ReportControlChangePayload, context: ReportControlPluginContext) => void;
+    onControlMetadataChanged?: (change: ReportControlChangePayload, context: ReportControlPluginContext) => void;
+};
+/** 创建 core 编辑器实例的配置。 */
+export type ReportEditorOptions = {
+    editorId?: string;
+    element?: HTMLElement;
+    content?: ReportDocument | string;
+    template?: ReportTemplate;
+    features?: ReportFeatureDescriptor[];
+    controlPlugins?: ReportControlPlugin[];
+    editorGroup?: ReportEditorGroupManager;
+    controlShortcuts?: ReportControlShortcutOptions;
+    readonly?: boolean;
+    documentVersion?: string;
+    emitInitialContent?: boolean;
+    onChange?: (payload: ReportChangePayload) => void;
+    onSelectionChange?: (payload: ReportSelectionPayload) => void;
+    onReady?: (instance: ReportEditorInstance) => void;
+    onError?: (error: ReportEditorError) => void;
+};
+/** core 编辑器实例对外暴露的命令和查询 API。 */
+export type ReportEditorInstance = {
+    getEditorId(): string;
+    getTiptapEditor(): Editor;
+    focus(): void;
+    destroy(): void;
+    undo(): boolean;
+    redo(): boolean;
+    getJSON(): ReportDocument;
+    getHTML(mode?: HtmlOutputMode): string;
+    getPlainText(options?: ReportPlainTextOptions): string;
+    setContent(content: ReportDocument | string): void;
+    clearContent(): void;
+    applyTemplate(template: ReportTemplate): boolean;
+    appendTemplate(template: ReportTemplate): boolean;
+    insertControl(nodeType: string, attrs: ReportControlAttrs): boolean;
+    updateControlAttrs(controlId: string, attrs: Partial<ReportControlAttrs>): boolean;
+    updateControlValue(controlId: string, value: StructuredFieldValue): boolean;
+    updateControlValueByFieldName(fieldName: string, value: StructuredFieldValue): boolean;
+    getControls(): ReportControlSnapshot[];
+    getControl(controlId: string): ReportControlSnapshot | undefined;
+    insertPageBreak(): boolean;
+    deletePageBreak(id?: string): boolean;
+    getPageBreaks(): ReportPageBreakSnapshot[];
+    toggleHiddenParagraph(): boolean;
+    setParagraphHidden(hidden: boolean): boolean;
+    moveNumberedBlock(fromIndex: number, toIndex: number): boolean;
+    setEditable(editable: boolean): void;
+};
+/** 可恢复选区的快照。 */
+export type SavedSelection = {
+    from: number;
+    to: number;
+    anchor: number;
+    head: number;
+    timestamp: number;
+};
+/** 跨编辑器共享历史的一条变更记录。 */
+export type SharedHistoryEntry = {
+    editorId: string;
+    before: ReportDocument;
+    after: ReportDocument;
+    timestamp: number;
+    label?: string;
+};
+/** 共享历史状态变更 payload。 */
+export type SharedHistoryChangePayload = {
+    canUndo: boolean;
+    canRedo: boolean;
+    undoDepth: number;
+    redoDepth: number;
+    activeEditorId?: string;
+};
+/** 共享历史管理器配置。 */
+export type SharedHistoryManagerOptions = {
+    /** 单个撤销/重做栈最多保留的记录数，默认 30，最大 30。 */
+    maxDepth?: number;
+    editorGroup?: ReportEditorGroupManager;
+    onChange?: (payload: SharedHistoryChangePayload) => void;
+    onRestore?: (entry: SharedHistoryEntry, direction: 'undo' | 'redo') => void;
+};
+/** 传给 Tiptap 的 doc JSON。 */
+export type TiptapDocument = {
+    type: 'doc';
+    content?: ProseMirrorNode[];
+};
+/** 自定义节点模板校验上下文。 */
+export type ReportTemplateValidationContext = {
+    validateChildren(nodes: TemplateNode[] | undefined): void;
+};
+/** 自定义节点模板转 ProseMirror 时的上下文。 */
+export type ReportTemplateConversionContext = {
+    toContent(nodes: TemplateNode[] | undefined): ProseMirrorNode[];
+    withFreshControlId<TAttrs extends ReportControlAttrs>(attrs: TAttrs): TAttrs;
+};
+/** 自定义节点和 mark 渲染 HTML 时的上下文。 */
+export type ReportHtmlRenderContext = {
+    mode: HtmlOutputMode;
+    renderContent(content: ProseMirrorNode[] | undefined, mode?: HtmlOutputMode): string;
+    renderBlockAttrs(node: ProseMirrorNode, className: string): string;
+    warn(code: ReportEditorErrorCode, message: string, detail?: unknown): void;
+};
+/** 自定义节点和 mark 渲染纯文本时的上下文。 */
+export type ReportPlainTextRenderContext = {
+    hideVisibilityGroups: boolean;
+    renderContent(content: ProseMirrorNode[] | undefined): string;
+    warn(code: ReportEditorErrorCode, message: string, detail?: unknown): void;
+};
+/** 单个报告节点的扩展描述。 */
+export type ReportNodeDescriptor = {
+    nodeName: string;
+    templateType: string;
+    dataNode?: string;
+    extension: Extensions[number];
+    isInline?: boolean;
+    isControl?: boolean;
+    supportsBlockFormatting?: boolean;
+    isNumberedBlock?: boolean;
+    validateAttrs?: (attrs: Record<string, unknown>) => void;
+    validateTemplate?: (node: TemplateCustomNode, context: ReportTemplateValidationContext) => void;
+    toProseMirrorNode?: (node: TemplateCustomNode, context: ReportTemplateConversionContext) => ProseMirrorNode;
+    renderHTML?: (node: ProseMirrorNode, context: ReportHtmlRenderContext) => string;
+    renderText?: (node: ProseMirrorNode, context: ReportPlainTextRenderContext) => string;
+};
+/** 单个报告 mark 的序列化描述。 */
+export type ReportMarkDescriptor = {
+    markName: string;
+    validateAttrs?: (attrs: Record<string, unknown>) => void;
+    renderHTML?: (mark: ProseMirrorMark, html: string, context: ReportHtmlRenderContext) => string;
+    renderText?: (mark: ProseMirrorMark, text: string, context: ReportPlainTextRenderContext) => string;
+};
+/** 一组可插拔报告能力的描述。 */
+export type ReportFeatureDescriptor = {
+    name: string;
+    extensions?: Extensions;
+    nodes?: ReportNodeDescriptor[];
+    marks?: ReportMarkDescriptor[];
+};
+/** feature 注册表对模板、序列化和扩展工厂提供的查询接口。 */
+export type ReportFeatureRegistry = {
+    features(): ReportFeatureDescriptor[];
+    descriptors(): ReportNodeDescriptor[];
+    markDescriptors(): ReportMarkDescriptor[];
+    extensions(): Extensions;
+    getByNodeName(nodeName: string): ReportNodeDescriptor | undefined;
+    getByTemplateType(templateType: string): ReportNodeDescriptor | undefined;
+    getMarkDescriptor(markName: string): ReportMarkDescriptor | undefined;
+    isControlNode(nodeName: string): boolean;
+    isNumberedBlockNode(nodeName: string): boolean;
+    controlNodeNames(): string[];
+    blockFormattingNodeNames(): string[];
+    numberedBlockNodeNames(): string[];
+};

package/dist/utils/ReportErrorDispatcher.d.ts

@@ -0,0 +1,13 @@
+import type { ReportEditorError } from '../types/index.js';
+/** 统一派发编辑器警告和错误事件。 */
+export declare class ReportErrorDispatcher {
+    private readonly listener?;
+    /** 创建错误派发器并绑定可选监听器。 */
+    constructor(listener?: ((error: ReportEditorError) => void) | undefined);
+    /** 派发 warning 级别事件。 */
+    warning(code: ReportEditorError['code'], message: string, detail?: unknown): void;
+    /** 派发 error 级别事件。 */
+    error(code: ReportEditorError['code'], message: string, detail?: unknown): void;
+    /** 调用外部错误监听器。 */
+    private emit;
+}

package/dist/utils/controlAttrs.d.ts

@@ -0,0 +1,10 @@
+import type { DropdownOption, StructuredFieldValue } from '../types/index.js';
+export type SerializedControlValueType = 'string' | 'number' | 'boolean' | 'null';
+/** 判断值是否符合结构化控件的持久化值类型。 */
+export declare function isStructuredFieldValue(value: unknown): value is StructuredFieldValue;
+/** 生成 edit HTML 中用于无损恢复控件值的类型标签。 */
+export declare function controlValueType(value: unknown): SerializedControlValueType;
+/** 从 edit HTML 的字符串属性恢复结构化控件值。 */
+export declare function parseTypedControlValue(value: string | null, type: string | null): StructuredFieldValue;
+/** 将未知下拉选项输入归一为可安全渲染的选项数组。 */
+export declare function normalizeDropdownOptions(value: unknown): DropdownOption[];

package/dist/utils/controlTextSegments.d.ts

@@ -0,0 +1,15 @@
+import type { ProseMirrorMark, ReportControlTextSegment, StructuredFieldValue } from '../types/index.js';
+/** 安全解析控件内部富文本分段 JSON。 */
+export declare function parseControlTextSegments(value: string | null): ReportControlTextSegment[] | undefined;
+/** 将控件值和可选分段归一为可渲染分段。 */
+export declare function normalizeControlTextSegments(value: StructuredFieldValue | undefined, segments: unknown): ReportControlTextSegment[];
+/** 序列化控件内部富文本分段，空分段不输出。 */
+export declare function serializeControlTextSegments(segments: ReportControlTextSegment[] | undefined): string | undefined;
+/** 从分段中读取纯文本。 */
+export declare function controlTextFromSegments(segments: ReportControlTextSegment[]): string;
+/** 将分段渲染为内置富文本 HTML。 */
+export declare function renderControlTextSegmentsHTML(segments: ReportControlTextSegment[], fallbackText: StructuredFieldValue | undefined): string;
+/** 判断两组 marks 是否等价。 */
+export declare function sameControlTextMarks(left: ProseMirrorMark[] | undefined, right: ProseMirrorMark[] | undefined): boolean;
+/** 合并相邻且 marks 相同的分段。 */
+export declare function mergeAdjacentSegments(segments: ReportControlTextSegment[]): ReportControlTextSegment[];

package/dist/utils/html.d.ts

@@ -0,0 +1,33 @@
+import type { StructuredFieldValue } from '../types/index.js';
+/** HTML 转义工具。 */
+export declare class HtmlEscaper {
+    /** 转义文本节点内容。 */
+    static text(value: unknown): string;
+    /** 转义 HTML 属性值。 */
+    static attr(value: unknown): string;
+}
+/** 构建安全 style 属性字符串的工具。 */
+export declare class HtmlStyleBuilder {
+    private readonly declarations;
+    /** 添加非空字符串或有限数字样式声明。 */
+    add(name: string, value: unknown): this;
+    /** 添加经过 CSS 值白名单校验的样式声明。 */
+    addSafe(name: string, value: unknown): this;
+    /** 输出完整 style 属性字符串。 */
+    toAttribute(): string;
+}
+/** CSS 样式值白名单清洗工具。 */
+export declare class CssValueSanitizer {
+    /** 按 CSS 属性名清洗单个样式值，非法值返回 undefined。 */
+    static sanitize(name: string, value: unknown): string | undefined;
+    private static hasUnsafeSyntax;
+    private static isSafeColor;
+    private static isSafeLength;
+    private static isSafeNumber;
+    private static isSafeFontFamily;
+}
+/** 结构化控件值判断工具。 */
+export declare class FieldValue {
+    /** 判断控件值是否为空。 */
+    static isEmpty(value: StructuredFieldValue | undefined): boolean;
+}

package/dist/utils/reportDocument.d.ts

@@ -0,0 +1,11 @@
+import type { ReportDocument, TiptapDocument } from '../types/index.js';
+export declare const DEFAULT_REPORT_DOCUMENT_VERSION = "1.0.3";
+/** 报告文档和 Tiptap doc JSON 的转换工具。 */
+export declare class ReportDocumentMapper {
+    /** 将报告文档转换为 Tiptap setContent 可接受的内容。 */
+    static toTiptapContent(content: ReportDocument | string | undefined): TiptapDocument | string | undefined;
+    /** 将 Tiptap JSON 包装为报告文档。 */
+    static fromTiptapJSON(json: unknown, version?: string): ReportDocument;
+    /** 创建空报告文档。 */
+    static empty(version?: string): ReportDocument;
+}

package/dist/utils/reportDocumentValidation.d.ts

@@ -0,0 +1,16 @@
+import type { Schema } from '@tiptap/pm/model';
+import type { ReportDocument, ReportEditorErrorCode, ReportFeatureRegistry } from '../types/index.js';
+/** 文档输入校验失败，携带应派发给业务方的错误码。 */
+export declare class ReportDocumentValidationError extends Error {
+    readonly code: ReportEditorErrorCode;
+    readonly detail?: unknown | undefined;
+    constructor(code: ReportEditorErrorCode, message: string, detail?: unknown | undefined);
+}
+/** 校验报告文档根结构和版本。 */
+export declare function assertReportDocumentRoot(value: unknown, expectedVersion: string): asserts value is ReportDocument;
+/** 校验文档节点的 JSON 形态和所有结构化控件 attrs。 */
+export declare function validateReportDocumentNodes(document: ReportDocument, registry: ReportFeatureRegistry): void;
+/** 使用 ProseMirror schema 做严格内容模型校验。 */
+export declare function validateProseMirrorDocument(document: ReportDocument, schema: Schema): void;
+/** 将任意 ProseMirror JSON 包装成报告文档后执行完整校验。 */
+export declare function validateReportDocument(document: ReportDocument, registry: ReportFeatureRegistry, schema: Schema): void;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@hmg-report-editor/core",
+  "version": "1.0.0",
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json && node ../../scripts/finalize-package-types.mjs .",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "@tiptap/core": "^2.12.0",
+    "@tiptap/extension-font-family": "^2.12.0",
+    "@tiptap/extension-text-style": "^2.12.0",
+    "@tiptap/extension-underline": "^2.12.0",
+    "@tiptap/pm": "^2.12.0",
+    "@tiptap/starter-kit": "^2.12.0"
+  },
+  "peerDependencies": {
+    "@tiptap/core": "^2.12.0"
+  }
+}