@worm-vue3-print/common 0.0.0-stage → 1.4.0-beta.0

package/dist/print-designer.d.ts

@@ -0,0 +1,187 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { UploadDesignBackgroundFn, UploadImageFn } from '@worm-vue3-print/core/designer';
+import type { PrintFontDeclaration } from '@worm-vue3-print/core';
+export declare class PrintDesignerElement extends HTMLElement {
+    private root;
+    private store;
+    private format;
+    private unsub;
+    private state;
+    private geom;
+    /** 接管全局快捷键的实例（同页多设计器时最后一个交互者），见 bindKeys */
+    private static active;
+    private docKeydown;
+    private ro;
+    private roArea;
+    /** 工具栏收纳的尺寸驱动源：容器宽度变化不触发重绘，需观察器重跑后置遍 */
+    private toolbarRo;
+    private scrollPos;
+    private marquee;
+    private menu;
+    private guidePreview;
+    private zoneResizing;
+    /** 表格右键菜单状态：由 shell/table.ts 读写，每帧随 renderTableContextMenu 一起出图 */
+    private tableMenu;
+    private exprTarget;
+    private exprMountedFor;
+    /** 帮助弹窗：canvas 的 helpVisible（showHelp 为 false 时强制收起，见 set showHelp） */
+    private helpVisible;
+    private unmountHelp;
+    private drag;
+    private snapTimer;
+    /** 悬浮提示浮层：挂在 shadow root 上（canvas 的 useHoverTip / .pd-hover-tip 等价物） */
+    private hoverTipEl;
+    private hoverTipTimer;
+    private resize;
+    private raf;
+    private lastSelKey;
+    private chromeKey;
+    /** 宿主注入：图片上传，返回可访问 URL 或 data URL（对应 canvas 的 UPLOAD_IMAGE_KEY） */
+    uploadImage?: UploadImageFn;
+    /** 宿主注入：设计背景图上传，返回可直接 <img src> 的完整路径（对应 canvas 的 UPLOAD_DESIGN_BACKGROUND_KEY） */
+    uploadDesignBackground?: UploadDesignBackgroundFn;
+    /** 模板级字体声明（对应 canvas 的 fonts prop）：注入 @font-face、列出字体候选、随保存/导出写回模板 */
+    private _fonts?;
+    set fonts(v: readonly PrintFontDeclaration[] | undefined);
+    get fonts(): readonly PrintFontDeclaration[] | undefined;
+    /** 字体声明的 @font-face 样式节点（挂在 shadow root 内，设计期所见即出图所得） */
+    private fontFaceStyle;
+    private docFontFaceStyle;
+    constructor();
+    set template(v: unknown);
+    get template(): unknown;
+    set fields(v: unknown);
+    set isEdit(v: boolean);
+    /** canvas 口径：showHelp 控制「帮助入口 + 弹窗」，关闭时强制收起已打开的弹窗 */
+    set showHelp(v: boolean);
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    connectedCallback(): void;
+    /** 面板折叠态：与 canvas 的 useStudioChrome 共用 localStorage 键，同一浏览器里两边偏好互通 */
+    private readChrome;
+    private persistChrome;
+    disconnectedCallback(): void;
+    /**
+     * 注入 @font-face：既进 shadow root（画布文档内），也进宿主文档 head。
+     * 原因：`@font-face` 只在文档作用域参与字体加载，shadow 内单独声明不会触发下载，
+     * 只挂 shadow 会出现「computed font-family 正确但字形回落」。canvas 本身就注到 document。
+     */
+    private applyFontFace;
+    /** 与 canvas 的 templateJsonWithFonts 同口径：宿主字体声明随保存/导出一起出图 */
+    private templateJsonWithFonts;
+    getTemplateJson(): string;
+    loadTemplate(input: unknown): void;
+    save(): void;
+    /** 拼版配置校验：getTemplateJson 是旁路，宿主导出/另存时需自行调用拦截 */
+    validateTemplate(): import("@worm-vue3-print/core").TilingIssue[];
+    /**
+     * 出纸裁切提示（旋转外接盒顶越页首、元素超出纸面左右缘），与 canvas 同名同口径。
+     * 预估口径：编辑期无实测高，自适应行高按设计盒估算 ⇒ 只提示、不阻断保存。
+     */
+    getGeometryWarnings(): string[];
+    private applyTemplate;
+    private openExpression;
+    private closeExpression;
+    private syncExpression;
+    private openHelp;
+    private closeHelp;
+    private syncHelp;
+    /** 回写：targetPath 为 options.<字段>（含 tableRows[r].cells[c] 下标形）/ watermark.content */
+    private applyExpression;
+    /** 画布双击元素：与 canvas 的 DBL_EDITABLE_FIELD 白名单一致，锁定元素只选中不弹框 */
+    private dblEditElement;
+    /** 表格单元格双击：定位合并主格后编辑其 formatter（对照 canvas 的 onDblClickCell） */
+    private dblEditCell;
+    private get ctx();
+    private canvasUi;
+    private repaint;
+    private paint;
+    /**
+     * 自动缩小实测遍：与 canvas 的 useShrinkFit 同一算法（core/browser fitTextNode），
+     * 让「设计态看到的字号」等于「出纸字号」。覆盖元素级与表格单元格级两类探针节点。
+     */
+    private applyShrinkFit;
+    private measureRuler;
+    /**
+     * 画布区尺寸变化（宿主改宽、面板折叠、窗口缩放、字体到位后重排）后重画标尺。
+     * 对应 canvas 的 ResizeObserver(measureRuler)：整体重绘会换掉节点，故按当前节点重新挂载。
+     */
+    private observeCanvasArea;
+    private syncRulers;
+    /** 拖拽过程中只重写受影响元素的几何，避免全量重渲染打断输入态 */
+    private patchElementDom;
+    private fire;
+    private onDrop;
+    /** 纸面 mm 落点（对应 canvas 的 toPaperPoint）：不取整，越出纸张左上角即视为无效 */
+    private pointToPaperMm;
+    private onCanvasMouseDown;
+    private onCanvasMouseMove;
+    private clearCoord;
+    private onContextMenu;
+    private onElementContextMenu;
+    private openMenu;
+    private startMarquee;
+    /**
+     * 双击判定：同一目标两次左键 mousedown，间隔 <500ms 且位移 ≤6px 即视为一次双击。
+     * 不能用原生 dblclick：paint 是 clear(shell) 全量重建，第一击选中元素后旧节点即被替换，
+     * 第二击落在新节点上时 Chrome 不再派发 dblclick（实测 30ms 间隔亦为空）；
+     * canvas 侧 Vue 原地 patch 节点不换，才没有这个问题。
+     */
+    private taps;
+    private isDoubleTap;
+    private beginDrag;
+    /** 把 `.drag-ghost` 与 `.drag-preview` 同步到当前拖拽态（拖拽中不做整体重绘，定点改 DOM） */
+    private syncDragGhost;
+    /**
+     * Alt+拖拽落点生成副本（对应 canvas BaseElement.onDragEnd 的 alt 分支 + onCloneElement）：
+     * 原元素留在原位、副本继承其全部样式但剥离组身份，选中落在副本、记一条历史。
+     */
+    private finishAltClone;
+    /** 吸附闪烁点（对应 canvas CanvasPaper.showSnapIndicator：300ms 后自动消失，重复吸附则重启动画） */
+    private flashSnapIndicator;
+    private beginResize;
+    private beginZoneResize;
+    private beginGuideDrag;
+    private beginRulerGuide;
+    /**
+     * 标尺拖出参考线时的 mm 换算。canvas 是 `(clientX - rulerRect.left - originPx) / pxPerMM`，
+     * 而 originPx = paperRect.left - areaRect.left - 尺宽、rulerRect.left = areaRect.left + 尺宽，
+     * 两项相消后等价于「相对纸张本体的像素距离 / pxPerMM」——这里直接用后一形式，
+     * 早期实现漏掉尺宽与滚动量，同一屏幕点会算出与 canvas 不同的 mm（成对拖拽对拍揭穿）。
+     */
+    private rulerPointToMM;
+    /**
+     * 统一缩放入口（对应 canvas CanvasArea.applyZoom）：以容器内锚点为不动点，
+     * 缩放后校正滚动位置，保证锚点下的内容不漂移。
+     * 容器存在非对称 padding（44/28/32/44），锚点换算必须扣除，否则每次漂移 pad*(ratio-1)。
+     */
+    private applyZoom;
+    /** 工具栏放大/缩小：与滚轮同一乘性步进，以视口几何中心为锚点 */
+    private zoomByStep;
+    /** 适应窗口（对应 canvas PrintDesigner.onFitWindow + CanvasArea.fitToWindow） */
+    private fitToWindow;
+    private onWheel;
+    private onScroll;
+    private bindPointer;
+    private showHoverTip;
+    private hideHoverTip;
+    private manualGuides;
+    /** 仅重绘吸附引导线，避免拖拽中全量重建 DOM */
+    private paintGuidesOnly;
+    private bindKeys;
+    /** document 级快捷键监听：随挂载/卸载成对增删（重连场景 store 已存在，bindKeys 不再执行） */
+    private attachDocKeys;
+    private detachDocKeys;
+    private onGlobalKeydown;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'print-designer': PrintDesignerElement;
+    }
+}
+export declare function definePrintDesigner(tag?: string): string;

