drizzle-cube 0.6.1 → 0.6.3

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

@@ -0,0 +1,94 @@
+import { PortletConfig, DashboardConfig } from '../types.js';
+export * from './chartUtils.js';
+export * from './chartConstants.js';
+export * from './measureIcons.js';
+export * from './periodUtils.js';
+export * from './pivotUtils.js';
+export * from './syntaxHighlighting.js';
+export * from './comparisonUtils.js';
+export { captureThumbnail, isThumbnailCaptureAvailable } from './thumbnail.js';
+export { exportPortletToXlsx, isExportAvailable } from './exportXlsx.js';
+/**
+ * Create a dashboard layout from portlet configurations
+ */
+export declare function createDashboardLayout(portlets: PortletConfig[]): DashboardConfig;
+/**
+ * Generate responsive layouts for different breakpoints
+ */
+export declare function generateResponsiveLayouts(portlets: PortletConfig[]): {
+    lg: {
+        i: string;
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+        minW: number;
+        minH: number;
+    }[];
+    md: {
+        w: number;
+        i: string;
+        x: number;
+        y: number;
+        h: number;
+        minW: number;
+        minH: number;
+    }[];
+    sm: {
+        w: number;
+        i: string;
+        x: number;
+        y: number;
+        h: number;
+        minW: number;
+        minH: number;
+    }[];
+    xs: {
+        w: number;
+        i: string;
+        x: number;
+        y: number;
+        h: number;
+        minW: number;
+        minH: number;
+    }[];
+    xxs: {
+        w: number;
+        i: string;
+        x: number;
+        y: number;
+        h: number;
+        minW: number;
+        minH: number;
+    }[];
+};
+/**
+ * Format chart data for display
+ */
+export declare function formatChartData(data: any[], options?: {
+    formatNumbers?: boolean;
+    precision?: number;
+}): any[];
+/**
+ * Generate a unique ID for new portlets
+ */
+export declare function generatePortletId(): string;
+/**
+ * Find the next available position in a grid
+ */
+export declare function findNextPosition(existingPortlets: PortletConfig[], _w?: number, _h?: number): {
+    x: number;
+    y: number;
+};
+/**
+ * Validate a cube query JSON string
+ */
+export declare function validateCubeQuery(queryString: string): {
+    valid: boolean;
+    error?: string;
+    query?: any;
+};
+/**
+ * Create a sample portlet configuration
+ */
+export declare function createSamplePortlet(): Omit<PortletConfig, 'id'>;

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

@@ -0,0 +1,27 @@
+import { CubeMeta, CubeMetaDimension, PortletConfig } from '../types.js';
+/**
+ * Compute the set of cubes reachable from the given start cubes via join
+ * relationships. Relationships are treated as undirected, mirroring the
+ * server's bidirectional join resolution. Start cubes are included.
+ */
+export declare function getReachableCubes(meta: CubeMeta | null, startCubes: string[]): Set<string>;
+/**
+ * Get the cube names referenced by a portlet's query (measures, dimensions,
+ * timeDimensions) across single-query, multi-query, and funnel shapes.
+ */
+export declare function getPortletQueryCubes(portlet: PortletConfig): string[];
+export interface ReachableDimensionGroup {
+    cubeName: string;
+    cubeTitle: string;
+    dimensions: CubeMetaDimension[];
+}
+/**
+ * Get the dimensions a dashboard filter can be remapped to for a portlet:
+ * dimensions of join-reachable cubes, grouped by cube. When `sameTypeAs` is a
+ * known dimension, options are restricted to dimensions of the same type
+ * (operator and values are shared across portlets, so the target field must
+ * be type-compatible).
+ */
+export declare function getReachableDimensionOptions(meta: CubeMeta | null, portlet: PortletConfig, options?: {
+    sameTypeAs?: string;
+}): ReachableDimensionGroup[];

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

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+/**
+ * Get the appropriate icon component for a given measure type
+ * All icons use amber coloring for consistency
+ */
+export declare function getMeasureIcon(measureType: string | undefined, className?: string): React.ReactElement;
+/**
+ * Get all available measure type icons
+ * Useful for documentation or UI that shows all measure types
+ */
+export declare function getAllMeasureIcons(): Record<string, React.ReactElement>;

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

