@wick-charts/react 0.2.2 → 0.3.0

package/src/ui/PieTooltip.tsx

@@ -0,0 +1,204 @@
+import { type ReactNode, useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+import {
+  type ChartInstance,
+  type HoverInfo,
+  type ValueFormatter,
+  computeTooltipPosition,
+  formatCompact,
+} from '@wick-charts/core';
+
+import { useChartInstance } from '../context';
+import { useCrosshairPosition } from '../store-bridge';
+
+/** Context passed to the {@link PieTooltip} render-prop. */
+export interface PieTooltipRenderContext {
+  readonly info: HoverInfo;
+  readonly format: ValueFormatter;
+}
+
+export interface PieTooltipProps {
+  /**
+   * Owning series id. **Optional** — when omitted, the first visible pie
+   * series is picked.
+   */
+  seriesId?: string;
+  /** Custom formatter for the slice value. Default: shared `formatCompact`. */
+  format?: ValueFormatter;
+  /** Render-prop escape hatch — receives hover info + format, replaces default UI. */
+  children?: (ctx: PieTooltipRenderContext) => ReactNode;
+}
+
+function resolvePieSeriesId(chart: ChartInstance, explicit: string | undefined): string | null {
+  if (explicit !== undefined) return explicit;
+
+  const pies = chart.getSeriesIdsByType('pie', { visibleOnly: true });
+
+  return pies.length > 0 ? pies[0] : null;
+}
+
+const DEFAULT_TOOLTIP_WIDTH = 160;
+const DEFAULT_TOOLTIP_HEIGHT = 70;
+
+/** Tooltip for pie/donut charts. Shows hovered slice label, value, and percentage. */
+export function PieTooltip({ seriesId, format = formatCompact, children }: PieTooltipProps) {
+  const chart = useChartInstance();
+  const crosshair = useCrosshairPosition(chart);
+
+  const [, setBumpSignal] = useState(0);
+  useLayoutEffect(() => {
+    const handler = () => setBumpSignal((n) => n + 1);
+    chart.on('overlayChange', handler);
+
+    return () => {
+      chart.off('overlayChange', handler);
+    };
+  }, [chart]);
+
+  const resolvedId = resolvePieSeriesId(chart, seriesId);
+  const info = resolvedId !== null ? chart.getHoverInfo(resolvedId) : null;
+  if (!info || !crosshair) return null;
+
+  const theme = chart.getTheme();
+  const mediaSize = chart.getMediaSize();
+
+  if (children) {
+    return (
+      <CustomPieTooltip
+        x={crosshair.mediaX}
+        y={crosshair.mediaY}
+        chartWidth={mediaSize.width}
+        chartHeight={mediaSize.height}
+      >
+        {children({ info, format })}
+      </CustomPieTooltip>
+    );
+  }
+
+  const { left, top } = computeTooltipPosition({
+    x: crosshair.mediaX,
+    y: crosshair.mediaY,
+    chartWidth: mediaSize.width,
+    chartHeight: mediaSize.height,
+    tooltipWidth: DEFAULT_TOOLTIP_WIDTH,
+    tooltipHeight: DEFAULT_TOOLTIP_HEIGHT,
+    offsetX: 16,
+    offsetY: 16,
+  });
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left,
+        top,
+        pointerEvents: 'none',
+        zIndex: 10,
+        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)',
+        fontSize: theme.typography.fontSize,
+        fontFamily: theme.typography.fontFamily,
+        color: theme.tooltip.textColor,
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 6,
+      }}
+    >
+      <div style={{ display: 'flex', alignItems: 'center', gap: 8 }}>
+        <span
+          style={{
+            width: 10,
+            height: 10,
+            borderRadius: '50%',
+            background: info.color,
+            flexShrink: 0,
+          }}
+        />
+        <span style={{ fontWeight: 600 }}>{info.label}</span>
+      </div>
+      <div style={{ display: 'flex', justifyContent: 'space-between', gap: 16 }}>
+        <span style={{ opacity: 0.6 }}>{format(info.value)}</span>
+        <span style={{ fontWeight: 600 }}>{info.percent.toFixed(1)}%</span>
+      </div>
+    </div>
+  );
+}
+
+// Custom slot content has unknown dimensions — measure the container, then
+// position it. Matches the pattern in `Tooltip` (PR #39) so user-rendered pie
+// tooltips flip/clamp correctly near edges instead of overflowing with the
+// hardcoded 160×70 defaults.
+function CustomPieTooltip({
+  x,
+  y,
+  chartWidth,
+  chartHeight,
+  children,
+}: {
+  x: number;
+  y: number;
+  chartWidth: number;
+  chartHeight: number;
+  children: ReactNode;
+}) {
+  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,
+        offsetX: 16,
+        offsetY: 16,
+      })
+    : { left: 0, top: 0 };
+
+  return (
+    <div
+      ref={nodeRef}
+      data-measured={size ? 'true' : 'false'}
+      style={{
+        position: 'absolute',
+        left: position.left,
+        top: position.top,
+        pointerEvents: 'none',
+        zIndex: 10,
+        width: 'max-content',
+        maxWidth: chartWidth,
+        boxSizing: 'border-box',
+        // Hide until the first measurement so the user never sees a paint
+        // with out-of-bounds position.
+        visibility: size ? 'visible' : 'hidden',
+      }}
+    >
+      {children}
+    </div>
+  );
+}

