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

package/esm/chart/utils/axis.js

@@ -8,10 +8,41 @@ function _objectWithoutProperties(e, t) { if (null == e) return {}; var o, r, i
 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 { getPointOnScale } from './point';
 import { getCategoricalScale, getNumericScale, isCategoricalScale, isNumericScale } from './scale';
 export const defaultAxisId = 'DEFAULT_AXIS_ID';
 export const defaultAxisScaleType = 'linear';
 
+/**
+ * Position options for band scale axis elements.
+ *
+ * - `'start'` - At the start of each step (before bar padding)
+ * - `'middle'` - At the center of each band
+ * - `'end'` - At the end of each step (after bar padding)
+ * - `'edges'` - At start of each tick, plus end for the last tick (encloses the chart)
+ *
+ * @note These properties only apply when using a band scale (`scaleType: 'band'`).
+ */
+
+/**
+ * Converts an AxisBandPlacement to the corresponding PointAnchor for use with getPointOnScale.
+ *
+ * @param placement - The axis placement value
+ * @returns The corresponding PointAnchor for scale calculations
+ */
+export const toPointAnchor = placement => {
+  switch (placement) {
+    case 'edges': // edges uses stepStart for each tick, stepEnd handled separately
+    case 'start':
+      return 'stepStart';
+    case 'end':
+      return 'stepEnd';
+    case 'middle':
+    default:
+      return 'middle';
+  }
+};
+
 /**
  * Axis configuration with computed bounds
  */
@@ -27,23 +58,36 @@ export const defaultAxisScaleType = 'linear';
  * 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.
  *
+ * Range inversion is determined by axis role (category vs value) and layout:
+ * - Vertical layout: Y axis (value) is inverted for SVG coordinate system
+ * - Horizontal layout: Y axis (category) is inverted (first category at top)
+ *
  * @param params - Scale parameters
  * @returns The D3 scale function
  * @throws An Error if bounds are invalid
  */
-export const getAxisScale = _ref => {
+export const getCartesianAxisScale = _ref => {
   var _config$scaleType;
   let {
     config,
     type,
     range,
-    dataDomain
+    dataDomain,
+    layout = 'vertical'
   } = _ref;
   const scaleType = (_config$scaleType = config === null || config === void 0 ? void 0 : config.scaleType) !== null && _config$scaleType !== void 0 ? _config$scaleType : 'linear';
   let adjustedRange = range;
 
-  // Invert range for Y axis for SVG coordinate system
-  if (type === 'y') {
+  // Determine if this axis needs range inversion for SVG coordinate system.
+  // SVG Y coordinates increase downward, so we need to invert for value axes
+  // where we want higher values at the top.
+  //
+  // For vertical layout: Y axis is the value axis → invert (higher values at top)
+  // For horizontal layout: Y axis is the category axis → don't invert (first category at top is natural)
+  // X axis never needs inversion (left-to-right is natural for both layouts)
+
+  const shouldInvertRange = type === 'y' && layout !== 'horizontal';
+  if (shouldInvertRange) {
     adjustedRange = {
       min: adjustedRange.max,
       max: adjustedRange.min
@@ -57,7 +101,7 @@ export const getAxisScale = _ref => {
       max: (_config$domain$max = config.domain.max) !== null && _config$domain$max !== void 0 ? _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 (!isValidBounds(adjustedDomain)) throw new Error('Invalid domain bounds. See https://cds.coinbase.com/components/charts/XAxis/#domain');
   if (scaleType === 'band') {
     var _config$categoryPaddi;
     return getCategoricalScale({
@@ -91,6 +135,8 @@ export const getAxisConfig = function (type, axes) {
   let defaultId = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : defaultAxisId;
   let defaultScaleType = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : defaultAxisScaleType;
   const defaultDomainLimit = type === 'x' ? 'strict' : 'nice';
+  const axisName = type === 'x' ? 'x-axis' : 'y-axis';
+  const axisDocUrl = type === 'x' ? 'https://cds.coinbase.com/components/charts/XAxis' : 'https://cds.coinbase.com/components/charts/YAxis';
   if (!axes) {
     return [{
       id: defaultId,
@@ -107,16 +153,27 @@ export const getAxisConfig = function (type, axes) {
       } = _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.');
+      throw new Error("When defining multiple ".concat(axisName, ", each must have a unique id. See ").concat(axisDocUrl, "."));
     }
-    return axes.map(_ref3 => {
+    if (axesLength > 1) {
+      const ids = axes.map(_ref3 => {
+        let {
+          id
+        } = _ref3;
+        return id;
+      }).filter(id => id !== undefined);
+      if (new Set(ids).size !== ids.length) {
+        throw new Error("When defining multiple ".concat(axisName, ", each must have a unique id. See ").concat(axisDocUrl, "."));
+      }
+    }
+    return axes.map(_ref4 => {
       let {
           id
-        } = _ref3,
-        axis = _objectWithoutProperties(_ref3, _excluded);
+        } = _ref4,
+        axis = _objectWithoutProperties(_ref4, _excluded);
       return _objectSpread({
         // defaults the axis id if only a single axis is provided
-        id: axesLength > 1 ? id !== null && id !== void 0 ? id : defaultAxisId : id,
+        id: axesLength > 1 ? id !== null && id !== void 0 ? id : defaultAxisId : id !== null && id !== void 0 ? id : defaultId,
         scaleType: defaultScaleType,
         domainLimit: defaultDomainLimit
       }, axis);
@@ -138,10 +195,12 @@ export const getAxisConfig = function (type, axes) {
  * @param axisParam - The axis configuration
  * @param series - Array of series objects (for stacking support)
  * @param axisType - Whether this is an 'x' or 'y' axis
+ * @param layout - Chart layout ('horizontal' or 'vertical')
  * @returns The calculated axis bounds
  */
-export const getAxisDomain = (axisParam, series, axisType) => {
+export const getCartesianAxisDomain = function (axisParam, series, axisType) {
   var _finalDomain$min, _finalDomain$max;
+  let layout = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : 'vertical';
   let dataDomain = null;
   if (axisParam.data && Array.isArray(axisParam.data) && axisParam.data.length > 0) {
     const firstItem = axisParam.data[0];
@@ -163,7 +222,10 @@ export const getAxisDomain = (axisParam, series, axisType) => {
   }
 
   // Calculate domain from series data
-  const seriesDomain = axisType === 'x' ? getChartDomain(series) : getChartRange(series);
+  // In vertical layout: X is category (index), Y is value (value)
+  // In horizontal layout: Y is category (index), X is value (value)
+  const isCategoryAxis = layout !== 'horizontal' && axisType === 'x' || layout === 'horizontal' && axisType === 'y';
+  const seriesDomain = isCategoryAxis ? getChartDomain(series) : getChartRange(series);
 
   // If data sets the domain, use that instead of the series domain
   const preferredDataDomain = dataDomain !== null && dataDomain !== void 0 ? dataDomain : seriesDomain;
@@ -457,7 +519,8 @@ const generateEvenlyDistributedTicks = (scale, tickInterval, possibleTickValues,
  * });
  * // Returns tick positions centered in each selected band
  */
-export const getAxisTicksData = _ref4 => {
+export const getAxisTicksData = _ref5 => {
+  var _options$anchor;
   let {
     ticks,
     scaleFunction,
@@ -466,54 +529,38 @@ export const getAxisTicksData = _ref4 => {
     possibleTickValues,
     tickInterval,
     options
-  } = _ref4;
+  } = _ref5;
+  const anchor = (_options$anchor = options === null || options === void 0 ? void 0 : options.anchor) !== null && _options$anchor !== void 0 ? _options$anchor : 'middle';
+
   // Handle band scales
   if (isCategoricalScale(scaleFunction)) {
+    const bandScale = 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, _bandwidth2, _ref5;
-        // Band scales expect numeric indices, not category strings
-        const position = scaleFunction(index);
-        if (position === undefined) return null;
-        return {
-          tick: index,
-          position: position + ((_bandwidth = (_bandwidth2 = (_ref5 = scaleFunction).bandwidth) === null || _bandwidth2 === void 0 ? void 0 : _bandwidth2.call(_ref5)) !== null && _bandwidth !== void 0 ? _bandwidth : 0) / 2
-        };
-      }).filter(Boolean);
+      return ticks.filter(index => index >= 0 && index < categories.length).map(index => ({
+        tick: index,
+        position: getPointOnScale(index, bandScale, anchor)
+      }));
     }
 
     // If a tick function is provided, use it to filter
     if (typeof ticks === 'function') {
       return categories.map((category, index) => {
-        var _bandwidth3, _bandwidth4, _ref6;
         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 + ((_bandwidth3 = (_bandwidth4 = (_ref6 = scaleFunction).bandwidth) === null || _bandwidth4 === void 0 ? void 0 : _bandwidth4.call(_ref6)) !== null && _bandwidth3 !== void 0 ? _bandwidth3 : 0) / 2
+          position: getPointOnScale(index, bandScale, anchor)
         };
       }).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 _bandwidth5, _bandwidth6, _ref7;
-      // Band scales expect numeric indices, not category strings
-      const position = scaleFunction(index);
-      if (position === undefined) return null;
-      return {
-        tick: index,
-        position: position + ((_bandwidth5 = (_bandwidth6 = (_ref7 = scaleFunction).bandwidth) === null || _bandwidth6 === void 0 ? void 0 : _bandwidth6.call(_ref7)) !== null && _bandwidth5 !== void 0 ? _bandwidth5 : 0) / 2
-      };
-    }).filter(Boolean);
+    return categories.map((_, index) => ({
+      tick: index,
+      position: getPointOnScale(index, bandScale, anchor)
+    }));
   }
 
   // Handle numeric scales