Introduction of the <InfiniteScroll> component

package.json

@@ -17,20 +17,20 @@
     "test:react": "PACKAGE=react playwright test",
     "test:svelte": "PACKAGE=svelte playwright test",
     "test:vue": "PACKAGE=vue3 playwright test",
-    "playground:react": "cd playgrounds/react && composer run dev",
-    "playground:svelte4": "cd playgrounds/svelte4 && composer run dev",
-    "playground:svelte5": "cd playgrounds/svelte5 && composer run dev",
-    "playground:vue": "cd playgrounds/vue3 && composer run dev",
+    "playground:react": "cd playgrounds/react && ./init.sh && composer run dev",
+    "playground:svelte4": "cd playgrounds/svelte4 && ./init.sh && composer run dev",
+    "playground:svelte5": "cd playgrounds/svelte5 && ./init.sh && composer run dev",
+    "playground:vue": "cd playgrounds/vue3 && ./init.sh && composer run dev",
     "format": "prettier --write ."
   },
   "dependencies": {
-    "@playwright/test": "^1.55.0",
-    "prettier": "^3.2.5",
-    "prettier-plugin-organize-imports": "^4.1.0",
-    "prettier-plugin-svelte": "^3.2.3",
-    "prettier-plugin-tailwindcss": "^0.6.9"
+    "@playwright/test": "^1.55.1",
+    "prettier": "^3.6.2",
+    "prettier-plugin-organize-imports": "^4.3.0",
+    "prettier-plugin-svelte": "^3.4.0",
+    "prettier-plugin-tailwindcss": "^0.6.14"
   },
   "optionalDependencies": {
-    "@rollup/rollup-linux-x64-gnu": "^4.28.1"
+    "@rollup/rollup-linux-x64-gnu": "^4.52.2"
   }
 }

packages/core/package.json

@@ -53,18 +53,18 @@
   },
   "dependencies": {
     "@types/lodash-es": "^4.17.12",
-    "axios": "^1.12.0",
+    "axios": "^1.12.2",
     "lodash-es": "^4.17.21",
-    "qs": "^6.9.0"
+    "qs": "^6.14.0"
   },
   "devDependencies": {
-    "@types/deepmerge": "^2.2.0",
-    "@types/node": "^18.4",
-    "@types/nprogress": "^0.2.0",
-    "@types/qs": "^6.9.0",
+    "@types/deepmerge": "^2.2.3",
+    "@types/node": "^18.19.127",
+    "@types/nprogress": "^0.2.3",
+    "@types/qs": "^6.14.0",
     "es-check": "^9.3.1",
-    "esbuild": "^0.25.0",
-    "esbuild-node-externals": "^1.6.0",
+    "esbuild": "^0.25.10",
+    "esbuild-node-externals": "^1.18.0",
     "typescript": "^5.9.2"
   }
 }

packages/core/src/domUtils.ts

@@ -0,0 +1,57 @@
+const elementInViewport = (el: HTMLElement) => {
+  const rect = el.getBoundingClientRect()
+
+  // We check both vertically and horizontally for containers that scroll in either direction
+  const verticallyVisible = rect.top < window.innerHeight && rect.bottom >= 0
+  const horizontallyVisible = rect.left < window.innerWidth && rect.right >= 0
+
+  return verticallyVisible && horizontallyVisible
+}
+
+export const getScrollableParent = (element: HTMLElement | null): HTMLElement | null => {
+  let parent = element?.parentElement
+
+  while (parent) {
+    const overflowY = window.getComputedStyle(parent).overflowY
+
+    if (overflowY === 'auto' || overflowY === 'scroll') {
+      return parent
+    }
+
+    parent = parent.parentElement
+  }
+
+  return null
+}
+
+export const getElementsInViewportFromCollection = (
+  referenceElement: HTMLElement,
+  elements: HTMLElement[],
+): HTMLElement[] => {
+  const referenceIndex = elements.indexOf(referenceElement)
+  const visibleElements: HTMLElement[] = []
+
+  // Traverse upwards until an element is not visible
+  for (let i = referenceIndex; i >= 0; i--) {
+    const element = elements[i]
+
+    if (elementInViewport(element)) {
+      visibleElements.push(element)
+    } else {
+      break
+    }
+  }
+
+  // Traverse downwards until an element is not visible
+  for (let i = referenceIndex + 1; i < elements.length; i++) {
+    const element = elements[i]
+
+    if (elementInViewport(element)) {
+      visibleElements.push(element)
+    } else {
+      break
+    }
+  }
+
+  return visibleElements
+}

packages/core/src/events.ts

@@ -27,6 +27,10 @@ export const fireInvalidEvent: GlobalEventTrigger<'invalid'> = (response) => {
   return fireEvent('invalid', { cancelable: true, detail: { response } })
 }
 
