feat(chart): add y-axis minimum interval

.changeset/silly-integers-relax.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/kumo": minor
+---
+
+Add an optional `yAxisMinInterval` prop to `TimeseriesChart` for discrete data.

packages/kumo-docs-astro/src/components/demos/Chart/ChartDemo.tsx

@@ -111,6 +111,40 @@ export function BasicLineChartDemo() {
   );
 }
 
+/**
+ * Discrete request-count chart with whole-number y-axis ticks.
+ */
+export function IntegerYAxisChartDemo() {
+  const isDarkMode = useIsDarkMode();
+
+  const data = useMemo(() => {
+    const end = Date.now();
+    const values = [0, 1, 3, 2, 5, 4, 7, 3, 6, 2, 4, 1];
+
+    return [
+      {
+        name: "Requests",
+        data: values.map((value, index): [number, number] => [
+          end - (values.length - index - 1) * 60_000,
+          value,
+        ]),
+        color: ChartPalette.semantic("Neutral", isDarkMode),
+      },
+    ];
+  }, [isDarkMode]);
+
+  return (
+    <TimeseriesChart
+      echarts={echarts}
+      isDarkMode={isDarkMode}
+      data={data}
+      xAxisName="Time (UTC)"
+      yAxisName="Requests"
+      yAxisMinInterval={1}
+    />
+  );
+}
+
 export function ReferenceMarkersChartDemo() {
   const isDarkMode = useIsDarkMode();
 

packages/kumo-docs-astro/src/pages/charts/timeseries.mdx

@@ -9,6 +9,7 @@ import ComponentSection from "~/components/docs/ComponentSection.astro";
 import ComponentExample from "~/components/docs/ComponentExample.astro";
 import {
   BasicLineChartDemo,
+  IntegerYAxisChartDemo,
   BarChartDemo,
   ReferenceMarkersChartDemo,
   ThresholdsChartDemo,
@@ -43,6 +44,21 @@ import {
 
 <ComponentSection>
 
+## Discrete Count Data
+
+<p>
+  Set <code>yAxisMinInterval={1}</code> for discrete values such as request
+  counts. This prevents fractional y-axis tick marks while leaving the default
+  axis behavior unchanged for rates and other continuous values.
+</p>
+
+  <ComponentExample demo="IntegerYAxisChartDemo">
+    <IntegerYAxisChartDemo client:visible />
+  </ComponentExample>
+</ComponentSection>
+
+<ComponentSection>
+
 ## Reference Markers
 
 <p>

packages/kumo/src/components/chart/TimeseriesChart.test.tsx

@@ -24,6 +24,49 @@ const createMockEcharts = (mockChart = createMockChart()) => ({
 });
 
 describe("TimeseriesChart", () => {
+  it("leaves the y-axis interval unconstrained by default", async () => {
+    const mockChart = createMockChart();
+
+    render(
+      <TimeseriesChart
+        echarts={createMockEcharts(mockChart) as any}
+        data={[]}
+      />,
+    );
+
+    await waitFor(() =>
+      expect(mockChart.setOption).toHaveBeenCalledWith(
+        expect.objectContaining({
+          yAxis: expect.not.objectContaining({
+            minInterval: expect.anything(),
+          }),
+        }),
+        expect.anything(),
+      ),
+    );
+  });
+
+  it("passes yAxisMinInterval to ECharts", async () => {
+    const mockChart = createMockChart();
+
+    render(
+      <TimeseriesChart
+        echarts={createMockEcharts(mockChart) as any}
+        data={[]}
+        yAxisMinInterval={1}
+      />,
+    );
+
+    await waitFor(() =>
+      expect(mockChart.setOption).toHaveBeenCalledWith(
+        expect.objectContaining({
+          yAxis: expect.objectContaining({ minInterval: 1 }),
+        }),
+        expect.anything(),
+      ),
+    );
+  });
+
   it("does not reserve footer space for an empty string", () => {
     const { container } = render(
       <TooltipContent

packages/kumo/src/components/chart/TimeseriesChart.tsx

@@ -86,6 +86,11 @@ export interface TimeseriesChartProps {
   yAxisName?: string;
   /** Number of ticks to display on the y-axis */
   yAxisTickCount?: number;
+  /**
+   * Minimum interval between y-axis ticks. Set to `1` for discrete count data
+   * so ECharts does not render fractional tick marks.
+   */
+  yAxisMinInterval?: number;
   /**
    * Custom formatter for tooltip values.
    * Receives the raw y-value and returns a display string.
@@ -240,6 +245,7 @@ export const TimeseriesChart = forwardRef<
     yAxisTickLabelFormat,
     yAxisName,
     yAxisTickCount,
+    yAxisMinInterval,
     tooltipValueFormat,
     tooltipFooter,
     onTimeRangeChange,
@@ -532,6 +538,9 @@ export const TimeseriesChart = forwardRef<
           },
         },
         splitNumber: yAxisTickCount,
+        ...(yAxisMinInterval !== undefined && {
+          minInterval: yAxisMinInterval,
+        }),
         ...(thresholdExtent && {
           min: (value: { min: number }) =>
             Math.min(value.min, thresholdExtent.min),
@@ -555,6 +564,7 @@ export const TimeseriesChart = forwardRef<
     yAxisTickFormat,
     yAxisName,
     yAxisTickCount,
+    yAxisMinInterval,
     incompleteBefore,
     incompleteAfter,
     type,