feat: added a scroll pagination hook / component (to refactor).

Author: Blankeos

src/components/scroll-pagination-observer.tsx

@@ -0,0 +1,97 @@
+import { useIntersection } from "bagon-hooks"
+import {
+  type Accessor,
+  createEffect,
+  createMemo,
+  createSignal,
+  Match,
+  on,
+  Show,
+  Switch,
+  type VoidProps,
+} from "solid-js"
+import { IconLoading } from "@/assets/icons"
+import { cn } from "@/utils/cn"
+
+// ===========================================================================
+// HOOK
+// ===========================================================================
+interface UseScrollPaginationOptions {
+  onLoadMore: () => void
+  isLoading: boolean
+  hasMore: boolean
+  threshold?: number
+}
+
+export type ScrollPaginationState = "idle" | "loading" | "end"
+
+export function useScrollPagination(params: Accessor<UseScrollPaginationOptions>) {
+  const [_containerRef, setContainerRef] = createSignal<HTMLElement>()
+  const { ref, entry } = useIntersection({
+    root: _containerRef(),
+    threshold: params().threshold ?? 0.75,
+  })
+
+  createEffect(
+    // Strictly only trigger on intersection. Very hard bug I encountered was changes in isLoading/hasMore are triggering onLoadMore no matter what.
+    on([entry], () => {
+      const el = entry()
+      if (el?.isIntersecting && !params().isLoading && params().hasMore) {
+        params().onLoadMore()
+      }
+    })
+  )
+
+  const loadTriggerState = createMemo(() => {
+    if (params().isLoading) return "loading"
+    if (!params().hasMore) return "end"
+    return "idle"
+  })
+
+  return {
+    /** No need to assign since it's viewport by default. */
+    scrollContainerRef: setContainerRef,
+    loadTriggerRef: ref,
+    loadTriggerState,
+    /** For debugging */
+    _entry: entry,
+  }
+}
+
+// ===========================================================================
+// COMPONENT
+// ===========================================================================
+
+interface ScrollPaginationObserverProps {
+  ref: (element: any) => void
+  state: Accessor<ScrollPaginationState>
+  class?: string
+}
+/**
+ * Usage: (Recommended TanStack)
+ *
+ * const { loadTriggerRef, loadTriggerState } = useScrollPagination({
+ *   onLoadMore: () => infiniteQuery.fetchNextPage()
+ *   hasMore: infiniteQuery.hasNextPage,
+ *   isLoading: infiniteQuery.isLoading
+ * })
+ *
+ * <ScrollPaginationObserver ref={loadTriggerRef} state={loadTriggerState} />
+ */
+export function ScrollPaginationObserver(props: VoidProps<ScrollPaginationObserverProps>) {
+  return (
+    <div
+      class={cn("flex h-20 items-center justify-center text-gray-500", props.class)}
+      ref={props.ref}
+    >
+      <Show when={props.state() !== "idle"}>
+        <Switch>
+          <Match when={props.state() === "loading"}>
+            <IconLoading class="size-8" />
+          </Match>
+          <Match when={props.state() === "end"}>You've reached the end.</Match>
+        </Switch>
+      </Show>
+    </div>
+  )
+}

src/pages/_components/+Page.tsx

@@ -39,6 +39,7 @@ import { useThemeContext } from "@/contexts/theme.context"
 import { Tippy } from "@/lib/solid-tippy"
 import { cn } from "@/utils/cn"
 import { DragExample } from "./drag-example"