@@ -0,0 +1,86 @@
+import { CubeResultSet, CubeQuery, QueryMergeStrategy } from '../types.js';
+/**
+ * Metadata fields injected into multi-query data
+ */
+export interface MultiQueryMetadata {
+    __queryIndex: number;
+    __queryLabel: string;
+}
+/**
+ * Check if data contains multi-query metadata
+ */
+export declare function isMultiQueryData(data: unknown[]): boolean;
+/**
+ * Get unique query labels from multi-query data
+ */
+export declare function getQueryLabels(data: unknown[]): string[];
+/**
+ * Get query indices from multi-query data
+ */
+export declare function getQueryIndices(data: unknown[]): number[];
+/**
+ * Merge results using 'concat' strategy
+ * Appends all rows with __queryIndex and __queryLabel metadata
+ *
+ * @param resultSets - Array of CubeResultSet from each query
+ * @param queries - Original CubeQuery objects
+ * @param labels - Optional user-defined labels per query
+ * @returns Merged data array with query metadata
+ */
+export declare function mergeResultsConcat(resultSets: CubeResultSet[], _queries: CubeQuery[], labels?: string[]): unknown[];
+/**
+ * Merge results using 'merge' strategy
+ * Aligns data by common dimensions (composite key), combining measures from all queries
+ *
+ * Example:
+ *   Query 1: [{ date: '2024-01', revenue: 100 }]
+ *   Query 2: [{ date: '2024-01', cost: 50 }]
+ *   Result:  [{ date: '2024-01', revenue: 100, cost: 50 }]
+ *
+ * If multiple queries have the same measure, the first query's value is used.
+ *
+ * @param resultSets - Array of CubeResultSet from each query
+ * @param queries - Original CubeQuery objects
+ * @param mergeKeys - Dimension fields to align data on (composite key)
+ * @param _labels - Optional user-defined labels per query (unused, kept for API compatibility)
+ * @returns Merged data array with combined measures
+ */
+export declare function mergeResultsByKey(resultSets: CubeResultSet[], queries: CubeQuery[], mergeKeys: string[], _labels?: string[]): unknown[];
+/**
+ * Main entry point for merging query results
+ * Delegates to appropriate strategy implementation
+ *
+ * @param resultSets - Array of CubeResultSet from each query
+ * @param queries - Original CubeQuery objects
+ * @param strategy - Merge strategy ('concat' or 'merge')
+ * @param mergeKeys - Dimension fields to align on (required for 'merge' strategy)
+ * @param labels - Optional user-defined labels per query
+ * @returns Merged data array
+ */
+export declare function mergeQueryResults(resultSets: CubeResultSet[], queries: CubeQuery[], strategy: QueryMergeStrategy, mergeKeys?: string[], labels?: string[]): unknown[];
+/**
+ * Get combined fields from all queries
+ * Used for chart configuration to show all available measures/dimensions
+ *
+ * @param queries - Array of CubeQuery objects
+ * @param _labels - Optional user-defined labels per query (unused, kept for API compatibility)
+ * @returns Object containing combined measures, dimensions, and time dimensions
+ */
+export declare function getCombinedFields(queries: CubeQuery[], _labels?: string[]): {
+    measures: string[];
+    dimensions: string[];
+    timeDimensions: string[];
+};
+/**
+ * Generate a default label for a query based on its measures
+ * Used when user doesn't provide custom labels
+ */
+export declare function generateQueryLabel(query: CubeQuery, index: number): string;
+/**
+ * Validate merge key exists in all queries
+ * Returns validation result with details
+ */
+export declare function validateMergeKey(queries: CubeQuery[], mergeKey: string): {
+    isValid: boolean;
+    missingInQueries: number[];
+};

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

