@oxyhq/bloom 0.29.6 → 0.30.1

package/src/activity-heatmap/types.ts

@@ -0,0 +1,74 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/** A single day cell in the {@link ActivityHeatmap}. */
+export interface ActivityHeatmapDay {
+  /** ISO `YYYY-MM-DD` date (parsed in UTC). */
+  date: string;
+  /** Activity count for that day. */
+  count: number;
+}
+
+export interface ActivityHeatmapProps {
+  /** Per-day activity counts. Days not present are treated as count 0. */
+  data: ActivityHeatmapDay[];
+  /**
+   * Number of days to render, ending at `endDate`.
+   * @default 364
+   */
+  numDays?: number;
+  /**
+   * Last (rightmost) day of the grid as `YYYY-MM-DD`. Defaults to the latest
+   * date present in `data`. The component never reads the system clock, so pass
+   * `endDate` explicitly to anchor the grid to "today".
+   */
+  endDate?: string;
+  /**
+   * Ascending count thresholds partitioning positive counts into color levels.
+   * With N thresholds a positive count maps to `colorScale[number of thresholds
+   * met]` (clamped to the scale). Count 0 always uses `emptyColor`.
+   * @default [1, 3, 6, 10]
+   */
+  levels?: number[];
+  /**
+   * Colors low→high. Index 0 is the faintest activity shade, the last index the
+   * strongest. Defaults to five opacity steps of `theme.colors.primary`.
+   */
+  colorScale?: string[];
+  /**
+   * Color for zero-activity days.
+   * @default theme.colors.backgroundSecondary
+   */
+  emptyColor?: string;
+  /**
+   * Side length of each day cell in px.
+   * @default 12
+   */
+  cellSize?: number;
+  /**
+   * Gap between cells in px (both axes).
+   * @default 3
+   */
+  gap?: number;
+  /**
+   * First day of the week: 0 = Sunday, 1 = Monday. Controls both the row order
+   * and how the leading partial week aligns.
+   * @default 0
+   */
+  weekStartsOn?: 0 | 1;
+  /**
+   * 12 short month names indexed by month (0 = January), for the month-label
+   * row. Pass localized names; defaults to English abbreviations.
+   */
+  monthLabels?: string[];
+  /**
+   * 7 short weekday names indexed by day of week (0 = Sunday). When provided, a
+   * weekday-label column is rendered to the left of the grid. Omit for no
+   * weekday column. Pass empty strings for rows you want left blank.
+   */
+  weekdayLabels?: string[];
+  /** Called with the pressed day. When set, each populated cell is pressable. */
+  onPressDay?: (day: ActivityHeatmapDay) => void;
+  /** Container style override. */
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

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

@@ -133,3 +133,17 @@ export const Sizes: Story = {
     </View>
   ),
 };
+
+/**
+ * Row layout: avatars placed adjacent with a positive gap and no separator
+ * ring — the "top tokens" / adjacent-icons strip. Still collapses to `+N`.
+ */
+export const RowLayout: Story = {
+  render: () => (
+    <View style={{ gap: 16 }}>
+      <AvatarGroup layout="row" items={WITH_PHOTOS} size={28} max={4} />
+      <AvatarGroup layout="row" items={WITH_PHOTOS} size={36} max={5} spacing={10} />
+    </View>
+  ),
+  name: 'Row layout',
+};

package/src/avatar-group/AvatarGroupBase.tsx

