@oxyhq/bloom 0.24.0 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/bloom",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Bloom UI — Oxy ecosystem component library for React Native + Expo + Web",
   "main": "lib/commonjs/index.js",
   "module": "lib/module/index.js",
@@ -805,6 +805,22 @@
         "default": "./lib/commonjs/content-panel/index.js"
       }
     },
+    "./list": {
+      "react-native": "./src/list/index.tsx",
+      "browser": {
+        "types": "./lib/typescript/module/list/index.web.d.ts",
+        "import": "./lib/module/list/index.web.js",
+        "require": "./lib/commonjs/list/index.web.js"
+      },
+      "import": {
+        "types": "./lib/typescript/module/list/index.d.ts",
+        "default": "./lib/module/list/index.js"
+      },
+      "require": {
+        "types": "./lib/typescript/commonjs/list/index.d.ts",
+        "default": "./lib/commonjs/list/index.js"
+      }
+    },
     "./package.json": "./package.json"
   },
   "files": [
@@ -860,6 +876,8 @@
     "label",
     "kbd",
     "item",
+    "list",
+    "virtual-list",
     "ai"
   ],
   "repository": {
@@ -992,6 +1010,7 @@
     ]
   },
   "dependencies": {
+    "@tanstack/react-virtual": "^3.14.3",
     "nanoid": "^5.1.5",
     "react-native-css": "3.0.7",
     "react-remove-scroll-bar": "^2.3.8"

package/src/__tests__/LinkPreviewCard.test.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { Linking } from 'react-native';
+import { Image, Linking } from 'react-native';
 import { render, fireEvent } from '@testing-library/react-native';
 
 import { BloomThemeProvider } from '../theme/BloomThemeProvider';
@@ -57,4 +57,32 @@ describe('LinkPreviewCard', () => {
     expect(openURL).toHaveBeenCalledWith('https://example.com/open');
     openURL.mockRestore();
   });
+
+  it('gives the cover image a fixed height by default (coverFill omitted)', () => {
+    const { UNSAFE_getByType } = renderWithTheme(
+      <LinkPreviewCard
+        url="https://example.com"
+        title="Fixed"
+        image="https://cdn.example.com/og.png"
+      />,
+    );
+    const imageStyle = UNSAFE_getByType(Image).props.style as Record<string, unknown>;
+    expect(imageStyle.height).toBe(160);
+    expect(imageStyle.flex).toBeUndefined();
+  });
+
+  it('flexes the cover image (no fixed height) when coverFill is true', () => {
+    const { UNSAFE_getByType } = renderWithTheme(
+      <LinkPreviewCard
+        url="https://example.com"
+        title="Fill"
+        image="https://cdn.example.com/og.png"
+        coverFill
+        style={{ height: 180 }}
+      />,
+    );
+    const imageStyle = UNSAFE_getByType(Image).props.style as Record<string, unknown>;
+    expect(imageStyle.flex).toBe(1);
+    expect(imageStyle.height).toBeUndefined();
+  });
 });

package/src/__tests__/VirtualList.native.test.tsx