package/src/ui/Sparkline.tsx

@@ -0,0 +1,216 @@
+import { type CSSProperties, useMemo } from 'react';
+
+import { type ChartTheme, type TimePoint, formatCompact, resolveCandlestickBodyColor } from '@wick-charts/core';
+
+import { BarSeries } from '../BarSeries';
+import { ChartContainer } from '../ChartContainer';
+import { LineSeries } from '../LineSeries';
+
+export type SparklineVariant = 'line' | 'bar';
+export type SparklineValuePosition = 'left' | 'right' | 'none';
+
+export interface SparklineProps {
+  data: TimePoint[];
+  theme: ChartTheme;
+  /** 'line' (default) or 'bar' */
+  variant?: SparklineVariant;
+  /** Where to show the value label */
+  valuePosition?: SparklineValuePosition;
+  /** Custom format for the value */
+  formatValue?: (value: number) => string;
+  /** Label text above the value */
+  label?: string;
+  /** Sublabel text below the value (defaults to the change %) */
+  sublabel?: string;
+  /** Line/bar color override (defaults to theme) */
+  color?: string;
+  /** Secondary color for negative bars */
+  negativeColor?: string;
+  /** Show area fill under line */
+  area?: { visible: boolean };
+  /** @deprecated Use {@link area} instead. */
+  areaFill?: boolean;
+  /** Chart width (default: 140) */
+  width?: number;
+  /** Overall height (default: 48) */
+  height?: number;
+  /** Stroke width in CSS pixels (default: 1.5) */
+  strokeWidth?: number;
+  /** Show chart background gradient (default: true) */
+  gradient?: boolean;
+  /** Container style override */
+  style?: CSSProperties;
+}
+
+function hexToRgba(color: string, alpha: number): string {
+  if (color.startsWith('rgba')) return color;
+  if (!color.startsWith('#')) return color;
+  const r = parseInt(color.slice(1, 3), 16);
+  const g = parseInt(color.slice(3, 5), 16);
+  const b = parseInt(color.slice(5, 7), 16);
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+function computeChange(data: TimePoint[]): { value: number; pct: number; positive: boolean } {
+  if (data.length < 2) return { value: 0, pct: 0, positive: true };
+  const first = data[0].value;
+  const last = data[data.length - 1].value;
+  const diff = last - first;
+  const pct = first !== 0 ? (diff / first) * 100 : 0;
+  return { value: diff, pct, positive: diff >= 0 };
+}
+
+export function Sparkline({
+  data,
+  theme,
+  variant = 'line',
+  valuePosition = 'right',
+  formatValue = formatCompact,
+  label,
+  sublabel,
+  color,
+  negativeColor,
+  area,
+  areaFill,
+  width = 140,
+  height = 48,
+  strokeWidth = 1.5,
+  gradient = true,
+  style,
+}: SparklineProps) {
+  // Default area-visible = true. `area` wins if caller passes it; otherwise
+  // fall back to the deprecated flat `areaFill` flag for backward compatibility.
+  const areaVisible = area?.visible ?? areaFill ?? true;
+  const lastValue = data.length > 0 ? data[data.length - 1].value : 0;
+  const change = useMemo(() => computeChange(data), [data]);
+
+  const resolvedColor = color ?? theme.seriesColors[0];
+  const resolvedNegColor = negativeColor ?? resolveCandlestickBodyColor(theme.candlestick.down.body);
+  const changeColor = resolveCandlestickBodyColor(
+    change.positive ? theme.candlestick.up.body : theme.candlestick.down.body,
+  );
+
+  const valueBlock = valuePosition !== 'none' && (
+    <div
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        justifyContent: 'center',
+        gap: 1,
+        minWidth: 0,
+        flexShrink: 0,
+      }}
+    >
+      {label && (
+        <div
+          style={{
+            fontSize: theme.axis.fontSize,
+            color: theme.axis.textColor,
+            lineHeight: 1.2,
+            whiteSpace: 'nowrap',
+            overflow: 'hidden',
+            textOverflow: 'ellipsis',
+          }}
+        >
+          {label}
+        </div>
+      )}
+      <div
+        style={{
+          fontSize: theme.typography.fontSize + 3,
+          fontWeight: 700,
+          color: theme.tooltip.textColor,
+          lineHeight: 1.1,
+          whiteSpace: 'nowrap',
+          fontVariantNumeric: 'tabular-nums',
+        }}
+      >
+        {formatValue(lastValue)}
+      </div>
+      {sublabel !== undefined ? (
+        <div
+          style={{
+            fontSize: theme.axis.fontSize - 1,
+            color: theme.axis.textColor,
+            lineHeight: 1.2,
+            whiteSpace: 'nowrap',
+          }}
+        >
+          {sublabel}
+        </div>
+      ) : (
+        <div
+          style={{
+            fontSize: theme.axis.fontSize - 1,
+            fontWeight: 500,
+            color: changeColor,
+            lineHeight: 1.2,
+            whiteSpace: 'nowrap',
+            fontVariantNumeric: 'tabular-nums',
+          }}
+        >
+          {change.positive ? '+' : ''}
+          {change.pct.toFixed(1)}%
+        </div>
+      )}
+    </div>
+  );
+
+  const chartBlock = (
+    <div style={{ width, height, flexShrink: 0, borderRadius: 4, overflow: 'hidden' }}>
+      <ChartContainer
+        theme={theme}
+        axis={{
+          y: { visible: false, width: 0 },
+          x: { visible: false, height: 0 },
+        }}
+        padding={{ top: 5, right: 0, bottom: 0, left: 0 }}
+        gradient={gradient}
+        interactive={false}
+        grid={{ visible: false }}
+      >
+        {variant === 'line' ? (
+          <LineSeries
+            data={[data]}
+            options={{
+              colors: [resolvedColor],
+              strokeWidth,
+              area: { visible: areaVisible },
+              pulse: false,
+              stacking: 'off',
+            }}
+          />
+        ) : (
+          <BarSeries
+            data={[data]}
+            options={{
+              colors: [resolvedColor, resolvedNegColor],
+              barWidthRatio: 0.7,
+              stacking: 'off',
+            }}
+          />
+        )}
+      </ChartContainer>
+    </div>
+  );
+
+  return (
+    <div
+      style={{
+        display: 'inline-flex',
+        alignItems: 'center',
+        gap: 12,
+        padding: '8px 12px',
+        borderRadius: 8,
+        background: hexToRgba(theme.tooltip.background, 0.7),
+        border: `1px solid ${theme.tooltip.borderColor}`,
+        fontFamily: theme.typography.fontFamily,
+        ...style,
+      }}
+    >
+      {valuePosition === 'left' && valueBlock}
+      {chartBlock}
+      {valuePosition === 'right' && valueBlock}
+    </div>
+  );
+}

