@stablelab/forse-chart

A CGL component library for internal projects.

Installation

Prerequisites

This library requires the following peer dependencies:

npm install react@^19.1.0 react-dom@^19.1.0
# or
yarn add react@^19.1.0 react-dom@^19.1.0

Setup

1. Add Tailwind CSS

Components are styled using Tailwind CSS. You need to install Tailwind CSS v4 in your project.

Follow the Tailwind CSS installation instructions to get started.

2. Configure GitHub Package Registry

Add a .npmrc file to the root of your project:

cat <<EOF > .npmrc
//npm.pkg.github.com/:_authToken=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
@stablelab:registry=https://npm.pkg.github.com
EOF

3. Install the package

npm install @stablelab/forse-chart
# or
yarn add @stablelab/forse-chart

4. Import the CSS

@import 'tailwindcss';
@import '@stablelab/forse-chart';

5. Add environment variable configurations

• vercelEnv - Vercel environment variable (defaults to 'development')
• apiKey - API key from NEXT_PUBLIC_API_KEY environment variable
• apiDomain - API domain from NEXT_PUBLIC_API_URL environment variable (defaults to 'http://localhost:4000')

6. (Optional) Setup Mixpanel Analytics

If you want to enable Mixpanel tracking in the library, wrap your app with the MixpanelProvider:

npm install mixpanel-browser
# or
yarn add mixpanel-browser

Option 1: Pass mixpanel as prop (recommended)

import mixpanel from 'mixpanel-browser';
import { MixpanelProvider } from '@stablelab/forse-chart';

// Initialize mixpanel in your app first
mixpanel.init('your-mixpanel-token');

function App() {
  return (
    <MixpanelProvider mixpanel={mixpanel}>
      <YourApp />
    </MixpanelProvider>
  );
}

Option 2: Use global mixpanel instance

import mixpanel from 'mixpanel-browser';
import { MixpanelProvider } from '@stablelab/forse-chart';

// Initialize mixpanel globally (available as window.mixpanel)
mixpanel.init('your-mixpanel-token');

function App() {
  return (
    <MixpanelProvider>
      <YourApp />
    </MixpanelProvider>
  );
}

Note:

• Mixpanel is optional. The library will work without it, but tracking events will be logged to console and not sent if Mixpanel is not configured.
• All tracking events are logged to console for debugging purposes.

Usage

Basic Import

import { FoChartLib } from '@stablelab/forse-chart';

function MyComponent() {
  return <FoChartLib></FoChartLib>;
}

Subpath Exports

The library provides subpath exports for better tree-shaking and organization. You can import from specific paths:

Types

import type {
  GenericTimeSeriesGraphApiResponse,
  HasDataPeriod,
} from '@stablelab/forse-chart/types';

Hooks

import { useExportCGLChart, useWindowSize } from '@stablelab/forse-chart/hooks';

API

import {
  getGraphDataByCategoryIdAndGraphId,
  getKpiData,
  getMetaForGraph,
  getTabGroups,
} from '@stablelab/forse-chart/api';

Constants

import {
  bgColor,
  borderColor,
  kpiCard,
  textMain,
  textMainColor,
} from '@stablelab/forse-chart/constants';

Example with Subpath Exports

import { FoChartLib } from '@stablelab/forse-chart';
import { getGraphDataByCategoryIdAndGraphId } from '@stablelab/forse-chart/api';
import { useWindowSize } from '@stablelab/forse-chart/hooks';
import type { GenericTimeSeriesGraphApiResponse } from '@stablelab/forse-chart/types';

function MyComponent() {
  const { width, height } = useWindowSize();
  // ... use the imports
  return <FoChartLib></FoChartLib>;
}

Features

The @stablelab/forse-chart package exports the following. All exports are available from the main package, and many are also available as subpath exports (@stablelab/forse-chart/types, @stablelab/forse-chart/hooks, @stablelab/forse-chart/api, @stablelab/forse-chart/constants) for better tree-shaking:

Legacy Chart Components

• FoChartLib - Legacy chart component
• FoChartLibForOld - Legacy chart component variant
• FoChartLibProps - TypeScript type for FoChartLib props

CGL Components

Main Chart Components

• CGLChart - Main CGL chart component
• CGLChartLib - CGL chart library wrapper
• CGLChartLibProps - TypeScript type for CGLChartLib props
• cglDefaultChartColors - Default colors for CGL charts
• CGLCommentCard - Comment card component
• CGLDonutGauges - Donut, gauges chart component
• CGLGroupTable - Group table component
• CGLHorizontalGauge - Horizontal gauge component
• CGLKpi - KPI component
• CGLSvg - SVG component
• CGLTable - Table component

Custom Components

• FoStatsAccordion - Statistics accordion component

Chart Option Builders

