@coinbase/cds-mobile-visualization 3.4.0-beta.8 → 3.4.0

package/esm/chart/utils/chart.js

@@ -1,6 +1,19 @@
 import { isSharedValue } from 'react-native-reanimated';
 import { stack as d3Stack, stackOffsetDiverging, stackOrderNone } from 'd3-shape';
 export const defaultStackId = 'DEFAULT_STACK_ID';
+
+/**
+ * Shape variants available for legend items.
+ */
+
+/**
+ * Shape for legend items. Can be a preset variant or a custom ReactNode.
+ */
+
+/**
+ * Position of the legend relative to the chart.
+ */
+
 /**
  * Type guard to check if bounds are complete with both min and max values.
  * @param bounds - The bounds to validate
@@ -33,15 +46,16 @@ export const getChartDomain = (series, min, max) => {
 };
 
 /**
- * Creates a composite stack key that includes both stack ID and y-axis ID.
- * This ensures series with different y-scales don't get stacked together.
+ * Creates a composite stack key that includes stack ID and axis IDs.
+ * This ensures series with different scales don't get stacked together.
  */
 const createStackKey = series => {
   if (series.stackId === undefined) return undefined;
 
-  // Include y-axis ID to prevent cross-scale stacking
+  // Include axis IDs to prevent cross-scale stacking
+  const xAxisId = series.xAxisId || 'default';
   const yAxisId = series.yAxisId || 'default';
-  return series.stackId + ":" + yAxisId;
+  return series.stackId + ":" + xAxisId + ":" + yAxisId;
 };
 
 /**
@@ -127,9 +141,9 @@ export const getLineData = data => {
   const firstNonNull = data.find(d => d !== null);
   if (Array.isArray(firstNonNull)) {
     return data.map(d => {
-      var _d$at;
+      var _d;
       if (d === null) return null;
-      if (Array.isArray(d)) return (_d$at = d.at(-1)) != null ? _d$at : null;
+      if (Array.isArray(d)) return (_d = d[d.length - 1]) != null ? _d : null;
       return d;
     });
   }
@@ -212,12 +226,25 @@ export const getChartRange = (series, min, max) => {
   }
   return range;
 };
-export const defaultChartInset = {
+export const defaultVerticalLayoutChartInset = {
   top: 32,
   left: 16,
   bottom: 16,
   right: 16
 };
+export const defaultHorizontalLayoutChartInset = {
+  top: 16,
+  left: 16,
+  bottom: 16,
+  right: 48
+};
+
+/**
+ * @deprecated Use `defaultVerticalLayoutChartInset` for vertical layout charts or. This will be removed in a future major release.
+ * @deprecationExpectedRemoval v4
+ * `defaultHorizontalLayoutChartInset` for horizontal layout charts.
+ */
+export const defaultChartInset = defaultVerticalLayoutChartInset;
 
 /**
  * Normalize padding to include all sides with a value.

package/esm/chart/utils/context.js

@@ -1,5 +1,12 @@
 import { createContext, useContext } from 'react';
 
+/**
+ * Chart layout for Cartesian charts.
+ * Describes the direction bars/areas grow.
+ * - 'vertical': Bars grow vertically (up/down). X is category axis, Y is value axis.
+ * - 'horizontal': Bars grow horizontally (left/right). Y is category axis, X is value axis.
+ */
+
 /**
  * Context value for Cartesian (X/Y) coordinate charts.
  * Contains axis-specific methods and properties for rectangular coordinate systems.

package/esm/chart/utils/gradient.js

@@ -262,9 +262,13 @@ export const getBaseline = function (axisBounds, baseline) {
  * @param fill - The color to use for the gradient
  * @param peakOpacity - Opacity at the peak of the gradient
  * @param baselineOpacity - Opacity at the baseline
- * @returns A gradient definition with y-axis stops in ascending order
+ * @param axis - The axis the gradient maps to ('y' for vertical, 'x' for horizontal layout)
+ * @returns A gradient definition with stops in ascending order
  */
