@toniel/laravel-tanstack-pagination 0.1.1 → 0.1.2

package/README.md

@@ -94,13 +94,15 @@ Main composable for handling Laravel pagination.
 | `search` | `Ref<string>` | Current search query |
 | `sortBy` | `Ref<string \| null>` | Current sort column |
 | `sortDirection` | `Ref<'asc' \| 'desc'>` | Sort direction |
-| `filters` | `ComputedRef<PaginationFilters>` | All active filters |
+| `filters` | `ComputedRef<PaginationFilters>` | All active filters (including custom filters) |
+| `customFilters` | `Ref<Record<string, any>>` | Custom filter state (for external use) |
 | `isLoading` | `Ref<boolean>` | Loading state from TanStack Query |
 | `error` | `Ref<Error \| null>` | Error state from TanStack Query |
 | `handlePageChange` | `(page: number) => void` | Change page handler |
 | `handlePerPageChange` | `(perPage: number) => void` | Change per page handler |
 | `handleSearchChange` | `(search: string) => void` | Search change handler (debounced) |
 | `handleSortChange` | `(column: string) => void` | Toggle sort on column |
+| `handleFilterChange` | `(filters: Record<string, any>) => void` | Bulk update custom filters |
 | `setFilter` | `(key: string, value: any) => void` | Add custom filter |
 | `removeFilter` | `(key: string) => void` | Remove custom filter |
 | `resetFilters` | `() => void` | Reset all filters to defaults |
@@ -257,6 +259,158 @@ npm install @toniel/laravel-tanstack-datatable
 
 See: https://www.npmjs.com/package/@toniel/laravel-tanstack-datatable
 
+## 🔍 Filtering
+
+The `usePagination` composable provides comprehensive filter management with proper state persistence across page changes.
+
+### Single Filter Operations
+
+```typescript
+const {
+  setFilter,
+  removeFilter,
+  customFilters,
+  refetch,
+} = usePagination(fetchFn, { queryKey: 'users' })
+
+// Set a single filter
+setFilter('status', 'active')
+setFilter('category', 'A')
+
+// Remove a filter
+removeFilter('status')
+
+// The query will automatically refetch when filters change
+```
+
+### Bulk Filter Operations
+
+```typescript
+const {
+  handleFilterChange,
+  customFilters,
+  refetch,
+} = usePagination(fetchFn, { queryKey: 'users' })
+
+// Bulk update multiple filters at once
+handleFilterChange({
+  status: 'active',
+  category: 'A',
+  year: '2024'
+})
+
+// Or pass partial updates (will merge with existing)
+handleFilterChange({
+  ...customFilters.value,
+  status: 'inactive'
+})
+```
+
+### Filter State Persistence
+
+Custom filters are properly included in the TanStack Query cache key, ensuring:
+- Filters persist when changing pages
+- Filters persist when changing per page
+- Correct cache invalidation on filter changes
+- Back/forward navigation works correctly
+
+```typescript
+// Filters are automatically included in queryKey
+const { filters } = usePagination(fetchFn, { queryKey: 'users' })
+
+// filters.value = { page: 1, per_page: 10, search: '', status: 'active', category: 'A' }
+```
+
+### Reset Filters
+
+```typescript
+const {
+  resetFilters,
+  customFilters,
+  search,
+  perPage,
+} = usePagination(fetchFn, { queryKey: 'users', defaultPerPage: 20 })
+
+// Reset all filters to defaults
+resetFilters()
+
+// After reset:
+// - customFilters = {}
+// - search = ''
+// - perPage = 20
+// - page = 1
+```
+
+### Example: Complex Filter Form
+
+```typescript
+<script setup lang="ts">
+import { ref, computed } from 'vue'
+import { usePagination } from '@toniel/laravel-tanstack-pagination'
+
+// Filter form state (separate from composable)
+const filterForm = ref({
+  status: '',
+  category: '',
+  year: new Date().getFullYear().toString(),
+  month: '',
+})
+
+const {
+  tableData,
+  pagination,
+  customFilters,
+  setFilter,
+  removeFilter,
+  handlePageChange,
+  refetch,
+} = usePagination(
+  (filters) => axios.get('/api/transactions', { params: filters }),
+  { queryKey: 'transactions', defaultPerPage: 20 }
+)
+
+// Apply filters
+const applyFilters = () => {
+  // Clear existing custom filters first
+  if (filterForm.value.status) {
+    setFilter('status', filterForm.value.status)
+  } else {
+    removeFilter('status')
+  }
+  
+  if (filterForm.value.category) {
+    setFilter('category', filterForm.value.category)
+  } else {
+    removeFilter('category')
+  }
+  
+  if (filterForm.value.year) {
+    setFilter('year', filterForm.value.year)
+  } else {
+    removeFilter('year')
+  }
+  
+  if (filterForm.value.month) {
+    setFilter('month', filterForm.value.month)
+  } else {
+    removeFilter('month')
+  }
+  
+  refetch()
+}
+
+// Clear all filters
+const clearFilters = () => {
+  filterForm.value = { status: '', category: '', year: new Date().getFullYear().toString(), month: '' }
+  removeFilter('status')
+  removeFilter('category')
+  removeFilter('year')
+  removeFilter('month')
+  refetch()
+}
+</script>
+```
+
 ## 🔧 Laravel Backend Setup
 
 Your Laravel API should return paginated responses in this format:

package/dist/index.d.mts

