@oxyhq/bloom 0.8.5 → 0.9.0

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

@@ -0,0 +1,135 @@
+import React from 'react';
+import { Text, View } from 'react-native';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { AvatarGroup } from './AvatarGroup';
+import type { AvatarGroupItem } from './types';
+
+const ITEMS: AvatarGroupItem[] = [
+  { id: '1', displayName: 'Ada Lovelace', username: 'ada' },
+  { id: '2', displayName: 'Grace Hopper', username: 'grace' },
+  { id: '3', displayName: 'Alan Turing', username: 'alan' },
+  { id: '4', displayName: 'Linus Torvalds', username: 'linus' },
+  { id: '5', displayName: 'Margaret Hamilton', username: 'margaret' },
+  { id: '6', displayName: 'Katherine Johnson', username: 'katherine' },
+  { id: '7', displayName: 'Dennis Ritchie', username: 'dennis' },
+];
+
+const WITH_PHOTOS: AvatarGroupItem[] = [
+  {
+    id: '1',
+    displayName: 'Nate Isern',
+    username: 'nate',
+    uri: 'https://images.unsplash.com/photo-1535713875002-d1d0cf377fde?w=200&h=200&fit=crop',
+  },
+  {
+    id: '2',
+    displayName: 'Jordan Lee',
+    username: 'jordan',
+    uri: 'https://images.unsplash.com/photo-1502685104226-ee32379fefbe?w=200&h=200&fit=crop',
+  },
+  {
+    id: '3',
+    displayName: 'Sam Rivera',
+    username: 'sam',
+    uri: 'https://images.unsplash.com/photo-1438761681033-6461ffad8d80?w=200&h=200&fit=crop',
+  },
+  { id: '4', displayName: 'Priya Patel', username: 'priya' },
+  { id: '5', displayName: 'Chris Doe', username: 'chris' },
+];
+
+const meta: Meta<typeof AvatarGroup> = {
+  title: 'Components/AvatarGroup',
+  component: AvatarGroup,
+  argTypes: {
+    size: { control: { type: 'number', min: 16, max: 96, step: 4 } },
+    max: { control: { type: 'number', min: 1, max: 10, step: 1 } },
+    overlap: { control: { type: 'number', min: 0, max: 48, step: 1 } },
+    hoverCard: { control: 'boolean' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof AvatarGroup>;
+
+/** Header / starter-pack use-case: purely presentational, no interaction. */
+export const Presentational: Story = {
+  args: { items: ITEMS, size: 32, max: 5 },
+};
+
+export const WithPhotos: Story = {
+  args: { items: WITH_PHOTOS, size: 40, max: 5 },
+  name: 'With photos',
+};
+
+/** Overflow chip showing `+N` derived from `total`. */
+export const WithTotal: Story = {
+  args: { items: ITEMS, size: 36, max: 4, total: 128 },
+  name: 'With explicit total',
+};
+
+/** Each avatar is pressable — the consumer navigates to the profile. */
+export const Pressable: Story = {
+  render: (args) => (
+    <View style={{ gap: 12 }}>
+      <AvatarGroup
+        {...args}
+        items={ITEMS}
+        size={40}
+        max={5}
+        onPressItem={(item) => {
+          // eslint-disable-next-line no-alert
+          if (typeof window !== 'undefined') window.alert(`@${item.username}`);
+        }}
+      />
+      <Text>Tap an avatar to fire onPressItem.</Text>
+    </View>
+  ),
+};
+
+/** Web-only: hovering an avatar reveals the UserHoverCard. */
+export const HoverCard: Story = {
+  render: (args) => (
+    <View style={{ gap: 12, minHeight: 240 }}>
+      <AvatarGroup
+        {...args}
+        items={WITH_PHOTOS}
+        size={44}
+        max={5}
+        hoverCard
+        onPressItem={(item) => {
+          // eslint-disable-next-line no-alert
+          if (typeof window !== 'undefined') window.alert(`@${item.username}`);
+        }}
+        renderItemAction={(item) => (
+          <View
+            style={{
+              paddingHorizontal: 12,
+              paddingVertical: 6,
+              borderRadius: 999,
+              backgroundColor: '#1A73E8',
+            }}
+          >
+            <Text style={{ color: '#fff', fontWeight: '600', fontSize: 13 }}>
+              Follow
+            </Text>
+          </View>
+        )}
+      />
+      <Text>Hover an avatar (web) to see the card with an injected action.</Text>
+    </View>
+  ),
+  name: 'Hover card (web)',
+};
+
+export const Sizes: Story = {
+  render: () => (
+    <View style={{ gap: 16 }}>
+      <AvatarGroup items={ITEMS} size={24} max={5} />
+      <AvatarGroup items={ITEMS} size={32} max={5} />
+      <AvatarGroup items={ITEMS} size={48} max={5} />
+      <AvatarGroup items={ITEMS} size={64} max={5} />
+    </View>
+  ),
+};

package/src/avatar-group/AvatarGroup.tsx

@@ -0,0 +1,19 @@
+import React, { memo } from 'react';
+
+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.
+ *
+ * Hover behavior is web-only; on native the `hoverCard` / `renderItemAction`
+ * props are accepted for API parity but intentionally do nothing (no hover on
+ * touch devices). The web fork (`AvatarGroup.web.tsx`) wires up the hover card.
+ */
+const AvatarGroupComponent: React.FC<AvatarGroupProps> = (props) => {
+  return <AvatarGroupBase {...props} />;
+};
+
+export const AvatarGroup = memo(AvatarGroupComponent);
+AvatarGroup.displayName = 'AvatarGroup';

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

@@ -0,0 +1,145 @@
+import React, { memo, useCallback, useMemo, useRef, useState } from 'react';
+import { Pressable, StyleSheet, View } from 'react-native';
+
+import { Portal } from '../portal';
+import { Z_INDEX } from '../styles/z-index';
+import { UserHoverCard } from '../user-hover-card';
+import {
+  AvatarGroupBase,
+  type AvatarGroupCellHoverHandlers,
+} from './AvatarGroupBase';
+import type { AvatarGroupItem, AvatarGroupProps } from './types';
+
+/** Delay before dismissing the card so the cursor can travel into it. */
+const CLOSE_DELAY_MS = 120;
+/** Gap between the anchored avatar and the floating card. */
+const CARD_GAP = 8;
+const CARD_WIDTH = 280;
+
+interface HoverState {
+  item: AvatarGroupItem;
+  index: number;
+  top: number;
+  left: number;
+}
+
+function getItemName(item: AvatarGroupItem): string {
+  return item.displayName ?? item.name ?? item.username ?? '';
+}
+
+/**
+ * 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.
+ */
+const AvatarGroupWebComponent: React.FC<AvatarGroupProps> = (props) => {
+  const { hoverCard, renderItemAction, onPressItem } = props;
+  const [hover, setHover] = useState<HoverState | null>(null);
+  const cellRefs = useRef<Map<number, View>>(new Map());
+  const closeTimer = useRef<ReturnType<typeof setTimeout> | null>(null);
+
+  const cancelClose = useCallback(() => {
+    if (closeTimer.current) {
+      clearTimeout(closeTimer.current);
+      closeTimer.current = null;
+    }
+  }, []);
+
+  const scheduleClose = useCallback(() => {
+    cancelClose();
+    closeTimer.current = setTimeout(() => setHover(null), CLOSE_DELAY_MS);
+  }, [cancelClose]);
+
+  const registerCellRef = useCallback((index: number, node: View | null) => {
+    if (node) cellRefs.current.set(index, node);
+    else cellRefs.current.delete(index);
+  }, []);
+
+  const handleHoverIn = useCallback(
+    (item: AvatarGroupItem, index: number) => {
+      cancelClose();
+      const node = cellRefs.current.get(index);
+      if (!node) return;
+      node.measureInWindow((x, y, width, height) => {
+        // Center the card under the avatar, clamped to the viewport.
+        const viewportWidth =
+          typeof window !== 'undefined' ? window.innerWidth : CARD_WIDTH;
+        let left = x + width / 2 - CARD_WIDTH / 2;
+        left = Math.max(
+          CARD_GAP,
+          Math.min(left, viewportWidth - CARD_WIDTH - CARD_GAP),
+        );
+        setHover({
+          item,
+          index,
+          top: y + height + CARD_GAP,
+          left,
+        });
+      });
+    },
+    [cancelClose],
+  );
+
+  const hoverHandlers = useMemo<AvatarGroupCellHoverHandlers | undefined>(() => {
+    if (!hoverCard) return undefined;
+    return {
+      onHoverIn: handleHoverIn,
+      onHoverOut: scheduleClose,
+      registerCellRef,
+    };
+  }, [hoverCard, handleHoverIn, scheduleClose, registerCellRef]);
+
+  return (
+    <>
+      <AvatarGroupBase {...props} hoverHandlers={hoverHandlers} />
+      {hoverCard && hover && (
+        <Portal>
+          {/*
+            A Pressable hosts the hover-bridge: `onHoverIn`/`onHoverOut` are
+            typed in React Native (and map to mouseenter/mouseleave on
+            react-native-web), so the card stays open while the cursor is over
+            it without any web-only DOM-prop type suppression.
+          */}
+          <Pressable
+            onHoverIn={cancelClose}
+            onHoverOut={scheduleClose}
+            accessibilityRole="none"
+            pointerEvents="auto"
+            style={[
+              webStyles.floating,
+              { top: hover.top, left: hover.left, width: CARD_WIDTH },
+            ]}
+          >
+            <UserHoverCard
+              avatar={hover.item.uri ?? undefined}
+              displayName={getItemName(hover.item)}
+              username={hover.item.username}
+              onPressProfile={
+                onPressItem
+                  ? () => onPressItem(hover.item, hover.index)
+                  : undefined
+              }
+              action={renderItemAction?.(hover.item, hover.index)}
+              style={webStyles.card}
+            />
+          </Pressable>
+        </Portal>
+      )}
+    </>
+  );
+};
+
+const webStyles = StyleSheet.create({
+  floating: {
+    position: 'fixed' as 'absolute',
+    zIndex: Z_INDEX.tooltip,
+  },
+  card: {
+    width: CARD_WIDTH,
+  },
+});
+
+export const AvatarGroup = memo(AvatarGroupWebComponent);
+AvatarGroup.displayName = 'AvatarGroup';

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/theme/color-scope/index.web.tsx

@@ -3,20 +3,19 @@ import React, { Children, cloneElement, isValidElement, useContext, useMemo } fr
 import { BloomThemeContext, type BloomThemeContextValue } from '../BloomThemeProvider';
 import { buildTheme } from '../build-theme';
 import type { AppColorName } from '../color-presets';
-import { getResolvedTokens } from '../token-registry';
+import { buildScopeVars } from './style-builder';
 
 /**
- * `getResolvedTokens` returns every canonical token already resolved to an sRGB
- * `rgb(...)` string — the SAME pipeline the document-root web writer and the
- * native writer use. Scoped onto an element's inline `style`, Tailwind v4's
- * compiled utilities read these as `var(--x)` directly, so each base token is a
- * full CSS color with no per-value wrapping needed.
+ * `buildScopeVars` returns every canonical token already resolved to an sRGB
+ * `rgb(...)` string, plus the `--color-*` aliases consumed by Tailwind v4
+ * utilities. Scoped onto an element's inline `style`, profile-level NativeWind
+ * classes resolve against the subtree preset instead of the document root.
  */
 function buildWebScopeVars(
   colorPreset: AppColorName,
   mode: 'light' | 'dark',
 ): React.CSSProperties {
-  return getResolvedTokens(colorPreset, mode) as React.CSSProperties;
+  return buildScopeVars(colorPreset, mode) as React.CSSProperties;
 }
 
 export interface BloomColorScopeProps {