@worm-vue3-print/core 1.3.7 → 1.3.8

package/dist/designer/index.d.cts

@@ -1,12 +1,12 @@
 /*!
- * @worm-vue3-print/core v1.3.7
+ * @worm-vue3-print/core v1.3.8
  * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
  * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
  * SPDX-License-Identifier: MIT
  */
-import { E as ElementBorderSide, b as ElementOptions, c as TemplateData, d as TableRow, e as TableCellBorder, f as TableCell, g as TableRowType, h as ElementType, i as RuntimeElement, j as ElementZone, k as PrintBusinessField, B as BindingDescriptor, l as ElementRect, A as AdsorbResult, m as ResizePoint } from '../driver-Dzr2Aikx.cjs';
-export { n as AlignLine, o as DesignBackground, p as ElementBorderEdge, q as ElementFieldBinding, r as MultiPageTemplateData, s as PaginationConfig, t as PaperSize, u as PrintElementData, v as PrintElementTypeMeta, w as TableCellBorders, x as TableCellType, y as TablePaginationConfig, z as TableSelection, F as TemplateElement, G as TextAlign, H as TextFit, U as UploadDesignBackgroundFn, I as UploadImageFn, V as VerticalAlign, W as WatermarkOptions } from '../driver-Dzr2Aikx.cjs';
-export { C as CellFitRowKind, D as DEFAULT_SHRINK_MIN_FONT_SIZE_PT, F as FitFontSize, M as MIN_SHRINK_FONT_SIZE_PT, c as cellFitCapMm, a as cellFitKey, b as cellFitWidthMm, f as floorFontSize, p as parseCellFitKey, r as resolveCellTextFit, d as resolveElementTextFit, e as resolveShrinkMinFontSize, g as roundFontSize } from '../ports-Bin4xmo0.cjs';
+import { E as ElementBorderSide, b as ElementOptions, c as TemplateData, d as TableRow, e as TableCellBorder, f as TableCell, g as TableRowType, h as ElementType, i as RuntimeElement, j as ElementZone, k as PrintBusinessField, B as BindingDescriptor, l as ElementRect, A as AdsorbResult, m as ResizePoint } from '../driver-hJxBl2_n.cjs';
+export { n as AlignLine, o as DesignBackground, p as ElementBorderEdge, q as ElementFieldBinding, r as MultiPageTemplateData, s as PaginationConfig, t as PaperSize, u as PrintElementData, v as PrintElementTypeMeta, w as TableCellBorders, x as TableCellType, y as TablePaginationConfig, z as TableSelection, F as TemplateElement, G as TextAlign, H as TextFit, U as UploadDesignBackgroundFn, I as UploadImageFn, V as VerticalAlign, W as WatermarkOptions } from '../driver-hJxBl2_n.cjs';
+export { C as CellFitRowKind, D as DEFAULT_SHRINK_MIN_FONT_SIZE_PT, F as FitFontSize, M as MIN_SHRINK_FONT_SIZE_PT, c as cellFitCapMm, a as cellFitKey, b as cellFitWidthMm, d as cellImageBoxMm, f as floorFontSize, p as parseCellFitKey, r as resolveCellTextFit, e as resolveElementTextFit, g as resolveShrinkMinFontSize, h as roundFontSize } from '../ports-B-Jb2XwT.cjs';
 import { TemplateEngine, formatMoney, ifFn, addNumbers, subtractNumbers, multiplyNumbers, divideNumbers, round, roundUp, roundDown, roundHalfEven, formatDate, toUpperCaseAmount } from '../index.cjs';
 
 /** 1 英寸 = 25.4mm */
@@ -88,6 +88,29 @@ type BorderFields = Pick<ElementOptions, 'borderWidth' | 'borderStyle' | 'border
 /** 解析元素级边框；返回 null 表示无任何生效边框 */
 declare function resolveElementBorder(type: string | undefined, opts: BorderFields | undefined): ElementBordersCss | null;
 
+/**
+ * 剪裁取位与放大的声明单点（画布 / 预览 / 出纸三端共用）。
+ *
+ * 「剪裁」（`fit: 'cover'`）把图等比铺满框，图与框同比例时画面刚好等于框——没有任何东西可裁，
+ * 所以放大比例 `fitScale` 把画面按百分比再推大，两轴同时溢出，锚点才真的裁得动。
+ *
+ * 放大用 `transform: scale()` 而不是撑大 img 盒：object-position 把画面的 x% 点钉在框的 x% 处，
+ * transform 以同一比例的 transform-origin 为不动点放大，于是「取位点＝放大中心」两件事共用一个值，
+ * 三端不必各推一遍落点公式。放大后的画面由元素框 / 单元格盒的 overflow:hidden 裁掉。
+ */
+/** 放大比例区间（%）：100＝不放大（存量形态），上限防止画面被推到无意义尺度 */
+declare const CROP_SCALE_MIN = 100;
+declare const CROP_SCALE_MAX = 400;
+/** 净化锚点：非法字符、超长、空值一律给空串（宿主 CSSOM 同样会丢弃非法值，两端行为一致） */
+declare function sanitizeObjectPosition(value?: string): string;
+/** 只有剪裁档有可裁的边，故只有它消费放大比例；100 与非法值都归成 undefined＝不落声明 */
+declare function cropScalePct(fit: string | undefined, scale: number | undefined): number | undefined;
+/**
+ * 剪裁相关的样式声明（camelCase 键，宿主直接展开进 style 对象；出纸端按键名转 kebab 内联）。
+ * 放大时 transform-origin 复用同一条锚点值：取位点即放大不动点，缺一半都会跑偏。
+ */
+declare function cropStyleDeclarations(fit: string | undefined, scale: number | undefined, objectPosition?: string): Record<string, string>;
+
 /** pt 转 mm */
 declare function ptToMm(pt: number): number;
 /** px 转 mm（基于 96dpi 屏幕） */
