@coinbase/cds-web 8.66.1 → 9.0.0-rc.1

package/esm/visualizations/chart/utils/chart.js

@@ -0,0 +1,314 @@
+import { stack as d3Stack, stackOffsetDiverging, stackOrderNone } from 'd3-shape';
+import { defaultAxisId } from './axis';
+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
+ * @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 dataLength = 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 (dataLength > 0) {
+      if (domain.min === undefined) domain.min = 0;
+      if (domain.max === undefined) domain.max = dataLength - 1;
+    }
+  }
+  return domain;
+};
+
+/**
+ * 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 axis IDs to prevent cross-scale stacking
+  const xAxisId = series.xAxisId || 'default';
+  const yAxisId = series.yAxisId || 'default';
+  return "".concat(series.stackId, ":").concat(xAxisId, ":").concat(yAxisId);
+};
+
+/**
+ * Get the baseline for a series on the value axis for a series (stacking and plain numeric points).
+ * @returns The baseline for the series on the value axis, or `0` if none.
+ */
+const getValueAxisBaselineForSeries = (layout, series, xAxisConfigs, yAxisConfigs) => {
+  var _series$yAxisId, _yAxisConfigs$find$ba, _yAxisConfigs$find;
+  if (layout === 'horizontal') {
+    var _series$xAxisId, _xAxisConfigs$find$ba, _xAxisConfigs$find;
+    const seriesAxisId = (_series$xAxisId = series.xAxisId) !== null && _series$xAxisId !== void 0 ? _series$xAxisId : defaultAxisId;
+    return (_xAxisConfigs$find$ba = (_xAxisConfigs$find = xAxisConfigs.find(a => a.id === seriesAxisId)) === null || _xAxisConfigs$find === void 0 ? void 0 : _xAxisConfigs$find.baseline) !== null && _xAxisConfigs$find$ba !== void 0 ? _xAxisConfigs$find$ba : 0;
+  }
+  const seriesAxisId = (_series$yAxisId = series.yAxisId) !== null && _series$yAxisId !== void 0 ? _series$yAxisId : defaultAxisId;
+  return (_yAxisConfigs$find$ba = (_yAxisConfigs$find = yAxisConfigs.find(a => a.id === seriesAxisId)) === null || _yAxisConfigs$find === void 0 ? void 0 : _yAxisConfigs$find.baseline) !== null && _yAxisConfigs$find$ba !== void 0 ? _yAxisConfigs$find$ba : 0;
+};
+
+/**
+ * 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
+ * @param layout - When set with axis configs, value-axis baselines are resolved for stacking
+ * @returns Map of series ID to stacked data arrays
+ */
+export const getStackedSeriesData = (series, layout, xAxisConfigs, yAxisConfigs) => {
+  const stackedDataMap = new Map();
+  const numericStackGroups = new Map();
+  const individualSeries = [];
+  const normalizeSeriesData = seriesItem => {
+    if (!seriesItem.data) return;
+    const baseline = getValueAxisBaselineForSeries(layout, seriesItem, xAxisConfigs, yAxisConfigs);
+    return seriesItem.data.map(val => {
+      if (val === null) return null;
+      if (Array.isArray(val)) {
+        return val;
+      }
+      if (typeof val === 'number') return [baseline, val];
+      return null;
+    });
+  };
+  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 => {
+    const normalizedData = normalizeSeriesData(s);
+    if (!normalizedData) return;
+    stackedDataMap.set(s.id, normalizedData);
+  });
+  numericStackGroups.forEach(groupSeries => {
+    // A lone series with stackId should still behave like a non-stacked series.
+    if (groupSeries.length < 2) {
+      groupSeries.forEach(singleSeries => {
+        const normalizedData = normalizeSeriesData(singleSeries);
+        if (!normalizedData) return;
+        stackedDataMap.set(singleSeries.id, normalizedData);
+      });
+      return;
+    }
+    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 first = groupSeries[0];
+    const groupBaseline = getValueAxisBaselineForSeries(layout, first, xAxisConfigs, yAxisConfigs);
+    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];
+        // Stack around baseline by translating values into baseline-relative deltas.
+        const num = typeof val === 'number' ? val - groupBaseline : 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 + groupBaseline, top + groupBaseline];
+      });
+      stackedDataMap.set(seriesId, stackedData);
+    });
+  });
+  return stackedDataMap;
+};
+
+/**
+ * Extracts line data values from series data that may contain tuples.
+ * For tuple data [[baseline, value]], extracts the last value.
+ * For numeric data [value], returns as-is.
+ *
+ * @param data - Array of numbers, tuples, or null values
+ * @returns Array of numbers or null values
+ */
+export const getLineData = data => {
+  if (!data) return [];
+
+  // Check if this is tuple data by finding first non-null entry
+  const firstNonNull = data.find(d => d !== null);
+  if (Array.isArray(firstNonNull)) {
+    return data.map(d => {
+      var _d;
+      if (d === null) return null;
+      if (Array.isArray(d)) return (_d = d[d.length - 1]) !== null && _d !== void 0 ? _d : null;
+      return d;
+    });
+  }
+
+  // Already numeric data
+  return data;
+};
+
+/**
+ * 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, layout, xAxisConfigs, yAxisConfigs, 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, layout, xAxisConfigs, yAxisConfigs);
+
+    // Find the extreme values from the stacked data
+    let stackedMax = -Infinity;
+    let stackedMin = Infinity;
+    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 = stackedMin === Infinity ? 0 : stackedMin;
+    if (range.max === undefined) range.max = stackedMax === -Infinity ? 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 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.
+ * @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/visualizations/chart/utils/context.js

@@ -0,0 +1,22 @@
+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.
+ */
+
+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/visualizations/chart/utils/gradient.js