package/dist/shell/binding.d.ts

@@ -0,0 +1,21 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { BindingDescriptor, RuntimeElement } from '@worm-vue3-print/core/designer';
+import type { ShellCtx } from './controls';
+import type { DesignerStore } from '../core/store';
+/**
+ * 统一解析带点分段与数组下标的 targetPath 为段/索引混排数组（与 canvas 的 parsePath 同实现）
+ * 例：'options.formatter' → ['options','formatter']
+ * 例：'options.tableRows[0].cells[1].formatter' → ['options','tableRows',0,'cells',1,'formatter']
+ */
+export declare function parseBindingPath(targetPath: string): (string | number)[];
+export declare function readBindingValue(element: RuntimeElement, targetPath: string): string;
+/** 写回：canvas 的 setBindingValue 是「先赋值、后 recordHistory」，此处保持同序 */
+export declare function writeBindingValue(store: DesignerStore, element: RuntimeElement, targetPath: string, value: string): void;
+/** 当前应渲染的绑定项：表格有选区时只出选中单元格，否则按注册表（与 canvas 同口径） */
+export declare function bindingDescriptorsFor(ctx: ShellCtx, el: RuntimeElement): BindingDescriptor[];
+export declare function bindingGroup(ctx: ShellCtx, el: RuntimeElement): import("../core/h").El;

