Skip to main content
cngx-src documentation

CngxIncrementalList

ComponentPrimaryOnPushNo encapsulationv0.1.0WCAG AA

projects/ui/collection/incremental-list.component.ts

GitHub

Import#

import { CngxIncrementalList } from '@cngx/ui/collection'

Description#

Append-style collection organism.
Accumulates rows across pages (append, don't replace) and switches its view by async status - loading / content / empty / error / end-reached - from a single [state] source. A thin shell over the CngxPaginate brain (applied as a hostDirective): the accumulated slice is read from the brain's cumulativeRange(), the end-reached branch from isLast(), and the loading gate from the bound state's isBusy(). It owns no [mode] flag and no accumulation state of its own.

The brain is provided as CNGX_PAGINATOR_HOST via useExisting, so an existing trigger atom (cngx-pgn-load-more, cngx-pgn-infinite) injects the same contract when projected - the trigger stays a swappable terminal unit, the rich async experience lives here.

Two-way [(pageIndex)] / [(pageSize)] mirror the paginator shell: the brain's controlled inputs are aliased through hostDirectives and this component is the single emitter of the matching outputs.

All ARIA is signal-driven: aria-busy reflects the brain busy signal and a polite live region communicates every settle (empty / error / end-reached).

Related#

Metadata#

Selector
cngx-incremental-list
Export as
cngxIncrementalList
Change detection
ChangeDetectionStrategy.OnPush
Encapsulation
ViewEncapsulation.None
Template URL
./incremental-list.component.html
Style URLs
./incremental-list.component.css
Style URL
./incremental-list.component.css
Imports
CngxProgressCngxEmptyStateCngxLiveRegionNgTemplateOutletCngxIncrementalVirtualizedBody
Host directives
CngxPaginate
inputs cngxPageIndex: pageIndex cngxPageSize: pageSize total state

Host#

Class
cngx-incremental-list
Static attributes
[attr.aria-busy]paginate.isBusy()
[attr.data-skin]skin()
[attr.data-virtualize]virtualize() ? '' : null

Providers#

CNGX_PAGINATOR_HOST
useExisting CngxPaginate
CNGX_RECYCLER_I18N
useFactory (): RecyclerI18n => { const config = injectIncrementalListConfig(); return { loaded: (count, total) => config.ariaLabels.loadedMore(count, total), filtered: () => '', empty: () => '', error: () => '', }; }

Dependencies#

CngxPaginateinject()paginate

Relationships

Depends on7

CngxProgressStandalone component
CngxEmptyStateStandalone component
CngxLiveRegionAttribute directive
NgTemplateOutletdependency
CngxIncrementalVirtualizedBodydependency
CNGX_PAGINATOR_HOSTservice
CNGX_RECYCLER_I18Nservice

Index#

Properties

retryFntrackItem

Methods

handleFocusEscaped

Inputs

estimateSizeskintrackByvirtualize

Outputs

pageIndexChangepageSizeChangeretry

Derived State

emptyLabelemptyTemplateendLabelendTemplateerrorContexterrorLabelerrorTemplateerrorViewLabelexhausteditemsitemTemplateloadingLabelloadingTemplatepageErrorLabelretryLabelstatusMessageview

HostBindings

attr.aria-busyattr.data-skinattr.data-virtualize

Inputs#

estimateSize#number
input()

Initial per-row height estimate (px) for the virtualized window - the first guess before a row is measured. Ignored unless [virtualize] is set.

default 48
skin#CngxIncrementalListSkin
input()

Visual skin; reflected onto [data-skin]. Paint-only.

default 'plain'
trackBy#(index: number, item: T) => unknown

Item identity for the accumulated @for. Defaults to the row index (append-safe: appended rows keep their position). Supply a key fn when the bound [state] data can be replaced or reordered, so a projected item template keeps its per-row state instead of being reused by position.

default (index) => index
virtualize#
input()

Opt into DOM recycling. When set, the accumulated content branch renders only the visible window of rows through an internal virtualized body inside a bounded scroll viewport; every off-window row is a pixel spacer. Unset (default) keeps the render-all path - the recycler never constructs, so a small list pays nothing. Reflected onto [data-virtualize].

default false, { transform: booleanAttribute }

Outputs#

pageIndexChange#number
output()

Emits the effective page index on every change - navigation or total-shrink clamp.

pageSizeChange#number
output()

Emits the effective page size on every change.

retry#void
output()

Emits when the error view's retry affordance is activated (the built-in button or a projected error slot's retry() context). The consumer re-runs its data source; the organism owns no fetch of its own.

Instance Properties#

retryFn#unknown
ProtectedReadonly

Stable retry callback - emits the retry output; shared by the built-in button and the error slot context.

() => {...}
trackItem#unknown
ProtectedReadonly

@for track expression - delegates to the trackBy input (index by default).

() => {...}

Methods#

handleFocusEscaped#void
Protected

Focus fallback for the virtualized body: when a focused row recycles out and the window has no row left to catch focus, restore it to the projected trigger. The organism owns the trigger ng-content, so the escape target is the organism's, not the body's.

HostBindings#

BindingExpression
[attr.aria-busy]paginate.isBusy()
[attr.data-skin]skin()
[attr.data-virtualize]virtualize() ? '' : null
Enter to selectArrow Down Arrow Up to navigateEsc to close