drizzle-cube 0.3.13 → 0.3.16

package/dist/client/components/AnalysisBuilder/AnalysisTypeSelector.d.ts

@@ -1,5 +1,5 @@
 import { default as React } from 'react';
-import { AnalysisType } from '../../types';
+import { AnalysisType, CubeMeta } from '../../types';
 interface AnalysisTypeSelectorProps {
     /** Currently selected analysis type */
     value: AnalysisType;
@@ -7,6 +7,8 @@ interface AnalysisTypeSelectorProps {
     onChange: (type: AnalysisType) => void;
     /** Disable the selector */
     disabled?: boolean;
+    /** Cube metadata for eventStream detection */
+    schema?: CubeMeta | null;
 }
 /**
  * AnalysisTypeSelector - Horizontal tabs for analysis type selection

package/dist/client/components/AnalysisBuilder/RetentionConfigPanel.d.ts

@@ -0,0 +1,36 @@
+import { default as React } from 'react';
+import { CubeMeta, FunnelBindingKey } from '../../types';
+import { DateRange } from '../../types/retention';
+export interface RetentionConfigPanelProps {
+    /** Currently selected cube */
+    selectedCube: string | null;
+    /** Binding key that identifies entities */
+    bindingKey: FunnelBindingKey | null;
+    /** Timestamp dimension for the analysis */
+    timeDimension: string | null;
+    /** Date range for cohort analysis (for collapsed summary display) */
+    dateRange: DateRange;
+    /** Cube metadata for field selection */
+    schema: CubeMeta | null;
+    /** Callback when cube changes */
+    onCubeChange: (cube: string | null) => void;
+    /** Callback when binding key changes */
+    onBindingKeyChange: (bindingKey: FunnelBindingKey | null) => void;
+    /** Callback when timestamp dimension changes */
+    onTimeDimensionChange: (dimension: string | null) => void;
+}
+/**
+ * Date range selector component
+ * Exported for use in RetentionModeContent
+ */
+export interface DateRangeSelectorProps {
+    dateRange: DateRange;
+    onDateRangeChange: (range: DateRange) => void;
+}
+export declare const DateRangeSelector: React.NamedExoticComponent<DateRangeSelectorProps>;
+/**
+ * RetentionConfigPanel displays selectors for cube, binding key, time dimension,
+ * and date range in a collapsible section.
+ */
+declare const RetentionConfigPanel: React.NamedExoticComponent<RetentionConfigPanelProps>;
+export default RetentionConfigPanel;

package/dist/client/components/AnalysisBuilder/RetentionModeContent.d.ts

