@coinbase/cds-mobile-visualization 3.3.0 → 3.4.0-beta.10

package/esm/chart/utils/axis.js

@@ -0,0 +1,592 @@
+const _excluded = ["id"];
+function _extends() { return _extends = Object.assign ? Object.assign.bind() : function (n) { for (var e = 1; e < arguments.length; e++) { var t = arguments[e]; for (var r in t) ({}).hasOwnProperty.call(t, r) && (n[r] = t[r]); } return n; }, _extends.apply(null, arguments); }
+function _objectWithoutPropertiesLoose(r, e) { if (null == r) return {}; var t = {}; for (var n in r) if ({}.hasOwnProperty.call(r, n)) { if (-1 !== e.indexOf(n)) continue; t[n] = r[n]; } return t; }
+import { useCallback, useMemo, useState } from 'react';
+import { getChartDomain, getChartRange, isValidBounds } from './chart';
+import { getCategoricalScale, getNumericScale, isCategoricalScale, isNumericScale } from './scale';
+export const defaultAxisId = 'DEFAULT_AXIS_ID';
+export const defaultAxisScaleType = 'linear';
+
+/**
+ * Axis configuration with computed bounds
+ */
+
+/**
+ * Axis configuration without computed bounds (used for input)
+ */
+
+/**
+ * Gets a D3 scale based on the axis configuration.
+ * Handles both numeric (linear/log) and categorical (band) scales.
+ *
+ * For numeric scales, the domain limit controls whether bounds are "nice" (human-friendly)
+ * or "strict" (exact min/max). Range can be customized using function-based configuration.
+ *
+ * @param params - Scale parameters
+ * @returns The D3 scale function
+ * @throws An Error if bounds are invalid
+ */
+export const getAxisScale = _ref => {
+  var _config$scaleType;
+  let {
+    config,
+    type,
+    range,
+    dataDomain
+  } = _ref;
+  const scaleType = (_config$scaleType = config == null ? void 0 : config.scaleType) != null ? _config$scaleType : 'linear';
+  let adjustedRange = range;
+
+  // Invert range for Y axis for SVG coordinate system
+  if (type === 'y') {
+    adjustedRange = {
+      min: adjustedRange.max,
+      max: adjustedRange.min
+    };
+  }
+  let adjustedDomain = dataDomain;
+  if (config != null && config.domain) {
+    var _config$domain$min, _config$domain$max;
+    adjustedDomain = {
+      min: (_config$domain$min = config.domain.min) != null ? _config$domain$min : dataDomain.min,
+      max: (_config$domain$max = config.domain.max) != null ? _config$domain$max : dataDomain.max
+    };
+  }
+  if (!isValidBounds(adjustedDomain)) throw new Error('Invalid domain bounds. See https://cds.coinbase.com/http://localhost:3000/components/graphs/XAxis/#domain');
+  if (scaleType === 'band') {
+    var _config$categoryPaddi;
+    return getCategoricalScale({
+      domain: adjustedDomain,
+      range: adjustedRange,
+      padding: (_config$categoryPaddi = config == null ? void 0 : config.categoryPadding) != null ? _config$categoryPaddi : 0.3
+    });
+  } else {
+    const scale = getNumericScale({
+      domain: adjustedDomain,
+      range: adjustedRange,
+      scaleType: scaleType
+    });
+    if ((config == null ? void 0 : config.domainLimit) === 'nice') scale.nice();
+    return scale;
+  }
+};
+
+/**
+ * Formats the array of user-provided axis configs with default values and validates axis ids.
+ * Ensures at least one axis config exists if no input is provided.
+ * Requires specific axis ids when there are more than 1 axes.
+ * Defaults the axis id for a single axis config if there is no id.
+ * @param type - the type of axis, 'x' or 'y'
+ * @param axes - array of axis configs or single axis config
+ * @param defaultId - the default id to use for the axis
+ * @param defaultScaleType - the default scale type to use for the axis
+ * @returns array of axis configs with IDs
+ */
+export const getAxisConfig = function (type, axes, defaultId, defaultScaleType) {
+  if (defaultId === void 0) {
+    defaultId = defaultAxisId;
+  }
+  if (defaultScaleType === void 0) {
+    defaultScaleType = defaultAxisScaleType;
+  }
+  const defaultDomainLimit = type === 'x' ? 'strict' : 'nice';
+  if (!axes) {
+    return [{
+      id: defaultId,
+      scaleType: defaultScaleType,
+      domainLimit: defaultDomainLimit
+    }];
+  }
+  if (Array.isArray(axes)) {
+    const axesLength = axes.length;
+    // forces id to be defined on every input config when there are multiple axes
+    if (axesLength > 1 && axes.some(_ref2 => {
+      let {
+        id
+      } = _ref2;
+      return id === undefined;
+    })) {
+      throw new Error('When defining multiple axes, each must have a unique id. See https://cds.coinbase.com/components/graphs/YAxis/#multiple-y-axes.');
+    }
+    return axes.map(_ref3 => {
+      let {
+          id
+        } = _ref3,
+        axis = _objectWithoutPropertiesLoose(_ref3, _excluded);
+      return _extends({
+        // defaults the axis id if only a single axis is provided
+        id: axesLength > 1 ? id != null ? id : defaultAxisId : id,
+        scaleType: defaultScaleType,
+        domainLimit: defaultDomainLimit
+      }, axis);
+    });
+  }
+
+  // Single axis config
+  return [_extends({
+    id: defaultId,
+    scaleType: defaultScaleType,
+    domainLimit: defaultDomainLimit
+  }, axes)];
+};
+
+/**
+ * Calculates the data domain for an axis based on its configuration and series data.
+ * Handles both x and y axes, categorical data, custom domain configurations, and stacking.
+ *
+ * @param axisParam - The axis configuration
+ * @param series - Array of series objects (for stacking support)
+ * @param axisType - Whether this is an 'x' or 'y' axis
+ * @returns The calculated axis bounds
+ */
+export const getAxisDomain = (axisParam, series, axisType) => {
+  var _finalDomain$min, _finalDomain$max;
+  let dataDomain = null;
+  if (axisParam.data && Array.isArray(axisParam.data) && axisParam.data.length > 0) {
+    const firstItem = axisParam.data[0];
+    if (typeof firstItem === 'number') {
+      // Numeric data - use actual min/max values
+      const numericData = axisParam.data;
+      dataDomain = {
+        min: Math.min(...numericData),
+        max: Math.max(...numericData)
+      };
+    } else if (typeof firstItem === 'string') {
+      // String labels - use indices as domain (0 to length-1)
+      // This allows using string labels with linear scales
+      dataDomain = {
+        min: 0,
+        max: axisParam.data.length - 1
+      };
+    }
+  }
+
+  // Calculate domain from series data
+  const seriesDomain = axisType === 'x' ? getChartDomain(series) : getChartRange(series);
+
+  // If data sets the domain, use that instead of the series domain
+  const preferredDataDomain = dataDomain != null ? dataDomain : seriesDomain;
+  const bounds = axisParam.domain;
+  let finalDomain;
+  if (typeof bounds === 'function') {
+    var _preferredDataDomain$, _preferredDataDomain$2;
+    // Apply the transform function to the base domain
+    // No need to default to 0 here since we'll do it once at the end
+    finalDomain = bounds({
+      min: (_preferredDataDomain$ = preferredDataDomain.min) != null ? _preferredDataDomain$ : 0,
+      max: (_preferredDataDomain$2 = preferredDataDomain.max) != null ? _preferredDataDomain$2 : 0
+    });
+  } else if (bounds && typeof bounds === 'object') {
+    var _bounds$min, _bounds$max;
+    // Merge explicit bounds with calculated domain
+    finalDomain = {
+      min: (_bounds$min = bounds.min) != null ? _bounds$min : preferredDataDomain.min,
+      max: (_bounds$max = bounds.max) != null ? _bounds$max : preferredDataDomain.max
+    };
+  } else {
+    // Use the base domain as-is
+    finalDomain = preferredDataDomain;
+  }
+
+  // Ensure we always return valid bounds with no undefined values
+  return {
+    min: (_finalDomain$min = finalDomain.min) != null ? _finalDomain$min : 0,
+    max: (_finalDomain$max = finalDomain.max) != null ? _finalDomain$max : 0
+  };
+};
+
+/**
+ * Calculates the visual range for an axis based on the chart rectangle and configuration.
+ * Handles custom range configurations including functions and partial bounds.
+ *
+ * @param axisParam - The axis configuration
+ * @param chartRect - The chart drawing area rectangle
+ * @param axisType - Whether this is an 'x' or 'y' axis
+ * @returns The calculated axis range bounds
+ */
+export const getAxisRange = (axisParam, chartRect, axisType) => {
+  // Calculate base range based on axis type
+  let baseRange;
+  if (axisType === 'x') {
+    baseRange = {
+      min: chartRect.x,
+      max: chartRect.x + chartRect.width
+    };
+  } else {
+    baseRange = {
+      min: chartRect.y,
+      max: chartRect.y + chartRect.height
+    };
+  }
+
+  // Apply any custom range configuration
+  const rangeConfig = axisParam.range;
+  if (!rangeConfig) {
+    return baseRange;
+  }
+  if (typeof rangeConfig === 'function') {
+    // Apply the transform function to the base range
+    return rangeConfig(baseRange);
+  } else {
+    var _rangeConfig$min, _rangeConfig$max;
+    // Merge explicit range values with calculated range
+    return {
+      min: (_rangeConfig$min = rangeConfig.min) != null ? _rangeConfig$min : baseRange.min,
+      max: (_rangeConfig$max = rangeConfig.max) != null ? _rangeConfig$max : baseRange.max
+    };
+  }
+};
+
+/**
+ * Options for tick generation behavior
+ */
+
+/**
+ * Formats a tick value for display on an axis.
+ * Consolidates the identical formatting logic shared between XAxis and YAxis.
+ *
+ * @param value - The raw tick value to format
+ * @param tickFormatter - Optional custom formatter function
+ * @returns The formatted tick value as a React node
+ */
+export const formatAxisTick = (value, tickFormatter) => {
+  if (tickFormatter) {
+    return tickFormatter(value);
+  }
+  return value;
+};
+
+/**
+ * Calculates a rounded step size for tick generation.
+ * Chooses from multiples of 1, 2, or 5 (scaled by powers of 10).
+ *
+ * @param roughStep - The approximate step size needed
+ * @param minStep - Optional minimum step size constraint
+ * @param maxStep - Optional maximum step size constraint
+ * @returns rounded step size within the specified constraints
+ */
+const calculateNiceStep = (roughStep, minStep, maxStep) => {
+  if (roughStep <= 0) return minStep != null ? minStep : 1;
+  const magnitude = Math.pow(10, Math.floor(Math.log10(roughStep)));
+  const residual = roughStep / magnitude;
+  let roundResidual;
+  if (residual <= 1) {
+    roundResidual = 1;
+  } else if (residual <= 2) {
+    roundResidual = 2;
+  } else if (residual <= 5) {
+    roundResidual = 5;
+  } else {
+    roundResidual = 10;
+  }
+  let niceStep = roundResidual * magnitude;
+  if (minStep !== undefined && niceStep < minStep) {
+    niceStep = minStep;
+  }
+  if (maxStep !== undefined && niceStep > maxStep) {
+    niceStep = maxStep;
+  }
+  return niceStep;
+};
+
+/**
+ * Generates evenly distributed tick values.
+ * Always includes first and last domain values, with intermediate ticks evenly distributed using nice step sizes.
+ * Selects from actual data points (possibleTickValues) or generates nice round numbers.
+ *
+ * @param scale - The numeric scale function
+ * @param tickInterval - Space between ticks (in pixels)
+ * @param possibleTickValues - Optional array of possible tick values to select from (e.g., data indices). If not provided, generates nice round numbers with guaranteed first/last inclusion.
+ * @param options - Options for tick generation behavior
+ * @returns Array of tick values, always including first and last domain values
+ */
+const generateEvenlyDistributedTicks = (scale, tickInterval, possibleTickValues, options) => {
+  var _options$minTickCount;
+  const minTickCount = (_options$minTickCount = options == null ? void 0 : options.minTickCount) != null ? _options$minTickCount : 4;
+  const [rangeMin, rangeMax] = scale.range();
+  const range = Math.abs(rangeMax - rangeMin);
+  const tickCountFromSpace = Math.floor(range / tickInterval);
+  const tickCount = Math.max(tickCountFromSpace, minTickCount);
+  if (tickCount < 1) {
+    return [];
+  }
+
+  // If we have possibleTickValues, select evenly from them
+  if (possibleTickValues && possibleTickValues.length > 0) {
+    // Limit tick count to available values
+    const finalTickCount = Math.min(tickCount, possibleTickValues.length);
+    const tickValues = [];
+    const step = (possibleTickValues.length - 1) / (finalTickCount - 1);
+    for (let i = 0; i < finalTickCount; i++) {
+      const index = i === finalTickCount - 1 ? possibleTickValues.length - 1 : Math.round(step * i);
+      tickValues.push(possibleTickValues[index]);
+    }
+    return tickValues;
+  }
+
+  // Generate nice round numbers that always include first and last domain values
+  const [domainMin, domainMax] = scale.domain();
+  if (tickCount === 1) {
+    return [domainMin];
+  }
+  if (tickCount === 2) {
+    return [domainMin, domainMax];
+  }
+
+  // Calculate a nice step size
+  const domainRange = domainMax - domainMin;
+  const roughStep = domainRange / (tickCount - 1);
+  const niceStep = calculateNiceStep(roughStep, options == null ? void 0 : options.minStep, options == null ? void 0 : options.maxStep);
+
+  // Generate ticks starting from domainMin and stepping by niceStep
+  const tickValues = [domainMin];
+
+  // Generate intermediate ticks using the nice step, starting from domainMin
+  let currentTick = domainMin + niceStep;
+  while (currentTick < domainMax) {
+    // Avoid floating point precision issues
+    const roundedTick = Number(currentTick.toFixed(10));
+    tickValues.push(roundedTick);
+    currentTick += niceStep;
+  }
+
+  // Only include domainMax if it naturally falls on a step (or very close due to floating point)
+  // or if the last tick is far enough away that including max provides useful context
+  const lastTick = tickValues[tickValues.length - 1];
+  const distanceToMax = domainMax - lastTick;
+
+  // Include max if:
+  // 1. It naturally falls on a step (within floating point tolerance)
+  // 2. Or the last tick is more than half a step away (provides meaningful context)
+  const tolerance = niceStep * 0.0001; // Floating point tolerance
+  const shouldIncludeMax = Math.abs(distanceToMax - niceStep) < tolerance ||
+  // Natural step
+  distanceToMax > niceStep * 0.5; // Far enough to provide context
+
+  if (shouldIncludeMax && domainMax !== lastTick) {
+    tickValues.push(domainMax);
+  }
+  return tickValues;
+};
+
+/**
+ * Processes tick configuration and returns tick data with positions.
+ *
+ * **Parameter Precedence by Scale Type:**
+ *
+ * **For Numeric Scales (linear/log):**
+ * 1. `ticks` (array) - Explicit tick values override all other options
+ * 2. `ticks` (function) - Filter function for tick selection
+ * 3. `ticks` (boolean) - Show/hide all possible ticks
+ * 4. `requestedTickCount` - D3 automatic tick generation (overrides tickInterval)
+ * 5. `tickInterval` - Pixel-based spacing (fallback)
+ *
+ * **For Categorical Scales (band):**
+ * 1. `ticks` (array) - Explicit category indices to display
+ * 2. `ticks` (function) - Filter function for category selection
+ * 3. `ticks` (boolean) - Show/hide all categories
+ * 4. Default - Show all categories (requestedTickCount and tickInterval are ignored)
+ *
+ * @param params - Tick processing parameters
+ * @param params.ticks - Custom tick configuration with multiple formats:
+ *   - **Array**: For numeric scales: exact tick values; For band scales: category indices
+ *   - **Function**: Predicate to filter tick values or category indices
+ *   - **Boolean**: Show all (true) or no ticks (false) for both scale types
+ * @param params.scaleFunction - D3 scale function (numeric or band scale)
+ * @param params.requestedTickCount - Number of ticks for D3 generation (**numeric scales only**, overrides tickInterval)
+ * @param params.categories - Category labels (**band scales only**)
+ * @param params.possibleTickValues - Available tick values for filtering/selection (**numeric scales only**)
+ * @param params.tickInterval - Pixel spacing between ticks (**numeric scales only**, fallback option)
+ * @returns Array of tick data with values and positions
+ *
+ * @example
+ * // Basic usage with tickInterval for pixel-based spacing
+ * import { scaleLinear } from 'd3-scale';
+ *
+ * const numericScale = scaleLinear().domain([0, 10]).range([0, 400]);
+ * const result = getAxisTicksData({
+ *   scaleFunction: numericScale,
+ *   tickInterval: 80, // 80 pixels between ticks
+ *   possibleTickValues: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ * });
+ * // Returns: [
+ * //   { tick: 0, position: 0 },    // Always includes first
+ * //   { tick: 2, position: 80 },
+ * //   { tick: 5, position: 200 },
+ * //   { tick: 7, position: 280 },
+ * //   { tick: 10, position: 400 }  // Always includes last
+ * // ]
+ *
+ * @example
+ * // Using requestedTickCount for D3-generated ticks
+ * const result = getAxisTicksData({
+ *   scaleFunction: numericScale,
+ *   requestedTickCount: 5
+ * });
+ * // Uses D3's tick generation algorithm
+ *
+ * @example
+ * // Using explicit tick values
+ * const result = getAxisTicksData({
+ *   scaleFunction: numericScale,
+ *   ticks: [0, 2.5, 5, 7.5, 10]
+ * });
+ * // Returns exact positions for specified values
+ *
+ * @example
+ * // Using tick filter function
+ * const result = getAxisTicksData({
+ *   scaleFunction: numericScale,
+ *   ticks: (value) => value % 2 === 0, // Only even numbers
+ *   possibleTickValues: [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
+ * });
+ * // Returns: [0, 2, 4, 6, 8, 10] with their positions
+ *
+ * @example
+ * // Band scale with categories (requestedTickCount and tickInterval are ignored)
+ * import { scaleBand } from 'd3-scale';
+ *
+ * const bandScale = scaleBand().domain([0, 1, 2, 3, 4]).range([0, 400]).padding(0.1);
+ * const result = getAxisTicksData({
+ *   scaleFunction: bandScale,
+ *   categories: ['Jan', 'Feb', 'Mar', 'Apr', 'May'],
+ *   ticks: [0, 2, 4], // Show only Jan (index 0), Mar (index 2), May (index 4)
+ *   requestedTickCount: 10, // IGNORED for band scales
+ *   tickInterval: 50 // IGNORED for band scales
+ * });
+ * // Returns tick positions centered in each selected band
+ */
+export const getAxisTicksData = _ref4 => {
+  let {
+    ticks,
+    scaleFunction,
+    requestedTickCount,
+    categories = [],
+    possibleTickValues,
+    tickInterval,
+    options
+  } = _ref4;
+  // Handle band scales
+  if (isCategoricalScale(scaleFunction)) {
+    // If explicit ticks are provided as array, use them
+    if (Array.isArray(ticks)) {
+      return ticks.filter(index => index >= 0 && index < categories.length).map(index => {
+        var _bandwidth;
+        // Band scales expect numeric indices, not category strings
+        const position = scaleFunction(index);
+        if (position === undefined) return null;
+        return {
+          tick: index,
+          position: position + ((_bandwidth = scaleFunction.bandwidth == null ? void 0 : scaleFunction.bandwidth()) != null ? _bandwidth : 0) / 2
+        };
+      }).filter(Boolean);
+    }
+
+    // If a tick function is provided, use it to filter
+    if (typeof ticks === 'function') {
+      return categories.map((category, index) => {
+        var _bandwidth2;
+        if (!ticks(index)) return null;
+
+        // Band scales expect numeric indices, not category strings
+        const position = scaleFunction(index);
+        if (position === undefined) return null;
+        return {
+          tick: index,
+          position: position + ((_bandwidth2 = scaleFunction.bandwidth == null ? void 0 : scaleFunction.bandwidth()) != null ? _bandwidth2 : 0) / 2
+        };
+      }).filter(Boolean);
+    }
+    if (typeof ticks === 'boolean' && !ticks) {
+      return [];
+    }
+
+    // For band scales without explicit ticks, show all categories
+    // requestedTickCount is ignored for categorical scales - use ticks parameter to control visibility
+    return categories.map((category, index) => {
+      var _bandwidth3;
+      // Band scales expect numeric indices, not category strings
+      const position = scaleFunction(index);
+      if (position === undefined) return null;
+      return {
+        tick: index,
+        position: position + ((_bandwidth3 = scaleFunction.bandwidth == null ? void 0 : scaleFunction.bandwidth()) != null ? _bandwidth3 : 0) / 2
+      };
+    }).filter(Boolean);
+  }
+
+  // Handle numeric scales
+  if (!isNumericScale(scaleFunction)) {
+    console.warn('Scale does not support automatic tick generation');
+    return [];
+  }
+  const numericScale = scaleFunction;
+  let tickValues = [];
+  if (Array.isArray(ticks)) {
+    // Use exact tick values provided
+    tickValues = ticks;
+  } else if (typeof ticks === 'function') {
+    // Filter the possible tick values using the predicate function
+    if (possibleTickValues) {
+      tickValues = possibleTickValues.filter(ticks);
+    } else {
+      // Fallback to scale-generated ticks if no possible tick values provided
+      const generatedTicks = numericScale.ticks(requestedTickCount);
+      tickValues = generatedTicks.filter(ticks);
+    }
+  } else if (requestedTickCount !== undefined) {
+    // Use scale-generated ticks
+    tickValues = numericScale.ticks(requestedTickCount);
+  } else if (tickInterval !== undefined) {
+    tickValues = generateEvenlyDistributedTicks(numericScale, tickInterval, possibleTickValues, options);
+  }
+
+  // Map values to positions using the scale function
+  return tickValues.map(tick => ({
+    tick,
+    position: numericScale(tick)
+  }));
+};
+/**
+ * Calculates the total amount of padding needed to render a set of axes on the main drawing area of the chart.
+ * Returns the registed axes, an API for adding/removing axes as well as the total calculated padding that must be reserved in the drawing area.
+ */
+export const useTotalAxisPadding = () => {
+  const [renderedAxes, setRenderedAxes] = useState(new Map());
+  const registerAxis = useCallback((id, position, size) => {
+    setRenderedAxes(prev => {
+      const newMap = new Map(prev);
+      newMap.set(id, {
+        id,
+        position,
+        size
+      });
+      return newMap;
+    });
+  }, []);
+  const unregisterAxis = useCallback(id => {
+    setRenderedAxes(prev => {
+      const newMap = new Map(prev);
+      newMap.delete(id);
+      return newMap;
+    });
+  }, []);
+  const axisPadding = useMemo(() => {
+    const padding = {
+      top: 0,
+      right: 0,
+      bottom: 0,
+      left: 0
+    };
+    renderedAxes.forEach(axis => {
+      padding[axis.position] += axis.size;
+    });
+    return padding;
+  }, [renderedAxes]);
+  return {
+    renderedAxes,
+    axisPadding,
+    registerAxis,
+    unregisterAxis
+  };
+};

package/esm/chart/utils/bar.js

@@ -0,0 +1,24 @@
+/**
+ * Calculates the size adjustment needed for bars when accounting for gaps between them.
+ * This function helps determine how much to reduce each bar's width to accommodate
+ * the specified gap size between multiple bars in a group.
+ *
+ * @param barCount - The number of bars in the group
+ * @param gapSize - The desired gap size between bars
+ * @returns The amount to reduce each bar's size by, or 0 if there's only one bar
+ *
+ * @example
+ * ```typescript
+ * // For 3 bars with 12px gaps, each bar should be reduced by 8px
+ * const adjustment = getBarSizeAdjustment(3, 12);
+ *
+ * // Single bar needs no adjustment
+ * const singleBarAdjustment = getBarSizeAdjustment(1, 10);
+ * ```
+ */
+export function getBarSizeAdjustment(barCount, gapSize) {
+  if (barCount <= 1) {
+    return 0;
+  }
+  return gapSize * (barCount - 1) / barCount;
+}