npm package: @petal-nexus/toolkit
Description: Production-grade, themeable React components for financial data visualization
Author: Petal
Latest version: 0.3.0

# @petal-nexus/toolkit

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

Built on [SciChart](https://www.scichart.com/) 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](https://www.scichart.com/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 <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:

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

### Custom Themes

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

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

## Technical Indicators

Built-in with `FinancialChart`:

```tsx
<FinancialChart
  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

### Prerequisites

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

### Setup

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

### Scripts

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

### 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:

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

### Publishing Workflow

**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.

### 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