@agile-team/mach-report 2.11.1 → 2.12.0

package/dist/codes.d.cts

@@ -0,0 +1,223 @@
+/** Stable failure category and field path, without echoing business payloads. */
+export declare class CodeImageError extends Error {
+    readonly code: CodeImageErrorCode;
+    readonly path?: string;
+    readonly cause: unknown;
+    constructor(code: CodeImageErrorCode, message: string, path?: string, cause?: unknown);
+}
+
+export declare type CodeImageErrorCode = "invalid-input" | "unsupported-format" | "capacity" | "encode-failed";
+
+export declare interface CodeImageOptions {
+    /** PNG raster resolution, default 300; independent of the preview zoom. */
+    dpi?: number;
+    /** UTF-8 payload budget, default 2048 bytes (linear symbols also cap at 256 characters). */
+    maxTextBytes?: number;
+    /** Raster allocation budget, default 4,000,000 grayscale pixels. */
+    maxPixels?: number;
+    /** Maximum width/height, default 4096 pixels. */
+    maxDimensionPx?: number;
+    /** Per-renderer successful-image LRU, default 64 entries; 0 disables caching. */
+    maxCacheEntries?: number;
+    /** Approximate retained UTF-16 key/data-URL bytes, default 8 MiB; 0 disables caching. */
+    maxCacheBytes?: number;
+}
+
+/** 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 之前，
+ * 三后端（DOM/Canvas/PDF）零改动。
+ *
+ * 语义约定（v0.9 固化）：
+ * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
+ * - number.thousands 默认 false（千分位显式开启）
+ * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
+ *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
+ */
+declare type ColumnFormat = {
+    kind: "number";
+    thousands?: boolean;
+    digits?: number;
+} | {
+    kind: "percent";
+    digits?: number;
+} | {
+    kind: "date";
+    pattern?: string;
+};
+
+/** A literal own field of the current label record; expressions and paths are not evaluated. */
+declare interface ComponentBinding {
+    field: string;
+    format?: ValueFormat;
+    prefix?: string;
+    suffix?: string;
+    emptyText?: string;
+}
+
+declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+
+declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+
+declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
+declare interface ComponentStyle {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+
+/** Plug into assets.assetRenderers. Its bounded LRU stores successful images only. */
+export declare function createCodeAssetRenderers(options?: CodeImageOptions): {
+    barcode: ComponentImageRenderer;
+    qrcode: ComponentImageRenderer;
+};
+
+declare interface GridCell {
+    text?: string;
+    rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
+    /** Physical left inset for hierarchical labels; raw value stays unchanged. */
+    indentMm?: number;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    source?: ReportCellSource;
+    /** SDK 派生结果不映射业务来源，始终只读（包括覆盖同名源字段的计算）。 */
+    derived?: boolean;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle;
+}
+
+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;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph[];
+    imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
+    grid?: PlanGrid;
+    table?: PlanTableFragment;
+    style?: ComponentStyle;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+
+declare interface PlanGrid {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
+}
+
+/** Cross-platform PNG output. It uses no DOM, Canvas, Buffer, network or platform font service. */
+export declare function renderCodeImage(component: Readonly<PlanComponent>, options?: CodeImageOptions, signal?: AbortSignal): Promise<string>;
+
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
+declare interface RichParagraph {
+    segments: RichSegment[];
+    align?: ComponentStyle["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+
+declare interface RichSegment {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle;
+}
+
+/** The same declarative formatting used by list columns, before any output backend. */
+declare type ValueFormat = ColumnFormat;
+
+export { }

package/dist/codes.d.ts

@@ -0,0 +1,223 @@
+/** Stable failure category and field path, without echoing business payloads. */
+export declare class CodeImageError extends Error {
+    readonly code: CodeImageErrorCode;
+    readonly path?: string;
+    readonly cause: unknown;
+    constructor(code: CodeImageErrorCode, message: string, path?: string, cause?: unknown);
+}
+
+export declare type CodeImageErrorCode = "invalid-input" | "unsupported-format" | "capacity" | "encode-failed";
+
+export declare interface CodeImageOptions {
+    /** PNG raster resolution, default 300; independent of the preview zoom. */
+    dpi?: number;
+    /** UTF-8 payload budget, default 2048 bytes (linear symbols also cap at 256 characters). */
+    maxTextBytes?: number;
+    /** Raster allocation budget, default 4,000,000 grayscale pixels. */
+    maxPixels?: number;
+    /** Maximum width/height, default 4096 pixels. */
+    maxDimensionPx?: number;
+    /** Per-renderer successful-image LRU, default 64 entries; 0 disables caching. */
+    maxCacheEntries?: number;
+    /** Approximate retained UTF-16 key/data-URL bytes, default 8 MiB; 0 disables caching. */
+    maxCacheBytes?: number;
+}
+
+/** 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 之前，
+ * 三后端（DOM/Canvas/PDF）零改动。
+ *
+ * 语义约定（v0.9 固化）：
+ * - number.digits 显式给出 → 精确保留（12.5 + digits:2 → "12.50"）
+ * - number.thousands 默认 false（千分位显式开启）
+ * - date 字符串按"本地时区的日历日"解析（YYYY-MM-DD / YYYY/MM/DD 直取年月日，
+ *   不经 Date 字符串构造——后者按 UTC 零点，负时区环境会少一天）
+ */
+declare type ColumnFormat = {
+    kind: "number";
+    thousands?: boolean;
+    digits?: number;
+} | {
+    kind: "percent";
+    digits?: number;
+} | {
+    kind: "date";
+    pattern?: string;
+};
+
+/** A literal own field of the current label record; expressions and paths are not evaluated. */
+declare interface ComponentBinding {
+    field: string;
+    format?: ValueFormat;
+    prefix?: string;
+    suffix?: string;
+    emptyText?: string;
+}
+
+declare interface ComponentImageContext {
+    readonly component: Readonly<PlanComponent>;
+    readonly pageIndex: number;
+    readonly componentIndex: number;
+    readonly componentPath: readonly number[];
+    readonly signal: AbortSignal;
+}
+
+declare type ComponentImageRenderer = (context: ComponentImageContext) => string | Promise<string>;
+
+declare type ComponentKind = "text" | "image" | "barcode" | "qrcode" | "chart" | "line" | "rect" | "ellipse";
+
+declare interface ComponentStyle {
+    fontSizePx?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    color?: string;
+    backgroundColor?: string;
+    align?: "left" | "center" | "right" | "justify";
+    verticalAlign?: "top" | "middle" | "bottom";
+    lineColor?: string;
+    borderColor?: string;
+    lineWidthPt?: number;
+    borderTop?: boolean;
+    borderRight?: boolean;
+    borderBottom?: boolean;
+    borderLeft?: boolean;
+    lineHeight?: number;
+    letterSpacing?: number;
+    opacity?: number;
+    rotateDeg?: number;
+}
+
+/** Plug into assets.assetRenderers. Its bounded LRU stores successful images only. */
+export declare function createCodeAssetRenderers(options?: CodeImageOptions): {
+    barcode: ComponentImageRenderer;
+    qrcode: ComponentImageRenderer;
+};
+
+declare interface GridCell {
+    text?: string;
+    rawText?: string;
+    /** 原始值，仅供 Excel raw 模式消费；不参与预览、分页与 PDF 绘制。 */
+    value?: string | number | boolean | null;
+    /** Excel 数字格式（例如 #,##0.00 / 0.00%），不改变 text。 */
+    numberFormat?: string;
+    /** Physical left inset for hierarchical labels; raw value stays unchanged. */
+    indentMm?: number;
+    /** 编辑输入类型；省略时只按原始值推断，数字字符串不会被转换为数值。 */
+    valueType?: "text" | "number" | "boolean";
+    /** 单元格级编辑控制；预览仍需显式开启 editing。 */
+    editable?: boolean;
+    source?: ReportCellSource;
+    /** SDK 派生结果不映射业务来源，始终只读（包括覆盖同名源字段的计算）。 */
+    derived?: boolean;
+    /** Excel 公式保留元数据；当前引擎不计算公式，公式格始终只读。 */
+    formula?: string;
+    children?: PlanComponent[];
+    colSpan?: number;
+    rowSpan?: number;
+    style?: ComponentStyle;
+}
+
+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;
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    nid?: string;
+    rkey?: string;
+    text?: string;
+    rawText?: string;
+    lines?: string[];
+    richParagraphs?: RichParagraph[];
+    imageData?: string;
+    /** 明确指定线段方向；省略保持历史水平线行为。 */
+    lineDirection?: "down" | "up";
+    grid?: PlanGrid;
+    table?: PlanTableFragment;
+    style?: ComponentStyle;
+    meta?: Record<string, unknown>;
+    /** MachReport 扩展字段：未知 kind 的兜底渲染标记 */
+    fallbackText?: string;
+}
+
+declare interface PlanGrid {
+    /** 行内允许 null 空位；渲染器按空单元格处理 */
+    cells: (GridCell | null)[][];
+    colWidthsMm?: number[];
+    rowHeightsMm?: number[];
+    gapMm?: number;
+    /** 单元格四边内距；旧静态网格默认 0.5mm，分页列表使用其真实测量内距。 */
+    paddingMm?: number;
+}
+
+/** 列表的逻辑行来源；用于连续 Excel 重组，避免按文本猜测重复表头。 */
+declare interface PlanTableFragment {
+    /** 在整个计划中唯一的逻辑表身份；同一表的分页片段共享身份。 */
+    id: string;
+    /** 表头固定 -1；其余行（包括组头/小计/总计）从 0 连续递增。 */
+    rowIndex: number;
+    role: "header" | "body" | "group-header" | "subtotal" | "grand-total";
+    /** 按物理列顺序保存字段身份；不以表头显示文本判断列结构。 */
+    columnKeys: string[];
+    layout?: "page" | "wide";
+    title?: string;
+    /** 只有宿主声明稳定 rowKey 时生成，不能用显示顺序替代业务主键。 */
+    source?: Omit<ReportCellSource, "field" | "rowKey"> & {
+        rowKey?: string | number;
+    };
+}
+
+/** Cross-platform PNG output. It uses no DOM, Canvas, Buffer, network or platform font service. */
+export declare function renderCodeImage(component: Readonly<PlanComponent>, options?: CodeImageOptions, signal?: AbortSignal): Promise<string>;
+
+/** 可持久化的业务身份与计划坐标独立；权限及并发校验仍由业务服务器执行。 */
+declare interface ReportCellSource {
+    datasetId: string;
+    rowKey: string | number;
+    field: string;
+    revision?: string | number;
+    sourceToken?: string;
+}
+
+declare interface RichParagraph {
+    segments: RichSegment[];
+    align?: ComponentStyle["align"];
+    lineHeight?: number;
+    spaceBeforeMm?: number;
+    spaceAfterMm?: number;
+    indentMm?: number;
+}
+
+declare interface RichSegment {
+    kind?: "text" | "field";
+    text?: string;
+    field?: string;
+    style?: ComponentStyle;
+}
+
+/** The same declarative formatting used by list columns, before any output backend. */
+declare type ValueFormat = ColumnFormat;
+
+export { }