panelui-native 0.101.0 → 0.102.0

package/lib/module/components/sankey-chart/index.js

@@ -67,11 +67,13 @@ import Svg, { G, Path, Rect } from 'react-native-svg';
 import { useCSSVariable } from 'uniwind';
 import { ChartAccessibilityData } from "../../primitives/chart-accessibility.js";
 import { Text } from "../../primitives/text.js";
-import { compactNumber, flowPath, seriesColorAt, useSeriesColor } from "../../utils/chart.js";
+import { compactNumber, flowPath, flowPathVertical, seriesColorAt, useSeriesColor } from "../../utils/chart.js";
 import { cn } from "../../utils/cn.js";
 import { useDirection } from "../../hooks/use-direction.js";
 import { useSkeletonHandoff } from "../../hooks/use-skeleton-handoff.js";
-import { sankeyLayout } from "./sankey-layout.js";
+import { sankeyLayout, transposeLayout } from "./sankey-layout.js";
+
+/** Which way the flow runs. */
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 const AnimatedPath = Animated.createAnimatedComponent(Path);
 const AnimatedRect = Animated.createAnimatedComponent(Rect);
@@ -80,6 +82,17 @@ const AnimatedG = Animated.createAnimatedComponent(G);
 /** How tall the diagram is drawn when the caller does not say. */
 const DEFAULT_HEIGHT = 240;
 
+/**
+ * How much depth one stage of an upright flow is given when nothing says.
+ *
+ * A vertical diagram's height is the length of the flow, so unlike the
+ * horizontal case it grows with the data: four stages in the height of three
+ * is a set of bars with no room for a ribbon between them. Enough for a bar,
+ * a name on each side of it, and a run of ribbon long enough to read as one —
+ * and no more, because on a phone every extra point of it is a scroll.
+ */
+const VERTICAL_STAGE = 104;
+
 /** How thick a node's bar is. Thin enough to read as an edge the flow meets. */
 const DEFAULT_NODE_WIDTH = 10;
 
@@ -122,6 +135,28 @@ const LABEL_GAP = 6;
 /** The smallest a label's press target is allowed to be, in points. */
 const MIN_TARGET = 44;
 
+/**
+ * Roughly how wide a name is drawn, in points, backdrop included.
+ *
+ * An estimate rather than a measurement, because measuring every name means a
+ * render to find out where to render them. Deliberately on the generous side:
+ * guessing short is how a name ends up cut off, and guessing long only costs a
+ * few points of the row.
+ */
+function nameWidth(name) {
+  return name.length * 7 + 18;
+}
+
+/**
+ * How much height one line of a name takes, in points, backdrop included.
+ *
+ * A name is centred on its bar, and a bar thinner than this carries a name
+ * taller than itself — which is fine until two of them sit close enough for
+ * the text to run into each other. So names are placed as boxes of this
+ * height, not of the bar's.
+ */
+const LABEL_LINE = 20;
+
 /** Columns the placeholder suggests while there is no data to count. */
 const SKELETON_COLUMNS = 3;
 
@@ -147,12 +182,16 @@ function useChart(component) {
   return context;
 }
 
+/** One end of a stream meeting the selected node. */
+
 /** The selected node and what runs through it, for something drawn inside the chart. */
 export function useSankeyChart() {
   const {
     nodes,
     layout,
-    activeId
+    activeId,
+    colors,
+    labelFor
   } = useChart('useSankeyChart');
   return useMemo(() => {
     const placed = activeId ? layout.nodes.find(node => node.id === activeId) : undefined;
@@ -162,27 +201,67 @@ export function useSankeyChart() {
         activeNode: null,
         activeValue: 0,
         incoming: 0,
-        outgoing: 0
+        outgoing: 0,
+        sources: [],
+        targets: [],
+        collapsed: null
       };
     }
     const position = layout.nodes.indexOf(placed);
     let incoming = 0;
     let outgoing = 0;
+    const sources = [];
+    const targets = [];
+    const flow = (at, value) => {
+      const other = layout.nodes[at];
+      if (!other) return null;
+      return {
+        id: other.id,
+        label: labelFor(other.id),
+        value,
+        // Against what passes through the node rather than against the side's
+        // own total, so in and out are read on one scale — at a node that
+        // loses some of what it received, two totals that differ is the point.
+        share: placed.value > 0 ? value / placed.value : 0,
+        color: colors[at] ?? colors[0] ?? '#3b82f6'
+      };
+    };
     for (const link of layout.links) {
-      if (link.target === position) incoming += link.value;
-      if (link.source === position) outgoing += link.value;
+      if (link.target === position) {
+        incoming += link.value;
+        const row = flow(link.source, link.value);
+        if (row) sources.push(row);
+      }
+      if (link.source === position) {
+        outgoing += link.value;
+        const row = flow(link.target, link.value);
+        if (row) targets.push(row);
+      }
     }
+
+    // Largest first: the reason to open a breakdown is to find out what the
+    // biggest part of it was.
+    sources.sort((a, b) => b.value - a.value);
+    targets.sort((a, b) => b.value - a.value);
     return {
       activeId,
-      activeNode: nodes.find(node => node.id === activeId) ?? null,
+      activeNode: nodes[placed.index] ?? {
+        id: placed.id
+      },
       /** What passes through it — what the bar's height is drawn from. */
       activeValue: placed.value,
       /** What arrives. Zero at a node the flow starts from. */
       incoming,
       /** What leaves. Zero at a node the flow ends at. */
-      outgoing
+      outgoing,
+      /** Where it came from, largest first. */
+      sources,
+      /** Where it went, largest first. */
+      targets,
+      /** The ids `collapse` folded in, on a bucket. `null` on every other node. */
+      collapsed: placed.collapsed ?? null
     };
-  }, [nodes, layout, activeId]);
+  }, [nodes, layout, activeId, colors, labelFor]);
 }
 
 /** Imperative handle: re-run the entrance, for a "replay" control. */
