@coinbase/cds-web-visualization 3.4.0-beta.1 → 3.4.0-beta.11

package/esm/chart/utils/path.js

@@ -40,17 +40,18 @@ export const getPathCurveFunction = function () {
  * @example
  * ```typescript
  * const chartScale = getChartScale({ chartRect, domain, range, xScale, yScale });
- * const path = getLinePath({ data: [1, 2, 3], chartScale, curve: 'linear' });
+ * const path = getLinePath({ data: [1, 2, 3], chartScale, curve: 'bump' });
  * ```
  */
 export const getLinePath = _ref => {
   var _pathGenerator;
   let {
     data,
-    curve = 'linear',
+    curve = 'bump',
     xScale,
     yScale,
-    xData
+    xData,
+    connectNulls
   } = _ref;
   if (data.length === 0) {
     return '';
@@ -62,9 +63,12 @@ export const getLinePath = _ref => {
     yScale,
     xData
   });
-  const pathGenerator = d3Line().x(d => d.x).y(d => d.y).curve(curveFunction).defined(d => d !== null); // Only draw lines where point is not null
 
-  return (_pathGenerator = pathGenerator(dataPoints)) !== null && _pathGenerator !== void 0 ? _pathGenerator : '';
+  // When connectNulls is true, filter out null values before rendering
+  // When false, use defined() to create gaps in the line
+  const filteredPoints = connectNulls ? dataPoints.filter(d => d !== null) : dataPoints;
+  const pathGenerator = d3Line().x(d => d.x).y(d => d.y).curve(curveFunction).defined(d => connectNulls || d !== null);
+  return (_pathGenerator = pathGenerator(filteredPoints)) !== null && _pathGenerator !== void 0 ? _pathGenerator : '';
 };
 
 /**
@@ -92,10 +96,11 @@ export const getLinePath = _ref => {
 export const getAreaPath = _ref2 => {
   let {
     data,
-    curve = 'linear',
+    curve = 'bump',
     xScale,
     yScale,
-    xData
+    xData,
+    connectNulls
   } = _ref2;
   if (data.length === 0) {
     return '';
@@ -156,6 +161,10 @@ export const getAreaPath = _ref2 => {
       isValid: true
     };
   });
+
+  // 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 !== void 0 ? _d$low : 0;
@@ -164,12 +173,26 @@ export const getAreaPath = _ref2 => {
     var _d$high;
     return (_d$high = d.high) !== null && _d$high !== void 0 ? _d$high : 0;
   }) // Top boundary (high values), fallback to 0
-  .curve(curveFunction).defined(d => d.isValid && d.low != null && d.high != null); // Only draw where both values exist
+  .curve(curveFunction).defined(d => connectNulls || d.isValid && d.low != null && d.high != null); // Only draw where both values exist
 
-  const result = areaGenerator(dataPoints);
+  const result = areaGenerator(filteredPoints);
   return result !== null && result !== void 0 ? result : '';
 };
 
+/**
+ * Converts line coordinates to an SVG path string.
+ * Useful for rendering axis lines and tick marks.
+ *
+ * @example
+ * ```typescript
+ * const path = lineToPath(0, 0, 100, 100);
+ * // Returns: "M 0 0 L 100 100"
+ * ```
+ */
+export const lineToPath = (x1, y1, x2, y2) => {
+  return "M".concat(x1, ",").concat(y1, " L").concat(x2, ",").concat(y2);
+};
+
 /**
  * Creates an SVG path string for a rectangle with selective corner rounding.
  * Useful for creating bars in charts with optional rounded corners.

package/esm/chart/utils/point.js

@@ -1,20 +1,46 @@
 import { isCategoricalScale, isLogScale, isNumericScale } from './scale';
 
+/**
+ * Position a label should be placed relative to the point
+ *
+ * @example
+ * 'top' would have the label be located above the point itself,
+ * and thus the vertical alignment of that text would be bottom.
+ */
+
 /**
  * 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) {
+  var _scale;
+  let anchor = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 'middle';
   if (isCategoricalScale(scale)) {
-    var _scale, _scale$bandwidth;
-    const bandStart = (_scale = scale(dataValue)) !== null && _scale !== void 0 ? _scale : 0;
-    const bandwidth = (_scale$bandwidth = scale.bandwidth()) !== null && _scale$bandwidth !== void 0 ? _scale$bandwidth : 0;
-    return bandStart + bandwidth / 2;
+    var _bandScale$bandwidth, _bandScale$bandwidth2, _bandScale$step, _bandScale$step2;
+    const bandScale = scale;
+    const bandStart = bandScale(dataValue);
+    if (bandStart === undefined) return 0;
+    const bandwidth = (_bandScale$bandwidth = (_bandScale$bandwidth2 = bandScale.bandwidth) === null || _bandScale$bandwidth2 === void 0 ? void 0 : _bandScale$bandwidth2.call(bandScale)) !== null && _bandScale$bandwidth !== void 0 ? _bandScale$bandwidth : 0;
+    const step = (_bandScale$step = (_bandScale$step2 = bandScale.step) === null || _bandScale$step2 === void 0 ? void 0 : _bandScale$step2.call(bandScale)) !== null && _bandScale$step !== void 0 ? _bandScale$step : bandwidth;
+    const paddingOffset = (step - bandwidth) / 2;
+    const stepStart = bandStart - paddingOffset;
+    switch (anchor) {
+      case 'stepStart':
+        return stepStart;
+      case 'bandStart':
+        return bandStart;
+      case 'bandEnd':
+        return bandStart + bandwidth;
+      case 'stepEnd':
+        return stepStart + step;
+      case 'middle':
+      default:
+        return bandStart + bandwidth / 2;
+    }
   }
 
   // For log scales, ensure the value is positive
@@ -22,7 +48,7 @@ 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 !== void 0 ? _scale2 : 0;
+  return (_scale = scale(adjustedValue)) !== null && _scale !== void 0 ? _scale : 0;
 };
 
 /**
@@ -115,4 +141,65 @@ export const projectPoints = _ref2 => {
       yScale
     });
   });
+};
+
+/**
+ * Determines text alignment based on label position.
+ * For example, a 'top' position needs the text aligned to the 'bottom' so it appears above the point.
+ */
+export const getAlignmentFromPosition = position => {
+  let horizontalAlignment = 'center';
+  let verticalAlignment = 'middle';
+  switch (position) {
+    case 'top':
+      verticalAlignment = 'bottom';
+      break;
+    case 'bottom':
+      verticalAlignment = 'top';
+      break;
+    case 'left':
+      horizontalAlignment = 'right';
+      break;
+    case 'right':
+      horizontalAlignment = 'left';
+      break;
+    case 'center':
+    default:
+      horizontalAlignment = 'center';
+      verticalAlignment = 'middle';
+      break;
+  }
+  return {
+    horizontalAlignment,
+    verticalAlignment
+  };
+};
+
+/**
+ * Calculates the final label coordinates by applying offset based on position.
+ */
+export const getLabelCoordinates = (x, y, position, offset) => {
+  let dx = 0;
+  let dy = 0;
+  switch (position) {
+    case 'top':
+      dy = -offset;
+      break;
+    case 'bottom':
+      dy = offset;
+      break;
+    case 'left':
+      dx = -offset;
+      break;
+    case 'right':
+      dx = offset;
+      break;
+    case 'center':
+    default:
+      break;
+  }
+  return {
+    x: x + dx,
+    y: y + dy
+  };
 };

package/esm/chart/utils/scale.js

@@ -43,6 +43,17 @@ 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
+ */

package/esm/chart/utils/scrubber.js

@@ -0,0 +1,132 @@
+/**
+ * Determines which side (left/right) to place scrubber labels based on available space.
+ * Prefers right side, switches to left when labels would overflow.
+ */
+export const getLabelPosition = function (beaconX, maxLabelWidth, drawingArea) {
+  let xOffset = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 16;
+  if (drawingArea.width <= 0 || drawingArea.height <= 0) {
+    return 'right';
+  }
+  const availableRightSpace = drawingArea.x + drawingArea.width - beaconX;
+  const requiredSpace = maxLabelWidth + xOffset;
+  return requiredSpace <= availableRightSpace ? 'right' : 'left';
+};
+/**
+ * Calculates Y positions for all labels avoiding overlaps while maintaining order.
+ */
+export const calculateLabelYPositions = (dimensions, drawingArea, labelHeight, minGap) => {
+  if (dimensions.length === 0) {
+    return new Map();
+  }
+
+  // Sort by preferred Y values and create working labels
+  const sortedLabels = [...dimensions].sort((a, b) => a.preferredY - b.preferredY).map(dim => ({
+    seriesId: dim.seriesId,
+    preferredY: dim.preferredY,
+    finalY: dim.preferredY
+  }));
+
+  // Initial bounds fitting
+  const minY = drawingArea.y + labelHeight / 2;
+  const maxY = drawingArea.y + drawingArea.height - labelHeight / 2;
+  const requiredDistance = labelHeight + minGap;
+  for (const label of sortedLabels) {
+    // Clamp each label to the drawing area
+    label.finalY = Math.max(minY, Math.min(maxY, label.preferredY));
+  }
+
+  // First pass: push down any overlapping labels
+  for (let i = 1; i < sortedLabels.length; i++) {
+    const prev = sortedLabels[i - 1];
+    const current = sortedLabels[i];
+    const minAllowedY = prev.finalY + requiredDistance;
+    if (current.finalY < minAllowedY) {
+      current.finalY = minAllowedY;
+    }
+  }
+
+  // Find collision groups - groups of labels that are tightly packed (gap < minGap between them)
+  const collisionGroups = [];
+  let currentGroup = [sortedLabels[0]];
+  for (let i = 1; i < sortedLabels.length; i++) {
+    const prev = sortedLabels[i - 1];
+    const current = sortedLabels[i];
+    const gap = current.finalY - prev.finalY - labelHeight;
+    if (gap < minGap + 0.01) {
+      // Labels are touching or very close - part of same collision group
+      currentGroup.push(current);
+    } else {
+      // Gap is large enough - start new group
+      collisionGroups.push(currentGroup);
+      currentGroup = [current];
+    }
+  }
+  collisionGroups.push(currentGroup);
+
+  // Process each collision group - optimize positioning to minimize displacement
+  for (const group of collisionGroups) {
+    if (group.length === 1) {
+      // Single label, already at best position
+      continue;
+    }
+    const groupLastLabel = group[group.length - 1];
+    const groupFirstLabel = group[0];
+    const groupOverflow = groupLastLabel.finalY + labelHeight / 2 - (drawingArea.y + drawingArea.height);
+
+    // Calculate the ideal center point for this group
+    const groupPreferredCenter = group.reduce((sum, label) => sum + label.preferredY, 0) / group.length;
+    const groupTotalNeeded = group.length * labelHeight + (group.length - 1) * minGap;
+    if (groupOverflow <= 0) {
+      // Group fits, but let's center it better if possible
+      // Calculate how much we can shift up/down to center around preferred positions
+      const currentCenter = (groupFirstLabel.finalY + groupLastLabel.finalY) / 2;
+      const desiredShift = groupPreferredCenter - currentCenter;
+
+      // Calculate max shift in each direction
+      const maxShiftUp = groupFirstLabel.finalY - minY;
+      const maxShiftDown = maxY - groupLastLabel.finalY;
+
+      // Apply the shift, constrained by boundaries
+      const actualShift = Math.max(-maxShiftUp, Math.min(maxShiftDown, desiredShift));
+      if (Math.abs(actualShift) > 0.01) {
+        for (const label of group) {
+          label.finalY += actualShift;
+        }
+      }
+    } else {
+      // Group overflows - need to adjust
+      const groupStartY = groupFirstLabel.finalY - labelHeight / 2;
+      const availableSpace = drawingArea.y + drawingArea.height - groupStartY;
+      const maxShiftUp = groupFirstLabel.finalY - minY;
+      if (maxShiftUp >= groupOverflow) {
+        // Can shift entire group up to fit
+        for (const label of group) {
+          label.finalY -= groupOverflow;
+        }
+      } else if (groupTotalNeeded <= availableSpace) {
+        // Can't shift enough, but there's room - redistribute with proper spacing
+        let currentY = Math.max(minY, groupFirstLabel.finalY - maxShiftUp);
+        const gap = (availableSpace - group.length * labelHeight) / Math.max(1, group.length - 1);
+        for (const label of group) {
+          label.finalY = currentY;
+          currentY += labelHeight + gap;
+        }
+      } else {
+        // Not enough space even with compression - compress gaps and fit to bottom
+        const compressedGap = Math.max(1, (availableSpace - group.length * labelHeight) / Math.max(1, group.length - 1));
+        // Position so last label is at maxY
+        let currentY = maxY - (group.length - 1) * (labelHeight + compressedGap);
+        currentY = Math.max(minY, currentY);
+        for (const label of group) {
+          label.finalY = currentY;
+          currentY += labelHeight + compressedGap;
+        }
+      }
+    }
+  }
+  const result = new Map();
+  for (const label of sortedLabels) {
+    result.set(label.seriesId, label.finalY);
+  }
+  return result;
+};

package/esm/chart/utils/transition.js

@@ -0,0 +1,111 @@
+function ownKeys(e, r) { var t = Object.keys(e); if (Object.getOwnPropertySymbols) { var o = Object.getOwnPropertySymbols(e); r && (o = o.filter(function (r) { return Object.getOwnPropertyDescriptor(e, r).enumerable; })), t.push.apply(t, o); } return t; }
+function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t = null != arguments[r] ? arguments[r] : {}; r % 2 ? ownKeys(Object(t), !0).forEach(function (r) { _defineProperty(e, r, t[r]); }) : Object.getOwnPropertyDescriptors ? Object.defineProperties(e, Object.getOwnPropertyDescriptors(t)) : ownKeys(Object(t)).forEach(function (r) { Object.defineProperty(e, r, Object.getOwnPropertyDescriptor(t, r)); }); } return e; }
+function _defineProperty(e, r, t) { return (r = _toPropertyKey(r)) in e ? Object.defineProperty(e, r, { value: t, enumerable: !0, configurable: !0, writable: !0 }) : e[r] = t, e; }
+function _toPropertyKey(t) { var i = _toPrimitive(t, "string"); return "symbol" == typeof i ? i : i + ""; }
+function _toPrimitive(t, r) { if ("object" != typeof t || !t) return t; var e = t[Symbol.toPrimitive]; if (void 0 !== e) { var i = e.call(t, r || "default"); if ("object" != typeof i) return i; throw new TypeError("@@toPrimitive must return a primitive value."); } return ("string" === r ? String : Number)(t); }
+import { useEffect, useRef } from 'react';
+import { interpolatePath } from 'd3-interpolate-path';
+import { animate, useMotionValue, useTransform } from 'framer-motion';
+
+/**
+ * Default transition configuration used across all chart components.
+ */
+export const defaultTransition = {
+  type: 'spring',
+  stiffness: 900,
+  damping: 120,
+  mass: 4
+};
+
+/**
+ * Duration in seconds for accessory elements to fade in.
+ */
+export const accessoryFadeTransitionDuration = 0.15;
+
+/**
+ * Delay in seconds before accessory elements fade in.
+ */
+export const accessoryFadeTransitionDelay = 0.35;
+
+/**
+ * Hook for path animation state and transitions.
+ *
+ * @param currentPath - Current target path to animate to
+ * @param initialPath - Initial path for enter animation. When provided, the first animation will go from initialPath to currentPath.
+ * @param transition - Transition configuration
+ * @returns MotionValue containing the current interpolated path string
+ *
+ * @example
+ * // Simple path transition
+ * const animatedPath = usePathTransition({
+ *   currentPath: d ?? '',
+ *   transition: {
+ *     type: 'spring',
+ *     stiffness: 300,
+ *     damping: 20
+ *   }
+ * });
+ *
+ * @example
+ * // Time based animation
+ * const animatedPath = usePathTransition({
+ *   currentPath: targetPath,
+ *   initialPath: baselinePath,
+ *   transition: {
+ *     type: 'tween',
+ *     duration: 0.3,
+ *     ease: 'easeInOut'
+ *   }
+ * });
+ */
+export const usePathTransition = _ref => {
+  let {
+    currentPath,
+    initialPath,
+    transition = defaultTransition
+  } = _ref;
+  const isInitialRender = useRef(true);
+  const previousPathRef = useRef(initialPath !== null && initialPath !== void 0 ? initialPath : currentPath);
+  const targetPathRef = useRef(currentPath);
+  const animationRef = useRef(null);
+  const progress = useMotionValue(0);
+
+  // Derive the interpolated path from progress using useTransform
+  const interpolatedPath = useTransform(progress, latest => {
+    const pathInterpolator = interpolatePath(previousPathRef.current, targetPathRef.current);
+    return pathInterpolator(latest);
+  });
+  useEffect(() => {
+    // Only proceed if the target path has actually changed
+    if (targetPathRef.current !== currentPath) {
+      // Cancel any ongoing animation before starting a new one
+      const wasAnimating = !!animationRef.current;
+      if (animationRef.current) {
+        animationRef.current.cancel();
+        animationRef.current = null;
+      }
+      const currentInterpolatedPath = interpolatedPath.get();
+
+      // If we were animating and the interpolated path is different from both start and end,
+      // use it as the starting point for the next animation (smooth interruption)
+      const isInterpolatedPosition = currentInterpolatedPath !== previousPathRef.current && currentInterpolatedPath !== currentPath;
+      if (wasAnimating && isInterpolatedPosition) {
+        previousPathRef.current = currentInterpolatedPath;
+      }
+      targetPathRef.current = currentPath;
+      progress.set(0);
+      animationRef.current = animate(progress, 1, _objectSpread(_objectSpread({}, transition), {}, {
+        onComplete: () => {
+          previousPathRef.current = currentPath;
+        }
+      }));
+      isInitialRender.current = false;
+    }
+    return () => {
+      if (animationRef.current) {
+        animationRef.current.cancel();
+      }
+    };
+  }, [currentPath, transition, progress, interpolatedPath]);
+  return interpolatedPath;
+};