@@ -0,0 +1,69 @@
+import { CubeQuery, QueryMergeStrategy } from '../types.js';
+type TimeDimension = NonNullable<CubeQuery['timeDimensions']>[number];
+/**
+ * Validation error for multi-query configuration
+ */
+export interface MultiQueryValidationError {
+    type: 'missing_time_dimension' | 'granularity_mismatch' | 'missing_merge_key';
+    queryIndex: number;
+    message: string;
+    details?: {
+        field?: string;
+        expectedGranularity?: string;
+        actualGranularity?: string;
+    };
+}
+/**
+ * Validation warning for multi-query configuration
+ */
+export interface MultiQueryValidationWarning {
+    type: 'measure_collision' | 'asymmetric_date_range';
+    queryIndices: number[];
+    message: string;
+    affectedMeasures?: string[];
+}
+/**
+ * Result of multi-query validation
+ */
+export interface MultiQueryValidationResult {
+    isValid: boolean;
+    errors: MultiQueryValidationError[];
+    warnings: MultiQueryValidationWarning[];
+}
+/**
+ * Extract time dimension info from a query
+ */
+export declare function extractTimeDimensions(query: CubeQuery): TimeDimension[];
+/**
+ * Validate that all queries have matching time dimension granularities
+ * Only relevant for 'merge' strategy where data needs to align
+ */
+export declare function validateTimeDimensionAlignment(queries: CubeQuery[]): MultiQueryValidationError[];
+/**
+ * Validate that merge keys exist in all queries
+ */
+export declare function validateMergeKeys(queries: CubeQuery[], mergeKeys: string[]): MultiQueryValidationError[];
+/**
+ * Detect when the same measure appears in multiple queries
+ * This is a warning since the first value wins in merge mode
+ */
+export declare function detectMeasureCollisions(queries: CubeQuery[]): MultiQueryValidationWarning[];
+/**
+ * Check if queries have different date ranges
+ */
+export declare function detectAsymmetricDateRanges(queries: CubeQuery[]): MultiQueryValidationWarning[];
+/**
+ * Validate a multi-query configuration
+ * For 'merge' strategy: strict validation (errors block execution)
+ * For 'concat' and 'funnel' strategies: only warnings
+ */
+export declare function validateMultiQueryConfig(queries: CubeQuery[], mergeStrategy: QueryMergeStrategy, mergeKeys?: string[]): MultiQueryValidationResult;
+/**
+ * Check if a multi-query configuration is valid for execution
+ */
+export declare function isMultiQueryValid(queries: CubeQuery[]): boolean;
+/**
+ * Get human-readable validation summary
+ */
+export declare function getValidationSummary(result: MultiQueryValidationResult): string;
+export {};

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

@@ -0,0 +1,40 @@
+/**
+ * Utility functions for detecting incomplete time periods in KPI charts
+ */
+/**
+ * Get the end date of a period based on granularity
+ * @param date - The date within the period
+ * @param granularity - The time granularity (day, week, month, quarter, year)
+ * @returns The end date of the period (end of day)
+ */
+export declare function getPeriodEndDate(date: Date, granularity: string): Date;
+/**
+ * Check if the last period in the data is complete based on granularity
+ * @param lastDataPoint - The last data point in the sorted dataset
+ * @param timeDimensionField - The field name containing the time value
+ * @param granularity - The time granularity
+ * @returns true if the period is complete, false if it's incomplete
+ */
+export declare function isLastPeriodComplete(lastDataPoint: any, timeDimensionField: string, granularity: string): boolean;
+/**
+ * Extract granularity from a query object
+ * @param queryObject - The CubeQuery object
+ * @param dimensionField - Optional specific dimension field to match
+ * @returns The granularity string or null if not found
+ */
+export declare function getQueryGranularity(queryObject: any, dimensionField?: string): string | null;
+/**
+ * Filter data to exclude incomplete or last period
+ * @param data - The data array sorted by time
+ * @param timeDimensionField - The field containing time values
+ * @param queryObject - The query object containing timeDimensions
+ * @param useLastCompletePeriod - Whether to check for incomplete periods
+ * @param skipLastPeriod - Whether to always skip the last period (overrides useLastCompletePeriod)
+ * @returns Object with filtered data and whether filtering was applied
+ */
+export declare function filterIncompletePeriod(data: any[], timeDimensionField: string | undefined, queryObject: any, useLastCompletePeriod: boolean, skipLastPeriod?: boolean): {
+    filteredData: any[];
+    excludedIncompletePeriod: boolean;
+    skippedLastPeriod: boolean;
+    granularity: string | null;
+};

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

