react-semaphor 0.1.372 → 0.1.374

package/dist/types/dashboard.d.ts

@@ -205,6 +205,28 @@ declare interface CalculatedFieldFormula {
 declare type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
 
 declare interface CardConfig {
+    /**
+     * Matrix table is the shared analytics-spine successor for pivot and
+     * hierarchical aggregate tables. Dashboard cards store the public matrix
+     * intent shape so Data Apps, MCP, and dashboard runtime consume one contract.
+     */
+    matrixIntent?: SemaphorMatrixIntent;
+    /**
+     * Deprecated compatibility fields for older matrix table drafts. New
+     * dashboard-authored matrix cards should use `matrixIntent` so normal
+     * `filters` can remain the explorer/card-level `FilterGroup`.
+     */
+    version?: SemaphorMatrixIntent['version'];
+    source?: SemaphorMatrixIntent['source'];
+    rows?: SemaphorMatrixIntent['rows'];
+    columns?: SemaphorMatrixIntent['columns'];
+    values?: SemaphorMatrixIntent['values'];
+    inputs?: SemaphorMatrixIntent['inputs'];
+    totals?: SemaphorMatrixIntent['totals'];
+    sort?: SemaphorMatrixIntent['sort'];
+    expansion?: SemaphorMatrixIntent['expansion'];
+    layout?: SemaphorMatrixIntent['layout'];
+    displayLimits?: SemaphorMatrixIntent['displayLimits'];
     groupByColumns?: GroupByField[];
     metricColumns?: MetricField[];
     pivotByColumns?: PivotByField[];
@@ -1924,6 +1946,37 @@ declare type SemanticExecutionPayload = {
 
 declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
 
+declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
+
+declare type SemaphorAnalyticsFilterBase = {
+    id?: string;
+    field: SemaphorFieldRef;
+    /**
+     * Controls where the filter is applied in an aggregate query.
+     *
+     * `row` means pre-aggregation filtering (`WHERE`).
+     * `aggregate` means post-aggregation filtering (`HAVING`) and is valid only
+     * for measure fields the execution engine can aggregate safely.
+     */
+    scope?: 'row' | 'aggregate';
+};
+
+declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
+    operator: SemaphorAnalyticsNullFilterOperator;
+    values?: never;
+};
+
+declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
+
+declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
+    operator?: SemaphorAnalyticsValueFilterOperator;
+    values: unknown[];
+};
+
+declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
+
 declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
 
 declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
@@ -1944,7 +1997,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: unknown;
+    format?: SemaphorValueFormat;
     tags?: string[];
 };
 