package/esm/sparkline/sparkline-interactive/SparklineInteractiveMarkerDates.js

@@ -13,14 +13,15 @@ const noPointerEvents = {
 };
 const SparklineInteractiveMarkerDate = /*#__PURE__*/memo(_ref => {
   let {
-    getFormattedDate
+    getFormattedDate,
+    containerOffsetLeft
   } = _ref;
   const [xPos, setXPos] = useState(0);
   const setupRef = useCallback(ref => {
     if (ref) {
-      setXPos(ref.offsetLeft + ref.offsetWidth / 2);
+      setXPos(ref.offsetLeft + ref.offsetWidth / 2 - containerOffsetLeft);
     }
-  }, []);
+  }, [containerOffsetLeft]);
   const dateStr = getFormattedDate(xPos);
 
   // take up space while loading so when it finishes loading there is no jump
@@ -48,6 +49,7 @@ function SparklineInteractiveMarkerDatesWithGeneric(_ref2) {
     timePeriodGutter = 2
   } = _ref2;
   const [numberOfLabels, setNumberOfLabels] = useState(0);
+  const [containerOffsetLeft, setContainerOffsetLeft] = useState(0);
   const getFormattedDate = useDateLookup({
     getMarker,
     formatDate,
@@ -57,15 +59,17 @@ function SparklineInteractiveMarkerDatesWithGeneric(_ref2) {
     if (ref) {
       const numberOfLabelsFromWidth = Math.floor(ref.offsetWidth / labelWidth);
       setNumberOfLabels(Math.max(numberOfLabelsFromWidth, 4));
+      setContainerOffsetLeft(ref.offsetLeft);
     }
   }, []);
   const markers = useMemo(() => {
     return times(numberOfLabels).map((_, i) => {
       return /*#__PURE__*/_jsx(SparklineInteractiveMarkerDate, {
+        containerOffsetLeft: containerOffsetLeft,
         getFormattedDate: getFormattedDate
       }, i);
     });
-  }, [getFormattedDate, numberOfLabels]);
+  }, [containerOffsetLeft, getFormattedDate, numberOfLabels]);
   return /*#__PURE__*/_jsx(HStack, {
     ref: setupRef,
     className: fadeInCss,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coinbase/cds-web-visualization",
-  "version": "3.4.0-beta.1",
+  "version": "3.4.0-beta.11",
   "description": "Coinbase Design System - Web Sparkline",
   "repository": {
     "type": "git",
@@ -38,10 +38,10 @@
     "CHANGELOG"
   ],
   "peerDependencies": {
-    "@coinbase/cds-common": "^8.13.5",
-    "@coinbase/cds-lottie-files": "^3.3.1",
-    "@coinbase/cds-utils": "^2.3.2",
-    "@coinbase/cds-web": "^8.13.5",
+    "@coinbase/cds-common": "^8.36.2",
+    "@coinbase/cds-lottie-files": "^3.3.4",
+    "@coinbase/cds-utils": "^2.3.5",
+    "@coinbase/cds-web": "^8.36.2",
     "react": "^18.3.1",
     "react-dom": "^18.3.1"
   },
@@ -58,10 +58,10 @@
     "@babel/preset-env": "^7.28.0",
     "@babel/preset-react": "^7.27.1",
     "@babel/preset-typescript": "^7.27.1",
-    "@coinbase/cds-common": "^8.13.5",
-    "@coinbase/cds-lottie-files": "^3.3.1",
-    "@coinbase/cds-utils": "^2.3.2",
-    "@coinbase/cds-web": "^8.13.5",
+    "@coinbase/cds-common": "^8.36.2",
+    "@coinbase/cds-lottie-files": "^3.3.4",
+    "@coinbase/cds-utils": "^2.3.5",
+    "@coinbase/cds-web": "^8.36.2",
     "@figma/code-connect": "^1.3.4",
     "@linaria/core": "^3.0.0-beta.22",
     "@types/react": "^18.3.12",