@ledgerhq/lumen-ui-rnative-visualization 0.1.2 → 0.1.3

package/src/lib/utils/domain/domain.ts

@@ -0,0 +1,101 @@
+import type { AxisBounds, AxisConfigProps, Series } from '../types';
+
+/**
+ * Compute the X domain (index-based) from series data and axis config.
+ * For the X axis the domain is typically 0..N-1 where N = longest series length,
+ * unless explicit `data` is provided on the axis config.
+ */
+export const computeXDomain = (
+  series: Series[],
+  axisConfig?: Partial<AxisConfigProps>,
+): AxisBounds => {
+  const axisData = axisConfig?.data;
+
+  let autoBounds: AxisBounds;
+
+  if (axisData && axisData.length > 0) {
+    if (typeof axisData[0] === 'number') {
+      const nums = axisData as number[];
+      let min = nums[0];
+      let max = nums[0];
+      for (let i = 1; i < nums.length; i += 1) {
+        const value = nums[i];
+        if (value < min) min = value;
+        if (value > max) max = value;
+      }
+      autoBounds = { min, max };
+    } else {
+      autoBounds = { min: 0, max: axisData.length - 1 };
+    }
+  } else {
+    const maxLen = series.reduce(
+      (max, s) => Math.max(max, s.data?.length ?? 0),
+      0,
+    );
+    autoBounds = { min: 0, max: Math.max(0, maxLen - 1) };
+  }
+
+  return applyDomainOverride(autoBounds, axisConfig?.domain);
+};
+
+/**
+ * Compute the Y domain (value-based) from series data and axis config.
+ * Scans all non-null values across all series to find min/max.
+ */
+export const computeYDomain = (
+  series: Series[],
+  axisConfig?: Partial<AxisConfigProps>,
+): AxisBounds => {
+  let min = 0;
+  let max = 0;
+  let hasValue = false;
+
+  for (const s of series) {
+    if (!s.data) continue;
+    for (const v of s.data) {
+      if (v !== null && v !== undefined) {
+        if (!hasValue) {
+          min = v;
+          max = v;
+          hasValue = true;
+        } else {
+          if (v < min) min = v;
+          if (v > max) max = v;
+        }
+      }
+    }
+  }
+
+  const autoBounds: AxisBounds = hasValue ? { min, max } : { min: 0, max: 1 };
+
+  return applyDomainOverride(autoBounds, axisConfig?.domain);
+};
+
+/**
+ * Compute the data length (number of discrete positions on the index axis).
+ */
+export const computeDataLength = (
+  series: Series[],
+  axisConfig?: Partial<AxisConfigProps>,
+): number => {
+  if (axisConfig?.data && axisConfig.data.length > 0) {
+    return axisConfig.data.length;
+  }
+  return series.reduce((max, s) => Math.max(max, s.data?.length ?? 0), 0);
+};
+
+const applyDomainOverride = (
+  autoBounds: AxisBounds,
+  domainOverride?: AxisConfigProps['domain'],
+): AxisBounds => {
+  if (!domainOverride) return autoBounds;
+
+  if (typeof domainOverride === 'function') {
+    return domainOverride(autoBounds);
+  }
+
+  return {
+    min: domainOverride.min ?? autoBounds.min,
+    max: domainOverride.max ?? autoBounds.max,
+  };
+};

package/src/lib/utils/index.ts

@@ -1 +1,11 @@
-export * from './types';
+export type {
+  AxisBounds,
+  AxisConfigProps,
+  CartesianChartContextValue,
+  CategoricalScale,
+  ChartInset,
+  ChartScaleFunction,
+  DrawingArea,
+  NumericScale,
+  Series,
+} from './types';

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