+export const fireBeforeUpdateEvent: GlobalEventTrigger<'beforeUpdate'> = (page) => {
+  return fireEvent('beforeUpdate', { detail: { page } })
+}
+
 export const fireNavigateEvent: GlobalEventTrigger<'navigate'> = (page) => {
   return fireEvent('navigate', { detail: { page } })
 }

packages/core/src/index.ts

@@ -1,8 +1,10 @@
 import { Router } from './router'
 
+export { getScrollableParent } from './domUtils'
 export { objectToFormData } from './formData'
 export { formDataToObject } from './formObject'
 export { default as createHeadManager } from './head'
+export { default as useInfiniteScroll } from './infiniteScroll'
 export { shouldIntercept, shouldNavigate } from './navigationEvents'
 export { hide as hideProgress, progress, reveal as revealProgress, default as setupProgress } from './progress'
 export { resetFormFields } from './resetFormFields'

packages/core/src/infiniteScroll.ts

@@ -0,0 +1,95 @@
+import { useInfiniteScrollData } from './infiniteScroll/data'
+import { useInfiniteScrollElementManager } from './infiniteScroll/elements'
+import { useInfiniteScrollQueryString } from './infiniteScroll/queryString'
+import { useInfiniteScrollPreservation } from './infiniteScroll/scrollPreservation'
+import { Page, ReloadOptions, UseInfiniteScrollOptions, UseInfiniteScrollProps } from './types'
+
+/**
+ * Core infinite scroll composable that orchestrates data fetching, DOM management,
+ * scroll preservation, and URL synchronization.
+ *
+ * This is the main entry point that coordinates four sub-systems:
+ * - Data management: Handles pagination state and server requests
+ * - Element management: DOM observation and intersection detection
+ * - Query string sync: Updates URL as user scrolls through pages
+ * - Scroll preservation: Maintains scroll position during content updates
+ */
+export default function useInfiniteScroll(options: UseInfiniteScrollOptions): UseInfiniteScrollProps {
+  const queryStringManager = useInfiniteScrollQueryString({ ...options, getPageName: () => dataManager.getPageName() })
+
+  // Create scroll preservation callbacks that capture and restore scroll position
+  // and restore it after new content is prepended to maintain visual stability
+  const scrollPreservation = useInfiniteScrollPreservation(options)
+
+  const elementManager = useInfiniteScrollElementManager({
+    ...options,
+    // As items enter viewport, update URL to reflect the most visible page
+    onItemIntersected: queryStringManager.onItemIntersected,
+    onPreviousTriggered: () => dataManager.fetchPrevious(),
+    onNextTriggered: () => dataManager.fetchNext(),
+  })
+
+  const dataManager = useInfiniteScrollData({
+    ...options,
+    // Before updating page data, tag any manually added DOM elements
+    // so they don't get confused with server-loaded content
+    onBeforeUpdate: elementManager.processManuallyAddedElements,
+    // After successful request, tag new server content
+    onCompletePreviousRequest: (loadedPage?: string | number) => {
+      setTimeout(() => {
+        elementManager.processServerLoadedElements(loadedPage)
+        options.onCompletePreviousRequest()
+        window.queueMicrotask(elementManager.refreshTriggers)
+      })
+    },
+    onCompleteNextRequest: (loadedPage?: string | number) => {
+      setTimeout(() => {
+        elementManager.processServerLoadedElements(loadedPage)
+        options.onCompleteNextRequest()
+        window.queueMicrotask(elementManager.refreshTriggers)
+      })
+    },
+  })
+
+  const addScrollPreservationCallbacks = (reloadOptions: ReloadOptions): ReloadOptions => {
+    const { captureScrollPosition, restoreScrollPosition } = scrollPreservation.createCallbacks()
+
+    const originalOnBeforeUpdate = reloadOptions.onBeforeUpdate || (() => {})
+    const originalOnSuccess = reloadOptions.onSuccess || (() => {})
+
+    reloadOptions.onBeforeUpdate = (page: Page) => {
+      originalOnBeforeUpdate(page)
+      captureScrollPosition()
+    }
+
+    reloadOptions.onSuccess = (page: Page) => {
+      originalOnSuccess(page)
+      restoreScrollPosition()
+    }
+
+    return reloadOptions
+  }
+
+  const originalFetchNext = dataManager.fetchNext
+  dataManager.fetchNext = (reloadOptions: ReloadOptions = {}) => {
+    if (options.inReverseMode()) {
+      reloadOptions = addScrollPreservationCallbacks(reloadOptions)
+    }
+
+    originalFetchNext(reloadOptions)
+  }
+
+  const originalFetchPrevious = dataManager.fetchPrevious
+  dataManager.fetchPrevious = (reloadOptions: ReloadOptions = {}) => {
+    if (!options.inReverseMode()) {
+      reloadOptions = addScrollPreservationCallbacks(reloadOptions)
+    }
+
+    originalFetchPrevious(reloadOptions)
+  }
+
+  return {
+    dataManager,
+    elementManager,
+  }
+}