package/src/ui/TimeAxis.tsx

@@ -0,0 +1,112 @@
+import { useLayoutEffect, useRef } from 'react';
+
+import { formatTime, resolveAxisFontSize, resolveAxisTextColor } from '@wick-charts/core';
+
+import { useChartInstance } from '../context';
+import { useVisibleRange } from '../store-bridge';
+
+interface TrackedTick {
+  opacity: number;
+  addedAt: number;
+  fadedAt?: number;
+}
+
+export interface TimeAxisProps {
+  /** Desired number of labels (≥ 2). Overrides chart-level `axis.x.labelCount`. */
+  labelCount?: number;
+  /** Minimum pixel gap between adjacent labels (hard floor). Overrides chart-level. */
+  minLabelSpacing?: number;
+}
+
+export function TimeAxis({ labelCount, minLabelSpacing }: TimeAxisProps = {}) {
+  const chart = useChartInstance();
+  useVisibleRange(chart); // subscribe to viewport changes so ticks re-render
+
+  useLayoutEffect(() => {
+    chart.setTimeAxisLabelDensity({
+      labelCount: labelCount ?? null,
+      minLabelSpacing: minLabelSpacing ?? null,
+    });
+
+    return () => {
+      chart.setTimeAxisLabelDensity({ labelCount: null, minLabelSpacing: null });
+    };
+  }, [chart, labelCount, minLabelSpacing]);
+  const theme = chart.getTheme();
+  const dataInterval = chart.getDataInterval();
+  const { ticks: currentTicks, tickInterval } = chart.timeScale.niceTickValues(dataInterval);
+  const currentSet = new Set(currentTicks);
+
+  // Persistent map: tick value → tracked state
+  const mapRef = useRef<Map<number, TrackedTick>>(new Map());
+  const map = mapRef.current;
+  const now = performance.now();
+
+  // Mark current ticks as visible
+  for (const t of currentTicks) {
+    if (!map.has(t)) {
+      map.set(t, { opacity: 1, addedAt: now });
+    } else {
+      map.get(t)!.opacity = 1;
+    }
+  }
+
+  // Mark missing ticks for fade-out
+  for (const [t, entry] of map) {
+    if (!currentSet.has(t)) {
+      if (entry.opacity !== 0) {
+        entry.opacity = 0;
+        entry.fadedAt = now;
+      }
+    }
+  }
+
+  // Clean up ticks that have finished fading (400ms CSS transition + buffer)
+  for (const [t, entry] of map) {
+    if (entry.opacity === 0 && entry.fadedAt !== undefined && now - entry.fadedAt > 600) {
+      map.delete(t);
+    }
+  }
+
+  // Collect all ticks to render (current + fading out)
+  const allTicks = Array.from(map.entries());
+
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: 0,
+        bottom: 0,
+        right: chart.yAxisWidth,
+        height: chart.xAxisHeight,
+        pointerEvents: 'none',
+        display: 'flex',
+        alignItems: 'center',
+      }}
+    >
+      {allTicks.map(([time, entry]) => {
+        const x = chart.timeScale.timeToX(time);
+        return (
+          <span
+            key={time}
+            style={{
+              position: 'absolute',
+              left: x,
+              transform: 'translateX(-50%)',
+              color: resolveAxisTextColor(theme, 'x'),
+              fontSize: resolveAxisFontSize(theme, 'x'),
+              fontFamily: theme.typography.fontFamily,
+              userSelect: 'none',
+              whiteSpace: 'nowrap',
+              opacity: entry.opacity,
+              transition: 'opacity 0.3s ease',
+              willChange: 'opacity',
+            }}
+          >
+            {formatTime(time, tickInterval)}
+          </span>
+        );
+      })}
+    </div>
+  );
+}

