chart-library-native 1.0.0

package/src/README.md

@@ -0,0 +1,241 @@
+# 📚 High-Level API Wrapper - Usage Guide
+
+## 🎯 Two-Tier API Architecture
+
+### **Tier 1: Simplified API** ⭐ (90% use cases)
+- Zero configuration
+- Pre-configured defaults
+- Built-in signal calculations
+- Ready-to-use components
+
+### **Tier 2: Advanced API** (10% use cases)
+- Full customization
+- Custom parameters
+- Direct control
+
+---
+
+## 🚀 Quick Start (Tier 1)
+
+### Example 1: Simple MA
+
+```typescript
+import { useQuickMA, QuickIndicatorDisplay } from 'chart-library-native/src';
+
+const MyComponent = () => {
+  const closes = [100, 101, 102, 101, 100, 99, 98, 99, 100, 101];
+  const { data, lastValues, loading } = useQuickMA(closes);
+
+  return (
+    <View>
+      <QuickIndicatorDisplay 
+        name="MA20"
+        value={lastValues.current}
+        previousValue={lastValues.previous}
+      />
+      <Text>Trend: {lastValues.trend}</Text>
+    </View>
+  );
+};
+```
+
+### Example 2: Multiple Indicators
+
+```typescript
+import { 
+  useQuickMA, 
+  useQuickRSI, 
+  useQuickMACD,
+  QuickIndicatorDisplay 
+} from 'chart-library-native/src';
+
+const Dashboard = () => {
+  const closes = [100, 101, 102, 101, 100, 99, 98, 99, 100, 101];
+  
+  const ma = useQuickMA(closes);
+  const rsi = useQuickRSI(closes);
+  const macd = useQuickMACD(closes);
+
+  return (
+    <ScrollView>
+      <QuickIndicatorDisplay 
+        name="MA20"
+        value={ma.lastValues.current}
+      />
+      
+      <QuickIndicatorDisplay 
+        name="RSI14"
+        value={rsi.currentLevel.value}
+        color={rsi.currentLevel.level === 'overbought' ? '#f44336' : '#4CAF50'}
+      />
+      
+      <View>
+        <Text>MACD Signal: {macd.currentSignal.signal}</Text>
+      </View>
+    </ScrollView>
+  );
+};
+```
+
+---
+
+## 🔧 Advanced Usage (Tier 2)
+
+### Custom MA Period
+
+```typescript
+import { useMA } from 'chart-library-native/src';
+
+const CustomMA = () => {
+  const closes = [100, 101, 102, 101, 100, 99, 98, 99, 100, 101];
+  
+  // Custom period: MA50
+  const { data, loading } = useMA(closes, {
+    period: 50,
+    type: 'simple'
+  });
+
+  return <Text>MA50: {data[data.length - 1]}</Text>;
+};
+```
+
+### Custom MACD Settings
+
+```typescript
+import { useMACD } from 'chart-library-native/src';
+
+const CustomMACD = () => {
+  const closes = [100, 101, 102, 101, 100, 99, 98, 99, 100, 101];
+  
+  // Custom MACD: fast=8, slow=21, signal=5
+  const { macd, signal, histogram } = useMACD(closes, {
+    fast: 8,
+    slow: 21,
+    signal: 5
+  });
+
+  return (
+    <View>
+      <Text>MACD: {macd[macd.length - 1]}</Text>
+      <Text>Signal: {signal[signal.length - 1]}</Text>
+    </View>
+  );
+};
+```
+
+---
+
+## 📊 Available Tier 1 Hooks
+
+| Hook | Default | Description |
+|------|---------|-------------|
+| `useQuickMA` | MA20 | Simple Moving Average |
+| `useQuickEMA` | EMA12 | Exponential Moving Average |
+| `useQuickMACD` | 12/26/9 | MACD with signal calculation |
+| `useQuickRSI` | RSI14 | RSI with overbought/oversold levels |
+| `useQuickKDJ` | 9/3/3 | KDJ Stochastic |
+| `useQuickBollinger` | BB(20,2) | Bollinger Bands |
+| `useQuickDMI` | DMI(14) | Directional Movement Index |
+
+---
+
+## 🎨 Components
+
+### QuickIndicatorDisplay
+
+Pre-built component to display indicator values:
+
+```typescript
+<QuickIndicatorDisplay 
+  name="MA20"
+  value={106.5}
+  previousValue={105.8}
+  decimals={2}
+  color="#1f77b4"
+  status="success"
+/>
+```
+
+**Props:**
+- `name`: Indicator name
+- `value`: Current value
+- `previousValue`: Previous value (optional, for trend calculation)
+- `decimals`: Number of decimal places (default: 2)
+- `color`: Text color (default: '#1f77b4')
+- `status`: 'success' | 'error'
+- `error`: Error message (if status is 'error')
+
+---
+
+## 📝 Migration: Tier 1 → Tier 2
+
+```typescript
+// Start with Tier 1
+import { useQuickMA } from 'chart-library-native/src';
+const { data } = useQuickMA(closes);
+
+// Later, migrate to Tier 2 for custom period
+import { useMA } from 'chart-library-native/src';
+const { data } = useMA(closes, { period: 50, type: 'simple' });
+
+// Zero breaking changes!
+```
+
+---
+
+## 🔗 Architecture
+
+```
+┌─────────────────────────────────┐
+│   Tier 1: Simplified API        │
+│   useQuickMA, useQuickRSI, etc. │
+└──────────────┬──────────────────┘
+               │
+┌──────────────▼──────────────────┐
+│   Tier 2: Advanced API          │
+│   useMA, useRSI, useMACD, etc.  │
+└──────────────┬──────────────────┘
+               │
+┌──────────────▼──────────────────┐
+│   Low-Level: ChartLibrary       │
+│   Direct JSI calls              │
+└──────────────┬──────────────────┘
+               │
+┌──────────────▼──────────────────┐
+│   C API Layer                   │
+│   chart_calculate_ma, etc.     │
+└──────────────┬──────────────────┘
+               │
+┌──────────────▼──────────────────┐
+│   C++ Core                      │
+│   calculateMA, calculateRSI, etc│
+└─────────────────────────────────┘
+```
+
+---
+
+## ✅ Benefits
+
+### Tier 1 Benefits:
+- ✅ Zero configuration
+- ✅ Industry-standard defaults
+- ✅ Built-in signal calculations
+- ✅ Ready-to-use components
+- ✅ Perfect for 90% of use cases
+
+### Tier 2 Benefits:
+- ✅ Full customization
+- ✅ Any parameters
+- ✅ Advanced features
+- ✅ Direct control
+
+---
+
+## 📚 More Examples
+
+See `examples/` directory for complete examples:
+- Simple dashboard
+- Multiple indicators
+- Custom configurations
+- Chart integration
+