package/dist/shell/canvas.d.ts

@@ -0,0 +1,59 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { TemplateData } from '@worm-vue3-print/core/designer';
+import type { ShellCtx } from './controls';
+import type { RulerGeom } from './ruler';
+export interface CanvasUI {
+    geom: RulerGeom;
+    marquee: {
+        visible: boolean;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    };
+    contextMenu: {
+        visible: boolean;
+        x: number;
+        y: number;
+        flipX: number;
+        flipY: number;
+        targetId: string | null;
+    };
+    guidePreview: {
+        type: 'vertical' | 'horizontal';
+        position: number;
+    } | null;
+    zoneResizing: 'header' | 'footer' | null;
+    scrollX: number;
+    scrollY: number;
+}
+/** 三区矩形（mm，纸面坐标系）：上边距→页眉→内容→页脚→下边距（同 CanvasPaper.zoneRectsMM） */
+export declare function zoneRectsMM(t: TemplateData, paper: {
+    width: number;
+    height: number;
+}): {
+    header: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    content: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+    footer: {
+        left: number;
+        top: number;
+        width: number;
+        height: number;
+    };
+};
+export declare function renderCanvasArea(ctx: ShellCtx, ui: CanvasUI): import("../core/h").El;

package/dist/shell/code.d.ts

