react-semaphor 0.1.504 → 0.1.506

package/dist/types/lib/utils/card-definition.d.ts

@@ -0,0 +1,387 @@
+import { TCard } from '../types/common-types.js';
+import { CardConfig, Field } from '../types/explorer-types.js';
+import { MatrixCardCatalog } from '../matrix-table/matrix-card-adapter.js';
+export type DefinitionCard = Pick<TCard, 'type' | 'config' | 'sql' | 'python'>;
+export type ShelfCard = Omit<TCard, 'type'> & {
+    type: Exclude<TCard['type'], 'matrixTable'>;
+};
+export type ShelfDefinitionCard = Pick<ShelfCard, 'type' | 'config'>;
+export type AuthoredCardFields = {
+    rows: Field[];
+    columns: Field[];
+    metrics: Field[];
+    details: Field[];
+};
+/** A generic card must be narrowed before entering a shelf-only operation. */
+export declare function isShelfCard<T extends DefinitionCard>(card: T): card is T & ShelfDefinitionCard;
+export declare function readShelfCardFields(card: ShelfDefinitionCard): AuthoredCardFields;
+/** Read-only definition capabilities. Execution and lifecycle remain separate. */
+export declare function getCardDefinition(card: DefinitionCard, catalog?: MatrixCardCatalog): {
+    kind: "shelf";
+    status: "absent" | "ready";
+    fields: AuthoredCardFields;
+    filters: import('../types/explorer-types.js').FilterGroup | undefined;
+    joinPlan: import('../types/explorer-types.js').JoinPlan | undefined;
+    configured: boolean;
+    supportsSql: boolean;
+    matrix?: undefined;
+    error?: undefined;
+} | {
+    kind: "matrix";
+    status: "absent" | "invalid" | "ready";
+    matrix: {
+        presentation: {
+            totals: {
+                columns: {
+                    grand: {
+                        visible: boolean;
+                        position: "before" | "after";
+                        label?: string | undefined;
+                    };
+                    levels: Readonly<Record<string, {
+                        visible: boolean;
+                        position: "before" | "after";
+                        label?: string | undefined;
+                    }>>;
+                };
+                rows: {
+                    grand: {
+                        visible: boolean;
+                        position: "before" | "after";
+                        label?: string | undefined;
+                    };
+                    levels: Readonly<Record<string, {
+                        visible: boolean;
+                        position: "before" | "after";
+                        label?: string | undefined;
+                    }>>;
+                };
+            };
+            layout: {
+                kind: "compact";
+            } | {
+                kind: "tabular";
+                repeatLabels: boolean;
+            };
+            absence: {
+                emptyText: string;
+                nullText: string;
+            };
+            levelLabels: Readonly<Record<string, string>>;
+            measureLabels: Readonly<Record<string, string>>;
+            levelFormats: Readonly<Record<string, import('../../shared/analytics-protocol/index.js').TemporalBucketFormat | {
+                type: "date" | "datetime";
+                pattern?: string | undefined;
+                locale?: string | undefined;
+                prefix?: string | undefined;
+                suffix?: string | undefined;
+                relative?: boolean | undefined;
+                timezone?: string | undefined;
+                sourceTimezone?: string | undefined;
+            } | {
+                type: "duration";
+                prefix?: string | undefined;
+                suffix?: string | undefined;
+                negativeStyle?: "minus" | "parentheses" | undefined;
+                inputUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+                outputStyle?: "compact" | "digital" | "long" | undefined;
+                largestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+                smallestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+                maxUnits?: number | undefined;
+            } | {
+                type: "string";
+                prefix?: string | undefined;
+                suffix?: string | undefined;
+            } | {
+                type: "number" | "currency" | "percent" | "percentage" | "scientific";
+                currency?: string | undefined;
+                minimumFractionDigits?: number | undefined;
+                maximumFractionDigits?: number | undefined;
+                useGrouping?: boolean | undefined;
+                prefix?: string | undefined;
+                suffix?: string | undefined;
+                negativeStyle?: "minus" | "parentheses" | undefined;
+                compact?: boolean | undefined;
+                scale?: number | undefined;
+                percentValueMode?: "fraction" | "whole" | undefined;
+            }>>;
+            measureFormats: Readonly<Record<string, import('../../shared/analytics-protocol/index.js').TemporalBucketFormat | {
+                type: "date" | "datetime";
+                pattern?: string | undefined;
+                locale?: string | undefined;
+                prefix?: string | undefined;
+                suffix?: string | undefined;
+                relative?: boolean | undefined;
+                timezone?: string | undefined;
+                sourceTimezone?: string | undefined;
+            } | {
+                type: "duration";
+                prefix?: string | undefined;
+                suffix?: string | undefined;
+                negativeStyle?: "minus" | "parentheses" | undefined;
+                inputUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+                outputStyle?: "compact" | "digital" | "long" | undefined;
+                largestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+                smallestUnit?: "second" | "minute" | "hour" | "day" | "millisecond" | undefined;
+                maxUnits?: number | undefined;
+            } | {
+                type: "string";
+                prefix?: string | undefined;
+                suffix?: string | undefined;
+            } | {
+                type: "number" | "currency" | "percent" | "percentage" | "scientific";
+                currency?: string | undefined;
+                minimumFractionDigits?: number | undefined;
+                maximumFractionDigits?: number | undefined;
+                useGrouping?: boolean | undefined;
+                prefix?: string | undefined;
+                suffix?: string | undefined;
+                negativeStyle?: "minus" | "parentheses" | undefined;
+                compact?: boolean | undefined;
+                scale?: number | undefined;
+                percentValueMode?: "fraction" | "whole" | undefined;
+            }>>;
+            conditionalFormatting?: {
+                version: 1;
+                rules: {
+                    id: string;
+                    target: {
+                        level: "row" | "cell";
+                        matrix?: {
+                            axis: "columns" | "rows";
+                            levelId?: string | undefined;
+                            oppositePath?: {
+                                member: {
+                                    value: string | number | boolean | {
+                                        value: string;
+                                        type: "integer" | "decimal";
+                                        kind: "exact_number";
+                                    } | null;
+                                    kind: "value";
+                                } | {
+                                    kind: "others";
+                                    rankingId: string;
+                                };
+                                levelId: string;
+                            }[] | undefined;
+                        } | undefined;
+                        columnIds?: string[] | undefined;
+                        conditionColumnId?: string | undefined;
+                        applyToColumnIds?: string[] | undefined;
+                        tableParts?: ("subtotal" | "body" | "header" | "footer" | "grandTotal")[] | undefined;
+                        rowRoles?: ("member" | "subtotal" | "grand_total" | "others")[] | undefined;
+                        depth?: number | undefined;
+                        includeTotals?: boolean | undefined;
+                        includeSubtotals?: boolean | undefined;
+                    };
+                    condition: {
+                        value: string | number | boolean | {
+                            value: string;
+                            type: "integer" | "decimal";
+                            kind: "exact_number";
+                        } | null;
+                        kind: "comparison";
+                        operator: "eq" | "neq" | "gt" | "gte" | "lt" | "lte";
+                        columnId: string;
+                    } | {
+                        kind: "between";
+                        columnId: string;
+                        min: string | number | boolean | {
+                            value: string;
+                            type: "integer" | "decimal";
+                            kind: "exact_number";
+                        } | null;
+                        max: string | number | boolean | {
+                            value: string;
+                            type: "integer" | "decimal";
+                            kind: "exact_number";
+                        } | null;
+                        inclusive?: boolean | undefined;
+                    } | {
+                        kind: "blank";
+                        columnId: string;
+                        isBlank: boolean;
+                    } | {
+                        value: string;
+                        kind: "contains";
+                        columnId: string;
+                        exact?: boolean | undefined;
+                        caseSensitive?: boolean | undefined;
+                    } | {
+                        kind: "topBottom";
+                        count: number;
+                        columnId: string;
+                        direction: "top" | "bottom";
+                    } | {
+                        kind: "colorScale";
+                        columnId: string;
+                        range: "auto" | "manual";
+                        colors: {
+                            min: string;
+                            max: string;
+                            mid?: string | undefined;
+                        };
+                        min?: number | undefined;
+                        max?: number | undefined;
+                        mid?: number | undefined;
+                    } | {
+                        kind: "dataBar";
+                        columnId: string;
+                        range: "auto" | "manual";
+                        color: string;
+                        min?: number | undefined;
+                        max?: number | undefined;
+                        showValue?: boolean | undefined;
+                    };
+                    name?: string | undefined;
+                    enabled?: boolean | undefined;
+                    style?: {
+                        dataBar?: {
+                            color: string;
+                            showValue: boolean;
+                        } | undefined;
+                        backgroundColor?: string | undefined;
+                        textColor?: string | undefined;
+                        fontWeight?: "normal" | "medium" | "semibold" | "bold" | undefined;
+                        italic?: boolean | undefined;
+                        textDecoration?: "none" | "underline" | "line-through" | undefined;
+                        icon?: "arrowUp" | "arrowDown" | "warning" | "check" | "x" | undefined;
+                    } | undefined;
+                }[];
+            } | undefined;
+        };
+        version: 1;
+        spec: {
+            source: {
+                kind: "semantic";
+                domainId: string;
+                datasetName: string;
+                datasetId?: string | undefined;
+                label?: string | undefined;
+                connectionId?: string | undefined;
+            } | {
+                kind: "physical";
+                connectionId: string;
+                tableName: string;
+                label?: string | undefined;
+                connectionType?: string | undefined;
+                databaseName?: string | undefined;
+                schemaName?: string | undefined;
+                dialect?: "postgres" | "mysql" | "mssql" | "snowflake" | "clickhouse" | "bigquery" | "redshift" | "duckdb" | "sqlite" | "unknown" | undefined;
+            };
+            columns: readonly import('../../shared/analytics-protocol/matrix-definition-contract.js').MatrixLevel[];
+            measures: readonly ({
+                id: string;
+                kind: "aggregate";
+                aggregate: "SUM" | "COUNT" | "AVG" | "MIN" | "MAX" | "DISTINCT";
+                field: Omit<import('../../shared/analytics-protocol/index.js').SemaphorExecutionFieldRef, "source" | "aggregate" | "derivedField"> & {
+                    source?: import('../../shared/analytics-protocol/index.js').SemaphorMatrixSourceRef;
+                    derivedField?: Omit<import('../../data-app-sdk.js').SemaphorDerivedFieldDefinition, "inputs"> & {
+                        inputs: Record<string, {
+                            kind: "field";
+                            field: Omit<import('../../data-app-sdk.js').SemaphorFieldRef, "source"> & {
+                                source?: import('../../shared/analytics-protocol/index.js').SemaphorMatrixSourceRef;
+                            };
+                            aggregate?: import('../../shared/analytics-protocol/index.js').SemaphorAggregateFunction;
+                        }>;
+                    };
+                };
+            } | {
+                id: string;
+                kind: "calculated";
+                definition: Omit<import('../../data-app-sdk.js').SemaphorDerivedFieldDefinition, "inputs"> & {
+                    inputs: Record<string, {
+                        kind: "field";
+                        field: Omit<import('../../data-app-sdk.js').SemaphorFieldRef, "source"> & {
+                            source?: import('../../shared/analytics-protocol/index.js').SemaphorMatrixSourceRef;
+                        };
+                        aggregate?: import('../../shared/analytics-protocol/index.js').SemaphorAggregateFunction;
+                    }>;
+                };
+            })[];
+            rows: readonly import('../../shared/analytics-protocol/matrix-definition-contract.js').MatrixLevel[];
+            sorts: readonly {
+                target: import('../../shared/analytics-protocol/matrix-definition-contract.js').MatrixSortTarget;
+                scope: {
+                    kind: "level";
+                } | {
+                    kind: "branch";
+                    parent: readonly {
+                        member: {
+                            value: string | number | boolean | {
+                                value: string;
+                                type: "integer" | "decimal";
+                                kind: "exact_number";
+                            } | null;
+                            kind: "value";
+                        } | {
+                            kind: "others";
+                            rankingId: string;
+                        };
+                        levelId: string;
+                    }[];
+                };
+                levelId: string;
+                axis: "columns" | "rows";
+                direction: "asc" | "desc";
+                nulls: "first" | "last";
+            }[];
+            rankings: readonly import('../../shared/analytics-protocol/matrix-definition-contract.js').MatrixRanking[];
+            filters?: import('../types/explorer-types.js').FilterGroup | undefined;
+            joinPlan?: import('../types/explorer-types.js').JoinPlan | undefined;
+            relationshipHint?: {
+                relationshipIds?: string[] | undefined;
+            } | undefined;
+        };
+        defaultView: {
+            columns: {
+                depth: number;
+                overrides: readonly {
+                    path: readonly {
+                        member: {
+                            value: string | number | boolean | {
+                                value: string;
+                                type: "integer" | "decimal";
+                                kind: "exact_number";
+                            } | null;
+                            kind: "value";
+                        } | {
+                            kind: "others";
+                            rankingId: string;
+                        };
+                        levelId: string;
+                    }[];
+                    expanded: boolean;
+                }[];
+            };
+            rows: {
+                depth: number;
+                overrides: readonly {
+                    path: readonly {
+                        member: {
+                            value: string | number | boolean | {
+                                value: string;
+                                type: "integer" | "decimal";
+                                kind: "exact_number";
+                            } | null;
+                            kind: "value";
+                        } | {
+                            kind: "others";
+                            rankingId: string;
+                        };
+                        levelId: string;
+                    }[];
+                    expanded: boolean;
+                }[];
+            };
+        };
+    } | undefined;
+    error: Error | undefined;
+    readonly fields: AuthoredCardFields;
+    filters: import('../types/explorer-types.js').FilterGroup | undefined;
+    joinPlan: import('../types/explorer-types.js').JoinPlan | undefined;
+    readonly configured: boolean;
+    supportsSql: boolean;
+};
+/** Config-only callers must explicitly identify which representation they read. */
+export declare function hasShelfFields(config: CardConfig | undefined): boolean;

