@drivenets/design-system 0.13.0 → 0.14.0

package/src/components/ds-table/components/ds-table-body-virtualized/ds-table-body-virtualized.tsx

@@ -110,7 +110,7 @@ interface DsTableBodyProps<TData> {
 	rowSelection: RowSelectionState;
 }
 
-function DsTableBody<TData>({
+export function DsTableBody<TData>({
 	ref,
 	rowVirtualizer,
 	rowsMapRef,
@@ -122,6 +122,11 @@ function DsTableBody<TData>({
 	const virtualRows = rowVirtualizer.getVirtualItems();
 	const totalSize = rowVirtualizer.getTotalSize();
 
+	// Gate the empty state on real data count, not on rendered virtual rows.
+	// getVirtualItems() transiently returns [] while the virtualizer re-measures
+	// after a `data` swap; rendering nothing for that frame avoids an empty-state flash.
+	const hasNoData = rowsAndExpandedRowContent.length === 0;
+
 	return (
 		<TableBody ref={ref} className={styles.body}>
 			{virtualRows.length > 0 ? (
@@ -144,11 +149,11 @@ function DsTableBody<TData>({
 						/>
 					);
 				})
-			) : (
+			) : hasNoData ? (
 				<TableRow>
 					<TableCell className={styles.emptyState}>{emptyState || EMPTY_TABLE_STATE_TEXT}</TableCell>
 				</TableRow>
-			)}
+			) : null}
 
 			<tr aria-hidden className={styles.sentinel} style={{ top: `${totalSize.toString()}px` }}>
 				<td />

package/src/components/ds-table/components/ds-table-group-header-cell/ds-table-group-header-cell.module.scss

@@ -0,0 +1,31 @@
+@use '../../../../styles/typography';
+@use '../../styles/variables' as vars;
+
+.groupHeaderCell {
+	@include typography.body-sm-md;
+	color: var(--font-main);
+	height: var(--ds-table-header-height);
+	padding: 0;
+	border-bottom: vars.$border-width solid var(--color-dap-gray-400);
+	border-left: vars.$group-border-width solid var(--border);
+}
+
+.groupHeaderContent {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	gap: vars.$header-sort-gap;
+	width: 100%;
+	height: 100%;
+	padding: 0 var(--standard);
+}
+
+.groupLabel {
+	overflow: hidden;
+	text-overflow: ellipsis;
+	white-space: nowrap;
+}
+
+.collapseToggle {
+	flex-shrink: 0;
+}

package/src/components/ds-table/components/ds-table-group-header-cell/ds-table-group-header-cell.tsx

@@ -0,0 +1,48 @@
+import { flexRender } from '@tanstack/react-table';
+import { DsButtonV3 } from '../../../ds-button-v3';
+import { TableHead } from '../core-table';
+import { useDsTableContext } from '../../context/ds-table-context';
+import { getGroupColumnSizeStyle } from '../../grouping';
+import { defaultDsTableLocale } from '../../ds-table.types';
+import type { DsTableGroupHeaderCellProps } from './ds-table-group-header-cell.types';
+import styles from './ds-table-group-header-cell.module.scss';
+
+export const DsTableGroupHeaderCell = <TData, TValue>({
+	header,
+}: DsTableGroupHeaderCellProps<TData, TValue>) => {
+	const { collapsedColumnGroups, onToggleColumnGroup, locale } = useDsTableContext<TData, TValue>();
+
+	const groupId = header.column.id;
+	const visibleLeafColumns = header.column.getLeafColumns().filter((leaf) => leaf.getIsVisible());
+	const groupStyle = getGroupColumnSizeStyle(visibleLeafColumns);
+
+	const isCollapsible = header.column.columnDef.meta?.group?.collapsible ?? false;
+	const isCollapsed = collapsedColumnGroups?.includes(groupId) ?? false;
+
+	const mergedLocale = { ...defaultDsTableLocale, ...locale };
+	const toggleLabel = isCollapsed ? mergedLocale.expandColumnGroup : mergedLocale.collapseColumnGroup;
+
+	const handleToggle = () => onToggleColumnGroup?.(groupId);
+
+	return (
+		<TableHead className={styles.groupHeaderCell} style={groupStyle} colSpan={header.colSpan}>
+			<div className={styles.groupHeaderContent}>
+				<span className={styles.groupLabel}>
+					{flexRender(header.column.columnDef.header, header.getContext())}
+				</span>
+				{isCollapsible && (
+					<DsButtonV3
+						variant="secondary"
+						size="tiny"
+						icon={isCollapsed ? 'chevron_right' : 'chevron_left'}
+						className={styles.collapseToggle}
+						aria-label={toggleLabel}
+						aria-expanded={!isCollapsed}
+						title={toggleLabel}
+						onClick={handleToggle}
+					/>
+				)}
+			</div>
+		</TableHead>
+	);
+};

package/src/components/ds-table/components/ds-table-group-header-cell/ds-table-group-header-cell.types.ts

@@ -0,0 +1,12 @@
+import type { Header } from '@tanstack/react-table';
+
+/**
+ * Props for the grouping column header cell.
+ */
+export interface DsTableGroupHeaderCellProps<TData, TValue> {
+	/**
+	 * The grouping header from `@tanstack/react-table` (a header whose column nests
+	 * child columns).
+	 */
+	header: Header<TData, TValue>;
+}

package/src/components/ds-table/components/ds-table-group-header-cell/index.ts

@@ -0,0 +1,2 @@
+export { DsTableGroupHeaderCell } from './ds-table-group-header-cell';
+export type { DsTableGroupHeaderCellProps } from './ds-table-group-header-cell.types';

package/src/components/ds-table/components/ds-table-header/ds-table-header.module.scss

@@ -57,6 +57,10 @@
 	justify-content: center;
 }
 
+.groupStart {
+	border-left: vars.$group-border-width solid var(--border);
+}
+
 .headerSortContainer {
 	display: flex;
 	align-items: center;

package/src/components/ds-table/components/ds-table-header/ds-table-header.tsx

@@ -11,6 +11,8 @@ import { SELECT_COLUMN_ID } from '../../utils/constants';
 import { DsStack } from '../../../ds-stack';
 import { DsTableColumnFilterPopover } from '../../filters/components/column-filter-popover';
 import type { ResolvedColumnFilter } from '../../filters/types/filter-adapter.types';
+import { DsTableGroupHeaderCell } from '../ds-table-group-header-cell';
+import { isFirstLeafColumnOfGroup } from '../../grouping';
 
 const DsTableHeader = <TData,>({ table }: DsTableHeaderProps<TData>) => {
 	const { stickyHeader, bordered, virtualized } = useDsTableContext<TData, unknown>();
@@ -29,9 +31,24 @@ const DsTableHeader = <TData,>({ table }: DsTableHeaderProps<TData>) => {
 					)}
 				>
 					{headerGroup.headers.map((header) => {
+						if (header.isPlaceholder) {
+							return (
+								<TableHead
+									key={header.id}
+									className={styles.headerCell}
+									style={getColumnSizeStyle(header.getSize())}
+								/>
+							);
+						}
+
+						if (header.subHeaders.length > 0) {
+							return <DsTableGroupHeaderCell key={header.id} header={header} />;
+						}
+
 						const headerStyle = getColumnSizeStyle(header.column.getSize());
 						const canSort = header.column.getCanSort();
 						const isSelectColumn = header.column.id === SELECT_COLUMN_ID;
+						const isGroupStart = isFirstLeafColumnOfGroup(header.column);
 
 						const metaFilter = header.column.columnDef.meta?.filter;
 						const resolvedFilter: ResolvedColumnFilter | undefined =
@@ -47,49 +64,48 @@ const DsTableHeader = <TData,>({ table }: DsTableHeaderProps<TData>) => {
 									isSelectColumn && styles.selectHeaderCell,
 									resolvedFilter && styles.filterableHeader,
 									hasActiveColumnFilter && styles.filterActive,
+									isGroupStart && styles.groupStart,
 								)}
 								onClick={header.column.getToggleSortingHandler()}
 								style={headerStyle}
 							>
-								{header.isPlaceholder ? null : (
-									<div className={styles.headerSortContainer}>
-										<DsStack direction="column" justifyContent="center" width="100%">
-											{flexRender(header.column.columnDef.header, header.getContext())}
-										</DsStack>
-										{canSort && (
-											<div className={styles.pageButtonIconContainer}>
-												{{
-													asc: (
-														<DsIcon
-															icon="arrow_drop_up"
-															className={classnames(styles.pageButtonIcon, stylesShared.pageButtonIcon)}
-														/>
-													),
-													desc: (
-														<DsIcon
-															icon="arrow_drop_down"
-															className={classnames(styles.pageButtonIcon, stylesShared.pageButtonIcon)}
-														/>
-													),
-												}[header.column.getIsSorted() as string] ?? (
-													<div className={classnames(styles.pageButtonIcon, stylesShared.pageButtonIcon)} />
-												)}
-											</div>
-										)}
-										{resolvedFilter && (
-											<div className={styles.filterTriggerContainer}>
-												<DsTableColumnFilterPopover
-													hasActiveFilter={resolvedFilter.hasActiveFilter}
-													onApply={resolvedFilter.onApply}
-													onClear={resolvedFilter.onClear}
-													onCancel={resolvedFilter.onCancel}
-												>
-													{resolvedFilter.render()}
-												</DsTableColumnFilterPopover>
-											</div>
-										)}
-									</div>
-								)}
+								<div className={styles.headerSortContainer}>
+									<DsStack direction="column" justifyContent="center" width="100%">
+										{flexRender(header.column.columnDef.header, header.getContext())}
+									</DsStack>
+									{canSort && (
+										<div className={styles.pageButtonIconContainer}>
+											{{
+												asc: (
+													<DsIcon
+														icon="arrow_drop_up"
+														className={classnames(styles.pageButtonIcon, stylesShared.pageButtonIcon)}
+													/>
+												),
+												desc: (
+													<DsIcon
+														icon="arrow_drop_down"
+														className={classnames(styles.pageButtonIcon, stylesShared.pageButtonIcon)}
+													/>
+												),
+											}[header.column.getIsSorted() as string] ?? (
+												<div className={classnames(styles.pageButtonIcon, stylesShared.pageButtonIcon)} />
+											)}
+										</div>
+									)}
+									{resolvedFilter && (
+										<div className={styles.filterTriggerContainer}>
+											<DsTableColumnFilterPopover
+												hasActiveFilter={resolvedFilter.hasActiveFilter}
+												onApply={resolvedFilter.onApply}
+												onClear={resolvedFilter.onClear}
+												onCancel={resolvedFilter.onCancel}
+											>
+												{resolvedFilter.render()}
+											</DsTableColumnFilterPopover>
+										</div>
+									)}
+								</div>
 							</TableHead>
 						);
 					})}

package/src/components/ds-table/components/ds-table-row/ds-table-row.module.scss

@@ -85,6 +85,10 @@
 	justify-content: center;
 }
 
+.groupStart {
+	border-left: vars.$group-border-width solid var(--border);
+}
+
 .tableRow .editableCell {
 	padding: 1px;
 

package/src/components/ds-table/components/ds-table-row/ds-table-row.tsx

@@ -10,6 +10,7 @@ import styles from './ds-table-row.module.scss';
 import { useDsTableContext } from '../../context/ds-table-context';
 import { mergeRefs } from '../../../../utils/merge-refs';
 import { getColumnSizeStyle } from '../../utils/column-size';
+import { isFirstLeafColumnOfGroup } from '../../grouping';
 import { EXPANDER_COLUMN_ID, REORDER_COLUMN_ID, SELECT_COLUMN_ID } from '../../utils/constants';
 
 interface DsRowDragHandleProps {
@@ -118,6 +119,7 @@ const DsTableRow = <TData,>({ ref, row, isSelected }: DsTableRowProps<TData>) =>
 								styles.tableCell,
 								cell.column.id === EXPANDER_COLUMN_ID && styles.expandableCell,
 								cell.column.id === SELECT_COLUMN_ID && styles.selectableCell,
+								isFirstLeafColumnOfGroup(cell.column) && styles.groupStart,
 								typeof cell.column.columnDef.editCell === 'function' && styles.editableCell,
 							)}
 							style={cellStyle}

package/src/components/ds-table/components/ds-table-row-virtualized/ds-table-row-virtualized.module.scss

@@ -66,6 +66,10 @@
 	justify-content: center;
 }
 
