be-components 7.4.7 → 7.5.1

package/src/Charts/README.md

@@ -0,0 +1,310 @@
+# BettorEdge Charts Library
+
+Beautiful, cross-platform charting library for React Native (iOS/Android) and Web.
+
+## Features
+
+- ✨ Stunning visuals with gradients and smooth animations
+- 📱 Works on iOS, Android, and Web (react-native-web)
+- 🎨 Customizable themes and colors
+- 📊 Live updates for real-time data
+- 🎯 Interactive tooltips and click handlers
+- 🔄 Data adapter layer for easy integration
+
+## Installation
+
+Dependencies are already installed in this project:
+- `react-native-gifted-charts` (for React Native)
+- `react-gifted-charts` (for Web)
+
+## Quick Start
+
+### 1. Basic Usage
+
+```typescript
+import { LivePriceChart, TradeChartAdapter } from '../Charts';
+
+// Your trade data
+const trades = [
+  { timestamp: 1704067200000, price: 0.40, side: 'away' },
+  { timestamp: 1704067260000, price: 0.42, side: 'away' },
+  { timestamp: 1704067320000, price: 0.45, side: 'away' },
+  { timestamp: 1704067200000, price: 0.55, side: 'home' },
+  { timestamp: 1704067260000, price: 0.53, side: 'home' },
+  { timestamp: 1704067320000, price: 0.50, side: 'home' },
+];
+
+// Convert to chart format
+const chartData = TradeChartAdapter.toTimeSeriesData(trades, {
+  gradient: true,
+  curved: true,
+  showDataPoints: false,
+});
+
+// Render chart
+<LivePriceChart
+  data={chartData}
+  height={300}
+  animated={true}
+  showTooltip={true}
+  showLegend={true}
+/>
+```
+
+### 2. Live Updates
+
+```typescript
+import { useState, useEffect } from 'react';
+import { LivePriceChart, TradeChartAdapter, Trade } from '../Charts';
+
+const MarketDetailPage = () => {
+  const [trades, setTrades] = useState<Trade[]>([]);
+  const [chartData, setChartData] = useState([]);
+
+  // Initial load
+  useEffect(() => {
+    const initialTrades = fetchInitialTrades(); // Your data fetching
+    const data = TradeChartAdapter.toTimeSeriesData(initialTrades);
+    setChartData(data);
+  }, []);
+
+  // Subscribe to new trades
+  useEffect(() => {
+    const handleNewTrade = (newTrade: Trade) => {
+      setChartData(prev =>
+        TradeChartAdapter.appendTrade(prev, newTrade, 100) // Keep last 100 points
+      );
+    };
+
+    const unsubscribe = subscribeToTrades(handleNewTrade); // Your WebSocket/polling
+    return () => unsubscribe();
+  }, []);
+
+  return (
+    <View>
+      <Text>Live Market Prices</Text>
+      <LivePriceChart
+        data={chartData}
+        height={300}
+        animated={true}
+        showTooltip={true}
+        onPointPress={(point, series) => {
+          console.log(`${series} price: ${point.value} at ${new Date(point.timestamp)}`);
+        }}
+      />
+    </View>
+  );
+};
+```
+
+### 3. Custom Styling
+
+```typescript
+import {
+  LivePriceChart,
+  TradeChartAdapter,
+  defaultChartTheme,
+  lineChartStyles,
+} from '../Charts';
+
+const chartData = TradeChartAdapter.toTimeSeriesData(trades, {
+  gradient: true,
+  curved: true,
+  showDataPoints: true,
+});
+
+// Override colors
+chartData[0].color = '#FF0000'; // Custom away color
+chartData[1].color = '#0000FF'; // Custom home color
+
+<LivePriceChart
+  data={chartData}
+  height={350}
+  animated={true}
+  showLegend={true}
+  yAxisPrefix=""
+  yAxisSuffix=""
+  yAxisLabelCount={8}
+  xAxisLabelCount={6}
+/>
+```
+
+### 4. Time Range Filtering
+
+```typescript
+const now = Date.now();
+const oneHourAgo = now - (60 * 60 * 1000);
+
+<LivePriceChart
+  data={chartData}
+  timeRange={{
+    start: oneHourAgo,
+    end: now,
+  }}
+  height={300}
+/>
+```
+
+## Data Adapter
+
+The `TradeChartAdapter` is the middle layer that converts your trade data to chart format.
+
+### Trade Interface
+
+Define your trade type to match this interface:
+
+```typescript
+interface Trade {
+  timestamp: number;  // Unix timestamp in milliseconds
+  price: number;      // Price/odds value (e.g., 0.40, 0.55)
+  side: 'away' | 'home';  // Which side of the market
+}
+```
+
+### Adapter Methods
+
+```typescript
+// Convert trades to chart data
+const chartData = TradeChartAdapter.toTimeSeriesData(trades, options);
+
+// Append new trade (for live updates)
+const updated = TradeChartAdapter.appendTrade(existingData, newTrade);
+
+// Filter by time range
+const filtered = TradeChartAdapter.filterByTimeRange(trades, startTime, endTime);
+
+// Get statistics
+const stats = TradeChartAdapter.getStats(trades);
+// Returns: { min, max, avg, latest, change }
+```
+
+## Components
+
+### LivePriceChart
+
+Main chart component for showing away/home prices over time.
+
+**Props:**
+- `data` - Array of TimeSeriesData (from adapter)
+- `height` - Chart height in pixels (default: 300)
+- `width` - Chart width (default: full width)
+- `animated` - Enable animations (default: true)
+- `showTooltip` - Show tooltips on press/hover (default: true)
+- `showLegend` - Show legend with current prices (default: true)
+- `yAxisPrefix` - Prefix for Y-axis labels (e.g., "$")
+- `yAxisSuffix` - Suffix for Y-axis labels (e.g., "%")
+- `timeRange` - Filter data by time range
+- `onPointPress` - Callback when user presses a point
+
+### BaseLineChart
+
+Lower-level chart component for custom use cases.
+
+## Themes
+
+```typescript
+import {
+  defaultChartTheme,
+  darkChartTheme,
+  gradients,
+  getAwayHomeGradients,
+} from '../Charts';
+
+// Use default colors
+const colors = defaultChartTheme;
+
+// Or dark theme
+const darkColors = darkChartTheme;
+
+// Get away/home gradients
+const awayHomeGradients = getAwayHomeGradients();
+```
+
+## Utilities
+
+```typescript
+import {
+  formatTime,
+  formatDate,
+  formatPrice,
+  formatCurrency,
+  formatPercentage,
+  getSmartTimeLabel,
+  calculateNiceYBounds,
+} from '../Charts';
+
+// Format timestamp to "3:45 PM"
+const timeStr = formatTime(timestamp, 'medium');
+
+// Format timestamp to "Jan 15"
+const dateStr = formatDate(timestamp, 'medium');
+
+// Format price to "0.42"
+const priceStr = formatPrice(0.423, 2);
+
+// Smart label based on data range
+const label = getSmartTimeLabel(timestamp, minTime, maxTime);
+
+// Calculate nice Y-axis bounds
+const { min, max } = calculateNiceYBounds([0.40, 0.42, 0.45]);
+```
+
+## Architecture
+
+```
+Charts/
+├── components/       # React components
+│   ├── LivePriceChart.tsx    # Main chart for away/home prices
+│   └── BaseLineChart.tsx     # Low-level chart wrapper
+├── adapters/        # Data transformation layer
+│   └── TradeChartAdapter.ts  # Converts trades → chart data
+├── themes/          # Colors and styling
+│   └── chartTheme.ts         # Theme configuration
+├── utils/           # Helper functions
+│   └── formatters.ts         # Date/price formatters
+├── types.ts         # TypeScript interfaces
+└── index.tsx        # Public exports
+```
+
+## Extending
+
+### Adding New Chart Types
+
+1. Create new component in `components/`
+2. Use `BaseLineChart` or create custom implementation
+3. Export from `index.tsx`
+
+### Custom Data Adapters
+
+Create adapter for your specific data type:
+
+```typescript
+export class CustomDataAdapter {
+  static toTimeSeriesData(customData: YourType[]): TimeSeriesData[] {
+    // Your transformation logic
+    return transformedData;
+  }
+}
+```
+
+## Performance Tips
+
+- Limit data points with `maxPoints` option (default: 100)
+- Use `smoothing: true` to reduce noise
+- Disable animations on very frequent updates
+- Filter data by time range before passing to chart
+
+## Troubleshooting
+
+### Chart not rendering on web
+- Make sure `react-gifted-charts` is installed
+- Check that Platform.OS === 'web' is correctly detected
+
+### Performance issues with many points
+- Use `maxPoints` option in adapter
+- Enable smoothing to reduce data points
+- Consider pagination/windowing for historical data
+
+## License
+
+Part of the BettorEdge be-components module.