@agile-team/mach-report 2.11.1 → 2.12.0

package/dist/index.d.ts

@@ -113,6 +113,18 @@ export declare function cloneReportTemplate(document: ReportTemplateDocument, id
     name: string;
 }): ReportTemplateDocument;
 
+/** Serializable symbol settings. Encoders remain in the optional /codes entry. */
+export declare interface CodeOptions {
+    /** Explicit content, including an empty value, takes precedence over legacy fallbackText. */
+    value?: string;
+    symbology?: "code128" | "code39" | "ean13" | "ean8";
+    errorCorrection?: "L" | "M" | "Q" | "H";
+    /** White modules around a symbol: QR >=4, linear >=10, EAN >=11. */
+    quietZoneModules?: number;
+    /** Human-readable content below a linear barcode. */
+    showText?: boolean;
+}
+
 /**
  * 列值格式化（声明式、JSON 可序列化）。
  * 在 paginate 的 cellText 出口统一消费：格式化发生在进 RenderPlan 之前，
@@ -139,6 +151,20 @@ export declare type ColumnFormat = {
 /** 同一字段契约生成列语义和表头，业务侧无需复制另一份字段清单。 */
 export declare function columnsFromContract(contract: DatasetContract, overrides?: Record<string, Partial<TableTemplateColumn>>): TableTemplateColumn[];
 