@@ -41,18 +41,22 @@ interface AvatarGroupBaseProps extends AvatarGroupProps {
 
 const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
   items,
+  layout = 'stack',
   size = 32,
   variant = 'thumb',
   max = 5,
   total,
   overlap,
+  spacing,
   ringColor,
+  showInitials = false,
   onPressItem,
   style,
   testID,
   hoverHandlers,
 }) => {
   const theme = useTheme();
+  const isRow = layout === 'row';
 
   // The ring is the thin separator drawn between overlapping avatars. It
   // defaults to the page background so avatars read as cleanly punched out of
@@ -65,6 +69,10 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
   // 1px border on each side, so the negative margin absorbs both borders to
   // keep the visual overlap equal to `effectiveOverlap`.
   const negativeMargin = -(effectiveOverlap + RING_WIDTH * 2);
+  // Row layout: a positive gap between adjacent avatars (no overlap, no ring).
+  const rowGap = spacing ?? Math.round(size * DEFAULT_OVERLAP_RATIO);
+  // Horizontal offset applied to every avatar after the first.
+  const itemMargin = isRow ? rowGap : negativeMargin;
 
   const shown = useMemo(
     () => items.slice(0, Math.max(0, max)),
@@ -74,11 +82,20 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
   const realTotal = total ?? items.length;
   const overflow = Math.max(0, realTotal - shown.length);
 
-  // Each cell is a circular, clipped container with a 1px ring border. The inner
-  // Avatar is inset by the border on both sides so the image fills the circle
-  // exactly inside the ring.
-  const innerSize = size - RING_WIDTH * 2;
+  // Stack: each cell is a circular, clipped container with a 1px ring border,
+  // and the inner Avatar is inset by the border on both sides. Row: no ring, so
+  // the Avatar fills the full cell.
+  const innerSize = isRow ? size : size - RING_WIDTH * 2;
   const cellStyle = useMemo((): ViewStyle => {
+    if (isRow) {
+      return {
+        width: size,
+        height: size,
+        borderRadius: size / 2,
+        alignItems: 'center',
+        justifyContent: 'center',
+      };
+    }
     return {
       width: size,
       height: size,
@@ -89,7 +106,7 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
       alignItems: 'center',
       justifyContent: 'center',
     };
-  }, [size, ring]);
+  }, [isRow, size, ring]);
 
   const overflowTextStyle = useMemo(
     () => ({
@@ -121,12 +138,14 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
           ? `${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.
+        // The horizontal margin and stacking order live on the outermost row
+        // element so layout and hit-testing stay aligned with the visual
+        // overlap. In stack mode earlier siblings render on top of later ones
+        // (descending zIndex); in row mode there is no overlap so stacking
+        // order is irrelevant.
         const wrapperStyle: ViewStyle = {
-          ...(index > 0 && { marginLeft: negativeMargin }),
-          zIndex: shown.length - index,
+          ...(index > 0 && { marginLeft: itemMargin }),
+          ...(isRow ? {} : { zIndex: shown.length - index }),
         };
 
         const cell = (
@@ -147,9 +166,15 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
               `'thumb'`) is forwarded so the resolver builds a small rendition
               for these stacked avatars. No `name` is passed, so a missing
               avatar shows Avatar's neutral default placeholder rather than a
-              colored deterministic initial.
+              colored deterministic initial. When `showInitials` is set the item's
+              name IS passed, so an avatar-less item renders a colored initial.
             */}
-            <Avatar source={item.uri ?? undefined} variant={variant} size={innerSize} />
+            <Avatar
+              source={item.uri ?? undefined}
+              name={showInitials ? name : undefined}
+              variant={variant}
+              size={innerSize}
+            />
           </View>
         );
 
@@ -190,7 +215,8 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
         <OverflowCircle
           count={overflow}
           cellStyle={cellStyle}
-          negativeMargin={shown.length > 0 ? negativeMargin : 0}
+          marginLeft={shown.length > 0 ? itemMargin : 0}
+          isRow={isRow}
           textStyle={overflowTextStyle}
           onPress={overflowOnPress}
         />
@@ -202,23 +228,25 @@ const AvatarGroupBaseComponent: React.FC<AvatarGroupBaseProps> = ({
 function OverflowCircle({
   count,
   cellStyle,
-  negativeMargin,
+  marginLeft,
+  isRow,
   textStyle,
   onPress,
 }: {
   count: number;
   cellStyle: ViewStyle;
-  negativeMargin: number;
+  marginLeft: number;
+  isRow: boolean;
   textStyle: { color: string; fontSize: number; fontWeight: '600' };
   onPress?: () => void;
 }) {
   const theme = useTheme();
-  // The count circle 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.
+  // In stack mode the count circle is anchored at the lowest stacking order so
+  // it tucks behind the last avatar's ring; row mode has no overlap. The margin
+  // lives on the outer element to keep layout aligned with the spacing.
   const wrapperStyle: ViewStyle = {
-    ...(negativeMargin !== 0 && { marginLeft: negativeMargin }),
-    zIndex: 0,
+    ...(marginLeft !== 0 && { marginLeft }),
+    ...(isRow ? {} : { zIndex: 0 }),
   };
 
   // A solid "+N" count circle: secondary-text-colored fill with white text,

package/src/avatar-group/types.ts

@@ -28,6 +28,15 @@ export interface AvatarGroupItem {
 export interface AvatarGroupProps {
   /** Members to render, in stacking order (first item sits on top). */
   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.
+   * - `'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`.
+   */
+  layout?: 'stack' | 'row';
   /** Diameter of each avatar in pixels. */
   size?: number;
   /**
@@ -47,15 +56,28 @@ export interface AvatarGroupProps {
   total?: number;
   /**
    * Horizontal overlap between adjacent avatars in pixels. Defaults to ~1/3 of
-   * `size`. Larger values pull avatars closer together.
+   * `size`. Larger values pull avatars closer together. `layout='stack'` only.
    */
   overlap?: number;
+  /**
+   * Horizontal gap between adjacent avatars in pixels when `layout='row'`.
+   * Defaults to ~1/3 of `size`. `layout='row'` only.
+   */
+  spacing?: number;
   /**
    * Color of the thin ring/border drawn around each avatar so overlapping
    * avatars separate cleanly. Defaults to the theme `background` color so the
    * avatars read as punched out of the surface behind them.
    */
   ringColor?: string;
+  /**
+   * When true, an item with no `uri` renders {@link Avatar}'s colored
+   * deterministic initial (derived from its name) instead of the neutral
+   * default placeholder. Use for decorative/icon rows (e.g. a top-tokens strip)
+   * where distinct colors read better than identical grey circles. Defaults to
+   * `false` to preserve the neutral facepile placeholder for avatar-less people.
+   */
+  showInitials?: boolean;
   /**
    * Per-avatar press handler. When provided, each avatar (and the overflow chip)
    * becomes pressable. When omitted, the group is purely presentational.

package/src/composition-bar/CompositionBar.stories.tsx

@@ -0,0 +1,70 @@
+import React, { useState } from 'react';
+import { View } from 'react-native';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { CompositionBar } from './index';
+import type { CompositionCategory } from './index';
+import { BloomThemeProvider } from '../theme';
+
+const CATEGORIES: CompositionCategory[] = [
+  { key: 'content', name: 'Content', amount: 320, color: '#6366F1' },
+  { key: 'social', name: 'Social', amount: 180, color: '#10B981' },
+  { key: 'trust', name: 'Trust', amount: 96, color: '#F59E0B' },
+  { key: 'physical', name: 'Physical', amount: 44, color: '#EF4444' },
+];
+
+function Demo() {
+  const [selectedKey, setSelectedKey] = useState<string | null>(null);
+  return (
+    <CompositionBar
+      categories={CATEGORIES}
+      selectedKey={selectedKey}
+      onSelect={(key) => setSelectedKey((prev) => (prev === key ? null : key))}
+      hintLabel="Tap a segment to see its share"
+    />
+  );
+}
+
+const meta: Meta<typeof CompositionBar> = {
+  title: 'Data Display/CompositionBar',
+  component: CompositionBar,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof CompositionBar>;
+
+export const Light: Story = {
+  render: () => (
+    <BloomThemeProvider mode="light">
+      <View style={{ padding: 24, width: 360 }}>
+        <Demo />
+      </View>
+    </BloomThemeProvider>
+  ),
+};
+
+export const Dark: Story = {
+  render: () => (
+    <BloomThemeProvider mode="dark">
+      <View style={{ padding: 24, width: 360, backgroundColor: '#000' }}>
+        <Demo />
+      </View>
+    </BloomThemeProvider>
+  ),
+};
+
+export const Empty: Story = {
+  render: () => (
+    <BloomThemeProvider mode="light">
+      <View style={{ padding: 24, width: 360 }}>
+        <CompositionBar
+          categories={[]}
+          selectedKey={null}
+          onSelect={() => {}}
+          hintLabel="No data yet"
+        />
+      </View>
+    </BloomThemeProvider>
+  ),
+};

package/src/composition-bar/CompositionBar.tsx

@@ -0,0 +1,161 @@
+import React, { memo, useMemo } from 'react';
+import { View, StyleSheet, Pressable } from 'react-native';
+
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import type { CompositionBarProps } from './types';
+
+const BAR_HEIGHT = 44;
+/** Fully-rounded capsule ends. */
+const RADIUS_FULL = BAR_HEIGHT / 2;
+/** Slight inner-corner rounding so segments read as one bar, not buttons. */
+const RADIUS_INNER = 8;
+/** Floor so a tiny category stays tappable/visible; flexbox renormalizes the rest. */
+const MIN_SEGMENT_WIDTH = 18;
+
+function defaultFormatReadout(points: number, percent: number): string {
+  return `${points} pts · ${percent}%`;
+}
+
+/**
+ * The distribution bar — the signature composition visual. A single thick
+ * capsule split into one colored block per category, each block's width
+ * proportional to that category's share of the total (never a progress bar —
+ * the segments always fill the full width). The first/last blocks carry the
+ * rounded capsule ends; inner blocks are only slightly rounded and separated by
+ * a hairline-thin background gap so they read as ONE bar. Tapping a block
+ * selects it (dimming the rest) and reveals a readout of its name, points, and
+ * percentage; selection is lifted so the matching list row highlights in sync.
+ */
+const CompositionBarComponent: React.FC<CompositionBarProps> = ({
+  categories,
+  selectedKey,
+  onSelect,
+  hintLabel,
+  formatReadout = defaultFormatReadout,
+  style,
+  testID,
+}) => {
+  const { colors } = useTheme();
+
+  const positive = useMemo(
+    () => categories.filter((category) => category.amount > 0),
+    [categories],
+  );
+  const total = useMemo(
+    () => positive.reduce((sum, category) => sum + category.amount, 0),
+    [positive],
+  );
+  const selected = useMemo(
+    () => (selectedKey ? positive.find((category) => category.key === selectedKey) ?? null : null),
+    [positive, selectedKey],
+  );
+
+  if (total <= 0) {
+    return (
+      <View
+        style={[styles.emptyTrack, { backgroundColor: colors.backgroundSecondary }, style]}
+        testID={testID}
+      />
+    );
+  }
+
+  const selectedPercent = selected ? Math.round((selected.amount / total) * 100) : 0;
+
+  return (
+    <View style={[styles.wrap, style]} testID={testID}>
+      <View style={styles.bar}>
+        {positive.map((category, index) => {
+          const isFirst = index === 0;
+          const isLast = index === positive.length - 1;
+          const dim = selected != null && category.key !== selectedKey;
+          return (
+            <Pressable
+              key={category.key}
+              onPress={() => onSelect(category.key)}
+              accessibilityRole="button"
+              accessibilityLabel={category.name}
+              accessibilityState={{ selected: category.key === selectedKey }}
+              style={[
+                styles.segment,
+                {
+                  flexGrow: category.amount,
+                  backgroundColor: category.color,
+                  opacity: dim ? 0.35 : 1,
+                  borderTopLeftRadius: isFirst ? RADIUS_FULL : RADIUS_INNER,
+                  borderBottomLeftRadius: isFirst ? RADIUS_FULL : RADIUS_INNER,
+                  borderTopRightRadius: isLast ? RADIUS_FULL : RADIUS_INNER,
+                  borderBottomRightRadius: isLast ? RADIUS_FULL : RADIUS_INNER,
+                },
+              ]}
+            />
+          );
+        })}
+      </View>
+
+      {selected ? (
+        <View style={styles.readout}>
+          <View style={[styles.readoutDot, { backgroundColor: selected.color }]} />
+          <Text style={[styles.readoutName, { color: colors.text }]} numberOfLines={1}>
+            {selected.name}
+          </Text>
+          <Text style={[styles.readoutMeta, { color: colors.textSecondary }]} numberOfLines={1}>
+            {formatReadout(selected.amount, selectedPercent)}
+          </Text>
+        </View>
+      ) : (
+        <Text style={[styles.hint, { color: colors.textSecondary }]} numberOfLines={1}>
+          {hintLabel}
+        </Text>
+      )}
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  wrap: {
+    gap: 12,
+  },
+  bar: {
+    flexDirection: 'row',
+    height: BAR_HEIGHT,
+    gap: 3,
+  },
+  segment: {
+    flexBasis: 0,
+    minWidth: MIN_SEGMENT_WIDTH,
+    height: BAR_HEIGHT,
+    borderCurve: 'continuous',
+  },
+  emptyTrack: {
+    height: BAR_HEIGHT,
+    borderRadius: RADIUS_FULL,
+    borderCurve: 'continuous',
+  },
+  readout: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 8,
+  },
+  readoutDot: {
+    width: 10,
+    height: 10,
+    borderRadius: 5,
+  },
+  readoutName: {
+    fontSize: 14,
+    fontWeight: '700',
+    letterSpacing: -0.2,
+  },
+  readoutMeta: {
+    flexShrink: 1,
+    fontSize: 13,
+    fontVariant: ['tabular-nums'],
+  },
+  hint: {
+    fontSize: 13,
+  },
+});
+
+export const CompositionBar = memo(CompositionBarComponent);
+CompositionBar.displayName = 'CompositionBar';

package/src/composition-bar/index.ts

@@ -0,0 +1,2 @@
+export { CompositionBar } from './CompositionBar';
+export type { CompositionBarProps, CompositionCategory } from './types';

package/src/composition-bar/types.ts

@@ -0,0 +1,30 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+/** One distribution-bar category. Percentages are computed internally. */
+export interface CompositionCategory {
+  key: string;
+  name: string;
+  /** Non-negative magnitude; the segment width is its share of the total. */
+  amount: number;
+  color: string;
+}
+
+export interface CompositionBarProps {
+  /** Categories to render, in left→right order. Non-positive amounts are dropped. */
+  categories: CompositionCategory[];
+  /** The currently-selected category key, or null. */
+  selectedKey: string | null;
+  /** Called with a category key when a segment is pressed. */
+  onSelect: (key: string) => void;
+  /** Text shown below the bar when nothing is selected. */
+  hintLabel: string;
+  /**
+   * Formats the readout shown below the bar for the selected segment. Receives
+   * the raw amount (points) and the rounded share percentage (0–100).
+   * @default `(points, percent) => `${points} pts · ${percent}%``
+   */
+  formatReadout?: (points: number, percent: number) => string;
+  /** Container style override. */
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}

package/src/dot-grid-meter/DotGridMeter.stories.tsx

@@ -0,0 +1,47 @@
+import React from 'react';
+import { View } from 'react-native';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { DotGridMeter } from './index';
+import { BloomThemeProvider } from '../theme';
+import { Text } from '../typography';
+
+function Demo() {
+  return (
+    <View style={{ gap: 16 }}>
+      <Text style={{ fontSize: 12, opacity: 0.6 }}>Token diversity</Text>
+      <DotGridMeter filled={34} total={50} columns={10} />
+      <Text style={{ fontSize: 12, opacity: 0.6 }}>Compact (accent)</Text>
+      <DotGridMeter filled={7} total={12} columns={6} dotSize={12} gap={8} filledColor="#8B5CF6" />
+    </View>
+  );
+}
+
+const meta: Meta<typeof DotGridMeter> = {
+  title: 'Data Display/DotGridMeter',
+  component: DotGridMeter,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof DotGridMeter>;
+
+export const Light: Story = {
+  render: () => (
+    <BloomThemeProvider mode="light">
+      <View style={{ padding: 24 }}>
+        <Demo />
+      </View>
+    </BloomThemeProvider>
+  ),
+};
+
+export const Dark: Story = {
+  render: () => (
+    <BloomThemeProvider mode="dark">
+      <View style={{ padding: 24, backgroundColor: '#000' }}>
+        <Demo />
+      </View>
+    </BloomThemeProvider>
+  ),
+};

package/src/dot-grid-meter/DotGridMeter.tsx

@@ -0,0 +1,71 @@
+import React, { memo, useMemo } from 'react';
+import { View } from 'react-native';
+
+import { useTheme } from '../theme/use-theme';
+import type { DotGridMeterProps } from './types';
+
+/**
+ * A data-driven grid of small circular dots — the "diversity meter" visual. The
+ * first `filled` dots use `filledColor`, the rest use `emptyColor`, laid out in
+ * a flex-wrapped grid of `columns` per row. Pure `<View>` composition (no SVG),
+ * so it renders identically on web and native.
+ */
+const DotGridMeterComponent: React.FC<DotGridMeterProps> = ({
+  filled,
+  total,
+  columns = 10,
+  dotSize = 10,
+  gap = 6,
+  filledColor,
+  emptyColor,
+  style,
+  testID,
+}) => {
+  const { colors } = useTheme();
+  const onColor = filledColor ?? colors.success;
+  const offColor = emptyColor ?? colors.backgroundSecondary;
+
+  const safeTotal = Math.max(0, Math.floor(total));
+  const safeFilled = Math.min(safeTotal, Math.max(0, Math.floor(filled)));
+  // A row can hold at most `columns` dots; a grid narrower than one full row
+  // should still wrap tightly, so the container width follows the smaller count.
+  const perRow = Math.max(1, Math.floor(columns));
+  const rowWidth = Math.min(safeTotal, perRow);
+
+  const dots = useMemo(
+    () => Array.from({ length: safeTotal }, (_, index) => index < safeFilled),
+    [safeTotal, safeFilled],
+  );
+
+  return (
+    <View
+      style={[
+        {
+          flexDirection: 'row',
+          flexWrap: 'wrap',
+          gap,
+          width: rowWidth * dotSize + Math.max(0, rowWidth - 1) * gap,
+        },
+        style,
+      ]}
+      accessibilityRole="progressbar"
+      accessibilityValue={{ min: 0, max: safeTotal, now: safeFilled }}
+      testID={testID}
+    >
+      {dots.map((isFilled, index) => (
+        <View
+          key={index}
+          style={{
+            width: dotSize,
+            height: dotSize,
+            borderRadius: dotSize / 2,
+            backgroundColor: isFilled ? onColor : offColor,
+          }}
+        />
+      ))}
+    </View>
+  );
+};
+
+export const DotGridMeter = memo(DotGridMeterComponent);
+DotGridMeter.displayName = 'DotGridMeter';

package/src/dot-grid-meter/index.ts

@@ -0,0 +1,2 @@
+export { DotGridMeter } from './DotGridMeter';
+export type { DotGridMeterProps } from './types';