-export const createGradient = (axisBounds, baselineValue, fill, peakOpacity, baselineOpacity) => {
+export const createGradient = function (axisBounds, baselineValue, fill, peakOpacity, baselineOpacity, axis) {
+  if (axis === void 0) {
+    axis = 'y';
+  }
   const {
     min,
     max
@@ -273,7 +277,7 @@ export const createGradient = (axisBounds, baselineValue, fill, peakOpacity, bas
   const upperBound = Math.max(min, max);
   if (lowerBound < baselineValue && baselineValue < upperBound) {
     return {
-      axis: 'y',
+      axis,
       stops: [{
         offset: lowerBound,
         color: fill,
@@ -291,7 +295,7 @@ export const createGradient = (axisBounds, baselineValue, fill, peakOpacity, bas
   }
   const peakValue = Math.abs(min - baselineValue) > Math.abs(max - baselineValue) ? min : max;
   return {
-    axis: 'y',
+    axis,
     stops: [{
       offset: peakValue,
       color: fill,

package/esm/chart/utils/path.js

@@ -1,22 +1,35 @@
-import { area as d3Area, curveBumpX, curveCatmullRom, curveLinear, curveLinearClosed, curveMonotoneX, curveNatural, curveStep, curveStepAfter, curveStepBefore, line as d3Line } from 'd3-shape';
-import { projectPoint, projectPoints } from './point';
+import { area as d3Area, curveBumpX, curveBumpY, curveCatmullRom, curveLinear, curveLinearClosed, curveMonotoneX, curveMonotoneY, curveNatural, curveStep, curveStepAfter, curveStepBefore, line as d3Line } from 'd3-shape';
+import { getPointOnScale, projectPoints } from './point';
 import { isCategoricalScale } from './scale';
+/**
+ * Default enter transition for path-based components (Line, Area).
+ * `{ type: 'timing', duration: 500 }`
+ */
+export const defaultPathEnterTransition = {
+  type: 'timing',
+  duration: 500
+};
 /**
  * Get the d3 curve function for a path.
  * See https://d3js.org/d3-shape/curve
  * @param curve - The curve type. Defaults to 'linear'.
+ * @param layout - The chart layout. Defaults to 'vertical'.
  * @returns The d3 curve function.
  */
-export const getPathCurveFunction = function (curve) {
+export const getPathCurveFunction = function (curve, layout) {
   if (curve === void 0) {
     curve = 'linear';
   }
+  if (layout === void 0) {
+    layout = 'vertical';
+  }
   switch (curve) {
     case 'catmullRom':
       return curveCatmullRom;
     case 'monotone':
-      // When we support layout="vertical" this should dynamically switch to curveMonotoneY
-      return curveMonotoneX;
+      // For vertical layout, X is the independent axis (category/index), so use MonotoneX.
+      // For horizontal layout, Y is the independent axis (category/index), so use MonotoneY.
+      return layout !== 'horizontal' ? curveMonotoneX : curveMonotoneY;
     case 'natural':
       return curveNatural;
     case 'step':
@@ -26,8 +39,9 @@ export const getPathCurveFunction = function (curve) {
     case 'stepAfter':
       return curveStepAfter;
     case 'bump':
-      // When we support layout="vertical" this should dynamically switch to curveBumpY
-      return curveBumpX;
+      // For vertical layout, X is the independent axis (category/index), so use BumpX.
+      // For horizontal layout, Y is the independent axis (category/index), so use BumpY.
+      return layout !== 'horizontal' ? curveBumpX : curveBumpY;
     case 'linearClosed':
       return curveLinearClosed;
     case 'linear':
@@ -53,17 +67,21 @@ export const getLinePath = _ref => {
     xScale,
     yScale,
     xData,
-    connectNulls = false
+    yData,
+    connectNulls = false,
+    layout = 'vertical'
   } = _ref;
   if (data.length === 0) {
     return '';
   }
-  const curveFunction = getPathCurveFunction(curve);
+  const curveFunction = getPathCurveFunction(curve, layout);
   const dataPoints = projectPoints({
     data,
     xScale,
     yScale,
-    xData
+    xData,
+    yData,
+    layout
   });
 
   // When connectNulls is true, filter out null values before rendering
@@ -102,14 +120,20 @@ export const getAreaPath = _ref2 => {
     xScale,
     yScale,
     xData,
-    connectNulls = false
+    yData,
+    connectNulls = false,
+    layout = 'vertical'
   } = _ref2;
   if (data.length === 0) {
     return '';
   }
-  const curveFunction = getPathCurveFunction(curve);
-  const yDomain = yScale.domain();
-  const yMin = Math.min(...yDomain);
+  const curveFunction = getPathCurveFunction(curve, layout);
+  const categoryAxisIsX = layout !== 'horizontal';
+
+  // Determine baseline from the value scale.
+  const valueScale = categoryAxisIsX ? yScale : xScale;
+  const domain = valueScale.domain();
+  const min = Math.min(...domain);
   const normalizedData = data.map((item, index) => {
     if (item === null) {
       return null;
@@ -121,7 +145,7 @@ export const getAreaPath = _ref2 => {
       return null;
     }
     if (typeof item === 'number') {
-      return [yMin, item];
+      return [min, item];
     }
     return null;
   });
@@ -129,37 +153,28 @@ export const getAreaPath = _ref2 => {
     if (range === null) {
       return {
         x: 0,
+        y: 0,
         low: null,
         high: null,
         isValid: false
       };
     }
-    let xValue = index;
-    if (!isCategoricalScale(xScale) && xData && xData[index] !== undefined) {
-      xValue = xData[index];
+
+    // Determine the position along the independent (index/category) axis.
+    let indexValue = index;
+    const indexScale = categoryAxisIsX ? xScale : yScale;
+    const indexData = categoryAxisIsX ? xData : yData;
+    if (!isCategoricalScale(indexScale) && indexData && indexData[index] !== undefined) {
+      indexValue = indexData[index];
     }
-    const xPoint = projectPoint({
-      x: xValue,
-      y: 0,
-      xScale,
-      yScale
-    });
-    const lowPoint = projectPoint({
-      x: xValue,
-      y: range[0],
-      xScale,
-      yScale
-    });
-    const highPoint = projectPoint({
-      x: xValue,
-      y: range[1],
-      xScale,
-      yScale
-    });
+    const position = getPointOnScale(indexValue, indexScale);
+    const low = getPointOnScale(range[0], valueScale);
+    const high = getPointOnScale(range[1], valueScale);
     return {
-      x: xPoint.x,
-      low: lowPoint.y,
-      high: highPoint.y,
+      x: categoryAxisIsX ? position : 0,
+      y: !categoryAxisIsX ? position : 0,
+      low,
+      high,
       isValid: true
     };
   });
@@ -167,16 +182,25 @@ export const getAreaPath = _ref2 => {
   // When connectNulls is true, filter out invalid points before rendering
   // When false, use defined() to create gaps in the area
   const filteredPoints = connectNulls ? dataPoints.filter(d => d.isValid) : dataPoints;
-  const areaGenerator = d3Area().x(d => d.x).y0(d => {
-    var _d$low;
-    return (_d$low = d.low) != null ? _d$low : 0;
-  }) // Bottom boundary (low values), fallback to 0
-  .y1(d => {
-    var _d$high;
-    return (_d$high = d.high) != null ? _d$high : 0;
-  }) // Top boundary (high values), fallback to 0
-  .curve(curveFunction).defined(d => connectNulls || d.isValid && d.low != null && d.high != null); // Only draw where both values exist
-
+  const areaGenerator = d3Area();
+  if (categoryAxisIsX) {
+    areaGenerator.x(d => d.x).y0(d => {
+      var _d$low;
+      return (_d$low = d.low) != null ? _d$low : 0;
+    }).y1(d => {
+      var _d$high;
+      return (_d$high = d.high) != null ? _d$high : 0;
+    });
+  } else {
+    areaGenerator.y(d => d.y).x0(d => {
+      var _d$low2;
+      return (_d$low2 = d.low) != null ? _d$low2 : 0;
+    }).x1(d => {
+      var _d$high2;
+      return (_d$high2 = d.high) != null ? _d$high2 : 0;
+    });
+  }
+  areaGenerator.curve(curveFunction).defined(d => connectNulls || d.isValid && d.low != null && d.high != null);
   const result = areaGenerator(filteredPoints);
   return result != null ? result : '';
 };
@@ -208,22 +232,28 @@ export const lineToPath = (x1, y1, x2, y2) => {
  * const roundedPath = getBarPath(10, 20, 50, 100, 8, true, false);
  * ```
  */
-export const getBarPath = (x, y, width, height, radius, roundTop, roundBottom) => {
+export const getBarPath = function (x, y, width, height, radius, roundTop, roundBottom, layout) {
+  if (layout === void 0) {
+    layout = 'vertical';
+  }
+  const isVerticalLayout = layout === 'vertical';
   const roundBothSides = roundTop && roundBottom;
   const r = Math.min(radius, width / 2, roundBothSides ? height / 2 : height);
-  const topR = roundTop ? r : 0;
-  const bottomR = roundBottom ? r : 0;
+  const rTL = isVerticalLayout ? roundTop ? r : 0 : roundBottom ? r : 0;
+  const rTR = isVerticalLayout ? roundTop ? r : 0 : roundTop ? r : 0;
+  const rBR = isVerticalLayout ? roundBottom ? r : 0 : roundTop ? r : 0;
+  const rBL = isVerticalLayout ? roundBottom ? r : 0 : roundBottom ? r : 0;
 
   // Build path with selective rounding
-  let path = "M " + (x + (roundTop ? r : 0)) + " " + y;
-  path += " L " + (x + width - topR) + " " + y;
-  path += " A " + topR + " " + topR + " 0 0 1 " + (x + width) + " " + (y + topR);
-  path += " L " + (x + width) + " " + (y + height - bottomR);
-  path += " A " + bottomR + " " + bottomR + " 0 0 1 " + (x + width - bottomR) + " " + (y + height);
-  path += " L " + (x + bottomR) + " " + (y + height);
-  path += " A " + bottomR + " " + bottomR + " 0 0 1 " + x + " " + (y + height - bottomR);
-  path += " L " + x + " " + (y + topR);
-  path += " A " + topR + " " + topR + " 0 0 1 " + (x + topR) + " " + y;
+  let path = "M " + (x + rTL) + " " + y;
+  path += " L " + (x + width - rTR) + " " + y;
+  path += " A " + rTR + " " + rTR + " 0 0 1 " + (x + width) + " " + (y + rTR);
+  path += " L " + (x + width) + " " + (y + height - rBR);
+  path += " A " + rBR + " " + rBR + " 0 0 1 " + (x + width - rBR) + " " + (y + height);
+  path += " L " + (x + rBL) + " " + (y + height);
+  path += " A " + rBL + " " + rBL + " 0 0 1 " + x + " " + (y + height - rBL);
+  path += " L " + x + " " + (y + rTL);
+  path += " A " + rTL + " " + rTL + " 0 0 1 " + (x + rTL) + " " + y;
   path += ' Z';
   return path;
 };

package/esm/chart/utils/point.js

@@ -1,4 +1,4 @@
-import { applySerializableScale, isCategoricalScale, isLogScale, isNumericScale } from './scale';
+import { applyBandScale, applySerializableScale, isCategoricalScale, isLogScale } from './scale';
 
 /**
  * Position a label should be placed relative to the point
@@ -10,19 +10,38 @@ import { applySerializableScale, isCategoricalScale, isLogScale, isNumericScale
 
 /**
  * Get a point from a data value and a scale.
- * @note for categorical scales, the point will be centered within the band.
- * @note for log scales, zero and negative values are clamped to a small positive value.
- * @param data - the data value.
- * @param scale - the scale function.
- * @returns the pixel value (defaulting to 0 if data value is not defined in scale).
+ *
+ * @param dataValue - The data value to convert to a pixel position.
+ * @param scale - The scale function.
+ * @param anchor (@default 'middle') - For band scales, where to anchor the point within the band.
+ * @returns The pixel value (@default 0 if data value is not defined in scale).
  */
-export const getPointOnScale = (dataValue, scale) => {
-  var _scale2;
+export const getPointOnScale = function (dataValue, scale, anchor) {
+  var _scale;
+  if (anchor === void 0) {
+    anchor = 'middle';
+  }
   if (isCategoricalScale(scale)) {
-    var _scale, _scale$bandwidth;
-    const bandStart = (_scale = scale(dataValue)) != null ? _scale : 0;
-    const bandwidth = (_scale$bandwidth = scale.bandwidth()) != null ? _scale$bandwidth : 0;
-    return bandStart + bandwidth / 2;
+    var _bandScale$bandwidth, _bandScale$step;
+    const bandScale = scale;
+    const bandStart = bandScale(dataValue);
+    if (bandStart === undefined) return 0;
+    const bandwidth = (_bandScale$bandwidth = bandScale.bandwidth == null ? void 0 : bandScale.bandwidth()) != null ? _bandScale$bandwidth : 0;
+    const step = (_bandScale$step = bandScale.step == null ? void 0 : bandScale.step()) != null ? _bandScale$step : bandwidth;
+    const paddingOffset = (step - bandwidth) / 2;
+    const stepStart = bandStart - paddingOffset;
+    switch (anchor) {
+      case 'stepStart':
+        return stepStart;
+      case 'bandStart':
+        return bandStart;
+      case 'middle':
+        return bandStart + bandwidth / 2;
+      case 'bandEnd':
+        return bandStart + bandwidth;
+      case 'stepEnd':
+        return stepStart + step;
+    }
   }
 
   // For log scales, ensure the value is positive
@@ -30,23 +49,47 @@ export const getPointOnScale = (dataValue, scale) => {
   if (isLogScale(scale) && dataValue <= 0) {
     adjustedValue = 0.001; // Use a small positive value for log scales
   }
-  return (_scale2 = scale(adjustedValue)) != null ? _scale2 : 0;
+  return (_scale = scale(adjustedValue)) != null ? _scale : 0;
 };
 
 /**
  * Get a point from a data value and a serializable scale (worklet-compatible).
- * @note for categorical scales, the point will be centered within the band.
- * @note for log scales, zero and negative values are clamped to a small positive value.
- * @param dataValue - the data value.
- * @param scale - the serializable scale object.
- * @returns the pixel value (defaulting to 0 if data value is not defined in scale).
+ *
+ * @param dataValue - The data value to convert to a pixel position.
+ * @param scale - The serializable scale function.
+ * @param anchor (@default 'middle') - For band scales, where to anchor the point within the band.
+ * @returns The pixel value (@default 0 if data value is not defined in scale).
  */
-export function getPointOnSerializableScale(dataValue, scale) {
+export function getPointOnSerializableScale(dataValue, scale, anchor) {
   'worklet';
 
+  // Handle band scales with the specified position
+  if (anchor === void 0) {
+    anchor = 'middle';
+  }
   if (scale.type === 'band') {
-    const bandStart = applySerializableScale(dataValue, scale);
-    return bandStart + scale.bandwidth / 2;
+    const bandScale = scale;
+    const [domainMin, domainMax] = bandScale.domain;
+    const index = dataValue - domainMin;
+    const n = domainMax - domainMin + 1;
+    if (index < 0 || index >= n) {
+      return 0;
+    }
+    const bandStart = applyBandScale(dataValue, bandScale);
+    const paddingOffset = (bandScale.step - bandScale.bandwidth) / 2;
+    const stepStart = bandStart - paddingOffset;
+    switch (anchor) {
+      case 'stepStart':
+        return stepStart;
+      case 'bandStart':
+        return bandStart;
+      case 'middle':
+        return bandStart + bandScale.bandwidth / 2;
+      case 'bandEnd':
+        return bandStart + bandScale.bandwidth;
+      case 'stepEnd':
+        return stepStart + bandScale.step;
+    }
   }
 
   // For log scales, ensure the value is positive
@@ -121,7 +164,8 @@ export const projectPoints = _ref3 => {
     xScale,
     yScale,
     xData,
-    yData
+    yData,
+    layout = 'vertical'
   } = _ref3;
   if (data.length === 0) {
     return [];
@@ -139,28 +183,37 @@ export const projectPoints = _ref3 => {
       });
     }
 
-    // For scales with axis data, determine the correct x value
-    let xValue = index;
-
-    // For band scales, always use the index
-    if (!isCategoricalScale(xScale)) {
-      // For numeric scales with axis data, use the axis data values instead of indices
-      if (xData && Array.isArray(xData) && xData.length > 0) {
-        // Check if it's numeric data
-        if (typeof xData[0] === 'number') {
-          var _numericXData$index;
-          const numericXData = xData;
-          xValue = (_numericXData$index = numericXData[index]) != null ? _numericXData$index : index;
+    // Determine values/scales based on role (index vs value) and layout.
+    const categoryAxisIsX = layout !== 'horizontal';
+    const indexScale = categoryAxisIsX ? xScale : yScale;
+    const indexData = categoryAxisIsX ? xData : yData;
+
+    // 1. Calculate position along the index axis (categorical or numeric domain).
+    let indexValue = index;
+    if (!isCategoricalScale(indexScale)) {
+      if (indexData && Array.isArray(indexData) && indexData.length > 0) {
+        if (typeof indexData[0] === 'number') {
+          var _indexData$index;
+          indexValue = (_indexData$index = indexData[index]) != null ? _indexData$index : index;
         }
       }
     }
-    let yValue = value;
-    if (isNumericScale(yScale) && yData && Array.isArray(yData) && yData.length > 0 && typeof yData[0] === 'number' && typeof value === 'number') {
-      yValue = value;
+
+    // 2. Calculate position along the value axis (measured magnitude).
+    const valueAsNumber = value;
+
+    // 3. Project final coordinates based on layout.
+    if (categoryAxisIsX) {
+      return projectPoint({
+        x: indexValue,
+        y: valueAsNumber,
+        xScale,
+        yScale
+      });
     }
     return projectPoint({
-      x: xValue,
-      y: yValue,
+      x: valueAsNumber,
+      y: indexValue,
       xScale,
       yScale
     });

package/esm/chart/utils/scale.js

@@ -53,10 +53,21 @@ export const getCategoricalScale = _ref2 => {
   const domainArray = Array.from({
     length: domain.max - domain.min + 1
   }, (_, i) => i);
-  const scale = scaleBand().domain(domainArray).range([range.min, range.max]).padding(padding);
+  const scale = scaleBand().domain(domainArray).range([range.min, range.max]).paddingInner(padding).paddingOuter(padding / 2);
   return scale;
 };
 
+/**
+ * Anchor position for points on a scale. Currently used only for band scales.
+ *
+ * For band scales, this determines where within the band to position a point:
+ * - `'stepStart'` - At the start of the step
+ * - `'bandStart'` - At the start of the band
+ * - `'middle'` - At the center of the band
+ * - `'bandEnd'` - At the end of the band
+ * - `'stepEnd'` - At the end of the step
+ */
+
 /**
  * Convert a D3 scale to a serializable scale configuration that can be used in worklets
  */
@@ -176,7 +187,7 @@ export function applyBandScale(value, scale) {
   if (index < 0 || index >= n) {
     return r0;
   }
-  const paddingOffset = step - scale.bandwidth;
+  const paddingOffset = (step - scale.bandwidth) / 2;
   const bandStart = r0 + step * index + paddingOffset;
   return bandStart;
 }

package/esm/chart/utils/scrubber.js

@@ -1,20 +1,27 @@
 /**
  * Determines which side (left/right) to place scrubber labels based on available space.
- * Prefers right side, switches to left when labels would overflow.
+ * Honors the preferred side when there's enough space, otherwise switches to the opposite side.
  */
-export const getLabelPosition = function (beaconX, maxLabelWidth, drawingArea, xOffset) {
+export const getLabelPosition = function (beaconX, maxLabelWidth, drawingArea, xOffset, preferredSide) {
   'worklet';
 
   // any regular functions in ui thread must be marked with 'worklet'
   if (xOffset === void 0) {
     xOffset = 16;
   }
+  if (preferredSide === void 0) {
+    preferredSide = 'right';
+  }
   if (drawingArea.width <= 0 || drawingArea.height <= 0) {
-    return 'right';
+    return preferredSide;
   }
-  const availableRightSpace = drawingArea.x + drawingArea.width - beaconX;
   const requiredSpace = maxLabelWidth + xOffset;
-  return requiredSpace <= availableRightSpace ? 'right' : 'left';
+  if (preferredSide === 'right') {
+    const availableSpace = drawingArea.x + drawingArea.width - beaconX;
+    return requiredSpace <= availableSpace ? 'right' : 'left';
+  }
+  const availableSpace = beaconX - drawingArea.x;
+  return requiredSpace <= availableSpace ? 'left' : 'right';
 };
 /**
  * Calculates Y positions for all labels avoiding overlaps while maintaining order.