react-semaphor 0.1.423 → 0.1.425

package/dist/surfboard/index.cjs

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("../chunks/index-BPM3gDRw.js"),e=require("../chunks/common-types-C73-Ud1-.js"),a=require("../chunks/calendar-preferences-dialog-CTmeASaM.js");exports.Surfboard=r.DashboardPlus;exports.CONTROL_CARD_DEFAULT_VALUE=e.CONTROL_CARD_DEFAULT_VALUE;exports.EMPTY_SELECTION=e.EMPTY_SELECTION;exports.CalendarPreferencesDialog=a.CalendarPreferencesDialog;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const r=require("../chunks/dashboard-MKIqgGDp.js"),e=require("../chunks/common-types-C73-Ud1-.js"),a=require("../chunks/calendar-preferences-dialog-BLaSWhLl.js");exports.Surfboard=r.DashboardPlus;exports.CONTROL_CARD_DEFAULT_VALUE=e.CONTROL_CARD_DEFAULT_VALUE;exports.EMPTY_SELECTION=e.EMPTY_SELECTION;exports.CalendarPreferencesDialog=a.CalendarPreferencesDialog;

package/dist/surfboard/index.js

@@ -1,6 +1,6 @@
-import { a as e } from "../chunks/index-yHe0SeLO.js";
-import { C, E } from "../chunks/common-types-4bjoIgvm.js";
-import { C as s } from "../chunks/calendar-preferences-dialog-t5ET6MON.js";
+import { a as e } from "../chunks/dashboard-5agU0G_D.js";
+import { C, E } from "../chunks/common-types-ClkOI-3O.js";
+import { C as s } from "../chunks/calendar-preferences-dialog-DJwV0aqn.js";
 export {
   C as CONTROL_CARD_DEFAULT_VALUE,
   s as CalendarPreferencesDialog,

package/dist/types/analytics-protocol.d.ts

@@ -56,16 +56,97 @@ export declare function buildSemaphorQualifiedSourcePath(input: {
     quoteIdentifier?: (value: string, dialect: SemaphorDialect) => string;
 }): string;
 
+export declare const COMPARISON_PRESENTATION_DEFAULTS: {
+    readonly displayMode: "difference";
+    readonly showComparison: true;
+    readonly indicatorStyle: "arrow_badge";
+    readonly showColor: true;
+    readonly conditionalLabel: false;
+};
+
+export declare type ComparisonAvailability = {
+    status: 'available';
+} | {
+    status: 'unavailable';
+    reason: ComparisonUnavailableReason;
+    traceId?: string;
+};
+
+export 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 type ComparisonUnavailableReason = 'finite_current_window_required' | 'current_window_not_started' | 'temporal_binding_missing' | 'temporal_binding_ambiguous' | 'temporal_binding_invalid' | 'unsupported_output_shape' | 'unsupported_raw_sql' | 'insufficient_history' | 'invalid_comparison_spec' | 'comparison_execution_failed';
+
+export declare const DEFAULT_METRIC_COMPARISON_POLARITY: "higher_is_better";
+
+export declare function evaluateMetricComparison(input: {
+    currentValue: number | null;
+    comparisonValue: number | null;
+    polarity?: MetricComparisonPolarity;
+}): MetricComparisonEvaluation;
+
 export declare function getAnalyticsCatalogFieldCandidates(field: AnalyticsCatalogField): string[];
 
 export declare function getAnalyticsCatalogFieldName(field: AnalyticsCatalogField): string;
 
+/** Stable persisted identity for a card control's compatibility input. */
+export declare function getCardControlCompatInputId(cardId: string, controlId: string): string;
+
+/** Stable persisted identity for a card inline filter's compatibility input. */
+export declare function getCardInlineFilterCompatInputId(cardId: string, filterId: string): string;
+
+/** Stable persisted identity for a dashboard control's compatibility input. */
+export declare function getDashboardControlCompatInputId(controlId: string): string;
+
+/** Stable persisted identity for a dashboard filter's compatibility input. */
+export declare function getDashboardFilterCompatInputId(filterId: string): string;
+
 export declare function getSemaphorAnalyzeResultFieldNames(): SemaphorAnalyzeResultFieldName[];
 
 export declare function getSemaphorConnectionCapabilities(connectionType: string | undefined, options?: {
     connectionId?: string;
 }): SemaphorConnectionCapabilities;
 
+export declare type GlobalDateComparisonContext = {
+    selection: GlobalDateComparisonSelection;
+    inheritGlobalComparison?: false;
+    /** Fixed execution clock carried by authoritative dashboard replay snapshots. */
+    referenceTime?: string;
+};
+
+export declare type GlobalDateComparisonSelection = {
+    mode: 'off';
+} | {
+    mode: 'period';
+    spec: ViewerPeriodComparisonSpec;
+};
+
+export declare function hasCompleteSemaphorSourceIdentity(source: SemaphorSourceRef | undefined): boolean;
+
 export declare function isAnalyticsCatalogDateField(field: AnalyticsCatalogField): boolean;
 
 export declare function isAnalyticsCatalogDimensionField(field: AnalyticsCatalogField): boolean;
@@ -405,6 +486,104 @@ export declare type MatrixWarning = {
 
 export declare function mergeSemaphorSourcesByIdentity<TSource extends SemaphorSourceRef>(sources: readonly TSource[]): TSource[];
 
+export declare type MetricComparisonConfig = {
+    mode: 'off';
+} | {
+    mode: 'explicit';
+    spec: MetricComparisonSpec;
+};
+
+export declare type MetricComparisonDirection = 'increase' | 'decrease' | 'no_change' | 'unknown';
+
+export declare type MetricComparisonEvaluation = {
+    status: 'available' | 'insufficient_history';
+    currentValue: number | null;
+    comparisonValue: number | null;
+    delta: number | null;
+    percentChange: number | null;
+    ratio: number | null;
+    direction: MetricComparisonDirection;
+    sentiment: MetricComparisonSentiment;
+};
+
+export declare type MetricComparisonMetadataEntry = {
+    type: MetricComparisonSpec['kind'];
+    displayName?: string;
+    displayLabel?: string;
+    output: MetricComparisonOutput;
+};
+
+/** Keyed by MetricComparisonOutput.outputId, never by source id or label. */
+export declare type MetricComparisonMetadataMap = Record<MetricComparisonOutput['outputId'], MetricComparisonMetadataEntry>;
+
+export declare type MetricComparisonOutput = MetricComparisonOutputBase & ({
+    request: ResolvedMetricComparisonRequest;
+    availability: {
+        status: 'available';
+    };
+    comparisonColumnKey: string;
+    deltaColumnKey: string;
+    percentChangeColumnKey: string;
+    ratioColumnKey: string;
+    rowStatusColumnKey?: string;
+    currentBucketColumnKey?: string;
+    comparisonSourceBucketColumnKey?: string;
+} | {
+    request?: ResolvedMetricComparisonRequest;
+    availability: Extract<ComparisonAvailability, {
+        status: 'unavailable';
+    }>;
+    comparisonColumnKey?: never;
+    deltaColumnKey?: never;
+    percentChangeColumnKey?: never;
+    ratioColumnKey?: never;
+    rowStatusColumnKey?: never;
+    currentBucketColumnKey?: never;
+    comparisonSourceBucketColumnKey?: never;
+});
+
+export declare type MetricComparisonOutputBase = {
+    outputId: string;
+    metricId: string;
+    metricAlias: string;
+    currentColumnKey: string;
+    windowGrain?: MetricComparisonWindowGrain;
+    currentWindow?: ResolvedDateWindow;
+    comparisonWindow?: ResolvedDateWindow;
+    referenceTime?: string;
+    temporalField?: SemaphorFieldRef;
+};
+
+export declare type MetricComparisonPolarity = 'higher_is_better' | 'lower_is_better' | 'neutral';
+
+export declare type MetricComparisonSentiment = 'favorable' | 'unfavorable' | 'neutral';
+
+export 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;
+};
+
+export declare type MetricComparisonWindowGrain = 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+export declare type MetricResultAliasInput = {
+    alias?: string;
+    name: string;
+    entityName?: string;
+    role?: string;
+    aggregate?: string;
+    expression?: string;
+};
+
 export declare function normalizeAnalyticsCatalogDataType(value: unknown): AnalyticsCatalogDataType;
 
 export declare function normalizeAnalyticsCatalogName(value: unknown): string;
@@ -417,12 +596,61 @@ export declare function normalizeSemaphorInputOperator(value: SemaphorInputOpera
 
 export declare function parseSemaphorAnalyzeResult(value: unknown): SemaphorAnalyzeResult;
 
+export declare function parseSemaphorIsoInstant(value: unknown): Date | null;
+
 export declare function parseSemaphorIsoTimeWindowBoundary(value: unknown): Date | null;
 
 export declare function preferSemaphorFieldRefMetadata(current: SemaphorFieldRef, next: SemaphorFieldRef): SemaphorFieldRef;
 
 export declare function preferSemaphorSourceMetadata(current: SemaphorSourceRef, next: SemaphorSourceRef): SemaphorSourceRef;
 
+export declare type ResolvedDateWindow = {
+    startInclusive: string;
+    endExclusive: string;
+    timezone: string;
+};
+
+export declare type ResolvedMetricComparisonRequest = {
+    source: 'explicit';
+    spec: MetricComparisonSpec;
+} | {
+    source: 'inherited';
+    spec: ViewerPeriodComparisonSpec;
+};
+
+export declare type ResolvedTemporalContext = {
+    status: 'resolved';
+    field: SourceBearingTemporalField;
+    bindingSource: TemporalBindingCandidate['kind'];
+    currentWindow?: ResolvedDateWindow;
+    governingWindowSource?: TemporalRangeCandidate['source'];
+    governingRangeId?: string;
+    constraints: TemporalRangeCandidate[];
+} | {
+    status: 'unavailable';
+    reason: 'temporal_binding_missing' | 'temporal_binding_ambiguous' | 'temporal_binding_invalid' | 'unsupported_raw_sql';
+    constraints: TemporalRangeCandidate[];
+};
+
+export declare function resolveMetricComparisonRequest(input: {
+    metricComparison?: MetricComparisonConfig;
+    inheritGlobalComparison?: false;
+    globalSelection?: GlobalDateComparisonSelection;
+    isGlobalDateApplicable: boolean;
+}): ResolvedMetricComparisonRequest | undefined;
+
+/** Stable result-instance identity shared by query producers and consumers. */
+export declare function resolveMetricResultAlias(metric: MetricResultAliasInput): string;
+
+export declare function resolveTemporalContext(input: ResolveTemporalContextInput): ResolvedTemporalContext;
+
+export declare type ResolveTemporalContextInput = {
+    rawSql?: boolean;
+    candidates: TemporalBindingCandidate[];
+    ranges?: TemporalRangeCandidate[];
+    querySources?: SemaphorSourceRef[];
+};
+
 export declare const SEMAPHOR_ANALYTICS_INTENT_FIXTURES: {
     revenueKpi: {
         version: 1;
@@ -641,7 +869,7 @@ export declare const SEMAPHOR_ANALYZE_RESULT_FIELD_CONTRACT: {
     readonly answerSummary: "string";
     readonly responseDetail: "responseDetail";
     readonly mode: "string";
-    readonly comparisonType: "string";
+    readonly comparisonKind: "string";
     readonly executionResult: "executionResult";
     readonly compiledQuery: "unknown";
     readonly data: "unknown";
@@ -1117,7 +1345,7 @@ export declare type SemaphorAnalyticsObligation = {
     requiredFieldCandidates?: string[];
     limit?: number;
     timeWindow?: SemaphorTimeWindow;
-    comparison?: 'same_period_last_year' | 'previous_period';
+    comparison?: 'previous_year' | 'previous_period';
     required?: boolean;
 };
 
@@ -2012,7 +2240,7 @@ export declare type SemaphorAnalyzeResult = Partial<Record<SemaphorAnalyzeResult
     answerSummary?: string;
     responseDetail?: SemaphorAnalyzeResponseDetail;
     mode?: string;
-    comparisonType?: string;
+    comparisonKind?: string;
     executionResult?: SemaphorAnalyticsExecutionResult;
     compiledQuery?: SemaphorCompiledQuery;
     data?: unknown;
@@ -3925,6 +4153,70 @@ export declare type SemaphorViewPresentation = {
     kind: 'text';
 };
 
+export declare type SourceBearingTemporalField = SemaphorFieldRef & {
+    source: SemaphorSourceRef;
+};
+
+export declare const TEMPORAL_CONTEXT_ADAPTER_PARITY_FIXTURES: {
+    readonly visibleAxis: {
+        readonly source: {
+            kind: "semantic";
+            domainId: string;
+            datasetName: string;
+        };
+        readonly field: {
+            readonly name: "order_date";
+            readonly label: "Order date";
+            readonly dataType: "timestamp with time zone";
+        };
+        readonly expected: {
+            readonly status: "resolved";
+            readonly bindingSource: "visible_axis";
+            readonly name: "order_date";
+            readonly dataType: "datetime";
+        };
+    };
+    readonly invalidSource: {
+        readonly source: {
+            readonly kind: "semantic";
+            readonly datasetName: "orders";
+        };
+        readonly field: {
+            readonly name: "order_date";
+            readonly label: "Order date";
+            readonly dataType: "date";
+        };
+        readonly expected: {
+            readonly status: "unavailable";
+            readonly reason: "temporal_binding_invalid";
+        };
+    };
+};
+
+export declare type TemporalBindingCandidate = {
+    kind: 'visible_axis' | 'explicit_hidden' | 'semantic_primary';
+    field: SourceBearingTemporalField;
+};
+
+export declare type TemporalRangeCandidate = {
+    id: string;
+    source: 'global_date' | 'card';
+    field: SourceBearingTemporalField;
+    window: ResolvedDateWindow;
+};
+
+export declare function validateComparisonPresentationSpec(value: unknown, path?: string): SemaphorValidationResult;
+
+export declare function validateGlobalDateComparisonContext(value: unknown, path?: string): SemaphorValidationResult;
+
+export declare function validateGlobalDateComparisonSelection(value: unknown, path?: string): SemaphorValidationResult;
+
+export declare function validateMetricComparisonConfig(value: unknown, path?: string): SemaphorValidationResult;
+
+export declare function validateMetricComparisonPolarity(value: unknown, path?: string): SemaphorValidationResult;
+
+export declare function validateMetricComparisonSpec(value: unknown, path?: string): SemaphorValidationResult;
+
 export declare function validateSemaphorAnalyticsIntent(intent: SemaphorAnalyticsIntent): SemaphorAnalyticsValidationResult;
 
 export declare function validateSemaphorAnalyticsRecoveryPlan(plan: SemaphorAnalyticsRecoveryPlan): SemaphorAnalyticsValidationResult;
@@ -3942,4 +4234,8 @@ export declare function validateSemaphorOperationIntent(intent: SemaphorOperatio
 
 export declare function validateSemaphorResultCalculation(calculation: SemaphorResultCalculation): SemaphorValidationResult;
 
+export declare type ViewerPeriodComparisonSpec = Extract<MetricComparisonSpec, {
+    kind: 'previous_period' | 'previous_year';
+}>;
+
 export { }

package/dist/types/brand-studio.d.ts

@@ -1,4 +1,4 @@
-import { JSX } from 'react/jsx-runtime';
+import { default as default_2 } from 'react';
 
 declare const APPEARANCE_SPEC_VERSION: 1;
 
@@ -101,7 +101,7 @@ export declare type BrandStudioDraft = {
     };
 };
 
-export declare function BrandStudioEditor({ appearance, previewTitle, isLoading, isSaving, error, className, onDraftChange, onSave, onClearConfig, onCancel, }: BrandStudioEditorProps): JSX.Element;
+export declare function BrandStudioEditor({ appearance, previewTitle, isLoading, isSaving, error, className, onDraftChange, onSave, onClearConfig, onCancel, }: BrandStudioEditorProps): default_2.JSX.Element;
 
 export declare type BrandStudioEditorProps = {
     appearance?: AppearanceSpec | null;

package/dist/types/briefings.d.ts

@@ -526,9 +526,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';
@@ -665,6 +662,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;
@@ -957,7 +981,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';
@@ -1449,6 +1472,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;
@@ -1497,9 +1544,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 = {};
@@ -2193,6 +2241,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;
@@ -2265,43 +2318,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;

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

@@ -109,9 +109,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';
@@ -356,7 +353,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';
@@ -791,6 +787,30 @@ declare type MatrixTotals = {
     };
 };
 
+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;
@@ -839,9 +859,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 Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'like' | 'not like' | 'in' | 'not in' | 'between' | 'not between' | 'isNull' | 'isNotNull';