jfs-components 0.0.84 → 0.0.86

package/lib/typescript/src/components/AllocationComparisonChart/AllocationComparisonChart.d.ts

@@ -0,0 +1,118 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+/**
+ * One vertical pill in the {@link AllocationComparisonChartProps.data} array.
+ *
+ * Each segment renders a single bar whose **height encodes `value`** (the
+ * "current" reading) and, when supplied, a **`baseline`** overlay drawn from
+ * the bottom up with a dashed marker line (the "recommended" reading). Both
+ * are measured against the same shared scale so bars and baselines are
+ * directly comparable across segments.
+ */
+export type AllocationSegment = {
+    /** Stable React key (falls back to the array index). */
+    key?: React.Key;
+    /** Caption rendered under the bar — e.g. `"Small & Mid"`. */
+    label: React.ReactNode;
+    /**
+     * Primary value driving the bar's height (the "current" reading). Scaled
+     * against {@link AllocationComparisonChartProps.max}.
+     */
+    value: number;
+    /**
+     * Optional comparison value (the "recommended" reading). When provided, a
+     * filled overlay is drawn from the bottom of the bar up to this level.
+     * Omit to render a plain bar.
+     */
+    baseline?: number;
+    /**
+     * Whether to draw the dashed reference line + value label at the top of the
+     * `baseline` overlay. Defaults to `true` **only for the first segment that
+     * has a `baseline`** and `false` for the rest, so the marker stays a
+     * focused callout rather than repeating on every bar. Set explicitly to
+     * force it on/off per segment. Has no effect without a `baseline`.
+     */
+    showMarker?: boolean;
+    /**
+     * Text shown above the bar. Defaults to `formatValue(value)`. Pass `null`
+     * to hide it.
+     */
+    valueLabel?: React.ReactNode;
+    /**
+     * Text shown beside the dashed baseline marker. Defaults to
+     * `formatValue(baseline)`. Pass `null` to hide just the marker label while
+     * keeping the dashed line.
+     */
+    baselineLabel?: React.ReactNode;
+    /** Hard-override the bar (current) fill color. */
+    color?: string;
+    /** Hard-override the baseline (recommended) overlay color. */
+    baselineColor?: string;
+    /** Per-segment accessibility label. */
+    accessibilityLabel?: string;
+};
+export type AllocationComparisonChartProps = {
+    /**
+     * The segments to plot, left → right. Each carries its `value`, optional
+     * `baseline` and its `label`, so a bar can never drift from its caption.
+     */
+    data?: AllocationSegment[];
+    /**
+     * Maximum value used to scale every bar **and** baseline. Defaults to the
+     * largest `value`/`baseline` across `data`. Pass an explicit `max` (e.g.
+     * `100` for percentages) for a fixed scale.
+     */
+    max?: number;
+    /**
+     * Height in px of the bar area — i.e. the height of a bar whose value
+     * equals `max`. Excludes the value/caption label rows. Default: `154`.
+     */
+    height?: number;
+    /** Width of each pill bar in px. Default: the `segmentIndicator/track/width` token (`28`). */
+    barWidth?: number;
+    /** Show the legend row above the chart. Default: `true`. */
+    showLegend?: boolean;
+    /** Legend label for the bar (current) series. Default: `"Current"`. */
+    valueLegendLabel?: React.ReactNode;
+    /**
+     * Legend label for the baseline (recommended) series. Default:
+     * `"Recommended"`. The baseline legend item only appears when at least one
+     * segment defines a `baseline`.
+     */
+    baselineLegendLabel?: React.ReactNode;
+    /**
+     * Formats numeric `value`/`baseline` into the default labels. Default:
+     * `(v) => \`${v}%\``.
+     */
+    formatValue?: (value: number) => string;
+    /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+    modes?: Record<string, any>;
+    /** Container style override. */
+    style?: StyleProp<ViewStyle>;
+    /** Style applied to the bars row. */
+    chartStyle?: StyleProp<ViewStyle>;
+    /** Style applied to the legend row. */
+    legendStyle?: StyleProp<ViewStyle>;
+    /** Accessibility label for the whole chart. */
+    accessibilityLabel?: string;
+};
+/**
+ * `AllocationComparisonChart` plots a row of vertical pill bars that compare a
+ * **current** reading (each bar's height) against an optional **recommended**
+ * baseline (a filled overlay drawn from the bottom up, marked with a dashed
+ * line). Every bar and baseline shares a single scale, so heights are directly
+ * comparable across segments — no axes required.
+ *
+ * The chart is driven entirely by the `data` array: each entry pairs a
+ * `value`, an optional `baseline` and its `label`, so a bar can never drift
+ * out of sync with its caption or its baseline marker.
+ *
+ * Colors, fonts, spacing and the pill radius resolve from the Figma
+ * `segmentIndicator/*`, `metricLegendItem/*` and `allocationComparisonChart/*`
+ * tokens via the `modes` prop.
+ *
+ * @component
+ */
+declare function AllocationComparisonChart({ data, max, height, barWidth, showLegend, valueLegendLabel, baselineLegendLabel, formatValue, modes: propModes, style, chartStyle, legendStyle, accessibilityLabel, }: AllocationComparisonChartProps): import("react/jsx-runtime").JSX.Element;
+export default AllocationComparisonChart;
+//# sourceMappingURL=AllocationComparisonChart.d.ts.map

