@drivenets/design-system 0.0.1

package/src/components/ds-table/filters/hooks/use-table-filters.ts

@@ -0,0 +1,234 @@
+import { type ReactNode, useState } from 'react';
+import type { CellContext, ColumnDef } from '@tanstack/react-table';
+import type { ChipItem } from '../../../ds-chip-group';
+import type {
+	AnyAdapter,
+	ColumnFilterState,
+	FilterAdapter,
+	FilterNavItem,
+	FilterState,
+} from '../types/filter-adapter.types';
+
+export interface UseTableFiltersResult<TData, TValue> {
+	/**
+	 * Current filter state
+	 */
+	filterState: FilterState<TValue>;
+
+	/**
+	 * Column filters for TanStack Table
+	 */
+	columnFilters: ColumnFilterState<TValue>[];
+
+	/**
+	 * Filter chips for display
+	 */
+	filterChips: ChipItem[];
+
+	/**
+	 * Filter navigation items with counts
+	 */
+	filterNavItems: FilterNavItem[];
+
+	/**
+	 * Enhanced column definitions with filter functions
+	 */
+	enhancedColumns: ColumnDef<TData>[];
+
+	/**
+	 * Handlers
+	 */
+	handlers: {
+		/**
+		 * Update a specific filter's value
+		 */
+		updateFilter: (filterId: string, value: TValue) => void;
+
+		/**
+		 * Apply all filters (converts to TanStack format)
+		 */
+		applyFilters: () => void;
+
+		/**
+		 * Clear all filters
+		 */
+		clearAll: () => void;
+
+		/**
+		 * Delete a specific chip
+		 */
+		deleteChip: (chip: ChipItem) => void;
+	};
+
+	/**
+	 * Render function for filter modal content
+	 */
+	renderFilterContent: (selectedFilter: FilterNavItem) => ReactNode;
+}
+
+/**
+ * Hook to orchestrate table filtering with adapters
+ * Manages filter state, generates chips, handles column definitions
+ *
+ * @param filterAdapters Array of filter adapters
+ * @param baseColumns Base column definitions (optional)
+ * @returns Complete filter management system
+ */
+export function useTableFilters<TData, TValue, TCellValue>(
+	filterAdapters: FilterAdapter<TData, TValue, TCellValue>[] | AnyAdapter[],
+	baseColumns?: ColumnDef<TData>[],
+): UseTableFiltersResult<TData, TValue> {
+	// Internal variable just to avoid assignment issues of `any`.
+	const _filterAdapters = filterAdapters as FilterAdapter<TData, TValue, TCellValue>[];
+
+	// Initialize filter state from adapters
+	const initialState: FilterState<TValue> = {};
+	_filterAdapters.forEach((adapter) => {
+		initialState[adapter.id] = adapter.initialValue;
+	});
+
+	const [filterState, setFilterState] = useState<FilterState<TValue>>(initialState);
+	const [columnFilters, setColumnFilters] = useState<ColumnFilterState<TValue>[]>([]);
+	const [filterChips, setFilterChips] = useState<ChipItem[]>([]);
+
+	// Generate filter nav items with counts (updates as user changes filters in modal)
+	const filterNavItems: FilterNavItem[] = _filterAdapters.map((adapter) => ({
+		id: adapter.id,
+		label: adapter.label,
+		count: adapter.getActiveFiltersCount(filterState[adapter.id]),
+	}));
+
+	// Enhance column definitions with filter functions and renderers
+	const enhancedColumns: ColumnDef<TData>[] = !baseColumns
+		? []
+		: baseColumns.map((col) => {
+				const adapter = _filterAdapters.find((a) => a.id === col.id);
+
+				if (adapter) {
+					const cellRenderer = adapter.cellRenderer;
+					return {
+						...col,
+						filterFn: adapter.columnFilterFn,
+						...(cellRenderer && {
+							cell: (info: CellContext<TData, TCellValue>) => cellRenderer(info.getValue()),
+						}),
+					};
+				}
+
+				return col;
+			});
+
+	// Handlers
+	const updateFilter = (filterId: string, value: TValue) => {
+		setFilterState((prev) => ({
+			...prev,
+			[filterId]: value,
+		}));
+	};
+
+	const applyFilters = () => {
+		const filters: ColumnFilterState<TValue>[] = [];
+		const chips: ChipItem[] = [];
+
+		_filterAdapters.forEach((adapter) => {
+			const value = filterState[adapter.id];
+
+			if (adapter.getActiveFiltersCount(value) > 0) {
+				filters.push({
+					id: adapter.id,
+					value,
+				});
+			}
+
+			// Generate chips from current filter value
+			const adapterChips = adapter.toChips(value);
+			chips.push(...adapterChips);
+		});
+
+		setColumnFilters(filters);
+		setFilterChips(chips);
+	};
+
+	const clearAll = () => {
+		const resetState: FilterState<TValue> = {};
+		_filterAdapters.forEach((adapter) => {
+			resetState[adapter.id] = adapter.reset();
+		});
+		setFilterState(resetState);
+		setColumnFilters([]);
+		setFilterChips([]);
+	};
+
+	const deleteChip = (chip: ChipItem) => {
+		const filterKey = typeof chip.metadata?.key === 'string' ? chip.metadata.key : undefined;
+		if (!filterKey) {
+			return;
+		}
+
+		const adapter = _filterAdapters.find((a) => a.id === filterKey);
+		if (!adapter) {
+			return;
+		}
+
+		const currentValue = filterState[filterKey];
+		const newValue = adapter.fromChip(chip, currentValue);
+
+		// Regenerate chips to check if this was the last one
+		const chips: ChipItem[] = [];
+		_filterAdapters.forEach((adapter) => {
+			const value = adapter.id === filterKey ? newValue : filterState[adapter.id];
+			const adapterChips = adapter.toChips(value);
+			chips.push(...adapterChips);
+		});
+
+		// If no chips left, clear all filters
+		if (chips.length === 0) {
+			clearAll();
+			return;
+		}
+
+		// Otherwise, update state and filters
+		setFilterState((prev) => ({
+			...prev,
+			[filterKey]: newValue,
+		}));
+
+		// Update column filters
+		if (adapter.getActiveFiltersCount(newValue) === 0) {
+			setColumnFilters((prev) => prev.filter((cf) => cf.id !== filterKey));
+		} else {
+			setColumnFilters((prev) =>
+				prev.map((cf) => (cf.id === filterKey ? { id: filterKey, value: newValue } : cf)),
+			);
+		}
+
+		setFilterChips(chips);
+	};
+
+	const renderFilterContent = (selectedFilter: FilterNavItem) => {
+		const adapter = _filterAdapters.find((a) => a.id === selectedFilter.id);
+		if (!adapter) {
+			return null;
+		}
+
+		const value = filterState[adapter.id];
+		const onChange = (newValue: TValue) => updateFilter(adapter.id, newValue);
+
+		return adapter.renderFilter(value, onChange);
+	};
+
+	return {
+		filterState,
+		columnFilters,
+		filterChips,
+		filterNavItems,
+		enhancedColumns,
+		handlers: {
+			updateFilter,
+			applyFilters,
+			clearAll,
+			deleteChip,
+		},
+		renderFilterContent,
+	};
+}

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