package/src/api/tier1/components/QuickIndicatorDisplay.tsx

@@ -0,0 +1,109 @@
+// ============================================================================
+// 📄 bindings/react-native/src/api/tier1/components/QuickIndicatorDisplay.tsx
+// Pre-built component to display any indicator
+// ============================================================================
+
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+
+interface QuickIndicatorDisplayProps {
+  name: string;
+  value: number | null;
+  previousValue?: number | null;
+  decimals?: number;
+  color?: string;
+  status?: 'success' | 'error';
+  error?: string;
+}
+
+/**
+ * Pre-built indicator display component
+ * 
+ * @example
+ * <QuickIndicatorDisplay 
+ *   name="MA20" 
+ *   value={106.5}
+ *   previousValue={105.8}
+ *   status="success"
+ * />
+ */
+export const QuickIndicatorDisplay: React.FC<QuickIndicatorDisplayProps> = ({
+  name,
+  value,
+  previousValue,
+  decimals = 2,
+  color = '#1f77b4',
+  status = 'success',
+  error
+}) => {
+  const formattedValue = value !== null ? value.toFixed(decimals) : 'N/A';
+  const change = 
+    value !== null && previousValue !== null && previousValue !== undefined
+      ? ((value - previousValue) / Math.abs(previousValue) * 100).toFixed(2)
+      : null;
+
+  const changeColor = change && parseFloat(change) > 0 ? '#4CAF50' : '#f44336';
+
+  return (
+    <View style={styles.container}>
+      <View style={styles.header}>
+        <Text style={styles.name}>{name}</Text>
+        {status === 'error' && (
+          <Text style={styles.error}>❌ {error || 'Error'}</Text>
+        )}
+      </View>
+      
+      <View style={styles.content}>
+        <Text style={[styles.value, { color }]}>
+          {formattedValue}
+        </Text>
+        
+        {change !== null && (
+          <Text style={[styles.change, { color: changeColor }]}>
+            {parseFloat(change) > 0 ? '↑' : '↓'} {change}%
+          </Text>
+        )}
+      </View>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    padding: 12,
+    backgroundColor: '#fff',
+    borderRadius: 8,
+    marginVertical: 6,
+    borderLeftWidth: 4,
+    borderLeftColor: '#1f77b4'
+  },
+  header: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center'
+  },
+  name: {
+    fontSize: 12,
+    fontWeight: '600',
+    color: '#666'
+  },
+  error: {
+    fontSize: 10,
+    color: '#f44336'
+  },
+  content: {
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'baseline',
+    marginTop: 8
+  },
+  value: {
+    fontSize: 18,
+    fontWeight: 'bold'
+  },
+  change: {
+    fontSize: 12,
+    fontWeight: '600'
+  }
+});
+

