drizzle-cube 0.6.1 → 0.6.3

package/dist/cjs/client/utils/colorPalettes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Unified Color Palette System
+ * Each palette contains coordinated series and gradient colors that work well together
+ */
+export interface ColorPalette {
+    name: string;
+    label: string;
+    colors: string[];
+    gradient: string[];
+}
+export declare const COLOR_PALETTES: ColorPalette[];
+/**
+ * Get a color palette by name, with fallback to default
+ */
+export declare function getColorPalette(paletteName?: string): ColorPalette;
+/**
+ * Get just the series colors for a palette
+ */
+export declare function getSeriesColors(paletteName?: string): string[];
+/**
+ * Get just the gradient colors for a palette
+ */
+export declare function getGradientColors(paletteName?: string): string[];
+/**
+ * Chart types that use series colors (discrete categories)
+ */
+export declare const SERIES_CHART_TYPES: readonly ["bar", "line", "area", "pie", "scatter", "radar", "radialBar", "treeMap"];
+/**
+ * Chart types that use gradient colors (continuous values)
+ */
+export declare const GRADIENT_CHART_TYPES: readonly ["bubble", "activityGrid"];
+/**
+ * Determine if a chart type uses gradient colors
+ */
+export declare function usesGradientColors(chartType: string): boolean;

package/dist/cjs/client/utils/comparisonUtils.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Comparison Data Utilities
+ * Handles period-over-period comparison data transformation for charts
+ *
+ * These utilities detect comparison query results (with __periodIndex metadata)
+ * and transform them for visualization in either 'separate' or 'overlay' mode.
+ */
+/**
+ * Check if data contains comparison period metadata
+ */
+export declare function isComparisonData(data: any[]): boolean;
+/**
+ * Get unique period labels from comparison data
+ */
+export declare function getPeriodLabels(data: any[]): string[];
+/**
+ * Get period indices from comparison data
+ */
+export declare function getPeriodIndices(data: any[]): number[];
+/**
+ * Generate a short label for a period (used in legends)
+ * Uses simple "Current" / "Prior" labels for clarity
+ */
+export declare function generatePeriodShortLabel(_periodLabel: string, index: number): string;
+/**
+ * Transform comparison data for 'separate' mode
+ * Returns data with each row having its original measure values
+ * Series are created per period (e.g., "totalLinesOfCode (Current)", "totalLinesOfCode (Prior)")
+ */
+export declare function transformForSeparateMode(data: any[], measures: string[], _timeDimensionKey: string): {
+    data: any[];
+    seriesKeys: string[];
+};
+/**
+ * Transform comparison data for 'overlay' mode
+ * Pivots data so each row represents a day-of-period index,
+ * with separate columns for each period's values.
+ *
+ * When dimensions are present, creates series keys that include
+ * dimension values: "Engineering - Total Lines of Code (Current)"
+ *
+ * Input (without dimensions):
+ *   [
+ *     { date: '2024-01-01', value: 100, __periodIndex: 0, __periodDayIndex: 0 },
+ *     { date: '2024-01-02', value: 110, __periodIndex: 0, __periodDayIndex: 1 },
+ *     { date: '2023-01-01', value: 80, __periodIndex: 1, __periodDayIndex: 0 },
+ *     { date: '2023-01-02', value: 85, __periodIndex: 1, __periodDayIndex: 1 },
+ *   ]
+ *
+ * Output (without dimensions):
+ *   [
+ *     { __periodDayIndex: 0, 'value (Current)': 100, 'value (Prior)': 80 },
+ *     { __periodDayIndex: 1, 'value (Current)': 110, 'value (Prior)': 85 },
+ *   ]
+ *
+ * Input (with dimensions):
+ *   [
+ *     { date: '2024-01-01', 'Dept.name': 'Engineering', value: 100, __periodIndex: 0, __periodDayIndex: 0 },
+ *     { date: '2024-01-01', 'Dept.name': 'Sales', value: 50, __periodIndex: 0, __periodDayIndex: 0 },
+ *     { date: '2023-01-01', 'Dept.name': 'Engineering', value: 80, __periodIndex: 1, __periodDayIndex: 0 },
+ *     { date: '2023-01-01', 'Dept.name': 'Sales', value: 40, __periodIndex: 1, __periodDayIndex: 0 },
+ *   ]
+ *
+ * Output (with dimensions):
+ *   [
+ *     {
+ *       __periodDayIndex: 0,
+ *       'Engineering - value (Current)': 100,
+ *       'Engineering - value (Prior)': 80,
+ *       'Sales - value (Current)': 50,
+ *       'Sales - value (Prior)': 40,
+ *     },
+ *   ]
+ */
+export declare function transformForOverlayMode(data: any[], measures: string[], timeDimensionKey: string, getFieldLabel?: (fieldName: string) => string): {
+    data: any[];
+    seriesKeys: string[];
+    xAxisKey: string;
+};
+/**
+ * Format the period day index for display on X-axis
+ * Can show as "Day 1", "Day 2", etc., or as the original date
+ */
+export declare function formatPeriodDayIndex(dayIndex: number, displayDate?: string | Date, options?: {
+    showDayNumber?: boolean;
+    dateFormat?: 'short' | 'long';
+}): string;
+/**
+ * Check if a series key represents a prior period (not the first period)
+ * Used for applying different styling to prior period lines
+ */
+export declare function isPriorPeriodSeries(seriesKey: string, periodLabels: string[]): boolean;
+/**
+ * Get the stroke dash array for prior period styling
+ */
+export declare function getPriorPeriodStrokeDashArray(style?: 'solid' | 'dashed' | 'dotted'): string | undefined;

