@oxyhq/bloom 0.29.6 → 0.30.0

package/src/__tests__/public-api-contract.test.ts

@@ -19,6 +19,11 @@ const REPRESENTATIVE_PARTS = [
   'AdmonitionIcon', 'PromptInputTextarea',
 ] as const;
 
+// Stat / profile widget components added to the public surface.
+const NEW_FLAT_COMPONENTS = [
+  'CompositionBar', 'DotGridMeter', 'StatBar', 'ActivityHeatmap', 'ProfileCard',
+] as const;
+
 /**
  * A flat React component export is either a plain function component or a wrapped
  * component object (React.memo / forwardRef), which carries a `$$typeof` symbol.
@@ -51,4 +56,14 @@ describe('public API contract', () => {
       expect(isReactComponent(api[name])).toBe(true);
     }
   });
+
+  it('exposes the stat/profile widget components as flat components', () => {
+    for (const name of NEW_FLAT_COMPONENTS) {
+      expect(isReactComponent(api[name])).toBe(true);
+    }
+  });
+
+  it('exposes bucketByDay as a helper function', () => {
+    expect(typeof api.bucketByDay).toBe('function');
+  });
 });

package/src/activity-heatmap/ActivityHeatmap.stories.tsx

@@ -0,0 +1,108 @@
+import React from 'react';
+import { View, ScrollView } from 'react-native';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ActivityHeatmap, bucketByDay } from './index';
+import type { ActivityHeatmapDay } from './index';
+import { BloomThemeProvider } from '../theme';
+
+const END_DATE = '2026-06-30';
+
+/** Deterministic pseudo-random sample so stories render stably. */
+function sampleData(days: number, endKey: string): ActivityHeatmapDay[] {
+  const [y, m, d] = endKey.split('-').map(Number);
+  const end = Date.UTC(y ?? 2026, (m ?? 1) - 1, d ?? 1);
+  const out: ActivityHeatmapDay[] = [];
+  let seed = 42;
+  for (let i = 0; i < days; i++) {
+    seed = (seed * 1103515245 + 12345) & 0x7fffffff;
+    const roll = seed % 100;
+    const count = roll < 45 ? 0 : roll < 70 ? 1 : roll < 85 ? 3 : roll < 95 ? 7 : 14;
+    const ts = end - (days - 1 - i) * 86_400_000;
+    const dt = new Date(ts);
+    const key = `${dt.getUTCFullYear()}-${String(dt.getUTCMonth() + 1).padStart(2, '0')}-${String(
+      dt.getUTCDate(),
+    ).padStart(2, '0')}`;
+    if (count > 0) out.push({ date: key, count });
+  }
+  return out;
+}
+
+const DATA = sampleData(364, END_DATE);
+
+const meta: Meta<typeof ActivityHeatmap> = {
+  title: 'Data Display/ActivityHeatmap',
+  component: ActivityHeatmap,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ActivityHeatmap>;
+
+export const Light: Story = {
+  render: () => (
+    <BloomThemeProvider mode="light">
+      <View style={{ padding: 24 }}>
+        <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+          <ActivityHeatmap
+            data={DATA}
+            endDate={END_DATE}
+            weekdayLabels={['', 'Mon', '', 'Wed', '', 'Fri', '']}
+          />
+        </ScrollView>
+      </View>
+    </BloomThemeProvider>
+  ),
+};
+
+export const Dark: Story = {
+  render: () => (
+    <BloomThemeProvider mode="dark">
+      <View style={{ padding: 24, backgroundColor: '#000' }}>
+        <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+          <ActivityHeatmap
+            data={DATA}
+            endDate={END_DATE}
+            weekdayLabels={['', 'Mon', '', 'Wed', '', 'Fri', '']}
+          />
+        </ScrollView>
+      </View>
+    </BloomThemeProvider>
+  ),
+};
+
+export const CustomScale: Story = {
+  render: () => (
+    <BloomThemeProvider mode="dark">
+      <View style={{ padding: 24, backgroundColor: '#000' }}>
+        <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+          <ActivityHeatmap
+            data={DATA}
+            endDate={END_DATE}
+            numDays={140}
+            cellSize={14}
+            gap={4}
+            colorScale={['#0E3B2E', '#146B4C', '#1FA971', '#38D896', '#7DF3BD']}
+          />
+        </ScrollView>
+      </View>
+    </BloomThemeProvider>
+  ),
+};
+
+/** Demonstrates the `bucketByDay` helper grouping raw timestamps. */
+export const FromRawEvents: Story = {
+  render: () => {
+    const events = DATA.flatMap((d) => Array.from({ length: d.count }, () => ({ at: d.date })));
+    const bucketed = bucketByDay(events, (e) => e.at);
+    return (
+      <BloomThemeProvider mode="light">
+        <View style={{ padding: 24 }}>
+          <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+            <ActivityHeatmap data={bucketed} endDate={END_DATE} />
+          </ScrollView>
+        </View>
+      </BloomThemeProvider>
+    );
+  },
+};

package/src/activity-heatmap/ActivityHeatmap.tsx

@@ -0,0 +1,289 @@
+import React, { memo, useMemo } from 'react';
+import { View, Pressable, StyleSheet } from 'react-native';
+
+import { useTheme } from '../theme/use-theme';
+import { Text } from '../typography';
+import type { ActivityHeatmapDay, ActivityHeatmapProps } from './types';
+
+const DAY_MS = 86_400_000;
+const DEFAULT_NUM_DAYS = 364;
+const DEFAULT_LEVELS = [1, 3, 6, 10];
+const DEFAULT_MONTHS = [
+  'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
+  'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec',
+];
+/** Opacity steps (low→high) used to derive the default color scale from primary. */
+const DEFAULT_ALPHAS = [0.16, 0.32, 0.52, 0.75, 1];
+const LABEL_FONT_SIZE = 10;
+const MONTH_ROW_HEIGHT = 16;
+const WEEKDAY_COL_WIDTH = 26;
+
+const DATE_KEY_RE = /^(\d{4})-(\d{2})-(\d{2})/;
+
+function parseDateKey(key: string): number | null {
+  const match = DATE_KEY_RE.exec(key);
+  if (match) {
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const ts = Date.UTC(year, month - 1, day);
+    return Number.isNaN(ts) ? null : ts;
+  }
+  const parsed = Date.parse(key);
+  return Number.isNaN(parsed) ? null : parsed;
+}
+
+function formatUtcKey(ts: number): string {
+  const d = new Date(ts);
+  const year = d.getUTCFullYear();
+  const month = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/** Count of ascending thresholds `count` meets — the color-scale index. */
+function levelForCount(count: number, levels: number[]): number {
+  if (count <= 0) return 0;
+  let level = 0;
+  for (const threshold of levels) {
+    if (count >= threshold) level += 1;
+    else break;
+  }
+  return level;
+}
+
+function parseRgb(color: string): { r: number; g: number; b: number } | null {
+  const trimmed = color.trim();
+  if (trimmed.startsWith('#')) {
+    let hex = trimmed.slice(1);
+    if (hex.length === 3) hex = hex.split('').map((c) => c + c).join('');
+    if (hex.length !== 6) return null;
+    const r = parseInt(hex.slice(0, 2), 16);
+    const g = parseInt(hex.slice(2, 4), 16);
+    const b = parseInt(hex.slice(4, 6), 16);
+    if ([r, g, b].some((v) => Number.isNaN(v))) return null;
+    return { r, g, b };
+  }
+  const match = /rgba?\(([^)]+)\)/i.exec(trimmed);
+  if (!match || match[1] === undefined) return null;
+  const parts = match[1].split(/[\s,/]+/).filter(Boolean).map(Number);
+  if (parts.length < 3) return null;
+  const [r, g, b] = parts;
+  if (r === undefined || g === undefined || b === undefined) return null;
+  if ([r, g, b].some((v) => Number.isNaN(v))) return null;
+  return { r, g, b };
+}
+
+/** Compose `color` at `alpha`; returns the input unchanged if it can't parse. */
+function withAlpha(color: string, alpha: number): string {
+  const rgb = parseRgb(color);
+  if (!rgb) return color;
+  return `rgba(${rgb.r}, ${rgb.g}, ${rgb.b}, ${alpha})`;
+}
+
+interface Cell {
+  key: string;
+  count: number;
+  color: string;
+}
+
+/**
+ * A GitHub-style contribution graph: columns of weeks × 7 weekday rows of
+ * rounded square cells, each colored by its day's activity level. Pure `<View>`
+ * composition (no SVG), rendering identically on web and native. The component
+ * lays out at its natural width — wrap it in a horizontal `ScrollView` for
+ * narrow viewports. All date math runs in UTC and the system clock is never
+ * read; anchor the grid with `endDate`.
+ */
+const ActivityHeatmapComponent: React.FC<ActivityHeatmapProps> = ({
+  data,
+  numDays = DEFAULT_NUM_DAYS,
+  endDate,
+  levels = DEFAULT_LEVELS,
+  colorScale,
+  emptyColor,
+  cellSize = 12,
+  gap = 3,
+  weekStartsOn = 0,
+  monthLabels,
+  weekdayLabels,
+  onPressDay,
+  style,
+  testID,
+}) => {
+  const { colors } = useTheme();
+  const empty = emptyColor ?? colors.backgroundSecondary;
+  const scale = useMemo(
+    () => colorScale ?? DEFAULT_ALPHAS.map((alpha) => withAlpha(colors.primary, alpha)),
+    [colorScale, colors.primary],
+  );
+  const sortedLevels = useMemo(() => [...levels].sort((a, b) => a - b), [levels]);
+  const months = monthLabels ?? DEFAULT_MONTHS;
+
+  const grid = useMemo(() => {
+    // Sum counts per UTC day.
+    const countByKey = new Map<string, number>();
+    let latest: number | null = null;
+    for (const entry of data) {
+      const ts = parseDateKey(entry.date);
+      if (ts === null) continue;
+      const key = formatUtcKey(ts);
+      countByKey.set(key, (countByKey.get(key) ?? 0) + entry.count);
+      if (latest === null || ts > latest) latest = ts;
+    }
+
+    const providedEnd = endDate ? parseDateKey(endDate) : null;
+    const endTs = providedEnd ?? latest;
+    if (endTs === null) return null;
+
+    const days = Math.max(1, Math.floor(numDays));
+    const rawStart = endTs - (days - 1) * DAY_MS;
+    // Align the first column to the start-of-week boundary.
+    const back = (new Date(rawStart).getUTCDay() - weekStartsOn + 7) % 7;
+    const gridStart = rawStart - back * DAY_MS;
+    const columnCount = Math.ceil((Math.floor((endTs - gridStart) / DAY_MS) + 1) / 7);
+
+    const maxColor = scale.length - 1;
+    const columns: Array<Array<Cell | null>> = [];
+    for (let c = 0; c < columnCount; c++) {
+      const column: Array<Cell | null> = [];
+      for (let r = 0; r < 7; r++) {
+        const ts = gridStart + (c * 7 + r) * DAY_MS;
+        if (ts > endTs) {
+          column.push(null);
+          continue;
+        }
+        const key = formatUtcKey(ts);
+        const count = countByKey.get(key) ?? 0;
+        const level = Math.min(levelForCount(count, sortedLevels), maxColor);
+        const color = count <= 0 ? empty : scale[level] ?? empty;
+        column.push({ key, count, color });
+      }
+      columns.push(column);
+    }
+
+    // Month labels: first column whose leading day starts a new month.
+    const monthMarks: Array<{ x: number; label: string }> = [];
+    let lastMonth = -1;
+    for (let c = 0; c < columnCount; c++) {
+      const firstTs = gridStart + c * 7 * DAY_MS;
+      const month = new Date(firstTs).getUTCMonth();
+      if (month !== lastMonth) {
+        monthMarks.push({ x: c * (cellSize + gap), label: months[month] ?? DEFAULT_MONTHS[month] ?? '' });
+        lastMonth = month;
+      }
+    }
+
+    return { columns, monthMarks };
+  }, [data, endDate, numDays, weekStartsOn, sortedLevels, scale, empty, cellSize, gap, months]);
+
+  if (!grid) {
+    return <View style={style} testID={testID} />;
+  }
+
+  const { columns, monthMarks } = grid;
+  const hasWeekdayCol = Array.isArray(weekdayLabels);
+  const weekdayColWidth = hasWeekdayCol ? WEEKDAY_COL_WIDTH : 0;
+  const monthRowMarginLeft = hasWeekdayCol ? weekdayColWidth + gap : 0;
+  const cellRadius = Math.max(2, Math.round(cellSize * 0.25));
+
+  return (
+    <View style={style} testID={testID}>
+      <View style={[styles.monthRow, { marginLeft: monthRowMarginLeft }]}>
+        {monthMarks.map((mark, i) => (
+          <Text
+            key={`${mark.label}-${i}`}
+            numberOfLines={1}
+            style={[styles.label, { left: mark.x, color: colors.textTertiary }]}
+          >
+            {mark.label}
+          </Text>
+        ))}
+      </View>
+
+      <View style={styles.body}>
+        {hasWeekdayCol && (
+          <View style={{ width: weekdayColWidth, marginRight: gap }}>
+            {Array.from({ length: 7 }, (_, r) => {
+              const dow = (weekStartsOn + r) % 7;
+              return (
+                <View
+                  key={r}
+                  style={{
+                    height: cellSize,
+                    marginBottom: r < 6 ? gap : 0,
+                    justifyContent: 'center',
+                  }}
+                >
+                  <Text numberOfLines={1} style={[styles.weekdayLabel, { color: colors.textTertiary }]}>
+                    {weekdayLabels[dow] ?? ''}
+                  </Text>
+                </View>
+              );
+            })}
+          </View>
+        )}
+
+        <View style={styles.grid}>
+          {columns.map((column, c) => (
+            <View key={c} style={{ marginRight: c < columns.length - 1 ? gap : 0 }}>
+              {column.map((cell, r) => {
+                const cellStyle = {
+                  width: cellSize,
+                  height: cellSize,
+                  borderRadius: cellRadius,
+                  marginBottom: r < 6 ? gap : 0,
+                };
+                if (!cell) {
+                  return <View key={r} style={cellStyle} />;
+                }
+                if (onPressDay) {
+                  const day: ActivityHeatmapDay = { date: cell.key, count: cell.count };
+                  return (
+                    <Pressable
+                      key={r}
+                      onPress={() => onPressDay(day)}
+                      accessibilityRole="button"
+                      accessibilityLabel={`${cell.key}: ${cell.count}`}
+                      style={[cellStyle, styles.cell, { backgroundColor: cell.color }]}
+                    />
+                  );
+                }
+                return (
+                  <View key={r} style={[cellStyle, styles.cell, { backgroundColor: cell.color }]} />
+                );
+              })}
+            </View>
+          ))}
+        </View>
+      </View>
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  monthRow: {
+    height: MONTH_ROW_HEIGHT,
+    position: 'relative',
+  },
+  label: {
+    position: 'absolute',
+    top: 0,
+    fontSize: LABEL_FONT_SIZE,
+  },
+  body: {
+    flexDirection: 'row',
+  },
+  grid: {
+    flexDirection: 'row',
+  },
+  cell: {
+    borderCurve: 'continuous',
+  },
+  weekdayLabel: {
+    fontSize: LABEL_FONT_SIZE,
+  },
+});
+
+export const ActivityHeatmap = memo(ActivityHeatmapComponent);
+ActivityHeatmap.displayName = 'ActivityHeatmap';

package/src/activity-heatmap/bucketByDay.ts

@@ -0,0 +1,49 @@
+import type { ActivityHeatmapDay } from './types';
+
+const DATE_KEY_RE = /^(\d{4})-(\d{2})-(\d{2})/;
+
+/**
+ * Normalize a date input to a `YYYY-MM-DD` key in UTC, or `null` if it can't be
+ * parsed. Strings already prefixed with an ISO date are sliced directly (no
+ * timezone shift); everything else is parsed and formatted in UTC.
+ */
+function toDateKey(value: string | Date): string | null {
+  if (value instanceof Date) {
+    const ts = value.getTime();
+    if (Number.isNaN(ts)) return null;
+    return formatUtcKey(ts);
+  }
+  if (DATE_KEY_RE.test(value)) return value.slice(0, 10);
+  const parsed = Date.parse(value);
+  if (Number.isNaN(parsed)) return null;
+  return formatUtcKey(parsed);
+}
+
+function formatUtcKey(ts: number): string {
+  const d = new Date(ts);
+  const year = d.getUTCFullYear();
+  const month = String(d.getUTCMonth() + 1).padStart(2, '0');
+  const day = String(d.getUTCDate()).padStart(2, '0');
+  return `${year}-${month}-${day}`;
+}
+
+/**
+ * Group arbitrary items by their `YYYY-MM-DD` day and count how many fall on
+ * each day. Returns entries sorted ascending by date — ready to hand to
+ * {@link ActivityHeatmap}'s `data` prop. Items whose date can't be parsed are
+ * skipped.
+ */
+export function bucketByDay<T>(
+  items: T[],
+  getDate: (item: T) => string | Date,
+): ActivityHeatmapDay[] {
+  const counts = new Map<string, number>();
+  for (const item of items) {
+    const key = toDateKey(getDate(item));
+    if (key === null) continue;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  return [...counts.entries()]
+    .map(([date, count]) => ({ date, count }))
+    .sort((a, b) => (a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+}

package/src/activity-heatmap/index.ts

@@ -0,0 +1,3 @@
+export { ActivityHeatmap } from './ActivityHeatmap';
+export { bucketByDay } from './bucketByDay';
+export type { ActivityHeatmapProps, ActivityHeatmapDay } from './types';

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',
+};