@printstack/print-studio 0.0.0-stage → 0.1.0

package/composables/use-z-index.d.ts

@@ -0,0 +1,9 @@
+import { InjectionKey, MaybeRefOrGetter } from 'vue';
+import { ZIndexOptions, ZIndexService } from '../core/z-index';
+export declare const ZIndexKey: InjectionKey<ZIndexService>;
+export declare function useZIndex(visible: MaybeRefOrGetter<boolean>, options?: MaybeRefOrGetter<ZIndexOptions>, injectedService?: ZIndexService): {
+    bringToFront: () => void;
+    close: () => void;
+    isTop: import('vue').ComputedRef<boolean>;
+    zIndex: import('vue').ComputedRef<number | undefined>;
+};

package/core/align.d.ts

@@ -0,0 +1,43 @@
+import { Rect } from './geometry';
+export type AlignMode = 'bottom' | 'hcenter' | 'left' | 'right' | 'top' | 'vcenter';
+export type AlignAxis = 'x' | 'y';
+/** 间距分布方向：h 为水平间距，v 为垂直间距 */
+export type SpacingDirection = 'h' | 'v';
+/** 对齐基准：选区范围 / 页面（画板）/ 关键对象 */
+export type AlignTarget = 'key' | 'page' | 'selection';
+export interface AlignItem {
+    box: Rect;
+    id: string;
+}
+export interface AlignOptions {
+    /** `key` 基准的关键对象 ID；不在参与对象内时退化为选区 */
+    keyId?: string;
+    /** `page` 基准的页面范围 */
+    pageBounds?: Rect;
+    target?: AlignTarget;
+}
+export interface DistributeSpacingOptions extends AlignOptions {
+    /** 固定间距（mm，可为负）；缺省按范围自动计算 */
+    spacing?: null | number;
+}
+/** 各对象沿所属轴的平移量；零位移的对象不出现 */
+export type AlignOffsets = Map<string, number>;
+export declare function alignModeAxis(mode: AlignMode): AlignAxis;
+export declare function spacingDirectionAxis(direction: SpacingDirection): AlignAxis;
+/** 基础对齐：把每个对象的基准点移到参照范围的对应位置 */
+export declare function computeAlignOffsets(items: AlignItem[], mode: AlignMode, options?: AlignOptions): AlignOffsets;
+/**
+ * 分布对象：按基准点（边缘或中心）等距，不保证空隙相等。
+ * 基准为选区 / 关键对象时首尾对象不动；基准为页面时首尾对象的外侧边缘贴齐页面边缘。
+ * 至少 3 个对象，否则返回 null。
+ */
+export declare function computeDistributeOffsets(items: AlignItem[], mode: AlignMode, options?: AlignOptions): AlignOffsets | null;
+/**
+ * 分布间距：令相邻对象之间的空白距离相等。
+ * - 未指定固定间距：基准为选区 / 关键对象时首尾对象不动，基准为页面时铺满页面；
+ *   至少 3 个对象。
+ * - 指定固定间距：有关键对象时关键对象不动、其余向两侧排布，否则以最先的对象为起点；
+ *   至少 2 个对象。
+ * 不足对象数量时返回 null。
+ */
+export declare function computeDistributeSpacingOffsets(items: AlignItem[], direction: SpacingDirection, options?: DistributeSpacingOptions): AlignOffsets | null;

package/core/binding-expression.d.ts

@@ -0,0 +1,25 @@
+import { DataSource, SchemaFieldType } from './types';
+export interface BindingVariable {
+    args: string[];
+    formatter?: string;
+    path: string;
+}
+export type TemplateSegment = {
+    expression: string;
+    kind: 'variable';
+    variable: BindingVariable;
+} | {
+    kind: 'text';
+    text: string;
+};
+export interface BindingVariableField {
+    label: string;
+    type?: SchemaFieldType;
+}
+export declare function parseBindingVariable(raw: string): BindingVariable;
+export declare function serializeBindingVariable(variable: BindingVariable): string;
+export declare function createDocumentVariablePath(name: string): string;
+/** 字符串 → 文本 / 变量片段序列；变量保留原始表达式，便于原样回写 */
+export declare function parseTemplateSegments(text: string): TemplateSegment[];
+/** 解析变量对应的字段展示名与数据类型；文档变量优先，其次数据源字段树 */
+export declare function resolveBindingVariableField(path: string, sources: DataSource[], relativeTo?: string): BindingVariableField | undefined;