@@ -1964,6 +2017,14 @@ declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id
 
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
+/**
+ * Explorer-backed table source. This is intentionally distinct from raw SQL:
+ * matrix planning needs stable source metadata, fields, and dialect context.
+ */
+declare type SemaphorExplorerSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'physical';
+}>;
+
 declare type SemaphorFieldRef = {
     name: string;
     label?: string;
@@ -1973,6 +2034,166 @@ declare type SemaphorFieldRef = {
     aggregate?: SemaphorAggregateFunction;
 };
 
+declare type SemaphorInputBinding = {
+    inputId: string;
+    kind?: 'filter' | 'control';
+    controlRole?: 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+    operator?: SemaphorInputOperator;
+    field?: SemaphorFieldRef;
+};
+
+declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'not_contains' | 'between' | 'not_between' | '>' | '>=' | '<' | '<=';
+
+declare type SemaphorMatrixAxisExpansionOptions = {
+    defaultDepth?: number;
+    lazy?: boolean;
+    expandedPaths?: SemaphorMatrixMemberPathSegment[][];
+};
+
+declare type SemaphorMatrixAxisLevel = {
+    id?: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    label?: string;
+    subtotal?: boolean | SemaphorMatrixSubtotalOptions;
+    sortBy?: SemaphorMatrixAxisSortRule;
+};
+
+declare type SemaphorMatrixAxisSortRule = {
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+declare type SemaphorMatrixDisplayLimitOptions = {
+    rows?: SemaphorMatrixDisplayLimitRule;
+    columns?: SemaphorMatrixDisplayLimitRule;
+};
+
+declare type SemaphorMatrixDisplayLimitRule = {
+    limit: number;
+    by?: 'label' | 'value';
+    direction?: 'top' | 'bottom';
+    others?: boolean | {
+        label?: string;
+    };
+};
+
+declare type SemaphorMatrixExpansionOptions = {
+    rows?: SemaphorMatrixAxisExpansionOptions;
+    columns?: SemaphorMatrixAxisExpansionOptions;
+};
+
+declare type SemaphorMatrixIntent = {
+    kind: 'matrix';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorMatrixSourceRef;
+    rows: SemaphorMatrixAxisLevel[];
+    columns?: SemaphorMatrixAxisLevel[];
+    values: SemaphorMatrixValueField[];
+    filters?: SemaphorAnalyticsFilter[];
+    inputs?: SemaphorInputBinding[];
+    totals?: SemaphorMatrixTotalOptions;
+    sort?: SemaphorMatrixSortRule[];
+    expansion?: SemaphorMatrixExpansionOptions;
+    layout?: SemaphorMatrixLayoutOptions;
+    displayLimits?: SemaphorMatrixDisplayLimitOptions;
+};
+
+declare type SemaphorMatrixLayoutOptions = {
+    hierarchy?: 'compact' | 'tabular' | 'outline';
+    valuesPlacement?: 'columns' | 'rows';
+    stickyRowHeaders?: boolean;
+    stickyColumnHeaders?: boolean;
+};
+
+declare type SemaphorMatrixMemberPathSegment = {
+    levelId: string;
+    value: unknown;
+};
+
+declare type SemaphorMatrixSortRule = {
+    axis: 'row' | 'column';
+    targetId?: string;
+    direction: 'asc' | 'desc';
+    by: {
+        kind: 'label';
+    } | {
+        kind: 'field';
+        field: SemaphorFieldRef;
+        aggregate?: SemaphorAggregateFunction;
+    } | {
+        kind: 'value';
+        valueId: string;
+        rowPath?: SemaphorMatrixMemberPathSegment[];
+        columnPath?: SemaphorMatrixMemberPathSegment[];
+    };
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+};
+
+declare type SemaphorMatrixSourceRef = SemaphorSemanticSourceRef | SemaphorExplorerSourceRef;
+
+declare type SemaphorMatrixSubtotalOptions = {
+    enabled?: boolean;
+    position?: 'before' | 'after';
+    label?: string;
+};
+
+declare type SemaphorMatrixTotalCalculation = {
+    kind: 'defaultAggregate';
+} | {
+    kind: 'blank';
+} | {
+    kind: 'labelOnly';
+    label?: string;
+} | {
+    kind: 'customAggregate';
+    aggregate: SemaphorAggregateFunction;
+} | {
+    kind: 'percentOfParent';
+} | {
+    kind: 'percentOfGrandTotal';
+} | {
+    kind: 'customExpression';
+    expressionId: string;
+};
+
+declare type SemaphorMatrixTotalOptions = {
+    rows?: boolean | 'perLevel';
+    columns?: boolean | 'perLevel';
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+    rowPosition?: 'top' | 'bottom';
+    columnPosition?: 'left' | 'right';
+};
+
+declare type SemaphorMatrixValueField = {
+    id?: string;
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+    label?: string;
+    format?: SemaphorValueFormat;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
+declare type SemaphorProtocolVersion = 1;
+
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -1996,6 +2217,46 @@ declare type SemaphorSourceRef = {
     label?: string;
 };
 
+declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+declare type SemaphorValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';
@@ -2549,7 +2810,7 @@ export declare type TChartOptions = {
     treemapColorMode?: 'branch' | 'category';
 };
 
-declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'detailTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
+declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'matrixTable' | 'detailTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
 
 export declare type TColumnSetting<T extends DisplayDataType> = {
     columnIdx: number;

package/dist/types/data-app-builder.d.ts

@@ -600,7 +600,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: unknown;
+    format?: SemaphorValueFormat;
     tags?: string[];
 };
 
@@ -799,6 +799,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
+    format?: SemaphorValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -921,6 +922,44 @@ declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' |
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
+declare type SemaphorValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 export declare type WorkspaceContext = {
     projectRoot?: string;
     framework?: string;

package/dist/types/data-app-sdk-validation.d.ts

@@ -36,44 +36,27 @@ declare type MatrixAxisLevelDescriptor = {
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
-declare type MatrixAxisPayload = {
+declare type MatrixAxisResultPayload = {
     id: 'rows' | 'columns';
     levels: MatrixAxisLevelDescriptor[];
-    nodes: MatrixNode[];
+    nodeIds: string[];
 };
 
-declare type MatrixCapability = 'rowHierarchy' | 'columnHierarchy' | 'rowSubtotals' | 'columnSubtotals' | 'grandTotals' | 'lazyRows' | 'lazyColumns' | 'conditionalFormatting' | 'visualExport' | (string & {});
-
-declare type MatrixCell = {
+declare type MatrixCalculationDescriptor = {
     id: string;
-    rowNodeId: string;
-    columnNodeId?: string;
-    measureInstanceId: string;
-    rowPath: MatrixMemberPathSegment[];
-    columnPath: MatrixMemberPathSegment[];
-    rawValue: unknown;
-    presence: MatrixCellPresence;
-    formattedValue?: string;
-    role: MatrixCellRole;
-    aggregateFunction?: SemaphorAggregateFunction;
-    formattingScope: MatrixCellFormattingScope;
-    actions?: MatrixCellAction[];
-};
-
-declare type MatrixCellAction = {
-    kind: 'requestSubgoal' | 'filter' | 'copyValue' | 'explainCalculation' | 'inspectContributingRows' | 'drillThrough' | (string & {});
+    measureId: string;
+    aggregate?: SemaphorAggregateFunction;
     label?: string;
-    payload?: Record<string, unknown>;
+    source: 'measureDefault' | 'rowSubtotal' | 'columnSubtotal' | 'subtotalIntersection' | 'rowGrandTotal' | 'columnGrandTotal' | 'matrixGrandTotal' | 'custom';
+    scope?: {
+        rowLevelId?: string;
+        columnLevelId?: string;
+        rowNodeId?: string;
+        columnNodeId?: string;
+    };
 };
 
-declare type MatrixCellFormattingScope = {
-    rowNodeId: string;
-    columnNodeId?: string;
-    measureInstanceId: string;
-    role: MatrixCellRole;
-    rowPath: MatrixMemberPathSegment[];
-    columnPath: MatrixMemberPathSegment[];
-};
+declare type MatrixCapability = 'rowHierarchy' | 'columnHierarchy' | 'rowSubtotals' | 'columnSubtotals' | 'grandTotals' | 'lazyRows' | 'lazyColumns' | 'conditionalFormatting' | 'visualExport' | (string & {});
 
 declare type MatrixCellPresence = 'present' | 'presentNull' | 'missing' | 'densified';
 
@@ -114,10 +97,6 @@ declare type MatrixFieldDescriptor = {
     label?: string;
 };
 
-declare type MatrixFieldDirectory = {
-    fieldsByInstanceId: Record<string, MatrixFieldDescriptor>;
-};
-
 declare type MatrixFormattingContext = {
     domains?: Record<string, {
         min?: number;
@@ -126,19 +105,6 @@ declare type MatrixFormattingContext = {
     rules?: Array<Record<string, unknown>>;
 };
 
-declare type MatrixGridCell = {
-    id: string;
-    columnId: string;
-    cellId?: string;
-    rawValue: unknown;
-    formattedValue?: string;
-    presence: MatrixCellPresence;
-    role: MatrixCellRole;
-    measureInstanceId: string;
-    rowPath: MatrixMemberPathSegment[];
-    columnPath: MatrixMemberPathSegment[];
-};
-
 declare type MatrixGridColumn = {
     id: string;
     label: string;
@@ -163,42 +129,32 @@ declare type MatrixGridHeaderRow = {
     cells: MatrixGridHeaderCell[];
 };
 
-declare type MatrixGridProjection = {
-    schemaVersion: 1;
-    shape: MatrixShape;
-    rowHeaderLevels: MatrixGridRowHeaderLevel[];
-    columnHeaderRows: MatrixGridHeaderRow[];
-    columns: MatrixGridColumn[];
-    rows: MatrixGridRow[];
-};
-
-declare type MatrixGridRow = {
-    id: string;
-    rowNodeId: string;
-    rowPath: MatrixMemberPathSegment[];
-    depth: number;
-    label: string;
-    role: 'value' | 'rowSubtotal' | 'rowGrandTotal';
-    isExpanded?: boolean;
-    hasChildren?: boolean;
-    cells: MatrixGridCell[];
-};
-
 declare type MatrixGridRowHeaderLevel = {
     id: string;
     label: string;
     fieldInstanceId: string;
 };
 
+declare type MatrixLayoutProjection = {
+    rowHeaderLevels: MatrixGridRowHeaderLevel[];
+    columnHeaderRows: MatrixGridHeaderRow[];
+    columns: MatrixGridColumn[];
+};
+
 declare type MatrixMeasureDescriptor = {
     instanceId: string;
     fieldKey: string;
     label: string;
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
+    format?: SemaphorValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
+declare type MatrixMeasureResultDescriptor = MatrixMeasureDescriptor & {
+    semantics: MatrixMeasureSemantics;
+};
+
 declare type MatrixMeasureSemantics = {
     kind: 'additive';
     aggregate?: SemaphorAggregateFunction;
@@ -257,29 +213,6 @@ declare type MatrixPageInfo = {
     hasMoreColumns?: boolean;
 };
 
-declare type MatrixPayload = {
-    kind: 'matrixPayload';
-    schemaVersion: 1;
-    shape: MatrixShape;
-    capabilities: MatrixCapability[];
-    executionMetadata: MatrixExecutionMetadata;
-    axes: {
-        rows: MatrixAxisPayload;
-        columns: MatrixAxisPayload;
-    };
-    measures: MatrixMeasureDescriptor[];
-    measureSemantics: Record<string, MatrixMeasureSemantics>;
-    fieldDirectory: MatrixFieldDirectory;
-    rowNodes: MatrixNode[];
-    columnNodes: MatrixNode[];
-    cells: MatrixCell[];
-    totals: MatrixTotals;
-    sort: MatrixResolvedSort[];
-    formattingContext: MatrixFormattingContext;
-    pageInfo?: MatrixPageInfo;
-    warnings?: MatrixWarning[];
-};
-
 declare type MatrixQueryStrategy = 'tall' | 'wide' | 'lazy' | 'export';
 
 declare type MatrixResolvedSort = {
@@ -292,6 +225,17 @@ declare type MatrixResolvedSort = {
     by: SemaphorMatrixSortRule['by'];
 };
 
+declare type MatrixResultCell = {
+    rowId: string;
+    columnId?: string;
+    measureId: string;
+    value: unknown;
+    formattedValue?: string;
+    presence: MatrixCellPresence;
+    role: MatrixCellRole;
+    calculationId?: string;
+};
+
 declare type MatrixShape = 'hierarchical' | 'pivot';
 
 declare type MatrixTotals = {
@@ -303,13 +247,6 @@ declare type MatrixTotals = {
     };
 };
 
-declare type MatrixWarning = {
-    code: string;
-    message: string;
-    path?: string;
-    severity?: 'info' | 'warning' | 'error';
-};
-
 export declare function normalizeSemaphorAnalysisQueryOptions(value: unknown, options?: {
     pathPrefix?: string;
     validateTimezone?: SemaphorAnalysisTimezoneValidator;
@@ -567,7 +504,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: unknown;
+    format?: SemaphorValueFormat;
     tags?: string[];
 };
 
@@ -801,9 +738,25 @@ declare type SemaphorMatrixQuerySpec = Omit<SemaphorMatrixIntent, 'kind' | 'vers
 
 declare type SemaphorMatrixResult = SemaphorAnalyticsResultBase & {
     kind: 'matrix';
-    intent: SemaphorMatrixIntent;
-    payload: MatrixPayload;
-    grid: MatrixGridProjection;
+    schemaVersion: 1;
+    intent?: SemaphorMatrixIntent;
+    shape: MatrixShape;
+    capabilities: MatrixCapability[];
+    executionMetadata: MatrixExecutionMetadata;
+    fieldsById: Record<string, MatrixFieldDescriptor>;
+    measuresById: Record<string, MatrixMeasureResultDescriptor>;
+    calculationsById?: Record<string, MatrixCalculationDescriptor>;
+    axes: {
+        rows: MatrixAxisResultPayload;
+        columns: MatrixAxisResultPayload;
+    };
+    nodesById: Record<string, MatrixNode>;
+    layout: MatrixLayoutProjection;
+    cells: MatrixResultCell[];
+    totals: MatrixTotals;
+    sort: MatrixResolvedSort[];
+    formattingContext: MatrixFormattingContext;
+    pageInfo?: MatrixPageInfo;
     expansion?: MatrixExpansionResponseHints;
 };
 
@@ -870,6 +823,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
+    format?: SemaphorValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -1179,6 +1133,44 @@ declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' |
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
+declare type SemaphorValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    locale?: string;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 export declare function validateSemaphorDataAppQuerySpecs(input: {
     queries: SemaphorDataAppQuerySpecEnvelope[];
     fieldCatalogs?: SemaphorDataAppFieldCatalog[];