package/dist/cjs/client/utils/configMigration.d.ts

@@ -0,0 +1,85 @@
+import { AnalysisConfig, FunnelAnalysisConfig } from '../types/analysisConfig.js';
+import { ChartType, ChartAxisConfig, ChartDisplayConfig, CubeQuery, FunnelBindingKey, PortletConfig } from '../types.js';
+/**
+ * Legacy portlet format (before AnalysisConfig)
+ */
+export interface LegacyPortlet {
+    /** JSON string of CubeQuery or MultiQueryConfig */
+    query: string;
+    chartType?: ChartType;
+    chartConfig?: ChartAxisConfig;
+    displayConfig?: ChartDisplayConfig;
+    analysisType?: 'query' | 'funnel';
+    funnelChartType?: ChartType;
+    funnelChartConfig?: ChartAxisConfig;
+    funnelDisplayConfig?: ChartDisplayConfig;
+}
+/**
+ * Legacy MultiQueryConfig with funnel merge strategy
+ * This is a standalone type (not extending MultiQueryConfig) to handle old data
+ * where mergeStrategy was 'funnel' before it was removed from QueryMergeStrategy.
+ */
+export interface LegacyFunnelMultiQuery {
+    queries: CubeQuery[];
+    mergeStrategy: 'funnel';
+    mergeKeys?: string[];
+    queryLabels?: string[];
+    funnelBindingKey?: FunnelBindingKey | null;
+    stepTimeToConvert?: (string | null)[];
+}
+/**
+ * Migrate a legacy portlet to AnalysisConfig format
+ *
+ * Handles:
+ * - Single CubeQuery → QueryAnalysisConfig
+ * - MultiQueryConfig → QueryAnalysisConfig
+ * - ServerFunnelQuery → FunnelAnalysisConfig
+ * - ServerFlowQuery → FlowAnalysisConfig
+ * - Legacy mergeStrategy:'funnel' → FunnelAnalysisConfig (via migrateLegacyFunnelMerge)
+ *
+ * @param portlet - Legacy portlet with query string
+ * @returns AnalysisConfig in new format
+ */
+export declare function migrateLegacyPortlet(portlet: LegacyPortlet): AnalysisConfig;
+/**
+ * Migrate legacy mergeStrategy:'funnel' to FunnelAnalysisConfig
+ *
+ * This handles the old pattern where funnels were created using multi-query
+ * with mergeStrategy: 'funnel'. Converts to the new dedicated funnel format.
+ *
+ * @param legacyQuery - MultiQueryConfig with mergeStrategy: 'funnel'
+ * @param portlet - Legacy portlet for chart config
+ * @returns FunnelAnalysisConfig in new format
+ */
+export declare function migrateLegacyFunnelMerge(legacyQuery: LegacyFunnelMultiQuery, portlet?: LegacyPortlet): FunnelAnalysisConfig;
+/**
+ * Migrate any config to the latest version
+ *
+ * Handles:
+ * - Already valid AnalysisConfig (returns as-is)
+ * - Legacy portlet format (converts to AnalysisConfig)
+ * - Unknown format (returns default config)
+ *
+ * @param config - Unknown config value
+ * @returns Valid AnalysisConfig
+ */
+export declare function migrateConfig(config: unknown): AnalysisConfig;
+/**
+ * Check if a portlet has the new AnalysisConfig format
+ */
+export declare function hasAnalysisConfig(portlet: unknown): portlet is {
+    analysisConfig: AnalysisConfig;
+};
+/**
+ * Ensure a portlet has analysisConfig, migrating from legacy format if needed.
+ *
+ * This is the primary entry point for rendering portlets - it guarantees
+ * that analysisConfig exists, either by using the existing one or by
+ * converting legacy fields on-the-fly.
+ *
+ * @param portlet - PortletConfig which may or may not have analysisConfig
+ * @returns PortletConfig with analysisConfig guaranteed to exist
+ */
+export declare function ensureAnalysisConfig(portlet: PortletConfig): PortletConfig & {
+    analysisConfig: AnalysisConfig;
+};

