jfs-components 0.0.84 → 0.0.85

package/src/components/AreaLineChart/chartMath.ts

@@ -0,0 +1,265 @@
+/**
+ * Pure, framework-agnostic math helpers for `AreaLineChart`.
+ *
+ * Everything here is intentionally dependency-free (no d3, no react-native)
+ * so the chart can stay lightweight and be unit-reasoned in isolation. The
+ * functions cover the four primitives a line/area chart needs:
+ *   1. linear scales (data domain -> pixel range)
+ *   2. "nice" tick generation for the value axis
+ *   3. SVG path generation for lines and filled areas (straight + smooth)
+ *   4. interaction lookup (which data index is nearest a touch x)
+ */
+
+/** A resolved point in data space. `x` is the categorical/linear index. */
+export type ResolvedPoint = {
+    /** Position along the x domain (defaults to the array index). */
+    x: number
+    /** Value along the y domain. */
+    y: number
+    /**
+     * When true, the line segment that *ends* at this point is rendered
+     * dashed (used for projected / low-confidence data).
+     */
+    projected: boolean
+}
+
+/** A point already projected into pixel space. */
+export type PixelPoint = { x: number; y: number; projected: boolean }
+
+/** Linear interpolation scale: maps a value from `domain` into `range`. */
+export type LinearScale = {
+    (value: number): number
+    domain: readonly [number, number]
+    range: readonly [number, number]
+}
+
+/**
+ * Create a linear scale mapping `domain` -> `range`. Mirrors the subset of
+ * `d3-scale.scaleLinear` we rely on, without the dependency. A zero-width
+ * domain collapses to the midpoint of the range so we never divide by zero.
+ */
+export function createLinearScale(
+    domain: readonly [number, number],
+    range: readonly [number, number]
+): LinearScale {
+    const [d0, d1] = domain
+    const [r0, r1] = range
+    const domainSpan = d1 - d0
+
+    const scale = ((value: number): number => {
+        if (domainSpan === 0) {
+            return (r0 + r1) / 2
+        }
+        const t = (value - d0) / domainSpan
+        return r0 + t * (r1 - r0)
+    }) as LinearScale
+
+    scale.domain = domain
+    scale.range = range
+    return scale
+}
+
+/**
+ * Generate up to ~`count` "nice" evenly-spaced tick values spanning
+ * `[min, max]`, snapping the step to a 1/2/5 * 10^n progression so labels
+ * read cleanly (e.g. 0, 30K, 60K, 90K). Returns ascending values that
+ * always include the rounded-down min and rounded-up max bounds.
+ */
+export function niceTicks(min: number, max: number, count = 5): number[] {
+    if (!Number.isFinite(min) || !Number.isFinite(max)) {
+        return []
+    }
+    if (min === max) {
+        return [min]
+    }
+    const safeCount = Math.max(1, Math.floor(count))
+    const span = max - min
+    const rawStep = span / safeCount
+    const magnitude = Math.pow(10, Math.floor(Math.log10(rawStep)))
+    const normalized = rawStep / magnitude
+
+    let niceNormalized: number
+    if (normalized <= 1) niceNormalized = 1
+    else if (normalized <= 2) niceNormalized = 2
+    else if (normalized <= 5) niceNormalized = 5
+    else niceNormalized = 10
+
+    const step = niceNormalized * magnitude
+    const niceMin = Math.floor(min / step) * step
+    const niceMax = Math.ceil(max / step) * step
+
+    const ticks: number[] = []
+    // Guard against floating point drift by rounding to the step's precision.
+    const decimals = Math.max(0, -Math.floor(Math.log10(step)))
+    for (let v = niceMin; v <= niceMax + step / 2; v += step) {
+        ticks.push(Number(v.toFixed(decimals)))
+    }
+    return ticks
+}
+
+/**
+ * Compute the [min, max] extent of an array of resolved points along the
+ * requested axis. Returns `[0, 0]` for an empty list.
+ */
+export function extent(points: ResolvedPoint[], axis: 'x' | 'y'): [number, number] {
+    if (points.length === 0) {
+        return [0, 0]
+    }
+    let min = Infinity
+    let max = -Infinity
+    for (const p of points) {
+        const v = p[axis]
+        if (v < min) min = v
+        if (v > max) max = v
+    }
+    return [min, max]
+}
+
+/**
+ * Normalize the loose `number[] | ChartPoint[]` series data into a uniform
+ * `ResolvedPoint[]`. Bare numbers use their array index as the x value.
+ */
+export function resolvePoints(
+    data: ReadonlyArray<number | { x?: number | string; y: number; projected?: boolean }>
+): ResolvedPoint[] {
+    return data.map((entry, index) => {
+        if (typeof entry === 'number') {
+            return { x: index, y: entry, projected: false }
+        }
+        const x = typeof entry.x === 'number' ? entry.x : index
+        return { x, y: entry.y, projected: entry.projected === true }
+    })
+}
+
+/**
+ * Catmull-Rom -> cubic Bézier control point helper. Produces a smooth,
+ * monotone-ish curve through the points without overshooting wildly. Used
+ * for the `curve="monotone"` mode. `tension` of 0 yields a standard
+ * Catmull-Rom spline.
+ */
+function controlPoints(
+    p0: PixelPoint,
+    p1: PixelPoint,
+    p2: PixelPoint,
+    p3: PixelPoint
+): { cp1x: number; cp1y: number; cp2x: number; cp2y: number } {
+    const t = 1 / 6
+    return {
+        cp1x: p1.x + (p2.x - p0.x) * t,
+        cp1y: p1.y + (p2.y - p0.y) * t,
+        cp2x: p2.x - (p3.x - p1.x) * t,
+        cp2y: p2.y - (p3.y - p1.y) * t,
+    }
+}
+
+export type Curve = 'linear' | 'monotone'
+
+/**
+ * One drawable line segment. `dashed` mirrors the `projected` flag of the
+ * point the segment ends at, letting the renderer split the polyline into
+ * solid and dashed `Path`s.
+ */
+export type LineSegment = { d: string; dashed: boolean }
+
+/**
+ * Build the SVG path(s) for a polyline through `points`, split into runs of
+ * solid vs dashed segments. Each individual segment ("move to A, line/curve
+ * to B") is emitted as its own sub-path so that a single projected point can
+ * dash exactly one segment while leaving its neighbours solid.
+ */
+export function buildLineSegments(points: PixelPoint[], curve: Curve): LineSegment[] {
+    if (points.length < 2) {
+        return []
+    }
+
+    const segments: LineSegment[] = []
+
+    for (let i = 0; i < points.length - 1; i++) {
+        const start = points[i]
+        const end = points[i + 1]
+        const dashed = end.projected
+
+        let d: string
+        if (curve === 'monotone') {
+            const p0 = points[i - 1] ?? start
+            const p3 = points[i + 2] ?? end
+            const { cp1x, cp1y, cp2x, cp2y } = controlPoints(p0, start, end, p3)
+            d = `M ${start.x} ${start.y} C ${cp1x} ${cp1y} ${cp2x} ${cp2y} ${end.x} ${end.y}`
+        } else {
+            d = `M ${start.x} ${start.y} L ${end.x} ${end.y}`
+        }
+        segments.push({ d, dashed })
+    }
+
+    // Merge adjacent segments that share the same dashed-ness into one path
+    // string to minimize the number of rendered <Path> nodes.
+    const merged: LineSegment[] = []
+    for (const seg of segments) {
+        const last = merged[merged.length - 1]
+        if (last && last.dashed === seg.dashed) {
+            // Drop the redundant leading "M x y" of the appended segment.
+            const continuation = seg.d.replace(/^M [^A-Za-z]+/, '')
+            last.d += ' ' + continuation
+        } else {
+            merged.push({ ...seg })
+        }
+    }
+    return merged
+}
+
+/**
+ * Build a single closed area path (the line, then down to `baselineY` and
+ * back) for a filled area fill. Curve smoothing matches `buildLineSegments`.
+ */
+export function buildAreaPath(
+    points: PixelPoint[],
+    baselineY: number,
+    curve: Curve
+): string {
+    if (points.length === 0) {
+        return ''
+    }
+    if (points.length === 1) {
+        const p = points[0]
+        return `M ${p.x} ${baselineY} L ${p.x} ${p.y} Z`
+    }
+
+    let d = `M ${points[0].x} ${baselineY} L ${points[0].x} ${points[0].y}`
+
+    for (let i = 0; i < points.length - 1; i++) {
+        const start = points[i]
+        const end = points[i + 1]
+        if (curve === 'monotone') {
+            const p0 = points[i - 1] ?? start
+            const p3 = points[i + 2] ?? end
+            const { cp1x, cp1y, cp2x, cp2y } = controlPoints(p0, start, end, p3)
+            d += ` C ${cp1x} ${cp1y} ${cp2x} ${cp2y} ${end.x} ${end.y}`
+        } else {
+            d += ` L ${end.x} ${end.y}`
+        }
+    }
+
+    const lastX = points[points.length - 1].x
+    d += ` L ${lastX} ${baselineY} Z`
+    return d
+}
+
+/**
+ * Find the index of the point whose pixel-x is nearest to `targetX`. Used to
+ * snap the crosshair / tooltip to the closest data point during hover/drag.
+ */
+export function nearestIndex(pixelXs: number[], targetX: number): number {
+    if (pixelXs.length === 0) {
+        return -1
+    }
+    let best = 0
+    let bestDist = Infinity
+    for (let i = 0; i < pixelXs.length; i++) {
+        const dist = Math.abs(pixelXs[i] - targetX)
+        if (dist < bestDist) {
+            bestDist = dist
+            best = i
+        }
+    }
+    return best
+}

