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

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

@@ -0,0 +1,59 @@
+import type { ReactNode } from 'react';
+
+export type ScrubberContextValue = {
+  /**
+   * Whether scrubbing interactions are enabled.
+   */
+  enableScrubbing: boolean;
+  /**
+   * The current data index of the scrubber, or undefined when idle.
+   */
+  scrubberPosition: number | undefined;
+  /**
+   * Callback to update the scrubber position.
+   */
+  onScrubberPositionChange: (index: number | undefined) => void;
+};
+
+export type ScrubberProviderProps = {
+  children: ReactNode;
+  /**
+   * Width of the chart in pixels. Used to bound gesture detection.
+   */
+  width: number;
+  /**
+   * Height of the chart in pixels. Used to bound gesture detection.
+   */
+  height: number;
+  /**
+   * Whether scrubbing is enabled.
+   */
+  enableScrubbing: boolean;
+  /**
+   * Optional external callback fired whenever the scrubber position changes.
+   */
+  onScrubberPositionChange?: (index: number | undefined) => void;
+};
+
+export type ScrubberProps = {
+  /**
+   * Formats a label string shown above the reference line for a given data index.
+   * When omitted, no label is rendered.
+   */
+  label?: (dataIndex: number) => string;
+  /**
+   * Hides the vertical reference line.
+   * @default false
+   */
+  hideLine?: boolean;
+  /**
+   * Hides the semi-transparent overlay that dims data after the scrubber position.
+   * @default false
+   */
+  hideOverlay?: boolean;
+  /**
+   * Shows the beacon dots on each series at the scrubbed data index.
+   * @default false
+   */
+  showBeacons?: boolean;
+};

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

@@ -0,0 +1,172 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  getCategoricalScale,
+  getNumericScale,
+} from '../../utils/scales/scales';
+import {
+  getDataIndexFromPosition,
+  resolvePixelX,
+  resolvePixelY,
+} from './utils';
+
+describe('getDataIndexFromPosition', () => {
+  describe('with a categorical (band) scale', () => {
+    const scale = getCategoricalScale({
+      domain: { min: 0, max: 3 },
+      range: { min: 0, max: 400 },
+      padding: 0,
+    });
+
+    it('returns 0 for a position at the center of the first band', () => {
+      const bandwidth = scale.bandwidth();
+      const center0 = (scale(0) ?? 0) + bandwidth / 2;
+      expect(getDataIndexFromPosition(center0, scale, undefined, 4)).toBe(0);
+    });
+
+    it('returns 1 for a position at the center of the second band', () => {
+      const bandwidth = scale.bandwidth();
+      const center1 = (scale(1) ?? 0) + bandwidth / 2;
+      expect(getDataIndexFromPosition(center1, scale, undefined, 4)).toBe(1);
+    });
+
+    it('returns the nearest band for a position between bands', () => {
+      expect(getDataIndexFromPosition(190, scale, undefined, 4)).toBe(1);
+      expect(getDataIndexFromPosition(210, scale, undefined, 4)).toBe(2);
+    });
+
+    it('returns 3 (last) for a position beyond the last band', () => {
+      expect(getDataIndexFromPosition(500, scale, undefined, 4)).toBe(3);
+    });
+  });
+
+  describe('with a numeric (linear) scale and no axisData', () => {
+    const scale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 4 },
+      range: { min: 0, max: 400 },
+    });
+
+    it('returns 0 for pixel 0', () => {
+      expect(getDataIndexFromPosition(0, scale, undefined, 5)).toBe(0);
+    });
+
+    it('returns 2 for pixel 200 (midpoint)', () => {
+      expect(getDataIndexFromPosition(200, scale, undefined, 5)).toBe(2);
+    });
+
+    it('clamps to 0 for negative positions', () => {
+      expect(getDataIndexFromPosition(-50, scale, undefined, 5)).toBe(0);
+    });
+
+    it('clamps to dataLength-1 for positions beyond range', () => {
+      expect(getDataIndexFromPosition(600, scale, undefined, 5)).toBe(4);
+    });
+  });
+
+  describe('with a numeric scale and numeric axisData', () => {
+    const scale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 10, max: 30 },
+      range: { min: 0, max: 200 },
+    });
+    const axisConfig = { data: [10, 20, 30] as number[] };
+
+    it('returns 0 for pixel closest to first data point', () => {
+      expect(getDataIndexFromPosition(10, scale, axisConfig, 3)).toBe(0);
+    });
+
+    it('returns 1 for pixel closest to middle data point', () => {
+      expect(getDataIndexFromPosition(100, scale, axisConfig, 3)).toBe(1);
+    });
+
+    it('returns 2 for pixel closest to last data point', () => {
+      expect(getDataIndexFromPosition(195, scale, axisConfig, 3)).toBe(2);
+    });
+  });
+});
+
+describe('resolvePixelX', () => {
+  it('returns undefined when getXScale returns undefined', () => {
+    const getXScale = () => undefined;
+    expect(resolvePixelX(0, getXScale)).toBeUndefined();
+  });
+
+  it('returns the correct pixel for a numeric scale', () => {
+    const scale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 4 },
+      range: { min: 0, max: 400 },
+    });
+    const getXScale = () => scale;
+    const result = resolvePixelX(2, getXScale);
+    expect(result).toBe(scale(2));
+  });
+
+  it('returns the band center for a categorical scale', () => {
+    const scale = getCategoricalScale({
+      domain: { min: 0, max: 3 },
+      range: { min: 0, max: 400 },
+      padding: 0,
+    });
+    const getXScale = () => scale;
+    const expected = (scale(1) ?? 0) + scale.bandwidth() / 2;
+    expect(resolvePixelX(1, getXScale)).toBe(expected);
+  });
+
+  it('uses numeric axisConfig.data values instead of the index', () => {
+    const scale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 10, max: 30 },
+      range: { min: 0, max: 200 },
+    });
+    const getXScale = () => scale;
+    const axisConfig = { data: [10, 20, 30] as number[] };
+
+    const atIndex = resolvePixelX(1, getXScale);
+    const atAxisValue = resolvePixelX(1, getXScale, axisConfig);
+
+    expect(atAxisValue).not.toBe(atIndex);
+    expect(atAxisValue).toBe(scale(20));
+  });
+
+  it('falls back to index when axisConfig.data is strings', () => {
+    const scale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 4 },
+      range: { min: 0, max: 400 },
+    });
+    const getXScale = () => scale;
+    const axisConfig = { data: ['a', 'b', 'c'] as string[] };
+
+    expect(resolvePixelX(2, getXScale, axisConfig)).toBe(
+      resolvePixelX(2, getXScale),
+    );
+  });
+});
+
+describe('resolvePixelY', () => {
+  const scale = getNumericScale({
+    scaleType: 'linear',
+    domain: { min: 0, max: 100 },
+    range: { min: 200, max: 0 },
+  });
+  const getYScale = () => scale;
+
+  it('returns undefined when getYScale returns undefined', () => {
+    expect(resolvePixelY(0, [10, 20], () => undefined)).toBeUndefined();
+  });
+
+  it('returns undefined when seriesData is undefined', () => {
+    expect(resolvePixelY(0, undefined, getYScale)).toBeUndefined();
+  });
+
+  it('returns undefined for a null data value', () => {
+    expect(resolvePixelY(1, [10, null, 30], getYScale)).toBeUndefined();
+  });
+
+  it('returns the correct pixel y for a valid data point', () => {
+    const result = resolvePixelY(0, [50], getYScale);
+    expect(result).toBe(scale(50));
+  });
+});

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