package/dist/cjs/client/utils/drillQueryBuilder.d.ts

@@ -0,0 +1,41 @@
+import { CubeQuery, CubeMeta, CubeMetaHierarchy, TimeGranularity, DashboardFilter, DashboardFilterMapping } from '../types.js';
+import { DrillOption, DrillResult, ChartDataPointClickEvent } from '../types/drill.js';
+/**
+ * Check if a dimension is a time dimension based on metadata
+ */
+export declare function isTimeDimension(dimensionName: string, metadata: CubeMeta): boolean;
+/**
+ * Get the granularities available for a time dimension
+ */
+export declare function getTimeDimensionGranularities(dimensionName: string, metadata: CubeMeta): TimeGranularity[];
+/**
+ * Get the current granularity from a query's time dimensions
+ */
+export declare function getCurrentGranularity(query: CubeQuery): TimeGranularity | null;
+/**
+ * Get drillMembers for a measure from metadata
+ */
+export declare function getMeasureDrillMembers(measureName: string, metadata: CubeMeta): string[] | null;
+/**
+ * Get hierarchy by name from metadata
+ */
+export declare function getHierarchy(hierarchyName: string, cubeName: string, metadata: CubeMeta): CubeMetaHierarchy | null;
+/**
+ * Get all hierarchies for a cube
+ */
+export declare function getCubeHierarchies(cubeName: string, metadata: CubeMeta): CubeMetaHierarchy[];
+/**
+ * Find which hierarchy (if any) contains a dimension
+ */
+export declare function findHierarchyForDimension(dimensionName: string, metadata: CubeMeta): {
+    hierarchy: CubeMetaHierarchy;
+    levelIndex: number;
+} | null;
+/**
+ * Build drill options for a clicked data point
+ */
+export declare function buildDrillOptions(event: ChartDataPointClickEvent, query: CubeQuery, metadata: CubeMeta | null, dashboardFilters?: DashboardFilter[], dashboardFilterMapping?: DashboardFilterMapping): DrillOption[];
+/**
+ * Build a drill query based on the selected option
+ */
+export declare function buildDrillQuery(option: DrillOption, event: ChartDataPointClickEvent, query: CubeQuery, metadata: CubeMeta): DrillResult;

package/dist/cjs/client/utils/exportXlsx.d.ts

@@ -0,0 +1,20 @@
+import { XlsExportFeatureConfig } from '../types.js';
+import { PortletDebugDataEntry } from '../stores/dashboardStore.js';
+/**
+ * Check if XLSX export is available (ExcelJS installed)
+ */
+export declare function isExportAvailable(): Promise<boolean>;
+declare global {
+    interface Window {
+        __drizzle_cube_xls_export_warning__?: boolean;
+    }
+}
+/**
+ * Log a development-mode warning when xlsExport feature is enabled but exceljs is missing
+ */
+export declare function warnIfExcelJsMissing(xlsExportConfig: XlsExportFeatureConfig | undefined): void;
+/**
+ * Export portlet data as a formatted XLSX file.
+ * Returns true on success, false on failure.
+ */
+export declare function exportPortletToXlsx(portletTitle: string, debugData: PortletDebugDataEntry): Promise<boolean>;

package/dist/cjs/client/utils/filterUtils.d.ts