@@ -0,0 +1,87 @@
+import { CubeQuery, CubeMeta } from '../types.js';
+/**
+ * Derives ordered column list from a CubeQuery object.
+ * Order: dimensions, timeDimensions (as field names), measures
+ *
+ * @param queryObject The CubeQuery object
+ * @returns Array of field names in order
+ */
+export declare function getOrderedColumnsFromQuery(queryObject?: CubeQuery): string[];
+/**
+ * Configuration for pivoting based on query structure
+ */
+export interface PivotConfig {
+    /** Time dimension field name (e.g., "Sales.date") */
+    timeDimension: string;
+    /** Time granularity (e.g., "month", "day", "year") */
+    granularity: string;
+    /** Non-time dimension fields */
+    dimensions: string[];
+    /** Measure fields */
+    measures: string[];
+}
+/**
+ * Column definition for pivoted table
+ */
+export interface PivotColumn {
+    /** Column key for data access */
+    key: string;
+    /** Display label for column header */
+    label: string;
+    /** Whether this is a time column (vs row identifier column) */
+    isTimeColumn: boolean;
+    /** Whether this is the measure column */
+    isMeasureColumn?: boolean;
+}
+/**
+ * Row in the pivoted table
+ */
+export interface PivotRow {
+    /** Unique row identifier */
+    id: string;
+    /** The measure field name (for icon lookup) */
+    measureField: string;
+    /** Values keyed by column key */
+    values: Record<string, any>;
+    /** Whether this is the first row in a dimension group (for row spanning) */
+    isFirstInGroup?: boolean;
+    /** Number of rows to span for dimension cells (only set on first row in group) */
+    dimensionRowSpan?: number;
+}
+/**
+ * Result of pivoting table data
+ */
+export interface PivotedTableData {
+    /** Whether data was pivoted (has time dimension with granularity) */
+    isPivoted: boolean;
+    /** Column definitions for the pivoted table */
+    columns: PivotColumn[];
+    /** Rows of pivoted data */
+    rows: PivotRow[];
+}
+/**
+ * Determines if a query has a time dimension with granularity that should trigger pivoting
+ * @param queryObject The CubeQuery object
+ * @param xAxisOverride Optional array of fields to use for filtering dimensions and measures
+ *                      (for respecting chartConfig.xAxis configuration)
+ * @returns PivotConfig if pivoting should occur, null otherwise
+ */
+export declare function hasTimeDimensionForPivot(queryObject?: CubeQuery, xAxisOverride?: string[]): PivotConfig | null;
+/**
+ * Pivots flat data into time-columned table structure
+ *
+ * @param data Raw data array from query result
+ * @param config Pivot configuration
+ * @param getFieldLabel Function to get display label for a field
+ * @param meta Optional cube metadata for looking up measure types
+ * @returns Pivoted table data structure
+ */
+export declare function pivotTableData(data: any[], config: PivotConfig, getFieldLabel: (field: string) => string, _meta?: CubeMeta | null): PivotedTableData;
+/**
+ * Looks up the measure type from metadata
+ *
+ * @param measureField The fully qualified measure field name (e.g., "Sales.revenue")
+ * @param meta Cube metadata
+ * @returns The measure type (e.g., "sum", "count", "avg") or undefined
+ */
+export declare function getMeasureType(measureField: string, meta: CubeMeta | null): string | undefined;

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

