@drivenets/design-system 0.0.1

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

@@ -0,0 +1,312 @@
+import * as React from 'react';
+import { useImperativeHandle } from 'react';
+import {
+	type RowSelectionState,
+	type ColumnFiltersState,
+	getCoreRowModel,
+	getFilteredRowModel,
+	getSortedRowModel,
+	type SortingState,
+	useReactTable,
+	type VisibilityState,
+} from '@tanstack/react-table';
+import { useVirtualizer, type VirtualItem } from '@tanstack/react-virtual';
+import classnames from 'classnames';
+import { Table, TableBody, TableCell, TableRow } from './components/core-table';
+import { DsTableBulkActions } from './components/ds-table-bulk-actions';
+import { DsTableHeader } from './components/ds-table-header';
+import styles from './ds-table.module.scss';
+import type { DsDataTableProps, DsTableRowSize } from './ds-table.types';
+import { DsTableRow } from './components/ds-table-row';
+import { useDragAndDrop } from './hooks/use-drag-and-drop';
+import { type DsTableContextType, DsTableContext } from './context/ds-table-context';
+import { createColumnsGridTemplate } from './utils/create-columns-grid-template';
+
+// Row size to pixel height mapping (matches CSS variables)
+const ROW_SIZE_HEIGHT_MAP: Record<DsTableRowSize, number> = {
+	small: 36,
+	medium: 48,
+	large: 64,
+};
+
+/**
+ * Design system Table component
+ */
+const DsTable = <TData extends { id: string }, TValue>({
+	ref,
+	columns,
+	data: tableData,
+	virtualized = false,
+	virtualizedOptions,
+	className,
+	onRowClick,
+	emptyState,
+	stickyHeader = true,
+	bordered = true,
+	fullWidth = true,
+	highlightOnHover = true,
+	rowSize = 'medium',
+	expandable = false,
+	renderExpandedRow,
+	selectable = false,
+	showSelectAllCheckbox = true,
+	onSelectionChange,
+	onSortingChange,
+	onScroll,
+	actions = [],
+	onRowDoubleClick,
+	primaryRowActions = [],
+	secondaryRowActions,
+	reorderable = false,
+	onOrderChange,
+	columnFilters: externalColumnFilters,
+	onColumnFiltersChange,
+	columnVisibility: externalColumnVisibility,
+	onColumnVisibilityChange,
+	activeRowId,
+}: DsDataTableProps<TData, TValue>) => {
+	const [data, setData] = React.useState(tableData);
+	const [sorting, setSorting] = React.useState<SortingState>([]);
+	const [internalColumnFilters, setInternalColumnFilters] = React.useState<ColumnFiltersState>([]);
+	const [internalColumnVisibility, setInternalColumnVisibility] = React.useState<VisibilityState>({});
+	const [rowSelection, setRowSelection] = React.useState<RowSelectionState>({});
+	const [expandedRows, setExpandedRows] = React.useState<Record<string, boolean>>({});
+
+	const { DragWrapper, SortableWrapper } = useDragAndDrop<TData>({
+		isDragEnabled: reorderable && !virtualized,
+		onOrderChange: (newData) => {
+			setData(newData);
+			onOrderChange?.(newData);
+		},
+		items: data,
+	});
+
+	const tableContainerRef = React.useRef<HTMLDivElement>(null);
+
+	const columnFilters = externalColumnFilters ?? internalColumnFilters;
+	const handleColumnFiltersChange = (
+		updaterOrValue: ColumnFiltersState | ((old: ColumnFiltersState) => ColumnFiltersState),
+	) => {
+		const newFilters = typeof updaterOrValue === 'function' ? updaterOrValue(columnFilters) : updaterOrValue;
+		if (onColumnFiltersChange) {
+			onColumnFiltersChange(newFilters);
+		} else {
+			setInternalColumnFilters(newFilters);
+		}
+	};
+
+	const columnVisibility = externalColumnVisibility ?? internalColumnVisibility;
+	const handleColumnVisibilityChange = (
+		updaterOrValue: VisibilityState | ((old: VisibilityState) => VisibilityState),
+	) => {
+		const newVisibility =
+			typeof updaterOrValue === 'function' ? updaterOrValue(columnVisibility) : updaterOrValue;
+
+		if (onColumnVisibilityChange) {
+			onColumnVisibilityChange(newVisibility);
+		} else {
+			setInternalColumnVisibility(newVisibility);
+		}
+	};
+
+	const handleSortingChange = (updaterOrValue: SortingState | ((old: SortingState) => SortingState)) => {
+		const newSorting = typeof updaterOrValue === 'function' ? updaterOrValue(sorting) : updaterOrValue;
+		setSorting(newSorting);
+		onSortingChange?.(newSorting);
+	};
+
+	const handleRowSelectionChange = (
+		updaterOrValue: RowSelectionState | ((old: RowSelectionState) => RowSelectionState),
+	) => {
+		const newRowSelection =
+			typeof updaterOrValue === 'function' ? updaterOrValue(rowSelection) : updaterOrValue;
+		setRowSelection(newRowSelection);
+		onSelectionChange?.(newRowSelection);
+	};
+
+	const table = useReactTable({
+		data: reorderable ? data : tableData,
+		columns,
+		getCoreRowModel: getCoreRowModel(),
+		onSortingChange: handleSortingChange,
+		getSortedRowModel: getSortedRowModel(),
+		onColumnFiltersChange: handleColumnFiltersChange,
+		getFilteredRowModel: getFilteredRowModel(),
+		onColumnVisibilityChange: handleColumnVisibilityChange,
+		onRowSelectionChange: handleRowSelectionChange,
+		getRowId: (row) => row.id,
+		state: {
+			sorting,
+			columnFilters,
+			columnVisibility,
+			rowSelection,
+		},
+		enableRowSelection: typeof selectable === 'function' ? (row) => selectable(row.original) : selectable,
+	});
+
+	useImperativeHandle(
+		ref,
+		() => ({
+			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);
+			},
+		}),
+		[table],
+	);
+
+	const { rows, rowsById } = table.getRowModel();
+
+	const rowVirtualizer = useVirtualizer({
+		count: rows.length,
+		getScrollElement: () => tableContainerRef.current,
+		// estimate row height for accurate scrollbar dragging
+		estimateSize: () => virtualizedOptions?.estimateSize || ROW_SIZE_HEIGHT_MAP[rowSize],
+		overscan: virtualizedOptions?.overscan || 5,
+		onChange: (instance, sync) => {
+			if (sync && onScroll) {
+				const scrollOffset = instance.scrollOffset || 0;
+				const totalContentHeight = instance.getTotalSize();
+				const viewportHeight = instance.scrollElement?.clientHeight;
+
+				if (viewportHeight) {
+					onScroll({ scrollOffset, totalContentHeight, viewportHeight });
+				}
+			}
+		},
+	});
+
+	const toggleRowExpanded = (rowId: string) => {
+		setExpandedRows((prev) => ({
+			...prev,
+			[rowId]: !prev[rowId],
+		}));
+	};
+
+	const renderEmptyState = () =>
+		virtualized ? (
+			<div className={styles.emptyStateVirtualized}>{emptyState || 'No results.'}</div>
+		) : (
+			<TableRow>
+				<TableCell
+					colSpan={columns.length + (expandable ? 1 : 0) + (selectable ? 1 : 0)}
+					className={styles.emptyState}
+				>
+					{emptyState || 'No results.'}
+				</TableCell>
+			</TableRow>
+		);
+
+	const selectedRows = Object.entries(rowSelection)
+		.filter(([, selected]) => selected)
+		// This is not necessarily a redundant condition. It depends on `noUncheckedIndexedAccess`.
+		// eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+		.map(([key]) => rowsById[key]?.original)
+		.filter(Boolean);
+
+	const contextValue: DsTableContextType<TData, TValue> = {
+		stickyHeader,
+		bordered,
+		fullWidth,
+		highlightOnHover,
+		rowSize,
+		expandable,
+		selectable,
+		reorderable,
+		showSelectAllCheckbox,
+		onRowClick,
+		onRowDoubleClick,
+		primaryRowActions,
+		secondaryRowActions,
+		renderExpandedRow,
+		virtualized,
+		expandedRows,
+		toggleRowExpanded,
+		activeRowId,
+	};
+
+	return (
+		<DsTableContext.Provider value={contextValue}>
+			<div
+				ref={tableContainerRef}
+				className={classnames(
+					styles.container,
+					!virtualized && styles.dataTableContainer,
+					virtualized && styles.virtualizedContainer,
+					className,
+				)}
+			>
+				<DragWrapper>
+					<Table
+						style={
+							virtualized
+								? ({
+										'--ds-table-columns-template': createColumnsGridTemplate({
+											columns,
+											selectable: !!selectable,
+										}),
+									} as React.CSSProperties)
+								: undefined
+						}
+						className={classnames(
+							fullWidth && styles.fullWidth,
+							!bordered && styles.tableNoBorder,
+							virtualized && styles.virtualized,
+						)}
+					>
+						<DsTableHeader table={table} />
+						<TableBody
+							style={{ height: virtualized ? `${String(rowVirtualizer.getTotalSize())}px` : undefined }}
+							className={classnames(virtualized && styles.virtualizedBody)}
+						>
+							{virtualized ? (
+								rowVirtualizer.getVirtualItems().length ? (
+									rowVirtualizer.getVirtualItems().map((virtualRow: VirtualItem) => {
+										const row = rows[virtualRow.index];
+										return <DsTableRow key={row.id} row={row} virtualRow={virtualRow} />;
+									})
+								) : (
+									renderEmptyState()
+								)
+							) : (
+								<SortableWrapper>
+									{rows.length
+										? rows.map((row) => <DsTableRow key={row.id} row={row} />)
+										: renderEmptyState()}
+								</SortableWrapper>
+							)}
+						</TableBody>
+					</Table>
+				</DragWrapper>
+			</div>
+			{selectable && actions.length > 0 && (
+				<DsTableBulkActions
+					numSelectedRows={selectedRows.length}
+					actions={actions.map((action) => ({
+						...action,
+						onClick: () => action.onClick(selectedRows),
+					}))}
+					onClearSelection={table.resetRowSelection}
+				/>
+			)}
+		</DsTableContext.Provider>
+	);
+};
+
+export default DsTable;

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