@@ -0,0 +1,113 @@
+import { Filter, DashboardFilter, DashboardFilterMapping, DashboardFilterMappingEntry, CubeMeta, DashboardConfig } from '../types.js';
+/**
+ * Normalize a portlet filter mapping to entry objects.
+ * Plain string entries (the legacy format) become { filterId } with no override.
+ */
+export declare function normalizeFilterMapping(mapping: DashboardFilterMapping | undefined): DashboardFilterMappingEntry[];
+/**
+ * Serialize mapping entries for storage.
+ * Entries without a member override collapse back to plain strings so saved
+ * configs only change shape when an override is actually used.
+ */
+export declare function serializeFilterMapping(entries: DashboardFilterMappingEntry[]): DashboardFilterMapping;
+/**
+ * Check whether a mapping (either format) includes a given dashboard filter
+ */
+export declare function mappingIncludesFilter(mapping: DashboardFilterMapping | undefined, filterId: string): boolean;
+/**
+ * Get the per-portlet member override for a dashboard filter, if any
+ */
+export declare function getMappingMemberOverride(mapping: DashboardFilterMapping | undefined, filterId: string): string | undefined;
+/**
+ * Clone a filter with its member rewritten to the override field.
+ * Only SimpleFilters can be rewritten; GroupFilters pass through unchanged.
+ */
+export declare function applyMemberOverride(filter: Filter, member?: string): Filter;
+/**
+ * Check if a filter should be included in the query (has valid values or doesn't require values)
+ * @param filter - The filter to check
+ * @returns true if the filter should be included, false otherwise
+ */
+export declare function shouldIncludeFilter(filter: Filter): boolean;
+/**
+ * Get dashboard filters that should be applied to a portlet based on its mapping configuration
+ *
+ * Mapping entries may carry a per-portlet member override, in which case the
+ * filter is applied with its member rewritten to the override field (operator
+ * and values stay shared across all portlets).
+ *
+ * @param dashboardFilters - All available dashboard filters
+ * @param filterMapping - The portlet's filter mapping (filter IDs or entries with member overrides)
+ * @returns Array of filters that should be applied to the portlet
+ */
+export declare function getApplicableDashboardFilters(dashboardFilters: DashboardFilter[] | undefined, filterMapping: DashboardFilterMapping | undefined): Filter[];
+/**
+ * Filter format for merge operation:
+ * - 'server': Returns {and: [...]} or {or: [...]} format (for API queries)
+ * - 'client': Returns {type: 'and', filters: [...]} format (for UI components)
+ */
+export type FilterFormat = 'server' | 'client';
+/**
+ * Merge dashboard filters with portlet filters using AND logic
+ * Dashboard filters are combined with portlet filters so both sets of filters apply
+ *
+ * @param dashboardFilters - Filters from dashboard-level configuration
+ * @param portletFilters - Filters from portlet query
+ * @param format - Output format: 'server' for API queries, 'client' for UI (default: 'server')
+ * @returns Merged filter array with AND logic in the specified format
+ */
+export declare function mergeDashboardAndPortletFilters(dashboardFilters: Filter[], portletFilters: Filter[] | undefined, format?: FilterFormat): Filter[] | undefined;
+/**
+ * @deprecated Use mergeDashboardAndPortletFilters(filters, portletFilters, 'client') instead
+ */
+export declare function mergeDashboardAndPortletFiltersClientFormat(dashboardFilters: Filter[], portletFilters: Filter[] | undefined): Filter[] | undefined;
+/**
+ * Check if a filter field exists in the cube metadata
+ * This helps identify filters that might not apply to a specific portlet's data
+ * @param filter - The filter to validate
+ * @param cubeMeta - Cube metadata to validate against
+ * @returns true if the filter field exists in any cube's measures or dimensions
+ */
+export declare function validateFilterForCube(filter: Filter, cubeMeta: CubeMeta | null): boolean;
+/**
+ * Validate that all dashboard filters in a portlet's mapping exist and are valid
+ * @param dashboardFilters - All available dashboard filters
+ * @param filterMapping - The portlet's filter mapping
+ * @param cubeMeta - Cube metadata for validation
+ * @returns Object with validation result and list of invalid filter IDs
+ */
+export declare function validatePortletFilterMapping(dashboardFilters: DashboardFilter[] | undefined, filterMapping: DashboardFilterMapping | undefined, cubeMeta: CubeMeta | null): {
+    isValid: boolean;
+    invalidFilterIds: string[];
+    missingFilterIds: string[];
+};
+/**
+ * Extract all unique measures, dimensions, and timeDimensions used across all portlets in a dashboard
+ * This helps create a filtered schema view showing only fields relevant to the dashboard
+ * @param dashboardConfig - Dashboard configuration
+ * @returns Object with unique measures, dimensions, and timeDimensions
+ */
+export declare function extractDashboardFields(dashboardConfig: DashboardConfig): {
+    measures: Set<string>;
+    dimensions: Set<string>;
+    timeDimensions: Set<string>;
+};
+/**
+ * Time dimension type from CubeQuery
+ */
+type TimeDimension = {
+    dimension: string;
+    granularity?: string;
+    dateRange?: string[] | string;
+};
+/**
+ * Apply universal time filters to a portlet's timeDimensions
+ * Universal time filters apply their dateRange to ALL time dimensions in the portlet
+ *
+ * @param dashboardFilters - All dashboard filters
+ * @param filterMapping - Filter IDs that apply to this portlet
+ * @param portletTimeDimensions - The portlet's existing timeDimensions array
+ * @returns Updated timeDimensions array with date ranges applied
+ */
+export declare function applyUniversalTimeFilters(dashboardFilters: DashboardFilter[] | undefined, filterMapping: DashboardFilterMapping | undefined, portletTimeDimensions: TimeDimension[] | undefined): TimeDimension[] | undefined;
+export {};

