jfs-components 0.0.84 → 0.0.86

package/src/components/BubbleChart/bubblePacking.ts

@@ -0,0 +1,397 @@
+/**
+ * Dependency-free layout math for `BubbleChart`.
+ *
+ * Instead of a rigid ring, bubbles are arranged with a small **force
+ * simulation** — think of bubbles floating in a rectangular pool: each one
+ * repels the others (collision), a gentle pull keeps the cluster balanced
+ * (gravity), and the pool walls confine everything inside the container box so
+ * nothing overflows. Radii are first `sqrt`-scaled from the data magnitudes and
+ * down-scaled to fit the available area. Finally, for bubbles whose text must
+ * sit *outside* the circle, a direction chooser picks the side (top / bottom /
+ * left / right) with the most free space so labels avoid further collisions.
+ */
+
+export type LabelDirection = 'top' | 'bottom' | 'left' | 'right'
+
+export type PositionedNode = {
+    x: number
+    y: number
+    r: number
+}
+
+export type LabelBox = {
+    /** Estimated rendered width of the outside label, in px. */
+    w: number
+    /** Estimated rendered height of the outside label, in px. */
+    h: number
+}
+
+type Rect = { x: number; y: number; w: number; h: number }
+
+// --- Radius scaling --------------------------------------------------------
+
+/**
+ * Map magnitudes to radii so a bubble's *area* scales with its value
+ * (`sqrt`-encoding), clamped into `[minRadius, maxRadius]`.
+ */
+export function scaleRadii(magnitudes: number[], minRadius: number, maxRadius: number): number[] {
+    if (magnitudes.length === 0) return []
+
+    const safe = magnitudes.map((m) => (Number.isFinite(m) && m > 0 ? m : 0))
+    let lo = Infinity
+    let hi = -Infinity
+    for (const m of safe) {
+        if (m < lo) lo = m
+        if (m > hi) hi = m
+    }
+
+    if (!Number.isFinite(lo) || !Number.isFinite(hi) || hi <= 0 || hi === lo) {
+        return safe.map(() => maxRadius)
+    }
+
+    const sqrtLo = Math.sqrt(lo)
+    const sqrtHi = Math.sqrt(hi)
+    const span = sqrtHi - sqrtLo
+
+    return safe.map((m) => {
+        if (m <= 0) return minRadius
+        const t = span > 0 ? (Math.sqrt(m) - sqrtLo) / span : 1
+        return minRadius + t * (maxRadius - minRadius)
+    })
+}
+
+/**
+ * Uniformly shrink radii (preserving relative proportions) so the bubbles plus
+ * some breathing room and label allowance fit inside the `width × height` box.
+ * Returns the radii unchanged when they already fit.
+ */
+export function fitRadiiToBox(
+    radii: number[],
+    width: number,
+    height: number,
+    options: { density?: number; labelArea?: number; minRadius?: number } = {}
+): number[] {
+    const { density = 0.58, labelArea = 0, minRadius = 6 } = options
+    if (radii.length === 0 || width <= 0 || height <= 0) return radii
+
+    let circleArea = 0
+    for (const r of radii) circleArea += Math.PI * r * r
+
+    const required = circleArea / density + labelArea
+    const available = width * height
+    if (required <= available) return radii
+
+    // Area scales with the square of the linear factor; ignore the (non-scaling)
+    // label term in the factor for simplicity — the sim's hard clamp covers the
+    // small remainder.
+    const factor = Math.sqrt(Math.max(0.05, (available - labelArea) / circleArea) * density)
+    return radii.map((r) => Math.max(minRadius, r * Math.min(1, factor)))
+}
+
+// --- Force simulation ------------------------------------------------------
+
+/** Tiny deterministic PRNG so layouts are reproducible across renders. */
+function mulberry32(seed: number): () => number {
+    let s = seed >>> 0
+    return () => {
+        s = (s + 0x6d2b79f5) >>> 0
+        let t = s
+        t = Math.imul(t ^ (t >>> 15), t | 1)
+        t ^= t + Math.imul(t ^ (t >>> 7), t | 61)
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296
+    }
+}
+
+/**
+ * Arrange circles inside a `width × height` box with a collision + gravity
+ * relaxation. Bubbles never overlap (separated by at least `gap`) and are hard-
+ * clamped within the walls so the cluster stays inside the container.
+ */
+export function simulateCluster(
+    radii: number[],
+    options: {
+        width: number
+        height: number
+        gap?: number
+        iterations?: number
+        gravity?: number
+        /** Horizontal wall inset reserved for outside labels. */
+        insetX?: number
+        /** Vertical wall inset reserved for outside labels. */
+        insetY?: number
+        /**
+         * Per-node flag: `true` nodes are pulled toward the perimeter ring
+         * (instead of the center) so their outside labels reach the open band
+         * along the walls. Typically the small / outside-labelled bubbles.
+         */
+        perimeter?: boolean[]
+    }
+): PositionedNode[] {
+    const {
+        width,
+        height,
+        gap = 8,
+        iterations = 500,
+        gravity = 0.02,
+        insetX = 0,
+        insetY = 0,
+        perimeter,
+    } = options
+    const n = radii.length
+    const nodes: PositionedNode[] = radii.map((r) => ({ x: 0, y: 0, r }))
+    if (n === 0) return nodes
+
+    const cx = width / 2
+    const cy = height / 2
+    const rand = mulberry32(0x9e3779b9 ^ (n * 2654435761))
+
+    // Seed positions on a phyllotaxis spiral so the relaxation starts spread out.
+    const spread = Math.min(width - 2 * insetX, height - 2 * insetY) * 0.45
+    for (let i = 0; i < n; i++) {
+        const nd = nodes[i]!
+        const a = i * 2.399963229728653 // golden angle
+        const rad = Math.sqrt((i + 0.5) / n) * spread
+        nd.x = cx + Math.cos(a) * rad + (rand() - 0.5) * 2
+        nd.y = cy + Math.sin(a) * rad + (rand() - 0.5) * 2
+    }
+
+    const margin = gap / 2
+    let maxR = 0
+    for (const r of radii) if (r > maxR) maxR = r
+    maxR = maxR || 1
+
+    const clamp = () => {
+        for (const nd of nodes) {
+            const minX = insetX + nd.r + margin
+            const maxX = Math.max(minX, width - insetX - nd.r - margin)
+            const minY = insetY + nd.r + margin
+            const maxY = Math.max(minY, height - insetY - nd.r - margin)
+            nd.x = Math.min(maxX, Math.max(minX, nd.x))
+            nd.y = Math.min(maxY, Math.max(minY, nd.y))
+        }
+    }
+
+    for (let it = 0; it < iterations; it++) {
+        // Big bubbles are pulled to the center; "perimeter" bubbles (the small,
+        // outside-labelled ones) are pulled toward the wall ring so their labels
+        // land in the open band — like small bubbles floating around a big one.
+        for (let i = 0; i < n; i++) {
+            const nd = nodes[i]!
+            if (perimeter && perimeter[i]) {
+                const dx = nd.x - cx
+                const dy = nd.y - cy
+                const d = Math.sqrt(dx * dx + dy * dy) || 1
+                const targetD = Math.max(
+                    0,
+                    Math.min(
+                        width / 2 - insetX - nd.r - margin,
+                        height / 2 - insetY - nd.r - margin
+                    )
+                )
+                const f = ((targetD - d) / d) * gravity * 2
+                nd.x += dx * f
+                nd.y += dy * f
+            } else {
+                const ratio = nd.r / maxR
+                const g = gravity * (0.4 + 0.6 * ratio)
+                nd.x += (cx - nd.x) * g
+                nd.y += (cy - nd.y) * g
+            }
+        }
+
+        // Collision: push overlapping pairs apart. Two passes per tick keeps it
+        // stable for dense clusters. Smaller bubbles move more than bigger ones.
+        for (let pass = 0; pass < 2; pass++) {
+            for (let i = 0; i < n; i++) {
+                for (let j = i + 1; j < n; j++) {
+                    const a = nodes[i]!
+                    const b = nodes[j]!
+                    let dx = b.x - a.x
+                    let dy = b.y - a.y
+                    let dist = Math.sqrt(dx * dx + dy * dy)
+                    const min = a.r + b.r + gap
+                    if (dist < min) {
+                        if (dist < 1e-6) {
+                            dx = rand() - 0.5 || 0.01
+                            dy = rand() - 0.5 || 0.01
+                            dist = Math.sqrt(dx * dx + dy * dy)
+                        }
+                        const overlap = min - dist
+                        const ux = dx / dist
+                        const uy = dy / dist
+                        const total = a.r + b.r
+                        const aShare = b.r / total
+                        const bShare = a.r / total
+                        a.x -= ux * overlap * aShare
+                        a.y -= uy * overlap * aShare
+                        b.x += ux * overlap * bShare
+                        b.y += uy * overlap * bShare
+                    }
+                }
+            }
+            clamp()
+        }
+    }
+
+    return nodes
+}
+
+// --- Outside-label sizing + direction --------------------------------------
+
+/**
+ * Roughly estimate the rendered size of an outside label block (a bold value
+ * line stacked over a lighter caption line), used purely for layout scoring.
+ */
+export function estimateLabelBox(
+    value: string,
+    label: string,
+    options: { valueFontSize?: number; labelFontSize?: number } = {}
+): LabelBox {
+    const { valueFontSize = 24, labelFontSize = 14 } = options
+    // Slightly over-estimate width so the direction chooser reserves enough
+    // room and never picks a side that would clip the (wider) rendered text.
+    const valueW = value.length * valueFontSize * 0.68
+    const labelW = label.length * labelFontSize * 0.6
+    const valueH = value ? valueFontSize * 1.18 : 0
+    const labelH = label ? labelFontSize * 1.32 : 0
+    const gapBetween = value && label ? 2 : 0
+    return {
+        w: Math.max(valueW, labelW, 1),
+        h: Math.max(valueH + labelH + gapBetween, 1),
+    }
+}
+
+const DIRECTIONS: LabelDirection[] = ['bottom', 'right', 'left', 'top']
+
+function directionVector(dir: LabelDirection): { x: number; y: number } {
+    switch (dir) {
+        case 'top':
+            return { x: 0, y: -1 }
+        case 'bottom':
+            return { x: 0, y: 1 }
+        case 'left':
+            return { x: -1, y: 0 }
+        case 'right':
+            return { x: 1, y: 0 }
+    }
+}
+
+/** The rect an outside label occupies for a given direction (at `r + gap`). */
+function labelRect(node: PositionedNode, box: LabelBox, dir: LabelDirection, gap: number): Rect {
+    const { x: cx, y: cy, r } = node
+    switch (dir) {
+        case 'bottom':
+            return { x: cx - box.w / 2, y: cy + r + gap, w: box.w, h: box.h }
+        case 'top':
+            return { x: cx - box.w / 2, y: cy - r - gap - box.h, w: box.w, h: box.h }
+        case 'right':
+            return { x: cx + r + gap, y: cy - box.h / 2, w: box.w, h: box.h }
+        case 'left':
+            return { x: cx - r - gap - box.w, y: cy - box.h / 2, w: box.w, h: box.h }
+    }
+}
+
+function rectOverlapArea(a: Rect, b: Rect): number {
+    const ox = Math.max(0, Math.min(a.x + a.w, b.x + b.w) - Math.max(a.x, b.x))
+    const oy = Math.max(0, Math.min(a.y + a.h, b.y + b.h) - Math.max(a.y, b.y))
+    return ox * oy
+}
+
+/** Approximate a circle as its bounding square for cheap rect/circle overlap. */
+function rectCircleOverlap(rect: Rect, node: PositionedNode): number {
+    const circleRect: Rect = {
+        x: node.x - node.r,
+        y: node.y - node.r,
+        w: node.r * 2,
+        h: node.r * 2,
+    }
+    return rectOverlapArea(rect, circleRect)
+}
+
+/**
+ * For each node that has an outside label (`labels[i]` non-null), pick the
+ * direction whose label rect best avoids the other circles, already-placed
+ * labels, and the container walls — biased to point *outward* (away from the
+ * cluster centroid, toward free space).
+ *
+ * Returns a direction per node, or `null` for nodes without an outside label.
+ */
+export function chooseLabelDirections(
+    nodes: PositionedNode[],
+    labels: Array<LabelBox | null>,
+    options: { width: number; height: number; gap?: number }
+): Array<LabelDirection | null> {
+    const { width, height, gap = 8 } = options
+    const result: Array<LabelDirection | null> = nodes.map(() => null)
+    if (nodes.length === 0) return result
+
+    let gx = 0
+    let gy = 0
+    for (const nd of nodes) {
+        gx += nd.x
+        gy += nd.y
+    }
+    gx /= nodes.length
+    gy /= nodes.length
+
+    // Place outer bubbles first — they sit near free space and deserve the best slot.
+    const order = nodes
+        .map((_, i) => i)
+        .filter((i) => labels[i])
+        .sort((a, b) => {
+            const na = nodes[a]!
+            const nb = nodes[b]!
+            const da = (na.x - gx) ** 2 + (na.y - gy) ** 2
+            const db = (nb.x - gx) ** 2 + (nb.y - gy) ** 2
+            return db - da
+        })
+
+    const placed: Rect[] = []
+
+    for (const i of order) {
+        const node = nodes[i]!
+        const box = labels[i]!
+        const ox = node.x - gx
+        const oy = node.y - gy
+        const outLen = Math.hypot(ox, oy) || 1
+
+        let best: LabelDirection = 'bottom'
+        let bestScore = Infinity
+
+        for (const dir of DIRECTIONS) {
+            const rect = labelRect(node, box, dir, gap)
+            let score = 0
+
+            // Out-of-bounds is forbidden whenever any in-bounds option exists:
+            // a clipped label is the worst possible outcome. A large fixed
+            // penalty plus a proportional term enforces this.
+            const outX = Math.max(0, -rect.x) + Math.max(0, rect.x + rect.w - width)
+            const outY = Math.max(0, -rect.y) + Math.max(0, rect.y + rect.h - height)
+            if (outX > 0 || outY > 0) score += 1_000_000 + (outX + outY) * 150
+
+            // Overlap with other circles.
+            for (let k = 0; k < nodes.length; k++) {
+                if (k === i) continue
+                score += rectCircleOverlap(rect, nodes[k]!)
+            }
+
+            // Overlap with previously-placed labels (penalized extra to spread).
+            for (const p of placed) score += rectOverlapArea(rect, p) * 2
+
+            // Mild preference for pointing outward (toward open space).
+            const dv = directionVector(dir)
+            const align = (dv.x * ox + dv.y * oy) / outLen // -1..1
+            score += (1 - align) * 15
+
+            if (score < bestScore) {
+                bestScore = score
+                best = dir
+            }
+        }
+
+        result[i] = best
+        placed.push(labelRect(node, box, best, gap))
+    }
+
+    return result
+}