@ledgerhq/lumen-ui-rnative-visualization 0.1.14 → 0.1.15

package/src/lib/Components/Point/utils.test.ts

@@ -1,14 +1,14 @@
-import { describe, expect, it } from '@jest/globals';
+import { describe, expect, it, jest } from '@jest/globals';
+import { renderHook } from '@testing-library/react-native';
 
+import type { BaseAxisProps } from '../Axis';
+import { ARROW_HEIGHT, ARROW_WIDTH, GAP, LABEL_FONT_SIZE } from './constants';
 import {
-  ARROW_HEIGHT,
-  ARROW_WIDTH,
   buildArrowPoints,
   computeLabelY,
-  GAP,
   isWithinBounds,
-  LABEL_FONT_SIZE,
   resolveLabel,
+  useMagneticRegistration,
 } from './utils';
 
 describe('isWithinBounds', () => {
@@ -116,3 +116,93 @@ describe('computeLabelY', () => {
     expect(result).toBe(pixelY + radius + GAP + GAP + LABEL_FONT_SIZE);
   });
 });
+
+const makeContext = () => ({
+  register: jest.fn(),
+  unregister: jest.fn(),
+  version: 0,
+  getMagneticPoints: () => new Set<number>(),
+});
+
+const noAxisConfig = (): BaseAxisProps | undefined => undefined;
+
+describe('useMagneticRegistration', () => {
+  it('registers the data index when magnetic is true', () => {
+    const ctx = makeContext();
+    renderHook(() => useMagneticRegistration(true, 3, noAxisConfig, ctx));
+
+    expect(ctx.register).toHaveBeenCalledWith(3);
+  });
+
+  it('does not register when magnetic is false', () => {
+    const ctx = makeContext();
+    renderHook(() => useMagneticRegistration(false, 3, noAxisConfig, ctx));
+
+    expect(ctx.register).not.toHaveBeenCalled();
+  });
+
+  it('unregisters on unmount', () => {
+    const ctx = makeContext();
+    const { unmount } = renderHook(() =>
+      useMagneticRegistration(true, 3, noAxisConfig, ctx),
+    );
+
+    unmount();
+    expect(ctx.unregister).toHaveBeenCalledWith(3);
+  });
+
+  it('resolves dataX through axis config data when provided', () => {
+    const ctx = makeContext();
+    const getXAxisConfig = (): BaseAxisProps => ({
+      scaleType: 'band',
+      data: [100, 200, 300],
+    });
+
+    renderHook(() => useMagneticRegistration(true, 200, getXAxisConfig, ctx));
+
+    expect(ctx.register).toHaveBeenCalledWith(1);
+  });
+
+  it('does not register when axis data exists but does not contain the value', () => {
+    const ctx = makeContext();
+    const getXAxisConfig = (): BaseAxisProps => ({
+      scaleType: 'band',
+      data: [100, 200, 300],
+    });
+
+    renderHook(() => useMagneticRegistration(true, 999, getXAxisConfig, ctx));
+
+    expect(ctx.register).not.toHaveBeenCalled();
+  });
+
+  it('re-registers when dataX changes', () => {
+    const ctx = makeContext();
+    const { rerender } = renderHook(
+      ({ dataX }: { dataX: number }) =>
+        useMagneticRegistration(true, dataX, noAxisConfig, ctx),
+      { initialProps: { dataX: 2 } },
+    );
+
+    expect(ctx.register).toHaveBeenCalledWith(2);
+
+    rerender({ dataX: 4 });
+
+    expect(ctx.unregister).toHaveBeenCalledWith(2);
+    expect(ctx.register).toHaveBeenCalledWith(4);
+  });
+
+  it('unregisters and stops when magnetic switches to false', () => {
+    const ctx = makeContext();
+    const { rerender } = renderHook(
+      ({ magnetic }: { magnetic: boolean }) =>
+        useMagneticRegistration(magnetic, 3, noAxisConfig, ctx),
+      { initialProps: { magnetic: true } },
+    );
+
+    expect(ctx.register).toHaveBeenCalledWith(3);
+
+    rerender({ magnetic: false });
+
+    expect(ctx.unregister).toHaveBeenCalledWith(3);
+  });
+});

package/src/lib/Components/Point/utils.ts

@@ -1,11 +1,9 @@
-import type { DrawingArea } from '../../utils/types';
+import { useEffect } from 'react';
 
