@pipsend/charts/README.md

Advanced financial charting library with built-in technical indicators - Simple, powerful, and framework-agnostic

# 📊 Pipsend Charts

[![npm version](https://img.shields.io/npm/v/@pipsend/charts.svg?style=flat-square)](https://www.npmjs.com/package/@pipsend/charts)
[![npm downloads](https://img.shields.io/npm/dm/@pipsend/charts.svg?style=flat-square)](https://www.npmjs.com/package/@pipsend/charts)
[![License](https://img.shields.io/badge/License-Dual%20License-blue.svg?style=flat-square)](LICENSE)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue?style=flat-square&logo=typescript)](https://www.typescriptlang.org/)
[![Bundle Size](https://img.shields.io/bundlephobia/minzip/@pipsend/charts?style=flat-square)](https://bundlephobia.com/package/@pipsend/charts)

**Professional Financial Charting Library with 10+ Technical Indicators & Interactive Trading Tools**

Simple • Powerful • Framework-Agnostic • TypeScript

---

## 📑 Table of Contents

- [Why Pipsend Charts?](#-why-pipsend-charts)
- [Installation](#-installation)
- [Quick Start](#-quick-start)
- [Demo & Examples](#-demo--examples)
- [Available Technical Indicators](#-available-technical-indicators)
- [Interactive Trading Lines API](#-interactive-trading-lines-api)
- [Framework Integration Examples](#-framework-integration-examples)
- [Full API Reference](#-full-api-reference)
- [Real-World Example](#-real-world-example)
- [Customization](#-customization)
- [Browser Support](#-browser-support)
- [Performance](#-performance)
- [Troubleshooting](#-troubleshooting)
- [FAQ](#-faq)
- [Roadmap](#-roadmap)
- [Contributing](#-contributing)
- [Changelog](#-changelog)
- [License](#-license)

---

## 🚀 Why Pipsend Charts?

**Pipsend Charts** is a high-performance financial charting library designed for professional trading applications. Built on TradingView's Lightweight Charts™, enhanced with:

✅ **10 Technical Indicators** - SMA, EMA, WMA, RSI, MACD, Stochastic, Bollinger Bands, ATR, Volume, OBV  
✅ **Interactive Trading Lines** - Draggable Stop Loss & Take Profit with click-to-create  
✅ **Functional API** - One function call per indicator, auto-updating  
✅ **Framework Agnostic** - Works with React, Vue, Angular, Svelte, or vanilla JS  
✅ **Lightweight** - ~49KB gzipped, minimal dependencies  
✅ **TypeScript Native** - Full type safety and autocomplete  
✅ **High Performance** - 60 FPS on thousands of data points  

---

## 🎬 Demo & Examples

### Live Examples

Explore interactive examples to see Pipsend Charts in action:

- **[Basic Indicators Demo](./examples/indicators.html)** - See all 10 technical indicators working together
- **[Trading Lines Demo](./examples/trading-lines.html)** - Interactive Stop Loss & Take Profit lines
- **[Advanced Trading Lines](./examples/trading-lines-advanced.html)** - Click-to-create and advanced features

### Screenshots

![PipsendCharts Clean](image.png)
![PipsendCharts Indicators](image-1.png)
![PipsendCharts Trading Lines](image-2.png)

```
📊 Candlestick Chart with SMA & EMA
📈 RSI & MACD Oscillators
🎯 Interactive Trading Lines
🌙 Dark & Light Themes
```

### Quick Preview

```javascript
// Create a professional trading chart in 3 lines
const chart = createChart(document.getElementById('chart'));
const series = chart.addSeries(CandlestickSeries);
applySMA(series, chart, { period: 20 }); // Add moving average
```

---

## 📦 Installation

### Package Managers

```bash
# npm
npm install @pipsend/charts

# yarn
yarn add @pipsend/charts

# pnpm
pnpm add @pipsend/charts

# bun
bun add @pipsend/charts
```

### CDN

```html
<!-- Production (Minified) -->
<script src="https://unpkg.com/@pipsend/charts/dist/pipsend-charts.standalone.production.js"></script>

<!-- Development (with warnings) -->
<script src="https://unpkg.com/@pipsend/charts/dist/pipsend-charts.standalone.development.js"></script>
```

### Requirements

- **Node.js**: >= 22.3 (for development)
- **Browsers**: Modern browsers with ES2015+ support (see [Browser Support](#-browser-support))

---

## 🎯 Quick Start

### Basic Candlestick Chart

```javascript
import { createChart, CandlestickSeries } from '@pipsend/charts';

const chart = createChart(document.getElementById('chart'), {
    width: 800,
    height: 600
});

const candleSeries = chart.addSeries(CandlestickSeries, {
    upColor: '#26a69a',
    downColor: '#ef5350'
});

candleSeries.setData([
    { time: '2024-01-01', open: 100, high: 105, low: 95, close: 102 },
    { time: '2024-01-02', open: 102, high: 108, low: 100, close: 106 },
]);
```

### Adding Technical Indicators

```javascript
import { 
    createChart, 
    CandlestickSeries,
    applySMA,
    applyRSI,
    applyMACD
} from '@pipsend/charts';

const chart = createChart(document.getElementById('chart'));
const series = chart.addSeries(CandlestickSeries);
series.setData(historicalData);

// Add SMA (Simple Moving Average) - appears on main chart
applySMA(series, chart, { period: 20, color: '#2196F3' });

// Add RSI - appears in separate panel
applyRSI(series, chart, { period: 14, color: '#9C27B0' });

// Add MACD - appears in separate panel
applyMACD(series, chart, { 
    fastPeriod: 12, 
    slowPeriod: 26, 
    signalPeriod: 9 
});
```

### Interactive Trading Lines (100% Configurable)

```javascript
import { 
    createTradingLine,
    createInteractiveLineManager 
} from '@pipsend/charts';

// Stop Loss (draggable by default)
const stopLoss = createTradingLine(series, chart, {
    price: 95.00,
    type: 'stop-loss',
    onDragEnd: (price) => {
        console.log('Stop Loss updated:', price);
        // Update your order in backend
    }
});

// Take Profit (draggable by default)
const takeProfit = createTradingLine(series, chart, {
    price: 110.00,
    type: 'take-profit',
    onDragEnd: (price) => console.log('TP:', price)
});

// Price Alert - Fully customizable
const alert = createTradingLine(series, chart, {
    price: 100.00,
    title: 'Price Alert',
    color: '#FFC107',
    lineStyle: LineStyle.Dotted,
    onDragEnd: (price) => api.updateAlert(price)
});

// Click-to-create: Create lines by clicking on chart
const manager = createInteractiveLineManager(chart, series);

// Create Stop Loss with click
document.getElementById('btnSL').onclick = async () => {
    await manager.enableClickToCreate('stop-loss');
};

// Create custom Alert with click
document.getElementById('btnAlert').onclick = async () => {
    await manager.enableClickToCreate('custom', {
        title: 'Alert',
        color: '#FFC107',
        onDragEnd: (price) => api.createAlert(price)
    });
};
```

**All lines are draggable and fully configurable** - Use them for Stop Loss, Take Profit, Alerts, Targets, Resistance/Support, or anything you need!

---

## 📊 Available Technical Indicators

### Overlay Indicators (appear on main chart)

#### 1. SMA - Simple Moving Average
```javascript
import { applySMA } from '@pipsend/charts';

applySMA(series, chart, {
    period: 20,
    color: '#2196F3'
});
```

#### 2. EMA - Exponential Moving Average
```javascript
import { applyEMA } from '@pipsend/charts';

applyEMA(series, chart, {
    period: 12,
    color: '#FF9800'
});
```

#### 3. WMA - Weighted Moving Average
```javascript
import { applyWMA } from '@pipsend/charts';

applyWMA(series, chart, {
    period: 20,
    color: '#4CAF50'
});
```

#### 4. Bollinger Bands
```javascript
import { applyBollingerBands } from '@pipsend/charts';

applyBollingerBands(series, chart, {
    period: 20,
    stdDev: 2
});
```

### Panel Indicators (appear in separate panels)

#### 5. RSI - Relative Strength Index
```javascript
import { applyRSI } from '@pipsend/charts';

applyRSI(series, chart, {
    period: 14,
    color: '#9C27B0'
});
```

#### 6. MACD - Moving Average Convergence Divergence
```javascript
import { applyMACD } from '@pipsend/charts';

applyMACD(series, chart, {
    fastPeriod: 12,
    slowPeriod: 26,
    signalPeriod: 9
});
```

#### 7. Stochastic Oscillator
```javascript
import { applyStochastic } from '@pipsend/charts';

applyStochastic(series, chart, {
    kPeriod: 14,
    dPeriod: 3
});
```

#### 8. ATR - Average True Range
```javascript
import { applyATR } from '@pipsend/charts';

applyATR(series, chart, {
    period: 14,
    color: '#FF9800'
});
```

#### 9. Volume
```javascript
import { applyVolume, setVolumeData } from '@pipsend/charts';

// First, set volume data
setVolumeData(series, chartData);

// Then apply volume indicator
applyVolume(series, chart, {
    colorUp: '#26a69a',
    colorDown: '#ef5350'
});
```

#### 10. OBV - On-Balance Volume
```javascript
import { applyOBV, setOBVVolumeData } from '@pipsend/charts';

// First, set volume data
setOBVVolumeData(series, chartData);

// Then apply OBV indicator
applyOBV(series, chart, {
    color: '#673AB7'
});
```

---

## 🎯 Interactive Trading Lines API

### Draggable Stop Loss / Take Profit

```javascript
import { 
    createTradingLine,
    createInteractiveLineManager
} from '@pipsend/charts';

// 1. Stop Loss with preset
const stopLoss = createTradingLine(series, chart, {
    price: 95.00,
    type: 'stop-loss',
    onDragStart: (price) => console.log('Drag started'),
    onDragMove: (price) => console.log('Moving:', price),
    onDragEnd: (price) => console.log('Final:', price)
});

// 2. Take Profit with preset
const takeProfit = createTradingLine(series, chart, {
    price: 110.00,
    type: 'take-profit',
    onDragEnd: (price) => updateOrderInBackend(price)
});

// 3. Entry Line (non-draggable)
const entry = createTradingLine(series, chart, {
    price: 100.00,
    type: 'entry'
});

// 4. Custom line with full control
const customLine = createTradingLine(series, chart, {
    price: 105.00,
    title: 'Target 1',
    color: '#FF9800',
    lineStyle: LineStyle.Dashed,
    lineWidth: 2,
    draggable: true,
    onDragEnd: (price) => console.log('Custom line:', price)
});

// 5. Interactive Click-to-Create
const manager = createInteractiveLineManager(chart, series);

// Button to activate click mode
document.getElementById('addStopLoss').onclick = async () => {
    const line = await manager.enableClickToCreate('stop-loss');
    // User clicks on chart, line is created at that price
};

document.getElementById('addTakeProfit').onclick = async () => {
    await manager.enableClickToCreate('take-profit');
};
```

### Line Methods

```javascript
// Get current price
const currentPrice = stopLoss.getPrice();

// Update price programmatically
stopLoss.setPrice(93.00);

// Update options
stopLoss.applyOptions({
    color: '#FF0000',
    title: 'New Stop Loss'
});

// Remove line
stopLoss.remove();
```

---

## 🌐 Framework Integration Examples

### React

```tsx
import { useEffect, useRef } from 'react';
import { createChart, CandlestickSeries, applySMA, applyRSI } from '@pipsend/charts';

function TradingChart({ data }) {
    const chartContainerRef = useRef<HTMLDivElement>(null);
    const chartRef = useRef<any>(null);
    const seriesRef = useRef<any>(null);

    useEffect(() => {
        if (!chartContainerRef.current) return;

        // Create chart
        chartRef.current = createChart(chartContainerRef.current, {
            width: chartContainerRef.current.clientWidth,
            height: 600
        });

        // Add series
        seriesRef.current = chartRef.current.addSeries(CandlestickSeries);
        seriesRef.current.setData(data);

        // Add indicators
        applySMA(seriesRef.current, chartRef.current, { period: 20 });
        applyRSI(seriesRef.current, chartRef.current, { period: 14 });

        // Cleanup
        return () => {
            if (chartRef.current) {
                chartRef.current.remove();
            }
        };
    }, []);

    // Update data when it changes
    useEffect(() => {
        if (seriesRef.current && data) {
            seriesRef.current.setData(data);
        }
    }, [data]);

    return <div ref={chartContainerRef} />;
}
```

### Vue 3

```vue
<template>
  <div ref="chartContainer"></div>
</template>

<script setup>
import { ref, onMounted, onUnmounted, watch } from 'vue';
import { createChart, CandlestickSeries, applyMACD } from '@pipsend/charts';

const props = defineProps(['data']);
const chartContainer = ref(null);
let chart = null;
let series = null;

onMounted(() => {
    chart = createChart(chartContainer.value, {
        width: chartContainer.value.clientWidth,
        height: 600
    });

    series = chart.addSeries(CandlestickSeries);
    series.setData(props.data);

    // Add MACD
    applyMACD(series, chart, {
        fastPeriod: 12,
        slowPeriod: 26,
        signalPeriod: 9
    });
});

watch(() => props.data, (newData) => {
    if (series) {
        series.setData(newData);
    }
});

onUnmounted(() => {
    if (chart) {
        chart.remove();
    }
});
</script>
```

### Angular

```typescript
import { Component, ElementRef, Input, OnInit, OnDestroy, ViewChild } from '@angular/core';
import { createChart, CandlestickSeries, applyBollingerBands } from '@pipsend/charts';

@Component({
  selector: 'app-trading-chart',
  template: '<div #chartContainer></div>'
})
export class TradingChartComponent implements OnInit, OnDestroy {
  @ViewChild('chartContainer') chartContainer!: ElementRef;
  @Input() data: any[];

  private chart: any;
  private series: any;

  ngOnInit() {
    this.chart = createChart(this.chartContainer.nativeElement, {
      width: this.chartContainer.nativeElement.clientWidth,
      height: 600
    });

    this.series = this.chart.addSeries(CandlestickSeries);
    this.series.setData(this.data);

    // Add Bollinger Bands
    applyBollingerBands(this.series, this.chart, {
      period: 20,
      stdDev: 2
    });
  }

  ngOnDestroy() {
    if (this.chart) {
      this.chart.remove();
    }
  }
}
```

### Svelte

```svelte
<script>
    import { onMount, onDestroy } from 'svelte';
    import { createChart, CandlestickSeries, applyStochastic } from '@pipsend/charts';

    export let data;

    let chartContainer;
    let chart;
    let series;

    onMount(() => {
        chart = createChart(chartContainer, {
            width: chartContainer.clientWidth,
            height: 600
        });

        series = chart.addSeries(CandlestickSeries);
        series.setData(data);

        // Add Stochastic
        applyStochastic(series, chart, {
            kPeriod: 14,
            dPeriod: 3
        });
    });

    $: if (series && data) {
        series.setData(data);
    }

    onDestroy(() => {
        if (chart) {
            chart.remove();
        }
    });
</script>

<div bind:this={chartContainer}></div>
```

### Vanilla JavaScript

```javascript
import { 
    createChart, 
    CandlestickSeries,
    applySMA,
    applyRSI,
    createTradingLine
} from '@pipsend/charts';

// Create chart
const chart = createChart(document.getElementById('chart'), {
    width: 800,
    height: 600
});

// Add candlestick series
const series = chart.addSeries(CandlestickSeries);
series.setData(historicalData);

// Add indicators
applySMA(series, chart, { period: 50, color: '#FF6D00' });
applyRSI(series, chart, { period: 14 });

// Add trading lines
const stopLoss = createTradingLine(series, chart, {
    price: 95.00,
    type: 'stop-loss',
    onDragEnd: (price) => {
        document.getElementById('slPrice').textContent = price.toFixed(2);
    }
});
```

---

## 📚 Full API Reference

### Chart Creation

```typescript
import { createChart } from '@pipsend/charts';

const chart = createChart(container: HTMLElement, options?: {
    width?: number;
    height?: number;
    layout?: {
        background?: { color: string };
        textColor?: string;
    };
    grid?: {
        vertLines?: { color: string };
        horzLines?: { color: string };
    };
    // ... more options
});
```

### Indicator Options

All indicators support these common options:

```typescript
{
    period?: number;        // Calculation period
    color?: string;         // Line color
    lineWidth?: number;     // Line width
    visible?: boolean;      // Show/hide indicator
}
```

### Trading Line Options

```typescript
{
    price: number;                          // Required: Line price
    color?: string;                         // Line color
    lineWidth?: number;                     // Line width (1-4)
    lineStyle?: LineStyle;                  // Solid, Dashed, etc.
    title?: string;                         // Label text
    axisLabelVisible?: boolean;             // Show price on axis
    draggable?: boolean;                    // Enable dragging
    onDragStart?: (price: number) => void;  // Drag start callback
    onDragMove?: (price: number) => void;   // Drag move callback
    onDragEnd?: (price: number) => void;    // Drag end callback
}
```

---

## 🔥 Real-World Example

```javascript
import { 
    createChart, 
    CandlestickSeries,
    applySMA,
    applyEMA,
    applyBollingerBands,
    applyRSI,
    applyMACD,
    applyVolume,
    setVolumeData,
    createTradingLine,
    createInteractiveLineManager
} from '@pipsend/charts';

// Fetch data from your API
const response = await fetch('/api/ohlcv');
const data = await response.json();

// Create chart
const chart = createChart(document.getElementById('chart'), {
    width: window.innerWidth,
    height: 600,
    layout: {
        background: { color: '#1E222D' },
        textColor: '#DDD',
    },
});

// Add candlestick series
const series = chart.addSeries(CandlestickSeries, {
    upColor: '#26a69a',
    downColor: '#ef5350',
});
series.setData(data);

// Add moving averages
applySMA(series, chart, { period: 20, color: '#2196F3' });
applyEMA(series, chart, { period: 50, color: '#FF9800' });

// Add Bollinger Bands
applyBollingerBands(series, chart, { period: 20, stdDev: 2 });

// Add oscillators
applyRSI(series, chart, { period: 14, color: '#9C27B0' });
applyMACD(series, chart, { fastPeriod: 12, slowPeriod: 26, signalPeriod: 9 });

// Add volume
setVolumeData(series, data);
applyVolume(series, chart, { colorUp: '#26a69a', colorDown: '#ef5350' });

// Add trading lines
const currentPrice = data[data.length - 1].close;

const stopLoss = createTradingLine(series, chart, {
    price: currentPrice * 0.98,
    type: 'stop-loss',
    onDragEnd: async (price) => {
        await fetch('/api/orders/update', {
            method: 'POST',
            body: JSON.stringify({ stopLoss: price })
        });
    }
});

const takeProfit = createTradingLine(series, chart, {
    price: currentPrice * 1.05,
    type: 'take-profit',
    onDragEnd: async (price) => {
        await fetch('/api/orders/update', {
            method: 'POST',
            body: JSON.stringify({ takeProfit: price })
        });
    }
});

// Interactive line manager
const manager = createInteractiveLineManager(chart, series);

document.getElementById('addSL').onclick = async () => {
    const line = await manager.enableClickToCreate('stop-loss', {
        onDragEnd: (price) => console.log('SL:', price)
    });
};

// Responsive
window.addEventListener('resize', () => {
    chart.applyOptions({ width: window.innerWidth });
});
```

---

## 🎨 Customization

### Chart Themes

```javascript
// Dark Theme
const chart = createChart(container, {
    layout: {
        background: { color: '#1E222D' },
        textColor: '#D9D9D9',
    },
    grid: {
        vertLines: { color: '#2B2B43' },
        horzLines: { color: '#363C4E' },
    },
});

// Light Theme
const chart = createChart(container, {
    layout: {
        background: { color: '#FFFFFF' },
        textColor: '#191919',
    },
    grid: {
        vertLines: { color: '#e1e1e1' },
        horzLines: { color: '#e1e1e1' },
    },
});
```

### Custom Indicator Colors

```javascript
applySMA(series, chart, { 
    period: 20, 
    color: '#FF6B6B',
    lineWidth: 3
});

applyRSI(series, chart, { 
    period: 14, 
    color: '#4ECDC4',
    lineWidth: 2
});
```

---

## 🌐 Browser Support

Pipsend Charts works in all modern browsers that support ES2015+ and Canvas API.

### Supported Browsers

| Browser | Minimum Version |
|---------|----------------|
| Chrome | 63+ |
| Firefox | 67+ |
| Safari | 11.1+ |
| Edge | 79+ |
| Opera | 50+ |
| iOS Safari | 11.3+ |
| Chrome Android | 63+ |

### Required Features

- **Canvas API** - For rendering charts
- **ES2015+ (ES6)** - Modern JavaScript features
- **ResizeObserver** - For responsive charts (polyfill included)

### Polyfills

For older browsers, you may need to include polyfills:

```html
<!-- For IE11 and older browsers -->
<script src="https://polyfill.io/v3/polyfill.min.js?features=es2015,ResizeObserver"></script>
```

---

## 🏗️ Build Variants

| Dependencies | Mode | ES Module | IIFE |
|--------------|------|-----------|------|
| No | PROD | `pipsend-charts.production.mjs` | N/A |
| No | DEV | `pipsend-charts.development.mjs` | N/A |
| Yes | PROD | `pipsend-charts.standalone.production.mjs` | `pipsend-charts.standalone.production.js` |
| Yes | DEV | `pipsend-charts.standalone.development.mjs` | `pipsend-charts.standalone.development.js` |

---

## ⚡ Performance

Pipsend Charts is built for speed and efficiency, capable of handling large datasets with smooth 60 FPS rendering.

### Benchmarks

| Metric | Value |
|--------|-------|
| **Bundle Size** | ~49KB gzipped |
| **Initial Load** | < 100ms |
| **Render 1,000 candles** | < 16ms (60 FPS) |
| **Render 10,000 candles** | < 33ms (30 FPS) |
| **Memory Usage** | ~15MB for 10K candles |
| **Indicator Calculation** | < 5ms per indicator |

### Performance Tips

1. **Use Time-based Data** - Time series data performs better than tick data
2. **Limit Visible Range** - Only render visible candles for best performance
3. **Debounce Updates** - Batch data updates instead of updating on every tick
4. **Lazy Load Indicators** - Add indicators only when needed
5. **Use Production Build** - Always use minified production build in production

### Example: Optimized Real-time Updates

```javascript
let updateQueue = [];
let updateTimer = null;

function queueUpdate(newCandle) {
    updateQueue.push(newCandle);
    
    if (!updateTimer) {
        updateTimer = setTimeout(() => {
            series.update(updateQueue[updateQueue.length - 1]);
            updateQueue = [];
            updateTimer = null;
        }, 100); // Batch updates every 100ms
    }
}
```

---

## 🔧 Development

### Building from Source

```bash
# Install dependencies
npm install

# Build production
npm run build:prod

# Build development
npm run build
```

---

## 🔧 Troubleshooting

### Common Issues

#### Chart Not Rendering

**Problem:** Chart container is empty or chart doesn't appear

**Solutions:**
```javascript
// 1. Ensure container has explicit dimensions
const container = document.getElementById('chart');
container.style.width = '800px';
container.style.height = '600px';

// 2. Wait for DOM to be ready
document.addEventListener('DOMContentLoaded', () => {
    const chart = createChart(container);
});

// 3. Check if container exists
if (!container) {
    console.error('Chart container not found!');
}
```

#### Indicators Not Showing

**Problem:** Technical indicators don't appear on chart

**Solutions:**
```javascript
// 1. Ensure you have data before applying indicators
series.setData(data);
applySMA(series, chart, { period: 20 }); // Apply AFTER setData

// 2. Check data format
const validData = [
    { time: '2024-01-01', open: 100, high: 105, low: 95, close: 102 },
    // time must be string (YYYY-MM-DD) or timestamp
];

// 3. Verify indicator period is not larger than data length
// If you have 10 candles, period: 20 won't work
```

#### TypeScript Errors

**Problem:** Type errors when using the library

**Solutions:**
```typescript
// 1. Import types explicitly
import { 
    IChartApi, 
    ISeriesApi,
    CandlestickData 
} from '@pipsend/charts';

// 2. Use proper type annotations
const chart: IChartApi = createChart(container);
const series: ISeriesApi<"Candlestick"> = chart.addSeries(CandlestickSeries);
```

#### Performance Issues

**Problem:** Chart is slow or laggy

**Solutions:**
```javascript
// 1. Limit visible data range
chart.timeScale().setVisibleRange({
    from: startTime,
    to: endTime
});

// 2. Use production build
import { createChart } from 'pipsend-charts/dist/pipsend-charts.production.mjs';

// 3. Disable animations for large datasets
chart.applyOptions({
    handleScroll: false,
    handleScale: false
});
```

#### Module Not Found Errors

**Problem:** `Cannot find module 'pipsend-charts'`

**Solutions:**
```bash
# 1. Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

# 2. Check package.json has the dependency
npm list pipsend-charts

# 3. For TypeScript, ensure moduleResolution is set
# tsconfig.json
{
  "compilerOptions": {
    "moduleResolution": "node"
  }
}
```

### Getting Help

If you encounter issues not covered here:

1. **Check Examples** - Review the [examples](./examples) directory
2. **Search Issues** - Look for similar issues on [GitHub Issues](https://github.com/ArcaTechCo/PipsendCharts/issues)
3. **Ask Questions** - Open a new issue with:
   - Your code snippet
   - Expected vs actual behavior
   - Browser/Node version
   - Error messages

---

## ❓ FAQ

### General Questions

**Q: Is Pipsend Charts free to use?**  
A: Yes! Pipsend Charts is FREE to use in both personal and commercial projects, as long as you use the unmodified version. If you want to modify and redistribute commercially, you'll need a commercial license.

**Q: What's the difference between Pipsend Charts and TradingView Lightweight Charts?**  
A: Pipsend Charts is built on top of TradingView's Lightweight Charts™ and adds:
- 10 pre-built technical indicators (SMA, EMA, RSI, MACD, etc.)
- Interactive draggable trading lines (Stop Loss, Take Profit)
- Simplified functional API for indicators
- Click-to-create line tools

**Q: Can I use this in production?**  
A: Absolutely! Pipsend Charts is production-ready and optimized for performance. Make sure to use the production build.

**Q: Do I need a TradingView account?**  
A: No. Pipsend Charts is a standalone library that doesn't require any TradingView account or API keys.

### Technical Questions

**Q: Can I add custom indicators?**  
A: Yes! You can create custom indicators using the underlying TradingView Lightweight Charts API or by extending the existing indicator patterns.

**Q: How do I update data in real-time?**  
A: Use the `update()` method on your series:
```javascript
series.update({ time: Date.now() / 1000, open: 100, high: 105, low: 95, close: 102 });
```

**Q: Can I use multiple timeframes?**  
A: Yes, but you need to create separate charts for each timeframe. You can switch data on the same chart by calling `setData()` with different timeframe data.

**Q: Does it work with cryptocurrency data?**  
A: Yes! Pipsend Charts works with any OHLC (Open, High, Low, Close) data - stocks, forex, crypto, commodities, etc.

**Q: Can I customize the colors and styles?**  
A: Absolutely! Every aspect of the chart is customizable - colors, line styles, fonts, backgrounds, etc. See the [Customization](#-customization) section.

**Q: How do I save/export charts?**  
A: You can export charts as images using the Canvas API:
```javascript
const canvas = document.querySelector('canvas');
const image = canvas.toDataURL('image/png');
```

**Q: Is server-side rendering (SSR) supported?**  
A: Pipsend Charts requires a browser environment (Canvas API). For SSR frameworks like Next.js, use dynamic imports:
```javascript
const Chart = dynamic(() => import('./Chart'), { ssr: false });
```

**Q: What's the maximum number of data points?**  
A: The library can handle 10,000+ data points smoothly. Performance depends on your hardware and browser.

**Q: Can I use this with TypeScript?**  
A: Yes! Pipsend Charts is written in TypeScript and includes full type definitions.

**Q: How do I remove an indicator?**  
A: Indicators return a cleanup function:
```javascript
const cleanup = applySMA(series, chart, { period: 20 });
cleanup(); // Removes the indicator
```

### Licensing Questions

**Q: Can I use this in a commercial product?**  
A: Yes! You can use the unmodified library in commercial products for FREE. If you want to modify and redistribute commercially, you need a commercial license.

**Q: Do I need to credit Pipsend Charts?**  
A: Attribution is required as per the license terms. You must include the copyright notice and license in your distribution.

**Q: Can I modify the source code?**  
A: Yes, you can modify for your own internal use. To modify and redistribute commercially, you need a [commercial license](./LICENSE-COMMERCIAL.md).

**Q: How much does a commercial license cost?**  
A: Commercial licenses start at $499/year for startups. See [LICENSE-COMMERCIAL.md](./LICENSE-COMMERCIAL.md) for full pricing.

**Q: What if I'm a non-profit or educational institution?**  
A: Contact us at licensing@pipsend.com for special pricing and discounts for non-profits and educational institutions.

---

## 🗺️ Roadmap

### Current Version (1.0.0)

✅ 10 Technical Indicators (SMA, EMA, WMA, RSI, MACD, Stochastic, Bollinger Bands, ATR, Volume, OBV)  
✅ Interactive Trading Lines (Stop Loss, Take Profit, Custom Lines)  
✅ Click-to-Create Line Tools  
✅ Framework Integration Examples (React, Vue, Angular, Svelte)  
✅ TypeScript Support  
✅ Production-Ready Performance  

### Planned Features

#### v1.1.0 (Q4 2025)
- 🔄 **More Indicators**
  - Fibonacci Retracement
  - Ichimoku Cloud
  - Parabolic SAR
  - ADX (Average Directional Index)
- 📊 **Drawing Tools**
  - Trend Lines
  - Horizontal Lines
  - Rectangle/Box Drawing
  - More dynamic line tools
- 🎨 **Themes**
  - Pre-built Dark/Light themes
  - Theme switcher utility

#### v1.2.0 (Q1 2026)
- 📈 **Advanced Features**
  - Multi-chart synchronization
  - Chart comparison (overlay multiple symbols)
  - Volume Profile
  - Heatmap visualization
- 🔔 **Alerts System**
  - Price alerts with notifications
  - Indicator-based alerts
  - Alert management API

#### v1.3.0 (Q2 2026)
- 🤖 **AI/ML Integration**
  - Pattern recognition
  - Trend prediction helpers
  - Anomaly detection
- 📱 **Mobile Optimization**
  - Touch gesture improvements
  - Mobile-specific UI components
  - Responsive chart layouts

#### Future Considerations
- WebSocket integration examples
- Chart templates/presets
- Export to PDF/PNG
- Replay mode (historical playback)
- Custom indicator builder UI
- Plugin system for community extensions

### Community Requests

Have a feature request? [Open an issue](https://github.com/ArcaTechCo/PipsendCharts/issues) with the `enhancement` label!

---

## 🤝 Contributing

We welcome contributions from the community! Whether it's bug fixes, new features, documentation improvements, or examples.

### How to Contribute

1. **Fork the Repository**
   ```bash
   git clone https://github.com/ArcaTechCo/PipsendCharts.git
   cd pipsend-charts
   ```

2. **Install Dependencies**
   ```bash
   npm install
   ```

3. **Create a Branch**
   ```bash
   git checkout -b feature/your-feature-name
   # or
   git checkout -b fix/your-bug-fix
   ```

4. **Make Your Changes**
   - Write clean, documented code
   - Follow existing code style
   - Add tests if applicable
   - Update documentation

5. **Test Your Changes**
   ```bash
   # Run tests
   npm test
   
   # Run linter
   npm run lint
   
   # Build the project
   npm run build:prod
   ```

6. **Commit Your Changes**
   ```bash
   git add .
   git commit -m "feat: add new indicator XYZ"
   # or
   git commit -m "fix: resolve issue with chart rendering"
   ```

   **Commit Message Format:**
   - `feat:` - New feature
   - `fix:` - Bug fix
   - `docs:` - Documentation changes
   - `style:` - Code style changes (formatting)
   - `refactor:` - Code refactoring
   - `test:` - Adding or updating tests
   - `chore:` - Maintenance tasks

7. **Push and Create Pull Request**
   ```bash
   git push origin feature/your-feature-name
   ```
   Then open a Pull Request on GitHub.

### Development Guidelines

- **Code Style**: Follow the existing ESLint configuration
- **TypeScript**: Maintain type safety, avoid `any` types
- **Documentation**: Update README and add JSDoc comments
- **Tests**: Add unit tests for new features
- **Performance**: Ensure changes don't degrade performance
- **Backwards Compatibility**: Avoid breaking changes when possible

### Areas We Need Help With

- 📚 **Documentation** - Improve examples, tutorials, API docs
- 🐛 **Bug Reports** - Find and report bugs
- ✨ **New Indicators** - Implement additional technical indicators
- 🎨 **Themes** - Create beautiful chart themes
- 🌍 **Translations** - Translate documentation
- 📝 **Examples** - Add framework-specific examples
- 🧪 **Testing** - Improve test coverage

### Reporting Bugs

When reporting bugs, please include:

1. **Description** - Clear description of the issue
2. **Steps to Reproduce** - Minimal code to reproduce the bug
3. **Expected Behavior** - What should happen
4. **Actual Behavior** - What actually happens
5. **Environment** - Browser, OS, library version
6. **Screenshots** - If applicable

### Code of Conduct

- Be respectful and inclusive
- Provide constructive feedback
- Focus on the code, not the person
- Help others learn and grow

### Questions?

- 💬 **Discussions** - Use [GitHub Discussions](https://github.com/ArcaTechCo/PipsendCharts/discussions) for questions
- 🐛 **Issues** - Use [GitHub Issues](https://github.com/ArcaTechCo/PipsendCharts/issues) for bugs
- 📧 **Email** - Contact maintainers for private matters

Thank you for contributing to Pipsend Charts! 🎉

---

## 📝 Changelog

### [0.0.8] - 2025-10-24

#### 🎉 Initial Release

**Core Features**
- ✅ Professional candlestick charting library
- ✅ Built on TradingView's Lightweight Charts™
- ✅ Full TypeScript support with type definitions
- ✅ Framework-agnostic (React, Vue, Angular, Svelte, Vanilla JS)

**Technical Indicators (10 Total)**

*Overlay Indicators:*
- ✅ SMA (Simple Moving Average)
- ✅ EMA (Exponential Moving Average)
- ✅ WMA (Weighted Moving Average)
- ✅ Bollinger Bands

*Panel Indicators:*
- ✅ RSI (Relative Strength Index)
- ✅ MACD (Moving Average Convergence Divergence)
- ✅ Stochastic Oscillator
- ✅ ATR (Average True Range)
- ✅ Volume
- ✅ OBV (On-Balance Volume)

**Interactive Trading Tools**
- ✅ Draggable price lines (Stop Loss, Take Profit)
- ✅ Click-to-create line functionality
- ✅ Interactive line manager
- ✅ Customizable line styles and colors
- ✅ Drag event callbacks (onDragStart, onDragMove, onDragEnd)

**API & Developer Experience**
- ✅ Functional API for indicators (one function call per indicator)
- ✅ Auto-updating indicators when data changes
- ✅ Comprehensive TypeScript types
- ✅ Full API documentation
- ✅ Framework integration examples

**Performance**
- ✅ ~49KB gzipped bundle size
- ✅ 60 FPS rendering for 1,000+ candles
- ✅ Optimized for real-time data updates
- ✅ Minimal dependencies

**Documentation**
- ✅ Complete README with examples
- ✅ API reference documentation
- ✅ Framework integration guides
- ✅ Live HTML examples

**Build System**
- ✅ ES Module builds
- ✅ IIFE builds for CDN usage
- ✅ Development and production variants
- ✅ Standalone and dependency-based builds

---

For detailed changes in future versions, see [GitHub Releases](https://github.com/ArcaTechCo/PipsendCharts/releases).

---

## 📄 License

Pipsend Charts is available under a **Dual License** model.

### 🆓 Free License

**Use Pipsend Charts for FREE in your projects!**

✅ **What You CAN Do (FREE):**
- ✅ Use the **unmodified** library in personal projects
- ✅ Use the **unmodified** library in commercial applications
- ✅ Distribute the original, unmodified library
- ✅ Include as a dependency in your projects
- ✅ Make internal modifications for your own use (not for redistribution)

❌ **What You CANNOT Do (Without Commercial License):**
- ❌ Modify and redistribute commercially
- ❌ Sell modified versions
- ❌ Create derivative products for commercial distribution
- ❌ White-label or rebrand modified versions

### 💼 Commercial License

**Need to modify and redistribute?** Get a commercial license!

If you want to:
- Modify the source code and sell it
- Create derivative products for commercial distribution
- Redistribute modified versions under your own brand
- Build SaaS products with modified versions

**[View Commercial License Options →](./LICENSE-COMMERCIAL.md)**

Pricing starts at $499/year for startups. Enterprise licenses available.

### 📋 Quick Comparison

| Feature | Free License | Commercial License |
|---------|--------------|-------------------|
| Use in personal projects | ✅ Free | ✅ Included |
| Use in commercial apps (unmodified) | ✅ Free | ✅ Included |
| Modify for internal use | ✅ Free | ✅ Included |
| **Modify and redistribute commercially** | ❌ Not allowed | ✅ **Allowed** |
| **Sell modified versions** | ❌ Not allowed | ✅ **Allowed** |
| **White-label/rebrand** | ❌ Not allowed | ✅ **Allowed** |
| Priority support | ❌ No | ✅ Yes |
| Custom features | ❌ No | ✅ Yes (Enterprise) |

### 🤔 Do I Need a Commercial License?

**You DON'T need a commercial license if:**
- You're using the library as-is in your app (even commercial apps)
- You're making internal modifications for your own use
- You're using it for learning or personal projects

**You DO need a commercial license if:**
- You want to sell a modified version of the library
- You want to create a competing product based on this library
- You want to redistribute modified versions commercially

### 📜 Full License Text

See the [LICENSE](./LICENSE) file for complete terms and conditions.

### 💬 Questions About Licensing?

- 📧 Email: licensing@pipsend.com
- 💬 Discussions: [GitHub Discussions](https://github.com/ArcaTechCo/PipsendCharts/discussions)
- 📄 Commercial License Details: [LICENSE-COMMERCIAL.md](./LICENSE-COMMERCIAL.md)

### Attribution

Pipsend Charts is built on top of [TradingView's Lightweight Charts™](https://github.com/tradingview/lightweight-charts), which is licensed under Apache 2.0.

**Copyright Notice:**
```
Copyright (c) 2025 Pipsend
Based on TradingView's Lightweight Charts™ (Copyright 2024 TradingView, Inc.)
```

### Third-Party Components

This project includes code from:
- **TradingView Lightweight Charts™** - [Apache 2.0](https://github.com/tradingview/lightweight-charts/blob/master/LICENSE)
- **fancy-canvas** - [ISC License](https://github.com/tradingview/fancy-canvas/blob/master/LICENSE)

These components retain their original licenses.

---

## 🙏 Acknowledgments

- **TradingView** - For creating the excellent Lightweight Charts library
- **Contributors** - Everyone who has contributed to this project
- **Community** - Users who provide feedback and report issues

---

## 📞 Support & Contact

- **Documentation**: [README.md](./README.md)
- **Examples**: [./examples](./examples)
- **Issues**: [GitHub Issues](https://github.com/ArcaTechCo/PipsendCharts/issues)
- **Discussions**: [GitHub Discussions](https://github.com/ArcaTechCo/PipsendCharts/discussions)
- **Website**: [https://github.com/ArcaTechCo/PipsendCharts](https://github.com/ArcaTechCo/PipsendCharts)

---

<div align="center">

**Made with ❤️ by the Pipsend Team**

⭐ **Star us on GitHub** if you find this project useful!

[Report Bug](https://github.com/ArcaTechCo/PipsendCharts/issues) · [Request Feature](https://github.com/ArcaTechCo/PipsendCharts/issues) · [Documentation](https://github.com/ArcaTechCo/PipsendCharts)

</div>