+import { ScrollPaginationExample } from "./scroll-pagination-example"
 
 export default function ComponentsPage() {
   return (
@@ -916,6 +917,10 @@ export default function ComponentsPage() {
         </span>
         <DragExample />
       </ComponentCard>
+
+      <ComponentCard label="Scroll Pagination">
+        <ScrollPaginationExample />
+      </ComponentCard>
     </div>
   )
 }

src/pages/_components/scroll-pagination-example.tsx

@@ -0,0 +1,78 @@
+import { useInfiniteQuery, useQueryClient } from "@tanstack/solid-query"
+import { For } from "solid-js"
+import {
+  ScrollPaginationObserver,
+  useScrollPagination,
+} from "@/components/scroll-pagination-observer"
+import { Badge } from "@/components/ui/badge"
+import { Button } from "@/components/ui/button"
+
+// Mock async fetcher that returns a page of items
+const all = Array.from({ length: 20 }, (_, i) => ({
+  id: i + 1,
+  title: `Item ${i + 1}`,
+}))
+const fetchPage = async (page: number) => {
+  await new Promise((r) => setTimeout(r, 1000)) // simulate network delay
+  const limit = 3 // default from paginationDTO
+  const start = (page - 1) * limit // pages start at 1
+  const items = all.slice(start, start + limit)
+  return {
+    items,
+    hasMore: start + limit < all.length,
+    total: all.length,
+    page,
+    limit,
+  }
+}
+
+export function ScrollPaginationExample() {
+  const queryClient = useQueryClient()
+
+  const infiniteQuery = useInfiniteQuery(() => ({
+    queryKey: ["scroll-pagination-items"],
+    queryFn: async ({ pageParam }) => fetchPage(pageParam),
+    initialPageParam: 1,
+    getNextPageParam: (lastPage) => {
+      return lastPage.hasMore ? lastPage.page + 1 : undefined
+    },
+  }))
+  const { scrollContainerRef, loadTriggerRef, loadTriggerState, _entry } = useScrollPagination(
+    () => ({
+      onLoadMore: () => infiniteQuery.fetchNextPage(),
+      isLoading: infiniteQuery.isFetching,
+      hasMore: infiniteQuery.hasNextPage,
+    })
+  )
+
+  // flatten pages into one list
+  const items = () => infiniteQuery.data?.pages.flatMap((p) => p.items) ?? []
+
+  const handleReset = () => {
+    queryClient.resetQueries({ queryKey: ["scroll-pagination-items"] })
+  }
+
+  return (
+    <div class="w-72 p-6">
+      <Badge variant={_entry()?.isIntersecting ? "success" : "info"}>
+        {_entry()?.isIntersecting ? "Intersecting" : "Idle"}
+      </Badge>
+      <div class="mb-4 flex items-center justify-between gap-5 text-xs">
+        <h2 class="">Items ({items().length}/ 20)</h2>
+        <Button onClick={handleReset} variant="ghost" size="sm">
+          Reset
+        </Button>
+      </div>
+
+      <div class="h-full max-h-52 overflow-y-auto" ref={scrollContainerRef}>
+        <ul class="space-y-2">
+          <For each={items()}>
+            {(item) => <li class="rounded border p-3 shadow-sm">{item.title}</li>}
+          </For>
+        </ul>
+
+        <ScrollPaginationObserver ref={loadTriggerRef} state={loadTriggerState} />
+      </div>
+    </div>
+  )
+}

src/server/dtos/pagination.dto.ts

@@ -11,3 +11,25 @@ export const DEFAULT_PAGINATION_OPTIONS: PaginationOptionsDTO = {
   page: 1,
   limit: 10,
 }
+
+export const paginatedResponseDTO = <T extends z.ZodTypeAny>(itemSchema: T) =>
+  z.object({
+    /** Array of items for the current page */
+    items: z.array(itemSchema),
+    /** Indicates if more pages are available */
+    hasMore: z.boolean(),
+    /** Total number of items across all pages */
+    total: z.number().int().min(0),
+    /** Current page number (starts at 1) */
+    page: z.number().int().min(1),
+    /** Number of items per page */
+    limit: z.number().int().min(0),
+  })
+
+export type PaginatedResponseDTO<T> = {
+  items: T[]
+  hasMore: boolean
+  total: number
+  page: number
+  limit: number
+}