@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

``bash
npm install @petal-nexus/toolkit scichart
`

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

Quick Start

`tsx
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 ;
}
`

Available Charts

$3

CandlestickChart · FinancialChart · TimeSeriesChart · VolumeChart · DepthChart · PerformanceBarChart

$3

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

$3

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

$3

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

$3

PriceTargetChart · EstimateTrendChart · EstimateGrowthChart · AnalystUpgradesChart · DividendsChart · MarketCapChart

$3

DonutChart · TreemapChart · SparklineMatrixChart

Theming

All charts support three built-in theme presets:

`tsx
// Default


`

$3

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

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

Technical Indicators

Built-in with FinancialChart:

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

Or use calculation utilities directly:

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

Utilities

`typescript
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:

`typescript
import { SciChartSurface } from 'scichart';

SciChartSurface.setRuntimeLicenseKey('YOUR_LICENSE_KEY');
`

---

Development

$3

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

$3

`bash
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

`

$3

`bash


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
`

$3

`
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

$3

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

`bash
CHROMATIC_PROJECT_TOKEN=your_chromatic_token
`

2. Log in to npm:

`bash
npm login
`

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

$3

ALWAYS commit and push BEFORE publishing to npm.

`bash


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.

$3

- 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