react-semaphor 0.1.424 → 0.1.426

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

@@ -188,9 +188,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';
@@ -343,8 +340,67 @@ declare type ColumnTextWrap = 'default' | 'truncate' | 'wrap' | 'nowrap' | 'pres
 
 declare type ColumnType = 'string' | 'number' | 'date';
 
+export declare type ComparisonDocumentChange = {
+    kind: 'metric';
+    path: string;
+    metricId?: string;
+    legacyType: string;
+    comparison?: MetricComparisonConfig;
+    comparisonPolarity?: MetricComparisonPolarity;
+    removedFields: string[];
+} | {
+    kind: 'presentation';
+    path: string;
+    comparisonPresentation?: ComparisonPresentationSpec;
+    metricPairComparisonEnabled?: boolean;
+    comparisonPolarityMetricIds?: string[];
+    intentionallyDiscardedFields?: string[];
+    removedFields: string[];
+};
+
+export declare type ComparisonDocumentTransformResult<T> = {
+    document: T;
+    changed: boolean;
+    changes: ComparisonDocumentChange[];
+    diagnostics: ComparisonMigrationDiagnostic[];
+};
+
+export declare type ComparisonMigrationDiagnostic = {
+    severity: 'warning' | 'error';
+    code: 'invalid_target_value' | 'unsupported_start_vs_end' | 'unsupported_comparison_type' | 'stray_target_value' | 'malformed_metric_columns' | 'conflicting_comparison_contracts' | 'conflicting_comparison_window_transform' | 'conflicting_comparison_presentation_contracts' | 'conflicting_legacy_presentation_namespaces' | 'conflicting_legacy_polarity' | 'invalid_legacy_comparison_presentation' | 'unsupported_comparison_format';
+    path: string;
+    message: string;
+};
+
 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;
+    };
+};
+
 export declare function compileDashboardFromPlan(input: {
     dashboardId: string;
     plan: DashboardPlan;
@@ -676,11 +732,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<{
@@ -906,7 +968,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';
@@ -1506,6 +1567,13 @@ export declare type GeneratedDashboardCardArtifact = {
 
 export declare function getDashboardAuthoringCardSource(card: Pick<DashboardPlanCard, 'analyticsIntent'>): SemaphorSourceRef | undefined;
 
+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 {
@@ -1660,6 +1728,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;
@@ -1708,9 +1800,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 = {};
@@ -2687,6 +2780,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;
@@ -2759,43 +2857,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;
@@ -3254,6 +3323,13 @@ declare type TotalsBehavior = 'sum' | 'avg' | 'count' | 'label' | 'none';
 /** Point style options supported by Chart.js */
 declare type TPointStyle = 'circle' | 'cross' | 'crossRot' | 'dash' | 'line' | 'rect' | 'rectRounded' | 'rectRot' | 'star' | 'triangle';
 
+/**
+ * Pure, atomic migration for persisted dashboard-shaped JSON documents.
+ * Documents with neither an active legacy metric comparison nor legacy
+ * comparison presentation are returned by identity.
+ */
+export declare function transformComparisonDocument<T>(document: T): ComparisonDocumentTransformResult<T>;
+
 declare type TSheet = {
     id: string;
     kind?: 'dashboard' | 'document';
@@ -3320,6 +3396,10 @@ export declare function validateDashboardChangePlan(plan: DashboardChangePlan):
 
 export declare function validateDashboardPlan(plan: DashboardPlan): DashboardAuthoringValidationResult;
 
+declare type ViewerPeriodComparisonSpec = Extract<MetricComparisonSpec, {
+    kind: 'previous_period' | 'previous_year';
+}>;
+
 /**
  * Display mode for visual components - controls which UI elements are shown
  */

package/dist/types/dashboard.d.ts

@@ -1,7 +1,6 @@
 import { ColumnSizingState } from '@tanstack/react-table';
 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';
 
@@ -265,9 +264,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';
@@ -430,6 +426,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;
@@ -680,11 +703,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<{
@@ -919,7 +948,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';
@@ -1534,7 +1562,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;
@@ -1549,6 +1578,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 {
@@ -1684,7 +1720,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';
@@ -1703,12 +1744,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;
@@ -1757,9 +1830,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 = {};
@@ -1880,6 +1954,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';
@@ -1895,6 +1983,7 @@ export declare type ResolvedDashboardInput = {
     control?: ControlDefinition;
     controlValue?: unknown;
     missingRequiredValue?: boolean;
+    comparisonSelection?: GlobalDateComparisonSelection;
 };
 
 export declare type ResolvedDashboardInputContext = {
@@ -1906,6 +1995,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[];
 };
@@ -1930,6 +2021,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;
@@ -2651,6 +2744,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;
@@ -2723,43 +2821,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;
@@ -3248,7 +3317,8 @@ export declare type TLens = {
     id: string;
     name: string;
     template?: string;
-    filterValues?: TFilterValue[];
+    filterValues?: TFilterValue[] | null;
+    inputValues?: LensInputValuesSnapshot | null;
     isDefault?: boolean;
     shared?: boolean;
 };
@@ -3338,6 +3408,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
  */

package/dist/types/data-app-builder.d.ts

@@ -1,4 +1,4 @@
-import { JSX } from 'react/jsx-runtime';
+import * as ReactRuntime from 'react';
 
 export declare type ApiStatus = {
     ok: boolean;
@@ -169,7 +169,7 @@ export declare type BuilderTurnResult = {
     error?: string;
 };
 
-export declare function DataAppBuilder({ projectId, projectName, dataAppId, apiServiceUrl, adapters, }: DataAppBuilderProps): JSX.Element;
+export declare function DataAppBuilder({ projectId, projectName, dataAppId, apiServiceUrl, adapters, }: DataAppBuilderProps): ReactRuntime.JSX.Element;
 
 export declare type DataAppBuilderAdapters = {
     readStatus?: (options: {

package/dist/types/data-app-sdk.d.ts

@@ -1,5 +1,5 @@
 import { CSSProperties } from 'react';
-import { JSX } from 'react/jsx-runtime';
+import { JSX } from 'react';
 import { ReactElement } from 'react';
 import { ReactNode } from 'react';