@wick-charts/react 0.3.5 → 0.4.0

package/src/LineSeries.tsx

@@ -1,6 +1,12 @@
 import { useEffect, useLayoutEffect, useRef } from 'react';
 
-import { type LineSeriesOptions, type TimePoint, normalizeTime } from '@wick-charts/core';
+import {
+  EMPTY_SYNC_STATE,
+  type LineSeriesOptions,
+  type SeriesSyncState,
+  type TimePoint,
+  syncSeriesLayer,
+} from '@wick-charts/core';
 
 import { useChartInstance } from './context';
 
@@ -13,30 +19,19 @@ export interface LineSeriesProps {
   id?: string;
 }
 
-/** Only fall back to a full `setSeriesData` replace when more than this many new
- * points appear in a single tick — otherwise streamed updates would always look
- * like bulk loads and the renderer would clear its entrance-animation entries. */
-const BULK_THRESHOLD = 20;
-
 export function LineSeries({ data, options, id: idProp }: LineSeriesProps) {
   const chart = useChartInstance();
   const seriesRef = useRef<string | null>(null);
-  const prevLensRef = useRef<number[]>([]);
-  const prevFirstTimesRef = useRef<(number | null)[]>([]);
-  const prevLastTimesRef = useRef<(number | null)[]>([]);
+  const prevSyncRef = useRef<SeriesSyncState[]>([]);
 
   useLayoutEffect(() => {
-    const id = chart.addLineSeries({ ...options, layers: data.length, id: idProp });
+    const id = chart.addSeries('line', { ...options, layers: data.length, id: idProp });
     seriesRef.current = id;
-    prevLensRef.current = new Array(data.length).fill(0);
-    prevFirstTimesRef.current = new Array(data.length).fill(null);
-    prevLastTimesRef.current = new Array(data.length).fill(null);
+    prevSyncRef.current = new Array(data.length).fill(EMPTY_SYNC_STATE);
     return () => {
       chart.removeSeries(id);
       seriesRef.current = null;
-      prevLensRef.current = [];
-      prevFirstTimesRef.current = [];
-      prevLastTimesRef.current = [];
+      prevSyncRef.current = [];
     };
   }, [chart, data.length, idProp]);
 
@@ -46,44 +41,13 @@ export function LineSeries({ data, options, id: idProp }: LineSeriesProps) {
 
     chart.batch(() => {
       for (let i = 0; i < data.length; i++) {
-        const layer = data[i];
-        const prevLen = prevLensRef.current[i] ?? 0;
-        const prevFirst = prevFirstTimesRef.current[i] ?? null;
-
-        if (layer.length === 0) {
-          chart.setSeriesData(id, [], i);
-          prevLensRef.current[i] = 0;
-          prevFirstTimesRef.current[i] = null;
-          prevLastTimesRef.current[i] = null;
-          continue;
-        }
-
-        const firstTime = normalizeTime(layer[0].time);
-        const lastTime = normalizeTime(layer[layer.length - 1].time);
-        const prevLast = prevLastTimesRef.current[i] ?? null;
-        const shifted = prevFirst !== null && prevFirst !== firstTime;
-        const added = layer.length - prevLen;
-        const hasNewLast = prevLast !== null && prevLast !== lastTime;
-
-        // Rolling-window slide (maxPoints cap): drop oldest, append newest,
-        // length unchanged. Sync prefix then appendData the new tail so the
-        // entrance animation fires instead of getting wiped by setSeriesData.
-        if (shifted && added === 0 && hasNewLast) {
-          chart.setSeriesData(id, layer.slice(0, -1), i);
-          chart.appendData(id, layer[layer.length - 1], i);
-        } else if (prevLen === 0 || layer.length < prevLen || added > BULK_THRESHOLD || shifted) {
-          chart.setSeriesData(id, layer, i);
-        } else if (layer.length === prevLen) {
-          chart.updateData(id, layer[layer.length - 1], i);
-        } else {
-          for (let j = prevLen; j < layer.length; j++) {
-            chart.appendData(id, layer[j], i);
-          }
-        }
-
-        prevLensRef.current[i] = layer.length;
-        prevFirstTimesRef.current[i] = firstTime;
-        prevLastTimesRef.current[i] = lastTime;
+        prevSyncRef.current[i] = syncSeriesLayer({
+          chart,
+          id,
+          data: data[i],
+          prev: prevSyncRef.current[i] ?? EMPTY_SYNC_STATE,
+          layerIndex: i,
+        });
       }
     });
   }, [chart, data]);