@@ -0,0 +1,133 @@
+import { describe, expect, it } from '@jest/globals';
+
+import {
+  getCategoricalScale,
+  getNumericScale,
+  isBandScaleType,
+  isCategoricalScale,
+  isNumericScale,
+} from './scales';
+
+describe('getNumericScale', () => {
+  it('should create a linear scale mapping domain to range', () => {
+    const scale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 100 },
+      range: { min: 0, max: 500 },
+    });
+    expect(scale(0)).toBe(0);
+    expect(scale(50)).toBe(250);
+    expect(scale(100)).toBe(500);
+  });
+
+  it('should create a log scale', () => {
+    const scale = getNumericScale({
+      scaleType: 'log',
+      domain: { min: 1, max: 1000 },
+      range: { min: 0, max: 300 },
+    });
+    expect(scale(1)).toBe(0);
+    expect(scale(1000)).toBe(300);
+  });
+
+  it('should set correct domain', () => {
+    const scale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 10, max: 50 },
+      range: { min: 0, max: 200 },
+    });
+    const domain = scale.domain();
+    expect(domain[0]).toBe(10);
+    expect(domain[1]).toBe(50);
+  });
+
+  it('should set correct range', () => {
+    const scale = getNumericScale({
+      scaleType: 'linear',
+      domain: { min: 0, max: 100 },
+      range: { min: 20, max: 400 },
+    });
+    const range = scale.range();
+    expect(range[0]).toBe(20);
+    expect(range[1]).toBe(400);
+  });
+});
+
+describe('getCategoricalScale', () => {
+  it('should create a band scale with correct domain', () => {
+    const scale = getCategoricalScale({
+      domain: { min: 0, max: 3 },
+      range: { min: 0, max: 400 },
+      padding: 0,
+    });
+    expect(scale.domain()).toEqual([0, 1, 2, 3]);
+  });
+
+  it('should have non-zero bandwidth', () => {
+    const scale = getCategoricalScale({
+      domain: { min: 0, max: 4 },
+      range: { min: 0, max: 500 },
+    });
+    expect(scale.bandwidth()).toBeGreaterThan(0);
+  });
+
+  it('should map values within the range', () => {
+    const scale = getCategoricalScale({
+      domain: { min: 0, max: 2 },
+      range: { min: 0, max: 300 },
+      padding: 0,
+    });
+    expect(scale(0)).toBeGreaterThanOrEqual(0);
+    expect((scale(2) ?? 0) + scale.bandwidth()).toBeLessThanOrEqual(300);
+  });
+
+  it('should handle custom domain offset', () => {
+    const scale = getCategoricalScale({
+      domain: { min: 5, max: 7 },
+      range: { min: 0, max: 300 },
+      padding: 0,
+    });
+    expect(scale.domain()).toEqual([5, 6, 7]);
+  });
+});
+
+describe('isBandScaleType', () => {
+  it('should return true for band scale type', () => {
+    expect(isBandScaleType('band')).toBe(true);
+  });
+
+  it('should return false for linear scale type', () => {
+    expect(isBandScaleType('linear')).toBe(false);
+  });
+
+  it('should return false for log scale type', () => {
+    expect(isBandScaleType('log')).toBe(false);
+  });
+
+  it('should return false for undefined', () => {
+    expect(isBandScaleType(undefined)).toBe(false);
+  });
+});
+
+describe('isCategoricalScale / isNumericScale', () => {
+  const numericScale = getNumericScale({
+    scaleType: 'linear',
+    domain: { min: 0, max: 100 },
+    range: { min: 0, max: 500 },
+  });
+
+  const bandScale = getCategoricalScale({
+    domain: { min: 0, max: 4 },
+    range: { min: 0, max: 500 },
+  });
+
+  it('should identify a numeric scale', () => {
+    expect(isNumericScale(numericScale)).toBe(true);
+    expect(isCategoricalScale(numericScale)).toBe(false);
+  });
+
+  it('should identify a categorical scale', () => {
+    expect(isCategoricalScale(bandScale)).toBe(true);
+    expect(isNumericScale(bandScale)).toBe(false);
+  });
+});

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