@@ -0,0 +1,11 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { RuntimeElement } from '@worm-vue3-print/core/designer';
+export declare function renderQrcode(el: RuntimeElement): import("../core/h").El;
+export declare function renderBarcode(el: RuntimeElement): import("../core/h").El;
+/** DOM 落位后绘制所有码类元素 */
+export declare function hydrateCodes(root: ShadowRoot, elements: RuntimeElement[]): void;

package/dist/shell/color-picker.d.ts

@@ -0,0 +1,44 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { El } from '../core/h';
+export interface ColorPickerOptions {
+    /** 当前色值；空串/undefined 均视为「未设置」 */
+    value?: string;
+    /** 是否允许清除（canvas 边框等必填场景传 false），默认 true */
+    clearable?: boolean;
+    /** 触发按钮 title（canvas 侧为色值或「自动」，本包保留调用方传入的字段名语义） */
+    title?: string;
+    /** 追加在触发钮上的类名（canvas 给组件根挂的 class 会与其自身类名合并，如 `page-bg-picker`） */
+    triggerClass?: string;
+    /** 选中回调；undefined 表示清除（canvas emit '' 的等价归一） */
+    onChange: (value: string | undefined) => void;
+}
+export declare function parseHex(color: string): {
+    r: number;
+    g: number;
+    b: number;
+} | null;
+export declare function normalizeHex(color: string): string;
+export declare function rgbToHex({ r, g, b }: {
+    r: number;
+    g: number;
+    b: number;
+}): string;
+export declare function rgbToHsv(r: number, g: number, b: number): {
+    h: number;
+    s: number;
+    v: number;
+};
+export declare function hsvToRgb(h_: number, s: number, v: number): {
+    r: number;
+    g: number;
+    b: number;
+};
+/** 触发按钮（对应 canvas 的 button.preset-color-trigger）；点击在挂载根上开/关面板 */
+export declare function colorPicker(opts: ColorPickerOptions): El;
+/** 关闭当前打开的面板并解除全部监听（宿主 disconnectedCallback 亦可用） */
+export declare function closeColorPicker(): void;

package/dist/shell/controls.d.ts

