react-semaphor 0.1.443 → 0.1.445

package/dist/types/report-runtime-context.d.ts

@@ -22,6 +22,9 @@ export declare type CalendarPreferencesResponse = {
 
 export declare const DEFAULT_CALENDAR_CONTEXT: CalendarContext;
 
+/** React-free validation shared by Calendar and temporal-result boundaries. */
+export declare function isValidIanaTimeZone(value: string): boolean;
+
 declare type LocaleStyle = 'short' | 'medium' | 'long';
 
 export declare type MonthAlignedFiscalCalendar = {

package/dist/types/shared.d.ts

@@ -64,6 +64,8 @@ declare type BaseFilter = {
     dataType?: string;
     fieldMeta?: FilterFieldMeta;
     semanticContext?: FilterSemanticContext;
+    /** Governed meaning for canonical grouped-temporal filter values. */
+    temporalBucket?: TemporalBucketMetadata;
 };
 
 declare type CacheConfig = {
@@ -119,6 +121,15 @@ 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 interface CardConfig {
     /**
      * Matrix table is the shared analytics-spine successor for pivot and
@@ -180,9 +191,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;
@@ -499,7 +507,10 @@ declare type ControlOption = {
     label: string;
     presentation?: {
         granularity?: TimeGranularity;
+        format?: TemporalBucketFormat;
+        /** Saved-dashboard compatibility only. New authoring writes `format`. */
         dateFormat?: DateFormatValue;
+        /** Saved-dashboard compatibility only. New authoring writes `format`. */
         customFormat?: string;
     };
 };
@@ -1091,8 +1102,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;
@@ -1134,6 +1146,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;
 }
@@ -1177,6 +1195,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 type FilterDashboardInput = DashboardInputBase & {
@@ -1337,7 +1359,7 @@ declare type FormatSpec = {
     type: 'string';
     prefix?: string;
     suffix?: string;
-};
+} | TemporalBucketFormat;
 
 declare type GlobalDateComparisonSelection = {
     mode: 'off';
@@ -1346,7 +1368,7 @@ declare type GlobalDateComparisonSelection = {
     spec: ViewerPeriodComparisonSpec;
 };
 
-declare type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+declare type Granularity = SemaphorTimeGrain;
 
 declare interface GroupByColumn extends BaseColumn {
     role: 'groupby';
@@ -1357,6 +1379,11 @@ declare interface GroupByColumn extends BaseColumn {
 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.
@@ -1568,6 +1595,11 @@ declare interface MetricField extends Field {
     semanticComparisonPolarity?: MetricComparisonPolarity;
 }
 
+declare type MonthAlignedFiscalCalendar = {
+    kind: 'month_aligned';
+    yearStartMonth: number;
+};
+
 declare type NoneOptions = {};
 
 /**
@@ -1635,6 +1667,11 @@ declare type PersistedInteraction = Interaction & {
 
 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 interface QueryConfig {
@@ -1687,6 +1724,15 @@ 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 SemaphorAggregateFunction = 'SUM' | 'COUNT' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
 
 declare type SemaphorAnalyticsFilter = SemaphorAnalyticsValueFilter | SemaphorAnalyticsNullFilter;
@@ -1740,7 +1786,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -1791,7 +1837,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -1883,6 +1929,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -1918,7 +1966,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -1928,36 +1976,7 @@ declare type SemaphorRelationshipHint = {
     relationshipIds?: string[];
 };
 
-declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
-    kind: 'semantic';
-}>;
-
-declare type SemaphorSourceRef = {
-    kind: 'semantic';
-    domainId: string;
-    datasetName: string;
-    datasetId?: string;
-    label?: string;
-    connectionId?: string;
-} | {
-    kind: 'physical';
-    connectionId: string;
-    connectionType?: string;
-    tableName: string;
-    databaseName?: string;
-    schemaName?: string;
-    label?: string;
-    dialect?: SemaphorDialect;
-} | {
-    kind: 'sql';
-    connectionId: string;
-    dialect?: SemaphorDialect;
-    label?: string;
-};
-
-declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
-
-declare type SemaphorValueFormat = {
+declare type SemaphorScalarValueFormat = {
     type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
     minimumFractionDigits?: number;
     maximumFractionDigits?: number;
@@ -1994,6 +2013,35 @@ declare type SemaphorValueFormat = {
     suffix?: string;
 };
 
+declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
+    kind: 'semantic';
+}>;
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    connectionType?: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
+
 /**
  * Stable serializer for dashboard dirty checks.
  * This consolidates normalization + serialization into one call site, so
@@ -2628,6 +2676,31 @@ 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 TemporalPrecision = 'minute';
 
 declare type TextCardInlineFormat = {
@@ -2815,7 +2888,7 @@ declare interface TimeDrillStep {
     rollingWindow?: number;
 }
 
-declare type TimeGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+declare type TimeGranularity = SemaphorTimeGrain;
 
 /**
  * Inline filter definition stored on a card.
@@ -2989,6 +3062,8 @@ declare type VisualDisplayPreferences = {
     };
 };
 
+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 {