react-semaphor 0.1.372 → 0.1.373

package/dist/types/main.d.ts

@@ -1180,6 +1180,28 @@ export declare function cancelExport(apiServiceUrl: string, token: string, expor
 export declare type CanonicalFormatSpec = NumericCanonicalFormat | DateCanonicalFormat | DurationCanonicalFormat | StringCanonicalFormat;
 
 export 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[];
@@ -3875,6 +3897,369 @@ declare type ManagementStore = {
     actions: Actions;
 };
 
+declare type MatrixAxisLevelDescriptor = {
+    instanceId: string;
+    fieldKey: string;
+    label: string;
+    field: SemaphorFieldRef;
+    grain?: SemaphorTimeGrain;
+    subtotal?: SemaphorMatrixSubtotalOptions;
+};
+
+declare type MatrixAxisPayload = {
+    id: 'rows' | 'columns';
+    levels: MatrixAxisLevelDescriptor[];
+    nodes: MatrixNode[];
+};
+
+declare type MatrixAxisResultPayload = {
+    id: 'rows' | 'columns';
+    levels: MatrixAxisLevelDescriptor[];
+    nodeIds: string[];
+};
+
+declare type MatrixBulkColumnExpansionStateUpdate = {
+    state: MatrixExpansionState;
+    kind: 'bulkColumns';
+    isExpanded: boolean;
+};
+
+declare type MatrixBulkRowExpansionStateUpdate = {
+    state: MatrixExpansionState;
+    kind: 'bulkRows';
+    isExpanded: boolean;
+};
+
+declare type MatrixCalculationDescriptor = {
+    id: string;
+    measureId: string;
+    aggregate?: SemaphorAggregateFunction;
+    label?: string;
+    source: 'measureDefault' | 'rowSubtotal' | 'columnSubtotal' | 'subtotalIntersection' | 'rowGrandTotal' | 'columnGrandTotal' | 'matrixGrandTotal' | 'custom';
+    scope?: {
+        rowLevelId?: string;
+        columnLevelId?: string;
+        rowNodeId?: string;
+        columnNodeId?: string;
+    };
+};
+
+declare type MatrixCapability = 'rowHierarchy' | 'columnHierarchy' | 'rowSubtotals' | 'columnSubtotals' | 'grandTotals' | 'lazyRows' | 'lazyColumns' | 'conditionalFormatting' | 'visualExport' | (string & {});
+
+declare type MatrixCell = {
+    id: string;
+    rowNodeId: string;
+    columnNodeId?: string;
+    measureInstanceId: string;
+    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 & {});
+    label?: string;
+    payload?: Record<string, unknown>;
+};
+
+declare type MatrixCellFormattingScope = {
+    rowNodeId: string;
+    columnNodeId?: string;
+    measureInstanceId: string;
+    role: MatrixCellRole;
+};
+
+declare type MatrixCellPresence = 'present' | 'presentNull' | 'missing' | 'densified';
+
+declare type MatrixCellRole = 'value' | 'rowSubtotal' | 'columnSubtotal' | 'subtotalIntersection' | 'rowGrandTotal' | 'columnGrandTotal' | 'matrixGrandTotal';
+
+declare type MatrixColumnExpansionStateUpdate = {
+    state: MatrixExpansionState;
+    columnPath: MatrixMemberPathSegment[];
+    isExpanded: boolean;
+};
+
+declare type MatrixExecutionMetadata = {
+    strategy?: MatrixQueryStrategy;
+    dialect?: SemaphorDialect;
+    rowNodeCount?: number;
+    columnNodeCount?: number;
+    cellCount?: number;
+    groupingSetCount?: number;
+    queryDurationMs?: number;
+    budgetRejected?: boolean;
+    cacheStatus?: 'hit' | 'miss' | 'bypass';
+    [key: string]: unknown;
+};
+
+declare type MatrixExpansionRequest = {
+    axis: 'row' | 'column';
+    path: MatrixMemberPathSegment[];
+    depth?: number;
+};
+
+declare type MatrixExpansionResponseHints = {
+    rowLazyLoading?: boolean;
+    columnLazyLoading?: boolean;
+    expandableRowNodeIds?: string[];
+    expandableColumnNodeIds?: string[];
+    nextRequests?: MatrixExpansionRequest[];
+};
+
+declare type MatrixExpansionState = {
+    schemaVersion: 1;
+    expandedRowPaths: MatrixMemberPathSegment[][];
+    expandedColumnPaths: MatrixMemberPathSegment[][];
+};
+
+declare type MatrixExpansionStateUpdate = {
+    state: MatrixExpansionState;
+    rowPath: MatrixMemberPathSegment[];
+    isExpanded: boolean;
+};
+
+declare type MatrixFieldDescriptor = {
+    instanceId: string;
+    fieldKey: string;
+    field: SemaphorFieldRef;
+    role: 'row' | 'column' | 'measure' | 'sort' | 'filter';
+    label?: string;
+};
+
+declare type MatrixFieldDirectory = {
+    fieldsByInstanceId: Record<string, MatrixFieldDescriptor>;
+};
+
+declare type MatrixFormattingContext = {
+    domains?: Record<string, {
+        min?: number;
+        max?: number;
+    }>;
+    rules?: Array<Record<string, unknown>>;
+};
+
+declare type MatrixGridCell = {
+    id: string;
+    columnId: string;
+    cellId?: string;
+    rawValue: unknown;
+    formattedValue?: string;
+    presence: MatrixCellPresence;
+    role: MatrixCellRole;
+    measureInstanceId: string;
+};
+
+declare type MatrixGridColumn = {
+    id: string;
+    label: string;
+    columnNodeId?: string;
+    columnPath: MatrixMemberPathSegment[];
+    measureInstanceId: string;
+    role: 'value' | 'columnSubtotal' | 'columnGrandTotal';
+};
+
+declare type MatrixGridHeaderCell = {
+    id: string;
+    label: string;
+    role: 'rowHeader' | 'columnHeader' | 'measureHeader' | 'subtotal' | 'grandTotal';
+    colSpan: number;
+    rowSpan: number;
+    columnPath: MatrixMemberPathSegment[];
+    measureInstanceId?: string;
+};
+
+declare type MatrixGridHeaderRow = {
+    id: string;
+    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;
+} | {
+    kind: 'semiAdditive';
+    aggregate?: SemaphorAggregateFunction;
+    grain?: SemaphorTimeGrain;
+} | {
+    kind: 'nonAdditive';
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'ratio';
+    numeratorMeasureInstanceId?: string;
+    denominatorMeasureInstanceId?: string;
+} | {
+    kind: 'custom';
+    expressionId?: string;
+};
+
+declare type MatrixMemberPathSegment = {
+    instanceId: string;
+    fieldKey: string;
+    value: unknown;
+    label: string;
+};
+
+declare type MatrixNode = {
+    id: string;
+    axis: 'row' | 'column';
+    path: MatrixMemberPathSegment[];
+    level: number;
+    label: string;
+    value: unknown;
+    parentId?: string;
+    hasChildren: boolean;
+    isExpanded?: boolean;
+    isSubtotal?: boolean;
+    isGrandTotal?: boolean;
+    subtotalFunction?: SemaphorAggregateFunction;
+    childCount?: number;
+    actions?: MatrixNodeAction[];
+};
+
+declare type MatrixNodeAction = {
+    kind: 'expand' | 'collapse' | 'requestSubgoal' | 'filter' | 'drillThrough' | 'openRelatedRecords' | (string & {});
+    label?: string;
+    payload?: Record<string, unknown>;
+};
+
+declare type MatrixPageInfo = {
+    rowOffset?: number;
+    rowLimit?: number;
+    columnOffset?: number;
+    columnLimit?: number;
+    hasMoreRows?: boolean;
+    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 = {
+    id: string;
+    axis: 'row' | 'column';
+    targetInstanceId?: string;
+    direction: 'asc' | 'desc';
+    nulls?: 'warehouseDefault' | 'first' | 'last';
+    scope?: 'global' | 'withinParent';
+    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';
+
+export declare function MatrixTableVisual({ result, grid, payload, isLoading, expansionState, onExpansionChange, loadingRowPathKeys, onSortChange, onLoadMoreRows, }: MatrixTableVisualProps): JSX.Element;
+
+export declare type MatrixTableVisualProps = {
+    result?: SemaphorMatrixResult;
+    grid?: MatrixGridProjection;
+    payload?: MatrixPayload;
+    isLoading?: boolean;
+    expansionState?: MatrixExpansionState;
+    onExpansionChange?: (update: MatrixExpansionStateUpdate | MatrixColumnExpansionStateUpdate | MatrixBulkColumnExpansionStateUpdate | MatrixBulkRowExpansionStateUpdate) => void;
+    loadingRowPathKeys?: Set<string>;
+    onSortChange?: (sortRules: SemaphorMatrixSortRule[]) => void;
+    onLoadMoreRows?: (rowPath: MatrixMemberPathSegment[]) => void;
+};
+
+declare type MatrixTotals = {
+    rows?: boolean;
+    columns?: boolean;
+    grandTotal?: boolean | {
+        rows?: boolean;
+        columns?: boolean;
+    };
+};
+
+declare type MatrixWarning = {
+    code: string;
+    message: string;
+    path?: string;
+    severity?: 'info' | 'warning' | 'error';
+};
+
 export declare interface MetricColumn extends BaseColumn {
     role: 'metric';
     aggregate: AggregateFunction;
@@ -4178,6 +4563,7 @@ export declare interface QueryExecutionResponse {
     columnKeyMap?: QueryColumnKeyMap;
     tableTotalsByColumnId?: Record<string, string | number | null>;
     documentTableTotalsBaseSql?: string;
+    matrixResult?: SemaphorMatrixResult;
     metadata?: any;
 }
 
@@ -4444,6 +4830,16 @@ declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsNullFilterOperator = 'is_null' | 'is_not_null';
 
+declare type SemaphorAnalyticsResultBase = {
+    intentId?: string;
+    queryPath: SemaphorQueryPath;
+    warnings?: string[];
+    rowCount?: number;
+    rowLimitExceeded?: boolean;
+    limit?: number;
+    pagination?: SemaphorPaginationMetadata;
+};
+
 declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
     operator?: SemaphorAnalyticsValueFilterOperator;
     values: unknown[];
@@ -4476,7 +4872,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: unknown;
+    format?: SemaphorValueFormat;
     tags?: string[];
 };
 
@@ -4612,6 +5008,30 @@ declare type SemaphorMatrixMemberPathSegment = {
     value: unknown;
 };
 
+declare type SemaphorMatrixResult = SemaphorAnalyticsResultBase & {
+    kind: 'matrix';
+    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;
+};
+
 declare type SemaphorMatrixSortRule = {
     axis: 'row' | 'column';
     targetId?: string;
@@ -4675,6 +5095,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
+    format?: SemaphorValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -4712,6 +5133,15 @@ declare type SemaphorMetricIntent = {
     derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
+declare type SemaphorPaginationMetadata = {
+    page: number;
+    pageSize: number;
+    pageCount: number;
+    totalCount: number;
+    hasNextPage: boolean;
+    hasPrevPage: boolean;
+};
+
 declare type SemaphorPaginationRequest = {
     page: number;
     pageSize: number;
@@ -4725,6 +5155,8 @@ declare function SemaphorQueryClient({ children, }: {
 export { SemaphorQueryClient as SemaphorDataProvider }
 export { SemaphorQueryClient }
 
+declare type SemaphorQueryPath = 'query_spec' | 'sql' | 'sql_python';
+
 declare type SemaphorRecordsIntent = {
     kind: 'records';
     version?: SemaphorProtocolVersion;
@@ -4803,6 +5235,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;
+};
+
 /**
  * Stable serializer for dashboard dirty checks.
  * This consolidates normalization + serialization into one call site, so
@@ -5513,7 +5983,7 @@ export declare type TChartOptions = {
     treemapColorMode?: 'branch' | 'category';
 };
 
-export 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';
+export 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;
@@ -6373,6 +6843,7 @@ export declare function useCard(cardId: string): {
     handleDatapointClick: (chart: Chart_2, datasetIndex: number, clickIndex: number, value: number) => void;
     cfg: TChartConfiguration | undefined;
     queryKey: string[];
+    queryRequestPayload: Record<string, unknown> | undefined;
     pagination: PaginationMetadata | undefined;
     comparisonMetadata: ComparisonMetadataMap | undefined;
     resolvedPrimaryDateField: ResolvedPrimaryDateField | undefined;