@@ -145,6 +168,28 @@ interface ToolbarOverflowResult {
 }
 declare function resolveToolbarOverflow(input: ToolbarOverflowInput): ToolbarOverflowResult;
 
+/**
+ * 浮层放置判定：输入触发框、浮层高度与可用区（已折算最近裁剪祖先与视口的交集），
+ * 返回浮层该向下还是向上展开。测量由宿主完成，此处只做数值判定，
+ * 保证 canvas 与 print-common 两套宿主在同一尺寸下得到同一结论。
+ */
+type OverlayPlacement = 'down' | 'up';
+interface OverlayPlacementInput {
+    /** 触发框上沿（视口坐标） */
+    triggerTop: number;
+    /** 触发框下沿（视口坐标） */
+    triggerBottom: number;
+    /** 浮层自身高度 */
+    overlayHeight: number;
+    /** 可用区上沿 */
+    boundaryTop: number;
+    /** 可用区下沿 */
+    boundaryBottom: number;
+    /** 触发框与浮层之间的间隙，缺省 4 */
+    gap?: number;
+}
+declare function resolveOverlayPlacement(input: OverlayPlacementInput): OverlayPlacement;
+
 declare function normalizeTemplateUnits(data: TemplateData): TemplateData;
 
 /** 标签纸分组名（PAPER_PRESETS.group）：该组纸型默认取消页眉、页脚与页边距 */
@@ -343,6 +388,118 @@ declare function searchProperties(search: string): {
     itemKeys: Set<string>;
 };
 