-export const DEFAULT_SIZE = 10;
-export const STROKE_WIDTH = 2;
-export const LABEL_FONT_SIZE = 10;
-export const ARROW_WIDTH = 6;
-export const ARROW_HEIGHT = 4;
-export const GAP = 4;
+import type { DrawingArea } from '../../utils/types';
+import type { BaseAxisProps } from '../Axis';
+import { LABEL_FONT_SIZE, ARROW_WIDTH, ARROW_HEIGHT, GAP } from './constants';
+import type { MagneticPointsContextValue } from './pointContext/magneticPointsContext';
 
 export const isWithinBounds = (
   px: number,
@@ -53,6 +51,36 @@ export const resolveLabel = (
   return resolved === '' ? undefined : resolved;
 };
 
+export const resolveDataXToIndex = (
+  dataX: number,
+  axisConfig: BaseAxisProps | undefined,
+): number | undefined => {
+  const axisData = axisConfig?.data;
+  if (!axisData || typeof axisData[0] !== 'number') return dataX;
+  const index = (axisData as number[]).indexOf(dataX);
+  if (index === -1) return undefined;
+  return index;
+};
+
+/**
+ * Registers/unregisters a data index as a magnetic snap target
+ * when the Point has `magnetic` enabled.
+ */
+export const useMagneticRegistration = (
+  magnetic: boolean,
+  dataX: number,
+  getXAxisConfig: () => BaseAxisProps | undefined,
+  { register, unregister }: MagneticPointsContextValue,
+): void => {
+  useEffect(() => {
+    if (!magnetic) return;
+    const index = resolveDataXToIndex(dataX, getXAxisConfig());
+    if (index === undefined) return;
+    register(index);
+    return () => unregister(index);
+  }, [magnetic, dataX, getXAxisConfig, register, unregister]);
+};
+
 /**
  * Computes the vertical position of the label text baseline.
  */

package/src/lib/Components/ReferenceLine/utils.ts

@@ -1,9 +1,6 @@
 import { getPointOnScale, isCategoricalScale } from '../../utils/scales/scales';
-import type {
-  AxisConfigProps,
-  ChartScaleFunction,
-  DrawingArea,
-} from '../../utils/types';
+import type { ChartScaleFunction, DrawingArea } from '../../utils/types';
+import type { BaseAxisProps } from '../Axis';
 
 import type { LabelAlignment, LabelPosition } from './types';
 
@@ -28,7 +25,7 @@ type ResolvePixelParams = {
   scale: ChartScaleFunction | undefined;
   axis: 'x' | 'y';
   drawingArea: DrawingArea;
-  axisConfig?: AxisConfigProps;
+  axisConfig?: BaseAxisProps;
 };
 
 type LabelParams = {
@@ -95,7 +92,7 @@ export const isPixelWithinDrawingArea = (
  */
 const resolveDataValue = (
   index: number,
-  axisConfig?: AxisConfigProps,
+  axisConfig?: BaseAxisProps,
 ): number | undefined => {
   const data = axisConfig?.data;
   if (!data || data.length === 0) return index;

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

@@ -148,7 +148,7 @@ describe('DefaultScrubberTooltip', () => {
         scrubberProps: { tooltip: defaultTooltip },
         scrubberContext: scrubberAt(2),
       });
-      expect(getByTestId('chart-tooltip-rect').props.x).toBe(210);
+      expect(getByTestId('chart-tooltip-rect').props.x).toBe(260);
     });
 
     it('flips tooltip left when right side would overflow (index 3)', () => {
@@ -158,7 +158,7 @@ describe('DefaultScrubberTooltip', () => {
         },
         scrubberContext: scrubberAt(3),
       });
-      expect(getByTestId('chart-tooltip-rect').props.x).toBe(145);
+      expect(getByTestId('chart-tooltip-rect').props.x).toBe(220);
     });
 
     it('flips at the rightmost scrubber position (index 4)', () => {
@@ -168,7 +168,7 @@ describe('DefaultScrubberTooltip', () => {
         },
         scrubberContext: scrubberAt(4),
       });
-      expect(getByTestId('chart-tooltip-rect').props.x).toBe(220);
+      expect(getByTestId('chart-tooltip-rect').props.x).toBe(320);
     });
 
     it('custom offset shifts the no-flip tooltip position', () => {
@@ -178,7 +178,7 @@ describe('DefaultScrubberTooltip', () => {
         },
         scrubberContext: scrubberAt(2),
       });
-      expect(getByTestId('chart-tooltip-rect').props.x).toBe(220);
+      expect(getByTestId('chart-tooltip-rect').props.x).toBe(270);
     });
 
     it('wider minWidth can trigger a flip that the default width would not', () => {

package/src/lib/Components/Scrubber/DefaultScrubberTooltip/utils.test.ts

@@ -192,7 +192,7 @@ describe('measureWidths', () => {
       titleRef,
       labelRefs,
       valueRefs,
-    );
+    ).promise;
 
     expect(result).toEqual({ title: 50, labels: [30], values: [20] });
     raf.mockRestore();
@@ -212,7 +212,7 @@ describe('measureWidths', () => {
       titleRef,
       labelRefs,
       valueRefs,
-    );
+    ).promise;
 
     expect(result.title).toBe(0);
     raf.mockRestore();
@@ -235,7 +235,7 @@ describe('measureWidths', () => {
       titleRef,
       labelRefs,
       valueRefs,
-    );
+    ).promise;
 
     expect(result.labels).toEqual([10, 20]);
     expect(result.values).toEqual([5, 15]);
@@ -256,7 +256,7 @@ describe('measureWidths', () => {
       titleRef,
       labelRefs,
       valueRefs,
-    );
+    ).promise;
 
     expect(result).toEqual({ title: 0, labels: [0], values: [0] });
     raf.mockRestore();

package/src/lib/Components/Scrubber/DefaultScrubberTooltip/utils.ts

@@ -107,29 +107,41 @@ export const computeItemsBaseY = (
   return drawingAreaY + PADDING_Y + titleBlockHeight;
 };
 
-const waitForAnimationFrame = (): Promise<void> =>
-  new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+const waitForAnimationFrame = (): {
+  promise: Promise<void>;
+  cancel: () => void;
+} => {
+  let id: number;
+  const promise = new Promise<void>((resolve) => {
+    id = requestAnimationFrame(() => resolve());
+  });
+  return { promise, cancel: () => cancelAnimationFrame(id) };
+};
 
 /**
  * Reads the rendered widths of all tooltip text elements via async `getBBox`.
  * Defers until the next animation frame so layout has settled.
+ * Returns a cancel function so callers can abort the pending RAF.
  */
-export const measureWidths = async (
+export const measureWidths = (
   items: ChartTooltipItemData[],
   hasTitle: boolean,
   titleRef: RefObject<SvgBBoxElement | null>,
   labelRefs: RefObject<(SvgBBoxElement | null)[]>,
   valueRefs: RefObject<(SvgBBoxElement | null)[]>,
-): Promise<Widths> => {
-  await waitForAnimationFrame();
-  const title = hasTitle ? await safeGetBBoxWidth(titleRef.current) : 0;
-  const labels = await Promise.all(
-    items.map((_, i) => safeGetBBoxWidth(labelRefs.current[i])),
-  );
-  const values = await Promise.all(
-    items.map((_, i) => safeGetBBoxWidth(valueRefs.current[i])),
-  );
-  return { title, labels, values };
+): { promise: Promise<Widths>; cancel: () => void } => {
+  const raf = waitForAnimationFrame();
+  const promise = raf.promise.then(async () => {
+    const title = hasTitle ? await safeGetBBoxWidth(titleRef.current) : 0;
+    const labels = await Promise.all(
+      items.map((_, i) => safeGetBBoxWidth(labelRefs.current[i])),
+    );
+    const values = await Promise.all(
+      items.map((_, i) => safeGetBBoxWidth(valueRefs.current[i])),
+    );
+    return { title, labels, values };
+  });
+  return { promise, cancel: raf.cancel };
 };
 
 /**
@@ -186,18 +198,20 @@ export function useTooltipMeasurement(
 
     let cancelled = false;
 
-    void measureWidths(
+    const { promise, cancel } = measureWidths(
       itemsRef.current,
       hasTitleRef.current,
       titleRef,
       labelRefs,
       valueRefs,
-    ).then((result) => {
+    );
+    void promise.then((result) => {
       if (!cancelled) setWidths(result);
     });
 
     return () => {
       cancelled = true;
+      cancel();
     };
   }, [shapeKey]);
 

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

@@ -5,9 +5,15 @@ import Animated, { useSharedValue } from 'react-native-reanimated';
 import { scheduleOnRN } from 'react-native-worklets';
 
 import { useCartesianChartContext } from '../CartesianChart/context';
+import { useMagneticPointsContext } from '../Point/pointContext';
 import { ScrubberContextProvider } from './context';
 import type { ScrubberProviderProps } from './types';
-import { getDataIndexFromPosition } from './utils';
+import {
+  applyMagnetisation,
+  getDataIndexFromPosition,
+  resolvePixelX,
+  buildSortedMagnets,
+} from './utils';
 
 const LONG_PRESS_MIN_DURATION_MS = 50;
 
@@ -30,29 +36,46 @@ export function ScrubberProvider({
   height,
   enableScrubbing,
   onScrubberPositionChange,
+  magnetRadius = 6,
+  style,
 }: Readonly<ScrubberProviderProps>) {
   const [scrubberPosition, setScrubberPosition] = useState<
     number | undefined
   >();
 
   const { getXScale, getXAxisConfig, dataLength } = useCartesianChartContext();
+  const { getMagneticPoints, version } = useMagneticPointsContext();
 
   // All values touched by the gesture's JS-thread callback live in a single
   // ref. Reading via `latest.current` keeps the callbacks reference-stable
   // across data, scale, and prop updates, which in turn keeps `composed` and
   // the gesture surface JSX stable so re-rendering the provider on each
   // index change never tears down the GestureDetector or the View tree.
+  const sortedMagnets = useMemo(() => {
+    const magneticIndices = getMagneticPoints();
+    return buildSortedMagnets({
+      magneticIndices,
+      getPixelForIndex: (index) =>
+        resolvePixelX(index, getXScale, getXAxisConfig()),
+    });
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [version, getXScale, getXAxisConfig, getMagneticPoints]);
+
   const latest = useRef({
     getXScale,
     getXAxisConfig,
     dataLength,
     onChange: onScrubberPositionChange,
     lastIndex: undefined as number | undefined,
+    magnetRadius,
+    sortedMagnets,
   });
   latest.current.getXScale = getXScale;
   latest.current.getXAxisConfig = getXAxisConfig;
   latest.current.dataLength = dataLength;
   latest.current.onChange = onScrubberPositionChange;
+  latest.current.magnetRadius = magnetRadius;
+  latest.current.sortedMagnets = sortedMagnets;
 
   const setScrubberPositionAndNotify = useCallback(
     (index: number | undefined) => {
@@ -78,12 +101,25 @@ export function ScrubberProvider({
       const ref = latest.current;
       const scale = ref.getXScale();
       if (!scale || ref.dataLength <= 0) return;
-      const index = getDataIndexFromPosition(
+
+      const xAxisConfig = ref.getXAxisConfig();
+
+      let index = getDataIndexFromPosition(
         pixelX,
         scale,
-        ref.getXAxisConfig(),
+        xAxisConfig,
         ref.dataLength,
       );
+
+      if (ref.magnetRadius > 0) {
+        index = applyMagnetisation({
+          resolvedIndex: index,
+          pixelX,
+          sortedMagnets: ref.sortedMagnets,
+          magnetRadius: ref.magnetRadius,
+        });
+      }
+
       setScrubberPositionAndNotify(index);
     },
     [setScrubberPositionAndNotify],
@@ -128,7 +164,7 @@ export function ScrubberProvider({
   // context as expected.
   const surface = useMemo(
     () => (
-      <View style={{ width, height }}>
+      <View style={[{ width, height }, style]}>
         {children}
         {enableScrubbing && (
           <GestureDetector gesture={composed}>
@@ -140,7 +176,7 @@ export function ScrubberProvider({
         )}
       </View>
     ),
-    [width, height, children, enableScrubbing, composed],
+    [width, height, style, children, enableScrubbing, composed],
   );
 
   const contextValue = useMemo(

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

@@ -1,4 +1,5 @@
 import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
 
 import type { DrawingArea } from '../../utils/types';
 
@@ -35,6 +36,18 @@ export type ScrubberProviderProps = {
    * Optional external callback fired whenever the scrubber position changes.
    */
   onScrubberPositionChange?: (index: number | undefined) => void;
+  /**
+   * Pixel radius within which the scrubber magnetically snaps to registered
+   * magnetic points. Set to `0` to disable magnetisation.
+   * @default 6
+   */
+  magnetRadius?: number;
+  /**
+   * Optional style applied to the wrapping `View` that holds the chart and the
+   * gesture overlay.Used to offset the(enlarged) SVG group so its drawing area
+   * aligns with the container footprint.
+   */
+  style?: StyleProp<ViewStyle>;
 };
 
 export type ChartTooltipItemData = {

package/src/lib/Components/Scrubber/utils.test.ts

@@ -5,10 +5,14 @@ import {
   getNumericScale,
 } from '../../utils/scales/scales';
 import {
+  applyMagnetisation,
+  buildSortedMagnets,
   getDataIndexFromPosition,
+  nearestIndex,
   resolvePixelX,
   resolvePixelY,
 } from './utils';
+import type { MagnetEntry } from './utils';
 
 describe('getDataIndexFromPosition', () => {
   describe('with a categorical (band) scale', () => {
@@ -170,3 +174,149 @@ describe('resolvePixelY', () => {
     expect(result).toBe(scale(50));
   });
 });
+
+describe('buildSortedMagnets', () => {
+  it('returns an empty array when the set is empty', () => {
+    const result = buildSortedMagnets({
+      magneticIndices: new Set(),
+      getPixelForIndex: () => 0,
+    });
+    expect(result).toEqual([]);
+  });
+
+  it('returns entries sorted by pixelX', () => {
+    const result = buildSortedMagnets({
+      magneticIndices: new Set([3, 1, 2]),
+      getPixelForIndex: (i) => i * 50,
+    });
+    expect(result).toEqual([
+      { index: 1, pixelX: 50 },
+      { index: 2, pixelX: 100 },
+      { index: 3, pixelX: 150 },
+    ]);
+  });
+
+  it('filters out indices where getPixelForIndex returns undefined', () => {
+    const result = buildSortedMagnets({
+      magneticIndices: new Set([0, 1, 2]),
+      getPixelForIndex: (i) => (i === 1 ? undefined : i * 100),
+    });
+    expect(result).toEqual([
+      { index: 0, pixelX: 0 },
+      { index: 2, pixelX: 200 },
+    ]);
+  });
+
+  it('returns an empty array when all indices resolve to undefined', () => {
+    const result = buildSortedMagnets({
+      magneticIndices: new Set([0, 1]),
+      getPixelForIndex: () => undefined,
+    });
+    expect(result).toEqual([]);
+  });
+});
+
+describe('nearestIndex', () => {
+  const magnets = (...pixelXs: number[]): MagnetEntry[] =>
+    pixelXs.map((px, i) => ({ index: i, pixelX: px }));
+
+  it('returns -1 for an empty array', () => {
+    expect(nearestIndex([], 100)).toBe(-1);
+  });
+
+  it('returns 0 for a single-element array', () => {
+    expect(nearestIndex(magnets(200), 100)).toBe(0);
+  });
+
+  it('returns the index of the exact match', () => {
+    expect(nearestIndex(magnets(100, 200, 300), 200)).toBe(1);
+  });
+
+  it('returns the closer index when target is between two values', () => {
+    expect(nearestIndex(magnets(100, 200), 160)).toBe(1);
+    expect(nearestIndex(magnets(100, 200), 140)).toBe(0);
+  });
+
+  it('favors the left index when equidistant', () => {
+    expect(nearestIndex(magnets(100, 200), 150)).toBe(0);
+  });
+
+  it('returns the last index when target is beyond all values', () => {
+    expect(nearestIndex(magnets(100, 200), 500)).toBe(1);
+  });
+
+  it('returns the first index when target is before all values', () => {
+    expect(nearestIndex(magnets(100, 200), 0)).toBe(0);
+  });
+});
+
+describe('applyMagnetisation', () => {
+  const toMagnets = (...indices: number[]): MagnetEntry[] =>
+    indices.map((i) => ({ index: i, pixelX: i * 100 }));
+
+  it('returns resolvedIndex when sortedMagnets is empty', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 200,
+        sortedMagnets: [],
+        magnetRadius: 30,
+      }),
+    ).toBe(2);
+  });
+
+  it('returns resolvedIndex when magnetRadius is 0', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 1,
+        pixelX: 200,
+        sortedMagnets: toMagnets(2),
+        magnetRadius: 0,
+      }),
+    ).toBe(1);
+  });
+
+  it('returns resolvedIndex when nearest magnet is outside radius', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 200,
+        sortedMagnets: toMagnets(0, 4),
+        magnetRadius: 30,
+      }),
+    ).toBe(2);
+  });
+
+  it('snaps to nearest magnet when within radius', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 280,
+        sortedMagnets: toMagnets(3),
+        magnetRadius: 30,
+      }),
+    ).toBe(3);
+  });
+
+  it('snaps at the exact boundary of magnetRadius', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 270,
+        sortedMagnets: toMagnets(3),
+        magnetRadius: 30,
+      }),
+    ).toBe(3);
+  });
+
+  it('does not snap when distance exceeds magnetRadius by 1', () => {
+    expect(
+      applyMagnetisation({
+        resolvedIndex: 2,
+        pixelX: 269,
+        sortedMagnets: toMagnets(3),
+        magnetRadius: 30,
+      }),
+    ).toBe(2);
+  });
+});