package/dist/types/lib/utils/card-loading-state.d.ts

@@ -0,0 +1,17 @@
+import { TCard } from '../types/common-types.js';
+type CardLoadingPresentationInput = {
+    card: Pick<TCard, 'type'> | undefined;
+    fetchStatus?: 'fetching' | 'paused' | 'idle';
+    isLoading?: boolean;
+    isFetching?: boolean;
+    isPending?: boolean;
+    hasRecords?: boolean;
+};
+export declare function shouldUseCardSkeletonDuringRefetch(card: Pick<TCard, 'type'> | undefined): boolean;
+export declare function getCardLoadingPresentation({ card, fetchStatus, isLoading, isFetching, isPending, hasRecords, }: CardLoadingPresentationInput): {
+    isBusy: boolean;
+    showCardSkeleton: boolean;
+    showGenericLoadingFallback: boolean;
+    showStaleDataOverlay: boolean;
+};
+export {};

package/dist/types/lib/utils/card-utils.d.ts

@@ -0,0 +1,52 @@
+import { TDashboard, TCard, TSheet } from '../types/common-types.js';
+export type DashboardCardEntry = {
+    card: TCard;
+    sheet: TSheet;
+};
+export declare function getDashboardCardEntries(dashboard: Pick<TDashboard, 'sheets'>): DashboardCardEntry[];
+export declare function getDashboardCards(dashboard: Pick<TDashboard, 'sheets'>): TCard[];
+/**
+ * Check if a card ID is unique across the entire dashboard
+ * @param dashboard - The dashboard to check against
+ * @param cardId - The proposed card ID
+ * @param currentCardId - The current card ID (to exclude from check when editing)
+ * @returns true if the ID is unique, false otherwise
+ */
+export declare function isCardIdUnique(dashboard: TDashboard, cardId: string, currentCardId?: string): boolean;
+/**
+ * Validate card ID format
+ * @param cardId - The card ID to validate
+ * @returns An object with isValid flag and error message if invalid
+ */
+export declare function validateCardId(cardId: string): {
+    isValid: boolean;
+    error?: string;
+};
+/**
+ * Sanitize user input for card ID
+ * Converts to lowercase and replaces spaces with hyphens
+ * @param input - The user input to sanitize
+ * @returns Sanitized card ID
+ */
+export declare function sanitizeCardId(input: string): string;
+/**
+ * Get all card IDs in the dashboard
+ * @param dashboard - The dashboard to extract IDs from
+ * @returns Array of all card IDs
+ */
+export declare function getAllCardIds(dashboard: TDashboard): string[];
+/**
+ * Find a card by ID in the dashboard
+ * @param dashboard - The dashboard to search in
+ * @param cardId - The card ID to find
+ * @returns The card if found, undefined otherwise
+ */
+export declare function findCardById(dashboard: TDashboard, cardId: string): TCard | undefined;
+export declare function findCardLocationById(dashboard: TDashboard, cardId: string): {
+    card: TCard;
+    sheet: TSheet;
+} | undefined;
+export declare function findFrameCardLocationById(dashboard: TDashboard, cardId: string): {
+    card: TCard;
+    sheet: TSheet;
+} | undefined;