package/src/components/Attached/Attached.tsx

@@ -7,6 +7,7 @@ import {
   type ViewStyle,
 } from 'react-native'
 import { useTokens } from '../../design-tokens/JFSThemeProvider'
+import { getVariableByName } from '../../design-tokens/figma-variables-resolver'
 import { cloneChildrenWithModes, EMPTY_MODES } from '../../utils/react-utils'
 
 /**
@@ -178,6 +179,32 @@ function Attached({
     }
   }, [badgeSize, badgeRadius])
 
+  // Forced slot ring. Like the corner radius, the border color/width are driven
+  // by design tokens (`attached/slot/border`, `attached/slot/borderWidth`) and
+  // applied to the slot regardless of the node passed. Rendered as an *outside*
+  // border: the ring lives on a wrapper that is pulled out by `-borderWidth` on
+  // every side (negative margin) so it grows outward instead of eating into the
+  // content, and its layout footprint stays equal to the slot box (keeping the
+  // anchor centering intact).
+  const slotBorderStyle = useMemo<ViewStyle | null>(() => {
+    const borderColor = getVariableByName('attached/slot/border', modes)
+    const borderWidth = parseFloat(getVariableByName('attached/slot/borderWidth', modes) || '0')
+    if (!borderColor || !(borderWidth > 0)) return null
+
+    // Match the inner clip radius so the ring stays concentric. The outer edge
+    // sits `borderWidth` further out, hence `innerRadius + borderWidth`.
+    const innerRadius =
+      badgeBoxStyle != null
+        ? (badgeBoxStyle.borderRadius as number)
+        : badgeRadius ?? 9999
+    return {
+      borderWidth,
+      borderColor,
+      borderRadius: (typeof innerRadius === 'number' ? innerRadius : 9999) + borderWidth,
+      margin: -borderWidth,
+    }
+  }, [modes, badgeBoxStyle, badgeRadius])
+
   const badgePlacement = useMemo<ViewStyle>(() => {
     const { fx, fy } = resolveAnchorFractions(position)
     const measured = mainSize.width > 0 && measuredBadgeSize.width > 0
@@ -214,11 +241,15 @@ function Attached({
       <View onLayout={onMainLayout}>{mainChildren}</View>
       {badgeChildren != null && (
         <View style={badgePlacement} onLayout={onBadgeLayout} pointerEvents="box-none">
-          {badgeBoxStyle != null ? (
-            <View style={badgeBoxStyle}>{forceBadgeFill(badgeChildren)}</View>
-          ) : (
-            badgeChildren
-          )}
+          {(() => {
+            const slot =
+              badgeBoxStyle != null ? (
+                <View style={badgeBoxStyle}>{forceBadgeFill(badgeChildren)}</View>
+              ) : (
+                badgeChildren
+              )
+            return slotBorderStyle != null ? <View style={slotBorderStyle}>{slot}</View> : slot
+          })()}
         </View>
       )}
     </View>

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