package/src/ui/Title.tsx

@@ -0,0 +1,62 @@
+import type { CSSProperties, ReactNode } from 'react';
+
+import { useTheme } from '../ThemeContext';
+
+/** Props for the {@link Title} component. */
+export interface TitleProps {
+  /** Primary label (e.g. "BTC/USD"). */
+  children?: ReactNode;
+  /**
+   * Secondary label rendered in a muted colour next to the primary one (e.g.
+   * "Live Candlestick", "1m", series count).
+   */
+  sub?: ReactNode;
+  /** Extra styles merged onto the flex row. */
+  style?: CSSProperties;
+}
+
+/**
+ * Chart title / subtitle bar rendered as a flex row above the chart canvas
+ * (above {@link InfoBar} when both are present). Hoisted out of the
+ * overlay layer by {@link ChartContainer}, so browser flex layout reserves
+ * its height and ResizeObserver drives a Y-range recompute.
+ *
+ * Place it at the top of a chart's children — its slot in the DOM is
+ * determined by `ChartContainer`, not by source order:
+ * ```tsx
+ * <ChartContainer>
+ *   <Title sub="Live Candlestick">BTC/USD</Title>
+ *   <InfoBar />
+ *   <CandlestickSeries data={data} />
+ *   ...
+ * </ChartContainer>
+ * ```
+ */
+export function Title({ children, sub, style }: TitleProps) {
+  const theme = useTheme();
+  return (
+    <div
+      data-chart-title=""
+      style={{
+        display: 'flex',
+        alignItems: 'baseline',
+        gap: 6,
+        padding: '6px 8px 4px',
+        flexShrink: 0,
+        fontFamily: theme.typography.fontFamily,
+        fontSize: theme.typography.fontSize,
+        fontWeight: 600,
+        color: theme.tooltip.textColor,
+        pointerEvents: 'none',
+        ...style,
+      }}
+    >
+      {children != null && children !== false && <span>{children}</span>}
+      {sub != null && sub !== false && (
+        <span style={{ fontWeight: 400, color: theme.axis.textColor, fontSize: theme.axis.fontSize }}>
+          {sub}
+        </span>
+      )}
+    </div>
+  );
+}