react-semaphor 0.1.424 → 0.1.426

package/dist/types/shared.d.ts

@@ -180,9 +180,6 @@ declare interface CardConfig {
      * Configuration for on-click dashboard filters triggered by this card.
      */
     clickFilterInteractions?: ClickFilterInteraction[];
-    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
-    targetValue?: number;
-    showComparisonInLegend?: boolean;
     showTrendline?: boolean;
     trendlineWindow?: number;
     trendlineGranularity?: 'day' | 'week' | 'month';
@@ -337,6 +334,33 @@ declare type ColumnType = 'string' | 'number' | 'date';
 
 declare type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
 
+declare type ComparisonPresentationSpec = {
+    /** Defaults to difference. */
+    displayMode?: 'difference' | 'percent_change' | 'both' | 'ratio';
+    /** Defaults to true. This controls display, not baseline selection. */
+    showComparison?: boolean;
+    /** Percent/ratio precision. Defaults to the surface formatter; valid range is 0..6. */
+    precision?: number;
+    /** Defaults to arrow_badge. */
+    indicatorStyle?: 'arrow_badge' | 'arrow' | 'badge' | 'none';
+    /** Defaults to true. */
+    showColor?: boolean;
+    position?: 'left' | 'right' | 'top';
+    /** Defaults to false. */
+    conditionalLabel?: boolean;
+    labelName?: string;
+    conditionalLabels?: {
+        increase?: string;
+        decrease?: string;
+        neutral?: string;
+    };
+    colors?: {
+        increase?: string;
+        decrease?: string;
+        neutral?: string;
+    };
+};
+
 declare type ConditionalFormatCondition = {
     kind: 'comparison';
     columnId: string;
@@ -564,11 +588,17 @@ declare type DashboardInputScope = {
     sectionIds: string[];
 };
 
-declare type DashboardInputSlot = {
+declare type DashboardInputSlot = ({
     status: 'set';
     value: DashboardInputValue;
-} | {
+    comparisonSelection?: GlobalDateComparisonSelection;
+}) | ({
     status: 'cleared';
+    comparisonSelection?: GlobalDateComparisonSelection;
+}) | {
+    status?: never;
+    value?: never;
+    comparisonSelection: GlobalDateComparisonSelection;
 };
 
 declare type DashboardInputTextContent = Array<{
@@ -702,7 +732,6 @@ declare interface DetailTableBackupConfig {
         function: AggregateFunction;
         pivotLevel: string | 'ALL';
     }>;
-    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
 }
 
 declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
@@ -1290,6 +1319,13 @@ declare type FormatSpec = {
     suffix?: string;
 };
 
+declare type GlobalDateComparisonSelection = {
+    mode: 'off';
+} | {
+    mode: 'period';
+    spec: ViewerPeriodComparisonSpec;
+};
+
 declare type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
 
 declare interface GroupByColumn extends BaseColumn {
@@ -1434,6 +1470,30 @@ declare interface MetricColumn extends BaseColumn {
     aliasTemplate?: string;
 }
 
+declare type MetricComparisonConfig = {
+    mode: 'off';
+} | {
+    mode: 'explicit';
+    spec: MetricComparisonSpec;
+};
+
+declare type MetricComparisonPolarity = 'higher_is_better' | 'lower_is_better' | 'neutral';
+
+declare type MetricComparisonSpec = {
+    kind: 'previous_period';
+    offsetPeriods?: number;
+    alignment?: 'calendar' | 'weekday';
+    toDate?: boolean;
+} | {
+    kind: 'previous_year';
+    offsetYears?: number;
+    alignment?: 'calendar' | 'weekday';
+    toDate?: boolean;
+} | {
+    kind: 'target';
+    targetValue: number;
+};
+
 declare interface MetricField extends Field {
     role: 'metric';
     aggregate?: AggregateFunction;
@@ -1482,9 +1542,10 @@ declare interface MetricField extends Field {
      * pre-aggregated metric input.
      */
     isPreAggregated?: boolean;
-    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'start_vs_end' | 'target';
-    comparisonDisplay?: 'column' | 'inline' | 'hover';
-    targetValue?: number;
+    comparison?: MetricComparisonConfig;
+    comparisonPolarity?: MetricComparisonPolarity;
+    /** Governed runtime annotation. When present, authoring polarity is read-only. */
+    semanticComparisonPolarity?: MetricComparisonPolarity;
 }
 
 declare type NoneOptions = {};
@@ -2247,6 +2308,11 @@ declare type TCard = {
 };
 
 declare type TCardPreferences = {
+    comparisonPresentation?: ComparisonPresentationSpec;
+    /** Absence means eligible metrics inherit the Global Date comparison. */
+    inheritGlobalComparison?: false;
+    /** Separate two-metric KPI feature; defaults to false. */
+    metricPairComparisonEnabled?: boolean;
     onClickFilter?: FilterOnClick[];
     filterOnClick?: boolean;
     filterOnClickField?: string;
@@ -2319,43 +2385,14 @@ declare type TCardPreferences = {
         colorScale?: string;
     };
     kpiVisualOptions?: {
-        lowerIsBetter?: boolean;
         countryLogoId?: string;
         valueAlignment?: 'left' | 'center';
         formatOptions?: TFormatOptions;
-        metricComparison?: {
-            enabled?: boolean;
-            calculationType?: 'difference' | 'change' | 'change_difference' | 'ratio';
-            formatOptions?: TFormatOptions;
-            showArrow?: boolean;
-            showColor?: boolean;
-            conditionalLabel?: boolean;
-            labelName?: string;
-            position?: 'left' | 'right' | 'top';
-            conditionalLabels?: {
-                increase?: string;
-                decrease?: string;
-                noChange?: string;
-            };
-            colorConfig?: {
-                increase?: 'green' | 'red' | 'neutral' | string;
-                decrease?: 'green' | 'red' | 'neutral' | string;
-                noChange?: 'green' | 'red' | 'neutral' | string;
-            };
-        };
-    };
-    tableVisualOptions?: {
-        metricComparison?: {
-            calculatedAs?: 'difference' | 'change' | 'change_difference' | 'ratio';
-            indicatorStyle?: 'arrow_badge' | 'arrow' | 'badge' | 'none';
-            formatOptions?: TFormatOptions;
-            colors?: {
-                increase?: 'green' | 'red' | 'neutral' | string;
-                decrease?: 'green' | 'red' | 'neutral' | string;
-                neutral?: 'green' | 'red' | 'neutral' | string;
-            };
-            lowerIsBetter?: boolean;
-        };
+        /**
+         * Presentation-only polarity for a query-backed KPI's manually returned
+         * current/prior value pair. Governed KPIs use per-metric polarity instead.
+         */
+        queryComparisonPolarity?: MetricComparisonPolarity;
     };
     pivotTableOptions?: {
         showRowTotals?: boolean;
@@ -2887,6 +2924,10 @@ export declare function useDebouncedDirtyCheck<T>(currentState: T, pristineState
     resetDirty: () => void;
 };
 
+declare type ViewerPeriodComparisonSpec = Extract<MetricComparisonSpec, {
+    kind: 'previous_period' | 'previous_year';
+}>;
+
 /**
  * Display mode for visual components - controls which UI elements are shown
  */

package/dist/types/surfboard.d.ts

@@ -1,7 +1,7 @@
 import { ColumnSizingState } from '@tanstack/react-table';
+import { default as default_2 } from 'react';
 import { FontSpec } from 'chart.js';
-import { JSX } from 'react/jsx-runtime';
-import { JSX as JSX_2 } from 'react';
+import { JSX } from 'react';
 
 export declare type AggregateCalc = 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'COUNT' | 'COUNT_DISTINCT';
 
@@ -204,7 +204,7 @@ declare interface CalculatedFieldFormula {
  */
 declare type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
 
-export declare function CalendarPreferencesDialog({ open, onOpenChange, }: CalendarPreferencesDialogProps): JSX.Element;
+export declare function CalendarPreferencesDialog({ open, onOpenChange, }: CalendarPreferencesDialogProps): default_2.JSX.Element;
 
 declare interface CalendarPreferencesDialogProps {
     open: boolean;
@@ -272,9 +272,6 @@ declare interface CardConfig {
      * Configuration for on-click dashboard filters triggered by this card.
      */
     clickFilterInteractions?: ClickFilterInteraction[];
-    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
-    targetValue?: number;
-    showComparisonInLegend?: boolean;
     showTrendline?: boolean;
     trendlineWindow?: number;
     trendlineGranularity?: 'day' | 'week' | 'month';
@@ -437,6 +434,33 @@ declare type ColumnType = 'string' | 'number' | 'date';
 
 declare type ComparisonOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte';
 
+declare type ComparisonPresentationSpec = {
+    /** Defaults to difference. */
+    displayMode?: 'difference' | 'percent_change' | 'both' | 'ratio';
+    /** Defaults to true. This controls display, not baseline selection. */
+    showComparison?: boolean;
+    /** Percent/ratio precision. Defaults to the surface formatter; valid range is 0..6. */
+    precision?: number;
+    /** Defaults to arrow_badge. */
+    indicatorStyle?: 'arrow_badge' | 'arrow' | 'badge' | 'none';
+    /** Defaults to true. */
+    showColor?: boolean;
+    position?: 'left' | 'right' | 'top';
+    /** Defaults to false. */
+    conditionalLabel?: boolean;
+    labelName?: string;
+    conditionalLabels?: {
+        increase?: string;
+        decrease?: string;
+        neutral?: string;
+    };
+    colors?: {
+        increase?: string;
+        decrease?: string;
+        neutral?: string;
+    };
+};
+
 declare type ConditionalFormatCondition = {
     kind: 'comparison';
     columnId: string;
@@ -685,11 +709,17 @@ export declare type DashboardInputScope = {
     sectionIds: string[];
 };
 
-export declare type DashboardInputSlot = {
+export declare type DashboardInputSlot = ({
     status: 'set';
     value: DashboardInputValue;
-} | {
+    comparisonSelection?: GlobalDateComparisonSelection;
+}) | ({
     status: 'cleared';
+    comparisonSelection?: GlobalDateComparisonSelection;
+}) | {
+    status?: never;
+    value?: never;
+    comparisonSelection: GlobalDateComparisonSelection;
 };
 
 export declare type DashboardInputTextContent = Array<{
@@ -929,7 +959,6 @@ declare interface DetailTableBackupConfig {
         function: AggregateFunction;
         pivotLevel: string | 'ALL';
     }>;
-    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'target' | 'start_vs_end';
 }
 
 declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowflake' | 'clickhouse' | 'duckdb' | 'mssql';
@@ -1544,7 +1573,8 @@ declare type FormatSpec = {
 export declare type GetDashboardResponse = {
     dashboard: TDashboard;
     lenses: TLens[];
-    filterValues?: TFilterValue[];
+    filterValues?: TFilterValue[] | null;
+    inputValues?: LensInputValuesSnapshot | null;
     defaultLensId?: string;
     assistantProfileId?: string;
     semanticExecutionPayload: SemanticExecutionPayload;
@@ -1559,6 +1589,13 @@ export declare type GetPluginsResponse = {
     }[];
 };
 
+declare type GlobalDateComparisonSelection = {
+    mode: 'off';
+} | {
+    mode: 'period';
+    spec: ViewerPeriodComparisonSpec;
+};
+
 declare type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
 
 declare interface GroupByColumn extends BaseColumn {
@@ -1694,7 +1731,12 @@ declare interface JoinPlan {
 export declare type KPICardProps = {
     card: TCard;
     isLoading?: boolean;
-    renderFilterInfo?: () => JSX_2.Element | null;
+    renderFilterInfo?: () => JSX.Element | null;
+};
+
+export declare type LensInputValuesSnapshot = {
+    generatedAt: string;
+    dashboardInputValues: DashboardInputValues;
 };
 
 export declare type Level = 'database' | 'schema' | 'table';
@@ -1713,12 +1755,44 @@ export declare type LoadingProps = {
 
 declare type LogicalOperator = 'AND' | 'OR';
 
+/**
+ * A comparison input proven to be present in the card's executed filter set.
+ * Ownership and UI coverage must consume this stage, never source inputs.
+ */
+export declare type MaterializedDashboardDateComparisonInput = ResolvedDashboardDateComparisonInput & {
+    effectiveFilterValue: TFilterValue;
+};
+
 declare interface MetricColumn extends BaseColumn {
     role: 'metric';
     aggregate: AggregateFunction;
     aliasTemplate?: string;
 }
 
+declare type MetricComparisonConfig = {
+    mode: 'off';
+} | {
+    mode: 'explicit';
+    spec: MetricComparisonSpec;
+};
+
+declare type MetricComparisonPolarity = 'higher_is_better' | 'lower_is_better' | 'neutral';
+
+declare type MetricComparisonSpec = {
+    kind: 'previous_period';
+    offsetPeriods?: number;
+    alignment?: 'calendar' | 'weekday';
+    toDate?: boolean;
+} | {
+    kind: 'previous_year';
+    offsetYears?: number;
+    alignment?: 'calendar' | 'weekday';
+    toDate?: boolean;
+} | {
+    kind: 'target';
+    targetValue: number;
+};
+
 declare interface MetricField extends Field {
     role: 'metric';
     aggregate?: AggregateFunction;
@@ -1767,9 +1841,10 @@ declare interface MetricField extends Field {
      * pre-aggregated metric input.
      */
     isPreAggregated?: boolean;
-    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'start_vs_end' | 'target';
-    comparisonDisplay?: 'column' | 'inline' | 'hover';
-    targetValue?: number;
+    comparison?: MetricComparisonConfig;
+    comparisonPolarity?: MetricComparisonPolarity;
+    /** Governed runtime annotation. When present, authoring polarity is read-only. */
+    semanticComparisonPolarity?: MetricComparisonPolarity;
 }
 
 declare type NoneOptions = {};
@@ -1890,6 +1965,20 @@ declare type RelativeDateFilter = {
     to: number;
 };
 
+export declare type ResolvedDashboardDateComparisonInput = {
+    inputId: string;
+    filterId: string;
+    label: string;
+    filter: TFilter;
+    /**
+     * The active value before execution-only canonicalization. Comparison
+     * ownership uses this value as provenance evidence and must fail closed
+     * when its filter or field identity does not match the definition.
+     */
+    filterValue?: TFilterValue;
+    selection: GlobalDateComparisonSelection;
+};
+
 export declare type ResolvedDashboardInput = {
     id: string;
     kind: 'filter' | 'control';
@@ -1905,6 +1994,7 @@ export declare type ResolvedDashboardInput = {
     control?: ControlDefinition;
     controlValue?: unknown;
     missingRequiredValue?: boolean;
+    comparisonSelection?: GlobalDateComparisonSelection;
 };
 
 export declare type ResolvedDashboardInputContext = {
@@ -1916,6 +2006,8 @@ export declare type ResolvedDashboardInputContext = {
     controlBindings: ControlBinding[];
     controlValues: Record<string, unknown>;
     variablesByName: Record<string, ResolvedDashboardInput>;
+    globalDateComparisonSelection?: GlobalDateComparisonSelection;
+    dateComparisonInputs?: ResolvedDashboardDateComparisonInput[];
     variablesById: Record<string, ResolvedDashboardInput>;
     missingRequiredInputs: ResolvedDashboardInput[];
 };
@@ -1940,6 +2032,8 @@ declare type ResolvedPrimaryDateField = {
     entityName: string;
     entityType: string;
     dataType: string;
+    /** Canonical dataset coordinates stamped by the temporal grounding boundary. */
+    source?: SemaphorSourceRef;
     dateFormat?: string;
     customFormat?: string;
     defaultGranularity?: TimeGranularity;
@@ -2663,6 +2757,11 @@ export declare type TCardContext = {
 };
 
 export declare type TCardPreferences = {
+    comparisonPresentation?: ComparisonPresentationSpec;
+    /** Absence means eligible metrics inherit the Global Date comparison. */
+    inheritGlobalComparison?: false;
+    /** Separate two-metric KPI feature; defaults to false. */
+    metricPairComparisonEnabled?: boolean;
     onClickFilter?: FilterOnClick[];
     filterOnClick?: boolean;
     filterOnClickField?: string;
@@ -2735,43 +2834,14 @@ export declare type TCardPreferences = {
         colorScale?: string;
     };
     kpiVisualOptions?: {
-        lowerIsBetter?: boolean;
         countryLogoId?: string;
         valueAlignment?: 'left' | 'center';
         formatOptions?: TFormatOptions;
-        metricComparison?: {
-            enabled?: boolean;
-            calculationType?: 'difference' | 'change' | 'change_difference' | 'ratio';
-            formatOptions?: TFormatOptions;
-            showArrow?: boolean;
-            showColor?: boolean;
-            conditionalLabel?: boolean;
-            labelName?: string;
-            position?: 'left' | 'right' | 'top';
-            conditionalLabels?: {
-                increase?: string;
-                decrease?: string;
-                noChange?: string;
-            };
-            colorConfig?: {
-                increase?: 'green' | 'red' | 'neutral' | string;
-                decrease?: 'green' | 'red' | 'neutral' | string;
-                noChange?: 'green' | 'red' | 'neutral' | string;
-            };
-        };
-    };
-    tableVisualOptions?: {
-        metricComparison?: {
-            calculatedAs?: 'difference' | 'change' | 'change_difference' | 'ratio';
-            indicatorStyle?: 'arrow_badge' | 'arrow' | 'badge' | 'none';
-            formatOptions?: TFormatOptions;
-            colors?: {
-                increase?: 'green' | 'red' | 'neutral' | string;
-                decrease?: 'green' | 'red' | 'neutral' | string;
-                neutral?: 'green' | 'red' | 'neutral' | string;
-            };
-            lowerIsBetter?: boolean;
-        };
+        /**
+         * Presentation-only polarity for a query-backed KPI's manually returned
+         * current/prior value pair. Governed KPIs use per-metric polarity instead.
+         */
+        queryComparisonPolarity?: MetricComparisonPolarity;
     };
     pivotTableOptions?: {
         showRowTotals?: boolean;
@@ -3260,7 +3330,8 @@ export declare type TLens = {
     id: string;
     name: string;
     template?: string;
-    filterValues?: TFilterValue[];
+    filterValues?: TFilterValue[] | null;
+    inputValues?: LensInputValuesSnapshot | null;
     isDefault?: boolean;
     shared?: boolean;
 };
@@ -3350,6 +3421,10 @@ export declare interface UserPreference {
     updatedAt: string;
 }
 
+declare type ViewerPeriodComparisonSpec = Extract<MetricComparisonSpec, {
+    kind: 'previous_period' | 'previous_year';
+}>;
+
 /**
  * Display mode for visual components - controls which UI elements are shown
  */