packages/core/src/infiniteScroll/data.ts

@@ -0,0 +1,111 @@
+import { router } from '../index'
+import { page as currentPage } from '../page'
+import { Page, PendingVisit, ReloadOptions, ScrollProp, UseInfiniteScrollDataManager } from '../types'
+
+const MERGE_INTENT_HEADER = 'X-Inertia-Infinite-Scroll-Merge-Intent'
+
+type Side = 'previous' | 'next'
+type ScrollPropPageNames = keyof Pick<ScrollProp, 'previousPage' | 'nextPage'>
+
+export const useInfiniteScrollData = (options: {
+  getPropName: () => string
+  onBeforeUpdate: () => void
+  onBeforePreviousRequest: () => void
+  onBeforeNextRequest: () => void
+  onCompletePreviousRequest: (loadedPage?: string | number) => void
+  onCompleteNextRequest: (loadedPage?: string | number) => void
+}): UseInfiniteScrollDataManager => {
+  const getScrollPropFromCurrentPage = (): ScrollProp => {
+    const scrollProp = currentPage.get().scrollProps?.[options.getPropName()]
+
+    if (scrollProp) {
+      return scrollProp
+    }
+
+    throw new Error(`The page object does not contain a scroll prop named "${options.getPropName()}".`)
+  }
+
+  const { previousPage, nextPage, currentPage: lastLoadedPage } = getScrollPropFromCurrentPage()
+
+  const state = {
+    loading: false,
+    previousPage,
+    nextPage,
+    lastLoadedPage,
+  }
+
+  const getScrollPropKeyForSide = (side: Side): ScrollPropPageNames => {
+    return side === 'next' ? 'nextPage' : 'previousPage'
+  }
+
+  const findPageToLoad = (side: Side) => {
+    const pagePropName = getScrollPropKeyForSide(side)
+
+    return state[pagePropName]
+  }
+
+  const syncStateOnSuccess = (side: Side) => {
+    const scrollProp = getScrollPropFromCurrentPage()
+    const paginationProp = getScrollPropKeyForSide(side)
+
+    state.lastLoadedPage = scrollProp.currentPage
+    state[paginationProp] = scrollProp[paginationProp]
+  }
+
+  const getPageName = () => getScrollPropFromCurrentPage().pageName
+
+  const fetchPage = (side: Side, reloadOptions: ReloadOptions = {}): void => {
+    const page = findPageToLoad(side)
+
+    if (state.loading || page === null) {
+      return
+    }
+
+    state.loading = true
+
+    router.reload({
+      ...reloadOptions,
+      data: { [getPageName()]: page },
+      only: [options.getPropName()],
+      preserveUrl: true, // we handle URL updates manually via useInfiniteScrollQueryString()
+      headers: {
+        [MERGE_INTENT_HEADER]: side === 'previous' ? 'prepend' : 'append',
+        ...reloadOptions.headers,
+      },
+      onBefore: (visit: PendingVisit) => {
+        side === 'next' ? options.onBeforeNextRequest() : options.onBeforePreviousRequest()
+        reloadOptions.onBefore?.(visit)
+      },
+      onBeforeUpdate: (page: Page) => {
+        options.onBeforeUpdate()
+        reloadOptions.onBeforeUpdate?.(page)
+      },
+      onSuccess: (page: Page) => {
+        syncStateOnSuccess(side)
+        reloadOptions.onSuccess?.(page)
+      },
+      onFinish: (visit: any) => {
+        state.loading = false
+        side === 'next'
+          ? options.onCompleteNextRequest(state.lastLoadedPage)
+          : options.onCompletePreviousRequest(state.lastLoadedPage)
+        reloadOptions.onFinish?.(visit)
+      },
+    })
+  }
+
+  const getLastLoadedPage = () => state.lastLoadedPage
+  const hasPrevious = () => !!state.previousPage
+  const hasNext = () => !!state.nextPage
+  const fetchPrevious = (reloadOptions?: ReloadOptions): void => fetchPage('previous', reloadOptions)
+  const fetchNext = (reloadOptions?: ReloadOptions): void => fetchPage('next', reloadOptions)
+
+  return {
+    getLastLoadedPage,
+    getPageName,
+    hasPrevious,
+    hasNext,
+    fetchNext,
+    fetchPrevious,
+  }
+}