@mdxui/terminal 2.0.0

package/src/data/reactive.ts

@@ -0,0 +1,1225 @@
+/**
+ * @mdxui/terminal Reactive Data Hooks for Data Components
+ *
+ * This module provides React hooks for connecting data components (Table, List,
+ * Card, Metrics) to TanStack DB collections with reactive updates and optimistic
+ * mutations.
+ *
+ * Key features:
+ * - Reactive data binding - UI updates automatically when collection data changes
+ * - Optimistic updates - UI updates immediately, rolls back on error
+ * - Type-safe queries - Full TypeScript support with Zod validation
+ * - Live subscriptions - Real-time updates from collection changes
+ *
+ * @example
+ * ```tsx
+ * import { useReactiveTable, useReactiveList } from '@mdxui/terminal'
+ *
+ * function UsersTable() {
+ *   const { data, isLoading, mutate, sort, setSort } = useReactiveTable({
+ *     collection: 'users',
+ *     where: { status: 'active' },
+ *     orderBy: { name: 'asc' },
+ *   })
+ *
+ *   // Data updates reactively when collection changes
+ *   return (
+ *     <Table
+ *       columns={[
+ *         { key: 'name', header: 'Name', sortable: true },
+ *         { key: 'email', header: 'Email' },
+ *       ]}
+ *       data={data}
+ *       sortBy={sort.field}
+ *       sortDirection={sort.direction}
+ *       onSort={(field) => setSort(field)}
+ *       onRowAction={(action, row) => {
+ *         if (action === 'delete') {
+ *           mutate.delete({ id: row.id })
+ *         }
+ *       }}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+
+import { useState, useEffect, useCallback, useRef } from 'react'
+import { useDBContext } from './context'
+import type {
+  QueryOptions,
+  MutationResult,
+  WhereClause,
+  OrderByClause,
+  OrderDirection,
+  Collection,
+} from './types'
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Sort state for reactive data components
+ *
+ * @example
+ * ```typescript
+ * const sort: SortState = {
+ *   field: 'createdAt',
+ *   direction: 'desc',
+ * }
+ * ```
+ */
+export interface SortState {
+  /** Field to sort by */
+  field: string | null
+  /** Sort direction: 'asc' or 'desc' */
+  direction: OrderDirection
+}
+
+/**
+ * Selection state for reactive data components
+ *
+ * @example
+ * ```typescript
+ * const selection: SelectionState = {
+ *   mode: 'multi',
+ *   selected: new Set(['user-1', 'user-3']),
+ * }
+ * ```
+ */
+export interface SelectionState {
+  /** Selection mode: 'single', 'multi', or 'none' */
+  mode: 'single' | 'multi' | 'none'
+  /** Set of selected item IDs */
+  selected: Set<string>
+}
+
+/**
+ * Pagination state for reactive data components
+ *
+ * @example
+ * ```typescript
+ * const pagination: PaginationState = {
+ *   page: 1,
+ *   pageSize: 20,
+ *   total: 150,
+ * }
+ * ```
+ */
+export interface PaginationState {
+  /** Current page (1-indexed) */
+  page: number
+  /** Items per page */
+  pageSize: number
+  /** Total item count (from query) */
+  total: number
+}
+
+/**
+ * Options for useReactiveData hook
+ *
+ * @template T - The document type
+ *
+ * @remarks
+ * Extends QueryOptions with reactive-specific options like selection, sorting,
+ * and pagination control.
+ *
+ * @example
+ * ```typescript
+ * const options: ReactiveDataOptions<User> = {
+ *   collection: 'users',
+ *   where: { role: 'admin' },
+ *   orderBy: { createdAt: 'desc' },
+ *   limit: 20,
+ *   selectable: 'multi',
+ *   optimistic: true,
+ * }
+ * ```
+ */
+export interface ReactiveDataOptions<T> {
+  /** Collection name to query from */
+  collection: string
+  /** Filter conditions */
+  where?: WhereClause<T>
+  /** Sort order */
+  orderBy?: OrderByClause<T> | OrderByClause<T>[]
+  /** Maximum items to return */
+  limit?: number
+  /** Items to skip (for pagination) */
+  offset?: number
+  /** Enable selection: 'single', 'multi', or false */
+  selectable?: 'single' | 'multi' | boolean
+  /** Enable optimistic updates (default: true) */
+  optimistic?: boolean
+  /** Primary key field (default: 'id') */
+  primaryKey?: keyof T
+}
+
+/**
+ * Result of useReactiveData hook
+ *
+ * @template T - The document type
+ *
+ * @remarks
+ * Provides reactive data, loading/error states, mutation functions, and
+ * controls for sorting, selection, and pagination.
+ *
+ * @example
+ * ```typescript
+ * const {
+ *   data,
+ *   isLoading,
+ *   error,
+ *   mutate,
+ *   sort,
+ *   setSort,
+ *   selection,
+ *   toggleSelect,
+ *   pagination,
+ *   setPage,
+ * } = useReactiveData<User>({ collection: 'users' })
+ * ```
+ */
+export interface ReactiveDataResult<T> {
+  /** Reactive data array - updates when collection changes */
+  data: T[]
+  /** True while initial query is executing */
+  isLoading: boolean
+  /** Error if query or mutation failed */
+  error: Error | undefined
+  /** Manual refetch function */
+  refetch: () => void
+
+  // Mutation functions
+  /** Mutation functions for insert, update, delete */
+  mutate: {
+    /** Insert a new document */
+    insert: (data: T) => Promise<void>
+    /** Update documents matching filter */
+    update: (filter: Partial<T>, updates: Partial<T>) => Promise<void>
+    /** Delete a document by ID */
+    delete: (filter: { id: string } | Partial<T>) => Promise<void>
+  }
+  /** True while any mutation is pending */
+  isMutating: boolean
+
+  // Sort state
+  /** Current sort state */
+  sort: SortState
+  /** Set sort field (toggles direction if same field) */
+  setSort: (field: string) => void
+
+  // Selection state
+  /** Current selection state */
+  selection: SelectionState
+  /** Toggle selection for an item */
+  toggleSelect: (id: string) => void
+  /** Select all items */
+  selectAll: () => void
+  /** Clear all selections */
+  clearSelection: () => void
+
+  // Pagination state
+  /** Current pagination state */
+  pagination: PaginationState
+  /** Go to a specific page */
+  setPage: (page: number) => void
+  /** Change page size */
+  setPageSize: (size: number) => void
+}
+
+/**
+ * Options for useReactiveTable hook
+ *
+ * @template T - The document type
+ *
+ * @remarks
+ * Table-specific options extending ReactiveDataOptions with column definitions.
+ */
+export interface ReactiveTableOptions<T> extends ReactiveDataOptions<T> {
+  /** Column definitions for the table */
+  columns?: Array<{
+    key: keyof T
+    header: string
+    sortable?: boolean
+    width?: number
+    align?: 'left' | 'center' | 'right'
+  }>
+}
+
+/**
+ * Options for useReactiveList hook
+ *
+ * @template T - The document type
+ *
+ * @remarks
+ * List-specific options extending ReactiveDataOptions.
+ */
+export interface ReactiveListOptions<T> extends ReactiveDataOptions<T> {
+  /** Field to use as display text */
+  labelField?: keyof T
+  /** Field to use as icon */
+  iconField?: keyof T
+}
+
+/**
+ * Options for useReactiveMetrics hook
+ *
+ * @template T - The document type
+ *
+ * @remarks
+ * Metrics-specific options for aggregated data display.
+ */
+export interface ReactiveMetricsOptions<T> extends Omit<ReactiveDataOptions<T>, 'limit' | 'offset'> {
+  /** Metrics to compute from collection data */
+  metrics: Array<{
+    /** Unique key for the metric */
+    key: string
+    /** Display label */
+    label: string
+    /** Field to aggregate */
+    field: keyof T
+    /** Aggregation function */
+    aggregate: 'count' | 'sum' | 'avg' | 'min' | 'max' | 'latest'
+    /** Format for display */
+    format?: 'number' | 'currency' | 'percentage'
+    /** Unit suffix */
+    unit?: string
+  }>
+}
+
+/**
+ * Single metric result
+ */
+export interface MetricValue {
+  /** Metric key */
+  key: string
+  /** Display label */
+  label: string
+  /** Computed value */
+  value: number | string
+  /** Trend direction (computed from previous values if available) */
+  trend?: 'up' | 'down' | 'neutral'
+  /** Trend percentage change */
+  trendValue?: number
+  /** Optional sparkline data */
+  sparkline?: number[]
+}
+
+/**
+ * Result of useReactiveMetrics hook
+ */
+export interface ReactiveMetricsResult {
+  /** Computed metric values */
+  metrics: MetricValue[]
+  /** True while initial query is executing */
+  isLoading: boolean
+  /** Error if query failed */
+  error: Error | undefined
+  /** Manual refetch function */
+  refetch: () => void
+}
+
+/**
+ * Options for useReactiveCard hook
+ *
+ * @template T - The document type
+ *
+ * @remarks
+ * Card-specific options for single-record display.
+ */
+export interface ReactiveCardOptions<T> {
+  /** Collection name */
+  collection: string
+  /** Filter to find single record */
+  where: WhereClause<T>
+  /** Fields to display as key-value pairs */
+  fields?: Array<{
+    key: keyof T
+    label: string
+    format?: 'string' | 'date' | 'currency' | 'badge'
+  }>
+  /** Enable optimistic updates */
+  optimistic?: boolean
+}
+
+/**
+ * Result of useReactiveCard hook
+ */
+export interface ReactiveCardResult<T> {
+  /** Single record data */
+  data: T | null
+  /** True while loading */
+  isLoading: boolean
+  /** Error if query failed */
+  error: Error | undefined
+  /** Refetch function */
+  refetch: () => void
+  /** Update the record */
+  update: (updates: Partial<T>) => Promise<void>
+  /** True while updating */
+  isUpdating: boolean
+}
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+/**
+ * Hook for reactive data binding with TanStack DB collections
+ *
+ * Provides reactive data updates, optimistic mutations, sorting, selection,
+ * and pagination for data components like Table and List.
+ *
+ * @template T - The document type (must extend Record<string, any>)
+ *
+ * @param options - Configuration for collection, filters, and behavior
+ * @returns ReactiveDataResult with data, mutations, and state controls
+ *
+ * @remarks
+ * - Data updates automatically when collection changes (via subscriptions)
+ * - Optimistic updates show changes immediately, roll back on error
+ * - Sort state toggles direction when same field is selected
+ * - Selection supports single and multi-select modes
+ * - Pagination is handled client-side with limit/offset
+ *
+ * @example
+ * ```tsx
+ * function UserList() {
+ *   const {
+ *     data,
+ *     isLoading,
+ *     mutate,
+ *     sort,
+ *     setSort,
+ *     selection,
+ *     toggleSelect,
+ *   } = useReactiveData<User>({
+ *     collection: 'users',
+ *     where: { status: 'active' },
+ *     orderBy: { name: 'asc' },
+ *     selectable: 'multi',
+ *   })
+ *
+ *   if (isLoading) return <Spinner />
+ *
+ *   return (
+ *     <List
+ *       items={data.map(user => ({
+ *         id: user.id,
+ *         text: user.name,
+ *         selected: selection.selected.has(user.id),
+ *       }))}
+ *       onItemClick={(id) => toggleSelect(id)}
+ *       onDelete={(id) => mutate.delete({ id })}
+ *     />
+ *   )
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With optimistic updates
+ * function QuickAddUser() {
+ *   const { mutate, isMutating } = useReactiveData<User>({
+ *     collection: 'users',
+ *     optimistic: true,
+ *   })
+ *
+ *   const handleAdd = async () => {
+ *     // UI updates immediately, rolls back if server fails
+ *     await mutate.insert({
+ *       id: crypto.randomUUID(),
+ *       name: 'New User',
+ *       status: 'active',
+ *     })
+ *   }
+ *
+ *   return (
+ *     <button onClick={handleAdd} disabled={isMutating}>
+ *       {isMutating ? 'Adding...' : 'Add User'}
+ *     </button>
+ *   )
+ * }
+ * ```
+ */
+export function useReactiveData<T extends Record<string, any>>(
+  options: ReactiveDataOptions<T>
+): ReactiveDataResult<T> {
+  const db = useDBContext()
+  const {
+    collection: collectionName,
+    where,
+    orderBy: initialOrderBy,
+    limit,
+    offset,
+    selectable = false,
+    optimistic = true,
+    primaryKey = 'id' as keyof T,
+  } = options
+
+  // Data state
+  const [data, setData] = useState<T[]>([])
+  const [isLoading, setIsLoading] = useState(true)
+  const [error, setError] = useState<Error | undefined>(undefined)
+  const [isMutating, setIsMutating] = useState(false)
+
+  // Sort state
+  const [sort, setSortState] = useState<SortState>(() => {
+    if (!initialOrderBy) return { field: null, direction: 'asc' as OrderDirection }
+    const orderClauses = Array.isArray(initialOrderBy) ? initialOrderBy : [initialOrderBy]
+    if (orderClauses.length === 0) return { field: null, direction: 'asc' as OrderDirection }
+    const [field, direction] = Object.entries(orderClauses[0])[0]
+    return { field, direction: direction as OrderDirection }
+  })
+
+  // Selection state
+  const [selection, setSelection] = useState<SelectionState>({
+    mode: selectable === true ? 'single' : selectable === false ? 'none' : selectable,
+    selected: new Set<string>(),
+  })
+
+  // Pagination state
+  const [pagination, setPagination] = useState<PaginationState>({
+    page: 1,
+    pageSize: limit ?? 20,
+    total: 0,
+  })
+
+  // Refs for tracking rollback data
+  const rollbackDataRef = useRef<T[]>([])
+
+  // Get collection
+  const collection = db.collections[collectionName] as Collection<T> | undefined
+
+  // Build orderBy from sort state
+  const currentOrderBy = sort.field
+    ? { [sort.field]: sort.direction } as OrderByClause<T>
+    : initialOrderBy
+
+  // Execute query
+  const executeQuery = useCallback(async () => {
+    if (!collection) {
+      setError(new Error(`Collection '${collectionName}' not found`))
+      setIsLoading(false)
+      return
+    }
+
+    try {
+      const result = await collection.findMany({
+        where,
+        orderBy: currentOrderBy,
+        limit,
+        offset,
+      })
+      setData(result)
+      setPagination(prev => ({ ...prev, total: result.length }))
+      setError(undefined)
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)))
+    } finally {
+      setIsLoading(false)
+    }
+  }, [collection, collectionName, JSON.stringify(where), JSON.stringify(currentOrderBy), limit, offset])
+
+  // Initial fetch
+  useEffect(() => {
+    executeQuery()
+  }, [executeQuery])
+
+  // Subscribe to collection changes
+  useEffect(() => {
+    if (!collection) return
+
+    const unsubscribe = collection.subscribe((allData: T[]) => {
+      // Re-apply filters when data changes
+      let result = allData
+
+      if (where) {
+        result = result.filter(doc => matchesWhere(doc, where))
+      }
+
+      if (currentOrderBy) {
+        result = sortDocuments(result, currentOrderBy)
+      }
+
+      if (offset !== undefined) {
+        result = result.slice(offset)
+      }
+
+      if (limit !== undefined) {
+        result = result.slice(0, limit)
+      }
+
+      setData(result)
+      setPagination(prev => ({ ...prev, total: result.length }))
+    })
+
+    return unsubscribe
+  }, [collection, JSON.stringify(where), JSON.stringify(currentOrderBy), limit, offset])
+
+  // Mutation functions
+  const mutate = {
+    insert: useCallback(async (newData: T) => {
+      if (!collection) {
+        throw new Error(`Collection '${collectionName}' not found`)
+      }
+
+      setIsMutating(true)
+
+      if (optimistic) {
+        // Save for rollback
+        rollbackDataRef.current = [...data]
+        // Optimistically add to local state
+        setData(prev => [...prev, newData])
+      }
+
+      try {
+        await collection.insert(newData)
+        // If not optimistic, data will update via subscription
+      } catch (err) {
+        // Rollback on error
+        if (optimistic) {
+          setData(rollbackDataRef.current)
+        }
+        throw err
+      } finally {
+        setIsMutating(false)
+      }
+    }, [collection, collectionName, data, optimistic]),
+
+    update: useCallback(async (filter: Partial<T>, updates: Partial<T>) => {
+      if (!collection) {
+        throw new Error(`Collection '${collectionName}' not found`)
+      }
+
+      setIsMutating(true)
+
+      if (optimistic) {
+        // Save for rollback
+        rollbackDataRef.current = [...data]
+        // Optimistically update local state
+        setData(prev => prev.map(item => {
+          const matches = Object.entries(filter).every(([key, val]) => item[key] === val)
+          return matches ? { ...item, ...updates } : item
+        }))
+      }
+
+      try {
+        await collection.update(filter, updates)
+      } catch (err) {
+        if (optimistic) {
+          setData(rollbackDataRef.current)
+        }
+        throw err
+      } finally {
+        setIsMutating(false)
+      }
+    }, [collection, collectionName, data, optimistic]),
+
+    delete: useCallback(async (filter: { id: string } | Partial<T>) => {
+      if (!collection) {
+        throw new Error(`Collection '${collectionName}' not found`)
+      }
+
+      setIsMutating(true)
+
+      if (optimistic) {
+        // Save for rollback
+        rollbackDataRef.current = [...data]
+        // Optimistically remove from local state
+        setData(prev => prev.filter(item => {
+          const matches = Object.entries(filter).every(([key, val]) => item[key as keyof T] === val)
+          return !matches
+        }))
+      }
+
+      try {
+        await collection.delete(filter as Partial<T>)
+      } catch (err) {
+        if (optimistic) {
+          setData(rollbackDataRef.current)
+        }
+        throw err
+      } finally {
+        setIsMutating(false)
+      }
+    }, [collection, collectionName, data, optimistic]),
+  }
+
+  // Sort control
+  const setSort = useCallback((field: string) => {
+    setSortState(prev => ({
+      field,
+      direction: prev.field === field && prev.direction === 'asc' ? 'desc' : 'asc',
+    }))
+  }, [])
+
+  // Selection controls
+  const toggleSelect = useCallback((id: string) => {
+    setSelection(prev => {
+      const newSelected = new Set(prev.selected)
+      if (prev.mode === 'single') {
+        // Single mode: toggle or replace
+        if (newSelected.has(id)) {
+          newSelected.clear()
+        } else {
+          newSelected.clear()
+          newSelected.add(id)
+        }
+      } else if (prev.mode === 'multi') {
+        // Multi mode: toggle
+        if (newSelected.has(id)) {
+          newSelected.delete(id)
+        } else {
+          newSelected.add(id)
+        }
+      }
+      return { ...prev, selected: newSelected }
+    })
+  }, [])
+
+  const selectAll = useCallback(() => {
+    if (selection.mode === 'none') return
+    const allIds = data.map(item => String(item[primaryKey]))
+    setSelection(prev => ({ ...prev, selected: new Set(allIds) }))
+  }, [data, primaryKey, selection.mode])
+
+  const clearSelection = useCallback(() => {
+    setSelection(prev => ({ ...prev, selected: new Set() }))
+  }, [])
+
+  // Pagination controls
+  const setPage = useCallback((page: number) => {
+    setPagination(prev => ({ ...prev, page }))
+  }, [])
+
+  const setPageSize = useCallback((size: number) => {
+    setPagination(prev => ({ ...prev, pageSize: size, page: 1 }))
+  }, [])
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: executeQuery,
+    mutate,
+    isMutating,
+    sort,
+    setSort,
+    selection,
+    toggleSelect,
+    selectAll,
+    clearSelection,
+    pagination,
+    setPage,
+    setPageSize,
+  }
+}
+
+/**
+ * Hook for reactive table data with TanStack DB integration
+ *
+ * Specialized version of useReactiveData for Table components with
+ * column-aware sorting and selection.
+ *
+ * @template T - The document type
+ *
+ * @param options - Table-specific options including column definitions
+ * @returns ReactiveDataResult with table-optimized behavior
+ *
+ * @example
+ * ```tsx
+ * function UsersTable() {
+ *   const {
+ *     data,
+ *     sort,
+ *     setSort,
+ *     selection,
+ *     toggleSelect,
+ *   } = useReactiveTable<User>({
+ *     collection: 'users',
+ *     columns: [
+ *       { key: 'name', header: 'Name', sortable: true },
+ *       { key: 'email', header: 'Email' },
+ *       { key: 'role', header: 'Role', sortable: true },
+ *     ],
+ *     selectable: 'multi',
+ *   })
+ *
+ *   return (
+ *     <Table
+ *       columns={columns}
+ *       data={data}
+ *       sortBy={sort.field}
+ *       sortDirection={sort.direction}
+ *       onSort={setSort}
+ *       selectedRows={Array.from(selection.selected)}
+ *       onRowSelect={toggleSelect}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useReactiveTable<T extends Record<string, any>>(
+  options: ReactiveTableOptions<T>
+): ReactiveDataResult<T> {
+  return useReactiveData<T>(options)
+}
+
+/**
+ * Hook for reactive list data with TanStack DB integration
+ *
+ * Specialized version of useReactiveData for List components with
+ * item-level selection and actions.
+ *
+ * @template T - The document type
+ *
+ * @param options - List-specific options
+ * @returns ReactiveDataResult with list-optimized behavior
+ *
+ * @example
+ * ```tsx
+ * function TaskList() {
+ *   const {
+ *     data,
+ *     mutate,
+ *     toggleSelect,
+ *   } = useReactiveList<Task>({
+ *     collection: 'tasks',
+ *     where: { completed: false },
+ *     orderBy: { priority: 'desc' },
+ *     labelField: 'title',
+ *     selectable: 'single',
+ *   })
+ *
+ *   return (
+ *     <List
+ *       items={data.map(task => ({
+ *         id: task.id,
+ *         content: task.title,
+ *         icon: task.priority === 'high' ? 'alert' : 'task',
+ *       }))}
+ *       onItemClick={(id) => toggleSelect(id)}
+ *       onDelete={(id) => mutate.delete({ id })}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useReactiveList<T extends Record<string, any>>(
+  options: ReactiveListOptions<T>
+): ReactiveDataResult<T> {
+  return useReactiveData<T>(options)
+}
+
+/**
+ * Hook for reactive metrics computed from TanStack DB collections
+ *
+ * Aggregates collection data into metric values with optional trend
+ * computation and sparkline data.
+ *
+ * @template T - The document type
+ *
+ * @param options - Metrics configuration with aggregation definitions
+ * @returns ReactiveMetricsResult with computed metric values
+ *
+ * @example
+ * ```tsx
+ * function DashboardMetrics() {
+ *   const { metrics, isLoading } = useReactiveMetrics<Order>({
+ *     collection: 'orders',
+ *     where: { status: 'completed' },
+ *     metrics: [
+ *       {
+ *         key: 'total-orders',
+ *         label: 'Total Orders',
+ *         field: 'id',
+ *         aggregate: 'count',
+ *       },
+ *       {
+ *         key: 'revenue',
+ *         label: 'Revenue',
+ *         field: 'total',
+ *         aggregate: 'sum',
+ *         format: 'currency',
+ *       },
+ *       {
+ *         key: 'avg-order',
+ *         label: 'Avg Order',
+ *         field: 'total',
+ *         aggregate: 'avg',
+ *         format: 'currency',
+ *       },
+ *     ],
+ *   })
+ *
+ *   if (isLoading) return <Spinner />
+ *
+ *   return (
+ *     <Metrics
+ *       metrics={metrics.map(m => ({
+ *         label: m.label,
+ *         value: m.value,
+ *         trend: m.trend,
+ *         trendValue: m.trendValue,
+ *       }))}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useReactiveMetrics<T extends Record<string, any>>(
+  options: ReactiveMetricsOptions<T>
+): ReactiveMetricsResult {
+  const db = useDBContext()
+  const { collection: collectionName, where, metrics: metricDefs } = options
+
+  const [metrics, setMetrics] = useState<MetricValue[]>([])
+  const [isLoading, setIsLoading] = useState(true)
+  const [error, setError] = useState<Error | undefined>(undefined)
+
+  // Historical data for sparklines (last N values per metric)
+  const historyRef = useRef<Map<string, number[]>>(new Map())
+
+  const collection = db.collections[collectionName] as Collection<T> | undefined
+
+  const computeMetrics = useCallback(async () => {
+    if (!collection) {
+      setError(new Error(`Collection '${collectionName}' not found`))
+      setIsLoading(false)
+      return
+    }
+
+    try {
+      const data = await collection.findMany({ where })
+
+      const computed: MetricValue[] = metricDefs.map(def => {
+        const values: number[] = data.map(doc => {
+          const val = doc[def.field]
+          return typeof val === 'number' ? val : 0
+        })
+
+        let value: number
+        switch (def.aggregate) {
+          case 'count':
+            value = data.length
+            break
+          case 'sum':
+            value = values.reduce((a: number, b: number) => a + b, 0)
+            break
+          case 'avg':
+            value = values.length > 0 ? values.reduce((a: number, b: number) => a + b, 0) / values.length : 0
+            break
+          case 'min':
+            value = values.length > 0 ? Math.min(...values) : 0
+            break
+          case 'max':
+            value = values.length > 0 ? Math.max(...values) : 0
+            break
+          case 'latest':
+            value = values.length > 0 ? values[values.length - 1] : 0
+            break
+          default:
+            value = 0
+        }
+
+        // Update history for sparkline
+        const history = historyRef.current.get(def.key) || []
+        history.push(value)
+        if (history.length > 20) history.shift() // Keep last 20 values
+        historyRef.current.set(def.key, history)
+
+        // Compute trend
+        let trend: 'up' | 'down' | 'neutral' = 'neutral'
+        let trendValue: number | undefined
+        if (history.length >= 2) {
+          const prev = history[history.length - 2]
+          const current = history[history.length - 1]
+          if (prev !== 0) {
+            trendValue = ((current - prev) / prev) * 100
+            trend = trendValue > 0 ? 'up' : trendValue < 0 ? 'down' : 'neutral'
+          }
+        }
+
+        // Format value
+        let formattedValue: string | number = value
+        if (def.format === 'currency') {
+          formattedValue = `$${value.toLocaleString()}`
+        } else if (def.format === 'percentage') {
+          formattedValue = `${value.toFixed(1)}%`
+        }
+        if (def.unit) {
+          formattedValue = `${formattedValue} ${def.unit}`
+        }
+
+        return {
+          key: def.key,
+          label: def.label,
+          value: formattedValue,
+          trend,
+          trendValue,
+          sparkline: [...history],
+        }
+      })
+
+      setMetrics(computed)
+      setError(undefined)
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)))
+    } finally {
+      setIsLoading(false)
+    }
+  }, [collection, collectionName, JSON.stringify(where), JSON.stringify(metricDefs)])
+
+  // Initial computation
+  useEffect(() => {
+    computeMetrics()
+  }, [computeMetrics])
+
+  // Subscribe to changes
+  useEffect(() => {
+    if (!collection) return
+    const unsubscribe = collection.subscribe(() => {
+      computeMetrics()
+    })
+    return unsubscribe
+  }, [collection, computeMetrics])
+
+  return {
+    metrics,
+    isLoading,
+    error,
+    refetch: computeMetrics,
+  }
+}
+
+/**
+ * Hook for reactive single-record card data with TanStack DB integration
+ *
+ * Fetches and subscribes to a single record from a collection for
+ * Card component display.
+ *
+ * @template T - The document type
+ *
+ * @param options - Card-specific options
+ * @returns ReactiveCardResult with single record and update function
+ *
+ * @example
+ * ```tsx
+ * function UserProfileCard({ userId }: { userId: string }) {
+ *   const {
+ *     data,
+ *     isLoading,
+ *     update,
+ *     isUpdating,
+ *   } = useReactiveCard<User>({
+ *     collection: 'users',
+ *     where: { id: userId },
+ *     fields: [
+ *       { key: 'name', label: 'Name' },
+ *       { key: 'email', label: 'Email' },
+ *       { key: 'role', label: 'Role', format: 'badge' },
+ *     ],
+ *   })
+ *
+ *   if (isLoading) return <Spinner />
+ *   if (!data) return <Empty message="User not found" />
+ *
+ *   return (
+ *     <Card
+ *       title={data.name}
+ *       subtitle={data.email}
+ *       pairs={[
+ *         { key: 'Role', value: data.role },
+ *         { key: 'Status', value: data.status },
+ *       ]}
+ *       actions={[
+ *         {
+ *           label: isUpdating ? 'Saving...' : 'Edit',
+ *           action: () => update({ status: 'updated' }),
+ *         },
+ *       ]}
+ *     />
+ *   )
+ * }
+ * ```
+ */
+export function useReactiveCard<T extends Record<string, any>>(
+  options: ReactiveCardOptions<T>
+): ReactiveCardResult<T> {
+  const db = useDBContext()
+  const { collection: collectionName, where, optimistic = true } = options
+
+  const [data, setData] = useState<T | null>(null)
+  const [isLoading, setIsLoading] = useState(true)
+  const [error, setError] = useState<Error | undefined>(undefined)
+  const [isUpdating, setIsUpdating] = useState(false)
+
+  const rollbackRef = useRef<T | null>(null)
+
+  const collection = db.collections[collectionName] as Collection<T> | undefined
+
+  const fetchData = useCallback(async () => {
+    if (!collection) {
+      setError(new Error(`Collection '${collectionName}' not found`))
+      setIsLoading(false)
+      return
+    }
+
+    try {
+      const result = await collection.findOne(where as Partial<T>)
+      setData(result)
+      setError(undefined)
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error(String(err)))
+    } finally {
+      setIsLoading(false)
+    }
+  }, [collection, collectionName, JSON.stringify(where)])
+
+  // Initial fetch
+  useEffect(() => {
+    fetchData()
+  }, [fetchData])
+
+  // Subscribe to changes
+  useEffect(() => {
+    if (!collection) return
+
+    const unsubscribe = collection.subscribe((allData: T[]) => {
+      // Find matching record
+      const found = allData.find(doc =>
+        Object.entries(where).every(([key, val]) => doc[key as keyof T] === val)
+      )
+      setData(found ?? null)
+    })
+
+    return unsubscribe
+  }, [collection, JSON.stringify(where)])
+
+  const update = useCallback(async (updates: Partial<T>) => {
+    if (!collection || !data) {
+      throw new Error('Cannot update: no data or collection')
+    }
+
+    setIsUpdating(true)
+
+    if (optimistic) {
+      rollbackRef.current = data
+      setData(prev => prev ? { ...prev, ...updates } : null)
+    }
+
+    try {
+      await collection.update(where as Partial<T>, updates)
+    } catch (err) {
+      if (optimistic && rollbackRef.current) {
+        setData(rollbackRef.current)
+      }
+      throw err
+    } finally {
+      setIsUpdating(false)
+    }
+  }, [collection, data, where, optimistic])
+
+  return {
+    data,
+    isLoading,
+    error,
+    refetch: fetchData,
+    update,
+    isUpdating,
+  }
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Check if a value matches a field filter
+ */
+function matchesFilter<T>(value: T, filter: any): boolean {
+  if (filter === null || filter === undefined || typeof filter !== 'object') {
+    return value === filter
+  }
+
+  const ops = filter as Record<string, any>
+
+  if ('$eq' in ops && value !== ops.$eq) return false
+  if ('$ne' in ops && value === ops.$ne) return false
+  if ('$gt' in ops && !(value > ops.$gt)) return false
+  if ('$gte' in ops && !(value >= ops.$gte)) return false
+  if ('$lt' in ops && !(value < ops.$lt)) return false
+  if ('$lte' in ops && !(value <= ops.$lte)) return false
+  if ('$in' in ops && !ops.$in.includes(value)) return false
+  if ('$nin' in ops && ops.$nin.includes(value)) return false
+
+  return true
+}
+
+/**
+ * Check if a document matches a where clause
+ */
+function matchesWhere<T extends Record<string, any>>(doc: T, where: WhereClause<T>): boolean {
+  if ('$or' in where && where.$or) {
+    const orClauses = where.$or as WhereClause<T>[]
+    const matchesOr = orClauses.some(clause => matchesWhere(doc, clause))
+    if (!matchesOr) return false
+
+    const { $or, ...rest } = where
+    if (Object.keys(rest).length === 0) return true
+    return matchesWhere(doc, rest as WhereClause<T>)
+  }
+
+  for (const [key, filter] of Object.entries(where)) {
+    if (key === '$or') continue
+    const value = doc[key]
+    if (!matchesFilter(value, filter)) {
+      return false
+    }
+  }
+
+  return true
+}
+
+/**
+ * Sort documents by orderBy clause
+ */
+function sortDocuments<T extends Record<string, any>>(
+  docs: T[],
+  orderBy: OrderByClause<T> | OrderByClause<T>[]
+): T[] {
+  const orderClauses = Array.isArray(orderBy) ? orderBy : [orderBy]
+
+  return [...docs].sort((a, b) => {
+    for (const clause of orderClauses) {
+      const [field, direction] = Object.entries(clause)[0]
+      const aVal = a[field]
+      const bVal = b[field]
+
+      if (aVal === null || aVal === undefined) {
+        if (bVal !== null && bVal !== undefined) return 1
+        continue
+      }
+      if (bVal === null || bVal === undefined) return -1
+
+      let comparison = 0
+      if (typeof aVal === 'string') {
+        comparison = aVal.localeCompare(bVal)
+      } else if (typeof aVal === 'number') {
+        comparison = aVal - bVal
+      } else if (aVal instanceof Date) {
+        comparison = aVal.getTime() - bVal.getTime()
+      } else {
+        comparison = String(aVal).localeCompare(String(bVal))
+      }
+
+      if (comparison !== 0) {
+        return direction === 'desc' ? -comparison : comparison
+      }
+    }
+    return 0
+  })
+}