@@ -52,6 +52,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -101,6 +102,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -108,6 +110,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -157,6 +160,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -164,6 +168,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -213,6 +218,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -220,6 +226,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -269,6 +276,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -276,6 +284,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -325,6 +334,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -332,6 +342,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -381,6 +392,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 };
 
 interface NumberingOptions {

package/dist/index.d.ts

@@ -52,6 +52,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -101,6 +102,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -108,6 +110,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -157,6 +160,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -164,6 +168,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -213,6 +218,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -220,6 +226,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -269,6 +276,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -276,6 +284,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -325,6 +334,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 } | {
     tableData: vue.ComputedRef<T[]>;
     pagination: vue.ComputedRef<LaravelPaginationResponse<T> | null>;
@@ -332,6 +342,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     handlePerPageChange: (newPerPage: number) => void;
     handleSearchChange: (newSearch: string) => void;
     handleSortChange: (column: string) => void;
+    handleFilterChange: (newFilters: Record<string, any>) => void;
     resetFilters: () => void;
     setFilter: (key: string, value: any) => void;
     removeFilter: (key: string) => void;
@@ -381,6 +392,7 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     sortBy: vue.Ref<string | null, string | null>;
     sortDirection: vue.Ref<"asc" | "desc", "asc" | "desc">;
     filters: vue.ComputedRef<PaginationFilters>;
+    customFilters: vue.Ref<Record<string, any>, Record<string, any>>;
 };
 
 interface NumberingOptions {

package/dist/index.js

@@ -103,11 +103,13 @@ function usePagination(fetchFn, options) {
   const search = (0, import_vue2.ref)(options.defaultSearch || "");
   const sortBy = (0, import_vue2.ref)(options.defaultSort?.column || null);
   const sortDirection = (0, import_vue2.ref)(options.defaultSort?.direction || "asc");
+  const customFilters = (0, import_vue2.ref)({});
   const filters = (0, import_vue2.computed)(() => {
     const baseFilters = {
       page: currentPage.value,
       per_page: perPage.value,
-      search: search.value
+      search: search.value,
+      ...customFilters.value
     };
     if (sortBy.value) {
       baseFilters[`sort[${sortBy.value}]`] = sortDirection.value;
@@ -143,11 +145,15 @@ function usePagination(fetchFn, options) {
     currentPage.value = 1;
   };
   const setFilter = (key, value) => {
-    filters.value[key] = value;
+    customFilters.value[key] = value;
     currentPage.value = 1;
   };
   const removeFilter = (key) => {
-    delete filters.value[key];
+    delete customFilters.value[key];
+    currentPage.value = 1;
+  };
+  const handleFilterChange = (newFilters) => {
+    customFilters.value = { ...newFilters };
     currentPage.value = 1;
   };
   const resetFilters = () => {
@@ -156,6 +162,7 @@ function usePagination(fetchFn, options) {
     search.value = options.defaultSearch || "";
     sortBy.value = options.defaultSort?.column || null;
     sortDirection.value = options.defaultSort?.direction || "asc";
+    customFilters.value = {};
   };
   let searchTimeout;
   (0, import_vue2.watch)(search, () => {
@@ -176,6 +183,7 @@ function usePagination(fetchFn, options) {
     sortBy,
     sortDirection,
     filters,
+    customFilters,
     // Query result
     ...queryResult,
     // Computed
@@ -186,6 +194,7 @@ function usePagination(fetchFn, options) {
     handlePerPageChange,
     handleSearchChange,
     handleSortChange,
+    handleFilterChange,
     resetFilters,
     setFilter,
     removeFilter,

package/dist/index.mjs

@@ -76,11 +76,13 @@ function usePagination(fetchFn, options) {
   const search = ref(options.defaultSearch || "");
   const sortBy = ref(options.defaultSort?.column || null);
   const sortDirection = ref(options.defaultSort?.direction || "asc");
+  const customFilters = ref({});
   const filters = computed(() => {
     const baseFilters = {
       page: currentPage.value,
       per_page: perPage.value,
-      search: search.value
+      search: search.value,
+      ...customFilters.value
     };
     if (sortBy.value) {
       baseFilters[`sort[${sortBy.value}]`] = sortDirection.value;
@@ -116,11 +118,15 @@ function usePagination(fetchFn, options) {
     currentPage.value = 1;
   };
   const setFilter = (key, value) => {
-    filters.value[key] = value;
+    customFilters.value[key] = value;
     currentPage.value = 1;
   };
   const removeFilter = (key) => {
-    delete filters.value[key];
+    delete customFilters.value[key];
+    currentPage.value = 1;
+  };
+  const handleFilterChange = (newFilters) => {
+    customFilters.value = { ...newFilters };
     currentPage.value = 1;
   };
   const resetFilters = () => {
@@ -129,6 +135,7 @@ function usePagination(fetchFn, options) {
     search.value = options.defaultSearch || "";
     sortBy.value = options.defaultSort?.column || null;
     sortDirection.value = options.defaultSort?.direction || "asc";
+    customFilters.value = {};
   };
   let searchTimeout;
   watch(search, () => {
@@ -149,6 +156,7 @@ function usePagination(fetchFn, options) {
     sortBy,
     sortDirection,
     filters,
+    customFilters,
     // Query result
     ...queryResult,
     // Computed
@@ -159,6 +167,7 @@ function usePagination(fetchFn, options) {
     handlePerPageChange,
     handleSearchChange,
     handleSortChange,
+    handleFilterChange,
     resetFilters,
     setFilter,
     removeFilter,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toniel/laravel-tanstack-pagination",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Vue 3 composables for Laravel pagination with TanStack Query",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",