Core row, cell & range selection

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.

Core selection uses stable row IDs and column IDs. React ref row-selection methods instead accept indexes. Low-level setters do not validate ID existence; pass valid IDs.

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

selectRow

export declare function selectRow<TData>(state: CominsTableState<TData>, rowId: CominsRowId, options?: CominsRowSelectionOptions): CominsTableState<TData>;

Selects one row by default. multi: true adds to existing rows; toggle: true removes an already selected row. Cell/range state is preserved.

selectRows

export declare function selectRows<TData>(state: CominsTableState<TData>, rowIds: readonly CominsRowId[]): CominsTableState<TData>;

Replaces selected row IDs with a copy of the supplied array; it does not deduplicate it.

selectCell

export declare function selectCell<TData>(state: CominsTableState<TData>, cell: CominsCellAddress, options?: CominsCellSelectionOptions): {
    columnOrder: string[];
    columnGroups: import("./core-compat").CominsTableRuntimeColumnGroup[];
    columnGroupState: Record<string, import("./core-compat").CominsColumnGroupRuntimeState>;
    columns: CominsTableRuntimeColumn<TData, unknown>[];
    columnState: Record<string, import("./core-compat").CominsColumnRuntimeState>;
    getRowId: (row: TData, index: number) => CominsRowId;
    pagination: CominsPaginationState;
    rowIds: CominsRowId[];
    rows: TData[];
    showHeader: boolean;
    sort: CominsSortState | null;
    sortModel: CominsSortModel;
    theme: CominsTableTheme;
    selection: {
        rowIds: CominsRowId[];
        cell: CominsCellAddress | null;
        cells: CominsCellAddress[];
        range: null;
    };
};

Updates selected cells using multi/toggle and sets the active cell. Clears the previous range.

selectCellRange

export declare function selectCellRange<TData>(state: CominsTableState<TData>, range: CominsCellRange): {
    columnOrder: string[];
    columnGroups: import("./core-compat").CominsTableRuntimeColumnGroup[];
    columnGroupState: Record<string, import("./core-compat").CominsColumnGroupRuntimeState>;
    columns: CominsTableRuntimeColumn<TData, unknown>[];
    columnState: Record<string, import("./core-compat").CominsColumnRuntimeState>;
    getRowId: (row: TData, index: number) => CominsRowId;
    pagination: CominsPaginationState;
    rowIds: CominsRowId[];
    rows: TData[];
    showHeader: boolean;
    sort: CominsSortState | null;
    sortModel: CominsSortModel;
    theme: CominsTableTheme;
    selection: {
        rowIds: CominsRowId[];
        cell: CominsCellAddress;
        cells: never[];
        range: CominsCellRange;
    };
};

Sets the anchor/focus range, makes focus the active cell, and clears cells.

clearCominsCellRange

export declare function clearCominsCellRange<TData>(state: CominsTableState<TData>): {
    columnOrder: string[];
    columnGroups: import("./core-compat").CominsTableRuntimeColumnGroup[];
    columnGroupState: Record<string, import("./core-compat").CominsColumnGroupRuntimeState>;
    columns: CominsTableRuntimeColumn<TData, unknown>[];
    columnState: Record<string, import("./core-compat").CominsColumnRuntimeState>;
    getRowId: (row: TData, index: number) => CominsRowId;
    pagination: CominsPaginationState;
    rowIds: CominsRowId[];
    rows: TData[];
    showHeader: boolean;
    sort: CominsSortState | null;
    sortModel: CominsSortModel;
    theme: CominsTableTheme;
    selection: {
        cell: CominsCellAddress | null;
        cells?: CominsCellAddress[];
        rowIds: CominsRowId[];
        range: null;
    };
};

Clears only range, preserving the active cell, selected cells and row selection.

clearCominsSelection

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

Clears all row, cell and range selection.

isCominsRowSelected

export declare function isCominsRowSelected<TData>(state: CominsTableState<TData>, rowId: CominsRowId): boolean;

Tests membership in selection.rowIds.

isCominsCellSelected

export declare function isCominsCellSelected<TData>(state: CominsTableState<TData>, cell: CominsCellAddress): boolean;

Checks individual cells, or the active cell when that list is empty. Use the separate range query for rectangular membership.

getCominsSelectedCellRange

export declare function getCominsSelectedCellRange<TData>(state: CominsTableState<TData>, range?: CominsCellRange | null, rowIds?: readonly CominsRowId[]): CominsCellAddress[];

Returns rectangular cell addresses in row-major order, defaulting to state.selection.range and state.rowIds. Hidden columns are excluded; missing ranges/endpoints return an empty array. Supply displayed rowIds for sorted/filtered views.

isCominsCellInSelectedRange

export declare function isCominsCellInSelectedRange<TData>(state: CominsTableState<TData>, cell: CominsCellAddress, rowIds?: readonly CominsRowId[]): boolean;

Tests whether a cell is in the current range; omitted rowIds uses underlying order.

CominsSelectionState

export type CominsSelectionState = {
    cell: CominsCellAddress | null;
    cells?: CominsCellAddress[];
    range: CominsCellRange | null;
    rowIds: CominsRowId[];
};

Property	Behavior / default
`cell`	Active cell or null.
`cells`	Individually selected cells.
`range`	Anchor/focus rectangle or null.
`rowIds`	Selected row IDs.

CominsCellAddress

export type CominsCellAddress = {
    columnId: string;
    rowId: CominsRowId;
};

Property	Behavior / default
`columnId`	Column ID.
`rowId`	Row ID.

CominsCellRange

export type CominsCellRange = {
    anchor: CominsCellAddress;
    focus: CominsCellAddress;
};

Property	Behavior / default
`anchor`	Range anchor.
`focus`	Current range endpoint; reversed ranges are supported.

CominsRowSelectionOptions

export type CominsRowSelectionOptions = {
    multi?: boolean;
    toggle?: boolean;
};

Property	Behavior / default
`multi`	Defaults to false; true adds to existing selection.
`toggle`	Defaults to false; true toggles an already selected item off.

CominsCellSelectionOptions

export type CominsCellSelectionOptions = {
    multi?: boolean;
    toggle?: boolean;
};

Property	Behavior / default
`multi`	Defaults to false; true adds to existing selection.
`toggle`	Defaults to false; true toggles an already selected item off.