@lotics/ui 1.17.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.17.0",
+  "version": "1.19.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -105,6 +105,7 @@
     "./pager_view": "./src/pager_view.tsx",
     "./date_picker": "./src/date_picker.tsx",
     "./date_filter": "./src/date_filter.tsx",
+    "./date_range_filter_field": "./src/date_range_filter_field.tsx",
     "./time_picker": "./src/time_picker.tsx",
     "./time_field": "./src/time_field.tsx",
     "./date_calendar": "./src/date_calendar.tsx",
@@ -144,7 +145,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_range_filter_field.tsx

@@ -0,0 +1,116 @@
+import React, { useMemo, useState } from "react";
+import { View } from "react-native";
+import { Text } from "./text";
+import { colors } from "./colors";
+import { Icon } from "./icon";
+import { Button } from "./button";
+import { PressableHighlight } from "./pressable_highlight";
+import { Popover, PopoverTrigger, PopoverContent, PopoverFooter } from "./popover";
+import { DateFilter, DateFilterValue, DateFilterLabels } from "./date_filter";
+
+// =============================================================================
+// DateRangeFilterField — the common filter composition over DateFilter:
+// a trigger button showing the selected range, a popover holding the DateFilter
+// preset panel, and a Clear/Done footer. Use this for a date-range filter on a
+// toolbar/form; use the bare `DateFilter` panel when the host owns its own
+// trigger + footer (e.g. a grid column header).
+// =============================================================================
+
+export interface DateRangeFilterFieldLabels extends DateFilterLabels {
+  /** Footer: reset to no range. */
+  clear: string;
+  /** Footer: close the popover. */
+  done: string;
+  /** Trigger text when no range is selected. */
+  placeholder: string;
+}
+
+const DEFAULT_FIELD_LABELS = { clear: "Clear", done: "Done", placeholder: "All time" };
+
+export interface DateRangeFilterFieldProps {
+  value: DateFilterValue;
+  onValueChange: (value: DateFilterValue) => void;
+  includeTime?: boolean;
+  /** Translated labels (presets + footer + placeholder). Defaults to English. */
+  labels?: Partial<DateRangeFilterFieldLabels>;
+  /** BCP-47 locale for the calendar + trigger date display. Defaults to "en-US". */
+  locale?: string;
+  testID?: string;
+}
+
+const EMPTY_VALUE: DateFilterValue = {
+  start: { date: null, time: null },
+  end: { date: null, time: null },
+};
+
+function formatDate(date: Date | null, locale: string | undefined): string {
+  if (!date) return "";
+  try {
+    return new Intl.DateTimeFormat(locale, {
+      day: "2-digit",
+      month: "2-digit",
+      year: "numeric",
+    }).format(date);
+  } catch {
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+  }
+}
+
+export function DateRangeFilterField(props: DateRangeFilterFieldProps) {
+  const { value, onValueChange, includeTime, locale, testID } = props;
+  const labels = useMemo(() => ({ ...DEFAULT_FIELD_LABELS, ...props.labels }), [props.labels]);
+  const [open, setOpen] = useState(false);
+
+  const hasValue = Boolean(value.start.date || value.end.date);
+  const display = hasValue
+    ? `${formatDate(value.start.date, locale)} – ${formatDate(value.end.date, locale)}`
+    : labels.placeholder;
+
+  return (
+    <Popover open={open} onOpenChange={setOpen} side="bottom" align="start">
+      <PopoverTrigger>
+        <PressableHighlight
+          testID={testID}
+          accessibilityRole="button"
+          accessibilityLabel={labels.selectDateRange}
+          style={{
+            flexDirection: "row",
+            alignItems: "center",
+            gap: 8,
+            paddingVertical: 9,
+            paddingHorizontal: 12,
+            borderWidth: 1,
+            borderColor: colors.zinc[300],
+            borderRadius: 8,
+            backgroundColor: colors.white,
+          }}
+        >
+          <Icon name="calendar" size={16} color={hasValue ? colors.zinc[700] : colors.zinc[400]} />
+          <Text size="sm" color={hasValue ? "default" : "muted"} numberOfLines={1} style={{ flex: 1 }}>
+            {display}
+          </Text>
+          <Icon name="chevron-down" size={14} color={colors.zinc[400]} />
+        </PressableHighlight>
+      </PopoverTrigger>
+      <PopoverContent disableBodyScroll>
+        <DateFilter
+          value={value}
+          onValueChange={onValueChange}
+          includeTime={includeTime}
+          labels={props.labels}
+          locale={locale}
+        />
+        <PopoverFooter>
+          <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between" }}>
+            {hasValue ? (
+              <Button title={labels.clear} onPress={() => onValueChange(EMPTY_VALUE)} />
+            ) : (
+              <View />
+            )}
+            <Button title={labels.done} color="secondary" onPress={() => setOpen(false)} />
+          </View>
+        </PopoverFooter>
+      </PopoverContent>
+    </Popover>
+  );
+}

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