jfs-components 0.0.79 → 0.0.85

package/src/components/BubbleChart/BubbleChart.tsx

@@ -0,0 +1,319 @@
+import React, { useCallback, useMemo, useState } from 'react'
+import {
+    StyleSheet,
+    View,
+    type LayoutChangeEvent,
+    type StyleProp,
+    type ViewStyle,
+} from 'react-native'
+import { EMPTY_MODES } from '../../utils/react-utils'
+import ClusterBubble, {
+    type ClusterBubbleLabelDirection,
+    type ClusterBubbleLabelPlacement,
+} from '../ClusterBubble/ClusterBubble'
+import {
+    chooseLabelDirections,
+    estimateLabelBox,
+    fitRadiiToBox,
+    scaleRadii,
+    simulateCluster,
+    type LabelBox,
+} from './bubblePacking'
+
+/** One bubble in the chart. */
+export type BubbleDatum = {
+    /** Stable React key (falls back to the array index). */
+    id?: React.Key
+    /**
+     * Numeric magnitude controlling the bubble's *area*. Larger values produce
+     * larger circles (`sqrt`-scaled between `minBubbleSize` and `maxBubbleSize`).
+     */
+    value: number
+    /**
+     * Bold primary text shown in/under the bubble — e.g. `"40%"`, `"₹270K"`.
+     * Defaults to the stringified `value`.
+     */
+    display?: React.ReactNode
+    /** Secondary caption beside the primary text — e.g. `"Recommended"`. */
+    label?: React.ReactNode
+    /** `Appearance / DataViz` mode for the fill. Cycles automatically if omitted. */
+    appearance?: string
+    /** Hard color override (bypasses token resolution). */
+    color?: string
+    /** Force this bubble's label placement, overriding the chart-level default. */
+    labelPlacement?: ClusterBubbleLabelPlacement
+    /** Per-bubble accessibility label. */
+    accessibilityLabel?: string
+}
+
+export type BubbleChartProps = {
+    /** The bubbles to lay out and render. */
+    data: BubbleDatum[]
+    /** Smallest bubble diameter in px. Defaults to `48`. */
+    minBubbleSize?: number
+    /** Largest bubble diameter in px. Defaults to `170`. */
+    maxBubbleSize?: number
+    /** Minimum spacing between packed bubbles in px. Defaults to `8`. */
+    gap?: number
+    /** Gap in px between a circle's edge and its outside label. Defaults to `gap`. */
+    labelGap?: number
+    /**
+     * Fixed pool height in px. When omitted, the height is derived from the
+     * measured width and the total bubble area so the cluster fits comfortably.
+     * The cluster is always confined to the `width × height` box and never
+     * overflows.
+     */
+    height?: number
+    /** Default label placement for every bubble. Defaults to `auto`. */
+    labelPlacement?: ClusterBubbleLabelPlacement
+    /** Diameter (px) at/above which `auto` placement renders the label inside. Defaults to `88`. */
+    autoInsideMinSize?: number
+    /**
+     * Ordering of `appearance` colors assigned to bubbles that don't specify
+     * one. Cycles through this list in input order.
+     */
+    appearanceCycle?: string[]
+    /** Number of force-simulation iterations. Higher = more settled. Defaults to `500`. */
+    iterations?: number
+    /** Notified when a bubble is pressed. Makes every bubble pressable. */
+    onBubblePress?: (datum: BubbleDatum, index: number) => void
+    /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+    modes?: Record<string, any>
+    /** Container style override. */
+    style?: StyleProp<ViewStyle>
+    /** Accessibility label for the whole chart. */
+    accessibilityLabel?: string
+}
+
+const DEFAULT_APPEARANCE_CYCLE = [
+    'Primary',
+    'Secondary',
+    'Tertiary',
+    'Quaternary',
+    'Quinary',
+    'Senary',
+    'Neutral',
+]
+
+const toText = (node: React.ReactNode, fallback = ''): string =>
+    typeof node === 'string' || typeof node === 'number' ? String(node) : fallback
+
+type RenderBubble = {
+    datum: BubbleDatum
+    index: number
+    appearance: string
+    placement: 'inside' | 'outside'
+    direction: ClusterBubbleLabelDirection
+    left: number
+    top: number
+    size: number
+}
+
+/**
+ * `BubbleChart` arranges a set of `ClusterBubble`s with a lightweight **force
+ * simulation** — bubbles repel one another (collision), a gentle gravity keeps
+ * the cluster balanced, and the container box acts as the walls of a pool, so
+ * nothing ever overflows. Each datum's `value` drives its area (`sqrt`-scaled),
+ * colors resolve from the `dataViz/bg` token via a cycling `appearance`, and the
+ * emphasis comes from the `Emphasis / DataViz` mode. When a bubble is too small
+ * to hold its text, the label is anchored just outside the circle on whichever
+ * side has the most free space.
+ *
+ * @component
+ */
+function BubbleChart({
+    data,
+    minBubbleSize = 48,
+    maxBubbleSize = 170,
+    gap = 8,
+    labelGap,
+    height,
+    labelPlacement = 'auto',
+    autoInsideMinSize = 88,
+    appearanceCycle = DEFAULT_APPEARANCE_CYCLE,
+    iterations = 500,
+    onBubblePress,
+    modes: propModes = EMPTY_MODES,
+    style,
+    accessibilityLabel,
+}: BubbleChartProps) {
+    const modes = propModes
+    const resolvedLabelGap = labelGap ?? gap
+
+    const [width, setWidth] = useState(0)
+
+    const handleLayout = useCallback((e: LayoutChangeEvent) => {
+        const w = e.nativeEvent.layout.width
+        setWidth((prev) => (Math.abs(prev - w) > 0.5 ? w : prev))
+    }, [])
+
+    const layout = useMemo(() => {
+        if (data.length === 0 || width <= 0) {
+            return { bubbles: [] as RenderBubble[], poolHeight: height ?? 0 }
+        }
+
+        const minR = Math.max(1, minBubbleSize / 2)
+        const maxR = Math.max(minR, maxBubbleSize / 2)
+        const baseRadii = scaleRadii(
+            data.map((d) => d.value),
+            minR,
+            maxR
+        )
+
+        // Estimate label sizes up front (independent of radius) so we can
+        // reserve a margin band around the bubbles for any outside labels.
+        const labelEstimates: LabelBox[] = data.map((d) =>
+            estimateLabelBox(toText(d.display, String(d.value)), toText(d.label))
+        )
+        const mayHaveOutside =
+            labelPlacement !== 'inside' &&
+            (minBubbleSize < autoInsideMinSize ||
+                data.some((d) => d.labelPlacement === 'outside'))
+        let insetX = gap
+        let insetY = gap
+        if (mayHaveOutside) {
+            let maxHalfW = 0
+            let maxH = 0
+            for (const e of labelEstimates) {
+                if (e.w / 2 > maxHalfW) maxHalfW = e.w / 2
+                if (e.h > maxH) maxH = e.h
+            }
+            insetX = Math.max(gap, maxHalfW + resolvedLabelGap)
+            insetY = Math.max(gap, maxH + resolvedLabelGap)
+        }
+
+        // Derive a pool height from the bubble area when none is supplied, then
+        // shrink radii (if needed) so everything fits inside the inner box.
+        let circleArea = 0
+        for (const r of baseRadii) circleArea += Math.PI * r * r
+        const derivedHeight = Math.min(
+            width * 1.35,
+            Math.max(width * 0.6, circleArea / 0.42 / width + 2 * insetY)
+        )
+        const poolHeight = Math.max(1, height ?? derivedHeight)
+
+        const innerW = Math.max(1, width - 2 * insetX)
+        const innerH = Math.max(1, poolHeight - 2 * insetY)
+
+        const radii = fitRadiiToBox(baseRadii, innerW, innerH, {
+            density: 0.5,
+            labelArea: 0,
+            minRadius: 6,
+        })
+
+        // Resolve placement per bubble (outside-labelled bubbles want the
+        // perimeter so their labels reach the open band along the walls).
+        const placements: Array<'inside' | 'outside'> = data.map((d, i) => {
+            const pref = d.labelPlacement ?? labelPlacement
+            const diameter = (radii[i] ?? 0) * 2
+            if (pref === 'auto') return diameter >= autoInsideMinSize ? 'inside' : 'outside'
+            return pref
+        })
+        const perimeter = placements.map((p) => p === 'outside')
+
+        const nodes = simulateCluster(radii, {
+            width,
+            height: poolHeight,
+            gap,
+            iterations,
+            insetX,
+            insetY,
+            perimeter,
+        })
+
+        const labelBoxes: Array<LabelBox | null> = data.map((d, i) => {
+            if (placements[i] !== 'outside') return null
+            const v = toText(d.display, String(d.value))
+            const l = toText(d.label)
+            if (!v && !l) return null
+            return labelEstimates[i] ?? estimateLabelBox(v, l)
+        })
+
+        const directions = chooseLabelDirections(nodes, labelBoxes, {
+            width,
+            height: poolHeight,
+            gap: resolvedLabelGap,
+        })
+
+        const bubbles: RenderBubble[] = data.map((datum, index) => {
+            const node = nodes[index]!
+            const r = radii[index] ?? 0
+            return {
+                datum,
+                index,
+                appearance:
+                    datum.appearance ??
+                    appearanceCycle[index % appearanceCycle.length] ??
+                    'Primary',
+                placement: placements[index] ?? 'inside',
+                direction: directions[index] ?? 'bottom',
+                left: node.x - r,
+                top: node.y - r,
+                size: r * 2,
+            }
+        })
+
+        return { bubbles, poolHeight }
+    }, [
+        data,
+        width,
+        height,
+        minBubbleSize,
+        maxBubbleSize,
+        gap,
+        resolvedLabelGap,
+        labelPlacement,
+        autoInsideMinSize,
+        appearanceCycle,
+        iterations,
+    ])
+
+    return (
+        <View
+            style={[styles.container, { height: layout.poolHeight }, style]}
+            onLayout={handleLayout}
+            accessibilityRole="image"
+            accessibilityLabel={accessibilityLabel}
+        >
+            {layout.bubbles.map((b) => (
+                <View
+                    key={b.datum.id ?? b.index}
+                    style={[styles.bubble, { left: b.left, top: b.top }]}
+                    pointerEvents="box-none"
+                >
+                    <ClusterBubble
+                        size={b.size}
+                        value={b.datum.display ?? String(b.datum.value)}
+                        label={b.datum.label}
+                        appearance={b.appearance}
+                        labelPlacement={b.placement}
+                        labelDirection={b.direction}
+                        labelGap={resolvedLabelGap}
+                        autoInsideMinSize={autoInsideMinSize}
+                        modes={modes}
+                        {...(b.datum.color ? { color: b.datum.color } : null)}
+                        {...(b.datum.accessibilityLabel
+                            ? { accessibilityLabel: b.datum.accessibilityLabel }
+                            : null)}
+                        {...(onBubblePress
+                            ? { onPress: () => onBubblePress(b.datum, b.index) }
+                            : null)}
+                    />
+                </View>
+            ))}
+        </View>
+    )
+}
+
+const styles = StyleSheet.create({
+    container: {
+        width: '100%',
+        position: 'relative',
+        overflow: 'hidden',
+    },
+    bubble: {
+        position: 'absolute',
+    },
+})
+
+export default BubbleChart