+.groupStart {
+	border-left: vars.$group-border-width solid var(--border);
+}
+
 .expandedRowContent {
 	background-color: var(--background-secondary);
 

package/src/components/ds-table/components/ds-table-row-virtualized/ds-table-row-virtualized.tsx

@@ -2,6 +2,7 @@ import classnames from 'classnames';
 import styles from './ds-table-row-virtualized.module.scss';
 import { useDsTableContext } from '../../context/ds-table-context';
 import { getColumnSizeStyle } from '../../utils/column-size';
+import { isFirstLeafColumnOfGroup } from '../../grouping';
 import { TableCell, TableRow } from '../core-table';
 import type { DsTableRowVirtualizedProps } from './ds-table-row-virtualized.types';
 import { DsTableCell } from '../ds-table-cell';
@@ -77,6 +78,7 @@ export const DsTableRowVirtualized = <TData,>({
 									styles.cell,
 									cell.column.id === EXPANDER_COLUMN_ID && styles.expandableCell,
 									cell.column.id === SELECT_COLUMN_ID && styles.selectableCell,
+									isFirstLeafColumnOfGroup(cell.column) && styles.groupStart,
 									typeof cell.column.columnDef.editCell === 'function' && styles.editableCell,
 								)}
 							>

package/src/components/ds-table/context/ds-table-context.ts

@@ -23,6 +23,10 @@ export interface DsTableContextType<TData, TValue> extends Partial<DsDataTablePr
 	 * ID of the currently active row
 	 */
 	activeRowId?: string | null;
+	/**
+	 * Toggles the collapsed state of a column group by its id.
+	 */
+	onToggleColumnGroup?: (groupId: string) => void;
 	/** The cell currently in edit mode, if any. */
 	editing: EditingState<TData, TValue> | null;
 	beginEdit: (cell: Cell<TData, TValue>) => void;

package/src/components/ds-table/ds-table.tsx

@@ -25,6 +25,7 @@ import { DsTableHeaderSelectableCell } from './components/ds-table-header-select
 import { useDragAndDrop } from './hooks/use-drag-and-drop';
 import { type DsTableContextType, DsTableContext, useEditingState } from './context/ds-table-context';
 import { DsTableBodyVirtualized } from './components/ds-table-body-virtualized';
+import { useColumnGroups } from './grouping';
 import {
 	EMPTY_TABLE_STATE_TEXT,
 	EXPANDER_COLUMN_ID,
@@ -75,6 +76,9 @@ const DsTable = <TData extends { id: string }, TValue>({
 	onColumnFiltersChange,
 	columnVisibility: externalColumnVisibility,
 	onColumnVisibilityChange,
+	collapsedColumnGroups: externalCollapsedColumnGroups,
+	onCollapsedColumnGroupsChange,
+	locale,
 	activeRowId,
 	infiniteScroll,
 	onCellEdit,
@@ -109,12 +113,12 @@ const DsTable = <TData extends { id: string }, TValue>({
 		}
 	};
 
-	const columnVisibility = externalColumnVisibility ?? internalColumnVisibility;
+	const baseColumnVisibility = externalColumnVisibility ?? internalColumnVisibility;
 	const handleColumnVisibilityChange = (
 		updaterOrValue: VisibilityState | ((old: VisibilityState) => VisibilityState),
 	) => {
 		const newVisibility =
-			typeof updaterOrValue === 'function' ? updaterOrValue(columnVisibility) : updaterOrValue;
+			typeof updaterOrValue === 'function' ? updaterOrValue(baseColumnVisibility) : updaterOrValue;
 
 		if (onColumnVisibilityChange) {
 			onColumnVisibilityChange(newVisibility);
@@ -123,6 +127,17 @@ const DsTable = <TData extends { id: string }, TValue>({
 		}
 	};
 
+	const { collapsedColumnGroups, toggleColumnGroup, collapsedVisibility } = useColumnGroups({
+		columns: columnsProp,
+		collapsedColumnGroups: externalCollapsedColumnGroups,
+		onCollapsedColumnGroupsChange,
+	});
+
+	const columnVisibility = useMemo(
+		() => ({ ...baseColumnVisibility, ...collapsedVisibility }),
+		[baseColumnVisibility, collapsedVisibility],
+	);
+
 	const handleSortingChange = (updaterOrValue: SortingState | ((old: SortingState) => SortingState)) => {
 		const newSorting = typeof updaterOrValue === 'function' ? updaterOrValue(sorting) : updaterOrValue;
 		setSorting(newSorting);
@@ -287,6 +302,9 @@ const DsTable = <TData extends { id: string }, TValue>({
 		renderExpandedRow,
 		virtualized,
 		activeRowId,
+		collapsedColumnGroups,
+		onToggleColumnGroup: toggleColumnGroup,
+		locale,
 		onCellEdit,
 		...editingState,
 	};

package/src/components/ds-table/ds-table.types.ts

@@ -16,6 +16,31 @@ import type { InfiniteScrollConfig, ScrollParams } from './components/ds-table-b
  */
 export type DsTableRowSize = 'small' | 'medium' | 'large';
 
+/**
+ * Overridable, user-facing strings used by the table (e.g. accessible labels for
+ * the column-group collapse toggle). Pass a partial object via the `locale` prop
+ * to localize.
+ */
+export interface DsTableLocale {
+	/**
+	 * Accessible label for the toggle that collapses a column group.
+	 */
+	collapseColumnGroup: string;
+
+	/**
+	 * Accessible label for the toggle that expands a column group.
+	 */
+	expandColumnGroup: string;
+}
+
+/**
+ * Default English strings for {@link DsTableLocale}.
+ */
+export const defaultDsTableLocale: DsTableLocale = Object.freeze({
+	collapseColumnGroup: 'Collapse column group',
+	expandColumnGroup: 'Expand column group',
+});
+
 /**
  * API for programmatically controlling a DsTable component.
  * This interface provides methods to interact with the table's selection, sorting, filtering, and pagination features.
@@ -442,6 +467,36 @@ export interface DsDataTableProps<TData, TValue> {
 	 */
 	onColumnVisibilityChange?: (visibility: VisibilityState) => void;
 
+	/**
+	 * Controlled list of collapsed column-group ids. A group is collapsible when its
+	 * column def sets `meta.group.collapsible`; collapsing hides every leaf column in
+	 * the group except those marked `meta.keepVisibleWhenCollapsed`. Omit for
+	 * uncontrolled behavior (seeded from `meta.group.defaultCollapsed`).
+	 *
+	 * @example
+	 * ```tsx
+	 * const [collapsed, setCollapsed] = useState<string[]>(['equipment']);
+	 *
+	 * <DsTable
+	 *   collapsedColumnGroups={collapsed}
+	 *   onCollapsedColumnGroupsChange={setCollapsed}
+	 * />
+	 * ```
+	 */
+	collapsedColumnGroups?: string[];
+
+	/**
+	 * Callback fired with the next list of collapsed group ids when a group's
+	 * collapse toggle is clicked.
+	 */
+	onCollapsedColumnGroupsChange?: (collapsedGroupIds: string[]) => void;
+
+	/**
+	 * Overrides for user-facing strings (e.g. column-group toggle labels). Merged
+	 * over the built-in English defaults.
+	 */
+	locale?: Partial<DsTableLocale>;
+
 	/**
 	 * Callback fired when an editable cell commits a new value via one of the
 	 * `DsTableEditCell*` wrappers or the `useCellEditor` hook. The parent is

package/src/components/ds-table/figma/ds-table-expandable.figma.ts

@@ -0,0 +1,17 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=36535-44213
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-table
+// component=DsTable
+//
+// `DAP_Table Expandable_v03` is the expandable table on the "Table New (Data grid)"
+// page. It maps to the same `DsTable` code component as the simple table, with the
+// `expandable` prop enabled and a `renderExpandedRow` callback for the nested content.
+// The Simple vs Expandable split exists only because of a Figma restriction (a
+// component can't contain an instance of itself); in code it's one `DsTable`.
+import figma from 'figma';
+
+export default {
+	example: figma.code`<DsTable columns={columns} data={data} expandable renderExpandedRow={(row) => null} />`,
+	imports: ["import { DsTable } from '@drivenets/design-system'"],
+	id: 'ds-table-expandable',
+	metadata: { nestable: false },
+};

package/src/components/ds-table/figma/ds-table.figma.ts

@@ -0,0 +1,16 @@
+// url=https://www.figma.com/design/nha3m67y7S57cHCSuQO2gp/DAP-Design-System-1.2?node-id=36354-1965
+// source=https://github.com/drivenets/design-system/tree/main/packages/design-system/src/components/ds-table
+// component=DsTable
+//
+// `DAP_Table Simple_v03` is the non-expandable table on the "Table New (Data grid)"
+// page. Figma models the table as separate components (header/row/cell),
+// while code exposes a single declarative `DsTable` driven by `columns`/`data`,
+// so the snippet is a representative usage that references those consts.
+import figma from 'figma';
+
+export default {
+	example: figma.code`<DsTable columns={columns} data={data} />`,
+	imports: ["import { DsTable } from '@drivenets/design-system'"],
+	id: 'ds-table',
+	metadata: { nestable: false },
+};

package/src/components/ds-table/grouping/hooks/use-column-groups.ts

@@ -0,0 +1,73 @@
+import { useMemo } from 'react';
+import type { ColumnDef, VisibilityState } from '@tanstack/react-table';
+import { useControlled } from '../../../../utils/use-controlled';
+import { getCollapsedColumnVisibility, getInitialCollapsedGroups } from '../utils/column-group';
+
+interface UseColumnGroupsParams<TData, TValue> {
+	/**
+	 * Consumer-provided columns (before utility columns are injected). Group defs
+	 * nest child columns via `columns`.
+	 */
+	columns: ColumnDef<TData, TValue>[];
+
+	/**
+	 * Controlled list of collapsed group ids. When provided, the table no longer
+	 * manages collapse state internally.
+	 */
+	collapsedColumnGroups?: string[];
+
+	/**
+	 * Called with the next list of collapsed group ids whenever a group is toggled.
+	 */
+	onCollapsedColumnGroupsChange?: (collapsedGroupIds: string[]) => void;
+}
+
+interface UseColumnGroupsResult {
+	/**
+	 * The effective list of collapsed group ids (controlled or internal).
+	 */
+	collapsedColumnGroups: string[];
+
+	/**
+	 * Toggles a single group's collapsed state.
+	 */
+	toggleColumnGroup: (groupId: string) => void;
+
+	/**
+	 * Visibility overrides derived from the collapsed groups, to be layered on top
+	 * of the consumer's own column visibility.
+	 */
+	collapsedVisibility: VisibilityState;
+}
+
+/**
+ * Manages column-group collapse state. Supports both controlled
+ * (`collapsedColumnGroups` + `onCollapsedColumnGroupsChange`) and uncontrolled
+ * usage (seeded from `meta.group.defaultCollapsed`).
+ */
+export const useColumnGroups = <TData, TValue>({
+	columns,
+	collapsedColumnGroups,
+	onCollapsedColumnGroupsChange,
+}: UseColumnGroupsParams<TData, TValue>): UseColumnGroupsResult => {
+	const [collapsed, setCollapsed] = useControlled(
+		collapsedColumnGroups,
+		onCollapsedColumnGroupsChange,
+		getInitialCollapsedGroups(columns),
+	);
+
+	const toggleColumnGroup = (groupId: string) => {
+		const next = collapsed.includes(groupId)
+			? collapsed.filter((id) => id !== groupId)
+			: [...collapsed, groupId];
+
+		setCollapsed(next);
+	};
+
+	const collapsedVisibility = useMemo(
+		() => getCollapsedColumnVisibility(columns, collapsed),
+		[columns, collapsed],
+	);
+
+	return { collapsedColumnGroups: collapsed, toggleColumnGroup, collapsedVisibility };
+};

package/src/components/ds-table/grouping/index.ts

@@ -0,0 +1,5 @@
+import './types/column-group-meta.augmentation';
+
+export type { DsColumnGroupMeta } from './types/column-group.types';
+export { useColumnGroups } from './hooks/use-column-groups';
+export { getGroupColumnSizeStyle, isFirstLeafColumnOfGroup } from './utils/column-group';

package/src/components/ds-table/grouping/types/column-group-meta.augmentation.ts

@@ -0,0 +1,26 @@
+import '@tanstack/react-table';
+import type { DsColumnGroupMeta } from './column-group.types';
+
+declare module '@tanstack/react-table' {
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	interface ColumnMeta<TData, TValue> {
+		/**
+		 * Set on a grouping column def (one that nests child `columns`) to configure
+		 * the group header and its collapse behavior.
+		 */
+		group?: DsColumnGroupMeta;
+
+		/**
+		 * Set on a leaf column to keep it visible while its parent group is collapsed
+		 * (e.g. a key identifier column that should always stay on screen).
+		 *
+		 * Only affects the collapsed state. When `false` or omitted (the default),
+		 * the column is hidden while the group is collapsed and shown again when the
+		 * group is expanded — it is never permanently hidden by this flag.
+		 * @default false
+		 */
+		keepVisibleWhenCollapsed?: boolean;
+	}
+}
+
+export {};

package/src/components/ds-table/grouping/types/column-group.types.ts

@@ -0,0 +1,35 @@
+/**
+ * Configuration for a grouping column, set on a column definition that nests
+ * child columns via TanStack's `columns` array. Lives under `meta.group`.
+ *
+ * @example
+ * ```tsx
+ * const columns: ColumnDef<Row>[] = [
+ *   {
+ *     id: 'equipment',
+ *     header: 'Equipment',
+ *     meta: { group: { collapsible: true } },
+ *     columns: [
+ *       { accessorKey: 'cabinetType', header: 'Cabinet Type', meta: { keepVisibleWhenCollapsed: true } },
+ *       { accessorKey: 'shelf', header: 'Shelf#' },
+ *     ],
+ *   },
+ * ];
+ * ```
+ */
+export interface DsColumnGroupMeta {
+	/**
+	 * Renders a collapse/expand toggle in the group header. When collapsed, every
+	 * leaf column in the group is hidden except those marked
+	 * `meta.keepVisibleWhenCollapsed`.
+	 * @default false
+	 */
+	collapsible?: boolean;
+
+	/**
+	 * When the table manages collapse state internally (uncontrolled), start this
+	 * group collapsed. Ignored once `collapsedColumnGroups` is provided.
+	 * @default false
+	 */
+	defaultCollapsed?: boolean;
+}