panelui-native 0.86.1 → 0.87.0

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

@@ -0,0 +1,1266 @@
+"use strict";
+
+/**
+ * BubbleChart — one labelled circle per row, on two measured axes, with a third
+ * quantity on each circle's area.
+ *
+ * ```tsx
+ * <BubbleChart data={teams} xDataKey="efficiency" yDataKey="performance"
+ *   sizeKey="headcount" labelKey="team">
+ *   <BubbleChart.Grid />
+ *   <BubbleChart.Bubbles />
+ *   <BubbleChart.Labels />
+ *   <BubbleChart.XAxis />
+ *   <BubbleChart.YAxis />
+ *   <BubbleChart.Tooltip />
+ * </BubbleChart>
+ * ```
+ *
+ * ## When this and not a scatter plot
+ *
+ * `ScatterChart` also maps a third quantity onto point area, through `sizeKey`,
+ * and it is the right component for a *series* of observations: many points of
+ * one colour, where the shape of the cloud is the finding and no single dot
+ * needs a name.
+ *
+ * This one is for a handful of named things. Each row is its own circle with
+ * its own colour and its own label written inside it, so the chart can be read
+ * entity by entity rather than as a distribution. Eight teams, twelve products,
+ * six regions — where the reader wants to find one of them and see where it
+ * sits.
+ *
+ * ## Area, not radius
+ *
+ * `sizeKey` maps to a circle's area. Doubling a radius quadruples the ink, so a
+ * chart that scaled the radius would show a doubled value as four times the
+ * size, and the reader would believe the picture. The scale runs over the whole
+ * data set, so one bubble's size means the same thing as another's.
+ *
+ * ## Labels are text, not SVG
+ *
+ * The names inside the bubbles are React Native `Text` in a layer over the
+ * plot, so they follow the theme's font and the platform's text scaling — SVG
+ * text does neither. A bubble too small to hold its own label is left without
+ * one rather than given an unreadable one; the readout still names it.
+ */
+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, runOnJS, useAnimatedProps, useAnimatedStyle, useDerivedValue, useReducedMotion, useSharedValue, withTiming } from 'react-native-reanimated';
+import Svg, { Circle, G, Line as SvgLine } from 'react-native-svg';
+import { useCSSVariable } from 'uniwind';
+import { useSkeletonHandoff } from "../../hooks/use-skeleton-handoff.js";
+import { ChartAccessibilityData } from "../../primitives/chart-accessibility.js";
+import { Text } from "../../primitives/text.js";
+import { bubbleRadius, compactNumber, niceDomain, useSeriesColor, xAt, yOf } 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 AnimatedCircle = Animated.createAnimatedComponent(Circle);
+const AnimatedG = Animated.createAnimatedComponent(G);
+
+/**
+ * How much of the reveal is spent handing out the bubbles' start times. The
+ * rest is the window each one gets, so the whole field still lands inside the
+ * one duration however many there are.
+ */
+const STAGGER = 0.4;
+
+/** Milliseconds for a bubble to swell as it is selected, and settle as it is not. */
+const SELECT_DURATION = 140;
+
+/**
+ * A bubble arriving: up past its size and back to it.
+ *
+ * A circle that simply grows to its radius reads as the chart still loading
+ * right up to the last frame. The small overshoot is what makes it read as
+ * landing.
+ */
+function landing(t) {
+  'worklet';
+
+  const back = 1.3;
+  const u = t - 1;
+  return 1 + (back + 1) * u * u * u + back * u * u;
+}
+
+/** Room left around the plot for the axis labels and the outermost bubbles. */
+const PADDING = {
+  top: 18,
+  right: 18,
+  bottom: 22,
+  left: 18
+};
+
+/** Left gutter reserved when a `YAxis` is present, for its labels to sit in. */
+const Y_AXIS_WIDTH = 44;
+
+/** Gap between the value labels and the plot they sit beside. */
+const Y_AXIS_GUTTER = 6;
+
+/** Line height of an `xs` label, for centring one on the grid line it names. */
+const AXIS_LABEL_HEIGHT = 16;
+
+/** Box each axis label is centred in, so a long number is ellipsised not shoved. */
+const AXIS_LABEL_WIDTH = 56;
+
+/** Width of the readout that floats by the selected bubble. */
+const LABEL_WIDTH = 132;
+
+/** Gap between the readout and the edge of the bubble it describes. */
+const LABEL_GAP = 10;
+
+/** Line box a bubble's own label is laid out in. */
+const BUBBLE_LABEL_HEIGHT = 16;
+
+/**
+ * Smallest radius a bubble may have and still be given its label. Below this
+ * the name is wider than the circle and reads as text lying on the plot rather
+ * than as the bubble's own.
+ *
+ * Ten points, which is a twenty-point circle: enough for the initial or the
+ * short code a bubble chart's labels usually are. Set higher and the smallest
+ * bubble in an ordinary set silently loses its name, which reads as a bug
+ * rather than as a decision.
+ */
+const LABEL_MIN_RADIUS = 10;
+
+/** Floor on the touch target, for a chart whose smallest bubbles are tiny. */
+const HIT_RADIUS = 22;
+
+/** How many colours the ramp cycles through. */
+const PALETTE_SIZE = 5;
+
+/** Steps each axis is rounded out to. Matches the labels an axis draws. */
+const AXIS_STEPS = 2;
+
+/** One bubble, resolved back to the row it came from. */
+
+/** A bubble with its geometry resolved. Shared by every part. */
+
+const BubbleChartContext = /*#__PURE__*/createContext(null);
+function useChart(component) {
+  const context = useContext(BubbleChartContext);
+  if (!context) {
+    throw new Error(`${component} must be used within a <BubbleChart>`);
+  }
+  return context;
+}
+
+/**
+ * The bubble under the finger, for something rendered *inside* the chart. A
+ * readout in the card's header is outside this provider — use
+ * `onActivePointChange` for that.
+ */
+export function useBubbleChart() {
+  const {
+    bubbles,
+    activeIndexJS
+  } = useChart('useBubbleChart');
+  const active = bubbles.find(bubble => bubble.index === activeIndexJS) ?? null;
+  return {
+    activeIndex: activeIndexJS,
+    activePoint: active
+  };
+}
+
+/**
+ * An extent widened out to round numbers, and a usable one for the degenerate
+ * cases — no data at all, or every reading identical. A domain of zero width
+ * divides by zero and puts every bubble on the same edge.
+ *
+ * Rounded rather than padded by a fraction: a fraction of the data's own span
+ * ends the axis at 52.7, which is true and which nobody was looking for. Two
+ * steps, matching the labels each axis draws by default, so the middle one is
+ * round as well as the ends.
+ */
+function padExtent(min, max) {
+  if (min === Infinity) return [0, 1];
+  if (min === max) return [min - 1, max + 1];
+  return niceDomain(min, max, AXIS_STEPS);
+}
+
+/** Imperative handle: re-run the grow-in, for a "replay" control. */
+
+function partition(children) {
+  const svg = [];
+  const overlay = [];
+  const header = [];
+  const footer = [];
+  Children.forEach(children, (child, index) => {
+    if (! /*#__PURE__*/isValidElement(child)) return;
+    const layer = child.type.layer ?? 'svg';
+    const slot = /*#__PURE__*/_jsx(ChildSlot, {
+      children: child
+    }, index);
+    const into = layer === 'header' ? header : layer === 'footer' ? footer : layer === 'overlay' ? overlay : svg;
+    into.push(slot);
+  });
+  return {
+    svg,
+    overlay,
+    header,
+    footer
+  };
+}
+function ChildSlot({
+  children
+}) {
+  return /*#__PURE__*/_jsx(_Fragment, {
+    children: children
+  });
+}
+const BubbleChartRoot = /*#__PURE__*/forwardRef(function BubbleChartRoot({
+  className,
+  data,
+  xDataKey = 'x',
+  yDataKey = 'y',
+  sizeKey,
+  labelKey,
+  colorKey,
+  sizeRange = [10, 28],
+  status = 'ready',
+  aspectRatio = 1,
+  animationDuration = 800,
+  domainDuration = 500,
+  xDomain,
+  yDomain,
+  onActivePointChange,
+  accessible,
+  accessibilityLabel,
+  accessibilityHint,
+  accessibilityLabelForDatum,
+  onAccessibilityDatumPress,
+  children,
+  ...props
+}, ref) {
+  const [size, setSize] = useState({
+    width: 0,
+    height: 0
+  });
+  const [activeIndexJS, setActiveIndexJS] = useState(-1);
+  const reveal = useSharedValue(0);
+  const xMin = useSharedValue(0);
+  const xMax = useSharedValue(0);
+  const yMin = useSharedValue(0);
+  const yMax = useSharedValue(0);
+  const activeIndex = useSharedValue(-1);
+  const reducedMotion = useReducedMotion();
+
+  /*
+   * The whole ramp, resolved once. Every bubble is its own category here
+   * rather than a member of a series, so the colour is chosen by row index
+   * and there is nothing to register.
+   */
+  const chart1 = useSeriesColor(undefined, 1);
+  const chart2 = useSeriesColor(undefined, 2);
+  const chart3 = useSeriesColor(undefined, 3);
+  const chart4 = useSeriesColor(undefined, 4);
+  const chart5 = useSeriesColor(undefined, 5);
+  const palette = useMemo(() => [chart1, chart2, chart3, chart4, chart5], [chart1, chart2, chart3, chart4, chart5]);
+  const hasYAxis = useMemo(() => {
+    let found = false;
+    Children.forEach(children, child => {
+      if (/*#__PURE__*/isValidElement(child) && child.type.axis === 'y') {
+        found = true;
+      }
+    });
+    return found;
+  }, [children]);
+
+  /*
+   * A circle is drawn about its centre, so every edge of the plot has to hold
+   * back the largest radius or the outermost bubble is cropped by it — and
+   * the largest bubble is the one carrying the largest value, which is the
+   * last one that should be half missing. `sizeRange` is the ceiling, so this
+   * is known before anything is measured.
+   */
+  const reach = sizeRange[1];
+  const pad = {
+    top: Math.max(PADDING.top, reach),
+    right: Math.max(PADDING.right, reach),
+    bottom: Math.max(PADDING.bottom, reach),
+    left: Math.max(hasYAxis ? Y_AXIS_WIDTH : PADDING.left, reach)
+  };
+  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 extents = useMemo(() => {
+    let lowX = Infinity;
+    let highX = -Infinity;
+    let lowY = Infinity;
+    let highY = -Infinity;
+    for (const row of data) {
+      const x = row[xDataKey];
+      const y = row[yDataKey];
+      // A row missing either coordinate is not a bubble at all, and must not
+      // stretch the axes towards an origin it never had.
+      if (typeof x !== 'number' || Number.isNaN(x)) continue;
+      if (typeof y !== 'number' || Number.isNaN(y)) continue;
+      if (x < lowX) lowX = x;
+      if (x > highX) highX = x;
+      if (y < lowY) lowY = y;
+      if (y > highY) highY = y;
+    }
+    return {
+      x: xDomain ?? padExtent(lowX, highX),
+      y: yDomain ?? padExtent(lowY, highY)
+    };
+  }, [data, xDataKey, yDataKey, xDomain, yDomain]);
+
+  /*
+   * The size scale runs over the whole data set, so one bubble's area means
+   * the same thing as another's. Without a `sizeKey` there is nothing to
+   * scale and every bubble takes the middle of the range — which is a
+   * scatter plot with names on it, and an honest one.
+   */
+  const sizeExtent = useMemo(() => {
+    if (!sizeKey) return null;
+    let min = Infinity;
+    let max = -Infinity;
+    for (const row of data) {
+      const value = row[sizeKey];
+      if (typeof value !== 'number' || Number.isNaN(value)) continue;
+      if (value < min) min = value;
+      if (value > max) max = value;
+    }
+    return min === Infinity ? null : [min, max];
+  }, [data, sizeKey]);
+
+  /*
+   * Resolved once, in the root, because four parts need exactly this list and
+   * three of them would otherwise derive it again: the circles, the labels
+   * over them, the hit test under them and the legend beside them all have to
+   * agree about where a bubble is and how big it is.
+   */
+  const bubbles = useMemo(() => {
+    const middle = (sizeRange[0] + sizeRange[1]) / 2;
+    const out = [];
+    data.forEach((datum, index) => {
+      const x = datum[xDataKey];
+      const y = datum[yDataKey];
+      if (typeof x !== 'number' || Number.isNaN(x)) return;
+      if (typeof y !== 'number' || Number.isNaN(y)) return;
+      const raw = sizeKey ? datum[sizeKey] : undefined;
+      const value = typeof raw === 'number' && !Number.isNaN(raw) ? raw : null;
+      const r = sizeExtent && value !== null ? bubbleRadius(value, sizeExtent, sizeRange) : middle;
+      const explicit = colorKey ? datum[colorKey] : undefined;
+      const color = typeof explicit === 'string' ? explicit : typeof explicit === 'number' ? palette[(Math.round(explicit) - 1 + PALETTE_SIZE) % PALETTE_SIZE] ?? palette[0] : palette[index % PALETTE_SIZE] ?? palette[0];
+      out.push({
+        index,
+        x,
+        y,
+        r,
+        size: value,
+        label: labelKey ? String(datum[labelKey] ?? '') : '',
+        color,
+        datum
+      });
+    });
+    return out;
+  }, [data, xDataKey, yDataKey, sizeKey, labelKey, colorKey, sizeExtent, sizeRange, palette]);
+  const loading = status === 'loading';
+  useEffect(() => {
+    if (loading) return;
+    const [x0, x1] = extents.x;
+    const [y0, y1] = extents.y;
+    // The first domain lands without a tween: there is no previous scale to
+    // move from, and animating up from zero reads as the numbers changing.
+    const first = xMin.value === 0 && xMax.value === 0 && yMin.value === 0 && yMax.value === 0;
+    if (first || reducedMotion) {
+      xMin.value = x0;
+      xMax.value = x1;
+      yMin.value = y0;
+      yMax.value = y1;
+      return;
+    }
+    xMin.value = withTiming(x0, {
+      duration: domainDuration
+    });
+    xMax.value = withTiming(x1, {
+      duration: domainDuration
+    });
+    yMin.value = withTiming(y0, {
+      duration: domainDuration
+    });
+    yMax.value = withTiming(y1, {
+      duration: domainDuration
+    });
+  }, [extents, loading, reducedMotion, domainDuration, xMin, xMax, yMin, yMax]);
+  const revealed = useRef(false);
+  const playReveal = useMemo(() => () => {
+    if (reducedMotion) {
+      reveal.value = 1;
+      return;
+    }
+    reveal.value = 0;
+    /*
+     * Eased out rather than in and out. Each bubble is given a slice of
+     * this one clock, so an ease that dawdles at the start spends it on the
+     * first few and leaves the rest to arrive in a rush.
+     */
+    reveal.value = withTiming(1, {
+      duration: animationDuration,
+      easing: Easing.out(Easing.cubic)
+    });
+  }, [reducedMotion, animationDuration, reveal]);
+  useEffect(() => {
+    if (loading) {
+      revealed.current = false;
+      reveal.value = 0;
+      return;
+    }
+    if (revealed.current || plot.width <= 0 || !bubbles.length) return;
+    revealed.current = true;
+    playReveal();
+  }, [loading, plot.width, bubbles.length, playReveal, reveal]);
+  useImperativeHandle(ref, () => ({
+    replay: playReveal
+  }), [playReveal]);
+
+  // One place the selection lands, so the chart's own children and a readout
+  // outside it never disagree about which bubble is active.
+  const setActivePoint = useMemo(() => point => {
+    setActiveIndexJS(point ? point.index : -1);
+    onActivePointChange?.(point);
+  }, [onActivePointChange]);
+  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,
+    xDataKey,
+    yDataKey,
+    labelKey,
+    plot,
+    status,
+    bubbles,
+    xMin,
+    xMax,
+    yMin,
+    yMax,
+    xExtent: extents.x,
+    yExtent: extents.y,
+    reveal,
+    activeIndex,
+    activeIndexJS,
+    setActivePoint
+  }),
+  // `plot` is rebuilt every render from `size`, so it is compared by value.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  [data, xDataKey, yDataKey, labelKey, plot.width, plot.height, plot.left, plot.top, status, bubbles, xMin, xMax, yMin, yMax, extents, reveal, activeIndex, activeIndexJS, setActivePoint]);
+  const {
+    svg,
+    overlay,
+    header,
+    footer
+  } = 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(BubbleChartContext.Provider, {
+    value: context,
+    children: /*#__PURE__*/_jsxs(View, {
+      ...props,
+      style: props.style,
+      className: cn('w-full', className),
+      children: [header, /*#__PURE__*/_jsx(ChartAccessibilityData, {
+        chart: "Bubble chart",
+        data: data,
+        disabled: accessible === false || loading,
+        accessibilityLabel: accessibilityLabel,
+        accessibilityHint: accessibilityHint,
+        accessibilityLabelForDatum: accessibilityLabelForDatum,
+        onAccessibilityDatumPress: onAccessibilityDatumPress,
+        valueOf: datum => {
+          const pairs = [[xDataKey, datum[xDataKey]], [yDataKey, datum[yDataKey]]];
+          if (labelKey) pairs.unshift([labelKey, datum[labelKey]]);
+          if (sizeKey) pairs.push([sizeKey, datum[sizeKey]]);
+          return pairs;
+        }
+      }), /*#__PURE__*/_jsx(View, {
+        onLayout: onLayout,
+        style: {
+          aspectRatio
+        },
+        className: "w-full",
+        accessibilityElementsHidden: true,
+        importantForAccessibility: "no-hide-descendants",
+        children: plot.width > 0 ? /*#__PURE__*/_jsxs(_Fragment, {
+          children: [/*#__PURE__*/_jsx(Svg, {
+            width: "100%",
+            height: "100%",
+            style: StyleSheet.absoluteFill,
+            children: svg
+          }), overlay]
+        }) : null
+      }), footer]
+    })
+  });
+});
+BubbleChartRoot.displayName = 'BubbleChart';
+
+/* -------------------------------------------------------------------------- */
+/* SVG layer                                                                  */
+/* -------------------------------------------------------------------------- */
+
+/** Reference lines both ways, so a bubble can be placed against two numbers. */
+function BubbleChartGrid({
+  rows = 5,
+  columns = 5,
+  color,
+  opacity = 1
+}) {
+  const {
+    plot
+  } = useChart('BubbleChart.Grid');
+  const token = useCSSVariable('--color-border');
+  const stroke = color ?? (typeof token === 'string' ? token : 'rgba(0,0,0,0.1)');
+  const horizontals = Array.from({
+    length: rows + 1
+  }, (_unused, i) => i / rows);
+  const verticals = Array.from({
+    length: columns + 1
+  }, (_unused, i) => i / columns);
+  return /*#__PURE__*/_jsxs(G, {
+    opacity: opacity,
+    children: [horizontals.map(fraction => /*#__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,
+      strokeWidth: 1
+    }, `h${fraction}`)), verticals.map(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,
+      strokeWidth: 1
+    }, `v${fraction}`))]
+  });
+}
+BubbleChartGrid.displayName = 'BubbleChart.Grid';
+BubbleChartGrid.layer = 'svg';
+/** The circles. */
+function BubbleChartBubbles({
+  opacity = 0.9,
+  color
+}) {
+  const {
+    bubbles,
+    plot,
+    status,
+    xMin,
+    xMax,
+    yMin,
+    yMax,
+    reveal,
+    activeIndex
+  } = useChart('BubbleChart.Bubbles');
+  if (status === 'loading') return null;
+  return /*#__PURE__*/_jsx(G, {
+    children: bubbles.map((bubble, order) => /*#__PURE__*/_jsx(Bubble, {
+      bubble: bubble,
+      plot: plot,
+      xMin: xMin,
+      xMax: xMax,
+      yMin: yMin,
+      yMax: yMax,
+      fill: color ?? bubble.color,
+      opacity: opacity,
+      activeIndex: activeIndex,
+      reveal: reveal,
+      order: order,
+      total: bubbles.length
+    }, bubble.index))
+  });
+}
+BubbleChartBubbles.displayName = 'BubbleChart.Bubbles';
+BubbleChartBubbles.layer = 'svg';
+
+/**
+ * One bubble. Its position follows both domain tweens, so a data change moves
+ * the whole field to the new scale rather than cutting to it.
+ *
+ * It arrives by growing in place, on its own slice of the shared reveal. A wipe
+ * across the plot — which is what the line and area charts do — gives the
+ * reader a direction to read the arrival in, and a field of bubbles has none:
+ * position is the whole message, so a bubble may only ever appear where it
+ * belongs.
+ */
+function Bubble({
+  bubble,
+  plot,
+  xMin,
+  xMax,
+  yMin,
+  yMax,
+  fill,
+  opacity,
+  activeIndex,
+  reveal,
+  order,
+  total
+}) {
+  const {
+    index,
+    x,
+    y,
+    r
+  } = bubble;
+
+  /*
+   * The selection, as something that moves. A hard switch made the bubble it
+   * named jump between one frame and the next while every neighbour stayed put,
+   * which reads as a glitch rather than as a response to the finger.
+   */
+  const selected = useDerivedValue(() => withTiming(activeIndex.value === index ? 1 : 0, {
+    duration: SELECT_DURATION
+  }));
+
+  // Where in the reveal this bubble starts. Spread over `STAGGER`, so the field
+  // settles as a field rather than switching on all at once.
+  const start = total > 1 ? order / total * STAGGER : 0;
+  const animatedProps = useAnimatedProps(() => {
+    const arrived = Math.max(0, Math.min(1, (reveal.value - start) / (1 - STAGGER)));
+    // The selected bubble swells and goes solid. Both, rather than one: a size
+    // change alone is easy to miss among neighbours, and an opacity change
+    // alone is invisible wherever the circles already overlap.
+    const swell = 1 + 0.12 * selected.value;
+    return {
+      cx: xAt(x, plot, xMin.value, xMax.value),
+      cy: yOf(y, plot, yMin.value, yMax.value),
+      r: r * landing(arrived) * swell,
+      // Ahead of the size, so a bubble is legible by the time it stops moving
+      // rather than fading in for the whole of its arrival.
+      fillOpacity: Math.min(1, arrived * 2) * (opacity + (1 - opacity) * selected.value)
+    };
+  });
+  return /*#__PURE__*/_jsx(AnimatedCircle, {
+    animatedProps: animatedProps,
+    fill: fill
+  });
+}
+/**
+ * The loading state: a still field of muted circles where the data will be.
+ *
+ * Deliberately still. A shimmer over a field of circles reads as them *moving*,
+ * which is the one thing this chart must never appear to do — position is the
+ * entire message, and a loading state that implies it is changing is a loading
+ * state that lies.
+ *
+ * The layout is deterministic rather than random, so it does not reshuffle on
+ * every render of a component that may re-render several times while waiting.
+ * It dissolves as the real bubbles grow in, and outlives the status change by
+ * exactly that long: cut at the frame the data lands, the placeholder would
+ * disappear before anything had replaced it.
+ */
+function BubbleChartSkeleton({
+  count = 7,
+  color
+}) {
+  const {
+    plot,
+    status
+  } = useChart('BubbleChart.Skeleton');
+  const token = useCSSVariable('--color-skeleton');
+  const fill = color ?? (typeof token === 'string' ? token : 'rgba(128,128,128,0.2)');
+  const {
+    mounted,
+    opacity: fade
+  } = useSkeletonHandoff(status === 'loading');
+  const circles = useMemo(() =>
+  // Two irrational-ish strides that do not share a factor, so the circles
+  // spread instead of falling into a lattice.
+  Array.from({
+    length: count
+  }, (_unused, index) => ({
+    key: index,
+    fx: index * 0.618 % 1 * 0.84 + 0.08,
+    fy: index * 0.379 % 1 * 0.84 + 0.08,
+    r: 16 + index * 0.472 % 1 * 12
+  })), [count]);
+  const animatedProps = useAnimatedProps(() => ({
+    opacity: fade.value
+  }));
+  if (!mounted) return null;
+  return /*#__PURE__*/_jsx(AnimatedG, {
+    animatedProps: animatedProps,
+    children: circles.map(circle => /*#__PURE__*/_jsx(Circle, {
+      cx: plot.left + circle.fx * plot.width,
+      cy: plot.top + circle.fy * plot.height,
+      r: circle.r,
+      fill: fill
+    }, circle.key))
+  });
+}
+BubbleChartSkeleton.displayName = 'BubbleChart.Skeleton';
+BubbleChartSkeleton.layer = 'svg';
+
+/* -------------------------------------------------------------------------- */
+/* Overlay layer                                                              */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The names, written inside the circles.
+ *
+ * Real text over the plot rather than SVG text, so they follow the theme's font
+ * and the platform's text scaling. Each one rides the same domain tweens the
+ * circle under it does, so a label never lags the bubble it belongs to.
+ *
+ * A bubble too small to hold its name is left without one. Shrinking the text
+ * to fit would make it unreadable on exactly the bubbles the reader is
+ * squinting at already; the readout names those instead.
+ */
+function BubbleChartLabels({
+  minRadius = LABEL_MIN_RADIUS,
+  format,
+  className
+}) {
+  const {
+    bubbles,
+    plot,
+    status,
+    xMin,
+    xMax,
+    yMin,
+    yMax,
+    reveal
+  } = useChart('BubbleChart.Labels');
+  if (status === 'loading') return null;
+  return /*#__PURE__*/_jsx(View, {
+    style: {
+      position: 'absolute',
+      inset: 0,
+      pointerEvents: 'none'
+    },
+    children: bubbles.filter(bubble => bubble.r >= minRadius && (format || bubble.label)).map((bubble, order) => /*#__PURE__*/_jsx(BubbleLabel, {
+      bubble: bubble,
+      text: format ? format(bubble) : bubble.label,
+      plot: plot,
+      xMin: xMin,
+      xMax: xMax,
+      yMin: yMin,
+      yMax: yMax,
+      reveal: reveal,
+      order: order,
+      total: bubbles.length,
+      className: className
+    }, bubble.index))
+  });
+}
+BubbleChartLabels.displayName = 'BubbleChart.Labels';
+BubbleChartLabels.layer = 'overlay';
+function BubbleLabel({
+  bubble,
+  text,
+  plot,
+  xMin,
+  xMax,
+  yMin,
+  yMax,
+  reveal,
+  order,
+  total,
+  className
+}) {
+  const {
+    x,
+    y,
+    r
+  } = bubble;
+  const width = r * 2;
+  const start = total > 1 ? order / total * STAGGER : 0;
+  const style = useAnimatedStyle(() => {
+    const arrived = Math.max(0, Math.min(1, (reveal.value - start) / (1 - STAGGER)));
+    return {
+      opacity: Math.max(0, arrived * 2 - 1),
+      transform: [{
+        translateX: xAt(x, plot, xMin.value, xMax.value) - width / 2
+      }, {
+        translateY: yOf(y, plot, yMin.value, yMax.value) - BUBBLE_LABEL_HEIGHT / 2
+      }]
+    };
+  });
+  return /*#__PURE__*/_jsx(Animated.View, {
+    pointerEvents: "none",
+    style: [{
+      position: 'absolute',
+      left: 0,
+      top: 0,
+      width,
+      height: BUBBLE_LABEL_HEIGHT
+    }, style],
+    children: /*#__PURE__*/_jsx(Text, {
+      size: "xs",
+      weight: "medium",
+      numberOfLines: 1
+      // White on the fill, which is a chart colour in every theme rather than
+      // a surface — so this is the one place a literal is right: the token
+      // that reads on a card would vanish on the bubble.
+      ,
+      className: cn('text-center text-white', className),
+      children: text
+    })
+  });
+}
+/**
+ * The x labels, evenly along the axis.
+ *
+ * Evenly spaced, because this axis is a continuous scale rather than a list of
+ * rows. There is no bubble for a label to sit under.
+ */
+function BubbleChartXAxis({
+  ticks = 2,
+  format,
+  className
+}) {
+  const {
+    plot,
+    xExtent
+  } = useChart('BubbleChart.XAxis');
+  const labels = useMemo(() => {
+    const [min, max] = xExtent;
+    if (min === 0 && max === 0) return [];
+    return Array.from({
+      length: ticks + 1
+    }, (_unused, index) => {
+      const value = min + (max - min) * index / ticks;
+      return {
+        key: index,
+        text: format ? format(value) : compactNumber(value)
+      };
+    });
+  }, [xExtent, ticks, format]);
+  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,
+        // Centred on its tick, then held inside the chart. The first and
+        // last ticks sit on the plot's own edges, so a box centred on them
+        // hangs half its width off the side — the clamp slides those two
+        // back in rather than letting the numbers leave the frame.
+        left: Math.max(0, Math.min(plot.left + plot.width / ticks * label.key - AXIS_LABEL_WIDTH / 2, plot.left + plot.width + PADDING.right - AXIS_LABEL_WIDTH)),
+        width: AXIS_LABEL_WIDTH,
+        textAlign: 'center'
+      },
+      children: label.text
+    }, label.key))
+  });
+}
+BubbleChartXAxis.displayName = 'BubbleChart.XAxis';
+BubbleChartXAxis.layer = 'overlay';
+/** Value labels down the side, one per grid line. Reserves its own gutter. */
+function BubbleChartYAxis({
+  ticks = 2,
+  format,
+  className
+}) {
+  const {
+    plot,
+    yExtent
+  } = useChart('BubbleChart.YAxis');
+  const labels = useMemo(() => {
+    const [min, max] = yExtent;
+    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)
+      };
+    });
+  }, [yExtent, ticks, format]);
+  return /*#__PURE__*/_jsx(View, {
+    pointerEvents: "none",
+    style: {
+      position: 'absolute',
+      left: 0,
+      // Centred on the grid line each label 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.
+      top: plot.top - AXIS_LABEL_HEIGHT / 2,
+      height: plot.height + AXIS_LABEL_HEIGHT,
+      width: Math.max(plot.left - Y_AXIS_GUTTER, 0)
+    },
+    className: cn('items-end justify-between', className),
+    children: labels.map(label => /*#__PURE__*/_jsx(Text, {
+      size: "xs",
+      muted: true,
+      numberOfLines: 1,
+      children: label.text
+    }, label.key))
+  });
+}
+BubbleChartYAxis.displayName = 'BubbleChart.YAxis';
+BubbleChartYAxis.layer = 'overlay';
+// Read by the root, which has to leave room for the labels before it lays the
+// plot out.
+BubbleChartYAxis.axis = 'y';
+/**
+ * The touch target, the selection it drives, and the readout that follows it.
+ *
+ * A touch picks the nearest bubble whose own circle — or the `hitRadius` floor,
+ * whichever is larger — reaches the finger. Nearest rather than topmost,
+ * because where bubbles overlap the one drawn last is not the one being aimed
+ * at.
+ *
+ * The search runs on the UI thread over flat arrays of already-projected
+ * coordinates, and only the *index* of the winner crosses back into JS, and
+ * only when it changes. A drag across the plot therefore costs a handful of
+ * re-renders rather than one per frame.
+ *
+ * Distances are compared squared. The nearest bubble by distance is the nearest
+ * by distance-squared, and a square root per bubble per frame buys nothing.
+ */
+function BubbleChartTooltip({
+  showLabel = true,
+  formatX,
+  formatY,
+  formatSize,
+  hitRadius = HIT_RADIUS,
+  className
+}) {
+  const {
+    bubbles,
+    plot,
+    xExtent,
+    yExtent,
+    activeIndex,
+    activeIndexJS,
+    setActivePoint,
+    status
+  } = useChart('BubbleChart.Tooltip');
+
+  /*
+   * Every bubble, projected once, as parallel arrays.
+   *
+   * Parallel arrays rather than an array of objects because this is read inside
+   * a worklet: Reanimated has to copy whatever the gesture captures across to
+   * the UI thread, and four number arrays cross far more cheaply than a few
+   * hundred small objects.
+   *
+   * Projected against the *settled* extents rather than the tweening shared
+   * values. Hit-testing against a moving scale would mean rebuilding this on
+   * every frame of a domain animation, and a bubble being half a second stale
+   * during a transition is not something a finger can notice.
+   */
+  const hit = useMemo(() => {
+    const xs = [];
+    const ys = [];
+    const rs = [];
+    const limits = [];
+    const indices = [];
+    for (const bubble of bubbles) {
+      xs.push(xAt(bubble.x, plot, xExtent[0], xExtent[1]));
+      ys.push(yOf(bubble.y, plot, yExtent[0], yExtent[1]));
+      rs.push(bubble.r);
+      const reach = Math.max(bubble.r, hitRadius);
+      limits.push(reach * reach);
+      indices.push(bubble.index);
+    }
+    return {
+      xs,
+      ys,
+      rs,
+      limits,
+      indices
+    };
+  }, [bubbles, plot, xExtent, yExtent, hitRadius]);
+  const select = useMemo(() => index => {
+    if (index < 0) {
+      setActivePoint(null);
+      return;
+    }
+    setActivePoint(bubbles.find(bubble => bubble.index === index) ?? null);
+  }, [bubbles, setActivePoint]);
+
+  /*
+   * Built in one closure, and everything it captures is a plain array, a number
+   * or a shared value. A worklet may only call another worklet, and the rule is
+   * enforced by crashing rather than by warning — so the resolver is declared
+   * here, next to its callers, rather than as a helper elsewhere in the file
+   * where it would be easy to leave un-workletised.
+   */
+  const pan = useMemo(() => {
+    const xs = hit.xs;
+    const ys = hit.ys;
+    const limits = hit.limits;
+    const indices = hit.indices;
+    const resolve = (px, py) => {
+      'worklet';
+
+      let bestIndex = -1;
+      let best = Infinity;
+      for (let i = 0; i < xs.length; i += 1) {
+        const dx = xs[i] - px;
+        const dy = ys[i] - py;
+        const distance = dx * dx + dy * dy;
+        // Each bubble reaches as far as it is big, so a large one is not
+        // beaten by a small one that happens to be marginally nearer.
+        if (distance <= limits[i] && distance < best) {
+          best = distance;
+          bestIndex = indices[i];
+        }
+      }
+      if (bestIndex === activeIndex.value) return;
+      activeIndex.value = bestIndex;
+      runOnJS(select)(bestIndex);
+    };
+    const clear = () => {
+      'worklet';
+
+      if (activeIndex.value === -1) return;
+      activeIndex.value = -1;
+      runOnJS(select)(-1);
+    };
+    return Gesture.Pan().minDistance(0).onBegin(event => {
+      'worklet';
+
+      resolve(event.x, event.y);
+    }).onUpdate(event => {
+      'worklet';
+
+      resolve(event.x, event.y);
+    }).onFinalize(() => {
+      'worklet';
+
+      clear();
+    });
+  }, [hit, activeIndex, select]);
+
+  /*
+   * The readout's own height, measured rather than assumed. It decides whether
+   * the readout fits above the bubble, and how tall it is depends on whether
+   * the row has a label and a size — a constant would either overlap a
+   * three-line readout or reserve room a one-line one never uses.
+   */
+  const labelHeight = useSharedValue(0);
+
+  /*
+   * Above the bubble, clear of its edge rather than of its centre, and clamped
+   * inside the plot. Lifted by a constant it landed *on* the larger circles —
+   * which are exactly the ones a finger is most likely to be resting on, so the
+   * readout was hidden under the hand that summoned it.
+   *
+   * Where there is no room above, it goes below instead. Sliding it down to the
+   * top edge of the plot would leave it over the bubble again.
+   */
+  const labelStyle = useAnimatedStyle(() => {
+    const index = activeIndex.value;
+    if (index < 0) return {
+      opacity: 0
+    };
+    const at = hit.indices.indexOf(index);
+    if (at < 0) return {
+      opacity: 0
+    };
+    const x = hit.xs[at];
+    const y = hit.ys[at];
+    const r = hit.rs[at];
+    const half = LABEL_WIDTH / 2;
+    const tall = labelHeight.value;
+    const above = y - r - LABEL_GAP - tall;
+    const below = y + r + LABEL_GAP;
+    const top = above >= plot.top ? above : below;
+    return {
+      opacity: 1,
+      transform: [{
+        translateX: Math.min(plot.left + plot.width - half, Math.max(plot.left + half, x)) - half
+      }, {
+        translateY: top
+      }]
+    };
+  });
+  const active = bubbles.find(bubble => bubble.index === activeIndexJS) ?? null;
+  const fmtX = formatX ?? compactNumber;
+  const fmtY = formatY ?? compactNumber;
+  const fmtSize = formatSize ?? compactNumber;
+  if (status === 'loading') return null;
+  return /*#__PURE__*/_jsx(GestureDetector, {
+    gesture: pan,
+    children: /*#__PURE__*/_jsx(View, {
+      style: StyleSheet.absoluteFill,
+      children: showLabel ? /*#__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: [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.color
+              }
+            }), /*#__PURE__*/_jsx(Text, {
+              size: "xs",
+              weight: "medium",
+              numberOfLines: 1,
+              children: active.label
+            })]
+          }) : null, /*#__PURE__*/_jsxs(Text, {
+            size: "xs",
+            muted: true,
+            numberOfLines: 1,
+            children: [fmtX(active.x), ", ", fmtY(active.y)]
+          }), active.size !== null ? /*#__PURE__*/_jsx(Text, {
+            size: "xs",
+            muted: true,
+            numberOfLines: 1,
+            children: fmtSize(active.size)
+          }) : null]
+        }) : null
+      }) : null
+    })
+  });
+}
+BubbleChartTooltip.displayName = 'BubbleChart.Tooltip';
+BubbleChartTooltip.layer = 'overlay';
+/**
+ * A swatch and a name per bubble, for a chart whose circles are too small to
+ * carry their own labels.
+ *
+ * Drawn **under** the plot rather than floating in a corner of it. A key that
+ * overlays the drawing area competes with the bubbles for the space they are
+ * plotted in, and on a square chart there is no corner that is reliably empty —
+ * the position of a bubble is the data, so nowhere can be reserved for it.
+ *
+ * It lists rows rather than series, because in this chart a row *is* a
+ * category. Use it instead of `BubbleChart.Labels`, not beside it — the same
+ * names twice is the legend telling the reader what the plot already says.
+ */
+function BubbleChartLegend({
+  className,
+  limit = 8,
+  ...props
+}) {
+  const {
+    bubbles
+  } = useChart('BubbleChart.Legend');
+  const shown = bubbles.filter(bubble => bubble.label).slice(0, limit);
+  if (!shown.length) return null;
+  return /*#__PURE__*/_jsx(View, {
+    ...props,
+    style: [{
+      pointerEvents: 'none'
+    }, props.style],
+    className: cn('flex-row flex-wrap items-center justify-center gap-x-3 gap-y-1 pt-3', className),
+    children: shown.map(bubble => /*#__PURE__*/_jsxs(View, {
+      className: "flex-row items-center gap-1.5",
+      children: [/*#__PURE__*/_jsx(View, {
+        style: {
+          backgroundColor: bubble.color
+        },
+        className: "h-2 w-2 rounded-full"
+      }), /*#__PURE__*/_jsx(Text, {
+        size: "xs",
+        muted: true,
+        children: bubble.label
+      })]
+    }, bubble.index))
+  });
+}
+BubbleChartLegend.displayName = 'BubbleChart.Legend';
+BubbleChartLegend.layer = 'footer';
+
+/* -------------------------------------------------------------------------- */
+/* Header layer                                                               */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * The strip above the plot: what the chart is of, what it currently reads, and
+ * what the size of a circle means.
+ *
+ * The caption earns its place here more than on most charts. Two axes and an
+ * area is three quantities, and a reader who is not told what the area is has
+ * no way to work it out from the picture.
+ *
+ * The value is not derived here. A readout that follows the finger belongs to
+ * whoever owns the data — take it from `onActivePointChange` and pass the
+ * formatted string down.
+ */
+function BubbleChartHeader({
+  className,
+  title,
+  value,
+  caption,
+  children,
+  ...props
+}) {
+  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]
+    }), children ? /*#__PURE__*/_jsx(View, {
+      className: "shrink pt-1",
+      children: children
+    }) : null]
+  });
+}
+BubbleChartHeader.displayName = 'BubbleChart.Header';
+BubbleChartHeader.layer = 'header';
+export const BubbleChart = Object.assign(BubbleChartRoot, {
+  Header: BubbleChartHeader,
+  Grid: BubbleChartGrid,
+  Bubbles: BubbleChartBubbles,
+  Labels: BubbleChartLabels,
+  Skeleton: BubbleChartSkeleton,
+  XAxis: BubbleChartXAxis,
+  YAxis: BubbleChartYAxis,
+  Tooltip: BubbleChartTooltip,
+  Legend: BubbleChartLegend
+});
+//# sourceMappingURL=index.js.map