package/dist/types/lib/utils/chart-icon-utils.d.ts

@@ -0,0 +1,26 @@
+import { default as React } from 'react';
+import { BulletChartIcon } from '../../components/icons/bullet-chart-icon.js';
+export declare const chartTypes: ({
+    id: string;
+    icon: React.ForwardRefExoticComponent<Omit<import('lucide-react').LucideProps, "ref"> & React.RefAttributes<SVGSVGElement>>;
+    label: string;
+} | {
+    id: string;
+    icon: import('react-icons/lib').IconType;
+    label: string;
+} | {
+    id: string;
+    icon: typeof BulletChartIcon;
+    label: string;
+})[];
+/**
+ * Auto-detect chart type from component name
+ * Checks if the lowercase name contains any standard chart type IDs
+ * Special handling for doughnut/donut spelling variations
+ */
+export declare const getAutoDetectedChartIcon: (componentName: string) => React.ReactElement<any> | null;
+/**
+ * Get chart icon component by chart type ID
+ * Returns the icon component for a specific chart type
+ */
+export declare const getChartIconByType: (chartType: string, className?: string) => React.ReactElement<any>;

package/dist/types/lib/utils/chart-type-field-validation.d.ts

@@ -0,0 +1,25 @@
+import { Field, ContainerId } from '../types/explorer-types.js';
+import { TChartType } from '../charts/types.js';
+export interface FieldValidationResult {
+    isValid: boolean;
+    reason?: string;
+}
+/**
+ * Validates if a field can be dropped/added to a container for a specific chart type.
+ * This centralizes all chart-type-specific field validation logic.
+ *
+ * @param field - The field to validate
+ * @param containerId - The target container (groupBy, metrics, pivotBy, sortBy)
+ * @param chartType - The current chart type
+ * @returns Validation result with optional reason for rejection
+ */
+export declare function validateFieldForChartType(field: Field, containerId: ContainerId, chartType: TChartType): FieldValidationResult;
+/**
+ * Checks if a field is compatible with the current chart type
+ * This is used for visual feedback (e.g., disabling fields in the field list)
+ *
+ * @param field - The field to check
+ * @param chartType - The current chart type
+ * @returns true if the field can be used with this chart type
+ */
+export declare function isFieldCompatibleWithChartType(field: Field, chartType: TChartType): boolean;