@@ -0,0 +1,126 @@
+import {
+  getPointOnScale,
+  isCategoricalScale,
+  isNumericScale,
+} from '../../utils/scales/scales';
+import type {
+  AxisConfigProps,
+  CartesianChartContextValue,
+  ChartScaleFunction,
+} from '../../utils/types';
+
+const isNumberArray = (arr: string[] | number[]): arr is number[] =>
+  typeof arr[0] === 'number';
+
+/**
+ * Returns the index of the item whose pixel position is closest to `pixelX`.
+ * `getPixelPosition` maps each index to its pixel coordinate (or undefined if
+ * the value cannot be projected).
+ */
+const findClosestIndex = (
+  length: number,
+  pixelX: number,
+  getPixelPosition: (index: number) => number | undefined,
+): number => {
+  let closestIndex = 0;
+  let closestDistance = Infinity;
+
+  for (let i = 0; i < length; i++) {
+    const pos = getPixelPosition(i);
+    if (pos === undefined) continue;
+
+    const distance = Math.abs(pixelX - pos);
+    if (distance < closestDistance) {
+      closestDistance = distance;
+      closestIndex = i;
+    }
+  }
+
+  return closestIndex;
+};
+
+/**
+ * Converts a pixel position along the x-axis into the nearest data index.
+ *
+ * For band (categorical) scales, finds the band whose center is closest to
+ * `pixelX`. For numeric scales, uses `scale.invert()` and rounds to the
+ * nearest integer, clamped to the valid index range.
+ */
+export const getDataIndexFromPosition = (
+  pixelX: number,
+  scale: ChartScaleFunction,
+  axisConfig: Partial<AxisConfigProps> | undefined,
+  dataLength: number,
+): number => {
+  if (dataLength <= 0) return 0;
+
+  if (isCategoricalScale(scale)) {
+    const axisData = axisConfig?.data;
+    if (axisData && axisData.length > 0 && isNumberArray(axisData)) {
+      return findClosestIndex(dataLength, pixelX, (i) =>
+        getPointOnScale(axisData[i], scale),
+      );
+    }
+    const step = scale.step();
+    const [rangeStart] = scale.range();
+    const offset =
+      rangeStart + scale.paddingOuter() * step + scale.bandwidth() / 2;
+    const index = Math.round((pixelX - offset) / step);
+    return Math.max(0, Math.min(index, dataLength - 1));
+  }
+
+  if (isNumericScale(scale)) {
+    const axisData = axisConfig?.data;
+
+    if (axisData && axisData.length > 0 && isNumberArray(axisData)) {
+      return findClosestIndex(axisData.length, pixelX, (i) =>
+        scale(axisData[i]),
+      );
+    }
+
+    const inverted = scale.invert(pixelX);
+    return Math.max(
+      0,
+      Math.min(Math.round(inverted as number), dataLength - 1),
+    );
+  }
+
+  return 0;
+};
+
+/**
+ * Resolves the pixel y-coordinate for a given series data point at a data index.
+ * Returns undefined when the value is null/missing or the scale is unavailable.
+ */
+export const resolvePixelY = (
+  dataIndex: number,
+  seriesData: (number | null)[] | undefined,
+  getYScale: CartesianChartContextValue['getYScale'],
+): number | undefined => {
+  const yScale = getYScale();
+  if (!yScale || !isNumericScale(yScale)) return undefined;
+  if (!seriesData) return undefined;
+
+  const value = seriesData[dataIndex];
+  if (value === null || value === undefined) return undefined;
+
+  return yScale(value) as number;
+};
+
+/**
+ * Resolves the pixel x-coordinate for a given data index using the x-scale.
+ * When numeric x-axis data is provided, the corresponding axis value is used;
+ * otherwise the data index is used as the x input.
+ * Returns undefined only when the scale is unavailable.
+ */
+export const resolvePixelX = (
+  dataIndex: number,
+  getXScale: CartesianChartContextValue['getXScale'],
+  axisConfig?: AxisConfigProps,
+): number | undefined => {
+  const scale = getXScale();
+  if (!scale) return undefined;
+  const axisValue = axisConfig?.data?.[dataIndex];
+  const xValue = typeof axisValue === 'number' ? axisValue : dataIndex;
+  return getPointOnScale(xValue, scale);
+};

