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

package/esm/chart/utils/chart.js

@@ -0,0 +1,229 @@
+import { stack as d3Stack, stackOffsetDiverging, stackOrderNone } from 'd3-shape';
+export const defaultStackId = 'DEFAULT_STACK_ID';
+/**
+ * Type guard to check if bounds are complete with both min and max values.
+ * @param bounds - The bounds to validate
+ * @returns True if bounds has both min and max defined
+ */
+export const isValidBounds = bounds => bounds.min !== undefined && bounds.max !== undefined;
+/**
+ * Calculates the domain of a chart from series data.
+ * Domain represents the range of x-values from the data.
+ */
+export const getChartDomain = (series, min, max) => {
+  const domain = {
+    min,
+    max
+  };
+  if (domain.min !== undefined && domain.max !== undefined) {
+    return domain;
+  }
+  if (series.length > 0) {
+    const maxDataLength = Math.max(...series.map(s => {
+      var _s$data;
+      return ((_s$data = s.data) === null || _s$data === void 0 ? void 0 : _s$data.length) || 0;
+    }));
+    if (maxDataLength > 0) {
+      if (domain.min === undefined) domain.min = 0;
+      if (domain.max === undefined) domain.max = maxDataLength - 1;
+    }
+  }
+  return domain;
+};
+
+/**
+ * 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.
+ */
+const createStackKey = series => {
+  if (series.stackId === undefined) return undefined;
+
+  // Include y-axis ID to prevent cross-scale stacking
+  const yAxisId = series.yAxisId || 'default';
+  return "".concat(series.stackId, ":").concat(yAxisId);
+};
+
+/**
+ * Transforms series data into stacked data using D3's stack algorithm.
+ * Returns a map of series ID to transformed [baseline, value] tuples.
+ *
+ * @param series - Array of series with potential stack properties
+ * @returns Map of series ID to stacked data arrays
+ */
+export const getStackedSeriesData = series => {
+  const stackedDataMap = new Map();
+  const numericStackGroups = new Map();
+  const individualSeries = [];
+  series.forEach(s => {
+    var _s$data2;
+    const stackKey = createStackKey(s);
+    const hasTupleData = (_s$data2 = s.data) === null || _s$data2 === void 0 ? void 0 : _s$data2.some(val => Array.isArray(val));
+    if (hasTupleData || stackKey === undefined) {
+      individualSeries.push(s);
+    } else {
+      if (!numericStackGroups.has(stackKey)) {
+        numericStackGroups.set(stackKey, []);
+      }
+      numericStackGroups.get(stackKey).push(s);
+    }
+  });
+  individualSeries.forEach(s => {
+    if (!s.data) return;
+    const normalizedData = s.data.map(val => {
+      if (val === null) return null;
+      if (Array.isArray(val)) {
+        return val;
+      }
+      if (typeof val === 'number') {
+        return [0, val];
+      }
+      return null;
+    });
+    stackedDataMap.set(s.id, normalizedData);
+  });
+  numericStackGroups.forEach((groupSeries, stackKey) => {
+    const maxLength = Math.max(...groupSeries.map(s => {
+      var _s$data3;
+      return ((_s$data3 = s.data) === null || _s$data3 === void 0 ? void 0 : _s$data3.length) || 0;
+    }));
+    if (maxLength === 0) return;
+    const dataset = new Array(maxLength).fill(undefined).map((_, i) => {
+      const row = {};
+      for (const s of groupSeries) {
+        var _s$data4;
+        const val = (_s$data4 = s.data) === null || _s$data4 === void 0 ? void 0 : _s$data4[i];
+        const num = typeof val === 'number' ? val : 0;
+        row[s.id] = num;
+      }
+      return row;
+    });
+    const keys = groupSeries.map(s => s.id);
+    const stackedSeries = d3Stack().keys(keys).order(stackOrderNone).offset(stackOffsetDiverging)(dataset);
+    stackedSeries.forEach((layer, layerIndex) => {
+      const seriesId = keys[layerIndex];
+      const stackedData = layer.map(_ref => {
+        let [bottom, top] = _ref;
+        return [bottom, top];
+      });
+      stackedDataMap.set(seriesId, stackedData);
+    });
+  });
+  return stackedDataMap;
+};
+
+/**
+ * Calculates the range of a chart from series data.
+ * Range represents the range of y-values from the data.
+ * Handles stacking by transforming data when series have stack properties.
+ */
+export const getChartRange = (series, min, max) => {
+  const range = {
+    min,
+    max
+  };
+  if (range.min !== undefined && range.max !== undefined) {
+    return range;
+  }
+  if (series.length === 0) {
+    return range;
+  }
+
+  // Group series by composite stack key for proper calculation
+  const stackGroups = new Map();
+  series.forEach(s => {
+    const stackKey = createStackKey(s);
+    if (!stackGroups.has(stackKey)) {
+      stackGroups.set(stackKey, []);
+    }
+    stackGroups.get(stackKey).push(s);
+  });
+
+  // Check if we have any stacked series
+  const hasStacks = Array.from(stackGroups.keys()).some(k => k !== undefined);
+  if (hasStacks) {
+    // Get stacked data using the shared function
+    const stackedDataMap = getStackedSeriesData(series);
+
+    // Find the extreme values from the stacked data
+    let stackedMax = 0;
+    let stackedMin = 0;
+    stackedDataMap.forEach(stackedData => {
+      stackedData.forEach(point => {
+        if (point !== null) {
+          const [bottom, top] = point;
+          if (top > stackedMax) stackedMax = top;
+          if (bottom < stackedMin) stackedMin = bottom;
+        }
+      });
+    });
+
+    // Don't add padding - let D3's nice() function handle axis padding
+    if (range.min === undefined) range.min = Math.min(0, stackedMin);
+    if (range.max === undefined) range.max = Math.max(0, stackedMax);
+  } else {
+    // No stacking, calculate range from raw values
+    const allValues = [];
+    series.forEach(s => {
+      if (s.data) {
+        s.data.forEach(point => {
+          if (typeof point === 'number') {
+            allValues.push(point);
+          } else if (Array.isArray(point)) {
+            // Filter out null values from tuples
+            const validValues = point.filter(val => val !== null);
+            allValues.push(...validValues);
+          }
+        });
+      }
+    });
+    if (allValues.length > 0) {
+      const minValue = Math.min(...allValues);
+      const maxValue = Math.max(...allValues);
+      if (range.min === undefined) range.min = minValue;
+      if (range.max === undefined) range.max = maxValue;
+    }
+  }
+  return range;
+};
+export const defaultChartInset = {
+  top: 32,
+  left: 16,
+  bottom: 16,
+  right: 16
+};
+
+/**
+ * Normalize padding to include all sides with a value.
+ * @param padding - The padding to get.
+ * @param defaults - Optional complete default values to use instead of 0.
+ * @returns The calculated padding.
+ */
+/**
+ * Normalize inset to include all sides with a value.
+ * @param inset - The inset to get.
+ * @param defaults - Optional complete default values to use instead of 0.
+ * @returns The calculated inset.
+ */
+export const getChartInset = (inset, defaults) => {
+  var _inset$top, _inset$left, _inset$bottom, _inset$right;
+  const baseDefaults = defaults !== null && defaults !== void 0 ? defaults : {
+    top: 0,
+    left: 0,
+    bottom: 0,
+    right: 0
+  };
+  if (typeof inset === 'number') {
+    return {
+      top: inset,
+      left: inset,
+      bottom: inset,
+      right: inset
+    };
+  }
+  return {
+    top: (_inset$top = inset === null || inset === void 0 ? void 0 : inset.top) !== null && _inset$top !== void 0 ? _inset$top : baseDefaults.top,
+    left: (_inset$left = inset === null || inset === void 0 ? void 0 : inset.left) !== null && _inset$left !== void 0 ? _inset$left : baseDefaults.left,
+    bottom: (_inset$bottom = inset === null || inset === void 0 ? void 0 : inset.bottom) !== null && _inset$bottom !== void 0 ? _inset$bottom : baseDefaults.bottom,
+    right: (_inset$right = inset === null || inset === void 0 ? void 0 : inset.right) !== null && _inset$right !== void 0 ? _inset$right : baseDefaults.right
+  };
+};

