@coinbase/cds-web-visualization 3.4.0-beta.2 → 3.4.0-beta.20

package/esm/chart/utils/bar.js

@@ -1,3 +1,51 @@
+const _excluded = ["staggerDelay"];
+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); }
+function _objectWithoutProperties(e, t) { if (null == e) return {}; var o, r, i = _objectWithoutPropertiesLoose(e, t); if (Object.getOwnPropertySymbols) { var n = Object.getOwnPropertySymbols(e); for (r = 0; r < n.length; r++) o = n[r], -1 === t.indexOf(o) && {}.propertyIsEnumerable.call(e, o) && (i[o] = e[o]); } return 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 { defaultTransition } from './transition';
+
+/**
+ * A bar-specific transition that extends Transition with stagger support.
+ * When `staggerDelay` is provided, bars will animate with increasing delays
+ * based on their horizontal position (leftmost starts first, rightmost last).
+ *
+ * @example
+ * // Bars stagger in from left to right over 0.25s, each animating for 0.75s
+ * { type: 'tween', duration: 0.75, staggerDelay: 0.25 }
+ */
+
+/**
+ * Strips `staggerDelay` from a transition and computes a positional delay.
+ *
+ * @param transition - The transition config (may include staggerDelay)
+ * @param normalizedX - The bar's normalized x position (0 = left edge, 1 = right edge)
+ * @returns A standard Transition with computed delay
+ */
+export const withStaggerDelayTransition = (transition, normalizedX) => {
+  var _baseTransition$delay;
+  const {
+      staggerDelay
+    } = transition,
+    baseTransition = _objectWithoutProperties(transition, _excluded);
+  if (!staggerDelay) return transition;
+  return _objectSpread(_objectSpread({}, baseTransition), {}, {
+    delay: ((_baseTransition$delay = baseTransition === null || baseTransition === void 0 ? void 0 : baseTransition.delay) !== null && _baseTransition$delay !== void 0 ? _baseTransition$delay : 0) + normalizedX * staggerDelay
+  });
+};
+
+/**
+ * Default bar enter transition. Uses the default spring with a stagger delay
+ * so bars spring into place from left to right.
+ * `{ type: 'spring', stiffness: 900, damping: 120, mass: 4, staggerDelay: 0.25 }`
+ */
+export const defaultBarEnterTransition = _objectSpread(_objectSpread({}, defaultTransition), {}, {
+  staggerDelay: 0.25
+});
+
 /**
  * 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

package/esm/chart/utils/chart.js

@@ -1,5 +1,18 @@
 import { stack as d3Stack, stackOffsetDiverging, stackOrderNone } from 'd3-shape';
 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
@@ -19,13 +32,13 @@ export const getChartDomain = (series, min, max) => {
     return domain;
   }
   if (series.length > 0) {
-    const maxDataLength = Math.max(...series.map(s => {
+    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 (maxDataLength > 0) {
+    if (dataLength > 0) {
       if (domain.min === undefined) domain.min = 0;
-      if (domain.max === undefined) domain.max = maxDataLength - 1;
+      if (domain.max === undefined) domain.max = dataLength - 1;
     }
   }
   return domain;
@@ -111,6 +124,32 @@ export const getStackedSeriesData = series => {
   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$at;
+      if (d === null) return null;
+      if (Array.isArray(d)) return (_d$at = d.at(-1)) !== null && _d$at !== void 0 ? _d$at : 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.

package/esm/chart/utils/gradient.js

@@ -0,0 +1,257 @@
+import { isCategoricalScale } from './scale';
+
+/**
+ * Defines a color transition point in the gradient
+ */
+
+/**
+ * Defines a gradient.
+ */
+
+/**
+ * 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 (required)
+ * @param xScale - X-axis scale (required)
+ * @param yScale - Y-axis scale (required)
+ * @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 = (gradient, xScale, yScale) => {
+  if (!gradient) return;
+
+  // Get the scale based on axis
+  const scale = gradient.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
+ * @returns A gradient definition with y-axis stops in ascending order
+ */
+export const createGradient = (axisBounds, baselineValue, fill, peakOpacity, baselineOpacity) => {
+  const {
+    min,
+    max
+  } = axisBounds;
+  const lowerBound = Math.min(min, max);
+  const upperBound = Math.max(min, max);
+  if (lowerBound < baselineValue && baselineValue < upperBound) {
+    return {
+      axis: 'y',
+      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: 'y',
+    stops: [{
+      offset: peakValue,
+      color: fill,
+      opacity: peakOpacity
+    }, {
+      offset: baselineValue,
+      color: fill,
+      opacity: baselineOpacity
+    }].sort((a, b) => a.offset - b.offset)
+  };
+};

package/esm/chart/utils/index.js

@@ -3,7 +3,11 @@ 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