package/dist/types/lib/utils/comparison-export-utils.d.ts

@@ -0,0 +1,31 @@
+import { TCard } from '../types/common-types.js';
+import { QueryColumnKeyMap } from '../types/explorer-types.js';
+import { ComparisonMetadataMap } from '../types/query-types.js';
+import { ComparisonPresentationSpec } from '../../shared/analytics-protocol/index.js';
+export type ComparisonExportProjection = {
+    excludedKeys: Set<string>;
+    selectedDerivedKeys: Set<string>;
+    columnLabels: Map<string, string>;
+    columnPresentationOwners: Map<string, {
+        metricId: string;
+        metricAlias: string;
+        kind: 'comparison' | 'delta' | 'percent_change' | 'ratio';
+    }>;
+};
+export declare function getComparisonExportProjection(params: {
+    comparisonMetadata?: ComparisonMetadataMap;
+    presentation?: ComparisonPresentationSpec;
+    resolveMetricName?: (identity: {
+        metricId: string;
+        metricAlias: string;
+    }) => string | undefined;
+}): ComparisonExportProjection;
+export declare function getCardComparisonExportProjection(params: {
+    card?: TCard;
+    comparisonMetadata?: ComparisonMetadataMap;
+    columnKeyMap?: QueryColumnKeyMap;
+}): ComparisonExportProjection;
+export declare function hasComparisonExportMetadataGap(params: {
+    card: TCard;
+    comparisonMetadata?: ComparisonMetadataMap;
+}): boolean;

