Core state model

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 functions take CominsTableState and return derived results or the next state. This model is separate from React Table props. Do not spread the entire state into CominsTable; use its documented props and ref for React integration.

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

This page documents the root comins-table helpers for React state. Import framework-neutral state from comins-table/core.

import { createCominsTableState, updateCominsRows } from "comins-table";

createCominsTableState

export declare function createCominsTableState<TData>(input: CominsTableStateInput<TData>): CominsTableState<TData>;

Creates state from columns and rows. A column without id uses field; the default getRowId returns the row index. Supply a unique business ID when rows can be inserted, removed or sorted. The rows array is shared without a deep copy, so do not mutate it externally. sortModel takes precedence over sort; selection starts empty.

setCominsTableTheme

export declare function setCominsTableTheme<TData>(state: CominsTableState<TData>, theme: CominsTableTheme): CominsTableState<TData>;

Shallow-merges theme into the existing theme; nested style properties are not deep-merged.

setCominsHeaderVisible

export declare function setCominsHeaderVisible<TData>(state: CominsTableState<TData>, showHeader: boolean): CominsTableState<TData>;

Updates showHeader only. The header-row model builder does not check this flag; a custom renderer decides whether to display it.

CominsTableStateInput

export type CominsTableStateInput<TData> = {
    columnLayout?: Partial<CominsColumnLayout>;
    columnGroups?: ReadonlyArray<CominsTableColumnGroup>;
    columns: ReadonlyArray<CominsTableColumn<TData>>;
    getRowId?: (row: TData, index: number) => CominsRowId;
    pagination?: Partial<CominsPaginationState>;
    rows: readonly TData[];
    showHeader?: boolean;
    sort?: CominsSortState | null;
    sortModel?: CominsSortModel;
    theme?: CominsTableTheme;
};

Property	Behavior / default
`columnLayout`	Optional saved column order, widths, visibility and pinning.
`columnGroups`	Optional group IDs and child column IDs; defaults to an empty array.
`columns`	Required column definitions.
`getRowId`	Optional (row, index) → string/number; defaults to index.
`pagination`	Defaults to pageIndex 0 and pageSize max(rows.length, 1).
`rows`	Required row array; do not mutate it externally.
`showHeader`	Defaults to true.
`sort`	Optional single sort; defaults to null and yields to sortModel.
`sortModel`	Ordered multi-sort rules; only sortable columns are retained.
`theme`	Optional theme; defaults to an empty object.

CominsTableState

export type CominsTableState<TData> = {
    columnOrder: string[];
    columnGroups: CominsTableRuntimeColumnGroup[];
    columnGroupState: Record<string, CominsColumnGroupRuntimeState>;
    columns: Array<CominsTableRuntimeColumn<TData>>;
    columnState: Record<string, CominsColumnRuntimeState>;
    getRowId: (row: TData, index: number) => CominsRowId;
    pagination: CominsPaginationState;
    rowIds: CominsRowId[];
    rows: TData[];
    selection: CominsSelectionState;
    showHeader: boolean;
    sort: CominsSortState | null;
    sortModel: CominsSortModel;
    theme: CominsTableTheme;
};

Property	Behavior / default
`columnOrder`	All column IDs in order; displayed order also applies pinning/group rules.
`columnGroups`	Normalized column group definitions.
`columnGroupState`	Visibility/pinning state by group ID.
`columns`	Runtime columns with resolved IDs.
`columnState`	Width/visibility/pinning state by column ID.
`getRowId`	Row ID resolver.
`pagination`	Current pageIndex/pageSize.
`rowIds`	Row IDs in the same order as rows.
`rows`	Underlying row array; changing sort rules alone preserves its order.
`selection`	Row, cell and range selection state.
`showHeader`	Header visibility flag.
`sort`	First rule in sortModel, or null.
`sortModel`	Normalized sort rules.
`theme`	Current theme object.

CominsRowId

export type CominsRowId = string | number;

Row identifiers are strings or numbers. Numeric 1 and string “1” are distinct IDs.

CominsTableDensity

export type CominsTableDensity = "comfortable" | "compact" | "spacious";

The three density tokens are comfortable, compact and spacious.