@@ -0,0 +1,138 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { PrintFontDeclaration } from '@worm-vue3-print/core';
+import type { DesignerStore } from '../core/store';
+/** 外壳局部 UI 状态（不落模板数据，仅影响渲染） */
+export interface ShellState {
+    leftTab: 'elements' | 'fields' | 'layers';
+    leftCollapsed: boolean;
+    propTab: 'element' | 'page';
+    propCollapsed: boolean;
+    /** 打开的下拉面板 id（同一时刻只允许一个） */
+    openDd: string | null;
+    /**
+     * 「更多」收纳面板的开关。与 openDd 分持：面板内还嵌着对齐/边框等下拉，
+     * 共用一个开关键会让内层下拉一打开就把外层「更多」顶掉（canvas 是每个实例独立 open）。
+     */
+    openMore?: boolean;
+    /** 字段搜索关键字（仅影响左栏字段树） */
+    fieldSearch?: string;
+    /** 折叠的字段分组 key */
+    collapsedGroups: Set<string>;
+    /** 正在行内重命名的页面下标 */
+    renamingPage: number | null;
+    renameText?: string;
+    /** 属性台搜索关键字（门控分组与字段，对应 canvas PropertyPanel 的 searchText） */
+    propSearch?: string;
+    /** 展开中的字体下拉：整体重绘模型下必须外置，否则 repaint() 会让候选列表闪断 */
+    fontOpen?: {
+        id: string;
+        query: string;
+        highlighted: number;
+    } | null;
+}
+/** 外壳渲染上下文：工具栏动作以 fire(name, arg) 上报，由自定义元素分发 */
+export interface ShellCtx {
+    store: DesignerStore;
+    /** 格式栏语义内核（shell/format-bar.ts 需要；由自定义元素注入） */
+    format: import('../core/format').FormatToolbar;
+    state: ShellState;
+    repaint: () => void;
+    fire: (action: string, arg?: unknown) => void;
+    /** 宿主能力开关 */
+    showHelp: boolean;
+    isEdit: boolean;
+    /** 宿主注入能力（图片上传、设计背景上传、字体清单），未注入时相关入口置灰 */
+    host: {
+        uploadImage?: (file: File) => Promise<string>;
+        uploadDesignBackground?: (file: File) => Promise<string>;
+        /** 模板级字体声明，与 canvas 的 PrintDesigner `fonts` prop 同类型（裸字符串族名不参与候选，与画布一致） */
+        fonts?: readonly PrintFontDeclaration[];
+    };
+}
+/** 带图标的工具栏按钮（对应 canvas 的 .tb-btn.tb-icon） */
+export declare function tbIconBtn(ctx: ShellCtx, iconName: string, action: string, opts: {
+    tip: string;
+    disabled?: boolean;
+    on?: boolean;
+    danger?: boolean;
+    arg?: unknown;
+    test?: string;
+}): import("../core/h").El;
+/** 下拉壳：触发钮 + 面板，面板内容由调用方给出（对应 canvas 的 ToolbarDropdown） */
+export declare function dropdown(ctx: ShellCtx, id: string, opts: {
+    tip: string;
+    icon?: string;
+    text?: string;
+    textClass?: string;
+    disabled?: boolean;
+    testId?: string;
+    panelClass?: string;
+}, panel: unknown[]): import("../core/h").El;
+/** 步进数字输入（对应 canvas 的 property/StepperInput） */
+export declare function stepper(opts: {
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    placeholder?: string;
+    disabled?: boolean;
+    onCommit: (v: number) => void;
+}): import("../core/h").El;
+/** 属性行：pd-field > pd-label(.pd-label-t + 恢复默认值) + 控件 */
+export declare function field(label: string, control: unknown, hint?: string, reset?: unknown): import("../core/h").El;
+/** 字段说明图标：说明不常驻行内，悬浮或点击聚焦时才浮出（对应 canvas 的 button.pd-help） */
+export declare const labelHelp: (tip: string) => import("../core/h").El;
+/** 带说明图标的属性行：与 field() 同结构，差别只在说明挂图标而非常驻 .pd-hint 段落 */
+export declare function fieldHelp(label: string, control: unknown, tip: string, reset?: unknown): import("../core/h").El;
+/**
+ * 「恢复默认值」按钮，与 canvas 的 property/ResetButton.vue 逐字同构。
+ * 落点派生自 base[propKey]：判据一律 === 比出厂值，base 里取到 undefined 即「未设」，
+ * 写回它天然等于删键。0 与 undefined 是两个状态，不得用 ?? / || 归并。
+ * 外壳是全量重绘模型，灰/亮在构造时求值即可，不需要响应式。
+ * 按钮不带任何文本子节点——属性搜索按 .pd-label 的 textContent 匹配，写字会污染命中。
+ */
+export declare function resetButton(o: {
+    target: Record<string, any>;
+    base: Record<string, any>;
+    propKey: string;
+    /** 提示语数值：仅用于文案，不参与判定 */
+    tipValue?: number | string;
+    tipUnit?: string;
+    /** 覆盖整条提示（单元格级固定用「跟随表格默认」，回落目标是该表自己的默认） */
+    tipOverride?: string;
+    /** 覆盖写回通道：单元格组必须整选区恢复，不能让按钮只改当前展示的那一个 cell 对象 */
+    write?: (value: any) => void;
+    /** 写回后的收尾（重绘 / 记历史）；不提供时只改对象 */
+    onReset?: () => void;
+    /** 多选批量档：不显示"已改"脏点（判据取自单格会误导），但按钮恒可点，写回整选区 */
+    force?: boolean;
+}): import("../core/h").El;
+/** 分节标题（对应 canvas 的 h3.pd-divider） */
+export declare const divider: (text: string) => import("../core/h").El;
+/** 颜色触发钮：预设色板面板（移植 canvas 的 PresetColorPicker.vue，面板实现见 shell/color-picker.ts）。
+ * onPick 收到的 undefined 表示「清除颜色」：canvas 侧 emit '' 后由消费方归一化为未设置，
+ * 本包在触发器层直接归一后透传，调用方 patch 即删除该颜色属性（签名保持 (v: string) 不变）。 */
+export declare function colorTrigger(value: string | undefined, onPick: (v: string) => void, title?: string, triggerClass?: string): import("../core/h").El;
+/** 单选组（对应 canvas 的 .pd-radio-group） */
+export declare function radioGroup(name: string, options: {
+    value: string;
+    label: string;
+}[], current: string, onChange: (v: string) => void, twoCol?: boolean): import("../core/h").El;
+/**
+ * 裸下拉（无 label 包裹，用于 .border-style-row 这类横向控件行）。
+ * 不能只靠 <option selected> 属性：happy-dom/部分内核在"首项未选中、第三项选中"时会回落到第二项，
+ * 必须建真节点后显式 select.value = 当前值（与 selectField 同一套可靠赋值）。
+ */
+export declare function plainSelect(value: string, options: {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}[], onChange: (v: string) => void, attrs?: {
+    className?: string;
+    width?: string;
+}): HTMLSelectElement;