@@ -0,0 +1,61 @@
+import { AnalysisConfig } from '../types/analysisConfig.js';
+export type { AnalysisConfig as ShareableState };
+/**
+ * Result of compression with fallback
+ */
+export interface CompressionResult {
+    encoded: string | null;
+    queryOnly: boolean;
+}
+/**
+ * Compress AnalysisConfig to URL-safe encoded string
+ */
+export declare function compressAndEncode(config: AnalysisConfig): string;
+/**
+ * Decompress URL-safe encoded string back to AnalysisConfig
+ * Returns null if decompression, parsing, or validation fails.
+ *
+ * Note: This does not support legacy share URL formats (breaking change).
+ */
+export declare function decodeAndDecompress(encoded: string): AnalysisConfig | null;
+/**
+ * Check if compressed config fits within URL length limit
+ */
+export declare function isShareableSize(config: AnalysisConfig): {
+    ok: boolean;
+    size: number;
+    maxSize: number;
+};
+/**
+ * Compress config with automatic fallback
+ * If full config is too large, tries with query only (preserving essential fields)
+ * Returns null encoded if even query-only is too large
+ */
+export declare function compressWithFallback(config: AnalysisConfig): CompressionResult;
+/**
+ * Generate full share URL with compressed config in hash
+ */
+export declare function generateShareUrl(config: AnalysisConfig): string | null;
+/**
+ * Parse share hash from current URL
+ * Returns encoded string if #share= is present, null otherwise
+ */
+export declare function parseShareHash(): string | null;
+/**
+ * Clear share hash from URL without page reload
+ */
+export declare function clearShareHash(): void;
+/**
+ * Get the maximum allowed hash length
+ */
+export declare function getMaxHashLength(): number;
+/**
+ * Create a share URL from store's save() method output
+ * This is the primary entry point for creating share URLs.
+ */
+export declare function createShareUrl(config: AnalysisConfig): string | null;
+/**
+ * Parse and validate share URL, returning AnalysisConfig or null
+ * This is the primary entry point for loading from share URLs.
+ */
+export declare function parseShareUrl(): AnalysisConfig | null;

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

@@ -0,0 +1,36 @@
+/**
+ * Syntax Highlighting Utility
+ *
+ * Lazy-loads highlight.js only when needed for syntax highlighting in debug panels.
+ * This minimizes bundle size impact since syntax highlighting is not needed on initial load.
+ *
+ * Usage:
+ *   await highlightCodeBlocks()
+ */
+/**
+ * Lazy-loads highlight.js and registers supported languages.
+ * Only loads once - subsequent calls return immediately.
+ */
+export declare function loadSyntaxHighlighter(): Promise<void>;
+/**
+ * Highlights all code blocks on the page that haven't been highlighted yet.
+ * Gracefully handles cases where highlight.js fails to load.
+ */
+export declare function highlightCodeBlocks(): Promise<void>;
+/**
+ * Highlights a specific code block element.
+ * Useful for dynamically added content.
+ *
+ * @param element - The code block element to highlight
+ */
+export declare function highlightCodeBlock(element: HTMLElement): Promise<void>;
+/**
+ * Returns whether syntax highlighting is available.
+ * Useful for conditional rendering or feature detection.
+ */
+export declare function isSyntaxHighlightingAvailable(): boolean;
+/**
+ * Returns the loaded highlight.js instance, if available.
+ * Useful for custom highlighting flows that need direct access.
+ */
+export declare function getSyntaxHighlighter(): any | null;

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