package/src/lib/Components/index.ts

@@ -1,2 +1,4 @@
 export * from './LineChart';
 export * from './Point';
+export * from './ReferenceLine';
+export * from './Scrubber';

package/src/lib/utils/scales/scales.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from '@jest/globals';
 import {
   getCategoricalScale,
   getNumericScale,
+  getPointOnScale,
   isBandScaleType,
   isCategoricalScale,
   isNumericScale,
@@ -133,6 +134,27 @@ describe('isCategoricalScale / isNumericScale', () => {
   });
 });
 
+describe('getPointOnScale', () => {
+  it('returns the center of a band for categorical scales', () => {
+    const scale = getCategoricalScale({
+      domain: { min: 0, max: 3 },
+      range: { min: 0, max: 400 },
+      padding: 0,
+    });
+    const expected = (scale(0) ?? 0) + scale.bandwidth() / 2;
+    expect(getPointOnScale(0, scale)).toBe(expected);
+  });
+
+  it('returns the direct scale value for numeric scales', () => {
+    const scale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 4 },
+      range: { min: 0, max: 400 },
+    });
+    expect(getPointOnScale(2, scale)).toBe(scale(2));
+  });
+});
+
 describe('projectPoint', () => {
   it('should project using two linear scales', () => {
     const xScale = getNumericScale({

package/src/lib/utils/scales/scales.ts

@@ -73,6 +73,21 @@ export const isNumericScale = (
   return !isCategoricalScale(scale);
 };
 
+/**
+ * Returns the pixel coordinate at the center of the given data index on the scale.
+ * For band (categorical) scales, centers on the bandwidth.
+ * For numeric scales, calls the scale directly.
+ */
+export const getPointOnScale = (
+  dataIndex: number,
+  scale: ChartScaleFunction,
+): number => {
+  if (isCategoricalScale(scale)) {
+    return (scale(dataIndex) ?? 0) + scale.bandwidth() / 2;
+  }
+  return scale(dataIndex) as number;
+};
+
 /**
  * Projects a single data-space coordinate pair to pixel-space
  * using the provided x and y scale functions.
@@ -84,12 +99,7 @@ export const projectPoint = (
   dataY: number,
   xScale: ChartScaleFunction,
   yScale: ChartScaleFunction,
-): { x: number; y: number } => {
-  const x = isCategoricalScale(xScale)
-    ? (xScale(dataX) ?? 0) + xScale.bandwidth() / 2
-    : xScale(dataX);
-  const y = isCategoricalScale(yScale)
-    ? (yScale(dataY) ?? 0) + yScale.bandwidth() / 2
-    : yScale(dataY);
-  return { x: x, y };
-};
+): { x: number; y: number } => ({
+  x: getPointOnScale(dataX, xScale),
+  y: getPointOnScale(dataY, yScale),
+});