package/lib/typescript/src/components/AreaLineChart/AreaLineChart.d.ts

@@ -0,0 +1,212 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import { type Curve, type LinearScale, type ResolvedPoint } from './chartMath';
+/** A single data point. Bare numbers are also accepted in `data`. */
+export type ChartPoint = {
+    /** Position on the x domain. Defaults to the array index. */
+    x?: number | string;
+    /** Value on the y domain. */
+    y: number;
+    /**
+     * Marks this point as projected / low-confidence. The line segment
+     * ending at this point is rendered dashed.
+     */
+    projected?: boolean;
+};
+/** One line+area series. Pass one for a single chart, several to overlap. */
+export type ChartSeries = {
+    /** Stable React key. */
+    key?: React.Key;
+    /** The data, either bare y-values or `ChartPoint`s. */
+    data: Array<number | ChartPoint>;
+    /** Legend / tooltip label. */
+    label?: string;
+    /**
+     * `Appearance / DataViz` mode used to resolve the series color from the
+     * `dataViz/bg` token (e.g. `Primary`, `Secondary`). Defaults cycle.
+     */
+    appearance?: string;
+    /** Hard-override the line + dot color (bypasses token resolution). */
+    color?: string;
+    /** Hard-override the area fill color (bypasses token resolution). */
+    areaColor?: string;
+    /** Whether to render the filled area. Defaults to `true`. */
+    showArea?: boolean;
+    /** Whether to render the line stroke. Defaults to `true`. */
+    showLine?: boolean;
+};
+export type ChartInset = {
+    top?: number;
+    bottom?: number;
+    left?: number;
+    right?: number;
+};
+export type GoalPinConfig = {
+    /** Pill content. */
+    value: React.ReactNode;
+    /** Data index the pin anchors to. Defaults to the last point. */
+    atIndex?: number;
+    /** Which series the pin anchors to. Defaults to `0`. */
+    seriesIndex?: number;
+};
+export type AreaLineChartProps = {
+    /**
+     * The series to plot. A single entry renders the "Area Line Chart"
+     * preset; multiple entries render the overlapping multi-series preset
+     * with an automatic legend.
+     */
+    series: ChartSeries[];
+    /** Labels rendered along the x axis (left-to-right). */
+    xLabels?: Array<string | number>;
+    /** Force the lower bound of the y domain. */
+    yMin?: number;
+    /** Force the upper bound of the y domain. */
+    yMax?: number;
+    /** Approximate number of y-axis ticks / grid lines. Defaults to `4`. */
+    numberOfTicks?: number;
+    /** Interpolation between points. Defaults to `linear` (straight segments). */
+    curve?: Curve;
+    /** Plot drawing height in px (excludes the x-axis row). Defaults to `218`. */
+    height?: number;
+    /** Fake margin inside the SVG so strokes/dots/pins are not clipped. */
+    contentInset?: ChartInset;
+    /** Toggle the background grid. Defaults to `true`. */
+    showGrid?: boolean;
+    /** Toggle the x-axis labels. Defaults to `true`. */
+    showXAxis?: boolean;
+    /** Toggle the y-axis labels. Defaults to `true`. */
+    showYAxis?: boolean;
+    /** Toggle the legend (multi-series only). Defaults to `true`. */
+    showLegend?: boolean;
+    /** Render a dot on every data point. Defaults to `false`. */
+    showDots?: boolean;
+    /** Format an x label. Receives the raw label and index. */
+    formatX?: (label: string | number, index: number) => React.ReactNode;
+    /** Format a y-axis tick label. */
+    formatY?: (value: number) => React.ReactNode;
+    /** Format a value shown in the tooltip. Defaults to `formatY`. */
+    formatValue?: (value: number, series: ChartSeries) => React.ReactNode;
+    /** Render a goal pin anchored to a data point. */
+    goalPin?: GoalPinConfig;
+    /** Controlled active index (the highlighted point). */
+    activeIndex?: number | null;
+    /** Initial active index for the uncontrolled case. */
+    defaultActiveIndex?: number | null;
+    /** Notified whenever the active index changes. */
+    onActiveIndexChange?: (index: number | null) => void;
+    /** Enable hover/press-drag interaction + tooltip. Defaults to `true`. */
+    interactive?: boolean;
+    /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+    modes?: Record<string, any>;
+    /** Container style override. */
+    style?: StyleProp<ViewStyle>;
+    /** Extra SVG-decorator children rendered on top of the default layers. */
+    children?: React.ReactNode;
+    /** Accessibility label for the whole chart. */
+    accessibilityLabel?: string;
+};
+type ResolvedSeries = {
+    key: React.Key;
+    label?: string;
+    appearance: string;
+    lineColor: string;
+    areaColor: string;
+    showArea: boolean;
+    showLine: boolean;
+    points: ResolvedPoint[];
+};
+type ChartContextValue = {
+    width: number;
+    height: number;
+    inset: Required<ChartInset>;
+    xScale: LinearScale;
+    yScale: LinearScale;
+    yTicks: number[];
+    /** Pixel x position for each canonical data index. */
+    indexXs: number[];
+    /** Number of canonical data points. */
+    count: number;
+    series: ResolvedSeries[];
+    curve: Curve;
+    activeIndex: number | null;
+    setActiveIndex: (index: number | null) => void;
+    xLabels?: Array<string | number>;
+    formatX: (label: string | number, index: number) => React.ReactNode;
+    formatY: (value: number) => React.ReactNode;
+    showDots: boolean;
+    modes: Record<string, any>;
+};
+/** Access the surrounding chart geometry from a decorator/sub-component. */
+export declare function useChart(): ChartContextValue;
+/**
+ * `AreaLineChart` is a lightweight, token-driven area/line chart built
+ * entirely on `react-native-svg`. A single `series` renders one filled
+ * area with a line on top (plus an optional goal pin); multiple `series`
+ * overlap with an automatic legend. It supports smooth/linear curves,
+ * dashed "projected" segments, a configurable grid and axes, and a
+ * cross-platform crosshair tooltip (hover on web, press-drag on native).
+ *
+ * The reusable building blocks (`AreaLineChart.Grid`, `.XAxis`, `.YAxis`,
+ * `.GoalPin`) read the shared chart geometry through `useChart()`, so you
+ * can also compose them manually or add your own SVG decorators as
+ * children.
+ *
+ * @component
+ */
+declare function AreaLineChart({ series, xLabels, yMin, yMax, numberOfTicks, curve, height, contentInset, showGrid, showXAxis, showYAxis, showLegend, showDots, formatX, formatY, formatValue, goalPin, activeIndex: activeIndexProp, defaultActiveIndex, onActiveIndexChange, interactive, modes: propModes, style, children, accessibilityLabel, }: AreaLineChartProps): import("react/jsx-runtime").JSX.Element;
+declare namespace AreaLineChart {
+    var Grid: typeof ChartGrid;
+    var XAxis: typeof ChartXAxis;
+    var YAxis: typeof ChartYAxis;
+    var GoalPin: typeof ChartGoalPin;
+}
+export type ChartGridProps = {
+    /** Which grid lines to draw. Defaults to `horizontal`. */
+    direction?: 'horizontal' | 'vertical' | 'both';
+    /** Stroke color. Defaults to a subtle grey. */
+    stroke?: string;
+    /** Stroke width. Defaults to `1`. */
+    strokeWidth?: number;
+    /** Dash pattern, e.g. `'4,4'`. Solid by default. */
+    strokeDasharray?: string;
+};
+/** Background grid lines aligned to the y-ticks (horizontal) and x data points (vertical). */
+declare function ChartGrid({ direction, stroke, strokeWidth, strokeDasharray, }: ChartGridProps): import("react/jsx-runtime").JSX.Element;
+export type ChartYAxisProps = {
+    /** Show the tick text labels. Defaults to `true`. */
+    showLabels?: boolean;
+    /** Show short tick marks next to the labels. Defaults to `false`. */
+    showTicks?: boolean;
+    /** Length of a tick mark in px. Defaults to `4`. */
+    tickLength?: number;
+    /** Show a vertical axis line. Defaults to `false`. */
+    showAxisLine?: boolean;
+    /** Override the tick label formatter. */
+    formatLabel?: (value: number) => React.ReactNode;
+};
+/** Y-axis tick labels, vertically positioned to align with the grid. */
+declare function ChartYAxis({ showLabels, showTicks, tickLength, showAxisLine, formatLabel, }: ChartYAxisProps): import("react/jsx-runtime").JSX.Element;
+export type ChartXAxisProps = {
+    /** Show the tick text labels. Defaults to `true`. */
+    showLabels?: boolean;
+    /** Show short tick marks above the labels. Defaults to `false`. */
+    showTicks?: boolean;
+    /** Length of a tick mark in px. Defaults to `4`. */
+    tickLength?: number;
+    /** Make labels tap-to-select the nearest data point. Defaults to `true`. */
+    selectable?: boolean;
+    /** Override the label formatter. */
+    formatLabel?: (label: string | number, index: number) => React.ReactNode;
+};
+/** X-axis labels, horizontally positioned to align with the data points. */
+declare function ChartXAxis({ showLabels, showTicks, tickLength, selectable, formatLabel, }: ChartXAxisProps): import("react/jsx-runtime").JSX.Element;
+export type ChartGoalPinProps = GoalPinConfig & {
+    /** Pill background. Defaults to the series color. */
+    color?: string;
+    /** Pill text color. Defaults to the `mode/Grey/2500` token (white). */
+    textColor?: string;
+};
+/** A pill marker anchored to a data point, with a dashed connector to the baseline. */
+declare function ChartGoalPin({ value, atIndex, seriesIndex, color, textColor }: ChartGoalPinProps): import("react/jsx-runtime").JSX.Element;
+export default AreaLineChart;
+//# sourceMappingURL=AreaLineChart.d.ts.map

