react-semaphor 0.1.443 → 0.1.445

package/dist/types/briefings.d.ts

@@ -315,6 +315,7 @@ export declare type BriefingDraft = {
     presentation?: Partial<BriefingPresentation>;
     limits?: BriefingLimits;
     deliveryConfig?: BriefingDeliveryConfig | null;
+    resolvedFormats?: ResolvedPresentationEntry[];
 };
 
 export declare type BriefingEntityPresentation = {
@@ -337,6 +338,7 @@ declare type BriefingFragments = {
 export declare type BriefingJobConfig = {
     kind: BriefingKind;
     reportContext: ReportRuntimeContext;
+    resolvedFormats?: ResolvedPresentationEntry[];
     source: BriefingSource;
     body: BriefingBody;
     attachments: BriefingAttachment[];
@@ -605,9 +607,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;
@@ -901,7 +900,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;
     };
 };
@@ -937,6 +939,7 @@ export declare type CreateBriefingRequest = {
     presentation: BriefingPresentation;
     limits?: BriefingLimits;
     deliveryConfig: BriefingDeliveryConfig | null;
+    resolvedFormats?: ResolvedPresentationEntry[];
 };
 
 declare type CurrencyPresentationBinding = {
@@ -1229,8 +1232,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;
@@ -1272,6 +1276,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;
 }
@@ -1304,6 +1314,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 FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
@@ -1389,7 +1403,7 @@ declare type FormatSpec = {
     type: 'string';
     prefix?: string;
     suffix?: string;
-};
+} | TemporalBucketFormat;
 
 export declare function getBriefingCardAttachmentCapability(card: TCard): BriefingCardAttachmentCapability;
 
@@ -1424,7 +1438,7 @@ export declare function getDefaultBriefingCardAttachmentFormat(input: {
     allowDownload?: boolean;
 }): BriefingAttachmentFormat;
 
-declare type Granularity = 'day' | 'week' | 'month' | 'quarter' | 'year' | 'hour' | 'minute' | 'second';
+declare type Granularity = SemaphorTimeGrain;
 
 declare interface GroupByColumn extends BaseColumn {
     role: 'groupby';
@@ -1435,6 +1449,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.
@@ -1691,15 +1710,6 @@ declare type NumberOptions = {
     colorRanges?: ColorRange[];
 };
 
-/**
- * Shared format types for export system
- * IMPORTANT: No React imports allowed in this file
- *
- * These types are used by:
- * - react-semaphor (browser) for client-side exports
- * - semaphor-app (Next.js) for API routes
- * - Lambda (Node.js) for async export processing
- */
 declare type NumericCanonicalFormat = {
     type: 'number' | 'currency' | 'percent' | 'scientific';
     locale?: string;
@@ -1773,8 +1783,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';
 }
 
+declare type PresentationScope = {
+    dashboardId: string;
+    cardId?: string;
+    attachmentIndex?: number;
+};
+
 declare interface QueryConfig {
     groupByColumns?: GroupByColumn[];
     pivotColumns?: GroupByColumn[];
@@ -1841,6 +1862,24 @@ declare type ResolvedCalendarPreferenceSources = {
     weekStart: ReportPreferenceSource;
 };
 
+declare type ResolvedNumericPresentationEntry = {
+    scope: PresentationScope;
+    target: NumericPresentationTarget;
+    format: NumericCanonicalFormat;
+};
+
+declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry;
+
+declare type ResolvedTemporalBucketFormat = TemporalBucketFormat & {
+    locale: string;
+};
+
+declare type ResolvedTemporalBucketPresentationEntry = {
+    scope: PresentationScope;
+    target: TemporalBucketPresentationTarget;
+    format: ResolvedTemporalBucketFormat;
+};
+
 declare type ResolvedValueFormatPreferences = {
     locale: string;
     dateStyle: LocaleStyle;
@@ -1865,6 +1904,15 @@ declare type SelectedEntities = SelectedEntity[];
 
 declare type SelectedEntity = DatabaseEntityReference | DataModelEntityReference | DatasetEntityReference | FileEntityReference;
 
+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;
@@ -1918,7 +1966,7 @@ declare type SemaphorDerivedFieldDefinition = {
     defaultAggregate?: SemaphorAggregateFunction;
     aggregationBehavior?: SemaphorDerivedFieldAggregationBehavior;
     aggregationStrategy?: SemaphorDerivedFieldAggregationStrategy;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     tags?: string[];
 };
 
@@ -1969,7 +2017,7 @@ declare type SemaphorMatrixAxisExpansionOptions = {
 declare type SemaphorMatrixAxisLevel = {
     id?: string;
     field: SemaphorFieldRef;
-    grain?: SemaphorTimeGrain;
+    grain?: SemaphorMatrixTimeGrain;
     label?: string;
     subtotal?: boolean | SemaphorMatrixSubtotalOptions;
     sortBy?: SemaphorMatrixAxisSortRule;
@@ -2061,6 +2109,8 @@ declare type SemaphorMatrixSubtotalOptions = {
     label?: string;
 };
 
+declare type SemaphorMatrixTimeGrain = (typeof SEMAPHOR_MATRIX_TIME_GRAINS)[number];
+
 declare type SemaphorMatrixTotalCalculation = {
     kind: 'defaultAggregate';
 } | {
@@ -2096,7 +2146,7 @@ declare type SemaphorMatrixValueField = {
     field: SemaphorFieldRef;
     aggregate?: SemaphorAggregateFunction;
     label?: string;
-    format?: SemaphorValueFormat;
+    format?: SemaphorScalarValueFormat;
     totalBehavior?: SemaphorMatrixTotalCalculation;
 };
 
@@ -2106,36 +2156,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;
@@ -2172,6 +2193,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';
@@ -2703,6 +2753,44 @@ 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 TemporalBucketPresentationTarget = {
+    kind: 'field';
+    fieldId: string;
+    /** Distinguishes one semantic field used on both pivot axes. */
+    role?: 'groupby' | 'pivotby';
+} | {
+    kind: 'column';
+    columnKey: string;
+} | {
+    kind: 'matrix_axis';
+    axisInstanceId: string;
+};
+
+declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
+
 declare type TextCardInlineFormat = {
     bold?: boolean;
     italic?: boolean;
@@ -2824,7 +2912,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.