@wick-charts/react 0.2.2 → 0.3.0

package/src/ui/Tooltip.tsx

@@ -0,0 +1,325 @@
+import { type ReactNode, useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+import {
+  type ChartTheme,
+  type OHLCData,
+  type SeriesSnapshot,
+  type TimePoint,
+  type TooltipFormatter,
+  buildHoverSnapshots,
+  computeTooltipPosition,
+  formatCompact,
+  formatDate,
+  formatPriceAdaptive,
+  formatTime,
+  resolveCandlestickBodyColor,
+} from '@wick-charts/core';
+
+export { computeTooltipPosition } from '@wick-charts/core';
+
+import { useChartInstance } from '../context';
+import { useCrosshairPosition } from '../store-bridge';
+
+/** Sort order for multi-series tooltip values. */
+export type TooltipSort = 'none' | 'asc' | 'desc';
+
+/** Context passed to the {@link Tooltip} render-prop. */
+export interface TooltipRenderContext {
+  readonly snapshots: readonly SeriesSnapshot[];
+  /** Crosshair timestamp — the tooltip is hover-only, so this is always a real hover time. */
+  readonly time: number;
+}
+
+/**
+ * Props for the {@link Tooltip} component.
+ * Renders the built-in floating glass panel by default. Pass a render-prop
+ * child to replace its *contents* — the positioned container (with flip/clamp)
+ * stays.
+ */
+export interface TooltipProps {
+  /** Sort order for line values (default: 'none'). */
+  sort?: TooltipSort;
+  /**
+   * Custom formatter for every displayed number in the default UI. Called per
+   * row with the field hint (`'open' | 'high' | 'low' | 'close' | 'volume' | 'value'`).
+   * Defaults: adaptive precision for ohlc/value, compact (K/M/B/T) for volume.
+   * Ignored when {@link children} is a render-prop.
+   */
+  format?: TooltipFormatter;
+  /**
+   * Render-prop escape hatch. Receives the hover snapshots and replaces the
+   * built-in panel contents. The floating container (positioning, blur glass,
+   * clamping) is preserved — use
+   * [`computeTooltipPosition`](../../core/src/tooltip-position.ts) directly if
+   * you need your own container.
+   */
+  children?: (ctx: TooltipRenderContext) => ReactNode;
+}
+
+/** Default tooltip formatter — adaptive precision + compact volumes. */
+const defaultTooltipFormat: TooltipFormatter = (v, field) =>
+  field === 'volume' ? formatCompact(v) : formatPriceAdaptive(v);
+
+/**
+ * Floating near-cursor glass tooltip that appears while hovering the chart.
+ *
+ * Hover-only: without a crosshair position, the component renders `null`.
+ * The companion {@link InfoBar} shows last-known values when no hover is active.
+ */
+export function Tooltip({ sort = 'none', format = defaultTooltipFormat, children }: TooltipProps) {
+  const chart = useChartInstance();
+  const crosshair = useCrosshairPosition(chart);
+
+  const [, bump] = useState(0);
+  useLayoutEffect(() => {
+    const onOverlayChange = () => bump((n) => n + 1);
+    chart.on('overlayChange', onOverlayChange);
+    if (chart.getSeriesIds().length > 0) bump((n) => n + 1);
+
+    return () => {
+      chart.off('overlayChange', onOverlayChange);
+    };
+  }, [chart]);
+
+  if (!crosshair) return null;
+
+  const snapshots = buildHoverSnapshots(chart, { time: crosshair.time, sort, cacheKey: 'tooltip' });
+  if (snapshots.length === 0) return null;
+
+  const theme = chart.getTheme();
+  const dataInterval = chart.getDataInterval();
+  const mediaSize = chart.getMediaSize();
+  const chartWidth = mediaSize.width - chart.yAxisWidth;
+  const chartHeight = mediaSize.height - chart.xAxisHeight;
+
+  if (children) {
+    return (
+      <CustomFloatingTooltip
+        x={crosshair.mediaX}
+        y={crosshair.mediaY}
+        chartWidth={chartWidth}
+        chartHeight={chartHeight}
+        theme={theme}
+      >
+        {/* `crosshair.time` is the semantic truth — snapshots[0].data.time
+            shifts with `sort` and, for ragged multi-layer data, disagrees
+            with the actual hover moment. */}
+        {children({ snapshots, time: crosshair.time })}
+      </CustomFloatingTooltip>
+    );
+  }
+
+  return (
+    <FloatingTooltip
+      snapshots={snapshots}
+      displayTime={crosshair.time}
+      x={crosshair.mediaX}
+      y={crosshair.mediaY}
+      chartWidth={chartWidth}
+      chartHeight={chartHeight}
+      theme={theme}
+      dataInterval={dataInterval}
+      format={format}
+    />
+  );
+}
+
+function CustomFloatingTooltip({
+  x,
+  y,
+  chartWidth,
+  chartHeight,
+  theme,
+  children,
+}: {
+  x: number;
+  y: number;
+  chartWidth: number;
+  chartHeight: number;
+  theme: ChartTheme;
+  children: ReactNode;
+}) {
+  // Custom content has unknown dimensions until the first paint — measure the
+  // container, then position it. Hide with `visibility: hidden` on the
+  // pre-measured frame so the user never sees an un-clamped paint.
+  const nodeRef = useRef<HTMLDivElement | null>(null);
+  const [size, setSize] = useState<{ width: number; height: number } | null>(null);
+
+  useEffect(() => {
+    const node = nodeRef.current;
+    if (!node || typeof ResizeObserver === 'undefined') return;
+
+    const ro = new ResizeObserver((entries) => {
+      const box = entries[0]?.contentRect;
+      if (!box) return;
+      setSize((prev) =>
+        prev && prev.width === box.width && prev.height === box.height
+          ? prev
+          : { width: box.width, height: box.height },
+      );
+    });
+    ro.observe(node);
+
+    return () => ro.disconnect();
+  }, []);
+
+  const position = size
+    ? computeTooltipPosition({ x, y, chartWidth, chartHeight, tooltipWidth: size.width, tooltipHeight: size.height })
+    : { left: 0, top: 0 };
+
+  return (
+    <div
+      ref={nodeRef}
+      data-measured={size ? 'true' : 'false'}
+      style={{
+        position: 'absolute',
+        left: position.left,
+        top: position.top,
+        pointerEvents: 'none',
+        background: theme.tooltip.background,
+        backdropFilter: 'blur(12px)',
+        WebkitBackdropFilter: 'blur(12px)',
+        border: `1px solid ${theme.tooltip.borderColor}`,
+        borderRadius: 8,
+        padding: '10px 14px',
+        boxShadow: '0 4px 16px rgba(0,0,0,0.1), 0 1px 4px rgba(0,0,0,0.06)',
+        fontFamily: theme.typography.fontFamily,
+        fontSize: theme.tooltip.fontSize,
+        fontVariantNumeric: 'tabular-nums',
+        color: theme.tooltip.textColor,
+        width: 'max-content',
+        maxWidth: chartWidth,
+        boxSizing: 'border-box',
+        zIndex: 10,
+        visibility: size ? 'visible' : 'hidden',
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+function FloatingTooltip({
+  snapshots,
+  displayTime,
+  x,
+  y,
+  chartWidth,
+  chartHeight,
+  theme,
+  dataInterval,
+  format,
+}: {
+  snapshots: readonly SeriesSnapshot[];
+  displayTime: number;
+  x: number;
+  y: number;
+  chartWidth: number;
+  chartHeight: number;
+  theme: ChartTheme;
+  dataInterval: number;
+  format: TooltipFormatter;
+}) {
+  const hasOHLC = snapshots.some((s) => 'open' in s.data);
+  const lineCount = snapshots.filter((s) => !('open' in s.data)).length;
+
+  const tooltipWidth = 160;
+  const tooltipHeight = hasOHLC ? 140 : 40 + lineCount * 22;
+
+  const { left, top } = computeTooltipPosition({ x, y, chartWidth, chartHeight, tooltipWidth, tooltipHeight });
+
+  const bg = theme.tooltip.background;
+  const border = theme.tooltip.borderColor;
+  const shadow = '0 4px 16px rgba(0,0,0,0.1), 0 1px 4px rgba(0,0,0,0.06)';
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left,
+        top,
+        pointerEvents: 'none',
+        background: bg,
+        backdropFilter: 'blur(12px)',
+        WebkitBackdropFilter: 'blur(12px)',
+        border: `1px solid ${border}`,
+        borderRadius: 8,
+        padding: '10px 14px',
+        boxShadow: shadow,
+        fontSize: theme.tooltip.fontSize,
+        fontFamily: theme.typography.fontFamily,
+        fontVariantNumeric: 'tabular-nums',
+        color: theme.tooltip.textColor,
+        // Fix the rendered width to the value `computeTooltipPosition` assumes
+        // so content growth (e.g. long labels) can't push the tooltip past the
+        // clamp and back out of the plot area.
+        width: tooltipWidth,
+        boxSizing: 'border-box',
+        zIndex: 10,
+        transition: 'opacity 0.15s ease',
+      }}
+    >
+      {/* Time header */}
+      <div
+        style={{
+          fontSize: theme.axis.fontSize,
+          color: theme.axis.textColor,
+          marginBottom: 8,
+          paddingBottom: 6,
+          borderBottom: `1px solid ${border}`,
+          letterSpacing: '0.02em',
+        }}
+      >
+        {formatDate(displayTime)} {formatTime(displayTime, dataInterval)}
+      </div>
+
+      {snapshots.map((s) => {
+        const isOHLC = 'open' in s.data;
+        if (isOHLC) {
+          const ohlc = s.data as OHLCData;
+          const isUp = ohlc.close >= ohlc.open;
+          const valColor = resolveCandlestickBodyColor(
+            isUp ? theme.candlestick.up.body : theme.candlestick.down.body,
+          );
+          return (
+            <div key={s.id} style={{ display: 'grid', gridTemplateColumns: 'auto 1fr', gap: '4px 12px' }}>
+              <TooltipRow label="Open" color={valColor} display={format(ohlc.open, 'open')} />
+              <TooltipRow label="High" color={valColor} display={format(ohlc.high, 'high')} />
+              <TooltipRow label="Low" color={valColor} display={format(ohlc.low, 'low')} />
+              <TooltipRow label="Close" color={valColor} display={format(ohlc.close, 'close')} />
+              {ohlc.volume != null && (
+                <TooltipRow label="Volume" color={theme.tooltip.textColor} display={format(ohlc.volume, 'volume')} />
+              )}
+            </div>
+          );
+        }
+        const line = s.data as TimePoint;
+
+        return (
+          <div key={s.id} style={{ display: 'flex', alignItems: 'center', gap: 8, padding: '2px 0' }}>
+            <span
+              style={{
+                width: 8,
+                height: 8,
+                borderRadius: '50%',
+                background: s.color,
+                flexShrink: 0,
+              }}
+            />
+            <span style={{ opacity: 0.6, flex: 1 }}>{s.label ?? 'Value'}</span>
+            <span style={{ fontWeight: 600, color: s.color }}>{format(line.value, 'value')}</span>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
+
+function TooltipRow({ label, color, display }: { label: string; color: string; display: string }) {
+  return (
+    <>
+      <span style={{ opacity: 0.5 }}>{label}</span>
+      <span style={{ fontWeight: 600, color, textAlign: 'right' }}>{display}</span>
+    </>
+  );
+}

package/src/ui/YAxis.tsx

@@ -0,0 +1,122 @@
+import { useLayoutEffect, useRef } from 'react';
+
+import { resolveAxisFontSize, resolveAxisTextColor, type ValueFormatter } from '@wick-charts/core';
+
+import { useChartInstance } from '../context';
+import { useYRange } from '../store-bridge';
+
+interface TrackedTick {
+  opacity: number;
+  addedAt: number;
+  fadedAt?: number;
+}
+
+export interface YAxisProps {
+  /**
+   * Custom tick-label formatter. When supplied, overrides the built-in
+   * range-adaptive formatter for this axis.
+   */
+  format?: ValueFormatter;
+  /**
+   * Desired number of labels (≥ 2). Overrides any chart-level `axis.y.labelCount`.
+   * Realized count may differ ±1 after the 1-2-5 snap.
+   */
+  labelCount?: number;
+  /** Minimum pixel gap between adjacent labels (hard floor). Overrides chart-level. */
+  minLabelSpacing?: number;
+}
+
+export function YAxis({ format, labelCount, minLabelSpacing }: YAxisProps = {}) {
+  const chart = useChartInstance();
+  useYRange(chart); // subscribe to viewport changes so ticks re-render
+
+  // Route the prop through yScale so the *same* formatter drives every
+  // surface that reads `yScale.formatY()` (Crosshair, YLabel fallback).
+  useLayoutEffect(() => {
+    chart.yScale.setFormat(format ?? null);
+
+    return () => chart.yScale.setFormat(null);
+  }, [chart, format]);
+
+  useLayoutEffect(() => {
+    chart.setYAxisLabelDensity({
+      labelCount: labelCount ?? null,
+      minLabelSpacing: minLabelSpacing ?? null,
+    });
+
+    return () => {
+      chart.setYAxisLabelDensity({ labelCount: null, minLabelSpacing: null });
+    };
+  }, [chart, labelCount, minLabelSpacing]);
+
+  const theme = chart.getTheme();
+  const currentTicks = chart.yScale.niceTickValues();
+  const currentSet = new Set(currentTicks);
+
+  const mapRef = useRef<Map<number, TrackedTick>>(new Map());
+  const map = mapRef.current;
+  const now = performance.now();
+
+  for (const p of currentTicks) {
+    if (!map.has(p)) {
+      map.set(p, { opacity: 1, addedAt: now });
+    } else {
+      map.get(p)!.opacity = 1;
+    }
+  }
+
+  for (const [p, entry] of map) {
+    if (!currentSet.has(p)) {
+      if (entry.opacity !== 0) {
+        entry.opacity = 0;
+        entry.fadedAt = now;
+      }
+    }
+  }
+
+  for (const [p, entry] of map) {
+    if (entry.opacity === 0 && entry.fadedAt !== undefined && now - entry.fadedAt > 600) {
+      map.delete(p);
+    }
+  }
+
+  const allTicks = Array.from(map.entries());
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        right: 0,
+        top: 0,
+        bottom: chart.xAxisHeight,
+        width: chart.yAxisWidth,
+        pointerEvents: 'none',
+      }}
+    >
+      {allTicks.map(([price, entry]) => {
+        const y = chart.yScale.valueToY(price);
+        return (
+          <span
+            key={price}
+            style={{
+              position: 'absolute',
+              right: 8,
+              top: y,
+              transform: 'translateY(-50%)',
+              color: resolveAxisTextColor(theme, 'y'),
+              fontSize: resolveAxisFontSize(theme, 'y'),
+              fontFamily: theme.typography.fontFamily,
+              fontVariantNumeric: 'tabular-nums',
+              userSelect: 'none',
+              opacity: entry.opacity,
+              transition: 'opacity 0.3s ease',
+              willChange: 'opacity',
+            }}
+          >
+            {chart.yScale.formatY(price)}
+          </span>
+        );
+      })}
+    </div>
+  );
+}

package/src/ui/YLabel.tsx

@@ -0,0 +1,167 @@
+import { type ReactNode, useEffect, useLayoutEffect, useMemo, useState } from 'react';
+
+import type { ChartInstance, ValueFormatter } from '@wick-charts/core';
+
+import { useChartInstance } from '../context';
+import { NumberFlow } from './NumberFlow';
+
+/** Direction of the current value vs. previous close. Drives the badge color in the default UI. */
+export type YLabelDirection = 'up' | 'down' | 'neutral';
+
+/** Context passed to the {@link YLabel} render-prop. */
+export interface YLabelRenderContext {
+  readonly value: number;
+  /** Pixel Y of the badge anchor (already account for current viewport). */
+  readonly y: number;
+  /** Final background color chosen by the built-in UI — handy if you want to match the dashed line accent. */
+  readonly bgColor: string;
+  /** `true` while the chart is tracking a live last point (still mutating). */
+  readonly isLive: boolean;
+  readonly direction: YLabelDirection;
+  readonly format: ValueFormatter;
+}
+
+export interface YLabelProps {
+  /**
+   * Owning series id. **Optional** — when omitted, the first visible
+   * single-layer time series is picked, falling back to the first visible
+   * multi-layer time series. `null` (no compatible series) renders nothing.
+   */
+  seriesId?: string;
+  /** Override badge color (e.g. line color). If not set, uses up/down/neutral from theme. */
+  color?: string;
+  /**
+   * Custom formatter. Routed through NumberFlow as its `format` prop so the
+   * digit-by-digit animation still plays on the output string — NumberFlow
+   * animates whichever characters the formatter returns.
+   */
+  format?: ValueFormatter;
+  /**
+   * Render-prop escape hatch. Receives the resolved value, pixel position, and
+   * direction metadata. Replaces the built-in badge + dashed line entirely.
+   */
+  children?: (ctx: YLabelRenderContext) => ReactNode;
+}
+
+function resolveSeriesId(chart: ChartInstance, explicit: string | undefined): string | null {
+  if (explicit !== undefined) return explicit;
+
+  const singleLayer = chart.getSeriesIdsByType('time', { visibleOnly: true, singleLayerOnly: true });
+  if (singleLayer.length > 0) return singleLayer[0];
+
+  const anyTime = chart.getSeriesIdsByType('time', { visibleOnly: true });
+
+  return anyTime.length > 0 ? anyTime[0] : null;
+}
+
+export function YLabel({ seriesId, color, format, children }: YLabelProps) {
+  const chart = useChartInstance();
+
+  // Notify chart that YLabel is present (affects right padding).
+  useEffect(() => {
+    chart.setYLabel(true);
+    return () => chart.setYLabel(false);
+  }, [chart]);
+
+  // Single subscription covering data/visibility/theme/options changes, plus
+  // viewportChange for pixel-Y drift on pan/zoom where the value is unchanged
+  // but the badge must move.
+  const [, setBumpSignal] = useState(0);
+  useLayoutEffect(() => {
+    const onChange = () => setBumpSignal((n) => n + 1);
+    chart.on('overlayChange', onChange);
+    chart.on('viewportChange', onChange);
+    if (chart.getSeriesIds().length > 0) setBumpSignal((n) => n + 1);
+
+    return () => {
+      chart.off('overlayChange', onChange);
+      chart.off('viewportChange', onChange);
+    };
+  }, [chart]);
+
+  const resolvedId = resolveSeriesId(chart, seriesId);
+  const last = resolvedId !== null ? chart.getStackedLastValue(resolvedId) : null;
+  const previousClose = resolvedId !== null ? chart.getPreviousClose(resolvedId) : null;
+
+  const yRange = chart.yScale.getRange();
+  const range = yRange.max - yRange.min;
+  const fractionDigits = range < 0.1 ? 6 : range < 10 ? 4 : range < 1000 ? 2 : 0;
+
+  // Build the fallback range-adaptive Intl formatter before the early return
+  // so this hook call can't be skipped on subsequent renders (Rules of Hooks).
+  const effectiveFormat = useMemo<ValueFormatter>(() => {
+    if (format) return format;
+    const nf = new Intl.NumberFormat('en-US', {
+      minimumFractionDigits: fractionDigits,
+      maximumFractionDigits: fractionDigits,
+      useGrouping: false,
+    });
+
+    return (v: number) => nf.format(v);
+  }, [format, fractionDigits]);
+
+  if (!last || resolvedId === null) return null;
+
+  const { value, isLive } = last;
+  const theme = chart.getTheme();
+  const y = chart.yScale.valueToY(value);
+
+  const direction: YLabelDirection =
+    previousClose === null ? 'neutral' : value > previousClose ? 'up' : value < previousClose ? 'down' : 'neutral';
+
+  let bgColor: string;
+  if (!isLive) {
+    bgColor = theme.axis.textColor;
+  } else if (color) {
+    bgColor = color;
+  } else {
+    bgColor =
+      direction === 'up'
+        ? theme.yLabel.upBackground
+        : direction === 'down'
+          ? theme.yLabel.downBackground
+          : theme.yLabel.neutralBackground;
+  }
+
+  if (children) {
+    return <>{children({ value, y, bgColor, isLive, direction, format: effectiveFormat })}</>;
+  }
+
+  return (
+    <>
+      <div
+        style={{
+          position: 'absolute',
+          left: 0,
+          right: chart.yAxisWidth,
+          top: y,
+          height: 0,
+          borderTop: `1px dashed ${bgColor}`,
+          opacity: 0.5,
+          pointerEvents: 'none',
+          zIndex: 2,
+        }}
+      />
+      <div
+        style={{
+          position: 'absolute',
+          right: 4,
+          top: y,
+          transform: 'translateY(-50%)',
+          pointerEvents: 'auto',
+          zIndex: 3,
+          background: bgColor,
+          color: theme.yLabel.textColor,
+          fontSize: theme.yLabel.fontSize,
+          fontFamily: theme.typography.fontFamily,
+          padding: '3px 8px',
+          borderRadius: 3,
+          whiteSpace: 'nowrap',
+          transition: 'background-color 0.3s ease',
+        }}
+      >
+        <NumberFlow value={value} format={effectiveFormat} spinDuration={350} />
+      </div>
+    </>
+  );
+}