Core sorting, pages & virtual rows

comins-table@0.2.2React

0.2.0: Types and helpers on this page use the React-state contract from the root comins-table entry. Neutral /core has a separate type contract. See the migration guide for imports and cell policies.

Setting sort rules preserves the underlying row order. Derive sorted indexes, pages or virtual rows, or reorder the underlying array with sortCominsRows.

Long structural return declarations are shown as the equivalent CominsTableState<TData>. Validation checks assignability in both directions against the published declaration.

setCominsSortState

export declare function setCominsSortState<TData>(state: CominsTableState<TData>, sort: CominsSortState | null): CominsTableState<TData>;

Converts one rule or null into a one-rule or empty sortModel.

setCominsSortModel

export declare function setCominsSortModel<TData>(state: CominsTableState<TData>, sortModel: CominsSortModel): CominsTableState<TData>;

Rules are prioritized from the start. Only columns with sort enabled remain; duplicate/unknown IDs and invalid directions are removed. An unchanged normalized model returns the original state.

clearCominsSortState

export declare function clearCominsSortState<TData>(state: CominsTableState<TData>): CominsTableState<TData>;

Clears sortModel and sets sort to null. It does not restore an earlier order of physically reordered rows.

getCominsSortedRowIndexes

export declare function getCominsSortedRowIndexes<TData>(state: CominsTableState<TData>, sourceIndexes?: readonly number[]): number[];

Sorts all row indexes or the supplied sourceIndexes subset. Numbers use numeric comparison, other values use string localeCompare, and custom column comparators are supported. Ties use original row indexes.

sortCominsRows

export declare function sortCominsRows<TData>(state: CominsTableState<TData>, sort: CominsSortState | null): CominsTableState<TData>;

Sets a single sort rule and reorders rows/rowIds. A changed ID order clears selection.

setCominsPagination

export declare function setCominsPagination<TData>(state: CominsTableState<TData>, pagination: Partial<CominsPaginationState>): CominsTableState<TData>;

Merges supplied pageIndex/pageSize values. The setter does not validate integers; provide valid input.

getCominsPageRows

export declare function getCominsPageRows<TData>(state: CominsTableState<TData>, pagination?: Partial<CominsPaginationState>): NonNullable<TData>[];

Slices a page after sorting. The optional argument overrides pagination for this query; calculation clamps pageIndex to at least 0 and pageSize to at least 1. State is unchanged.

getCominsVirtualRows

export declare function getCominsVirtualRows<TData>(state: CominsTableState<TData>, { overscan, rowHeight, scrollTop, viewportHeight }: CominsVirtualRowsOptions): CominsVirtualRows<TData>;

Sorts the full local array and computes a fixed-height render range and spacer heights. overscan defaults to 2; rowHeight is at least 1. Pagination is not applied. This is separate from the server Viewport hook and automatic-height engine.

CominsSortDirection

export type CominsSortDirection = "asc" | "desc";

asc means ascending; desc means descending.

CominsSortState

export type CominsSortState = {
    columnId: string;
    direction: CominsSortDirection;
};

Property	Behavior / default
`columnId`	ID of a sortable column.
`direction`	asc or desc.

CominsSortModel

export type CominsSortModel = readonly CominsSortState[];

Readonly sort-rule array, ordered from highest to lowest priority.

CominsPaginationState

export type CominsPaginationState = {
    pageIndex: number;
    pageSize: number;
};

Property	Behavior / default
`pageIndex`	Zero-based page number.
`pageSize`	Rows per page; use a positive integer.

CominsVirtualRowsOptions

export type CominsVirtualRowsOptions = {
    overscan?: number;
    rowHeight: number;
    scrollTop: number;
    viewportHeight: number;
};

Property	Behavior / default
`overscan`	Extra rows before/after the viewport; defaults to 2. Use a non-negative integer.
`rowHeight`	Required fixed row height in pixels.
`scrollTop`	Required vertical scroll position in pixels, within the valid dataset scroll range.
`viewportHeight`	Required viewport height in pixels.

CominsVirtualRows

export type CominsVirtualRows<TData> = {
    bottomSpacerHeight: number;
    endIndex: number;
    rows: TData[];
    startIndex: number;
    topSpacerHeight: number;
    totalHeight: number;
};

Property	Behavior / default
`bottomSpacerHeight`	Bottom spacer height in pixels.
`endIndex`	Exclusive end in the sorted index array.
`rows`	Sorted rows to render.
`startIndex`	Inclusive start in the sorted index array.
`topSpacerHeight`	Top spacer height in pixels.
`totalHeight`	Total row count multiplied by normalized row height.