react-semaphor 0.1.369 → 0.1.371

package/dist/types/main.d.ts

@@ -1083,8 +1083,14 @@ export declare const CALCULATED_FIELD_ENTITY_MARKER: "SEMAPHOR_CALCULATED_FIELD"
 
 /**
  * Formula metadata for calculated fields (UI-only metadata)
- * This is supplementary data to help the UI display and edit calculated fields.
- * The `expression` field remains the source of truth for the backend.
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
  *
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
@@ -3257,6 +3263,15 @@ export declare interface Field {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
@@ -4420,7 +4435,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;
@@ -4441,8 +4456,54 @@ export declare const SemaphorContextProvider: ({ children, dashboardProps, }: {
     dashboardProps: DashboardProps;
 }) => JSX.Element;
 
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 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;
@@ -4471,6 +4532,150 @@ declare type SemaphorInputOptionsIntent = {
     field: SemaphorFieldRef;
     search?: string;
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
+};
+
+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 = {
@@ -4504,6 +4709,7 @@ declare type SemaphorMetricIntent = {
     };
     inputs?: SemaphorInputBinding[];
     limit?: number;
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorPaginationRequest = {
@@ -4537,6 +4743,7 @@ declare type SemaphorRecordsIntent = {
         direction: 'asc' | 'desc';
     };
     inputs?: SemaphorInputBinding[];
+    derivedFields?: SemaphorDerivedFieldDefinition[];
 };
 
 declare type SemaphorRelativeTimeWindow = {
@@ -4547,6 +4754,10 @@ declare type SemaphorRelativeTimeWindow = {
     completeness?: 'include_partial' | 'complete_periods';
 };
 
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -5383,6 +5594,7 @@ export declare type TDataColumn = {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     sourceField?: string;
     aggregate?: AggregateFunction;

package/dist/types/shared.d.ts

@@ -73,8 +73,14 @@ declare type CacheConfig = {
 
 /**
  * Formula metadata for calculated fields (UI-only metadata)
- * This is supplementary data to help the UI display and edit calculated fields.
- * The `expression` field remains the source of truth for the backend.
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
  *
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
@@ -1047,6 +1053,15 @@ declare interface Field {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
@@ -1557,8 +1572,57 @@ declare type SelectedEntities = SelectedEntity[];
 
 declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
 
+declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
+declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;

package/dist/types/surfboard.d.ts

@@ -158,8 +158,14 @@ export declare type CacheConfig = {
 
 /**
  * Formula metadata for calculated fields (UI-only metadata)
- * This is supplementary data to help the UI display and edit calculated fields.
- * The `expression` field remains the source of truth for the backend.
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
  *
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
@@ -1298,6 +1304,15 @@ declare interface Field {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
@@ -1917,8 +1932,57 @@ declare type SemanticExecutionPayload = {
     }>;
 };
 
+declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
+declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -2578,6 +2642,7 @@ export declare type TDataColumn = {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     sourceField?: string;
     aggregate?: AggregateFunction;

package/dist/types/types.d.ts

@@ -571,8 +571,14 @@ export declare const CALCULATED_FIELD_ENTITY_MARKER: "SEMAPHOR_CALCULATED_FIELD"
 
 /**
  * Formula metadata for calculated fields (UI-only metadata)
- * This is supplementary data to help the UI display and edit calculated fields.
- * The `expression` field remains the source of truth for the backend.
+ * This is supplementary runtime/compiler data to help dashboard UI display,
+ * edit, and execute calculated fields.
+ *
+ * Public source-level calculation metadata belongs in `Field.derivedField`
+ * (`SemaphorDerivedFieldDefinition`). `calculatedFormula` deliberately uses
+ * indexed `{field_N}` tokens and full runtime Field objects so current dashboard
+ * query execution can resolve aliases, joins, filters, and aggregates without
+ * doing catalog lookups.
  *
  * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
  * Both are generated together from the same dialog inputs, preventing drift.
@@ -1846,6 +1852,15 @@ export declare interface Field {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    /**
+     * Public, source-level derived-field metadata for semantic/domain-authored
+     * calculations. This is the AI/MCP/Data App-facing contract: named-token
+     * expression, typed inputs, result role, and compute stage.
+     *
+     * Dashboard-local calculated fields may omit this because they are local
+     * runtime artifacts rather than semantic-domain definitions.
+     */
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
@@ -2677,8 +2692,57 @@ declare type SemanticExecutionPayload = {
     }>;
 };
 
