@ledgerhq/lumen-ui-rnative-visualization 0.1.10 → 0.1.11

package/src/lib/Components/Scrubber/Scrubber.test.tsx

@@ -0,0 +1,110 @@
+import { describe, expect, it } from '@jest/globals';
+import { ledgerLiveThemes } from '@ledgerhq/lumen-design-core';
+import { ThemeProvider } from '@ledgerhq/lumen-ui-rnative';
+import { render } from '@testing-library/react-native';
+import type { ReactNode, ComponentProps } from 'react';
+
+import { CartesianChart } from '../CartesianChart';
+import { ScrubberContextProvider } from './context';
+import { Scrubber } from './Scrubber';
+import type { ScrubberContextValue } from './types';
+
+const sampleSeries = [
+  { id: 's1', stroke: '#7B61FF', data: [10, 20, 30, 40, 50] },
+  { id: 's2', stroke: '#44D7B6', data: [50, 40, 30, 20, 10] },
+];
+
+const Wrapper = ({ children }: { children: ReactNode }) => (
+  <ThemeProvider themes={ledgerLiveThemes} colorScheme='light'>
+    {children}
+  </ThemeProvider>
+);
+
+const activeScrubberContext = {
+  enableScrubbing: true,
+  scrubberPosition: 2,
+  onScrubberPositionChange: () => undefined,
+};
+
+const renderScrubber = ({
+  scrubberProps = {},
+  scrubberContext = activeScrubberContext,
+}: {
+  scrubberProps?: ComponentProps<typeof Scrubber>;
+  scrubberContext?: ScrubberContextValue;
+} = {}) =>
+  render(
+    <Wrapper>
+      <CartesianChart series={sampleSeries} width={400} height={200}>
+        <ScrubberContextProvider value={scrubberContext}>
+          <Scrubber {...scrubberProps} />
+        </ScrubberContextProvider>
+      </CartesianChart>
+    </Wrapper>,
+  );
+
+describe('Scrubber', () => {
+  it('renders nothing when no scrubber position is active', () => {
+    const { queryByTestId } = renderScrubber({
+      scrubberContext: {
+        enableScrubbing: true,
+        scrubberPosition: undefined,
+        onScrubberPositionChange: () => undefined,
+      },
+    });
+    expect(queryByTestId('scrubber')).toBeNull();
+  });
+
+  it('renders the scrubber group when a position is active', () => {
+    const { getByTestId } = renderScrubber();
+    expect(getByTestId('scrubber')).toBeTruthy();
+  });
+
+  it('renders the reference line by default', () => {
+    const { getByTestId } = renderScrubber();
+    expect(getByTestId('scrubber-line')).toBeTruthy();
+  });
+
+  it('hides the reference line when hideLine is true', () => {
+    const { queryByTestId } = renderScrubber({
+      scrubberProps: { hideLine: true },
+    });
+    expect(queryByTestId('scrubber-line')).toBeNull();
+  });
+
+  it('renders the overlay by default', () => {
+    const { getByTestId } = renderScrubber();
+    expect(getByTestId('scrubber-overlay')).toBeTruthy();
+  });
+
+  it('hides the overlay when hideOverlay is true', () => {
+    const { queryByTestId } = renderScrubber({
+      scrubberProps: { hideOverlay: true },
+    });
+    expect(queryByTestId('scrubber-overlay')).toBeNull();
+  });
+
+  it('does not render beacons by default', () => {
+    const { queryAllByTestId } = renderScrubber();
+    expect(queryAllByTestId(/scrubber-beacon-/)).toHaveLength(0);
+  });
+
+  it('renders one beacon per series when showBeacons is true', () => {
+    const { getAllByTestId } = renderScrubber({
+      scrubberProps: { showBeacons: true },
+    });
+    expect(getAllByTestId(/scrubber-beacon-/)).toHaveLength(2);
+  });
+
+  it('renders a label when a label function is provided', () => {
+    const { getByTestId } = renderScrubber({
+      scrubberProps: { label: (i: number) => `Index ${i}` },
+    });
+    expect(getByTestId('scrubber-label')).toBeTruthy();
+  });
+
+  it('does not render a label when no label function is provided', () => {
+    const { queryByTestId } = renderScrubber();
+    expect(queryByTestId('scrubber-label')).toBeNull();
+  });
+});

