@sproutsocial/seeds-react-data-viz 0.3.1 → 0.4.0

package/dist/index.js

@@ -51,18 +51,25 @@ __export(index_exports, {
   LineChart: () => LineChart,
   NetworkColorBox: () => NetworkColorBox,
   TIME_SERIES_CHART_HEIGHT: () => TIME_SERIES_CHART_HEIGHT,
+  VERTICAL_BAR_CHART_DEFAULT_SERIES_LIMIT: () => VERTICAL_BAR_CHART_DEFAULT_SERIES_LIMIT,
   areaChartOptions: () => areaChartOptions,
   areaChartStyles: () => areaChartStyles,
   baseChartOptions: () => baseChartOptions,
   baseChartStyles: () => baseChartStyles,
+  columnChartOptions: () => columnChartOptions,
   donutChartOptions: () => donutChartOptions,
   donutChartStyles: () => donutChartStyles,
   generateChartTooltipPortalId: () => generateChartTooltipPortalId,
   getDatavizColor: () => getDatavizColor,
   getDatavizColorWithAlpha: () => getDatavizColorWithAlpha,
   getDatavizOpacity: () => getDatavizOpacity,
+  getStorybookCategoricalData: () => getStorybookCategoricalData,
+  getStorybookSparseTimelineData: () => getStorybookSparseTimelineData,
+  isCategoricalHourData: () => isCategoricalHourData,
+  isHourlyTimeData: () => isHourlyTimeData,
   lineChartOptions: () => lineChartOptions,
   lineChartStyles: () => lineChartStyles,
+  timeSeriesChartOptions: () => timeSeriesChartOptions,
   timeSeriesChartStyles: () => timeSeriesChartStyles,
   transformDataToSeries: () => transformDataToSeries,
   transformTimeSeriesTooltipData: () => transformTimeSeriesTooltipData,
@@ -611,7 +618,12 @@ var ChartXAnnotationMarkerPortal = (0, import_react14.memo)(
 );
 
 // src/helpers/transformDataToSeries.ts
-var transformDataToSeries = ({ data }, type) => {
+var transformDataToSeries = ({
+  data
+}, type) => {
+  const hasCategoricalData = data.some(
+    (series) => series.points.some((point) => typeof point.x === "string")
+  );
   return data.map((dataItem, dataIndex) => {
     const points = dataItem.points || [];
     const dataPoints = points.map((point, pointsIndex) => {
@@ -628,12 +640,14 @@ var transformDataToSeries = ({ data }, type) => {
         enableMarker = true;
       }
       return {
-        x: point.x,
+        x: hasCategoricalData ? pointsIndex : point.x,
         y: point.y,
         marker: {
           enabled: enableMarker ? enableMarker : void 0,
           symbol: enableMarker ? "circle" : void 0
-        }
+        },
+        // For categorical data, store the original category name
+        ...hasCategoricalData && { name: point.x }
       };
     });
     return {
@@ -663,6 +677,42 @@ var transformTimeSeriesTooltipData = ({
   });
 };
 
+// src/helpers/yAxisLabelFormatter.ts
+var import_seeds_react_duration2 = require("@sproutsocial/seeds-react-duration");
+var import_seeds_react_numeral2 = require("@sproutsocial/seeds-react-numeral");
+var yAxisLabelFormatter = ({
+  numberLocale,
+  textLocale,
+  tickPositions,
+  value,
+  currency = "USD",
+  numberFormat = "decimal"
+}) => {
+  const numberValue = Number(value);
+  if (numberValue === 0) {
+    return (0, import_seeds_react_numeral2.formatNumeral)({
+      locale: numberLocale,
+      number: numberValue
+    });
+  }
+  if (numberFormat === "duration") {
+    return (0, import_seeds_react_duration2.formatDuration)({
+      display: "narrow",
+      locale: textLocale,
+      milliseconds: numberValue
+    });
+  }
+  const maxValue = tickPositions && tickPositions.length > 0 ? tickPositions[tickPositions.length - 1] : void 0;
+  const abbreviate = typeof maxValue === "number" && maxValue > 9999 ? 1e3 : true;
+  return (0, import_seeds_react_numeral2.formatNumeral)({
+    abbreviate,
+    currency,
+    format: numberFormat,
+    locale: numberLocale,
+    number: numberValue
+  });
+};
+
 // src/helpers/xAxisLabelFormatter.ts
 var xAxisLabelFormatter = ({
   textLocale,
@@ -672,6 +722,9 @@ var xAxisLabelFormatter = ({
   // optional
   timeFormat = "12"
 }) => {
+  if (typeof value === "string") {
+    return `<span>${value}</span>`;
+  }
   const tickIndex = tickPositions.indexOf(value);
   const isFirst = tickIndex === 0;
   const previousValue = tickPositions[tickIndex - 1];
@@ -717,39 +770,227 @@ var xAxisLabelFormatter = ({
   return `<span>${firstPart}</span>${secondPart ? `<span>${secondPart}</span>` : ""}`;
 };
 
-// src/helpers/yAxisLabelFormatter.ts
-var import_seeds_react_duration2 = require("@sproutsocial/seeds-react-duration");
-var import_seeds_react_numeral2 = require("@sproutsocial/seeds-react-numeral");
-var yAxisLabelFormatter = ({
-  numberLocale,
-  textLocale,
-  tickPositions,
-  value,
-  currency = "USD",
-  numberFormat = "decimal"
-}) => {
-  const numberValue = Number(value);
-  if (numberValue === 0) {
-    return (0, import_seeds_react_numeral2.formatNumeral)({
-      locale: numberLocale,
-      number: numberValue
-    });
-  }
-  if (numberFormat === "duration") {
-    return (0, import_seeds_react_duration2.formatDuration)({
-      display: "narrow",
-      locale: textLocale,
-      milliseconds: numberValue
-    });
+// src/helpers/isHourlyTimeData.ts
+function isHourlyTimeData(data) {
+  if (!data.length) return false;
+  const xVals = data.flatMap((series) => series.points.map((p) => p.x));
+  if (!xVals.length) return false;
+  if (xVals.some((x) => typeof x === "string")) return false;
+  const dates = xVals.map((x) => {
+    const d = new Date(x);
+    return `${d.getUTCFullYear()}-${d.getUTCMonth()}-${d.getUTCDate()}`;
+  });
+  const uniqueDates = new Set(dates);
+  if (uniqueDates.size !== 1) return false;
+  return xVals.every((x) => {
+    const d = new Date(x);
+    const hour = d.getUTCHours();
+    const minutes = d.getUTCMinutes();
+    const seconds = d.getUTCSeconds();
+    return hour >= 0 && hour <= 23 && minutes === 0 && seconds === 0;
+  });
+}
+
+// src/helpers/isCategoricalHourData.ts
+function isCategoricalHourData(data) {
+  if (!data.length) return false;
+  const xVals = data.flatMap((series) => series.points.map((p) => p.x));
+  if (!xVals.length) return false;
+  if (xVals.some((x) => typeof x !== "string")) return false;
+  const hour12Pattern = /^\d{1,2} (AM|PM)$/;
+  const hour24Pattern = /^([01]?\d|2[0-3]):([0-5]\d)$/;
+  const stringValues = xVals;
+  const allMatch12Hour = stringValues.every((x) => hour12Pattern.test(x));
+  const allMatch24Hour = stringValues.every((x) => hour24Pattern.test(x));
+  return allMatch12Hour || allMatch24Hour;
+}
+
+// src/helpers/getStorybookRandomColor.ts
+var getStorybookRandomColor = () => {
+  const letters = "0123456789ABCDEF";
+  let color = "#";
+  for (let i = 0; i < 6; i++) {
+    color += letters[Math.floor(Math.random() * 16)];
   }
-  const maxValue = tickPositions && tickPositions.length > 0 ? tickPositions[tickPositions.length - 1] : void 0;
-  const abbreviate = typeof maxValue === "number" && maxValue > 9999 ? 1e3 : true;
-  return (0, import_seeds_react_numeral2.formatNumeral)({
-    abbreviate,
-    currency,
-    format: numberFormat,
-    locale: numberLocale,
-    number: numberValue
+  return color;
+};
+
+// src/helpers/getStorybookCategoricalData.ts
+var getStorybookCategoricalData = ({
+  showNulls,
+  showNegativeValues,
+  numberOfSeries,
+  yAxisMax,
+  showCustomColors,
+  showDashedLines,
+  categoryType
+}) => {
+  const categoryOptions = {
+    hours: [
+      "12 AM",
+      "1 AM",
+      "2 AM",
+      "3 AM",
+      "4 AM",
+      "5 AM",
+      "6 AM",
+      "7 AM",
+      "8 AM",
+      "9 AM",
+      "10 AM",
+      "11 AM",
+      "12 PM",
+      "1 PM",
+      "2 PM",
+      "3 PM",
+      "4 PM",
+      "5 PM",
+      "6 PM",
+      "7 PM",
+      "8 PM",
+      "9 PM",
+      "10 PM",
+      "11 PM"
+    ],
+    hours24: [
+      "00:00",
+      "01:00",
+      "02:00",
+      "03:00",
+      "04:00",
+      "05:00",
+      "06:00",
+      "07:00",
+      "08:00",
+      "09:00",
+      "10:00",
+      "11:00",
+      "12:00",
+      "13:00",
+      "14:00",
+      "15:00",
+      "16:00",
+      "17:00",
+      "18:00",
+      "19:00",
+      "20:00",
+      "21:00",
+      "22:00",
+      "23:00"
+    ],
+    days: [
+      "Monday",
+      "Tuesday",
+      "Wednesday",
+      "Thursday",
+      "Friday",
+      "Saturday",
+      "Sunday"
+    ],
+    months: [
+      "January",
+      "February",
+      "March",
+      "April",
+      "May",
+      "June",
+      "July",
+      "August",
+      "September",
+      "October",
+      "November",
+      "December"
+    ],
+    custom: [
+      "Category A",
+      "Category B",
+      "Category C",
+      "Category D",
+      "Category E"
+    ]
+  };
+  const categories = categoryOptions[categoryType];
+  const numberOfPoints = categories.length;
+  return [...Array(numberOfSeries).keys()].map((seriesIndex) => {
+    let nullsArray = [];
+    if (showNulls) {
+      const nullsArrayLength = Math.floor(numberOfPoints / 5);
+      nullsArray = [...Array(nullsArrayLength)].map(
+        () => Math.floor(Math.random() * numberOfPoints)
+      );
+    }
+    return {
+      points: categories.map((category, pointIndex) => {
+        const showNull = nullsArray && nullsArray.length > 0 ? nullsArray.includes(pointIndex) : false;
+        const randomValue = Math.random();
+        const positiveOrNegativeYAxisMax = showNegativeValues ? randomValue < 0.5 ? -yAxisMax : yAxisMax : yAxisMax;
+        return {
+          x: category,
+          y: showNull ? null : Math.floor(randomValue * positiveOrNegativeYAxisMax)
+        };
+      }),
+      name: `Series ${seriesIndex + 1}`,
+      styles: {
+        color: showCustomColors ? getStorybookRandomColor() : void 0,
+        pattern: showDashedLines ? "dashed" : "solid"
+      }
+    };
+  });
+};
+
+// src/helpers/getStorybookSparseTimelineData.ts
+var getStorybookSparseTimelineData = ({
+  showNulls,
+  showNegativeValues,
+  numberOfSeries,
+  yAxisMax,
+  showCustomColors,
+  showDashedLines,
+  numberOfPoints = 5,
+  timeSpanHours = 24
+}) => {
+  const seriesNames = [
+    "Posts Published",
+    "Comments",
+    "Likes",
+    "Shares",
+    "Clicks",
+    "Views",
+    "Saves",
+    "Reposts",
+    "Mentions",
+    "Reactions"
+  ];
+  const baseDate = /* @__PURE__ */ new Date("2024-01-01T00:00:00Z");
+  const timeSpanMs = timeSpanHours * 60 * 60 * 1e3;
+  return [...Array(numberOfSeries).keys()].map((seriesIndex) => {
+    let nullsArray = [];
+    if (showNulls) {
+      const nullsArrayLength = Math.floor(numberOfPoints / 5);
+      nullsArray = [...Array(nullsArrayLength)].map(
+        () => Math.floor(Math.random() * numberOfPoints)
+      );
+    }
+    const timestamps = [...Array(numberOfPoints)].map(() => {
+      const randomOffset = Math.random() * timeSpanMs;
+      return baseDate.getTime() + randomOffset;
+    }).sort((a, b) => a - b);
+    return {
+      points: timestamps.map((timestamp, pointIndex) => {
+        const showNull = nullsArray && nullsArray.length > 0 ? nullsArray.includes(pointIndex) : false;
+        const randomValue = Math.random();
+        const positiveOrNegativeYAxisMax = showNegativeValues ? randomValue < 0.5 ? -yAxisMax : yAxisMax : yAxisMax;
+        return {
+          x: timestamp,
+          y: showNull ? null : Math.floor(randomValue * positiveOrNegativeYAxisMax)
+        };
+      }),
+      name: seriesNames[seriesIndex] || `Series ${seriesIndex + 1}`,
+      styles: {
+        color: showCustomColors ? getStorybookRandomColor() : void 0,
+        pattern: showDashedLines ? "dashed" : "solid"
+      }
+    };
   });
 };
 
@@ -839,7 +1080,20 @@ var timeSeriesChartOptions = import_lodash.default.merge({}, baseChartOptions, {
     softMin: 0,
     title: {
       text: void 0
-    }
+    },
+    plotLines: [
+      /* Adds a custom plotLine at y=0 to represent the chart baseline.
+        This approach allows full control over the line's appearance (e.g., color, z-index),
+        unlike relying on the default xAxis line, which always renders at the bottom of the chart
+        even when y=0 appears elsewhere (e.g., with negative values).
+      */
+      {
+        className: "y-axis-zero-line",
+        value: 0,
+        zIndex: 3
+        // ensures the line appears over the default y=0 line, which we can't seleect as specifically
+      }
+    ]
   }
 });
 var lineChartOptions = import_lodash.default.merge({}, timeSeriesChartOptions, {
@@ -853,6 +1107,30 @@ var areaChartOptions = import_lodash.default.merge({}, timeSeriesChartOptions, {
     }
   }
 });
+var columnChartOptions = import_lodash.default.merge({}, timeSeriesChartOptions, {
+  plotOptions: {
+    column: {
+      stacking: "normal",
+      pointPadding: 0.25,
+      groupPadding: 0.25,
+      borderRadius: 4
+    }
+  },
+  xAxis: {
+    crosshair: false
+  },
+  yAxis: {
+    plotLines: [
+      {
+        // For stacked column charts with visible borders (e.g., white for contrast),
+        // we raise the zIndex of the y=0 plotLine to ensure it remains visible
+        // and isn't visually covered by overlapping column borders.
+        zIndex: 5
+      }
+    ]
+  }
+});
+var VERTICAL_BAR_CHART_DEFAULT_SERIES_LIMIT = 10;
 var DONUT_CHART_HALO_SIZE = 10;
 var DONUT_CHART_HEIGHT = 250 + DONUT_CHART_HALO_SIZE * 2;
 var DONUT_CHART_WIDTH = DONUT_CHART_HEIGHT;
@@ -887,7 +1165,8 @@ var useTimeSeriesChartOptions = ({
   numberFormat = "decimal",
   yAxisLabelFormatter: yAxisLabelFormatter2,
   onClick,
-  timeFormat = "12"
+  timeFormat = "12",
+  xAxisLabelFormatter: xAxisLabelFormatter2
 }) => {
   const [chart, setChart] = (0, import_react15.useState)(null);
   const callback = (0, import_react15.useCallback)((chartInstance) => {
@@ -921,7 +1200,24 @@ var useTimeSeriesChartOptions = ({
     }
   };
   const chartMarginTop = xAnnotations ? 24 : null;
-  const baseChartOptions2 = seriesType === "areaspline" ? areaChartOptions : lineChartOptions;
+  const getBaseChartOptions = (type) => {
+    switch (type) {
+      case "areaspline":
+        return areaChartOptions;
+      case "spline":
+        return lineChartOptions;
+      case "column":
+        return columnChartOptions;
+      default:
+        return lineChartOptions;
+    }
+  };
+  const baseChartOptions2 = getBaseChartOptions(seriesType);
+  const hasCategoricalData = data.some(
+    (series) => series.points.some((point) => typeof point.x === "string")
+  );
+  const categories = hasCategoricalData ? data[0]?.points.map((point) => point.x) || [] : [];
+  const hasSparseTimelineData = !hasCategoricalData && seriesType === "column";
   const options = (0, import_react15.useMemo)(() => {
     return (0, import_lodash2.merge)({}, baseChartOptions2, {
       accessibility: {
@@ -962,6 +1258,61 @@ var useTimeSeriesChartOptions = ({
               return onClick({ x: event.point.x });
             } : void 0
           }
+        },
+        column: {
+          // For sparse timeline data, set explicit point width to make columns wider
+          ...hasSparseTimelineData && {
+            pointWidth: 20
+            // Fixed width in pixels for sparse timeline data
+          },
+          point: {
+            events: {
+              /*
+                Custom hover behavior for multi-series column charts.
+                
+                In multi-series column charts, multiple columns
+                can share the same x-axis position (stacked or grouped). When hovering
+                over one column, we want ALL columns at that x-position to highlight
+                together for better visual feedback. Simple CSS :hover only affects the
+                individual element being hovered, not related columns at the same position.
+                
+                This custom behavior ensures that when you hover over any column at a
+                specific x-position, all columns at that same position get the "column-hover"
+                class, creating a unified highlight effect across all series.
+              */
+              mouseOver: function() {
+                const x = this.x;
+                if (this.series && this.series.chart && this.series.chart.series) {
+                  this.series.chart.series.forEach((series) => {
+                    if (series.type === "column") {
+                      series.data.forEach((point) => {
+                        if (point.x === x) {
+                          const el = point.graphic && point.graphic.element;
+                          if (el) {
+                            el.classList.add("column-hover");
+                          }
+                        }
+                      });
+                    }
+                  });
+                }
+              },
+              mouseOut: function() {
+                if (this.series && this.series.chart && this.series.chart.series) {
+                  this.series.chart.series.forEach((series) => {
+                    if (series.type === "column") {
+                      series.data.forEach((point) => {
+                        const el = point.graphic && point.graphic.element;
+                        if (el) {
+                          el.classList.remove("column-hover");
+                        }
+                      });
+                    }
+                  });
+                }
+              }
+            }
+          }
         }
       },
       series: transformDataToSeries({ data }, seriesType),
@@ -971,14 +1322,37 @@ var useTimeSeriesChartOptions = ({
       xAxis: {
         labels: {
           formatter: function() {
-            return xAxisLabelFormatter({
-              textLocale,
-              tickPositions: this.axis.tickPositions || [],
-              timeFormat,
-              unitName: this.tickPositionInfo.unitName,
-              value: this.value
-            });
+            const tickPositions = (this.axis.tickPositions || []).map(
+              Number
+            );
+            const value = this.value;
+            const unitName = this.tickPositionInfo?.unitName;
+            if (typeof xAxisLabelFormatter2 === "function") {
+              return xAxisLabelFormatter2({
+                textLocale,
+                tickPositions,
+                timeFormat,
+                unitName,
+                value
+              });
+            }
+            if (typeof xAxisLabelFormatterDefault === "function") {
+              return xAxisLabelFormatterDefault({
+                textLocale,
+                tickPositions,
+                timeFormat,
+                unitName,
+                value
+              });
+            }
+            return "";
           }
+        },
+        // Override xAxis type for categorical data
+        ...hasCategoricalData && {
+          type: "category",
+          categories,
+          crosshair: false
         }
       },
       yAxis: {
@@ -1001,8 +1375,11 @@ var useTimeSeriesChartOptions = ({
     });
   }, [
     baseChartOptions2,
+    categories,
     currency,
     data,
+    hasCategoricalData,
+    hasSparseTimelineData,
     numberFormat,
     numberLocale,
     onClick,
@@ -1010,10 +1387,12 @@ var useTimeSeriesChartOptions = ({
     textLocale,
     timeFormat,
     xAnnotations,
-    yAxisLabelFormatter2
+    yAxisLabelFormatter2,
+    xAxisLabelFormatter2
   ]);
   return { options, chart, callback };
 };
+var xAxisLabelFormatterDefault = xAxisLabelFormatter;
 
 // src/styles/chartStyles.ts
 var import_styled_components7 = require("styled-components");
@@ -1032,6 +1411,8 @@ var GlobalChartStyleOverrides = import_styled_components7.createGlobalStyle`
   }
 `;
 var baseChartStyles = import_styled_components7.css`
+  --highcharts-background-color: ${({ theme: theme14 }) => theme14.colors.container.background.base};
+
   // set color variables and map to each series
   ${({ $colors }) => $colors.map((color, index) => {
   const chartColor = color || import_seeds_react_theme7.theme.colors.DATAVIZ_COLORS_LIST[index];
@@ -1075,9 +1456,11 @@ var timeSeriesChartStyles = import_styled_components7.css`
   .highcharts-grid-line {
     stroke: ${({ theme: theme14 }) => theme14.colors.container.border.base};
   }
+
   .highcharts-axis-line {
     stroke: ${({ theme: theme14 }) => theme14.colors.container.border.base};
   }
+
   .highcharts-tick {
     stroke: none;
   }
@@ -1118,6 +1501,10 @@ var timeSeriesChartStyles = import_styled_components7.css`
  				fill: transparent;
  				cursor: pointer;
  		}`}
+
+  path.highcharts-plot-line.y-axis-zero-line {
+    stroke: ${({ theme: theme14 }) => theme14.colors.container.border.decorative.neutral};
+  }
 `;
 var lineChartStyles = import_styled_components7.css`
   ${timeSeriesChartStyles}
@@ -1803,18 +2190,25 @@ var LineChartWithData = (0, import_react23.memo)(function LineChartWithData2({
   LineChart,
   NetworkColorBox,
   TIME_SERIES_CHART_HEIGHT,
+  VERTICAL_BAR_CHART_DEFAULT_SERIES_LIMIT,
   areaChartOptions,
   areaChartStyles,
   baseChartOptions,
   baseChartStyles,
+  columnChartOptions,
   donutChartOptions,
   donutChartStyles,
   generateChartTooltipPortalId,
   getDatavizColor,
   getDatavizColorWithAlpha,
   getDatavizOpacity,
+  getStorybookCategoricalData,
+  getStorybookSparseTimelineData,
+  isCategoricalHourData,
+  isHourlyTimeData,
   lineChartOptions,
   lineChartStyles,
+  timeSeriesChartOptions,
   timeSeriesChartStyles,
   transformDataToSeries,
   transformTimeSeriesTooltipData,