@@ -0,0 +1,67 @@
+import { scaleBand, scaleLinear, scaleLog } from 'd3-scale';
+
+import type {
+  AxisBounds,
+  AxisConfigProps,
+  CategoricalScale,
+  ChartScaleFunction,
+  NumericScale,
+} from '../types';
+
+export const getNumericScale = ({
+  scaleType,
+  domain,
+  range,
+}: {
+  scaleType: 'linear' | 'log';
+  domain: AxisBounds;
+  range: AxisBounds;
+}): NumericScale => {
+  const scale = scaleType === 'log' ? scaleLog() : scaleLinear();
+  return scale.domain([domain.min, domain.max]).range([range.min, range.max]);
+};
+
+export const getCategoricalScale = ({
+  domain,
+  range,
+  padding = 0.1,
+}: {
+  domain: AxisBounds;
+  range: AxisBounds;
+  padding?: number;
+}): CategoricalScale => {
+  const domainArray = Array.from(
+    { length: domain.max - domain.min + 1 },
+    (_, i) => domain.min + i,
+  );
+  return scaleBand<number>()
+    .domain(domainArray)
+    .range([range.min, range.max])
+    .paddingInner(padding)
+    .paddingOuter(padding / 2);
+};
+
+/**
+ * Checks if a scale type config value refers to a band (categorical) scale.
+ */
+export const isBandScaleType = (
+  scaleType: AxisConfigProps['scaleType'],
+): scaleType is 'band' => scaleType === 'band';
+
+/**
+ * Checks if a scale is a categorical scale.
+ */
+export const isCategoricalScale = (
+  scale: ChartScaleFunction,
+): scale is CategoricalScale => {
+  return 'bandwidth' in scale && typeof scale.bandwidth === 'function';
+};
+
+/**
+ * Checks if a scale is a numeric scale.
+ */
+export const isNumericScale = (
+  scale: ChartScaleFunction,
+): scale is NumericScale => {
+  return !isCategoricalScale(scale);
+};

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

@@ -0,0 +1,136 @@
+import { describe, expect, it, jest } from '@jest/globals';
+
+import { getCategoricalScale, getNumericScale } from '../scales/scales';
+
+import {
+  buildTicksData,
+  getTickLabel,
+  getTickPosition,
+  getTickValues,
+} from './ticks';
+
+const numericScale = getNumericScale({
+  scaleType: 'linear',
+  domain: { min: 0, max: 100 },
+  range: { min: 0, max: 500 },
+});
+
+const bandScale = getCategoricalScale({
+  domain: { min: 0, max: 4 },
+  range: { min: 0, max: 500 },
+  padding: 0,
+});
+
+describe('getTickValues', () => {
+  it('should return explicit ticks when provided', () => {
+    expect(getTickValues(numericScale, [0, 25, 50])).toEqual([0, 25, 50]);
+  });
+
+  it('should return scale.ticks() for numeric scales', () => {
+    const ticks = getTickValues(numericScale);
+    expect(ticks.length).toBeGreaterThan(0);
+    expect(ticks).toContain(0);
+    expect(ticks).toContain(100);
+  });
+
+  it('should return full domain for band scales', () => {
+    expect(getTickValues(bandScale)).toEqual([0, 1, 2, 3, 4]);
+  });
+});
+
+describe('getTickPosition', () => {
+  it('should map value through numeric scale', () => {
+    expect(getTickPosition(numericScale, 0)).toBe(0);
+    expect(getTickPosition(numericScale, 50)).toBe(250);
+    expect(getTickPosition(numericScale, 100)).toBe(500);
+  });
+
+  it('should center within band for categorical scale', () => {
+    const pos = getTickPosition(bandScale, 0);
+    const bandwidth = bandScale.bandwidth();
+    expect(pos).toBe((bandScale(0) ?? 0) + bandwidth / 2);
+  });
+});
+
+describe('getTickLabel', () => {
+  it('should return stringified tick value by default', () => {
+    expect(getTickLabel(42, undefined)).toBe('42');
+  });
+
+  it('should look up string labels from axis data', () => {
+    const axisData = ['Jan', 'Feb', 'Mar'];
+    expect(getTickLabel(0, axisData)).toBe('Jan');
+    expect(getTickLabel(1, axisData)).toBe('Feb');
+  });
+
+  it('should fall back to tick value when index is out of range', () => {
+    const axisData = ['Jan', 'Feb'];
+    expect(getTickLabel(5, axisData)).toBe('5');
+  });
+
+  it('should apply formatter with raw string label when available', () => {
+    const axisData = ['January', 'February'];
+    const formatter = jest.fn(
+      (v: number | string) => `${String(v).slice(0, 3)}`,
+    );
+
+    expect(getTickLabel(0, axisData, formatter)).toBe('Jan');
+    expect(formatter).toHaveBeenCalledWith('January');
+  });
+
+  it('should apply formatter with numeric value when no string labels', () => {
+    const formatter = jest.fn((v: number | string) => `$${v}`);
+
+    expect(getTickLabel(10, undefined, formatter)).toBe('$10');
+    expect(formatter).toHaveBeenCalledWith(10);
+  });
+
+  it('should apply formatter with numeric data', () => {
+    const axisData = [100, 200, 300];
+    const formatter = jest.fn((v: number | string) => `${v}!`);
+
+    expect(getTickLabel(1, axisData, formatter)).toBe('1!');
+    expect(formatter).toHaveBeenCalledWith(1);
+  });
+});
+
+describe('buildTicksData', () => {
+  it('should combine position, value, and label for each tick', () => {
+    const result = buildTicksData(numericScale);
+    expect(result.length).toBeGreaterThan(0);
+    for (const tick of result) {
+      expect(tick).toHaveProperty('position');
+      expect(tick).toHaveProperty('value');
+      expect(tick).toHaveProperty('label');
+      expect(typeof tick.position).toBe('number');
+      expect(typeof tick.label).toBe('string');
+    }
+  });
+
+  it('should use explicit ticks when provided', () => {
+    const result = buildTicksData(numericScale, undefined, [0, 50, 100]);
+    expect(result).toHaveLength(3);
+    expect(result.map((t: { value: number }) => t.value)).toEqual([0, 50, 100]);
+  });
+
+  it('should resolve string labels from axis config', () => {
+    const result = buildTicksData(bandScale, {
+      data: ['Mon', 'Tue', 'Wed', 'Thu', 'Fri'],
+    });
+    expect(result[0].label).toBe('Mon');
+    expect(result[1].label).toBe('Tue');
+  });
+
+  it('should apply tick formatter', () => {
+    const formatter = (v: number | string): string => `$${v}`;
+    const result = buildTicksData(numericScale, undefined, [0, 50], formatter);
+    expect(result[0].label).toBe('$0');
+    expect(result[1].label).toBe('$50');
+  });
+
+  it('should compute correct positions for numeric scale', () => {
+    const result = buildTicksData(numericScale, undefined, [0, 100]);
+    expect(result[0].position).toBe(0);
+    expect(result[1].position).toBe(500);
+  });
+});

