@agile-team/mach-report 2.11.2 → 2.13.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,12 +352,22 @@ 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";
 
 /** 默认文本色 */
 export declare const DEFAULT_TEXT_COLOR = "#000000";
 
+/**
+ * Flat label integration for the same Vue/Node source pipeline: template + rows/load.
+ * It maps the one dataset and optional contract without caching or converting business values.
+ * Dynamic templates and multiple datasets continue to use defineReport.
+ */
+export declare function defineLabelReport(options: LabelReportDefinitionOptions): ReportDefinition;
+
 /** 类型推导业务接口的响应，包内完成字段映射后交给同一分页流程。 */
 export declare function defineReport<TData>(definition: ReportDefinitionOptions<TData>): ReportDefinition;
 
@@ -480,6 +519,36 @@ export declare function isReportYear(value: string): boolean;
 
 export declare function isRichText(comp: PlanComponent): boolean;
 
+declare interface LabelReportDefinitionBase extends Pick<ReportDefinition, "params" | "pagination" | "dataValidation"> {
+    /** An existing fixed label template. Its repeat.dataset supplies the dataset name. */
+    template: ReportTemplate;
+    /** The single label dataset's contract; no dataset-name wrapper is needed. */
+    dataSchema?: DatasetContract;
+}
+
+export declare type LabelReportDefinitionOptions = LabelReportDefinitionBase & ({
+    rows: LabelReportRows;
+    load?: never;
+} | {
+    rows?: never;
+    load: (context: ReportLoadContext) => LabelReportRows | Promise<LabelReportRows>;
+});
+
+/** Named business row interfaces and readonly arrays need no index signature or conversion. */
+export declare type LabelReportRows = readonly object[];
+
+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 +867,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 +996,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 +1415,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 +1434,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 +1559,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 +1590,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 +1642,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 +1778,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 +1942,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 字符任意位置可断（与既有行为一致）