@@ -0,0 +1,50 @@
+/**
+ * Table Filters - Filter Adapter Pattern
+ *
+ * A plug-and-play filter system that eliminates boilerplate and centralizes filter logic.
+ *
+ * ## Quick Start:
+ *
+ * ```typescript
+ * // 1. Create filter adapters in a config file
+ * import { createCheckboxFilterAdapter, createDualRangeFilterAdapter } from '../filters';
+ *
+ * export const statusFilter = createCheckboxFilterAdapter({
+ *   id: 'status',
+ *   label: 'Status',
+ *   items: [{ value: 'active', label: 'Active' }],
+ * });
+ *
+ * export const myFilters = [statusFilter];
+ *
+ * // 2. Use in component with useTableFilters hook
+ * import { useTableFilters } from '../filters';
+ *
+ * const { columnFilters, filterChips, enhancedColumns, handlers } =
+ *   useTableFilters(myFilters, columns);
+ * ```
+ *
+ * ## Available Exports:
+ *
+ * ### Factory Functions:
+ * - `createCheckboxFilterAdapter` - Multi-select checkbox filters
+ * - `createDualRangeFilterAdapter` - Numeric range filters (with multiple fields)
+ * - `createFilterAdapter` - Base function for custom filters (full control)
+ *
+ * ### Hook:
+ * - `useTableFilters` - Orchestrates multiple filters, manages state
+ *
+ * ### Types:
+ * - `FilterAdapter` - Core adapter interface
+ * - `CheckboxFilterItem` - Item type for checkbox filters
+ * - `RangeFilterValue` - Value type for range filters
+ *
+ * ## Example:
+ * See `stories/filters-panel.stories.tsx` and `stories/filters-panel/workflow-filters.config.tsx`
+ */
+
+export * from './adapters';
+export * from './types/filter-adapter.types';
+export * from './hooks';
+export type { CheckboxFilterItem, CheckboxFilterProps } from './components/checkbox-filter';
+export type { RangeFilterValue, RangeFilterProps } from './components/range-filter';