package/core/binding-formatters.d.ts

@@ -0,0 +1,43 @@
+import { SchemaFieldType } from './types';
+export interface FormatterParamOption {
+    label: () => string;
+    value: string;
+}
+interface FormatterParamBase {
+    defaultValue: string;
+    key: string;
+    label: () => string;
+}
+export type FormatterParam = (FormatterParamBase & {
+    kind: 'number';
+    max: number;
+    min: number;
+}) | (FormatterParamBase & {
+    kind: 'select';
+    options: FormatterParamOption[];
+});
+/**
+ * 格式化修饰符的元数据：声明适用的字段类型与参数配置。
+ * 运行时求值由 data-context 的格式化器负责，名称必须与其一致。
+ */
+export interface BindingFormatterDefinition {
+    label: () => string;
+    name: string;
+    params: FormatterParam[];
+    types: SchemaFieldType[];
+}
+declare class BindingFormatterRegistry {
+    private readonly definitions;
+    get(name: string): BindingFormatterDefinition | undefined;
+    list(): BindingFormatterDefinition[];
+    /** 字段类型未知（如循环内相对路径）时无法约束，返回全部 */
+    listForType(type: SchemaFieldType | undefined): BindingFormatterDefinition[];
+    register(definition: BindingFormatterDefinition): () => void;
+}
+export declare const bindingFormatterRegistry: BindingFormatterRegistry;
+export declare function isFormatterCompatible(name: string, type: SchemaFieldType | undefined): boolean;
+/** 参数补全：缺省或空值取默认值，数量以定义为准 */
+export declare function normalizeFormatterArgs(definition: BindingFormatterDefinition, args: string[]): string[];
+export declare function createDefaultFormatterArgs(definition: BindingFormatterDefinition): string[];
+export declare const builtinBindingFormatters: readonly BindingFormatterDefinition[];
+export {};

package/core/data-context.d.ts

@@ -0,0 +1,73 @@
+import { ElementRegistry } from './element-registry';
+import { ElementNode } from './types';
+/** 循环上下文帧：区块展开时注入当前数组元素 */
+export interface LoopFrame {
+    /** 绑定的数组路径（如 'items'），便于诊断 */
+    collectionPath: string;
+    index: number;
+    item: unknown;
+}
+export interface DataContext {
+    deferExpression?: (path: string, raw: string) => string | undefined;
+    elements?: ElementRegistry;
+    /** 循环帧栈，索引大者为内层 */
+    loops: LoopFrame[];
+    /** 打印输入根数据（renderPrintTemplate 的 input） */
+    root: Record<string, unknown>;
+}
+export declare function createDataContext(root: Record<string, unknown>): DataContext;
+/** 派生子上下文：循环区块为每个副本注入当前 item */
+export declare function createChildContext(parent: DataContext, frame: LoopFrame): DataContext;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** 把 'items[0].name' 拆为 ['items', '0', 'name'] */
+export declare function splitPath(path: string): string[];
+/**
+ * 解析绑定路径：
+ * 1. `$index` → 最内层循环的当前序号
+ * 2. 首段在循环帧 item 上（由内向外查找）→ 相对当前行取值
+ * 3. 否则回退根数据（input 顶层键）
+ */
+export declare function resolvePath(context: DataContext, path: string): unknown;
+/**
+ * 按名称应用格式化器（number / thousand / currency / date / upper / lower）。
+ * 供表格列格式化等无法走内嵌表达式的场景复用；未知格式化器原样返回字符串。
+ */
+export declare function formatValue(value: unknown, formatter: string, args?: string[]): string;
+export declare const EXPRESSION_PATTERN: RegExp;
+export interface ParsedExpression {
+    args: string[];
+    formatter?: string;
+    path: string;
+}
+export declare function parseExpression(raw: string): ParsedExpression;
+export declare class WarningCollector {
+    private readonly items;
+    /** scope() 压入的定位上下文栈（如元素标签），add 时自动附加前缀 */
+    private readonly sourceStack;
+    add(message: string): void;
+    list(): string[];
+    /** 在定位上下文中执行 fn：期间产生的告警都带上 source 前缀（可嵌套） */
+    scope<T>(source: string, fn: () => T): T;
+}
+/** 告警定位标签：优先图层名，退化为「类型#短id」 */
+export declare function elementWarningSource(node: Pick<ElementNode, 'id' | 'name' | 'type'>): string;
+/**
+ * 解析字符串中的全部内嵌表达式。
+ * 整串恰为一个表达式时保留原生类型（无格式化器时），否则做字符串拼接。
+ * 取值失败输出空串并记录告警。
+ */
+export declare function resolveTemplateString(text: string, context: DataContext, warnings: WarningCollector, shouldResolve?: (path: string) => boolean): unknown;
+/** 字符串是否包含绑定表达式（设计时判断绑定状态用） */
+export declare function containsExpression(text: unknown): boolean;
+/** 去除模板表达式但保留静态文本，供设计态内容测量使用。 */
+export declare function stripTemplateExpressions(text: string): string;
+export declare function mapBindingProps(value: unknown, resolveString: (text: string) => unknown, skipKeys?: ReadonlySet<string>): unknown;
+/** 列标题猜测绑定字段：标题与 item 键名一致（或忽略大小写一致）时自动回填 */
+export declare function guessColumnBind(title: string, item: unknown): string;
+/**
+ * 解析单个元素：返回属性已全部求值的元素副本（原节点不变）。
+ * 1. 调用元素注册定义的结构化绑定能力；
+ * 2. 替换字符串属性内嵌表达式，跳过能力已求值的字段。
+ */
+export declare function resolveElementNode(node: ElementNode, context: DataContext, warnings: WarningCollector, mode?: 'design' | 'preview' | 'render'): ElementNode;
+export declare function resolveElementBindings(node: ElementNode, context: DataContext, warnings: WarningCollector): ElementNode;

