@lotics/ui 1.16.0 → 1.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.16.0",
+  "version": "1.18.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -104,6 +104,7 @@
     "./page_header": "./src/page_header.tsx",
     "./pager_view": "./src/pager_view.tsx",
     "./date_picker": "./src/date_picker.tsx",
+    "./date_filter": "./src/date_filter.tsx",
     "./time_picker": "./src/time_picker.tsx",
     "./time_field": "./src/time_field.tsx",
     "./date_calendar": "./src/date_calendar.tsx",
@@ -143,7 +144,10 @@
     "./grid/skeleton_row": "./src/grid/skeleton_row.tsx",
     "./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/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"
   },
   "files": [
     "src"

package/src/date_filter.tsx

@@ -0,0 +1,389 @@
+import React, { useCallback, useMemo, useRef, useState } from "react";
+import { ScrollView, StyleSheet, View } from "react-native";
+import { Text } from "./text";
+import { colors } from "./colors";
+import { MenuButton } from "./menu_button";
+import { Calendar, CalendarRangeValue, CalendarRef } from "./date_calendar";
+import { TimeField } from "./time_field";
+import { Switch } from "./switch";
+import { useScreenSize } from "./use_screen_size";
+import { SegmentLabels } from "./date_segments";
+import { PresetId, PRESET_IDS, getPresetValue } from "./date_filter_presets";
+
+type SelectionMode = "single" | "range";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface DateFilterValue {
+  start: { date: Date | null; time: string | null };
+  end: { date: Date | null; time: string | null };
+}
+
+/**
+ * Translated labels. Extends `SegmentLabels` (consumed by the time fields);
+ * the rest are the preset names and the range-display strings. The frontend
+ * feeds these from `useDateFilterLabels`; standalone apps pass literals.
+ */
+export interface DateFilterLabels extends SegmentLabels {
+  today: string;
+  yesterday: string;
+  tomorrow: string;
+  thisWeek: string;
+  thisMonth: string;
+  lastMonth: string;
+  custom: string;
+  from: string;
+  to: string;
+  selectDateRange: string;
+  selectDate: string;
+}
+
+const DEFAULT_LABELS: DateFilterLabels = {
+  year: "Year",
+  month: "Month",
+  day: "Day",
+  hour: "Hour",
+  minute: "Minute",
+  dayPeriod: "AM/PM",
+  today: "Today",
+  yesterday: "Yesterday",
+  tomorrow: "Tomorrow",
+  thisWeek: "This week",
+  thisMonth: "This month",
+  lastMonth: "Last month",
+  custom: "Custom",
+  from: "From",
+  to: "To",
+  selectDateRange: "Select date range",
+  selectDate: "Select date",
+};
+
+export interface DateFilterProps {
+  value: DateFilterValue;
+  onValueChange: (value: DateFilterValue) => void;
+  includeTime?: boolean;
+  /** Translated labels. Defaults to English. */
+  labels?: Partial<DateFilterLabels>;
+  /** BCP-47 locale for the calendar and date display. Defaults to "en-US". */
+  locale?: string;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function presetLabel(id: PresetId, labels: DateFilterLabels): string {
+  switch (id) {
+    case "today":
+      return labels.today;
+    case "yesterday":
+      return labels.yesterday;
+    case "tomorrow":
+      return labels.tomorrow;
+    case "this_week":
+      return labels.thisWeek;
+    case "this_month":
+      return labels.thisMonth;
+    case "last_month":
+      return labels.lastMonth;
+    case "custom":
+      return labels.custom;
+  }
+}
+
+function formatDateDisplay(date: Date | null, locale: string | undefined): string {
+  if (!date) return "";
+  const isoDate = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+  try {
+    return new Intl.DateTimeFormat(locale, {
+      month: "short",
+      day: "numeric",
+      year: "numeric",
+    }).format(date);
+  } catch {
+    return isoDate;
+  }
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+export function DateFilter(props: DateFilterProps) {
+  const { value, onValueChange, includeTime = false, locale } = props;
+  const labels = useMemo<DateFilterLabels>(
+    () => ({ ...DEFAULT_LABELS, ...props.labels }),
+    [props.labels],
+  );
+  const screenSize = useScreenSize();
+  const calendarRef = useRef<CalendarRef>(null);
+  const [selectionMode, setSelectionMode] = useState<SelectionMode>(() => {
+    if (value.start.date && value.end.date) {
+      if (value.start.date.toDateString() !== value.end.date.toDateString()) {
+        return "range";
+      }
+    }
+    return "single";
+  });
+
+  const calendarValue: CalendarRangeValue = useMemo(
+    () => ({ start: value.start.date, end: value.end.date }),
+    [value.start.date, value.end.date],
+  );
+
+  const handleCalendarChange = useCallback(
+    (newValue: CalendarRangeValue) => {
+      // In single mode, one click selects a single date immediately
+      if (selectionMode === "single" && newValue.start && !newValue.end) {
+        onValueChange({
+          start: { date: newValue.start, time: value.start.time },
+          end: { date: newValue.start, time: value.end.time },
+        });
+        return;
+      }
+      onValueChange({
+        start: { date: newValue.start, time: value.start.time },
+        end: { date: newValue.end, time: value.end.time },
+      });
+    },
+    [onValueChange, value.start.time, value.end.time, selectionMode],
+  );
+
+  const handleModeChange = useCallback(
+    (isRange: boolean) => {
+      const newMode: SelectionMode = isRange ? "range" : "single";
+      setSelectionMode(newMode);
+
+      // Switching to single: collapse range to start date
+      if (newMode === "single" && value.start.date) {
+        onValueChange({
+          start: value.start,
+          end: { date: value.start.date, time: value.start.time },
+        });
+      }
+    },
+    [value, onValueChange],
+  );
+
+  const handleStartTimeChange = useCallback(
+    (time: string) => {
+      onValueChange({ ...value, start: { ...value.start, time: time || null } });
+    },
+    [onValueChange, value],
+  );
+
+  const handleEndTimeChange = useCallback(
+    (time: string) => {
+      onValueChange({ ...value, end: { ...value.end, time: time || null } });
+    },
+    [onValueChange, value],
+  );
+
+  // Which preset (if any) the current value matches.
+  const activePresetId = useMemo((): PresetId | null => {
+    if (!value.start.date && !value.end.date) return null;
+    const now = new Date();
+    for (const id of PRESET_IDS) {
+      const presetValue = getPresetValue(id, now);
+      if (!presetValue) continue; // "custom"
+      if (
+        value.start.date?.toDateString() === presetValue.start.date?.toDateString() &&
+        value.end.date?.toDateString() === presetValue.end.date?.toDateString()
+      ) {
+        return id;
+      }
+    }
+    return "custom";
+  }, [value]);
+
+  const handlePresetSelect = useCallback(
+    (id: PresetId) => {
+      // Re-clicking the active preset clears the filter
+      if (activePresetId === id) {
+        onValueChange({ start: { date: null, time: null }, end: { date: null, time: null } });
+        return;
+      }
+
+      const presetValue = getPresetValue(id, new Date());
+      if (!presetValue) {
+        // "Custom" clears the value so the user can select manually
+        onValueChange({ start: { date: null, time: null }, end: { date: null, time: null } });
+        return;
+      }
+
+      // Auto-switch to range mode for multi-day presets
+      if (presetValue.start.date && presetValue.end.date) {
+        const isSingleDay =
+          presetValue.start.date.toDateString() === presetValue.end.date.toDateString();
+        if (!isSingleDay && selectionMode === "single") setSelectionMode("range");
+      }
+
+      onValueChange(presetValue);
+
+      if (presetValue.start.date) {
+        calendarRef.current?.navigateToMonth(
+          presetValue.start.date.getFullYear(),
+          presetValue.start.date.getMonth(),
+        );
+      }
+    },
+    [onValueChange, activePresetId, selectionMode],
+  );
+
+  const renderPreset = (id: PresetId) => {
+    const isActive = activePresetId === id;
+    return (
+      <MenuButton
+        key={id}
+        title={
+          <Text size="sm" color={isActive ? "inverted" : "default"}>
+            {presetLabel(id, labels)}
+          </Text>
+        }
+        onPress={() => handlePresetSelect(id)}
+        style={[styles.presetItem, isActive && styles.presetItemActive]}
+      />
+    );
+  };
+
+  return (
+    <View style={[styles.container, { flexDirection: screenSize.small ? "column" : "row" }]}>
+      {/* Presets sidebar (desktop only) */}
+      {!screenSize.small && (
+        <View style={styles.presetsSidebar}>{PRESET_IDS.map(renderPreset)}</View>
+      )}
+
+      {/* Calendar and time pickers */}
+      <View style={styles.mainContent}>
+        <Calendar<"range">
+          ref={calendarRef}
+          mode="range"
+          value={calendarValue}
+          onValueChange={handleCalendarChange}
+          locale={locale}
+        />
+
+        {selectionMode === "range" ? (
+          <View style={styles.rangeDisplay}>
+            {value.start.date ? (
+              <View style={styles.rangeItem}>
+                <Text size="xs" color="zinc-500">
+                  {labels.from}
+                </Text>
+                <Text size="sm" weight="medium">
+                  {formatDateDisplay(value.start.date, locale) || labels.selectDate}
+                </Text>
+                {includeTime && (
+                  <View style={{ marginTop: 4 }}>
+                    <TimeField
+                      value={value.start.time || ""}
+                      onChange={handleStartTimeChange}
+                      segmentLabels={labels}
+                      locale={locale}
+                    />
+                  </View>
+                )}
+              </View>
+            ) : (
+              <View style={styles.rangeItem} />
+            )}
+            {value.end.date ? (
+              <View style={styles.rangeItem}>
+                <Text size="xs" color="zinc-500">
+                  {labels.to}
+                </Text>
+                <Text size="sm" weight="medium">
+                  {formatDateDisplay(value.end.date, locale) || labels.selectDate}
+                </Text>
+                {includeTime && value.end.date && (
+                  <View style={{ marginTop: 4 }}>
+                    <TimeField
+                      value={value.end.time || ""}
+                      onChange={handleEndTimeChange}
+                      segmentLabels={labels}
+                      locale={locale}
+                    />
+                  </View>
+                )}
+              </View>
+            ) : (
+              <View style={styles.rangeItem} />
+            )}
+          </View>
+        ) : null}
+
+        <View style={styles.modeToggle}>
+          <Switch value={selectionMode === "range"} onChange={handleModeChange} />
+          <Text size="sm" color="muted">
+            {labels.selectDateRange}
+          </Text>
+        </View>
+      </View>
+
+      {/* Presets (mobile only - below calendar) */}
+      {screenSize.small && (
+        <ScrollView
+          horizontal
+          showsHorizontalScrollIndicator={false}
+          style={styles.presetsScrollView}
+          contentContainerStyle={styles.presetsScrollContent}
+        >
+          {PRESET_IDS.map(renderPreset)}
+        </ScrollView>
+      )}
+    </View>
+  );
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = StyleSheet.create({
+  container: {
+    backgroundColor: colors.white,
+    borderRadius: 8,
+    gap: 16,
+  },
+  presetsSidebar: {
+    minWidth: 140,
+  },
+  presetsScrollView: {
+    borderTopWidth: 1,
+    borderTopColor: colors.zinc["200"],
+    paddingTop: 8,
+  },
+  presetsScrollContent: {
+    flexDirection: "row",
+    gap: 4,
+  },
+  presetItem: {
+    marginHorizontal: 0,
+    marginBottom: 2,
+  },
+  presetItemActive: {
+    backgroundColor: colors.zinc["800"],
+  },
+  mainContent: {
+    flex: 1,
+  },
+  modeToggle: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    paddingTop: 8,
+    paddingBottom: 8,
+    paddingLeft: 8,
+  },
+  rangeDisplay: {
+    flexDirection: "row",
+    gap: 16,
+    paddingTop: 8,
+  },
+  rangeItem: {
+    flex: 1,
+    paddingLeft: 8,
+  },
+});

package/src/date_filter_presets.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { getPresetValue, PRESET_IDS, type PresetId } from "./date_filter_presets";
+
+// Wednesday, 10 June 2026, 14:30 — a fixed clock so every range is deterministic.
+const NOW = new Date(2026, 5, 10, 14, 30, 0, 0);
+
+function ymd(d: Date | null): string {
+  if (!d) return "null";
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+describe("getPresetValue", () => {
+  it("today spans the start to end of the current day", () => {
+    const v = getPresetValue("today", NOW)!;
+    expect(ymd(v.start.date)).toBe("2026-06-10");
+    expect(ymd(v.end.date)).toBe("2026-06-10");
+    expect(v.start.date!.getHours()).toBe(0);
+    expect(v.start.date!.getMilliseconds()).toBe(0);
+    expect(v.end.date!.getHours()).toBe(23);
+    expect(v.end.date!.getMinutes()).toBe(59);
+    expect(v.end.date!.getMilliseconds()).toBe(999);
+  });
+
+  it("yesterday and tomorrow shift by one day", () => {
+    expect(ymd(getPresetValue("yesterday", NOW)!.start.date)).toBe("2026-06-09");
+    expect(ymd(getPresetValue("yesterday", NOW)!.end.date)).toBe("2026-06-09");
+    expect(ymd(getPresetValue("tomorrow", NOW)!.start.date)).toBe("2026-06-11");
+    expect(ymd(getPresetValue("tomorrow", NOW)!.end.date)).toBe("2026-06-11");
+  });
+
+  it("this_week runs Monday → Sunday around now", () => {
+    const v = getPresetValue("this_week", NOW)!;
+    expect(ymd(v.start.date)).toBe("2026-06-08"); // Monday
+    expect(v.start.date!.getDay()).toBe(1);
+    expect(ymd(v.end.date)).toBe("2026-06-14"); // Sunday
+    expect(v.end.date!.getDay()).toBe(0);
+  });
+
+  it("this_month covers the whole calendar month", () => {
+    const v = getPresetValue("this_month", NOW)!;
+    expect(ymd(v.start.date)).toBe("2026-06-01");
+    expect(ymd(v.end.date)).toBe("2026-06-30");
+  });
+
+  it("last_month covers the previous calendar month", () => {
+    const v = getPresetValue("last_month", NOW)!;
+    expect(ymd(v.start.date)).toBe("2026-05-01");
+    expect(ymd(v.end.date)).toBe("2026-05-31");
+  });
+
+  it("custom carries no range", () => {
+    expect(getPresetValue("custom", NOW)).toBeNull();
+  });
+
+  it("every preset id resolves (only custom is null)", () => {
+    for (const id of PRESET_IDS) {
+      const v = getPresetValue(id as PresetId, NOW);
+      if (id === "custom") expect(v).toBeNull();
+      else expect(v).not.toBeNull();
+    }
+  });
+});

package/src/date_filter_presets.ts

@@ -0,0 +1,100 @@
+import type { DateFilterValue } from "./date_filter";
+
+// Pure preset-range math for DateFilter. Kept free of React/RN so it can be
+// unit-tested deterministically: every range is computed from an injected
+// `now`, never an ambient clock.
+
+export type PresetId =
+  | "custom"
+  | "today"
+  | "yesterday"
+  | "tomorrow"
+  | "this_week"
+  | "this_month"
+  | "last_month";
+
+/** Display order. "custom" carries no range — it clears the value. */
+export const PRESET_IDS: PresetId[] = [
+  "today",
+  "yesterday",
+  "tomorrow",
+  "this_week",
+  "this_month",
+  "last_month",
+  "custom",
+];
+
+function startOfDay(date: Date): Date {
+  const d = new Date(date);
+  d.setHours(0, 0, 0, 0);
+  return d;
+}
+
+function endOfDay(date: Date): Date {
+  const d = new Date(date);
+  d.setHours(23, 59, 59, 999);
+  return d;
+}
+
+function startOfWeek(date: Date): Date {
+  const d = new Date(date);
+  const day = d.getDay();
+  const diff = d.getDate() - day + (day === 0 ? -6 : 1); // Monday is first day
+  d.setDate(diff);
+  d.setHours(0, 0, 0, 0);
+  return d;
+}
+
+function endOfWeek(date: Date): Date {
+  const start = startOfWeek(date);
+  const end = new Date(start);
+  end.setDate(end.getDate() + 6);
+  end.setHours(23, 59, 59, 999);
+  return end;
+}
+
+function startOfMonth(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+
+function endOfMonth(date: Date): Date {
+  return new Date(date.getFullYear(), date.getMonth() + 1, 0, 23, 59, 59, 999);
+}
+
+function range(start: Date, end: Date): DateFilterValue {
+  return { start: { date: start, time: null }, end: { date: end, time: null } };
+}
+
+/**
+ * Resolve a preset to a concrete date range relative to `now`. Returns `null`
+ * for "custom" (no range — the caller clears the value so the user picks
+ * manually). The boundary math is identical to the view-page filter so a
+ * resolved range round-trips back to the same preset.
+ */
+export function getPresetValue(id: PresetId, now: Date): DateFilterValue | null {
+  switch (id) {
+    case "today":
+      return range(startOfDay(now), endOfDay(now));
+    case "yesterday": {
+      const d = new Date(now);
+      d.setDate(d.getDate() - 1);
+      return range(startOfDay(d), endOfDay(d));
+    }
+    case "tomorrow": {
+      const d = new Date(now);
+      d.setDate(d.getDate() + 1);
+      return range(startOfDay(d), endOfDay(d));
+    }
+    case "this_week":
+      return range(startOfWeek(now), endOfWeek(now));
+    case "this_month":
+      return range(startOfMonth(now), endOfMonth(now));
+    case "last_month": {
+      const d = new Date(now);
+      d.setMonth(d.getMonth() - 1);
+      return range(startOfMonth(d), endOfMonth(d));
+    }
+    case "custom":
+      return null;
+  }
+}

package/src/grid/column_filter.tsx

@@ -0,0 +1,195 @@
+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";
+
+/** A column the picker can filter on. `type` selects the control + operators. */
+export interface FilterableColumn {
+  key: string;
+  label: string;
+  type: "text" | "number" | "select";
+  /** Options for `type: "select"`. */
+  options?: PickerOption[];
+}
+
+/** Controlled value of one column's filter — the canonical per-type input. */
+export type ColumnFilterValue =
+  | { kind: "text"; query: string }
+  | { kind: "number"; min: number | null; max: number | null }
+  | { kind: "select"; selected: string[] };
+
+/** A `TableRecordFilters` condition node (the shape the app query RPC accepts). */
+export interface FilterConditionNode {
+  node_type: "condition";
+  field_key: string;
+  type: "text" | "number" | "select";
+  operator: string;
+  value: unknown;
+}
+
+/**
+ * Map one column's filter value to query conditions (pure; reusable wherever a
+ * column filter must become a `TableRecordFilters` predicate). Returns 0+ nodes
+ * — a number range yields two, an empty filter yields none.
+ */
+export function columnFilterToConditions(
+  column: FilterableColumn,
+  value: ColumnFilterValue | undefined,
+): FilterConditionNode[] {
+  if (!value) return [];
+  if (value.kind === "text") {
+    const q = value.query.trim();
+    return q
+      ? [{ node_type: "condition", field_key: column.key, type: "text", operator: "contains", value: q }]
+      : [];
+  }
+  if (value.kind === "number") {
+    const nodes: FilterConditionNode[] = [];
+    if (value.min != null) {
+      nodes.push({ node_type: "condition", field_key: column.key, type: "number", operator: "greater_than_or_equal_to", value: value.min });
+    }
+    if (value.max != null) {
+      nodes.push({ node_type: "condition", field_key: column.key, type: "number", operator: "less_than_or_equal_to", value: value.max });
+    }
+    return nodes;
+  }
+  return value.selected.length > 0
+    ? [{ node_type: "condition", field_key: column.key, type: "select", operator: "has_any_of", value: value.selected }]
+    : [];
+}
+
+/** Whether a value represents an active (non-empty) filter — drives the pill state. */
+export function isColumnFilterActive(value: ColumnFilterValue | undefined): boolean {
+  if (!value) return false;
+  if (value.kind === "text") return value.query.trim().length > 0;
+  if (value.kind === "number") return value.min != null || value.max != null;
+  return value.selected.length > 0;
+}
+
+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". */
+  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
+ * `columnFilterToConditions`. Pure UI; no data layer.
+ */
+export function ColumnFilter(props: ColumnFilterProps) {
+  const { column, value, onChange, clearLabel = "Clear" } = props;
+  const active = isColumnFilterActive(value);
+
+  return (
+    <Popover side="bottom" align="start">
+      <PopoverTrigger>
+        <PressableHighlight
+          accessibilityRole="button"
+          accessibilityLabel={column.label}
+          style={[styles.pill, active && styles.pillActive]}
+        >
+          <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}
+          </Text>
+          <Icon name="chevron-down" size={14} color={colors.zinc["400"]} />
+        </PressableHighlight>
+      </PopoverTrigger>
+      <PopoverContent style={styles.content}>
+        {column.type === "text" ? (
+          <TextInputField
+            autoFocus
+            value={value?.kind === "text" ? value.query : ""}
+            onChangeText={(query) => onChange({ kind: "text", query })}
+            placeholder={column.label}
+          />
+        ) : column.type === "number" ? (
+          <View style={styles.range}>
+            <NumberInput
+              accessibilityLabel={`${column.label} min`}
+              value={value?.kind === "number" ? value.min : null}
+              onValueChange={(min) =>
+                onChange({ kind: "number", min, max: value?.kind === "number" ? value.max : null })
+              }
+            />
+            <Text size="sm" color="zinc-500">
+              –
+            </Text>
+            <NumberInput
+              accessibilityLabel={`${column.label} max`}
+              value={value?.kind === "number" ? value.max : null}
+              onValueChange={(max) =>
+                onChange({ kind: "number", min: value?.kind === "number" ? value.min : null, max })
+              }
+            />
+          </View>
+        ) : (
+          <PickerMenu
+            multi
+            enableSearch
+            options={column.options ?? []}
+            value={value?.kind === "select" ? value.selected : []}
+            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,
+  },
+  range: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+  },
+  clear: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+    paddingVertical: 6,
+    paddingHorizontal: 4,
+  },
+});

package/src/grid/data_grid_picker.tsx

@@ -0,0 +1,322 @@
+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";
+
+/** A grid column the picker displays. Sorting/filtering are opt-in per column. */
+export interface PickerColumn<TRow> {
+  key: string;
+  label: string;
+  /** Fixed pixel width. Omit to let the grid size it. */
+  width?: number;
+  /** 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`).
+   */
+  renderCell?: (row: TRow) => React.ReactNode;
+}
+
+/** Single-column sort state — the picker sorts by one column at a time. */
+export interface DataGridPickerSort {
+  key: string;
+  order: SortOrder;
+}
+
+export interface DataGridPickerProps<TRow extends Record<string, unknown>> {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  /** Heading shown above the search box. */
+  title?: string;
+
+  columns: PickerColumn<TRow>[];
+  rows: TRow[];
+  /** Stable identity for a row — the value returned by selection. */
+  rowIdGetter: (row: TRow) => string;
+
+  /** Currently selected row id, or null. Highlights the matching row. */
+  value: string | null;
+  /** Called with the picked row id. */
+  onValueChange: (id: string) => void;
+  /** Close the dialog after a pick. Default `true`. */
+  closeOnSelect?: boolean;
+
+  /** Controlled search term. The consumer owns it and re-queries. */
+  searchQuery: string;
+  onSearchChange: (query: string) => void;
+  searchPlaceholder?: string;
+
+  /**
+   * Controlled single-column sort. Omit `onSortChange` to disable sorting
+   * entirely (headers render static). Toggling a column cycles asc → desc → off.
+   */
+  sort?: DataGridPickerSort | null;
+  onSortChange?: (sort: DataGridPickerSort | 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`.
+   */
+  filters?: FilterableColumn[];
+  filterValues?: Record<string, ColumnFilterValue>;
+  onFilterChange?: (key: string, value: ColumnFilterValue | undefined) => void;
+  /** 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;
+
+  /** A request is in flight. Shows a spinner (overlay when rows exist). */
+  loading?: boolean;
+  /** Message when there are no rows and nothing is loading. */
+  emptyLabel?: string;
+
+  rowHeight?: number;
+  testID?: string;
+}
+
+/** Render an arbitrary cell value as a single line when no `renderCell` is given. */
+function defaultCellText(value: unknown): string {
+  if (value == null) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return value.map(defaultCellText).filter(Boolean).join(", ");
+  if (typeof value === "object") {
+    const o = value as { label?: unknown; display?: unknown; name?: unknown };
+    for (const k of [o.label, o.display, o.name]) {
+      if (typeof k === "string") return k;
+    }
+  }
+  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.
+ *
+ * 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.
+ */
+export function DataGridPicker<TRow extends Record<string, unknown>>(
+  props: DataGridPickerProps<TRow>,
+) {
+  const {
+    open,
+    onOpenChange,
+    title,
+    columns,
+    rows,
+    rowIdGetter,
+    value,
+    onValueChange,
+    closeOnSelect = true,
+    searchQuery,
+    onSearchChange,
+    searchPlaceholder,
+    sort = null,
+    onSortChange,
+    filters,
+    filterValues,
+    onFilterChange,
+    clearLabel,
+    onEndReached,
+    loading = false,
+    emptyLabel,
+    rowHeight = DEFAULT_ROW_HEIGHT,
+    testID,
+  } = props;
+
+  const handleSelect = useCallback(
+    (id: string) => {
+      onValueChange(id);
+      if (closeOnSelect) onOpenChange(false);
+    },
+    [onValueChange, closeOnSelect, onOpenChange],
+  );
+
+  const toggleSort = useCallback(
+    (key: string) => {
+      if (!onSortChange) return;
+      if (!sort || sort.key !== key) onSortChange({ key, order: "asc" });
+      else if (sort.order === "asc") onSortChange({ key, order: "desc" });
+      else onSortChange(null);
+    },
+    [sort, onSortChange],
+  );
+
+  const gridColumns = useMemo<DataGridColumn<TRow>[]>(
+    () =>
+      columns.map((col) => ({
+        key: col.key,
+        name: 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>
+        ),
+      })),
+    [columns, sort, onSortChange, toggleSort, handleSelect, rowIdGetter],
+  );
+
+  const groups = useMemo<DataGridGroup<TRow>[]>(
+    () => (rows.length > 0 ? [{ value: null, columnKey: "", rows }] : []),
+    [rows],
+  );
+
+  const rowColorGetter = useCallback(
+    (row: TRow) =>
+      value != null && rowIdGetter(row) === value ? colors.blue["50"] : undefined,
+    [value, rowIdGetter],
+  );
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange} height="90%" testID={testID}>
+      <View style={styles.root}>
+        {title ? (
+          <Text size="lg" weight="semibold" color="zinc-900" style={styles.title}>
+            {title}
+          </Text>
+        ) : null}
+
+        <SearchInput
+          testID="data-grid-picker-search"
+          value={searchQuery}
+          onChangeText={onSearchChange}
+          placeholder={searchPlaceholder}
+          style={styles.search}
+        />
+
+        {filters && filters.length > 0 ? (
+          <View style={styles.filterRow}>
+            {filters.map((f) => (
+              <ColumnFilter
+                key={f.key}
+                column={f}
+                value={filterValues?.[f.key]}
+                onChange={(v) => onFilterChange?.(f.key, v)}
+                clearLabel={clearLabel}
+              />
+            ))}
+          </View>
+        ) : 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}
+            />
+          ) : (
+            <View style={styles.center}>
+              {loading ? (
+                <ActivityIndicator />
+              ) : (
+                <Text size="sm" color="zinc-500">
+                  {emptyLabel ?? "No results"}
+                </Text>
+              )}
+            </View>
+          )}
+          {loading && groups.length > 0 ? (
+            <View style={styles.loadingOverlay} pointerEvents="none">
+              <ActivityIndicator />
+            </View>
+          ) : null}
+        </View>
+      </View>
+    </Dialog>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flex: 1,
+    width: "100%",
+    gap: 12,
+    paddingHorizontal: 4,
+  },
+  title: {
+    paddingHorizontal: 4,
+  },
+  search: {
+    width: "100%",
+  },
+  filterRow: {
+    flexDirection: "row",
+    flexWrap: "wrap",
+    alignItems: "center",
+    gap: 8,
+  },
+  gridArea: {
+    flex: 1,
+    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/grid/sortable_header_cell.tsx

@@ -0,0 +1,58 @@
+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,
+  },
+});