package/esm/chart/utils/context.js

@@ -0,0 +1,15 @@
+import { createContext, useContext } from 'react';
+
+/**
+ * Context value for Cartesian (X/Y) coordinate charts.
+ * Contains axis-specific methods and properties for rectangular coordinate systems.
+ */
+
+export const ScrubberContext = /*#__PURE__*/createContext(undefined);
+export const useScrubberContext = () => {
+  const context = useContext(ScrubberContext);
+  if (!context) {
+    throw new Error('useScrubberContext must be used within a Chart component');
+  }
+  return context;
+};

package/esm/chart/utils/index.js

@@ -0,0 +1,9 @@
+// codegen:start {preset: barrel, include: ./*.ts, exclude: ./__tests__/*.ts}
+export * from './axis';
+export * from './bar';
+export * from './chart';
+export * from './context';
+export * from './path';
+export * from './point';
+export * from './scale';
+// codegen:end

package/esm/chart/utils/path.js

@@ -0,0 +1,204 @@
+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 { isCategoricalScale } from './scale';
+/**
+ * Get the d3 curve function for a path.
+ * See https://d3js.org/d3-shape/curve
+ * @param curve - The curve type. Defaults to 'linear'.
+ * @returns The d3 curve function.
+ */
+export const getPathCurveFunction = function () {
+  let curve = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : 'linear';
+  switch (curve) {
+    case 'catmullRom':
+      return curveCatmullRom;
+    case 'monotone':
+      // When we support layout="vertical" this should dynamically switch to curveMonotoneY
+      return curveMonotoneX;
+    case 'natural':
+      return curveNatural;
+    case 'step':
+      return curveStep;
+    case 'stepBefore':
+      return curveStepBefore;
+    case 'stepAfter':
+      return curveStepAfter;
+    case 'bump':
+      // When we support layout="vertical" this should dynamically switch to curveBumpY
+      return curveBumpX;
+    case 'linearClosed':
+      return curveLinearClosed;
+    case 'linear':
+    default:
+      return curveLinear;
+  }
+};
+
+/**
+ * Generates an SVG line path string from data using chart scale functions.
+ *
+ * @example
+ * ```typescript
+ * const chartScale = getChartScale({ chartRect, domain, range, xScale, yScale });
+ * const path = getLinePath({ data: [1, 2, 3], chartScale, curve: 'linear' });
+ * ```
+ */
+export const getLinePath = _ref => {
+  var _pathGenerator;
+  let {
+    data,
+    curve = 'linear',
+    xScale,
+    yScale,
+    xData
+  } = _ref;
+  if (data.length === 0) {
+    return '';
+  }
+  const curveFunction = getPathCurveFunction(curve);
+  const dataPoints = projectPoints({
+    data,
+    xScale,
+    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 : '';
+};
+
+/**
+ * Generates an SVG area path string from data using chart scale functions.
+ * Supports both single values (area from baseline to value) and tuples ([baseline, value]).
+ *
+ * @example
+ * ```typescript
+ * // Single values - area from baseline to value
+ * const area = getAreaPath({
+ *   data: [1, 2, 3],
+ *   xScale,
+ *   yScale,
+ * });
+ *
+ * // Range values - area from low to high
+ * const rangeArea = getAreaPath({
+ *   data: [[0, 3], [2, 4], [1, 5]],
+ *   xScale,
+ *   yScale,
+ *   curve: 'monotone'
+ * });
+ * ```
+ */
+export const getAreaPath = _ref2 => {
+  let {
+    data,
+    curve = 'linear',
+    xScale,
+    yScale,
+    xData
+  } = _ref2;
+  if (data.length === 0) {
+    return '';
+  }
+  const curveFunction = getPathCurveFunction(curve);
+  const yDomain = yScale.domain();
+  const yMin = Math.min(...yDomain);
+  const normalizedData = data.map((item, index) => {
+    if (item === null) {
+      return null;
+    }
+    if (Array.isArray(item)) {
+      if (item.length >= 2 && typeof item[0] === 'number' && typeof item[1] === 'number') {
+        return [item[0], item[1]];
+      }
+      return null;
+    }
+    if (typeof item === 'number') {
+      return [yMin, item];
+    }
+    return null;
+  });
+  const dataPoints = normalizedData.map((range, index) => {
+    if (range === null) {
+      return {
+        x: 0,
+        low: null,
+        high: null,
+        isValid: false
+      };
+    }
+    let xValue = index;
+    if (!isCategoricalScale(xScale) && xData && xData[index] !== undefined) {
+      xValue = xData[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
+    });
+    return {
+      x: xPoint.x,
+      low: lowPoint.y,
+      high: highPoint.y,
+      isValid: true
+    };
+  });
+  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;
+  }) // Bottom boundary (low values), fallback to 0
+  .y1(d => {
+    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
+
+  const result = areaGenerator(dataPoints);
+  return result !== null && result !== void 0 ? result : '';
+};
+
+/**
+ * Creates an SVG path string for a rectangle with selective corner rounding.
+ * Useful for creating bars in charts with optional rounded corners.
+ *
+ * @example
+ * ```typescript
+ * // Simple rectangle bar
+ * const barPath = getBarPath(10, 20, 50, 100, 0, false, false);
+ *
+ * // Bar with rounded top corners
+ * const roundedPath = getBarPath(10, 20, 50, 100, 8, true, false);
+ * ```
+ */
+export const getBarPath = (x, y, width, height, radius, roundTop, roundBottom) => {
+  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;
+
+  // Build path with selective rounding
+  let path = "M ".concat(x + (roundTop ? r : 0), " ").concat(y);
+  path += " L ".concat(x + width - topR, " ").concat(y);
+  path += " A ".concat(topR, " ").concat(topR, " 0 0 1 ").concat(x + width, " ").concat(y + topR);
+  path += " L ".concat(x + width, " ").concat(y + height - bottomR);
+  path += " A ".concat(bottomR, " ").concat(bottomR, " 0 0 1 ").concat(x + width - bottomR, " ").concat(y + height);
+  path += " L ".concat(x + bottomR, " ").concat(y + height);
+  path += " A ".concat(bottomR, " ").concat(bottomR, " 0 0 1 ").concat(x, " ").concat(y + height - bottomR);
+  path += " L ".concat(x, " ").concat(y + topR);
+  path += " A ".concat(topR, " ").concat(topR, " 0 0 1 ").concat(x + topR, " ").concat(y);
+  path += ' Z';
+  return path;
+};

package/esm/chart/utils/point.js

@@ -0,0 +1,118 @@
+import { isCategoricalScale, isLogScale, isNumericScale } from './scale';
+
+/**
+ * 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).
+ */
+export const getPointOnScale = (dataValue, scale) => {
+  var _scale2;
+  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;
+  }
+
+  // For log scales, ensure the value is positive
+  let adjustedValue = dataValue;
+  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;
+};
+
+/**
+ * Projects a data point to pixel coordinates using the chart scale.
+ * Automatically handles log scale transformations for zero/negative values.
+ *
+ * @example
+ * ```typescript
+ * const chartScale = getChartScale({ chartRect, domain, range, xScale, yScale });
+ * const pixelCoord = projectPoint({ x: 5, y: 10, chartScale });
+ * ```
+ * @example
+ * ```typescript
+ * const chartScale = getChartScale({ chartRect, domain, range, xScale, yScale });
+ * const pixelCoord = projectPoint({ x: 2, y: 10, chartScale, xData: ['Jan', 'Feb', 'Mar'] });
+ * ```
+ */
+export const projectPoint = _ref => {
+  let {
+    x,
+    y,
+    xScale,
+    yScale
+  } = _ref;
+  return {
+    x: getPointOnScale(x, xScale),
+    y: getPointOnScale(y, yScale)
+  };
+};
+
+/**
+ * Projects multiple data points to pixel coordinates using chart scale functions.
+ * Handles both numeric and band scales automatically.
+ *
+ * @example
+ * ```typescript
+ * const chartScale = getChartScale({ chartRect, domain, range, xScale, yScale });
+ * const pixelPoints = projectPoints({ data, chartScale });
+ * // For mixed scales
+ * const pixelPoints = projectPoints({ data, chartScale, xData: ['Jan', 'Feb', 'Mar'] });
+ * ```
+ */
+export const projectPoints = _ref2 => {
+  let {
+    data,
+    xScale,
+    yScale,
+    xData,
+    yData
+  } = _ref2;
+  if (data.length === 0) {
+    return [];
+  }
+  return data.map((value, index) => {
+    if (value === null) {
+      return null;
+    }
+    if (typeof value === 'object' && 'x' in value && 'y' in value) {
+      return projectPoint({
+        x: value.x,
+        y: value.y,
+        xScale,
+        yScale
+      });
+    }
+
+    // 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 !== void 0 ? _numericXData$index : index;
+        }
+      }
+    }
+    let yValue = value;
+    if (isNumericScale(yScale) && yData && Array.isArray(yData) && yData.length > 0 && typeof yData[0] === 'number' && typeof value === 'number') {
+      yValue = value;
+    }
+    return projectPoint({
+      x: xValue,
+      y: yValue,
+      xScale,
+      yScale
+    });
+  });
+};

