react-semaphor 0.1.209 → 0.1.211

package/dist/types/shared.d.ts

@@ -0,0 +1,1762 @@
+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?: {
+        enabled: boolean;
+        text?: string;
+        /** Font size for the axis title */
+        fontSize?: number;
+        /** Font weight for the axis title */
+        fontWeight?: 'normal' | 'bold';
+    };
+    position?: 'auto' | 'top' | 'bottom' | 'left' | 'right';
+    labels?: {
+        enabled: boolean;
+        rotation?: 'auto' | 0 | 45 | 90 | -45 | -90;
+    };
+    formatOptions?: TFormatOptions;
+    scale?: {
+        min?: number | 'auto';
+        max?: number | 'auto';
+        stepSize?: number | 'auto';
+    };
+};
+
+declare interface BaseColumn {
+    id: string;
+    name: string;
+    label?: string;
+    type: ColumnType;
+    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;
+};
+
+declare type CacheConfig = {
+    ttl: string;
+    status: 'on' | 'on-refresh' | 'off';
+};
+
+/**
+ * Formula metadata for calculated fields (UI-only metadata)
+ * This is supplementary data to help the UI display and edit calculated fields.
+ * The `expression` field remains the source of truth for the backend.
+ *
+ * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
+ * Both are generated together from the same dialog inputs, preventing drift.
+ */
+declare interface CalculatedFieldFormula {
+    operation: CalculatedFieldOperation;
+    /**
+     * Array of full MetricField objects used as inputs to the calculated field.
+     *
+     * Storing complete Field objects eliminates the need for runtime lookups and ensures:
+     * - Table alias resolution works with schema-qualified tables (Issue 1)
+     * - All field metadata is available even if the input field isn't selected on the card (Issue 2)
+     * - Aggregate functions, filters, and entity info are preserved
+     *
+     * Each input field contains complete metadata:
+     * - name, entityId, entityName, qualifiedEntityName (for table qualification)
+     * - aggregate (for proper post-aggregation: SUM(sales) / COUNT(orders))
+     * - parameters.filters (for filtered metrics)
+     * - dataType and other properties
+     *
+     * Example: [
+     *   {name: 'sales', aggregate: 'SUM', entityName: 'sales_data', ...},
+     *   {name: 'order_id', aggregate: 'COUNT', entityName: 'sales_data', ...}
+     * ]
+     */
+    inputFields: Array<MetricField | GroupByField>;
+    /**
+     * Constant value used in scale operations (e.g., multiply by 0.15)
+     * Only applicable for 'scale' operation type
+     */
+    constant?: number;
+}
+
+/**
+ * Operations supported for calculated fields
+ */
+declare type CalculatedFieldOperation = 'sum' | 'difference' | 'product' | 'ratio' | 'change' | 'percentage' | 'scale' | 'custom';
+
+declare interface CardConfig {
+    groupByColumns?: GroupByField[];
+    metricColumns?: MetricField[];
+    pivotByColumns?: PivotByField[];
+    sortByColumns?: SortByField[];
+    detailColumns?: DetailField[];
+    /** Preserves non-detail config when switching to detail tables. */
+    detailTableBackup?: DetailTableBackupConfig;
+    filters?: FilterGroup;
+    joinPlan?: JoinPlan;
+    rowLimit?: number;
+    /**
+     * One or more hierarchies that define drillable paths through dimensions.
+     */
+    drillHierarchies?: DrillHierarchy[];
+    /**
+     * Optional list of dimensions allowed for dynamic drill-down across this card.
+     * Used only when drill steps contain `mode: 'dynamicDrill'` or `type: 'dynamic'`.
+     */
+    allowedDrillTargets?: Field[];
+    /**
+     * NOT UOptional preload settings for inline drill previews
+     */
+    inlineDrillPreview?: {
+        enabled: boolean;
+        limit: number;
+        mode: 'lazy' | 'preloaded';
+    };
+    /**
+     * 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';
+    summary?: {
+        enabled?: boolean;
+        showOnCard?: boolean;
+        includeInDashboardSummary?: boolean;
+        breakdownDimensions?: GroupByField[];
+        anomalyEnabled?: boolean;
+    };
+    rowAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        groupLevel: string | 'ALL';
+    }>;
+    columnAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        pivotLevel: string | 'ALL';
+    }>;
+}
+
+declare interface CardInteractionConfig {
+    /**
+     * V2: Unified interactions array.
+     * Each interaction includes a trigger that specifies what element must be clicked.
+     */
+    interactions?: PersistedInteraction[];
+    allowedDrillTargets?: Field[];
+    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';
+    /**
+     * What element must be clicked to trigger this interaction.
+     * Determines both the matching logic and the filtering behavior.
+     *
+     * @migration Optional during migration. Will be required in V2.
+     * Old configs without trigger will apply to any click (legacy behavior).
+     */
+    trigger?: InteractionTrigger;
+    /**
+     * Fields from the chart element that should be used as filters.
+     * e.g., [region, ship_mode] from a stacked bar chart
+     */
+    filterFields: Field[];
+    /**
+     * Should this card visually highlight when clicked?
+     */
+    highlightSelf?: boolean;
+    /**
+     * Cards this filter applies to (inclusive).
+     * If omitted and `excludeCardIds` is also omitted → applies to all cards except self.
+     */
+    applyToCardIds?: string[];
+    /**
+     * Cards to explicitly exclude from receiving this filter.
+     * Takes effect only if `applyToCardIds` is undefined (acts as override).
+     */
+    excludeCardIds?: string[];
+    /**
+     * Optional UI label or tooltip.
+     */
+    label?: string;
+}
+
+declare type ColorConfig = {
+    segments: Record<string, string>;
+};
+
+declare type ColorRange = {
+    start: number;
+    end: number;
+    color: string;
+};
+
+declare interface ColorRange_2 {
+    min: number;
+    max: number;
+    color: string;
+    applyTo: 'cell' | 'row';
+}
+
+declare interface ColumnSettings {
+    type: 'none' | 'text' | 'number' | 'date' | 'badge' | 'link' | 'progress';
+    textAlign: 'left' | 'center' | 'right';
+    width: number;
+    minWidth?: number;
+    maxWidth?: number;
+    textOverflow?: 'ellipsis' | 'wrap' | 'clip';
+    textWrap: 'wrap' | 'nowrap';
+    numberFormat: {
+        style: 'decimal' | 'currency' | 'percent';
+        currency: string;
+        locale: string;
+        minimumFractionDigits: number;
+        maximumFractionDigits: number;
+        showDataBar: boolean;
+        dataBarColor: string;
+        dataBarMinValue?: number;
+        dataBarMaxValue?: number;
+    };
+    dateFormat: {
+        format: string;
+        useCustomFormat: boolean;
+        customFormat: string;
+        useRelativeTime: boolean;
+        timezone?: string;
+        sourceTimezone?: string;
+    };
+    linkFormat: LinkFormat;
+    colorRanges: ColorRange_2[];
+}
+
+declare type ColumnSettingsMap = Record<string, ColumnSettings>;
+
+declare type ColumnType = 'string' | 'number' | 'date';
+
+declare type ConnectionType = 'GoogleSheets' | 'FileUpload' | 'MySQL' | 'MSSQL' | 'PostgreSQL' | 'BigQuery' | 'Redshift' | 'Snowflake' | 'S3' | 'clickhouse' | 'S3Tables' | 'API' | 'none';
+
+declare type CustomCard = CardWithContent | CardWithFooter;
+
+declare interface DatabaseEntityReference {
+    connectionId: string;
+    connectionType: ConnectionType;
+    type: EntityType;
+    dbObjectType?: string;
+    dialect?: Dialect;
+    database?: string;
+    schema?: string;
+    name: string;
+}
+
+declare type DatabaseEntityType = 'table' | 'view' | 'materialized view';
+
+declare interface DataModelEntityReference extends DatabaseEntityReference {
+    type: 'model';
+    id: string;
+    label: string;
+    description: string;
+}
+
+declare interface DataSource {
+    connectionId: string;
+    semanticDomainId?: string;
+    connectionType: string;
+    mode: 'database' | 'upload' | 'url' | 'semanticDomain';
+    dbSelection?: {
+        database: string;
+        schema: string;
+        entityType: DatabaseEntityType;
+    };
+    selectedEntities: SelectedEntities;
+}
+
+declare const DATE_FORMAT_VALUES: readonly ["MM-DD-YYYY", "YYYY-MM-DD", "MM/DD/YYYY", "DD/MM/YYYY", "MMMM DD, YYYY", "MMM DD, YYYY", "DD MMM YYYY", "YYYY-MM-DD HH:mm", "YYYY-MM-DD HH:mm:ss", "YYYY-MM-DD HH:mm Z", "YYYY-MM-DD HH:mm:ss Z", "Week of MMM DD, YYYY", "Week of MMMM DD, YYYY", "YYYY-WW", "MMM YYYY", "MMMM YYYY", "YYYY-MM", "MM/YYYY", "YYYY MMM", "Q1 YYYY", "YYYY Q1", "1st Quarter YYYY", "YYYY-Q1", "Quarter 1, YYYY", "YYYY", "YY", "custom"];
+
+declare type DateFormatValue = (typeof DATE_FORMAT_VALUES)[number];
+
+declare type DateOptions = {
+    locale: string;
+    format: string;
+    options: Intl.DateTimeFormatOptions;
+};
+
+declare type DateSelectionMode = 'range' | 'months';
+
+declare type DateUnit = 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+/**
+ * Field configuration for detail table columns.
+ * Unlike GroupByField, DetailField does not support aggregation or granularity.
+ * Columns are selected and displayed as-is from the database.
+ */
+declare interface DetailField extends Omit<Field, 'role' | 'granularity'> {
+    role: 'detail';
+    dateFormat?: DateFormatValue;
+    customFormat?: string;
+    /**
+     * Optional SQL expression for calculated detail fields.
+     */
+    expression?: string;
+    /**
+     * Formula metadata for calculated fields (used for token qualification).
+     */
+    calculatedFormula?: CalculatedFieldFormula;
+}
+
+declare interface DetailTableBackupConfig {
+    groupByColumns?: GroupByField[];
+    metricColumns?: MetricField[];
+    pivotByColumns?: PivotByField[];
+    sortByColumns?: SortByField[];
+    rowAggregates?: Array<{
+        label?: string;
+        function: AggregateFunction;
+        groupLevel: string | 'ALL';
+    }>;
+    columnAggregates?: Array<{
+        label?: string;
+        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';
+
+declare type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
+
+declare interface DrillDownInteraction {
+    mode: 'drillDown';
+    /**
+     * What element must be clicked to trigger this drill-down.
+     * Optional during configuration, but must be defined before execution.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    hierarchyId?: string;
+    label?: string;
+}
+
+declare interface DrillHierarchy {
+    id: string;
+    label?: string;
+    type: 'static' | 'date';
+    steps: DrillHierarchyStep[];
+    default?: boolean;
+    baseField?: Field;
+}
+
+declare interface DrillHierarchyStep {
+    field: Field;
+    mode: 'drillDown';
+    preferredChartType?: TChartType;
+    breadcrumbLabelTemplate?: string;
+    retainFilters?: boolean;
+    label?: string;
+    linkedInsightId?: string;
+}
+
+declare interface DrillThroughInteraction {
+    mode: 'drillThrough';
+    /**
+     * What element must be clicked to trigger this drill-through.
+     * @migration Optional during migration. Will be required in V2.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    targetDashboardId: string;
+    /**
+     * How to pass context to the target dashboard
+     * @default 'interactionFilters'
+     */
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    label?: string;
+}
+
+declare interface DrillToDetailInteraction {
+    mode: 'drillToDetail';
+    /**
+     * What element must be clicked to trigger this drill to detail.
+     * @migration Optional during migration. Will be required in V2.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    detailFields?: Field[];
+    sortBy?: SortByField[];
+    limit?: number;
+    detailTitle?: string;
+    /**
+     * Target insight ID to navigate to
+     */
+    targetInsightId?: string;
+    /**
+     * How to pass context to the target insight
+     * @default 'interactionFilters'
+     */
+    contextMode?: 'interactionFilters' | 'full' | 'none';
+    /**
+     * How to display the insight
+     * @default 'modal'
+     */
+    displayMode?: 'modal' | 'replace-card';
+    label?: string;
+}
+
+declare interface DrillToURLInteraction {
+    mode: 'drillToURL';
+    /**
+     * What element must be clicked to trigger this URL drill.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    /**
+     * URL template with placeholders (e.g., 'https://example.com/product/{{product_id}}')
+     */
+    urlTemplate: string;
+    /**
+     * List of parameters used in the URL template
+     */
+    parameters: URLParameter[];
+    /**
+     * Whether to URL-encode parameter values
+     * @default true
+     */
+    encodeParameters?: boolean;
+    /**
+     * Custom label for this interaction in the menu
+     */
+    label?: string;
+}
+
+declare interface DrillUpInteraction {
+    mode: 'drillUp';
+    /**
+     * What element must be clicked to trigger this drill-up.
+     * For synthetic drill-up interactions, this is inherited from the original drill-down.
+     */
+    trigger?: InteractionTrigger;
+    /**
+     * The hierarchy ID to reference for display purposes.
+     * Used to show the parent level name in the interaction menu.
+     */
+    hierarchyId?: string;
+    label?: string;
+}
+
+declare interface DynamicDrillInteraction {
+    mode: 'dynamicDrill';
+    /**
+     * What element must be clicked to trigger this dynamic drill menu.
+     * When this trigger fires, user sees a menu of available fields to explore.
+     */
+    trigger?: InteractionTrigger;
+    /**
+     * List of fields available for dynamic exploration.
+     * User can choose which field to drill into at runtime.
+     * Only drillable fields (string, boolean types) should be included.
+     */
+    availableFields: Field[];
+    /**
+     * Optional label for the menu item.
+     * Defaults to "Explore Fields" if not specified.
+     */
+    label?: string;
+    /* 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 {
+    /**
+     * Unique identifier for this field instance (for joins, UI state, etc.).
+     * Should be unique within the context of the query or data model.
+     * Example: 'orders.customer_id', 'expr_12345', etc.
+     */
+    id: string;
+    /**
+     * The physical/source column name in the database or data source.
+     * Used for mapping to the underlying data model and SQL generation (unless overridden by expression).
+     */
+    name: string;
+    /**
+     * Human-friendly, localizable display name for the UI (table headers, chart axes, etc.).
+     */
+    label: string;
+    /**
+     * Unique, stable, machine-friendly reference name for SQL (AS alias), exports, and scripting.
+     * If not provided, should be auto-generated from label or name.
+     */
+    alias?: string;
+    qualifiedFieldName: string;
+    dataType: string;
+    description?: string;
+    qualifiedEntityName?: string;
+    dateFormat?: DateFormatValue;
+    customFormat?: string;
+    granularity?: TimeGranularity;
+    entityId: string;
+    entityName: string;
+    entityType: EntityType;
+    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
+    fieldScope?: FieldScope;
+}
+
+declare type FieldScope = 'card' | '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';
+    label: string;
+    description: string;
+    originalName: string;
+    file?: File;
+    url?: string;
+}
+
+declare interface FilterByColumn extends BaseColumn {
+    role: 'filter';
+    operators?: string[];
+    mode?: 'include' | 'exclude';
+    sql?: string;
+    fetchValues?: boolean;
+    fetchLimit?: number;
+    valueSource?: 'distinct' | 'static' | 'range';
+    staticValues?: string[];
+}
+
+declare interface FilterCondition {
+    id: string;
+    field: Field;
+    operator: Operator;
+    value: FilterValue;
+}
+
+/**
+ * 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, 'qualifiedEntityName' | 'entityId' | 'dataType' | 'role'>> & {
+    entityName?: Field['entityName'];
+    entityType?: string;
+    expression?: string;
+    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, Date];
+    relativeMeta?: RelativeDateFilter;
+};
+
+declare type FilterForEqual = BaseFilter & {
+    operation: '=' | '!=' | 'is null' | 'is not null';
+    values: [string | number];
+};
+
+declare type FilterForIn = BaseFilter & {
+    operation: 'in' | 'not in';
+    values: (string | number)[];
+};
+
+declare type FilterForString = BaseFilter & {
+    operation: 'like' | 'not like';
+    values: [string];
+};
+
+declare interface FilterGroup {
+    id: string;
+    logicalOperator: LogicalOperator;
+    negate: boolean;
+    conditions: FilterCondition[];
+    groups: FilterGroup[];
+}
+
+/**
+ * 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;
+};
+
+declare type FilterLocation = 'dashboard' | 'frame' | 'sheet' | undefined;
+
+declare type FilterOnClick = {
+    expression?: string;
+    columnIndex: number;
+};
+
+declare type FilterSemanticContext = {
+    semanticDomainId?: string;
+    selectedEntities?: unknown[];
+    connectionId?: string;
+    connectionType?: string;
+};
+
+declare type FilterValue = string | number | boolean | Date | null | [number, number] | [string, string] | string[] | number[];
+
+declare type Granularity = 'day' | 'week' | 'month' | 'year';
+
+declare interface GroupByColumn extends BaseColumn {
+    role: 'groupby';
+    granularity?: Granularity;
+    format?: string;
+}
+
+declare interface GroupByField extends Field {
+    role: 'groupby';
+    granularity?: 'day' | 'week' | 'month' | 'quarter' | 'year';
+    /**
+     * 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.
+     */
+    expression?: string;
+    timeDrillPath?: TimeDrillStep[];
+    calculatedFormula?: CalculatedFieldFormula;
+}
+
+declare type HtmlOptions = {
+    html: string;
+};
+
+declare interface InlineDrillInteraction {
+    mode: 'inlineDrill';
+    /**
+     * What element must be clicked to trigger this inline drill.
+     * @migration Optional during migration. Will be required in V2.
+     */
+    trigger?: InteractionTrigger;
+    filterFields: Field[];
+    /**
+     * When to fetch the detailed data
+     * @default 'lazy'
+     */
+    fetchMode?: 'lazy' | 'preloaded';
+    /**
+     * Maximum number of records to show (0 for unlimited)
+     * @default 100
+     */
+    inlineLimit?: number;
+    /**
+     * How to display the detailed records
+     * @default 'table'
+     */
+    displayMode?: 'table' | 'list' | 'cards';
+    /**
+     * Whether to show records in a modal overlay
+     * @default false
+     */
+    showInModal?: boolean;
+    /**
+     * Whether to allow exporting the detailed records
+     * @default true
+     */
+    allowExport?: boolean;
+    label?: string;
+}
+
+/**
+ * Unified Interaction type (V2)
+ * Combines all interaction types into a single union for the new interactions array.
+ */
+declare type Interaction = ClickFilterInteraction | DrillDownInteraction | DrillThroughInteraction | DrillToDetailInteraction | DrillToURLInteraction | InlineDrillInteraction | DrillUpInteraction | DynamicDrillInteraction;
+
+declare interface InteractionTargetOverride {
+    applyToCardIds?: string[] | null;
+    excludeCardIds?: string[] | null;
+}
+
+/**
+ * Defines what element must be clicked to trigger an interaction.
+ *
+ * The `type` determines filtering behavior:
+ * - 'metric': Captures intersection of ALL dimensions (e.g., country='USA' AND state='CA')
+ * - 'attribute': Captures ONLY the clicked dimension (e.g., country='USA')
+ *
+ * Note: `trigger.type` is different from `field.type`:
+ * - trigger.type = filtering behavior ('metric' | 'attribute')
+ * - field.type = data type ('dimension' | 'metric' | 'measure')
+ */
+declare interface InteractionTrigger {
+    /**
+     * Determines filtering behavior when this trigger fires:
+     * - 'metric': Capture intersection of all dimensions
+     * - 'attribute': Capture only this specific dimension
+     */
+    type: 'metric' | 'attribute';
+    /**
+     * The field (metric or attribute) that must be clicked.
+     * For multi-series charts: Use the specific metric Field with unique ID
+     * (e.g., Field with id='count_of_orders')
+     */
+    field: Field;
+}
+
+declare interface Join {
+    id: string;
+    source: DatabaseEntityReference;
+    target: DatabaseEntityReference;
+    joinType: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
+    joinKeyGroups: JoinKeyGroup[];
+    sequence: number;
+}
+
+declare interface JoinKey {
+    id?: string;
+    source: Field;
+    target: Field;
+    operator: string;
+}
+
+declare interface JoinKeyGroup {
+    id: string;
+    operator: string;
+    keys: JoinKey[];
+}
+
+declare interface JoinPlan {
+    baseEntity: DatabaseEntityReference;
+    joins: Join[];
+}
+
+declare interface LinkFormat {
+    urlTemplate: string;
+    labelType: 'value' | 'static' | 'column';
+    staticLabel?: string;
+    labelColumn?: string;
+    openInNewTab: boolean;
+}
+
+declare type LogicalOperator = 'AND' | 'OR';
+
+declare interface MetricColumn extends BaseColumn {
+    role: 'metric';
+    aggregate: AggregateFunction;
+    aliasTemplate?: string;
+}
+
+declare interface MetricField extends Field {
+    role: 'metric';
+    aggregate?: AggregateFunction;
+    /**
+     * Optional SQL expression for the metric (e.g., ship_date - order_date).
+     * If present, used as aggregate(expression) instead of aggregate(name).
+     */
+    expression?: string;
+    /**
+     * Optional parameters for future extensibility (e.g., window functions).
+     * * Example:
+     * {
+     aggregate: "SUM",
+     name: "sales",
+     parameters: {
+     window: "PARTITION BY region ORDER BY date ROWS BETWEEN 1 PRECEDING AND CURRENT ROW"
+     }
+     }
+
+     {
+     aggregate: "COUNT",
+     name: "order_id",
+     parameters: {
+     filter: "status = 'Active'"
+     }
+     }
+     */
+    parameters?: {
+        filters?: FilterGroup;
+    };
+    aliasTemplate?: string;
+    valueAliases?: Record<string, string>;
+    /**
+     * Formula metadata for calculated fields (UI-only metadata)
+     * This is supplementary data to help the UI display and edit calculated fields.
+     * The `expression` field remains the source of truth for the backend.
+     *
+     * IMPORTANT: This metadata is ALWAYS updated atomically with the expression field.
+     * Both are generated together from the same dialog inputs, preventing drift.
+     */
+    calculatedFormula?: CalculatedFieldFormula;
+    comparisonType?: 'none' | 'previous_period' | 'same_period_last_year' | 'start_vs_end' | 'target';
+    comparisonDisplay?: 'column' | 'inline' | 'hover';
+    targetValue?: number;
+}
+
+declare type NoneOptions = {};
+
+/**
+ * Normalizes dashboard layout objects into a canonical structure:
+ * - strips transient react-grid-layout runtime fields
+ * - sorts layout arrays deterministically
+ * - keeps all breakpoints so md/xs-only edits still register as dirty
+ */
+export declare function normalizeDashboardForDirtyCheck(dashboard: TDashboard | null): TDashboard | null;
+
+declare type NumberAxisFormat = {
+    decimalPlaces?: number;
+    suffix?: string;
+    currency?: string;
+    locale?: string;
+};
+
+declare type NumberOptions = {
+    locale: string;
+    currency?: string;
+    options: Intl.NumberFormatOptions;
+    colorRanges?: ColorRange[];
+};
+
+declare type OldFilterValue = string | number | null | (string | number)[] | RangeValue;
+
+declare type Operation = '=' | '>' | '<' | '>=' | '<=' | '!=' | 'in' | 'not in' | 'like' | 'not like' | 'between' | 'not between' | 'is null' | 'is not null';
+
+declare type Operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'not in' | 'between' | 'not between' | 'isNull' | 'isNotNull';
+
+declare type OptionsMap = {
+    number: NumberOptions;
+    string: StringOptions;
+    date: DateOptions;
+    html: HtmlOptions;
+    none: NoneOptions;
+};
+
+declare interface OrderBy {
+    columnId: string;
+    direction: 'asc' | 'desc';
+}
+
+/**
+ * Pagination configuration for table queries
+ */
+declare interface PaginationConfig {
+    page: number;
+    pageSize: number;
+}
+
+declare type PersistedInteraction = Interaction & {
+    id?: string;
+};
+
+declare interface PivotByField extends Field {
+    role: 'pivotby';
+}
+
+declare interface QueryConfig {
+    groupByColumns?: GroupByColumn[];
+    pivotColumns?: GroupByColumn[];
+    metricColumns?: MetricColumn[];
+    filterColumns?: FilterByColumn[];
+    filters?: QueryFilter[];
+    limit?: number;
+    orderBy?: OrderBy[];
+}
+
+declare type QueryFilter = {
+    filterColumnName: string;
+    filterValue: OldFilterValue;
+};
+
+declare type RangeValue = {
+    gte?: string | number;
+    lte?: string | number;
+    lt?: string | number;
+    gt?: string | number;
+};
+
+declare type RelativeDateFilter = {
+    mode: 'last';
+    n: number;
+    unit: DateUnit;
+    complete?: boolean;
+} | {
+    mode: 'this';
+    unit: DateUnit;
+    toDate?: boolean;
+} | {
+    mode: 'previous';
+    unit: DateUnit;
+} | {
+    mode: 'between';
+    unit: DateUnit;
+    from: number;
+    to: number;
+};
+
+declare type SelectedEntities = DatabaseEntityReference[] | DataModelEntityReference[] | FileEntityReference[];
+
+/**
+ * Stable serializer for dashboard dirty checks.
+ * This consolidates normalization + serialization into one call site, so
+ * callers can avoid separate pre-normalization state objects.
+ */
+export declare function serializeDashboardForDirtyCheck(dashboard: TDashboard | null): string;
+
+declare interface SortByField extends Field {
+    role: 'sortby';
+    direction: 'asc' | 'desc';
+}
+
+declare type StateSerializer<T> = (value: T) => string;
+
+declare type StringOptions = {
+    maxLength?: number;
+};
+
+/**
+ * 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 TablePreferences = {
+    columnSettingsMap?: ColumnSettingsMap;
+    selectColumnVisible?: boolean;
+    columnVisibility?: Record<string, boolean>;
+    columnSizing?: ColumnSizingState;
+    pageSize?: number;
+    enableDevModePagination?: boolean;
+    forceClientPagination?: boolean;
+};
+
+/**
+ * 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 */
+    borderRadius?: number;
+    /** Default border width for all bars - 0-5 pixels */
+    borderWidth?: number;
+    /** Default bar width as percentage of category width (0.1-1.0) */
+    barPercentage?: number;
+    /** Default category width as percentage of available space (0.1-1.0) */
+    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.
+     */
+    xMetricKey?: string;
+    /**
+     * Explicit key for Y-axis metric. Falls back to auto-detection.
+     */
+    yMetricKey?: string;
+    /**
+     * Explicit key for radius metric (bubble only). Falls back to auto-detection.
+     */
+    radiusMetricKey?: string;
+    /**
+     * Key for point labels (first dimension).
+     */
+    labelKey?: string;
+    /**
+     * Whether to group points into series. Defaults to auto-detect in card config mode.
+     */
+    enableGrouping?: boolean;
+    /**
+     * Key for series grouping. Can be any data type (string, number, date).
+     */
+    groupKey?: string;
+    /**
+     * Scaling mode for bubble radius.
+     */
+    radiusScale?: 'linear' | 'sqrt' | 'fixed';
+    /**
+     * Fixed radius value when radiusScale is 'fixed' or for scatter charts.
+     */
+    fixedRadius?: number;
+    /**
+     * Minimum radius for bubble scaling.
+     */
+    minRadius?: number;
+    /**
+     * Maximum radius for bubble scaling.
+     */
+    maxRadius?: number;
+};
+
+declare type TBulletConfig = {
+    /**
+     * Orientation of the bullet chart. Defaults to horizontal.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Explicit metric key to use for target markers. Falls back to the next metric column.
+     */
+    targetMetricKey?: string;
+    /**
+     * Optional comparative metric (e.g., previous period).
+     */
+    comparativeMetricKey?: string;
+    /**
+     * When true, disables automatic comparative assignment even if a metric exists.
+     */
+    disableAutoComparative?: boolean;
+    /**
+     * Mapping of qualitative range names to column keys.
+     */
+    rangeKeys?: TBulletRangeKeys;
+    /**
+     * Static range values if columns are not provided.
+     */
+    ranges?: TBulletRangeValues;
+    /**
+     * Global target value if a column is not provided.
+     */
+    targetValue?: number;
+    /**
+     * Show numeric labels on the actual bar. Default true.
+     */
+    showValueLabels?: boolean;
+    /**
+     * Treat provided range values as percentages (0-1) when true.
+     */
+    rangesArePercentages?: boolean;
+    /**
+     * Whether qualitative ranges should be rendered.
+     */
+    showRanges?: boolean;
+    /**
+     * Display labels for qualitative ranges.
+     */
+    rangeLabels?: TBulletRangeLabelOverrides;
+};
+
+declare type TBulletRangeKeys = Partial<Record<TBulletRangeLabels, string>>;
+
+declare type TBulletRangeLabelOverrides = Partial<Record<TBulletRangeLabels, string>>;
+
+declare type TBulletRangeLabels = 'poor' | 'satisfactory' | 'good';
+
+declare type TBulletRangeValues = Partial<Record<TBulletRangeLabels, number>>;
+
+declare type TCard = {
+    id: string;
+    title: string;
+    tabTitle?: string;
+    displayTab?: boolean;
+    description?: string;
+    info?: string;
+    connectionId?: string;
+    datamodelId?: string;
+    type: TChartType;
+    sql?: string;
+    python?: string;
+    dataSource?: DataSource;
+    config?: CardConfig;
+    interactionConfig?: CardInteractionConfig;
+    linkedSourceCardId?: string;
+    linkedInteractionTargetOverrides?: Record<string, InteractionTargetOverride>;
+    paginationConfig?: PaginationConfig;
+    queryConfig?: QueryConfig;
+    customCfg?: any;
+    preferences?: TCardPreferences;
+    customCardPreferences?: TCustomCardPreferences;
+    lastSelectedDatabase?: string;
+    lastSelectedDatamodelId?: string;
+    lastSelectedSchema?: string;
+    lastSelectedTable?: string;
+    refreshInterval?: string;
+    /**
+     * Card-specific display preferences that override dashboard-level preferences.
+     * If not specified, the card will use the dashboard's display preferences.
+     */
+    displayPreferences?: VisualDisplayPreferences;
+    /**
+     * Inline filter definitions for this card.
+     * Configured by editors via the visual editor settings.
+     */
+    inlineFilters?: TInlineFilter[];
+};
+
+declare type TCardPreferences = {
+    onClickFilter?: FilterOnClick[];
+    filterOnClick?: boolean;
+    filterOnClickField?: string;
+    filterOnClickColumnIndex?: number;
+    sortChart?: 'asc' | 'desc' | 'none';
+    formatNumber?: {
+        decimalPlaces?: number;
+        currency?: string;
+        locale?: string;
+        suffix?: string;
+        enabled?: boolean | string;
+        colorRanges?: ColorRange[];
+    };
+    numberAxisFormat?: NumberAxisFormat;
+    datasetOptions?: TDatasetOptions[];
+    chartOptions?: TChartOptions;
+    columnSettings?: TColumnSetting<DisplayDataType>[];
+    colorConfig?: ColorConfig;
+    xAxisConfig?: AxisConfig;
+    yAxisConfig?: AxisConfig;
+    secondaryYAxisConfig?: AxisConfig;
+    dataLabelsConfig?: TDataLabelsConfig;
+    bulletConfig?: TBulletConfig;
+    heatmapConfig?: THeatmapConfig;
+    bubbleScatterConfig?: TBubbleScatterConfig;
+    funnelConfig?: TFunnelConfig;
+    /** Global line/point style defaults for line and area charts */
+    lineStyleConfig?: {
+        lineStyle?: TLineStyle;
+        pointRadius?: number;
+        pointStyle?: TPointStyle;
+    };
+    /** Global bar style defaults for bar charts */
+    barStyleConfig?: TBarStyleConfig;
+    tablePrefs?: TablePreferences;
+    allowDownload?: boolean;
+    customVisualCode?: string;
+    textVisualOptions?: {
+        isDynamicText?: boolean;
+    };
+    mapVisualOptions?: {
+        topoJsonUrl?: string;
+        objectKey?: string;
+        outlineKey?: string;
+        customTopoJsonUrl?: string;
+        projection?: string;
+        projectionScale?: number;
+        projectionOffset?: [number, number];
+        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;
+        };
+    };
+    pivotTableOptions?: {
+        showRowTotals?: boolean;
+        showColumnTotals?: boolean;
+        showGrandTotal?: boolean;
+        sortRowsBy?: 'label' | 'total' | 'metric';
+        sortColumnsBy?: 'label' | 'total' | 'metric';
+    };
+    displayOptions?: {
+        showFilterInfo?: boolean;
+        showCardToolbar?: boolean;
+        showChrome?: boolean;
+        allowScroll?: boolean;
+        showInlineFilterBar?: boolean;
+    };
+};
+
+declare type TChartOptions = {
+    type?: TChartType;
+    scales?: {
+        y?: {
+            type?: 'linear' | 'logarithmic';
+            min?: number;
+            max?: number;
+            ticks?: {
+                stepSize?: number;
+            };
+            grid?: {
+                display?: boolean;
+            };
+        };
+        x?: {
+            type?: 'linear' | 'logarithmic';
+            min?: number;
+            max?: number;
+            ticks?: {
+                stepSize?: number;
+            };
+            grid?: {
+                display?: boolean;
+            };
+        };
+    };
+    indexAxis?: 'x' | 'y' | undefined;
+    plugins?: {
+        legend?: TLegendOptions;
+        datalabels?: {
+            anchor?: string;
+        };
+    };
+    treemapColorMode?: 'branch' | 'category';
+};
+
+declare type TChartType = 'bar' | 'horizontalBar' | 'line' | 'area' | 'stackedArea' | 'combo' | 'pie' | 'doughnut' | 'radar' | 'polarArea' | 'bubble' | 'scatter' | 'stackedBar' | 'stackedLine' | 'table' | 'pivotTable' | 'aggregateTable' | 'detailTable' | 'tableBuilder' | 'kpi' | 'pyramid' | 'tornado' | 'range' | 'text' | 'map' | 'funnel' | 'bullet' | 'heatmap' | 'treemap' | 'custom';
+
+declare type TColumnSetting<T extends DisplayDataType> = {
+    columnIdx: number;
+    textAlign?: 'left' | 'center' | 'right';
+    width?: number;
+    type: T;
+    options: OptionsMap[T];
+};
+
+declare type TCustomCardPreferences = {
+    showCardHeader?: boolean;
+    url?: string;
+    componentName?: string;
+    icon?: string;
+    pluginChartType?: string;
+    type?: 'iframe' | 'component';
+    visualType?: 'single' | 'multiple';
+    minInputs?: number;
+    maxInputs?: number;
+    slotIndex?: number;
+    settings?: any;
+    slotSettings?: any;
+    /** @deprecated Use position-based data collection. Kept for legacy dashboard support. */
+    dataInputCardIds?: {
+        [key: number]: {
+            cardId: string;
+        };
+    };
+};
+
+declare type TCustomFilterPreferences = {
+    url: string;
+    componentName: string;
+    pluginFilterType?: string;
+    icon?: string;
+    settings?: Record<string, string | number | boolean>;
+};
+
+declare type TDashboard = {
+    id: string;
+    title?: string;
+    aiContext?: AIContext;
+    summary?: {
+        enabled?: boolean;
+        position?: 'top' | 'bottom';
+        maxItems?: number;
+    };
+    description?: string;
+    sheets?: TSheet[];
+    style?: TStyle;
+    filters?: TFilter[];
+    customCards?: CustomCard[];
+    baseQueries?: TBaseQuery[];
+    aiScopeTables?: AIScopeTable[];
+    globalStyle?: TStyle;
+    globalCacheConfig?: CacheConfig;
+    emailSettings?: EmailSettings;
+    defaultFilterValues?: TFilterValue[];
+    filterLayout?: FilterLayoutSettings;
+};
+
+declare type TDataLabelsConfig = {
+    enabled?: boolean;
+    position?: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'auto' | 'custom';
+    anchor?: 'center' | 'start' | 'end';
+    align?: 'center' | 'start' | 'end' | 'top' | 'bottom' | number;
+    display?: 'auto' | boolean;
+    format?: 'auto' | 'number' | 'currency' | 'percent' | 'date' | 'scientific' | 'none';
+    formatOptions?: TFormatOptions;
+    font?: {
+        size?: number;
+        weight?: 'normal' | 'bold';
+    };
+    color?: 'auto' | string;
+    clamp?: boolean;
+    clip?: boolean;
+    rotation?: number;
+    showTotal?: boolean;
+    offset?: number;
+};
+
+declare type TDatasetOptions = {
+    idx: number;
+    type?: 'bar' | 'line';
+    fill?: string | number;
+    /** Y-axis assignment for combo charts: 'y' (primary/left) or 'y2' (secondary/right) */
+    yAxisId?: 'y' | 'y2';
+    /** Per-series data labels configuration - uses full TDataLabelsConfig for feature parity */
+    dataLabels?: TDataLabelsConfig;
+    /** Point radius (size) for line/area charts - 0 hides points */
+    pointRadius?: number;
+    /** Point shape style for line/area charts */
+    pointStyle?: TPointStyle;
+    /** Point radius on hover - defaults to pointRadius + 2 */
+    pointHoverRadius?: number;
+    /** Line dash style for line/area charts */
+    lineStyle?: TLineStyle;
+    /** Border radius (rounded corners) for bar charts - 0-20 pixels */
+    borderRadius?: number;
+    /** Border width for bar charts - 0-5 pixels */
+    barBorderWidth?: number;
+    /** Bar width as percentage of category width (0.1-1.0) */
+    barPercentage?: number;
+    /** Category width as percentage of available space (0.1-1.0) */
+    categoryPercentage?: number;
+    /** @deprecated Use dataLabels instead */
+    datalabels?: {
+        display?: boolean;
+        align?: string;
+        anchor?: string;
+        clamp?: boolean;
+        color?: string;
+    };
+};
+
+declare type TFilter = {
+    type?: 'single' | 'multiple';
+    uiType?: 'radio' | 'dropdown' | 'tabs';
+    dateSelectionMode?: DateSelectionMode;
+    defaultValues?: (string | number)[];
+    defaultDateFilter?: RelativeDateFilter;
+    sheetId?: string;
+    location?: FilterLocation;
+    hide?: boolean;
+    id: 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 | FilterForDate;
+
+declare type TFormatOptions = {
+    type?: 'auto' | 'number' | 'currency' | 'percent' | 'scientific' | 'date';
+    decimalPlaces?: number;
+    currency?: string;
+    locale?: string;
+    prefix?: string;
+    suffix?: string;
+    useSuffix?: boolean;
+    negativeInParentheses?: boolean;
+    multiplyBy?: number;
+    dateFormat?: string;
+};
+
+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.
+     * - 'percentOfTotal': Each stage shows % of total sum (default/current behavior)
+     * - 'percentOfFirst': First stage = 100%, others relative to first
+     */
+    percentMode?: TFunnelPercentMode;
+    /**
+     * Controls how much funnel segments narrow based on their values.
+     * - 0: No shrink (all segments same width)
+     * - 1: Full shrink (segments narrow proportionally to values, default)
+     * Lower values prevent segments from becoming too narrow for labels.
+     */
+    shrinkFraction?: number;
+    /**
+     * Hide labels for segments smaller than this percentage of total.
+     * - 0: Show all labels (default)
+     * - 10: Hide labels for segments < 10% of total
+     * Range: 0-25
+     */
+    labelThreshold?: number;
+};
+
+/**
+ * Tooltip/data label percentage calculation mode for funnel charts.
+ * - 'percentOfTotal': Percentage relative to sum of all values (default)
+ * - 'percentOfFirst': Percentage relative to the first stage value (first stage = 100%)
+ */
+declare type TFunnelPercentMode = 'percentOfTotal' | 'percentOfFirst';
+
+declare type THeatmapConfig = {
+    colorMode?: 'continuous' | 'stepped';
+    steps?: number;
+    colorRange?: [string, string];
+    colorPalette?: 'blue' | 'green' | 'purple' | 'orange' | 'custom';
+    showLegend?: boolean;
+    legendPosition?: 'top' | 'bottom' | 'left' | 'right';
+    showDataLabels?: boolean;
+    nullFillColor?: string;
+    fillMissingCells?: boolean;
+    xAxisBuckets?: string[];
+    yAxisBuckets?: string[];
+};
+
+declare interface TimeDrillStep {
+    granularity: TimeGranularity;
+    next?: TimeGranularity;
+    comparison?: 'previous_year' | 'previous_period';
+    rollingWindow?: number;
+}
+
+declare type TimeGranularity = 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+/**
+ * Inline filter definition stored on a card.
+ * Inline filters appear on the right-hand side of the card header,
+ * allowing ad-hoc data exploration without affecting other cards.
+ */
+declare type TInlineFilter = {
+    id: string;
+    column: string;
+    title: string;
+    dataType: string;
+    table: string;
+    database: string;
+    connectionId: string;
+    operation: Operation;
+    sql: string;
+    fieldMeta?: FilterFieldMeta;
+    semanticContext?: FilterSemanticContext;
+    /** Selection type: 'single' allows one value, 'multiple' allows many */
+    type?: 'single' | 'multiple';
+    /** UI component for single-select filters */
+    uiType?: 'radio' | 'dropdown' | 'tabs';
+    /** Date picker type: 'range' for full calendar, 'months' for month picker */
+    dateSelectionMode?: DateSelectionMode;
+    /** Default values applied when the dashboard first loads */
+    defaultValues?: (string | number)[];
+    /** Default relative date filter (e.g., "Last 7 days") applied on dashboard load */
+    defaultDateFilter?: RelativeDateFilter;
+    /** Search mode for numeric filters: 'text' treats as text, 'numeric' enables operators (>, <, =) */
+    searchMode?: 'text' | 'numeric' | 'auto';
+    /** Custom filter UI from a plugin */
+    customFilterPreferences?: TCustomFilterPreferences;
+    /** Width of the inline filter in pixels (default: 250) */
+    width?: number;
+    /** Whether to show the label above the filter (default: true) */
+    showLabel?: boolean;
+};
+
+declare type TLegendOptions = {
+    display?: boolean;
+    position?: 'top' | 'left' | 'bottom' | 'right';
+    align?: 'start' | 'center' | 'end';
+    labels?: {
+        generateLabels?: (chart: any) => any[];
+        [key: string]: any;
+    };
+};
+
+/** Line dash style options */
+declare type TLineStyle = 'solid' | 'dashed' | 'dotted' | 'dash-dot';
+
+/** 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;
+    title?: string;
+    description?: string;
+    layout?: ReactGridLayout.Layout[];
+    layouts?: ReactGridLayout.Layouts;
+    cards?: TCard[];
+    frames?: TFrame[];
+};
+
+/**
+ * Style for the dashboard
+ */
+declare type TStyle = {
+    default: StyleProps;
+    dark?: StyleProps;
+};
+
+/**
+ * URL Parameter for drill-to-URL interpolation
+ * Represents a placeholder in the URL template (e.g., {{product_id}})
+ */
+declare interface URLParameter {
+    /**
+     * Unique identifier for the parameter (e.g., 'product_id', 'card_id')
+     * Used in template as {{id}}
+     */
+    id: string;
+    /**
+     * Display label for the parameter
+     */
+    label: string;
+    /**
+     * Category of the parameter
+     * - attribute: From card dimensions/attributes (e.g., product name, region)
+     * - identifier: System values (card_id, frame_id, sheet_id)
+     */
+    category: 'attribute' | 'identifier';
+    /**
+     * For attribute parameters: the complete field object
+     * Provides access to all field properties (name, qualifiedFieldName, dataType, etc.)
+     */
+    field?: Field;
+}
+
+/**
+ * Efficiently checks if current state differs from pristine state
+ * using debouncing and requestIdleCallback to avoid blocking the main thread.
+ *
+ * @param currentState - The current state to compare
+ * @param pristineState - The original state to compare against (null if not tracking)
+ * @param debounceMs - Milliseconds to wait after last change (default: 300)
+ * @param idleTimeout - Max ms to wait for idle time (default: 1000)
+ * @returns Object with isDirty boolean and resetDirty function to immediately clear dirty state
+ */
+export declare function useDebouncedDirtyCheck<T>(currentState: T, pristineState: T | null, debounceMs?: number, idleTimeout?: number, serializeState?: StateSerializer<T>): {
+    isDirty: boolean;
+    isDirtyPending: boolean;
+    resetDirty: () => void;
+};
+
+/**
+ * Display mode for visual components - controls which UI elements are shown
+ */
+declare type VisualDisplayMode = 'full' | 'print' | 'table-print';
+
+/**
+ * Display preferences for controlling visual component rendering
+ */
+declare type VisualDisplayPreferences = {
+    /**
+     * Predefined display mode
+     * - 'full': All UI elements (default)
+     * - 'print': Optimized for printing (shows title and description, hides interactive elements)
+     * - 'table-print': Table-specific print mode (title only, no pagination/toolbar)
+     */
+    mode?: VisualDisplayMode;
+    /**
+     * Override specific UI elements visibility
+     * These overrides take precedence over the mode presets
+     */
+    overrides?: {
+        showHeader?: boolean;
+        showTitle?: boolean;
+        showDescription?: boolean;
+        showTabs?: boolean;
+        showFooter?: boolean;
+        showFilters?: boolean;
+        showBreadcrumbs?: boolean;
+        showRefreshIndicator?: boolean;
+        showFilterInfo?: boolean;
+        showPagination?: boolean;
+        showTableToolbar?: boolean;
+        showColumnSettings?: boolean;
+    };
+};
+
+export { }