feat(examples): integrate TanStack DB for client-side data management

- Replace server functions with TanStack DB collections and live queries
- Add @tanstack/react-db, @tanstack/query-db-collection, and related packages
- Implement disputes, orders, and settlements collections with Zod validation
- Create useLiveQuery hooks for reactive data filtering and searching
- Update components to use client-side collections instead of server functions

Author: denis-shvets

examples/ts-react-search/package.json

@@ -14,12 +14,16 @@
     "@tanstack/ai": "workspace:*",
     "@tanstack/ai-openai": "workspace:*",
     "@tanstack/ai-react": "workspace:*",
+    "@tanstack/query-db-collection": "^1.0.6",
+    "@tanstack/react-db": "^0.1.55",
     "@tanstack/react-devtools": "^0.8.2",
+    "@tanstack/react-query": "^5.90.12",
     "@tanstack/react-router": "^1.139.7",
     "@tanstack/react-router-devtools": "^1.139.7",
     "@tanstack/react-router-ssr-query": "^1.139.7",
     "@tanstack/react-start": "^1.139.8",
     "@tanstack/router-plugin": "^1.139.7",
+    "@tanstack/zod-adapter": "^1.140.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.555.0",

examples/ts-react-search/src/components/FilterSelect.tsx

@@ -0,0 +1,46 @@
+import { Label } from '@/components/ui/label'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/ui/select'
+import { ALL_OPTION } from '@/constants'
+
+type FilterSelectProps = {
+  id: string
+  label: string
+  value: string
+  onChange: (value: string) => void
+  options: Array<[string, string]>
+}
+
+function FilterSelect({
+  id,
+  label,
+  value,
+  onChange,
+  options,
+}: FilterSelectProps) {
+  return (
+    <div className="flex min-w-0 flex-col gap-2">
+      <Label htmlFor={id}>{label}</Label>
+      <Select name="status" value={value || ''} onValueChange={onChange}>
+        <SelectTrigger id={id}>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value={ALL_OPTION}>All</SelectItem>
+          {options.map(([key, label]) => (
+            <SelectItem key={key} value={key}>
+              {label}
+            </SelectItem>
+          ))}
+        </SelectContent>
+      </Select>
+    </div>
+  )
+}
+
+export default FilterSelect

examples/ts-react-search/src/components/Spinner.tsx

@@ -0,0 +1,7 @@
+import { LoaderCircleIcon } from 'lucide-react'
+
+function Spinner() {
+  return <LoaderCircleIcon className="animate-spin size-4 m-auto" />
+}
+
+export default Spinner

examples/ts-react-search/src/constants.ts

@@ -0,0 +1 @@
+export const ALL_OPTION = 'ALL'

examples/ts-react-search/src/features/disputes/DisputesFilters.tsx

@@ -2,18 +2,17 @@
 
 import { useState } from 'react'
 import { useNavigate } from '@tanstack/react-router'
-import { DISPUTE_REASON_MAP, DISPUTE_STATUS_MAP } from './constants'
+import {
+  DISPUTE_REASON_MAP,
+  DISPUTE_STATUS_MAP,
+  disputesSearchSchema,
+} from './constants'
+import type { FormEvent } from 'react'
 import type { DisputesSearch } from './types'