package/lib/typescript/src/components/AreaLineChart/chartMath.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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 declare function createLinearScale(domain: readonly [number, number], range: readonly [number, number]): LinearScale;
+/**
+ * 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 declare function niceTicks(min: number, max: number, count?: number): number[];
+/**
+ * Compute the [min, max] extent of an array of resolved points along the
+ * requested axis. Returns `[0, 0]` for an empty list.
+ */
+export declare function extent(points: ResolvedPoint[], axis: 'x' | 'y'): [number, number];
+/**
+ * Normalize the loose `number[] | ChartPoint[]` series data into a uniform
+ * `ResolvedPoint[]`. Bare numbers use their array index as the x value.
+ */
+export declare function resolvePoints(data: ReadonlyArray<number | {
+    x?: number | string;
+    y: number;
+    projected?: boolean;
+}>): ResolvedPoint[];
+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 declare function buildLineSegments(points: PixelPoint[], curve: Curve): LineSegment[];
+/**
+ * Build a single closed area path (the line, then down to `baselineY` and
+ * back) for a filled area fill. Curve smoothing matches `buildLineSegments`.
+ */
+export declare function buildAreaPath(points: PixelPoint[], baselineY: number, curve: Curve): string;
+/**
+ * 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 declare function nearestIndex(pixelXs: number[], targetX: number): number;
+//# sourceMappingURL=chartMath.d.ts.map

package/lib/typescript/src/components/BubbleChart/BubbleChart.d.ts

@@ -0,0 +1,81 @@
+import React from 'react';
+import { type StyleProp, type ViewStyle } from 'react-native';
+import { type ClusterBubbleLabelPlacement } from '../ClusterBubble/ClusterBubble';
+/** 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;
+};
+/**
+ * `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
+ */
+declare function BubbleChart({ data, minBubbleSize, maxBubbleSize, gap, labelGap, height, labelPlacement, autoInsideMinSize, appearanceCycle, iterations, onBubblePress, modes: propModes, style, accessibilityLabel, }: BubbleChartProps): import("react/jsx-runtime").JSX.Element;
+export default BubbleChart;
+//# sourceMappingURL=BubbleChart.d.ts.map

