panelui-native 0.63.0 → 0.65.0

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

@@ -0,0 +1,1325 @@
+"use strict";
+
+/**
+ * WaterfallChart — how a run of changes carried one total to another.
+ *
+ * Composed the same way the other charts are: the grid, the bars, the
+ * connectors, the axes and the readout are separate children, so a chart that
+ * wants no grid simply does not have one.
+ *
+ * ```tsx
+ * <WaterfallChart data={bridge}>
+ *   <WaterfallChart.Grid />
+ *   <WaterfallChart.Connectors />
+ *   <WaterfallChart.Bars />
+ *   <WaterfallChart.XAxis />
+ *   <WaterfallChart.Tooltip />
+ * </WaterfallChart>
+ * ```
+ *
+ * ## What the shape is asserting
+ *
+ * **Every bar but a total floats.** A step's bar starts where the previous one
+ * ended and reaches as far as its own value carries it, so the gap under it is
+ * the running total it is acting on. That floating is the entire point: a bar
+ * chart of the same numbers would compare the changes against each other, and
+ * this compares each of them against the balance it moved.
+ *
+ * **A total is anchored to zero.** It is a reading rather than a change, so it
+ * is measured from the baseline like an ordinary bar and drawn in a neutral
+ * colour. Marking the opening and closing steps `total` is what gives the run
+ * two ends to be a bridge between.
+ *
+ * **Three colours, and no more.** Up, down, and total. A fourth would have to
+ * mean something the reader has to be told, and the one thing this chart has
+ * going for it is that the direction of a bar is legible before its label is.
+ *
+ * **The connectors are the sequence.** Without them the bars are a row of
+ * floating rectangles at unexplained heights; the line from one bar's end to
+ * the next bar's start is what says the second continues the first.
+ */
+import { Children, createContext, forwardRef, isValidElement, useContext, useEffect, useImperativeHandle, useMemo, useRef, useState } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { Gesture, GestureDetector } from 'react-native-gesture-handler';
+import Animated, { Easing, cancelAnimation, runOnJS, useAnimatedProps, useAnimatedStyle, useReducedMotion, useSharedValue, withRepeat, withTiming } from 'react-native-reanimated';
+import Svg, { Defs, G, Line as SvgLine, LinearGradient, Path, Stop } from 'react-native-svg';
+import { useCSSVariable } from 'uniwind';
+import { Text } from "../../primitives/text.js";
+import { barPath, compactNumber } from "../../utils/chart.js";
+import { cn } from "../../utils/cn.js";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+const AnimatedPath = Animated.createAnimatedComponent(Path);
+const AnimatedLinearGradient = Animated.createAnimatedComponent(LinearGradient);
+
+/** Room left around the plot for the axis labels. */
+const PADDING = {
+  top: 12,
+  right: 10,
+  bottom: 22,
+  left: 10
+};
+
+/**
+ * Sideways, the step names run down the left instead of along the bottom, so
+ * the room has to come off that side. Reserved rather than overlaid: a name
+ * drawn on top of the bars is unreadable against them and makes the bars
+ * unreadable too.
+ */
+const PADDING_SIDEWAYS = {
+  top: 6,
+  right: 10,
+  bottom: 6,
+  left: 76
+};
+
+/** Width the readout is laid out at, so it can be clamped inside the plot. */
+const LABEL_WIDTH = 148;
+
+/** Left gutter reserved when a `YAxis` is present, for its labels to sit in. */
+const Y_AXIS_WIDTH = 44;
+
+/** Line height of an `xs` label, for centring one on the grid line it names. */
+const AXIS_LABEL_HEIGHT = 16;
+
+/** Fallbacks, only reached if the theme CSS was never imported. */
+const FALLBACK_RISE = '#10b981';
+const FALLBACK_FALL = '#ef4444';
+const FALLBACK_TOTAL = '#262626';
+
+/** Which of the three roles a step's bar is drawn in. */
+
+/** One step, resolved against the running total it acts on. */
+
+const WaterfallChartContext = /*#__PURE__*/createContext(null);
+function useChart(component) {
+  const context = useContext(WaterfallChartContext);
+  if (!context) {
+    throw new Error(`${component} must be used within a <WaterfallChart>`);
+  }
+  return context;
+}
+
+/**
+ * The step under the finger, for something rendered *inside* the chart. A
+ * readout in the card's header is outside this provider — use
+ * `onActiveIndexChange` for that.
+ */
+export function useWaterfallChart() {
+  const {
+    steps,
+    activeIndexJS
+  } = useChart('useWaterfallChart');
+  return {
+    activeIndex: activeIndexJS,
+    activeStep: activeIndexJS >= 0 ? steps[activeIndexJS] ?? null : null
+  };
+}
+
+/**
+ * The running totals every step sits on.
+ *
+ * Split out because it is the one piece of the chart that is pure arithmetic
+ * over the data, and every part that draws anything needs the same answer —
+ * two parts deriving it separately is two chances for the bars and the
+ * connectors to disagree about where a step ended.
+ */
+export function waterfallSteps(data) {
+  const steps = [];
+  let running = 0;
+  for (const datum of data) {
+    const value = typeof datum.value === 'number' && !Number.isNaN(datum.value) ? datum.value : 0;
+    if (datum.total) {
+      // A total is a reading, so it is measured from the baseline and the
+      // running figure becomes whatever it reads.
+      running += value;
+      steps.push({
+        datum,
+        label: datum.label,
+        value: running,
+        kind: 'total',
+        start: 0,
+        end: running
+      });
+      continue;
+    }
+    const start = running;
+    running += value;
+    steps.push({
+      datum,
+      label: datum.label,
+      value,
+      kind: value < 0 ? 'fall' : 'rise',
+      start,
+      end: running
+    });
+  }
+  return steps;
+}
+
+/** Imperative handle: re-run the grow-in, for a "replay" control. */
+
+function partition(children) {
+  const svg = [];
+  const overlay = [];
+  const header = [];
+  Children.forEach(children, (child, index) => {
+    if (! /*#__PURE__*/isValidElement(child)) return;
+    const layer = child.type.layer ?? 'svg';
+    const slot = /*#__PURE__*/_jsx(ChildSlot, {
+      children: child
+    }, index);
+    (layer === 'header' ? header : layer === 'overlay' ? overlay : svg).push(slot);
+  });
+  return {
+    svg,
+    overlay,
+    header
+  };
+}
+function ChildSlot({
+  children
+}) {
+  return /*#__PURE__*/_jsx(_Fragment, {
+    children: children
+  });
+}
+const WaterfallChartRoot = /*#__PURE__*/forwardRef(function WaterfallChartRoot({
+  className,
+  data,
+  status = 'ready',
+  aspectRatio = 2,
+  animationDuration = 700,
+  domainDuration = 500,
+  yDomain,
+  orientation = 'vertical',
+  barGap = 0.34,
+  barWidth,
+  cornerRadius = 4,
+  minBarLength = 2,
+  fadedOpacity = 0.3,
+  riseColor,
+  fallColor,
+  totalColor,
+  onActiveIndexChange,
+  compact = false,
+  children,
+  ...props
+}, ref) {
+  const [size, setSize] = useState({
+    width: 0,
+    height: 0
+  });
+  const [activeIndexJS, setActiveIndexJS] = useState(-1);
+  const reveal = useSharedValue(0);
+  const domainMin = useSharedValue(0);
+  const domainMax = useSharedValue(0);
+  const activeIndex = useSharedValue(-1);
+  const reducedMotion = useReducedMotion();
+  const riseToken = useCSSVariable('--color-success');
+  const fallToken = useCSSVariable('--color-destructive');
+  const totalToken = useCSSVariable('--color-chart-1');
+  const colors = useMemo(() => ({
+    rise: riseColor ?? (typeof riseToken === 'string' ? riseToken : FALLBACK_RISE),
+    fall: fallColor ?? (typeof fallToken === 'string' ? fallToken : FALLBACK_FALL),
+    total: totalColor ?? (typeof totalToken === 'string' ? totalToken : FALLBACK_TOTAL)
+  }), [riseColor, fallColor, totalColor, riseToken, fallToken, totalToken]);
+  const steps = useMemo(() => waterfallSteps(data), [data]);
+
+  /*
+   * Whether an axis is asking for room. It has to be known before the plot is
+   * laid out, and only the root sees the children early enough to ask — the
+   * axis itself renders into a box that has already been decided.
+   */
+  const hasYAxis = useMemo(() => {
+    let found = false;
+    Children.forEach(children, child => {
+      if (/*#__PURE__*/isValidElement(child) && child.type.axis === 'y') {
+        found = true;
+      }
+    });
+    return found;
+  }, [children]);
+  const pad = compact ? {
+    top: 2,
+    right: 1,
+    bottom: 2,
+    left: 1
+  } : orientation === 'horizontal' ? PADDING_SIDEWAYS : {
+    ...PADDING,
+    left: hasYAxis ? Y_AXIS_WIDTH : PADDING.left
+  };
+  const plot = {
+    left: pad.left,
+    top: pad.top,
+    width: Math.max(size.width - pad.left - pad.right, 0),
+    height: Math.max(size.height - pad.top - pad.bottom, 0)
+  };
+  const extent = useMemo(() => {
+    if (yDomain) return yDomain;
+
+    /*
+     * Both ends of every bar, not just the values. A step's bar occupies the
+     * span between two running totals, and a domain taken from the changes
+     * alone would be the range of the *deltas* — which on any run that
+     * climbs before it falls is a fraction of the height the bars need.
+     */
+    let min = 0;
+    let max = 0;
+    for (const step of steps) {
+      const low = Math.min(step.start, step.end);
+      const high = Math.max(step.start, step.end);
+      if (low < min) min = low;
+      if (high > max) max = high;
+    }
+    if (min === 0 && max === 0) return [0, 1];
+    // Headroom past the furthest bar only. The zero end is left exactly where
+    // it is: padding it would lift the run off its own baseline.
+    return [min === 0 ? 0 : min * 1.1, max === 0 ? 0 : max * 1.1];
+  }, [steps, yDomain]);
+  const loading = status === 'loading';
+  useEffect(() => {
+    if (loading) return;
+    const [min, max] = extent;
+    const first = domainMin.value === 0 && domainMax.value === 0;
+    if (first || reducedMotion) {
+      domainMin.value = min;
+      domainMax.value = max;
+      return;
+    }
+    domainMin.value = withTiming(min, {
+      duration: domainDuration
+    });
+    domainMax.value = withTiming(max, {
+      duration: domainDuration
+    });
+  }, [extent, loading, reducedMotion, domainDuration, domainMin, domainMax]);
+  const revealed = useRef(false);
+  const playReveal = useMemo(() => () => {
+    if (reducedMotion) {
+      reveal.value = 1;
+      return;
+    }
+    reveal.value = 0;
+    reveal.value = withTiming(1, {
+      duration: animationDuration,
+      easing: Easing.out(Easing.cubic)
+    });
+  }, [reducedMotion, animationDuration, reveal]);
+  useEffect(() => {
+    /*
+     * Going back to `loading` arms the reveal again. Without this a chart that
+     * is refetched comes back fully drawn on the frame the data lands, which
+     * reads as the loading state having been for nothing.
+     */
+    if (loading) {
+      revealed.current = false;
+      reveal.value = 0;
+      return;
+    }
+    if (revealed.current || plot.width <= 0 || !steps.length) return;
+    revealed.current = true;
+    playReveal();
+  }, [loading, plot.width, steps.length, playReveal, reveal]);
+  useImperativeHandle(ref, () => ({
+    replay: playReveal
+  }), [playReveal]);
+  const handleActiveIndex = useMemo(() => index => {
+    setActiveIndexJS(index);
+    onActiveIndexChange?.(index, index >= 0 ? steps[index] ?? null : null);
+  }, [onActiveIndexChange, steps]);
+  const onLayout = event => {
+    const {
+      width,
+      height
+    } = event.nativeEvent.layout;
+    setSize(current => Math.abs(current.width - width) < 1 && Math.abs(current.height - height) < 1 ? current : {
+      width,
+      height
+    });
+    props.onLayout?.(event);
+  };
+  const context = useMemo(() => ({
+    data,
+    steps,
+    plot,
+    status,
+    orientation,
+    barGap,
+    barWidth,
+    cornerRadius,
+    minBarLength,
+    fadedOpacity,
+    colors,
+    domainMin,
+    domainMax,
+    extent,
+    reveal,
+    activeIndex,
+    activeIndexJS,
+    setActiveIndexJS: handleActiveIndex
+  }),
+  // `plot` is rebuilt every render from `size`, so it is compared by value.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  [data, steps, plot.width, plot.height, plot.left, plot.top, status, orientation, barGap, barWidth, cornerRadius, minBarLength, fadedOpacity, colors, domainMin, domainMax, extent, reveal, activeIndex, activeIndexJS, handleActiveIndex]);
+  const {
+    svg,
+    overlay,
+    header
+  } = partition(children);
+
+  /*
+   * Two views, because the header is not part of the plot. `aspectRatio` and
+   * the layout measurement belong to the drawing area alone — measured on the
+   * outer view they would take in the header too, and the plot would lose as
+   * much height as the readout took while still claiming the shape asked for.
+   */
+  return /*#__PURE__*/_jsx(WaterfallChartContext.Provider, {
+    value: context,
+    children: /*#__PURE__*/_jsxs(View, {
+      ...props,
+      style: props.style,
+      className: cn('w-full', className),
+      children: [header, /*#__PURE__*/_jsx(View, {
+        onLayout: onLayout,
+        style: {
+          aspectRatio
+        },
+        className: "w-full",
+        children: plot.width > 0 ? /*#__PURE__*/_jsxs(_Fragment, {
+          children: [/*#__PURE__*/_jsx(Svg, {
+            width: "100%",
+            height: "100%",
+            style: StyleSheet.absoluteFill,
+            children: svg
+          }), overlay]
+        }) : null
+      })]
+    })
+  });
+});
+WaterfallChartRoot.displayName = 'WaterfallChart';
+
+/* -------------------------------------------------------------------------- */
+/* Geometry                                                                   */
+/* -------------------------------------------------------------------------- */
+
+/** The band measurements every drawn part reads the same way. */
+
+/**
+ * How the plot divides between the steps.
+ *
+ * A worklet because the bars rebuild on the UI thread every frame the domain is
+ * tweening, and shared with the parts that only run on JS so a label and the
+ * bar it names can never land on different centres.
+ */
+function bandsOf(plot, total, horizontal, barGap, barWidth) {
+  'worklet';
+
+  const along = horizontal ? plot.height : plot.width;
+  const across = horizontal ? plot.width : plot.height;
+  const band = along / Math.max(1, total);
+  const usable = band * (1 - barGap);
+  return {
+    along,
+    across,
+    alongStart: horizontal ? plot.top : plot.left,
+    acrossStart: horizontal ? plot.left : plot.top,
+    band,
+    thickness: Math.min(barWidth ?? usable, usable)
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* SVG layer                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Lines across the value axis, so a bar can be read against a number rather
+ * than only against the bar beside it.
+ */
+function WaterfallChartGrid({
+  rows = 4,
+  color,
+  dashArray = '4,6',
+  opacity = 1
+}) {
+  const {
+    plot,
+    orientation
+  } = useChart('WaterfallChart.Grid');
+  const token = useCSSVariable('--color-border');
+  const stroke = color ?? (typeof token === 'string' ? token : 'rgba(0,0,0,0.1)');
+  const lines = Array.from({
+    length: rows + 1
+  }, (_unused, index) => index / rows);
+  return /*#__PURE__*/_jsx(G, {
+    opacity: opacity,
+    children: lines.map(fraction => orientation === 'vertical' ? /*#__PURE__*/_jsx(SvgLine, {
+      x1: plot.left,
+      x2: plot.left + plot.width,
+      y1: plot.top + plot.height * fraction,
+      y2: plot.top + plot.height * fraction,
+      stroke: stroke,
+      strokeDasharray: dashArray,
+      strokeWidth: 1
+    }, fraction) : /*#__PURE__*/_jsx(SvgLine, {
+      x1: plot.left + plot.width * fraction,
+      x2: plot.left + plot.width * fraction,
+      y1: plot.top,
+      y2: plot.top + plot.height,
+      stroke: stroke,
+      strokeDasharray: dashArray,
+      strokeWidth: 1
+    }, fraction))
+  });
+}
+WaterfallChartGrid.displayName = 'WaterfallChart.Grid';
+WaterfallChartGrid.layer = 'svg';
+/**
+ * The bars.
+ *
+ * Six animated paths a frame rather than one per step: one per role, so the
+ * three colours can be three fills, and each of those split into the bar under
+ * the finger and the rest, so the others can dim without every bar carrying its
+ * own opacity. A run of forty steps costs the same as a run of four.
+ *
+ * Each bar grows from its own `start` towards its `end` rather than up from the
+ * baseline. A step is a movement from one balance to another, and growing it
+ * from zero would animate a quantity the chart is not claiming.
+ */
+function WaterfallChartBars({
+  cornerRadius
+}) {
+  const {
+    steps,
+    plot,
+    status,
+    orientation,
+    barGap,
+    barWidth,
+    cornerRadius: chartRadius,
+    minBarLength,
+    fadedOpacity,
+    colors,
+    domainMin,
+    domainMax,
+    reveal,
+    activeIndex
+  } = useChart('WaterfallChart.Bars');
+  const radius = cornerRadius ?? chartRadius;
+  const loading = status === 'loading';
+  const total = steps.length;
+  const horizontal = orientation === 'horizontal';
+
+  /*
+   * All six paths come out of one builder, filtered by role and by whether the
+   * bar is the active one. Six passes over the data a frame is still cheaper
+   * than the bookkeeping needed to build them all at once, and it keeps the
+   * geometry in exactly one place.
+   */
+  const build = (kind, wantActive) => () => {
+    'worklet';
+
+    if (!total || plot.width <= 0) {
+      return {
+        d: '',
+        opacity: 1
+      };
+    }
+    const bands = bandsOf(plot, total, horizontal, barGap, barWidth);
+    const min = domainMin.value;
+    const max = domainMax.value;
+    const range = max - min || 1;
+    const grow = reveal.value;
+    const active = activeIndex.value;
+
+    /*
+     * Where a value sits along the value axis. Vertical counts down from the
+     * top, horizontal counts up from the left — the same scale read in
+     * opposite directions, which is the only thing orientation changes.
+     */
+    const project = value => {
+      'worklet';
+
+      const fraction = (value - min) / range;
+      return horizontal ? bands.acrossStart + fraction * bands.across : bands.acrossStart + bands.across - fraction * bands.across;
+    };
+    let d = '';
+    for (let i = 0; i < total; i++) {
+      const step = steps[i];
+      if (!step || step.kind !== kind) continue;
+      if (i === active !== wantActive) continue;
+
+      /*
+       * Staggered by step, but every bar still finishes inside the one
+       * duration: the window each gets is what is left after the stagger, so a
+       * run of forty steps does not take forty times as long to arrive.
+       */
+      const startAt = total > 1 ? i / total * 0.45 : 0;
+      const eased = Math.max(0, Math.min(1, (grow - startAt) / 0.55));
+      const reached = loading ? step.start : step.start + (step.end - step.start) * eased;
+      const from = project(step.start);
+      const to = project(reached);
+      let length = Math.abs(to - from);
+      // A step that rounds to nothing still happened, and a bar of zero length
+      // says it did not. Held back until the grow-in has actually started, so
+      // the stub does not appear before the bar it belongs to.
+      if (minBarLength > 0 && eased > 0 && !loading && length < minBarLength) {
+        length = minBarLength;
+      }
+      if (length <= 0) continue;
+      const lead = bands.alongStart + i * bands.band + (bands.band - bands.thickness) / 2;
+      // Which way the bar points is the direction of the change, not the sign
+      // of the value — a fall from 900 to 400 points down whatever those two
+      // numbers are, and a total always points away from the baseline.
+      const forward = reached >= step.start;
+      d += horizontal ? barPath(forward ? from : from - length, lead, length, bands.thickness, radius, forward ? 'right' : 'left') : barPath(lead, forward ? from - length : from, bands.thickness, length, radius, forward ? 'up' : 'down');
+    }
+
+    // Dimming only happens while something *is* active; with nothing under the
+    // finger every bar is at full ink, which is the resting state.
+    const dim = !wantActive && active >= 0 ? fadedOpacity : 1;
+    return {
+      d,
+      opacity: dim
+    };
+  };
+  const riseRest = useAnimatedProps(build('rise', false));
+  const riseActive = useAnimatedProps(build('rise', true));
+  const fallRest = useAnimatedProps(build('fall', false));
+  const fallActive = useAnimatedProps(build('fall', true));
+  const totalRest = useAnimatedProps(build('total', false));
+  const totalActive = useAnimatedProps(build('total', true));
+  return /*#__PURE__*/_jsxs(G, {
+    children: [/*#__PURE__*/_jsx(AnimatedPath, {
+      animatedProps: riseRest,
+      fill: colors.rise
+    }), /*#__PURE__*/_jsx(AnimatedPath, {
+      animatedProps: riseActive,
+      fill: colors.rise
+    }), /*#__PURE__*/_jsx(AnimatedPath, {
+      animatedProps: fallRest,
+      fill: colors.fall
+    }), /*#__PURE__*/_jsx(AnimatedPath, {
+      animatedProps: fallActive,
+      fill: colors.fall
+    }), /*#__PURE__*/_jsx(AnimatedPath, {
+      animatedProps: totalRest,
+      fill: colors.total
+    }), /*#__PURE__*/_jsx(AnimatedPath, {
+      animatedProps: totalActive,
+      fill: colors.total
+    })]
+  });
+}
+WaterfallChartBars.displayName = 'WaterfallChart.Bars';
+WaterfallChartBars.layer = 'svg';
+/**
+ * The lines from each bar's end to the next bar's start.
+ *
+ * Drawn under the bars, and reaching the full width of both bands rather than
+ * only the gap between them, so the ends are hidden behind the bars they touch
+ * and the line reads as passing behind the run instead of stopping short of it.
+ *
+ * They arrive with the reveal, each one held back until the bar on its left has
+ * finished growing — a connector drawn to a bar that is not there yet points at
+ * nothing.
+ */
+function WaterfallChartConnectors({
+  color,
+  dashArray = '3,4',
+  strokeWidth = 1,
+  opacity = 1
+}) {
+  const {
+    steps,
+    plot,
+    status,
+    orientation,
+    barGap,
+    barWidth,
+    domainMin,
+    domainMax,
+    reveal
+  } = useChart('WaterfallChart.Connectors');
+  const token = useCSSVariable('--color-muted-foreground');
+  const stroke = color ?? (typeof token === 'string' ? token : 'rgba(0,0,0,0.4)');
+  const total = steps.length;
+  const horizontal = orientation === 'horizontal';
+  const loading = status === 'loading';
+  const animatedProps = useAnimatedProps(() => {
+    'worklet';
+
+    if (total < 2 || plot.width <= 0 || loading) return {
+      d: ''
+    };
+    const bands = bandsOf(plot, total, horizontal, barGap, barWidth);
+    const min = domainMin.value;
+    const max = domainMax.value;
+    const range = max - min || 1;
+    const grow = reveal.value;
+    const project = value => {
+      'worklet';
+
+      const fraction = (value - min) / range;
+      return horizontal ? bands.acrossStart + fraction * bands.across : bands.acrossStart + bands.across - fraction * bands.across;
+    };
+    let d = '';
+    for (let i = 0; i < total - 1; i++) {
+      const step = steps[i];
+      if (!step) continue;
+
+      // The same window the bar on the left is growing in. The connector only
+      // starts once that bar has arrived at the level it is drawn at.
+      const startAt = total > 1 ? i / total * 0.45 : 0;
+      const eased = Math.max(0, Math.min(1, (grow - startAt) / 0.55));
+      if (eased <= 0) continue;
+      const level = project(step.end);
+      const from = bands.alongStart + i * bands.band + (bands.band - bands.thickness) / 2;
+      const to = bands.alongStart + (i + 2) * bands.band - (bands.band - bands.thickness) / 2;
+      // Extends as the next bar arrives, so the line and the bar it is
+      // reaching for grow together rather than the line waiting drawn.
+      const reach = from + (to - from) * eased;
+      d += horizontal ? `M${level},${from}L${level},${reach}` : `M${from},${level}L${reach},${level}`;
+    }
+    return {
+      d
+    };
+  });
+  if (total < 2) return null;
+  return /*#__PURE__*/_jsx(AnimatedPath, {
+    animatedProps: animatedProps,
+    stroke: stroke,
+    strokeWidth: strokeWidth,
+    strokeDasharray: dashArray,
+    strokeOpacity: opacity,
+    fill: "none"
+  });
+}
+WaterfallChartConnectors.displayName = 'WaterfallChart.Connectors';
+WaterfallChartConnectors.layer = 'svg';
+
+/** How much of the value axis a placeholder bar takes. */
+const SKELETON_LENGTH = 0.18;
+
+/** Steps to draw when there is no data yet to count them from. */
+const SKELETON_BARS = 6;
+/**
+ * The loading state: a row of short, equal stubs on the baseline, with a
+ * highlight travelling across them.
+ *
+ * Equal and on the baseline on purpose. Placeholder bars at differing heights
+ * are a run the reader has no way to tell from the real one until it changes
+ * under them, and floating them would invent a set of running totals — which is
+ * the one thing this chart exists to report.
+ */
+function WaterfallChartSkeleton({
+  bars,
+  duration = 1400,
+  color
+}) {
+  const {
+    plot,
+    status,
+    orientation,
+    steps,
+    barGap,
+    barWidth,
+    cornerRadius
+  } = useChart('WaterfallChart.Skeleton');
+  const token = useCSSVariable('--color-skeleton');
+  const base = color ?? (typeof token === 'string' ? token : 'rgba(128,128,128,0.2)');
+  const highlightToken = useCSSVariable('--color-chart-1');
+  const highlight = typeof highlightToken === 'string' ? highlightToken : FALLBACK_TOTAL;
+  const sweep = useSharedValue(0);
+  const reducedMotion = useReducedMotion();
+  const loading = status === 'loading';
+  useEffect(() => {
+    if (!loading || reducedMotion) {
+      cancelAnimation(sweep);
+      sweep.value = 0;
+      return;
+    }
+    sweep.value = 0;
+    sweep.value = withRepeat(withTiming(1, {
+      duration,
+      easing: Easing.linear
+    }), -1, false);
+    return () => cancelAnimation(sweep);
+  }, [loading, reducedMotion, duration, sweep]);
+
+  // The band travels by moving the gradient's own endpoints, so the whole
+  // effect is two numbers changing on the UI thread.
+  const animatedProps = useAnimatedProps(() => ({
+    x1: `${(sweep.value * 1.4 - 0.4) * 100}%`,
+    x2: `${(sweep.value * 1.4 - 0.4 + 0.4) * 100}%`
+  }));
+  const horizontal = orientation === 'horizontal';
+  const total = Math.max(1, bars ?? (steps.length || SKELETON_BARS));
+  const d = useMemo(() => {
+    if (plot.width <= 0 || plot.height <= 0) return '';
+    const bands = bandsOf(plot, total, horizontal, barGap, barWidth);
+    const length = bands.across * SKELETON_LENGTH;
+    let path = '';
+    for (let i = 0; i < total; i += 1) {
+      const lead = bands.alongStart + i * bands.band + (bands.band - bands.thickness) / 2;
+      path += horizontal ? barPath(plot.left, lead, length, bands.thickness, cornerRadius, 'right') : barPath(lead, plot.top + plot.height - length, bands.thickness, length, cornerRadius, 'up');
+    }
+    return path;
+  }, [plot, horizontal, total, barGap, barWidth, cornerRadius]);
+  if (!loading || !d) return null;
+  const gradientId = 'panelui-waterfall-skeleton';
+  return /*#__PURE__*/_jsxs(G, {
+    children: [/*#__PURE__*/_jsx(Defs, {
+      children: /*#__PURE__*/_jsxs(AnimatedLinearGradient, {
+        id: gradientId,
+        animatedProps: animatedProps,
+        y1: "0",
+        y2: "0",
+        children: [/*#__PURE__*/_jsx(Stop, {
+          offset: "0",
+          stopColor: base
+        }), /*#__PURE__*/_jsx(Stop, {
+          offset: "0.5",
+          stopColor: highlight,
+          stopOpacity: 0.35
+        }), /*#__PURE__*/_jsx(Stop, {
+          offset: "1",
+          stopColor: base
+        })]
+      })
+    }), /*#__PURE__*/_jsx(Path, {
+      d: d,
+      fill: `url(#${gradientId})`
+    })]
+  });
+}
+WaterfallChartSkeleton.displayName = 'WaterfallChart.Skeleton';
+WaterfallChartSkeleton.layer = 'svg';
+
+/* -------------------------------------------------------------------------- */
+/* Overlay layer                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * Narrowest a step label may be drawn before the axis starts dropping some.
+ * Roughly three characters at `xs`, which is what a short name needs.
+ */
+const MIN_BAND_LABEL = 34;
+/**
+ * The step names, one under each band it has room for. Real text rather than
+ * SVG text, so they follow the theme's font and the platform's text scaling —
+ * SVG text does neither.
+ */
+function WaterfallChartXAxis({
+  ticks,
+  format,
+  className
+}) {
+  const {
+    steps,
+    plot,
+    orientation
+  } = useChart('WaterfallChart.XAxis');
+  const labels = useMemo(() => {
+    if (!steps.length) return [];
+
+    /*
+     * Every step, unless they will not fit. The axis asks the plot how much
+     * room there is and only thins when the answer is not enough — a fixed tick
+     * count drops names that had room to be drawn.
+     */
+    const room = Math.max(1, Math.floor(plot.width / MIN_BAND_LABEL));
+    const count = Math.max(1, Math.min(ticks ?? room, steps.length));
+
+    // Every nth band, rather than a fractional step rounded to the nearest
+    // index — rounding lands on the same band twice and skips its neighbour.
+    const stride = Math.ceil(steps.length / count);
+    const picked = [];
+    for (let index = 0; index < steps.length; index += stride) {
+      const step = steps[index];
+      if (!step) continue;
+      picked.push({
+        key: index,
+        text: format ? format(step, index) : step.label
+      });
+    }
+    return picked;
+  }, [steps, ticks, format, plot.width]);
+  if (orientation === 'horizontal') return null;
+
+  /*
+   * One box per band, exactly the band's width. Tiling them rather than giving
+   * each a fixed width means they can never overlap each other and the first
+   * and last can never hang off the ends of the plot — the row of labels
+   * occupies precisely the space the bars do.
+   */
+  const bandWidth = steps.length > 0 ? plot.width / steps.length : 0;
+  return /*#__PURE__*/_jsx(View, {
+    style: {
+      position: 'absolute',
+      inset: 0,
+      pointerEvents: 'none'
+    },
+    className: cn(className),
+    children: labels.map(label => /*#__PURE__*/_jsx(Text, {
+      size: "xs",
+      muted: true,
+      numberOfLines: 1,
+      style: {
+        position: 'absolute',
+        bottom: 0,
+        left: plot.left + bandWidth * label.key,
+        width: bandWidth,
+        textAlign: 'center'
+      },
+      children: label.text
+    }, label.key))
+  });
+}
+WaterfallChartXAxis.displayName = 'WaterfallChart.XAxis';
+WaterfallChartXAxis.layer = 'overlay';
+/** Value labels down the side, aligned to the grid lines. */
+function WaterfallChartYAxis({
+  ticks = 4,
+  format,
+  className
+}) {
+  const {
+    plot,
+    steps,
+    orientation,
+    extent
+  } = useChart('WaterfallChart.YAxis');
+  const horizontal = orientation === 'horizontal';
+
+  /*
+   * Read off the settled domain rather than the shared values the paths use.
+   * A label is text, and text is JS — following the tween would re-render on
+   * every frame of it to redraw a number nobody can read while it moves.
+   */
+  const labels = useMemo(() => {
+    if (horizontal) {
+      // Sideways, the side of the chart is the step axis.
+      return steps.map((step, index) => ({
+        key: index,
+        text: step.label
+      }));
+    }
+    const [min, max] = extent;
+    if (min === 0 && max === 0) return [];
+    return Array.from({
+      length: ticks + 1
+    }, (_unused, index) => {
+      const value = max - (max - min) * index / ticks;
+      return {
+        key: index,
+        text: format ? format(value) : compactNumber(value)
+      };
+    });
+  }, [extent, ticks, format, horizontal, steps]);
+
+  /*
+   * Sideways the labels sit in the gutter the plot already left for them, one
+   * band each — `flex-1` per row rather than spacing them edge to edge, so
+   * every name lands beside its own bar instead of only the first and last
+   * doing so. Upright there are no bands to line up with, so the ticks space
+   * themselves against the grid.
+   */
+  return /*#__PURE__*/_jsx(View, {
+    pointerEvents: "none",
+    style: {
+      position: 'absolute',
+      left: 0,
+      // Upright, each label is centred on the grid line it names: the strip
+      // is lifted half a label and grown by a whole one, so `justify-between`
+      // lands the text's middle on the line rather than its top edge on the
+      // first and its bottom edge on the last.
+      top: horizontal ? plot.top : plot.top - AXIS_LABEL_HEIGHT / 2,
+      height: horizontal ? plot.height : plot.height + AXIS_LABEL_HEIGHT,
+      width: horizontal ? Math.max(plot.left - 8, 0) : undefined
+    },
+    className: cn(horizontal ? 'items-end' : 'justify-between', className),
+    children: labels.map(label => /*#__PURE__*/_jsx(View, {
+      className: horizontal ? 'flex-1 justify-center' : undefined,
+      children: /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        muted: true,
+        numberOfLines: 1,
+        children: label.text
+      })
+    }, label.key))
+  });
+}
+WaterfallChartYAxis.displayName = 'WaterfallChart.YAxis';
+WaterfallChartYAxis.layer = 'overlay';
+// Read by the root, which has to leave room for the labels before it lays the
+// plot out — an axis drawn over the plot is unreadable, and makes what it is
+// drawn over unreadable too.
+WaterfallChartYAxis.axis = 'y';
+/**
+ * The change each step made, written at the far end of its bar.
+ *
+ * Signed, because on this chart the sign is the reading: a bar's direction
+ * already says which way it went, and a label that drops the sign makes the
+ * two directions look like the same number twice.
+ *
+ * Only drawn upright. Sideways the bars run across a plot whose width is a
+ * phone's, and a number at the end of one has nowhere to go that is not on top
+ * of the bar or off the chart.
+ */
+function WaterfallChartValues({
+  format,
+  className
+}) {
+  const {
+    steps,
+    plot,
+    orientation,
+    status,
+    barGap,
+    barWidth,
+    extent
+  } = useChart('WaterfallChart.Values');
+  if (orientation === 'horizontal' || status === 'loading' || !steps.length) return null;
+  if (plot.width <= 0 || plot.height <= 0) return null;
+  const bands = bandsOf(plot, steps.length, false, barGap, barWidth);
+  const [min, max] = extent;
+  const range = max - min || 1;
+  return /*#__PURE__*/_jsx(View, {
+    style: {
+      position: 'absolute',
+      inset: 0,
+      pointerEvents: 'none'
+    },
+    children: steps.map((step, index) => {
+      const fraction = (step.end - min) / range;
+      const y = plot.top + plot.height - fraction * plot.height;
+      const forward = step.end >= step.start;
+      const text = format ? format(step, index) : step.kind === 'total' ? compactNumber(step.value) : `${step.value > 0 ? '+' : ''}${compactNumber(step.value)}`;
+      return /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        weight: "medium",
+        numberOfLines: 1,
+        className: cn(className),
+        style: {
+          position: 'absolute',
+          // Sat off the growing end of the bar, on whichever side that is.
+          // A label inside a bar is unreadable on a short one and a label
+          // always above is inside the plot's ceiling on the tall one.
+          top: forward ? y - AXIS_LABEL_HEIGHT - 2 : y + 2,
+          left: plot.left + bands.band * index,
+          width: bands.band,
+          textAlign: 'center'
+        },
+        children: text
+      }, index);
+    })
+  });
+}
+WaterfallChartValues.displayName = 'WaterfallChart.Values';
+WaterfallChartValues.layer = 'overlay';
+/**
+ * The readout, and the drag that drives it.
+ *
+ * It reports two numbers, because a step on this chart has two: what it changed
+ * by, and what the balance stood at afterwards. The second is the one a bar's
+ * position encodes and its length does not, so a readout that only gave the
+ * change would leave the reader converting the height back by eye.
+ *
+ * The hit area is the whole plot. A readout you have to land on the bar to
+ * summon is a readout nobody finds — and the bars here are narrower than a bar
+ * chart's, since the gap between them is what the connectors run through.
+ */
+function WaterfallChartTooltip({
+  formatValue,
+  formatTotal,
+  className
+}) {
+  const {
+    steps,
+    plot,
+    orientation,
+    colors,
+    activeIndex,
+    activeIndexJS,
+    setActiveIndexJS,
+    status
+  } = useChart('WaterfallChart.Tooltip');
+  const total = steps.length;
+  const horizontal = orientation === 'horizontal';
+  const left = plot.left;
+  const top = plot.top;
+  const width = plot.width;
+  const height = plot.height;
+
+  /*
+   * The readout's own height, measured rather than assumed. Sideways it has to
+   * be clamped inside the plot vertically, and how tall it is depends on
+   * whether the running total line is shown.
+   */
+  const labelHeight = useSharedValue(0);
+
+  /*
+   * Declared inside the memo, next to its callers: a worklet may only call
+   * another worklet, and the rule is enforced by crashing rather than warning.
+   */
+  const pan = useMemo(() => {
+    const resolve = (x, y) => {
+      'worklet';
+
+      if (!total) return;
+      const span = horizontal ? height : width;
+      const offset = (horizontal ? y - top : x - left) / (span || 1);
+      // Bands, not points: the finger is inside whichever slice it lands on,
+      // which is a floor rather than a round to the nearest centre.
+      const next = Math.max(0, Math.min(total - 1, Math.floor(offset * total)));
+      if (next === activeIndex.value) return;
+      activeIndex.value = next;
+      runOnJS(setActiveIndexJS)(next);
+    };
+    return Gesture.Pan().minDistance(0).onBegin(event => {
+      'worklet';
+
+      resolve(event.x, event.y);
+    }).onUpdate(event => {
+      'worklet';
+
+      resolve(event.x, event.y);
+    }).onFinalize(() => {
+      'worklet';
+
+      activeIndex.value = -1;
+      runOnJS(setActiveIndexJS)(-1);
+    });
+  }, [total, left, top, width, height, horizontal, activeIndex, setActiveIndexJS]);
+
+  // The readout centres over its band and is clamped inside the plot, so it
+  // never runs off the edge at the first or last one. Which axis it follows is
+  // the axis the bands run along.
+  const labelStyle = useAnimatedStyle(() => {
+    const index = activeIndex.value;
+    if (index < 0 || !total) return {
+      opacity: 0
+    };
+    const band = (horizontal ? plot.height : plot.width) / total;
+    const centre = (horizontal ? plot.top : plot.left) + band * (index + 0.5);
+    const half = LABEL_WIDTH / 2;
+    const clamped = Math.min(plot.left + plot.width - half, Math.max(plot.left + half, horizontal ? plot.left + plot.width / 2 : centre));
+    if (!horizontal) {
+      return {
+        opacity: 1,
+        transform: [{
+          translateX: clamped - half
+        }]
+      };
+    }
+    const tall = labelHeight.value;
+    const y = Math.min(plot.top + Math.max(plot.height - tall, 0), Math.max(plot.top, centre - tall / 2));
+    return {
+      opacity: 1,
+      transform: [{
+        translateX: clamped - half
+      }, {
+        translateY: y
+      }]
+    };
+  });
+  const active = activeIndexJS >= 0 ? steps[activeIndexJS] : null;
+  const fmtValue = formatValue ?? (step => step.kind === 'total' ? compactNumber(step.value) : `${step.value > 0 ? '+' : ''}${compactNumber(step.value)}`);
+  const fmtTotal = formatTotal ?? (step => step.kind === 'total' ? null : compactNumber(step.end));
+  if (status === 'loading') return null;
+  const runningTotal = active ? fmtTotal(active) : null;
+  return /*#__PURE__*/_jsx(GestureDetector, {
+    gesture: pan,
+    children: /*#__PURE__*/_jsx(View, {
+      style: StyleSheet.absoluteFill,
+      children: /*#__PURE__*/_jsx(Animated.View, {
+        pointerEvents: "none",
+        style: [{
+          position: 'absolute',
+          left: 0,
+          top: 0,
+          width: LABEL_WIDTH
+        }, labelStyle],
+        children: active ? /*#__PURE__*/_jsxs(View, {
+          onLayout: event => {
+            labelHeight.value = event.nativeEvent.layout.height;
+          },
+          className: cn('rounded-xl border border-border bg-popover px-2.5 py-1.5 shadow-lg', className),
+          children: [/*#__PURE__*/_jsx(Text, {
+            size: "xs",
+            muted: true,
+            numberOfLines: 1,
+            children: active.label
+          }), /*#__PURE__*/_jsxs(View, {
+            className: "flex-row items-center gap-1.5",
+            children: [/*#__PURE__*/_jsx(View, {
+              style: {
+                width: 6,
+                height: 6,
+                borderRadius: 3,
+                backgroundColor: active.datum.color ?? colors[active.kind]
+              }
+            }), /*#__PURE__*/_jsx(Text, {
+              size: "xs",
+              weight: "medium",
+              children: fmtValue(active)
+            })]
+          }), runningTotal ? /*#__PURE__*/_jsx(Text, {
+            size: "xs",
+            muted: true,
+            numberOfLines: 1,
+            children: runningTotal
+          }) : null]
+        }) : null
+      })
+    })
+  });
+}
+WaterfallChartTooltip.displayName = 'WaterfallChart.Tooltip';
+WaterfallChartTooltip.layer = 'overlay';
+
+/** One role's colour and name. Shared by the legend and the header. */
+function RoleSwatch({
+  color,
+  label
+}) {
+  return /*#__PURE__*/_jsxs(View, {
+    className: "flex-row items-center gap-1.5",
+    children: [/*#__PURE__*/_jsx(View, {
+      style: {
+        backgroundColor: color
+      },
+      className: "h-2 w-2 rounded-full"
+    }), /*#__PURE__*/_jsx(Text, {
+      size: "xs",
+      muted: true,
+      children: label
+    })]
+  });
+}
+/**
+ * A swatch and a name for each role the run actually contains.
+ *
+ * Three entries at most, and only the ones present — a run with no totals in it
+ * listing a "Total" colour is a key to a colour that is not on the chart.
+ */
+function WaterfallChartLegend({
+  className,
+  labels,
+  ...props
+}) {
+  const {
+    steps,
+    colors
+  } = useChart('WaterfallChart.Legend');
+  const present = useMemo(() => {
+    const order = ['rise', 'fall', 'total'];
+    const seen = new Set(steps.map(step => step.kind));
+    return order.filter(kind => seen.has(kind));
+  }, [steps]);
+  if (!present.length) return null;
+  const names = {
+    rise: labels?.rise ?? 'Increase',
+    fall: labels?.fall ?? 'Decrease',
+    total: labels?.total ?? 'Total'
+  };
+  return /*#__PURE__*/_jsx(View, {
+    ...props,
+    style: [{
+      pointerEvents: 'none'
+    }, props.style],
+    className: cn('absolute right-2 top-1 flex-row gap-3', className),
+    children: present.map(kind => /*#__PURE__*/_jsx(RoleSwatch, {
+      color: colors[kind],
+      label: names[kind]
+    }, kind))
+  });
+}
+WaterfallChartLegend.displayName = 'WaterfallChart.Legend';
+WaterfallChartLegend.layer = 'overlay';
+
+/* -------------------------------------------------------------------------- */
+/* Header layer                                                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The strip above the plot: what the run is of, what it currently reads, and
+ * what the colours mean.
+ *
+ * The value is not derived here. A readout that follows the finger belongs to
+ * whoever owns the data — take it from `onActiveIndexChange` and pass the
+ * formatted string down, so one header can show the closing balance when
+ * nothing is pressed and a step's change when something is.
+ */
+function WaterfallChartHeader({
+  className,
+  title,
+  value,
+  caption,
+  labels,
+  legend = false,
+  children,
+  ...props
+}) {
+  const {
+    steps,
+    colors
+  } = useChart('WaterfallChart.Header');
+  const present = useMemo(() => {
+    const order = ['rise', 'fall', 'total'];
+    const seen = new Set(steps.map(step => step.kind));
+    return order.filter(kind => seen.has(kind));
+  }, [steps]);
+  const names = {
+    rise: labels?.rise ?? 'Increase',
+    fall: labels?.fall ?? 'Decrease',
+    total: labels?.total ?? 'Total'
+  };
+  const trailing = children ?? (legend && present.length ? /*#__PURE__*/_jsx(View, {
+    className: "flex-row flex-wrap items-center justify-end gap-x-3 gap-y-1",
+    children: present.map(kind => /*#__PURE__*/_jsx(RoleSwatch, {
+      color: colors[kind],
+      label: names[kind]
+    }, kind))
+  }) : null);
+  return /*#__PURE__*/_jsxs(View, {
+    ...props,
+    className: cn('flex-row items-start justify-between gap-3 pb-3', className),
+    children: [/*#__PURE__*/_jsxs(View, {
+      className: "flex-1 gap-0.5",
+      children: [title ? /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        muted: true,
+        children: title
+      }) : null, value ? /*#__PURE__*/_jsx(Text, {
+        size: "xl",
+        weight: "bold",
+        children: value
+      }) : null, caption ? /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        muted: true,
+        children: caption
+      }) : null]
+    }), trailing ? /*#__PURE__*/_jsx(View, {
+      className: "shrink pt-1",
+      children: trailing
+    }) : null]
+  });
+}
+WaterfallChartHeader.displayName = 'WaterfallChart.Header';
+WaterfallChartHeader.layer = 'header';
+export const WaterfallChart = Object.assign(WaterfallChartRoot, {
+  Header: WaterfallChartHeader,
+  Grid: WaterfallChartGrid,
+  Connectors: WaterfallChartConnectors,
+  Bars: WaterfallChartBars,
+  Values: WaterfallChartValues,
+  Skeleton: WaterfallChartSkeleton,
+  XAxis: WaterfallChartXAxis,
+  YAxis: WaterfallChartYAxis,
+  Tooltip: WaterfallChartTooltip,
+  Legend: WaterfallChartLegend
+});
+//# sourceMappingURL=index.js.map