package/dist/cjs/client/utils/funnelExecution.d.ts

@@ -0,0 +1,211 @@
+import { CubeQuery, SimpleFilter } from '../types.js';
+import { FunnelBindingKey, FunnelBindingKeyMapping, FunnelConfig, FunnelStep, FunnelStepResult, FunnelExecutionResult, FunnelChartData } from '../types/funnel.js';
+/**
+ * Default maximum number of binding key values to pass between funnel steps.
+ * Limits the size of the IN clause to prevent performance issues.
+ */
+export declare const DEFAULT_BINDING_KEY_LIMIT = 500;
+/**
+ * Extract the binding key field name for a specific query/cube.
+ *
+ * For simple binding keys (string), returns the dimension directly.
+ * For cross-cube mappings, finds the mapping for the cube used in the query.
+ *
+ * @param bindingKey - The funnel binding key configuration
+ * @param query - The cube query (used to determine which cube is being queried)
+ * @returns The binding key field name (e.g., "Users.userId")
+ */
+export declare function getBindingKeyField(bindingKey: FunnelBindingKey, query: CubeQuery): string;
+/**
+ * Extract the cube name from a query by looking at measures/dimensions
+ */
+export declare function getCubeNameFromQuery(query: CubeQuery): string | null;
+/**
+ * Result from extracting binding key values
+ */
+export interface ExtractedBindingKeyValues {
+    /** Binding key values (limited to max if specified) */
+    values: (string | number)[];
+    /** Total count of unique values before limiting */
+    totalCount: number;
+    /** Whether values were truncated due to limit */
+    wasTruncated: boolean;
+}
+/**
+ * Extract unique values for the binding key from query result data
+ *
+ * @deprecated This function was used for client-side funnel execution.
+ * Server-side funnel execution is now the default approach.
+ *
+ * @param data - Raw data from query result
+ * @param bindingKeyField - The field name to extract values from
+ * @param limit - Maximum number of values to return (default: DEFAULT_BINDING_KEY_LIMIT)
+ * @returns Object with values array, total count, and truncation flag
+ */
+export declare function extractBindingKeyValues(data: unknown[], bindingKeyField: string, limit?: number): ExtractedBindingKeyValues;
+/**
+ * Build a step query with binding key filter applied.
+ *
+ * @deprecated This function was used for client-side funnel execution.
+ * Server-side funnel execution is now the default approach.
+ *
+ * For the first step (no previous values), returns the original query
+ * with the binding key dimension ensured.
+ *
+ * For subsequent steps, adds an IN filter for the previous step's
+ * binding key values.
+ *
+ * @param step - The funnel step configuration
+ * @param bindingKey - The funnel binding key configuration
+ * @param previousBindingKeyValues - Binding key values from previous step (null for first step)
+ * @returns Modified CubeQuery with binding key filter
+ */
+export declare function buildStepQuery(step: FunnelStep, bindingKey: FunnelBindingKey, previousBindingKeyValues: (string | number)[] | null): CubeQuery;
+/**
+ * Calculate conversion metrics for a step
+ *
+ * @deprecated This function was used for client-side funnel execution.
+ * Server-side funnel execution now calculates metrics directly.
+ */
+export declare function calculateStepMetrics(currentCount: number, previousCount: number | null, firstStepCount: number): {
+    conversionRate: number | null;
+    cumulativeConversionRate: number;
+};
+/**
+ * Build a funnel step result from query execution
+ *
+ * @deprecated This function was used for client-side funnel execution.
+ * Server-side funnel execution now returns results directly.
+ */
+export declare function buildStepResult(step: FunnelStep, stepIndex: number, data: unknown[], bindingKeyField: string, countUnique: boolean, previousCount: number | null, firstStepCount: number, executionTime: number, error?: Error | null, bindingKeyLimit?: number): FunnelStepResult;
+/**
+ * Convert step results to chart-ready data format
+ *
+ * @deprecated Use transformServerFunnelResult() instead.
+ * Server-side funnel execution returns data in a compatible format.
+ */
+export declare function buildFunnelChartData(stepResults: FunnelStepResult[]): FunnelChartData[];
+/**
+ * Build the complete funnel execution result
+ *
+ * @deprecated This function was used for client-side funnel execution.
+ * Server-side funnel execution now builds results directly.
+ */
+export declare function buildFunnelResult(config: FunnelConfig, stepResults: FunnelStepResult[], status: FunnelExecutionResult['status'], error?: Error | null, currentStepIndex?: number | null): FunnelExecutionResult;
+/**
+ * Create an empty/initial funnel result
+ *
+ * @deprecated This function was used for client-side funnel execution.
+ * Server-side funnel execution manages state differently.
+ */
+export declare function createEmptyFunnelResult(config: FunnelConfig): FunnelExecutionResult;
+/**
+ * Build a FunnelConfig from multi-query config state.
+ * Used to convert AnalysisBuilder state to funnel configuration.
+ *
+ * @deprecated Use the dedicated funnel mode (analysisType === 'funnel') instead.
+ * This function supports backward compatibility with legacy multi-query funnel mode
+ * (mergeStrategy === 'funnel'). For new implementations, use the dedicated funnel
+ * state in the store which provides better UX with step-based configuration.
+ *
+ * @param queries - Array of CubeQuery objects (one per step)
+ * @param bindingKey - The binding key configuration
+ * @param stepLabels - Optional labels for each step
+ * @param stepTimeToConvert - Optional time window for each step
+ * @returns FunnelConfig ready for execution
+ */
+export declare function buildFunnelConfigFromQueries(queries: CubeQuery[], bindingKey: FunnelBindingKey, stepLabels?: string[], stepTimeToConvert?: (string | null)[]): FunnelConfig;
+/**
+ * Check if funnel execution should stop early
+ * (e.g., when no binding key values remain)
+ */
+export declare function shouldStopFunnelExecution(stepResult: FunnelStepResult): boolean;
+/**
+ * Metadata fields injected into funnel result data
+ * (for compatibility with existing chart/table components)
+ */
+export interface FunnelMetadata {
+    __stepIndex: number;
+    __stepName: string;
+    __stepId: string;
+    __conversionRate: number | null;
+    __cumulativeRate: number;
+}
+/**
+ * Check if data contains funnel metadata
+ */
+export declare function isFunnelData(data: unknown[]): boolean;
+/**
+ * Server-side funnel step definition (for FunnelQueryConfig)
+ */
+export interface ServerFunnelStep {
+    name: string;
+    filter?: SimpleFilter | SimpleFilter[];
+    timeToConvert?: string;
+}
+/**
+ * Server-side funnel query configuration
+ */
+export interface ServerFunnelQueryConfig {
+    bindingKey: string | FunnelBindingKeyMapping[];
+    timeDimension: string | Array<{
+        cube: string;
+        dimension: string;
+    }>;
+    steps: ServerFunnelStep[];
+    includeTimeMetrics?: boolean;
+    globalTimeWindow?: string;
+}
+/**
+ * Server-side funnel result row
+ */
+export interface ServerFunnelResultRow {
+    step: string;
+    stepIndex: number;
+    count: number;
+    conversionRate: number | null;
+    cumulativeConversionRate: number;
+    avgSecondsToConvert?: number | null;
+    medianSecondsToConvert?: number | null;
+    p90SecondsToConvert?: number | null;
+    minSecondsToConvert?: number | null;
+    maxSecondsToConvert?: number | null;
+}
+/**
+ * Query shape for server-side funnel execution
+ */
+export interface ServerFunnelQuery {
+    funnel: ServerFunnelQueryConfig;
+}
+/**
+ * Build a server-side funnel query from client state.
+ *
+ * Transforms the client-side FunnelConfig format into a SemanticQuery
+ * with `funnel` property that the server can execute.
+ *
+ * @param queries - Array of CubeQuery objects (one per step)
+ * @param bindingKey - The binding key configuration
+ * @param stepLabels - Optional labels for each step
+ * @param stepTimeToConvert - Optional time window for each step (ISO 8601 duration)
+ * @param includeTimeMetrics - Whether to include time-to-convert metrics
+ * @returns Query object with funnel configuration for server execution
+ */
+export declare function buildServerFunnelQuery(queries: CubeQuery[], bindingKey: FunnelBindingKey, stepLabels?: string[], stepTimeToConvert?: (string | null)[], includeTimeMetrics?: boolean): ServerFunnelQuery;
+/**
+ * Transform server funnel result rows to client FunnelChartData format.
+ *
+ * Maps the server's FunnelResultRow[] to the client's FunnelChartData[]
+ * format expected by FunnelChart component.
+ *
+ * @param serverResult - Raw data from server (FunnelResultRow[])
+ * @param stepNames - Optional step names to override server names
+ * @returns FunnelChartData[] ready for FunnelChart component
+ */
+export declare function transformServerFunnelResult(serverResult: unknown[], stepNames?: string[]): FunnelChartData[];
+/**
+ * Format a duration in seconds to a human-readable string.
+ *
+ * @param seconds - Duration in seconds
+ * @returns Formatted string (e.g., "45s", "2.5m", "1.3h", "3.2d")
+ */
+export declare function formatDuration(seconds: number | null | undefined): string;

