@oxyhq/bloom 0.8.6 → 0.9.0

package/src/avatar-group/AvatarGroupBase.tsx

@@ -0,0 +1,249 @@
+import React, { memo, useMemo } from 'react';
+import {
+  Pressable,
+  StyleSheet,
+  Text,
+  View,
+  type ViewStyle,
+} from 'react-native';
+
+import { Avatar } from '../avatar';
+import { useTheme } from '../theme/use-theme';
+import { fontSize } from '../styles/tokens';
+import type { AvatarGroupItem, AvatarGroupProps } from './types';
+
+/** Ring thickness as a fraction of avatar size. */
+const RING_RATIO = 0.08;
+/** Minimum ring thickness so small avatars still separate cleanly. */
+const MIN_RING = 2;
+/** Default horizontal overlap as a fraction of avatar size. */
+const DEFAULT_OVERLAP_RATIO = 0.35;
+
+function getItemName(item: AvatarGroupItem): string | undefined {
+  return item.displayName ?? item.name ?? item.username;
+}
+
+function getItemKey(item: AvatarGroupItem, index: number): string {
+  return item.id ?? item.username ?? item.uri ?? `avatar-${index}`;
+}
+
+/** Hover callbacks injected by the web fork; undefined (no-op) on native. */
+export interface AvatarGroupCellHoverHandlers {
+  onHoverIn?: (item: AvatarGroupItem, index: number) => void;
+  onHoverOut?: (item: AvatarGroupItem, index: number) => void;
+  /** Sets the measured anchor ref for the hovered cell (web only). */
+  registerCellRef?: (index: number, node: View | null) => void;
+}
+
+interface AvatarGroupBaseProps extends AvatarGroupProps {
+  hoverHandlers?: AvatarGroupCellHoverHandlers;
+}
+
+const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
+  items,
+  size = 32,
+  max = 5,
+  total,
+  overlap,
+  ringColor,
+  onPressItem,
+  style,
+  testID,
+  hoverHandlers,
+}) => {
+  const theme = useTheme();
+
+  const ring = ringColor ?? theme.colors.card;
+  const ringWidth = Math.max(MIN_RING, Math.round(size * RING_RATIO));
+  const effectiveOverlap =
+    overlap ?? Math.round(size * DEFAULT_OVERLAP_RATIO);
+  // Each avatar after the first is pulled left by `overlap`, but the ring adds
+  // visual width on both sides, so the negative margin accounts for the ring.
+  const negativeMargin = -(effectiveOverlap + ringWidth);
+
+  const shown = useMemo(
+    () => items.slice(0, Math.max(0, max)),
+    [items, max],
+  );
+
+  const realTotal = total ?? items.length;
+  const overflow = Math.max(0, realTotal - shown.length);
+
+  const cellStyle = useMemo((): ViewStyle => {
+    return {
+      width: size + ringWidth * 2,
+      height: size + ringWidth * 2,
+      borderRadius: (size + ringWidth * 2) / 2,
+      backgroundColor: ring,
+      alignItems: 'center',
+      justifyContent: 'center',
+    };
+  }, [size, ringWidth, ring]);
+
+  const overflowTextStyle = useMemo(
+    () => ({
+      color: theme.colors.textSecondary,
+      fontSize: Math.max(fontSize._2xs, Math.round(size * 0.4)),
+      fontWeight: '600' as const,
+    }),
+    [theme.colors.textSecondary, size],
+  );
+
+  const interactive = typeof onPressItem === 'function';
+  const hoverable =
+    typeof hoverHandlers?.onHoverIn === 'function' ||
+    typeof hoverHandlers?.onHoverOut === 'function';
+
+  // Pressing the "+N" chip surfaces the first hidden member (if any), so
+  // consumers can route it to a full member list.
+  const firstHidden = items[shown.length];
+  const overflowOnPress =
+    interactive && firstHidden
+      ? () => onPressItem?.(firstHidden, shown.length)
+      : undefined;
+
+  return (
+    <View style={[styles.row, style]} testID={testID}>
+      {shown.map((item, index) => {
+        const name = getItemName(item);
+        const accessibilityLabel = item.username
+          ? `${name ?? item.username} (@${item.username})`
+          : name;
+
+        // The negative margin and stacking order live on the outermost
+        // row element so layout and hit-testing stay aligned with the visual
+        // overlap. Earlier siblings render on top of later ones.
+        const wrapperStyle: ViewStyle = {
+          ...(index > 0 && { marginLeft: negativeMargin }),
+          zIndex: shown.length - index,
+        };
+
+        const cell = (
+          <View
+            ref={
+              hoverHandlers?.registerCellRef
+                ? (node) => hoverHandlers.registerCellRef?.(index, node)
+                : undefined
+            }
+            collapsable={false}
+            style={cellStyle}
+          >
+            <Avatar uri={item.uri ?? undefined} name={name} size={size} />
+          </View>
+        );
+
+        if (interactive || hoverable) {
+          return (
+            <Pressable
+              key={getItemKey(item, index)}
+              onPress={
+                interactive ? () => onPressItem?.(item, index) : undefined
+              }
+              onHoverIn={
+                hoverHandlers?.onHoverIn
+                  ? () => hoverHandlers.onHoverIn?.(item, index)
+                  : undefined
+              }
+              onHoverOut={
+                hoverHandlers?.onHoverOut
+                  ? () => hoverHandlers.onHoverOut?.(item, index)
+                  : undefined
+              }
+              accessibilityRole={interactive ? 'button' : undefined}
+              accessibilityLabel={accessibilityLabel}
+              style={wrapperStyle}
+            >
+              {cell}
+            </Pressable>
+          );
+        }
+
+        return (
+          <View key={getItemKey(item, index)} style={wrapperStyle}>
+            {cell}
+          </View>
+        );
+      })}
+
+      {overflow > 0 && (
+        <OverflowChip
+          count={overflow}
+          cellStyle={cellStyle}
+          negativeMargin={shown.length > 0 ? negativeMargin : 0}
+          textStyle={overflowTextStyle}
+          onPress={overflowOnPress}
+        />
+      )}
+    </View>
+  );
+};
+
+function OverflowChip({
+  count,
+  cellStyle,
+  negativeMargin,
+  textStyle,
+  onPress,
+}: {
+  count: number;
+  cellStyle: ViewStyle;
+  negativeMargin: number;
+  textStyle: { color: string; fontSize: number; fontWeight: '600' };
+  onPress?: () => void;
+}) {
+  const theme = useTheme();
+  // The chip is anchored at the lowest stacking order so it tucks behind the
+  // last avatar's ring. The margin lives on the outer element to keep layout
+  // aligned with the overlap.
+  const wrapperStyle: ViewStyle = {
+    ...(negativeMargin !== 0 && { marginLeft: negativeMargin }),
+    zIndex: 0,
+  };
+
+  const chip = (
+    <View style={[cellStyle, { backgroundColor: theme.colors.card }]}>
+      <View
+        style={[
+          styles.chipInner,
+          { backgroundColor: theme.colors.backgroundTertiary },
+        ]}
+      >
+        <Text allowFontScaling={false} style={textStyle}>
+          +{count}
+        </Text>
+      </View>
+    </View>
+  );
+
+  if (onPress) {
+    return (
+      <Pressable
+        onPress={onPress}
+        accessibilityRole="button"
+        accessibilityLabel={`${count} more`}
+        style={wrapperStyle}
+      >
+        {chip}
+      </Pressable>
+    );
+  }
+
+  return <View style={wrapperStyle}>{chip}</View>;
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+  chipInner: {
+    width: '100%',
+    height: '100%',
+    borderRadius: 999,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+});
+
+export const AvatarGroupBase = memo(AvatarGroupBaseComponent);
+AvatarGroupBase.displayName = 'AvatarGroupBase';

