@adrienhobbs/candlekit 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 adrienhobbs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# Trading Chart Component
+
+A powerful, provider-agnostic trading chart built on TradingView's Lightweight Charts library.
+
+## Features
+
+### Chart Visualization
+- Real-time candlestick charts with volume
+- Technical indicators (SMA, EMA, RSI, Bollinger Bands, VWAP)
+- Interactive price lines for entry/exit levels
+- Bar selection and inspection
+- Infinite scroll for historical data
+- Context menu for quick actions
+
+### Data Management
+- Provider-agnostic architecture (works with any data source)
+- Built-in Alpaca Markets integration
+- Real-time WebSocket support
+- Historical data fetching with pagination
+- Data validation and normalization utilities
+- Error handling and retry logic
+- Easy to create custom adapters for other providers
+
+## Install (as a package)
+
+```bash
+npm install @adrienhobbs/candlekit lightweight-charts react react-dom
+```
+
+`react`, `react-dom`, and `lightweight-charts` are peer dependencies — install them
+alongside the package.
+
+```tsx
+import { ChartComponent } from '@adrienhobbs/candlekit';
+import '@adrienhobbs/candlekit/styles.css';
+
+<ChartComponent bars={bars} />
+```
+
+Indicator overlays persist via localStorage by default
+(`createPersistenceAdapter('localStorage')`), or pass `'noop'` to disable.
+
+## Quick Start
+
+> The sections below describe the **dev harness** (`npm run dev`) bundled in this repo,
+> not the published package.
+
+### Option 1: With Mock Data (No Setup Required)
+
+```bash
+npm install
+npm run dev
+```
+
+The app will run with realistic mock data - perfect for testing and development.
+
+### Option 2: With Real Alpaca Market Data
+
+1. Install dependencies:
+```bash
+npm install
+```
+
+2. Get free Alpaca API credentials (see below)
+
+3. Copy `.env.example` to `.env` and add your credentials:
+```bash
+cp .env.example .env
+```
+
+Edit `.env`:
+```
+VITE_ALPACA_API_KEY=your-api-key
+VITE_ALPACA_SECRET_KEY=your-secret-key
+```
+
+4. Run the development server:
+```bash
+npm run dev
+```
+
+The app will automatically detect your API keys and switch to real market data!
+
+## Getting Alpaca API Credentials
+
+1. Sign up for a free account at [Alpaca Markets](https://alpaca.markets/)
+2. Navigate to the [Paper Trading Dashboard](https://app.alpaca.markets/paper/dashboard/overview)
+3. Go to "Your API Keys" section
+4. Generate new API keys
+5. Copy the API Key ID and Secret Key to your `.env` file
+
+## Documentation
+
+See the [docs](./docs) folder for comprehensive documentation:
+
+- [Data Management Guide](./docs/data-management.md) - Complete guide to fetching and managing market data
+- [ChartComponent Usage](./docs/chart-component.md) - Complete guide to using the chart
+- [Creating Indicators](./docs/creating-indicators.md) - Build custom indicators
+- [Architecture](./docs/architecture.md) - System design and architecture
+- [API Reference](./docs/api-reference.md) - Complete API documentation
+- [Examples](./docs/examples.md) - Code examples and recipes
+
+## Project Structure
+
+```
+src/
+├── components/          # React components
+│   ├── ChartComponent.tsx
+│   ├── IndicatorBrowser.tsx
+│   └── SettingsDialog.tsx
+├── hooks/              # Custom React hooks
+│   ├── useBarsData.ts      # Data management hook
+│   ├── useChartAPI.ts      # Chart API hook
+│   └── useRealtimeUpdates.ts (deprecated)
+├── adapters/           # Data provider adapters
+│   ├── types.ts
+│   └── alpaca.ts
+├── indicators/         # Technical indicators
+│   ├── core/
+│   ├── primitives/
+│   ├── registry/
+│   └── utils/
+├── types/             # TypeScript type definitions
+└── utils/             # Utility functions
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,425 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
+
+interface OHLCVBar {
+    timestamp: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+    trade_count?: number;
+    vwap?: number;
+}
+interface ChartLine {
+    id: string;
+    price: number;
+    color: string;
+    lineWidth?: number;
+    lineStyle?: 'solid' | 'dashed' | 'dotted';
+    title?: string;
+    type?: 'entry' | 'stopLoss' | 'takeProfit';
+}
+interface IndicatorSettings$1 {
+    [key: string]: any;
+}
+interface IndicatorPanel {
+    id: string;
+    name: string;
+    type: 'line' | 'histogram' | 'area';
+    settings: IndicatorSettings$1;
+    data: any[];
+}
+
+declare enum IndicatorCategory {
+    TREND = "Trend",
+    MOMENTUM = "Momentum",
+    VOLATILITY = "Volatility",
+    VOLUME = "Volume",
+    OSCILLATORS = "Oscillators"
+}
+declare enum ChartSeriesType {
+    LINE = "line",
+    HISTOGRAM = "histogram",
+    AREA = "area"
+}
+declare const SettingFieldTypeSchema: z.ZodEnum<{
+    number: "number";
+    boolean: "boolean";
+    color: "color";
+    select: "select";
+    lineStyle: "lineStyle";
+}>;
+declare const LineStyleSchema: z.ZodEnum<{
+    solid: "solid";
+    dashed: "dashed";
+    dotted: "dotted";
+}>;
+declare const SettingFieldSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        color: "color";
+        select: "select";
+        lineStyle: "lineStyle";
+    }>;
+    label: z.ZodString;
+    defaultValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    description: z.ZodOptional<z.ZodString>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    step: z.ZodOptional<z.ZodNumber>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+declare const IndicatorSettingsSchema: z.ZodRecord<z.ZodString, z.ZodObject<{
+    type: z.ZodEnum<{
+        number: "number";
+        boolean: "boolean";
+        color: "color";
+        select: "select";
+        lineStyle: "lineStyle";
+    }>;
+    label: z.ZodString;
+    defaultValue: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+    description: z.ZodOptional<z.ZodString>;
+    min: z.ZodOptional<z.ZodNumber>;
+    max: z.ZodOptional<z.ZodNumber>;
+    step: z.ZodOptional<z.ZodNumber>;
+    options: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        label: z.ZodString;
+        value: z.ZodString;
+    }, z.core.$strip>>>;
+}, z.core.$strip>>;
+declare const IndicatorMetadataSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodEnum<typeof IndicatorCategory>;
+    version: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+declare const RenderConfigSchema: z.ZodObject<{
+    seriesType: z.ZodEnum<typeof ChartSeriesType>;
+    outputCount: z.ZodDefault<z.ZodNumber>;
+    overlay: z.ZodDefault<z.ZodBoolean>;
+    hasBandFill: z.ZodOptional<z.ZodBoolean>;
+    fillBands: z.ZodOptional<z.ZodObject<{
+        upper: z.ZodString;
+        lower: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type SettingFieldType = z.infer<typeof SettingFieldTypeSchema>;
+type LineStyle = z.infer<typeof LineStyleSchema>;
+type SettingField = z.infer<typeof SettingFieldSchema>;
+type IndicatorSettings = z.infer<typeof IndicatorSettingsSchema>;
+type IndicatorMetadata = z.infer<typeof IndicatorMetadataSchema>;
+type RenderConfig = z.infer<typeof RenderConfigSchema>;
+interface IndicatorOutput {
+    time: number;
+    value: number;
+    [key: string]: number;
+}
+type IndicatorCalculation = (bars: OHLCVBar[], settings: Record<string, any>) => IndicatorOutput[];
+interface IndicatorDefinition {
+    metadata: IndicatorMetadata;
+    settings: IndicatorSettings;
+    renderConfig: RenderConfig;
+    calculate: IndicatorCalculation;
+}
+interface IndicatorInstance {
+    id: string;
+    definitionId: string;
+    name: string;
+    settings: Record<string, any>;
+    data?: IndicatorOutput[];
+}
+declare const IndicatorInstanceSchema: z.ZodObject<{
+    id: z.ZodString;
+    definitionId: z.ZodString;
+    name: z.ZodString;
+    settings: z.ZodRecord<z.ZodString, z.ZodAny>;
+}, z.core.$strip>;
+
+interface ChartComponentProps {
+    bars: OHLCVBar[];
+    onLoadMoreData?: (oldestTimestamp: number) => void;
+    indicators?: IndicatorInstance[];
+    lines?: ChartLine[];
+    onBarUpdate?: (updatedBar: OHLCVBar) => void;
+    onNewBar?: (newBar: OHLCVBar) => void;
+    onDeleteLine?: (lineId: string) => void;
+    onAddLine?: (type: 'entry' | 'stopLoss' | 'takeProfit' | 'support' | 'resistance', price: number) => void;
+    onClearAllLines?: () => void;
+    enableBarSelection?: boolean;
+    onBarClick?: (bar: OHLCVBar | null) => void;
+}
+declare function ChartComponent({ bars, onLoadMoreData, indicators, lines, onBarUpdate, onNewBar, onDeleteLine, onAddLine, onClearAllLines, enableBarSelection, onBarClick, }: ChartComponentProps): react_jsx_runtime.JSX.Element;
+
+interface IndicatorBrowserProps {
+    isOpen: boolean;
+    onClose: () => void;
+    onAddIndicator: (definitionId: string) => void;
+}
+declare function IndicatorBrowser({ isOpen, onClose, onAddIndicator, }: IndicatorBrowserProps): react_jsx_runtime.JSX.Element | null;
+
+interface IndicatorSettingsFormProps {
+    settings: IndicatorSettings;
+    currentValues: Record<string, any>;
+    onChange: (key: string, value: any) => void;
+}
+declare function IndicatorSettingsForm({ settings, currentValues, onChange, }: IndicatorSettingsFormProps): react_jsx_runtime.JSX.Element;
+
+interface SettingsDialogProps {
+    isOpen: boolean;
+    onClose: () => void;
+    indicator: IndicatorInstance | null;
+    onSave: (indicatorId: string, settings: Record<string, any>) => void;
+}
+declare function SettingsDialog({ isOpen, onClose, indicator, onSave, }: SettingsDialogProps): react_jsx_runtime.JSX.Element | null;
+
+interface PersistenceAdapter {
+    saveIndicators(indicators: IndicatorInstance[]): Promise<void>;
+    loadIndicators(): Promise<IndicatorInstance[]>;
+    deleteIndicator(id: string): Promise<void>;
+}
+declare class LocalStoragePersistenceAdapter implements PersistenceAdapter {
+    private storageKey;
+    saveIndicators(indicators: IndicatorInstance[]): Promise<void>;
+    loadIndicators(): Promise<IndicatorInstance[]>;
+    deleteIndicator(id: string): Promise<void>;
+}
+declare class NoOpPersistenceAdapter implements PersistenceAdapter {
+    saveIndicators(indicators: IndicatorInstance[]): Promise<void>;
+    loadIndicators(): Promise<IndicatorInstance[]>;
+    deleteIndicator(id: string): Promise<void>;
+}
+declare function createPersistenceAdapter(kind: 'noop' | 'localStorage'): PersistenceAdapter;
+
+interface UseChartAPIOptions {
+    persistenceAdapter?: PersistenceAdapter;
+}
+declare function useChartAPI(options?: UseChartAPIOptions): {
+    lines: ChartLine[];
+    indicators: IndicatorInstance[];
+    isLoadingIndicators: boolean;
+    addLine: (id: string, price: number, options?: {
+        color?: string;
+        lineWidth?: number;
+        lineStyle?: "solid" | "dashed" | "dotted";
+        title?: string;
+    }) => void;
+    removeLine: (id: string) => void;
+    updateLine: (id: string, price: number) => void;
+    addEntryLine: (price: number) => void;
+    addStopLoss: (price: number) => void;
+    addTakeProfit: (price: number) => void;
+    addSupportLine: (price: number) => void;
+    addResistanceLine: (price: number) => void;
+    clearAllLines: () => void;
+    addLineByType: (type: "entry" | "stopLoss" | "takeProfit" | "support" | "resistance", price: number) => void;
+    addIndicator: (definitionId: string, customSettings?: Record<string, any>) => IndicatorInstance;
+    removeIndicator: (id: string) => void;
+    updateIndicatorSettings: (id: string, settings: Record<string, any>) => void;
+};
+
+interface HistoricalDataParams {
+    symbol: string;
+    timeframe: string;
+    before?: number;
+    after?: number;
+    limit?: number;
+}
+interface RealtimeSubscription {
+    unsubscribe: () => void;
+}
+interface RealtimeHandlers {
+    onBar?: (bar: OHLCVBar) => void;
+    onTrade?: (price: number, volume: number) => void;
+    onError?: (error: Error) => void;
+    onConnect?: () => void;
+    onDisconnect?: () => void;
+}
+interface BarDataAdapter {
+    fetchHistoricalBars(params: HistoricalDataParams): Promise<OHLCVBar[]>;
+    subscribeRealtime?(symbol: string, handlers: RealtimeHandlers): RealtimeSubscription;
+    unsubscribeAll?(): void;
+}
+interface BarDataAdapterOptions {
+    apiKey?: string;
+    secretKey?: string;
+    baseUrl?: string;
+    [key: string]: any;
+}
+
+interface UseBarsDataOptions {
+    adapter?: BarDataAdapter;
+    symbol?: string;
+    timeframe?: string;
+    autoFetch?: boolean;
+    autoSubscribe?: boolean;
+    limit?: number;
+}
+interface UseBarsDataReturn {
+    bars: OHLCVBar[];
+    loading: boolean;
+    error: Error | null;
+    connected: boolean;
+    setBars: (bars: OHLCVBar[]) => void;
+    appendBar: (bar: OHLCVBar) => void;
+    updateLastBar: (bar: OHLCVBar) => void;
+    updateCurrentBar: (tradePrice: number, tradeVolume: number) => void;
+    prependBars: (bars: OHLCVBar[]) => void;
+    clearBars: () => void;
+    fetchHistorical: (params?: Partial<HistoricalDataParams>) => Promise<void>;
+    subscribe: () => void;
+    unsubscribe: () => void;
+    refetch: () => Promise<void>;
+}
+declare function useBarsData(options?: UseBarsDataOptions): UseBarsDataReturn;
+
+interface RealtimeUpdateConfig {
+    enabled: boolean;
+    updateIntervalMs: number;
+    newBarIntervalMs: number;
+}
+declare function useRealtimeUpdates(initialBars: OHLCVBar[], config: RealtimeUpdateConfig): {
+    bars: OHLCVBar[];
+    updateCurrentBar: (tradePrice: number, tradeVolume: number) => void;
+    addNewBar: (newBar: OHLCVBar) => void;
+    prependBars: (newBars: OHLCVBar[]) => void;
+};
+
+declare class IndicatorRegistry {
+    private indicators;
+    private instanceCounters;
+    register(definition: IndicatorDefinition): void;
+    unregister(id: string): boolean;
+    get(id: string): IndicatorDefinition | undefined;
+    getAll(): IndicatorDefinition[];
+    getByCategory(category: IndicatorCategory): IndicatorDefinition[];
+    search(query: string): IndicatorDefinition[];
+    createInstance(definitionId: string, customSettings?: Record<string, any>): IndicatorInstance;
+    validateSettings(definitionId: string, settings: Record<string, any>): boolean;
+    getMetadataList(): IndicatorMetadata[];
+    clear(): void;
+}
+declare const indicatorRegistry: IndicatorRegistry;
+
+declare class IndicatorCalculator {
+    private cache;
+    private hashSettings;
+    calculate(instance: IndicatorInstance, bars: OHLCVBar[]): IndicatorOutput[];
+    invalidateCache(instanceId?: string): void;
+    getCacheSize(): number;
+}
+declare const indicatorCalculator: IndicatorCalculator;
+
+declare const SMAIndicator: IndicatorDefinition;
+
+declare const EMAIndicator: IndicatorDefinition;
+
+declare const RSIIndicator: IndicatorDefinition;
+
+declare const BollingerBandsIndicator: IndicatorDefinition;
+
+declare const VWAPIndicator: IndicatorDefinition;
+
+declare const StochasticIndicator: IndicatorDefinition;
+
+declare const OBVIndicator: IndicatorDefinition;
+
+declare const MFIIndicator: IndicatorDefinition;
+
+declare const ForceIndexIndicator: IndicatorDefinition;
+
+declare const ATRIndicator: IndicatorDefinition;
+
+declare const ADXIndicator: IndicatorDefinition;
+
+declare const MACDIndicator: IndicatorDefinition;
+
+declare const PSARIndicator: IndicatorDefinition;
+
+declare const CCIIndicator: IndicatorDefinition;
+
+declare const WilliamsRIndicator: IndicatorDefinition;
+
+declare const KeltnerChannelsIndicator: IndicatorDefinition;
+
+declare const SuperTrendIndicator: IndicatorDefinition;
+
+declare const IchimokuIndicator: IndicatorDefinition;
+
+declare const DonchianChannelsIndicator: IndicatorDefinition;
+
+declare const ROCIndicator: IndicatorDefinition;
+
+declare const StochRSIIndicator: IndicatorDefinition;
+
+declare const WMAIndicator: IndicatorDefinition;
+
+declare function registerBuiltInIndicators(): void;
+
+declare function padIndicatorArray(result: number[], barsLength: number): number[];
+declare function displaceArray(arr: number[], offset: number): number[];
+declare function calculateSMA(bars: OHLCVBar[], period: number): number[];
+declare function calculateEMA(bars: OHLCVBar[], period: number): number[];
+declare function calculateRSI(bars: OHLCVBar[], period: number): number[];
+declare function calculateStandardDeviation(values: number[], period: number): number[];
+declare function calculateBollingerBands(bars: OHLCVBar[], period: number, stdDev: number): {
+    upper: number[];
+    middle: number[];
+    lower: number[];
+};
+
+declare class AlpacaBarAdapter implements BarDataAdapter {
+    private apiKey;
+    private secretKey;
+    private baseUrl;
+    private wsUrl;
+    private ws;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private reconnectDelay;
+    private currentHandlers;
+    private currentSymbol;
+    private authenticated;
+    constructor(options: BarDataAdapterOptions);
+    fetchHistoricalBars(params: HistoricalDataParams): Promise<OHLCVBar[]>;
+    subscribeRealtime(symbol: string, handlers: RealtimeHandlers): RealtimeSubscription;
+    unsubscribeAll(): void;
+    private connectWebSocket;
+    private authenticate;
+    private subscribe;
+    private handleMessage;
+    private handleTrade;
+    private handleBar;
+    private attemptReconnect;
+    private disconnect;
+    private convertAlpacaBars;
+}
+
+declare class MockAdapter implements BarDataAdapter {
+    private intervalId;
+    fetchHistoricalBars(params: HistoricalDataParams): Promise<OHLCVBar[]>;
+    subscribeRealtime(symbol: string, handlers: RealtimeHandlers): RealtimeSubscription;
+    unsubscribeAll(): void;
+}
+
+declare function validateBar(bar: any): bar is OHLCVBar;
+declare function isValidBar(bar: any): bar is OHLCVBar;
+declare function normalizeTimestamp(timestamp: number): number;
+declare function sortBars(bars: OHLCVBar[]): OHLCVBar[];
+declare function deduplicateBars(bars: OHLCVBar[]): OHLCVBar[];
+declare function mergeBars(existingBars: OHLCVBar[], newBars: OHLCVBar[]): OHLCVBar[];
+declare function validateAndNormalizeBars(bars: any[]): OHLCVBar[];
+declare function updateBarInArray(bars: OHLCVBar[], updatedBar: OHLCVBar): OHLCVBar[];
+declare function appendBar(bars: OHLCVBar[], newBar: OHLCVBar): OHLCVBar[];
+declare function prependBars(bars: OHLCVBar[], newBars: OHLCVBar[]): OHLCVBar[];
+declare function getOldestBar(bars: OHLCVBar[]): OHLCVBar | null;
+declare function getNewestBar(bars: OHLCVBar[]): OHLCVBar | null;
+declare function updateCurrentBar(bars: OHLCVBar[], tradePrice: number, tradeVolume: number): OHLCVBar[];
+
+export { ADXIndicator, ATRIndicator, AlpacaBarAdapter, type BarDataAdapter, type BarDataAdapterOptions, BollingerBandsIndicator, CCIIndicator, ChartComponent, type ChartLine, ChartSeriesType, DonchianChannelsIndicator, EMAIndicator, ForceIndexIndicator, type HistoricalDataParams, IchimokuIndicator, IndicatorBrowser, type IndicatorCalculation, IndicatorCategory, type IndicatorDefinition, type IndicatorInstance, IndicatorInstanceSchema, type IndicatorMetadata, IndicatorMetadataSchema, type IndicatorOutput, type IndicatorPanel, type IndicatorSettings$1 as IndicatorSettings, IndicatorSettingsForm, IndicatorSettingsSchema, KeltnerChannelsIndicator, type LineStyle, LineStyleSchema, LocalStoragePersistenceAdapter, MACDIndicator, MFIIndicator, MockAdapter, NoOpPersistenceAdapter, OBVIndicator, type OHLCVBar, PSARIndicator, type PersistenceAdapter, ROCIndicator, RSIIndicator, type RealtimeHandlers, type RealtimeSubscription, type RenderConfig, RenderConfigSchema, SMAIndicator, type SettingField, SettingFieldSchema, type SettingFieldType, SettingFieldTypeSchema, SettingsDialog, StochRSIIndicator, StochasticIndicator, SuperTrendIndicator, VWAPIndicator, WMAIndicator, WilliamsRIndicator, appendBar, calculateBollingerBands, calculateEMA, calculateRSI, calculateSMA, calculateStandardDeviation, createPersistenceAdapter, deduplicateBars, displaceArray, getNewestBar, getOldestBar, indicatorCalculator, indicatorRegistry, isValidBar, mergeBars, normalizeTimestamp, padIndicatorArray, prependBars, registerBuiltInIndicators, sortBars, updateBarInArray, updateCurrentBar, useBarsData, useChartAPI, useRealtimeUpdates, validateAndNormalizeBars, validateBar };