package/core/data-source-path.d.ts

@@ -0,0 +1,10 @@
+import { DataSource, DataSourceField } from './types';
+export declare function transparentSourceRoot(source: DataSource): DataSourceField | undefined;
+export declare function findSchemaField(fields: DataSourceField[], path: string): DataSourceField | undefined;
+export declare function findSourceField(source: DataSource, path: string): DataSourceField | undefined;
+export declare function findSourceCollection(source: DataSource, path: string): DataSourceField | undefined;
+export declare function findBindingField(sources: DataSource[], path: string, relativeTo?: string): undefined | {
+    field: DataSourceField;
+    source: DataSource;
+};
+export declare function containsCollection(fields: DataSourceField[]): boolean;

package/core/data-source.d.ts

@@ -0,0 +1,26 @@
+import { DataSource, DataSourceField, PrintDocument, SchemaFieldType } from './types';
+/** 从任意 JSON 值推断字段结构（递归，数组取首元素结构作为元素字段） */
+export declare function inferSchemaFromValue(value: unknown): DataSourceField[];
+/**
+ * 打印输入构建：合并全部数据源——有 sampleData 用之，
+ * 否则按 schema 类型生成占位值，保证任何模板都能开箱预览。
+ */
+export declare function buildSampleInput(document: PrintDocument): Record<string, unknown>;
+/** 按 schema 字段树生成占位示例值 */
+export declare function sampleFromFields(fields: DataSourceField[]): unknown;
+export declare function sampleFromField(field: DataSourceField): unknown;
+/** 数据源扁平字段树 → 绑定选择器用的路径列表（含类型），数组字段标注 isCollection */
+export interface FieldPathOption {
+    /** array 元素内的相对路径列表（表格列绑定用） */
+    children?: FieldPathOption[];
+    isCollection: boolean;
+    label: string;
+    /** 绑定路径（不含数据源根键），如 'customer.name' */
+    path: string;
+    type: SchemaFieldType;
+}
+export declare function flattenSourceFields(fields: DataSourceField[], parentPath?: string): FieldPathOption[];
+/** 数据源 key 规范：作为 input 顶层键与表达式首段，仅允许字母数字下划线 */
+export declare function isValidSourceKey(key: string): boolean;
+/** 清理数据源数组：key 去重、剔除非法项 */
+export declare function normalizeDataSources(sources: DataSource[]): DataSource[];

package/core/document-expand.d.ts

@@ -0,0 +1,7 @@
+import { ElementRegistry } from './element-registry';
+import { PrintDocument } from './types';
+export interface ExpandResult {
+    document: PrintDocument;
+    warnings: string[];
+}
+export declare function expandDocument(template: PrintDocument, input: Record<string, unknown>, elements?: ElementRegistry): ExpandResult;

