@oxyhq/bloom 0.34.3 → 0.35.1

package/src/__tests__/AvatarGroupCluster.test.tsx

@@ -0,0 +1,168 @@
+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('fills the round box edge-to-edge for the force-packed counts (4+)', () => {
+    // After the recentre + scale, the outermost bubble edge lands on the box
+    // radius (0.5 from the box centre) — the blob fills the round box densely
+    // with no big empty margin — and the whole cluster stays roughly centred.
+    for (const count of [4, 5, 8, 12, 20]) {
+      const bubbles = computeClusterLayout(count);
+      let reach = 0;
+      for (const bubble of bubbles) {
+        const r = Math.hypot(bubble.cx - 0.5, bubble.cy - 0.5) + bubble.d / 2;
+        if (r > reach) reach = r;
+      }
+      expect(reach).toBeCloseTo(0.5, 6);
+      const primary = bubbleAt(bubbles, 0);
+      expect(primary.cx).toBeGreaterThan(0.4);
+      expect(primary.cx).toBeLessThan(0.6);
+      expect(primary.cy).toBeGreaterThan(0.4);
+      expect(primary.cy).toBeLessThan(0.6);
+    }
+  });
+
+  it('keeps the force-packed bubbles near-equal in size (mild taper)', () => {
+    // The pack should read as near-equal magnetic bubbles: a modestly larger
+    // primary, everyone else only slightly smaller — not a big primary ringed by
+    // tiny dots. The smallest bubble stays at least ~75% of the largest.
+    for (const count of [4, 5, 6, 8, 12, 20]) {
+      const diameters = computeClusterLayout(count).map((bubble) => bubble.d);
+      const maxD = Math.max(...diameters);
+      const minD = Math.min(...diameters);
+      expect(minD / maxD).toBeGreaterThan(0.75);
+    }
+  });
+
+  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);
+    }
+  });
+
+  it('gives the two-member cluster equal-diameter, overlapping bubbles', () => {
+    const bubbles = computeClusterLayout(2);
+    expect(bubbles).toHaveLength(2);
+    const front = bubbleAt(bubbles, 0);
+    const behind = bubbleAt(bubbles, 1);
+    // The fix: both bubbles share the SAME diameter — the one drawn behind is no
+    // longer rendered too small.
+    expect(front.d).toBeCloseTo(behind.d, 10);
+    // Still the intentional iMessage "front + behind" overlap (negative gap).
+    expect(minEdgeGap(bubbles)).toBeLessThan(0);
+    // Deterministic (no Math.random).
+    expect(computeClusterLayout(2)).toEqual(bubbles);
+    // Both bubbles sit fully inside the unit box.
+    for (const bubble of bubbles) {
+      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);
+    }
+  });
+});
+
+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,72 @@ 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
+ * NEAR-EQUAL-size avatars packed densely into a round box (`size` = box
+ * diameter). A modestly larger primary sits in front; the rest are only slightly
+ * smaller and nestle against it with a small uniform gap, filling the round box
+ * edge-to-edge. `showInitials` renders a colored letter for avatar-less members
+ * so the packing reads clearly. Shown at counts 3, 4, 5, 6, 8, 12, and 20.
+ */
+export const ClusterLayout: Story = {
+  render: () => (
+    <View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: 24, alignItems: 'center' }}>
+      {[3, 4, 5, 6, 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;