@agile-team/mach-report 2.17.0 → 2.19.0

package/dist/index.d.cts

@@ -10,6 +10,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;
+}
+
 /** 复制发生变化的页/组件/行；原计划保持不变，并拒绝覆盖已改变的单元格。 */
 export declare function applyReportCellEdit(plan: RenderPlan, edit: ReportCellEdit): RenderPlan;
 
@@ -29,6 +37,8 @@ export declare function assertRenderPlan(input: unknown): PlanPage[];
 
 export declare function assertReportParams(defs: readonly ReportParamDef[], input?: Record<string, unknown>): Record<string, string>;
 
+export declare function assertReportValidation(issues: readonly ReportValidationIssue[], warningPolicy?: "allow" | "block"): void;
+
 export declare interface AssetRenderBudget {
     /** Maximum newly rendered assets, default 1000. Existing imageData is kept unchanged. */
     maxAssets?: number;
@@ -164,6 +174,31 @@ export declare type ColumnFormat = {
 /** 同一字段契约生成列语义和表头，业务侧无需复制另一份字段清单。 */
 export declare function columnsFromContract(contract: DatasetContract, overrides?: Record<string, Partial<TableTemplateColumn>>): TableTemplateColumn[];
 
+export 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;
+});
+
+/** Stable-key comparison of business data or instance snapshots. Never compares report coordinates. */
+export declare function compareReportData(before: ReportDataSnapshot, after: ReportDataSnapshot, options: ReportDataComparisonOptions): ReportDataComparison;
+
+/** Bounded declarative conditions shared by visibility, styles, IF and candidate validation. */
+export declare function compileReportPredicate(predicate: ReportPredicate, budget?: {
+    nodes: number;
+}, depth?: number): ReportPredicateReader;
+
 export declare interface ComponentAssetRegistry {
     rendererFor(component: Readonly<PlanComponent>): ComponentImageRenderer | undefined;
     hasExtension(id: string, version: string, kind: string): boolean;
@@ -295,6 +330,9 @@ export declare function createReportCellEditBatch(plan: RenderPlan, inputs: read
 /** Operation-scoped index: avoids repeated geometry work without caching mutable plans globally. */
 export declare function createReportCellResolver(plan: RenderPlan): (address: ReportCellAddress) => ReportCellContext | null;
 
+/** 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;
+
 /** Explicit per-host registry. Templates contain bounded JSON bindings; loaders never come from a template. */
 export declare function createReportComponentRegistry(definitions: readonly ReportComponentExtensionDefinition[]): ReportComponentRegistry;
 
@@ -308,6 +346,9 @@ export declare function createReportEditSession(options: {
     pagination?: PaginateOptions;
 }): ReportEditSession;
 
+/** Explicit field allowlist + stable business keys. Does not mutate, persist or replace a workbook. */
+export declare function createReportPrefill(plan: RenderPlan, options: ReportPrefillOptions): ReportPrefillPreview;
+
 /**
  * 框架无关的报表数据源：注册一次模板与取数，包内完成分页、校验、按 ID 顺序合并。
  * 不缓存业务结果、不推断接口包装、不自动重试；鉴权与完整数据范围由宿主决定。
@@ -317,6 +358,7 @@ export declare function createReportSource(reports: ReportRegistry, options?: {
     onDatasets?: (reportId: string, datasets: DatasetRows, template: ReportTemplate) => void;
     maxPages?: number;
     maxCells?: number;
+    maxChartComponents?: number;
 }): ReportSource;
 
 /**
@@ -434,6 +476,8 @@ export declare function evalStyleRule(row: Record<string, unknown>, when: StyleR
 /** A tiny arithmetic parser: no functions, property access, globals, assignments or executable source. */
 export declare function evaluateReportAggregateExpression(expression: string, values: Readonly<Record<string, number>>): number;
 
+export declare function evaluateReportPredicate(row: Readonly<Record<string, unknown>>, predicate: ReportPredicate): boolean;
+
 /** Derives locatable explanations only from explicit business declarations; never evaluates formulas. */
 export declare function explainDatasetField(contract: DatasetContract, target: ReportDataTarget): ReportDiagnostic[];
 
@@ -444,6 +488,8 @@ declare interface ExpressionOptions {
     divisionByZero?: "null" | "error";
 }
 
+export declare function formatReportCascaderPath(value: readonly string[]): string;
+
 /** 同步 text/raw value，所有输出后端读取同一份更新后的 RenderPlan。 */
 export declare function formatReportCellEdit(context: ReportCellContext, value: ReportCellValue): string;
 
@@ -452,6 +498,10 @@ export declare function formatReportClipboard(rows: readonly (readonly string[])
 
 export declare function formatReportDateRange(range: ReportDateRange): string;
 
+export declare function formatReportNumberRange(value: ReportNumberRange): string;
+
+export declare function formatReportParamSelection(value: readonly string[]): string;
+
 /**
  * 应用格式化。非数值/无法解析时原样返回基础文本（降级不报错）：
  * - number：digits 小数位 + 可选千分位（12,345.60；thousands 默认 false）
@@ -476,6 +526,12 @@ export declare function getReportCellContext(plan: RenderPlan, address: ReportCe
 export declare function getReportEditSession(plan: RenderPlan): ReportEditSession | undefined;
 
 export 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;
@@ -688,6 +744,8 @@ export declare interface ListColumn {
     format?: ColumnFormat;
     /** 条件格式规则（声明式，命中合并进单元格样式；如负数红字） */
     rules?: StyleRule[];
+    /** Optional resolved color scale or value-preserving data bar. */
+    visual?: ColumnVisual;
     /** 内容列编辑控制；仍需由预览显式开启 editing，不影响表头/小计只读规则。 */
     editable?: boolean;
     /** 空值列或特殊数据类型可显式声明编辑输入类型。 */
@@ -955,6 +1013,13 @@ export declare class PaginateCellLimitError extends Error {
     constructor(limit: number, actual: number);
 }
 
+export declare class PaginateChartComponentLimitError extends Error {
+    readonly limit: number;
+    readonly estimated: number;
+    readonly code = "chart-component-limit";
+    constructor(limit: number, estimated: number);
+}
+
 export declare interface PaginateOptions {
     /** 每行额外占高（mm），压测专用钩子 */
     mmPerRow?: number;
@@ -964,6 +1029,8 @@ export declare interface PaginateOptions {
     maxPages?: number;
     /** Actual grid cells, including repeated furniture and nested children; checked before each page is appended. */
     maxCells?: number;
+    /** Shared bound-chart primitive budget, checked before expansion; default 50000, range 1..1000000. */
+    maxChartComponents?: number;
     signal?: AbortSignal;
     /** Streaming total-page anchors can skip the bounded counting pass when known. */
     knownTotalPages?: number;
@@ -982,6 +1049,8 @@ export declare class PaginatePageLimitError extends Error {
 export declare interface PaginateResult {
     plan: RenderPlan;
     warnings: string[];
+    /** Actual resolved bound-chart primitives, including empty placeholders. */
+    chartComponents: number;
 }
 
 /** Compatibility collector: the pagination engine is shared with the bounded page iterator. */
@@ -1001,6 +1070,8 @@ export declare type PaperName = keyof typeof PAPER_SIZES;
 /** 日历日字符串 → 本地 Date（不含时间的纯日期，杜绝 UTC 偏移） */
 export declare function parseDateLocal(input: string): Date | null;
 
+export declare function parseReportCascaderPath(value: unknown): string[] | undefined;
+
 /** Core type parsing is authoritative; field controls add restrictions, never coerce IDs or bypass readonly. */
 export declare function parseReportCellFieldInput(context: ReportCellContext, input: ReportCellValue, field?: ReportCellFieldOptions): ReportCellValue;
 
@@ -1013,10 +1084,16 @@ export declare function parseReportClipboard(text: string, maxCells?: number): s
 /** Only complete, ordered, real calendar dates are accepted; there is no timezone conversion. */
 export declare function parseReportDateRange(value: string): ReportDateRange | undefined;
 
+export declare function parseReportNumberRange(value: unknown): ReportNumberRange | undefined;
+
+export declare function parseReportParamSelection(value: unknown): string[] | undefined;
+
 /** 校验文件 JSON 文本或接口返回的未知对象，返回独立模板快照。 */
 export declare function parseReportTemplate(input: unknown): ReportTemplateDocument;
 
 export 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. */
@@ -1168,6 +1245,11 @@ export declare interface ReportCalculationSelection {
     focus: ReportCellAddress;
 }
 
+export declare interface ReportCandidateValidationOptions extends Pick<ReportDatasetValidationOptions, "rules" | "maxChecks" | "maxIssues"> {
+    /** Warnings are visible and allowed by default; block explicitly when required by business policy. */
+    warningPolicy?: "allow" | "block";
+}
+
 /** 预览中的物理坐标；合并单元格使用左上角坐标。 */
 export declare interface ReportCellAddress {
     pageIndex: number;
@@ -1282,6 +1364,58 @@ export declare type ReportCellValue = string | number | boolean | null;
 
 export declare type ReportCellValueType = NonNullable<GridCell["valueType"]>;
 
+/** 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;
+}
+
+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;
+}
+
+export 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 interface ReportComponentExtensionBinding {
     id: string;
     version: string;
@@ -1350,6 +1484,89 @@ export declare interface ReportComponentRegistry extends ComponentAssetRegistry
 
 export declare type ReportComponentValue = string | number | boolean | null;
 
+export declare interface ReportDataComparison {
+    sourceScope?: string;
+    datasetId: string;
+    differences: readonly ReportDataDifference[];
+    counts: {
+        added: number;
+        removed: number;
+        changed: number;
+        unchanged: number;
+        cells: number;
+    };
+}
+
+export declare interface ReportDataComparisonField {
+    field: string;
+    label?: string;
+    /** Numeric comparison is explicit; identifiers containing digits stay text. */
+    type?: "value" | "decimal";
+    /** Absolute decimal tolerance, inclusive. No binary floating-point subtraction. */
+    tolerance?: string;
+    /** Fractional ratio digits. changeRatio is (after - before) / before, not a percent. */
+    ratioDigits?: number;
+    zeroDenominator?: "omit" | "zero-if-equal";
+    missing?: "distinct" | "empty-equivalent" | "zero";
+}
+
+export declare interface ReportDataComparisonOptions extends ReportDataLimits {
+    fields: readonly ReportDataComparisonField[];
+    maxDifferences?: number;
+}
+
+export declare interface ReportDataDifference {
+    rowKey: string | number;
+    kind: "added" | "removed" | "changed";
+    field: string;
+    label: string;
+    before: ReportCellValue | undefined;
+    after: ReportCellValue | undefined;
+    /** Exact base-ten difference. Undefined when either input is missing/non-numeric. */
+    delta?: string;
+    changeRatio?: string;
+    ratioUnavailable?: "zero-denominator" | "missing";
+}
+
+export declare class ReportDataError extends Error {
+    readonly code: "identity" | "duplicate" | "limit" | "value" | "conflict";
+    constructor(code: "identity" | "duplicate" | "limit" | "value" | "conflict", message: string);
+}
+
+export declare interface ReportDataLimits {
+    maxRows?: number;
+    maxFields?: number;
+    maxCells?: number;
+}
+
+/** A business record, never a physical report row index. */
+export declare interface ReportDataRecord {
+    rowKey: string | number;
+    values: Readonly<Record<string, ReportCellValue>>;
+}
+
+export declare interface ReportDatasetValidationOptions {
+    rules: readonly ReportValidationRule[];
+    rowKey?: string;
+    computed?: readonly ComputedField[];
+    /** Explicit trusted engine, shared with pagination; never read from a serialized template. */
+    formula?: FormulaAdapter;
+    /** Uses the same bounded tree preparation and descendant-leaf summaries as pagination. */
+    tree?: TreeTableOptions;
+    maxChecks?: number;
+    maxIssues?: number;
+    signal?: AbortSignal;
+}
+
+export declare interface ReportDataSnapshot {
+    sourceScope?: string;
+    datasetId: string;
+    rows: readonly ReportDataRecord[];
+}
+
+/** Extracts explicit fields from the same rendered query; never makes a second business request. */
+export declare function reportDataSnapshotFromPlan(plan: RenderPlan, options: ReportPlanDataOptions): ReportDataSnapshot;
+
 export declare interface ReportDataTarget {
     datasetId: string;
     field: string;
@@ -1360,6 +1577,17 @@ export declare interface ReportDataTarget {
     reportScope?: string;
 }
 
+/** Resolve a business calendar default once per request; returns only a portable date value. */
+export declare function reportDateDefault(options: ReportDateDefaultOptions): string;
+
+export declare interface ReportDateDefaultOptions {
+    preset: "today" | "yesterday" | "month-start" | "month-end";
+    /** Explicit business clock in milliseconds or Date; no hidden browser/server clock. */
+    now: number | Date;
+    timeZone: string;
+    offsetDays?: number;
+}
+
 /** Wire values deliberately remain strings in browsers, Workers and backend runtimes. */
 export declare interface ReportDateRange {
     start: string;
@@ -1462,6 +1690,7 @@ export declare interface ReportEditConflict {
 
 export declare interface ReportEditPreparationOptions {
     signal?: AbortSignal;
+    validation?: ReportCandidateValidationOptions;
 }
 
 export declare interface ReportEditResult {
@@ -1486,6 +1715,8 @@ declare interface ReportEditSessionPart {
 
 export declare interface ReportEditSessionRegistration {
     parts: readonly ReportEditSessionPart[];
+    /** Trusted runtime adapters stay outside the serializable guarded source snapshot. */
+    validationFormulas?: readonly (FormulaAdapter | undefined)[];
     rebuild(parts: readonly ReportEditSessionPart[], signal?: AbortSignal): Promise<RenderPlan>;
 }
 
@@ -1498,10 +1729,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";
+
 /** 保持 Promise<RenderPlan> 契约；元数据为可选，旧业务 fetcher 无需改造。 */
 export declare interface ReportFetcher {
     (input: ReportFetchInput): Promise<RenderPlan>;
@@ -1573,6 +1808,8 @@ export declare interface ReportLoadContext {
     signal?: AbortSignal;
 }
 
+export declare type ReportNumberRange = readonly [number, number];
+
 export declare function reportOutputDiagnostics(plan: RenderPlan, format: OutputFormat, options: OutputDiagnosticOptions): OutputDiagnostic[];
 
 export declare interface ReportPageFlow {
@@ -1585,12 +1822,9 @@ export 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. */
@@ -1603,6 +1837,9 @@ export 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;
 }
 
 export declare interface ReportParamIssue {
@@ -1612,17 +1849,26 @@ export declare interface ReportParamIssue {
     message: string;
 }
 
-export declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength";
+export declare type ReportParamIssueCode = "definition" | "required" | "type" | "option" | "dependency" | "minimum" | "maximum" | "minLength" | "maxLength" | "minItems" | "maxItems";
 
 /** 描述 typedValues 的 Draft 2020-12 Schema；日期区间额外保留 x-report-* 扩展。 */
 export declare function reportParamsJsonSchema(defs: readonly ReportParamDef[]): Record<string, unknown>;
 
+/** Cascader values are unique within each sibling list. */
+export declare interface ReportParamTreeOption {
+    label: string;
+    value: string;
+    children?: ReportParamTreeOption[];
+}
+
+export declare type ReportParamTypedValue = string | number | string[] | ReportNumberRange;
+
 export declare interface ReportParamValidation {
     ok: boolean;
     /** 保留历史取数契约的字符串形式；未知参数保留，不能代替接口权限白名单。 */
     values: Record<string, string>;
     /** JSON Schema 对应的规范值：number 参数转换为有限数字。 */
-    typedValues: Record<string, string | number>;
+    typedValues: Record<string, ReportParamTypedValue>;
     issues: ReportParamIssue[];
 }
 
@@ -1632,9 +1878,80 @@ export declare class ReportParamValidationError extends Error {
     constructor(issues: readonly ReportParamIssue[]);
 }
 
+export declare interface ReportPlanDataOptions extends ReportDataLimits {
+    sourceScope?: string;
+    datasetId: string;
+    fields: readonly string[];
+}
+
+export declare type ReportPredicate = ReportComparison | {
+    all: readonly ReportPredicate[];
+} | {
+    any: readonly ReportPredicate[];
+} | {
+    not: ReportPredicate;
+};
+
+export declare function reportPredicateFields(predicate: ReportPredicate): string[];
+
+export declare type ReportPredicateOperand = {
+    field: string;
+} | {
+    value: ReportPredicateScalar;
+};
+
+export declare type ReportPredicateReader = (row: Readonly<Record<string, unknown>>) => boolean;
+
+export declare type ReportPredicateScalar = string | number | boolean | null;
+
+export declare interface ReportPrefillField {
+    field: string;
+    sourceField?: string;
+    label?: string;
+}
+
+/** Re-resolve coordinates after reflow; any changed value/token rejects the complete application. */
+export declare function reportPrefillInputs(plan: RenderPlan, preview: ReportPrefillPreview, canEdit?: (context: ReportCellContext) => boolean): ReportCellInput[];
+
+export declare interface ReportPrefillItem {
+    source: Readonly<ReportCellSource>;
+    label: string;
+    status: ReportPrefillStatus;
+    reason?: ReportPrefillReason;
+    before?: ReportCellValue;
+    after?: ReportCellValue;
+}
+
+export declare interface ReportPrefillOptions extends ReportDataLimits {
+    sourceScope?: string;
+    datasetId: string;
+    fields: readonly ReportPrefillField[];
+    rows: readonly ReportDataRecord[];
+    /** Default: fill only null/empty string. Existing zero, false and whitespace are data. */
+    mode?: "empty" | "replace";
+    maxChanges?: number;
+    canEdit?(context: ReportCellContext): boolean;
+}
+
+export declare interface ReportPrefillPreview {
+    sourceScope?: string;
+    datasetId: string;
+    items: readonly ReportPrefillItem[];
+    counts: Readonly<Record<ReportPrefillStatus, number>>;
+    /** Optimistic source tokens and previous values are retained for an atomic edit. */
+    edits: readonly ReportCellEdit[];
+}
+
+export declare type ReportPrefillReason = "unchanged" | "readonly" | "occupied" | "missing-source" | "missing-target" | "ambiguous" | "invalid";
+
+export declare type ReportPrefillStatus = "matched" | "changed" | "skipped" | "conflict";
+
 export declare interface ReportPreparedEdit {
     /** Calculated preview; no source/session state changes until commit succeeds. */
     readonly plan: RenderPlan;
+    readonly validationIssues: readonly ReportValidationIssue[];
+    /** Validate complete candidate source rows and derived fields before invoking persistence. */
+    validate(options: ReportCandidateValidationOptions): readonly ReportValidationIssue[];
     /** Call after persistence. A stale or repeated commit fails instead of publishing mixed state. */
     commit(result?: void | ReportEditResult): RenderPlan;
 }
@@ -1982,6 +2299,36 @@ export declare interface ReportTemplateVersion {
     restoredFrom?: string;
 }
 
+export declare class ReportValidationError extends Error {
+    readonly issues: readonly ReportValidationIssue[];
+    constructor(issues: readonly ReportValidationIssue[]);
+}
+
+export declare interface ReportValidationIssue {
+    ruleId: string;
+    rowKey?: string | number;
+    rowIndex?: number;
+    field?: string;
+    dataset?: string;
+    sourceScope?: string;
+    severity: "error" | "warning";
+    message: string;
+}
+
+export declare interface ReportValidationRule {
+    id: string;
+    /** Optional target; omitted applies to each candidate dataset. */
+    dataset?: string;
+    assert: ReportPredicate;
+    when?: ReportPredicate;
+    field?: string;
+    severity?: "error" | "warning";
+    message: string;
+    scope?: "row" | "dataset";
+    /** Dataset-scope assertions read this explicit summary row, never an arbitrary detail row. */
+    aggregates?: readonly AggregateDefinition[];
+}
+
 /** Optional business explanations never replace raw data or schema validation. */
 export declare type ReportValueState = "missing-source" | "not-applicable" | "not-calculable";
 
@@ -2093,13 +2440,7 @@ export declare function serializeReportTemplate(document: ReportTemplateDocument
 
 /** 条件格式规则求值（声明式，见 ListColumn.rules） */
 export 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>;
 }
@@ -2323,6 +2664,11 @@ export declare function validateRenderPlan(input: unknown): ValidationResult;
 /** Check configuration before opening an input, including JSON/JavaScript callers. */
 export declare function validateReportCellFieldDefinition(context: ReportCellContext, field: ReportCellFieldOptions): void;
 
+export declare function validateReportChartBinding(binding: ReportChartBinding): void;
+
+/** Pure candidate validation shared by browsers and Node; checks the complete proposed dataset before persistence. */
+export declare function validateReportDataset(input: readonly Record<string, unknown>[], options: ReportDatasetValidationOptions): ReportValidationIssue[];
+
 export declare function validateReportDrillActions(actions: readonly ReportDrillAction[]): void;
 
 /** 模板参数配置错误也统一返回结构化问题，不让无效默认值或边界静默进入后端。 */