package/core/document-model.d.ts

@@ -0,0 +1,56 @@
+import { ElementRegistry } from './element-registry';
+import { PageLayout } from './page-layout';
+import { ElementNode, PageNode, PageTemplate, PrintDocument } from './types';
+export declare const DOCUMENT_VERSION = "1.0";
+export declare function createId(prefix?: string): string;
+export declare function createPage(width?: number, height?: number, name?: string, overrides?: Partial<Pick<PageNode, 'background' | 'height' | 'margins' | 'name' | 'width'>>): PageNode;
+/** 内置空白模板 id：页面 templateId 缺省即应用它 */
+export declare const BLANK_TEMPLATE_ID = "template-blank";
+export declare const NO_TEMPLATE_ID = "template-none";
+/** 内置空白模板：不可删除；无背景（页面沿用自身背景）且初始无内容，可被编辑 */
+export declare function createBlankTemplate(): PageTemplate;
+export declare function resolveTemplateInheritance(doc: PrintDocument, template: PageTemplate, pageNumber?: number, visited?: Set<string>): PageTemplate;
+export declare function resolveTemplateBase(doc: PrintDocument, template: PageTemplate, pageNumber?: number): PageTemplate | undefined;
+export declare function getTemplatePages(template: PageTemplate): PageNode[];
+export declare function getTemplatePage(template: PageTemplate, pageNumber: number): PageNode;
+/** 新建页面模板（容器画布尺寸取参考尺寸，缺省 A4 纵向） */
+export declare function createTemplate(name?: string, reference?: PageLayout): PageTemplate;
+export declare function createElement(type: string, overrides?: Partial<ElementNode>, elements?: ElementRegistry): ElementNode;
+/** 声明 measureSize 的元素按内容修正节点尺寸；未声明或返回空时保持不变 */
+export declare function applyMeasureSize(node: ElementNode, definition?: import('./element-registry').ElementDefinition | undefined): void;
+/** 点驱动节点缺 points 时按定义的 migrateRect 补齐并同步包围盒；其余节点原样返回 */
+export declare function normalizeNodePoints(node: ElementNode, definition?: import('./element-registry').ElementDefinition | undefined): ElementNode;
+export declare function cloneElement(node: ElementNode): ElementNode;
+export declare function findElement(doc: PrintDocument, id: string): null | {
+    index: number;
+    node: ElementNode;
+    page: PageNode;
+};
+/** 元素容器集合：文档页面 + 页面模板容器（模板元素与页面元素共用同一套编辑能力） */
+export declare function iterateElementContainers(doc: PrintDocument): PageNode[];
+/** 按 id 查找元素容器：先文档页面，再页面模板容器 */
+export declare function findElementContainer(doc: PrintDocument, containerId: string): PageNode | undefined;
+/** 解析页面应用的页面模板；无引用时解析到内置空白模板，悬空引用视为未应用 */
+export declare function resolveDocumentTemplate(doc: PrintDocument, page: Partial<Pick<PageNode, 'id'>> & Pick<PageNode, 'templateId'>, pageNumber?: number): PageTemplate | undefined;
+export declare function resolveDocumentPageLayout(doc: PrintDocument, page: PageLayout & Partial<Pick<PageNode, 'id' | 'templateId'>>, pageNumber?: number): PageLayout;
+/**
+ * 物化页面模板：把每页引用的模板内容（元素 / 背景）合并进页面本身。
+ * 输出剥离 templateId 与 templates 字段（渲染就绪文档），因此对同一文档
+ * 重复调用是幂等的——展开与解析管线即使先后各调一次也不会叠加。
+ * 模板元素深拷贝并重新编号，渲染在页面元素下方（索引在前即叠放更底层）；
+ * 无可合并内容时原样返回页面引用。
+ */
+export declare function resolvePageTemplates(doc: PrintDocument, resolveElement?: (node: ElementNode) => ElementNode, onWarning?: (message: string) => void): PrintDocument;
+/** 首次运行的默认文档：空白画布与内置示例数据源。初始模板由应用启动入口加载。 */
+export declare function createSeedDocument(): PrintDocument;
+export declare function assertDocumentHasPages(document: Partial<PrintDocument>): asserts document is Partial<PrintDocument> & {
+    pages: PageNode[];
+};
+/**
+ * 反序列化外部 JSON：宽容校验 + 字段补全 + 剔除未注册的元素类型。
+ * 返回 { document, skippedTypes }，调用方据此提示用户。
+ */
+export declare function deserializeDocument(raw: unknown, elements?: ElementRegistry): {
+    document: PrintDocument;
+    skippedTypes: string[];
+};