@@ -0,0 +1,71 @@
+import { CubeMeta, FunnelBindingKey, ChartType, ChartDisplayConfig, Filter } from '../../types';
+import { ColorPalette } from '../../utils/colorPalettes';
+import { DateRange, RetentionGranularity, RetentionType, RetentionBreakdownItem } from '../../types/retention';
+export interface RetentionModeContentProps {
+    /** Currently selected cube for retention analysis */
+    retentionCube: string | null;
+    /** Binding key that links events to entities */
+    retentionBindingKey: FunnelBindingKey | null;
+    /** Time dimension for event ordering */
+    retentionTimeDimension: string | null;
+    /** Date range for cohort analysis */
+    retentionDateRange: DateRange;
+    /** Cohort filters - define who enters the cohort */
+    retentionCohortFilters: Filter[];
+    /** Activity filters - define what counts as a return */
+    retentionActivityFilters: Filter[];
+    /** Breakdown dimensions for segmentation */
+    retentionBreakdowns: RetentionBreakdownItem[];
+    /** Granularity for viewing retention periods */
+    retentionViewGranularity: RetentionGranularity;
+    /** Number of periods to analyze */
+    retentionPeriods: number;
+    /** Retention calculation type */
+    retentionType: RetentionType;
+    /** Cube metadata for field selection */
+    schema: CubeMeta | null;
+    /** Callback when cube changes */
+    onCubeChange: (cube: string | null) => void;
+    /** Callback when binding key changes */
+    onBindingKeyChange: (key: FunnelBindingKey | null) => void;
+    /** Callback when time dimension changes */
+    onTimeDimensionChange: (dim: string | null) => void;
+    /** Callback when date range changes */
+    onDateRangeChange: (range: DateRange) => void;
+    /** Callback when cohort filters change */
+    onCohortFiltersChange: (filters: Filter[]) => void;
+    /** Callback when activity filters change */
+    onActivityFiltersChange: (filters: Filter[]) => void;
+    /** Callback when breakdowns change (set all) */
+    onBreakdownsChange: (breakdowns: RetentionBreakdownItem[]) => void;
+    /** Callback to add a breakdown */
+    onAddBreakdown: (breakdown: RetentionBreakdownItem) => void;
+    /** Callback to remove a breakdown */
+    onRemoveBreakdown: (field: string) => void;
+    /** Callback when granularity changes */
+    onGranularityChange: (granularity: RetentionGranularity) => void;
+    /** Callback when periods changes */
+    onPeriodsChange: (periods: number) => void;
+    /** Callback when retention type changes */
+    onRetentionTypeChange: (type: RetentionType) => void;
+    /** Callback to open field modal for adding breakdowns */
+    onOpenFieldModal?: () => void;
+    /** Chart type for retention display */
+    chartType?: ChartType;
+    /** Callback when chart type changes */
+    onChartTypeChange?: (type: ChartType) => void;
+    /** Display configuration */
+    displayConfig?: ChartDisplayConfig;
+    /** Color palette */
+    colorPalette?: ColorPalette;
+    /** Callback when display config changes */
+    onDisplayConfigChange?: (config: ChartDisplayConfig) => void;
+}
+/**
+ * RetentionModeContent displays the complete retention configuration interface:
+ * - Tabs: Retention | Display
+ * - Retention tab: Config panel + cohort filter + activity filter + breakdown + settings
+ * - Display tab: Heatmap/chart display options
+ */
+declare const RetentionModeContent: import('react').NamedExoticComponent<RetentionModeContentProps>;
+export default RetentionModeContent;

package/dist/client/components/AnalysisBuilder/types.d.ts

