@asteby/metacore-runtime-react 23.1.0 → 23.3.0

package/src/dynamic-kanban.tsx

@@ -85,6 +85,7 @@ import {
     summarizeFilterValues,
     translateOptionLabels,
 } from './filter-chips'
+import { dedupeById, useInfiniteScrollSentinel } from './use-infinite-scroll'
 import { useMetadataCache } from './metadata-cache'
 import { ActivityValueRenderer } from './activity-value-renderer'
 import { DynamicIcon } from './dynamic-icon'
@@ -213,6 +214,30 @@ export function applyOptimisticMove(
     return next
 }
 
+/**
+ * Returns a NEW per-lane pagination map with the server totals adjusted for a
+ * card moving `fromStage` → `toStage`: the source loses one, the destination
+ * gains one. Lanes whose `total` is still unknown (`null`, not yet topped up)
+ * are left alone. Pure — backs the optimistic drag so a partial lane's
+ * `count/total` header stays truthful, and can be restored on PUT failure.
+ */
+export function applyLaneTotalsOnMove<T extends { total: number | null }>(
+    pagination: Record<string, T>,
+    fromStage: string,
+    toStage: string,
+): Record<string, T> {
+    const next = { ...pagination }
+    const bump = (key: string, delta: number) => {
+        const st = next[key]
+        if (st && st.total != null) {
+            next[key] = { ...st, total: Math.max(0, st.total + delta) }
+        }
+    }
+    bump(fromStage, -1)
+    bump(toStage, +1)
+    return next
+}
+
 /**
  * Picks the columns shown on a card: a `title` column (first searchable column,
  * else first text-ish column) and up to `maxFields` secondary columns. Excludes
@@ -337,6 +362,18 @@ interface LaneFilterState {
     query?: string
 }
 
+/** Incremental pagination bookkeeping for one lane/stage. */
+interface LanePageState {
+    /** Next stage-scoped page to request. */
+    nextPage: number
+    /** Server total for the stage (from response meta), or null if unknown. */
+    total: number | null
+    /** A top-up request is in flight. */
+    loading: boolean
+    /** No more pages for this stage. */
+    done: boolean
+}
+
 export interface DynamicKanbanProps {
     /** Model key as registered on the backend (e.g. "issue"). */
     model: string
@@ -357,10 +394,16 @@ export interface DynamicKanbanProps {
      */
     onAction?: (action: string, row: any) => void
     /**
-     * Max cards fetched per lane render. Kanban shows all cards at once (no
-     * pagination UI), so it requests a single large page. Defaults to 200.
+     * Size of the INITIAL board page (one request, grouped into lanes). Each
+     * lane then tops up incrementally on scroll (see `lanePageSize`). Defaults
+     * to 50 — enough to fill the visible lanes without loading the whole board.
      */
     pageSize?: number
+    /**
+     * Page size for a lane's incremental top-up fetch (scoped by
+     * `f_<group_by>=<stage>`). Defaults to 25.
+     */
+    lanePageSize?: number
     /** IANA timezone for datetime card fields (org config). */
     timeZone?: string
     /** ISO 4217 currency for money card fields (org config). */
@@ -378,7 +421,8 @@ export function DynamicKanban({
     refreshTrigger,
     onCardClick,
     onAction,
-    pageSize = 200,
+    pageSize = 50,
+    lanePageSize = 25,
     timeZone,
     currency,
     defaultFilters,
@@ -394,6 +438,14 @@ export function DynamicKanban({
     const [records, setRecords] = useState<any[]>([])
     const [loading, setLoading] = useState(!cachedMeta)
     const [loadingData, setLoadingData] = useState(true)
+    // Per-stage incremental pagination for infinite scroll. The initial board
+    // page (grouped into lanes) is fetched once; each lane then tops up its OWN
+    // stage via `f_<group_by>=<stage>&page=n`, appended (deduped by id) into the
+    // shared `records`. `total` is the stage's server count when the response
+    // meta carries it. Reset whenever the filters/search change.
+    const [lanePagination, setLanePagination] = useState<
+        Record<string, LanePageState>
+    >({})
 
     // Active drag card id (for the DragOverlay + drop-zone highlighting).
     const [activeId, setActiveId] = useState<string | null>(null)
@@ -449,7 +501,10 @@ export function DynamicKanban({
         clearAll,
     } = useDynamicFilters(metadata, { defaultFilters, model, endpoint })
 
-    // ---- records fetch (same path as DynamicTable, single large page) ----
+    // ---- initial board page (one request, grouped into lanes) ----
+    // Resets the per-lane pagination so every lane restarts its incremental
+    // top-up from scratch — called on mount, refresh, and any filter/search
+    // change (fetchData's identity changes with filterParams).
     const fetchData = useCallback(async () => {
         if (!metadata) return
         setLoadingData(true)
@@ -463,8 +518,67 @@ export function DynamicKanban({
         } finally {
             setLoadingData(false)
         }
+        setLanePagination({})
     }, [api, endpoint, model, metadata, pageSize, filterParams])
 
+    // Load the next page for ONE lane/stage and append it (deduped by id) into
+    // the shared records. Scoped by `f_<group_by>=<stage>` on top of the active
+    // filterParams (the stage scope wins over any global group_by filter).
+    const groupByKey = metadata?.group_by || ''
+    const loadMoreLane = useCallback(
+        async (stageKey: string) => {
+            if (!metadata || !groupByKey) return
+            const current = lanePagination[stageKey]
+            if (current?.loading || current?.done) return
+            const nextPage = current?.nextPage ?? 1
+            setLanePagination((p) => ({
+                ...p,
+                [stageKey]: {
+                    nextPage,
+                    total: current?.total ?? null,
+                    loading: true,
+                    done: false,
+                },
+            }))
+            try {
+                const res = (await api.get(endpoint || `/data/${model}`, {
+                    params: {
+                        ...filterParams,
+                        page: nextPage,
+                        per_page: lanePageSize,
+                        [`f_${groupByKey}`]: stageKey,
+                    },
+                })) as { data: ApiResponse<any[]> & { meta?: any } }
+                const rows = res.data.success ? res.data.data || [] : []
+                const total =
+                    res.data.meta?.total ?? res.data.meta?.count ?? null
+                setRecords((prev) => dedupeById(prev, rows))
+                setLanePagination((p) => ({
+                    ...p,
+                    [stageKey]: {
+                        nextPage: nextPage + 1,
+                        total,
+                        loading: false,
+                        // Exhausted when the server returned a short page.
+                        done: rows.length < lanePageSize,
+                    },
+                }))
+            } catch (err) {
+                console.error(`Error al cargar más tarjetas de ${stageKey}`, err)
+                setLanePagination((p) => ({
+                    ...p,
+                    [stageKey]: {
+                        nextPage,
+                        total: current?.total ?? null,
+                        loading: false,
+                        done: false,
+                    },
+                }))
+            }
+        },
+        [api, endpoint, model, metadata, groupByKey, filterParams, lanePageSize, lanePagination],
+    )
+
     // Refetch when metadata resolves, on an explicit refresh, or when the
     // filters change. `fetchData` is stable while `filterParams` is unchanged
     // (both memoized), so this only re-runs on real input changes. Debounced so
@@ -566,7 +680,6 @@ export function DynamicKanban({
         () => (metadata ? deriveStages(metadata) : []),
         [metadata],
     )
-    const groupByKey = metadata?.group_by || ''
     const transitions = metadata?.transitions
 
     const grouped = useMemo(
@@ -651,11 +764,16 @@ export function DynamicKanban({
 
             // OPTIMISTIC: move the card in local state immediately.
             const prevRecords = records
+            const prevPagination = lanePagination
             setRecords((rs) =>
                 rs.map((r) =>
                     String(r.id) === cardId ? { ...r, [groupByKey]: destStage } : r,
                 ),
             )
+            // Keep the server totals consistent with the moved card so a lane's
+            // `count/total` header stays truthful with partial lanes: one leaves
+            // the source stage, one joins the destination.
+            setLanePagination((p) => applyLaneTotalsOnMove(p, srcStage, destStage))
 
             try {
                 const base = endpoint || `/data/${model}`
@@ -672,6 +790,7 @@ export function DynamicKanban({
             } catch (err: any) {
                 // REVERT + toast on failure.
                 setRecords(prevRecords)
+                setLanePagination(prevPagination)
                 toast.error(
                     t('kanban.moveFailed', {
                         defaultValue: 'No se pudo mover la tarjeta',
@@ -682,7 +801,7 @@ export function DynamicKanban({
                 )
             }
         },
-        [api, endpoint, groupByKey, model, records, stageOfCard, t, transitions],
+        [api, endpoint, groupByKey, lanePagination, model, records, stageOfCard, t, transitions],
     )
 
     if (loading) {
@@ -855,12 +974,21 @@ export function DynamicKanban({
                         !activeId ||
                         stage.key === activeStage ||
                         isTransitionAllowed(transitions, activeStage, stage.key)
+                    // Infinite scroll is per declared stage; the synthetic
+                    // "unassigned" lane can't be stage-scoped, so it never tops up.
+                    const laneState = lanePagination[stage.key]
+                    const isUnassigned = stage.key === UNASSIGNED_LANE
+                    const laneHasMore = !isUnassigned && !laneState?.done
                     return (
                         <KanbanLane
                             key={stage.key}
                             stage={stage}
                             count={cards.length}
                             totalCount={allCards.length}
+                            serverTotal={laneState?.total ?? null}
+                            hasMore={laneHasMore}
+                            loadingMore={!!laneState?.loading}
+                            onLoadMore={() => loadMoreLane(stage.key)}
                             filterFields={filterFields}
                             laneFilter={laneFilter}
                             onFunnelChange={(f) =>
@@ -1029,6 +1157,14 @@ interface KanbanLaneProps {
     stage: StageMeta
     count: number
     totalCount: number
+    /** Server-reported total for the stage (from response meta), or null. */
+    serverTotal: number | null
+    /** More server pages available for this stage. */
+    hasMore: boolean
+    /** A top-up request for this stage is in flight. */
+    loadingMore: boolean
+    /** Request the next page for this stage. */
+    onLoadMore: () => void
     filterFields: LaneFilterField[]
     laneFilter: LaneFilterState | undefined
     onFunnelChange: (filter: LaneFunnelValue | null) => void
@@ -1043,6 +1179,10 @@ function KanbanLane({
     stage,
     count,
     totalCount,
+    serverTotal,
+    hasMore,
+    loadingMore,
+    onLoadMore,
     filterFields,
     laneFilter,
     onFunnelChange,
@@ -1054,6 +1194,12 @@ function KanbanLane({
 }: KanbanLaneProps) {
     const { t } = useTranslation()
     const { setNodeRef, isOver } = useDroppable({ id: stage.key, disabled })
+    // Infinite scroll: the sentinel lives at the bottom of the lane's own scroll
+    // container; a load in flight or an exhausted stage disables it.
+    const { rootRef, sentinelRef } = useInfiniteScrollSentinel({
+        onLoadMore,
+        disabled: !hasMore || loadingMore,
+    })
     const headerStyle = generateBadgeStyles(stage.color || optionColor(stage.key), {
         isDark,
     })
@@ -1111,7 +1257,11 @@ function KanbanLane({
                         {t(stage.label, { defaultValue: stage.label })}
                     </Badge>
                     <span className="text-xs font-medium tabular-nums text-muted-foreground">
-                        {laneActive ? `${count}/${totalCount}` : count}
+                        {laneActive
+                            ? `${count}/${totalCount}`
+                            : serverTotal != null
+                              ? `${count}/${serverTotal}`
+                              : count}
                     </span>
                 </div>
                 {/* Lane actions — always visible in muted (a hidden hover-reveal
@@ -1189,8 +1339,18 @@ function KanbanLane({
                 text wraps freely (no line-clamp) the cards grew past the lane
                 and spilled out of the stage. A normal `overflow-y-auto` block
                 constrains every card to the lane width so text wraps inside it. */}
-            <div className="flex min-h-[55vh] max-h-[70vh] min-w-0 flex-col gap-2 overflow-y-auto px-2 pb-3">
+            <div
+                ref={rootRef}
+                className="flex min-h-[55vh] max-h-[70vh] min-w-0 flex-col gap-2 overflow-y-auto px-2 pb-3"
+            >
                 {children}
+                {loadingMore && (
+                    <Skeleton className="h-16 w-full shrink-0" data-testid="lane-loading-more" />
+                )}
+                {/* Sentinel: entering view triggers the next stage page. */}
+                {hasMore && (
+                    <div ref={sentinelRef} className="h-1 w-full shrink-0" aria-hidden />
+                )}
             </div>
         </div>
     )

package/src/dynamic-row-actions.tsx

@@ -139,11 +139,13 @@ export function useDynamicRowActions({
         try {
             const deleteEndpoint = endpoint ? `${endpoint}/${rowToDelete.id}` : `/data/${model}/${rowToDelete.id}`
             const res = await api.delete(deleteEndpoint)
-            if (res.data.success) { toast.success(res.data.message || 'Eliminado correctamente'); onRefresh() }
-            else toast.error(res.data.message || 'Error al eliminar')
+            // CRUD estándar: no usar res.data.message (el endpoint dinámico
+            // devuelve texto en inglés que se filtraría al toast). String localizado.
+            if (res.data.success) { toast.success(t('dynamic.delete_success', { defaultValue: 'Registro eliminado correctamente' })); onRefresh() }
+            else toast.error(t('dynamic.delete_error', { defaultValue: 'No se pudo eliminar el registro' }))
         } catch (error) {
             console.error('Error al eliminar', error)
-            toast.error('Error al eliminar el registro')
+            toast.error(t('dynamic.delete_error', { defaultValue: 'No se pudo eliminar el registro' }))
         } finally {
             setIsDeleting(false)
             setRowToDelete(null)

package/src/dynamic-table.tsx

@@ -68,6 +68,7 @@ import type { ColumnFilterConfig, GetDynamicColumns } from './dynamic-columns-sh
 import { defaultGetDynamicColumns, DATE_CELL_TYPES, aggregateOf, formatAggregateTotal } from './dynamic-columns'
 import { useFacetLoaders, isLongTextColumn } from './use-facet-loaders'
 import { FilterChipsRow, translateOptionLabels, type FilterChipField } from './filter-chips'
+import { dedupeById, useInfiniteScrollSentinel } from './use-infinite-scroll'
 import { OptionsContext } from './options-context'
 import type { TableMetadata, ApiResponse } from './types'
 import { getSearchableColumnKeys } from './column-visibility'
@@ -112,6 +113,14 @@ export interface DynamicTableProps {
      * an explicit per-column currency. Optional — defaults to 'USD'.
      */
     currency?: string
+    /**
+     * Opt into infinite scroll: instead of the classic pager, rows accumulate as
+     * the user scrolls (a sentinel at the bottom fetches + appends the next
+     * page, deduped by id, respecting the active filters/search). Changing any
+     * filter/sort/search resets to page 1. Default false — existing hosts keep
+     * the classic pagination untouched.
+     */
+    infiniteScroll?: boolean
 }
 
 export function DynamicTable({
@@ -127,6 +136,7 @@ export function DynamicTable({
     getDynamicColumns = defaultGetDynamicColumns,
     timeZone,
     currency,
+    infiniteScroll = false,
 }: DynamicTableProps) {
     const { t, i18n } = useTranslation()
     const api = useApi()
@@ -144,6 +154,10 @@ export function DynamicTable({
     const [footerTotals, setFooterTotals] = useState<Record<string, any>>({})
     const [loading, setLoading] = useState(!cachedMeta)
     const [loadingData, setLoadingData] = useState(true)
+    // Infinite-scroll: a top-up page is in flight (distinct from the initial
+    // page load so only a small bottom spinner shows, not the whole-table one).
+    const [loadingMore, setLoadingMore] = useState(false)
+    const infPageRef = useRef(1)
     const [optionsMap, setOptionsMap] = useState<Map<string, any[]>>(new Map())
 
     const [exportOpen, setExportOpen] = useState(false)
@@ -472,9 +486,69 @@ export function DynamicTable({
         }
     }, [model, metadata, aggregateColumns, buildFilterParams, endpoint, currentBranch?.id, api])
 
+    // ---- infinite scroll: page fetch that REPLACES (page 1) or APPENDS ----
+    const infPageSize = 30
+    const fetchPage = useCallback(
+        async (page: number, append: boolean) => {
+            if (!metadata) return
+            if (append) setLoadingMore(true)
+            else setLoadingData(true)
+            try {
+                const params: Record<string, any> = {
+                    page,
+                    per_page: infPageSize,
+                    ...buildFilterParams(),
+                }
+                const res = (await api.get(endpoint || `/data/${model}`, {
+                    params,
+                })) as { data: ApiResponse<any[]> }
+                if (res.data.success) {
+                    const rows = res.data.data || []
+                    setData((prev) => (append ? dedupeById(prev, rows) : rows))
+                    if (res.data.meta) setRowCount(res.data.meta.total)
+                }
+            } catch (error) {
+                console.error('Error al cargar los datos', error)
+            } finally {
+                if (append) setLoadingMore(false)
+                else setLoadingData(false)
+            }
+        },
+        [metadata, buildFilterParams, endpoint, model, api, currentBranch?.id],
+    )
+
+    // Signature of everything that must reset the incremental list to page 1:
+    // the filters/search AND the sort (both live in buildFilterParams).
+    const filterSignature = useMemo(
+        () => JSON.stringify(buildFilterParams()),
+        [buildFilterParams],
+    )
+
+    const loadNextPage = useCallback(() => {
+        if (loadingMore || loadingData) return
+        if (data.length >= rowCount) return
+        infPageRef.current += 1
+        void fetchPage(infPageRef.current, true)
+    }, [loadingMore, loadingData, data.length, rowCount, fetchPage])
+
+    // Infinite-scroll sentinels. There are two scroll containers (desktop
+    // table + mobile card list) but only one is laid out at a time — the CSS
+    // `hidden`/`sm:hidden` container has no box, so its observer never fires.
+    // Each sentinel drives the SAME `loadNextPage`; its internal guards + the
+    // `disabled` flag keep concurrent/exhausted fetches from doubling up.
+    const infScrollDisabled =
+        !infiniteScroll || loadingMore || loadingData || data.length >= rowCount
+    const { rootRef: infDesktopRoot, sentinelRef: infDesktopSentinel } =
+        useInfiniteScrollSentinel({ onLoadMore: loadNextPage, disabled: infScrollDisabled })
+    const { rootRef: infMobileRoot, sentinelRef: infMobileSentinel } =
+        useInfiniteScrollSentinel({ onLoadMore: loadNextPage, disabled: infScrollDisabled })
+
     const initialFetchDone = useRef(false)
     useEffect(() => {
         if (!metadata) return
+        // Infinite mode owns its own fetching (reset-to-page-1 effect below);
+        // the classic pagination-driven path is skipped entirely.
+        if (infiniteScroll) return
         if (!initialFetchDone.current) {
             initialFetchDone.current = true
             fetchData()
@@ -486,9 +560,41 @@ export function DynamicTable({
             fetchAggregates()
         }, 300)
         return () => clearTimeout(timeoutId)
-    }, [fetchData, fetchAggregates, metadata])
+    }, [fetchData, fetchAggregates, metadata, infiniteScroll])
 
-    const handleRefresh = useCallback(() => { fetchData(); fetchAggregates() }, [fetchData, fetchAggregates])
+    // Infinite mode: (re)load page 1 on mount and whenever the filters/sort/
+    // search change (or an explicit refreshTrigger) — replacing the accumulated
+    // rows and resetting the cursor.
+    useEffect(() => {
+        if (!infiniteScroll || !metadata) return
+        infPageRef.current = 1
+        const first = !initialFetchDone.current
+        initialFetchDone.current = true
+        if (first) {
+            void fetchPage(1, false)
+            void fetchAggregates()
+            return
+        }
+        const timeoutId = setTimeout(() => {
+            void fetchPage(1, false)
+            void fetchAggregates()
+        }, 300)
+        return () => clearTimeout(timeoutId)
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [infiniteScroll, metadata, filterSignature])
+
+    const handleRefresh = useCallback(() => {
+        // Infinite mode owns its own list: refresh reloads page 1 and drops the
+        // accumulated pages (a classic fetchData would collapse it to one small
+        // pagination page). Classic mode keeps the pagination-driven refetch.
+        if (infiniteScroll) {
+            infPageRef.current = 1
+            void fetchPage(1, false)
+        } else {
+            fetchData()
+        }
+        fetchAggregates()
+    }, [infiniteScroll, fetchPage, fetchData, fetchAggregates])
 
     // Per-row action dispatch (view/edit/delete/link/custom) + its dialogs live
     // in the shared hook so DynamicKanban's card menu behaves identically.
@@ -522,8 +628,8 @@ export function DynamicTable({
         setBulkDeleteProgress(0)
         setBulkDeleteTotal(0)
         setRowSelection({})
-        if (successCount > 0) toast.success(`${successCount} registro(s) eliminado(s) correctamente`)
-        if (errorCount > 0) toast.error(`${errorCount} registro(s) no pudieron ser eliminados`)
+        if (successCount > 0) toast.success(t('dynamic.bulk_delete_success', { count: successCount, defaultValue: '{{count}} registro(s) eliminado(s) correctamente' }))
+        if (errorCount > 0) toast.error(t('dynamic.bulk_delete_error', { count: errorCount, defaultValue: '{{count}} registro(s) no pudieron ser eliminados' }))
         handleRefresh()
     }
 
@@ -838,7 +944,7 @@ export function DynamicTable({
                 {/* Desktop: classic horizontal-scroll table. Hidden on phones —
                     a 7-column table forces a wide horizontal scroll there, so we
                     render a card-per-row list instead (see MobileCards below). */}
-                <div className='hidden sm:block flex-1 min-h-0 overflow-auto border rounded-md bg-card'>
+                <div ref={infDesktopRoot} className='hidden sm:block flex-1 min-h-0 overflow-auto border rounded-md bg-card'>
                     <Table noWrapper className={cn('min-w-max w-full', aggregateColumns.length > 0 && Object.keys(footerTotals).length > 0 && 'h-full')}>
                         <TableHeader className='sticky top-0 z-10'>
                             {table.getHeaderGroups().map((headerGroup: HeaderGroup<any>) => (
@@ -954,12 +1060,25 @@ export function DynamicTable({
                             </TableFooter>
                         )}
                     </Table>
+                    {infiniteScroll && (
+                        <>
+                            {loadingMore && (
+                                <div className='p-2'>
+                                    <Skeleton className='h-8 w-full' data-testid='table-loading-more' />
+                                </div>
+                            )}
+                            {/* Sentinel stays mounted for the whole infinite-scroll
+                                session so its observer attaches once; `disabled`
+                                (no more pages / load in flight) gates the fetch. */}
+                            <div ref={infDesktopSentinel} className='h-1 w-full' aria-hidden />
+                        </>
+                    )}
                 </div>
 
                 {/* Mobile: one card per row — no horizontal scroll. Each card
                     stacks its columns as label : value pairs with the row actions
                     pinned at the bottom. */}
-                <div className='flex flex-1 min-h-0 flex-col gap-2 overflow-y-auto sm:hidden'>
+                <div ref={infMobileRoot} className='flex flex-1 min-h-0 flex-col gap-2 overflow-y-auto sm:hidden'>
                     {loadingData && data.length === 0 ? (
                         Array.from({ length: 5 }).map((_, i) => (
                             <div key={i} className='rounded-lg border bg-card p-3'>
@@ -1014,13 +1133,33 @@ export function DynamicTable({
                             <p className='text-sm text-muted-foreground'>No hay datos para mostrar en este momento.</p>
                         </div>
                     )}
+                    {infiniteScroll && (
+                        <>
+                            {loadingMore && (
+                                <Skeleton className='h-16 w-full shrink-0' data-testid='table-loading-more-mobile' />
+                            )}
+                            <div ref={infMobileSentinel} className='h-1 w-full shrink-0' aria-hidden />
+                        </>
+                    )}
                 </div>
 
                 <div className='shrink-0 pt-4'>
-                    <DataTablePagination
-                        table={table}
-                        pageSizeOptions={metadata.perPageOptions}
-                    />
+                    {infiniteScroll ? (
+                        data.length > 0 && (
+                            <p className='text-center text-xs text-muted-foreground tabular-nums'>
+                                {t('common.showingCount', {
+                                    defaultValue: '{{count}} de {{total}}',
+                                    count: data.length,
+                                    total: rowCount,
+                                })}
+                            </p>
+                        )
+                    ) : (
+                        <DataTablePagination
+                            table={table}
+                            pageSizeOptions={metadata.perPageOptions}
+                        />
+                    )}
                 </div>
             </div>
 

package/src/use-infinite-scroll.ts

@@ -0,0 +1,94 @@
+// Shared incremental-loading primitives for DynamicTable and DynamicKanban.
+//   - `dedupeById` appends a page of rows to the accumulated set, dropping any
+//     id already present (the server may re-paginate / overlap between a global
+//     page and a scoped top-up).
+//   - `useInfiniteScrollSentinel` wires an IntersectionObserver: attach
+//     `rootRef` to the scroll container and `sentinelRef` to a sentinel at its
+//     bottom; when the sentinel enters view (and it's enabled) `onLoadMore`
+//     fires. Degrades to a no-op where IntersectionObserver is unavailable
+//     (older/SSR/happy-dom) so callers still render.
+import { useEffect, useRef } from 'react'
+
+/**
+ * Returns a NEW array = `existing` followed by every row in `incoming` whose
+ * `id` is not already present. Stable on identity/order of `existing`. Pure.
+ */
+export function dedupeById<T extends { id?: any }>(
+  existing: T[],
+  incoming: T[],
+): T[] {
+  if (incoming.length === 0) return existing
+  const seen = new Set(existing.map((r) => String(r?.id)))
+  const additions: T[] = []
+  for (const row of incoming) {
+    const key = String(row?.id)
+    if (seen.has(key)) continue
+    seen.add(key)
+    additions.push(row)
+  }
+  return additions.length === 0 ? existing : [...existing, ...additions]
+}
+
+export interface UseInfiniteScrollOptions {
+  /** Fired when the sentinel scrolls into view and loading is enabled. */
+  onLoadMore: () => void
+  /** When true, the observer is inert (no more pages, or a load in flight). */
+  disabled?: boolean
+  /** Pixels of pre-fetch margin below the viewport. Default 200. */
+  rootMargin?: number
+}
+
+export interface InfiniteScrollRefs<
+  R extends HTMLElement = HTMLDivElement,
+  S extends HTMLElement = HTMLDivElement,
+> {
+  rootRef: React.RefObject<R | null>
+  sentinelRef: React.RefObject<S | null>
+}
+
+/**
+ * IntersectionObserver-backed infinite scroll. Attach `rootRef` to the
+ * scrollable container and `sentinelRef` to a small element at its bottom. The
+ * latest `onLoadMore`/`disabled` are read through a ref so the observer isn't
+ * torn down and rebuilt on every render.
+ */
+export function useInfiniteScrollSentinel<
+  R extends HTMLElement = HTMLDivElement,
+  S extends HTMLElement = HTMLDivElement,
+>({
+  onLoadMore,
+  disabled = false,
+  rootMargin = 200,
+}: UseInfiniteScrollOptions): InfiniteScrollRefs<R, S> {
+  const rootRef = useRef<R | null>(null)
+  const sentinelRef = useRef<S | null>(null)
+  const cb = useRef(onLoadMore)
+  const disabledRef = useRef(disabled)
+  cb.current = onLoadMore
+  disabledRef.current = disabled
+
+  useEffect(() => {
+    const sentinel = sentinelRef.current
+    if (
+      !sentinel ||
+      typeof IntersectionObserver === 'undefined'
+    ) {
+      return
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting && !disabledRef.current) {
+            cb.current()
+          }
+        }
+      },
+      { root: rootRef.current ?? null, rootMargin: `0px 0px ${rootMargin}px 0px` },
+    )
+    observer.observe(sentinel)
+    return () => observer.disconnect()
+    // Re-create only when the margin changes; onLoadMore/disabled are read live.
+  }, [rootMargin])
+
+  return { rootRef, sentinelRef }
+}