@drivenets/design-system 0.12.1 → 0.14.0

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

@@ -1,107 +1,77 @@
 import { type ReactNode, useState } from 'react';
 import type { CellContext, ColumnDef } from '@tanstack/react-table';
-import type { ChipItem } from '../../../ds-chip-group';
+import type { TagFilterItem } from '../../../ds-tag-filter';
 import type {
 	AnyAdapter,
+	ColumnFilterMeta,
 	ColumnFilterState,
 	FilterAdapter,
 	FilterNavItem,
 	FilterState,
+	ResolvedColumnFilter,
 } from '../types/filter-adapter.types';
 
+const resolveColumnAdapterId = (
+	meta: ColumnFilterMeta | ResolvedColumnFilter | undefined,
+): string | undefined => {
+	if (!meta) {
+		return undefined;
+	}
+	if ('render' in meta) {
+		return meta.filterId;
+	}
+	if (meta.adapter) {
+		return meta.adapter.id;
+	}
+	return meta.adapterId;
+};
+
 export interface UseTableFiltersOptions<TData, TValue, TCellValue> {
-	/**
-	 * Array of filter adapters that define filter behavior
-	 */
 	filterAdapters: FilterAdapter<TData, TValue, TCellValue>[] | AnyAdapter[];
-
-	/**
-	 * Base column definitions
-	 */
 	baseColumns?: ColumnDef<TData>[];
-
-	/**
-	 * Controlled mode: External applied filters (source of truth).
-	 * When provided with onFiltersChange, the hook operates in controlled mode.
-	 * Keys must match adapter IDs.
-	 */
+	/** Controlled applied filters, keyed by adapter id. Pair with `onFiltersChange`. */
 	appliedFilters?: FilterState<TValue>;
-
-	/**
-	 * Controlled mode: Callback when filters change.
-	 * Called by applyFilters(), deleteChip(), clearAll().
-	 */
+	/** Fires from `applyFilters`, `deleteChip`, and `clearAll` in controlled mode. */
 	onFiltersChange?: (filters: FilterState<TValue>) => void;
 }
 
 export interface UseTableFiltersResult<TData, TValue> {
-	/**
-	 * Current draft filter state (uncommitted user selections)
-	 */
+	/** Draft filter state (uncommitted). */
 	filterState: FilterState<TValue>;
-
-	/**
-	 * Column filters (derived from applied state)
-	 */
+	/** Applied filters mapped to TanStack's column-filters shape. */
 	columnFilters: ColumnFilterState<TValue>[];
-
-	/**
-	 * Filter chips for display (derived from applied state)
-	 */
-	filterChips: ChipItem[];
-
-	/**
-	 * Filter navigation items with active counts
-	 */
+	/** Chips for `DsTagFilter`, derived from applied state. */
+	filterChips: TagFilterItem[];
+	/** Filter-nav items with active counts. */
 	filterNavItems: FilterNavItem[];
-
-	/**
-	 * Enhanced column definitions with filter functions
-	 */
+	/** `baseColumns` with `filterFn`, cell renderer and per-column meta wired in. */
 	enhancedColumns: ColumnDef<TData>[];
-
-	/**
-	 * Handlers for filter operations
-	 */
 	handlers: {
-		/** Update a specific filter's draft value */
+		/** Update a filter's draft value. */
 		updateFilter: (filterId: string, value: TValue) => void;
-		/** Commit draft state to applied state */
+		/** Commit all drafts to applied state. */
 		applyFilters: () => void;
-		/** Clear all filters */
+		/** Clear all filters. */
 		clearAll: () => void;
-		/** Delete a specific filter chip */
-		deleteChip: (chip: ChipItem) => void;
+		/** Remove a chip's effect from applied state. */
+		deleteChip: (chip: TagFilterItem) => void;
+		/** Commit one column's draft (per-column popover Save). */
+		applyColumnFilter: (filterId: string) => void;
+		/** Discard one column's draft without committing. */
+		cancelColumnFilter: (filterId: string) => void;
+		/** Clear one applied filter (per-column popover Clear). */
+		clearColumnFilter: (filterId: string) => void;
 	};
-
-	/**
-	 * Render function for filter content
-	 */
+	/** Renders the adapter UI for a column id, or `null` if no match. */
+	renderColumnFilter: (filterId: string) => ReactNode;
+	/** Renders the adapter UI for a `FilterNavItem`. */
 	renderFilterContent: (selectedFilter: FilterNavItem) => ReactNode;
 }
 
 /**
- * Hook to orchestrate table filtering with adapters.
- * Manages filter state, generates chips, and handles column definitions.
- *
- * **Uncontrolled mode** (default): Filters are managed internally.
- * **Controlled mode**: Filters are managed externally via appliedFilters/onFiltersChange.
- *
- * @example
- * // Uncontrolled mode
- * const { filterChips, handlers } = useTableFilters({
- *   filterAdapters: adapters,
- *   baseColumns: columns,
- * });
- *
- * @example
- * // Controlled mode (e.g., URL-driven filtering)
- * const { filterChips, handlers } = useTableFilters({
- *   filterAdapters: adapters,
- *   baseColumns: columns,
- *   appliedFilters: filtersFromUrl,
- *   onFiltersChange: (filters) => updateUrlAndRefetch(filters),
- * });
+ * Orchestrates table filtering: drafts → applied state, chips, nav counts, and
+ * column wiring. Uncontrolled by default; pass `appliedFilters` +
+ * `onFiltersChange` for URL-driven / external state.
  */
 export function useTableFilters<TData, TValue, TCellValue>({
 	filterAdapters,
@@ -109,7 +79,6 @@ export function useTableFilters<TData, TValue, TCellValue>({
 	appliedFilters: externalAppliedFilters,
 	onFiltersChange: setExternalAppliedFilters,
 }: UseTableFiltersOptions<TData, TValue, TCellValue>): UseTableFiltersResult<TData, TValue> {
-	// Internal variable just to avoid assignment issues of `any`.
 	const _filterAdapters = filterAdapters as FilterAdapter<TData, TValue, TCellValue>[];
 
 	const isControlled = externalAppliedFilters !== undefined && setExternalAppliedFilters !== undefined;
@@ -148,18 +117,41 @@ export function useTableFilters<TData, TValue, TCellValue>({
 	const enhancedColumns: ColumnDef<TData>[] = !baseColumns
 		? []
 		: baseColumns.map((col) => {
-				const adapter = _filterAdapters.find((a) => a.id === col.id);
+				const metaFilter = col.meta?.filter as ColumnFilterMeta | undefined;
+				const adapterIdFromMeta = resolveColumnAdapterId(metaFilter);
+				const adapter =
+					(adapterIdFromMeta && _filterAdapters.find((a) => a.id === adapterIdFromMeta)) ||
+					_filterAdapters.find((a) => a.id === col.id);
+
 				if (!adapter) {
 					return col;
 				}
 
 				const cellRenderer = adapter.cellRenderer;
+				const appliedValue = appliedFilters[adapter.id];
+				const resolvedFilter: ResolvedColumnFilter | undefined = metaFilter
+					? {
+							filterId: adapter.id,
+							hasActiveFilter: appliedValue !== undefined && adapter.getActiveFiltersCount(appliedValue) > 0,
+							render: () => renderForId(adapter.id),
+							onApply: () => applyColumnFilter(adapter.id),
+							onClear: () => clearColumnFilter(adapter.id),
+							onCancel: () => cancelColumnFilter(adapter.id),
+						}
+					: undefined;
+
 				return {
 					...col,
 					filterFn: adapter.columnFilterFn,
 					...(cellRenderer && {
 						cell: (info: CellContext<TData, TCellValue>) => cellRenderer(info.getValue()),
 					}),
+					...(resolvedFilter && {
+						meta: {
+							...col.meta,
+							filter: resolvedFilter,
+						},
+					}),
 				};
 			});
 
@@ -185,7 +177,43 @@ export function useTableFilters<TData, TValue, TCellValue>({
 		setAppliedFilters({});
 	};
 
-	const deleteChip = (chip: ChipItem) => {
+	const omitKey = (source: FilterState<TValue>, filterId: string): FilterState<TValue> =>
+		Object.fromEntries(Object.entries(source).filter(([key]) => key !== filterId));
+
+	const applyColumnFilter = (filterId: string) => {
+		const adapter = _filterAdapters.find((a) => a.id === filterId);
+		if (!adapter) {
+			return;
+		}
+
+		const draftValue = draftFilters[filterId] as TValue;
+		const hasActive = adapter.getActiveFiltersCount(draftValue) > 0;
+		const next = hasActive
+			? { ...appliedFilters, [filterId]: draftValue }
+			: omitKey(appliedFilters, filterId);
+
+		setAppliedFilters(next);
+		setPendingFilters((prev) => omitKey(prev, filterId));
+	};
+
+	const cancelColumnFilter = (filterId: string) => {
+		setPendingFilters((prev) => omitKey(prev, filterId));
+	};
+
+	const clearColumnFilter = (filterId: string) => {
+		const adapter = _filterAdapters.find((a) => a.id === filterId);
+		if (!adapter) {
+			return;
+		}
+
+		setPendingFilters((prev) => ({ ...omitKey(prev, filterId), [filterId]: adapter.initialValue }));
+
+		if (appliedFilters[filterId] !== undefined) {
+			setAppliedFilters(omitKey(appliedFilters, filterId));
+		}
+	};
+
+	const deleteChip = (chip: TagFilterItem) => {
 		const filterKey = typeof chip.metadata?.key === 'string' ? chip.metadata.key : undefined;
 		if (!filterKey) {
 			return;
@@ -211,8 +239,8 @@ export function useTableFilters<TData, TValue, TCellValue>({
 		setAppliedFilters(newFilters);
 	};
 
-	const renderFilterContent = (selectedFilter: FilterNavItem) => {
-		const adapter = _filterAdapters.find((a) => a.id === selectedFilter.id);
+	const renderForId = (filterId: string): ReactNode => {
+		const adapter = _filterAdapters.find((a) => a.id === filterId);
 		if (!adapter) {
 			return null;
 		}
@@ -223,6 +251,9 @@ export function useTableFilters<TData, TValue, TCellValue>({
 		return adapter.renderFilter(value, onChange);
 	};
 
+	const renderFilterContent = (selectedFilter: FilterNavItem) => renderForId(selectedFilter.id);
+	const renderColumnFilter = (filterId: string) => renderForId(filterId);
+
 	return {
 		filterState: draftFilters,
 		columnFilters,
@@ -234,7 +265,11 @@ export function useTableFilters<TData, TValue, TCellValue>({
 			applyFilters,
 			clearAll,
 			deleteChip,
+			applyColumnFilter,
+			cancelColumnFilter,
+			clearColumnFilter,
 		},
 		renderFilterContent,
+		renderColumnFilter,
 	};
 }

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

@@ -1,50 +1,8 @@
-/**
- * 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`
- */
+import './types/column-meta.augmentation';
 
 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';
+export * from './components/column-filter-popover';

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

@@ -0,0 +1,19 @@
+import '@tanstack/react-table';
+import type { ColumnFilterMeta, ResolvedColumnFilter } from './filter-adapter.types';
+
+/**
+ * Adds `column.meta.filter`. Consumers set `ColumnFilterMeta`;
+ * `useTableFilters` swaps it for `ResolvedColumnFilter` on `enhancedColumns`
+ * so the header can render the trigger + popover. The header narrows the
+ * union by checking for `render`.
+ */
+declare module '@tanstack/react-table' {
+	// `TData` / `TValue` must mirror the original `ColumnMeta` signature for
+	// the augmentation to merge.
+	// eslint-disable-next-line @typescript-eslint/no-unused-vars
+	interface ColumnMeta<TData, TValue> {
+		filter?: ColumnFilterMeta | ResolvedColumnFilter;
+	}
+}
+
+export {};

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

@@ -1,117 +1,84 @@
 import type { ReactNode } from 'react';
 import type { Row } from '@tanstack/react-table';
-import type { ChipItem } from '../../../ds-chip-group';
+import type { TagFilterItem } from '../../../ds-tag-filter';
 
 // 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)
+ * Contract every filter implements. `TData` is the row type, `TFilterValue`
+ * the adapter's state, `TCellValue` the cell value returned by the column.
  */
 export interface FilterAdapter<TData, TFilterValue, TCellValue = unknown> {
-	/**
-	 * Unique identifier for the filter (should match column accessorKey)
-	 */
+	/** Unique id, should match the column `accessorKey`. */
 	id: string;
-
-	/**
-	 * Display label for the filter in the navigation
-	 */
+	/** Display label used in the filter navigation. */
 	label: string;
-
-	/**
-	 * Initial/default value for the filter state
-	 */
+	/** Initial / reset value. */
 	initialValue: TFilterValue;
-
-	/**
-	 * TanStack Table filter function
-	 * Determines if a row matches the current filter value
-	 */
+	/** TanStack `filterFn` — returns whether a row matches the current 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
-	 */
+	/** Optional cell renderer; receives the cell value, not the filter value. */
 	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)
+	 * Convert the filter value into chips for `DsTagFilter`. Each chip's
+	 * `metadata.key` / `metadata.value` must let `fromChip` undo it.
 	 */
+	toChips: (value: TFilterValue) => TagFilterItem[];
+	/** Remove a chip's effect from the current value. */
+	fromChip: (chip: TagFilterItem, currentValue: TFilterValue) => TFilterValue;
+	/** Number of active sub-filters; `0` means the filter is inactive. */
 	getActiveFiltersCount: (value: TFilterValue) => number;
-
-	/**
-	 * Reset filter to initial state
-	 */
+	/** Return the initial value. */
 	reset: () => TFilterValue;
-
-	/**
-	 * Render the filter UI component
-	 * Receives current value and onChange callback
-	 */
+	/** Render the filter UI for a given value + onChange. */
 	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)
-	 */
+	/** Matches `FilterAdapter.id`. */
 	id: string;
-	/**
-	 * Display label for the filter tab
-	 */
 	label: string;
-	/**
-	 * Optional count badge to display active filters
-	 */
+	/** Active filter count badge. */
 	count?: number;
-	/**
-	 * Whether this filter is disabled
-	 */
 	disabled?: boolean;
 }
 
-/**
- * Filter state managed by useTableFilters hook
- */
+/** Map of filter id → adapter value. */
 export interface FilterState<TValue> {
 	[filterId: string]: TValue;
 }
 
-/**
- * Column filter for TanStack Table
- */
 export interface ColumnFilterState<TValue> {
-	/**
-	 * Column identifier this filter applies to (matches the column `accessorKey`).
-	 */
+	/** Column id (matches the column `accessorKey`). */
 	id: string;
-	/**
-	 * Current filter value, passed to the column's filter function.
-	 */
+	/** Value passed to the column's filter function. */
 	value: TValue;
 }
+
+/**
+ * Set by the consumer on `column.meta.filter` to opt a column into the
+ * per-column filter popover. Provide an `adapter` inline or just `adapterId`
+ * to resolve against `useTableFilters({ filterAdapters })`.
+ */
+export interface ColumnFilterMeta {
+	/** Mutually exclusive with `adapterId`. */
+	adapter?: AnyAdapter;
+	/** Mutually exclusive with `adapter`. */
+	adapterId?: string;
+}
+
+/**
+ * What `useTableFilters` injects onto `column.meta.filter` of each enhanced
+ * column. Consumers don't build this — they set `ColumnFilterMeta` and the
+ * hook swaps it for this resolved shape on `enhancedColumns`.
+ */
+export interface ResolvedColumnFilter {
+	filterId: string;
+	hasActiveFilter: boolean;
+	/** Renders the adapter's filter UI for this column. */
+	render: () => ReactNode;
+	onApply: () => void;
+	onClear: () => void;
+	onCancel: () => void;
+}

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;
+}