+declare type SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
+
+declare type SemaphorDerivedFieldAggregationBehavior = 'additive' | 'non_additive' | 'ratio_of_sums' | 'weighted' | 'pre_aggregated' | 'snapshot';
+
+declare type SemaphorDerivedFieldAggregationStrategy = 'default' | 'symmetric_aggregate' | 'aggregate_then_join' | 'weighted';
+
+declare type SemaphorDerivedFieldComputeStage = 'row' | 'aggregate';
+
+declare type SemaphorDerivedFieldDefinition = {
+    kind: 'derived_field';
+    name: string;
+    label: string;
+    description?: string;
+    resultRole: SemaphorDerivedFieldResultRole;
+    dataType: NonNullable<SemaphorFieldRef['dataType']>;
+    computeStage: SemaphorDerivedFieldComputeStage;
+    expression: string;
+    expressionLanguage?: 'semaphor_sql_template';
+    inputs: Record<string, SemaphorDerivedFieldInput>;
+    defaultAggregate?: SemaphorAggregateFunction;
+    aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
+    aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
+    format?: unknown;
+    tags?: string[];
+};
+
+declare type SemaphorDerivedFieldInput = {
+    kind: 'field';
+    field: SemaphorFieldRef;
+    aggregate?: SemaphorAggregateFunction;
+} | {
+    kind: 'metric';
+    metric: SemaphorFieldRef;
+} | {
+    kind: 'dimension';
+    dimension: SemaphorFieldRef;
+};
+
+declare type SemaphorDerivedFieldResultRole = 'measure' | 'group' | 'date' | 'id' | 'filter';
+
 declare type SemaphorDialect = 'postgres' | 'mysql' | 'mssql' | 'snowflake' | 'clickhouse' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
 
+declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+    aggregate?: SemaphorAggregateFunction;
+};
+
 declare type SemaphorSourceRef = {
     kind: 'semantic';
     domainId: string;
@@ -3362,6 +3426,7 @@ export declare type TDataColumn = {
     role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
+    derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
     sourceField?: string;
     aggregate?: AggregateFunction;

package/package.json

@@ -5,7 +5,7 @@
     "email": "support@semaphor.cloud"
   },
   "license": "MIT",
-  "version": "0.1.369",
+  "version": "0.1.371",
   "description": "Fully interactive and customizable dashboards for your apps.",
   "keywords": [
     "react",

package/dist/chunks/validation-Dsf7PydY.js

@@ -1 +0,0 @@
-"use strict";const w=require("./validators-oc8qtP4q.js"),u=require("./source-identity-C-xaeE_I.js");function v(e){var t;const r=j(e);return{version:1,kind:"metric",id:e.id,label:e.label,source:S(e),metrics:r,primaryMetric:Q(e,r),dateField:e.dateField?a(e.dateField,"date"):void 0,timeGrain:e.timeGrain,dimensions:(t=e.dimensions)==null?void 0:t.map(o=>a(o,"dimension")),comparison:Z(e.comparison),orderBy:e.orderBy?{field:a(e.orderBy.field),direction:e.orderBy.direction}:void 0,inputs:p(e.inputs),limit:e.limit}}function M(e){var t;return{...v(e),...e.timeWindow?{timeWindow:e.timeWindow}:{},...(t=e.filters)!=null&&t.length?{filters:e.filters}:{},...e.analysis?{analysis:e.analysis}:{}}}function D(e){return{...e.chartTitle?{chartTitle:e.chartTitle}:{},...e.chartType?{chartType:e.chartType}:{},...e.driverMode?{driverMode:e.driverMode}:{},...e.includePopulation!==void 0?{includePopulation:e.includePopulation}:{},...e.calendarContext?{calendarContext:e.calendarContext}:{}}}function Q(e,r){if(!e.primaryMetric)return r[0]||{name:"",role:"measure"};const t=a(e.primaryMetric,"measure"),o=V(t,r),i=o.length===1?o[0]:void 0;return i?_(t,i):t}function j(e){const r=[];for(const t of e.metrics.map(o=>a(o,"measure"))){if(!t.name)continue;const o=r.findIndex(i=>K(i,t));if(o===-1){r.push(t);continue}r[o]=_(r[o],t)}return r}function K(e,r){return u.semaphorFieldRefsMatch(e,r)&&f(e)===f(r)}function E(e,r){return f(r)===f(e)}function N(e,r){return r.name!==e.name||e.source&&!u.semaphorFieldRefsMatch(r,e)?!1:E(e,r)}function V(e,r){const t=r.filter(o=>N(e,o));return e.aggregate!==void 0,t}function f(e){return(e.aggregate||"SUM").toUpperCase()}function _(e,r){if(e.aggregate&&r.aggregate&&e.aggregate!==r.aggregate)throw new Error(`Metric "${e.name}" was requested with conflicting aggregate semantics: ${e.aggregate} and ${r.aggregate}.`);return{...u.preferSemaphorFieldRefMetadata(e,r),aggregate:e.aggregate||r.aggregate}}function C(e){var t;if("sort"in e)throw new Error("semaphor.records supports orderBy for a single deterministic sort. Multiple sort clauses are not supported by the analytics protocol yet.");if(!Y(e))throw new Error("semaphor.records needs at least one field.");const r=W(e.fields);return{version:1,kind:"records",id:e.id,label:e.label,source:S(e),fields:r,dateField:e.dateField?a(e.dateField,"date"):void 0,timeGrain:e.timeGrain,...e.timeWindow?{timeWindow:e.timeWindow}:{},...(t=e.filters)!=null&&t.length?{filters:e.filters}:{},orderBy:e.orderBy?{field:a(e.orderBy.field),direction:e.orderBy.direction}:void 0,inputs:p(e.inputs),limit:e.limit,...e.pagination?{pagination:e.pagination}:{}}}function W(e){return e.map(r=>{const t=a(r);if(!t.role)throw new Error(`semaphor.records field "${t.name}" needs an explicit role.`);return t})}function R(e){return{version:1,kind:"inputOptions",id:e.id,label:e.label,source:S(e),field:a(e.field,"dimension"),search:e.search,limit:e.limit}}function $(e){var r;return{version:1,kind:"sql",id:e.id,label:e.label,source:e.source,sql:e.sql,...e.defaultParameters?{defaultParameters:e.defaultParameters}:{},...e.pythonCode?{pythonCode:e.pythonCode}:{},...(r=e.fields)!=null&&r.length?{fields:e.fields.map(t=>a(t))}:{},inputs:p(e.inputs),limit:e.limit,...e.pagination?{pagination:e.pagination}:{},rationale:e.rationale}}function T(e){if("toAnalyticsInput"in e){const n=e.toAnalyticsInput();return{inputId:n.inputId,kind:n.kind,...n.controlRole?{controlRole:n.controlRole}:{},...n.operator?{operator:n.operator}:{},...n.field?{field:n.field}:{}}}if("id"in e){const n=I(e);return{inputId:n.inputId,kind:n.kind,...n.controlRole?{controlRole:n.controlRole}:{},...n.operator?{operator:n.operator}:{},...n.field?{field:n.field}:{}}}const r="kind"in e?e.kind:void 0,t="operator"in e?F(e.operator,e.inputId):void 0,o="controlRole"in e?e.controlRole:"role"in e?e.role:void 0,i=U(o)?o:void 0;return{inputId:e.inputId,...r?{kind:r}:{},...i?{controlRole:i}:{},...t?{operator:t}:{},...e.field?{field:e.field}:{}}}function U(e){return e==="grain"||e==="metric"||e==="dimension"||e==="aggregation"||e==="sqlParam"}function G(e){const r=p(e);return r.length>0?r:void 0}function P(e){return(e||[]).map(X)}function L(e){return P(e).filter(r=>r.isActive)}function I(e){if(e.kind==="filter"){const r=F(e.operator,e.id);return{inputId:e.id,kind:e.kind,label:e.label,field:a(e.field,"dimension"),operator:r||"in"}}return{inputId:e.id,kind:e.kind,label:e.label,controlRole:e.role}}function J(e=[]){return e.map(r=>typeof r=="object"?r:{label:String(r),value:r})}function h(e){return e==null?!1:Array.isArray(e)?e.length>0:typeof e=="string"?e.trim().length>0:!0}function X(e){if("toAnalyticsInput"in e)return e.toAnalyticsInput();if("kind"in e&&"isActive"in e)return e;if("id"in e){const r=I(e),t=Object.prototype.hasOwnProperty.call(e,"value")?e.value:e.defaultValue;return{inputId:r.inputId,kind:r.kind,label:r.label,...r.field?{field:r.field}:{},...r.operator?{operator:r.operator}:{},...r.controlRole?{controlRole:r.controlRole}:{},value:t,isActive:h(t)}}return{...e,kind:"filter",isActive:h(e.value),value:e.value}}function S(e){return e.source}function Y(e){var r;return!!((r=e.fields)!=null&&r.length)}function a(e,r){return{...e,role:e.role||r}}function p(e){return(e||[]).map(T)}function Z(e){if(e)return e}function F(e,r){if(e===void 0)return;const t=w.normalizeSemaphorInputOperator(e);if(!t)throw new Error(`useSemaphorInput "${r}" uses unsupported filter operator "${e}".`);return t}function H(e,r={}){const t=r.pathPrefix||"analysisOptions";if(e===void 0)return{ok:!0};if(!e||typeof e!="object"||Array.isArray(e))return s(t,"Data App analysis options must be an object.");const o=e,i={};if(o.chartTitle!==void 0){if(typeof o.chartTitle!="string")return s(`${t}.chartTitle`,'Data App analysis option "chartTitle" must be a string.');i.chartTitle=o.chartTitle}if(o.chartType!==void 0){if(typeof o.chartType!="string")return s(`${t}.chartType`,'Data App analysis option "chartType" must be a string.');i.chartType=o.chartType}if(o.driverMode!==void 0){if(!te(o.driverMode))return s(`${t}.driverMode`,'Data App analysis option "driverMode" must be absolute_delta, largest_negative, largest_positive, positive_and_negative, or all.');i.driverMode=o.driverMode}if(o.includePopulation!==void 0){if(typeof o.includePopulation!="boolean")return s(`${t}.includePopulation`,'Data App analysis option "includePopulation" must be a boolean.');i.includePopulation=o.includePopulation}if(o.calendarContext!==void 0){const n=oe(o.calendarContext,{pathPrefix:`${t}.calendarContext`,validateTimezone:r.validateTimezone});if(!n.ok)return n;i.calendarContext=n.calendarContext}return{ok:!0,analysisOptions:i}}function ee(e){const r=e.queries.map((i,n)=>re(i,n,{fieldCatalogs:e.fieldCatalogs||[],requireFieldCatalog:!!e.requireFieldCatalog,validateTimezone:e.validateTimezone})),t=r.flatMap(i=>i.diagnostics),o=r.map(i=>i.executionResult);return{ok:t.every(i=>i.severity!=="error"),diagnostics:t,queries:r,intents:r.flatMap(i=>i.intent?[i.intent]:[]),executionResults:o}}function re(e,r,t){const o=`queries.${r}`;try{const i=ne(e),n=he(e,i),d=w.validateSemaphorAnalyticsIntent(i),l=[...ce({querySpec:e,queryId:n,intent:i,pathPrefix:o}),...d.errors.map(y=>q(y,{queryHook:e.queryHook,queryId:n,pathPrefix:o,severity:"error",intent:i})),...d.warnings.map(y=>q(y,{queryHook:e.queryHook,queryId:n,pathPrefix:o,severity:"warning",intent:i})),...se({querySpec:e,queryId:n,intent:i,pathPrefix:o,fieldCatalogs:t.fieldCatalogs,requireFieldCatalog:t.requireFieldCatalog}),...ue({querySpec:e,queryId:n,intent:i,pathPrefix:o,validateTimezone:t.validateTimezone})],c=ye(d,l);return{queryHook:e.queryHook,queryId:n,intent:i,diagnostics:l,executionResult:b({intent:i,validation:c,diagnostics:l})}}catch(i){const n={severity:"error",code:"invalid_query_spec",message:i instanceof Error?i.message:String(i),path:o,queryHook:e.queryHook,queryId:O(e.spec)},d=B([n]);return{queryHook:e.queryHook,queryId:n.queryId,diagnostics:[n],executionResult:b({validation:d,diagnostics:[n]})}}}function s(e,r){return{ok:!1,issues:[{code:"invalid_analysis_option",message:r,path:e}]}}function x(e){return!!(e&&typeof e=="object"&&!Array.isArray(e))}function te(e){return e==="absolute_delta"||e==="largest_negative"||e==="largest_positive"||e==="positive_and_negative"||e==="all"}function ie(e){return e.trim().length>0&&!Number.isNaN(Date.parse(e))}function oe(e,r){var c;if(!e||typeof e!="object"||Array.isArray(e))return s(r.pathPrefix,'Data App analysis option "calendarContext" must be an object.');const t=e,o=t.tz,i=t.weekStart,n=t.anchor,d=n&&typeof n=="object"&&!Array.isArray(n)?n.iso:void 0,l=typeof o=="string"?((c=r.validateTimezone)==null?void 0:c.call(r,o))??o:null;return l?typeof i!="number"||!Number.isInteger(i)||i<0||i>6?s(`${r.pathPrefix}.weekStart`,'Data App analysis option "calendarContext.weekStart" must be an integer from 0 to 6.'):n!=="now"&&!(typeof d=="string"&&ie(d))?s(`${r.pathPrefix}.anchor`,'Data App analysis option "calendarContext.anchor" must be "now" or an object with a valid iso string.'):{ok:!0,calendarContext:{tz:l,weekStart:i,anchor:n}}:s(`${r.pathPrefix}.tz`,'Data App analysis option "calendarContext.tz" must be a valid timezone string.')}function ne(e){return ae(e.spec)}function ae(e){if(!x(e))throw new Error("useSemaphorQuery spec must be an object.");if(e.queryKind==="metric")return v(e);if(e.queryKind==="analysis")return M(e);if(e.queryKind==="records")return C(e);if(e.queryKind==="sql")return $(e);if(e.queryKind==="inputOptions")return R(e);throw new Error("useSemaphorQuery spec.queryKind must be metric, analysis, records, inputOptions, or sql.")}function se(e){if(e.intent.kind==="sql")return[];if(e.fieldCatalogs.length===0&&!e.requireFieldCatalog)return[];const r=me(e.fieldCatalogs,e.intent.source);return r?[...de({...e,catalog:r}),...le({...e,catalog:r})]:[{severity:"error",code:"invalid_source_ref",message:`Source ref for ${e.querySpec.queryHook} does not match a visible Semaphor source.`,path:`${e.pathPrefix}.spec.source`,queryHook:e.querySpec.queryHook,queryId:e.queryId,intentId:e.intent.id,source:e.intent.source}]}function de(e){return fe(e.intent).flatMap(({field:r,path:t})=>z(e.catalog,r,e.intent.source)?[]:[{severity:"error",code:"missing_field",message:`Field "${r.name}" is not visible on the selected Semaphor source.`,path:`${e.pathPrefix}.${t}`,queryHook:e.querySpec.queryHook,queryId:e.queryId,intentId:e.intent.id,source:m(r,e.intent.source),field:r}])}function le(e){return("inputs"in e.intent?e.intent.inputs||[]:[]).flatMap((t,o)=>{if(!t.field)return[];const i=m(t.field,e.intent.source);return u.semaphorSourcesReferToSameDataset(i,e.intent.source)?z(e.catalog,t.field,e.intent.source)?[]:[{severity:"error",code:"missing_field",message:`Input "${t.inputId}" references field "${t.field.name}", which is not visible on the selected Semaphor source.`,path:`${e.pathPrefix}.spec.inputs.${o}.field`,queryHook:e.querySpec.queryHook,queryId:e.queryId,intentId:e.intent.id,source:i,field:t.field}]:[{severity:"error",code:"unsupported_input_filter_composition",message:`Input "${t.inputId}" filters a different Semaphor source than the query. Cross-source Data App inputs are not supported yet.`,path:`${e.pathPrefix}.spec.inputs.${o}.field`,queryHook:e.querySpec.queryHook,queryId:e.queryId,intentId:e.intent.id,source:i,field:t.field}]})}function ue(e){if(e.querySpec.spec.queryKind!=="analysis")return[];const r=H(e.querySpec.spec,{pathPrefix:`${e.pathPrefix}.spec`,validateTimezone:e.validateTimezone});return r.ok?[]:r.issues.map(t=>({severity:"error",code:t.code,message:t.message,path:t.path,queryHook:e.querySpec.queryHook,queryId:e.queryId,intentId:e.intent.id,source:e.intent.source}))}function ce(e){return e.querySpec.spec.queryKind!=="sql"?[]:x(e.querySpec.spec)?Object.prototype.hasOwnProperty.call(e.querySpec.spec,"parameters")?[{severity:"error",code:"deprecated_sql_parameters",message:"semaphor.sql uses defaultParameters for static SQL param(...) fallback values. The legacy parameters field is not supported.",path:`${e.pathPrefix}.spec.parameters`,queryHook:e.querySpec.queryHook,queryId:e.queryId,intentId:e.intent.id}]:[]:[]}function fe(e){return e.kind==="metric"?[...e.metrics.map((r,t)=>({field:r,path:`spec.metrics.${t}`})),...e.primaryMetric?[{field:e.primaryMetric,path:"spec.primaryMetric"}]:[],...e.dateField?[{field:e.dateField,path:"spec.dateField"}]:[],...(e.dimensions||[]).map((r,t)=>({field:r,path:`spec.dimensions.${t}`})),...e.orderBy?[{field:e.orderBy.field,path:"spec.orderBy.field"}]:[],...(e.filters||[]).map((r,t)=>({field:r.field,path:`spec.filters.${t}.field`}))]:e.kind==="records"?[...e.fields.map((r,t)=>({field:r,path:`spec.fields.${t}`})),...e.dateField?[{field:e.dateField,path:"spec.dateField"}]:[],...e.orderBy?[{field:e.orderBy.field,path:"spec.orderBy.field"}]:[],...(e.filters||[]).map((r,t)=>({field:r.field,path:`spec.filters.${t}.field`}))]:e.kind==="inputOptions"?[{field:e.field,path:"spec.field"}]:[]}function me(e,r){return e.find(t=>g(t,r))}function z(e,r,t){const o=m(r,t);if(g(e,o))return e.fields.find(i=>pe(i,r)&&g(e,m(i,e.source)))}function g(e,r){return[e.source,...e.sourceAliases||[]].some(t=>u.semaphorSourcesReferToSameDataset(t,r))}function m(e,r){return e.source||r}function pe(e,r){return!!(e.name&&r.name&&e.name===r.name)}function q(e,r){return{severity:r.severity,code:e.code||"invalid_analytics_intent",message:e.message,path:e.path?`${r.pathPrefix}.spec.${e.path}`:r.pathPrefix,queryHook:r.queryHook,queryId:r.queryId,intentId:r.intent.id,source:r.intent.source}}function ye(e,r){const t=B(r);return{ok:t.ok&&e.ok,errors:A([...e.errors,...t.errors]),warnings:A([...e.warnings,...t.warnings]),repairHints:[...e.repairHints,...t.repairHints]}}function B(e){const r=e.filter(o=>o.severity==="error").map(k),t=e.filter(o=>o.severity==="warning").map(k);return{ok:r.length===0,errors:r,warnings:t,repairHints:r.map(o=>{var i,n;return{code:o.code,message:o.message,fieldRole:o.fieldRole,invalidField:(i=o.repairHint)==null?void 0:i.invalidField,recommendedNextStep:((n=o.repairHint)==null?void 0:n.recommendedNextStep)||"Update the Data App SDK query spec to use visible Semaphor source and field refs."}})}}function k(e){var r;return{code:e.code,message:e.message,path:e.path,fieldRole:e.code==="invalid_source_ref"?"source":void 0,repairHint:{code:e.code,message:e.message,invalidField:(r=e.field)==null?void 0:r.name,fieldRole:e.code==="invalid_source_ref"?"source":void 0,recommendedNextStep:e.code==="unsupported_input_filter_composition"?"Use an input field from the same Semaphor source as the query, or split the query into separate source-scoped queries.":"Update the query spec to use a visible Semaphor source and field ref."}}}function A(e){const r=new Set;return e.filter(t=>{const o=`${t.code}:${t.path||""}:${t.message}`;return r.has(o)?!1:(r.add(o),!0)})}function b(e){var t,o;const r=e.diagnostics.filter(i=>i.severity==="error");return{intentId:(t=e.intent)==null?void 0:t.id,status:r.length?"failed":"answered",resultShape:(o=e.intent)==null?void 0:o.kind,intent:e.intent,validation:e.validation,coverage:{answeredObligations:r.length?[]:["query_spec_validation"],missingObligations:r.length?["query_spec_validation"]:[],warnings:e.validation.warnings},missingFields:r.filter(i=>i.code==="missing_field").flatMap(i=>{var n;return(n=i.field)!=null&&n.name?[i.field.name]:[]}),warnings:e.diagnostics.filter(i=>i.severity==="warning").map(i=>i.message),metadata:{validationKind:"data_app_sdk_query_spec"}}}function he(e,r){return r.id||O(e.spec)}function O(e){if(!e||typeof e!="object"||!("id"in e))return;const r=e.id;return typeof r=="string"&&r.trim()?r:void 0}exports.hasSemaphorInputValue=h;exports.normalizeSemaphorAnalysisQueryOptions=H;exports.normalizeSemaphorInputOptions=J;exports.toSemaphorActiveInputSnapshots=L;exports.toSemaphorAnalysisIntent=M;exports.toSemaphorAnalysisQueryOptions=D;exports.toSemaphorInputBinding=T;exports.toSemaphorInputBindings=G;exports.toSemaphorInputOptionsIntent=R;exports.toSemaphorInputSnapshots=P;exports.toSemaphorInputSpec=I;exports.toSemaphorMetricIntent=v;exports.toSemaphorRecordsIntent=C;exports.toSemaphorSqlIntent=$;exports.validateSemaphorDataAppQuerySpecs=ee;