@@ -191,9 +270,11 @@ const SankeyChartRoot = /*#__PURE__*/forwardRef(function SankeyChartRoot({
   className,
   nodes,
   links,
-  height = DEFAULT_HEIGHT,
+  height: heightProp,
   nodeWidth = DEFAULT_NODE_WIDTH,
   nodePadding = DEFAULT_NODE_PADDING,
+  orientation = 'horizontal',
+  collapse,
   align = 'justify',
   iterations = DEFAULT_ITERATIONS,
   curve = CURVE,
@@ -207,6 +288,7 @@ const SankeyChartRoot = /*#__PURE__*/forwardRef(function SankeyChartRoot({
   accessibilityLabel,
   accessibilityHint,
   accessibilityLabelForDatum,
+  accessibilityLabelForLink,
   onAccessibilityDatumPress,
   children,
   ...props
@@ -222,22 +304,57 @@ const SankeyChartRoot = /*#__PURE__*/forwardRef(function SankeyChartRoot({
     if (!controlled) setInternalActive(id);
     onActiveIdChange?.(id);
   }, [controlled, onActiveIdChange]);
-  const layout = useMemo(() => sankeyLayout(nodes, links, {
-    width,
-    height,
-    nodeWidth,
-    nodePadding,
-    align,
-    iterations
-  }), [nodes, links, width, height, nodeWidth, nodePadding, align, iterations]);
+  const upright = orientation === 'horizontal';
+
+  /*
+   * How many stages the flow needs, for the case where the height has to be
+   * worked out from it. Solved with no relaxation rounds and in an arbitrary
+   * box, because the column count falls out of the links alone — the
+   * arrangement inside the columns is exactly the part being skipped.
+   */
+  const stages = useMemo(() => {
+    if (upright || heightProp !== undefined) return 0;
+    return sankeyLayout(nodes, links, {
+      width: 1000,
+      height: 1000,
+      nodeWidth,
+      nodePadding,
+      align,
+      iterations: 0,
+      collapse
+    }).columns;
+  }, [upright, heightProp, nodes, links, nodeWidth, nodePadding, align, collapse]);
+  const height = heightProp ?? (upright ? DEFAULT_HEIGHT : Math.max(DEFAULT_HEIGHT, stages * VERTICAL_STAGE));
+  const layout = useMemo(() => {
+    /*
+     * An upright flow is solved in the box as given. A vertical one is
+     * solved in that box turned on its side and then turned back, so the
+     * stages advance down the screen — one set of maths, read the other way.
+     */
+    const solved = sankeyLayout(nodes, links, {
+      width: upright ? width : height,
+      height: upright ? height : width,
+      nodeWidth,
+      nodePadding,
+      align,
+      iterations,
+      collapse
+    });
+    return upright ? solved : transposeLayout(solved);
+  }, [nodes, links, width, height, nodeWidth, nodePadding, align, iterations, collapse, upright]);
 
   /*
    * A flow reads from where it starts, and under a right-to-left layout that
    * is the right-hand edge. Mirroring the finished layout rather than laying
    * it out backwards keeps one set of maths under both directions — the
    * arrangement is identical, it is only read from the other end.
+   *
+   * Only where the flow runs across the screen. A vertical one starts at the
+   * top in every script, and mirroring it would flip the axis carrying the
+   * values rather than the one carrying the order — the same diagram with
+   * its bars reflected, for no reason a reader could name.
    */
-  const mirrored = direction === 'rtl';
+  const mirrored = direction === 'rtl' && upright;
   const placed = useMemo(() => {
     if (!mirrored || !layout.nodes.length) return layout;
     return {
@@ -270,6 +387,9 @@ const SankeyChartRoot = /*#__PURE__*/forwardRef(function SankeyChartRoot({
     const names = new Map(nodes.map(node => [node.id, node.label ?? node.id]));
     return id => names.get(id) ?? id;
   }, [nodes]);
+  const datumFor = useMemo(() => node => nodes[node.index] ?? {
+    id: node.id
+  }, [nodes]);
 
   /*
    * One clock, with each column given the slice of it that it draws in, so
@@ -324,6 +444,22 @@ const SankeyChartRoot = /*#__PURE__*/forwardRef(function SankeyChartRoot({
     const next = Math.round(event.nativeEvent.layout.width);
     if (next !== width) setWidth(next);
   };
+
+  /*
+   * The ids `SankeyChart.Labels` drew a name for, or `null` while it has not
+   * said. Compared rather than replaced, because Labels reports on every
+   * layout change and a fresh array each time would re-render the chart
+   * forever.
+   */
+  const [labelledIds, setLabelledIds] = useState(null);
+  const reportLabelled = useMemo(() => ids => setLabelledIds(current => {
+    if (current === ids) return current;
+    if (current === null || ids === null) return ids;
+    if (current.length === ids.length && current.every((id, i) => id === ids[i])) {
+      return current;
+    }
+    return ids;
+  }), []);
   const context = useMemo(() => ({
     nodes,
     links,
@@ -337,8 +473,11 @@ const SankeyChartRoot = /*#__PURE__*/forwardRef(function SankeyChartRoot({
     status,
     activeId: activeId ?? null,
     setActiveId,
-    labelFor
-  }), [nodes, links, placed, width, height, curve, colors, windows, reveal, status, activeId, setActiveId, labelFor]);
+    labelFor,
+    reportLabelled,
+    orientation,
+    datumFor
+  }), [nodes, links, placed, width, height, curve, colors, windows, reveal, status, activeId, setActiveId, labelFor, reportLabelled, orientation, datumFor]);
   const slots = {
     svg: [],
     overlay: [],
@@ -346,10 +485,14 @@ const SankeyChartRoot = /*#__PURE__*/forwardRef(function SankeyChartRoot({
     footer: []
   };
   /*
-   * Whether the names are on the chart decides how it is read out. With
-   * `Labels` there is a pressable row per node already, and the semantic
-   * list below would say all of it a second time; without them the diagram
-   * is pure geometry and the list is the only way through it.
+   * Whether the names are on the chart decides how it is read out. Without
+   * `Labels` the diagram is pure geometry and the semantic list is the only
+   * way through it. With them, most nodes are a pressable row already and
+   * the list would say it all a second time — but only most: a bar too short
+   * to label is left with no target and no entry, which is how the smallest
+   * nodes on a crowded diagram became unreachable by either route. So the
+   * list is narrowed to what `Labels` reports it dropped rather than turned
+   * off wholesale.
    */
   let labelled = false;
   Children.forEach(children, (child, index) => {
@@ -362,6 +505,21 @@ const SankeyChartRoot = /*#__PURE__*/forwardRef(function SankeyChartRoot({
       children: child
     }, index));
   });
+
+  /*
+   * The nodes the semantic list still has to carry.
+   *
+   * With no `Labels` that is all of them. With `Labels` it is the ones it
+   * reported dropping — and until it has reported, none: a name that turns
+   * out to exist is a duplicate entry, which is worse for one render than a
+   * missing one, and the report lands on the render straight after.
+   */
+  const spoken = useMemo(() => {
+    if (!labelled) return nodes;
+    if (labelledIds === null) return [];
+    const drawn = new Set(labelledIds);
+    return nodes.filter(node => !drawn.has(node.id));
+  }, [nodes, labelled, labelledIds]);
   return /*#__PURE__*/_jsx(SankeyChartContext.Provider, {
     value: context,
     children: /*#__PURE__*/_jsxs(View, {
@@ -393,13 +551,19 @@ const SankeyChartRoot = /*#__PURE__*/forwardRef(function SankeyChartRoot({
         }) : null
       }), slots.footer, /*#__PURE__*/_jsx(ChartAccessibilityData, {
         chart: "Flow diagram",
-        data: nodes,
-        disabled: labelled || status === 'loading',
+        data: spoken,
+        disabled: status === 'loading' || labelled && spoken.length === 0,
         valueOf: node => [['Node', node.label ?? node.id], ['Value', placed.nodes.find(placedNode => placedNode.id === node.id)?.value]],
         accessibilityLabel: accessibilityLabel,
         accessibilityHint: accessibilityHint,
         accessibilityLabelForDatum: accessibilityLabelForDatum,
         onAccessibilityDatumPress: onAccessibilityDatumPress
+      }), /*#__PURE__*/_jsx(LinkAccessibilityData, {
+        disabled: status === 'loading',
+        layout: placed,
+        links: links,
+        labelFor: labelFor,
+        labelForLink: accessibilityLabelForLink
       })]
     })
   });
@@ -413,6 +577,53 @@ function ChildSlot({
   });
 }
 
+/**
+ * The ribbons, for a screen reader.
+ *
+ * Kept apart from the node list rather than folded into it, because the two
+ * are different readings and a caller overrides them separately: a node says
+ * how much passed through a stage, a ribbon says where it came from and where
+ * it went. A diagram read out as nodes alone is a list of totals with the
+ * routing — the thing the chart exists to show — missing from it.
+ *
+ * Offscreen rather than hidden, so the entries are reachable by swiping while
+ * nothing about the drawn diagram moves.
+ */
+function LinkAccessibilityData({
+  disabled,
+  layout,
+  links,
+  labelFor,
+  labelForLink
+}) {
+  if (disabled || !layout.links.length) return null;
+  return /*#__PURE__*/_jsx(View, {
+    style: {
+      position: 'absolute',
+      left: -10_000,
+      width: 1,
+      height: 1
+    },
+    children: layout.links.map(link => {
+      // `input` points back at the caller's row; `index` is the drawn order,
+      // which has closed up behind every row that could not be drawn.
+      // A ribbon that `collapse` merged has no single row of the caller's
+      // behind it, so there is nothing to hand an override — it still gets
+      // spoken, in the chart's own words.
+      const datum = link.input >= 0 ? links[link.input] : undefined;
+      const source = layout.nodes[link.source];
+      const target = layout.nodes[link.target];
+      if (!source || !target) return null;
+      const label = (datum ? labelForLink?.(datum, link.input) : undefined) ?? `${labelFor(source.id)} to ${labelFor(target.id)}, ${compactNumber(link.value)}`;
+      return /*#__PURE__*/_jsx(View, {
+        accessible: true,
+        accessibilityRole: "text",
+        accessibilityLabel: label
+      }, `${source.id}-${target.id}-${link.index}`);
+    })
+  });
+}
+
 /**
  * How much of the entrance a column has played, eased.
  *
@@ -452,9 +663,11 @@ function SankeyChartLinks({
     reveal,
     windows,
     status,
-    activeId
+    activeId,
+    orientation
   } = useChart('SankeyChart.Links');
   if (status === 'loading' || !layout.links.length) return null;
+  const upright = orientation === 'horizontal';
   return /*#__PURE__*/_jsx(G, {
     children: layout.links.map(link => {
       const source = layout.nodes[link.source];
@@ -466,13 +679,16 @@ function SankeyChartLinks({
         to: 1
       };
       return /*#__PURE__*/_jsx(Ribbon, {
-        x0: source.x1,
-        cy0: link.y0,
-        x1: target.x0,
-        cy1: link.y1,
+        // Where the ribbon leaves and arrives, along whichever axis the
+        // stages advance on; `link.y0`/`y1` are already across it.
+        from: upright ? source.x1 : source.y1,
+        cFrom: link.y0,
+        to: upright ? target.x0 : target.y0,
+        cTo: link.y1,
+        upright: upright,
         thickness: link.width,
         curve: curve,
-        fill: links[link.input]?.color ?? colors[link.source] ?? colors[0] ?? '#3b82f6',
+        fill: (link.input >= 0 ? links[link.input]?.color : undefined) ?? colors[link.source] ?? colors[0] ?? '#3b82f6',
         reveal: reveal,
         window: window,
         opacity: activeId === null ? opacity : touching ? activeOpacity : dimOpacity
@@ -483,20 +699,21 @@ function SankeyChartLinks({
 SankeyChartLinks.displayName = 'SankeyChart.Links';
 SankeyChartLinks.slot = 'svg';
 function Ribbon({
-  x0,
-  cy0,
-  x1,
-  cy1,
+  from: edgeFrom,
+  cFrom: centreFrom,
+  to: edgeTo,
+  cTo: centreTo,
   thickness,
   curve,
   fill,
   reveal,
   window,
-  opacity
+  opacity,
+  upright
 }) {
   const {
-    from,
-    to
+    from: windowFrom,
+    to: windowTo
   } = window;
   const settled = useDerivedValue(() => withTiming(opacity, {
     duration: SELECT_DURATION
@@ -507,9 +724,9 @@ function Ribbon({
      * one edge, so it stays anchored where it meets the node instead of
      * sliding down it as it arrives.
      */
-    const grown = thickness * progress(reveal.value, from, to);
+    const grown = thickness * progress(reveal.value, windowFrom, windowTo);
     return {
-      d: flowPath(x0, cy0, x1, cy1, grown, curve),
+      d: upright ? flowPath(edgeFrom, centreFrom, edgeTo, centreTo, grown, curve) : flowPathVertical(edgeFrom, centreFrom, edgeTo, centreTo, grown, curve),
       fillOpacity: settled.value
     };
   });
@@ -527,7 +744,8 @@ function Ribbon({
  */
 function SankeyChartNodes({
   radius = 2,
-  dimOpacity = 0.25
+  dimOpacity = 0.25,
+  interactive = true
 }) {
   const {
     layout,
@@ -535,25 +753,33 @@ function SankeyChartNodes({
     reveal,
     windows,
     status,
-    activeId
+    activeId,
+    setActiveId,
+    orientation
   } = useChart('SankeyChart.Nodes');
   if (status === 'loading' || !layout.nodes.length) return null;
+  const upright = orientation === 'horizontal';
   return /*#__PURE__*/_jsx(G, {
     children: layout.nodes.map((node, index) => {
       const window = windows[node.layer] ?? windows[0] ?? {
         from: 0,
         to: 1
       };
+      const selected = activeId === node.id;
       return /*#__PURE__*/_jsx(NodeBar, {
-        x: node.x0,
-        width: node.x1 - node.x0,
-        y0: node.y0,
-        y1: node.y1,
+        // The bar is `nodeWidth` across the flow and its value along it,
+        // so which pair of edges is which swaps with the orientation.
+        thin0: upright ? node.x0 : node.y0,
+        thin1: upright ? node.x1 : node.y1,
+        long0: upright ? node.y0 : node.x0,
+        long1: upright ? node.y1 : node.x1,
+        upright: upright,
         radius: radius,
         fill: colors[index] ?? '#3b82f6',
         reveal: reveal,
         window: window,
-        opacity: activeId === null || activeId === node.id ? 1 : dimOpacity
+        opacity: activeId === null || selected ? 1 : dimOpacity,
+        onPress: interactive ? () => setActiveId(selected ? null : node.id) : undefined
       }, node.id);
     })
   });
@@ -561,40 +787,83 @@ function SankeyChartNodes({
 SankeyChartNodes.displayName = 'SankeyChart.Nodes';
 SankeyChartNodes.slot = 'svg';
 function NodeBar({
-  x,
-  width,
-  y0,
-  y1,
+  thin0,
+  thin1,
+  long0,
+  long1,
+  upright,
   radius,
   fill,
   reveal,
   window,
-  opacity
+  opacity,
+  onPress
 }) {
   const {
     from,
     to
   } = window;
-  const extent = y1 - y0;
-  const centre = (y0 + y1) / 2;
+  const extent = long1 - long0;
+  const centre = (long0 + long1) / 2;
+  const thickness = thin1 - thin0;
   const settled = useDerivedValue(() => withTiming(opacity, {
     duration: SELECT_DURATION
   }));
   const animatedProps = useAnimatedProps(() => {
     // Grown about its centre, to match the ribbons meeting it.
     const grown = extent * progress(reveal.value, from, to);
-    return {
-      y: centre - grown / 2,
+    const near = centre - grown / 2;
+    return upright ? {
+      y: near,
       height: grown,
+      x: thin0,
+      width: thickness,
+      opacity: settled.value
+    } : {
+      x: near,
+      width: grown,
+      y: thin0,
+      height: thickness,
       opacity: settled.value
     };
   });
-  return /*#__PURE__*/_jsx(AnimatedRect, {
+  const bar = /*#__PURE__*/_jsx(AnimatedRect, {
     animatedProps: animatedProps,
-    x: x,
-    width: width,
     rx: radius,
-    fill: fill
+    fill: fill,
+    onPress: onPress
+  });
+  if (!onPress || extent >= MIN_TARGET) return bar;
+
+  /*
+   * A sliver gets a second, invisible rectangle to be pressed by, because the
+   * bar itself is two points tall and nobody can land on it. `transparent`
+   * rather than no fill: a shape with no fill is not hit-tested at all, so it
+   * would look identical and do nothing.
+   *
+   * It is drawn before the bar so the bar keeps the tap where the two overlap,
+   * and it grows about the same centre, which keeps the target over the bar
+   * rather than beside it.
+   */
+  const target = Math.max(extent, MIN_TARGET);
+  const thinCentre = (thin0 + thin1) / 2;
+  const across = {
+    from: thinCentre - MIN_TARGET / 2,
+    size: MIN_TARGET
+  };
+  const along = {
+    from: centre - target / 2,
+    size: target
+  };
+  return /*#__PURE__*/_jsxs(_Fragment, {
+    children: [/*#__PURE__*/_jsx(Rect, {
+      x: upright ? across.from : along.from,
+      width: upright ? across.size : along.size,
+      y: upright ? along.from : across.from,
+      height: upright ? along.size : across.size,
+      fill: "transparent",
+      onPress: onPress
+    }), bar]
   });
 }
 /**
@@ -622,121 +891,264 @@ function SankeyChartLabels({
 }) {
   const {
     layout,
-    nodes,
     width,
     height,
     status,
     activeId,
     setActiveId,
-    labelFor
+    labelFor,
+    reportLabelled,
+    orientation,
+    datumFor
   } = useChart('SankeyChart.Labels');
-  if (status === 'loading' || !layout.nodes.length) return null;
-  const format = formatValue ?? (value => compactNumber(value));
+  const upright = orientation === 'horizontal';
+  const drawing = status !== 'loading' && layout.nodes.length > 0;
 
   /*
-   * Where the neighbouring columns sit, in points across the plot.
-   *
-   * A name's row needs a bound on both sides or it runs the width of the chart
-   * and covers every row it crosses — and since the rows are absolutely
-   * positioned siblings, the last one drawn takes the touch. That is a tap on
-   * one name selecting a node two columns away, which is worse than a small
-   * target because it is wrong rather than merely hard.
+   * Where every name goes, and which ones there is no room for, worked out
+   * once: the chart has to be told which names were drawn so its semantic list
+   * can carry the rest, and a second copy of the rule would be a second answer
+   * to the same question.
    */
-  const edges = [];
-  for (const placed of layout.nodes) {
-    if (!edges.includes(placed.x0)) edges.push(placed.x0);
-    if (!edges.includes(placed.x1)) edges.push(placed.x1);
-  }
-  edges.sort((a, b) => a - b);
-  const nextEdge = x => edges.find(edge => edge > x + 1e-6);
-  const previousEdge = x => {
-    let found;
-    for (const edge of edges) if (edge < x - 1e-6) found = edge;
-    return found;
-  };
-  return /*#__PURE__*/_jsx(_Fragment, {
-    children: layout.nodes.map(node => {
-      const datum = nodes[node.index];
-      if (!datum) return null;
-      const extent = node.y1 - node.y0;
-      if (extent < minHeight) return null;
+  const placements = useMemo(() => {
+    if (!drawing) return [];
+
+    // Along the flow is the axis the stages advance on; across it is the axis
+    // carrying the values. Which is horizontal swaps with the orientation.
+    const alongStart = node => upright ? node.x0 : node.y0;
+    const alongEnd = node => upright ? node.x1 : node.y1;
+    const crossStart = node => upright ? node.y0 : node.x0;
+    const crossEnd = node => upright ? node.y1 : node.x1;
+    const alongSpan = upright ? width : height;
+    const crossSpan = upright ? height : width;
+
+    /*
+     * Where the neighbouring stages sit along the flow.
+     *
+     * A name's box needs a bound on both sides or it runs the length of the
+     * chart and covers every stage it crosses — and since the boxes are
+     * absolutely positioned siblings, the last one drawn takes the touch. That
+     * is a tap on one name selecting a node two stages away, which is worse
+     * than a small target because it is wrong rather than merely hard.
+     */
+    const edges = [];
+    for (const placed of layout.nodes) {
+      if (!edges.includes(alongStart(placed))) edges.push(alongStart(placed));
+      if (!edges.includes(alongEnd(placed))) edges.push(alongEnd(placed));
+    }
+    edges.sort((a, b) => a - b);
+    const placed = layout.nodes.map(node => {
+      const extent = crossEnd(node) - crossStart(node);
+      const after = edges.find(edge => edge > alongEnd(node) + 1e-6);
+      const before = edges.filter(edge => edge < alongStart(node) - 1e-6).pop();
+      const trailing = after === undefined;
 
       /*
-       * Which side the name goes on is decided by where the bar actually is,
-       * not by which column it belongs to. Under a right-to-left layout the
-       * finished diagram is mirrored, so the last column is the one on the
-       * left — reading the side off the column number there puts every name
-       * in a box of zero width and the chart loses all of them.
+       * The box along the flow: the half of the gap nearest its own bar, so
+       * the name leaving one stage and the name arriving at the next can share
+       * the space between them without sharing a touch target.
        */
-      const after = nextEdge(node.x1);
-      const before = previousEdge(node.x0);
-      const trailing = after === undefined;
+      const gap = trailing ? (() => {
+        const from = before === undefined ? 0 : (before + alongStart(node)) / 2;
+        return {
+          from,
+          size: Math.max(0, alongStart(node) - LABEL_GAP - from)
+        };
+      })() : (() => {
+        const from = alongEnd(node) + LABEL_GAP;
+        const to = after === undefined ? alongSpan : (alongEnd(node) + after) / 2;
+        return {
+          from,
+          size: Math.max(0, to - from)
+        };
+      })();
+
+      // And across it: the bar's own run, clamped inside the plot.
+      let crossFrom = Math.max(0, Math.min(crossStart(node), crossSpan - extent));
+      let crossSize = extent;
+
+      /*
+       * Along the flow the test is the bar's own run: forty names on forty
+       * hairlines overlap into a grey band that hides the flow behind it.
+       * Across it, where the flow runs downwards, whether a name fits is
+       * decided below, once every name in the row is known.
+       */
+      const show = extent >= minHeight;
+      return {
+        node,
+        show,
+        trailing,
+        gap,
+        crossFrom,
+        crossSize,
+        extent
+      };
+    });
+    if (!upright) {
+      /*
+       * Where the flow runs downwards a name sits across its bar, and a bar is
+       * as wide as its value — so a stage worth a few percent has a bar
+       * narrower than its own name. Squeezing the name into it gives "Groce…",
+       * which is cut off rather than shown.
+       *
+       * So a name is laid out at its own width, centred on its bar, and the
+       * row is filled from its largest stage down. A name may run over a
+       * neighbour's bar when that neighbour is not using the room — and where
+       * it would collide with a name already placed it slides clear, as long
+       * as it still sits over its own bar. A name that cannot be shown whole
+       * is not shown at all; the legend and the breakdown carry it, and its
+       * bar is still pressable.
+       */
+      const taken = new Map();
+      const order = [...placed].sort((a, b) => b.node.value - a.node.value);
+      for (const entry of order) {
+        if (!entry.show) continue;
+        const centre = (entry.node.x0 + entry.node.x1) / 2;
+        const size = Math.min(crossSpan, Math.max(entry.extent, nameWidth(labelFor(entry.node.id))));
+        const boxes = taken.get(entry.node.layer) ?? [];
+
+        // The free stretch of the row around this bar's centre.
+        let lo = 0;
+        let hi = crossSpan;
+        for (const [a, b] of boxes) {
+          if (b <= centre) lo = Math.max(lo, b + LABEL_GAP);else if (a >= centre) hi = Math.min(hi, a - LABEL_GAP);else {
+            lo = hi = centre;
+          }
+        }
+        if (hi - lo < size) {
+          entry.show = false;
+          continue;
+        }
+        // Centred where it can be, slid clear where it cannot, and never so
+        // far that it stops sitting over the bar it names.
+        const from = Math.max(lo, Math.min(centre - size / 2, hi - size));
+        if (centre < from || centre > from + size) {
+          entry.show = false;
+          continue;
+        }
+        boxes.push([from, from + size]);
+        taken.set(entry.node.layer, boxes);
+        entry.crossFrom = from;
+        entry.crossSize = size;
+      }
+      return placed;
+    }
+
+    /*
+     * Across the flow, an upright name is a line of text centred on a bar that
+     * may be thinner than the line. Where two such bars sit close together
+     * their names run into each other and both come out unreadable — which is
+     * worse than one of them being missing. So each column keeps names from
+     * its largest node down, and a name whose line would touch one already
+     * kept is left off. The node keeps its pressable bar, its place in the
+     * accessibility list and its entry in the legend.
+     */
+    const lineHeight = showValue ? LABEL_LINE * 2 : LABEL_LINE;
+    const kept = new Map();
+    const order = [...placed].sort((a, b) => b.node.value - a.node.value);
+    for (const entry of order) {
+      if (!entry.show) continue;
+      const centre = (entry.node.y0 + entry.node.y1) / 2;
+      const size = Math.max(entry.extent, lineHeight);
+      const from = Math.max(0, Math.min(centre - size / 2, height - size));
+      const to = from + size;
+      const key = `${entry.node.layer}:${entry.trailing ? 'end' : 'start'}`;
+      const taken = kept.get(key) ?? [];
+      if (taken.some(([a, b]) => from < b && to > a)) {
+        entry.show = false;
+        continue;
+      }
+      taken.push([from, to]);
+      kept.set(key, taken);
+      entry.crossFrom = from;
+      entry.crossSize = size;
+    }
+    return placed;
+  }, [drawing, layout.nodes, width, height, upright, minHeight, showValue, labelFor]);
+  const drawn = useMemo(() => drawing ? placements.filter(p => p.show).map(p => p.node.id) : null, [drawing, placements]);
+  useEffect(() => {
+    reportLabelled(drawn);
+    return () => reportLabelled(null);
+  }, [drawn, reportLabelled]);
+  if (!drawing) return null;
+  const format = formatValue ?? (value => compactNumber(value));
+  return /*#__PURE__*/_jsx(_Fragment, {
+    children: placements.map(({
+      node,
+      show,
+      trailing,
+      gap,
+      crossFrom,
+      crossSize
+    }) => {
+      if (!show) return null;
       const name = labelFor(node.id);
-      const value = format(node.value, datum);
+      const value = format(node.value, datumFor(node));
       const selected = activeId === node.id;
 
       /*
-       * A sliver's row is padded out to a real target rather than drawn
-       * taller — growing the row would push it over its neighbours, and two
-       * overlapping targets are worse than a small one.
+       * A sliver's box is padded out to a real target rather than drawn
+       * longer — growing it would push it over its neighbours, and two
+       * overlapping targets are worse than one small one.
        */
-      const slack = Math.max(0, (MIN_TARGET - extent) / 2);
-      const top = Math.max(0, Math.min(node.y0, height - extent));
-      return /*#__PURE__*/_jsxs(Pressable, {
+      const slack = Math.max(0, (MIN_TARGET - crossSize) / 2);
+      const align = upright ? trailing ? 'right' : 'left' : 'center';
+      return /*#__PURE__*/_jsx(Pressable, {
         accessibilityRole: "button",
         accessibilityState: {
           selected
         },
         accessibilityLabel: `${name}, ${value}`,
-        hitSlop: {
+        hitSlop: upright ? {
           top: slack,
           bottom: slack
+        } : {
+          left: slack,
+          right: slack
         },
         onPress: () => setActiveId(selected ? null : node.id),
         style: {
           position: 'absolute',
-          top,
-          height: extent,
-          justifyContent: 'center',
-          /*
-           * Each row takes the half of its gap nearest its own bar, so the
-           * name leaving one column and the name arriving at the next can
-           * share the space between them without sharing a touch target.
-           */
-          ...(trailing ? (() => {
-            const from = before === undefined ? 0 : (before + node.x0) / 2;
-            return {
-              left: from,
-              width: Math.max(0, node.x0 - LABEL_GAP - from),
-              alignItems: 'flex-end'
-            };
-          })() : (() => {
-            const from = node.x1 + LABEL_GAP;
-            const to = after === undefined ? width : (node.x1 + after) / 2;
-            return {
-              left: from,
-              width: Math.max(0, to - from)
-            };
-          })())
+          ...(upright ? {
+            top: crossFrom,
+            height: crossSize,
+            left: gap.from,
+            width: gap.size,
+            justifyContent: 'center',
+            alignItems: trailing ? 'flex-end' : 'flex-start'
+          } : {
+            left: crossFrom,
+            width: crossSize,
+            top: gap.from,
+            height: gap.size,
+            alignItems: 'center',
+            // Against the bar rather than centred in the gap, so the
+            // name sits with what it names instead of floating in the
+            // middle of the ribbons.
+            justifyContent: trailing ? 'flex-end' : 'flex-start'
+          })
         },
         className: cn(className),
-        children: [/*#__PURE__*/_jsx(Text, {
-          size: "xs",
-          weight: selected ? 'bold' : 'medium',
-          numberOfLines: 1,
-          style: {
-            textAlign: trailing ? 'right' : 'left'
-          },
-          children: name
-        }), showValue ? /*#__PURE__*/_jsx(Text, {
-          size: "xs",
-          muted: true,
-          numberOfLines: 1,
-          style: {
-            textAlign: trailing ? 'right' : 'left'
-          },
-          children: value
-        }) : null]
+        children: /*#__PURE__*/_jsxs(View, {
+          className: "max-w-full rounded-md bg-background/80 px-1.5 py-0.5",
+          children: [/*#__PURE__*/_jsx(Text, {
+            size: "xs",
+            weight: selected ? 'bold' : 'medium',
+            numberOfLines: 1,
+            style: {
+              textAlign: align
+            },
+            children: name
+          }), showValue ? /*#__PURE__*/_jsx(Text, {
+            size: "xs",
+            muted: true,
+            numberOfLines: 1,
+            style: {
+              textAlign: align
+            },
+            children: value
+          }) : null]
+        })
       }, node.id);
     })
   });
@@ -763,7 +1175,8 @@ function SankeyChartTooltip({
     layout,
     width,
     height,
-    labelFor
+    labelFor,
+    orientation
   } = useChart('SankeyChart.Tooltip');
   const {
     activeId,
@@ -776,16 +1189,33 @@ function SankeyChartTooltip({
   if (!node) return null;
   const format = formatValue ?? compactNumber;
   const CARD = 132;
-  const trailing = node.x1 + LABEL_GAP + CARD > width;
-  const left = trailing ? Math.max(0, node.x0 - LABEL_GAP - CARD) : Math.min(node.x1 + LABEL_GAP, Math.max(0, width - CARD));
-  const centre = (node.y0 + node.y1) / 2;
+  const HALF = 34;
+  const upright = orientation === 'horizontal';
+
+  /*
+   * Beside the bar on the axis the flow advances along, and level with its
+   * middle on the other — then clamped into the plot at both ends, so a node
+   * at an edge gets a card that is still entirely on the chart. It flips to
+   * the near side when there is no room on the far one, which is what keeps a
+   * last-stage node's card off the edge rather than half over it.
+   */
+  const alongEnd = upright ? node.x1 : node.y1;
+  const alongStart = upright ? node.x0 : node.y0;
+  const alongSpan = upright ? width : height;
+  const cardAlong = upright ? CARD : HALF * 2;
+  const trailing = alongEnd + LABEL_GAP + cardAlong > alongSpan;
+  const along = trailing ? Math.max(0, alongStart - LABEL_GAP - cardAlong) : Math.min(alongEnd + LABEL_GAP, Math.max(0, alongSpan - cardAlong));
+  const crossCentre = upright ? (node.y0 + node.y1) / 2 : (node.x0 + node.x1) / 2;
+  const crossSpan = upright ? height : width;
+  const cardCross = upright ? HALF * 2 : CARD;
+  const cross = Math.max(0, Math.min(crossCentre - cardCross / 2, crossSpan - cardCross));
   return /*#__PURE__*/_jsxs(View, {
     pointerEvents: "none",
     style: {
       position: 'absolute',
-      left,
       width: CARD,
-      top: Math.max(0, Math.min(centre - 34, height - 68))
+      left: upright ? along : cross,
+      top: upright ? cross : along
     },
     className: cn('gap-0.5 rounded-lg border border-border bg-background px-2.5 py-2 shadow-sm', className),
     children: [/*#__PURE__*/_jsx(Text, {
@@ -808,6 +1238,201 @@ function SankeyChartTooltip({
 }
 SankeyChartTooltip.displayName = 'SankeyChart.Tooltip';
 SankeyChartTooltip.slot = 'overlay';
+/**
+ * What the selected node carries, written out in full underneath the diagram.
+ *
+ * The names on a flow diagram live in the gaps between its stages, which on a
+ * phone is a few dozen points — wide enough to truncate almost anything. Here
+ * there is the whole width of the card, so a stream is read as the name of
+ * where it came from and the number it carried rather than as a ribbon whose
+ * label ran out of room.
+ *
+ * In and out are listed separately because they are only the same total when
+ * nothing was lost on the way through, and a node where they differ is the
+ * interesting one on the chart.
+ */
+function SankeyChartBreakdown({
+  className,
+  formatValue,
+  maxRows,
+  onSelectNode,
+  placeholder = 'Select a stage to see what it carries',
+  ...props
+}) {
+  const {
+    status,
+    setActiveId,
+    labelFor
+  } = useChart('SankeyChart.Breakdown');
+  const {
+    activeId,
+    activeValue,
+    sources,
+    targets
+  } = useSankeyChart();
+  if (status === 'loading') return null;
+  const format = formatValue ?? compactNumber;
+  const limit = maxRows && maxRows > 0 ? Math.floor(maxRows) : undefined;
+  if (!activeId) {
+    return /*#__PURE__*/_jsx(View, {
+      ...props,
+      className: cn('w-full pt-3', className),
+      children: /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        muted: true,
+        children: placeholder
+      })
+    });
+  }
+  const side = (title, rows) => {
+    if (!rows.length) return null;
+    const shown = limit ? rows.slice(0, limit) : rows;
+    const rest = rows.length - shown.length;
+    return /*#__PURE__*/_jsxs(View, {
+      className: "w-full gap-1",
+      children: [/*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        muted: true,
+        weight: "medium",
+        children: title
+      }), shown.map(row => /*#__PURE__*/_jsxs(Pressable, {
+        accessibilityRole: "button",
+        accessibilityLabel: `${row.label}, ${format(row.value)}, ${Math.round(row.share * 100)} percent`,
+        onPress: () => {
+          setActiveId(row.id);
+          onSelectNode?.(row.id);
+        },
+        className: "w-full flex-row items-center gap-2 py-1",
+        children: [/*#__PURE__*/_jsx(View, {
+          style: {
+            width: 8,
+            height: 8,
+            borderRadius: 2,
+            backgroundColor: row.color
+          }
+        }), /*#__PURE__*/_jsx(Text, {
+          size: "xs",
+          numberOfLines: 1,
+          className: "shrink grow",
+          children: row.label
+        }), /*#__PURE__*/_jsx(Text, {
+          size: "xs",
+          weight: "medium",
+          numberOfLines: 1,
+          children: format(row.value)
+        }), /*#__PURE__*/_jsx(Text, {
+          size: "xs",
+          muted: true,
+          numberOfLines: 1,
+          className: "w-10 text-right",
+          children: `${Math.round(row.share * 100)}%`
+        })]
+      }, `${title}-${row.id}`)), rest > 0 ? /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        muted: true,
+        children: `and ${rest} more`
+      }) : null]
+    });
+  };
+  return /*#__PURE__*/_jsxs(View, {
+    ...props,
+    className: cn('w-full gap-2 pt-3', className),
+    children: [/*#__PURE__*/_jsxs(View, {
+      className: "w-full flex-row items-baseline justify-between gap-2",
+      children: [/*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        weight: "bold",
+        numberOfLines: 1,
+        className: "shrink",
+        children: labelFor(activeId)
+      }), /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        weight: "semibold",
+        children: format(activeValue)
+      })]
+    }), side('In', sources), side('Out', targets)]
+  });
+}
+SankeyChartBreakdown.displayName = 'SankeyChart.Breakdown';
+SankeyChartBreakdown.slot = 'footer';
+/**
+ * Every stage named, under the diagram.
+ *
+ * The names on the chart are dropped wherever a bar is too short to carry one,
+ * which is the right call — forty names at that spacing overlap into a grey
+ * band that hides the flow behind them — but it leaves the smallest nodes with
+ * no name and nothing to press. Here each one gets its full name and a proper
+ * target, and pressing it selects the same node the bar would.
+ */
+function SankeyChartLegend({
+  className,
+  limit,
+  showShare = true,
+  ...props
+}) {
+  const {
+    layout,
+    colors,
+    status,
+    activeId,
+    setActiveId,
+    labelFor
+  } = useChart('SankeyChart.Legend');
+  if (status === 'loading' || !layout.nodes.length) return null;
+
+  // Against the widest stage rather than the sum of every node, which counts
+  // whatever passes through a middle stage twice and makes every share small.
+  let total = 0;
+  const byLayer = new Map();
+  for (const node of layout.nodes) {
+    const carried = (byLayer.get(node.layer) ?? 0) + node.value;
+    byLayer.set(node.layer, carried);
+    if (carried > total) total = carried;
+  }
+  const shown = limit && limit > 0 ? layout.nodes.slice(0, Math.floor(limit)) : layout.nodes;
+  return /*#__PURE__*/_jsx(View, {
+    ...props,
+    className: cn('w-full flex-row flex-wrap items-center gap-x-3 gap-y-1.5 pt-3', className),
+    children: shown.map((node, index) => {
+      const percent = total > 0 ? Math.round(node.value / total * 100) : 0;
+      const selected = activeId === node.id;
+      const dimmed = activeId !== null && !selected;
+      return /*#__PURE__*/_jsxs(Pressable, {
+        accessibilityRole: "button",
+        accessibilityState: {
+          selected
+        },
+        accessibilityLabel: `${labelFor(node.id)}, ${percent} percent`,
+        onPress: () => setActiveId(selected ? null : node.id),
+        style: {
+          opacity: dimmed ? 0.4 : 1
+        },
+        className: "max-w-full flex-row items-center gap-1.5",
+        children: [/*#__PURE__*/_jsx(View, {
+          style: {
+            width: 8,
+            height: 8,
+            borderRadius: 2,
+            backgroundColor: colors[index] ?? '#3b82f6'
+          }
+        }), /*#__PURE__*/_jsx(Text, {
+          size: "xs",
+          muted: true,
+          numberOfLines: 1,
+          className: "shrink",
+          children: labelFor(node.id)
+        }), showShare ? /*#__PURE__*/_jsx(Text, {
+          size: "xs",
+          weight: "medium",
+          numberOfLines: 1,
+          children: `${percent}%`
+        }) : null]
+      }, node.id);
+    })
+  });
+}
+SankeyChartLegend.displayName = 'SankeyChart.Legend';
+SankeyChartLegend.slot = 'footer';
 /**
  * The loading state: a few plain bars and the ribbons between them, carrying no
  * values.
@@ -825,7 +1450,8 @@ function SankeyChartSkeleton({
     width,
     height,
     curve,
-    status
+    status,
+    orientation
   } = useChart('SankeyChart.Skeleton');
   const token = useCSSVariable('--color-skeleton');
   const fill = color ?? (typeof token === 'string' ? token : 'rgba(128,128,128,0.2)');
@@ -840,28 +1466,36 @@ function SankeyChartSkeleton({
   const animatedProps = useAnimatedProps(() => ({
     opacity: opacity.value
   }));
+  const upright = orientation === 'horizontal';
   const shape = useMemo(() => {
     if (width <= 0 || height <= 0) return null;
+    // The placeholder is the diagram's own shape, turned the same way: a
+    // waiting state that does not match what replaces it moves the whole card
+    // at the moment the data lands.
+    const along = upright ? width : height;
+    const cross = upright ? height : width;
     const bar = DEFAULT_NODE_WIDTH;
-    const step = (width - bar) / Math.max(SKELETON_COLUMNS - 1, 1);
-    const band = height / 3;
+    const step = (along - bar) / Math.max(SKELETON_COLUMNS - 1, 1);
+    const band = cross / 3;
     const columns = Array.from({
       length: SKELETON_COLUMNS
     }, (_, i) => i * step);
+    const path = upright ? flowPath : flowPathVertical;
     const ribbons = [];
     for (let i = 0; i < SKELETON_COLUMNS - 1; i += 1) {
       const from = columns[i] + bar;
       const to = columns[i + 1];
-      ribbons.push(flowPath(from, height / 3, to, height / 3, band * 0.5, curve));
-      ribbons.push(flowPath(from, height * 2 / 3, to, height * 2 / 3, band * 0.5, curve));
+      ribbons.push(path(from, cross / 3, to, cross / 3, band * 0.5, curve));
+      ribbons.push(path(from, cross * 2 / 3, to, cross * 2 / 3, band * 0.5, curve));
     }
     return {
       bar,
       band,
       columns,
-      ribbons
+      ribbons,
+      cross
     };
-  }, [width, height, curve]);
+  }, [width, height, curve, upright]);
   if (!mounted || !shape) return null;
   return /*#__PURE__*/_jsxs(AnimatedG, {
     animatedProps: animatedProps,
@@ -869,11 +1503,11 @@ function SankeyChartSkeleton({
       d: d,
       fill: fill,
       fillOpacity: 0.5
-    }, `ribbon-${index}`)), shape.columns.map((x, index) => /*#__PURE__*/_jsx(Rect, {
-      x: x,
-      y: height / 6,
-      width: shape.bar,
-      height: height * 2 / 3,
+    }, `ribbon-${index}`)), shape.columns.map((at, index) => /*#__PURE__*/_jsx(Rect, {
+      x: upright ? at : shape.cross / 6,
+      y: upright ? shape.cross / 6 : at,
+      width: upright ? shape.bar : shape.cross * 2 / 3,
+      height: upright ? shape.cross * 2 / 3 : shape.bar,
       rx: 2,
       fill: fill
     }, `bar-${index}`))]
@@ -923,6 +1557,8 @@ function SankeyChartHeader({
 SankeyChartHeader.displayName = 'SankeyChart.Header';
 SankeyChartHeader.slot = 'header';
 export const SankeyChart = Object.assign(SankeyChartRoot, {
+  Breakdown: SankeyChartBreakdown,
+  Legend: SankeyChartLegend,
   Header: SankeyChartHeader,
   Links: SankeyChartLinks,
   Nodes: SankeyChartNodes,