@drivenets/design-system 0.17.0 → 0.18.1

package/src/components/ds-table/utils/column-size.ts

@@ -1,21 +1,224 @@
 import type { CSSProperties } from 'react';
-import { defaultColumnSizing } from '@tanstack/react-table';
+import { type ColumnSizingState } from '@tanstack/react-table';
+import { BUILTIN_COLUMN_IDS, RESIZE_MIN_COLUMN_WIDTH } from './constants';
+
+const DEFAULT_MAX_COLUMN_SIZE = Number.MAX_SAFE_INTEGER;
+
+type ColumnWidthSource = {
+	id: string;
+	columnDef: { size?: number; minSize?: number; maxSize?: number; meta?: { hasExplicitSize?: boolean } };
+};
+
+/**
+ * Leaf column used to resolve `minSize` / `maxSize` when clamping a sizing map.
+ */
+export type ColumnSizeBoundsSource = {
+	id: string;
+	columnDef: { minSize?: number; maxSize?: number };
+};
+
+type SizeHeader = {
+	id: string;
+	getSize: () => number;
+	column: { id: string; getSize: () => number };
+};
 
 /**
- * Generates the appropriate style object for a table column/cell based on its size
+ * Whether a column should use a fixed width rather than fill (`flex: 1`).
  *
- * Custom-sized columns get a fixed `width` plus `minWidth` and `flexShrink: 0` so
- * they enforce horizontal overflow on the table container. Default-sized columns
- * grow to fill the row evenly via `flex: 1`.
+ * True when the user has resized it (`columnSizing` entry), or when the raw
+ * column def authored `size` (`meta.hasExplicitSize`). TanStack merges a
+ * default size of 150 onto every column, so `columnDef.size` alone cannot
+ * tell authored 150px from an unsized fill column.
+ */
+export const isExplicitColumnWidth = (
+	column: ColumnWidthSource,
+	columnSizing: ColumnSizingState,
+): boolean => {
+	if (columnSizing[column.id] !== undefined) {
+		return true;
+	}
+
+	return column.columnDef.meta?.hasExplicitSize === true;
+};
+
+/**
+ * Style for a table column/cell based on its size and whether that size is explicit.
  *
- * @param columnSize - The size of the column
- * @returns Style object for the column/cell
+ * Explicit columns get a fixed `width` plus `minWidth` and `flexShrink: 0` so they
+ * enforce horizontal overflow on the table container. Fill columns grow evenly via
+ * `flex: 1`.
  */