@@ -0,0 +1,377 @@
+import type React from 'react';
+import type {
+	ColumnDef,
+	ColumnFiltersState,
+	SortingState,
+	Table,
+	VisibilityState,
+} from '@tanstack/react-table';
+import type { IconType } from '../ds-icon';
+import type { RowAction, SecondaryRowAction } from './components/ds-table-cell';
+
+/**
+ * Row size variants based on Figma design specifications
+ */
+export type DsTableRowSize = 'small' | 'medium' | 'large';
+
+/**
+ * Parameters passed to the onScroll callback in virtualized tables.
+ */
+export interface ScrollParams {
+	/** The current vertical scroll position from the top of the scrollable content (in pixels) */
+	scrollOffset: number;
+	/** The total height of all content in the virtualized table (in pixels) */
+	totalContentHeight: number;
+	/** The visible height of the table container (in pixels) */
+	viewportHeight: number;
+}
+
+/**
+ * API for programmatically controlling a DsTable component.
+ * This interface provides methods to interact with the table's selection, sorting, filtering, and pagination features.
+ *
+ * @template TData - The type of data items in the table
+ *
+ * @example
+ * ```tsx
+ * const tableRef = useRef<DsTableApi<Person>>(null);
+ *
+ * // Select a specific row
+ * tableRef.current?.selectRow('row-1');
+ *
+ * // Select multiple rows
+ * tableRef.current?.selectRows(['row-1', 'row-2', 'row-3']);
+ *
+ * // Get all selected rows
+ * const selected = tableRef.current?.getSelectedRows();
+ * ```
+ */
+export interface DsTableApi<TData> {
+	/**
+	 * Selects a single row by its ID.
+	 *
+	 * @param rowId - The unique identifier of the row to select
+	 *
+	 * @example
+	 * ```tsx
+	 * tableRef.current?.selectRow('user-123');
+	 * ```
+	 */
+	selectRow: (rowId: string) => void;
+
+	/**
+	 * Deselects a single row by its ID.
+	 *
+	 * @param rowId - The unique identifier of the row to deselect
+	 *
+	 * @example
+	 * ```tsx
+	 * tableRef.current?.deselectRow('user-123');
+	 * ```
+	 */
+	deselectRow: (rowId: string) => void;
+
+	/**
+	 * Selects all visible rows in the table.
+	 * This includes rows that are currently filtered or paginated.
+	 *
+	 * @example
+	 * ```tsx
+	 * tableRef.current?.selectAllRows();
+	 * ```
+	 */
+	selectAllRows: () => void;
+
+	/**
+	 * Deselects all rows in the table.
+	 * Clears the current selection state.
+	 *
+	 * @example
+	 * ```tsx
+	 * tableRef.current?.deselectAllRows();
+	 * ```
+	 */
+	deselectAllRows: () => void;
+
+	/**
+	 * Selects multiple rows by their IDs.
+	 *
+	 * @param rowIds - Array of unique identifiers for the rows to select
+	 *
+	 * @example
+	 * ```tsx
+	 * tableRef.current?.selectRows(['user-1', 'user-2', 'user-3']);
+	 * ```
+	 */
+	selectRows: (rowIds: string[]) => void;
+
+	/**
+	 * Returns an array of all currently selected row data.
+	 *
+	 * @returns Array of selected row data objects
+	 *
+	 * @example
+	 * ```tsx
+	 * const selectedUsers = tableRef.current?.getSelectedRows();
+	 * console.log('Selected users:', selectedUsers);
+	 * ```
+	 */
+	getSelectedRows: () => TData[];
+}
+
+/**
+ * Represents a bulk action that can be performed on multiple selected rows
+ */
+export interface Action<TData> {
+	/**
+	 * Icon to be displayed for the action
+	 */
+	icon: IconType;
+
+	/**
+	 * Label text for the action
+	 */
+	label: string;
+
+	/**
+	 * Function to be called when the action is clicked, receives the selected rows as parameter
+	 */
+	onClick: (rows: TData[]) => void;
+}
+
+export interface DsDataTableProps<TData, TValue> {
+	/**
+	 * Ref to the table API
+	 */
+	ref?: React.RefObject<DsTableApi<TData> | null>;
+
+	/**
+	 * Columns of the table
+	 */
+	columns: ColumnDef<TData, TValue>[];
+
+	/**
+	 * Data of the table
+	 */
+	data: TData[];
+
+	/**
+	 * Whether the table is virtualized
+	 * @default false
+	 */
+	virtualized?: boolean;
+
+	/**
+	 * Options for the virtualized table
+	 */
+	virtualizedOptions?: {
+		/**
+		 * Estimate size of the table
+		 */
+		estimateSize?: number;
+
+		/**
+		 * Overscan of the table
+		 */
+		overscan?: number;
+	};
+
+	/**
+	 * Class name of the table
+	 */
+	className?: string;
+
+	/**
+	 * Function to handle row click
+	 */
+	onRowClick?: (row: TData) => void;
+
+	/**
+	 * Function to handle row double click
+	 */
+	onRowDoubleClick?: (row: TData) => void;
+
+	/**
+	 * ID of the currently active row (useful for showing drawer/panel associations)
+	 * When set, the row with this ID will be visually highlighted with a persistent active state
+	 * @example
+	 * ```tsx
+	 * const [activeRowId, setActiveRowId] = useState<string | null>(null);
+	 * const [isDrawerOpen, setIsDrawerOpen] = useState(false);
+	 *
+	 * <DsTable
+	 *   activeRowId={isDrawerOpen ? activeRowId : null}
+	 *   onRowClick={(row) => {
+	 *     setActiveRowId(row.id);
+	 *     setIsDrawerOpen(true);
+	 *   }}
+	 * />
+	 * ```
+	 */
+	activeRowId?: string | null;
+
+	/**
+	 * Empty state of the table
+	 */
+	emptyState?: React.ReactNode;
+
+	/**
+	 * Whether the table has sticky header
+	 */
+	stickyHeader?: boolean;
+
+	/**
+	 * Whether the table has zebra stripes
+	 */
+	zebra?: boolean;
+
+	/**
+	 * Whether the table has bordered cells
+	 */
+	bordered?: boolean;
+
+	/**
+	 * Whether the table is full width
+	 */
+	fullWidth?: boolean;
+
+	/**
+	 * Whether the table has highlight on hover
+	 */
+	highlightOnHover?: boolean;
+
+	/**
+	 * Row size variant (small: 36px, medium: 48px, large: 64px)
+	 * @default 'medium'
+	 */
+	rowSize?: DsTableRowSize;
+
+	/**
+	 * Whether the table is expandable or if an individual row should be expandable
+	 */
+	expandable?: boolean | ((row: TData) => boolean);
+
+	/**
+	 * Function to render the expanded row
+	 */
+	renderExpandedRow?: (row: TData) => React.ReactNode;
+
+	/**
+	 * Function to handle table creation
+	 */
+	onTableCreated?: (table: Table<TData>) => void;
+
+	/**
+	 * Whether the table rows are selectable. Can be a boolean or a function that receives row data and returns whether it can be selected.
+	 * @default false
+	 * @example
+	 * ```tsx
+	 * // Enable selection for all rows
+	 * selectable={true}
+	 *
+	 * // Disable selection for rows where status is 'archived'
+	 * selectable={(rowData) => rowData.status !== 'archived'}
+	 *
+	 * // Limit selection to max 3 rows (note: use state to track current selection)
+	 * selectable={(rowData) => {
+	 *   // This will be called for each row during render
+	 *   const selectedIds = Object.keys(rowSelection).filter(id => rowSelection[id]);
+	 *   return selectedIds.includes(rowData.id) || selectedIds.length < 3;
+	 * }}
+	 * ```
+	 */
+	selectable?: boolean | ((rowData: TData) => boolean);
+
+	/**
+	 * Whether to show the select/deselect all checkbox in the header
+	 * @default true
+	 */
+	showSelectAllCheckbox?: boolean;
+
+	/**
+	 * Function to handle selection change
+	 */
+	onSelectionChange?: (selectedRows: Record<string, boolean>) => void;
+
+	/**
+	 * Function to handle sorting change
+	 */
+	onSortingChange?: (sorting: SortingState) => void;
+
+	/**
+	 * Function to handle scroll events in virtualized tables.
+	 * Called when the user scrolls within the table container.
+	 *
+	 * @param params - Scroll parameters containing scroll position and dimensions
+	 *
+	 * @example
+	 * ```tsx
+	 * const handleScroll = ({ scrollOffset, totalContentHeight, viewportHeight }) => {
+	 *   const distanceFromBottom = totalContentHeight - scrollOffset - viewportHeight;
+	 *   if (distanceFromBottom < 500) {
+	 *     // Fetch more data when within 500px of bottom
+	 *     fetchNextPage();
+	 *   }
+	 * };
+	 * ```
+	 */
+	onScroll?: (params: ScrollParams) => void;
+
+	/**
+	 * Actions to be shown in the bulk actions
+	 */
+	actions?: Action<TData>[];
+
+	/**
+	 * Primary actions to be shown on each row (on hover)
+	 */
+	primaryRowActions?: RowAction<TData>[];
+
+	/**
+	 * Secondary actions to be shown in a dropdown on each row (on hover)
+	 */
+	secondaryRowActions?: SecondaryRowAction<TData>[];
+
+	/**
+	 * Whether the table rows are reorderable via drag & drop
+	 * @note This feature does not work when virtualization is enabled
+	 */
+	reorderable?: boolean;
+
+	/**
+	 * Callback when the order of rows changes via drag & drop
+	 */
+	onOrderChange?: (newData: TData[]) => void;
+
+	/**
+	 * External column filters state
+	 */
+	columnFilters?: ColumnFiltersState;
+
+	/**
+	 * Callback when column filters change
+	 */
+	onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
+
+	/**
+	 * External column visibility state
+	 * @example
+	 * ```tsx
+	 * const [columnVisibility, setColumnVisibility] = useState<VisibilityState>({
+	 *   age: false, // hide age column
+	 *   status: true, // show status column
+	 * });
+	 *
+	 * <DsTable
+	 *   columnVisibility={columnVisibility}
+	 *   onColumnVisibilityChange={setColumnVisibility}
+	 * />
+	 * ```
+	 */
+	columnVisibility?: VisibilityState;
+
+	/**
+	 * Callback when column visibility changes
+	 */
+	onColumnVisibilityChange?: (visibility: VisibilityState) => void;
+}