wick-charts 0.9.0 → 0.10.1

package/README.md

@@ -208,6 +208,8 @@ const chart = createCandlestickChart(canvas, {
   },
   crosshair: {
     lineColor: '#9090904d',
+    lineWidth: 1,
+    lineDash: [4, 4], // [] for a solid line — same convention as ctx.setLineDash
     labelBackground: '#3a3a3a',
     labelTextColor: '#f0f0f0',
     labelPaddingX: 4,
@@ -249,12 +251,18 @@ it per chart instance via `formatLegend`:
 const chart = createCandlestickChart(canvas, {
   formatLegend(candle, style, { index, allPoints }) {
     const prev = allPoints[index - 1];
-    const change = prev ? (((candle.close - prev.close) / prev.close) * 100).toFixed(2) : null;
+    const change = prev ? ((candle.close - prev.close) / prev.close) * 100 : null;
     return [
       `시가 ${candle.open.toLocaleString()}`,
       `고가 ${candle.high.toLocaleString()}`,
       `저가 ${candle.low.toLocaleString()}`,
-      `종가 ${candle.close.toLocaleString()}${change === null ? '' : ` (${change}%)`}`,
+      `종가 ${candle.close.toLocaleString()}`,
+      // A line can be a plain string (drawn in legend.textColor, like the
+      // four above) or { text, color } for one that needs its own color —
+      // see "Coloring individual legend lines" just below.
+      change === null
+        ? '등락 —'
+        : { text: `등락 ${change >= 0 ? '+' : ''}${change.toFixed(2)}%`, color: change >= 0 ? '#22c55e' : '#ef4444' },
     ];
   },
 });
@@ -266,6 +274,20 @@ point currently loaded (not just visible), the same array a `ChartPlugin` reads
 `PluginRenderApi.allPoints`; `index` is `candle`'s position in it, so `allPoints[index - 1]` is
 the previous point regardless of where the user has panned/zoomed to.
 
+#### Coloring individual legend lines
+
+Every line returned by `formatLegend` is a `LegendLine` — either a plain `string`, drawn in
+`legend.textColor` like every line before this existed, or `{ text, color }` for one line that
+needs its own color independent of the rest (the `change` line above: green when positive, red
+when negative, regardless of `legend.textColor`). Mixing both shapes in one returned array, as
+above, is the normal case — only the lines that actually need a distinct color use the object
+form. There's no chart-wide "green means up" setting for this: which color means "up" is a
+convention that varies by market (green-up in most markets, red-up in South Korea and a few
+others) and isn't something the library should hardcode, so `formatLegend` decides it per line
+the same way it decides everything else about the legend's text. This is separate from
+`CandlestickStyle.upColor`/`downColor`, which is the *candle's own* body/wick color, a
+chart-wide setting rather than something recomputed per hovered point.
+
 `SeriesDefinition.formatLegend` (what candlestick/line ship with) is a shared default for every
 chart of that *type*; `WickChartOptions.formatLegend` is the per-*instance* override above it —
 reach for the latter for anything that varies by app, session, or locale rather than by chart
@@ -592,6 +614,62 @@ the price pane — an indicator pane's own hover readout, if you want one, is so
 plugin draws (it has the same `xForIndex`/`yForValue` a price-pane plugin does, just mapped
 against that pane's own value domain and pixel rect).
 
+### Splitting volume into its own pane
+
+The candlestick series' default volume bars are a translucent backdrop *inside* the price
+pane (`CandlestickStyle.volumeAreaHeightRatio`, `0.2` of the chart height by default) — fine
+for a compact chart, but on a tall one, or whenever a candle's own range dips into that bottom
+margin, the bars visually collide with the candles drawn over them. The same `addPane` +
+`ChartPlugin.paneId` mechanism the previous section uses for RSI/MACD works just as well for
+volume — it just reads `Candle.volume` instead of computing an indicator:
+
+```ts
+// PaneOptions.getValueRange takes no arguments, so — same as the MACD pane above needing its
+// own auto-fit range — it closes over the chart's current data itself rather than reading it
+// from an argument. `allData` is whatever you last passed to `chart.setData()`.
+let allData: Candle[] = [];
+
+const chart = createCandlestickChart(canvas, {
+  style: { volumeAreaHeightRatio: 0 }, // suppress the in-pane backdrop — see below for why
+});
+
+chart.addPane({
+  id: 'volume',
+  heightRatio: 0.15,
+  getValueRange: () => {
+    const { startIndex, endIndex } = chart.getVisibleRange();
+    let max = 0;
+    for (let i = startIndex; i < endIndex; i++) max = Math.max(max, allData[i]?.volume ?? 0);
+    return { min: 0, max: max || 1 };
+  },
+});
+
+chart.addPlugin({
+  paneId: 'volume',
+  draw({ ctx, allPoints, visibleStartIndex, visibleEndIndex, xForIndex, yForValue }) {
+    const zeroY = yForValue(0);
+    const barWidth = (xForIndex(visibleStartIndex + 1) - xForIndex(visibleStartIndex)) * 0.6;
+    for (let i = visibleStartIndex; i < visibleEndIndex; i++) {
+      const c = allPoints[i];
+      if (c.volume === undefined) continue;
+      ctx.fillStyle = c.close >= c.open ? '#26a69a' : '#ef5350';
+      const y = yForValue(c.volume);
+      ctx.fillRect(xForIndex(i) - barWidth / 2, y, barWidth, zeroY - y);
+    }
+  },
+});
+
+chart.setData(candles);
+allData = candles; // keep in sync on every later setData() call too
+```
+
+Setting `volumeAreaHeightRatio: 0` on the style matters — leaving the default `0.2` active
+alongside a dedicated volume pane double-draws the bars (once as the in-pane backdrop, once in
+the new pane). Unlike an indicator pane's `getValueRange`, volume's domain is naturally
+`[0, max]` rather than something auto-fit around a signed value the way MACD's is — the
+example above recomputes `max` from the currently visible candles each frame, the same way
+`computeMacdValueRange` does in the "Multi-pane indicators" example above.
+
 ### Cleanup
 
 Call `chart.destroy()` when you're done with a chart (component unmount, etc.) — it removes a

package/dist/crosshairRenderer.d.ts

@@ -1,4 +1,4 @@
-import type { ChartCrosshairOptions, ChartFontOptions, ChartLegendOptions } from './types.js';
+import type { ChartCrosshairOptions, ChartFontOptions, ChartLegendOptions, LegendLine } from './types.js';
 /** Everything one frame's hover crosshair/legend needs — computed by
  * `ChartRenderer.render()` (which owns the hovered point, the active
  * series, and its style) and handed in as plain data so this class stays
@@ -19,7 +19,7 @@ export interface CrosshairRenderInput {
      * across every indicator pane below it. */
     stackHeight: number;
     invertValueAxis: boolean;
-    legendParts: string[];
+    legendParts: LegendLine[];
     /** The canvas's own backing-store width — needed only to clamp the
      * time-axis label chip so it never runs off the right edge. */
     canvasWidth: number;

package/dist/crosshairRenderer.js

@@ -27,7 +27,8 @@ export class CrosshairRenderer {
         const { ctx, crosshair } = this;
         ctx.save();
         ctx.strokeStyle = crosshair.lineColor;
-        ctx.setLineDash([4, 4]);
+        ctx.lineWidth = crosshair.lineWidth;
+        ctx.setLineDash(crosshair.lineDash);
         // Spans the whole pane stack (not just the main pane's own
         // chartHeight) so hovering a candle lines up with the same column
         // across every indicator pane below it — see `stackHeight`'s own doc
@@ -74,8 +75,12 @@ export class CrosshairRenderer {
         ctx.font = this.legendFont();
         ctx.textAlign = 'left';
         ctx.textBaseline = 'top';
+        // Each line is either a plain string or { text, color } — normalize to
+        // its text once up front for sizing, and read its own color (falling
+        // back to legend.textColor) only when actually drawing it below.
+        const texts = lines.map((line) => (typeof line === 'string' ? line : line.text));
         const lineHeight = font.legendSize + 4;
-        const textWidth = Math.max(...lines.map((line) => ctx.measureText(line).width));
+        const textWidth = Math.max(...texts.map((text) => ctx.measureText(text).width));
         const boxWidth = textWidth + legend.paddingX * 2;
         const boxHeight = lines.length * lineHeight + legend.paddingY * 2;
         const anchorY = hoverY ?? 0;
@@ -83,9 +88,9 @@ export class CrosshairRenderer {
         const top = Math.min(Math.max(anchorY - boxHeight - legend.cursorGap, 0), Math.max(0, chartHeight - boxHeight));
         ctx.fillStyle = legend.background;
         ctx.fillRect(left, top, boxWidth, boxHeight);
-        ctx.fillStyle = legend.textColor;
         lines.forEach((line, i) => {
-            ctx.fillText(line, left + legend.paddingX, top + legend.paddingY + i * lineHeight);
+            ctx.fillStyle = typeof line === 'string' ? legend.textColor : (line.color ?? legend.textColor);
+            ctx.fillText(texts[i], left + legend.paddingX, top + legend.paddingY + i * lineHeight);
         });
     }
     /** The highlighted price-axis label that follows the crosshair's

package/dist/index.d.ts

@@ -2,8 +2,8 @@ import type { DataLoader } from './dataSource.js';
 import type { ChartPlugin } from './plugins/types.js';
 import type { CandlestickStyle } from './series/candlestick.js';
 import type { LineStyle } from './series/line.js';
-import type { Candle, LegendFormatContext, LinePoint, PaneOptions, WickChartOptions, SeriesPoint, ValueRange, WickTime } from './types.js';
-export type { BusinessDay, Candle, LegendFormatContext, LinePoint, PaneOptions, WickChartOptions, WickTime, SeriesPoint, UnixMillis, ValueRange, } from './types.js';
+import type { Candle, LegendFormatContext, LegendLine, LinePoint, PaneOptions, WickChartOptions, SeriesPoint, ValueRange, WickTime } from './types.js';
+export type { BusinessDay, Candle, LegendFormatContext, LegendLine, LinePoint, PaneOptions, WickChartOptions, WickTime, SeriesPoint, UnixMillis, ValueRange, } from './types.js';
 export type { DataLoader, DataRequest } from './dataSource.js';
 export type { ChartPlugin, ChartPointerEvent, PluginRenderApi } from './plugins/types.js';
 export { distanceToSegment, hitTestPoint, hitTestSegment } from './hitTest.js';
@@ -332,7 +332,7 @@ export declare function createCandlestickChart(canvas: HTMLCanvasElement, option
      * `context` narrowed to this series's own types instead of the general
      * (unchecked) `SeriesPoint`/`unknown` shape `WickChartOptions` itself
      * allows — see its doc comment for what this is for. */
-    formatLegend?(point: Candle, style: CandlestickStyle, context: LegendFormatContext<Candle>): string[];
+    formatLegend?(point: Candle, style: CandlestickStyle, context: LegendFormatContext<Candle>): LegendLine[];
 }): WickChart<Candle>;
 /**
  * The second series type's equivalent of `createCandlestickChart` above —
@@ -345,5 +345,5 @@ export declare function createLineChart(canvas: HTMLCanvasElement, options?: Omi
     style?: Partial<LineStyle>;
     /** Same override as `WickChartOptions.formatLegend`, narrowed to this
      * series's own types — see `createCandlestickChart`'s equivalent. */
-    formatLegend?(point: LinePoint, style: LineStyle, context: LegendFormatContext<LinePoint>): string[];
+    formatLegend?(point: LinePoint, style: LineStyle, context: LegendFormatContext<LinePoint>): LegendLine[];
 }): WickChart<LinePoint>;

package/dist/renderer.js

@@ -21,6 +21,8 @@ const DEFAULT_AXIS = {
 };
 const DEFAULT_CROSSHAIR = {
     lineColor: '#9090904d',
+    lineWidth: 1,
+    lineDash: [4, 4],
     labelBackground: '#3a3a3a',
     labelTextColor: '#f0f0f0',
     labelPaddingX: 4,
@@ -128,6 +130,8 @@ export class ChartRenderer {
         };
         const scaledCrosshair = {
             ...this.crosshair,
+            lineWidth: this.crosshair.lineWidth * ratio,
+            lineDash: this.crosshair.lineDash.map((segment) => segment * ratio),
             labelPaddingX: this.crosshair.labelPaddingX * ratio,
             labelPaddingY: this.crosshair.labelPaddingY * ratio,
         };
@@ -230,32 +234,6 @@ export class ChartRenderer {
                 axisRenderer.renderPriceAxis(min, max, step, scale, chartWidth, rect.height, rect.top);
             }
             axisRenderer.renderTimeAxis(times, startIdx, visible.length, stackHeight, chartWidth, xForIndex);
-            if (hoverIndex !== null && hoverIndex >= startIdx && hoverIndex < endIdx) {
-                // The dashed vertical line spans the whole stack (every pane); the
-                // horizontal line, price-label chip, and OHLC legend stay scoped
-                // to the main pane only — an indicator pane's own hover readout,
-                // if it wants one, is the job of whatever plugin draws into it.
-                // `formatLegendOverride`, when set, replaces the series's own
-                // formatLegend entirely for this chart instance rather than
-                // merging with it — see `WickChartOptions.formatLegend`.
-                const formatLegend = this.formatLegendOverride ?? seriesDefinition.formatLegend;
-                const legendContext = { index: hoverIndex, allPoints: sorted };
-                const legendParts = formatLegend?.(sorted[hoverIndex], style, legendContext) ?? [];
-                crosshairRenderer.render({
-                    x: xForIndex(hoverIndex),
-                    timeSeconds: times[hoverIndex],
-                    hoverY,
-                    valueMin,
-                    valueMax,
-                    priceStep,
-                    chartWidth,
-                    chartHeight,
-                    stackHeight,
-                    invertValueAxis: this.invertValueAxis,
-                    legendParts,
-                    canvasWidth: canvas.width,
-                });
-            }
             if (plugins.length > 0) {
                 // Everything every pane's PluginRenderApi shares — only the pane's
                 // own rect/value-domain/scale differ between `buildPluginApi`
@@ -300,6 +278,37 @@ export class ChartRenderer {
                     }
                 }
             }
+            // Drawn last, after every plugin (including paneId'd ones and main-pane
+            // overlays like trade markers) rather than right after the axes, so the
+            // hover legend/crosshair always sits on top of everything else instead
+            // of being covered by a plugin's own output — the crosshair is the most
+            // "active"/topmost thing on the chart at the moment it's shown.
+            if (hoverIndex !== null && hoverIndex >= startIdx && hoverIndex < endIdx) {
+                // The dashed vertical line spans the whole stack (every pane); the
+                // horizontal line, price-label chip, and OHLC legend stay scoped
+                // to the main pane only — an indicator pane's own hover readout,
+                // if it wants one, is the job of whatever plugin draws into it.
+                // `formatLegendOverride`, when set, replaces the series's own
+                // formatLegend entirely for this chart instance rather than
+                // merging with it — see `WickChartOptions.formatLegend`.
+                const formatLegend = this.formatLegendOverride ?? seriesDefinition.formatLegend;
+                const legendContext = { index: hoverIndex, allPoints: sorted };
+                const legendParts = formatLegend?.(sorted[hoverIndex], style, legendContext) ?? [];
+                crosshairRenderer.render({
+                    x: xForIndex(hoverIndex),
+                    timeSeconds: times[hoverIndex],
+                    hoverY,
+                    valueMin,
+                    valueMax,
+                    priceStep,
+                    chartWidth,
+                    chartHeight,
+                    stackHeight,
+                    invertValueAxis: this.invertValueAxis,
+                    legendParts,
+                    canvasWidth: canvas.width,
+                });
+            }
         }
         finally {
             frameState.ended = true;

package/dist/series/candlestick.d.ts

@@ -11,7 +11,12 @@ export interface CandlestickStyle {
     /** Fraction of the chart's full height that volume bars occupy, measured
      * up from the bottom. Candles still use the full height for their own
      * price scale regardless of this value — the bars sit in this bottom
-     * margin, layered underneath. Defaults to 0.2. */
+     * margin, layered underneath (and can visually collide with a candle
+     * whose range dips into that margin). Defaults to 0.2. Set to 0 to
+     * suppress this in-pane backdrop entirely — do this when drawing volume
+     * in its own pane instead via `WickChart.addPane` + a `ChartPlugin`
+     * reading `Candle.volume` off `allPoints` (see "Splitting volume into
+     * its own pane" in the README), so the two don't double-draw. */
     volumeAreaHeightRatio: number;
     /** Opacity (0-1) of the volume bars, so they read as a backdrop rather
      * than competing with the candles drawn over them. Defaults to 0.5. */

package/dist/series/candlestick.js

@@ -18,6 +18,13 @@ function getValueRange(visible, scaleFactor) {
  * OHLC-only data look exactly as they did before this existed. */
 function drawVolumeBars(context, style) {
     const { ctx, visible, startIndex, xForIndex, slotWidth, chartHeight } = context;
+    // A caller drawing volume in its own pane via WickChart.addPane (see
+    // "Splitting volume into its own pane" in the README) sets this to 0 to
+    // fully suppress this in-pane backdrop — without this guard, the
+    // Math.max(1, ...) floor below still drew a 1px sliver per candle even
+    // at ratio 0.
+    if (style.volumeAreaHeightRatio <= 0)
+        return;
     const maxVolume = visible.reduce((max, c) => (c.volume !== undefined ? Math.max(max, c.volume) : max), 0);
     if (maxVolume <= 0)
         return;

package/dist/series/types.d.ts

@@ -1,5 +1,5 @@
 import type { Scale } from '../hybridScale.js';
-import type { LegendFormatContext, SeriesPoint, ValueRange } from '../types.js';
+import type { LegendFormatContext, LegendLine, SeriesPoint, ValueRange } from '../types.js';
 export type { ValueRange } from '../types.js';
 /**
  * Everything a series's `draw` needs to turn its visible points into
@@ -68,5 +68,5 @@ export interface SeriesDefinition<TPoint extends SeriesPoint, TStyle> {
      * previous point — this built-in series doesn't need it, but a custom
      * one can. `WickChartOptions.formatLegend`, when set, overrides this per
      * chart instance rather than per series type — see its own doc comment. */
-    formatLegend?(point: TPoint, style: TStyle, context: LegendFormatContext<TPoint>): string[];
+    formatLegend?(point: TPoint, style: TStyle, context: LegendFormatContext<TPoint>): LegendLine[];
 }

package/dist/types.d.ts

@@ -103,8 +103,16 @@ export interface ChartAxisOptions {
 /** Coloring and padding for the hover crosshair's lines and its two
  * highlighted axis-label chips. */
 export interface ChartCrosshairOptions {
-    /** Dashed crosshair line color. Defaults to `'#9090904d'`. */
+    /** Crosshair line color. Defaults to `'#9090904d'`. */
     lineColor?: string;
+    /** Crosshair line thickness, in CSS px (scaled by `devicePixelRatio`
+     * like every other size field here). Defaults to `1`. */
+    lineWidth?: number;
+    /** `CanvasRenderingContext2D.setLineDash` pattern, in CSS px (scaled by
+     * `devicePixelRatio` like every other size field here). Defaults to
+     * `[4, 4]`. Pass `[]` for a solid line — the same canvas convention
+     * `setLineDash` itself uses, so this needs no separate on/off flag. */
+    lineDash?: number[];
     /** Background fill of the price/time label chips. Defaults to `'#3a3a3a'`. */
     labelBackground?: string;
     /** Text color inside the label chips. Defaults to `'#f0f0f0'`. */
@@ -185,6 +193,18 @@ export interface LegendFormatContext<TPoint extends SeriesPoint = SeriesPoint> {
      * time — the same array `SeriesDrawContext.allPoints` is. */
     allPoints: readonly TPoint[];
 }
+/**
+ * One line of the hover legend — a plain `string` (drawn in the legend's
+ * configured `textColor`, same as every version of this library before
+ * per-line color existed) or `{ text, color }` for a line that needs its
+ * own color independent of the rest — a percent-change line that should
+ * read green/red by sign, say. Mixing both in the same `formatLegend`
+ * return array is fine: each line is colored independently.
+ */
+export type LegendLine = string | {
+    text: string;
+    color?: string;
+};
 export interface WickChartOptions {
     /**
      * Which registered series type to render this chart as (see
@@ -218,7 +238,9 @@ export interface WickChartOptions {
     /**
      * Overrides the active series's own `formatLegend` (see
      * `SeriesDefinition.formatLegend`) for this chart instance specifically —
-     * the hover legend's text, one string per line. `SeriesDefinition.formatLegend`
+     * the hover legend's text, one `LegendLine` per line (a plain string, or
+     * `{ text, color }` for a line that needs its own color — see
+     * `LegendLine`). `SeriesDefinition.formatLegend`
      * is a shared default for every chart of that series *type* (registered
      * once via `registerSeries`); this is a per-*instance* override for
      * whatever varies by app/session instead of by chart type — localized
@@ -238,7 +260,7 @@ export interface WickChartOptions {
      * both to the concrete series's own types, the same way they narrow
      * `style` — see their own doc comments.
      */
-    formatLegend?(point: SeriesPoint, style: unknown, context: LegendFormatContext<SeriesPoint>): string[];
+    formatLegend?(point: SeriesPoint, style: unknown, context: LegendFormatContext<SeriesPoint>): LegendLine[];
     /**
      * Mirrors the value axis top-to-bottom — every pane's higher values
      * render lower on screen instead of higher, with no change to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wick-charts",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "description": "An open-source financial charting library — WASM (Rust) for compute, Canvas2D for rendering.",
   "license": "MIT",
   "author": "eatnows",