Appearance

useGalleryPreviewPager Composable ​

File Information ​

  • Path: app/composables/core/components/dialogs/useGalleryPreviewPager.ts
  • Purpose: Loads gallery pages on demand, from the front (head) and from the end (tail)
  • Type: Core Composable
  • Added: PR #137 (RIV-1266), 2026-10-28

Overview ​

useGalleryPreviewPager(options: GalleryPagerOptions) takes the assets the page already has and a GalleryPagination contract, and exposes one merged list plus the flags navigation needs. It keeps two fetched lists so the gallery can wrap from the first asset to the last one without loading every page in between:

  • head: baseAssets + pages loadedPages, loadedPages + 1, ... (nextPage is the next page to fetch)
  • tail: the last page, then the page before it, ... (tailFirstPage is the lowest tail page loaded)

All lists are merged by String(id); an id seen earlier wins, so overlapping pages never duplicate an asset.

Features ​

State and derived flags ​

NameRule
itemshead items, then tail items, de-duplicated
hasTailtail has items
mergedtailFirstPage !== null && nextPage >= tailFirstPage (head reached the tail)
hasGaphasTail && !merged
headLengthhead length while there is a gap, else items.length
canLoadForwardpagination set, head not exhausted, nextPage <= tailFirstPage - 1 (or <= lastPage without a tail)
canLoadBackwardpagination set and tailFirstPage - 1 >= nextPage
canLoadLastpagination set, no tail yet, lastPage finite and >= nextPage
totalitems.length once nothing can load; otherwise max(items.length, serverTotal)
canAutoLoadfalse after a failed load, until the next load starts

Loading ​

  • loadNext() fetches nextPage; if the page adds no new asset it keeps fetching while canLoadForward. The head is exhausted when nextPage > lastPage, or, with an unknown last page, when a page comes back empty.
  • loadLast() fetches lastPage into the tail; if that adds nothing it walks backwards.
  • loadPrevious() fetches tailFirstPage - 1, repeating while nothing new is added.
  • Each response may update lastPage and serverTotal.
  • Only one load runs at a time (loading). Each load gets a token; a response whose token is no longer current (dialog closed or reset) is dropped.
  • On error: paused = true and snackbar.showError(getErrorMessage(error)).

Reset ​

On open, and whenever pagination changes while open: fetched lists are cleared, nextPage = max(loadedPages, 1), lastPage = pagination.lastPage, else ceil(total / pageSize), else infinity; serverTotal = pagination.total. Closing invalidates in-flight requests. Without pagination the pager only exposes baseAssets.

Note that nextPage starts at loadedPages (the page the grid already loaded), so the first forward fetch re-requests that page; de-duplication drops the repeated rows.

Return Type ​

items, headLength, hasGap, hasTail, total, canLoadForward, canLoadBackward, canLoadLast, canAutoLoad, loading (readonly), loadNext, loadLast, loadPrevious.

Parameters ​

GalleryPagerOptions: baseAssets: () => any[], pagination: () => GalleryPagination | null | undefined, open: () => boolean.

Usage Example ​

typescript
const pager = useGalleryPreviewPager({
  baseAssets: () => props.assets,
  pagination: () => props.pagination,
  open: () => modalDialog.value,
});