package/esm/chart/utils/scale.js

@@ -0,0 +1,48 @@
+import { scaleBand, scaleLinear, scaleLog } from 'd3-scale';
+
+// https://d3js.org/d3-scale - ideal next scale would be time
+
+export const isCategoricalScale = scale => {
+  return scale !== undefined && 'bandwidth' in scale && typeof scale.bandwidth === 'function';
+};
+export const isNumericScale = scale => {
+  return scale !== undefined && !isCategoricalScale(scale);
+};
+
+/**
+ * Type guard to check if a scale is logarithmic.
+ */
+export const isLogScale = scale => {
+  return scale !== undefined && 'base' in scale && typeof scale.base === 'function';
+};
+
+/**
+ * Create a numeric scale (linear or logarithmic)
+ * @returns A numeric scale function
+ */
+export const getNumericScale = _ref => {
+  let {
+    scaleType,
+    domain,
+    range
+  } = _ref;
+  const scale = scaleType === 'log' ? scaleLog() : scaleLinear();
+  return scale.domain([domain.min, domain.max]).range([range.min, range.max]);
+};
+
+/**
+ * Create a categorical scale (band)
+ * @returns A categorical scale function
+ */
+export const getCategoricalScale = _ref2 => {
+  let {
+    domain,
+    range,
+    padding = 0.1
+  } = _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);
+  return scale;
+};

package/esm/index.js

@@ -1 +1,4 @@
-export * from './sparkline';
+// codegen:start {preset: barrel, include: ./*/index.ts}
+export * from './chart';
+export * from './sparkline';
+// codegen:end