feat(sankey): add left and right props for layout padding control (#516)

Author: lkipke

.changeset/sankey-left-right-props.md

@@ -0,0 +1,5 @@
+---
+"@cloudflare/kumo": patch
+---
+
+Add `left` and `right` props to SankeyChart for controlling series layout padding

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

@@ -286,6 +286,22 @@ export function SankeyChartRichTooltipDemo() {
   );
 }
 
+/** Demo showing full-width layout using left={0} and right={0} to eliminate default padding */
+export function SankeyChartFullWidthDemo() {
+  const isDarkMode = useIsDarkMode();
+  return (
+    <SankeyChart
+      echarts={echarts}
+      nodes={basicNodes}
+      links={basicLinks}
+      height={350}
+      left={0}
+      right={0}
+      isDarkMode={isDarkMode}
+    />
+  );
+}
+
 export function SankeyChartInteractiveDemo() {
   const isDarkMode = useIsDarkMode();
   const handleNodeClick = (node: { name: string }) => {

packages/kumo-docs-astro/src/pages/charts/sankey.astro

@@ -8,6 +8,7 @@ import PropsTable from "../../components/docs/PropsTable.astro";
 import {
   SankeyChartBasicDemo,
   SankeyChartMultiLevelDemo,
+  SankeyChartFullWidthDemo,
   SankeyChartTooltipDemo,
   SankeyChartRichTooltipDemo,
   SankeyChartInteractiveDemo,
@@ -103,6 +104,22 @@ export default function Example() {
         </ComponentExample>
       </div>
 
+      <div>
+        <Heading level={3}>Full-Width Layout</Heading>
+        <p class="mb-4 text-kumo-subtle">
+          Use <code class="text-kumo-default">left</code> and <code class="text-kumo-default">right</code> to control horizontal padding of the Sankey layout within its container. Set both to <code class="text-kumo-default">0</code> to eliminate the default 5% padding and fill the full width.
+        </p>
+        <ComponentExample code={`<SankeyChart
+  nodes={nodes}
+  links={links}
+  height={350}
+  left={0}
+  right={0}
+/>`}>
+          <SankeyChartFullWidthDemo client:visible />
+        </ComponentExample>
+      </div>
+
       <div>
         <Heading level={3}>Rich Tooltips</Heading>
         <p class="mb-4 text-kumo-subtle">

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

@@ -496,6 +496,82 @@ describe("SankeyChart", () => {
     });
   });
 
+  describe("left and right layout props", () => {
+    it("does not include left/right in series config when omitted", () => {
+      const mockChart = createMockChart();
+      const mockEcharts = createMockEcharts(mockChart);
+
+      render(
+        <SankeyChart
+          echarts={mockEcharts as any}
+          nodes={baseNodes}
+          links={baseLinks}
+        />,
+      );
+
+      const options = mockChart.setOption.mock.calls[0][0];
+      expect(options.series[0]).not.toHaveProperty("left");
+      expect(options.series[0]).not.toHaveProperty("right");
+    });
+
+    it("includes left: 0 and right: 0 when passed as numbers", () => {
+      const mockChart = createMockChart();
+      const mockEcharts = createMockEcharts(mockChart);
+
+      render(
+        <SankeyChart
+          echarts={mockEcharts as any}
+          nodes={baseNodes}
+          links={baseLinks}
+          left={0}
+          right={0}
+        />,
+      );
+
+      const options = mockChart.setOption.mock.calls[0][0];
+      expect(options.series[0].left).toBe(0);
+      expect(options.series[0].right).toBe(0);
+    });
+
+    it("forwards string percentage values correctly", () => {
+      const mockChart = createMockChart();
+      const mockEcharts = createMockEcharts(mockChart);
+
+      render(
+        <SankeyChart
+          echarts={mockEcharts as any}
+          nodes={baseNodes}
+          links={baseLinks}
+          left="10%"
+          right="15%"
+        />,
+      );
+
+      const options = mockChart.setOption.mock.calls[0][0];
+      expect(options.series[0].left).toBe("10%");
+      expect(options.series[0].right).toBe("15%");
+    });
+
+    it("forwards pixel number values correctly", () => {
+      const mockChart = createMockChart();
+      const mockEcharts = createMockEcharts(mockChart);
+
+      render(
+        <SankeyChart
+          echarts={mockEcharts as any}
+          nodes={baseNodes}
+          links={baseLinks}
+          left={20}
+          right={30}
+        />,
+      );
+
+      const options = mockChart.setOption.mock.calls[0][0];
+      expect(options.series[0].left).toBe(20);
+      expect(options.series[0].right).toBe(30);
+    });
+  });
+
   describe("dark mode", () => {
     it("initializes ECharts with dark theme when isDarkMode is true", () => {
       const mockChart = createMockChart();

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

@@ -77,6 +77,10 @@ export interface SankeyChartProps {
   nodePadding?: number;
   showTooltip?: boolean;
   defaultNodeColor?: string;
+  /** Left padding of the Sankey layout within the chart container. Accepts a number (px) or percentage string. ECharts default: '5%'. */
+  left?: number | string;
+  /** Right padding of the Sankey layout within the chart container. Accepts a number (px) or percentage string. ECharts default: '5%'. */
+  right?: number | string;
   /** Link fill style: 'gradient' blends source to target colors, 'gray' uses flat gray */
   linkColor?: "gradient" | "gray";
   linkOpacity?: number;
@@ -168,6 +172,8 @@ export function SankeyChart({
   formatValue = defaultFormatValue,
   tooltipFormatter,
   defaultNodeColor,
+  left,
+  right,
   linkColor = "gradient",
   linkOpacity = 0.5,
   className,
@@ -276,6 +282,8 @@ export function SankeyChart({
       series: [
         {
           type: "sankey",
+          ...(left !== undefined && { left }),
+          ...(right !== undefined && { right }),
           data: echartsNodes,
           links: echartsLinks,
           draggable: false,
@@ -329,6 +337,8 @@ export function SankeyChart({
     nodeWidth,
     nodePadding,
     defaultNodeColor,
+    left,
+    right,
     isDarkMode,
     linkColor,
     linkOpacity,