package/src/lib/Components/Scrubber/Scrubber.tsx

@@ -0,0 +1,189 @@
+import { useTheme } from '@ledgerhq/lumen-ui-rnative';
+import { useId, useMemo } from 'react';
+import {
+  Circle,
+  Defs,
+  G,
+  Line,
+  LinearGradient,
+  Rect,
+  Stop,
+  Text as SvgText,
+} from 'react-native-svg';
+
+import { useCartesianChartContext } from '../CartesianChart/context';
+import {
+  BEACON_RADIUS,
+  BEACON_STROKE_WIDTH,
+  LABEL_OFFSET_Y,
+  LINE_GRADIENT_EDGE_OPACITY,
+  OVERLAY_LINE_INSET,
+  OVERLAY_OFFSET,
+  OVERLAY_OPACITY,
+} from './constants';
+import { useScrubberContext } from './context';
+import type { ScrubberProps } from './types';
+import { resolvePixelX, resolvePixelY } from './utils';
+
+/**
+ * Renders the scrubber visuals: vertical reference line, future-data overlay
+ * rect, per-series beacon dots, and an optional formatted label above the line.
+ *
+ * Must be used as a child of `LineChart` (or `CartesianChart`) with
+ * `enableScrubbing` enabled. Renders nothing when no scrubber position is active.
+ *
+ * @example
+ * ```tsx
+ * <LineChart series={data} enableScrubbing>
+ *   <Scrubber label={(i) => data[i].date} />
+ * </LineChart>
+ * ```
+ */
+export function Scrubber({
+  label,
+  hideLine = false,
+  hideOverlay = false,
+  showBeacons = false,
+}: Readonly<ScrubberProps>) {
+  const lineGradientId = useId();
+  const { theme } = useTheme();
+  const { scrubberPosition } = useScrubberContext();
+  const {
+    getXScale,
+    getXAxisConfig,
+    getYScale,
+    drawingArea,
+    series,
+    seriesMap,
+  } = useCartesianChartContext();
+
+  const pixelX = useMemo(() => {
+    if (scrubberPosition === undefined) return undefined;
+    return resolvePixelX(scrubberPosition, getXScale, getXAxisConfig());
+  }, [scrubberPosition, getXScale, getXAxisConfig]);
+
+  const beacons = useMemo(() => {
+    if (scrubberPosition === undefined || !showBeacons) return [];
+    return series
+      .map((s) => {
+        const seriesData = seriesMap.get(s.id)?.data;
+        const pixelY = resolvePixelY(scrubberPosition, seriesData, getYScale);
+        if (pixelY === undefined) return null;
+        return { id: s.id, stroke: s.stroke, pixelY };
+      })
+      .filter(
+        (b): b is { id: string; stroke: string; pixelY: number } => b !== null,
+      );
+  }, [scrubberPosition, showBeacons, series, seriesMap, getYScale]);
+
+  const resolvedLabel = useMemo(() => {
+    if (scrubberPosition === undefined || !label) return undefined;
+    return label(scrubberPosition);
+  }, [scrubberPosition, label]);
+
+  if (scrubberPosition === undefined || pixelX === undefined) {
+    return null;
+  }
+
+  const {
+    x: drawX,
+    y: drawY,
+    width: drawWidth,
+    height: drawHeight,
+  } = drawingArea;
+
+  const overlayX = pixelX + OVERLAY_LINE_INSET;
+  const overlayY = drawY - OVERLAY_OFFSET;
+  const overlayWidth = Math.max(
+    0,
+    drawX + drawWidth - pixelX - OVERLAY_LINE_INSET + OVERLAY_OFFSET,
+  );
+  const overlayHeight = drawHeight + OVERLAY_OFFSET * 2;
+
+  const borderMutedColor = theme.colors.border.base;
+  const backgroundBaseColor = theme.colors.bg.base;
+  const textBaseColor = theme.colors.text.base;
+  const bgCanvasColor = theme.colors.bg.canvas;
+
+  return (
+    <G testID='scrubber'>
+      {!hideLine && (
+        <>
+          <Defs>
+            <LinearGradient
+              id={lineGradientId}
+              gradientUnits='userSpaceOnUse'
+              x1={pixelX}
+              y1={drawY}
+              x2={pixelX}
+              y2={drawY + drawHeight}
+            >
+              <Stop
+                offset='0%'
+                stopColor={borderMutedColor}
+                stopOpacity={LINE_GRADIENT_EDGE_OPACITY}
+              />
+              <Stop offset='20%' stopColor={borderMutedColor} stopOpacity={1} />
+              <Stop offset='80%' stopColor={borderMutedColor} stopOpacity={1} />
+              <Stop
+                offset='100%'
+                stopColor={borderMutedColor}
+                stopOpacity={LINE_GRADIENT_EDGE_OPACITY}
+              />
+            </LinearGradient>
+          </Defs>
+          <Line
+            testID='scrubber-line'
+            x1={pixelX}
+            y1={drawY}
+            x2={pixelX}
+            y2={drawY + drawHeight}
+            stroke={`url(#${lineGradientId})`}
+            strokeWidth={OVERLAY_LINE_INSET}
+          />
+        </>
+      )}
+
+      {!hideOverlay && (
+        <Rect
+          testID='scrubber-overlay'
+          x={overlayX}
+          y={overlayY}
+          width={overlayWidth}
+          height={overlayHeight}
+          fill={backgroundBaseColor}
+          opacity={OVERLAY_OPACITY}
+        />
+      )}
+
+      {resolvedLabel !== undefined && (
+        <SvgText
+          testID='scrubber-label'
+          x={pixelX}
+          y={drawY - LABEL_OFFSET_Y}
+          textAnchor='middle'
+          fill={textBaseColor}
+          fontSize={theme.typographies.body4.fontSize}
+          fontWeight={theme.typographies.body4.fontWeight}
+          fontFamily={theme.fontFamilies.sans}
+        >
+          {resolvedLabel}
+        </SvgText>
+      )}
+
+      {showBeacons &&
+        beacons.map((beacon) => (
+          <Circle
+            key={beacon.id}
+            testID={`scrubber-beacon-${beacon.id}`}
+            cx={pixelX}
+            cy={beacon.pixelY}
+            r={BEACON_RADIUS}
+            fill={beacon.stroke}
+            stroke={bgCanvasColor}
+            strokeWidth={BEACON_STROKE_WIDTH}
+          />
+        ))}
+    </G>
+  );
+}

