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

package/src/lib/Components/CartesianChart/RevealClip/RevealClipDefs.test.tsx

@@ -0,0 +1,129 @@
+import { describe, it, expect } 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 { Svg } from 'react-native-svg';
+
+import type { DrawingArea, Series } from '../../../utils/types';
+import { OVERFLOW_BUFFER } from '../utils';
+
+import { useRevealClip } from './context';
+import { RevealClipDefs } from './RevealClipDefs';
+
+const drawingArea: DrawingArea = {
+  x: 10,
+  y: 10,
+  width: 380,
+  height: 180,
+};
+
+const series: Series[] = [{ id: 'a', stroke: '#000', data: [1, 2, 3] }];
+
+function ClipConsumer() {
+  const clipPath = useRevealClip();
+  return <Svg testID='consumer' clipPath={clipPath} />;
+}
+
+const renderInSvg = (ui: React.ReactElement) =>
+  render(
+    <ThemeProvider themes={ledgerLiveThemes} colorScheme='light'>
+      <Svg>{ui}</Svg>
+    </ThemeProvider>,
+  );
+
+describe('RevealClipDefs', () => {
+  it('renders children', () => {
+    const { getByTestId } = renderInSvg(
+      <RevealClipDefs
+        drawingArea={drawingArea}
+        series={series}
+        transitions={{ enter: { duration: 0.5 } }}
+      >
+        <Svg testID='child' />
+      </RevealClipDefs>,
+    );
+
+    expect(getByTestId('child')).toBeTruthy();
+  });
+
+  it('renders a ClipPath with a Rect when animate is true', () => {
+    const { UNSAFE_root } = renderInSvg(
+      <RevealClipDefs
+        drawingArea={drawingArea}
+        series={series}
+        transitions={{ enter: { duration: 0.5 } }}
+      >
+        <Svg testID='child' />
+      </RevealClipDefs>,
+    );
+
+    const clipPaths = UNSAFE_root.findAllByType('ClipPath' as any);
+    expect(clipPaths.length).toBeGreaterThan(0);
+
+    const rects = clipPaths[0].findAllByType('Rect' as any);
+    expect(rects.length).toBeGreaterThan(0);
+
+    const rect = rects[0];
+    expect(rect.props.x).toBe(drawingArea.x - OVERFLOW_BUFFER.left);
+    expect(rect.props.y).toBe(drawingArea.y - OVERFLOW_BUFFER.top);
+    expect(rect.props.height).toBe(
+      drawingArea.height + OVERFLOW_BUFFER.top + OVERFLOW_BUFFER.bottom,
+    );
+  });
+
+  it('provides clipPathAttr to consumers via context', () => {
+    const { UNSAFE_root } = renderInSvg(
+      <RevealClipDefs
+        drawingArea={drawingArea}
+        series={series}
+        transitions={{ enter: { duration: 0.5 } }}
+      >
+        <ClipConsumer />
+      </RevealClipDefs>,
+    );
+
+    const consumer = UNSAFE_root.findByProps({ testID: 'consumer' });
+    expect(consumer.props.clipPath).toMatch(/^url\(#/);
+  });
+
+  it('skips ClipPath when animate is false', () => {
+    const { UNSAFE_root, getByTestId } = renderInSvg(
+      <RevealClipDefs drawingArea={drawingArea} series={series} animate={false}>
+        <Svg testID='child' />
+      </RevealClipDefs>,
+    );
+
+    expect(getByTestId('child')).toBeTruthy();
+
+    const clipPaths = UNSAFE_root.findAllByType('ClipPath' as any);
+    expect(clipPaths).toHaveLength(0);
+  });
+
+  it('does not provide clipPathAttr when animate is false', () => {
+    const { UNSAFE_root } = renderInSvg(
+      <RevealClipDefs drawingArea={drawingArea} series={series} animate={false}>
+        <ClipConsumer />
+      </RevealClipDefs>,
+    );
+
+    const consumer = UNSAFE_root.findByProps({ testID: 'consumer' });
+    expect(consumer.props.clipPath).toBeUndefined();
+  });
+
+  it('renders without crashing when transitions.enter is not defined', () => {
+    const { UNSAFE_root, getByTestId } = renderInSvg(
+      <RevealClipDefs
+        drawingArea={drawingArea}
+        series={series}
+        transitions={{}}
+      >
+        <Svg testID='child' />
+      </RevealClipDefs>,
+    );
+
+    expect(getByTestId('child')).toBeTruthy();
+
+    const clipPaths = UNSAFE_root.findAllByType('ClipPath' as any);
+    expect(clipPaths.length).toBeGreaterThan(0);
+  });
+});

package/src/lib/Components/CartesianChart/RevealClip/RevealClipDefs.tsx

@@ -0,0 +1,59 @@
+import { useMemo } from 'react';
+import Animated from 'react-native-reanimated';
+import { ClipPath, Defs, Rect } from 'react-native-svg';
+
+import { OVERFLOW_BUFFER } from '../utils';
+
+import { RevealClipContext } from './context';
+import type { RevealClipDefsProps } from './types';
+import { useComputeDataFingerprint, useRevealClipAnimation } from './utils';
+
+const DEFAULT_DURATION_IN_SECONDS = 0.8;
+
+const AnimatedRect = Animated.createAnimatedComponent(Rect);
+
+export function RevealClipDefs({
+  children,
+  drawingArea,
+  series,
+  animate = true,
+  transitions,
+}: RevealClipDefsProps) {
+  const isDisabled = !animate;
+  const durationMs =
+    (transitions?.enter?.duration ?? DEFAULT_DURATION_IN_SECONDS) * 1000;
+
+  const dataFingerprint = useComputeDataFingerprint({ series });
+  const { clipId, animatedRectProps } = useRevealClipAnimation({
+    durationMs,
+    drawingArea,
+    dataFingerprint,
+  });
+
+  const contextValue = useMemo(
+    () => ({ clipPathAttr: `url(#${clipId})` }),
+    [clipId],
+  );
+
+  if (isDisabled) {
+    return children;
+  }
+
+  return (
+    <RevealClipContext.Provider key={dataFingerprint} value={contextValue}>
+      <Defs>
+        <ClipPath id={clipId}>
+          <AnimatedRect
+            x={drawingArea.x - OVERFLOW_BUFFER.left}
+            y={drawingArea.y - OVERFLOW_BUFFER.top}
+            height={
+              drawingArea.height + OVERFLOW_BUFFER.top + OVERFLOW_BUFFER.bottom
+            }
+            animatedProps={animatedRectProps}
+          />
+        </ClipPath>
+      </Defs>
+      {children}
+    </RevealClipContext.Provider>
+  );
+}

package/src/lib/Components/CartesianChart/RevealClip/context.ts

@@ -0,0 +1,13 @@
+import { createContext, useContext } from 'react';
+
+type RevealClipContextValue = {
+  clipPathAttr: string;
+};
+
+export const RevealClipContext = createContext<
+  RevealClipContextValue | undefined
+>(undefined);
+
+export const useRevealClip = (): string | undefined => {
+  return useContext(RevealClipContext)?.clipPathAttr;
+};

package/src/lib/Components/CartesianChart/RevealClip/index.ts

@@ -0,0 +1,2 @@
+export { RevealClipDefs } from './RevealClipDefs';
+export { useRevealClip } from './context';

package/src/lib/Components/CartesianChart/RevealClip/types.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+
+import type { DrawingArea, Series } from '../../../utils';
+
+export type EnterTransitionConfig = {
+  /**
+   * Duration in seconds. @default 0.8
+   */
+  duration?: number;
+  /**
+   * Reanimated easing is configured internally.
+   * This field is kept for API parity with the web variant but is unused on native.
+   */
+  easing?: string;
+};
+
+export type RevealClipDefsProps = {
+  children: ReactNode;
+  /**
+   * The drawing area whose bounds define the clip rectangle.
+   */
+  drawingArea: DrawingArea;
+  /**
+   * Whether to animate the chart.
+   * @default true
+   */
+  animate?: boolean;
+  /**
+   * Transition configuration.
+   * @default { enter: { duration: 0.8 } }
+   */
+  transitions?: { enter?: EnterTransitionConfig };
+  /**
+   * Data series used to compute a fingerprint that restarts
+   * the animation when data changes.
+   */
+  series: Series[];
+};

package/src/lib/Components/CartesianChart/RevealClip/utils.ts

@@ -0,0 +1,51 @@
+import { useEffect, useId } from 'react';
+import {
+  useAnimatedProps,
+  useSharedValue,
+  withTiming,
+} from 'react-native-reanimated';
+
+import type { DrawingArea, Series } from '../../../utils/types';
+import { OVERFLOW_BUFFER } from '../utils';
+
+type RevealClipAnimationConfig = {
+  durationMs: number;
+  drawingArea: DrawingArea;
+  dataFingerprint: string;
+};
+
+type RevealClipAnimationResult = {
+  clipId: string;
+  animatedRectProps: ReturnType<typeof useAnimatedProps>;
+};
+
+export const useRevealClipAnimation = ({
+  durationMs,
+  drawingArea,
+  dataFingerprint,
+}: RevealClipAnimationConfig): RevealClipAnimationResult => {
+  const clipId = useId();
+  const width = useSharedValue(0);
+
+  useEffect(() => {
+    width.value = 0;
+    width.value = withTiming(
+      drawingArea.width + OVERFLOW_BUFFER.left + OVERFLOW_BUFFER.right,
+      { duration: durationMs },
+    );
+  }, [drawingArea.width, durationMs, width, dataFingerprint]);
+
+  const animatedRectProps = useAnimatedProps(() => ({
+    width: width.value,
+  }));
+
+  return { clipId, animatedRectProps };
+};
+
+export const useComputeDataFingerprint = ({
+  series,
+}: {
+  series: Series[];
+}): string => {
+  return series.map((s) => s.data?.join(',') ?? '').join('|');
+};

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

@@ -46,4 +46,21 @@ export type CartesianChartProps = {
    * SVG content rendered inside the chart's context provider.
    */
   children?: ReactNode;
+  /**
+   * Enables scrubbing (pan gesture) interactions on the chart.
+   * When true, add a `<Scrubber>` as a child to visualise the interaction.
+   * @default false
+   */
+  enableScrubbing?: boolean;
+  /**
+   * Callback fired whenever the scrubber moves to a new data index or is cleared.
+   * Receives `undefined` when the scrub gesture ends or the scrubber position is otherwise cleared.
+   */
+  onScrubberPositionChange?: (index: number | undefined) => void;
+  /**
+   * Whether to animate the chart on mount and data changes.
+   * Duration is 0.8 seconds.
+   * @default true
+   */
+  animate?: boolean;
 };

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

@@ -9,10 +9,10 @@ export const DEFAULT_HEIGHT = 160;
  * wrapper so the chart's visual footprint stays unchanged.
  */
 export const OVERFLOW_BUFFER: ChartInset = {
-  top: 30,
-  right: 20,
-  bottom: 30,
-  left: 20,
+  top: 50,
+  right: 50,
+  bottom: 50,
+  left: 50,
 };
 export const OVERFLOW_NEGATIVE_MARGIN = {
   marginTop: -OVERFLOW_BUFFER.top,

package/src/lib/Components/Line/Line.tsx

@@ -1,8 +1,9 @@
 import { useId, useMemo } from 'react';
-import { Defs, LinearGradient, Path, Stop } from 'react-native-svg';
+import { Defs, G, LinearGradient, Path, Stop } from 'react-native-svg';
 
 import { isNumericScale } from '../../utils/scales/scales';
 import { useCartesianChartContext } from '../CartesianChart/context';
+import { useRevealClip } from '../CartesianChart/RevealClip';
 
 import type { LineProps } from './types';
 import { buildAreaPath, buildLinePath, toScaledPoints } from './utils';
@@ -18,6 +19,7 @@ export const Line = ({
 }: LineProps) => {
   const { getXScale, getYScale, getXAxisConfig, drawingArea, seriesMap } =
     useCartesianChartContext();
+  const clipPath = useRevealClip();
 
   const xScale = getXScale();
   const yScale = getYScale();
@@ -53,7 +55,7 @@ export const Line = ({
   }
 
   return (
-    <>
+    <G clipPath={clipPath}>
       {showArea && areaPath && resolvedStroke && (
         <>
           <Defs>
@@ -83,6 +85,6 @@ export const Line = ({
         strokeLinecap='round'
         strokeLinejoin='round'
       />
-    </>
+    </G>
   );
 };

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

@@ -76,4 +76,27 @@ describe('LineChart', () => {
     );
     expect(queryAllByTestId('line-area')).toHaveLength(0);
   });
+
+  it('renders with animate true by default', () => {
+    const { getByTestId } = render(
+      <LineChartWrapper>
+        <LineChart series={sampleSeries} width={400} height={200} />
+      </LineChartWrapper>,
+    );
+    getByTestId('chart-svg');
+  });
+
+  it('renders with animate false', () => {
+    const { getByTestId } = render(
+      <LineChartWrapper>
+        <LineChart
+          series={sampleSeries}
+          width={400}
+          height={200}
+          animate={false}
+        />
+      </LineChartWrapper>,
+    );
+    getByTestId('chart-svg');
+  });
 });

package/src/lib/Components/LineChart/LineChart.tsx

@@ -20,6 +20,9 @@ export const LineChart = ({
   height = 160,
   inset,
   children,
+  enableScrubbing = false,
+  onScrubberPositionChange,
+  animate,
 }: LineChartProps) => {
   const {
     scaleType: xScaleType,
@@ -77,6 +80,9 @@ export const LineChart = ({
       height={height}
       inset={inset}
       axisPadding={axisPadding}
+      enableScrubbing={enableScrubbing}
+      onScrubberPositionChange={onScrubberPositionChange}
+      animate={animate}
     >
       {showXAxis && <XAxis {...xAxisVisualProps} />}
       {showYAxis && <YAxis {...yAxisVisualProps} />}

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

@@ -60,4 +60,20 @@ export type LineChartProps = {
    * Additional SVG content rendered inside the chart after lines and axes.
    */
   children?: ReactNode;
+  /**
+   * Enables scrubbing (pan gesture) interactions on the chart.
+   * When true, add a `<Scrubber>` as a child to visualise the interaction.
+   * @default false
+   */
+  enableScrubbing?: boolean;
+  /**
+   * Callback fired whenever the scrubber moves to a new data index or is cleared.
+   * Receives `undefined` when the scrub gesture ends or the scrubber position is otherwise cleared.
+   */
+  onScrubberPositionChange?: (index: number | undefined) => void;
+  /**
+   * Whether to animate the chart on mount and data changes.
+   * @default true
+   */
+  animate?: boolean;
 };

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

@@ -4,6 +4,7 @@ import { Circle, G, Polygon, Text as SvgText } from 'react-native-svg';
 
 import { projectPoint } from '../../utils/scales/scales';
 import { useCartesianChartContext } from '../CartesianChart/context';
+import { useRevealClip } from '../CartesianChart/RevealClip';
 
 import type { PointLabelProps, PointProps } from './types';
 import {
@@ -46,6 +47,7 @@ export function Point({
   onPress,
 }: Readonly<PointProps>) {
   const { getXScale, getYScale, drawingArea } = useCartesianChartContext();
+  const clipPath = useRevealClip();
   const { theme } = useTheme();
 
   const xScale = getXScale();
@@ -71,7 +73,7 @@ export function Point({
   const Label = LabelComponent ?? PointLabel;
 
   return (
-    <G testID='point-group' onPress={onPress}>
+    <G testID='point-group' clipPath={clipPath} onPress={onPress}>
       {!hidePoint && (
         <Circle
           testID='point-circle'

package/src/lib/Components/ReferenceLine/ReferenceLine.stories.tsx

@@ -0,0 +1,109 @@
+import { useTheme } from '@ledgerhq/lumen-ui-rnative';
+import type { Meta, StoryObj } from '@storybook/react-native-web-vite';
+import { View } from 'react-native';
+
+import { StoryDecorator } from '../../../../.storybook/StoryDecorator.tsx';
+import { LineChart } from '../LineChart';
+
+import { ReferenceLine } from './ReferenceLine';
+
+const sampleSeries = [
+  {
+    id: 'prices',
+    stroke: '#7B61FF',
+    data: [10, 22, 29, 45, 98, 45, 22, 52, 21, 4, 68, 20, 21, 58],
+  },
+];
+
+const meta = {
+  component: ReferenceLine,
+  title: 'Visualization/ReferenceLine',
+  tags: ['experimental'],
+  decorators: [
+    (Story, context) => {
+      return (
+        <StoryDecorator context={context}>
+          <View style={{ width: 600, padding: 16 }}>
+            <Story />
+          </View>
+        </StoryDecorator>
+      );
+    },
+  ],
+} satisfies Meta<typeof ReferenceLine>;
+
+export default meta;
+type Story = StoryObj<typeof ReferenceLine>;
+
+export const HorizontalLine: Story = {
+  parameters: {
+    layout: 'centered',
+    backgrounds: { default: 'light' },
+  },
+  render: () => (
+    <LineChart series={sampleSeries} height={250} showArea>
+      <ReferenceLine
+        dataY={50}
+        label='Target'
+        labelDy={-4}
+        labelVerticalAlignment='start'
+        labelHorizontalAlignment='start'
+      />
+    </LineChart>
+  ),
+};
+
+export const VerticalLine: Story = {
+  parameters: {
+    layout: 'centered',
+    backgrounds: { default: 'light' },
+  },
+  render: () => (
+    <LineChart series={sampleSeries} height={250} showArea>
+      <ReferenceLine
+        dataX={7}
+        label='Midpoint'
+        labelDx={4}
+        labelHorizontalAlignment='end'
+        labelVerticalAlignment='end'
+        labelPosition='start'
+      />
+    </LineChart>
+  ),
+};
+
+export const Combined: Story = {
+  parameters: {
+    layout: 'centered',
+    backgrounds: { default: 'light' },
+  },
+  render: () => {
+    const { theme } = useTheme();
+    return (
+      <LineChart series={sampleSeries} height={250} showArea>
+        <ReferenceLine
+          dataY={98}
+          label='ATH'
+          labelDy={4}
+          labelVerticalAlignment='start'
+          stroke={theme.colors.border.success}
+        />
+        <ReferenceLine
+          dataY={4}
+          label='Low'
+          labelDy={-4}
+          labelVerticalAlignment='end'
+          stroke={theme.colors.border.error}
+        />
+        <ReferenceLine
+          dataX={4}
+          label='Peak'
+          labelDx={8}
+          labelDy={8}
+          labelHorizontalAlignment='end'
+          labelPosition='start'
+        />
+      </LineChart>
+    );
+  },
+};