package/src/lib/utils/ticks/ticks.ts

@@ -0,0 +1,82 @@
+import { isCategoricalScale, isNumericScale } from '../scales/scales';
+import type { AxisConfigProps, ChartScaleFunction } from '../types';
+
+export const APPROXIMATE_TICK_COUNT = 5;
+
+export type TickData = {
+  position: number;
+  value: number;
+  label: string;
+};
+
+/**
+ * Resolves which numeric tick values should appear on the axis.
+ * Explicit ticks take priority, then scale-specific defaults.
+ */
+export const getTickValues = (
+  scale: ChartScaleFunction,
+  explicitTicks?: number[],
+): number[] => {
+  if (explicitTicks) return explicitTicks;
+  if (isCategoricalScale(scale)) return scale.domain();
+  if (isNumericScale(scale)) return scale.ticks(APPROXIMATE_TICK_COUNT);
+  return [];
+};
+
+/**
+ * Converts a tick value to its pixel position on the axis.
+ * Band scales are centered within the band.
+ */
+export const getTickPosition = (
+  scale: ChartScaleFunction,
+  tick: number,
+): number => {
+  if (isCategoricalScale(scale)) {
+    return (scale(tick) ?? 0) + scale.bandwidth() / 2;
+  }
+  return (scale as (v: number) => number)(tick);
+};
+
+/**
+ * Resolves the display label for a tick value.
+ * Priority: formatter > string label lookup > raw value.
+ */
+export const getTickLabel = (
+  tick: number,
+  axisData: AxisConfigProps['data'],
+  formatter?: (value: number | string) => string,
+): string => {
+  const hasStringLabels =
+    axisData && Array.isArray(axisData) && typeof axisData[0] === 'string';
+
+  if (formatter) {
+    const rawValue =
+      hasStringLabels && axisData[tick] !== undefined ? axisData[tick] : tick;
+    return String(formatter(rawValue as number | string));
+  }
+
+  if (hasStringLabels && axisData[tick] !== undefined) {
+    return String(axisData[tick]);
+  }
+
+  return String(tick);
+};
+
+/**
+ * Builds the complete tick data array from a scale and axis configuration.
+ */
+export const buildTicksData = (
+  scale: ChartScaleFunction,
+  axisConfig?: AxisConfigProps,
+  explicitTicks?: number[],
+  formatter?: (value: number | string) => string,
+): TickData[] => {
+  const tickValues = getTickValues(scale, explicitTicks);
+  const axisData = axisConfig?.data;
+
+  return tickValues.map((tick) => ({
+    position: getTickPosition(scale, tick),
+    value: tick,
+    label: getTickLabel(tick, axisData, formatter),
+  }));
+};