@@ -299,6 +299,54 @@ export interface AnalysisQueryPanelProps {
     flowDisplayConfig?: ChartDisplayConfig;
     /** Callback when flow display config changes */
     onFlowDisplayConfigChange?: (config: ChartDisplayConfig) => void;
+    /** Single cube for retention analysis */
+    retentionCube?: string | null;
+    /** Binding key for retention analysis */
+    retentionBindingKey?: import('../../types').FunnelBindingKey | null;
+    /** Single timestamp dimension for retention */
+    retentionTimeDimension?: string | null;
+    /** Date range for cohort analysis (REQUIRED) */
+    retentionDateRange?: import('../../types/retention').DateRange;
+    /** Cohort filters - define who enters the cohort */
+    retentionCohortFilters?: Filter[];
+    /** Activity filters - define what counts as a return */
+    retentionActivityFilters?: Filter[];
+    /** Breakdown dimensions for segmentation */
+    retentionBreakdowns?: import('../../types/retention').RetentionBreakdownItem[];
+    /** Granularity for viewing retention periods */
+    retentionViewGranularity?: import('../../types/retention').RetentionGranularity;
+    /** Number of periods */
+    retentionPeriods?: number;
+    /** Retention type */
+    retentionType?: import('../../types/retention').RetentionType;
+    /** Retention display config */
+    retentionDisplayConfig?: ChartDisplayConfig;
+    /** Callback when cube changes */
+    onRetentionCubeChange?: (cube: string | null) => void;
+    /** Callback when retention binding key changes */
+    onRetentionBindingKeyChange?: (key: import('../../types').FunnelBindingKey | null) => void;
+    /** Callback when time dimension changes */
+    onRetentionTimeDimensionChange?: (dim: string | null) => void;
+    /** Callback when date range changes */
+    onRetentionDateRangeChange?: (range: import('../../types/retention').DateRange) => void;
+    /** Callback when cohort filters change */
+    onRetentionCohortFiltersChange?: (filters: Filter[]) => void;
+    /** Callback when activity filters change */
+    onRetentionActivityFiltersChange?: (filters: Filter[]) => void;
+    /** Callback when breakdowns change (set all) */
+    onRetentionBreakdownsChange?: (breakdowns: import('../../types/retention').RetentionBreakdownItem[]) => void;
+    /** Callback to add a breakdown */
+    onAddRetentionBreakdown?: (breakdown: import('../../types/retention').RetentionBreakdownItem) => void;
+    /** Callback to remove a breakdown */
+    onRemoveRetentionBreakdown?: (field: string) => void;
+    /** Callback when granularity changes */
+    onRetentionViewGranularityChange?: (granularity: import('../../types/retention').RetentionGranularity) => void;
+    /** Callback when periods changes */
+    onRetentionPeriodsChange?: (periods: number) => void;
+    /** Callback when retention type changes */
+    onRetentionTypeChange?: (type: import('../../types/retention').RetentionType) => void;
+    /** Callback when retention display config changes */
+    onRetentionDisplayConfigChange?: (config: ChartDisplayConfig) => void;
 }
 /**
  * Props for the AnalysisResultsPanel component
@@ -429,6 +477,37 @@ export interface AnalysisResultsPanelProps {
         error: Error | null;
         flowMetadata?: unknown;
     } | null;
+    /**
+     * In retention mode, the actual server query { retention: {...} } sent to the API.
+     * Use this for debug display.
+     */
+    retentionServerQuery?: unknown;
+    /**
+     * Unified debug data for retention queries (SQL, analysis, loading/error state).
+     * Contains the CTE-based SQL for the retention analysis.
+     */
+    retentionDebugData?: {
+        sql: {
+            sql: string;
+            params: unknown[];
+        } | null;
+        analysis: unknown;
+        loading: boolean;
+        error: Error | null;
+        retentionMetadata?: unknown;
+    } | null;
+    /**
+     * Retention chart data (cohort × period matrix) for rendering.
+     */
+    retentionChartData?: import('../../types/retention').RetentionChartData | null;
+    /**
+     * Retention validation result (errors explaining why query cannot be built).
+     */
+    retentionValidation?: {
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    } | null;
 }
 /**
  * Props for the MetricsSection component
@@ -580,6 +659,24 @@ export interface AnalysisBuilderInitialFlowState {
     flowChartConfig?: ChartAxisConfig;
     flowDisplayConfig?: ChartDisplayConfig;
 }
+/**
+ * Initial retention state for AnalysisBuilder (matches RetentionSliceState in store)
+ */
+export interface AnalysisBuilderInitialRetentionState {
+    retentionCube?: string | null;
+    retentionBindingKey?: FunnelBindingKey | null;
+    retentionTimeDimension?: string | null;
+    retentionDateRange?: import('../../types/retention').DateRange;
+    retentionCohortFilters?: Filter[];
+    retentionActivityFilters?: Filter[];
+    retentionBreakdowns?: import('../../types/retention').RetentionBreakdownItem[];
+    retentionViewGranularity?: import('../../types/retention').RetentionGranularity;
+    retentionPeriods?: number;
+    retentionType?: import('../../types/retention').RetentionType;
+    retentionChartType?: ChartType;
+    retentionChartConfig?: ChartAxisConfig;
+    retentionDisplayConfig?: ChartDisplayConfig;
+}
 /**
  * Props for the main AnalysisBuilder component
  */