• buildBarOptions - Bar chart options builder
• buildBubbleOption - Bubble chart options builder
• buildEventOption - Event chart options builder
• buildGaugeOption - Gauge chart options builder
• buildHeatmapOption - Heatmap chart options builder
• buildLineOption - Line chart options builder
• buildNetworkGraphOption - Network graph options builder
• buildPieOptions - Pie chart options builder
• buildSankeyOption - Sankey chart options builder
• buildHorizontalBarOption - Horizontal bar chart options builder
• buildHorizontalGaugeOption - Horizontal gauge options builder
• buildGaugeSeries - Multi-gauge series builder
• buildRadarSeries - Radar chart series builder

Sub-components

• CGLDataAsOf - Data timestamp component
• CGLNoteItem - Note item component
• SwipeableNotes - Swipeable notes component
• CGLTabs - Tabs component
• CGLTitle - Title component
• CategoryCombobox - Category combobox component

KPI Sub-components

• KpiInChartType3 - KPI in chart type 3
• KpiInChartType4 - KPI in chart type 4
• KpiSparkLineType5 - KPI sparkline type 5

Tab Group Components

• CustomCells - Custom table cells component
• GATable - GA table component
• TableSearch - Table search component
• CGLGroupSelector - Group selector component
• TabGroupWrapper - Tab group wrapper component

Color Utilities

• createColorHasher - Create color hasher function
• clearColorCaches - Clear color caches function
• getHashedColorBy - Get hashed color by key function

Tooltip Builders

• buildTooltip - Build tooltip function
• buildTooltipFormatter - Build tooltip formatter function
• buildSankeyTooltip - Build Sankey tooltip function
• TooltipItem - TypeScript type for tooltip items

Common UI Components

• Card - Card component
• FoButton - Button component
• FoFilters - Filters component
• Filters - TypeScript type for filters
• FoInput - Input component
• FoLink - Link component
• FoTabs - Tabs component
• FoTooltip - Tooltip component
• Loading - Loading component
• Modal - Modal component
• SearchBox - Search box component
• ShadowWrapper - Shadow wrapper component
• ShadowSize - TypeScript type for shadow sizes
• TablePagination - Table pagination component

Wrapper Components

• FoChartCard - Chart card wrapper component

Other Components

• LegendList - Legend list component
• KpiCard - KPI card component
• FoDownloadScreenshot - Download screenshot component

State Components

• AuthState - Authentication state component
• ErrorState - Error state component
• LoadingState - Loading state component
• MaintenanceState - Maintenance state component
• UnderMaintenance - Under maintenance component
• NoDataState - No data state component

Types

• HasDataPeriod - Interface for data period
• AllPostsCountProd - Interface for posts count production data
• GenericTimeSeriesGraphApiResponse<T> - Generic time series graph API response
• ArbEvent - Interface for arbitrary events
• ArbEventWithSignificance - Interface for events with significance
• GenericEventsResponse<T> - Generic events response
• MetricOptions - Type for metric options
• GenericTimeSeriesObject - Interface for generic time series objects
• UserGroup - Type for user groups
• UserGroupCount - Interface for user group counts
• UserGroupCountResponse - Interface for user group count responses
• UserGroupAggregates - Interface for user group aggregates
• UserGroupAggregationResponse - Interface for user group aggregation responses
• SectorStat - Type for sector statistics
• StipMetadataResponse - Interface for STIP metadata responses
• AiQueryId - Type for AI query IDs
• ProjectTransaction - Type for project transactions
• ProjectData - Type for project data
• DonationActivity - Type for donation activity
• DonationActivitySeries - Type for donation activity series
• DonationActivityResponse - Type for donation activity responses
• GiniCoefficient - Type for Gini coefficient
• JokeraceActivity - Type for Jokerace activity
• JokeraceProjectData - Type for Jokerace project data
• ProcessedJokeRaceActivity - Type for processed Jokerace activity
• ContestParticipant - Type for contest participants
• TooltipFormatterParamsType - Type for tooltip formatter parameters
• TooltipFormatterType - Type for tooltip formatter

Hooks

• useExportCGLChart - Hook for exporting CGL charts
• useWindowSize - Hook for window size
• useMixpanel - Hook for Mixpanel tracking (returns tracking functions)

Mixpanel

• MixpanelProvider - Provider component to initialize Mixpanel with your token
• useMixpanel - Hook to access Mixpanel tracking functions

Store

• createCGLStore - Create CGL store function
• CGLStoreContext - CGL store context
• useCGLStore - Hook to use CGL store
• LegendItem - TypeScript type for legend items
• CGLState - TypeScript type for CGL state
• CGLStore - TypeScript type for CGL store

API

• getMetaForGraph - Get metadata for graph
• getGraphDataByCategoryIdAndGraphId - Get graph data by category and graph ID
• getTabGroups - Get tab groups
• getKpiData - Get KPI data
• getDashboardLabelConfigs - Get dashboard label configurations
• getGraphComments - Get graph comments