package/src/lib/utils/types.ts

@@ -1,11 +1,102 @@
-export type DataPoint = {
-  timestamp: number;
-  value: number;
+import type { ScaleBand, ScaleLinear, ScaleLogarithmic } from 'd3-scale';
+
+export type AxisBounds = { min: number; max: number };
+
+export type ChartInset = {
+  top: number;
+  right: number;
+  bottom: number;
+  left: number;
+};
+
+/**
+ * Pixel bounds of the drawable region.
+ */
+export type DrawingArea = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
 };
 
 export type Series = {
+  /**
+   * Unique identifier for the series.
+   */
   id: string;
-  label: string;
-  data: DataPoint[];
-  color?: string;
+  /**
+   * Numeric data points; `null` entries represent gaps.
+   */
+  data?: Array<number | null>;
+  /**
+   * Human-readable label used in legends and tooltips.
+   */
+  label?: string;
+  /**
+   * CSS color applied to the series line/mark.
+   */
+  stroke: string;
+};
+
+export type AxisConfigProps = {
+  /**
+   * Scale algorithm used by this axis.
+   * @default 'linear'
+   */
+  scaleType?: 'linear' | 'log' | 'band';
+  /**
+   * Explicit data values for band scales or category labels.
+   * For band scales, provides the discrete domain. For numeric scales, string values
+   * are used as tick labels at corresponding indices.
+   */
+  data?: string[] | number[];
+  /**
+   * Fixed domain bounds or a function that adjusts the computed bounds.
+   * A partial object overrides only the specified bound(s).
+   * A function receives the auto-computed bounds and returns adjusted ones.
+   */
+  domain?: Partial<AxisBounds> | ((bounds: AxisBounds) => AxisBounds);
+};
+
+export type NumericScale =
+  | ScaleLinear<number, number>
+  | ScaleLogarithmic<number, number>;
+
+export type CategoricalScale = ScaleBand<number>;
+
+export type ChartScaleFunction = NumericScale | CategoricalScale;
+
+export type CartesianChartContextValue = {
+  /**
+   * All data series registered in the chart.
+   */
+  series: Series[];
+  /**
+   * Lookup map for series by ID. Stable reference when series identity is unchanged.
+   */
+  seriesMap: Map<string, Series>;
+  /**
+   * Returns the x-axis scale. Accepts an optional axis ID for future multi-axis support.
+   */
+  getXScale: (id?: string) => ChartScaleFunction | undefined;
+  /**
+   * Returns the y-axis scale. Accepts an optional axis ID for future multi-axis support.
+   */
+  getYScale: (id?: string) => ChartScaleFunction | undefined;
+  /**
+   * Returns the x-axis config. Accepts an optional axis ID for future multi-axis support.
+   */
+  getXAxisConfig: (id?: string) => AxisConfigProps | undefined;
+  /**
+   * Returns the y-axis config. Accepts an optional axis ID for future multi-axis support.
+   */
+  getYAxisConfig: (id?: string) => AxisConfigProps | undefined;
+  /**
+   * Pixel bounds of the drawable region.
+   */
+  drawingArea: DrawingArea;
+  /**
+   * Number of data points along the x-axis.
+   */
+  dataLength: number;
 };

package/dist/module/lib/utils/math/index.js

@@ -1,4 +0,0 @@
-// Math abstractions for building chart shapes (d3-based utilities).
-// This module will contain scale, interpolation, and path generation helpers.
-"use strict";
-//# sourceMappingURL=index.js.map

package/dist/module/lib/utils/math/index.js.map

@@ -1 +0,0 @@
-{"version":3,"names":[],"sourceRoot":"../../../../../src","sources":["lib/utils/math/index.ts"],"mappings":"AAAA;AACA;AAAA","ignoreList":[]}

package/dist/typescript/src/lib/utils/math/index.d.ts

@@ -1 +0,0 @@
-//# sourceMappingURL=index.d.ts.map

package/dist/typescript/src/lib/utils/math/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../../../src/lib/utils/math/index.ts"],"names":[],"mappings":""}

package/src/lib/utils/math/index.ts

@@ -1,2 +0,0 @@
-// Math abstractions for building chart shapes (d3-based utilities).
-// This module will contain scale, interpolation, and path generation helpers.