@coinbase/cds-mobile-visualization 3.4.0-beta.1 → 3.4.0-beta.11

package/esm/chart/text/{SmartChartTextGroup.js → ChartTextGroup.js}

@@ -2,7 +2,7 @@ const _excluded = ["onDimensionsChange"];
 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 { memo, useEffect, useMemo, useState } from 'react';
-import { G } from 'react-native-svg';
+import { Group } from '@shopify/react-native-skia';
 import { ChartText } from './ChartText';
 
 /**
@@ -32,12 +32,13 @@ const EPSILON_PX = 0.5;
  *
  * The component focuses solely on overlap prevention logic for better separation of concerns.
  */
-export const SmartChartTextGroup = /*#__PURE__*/memo(_ref => {
+export const ChartTextGroup = /*#__PURE__*/memo(_ref => {
   let {
     labels,
     minGap = 8,
     prioritizeEndLabels = true,
-    chartTextProps
+    chartTextProps,
+    LabelComponent = ChartText
   } = _ref;
   const [boundingBoxes, setBoundingBoxes] = useState(new Map());
   const _ref2 = chartTextProps != null ? chartTextProps : {},
@@ -193,11 +194,11 @@ export const SmartChartTextGroup = /*#__PURE__*/memo(_ref => {
     }
     return new Set(greedy);
   }, [isReady, boundingBoxes, minGap, prioritizeEndLabels, labelsWithKeys]);
-  return /*#__PURE__*/_jsx(G, {
+  return /*#__PURE__*/_jsx(Group, {
     children: labelsWithKeys.map(labelData => {
       const hasMeasurement = boundingBoxes.has(labelData.key);
       const isVisible = hasMeasurement && isReady && (visibleKeySet == null ? void 0 : visibleKeySet.has(labelData.key));
-      return /*#__PURE__*/_jsx(ChartText, _extends({
+      return /*#__PURE__*/_jsx(LabelComponent, _extends({
         opacity: isVisible ? 1 : 0,
         x: labelData.x,
         y: labelData.y

package/esm/chart/text/index.js

@@ -1,4 +1,4 @@
 // codegen:start {preset: barrel, include: ./*.tsx, exclude: ./__stories__/*.tsx}
 export * from './ChartText';
-export * from './SmartChartTextGroup';
+export * from './ChartTextGroup';
 // codegen:end

package/esm/chart/utils/axis.js

@@ -3,10 +3,41 @@ function _extends() { return _extends = Object.assign ? Object.assign.bind() : f
 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 (grid lines, tick marks, labels).
+ *
+ * - `'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
  */
@@ -457,6 +488,7 @@ const generateEvenlyDistributedTicks = (scale, tickInterval, possibleTickValues,
  * // Returns tick positions centered in each selected band
  */
 export const getAxisTicksData = _ref4 => {
+  var _options$anchor;
   let {
     ticks,
     scaleFunction,
@@ -466,53 +498,37 @@ export const getAxisTicksData = _ref4 => {
     tickInterval,
     options
   } = _ref4;
+  const anchor = (_options$anchor = options == null ? void 0 : options.anchor) != null ? _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;
-        // 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);
+      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 _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
+          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 _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);
+    return categories.map((_, index) => ({
+      tick: index,
+      position: getPointOnScale(index, bandScale, anchor)
+    }));
   }
 
   // Handle numeric scales

package/esm/chart/utils/chart.js

@@ -1,3 +1,4 @@
+import { isSharedValue } from 'react-native-reanimated';
 import { stack as d3Stack, stackOffsetDiverging, stackOrderNone } from 'd3-shape';
 export const defaultStackId = 'DEFAULT_STACK_ID';
 /**
@@ -19,13 +20,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 ? 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 +112,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 : 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.
@@ -226,4 +253,18 @@ export const getChartInset = (inset, defaults) => {
     bottom: (_inset$bottom = inset == null ? void 0 : inset.bottom) != null ? _inset$bottom : baseDefaults.bottom,
     right: (_inset$right = inset == null ? void 0 : inset.right) != null ? _inset$right : baseDefaults.right
   };
+};
+
+/**
+ * Unwraps an optionally animated value to get the raw value.
+ * @param value - The value to unwrap.
+ * @returns The raw value.
+ */
+export const unwrapAnimatedValue = value => {
+  'worklet';
+
+  if (isSharedValue(value)) {
+    return value.value;
+  }
+  return value;
 };

package/esm/chart/utils/gradient.js

@@ -0,0 +1,305 @@
+import { Skia } from '@shopify/react-native-skia';
+import { applySerializableScale, isCategoricalScale, isSerializableScale } 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.
+ */
+export 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 : 1
+    };
+  }).sort((a, b) => a.offset - b.offset);
+  return normalizedStops;
+};
+
+/**
+ * Interpolates between two colors using linear interpolation.
+ * Returns an rgba string.
+ */
+const interpolateColor = (color1, color2, t) => {
+  'worklet';
+
+  const c1 = Skia.Color(color1);
+  const c2 = Skia.Color(color2);
+  const r = Math.round((c1[0] + (c2[0] - c1[0]) * t) * 255);
+  const g = Math.round((c1[1] + (c2[1] - c1[1]) * t) * 255);
+  const b = Math.round((c1[2] + (c2[2] - c1[2]) * t) * 255);
+  const a = c1[3] + (c2[3] - c1[3]) * t;
+  return "rgba(" + r + ", " + g + ", " + b + ", " + a + ")";
+};
+
+/**
+ * Adds an opacity to a color
+ * Returns an rgba string.
+ */
+export const getColorWithOpacity = (color1, opacity) => {
+  const c = Skia.Color(color1);
+  return "rgba(" + c[0] * 255 + ", " + c[1] * 255 + ", " + c[2] * 255 + ", " + opacity + ")";
+};
+
+/**
+ * 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);
+};
+
+/**
+ * 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) => {
+  'worklet';
+
+  if (stops.length === 0) return;
+
+  // Determine range based on scale type
+  let rangeMin;
+  let rangeMax;
+  if (isSerializableScale(scale)) {
+    // SerializableScale has range as [number, number]
+    [rangeMin, rangeMax] = scale.range;
+  } else {
+    // ChartScaleFunction has range() method
+    const scaleRange = scale.range();
+    [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
+  let dataPosition;
+  if (isSerializableScale(scale)) {
+    dataPosition = applySerializableScale(dataValue, scale);
+  } else {
+    const result = scale(dataValue);
+    if (result === undefined) return stops[0].color;
+    dataPosition = result;
+  }
+
+  // Normalize to 0-1 based on range
+  const normalizedValue = Math.max(0, Math.min(1, Math.abs(dataPosition - rangeMin) / rangeSpan));
+
+  // Map stop offsets through scale and normalize to 0-1
+  const positions = stops.map(stop => {
+    let stopPosition;
+    if (isSerializableScale(scale)) {
+      stopPosition = applySerializableScale(stop.offset, scale);
+    } else {
+      const result = scale(stop.offset);
+      if (result === undefined) return 0;
+      stopPosition = result;
+    }
+    return Math.max(0, Math.min(1, Math.abs(stopPosition - rangeMin) / rangeSpan));
+  });
+
+  // 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 dataValue matches any stop offset exactly (for hard transitions)
+  for (let i = 0; i < stops.length; i++) {
+    if (dataValue === stops[i].offset) {
+      // 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 && stops[lastIndexAtOffset + 1].offset === stops[i].offset) {
+        lastIndexAtOffset++;
+      }
+      return stops[lastIndexAtOffset].color;
+    }
+  }
+
+  // Find the segment to interpolate between
+  for (let i = 0; i < positions.length - 1; i++) {
+    if (normalizedValue >= positions[i] && normalizedValue <= positions[i + 1]) {
+      const segmentStart = positions[i];
+      const segmentEnd = positions[i + 1];
+      if (segmentEnd === segmentStart) {
+        return stops[i].color;
+      }
+      const t = (normalizedValue - segmentStart) / (segmentEnd - segmentStart);
+      return interpolateColor(stops[i].color, stops[i + 1].color, t);
+    }
+  }
+  return stops[0].color;
+};
+
+/**
+ * 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, baseline) {
+  if (baseline === void 0) {
+    baseline = 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,10 @@ export * from './axis';
 export * from './bar';
 export * from './chart';
 export * from './context';
+export * from './gradient';
 export * from './path';
 export * from './point';
 export * from './scale';
+export * from './scrubber';
+export * from './transition';
 // codegen:end

package/esm/chart/utils/path.js

@@ -49,10 +49,11 @@ export const getLinePath = _ref => {
   var _pathGenerator;
   let {
     data,
-    curve = 'linear',
+    curve = 'bump',
     xScale,
     yScale,
-    xData
+    xData,
+    connectNulls = false
   } = _ref;
   if (data.length === 0) {
     return '';
@@ -64,9 +65,12 @@ export const getLinePath = _ref => {
     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 : '';
+  // When connectNulls is true, filter out null values before rendering
+  // When false, use defined() to create gaps in the line
+  const filteredPoints = connectNulls ? dataPoints.filter(d => d !== null) : dataPoints;
+  const pathGenerator = d3Line().x(d => d.x).y(d => d.y).curve(curveFunction).defined(d => connectNulls || d !== null);
+  return (_pathGenerator = pathGenerator(filteredPoints)) != null ? _pathGenerator : '';
 };
 
 /**
@@ -94,10 +98,11 @@ export const getLinePath = _ref => {
 export const getAreaPath = _ref2 => {
   let {
     data,
-    curve = 'linear',
+    curve = 'bump',
     xScale,
     yScale,
-    xData
+    xData,
+    connectNulls = false
   } = _ref2;
   if (data.length === 0) {
     return '';
@@ -158,6 +163,10 @@ export const getAreaPath = _ref2 => {
       isValid: true
     };
   });
+
+  // When connectNulls is true, filter out invalid points before rendering
+  // When false, use defined() to create gaps in the area
+  const filteredPoints = connectNulls ? dataPoints.filter(d => d.isValid) : dataPoints;
   const areaGenerator = d3Area().x(d => d.x).y0(d => {
     var _d$low;
     return (_d$low = d.low) != null ? _d$low : 0;
@@ -166,12 +175,26 @@ export const getAreaPath = _ref2 => {
     var _d$high;
     return (_d$high = d.high) != null ? _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
+  .curve(curveFunction).defined(d => connectNulls || d.isValid && d.low != null && d.high != null); // Only draw where both values exist
 
-  const result = areaGenerator(dataPoints);
+  const result = areaGenerator(filteredPoints);
   return result != null ? result : '';
 };
 
+/**
+ * Converts line coordinates to an SVG path string.
+ * Useful for rendering axis lines and tick marks.
+ *
+ * @example
+ * ```typescript
+ * const path = lineToPath(0, 0, 100, 100);
+ * // Returns: "M 0 0 L 100 100"
+ * ```
+ */
+export const lineToPath = (x1, y1, x2, y2) => {
+  return "M " + x1 + " " + y1 + " L " + x2 + " " + y2;
+};
+
 /**
  * Creates an SVG path string for a rectangle with selective corner rounding.
  * Useful for creating bars in charts with optional rounded corners.
@@ -203,4 +226,49 @@ export const getBarPath = (x, y, width, height, radius, roundTop, roundBottom) =
   path += " A " + topR + " " + topR + " 0 0 1 " + (x + topR) + " " + y;
   path += ' Z';
   return path;
+};
+
+/**
+ * Generates an SVG path string with circles arranged in a dotted pattern within a bounding area.
+ * Creates circles at regular intervals based on the pattern size and dot size parameters.
+ *
+ * @param bounds - The bounding rectangle to fill with dots
+ * @param patternSize - Size of the pattern unit (spacing between dots)
+ * @param dotSize - Radius of each dot
+ * @returns SVG path string containing all the circles
+ *
+ * @example
+ * ```typescript
+ * const dotsPath = getDottedAreaPath(
+ *   { x: 0, y: 0, width: 100, height: 50 },
+ *   8, // 8px spacing
+ *   2  // 2px radius dots
+ * );
+ * ```
+ */
+export const getDottedAreaPath = (bounds, patternSize, dotSize) => {
+  if (bounds.width <= 0 || bounds.height <= 0 || patternSize <= 0 || dotSize <= 0) {
+    return '';
+  }
+  let path = '';
+
+  // Calculate the number of dots that fit in each dimension
+  const dotsX = Math.ceil(bounds.width / patternSize);
+  const dotsY = Math.ceil(bounds.height / patternSize);
+
+  // Generate circles in a grid pattern
+  for (let row = 0; row < dotsY; row++) {
+    for (let col = 0; col < dotsX; col++) {
+      const centerX = bounds.x + col * patternSize + patternSize / 2;
+      const centerY = bounds.y + row * patternSize + patternSize / 2;
+
+      // Only draw dots that are within the bounds
+      if (centerX >= bounds.x && centerX <= bounds.x + bounds.width && centerY >= bounds.y && centerY <= bounds.y + bounds.height) {
+        // Create circle using SVG arc commands
+        // M cx,cy-r a r,r 0 1,0 0,2r a r,r 0 1,0 0,-2r
+        path += "M " + centerX + "," + (centerY - dotSize) + " a " + dotSize + "," + dotSize + " 0 1,0 0," + dotSize * 2 + " a " + dotSize + "," + dotSize + " 0 1,0 0," + -dotSize * 2 + " ";
+      }
+    }
+  }
+  return path.trim();
 };