react-semaphor 0.1.443 → 0.1.445

package/dist/types/surfboard.d.ts

@@ -137,8 +137,16 @@ declare type BaseFilter = {
     dataType?: string;
     fieldMeta?: FilterFieldMeta;
     semanticContext?: FilterSemanticContext;
+    /** Governed meaning for canonical grouped-temporal filter values. */
+    temporalBucket?: TemporalBucketMetadata;
 };
 
+declare interface BaseInteractionEvent {
+    sourceCardId: string;
+    filterGroups: ClickFilterConditionGroup[];
+    metric?: ClickedMetricValue;
+}
+
 declare type BaseSurfaceAppearance = {
     background?: string;
     foreground?: string;
@@ -273,9 +281,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;
@@ -330,6 +335,38 @@ declare type ChartAppearance = {
     axisColor?: string;
 };
 
+declare interface ClickedMetricValue {
+    field: Field;
+    value: number;
+    formattedValue?: string;
+}
+
+declare interface ClickFilterCondition {
+    field: Field;
+    operator: Operator;
+    value: string | number | null;
+    label?: string;
+    /** Governed meaning for a canonical grouped-temporal scalar. */
+    temporalBucket?: TemporalBucketMetadata;
+}
+
+declare interface ClickFilterConditionGroup {
+    filters: ClickFilterCondition[];
+}
+
+declare interface ClickFilterEvent extends BaseInteractionEvent {
+    interactionMode: 'clickFilter';
+    applyToCardIds?: string[];
+    excludeCardIds?: string[];
+    /**
+     * Whether the source card should receive its own filter.
+     * When true, the source card will be filtered (not just blurred).
+     * Used when user selects from multiple interactions popup.
+     * @default false
+     */
+    filterSourceCard?: boolean;
+}
+
 declare interface ClickFilterInteraction {
     mode: 'clickFilter';
     /**
@@ -608,7 +645,10 @@ export 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;
     };
 };
@@ -855,6 +895,11 @@ export declare type DashboardProps = {
      * inputs instead of documentInputValues.
      */
     dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
+    /**
+     * Runtime interaction state captured for deterministic print/replay entry
+     * points. Ordinary dashboard consumers should leave this unset.
+     */
+    interactionExecutionSnapshot?: Record<string, InteractionState>;
     /**
      * Render target for print entry points. Generic dashboard PDF exports also
      * use cardDisplay.mode="print"; document-specific print handling must only
@@ -1193,6 +1238,43 @@ export declare type DocumentVariableRef = {
     key: 'generatedAt' | 'pageNumber' | 'pageCount';
 };
 
+declare interface DrillBreadcrumb {
+    /**
+     * The user clicked one or more segments. Each group of filters represents
+     * a single segment (i.e., a single click interaction).
+     *
+     * - Filters within a group are AND-ed (e.g., state = 'NY' AND ship_mode = 'Standard').
+     * - Across groups, they are OR-ed (e.g., ... OR state = 'CA' AND ship_mode = 'First Class').
+     */
+    sourceFilterGroups: ClickFilterConditionGroup[];
+    /**
+     * The next (group by) field the user is drilling into (e.g., 'city' after 'state').
+     */
+    toField?: Field;
+    /**
+     * Optional: If the drill target is a time field, this describes the granularity (e.g., month, year).
+     */
+    granularity?: TimeGranularity;
+    /**
+     * Optional: Indicates whether the drill is for time comparison (e.g., YoY).
+     */
+    timeComparison?: TimeComparison;
+    /**
+     * Optional: The metric the user clicked (e.g., '123 Orders'), used for display only.
+     */
+    metric?: ClickedMetricValue;
+}
+
+declare interface DrillDownEvent extends BaseInteractionEvent {
+    interactionMode: 'drillDown';
+    hierarchyId: string;
+    filterGroups: ClickFilterConditionGroup[];
+    metric?: ClickedMetricValue;
+    toField: Field;
+    granularity?: TimeGranularity;
+    timeComparison?: TimeComparison;
+}
+
 declare interface DrillDownInteraction {
     mode: 'drillDown';
     /**
@@ -1224,6 +1306,12 @@ declare interface DrillHierarchyStep {
     linkedInsightId?: string;
 }
 
+declare interface DrillThroughEvent extends BaseInteractionEvent {
+    interactionMode: 'drillThrough';
+    targetDashboardId: string;
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+}
+
 declare interface DrillThroughInteraction {
     mode: 'drillThrough';
     /**
@@ -1241,6 +1329,17 @@ declare interface DrillThroughInteraction {
     label?: string;
 }
 
+declare interface DrillToDetailEvent extends BaseInteractionEvent {
+    interactionMode: 'drillToDetail';
+    detailFields: Field[];
+    sortBy?: SortByField[];
+    limit?: number;
+    detailTitle?: string;
+    targetInsightId?: string;
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    displayMode?: 'modal' | 'replace-card';
+}
+
 declare interface DrillToDetailInteraction {
     mode: 'drillToDetail';
     /**
@@ -1270,6 +1369,11 @@ declare interface DrillToDetailInteraction {
     label?: string;
 }
 
+declare interface DrillToURLEvent extends BaseInteractionEvent {
+    interactionMode: 'drillToURL';
+    url: string;
+}
+
 declare interface DrillToURLInteraction {
     mode: 'drillToURL';
     /**
@@ -1313,6 +1417,15 @@ declare interface DrillUpInteraction {
 
 export declare type DroppableId = 'droppable-group-by' | 'droppable-metric';
 
+declare interface DynamicDrillEvent extends BaseInteractionEvent {
+    interactionMode: 'dynamicDrill';
+    filterGroups: ClickFilterConditionGroup[];
+    metric?: ClickedMetricValue;
+    toField: Field;
+    granularity?: TimeGranularity;
+    timeComparison?: TimeComparison;
+}
+
 declare interface DynamicDrillInteraction {
     mode: 'dynamicDrill';
     /**
@@ -1358,8 +1471,9 @@ export declare type ExportDataPayload = {
 
 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;
@@ -1401,6 +1515,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;
 }
@@ -1444,6 +1564,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;
 }
 
 export declare type FilterDashboardInput = DashboardInputBase & {
@@ -1604,7 +1728,7 @@ declare type FormatSpec = {
     type: 'string';
     prefix?: string;
     suffix?: string;
-};
+} | TemporalBucketFormat;
 
 export declare type GetDashboardResponse = {
     dashboard: TDashboard;
@@ -1633,7 +1757,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';
@@ -1644,6 +1768,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.
@@ -1657,6 +1786,12 @@ export declare type HtmlOptions = {
     html: string;
 };
 
+declare interface InlineDrillEvent extends BaseInteractionEvent {
+    interactionMode: 'inlineDrill';
+    fetchMode?: 'lazy' | 'preloaded';
+    inlineLimit?: number;
+}
+
 declare interface InlineDrillInteraction {
     mode: 'inlineDrill';
     /**
@@ -1699,6 +1834,60 @@ declare interface InlineDrillInteraction {
  */
 declare type Interaction = ClickFilterInteraction | DrillDownInteraction | DrillThroughInteraction | DrillToDetailInteraction | DrillToURLInteraction | InlineDrillInteraction | DrillUpInteraction | DynamicDrillInteraction;
 
+declare type InteractionEvent = DrillDownEvent | DynamicDrillEvent | DrillToURLEvent | DrillThroughEvent | DrillToDetailEvent | InlineDrillEvent | ClickFilterEvent;
+
+declare interface InteractionState {
+    /**
+     * If user is in a drill hierarchy (static or dynamic), this tracks which one.
+     * Undefined if not currently in a drill path.
+     */
+    hierarchyId?: string;
+    /**
+     * Breadcrumb trail representing the user's drill path.
+     * Empty if no drill-down steps have occurred.
+     */
+    breadcrumbs: DrillBreadcrumb[];
+    /**
+     * All click filters applied from this card
+     */
+    appliedClickFilters?: ClickFilterEvent[];
+    /**
+     * (Optional) Track last one-off interaction (e.g., drillToDetail, drillToURL).
+     * Useful for things like modals or redirection handling.
+     */
+    lastInteractionEvent?: InteractionEvent;
+    /**
+     * Context mode for drill-to-insight filtering.
+     * Controls whether dashboard filters are applied alongside interaction filters.
+     *
+     * - 'interactionFilters': Only filters from the interaction event (no dashboard filters)
+     * - 'full': Dashboard filters + interaction filters
+     * - 'none': No filters applied
+     *
+     * Undefined for regular cards (not insights).
+     */
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    /**
+     * Source dashboard ID for drill-through navigation.
+     * Used for "Back" button navigation.
+     * Only set for global drill context (interactionStates['__DRILL_CONTEXT__']).
+     */
+    sourceDashboardId?: string;
+    /**
+     * Source dashboard title for drill-through navigation.
+     * Used for "Back to [X]" UI display.
+     * Only set for global drill context (interactionStates['__DRILL_CONTEXT__']).
+     */
+    sourceDashboardTitle?: string;
+    /**
+     * Target dashboard ID for drill-through navigation.
+     * Filters only apply when current dashboard matches this ID.
+     * Prevents filters from applying to source dashboard during navigation.
+     * Only set for global drill context (interactionStates['__DRILL_CONTEXT__']).
+     */
+    targetDashboardId?: string;
+}
+
 declare interface InteractionTargetOverride {
     applyToCardIds?: string[] | null;
     excludeCardIds?: string[] | null;
@@ -1954,6 +2143,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';
 }
 
 export declare type Placeholders = {
@@ -2099,7 +2293,15 @@ export declare type ResolvedDocumentInput = {
     exports: Record<string, string | number | boolean | null>;
 };
 
-declare type ResolvedPrimaryDateField = {
+declare type ResolvedPrimaryDateField = (ResolvedPrimaryDateFieldBase & ({
+    defaultGranularity?: SemaphorTimeGrain;
+    format?: undefined;
+} | {
+    defaultGranularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+})) | null;
+
+declare type ResolvedPrimaryDateFieldBase = {
     sourceDataset: string;
     sourceField: string;
     name: string;
@@ -2109,13 +2311,10 @@ declare type ResolvedPrimaryDateField = {
     entityName: string;
     entityType: string;
     dataType: string;
-    /** Canonical dataset coordinates stamped by the temporal grounding boundary. */
+    /** Canonical dataset coordinates stamped by the semantic grounding boundary. */
     source?: SemaphorSourceRef;
-    dateFormat?: string;
-    customFormat?: string;
-    defaultGranularity?: TimeGranularity;
-    supportedGranularities?: TimeGranularity[];
-} | null;
+    supportedGranularities?: SemaphorTimeGrain[];
+};
 
 declare type ResolvedValueFormatPreferences = {
     locale: string;
@@ -2151,6 +2350,15 @@ declare type SemanticExecutionPayload = {
     }>;
 };
 
+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;
@@ -2204,7 +2412,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -2255,7 +2463,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -2347,6 +2555,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -2382,7 +2592,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -2392,36 +2602,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;
@@ -2458,6 +2639,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];
+
 declare interface SortByField extends Field {
     role: 'sortby';
     direction: 'asc' | 'desc';
@@ -3074,6 +3284,7 @@ export declare type TDataColumn = {
     calculatedFormula?: CalculatedFieldFormula;
     derivedField?: SemaphorDerivedFieldDefinition;
     format?: FormatSpec;
+    granularity?: TimeGranularity;
     sourceField?: string;
     aggregate?: AggregateFunction;
 };
@@ -3176,6 +3387,31 @@ export 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';
 
 export declare type TEvent = {
@@ -3363,6 +3599,12 @@ export declare type THeatmapConfig = {
 
 export declare type Theme = 'dark' | 'light' | 'system';
 
+declare interface TimeComparison {
+    type: 'previous_year' | 'previous_period';
+    offset: number;
+    granularity: TimeGranularity;
+}
+
 declare interface TimeDrillStep {
     granularity: TimeGranularity;
     next?: TimeGranularity;
@@ -3370,7 +3612,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.