package/lib/typescript/src/components/BubbleChart/bubblePacking.d.ts

@@ -0,0 +1,83 @@
+/**
+ * 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;
+};
+/**
+ * Map magnitudes to radii so a bubble's *area* scales with its value
+ * (`sqrt`-encoding), clamped into `[minRadius, maxRadius]`.
+ */
+export declare function scaleRadii(magnitudes: number[], minRadius: number, maxRadius: number): number[];
+/**
+ * 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 declare function fitRadiiToBox(radii: number[], width: number, height: number, options?: {
+    density?: number;
+    labelArea?: number;
+    minRadius?: number;
+}): number[];
+/**
+ * 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 declare 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[];
+/**
+ * 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 declare function estimateLabelBox(value: string, label: string, options?: {
+    valueFontSize?: number;
+    labelFontSize?: number;
+}): LabelBox;
+/**
+ * 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 declare function chooseLabelDirections(nodes: PositionedNode[], labels: Array<LabelBox | null>, options: {
+    width: number;
+    height: number;
+    gap?: number;
+}): Array<LabelDirection | null>;
+//# sourceMappingURL=bubblePacking.d.ts.map

package/lib/typescript/src/components/ClusterBubble/ClusterBubble.d.ts

@@ -0,0 +1,76 @@
+import React from 'react';
+import { type StyleProp, type TextStyle, type ViewStyle } from 'react-native';
+/** Where the value/label text sits relative to the circle. */
+export type ClusterBubbleLabelPlacement = 'inside' | 'outside' | 'auto';
+/** Which side of the circle an *outside* label is anchored to. */
+export type ClusterBubbleLabelDirection = 'top' | 'bottom' | 'left' | 'right';
+export type ClusterBubbleProps = {
+    /**
+     * The bold, primary content rendered in/under the bubble — e.g. `"40%"`,
+     * `"₹270K"`. Strings are auto-wrapped in a `<Text>`; pass a node for full
+     * control (e.g. a `MoneyValue`).
+     */
+    value?: React.ReactNode;
+    /** The secondary caption shown beside the value — e.g. `"Recommended"`. */
+    label?: React.ReactNode;
+    /** Diameter of the circle in px. Defaults to `120`. */
+    size?: number;
+    /**
+     * `Appearance / DataViz` mode used to resolve the fill from the
+     * `dataViz/bg` token (e.g. `Primary`, `Secondary`, `Tertiary`).
+     * Defaults to `Primary`. The *emphasis* of the fill is taken from the
+     * `Emphasis / DataViz` mode in `modes`.
+     */
+    appearance?: string;
+    /** Hard-override the circle fill color (bypasses token resolution). */
+    color?: string;
+    /**
+     * Where the text sits. `inside` centers it within the circle, `outside`
+     * anchors it just beyond the circle's edge, and `auto` (default) picks
+     * `inside` when the bubble is at least `autoInsideMinSize` px, otherwise
+     * `outside`.
+     */
+    labelPlacement?: ClusterBubbleLabelPlacement;
+    /**
+     * Which side an *outside* label is placed on. The label is positioned
+     * exactly `labelGap` px beyond the circle's radius in this direction.
+     * Defaults to `bottom`.
+     */
+    labelDirection?: ClusterBubbleLabelDirection;
+    /** Gap in px between the circle's edge and an outside label. Defaults to `8`. */
+    labelGap?: number;
+    /** Diameter (px) at/above which `auto` places the text inside. Defaults to `88`. */
+    autoInsideMinSize?: number;
+    /**
+     * Text color when the label sits *inside*. Defaults to an automatic
+     * black/white choice based on the fill's luminance for legibility.
+     */
+    insideTextColor?: string;
+    /** Press handler — wraps the bubble in a `Pressable` when provided. */
+    onPress?: () => void;
+    /** Style override for the value text. */
+    valueStyle?: StyleProp<TextStyle>;
+    /** Style override for the label text. */
+    labelStyle?: StyleProp<TextStyle>;
+    /** Style override for the circle view. */
+    circleStyle?: StyleProp<ViewStyle>;
+    /** Style override for the outer container. */
+    style?: StyleProp<ViewStyle>;
+    /** Design token modes for theming (e.g. `{ 'Color Mode': 'Light' }`). */
+    modes?: Record<string, any>;
+    /** Accessibility label. Defaults to a `value + label` composite. */
+    accessibilityLabel?: string;
+};
+/**
+ * `ClusterBubble` is the atomic circle that composes a `BubbleChart`. It renders
+ * a single token-colored disc with a bold `value` and a secondary `label`. The
+ * text can sit inside the circle or anchor just outside its edge on any side
+ * (`labelDirection`) at a precise `labelGap` distance — so consumers (or the
+ * chart) can steer labels toward free space. The inside text color adapts to
+ * the fill for legibility. It is fully usable standalone.
+ *
+ * @component
+ */
+declare function ClusterBubble({ value, label, size, appearance, color, labelPlacement, labelDirection, labelGap, autoInsideMinSize, insideTextColor, onPress, valueStyle, labelStyle, circleStyle, style, modes: propModes, accessibilityLabel, }: ClusterBubbleProps): import("react/jsx-runtime").JSX.Element;
+export default ClusterBubble;
+//# sourceMappingURL=ClusterBubble.d.ts.map