package/dist/types/lib/utils/comparison-output-keys.d.ts

@@ -0,0 +1,37 @@
+import { ComparisonMetadataMap } from '../types/query-types.js';
+import { MetricField } from '../types/explorer-types.js';
+import { ComparisonPresentationSpec, MetricComparisonOutput } from '../../shared/analytics-protocol/index.js';
+import { MetricComparisonKind } from './metric-comparison-config.js';
+type MetricOutputIdentity = {
+    id?: string;
+    name?: string;
+    alias?: string;
+};
+export declare function getComparisonMetadataForMetric(comparisonMetadata: ComparisonMetadataMap | undefined, metric: MetricOutputIdentity): import('../../shared/analytics-protocol/index.js').MetricComparisonMetadataEntry | undefined;
+/**
+ * Resolves the comparison identity a result renderer should present.
+ * Canonical execution metadata wins because inherited comparisons intentionally
+ * have no metric-level authoring config. The authored kind is only a fallback
+ * for callers rendering before canonical metadata is available.
+ */
+export declare function resolveMetricComparisonRenderContext(comparisonMetadata: ComparisonMetadataMap | undefined, metric: MetricField): {
+    comparisonKind: MetricComparisonKind;
+    metadata: ReturnType<typeof getComparisonMetadataForMetric>;
+};
+export declare function showsComparisonPresentation(presentation?: ComparisonPresentationSpec): boolean;
+export declare function getPresentedComparisonOutputKeys(output: MetricComparisonOutput, presentation?: ComparisonPresentationSpec): Set<string>;
+export type ComparisonOutputKeySets = {
+    internalKeys: Set<string>;
+    bookkeepingKeys: Set<string>;
+    comparisonColumnKeys: Set<string>;
+    deltaColumnKeys: Set<string>;
+    percentChangeColumnKeys: Set<string>;
+    ratioColumnKeys: Set<string>;
+    comparisonSeriesLabels: Map<string, {
+        metricName: string;
+        comparisonLabel: string;
+    }>;
+};
+export declare function getComparisonOutputKeySets(comparisonMetadata?: ComparisonMetadataMap): ComparisonOutputKeySets;
+export declare function isInternalComparisonOutputKey(key: string, comparisonMetadata?: ComparisonMetadataMap): boolean;
+export {};

