@petal-nexus/toolkit

Production-grade, themeable React components for financial data visualization — 41 charts from candlesticks to cash flow waterfalls.

Built on SciChart for high-performance charting with 100K+ data points.

Features

• 41 Chart Components - Core trading charts, financial statements, analyst charts, composition displays
• Smart Axis Labels - Auto-detects data granularity (daily vs intraday) and formats appropriately
• 3 Theme Presets - Dark, light, and navy themes with full customization support
• Technical Indicators - Built-in SMA, EMA, MACD, RSI calculations
• TypeScript - Full type safety with comprehensive interfaces
• Tree-shakeable - Import only what you need

Installation

npm install @petal-nexus/toolkit scichart

Note: SciChart requires a license key for production use. See SciChart Licensing.

Quick Start

import { CandlestickChart } from '@petal-nexus/toolkit';

const data = [
  { date: new Date('2024-01-01'), open: 100, high: 105, low: 98, close: 103, volume: 1000000 },
  { date: new Date('2024-01-02'), open: 103, high: 108, low: 101, close: 106, volume: 1200000 },
];

function App() {
  return <CandlestickChart data={data} height={400} themePreset="dark" />;
}

Available Charts

Core Charts (6)

CandlestickChart · FinancialChart · TimeSeriesChart · VolumeChart · DepthChart · PerformanceBarChart

Income Statement (8)

MarginAnalysisChart · EPSGrowthChart · RevenueGrowthWaterfallChart · CostStructureChart · RDInvestmentChart · TaxRateChart · OperatingLeverageChart · GrowthHeatmapChart

Balance Sheet (11)

DebtToEquityChart · CurrentRatioChart · CapitalStructureChart · WorkingCapitalChart · DebtStructureChart · CashInvestmentsChart · RetainedEarningsChart · SharesOutstandingChart · AssetCompositionChart · AssetEfficiencyChart · BookValueChart

Cash Flow (7)

FcfRangeBandChart · OcfWaterfallChart · CapitalAllocationChart · ShareholderReturnsChart · CashConversionChart · CapexDepreciationChart · InvestmentHeatmapChart

Analyst (6)

PriceTargetChart · EstimateTrendChart · EstimateGrowthChart · AnalystUpgradesChart · DividendsChart · MarketCapChart

Composition (3)

DonutChart · TreemapChart · SparklineMatrixChart

Theming

All charts support three built-in theme presets:

<FinancialChart data={data} themePreset="dark" />   // Default
<FinancialChart data={data} themePreset="light" />
<FinancialChart data={data} themePreset="navy" />

Custom Themes

import { createTheme, petalDark } from '@petal-nexus/toolkit';

const myTheme = createTheme(
  {
    colors: {
      positive: '#00ff00',
      negative: '#ff0000',
    },
  },
  petalDark
);

Technical Indicators

Built-in with FinancialChart:

<FinancialChart
  data={data}
  showMA={true}
  maType="ema"
  maPeriod={20}
  showMACD={true}
  showRSI={true}
  showVolume={true}
/>

Or use calculation utilities directly:

import { calculateSMA, calculateEMA, calculateMACD, calculateRSI } from '@petal-nexus/toolkit';

Utilities

import {
  formatCurrency, // $1,234,567.00
  formatPercent, // 12.34%
  formatVolume, // 1.5M
  formatAxisLabel, // Smart date/time formatting
  toUnixTimestamp,
  fromUnixTimestamp,
} from '@petal-nexus/toolkit';

SciChart Setup

Configure your SciChart license before rendering charts:

import { SciChartSurface } from 'scichart';

SciChartSurface.setRuntimeLicenseKey('YOUR_LICENSE_KEY');

Development

Prerequisites

• Node.js >= 22
• npm >= 10

Setup

git clone https://github.com/Petal-Nexus-Inc/petal-toolkit.git
cd petal-toolkit
npm install

# Optional: Set up environment variables for Chromatic
cp .env.example .env
# Edit .env and add your CHROMATIC_PROJECT_TOKEN

Scripts

# Development - runs Storybook on http://localhost:6006
npm run dev

# Build library for npm
npm run build

# Type checking
npm run typecheck

# Linting
npm run lint
npm run lint:fix

# Testing
npm test
npm run test:ui
npm run test:coverage

# Build Storybook static site
npm run build:storybook

Project Structure

petal-toolkit/
├── src/                    # Library source code
│   ├── charts/             # All chart components
│   ├── scichart/           # SciChart utilities & themes
│   ├── themes/             # Theme system
│   ├── hooks/              # React hooks
│   ├── utils/              # Utilities & formatters
│   └── index.ts            # Main exports
├── stories/                # Storybook stories (dev only)
├── dist/                   # Built library (npm package)
└── storybook-static/       # Built Storybook (for hosting)

Publishing to npm

First Time Setup

1. Create a .env file in the project root:

   CHROMATIC_PROJECT_TOKEN=your_chromatic_token

2. Log in to npm:

   npm login

3. Ensure you have access to the @petal organization on npm

Publishing Workflow

ALWAYS commit and push BEFORE publishing to npm.

# 1. Make your changes and commit them
git add .
git commit -m "Your changes"

# 2. Run CI checks (same order as GitHub Actions)
npm run lint
npm run format:check    # Fails if files aren't formatted
npm run typecheck
npm test
npm run build
npm run build:storybook

# 3. Deploy Storybook to Chromatic (visual regression testing)
npx chromatic --build-script-name=build:storybook

# 4. Bump version (creates a git commit + tag automatically)
npm version patch       # 0.1.0 → 0.1.1 (bug fixes)
# OR
npm version minor       # 0.1.0 → 0.2.0 (new features)
# OR
npm version major       # 0.1.0 → 1.0.0 (breaking changes)

# 5. Push commits and tags to git
git push && git push --tags

# 6. Preview what will be published
npm pack --dry-run

# NOTE: be sure to login right here to be safe
npm login

# 7. Publish to npm
npm publish

Tip: If format:check fails, run npm run format to fix all files, then commit.

Why this order?

• Git becomes the source of truth
• npm registry matches git tags
• Rollbacks are easier if something goes wrong
• CI/CD can verify commits before publish

Browser Support

• Chrome, Firefox, Safari, Edge (latest 2 versions)
• WebAssembly required (for SciChart)

License

MIT