+/** A literal own field of the current label record; expressions and paths are not evaluated. */
+export declare interface ComponentBinding {
+    field: string;
+    format?: ValueFormat;
+    prefix?: string;
+    suffix?: string;
+    emptyText?: string;
+}
+
+export declare interface ComponentBindingContext {
+    dataset?: string;
+    rowIndex?: number;
+}
+
 export declare interface ComponentImageContext {
     readonly component: Readonly<PlanComponent>;
     readonly pageIndex: number;
@@ -219,6 +245,9 @@ export declare function createCanvasPager(plan: RenderPlan, options?: CanvasPage
 /** 兼容旧 API：默认启发式测量 */
 export declare function createHeuristicMeasurer(): TextMeasurer;
 
+/** One declaration covers record binding, fixed paper size, copies and ordered multi-face labels. */
+export declare function createLabelTemplate(options: LabelTemplateOptions): ReportTemplate;
+
 /** Local catalog reference; an enterprise host supplies the same search/get contract with server filtering. */
 export declare function createLocalTemplateCatalog(input: LocalTemplateCatalogItem[]): ReportTemplateCatalogProvider;
 
@@ -323,6 +352,9 @@ export declare const DEFAULT_FONT_FAMILY = "\"Microsoft YaHei\", sans-serif";
 /** 默认字号（pt） */
 export declare const DEFAULT_FONT_PT = 10.5;
 
+/** Labels are bounded even when a host omits its normal report page budget. */
+export declare const DEFAULT_LABEL_PAGE_LIMIT = 10000;
+
 /** 默认描边色 */
 export declare const DEFAULT_STROKE_COLOR = "#333333";
 
@@ -480,6 +512,18 @@ export declare function isReportYear(value: string): boolean;
 
 export declare function isRichText(comp: PlanComponent): boolean;
 
+export declare interface LabelTemplateOptions extends ReportTemplateRepeat {
+    widthMm?: number;
+    heightMm?: number;
+    params?: ReportParamDef[];
+    /** A single face. Mutually exclusive with pages. */
+    components?: TemplateComponent[];
+    pages?: LabelTemplatePage[];
+}
+
+/** Each face inherits the label size; declare several faces for front/back or companion labels. */
+export declare type LabelTemplatePage = Pick<TemplatePage, "components" | "meta"> & Partial<Pick<TemplatePage, "widthMm" | "heightMm">>;
+
 /** 默认行高倍数（基线距 = 字号 × 该系数） */
 export declare const LINE_HEIGHT = 1.35;
 
@@ -798,6 +842,10 @@ export declare function parseReportDateRange(value: string): ReportDateRange | u
 export declare function parseReportTemplate(input: unknown): ReportTemplateDocument;
 
 export declare interface PlanComponent {
+    /** Optional QR/barcode encoding configuration; no encoder is loaded by the core. */
+    code?: CodeOptions;
+    /** Template-only binding; resolved and removed before constructing the output plan. */
+    binding?: ComponentBinding;
     /** Template page furniture repeats per page and reserves its vertical band. */
     pageAnchor?: "header" | "footer";
     kind: ComponentKind;
@@ -923,6 +971,14 @@ export declare function renderPlanToImages(plan: RenderPlan, options?: ImageRend
 /** 模板存储文档版本；与渲染计划版本独立演进。 */
 export declare const REPORT_TEMPLATE_DOCUMENT_VERSION = "1.0";
 
+export declare class ReportBindingError extends Error {
+    readonly path: string;
+    readonly rowIndex?: number | undefined;
+    readonly field?: string | undefined;
+    readonly code = "report-binding";
+    constructor(path: string, message: string, rowIndex?: number | undefined, field?: string | undefined);
+}
+
 export declare class ReportCalculationError extends Error {
     readonly code: ReportCalculationErrorCode;
     constructor(code: ReportCalculationErrorCode);
@@ -1334,7 +1390,7 @@ export declare class ReportSourceError extends Error {
 export declare interface ReportTaskEvent {
     taskId: string;
     correlationId?: string;
-    stage: "query" | "validate" | "layout" | "encode";
+    stage: "query" | "validate" | "layout" | "assets" | "encode";
     status: "started" | "completed" | "failed";
     reportId?: string;
     completed?: number;
@@ -1353,6 +1409,8 @@ export declare interface ReportTemplate {
     schemaVersion?: string;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
     params?: ReportParamDef[];
+    /** Fixed label pages repeat in record → copy → template-page order. */
+    repeat?: ReportTemplateRepeat;
     pages: TemplatePage[];
 }
 
@@ -1476,6 +1534,16 @@ export declare interface ReportTemplateRegistry {
     remove(id: string): boolean;
 }
 
+/** Every record emits its copies, each containing all template pages in their original order. */
+export declare interface ReportTemplateRepeat {
+    dataset: string;
+    rowKey?: string;
+    /** Whole copies per record, 1..1000. The field value must be a number, never a numeric string. */
+    copies?: number | {
+        field: string;
+    };
+}
+
 export declare interface ReportTemplateReview {
     ok: boolean;
     changes?: ReportTemplateDiff;
@@ -1497,6 +1565,8 @@ export declare interface ReportTemplateReviewIssue {
     pageIndex?: number;
     componentIndex?: number;
     field?: string;
+    /** Original structured output finding, retained for trusted publication resource handling. */
+    diagnostic?: OutputDiagnostic;
 }
 
 export declare interface ReportTemplateReviewOptions {
@@ -1547,6 +1617,9 @@ export declare interface ReportTemplateVersion {
  */
 export declare function resolveBoxBorders(style: Pick<ComponentStyle, "borderTop" | "borderRight" | "borderBottom" | "borderLeft"> | undefined): BoxBorders;
 
+/** The shared binding semantics for actual pagination and designer samples; never evaluates code. */
+export declare function resolveComponentBinding(binding: ComponentBinding, row: Record<string, unknown>, context?: ComponentBindingContext): string;
+
 /** 解析后的字号（px 值已按 dpi 换算；pt 值供 PDF 使用） */
 export declare interface ResolvedFontSize {
     fontSizePt: number;
@@ -1680,6 +1753,9 @@ export declare class TemplateBuilder {
     readonly pages: TemplatePage[];
     private pending;
     private templateParams;
+    private templateRepeat;
+    /** Fixed label pages repeat in record → copy → template-page order. */
+    repeat(options: ReportTemplateRepeat): this;
     /**
      * 声明报表参数（链式，可放在 .page() 前后任意位置）：
      * 渲染组件据此自动生成查询面板（也可由 paramDefs prop 提供，prop 优先）。
@@ -1841,6 +1917,9 @@ export declare interface ValidationResult {
     warnings: ValidationError[];
 }
 
+/** The same declarative formatting used by list columns, before any output backend. */
+export declare type ValueFormat = ColumnFormat;
+
 /**
  * 文本折行：
  * - CJK 字符任意位置可断（与既有行为一致）