package/dist/shell/crop-anchor.d.ts

@@ -0,0 +1,29 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { ShellCtx } from './controls';
+export interface CropAnchorOpts {
+    fieldKey: string;
+    label: string;
+    /** 容器类名：canvas 只在单元格台包一层 `pd-cell-anchor`（`TableCellGroup.vue`），元素台没有包层；缺省沿用本包 `pd-crop-anchor` */
+    containerClass?: string;
+    /** 已解析的图片地址（表达式由宿主求值后传入）；为空则回落内置示例图 */
+    src: string;
+    widthMm: number;
+    heightMm: number;
+    /** 缩放模式（CSS object-fit 原值，缺省按 contain）：可挪余量按它逐轴结算 */
+    fit?: string;
+    /** 剪裁放大比例（%）：只有 cover 消费，铺满后把画面再推大这么多 */
+    scale?: number;
+    /** 行尾「恢复默认值」图标：落点由宿主按所在层构造（元素级派生出厂值、单元格级删自身值），
+     *  本组件只负责把它摆进标签行右端，与 canvas 的 CropAnchorField 同一 DOM 结构 */
+    resetAnchor?: unknown;
+    resetScale?: unknown;
+    value?: string;
+    onCommit: (value: string | undefined) => void;
+    onScaleCommit: (value: number | undefined) => void;
+}
+export declare function cropAnchorField(ctx: ShellCtx, o: CropAnchorOpts): import("../core/h").El;

package/dist/shell/elements.d.ts

@@ -0,0 +1,27 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import { mmToPx } from '@worm-vue3-print/core/designer';
+import type { RuntimeElement } from '@worm-vue3-print/core/designer';
+import type { ShellCtx } from './controls';
+/** 元素几何与边框（对齐 BaseElement.elementStyle） */
+export declare function elementStyle(el: RuntimeElement, followMemberIds?: Set<string>): Record<string, string>;
+/** 文本与长文本共用的行内样式：与 canvas 的 TextElement / LongTextElement 逐项一致（差异按类型分支） */
+export declare function textLikeStyle(el: RuntimeElement): {
+    style: Record<string, string>;
+    fit: import("@worm-vue3-print/core").TextFit;
+};
+export declare function imageStyle(el: RuntimeElement): Record<string, string>;
+/** 选中角标文本：与 canvas BaseElement 的 posLabel 逐字一致（四舍五入到整数 mm） */
+export declare function positionLabel(o: {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}): string;
+export declare function renderDesignElement(ctx: ShellCtx, el: RuntimeElement, followMemberIds?: Set<string>): import("../core/h").El;
+/** mm → px（供画布几何换算复用同一口径） */
+export { mmToPx };

package/dist/shell/expression-editor.d.ts