-import { Label } from '@/components/ui/label'
 import { DatePicker } from '@/components/ui/date-picker'
 import { Button } from '@/components/ui/button'
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-} from '@/components/ui/select'
+import { ALL_OPTION } from '@/constants'
+import FilterSelect from '@/components/FilterSelect'
 
 type DisputesFiltersProps = {
   search: DisputesSearch
@@ -23,87 +22,58 @@ function DisputesFilters({ search }: DisputesFiltersProps) {
   const navigate = useNavigate()
 
   const [pendingStatus, setPendingStatus] = useState<string>(
-    search.status || 'ALL',
+    search.status || ALL_OPTION,
   )
   const [pendingReason, setPendingReason] = useState<string>(
-    search.reason || 'ALL',
+    search.reason || ALL_OPTION,
   )
   const [pendingFrom, setPendingFrom] = useState<string | undefined>(
     search.from,
   )
   const [pendingTo, setPendingTo] = useState<string | undefined>(search.to)
 
-  function handleSubmit(event: React.FormEvent<HTMLFormElement>) {
+  async function handleSubmit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault()
 
-    navigate({
+    await navigate({
       to: '/disputes',
-      search: {
-        status: pendingStatus === 'ALL' ? undefined : pendingStatus,
-        reason: pendingReason === 'ALL' ? undefined : pendingReason,
+      search: disputesSearchSchema.parse({
+        status: pendingStatus === ALL_OPTION ? undefined : pendingStatus,
+        reason: pendingReason === ALL_OPTION ? undefined : pendingReason,
         from: pendingFrom === '' ? undefined : pendingFrom,
         to: pendingTo === '' ? undefined : pendingTo,
-      },
+      }),
     })
   }
 
-  function handleClear() {
-    setPendingStatus('ALL')
-    setPendingReason('ALL')
+  async function handleClear() {
+    setPendingStatus(ALL_OPTION)
+    setPendingReason(ALL_OPTION)
     setPendingFrom(undefined)
     setPendingTo(undefined)
-    navigate({ to: '/disputes' })
+
+    await navigate({ to: '/disputes', search: disputesSearchSchema.parse({}) })
   }
 
   return (
     <form
       className="grid gap-4 lg:grid-cols-[repeat(4,minmax(0,1fr))_auto] px-6"
       onSubmit={handleSubmit}
     >
-      <div className="flex min-w-0 flex-col gap-2">
-        <Label htmlFor="status">Status</Label>
-        <Select
-          name="status"
-          value={pendingStatus || ''}
-          onValueChange={setPendingStatus}
-        >
-          <SelectTrigger id="status">
-            <SelectValue />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value="ALL">All</SelectItem>
-            {Object.entries(DISPUTE_STATUS_MAP).map(
-              ([statusKey, statusLabel]) => (
-                <SelectItem key={statusKey} value={statusKey}>
-                  {statusLabel}
-                </SelectItem>
-              ),
-            )}
-          </SelectContent>
-        </Select>
-      </div>
-      <div className="flex min-w-0 flex-col gap-2">
-        <Label htmlFor="reason">Reason</Label>
-        <Select
-          name="reason"
-          value={pendingReason || ''}
-          onValueChange={setPendingReason}
-        >
-          <SelectTrigger id="reason">
-            <SelectValue />
-          </SelectTrigger>
-          <SelectContent>
-            <SelectItem value="ALL">All</SelectItem>
-            {Object.entries(DISPUTE_REASON_MAP).map(
-              ([reasonKey, reasonLabel]) => (
-                <SelectItem key={reasonKey} value={reasonKey}>
-                  {reasonLabel}
-                </SelectItem>
-              ),
-            )}
-          </SelectContent>
-        </Select>
-      </div>
+      <FilterSelect
+        id="status"
+        label="Status"
+        value={pendingStatus}
+        onChange={setPendingStatus}
+        options={Object.entries(DISPUTE_STATUS_MAP)}
+      />
+      <FilterSelect
+        id="resason"
+        label="Reason"
+        value={pendingReason}
+        onChange={setPendingReason}
+        options={Object.entries(DISPUTE_REASON_MAP)}
+      />
       <DatePicker
         label="From"
         value={pendingFrom}

examples/ts-react-search/src/features/disputes/DisputesManager.tsx

@@ -0,0 +1,27 @@
+'use client'
+
+import useDisputesQuery from './useDisputesQuery'
+import DisputesTable from './DisputesTable'
+import disputesCollection from './disputesCollection'
+import type { DisputesSearch } from './types'
+import TableSummary from '@/components/TableSummary'
+
+type DisputesManagerProps = {
+  search: DisputesSearch
+}
+
+function DisputesManager({ search }: DisputesManagerProps) {
+  const { data: disputes } = useDisputesQuery(search)
+
+  return (
+    <>
+      <DisputesTable disputes={disputes} />
+      <TableSummary
+        totalCount={disputesCollection.toArray.length}
+        resultCount={disputes.length}
+      />
+    </>
+  )
+}
+
+export default DisputesManager

examples/ts-react-search/src/features/disputes/constants.ts

@@ -1,24 +1,50 @@
 import { z } from 'zod'
+import { fallback } from '@tanstack/zod-adapter'
+import type { DisputeReason, DisputeStatus } from './types'
 
-export const DISPUTE_STATUS_MAP = {
+export const DISPUTE_STATUSES = [
+  'LOST',
+  'RESPONSE_REQUIRED',
+  'UNDER_REVIEW',
+  'WON',
+] as const
+
+export const DISPUTE_STATUS_MAP: Record<DisputeStatus, string> = {
   LOST: 'Lost',
   RESPONSE_REQUIRED: 'Response required',
   UNDER_REVIEW: 'Under review',
   WON: 'Won',
-} as const
+}
+
+export const DISPUTE_REASONS = [
+  'FAULTY_GOODS',
+  'GOODS_NOT_RECEIVED',
+  'HIGH_RISK_ORDER',
+  'INCORRECT_INVOICE',
+  'RETURN',
+  'UNAUTHORIZED_PURCHASE',
+] as const
 
-export const DISPUTE_REASON_MAP = {
+export const DISPUTE_REASON_MAP: Record<DisputeReason, string> = {
   FAULTY_GOODS: 'Faulty goods',
   GOODS_NOT_RECEIVED: 'Goods not received',
   HIGH_RISK_ORDER: 'High risk order',
   INCORRECT_INVOICE: 'Incorrect invoice',
   RETURN: 'Return',
   UNAUTHORIZED_PURCHASE: 'Unauthorized purchase',
-} as const
+}
+
+export const disputeSchema = z.object({
+  id: z.string(),
+  status: z.enum(DISPUTE_STATUSES),
+  reason: z.enum(DISPUTE_REASONS),
+  from: z.iso.datetime(),
+  to: z.iso.datetime(),
+})
 
 export const disputesSearchSchema = z.object({
-  status: z.enum(Object.keys(DISPUTE_STATUS_MAP)).optional(),
-  reason: z.enum(Object.keys(DISPUTE_REASON_MAP)).optional(),
-  from: z.string().optional(),
-  to: z.string().optional(),
+  status: fallback(z.enum(DISPUTE_STATUSES).optional(), undefined),
+  reason: fallback(z.enum(DISPUTE_REASONS).optional(), undefined),
+  from: fallback(z.string().optional(), undefined),
+  to: fallback(z.string().optional(), undefined),
 })

examples/ts-react-search/src/features/disputes/data.ts

@@ -1,74 +1,73 @@
-import { DISPUTE_REASON_MAP, DISPUTE_STATUS_MAP } from './constants'
 import type { Dispute } from './types'
 
 export const DISPUTES: Array<Dispute> = [
   {
     id: 'dis_2001',
-    status: DISPUTE_STATUS_MAP.LOST,
-    reason: DISPUTE_REASON_MAP.RETURN,
+    status: 'LOST',
+    reason: 'RETURN',
     from: '2025-01-10T09:00:00Z',
     to: '2025-01-15T18:00:00Z',
   },
   {
     id: 'dis_2002',
-    status: DISPUTE_STATUS_MAP.WON,
-    reason: DISPUTE_REASON_MAP.INCORRECT_INVOICE,
+    status: 'WON',
+    reason: 'INCORRECT_INVOICE',
     from: '2025-02-05T10:30:00Z',
     to: '2025-02-12T14:00:00Z',
   },
   {
     id: 'dis_2003',
-    status: DISPUTE_STATUS_MAP.RESPONSE_REQUIRED,
-    reason: DISPUTE_REASON_MAP.HIGH_RISK_ORDER,
+    status: 'RESPONSE_REQUIRED',
+    reason: 'HIGH_RISK_ORDER',
     from: '2025-03-18T08:15:00Z',
     to: '2025-03-25T17:00:00Z',
   },
   {
     id: 'dis_2004',
-    status: DISPUTE_STATUS_MAP.UNDER_REVIEW,
-    reason: DISPUTE_REASON_MAP.GOODS_NOT_RECEIVED,
+    status: 'UNDER_REVIEW',
+    reason: 'GOODS_NOT_RECEIVED',
     from: '2025-04-12T11:00:00Z',
     to: '2025-04-18T16:30:00Z',
   },
   {
     id: 'dis_2005',
-    status: DISPUTE_STATUS_MAP.UNDER_REVIEW,
-    reason: DISPUTE_REASON_MAP.UNAUTHORIZED_PURCHASE,
+    status: 'UNDER_REVIEW',
+    reason: 'UNAUTHORIZED_PURCHASE',
     from: '2025-05-08T09:45:00Z',
     to: '2025-05-15T15:00:00Z',
   },
   {
     id: 'dis_2006',
-    status: DISPUTE_STATUS_MAP.LOST,
-    reason: DISPUTE_REASON_MAP.FAULTY_GOODS,
+    status: 'LOST',
+    reason: 'FAULTY_GOODS',
     from: '2025-06-02T13:20:00Z',
     to: '2025-06-08T10:00:00Z',
   },
   {
     id: 'dis_2007',
-    status: DISPUTE_STATUS_MAP.RESPONSE_REQUIRED,
-    reason: DISPUTE_REASON_MAP.UNAUTHORIZED_PURCHASE,
+    status: 'RESPONSE_REQUIRED',
+    reason: 'UNAUTHORIZED_PURCHASE',
     from: '2025-07-20T14:50:00Z',
     to: '2025-07-28T09:30:00Z',
   },
   {
     id: 'dis_2008',
-    status: DISPUTE_STATUS_MAP.UNDER_REVIEW,
-    reason: DISPUTE_REASON_MAP.RETURN,
+    status: 'UNDER_REVIEW',
+    reason: 'RETURN',
     from: '2025-08-14T08:00:00Z',
     to: '2025-08-22T17:30:00Z',
   },
   {
     id: 'dis_2009',
-    status: DISPUTE_STATUS_MAP.WON,
-    reason: DISPUTE_REASON_MAP.GOODS_NOT_RECEIVED,
+    status: 'WON',
+    reason: 'GOODS_NOT_RECEIVED',
     from: '2025-09-09T10:10:00Z',
     to: '2025-09-15T16:00:00Z',
   },
   {
     id: 'dis_2010',
-    status: DISPUTE_STATUS_MAP.UNDER_REVIEW,
-    reason: DISPUTE_REASON_MAP.HIGH_RISK_ORDER,
+    status: 'UNDER_REVIEW',
+    reason: 'HIGH_RISK_ORDER',
     from: '2025-10-01T15:00:00Z',
     to: '2025-10-10T11:00:00Z',
   },