Custom Analytics

Reusable utilities and UI components for querying, reporting, and visualizing analytics data over time. Built on top of the Cube analytics engine via @shared/cube-client.

Public API

The package exports the following from src/index.ts:

Export	Type	Description
PANEL_DICTIONARY	constant	Registry mapping panel type keys (e.g. table, line) to their metadata.
PANEL_DICTIONARY_KEYS	constant	Array of all available panel type keys.
PANEL_DICTIONARY_VALUES	constant	Array of all PanelType entries.
PanelType	type	Interface describing a panel entry (id, value, label, icon, component).
useQueryOptions	hook	React hook that manages Cube query state (dimensions, measures, segments, pagination).
DynamicTable	component	Table panel with sorting and pagination powered by Cube query results.

Project Structure

src/
├── index.ts                  # Public barrel export
├── types.ts                  # PanelType interface
├── constants.tsx              # PANEL_DICTIONARY – maps panel keys to icons & components
├── messages.tsx               # Internationalized labels for each panel type
├── hooks/
│   └── useQueryOptions.ts     # State hook for Cube query parameters
├── services/
│   └── cube/
│       └── query.ts           # useCubeQuery – React Query wrapper around @shared/cube-client
└── components/
    ├── panels/
    │   ├── DynamicTable/       # Sortable, paginated table visualization
    │   └── DynamicLineChart/   # Multi-line chart visualization
    └── states/
        ├── ErrorState/         # Empty-state UI for query errors
        └── LoadingState/       # Skeleton loading placeholders

Key Concepts

Panel Dictionary

PANEL_DICTIONARY is the central registry of visualization types. Each entry contains:

• id / value – unique string identifier (e.g. "table", "line").
• label – internationalized display name.
• icon – Starlight icon component for UI selectors.
• component – React component that renders the visualization.

Note: stackedBarChart, stackedHorizontalBarChart, barChart, and horizontalBar panels are currently placeholder implementations.

useCubeQuery

Internal React Query wrapper (services/cube/query.ts) that calls @shared/cube-client's getAnalyticsCube. It disables retries and enables error boundaries by default.

useQueryOptions

Provides local state for a Cube Query object with sensible defaults:

const { queryOptions, setQueryOptions } = useQueryOptions()
// queryOptions → { dimensions: [], measures: [], segments: [], limit: 25, offset: 0, total: true }

Usage Example

import {
  PANEL_DICTIONARY,
  useQueryOptions,
  DynamicTable,
} from '@shared/custom-analytics'

function MyReport() {
  const { queryOptions, setQueryOptions } = useQueryOptions()

  // Select which panel component to render
  const Panel = PANEL_DICTIONARY.table.component

  return <Panel queryOptions={queryOptions} setQueryOptions={setQueryOptions} />
}

Dependencies

Dependency	Purpose
@shared/cube-client	Cube analytics API client
@shared/charts	Reusable chart components
@rhapsody/localization	Internationalization (i18n)
@starlight/*	Design system (layout, tables, icons, loading, empty-state, tokens)
@tanstack/react-query	Server-state management

Ownership

• Primary: @SalesLoft/analytics-aces
• Additional approvers: @SalesLoft/metric-mavericks