package/src/components/ds-table/filters/types/filter-adapter.types.ts

@@ -0,0 +1,111 @@
+import type { ReactNode } from 'react';
+import type { Row } from '@tanstack/react-table';
+import type { ChipItem } from '../../../ds-chip-group';
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyAdapter = FilterAdapter<any, any, any>;
+
+/**
+ * Base filter adapter interface that all filters must implement
+ * This provides a consistent contract for filter behavior
+ *
+ * @template TData - The row data type
+ * @template TFilterValue - The filter state value type
+ * @template TCellValue - The actual cell value type from the table (defaults to unknown)
+ */
+export interface FilterAdapter<TData, TFilterValue, TCellValue = unknown> {
+	/**
+	 * Unique identifier for the filter (should match column accessorKey)
+	 */
+	id: string;
+
+	/**
+	 * Display label for the filter in the navigation
+	 */
+	label: string;
+
+	/**
+	 * Initial/default value for the filter state
+	 */
+	initialValue: TFilterValue;
+
+	/**
+	 * TanStack Table filter function
+	 * Determines if a row matches the current filter value
+	 */
+	columnFilterFn: (row: Row<TData>, columnId: string, filterValue: TFilterValue) => boolean;
+
+	/**
+	 * Optional custom cell renderer for the table column
+	 * Receives the actual cell value from the table, not the filter value
+	 * If not provided, default rendering will be used
+	 */
+	cellRenderer?: (value: TCellValue) => ReactNode;
+
+	/**
+	 * Convert filter value to filter chips for display
+	 * Returns empty array if no chips should be shown
+	 */
+	toChips: (value: TFilterValue) => ChipItem[];
+
+	/**
+	 * Remove a chip from the filter value
+	 * Returns updated filter value with the chip's effect removed
+	 */
+	fromChip: (chip: ChipItem, currentValue: TFilterValue) => TFilterValue;
+
+	/**
+	 * Calculate how many active filters are applied
+	 * Used for the count indicator in filter navigation
+	 * Can also be used to check if filter is active (count > 0)
+	 */
+	getActiveFiltersCount: (value: TFilterValue) => number;
+
+	/**
+	 * Reset filter to initial state
+	 */
+	reset: () => TFilterValue;
+
+	/**
+	 * Render the filter UI component
+	 * Receives current value and onChange callback
+	 */
+	renderFilter: (value: TFilterValue, onChange: (value: TFilterValue) => void) => ReactNode;
+}
+
+/**
+ * Filter navigation item used to render filter tabs in the UI
+ */
+export interface FilterNavItem {
+	/**
+	 * Unique identifier for the filter (matches FilterAdapter.id)
+	 */
+	id: string;
+	/**
+	 * Display label for the filter tab
+	 */
+	label: string;
+	/**
+	 * Optional count badge to display active filters
+	 */
+	count?: number;
+	/**
+	 * Whether this filter is disabled
+	 */
+	disabled?: boolean;
+}
+
+/**
+ * Filter state managed by useTableFilters hook
+ */
+export interface FilterState<TValue> {
+	[filterId: string]: TValue;
+}
+
+/**
+ * Column filter for TanStack Table
+ */
+export interface ColumnFilterState<TValue> {
+	id: string;
+	value: TValue;
+}

package/src/components/ds-table/hooks/use-drag-and-drop.tsx