@@ -0,0 +1,33 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { PrintBusinessField } from '@worm-vue3-print/core/designer';
+import type { El } from '../core/h';
+export interface ExpressionEditorTarget {
+    /** 元素 id（表格单元格时用于定位） */
+    elementId: string;
+    /** 要写回的目标路径，如 'options.formatter' 或 'cell:<rowId>:<colIndex>' */
+    targetPath: string;
+    /** 当前表达式文本 */
+    value: string;
+    /** 可选：字段绑定模式的初始字段 key */
+    binding?: string;
+}
+export interface ExpressionEditorOptions {
+    fields: PrintBusinessField[];
+    /** 求值预览用的样例行数据 */
+    demoData?: Record<string, any>;
+    /** 关闭弹窗 */
+    onClose: () => void;
+    /** 点确定：把最终表达式回写 */
+    onApply: (next: {
+        formatter?: string;
+        binding?: string;
+        title?: string;
+    }) => void;
+}
+/** 渲染表达式编辑器弹窗的 DOM 描述（内部已含遮罩层，render 进 shadow 根下即可） */
+export declare function renderExpressionEditor(opts: ExpressionEditorOptions, target: ExpressionEditorTarget): El;

package/dist/shell/flow-list.d.ts

@@ -0,0 +1,11 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { RuntimeElement } from '@worm-vue3-print/core/designer';
+/** 与 canvas FlowListElement 的 DESIGN_FALLBACK_ITEMS 逐字一致：新拖入的元素也要看得见形状 */
+export declare const FLOW_LIST_DEMO_ITEMS: string[];
+export declare function flowListCells(el: RuntimeElement, data?: Record<string, any>[]): string[];
+export declare function renderFlowListElement(el: RuntimeElement, data?: Record<string, any>[]): import("../core/h").El;

package/dist/shell/font-select.d.ts

@@ -0,0 +1,24 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import type { FontCatalogOption, PrintFontDeclaration } from '@worm-vue3-print/core';
+import type { ShellState } from './controls';
+export interface FontSelectOptions {
+    /** 实例标识：同一时刻只允许一个字体下拉处于展开态 */
+    id: string;
+    /** 外壳状态：展开态落在这里，跨重绘保持 */
+    state: ShellState;
+    /** 宿主注入的字体清单：条目须是字体声明（family/label，`files` 由宿主侧携带），裸字符串不进候选——与画布同一判据 */
+    fonts?: readonly (FontCatalogOption | PrintFontDeclaration | null | undefined)[];
+    /** 当前族名；undefined 表示未设置，走全局兜底字体栈 */
+    value?: string;
+    /** 空值行文案（同时用作输入框 placeholder） */
+    placeholder?: string;
+    /** 禁用（如格式工具栏无可用目标时置灰） */
+    disabled?: boolean;
+    onChange: (value: string | undefined) => void;
+}
+export declare function renderFontSelect(opts: FontSelectOptions): HTMLElement;

package/dist/shell/format-bar.d.ts

@@ -0,0 +1,15 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+import { field } from './controls';
+import type { ShellCtx } from './controls';
+import type { FormatToolbar } from '../core/format';
+type FormatCtx = ShellCtx & {
+    format: FormatToolbar;
+};
+export declare function renderFormatBar(ctx: FormatCtx): import("../core/h").El;
+/** 供状态栏/属性面板复用的排版行（保持与 canvas 同类名） */
+export { field as formatField };

package/dist/shell/help-content/changelog.d.ts

@@ -0,0 +1,12 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+declare const _default: {
+    id: string;
+    title: string;
+    content: string;
+};
+export default _default;

package/dist/shell/help-content/faq.d.ts

@@ -0,0 +1,12 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+declare const _default: {
+    id: string;
+    title: string;
+    content: string;
+};
+export default _default;

package/dist/shell/help-content/features.d.ts

@@ -0,0 +1,12 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+declare const _default: {
+    id: string;
+    title: string;
+    content: string;
+};
+export default _default;

package/dist/shell/help-content/getting-started.d.ts

@@ -0,0 +1,12 @@
+/*!
+ * @worm-vue3-print/common v1.4.0-beta.0
+ * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
+ * SPDX-License-Identifier: MIT
+ */
+declare const _default: {
+    id: string;
+    title: string;
+    content: string;
+};
+export default _default;