package/src/api/tier1/components/index.ts

@@ -0,0 +1,16 @@
+// ============================================================================
+// 📄 bindings/react-native/src/api/tier1/components/index.ts
+// Pre-built components ready to use
+// ============================================================================
+
+export { QuickIndicatorDisplay } from './QuickIndicatorDisplay';
+// Note: Chart components (SimpleLineChart, MAChart, etc.) would require
+// react-native-chart-kit or similar library. They are placeholders for now.
+// export { SimpleLineChart } from './SimpleLineChart';
+// export { MAChart } from './MAChart';
+// export { MACDChart } from './MACDChart';
+// export { RSIChart } from './RSIChart';
+// export { KDJChart } from './KDJChart';
+// export { BollingerChart } from './BollingerChart';
+// export { ChartCard } from './ChartCard';
+

package/src/api/tier1/index.ts

@@ -0,0 +1,15 @@
+// ============================================================================
+// 📄 bindings/react-native/src/api/tier1/index.ts
+// Tier 1 Simplified API exports
+// ============================================================================
+
+export { useQuickMA } from './useQuickMA';
+export { useQuickEMA } from './useQuickEMA';
+export { useQuickMACD } from './useQuickMACD';
+export { useQuickRSI } from './useQuickRSI';
+export { useQuickKDJ } from './useQuickKDJ';
+export { useQuickBollinger } from './useQuickBollinger';
+export { useQuickDMI } from './useQuickDMI';
+
+export * from './components';
+

package/src/api/tier1/useQuickBollinger.ts

@@ -0,0 +1,58 @@
+// ============================================================================
+// 📄 bindings/react-native/src/api/tier1/useQuickBollinger.ts
+// Tier 1 API: Bollinger Bands
+// ============================================================================
+
+import { useBollinger } from '../../hooks/useIndicators';
+
+export interface UseQuickBollingerResult {
+  upper: (number | null)[];
+  middle: (number | null)[];
+  lower: (number | null)[];
+  loading: boolean;
+  error?: string;
+  currentBands: {
+    upper: number | null;
+    middle: number | null;
+    lower: number | null;
+    price: number | null;
+    position: 'above' | 'within' | 'below';
+  };
+  status: 'success' | 'error';
+}
+
+/**
+ * Quick Bollinger Bands Hook - Standard BB(20,2)
+ * 
+ * @param closes - Array of close prices
+ * @returns { upper, middle, lower, currentBands, loading, error, status }
+ */
+export const useQuickBollinger = (closes: number[]): UseQuickBollingerResult => {
+  const { upper, middle, lower, loading, status, error } = useBollinger(closes, {
+    period: 20,
+    k: 2.0
+  });
+
+  const validUpper = upper.filter(v => v !== null && Number.isFinite(v)) as number[];
+  const validMiddle = middle.filter(v => v !== null && Number.isFinite(v)) as number[];
+  const validLower = lower.filter(v => v !== null && Number.isFinite(v)) as number[];
+
+  const u = validUpper.length > 0 ? validUpper[validUpper.length - 1] : null;
+  const m = validMiddle.length > 0 ? validMiddle[validMiddle.length - 1] : null;
+  const l = validLower.length > 0 ? validLower[validLower.length - 1] : null;
+  const price = closes.length > 0 ? closes[closes.length - 1] : null;
+
+  const currentBands = {
+    upper: u,
+    middle: m,
+    lower: l,
+    price,
+    position: ((): 'above' | 'within' | 'below' => {
+      if (u === null || l === null || price === null) return 'within';
+      return price > u ? 'above' : price < l ? 'below' : 'within';
+    })()
+  };
+
+  return { upper, middle, lower, loading, error, currentBands, status };
+};
+