@@ -0,0 +1,67 @@
+import React from 'react';
+import { Text } from 'react-native';
+import { render } from '@testing-library/react-native';
+
+import { VirtualList, type VirtualListHandle } from '../list';
+
+interface Row {
+  id: string;
+  label: string;
+}
+
+describe('VirtualList (native)', () => {
+  it('renders the header and every row through FlatList', () => {
+    const data: Row[] = [
+      { id: 'a', label: 'Alpha' },
+      { id: 'b', label: 'Bravo' },
+      { id: 'c', label: 'Charlie' },
+    ];
+
+    const { getByText } = render(
+      <VirtualList<Row>
+        data={data}
+        keyExtractor={(item) => item.id}
+        renderItem={({ item }) => <Text>{item.label}</Text>}
+        ListHeaderComponent={<Text>Header row</Text>}
+      />,
+    );
+
+    expect(getByText('Header row')).toBeTruthy();
+    expect(getByText('Alpha')).toBeTruthy();
+    expect(getByText('Bravo')).toBeTruthy();
+    expect(getByText('Charlie')).toBeTruthy();
+  });
+
+  it('renders the empty slot (and no rows) when data is empty', () => {
+    const { getByText, queryByText } = render(
+      <VirtualList<Row>
+        data={[]}
+        keyExtractor={(item) => item.id}
+        renderItem={({ item }) => <Text>{item.label}</Text>}
+        ListEmptyComponent={<Text>Nothing here</Text>}
+      />,
+    );
+
+    expect(getByText('Nothing here')).toBeTruthy();
+    expect(queryByText('Alpha')).toBeNull();
+  });
+
+  it('exposes an imperative scroll handle via ref', () => {
+    const ref = React.createRef<VirtualListHandle>();
+
+    render(
+      <VirtualList<Row>
+        ref={ref}
+        data={[{ id: 'a', label: 'Alpha' }]}
+        keyExtractor={(item) => item.id}
+        renderItem={({ item }) => <Text>{item.label}</Text>}
+      />,
+    );
+
+    expect(typeof ref.current?.scrollToOffset).toBe('function');
+    expect(typeof ref.current?.scrollTo).toBe('function');
+    // The FlatList mock does not implement scrollToOffset; calling the handle
+    // must be a safe no-op (optional-chained internal ref), never a throw.
+    expect(() => ref.current?.scrollToOffset({ offset: 0 })).not.toThrow();
+  });
+});

package/src/__tests__/VirtualList.web.test.tsx