package/src/avatar-group/index.ts

@@ -0,0 +1,2 @@
+export { AvatarGroup } from './AvatarGroup';
+export type { AvatarGroupProps, AvatarGroupItem } from './types';

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

@@ -0,0 +1,2 @@
+export { AvatarGroup } from './AvatarGroup.web';
+export type { AvatarGroupProps, AvatarGroupItem } from './types';

package/src/avatar-group/types.ts

@@ -0,0 +1,64 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/**
+ * A single member of an {@link AvatarGroup}. Mirrors the minimal shape needed to
+ * render an {@link Avatar} plus drive the optional hover card. `uri` is the
+ * avatar image URL; `name`/`displayName` feed Avatar's deterministic
+ * name-based placeholder when no image resolves.
+ */
+export interface AvatarGroupItem {
+  /** Stable identity used as a React key and passed back to handlers. */
+  id?: string;
+  /** Avatar image URL (null/undefined → name-based placeholder). */
+  uri?: string | null;
+  /** Fallback name used for the avatar placeholder when `displayName` is absent. */
+  name?: string;
+  /** Canonical, already-resolved display name (preferred over `name`). */
+  displayName?: string;
+  /** Handle without the leading `@`. */
+  username?: string;
+}
+
+export interface AvatarGroupProps {
+  /** Members to render, in stacking order (first item sits on top). */
+  items: AvatarGroupItem[];
+  /** Diameter of each avatar in pixels. */
+  size?: number;
+  /** Maximum number of avatars to render before collapsing into the overflow chip. */
+  max?: number;
+  /**
+   * Real total count of members. When provided and larger than the number of
+   * rendered avatars, the overflow chip shows `+ (total - shown)`. When omitted,
+   * overflow is derived from `items.length - shown`.
+   */
+  total?: number;
+  /**
+   * Horizontal overlap between adjacent avatars in pixels. Defaults to ~35% of
+   * `size`. Larger values pull avatars closer together.
+   */
+  overlap?: number;
+  /**
+   * Color of the ring/border drawn around each avatar so they separate cleanly.
+   * Defaults to the theme `card` surface color.
+   */
+  ringColor?: string;
+  /**
+   * Per-avatar press handler. When provided, each avatar (and the overflow chip)
+   * becomes pressable. When omitted, the group is purely presentational.
+   */
+  onPressItem?: (item: AvatarGroupItem, index: number) => void;
+  /**
+   * Enables the hover card on web. Hovering an avatar reveals a
+   * {@link UserHoverCard} for that item. No-op on native.
+   */
+  hoverCard?: boolean;
+  /**
+   * Per-item action slot rendered inside the hover card — typically the app's
+   * SDK FollowButton. Only used when `hoverCard` is enabled (web).
+   */
+  renderItemAction?: (item: AvatarGroupItem, index: number) => ReactNode;
+  /** Container style override. */
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/index.ts

@@ -49,6 +49,10 @@ export type {
   ErrorBoundaryFallbackContext,
 } from './error-boundary';
 export * from './avatar';
+export { AvatarGroup } from './avatar-group';
+export type { AvatarGroupProps, AvatarGroupItem } from './avatar-group';
+export { UserHoverCard } from './user-hover-card';
+export type { UserHoverCardProps, UserHoverCardStat } from './user-hover-card';
 export * from './loading';
 export * as PromptInput from './prompt-input';
 export * from './switch';

package/src/index.web.ts

@@ -54,6 +54,10 @@ export type {
   ErrorBoundaryFallbackContext,
 } from './error-boundary';
 export * from './avatar';
+export { AvatarGroup } from './avatar-group/index.web';
+export type { AvatarGroupProps, AvatarGroupItem } from './avatar-group/index.web';
+export { UserHoverCard } from './user-hover-card';
+export type { UserHoverCardProps, UserHoverCardStat } from './user-hover-card';
 export * from './loading/index.web';
 export * as PromptInput from './prompt-input';
 export * from './switch';

package/src/user-hover-card/UserHoverCard.stories.tsx

@@ -0,0 +1,113 @@
+import React from 'react';
+import { Pressable, Text, View } from 'react-native';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { UserHoverCard } from './UserHoverCard';
+
+const SAMPLE_AVATAR =
+  'https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=200&h=200&fit=crop';
+
+function DemoFollowButton() {
+  return (
+    <Pressable
+      style={{
+        paddingHorizontal: 14,
+        paddingVertical: 7,
+        borderRadius: 999,
+        backgroundColor: '#1A73E8',
+      }}
+    >
+      <Text style={{ color: '#fff', fontWeight: '600', fontSize: 13 }}>
+        Follow
+      </Text>
+    </Pressable>
+  );
+}
+
+const meta: Meta<typeof UserHoverCard> = {
+  title: 'Components/UserHoverCard',
+  component: UserHoverCard,
+  argTypes: {
+    verified: { control: 'boolean' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UserHoverCard>;
+
+export const Basic: Story = {
+  args: {
+    avatar: SAMPLE_AVATAR,
+    displayName: 'Nate Isern',
+    username: 'nate',
+    bio: 'Building the Oxy ecosystem. Designer, engineer, and occasional rose grower.',
+    stats: [
+      { label: 'Following', value: '312' },
+      { label: 'Followers', value: '4.8K' },
+    ],
+    verified: true,
+  },
+};
+
+export const WithAction: Story = {
+  args: {
+    avatar: SAMPLE_AVATAR,
+    displayName: 'Ada Lovelace',
+    username: 'ada',
+    bio: 'Mathematician. Wrote the first algorithm intended for a machine.',
+    stats: [
+      { label: 'Following', value: '12' },
+      { label: 'Followers', value: '1.2M' },
+    ],
+    verified: true,
+    action: <DemoFollowButton />,
+  },
+  name: 'With action slot',
+};
+
+export const NoAction: Story = {
+  args: {
+    avatar: null,
+    displayName: 'Grace Hopper',
+    username: 'grace',
+    bio: 'Computer scientist and US Navy rear admiral.',
+    stats: [
+      { label: 'Following', value: '88' },
+      { label: 'Followers', value: '900K' },
+    ],
+  },
+  name: 'No action slot',
+};
+
+export const Minimal: Story = {
+  args: {
+    displayName: 'Anonymous',
+  },
+  name: 'Minimal (name only)',
+};
+
+export const Pressable_: Story = {
+  render: (args) => (
+    <View style={{ gap: 8 }}>
+      <UserHoverCard
+        {...args}
+        avatar={SAMPLE_AVATAR}
+        displayName="Linus Torvalds"
+        username="linus"
+        bio="Creator of Linux and Git."
+        stats={[
+          { label: 'Following', value: '3' },
+          { label: 'Followers', value: '2.1M' },
+        ]}
+        action={<DemoFollowButton />}
+        onPressProfile={() => {
+          // eslint-disable-next-line no-alert
+          if (typeof window !== 'undefined') window.alert('open profile');
+        }}
+      />
+      <Text>Click the identity area to open the profile.</Text>
+    </View>
+  ),
+  name: 'Pressable identity',
+};

package/src/user-hover-card/UserHoverCard.tsx

@@ -0,0 +1,204 @@
+import React, { memo, useMemo } from 'react';
+import {
+  Platform,
+  Pressable,
+  StyleSheet,
+  Text,
+  View,
+  type ViewStyle,
+} from 'react-native';
+
+import { Avatar } from '../avatar';
+import { VerifiedCheck } from '../icons/VerifiedCheck';
+import { useTheme } from '../theme/use-theme';
+import { borderRadius, fontSize, space } from '../styles/tokens';
+import type { UserHoverCardProps } from './types';
+
+const AVATAR_SIZE = 48;
+const VERIFIED_SIZE = 16;
+
+const UserHoverCardComponent: React.FC<UserHoverCardProps> = ({
+  avatar,
+  displayName,
+  username,
+  bio,
+  stats,
+  verified = false,
+  onPressProfile,
+  action,
+  style,
+  testID,
+}) => {
+  const theme = useTheme();
+
+  const cardStyle = useMemo((): ViewStyle => {
+    const base: ViewStyle = {
+      backgroundColor: theme.colors.card,
+      borderRadius: borderRadius.lg,
+      borderWidth: StyleSheet.hairlineWidth,
+      borderColor: theme.colors.border,
+      padding: space.lg,
+      width: 280,
+    };
+
+    if (Platform.OS === 'web') {
+      base.boxShadow = `0px 8px 24px ${theme.colors.shadow}`;
+    } else {
+      base.shadowColor = theme.colors.shadow;
+      base.shadowOffset = { width: 0, height: 8 };
+      base.shadowOpacity = 0.18;
+      base.shadowRadius = 16;
+      base.elevation = 8;
+    }
+
+    return base;
+  }, [theme]);
+
+  const identity = (
+    <View style={styles.identityRow}>
+      <Avatar uri={avatar ?? undefined} name={displayName} size={AVATAR_SIZE} />
+      <View style={styles.identityText}>
+        <View style={styles.nameRow}>
+          <Text
+            numberOfLines={1}
+            style={[styles.displayName, { color: theme.colors.text }]}
+          >
+            {displayName}
+          </Text>
+          {verified && (
+            <VerifiedCheck
+              size="sm"
+              fill={theme.colors.primary}
+              width={VERIFIED_SIZE}
+              height={VERIFIED_SIZE}
+              style={styles.verifiedBadge}
+            />
+          )}
+        </View>
+        {username ? (
+          <Text
+            numberOfLines={1}
+            style={[styles.username, { color: theme.colors.textSecondary }]}
+          >
+            @{username}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+
+  return (
+    <View style={[cardStyle, style]} testID={testID}>
+      <View style={styles.header}>
+        {onPressProfile ? (
+          <Pressable
+            onPress={onPressProfile}
+            accessibilityRole="button"
+            accessibilityLabel={
+              username ? `${displayName} (@${username})` : displayName
+            }
+            style={styles.identityPressable}
+          >
+            {identity}
+          </Pressable>
+        ) : (
+          <View style={styles.identityPressable}>{identity}</View>
+        )}
+        {action != null ? <View style={styles.action}>{action}</View> : null}
+      </View>
+
+      {bio ? (
+        <Text
+          numberOfLines={3}
+          style={[styles.bio, { color: theme.colors.text }]}
+        >
+          {bio}
+        </Text>
+      ) : null}
+
+      {stats && stats.length > 0 ? (
+        <View style={styles.statsRow}>
+          {stats.map((stat) => (
+            <View key={stat.label} style={styles.stat}>
+              <Text style={[styles.statValue, { color: theme.colors.text }]}>
+                {stat.value}
+              </Text>
+              <Text
+                style={[styles.statLabel, { color: theme.colors.textSecondary }]}
+              >
+                {stat.label}
+              </Text>
+            </View>
+          ))}
+        </View>
+      ) : null}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  header: {
+    flexDirection: 'row',
+    alignItems: 'flex-start',
+    justifyContent: 'space-between',
+    gap: space.sm,
+  },
+  identityPressable: {
+    flexShrink: 1,
+    flexGrow: 1,
+  },
+  identityRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: space.sm,
+  },
+  identityText: {
+    flexShrink: 1,
+    flexGrow: 1,
+  },
+  nameRow: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: space.xs,
+  },
+  displayName: {
+    fontSize: fontSize.lg,
+    fontWeight: '700',
+    flexShrink: 1,
+  },
+  verifiedBadge: {
+    flexShrink: 0,
+  },
+  username: {
+    fontSize: fontSize.sm,
+    marginTop: space._2xs,
+  },
+  action: {
+    flexShrink: 0,
+  },
+  bio: {
+    fontSize: fontSize.sm,
+    lineHeight: fontSize.sm * 1.4,
+    marginTop: space.md,
+  },
+  statsRow: {
+    flexDirection: 'row',
+    gap: space.lg,
+    marginTop: space.md,
+  },
+  stat: {
+    flexDirection: 'row',
+    alignItems: 'baseline',
+    gap: space.xs,
+  },
+  statValue: {
+    fontSize: fontSize.sm,
+    fontWeight: '700',
+  },
+  statLabel: {
+    fontSize: fontSize.sm,
+  },
+});
+
+export const UserHoverCard = memo(UserHoverCardComponent);
+UserHoverCard.displayName = 'UserHoverCard';

package/src/user-hover-card/index.ts

@@ -0,0 +1,2 @@
+export { UserHoverCard } from './UserHoverCard';
+export type { UserHoverCardProps, UserHoverCardStat } from './types';

package/src/user-hover-card/types.ts

@@ -0,0 +1,38 @@
+import type { ReactNode } from 'react';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/** A single labeled metric rendered in the {@link UserHoverCardProps.stats} row. */
+export interface UserHoverCardStat {
+  /** Human-readable label, e.g. `"Followers"`. */
+  label: string;
+  /** Pre-formatted value, e.g. `"1.2K"` or `42`. */
+  value: string | number;
+}
+
+export interface UserHoverCardProps {
+  /**
+   * Avatar image source — a URL string, or null/undefined to fall back to the
+   * deterministic name-based placeholder rendered by {@link Avatar}.
+   */
+  avatar?: string | null;
+  /** Canonical, already-resolved display name (an API contract — render directly). */
+  displayName: string;
+  /** Handle without the leading `@` (the component prefixes it). */
+  username?: string;
+  /** Optional short biography; truncated to a few lines. */
+  bio?: string;
+  /** Optional metrics row (e.g. Following / Followers). */
+  stats?: UserHoverCardStat[];
+  /** Whether to show the verified badge next to the display name. */
+  verified?: boolean;
+  /** Makes the identity area (avatar + name + handle) pressable. */
+  onPressProfile?: () => void;
+  /**
+   * Slot for a consumer-injected action — typically the app's SDK FollowButton.
+   * Bloom does NOT implement follow logic; it only renders the card.
+   */
+  action?: ReactNode;
+  /** Container style override. */
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}