feat(mcp): render paths query results as a sankey in the mcp ui app

frontend/snapshots.yml

@@ -217,9 +217,9 @@ snapshots:
     charts-sankeychart--left-aligned-with-values--light:
         hash: v1.k794b7964.71b32f628496dd8801855184c3ea3d3f0b47312041f148137107b7a48632b21d.3AfY_JFLCbBv12AAbc_xFpoqjxTK4XIZoKQJD1nc-Gw
     charts-sankeychart--narrow--dark:
-        hash: v1.k794b7964.c0a92bc5346237079d7aa76591ef95866a0027554600de68d00488ec576ab34e.rae6pJ76-lo4OAFw2I21f4RwAfpkvPMce_DdY9MKzwQ
+        hash: v1.k794b7964.b2f0193be7c51e6f55e7971cd382edaa2aa2791e504e030a0158279767764f03.A48fC6kABWYb5bH8hKPUi-5GYX2I8zYoeyKzNS__FXE
     charts-sankeychart--narrow--light:
-        hash: v1.k794b7964.1f36bc77ab15bef2f717ba801cb66cb03cfe83d0deedffc0e69b0448302bb56c.1uAAAcF-jsEeS7JkUg0VbDHHQ1YZAdpwXiMG_8X9TRM
+        hash: v1.k794b7964.7b456eb24ee839014b47a23a7fc05b317e93e5d13d8fc2f88bbb61f47a94fb5e.w53BwKHfejMxdOlnCqXv_NxY4KDAzPjKliLhvMQ4LEc
     charts-sankeychart--tool-call-journeys--dark:
         hash: v1.k794b7964.e50f64b0a2556e240047944407ec800fb78ffc2ad3eca93219f235d64883327d.9_vvmCGYMQ1aMSvgEOizcAf1tRGe7r0-FwNnrD3cHMo
     charts-sankeychart--tool-call-journeys--light:
@@ -6306,6 +6306,12 @@ snapshots:
         hash: v1.k794b7964.f6b81da6dbf0a63ddb55f3fc72b96ac5f72716698f914d73edb124e8ea17b0d1.2FXYB8hKUiO_FXveQuHw5J4O8WTK5bzOeiwCE9MUT4Q
     mcp-apps-lifecycle--stacked--light:
         hash: v1.k794b7964.e1057e251338bfbf9c5d6931d0f1a826064ab0c29843b716cf517ed7e8ff7d4e.y37bYZBa7mXiNTF6Xi_o7FtpVTdWgQa-xkc2koc_YRE
+    mcp-apps-paths--empty--light:
+        hash: v1.k794b7964.77b9d91893c5eb208216101495bb726906a1ebd04d17d5dbe24d24f0f23db822.DiRsE3sG-mQA5IpcZUhKFbZbDZ7xlblqQ5AQWlcm1VA
+    mcp-apps-paths--single-transition--light:
+        hash: v1.k794b7964.1c39a0bd2e56c6ad3c840cb2f2c7ac82b7fede3695fb7e9c699cf2b8b5af46c1.C8mutFhNrCTIQqpcRgICk-DmD4T4ldKtT70DJJ6iGkI
+    mcp-apps-paths--store-journeys--light:
+        hash: v1.k794b7964.d1a80e7a42dbfba333e75311b06e72992c611130708899769647558c2f661887.2p7Ut-EFMO8QR2OcwN_evJC-e-NBfFbaU7PzlBOr-SE
     mcp-apps-query-results--single-number--light:
         hash: v1.k794b7964.b53e77f7c428fe5d86903e3bee082eb7c752f67fb3225c043229e4b713debe69.hhBuSmExHBpDioDG9Ij-4qfvVhG77IC5FNYierdlZq8
     mcp-apps-query-results--table--light:
@@ -12456,6 +12462,10 @@ snapshots:
         hash: v1.k794b7964.9549b853f80d754b9d6ccf17ab144d24218143200c90df7af687e184e7de5329.Er1_HM8avmrqmulj2hCLnkp98-HeuRvF5ed3j-_jS2A
     scenes-app-mcp-analytics--intent-clustering--light:
         hash: v1.k794b7964.82fd6a9108a34ff8808b23b9c1e9255dcbe4f38562bb9e99333877dd303c08b2.qjDLxTHFZT3vcTHmPeG35-orU88GSS277RR2DdXxBdw