package/src/lib/Components/Scrubber/ScrubberProvider.test.tsx

@@ -0,0 +1,223 @@
+import { describe, expect, it, jest } from '@jest/globals';
+import { ledgerLiveThemes } from '@ledgerhq/lumen-design-core';
+import { ThemeProvider } from '@ledgerhq/lumen-ui-rnative';
+import { fireEvent, render } from '@testing-library/react-native';
+import type { ReactNode } from 'react';
+import { Pressable, Text } from 'react-native';
+
+import { CartesianChart } from '../CartesianChart';
+import { useScrubberContext } from './context';
+
+const sampleSeries = [
+  { id: 's1', stroke: '#7B61FF', data: [10, 20, 30, 40, 50] },
+];
+
+const Wrapper = ({ children }: { children: ReactNode }) => (
+  <ThemeProvider themes={ledgerLiveThemes} colorScheme='light'>
+    {children}
+  </ThemeProvider>
+);
+
+const ContextConsumer = () => {
+  const { scrubberPosition, enableScrubbing } = useScrubberContext();
+  return (
+    <Text testID='context-output'>
+      {`enabled:${enableScrubbing},pos:${scrubberPosition ?? 'none'}`}
+    </Text>
+  );
+};
+
+describe('ScrubberProvider', () => {
+  it('renders children', () => {
+    const { getByTestId } = render(
+      <Wrapper>
+        <CartesianChart
+          series={sampleSeries}
+          width={400}
+          height={200}
+          enableScrubbing={true}
+        >
+          <Text testID='child'>hello</Text>
+        </CartesianChart>
+      </Wrapper>,
+    );
+    expect(getByTestId('child')).toBeTruthy();
+  });
+
+  it('renders the long-press + pan gesture overlay when enableScrubbing is true', () => {
+    const { getByTestId } = render(
+      <Wrapper>
+        <CartesianChart
+          series={sampleSeries}
+          width={400}
+          height={200}
+          enableScrubbing={true}
+        >
+          <Text>child</Text>
+        </CartesianChart>
+      </Wrapper>,
+    );
+    expect(getByTestId('scrubber-gesture-overlay')).toBeTruthy();
+  });
+
+  it('does not render the gesture overlay when enableScrubbing is false', () => {
+    const { queryByTestId } = render(
+      <Wrapper>
+        <CartesianChart
+          series={sampleSeries}
+          width={400}
+          height={200}
+          enableScrubbing={false}
+        >
+          <Text>child</Text>
+        </CartesianChart>
+      </Wrapper>,
+    );
+    expect(queryByTestId('scrubber-gesture-overlay')).toBeNull();
+  });
+
+  it('provides initial scrubberPosition as undefined via context', () => {
+    const { getByTestId } = render(
+      <Wrapper>
+        <CartesianChart
+          series={sampleSeries}
+          width={400}
+          height={200}
+          enableScrubbing={true}
+        >
+          <ContextConsumer />
+        </CartesianChart>
+      </Wrapper>,
+    );
+    expect(getByTestId('context-output').props.children).toBe(
+      'enabled:true,pos:none',
+    );
+  });
+
+  it('calls onScrubberPositionChange when position is updated via context', () => {
+    const onScrubberPositionChange = jest.fn();
+
+    const ContextTrigger = () => {
+      const { onScrubberPositionChange: updatePosition } = useScrubberContext();
+      return (
+        <>
+          <Pressable testID='set-position' onPress={() => updatePosition(2)} />
+          <Pressable
+            testID='clear-position'
+            onPress={() => updatePosition(undefined)}
+          />
+        </>
+      );
+    };
+
+    const { getByTestId } = render(
+      <Wrapper>
+        <CartesianChart
+          series={sampleSeries}
+          width={400}
+          height={200}
+          enableScrubbing={true}
+          onScrubberPositionChange={onScrubberPositionChange}
+        >
+          <ContextTrigger />
+        </CartesianChart>
+      </Wrapper>,
+    );
+
+    fireEvent.press(getByTestId('set-position'));
+    expect(onScrubberPositionChange).toHaveBeenCalledWith(2);
+
+    fireEvent.press(getByTestId('clear-position'));
+    expect(onScrubberPositionChange).toHaveBeenCalledWith(undefined);
+    expect(onScrubberPositionChange).toHaveBeenCalledTimes(2);
+  });
+
+  it('does not fire onScrubberPositionChange when the index is unchanged', () => {
+    const onScrubberPositionChange = jest.fn();
+
+    const ContextTrigger = () => {
+      const { onScrubberPositionChange: updatePosition } = useScrubberContext();
+      return (
+        <Pressable testID='set-position' onPress={() => updatePosition(2)} />
+      );
+    };
+
+    const { getByTestId } = render(
+      <Wrapper>
+        <CartesianChart
+          series={sampleSeries}
+          width={400}
+          height={200}
+          enableScrubbing={true}
+          onScrubberPositionChange={onScrubberPositionChange}
+        >
+          <ContextTrigger />
+        </CartesianChart>
+      </Wrapper>,
+    );
+
+    fireEvent.press(getByTestId('set-position'));
+    fireEvent.press(getByTestId('set-position'));
+    fireEvent.press(getByTestId('set-position'));
+    expect(onScrubberPositionChange).toHaveBeenCalledTimes(1);
+  });
+
+  it('clamps out-of-range index set via context', () => {
+    const onScrubberPositionChange = jest.fn();
+
+    const ContextTrigger = () => {
+      const { onScrubberPositionChange: updatePosition } = useScrubberContext();
+      return (
+        <Pressable testID='set-position' onPress={() => updatePosition(999)} />
+      );
+    };
+
+    const { getByTestId } = render(
+      <Wrapper>
+        <CartesianChart
+          series={sampleSeries}
+          width={400}
+          height={200}
+          enableScrubbing={true}
+          onScrubberPositionChange={onScrubberPositionChange}
+        >
+          <ContextTrigger />
+        </CartesianChart>
+      </Wrapper>,
+    );
+
+    fireEvent.press(getByTestId('set-position'));
+    expect(onScrubberPositionChange).toHaveBeenCalledWith(
+      sampleSeries[0].data.length - 1,
+    );
+  });
+
+  it('does not fire callback when dataLength is 0', () => {
+    const onScrubberPositionChange = jest.fn();
+    const emptySeries = [{ id: 's1', stroke: '#7B61FF', data: [] as number[] }];
+
+    const ContextTrigger = () => {
+      const { onScrubberPositionChange: updatePosition } = useScrubberContext();
+      return (
+        <Pressable testID='set-position' onPress={() => updatePosition(0)} />
+      );
+    };
+
+    const { getByTestId } = render(
+      <Wrapper>
+        <CartesianChart
+          series={emptySeries}
+          width={400}
+          height={200}
+          enableScrubbing={true}
+          onScrubberPositionChange={onScrubberPositionChange}
+        >
+          <ContextTrigger />
+        </CartesianChart>
+      </Wrapper>,
+    );
+
+    fireEvent.press(getByTestId('set-position'));
+    expect(onScrubberPositionChange).not.toHaveBeenCalled();
+  });
+});