@@ -0,0 +1,270 @@
+import { isCategoricalScale } from './scale';
+
+/**
+ * Defines a color transition point in the gradient
+ */
+
+/**
+ * Defines a gradient.
+ */
+
+/**
+ * Resolves the axis used for gradient processing.
+ */
+export const getGradientAxis = (gradient, layout) => {
+  var _gradient$axis;
+  return (_gradient$axis = gradient.axis) !== null && _gradient$axis !== void 0 ? _gradient$axis : layout === 'horizontal' ? 'x' : 'y';
+};
+
+/**
+ * Resolves gradient stops, handling both static arrays and function forms.
+ * When stops is a function, calls it with the domain bounds.
+ */
+const getGradientStops = (stops, domain) => {
+  if (typeof stops === 'function') {
+    return stops(domain);
+  }
+  return stops;
+};
+
+/**
+ * Processes Gradient to gradient configuration for SVG linearGradient.
+ * Colors are smoothly interpolated between stops by the browser.
+ * Multiple stops at the same offset create hard color transitions.
+ */
+const processGradientStops = (stops, scale) => {
+  if (stops.length === 0) {
+    console.warn('Gradient has no stops - falling back to default');
+    return;
+  }
+
+  // Check if stops are in ascending order
+  const isOutOfOrder = stops.some((stop, i) => {
+    return i > 0 && stop.offset < stops[i - 1].offset;
+  });
+  if (isOutOfOrder) {
+    console.warn("Gradient: stop offsets must be in ascending order");
+    return;
+  }
+  const [rangeMin, rangeMax] = scale.range();
+  const rangeSpan = Math.abs(rangeMax - rangeMin);
+
+  // Convert data value offsets to normalized positions (0-1) using scale
+  const normalizedStops = stops.map(stop => {
+    var _stop$opacity;
+    const stopPosition = scale(stop.offset);
+    const normalized = stopPosition === undefined ? 0 : Math.max(0, Math.min(1, Math.abs(stopPosition - rangeMin) / rangeSpan));
+    return {
+      offset: normalized,
+      // Now 0-1 normalized (not data space)
+      color: stop.color,
+      opacity: (_stop$opacity = stop.opacity) !== null && _stop$opacity !== void 0 ? _stop$opacity : 1
+    };
+  }).sort((a, b) => a.offset - b.offset);
+  return normalizedStops;
+};
+
+/**
+ * Evaluates the color at a specific data value based on the gradient stops, ignoring opacity.
+ * @param stops - The gradient stops configuration
+ * @param dataValue - The data value to evaluate (for band scales, this is the index)
+ * @param scale - The scale to use for value mapping (handles log scales correctly)
+ * @returns The color string at this data value, or undefined if invalid
+ */
+export const evaluateGradientAtValue = (stops, dataValue, scale) => {
+  if (stops.length === 0) return;
+
+  // Use srgb color space to match our linearGradient which uses srgb color space
+  // https://www.w3.org/TR/SVG11/painting.html#ColorInterpolationProperty
+  const colorSpace = 'srgb';
+
+  // Use scale to map values to positions (handles log scales correctly)
+  // For numeric scales: scale(value) returns pixel position
+  // We normalize these positions to 0-1 based on the range
+  const scaleRange = scale.range();
+  const [rangeMin, rangeMax] = Array.isArray(scaleRange) ? scaleRange : [scaleRange, scaleRange]; // fallback for band scales
+
+  const rangeSpan = Math.abs(rangeMax - rangeMin);
+  if (rangeSpan === 0) return stops[0].color;
+
+  // Map dataValue through scale to get position
+  const dataPosition = scale(dataValue);
+  if (dataPosition === undefined) return stops[0].color;
+
+  // Normalize to 0-1 based on range
+  const normalizedValue = Math.max(0, Math.min(1, Math.abs(dataPosition - rangeMin) / rangeSpan));
+
+  // stops already have normalized offsets (0-1), use them directly
+  const positions = stops.map(stop => stop.offset);
+
+  // Find which segment we're in
+  if (normalizedValue < positions[0]) {
+    return stops[0].color;
+  }
+  if (normalizedValue >= positions[positions.length - 1]) {
+    return stops[stops.length - 1].color;
+  }
+
+  // Check if normalizedValue matches any stop offset exactly (for hard transitions)
+  for (let i = 0; i < stops.length; i++) {
+    if (Math.abs(normalizedValue - stops[i].offset) < 1e-10) {
+      // Found exact match - check if there are multiple stops at this offset (hard transition)
+      // Use the LAST color at this offset for hard transitions
+      let lastIndexAtOffset = i;
+      while (lastIndexAtOffset + 1 < stops.length && Math.abs(stops[lastIndexAtOffset + 1].offset - stops[i].offset) < 1e-10) {
+        lastIndexAtOffset++;
+      }
+      return stops[lastIndexAtOffset].color;
+    }
+  }
+
+  // Find the two colors to mix based on normalized positions
+  for (let i = 0; i < positions.length - 1; i++) {
+    const start = positions[i];
+    const end = positions[i + 1];
+    if (normalizedValue >= start && normalizedValue <= end) {
+      const segmentProgress = (normalizedValue - start) / (end - start);
+      return "color-mix(in ".concat(colorSpace, ", ").concat(stops[i + 1].color, " ").concat(segmentProgress * 100, "%, ").concat(stops[i].color, ")");
+    }
+  }
+
+  // If we didn't reach any to be mixed, return the last color
+  return stops[stops.length - 1].color;
+};
+
+/**
+ * Creates a gradient configuration for SVG components.
+ * Processes a GradientDefinition into a renderable GradientConfig.
+ * Supports both numeric scales (linear, log) and categorical scales (band).
+ *
+ * @param gradient - GradientDefinition configuration
+ * @param xScale - X-axis scale
+ * @param yScale - Y-axis scale
+ * @param layout - Chart layout
+ * @returns GradientConfig or null if gradient processing fails
+ *
+ * @example
+ * const gradientConfig = useMemo(() => {
+ *   if (!gradient || !xScale || !yScale) return;
+ *   return getGradientConfig(gradient, xScale, yScale);
+ * }, [gradient, xScale, yScale]);
+ *
+ * if (gradientConfig) {
+ *   return (
+ *     <defs>
+ *       <Gradient
+ *         config={gradientConfig}
+ *         direction={gradient.axis === 'x' ? 'horizontal' : 'vertical'}
+ *         id={gradientId}
+ *       />
+ *     </defs>
+ *   );
+ * }
+ */
+export const getGradientConfig = function (gradient, xScale, yScale) {
+  let layout = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 'vertical';
+  if (!gradient) return;
+
+  // Get the scale based on axis
+  const axis = getGradientAxis(gradient, layout);
+  const scale = axis === 'x' ? xScale : yScale;
+  if (!scale) return;
+
+  // Extract domain from scale
+  const scaleDomain = scale.domain();
+  let domain;
+  if (isCategoricalScale(scale)) {
+    const domainArray = scaleDomain;
+    domain = {
+      min: domainArray[0],
+      max: domainArray[domainArray.length - 1]
+    };
+  } else {
+    const [min, max] = scaleDomain;
+    domain = {
+      min,
+      max
+    };
+  }
+  const resolvedStops = getGradientStops(gradient.stops, domain);
+  return processGradientStops(resolvedStops, scale);
+};
+
+/**
+ * Determines the baseline value for the gradient area by finding the value
+ * within the axis bounds that is closest to the target baseline.
+ *
+ * @param axisBounds - The min and max bounds of the axis
+ * @param baseline - The target baseline value (defaults to 0)
+ * @returns The value within bounds closest to the baseline
+ */
+export const getBaseline = function (axisBounds) {
+  let baseline = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
+  const {
+    min,
+    max
+  } = axisBounds;
+
+  // Normalize to ensure lowerBound <= upperBound
+  const lowerBound = Math.min(min, max);
+  const upperBound = Math.max(min, max);
+
+  // If baseline is within the range, use it
+  if (lowerBound <= baseline && baseline <= upperBound) return baseline;
+
+  // Otherwise, return the bound closest to baseline
+  return Math.abs(lowerBound - baseline) < Math.abs(upperBound - baseline) ? lowerBound : upperBound;
+};
+
+/**
+ * Generates a gradient definition for the area chart based on the axis bounds
+ * and styling parameters. Ensures gradient stops are in ascending order.
+ *
+ * @param axisBounds - The min and max bounds of the axis
+ * @param baselineValue - The baseline value for the gradient
+ * @param fill - The color to use for the gradient
+ * @param peakOpacity - Opacity at the peak of the gradient
+ * @param baselineOpacity - Opacity at the baseline
+ * @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 = function (axisBounds, baselineValue, fill, peakOpacity, baselineOpacity) {
+  let axis = arguments.length > 5 && arguments[5] !== undefined ? arguments[5] : 'y';
+  const {
+    min,
+    max
+  } = axisBounds;
+  const lowerBound = Math.min(min, max);
+  const upperBound = Math.max(min, max);
+  if (lowerBound < baselineValue && baselineValue < upperBound) {
+    return {
+      axis,
+      stops: [{
+        offset: lowerBound,
+        color: fill,
+        opacity: peakOpacity
+      }, {
+        offset: baselineValue,
+        color: fill,
+        opacity: baselineOpacity
+      }, {
+        offset: upperBound,
+        color: fill,
+        opacity: peakOpacity
+      }]
+    };
+  }
+  const peakValue = Math.abs(min - baselineValue) > Math.abs(max - baselineValue) ? min : max;
+  return {
+    axis,
+    stops: [{
+      offset: peakValue,
+      color: fill,
+      opacity: peakOpacity
+    }, {
+      offset: baselineValue,
+      color: fill,
+      opacity: baselineOpacity
+    }].sort((a, b) => a.offset - b.offset)
+  };
+};

package/esm/visualizations/chart/utils/index.js

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