+    scenes-app-mcp-analytics--intent-clustering-journey--dark:
+        hash: v1.k794b7964.dca69b2edf84d19bb67ce3e2cc1a216fe6a63e9a1a36d8edb233b1f8ca60fd47.DJ-_pBzuUihpltpNAimi3dx_FewI6FzyLNKdoMZAMH4
+    scenes-app-mcp-analytics--intent-clustering-journey--light:
+        hash: v1.k794b7964.ac0eec4da423308decb9fbbd3f220e099b0a0a54dec45784b68c3bea89e7ec4d.vT3XHi6hXU4CIW6_dGDW6ShwhxyN5i1G-w00_qLnx3k
     scenes-app-mcp-analytics--sessions--dark:
         hash: v1.k794b7964.b9da0424c439b93ca4cfee035f623db248bf270c2f35d67fb149913d51357021.MHRBg5VvUtimcxoRkdmXRQmmxfzUts7dkMN-IIoczzI
     scenes-app-mcp-analytics--sessions--light:

packages/quill/packages/charts/src/charts/SankeyChart/SankeyChart.test.tsx

@@ -3,8 +3,10 @@ import { fireEvent, render, waitFor } from '@testing-library/react'
 import type { ChartTheme } from '../../core/types'
 import { getHogChartTooltip, renderHogChart } from '../../testing'
 import { computeSankeyLayout } from './sankey-data'
-import type { SankeyLinkInput, SankeyNodeInput } from './sankey-data'
+import type { SankeyLinkInput, SankeyNodeDatum, SankeyNodeInput } from './sankey-data'
+import { labelsSharingLastGap, outsideLabelWidth, sankeyLabelBoxes } from './sankey-labels'
 import { SankeyChart } from './SankeyChart'
+import { fitHeader } from './SankeyColumnLabels'
 
 const THEME: ChartTheme = { colors: ['#1f77b4', '#ff7f0e', '#2ca02c'], backgroundColor: '#ffffff' }
 
@@ -50,6 +52,29 @@ describe('SankeyChart', () => {
         expect(chart.canvas.getAttribute('aria-label')).toBe('Sankey chart with 3 nodes and 2 links')
     })
 
