react-semaphor 0.1.504 → 0.1.506

package/dist/types/lib/types/common-types.d.ts

@@ -0,0 +1,1621 @@
+import { TFilter, TFilterValue, Operation, TCustomFilterPreferences, DateSelectionMode, DefaultDateFilter, FilterFieldMeta, FilterSemanticContext } from '../../components/surfboard/filter/types.js';
+import { FontSpec } from 'chart.js';
+import { TChartType } from '../charts/types.js';
+import { QueryConfig } from './query-types.js';
+import { TablePreferences } from '../../components/visual/data-table/types/data-table.js';
+import { CalculatedFieldFormula, CardConfig, Field, FormatSpec, AggregateFunction, GroupByField, MetricField, PaginationConfig, DateFormatValue, EntityType, TimeGranularity, DataSource } from './explorer-types.js';
+import { ComparisonPresentationSpec, GlobalDateComparisonSelection, MetricComparisonPolarity, SemaphorDerivedFieldDefinition, TemporalBucketFormat } from '../../shared/analytics-protocol/index.js';
+import { DashboardFilterApplication, DashboardFilterOptionSource, DashboardFilterOptionDependencies, DashboardFilterOptionPopulation } from '../../shared/dashboard-authoring/dashboard-filter-mapping-types.js';
+import { DashboardAIContext } from './assistant-types.js';
+import { CardInteractionConfig, InteractionState, InteractionTargetOverride } from './interaction-types.js';
+import { SemanticExecutionPayload } from './semantic-runtime-types.js';
+import { ReportRuntimeContext } from '../../shared/report-runtime-context/index.js';
+import { PresentationExecutionSnapshot } from '../../shared/format-utils/index.js';
+import { JSX } from 'react';
+export type { DashboardFilterApplication, DashboardFilterBoundCardApplication, DashboardFilterCardApplication, DashboardFilterExcludedCardApplication, DashboardFilterTarget, DashboardFilterTargetField, DashboardFilterTargetSource, DashboardFilterOptionSource, } from '../../shared/dashboard-authoring/dashboard-filter-mapping-types.js';
+export type Level = 'database' | 'schema' | 'table';
+export type SelectionState = Record<Level, string | null>;
+export declare const EMPTY_SELECTION: SelectionState;
+export type TDbCapabilities = {
+    path: Level[];
+    labels?: Partial<Record<Level, string>>;
+    prefixLevels: Level[];
+    dialect?: string;
+    supportsFilterClause?: boolean;
+};
+export type TDataColumn = {
+    column_name: string;
+    data_type: string;
+    /** Exact catalog type when the columns API can prove it independently. */
+    nativeDataType?: string;
+    /** @deprecated Use the API contract spelling `nativeDataType`. */
+    native_data_type?: string;
+    /** Whether `data_type` came from semantic metadata or physical introspection. */
+    dataTypeProvenance?: 'semantic' | 'physical';
+    is_nullable?: string;
+    label?: string;
+    description?: string;
+    qualifiedFieldName?: string;
+    qualifiedEntityName?: string;
+    entityId?: string;
+    entityName?: string;
+    entityType?: EntityType;
+    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
+    expression?: string;
+    calculatedFormula?: CalculatedFieldFormula;
+    derivedField?: SemaphorDerivedFieldDefinition;
+    fieldScope?: import('./explorer-types.js').FieldScope;
+    source?: import('./explorer-types.js').Field['source'];
+    calculatedFieldOrigin?: import('./explorer-types.js').Field['calculatedFieldOrigin'];
+    calculationRepresentation?: import('./explorer-types.js').Field['calculationRepresentation'];
+    aggregateOrigin?: import('./explorer-types.js').Field['aggregateOrigin'];
+    labelOrigin?: import('./explorer-types.js').Field['labelOrigin'];
+    formatOrigin?: import('./explorer-types.js').Field['formatOrigin'];
+    format?: FormatSpec;
+    granularity?: TimeGranularity;
+    sourceField?: string;
+    aggregate?: AggregateFunction;
+};
+export type DroppableId = 'droppable-group-by' | 'droppable-metric';
+export type AggregateCalc = 'AVG' | 'MIN' | 'MAX' | 'SUM' | 'COUNT' | 'COUNT_DISTINCT';
+export type SqlGen = {
+    measures?: {
+        name: string;
+        calc: AggregateCalc;
+    }[];
+    dimensions?: string[];
+};
+export type Theme = 'dark' | 'light' | 'system';
+export type LensInputValuesSnapshot = {
+    generatedAt: string;
+    dashboardInputValues: DashboardInputValues;
+};
+export type TLens = {
+    id: string;
+    name: string;
+    template?: string;
+    filterValues?: TFilterValue[] | null;
+    inputValues?: LensInputValuesSnapshot | null;
+    isDefault?: boolean;
+    shared?: boolean;
+};
+export type GetDashboardResponse = {
+    dashboard: TDashboard;
+    initialReportContext: ReportRuntimeContext;
+    lenses: TLens[];
+    filterValues?: TFilterValue[] | null;
+    inputValues?: LensInputValuesSnapshot | null;
+    defaultLensId?: string;
+    assistantProfileId?: string;
+    semanticExecutionPayload: SemanticExecutionPayload;
+    organizationAppearance?: import('../appearance/types.js').AppearanceSpec | null;
+};
+export type PluginType = 'custom' | 'standard';
+export type GetPluginsResponse = {
+    plugins: {
+        label: string;
+        value: string;
+        type: PluginType;
+    }[];
+};
+export type KPICardProps = {
+    card: TCard;
+    isLoading?: boolean;
+    renderFilterInfo?: () => JSX.Element | null;
+};
+export type ExportDataPayload = {
+    cardId: string;
+    title: string;
+    data: Record<string, any>[];
+    sql: string;
+};
+export type DashboardEventHandlers = {
+    onExportData?: (payload: ExportDataPayload) => void;
+};
+export type Placeholders = {
+    /**
+     * Placeholder for the card when there are no records to display.
+     */
+    NoRecords?: React.ReactNode;
+    /**
+     * Placeholder for session expired. This is shown when the session has expired.
+     */
+    SessionExpired?: React.ReactNode;
+};
+/**
+ * Display mode for visual components - controls which UI elements are shown
+ */
+export type VisualDisplayMode = 'full' | 'print' | 'table-print';
+/**
+ * Display preferences for controlling visual component rendering
+ */
+export 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;
+    };
+};
+/**
+ * Filter layout settings for controlling how dashboard filters are displayed
+ */
+export 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[];
+};
+/**
+ * Unified dashboard preferences for both card display and UI modes
+ */
+export type DashboardPreferences = {
+    /**
+     * Visual display preferences for cards
+     * Controls how card content is rendered (headers, footers, etc.)
+     */
+    cardDisplay?: VisualDisplayPreferences;
+    /**
+     * UI modes for developer and debug features
+     * Controls what developer tools and debug panels are available
+     */
+    uiMode?: {
+        /**
+         * Enable developer mode
+         * Shows additional controls and debug information
+         */
+        developer?: boolean;
+        /**
+         * Enable console mode
+         * Shows console panel for debugging
+         */
+        console?: boolean;
+        /**
+         * Offer non-persistent inspection when the current actor cannot edit.
+         * This is not an authorization grant.
+         */
+        inspection?: boolean;
+    };
+};
+export type DashboardProps = {
+    id?: string;
+    /**
+     * Auth token for the dashboard. Auth token grants access to the dashboard.
+     */
+    authToken: AuthToken | undefined;
+    /**
+     * Default filter values for the dashboard. The dashboard will be filtered by these values when the user loads the dashboard.
+     */
+    defaultFilterValues?: TFilterValue[];
+    /**
+     * Default runtime control values for the dashboard. Used by print/render flows
+     * and other external entry points that need deterministic control state.
+     */
+    defaultControlValues?: Record<string, unknown>;
+    /**
+     * Optional control contract override used by print/replay entry points that
+     * need to execute against a saved card/dashboard control contract snapshot.
+     */
+    controlContractOverrides?: {
+        controlDefinitions?: ControlDefinition[];
+        cardControlDefinitions?: ControlDefinition[];
+        controlBindings?: ControlBinding[];
+    };
+    /**
+     * Document-local runtime values for print/render entry points. Values are
+     * keyed by document input id and are intentionally separate from dashboard
+     * filters/controls.
+     *
+     * @deprecated Use dashboardInputExecutionSnapshot for document print/export
+     * entry points backed by DashboardInput.
+     */
+    documentInputValues?: DocumentInputRuntimeValues;
+    /**
+     * Authoritative dashboard input runtime snapshot for print/render entry
+     * points. Document print/export should use this for DashboardInput-backed
+     * inputs instead of documentInputValues.
+     */
+    dashboardInputExecutionSnapshot?: DashboardInputExecutionSnapshot;
+    /**
+     * Runtime interaction state captured for deterministic print/replay entry
+     * points. Ordinary dashboard consumers should leave this unset.
+     */
+    interactionExecutionSnapshot?: Record<string, InteractionState>;
+    /** Server-resolved immutable presentation snapshot for internal print views. */
+    presentationExecutionSnapshot?: PresentationExecutionSnapshot;
+    /**
+     * Render target for print entry points. Generic dashboard PDF exports also
+     * use cardDisplay.mode="print"; document-specific print handling must only
+     * run when this is explicitly "document".
+     */
+    renderMode?: 'dashboard' | 'document';
+    customStyle?: TStyle;
+    appearance?: import('../appearance/types.js').AppearanceSpec;
+    currentTheme?: Theme;
+    version?: string;
+    showAssistant?: boolean;
+    showBriefings?: boolean;
+    customCards?: CustomCard[];
+    onChartElementClicked?: (card: TCard, fieldValues: any) => void;
+    onEvent?: (event: TEvent) => void;
+    /** Receives dashboard editing lifecycle transitions from the shared runtime. */
+    onDashboardLifecycleEvent?: (event: DashboardLifecycleEvent) => void;
+    onSave?: (dashboard: TDashboard) => void;
+    onFilterValuesChange?: (filterValues: TFilterValue[]) => void;
+    LoadingComponent?: (props: LoadingProps) => React.ReactNode;
+    ErrorComponent?: (props: ErrorProps) => React.ReactNode;
+    eventHandlers?: DashboardEventHandlers;
+    /**
+     * Placeholders for the dashboard.
+     */
+    placeholders?: Placeholders;
+    /**
+     * The id of the sheet to be selected when the dashboard is loaded.
+     */
+    selectedSheetId?: string;
+    /**
+     * Unified preferences for dashboard configuration
+     * Includes both card display preferences and UI mode settings
+     */
+    preferences?: DashboardPreferences;
+};
+export type DocumentInputRuntimeValues = {
+    sheetId?: string;
+    filterValuesByInputId?: Record<string, TFilterValue | undefined>;
+    controlValuesByInputId?: Record<string, unknown>;
+    generatedAt?: string;
+};
+export type AuthToken = {
+    accessToken: string;
+    refreshToken?: string;
+};
+export type Breakpoint = 'lg' | 'md' | 'sm' | 'xs' | 'xxs';
+type FilterOnClick = {
+    expression?: string;
+    columnIndex: number;
+};
+type StringOptions = {
+    maxLength?: number;
+};
+type NoneOptions = {};
+export type NumberOptions = {
+    locale: string;
+    currency?: string;
+    options: Intl.NumberFormatOptions;
+    colorRanges?: ColorRange[];
+};
+export type DateOptions = {
+    locale: string;
+    format: string;
+    options: Intl.DateTimeFormatOptions;
+};
+export type HtmlOptions = {
+    html: string;
+};
+export type DisplayDataType = 'string' | 'date' | 'number' | 'html' | 'none';
+type OptionsMap = {
+    number: NumberOptions;
+    string: StringOptions;
+    date: DateOptions;
+    html: HtmlOptions;
+    none: NoneOptions;
+};
+export type TColumnSetting<T extends DisplayDataType> = {
+    columnIdx: number;
+    textAlign?: 'left' | 'center' | 'right';
+    width?: number;
+    type: T;
+    options: OptionsMap[T];
+};
+/** Point style options supported by Chart.js */
+export type TPointStyle = 'circle' | 'cross' | 'crossRot' | 'dash' | 'line' | 'rect' | 'rectRounded' | 'rectRot' | 'star' | 'triangle';
+/** Line dash style options */
+export type TLineStyle = 'solid' | 'dashed' | 'dotted' | 'dash-dot';
+export 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;
+    };
+};
+/** Global bar style configuration */
+export 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;
+};
+export type TLegendOptions = {
+    display?: boolean;
+    position?: 'top' | 'left' | 'bottom' | 'right';
+    align?: 'start' | 'center' | 'end';
+    labels?: {
+        generateLabels?: (chart: any) => any[];
+        [key: string]: any;
+    };
+};
+export type TFormatOptions = {
+    type?: 'auto' | 'number' | 'currency' | 'percent' | 'scientific' | 'date' | 'duration';
+    decimalPlaces?: number;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    currency?: string;
+    locale?: string;
+    prefix?: string;
+    suffix?: string;
+    useSuffix?: boolean;
+    useGrouping?: boolean;
+    negativeInParentheses?: boolean;
+    multiplyBy?: number;
+    percentValueMode?: 'fraction' | 'whole';
+    dateFormat?: string;
+    timezone?: string;
+    sourceTimezone?: string;
+    relative?: boolean;
+    durationInputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    durationDisplayStyle?: 'compact' | 'digital' | 'long';
+    durationLargestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    durationSmallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    durationMaxUnits?: number;
+};
+export type TTooltipFormatConfig = {
+    formatMode?: 'inherit' | 'override';
+    /** @deprecated Use formatMode */
+    mode?: 'inherit' | 'override';
+    formatOptions?: TFormatOptions;
+};
+export type TBulletRangeLabels = 'poor' | 'satisfactory' | 'good';
+export type TBulletRangeKeys = Partial<Record<TBulletRangeLabels, string>>;
+export type TBulletRangeValues = Partial<Record<TBulletRangeLabels, number>>;
+export type TBulletRangeLabelOverrides = Partial<Record<TBulletRangeLabels, string>>;
+export 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[];
+};
+/**
+ * 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%)
+ */
+export type TFunnelPercentMode = 'percentOfTotal' | 'percentOfFirst';
+export 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;
+};
+export 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;
+};
+export 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;
+};
+export 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;
+    formatMode?: 'inherit' | 'override';
+    /** @deprecated Use formatMode + formatOptions.type */
+    format?: 'auto' | 'number' | 'currency' | 'percent' | 'date' | 'scientific' | 'duration' | 'none';
+    formatOptions?: TFormatOptions;
+    font?: {
+        size?: number;
+        weight?: 'normal' | 'bold';
+    };
+    color?: 'auto' | string;
+    clamp?: boolean;
+    clip?: boolean;
+    rotation?: number;
+    showTotal?: boolean;
+    offset?: number;
+};
+export 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';
+};
+export type NumberAxisFormat = {
+    decimalPlaces?: number;
+    minimumFractionDigits?: number;
+    maximumFractionDigits?: number;
+    suffix?: string;
+    currency?: string;
+    locale?: string;
+    useGrouping?: boolean;
+    percentValueMode?: 'fraction' | 'whole';
+};
+export type ColorRange = {
+    start: number;
+    end: number;
+    color: string;
+};
+export type ColorConfig = {
+    segments: Record<string, string>;
+};
+export 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;
+    };
+    formatMode?: 'inherit' | 'override';
+    formatOptions?: TFormatOptions;
+    scale?: {
+        min?: number | 'auto';
+        max?: number | 'auto';
+        stepSize?: number | 'auto';
+    };
+};
+export type TCardPreferences = {
+    comparisonPresentation?: ComparisonPresentationSpec;
+    /** Absence means eligible metrics inherit the Global Date comparison. */
+    inheritGlobalComparison?: false;
+    /** Separate two-metric KPI feature; defaults to false. */
+    metricPairComparisonEnabled?: boolean;
+    onClickFilter?: FilterOnClick[];
+    filterOnClick?: boolean;
+    filterOnClickField?: string;
+    filterOnClickColumnIndex?: number;
+    sortChart?: 'asc' | 'desc' | 'none';
+    formatNumber?: {
+        decimalPlaces?: number;
+        minimumFractionDigits?: number;
+        maximumFractionDigits?: number;
+        currency?: string;
+        locale?: string;
+        suffix?: string;
+        prefix?: string;
+        useGrouping?: boolean;
+        percentValueMode?: 'fraction' | 'whole';
+        enabled?: boolean | string;
+        colorRanges?: ColorRange[];
+    };
+    numberAxisFormat?: NumberAxisFormat;
+    datasetOptions?: TDatasetOptions[];
+    chartOptions?: TChartOptions;
+    columnSettings?: TColumnSetting<DisplayDataType>[];
+    colorConfig?: ColorConfig;
+    xAxisConfig?: AxisConfig;
+    yAxisConfig?: AxisConfig;
+    secondaryYAxisConfig?: AxisConfig;
+    tooltipConfig?: TTooltipFormatConfig;
+    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;
+        /**
+         * Legacy structured content with dashboard-input variable refs.
+         * Authored via the plain-text ContentEditableText editor. New cards
+         * use `richContent` instead; this stays for backward compatibility
+         * and is never set on a card that has `richContent`.
+         */
+        content?: DashboardInputTextContent;
+        /**
+         * Editor-agnostic rich content authored via the Lexical-based
+         * editor. When this is present, the card renders via the rich-
+         * content path on both the dashboard surface and inside the visual
+         * editor. When absent (and `description` is set), the card falls
+         * back to the legacy HTML-string render path.
+         */
+        richContent?: TextCardRichContent;
+    };
+    mapVisualOptions?: {
+        topoJsonUrl?: string;
+        objectKey?: string;
+        outlineKey?: string;
+        customTopoJsonUrl?: string;
+        projection?: string;
+        projectionScale?: number;
+        projectionOffset?: [number, number];
+        colorScale?: string;
+    };
+    kpiVisualOptions?: {
+        countryLogoId?: string;
+        valueAlignment?: 'left' | 'center';
+        formatOptions?: TFormatOptions;
+        /**
+         * Presentation-only polarity for a query-backed KPI's manually returned
+         * current/prior value pair. Governed KPIs use per-metric polarity instead.
+         */
+        queryComparisonPolarity?: MetricComparisonPolarity;
+    };
+    pivotTableOptions?: {
+        showRowTotals?: boolean;
+        showColumnTotals?: boolean;
+        showGrandTotal?: boolean;
+        sortRowsBy?: 'label' | 'total' | 'metric';
+        sortColumnsBy?: 'label' | 'total' | 'metric';
+    };
+    displayOptions?: {
+        showFilterInfo?: boolean;
+        showCardToolbar?: boolean;
+        showChrome?: boolean;
+        allowScroll?: boolean;
+        showInlineFilterBar?: boolean;
+    };
+};
+export 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;
+        };
+    };
+};
+export type TVisualizationMode = 'builtin' | 'dynamic';
+export type TDynamicVisualIntent = {
+    primaryChartType?: TChartType | 'custom';
+    layout: 'chart-only' | 'composite';
+    includesKpis: boolean;
+};
+export type TDynamicVisualFallback = {
+    mode: 'chart' | 'table';
+    chartType?: TChartType;
+    reason: string;
+};
+export type TDynamicCardPreferences = {
+    renderer: 'dynamic-visual';
+    artifactId?: string;
+    parentArtifactId?: string;
+    title?: string;
+    rendererCode?: string;
+    question?: string;
+    provenance?: 'card-config' | 'query_spec' | 'sql' | 'sql+python';
+    visualIntent?: TDynamicVisualIntent;
+    assistantNote?: string;
+    builtinDisplayOptions?: {
+        showChrome?: boolean;
+        allowScroll?: boolean;
+    };
+    fallback: TDynamicVisualFallback;
+    error?: {
+        stage: string;
+        message: string;
+        details?: string[];
+    };
+};
+/**
+ * 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.
+ */
+export type TInlineFilter = {
+    id: string;
+    /** Alias exposed to document/text variables, for example {{region}}. */
+    variableName?: string;
+    column: string;
+    title: string;
+    dataType: string;
+    /** Exact database type retained when dataType is a normalized UI category. */
+    nativeDataType?: string;
+    table: string;
+    database: string;
+    qualifiedTableName?: 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, 'day' for single-day picker */
+    dateSelectionMode?: DateSelectionMode;
+    /** Default values applied when the dashboard first loads */
+    defaultValues?: (string | number | boolean)[];
+    /** Default date filter applied on dashboard load (relative, fixed month/year, or fixed day) */
+    defaultDateFilter?: DefaultDateFilter;
+    /** 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;
+};
+export type ControlScope = 'dashboard' | 'card';
+export type ControlType = 'enum' | 'multi_enum' | 'text' | 'number' | 'boolean' | 'date' | 'field_selector' | 'metric_selector' | 'aggregation_selector' | 'grain_selector';
+export type ControlInitialValueStrategy = 'saved_default' | 'builtin' | 'embed_required' | 'schedule_snapshot';
+export type ControlOption = {
+    value: string;
+    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;
+    };
+};
+export declare const CONTROL_CARD_DEFAULT_VALUE: "__card_default__";
+export type SqlQueryControlSource = {
+    kind: 'sql_query';
+    connectionId: string;
+    sql: string;
+    valueColumn: string;
+    labelColumn?: string;
+};
+export type ControlSource = {
+    kind: 'manual';
+    options: ControlOption[];
+} | {
+    kind: 'dataset_values';
+    fieldId: string;
+    connectionId?: string;
+} | {
+    kind: 'field_allowlist';
+    fieldIds: string[];
+} | {
+    kind: 'metric_allowlist';
+    metricIds: string[];
+} | SqlQueryControlSource;
+export type ControlDefinition = {
+    id: string;
+    label: string;
+    scope: ControlScope;
+    type: ControlType;
+    source: ControlSource;
+    initialValueStrategy: ControlInitialValueStrategy;
+    defaultValue?: unknown;
+    requiredAtExecution: boolean;
+    hidden?: boolean;
+    locked?: boolean;
+    helpText?: string;
+    placement?: 'toolbar' | 'card_header' | 'advanced';
+    showLabel?: boolean;
+    toolbarWidth?: number;
+};
+/** Matrix-only mapping to an existing authored level or aggregate measure. */
+export type MatrixSelectorTarget = {
+    kind: 'matrix_instance';
+    id: string;
+};
+export type StructuralFieldSelectorTarget = GroupByField | MatrixSelectorTarget;
+export type StructuralMetricSelectorTarget = MetricField | MatrixSelectorTarget;
+export type CurrencyPresentationTarget = {
+    kind: 'metric';
+    metricId: string;
+} | {
+    kind: 'column';
+    columnKey: string;
+} | {
+    kind: 'matrix_measure';
+    measureId: string;
+};
+export type CurrencyPresentationBinding = {
+    controlId: string;
+    target: 'presentation_currency';
+    presentationTarget: CurrencyPresentationTarget;
+};
+export type ControlBinding = {
+    controlId: string;
+    target: 'sql_param';
+    paramId: string;
+} | {
+    controlId: string;
+    target: 'config_metric_selector';
+    matrixTargetId?: string;
+    mapping: Record<string, StructuralMetricSelectorTarget>;
+} | {
+    controlId: string;
+    target: 'config_field_selector';
+    matrixTargetId?: string;
+    mapping: Record<string, StructuralFieldSelectorTarget>;
+} | {
+    controlId: string;
+    target: 'config_aggregation';
+    matrixTargetId?: string;
+    mapping: Record<string, string>;
+} | {
+    controlId: string;
+    target: 'config_grain';
+    matrixTargetId?: string;
+    mapping: Record<string, string>;
+} | CurrencyPresentationBinding;
+export type DashboardInput = FilterDashboardInput | ControlDashboardInput;
+export type DashboardInputScope = {
+    kind: 'allSheets';
+    sheetKinds?: Array<'dashboard' | 'document'>;
+} | {
+    kind: 'sheets';
+    sheetIds: string[];
+} | {
+    kind: 'cards';
+    cardIds: string[];
+} | {
+    kind: 'documentSections';
+    sheetId: string;
+    sectionIds: string[];
+};
+export type DashboardInputRuntimeScope = 'shared' | 'perSheet' | 'perCard' | 'perDocumentSection';
+export type DashboardInputPresentation = {
+    placement?: 'toolbar' | 'card_header' | 'advanced' | 'hidden';
+    widthPx?: number;
+    order?: number;
+};
+export type DashboardInputExportKey = 'label' | 'value' | 'start' | 'end' | 'range';
+export 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;
+};
+export type DashboardInputBase = {
+    id: string;
+    label: string;
+    variableName: string;
+    description?: string;
+    requiredAtExecution?: boolean;
+    scope: DashboardInputScope;
+    runtimeScope: DashboardInputRuntimeScope;
+    presentation?: DashboardInputPresentation;
+    exports?: DashboardInputExportKey[];
+    compatibility?: DashboardInputCompatibilityMetadata;
+};
+/** Filter-only lifecycle policy, independent of requiredAtExecution. */
+type FilterDashboardInputBase = DashboardInputBase & {
+    /** Empty selections restore the authored default; viewers may replace it. */
+    forceSelection?: boolean;
+};
+export type EmbeddedFilterDashboardInput = FilterDashboardInputBase & {
+    kind: 'filter';
+    filter: TFilter;
+    filterReference?: never;
+    optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
+    application?: DashboardFilterApplication;
+};
+export type ReferencedFilterDashboardInput = FilterDashboardInputBase & {
+    kind: 'filter';
+    filter?: never;
+    filterReference: {
+        kind: 'dashboardFilter';
+        filterId: string;
+    };
+    optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
+    application?: DashboardFilterApplication;
+};
+export type FilterDashboardInput = EmbeddedFilterDashboardInput | ReferencedFilterDashboardInput;
+/** Runtime form after dashboard-filter references are resolved once. */
+export type NormalizedFilterDashboardInput = FilterDashboardInputBase & {
+    kind: 'filter';
+    filter: TFilter;
+    optionSource?: DashboardFilterOptionSource;
+    optionDependencies?: DashboardFilterOptionDependencies;
+    optionPopulation?: DashboardFilterOptionPopulation;
+    application?: DashboardFilterApplication;
+    definitionOrigin: 'embedded' | 'dashboardFilter';
+};
+export type ControlDashboardInput = DashboardInputBase & {
+    kind: 'control';
+    control: ControlDefinition;
+};
+export type NormalizedDashboardInput = NormalizedFilterDashboardInput | ControlDashboardInput;
+export type DashboardInputValue = {
+    kind: 'filter';
+    filterValue: TFilterValue;
+} | {
+    kind: 'control';
+    value: unknown;
+};
+export type DashboardInputSlot = {
+    status: 'set';
+    value: DashboardInputValue;
+    comparisonSelection?: GlobalDateComparisonSelection;
+} | {
+    status: 'cleared';
+    comparisonSelection?: GlobalDateComparisonSelection;
+} | {
+    status?: never;
+    value?: never;
+    comparisonSelection: GlobalDateComparisonSelection;
+};
+export type DashboardInputValues = {
+    shared?: Record<string, DashboardInputSlot>;
+    bySheetId?: Record<string, Record<string, DashboardInputSlot>>;
+    byCardId?: Record<string, Record<string, DashboardInputSlot>>;
+    byDocumentSectionId?: Record<string, Record<string, DashboardInputSlot>>;
+};
+export type ResolvedDashboardInput = {
+    id: string;
+    kind: 'filter' | 'control';
+    label: string;
+    variableName: string;
+    requiredAtExecution: boolean;
+    slot?: DashboardInputSlot;
+    rawValue?: unknown;
+    displayValue: string;
+    exports: Partial<Record<DashboardInputExportKey, string | number | boolean | null>>;
+    filter?: TFilter;
+    filterValue?: TFilterValue;
+    /** Present when a set filter slot cannot be used with its current definition. */
+    invalidFilterSelection?: boolean;
+    control?: ControlDefinition;
+    controlValue?: unknown;
+    missingRequiredValue?: boolean;
+    comparisonSelection?: GlobalDateComparisonSelection;
+};
+export type ResolvedDashboardDateComparisonInput = {
+    inputId: string;
+    filterId: string;
+    label: string;
+    filter: TFilter;
+    /**
+     * The active value before execution-only canonicalization. Comparison
+     * ownership uses this value as provenance evidence and must fail closed
+     * when its filter or field identity does not match the definition.
+     */
+    filterValue?: TFilterValue;
+    selection: GlobalDateComparisonSelection;
+};
+/**
+ * A comparison input proven to be present in the card's executed filter set.
+ * Ownership and UI coverage must consume this stage, never source inputs.
+ */
+export type MaterializedDashboardDateComparisonInput = ResolvedDashboardDateComparisonInput & {
+    effectiveFilterValue: TFilterValue;
+    /** Target emitted by successful per-card mapping, before date materialization. */
+    mappedFilterValue?: TFilterValue;
+};
+export type ResolvedDashboardInputContext = {
+    inputs: NormalizedDashboardInput[];
+    resolvedInputs: ResolvedDashboardInput[];
+    activeFilters: TFilterValue[];
+    controlDefinitions: ControlDefinition[];
+    cardControlDefinitions: ControlDefinition[];
+    controlBindings: ControlBinding[];
+    controlValues: Record<string, unknown>;
+    variablesByName: Record<string, ResolvedDashboardInput>;
+    globalDateComparisonSelection?: GlobalDateComparisonSelection;
+    dateComparisonInputs?: ResolvedDashboardDateComparisonInput[];
+    variablesById: Record<string, ResolvedDashboardInput>;
+    missingRequiredInputs: ResolvedDashboardInput[];
+};
+export type DashboardInputVariableRef = {
+    source: 'dashboardInput';
+    inputId: string;
+    export: DashboardInputExportKey;
+} | {
+    source: 'dashboardInputAlias';
+    variableName: string;
+    export?: DashboardInputExportKey;
+} | {
+    source: 'documentMeta';
+    key: 'generatedAt' | 'pageNumber' | 'pageCount';
+};
+export type DashboardInputTextContent = Array<{
+    type: 'text';
+    value: string;
+} | {
+    type: 'variable';
+    ref: DashboardInputVariableRef;
+}>;
+export type TextCardInlineFormat = {
+    bold?: boolean;
+    italic?: boolean;
+};
+export type TextCardRichInline = {
+    type: 'text';
+    value: string;
+    format?: TextCardInlineFormat;
+} | {
+    type: 'variable';
+    ref: DashboardInputVariableRef;
+    format?: TextCardInlineFormat;
+} | {
+    type: 'link';
+    url: string;
+    children: Array<{
+        type: 'text';
+        value: string;
+        format?: TextCardInlineFormat;
+    } | {
+        type: 'variable';
+        ref: DashboardInputVariableRef;
+        format?: TextCardInlineFormat;
+    }>;
+};
+export type TextCardRichBlock = {
+    type: 'paragraph';
+    children: TextCardRichInline[];
+} | {
+    type: 'heading';
+    level: 1 | 2;
+    children: TextCardRichInline[];
+} | {
+    type: 'list';
+    style: 'bulleted' | 'numbered';
+    items: TextCardRichInline[][];
+};
+export type TextCardRichContent = {
+    version: 1;
+    blocks: TextCardRichBlock[];
+};
+export type DashboardInputExecutionSnapshot = {
+    sheetId?: string;
+    cardId?: string;
+    mode: 'dashboard' | 'document' | 'visual';
+    dashboardInputValues: DashboardInputValues;
+    generatedAt?: string;
+    timezone?: string;
+};
+/** Instance references applied to the latest linked library definition. */
+export type DashboardCardReferenceRemapping = {
+    cardIds?: Record<string, string>;
+    sheetIds?: Record<string, string>;
+    inputIds?: Record<string, string>;
+    controlIds?: Record<string, string>;
+    filterIds?: Record<string, string>;
+    inputAliases?: Record<string, DashboardInputVariableRef>;
+};
+export 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;
+    linkedReferenceOverrides?: DashboardCardReferenceRemapping;
+    linkedInteractionTargetOverrides?: Record<string, InteractionTargetOverride>;
+    paginationConfig?: PaginationConfig;
+    queryConfig?: QueryConfig;
+    customCfg?: any;
+    preferences?: TCardPreferences;
+    customCardPreferences?: TCustomCardPreferences;
+    visualizationMode?: TVisualizationMode;
+    dynamicCardPreferences?: TDynamicCardPreferences;
+    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[];
+    /**
+     * Card-scoped calculated fields that should remain available even when they
+     * are not actively selected in the chart configuration.
+     */
+    calculatedFields?: Field[];
+    /**
+     * Card-scoped control definitions for this card.
+     */
+    controls?: ControlDefinition[];
+    /**
+     * Per-card bindings that connect dashboard or card controls to this card's runtime targets.
+     */
+    controlBindings?: ControlBinding[];
+};
+export type TFrame = {
+    id: string;
+    visualId?: string;
+    filterId?: string;
+    cards: TCard[];
+    activeCardId: string;
+    calculatedFields?: Field[];
+};
+export type DocumentPageSetup = {
+    size: 'letter' | 'a4';
+    orientation: 'portrait' | 'landscape';
+    margins: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+        unit: 'in' | 'mm';
+    };
+};
+export type DocumentRuntimeSettings = {
+    generatedAtFormat?: string;
+};
+export type DocumentInputExportKey = 'label' | 'value' | 'start' | 'end' | 'range';
+export type DocumentInputDefinition = DocumentFilterInputDefinition | DocumentControlInputDefinition;
+export type DocumentInputBase = {
+    id: string;
+    label: string;
+    variableName: string;
+    requiredAtExecution: boolean;
+    documentPlacement?: 'input_bar';
+    description?: string;
+};
+export type DocumentFilterInputDefinition = DocumentInputBase & {
+    kind: 'filter';
+    filter: TFilter;
+    exports?: DocumentInputExportKey[];
+};
+export type DocumentControlInputDefinition = DocumentInputBase & {
+    kind: 'control';
+    control: ControlDefinition;
+    exports?: DocumentInputExportKey[];
+};
+export type ResolvedDocumentInput = {
+    inputId: string;
+    variableName: string;
+    rawValue: unknown;
+    displayValue: string;
+    filterValues?: TFilterValue[];
+    controlValue?: unknown;
+    exports: Record<string, string | number | boolean | null>;
+};
+export type DocumentRegion = DocumentHeaderRegion | DocumentFooterRegion;
+export type DocumentRegionBase = {
+    enabled: boolean;
+    heightPx?: number;
+    layout: DocumentRegionLayout;
+    blocks: DocumentRegionBlock[];
+};
+export type DocumentHeaderRegion = DocumentRegionBase & {
+    region: 'header';
+    layout: {
+        type: 'preset';
+        preset: 'mvp_header';
+    };
+};
+export type DocumentFooterRegion = DocumentRegionBase & {
+    region: 'footer';
+    layout: {
+        type: 'preset';
+        preset: 'mvp_footer';
+    };
+};
+export type DocumentRegionLayout = {
+    type: 'preset';
+    preset: 'mvp_header' | 'mvp_footer';
+};
+export type DocumentRegionBlock = DocumentTextRegionBlock | DocumentImageRegionBlock;
+export type DocumentRegionBlockBase = {
+    id: string;
+    area?: 'left' | 'center' | 'right' | 'title' | 'metadata' | 'note' | 'pageInfo';
+};
+export type DocumentTextRegionBlock = DocumentRegionBlockBase & {
+    type: 'text';
+    role?: 'title' | 'metadata' | 'note' | 'pageInfo';
+    content: DocumentTextContent;
+    style?: DocumentTextStyle;
+};
+export type DocumentImageRegionBlock = DocumentRegionBlockBase & {
+    type: 'image';
+    role?: 'logo';
+    src: string;
+    alt?: string;
+    widthPx?: number;
+};
+export type DocumentTextContent = DocumentTextNode[];
+export type DocumentTextNode = {
+    type: 'text';
+    value: string;
+    format?: DocumentTextInlineFormat;
+} | {
+    type: 'variable';
+    ref: DocumentVariableRef;
+    format?: DocumentTextInlineFormat;
+};
+export type DocumentVariableRef = {
+    source: 'input';
+    inputId: string;
+    export: DocumentInputExportKey;
+} | {
+    source: 'documentMeta';
+    key: 'generatedAt' | 'pageNumber' | 'pageCount';
+};
+export type DocumentTextInlineFormat = {
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+};
+export type DocumentTextStyle = {
+    fontSize?: number;
+    fontWeight?: 'normal' | 'medium' | 'semibold' | 'bold';
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+};
+export type DocumentSection = DocumentTextSection | DocumentTableSection | DocumentChartSection | DocumentSpacerSection | DocumentPageBreakSection;
+export type DocumentTextSection = {
+    id: string;
+    type: 'text';
+    content: DocumentTextContent;
+    style?: DocumentTextStyle;
+};
+export type DocumentTableSection = {
+    id: string;
+    type: 'table';
+    title?: string;
+    card: TCard;
+    table: {
+        totalsRow?: boolean;
+        columnFormatting?: Record<string, unknown>;
+        repeatHeaderOnPageBreak?: boolean;
+        rowHeightPx?: number;
+    };
+};
+export type DocumentChartSection = {
+    id: string;
+    type: 'chart';
+    title?: string;
+    card: TCard;
+    heightPx: number;
+};
+export type DocumentSpacerSection = {
+    id: string;
+    type: 'spacer';
+    heightPx: number;
+};
+export type DocumentPageBreakSection = {
+    id: string;
+    type: 'page_break';
+};
+export type DocumentTheme = {
+    fontFamily?: string;
+    primaryColor?: string;
+};
+export type DocumentDefinition = {
+    version: 1;
+    page: DocumentPageSetup;
+    runtime?: DocumentRuntimeSettings;
+    inputs?: DocumentInputDefinition[];
+    defaultInputValues?: Record<string, unknown>;
+    header?: DocumentHeaderRegion;
+    footer?: DocumentFooterRegion;
+    sections: DocumentSection[];
+    theme?: DocumentTheme;
+};
+export 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 propeerites for the dashboard
+ */
+export 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;
+    };
+};
+export type TEvent = {
+    type: 'success' | 'error' | 'info' | 'warning';
+    message: any;
+};
+/** Supported lifecycle transitions emitted by an editable dashboard session. */
+export type DashboardLifecycleEvent = {
+    type: 'dashboard:dirty-state';
+    dashboardId: string;
+    payload: {
+        dirty: boolean;
+    };
+};
+/**
+ * Style for the dashboard
+ */
+export type TStyle = {
+    default: StyleProps;
+    dark?: StyleProps;
+};
+export type TBaseQuery = {
+    id: string;
+    name: string;
+    connectionId: string;
+    sql: string;
+    context?: string;
+    description?: string;
+};
+export type CacheConfig = {
+    ttl: string;
+    status: 'on' | 'on-refresh' | 'off';
+};
+export type EmailSettings = {
+    companyName: string;
+    dashboardUrl: string;
+    supportEmail: string;
+    senderTitle: string;
+};
+export 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;
+};
+type BaseCustomCard = {
+    cardId: string;
+    replaceDefault?: boolean;
+};
+type CardWithContent = BaseCustomCard & {
+    content: React.FC<{
+        card: TCard;
+    }>;
+    footer?: React.FC<{
+        card: TCard;
+    }>;
+};
+type CardWithFooter = BaseCustomCard & {
+    content?: React.FC<{
+        card: TCard;
+    }>;
+    footer: React.FC<{
+        card: TCard;
+    }>;
+};
+export type CustomCard = CardWithContent | CardWithFooter;
+export type LoadingProps = {
+    message?: string;
+};
+export type ErrorProps = {
+    message?: string;
+};
+export type TCardContext = {
+    id: string;
+    name: string;
+    description: string;
+    sql: string;
+};
+type Params = {
+    [key: string]: string | number | string[] | number[];
+};
+export type ConnectionPolicy = {
+    connectionId?: string;
+    name: string;
+    params: Params;
+};
+export type AIScopeTable = {
+    connectionId: string;
+    connectionType: string;
+    databaseName: string;
+    schemaName: string;
+    tableName: string;
+    datamodelId: string;
+    datamodelName: string;
+};
+export type AssistantId = 'dashboard-assistant' | 'editor-assistant';
+export interface UserPreference {
+    id: string;
+    actorType: 'ORG_USER' | 'TENANT_USER';
+    projectId: string;
+    defaultDashboardId: string | null;
+    defaultDashboard?: {
+        id: string;
+        title: string;
+        description: string;
+    };
+    preferences: Record<string, any> | null;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface UpdateUserPreferenceRequest {
+    defaultDashboardId: string | null;
+}