package/src/api/tier1/useQuickDMI.ts

@@ -0,0 +1,65 @@
+// ============================================================================
+// 📄 bindings/react-native/src/api/tier1/useQuickDMI.ts
+// Tier 1 API: DMI (Directional Movement Index)
+// ============================================================================
+
+import { useDMI } from '../../hooks/useIndicators';
+import type { CandleData } from '../../types';
+
+export interface UseQuickDMIResult {
+  pdi: (number | null)[];
+  mdi: (number | null)[];
+  adx: (number | null)[];
+  adxr: (number | null)[];
+  loading: boolean;
+  error?: string;
+  currentTrend: {
+    pdi: number | null;
+    mdi: number | null;
+    adx: number | null;
+    direction: 'uptrend' | 'downtrend' | 'no_trend';
+    strength: 'strong' | 'moderate' | 'weak';
+  };
+  status: 'success' | 'error';
+}
+
+/**
+ * Quick DMI Hook - Standard DMI(14)
+ * 
+ * ADX > 25: Strong trend
+ * ADX 20-25: Moderate trend
+ * ADX < 20: Weak trend / No trend
+ * 
+ * @param candleData - Array of candle data
+ * @returns { pdi, mdi, adx, adxr, currentTrend, loading, error, status }
+ */
+export const useQuickDMI = (candleData: CandleData[]): UseQuickDMIResult => {
+  const { pdi, mdi, adx, adxr, loading, status, error } = useDMI(candleData, {
+    period: 14
+  });
+
+  const validPDI = pdi.filter(v => v !== null && Number.isFinite(v)) as number[];
+  const validMDI = mdi.filter(v => v !== null && Number.isFinite(v)) as number[];
+  const validADX = adx.filter(v => v !== null && Number.isFinite(v)) as number[];
+
+  const pdiVal = validPDI.length > 0 ? validPDI[validPDI.length - 1] : null;
+  const mdiVal = validMDI.length > 0 ? validMDI[validMDI.length - 1] : null;
+  const adxVal = validADX.length > 0 ? validADX[validADX.length - 1] : null;
+
+  const currentTrend = {
+    pdi: pdiVal,
+    mdi: mdiVal,
+    adx: adxVal,
+    direction: ((): 'uptrend' | 'downtrend' | 'no_trend' => {
+      if (pdiVal === null || mdiVal === null) return 'no_trend';
+      return pdiVal > mdiVal ? 'uptrend' : mdiVal > pdiVal ? 'downtrend' : 'no_trend';
+    })(),
+    strength: ((): 'strong' | 'moderate' | 'weak' => {
+      if (adxVal === null) return 'weak';
+      return adxVal > 25 ? 'strong' : adxVal > 20 ? 'moderate' : 'weak';
+    })()
+  };
+
+  return { pdi, mdi, adx, adxr, loading, error, currentTrend, status };
+};
+

package/src/api/tier1/useQuickEMA.ts

@@ -0,0 +1,48 @@
+// ============================================================================
+// 📄 bindings/react-native/src/api/tier1/useQuickEMA.ts
+// Tier 1 API: Exponential Moving Average
+// ============================================================================
+
+import { useEMA } from '../../hooks/useIndicators';
+
+export interface UseQuickEMAResult {
+  data: (number | null)[];
+  loading: boolean;
+  error?: string;
+  lastValues: {
+    current: number | null;
+    previous: number | null;
+    trend: 'up' | 'down' | 'flat';
+  };
+  status: 'success' | 'error';
+}
+
+/**
+ * Quick EMA Hook - No configuration needed
+ * 
+ * Default: EMA12 (fast EMA, commonly used with EMA26)
+ * 
+ * @param closes - Array of close prices
+ * @returns { data, loading, error, lastValues, status }
+ */
+export const useQuickEMA = (closes: number[]): UseQuickEMAResult => {
+  const { data, loading, status, error } = useEMA(closes, {
+    period: 12,
+    type: 'exponential'
+  });
+
+  const validData = data.filter(v => v !== null && Number.isFinite(v)) as number[];
+  const lastValues = {
+    current: validData.length > 0 ? validData[validData.length - 1] : null,
+    previous: validData.length > 1 ? validData[validData.length - 2] : null,
+    trend: ((): 'up' | 'down' | 'flat' => {
+      if (validData.length < 2) return 'flat';
+      const curr = validData[validData.length - 1];
+      const prev = validData[validData.length - 2];
+      return curr > prev ? 'up' : curr < prev ? 'down' : 'flat';
+    })()
+  };
+
+  return { data, loading, error, lastValues, status };
+};
+