@@ -606,6 +703,8 @@ export interface AnalysisBuilderProps {
     initialFunnelState?: AnalysisBuilderInitialFunnelState;
     /** Initial flow state (when initialAnalysisType === 'flow') */
     initialFlowState?: AnalysisBuilderInitialFlowState;
+    /** Initial retention state (when initialAnalysisType === 'retention') */
+    initialRetentionState?: AnalysisBuilderInitialRetentionState;
     /** Initial data to display (avoids re-fetching when editing existing portlets) */
     initialData?: any[];
     /** Color palette for chart visualization */

package/dist/client/components/DebugModal.d.ts

@@ -1,9 +1,10 @@
 import { FlowChartData } from '../types/flow';
+import { RetentionChartData } from '../types/retention';
 interface DebugModalProps {
     chartConfig: any;
     displayConfig: any;
     queryObject: any;
-    data: any[] | FlowChartData;
+    data: any[] | FlowChartData | RetentionChartData;
     chartType: string;
     cacheInfo?: {
         hit: true;

package/dist/client/components/charts/RetentionCombinedChart.config.d.ts

@@ -0,0 +1,2 @@
+import { ChartTypeConfig } from '../../charts/chartConfigs';
+export declare const retentionCombinedConfig: ChartTypeConfig;

package/dist/client/components/charts/RetentionCombinedChart.d.ts

@@ -0,0 +1,14 @@
+import { default as React } from 'react';
+import { ChartProps } from '../../types';
+/**
+ * Retention display mode
+ * - 'heatmap': Show retention as color-coded bars
+ * - 'line': Show retention as line curves
+ * - 'combined': Show both heatmap background and line overlay
+ */
+export type RetentionDisplayMode = 'heatmap' | 'line' | 'combined';
+/**
+ * RetentionCombinedChart Component
+ */
+declare const RetentionCombinedChart: React.NamedExoticComponent<ChartProps>;
+export default RetentionCombinedChart;

package/dist/client/components/charts/RetentionHeatmap.config.d.ts

@@ -0,0 +1,2 @@
+import { ChartTypeConfig } from '../../charts/chartConfigs';
+export declare const retentionHeatmapConfig: ChartTypeConfig;

package/dist/client/components/charts/RetentionHeatmap.d.ts

@@ -0,0 +1,7 @@
+import { default as React } from 'react';
+import { ChartProps } from '../../types';
+/**
+ * RetentionHeatmap Component
+ */
+declare const RetentionHeatmap: React.NamedExoticComponent<ChartProps>;
+export default RetentionHeatmap;

package/dist/client/components.js

@@ -1,5 +1,5 @@
-import { a as s, A as t, c as r, D as o, M as d, P as i, Q as l } from "./chunks/components-BDrlf9Er.js";
-import { c as b, d as c, b as u, a as y, g as P, v as D } from "./chunks/charts-xNubY0vm.js";
+import { a as s, A as t, c as r, D as o, M as d, P as i, Q as l } from "./chunks/components-BKZ7EAg0.js";
+import { c as b, d as c, b as u, a as y, g as P, v as D } from "./chunks/charts-Dk_9XrA7.js";
 export {
   s as AnalyticsDashboard,
   t as AnalyticsPortlet,

package/dist/client/hooks/queries/index.d.ts

@@ -12,8 +12,9 @@
 export { useCubeMetaQuery, prefetchCubeMeta, CUBE_META_QUERY_KEY, type UseCubeMetaQueryOptions, type UseCubeMetaQueryResult, } from './useCubeMetaQuery';
 export { useCubeLoadQuery, useCubeLoadQuery as useCubeQuery, createQueryKey, type UseCubeLoadQueryOptions, type UseCubeLoadQueryResult, } from './useCubeLoadQuery';
 export { useMultiCubeLoadQuery, createMultiQueryKey, type UseMultiCubeLoadQueryOptions, type UseMultiCubeLoadQueryResult, } from './useMultiCubeLoadQuery';
-export { useDryRunQuery, useMultiDryRunQueries, useDryRunQueries, useFunnelDryRunQuery, useFlowDryRunQuery, createDryRunQueryKey, type DebugDataEntry, type FunnelDebugDataEntry, type FlowDebugDataEntry, type UseDryRunQueryOptions, type UseDryRunQueryResult, type UseMultiDryRunQueriesOptions, type UseMultiDryRunQueriesResult, } from './useDryRunQuery';
+export { useDryRunQuery, useMultiDryRunQueries, useDryRunQueries, useFunnelDryRunQuery, useFlowDryRunQuery, useRetentionDryRunQuery, createDryRunQueryKey, type DebugDataEntry, type FunnelDebugDataEntry, type FlowDebugDataEntry, type RetentionDebugDataEntry, type UseDryRunQueryOptions, type UseDryRunQueryResult, type UseMultiDryRunQueriesOptions, type UseMultiDryRunQueriesResult, } from './useDryRunQuery';
 export { useFunnelQuery, createFunnelQueryKey, } from './useFunnelQuery';
 export { useFlowQuery, createFlowQueryKey, type UseFlowQueryOptions, type UseFlowQueryResult, } from './useFlowQuery';
+export { useRetentionQuery, type UseRetentionQueryOptions, type UseRetentionQueryResult, } from './useRetentionQuery';
 export { useExplainQuery, createExplainQueryKey, type UseExplainQueryOptions, type UseExplainQueryResult, } from './useExplainQuery';
 export { useExplainAI, type UseExplainAIOptions, type UseExplainAIResult, } from './useExplainAI';

package/dist/client/hooks/queries/useDryRunQuery.d.ts

@@ -159,3 +159,29 @@ export declare function useFlowDryRunQuery(serverQuery: unknown | null, options?
     debugData: FlowDebugDataEntry;
     refetch: () => void;
 };
+/**
+ * Debug data entry for retention queries
+ */
+export interface RetentionDebugDataEntry extends DebugDataEntry {
+    /** Retention-specific metadata from server */
+    retentionMetadata?: {
+        totalCohorts: number;
+        totalUsers: number;
+        periods: number;
+        cohortGranularity: string;
+        periodGranularity: string;
+        retentionType: string;
+    };
+}
+/**
+ * TanStack Query hook for retention query dry-run (debug) data
+ *
+ * Usage:
+ * ```tsx
+ * const { debugData } = useRetentionDryRunQuery(serverQuery, { skip: !isRetentionMode })
+ * ```
+ */
+export declare function useRetentionDryRunQuery(serverQuery: unknown | null, options?: UseDryRunQueryOptions): {
+    debugData: RetentionDebugDataEntry;
+    refetch: () => void;
+};

package/dist/client/hooks/queries/useExplainQuery.d.ts

@@ -1,11 +1,13 @@
 import { CubeQuery, ExplainResult, ExplainOptions } from '../../types';
 /**
- * Query type that can be explained - includes standard queries, funnel queries, and flow queries
+ * Query type that can be explained - includes standard queries, funnel queries, flow queries, and retention queries
  */
 export type ExplainableQuery = CubeQuery | {
     funnel: unknown;
 } | {
     flow: unknown;
+} | {
+    retention: unknown;
 } | unknown;
 /**
  * Create a stable query key for explain

package/dist/client/hooks/queries/useFlowQuery.d.ts

@@ -45,6 +45,11 @@ export interface UseFlowQueryResult {
     reset: () => void;
     /** The server query being executed */
     serverQuery: ServerFlowQuery | null;
+    /**
+     * Whether the query needs to be refreshed (manual refresh mode only).
+     * True when the current flow config differs from the last executed query.
+     */
+    needsRefresh: boolean;
 }
 /**
  * Hook for server-side flow query execution

package/dist/client/hooks/queries/useRetentionQuery.d.ts

@@ -0,0 +1,67 @@
+import { ServerRetentionQuery, RetentionChartData, RetentionResultRow } from '../../types/retention';
+/**
+ * Options for retention query hook
+ */
+export interface UseRetentionQueryOptions {
+    /** Skip execution */
+    skip?: boolean;
+    /** Debounce delay in milliseconds */
+    debounceMs?: number;
+    /** Callback when query completes */
+    onComplete?: (result: RetentionChartData) => void;
+    /** Callback when query fails */
+    onError?: (error: Error) => void;
+    /** Function to resolve field names to human-readable display labels */
+    getFieldLabel?: (fieldName: string) => string;
+}
+/**
+ * Result from retention query hook
+ */
+export interface UseRetentionQueryResult {
+    /** Retention chart data */
+    chartData: RetentionChartData | null;
+    /** Raw data rows from server */
+    rawData: RetentionResultRow[] | null;
+    /** Current execution status */
+    status: 'idle' | 'loading' | 'success' | 'error';
+    /** Whether currently loading */
+    isLoading: boolean;
+    /** Whether fetching (includes refetch) */
+    isFetching: boolean;
+    /** Whether waiting for debounce */
+    isDebouncing: boolean;
+    /** Error if execution failed */
+    error: Error | null;
+    /** Cache metadata when served from cache */
+    cacheInfo?: {
+        hit: true;
+        cachedAt: string;
+        ttlMs: number;
+        ttlRemainingMs: number;
+    } | null;
+    /** Execute the query (for manual refresh mode) */
+    execute: (options?: {
+        bustCache?: boolean;
+    }) => Promise<RetentionChartData | null>;
+    /** Refetch the query */
+    refetch: () => void;
+    /**
+     * Whether the query needs to be refreshed (manual refresh mode only).
+     * True when the current query config differs from the last executed query.
+     */
+    needsRefresh: boolean;
+}
+/**
+ * Hook for server-side retention query execution
+ *
+ * Usage:
+ * ```tsx
+ * const { chartData, isLoading, error } = useRetentionQuery(serverQuery, {
+ *   debounceMs: 300,
+ *   skip: !hasRequiredFields
+ * })
+ *
+ * <RetentionHeatmap data={chartData} />
+ * ```
+ */
+export declare function useRetentionQuery(serverQuery: ServerRetentionQuery | null, options?: UseRetentionQueryOptions): UseRetentionQueryResult;

package/dist/client/hooks/useAnalysisBuilderHook.d.ts

@@ -68,6 +68,28 @@ export interface UseAnalysisBuilderResult {
     joinStrategy: 'auto' | 'lateral' | 'window';
     /** Display config for flow mode */
     flowDisplayConfig: ChartDisplayConfig;
+    /** Single cube for retention analysis */
+    retentionCube: string | null;
+    /** Binding key for retention mode */
+    retentionBindingKey: import('../types/funnel').FunnelBindingKey | null;
+    /** Single timestamp dimension for retention mode */
+    retentionTimeDimension: string | null;
+    /** Date range for cohort analysis (REQUIRED) */
+    retentionDateRange: import('../types/retention').DateRange;
+    /** Cohort filters for retention mode */
+    retentionCohortFilters: import('../types').Filter[];
+    /** Activity filters for retention mode */
+    retentionActivityFilters: import('../types').Filter[];
+    /** Optional breakdown dimensions for segmenting the cohort */
+    retentionBreakdowns: import('../types/retention').RetentionBreakdownItem[];
+    /** Granularity for viewing retention periods (day/week/month) */
+    retentionViewGranularity: import('../types/retention').RetentionGranularity;
+    /** Number of periods for retention mode */
+    retentionPeriods: number;
+    /** Retention calculation type */
+    retentionType: import('../types/retention').RetentionType;
+    /** Display config for retention mode */
+    retentionDisplayConfig: ChartDisplayConfig | undefined;
     executionStatus: ExecutionStatus;
     executionResults: unknown[] | null;
     perQueryResults: (unknown[] | null)[] | null;
@@ -76,6 +98,11 @@ export interface UseAnalysisBuilderResult {
     error: Error | null;
     isValidQuery: boolean;
     debugDataPerQuery: DebugDataEntry[];
+    /**
+     * Whether the current query config differs from the last executed query.
+     * Used for manual refresh mode to show "needs refresh" indicator.
+     */
+    needsRefresh: boolean;
     /** In funnel mode, the actually executed queries with binding key dimension and IN filters */
     funnelExecutedQueries: CubeQuery[] | null;
     /** In funnel mode, the actual server query { funnel: {...} } sent to the API */
@@ -104,6 +131,27 @@ export interface UseAnalysisBuilderResult {
         error: Error | null;
         flowMetadata?: unknown;
     } | null;
+    /** In retention mode, the actual server query { retention: {...} } sent to the API */
+    retentionServerQuery: unknown | null;
+    /** In retention mode, unified debug data (SQL, analysis, retention metadata) */
+    retentionDebugData: {
+        sql: {
+            sql: string;
+            params: unknown[];
+        } | null;
+        analysis: unknown | null;
+        loading: boolean;
+        error: Error | null;
+        retentionMetadata?: unknown;
+    } | null;
+    /** In retention mode, the chart data (cohort × period matrix) */
+    retentionChartData: import('../types/retention').RetentionChartData | null;
+    /** In retention mode, validation result (errors explaining why query cannot be built) */
+    retentionValidation: {
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    } | null;
     chartType: ChartType;
     chartConfig: ChartAxisConfig;
     displayConfig: ChartDisplayConfig;
@@ -171,6 +219,19 @@ export interface UseAnalysisBuilderResult {
         setStepsAfter: (count: number) => void;
         setJoinStrategy: (strategy: 'auto' | 'lateral' | 'window') => void;
         setFlowDisplayConfig: (config: ChartDisplayConfig) => void;
+        setRetentionCube: (cube: string | null) => void;
+        setRetentionBindingKey: (key: import('../types/funnel').FunnelBindingKey | null) => void;
+        setRetentionTimeDimension: (dim: string | null) => void;
+        setRetentionDateRange: (range: import('../types/retention').DateRange) => void;
+        setRetentionCohortFilters: (filters: import('../types').Filter[]) => void;
+        setRetentionActivityFilters: (filters: import('../types').Filter[]) => void;
+        setRetentionBreakdowns: (breakdowns: import('../types/retention').RetentionBreakdownItem[]) => void;
+        addRetentionBreakdown: (breakdown: import('../types/retention').RetentionBreakdownItem) => void;
+        removeRetentionBreakdown: (field: string) => void;
+        setRetentionViewGranularity: (granularity: import('../types/retention').RetentionGranularity) => void;
+        setRetentionPeriods: (periods: number) => void;
+        setRetentionType: (type: import('../types/retention').RetentionType) => void;
+        setRetentionDisplayConfig: (config: ChartDisplayConfig) => void;
         setChartType: (type: ChartType) => void;
         setChartConfig: (config: ChartAxisConfig) => void;
         setDisplayConfig: (config: ChartDisplayConfig) => void;

package/dist/client/hooks/useAnalysisQueryExecution.d.ts

@@ -1,8 +1,9 @@
-import { DebugDataEntry, FunnelDebugDataEntry, FlowDebugDataEntry } from './queries';
+import { DebugDataEntry, FunnelDebugDataEntry, FlowDebugDataEntry, RetentionDebugDataEntry } from './queries';
 import { CubeQuery, MultiQueryConfig, FunnelBindingKey, QueryMergeStrategy, AnalysisType } from '../types';
 import { ExecutionStatus } from '../components/AnalysisBuilder/types';
 import { ServerFunnelQuery } from '../types/funnel';
 import { ServerFlowQuery, FlowChartData } from '../types/flow';
+import { ServerRetentionQuery, RetentionChartData } from '../types/retention';
 export interface UseAnalysisQueryExecutionOptions {
     /** Current query (for single-query mode) */
     currentQuery: CubeQuery;
@@ -41,6 +42,20 @@ export interface UseAnalysisQueryExecutionOptions {
      * Used when analysisType === 'flow' with the new dedicated flow state.
      */
     serverFlowQuery?: ServerFlowQuery | null;
+    /**
+     * Pre-built server retention query from store's buildRetentionQuery().
+     * Used when analysisType === 'retention' with the new dedicated retention state.
+     */
+    serverRetentionQuery?: ServerRetentionQuery | null;
+    /**
+     * Validation result for retention mode from store's getRetentionValidation().
+     * Used to display specific errors in the debug panel.
+     */
+    retentionValidation?: {
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    } | null;
 }
 export interface UseAnalysisQueryExecutionResult {
     /** Query execution status */
@@ -94,5 +109,31 @@ export interface UseAnalysisQueryExecutionResult {
      * Contains the flow SQL and flow-specific metadata
      */
     flowDebugData: FlowDebugDataEntry | null;
+    /**
+     * The server retention query being executed (when analysisType === 'retention')
+     */
+    retentionServerQuery: ServerRetentionQuery | null;
+    /**
+     * Retention chart data (cohort × period matrix)
+     */
+    retentionChartData: RetentionChartData | null;
+    /**
+     * Debug data specifically for retention mode
+     * Contains the retention SQL and retention-specific metadata
+     */
+    retentionDebugData: RetentionDebugDataEntry | null;
+    /**
+     * Retention validation result (errors explaining why query cannot be built)
+     */
+    retentionValidation: {
+        isValid: boolean;
+        errors: string[];
+        warnings: string[];
+    } | null;
+    /**
+     * Whether the current query config differs from the last executed query.
+     * Used for manual refresh mode to show "needs refresh" indicator.
+     */
+    needsRefresh: boolean;
 }
 export declare function useAnalysisQueryExecution(options: UseAnalysisQueryExecutionOptions): UseAnalysisQueryExecutionResult;

package/dist/client/hooks.js

@@ -1,6 +1,6 @@
-import { u as s, u as a, k as r, o, n as t, a as y, p as i } from "./chunks/useDirtyStateTracking-C_mitVwh.js";
-import { g as n } from "./chunks/providers-CqCiJTEj.js";
-import { b as D, u as p, a as l } from "./chunks/hooks-B8Zw5PfL.js";
+import { u as s, u as a, k as r, o, n as t, a as y, p as i } from "./chunks/useDirtyStateTracking-ZSi3voVl.js";
+import { g as n } from "./chunks/providers-Cj7PQfXn.js";
+import { b as D, u as p, a as l } from "./chunks/hooks-D7APQ8uS.js";
 export {
   s as useCubeLoadQuery,
   n as useCubeMetaQuery,

package/dist/client/icons/customIcons.d.ts

@@ -13,3 +13,10 @@ export declare const flowIcon: IconifyIcon;
  * 24x24 viewBox, stroke-width 1.5 for clean appearance
  */
 export declare const funnelIcon: IconifyIcon;
+/**
+ * Custom Retention icon
+ * Grid/heatmap pattern representing cohort retention matrix
+ * Shows users tracked across time periods with varying intensity cells
+ * 24x24 viewBox, stroke-width 1.5 for clean appearance
+ */
+export declare const retentionIcon: IconifyIcon;

package/dist/client/icons/types.d.ts

@@ -84,6 +84,7 @@ export interface IconRegistry {
     chartSankey: IconDefinition;
     chartSunburst: IconDefinition;
     chartHeatmap: IconDefinition;
+    chartRetention: IconDefinition;
     measureCount: IconDefinition;
     measureCountDistinct: IconDefinition;
     measureCountDistinctApprox: IconDefinition;

package/dist/client/icons.js

@@ -1,4 +1,4 @@
-import { D as a, g as t, i as o, b as c, c as g, f as I, h as n, a as r, r as y, e as i, s as p } from "./chunks/icons-NzFHtqeM.js";
+import { D as a, a as t, i as o, b as c, c as g, f as I, h as n, g as r, r as y, e as i, s as p } from "./chunks/icons-DRreo6m8.js";
 export {
   a as DEFAULT_ICONS,
   t as getChartTypeIcon,