react-semaphor 0.1.449 → 0.1.453

package/dist/types/briefings.d.ts

@@ -1,7 +1,23 @@
 import { ColumnSizingState } from '@tanstack/react-table';
+import { FontSpec } from 'chart.js';
 
 declare type AggregateFunction = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'MEDIAN' | 'DISTINCT';
 
+declare type AIContext = {
+    selectedEntities: SelectedEntities;
+    fileAttachments?: FileAttachment[];
+};
+
+declare type AIScopeTable = {
+    connectionId: string;
+    connectionType: string;
+    databaseName: string;
+    schemaName: string;
+    tableName: string;
+    datamodelId: string;
+    datamodelName: string;
+};
+
 declare type AxisConfig = {
     enabled?: boolean;
     name?: {
@@ -34,6 +50,24 @@ declare interface BaseColumn {
     table?: string;
 }
 
+declare type BaseCustomCard = {
+    cardId: string;
+    replaceDefault?: boolean;
+};
+
+declare type BaseFilter = {
+    filterId: TFilter['id'];
+    expression?: string;
+    name: string;
+    valueType: 'string' | 'number' | 'date' | 'boolean';
+    connectionType?: 'database' | 'api';
+    dataType?: string;
+    fieldMeta?: FilterFieldMeta;
+    semanticContext?: FilterSemanticContext;
+    /** Governed meaning for canonical grouped-temporal filter values. */
+    temporalBucket?: TemporalBucketMetadata;
+};
+
 export declare const BRIEFING_ARTIFACT_FORMATS: readonly ["markdown", "html"];
 
 export declare const BRIEFING_CONTENT_LIMITS: {
@@ -315,7 +349,6 @@ export declare type BriefingDraft = {
     presentation?: Partial<BriefingPresentation>;
     limits?: BriefingLimits;
     deliveryConfig?: BriefingDeliveryConfig | null;
-    resolvedFormats?: ResolvedPresentationEntry[];
 };
 
 export declare type BriefingEntityPresentation = {
@@ -337,8 +370,7 @@ declare type BriefingFragments = {
 
 export declare type BriefingJobConfig = {
     kind: BriefingKind;
-    reportContext: ReportRuntimeContext;
-    resolvedFormats?: ResolvedPresentationEntry[];
+    presentationExecutionSnapshot: PresentationExecutionSnapshot;
     source: BriefingSource;
     body: BriefingBody;
     attachments: BriefingAttachment[];
@@ -479,14 +511,32 @@ export declare type BriefingWebhookConfig = {
     secretEncrypted?: string;
 };
 
-export declare function buildBriefingJobConfig(input: Omit<Partial<BriefingJobConfig>, 'kind' | 'body' | 'reportContext'> & Pick<BriefingJobConfig, 'body' | 'reportContext'>): BriefingJobConfig;
+export declare function buildBriefingJobConfig(input: Omit<Partial<BriefingJobConfig>, 'kind' | 'body' | 'presentationExecutionSnapshot'> & Pick<BriefingJobConfig, 'body' | 'presentationExecutionSnapshot'>): BriefingJobConfig;
 
 export declare function buildBriefingScheduleExpr(view: BriefingScheduleViewModel): string;
 
 export declare function buildCreateBriefingRequest(draft: BriefingDraft): CreateBriefingRequest;
 
+/**
+ * Captures resolved temporal presentation at a one-time export click or a
+ * recurring-rule save. Targets use stable field IDs; result-column keys are
+ * resolved later from the executing query's authoritative column map.
+ */
+export declare function buildDashboardTemporalSnapshotEntries(input: {
+    dashboard: TDashboard;
+    selections: readonly DashboardTemporalSnapshotSelection[];
+    resolveCardConfig?: (card: TCard) => CardConfig;
+    valueFormatPreferences: ResolvedValueFormatPreferences;
+    calendar: Pick<CalendarContext, 'tz'>;
+}): ResolvedPresentationEntry[];
+
 export declare function buildUpdateBriefingRequest(draft: BriefingDraft): UpdateBriefingRequest;
 
+declare type CacheConfig = {
+    ttl: string;
+    status: 'on' | 'on-refresh' | 'off';
+};
+
 /**
  * Formula metadata for calculated fields (UI-only metadata)
  * This is supplementary runtime/compiler data to help dashboard UI display,
@@ -635,6 +685,24 @@ declare interface CardInteractionConfig {
     drillHierarchies?: DrillHierarchy[];
 }
 
+declare type CardWithContent = BaseCustomCard & {
+    content: React.FC<{
+        card: TCard;
+    }>;
+    footer?: React.FC<{
+        card: TCard;
+    }>;
+};
+
+declare type CardWithFooter = BaseCustomCard & {
+    content?: React.FC<{
+        card: TCard;
+    }>;
+    footer: React.FC<{
+        card: TCard;
+    }>;
+};
+
 declare interface ClickFilterInteraction {
     mode: 'clickFilter';
     /**
@@ -876,6 +944,11 @@ declare type ControlBinding = {
     mapping: Record<string, string>;
 } | CurrencyPresentationBinding;
 
+declare type ControlDashboardInput = DashboardInputBase & {
+    kind: 'control';
+    control: ControlDefinition;
+};
+
 declare type ControlDefinition = {
     id: string;
     label: string;
@@ -939,7 +1012,6 @@ export declare type CreateBriefingRequest = {
     presentation: BriefingPresentation;
     limits?: BriefingLimits;
     deliveryConfig: BriefingDeliveryConfig | null;
-    resolvedFormats?: ResolvedPresentationEntry[];
 };
 
 declare type CurrencyPresentationBinding = {
@@ -959,8 +1031,87 @@ declare type CurrencyPresentationTarget = {
     measureId: string;
 };
 
+declare type CustomCard = CardWithContent | CardWithFooter;
+
+declare type DashboardAIContext = AIContext & {
+    mode?: DashboardAIContextMode;
+};
+
+declare type DashboardAIContextMode = 'auto' | 'fixed';
+
+declare type DashboardInput = FilterDashboardInput | ControlDashboardInput;
+
+declare type DashboardInputBase = {
+    id: string;
+    label: string;
+    variableName: string;
+    description?: string;
+    requiredAtExecution?: boolean;
+    scope: DashboardInputScope;
+    runtimeScope: DashboardInputRuntimeScope;
+    presentation?: DashboardInputPresentation;
+    exports?: DashboardInputExportKey[];
+    compatibility?: DashboardInputCompatibilityMetadata;
+};
+
+declare type DashboardInputCompatibilityMetadata = {
+    source: 'dashboardFilter';
+    filterId: string;
+} | {
+    source: 'dashboardControl';
+    controlId: string;
+} | {
+    source: 'cardInlineFilter';
+    cardId: string;
+    filterId: string;
+} | {
+    source: 'cardControl';
+    cardId: string;
+    controlId: string;
+} | {
+    source: 'documentInput';
+    sheetId: string;
+    inputId: string;
+};
+
 declare type DashboardInputExportKey = 'label' | 'value' | 'start' | 'end' | 'range';
 
+declare type DashboardInputPresentation = {
+    placement?: 'toolbar' | 'card_header' | 'advanced' | 'hidden';
+    widthPx?: number;
+    order?: number;
+};
+
+declare type DashboardInputRuntimeScope = 'shared' | 'perSheet' | 'perCard' | 'perDocumentSection';
+
+declare type DashboardInputScope = {
+    kind: 'allSheets';
+    sheetKinds?: Array<'dashboard' | 'document'>;
+} | {
+    kind: 'sheets';
+    sheetIds: string[];
+} | {
+    kind: 'cards';
+    cardIds: string[];
+} | {
+    kind: 'documentSections';
+    sheetId: string;
+    sectionIds: string[];
+};
+
+declare type DashboardInputSlot = ({
+    status: 'set';
+    value: DashboardInputValue;
+    comparisonSelection?: GlobalDateComparisonSelection;
+}) | ({
+    status: 'cleared';
+    comparisonSelection?: GlobalDateComparisonSelection;
+}) | {
+    status?: never;
+    value?: never;
+    comparisonSelection: GlobalDateComparisonSelection;
+};
+
 declare type DashboardInputTextContent = Array<{
     type: 'text';
     value: string;
@@ -969,6 +1120,21 @@ declare type DashboardInputTextContent = Array<{
     ref: DashboardInputVariableRef;
 }>;
 
+declare type DashboardInputValue = {
+    kind: 'filter';
+    filterValue: TFilterValue;
+} | {
+    kind: 'control';
+    value: unknown;
+};
+
+declare type DashboardInputValues = {
+    shared?: Record<string, DashboardInputSlot>;
+    bySheetId?: Record<string, Record<string, DashboardInputSlot>>;
+    byCardId?: Record<string, Record<string, DashboardInputSlot>>;
+    byDocumentSectionId?: Record<string, Record<string, DashboardInputSlot>>;
+};
+
 declare type DashboardInputVariableRef = {
     source: 'dashboardInput';
     inputId: string;
@@ -982,6 +1148,13 @@ declare type DashboardInputVariableRef = {
     key: 'generatedAt' | 'pageNumber' | 'pageCount';
 };
 
+declare type DashboardTemporalSnapshotSelection = {
+    dashboardId: string;
+    sheetId?: string;
+    cardId?: string;
+    attachmentIndex?: number;
+};
+
 declare interface DatabaseEntityReference {
     connectionId: string;
     connectionType: ConnectionType;
@@ -1056,6 +1229,11 @@ export declare function describeBriefingSchedule(expression: string, timezone: s
  */
 declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
     role: 'detail';
+    /**
+     * Query transport policy for ungrouped temporal values. This marker is
+     * projected into executable config and is never persisted authoring state.
+     */
+    dateValueMode?: 'canonical' | 'formatted';
     dateFormat?: DateFormatValue;
     customFormat?: string;
     /**
@@ -1089,6 +1267,189 @@ declare type Dialect = 'mysql' | 'postgres' | 'bigquery' | 'redshift' | 'snowfla
 
 declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
 
+declare type DocumentChartSection = {
+    id: string;
+    type: 'chart';
+    title?: string;
+    card: TCard;
+    heightPx: number;
+};
+
+declare type DocumentControlInputDefinition = DocumentInputBase & {
+    kind: 'control';
+    control: ControlDefinition;
+    exports?: DocumentInputExportKey[];
+};
+
+declare type DocumentDefinition = {
+    version: 1;
+    page: DocumentPageSetup;
+    runtime?: DocumentRuntimeSettings;
+    inputs?: DocumentInputDefinition[];
+    defaultInputValues?: Record<string, unknown>;
+    header?: DocumentHeaderRegion;
+    footer?: DocumentFooterRegion;
+    sections: DocumentSection[];
+    theme?: DocumentTheme;
+};
+
+declare type DocumentFilterInputDefinition = DocumentInputBase & {
+    kind: 'filter';
+    filter: TFilter;
+    exports?: DocumentInputExportKey[];
+};
+
+declare type DocumentFooterRegion = DocumentRegionBase & {
+    region: 'footer';
+    layout: {
+        type: 'preset';
+        preset: 'mvp_footer';
+    };
+};
+
+declare type DocumentHeaderRegion = DocumentRegionBase & {
+    region: 'header';
+    layout: {
+        type: 'preset';
+        preset: 'mvp_header';
+    };
+};
+
+declare type DocumentImageRegionBlock = DocumentRegionBlockBase & {
+    type: 'image';
+    role?: 'logo';
+    src: string;
+    alt?: string;
+    widthPx?: number;
+};
+
+declare type DocumentInputBase = {
+    id: string;
+    label: string;
+    variableName: string;
+    requiredAtExecution: boolean;
+    documentPlacement?: 'input_bar';
+    description?: string;
+};
+
+declare type DocumentInputDefinition = DocumentFilterInputDefinition | DocumentControlInputDefinition;
+
+declare type DocumentInputExportKey = 'label' | 'value' | 'start' | 'end' | 'range';
+
+declare type DocumentPageBreakSection = {
+    id: string;
+    type: 'page_break';
+};
+
+declare type DocumentPageSetup = {
+    size: 'letter' | 'a4';
+    orientation: 'portrait' | 'landscape';
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+        unit: 'in' | 'mm';
+    };
+};
+
+declare type DocumentRegionBase = {
+    enabled: boolean;
+    heightPx?: number;
+    layout: DocumentRegionLayout;
+    blocks: DocumentRegionBlock[];
+};
+
+declare type DocumentRegionBlock = DocumentTextRegionBlock | DocumentImageRegionBlock;
+
+declare type DocumentRegionBlockBase = {
+    id: string;
+    area?: 'left' | 'center' | 'right' | 'title' | 'metadata' | 'note' | 'pageInfo';
+};
+
+declare type DocumentRegionLayout = {
+    type: 'preset';
+    preset: 'mvp_header' | 'mvp_footer';
+};
+
+declare type DocumentRuntimeSettings = {
+    generatedAtFormat?: string;
+};
+
+declare type DocumentSection = DocumentTextSection | DocumentTableSection | DocumentChartSection | DocumentSpacerSection | DocumentPageBreakSection;
+
+declare type DocumentSpacerSection = {
+    id: string;
+    type: 'spacer';
+    heightPx: number;
+};
+
+declare type DocumentTableSection = {
+    id: string;
+    type: 'table';
+    title?: string;
+    card: TCard;
+    table: {
+        totalsRow?: boolean;
+        columnFormatting?: Record<string, unknown>;
+        repeatHeaderOnPageBreak?: boolean;
+        rowHeightPx?: number;
+    };
+};
+
+declare type DocumentTextContent = DocumentTextNode[];
+
+declare type DocumentTextInlineFormat = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+};
+
+declare type DocumentTextNode = {
+    type: 'text';
+    value: string;
+    format?: DocumentTextInlineFormat;
+} | {
+    type: 'variable';
+    ref: DocumentVariableRef;
+    format?: DocumentTextInlineFormat;
+};
+
+declare type DocumentTextRegionBlock = DocumentRegionBlockBase & {
+    type: 'text';
+    role?: 'title' | 'metadata' | 'note' | 'pageInfo';
+    content: DocumentTextContent;
+    style?: DocumentTextStyle;
+};
+
+declare type DocumentTextSection = {
+    id: string;
+    type: 'text';
+    content: DocumentTextContent;
+    style?: DocumentTextStyle;
+};
+
+declare type DocumentTextStyle = {
+    fontSize?: number;
+    fontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+};
+
+declare type DocumentTheme = {
+    fontFamily?: string;
+    primaryColor?: string;
+};
+
+declare type DocumentVariableRef = {
+    source: 'input';
+    inputId: string;
+    export: DocumentInputExportKey;
+} | {
+    source: 'documentMeta';
+    key: 'generatedAt' | 'pageNumber' | 'pageCount';
+};
+
 declare interface DrillDownInteraction {
     mode: 'drillDown';
     /**
@@ -1228,6 +1589,13 @@ declare interface DynamicDrillInteraction {
     /* Excluded from this release type: drillField */
 }
 
+declare type EmailSettings = {
+    companyName: string;
+    dashboardUrl: string;
+    supportEmail: string;
+    senderTitle: string;
+};
+
 declare type EntityType = 'table' | 'view' | 'materialized view' | 'model' | 'file' | 'dataset' | 'url' | 'upload';
 
 declare interface Field {
@@ -1288,6 +1656,17 @@ declare interface Field {
 
 declare type FieldScope = 'card' | 'sheet' | 'dashboard' | 'domain';
 
+declare type FileAttachment = {
+    id: string;
+    name: string;
+    size: number;
+    type: string;
+    data?: string;
+    url?: string;
+    preview?: string;
+    uploadProgress?: number;
+};
+
 declare interface FileEntityReference extends DatabaseEntityReference {
     id: string;
     type: 'file' | 'url' | 'upload';
@@ -1320,6 +1699,19 @@ declare interface FilterCondition {
     temporalBucket?: TemporalBucketMetadata;
 }
 
+declare type FilterDashboardInput = DashboardInputBase & {
+    kind: 'filter';
+    filter: TFilter;
+};
+
+/**
+ * Display mode for individual filters
+ * - 'canvas': Filter displayed as a draggable card on the dashboard canvas
+ * - 'toolbar': Filter displayed in the compact toolbar
+ * - 'inherit': Use the dashboard's filterLayout.displayMode setting (default)
+ */
+declare type FilterDisplayMode = 'canvas' | 'toolbar' | 'inherit';
+
 declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Partial<Pick<Field, 'id' | 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role' | 'fieldScope'>> & {
     entityName?: Field['entityName'];
     entityType?: string;
@@ -1327,6 +1719,43 @@ declare type FilterFieldMeta = Pick<Field, 'name' | 'qualifiedFieldName'> & Part
     calculatedFormula?: CalculatedFieldFormula;
 };
 
+declare type FilterForBetween = BaseFilter & {
+    operation: 'between' | 'not between';
+    values: [number, number];
+};
+
+declare type FilterForCompare = BaseFilter & {
+    operation: '>' | '<' | '>=' | '<=';
+    values: [number];
+};
+
+declare type FilterForDate = BaseFilter & {
+    operation: 'between' | 'not between' | '=' | '!=' | '>' | '<' | '>=' | '<=';
+    values: [Date | string, Date | string] | [Date | string];
+    relativeMeta?: RelativeDateFilter;
+    temporalPrecision?: TemporalPrecision;
+};
+
+declare type FilterForEqual = BaseFilter & {
+    operation: '=' | '!=';
+    values: [string | number];
+};
+
+declare type FilterForIn = BaseFilter & {
+    operation: 'in' | 'not in';
+    values: (string | number)[];
+};
+
+declare type FilterForNull = BaseFilter & {
+    operation: 'is null' | 'is not null';
+    values: [];
+};
+
+declare type FilterForString = BaseFilter & {
+    operation: 'like' | 'not like';
+    values: [string];
+};
+
 declare interface FilterGroup {
     id: string;
     logicalOperator: LogicalOperator;
@@ -1335,6 +1764,38 @@ declare interface FilterGroup {
     groups: FilterGroup[];
 }
 
+declare type FilterKind = 'field' | 'global-date';
+
+/**
+ * Filter layout settings for controlling how dashboard filters are displayed
+ */
+declare type FilterLayoutSettings = {
+    /**
+     * Display mode for filters
+     * - 'canvas': Filters displayed as draggable/resizable cards on the dashboard canvas (default)
+     * - 'toolbar': Filters displayed in a compact horizontal toolbar below dashboard controls
+     */
+    displayMode?: 'canvas' | 'toolbar';
+    /**
+     * Whether the toolbar should wrap filters to multiple lines
+     * - false: Horizontal scroll when filters overflow (default)
+     * - true: Wrap to multiple lines
+     */
+    toolbarWrap?: boolean;
+    /**
+     * Whether to show a download button in the filter toolbar
+     * Useful when embedding Dashboard component without Surfboard's controls
+     */
+    showDownloadButton?: boolean;
+    /**
+     * Mixed toolbar item order for dashboard-level filter and control chips.
+     * Values use prefixed ids like `filter:<id>` and `control:<id>`.
+     */
+    toolbarItemOrder?: string[];
+};
+
+declare type FilterLocation = 'dashboard' | 'frame' | 'sheet' | undefined;
+
 declare type FilterOnClick = {
     expression?: string;
     columnIndex: number;
@@ -1438,6 +1899,13 @@ export declare function getDefaultBriefingCardAttachmentFormat(input: {
     allowDownload?: boolean;
 }): BriefingAttachmentFormat;
 
+declare type GlobalDateComparisonSelection = {
+    mode: 'off';
+} | {
+    mode: 'period';
+    spec: ViewerPeriodComparisonSpec;
+};
+
 declare type Granularity = SemaphorTimeGrain;
 
 declare interface GroupByColumn extends BaseColumn {
@@ -1804,6 +2272,12 @@ declare interface PivotByField extends Field {
  */
 declare type PivotMemberOrder = 'auto' | 'asc' | 'desc';
 
+declare type PresentationExecutionSnapshot = {
+    version: 1;
+    reportContext: ReportRuntimeContext;
+    resolvedFormats: ResolvedPresentationEntry[];
+};
+
 declare type PresentationScope = {
     dashboardId: string;
     cardId?: string;
@@ -1832,6 +2306,13 @@ declare type RangeValue = {
     gt?: string | number;
 };
 
+declare type RawTemporalPatternDialect = 'semaphor_tokens' | 'date_fns';
+
+declare type RawTemporalPresentationTarget = {
+    kind: 'column';
+    columnKey: string;
+};
+
 declare type RelativeDateFilter = {
     mode: 'last';
     n: number;
@@ -1882,10 +2363,47 @@ declare type ResolvedNumericPresentationEntry = {
     format: NumericCanonicalFormat;
 };
 
-declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry;
+declare type ResolvedPresentationEntry = ResolvedNumericPresentationEntry | ResolvedTemporalBucketPresentationEntry | ResolvedRawTemporalPresentationEntry;
+
+declare type ResolvedRawTemporalFormat = {
+    type: 'raw_temporal';
+    locale: string;
+    calendarTimezone: string;
+    /** Resolved source timezone for timezone-less wall datetimes, when authored. */
+    sourceTimezone?: string;
+    presentation: {
+        mode: 'auto';
+        styles: ResolvedTemporalStyleSet;
+    } | {
+        mode: 'pattern';
+        dialect: RawTemporalPatternDialect;
+        pattern: string;
+    };
+};
+
+declare type ResolvedRawTemporalPresentationEntry = {
+    scope: PresentationScope;
+    target: RawTemporalPresentationTarget;
+    format: ResolvedRawTemporalFormat;
+};
 
-declare type ResolvedTemporalBucketFormat = TemporalBucketFormat & {
+declare type ResolvedTemporalBucketFormat = {
+    type: 'temporal_bucket';
+    locale: string;
+    presentation: {
+        mode: 'auto';
+        styles: ResolvedTemporalStyleSet;
+    };
+} | {
+    type: 'temporal_bucket';
     locale: string;
+    presentation: {
+        mode: 'preset';
+        preset: TemporalBucketPreset;
+    } | {
+        mode: 'pattern';
+        pattern: string;
+    };
 };
 
 declare type ResolvedTemporalBucketPresentationEntry = {
@@ -1894,6 +2412,14 @@ declare type ResolvedTemporalBucketPresentationEntry = {
     format: ResolvedTemporalBucketFormat;
 };
 
+declare type ResolvedTemporalStyleSet = {
+    dateStyle: LocaleStyle;
+    dateTime: {
+        dateStyle: LocaleStyle;
+        timeStyle: LocaleStyle;
+    };
+};
+
 declare type ResolvedValueFormatPreferences = {
     locale: string;
     dateStyle: LocaleStyle;
@@ -2257,6 +2783,47 @@ declare type StructuralFieldSelectorTarget = GroupByField;
 
 declare type StructuralMetricSelectorTarget = MetricField;
 
+/**
+ * Style propeerites for the dashboard
+ */
+declare type StyleProps = {
+    /** Theme for dashboard background */
+    canvasTheme?: 'clear' | 'muted' | string;
+    /** css class for `dashboard-panel` */
+    dashboardPanel?: string;
+    /** css class for `dashboard-tabs-container` */
+    dashboardTabsContainer?: string;
+    /** css class for `dashboard-card` */
+    /** css class for `dashboard-card-container` */
+    dashboardCardContainer?: string;
+    dashboardCard?: string;
+    /** grid-layout config */
+    /**
+     * Border radius for the control inputs such as filter input, tabs, date picker, etc.
+     */
+    controlInputRadius?: number;
+    /**
+     * Border radius for the cards
+     */
+    cardBorderRadius?: number;
+    gridLayout?: {
+        /** css class for `react-grid-layout` */
+        className?: string;
+        margin?: [number, number];
+    };
+    /** chart config */
+    chart?: {
+        /** chart font config */
+        font?: Partial<FontSpec>;
+        dataset?: any;
+        /** chart options */
+        options?: any;
+    };
+    table?: {
+        tableHeaderColor?: string;
+    };
+};
+
 declare type SubDayDateUnit = 'minute' | 'hour';
 
 declare type TableBaseFormatting = {
@@ -2335,6 +2902,22 @@ declare type TableTotalsStylePreferences = {
     borderTopColor?: string;
 };
 
+/**
+ * Target column configuration for multi-field filters.
+ * Allows a single filter to target multiple columns from the SAME table,
+ * with users selecting which column to filter at runtime.
+ *
+ * Note: Cross-table filtering is not supported. All target columns must
+ * be from the same table as the filter's primary table. For cross-table
+ * date filtering, create separate filters or use a shared date dimension.
+ */
+declare type TargetColumn = {
+    /** Column name (e.g., "shipping_date") - must be from the filter's table */
+    column: string;
+    /** Display label shown in the dropdown (e.g., "Shipping Date") */
+    label: string;
+};
+
 /** Global bar style configuration */
 declare type TBarStyleConfig = {
     /** Default border radius for all bars - 0-20 pixels */
@@ -2347,6 +2930,15 @@ declare type TBarStyleConfig = {
     categoryPercentage?: number;
 };
 
+declare type TBaseQuery = {
+    id: string;
+    name: string;
+    connectionId: string;
+    sql: string;
+    context?: string;
+    description?: string;
+};
+
 declare type TBubbleScatterConfig = {
     /**
      * Explicit key for X-axis metric. Falls back to auto-detection.
@@ -2677,6 +3269,34 @@ declare type TCustomFilterPreferences = {
     settings?: Record<string, string | number | boolean>;
 };
 
+declare type TDashboard = {
+    id: string;
+    title?: string;
+    aiContext?: DashboardAIContext;
+    summary?: {
+        enabled?: boolean;
+        position?: 'top' | 'bottom';
+        maxItems?: number;
+    };
+    description?: string;
+    sheets?: TSheet[];
+    calculatedFields?: Field[];
+    style?: TStyle;
+    filters?: TFilter[];
+    customCards?: CustomCard[];
+    baseQueries?: TBaseQuery[];
+    aiScopeTables?: AIScopeTable[];
+    globalStyle?: TStyle;
+    globalCacheConfig?: CacheConfig;
+    emailSettings?: EmailSettings;
+    defaultFilterValues?: TFilterValue[];
+    controls?: ControlDefinition[];
+    defaultControlValues?: Record<string, unknown>;
+    inputs?: DashboardInput[];
+    defaultInputValues?: DashboardInputValues;
+    filterLayout?: FilterLayoutSettings;
+};
+
 declare type TDataLabelsConfig = {
     enabled?: boolean;
     position?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'custom';
@@ -2805,6 +3425,8 @@ declare type TemporalBucketPresentationTarget = {
 
 declare type TemporalBucketPreset = (typeof TEMPORAL_BUCKET_PRESETS)[number];
 
+declare type TemporalPrecision = 'minute';
+
 declare type TextCardInlineFormat = {
     bold?: boolean;
     italic?: boolean;
@@ -2850,6 +3472,61 @@ declare type TextCardRichInline = {
     }>;
 };
 
+declare type TFilter = {
+    kind?: FilterKind;
+    type?: 'single' | 'multiple';
+    uiType?: 'radio' | 'dropdown' | 'tabs';
+    dateSelectionMode?: DateSelectionMode;
+    defaultValues?: (string | number)[];
+    defaultDateFilter?: DefaultDateFilter;
+    sheetId?: string;
+    location?: FilterLocation;
+    hide?: boolean;
+    id: string;
+    /** Alias exposed to document/text variables, for example {{region}}. */
+    variableName?: string;
+    connectionId: string;
+    title: string;
+    column: string;
+    dataType: string;
+    table?: string;
+    database?: string;
+    qualifiedTableName?: string;
+    sql: string;
+    operation: Operation;
+    fieldMeta?: FilterFieldMeta;
+    semanticContext?: FilterSemanticContext;
+    /**
+     * Multi-field filter support: When set, provides multiple column options.
+     * The first column becomes the default. Users can select which column
+     * to filter at runtime via a dropdown in the date picker.
+     * If not set, the single `column` field is used (backward compatible).
+     */
+    targetColumns?: TargetColumn[];
+    searchMode?: 'text' | 'numeric' | 'auto';
+    applyToSheetIds?: string[];
+    excludeSheetIds?: string[];
+    applyToCardIds?: string[];
+    excludeCardIds?: string[];
+    customFilterPreferences?: TCustomFilterPreferences;
+    /** Whether to show the label above the filter (default: true) */
+    showLabel?: boolean;
+    /**
+     * Width in pixels when displayed in toolbar mode.
+     * Defaults vary by filter type (160px for dropdowns, 220px for date ranges, etc.)
+     */
+    toolbarWidth?: number;
+    /**
+     * Display mode for this filter
+     * - 'canvas': Always show as draggable card on canvas
+     * - 'toolbar': Always show in toolbar
+     * - 'inherit': Use dashboard's filterLayout.displayMode setting (default)
+     */
+    displayMode?: FilterDisplayMode;
+};
+
+declare type TFilterValue = FilterForString | FilterForEqual | FilterForCompare | FilterForBetween | FilterForIn | FilterForNull | FilterForDate;
+
 declare type TFormatOptions = {
     type?: 'auto' | 'number' | 'currency' | 'percent' | 'scientific' | 'date' | 'duration';
     decimalPlaces?: number;
@@ -2875,6 +3552,15 @@ declare type TFormatOptions = {
     durationMaxUnits?: number;
 };
 
+declare type TFrame = {
+    id: string;
+    visualId?: string;
+    filterId?: string;
+    cards: TCard[];
+    activeCardId: string;
+    calculatedFields?: Field[];
+};
+
 declare type TFunnelConfig = {
     /**
      * How to calculate percentage in tooltips and data labels.
@@ -2987,6 +3673,27 @@ 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';
 
+declare type TSheet = {
+    id: string;
+    kind?: 'dashboard' | 'document';
+    title?: string;
+    description?: string;
+    layout?: ReactGridLayout.Layout[];
+    layouts?: ReactGridLayout.Layouts;
+    cards?: TCard[];
+    frames?: TFrame[];
+    calculatedFields?: Field[];
+    document?: DocumentDefinition;
+};
+
+/**
+ * Style for the dashboard
+ */
+declare type TStyle = {
+    default: StyleProps;
+    dark?: StyleProps;
+};
+
 declare type TTooltipFormatConfig = {
     formatMode?: 'inherit' | 'override';
     /** @deprecated Use formatMode */
@@ -3031,6 +3738,10 @@ export declare function validateBriefingDraft(draft: unknown): BriefingValidatio
 
 export declare function validateBriefingJobConfig(input: unknown): BriefingValidationResult<BriefingJobConfig>;
 
+declare type ViewerPeriodComparisonSpec = Extract<MetricComparisonSpec, {
+    kind: 'previous_period' | 'previous_year';
+}>;
+
 /**
  * Display mode for visual components - controls which UI elements are shown
  */