package/src/lib/Components/Scrubber/ScrubberProvider.tsx

@@ -0,0 +1,132 @@
+import { useCallback, useMemo, useRef, useState } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import Animated, { useSharedValue } from 'react-native-reanimated';
+import { scheduleOnRN } from 'react-native-worklets';
+
+import { useCartesianChartContext } from '../CartesianChart/context';
+import { ScrubberContextProvider } from './context';
+import type { ScrubberProviderProps } from './types';
+import { getDataIndexFromPosition } from './utils';
+
+/**
+ * Provides scrubbing interaction for a chart.
+ *
+ * Must be placed as a child of `CartesianChartProvider` (so it can access the
+ * x-scale) but outside the `<Svg>` element (so it can render a transparent
+ * gesture-capture `View` overlay). `CartesianChart` handles this positioning
+ * automatically when `enableScrubbing` is true.
+ *
+ * Activation requires a 50 ms long press before panning begins. This prevents
+ * accidental scrubbing when the user is scrolling a parent `ScrollView` or
+ * `FlatList`. The `isScrubbing` shared value gates the pan via manual activation
+ * so scroll and scrub gestures never compete.
+ */
+export function ScrubberProvider({
+  children,
+  width,
+  height,
+  enableScrubbing,
+  onScrubberPositionChange,
+}: Readonly<ScrubberProviderProps>) {
+  const [scrubberPosition, setScrubberPosition] = useState<
+    number | undefined
+  >();
+  const lastPositionRef = useRef<number | undefined>(undefined);
+
+  const { getXScale, getXAxisConfig, dataLength } = useCartesianChartContext();
+
+  const isScrubbing = useSharedValue(false);
+
+  const setScrubberPositionAndNotify = useCallback(
+    (index: number | undefined) => {
+      const clamped =
+        index === undefined || dataLength <= 0
+          ? undefined
+          : Math.max(0, Math.min(index, dataLength - 1));
+      if (clamped === lastPositionRef.current) return;
+      lastPositionRef.current = clamped;
+      setScrubberPosition(clamped);
+      onScrubberPositionChange?.(clamped);
+    },
+    [dataLength, onScrubberPositionChange],
+  );
+
+  const handlePositionChange = useCallback(
+    (pixelX: number | null) => {
+      if (pixelX === null) {
+        setScrubberPositionAndNotify(undefined);
+        return;
+      }
+
+      const scale = getXScale();
+      if (!scale || dataLength <= 0) return;
+
+      const axisConfig = getXAxisConfig();
+      const index = getDataIndexFromPosition(
+        pixelX,
+        scale,
+        axisConfig,
+        dataLength,
+      );
+      setScrubberPositionAndNotify(index);
+    },
+    [getXScale, getXAxisConfig, dataLength, setScrubberPositionAndNotify],
+  );
+
+  const resetScrubber = useCallback((): void => {
+    'worklet';
+    isScrubbing.value = false;
+    scheduleOnRN(handlePositionChange, null);
+  }, [isScrubbing, handlePositionChange]);
+
+  const composed = useMemo(() => {
+    const longPress = Gesture.LongPress()
+      .minDuration(50)
+      .onStart((e) => {
+        'worklet';
+        isScrubbing.value = true;
+        scheduleOnRN(handlePositionChange, e.x);
+      });
+
+    const pan = Gesture.Pan()
+      .manualActivation(true)
+      .onTouchesMove((_, manager) => {
+        'worklet';
+        if (isScrubbing.value) manager.activate();
+      })
+      .onUpdate((e) => {
+        'worklet';
+        scheduleOnRN(handlePositionChange, e.x);
+      })
+      .onEnd(resetScrubber)
+      .onFinalize(resetScrubber);
+
+    return Gesture.Simultaneous(longPress, pan);
+  }, [isScrubbing, handlePositionChange, resetScrubber]);
+
+  const contextValue = useMemo(
+    () => ({
+      enableScrubbing,
+      scrubberPosition,
+      onScrubberPositionChange: setScrubberPositionAndNotify,
+    }),
+    [enableScrubbing, scrubberPosition, setScrubberPositionAndNotify],
+  );
+
+  return (
+    <ScrubberContextProvider value={contextValue}>
+      <View style={{ width, height }}>
+        {children}
+        {enableScrubbing && (
+          <GestureDetector gesture={composed}>
+            <Animated.View
+              testID='scrubber-gesture-overlay'
+              style={StyleSheet.absoluteFill}
+            />
+          </GestureDetector>
+        )}
+      </View>
+    </ScrubberContextProvider>
+  );
+}