@@ -0,0 +1,107 @@
+import React from 'react';
+import {
+	type DragEndEvent,
+	type UniqueIdentifier,
+	closestCenter,
+	DndContext,
+	KeyboardSensor,
+	MouseSensor,
+	TouchSensor,
+	useSensor,
+	useSensors,
+} from '@dnd-kit/core';
+import { arrayMove, SortableContext, verticalListSortingStrategy } from '@dnd-kit/sortable';
+import { restrictToVerticalAxis } from '@dnd-kit/modifiers';
+
+export interface UseDragAndDropResult {
+	DragWrapper: React.ComponentType<React.PropsWithChildren>;
+	SortableWrapper: React.ComponentType<React.PropsWithChildren>;
+}
+
+export interface UseDragAndDropOptions<T> {
+	isDragEnabled: boolean;
+	onOrderChange?: (newData: T[]) => void;
+	items: T[];
+}
+
+type DragWrapperProps = React.PropsWithChildren<{
+	onDragEnd: (event: DragEndEvent) => void;
+	sensors: ReturnType<typeof useSensors>;
+}>;
+
+const DragWrapper = ({ children, onDragEnd, sensors }: DragWrapperProps) => (
+	<DndContext
+		collisionDetection={closestCenter}
+		modifiers={[restrictToVerticalAxis]}
+		onDragEnd={onDragEnd}
+		sensors={sensors}
+	>
+		{children}
+	</DndContext>
+);
+
+type SortableWrapperProps = React.PropsWithChildren<{
+	items: UniqueIdentifier[];
+}>;
+
+const SortableWrapper = ({ children, items }: SortableWrapperProps) => (
+	<SortableContext items={items} strategy={verticalListSortingStrategy}>
+		{children}
+	</SortableContext>
+);
+
+export function useDragAndDrop<T extends { id: string }>({
+	isDragEnabled,
+	onOrderChange,
+	items,
+}: UseDragAndDropOptions<T>): UseDragAndDropResult {
+	const dataIds = React.useMemo(() => items.map((row) => row.id), [items]);
+
+	const sensors = useSensors(
+		useSensor(MouseSensor, {}),
+		useSensor(TouchSensor, {}),
+		useSensor(KeyboardSensor, {}),
+	);
+
+	const handleDragEnd = React.useCallback(
+		(event: DragEndEvent) => {
+			const { active, over } = event;
+			if (active.id !== over?.id) {
+				const oldIndex = items.findIndex((row) => row.id === active.id);
+				const newIndex = items.findIndex((row) => row.id === over?.id);
+				if (oldIndex !== -1 && newIndex !== -1) {
+					const newData = arrayMove(items, oldIndex, newIndex);
+					onOrderChange?.(newData);
+				}
+			}
+		},
+		[items, onOrderChange],
+	);
+
+	const DragWrapperComponent = React.useMemo(
+		() =>
+			isDragEnabled
+				? ({ children }: React.PropsWithChildren) => (
+						<DragWrapper onDragEnd={handleDragEnd} sensors={sensors}>
+							{children}
+						</DragWrapper>
+					)
+				: React.Fragment,
+		[isDragEnabled, handleDragEnd, sensors],
+	);
+
+	const SortableWrapperComponent = React.useMemo(
+		() =>
+			isDragEnabled
+				? ({ children }: React.PropsWithChildren) => (
+						<SortableWrapper items={dataIds}>{children}</SortableWrapper>
+					)
+				: React.Fragment,
+		[isDragEnabled, dataIds],
+	);
+
+	return {
+		DragWrapper: DragWrapperComponent,
+		SortableWrapper: SortableWrapperComponent,
+	};
+}

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

@@ -0,0 +1,4 @@
+export type { SecondaryRowAction, RowAction } from './components/ds-table-cell';
+
+export { default as DsTable } from './ds-table';
+export * from './ds-table.types';

package/src/components/ds-table/styles/_variables.scss

@@ -0,0 +1,17 @@
+$border-radius: 4px;
+$border-width: 1px;
+$virtualized-height: 600px;
+$expand-column-width: 40px;
+$select-column-width: 40px;
+$reorder-column-width: 60px;
+$container-margin-vertical: 1rem;
+$filter-input-gap: 0.5rem;
+$filter-input-max-width: 24rem;
+$header-sort-gap: 0.5rem;
+$empty-state-height: 6rem;
+
+$hover-bg-color: var(--color-background-secondary);
+$hover-border-color: var(--color-border);
+$expanded-row-bg-color: var(--color-background-secondary);
+$expand-toggle-hover-bg-color: var(--color-background-action-hover-weak);
+$expand-toggle-icon-color: var(--color-icon-information-main);

package/src/components/ds-table/styles/shared/ds-table-shared.module.scss

@@ -0,0 +1,16 @@
+@use '../../../../styles/utilities' as utils;
+@use '../variables' as vars;
+
+.checkboxContainer {
+	display: flex;
+	align-items: center;
+	justify-content: center;
+	width: fit-content;
+	margin: auto;
+	height: 100%;
+}
+
+.pageButtonIcon {
+	color: vars.$expand-toggle-icon-color;
+	@extend .rotate;
+}

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

@@ -0,0 +1,30 @@
+import type { CSSProperties } from 'react';
+import { defaultColumnSizing } from '@tanstack/react-table';
+
+/**
+ * Generates the appropriate style object for a table column/cell based on its size and virtualization state
+ *
+ * @param columnSize - The size of the column
+ * @param virtualized - Whether the table is virtualized
+ * @param isLastColumn - Whether this is the last column in the row
+ * @returns Style object or undefined if no custom styling is needed
+ */
+export const getColumnStyle = (
+	columnSize: number,
+	virtualized?: boolean,
+	isLastColumn: boolean = false,
+): CSSProperties | undefined => {
+	const hasCustomSize = columnSize !== defaultColumnSizing.size;
+	if (!hasCustomSize) {
+		return undefined;
+	}
+
+	if (virtualized) {
+		return {
+			flexBasis: `${String(columnSize)}px`,
+			flexGrow: isLastColumn ? 1 : 0,
+		};
+	}
+
+	return { width: columnSize };
+};