+    it('drops the label of a thin node that would print over its larger neighbor', () => {
+        // Two thin nodes stacked in one column: their boxes are a pixel or two tall, so their label
+        // centers sit closer than a line of text. The larger flow keeps its label.
+        const { chart } = renderHogChart(
+            <SankeyChart
+                nodes={[
+                    { id: 'start', label: 'Start' },
+                    { id: 'a', label: 'Big' },
+                    { id: 'b', label: 'Thin' },
+                    { id: 'c', label: 'Thinner' },
+                ]}
+                links={[
+                    { source: 'start', target: 'a', value: 400 },
+                    { source: 'start', target: 'b', value: 2 },
+                    { source: 'start', target: 'c', value: 1 },
+                ]}
+                theme={THEME}
+                config={{ nodePadding: 0 }}
+            />
+        )
+        expect(chart.sankeyNodeLabels()).toEqual(['Start', 'Big', 'Thin'])
+    })
+
     it('shows the hovered node in the tooltip, reports it once, and fires onNodeClick for it', async () => {
         const onNodeClick = jest.fn()
         const onHoverChange = jest.fn()
@@ -210,7 +235,13 @@ describe('SankeyChart', () => {
             broken: { links: [LINKS[0], { source: 'a', target: 'missing', value: 12 }] },
         },
         { name: 'the node padding', broken: { config: { nodePadding: -1 } } },
-    ])('recovers from an invalid graph when only $name is corrected', ({ broken }) => {
+        { name: 'a NaN pin', broken: { nodes: [{ ...NODES[0], column: NaN }, ...NODES.slice(1)] } },
+        {
+            name: 'a numeric-string pin',
+            broken: { nodes: [{ ...NODES[0], column: '0' as unknown as number }, ...NODES.slice(1)] },
+            corrected: { nodes: [{ ...NODES[0], column: 0 }, ...NODES.slice(1)] },
+        },
+    ])('recovers from an invalid graph when only $name is corrected', ({ broken, corrected }) => {
         jest.spyOn(console, 'error').mockImplementation(() => {})
         const onError = jest.fn()
         const { container, rerender } = render(
@@ -219,7 +250,131 @@ describe('SankeyChart', () => {
         expect(onError).toHaveBeenCalled()
         expect(container.textContent).toContain('Something went wrong')
 
-        rerender(<SankeyChart nodes={NODES} links={LINKS} theme={THEME} onError={onError} />)
+        rerender(<SankeyChart nodes={NODES} links={LINKS} theme={THEME} onError={onError} {...corrected} />)
         expect(container.textContent).not.toContain('Something went wrong')
     })
+
+    it('finds labels that face each other across the gap the last two columns share', () => {
+        const node = (id: string, column: number, y0: number): SankeyNodeDatum => ({
+            id,
+            label: id,
+            color: '#000',
+            index: 0,
+            column,
+            value: 1,
+            x0: 0,
+            x1: 0,
+            y0,
+            y1: y0 + 4,
+        })
+        const first = node('first', 0, 100)
+        const penultimate = node('penultimate', 1, 100)
+        const last = node('last', 2, 102)
+        const lastFarAway = node('lastFarAway', 2, 200)
+        expect(labelsSharingLastGap(new Set([first, penultimate, last, lastFarAway]), 3)).toEqual(
+            new Set([penultimate, last])
+        )
+    })
+
+    it('shows the node tooltip when the pointer is over its label, not the ribbon under it', async () => {
+        const { chart } = renderHogChart(<SankeyChart nodes={NODES} links={LINKS} theme={THEME} />, {
+            nativeTooltip: true,
+        })
+        // Right of the Start node, inside its label and over the Start -> Tool A ribbon.
+        const start = nodeCenter('start')
+        await waitFor(() => {
+            fireEvent.mouseMove(chart.element, { clientX: start.clientX + 17, clientY: start.clientY })
+            expect(getHogChartTooltip()?.textContent).toContain('Start')
+        })
+        expect(getHogChartTooltip()?.textContent).not.toContain('→')
+    })
+
+    it('places last-column labels outside the nodes when asked, and truncates headers to their span', () => {
+        const layout = computeSankeyLayout({
+            nodes: NODES,
+            links: LINKS,
+            plot: { plotLeft: 8, plotTop: 8, plotWidth: 600, plotHeight: 300 },
+            nodeWidth: 12,
+            nodePadding: 8,
+            nodeAlign: 'justify',
+            preserveNodeOrder: false,
+            colorForLabel: () => '#000',
+            resolveColor: (c) => c,
+        })
+        const options = { showValues: false, valueFormatter: String, outsideWidth: 120 }
+        const sideOfLast = (lastColumnLabels: 'inside' | 'outside'): string | undefined =>
+            sankeyLabelBoxes(layout, { ...options, lastColumnLabels }).find((box) => box.text === 'Completed')?.side
+        expect([sideOfLast('inside'), sideOfLast('outside')]).toEqual(['left', 'right'])
+
+        expect(fitHeader('Outcome', 1000)).toBe('Outcome')
+        expect(fitHeader('4th tool', 8)).toBe('4th…')
+    })
+
+    it('draws no label where a narrow chart leaves it no room', () => {
+        const layout = computeSankeyLayout({
+            nodes: NODES,
+            links: LINKS,
+            plot: { plotLeft: 8, plotTop: 8, plotWidth: 40, plotHeight: 300 },
+            nodeWidth: 12,
+            nodePadding: 8,
+            nodeAlign: 'justify',
+            preserveNodeOrder: false,
+            colorForLabel: () => '#000',
+            resolveColor: (c) => c,
+        })
+        const boxes = sankeyLabelBoxes(layout, {
+            showValues: false,
+            valueFormatter: String,
+            lastColumnLabels: 'inside',
+            outsideWidth: 0,
+        })
+        expect(boxes).toEqual([])
+    })
+
+    it.each([
+        { nodeAlign: 'left' as const, sizedBy: 'Completed' },
+        { nodeAlign: 'justify' as const, sizedBy: 'Left after the first tool' },
+    ])('sizes the outside margin by the sinks in the last column under $nodeAlign', ({ nodeAlign, sizedBy }) => {
+        const nodes: SankeyNodeInput[] = [...NODES, { id: 'early', label: 'Left after the first tool' }]
+        const links: SankeyLinkInput[] = [...LINKS, { source: 'start', target: 'early', value: 3 }]
+        const onlySink = outsideLabelWidth([{ id: 'only', label: sizedBy }], [], nodeAlign, false, String)
+        expect(outsideLabelWidth(nodes, links, nodeAlign, false, String)).toBe(onlySink)
+    })
+
+    it('keeps nodes and labels when the outside label room is wider than half the plot', () => {
+        const nodes: SankeyNodeInput[] = [
+            { id: 'start', label: 'Start' },
+            { id: 'done', label: 'Completed after a very long outcome name that needs the full margin' },
+        ]
+        // An 800px wrapper with a 700px left margin leaves a 92px plot, under the 160px label cap.
+        const { chart } = renderHogChart(
+            <SankeyChart
+                nodes={nodes}
+                links={[{ source: 'start', target: 'done', value: 5 }]}
+                theme={THEME}
+                config={{ lastColumnLabels: 'outside', margins: { left: 700 } }}
+            />
+        )
+        const labels = Array.from(
+            chart.element.querySelectorAll<HTMLElement>('[data-attr="hog-chart-sankey-node-label"]')
+        ).map((label) => label.textContent)
+        expect(labels).toEqual([expect.stringMatching(/^Start/), expect.stringMatching(/^Comp.*…/)])
+    })
+
+    it('keeps room for column headers when a consumer overrides the top margin', () => {
+        const { chart } = renderHogChart(
+            <SankeyChart
+                nodes={NODES}
+                links={LINKS}
+                theme={THEME}
+                config={{ columnLabels: ['Init', 'Tool', 'Outcome'], margins: { top: 0 } }}
+            />
+        )
+        // Start fills the plot height, so its label sits at the plot's vertical center: 18px of
+        // header room above a 400px wrapper with an 8px bottom margin.
+        const start = Array.from(
+            chart.element.querySelectorAll<HTMLElement>('[data-attr="hog-chart-sankey-node-label"]')
+        ).find((label) => label.textContent?.startsWith('Start'))
+        expect(start?.style.top).toBe(`${18 + (400 - 18 - 8) / 2}px`)
+    })
 })

packages/quill/packages/charts/src/charts/SankeyChart/SankeyChart.tsx

@@ -18,6 +18,8 @@ import { SankeyLayoutContext } from './sankey-context'
 import type { SankeyLayoutContextValue } from './sankey-context'
 import { computeSankeyLayout, defaultValueFormatter, hoverIndexToHit } from './sankey-data'
 import type { SankeyChartLayout, SankeyLinkInput, SankeyNodeInput } from './sankey-data'
+import { outsideLabelWidth, sankeyLabelBoxes } from './sankey-labels'
+import type { SankeyLabelBox } from './sankey-labels'
 import { SankeyColumnLabels } from './SankeyColumnLabels'
 import { SankeyNodeLabels } from './SankeyNodeLabels'
 import type { SankeyChartProps, SankeyTooltipContext } from './types'
@@ -41,8 +43,10 @@ function graphKey(
     config: SankeyChartProps['config']
 ): string {
     // Structured serialization: ids are free-form strings, so a delimiter inside one must not collide.
+    // JSON writes both NaN and a missing pin as null, so pins go in as strings to keep them apart.
+    // The type goes in too, so a rejected '1' and a corrected 1 do not share a key.
     return JSON.stringify([
-        nodes.map((node) => node.id),
+        nodes.map((node) => [node.id, typeof node.column, String(node.column)]),
         links.map(({ source, target, value }) => [source, target, value]),
         [config?.nodeWidth, config?.nodePadding, config?.nodeAlign, config?.preserveNodeOrder],
     ])
@@ -83,6 +87,7 @@ function SankeyChartInner<NodeMeta = unknown, LinkMeta = NodeMeta>({
         preserveNodeOrder = false,
         columnLabels,
         showNodeLabels = true,
+        lastColumnLabels = 'inside',
         showNodeValues = false,
         linkOpacity: configuredLinkOpacity = DEFAULT_LINK_OPACITY,
         valueFormatter = defaultValueFormatter,
@@ -95,15 +100,38 @@ function SankeyChartInner<NodeMeta = unknown, LinkMeta = NodeMeta>({
     const showTooltip = tooltipConfig?.enabled !== false
     const hasColumnLabels = !!columnLabels && columnLabels.length > 0
 
+    const outsideWidth = useMemo(
+        () =>
+            showNodeLabels && lastColumnLabels === 'outside'
+                ? outsideLabelWidth(nodes, links, nodeAlign, showNodeValues, valueFormatter)
+                : 0,
+        [showNodeLabels, lastColumnLabels, nodes, links, nodeAlign, showNodeValues, valueFormatter]
+    )
+
     const margins = useMemo<ChartMargins>(() => {
-        const computed = hasColumnLabels
-            ? { ...BASE_MARGINS, top: BASE_MARGINS.top + COLUMN_LABEL_HEIGHT }
-            : BASE_MARGINS
-        return marginsOverride ? applyMarginOverride(computed, marginsOverride) : computed
+        const applied = marginsOverride ? applyMarginOverride(BASE_MARGINS, marginsOverride) : BASE_MARGINS
+        // Column headers are sized for their room, so an override cannot take it away.
+        return { ...applied, top: applied.top + (hasColumnLabels ? COLUMN_LABEL_HEIGHT : 0) }
     }, [hasColumnLabels, marginsOverride])
 
     const { canvasRef, overlayCanvasRef, wrapperRef, dimensions, ctx, overlayCtx } = useChartCanvas({ margins })
 
+    // `outside` labels take their room from the plot, capped at half of it, so a chart narrower
+    // than the labels still has nodes to draw and the labels truncate instead.
+    const outsideRoom = dimensions ? Math.min(outsideWidth, Math.floor(dimensions.plotWidth / 2)) : 0
+    const plot = useMemo(
+        () =>
+            dimensions
+                ? {
+                      plotLeft: dimensions.plotLeft,
+                      plotTop: dimensions.plotTop,
+                      plotWidth: dimensions.plotWidth - outsideRoom,
+                      plotHeight: dimensions.plotHeight,
+                  }
+                : { plotLeft: 0, plotTop: 0, plotWidth: 0, plotHeight: 0 },
+        [dimensions, outsideRoom]
+    )
+
     // `useChartTheme` rereads the CSS variables on any class change on <html> or <body>, and returns
     // an equal palette in a new array. Keying on the values keeps that from rebuilding the layout,
     // because a new layout clears the hover and its tooltip.
@@ -130,15 +158,15 @@ function SankeyChartInner<NodeMeta = unknown, LinkMeta = NodeMeta>({
             computeSankeyLayout<NodeMeta, LinkMeta>({
                 nodes,
                 links,
-                plot: dimensions ?? { plotLeft: 0, plotTop: 0, plotWidth: 0, plotHeight: 0 },
+                plot,
                 nodeWidth,
                 nodePadding,
                 nodeAlign,
                 preserveNodeOrder,
                 colorForLabel,
                 resolveColor: resolveCssColor,
             }),
-        [nodes, links, dimensions, nodeWidth, nodePadding, nodeAlign, preserveNodeOrder, colorForLabel]
+        [nodes, links, plot, nodeWidth, nodePadding, nodeAlign, preserveNodeOrder, colorForLabel]
     )
 
     // A controlled highlight paints on the static layer, so a change to it is a full repaint
@@ -158,8 +186,22 @@ function SankeyChartInner<NodeMeta = unknown, LinkMeta = NodeMeta>({
         [dimensions, layout, linkOpacity, hasEmphasis]
     )
 
+    const labelBoxes = useMemo<SankeyLabelBox[]>(
+        () =>
+            showNodeLabels
+                ? sankeyLabelBoxes(layout as SankeyChartLayout<unknown, unknown>, {
+                      showValues: showNodeValues,
+                      valueFormatter,
+                      lastColumnLabels,
+                      outsideWidth: outsideRoom,
+                  })
+                : [],
+        [showNodeLabels, layout, showNodeValues, valueFormatter, lastColumnLabels, outsideRoom]
+    )
+
     const { hoverIndex, hoverPosition, tooltipCtx, handlers } = useSankeyInteraction<NodeMeta, LinkMeta>({
         layout,
+        labelBoxes,
         canvasRef,
         wrapperRef,
         showTooltip,
@@ -231,7 +273,7 @@ function SankeyChartInner<NodeMeta = unknown, LinkMeta = NodeMeta>({
         }
         return {
             scales,
-            dimensions,
+            dimensions: { ...dimensions, plotWidth: plot.plotWidth },
             labels: [],
             series: [],
             theme,
@@ -240,7 +282,7 @@ function SankeyChartInner<NodeMeta = unknown, LinkMeta = NodeMeta>({
             axis: { orientation: 'vertical', xTickFormatter: undefined, isPercent: false },
             yGutters: [],
         }
-    }, [scales, dimensions, theme, canvasBounds])
+    }, [scales, dimensions, plot.plotWidth, theme, canvasBounds])
     const sankeyValue = useMemo<SankeyLayoutContextValue<NodeMeta, LinkMeta>>(
         () => ({ layout, canvasBounds }),
         [layout, canvasBounds]
@@ -266,14 +308,10 @@ function SankeyChartInner<NodeMeta = unknown, LinkMeta = NodeMeta>({
                         handlers={handlers}
                         showOverlay={!!dimensions}
                     >
-                        {hasColumnLabels ? <SankeyColumnLabels labels={columnLabels} color={labelColor} /> : null}
-                        {showNodeLabels ? (
-                            <SankeyNodeLabels
-                                color={labelColor}
-                                showValues={showNodeValues}
-                                valueFormatter={valueFormatter}
-                            />
+                        {hasColumnLabels ? (
+                            <SankeyColumnLabels labels={columnLabels} color={labelColor} trailingRoom={outsideRoom} />
                         ) : null}
+                        {showNodeLabels ? <SankeyNodeLabels boxes={labelBoxes} color={labelColor} /> : null}
                         {children}
                         {tooltipCtx && showTooltip ? (
                             <Tooltip