package/src/lib/Components/Scrubber/constants.ts

@@ -0,0 +1,7 @@
+export const BEACON_RADIUS = 5;
+export const BEACON_STROKE_WIDTH = 2;
+export const LABEL_OFFSET_Y = 12;
+export const OVERLAY_OFFSET = 2;
+export const OVERLAY_LINE_INSET = 0.5;
+export const OVERLAY_OPACITY = 0.8;
+export const LINE_GRADIENT_EDGE_OPACITY = 0.1;

package/src/lib/Components/Scrubber/context/index.ts

@@ -0,0 +1 @@
+export { ScrubberContextProvider, useScrubberContext } from './scrubberContext';

package/src/lib/Components/Scrubber/context/scrubberContext.ts

@@ -0,0 +1,14 @@
+import { createSafeContext } from '@ledgerhq/lumen-utils-shared';
+
+import type { ScrubberContextValue } from '../types';
+
+const [ScrubberContextProvider, _useScrubberSafeContext] =
+  createSafeContext<ScrubberContextValue>('Scrubber');
+
+export const useScrubberContext = (): ScrubberContextValue =>
+  _useScrubberSafeContext({
+    consumerName: 'useScrubberContext',
+    contextRequired: true,
+  });
+
+export { ScrubberContextProvider };

package/src/lib/Components/Scrubber/index.ts

@@ -0,0 +1,3 @@
+export { Scrubber } from './Scrubber';
+export { useScrubberContext } from './context';
+export type { ScrubberProps, ScrubberContextValue } from './types';