package/dist/types/lib/utils/comparison-period-utils.d.ts

@@ -0,0 +1,6 @@
+export type ComparisonPeriod = {
+    start: string;
+    end: string;
+};
+export declare function formatComparisonDate(dateString: string | null | undefined, _displayTimezone?: string): string | null;
+export declare function formatComparisonPeriodRange(period: ComparisonPeriod | undefined, displayTimezone?: string): string | null;

package/dist/types/lib/utils/comparison-validation-utils.d.ts

@@ -0,0 +1,16 @@
+import { CardConfig } from '../types/explorer-types.js';
+import { TChartType } from '../charts/types.js';
+/**
+ * Validates that a card configuration has a valid comparison setup.
+ *
+ * This function performs two checks:
+ * 1. Chart type check: Ensures the chart type supports comparison mode
+ * 2. Date field check: If period comparison is enabled, ensures at least one date field exists in groupBy
+ *
+ * If validation fails, returns a corrected config with comparison type reset to 'none'.
+ *
+ * @param cardConfig - The card configuration to validate
+ * @param chartType - The type of chart
+ * @returns The validated card configuration with ineligible metric specs cleared.
+ */
+export declare function validateComparisonConfig(cardConfig: CardConfig, chartType: TChartType): CardConfig;

package/dist/types/lib/utils/comparison-window-caption.d.ts

@@ -0,0 +1,12 @@
+import { MetricComparisonWindowGrain } from '../../shared/analytics-protocol/index.js';
+export declare function formatCanonicalComparisonRange(period: {
+    start: string;
+    end: string;
+}, timezone: string, windowGrain: MetricComparisonWindowGrain | undefined, short?: boolean): string;
+export declare function formatCanonicalComparisonBoundaries(period: {
+    start: string;
+    end: string;
+}, timezone: string, windowGrain: MetricComparisonWindowGrain | undefined, short?: boolean): {
+    start: string;
+    end: string;
+};

package/dist/types/lib/utils/connection-capabilities.d.ts

@@ -0,0 +1,26 @@
+import { TDbCapabilities } from '../types/common-types.js';
+/**
+ * Build qualified table name using prefixLevels from capabilities.
+ * Backend always provides prefixLevels, so no fallback lookup needed.
+ *
+ * @example
+ * // PostgreSQL with prefixLevels: ['schema', 'table']
+ * buildQualifiedTableName({ capabilities, database: 'mydb', schema: 'public', table: 'orders' })
+ * // => 'public.orders'
+ *
+ * @example
+ * // S3Tables with prefixLevels: ['database', 'schema', 'table']
+ * buildQualifiedTableName({ capabilities, database: 'ns', schema: 'sch', table: 'orders' })
+ * // => 'ns.sch.orders'
+ *
+ * @example
+ * // S3/API with prefixLevels: ['table']
+ * buildQualifiedTableName({ capabilities, table: 'data.csv' })
+ * // => 'data.csv'
+ */
+export declare function buildQualifiedTableName({ capabilities, database, schema, table, }: {
+    capabilities: TDbCapabilities;
+    database?: string;
+    schema?: string;
+    table: string;
+}): string;