@@ -101,9 +65,7 @@ export function LineSeries({ data, options, id: idProp }: LineSeriesProps) {
     options?.pulse,
     options?.stacking,
     options?.entryAnimation,
-    options?.enterAnimation,
     options?.entryMs,
-    options?.enterMs,
     options?.smoothMs,
   ]);
 

package/src/PieSeries.tsx

@@ -19,7 +19,7 @@ export function PieSeries({ data, options, id: idProp }: PieSeriesProps) {
   const seriesRef = useRef<string | null>(null);
 
   useLayoutEffect(() => {
-    const id = chart.addPieSeries({ ...options, id: idProp });
+    const id = chart.addSeries('pie', { ...options, id: idProp });
     seriesRef.current = id;
     return () => {
       chart.removeSeries(id);
@@ -48,7 +48,6 @@ export function PieSeries({ data, options, id: idProp }: PieSeriesProps) {
     options?.sliceLabels?.labelGap,
     options?.sliceLabels?.distance,
     options?.sliceLabels?.railWidth,
-    options?.sliceLabels?.balanceSides,
   ]);
 
   useLayoutEffect(() => {

package/src/index.ts

@@ -9,12 +9,12 @@
  */
 
 export type {
+  AnimationTime,
   AnimationsConfig,
   AxisBound,
   AxisConfig,
   BarSeriesOptions,
   /** @deprecated Use {@link StackingMode} instead. */
-  BarStacking,
   BuildHoverSnapshotsArgs,
   BuildLastSnapshotsArgs,
   CandlestickSeriesOptions,
@@ -22,10 +22,12 @@ export type {
   ChartOptions,
   ChartTheme,
   CrosshairPosition,
+  EdgeReachedInfo,
+  EdgeSide,
+  EdgeState,
   HoverInfo,
   LegendItem,
   /** @deprecated Use {@link TimePoint} instead. */
-  LineData,
   LineSeriesOptions,
   NavigatorCandlePoint,
   NavigatorControllerParams,
@@ -51,6 +53,9 @@ export type {
   TooltipFormatter,
   TooltipPosition,
   TooltipPositionArgs,
+  Transition,
+  TransitionContext,
+  TransitionFactory,
   Typography,
   ValueFormatter,
   VisibleRange,
@@ -69,7 +74,6 @@ export {
   catppuccin,
   computeTooltipPosition,
   createTheme,
-  darkTheme,
   detectInterval,
   dracula,
   formatCompact,
@@ -79,10 +83,11 @@ export {
   githubLight,
   gruvbox,
   handwritten,
+  hermite,
   highContrast,
+  isDarkBg,
   lavenderMist,
   lightPink,
-  lightTheme,
   materialPalenight,
   minimalLight,
   mintBreeze,
@@ -91,6 +96,7 @@ export {
   normalizeTime,
   oneDarkPro,
   panda,
+  parseAnimationTime,
   peachCream,
   quietLight,
   resolveAxisFontSize,
@@ -98,7 +104,9 @@ export {
   resolveCandlestickBodyColor,
   rosePineDawn,
   sandDune,
+  snap,
   solarizedLight,
+  spring,
 } from '@wick-charts/core';
 
 export { BarSeries } from './BarSeries';
@@ -107,6 +115,8 @@ export { CandlestickSeries } from './CandlestickSeries';
 export { ChartContainer } from './ChartContainer';
 // React hooks
 export { useChartInstance } from './context';
+export type { EdgeLoaderProps, EdgeLoaderRenderArgs } from './EdgeLoader';
+export { EdgeLoader } from './EdgeLoader';
 export { LineSeries } from './LineSeries';
 export { PieSeries } from './PieSeries';
 export {

package/src/ui/Crosshair.tsx

@@ -11,6 +11,10 @@ export function Crosshair() {
 
   const theme = chart.getTheme();
   const dataInterval = chart.getDataInterval();
+  // Format the time pill at the axis's *resolved* tick granularity, not the raw
+  // data interval — otherwise a time-of-day badge floats among date labels when
+  // zoomed out. Falls back to dataInterval on a degenerate range.
+  const tickInterval = chart.timeScale.niceTickValues(dataInterval).tickInterval || dataInterval;
 
   const labelStyle = {
     // Blend the theme's labelBackground at 80% opacity so the axis grid
@@ -54,7 +58,7 @@ export function Crosshair() {
           ...labelStyle,
         }}
       >
-        {formatTime(position.time, dataInterval)}
+        {formatTime(position.time, tickInterval)}
       </div>
     </>
   );

package/src/ui/InfoBar.tsx

@@ -97,7 +97,41 @@ export function InfoBar({ sort = 'none', format = defaultInfoBarFormat, children
     }
   }
 
-  if (snapshots.length === 0) return null;
+  // No data yet (initial mount, before the first series tick) — render a
+  // zero-content placeholder *for the default UI only* so the header reserves
+  // its real height from the very first paint. Without this the header grows
+  // when InfoBar pops in, ChartContainer's header-measure observer fires
+  // `setPadding`, and the canvas + axes visibly shift down on the next RAF.
+  //
+  // The render-prop variant (`children`) keeps the legacy "return null"
+  // behavior — its layout depends on user-supplied JSX, so we can't
+  // synthesise a meaningful placeholder.
+  if (snapshots.length === 0) {
+    if (children) return null;
+
+    return (
+      <div
+        data-tooltip-legend=""
+        aria-hidden="true"
+        style={{
+          display: 'flex',
+          alignItems: 'center',
+          gap: 4,
+          padding: '4px 8px',
+          flexShrink: 0,
+          fontSize: theme.typography.fontSize,
+          fontFamily: theme.typography.fontFamily,
+          fontVariantNumeric: 'tabular-nums',
+          visibility: 'hidden',
+          pointerEvents: 'none',
+        }}
+      >
+        {/* Non-breaking space keeps line-height intact so the div claims its
+            real rendered height instead of collapsing to padding-only. */}
+        <span>&nbsp;</span>
+      </div>
+    );
+  }
 
   if (children) {
     return (

package/src/ui/Sparkline.tsx

@@ -1,6 +1,12 @@
 import { type CSSProperties, useMemo } from 'react';
 
-import { type ChartTheme, type TimePoint, formatCompact, resolveCandlestickBodyColor } from '@wick-charts/core';
+import {
+  type AxisBound,
+  type ChartTheme,
+  type TimePoint,
+  formatCompact,
+  resolveCandlestickBodyColor,
+} from '@wick-charts/core';
 
 import { BarSeries } from '../BarSeries';
 import { ChartContainer } from '../ChartContainer';
@@ -12,6 +18,23 @@ export type SparklineValuePosition = 'left' | 'right' | 'none';
 export interface SparklineProps {
   /** Data points plotted by the sparkline. A flat `TimePoint[]` — the sparkline only ever shows one tiny line/bar. */
   data: TimePoint[];
+  /**
+   * Streaming-window mode: viewport is fixed at `capacity` bars wide. Pass
+   * at least two seed points in `data` so the initial window can infer the
+   * tick interval.
+   *
+   * `align` controls where the seed sits at mount:
+   * - `'right'` *(default)* — seed flush with the right edge; each tick
+   *   shifts the viewport left by one interval and the new tick lands at
+   *   the right edge.
+   * - `'left'` — seed flush with the left edge; the viewport is held in
+   *   place until empty bars on the right are consumed, then normal
+   *   tail-scroll resumes.
+   * - `'offscreen'` — seed starts one interval past the right edge so the
+   *   first tick's tail-scroll animates it onto canvas (a brief "drive-in"
+   *   effect).
+   */
+  flow?: { capacity: number; align?: 'left' | 'right' | 'offscreen' };
   /** Visual theme. Drives series colour, background gradient, and the change-direction colours used in the value block. */
   theme: ChartTheme;
   /** 'line' (default) or 'bar' */
@@ -35,6 +58,15 @@ export interface SparklineProps {
   };
   /** @deprecated Use {@link area} instead. */
   areaFill?: boolean;
+  /**
+   * Fixed Y-axis bounds. Omit a side (or pass `'auto'`) to keep that edge
+   * auto-scaled. Useful to pin a baseline (`{ min: 0 }`) or hold a stable
+   * window so streaming ticks don't rescale the line.
+   *
+   * Each bound is an {@link AxisBound}: a number, `'auto'`, a percentage
+   * offset string (`'+10%'`), or a `(values) => number` reducer.
+   */
+  yRange?: { min?: AxisBound; max?: AxisBound };
   /** Chart width (default: 140) */
   width?: number;
   /** Overall height (default: 48) */
@@ -77,6 +109,8 @@ export function Sparkline({
   negativeColor,
   area,
   areaFill,
+  yRange,
+  flow,
   width = 140,
   height = 48,
   strokeWidth = 1.5,
@@ -95,6 +129,58 @@ export function Sparkline({
     change.positive ? theme.candlestick.up.body : theme.candlestick.down.body,
   );
 
+  // Previously Sparkline kept its own running min/max in a useRef and handed
+  // a padded Y range to ChartContainer via `axis.y.{min,max}`. That worked
+  // around the chart's default auto-Y "jumps" on streamed wild values, but
+  // it had a hidden cost: every new data prop made the memo emit a fresh
+  // `{min, max}` object, which ChartContainer fed into `chart.setAxis`, and
+  // setAxis SNAPS Y (sets `#yInited = false` and calls `updateYRange(true)`).
+  // Result: every streaming tick snapped Y without animation, which is the
+  // jerky behaviour you saw. The chart core now has sticky-Y bounds + a
+  // `viewportChange` emit on Y advance, so the chart handles streaming
+  // stability itself — Sparkline can drop its local fix.
+
+  // Captured-at-mount viewport for flow mode. Three layouts, see the
+  // `flow.align` docstring on SparklineProps for the user-facing summary.
+  //
+  // - 'left' uses the `{ from, bars }` form, which arms the viewport's
+  //   warm-up hold (#holdUntilFilled) so it stays put while empty bars on
+  //   the right are consumed, then releases to normal tail-scroll.
+  // - 'right' and 'offscreen' use `{ from, to }`, which leaves the hold off
+  //   so tail-scroll kicks in on the first tick. The only difference is
+  //   `to`: at `last` the seed sits flush right; at `last - interval` the
+  //   seed sits one interval past the right edge and the first tick's scroll
+  //   animates it into view.
+  //
+  // Requires at least 2 seed points so `interval` can be inferred; falls
+  // back to undefined otherwise (chart fits to data normally). Subsequent
+  // renders don't recompute because ChartContainer ignores viewport prop
+  // changes after mount.
+  const viewport = useMemo(() => {
+    if (!flow || data.length < 2) return undefined;
+
+    const interval = data[1].time - data[0].time;
+    if (interval <= 0) return undefined;
+
+    const align = flow.align ?? 'right';
+
+    if (align === 'left') {
+      return {
+        maxVisibleBars: flow.capacity,
+        initialRange: { from: data[0].time, bars: flow.capacity } as const,
+      };
+    }
+
+    const last = data[data.length - 1].time;
+    const to = align === 'offscreen' ? last - interval : last;
+    const from = to - flow.capacity * interval;
+
+    return {
+      maxVisibleBars: flow.capacity,
+      initialRange: { from, to } as const,
+    };
+  }, []);
+
   const valueBlock = valuePosition !== 'none' && (
     <div
       style={{
@@ -166,13 +252,19 @@ export function Sparkline({
       <ChartContainer
         theme={theme}
         axis={{
-          y: { visible: false, width: 0 },
+          // `min`/`max` are stable user props (not recomputed per tick), so
+          // ChartContainer's setAxis effect — keyed on the primitive bound
+          // values — only re-applies on an actual change, never per stream
+          // tick. This is why a fixed `yRange` is safe where the old
+          // recompute-every-update min/max was not (see note above).
+          y: { visible: false, width: 0, min: yRange?.min, max: yRange?.max },
           x: { visible: false, height: 0 },
         }}
         padding={{ top: 5, right: 0, bottom: 0, left: 0 }}
         gradient={gradient}
         interactive={false}
         grid={{ visible: false }}
+        viewport={viewport}
       >
         {variant === 'line' ? (
           <LineSeries
@@ -192,6 +284,7 @@ export function Sparkline({
               colors: [resolvedColor, resolvedNegColor],
               barWidthRatio: 0.7,
               stacking: 'off',
+              anchor: 'right',
             }}
           />
         )}

package/src/ui/TimeAxis.tsx

@@ -1,16 +1,9 @@
 import { useLayoutEffect, useRef } from 'react';
 
-import { formatTime, resolveAxisFontSize, resolveAxisTextColor } from '@wick-charts/core';
+import { mountAxisLabels } from '@wick-charts/core';
 
 import { useChartInstance } from '../context';
 import { useVisibleRange } from '../store-bridge';
-import { AXIS_LABEL_CLEANUP_MS, AXIS_LABEL_FADE_CSS } from './axisFade';
-
-interface TrackedTick {
-  opacity: number;
-  addedAt: number;
-  fadedAt?: number;
-}
 
 export interface TimeAxisProps {
   /** Desired number of labels (≥ 2). Overrides chart-level `axis.x.labelCount`. */
@@ -21,7 +14,11 @@ export interface TimeAxisProps {
 
 export function TimeAxis({ labelCount, minLabelSpacing }: TimeAxisProps = {}) {
   const chart = useChartInstance();
-  useVisibleRange(chart); // subscribe to viewport changes so ticks re-render
+  // Subscribe so the container re-renders when chart geometry shifts
+  // (yAxisWidth / xAxisHeight can change on resize, legend mount, etc.).
+  useVisibleRange(chart);
+
+  const containerRef = useRef<HTMLDivElement | null>(null);
 
   useLayoutEffect(() => {
     chart.setTimeAxisLabelDensity({
@@ -33,49 +30,17 @@ export function TimeAxis({ labelCount, minLabelSpacing }: TimeAxisProps = {}) {
       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. Buffer = AXIS_LABEL_FADE_MS + 250
-  // (one transition + a frame margin) so the DOM node sticks around past the
-  // visible fade.
-  for (const [t, entry] of map) {
-    if (entry.opacity === 0 && entry.fadedAt !== undefined && now - entry.fadedAt > AXIS_LABEL_CLEANUP_MS) {
-      map.delete(t);
-    }
-  }
+  useLayoutEffect(() => {
+    const container = containerRef.current;
+    if (container === null) return;
 
-  // Collect all ticks to render (current + fading out)
-  const allTicks = Array.from(map.entries());
+    return mountAxisLabels({ chart, container, axis: 'x' });
+  }, [chart]);
 
   return (
     <div
+      ref={containerRef}
       style={{
         position: 'absolute',
         left: 0,
@@ -86,30 +51,6 @@ export function TimeAxis({ labelCount, minLabelSpacing }: TimeAxisProps = {}) {
         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: AXIS_LABEL_FADE_CSS,
-              willChange: 'opacity',
-            }}
-          >
-            {formatTime(time, tickInterval)}
-          </span>
-        );
-      })}
-    </div>
+    />
   );
 }

package/src/ui/Title.tsx

@@ -1,4 +1,4 @@
-import type { CSSProperties, ReactNode } from 'react';
+import { type CSSProperties, type ReactNode, memo } from 'react';
 
 import { useTheme } from '../ThemeContext';
 
@@ -32,31 +32,35 @@ export interface TitleProps {
  * </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>
-  );
-}
+export const Title = memo(
+  function Title({ children, sub, style }: TitleProps) {
+    const theme = useTheme();
+    return (
+      <div
+        data-chart-title=""
+        style={{
+          display: 'flex',
+          alignItems: 'baseline',
+          gap: 6,
+          padding: '6px 8px 0',
+          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>
+    );
+  },
+  // Explicit comparator: equivalent to default shallow-compare, but avoids the
+  // dev-only Profiler/highlight noise observed with bare `memo` (see
+  // facebook/react#19778).
+  (prev, next) => prev.children === next.children && prev.sub === next.sub && prev.style === next.style,
+);