hyperliquid_chart_engine 0.1.1

Professional financial charting engine for Flutter — TradingView-style charts with 21+ chart types, drawing tools, indicators, and real-time data.

Hyperliquid Chart Engine

O Hyperliquid Chart Engine é uma biblioteca Flutter nativa e de altíssima performance para visualização gráfica financeira. Desenvolvido para operações de nível institucional (corretoras, home brokers e exchanges de criptomoedas), seu core utiliza as APIs de baixíssimo nível de renderização (Canvas/CustomPaint) combinadas com a reatividade do Riverpod, oferecendo +20 recursos técnicos essenciais de análise gráfica rodando de 60 a 120 FPS fluidos.

---

🌟 Principais Inovações Técnicas

1. Eficiência 100% O(N) para O(1): Nossos calculadores assíncronos não recalibram milhares de barras de histórico para a chegada de um novo tick. O método calculateIncremental gerencia buffers de janelas dinâmicas O(1) de modo suave.
2. Viewport Culling Híbrido: O pipeline identifica quais segmentos das barras e desenhos estão visíveis na matriz da tela (eixos X e Y) e descarta o carregamento raster off-screen.
3. Decimation Engine: Diminui drasticamente as sobreposições de barras quando o zoom está máximo (condensando clusters visuais idênticos) sem perder fidelidade do ponto.
4. Painéis Interativos Independentes: Assim como o TradingView, o gráfico pode rodar com indicadores "Overlay" no preço (ex: MACD signal) ou "Pannels" embaixo do eixo.

---

🚀 Instalação Rápida

Adicione em seu pubspec.yaml:

dependencies:
  hyperliquid_chart_engine: ^0.1.0
  flutter_riverpod: ^2.6.1 # Recomendado para instanciar as árvores de provider

---

📊 1. Tipos de Gráficos (Chart Types)

No núcleo da engine, ChartWidget gerencia como as propriedades matemáticas estruturam os corpos na pintura visual.

Temos suportes clássicos dependentes apenas de OHLCV (Open, High, Low, Close, Volume) e tipos baseados em ação estrita do preço.

Tipo de Gráfico	Flag no Widget	Descrição de Renderização
Candles Clássicos	ChartType.candles	Corpos preenchidos e pavios com bordas. Padrão asiático
OHLC Bars	ChartType.bars	Sem body, linhas abertas em flag
Hollow Candles	ChartType.hollowCandles	Velas estéticas com preenchimento vazio para altas, foco em continuidade de tendências
Volume Candles	ChartType.volumeCandles	Largura proporcional e coloração baseada em densidade de capital
Linha Contínua	ChartType.line	Curva B-Spline no preço de Fechamento (Close)
Área Sombreada	ChartType.area	Espectro preenchido embaixo da curva B-Spline
Heikin Ashi	ChartType.heikinAshi	Manipulação estocástica (Open e Close suavizados pelas médias do corpo anterior)
Kagi	ChartType.kagi	Alterna inflexões na thickness das setas unicolor, independentes de tempo.
Pontos e Figuras	ChartType.pointAndFigure	Blocos de "X" (Subida) e "O" (Descida) ancorados em ticks absolutos
Renko	ChartType.renko	Bricks (tijolos) atemporais criados 100% sobre quebras e retrocessos limpos do preço

Como renderizar uma forma visual diferente?

ChartWidget(
  bars: myHistoricalData, 
  chartType: ChartType.heikinAshi, // Substitua aqui
  theme: ChartTheme.dark(), 
);

---

🧮 2. Setup e Integração de Indicadores

A grande evolução do pacote é seu mapeador de Painéis (PanelConfig). Renderize seus indicadores ativando switches no dicionário central do Widget.

Nossa arquitetura conta com Provider Notifiers, que calculam tudo nos bastidores.

Exemplo Prático: Plotando Gráfico com EMA, MACD e Volume

ChartWidget(
  bars: myHistoricalData,     
  chartType: ChartType.candles,

  // Indicadores de SOBREPOSIÇÃO (Overlays) - Renderizam em cima dos Candles
  showVWAP: true,         // Volume Weighted Average Price
  showBollingerBands: true, // Bandas de Bollinger

  // Indicadores em PAINÉIS EXTRAS (Panels) - Renderizam no layout inferior
  panels: [
    if (showVolume) PanelConfig(type: PanelType.volume, heightRatio: 0.15),
    if (showMacd)   PanelConfig(type: PanelType.macd, heightRatio: 0.2),
    if (showRsi)    PanelConfig(type: PanelType.rsi, heightRatio: 0.15),
    if (showAtr)    PanelConfig(type: PanelType.atr, heightRatio: 0.15), // Average True Range
  ],
)

Nesta arquitetura, todo painel recalcula apenas em escala delta se alimentado por Websockets e não reinicia a tela!

---

🖌️ 3. Ferramentas de Desenho (Drawing Tools)

O Engine não apenas consome dados visuais; ele reage! O usuário consegue traçar polígonos, retas e suportes complexos.

A estrutura atual conta com duas principais ferramentas nativas:

1. Trend Lines (Linha de Tendência): ancorada em dois pontos A (x1,y1) e B (x2, y2).
2. Fibonacci Retracement: ferramenta avançada baseada em matemática natural que detecta automaticamente suportes de retração (0.0, 0.236, 0.382, 0.5, 0.618, 0.786 e 1.0) desenhando o tracking de níveis paralelamente.

Para habilitar a camada reativa:

1. Sete a ferramenta ativa conectada pelo seu StateNotifier:

   ref.read(activeDrawingToolProvider.notifier).state = DrawingToolType.fibonacci;
   

2. Arraste e solte o polegar - as interseções serão fixadas ao Timestamp absoluto em UTC, garantindo total flexibilidade com o zoom infinito do usuário. O re-draw não quebra o pixel-ratio e recria suportes visualmente acurados.

---

🔔 4. Motores de Alerta de Preço

Para traders autônomos, observar a tela passivamente é passado. O Hyperliquid Chart fornece o Alert Monitor Engine.

Ele acopla-se fluidamente com o Backend:

// Definindo que eu quero um Alerta Visual Vermelho quando o BTC bater $70.000,00
final alarm = PriceAlert(
    id: const Uuid().v4(),
    targetPrice: 70000.0,
    condition: AlertCondition.crossesUp, // cruzamento direcional de subida
    isActive: true,
);

ref.read(priceAlertsProvider.notifier).addAlert(alarm);
ref.read(alertMonitorProvider.notifier).startMonitoring(); 

O Canvas nativo plotará uma tag semi-transparente pontilhada com ícone lateral e o Observer interno vigiará o close price e disparará o callback sonoro ou Push.

---

🎨 5. Customização Completa (Theming Engine)

Tudo isso encapsulado com cores corporativas flexíveis:

final myCorpTheme = ChartTheme(
  background: const Color(0xFF131722),
  gridColor: const Color(0xFF2A2E39),
  bullish: Colors.greenAccent,
  bearish: Colors.redAccent,
  crosshair: Colors.grey,
  textStyle: const TextStyle(fontSize: 11, color: Colors.white70),
);

ChartWidget(
  theme: myCorpTheme,
  // ...
)

---

Desenvolvido para Escala

Mais de 150 mil pontos de série OHLCV (barras M1 de cripto) mapeados simultaneamente testam nosso garbage collector nativo, decimation filter, e culling. Se você desenvolve ferramentas em Node/Rails/NestJS para TradingView, sentirá um impacto de responsividade em C++ com as bibliotecas nativas de compilação da plataforma!