@lotics/ui 1.22.0 → 1.24.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.22.0",
+  "version": "1.24.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -16,6 +16,8 @@
     },
     "./file_preview_types": "./src/file_preview_types.ts",
     "./file_gallery_modal": "./src/file_gallery_modal.tsx",
+    "./image_gallery": "./src/image_gallery.tsx",
+    "./file_thumbnail_grid": "./src/file_thumbnail_grid.tsx",
     "./pagination": "./src/pagination.tsx",
     "./bar_chart": "./src/bar_chart.tsx",
     "./line_chart": "./src/line_chart.tsx",
@@ -151,9 +153,8 @@
     "./grid/data_grid": "./src/grid/data_grid.tsx",
     "./grid/data_grid_context": "./src/grid/data_grid_context.ts",
     "./grid/search_highlight": "./src/grid/search_highlight.ts",
-    "./grid/sortable_header_cell": "./src/grid/sortable_header_cell.tsx",
-    "./grid/column_filter": "./src/grid/column_filter.tsx",
-    "./grid/data_grid_picker": "./src/grid/data_grid_picker.tsx"
+    "./column_filter": "./src/column_filter.tsx",
+    "./table_picker": "./src/table_picker.tsx"
   },
   "files": [
     "src"

package/src/{grid/column_filter.tsx → column_filter.tsx}

@@ -1,13 +1,13 @@
-import { StyleSheet, View } from "react-native";
-import { colors } from "../colors";
-import { Text } from "../text";
-import { Icon } from "../icon";
-import { PressableHighlight } from "../pressable_highlight";
-import { TextInputField } from "../text_input_field";
-import { NumberInput } from "../number_input";
-import { PickerMenu } from "../picker_menu";
-import { Popover, PopoverTrigger, PopoverContent } from "../popover";
-import type { PickerOption } from "../picker";
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { colors } from "./colors";
+import { TextInputField } from "./text_input_field";
+import { NumberInput } from "./number_input";
+import { PickerMenu } from "./picker_menu";
+import { PillButton } from "./pill_button";
+import { Popover, PopoverTrigger, PopoverContent } from "./popover";
+import type { PickerOption } from "./picker";
 
 /** A column the picker can filter on. `type` selects the control + operators. */
 export interface FilterableColumn {
@@ -72,18 +72,39 @@ export function isColumnFilterActive(value: ColumnFilterValue | undefined): bool
   return value.selected.length > 0;
 }
 
+/** A short human summary of an active value, for the pill label ("Vàng, Đỏ", "≥ 10"). */
+export function columnFilterSummary(
+  column: FilterableColumn,
+  value: ColumnFilterValue | undefined,
+): string {
+  if (!value) return "";
+  if (value.kind === "text") return value.query.trim();
+  if (value.kind === "number") {
+    const { min, max } = value;
+    if (min != null && max != null) return `${min}–${max}`;
+    if (min != null) return `≥ ${min}`;
+    if (max != null) return `≤ ${max}`;
+    return "";
+  }
+  return value.selected
+    .map((k) => column.options?.find((o) => o.value === k)?.label ?? k)
+    .join(", ");
+}
+
 export interface ColumnFilterProps {
   column: FilterableColumn;
   value: ColumnFilterValue | undefined;
   onChange: (value: ColumnFilterValue | undefined) => void;
-  /** Accessible name for the clear control. Pass a translated string. Default "Clear". */
+  /** Accessible name for the clear (X) control. Pass a translated string. Default "Clear". */
   clearLabel?: string;
 }
 
 /**
- * A reusable per-column filter: a pill that opens a type-aware editor (text
- * contains / number range / multi-select). Controlled — the consumer holds the
- * `ColumnFilterValue` and maps it to query conditions via
+ * A toolbar-style filter pill: the same `PillButton` the table toolbar uses, so
+ * a picker's filters read identically. Inactive → "Label ⌄"; active →
+ * "Label: summary" with an X to clear. Pressing the pill opens a type-aware
+ * editor (text contains / number range / multi-select). Controlled — the
+ * consumer holds the `ColumnFilterValue` and maps it to query conditions via
  * `columnFilterToConditions`. Pure UI; no data layer.
  */
 export function ColumnFilter(props: ColumnFilterProps) {
@@ -93,17 +114,15 @@ export function ColumnFilter(props: ColumnFilterProps) {
   return (
     <Popover side="bottom" align="start">
       <PopoverTrigger>
-        <PressableHighlight
-          accessibilityRole="button"
-          accessibilityLabel={column.label}
-          style={[styles.pill, active && styles.pillActive]}
+        <PillButton
+          onDismiss={active ? () => onChange(undefined) : undefined}
+          dismissTooltip={clearLabel}
         >
-          <Icon name="list-filter" size={13} color={active ? colors.zinc["950"] : colors.zinc["500"]} />
           <Text size="sm" weight="medium" color={active ? "zinc-900" : "zinc-700"} numberOfLines={1}>
-            {column.label}
+            {active ? `${column.label}: ${columnFilterSummary(column, value)}` : column.label}
           </Text>
-          <Icon name="chevron-down" size={14} color={colors.zinc["400"]} />
-        </PressableHighlight>
+          {!active ? <Icon name="chevron-down" size={14} color={colors.zinc["400"]} /> : null}
+        </PillButton>
       </PopoverTrigger>
       <PopoverContent style={styles.content}>
         {column.type === "text" ? (
@@ -142,40 +161,12 @@ export function ColumnFilter(props: ColumnFilterProps) {
             onValueChange={(selected) => onChange({ kind: "select", selected })}
           />
         )}
-        {active ? (
-          <PressableHighlight
-            accessibilityRole="button"
-            accessibilityLabel={clearLabel}
-            onPress={() => onChange(undefined)}
-            style={styles.clear}
-          >
-            <Icon name="x" size={14} color={colors.zinc["500"]} />
-            <Text size="sm" color="zinc-500">
-              {clearLabel}
-            </Text>
-          </PressableHighlight>
-        ) : null}
       </PopoverContent>
     </Popover>
   );
 }
 
 const styles = StyleSheet.create({
-  pill: {
-    flexDirection: "row",
-    alignItems: "center",
-    gap: 5,
-    height: 32,
-    paddingHorizontal: 10,
-    borderRadius: 8,
-    borderWidth: 1,
-    borderColor: colors.border,
-    backgroundColor: colors.background,
-  },
-  pillActive: {
-    borderColor: colors.zinc["400"],
-    backgroundColor: colors.zinc["100"],
-  },
   content: {
     minWidth: 240,
     gap: 8,
@@ -185,11 +176,4 @@ const styles = StyleSheet.create({
     alignItems: "center",
     gap: 8,
   },
-  clear: {
-    flexDirection: "row",
-    alignItems: "center",
-    gap: 6,
-    paddingVertical: 6,
-    paddingHorizontal: 4,
-  },
 });

package/src/file_thumbnail_grid.tsx

@@ -0,0 +1,165 @@
+// Pure, reusable thumbnail-grid layout + a file-specific specialization.
+//
+// `ThumbnailGrid<T>` is the layout engine (three mutually-exclusive modes:
+// compact / fixed-columns / auto-columns, with `maxVisible` overflow). It is
+// item-agnostic — pass `renderItem`. `FileThumbnailGrid` is the common case:
+// a grid of `DisplayFile`s rendered with `FileThumbnail` (any file type —
+// image/video/audio/doc — via FileThumbnail's own type handling).
+//
+// The Lotics-coupled file grid (`@lotics/ui-internal/file_grid`, which mixes in
+// upload-progress thumbnails) composes `ThumbnailGrid` with its own renderItem,
+// so the layout lives in exactly one place.
+import React, { useState } from "react";
+import { View, StyleSheet, type ViewStyle } from "react-native";
+import { Text } from "./text";
+import { FileThumbnail, type DisplayFile, THUMBNAIL_SIZE } from "./file_thumbnail";
+
+export interface ThumbnailGridProps<T> {
+  items: T[];
+  keyExtractor: (item: T) => string;
+  /** Render one item. `size` is passed in compact mode (fixed px); omitted in
+   *  column modes, where the item fills its flex cell. */
+  renderItem: (item: T, size?: number) => React.ReactNode;
+  /** Fixed pixel size per item → flat horizontal wrap. Takes precedence. */
+  itemSize?: number;
+  /** Fixed column count → items fill 1/N of the row width. */
+  columns?: number;
+  /** Minimum item width for auto column count when neither itemSize nor columns
+   *  is set. Default 96. */
+  minItemWidth?: number;
+  /** Gap between items. Default 8. */
+  gap?: number;
+  /** Max items shown before a "+N" overflow indicator. */
+  maxVisible?: number;
+  /** Alignment of a partial last row. Default "start". */
+  partialRowAlign?: "start" | "end";
+  style?: ViewStyle;
+  /** Disable press/click interactions (sets pointerEvents none). */
+  disablePress?: boolean;
+  /** Rendered inside the container after the grid (e.g. a retry-all button). */
+  footer?: React.ReactNode;
+}
+
+export function ThumbnailGrid<T>(props: ThumbnailGridProps<T>) {
+  const {
+    items,
+    keyExtractor,
+    renderItem,
+    itemSize,
+    columns,
+    minItemWidth = THUMBNAIL_SIZE,
+    gap = 8,
+    maxVisible,
+    partialRowAlign = "start",
+    style,
+    disablePress,
+    footer,
+  } = props;
+
+  const [containerWidth, setContainerWidth] = useState(0);
+
+  const isCompact = itemSize !== undefined;
+  const dynamicColumns =
+    !isCompact && columns === undefined && containerWidth > 0
+      ? Math.max(1, Math.floor((containerWidth + gap) / (minItemWidth + gap)))
+      : undefined;
+  const effectiveColumns = columns ?? dynamicColumns;
+
+  const visible = maxVisible ? items.slice(0, maxVisible) : items;
+  const overflow = maxVisible ? Math.max(0, items.length - maxVisible) : 0;
+  const canRender = isCompact || columns !== undefined || containerWidth > 0;
+
+  if (items.length === 0) return null;
+
+  const renderRows = (rowItems: T[], cols: number) => {
+    const rows: T[][] = [];
+    for (let i = 0; i < rowItems.length; i += cols) rows.push(rowItems.slice(i, i + cols));
+    return rows.map((row, rowIndex) => {
+      const spacers =
+        row.length < cols
+          ? Array.from({ length: cols - row.length }, (_, i) => (
+              <View key={`spacer-${i}`} style={styles.flexItem} />
+            ))
+          : null;
+      return (
+        <View key={rowIndex} style={[styles.row, { gap }]}>
+          {partialRowAlign === "end" && spacers}
+          {row.map((item) => (
+            <View key={keyExtractor(item)} style={styles.flexItem}>
+              {renderItem(item)}
+            </View>
+          ))}
+          {partialRowAlign === "start" && spacers}
+        </View>
+      );
+    });
+  };
+
+  return (
+    <View
+      style={[isCompact && styles.compactContainer, { gap }, style]}
+      pointerEvents={disablePress ? "none" : "auto"}
+      onLayout={(e) => setContainerWidth(e.nativeEvent.layout.width)}
+    >
+      {canRender &&
+        (isCompact
+          ? visible.map((item) => (
+              <React.Fragment key={keyExtractor(item)}>{renderItem(item, itemSize)}</React.Fragment>
+            ))
+          : effectiveColumns !== undefined
+            ? renderRows(visible, effectiveColumns)
+            : null)}
+
+      {overflow > 0 && (
+        <Text size="sm" color="muted" userSelect="none">
+          +{overflow}
+        </Text>
+      )}
+
+      {footer}
+    </View>
+  );
+}
+
+export interface FileThumbnailGridProps {
+  files: DisplayFile[];
+  itemSize?: number;
+  columns?: number;
+  minItemWidth?: number;
+  gap?: number;
+  maxVisible?: number;
+  partialRowAlign?: "start" | "end";
+  style?: ViewStyle;
+  disablePress?: boolean;
+  /** Selected file IDs — renders a selection overlay on those thumbnails. */
+  selectedIds?: ReadonlySet<string>;
+  onFilePress?: (file: DisplayFile) => void;
+  onRemove?: (id: string) => void;
+}
+
+export function FileThumbnailGrid(props: FileThumbnailGridProps) {
+  const { files, selectedIds, onFilePress, onRemove, disablePress, ...layout } = props;
+  return (
+    <ThumbnailGrid
+      {...layout}
+      items={files}
+      keyExtractor={(f) => f.id}
+      disablePress={disablePress}
+      renderItem={(file, size) => (
+        <FileThumbnail
+          file={file}
+          size={size}
+          onPress={disablePress || !onFilePress ? undefined : () => onFilePress(file)}
+          onRemove={onRemove ? () => onRemove(file.id) : undefined}
+          selected={selectedIds?.has(file.id)}
+        />
+      )}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  compactContainer: { flexDirection: "row", flexWrap: "wrap", userSelect: "none" },
+  row: { flexDirection: "row" },
+  flexItem: { flex: 1 },
+});

package/src/image_gallery.tsx

@@ -0,0 +1,123 @@
+// Ecommerce-style image gallery: a large main image plus a thumbnail grid.
+// Click a thumbnail to swap the main image; click the main image to zoom it
+// full-screen via FileGalleryModal. Source-agnostic — takes DisplayFile[], so
+// any caller (record photos, uploads, chat attachments) can use it.
+//
+// Width is measured with onLayout (like FileThumbnailGrid) and the columns are
+// sized from it, so the gallery adapts to the available space instead of
+// relying on percentage/flex-basis resolution (which collapses inside an
+// auto-width parent).
+import { useState } from "react";
+import { View, Image, Pressable } from "react-native";
+import { Text } from "./text";
+import { colors } from "./colors";
+import { ActivityIndicator } from "./activity_indicator";
+import { FileThumbnail, type DisplayFile } from "./file_thumbnail";
+import { FileGalleryModal } from "./file_gallery_modal";
+
+const GAP = 12;
+
+export interface ImageGalleryProps {
+  images: DisplayFile[];
+  loading?: boolean;
+  /** Shown when there are no images and not loading. Pass a translated string. */
+  emptyText?: string;
+  /** Optional max width. Omit to fill the container. */
+  maxWidth?: number;
+  /** Hint shown in the full-screen zoom modal. Pass a translated string. */
+  captionHint?: string;
+  /** "bottom" stacks thumbnails under the main image; "right" puts the main
+   *  image (~60% of the width) and the thumbnail grid side by side. */
+  thumbnailPosition?: "bottom" | "right";
+  /** Aspect ratio (width / height) of the main image box. Default 4/3. A
+   *  smaller value (e.g. 1) makes a taller, larger preview. */
+  mainAspectRatio?: number;
+  /** Main image's fraction of the width in "right" mode (0–1). Default 0.6. */
+  mainFraction?: number;
+}
+
+export function ImageGallery({
+  images,
+  loading = false,
+  emptyText = "No images.",
+  maxWidth,
+  captionHint = "ESC to close · ←/→ to navigate",
+  thumbnailPosition = "bottom",
+  mainAspectRatio = 4 / 3,
+  mainFraction = 0.6,
+}: ImageGalleryProps) {
+  const [selected, setSelected] = useState(0);
+  const [zoomIdx, setZoomIdx] = useState<number | null>(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+
+  if (loading) return <ActivityIndicator />;
+  if (images.length === 0) return <Text size="sm" color="muted">{emptyText}</Text>;
+
+  const idx = Math.min(selected, images.length - 1);
+  const main = images[idx];
+  const right = thumbnailPosition === "right";
+  const width = maxWidth ? Math.min(containerWidth, maxWidth) : containerWidth;
+
+  const mainImage = (
+    <Pressable
+      onPress={() => setZoomIdx(idx)}
+      accessibilityRole="button"
+      accessibilityLabel="Zoom image"
+      style={{
+        width: "100%",
+        aspectRatio: mainAspectRatio,
+        borderRadius: 8,
+        borderWidth: 1,
+        borderColor: colors.border,
+        backgroundColor: colors.zinc["100"],
+        overflow: "hidden",
+        cursor: "pointer",
+      }}
+    >
+      <Image source={{ uri: main.url }} resizeMode="contain" style={{ width: "100%", height: "100%" }} />
+    </Pressable>
+  );
+
+  const thumbnails = images.length > 1 ? (
+    <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 6 }}>
+      {images.map((img, i) => (
+        // Border radius = FileThumbnail's own radius (8) + the 2px border, so
+        // the active highlight is concentric with the thumbnail's corners.
+        <View
+          key={img.id}
+          style={{
+            borderRadius: 10,
+            borderWidth: 2,
+            borderColor: i === idx ? colors.zinc["900"] : colors.zinc["200"],
+          }}
+        >
+          <FileThumbnail file={img} size={56} onPress={() => setSelected(i)} />
+        </View>
+      ))}
+    </View>
+  ) : null;
+
+  return (
+    <View onLayout={(e) => setContainerWidth(e.nativeEvent.layout.width)}>
+      {width > 0 &&
+        (right && thumbnails ? (
+          <View style={{ flexDirection: "row", gap: GAP }}>
+            <View style={{ width: (width - GAP) * mainFraction }}>{mainImage}</View>
+            <View style={{ width: (width - GAP) * (1 - mainFraction) }}>{thumbnails}</View>
+          </View>
+        ) : (
+          <View style={{ gap: 8, width }}>
+            {mainImage}
+            {thumbnails}
+          </View>
+        ))}
+
+      <FileGalleryModal
+        files={images}
+        activeIndex={zoomIdx}
+        onIndexChange={setZoomIdx}
+        captionHint={captionHint}
+      />
+    </View>
+  );
+}

package/src/table.tsx

@@ -16,7 +16,7 @@ const stickyHeader = [0];
 const CHEVRON_W = 44;
 
 export function Table<TRow extends Record<string, unknown>>(props: TableProps<TRow>) {
-  const { columns, rows, rowKey, rowStyle, sort, onSortChange, renderDetail, expandedKeys, onToggleRow } = props;
+  const { columns, rows, rowKey, rowStyle, sort, onSortChange, renderDetail, expandedKeys, onToggleRow, onRowPress } = props;
   const [internal, setInternal] = useState<Set<string>>(() => new Set());
   const expanded = expandedKeys ?? internal;
   const expandable = !!renderDetail;
@@ -89,6 +89,14 @@ export function Table<TRow extends Record<string, unknown>>(props: TableProps<TR
                   <Icon name={isOpen ? "chevron-up" : "chevron-down"} size={18} color={colors.zinc[400]} />
                 </View>
               </Pressable>
+            ) : onRowPress ? (
+              <Pressable
+                accessibilityRole="button"
+                onPress={() => onRowPress(row)}
+                style={({ pressed }) => [styles.bodyRow, pressed ? styles.rowPressed : null, extra]}
+              >
+                {cells}
+              </Pressable>
             ) : (
               <View style={[styles.bodyRow, extra]}>{cells}</View>
             )}

package/src/table.web.tsx

@@ -19,11 +19,14 @@ function colWidth<TRow extends Record<string, unknown>>(col: Column<TRow>): CSSP
 }
 
 export function Table<TRow extends Record<string, unknown>>(props: TableProps<TRow>) {
-  const { columns, rows, rowKey, rowStyle, sort, onSortChange, renderDetail, expandedKeys, onToggleRow } = props;
+  const { columns, rows, rowKey, rowStyle, sort, onSortChange, renderDetail, expandedKeys, onToggleRow, onRowPress } = props;
   const [internal, setInternal] = useState<Set<string>>(() => new Set());
   const [hoverKey, setHoverKey] = useState<string | null>(null);
   const expanded = expandedKeys ?? internal;
   const expandable = !!renderDetail;
+  // A row reacts to clicks for one of two reasons: expansion (renderDetail) or
+  // selection (onRowPress). Expansion wins if both are set.
+  const pressable = expandable || !!onRowPress;
 
   const toggle = (key: string, row: TRow) => {
     onToggleRow?.(key, row);
@@ -97,8 +100,8 @@ export function Table<TRow extends Record<string, unknown>>(props: TableProps<TR
         const extra = (rowStyle?.(row) as CSSProperties | undefined) ?? undefined;
         const rowStyleFinal: CSSProperties = {
           ...bodyRowStyle,
-          cursor: expandable ? "pointer" : "default",
-          background: hoverKey === key && expandable ? colors.zinc[50] : colors.white,
+          cursor: pressable ? "pointer" : "default",
+          background: hoverKey === key && pressable ? colors.zinc[50] : colors.white,
           ...extra,
         };
         return (
@@ -106,18 +109,19 @@ export function Table<TRow extends Record<string, unknown>>(props: TableProps<TR
             <div
               role="row"
               onClick={
-                expandable
+                pressable
                   ? (e: React.MouseEvent) => {
-                      // Whole-row click expands, EXCEPT clicks inside an interactive cell
-                      // (pickers/buttons) — they keep their own behaviour. The disclosure
-                      // chevron is the keyboard/AT affordance.
+                      // Whole-row click acts (expand or select), EXCEPT clicks inside an
+                      // interactive cell (pickers/buttons) — they keep their own behaviour.
+                      // The disclosure chevron is the keyboard/AT affordance for expansion.
                       if ((e.target as HTMLElement).closest("[data-interactive]")) return;
-                      toggle(key, row);
+                      if (expandable) toggle(key, row);
+                      else onRowPress?.(row);
                     }
                   : undefined
               }
-              onMouseEnter={expandable ? () => setHoverKey(key) : undefined}
-              onMouseLeave={expandable ? () => setHoverKey((k) => (k === key ? null : k)) : undefined}
+              onMouseEnter={pressable ? () => setHoverKey(key) : undefined}
+              onMouseLeave={pressable ? () => setHoverKey((k) => (k === key ? null : k)) : undefined}
               style={rowStyleFinal}
             >
               {columns.map((col) => (
@@ -165,7 +169,10 @@ export function Table<TRow extends Record<string, unknown>>(props: TableProps<TR
   );
 }
 
-const containerStyle: CSSProperties = { width: "100%", overflow: "auto" };
+// `maxHeight: 100%` is a no-op in a content-sized parent (a card grows to its
+// rows) but caps the table to a bounded parent (a modal's flex region), so
+// `overflow: auto` then scrolls and the sticky header engages.
+const containerStyle: CSSProperties = { width: "100%", maxHeight: "100%", overflow: "auto" };
 const headerRowStyle: CSSProperties = {
   display: "flex",
   position: "sticky",

package/src/{grid/data_grid_picker.tsx → table_picker.tsx}

@@ -1,50 +1,46 @@
 import { useCallback, useMemo } from "react";
 import { StyleSheet, View } from "react-native";
-import { colors } from "../colors";
-import { Text } from "../text";
-import { SearchInput } from "../search_input";
-import { ActivityIndicator } from "../activity_indicator";
-import { Dialog } from "../dialog";
-import { PressableHighlight } from "../pressable_highlight";
-import { DataGrid, type DataGridColumn, type DataGridGroup } from "./data_grid";
-import { SortableHeaderCell, type SortOrder } from "./sortable_header_cell";
-import {
-  ColumnFilter,
-  type FilterableColumn,
-  type ColumnFilterValue,
-} from "./column_filter";
+import { colors } from "./colors";
+import { Text } from "./text";
+import { SearchInput } from "./search_input";
+import { ActivityIndicator } from "./activity_indicator";
+import { Dialog } from "./dialog";
+import { Table } from "@lotics/ui/table";
+import type { Column, TableSort } from "@lotics/ui/table_types";
+import { Pagination } from "./pagination";
+import { ColumnFilter, type FilterableColumn, type ColumnFilterValue } from "./column_filter";
 
-/** A grid column the picker displays. Sorting/filtering are opt-in per column. */
-export interface PickerColumn<TRow> {
+/** A grid column the picker displays. Sorting is opt-in per column. */
+export interface PickerColumn<TRow extends Record<string, unknown>> {
   key: string;
   label: string;
-  /** Fixed pixel width. Omit to let the grid size it. */
+  /** Fixed pixel width. Omit to flex. */
   width?: number;
+  align?: "left" | "right";
   /** Show a sortable header for this column. Requires `sort`/`onSortChange`. */
   sortable?: boolean;
-  /**
-   * Cell content for this column. Default: a single-line text of the row's
-   * value at `key` (objects render their `label`/`display`/`name`).
-   */
+  /** Cell content. Default: the row's value at `key` rendered as text. */
   renderCell?: (row: TRow) => React.ReactNode;
 }
 
 /** Single-column sort state — the picker sorts by one column at a time. */
-export interface DataGridPickerSort {
+export interface TablePickerSort {
   key: string;
-  order: SortOrder;
+  order: "asc" | "desc";
 }
 
-export interface DataGridPickerProps<TRow extends Record<string, unknown>> {
+export interface TablePickerProps<TRow extends Record<string, unknown>> {
   open: boolean;
   onOpenChange: (open: boolean) => void;
   /** Heading shown above the search box. */
   title?: string;
 
   columns: PickerColumn<TRow>[];
+  /** Rows of the current page (the consumer paginates). */
   rows: TRow[];
-  /** Stable identity for a row — the value returned by selection. */
-  rowIdGetter: (row: TRow) => string;
+  /** The field holding each row's stable id — returned by selection and used to
+   *  highlight the picked row (e.g. `"__source_record_id"`). */
+  rowKey: keyof TRow & string;
 
   /** Currently selected row id, or null. Highlights the matching row. */
   value: string | null;
@@ -59,16 +55,15 @@ export interface DataGridPickerProps<TRow extends Record<string, unknown>> {
   searchPlaceholder?: string;
 
   /**
-   * Controlled single-column sort. Omit `onSortChange` to disable sorting
-   * entirely (headers render static). Toggling a column cycles asc → desc → off.
+   * Controlled single-column sort. Omit `onSortChange` to disable sorting.
+   * Toggling a column cycles asc → desc → off.
    */
-  sort?: DataGridPickerSort | null;
-  onSortChange?: (sort: DataGridPickerSort | null) => void;
+  sort?: TablePickerSort | null;
+  onSortChange?: (sort: TablePickerSort | null) => void;
 
   /**
-   * Per-column filters shown as a pill row. The consumer holds `filterValues`
-   * (keyed by column key) and maps them to query conditions via
-   * `columnFilterToConditions`.
+   * Per-column filter pills. The consumer holds `filterValues` (keyed by column
+   * key) and maps them to query conditions via `columnFilterToConditions`.
    */
   filters?: FilterableColumn[];
   filterValues?: Record<string, ColumnFilterValue>;
@@ -76,15 +71,18 @@ export interface DataGridPickerProps<TRow extends Record<string, unknown>> {
   /** Accessible name for the per-filter clear control. Pass a translated string. */
   clearLabel?: string;
 
-  /** Called when the grid scrolls near the end — load the next page. */
-  onEndReached?: () => void;
+  /** Pagination (page-model — the consumer owns the page cursor). */
+  page: number;
+  pageSize: number;
+  /** Total rows across all pages, when known — drives "Page 1 of N". */
+  total?: number;
+  hasMore: boolean;
+  onPageChange: (page: number) => void;
 
-  /** A request is in flight. Shows a spinner (overlay when rows exist). */
+  /** A request is in flight. */
   loading?: boolean;
   /** Message when there are no rows and nothing is loading. */
   emptyLabel?: string;
-
-  rowHeight?: number;
   testID?: string;
 }
 
@@ -103,22 +101,20 @@ function defaultCellText(value: unknown): string {
   return "";
 }
 
-const DEFAULT_ROW_HEIGHT = 48;
-
 /**
- * A data-agnostic record-style picker: a modal holding a virtualized grid the
- * user can browse, search, sort, and filter, then pick one row. It knows nothing
- * about records/tables/fields — the consumer supplies `columns` + `rows` and
- * owns the search/sort/filter/pagination state (so the same component drives a
- * server-side query, an in-memory list, or any other source). Compose it with a
- * domain hook (e.g. an app's `useRecordSearch`) to build a record picker, or
- * with any other row source for a different purpose.
+ * A data-agnostic record-style picker: a modal holding a table the user can
+ * browse (numbered pages), search, sort, and filter, then pick one row. It knows
+ * nothing about records/tables/fields — the consumer supplies `columns` + `rows`
+ * (one page) and owns the search/sort/filter/page state (so the same component
+ * drives a server query, an in-memory list, or any other source). Compose it
+ * with a domain hook (e.g. an app's `usePaginatedQuery`) to build a record
+ * picker, or with any other row source for a different purpose.
  *
- * Single-select: clicking any cell in a row picks that row's id. The selected
- * row is highlighted; `closeOnSelect` (default) dismisses the modal on pick.
+ * Single-select: clicking a row picks its id; the selected row is highlighted;
+ * `closeOnSelect` (default) dismisses the modal on pick.
  */
-export function DataGridPicker<TRow extends Record<string, unknown>>(
-  props: DataGridPickerProps<TRow>,
+export function TablePicker<TRow extends Record<string, unknown>>(
+  props: TablePickerProps<TRow>,
 ) {
   const {
     open,
@@ -126,7 +122,7 @@ export function DataGridPicker<TRow extends Record<string, unknown>>(
     title,
     columns,
     rows,
-    rowIdGetter,
+    rowKey,
     value,
     onValueChange,
     closeOnSelect = true,
@@ -139,21 +135,25 @@ export function DataGridPicker<TRow extends Record<string, unknown>>(
     filterValues,
     onFilterChange,
     clearLabel,
-    onEndReached,
+    page,
+    pageSize,
+    total,
+    hasMore,
+    onPageChange,
     loading = false,
     emptyLabel,
-    rowHeight = DEFAULT_ROW_HEIGHT,
     testID,
   } = props;
 
   const handleSelect = useCallback(
-    (id: string) => {
-      onValueChange(id);
+    (row: TRow) => {
+      onValueChange(String(row[rowKey]));
       if (closeOnSelect) onOpenChange(false);
     },
-    [onValueChange, closeOnSelect, onOpenChange],
+    [onValueChange, rowKey, closeOnSelect, onOpenChange],
   );
 
+  // Toggle this column's sort: asc → desc → off. The consumer holds the state.
   const toggleSort = useCallback(
     (key: string) => {
       if (!onSortChange) return;
@@ -164,51 +164,35 @@ export function DataGridPicker<TRow extends Record<string, unknown>>(
     [sort, onSortChange],
   );
 
-  const gridColumns = useMemo<DataGridColumn<TRow>[]>(
+  const tableColumns = useMemo<Column<TRow>[]>(
     () =>
       columns.map((col) => ({
         key: col.key,
-        name: col.label,
+        label: col.label,
         width: col.width,
-        renderHeaderCell:
-          col.sortable && onSortChange
-            ? () => (
-                <SortableHeaderCell
-                  label={col.label}
-                  order={sort?.key === col.key ? sort.order : null}
-                  onToggle={() => toggleSort(col.key)}
-                  testID={`picker-sort-${col.key}`}
-                />
-              )
-            : undefined,
-        renderCell: ({ row }: { row: TRow }) => (
-          <PressableHighlight
-            accessibilityRole="button"
-            onPress={() => handleSelect(rowIdGetter(row))}
-            style={styles.cell}
-          >
-            {col.renderCell ? (
-              col.renderCell(row)
-            ) : (
-              <Text size="sm" color="zinc-900" numberOfLines={1}>
-                {defaultCellText(row[col.key])}
-              </Text>
-            )}
-          </PressableHighlight>
-        ),
+        align: col.align,
+        sortable: col.sortable && !!onSortChange,
+        renderCell: ({ row }: { row: TRow }) =>
+          col.renderCell ? (
+            col.renderCell(row)
+          ) : (
+            <Text size="sm" color="zinc-900" numberOfLines={1}>
+              {defaultCellText(row[col.key])}
+            </Text>
+          ),
       })),
-    [columns, sort, onSortChange, toggleSort, handleSelect, rowIdGetter],
+    [columns, onSortChange],
   );
 
-  const groups = useMemo<DataGridGroup<TRow>[]>(
-    () => (rows.length > 0 ? [{ value: null, columnKey: "", rows }] : []),
-    [rows],
+  const tableSort = useMemo<TableSort<TRow> | null>(
+    () => (sort ? { key: sort.key, dir: sort.order } : null),
+    [sort],
   );
 
-  const rowColorGetter = useCallback(
+  const rowStyle = useCallback(
     (row: TRow) =>
-      value != null && rowIdGetter(row) === value ? colors.blue["50"] : undefined,
-    [value, rowIdGetter],
+      value != null && String(row[rowKey]) === value ? { backgroundColor: colors.blue["50"] } : undefined,
+    [value, rowKey],
   );
 
   return (
@@ -221,7 +205,7 @@ export function DataGridPicker<TRow extends Record<string, unknown>>(
         ) : null}
 
         <SearchInput
-          testID="data-grid-picker-search"
+          testID="table-picker-search"
           value={searchQuery}
           onChangeText={onSearchChange}
           placeholder={searchPlaceholder}
@@ -243,16 +227,15 @@ export function DataGridPicker<TRow extends Record<string, unknown>>(
         ) : null}
 
         <View style={styles.gridArea}>
-          {groups.length > 0 ? (
-            <DataGrid<TRow>
-              rowIdGetter={rowIdGetter}
-              rowHeight={rowHeight}
-              groups={groups}
-              columns={gridColumns}
-              rowColorGetter={rowColorGetter}
-              frozenColumnCount={0}
-              enableReordering={false}
-              onEndReached={onEndReached}
+          {rows.length > 0 ? (
+            <Table<TRow>
+              columns={tableColumns}
+              rows={rows}
+              rowKey={rowKey}
+              sort={tableSort}
+              onSortChange={onSortChange ? (key) => toggleSort(key as string) : undefined}
+              onRowPress={handleSelect}
+              rowStyle={rowStyle}
             />
           ) : (
             <View style={styles.center}>
@@ -265,12 +248,17 @@ export function DataGridPicker<TRow extends Record<string, unknown>>(
               )}
             </View>
           )}
-          {loading && groups.length > 0 ? (
-            <View style={styles.loadingOverlay} pointerEvents="none">
-              <ActivityIndicator />
-            </View>
-          ) : null}
         </View>
+
+        <Pagination
+          page={page}
+          pageSize={pageSize}
+          rowCount={rows.length}
+          hasMore={hasMore}
+          total={total}
+          loading={loading}
+          onPageChange={onPageChange}
+        />
       </View>
     </Dialog>
   );
@@ -297,26 +285,16 @@ const styles = StyleSheet.create({
   },
   gridArea: {
     flex: 1,
+    minHeight: 0,
     borderWidth: 1,
     borderColor: colors.border,
     borderRadius: 12,
     overflow: "hidden",
   },
-  cell: {
-    flex: 1,
-    height: "100%",
-    justifyContent: "center",
-    paddingHorizontal: 8,
-  },
   center: {
     flex: 1,
     alignItems: "center",
     justifyContent: "center",
     padding: 24,
   },
-  loadingOverlay: {
-    position: "absolute",
-    top: 8,
-    right: 8,
-  },
 });

package/src/table_types.ts

@@ -35,6 +35,11 @@ export interface TableProps<TRow extends Record<string, unknown>> {
    *  parent owns the actual sorting of `rows` — this only drives the indicator. */
   sort?: TableSort<TRow> | null;
   onSortChange?: (key: keyof TRow) => void;
+  /** Click-to-select: pressing a row (except `interactive` cells) calls this —
+   *  e.g. a picker that returns the chosen row. Mutually exclusive with
+   *  `renderDetail` (a row either expands or selects); `renderDetail` wins if
+   *  both are set. Pair with `rowStyle` to highlight the selected row. */
+  onRowPress?: (row: TRow) => void;
   /** Render an inline detail panel, full-width below the row. When set, the
    *  whole row (except `interactive` cells) is click-to-expand. */
   renderDetail?: (row: TRow) => ReactNode;

package/src/grid/sortable_header_cell.tsx

@@ -1,58 +0,0 @@
-import { StyleSheet } from "react-native";
-import { colors } from "../colors";
-import { Text } from "../text";
-import { Icon } from "../icon";
-import { PressableHighlight } from "../pressable_highlight";
-
-export type SortOrder = "asc" | "desc";
-
-export interface SortableHeaderCellProps {
-  label: string;
-  /** Current sort order for THIS column, or null when another (or no) column
-   *  is the sort key. */
-  order: SortOrder | null;
-  /** Toggle this column's sort. The consumer owns sort state and re-queries. */
-  onToggle: () => void;
-  testID?: string;
-}
-
-/**
- * A clickable column header that cycles/toggles sort and shows the direction —
- * drop it into any `DataGrid` column's `renderHeaderCell`. Pure presentation:
- * the consumer holds the sort state and reorders/re-queries the rows. Reusable
- * outside the picker (any sortable grid).
- */
-export function SortableHeaderCell(props: SortableHeaderCellProps) {
-  const { label, order, onToggle, testID } = props;
-  const active = order !== null;
-  return (
-    <PressableHighlight
-      testID={testID}
-      onPress={onToggle}
-      accessibilityRole="button"
-      accessibilityLabel={label}
-      style={styles.cell}
-    >
-      <Text size="sm" weight="medium" color={active ? "zinc-900" : "zinc-500"} numberOfLines={1}>
-        {label}
-      </Text>
-      <Icon
-        name={order === "asc" ? "chevron-up" : order === "desc" ? "chevron-down" : "chevrons-up-down"}
-        size={14}
-        color={active ? colors.zinc["700"] : colors.zinc["400"]}
-      />
-    </PressableHighlight>
-  );
-}
-
-const styles = StyleSheet.create({
-  cell: {
-    flexDirection: "row",
-    alignItems: "center",
-    justifyContent: "space-between",
-    gap: 4,
-    flex: 1,
-    height: "100%",
-    paddingHorizontal: 8,
-  },
-});