@agile-team/mach-report 2.16.0 → 2.18.0

package/dist/analytics.d.cts

@@ -62,6 +62,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;
+});
+
 export declare function compareDecimal(a: DecimalValue, b: DecimalValue): number;
 
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
@@ -153,7 +170,10 @@ export declare function createChartComponents(options: ReportChartOptions): Plan
 export declare function createCrossTable(input: readonly Record<string, unknown>[], options: CrossTableOptions): CrossTableResult;
 
 /** Multi-measure pivot shares dimensions and original rows; weighted totals never average averages. */
-export declare function createMatrixTable(input: readonly Record<string, unknown>[], options: MatrixTableOptions): CrossTableResult;
+export declare function createMatrixTable(input: readonly Record<string, unknown>[], options: MatrixTableOptions): MatrixTableResult;
+
+/** One bounded scan, shared aggregate semantics; labels never coerce identifier source values. */
+export declare function createReportChartData(rows: readonly Record<string, unknown>[], binding: ReportChartBinding, signal?: AbortSignal): ReportChartData;
 
 export declare interface CrossTableOptions {
     rowField: string;
@@ -221,38 +241,8 @@ export declare function getComputationMetadata(fields?: readonly {
         type: string;
         label?: string;
     }[];
-    functions: readonly [{
-        readonly name: "add";
-        readonly minArgs: 2;
-        readonly maxArgs: 256;
-        readonly input: "numeric";
-        readonly output: "numeric";
-    }, {
-        readonly name: "subtract";
-        readonly minArgs: 2;
-        readonly maxArgs: 2;
-        readonly input: "numeric";
-        readonly output: "numeric";
-    }, {
-        readonly name: "multiply";
-        readonly minArgs: 2;
-        readonly maxArgs: 256;
-        readonly input: "numeric";
-        readonly output: "numeric";
-    }, {
-        readonly name: "divide";
-        readonly minArgs: 2;
-        readonly maxArgs: 2;
-        readonly input: "numeric";
-        readonly output: "numeric";
-    }, {
-        readonly name: "coalesce";
-        readonly minArgs: 2;
-        readonly maxArgs: 256;
-        readonly input: "scalar";
-        readonly output: "scalar";
-    }];
-    operations: readonly ["add", "subtract", "multiply", "divide", "coalesce"];
+    functions: readonly ReportExpressionFunction[];
+    operations: ReportExpressionOperation[];
     aggregates: readonly ["sum", "count", "avg", "min", "max", "weightedAvg"];
     scopes: readonly ["row", "group", "dataset"];
     numericModes: readonly ["number", "decimal"];
@@ -268,6 +258,12 @@ export declare function getComputationMetadata(fields?: readonly {
 };
 
 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;
@@ -311,6 +307,8 @@ declare interface ListColumn {
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule[];
+    /** Optional resolved color scale or value-preserving data bar. */
+    visual?: ColumnVisual;
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
@@ -322,6 +320,58 @@ declare interface ListColumn {
     visibleWhen?: StyleRule["when"];
 }
 
+export declare interface MatrixAxisOptions {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+
+export declare interface MatrixColumnMember extends MatrixDimensionMember {
+    field: string;
+    measure: number;
+    measureField: string;
+    valueField: string;
+    operation: AggregateOperation;
+}
+
+export declare interface MatrixDimensionMember {
+    /** Typed field/value identity, independent of labels, source order and display indices. */
+    key: string;
+    kind: "member" | "subtotal" | "total";
+    depth: number;
+    /** Prefix predicates. Empty for grand totals; never business write identities. */
+    fields: string[];
+    values: MatrixDimensionValue[];
+    labels: string[];
+}
+
+export declare type MatrixDimensionOrder = "source" | "asc" | "desc";
+
+export declare type MatrixDimensionValue = string | number | boolean | null;
+
+export declare interface MatrixHierarchyOptions {
+    row?: MatrixAxisOptions;
+    column?: MatrixAxisOptions;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
+
+export declare interface MatrixTableMetadata {
+    rowFields: string[];
+    rowLabels: string[];
+    columnFields: string[];
+    columnLabels: string[];
+    /** Aligned with result.rows. */
+    rows: MatrixDimensionMember[];
+    /** Measure columns only, addressed by their generated field. */
+    columns: MatrixColumnMember[];
+}
+
 export declare interface MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -336,6 +386,16 @@ export declare interface MatrixTableOptions {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
+}
+
+export declare interface MatrixTableResult extends CrossTableResult {
+    /** Present only for opt-in hierarchy; the paginator supplies final physical widths/styles. */
+    headerGrid?: PlanGrid;
+    metadata?: MatrixTableMetadata;
 }
 
 export declare interface MatrixTableShape {
@@ -349,6 +409,8 @@ export declare function multiplyDecimal(a: DecimalValue, b: DecimalValue): Decim
 export declare function parseDecimal(input: unknown): DecimalValue;
 
 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. */
@@ -417,8 +479,31 @@ declare interface ReportCellSource {
     sourceToken?: string;
 }
 
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+export declare interface ReportChartBinding {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure[];
+    type: ReportChartOptions["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+
+export declare interface ReportChartData {
+    categories: string[];
+    series: ReportChartSeries[];
+}
+
+export declare interface ReportChartMeasure extends AggregateRequest {
+    label?: string;
+    color?: string;
+}
+
 export declare interface ReportChartOptions {
-    type: "bar" | "line";
+    type: "bar" | "line" | "stackedBar" | "percentBar";
     categories: readonly string[];
     series: readonly ReportChartSeries[];
     leftMm: number;
@@ -435,6 +520,17 @@ export declare interface ReportChartSeries {
     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";
+}
+
 export declare type ReportExpression = {
     field: string;
 } | {
@@ -444,10 +540,39 @@ export 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 interface ReportExpressionFunction {
+    readonly name: ReportExpressionOperation;
+    readonly minArgs: number;
+    readonly maxArgs: number;
+    readonly input: string;
+    readonly output: string;
+    readonly example: string;
+}
+
+declare type ReportExpressionOperation = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
+
+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 RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -466,13 +591,7 @@ declare interface RichSegment {
 
 /** 条件格式规则求值（声明式，见 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>;
 }
@@ -489,6 +608,8 @@ export declare function validateComputedFields(definitions: readonly ComputedFie
 
 export declare function validateMatrixOptions(options: MatrixTableOptions): void;
 
+export declare function validateReportChartBinding(binding: ReportChartBinding): void;
+
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat = ColumnFormat;
 

package/dist/analytics.d.ts

@@ -62,6 +62,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;
+});
+
 export declare function compareDecimal(a: DecimalValue, b: DecimalValue): number;
 
 /** A literal own field of the current label record; expressions and paths are not evaluated. */
@@ -153,7 +170,10 @@ export declare function createChartComponents(options: ReportChartOptions): Plan
 export declare function createCrossTable(input: readonly Record<string, unknown>[], options: CrossTableOptions): CrossTableResult;
 
 /** Multi-measure pivot shares dimensions and original rows; weighted totals never average averages. */
-export declare function createMatrixTable(input: readonly Record<string, unknown>[], options: MatrixTableOptions): CrossTableResult;
+export declare function createMatrixTable(input: readonly Record<string, unknown>[], options: MatrixTableOptions): MatrixTableResult;
+
+/** One bounded scan, shared aggregate semantics; labels never coerce identifier source values. */
+export declare function createReportChartData(rows: readonly Record<string, unknown>[], binding: ReportChartBinding, signal?: AbortSignal): ReportChartData;
 
 export declare interface CrossTableOptions {
     rowField: string;
@@ -221,38 +241,8 @@ export declare function getComputationMetadata(fields?: readonly {
         type: string;
         label?: string;
     }[];
-    functions: readonly [{
-        readonly name: "add";
-        readonly minArgs: 2;
-        readonly maxArgs: 256;
-        readonly input: "numeric";
-        readonly output: "numeric";
-    }, {
-        readonly name: "subtract";
-        readonly minArgs: 2;
-        readonly maxArgs: 2;
-        readonly input: "numeric";
-        readonly output: "numeric";
-    }, {
-        readonly name: "multiply";
-        readonly minArgs: 2;
-        readonly maxArgs: 256;
-        readonly input: "numeric";
-        readonly output: "numeric";
-    }, {
-        readonly name: "divide";
-        readonly minArgs: 2;
-        readonly maxArgs: 2;
-        readonly input: "numeric";
-        readonly output: "numeric";
-    }, {
-        readonly name: "coalesce";
-        readonly minArgs: 2;
-        readonly maxArgs: 256;
-        readonly input: "scalar";
-        readonly output: "scalar";
-    }];
-    operations: readonly ["add", "subtract", "multiply", "divide", "coalesce"];
+    functions: readonly ReportExpressionFunction[];
+    operations: ReportExpressionOperation[];
     aggregates: readonly ["sum", "count", "avg", "min", "max", "weightedAvg"];
     scopes: readonly ["row", "group", "dataset"];
     numericModes: readonly ["number", "decimal"];
@@ -268,6 +258,12 @@ export declare function getComputationMetadata(fields?: readonly {
 };
 
 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;
@@ -311,6 +307,8 @@ declare interface ListColumn {
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule[];
+    /** Optional resolved color scale or value-preserving data bar. */
+    visual?: ColumnVisual;
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
@@ -322,6 +320,58 @@ declare interface ListColumn {
     visibleWhen?: StyleRule["when"];
 }
 
+export declare interface MatrixAxisOptions {
+    /** Display names in the same outer-to-inner order as the dimension fields. */
+    labels?: readonly string[];
+    /** Per-level sibling order; omitted levels retain first-seen order. */
+    sort?: readonly MatrixDimensionOrder[];
+    /** One-based prefix depths. Leaf depths are not subtotals. */
+    subtotals?: readonly number[];
+}
+
+export declare interface MatrixColumnMember extends MatrixDimensionMember {
+    field: string;
+    measure: number;
+    measureField: string;
+    valueField: string;
+    operation: AggregateOperation;
+}
+
+export declare interface MatrixDimensionMember {
+    /** Typed field/value identity, independent of labels, source order and display indices. */
+    key: string;
+    kind: "member" | "subtotal" | "total";
+    depth: number;
+    /** Prefix predicates. Empty for grand totals; never business write identities. */
+    fields: string[];
+    values: MatrixDimensionValue[];
+    labels: string[];
+}
+
+export declare type MatrixDimensionOrder = "source" | "asc" | "desc";
+
+export declare type MatrixDimensionValue = string | number | boolean | null;
+
+export declare interface MatrixHierarchyOptions {
+    row?: MatrixAxisOptions;
+    column?: MatrixAxisOptions;
+    /** Only null/missing values use this label; empty strings and zero stay distinct. */
+    emptyLabel?: string;
+    subtotalLabel?: string;
+    totalLabel?: string;
+}
+
+export declare interface MatrixTableMetadata {
+    rowFields: string[];
+    rowLabels: string[];
+    columnFields: string[];
+    columnLabels: string[];
+    /** Aligned with result.rows. */
+    rows: MatrixDimensionMember[];
+    /** Measure columns only, addressed by their generated field. */
+    columns: MatrixColumnMember[];
+}
+
 export declare interface MatrixTableOptions {
     rowFields: readonly string[];
     columnFields: readonly string[];
@@ -336,6 +386,16 @@ export declare interface MatrixTableOptions {
     maxColumns?: number;
     maxInputRows?: number;
     maxCells?: number;
+    /** Opt-in hierarchical dimensions, physical merged headers and prefix subtotals. */
+    hierarchy?: MatrixHierarchyOptions;
+    /** Hierarchical aggregate work, checked before measure reads; default 10 million updates. */
+    maxAggregateUpdates?: number;
+}
+
+export declare interface MatrixTableResult extends CrossTableResult {
+    /** Present only for opt-in hierarchy; the paginator supplies final physical widths/styles. */
+    headerGrid?: PlanGrid;
+    metadata?: MatrixTableMetadata;
 }
 
 export declare interface MatrixTableShape {
@@ -349,6 +409,8 @@ export declare function multiplyDecimal(a: DecimalValue, b: DecimalValue): Decim
 export declare function parseDecimal(input: unknown): DecimalValue;
 
 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. */
@@ -417,8 +479,31 @@ declare interface ReportCellSource {
     sourceToken?: string;
 }
 
+/** Serializable binding; data and authorization continue to come from the existing report source. */
+export declare interface ReportChartBinding {
+    dataset: string;
+    categoryField: string;
+    measures: readonly ReportChartMeasure[];
+    type: ReportChartOptions["type"];
+    sort?: "asc" | "desc";
+    title?: string;
+    showValues?: boolean;
+    maxRows?: number;
+    maxCategories?: number;
+}
+
+export declare interface ReportChartData {
+    categories: string[];
+    series: ReportChartSeries[];
+}
+
+export declare interface ReportChartMeasure extends AggregateRequest {
+    label?: string;
+    color?: string;
+}
+
 export declare interface ReportChartOptions {
-    type: "bar" | "line";
+    type: "bar" | "line" | "stackedBar" | "percentBar";
     categories: readonly string[];
     series: readonly ReportChartSeries[];
     leftMm: number;
@@ -435,6 +520,17 @@ export declare interface ReportChartSeries {
     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";
+}
+
 export declare type ReportExpression = {
     field: string;
 } | {
@@ -444,10 +540,39 @@ export 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 interface ReportExpressionFunction {
+    readonly name: ReportExpressionOperation;
+    readonly minArgs: number;
+    readonly maxArgs: number;
+    readonly input: string;
+    readonly output: string;
+    readonly example: string;
+}
+
+declare type ReportExpressionOperation = "add" | "subtract" | "multiply" | "divide" | "coalesce" | "if" | "round" | "abs" | "concat" | "trim" | "upper" | "lower" | "dateYear" | "dateMonth" | "dateDay";
+
+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 RichParagraph {
     segments: RichSegment[];
     align?: ComponentStyle["align"];
@@ -466,13 +591,7 @@ declare interface RichSegment {
 
 /** 条件格式规则求值（声明式，见 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>;
 }
@@ -489,6 +608,8 @@ export declare function validateComputedFields(definitions: readonly ComputedFie
 
 export declare function validateMatrixOptions(options: MatrixTableOptions): void;
 
+export declare function validateReportChartBinding(binding: ReportChartBinding): void;
+
 /** The same declarative formatting used by list columns, before any output backend. */
 declare type ValueFormat = ColumnFormat;