Core columns & header layout

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.

Column definitions and runtime layout state are separate. Persist widths, visibility, order and pinning using serializeCominsColumnLayout.

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

setCominsColumnWidth

export declare function setCominsColumnWidth<TData>(state: CominsTableState<TData>, columnId: string, width: number): CominsTableState<TData>;

Sets columnState[columnId].width. This Core setter does not enforce width limits; supply a valid width.

setCominsColumnHidden

export declare function setCominsColumnHidden<TData>(state: CominsTableState<TData>, columnId: string, hidden: boolean): CominsTableState<TData>;

Updates runtime hidden state. A hidden parent group still suppresses a column set to visible.

setCominsColumnGroupHidden

export declare function setCominsColumnGroupHidden<TData>(state: CominsTableState<TData>, groupId: string, hidden: boolean): CominsTableState<TData>;

Updates group visibility, preserving individual child visibility settings. An unknown group returns the original state.

setCominsColumnGroupWidth

export declare function setCominsColumnGroupWidth<TData>(state: CominsTableState<TData>, groupId: string, width: number): CominsTableState<TData>;

Distributes a total group width among visible children while respecting their minWidth/maxWidth. Missing/hidden groups or groups without visible children are unchanged.

moveCominsColumn

export declare function moveCominsColumn<TData>(state: CominsTableState<TData>, columnId: string, targetIndex: number): CominsTableState<TData>;

Inserts at targetIndex in the full columnOrder after removing the source. Group children remain within their group; moves that change locked or pinned block positions are rejected.

moveCominsColumnGroup

export declare function moveCominsColumnGroup<TData>(state: CominsTableState<TData>, groupId: string, targetIndex: number): CominsTableState<TData>;

Removes group children as one block and inserts them at targetIndex. Locked/pinned groups and moves changing protected positions are rejected.

serializeCominsColumnLayout

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

Returns order and columns, plus groups when present. It does not serialize functions or React nodes. Nested references are not fully deep-copied; do not mutate the result.

applyCominsColumnLayout

export declare function applyCominsColumnLayout<TData>(state: CominsTableState<TData>, layout: CominsColumnLayout): CominsTableState<TData>;

Normalizes a saved layout against current column/group definitions, rebuilding order and state using known IDs and contiguous groups.

getCominsVisibleColumns

export declare function getCominsVisibleColumns<TData>(state: CominsTableState<TData>): CominsTableRuntimeColumn<TData, unknown>[];

Excludes hidden columns/groups and emits group children together, ordered left-pinned, unpinned, then right-pinned. Read runtime widths separately from columnState.

getCominsHeaderRows

export declare function getCominsHeaderRows<TData>(state: CominsTableState<TData>): Array<Array<CominsHeaderCell<TData>>>;

Returns one header row without groups, or parent/child rows with groups. Ungrouped columns use rowSpan 2; group colSpan equals its visible child count.

CominsColumnRuntimeState

export type CominsColumnRuntimeState = {
    hidden?: boolean;
    pinned?: CominsColumnPinned;
    width?: number;
};

Property	Behavior / default
`hidden`	Column visibility state.
`pinned`	left/right pinning state.
`width`	Runtime width in pixels.

CominsColumnGroupRuntimeState

export type CominsColumnGroupRuntimeState = {
    hidden?: boolean;
    pinned?: CominsColumnPinned;
};

Property	Behavior / default
`hidden`	Visibility of the whole group.
`pinned`	left/right pinning for the group block.

CominsColumnLayout

export type CominsColumnLayout = {
    columns: Record<string, CominsColumnRuntimeState>;
    groups?: Record<string, CominsColumnGroupRuntimeState>;
    order: string[];
};

Property	Behavior / default
`columns`	State by column ID.
`groups`	Optional state by group ID.
`order`	Ordered column IDs.

CominsTableRuntimeColumn

export type CominsTableRuntimeColumn<TData, TValue = unknown> = Omit<CominsTableColumn<TData, TValue>, "id"> & {
    id: string;
};

CominsTableColumn with its optional id resolved to a required string ID.

CominsTableRuntimeColumnGroup

export type CominsTableRuntimeColumnGroup = Omit<CominsTableColumnGroup, "children"> & {
    children: string[];
};

Normalized group definition whose children are valid column IDs.

CominsHeaderColumnCell

export type CominsHeaderColumnCell<TData> = {
    colSpan: 1;
    column: CominsTableRuntimeColumn<TData>;
    columnId: string;
    groupId?: string;
    kind: "column";
    rowSpan: 1 | 2;
};

Property	Behavior / default
`colSpan`	Always 1.
`column`	Runtime column definition to render.
`columnId`	Column ID.
`groupId`	Group ID when grouped.
`kind`	column discriminator.
`rowSpan`	Normally 1; 2 for an ungrouped parent-row cell.

CominsHeaderGroupCell

export type CominsHeaderGroupCell = {
    colSpan: number;
    group: CominsTableRuntimeColumnGroup;
    groupId: string;
    kind: "group";
    rowSpan: 1;
};

Property	Behavior / default
`colSpan`	Number of visible children.
`group`	Group definition.
`groupId`	Group ID.
`kind`	group discriminator.
`rowSpan`	Always 1.

CominsHeaderCell

export type CominsHeaderCell<TData> = CominsHeaderColumnCell<TData> | CominsHeaderGroupCell;

A union discriminated by kind: column or group.