@@ -0,0 +1,36 @@
+/**
+ * Utility functions for handling target values in charts
+ */
+/**
+ * Parse target values from string format
+ * @param targetString - String containing target values (e.g., "100" or "50,75,100")
+ * @returns Array of numeric target values
+ */
+export declare function parseTargetValues(targetString: string): number[];
+/**
+ * Spread target values across data points
+ * @param targets - Array of target values
+ * @param dataLength - Number of data points to spread across
+ * @returns Array of target values for each data point
+ */
+export declare function spreadTargetValues(targets: number[], dataLength: number): number[];
+/**
+ * Calculate variance between actual and target values
+ * @param actual - Actual value
+ * @param target - Target value
+ * @returns Variance as percentage
+ */
+export declare function calculateVariance(actual: number, target: number): number;
+/**
+ * Format variance as percentage string with appropriate sign and color indication
+ * @param variance - Variance percentage
+ * @param decimals - Number of decimal places (default: 1)
+ * @returns Formatted variance string (e.g., "+12.5%" or "-8.3%")
+ */
+export declare function formatVariance(variance: number, decimals?: number): string;
+/**
+ * Get unique target values for reference lines
+ * @param targets - Array of target values (may contain duplicates)
+ * @returns Array of unique target values
+ */
+export declare function getUniqueTargets(targets: number[]): number[];

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

@@ -0,0 +1,36 @@
+import { RefObject } from 'react';
+import { ThumbnailFeatureConfig } from '../types.js';
+declare global {
+    interface Window {
+        __drizzle_cube_thumbnail_warning__?: boolean;
+    }
+}
+/**
+ * Log a development-mode warning when thumbnail feature is enabled but modern-screenshot is missing
+ */
+export declare function warnIfScreenshotLibMissing(thumbnailConfig: ThumbnailFeatureConfig | undefined): void;
+/**
+ * Capture a thumbnail of the dashboard element
+ *
+ * @param elementRef - React ref to the dashboard container element
+ * @param config - Thumbnail configuration (dimensions, format, quality)
+ * @returns Base64 data URI of the thumbnail, or null if capture failed
+ */
+export declare function captureThumbnail(elementRef: RefObject<HTMLElement | null>, config: ThumbnailFeatureConfig): Promise<string | null>;
+/**
+ * Check if thumbnail capture is available and enabled
+ */
+export declare function isThumbnailCaptureAvailable(config: ThumbnailFeatureConfig | undefined): Promise<boolean>;
+/**
+ * Check if portlet screenshot-to-clipboard is available.
+ * Requires both modern-screenshot AND Clipboard API with image support.
+ */
+export declare function isPortletCopyAvailable(): Promise<boolean>;
+/**
+ * Capture a portlet element and copy to clipboard as PNG.
+ * Returns true on success, false on failure.
+ *
+ * @param element - The HTML element to capture
+ * @returns Promise<boolean> - true if successfully copied to clipboard
+ */
+export declare function copyPortletToClipboard(element: HTMLElement): Promise<boolean>;

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

@@ -0,0 +1,32 @@
+/**
+ * Helpers for `formatTimeValue` — parsing timestamp strings and formatting
+ * them by known or inferred granularity. Split out of chartUtils to keep
+ * each unit small.
+ */
+/**
+ * Components of a parsed UTC timestamp used for granularity formatting.
+ */
+export interface TimestampParts {
+    date: Date;
+    year: number;
+    month: string;
+    day: string;
+    hours: number;
+    minutes: number;
+}
+/**
+ * Parse a timestamp string (ISO or PostgreSQL format) into UTC parts.
+ * Returns null if the string isn't a recognizable timestamp or is invalid.
+ */
+export declare function parseTimestampParts(str: string): TimestampParts | null;
+/**
+ * Format parsed timestamp parts using an explicit granularity.
+ * Returns null for an unknown granularity so the caller can fall back to the
+ * heuristic formatter.
+ */
+export declare function formatByGranularity(parts: TimestampParts, granularity: string): string | null;
+/**
+ * Infer a display string for parsed timestamp parts when no explicit
+ * granularity is known, based on which time components are non-zero.
+ */
+export declare function formatByHeuristic(parts: TimestampParts): string;

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

@@ -0,0 +1,8 @@
+/**
+ * Drizzle Cube Utilities
+ *
+ * Utility functions only - for applications that need helper functions
+ * without any UI components.
+ */
+export * from './utils/index.js';
+export type {} from './types.js';

package/dist/cjs/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "commonjs"
+}