react-semaphor 0.1.444 → 0.1.445

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

@@ -24,6 +24,8 @@ export declare function applyDashboardChangePlan(input: {
     cardArtifacts: GeneratedDashboardCardArtifact[];
 }): DashboardChangeCompileResult;
 
+export declare const AUTOMATIC_TEMPORAL_BUCKET_FORMAT: TemporalBucketFormat;
+
 declare type AxisConfig = {
     enabled?: boolean;
     name?: {
@@ -70,6 +72,8 @@ declare type BaseFilter = {
     dataType?: string;
     fieldMeta?: FilterFieldMeta;
     semanticContext?: FilterSemanticContext;
+    /** Governed meaning for canonical grouped-temporal filter values. */
+    temporalBucket?: TemporalBucketMetadata;
 };
 
 declare type Breakpoint = 'lg' | 'md' | 'sm' | 'xs' | 'xxs';
@@ -127,6 +131,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
@@ -188,9 +201,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;
@@ -552,7 +562,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;
     };
 };
@@ -1327,8 +1340,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;
@@ -1370,6 +1384,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;
 }
@@ -1413,6 +1433,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 & {
@@ -1575,7 +1599,7 @@ declare type FormatSpec = {
     type: 'string';
     prefix?: string;
     suffix?: string;
-};
+} | TemporalBucketFormat;
 
 export declare type GeneratedDashboardCardArtifact = {
     planCardId: string;
@@ -1587,6 +1611,10 @@ export declare type GeneratedDashboardCardArtifact = {
 
 export declare function getDashboardAuthoringCardSource(card: Pick<DashboardPlanCard, 'analyticsIntent'>): SemaphorSourceRef | undefined;
 
+export declare function getTemporalBucketAuthoringOptions(granularity: SemaphorTimeGrain, preservedFormat?: TemporalBucketFormat): readonly TemporalBucketAuthoringOption[];
+
+export declare function getTemporalBucketAuthoringSelection(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): TemporalBucketAuthoringSelection;
+
 declare type GlobalDateComparisonSelection = {
     mode: 'off';
 } | {
@@ -1594,7 +1622,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';
@@ -1605,6 +1633,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.
@@ -1693,6 +1726,8 @@ declare interface InteractionTrigger {
 
 export declare function isMaterializableDashboardAuthoringSource(value: unknown): value is MaterializableDashboardAuthoringSource;
 
+export declare function isSemaphorCartesianChartType(value: string | null | undefined): value is SemaphorCartesianChartType;
+
 export declare function isSemaphorSourceRef(value: unknown): value is SemaphorSourceRef;
 
 declare interface Join {
@@ -1826,6 +1861,11 @@ declare interface MetricField extends Field {
     semanticComparisonPolarity?: MetricComparisonPolarity;
 }
 
+declare type MonthAlignedFiscalCalendar = {
+    kind: 'month_aligned';
+    yearStartMonth: number;
+};
+
 declare type NoneOptions = {};
 
 declare type NumberAxisFormat = {
@@ -1902,12 +1942,19 @@ 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 function preferDashboardAuthoringSourceMetadata(current: SemaphorSourceRef, next: SemaphorSourceRef): SemaphorSourceRef;
 
 export declare function preferredDashboardAuthoringSource(sources: readonly SemaphorSourceRef[]): SemaphorSourceRef | undefined;
 
+export declare function previewTemporalBucketAuthoringFormat(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): string;
+
 declare interface QueryConfig {
     groupByColumns?: GroupByColumn[];
     pivotColumns?: GroupByColumn[];
@@ -1930,6 +1977,8 @@ declare type RangeValue = {
     gt?: string | number;
 };
 
+export declare function reconcileTemporalBucketAuthoringFormat(format: TemporalBucketFormat, granularity: SemaphorTimeGrain): TemporalBucketFormat;
+
 declare type RelativeDateFilter = {
     mode: 'last';
     n: number;
@@ -1961,10 +2010,30 @@ export declare function resolveDashboardAuthoringSource({ explicitSource, field,
     fallbackSources?: readonly SemaphorSourceRef[];
 }): MaterializableDashboardAuthoringSource | undefined;
 
+export declare function resolveTemporalBucketAuthoringFormat(granularity: SemaphorTimeGrain, value: string, customPattern?: string): TemporalBucketFormat;
+
+/**
+ * Selects the only result owner eligible for canonical temporal metadata.
+ * Active SQL or normalized Python always owns the result, even when a card
+ * retains config from a prior authoring mode.
+ */
+export declare function resolveTemporalResultOwner(input: TemporalResultOwnerInput): TemporalResultOwner;
+
 declare type SelectedEntities = SelectedEntity[];
 
 declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
 
+declare type SemanticTemporalPresentation = {
+    granularity: SemaphorTimeGrain;
+    format: TemporalBucketFormat;
+};
+
+export declare const SEMAPHOR_CARTESIAN_CHART_TYPES: readonly ["bar", "horizontalBar", "line", "area", "stackedArea", "combo", "stackedBar", "stackedLine"];
+
+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 SemaphorAbsoluteTimeWindow = {
     kind: 'absolute';
     start: string;
@@ -2006,6 +2075,8 @@ declare type SemaphorAnalyticsValueFilter = SemaphorAnalyticsFilterBase & {
 
 declare type SemaphorAnalyticsValueFilterOperator = Exclude<SemaphorAnalyticsFilterOperator, 'is_null' | 'is_not_null'>;
 
+export declare type SemaphorCartesianChartType = (typeof SEMAPHOR_CARTESIAN_CHART_TYPES)[number];
+
 declare type SemaphorDashboardIntent = {
     version: SemaphorProtocolVersion;
     kind: 'dashboard';
@@ -2051,7 +2122,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -2144,7 +2215,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -2236,6 +2307,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -2271,7 +2344,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -2366,12 +2439,49 @@ declare type SemaphorRelationshipHint = {
 
 declare type SemaphorRelativeTimeWindow = {
     kind?: 'relative';
-    unit: 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+    unit: SemaphorTimeGrain;
     value: number;
     anchor?: 'now' | 'latest_available';
     completeness?: 'include_partial' | 'complete_periods';
 };
 
+declare type SemaphorScalarValueFormat = {
+    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    useGrouping?: boolean;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+    compact?: boolean;
+    scale?: number;
+    currency?: string;
+    percentValueMode?: 'fraction' | 'whole';
+} | {
+    type: 'date' | 'datetime';
+    locale?: string;
+    pattern?: string;
+    relative?: boolean;
+    timezone?: string;
+    sourceTimezone?: string;
+    prefix?: string;
+    suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
+} | {
+    type: 'string';
+    prefix?: string;
+    suffix?: string;
+};
+
 declare type SemaphorSemanticSourceRef = Extract<SemaphorSourceRef, {
     kind: 'semantic';
 }>;
@@ -2417,47 +2527,10 @@ declare type SemaphorSqlIntent = {
     inputs?: SemaphorInputBinding[];
 };
 
-declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+declare type SemaphorTimeGrain = (typeof SEMAPHOR_TIME_GRAINS)[number];
 
 declare type SemaphorTimeWindow = SemaphorRelativeTimeWindow | SemaphorAbsoluteTimeWindow;
 
-declare type SemaphorValueFormat = {
-    type: 'number' | 'currency' | 'percent' | 'percentage' | 'scientific';
-    minimumFractionDigits?: number;
-    maximumFractionDigits?: number;
-    useGrouping?: boolean;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-    compact?: boolean;
-    scale?: number;
-    currency?: string;
-    percentValueMode?: 'fraction' | 'whole';
-} | {
-    type: 'date' | 'datetime';
-    locale?: string;
-    pattern?: string;
-    relative?: boolean;
-    timezone?: string;
-    sourceTimezone?: string;
-    prefix?: string;
-    suffix?: string;
-} | {
-    type: 'duration';
-    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    outputStyle?: 'compact' | 'digital' | 'long';
-    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
-    maxUnits?: number;
-    prefix?: string;
-    suffix?: string;
-    negativeStyle?: 'minus' | 'parentheses';
-} | {
-    type: 'string';
-    prefix?: string;
-    suffix?: string;
-};
-
 declare type SemaphorViewPresentation = {
     kind: 'kpi';
     format?: 'number' | 'currency' | 'percent' | 'duration';
@@ -2539,6 +2612,8 @@ declare type StyleProps = {
 
 declare type SubDayDateUnit = 'minute' | 'hour';
 
+export declare function supportsCanonicalDashboardTemporalResult(value: string | null | undefined): boolean;
+
 declare type TableBaseFormatting = {
     version: TableFormattingVersion;
     tableParts?: Partial<Record<TablePart, TableBaseStyle>>;
@@ -3100,8 +3175,63 @@ 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"];
+
+export declare type TemporalBucketAuthoringOption = {
+    value: string;
+    label: string;
+    format?: TemporalBucketFormat;
+    custom?: true;
+};
+
+export declare type TemporalBucketAuthoringSelection = {
+    value: string;
+    customPattern: string;
+    format: TemporalBucketFormat;
+};
+
+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 TemporalResultOwner = 'config' | 'freeform' | 'none';
+
+export declare type TemporalResultOwnerInput = {
+    /**
+     * Result of the runtime's executable-config validation. The ownership
+     * module deliberately does not reinterpret card-config structure.
+     */
+    hasExecutableConfig: boolean;
+    sql?: string | null;
+    /**
+     * Python after the existing execution normalizer has converted the inert
+     * editor template to an empty string. This module treats non-empty Python as
+     * opaque free-form execution and never parses its contents.
+     */
+    normalizedPython?: string | null;
+};
+
 declare type TextCardInlineFormat = {
     bold?: boolean;
     italic?: boolean;
@@ -3287,7 +3417,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.
@@ -3461,6 +3591,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 {