react-semaphor 0.1.368 → 0.1.370

package/dist/types/dashboard-authoring.d.ts

@@ -1828,7 +1828,7 @@ declare type SemaphorAnalyticsFilterBase = {
 
 declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
 
-declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
+declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent | SemaphorMatrixIntent;
 
 declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
     operator: SemaphorAnalyticsNullFilterOperator;
@@ -1871,6 +1871,14 @@ declare type SemaphorDashboardViewIntent = {
 
 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;
@@ -1882,6 +1890,9 @@ declare type SemaphorFieldRef = {
 
 declare type SemaphorInputBinding = {
     inputId: string;
+    kind?: 'filter' | 'control';
+    controlRole?: 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+    operator?: SemaphorInputOperator;
     field?: SemaphorFieldRef;
 };
 
@@ -1925,6 +1936,149 @@ declare type SemaphorInputSpec = {
     scope?: SemaphorInputScope;
 };
 
+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;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
 declare type SemaphorMetricAnalysis = {
     kind: 'period_change';
     orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
@@ -1958,6 +2112,11 @@ declare type SemaphorMetricIntent = {
     limit?: number;
 };
 
+declare type SemaphorPaginationRequest = {
+    page: number;
+    pageSize: number;
+};
+
 declare type SemaphorProtocolVersion = 1;
 
 declare type SemaphorRecordsIntent = {
@@ -1972,6 +2131,7 @@ declare type SemaphorRecordsIntent = {
     timeWindow?: SemaphorTimeWindow;
     filters?: SemaphorAnalyticsFilter[];
     limit?: number;
+    pagination?: SemaphorPaginationRequest;
     orderBy?: {
         field: SemaphorFieldRef;
         direction: 'asc' | 'desc';
@@ -1987,6 +2147,10 @@ declare type SemaphorRelativeTimeWindow = {
     completeness?: 'include_partial' | 'complete_periods';
 };
 
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -2019,9 +2183,10 @@ declare type SemaphorSqlIntent = {
         kind: 'sql';
     }>;
     sql: string;
-    parameters?: Record<string, unknown>;
+    defaultParameters?: Record<string, unknown>;
     pythonCode?: string;
     limit?: number;
+    pagination?: SemaphorPaginationRequest;
     rationale?: string;
     fields?: SemaphorFieldRef[];
     inputs?: SemaphorInputBinding[];
@@ -2041,6 +2206,9 @@ declare type SemaphorViewPresentation = {
 } | {
     kind: 'table';
     columns?: string[];
+} | {
+    kind: 'matrixTable';
+    mode?: 'auto' | 'pivot' | 'hierarchical';
 } | {
     kind: 'text';
 };

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

@@ -564,7 +564,7 @@ declare type SemaphorAnalyticsFilterBase = {
 
 declare type SemaphorAnalyticsFilterOperator = SemaphorInputOperator | 'not_contains' | 'is_null' | 'is_not_null';
 
-declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
+declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent | SemaphorMatrixIntent;
 
 declare type SemaphorAnalyticsNullFilter = SemaphorAnalyticsFilterBase & {
     operator: SemaphorAnalyticsNullFilterOperator;
@@ -582,6 +582,14 @@ declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFil
 
 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;
@@ -593,6 +601,9 @@ declare type SemaphorFieldRef = {
 
 declare type SemaphorInputBinding = {
     inputId: string;
+    kind?: 'filter' | 'control';
+    controlRole?: 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+    operator?: SemaphorInputOperator;
     field?: SemaphorFieldRef;
 };
 
@@ -609,6 +620,149 @@ declare type SemaphorInputOptionsIntent = {
     limit?: number;
 };
 
+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;
+    totalBehavior?: SemaphorMatrixTotalCalculation;
+};
+
 declare type SemaphorMetricAnalysis = {
     kind: 'period_change';
     orderBy?: 'absolute_change' | 'positive_change' | 'negative_change' | 'period';
@@ -642,6 +796,11 @@ declare type SemaphorMetricIntent = {
     limit?: number;
 };
 
+declare type SemaphorPaginationRequest = {
+    page: number;
+    pageSize: number;
+};
+
 declare type SemaphorProtocolVersion = 1;
 
 declare type SemaphorRecordsIntent = {
@@ -656,6 +815,7 @@ declare type SemaphorRecordsIntent = {
     timeWindow?: SemaphorTimeWindow;
     filters?: SemaphorAnalyticsFilter[];
     limit?: number;
+    pagination?: SemaphorPaginationRequest;
     orderBy?: {
         field: SemaphorFieldRef;
         direction: 'asc' | 'desc';
@@ -671,6 +831,10 @@ declare type SemaphorRelativeTimeWindow = {
     completeness?: 'include_partial' | 'complete_periods';
 };
 
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -703,9 +867,10 @@ declare type SemaphorSqlIntent = {
         kind: 'sql';
     }>;
     sql: string;
-    parameters?: Record<string, unknown>;
+    defaultParameters?: Record<string, unknown>;
     pythonCode?: string;
     limit?: number;
+    pagination?: SemaphorPaginationRequest;
     rationale?: string;
     fields?: SemaphorFieldRef[];
     inputs?: SemaphorInputBinding[];