drizzle-cube 0.6.1 → 0.6.2

package/dist/cjs/client/types/drill.d.ts

@@ -0,0 +1,240 @@
+import { MouseEvent } from 'react';
+import { CubeQuery, Filter, TimeGranularity, ChartAxisConfig } from '../types.js';
+/**
+ * Event fired when a user clicks on a data point in a chart
+ * Generic across all chart types (bar, line, pie, etc.)
+ */
+export interface ChartDataPointClickEvent {
+    /**
+     * The clicked data point values (from the transformed chart data)
+     * Contains all fields for the clicked row
+     * @example { name: '2024-01', 'Revenue': 50000, 'Orders': 120 }
+     */
+    dataPoint: Record<string, unknown>;
+    /**
+     * Which field/series was clicked (typically a y-axis field or measure)
+     * @example 'Orders.totalRevenue'
+     */
+    clickedField: string;
+    /**
+     * The x-axis value (category/time value)
+     * @example '2024-01' or 'Electronics'
+     */
+    xValue: unknown;
+    /**
+     * Screen coordinates for positioning drill menu/popover
+     */
+    position: {
+        x: number;
+        y: number;
+    };
+    /**
+     * Original mouse event for additional context
+     */
+    nativeEvent?: MouseEvent;
+}
+/**
+ * Drill option types
+ * - drillDown: Navigate to more granular level
+ * - drillUp: Navigate to less granular level (roll-up)
+ * - details: Show underlying records via drillMembers
+ */
+export type DrillOptionType = 'drillDown' | 'drillUp' | 'details';
+/**
+ * Where to apply the drill action
+ * - portlet: Only affects the current chart/portlet
+ * - dashboard: Updates a dashboard filter, affecting all mapped portlets
+ */
+export type DrillScope = 'portlet' | 'dashboard';
+/**
+ * A single drill option shown in the drill menu
+ */
+export interface DrillOption {
+    /** Unique identifier for this option */
+    id: string;
+    /**
+     * Display label
+     * @example "Drill to Week", "Show Order Details", "Roll up to Quarter"
+     */
+    label: string;
+    /** Type of drill action */
+    type: DrillOptionType;
+    /**
+     * Icon to display
+     * - 'time': For time granularity changes
+     * - 'hierarchy': For dimension hierarchy navigation
+     * - 'table': For showing detail records
+     */
+    icon?: 'time' | 'hierarchy' | 'table';
+    /**
+     * Which hierarchy this option belongs to (if type is drillDown/drillUp for hierarchies)
+     * @example 'location', 'product'
+     */
+    hierarchy?: string;
+    /**
+     * Target time granularity (for time-based drill)
+     * @example 'week', 'day', 'month'
+     */
+    targetGranularity?: TimeGranularity;
+    /**
+     * Target dimension (for hierarchy-based drill)
+     * @example 'Orders.city', 'Products.subcategory'
+     */
+    targetDimension?: string;
+    /**
+     * Where to apply this drill action
+     */
+    scope: DrillScope;
+    /**
+     * Dashboard filter ID to update (when scope is 'dashboard')
+     */
+    dashboardFilterId?: string;
+    /**
+     * Measure being drilled (for context)
+     */
+    measure?: string;
+}
+/**
+ * Entry in the drill navigation path (breadcrumb)
+ * Tracks the history of drill actions for back-navigation
+ */
+export interface DrillPathEntry {
+    /** Unique identifier */
+    id: string;
+    /**
+     * Display label for the breadcrumb
+     * @example "All Time", "Q1 2024", "January 2024"
+     */
+    label: string;
+    /**
+     * The query state at this level
+     */
+    query: CubeQuery;
+    /**
+     * Filters applied at this level (for restoration on back-nav)
+     */
+    filters?: Filter[];
+    /**
+     * Time granularity at this level (for time-based drill)
+     */
+    granularity?: TimeGranularity;
+    /**
+     * Active dimension at this level (for hierarchy-based drill)
+     */
+    dimension?: string;
+    /**
+     * Which hierarchy was used (if any)
+     */
+    hierarchy?: string;
+    /**
+     * The clicked value that led to this drill
+     * @example '2024-01', 'Electronics'
+     */
+    clickedValue?: unknown;
+    /**
+     * Chart configuration override for this drill level
+     * Used when drilling to details to map drillMembers to chart axes
+     */
+    chartConfig?: ChartAxisConfig;
+}
+/**
+ * Result of building a drill query
+ */
+export interface DrillResult {
+    /** The new query to execute */
+    query: CubeQuery;
+    /** Context about the drill for breadcrumb/navigation */
+    pathEntry: DrillPathEntry;
+    /**
+     * Filter to apply at dashboard level (when scope is 'dashboard')
+     */
+    dashboardFilter?: {
+        id: string;
+        filter: Filter;
+    };
+    /**
+     * Chart configuration override for this drill
+     * When drilling to details, maps drillMembers to chart axes
+     */
+    chartConfig?: ChartAxisConfig;
+}
+/**
+ * Configuration for the useDrillInteraction hook
+ */
+export interface UseDrillInteractionOptions {
+    /** Current query being displayed */
+    query: CubeQuery;
+    /** Cube metadata for computing drill options */
+    metadata: import('../types.js').CubeMeta | null;
+    /** Callback when query changes due to drill */
+    onQueryChange: (query: CubeQuery) => void;
+    /** Current chart configuration (to restore on drill up to root) */
+    chartConfig?: ChartAxisConfig;
+    /** Dashboard filters context (for dashboard-level drill) */
+    dashboardFilters?: import('../types.js').DashboardFilter[];
+    /** Which dashboard filters apply to this portlet */
+    dashboardFilterMapping?: import('../types.js').DashboardFilterMapping;
+    /** Callback to update a dashboard filter */
+    onDashboardFilterChange?: (filterId: string, filter: import('../types.js').Filter) => void;
+    /** Whether drill is enabled (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Return type of useDrillInteraction hook
+ */
+export interface DrillInteraction {
+    /** Handler to pass to chart's onDataPointClick prop */
+    handleDataPointClick: (event: ChartDataPointClickEvent) => void;
+    /** Whether the drill menu is currently open */
+    menuOpen: boolean;
+    /** Position for the drill menu */
+    menuPosition: {
+        x: number;
+        y: number;
+    } | null;
+    /** Available drill options for the clicked data point */
+    menuOptions: DrillOption[];
+    /** Handler for when user selects a drill option */
+    handleOptionSelect: (option: DrillOption) => void;
+    /** Close the drill menu */
+    closeMenu: () => void;
+    /** Current drill navigation path (for breadcrumb) */
+    drillPath: DrillPathEntry[];
+    /** Navigate back one level */
+    navigateBack: () => void;
+    /** Navigate to a specific level in the path */
+    navigateToLevel: (index: number) => void;
+    /** Whether any drill options are available for the current query/metadata */
+    drillEnabled: boolean;
+    /** Whether the current dimension matches a dashboard filter */
+    hasDashboardFilterMatch: boolean;
+    /** Current chart config override from drill (null if using original config) */
+    currentChartConfig: ChartAxisConfig | null;
+}
+/**
+ * Props for the DrillMenu component
+ */
+export interface DrillMenuProps {
+    /** Available drill options */
+    options: DrillOption[];
+    /** Position for the menu */
+    position: {
+        x: number;
+        y: number;
+    };
+    /** Handler when an option is selected */
+    onSelect: (option: DrillOption) => void;
+    /** Handler to close the menu */
+    onClose: () => void;
+}
+/**
+ * Props for the DrillBreadcrumb component
+ */
+export interface DrillBreadcrumbProps {
+    /** Drill path entries */
+    path: DrillPathEntry[];
+    /** Handler when navigating back */
+    onNavigate: () => void;
+    /** Handler when clicking a specific level */
+    onLevelClick?: (index: number) => void;
+}

package/dist/cjs/client/types/flow.d.ts

@@ -0,0 +1,191 @@
+import { Filter } from '../types.js';
+import { FunnelBindingKey } from './funnel.js';
+/**
+ * Starting step definition for flow analysis
+ * The starting step is the anchor point from which we explore paths
+ * in both directions (before and after)
+ */
+export interface FlowStartingStep {
+    /** Display name for the starting step */
+    name: string;
+    /** Filters that define which events qualify as the starting step */
+    filters: Filter[];
+}
+/**
+ * Server flow query format
+ * This is the shape sent to the server for execution
+ * Wrapped in { flow: {...} } similar to funnel queries
+ */
+export interface ServerFlowQuery {
+    flow: FlowQueryConfig;
+}
+/**
+ * Flow query configuration
+ * Contains all parameters needed for server-side flow analysis
+ */
+export interface FlowQueryConfig {
+    /**
+     * Binding key that identifies individual entities (e.g., userId)
+     * Can be a single string like 'Events.userId' or array for multi-cube
+     */
+    bindingKey: string | {
+        cube: string;
+        dimension: string;
+    }[];
+    /**
+     * Time dimension used for ordering events
+     * Can be a single string like 'Events.timestamp' or array for multi-cube
+     */
+    timeDimension: string | {
+        cube: string;
+        dimension: string;
+    }[];
+    /**
+     * The starting step from which we explore paths
+     * Defines the anchor point for bidirectional flow analysis
+     */
+    startingStep: {
+        /** Display name for the starting step */
+        name: string;
+        /** Filter(s) that identify events for this starting step */
+        filter?: Filter | Filter[];
+    };
+    /** Number of steps to explore BEFORE the starting step (0-5) */
+    stepsBefore: number;
+    /** Number of steps to explore AFTER the starting step (0-5) */
+    stepsAfter: number;
+    /**
+     * Event dimension that categorizes events (e.g., 'Events.eventType')
+     * This dimension's values become the node labels in the Sankey diagram
+     */
+    eventDimension: string;
+    /**
+     * Optional limit on the number of entities to process
+     * Useful for performance on large datasets
+     */
+    entityLimit?: number;
+    /**
+     * Output mode for flow data aggregation
+     * - 'sankey': Aggregate by (layer, event_type) - standard flow visualization where paths can converge
+     * - 'sunburst': Path-qualified nodes for hierarchical tree visualization where each path is unique
+     * @default 'sankey'
+     */
+    outputMode?: 'sankey' | 'sunburst';
+    /**
+     * Join strategy for fetching steps
+     * - 'auto' (default): use lateral when supported, otherwise window
+     * - 'lateral': force lateral joins
+     * - 'window': force window function strategy
+     */
+    joinStrategy: 'auto' | 'lateral' | 'window';
+}
+/**
+ * A node in the Sankey diagram
+ * Represents an event type at a specific layer (distance from starting step)
+ */
+export interface SankeyNode {
+    /**
+     * Unique identifier for this node
+     * Format: "before_{depth}_{eventType}" or "after_{depth}_{eventType}" or "start_{eventType}"
+     * Examples: "before_2_Signup", "start_Purchase", "after_1_Checkout"
+     */
+    id: string;
+    /** Display name (typically the event type value) */
+    name: string;
+    /**
+     * Layer position in the Sankey diagram
+     * Negative for steps before starting step, 0 for starting step, positive for after
+     * Example: -2, -1, 0, 1, 2 for a flow with 2 steps before and 2 after
+     */
+    layer: number;
+    /** Total count of entities passing through this node */
+    value?: number;
+}
+/**
+ * A link (edge) in the Sankey diagram
+ * Represents a transition between two nodes
+ */
+export interface SankeyLink {
+    /** Source node ID */
+    source: string;
+    /** Target node ID */
+    target: string;
+    /** Count of entities that follow this path */
+    value: number;
+}
+/**
+ * Complete flow result row returned from server
+ * Contains the full Sankey diagram data
+ */
+export interface FlowResultRow {
+    nodes: SankeyNode[];
+    links: SankeyLink[];
+}
+/**
+ * Chart-ready flow data format
+ * Same structure as FlowResultRow, used for chart components
+ */
+export interface FlowChartData {
+    nodes: SankeyNode[];
+    links: SankeyLink[];
+}
+/**
+ * Flow mode state for the AnalysisBuilder store
+ * Contains all UI state needed to configure a flow analysis
+ */
+export interface FlowSliceState {
+    /** Selected cube for flow analysis (must be an eventStream cube) */
+    flowCube: string | null;
+    /** Binding key that identifies entities (reuses funnel binding key type) */
+    flowBindingKey: FunnelBindingKey | null;
+    /** Time dimension for ordering events */
+    flowTimeDimension: string | null;
+    /** Starting step configuration */
+    startingStep: FlowStartingStep;
+    /** Number of steps to explore before starting step (0-5, default 3) */
+    stepsBefore: number;
+    /** Number of steps to explore after starting step (0-5, default 3) */
+    stepsAfter: number;
+    /** Event dimension that categorizes events */
+    eventDimension: string | null;
+    /** Join strategy for flow execution */
+    joinStrategy: 'auto' | 'lateral' | 'window';
+}
+/**
+ * Flow slice actions for the store
+ */
+export interface FlowSliceActions {
+    setFlowCube: (cube: string | null) => void;
+    setFlowBindingKey: (key: FunnelBindingKey | null) => void;
+    setFlowTimeDimension: (dim: string | null) => void;
+    setEventDimension: (dim: string | null) => void;
+    setStartingStepName: (name: string) => void;
+    setStartingStepFilters: (filters: Filter[]) => void;
+    addStartingStepFilter: (filter: Filter) => void;
+    removeStartingStepFilter: (index: number) => void;
+    updateStartingStepFilter: (index: number, filter: Filter) => void;
+    setStepsBefore: (count: number) => void;
+    setStepsAfter: (count: number) => void;
+    setJoinStrategy: (strategy: 'auto' | 'lateral' | 'window') => void;
+    isFlowMode: () => boolean;
+    isFlowModeEnabled: () => boolean;
+    buildFlowQuery: () => ServerFlowQuery | null;
+}
+/**
+ * Type guard to check if data is Sankey/Flow chart data
+ */
+export declare function isSankeyData(data: unknown): data is FlowChartData;
+/**
+ * Type guard to detect server flow query format
+ * Used to distinguish { flow: {...} } from CubeQuery, MultiQueryConfig, or ServerFunnelQuery
+ */
+export declare function isServerFlowQuery(obj: unknown): obj is ServerFlowQuery;
+/**
+ * Default flow slice state for store initialization
+ */
+export declare const defaultFlowSliceState: FlowSliceState;
+/**
+ * Minimum and maximum values for step depth
+ */
+export declare const FLOW_MIN_DEPTH = 0;
+export declare const FLOW_MAX_DEPTH = 5;