@drivenets/design-system 0.3.0 → 0.5.0

package/dist/components/ds-table/filters/hooks/use-table-filters.cjs

@@ -4,214 +4,209 @@ let react = require("react");
 
 //#region src/components/ds-table/filters/hooks/use-table-filters.ts
 /**
-* Hook to orchestrate table filtering with adapters
-* Manages filter state, generates chips, handles column definitions
+* Hook to orchestrate table filtering with adapters.
+* Manages filter state, generates chips, and handles column definitions.
 *
-* @param filterAdapters Array of filter adapters
-* @param baseColumns Base column definitions (optional)
-* @returns Complete filter management system
+* **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),
+* });
 */
-function useTableFilters(filterAdapters, baseColumns) {
-	const $ = (0, react_compiler_runtime.c)(39);
+function useTableFilters(t0) {
+	const $ = (0, react_compiler_runtime.c)(30);
+	const { filterAdapters, baseColumns, appliedFilters: externalAppliedFilters, onFiltersChange: setExternalAppliedFilters } = t0;
 	const _filterAdapters = filterAdapters;
-	let initialState;
-	if ($[0] !== _filterAdapters) {
-		initialState = {};
-		_filterAdapters.forEach((adapter) => {
-			initialState[adapter.id] = adapter.initialValue;
-		});
-		$[0] = _filterAdapters;
-		$[1] = initialState;
-	} else initialState = $[1];
-	const [filterState, setFilterState] = (0, react.useState)(initialState);
-	let t0;
-	if ($[2] === Symbol.for("react.memo_cache_sentinel")) {
-		t0 = [];
-		$[2] = t0;
-	} else t0 = $[2];
-	const [columnFilters, setColumnFilters] = (0, react.useState)(t0);
+	const isControlled = externalAppliedFilters !== void 0 && setExternalAppliedFilters !== void 0;
+	const initialFilters = _filterAdapters.reduce(_temp, {});
 	let t1;
-	if ($[3] === Symbol.for("react.memo_cache_sentinel")) {
-		t1 = [];
-		$[3] = t1;
-	} else t1 = $[3];
-	const [filterChips, setFilterChips] = (0, react.useState)(t1);
+	if ($[0] === Symbol.for("react.memo_cache_sentinel")) {
+		t1 = {};
+		$[0] = t1;
+	} else t1 = $[0];
+	const [internalAppliedFilters, setInternalAppliedFilters] = (0, react.useState)(t1);
 	let t2;
-	if ($[4] !== filterState) {
-		t2 = (adapterId) => filterState[adapterId];
-		$[4] = filterState;
-		$[5] = t2;
-	} else t2 = $[5];
-	const getValueByAdapterId = t2;
+	if ($[1] === Symbol.for("react.memo_cache_sentinel")) {
+		t2 = {};
+		$[1] = t2;
+	} else t2 = $[1];
+	const [pendingFilters, setPendingFilters] = (0, react.useState)(t2);
+	const appliedFilters = isControlled ? externalAppliedFilters : internalAppliedFilters;
+	const setAppliedFilters = isControlled ? setExternalAppliedFilters : setInternalAppliedFilters;
+	const draftFilters = {
+		...initialFilters,
+		...appliedFilters,
+		...pendingFilters
+	};
 	let t3;
-	if ($[6] !== _filterAdapters || $[7] !== getValueByAdapterId) {
-		let t4$1;
-		if ($[9] !== getValueByAdapterId) {
-			t4$1 = (adapter_0) => ({
-				id: adapter_0.id,
-				label: adapter_0.label,
-				count: adapter_0.getActiveFiltersCount(getValueByAdapterId(adapter_0.id))
-			});
-			$[9] = getValueByAdapterId;
-			$[10] = t4$1;
-		} else t4$1 = $[10];
-		t3 = _filterAdapters.map(t4$1);
-		$[6] = _filterAdapters;
-		$[7] = getValueByAdapterId;
-		$[8] = t3;
-	} else t3 = $[8];
-	const filterNavItems = t3;
+	if ($[2] !== appliedFilters) {
+		t3 = Object.entries(appliedFilters);
+		$[2] = appliedFilters;
+		$[3] = t3;
+	} else t3 = $[3];
 	let t4;
-	if ($[11] !== _filterAdapters || $[12] !== baseColumns) {
-		t4 = !baseColumns ? [] : baseColumns.map((col) => {
-			const adapter_1 = _filterAdapters.find((a) => a.id === col.id);
-			if (adapter_1) {
-				const cellRenderer = adapter_1.cellRenderer;
-				return {
-					...col,
-					filterFn: adapter_1.columnFilterFn,
-					...cellRenderer && { cell: (info) => cellRenderer(info.getValue()) }
-				};
-			}
-			return col;
-		});
-		$[11] = _filterAdapters;
-		$[12] = baseColumns;
-		$[13] = t4;
-	} else t4 = $[13];
-	const enhancedColumns = t4;
+	if ($[4] !== _filterAdapters || $[5] !== appliedFilters || $[6] !== t3) {
+		t4 = t3.filter((t5$1) => {
+			const [id] = t5$1;
+			const adapter_0 = _filterAdapters.find((a) => a.id === id);
+			return adapter_0 ? adapter_0.getActiveFiltersCount(appliedFilters[id]) > 0 : false;
+		}).map(_temp2);
+		$[4] = _filterAdapters;
+		$[5] = appliedFilters;
+		$[6] = t3;
+		$[7] = t4;
+	} else t4 = $[7];
+	const columnFilters = t4;
 	let t5;
-	if ($[14] === Symbol.for("react.memo_cache_sentinel")) {
-		t5 = (filterId, value) => {
-			setFilterState((prev) => ({
-				...prev,
-				[filterId]: value
-			}));
-		};
-		$[14] = t5;
-	} else t5 = $[14];
-	const updateFilter = t5;
+	if ($[8] !== _filterAdapters || $[9] !== appliedFilters) {
+		let t6$1;
+		if ($[11] !== appliedFilters) {
+			t6$1 = (adapter_1) => {
+				const value_0 = appliedFilters[adapter_1.id];
+				return value_0 !== void 0 ? adapter_1.toChips(value_0) : [];
+			};
+			$[11] = appliedFilters;
+			$[12] = t6$1;
+		} else t6$1 = $[12];
+		t5 = _filterAdapters.flatMap(t6$1);
+		$[8] = _filterAdapters;
+		$[9] = appliedFilters;
+		$[10] = t5;
+	} else t5 = $[10];
+	const filterChips = t5;
+	const filterNavItems = _filterAdapters.map((adapter_2) => ({
+		id: adapter_2.id,
+		label: adapter_2.label,
+		count: adapter_2.getActiveFiltersCount(draftFilters[adapter_2.id])
+	}));
 	let t6;
-	if ($[15] !== _filterAdapters || $[16] !== getValueByAdapterId) {
-		t6 = () => {
-			const filters = [];
-			const chips = [];
-			_filterAdapters.forEach((adapter_2) => {
-				const value_0 = getValueByAdapterId(adapter_2.id);
-				if (adapter_2.getActiveFiltersCount(value_0) > 0) filters.push({
-					id: adapter_2.id,
-					value: value_0
-				});
-				const adapterChips = adapter_2.toChips(value_0);
-				chips.push(...adapterChips);
-			});
-			setColumnFilters(filters);
-			setFilterChips(chips);
-		};
-		$[15] = _filterAdapters;
-		$[16] = getValueByAdapterId;
-		$[17] = t6;
-	} else t6 = $[17];
-	const applyFilters = t6;
+	if ($[13] !== _filterAdapters || $[14] !== baseColumns) {
+		t6 = !baseColumns ? [] : baseColumns.map((col) => {
+			const adapter_3 = _filterAdapters.find((a_0) => a_0.id === col.id);
+			if (!adapter_3) return col;
+			const cellRenderer = adapter_3.cellRenderer;
+			return {
+				...col,
+				filterFn: adapter_3.columnFilterFn,
+				...cellRenderer && { cell: (info) => cellRenderer(info.getValue()) }
+			};
+		});
+		$[13] = _filterAdapters;
+		$[14] = baseColumns;
+		$[15] = t6;
+	} else t6 = $[15];
+	const enhancedColumns = t6;
 	let t7;
-	if ($[18] !== _filterAdapters) {
-		t7 = () => {
-			const resetState = {};
-			_filterAdapters.forEach((adapter_3) => {
-				resetState[adapter_3.id] = adapter_3.reset();
-			});
-			setFilterState(resetState);
-			setColumnFilters([]);
-			setFilterChips([]);
+	if ($[16] !== setPendingFilters) {
+		t7 = (filterId, value_1) => {
+			setPendingFilters((prev) => ({
+				...prev,
+				[filterId]: value_1
+			}));
 		};
-		$[18] = _filterAdapters;
-		$[19] = t7;
-	} else t7 = $[19];
-	const clearAll = t7;
+		$[16] = setPendingFilters;
+		$[17] = t7;
+	} else t7 = $[17];
+	const updateFilter = t7;
+	const applyFilters = () => {
+		setAppliedFilters(_filterAdapters.reduce((acc, adapter_4) => {
+			const value_2 = draftFilters[adapter_4.id];
+			if (adapter_4.getActiveFiltersCount(value_2) > 0) acc[adapter_4.id] = value_2;
+			return acc;
+		}, {}));
+		setPendingFilters({});
+	};
 	let t8;
-	if ($[20] !== _filterAdapters || $[21] !== clearAll || $[22] !== getValueByAdapterId) {
-		t8 = (chip) => {
+	if ($[18] !== setAppliedFilters || $[19] !== setPendingFilters) {
+		t8 = () => {
+			setPendingFilters({});
+			setAppliedFilters({});
+		};
+		$[18] = setAppliedFilters;
+		$[19] = setPendingFilters;
+		$[20] = t8;
+	} else t8 = $[20];
+	const clearAll = t8;
+	let t9;
+	if ($[21] !== _filterAdapters || $[22] !== appliedFilters || $[23] !== setAppliedFilters) {
+		t9 = (chip) => {
 			const filterKey = typeof chip.metadata?.key === "string" ? chip.metadata.key : void 0;
 			if (!filterKey) return;
-			const adapter_4 = _filterAdapters.find((a_0) => a_0.id === filterKey);
-			if (!adapter_4) return;
-			const currentValue = getValueByAdapterId(filterKey);
-			const newValue = adapter_4.fromChip(chip, currentValue);
-			const chips_0 = [];
-			_filterAdapters.forEach((adapter_5) => {
-				const value_1 = adapter_5.id === filterKey ? newValue : getValueByAdapterId(adapter_5.id);
-				const adapterChips_0 = adapter_5.toChips(value_1);
-				chips_0.push(...adapterChips_0);
-			});
-			if (chips_0.length === 0) {
-				clearAll();
-				return;
-			}
-			setFilterState((prev_0) => ({
-				...prev_0,
+			const adapter_5 = _filterAdapters.find((a_1) => a_1.id === filterKey);
+			if (!adapter_5) return;
+			const currentValue = appliedFilters[filterKey];
+			if (currentValue === void 0) return;
+			const newValue = adapter_5.fromChip(chip, currentValue);
+			setAppliedFilters(adapter_5.getActiveFiltersCount(newValue) === 0 ? Object.fromEntries(Object.entries(appliedFilters).filter((t10$1) => {
+				const [key] = t10$1;
+				return key !== filterKey;
+			})) : {
+				...appliedFilters,
 				[filterKey]: newValue
-			}));
-			if (adapter_4.getActiveFiltersCount(newValue) === 0) setColumnFilters((prev_1) => prev_1.filter((cf) => cf.id !== filterKey));
-			else setColumnFilters((prev_2) => prev_2.map((cf_0) => cf_0.id === filterKey ? {
-				id: filterKey,
-				value: newValue
-			} : cf_0));
-			setFilterChips(chips_0);
-		};
-		$[20] = _filterAdapters;
-		$[21] = clearAll;
-		$[22] = getValueByAdapterId;
-		$[23] = t8;
-	} else t8 = $[23];
-	const deleteChip = t8;
-	let t9;
-	if ($[24] !== _filterAdapters || $[25] !== getValueByAdapterId) {
-		t9 = (selectedFilter) => {
-			const adapter_6 = _filterAdapters.find((a_1) => a_1.id === selectedFilter.id);
-			if (!adapter_6) return null;
-			const value_2 = getValueByAdapterId(adapter_6.id);
-			const onChange = (newValue_0) => updateFilter(adapter_6.id, newValue_0);
-			return adapter_6.renderFilter(value_2, onChange);
+			});
 		};
-		$[24] = _filterAdapters;
-		$[25] = getValueByAdapterId;
-		$[26] = t9;
-	} else t9 = $[26];
-	const renderFilterContent = t9;
+		$[21] = _filterAdapters;
+		$[22] = appliedFilters;
+		$[23] = setAppliedFilters;
+		$[24] = t9;
+	} else t9 = $[24];
+	const deleteChip = t9;
+	const renderFilterContent = (selectedFilter) => {
+		const adapter_6 = _filterAdapters.find((a_2) => a_2.id === selectedFilter.id);
+		if (!adapter_6) return null;
+		const value_3 = draftFilters[adapter_6.id];
+		const onChange = (newValue_0) => updateFilter(adapter_6.id, newValue_0);
+		return adapter_6.renderFilter(value_3, onChange);
+	};
 	let t10;
-	if ($[27] !== applyFilters || $[28] !== clearAll || $[29] !== deleteChip) {
+	if ($[25] !== applyFilters || $[26] !== clearAll || $[27] !== deleteChip || $[28] !== updateFilter) {
 		t10 = {
 			updateFilter,
 			applyFilters,
 			clearAll,
 			deleteChip
 		};
-		$[27] = applyFilters;
-		$[28] = clearAll;
-		$[29] = deleteChip;
-		$[30] = t10;
-	} else t10 = $[30];
-	let t11;
-	if ($[31] !== columnFilters || $[32] !== enhancedColumns || $[33] !== filterChips || $[34] !== filterNavItems || $[35] !== filterState || $[36] !== renderFilterContent || $[37] !== t10) {
-		t11 = {
-			filterState,
-			columnFilters,
-			filterChips,
-			filterNavItems,
-			enhancedColumns,
-			handlers: t10,
-			renderFilterContent
-		};
-		$[31] = columnFilters;
-		$[32] = enhancedColumns;
-		$[33] = filterChips;
-		$[34] = filterNavItems;
-		$[35] = filterState;
-		$[36] = renderFilterContent;
-		$[37] = t10;
-		$[38] = t11;
-	} else t11 = $[38];
-	return t11;
+		$[25] = applyFilters;
+		$[26] = clearAll;
+		$[27] = deleteChip;
+		$[28] = updateFilter;
+		$[29] = t10;
+	} else t10 = $[29];
+	return {
+		filterState: draftFilters,
+		columnFilters,
+		filterChips,
+		filterNavItems,
+		enhancedColumns,
+		handlers: t10,
+		renderFilterContent
+	};
+}
+function _temp2(t0) {
+	const [id_0, value] = t0;
+	return {
+		id: id_0,
+		value
+	};
+}
+function _temp(state, adapter) {
+	return {
+		...state,
+		[adapter.id]: adapter.initialValue
+	};
 }
 
 //#endregion

package/dist/components/ds-table/filters/hooks/use-table-filters.d.cts

@@ -4,21 +4,42 @@ import { ReactNode } from "react";
 import { ColumnDef } from "@tanstack/react-table";
 
 //#region src/components/ds-table/filters/hooks/use-table-filters.d.ts
+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.
+   */
+  appliedFilters?: FilterState<TValue>;
+  /**
+   * Controlled mode: Callback when filters change.
+   * Called by applyFilters(), deleteChip(), clearAll().
+   */
+  onFiltersChange?: (filters: FilterState<TValue>) => void;
+}
 interface UseTableFiltersResult<TData, TValue> {
   /**
-   * Current filter state
+   * Current draft filter state (uncommitted user selections)
    */
   filterState: FilterState<TValue>;
   /**
-   * Column filters for TanStack Table
+   * Column filters (derived from applied state)
    */
   columnFilters: ColumnFilterState<TValue>[];
   /**
-   * Filter chips for display
+   * Filter chips for display (derived from applied state)
    */
   filterChips: ChipItem[];
   /**
-   * Filter navigation items with counts
+   * Filter navigation items with active counts
    */
   filterNavItems: FilterNavItem[];
   /**
@@ -26,40 +47,52 @@ interface UseTableFiltersResult<TData, TValue> {
    */
   enhancedColumns: ColumnDef<TData>[];
   /**
-   * Handlers
+   * Handlers for filter operations
    */
   handlers: {
-    /**
-     * Update a specific filter's value
-     */
+    /** Update a specific filter's draft value */
     updateFilter: (filterId: string, value: TValue) => void;
-    /**
-     * Apply all filters (converts to TanStack format)
-     */
+    /** Commit draft state to applied state */
     applyFilters: () => void;
-    /**
-     * Clear all filters
-     */
+    /** Clear all filters */
     clearAll: () => void;
-    /**
-     * Delete a specific chip
-     */
+    /** Delete a specific filter chip */
     deleteChip: (chip: ChipItem) => void;
   };
   /**
-   * Render function for filter modal content
+   * Render function for filter content
    */
   renderFilterContent: (selectedFilter: FilterNavItem) => ReactNode;
 }
 /**
- * Hook to orchestrate table filtering with adapters
- * Manages filter state, generates chips, handles column definitions
+ * 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,
+ * });
  *
- * @param filterAdapters Array of filter adapters
- * @param baseColumns Base column definitions (optional)
- * @returns Complete filter management system
+ * @example
+ * // Controlled mode (e.g., URL-driven filtering)
+ * const { filterChips, handlers } = useTableFilters({
+ *   filterAdapters: adapters,
+ *   baseColumns: columns,
+ *   appliedFilters: filtersFromUrl,
+ *   onFiltersChange: (filters) => updateUrlAndRefetch(filters),
+ * });
  */
-declare function useTableFilters<TData, TValue, TCellValue>(filterAdapters: FilterAdapter<TData, TValue, TCellValue>[] | AnyAdapter[], baseColumns?: ColumnDef<TData>[]): UseTableFiltersResult<TData, TValue>;
+declare function useTableFilters<TData, TValue, TCellValue>({
+  filterAdapters,
+  baseColumns,
+  appliedFilters: externalAppliedFilters,
+  onFiltersChange: setExternalAppliedFilters
+}: UseTableFiltersOptions<TData, TValue, TCellValue>): UseTableFiltersResult<TData, TValue>;
 //#endregion
-export { UseTableFiltersResult, useTableFilters };
+export { UseTableFiltersOptions, UseTableFiltersResult, useTableFilters };
 //# sourceMappingURL=use-table-filters.d.cts.map

package/dist/components/ds-table/filters/hooks/use-table-filters.d.cts.map

@@ -1 +1 @@
-{"version":3,"file":"use-table-filters.d.cts","names":[],"sources":["../../../../../src/components/ds-table/filters/hooks/use-table-filters.ts"],"sourcesContent":[],"mappings":";;;;;;UAWiB;;AAAjB;;EAIc,WAAA,EAAA,WAAA,CAAY,MAAZ,CAAA;EAKoB;;;EAUjB,aAAA,EAVD,iBAUC,CAViB,MAUjB,CAAA,EAAA;EAKW;;;EAwBP,WAAA,EAlCP,QAkCO,EAAA;EAMkB;;;EAWvB,cAAA,EA9CC,aA8Cc,EAAA;EACA;;;EAAd,eAAA,EA1CC,SA0CD,CA1CW,KA0CX,CAAA,EAAA;EAA6C;;;EAErC,QAAA,EAAA;IAAO;;;4CAnCU;;;;;;;;;;;;uBAerB;;;;;wCAMkB,kBAAkB;;;;;;;;;;iBAWzC,2DACC,cAAc,OAAO,QAAQ,gBAAgB,4BAC/C,UAAU,WACtB,sBAAsB,OAAO"}
+{"version":3,"file":"use-table-filters.d.cts","names":[],"sources":["../../../../../src/components/ds-table/filters/hooks/use-table-filters.ts"],"sourcesContent":[],"mappings":";;;;;;UAWiB;;AAAjB;;EAIsC,cAAA,EAArB,aAAqB,CAAP,KAAO,EAAA,MAAA,EAAQ,UAAR,CAAA,EAAA,GAAwB,UAAxB,EAAA;EAAQ;;;EAKrB,WAAA,CAAA,EAAV,SAAU,CAAA,KAAA,CAAA,EAAA;EAAV;;;;;EAayB,cAAA,CAAA,EANtB,WAMsB,CANV,MAMU,CAAA;EAGvB;;;;EASD,eAAA,CAAA,EAAA,CAAA,OAAA,EAZa,WAYb,CAZyB,MAYzB,CAAA,EAAA,GAAA,IAAA;;AAUC,UAnBA,qBAmBA,CAAA,KAAA,EAAA,MAAA,CAAA,CAAA;EAKW;;;EAaP,WAAA,EAjCP,WAiCO,CAjCK,MAiCL,CAAA;EAMkB;;;EA0BvB,aAAA,EA5DA,iBA4De,CA5DG,MA4DH,CAAA,EAAA;EAC9B;;;EAGiB,WAAA,EA3DJ,QA2DI,EAAA;EACQ;;;EAAvB,cAAA,EAvDc,aAuDd,EAAA;EAA0E;;;EAAD,eAAA,EAlD1D,SAkD0D,CAlDhD,KAkDgD,CAAA,EAAA;;;;;;4CA3ClC;;;;;;uBAMrB;;;;;wCAMkB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BzC;;;kBAGC;mBACC;GACf,uBAAuB,OAAO,QAAQ,cAAc,sBAAsB,OAAO"}

package/dist/components/ds-table/filters/hooks/use-table-filters.d.ts

@@ -5,21 +5,42 @@ import { ReactNode } from "react";
 import { ColumnDef } from "@tanstack/react-table";
 
 //#region src/components/ds-table/filters/hooks/use-table-filters.d.ts
+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.
+   */
+  appliedFilters?: FilterState<TValue>;
+  /**
+   * Controlled mode: Callback when filters change.
+   * Called by applyFilters(), deleteChip(), clearAll().
+   */
+  onFiltersChange?: (filters: FilterState<TValue>) => void;
+}
 interface UseTableFiltersResult<TData, TValue> {
   /**
-   * Current filter state
+   * Current draft filter state (uncommitted user selections)
    */
   filterState: FilterState<TValue>;
   /**
-   * Column filters for TanStack Table
+   * Column filters (derived from applied state)
    */
   columnFilters: ColumnFilterState<TValue>[];
   /**
-   * Filter chips for display
+   * Filter chips for display (derived from applied state)
    */
   filterChips: ChipItem[];
   /**
-   * Filter navigation items with counts
+   * Filter navigation items with active counts
    */
   filterNavItems: FilterNavItem[];
   /**
@@ -27,40 +48,52 @@ interface UseTableFiltersResult<TData, TValue> {
    */
   enhancedColumns: ColumnDef<TData>[];
   /**
-   * Handlers
+   * Handlers for filter operations
    */
   handlers: {
-    /**
-     * Update a specific filter's value
-     */
+    /** Update a specific filter's draft value */
     updateFilter: (filterId: string, value: TValue) => void;
-    /**
-     * Apply all filters (converts to TanStack format)
-     */
+    /** Commit draft state to applied state */
     applyFilters: () => void;
-    /**
-     * Clear all filters
-     */
+    /** Clear all filters */
     clearAll: () => void;
-    /**
-     * Delete a specific chip
-     */
+    /** Delete a specific filter chip */
     deleteChip: (chip: ChipItem) => void;
   };
   /**
-   * Render function for filter modal content
+   * Render function for filter content
    */
   renderFilterContent: (selectedFilter: FilterNavItem) => ReactNode;
 }
 /**
- * Hook to orchestrate table filtering with adapters
- * Manages filter state, generates chips, handles column definitions
+ * 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,
+ * });
  *
- * @param filterAdapters Array of filter adapters
- * @param baseColumns Base column definitions (optional)
- * @returns Complete filter management system
+ * @example
+ * // Controlled mode (e.g., URL-driven filtering)
+ * const { filterChips, handlers } = useTableFilters({
+ *   filterAdapters: adapters,
+ *   baseColumns: columns,
+ *   appliedFilters: filtersFromUrl,
+ *   onFiltersChange: (filters) => updateUrlAndRefetch(filters),
+ * });
  */
-declare function useTableFilters<TData, TValue, TCellValue>(filterAdapters: FilterAdapter<TData, TValue, TCellValue>[] | AnyAdapter[], baseColumns?: ColumnDef<TData>[]): UseTableFiltersResult<TData, TValue>;
+declare function useTableFilters<TData, TValue, TCellValue>({
+  filterAdapters,
+  baseColumns,
+  appliedFilters: externalAppliedFilters,
+  onFiltersChange: setExternalAppliedFilters
+}: UseTableFiltersOptions<TData, TValue, TCellValue>): UseTableFiltersResult<TData, TValue>;
 //#endregion
-export { UseTableFiltersResult, useTableFilters };
+export { UseTableFiltersOptions, UseTableFiltersResult, useTableFilters };
 //# sourceMappingURL=use-table-filters.d.ts.map

package/dist/components/ds-table/filters/hooks/use-table-filters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"use-table-filters.d.ts","names":[],"sources":["../../../../../src/components/ds-table/filters/hooks/use-table-filters.ts"],"sourcesContent":[],"mappings":";;;;;;;UAWiB;;;AAAjB;EAI0B,WAAA,EAAZ,WAAY,CAAA,MAAA,CAAA;EAAZ;;;EAUA,aAAA,EALE,iBAKF,CALoB,MAKpB,CAAA,EAAA;EAKG;;;EAcyB,WAAA,EAnB5B,QAmB4B,EAAA;EAerB;;;EAM6C,cAAA,EAnCjD,aAmCiD,EAAA;EAWlD;;;EAC8B,eAAA,EA1C5B,SA0C4B,CA1ClB,KA0CkB,CAAA,EAAA;EAA7B;;;EACF,QAAA,EAAA;IACU;;;IAAD,YAAA,EAAA,CAAA,QAAA,EAAA,MAAA,EAAA,KAAA,EAnCkB,MAmClB,EAAA,GAAA,IAAA;;;;;;;;;;;;uBApBH;;;;;wCAMkB,kBAAkB;;;;;;;;;;iBAWzC,2DACC,cAAc,OAAO,QAAQ,gBAAgB,4BAC/C,UAAU,WACtB,sBAAsB,OAAO"}
+{"version":3,"file":"use-table-filters.d.ts","names":[],"sources":["../../../../../src/components/ds-table/filters/hooks/use-table-filters.ts"],"sourcesContent":[],"mappings":";;;;;;;UAWiB;;;AAAjB;EAI+B,cAAA,EAAd,aAAc,CAAA,KAAA,EAAO,MAAP,EAAe,UAAf,CAAA,EAAA,GAA+B,UAA/B,EAAA;EAAO;;;EAAwB,WAAA,CAAA,EAK/C,SAL+C,CAKrC,KALqC,CAAA,EAAA;EAKrC;;;;;EAaI,cAAA,CAAA,EANX,WAMW,CANC,MAMD,CAAA;EAAW;AAGxC;;;EASkC,eAAA,CAAA,EAAA,CAAA,OAAA,EAZL,WAYK,CAZO,MAYP,CAAA,EAAA,GAAA,IAAA;;AAKpB,UAdG,qBAcH,CAAA,KAAA,EAAA,MAAA,CAAA,CAAA;EAKG;;;EAYyB,WAAA,EA3B5B,WA2B4B,CA3BhB,MA2BgB,CAAA;EAMrB;;;EAM6C,aAAA,EAlClD,iBAkCkD,CAlChC,MAkCgC,CAAA,EAAA;EA0BlD;;;EAGC,WAAA,EA1DH,QA0DG,EAAA;EACC;;;EACuB,cAAA,EAvDxB,aAuDwB,EAAA;EAAtC;;;EAAoD,eAAA,EAlDrC,SAkDqC,CAlD3B,KAkD2B,CAAA,EAAA;EAAqB;;;;;4CA3ClC;;;;;;uBAMrB;;;;;wCAMkB,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;iBA0BzC;;;kBAGC;mBACC;GACf,uBAAuB,OAAO,QAAQ,cAAc,sBAAsB,OAAO"}