gloomberb 0.18.4 → 0.19.0

package/src/components/chart/composite/legend.tsx

@@ -13,7 +13,7 @@ import {
   seriesPriceReference,
 } from "./format";
 import type { CompositeChartProps, CompositeChartScene } from "./types";
-import { seriesCueCssBackground, type SeriesLineCue } from "./series-cues";
+import { DIRECTION_MARKER, seriesColorsDirection, seriesCueCssBackground, type SeriesLineCue } from "./series-cues";
 import { DisclosureMarker } from "../../ui/disclosure-marker";
 
 const LEGEND_WHEEL_DELTA_PER_CELL = 8;
@@ -120,12 +120,35 @@ function packLegendLines(widths: readonly number[], available: number, maxLines
   return lines;
 }
 
-/** The legend's marker for a series on the desktop: its line as the plot strokes it, or a dot. */
-function CompositeSeriesSwatch({ series, cue, filled = true }: {
+/** A triangle pointing up or down, as the desktop legend keys a bar's direction. */
+const DIRECTION_TRIANGLES = {
+  up: "polygon(50% 0, 100% 100%, 0 100%)",
+  down: "polygon(0 0, 100% 0, 50% 100%)",
+} as const;
+
+/** The legend's marker for a series on the desktop: its line as the plot strokes it, its up and down colors, or a dot. */
+function CompositeSeriesSwatch({ series, cue, downColor = null, filled = true }: {
   series: ResolvedSeries;
   cue: SeriesLineCue | null;
+  /** The down color, for a series keyed by direction: an up triangle in its color, then a down one in this. */
+  downColor?: string | null;
   filled?: boolean;
 }) {
+  if (downColor) {
+    return (
+      <Box
+        flexShrink={0}
+        flexDirection="row"
+        style={{ gap: 2, marginInlineEnd: 6, opacity: filled ? 1 : 0.35 }}
+        data-gloom-role="composite-chart-legend-marker"
+        data-gloom-cue="direction"
+      >
+        {([["up", series.color], ["down", downColor]] as const).map(([direction, color]) => (
+          <Box key={direction} flexShrink={0} style={{ width: 7, height: 7, backgroundColor: color, clipPath: DIRECTION_TRIANGLES[direction] }} />
+        ))}
+      </Box>
+    );
+  }
   return cue ? (
     // The line as the plot strokes it: solid, dashed, dotted or heavy.
     <Box
@@ -162,6 +185,7 @@ export function CompositeLegend({
   visibleSeriesIds,
   lineCues = NO_LINE_CUES,
   cellPlot = false,
+  directionDownColor = null,
   width,
   accessory,
   accessoryWidth,
@@ -183,6 +207,12 @@ export function CompositeLegend({
   lineCues?: ReadonlyMap<string, SeriesLineCue>;
   /** The plot is cell text, so a line's cue is its mark rather than its dash. */
   cellPlot?: boolean;
+  /**
+   * The color bars that closed down are drawn in, where the theme's up and
+   * down are not the familiar green and red: a candle series' marker then keys
+   * both (`▲▼`). Null keeps its dot.
+   */
+  directionDownColor?: string | null;
   width: number;
   accessory: CompositeChartProps["legendAccessory"];
   accessoryWidth: CompositeChartProps["legendAccessoryWidth"];
@@ -212,8 +242,9 @@ export function CompositeLegend({
   const valueDates = legendValueDates(series, scene, cursorValueById);
   const buildEntries = (withFiscalPeriods: boolean) => series.map((entry) => {
     const cue = lineCues.get(entry.id) ?? null;
-    const marker = cue ? `${cellPlot ? cue.glyph : cue.sample} ` : DOT_MARKER;
-    const markerWidth = isDesktopWeb ? cue ? DOM_LINE_CELLS : DOM_DOT_CELLS : displayWidth(marker);
+    const downColor = !cue && directionDownColor && seriesColorsDirection(entry) ? directionDownColor : null;
+    const marker = cue ? `${cellPlot ? cue.glyph : cue.sample} ` : downColor ? DIRECTION_MARKER.text : DOT_MARKER;
+    const markerWidth = isDesktopWeb ? cue || downColor ? DOM_LINE_CELLS : DOM_DOT_CELLS : displayWidth(marker);
     const toggleable = !!onToggleSeries && (isSeriesToggleable?.(entry) ?? true);
     const cursorValue = cursorValueById.get(entry.id);
     // A stacked layer reads its own amount, not the top of the stack it is drawn to.
@@ -253,6 +284,7 @@ export function CompositeLegend({
     return {
       entry,
       cue,
+      downColor,
       marker,
       markerWidth,
       label,
@@ -414,7 +446,7 @@ export function CompositeLegend({
     scrollBox.scrollTo({ x: nextLeft, y: scrollBox.scrollTop });
   };
   const renderEntry = (
-    { entry, cue, marker, text, statedUnit, valueTail, toggleable, tooltip, carried, width: entryWidth }: LegendEntry,
+    { entry, cue, downColor, marker, text, statedUnit, valueTail, toggleable, tooltip, carried, width: entryWidth }: LegendEntry,
     index: number,
   ) => {
     const entryVisible = visibleSeriesIds.has(entry.id);
@@ -446,7 +478,13 @@ export function CompositeLegend({
         title={isDesktopWeb ? tooltip : undefined}
       >
         {isDesktopWeb ? (
-          <CompositeSeriesSwatch series={entry} cue={cue} filled={entryVisible} />
+          <CompositeSeriesSwatch series={entry} cue={cue} downColor={downColor} filled={entryVisible} />
+        ) : downColor && entryVisible ? (
+          <Text>
+            <Span fg={entry.color}>{DIRECTION_MARKER.up}</Span>
+            <Span fg={downColor}>{DIRECTION_MARKER.down}</Span>
+            {" "}
+          </Text>
         ) : (
           <Text fg={entryVisible ? entry.color : themeColors.textMuted}>{marker}</Text>
         )}

package/src/components/chart/composite/levels.ts

@@ -23,6 +23,8 @@ export interface CompositeChartLevel {
   label?: string;
   /** Exact instrument price, independent of the grid's compact tick formatter. */
   axisLabel?: string;
+  /** A named reference guide keeps its axis label ahead of ordinary grid ticks. */
+  prioritizeAxisLabel?: boolean;
   dashed?: boolean;
 }
 

package/src/components/chart/composite/panel-gestures.ts

@@ -64,6 +64,39 @@ export function startPanGesture(
   };
 }
 
+/** Where the pointer was during a pan, for the speed it lets go at. */
+export interface PanSample {
+  at: number;
+  x: number;
+}
+
+/** Only the last moments of a drag count: a pointer that stopped before letting go throws nothing. */
+const PAN_RELEASE_WINDOW_MS = 100;
+/** How long a throw takes to lose about two thirds of its speed. */
+export const PAN_COAST_DECAY_MS = 325;
+/**
+ * Plot widths per second a release must reach to coast, and below which a
+ * coast stops. Only a flick coasts: a drag placing a bar under the pointer
+ * moves at about one plot width a second and must leave it there.
+ */
+export const PAN_COAST_START_SPEED = 2.5;
+export const PAN_COAST_STOP_SPEED = 0.02;
+
+/** Cells per millisecond the pointer moved over its last samples, 0 when it had come to rest. */
+export function panReleaseVelocity(samples: readonly PanSample[], now: number): number {
+  const recent = samples.filter((sample) => now - sample.at <= PAN_RELEASE_WINDOW_MS);
+  const first = recent[0];
+  const last = recent.at(-1);
+  if (!first || !last || last.at <= first.at) return 0;
+  return (last.x - first.x) / (last.at - first.at);
+}
+
+/** One frame of a coast: the cells it moves (the decaying speed integrated over the frame) and the speed left. */
+export function panCoastStep(velocity: number, elapsedMs: number): { cells: number; velocity: number } {
+  const decay = Math.exp(-Math.max(0, elapsedMs) / PAN_COAST_DECAY_MS);
+  return { cells: velocity * PAN_COAST_DECAY_MS * (1 - decay), velocity: velocity * decay };
+}
+
 export interface PendingWheel {
   /** Fraction of the visible span, positive toward older observations. */
   panRatio: number;

package/src/components/chart/composite/panel-series.ts

@@ -30,6 +30,7 @@ function sameSeriesMeta(left: ResolvedSeries, right: ResolvedSeries): boolean {
     && left.unitGroup === right.unitGroup
     && left.statedUnit === right.statedUnit
     && left.priceAssetCategory === right.priceAssetCategory
+    && left.valueDecimals === right.valueDecimals
     && left.nativeFrequency === right.nativeFrequency
     && left.timestampMode === right.timestampMode
     && left.dataShape === right.dataShape

package/src/components/chart/composite/panel-surface.tsx

@@ -69,9 +69,14 @@ import {
   COMPOSITE_PANEL_ROLE,
   isVerticalWheelDirection,
   manualValueAxes,
+  PAN_COAST_START_SPEED,
+  PAN_COAST_STOP_SPEED,
+  panCoastStep,
+  panReleaseVelocity,
   startPanGesture,
   releaseEditableFocus,
   type PanGesture,
+  type PanSample,
   type PendingAxisWheel,
   type PendingWheel,
   type ValueAxisStart,
@@ -542,6 +547,7 @@ export function CompositePanelSurface({
       yRatio,
       label: level.axisLabel ?? (formatAxisValue ? formatAxisValue(level.value, levelDomain) : formatCompositeCursorValue(level.value, levelDomain)),
       color: level.color,
+      prioritizeAxisLabel: level.prioritizeAxisLabel,
     })) : [], [formatAxisValue, levelDomain, projectedLevels, selectedLevelId]);
   const buildAxisMarkers = (side: "left" | "right") => {
     if (!panel.axes[side]) return undefined;
@@ -557,7 +563,8 @@ export function CompositePanelSurface({
     );
     const fixed = [lastPriceMarker, axisMarkers].filter(onSide).map(toAxisMarker);
     // The prior close's label yields to every level's.
-    const levelLabels = [...levelMarkers, priorCloseMarker].filter(onSide).map(toAxisMarker);
+    const referenceLabels = levelMarkers.filter((marker) => marker.prioritizeAxisLabel && onSide(marker)).map(toAxisMarker);
+    const levelLabels = [...levelMarkers.filter((marker) => !marker.prioritizeAxisLabel), priorCloseMarker].filter(onSide).map(toAxisMarker);
     // A label is a row tall, so close levels would stack into an unreadable
     // pile and hide the last price: each keeps its line, and only the labels
     // with a row to themselves show. Desktop badges sit between rows.
@@ -567,8 +574,13 @@ export function CompositePanelSurface({
         pixelY: tick.topPercent / 100 * Math.max(panel.height * cellHeightPx - 1, 1),
       }))
       : [...(side === "left" ? leftAxisLabels : rightAxisLabels)].map(([row, label]) => ({ id: undefined, row, pixelY: row * cellHeightPx, label, color: colors.textDim }));
+    const rowOf = (marker: ReturnType<typeof toAxisMarker>) => fractionalViewport ? marker.pixelY / cellHeightPx : marker.row;
+    // Named guides are part of the chart's readout: ordinary ticks yield to
+    // them, while a live price or cursor still keeps its place.
+    const references = fitAxisLabels(referenceLabels, fixed, rowOf);
     const markers = [
-      ...fitAxisLabels(levelLabels, [...fixed, ...grid], (marker) => fractionalViewport ? marker.pixelY / cellHeightPx : marker.row),
+      ...references,
+      ...fitAxisLabels(levelLabels, [...references, ...fixed, ...grid], rowOf),
       ...fixed,
     ];
     return markers.length > 0 ? markers : undefined;
@@ -726,6 +738,7 @@ export function CompositePanelSurface({
     }
     if (!updateCursor(event)) return;
     const values = manualValueAxes(panel);
+    panSamplesRef.current = [{ at: performance.now(), x: getGlobalMouseX(event, renderer) }];
     dragRef.current = {
       ...startPanGesture(
         frame,
@@ -808,6 +821,8 @@ export function CompositePanelSurface({
       return;
     }
     const globalX = getGlobalMouseX(event, renderer);
+    panSamplesRef.current.push({ at: performance.now(), x: globalX });
+    if (panSamplesRef.current.length > 12) panSamplesRef.current.shift();
     if (drag.frame !== frame) {
       // Data refreshed mid-drag. The new frame maps positions differently, so
       // continue from where the plot is now instead of replaying the drag.
@@ -840,6 +855,43 @@ export function CompositePanelSurface({
     updateCursor,
     viewport,
   ]);
+  // A pan let go while still moving keeps going and slows down, on the
+  // desktop and web only: in a terminal every frame would upload the plot again.
+  const panSamplesRef = useRef<PanSample[]>([]);
+  const coastFrameRef = useRef<number | null>(null);
+  const coastPanRef = useRef(onPanViewport);
+  coastPanRef.current = onPanViewport;
+  const stopCoast = useCallback(() => {
+    if (coastFrameRef.current === null) return;
+    webFrame.cancelAnimationFrame?.(coastFrameRef.current);
+    coastFrameRef.current = null;
+    globalThis.removeEventListener?.("pointerdown", stopCoast, true);
+    globalThis.removeEventListener?.("keydown", stopCoast, true);
+  }, []);
+  const startCoast = useCallback((velocity: number, positionsPerCell: number) => {
+    stopCoast();
+    const requestFrame = webFrame.requestAnimationFrame;
+    const widthCells = Math.max(plotSize.width, 1);
+    const plotWidthsPerSecond = (speed: number) => Math.abs(speed) * 1000 / widthCells;
+    if (!isDesktopWeb || !requestFrame || plotWidthsPerSecond(velocity) < PAN_COAST_START_SPEED) return;
+    if (globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return;
+    let speed = velocity;
+    let last = performance.now();
+    const step = () => {
+      const now = performance.now();
+      const next = panCoastStep(speed, now - last);
+      last = now;
+      speed = next.velocity;
+      coastPanRef.current(next.cells * positionsPerCell);
+      if (plotWidthsPerSecond(speed) < PAN_COAST_STOP_SPEED) stopCoast();
+      else coastFrameRef.current = requestFrame(step);
+    };
+    coastFrameRef.current = requestFrame(step);
+    // Any press or key anywhere, a range button or a reset, takes the view back from the coast.
+    globalThis.addEventListener?.("pointerdown", stopCoast, true);
+    globalThis.addEventListener?.("keydown", stopCoast, true);
+  }, [isDesktopWeb, plotSize.width, stopCoast]);
+  useEffect(() => stopCoast, [stopCoast]);
   const finishToolDrag = useCallback(() => {
     const drag = dragRef.current;
     if (!drag || drag.kind === "pan") return;
@@ -862,12 +914,14 @@ export function CompositePanelSurface({
     if (range) onSetViewport(range);
   }, [drawColor, frame.minimumSpanMs, levels, onDraw, onSetViewport, panel, scene]);
   const resetDrag = useCallback(() => {
-    if (dragRef.current?.kind === "pan") {
+    const drag = dragRef.current;
+    if (drag?.kind === "pan") {
       dragRef.current = null;
+      startCoast(panReleaseVelocity(panSamplesRef.current, performance.now()), drag.positionsPerCell);
       return;
     }
     finishToolDrag();
-  }, [finishToolDrag]);
+  }, [finishToolDrag, startCoast]);
   // Said once per change, so a pointer move costs the chart nothing.
   const reportedDragRef = useRef(false);
   const reportDrag = useCallback((dragging: boolean) => {
@@ -876,10 +930,11 @@ export function CompositePanelSurface({
     onDragActiveChange?.(dragging);
   }, [onDragActiveChange]);
   const pressPlot = useCallback((event: ChartMouseEvent) => {
+    stopCoast();
     const before = dragRef.current;
     startDrag(event);
     if (dragRef.current !== null && dragRef.current !== before) reportDrag(true);
-  }, [reportDrag, startDrag]);
+  }, [reportDrag, startDrag, stopCoast]);
   const releasePlot = useCallback(() => {
     resetDrag();
     reportDrag(false);
@@ -922,6 +977,7 @@ export function CompositePanelSurface({
   const panFromWheel = useCallback((event: ChartMouseEvent) => {
     const scroll = event.scroll;
     if (!scroll) return;
+    stopCoast();
     onActivate?.();
     consumeChartMouseEvent(event);
     const pointer = plotPointer(event);

package/src/components/chart/composite/range-statistics.ts

@@ -0,0 +1,62 @@
+import type { ResolvedSeries, TimeSeriesPoint } from "../../../time-series/types";
+import { formatCompositeSeriesValue } from "./format";
+import type { CompositeViewportRange } from "./interactions";
+import type { CompositeChartLevel, CompositeChartLevels } from "./levels";
+
+/** Population statistics of the finite observations actually in the window. */
+export function compositeRangeStatistics(points: readonly TimeSeriesPoint[], viewport: CompositeViewportRange) {
+  const start = viewport.start.getTime();
+  const end = viewport.end.getTime();
+  if (!Number.isFinite(start) || !Number.isFinite(end) || start > end) return null;
+  let count = 0;
+  let mean = 0;
+  let squaredDeviations = 0;
+  for (const point of points) {
+    const time = point.date.getTime();
+    const value = Number.isFinite(point.value) ? point.value : point.close;
+    if (!Number.isFinite(time) || time < start || time > end
+      || typeof value !== "number" || !Number.isFinite(value)) continue;
+    count += 1;
+    // Welford's update avoids subtracting nearly equal squared sums when
+    // valuations are tightly clustered around a large level.
+    const delta = value - mean;
+    mean += delta / count;
+    squaredDeviations += delta * (value - mean);
+  }
+  if (!count || !Number.isFinite(mean) || !Number.isFinite(squaredDeviations)) return null;
+  return { count, mean, standardDeviation: Math.sqrt(Math.max(0, squaredDeviations / count)) };
+}
+
+/** Read-only levels share the chart's axis labels, vector, Kitty and text paths. */
+export function compositeRangeStatisticsLevels(
+  series: ResolvedSeries | undefined,
+  viewport: CompositeViewportRange | null,
+  color: string,
+  formatValue: (value: number, series: ResolvedSeries) => string = formatCompositeSeriesValue,
+): CompositeChartLevels | null {
+  if (!series || series.hidden || !viewport) return null;
+  const statistics = compositeRangeStatistics(series.points, viewport);
+  if (!statistics || statistics.count < 20) return null;
+  const { mean, standardDeviation } = statistics;
+  const guides = [
+    { id: "mean", label: "Avg", value: mean, dashed: false },
+    { id: "upper", label: "+1σ", value: mean + standardDeviation, dashed: true },
+    { id: "lower", label: "−1σ", value: mean - standardDeviation, dashed: true },
+  ];
+  const items: CompositeChartLevel[] = [];
+  for (const guide of guides) {
+    // A constant window (including one observation) has only its mean.
+    if (!Number.isFinite(guide.value) || items.some((item) => item.value === guide.value)) continue;
+    items.push({
+      id: `range-statistics:${series.id}:${guide.id}`,
+      value: guide.value,
+      color,
+      dashed: guide.dashed,
+      axisLabel: `${guide.label} ${formatValue(guide.value, series)}`,
+      prioritizeAxisLabel: true,
+      editable: false,
+      actionable: false,
+    });
+  }
+  return { seriesId: series.id, items };
+}

package/src/components/chart/composite/rasterizer.ts

@@ -436,13 +436,14 @@ function drawColumns(
   domain: CompositeAxisDomain,
   color: RgbaColor,
   negativeColor: RgbaColor,
+  fallColor: RgbaColor,
   layout: CompositeColumnLayout,
   widthByFamily: ReadonlyMap<string, number>,
   opacity: number,
 ): void {
   const baseline = pixelY(0, domain, height) ?? height - 1;
   for (const projected of series.points) {
-    const fill = projected.value < 0 ? negativeColor : color;
+    const fill = projected.value < 0 ? negativeColor : projected.point.fell ? fallColor : color;
     const point = pixelPoint(projected, width, height, domain.manual);
     const geometry = columnPixelGeometry(projected, width, layout, widthByFamily);
     fillRect(
@@ -487,20 +488,27 @@ function drawOhlc(
     const closeY = pixelY(close, domain, height);
     if (highY === null || lowY === null || closeY === null) continue;
     const candleColor = close >= open ? color : negative;
-    drawLine(data, width, height, x, highY, x, lowY, candleColor, 1.1);
-    if (series.source.style === "candles" && openY !== null) {
-      fillRect(
-        data,
-        width,
-        height,
-        x - candleWidth / 2,
-        Math.min(openY, closeY),
-        x + candleWidth / 2,
-        Math.max(openY, closeY) + 1,
-        candleColor,
-      );
+    const style = series.source.style;
+    if (style !== "ohlc" && style !== "hlc" && openY !== null) {
+      const left = x - candleWidth / 2;
+      const right = x + candleWidth / 2;
+      const top = Math.min(openY, closeY);
+      const bottom = Math.max(openY, closeY) + 1;
+      // A hollow rising candle is an outline the wick stops at, as on other terminals.
+      if (style === "hollow" && close >= open) {
+        drawLine(data, width, height, x, highY, x, top, candleColor, 1.1);
+        drawLine(data, width, height, x, bottom, x, lowY, candleColor, 1.1);
+        drawLine(data, width, height, left, top, right, top, candleColor, 1.1);
+        drawLine(data, width, height, left, bottom, right, bottom, candleColor, 1.1);
+        drawLine(data, width, height, left, top, left, bottom, candleColor, 1.1);
+        drawLine(data, width, height, right, top, right, bottom, candleColor, 1.1);
+        continue;
+      }
+      drawLine(data, width, height, x, highY, x, lowY, candleColor, 1.1);
+      fillRect(data, width, height, left, top, right, bottom, candleColor);
       continue;
     }
+    drawLine(data, width, height, x, highY, x, lowY, candleColor, 1.1);
     if (series.source.style === "ohlc" && openY !== null) {
       drawLine(data, width, height, x - candleWidth / 2, openY, x, openY, candleColor, 1.2);
     }
@@ -585,6 +593,7 @@ export function renderCompositePanelBitmap(
           domain,
           color,
           negativeColor,
+          negative,
           columnLayout,
           columnWidthByFamily,
           mixesColumnsWithOtherMarks ? 0.48 : 0.72,
@@ -615,6 +624,8 @@ export function renderCompositePanelBitmap(
         break;
       }
       case "candles":
+      case "hollow":
+      case "heikin-ashi":
       case "ohlc":
       case "hlc":
         drawOhlc(data, width, height, series, domain, color, negative);

package/src/components/chart/composite/scene.ts

@@ -4,7 +4,7 @@ import type {
   ResolvedSeries,
   TimeSeriesPoint,
 } from "../../../time-series/types";
-import { effectiveTimeSeriesPointTime, timeSeriesObservationKey } from "../../../time-series/alignment";
+import { effectiveTimeSeriesPointTime, sortedUniquePoints, timeSeriesObservationKey } from "../../../time-series/alignment";
 import type {
   BuildCompositeChartSceneOptions,
   CompositeAxisDomain,
@@ -36,6 +36,37 @@ function resolveTimeSeriesPointValue(point: TimeSeriesPoint): number | null {
   return null;
 }
 
+/**
+ * Heikin Ashi bars in place of a series' own: each close averages the bar's
+ * four prices and each open sits halfway along the previous Heikin Ashi body,
+ * so the chain runs from the first loaded bar, before any viewport cut. The
+ * real close stays in `rawValue` for the last price marker.
+ */
+export function heikinAshiPoints(points: readonly TimeSeriesPoint[]): TimeSeriesPoint[] {
+  let previous: { open: number; close: number } | null = null;
+  // Chain over the bars the chart draws: one per observation, in time order,
+  // so a superseded copy of a bar never feeds the next open.
+  return sortedUniquePoints(points).map((point) => {
+    const close = point.close ?? point.value;
+    if (!isFiniteNumber(close)) return point;
+    const open = isFiniteNumber(point.open) ? point.open : close;
+    const high = isFiniteNumber(point.high) ? point.high : Math.max(open, close);
+    const low = isFiniteNumber(point.low) ? point.low : Math.min(open, close);
+    const haClose = (open + high + low + close) / 4;
+    const haOpen = previous ? (previous.open + previous.close) / 2 : (open + close) / 2;
+    previous = { open: haOpen, close: haClose };
+    return {
+      ...point,
+      value: haClose,
+      rawValue: close,
+      open: haOpen,
+      high: Math.max(high, haOpen, haClose),
+      low: Math.min(low, haOpen, haClose),
+      close: haClose,
+    };
+  });
+}
+
 function pointTime(point: TimeSeriesPoint): number | null {
   const time = point.date instanceof Date ? point.date.getTime() : new Date(point.date).getTime();
   return Number.isFinite(time) ? time : null;
@@ -330,11 +361,15 @@ function buildAxisDomain(
   scale: PanelScale,
   rows: number,
   manualScale?: CompositeManualValueScale,
+  referenceLevels?: BuildCompositeChartSceneOptions["referenceLevels"],
 ): CompositeAxisDomain | undefined {
   const axisSeries = series.filter((entry) => entry.axis === side);
   if (axisSeries.length === 0) return undefined;
   const values = axisSeries.flatMap(seriesDomainValues);
-  const fitted = paddedDomain([...values, ...priorCloseInReach(axisSeries, values)], scale);
+  const references = referenceLevels && axisSeries.some((entry) => entry.id === referenceLevels.seriesId)
+    ? referenceLevels.items.map((level) => level.value).filter(Number.isFinite)
+    : [];
+  const fitted = paddedDomain([...values, ...priorCloseInReach(axisSeries, values), ...references], scale);
   const scaleKey = valueScaleKey(scale, axisSeries);
   // A range set by hand holds while the axis plots the same series and some
   // of their data is in it; otherwise the axis fits the data again.
@@ -498,9 +533,11 @@ function primaryPriceSeries(series: readonly ResolvedSeries[]): ResolvedSeries |
   )) ?? null;
 }
 
-function lastCloseOf(points: readonly CompositeProjectedPoint[]): number | null {
+function lastCloseOf(points: readonly CompositeProjectedPoint[], heikinAshi = false): number | null {
   const last = points.at(-1);
   if (!last) return null;
+  // A Heikin Ashi close is an average; the marker names the price that traded.
+  if (heikinAshi && isFiniteNumber(last.point.rawValue)) return last.point.rawValue;
   return isFiniteNumber(last.point.close) ? last.point.close : last.value;
 }
 
@@ -518,7 +555,7 @@ function attachLastPriceMarker(
   // A rejected or missing latest bar cannot make an older close current.
   const latest = normalizedSourcePoints(primary).at(-1);
   if (latest?.point.provenance?.priceHistoryIntegrity || latest?.value === null) return;
-  const value = lastCloseOf(projected.points);
+  const value = lastCloseOf(projected.points, primary.style === "heikin-ashi");
   if (value === null) return;
   const yRatio = projectCompositeValue(value, domain);
   // An axis scaled by hand can leave the last close off the panel.
@@ -760,7 +797,9 @@ export function buildCompositeChartScene(
   panels: ChartPanelSpec[],
   options: BuildCompositeChartSceneOptions,
 ): CompositeChartScene | null {
-  const dataSeries = series.filter((entry) => normalizedPoints(entry).length > 0);
+  const dataSeries = series
+    .map((entry) => entry.style === "heikin-ashi" ? { ...entry, points: heikinAshiPoints(entry.points) } : entry)
+    .filter((entry) => normalizedPoints(entry).length > 0);
   if (dataSeries.length === 0) return null;
 
   // A known missing observation owns a date even though it has no drawable
@@ -849,8 +888,8 @@ export function buildCompositeChartScene(
       ? dataSeries.filter((entry) => entry.panelId === panel.id)
       : panelSeries;
     const rows = panelHeights.get(panel.id) ?? 1;
-    const left = buildAxisDomain("left", domainSeries, scale, rows, options.valueScales?.[valueScaleSlot(panel.id, "left")]);
-    const right = buildAxisDomain("right", domainSeries, scale, rows, options.valueScales?.[valueScaleSlot(panel.id, "right")]);
+    const left = buildAxisDomain("left", domainSeries, scale, rows, options.valueScales?.[valueScaleSlot(panel.id, "left")], options.referenceLevels);
+    const right = buildAxisDomain("right", domainSeries, scale, rows, options.valueScales?.[valueScaleSlot(panel.id, "right")], options.referenceLevels);
     const axes: Partial<Record<CompositeAxisSide, CompositeAxisDomain>> = { left, right };
     return {
       id: panel.id,

package/src/components/chart/composite/series-axis-tags.tsx

@@ -7,20 +7,23 @@ import type { SeriesAxisTag } from "./panel-labels";
  * ties. A forward pass separates neighbours; a backward pass fits the bottom
  * edge. Panels shorter than the readout use parallel lanes, not dropped tags
  * or smaller type. The gutter reserves those lanes before the cursor moves.
+ * Only a tag pushed off its value's height gets a leader: a tick beside a tag
+ * still on its value reads as a minus sign (`-8k` for a positive 8k).
  */
 export function placeSeriesAxisTags(tags: readonly SeriesAxisTag[], pixelHeight: number, labelHeight: number) {
   const height = Math.max(pixelHeight, labelHeight);
   const capacity = Math.max(1, Math.floor(height / labelHeight));
   const sorted = tags.map((tag, order) => ({ ...tag, order, anchorY: clamp(tag.yRatio, 0, 1) * Math.max(pixelHeight - 1, 0) }))
     .sort((a, b) => a.anchorY - b.anchorY || a.order - b.order);
-  const placed: Array<SeriesAxisTag & { anchorY: number; centerY: number; lane: number }> = [];
+  const placed: Array<SeriesAxisTag & { anchorY: number; centerY: number; lane: number; leader: boolean }> = [];
   for (let start = 0; start < sorted.length; start += capacity) {
     const lane = sorted.slice(start, start + capacity);
     const centers = lane.map((tag) => clamp(tag.anchorY, labelHeight / 2, height - labelHeight / 2));
     for (let i = 1; i < centers.length; i++) centers[i] = Math.max(centers[i]!, centers[i - 1]! + labelHeight);
     if (centers.length) centers[centers.length - 1] = Math.min(centers.at(-1)!, height - labelHeight / 2);
     for (let i = centers.length - 2; i >= 0; i--) centers[i] = Math.min(centers[i]!, centers[i + 1]! - labelHeight);
-    lane.forEach((tag, index) => placed.push({ ...tag, centerY: centers[index]!, lane: Math.floor(start / capacity) }));
+    lane.forEach((tag, index) => placed.push({ ...tag, centerY: centers[index]!, lane: Math.floor(start / capacity),
+      leader: Math.abs(centers[index]! - tag.anchorY) > labelHeight / 2 }));
   }
   return placed;
 }
@@ -37,13 +40,14 @@ export function SeriesAxisTags({ placed, pixelHeight, lanes, background }: {
     const edge = left ? "right" : "left";
     const inset = `${tag.lane * 100 / lanes}%`;
     return <Box key={tag.seriesId} style={{ position: "absolute", inset: 0, pointerEvents: "none" }}>
-      {/* The tick stays at the observation, even when the badge must move. */}
+      {/* The anchor stays at the observation; it draws a tick when the badge had to move off it. */}
       <Box
         data-gloom-role="chart-series-axis-anchor"
         data-series-id={tag.seriesId}
-        style={{ position: "absolute", [edge]: 0, top: percent(tag.anchorY), width: `calc(${inset} + .5em)`, height: 0, borderTop: `1px ${tag.carried ? "dashed" : "solid"} ${tag.color}` }}
+        data-leader={tag.leader ? "true" : undefined}
+        style={{ position: "absolute", [edge]: 0, top: percent(tag.anchorY), width: `calc(${inset} + .5em)`, height: 0, borderTop: tag.leader ? `1px ${tag.carried ? "dashed" : "solid"} ${tag.color}` : undefined }}
       />
-      <Box style={{ position: "absolute", [edge]: `calc(${inset} + .25em)`, top: percent(Math.min(tag.anchorY, tag.centerY)), height: percent(Math.abs(tag.centerY - tag.anchorY)), width: 0, borderLeft: `1px solid ${tag.color}` }} />
+      {tag.leader ? <Box style={{ position: "absolute", [edge]: `calc(${inset} + .25em)`, top: percent(Math.min(tag.anchorY, tag.centerY)), height: percent(Math.abs(tag.centerY - tag.anchorY)), width: 0, borderLeft: `1px solid ${tag.color}` }} /> : null}
       <Box
         data-gloom-role="chart-series-axis-tag"
         data-series-id={tag.seriesId}
@@ -52,12 +56,15 @@ export function SeriesAxisTags({ placed, pixelHeight, lanes, background }: {
         data-carried={tag.carried ? "true" : undefined}
         aria-label={`${tag.seriesLabel}: ${tag.label}${tag.carried ? " (carried)" : ""}`}
         style={{
-          position: "absolute", [edge]: `calc(${inset} + .5em)`, top: percent(tag.centerY), transform: "translateY(-50%)",
-          width: `calc(${100 / lanes}% - .5em)`, height: "1.5em", lineHeight: "1.5em",
-          alignItems: left ? "flex-end" : "flex-start", justifyContent: "center",
+          position: "absolute", [edge]: inset, top: percent(tag.centerY), transform: "translateY(-50%)",
+          // The value sits in a box in its series colour, as a chart level's label does, so nothing
+          // beside it can read as the value's sign. A box wider than its lane is clipped, not wrapped.
+          width: "max-content", maxWidth: `calc(${100 / lanes}% - ${lanes > 1 ? ".25em" : "0px"})`,
+          boxSizing: "border-box", height: "1.5em", lineHeight: "1.5em", paddingInline: ".15em",
+          alignItems: left ? "flex-end" : "flex-start", justifyContent: "center", overflow: "hidden",
           // Every badge paints above every leader, including another lane's.
           zIndex: 2, color: tag.color, backgroundColor: background, whiteSpace: "nowrap",
-          borderBlockEnd: tag.carried ? `1px dashed ${tag.color}` : undefined,
+          border: `1px ${tag.carried ? "dashed" : "solid"} ${tag.color}`,
         }}
       >
         <Text fg={tag.color} selectable={false}>{tag.label}</Text>

package/src/components/chart/composite/series-cues.ts

@@ -69,3 +69,17 @@ export function seriesCueCssBackground(cue: SeriesLineCue, color: string): strin
   });
   return `repeating-linear-gradient(to right, ${stops.join(", ")})`;
 }
+
+/** The OHLC family: one series drawn in the up color for a bar that closed up and the down color for one that closed down. */
+const DIRECTION_STYLES = new Set<SeriesStyle>(["candles", "ohlc", "hlc"]);
+
+/**
+ * Whether a series colors each bar by its direction, so its legend entry can
+ * key the two colors (`▲▼`) where the theme's are not the familiar green and red.
+ */
+export function seriesColorsDirection(series: Pick<ResolvedSeries, "style">): boolean {
+  return DIRECTION_STYLES.has(series.style);
+}
+
+/** The legend marker that keys up and down: the up color's triangle, then the down color's. */
+export const DIRECTION_MARKER = { up: "▲", down: "▼", text: "▲▼ " } as const;