package/src/api/tier1/useQuickKDJ.ts

@@ -0,0 +1,55 @@
+// ============================================================================
+// 📄 bindings/react-native/src/api/tier1/useQuickKDJ.ts
+// Tier 1 API: KDJ Stochastic
+// ============================================================================
+
+import { useKDJ } from '../../hooks/useIndicators';
+import type { CandleData } from '../../types';
+
+export interface UseQuickKDJResult {
+  k: (number | null)[];
+  d: (number | null)[];
+  j: (number | null)[];
+  loading: boolean;
+  error?: string;
+  currentValues: {
+    k: number | null;
+    d: number | null;
+    j: number | null;
+    signal: 'buy' | 'sell' | 'neutral';
+  };
+  status: 'success' | 'error';
+}
+
+/**
+ * Quick KDJ Hook - Standard KDJ(9,3,3)
+ * 
+ * @param candleData - Array of candle data with OHLC
+ * @returns { k, d, j, currentValues, loading, error, status }
+ */
+export const useQuickKDJ = (candleData: CandleData[]): UseQuickKDJResult => {
+  const { k, d, j, loading, status, error } = useKDJ(candleData, {
+    n: 9,
+    m1: 3,
+    m2: 3
+  });
+
+  const validK = k.filter(v => v !== null && Number.isFinite(v)) as number[];
+  const validD = d.filter(v => v !== null && Number.isFinite(v)) as number[];
+  const validJ = j.filter(v => v !== null && Number.isFinite(v)) as number[];
+
+  const currentValues = {
+    k: validK.length > 0 ? validK[validK.length - 1] : null,
+    d: validD.length > 0 ? validD[validD.length - 1] : null,
+    j: validJ.length > 0 ? validJ[validJ.length - 1] : null,
+    signal: ((): 'buy' | 'sell' | 'neutral' => {
+      if (validK.length === 0 || validD.length === 0) return 'neutral';
+      const kVal = validK[validK.length - 1];
+      const dVal = validD[validD.length - 1];
+      return kVal > dVal && kVal < 80 ? 'buy' : kVal < dVal && kVal > 20 ? 'sell' : 'neutral';
+    })()
+  };
+
+  return { k, d, j, loading, error, currentValues, status };
+};
+

package/src/api/tier1/useQuickMA.ts

@@ -0,0 +1,60 @@
+// ============================================================================
+// 📄 bindings/react-native/src/api/tier1/useQuickMA.ts
+// Tier 1 API: Simple Moving Average
+// Usage: const { data, loading, error } = useQuickMA(closes);
+// ============================================================================
+
+import { useMA } from '../../hooks/useIndicators';
+
+export interface UseQuickMAResult {
+  data: (number | null)[];
+  loading: boolean;
+  error?: string;
+  lastValues: {
+    current: number | null;
+    previous: number | null;
+    trend: 'up' | 'down' | 'flat';
+  };
+  status: 'success' | 'error';
+}
+
+/**
+ * Quick Moving Average Hook - No configuration needed
+ * 
+ * Default: MA20 (most common period for day traders)
+ * 
+ * @param closes - Array of close prices
+ * @returns { data, loading, error, lastValues, status }
+ * 
+ * @example
+ * const { data, lastValues } = useQuickMA(closePrices);
+ * console.log(`MA20: ${lastValues.current}, Trend: ${lastValues.trend}`);
+ */
+export const useQuickMA = (closes: number[]): UseQuickMAResult => {
+  const { data, loading, status, error } = useMA(closes, {
+    period: 20,
+    type: 'simple'
+  });
+
+  // Calculate trend
+  const validData = data.filter(v => v !== null && Number.isFinite(v)) as number[];
+  const lastValues = {
+    current: validData.length > 0 ? validData[validData.length - 1] : null,
+    previous: validData.length > 1 ? validData[validData.length - 2] : null,
+    trend: ((): 'up' | 'down' | 'flat' => {
+      if (validData.length < 2) return 'flat';
+      const curr = validData[validData.length - 1];
+      const prev = validData[validData.length - 2];
+      return curr > prev ? 'up' : curr < prev ? 'down' : 'flat';
+    })()
+  };
+
+  return {
+    data,
+    loading,
+    error,
+    lastValues,
+    status
+  };
+};
+