@@ -0,0 +1,127 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import React from 'react';
+import { act } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { getByText, queryByText } from '@testing-library/dom';
+import '@testing-library/jest-dom';
+
+import { VirtualList } from '../list/index.web';
+
+// `@tanstack/react-virtual` measures rows via ResizeObserver + getBoundingClientRect,
+// neither of which jsdom implements with a real layout engine. Stub both so the
+// window virtualizer computes a deterministic, non-empty range against jsdom's
+// default 768px-tall window — exactly the path that regressed in production
+// (rows present, wrapper sized, but `getVirtualItems()` came back empty).
+class ResizeObserverStub {
+  constructor(_cb: ResizeObserverCallback) {}
+  observe(): void {}
+  unobserve(): void {}
+  disconnect(): void {}
+}
+globalThis.ResizeObserver = ResizeObserverStub;
+
+const ROW_HEIGHT = 64;
+
+beforeAll(() => {
+  jest
+    .spyOn(Element.prototype, 'getBoundingClientRect')
+    .mockImplementation((): DOMRect => ({
+      x: 0,
+      y: 0,
+      top: 0,
+      left: 0,
+      right: 0,
+      bottom: ROW_HEIGHT,
+      width: 0,
+      height: ROW_HEIGHT,
+      toJSON: () => ({}),
+    }));
+});
+
+afterAll(() => {
+  jest.restoreAllMocks();
+});
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+let container: HTMLDivElement;
+let root: Root;
+
+function mount(ui: React.ReactElement): HTMLElement {
+  act(() => {
+    root.render(ui);
+  });
+  return container;
+}
+
+beforeEach(() => {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+interface Row {
+  id: string;
+  label: string;
+}
+
+describe('VirtualList (web)', () => {
+  it('mounts EVERY row of a short list in the first viewport (the empty-rows regression)', () => {
+    const data: Row[] = Array.from({ length: 5 }, (_, i) => ({
+      id: String(i),
+      label: `Row ${i}`,
+    }));
+
+    const c = mount(
+      <VirtualList<Row>
+        data={data}
+        keyExtractor={(item) => item.id}
+        renderItem={({ item }) => <span>{item.label}</span>}
+        ListHeaderComponent={<div>List header</div>}
+      />,
+    );
+
+    expect(getByText(c, 'List header')).toBeTruthy();
+    for (const row of data) {
+      expect(getByText(c, row.label)).toBeTruthy();
+    }
+  });
+
+  it('renders the header + empty slot (and no rows) when data is empty', () => {
+    const c = mount(
+      <VirtualList<Row>
+        data={[]}
+        keyExtractor={(item) => item.id}
+        renderItem={({ item }) => <span>{item.label}</span>}
+        ListHeaderComponent={<div>List header</div>}
+        ListEmptyComponent={<div>Nothing here</div>}
+      />,
+    );
+
+    expect(getByText(c, 'List header')).toBeTruthy();
+    expect(getByText(c, 'Nothing here')).toBeTruthy();
+    expect(queryByText(c, 'Row 0')).toBeNull();
+  });
+
+  it('supports a thunk slot for the header', () => {
+    const c = mount(
+      <VirtualList<Row>
+        data={[{ id: 'a', label: 'Only row' }]}
+        keyExtractor={(item) => item.id}
+        renderItem={({ item }) => <span>{item.label}</span>}
+        ListHeaderComponent={() => <div>Thunk header</div>}
+      />,
+    );
+
+    expect(getByText(c, 'Thunk header')).toBeTruthy();
+    expect(getByText(c, 'Only row')).toBeTruthy();
+  });
+});

package/src/link-preview/LinkPreviewCard.tsx

@@ -56,6 +56,7 @@ const LinkPreviewCardComponent: React.FC<LinkPreviewCardProps> = ({
   description,
   image,
   siteName,
+  coverFill = false,
   onPress,
   className,
   style,
@@ -107,7 +108,10 @@ const LinkPreviewCardComponent: React.FC<LinkPreviewCardProps> = ({
           resizeMode="cover"
           {...({ className: 'w-full' } as Record<string, string>)}
           style={{
-            height: COVER_IMAGE_HEIGHT,
+            // Fill-height mode: flex into the card's bounding height (supplied
+            // by the consumer via `style`), letting the text block stay a
+            // compact footer. Default mode: fixed intrinsic cover height.
+            ...(coverFill ? { flex: 1 } : { height: COVER_IMAGE_HEIGHT }),
             backgroundColor: colors.backgroundTertiary,
           }}
         />

package/src/link-preview/types.ts

@@ -23,6 +23,18 @@ export interface LinkPreviewCardProps {
   image?: string;
   /** Site / brand name shown above the title. Falls back to the URL hostname. */
   siteName?: string;
+  /**
+   * Fill-height mode for the cover image. Defaults to `false`.
+   *
+   * - `false` (default): the cover image keeps its fixed intrinsic height —
+   *   correct when the card sizes itself (e.g. a link rendered alone).
+   * - `true`: the cover image flexes (`flex: 1`, no fixed height) to fill
+   *   whatever vertical space the card is given, with the text block as a
+   *   compact intrinsic-height footer below it. The consumer supplies the
+   *   bounding height via `style` (e.g. `style={{ height: 180 }}`) so the card
+   *   fits a fixed-height row alongside other attachments without overflowing.
+   */
+  coverFill?: boolean;
   /** Press handler. When omitted, the card opens `url` via `Linking.openURL`. */
   onPress?: () => void;
   /** Extra NativeWind utilities merged onto the card surface. */

package/src/list/index.tsx

@@ -0,0 +1,121 @@
+/**
+ * `VirtualList` — the canonical cross-platform virtualized list for the Oxy
+ * ecosystem. Every app uses this ONE implementation for grouped/stacked row
+ * lists (who-to-follow, starter packs, connections, settings rows, …) so the
+ * virtualization behaviour is identical everywhere.
+ *
+ * NATIVE variant: a thin, correctly-typed wrapper over React Native `FlatList`.
+ * The consumer lists this component replaces are short and uniform, so the
+ * platform's own virtualization is the simplest robust choice — no
+ * `@legendapp/list`, no app-specific scroll bridge, nothing for a consumer to
+ * wire up. Bloom stays app-agnostic.
+ *
+ * WEB variant (`index.web.tsx`, selected via the `"browser"` export condition):
+ * a document-scroll window virtualizer built on `@tanstack/react-virtual`.
+ *
+ * This default file has NO platform-only imports, so consumer `tsc` and web
+ * bundlers resolve it cleanly (mirrors the `../scroll` / `../content-panel`
+ * fork pattern). The public API is shared via `./types`, so both forks expose
+ * an identical, generic, strongly-typed surface.
+ */
+import * as React from 'react';
+import { FlatList, type ListRenderItemInfo } from 'react-native';
+
+import type {
+  VirtualListHandle,
+  VirtualListProps,
+  VirtualListSlot,
+} from './types';
+
+export type {
+  VirtualListHandle,
+  VirtualListProps,
+  VirtualListRenderItem,
+  VirtualListRenderItemInfo,
+  VirtualListSlot,
+} from './types';
+
+function renderSlot(slot: VirtualListSlot): React.ReactElement | null {
+  if (!slot) return null;
+  return typeof slot === 'function' ? slot() : slot;
+}
+
+function VirtualListNativeInner<T>(
+  props: VirtualListProps<T>,
+  ref: React.ForwardedRef<VirtualListHandle>,
+) {
+  const {
+    data,
+    renderItem,
+    keyExtractor,
+    ListHeaderComponent,
+    ListEmptyComponent,
+    ListFooterComponent,
+    style,
+    contentContainerStyle,
+    onEndReached,
+    onEndReachedThreshold,
+    refreshing,
+    onRefresh,
+    initialNumToRender,
+    maxToRenderPerBatch,
+    windowSize,
+    removeClippedSubviews,
+    testID,
+  } = props;
+
+  const listRef = React.useRef<FlatList<T>>(null);
+
+  React.useImperativeHandle(
+    ref,
+    () => ({
+      scrollToOffset: (params) =>
+        listRef.current?.scrollToOffset({
+          offset: params?.offset ?? 0,
+          animated: params?.animated ?? true,
+        }),
+      scrollTo: (params) =>
+        listRef.current?.scrollToOffset({
+          offset: params?.y ?? 0,
+          animated: params?.animated ?? true,
+        }),
+    }),
+    [],
+  );
+
+  const renderFlatItem = React.useCallback(
+    (info: ListRenderItemInfo<T>) =>
+      renderItem ? renderItem({ item: info.item, index: info.index }) : null,
+    [renderItem],
+  );
+
+  return (
+    <FlatList<T>
+      ref={listRef}
+      data={data ?? undefined}
+      renderItem={renderFlatItem}
+      keyExtractor={keyExtractor}
+      ListHeaderComponent={renderSlot(ListHeaderComponent)}
+      ListEmptyComponent={renderSlot(ListEmptyComponent)}
+      ListFooterComponent={renderSlot(ListFooterComponent)}
+      style={style}
+      contentContainerStyle={contentContainerStyle}
+      onEndReached={onEndReached ? () => onEndReached() : undefined}
+      onEndReachedThreshold={onEndReachedThreshold}
+      refreshing={refreshing}
+      onRefresh={onRefresh}
+      initialNumToRender={initialNumToRender}
+      maxToRenderPerBatch={maxToRenderPerBatch}
+      windowSize={windowSize}
+      removeClippedSubviews={removeClippedSubviews}
+      testID={testID}
+    />
+  );
+}
+
+const VirtualList = React.forwardRef(VirtualListNativeInner) as <T>(
+  props: VirtualListProps<T> & { ref?: React.Ref<VirtualListHandle> },
+) => React.ReactElement;
+
+export { VirtualList };
+export default VirtualList;