package/core/document-variable-resolver.d.ts

@@ -0,0 +1,10 @@
+import { DataContext, WarningCollector } from './data-context';
+import { DocumentVariableContext } from './document-variables';
+import { ElementNode, PrintDocument } from './types';
+export declare function createDocumentDataContext(input: Record<string, unknown>, variables?: DocumentVariableContext): DataContext;
+export declare function resolveDocumentVariableNode(node: ElementNode, variables: DocumentVariableContext, warnings: WarningCollector, skipKeys?: ReadonlySet<string>): ElementNode;
+export declare function resolveDocumentVariables(document: PrintDocument, warnings?: WarningCollector, now?: Date): PrintDocument;
+export declare function createDocumentBindingSession(input: Record<string, unknown>): {
+    context: DataContext;
+    resolve: (document: PrintDocument, warnings: WarningCollector) => PrintDocument;
+};

package/core/document-variables.d.ts

@@ -0,0 +1,23 @@
+import { DataSourceField } from './types';
+export interface DocumentVariableContext {
+    documentName: string;
+    now: Date;
+    pageCount: number;
+    pageName: string;
+    pageNumber: number;
+}
+export interface DocumentVariableDefinition {
+    label: () => string;
+    name: string;
+    resolve: (context: DocumentVariableContext) => unknown;
+    type: DataSourceField['type'];
+}
+declare class DocumentVariableRegistry {
+    private readonly definitions;
+    get(name: string): DocumentVariableDefinition | undefined;
+    list(): DocumentVariableDefinition[];
+    register(definition: DocumentVariableDefinition): () => void;
+}
+export declare const documentVariableRegistry: DocumentVariableRegistry;
+export declare const builtinDocumentVariables: readonly DocumentVariableDefinition[];
+export {};

package/core/element-group.d.ts

@@ -0,0 +1,73 @@
+import { ElementGroup, ElementNode, PageNode, PrintDocument } from './types';
+export type GroupTreeNode = GroupTreeElement | GroupTreeGroup;
+export interface GroupTreeElement {
+    kind: 'element';
+    node: ElementNode;
+}
+export interface GroupTreeGroup {
+    /** 子节点，顺序与 elements 一致：索引 0 在最底层 */
+    children: GroupTreeNode[];
+    group: ElementGroup;
+    kind: 'group';
+}
+export interface GroupTreeKey {
+    id: string;
+    kind: 'element' | 'group';
+}
+export type GroupMovePlacement = 'above' | 'below' | 'inside';
+/** 图层面板等展示用的行：自上而下，含缩进层级 */
+export type GroupDisplayRow = {
+    depth: number;
+    group: ElementGroup;
+    kind: 'group';
+    parentId?: string;
+} | {
+    depth: number;
+    kind: 'element';
+    node: ElementNode;
+    parentId?: string;
+};
+export type GroupReorderMode = {
+    edge: 'back' | 'front';
+} | {
+    offset: number;
+};
+/**
+ * 修复文档内所有元素组：剔除已不存在的成员、空组及违反连续 / 嵌套约束的组。
+ * 元素删除、页面删除、文档载入、复制粘贴后调用，保证组数据始终自洽。
+ */
+export declare function pruneElementGroups(document: PrintDocument): void;
+/** 由容器元素与其元素组构建可变的分组树（每次调用返回全新的节点，可随意修改） */
+export declare function buildGroupTree(container: PageNode, groups: ElementGroup[]): GroupTreeNode[];
+/** 树中全部元素，按叠放顺序（底 → 顶） */
+export declare function flattenGroupTree(tree: GroupTreeNode[]): ElementNode[];
+/** 把（修改后的）分组树写回文档：容器元素顺序与该容器的元素组同步更新 */
+export declare function applyGroupTree(document: PrintDocument, container: PageNode, tree: GroupTreeNode[]): void;
+/** 包含全部给定元素的最内层组（无则 undefined） */
+export declare function findCommonGroup(tree: GroupTreeNode[], elementIds: string[]): ElementGroup | undefined;
+/**
+ * 把元素编为一个新组。新组落在所选元素最内层公共父级中，位置取最靠上的成员处；
+ * 选中了组的部分成员时，整组一并纳入（保持组的完整性）。
+ */
+export declare function groupTreeElements(tree: GroupTreeNode[], elementIds: string[], group: ElementGroup): boolean;
+/** 解散组：成员原位提升到父级，叠放顺序不变 */
+export declare function ungroupTreeNode(tree: GroupTreeNode[], groupId: string): boolean;
+/**
+ * 把一批节点（元素或组）移动到锚点节点的上方 / 下方，或放进锚点组的最顶层。
+ * 落点成为锚点所在级别的成员，因此拖进组 / 拖出组都由落点自然决定。
+ * 锚点位于被移动节点内部时拒绝（返回 false）。
+ */
+export declare function moveTreeNodes(tree: GroupTreeNode[], movingKeys: GroupTreeKey[], anchor: GroupTreeKey, placement: GroupMovePlacement): boolean;
+/**
+ * 调整叠放顺序：每个单元只在自己所在的级别内移动（不会因为上移 / 下移而跳出组），
+ * 经过其他组时把该组视作一个整体越过。
+ */
+export declare function reorderTreeUnits(tree: GroupTreeNode[], selectedIds: string[], mode: GroupReorderMode): boolean;
+/**
+ * 展开分组树为自上而下的展示行；折叠的组只保留组行，隐藏其全部后代。
+ */
+export declare function buildGroupDisplayRows(tree: GroupTreeNode[], isCollapsed: (groupId: string) => boolean): GroupDisplayRow[];
+export declare function createElementGroup(document: PrintDocument, pageId: string, createId: (prefix: string) => string, name?: string): ElementGroup;
+export declare function getContainerGroups(document: PrintDocument, containerId: string): ElementGroup[];
+/** 宽容恢复持久化的元素组：只做结构清洗，约束修复交给 pruneElementGroups */
+export declare function deserializeElementGroups(raw: unknown): ElementGroup[];

