Packages

Incremental candlestick chart: one bar in, that bar's shapes out

Current section

Files

Jump to
Raw

README.md

# bar_stream_chart

[![Package Version](https://img.shields.io/hexpm/v/bar_stream_chart)](https://hex.pm/packages/bar_stream_chart)
[![Hex Docs](https://img.shields.io/badge/hex-docs-ffaff3)](https://bar-stream-chart.hexdocs.pm/)

An incremental candlestick chart specification with no GUI-framework dependency.
One bar arrives, that bar's shapes are generated, and a framework-neutral shape
IR is returned for a renderer to translate.

```sh
gleam add bar_stream_chart@1
```

```gleam
import bar_stream_chart
import gleam/option.{None}

pub fn main() -> Nil {
  let chart =
    bar_stream_chart.empty(
      bar_stream_chart.Geometry(width: 800.0, height: 600.0),
      bar_stream_chart.PriceScaleLinear,
    )

  let bar =
    bar_stream_chart.Bar(
      idx: 0,
      open: 100.0,
      high: 102.0,
      low: 99.0,
      close: 101.0,
      volume: 1200,
      sma_medium: 100.5,
      yin_leaf_cma: 100.2,
      yang_leaf_cma: 101.1,
      k: 70.0,
      d: 60.0,
      j: 90.0,
      bb_u3: 103.0,
      bb_l3: 97.0,
      signal: bar_stream_chart.SignalHold,
    )

  let chart = bar_stream_chart.push(chart, bar)
  let layers =
    bar_stream_chart.shapes(
      chart,
      bar_stream_chart.default_viewport(bar_stream_chart.len(chart)),
      None,
    )

  // layers.axes / candles / overlays / volume / kdj / crosshair
  // are List(SpecShape); translate them to your renderer's nodes.
  let _ = layers
  Nil
}
```

Further documentation can be found at <https://bar-stream-chart.hexdocs.pm/>.

## Design rules

- `push(chart, bar)` is the **only** input. There is no batch API, no replay,
  and no way to load a list of bars.
- `Chart` is opaque. It stores generated shapes, O(1) carried bounds, and the
  one previous point set needed to draw connectors — never a copy of the
  caller's bar list. A single carried bar is transient state, not a model copy.
- `shapes` only assembles already-generated shapes. Zoom and pan change a
  viewport and apply one affine transform per layer; they never revisit old
  bar shapes.
- Output colours follow the Chinese market convention: up is red, down is
  green.
- View and model are separate: the caller owns its own data model, translates
  one bar into `bar_stream_chart.Bar`, and consumes the returned shape IR.

The plushie canvas adapter lives in `try_plushie/src/fusion_view.gleam`; it
translates `SpecShape` into plushie `PropValue` nodes without changing the
chart's behaviour.

## Release

See [`RELEASE.md`](RELEASE.md) for the maintainer's hex.pm publishing checklist.

## Development

```sh
gleam test                    # pure-function tests, no renderer needed
gleam build --warnings-as-errors
gleam format --check
gleam docs build
```