@ledgerhq/lumen-ui-rnative-visualization 0.1.5 → 0.1.6

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

@@ -0,0 +1,197 @@
+import { describe, it, expect, 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 React from 'react';
+import { Text as SvgText } from 'react-native-svg';
+
+import { CartesianChart } from '../CartesianChart';
+
+import { Point } from './Point';
+
+const sampleSeries = [{ id: 's1', stroke: '#000', data: [10, 20, 30, 40, 50] }];
+
+const Wrapper = ({ children }: { children: React.ReactNode }) => (
+  <ThemeProvider themes={ledgerLiveThemes} colorScheme='light'>
+    {children}
+  </ThemeProvider>
+);
+
+const renderInChart = (
+  pointElement: React.ReactNode,
+  {
+    width = 400,
+    height = 200,
+    xAxis,
+    yAxis,
+  }: {
+    width?: number;
+    height?: number;
+    xAxis?: Parameters<typeof CartesianChart>[0]['xAxis'];
+    yAxis?: Parameters<typeof CartesianChart>[0]['yAxis'];
+  } = {},
+) =>
+  render(
+    <Wrapper>
+      <CartesianChart
+        series={sampleSeries}
+        width={width}
+        height={height}
+        xAxis={xAxis}
+        yAxis={yAxis}
+      >
+        {pointElement}
+      </CartesianChart>
+    </Wrapper>,
+  );
+
+describe('Point', () => {
+  it('renders a circle at the projected position', () => {
+    const { getByTestId } = renderInChart(<Point dataX={2} dataY={30} />);
+    const circle = getByTestId('point-circle');
+    expect(circle).toBeTruthy();
+    expect(circle.props.r).toBe(5);
+  });
+
+  it('renders with custom color and size', () => {
+    const { getByTestId } = renderInChart(
+      <Point dataX={2} dataY={30} color='#FF0000' size={16} />,
+    );
+    const circle = getByTestId('point-circle');
+    expect(circle.props.fill).toBe('#FF0000');
+    expect(circle.props.r).toBe(8);
+  });
+
+  it('renders a string label', () => {
+    const { getByText } = renderInChart(
+      <Point dataX={2} dataY={30} label='Peak' />,
+    );
+    expect(getByText('Peak')).toBeTruthy();
+  });
+
+  it('renders a label via function', () => {
+    const { getByText } = renderInChart(
+      <Point dataX={2} dataY={30} label={(i) => `#${i}`} />,
+    );
+    expect(getByText('#2')).toBeTruthy();
+  });
+
+  it('renders custom LabelComponent', () => {
+    const CustomLabel = ({
+      x,
+      y,
+      children,
+    }: {
+      x: number;
+      y: number;
+      children: string;
+    }) => (
+      <SvgText testID='custom-label' x={x} y={y}>
+        {children}
+      </SvgText>
+    );
+
+    const { getByTestId } = renderInChart(
+      <Point dataX={2} dataY={30} label='Peak' LabelComponent={CustomLabel} />,
+    );
+
+    expect(getByTestId('custom-label')).toBeTruthy();
+  });
+
+  it('does not render LabelComponent when label is absent', () => {
+    const CustomLabel = ({
+      children,
+    }: {
+      x: number;
+      y: number;
+      children: string;
+    }) => <SvgText testID='custom-label'>{children}</SvgText>;
+
+    const { queryByTestId } = renderInChart(
+      <Point dataX={2} dataY={30} LabelComponent={CustomLabel} />,
+    );
+
+    expect(queryByTestId('custom-label')).toBeNull();
+  });
+
+  it('hides the circle when hidePoint is true but shows label', () => {
+    const { queryByTestId, getByText } = renderInChart(
+      <Point dataX={2} dataY={30} hidePoint label='Still here' />,
+    );
+    expect(queryByTestId('point-circle')).toBeNull();
+    expect(getByText('Still here')).toBeTruthy();
+  });
+
+  it('returns null when point is outside drawing area', () => {
+    const { queryByTestId } = renderInChart(
+      <Point dataX={-100} dataY={-100} />,
+    );
+    expect(queryByTestId('point-group')).toBeNull();
+  });
+
+  it('works with band (categorical) x-axis scale', () => {
+    const { getByTestId } = renderInChart(<Point dataX={1} dataY={30} />, {
+      xAxis: { scaleType: 'band' },
+    });
+    const circle = getByTestId('point-circle');
+    expect(circle).toBeTruthy();
+  });
+
+  it('renders arrow when label is present and showArrow is true', () => {
+    const { getByTestId } = renderInChart(
+      <Point dataX={2} dataY={30} label='Peak' />,
+    );
+    expect(getByTestId('point-arrow')).toBeTruthy();
+  });
+
+  it('does not render arrow when no label is present', () => {
+    const { queryByTestId } = renderInChart(<Point dataX={2} dataY={30} />);
+    expect(queryByTestId('point-arrow')).toBeNull();
+  });
+
+  it('does not render arrow when showArrow is false', () => {
+    const { queryByTestId } = renderInChart(
+      <Point dataX={2} dataY={30} label='Peak' showLabelArrow={false} />,
+    );
+    expect(queryByTestId('point-arrow')).toBeNull();
+  });
+
+  it('renders label below the point when labelPosition is bottom', () => {
+    const topSpy = jest.fn(
+      ({ y }: { x: number; y: number; children: string }) => (
+        <SvgText>{y}</SvgText>
+      ),
+    );
+    const bottomSpy = jest.fn(
+      ({ y }: { x: number; y: number; children: string }) => (
+        <SvgText>{y}</SvgText>
+      ),
+    );
+
+    renderInChart(
+      <Point dataX={2} dataY={30} label='T' LabelComponent={topSpy} />,
+    );
+    renderInChart(
+      <Point
+        dataX={2}
+        dataY={30}
+        label='B'
+        labelPosition='bottom'
+        LabelComponent={bottomSpy}
+      />,
+    );
+
+    const topY = topSpy.mock.calls[0][0].y;
+    const bottomY = bottomSpy.mock.calls[0][0].y;
+    expect(bottomY).toBeGreaterThan(topY);
+  });
+
+  it('calls onPress when the point is pressed', () => {
+    const onPress = jest.fn();
+    const { getByTestId } = renderInChart(
+      <Point dataX={2} dataY={30} onPress={onPress} />,
+    );
+    fireEvent.press(getByTestId('point-group'));
+    expect(onPress).toHaveBeenCalled();
+  });
+});

package/src/lib/Components/Point/Point.tsx

@@ -0,0 +1,100 @@
+import { useTheme } from '@ledgerhq/lumen-ui-rnative';
+import { useMemo } from 'react';
+import { Circle, G, Polygon, Text as SvgText } from 'react-native-svg';
+
+import { projectPoint } from '../../utils/scales/scales';
+import { useCartesianChartContext } from '../CartesianChart/context';
+
+import type { PointLabelProps, PointProps } from './types';
+import {
+  buildArrowPoints,
+  computeLabelY,
+  DEFAULT_SIZE,
+  isWithinBounds,
+  resolveLabel,
+  STROKE_WIDTH,
+} from './utils';
+
+export function PointLabel({
+  textAnchor = 'middle',
+  ...props
+}: Readonly<PointLabelProps>) {
+  const { theme } = useTheme();
+
+  return (
+    <SvgText
+      textAnchor={textAnchor}
+      fill={theme.colors.text.base}
+      fontSize={theme.typographies.body4.fontSize}
+      fontWeight={theme.typographies.body4.fontWeight}
+      fontFamily={theme.fontFamilies.sans}
+      {...props}
+    />
+  );
+}
+
+export function Point({
+  dataX,
+  dataY,
+  color,
+  label,
+  LabelComponent,
+  labelPosition = 'top',
+  hidePoint = false,
+  showLabelArrow = true,
+  size = DEFAULT_SIZE,
+  onPress,
+}: Readonly<PointProps>) {
+  const { getXScale, getYScale, drawingArea } = useCartesianChartContext();
+  const { theme } = useTheme();
+
+  const xScale = getXScale();
+  const yScale = getYScale();
+
+  const radius = size / 2;
+  const fill = color ?? theme.colors.bg.mutedStrong;
+
+  const pixel = useMemo(() => {
+    if (!xScale || !yScale) return undefined;
+    return projectPoint(dataX, dataY, xScale, yScale);
+  }, [dataX, dataY, xScale, yScale]);
+
+  if (!pixel || !isWithinBounds(pixel.x, pixel.y, drawingArea)) {
+    return null;
+  }
+
+  const resolvedLabel = resolveLabel(label, dataX);
+  const hasLabel = resolvedLabel != null;
+  const renderArrow = showLabelArrow && hasLabel;
+  const labelY = computeLabelY(pixel.y, radius, labelPosition, renderArrow);
+
+  const Label = LabelComponent ?? PointLabel;
+
+  return (
+    <G testID='point-group' onPress={onPress}>
+      {!hidePoint && (
+        <Circle
+          testID='point-circle'
+          cx={pixel.x}
+          cy={pixel.y}
+          r={radius}
+          fill={fill}
+          stroke={theme.colors.bg.canvas}
+          strokeWidth={STROKE_WIDTH}
+        />
+      )}
+      {renderArrow && (
+        <Polygon
+          testID='point-arrow'
+          points={buildArrowPoints(pixel.x, pixel.y, radius, labelPosition)}
+          fill={theme.colors.text.base}
+        />
+      )}
+      {resolvedLabel != null && (
+        <Label x={pixel.x} y={labelY}>
+          {resolvedLabel}
+        </Label>
+      )}
+    </G>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { Point, PointLabel } from './Point';
+export type { PointLabelComponent, PointLabelProps, PointProps } from './types';

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

@@ -0,0 +1,76 @@
+import type { ComponentType } from 'react';
+import type { GestureResponderEvent } from 'react-native';
+import type { TextProps } from 'react-native-svg';
+
+export type PointLabelProps = {
+  x: number;
+  y: number;
+  children: string;
+} & Omit<TextProps, 'x' | 'y' | 'children'>;
+
+export type PointLabelComponent = ComponentType<PointLabelProps>;
+
+export type PointProps = {
+  /**
+   * X coordinate in data space (index or explicit value).
+   */
+  dataX: number;
+  /**
+   * Y coordinate in data space.
+   */
+  dataY: number;
+  /**
+   * Fill color of the point circle.
+   * Defaults to `theme.colors.bg.mutedStrong`.
+   *
+   * Use the `useTheme` hook from `@ledgerhq/lumen-ui-rnative` to
+   * access design-token colors at runtime:
+   *
+   * @example
+   * ```tsx
+   * import { useTheme } from '@ledgerhq/lumen-ui-rnative';
+   *
+   * const { theme } = useTheme();
+   * <Point dataX={0} dataY={42} color={theme.colors.bg.errorStrong} />
+   * ```
+   */
+  color?: string;
+  /**
+   * Text label displayed near the point.
+   * A string is rendered directly; a function receives `dataX` and returns
+   * the label string, enabling index-based formatting.
+   */
+  label?: string | ((dataIndex: number) => string);
+  /**
+   * Custom component rendered instead of the default `PointLabel`.
+   * Receives pixel coordinates (`x`, `y`) and the resolved label as
+   * `children`. Use `PointLabel` inside your component to retain
+   * theme styling while customising layout or appearance.
+   */
+  LabelComponent?: PointLabelComponent;
+  /**
+   * Placement of the label relative to the point.
+   * @default 'top'
+   */
+  labelPosition?: 'top' | 'bottom';
+  /**
+   * When `true`, the point circle is hidden but the label (if any) is still rendered.
+   * @default false
+   */
+  hidePoint?: boolean;
+  /**
+   * Diameter of the point circle in pixels.
+   * Internally converted to an SVG radius (`size / 2`).
+   * @default 10
+   */
+  size?: number;
+  /**
+   * When `true`, an arrow is displayed pointing from the point to the label.
+   * @default true
+   */
+  showLabelArrow?: boolean;
+  /**
+   * Called when the point is pressed.
+   */
+  onPress?: (event: GestureResponderEvent) => void;
+};

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

@@ -0,0 +1,118 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  ARROW_HEIGHT,
+  ARROW_WIDTH,
+  buildArrowPoints,
+  computeLabelY,
+  GAP,
+  isWithinBounds,
+  LABEL_FONT_SIZE,
+  resolveLabel,
+} from './utils';
+
+describe('isWithinBounds', () => {
+  const area = { x: 10, y: 20, width: 100, height: 50 };
+
+  it('returns true for a point inside the area', () => {
+    expect(isWithinBounds(50, 40, area)).toBe(true);
+  });
+
+  it('returns true on the top-left edge', () => {
+    expect(isWithinBounds(10, 20, area)).toBe(true);
+  });
+
+  it('returns true on the bottom-right edge', () => {
+    expect(isWithinBounds(110, 70, area)).toBe(true);
+  });
+
+  it('returns false when x is left of the area', () => {
+    expect(isWithinBounds(9, 40, area)).toBe(false);
+  });
+
+  it('returns false when x is right of the area', () => {
+    expect(isWithinBounds(111, 40, area)).toBe(false);
+  });
+
+  it('returns false when y is above the area', () => {
+    expect(isWithinBounds(50, 19, area)).toBe(false);
+  });
+
+  it('returns false when y is below the area', () => {
+    expect(isWithinBounds(50, 71, area)).toBe(false);
+  });
+});
+
+describe('buildArrowPoints', () => {
+  const cx = 100;
+  const cy = 200;
+  const radius = 5;
+  const halfW = ARROW_WIDTH / 2;
+
+  it('builds a downward-pointing arrow for top position', () => {
+    const result = buildArrowPoints(cx, cy, radius, 'top');
+    const tipY = cy - radius - GAP;
+    const baseY = tipY - ARROW_HEIGHT;
+    expect(result).toBe(
+      `${cx},${tipY} ${cx - halfW},${baseY} ${cx + halfW},${baseY}`,
+    );
+  });
+
+  it('builds an upward-pointing arrow for bottom position', () => {
+    const result = buildArrowPoints(cx, cy, radius, 'bottom');
+    const tipY = cy + radius + GAP;
+    const baseY = tipY + ARROW_HEIGHT;
+    expect(result).toBe(
+      `${cx},${tipY} ${cx - halfW},${baseY} ${cx + halfW},${baseY}`,
+    );
+  });
+});
+
+describe('resolveLabel', () => {
+  it('returns a string label as-is', () => {
+    expect(resolveLabel('Peak', 0)).toBe('Peak');
+  });
+
+  it('calls a function label with dataX', () => {
+    expect(resolveLabel((i) => `#${i}`, 3)).toBe('#3');
+  });
+
+  it('returns undefined for an undefined label', () => {
+    expect(resolveLabel(undefined, 0)).toBeUndefined();
+  });
+
+  it('returns undefined for an empty string', () => {
+    expect(resolveLabel('', 0)).toBeUndefined();
+  });
+
+  it('returns undefined when a function returns an empty string', () => {
+    expect(resolveLabel(() => '', 0)).toBeUndefined();
+  });
+});
+
+describe('computeLabelY', () => {
+  const pixelY = 100;
+  const radius = 5;
+
+  it('positions label above the point when labelPosition is top with arrow', () => {
+    const result = computeLabelY(pixelY, radius, 'top', true);
+    const arrowOffset = ARROW_HEIGHT + GAP;
+    expect(result).toBe(pixelY - radius - arrowOffset - GAP);
+  });
+
+  it('positions label above the point when labelPosition is top without arrow', () => {
+    const result = computeLabelY(pixelY, radius, 'top', false);
+    expect(result).toBe(pixelY - radius - GAP - GAP);
+  });
+
+  it('positions label below the point when labelPosition is bottom with arrow', () => {
+    const result = computeLabelY(pixelY, radius, 'bottom', true);
+    const arrowOffset = ARROW_HEIGHT + GAP;
+    expect(result).toBe(pixelY + radius + arrowOffset + GAP + LABEL_FONT_SIZE);
+  });
+
+  it('positions label below the point when labelPosition is bottom without arrow', () => {
+    const result = computeLabelY(pixelY, radius, 'bottom', false);
+    expect(result).toBe(pixelY + radius + GAP + GAP + LABEL_FONT_SIZE);
+  });
+});

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

@@ -0,0 +1,70 @@
+import type { DrawingArea } from '../../utils/types';
+
+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;
+
+export const isWithinBounds = (
+  px: number,
+  py: number,
+  area: DrawingArea,
+): boolean =>
+  px >= area.x &&
+  px <= area.x + area.width &&
+  py >= area.y &&
+  py <= area.y + area.height;
+
+/**
+ * Builds the three SVG points of the arrow triangle.
+ *
+ * `'top'`    → arrow sits below the label, tip pointing **down** toward the circle.
+ * `'bottom'` → arrow sits above the label, tip pointing **up** toward the circle.
+ */
+export const buildArrowPoints = (
+  cx: number,
+  cy: number,
+  radius: number,
+  position: 'top' | 'bottom',
+): string => {
+  const halfW = ARROW_WIDTH / 2;
+
+  if (position === 'top') {
+    const tipY = cy - radius - GAP;
+    const baseY = tipY - ARROW_HEIGHT;
+    return `${cx},${tipY} ${cx - halfW},${baseY} ${cx + halfW},${baseY}`;
+  }
+
+  const tipY = cy + radius + GAP;
+  const baseY = tipY + ARROW_HEIGHT;
+  return `${cx},${tipY} ${cx - halfW},${baseY} ${cx + halfW},${baseY}`;
+};
+
+/**
+ * Resolves the label prop to a string or undefined.
+ */
+export const resolveLabel = (
+  label: string | ((dataIndex: number) => string) | undefined,
+  dataX: number,
+): string | undefined => {
+  const resolved = typeof label === 'function' ? label(dataX) : label;
+  return resolved === '' ? undefined : resolved;
+};
+
+/**
+ * Computes the vertical position of the label text baseline.
+ */
+export const computeLabelY = (
+  pixelY: number,
+  radius: number,
+  labelPosition: 'top' | 'bottom',
+  renderArrow: boolean,
+): number => {
+  const arrowOffset = renderArrow ? ARROW_HEIGHT + GAP : GAP;
+
+  return labelPosition === 'top'
+    ? pixelY - radius - arrowOffset - GAP
+    : pixelY + radius + arrowOffset + GAP + LABEL_FONT_SIZE;
+};

package/src/lib/Components/index.ts

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

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

@@ -6,6 +6,7 @@ import {
   isBandScaleType,
   isCategoricalScale,
   isNumericScale,
+  projectPoint,
 } from './scales';
 
 describe('getNumericScale', () => {
@@ -131,3 +132,56 @@ describe('isCategoricalScale / isNumericScale', () => {
     expect(isNumericScale(bandScale)).toBe(false);
   });
 });
+
+describe('projectPoint', () => {
+  it('should project using two linear scales', () => {
+    const xScale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 10 },
+      range: { min: 0, max: 500 },
+    });
+    const yScale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 100 },
+      range: { min: 300, max: 0 },
+    });
+
+    const pt = projectPoint(5, 50, xScale, yScale);
+    expect(pt.x).toBe(250);
+    expect(pt.y).toBe(150);
+  });
+
+  it('should center on band for a categorical x scale', () => {
+    const xScale = getCategoricalScale({
+      domain: { min: 0, max: 3 },
+      range: { min: 0, max: 400 },
+      padding: 0,
+    });
+    const yScale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 100 },
+      range: { min: 200, max: 0 },
+    });
+
+    const pt = projectPoint(1, 50, xScale, yScale);
+    const expectedX = (xScale(1) ?? 0) + xScale.bandwidth() / 2;
+    expect(pt.x).toBe(expectedX);
+    expect(pt.y).toBe(100);
+  });
+
+  it('should handle edge values at domain boundaries', () => {
+    const xScale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 10 },
+      range: { min: 0, max: 500 },
+    });
+    const yScale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 100 },
+      range: { min: 300, max: 0 },
+    });
+
+    expect(projectPoint(0, 0, xScale, yScale)).toEqual({ x: 0, y: 300 });
+    expect(projectPoint(10, 100, xScale, yScale)).toEqual({ x: 500, y: 0 });
+  });
+});

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

@@ -72,3 +72,24 @@ export const isNumericScale = (
 ): scale is NumericScale => {
   return !isCategoricalScale(scale);
 };
+
+/**
+ * Projects a single data-space coordinate pair to pixel-space
+ * using the provided x and y scale functions.
+ *
+ * For categorical (band) scales the point is anchored at the center of the band.
+ */
+export const projectPoint = (
+  dataX: number,
+  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 };
+};