package/dist/cjs/client/utils/funnelValidation.d.ts

@@ -0,0 +1,46 @@
+import { CubeQuery, CubeMeta } from '../types.js';
+import { FunnelBindingKey, FunnelConfig, FunnelStep, FunnelValidationError, FunnelValidationResult } from '../types/funnel.js';
+/**
+ * Validate that a binding key dimension exists in the given cubes
+ */
+export declare function validateBindingKeyExists(bindingKey: FunnelBindingKey, meta: CubeMeta | null): FunnelValidationError[];
+/**
+ * Validate that each step has a valid query
+ */
+export declare function validateStepQueries(steps: FunnelStep[]): FunnelValidationError[];
+/**
+ * Check if binding key can be resolved for a given query
+ */
+export declare function canResolveBindingKey(bindingKey: FunnelBindingKey, query: CubeQuery): boolean;
+/**
+ * Validate binding key for all funnel steps
+ */
+export declare function validateBindingKeyForSteps(bindingKey: FunnelBindingKey, steps: FunnelStep[]): FunnelValidationError[];
+/**
+ * Validate time window format (ISO 8601 duration)
+ */
+export declare function validateTimeWindow(duration: string | undefined): FunnelValidationError | null;
+/**
+ * Validate complete funnel configuration
+ */
+export declare function validateFunnelConfig(config: FunnelConfig, meta: CubeMeta | null): FunnelValidationResult;
+/**
+ * Quick check if minimum funnel requirements are met
+ */
+export declare function isMinimumFunnelConfigValid(bindingKey: FunnelBindingKey | null, queryCount: number): {
+    isValid: boolean;
+    message?: string;
+};
+/**
+ * Get available dimensions that can serve as binding keys
+ * These should be dimensions that identify entities (e.g., user IDs, order IDs)
+ */
+export declare function getAvailableBindingKeyDimensions(meta: CubeMeta | null): Array<{
+    cube: string;
+    dimension: string;
+    label: string;
+}>;
+/**
+ * Get the display label for a binding key
+ */
+export declare function getBindingKeyLabel(bindingKey: FunnelBindingKey | null): string;