@oxyhq/bloom 0.34.3 → 0.35.0

package/lib/module/avatar-group/cluster-layout.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["GOLDEN_ANGLE","Math","PI","sqrt","ITERATIONS","CLEANUP_ITERATIONS","CENTERING","SEPARATION_STRENGTH","LAYOUT_GAP","SEED_SPACING","PRIMARY_RADIUS","SECONDARY_MAX","SECONDARY_MIN","EPSILON","relativeRadius","index","count","t","separate","xs","ys","radii","i","j","dx","dy","dist","hypot","minDist","a","cos","sin","overlap","nx","ny","packCluster","Array","seedR","angle","iter","bound","reach","scale","bubbles","cx","cy","d","computeClusterLayout"],"sourceRoot":"../../../src","sources":["avatar-group/cluster-layout.ts"],"mappings":"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","ignoreList":[]}

package/lib/typescript/commonjs/avatar-group/AvatarGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/AvatarGroup.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAe,MAAM,OAAO,CAAC;AAGpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAchD,eAAO,MAAM,WAAW,8CAA6B,CAAC"}
+{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/AvatarGroup.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAe,MAAM,OAAO,CAAC;AAGpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAehD,eAAO,MAAM,WAAW,8CAA6B,CAAC"}

package/lib/typescript/commonjs/avatar-group/AvatarGroupBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroupBase.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/AvatarGroupBase.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,EAIL,IAAI,EAEL,MAAM,cAAc,CAAC;AAKtB,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAiBjE,6EAA6E;AAC7E,MAAM,WAAW,4BAA4B;IAC3C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,oEAAoE;IACpE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC;CAC9D;AAED,UAAU,oBAAqB,SAAQ,gBAAgB;IACrD,aAAa,CAAC,EAAE,4BAA4B,CAAC;CAC9C;AAuPD,eAAO,MAAM,eAAe,kDAAiC,CAAC"}
+{"version":3,"file":"AvatarGroupBase.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/AvatarGroupBase.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,EAIL,IAAI,EAIL,MAAM,cAAc,CAAC;AAMtB,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AA0BjE,6EAA6E;AAC7E,MAAM,WAAW,4BAA4B;IAC3C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,oEAAoE;IACpE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC;CAC9D;AAED,UAAU,oBAAqB,SAAQ,gBAAgB;IACrD,aAAa,CAAC,EAAE,4BAA4B,CAAC;CAC9C;AA4bD,eAAO,MAAM,eAAe,kDAAiC,CAAC"}

package/lib/typescript/commonjs/avatar-group/cluster-layout.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Deterministic organic circle-packing for the {@link AvatarGroup} `cluster`
+ * layout — the iMessage-style "magnetic bubble cluster" where several avatars of
+ * varying sizes nestle together inside a round bounding box (a large primary in
+ * the middle/front, smaller members packed around it with a uniform gap).
+ *
+ * For 4+ members the layout is produced by a small, FULLY DETERMINISTIC
+ * force-directed relaxation (no `Math.random`): the primary is pinned at the
+ * centre and the remaining members are seeded on a golden-angle spiral, then a
+ * fixed number of relaxation passes (a) pull every non-primary circle toward the
+ * centre and (b) push any two circles apart until they clear a uniform gap. A
+ * fixed iteration count + deterministic seed means the same `count` always
+ * yields byte-identical positions, so native and web render the cluster
+ * identically with no `onLayout`/DOM measurement. The very small counts (1, 2,
+ * 3) — where a relaxation degenerates into a line or a lone pair — use explicit
+ * iMessage-style arrangements instead.
+ *
+ * Output is resolution-independent: each bubble is expressed as a fraction of
+ * the group's bounding box (`cx`/`cy` centre, `d` diameter, all 0..1), so the
+ * consumer just multiplies by the pixel `size`. Every bubble is guaranteed to
+ * sit fully inside the `[0, 1]` box (the packed result is scaled + translated to
+ * fit), so the cluster drops in exactly where a single round Avatar would.
+ */
+/** A single packed bubble, expressed as fractions of the bounding box (0..1). */
+export interface ClusterBubble {
+    /** Centre X as a fraction of the box width. */
+    cx: number;
+    /** Centre Y as a fraction of the box height. */
+    cy: number;
+    /** Diameter as a fraction of the box size. */
+    d: number;
+}
+/**
+ * Deterministic cluster layout for `count` bubbles, as box-fraction bubbles
+ * ordered primary-first. `count` includes the `+N` overflow bubble when present
+ * (it is simply the last, smallest member of the pack).
+ *
+ * - `<= 0` → empty.
+ * - `1` → a single bubble filling the box.
+ * - `2` → the iMessage "one in front, one behind" pair: a larger primary set
+ *   low-left with a smaller member tucked behind it to the upper-right.
+ * - `3` → an iMessage-style triangle: the larger primary along the bottom with
+ *   two smaller members above it.
+ * - `4+` → the deterministic force-directed pack (primary centred, the rest
+ *   packed magnetically around it, denser as the count grows).
+ */
+export declare function computeClusterLayout(count: number): ClusterBubble[];
+//# sourceMappingURL=cluster-layout.d.ts.map

package/lib/typescript/commonjs/avatar-group/cluster-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-layout.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/cluster-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,CAAC,EAAE,MAAM,CAAC;CACX;AA4ID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,CAiBnE"}

package/lib/typescript/commonjs/avatar-group/types.d.ts

@@ -28,14 +28,27 @@ export interface AvatarGroupProps {
     items: AvatarGroupItem[];
     /**
      * How the avatars are arranged.
-     * - `'stack'` (default): overlapping facepile with a thin separator ring, a
-     *   trailing `+N` overflow chip, and the first item on top.
+     * - `'stack'` (default): overlapping horizontal facepile with a thin separator
+     *   ring, a trailing `+N` overflow chip, and the first item on top.
      * - `'row'`: avatars placed adjacent with a positive `spacing` gap and NO
      *   separator ring — an "adjacent row" of icons (e.g. a top-tokens strip).
      *   Still collapses into the `+N` overflow chip at `max`.
+     * - `'cluster'`: a compact 2D "magnetic bubble cluster" (iMessage-style) —
+     *   avatars of VARYING sizes deterministically packed into a round bounding
+     *   box with a uniform gap: the first item (primary) is the largest and sits
+     *   centred/in front, the rest nestle around it. Scales from 2 (a "front +
+     *   behind" pair) up through a dense pack (~20), collapsing into a trailing
+     *   `+N` bubble past `max`. Unlike the horizontal layouts, `size` is the
+     *   overall box diameter (see `size`) and `max` defaults to 20 (see `max`), so
+     *   it drops in where a single round Avatar would.
+     */
+    layout?: 'stack' | 'row' | 'cluster';
+    /**
+     * Diameter in pixels. For `'stack'`/`'row'` this is the diameter of EACH
+     * avatar. For `'cluster'` this is the diameter of the whole bounding box (the
+     * packed bubbles are sized as fractions of it), so the cluster occupies the
+     * same footprint as a single `size`-px Avatar.
      */
-    layout?: 'stack' | 'row';
-    /** Diameter of each avatar in pixels. */
     size?: number;
     /**
      * Rendition variant forwarded to each {@link Avatar}'s `variant` prop, which
@@ -44,7 +57,12 @@ export interface AvatarGroupProps {
      * `'thumb'`; pass `undefined` to request full-size renditions.
      */
     variant?: string;
-    /** Maximum number of avatars to render before collapsing into the overflow chip. */
+    /**
+     * Maximum number of avatars to render before collapsing into the overflow
+     * chip. Defaults to 5 for `'stack'`/`'row'`, and to 20 for `'cluster'` (which
+     * packs densely). In `'cluster'` the cap is inclusive of the `+N` bubble: past
+     * the cap the last slot becomes the overflow bubble.
+     */
     max?: number;
     /**
      * Real total count of members. When provided and larger than the number of

package/lib/typescript/commonjs/avatar-group/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IACzB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC;IACvE,gCAAgC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;IACrC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC;IACvE,gCAAgC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/lib/typescript/module/avatar-group/AvatarGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/AvatarGroup.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAe,MAAM,OAAO,CAAC;AAGpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAchD,eAAO,MAAM,WAAW,8CAA6B,CAAC"}
+{"version":3,"file":"AvatarGroup.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/AvatarGroup.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAe,MAAM,OAAO,CAAC;AAGpC,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAehD,eAAO,MAAM,WAAW,8CAA6B,CAAC"}

package/lib/typescript/module/avatar-group/AvatarGroupBase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroupBase.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/AvatarGroupBase.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,EAIL,IAAI,EAEL,MAAM,cAAc,CAAC;AAKtB,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAiBjE,6EAA6E;AAC7E,MAAM,WAAW,4BAA4B;IAC3C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,oEAAoE;IACpE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC;CAC9D;AAED,UAAU,oBAAqB,SAAQ,gBAAgB;IACrD,aAAa,CAAC,EAAE,4BAA4B,CAAC;CAC9C;AAuPD,eAAO,MAAM,eAAe,kDAAiC,CAAC"}
+{"version":3,"file":"AvatarGroupBase.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/AvatarGroupBase.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAwB,MAAM,OAAO,CAAC;AAC7C,OAAO,EAIL,IAAI,EAIL,MAAM,cAAc,CAAC;AAMtB,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AA0BjE,6EAA6E;AAC7E,MAAM,WAAW,4BAA4B;IAC3C,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,UAAU,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,oEAAoE;IACpE,eAAe,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,GAAG,IAAI,KAAK,IAAI,CAAC;CAC9D;AAED,UAAU,oBAAqB,SAAQ,gBAAgB;IACrD,aAAa,CAAC,EAAE,4BAA4B,CAAC;CAC9C;AA4bD,eAAO,MAAM,eAAe,kDAAiC,CAAC"}

package/lib/typescript/module/avatar-group/cluster-layout.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Deterministic organic circle-packing for the {@link AvatarGroup} `cluster`
+ * layout — the iMessage-style "magnetic bubble cluster" where several avatars of
+ * varying sizes nestle together inside a round bounding box (a large primary in
+ * the middle/front, smaller members packed around it with a uniform gap).
+ *
+ * For 4+ members the layout is produced by a small, FULLY DETERMINISTIC
+ * force-directed relaxation (no `Math.random`): the primary is pinned at the
+ * centre and the remaining members are seeded on a golden-angle spiral, then a
+ * fixed number of relaxation passes (a) pull every non-primary circle toward the
+ * centre and (b) push any two circles apart until they clear a uniform gap. A
+ * fixed iteration count + deterministic seed means the same `count` always
+ * yields byte-identical positions, so native and web render the cluster
+ * identically with no `onLayout`/DOM measurement. The very small counts (1, 2,
+ * 3) — where a relaxation degenerates into a line or a lone pair — use explicit
+ * iMessage-style arrangements instead.
+ *
+ * Output is resolution-independent: each bubble is expressed as a fraction of
+ * the group's bounding box (`cx`/`cy` centre, `d` diameter, all 0..1), so the
+ * consumer just multiplies by the pixel `size`. Every bubble is guaranteed to
+ * sit fully inside the `[0, 1]` box (the packed result is scaled + translated to
+ * fit), so the cluster drops in exactly where a single round Avatar would.
+ */
+/** A single packed bubble, expressed as fractions of the bounding box (0..1). */
+export interface ClusterBubble {
+    /** Centre X as a fraction of the box width. */
+    cx: number;
+    /** Centre Y as a fraction of the box height. */
+    cy: number;
+    /** Diameter as a fraction of the box size. */
+    d: number;
+}
+/**
+ * Deterministic cluster layout for `count` bubbles, as box-fraction bubbles
+ * ordered primary-first. `count` includes the `+N` overflow bubble when present
+ * (it is simply the last, smallest member of the pack).
+ *
+ * - `<= 0` → empty.
+ * - `1` → a single bubble filling the box.
+ * - `2` → the iMessage "one in front, one behind" pair: a larger primary set
+ *   low-left with a smaller member tucked behind it to the upper-right.
+ * - `3` → an iMessage-style triangle: the larger primary along the bottom with
+ *   two smaller members above it.
+ * - `4+` → the deterministic force-directed pack (primary centred, the rest
+ *   packed magnetically around it, denser as the count grows).
+ */
+export declare function computeClusterLayout(count: number): ClusterBubble[];
+//# sourceMappingURL=cluster-layout.d.ts.map

package/lib/typescript/module/avatar-group/cluster-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cluster-layout.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/cluster-layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,iFAAiF;AACjF,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,8CAA8C;IAC9C,CAAC,EAAE,MAAM,CAAC;CACX;AA4ID;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,MAAM,GAAG,aAAa,EAAE,CAiBnE"}

package/lib/typescript/module/avatar-group/types.d.ts

@@ -28,14 +28,27 @@ export interface AvatarGroupProps {
     items: AvatarGroupItem[];
     /**
      * How the avatars are arranged.
-     * - `'stack'` (default): overlapping facepile with a thin separator ring, a
-     *   trailing `+N` overflow chip, and the first item on top.
+     * - `'stack'` (default): overlapping horizontal facepile with a thin separator
+     *   ring, a trailing `+N` overflow chip, and the first item on top.
      * - `'row'`: avatars placed adjacent with a positive `spacing` gap and NO
      *   separator ring — an "adjacent row" of icons (e.g. a top-tokens strip).
      *   Still collapses into the `+N` overflow chip at `max`.
+     * - `'cluster'`: a compact 2D "magnetic bubble cluster" (iMessage-style) —
+     *   avatars of VARYING sizes deterministically packed into a round bounding
+     *   box with a uniform gap: the first item (primary) is the largest and sits
+     *   centred/in front, the rest nestle around it. Scales from 2 (a "front +
+     *   behind" pair) up through a dense pack (~20), collapsing into a trailing
+     *   `+N` bubble past `max`. Unlike the horizontal layouts, `size` is the
+     *   overall box diameter (see `size`) and `max` defaults to 20 (see `max`), so
+     *   it drops in where a single round Avatar would.
+     */
+    layout?: 'stack' | 'row' | 'cluster';
+    /**
+     * Diameter in pixels. For `'stack'`/`'row'` this is the diameter of EACH
+     * avatar. For `'cluster'` this is the diameter of the whole bounding box (the
+     * packed bubbles are sized as fractions of it), so the cluster occupies the
+     * same footprint as a single `size`-px Avatar.
      */
-    layout?: 'stack' | 'row';
-    /** Diameter of each avatar in pixels. */
     size?: number;
     /**
      * Rendition variant forwarded to each {@link Avatar}'s `variant` prop, which
@@ -44,7 +57,12 @@ export interface AvatarGroupProps {
      * `'thumb'`; pass `undefined` to request full-size renditions.
      */
     variant?: string;
-    /** Maximum number of avatars to render before collapsing into the overflow chip. */
+    /**
+     * Maximum number of avatars to render before collapsing into the overflow
+     * chip. Defaults to 5 for `'stack'`/`'row'`, and to 20 for `'cluster'` (which
+     * packs densely). In `'cluster'` the cap is inclusive of the `+N` bubble: past
+     * the cap the last slot becomes the overflow bubble.
+     */
     max?: number;
     /**
      * Real total count of members. When provided and larger than the number of

package/lib/typescript/module/avatar-group/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IACzB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC;IACvE,gCAAgC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/avatar-group/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACvC,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEzD;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,uEAAuE;IACvE,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,qEAAqE;IACrE,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB;;;;;;;;;;;;;;;OAeG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;IACrC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;;OAMG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7D;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,SAAS,CAAC;IACvE,gCAAgC;IAChC,KAAK,CAAC,EAAE,SAAS,CAAC,SAAS,CAAC,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.34.3",
+  "version": "0.35.0",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",

package/src/__tests__/AvatarGroupCluster.test.tsx

@@ -0,0 +1,123 @@
+import React from 'react';
+import { render } from '@testing-library/react-native';
+
+import { BloomThemeProvider } from '../theme/BloomThemeProvider';
+import { AvatarGroup } from '../avatar-group';
+import type { AvatarGroupItem } from '../avatar-group';
+import {
+  computeClusterLayout,
+  type ClusterBubble,
+} from '../avatar-group/cluster-layout';
+
+/** Returns bubble at `index` or throws — keeps the tests `!`/`as`-free under
+ * `noUncheckedIndexedAccess`. */
+function bubbleAt(bubbles: readonly ClusterBubble[], index: number): ClusterBubble {
+  const bubble = bubbles[index];
+  if (!bubble) throw new Error(`expected a bubble at index ${index}`);
+  return bubble;
+}
+
+/** Nearest-neighbour edge gap for every bubble (negative = overlap). */
+function minEdgeGap(bubbles: readonly ClusterBubble[]): number {
+  let worst = Infinity;
+  for (const a of bubbles) {
+    for (const b of bubbles) {
+      if (a === b) continue;
+      const centerDist = Math.hypot(a.cx - b.cx, a.cy - b.cy);
+      const gap = centerDist - (a.d / 2 + b.d / 2);
+      if (gap < worst) worst = gap;
+    }
+  }
+  return worst;
+}
+
+describe('computeClusterLayout', () => {
+  it('returns an empty layout for non-positive counts', () => {
+    expect(computeClusterLayout(0)).toEqual([]);
+    expect(computeClusterLayout(-3)).toEqual([]);
+  });
+
+  it('returns exactly `count` bubbles', () => {
+    for (let count = 1; count <= 20; count++) {
+      expect(computeClusterLayout(count)).toHaveLength(count);
+    }
+  });
+
+  it('is fully deterministic (no Math.random)', () => {
+    for (const count of [2, 3, 4, 8, 20]) {
+      expect(computeClusterLayout(count)).toEqual(computeClusterLayout(count));
+    }
+  });
+
+  it('keeps every bubble inside the unit box with no NaN', () => {
+    for (let count = 1; count <= 20; count++) {
+      const bubbles = computeClusterLayout(count);
+      for (const bubble of bubbles) {
+        expect(Number.isNaN(bubble.cx)).toBe(false);
+        expect(Number.isNaN(bubble.cy)).toBe(false);
+        expect(Number.isNaN(bubble.d)).toBe(false);
+        expect(bubble.cx - bubble.d / 2).toBeGreaterThanOrEqual(-1e-6);
+        expect(bubble.cx + bubble.d / 2).toBeLessThanOrEqual(1 + 1e-6);
+        expect(bubble.cy - bubble.d / 2).toBeGreaterThanOrEqual(-1e-6);
+        expect(bubble.cy + bubble.d / 2).toBeLessThanOrEqual(1 + 1e-6);
+      }
+    }
+  });
+
+  it('makes the primary (index 0) the largest bubble', () => {
+    for (let count = 2; count <= 20; count++) {
+      const bubbles = computeClusterLayout(count);
+      const primary = bubbleAt(bubbles, 0);
+      for (const bubble of bubbles) {
+        expect(primary.d).toBeGreaterThanOrEqual(bubble.d - 1e-9);
+      }
+    }
+  });
+
+  it('centres the primary for the force-packed counts (4+)', () => {
+    for (const count of [4, 5, 8, 12, 20]) {
+      const primary = bubbleAt(computeClusterLayout(count), 0);
+      expect(primary.cx).toBeCloseTo(0.5, 5);
+      expect(primary.cy).toBeCloseTo(0.5, 5);
+    }
+  });
+
+  it('keeps a uniform, non-overlapping gap for 3+ members', () => {
+    // n=2 is the intentional "front + behind" overlap; 3+ pack with a gap.
+    for (let count = 3; count <= 20; count++) {
+      expect(minEdgeGap(computeClusterLayout(count))).toBeGreaterThan(-1e-3);
+    }
+  });
+});
+
+const CLUSTER_ITEMS: AvatarGroupItem[] = Array.from({ length: 25 }, (_, i) => ({
+  id: `c${i}`,
+  displayName: `Member ${i}`,
+  username: `member${i}`,
+}));
+
+function renderCluster(ui: React.ReactElement) {
+  return render(<BloomThemeProvider mode="light" colorPreset="teal">{ui}</BloomThemeProvider>);
+}
+
+describe('AvatarGroup cluster layout', () => {
+  it('renders a "+N" overflow bubble past the cap', () => {
+    // 25 members, cap 20 → 19 avatars + a "+6" bubble.
+    const { getByText } = renderCluster(
+      <AvatarGroup layout="cluster" items={CLUSTER_ITEMS} size={140} max={20} showInitials />,
+    );
+    expect(getByText('+6')).toBeTruthy();
+  });
+
+  it('shows no overflow bubble when members fit under the cap', () => {
+    const { queryByText } = renderCluster(
+      <AvatarGroup
+        layout="cluster"
+        items={CLUSTER_ITEMS.slice(0, 4)}
+        size={64}
+        showInitials
+      />,
+    );
+    expect(queryByText(/^\+/)).toBeNull();
+  });
+});

package/src/avatar-group/AvatarGroup.stories.tsx

@@ -147,3 +147,71 @@ export const RowLayout: Story = {
   ),
   name: 'Row layout',
 };
+
+// A larger pool of initials-only members to show the cluster densely packed.
+const MANY: AvatarGroupItem[] = Array.from({ length: 25 }, (_, i) => ({
+  id: `c${i}`,
+  displayName: String.fromCharCode(65 + (i % 26)),
+  username: `user${i}`,
+}));
+
+/**
+ * Cluster layout: a compact iMessage-style "magnetic bubble cluster" of
+ * varying-size avatars packed into a round box (`size` = box diameter). The
+ * primary is largest and centred/in front; the rest nestle around it with a
+ * uniform gap. `showInitials` renders a colored letter for avatar-less members
+ * so the packing reads clearly. Shown at counts 3, 5, 8, 12, and 20.
+ */
+export const ClusterLayout: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 24, alignItems: 'center' }}>
+      {[3, 5, 8, 12, 20].map((count) => (
+        <View key={count} style={{ alignItems: 'center', gap: 8 }}>
+          <AvatarGroup
+            layout="cluster"
+            items={MANY.slice(0, count)}
+            size={120}
+            showInitials
+          />
+          <Text>{count}</Text>
+        </View>
+      ))}
+    </View>
+  ),
+  name: 'Cluster layout',
+};
+
+/**
+ * Cluster with photos at the common collaborative-post sizes (2 = "front +
+ * behind", then 3 and 4).
+ */
+export const ClusterWithPhotos: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 24, alignItems: 'center' }}>
+      {[2, 3, 4].map((count) => (
+        <AvatarGroup
+          key={count}
+          layout="cluster"
+          items={WITH_PHOTOS.slice(0, count)}
+          size={64}
+          showInitials
+        />
+      ))}
+    </View>
+  ),
+  name: 'Cluster with photos',
+};
+
+/**
+ * Cluster overflow: 25 members with `max={20}` shows 19 avatars + a trailing
+ * "+N" bubble as the last (smallest) cluster member.
+ */
+export const ClusterOverflow: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', gap: 24, alignItems: 'center' }}>
+      <AvatarGroup layout="cluster" items={MANY} size={140} max={20} showInitials />
+      <Text>25 members, max 20 → cap + &quot;+N&quot;</Text>
+    </View>
+  ),
+  name: 'Cluster overflow',
+};