-export const getColumnSizeStyle = (columnSize: number): CSSProperties => {
-	const hasCustomSize = columnSize !== defaultColumnSizing.size;
-	if (hasCustomSize) {
+export const getColumnSizeStyle = (columnSize: number, isExplicit: boolean): CSSProperties => {
+	if (isExplicit) {
 		return { width: columnSize, minWidth: columnSize, flexShrink: 0 };
 	}
 
 	return { flex: 1, minWidth: 0 };
 };
+
+export const getHeaderSizeCssVar = (headerId: string): string => `--header-${headerId}-size`;
+
+export const getColumnSizeCssVar = (columnId: string): string => `--col-${columnId}-size`;
+
+/**
+ * Pixel width via a CSS variable on an ancestor, so frozen (memoized) cells still
+ * track live resize without React reconciling each row.
+ */
+export const getResizableHeaderStyle = (headerId: string): CSSProperties => ({
+	width: `calc(var(${getHeaderSizeCssVar(headerId)}) * 1px)`,
+	minWidth: `calc(var(${getHeaderSizeCssVar(headerId)}) * 1px)`,
+	flexShrink: 0,
+});
+
+export const getResizableColumnStyle = (columnId: string): CSSProperties => ({
+	width: `calc(var(${getColumnSizeCssVar(columnId)}) * 1px)`,
+	minWidth: `calc(var(${getColumnSizeCssVar(columnId)}) * 1px)`,
+	flexShrink: 0,
+});
+
+export const getHeaderCellSizeStyle = (
+	headerId: string,
+	columnSize: number,
+	isExplicit: boolean,
+	resizeSizingReady: boolean,
+): CSSProperties => {
+	if (resizeSizingReady) {
+		return getResizableHeaderStyle(headerId);
+	}
+
+	return getColumnSizeStyle(columnSize, isExplicit);
+};
+
+export const getBodyCellSizeStyle = (
+	columnId: string,
+	columnSize: number,
+	isExplicit: boolean,
+	resizeSizingReady: boolean,
+): CSSProperties => {
+	if (resizeSizingReady) {
+		return getResizableColumnStyle(columnId);
+	}
+
+	return getColumnSizeStyle(columnSize, isExplicit);
+};
+
+/**
+ * TanStack v8 performant-resize map: header ids for header cells, column ids for
+ * body cells. Values are unitless px; consumers use `calc(var(...) * 1px)`.
+ */
+export const getColumnSizeCssVars = (headers: SizeHeader[]): Record<string, number> => {
+	const colSizes: Record<string, number> = {};
+
+	for (const header of headers) {
+		colSizes[getHeaderSizeCssVar(header.id)] = header.getSize();
+		colSizes[getColumnSizeCssVar(header.column.id)] = header.column.getSize();
+	}
+
+	return colSizes;
+};
+
+/**
+ * TanStack `getSize()` formula: `min(max(minSize, width), maxSize)`. Defaults
+ * match DsTable (`RESIZE_MIN_COLUMN_WIDTH`, unlimited max).
+ */
+export const clampColumnSize = (
+	width: number,
+	minSize: number = RESIZE_MIN_COLUMN_WIDTH,
+	maxSize: number = DEFAULT_MAX_COLUMN_SIZE,
+): number => Math.min(Math.max(minSize, width), maxSize);
+
+/**
+ * Clamps every finite entry in `sizing` to that leaf's `minSize` / `maxSize`.
+ * Non-finite widths are omitted so they do not poison state. Ids missing from
+ * `columns` use the table defaults.
+ */
+export const clampColumnSizing = (
+	sizing: ColumnSizingState,
+	columns: ReadonlyArray<ColumnSizeBoundsSource>,
+): ColumnSizingState => {
+	const boundsById = new Map(columns.map((column) => [column.id, column.columnDef]));
+	const next: ColumnSizingState = {};
+
+	for (const [id, width] of Object.entries(sizing)) {
+		if (!Number.isFinite(width)) {
+			continue;
+		}
+
+		const bounds = boundsById.get(id);
+		next[id] = clampColumnSize(
+			width,
+			bounds?.minSize ?? RESIZE_MIN_COLUMN_WIDTH,
+			bounds?.maxSize ?? DEFAULT_MAX_COLUMN_SIZE,
+		);
+	}
+
+	return next;
+};
+
+/**
+ * Width to restore on double-click: explicit `columnDef.size`, otherwise the
+ * snapshotted measured width.
+ */
+export const getResizeOriginSize = (column: ColumnWidthSource, measuredWidth: number): number => {
+	if (isExplicitColumnWidth(column, {})) {
+		return column.columnDef.size as number;
+	}
+
+	return measuredWidth;
+};
+
+/**
+ * Measured leaf header widths keyed by column id. Group header cells share
+ * `data-column-id` with a different id, so only `leafColumnIds` are read.
+ */
+export const measureLeafHeaderWidths = (
+	tableEl: HTMLElement,
+	leafColumnIds: string[],
+): Record<string, number> => {
+	const widths: Record<string, number> = {};
+
+	for (const id of leafColumnIds) {
+		const cell = tableEl.querySelector(`thead th[data-column-id="${CSS.escape(id)}"]`);
+		if (cell instanceof HTMLElement) {
+			widths[id] = cell.getBoundingClientRect().width;
+		}
+	}
+
+	return widths;
+};
+
+/**
+ * Sizing entries for leaves that are not yet in `existing`. Does not overwrite
+ * user-resized (or previously snapshotted) ids.
+ */
+export const collectMissingLeafSizing = (
+	measured: Record<string, number>,
+	existing: ColumnSizingState,
+): ColumnSizingState => {
+	const next: ColumnSizingState = {};
+
+	for (const [id, width] of Object.entries(measured)) {
+		if (existing[id] === undefined) {
+			next[id] = Math.round(width);
+		}
+	}
+
+	return next;
+};
+
+/**
+ * Copy of `columnSizing` without injected utility leaves. Use at the public
+ * `onColumnSizingChange` boundary so consumers persist only their own columns.
+ */
+export const omitBuiltinColumnSizing = (columnSizing: ColumnSizingState): ColumnSizingState => {
+	const next: ColumnSizingState = {};
+
+	for (const [id, size] of Object.entries(columnSizing)) {
+		if (!BUILTIN_COLUMN_IDS.has(id)) {
+			next[id] = size;
+		}
+	}
+
+	return next;
+};

package/src/components/ds-table/utils/column-size.unit.test.ts

@@ -0,0 +1,213 @@
+import { describe, expect, it } from 'vitest';
+import { defaultColumnSizing } from '@tanstack/react-table';
+import {
+	clampColumnSize,
+	clampColumnSizing,
+	collectMissingLeafSizing,
+	getBodyCellSizeStyle,
+	getColumnSizeCssVar,
+	getColumnSizeCssVars,
+	getColumnSizeStyle,
+	getHeaderCellSizeStyle,
+	getHeaderSizeCssVar,
+	getResizableColumnStyle,
+	getResizableHeaderStyle,
+	getResizeOriginSize,
+	isExplicitColumnWidth,
+	omitBuiltinColumnSizing,
+} from './column-size';
+import {
+	EXPANDER_COLUMN_ID,
+	REORDER_COLUMN_ID,
+	RESIZE_MIN_COLUMN_WIDTH,
+	SELECT_COLUMN_ID,
+} from './constants';
+
+describe('isExplicitColumnWidth', () => {
+	it('returns false for an unsized column with no sizing entry (fill column)', () => {
+		expect(isExplicitColumnWidth({ id: 'a', columnDef: {} }, {})).toBe(false);
+	});
+
+	it('returns true when size was authored, including TanStack’s default size', () => {
+		expect(
+			isExplicitColumnWidth(
+				{ id: 'a', columnDef: { size: defaultColumnSizing.size, meta: { hasExplicitSize: true } } },
+				{},
+			),
+		).toBe(true);
+	});
+
+	it('returns true when columnSizing has an entry, including the default size value', () => {
+		expect(isExplicitColumnWidth({ id: 'a', columnDef: {} }, { a: defaultColumnSizing.size })).toBe(true);
+	});
+});
+
+describe('getColumnSizeStyle', () => {
+	it('returns fill styles when not explicit', () => {
+		expect(getColumnSizeStyle(defaultColumnSizing.size, false)).toEqual({ flex: 1, minWidth: 0 });
+	});
+
+	it('returns fixed styles when explicit, including at the default size value', () => {
+		expect(getColumnSizeStyle(defaultColumnSizing.size, true)).toEqual({
+			width: defaultColumnSizing.size,
+			minWidth: defaultColumnSizing.size,
+			flexShrink: 0,
+		});
+	});
+
+	it('returns fixed styles for a custom explicit size', () => {
+		expect(getColumnSizeStyle(200, true)).toEqual({ width: 200, minWidth: 200, flexShrink: 0 });
+	});
+});
+
+describe('resizable CSS variable styles', () => {
+	it('names header and column size variables from ids', () => {
+		expect(getHeaderSizeCssVar('identity')).toBe('--header-identity-size');
+		expect(getColumnSizeCssVar('firstName')).toBe('--col-firstName-size');
+	});
+
+	it('uses header variables for header cells and column variables for body cells', () => {
+		expect(getResizableHeaderStyle('identity')).toEqual({
+			width: 'calc(var(--header-identity-size) * 1px)',
+			minWidth: 'calc(var(--header-identity-size) * 1px)',
+			flexShrink: 0,
+		});
+		expect(getResizableColumnStyle('firstName')).toEqual({
+			width: 'calc(var(--col-firstName-size) * 1px)',
+			minWidth: 'calc(var(--col-firstName-size) * 1px)',
+			flexShrink: 0,
+		});
+	});
+
+	it('switches header and body cells to CSS variables once resize sizing is ready', () => {
+		expect(getHeaderCellSizeStyle('a', 200, true, true)).toEqual(getResizableHeaderStyle('a'));
+		expect(getHeaderCellSizeStyle('a', 200, true, false)).toEqual(getColumnSizeStyle(200, true));
+		expect(getBodyCellSizeStyle('a', 200, true, true)).toEqual(getResizableColumnStyle('a'));
+		expect(getBodyCellSizeStyle('a', 150, false, false)).toEqual(getColumnSizeStyle(150, false));
+	});
+
+	it('maps each flat header to header and column size variables', () => {
+		const vars = getColumnSizeCssVars([
+			{ id: 'identity', getSize: () => 360, column: { id: 'identity', getSize: () => 150 } },
+			{ id: 'firstName', getSize: () => 180, column: { id: 'firstName', getSize: () => 180 } },
+		]);
+
+		expect(vars).toEqual({
+			'--header-identity-size': 360,
+			'--col-identity-size': 150,
+			'--header-firstName-size': 180,
+			'--col-firstName-size': 180,
+		});
+	});
+});
+
+describe('clampColumnSize', () => {
+	it('returns the width when it sits inside the range', () => {
+		expect(clampColumnSize(120, 80, 200)).toBe(120);
+	});
+
+	it('clamps to minSize', () => {
+		expect(clampColumnSize(40, 80, 200)).toBe(80);
+	});
+
+	it('clamps to maxSize', () => {
+		expect(clampColumnSize(300, 80, 200)).toBe(200);
+	});
+
+	it('returns maxSize when minSize is greater than maxSize', () => {
+		expect(clampColumnSize(150, 200, 100)).toBe(100);
+	});
+
+	it('uses the table default min when minSize is omitted', () => {
+		expect(clampColumnSize(20)).toBe(RESIZE_MIN_COLUMN_WIDTH);
+	});
+
+	it('allows a minSize below the table default', () => {
+		expect(clampColumnSize(10, 20)).toBe(20);
+		expect(clampColumnSize(40, 20)).toBe(40);
+	});
+});
+
+describe('clampColumnSizing', () => {
+	const columns = [
+		{ id: 'a', columnDef: { minSize: 80, maxSize: 200 } },
+		{ id: 'b', columnDef: { minSize: 20 } },
+	];
+
+	it('clamps each known id to its column bounds', () => {
+		expect(clampColumnSizing({ a: 40, b: 400 }, columns)).toEqual({ a: 80, b: 400 });
+		expect(clampColumnSizing({ a: 500 }, columns)).toEqual({ a: 200 });
+	});
+
+	it('uses table defaults for ids that are not in columns', () => {
+		expect(clampColumnSizing({ c: 10 }, columns)).toEqual({ c: RESIZE_MIN_COLUMN_WIDTH });
+	});
+
+	it('omits non-finite widths', () => {
+		expect(clampColumnSizing({ a: Number.NaN, b: Number.POSITIVE_INFINITY, c: 120 }, columns)).toEqual({
+			c: 120,
+		});
+	});
+});
+
+describe('getResizeOriginSize', () => {
+	it('uses columnDef.size when size was authored', () => {
+		expect(
+			getResizeOriginSize({ id: 'a', columnDef: { size: 200, meta: { hasExplicitSize: true } } }, 198),
+		).toBe(200);
+	});
+
+	it('uses columnDef.size when the authored size is TanStack’s default', () => {
+		expect(
+			getResizeOriginSize(
+				{ id: 'a', columnDef: { size: defaultColumnSizing.size, meta: { hasExplicitSize: true } } },
+				198,
+			),
+		).toBe(defaultColumnSizing.size);
+	});
+
+	it('uses the measured width for fill columns', () => {
+		expect(getResizeOriginSize({ id: 'a', columnDef: {} }, 387)).toBe(387);
+	});
+});
+
+describe('collectMissingLeafSizing', () => {
+	it('seeds only ids that are not already in columnSizing', () => {
+		expect(collectMissingLeafSizing({ a: 120.4, b: 200 }, { b: 180 })).toEqual({ a: 120 });
+	});
+
+	it('returns an empty map when every measured id already has a sizing entry', () => {
+		expect(collectMissingLeafSizing({ a: 100 }, { a: 90 })).toEqual({});
+	});
+});
+
+describe('omitBuiltinColumnSizing', () => {
+	it('drops select, expander, and reorder and keeps consumer ids', () => {
+		expect(
+			omitBuiltinColumnSizing({
+				[SELECT_COLUMN_ID]: 36,
+				[EXPANDER_COLUMN_ID]: 36,
+				[REORDER_COLUMN_ID]: 60,
+				firstName: 200,
+				lastName: 180,
+			}),
+		).toEqual({ firstName: 200, lastName: 180 });
+	});
+
+	it('returns an empty map when every id is a utility column', () => {
+		expect(
+			omitBuiltinColumnSizing({
+				[SELECT_COLUMN_ID]: 36,
+				[EXPANDER_COLUMN_ID]: 36,
+			}),
+		).toEqual({});
+	});
+
+	it('returns a copy when no utility ids are present', () => {
+		const sizing = { firstName: 200 };
+		const next = omitBuiltinColumnSizing(sizing);
+
+		expect(next).toEqual({ firstName: 200 });
+		expect(next).not.toBe(sizing);
+	});
+});

package/src/components/ds-table/utils/constants.ts

@@ -34,7 +34,35 @@ export const REORDER_COLUMN_ID = 'reorder';
  */
 export const REORDER_COLUMN_WIDTH = 60;
 
+/**
+ * Injected utility leaf ids (`select`, `expander`, `reorder`). Present in internal
+ * sizing for layout; omitted from the public `onColumnSizingChange` payload.
+ */
+export const BUILTIN_COLUMN_IDS: ReadonlySet<string> = Object.freeze(
+	new Set([SELECT_COLUMN_ID, EXPANDER_COLUMN_ID, REORDER_COLUMN_ID]),
+);
+
 /**
  * Number of placeholder skeleton rows rendered while the table is `loading`.
  */
 export const SKELETON_ROW_COUNT = 5;
+
+/**
+ * Default minimum width (in px) a column can be dragged to when
+ * `resizableColumns` is enabled. Overridable per column via `columnDef.minSize`
+ * (including values below this default). There is no default max; set
+ * `columnDef.maxSize` on a leaf to cap it.
+ */
+export const RESIZE_MIN_COLUMN_WIDTH = 52;
+
+/**
+ * Width change (in px) applied per Arrow key press when a resize handle is
+ * focused.
+ */
+export const RESIZE_KEYBOARD_STEP = 10;
+
+/**
+ * Larger width change (in px) applied when Shift is held with an Arrow key on a
+ * focused resize handle.
+ */
+export const RESIZE_KEYBOARD_STEP_LARGE = 40;

package/src/components/ds-table/utils/frozen-body.ts

@@ -0,0 +1,33 @@
+import type { Table as TanstackTable } from '@tanstack/react-table';
+
+/**
+ * `React.memo` comparator for the table body during a column-resize drag.
+ *
+ * While a column is being resized, sizing is applied through CSS variables on
+ * the table element, so body rows do not need to re-render — freezing them keeps
+ * dragging smooth. `table` is a stable mutable instance (ref-equal across
+ * renders), so comparing it is meaningless and it is skipped; every other prop
+ * must be referentially unchanged to freeze. That way parent-driven updates mid-
+ * drag (`rowSelection`, `emptyState`, `onScroll`, `infiniteScroll`, ...) are not
+ * dropped.
+ */
+export const areBodiesFrozen = <T>(
+	prev: { table: TanstackTable<T> },
+	next: { table: TanstackTable<T> },
+): boolean => {
+	if (!next.table.getState().columnSizingInfo.isResizingColumn) {
+		return false;
+	}
+
+	const prevProps = prev as unknown as Record<string, unknown>;
+	const nextProps = next as unknown as Record<string, unknown>;
+	const keys = new Set([...Object.keys(prevProps), ...Object.keys(nextProps)]);
+
+	for (const key of keys) {
+		if (key !== 'table' && prevProps[key] !== nextProps[key]) {
+			return false;
+		}
+	}
+
+	return true;
+};

package/src/components/ds-table/utils/frozen-body.unit.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, it } from 'vitest';
+import type { Table as TanstackTable } from '@tanstack/react-table';
+import { areBodiesFrozen } from './frozen-body';
+
+type Row = { id: string };
+
+const tableResizing = (isResizingColumn: string | false): TanstackTable<Row> =>
+	({ getState: () => ({ columnSizingInfo: { isResizingColumn } }) }) as unknown as TanstackTable<Row>;
+
+describe('areBodiesFrozen', () => {
+	it('never freezes when no column is being resized', () => {
+		const table = tableResizing(false);
+		const prev = { table, rowSelection: {} };
+		const next = { table, rowSelection: {} };
+
+		expect(areBodiesFrozen(prev, next)).toBe(false);
+	});
+
+	it('freezes during a resize when every non-table prop is unchanged', () => {
+		const table = tableResizing('firstName');
+		const rowSelection = {};
+		const emptyState = null;
+		const prev = { table, rowSelection, emptyState };
+		const next = { table, rowSelection, emptyState };
+
+		expect(areBodiesFrozen(prev, next)).toBe(true);
+	});
+
+	it('does not freeze when a non-table prop changes mid-resize', () => {
+		const table = tableResizing('firstName');
+		const prev = { table, rowSelection: {} };
+		const next = { table, rowSelection: { '1': true } };
+
+		expect(areBodiesFrozen(prev, next)).toBe(false);
+	});
+
+	it('ignores the identity of the stable table instance', () => {
+		const rowSelection = {};
+		const prev = { table: tableResizing('firstName'), rowSelection };
+		const next = { table: tableResizing('firstName'), rowSelection };
+
+		expect(areBodiesFrozen(prev, next)).toBe(true);
+	});
+});

package/src/components/ds-table/utils/table-api.ts

@@ -0,0 +1,42 @@
+import type { Table } from '@tanstack/react-table';
+import type { DsTableApi } from '../ds-table.types';
+
+export const createTableApi = <TData>(table: Table<TData>): DsTableApi<TData> => ({
+	selectRow: (rowId: string) => {
+		table.getRow(rowId).toggleSelected(true);
+	},
+	deselectRow: (rowId: string) => {
+		table.getRow(rowId).toggleSelected(false);
+	},
+	selectAllRows: () => {
+		table.toggleAllRowsSelected(true);
+	},
+	deselectAllRows: () => {
+		table.toggleAllRowsSelected(false);
+	},
+	selectRows: (rowIds: string[]) => {
+		const selection: Record<string, boolean> = {};
+		rowIds.forEach((id) => (selection[id] = true));
+		table.setRowSelection(selection);
+	},
+	getSelectedRows: () => {
+		return table.getFilteredSelectedRowModel().rows.map((r) => r.original);
+	},
+	expandRow: (rowId: string) => {
+		table.getRow(rowId).toggleExpanded(true);
+	},
+	collapseRow: (rowId: string) => {
+		table.getRow(rowId).toggleExpanded(false);
+	},
+	expandAllRows: () => {
+		table.toggleAllRowsExpanded(true);
+	},
+	collapseAllRows: () => {
+		table.toggleAllRowsExpanded(false);
+	},
+	expandRows: (rowIds: string[]) => {
+		const expansion: Record<string, boolean> = {};
+		rowIds.forEach((id) => (expansion[id] = true));
+		table.setExpanded(expansion);
+	},
+});

package/src/components/ds-table/utils/table-api.unit.test.ts

@@ -0,0 +1,82 @@
+import { describe, expect, it, vi } from 'vitest';
+import type { Table } from '@tanstack/react-table';
+import { createTableApi } from './table-api';
+
+type Person = { id: string; name: string };
+
+const alice: Person = { id: 'a', name: 'Alice' };
+const bob: Person = { id: 'b', name: 'Bob' };
+
+const createMockTable = () => {
+	const toggleSelected = vi.fn();
+	const toggleExpanded = vi.fn();
+	const toggleAllRowsSelected = vi.fn();
+	const toggleAllRowsExpanded = vi.fn();
+	const setRowSelection = vi.fn();
+	const setExpanded = vi.fn();
+	const getRow = vi.fn(() => ({ toggleSelected, toggleExpanded }));
+	const getFilteredSelectedRowModel = vi.fn(() => ({
+		rows: [{ original: alice }, { original: bob }],
+	}));
+
+	const table = {
+		getRow,
+		toggleAllRowsSelected,
+		toggleAllRowsExpanded,
+		setRowSelection,
+		setExpanded,
+		getFilteredSelectedRowModel,
+	} as unknown as Table<Person>;
+
+	return {
+		table,
+		toggleSelected,
+		toggleExpanded,
+		toggleAllRowsSelected,
+		toggleAllRowsExpanded,
+		setRowSelection,
+		setExpanded,
+		getRow,
+	};
+};
+
+describe('createTableApi', () => {
+	it('maps selection methods onto the table instance', () => {
+		const mock = createMockTable();
+		const api = createTableApi(mock.table);
+
+		api.selectRow('a');
+		api.deselectRow('b');
+		api.selectAllRows();
+		api.deselectAllRows();
+		api.selectRows(['a', 'b']);
+
+		expect(mock.getRow).toHaveBeenCalledWith('a');
+		expect(mock.getRow).toHaveBeenCalledWith('b');
+		expect(mock.toggleSelected).toHaveBeenCalledWith(true);
+		expect(mock.toggleSelected).toHaveBeenCalledWith(false);
+		expect(mock.toggleAllRowsSelected).toHaveBeenCalledWith(true);
+		expect(mock.toggleAllRowsSelected).toHaveBeenCalledWith(false);
+		expect(mock.setRowSelection).toHaveBeenCalledWith({ a: true, b: true });
+		expect(api.getSelectedRows()).toEqual([alice, bob]);
+	});
+
+	it('maps expand methods onto the table instance', () => {
+		const mock = createMockTable();
+		const api = createTableApi(mock.table);
+
+		api.expandRow('a');
+		api.collapseRow('b');
+		api.expandAllRows();
+		api.collapseAllRows();
+		api.expandRows(['a', 'b']);
+
+		expect(mock.getRow).toHaveBeenCalledWith('a');
+		expect(mock.getRow).toHaveBeenCalledWith('b');
+		expect(mock.toggleExpanded).toHaveBeenCalledWith(true);
+		expect(mock.toggleExpanded).toHaveBeenCalledWith(false);
+		expect(mock.toggleAllRowsExpanded).toHaveBeenCalledWith(true);
+		expect(mock.toggleAllRowsExpanded).toHaveBeenCalledWith(false);
+		expect(mock.setExpanded).toHaveBeenCalledWith({ a: true, b: true });
+	});
+});