CngxRecycler

Interface

projects/common/data/recycler/recycler.ts

Info
API

Referenced by#

CngxMeasure CngxRecyclerAnnouncer CngxVirtualItem

Import#

import { CngxRecycler } from '@cngx/common/data'

Description#

Signal-based virtualizer returned by injectRecycler. All derived values are computed() - the system cannot become inconsistent.

Index#

Instance Properties#

announcement#Signal

Readonly

SR announcement text for state transitions (load, filter, empty, error).

ariaSetSize#Signal

Readonly

serverTotal when set, otherwise totalCount. Bind to aria-setsize.

end#Signal

Readonly

End index (exclusive) of the rendered range, including overscan.

firstVisible#Signal

Readonly

First actually visible index (without overscan). For UI display.

isEmpty#Signal

Readonly

true when totalCount === 0 and not busy.

isLoading#Signal

Readonly

true during first load (state.isFirstLoad()). false without state.

isRefreshing#Signal

Readonly

true during refresh (state.isRefreshing()). Data remains visible.

lastVisible#Signal

Readonly

Last actually visible index (without overscan). For UI display.

lostFocus#Signal

Readonly

Reports the index of the item that had focus when it left the rendered range. null when no focus was lost. Consumer can use this to restore focus.

neededRange#Signal

Readonly

The range of item indices that must be available for rendering. Use in an effect to trigger page loads for windowed/sparse data sources.

Unlike firstVisible/lastVisible (which exclude overscan), this includes overscan items - all indices in this range may be rendered.

effect(() => {
  const { start, end } = recycler.neededRange();
  const startPage = Math.floor(start / PAGE_SIZE);
  const endPage = Math.floor(end / PAGE_SIZE);
  for (let p = startPage; p <= endPage; p++) {
    if (!pageCache.has(p)) { loadPage(p); }
  }
});

offsetAfter#Signal

Readonly

Spacer height after rendered items (px). Always 0 in grid mode.

offsetBefore#Signal

Readonly

Spacer height before rendered items (px). Always 0 in grid mode.

pendingTarget#Signal

Readonly

Target index that scrollToIndex() is waiting for. Non-null when the target index exceeds totalCount - consumer can show a "Scrolling to item..." indicator or trigger page loads. Clears automatically when totalCount grows past the target.

placeholdersAfter#Signal

Readonly

Placeholder count after rendered items. Only non-zero in grid mode.

placeholdersBefore#Signal

Readonly

Placeholder count before rendered items. Only non-zero in grid mode.

showSkeleton#Signal

Readonly

isLoading AND skeletonDelay elapsed. Prevents skeleton flicker on fast loads.

skeletonSlots#Signal

Readonly

How many skeleton items fit in the viewport: ceil(clientHeight / estimateSize).

start#Signal

Readonly

Start index (inclusive) of the rendered range, including overscan.

totalSize#Signal

Readonly

Total scrollable height of all items (px).

visibleCount#Signal

Readonly

Count of actually visible items (without overscan).

Methods#

anchorTo#void

anchorTo(index: number)

Locks scroll position relative to an item. When items are inserted above the anchored item, scrollTop is corrected to maintain visual position.

@paramindexnumber

measure#void

measure(index: number, element: HTMLElement)

Reports a measured item height to the internal SizeCache. No-op in grid mode (uniform row height assumed). Prefer CngxMeasure directive over calling this directly.

@paramindexnumber

@paramelementHTMLElement

releaseAnchor#void

Releases the scroll anchor set by anchorTo.

reset#void

Scrolls to top. Convenience for sort/filter changes.

scrollToIndex#void

scrollToIndex(index: number, behavior?: ScrollBehavior)

Scrolls to a specific item index. When index >= totalCount, stores the target in pendingTarget for resolution when data arrives.

@paramindexnumber

@parambehavior?ScrollBehavior

sliced#Signal

sliced(items: Signal)

Creates a computed() slicing items to the visible range. Call once in a field initializer - each call creates a new computed node. Do NOT call in templates or methods.

@paramitemsSignal