package/src/avatar-group/AvatarGroup.tsx

@@ -4,8 +4,9 @@ import { AvatarGroupBase } from './AvatarGroupBase';
 import type { AvatarGroupProps } from './types';
 
 /**
- * Native `AvatarGroup` — an overlapping, ringed stack of {@link Avatar}s with a
- * trailing `+N` overflow chip.
+ * Native `AvatarGroup` — {@link Avatar}s arranged as a horizontal facepile
+ * (`stack`), an adjacent `row`, or a 2D magnetic `cluster`, with a trailing
+ * `+N` overflow chip. See `layout` in {@link AvatarGroupProps}.
  *
  * Hover behavior is web-only; on native the `hoverCard` / `renderItemAction`
  * props are accepted for API parity but intentionally do nothing (no hover on

package/src/avatar-group/AvatarGroup.web.tsx

@@ -28,11 +28,11 @@ function getItemName(item: AvatarGroupItem): string {
 }
 
 /**
- * Web `AvatarGroup`. Identical stack rendering to native via
- * {@link AvatarGroupBase}, plus an optional hover card: when `hoverCard` is
- * enabled, hovering an avatar reveals a {@link UserHoverCard} positioned beneath
- * it. The card receives the per-item `renderItemAction` slot so the app can drop
- * its SDK FollowButton inside.
+ * Web `AvatarGroup`. Identical layout rendering to native (stack / row /
+ * cluster) via {@link AvatarGroupBase}, plus an optional hover card: when
+ * `hoverCard` is enabled, hovering an avatar reveals a {@link UserHoverCard}
+ * positioned beneath it. The card receives the per-item `renderItemAction` slot
+ * so the app can drop its SDK FollowButton inside.
  */
 const AvatarGroupWebComponent: React.FC<AvatarGroupProps> = (props) => {
   const { hoverCard, renderItemAction, onPressItem } = props;