@agile-team/mach-report 2.17.0 → 2.18.0

package/dist/xlsx.d.cts

@@ -35,6 +35,14 @@ declare interface AggregateDefinition {
 
 declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
 
+declare interface AggregateRequest {
+    op: AggregateOperation;
+    field?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+
 declare interface Alignment {
     	horizontal: 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
     	vertical: 'top' | 'middle' | 'bottom' | 'distributed' | 'justify';
@@ -416,6 +424,23 @@ declare type ColumnFormat = {
     pattern?: string;
 };
 
+declare type ColumnVisual = {
+    /** Defaults to the column field; never changes the cell's raw value or business identity. */
+    field?: string;
+    /** Numeric text requires explicit opt-in; formatting an identifier does not turn it into a measure. */
+    numeric?: "number" | "decimal";
+    min?: number;
+    max?: number;
+} & ({
+    kind: "colorScale";
+    lowColor?: string;
+    highColor?: string;
+} | {
+    kind: "dataBar";
+    color?: string;
+    negativeColor?: string;
+});
+
 declare interface Comment_2 {
     		texts?: RichText[];
     		margins?: Partial<CommentMargins>;
@@ -1188,6 +1213,12 @@ declare interface GradientStop {
 }
 
 declare interface GridCell {
+    /** Resolved visual only. Original value, text, editability and source are unchanged. */
+    dataBar?: {
+        start: number;
+        end: number;
+        color: string;
+    };
     /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
     richParagraphs?: RichParagraph[];
     text?: string;
@@ -1351,6 +1382,8 @@ declare interface ListColumn {
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule[];
+    /** Optional resolved color scale or value-preserving data bar. */
+    visual?: ColumnVisual;
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
@@ -1725,6 +1758,8 @@ export declare function parseExcelBindingSession(input: unknown): ExcelBindingSe
 export declare function parseExcelRegionBindingSession(input: unknown): ExcelRegionBindingSession;
 
 declare interface PlanComponent {
+    /** Template-only aggregate binding, expanded into shared primitives during layout. */
+    chartBinding?: ReportChartBinding;
     /** 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. */
@@ -1887,6 +1922,53 @@ declare interface ReportCellSource {
     sourceToken?: string;
 }
 
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+declare interface ReportChartBinding {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure[];
+    type: ReportChartOptions["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+
+declare interface ReportChartMeasure extends AggregateRequest {
+    label?: string;
+    color?: string;
+}
+
+declare interface ReportChartOptions {
+    type: "bar" | "line" | "stackedBar" | "percentBar";
+    categories: readonly string[];
+    series: readonly ReportChartSeries[];
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    title?: string;
+    showValues?: boolean;
+}
+
+declare interface ReportChartSeries {
+    name: string;
+    values: readonly (number | null)[];
+    color?: string;
+}
+
+declare interface ReportComparison {
+    field: string;
+    op: ">" | ">=" | "<" | "<=" | "==" | "!=" | "between" | "contains" | "isNull" | "isNotNull";
+    /** Legacy scalar thresholds remain supported. Use right for field-to-field comparisons. */
+    value?: ReportPredicateScalar;
+    right?: ReportPredicateOperand;
+    values?: readonly [ReportPredicateScalar, ReportPredicateScalar];
+    numeric?: "number" | "decimal";
+    valueType?: "number" | "decimal" | "text" | "date" | "boolean";
+}
+
 declare type ReportExpression = {
     field: string;
 } | {
@@ -1896,10 +1978,14 @@ declare type ReportExpression = {
     field?: string;
     weightField?: string;
 } | {
-    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    op: ReportExpressionOperation;
+    /** Required for if; args are [then, else], and only the selected branch is evaluated. */
+    condition?: ReportPredicate;
     args: readonly ReportExpression[];
 };
 
+declare type ReportExpressionOperation = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
+
 declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
 
 declare interface ReportFieldCalculation {
@@ -1952,12 +2038,9 @@ declare interface ReportParamDef {
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select" | "multiSelect" | "cascader" | "numberRange";
     /** select 选项 */
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
+    options?: ReportParamTreeOption[];
     /** Opaque host-resolved source key. No URL, credentials or executable code is stored. */
     optionsSource?: string;
     /** Select dependencies must be declared parameters; changing a parent clears descendants. */
@@ -1970,8 +2053,34 @@ declare interface ReportParamDef {
     max?: number | string;
     minLength?: number;
     maxLength?: number;
+    /** multiSelect item count (maximum 100). Cascader paths are bounded to 16 levels. */
+    minItems?: number;
+    maxItems?: number;
 }
 
+/** Cascader values are unique within each sibling list. */
+declare interface ReportParamTreeOption {
+    label: string;
+    value: string;
+    children?: ReportParamTreeOption[];
+}
+
+declare type ReportPredicate = ReportComparison | {
+    all: readonly ReportPredicate[];
+} | {
+    any: readonly ReportPredicate[];
+} | {
+    not: ReportPredicate;
+};
+
+declare type ReportPredicateOperand = {
+    field: string;
+} | {
+    value: ReportPredicateScalar;
+};
+
+declare type ReportPredicateScalar = string | number | boolean | null;
+
 declare interface ReportTemplate {
     schemaVersion?: string;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
@@ -2279,13 +2388,7 @@ declare interface Style {
 
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 declare interface StyleRule {
-    when: {
-        field: string;
-        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
-        value: number | string;
-        /** Explicit decimal comparisons retain decimal thresholds as text. */
-        numeric?: "number" | "decimal";
-    };
+    when: ReportPredicate;
     /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
     style: Record<string, unknown>;
 }
@@ -3157,6 +3260,8 @@ export declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImage
     sheetMode?: "auto" | "pages" | "continuous";
     /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
     valueMode?: "text" | "raw";
+    /** Static data-bar drawing budget; fail explicitly rather than omitting bars. Default 10,000. */
+    maxDataBars?: number;
     /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
     paperSize?: "auto" | "a3" | "a4" | "a5";
 }
@@ -3166,6 +3271,8 @@ export declare interface XlsxRenderResult {
     buffer: ExcelJS.Buffer;
     warnings: string[];
     diagnostics?: OutputDiagnostic[];
+    /** Informational output semantics; these do not indicate missing content. */
+    notes?: string[];
 }
 
 declare interface XlsxWriteOptions extends stream.xlsx.WorkbookWriterOptions {

package/dist/xlsx.d.ts

@@ -35,6 +35,14 @@ declare interface AggregateDefinition {
 
 declare type AggregateOperation = "sum" | "count" | "avg" | "min" | "max" | "weightedAvg";
 
+declare interface AggregateRequest {
+    op: AggregateOperation;
+    field?: string;
+    weightField?: string;
+    numeric?: "number" | "decimal";
+    digits?: number;
+}
+
 declare interface Alignment {
     	horizontal: 'left' | 'center' | 'right' | 'fill' | 'justify' | 'centerContinuous' | 'distributed';
     	vertical: 'top' | 'middle' | 'bottom' | 'distributed' | 'justify';
@@ -416,6 +424,23 @@ declare type ColumnFormat = {
     pattern?: string;
 };
 
+declare type ColumnVisual = {
+    /** Defaults to the column field; never changes the cell's raw value or business identity. */
+    field?: string;
+    /** Numeric text requires explicit opt-in; formatting an identifier does not turn it into a measure. */
+    numeric?: "number" | "decimal";
+    min?: number;
+    max?: number;
+} & ({
+    kind: "colorScale";
+    lowColor?: string;
+    highColor?: string;
+} | {
+    kind: "dataBar";
+    color?: string;
+    negativeColor?: string;
+});
+
 declare interface Comment_2 {
     		texts?: RichText[];
     		margins?: Partial<CommentMargins>;
@@ -1188,6 +1213,12 @@ declare interface GradientStop {
 }
 
 declare interface GridCell {
+    /** Resolved visual only. Original value, text, editability and source are unchanged. */
+    dataBar?: {
+        start: number;
+        end: number;
+        color: string;
+    };
     /** Styled cell content; text remains a plain-text fallback. Imported rich cells are read-only. */
     richParagraphs?: RichParagraph[];
     text?: string;
@@ -1351,6 +1382,8 @@ declare interface ListColumn {
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule[];
+    /** Optional resolved color scale or value-preserving data bar. */
+    visual?: ColumnVisual;
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
@@ -1725,6 +1758,8 @@ export declare function parseExcelBindingSession(input: unknown): ExcelBindingSe
 export declare function parseExcelRegionBindingSession(input: unknown): ExcelRegionBindingSession;
 
 declare interface PlanComponent {
+    /** Template-only aggregate binding, expanded into shared primitives during layout. */
+    chartBinding?: ReportChartBinding;
     /** 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. */
@@ -1887,6 +1922,53 @@ declare interface ReportCellSource {
     sourceToken?: string;
 }
 
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+declare interface ReportChartBinding {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure[];
+    type: ReportChartOptions["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+
+declare interface ReportChartMeasure extends AggregateRequest {
+    label?: string;
+    color?: string;
+}
+
+declare interface ReportChartOptions {
+    type: "bar" | "line" | "stackedBar" | "percentBar";
+    categories: readonly string[];
+    series: readonly ReportChartSeries[];
+    leftMm: number;
+    topMm: number;
+    widthMm: number;
+    heightMm: number;
+    title?: string;
+    showValues?: boolean;
+}
+
+declare interface ReportChartSeries {
+    name: string;
+    values: readonly (number | null)[];
+    color?: string;
+}
+
+declare interface ReportComparison {
+    field: string;
+    op: ">" | ">=" | "<" | "<=" | "==" | "!=" | "between" | "contains" | "isNull" | "isNotNull";
+    /** Legacy scalar thresholds remain supported. Use right for field-to-field comparisons. */
+    value?: ReportPredicateScalar;
+    right?: ReportPredicateOperand;
+    values?: readonly [ReportPredicateScalar, ReportPredicateScalar];
+    numeric?: "number" | "decimal";
+    valueType?: "number" | "decimal" | "text" | "date" | "boolean";
+}
+
 declare type ReportExpression = {
     field: string;
 } | {
@@ -1896,10 +1978,14 @@ declare type ReportExpression = {
     field?: string;
     weightField?: string;
 } | {
-    op: "add" | "subtract" | "multiply" | "divide" | "coalesce";
+    op: ReportExpressionOperation;
+    /** Required for if; args are [then, else], and only the selected branch is evaluated. */
+    condition?: ReportPredicate;
     args: readonly ReportExpression[];
 };
 
+declare type ReportExpressionOperation = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
+
 declare type ReportFieldAggregation = "sum" | "avg" | "min" | "max" | "count" | "none";
 
 declare interface ReportFieldCalculation {
@@ -1952,12 +2038,9 @@ declare interface ReportParamDef {
     field: string;
     /** 显示名（缺省用 field） */
     label?: string;
-    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select";
+    type?: "text" | "number" | "date" | "month" | "year" | "dateRange" | "select" | "multiSelect" | "cascader" | "numberRange";
     /** select 选项 */
-    options?: Array<{
-        label: string;
-        value: string;
-    }>;
+    options?: ReportParamTreeOption[];
     /** Opaque host-resolved source key. No URL, credentials or executable code is stored. */
     optionsSource?: string;
     /** Select dependencies must be declared parameters; changing a parent clears descendants. */
@@ -1970,8 +2053,34 @@ declare interface ReportParamDef {
     max?: number | string;
     minLength?: number;
     maxLength?: number;
+    /** multiSelect item count (maximum 100). Cascader paths are bounded to 16 levels. */
+    minItems?: number;
+    maxItems?: number;
 }
 
+/** Cascader values are unique within each sibling list. */
+declare interface ReportParamTreeOption {
+    label: string;
+    value: string;
+    children?: ReportParamTreeOption[];
+}
+
+declare type ReportPredicate = ReportComparison | {
+    all: readonly ReportPredicate[];
+} | {
+    any: readonly ReportPredicate[];
+} | {
+    not: ReportPredicate;
+};
+
+declare type ReportPredicateOperand = {
+    field: string;
+} | {
+    value: ReportPredicateScalar;
+};
+
+declare type ReportPredicateScalar = string | number | boolean | null;
+
 declare interface ReportTemplate {
     schemaVersion?: string;
     /** 参数定义（可选；宿主也可经 ReportPreview 的 paramDefs prop 提供，prop 优先） */
@@ -2279,13 +2388,7 @@ declare interface Style {
 
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 declare interface StyleRule {
-    when: {
-        field: string;
-        op: ">" | ">=" | "<" | "<=" | "==" | "!=";
-        value: number | string;
-        /** Explicit decimal comparisons retain decimal thresholds as text. */
-        numeric?: "number" | "decimal";
-    };
+    when: ReportPredicate;
     /** 命中时合并进单元格样式（color/bold/backgroundColor 等） */
     style: Record<string, unknown>;
 }
@@ -3157,6 +3260,8 @@ export declare interface XlsxRenderOptions extends AssetRenderOptions, XlsxImage
     sheetMode?: "auto" | "pages" | "continuous";
     /** 宽表或连续表默认 raw，其余默认 text；显式配置可覆盖默认值。 */
     valueMode?: "text" | "raw";
+    /** Static data-bar drawing budget; fail explicitly rather than omitting bars. Default 10,000. */
+    maxDataBars?: number;
     /** 连续表默认不限制打印纸型；显式 A3/A4/A5 仅设置打印适配，不改变 Excel 列宽。 */
     paperSize?: "auto" | "a3" | "a4" | "a5";
 }
@@ -3166,6 +3271,8 @@ export declare interface XlsxRenderResult {
     buffer: ExcelJS.Buffer;
     warnings: string[];
     diagnostics?: OutputDiagnostic[];
+    /** Informational output semantics; these do not indicate missing content. */
+    notes?: string[];
 }
 
 declare interface XlsxWriteOptions extends stream.xlsx.WorkbookWriterOptions {