react-semaphor 0.1.443 → 0.1.445

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

@@ -48,6 +48,31 @@ declare interface CalculatedFieldFormula {
  */
 declare type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
 
+declare type CalendarContext = {
+    tz: string;
+    weekStart: WeekStart;
+    anchor: 'now' | {
+        iso: string;
+    };
+    fiscalCalendar?: MonthAlignedFiscalCalendar;
+};
+
+declare type CanonicalPivotResultBase = {
+    columns: SemaphorResultColumn[];
+    columnKeyMap: QueryColumnKeyMap;
+    pivotResultContract: CanonicalPivotResultContract;
+};
+
+declare type CanonicalPivotResultContract = {
+    version: 1;
+    expectedRoleFieldIds: PivotResultExpectedRoleFieldIds;
+    expectedMetricAliases: readonly string[];
+    columnKinds: Readonly<Record<string, PivotResultColumnKind>>;
+    columnClassifications: Readonly<Record<string, PivotResultColumnClassification | undefined>>;
+};
+
+declare type CanonicalPivotResultTransport = LoadedEmptyPivotResult | LoadedValidPivotResult;
+
 declare interface CardConfig {
     /**
      * Matrix table is the shared analytics-spine successor for pivot and
@@ -109,9 +134,6 @@ declare interface CardConfig {
      * Configuration for on-click dashboard filters triggered by this card.
      */
     clickFilterInteractions?: ClickFilterInteraction[];
-    showTrendline?: boolean;
-    trendlineWindow?: number;
-    trendlineGranularity?: 'day' | 'week' | 'month';
     summary?: {
         enabled?: boolean;
         showOnCard?: boolean;
@@ -199,11 +221,14 @@ export declare type DashboardAssistantAnalysisRequest = {
 export declare type DashboardAssistantArtifact = {
     kind: 'analysis' | 'dynamic_visual' | 'clarification';
     status: 'ready' | 'partial' | 'failed';
+    resultOwner?: TemporalResultOwner;
+    pivotResult?: CanonicalPivotResultTransport;
     title?: string;
     question?: string;
     chartType?: TChartType;
     records?: Record<string, unknown>[];
     columns?: SemaphorResultColumn[];
+    columnKeyMap?: QueryColumnKeyMap_2;
     sql?: string;
     python?: string;
     cardConfig?: CardConfig;
@@ -380,8 +405,9 @@ declare type EntityType = 'table' | 'view' | 'materialized view' | 'model' | 'fi
 
 declare interface Field {
     /**
-     * Unique identifier for this field instance (for joins, UI state, etc.).
-     * Should be unique within the context of the query or data model.
+     * Stable authored/semantic field identifier (for joins, UI state, etc.).
+     * It is normally unique within a role, but one saved query may reuse it in
+     * different roles; result bindings must therefore include the role.
      * Example: 'orders.customer_id', 'expr_12345', etc.
      */
     id: string;
@@ -423,6 +449,12 @@ declare interface Field {
      */
     derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
+    /**
+     * Source-level temporal presentation keeps the semantic grain that authored
+     * the format. The card's mutable `granularity` remains the active query
+     * grain, so changing it cannot accidentally retarget a semantic default.
+     */
+    semanticTemporalPresentation?: SemanticTemporalPresentation;
     aggregate?: AggregateFunction;
     fieldScope?: FieldScope;
 }
@@ -444,6 +476,10 @@ declare interface FilterCondition {
     field: Field;
     operator: Operator;
     value: FilterValue;
+    /** Display-only label for canonical grouped-temporal values. */
+    label?: string;
+    /** Governed meaning for a canonical grouped-temporal scalar. */
+    temporalBucket?: TemporalBucketMetadata;
 }
 
 declare interface FilterGroup {
@@ -492,11 +528,16 @@ declare type FormatSpec = {
     type: 'string';
     prefix?: string;
     suffix?: string;
-};
+} | TemporalBucketFormat;
 
 declare interface GroupByField extends Field {
     role: 'groupby';
     granularity?: TimeGranularity;
+    /**
+     * Query transport policy for grouped temporal values. This is projected
+     * into executable card config and is not persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
     /**
      * Optional SQL expression for grouping (e.g., DATE_TRUNC('month', order_date)).
      * If present, used in SELECT and GROUP BY instead of just the column name.
@@ -565,6 +606,16 @@ declare interface JoinPlan {
     joins: Join[];
 }
 
+declare type LoadedEmptyPivotResult = CanonicalPivotResultBase & {
+    pivotResultState: 'loaded_empty';
+    records: [];
+};
+
+declare type LoadedValidPivotResult = CanonicalPivotResultBase & {
+    pivotResultState: 'loaded_valid';
+    records: [Record<string, unknown>, ...Record<string, unknown>[]];
+};
+
 declare type LogicalOperator = 'AND' | 'OR';
 
 declare type MatrixAxisLevelDescriptor = {
@@ -572,7 +623,7 @@ declare type MatrixAxisLevelDescriptor = {
     fieldKey: string;
     label: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     subtotal?: SemaphorMatrixSubtotalOptions;
 };
 
@@ -687,7 +738,7 @@ declare type MatrixMeasureDescriptor = {
     label: string;
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -701,7 +752,7 @@ declare type MatrixMeasureSemantics = {
 } | {
     kind: 'semiAdditive';
     aggregate?: SemaphorAggregateFunction;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
 } | {
     kind: 'nonAdditive';
     aggregate?: SemaphorAggregateFunction;
@@ -864,16 +915,63 @@ declare interface MetricField extends Field {
     semanticComparisonPolarity?: MetricComparisonPolarity;
 }
 
+declare type MonthAlignedFiscalCalendar = {
+    kind: 'month_aligned';
+    yearStartMonth: number;
+};
+
 declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'like' | 'not like' | 'in' | 'not in' | 'between' | 'not between' | 'isNull' | 'isNotNull';
 
 declare interface PivotByField extends Field {
     role: 'pivotby';
+    /**
+     * Query transport policy for grouped temporal pivot members. This is
+     * projected into executable config and is never persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
 }
 
+declare type PivotResultColumnClassification = {
+    isSubtotal?: boolean;
+    subtotalScope?: 'base' | 'pivot-value' | 'grand-total';
+};
+
+declare type PivotResultColumnKind = 'row' | 'pivot_metric' | 'value';
+
+declare type PivotResultExpectedRoleFieldIds = Readonly<Partial<Record<QueryColumnKeyRole, readonly string[]>>>;
+
+declare interface QueryColumnKeyMap {
+    version: 1;
+    source: 'explorer';
+    byRole: QueryColumnKeyMapByRole;
+    byMetricAlias?: Record<string, QueryColumnKeyMapEntry>;
+}
+
+declare type QueryColumnKeyMap_2 = QueryColumnKeyMap;
+
+declare type QueryColumnKeyMapByRole = Partial<Record<QueryColumnKeyRole, Record<string, QueryColumnKeyMapEntry>>>;
+
+declare interface QueryColumnKeyMapEntry {
+    role: QueryColumnKeyRole;
+    rawKey: string;
+    outputKey?: string;
+}
+
+declare type QueryColumnKeyRole = 'groupby' | 'metric' | 'pivotby' | 'detail';
+
 declare type SelectedEntities = SelectedEntity[];
 
 declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
 
+declare type SemanticTemporalPresentation = {
+    granularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+};
+
+declare const SEMAPHOR_MATRIX_TIME_GRAINS: ["hour", "day", "week", "month", "quarter", "year"];
+
+declare const SEMAPHOR_TIME_GRAINS: readonly ["second", "minute", "hour", "day", "week", "month", "quarter", "year"];
+
 declare type SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -1075,7 +1173,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -1159,7 +1257,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -1275,6 +1373,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -1310,7 +1410,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -1390,6 +1490,30 @@ declare type SemaphorPaginationRequest = {
     pageSize: number;
 };
 
+declare type SemaphorPivotResultColumnIdentity = {
+    metricId: string;
+    /** Collision-safe identity for this configured metric instance. */
+    metricAlias: string;
+    /**
+     * Sole transported tuple identity in configured pivot-axis order. A leaf
+     * carries the complete tuple, a subtotal carries its explicit prefix, and a
+     * metric-only or grand-total column carries an empty tuple.
+     */
+    members: SemaphorPivotResultMember[];
+};
+
+declare type SemaphorPivotResultMember = {
+    /** Stable identity of the configured pivot field. */
+    fieldId: string;
+    /** Canonical pivot member value; labels are resolved only at presentation. */
+    value: SemaphorPivotValue;
+    /** Present when this member is an activated governed temporal bucket. */
+    temporalBucket?: TemporalBucketMetadata;
+};
+
+/** Stable canonical scalar transported for one physical pivot member. */
+declare type SemaphorPivotValue = string | null;
+
 declare type SemaphorProtocolIssue = {
     code: string;
     message: string;
@@ -1469,7 +1593,7 @@ declare type SemaphorRelationshipHint = {
 
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
-    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    unit: SemaphorTimeGrain;
     value: number;
     anchor?: 'now' | 'latest_available';
     completeness?: 'include_partial' | 'complete_periods';
@@ -1494,6 +1618,45 @@ declare type SemaphorResultColumn = {
     aggregate?: SemaphorFieldRef['aggregate'];
     source?: SemaphorFieldRef['source'];
     derivedField?: SemaphorDerivedFieldDefinition;
+    temporalBucket?: TemporalBucketMetadata;
+    pivotIdentity?: SemaphorPivotResultColumnIdentity;
+};
+
+declare type SemaphorScalarValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    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 type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
@@ -1552,47 +1715,10 @@ declare type SemaphorSqlResult = SemaphorAnalyticsResultBase & {
     };
 };
 
-declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
-declare type SemaphorValueFormat = {
-    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
-    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';
@@ -1634,6 +1760,33 @@ declare type TDynamicVisualIntent = {
     includesKpis: boolean;
 };
 
+declare const TEMPORAL_BUCKET_PRESETS: readonly ["week_of_short", "week_of_long", "quarter_short", "quarter_long", "fiscal_quarter_short", "fiscal_year"];
+
+declare type TemporalBucketFormat = {
+    type: 'temporal_bucket';
+    presentation: TemporalBucketPresentation;
+};
+
+declare type TemporalBucketMetadata = {
+    kind: 'temporal_bucket';
+    granularity: SemaphorTimeGrain;
+    calendar: Pick<CalendarContext, 'tz' | 'weekStart' | 'fiscalCalendar'>;
+};
+
+declare type TemporalBucketPresentation = {
+    mode: 'auto';
+} | {
+    mode: 'preset';
+    preset: TemporalBucketPreset;
+} | {
+    mode: 'pattern';
+    pattern: string;
+};
+
+declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
+
+declare type TemporalResultOwner = 'config' | 'freeform' | 'none';
+
 declare interface TimeDrillStep {
     granularity: TimeGranularity;
     next?: TimeGranularity;
@@ -1641,10 +1794,12 @@ declare interface TimeDrillStep {
     rollingWindow?: number;
 }
 
-declare type TimeGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+declare type TimeGranularity = SemaphorTimeGrain;
 
 declare type TVisualizationMode = 'builtin' | 'dynamic';
 
+declare type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+
 declare type WindowFunction = 'running_total' | 'moving_average' | 'previous_period_delta' | 'percent_of_total';
 
 declare interface WindowTransform {