@wick-charts/react 0.2.2 → 0.3.0

package/src/ui/Legend.tsx

@@ -0,0 +1,274 @@
+import { type ReactNode, useLayoutEffect, useMemo, useRef, useState } from 'react';
+
+import type { ChartInstance, LegendItem } from '@wick-charts/core';
+
+import { useChartInstance } from '../context';
+import { useTheme } from '../ThemeContext';
+
+/**
+ * Minimal visual shape the {@link LegendProps.items} override accepts — just
+ * the pieces the built-in swatch/label UI needs. The canonical
+ * {@link LegendItem} (re-exported from `@wick-charts/core`) carries full
+ * identity plus `toggle`/`isolate` closures; those aren't meaningful when a
+ * consumer hands in a pre-baked, non-interactive legend.
+ */
+export interface LegendItemOverride {
+  label: string;
+  color: string;
+}
+
+/**
+ * Legend interaction mode.
+ * - `'toggle'` — click toggles the clicked item on/off (default).
+ * - `'isolate'` — click shows only that item; click again shows all.
+ * - `'solo'` — **@deprecated** alias for `'isolate'`, kept for back-compat.
+ */
+export type LegendMode = 'toggle' | 'isolate' | 'solo';
+
+/** Context passed to the {@link Legend} render-prop. */
+export interface LegendRenderContext {
+  readonly items: readonly LegendItem[];
+}
+
+export interface LegendProps {
+  /**
+   * Static override for auto-detected items. Renders a non-interactive legend
+   * with just swatch + label. Ignored when {@link children} is a render-prop.
+   */
+  items?: LegendItemOverride[];
+  /** Layout position. Default: 'bottom'. */
+  position?: 'bottom' | 'right';
+  /** Click behavior for the built-in UI. Default: `'toggle'`. Ignored when {@link children} is provided. */
+  mode?: LegendMode;
+  /**
+   * Render-prop escape hatch. Receives the computed `items` (each carrying
+   * its own `toggle()` / `isolate()` closures) and fully replaces the
+   * built-in flex row / column. Callers can filter, reorder, and re-style
+   * without reimplementing visibility wiring.
+   */
+  children?: (ctx: LegendRenderContext) => ReactNode;
+}
+
+interface BuildArgs {
+  chart: ChartInstance;
+  isolatedIdRef: { current: string | null };
+  setIsolatedId: (v: string | null) => void;
+}
+
+function buildLegendItems({ chart, isolatedIdRef, setIsolatedId }: BuildArgs): LegendItem[] {
+  const items: LegendItem[] = [];
+  const seriesIds = chart.getSeriesIds();
+
+  for (const seriesId of seriesIds) {
+    const layers = chart.getSeriesLayers(seriesId);
+    if (layers) {
+      const baseLabel = chart.getSeriesLabel(seriesId);
+      for (let layerIndex = 0; layerIndex < layers.length; layerIndex++) {
+        const id = `${seriesId}_layer${layerIndex}`;
+        const visible = chart.isSeriesVisible(seriesId) && chart.isLayerVisible(seriesId, layerIndex);
+        items.push(
+          makeItem({
+            id,
+            seriesId,
+            layerIndex,
+            label: baseLabel ? `${baseLabel} ${layerIndex + 1}` : `Series ${layerIndex + 1}`,
+            color: layers[layerIndex].color,
+            isDisabled: !visible,
+            chart,
+            isolatedIdRef,
+            setIsolatedId,
+          }),
+        );
+      }
+    } else {
+      const color = chart.getSeriesColor(seriesId);
+      if (!color) continue;
+
+      const label = chart.getSeriesLabel(seriesId);
+      const visible = chart.isSeriesVisible(seriesId);
+      items.push(
+        makeItem({
+          id: seriesId,
+          seriesId,
+          layerIndex: undefined,
+          label: label ?? 'Series',
+          color,
+          isDisabled: !visible,
+          chart,
+          isolatedIdRef,
+          setIsolatedId,
+        }),
+      );
+    }
+  }
+
+  return items;
+}
+
+interface MakeItemArgs {
+  id: string;
+  seriesId: string;
+  layerIndex: number | undefined;
+  label: string;
+  color: string;
+  isDisabled: boolean;
+  chart: ChartInstance;
+  isolatedIdRef: { current: string | null };
+  setIsolatedId: (v: string | null) => void;
+}
+
+function makeItem(args: MakeItemArgs): LegendItem {
+  const { id, seriesId, layerIndex, label, color, isDisabled, chart, isolatedIdRef, setIsolatedId } = args;
+
+  const toggle = () => {
+    if (layerIndex !== undefined) {
+      chart.setLayerVisible(seriesId, layerIndex, !chart.isLayerVisible(seriesId, layerIndex));
+    } else {
+      chart.setSeriesVisible(seriesId, !chart.isSeriesVisible(seriesId));
+    }
+  };
+
+  const isolate = () => {
+    if (isolatedIdRef.current === id) {
+      chart.batch(() => {
+        for (const sid of chart.getSeriesIds()) {
+          chart.setSeriesVisible(sid, true);
+          const layers = chart.getSeriesLayers(sid);
+          if (layers) {
+            for (let i = 0; i < layers.length; i++) chart.setLayerVisible(sid, i, true);
+          }
+        }
+      });
+      // Mutate the ref synchronously so a back-to-back second `isolate()`
+      // sees the unisolated state even before React's re-render commits.
+      isolatedIdRef.current = null;
+      setIsolatedId(null);
+
+      return;
+    }
+
+    chart.batch(() => {
+      for (const sid of chart.getSeriesIds()) {
+        const layers = chart.getSeriesLayers(sid);
+        if (layers) {
+          chart.setSeriesVisible(sid, sid === seriesId);
+          for (let i = 0; i < layers.length; i++) {
+            chart.setLayerVisible(sid, i, sid === seriesId && i === layerIndex);
+          }
+        } else {
+          chart.setSeriesVisible(sid, sid === id);
+        }
+      }
+    });
+    isolatedIdRef.current = id;
+    setIsolatedId(id);
+  };
+
+  return { id, seriesId, layerIndex, label, color, isDisabled, toggle, isolate };
+}
+
+export function Legend({ items, position = 'bottom', mode = 'toggle', children }: LegendProps) {
+  const chart = useChartInstance();
+  const theme = useTheme();
+  const [isolatedId, setIsolatedId] = useState<string | null>(null);
+  const [bumpSignal, setBumpSignal] = useState(0);
+
+  // Closure bound to every LegendItem.isolate() reads live state through this
+  // ref, not the captured-at-render value, so a second click correctly sees
+  // `isolatedId` even when the component hasn't re-rendered yet.
+  const isolatedIdRef = useRef(isolatedId);
+  isolatedIdRef.current = isolatedId;
+
+  useLayoutEffect(() => {
+    const onOverlayChange = () => setBumpSignal((n) => n + 1);
+    const onSeriesChange = () => setIsolatedId(null);
+    chart.on('overlayChange', onOverlayChange);
+    chart.on('seriesChange', onSeriesChange);
+    // Catch-up: a sibling series' layout effect may have registered data in
+    // the same commit. Bump so the next synchronous render picks it up.
+    if (chart.getSeriesIds().length > 0) setBumpSignal((n) => n + 1);
+
+    return () => {
+      chart.off('overlayChange', onOverlayChange);
+      chart.off('seriesChange', onSeriesChange);
+    };
+  }, [chart]);
+
+  const legendItems = useMemo(
+    () => buildLegendItems({ chart, isolatedIdRef, setIsolatedId }),
+    // biome-ignore lint/correctness/useExhaustiveDependencies: `bumpSignal` is the subscription signal; isolatedId triggers the opacity-only refresh
+    [chart, isolatedId, bumpSignal],
+  );
+
+  const isRight = position === 'right';
+  const containerStyle: React.CSSProperties = {
+    display: 'flex',
+    flexDirection: isRight ? 'column' : 'row',
+    flexWrap: 'wrap',
+    gap: isRight ? 6 : 14,
+    padding: isRight ? '8px 6px' : '6px 8px',
+    alignItems: isRight ? 'flex-start' : 'center',
+    justifyContent: isRight ? 'flex-start' : 'center',
+    fontFamily: theme.typography.fontFamily,
+    fontSize: theme.axis.fontSize,
+    color: theme.axis.textColor,
+    pointerEvents: 'auto',
+    flexShrink: 0,
+  };
+
+  if (children) {
+    if (legendItems.length === 0) return null;
+
+    return (
+      <div data-legend={position} style={containerStyle}>
+        {children({ items: legendItems })}
+      </div>
+    );
+  }
+
+  if (items) {
+    if (items.length === 0) return null;
+
+    return (
+      <div data-legend={position} style={containerStyle}>
+        {items.map((item, i) => (
+          // biome-ignore lint/suspicious/noArrayIndexKey: static override — caller chose the order
+          <div key={i} style={{ display: 'flex', alignItems: 'center', gap: 4, userSelect: 'none' }}>
+            <span style={{ width: 8, height: 8, borderRadius: 2, background: item.color, flexShrink: 0 }} />
+            <span style={{ whiteSpace: 'nowrap' }}>{item.label}</span>
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  if (legendItems.length === 0) return null;
+
+  const handleClick = (item: LegendItem) => {
+    if (mode === 'isolate' || mode === 'solo') item.isolate();
+    else item.toggle();
+  };
+
+  return (
+    <div data-legend={position} style={containerStyle}>
+      {legendItems.map((item) => (
+        <div
+          key={item.id}
+          onClick={() => handleClick(item)}
+          style={{
+            display: 'flex',
+            alignItems: 'center',
+            gap: 4,
+            cursor: 'pointer',
+            opacity: item.isDisabled ? 0.35 : 1,
+            transition: 'opacity 0.15s ease',
+            userSelect: 'none',
+          }}
+        >
+          <span style={{ width: 8, height: 8, borderRadius: 2, background: item.color, flexShrink: 0 }} />
+          <span style={{ whiteSpace: 'nowrap' }}>{item.label}</span>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/ui/NumberFlow.tsx

@@ -0,0 +1,118 @@
+import { type CSSProperties, useEffect, useMemo, useRef } from 'react';
+
+export interface NumberFlowProps {
+  value: number;
+  /**
+   * Value-to-string formatter. Defaults to the current locale's
+   * `Intl.NumberFormat` when omitted. Pass the shared `formatCompact` /
+   * `formatPriceAdaptive` helpers or your own function to customize.
+   *
+   * `Intl.NumberFormatOptions` is also accepted (legacy) — it's routed
+   * through the built-in `Intl.NumberFormat` for back-compat with callers
+   * from before this prop was a function.
+   */
+  format?: ((value: number) => string) | Intl.NumberFormatOptions;
+  locale?: string;
+  spinDuration?: number;
+  className?: string;
+  style?: CSSProperties;
+}
+
+const DIGITS = ['0', '1', '2', '3', '4', '5', '6', '7', '8', '9'];
+
+interface CharPart {
+  type: 'digit' | 'symbol';
+  value: string;
+}
+
+function decompose(formatted: string): CharPart[] {
+  const parts: CharPart[] = [];
+  for (const char of formatted) {
+    if (char >= '0' && char <= '9') {
+      parts.push({ type: 'digit', value: char });
+    } else {
+      parts.push({ type: 'symbol', value: char });
+    }
+  }
+  return parts;
+}
+
+export function NumberFlow({ value, format, locale = 'en-US', spinDuration = 350, className, style }: NumberFlowProps) {
+  const effectiveFormat = useMemo<(v: number) => string>(() => {
+    if (typeof format === 'function') return format;
+    const nf = new Intl.NumberFormat(locale, typeof format === 'object' ? format : undefined);
+    return (v: number) => nf.format(v);
+  }, [format, locale]);
+
+  const formatted = effectiveFormat(value);
+  const parts = decompose(formatted);
+
+  return (
+    <span
+      className={className}
+      style={{
+        display: 'inline-flex',
+        fontVariantNumeric: 'tabular-nums',
+        lineHeight: 1.2,
+        ...style,
+      }}
+    >
+      {parts.map((part, i) =>
+        part.type === 'digit' ? (
+          <DigitSlot key={`d${i}`} digit={parseInt(part.value, 10)} duration={spinDuration} />
+        ) : (
+          <span key={`s${i}`} style={{ display: 'inline-block' }}>
+            {part.value}
+          </span>
+        ),
+      )}
+    </span>
+  );
+}
+
+interface DigitSlotProps {
+  digit: number;
+  duration: number;
+}
+
+function DigitSlot({ digit, duration }: DigitSlotProps) {
+  const mountedRef = useRef(false);
+
+  useEffect(() => {
+    mountedRef.current = true;
+  }, []);
+
+  return (
+    <span
+      style={{
+        display: 'inline-block',
+        height: '1.2em',
+        overflow: 'hidden',
+        position: 'relative',
+      }}
+    >
+      <span
+        style={{
+          display: 'flex',
+          flexDirection: 'column',
+          transform: `translateY(${-digit * 1.2}em)`,
+          transition: mountedRef.current ? `transform ${duration}ms cubic-bezier(0.16, 1, 0.3, 1)` : 'none',
+        }}
+      >
+        {DIGITS.map((d) => (
+          <span
+            key={d}
+            style={{
+              display: 'flex',
+              alignItems: 'center',
+              justifyContent: 'center',
+              height: '1.2em',
+            }}
+          >
+            {d}
+          </span>
+        ))}
+      </span>
+    </span>
+  );
+}

package/src/ui/PieLegend.tsx

@@ -0,0 +1,152 @@
+import { type ReactNode, useLayoutEffect, useState } from 'react';
+
+import { type ChartInstance, type SliceInfo, type ValueFormatter, formatCompact } from '@wick-charts/core';
+
+import { useChartInstance } from '../context';
+
+/**
+ * Legend row content.
+ *
+ * - `'value'` — only the absolute value (e.g. `25`).
+ * - `'percent'` — only the percentage (e.g. `25.0%`).
+ * - `'both'` (default) — value + percent side-by-side; value is bold, percent dimmed.
+ */
+export type PieLegendMode = 'value' | 'percent' | 'both';
+
+/**
+ * Where the legend sits relative to the pie canvas.
+ *
+ * - `'bottom'` (default) — flex sibling below the canvas. Matches the time-series `<Legend>` layout.
+ * - `'right'` — flex sibling on the right of the canvas.
+ * - `'overlay'` — absolute overlay on top of the canvas. Back-compat escape hatch for callers
+ *   that were relying on the old positioning; stacks with any `<Title>` at the top-left and can
+ *   collide with it, so use sparingly.
+ */
+export type PieLegendPosition = 'bottom' | 'right' | 'overlay';
+
+/** Context passed to the {@link PieLegend} render-prop. */
+export interface PieLegendRenderContext {
+  readonly slices: readonly SliceInfo[];
+  readonly mode: PieLegendMode;
+  readonly format: ValueFormatter;
+}
+
+export interface PieLegendProps {
+  /**
+   * Owning series id. **Optional** — when omitted, the first visible pie
+   * series is picked.
+   */
+  seriesId?: string;
+  /** Default: `'both'`. See {@link PieLegendMode}. */
+  mode?: PieLegendMode;
+  /** Custom formatter for the absolute slice value. Default: shared `formatCompact`. */
+  format?: ValueFormatter;
+  /** Layout placement. Default: `'bottom'`. See {@link PieLegendPosition}. */
+  position?: PieLegendPosition;
+  /** Render-prop escape hatch. Receives slices + mode + format, replaces default UI. */
+  children?: (ctx: PieLegendRenderContext) => 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;
+}
+
+export function PieLegend({ seriesId, mode: modeProp, format, position, children }: PieLegendProps) {
+  const mode: PieLegendMode = modeProp ?? 'both';
+  const resolvedPosition: PieLegendPosition = position ?? 'bottom';
+  const formatter: ValueFormatter = format ?? formatCompact;
+  const chart = useChartInstance();
+  const theme = chart.getTheme();
+
+  const [, setBumpSignal] = useState(0);
+  useLayoutEffect(() => {
+    const handler = () => setBumpSignal((n) => n + 1);
+    chart.on('overlayChange', handler);
+    if (chart.getSeriesIds().length > 0) handler();
+
+    return () => {
+      chart.off('overlayChange', handler);
+    };
+  }, [chart]);
+
+  const resolvedId = resolvePieSeriesId(chart, seriesId);
+  const slices = resolvedId !== null ? chart.getSliceInfo(resolvedId) : null;
+  if (!slices || slices.length === 0) return null;
+
+  if (children) return <>{children({ slices, mode, format: formatter })}</>;
+
+  // When hoisted as a flex sibling (`bottom` / `right`), the container already
+  // reserves the legend's box. The extra 8px × 12px block padding only applies
+  // in `overlay` mode where the legend floats above the canvas and needs to
+  // breathe away from the edges.
+  const isOverlay = resolvedPosition === 'overlay';
+
+  return (
+    <div
+      data-chart-pie-legend=""
+      data-chart-pie-legend-position={resolvedPosition}
+      style={{
+        display: 'flex',
+        flexDirection: 'column',
+        gap: 6,
+        padding: isOverlay ? '8px 12px' : '6px 10px',
+        fontFamily: theme.typography.fontFamily,
+        fontSize: theme.typography.fontSize,
+        color: theme.tooltip.textColor,
+        pointerEvents: 'auto',
+      }}
+    >
+      {slices.map((slice, i) => (
+        // biome-ignore lint/suspicious/noArrayIndexKey: slice index is stable within a render
+        <div key={i} style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
+          <span
+            style={{
+              width: 10,
+              height: 10,
+              borderRadius: '50%',
+              background: slice.color,
+              flexShrink: 0,
+            }}
+          />
+          <span style={{ flex: 1, opacity: 0.8 }}>{slice.label}</span>
+          {(mode === 'value' || mode === 'both') && (
+            <span
+              style={{
+                fontWeight: 600,
+                fontVariantNumeric: 'tabular-nums',
+                // In 'value'-only mode the cell is the primary number and wants
+                // a wider reserved slot; in 'both' it's followed by the percent
+                // so keep it tight.
+                minWidth: mode === 'value' ? 40 : undefined,
+                textAlign: 'right',
+              }}
+            >
+              {formatter(slice.value)}
+            </span>
+          )}
+          {(mode === 'percent' || mode === 'both') && (
+            <span
+              style={{
+                // In 'percent' mode the percent IS the value → bold at full
+                // opacity. In 'both' it's a secondary reading next to the
+                // absolute value → dim + smaller.
+                opacity: mode === 'percent' ? 1 : 0.5,
+                fontWeight: mode === 'percent' ? 600 : 400,
+                fontSize: mode === 'percent' ? theme.typography.fontSize : theme.axis.fontSize,
+                fontVariantNumeric: 'tabular-nums',
+                minWidth: 40,
+                textAlign: 'right',
+              }}
+            >
+              {slice.percent.toFixed(1)}%
+            </span>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}