+interface CropBox {
+    /** 元素框宽（mm） */
+    widthMm: number;
+    /** 元素框高（mm） */
+    heightMm: number;
+    /** 图片自然宽（px）；动态字段图在设计态可能拿不到 */
+    naturalWidth?: number;
+    naturalHeight?: number;
+    /** 缩放模式（CSS object-fit 原值，缺省 contain）：余量按它逐轴结算 */
+    fit?: string;
+    /** 剪裁放大比例（%）：只有 cover 消费，铺满后把画面再推大这么多，两轴才同时有可裁的边 */
+    scalePct?: number;
+}
+/** 逐轴可挪余量（mm）。null＝拿不到图片尺寸，余量未知；0＝该轴贴满，挪不动 */
+interface CropTravel {
+    x: number | null;
+    y: number | null;
+}
+type CropAnchorParsed = {
+    kind: 'empty';
+} | {
+    kind: 'axes';
+    x: number;
+    y: number;
+} | {
+    kind: 'custom';
+    raw: string;
+};
+/** 生成落纸值；两轴都居中即缺省态，返回 undefined 让调用方不落声明（空串会覆盖默认居中） */
+declare function buildCropAnchor(x: number, y: number): string | undefined;
+/**
+ * 回显存量值。CSS 两值形式第一个值属水平轴，故首 token 先按水平解释、次 token 先按垂直解释，
+ * 覆盖 `50% 20%` / `center 20%` / `left top` / `top left` / 单值 `20%`。
+ * 表达不了的写法（mm 偏移、四值语法、calc）不猜，原样交「自定义」承载。
+ */
+declare function parseCropAnchor(value?: string): CropAnchorParsed;
+/** 逐轴可挪余量：拿不到图片尺寸时两轴都是 null（未知），不能糊成 0 说「挪不动」 */
+declare function resolveCropTravel(box: CropBox): CropTravel;
+/** 属性台示意图：可视窗在原图上的位置（百分比，与原图渲染尺寸无关） */
+declare function cropWindow(box: CropBox, x: number, y: number): {
+    leftPct: number;
+    topPct: number;
+    widthPct: number;
+    heightPct: number;
+} | null;
+/**
+ * 设计态图片地址：`{字段}` 表达式按 demo 数据求值，其余原样。
+ * 属性台的示意图与画布元素渲染必须拿到同一个地址，否则控件里看到的图与画布上的图不是一张。
+ */
+declare function resolveDesignImageSrc(raw?: string): string;
+/** 可动轴下拉项：值即该轴的百分比 */
+declare const CROP_AXIS_OPTIONS: Record<'vertical' | 'horizontal', Array<{
+    value: number;
+    label: string;
+}>>;
+/** 两轴组合档位（九宫格）：「上中」= 水平居中 + 垂直贴顶 */
+declare const CROP_GRID_OPTIONS: Array<{
+    x: number;
+    y: number;
+    label: string;
+}>;
+/**
+ * 缩放模式档位表：value 仍是 CSS object-fit 原值（模板 JSON 不变），
+ * 只有 cover 对用户改称「剪裁」——它是唯一真会裁掉画面的档位，也只有这一档给「裁剪锚点」行：
+ * 剪裁把图铺满框后必然溢出一条边，锚点挪的就是那条边；其余档图比框小或刚好铺满，没有可裁的边。
+ * 画布、单元格台、码值台、common 三处都取这一份，改名不再需要六处同步。
+ */
+declare const IMAGE_FIT_OPTIONS: Array<{
+    value: string;
+    label: string;
+}>;
+/**
+ * 剪裁示意专用的内置示例图（120×120 正方形，3×3 九宫格）：中心靶心，四条边中点各一色
+ * （顶红／底蓝／左绿／右橙），四角小灰点。方形是为了让水平与垂直两轴都能演示取位：
+ * cover 进竖框裁的是左右、cover 进横框裁的是上下，contain／原始尺寸则两轴都可能留空位。
+ * 它只服务于属性台的「原图可视窗示意」：画布与出纸上的空图片仍是虚线「图片」占位，不会变成这张图。
+ */
+declare const CROP_SAMPLE_IMAGE = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjAiIGhlaWdodD0iMTIwIiB2aWV3Qm94PSIwIDAgMTIwIDEyMCI+PHJlY3Qgd2lkdGg9IjEyMCIgaGVpZ2h0PSIxMjAiIGZpbGw9IiNmZmZmZmYiLz48cGF0aCBkPSJNNDAgMFYxMjBNODAgMFYxMjBNMCA0MEgxMjBNMCA4MEgxMjAiIHN0cm9rZT0iI2VlZjFmNiIgc3Ryb2tlLXdpZHRoPSIxIi8+PGNpcmNsZSBjeD0iMjAiIGN5PSIyMCIgcj0iMy41IiBmaWxsPSIjOGI5NWE1Ii8+PGNpcmNsZSBjeD0iMTAwIiBjeT0iMjAiIHI9IjMuNSIgZmlsbD0iIzhiOTVhNSIvPjxjaXJjbGUgY3g9IjIwIiBjeT0iMTAwIiByPSIzLjUiIGZpbGw9IiM4Yjk1YTUiLz48Y2lyY2xlIGN4PSIxMDAiIGN5PSIxMDAiIHI9IjMuNSIgZmlsbD0iIzhiOTVhNSIvPjxjaXJjbGUgY3g9IjYwIiBjeT0iMjAiIHI9IjciIGZpbGw9IiNjMDM5MmIiLz48Y2lyY2xlIGN4PSI2MCIgY3k9IjEwMCIgcj0iNyIgZmlsbD0iIzFmNGZhMyIvPjxjaXJjbGUgY3g9IjIwIiBjeT0iNjAiIHI9IjciIGZpbGw9IiMyYzdhNGEiLz48Y2lyY2xlIGN4PSIxMDAiIGN5PSI2MCIgcj0iNyIgZmlsbD0iI2UwN2EyMCIvPjxjaXJjbGUgY3g9IjYwIiBjeT0iNjAiIHI9IjE0IiBmaWxsPSJub25lIiBzdHJva2U9IiMyZjNhNGEiIHN0cm9rZS13aWR0aD0iNCIvPjxjaXJjbGUgY3g9IjYwIiBjeT0iNjAiIHI9IjYiIGZpbGw9IiMyZjNhNGEiLz48L3N2Zz4=";
+/** 示意图来自内置示例图时必须说破，否则用户会把演示图当成自己的业务图来判断取位（两端共用这一串） */
+declare const CROP_SAMPLE_NOTE = "\u56FE\u7247\u8FD8\u6CA1\u8BBE\u7F6E\uFF0C\u4E0A\u9762\u6309\u5185\u7F6E\u793A\u4F8B\u56FE\u6F14\u793A\u53D6\u4F4D\uFF1B\u6362\u4E0A\u771F\u56FE\u540E\u6863\u4F4D\u4E0E\u53EF\u632A\u91CF\u6309\u771F\u56FE\u91CD\u7B97";
+/**
+ * 属性台的示意图该画哪张图：传入已求值的业务图片地址，取不到即回落示例图。
+ * 未求值的表达式（`{image}` 这类字段在设计态没有 demo 值）也算取不到——直接当 src 用会渲染成破图，
+ * 既绕过示例兜底又让档位/note 停在旧图上（T-17）。合法地址不会含花括号，故按字符判定不误伤。
+ * isSample 给宿主用来标「示例图，非你的图片」，避免把演示图误认成业务图。
+ */
+declare function resolveCropPreview(resolvedSrc?: string): {
+    src: string;
+    isSample: boolean;
+};
+/** 可动轴数字框的行标签 */
+declare function cropAxisLabel(axis: 'horizontal' | 'vertical'): string;
+/** 「放大比例」行标签：区间与归一判据取 core `crop-style`（CROP_SCALE_MIN/MAX），两端不再各写一遍 */
+declare const CROP_SCALE_LABEL = "\u653E\u5927\u6BD4\u4F8B (%)";
+/** 一句话逐轴报数：两轴都能挪就把两个数都写出来；挪不动的那一轴直说，不含糊。keepRaw 表示模板里存的是表达不了的写法 */
+declare function cropAxisNote(travel: CropTravel, keepRaw?: boolean): string;
+/** 数字框行：两轴常驻（各带本轴余量，未知给 null），宿主只管渲染两行 */
+declare function cropAxisFields(travel: CropTravel, x: number, y: number): Array<{
+    name: 'horizontal' | 'vertical';
+    label: string;
+    value: number;
+    travelMm: number | null;
+}>;
+/**
+ * 位置档下拉：两轴都有余量给九宫格；只一轴有余量给该轴三档（另一轴带上现值，换图后接手）；
+ * 余量未知或全无也兜底九宫格——让用户能挑，比不给档诚实。
+ */
+declare function cropPresetOptions(travel: CropTravel, x: number, y: number): Array<{
+    value: string;
+    label: string;
+}>;
+
 interface FieldGroup {
     /** 分组键（fieldKey 首段）；空串表示无分组的顶层字段 */
     key: string;
@@ -522,4 +679,4 @@ declare function useBindingDisplay(): {
     getBindingDisplayState: (element: any) => BindingDisplayState;
 };
 
-export { type AdsorbConfig, AdsorbResult, type AlignMode, BARCODE_BAR_HEIGHT_MODULES, BARCODE_MARGIN_BOTTOM_MODULES, BARCODE_MODULE_WIDTH_MM, BARCODE_QUIET_ZONE_MODULES, BARCODE_TEXT_FONT_SIZE_MODULES, type BarcodeSize, type BarcodeSizeInput, BindingDescriptor, type BorderPreset, type CellRect, DEFAULT_DEMO_DATA, ELEMENT_BINDING_REGISTRY, ELEMENT_BORDER_SIDES, EXTENDED_FUNCTIONS, type ElementBorderCss, ElementBorderSide, type ElementBordersCss, ElementOptions, ElementRect, ElementType, ElementZone, FIT_SCALE_MIN_PERCENT, type FieldGroup, GHOST_BORDER_CSS, type KeyboardHandlers, LABEL_PAPER_GROUP, MIN_COL_WIDTH_MM, MIN_SCALE_PERCENT, MM_PER_INCH, type ManualGuides, type OverflowUnitInput, PAPER_PRESETS, PRESET_COLORS, PROPERTY_REGISTRY, type PaperPreset, PrintBusinessField, type PropertyGroupDef, type PropertyItem, RESIZE_POINTS, RULER_THICKNESS, type ResizeOptions, ResizePoint, type ResizeRect, type RulerTick, RuntimeElement, TableCell, TableCellBorder, TableRow, TableRowType, TemplateData, type ToolbarOverflowInput, type ToolbarOverflowResult, ZONE_ALLOWED_TYPES, type ZoneRectPt, acceptsElementBorder, applyBorderPreset, barcodeAvailableBoxMm, barcodePreferredModuleWidthMm, barcodeUnitsPerModule, buildRulerTicks, calcResizeRect, canMergeReason, chooseMajorStepMM, clampResizedColumnWidth, clampScalePercent, clampToZone, computeAdsorb, computeFitScale, createCell, createDefaultOptions, createDefaultTable, createFieldElement, createRuntimeElement, deleteCol, deleteRow, engine, evaluateTemplate, filterGroups, finalizeElementZone, findMainCell, generateGroupId, generateId, getDemoData, getElementBindings, getPaperDimensions, getPaperSizeMM, getSpanRect, getTableCellBindings, getZoneRects, groupFields, insertCol, insertRow, isContinuousPaperSize, isLabelPaperSize, labelPaperDefaults, matchKeywords, mergeCells, minorStepMM, mmToPx, nextWheelScale, normalizeSelection, normalizeTemplateUnits, propertyTip, ptToMm, pxToMm, resolveBarcodeDesignValue, resolveBarcodeSize, resolveCellBorderCss, resolveElementBorder, resolveTextBinding, resolveToolbarOverflow, safeEval, searchProperties, setHeaderRepeat, setRowType, splitCells, syncTableElementSize, useAlign, useBindingDisplay, useGroup, useKeyboard, useResize, zoneFromPaperPoint };
+export { type AdsorbConfig, AdsorbResult, type AlignMode, BARCODE_BAR_HEIGHT_MODULES, BARCODE_MARGIN_BOTTOM_MODULES, BARCODE_MODULE_WIDTH_MM, BARCODE_QUIET_ZONE_MODULES, BARCODE_TEXT_FONT_SIZE_MODULES, type BarcodeSize, type BarcodeSizeInput, BindingDescriptor, type BorderPreset, CROP_AXIS_OPTIONS, CROP_GRID_OPTIONS, CROP_SAMPLE_IMAGE, CROP_SAMPLE_NOTE, CROP_SCALE_LABEL, CROP_SCALE_MAX, CROP_SCALE_MIN, type CellRect, type CropAnchorParsed, type CropBox, type CropTravel, DEFAULT_DEMO_DATA, ELEMENT_BINDING_REGISTRY, ELEMENT_BORDER_SIDES, EXTENDED_FUNCTIONS, type ElementBorderCss, ElementBorderSide, type ElementBordersCss, ElementOptions, ElementRect, ElementType, ElementZone, FIT_SCALE_MIN_PERCENT, type FieldGroup, GHOST_BORDER_CSS, IMAGE_FIT_OPTIONS, type KeyboardHandlers, LABEL_PAPER_GROUP, MIN_COL_WIDTH_MM, MIN_SCALE_PERCENT, MM_PER_INCH, type ManualGuides, type OverflowUnitInput, type OverlayPlacement, type OverlayPlacementInput, PAPER_PRESETS, PRESET_COLORS, PROPERTY_REGISTRY, type PaperPreset, PrintBusinessField, type PropertyGroupDef, type PropertyItem, RESIZE_POINTS, RULER_THICKNESS, type ResizeOptions, ResizePoint, type ResizeRect, type RulerTick, RuntimeElement, TableCell, TableCellBorder, TableRow, TableRowType, TemplateData, type ToolbarOverflowInput, type ToolbarOverflowResult, ZONE_ALLOWED_TYPES, type ZoneRectPt, acceptsElementBorder, applyBorderPreset, barcodeAvailableBoxMm, barcodePreferredModuleWidthMm, barcodeUnitsPerModule, buildCropAnchor, buildRulerTicks, calcResizeRect, canMergeReason, chooseMajorStepMM, clampResizedColumnWidth, clampScalePercent, clampToZone, computeAdsorb, computeFitScale, createCell, createDefaultOptions, createDefaultTable, createFieldElement, createRuntimeElement, cropAxisFields, cropAxisLabel, cropAxisNote, cropPresetOptions, cropScalePct, cropStyleDeclarations, cropWindow, deleteCol, deleteRow, engine, evaluateTemplate, filterGroups, finalizeElementZone, findMainCell, generateGroupId, generateId, getDemoData, getElementBindings, getPaperDimensions, getPaperSizeMM, getSpanRect, getTableCellBindings, getZoneRects, groupFields, insertCol, insertRow, isContinuousPaperSize, isLabelPaperSize, labelPaperDefaults, matchKeywords, mergeCells, minorStepMM, mmToPx, nextWheelScale, normalizeSelection, normalizeTemplateUnits, parseCropAnchor, propertyTip, ptToMm, pxToMm, resolveBarcodeDesignValue, resolveBarcodeSize, resolveCellBorderCss, resolveCropPreview, resolveCropTravel, resolveDesignImageSrc, resolveElementBorder, resolveOverlayPlacement, resolveTextBinding, resolveToolbarOverflow, safeEval, sanitizeObjectPosition, searchProperties, setHeaderRepeat, setRowType, splitCells, syncTableElementSize, useAlign, useBindingDisplay, useGroup, useKeyboard, useResize, zoneFromPaperPoint };

package/dist/designer/index.d.ts

@@ -1,12 +1,12 @@
 /*!
- * @worm-vue3-print/core v1.3.7
+ * @worm-vue3-print/core v1.3.8
  * Copyright (c) 2026 worm <liu_long_qqcom@qq.com>
  * SPDX-FileCopyrightText: 2026 worm <liu_long_qqcom@qq.com>
  * SPDX-License-Identifier: MIT
  */
-import { E as ElementBorderSide, b as ElementOptions, c as TemplateData, d as TableRow, e as TableCellBorder, f as TableCell, g as TableRowType, h as ElementType, i as RuntimeElement, j as ElementZone, k as PrintBusinessField, B as BindingDescriptor, l as ElementRect, A as AdsorbResult, m as ResizePoint } from '../driver-Dzr2Aikx.js';
-export { n as AlignLine, o as DesignBackground, p as ElementBorderEdge, q as ElementFieldBinding, r as MultiPageTemplateData, s as PaginationConfig, t as PaperSize, u as PrintElementData, v as PrintElementTypeMeta, w as TableCellBorders, x as TableCellType, y as TablePaginationConfig, z as TableSelection, F as TemplateElement, G as TextAlign, H as TextFit, U as UploadDesignBackgroundFn, I as UploadImageFn, V as VerticalAlign, W as WatermarkOptions } from '../driver-Dzr2Aikx.js';
-export { C as CellFitRowKind, D as DEFAULT_SHRINK_MIN_FONT_SIZE_PT, F as FitFontSize, M as MIN_SHRINK_FONT_SIZE_PT, c as cellFitCapMm, a as cellFitKey, b as cellFitWidthMm, f as floorFontSize, p as parseCellFitKey, r as resolveCellTextFit, d as resolveElementTextFit, e as resolveShrinkMinFontSize, g as roundFontSize } from '../ports-B8MFq_Yo.js';
+import { E as ElementBorderSide, b as ElementOptions, c as TemplateData, d as TableRow, e as TableCellBorder, f as TableCell, g as TableRowType, h as ElementType, i as RuntimeElement, j as ElementZone, k as PrintBusinessField, B as BindingDescriptor, l as ElementRect, A as AdsorbResult, m as ResizePoint } from '../driver-hJxBl2_n.js';
+export { n as AlignLine, o as DesignBackground, p as ElementBorderEdge, q as ElementFieldBinding, r as MultiPageTemplateData, s as PaginationConfig, t as PaperSize, u as PrintElementData, v as PrintElementTypeMeta, w as TableCellBorders, x as TableCellType, y as TablePaginationConfig, z as TableSelection, F as TemplateElement, G as TextAlign, H as TextFit, U as UploadDesignBackgroundFn, I as UploadImageFn, V as VerticalAlign, W as WatermarkOptions } from '../driver-hJxBl2_n.js';
+export { C as CellFitRowKind, D as DEFAULT_SHRINK_MIN_FONT_SIZE_PT, F as FitFontSize, M as MIN_SHRINK_FONT_SIZE_PT, c as cellFitCapMm, a as cellFitKey, b as cellFitWidthMm, d as cellImageBoxMm, f as floorFontSize, p as parseCellFitKey, r as resolveCellTextFit, e as resolveElementTextFit, g as resolveShrinkMinFontSize, h as roundFontSize } from '../ports-CJ0SUYFt.js';
 import { TemplateEngine, formatMoney, ifFn, addNumbers, subtractNumbers, multiplyNumbers, divideNumbers, round, roundUp, roundDown, roundHalfEven, formatDate, toUpperCaseAmount } from '../index.js';
 
 /** 1 英寸 = 25.4mm */
@@ -88,6 +88,29 @@ type BorderFields = Pick<ElementOptions, 'borderWidth' | 'borderStyle' | 'border
 /** 解析元素级边框；返回 null 表示无任何生效边框 */
 declare function resolveElementBorder(type: string | undefined, opts: BorderFields | undefined): ElementBordersCss | null;
 
+/**
+ * 剪裁取位与放大的声明单点（画布 / 预览 / 出纸三端共用）。
+ *
+ * 「剪裁」（`fit: 'cover'`）把图等比铺满框，图与框同比例时画面刚好等于框——没有任何东西可裁，
+ * 所以放大比例 `fitScale` 把画面按百分比再推大，两轴同时溢出，锚点才真的裁得动。
+ *
+ * 放大用 `transform: scale()` 而不是撑大 img 盒：object-position 把画面的 x% 点钉在框的 x% 处，
+ * transform 以同一比例的 transform-origin 为不动点放大，于是「取位点＝放大中心」两件事共用一个值，
+ * 三端不必各推一遍落点公式。放大后的画面由元素框 / 单元格盒的 overflow:hidden 裁掉。
+ */
+/** 放大比例区间（%）：100＝不放大（存量形态），上限防止画面被推到无意义尺度 */
+declare const CROP_SCALE_MIN = 100;
+declare const CROP_SCALE_MAX = 400;
+/** 净化锚点：非法字符、超长、空值一律给空串（宿主 CSSOM 同样会丢弃非法值，两端行为一致） */
+declare function sanitizeObjectPosition(value?: string): string;
+/** 只有剪裁档有可裁的边，故只有它消费放大比例；100 与非法值都归成 undefined＝不落声明 */
+declare function cropScalePct(fit: string | undefined, scale: number | undefined): number | undefined;
+/**
+ * 剪裁相关的样式声明（camelCase 键，宿主直接展开进 style 对象；出纸端按键名转 kebab 内联）。
+ * 放大时 transform-origin 复用同一条锚点值：取位点即放大不动点，缺一半都会跑偏。
+ */
+declare function cropStyleDeclarations(fit: string | undefined, scale: number | undefined, objectPosition?: string): Record<string, string>;
+
 /** pt 转 mm */
 declare function ptToMm(pt: number): number;
 /** px 转 mm（基于 96dpi 屏幕） */
@@ -145,6 +168,28 @@ interface ToolbarOverflowResult {
 }
 declare function resolveToolbarOverflow(input: ToolbarOverflowInput): ToolbarOverflowResult;
 
+/**
+ * 浮层放置判定：输入触发框、浮层高度与可用区（已折算最近裁剪祖先与视口的交集），
+ * 返回浮层该向下还是向上展开。测量由宿主完成，此处只做数值判定，
+ * 保证 canvas 与 print-common 两套宿主在同一尺寸下得到同一结论。
+ */
+type OverlayPlacement = 'down' | 'up';
+interface OverlayPlacementInput {
+    /** 触发框上沿（视口坐标） */
+    triggerTop: number;
+    /** 触发框下沿（视口坐标） */
+    triggerBottom: number;
+    /** 浮层自身高度 */
+    overlayHeight: number;
+    /** 可用区上沿 */
+    boundaryTop: number;
+    /** 可用区下沿 */
+    boundaryBottom: number;
+    /** 触发框与浮层之间的间隙，缺省 4 */
+    gap?: number;
+}
+declare function resolveOverlayPlacement(input: OverlayPlacementInput): OverlayPlacement;
+
 declare function normalizeTemplateUnits(data: TemplateData): TemplateData;
 
 /** 标签纸分组名（PAPER_PRESETS.group）：该组纸型默认取消页眉、页脚与页边距 */
@@ -343,6 +388,118 @@ declare function searchProperties(search: string): {
     itemKeys: Set<string>;
 };
 
+interface CropBox {
+    /** 元素框宽（mm） */
+    widthMm: number;
+    /** 元素框高（mm） */
+    heightMm: number;
+    /** 图片自然宽（px）；动态字段图在设计态可能拿不到 */
+    naturalWidth?: number;
+    naturalHeight?: number;
+    /** 缩放模式（CSS object-fit 原值，缺省 contain）：余量按它逐轴结算 */
+    fit?: string;
+    /** 剪裁放大比例（%）：只有 cover 消费，铺满后把画面再推大这么多，两轴才同时有可裁的边 */
+    scalePct?: number;
+}
+/** 逐轴可挪余量（mm）。null＝拿不到图片尺寸，余量未知；0＝该轴贴满，挪不动 */
+interface CropTravel {
+    x: number | null;
+    y: number | null;
+}
+type CropAnchorParsed = {
+    kind: 'empty';
+} | {
+    kind: 'axes';
+    x: number;
+    y: number;
+} | {
+    kind: 'custom';
+    raw: string;
+};
+/** 生成落纸值；两轴都居中即缺省态，返回 undefined 让调用方不落声明（空串会覆盖默认居中） */
+declare function buildCropAnchor(x: number, y: number): string | undefined;
+/**
+ * 回显存量值。CSS 两值形式第一个值属水平轴，故首 token 先按水平解释、次 token 先按垂直解释，
+ * 覆盖 `50% 20%` / `center 20%` / `left top` / `top left` / 单值 `20%`。
+ * 表达不了的写法（mm 偏移、四值语法、calc）不猜，原样交「自定义」承载。
+ */
+declare function parseCropAnchor(value?: string): CropAnchorParsed;
+/** 逐轴可挪余量：拿不到图片尺寸时两轴都是 null（未知），不能糊成 0 说「挪不动」 */
+declare function resolveCropTravel(box: CropBox): CropTravel;
+/** 属性台示意图：可视窗在原图上的位置（百分比，与原图渲染尺寸无关） */
+declare function cropWindow(box: CropBox, x: number, y: number): {
+    leftPct: number;
+    topPct: number;
+    widthPct: number;
+    heightPct: number;
+} | null;
+/**
+ * 设计态图片地址：`{字段}` 表达式按 demo 数据求值，其余原样。
+ * 属性台的示意图与画布元素渲染必须拿到同一个地址，否则控件里看到的图与画布上的图不是一张。
+ */
+declare function resolveDesignImageSrc(raw?: string): string;
+/** 可动轴下拉项：值即该轴的百分比 */
+declare const CROP_AXIS_OPTIONS: Record<'vertical' | 'horizontal', Array<{
+    value: number;
+    label: string;
+}>>;
+/** 两轴组合档位（九宫格）：「上中」= 水平居中 + 垂直贴顶 */
+declare const CROP_GRID_OPTIONS: Array<{
+    x: number;
+    y: number;
+    label: string;
+}>;
+/**
+ * 缩放模式档位表：value 仍是 CSS object-fit 原值（模板 JSON 不变），
+ * 只有 cover 对用户改称「剪裁」——它是唯一真会裁掉画面的档位，也只有这一档给「裁剪锚点」行：
+ * 剪裁把图铺满框后必然溢出一条边，锚点挪的就是那条边；其余档图比框小或刚好铺满，没有可裁的边。
+ * 画布、单元格台、码值台、common 三处都取这一份，改名不再需要六处同步。
+ */
+declare const IMAGE_FIT_OPTIONS: Array<{
+    value: string;
+    label: string;
+}>;
+/**
+ * 剪裁示意专用的内置示例图（120×120 正方形，3×3 九宫格）：中心靶心，四条边中点各一色
+ * （顶红／底蓝／左绿／右橙），四角小灰点。方形是为了让水平与垂直两轴都能演示取位：
+ * cover 进竖框裁的是左右、cover 进横框裁的是上下，contain／原始尺寸则两轴都可能留空位。
+ * 它只服务于属性台的「原图可视窗示意」：画布与出纸上的空图片仍是虚线「图片」占位，不会变成这张图。
+ */
+declare const CROP_SAMPLE_IMAGE = "data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxMjAiIGhlaWdodD0iMTIwIiB2aWV3Qm94PSIwIDAgMTIwIDEyMCI+PHJlY3Qgd2lkdGg9IjEyMCIgaGVpZ2h0PSIxMjAiIGZpbGw9IiNmZmZmZmYiLz48cGF0aCBkPSJNNDAgMFYxMjBNODAgMFYxMjBNMCA0MEgxMjBNMCA4MEgxMjAiIHN0cm9rZT0iI2VlZjFmNiIgc3Ryb2tlLXdpZHRoPSIxIi8+PGNpcmNsZSBjeD0iMjAiIGN5PSIyMCIgcj0iMy41IiBmaWxsPSIjOGI5NWE1Ii8+PGNpcmNsZSBjeD0iMTAwIiBjeT0iMjAiIHI9IjMuNSIgZmlsbD0iIzhiOTVhNSIvPjxjaXJjbGUgY3g9IjIwIiBjeT0iMTAwIiByPSIzLjUiIGZpbGw9IiM4Yjk1YTUiLz48Y2lyY2xlIGN4PSIxMDAiIGN5PSIxMDAiIHI9IjMuNSIgZmlsbD0iIzhiOTVhNSIvPjxjaXJjbGUgY3g9IjYwIiBjeT0iMjAiIHI9IjciIGZpbGw9IiNjMDM5MmIiLz48Y2lyY2xlIGN4PSI2MCIgY3k9IjEwMCIgcj0iNyIgZmlsbD0iIzFmNGZhMyIvPjxjaXJjbGUgY3g9IjIwIiBjeT0iNjAiIHI9IjciIGZpbGw9IiMyYzdhNGEiLz48Y2lyY2xlIGN4PSIxMDAiIGN5PSI2MCIgcj0iNyIgZmlsbD0iI2UwN2EyMCIvPjxjaXJjbGUgY3g9IjYwIiBjeT0iNjAiIHI9IjE0IiBmaWxsPSJub25lIiBzdHJva2U9IiMyZjNhNGEiIHN0cm9rZS13aWR0aD0iNCIvPjxjaXJjbGUgY3g9IjYwIiBjeT0iNjAiIHI9IjYiIGZpbGw9IiMyZjNhNGEiLz48L3N2Zz4=";
+/** 示意图来自内置示例图时必须说破，否则用户会把演示图当成自己的业务图来判断取位（两端共用这一串） */
+declare const CROP_SAMPLE_NOTE = "\u56FE\u7247\u8FD8\u6CA1\u8BBE\u7F6E\uFF0C\u4E0A\u9762\u6309\u5185\u7F6E\u793A\u4F8B\u56FE\u6F14\u793A\u53D6\u4F4D\uFF1B\u6362\u4E0A\u771F\u56FE\u540E\u6863\u4F4D\u4E0E\u53EF\u632A\u91CF\u6309\u771F\u56FE\u91CD\u7B97";
+/**
+ * 属性台的示意图该画哪张图：传入已求值的业务图片地址，取不到即回落示例图。
+ * 未求值的表达式（`{image}` 这类字段在设计态没有 demo 值）也算取不到——直接当 src 用会渲染成破图，
+ * 既绕过示例兜底又让档位/note 停在旧图上（T-17）。合法地址不会含花括号，故按字符判定不误伤。
+ * isSample 给宿主用来标「示例图，非你的图片」，避免把演示图误认成业务图。
+ */
+declare function resolveCropPreview(resolvedSrc?: string): {
+    src: string;
+    isSample: boolean;
+};
+/** 可动轴数字框的行标签 */
+declare function cropAxisLabel(axis: 'horizontal' | 'vertical'): string;
+/** 「放大比例」行标签：区间与归一判据取 core `crop-style`（CROP_SCALE_MIN/MAX），两端不再各写一遍 */
+declare const CROP_SCALE_LABEL = "\u653E\u5927\u6BD4\u4F8B (%)";
+/** 一句话逐轴报数：两轴都能挪就把两个数都写出来；挪不动的那一轴直说，不含糊。keepRaw 表示模板里存的是表达不了的写法 */
+declare function cropAxisNote(travel: CropTravel, keepRaw?: boolean): string;
+/** 数字框行：两轴常驻（各带本轴余量，未知给 null），宿主只管渲染两行 */
+declare function cropAxisFields(travel: CropTravel, x: number, y: number): Array<{
+    name: 'horizontal' | 'vertical';
+    label: string;
+    value: number;
+    travelMm: number | null;
+}>;
+/**
+ * 位置档下拉：两轴都有余量给九宫格；只一轴有余量给该轴三档（另一轴带上现值，换图后接手）；
+ * 余量未知或全无也兜底九宫格——让用户能挑，比不给档诚实。
+ */
+declare function cropPresetOptions(travel: CropTravel, x: number, y: number): Array<{
+    value: string;
+    label: string;
+}>;
+
 interface FieldGroup {
     /** 分组键（fieldKey 首段）；空串表示无分组的顶层字段 */
     key: string;
@@ -522,4 +679,4 @@ declare function useBindingDisplay(): {
     getBindingDisplayState: (element: any) => BindingDisplayState;
 };
 
-export { type AdsorbConfig, AdsorbResult, type AlignMode, BARCODE_BAR_HEIGHT_MODULES, BARCODE_MARGIN_BOTTOM_MODULES, BARCODE_MODULE_WIDTH_MM, BARCODE_QUIET_ZONE_MODULES, BARCODE_TEXT_FONT_SIZE_MODULES, type BarcodeSize, type BarcodeSizeInput, BindingDescriptor, type BorderPreset, type CellRect, DEFAULT_DEMO_DATA, ELEMENT_BINDING_REGISTRY, ELEMENT_BORDER_SIDES, EXTENDED_FUNCTIONS, type ElementBorderCss, ElementBorderSide, type ElementBordersCss, ElementOptions, ElementRect, ElementType, ElementZone, FIT_SCALE_MIN_PERCENT, type FieldGroup, GHOST_BORDER_CSS, type KeyboardHandlers, LABEL_PAPER_GROUP, MIN_COL_WIDTH_MM, MIN_SCALE_PERCENT, MM_PER_INCH, type ManualGuides, type OverflowUnitInput, PAPER_PRESETS, PRESET_COLORS, PROPERTY_REGISTRY, type PaperPreset, PrintBusinessField, type PropertyGroupDef, type PropertyItem, RESIZE_POINTS, RULER_THICKNESS, type ResizeOptions, ResizePoint, type ResizeRect, type RulerTick, RuntimeElement, TableCell, TableCellBorder, TableRow, TableRowType, TemplateData, type ToolbarOverflowInput, type ToolbarOverflowResult, ZONE_ALLOWED_TYPES, type ZoneRectPt, acceptsElementBorder, applyBorderPreset, barcodeAvailableBoxMm, barcodePreferredModuleWidthMm, barcodeUnitsPerModule, buildRulerTicks, calcResizeRect, canMergeReason, chooseMajorStepMM, clampResizedColumnWidth, clampScalePercent, clampToZone, computeAdsorb, computeFitScale, createCell, createDefaultOptions, createDefaultTable, createFieldElement, createRuntimeElement, deleteCol, deleteRow, engine, evaluateTemplate, filterGroups, finalizeElementZone, findMainCell, generateGroupId, generateId, getDemoData, getElementBindings, getPaperDimensions, getPaperSizeMM, getSpanRect, getTableCellBindings, getZoneRects, groupFields, insertCol, insertRow, isContinuousPaperSize, isLabelPaperSize, labelPaperDefaults, matchKeywords, mergeCells, minorStepMM, mmToPx, nextWheelScale, normalizeSelection, normalizeTemplateUnits, propertyTip, ptToMm, pxToMm, resolveBarcodeDesignValue, resolveBarcodeSize, resolveCellBorderCss, resolveElementBorder, resolveTextBinding, resolveToolbarOverflow, safeEval, searchProperties, setHeaderRepeat, setRowType, splitCells, syncTableElementSize, useAlign, useBindingDisplay, useGroup, useKeyboard, useResize, zoneFromPaperPoint };
+export { type AdsorbConfig, AdsorbResult, type AlignMode, BARCODE_BAR_HEIGHT_MODULES, BARCODE_MARGIN_BOTTOM_MODULES, BARCODE_MODULE_WIDTH_MM, BARCODE_QUIET_ZONE_MODULES, BARCODE_TEXT_FONT_SIZE_MODULES, type BarcodeSize, type BarcodeSizeInput, BindingDescriptor, type BorderPreset, CROP_AXIS_OPTIONS, CROP_GRID_OPTIONS, CROP_SAMPLE_IMAGE, CROP_SAMPLE_NOTE, CROP_SCALE_LABEL, CROP_SCALE_MAX, CROP_SCALE_MIN, type CellRect, type CropAnchorParsed, type CropBox, type CropTravel, DEFAULT_DEMO_DATA, ELEMENT_BINDING_REGISTRY, ELEMENT_BORDER_SIDES, EXTENDED_FUNCTIONS, type ElementBorderCss, ElementBorderSide, type ElementBordersCss, ElementOptions, ElementRect, ElementType, ElementZone, FIT_SCALE_MIN_PERCENT, type FieldGroup, GHOST_BORDER_CSS, IMAGE_FIT_OPTIONS, type KeyboardHandlers, LABEL_PAPER_GROUP, MIN_COL_WIDTH_MM, MIN_SCALE_PERCENT, MM_PER_INCH, type ManualGuides, type OverflowUnitInput, type OverlayPlacement, type OverlayPlacementInput, PAPER_PRESETS, PRESET_COLORS, PROPERTY_REGISTRY, type PaperPreset, PrintBusinessField, type PropertyGroupDef, type PropertyItem, RESIZE_POINTS, RULER_THICKNESS, type ResizeOptions, ResizePoint, type ResizeRect, type RulerTick, RuntimeElement, TableCell, TableCellBorder, TableRow, TableRowType, TemplateData, type ToolbarOverflowInput, type ToolbarOverflowResult, ZONE_ALLOWED_TYPES, type ZoneRectPt, acceptsElementBorder, applyBorderPreset, barcodeAvailableBoxMm, barcodePreferredModuleWidthMm, barcodeUnitsPerModule, buildCropAnchor, buildRulerTicks, calcResizeRect, canMergeReason, chooseMajorStepMM, clampResizedColumnWidth, clampScalePercent, clampToZone, computeAdsorb, computeFitScale, createCell, createDefaultOptions, createDefaultTable, createFieldElement, createRuntimeElement, cropAxisFields, cropAxisLabel, cropAxisNote, cropPresetOptions, cropScalePct, cropStyleDeclarations, cropWindow, deleteCol, deleteRow, engine, evaluateTemplate, filterGroups, finalizeElementZone, findMainCell, generateGroupId, generateId, getDemoData, getElementBindings, getPaperDimensions, getPaperSizeMM, getSpanRect, getTableCellBindings, getZoneRects, groupFields, insertCol, insertRow, isContinuousPaperSize, isLabelPaperSize, labelPaperDefaults, matchKeywords, mergeCells, minorStepMM, mmToPx, nextWheelScale, normalizeSelection, normalizeTemplateUnits, parseCropAnchor, propertyTip, ptToMm, pxToMm, resolveBarcodeDesignValue, resolveBarcodeSize, resolveCellBorderCss, resolveCropPreview, resolveCropTravel, resolveDesignImageSrc, resolveElementBorder, resolveOverlayPlacement, resolveTextBinding, resolveToolbarOverflow, safeEval, sanitizeObjectPosition, searchProperties, setHeaderRepeat, setRowType, splitCells, syncTableElementSize, useAlign, useBindingDisplay, useGroup, useKeyboard, useResize, zoneFromPaperPoint };