package/core/element-registry.d.ts

@@ -0,0 +1,229 @@
+import { jsPDF } from 'jspdf';
+import { DataContext, WarningCollector } from './data-context';
+import { Point } from './geometry';
+import { PageLayout } from './page-layout';
+import { RenderResources } from './render/fonts';
+import { PdfDraw } from './render/pdf-draw';
+import { ElementNode, InspectorField, InspectorSection, PageNode, PrintDocument } from './types';
+export interface HtmlElementContext {
+    document: PrintDocument;
+    node: ElementNode;
+    page: PageNode;
+    props: Record<string, unknown>;
+}
+export interface PdfElementContext {
+    document: PrintDocument;
+    /** PDF 绘制助手（颜色 / 文本 / 图片等） */
+    draw: PdfDraw;
+    node: ElementNode;
+    page: PageNode;
+    /** jsPDF 实例，单位 mm，坐标原点为页面左上角；仅处理无旋转状态 */
+    pdf: jsPDF;
+    props: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export interface ElementOverflowContext {
+    node: ElementNode;
+    page: PageLayout;
+    warnings: WarningCollector;
+}
+export interface ElementOverflowResult {
+    continuation: {
+        elementId: string;
+        prepare: (target: ElementNode) => ElementNode;
+        templateId: string;
+    };
+    node: ElementNode;
+}
+export interface ElementMinSizeContext {
+    node: ElementNode;
+    props: Record<string, unknown>;
+}
+/** 内容自适应尺寸上下文：声明 measureSize 的元素在属性变化后按内容修正节点尺寸 */
+export interface ElementMeasureContext {
+    /** 设计态保留用户尺寸；预览态测量示例数据；输出态使用解析后的实际内容尺寸。 */
+    mode?: 'design' | 'preview' | 'render';
+    node: ElementNode;
+    props: Record<string, unknown>;
+}
+/** 打印跨页上下文：文档展开时对声明 paginate 的元素按可用页高切块 */
+export interface ElementPaginateContext {
+    getPage?: (chunkIndex: number) => PageLayout;
+    node: ElementNode;
+    page: PageLayout;
+    props: Record<string, unknown>;
+    warnings: WarningCollector;
+}
+export interface ElementPaginateChunk {
+    /** 该块高度（mm），展开时写回节点 height */
+    height: number;
+    /** 该块的属性片段（如切片后的 rows），展开时写回节点 props */
+    props: Record<string, unknown>;
+    y?: number;
+}
+/**
+ * 点驱动图形能力（线 / 钢笔路径……）：声明后元素的几何真身是 node.points
+ * （页面坐标顶点序列），x/y/width/height 派生为点集包围盒，rotation 恒为 0。
+ * 设计器据此切换交互形态：创建工具走「起点 → 终点」、选择框显示顶点手柄、
+ * 命中测试按图形本体而非包围盒。
+ */
+export interface PointBasedCapability {
+    /** 由起点 / 终点生成初始点集（页面坐标 mm）；start === end 表示单击创建 */
+    createPoints: (start: Point, end: Point) => Point[];
+    /**
+     * 图形本体的命中测试（页面坐标 mm）：框选 / 点击选区判断使用。
+     * 缺省退化为点是否落在节点包围盒内。
+     */
+    hitTest?: (ctx: {
+        node: ElementNode;
+        point: Point;
+        points: Point[];
+    }) => boolean;
+    /**
+     * 旧版定界框数据迁移为点集：仅历史文档（无 points 字段）加载时调用，
+     * 返回的点集会重新派生包围盒并把 rotation 归零。
+     */
+    migrateRect?: (node: ElementNode) => Point[];
+}
+export interface InlineEditCapability {
+    read: (node: ElementNode) => string;
+    style?: (node: ElementNode, pxPerMm: number) => Record<string, string>;
+    variableText?: boolean;
+    write: (node: ElementNode, value: string) => Partial<ElementNode>;
+}
+export interface FileDropCapability {
+    accepts: (file: File) => boolean;
+    create: (context: {
+        file: File;
+        page: PageNode;
+        point: Point;
+    }) => Partial<ElementNode> | Promise<Partial<ElementNode>>;
+}
+export interface ElementDefinition {
+    aspectRatio?: number;
+    /** 是否允许用户主动重置自动尺寸。 */
+    canResetAutoSize?: (node: ElementNode) => boolean;
+    /** 创建实例时的类型专属属性 */
+    createProps: () => Record<string, unknown>;
+    /** 拖拽创建时的默认尺寸（mm） */
+    defaultSize: {
+        height: number;
+        width: number;
+    };
+    fileDrop?: FileDropCapability;
+    /**
+     * 元素的固有最小尺寸（mm）：画布缩放手柄 / 多选整体缩放的下限，
+     * 例如表格不能缩小到行内容高度以下。未提供时使用全局默认最小值。
+     */
+    getMinSize?: (ctx: ElementMinSizeContext) => {
+        height: number;
+        width: number;
+    };
+    getResources?: (ctx: ElementMeasureContext) => RenderResources;
+    /** 图标名称，见 designer/components/ui/icons.ts */
+    icon: string;
+    /** 双击是否进入画布内联编辑（文本类元素） */
+    inlineEditable?: InlineEditCapability;
+    /** 属性面板 Schema */
+    inspectorSections: InspectorSection[];
+    /** 显示名称（工具栏 / 图层面板 / 属性面板） */
+    label: string;
+    /**
+     * 内容自适应尺寸：声明后创建元素、属性更新与文档展开（绑定求值后）
+     * 按返回值修正节点宽高（如表格 auto 高度模式跟随行数 / 字号变化）。
+     * 返回空对象表示保持不变。
+     */
+    measureSize?: (ctx: ElementMeasureContext) => Partial<Pick<ElementNode, 'height' | 'width'>>;
+    /**
+     * 旧文档属性归一化：反序列化与创建实例时调用（幂等）。
+     * 用于数据模型演进（如旧版边框字段迁移到新模型），元素自行声明迁移逻辑。
+     */
+    normalizeProps?: (props: Record<string, unknown>) => Record<string, unknown>;
+    /** 工具栏排序，越小越靠前 */
+    order: number;
+    overflow?: (ctx: ElementOverflowContext) => ElementOverflowResult | null;
+    /** 声明元素持有的页面扩展资源，供迁移、复制及生命周期管理复用。 */
+    pageExtensions?: {
+        rebind: (node: ElementNode, purpose: string, templateId: string, elementId: string) => void;
+        reconcile?: (document: PrintDocument, node: ElementNode) => void;
+        references: (node: ElementNode) => {
+            elementId: string;
+            purpose: string;
+            templateId: string;
+        }[];
+        resolveTarget?: (source: ElementNode, target: ElementNode, purpose: string) => ElementNode;
+        targetInspectorFields?: (purpose: string) => InspectorField[];
+    };
+    /**
+     * 打印跨页能力：文档展开阶段按可用页高把元素切成多块，块 0 留在原页，
+     * 其余块生成延续页，跨页公共内容由页面模板提供。返回 null 表示不分页。
+     */
+    paginate?: (ctx: ElementPaginateContext) => ElementPaginateChunk[] | null;
+    /** 点驱动能力（见 PointBasedCapability）：未声明时元素为定界框几何 */
+    pointBased?: PointBasedCapability;
+    /** 画布内的设计时预览组件 */
+    previewComponent?: unknown;
+    previewExpressionKeys?: readonly string[];
+    resolveBindings?: (ctx: {
+        context: DataContext;
+        node: ElementNode;
+        warnings: WarningCollector;
+    }) => {
+        props: Record<string, unknown>;
+        skipKeys?: ReadonlySet<string>;
+    };
+    /** 独立画布预览属性；声明后跳过数据绑定和表达式求值。 */
+    resolvePreviewProps?: (ctx: ElementMinSizeContext) => Record<string, unknown>;
+    settingsDialog?: {
+        layout: 'workspace';
+    };
+    /** 主工具快捷键（无修饰键） */
+    shortcut?: string;
+    /**
+     * 输出该元素的 HTML 片段（元素内部内容，不含定位外壳）。
+     * 必须是合法的 XHTML 片段（标签闭合、属性引号），因为 PDF 解析器
+     * 会通过 foreignObject 把这段 HTML 光栅化以支持旋转元素。
+     */
+    toHtml: (ctx: HtmlElementContext) => string;
+    /** 在 jsPDF 上绘制该元素（仅在无旋转时调用，旋转由解析器统一光栅化处理） */
+    toPdf: (ctx: PdfElementContext) => Promise<void> | void;
+    transformFields?: InspectorField[];
+    /** 全局唯一类型标识 */
+    type: string;
+    worker?: {
+        canExpand: (node: ElementNode) => boolean;
+        html: boolean;
+    };
+}
+export declare class ElementRegistry {
+    private definitions;
+    private listeners;
+    get(type: string): ElementDefinition | undefined;
+    /** 稳定排序的全部定义（按 order，再按 type） */
+    list(): ElementDefinition[];
+    register(definition: ElementDefinition): void;
+    subscribe(listener: () => void): () => void;
+    /** 生成工具栏用的元素工具项 */
+    toolItems(): {
+        icon: string;
+        label: string;
+        shortcut?: string;
+        type: string;
+    }[];
+    unregister(type: string): boolean;
+    private notify;
+}
+/** 全局元素注册表单例 */
+export declare const elementRegistry: ElementRegistry;
+/** 定义元素的便捷函数，仅为类型推断服务 */
+export declare function defineElement(definition: ElementDefinition): ElementDefinition;
+/** 解析上下文绑定的元素注册表；未绑定时回退全局单例 */
+export declare function resolveElementRegistry(context?: {
+    elements?: ElementRegistry;
+}): ElementRegistry;
+/**
+ * 元素本体的命中测试（页面坐标 mm）：点驱动元素用其 pointBased.hitTest，
+ * 其余元素退化为旋转后包围盒包含。
+ */
+export declare function hitTestNode(node: ElementNode, point: Point, elements?: ElementRegistry): boolean;
+export declare function paginateElement(registry: ElementRegistry, context: ElementPaginateContext): ElementPaginateChunk[] | null | undefined;

package/core/element-transform.d.ts

@@ -0,0 +1,12 @@
+import { ElementRegistry } from './element-registry';
+import { ElementNode } from './types';
+export type TransformKey = 'height' | 'opacity' | 'rotation' | 'width' | 'x' | 'y';
+export declare function getElementMinSize(node: ElementNode, elements?: ElementRegistry): {
+    height: number;
+    width: number;
+};
+export declare function constrainElementSize(node: ElementNode, patch: Partial<ElementNode>, elements?: ElementRegistry, options?: {
+    enforceMinimum?: boolean;
+}): Partial<ElementNode>;
+export declare function readTransformValue(node: ElementNode, key: TransformKey): number;
+export declare function transformValuePatch(node: ElementNode, key: TransformKey, value: unknown): Partial<ElementNode>;