@livo-build/charts 0.2.1 → 0.2.2

package/README.md

@@ -1,5 +1,9 @@
 # @livo-build/charts (livo-charts)
 
+> **Live demos + docs: [charts.livo.build](https://charts.livo.build)** — interactive
+> examples with copy-paste code, plus agent-friendly [llms.txt](https://charts.livo.build/llms.txt)
+> / [llms-full.txt](https://charts.livo.build/llms-full.txt).
+
 A lightweight, **dependency-free** canvas charting library. The core renders to a
 `<canvas>` with zero runtime dependencies; a thin, self-styled React wrapper is
 shipped under a separate entry so non-React consumers never pull React into their
@@ -7,8 +11,8 @@ bundle.
 
 It ships a **TradingView-style trading chart**: candlesticks **or** a line series, a
 **volume panel**, a **crosshair with price + time axis labels**, an **OHLCV legend**,
-independent **X and Y zoom** (+ pan), and a toolbar for **intervals, USD/ETH,
-price/market-cap and fullscreen**. The architecture (a framework-agnostic `Chart`
+independent **X and Y zoom** (+ pan, plus touch/pinch), and a toolbar for **intervals,
+USD/ETH, price/market-cap, log scale and fullscreen**. The architecture (a framework-agnostic `Chart`
 controller + a pure `draw()` pass) is built to keep growing — indicators, overlays,
 multiple panes — without touching consumers.
 
@@ -28,8 +32,7 @@ import { PriceChart } from "@livo-build/charts/react";
 <PriceChart
   swaps={trades}          // [{ t: unixSeconds, p: priceUsd, v: usdVolume }, …]
   ethUsd={1711.81}        // enables the USD↔ETH toggle
-  tokenAddress="0x…"      // enables the Price↔MCap toggle (reads totalSupply())
-  decimals={18}
+  supply={1_000_000_000}  // enables the Price↔MCap toggle (or tokenAddress to read it)
   symbol="PEPE"
   quote="WETH"
   height={420}
@@ -37,14 +40,15 @@ import { PriceChart } from "@livo-build/charts/react";
 ```
 
 `swaps` are aggregated into OHLC+volume candles client-side. The toolbar
-(`1s 1m 5m 15m 1h 4h 1d`, candle/line, Price/MCap, USD/ETH, flip, fullscreen) and the
+(`1s 1m 5m 15m 1h 4h 1d`, candle/line, Price/MCap, USD/ETH, flip, log, fullscreen) and the
 OHLCV legend are built in. The canvas is long-lived, so zoom/pan survive prop updates
 (streaming trades won't reset the user's view). The wrapper is styled inline — no CSS
 framework required.
 
-Market cap = `price × totalSupply()`, fetched once via `rpcUrl` (default
-`https://cloudflare-eth.com`) and cached; it silently falls back to price if the RPC
-is unavailable.
+Market cap = `price × supply`. Pass `supply` directly, or pass `tokenAddress` (+`decimals`)
+to read `totalSupply()` once via `rpcUrl` (default `https://cloudflare-eth.com`, cached).
+The **Price/MCap toggle only appears when one of those is set** — otherwise it's hidden
+(no dead button), and it falls back to price if the RPC read fails.
 
 ### Live Hyperliquid chart
 
@@ -71,12 +75,82 @@ API key. Zoom/pan survive every update.
 ### Indicators
 
 `PriceChart` and `HyperliquidChart` accept `indicators` — overlays drawn on the price
-pane. Each is `{ type: "sma" | "ema" | "wma" | "vwap", period, color?, source? }`
-(`source` defaults to `close`; `vwap` is cumulative and ignores period/source).
+pane. Each is `{ type: "sma" | "ema" | "wma" | "vwap" | "bollinger", period, color?, source?, mult? }`
+(`source` defaults to `close`; `vwap` is cumulative; `bollinger` draws a 3-line band at
+`mult` std-devs, default 2).
 Colors fall back to a built-in palette by position. The pure
 `sma`/`ema`/`wma`/`vwap`/`bollingerBands`/`computeIndicator` helpers are exported from
 the core (e.g. feed `bollingerBands(values).{upper,mid,lower}` as three overlays).
 
+**Oscillators (RSI / MACD)** render in their own **stacked sub-panes** below the volume
+panel — pass `oscillators`:
+
+```tsx
+<PriceChart
+  swaps={trades}
+  indicators={[{ type: "ema", period: 21 }]}   // on the price pane
+  oscillators={[
+    { type: "rsi", period: 14 },               // 0–100 band with 70/30 rails
+    { type: "macd", fast: 12, slow: 26, signal: 9 },  // line + signal + histogram
+  ]}
+/>
+```
+
+Each pane defaults to 84px (`height` to override). The pure `rsi(values, period)` and
+`macd(values, fast, slow, signal) → { macd, signal, hist }` helpers are exported too.
+
+### Fitting the container & axis styling
+
+By default `PriceChart` / `HyperliquidChart` **fit the container** (`fitContent`) — candles
+spread across the full plot width instead of clustering at a capped slot. Set
+`fitContent={false}` for the tight, right-anchored look (the low-level `Chart` defaults to
+tight; the React wrappers default to fill).
+
+The ticks are easy to style — every axis knob is a prop (and a `chart.setAxis({…})` call):
+
+```tsx
+<PriceChart
+  swaps={trades}
+  priceFormat={(v) => `$${v.toLocaleString()}`}  // y-axis labels
+  timeFormat={(t) => new Date(t * 1000).toLocaleTimeString()}
+  priceTicks={6}                                  // horizontal gridlines (default 5)
+  timeTicks={8}                                   // x-axis labels (default 7)
+  axisFont="11px Inter, sans-serif"               // label font (color = theme.axis)
+/>
+```
+
+The **default** price formatter is range-aware: it keeps just enough decimals to tell
+adjacent ticks apart, so a narrow high-value axis (e.g. WETH 1.71K–1.75K) renders
+`1.7350K / 1.7430K` instead of duplicate `1.73K`s. Tick text color comes from `theme.axis`.
+
+### Log scale & themes
+
+The price axis can be **logarithmic** — equal vertical distance = equal % move, the
+right default for assets that span orders of magnitude. `PriceChart`/`HyperliquidChart`
+expose a **Log** toolbar toggle (or pass `options={{ logScale: true }}`); the core has
+`chart.setLogScale(true)`. Log mode auto-falls back to linear if any visible low is ≤ 0.
+
+Two built-in themes ship as `DEFAULT_THEME` (dark) and `LIGHT_THEME`, also addressable
+via `THEME_PRESETS.dark` / `THEME_PRESETS.light`. Pass either (or a partial override) as
+`theme`, or call `chart.setTheme(LIGHT_THEME)`.
+
+### Drawing tools (trendlines & horizontal lines)
+
+The toolbar's **↗** (trendline) and **—** (horizontal line) buttons arm a one-shot draw:
+drag for a trendline, click for a horizontal price line. Drawings are anchored in **data
+space**, so they stay pinned to their price/time across pan, zoom and live updates. In the
+default cursor mode, click a line to select it, drag to move it, and **double-click a line
+to delete it**; **⌫** clears all.
+
+```tsx
+<PriceChart swaps={trades} onDrawingsChange={(d) => save(d)} drawings={restored} />
+```
+
+Drive it from the core too: `chart.setDrawMode("trendline" | "hline" | "none")`,
+`getDrawings()` / `setDrawings()` / `removeDrawing(id)` / `clearDrawings()`, and the
+`onDrawingsChange` callback. Pass `hideDrawingTools` to drop the buttons. The
+`computeProjection(input)` helper exposes the same pixel↔data mapping for custom tools.
+
 ### Realtime feeds + lazy history (any data source)
 
 Connect a chart to a **feed** — a source that serves paged OHLCV history *and* live
@@ -133,7 +207,13 @@ chart.destroy();
 | `setCandles(candles)` | Replace the series (each candle has `vol`) and redraw. |
 | `setInterval(seconds)` | Bucket interval — drives time-axis label granularity. |
 | `setChartType("candle" \| "line")` | Switch series style. |
+| `setShowVolume(on)` | Show / hide the volume panel (the price pane reclaims the space). |
+| `setLogScale(on)` | Toggle the logarithmic price axis (auto-falls back to linear if any low ≤ 0). |
+| `setAxis({ fitContent, priceFormat, timeFormat, priceTicks, timeTicks, axisFont })` | Style the axes — only the provided keys change. |
 | `setIndicators(indicators)` | Set the moving-average overlays and redraw. |
+| `setOscillators(oscillators)` | Set the RSI / MACD sub-panes and redraw. |
+| `setDrawMode(mode)` | Arm a drawing tool (`"trendline"` / `"hline"`) or `"none"`. |
+| `setDrawings` / `getDrawings` / `removeDrawing(id)` / `clearDrawings()` | Manage drawings. |
 | `setNeedHistory(cb)` | Callback fired when the view nears the start of loaded data (lazy history). |
 | `setHeight(px)` / `setTheme(partial)` | Resize / merge theme overrides. |
 | `resetView()` | Reset zoom/pan (same as double-click). |
@@ -142,15 +222,17 @@ chart.destroy();
 `ChartOptions`: `height`, `theme`, `initialBars` (120), `minBars` (20),
 `maxBarWidth` (18 — caps candle spacing so sparse series stay tight, right-anchored),
 `volumeRatio` (0.18), `rightPad`/`bottomPad`/`topPad`, `onCrosshair`, `indicators`,
-and `onNeedHistory`.
+`oscillators`, `drawings`, `showVolume` (true), `logScale` (false), `fitContent` (false),
+`maxBarWidth` (18) / `maxBodyWidth` (40), `priceFormat`/`timeFormat`, `priceTicks` (5) /
+`timeTicks` (7), `axisFont`, and `onNeedHistory`.
 
 ### Helpers
 
 - `buildOHLC(points, interval, transform?)` — bucket priced trades into OHLC+volume
   candles. `transform` = `{ denom, ethUsd, flip, supply }` (`supply` → market cap).
 - `transformPrice(p, transform?)` — apply the transform to one price.
-- `sma` / `ema` / `wma` / `vwap` / `bollingerBands` / `computeIndicator` — pure
-  indicator math (aligned to input, null until the window fills).
+- `sma` / `ema` / `wma` / `vwap` / `bollingerBands` / `rsi` / `macd` / `computeIndicator`
+  — pure indicator math (aligned to input, null until the window fills).
 - `connectFeed(chart, feed, opts)` — wire a `ChartFeed` (paged history + live stream)
   to a chart: latest page, lazy older history, live merge. Returns `{ disconnect }`.
 - `hyperliquidFeed({ coin, interval, testnet })` — a ready `ChartFeed` (REST history +
@@ -158,14 +240,24 @@ and `onNeedHistory`.
   `HL_INTERVAL_SECONDS` are exported for custom fetching.
 - `draw(input)` — the pure render pass (exported for custom hosts/tests); returns the
   crosshair candle.
-- `DEFAULT_THEME`, `formatValue`, `formatVolume`, `formatTime`.
+- `DEFAULT_THEME` / `LIGHT_THEME` / `THEME_PRESETS`, `formatValue`, `formatAxisValue`
+  (range-aware tick labels), `formatVolume`, `formatTime`.
+- `slotWidth(plotW, count, maxBarWidth, fitContent?)` — candle slot-width math (exported
+  for custom hosts).
+- `computeProjection(input)` / `priceScale` / `timeScale` / `windowOf` — the pixel↔data
+  mapping the renderer and drawing tools share (returns `{ xOfTime, timeOfX, yOfPrice,
+  priceOfY, … }`).
 
 ## Interaction
 
 - **Scroll** over the plot → zoom time; over the price axis → zoom price.
 - **Drag** the plot → pan; drag the time axis → zoom X; drag the price axis → zoom Y.
 - **Hover** → crosshair + price/time axis labels + the OHLCV legend.
-- **Double-click** → reset zoom/pan.
+- **Double-click** → reset zoom/pan (or delete a drawing when one is under the cursor).
+- **Touch** → one finger pans (or zooms an axis from its gutter); two-finger pinch
+  zooms time (horizontal spread) and price (vertical spread) together.
+- **Drawing tools** → arm trendline/h-line from the toolbar; select + drag to move,
+  double-click to delete.
 
 ## Design notes
 

package/dist/core/chart.d.ts

@@ -1,4 +1,4 @@
-import type { Candle, ChartOptions, ChartTheme, ChartType, Indicator } from "./types";
+import type { AxisOptions, Candle, ChartOptions, ChartTheme, ChartType, DrawMode, Drawing, Indicator, Oscillator } from "./types";
 /**
  * Framework-agnostic candlestick/line chart with a volume panel. Creates and owns a
  * `<canvas>` inside the given container and wires the interactions:
@@ -23,17 +23,36 @@ export declare class Chart {
     private readonly ro;
     private readonly pads;
     private readonly minBars;
-    private readonly maxBarWidth;
+    private maxBarWidth;
+    private maxBodyWidth?;
     private readonly volumeRatio;
     private readonly onCrosshair?;
     private theme;
     private height;
     private candles;
     private indicators;
+    private oscillators;
+    private drawings;
+    private drawMode;
+    private selectedDrawing;
+    /** in-progress trendline (drag from anchor A to B). */
+    private draftDrawing;
+    /** active move of an existing drawing: its id + the data-space grab anchor + originals. */
+    private drawingDrag;
+    private onDrawingsChange?;
+    private onDrawModeChange?;
     /** Indicator values precomputed on data/indicator change (not per frame). */
     private overlays;
     private interval;
     private type;
+    private showVolume;
+    private logScale;
+    private fitContent;
+    private priceFormat?;
+    private timeFormat?;
+    private priceTicks?;
+    private timeTicks?;
+    private axisFont?;
     /** requestAnimationFrame handle coalescing high-frequency redraws (0 = none queued). */
     private raf;
     private onNeedHistory?;
@@ -44,12 +63,38 @@ export declare class Chart {
     private yZoom;
     private hover;
     private drag;
+    /** two-finger pinch baseline: finger spreads + view at gesture start. */
+    private pinch;
     private lastActive;
     constructor(container: HTMLElement, opts?: ChartOptions);
     setCandles(candles: Candle[]): this;
     setInterval(interval: number): this;
     setChartType(type: ChartType): this;
+    /** Show or hide the volume panel (the price pane reclaims the space when hidden). */
+    setShowVolume(on: boolean): this;
+    /** Toggle the logarithmic price axis (equal pixels = equal % move). */
+    setLogScale(on: boolean): this;
+    /** Style the axes: fill-vs-tight candle spacing, custom price/time label formatters,
+     *  tick counts, and the label font. Only the provided keys change. */
+    setAxis(opts: AxisOptions): this;
     setIndicators(indicators: Indicator[]): this;
+    /** Set the oscillator sub-panes (RSI / MACD) drawn below the volume panel. */
+    setOscillators(oscillators: Oscillator[]): this;
+    /** Arm a drawing tool ("trendline" / "hline"), or "none" for pan/zoom + select/move.
+     *  Drawing tools are one-shot: after one drawing the mode auto-resets to "none". */
+    setDrawMode(mode: DrawMode): this;
+    /** Replace all drawings (does not fire onDrawingsChange). */
+    setDrawings(drawings: Drawing[]): this;
+    /** Current drawings (a copy). */
+    getDrawings(): Drawing[];
+    /** Remove a drawing by id. */
+    removeDrawing(id: string): this;
+    /** Remove the currently selected drawing, if any. */
+    deleteSelected(): this;
+    /** Remove all drawings. */
+    clearDrawings(): this;
+    private emitDrawings;
+    private exitDrawMode;
     /** Register a callback fired when the user pans/zooms near the start of loaded data
      *  (so a feed can lazily load older candles). See connectFeed. */
     setNeedHistory(cb: (() => void) | undefined): this;
@@ -61,6 +106,10 @@ export declare class Chart {
     private get plotW();
     private measure;
     private clampView;
+    /** Assemble the {@link RenderInput} from current state — shared by render() and projection(). */
+    private buildInput;
+    /** Pixel↔data projection for the current frame (null when there are no candles). */
+    private projection;
     private render;
     /** Coalesce high-frequency redraws (drag/hover/wheel) into one per animation frame. */
     private scheduleRender;
@@ -73,9 +122,19 @@ export declare class Chart {
     private readonly onWheel;
     /** Zoom the time axis by factor `f`, keeping the candle under `cursorX` anchored. */
     private zoomTimeAt;
+    /** Topmost drawing under the pointer (within tolerance), or null. */
+    private hitTest;
     private readonly onDown;
     private readonly onMove;
+    /** Translate the dragged drawing by the pointer's data-space delta from the grab anchor. */
+    private applyDrawingDrag;
+    /** Apply an in-progress drag (pan or axis-zoom) from the current pointer position.
+     *  Shared by mouse-move and single-finger touch-move. Returns true if a drag is active. */
+    private applyDrag;
     private readonly onUp;
     private readonly onLeave;
     private readonly onDouble;
+    private readonly onTouchStart;
+    private readonly onTouchMove;
+    private readonly onTouchEnd;
 }