package/src/components/ds-table/utils/create-columns-grid-template.ts

@@ -0,0 +1,23 @@
+import type { ColumnDef } from '@tanstack/react-table';
+
+type Args = {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any
+	columns: ColumnDef<any, any>[];
+	selectable?: boolean;
+};
+
+// In virtualized tables, the rows should all be positioned at the top with a `translateY` offset.
+// We're using a Grid for this rather than `position: absolute` to ensure that each cell aligns with
+// other cells in the same column (mimicking the native table behavior).
+export function createColumnsGridTemplate({ columns, selectable }: Args): string {
+	return columns
+		.reduce<string[]>(
+			(acc, col) => {
+				acc.push(col.size ? `${String(col.size)}px` : 'auto');
+
+				return acc;
+			},
+			selectable ? ['max-content'] : [],
+		)
+		.join(' ');
+}

package/src/components/ds-table/utils/merge-refs.ts

@@ -0,0 +1,15 @@
+import type { Ref, RefCallback } from 'react';
+
+export const mergeRefs = <T>(...refs: Array<Ref<T> | undefined>): RefCallback<T> => {
+	return (value) => {
+		refs
+			.filter((r) => !!r)
+			.forEach((ref) => {
+				if (typeof ref === 'function') {
+					ref(value);
+				} else {
+					ref.current = value;
+				}
+			});
+	};
+};

package/src/components/ds-table/utils/story-data-generator.ts

@@ -0,0 +1,91 @@
+import type { SortingState } from '@tanstack/react-table';
+import type { Status } from '../ds-table.stories';
+
+export type Person = {
+	id: string;
+	firstName: string;
+	lastName: string;
+	age: number;
+	visits: number;
+	status: Status;
+	progress: number;
+};
+
+export interface GeneratedDataResult {
+	data: Person[];
+	meta: {
+		totalRowCount: number;
+	};
+}
+
+/**
+ * Generates mock data for table stories with pagination support
+ */
+export const generatePersonData = (
+	start: number,
+	size: number,
+	sorting: SortingState,
+	totalRows: number = 10_000,
+): GeneratedDataResult => {
+	const firstNames = ['Alice', 'Bob', 'Charlie', 'Diana', 'Eve', 'Frank', 'Grace', 'Henry', 'Ivy', 'Jack'];
+	const lastNames = [
+		'Smith',
+		'Johnson',
+		'Williams',
+		'Brown',
+		'Jones',
+		'Garcia',
+		'Miller',
+		'Davis',
+		'Rodriguez',
+		'Martinez',
+	];
+	const statuses: Status[] = ['single', 'relationship', 'complicated'];
+
+	// Generate all data first for sorting
+	const allData: Person[] = Array.from({ length: totalRows }).map((_, index) => {
+		const i = index + 1;
+		return {
+			id: i.toString(),
+			firstName: firstNames[i % firstNames.length],
+			lastName: lastNames[i % lastNames.length],
+			age: 20 + (i % 50),
+			visits: Math.floor(Math.random() * 500) + 1,
+			status: statuses[i % statuses.length],
+			progress: Math.floor(Math.random() * 100) + 1,
+		};
+	});
+
+	// Apply sorting if provided
+	const sortedData = [...allData];
+	if (sorting.length) {
+		const sort = sorting[0];
+		const { id, desc } = sort;
+		sortedData.sort((a, b) => {
+			const aValue = a[id as keyof Person];
+			const bValue = b[id as keyof Person];
+			if (desc) {
+				return aValue < bValue ? 1 : -1;
+			}
+			return aValue > bValue ? 1 : -1;
+		});
+	}
+
+	// Return paginated slice
+	return {
+		data: sortedData.slice(start, start + size),
+		meta: {
+			totalRowCount: sortedData.length,
+		},
+	};
+};
+
+/**
+ * Simulates an API call with network delay
+ */
+export const simulateApiCall = async <T>(dataGenerator: () => T, delayMs: number = 200): Promise<T> => {
+	await delay(delayMs);
+	return dataGenerator();
+};
+
+const delay = (ms: number) => new Promise((resolve) => setTimeout(resolve, ms));