@toniel/laravel-tanstack-pagination 0.1.1 → 0.1.3

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

@@ -5,12 +5,12 @@ import { Ref, ComputedRef } from 'vue';
 
 type LaravelPaginationResponse<T = any> = {
     data: T[];
-    links: Array<{
+    links: {
         first: string | null;
         last: string | null;
         next: string | null;
         prev: string | null;
-    }>;
+    };
     meta: {
         current_page: number;
         from: number;
@@ -44,6 +44,7 @@ interface UsePaginationOptions<T> extends Omit<UseQueryOptions<LaravelPagination
     defaultPerPage?: number;
     defaultSearch?: string;
     defaultSort?: SortState;
+    debounceMs?: number;
 }
 declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) => Promise<LaravelPaginationResponse<T>>, options: UsePaginationOptions<T>): {
     tableData: vue.ComputedRef<T[]>;
@@ -52,10 +53,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -97,10 +99,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +112,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -153,10 +158,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +171,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -209,10 +217,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +230,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -265,10 +276,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +289,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -321,10 +335,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +348,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -377,10 +394,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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

@@ -5,12 +5,12 @@ import { Ref, ComputedRef } from 'vue';
 
 type LaravelPaginationResponse<T = any> = {
     data: T[];
-    links: Array<{
+    links: {
         first: string | null;
         last: string | null;
         next: string | null;
         prev: string | null;
-    }>;
+    };
     meta: {
         current_page: number;
         from: number;
@@ -44,6 +44,7 @@ interface UsePaginationOptions<T> extends Omit<UseQueryOptions<LaravelPagination
     defaultPerPage?: number;
     defaultSearch?: string;
     defaultSort?: SortState;
+    debounceMs?: number;
 }
 declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) => Promise<LaravelPaginationResponse<T>>, options: UsePaginationOptions<T>): {
     tableData: vue.ComputedRef<T[]>;
@@ -52,10 +53,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -97,10 +99,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +112,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -153,10 +158,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +171,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -209,10 +217,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +230,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -265,10 +276,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +289,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -321,10 +335,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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,10 +348,11 @@ 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;
-    getNumberingColumn: (options?: any) => {
+    getNumberingColumn: (columnOptions?: any) => {
         accessorKey: string;
         header: string;
         enableSorting: boolean;
@@ -377,10 +394,12 @@ declare function usePagination<T = any>(fetchFn: (filters: PaginationFilters) =>
     suspense: () => Promise<_tanstack_vue_query.QueryObserverResult<LaravelPaginationResponse<T>, Error>>;
     currentPage: vue.Ref<number, number>;
     perPage: vue.Ref<number, number>;
+    currentPerPage: vue.Ref<number, number>;
     search: vue.Ref<string, string>;
     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

@@ -31,7 +31,7 @@ function useTableNumbering() {
   const createNumberingColumn = (pagination, perPage, options = {}) => {
     const {
       header = "No.",
-      className = "text-center text-ubd-ocean-700 dark:text-ubd-ocean-200 font-medium",
+      className = "",
       width = "60px",
       enableSorting = false
     } = options;
@@ -97,19 +97,32 @@ function useTableNumbering() {
 // src/composables/usePagination.ts
 var import_vue_query = require("@tanstack/vue-query");
 var import_vue2 = require("vue");
+var VALID_SORT_COLUMN = /^[a-zA-Z0-9_.]+$/;
 function usePagination(fetchFn, options) {
   const currentPage = (0, import_vue2.ref)(1);
   const perPage = (0, import_vue2.ref)(options.defaultPerPage || 10);
   const search = (0, import_vue2.ref)(options.defaultSearch || "");
+  const debouncedSearch = (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)({});
+  let searchTimeout;
+  (0, import_vue2.watch)(search, (newValue) => {
+    clearTimeout(searchTimeout);
+    searchTimeout = setTimeout(() => {
+      debouncedSearch.value = newValue;
+      currentPage.value = 1;
+    }, options.debounceMs ?? 300);
+  });
+  (0, import_vue2.onScopeDispose)(() => clearTimeout(searchTimeout));
   const filters = (0, import_vue2.computed)(() => {
     const baseFilters = {
       page: currentPage.value,
       per_page: perPage.value,
-      search: search.value
+      search: debouncedSearch.value,
+      ...customFilters.value
     };
-    if (sortBy.value) {
+    if (sortBy.value && VALID_SORT_COLUMN.test(sortBy.value)) {
       baseFilters[`sort[${sortBy.value}]`] = sortDirection.value;
     }
     return baseFilters;
@@ -118,22 +131,24 @@ function usePagination(fetchFn, options) {
     ...options,
     queryKey: [options.queryKey, filters],
     queryFn: () => fetchFn(filters.value),
+    placeholderData: import_vue_query.keepPreviousData,
     refetchOnWindowFocus: false
   });
   const tableData = (0, import_vue2.computed)(() => queryResult.data.value?.data || []);
   const pagination = (0, import_vue2.computed)(() => queryResult.data.value || null);
   const handlePageChange = (page) => {
-    currentPage.value = page;
+    const lastPage = pagination.value?.meta?.last_page ?? Infinity;
+    currentPage.value = Math.min(Math.max(1, Math.floor(page)), lastPage);
   };
   const handlePerPageChange = (newPerPage) => {
-    perPage.value = newPerPage;
+    perPage.value = Math.max(1, Math.floor(newPerPage));
     currentPage.value = 1;
   };
   const handleSearchChange = (newSearch) => {
     search.value = newSearch;
-    currentPage.value = 1;
   };
   const handleSortChange = (column) => {
+    if (!VALID_SORT_COLUMN.test(column)) return;
     if (sortBy.value === column) {
       sortDirection.value = sortDirection.value === "asc" ? "desc" : "asc";
     } else {
@@ -143,39 +158,41 @@ function usePagination(fetchFn, options) {
     currentPage.value = 1;
   };
   const setFilter = (key, value) => {
-    filters.value[key] = value;
+    customFilters.value = { ...customFilters.value, [key]: value };
     currentPage.value = 1;
   };
   const removeFilter = (key) => {
-    delete filters.value[key];
+    const { [key]: _, ...rest } = customFilters.value;
+    customFilters.value = rest;
+    currentPage.value = 1;
+  };
+  const handleFilterChange = (newFilters) => {
+    customFilters.value = { ...newFilters };
     currentPage.value = 1;
   };
   const resetFilters = () => {
     currentPage.value = 1;
     perPage.value = options.defaultPerPage || 10;
     search.value = options.defaultSearch || "";
+    debouncedSearch.value = options.defaultSearch || "";
     sortBy.value = options.defaultSort?.column || null;
     sortDirection.value = options.defaultSort?.direction || "asc";
+    customFilters.value = {};
   };
-  let searchTimeout;
-  (0, import_vue2.watch)(search, () => {
-    clearTimeout(searchTimeout);
-    searchTimeout = window.setTimeout(() => {
-      currentPage.value = 1;
-    }, 300);
-  });
   const { createNumberingColumn } = useTableNumbering();
-  const getNumberingColumn = (options2 = {}) => {
-    return createNumberingColumn(pagination, perPage, options2);
+  const getNumberingColumn = (columnOptions = {}) => {
+    return createNumberingColumn(pagination, perPage, columnOptions);
   };
   return {
     // State
     currentPage,
     perPage,
+    currentPerPage: perPage,
     search,
     sortBy,
     sortDirection,
     filters,
+    customFilters,
     // Query result
     ...queryResult,
     // Computed
@@ -186,6 +203,7 @@ function usePagination(fetchFn, options) {
     handlePerPageChange,
     handleSearchChange,
     handleSortChange,
+    handleFilterChange,
     resetFilters,
     setFilter,
     removeFilter,

package/dist/index.mjs

@@ -4,7 +4,7 @@ function useTableNumbering() {
   const createNumberingColumn = (pagination, perPage, options = {}) => {
     const {
       header = "No.",
-      className = "text-center text-ubd-ocean-700 dark:text-ubd-ocean-200 font-medium",
+      className = "",
       width = "60px",
       enableSorting = false
     } = options;
@@ -68,21 +68,34 @@ function useTableNumbering() {
 }
 
 // src/composables/usePagination.ts
-import { useQuery } from "@tanstack/vue-query";
-import { computed, ref, watch } from "vue";
+import { useQuery, keepPreviousData } from "@tanstack/vue-query";
+import { computed, onScopeDispose, ref, watch } from "vue";
+var VALID_SORT_COLUMN = /^[a-zA-Z0-9_.]+$/;
 function usePagination(fetchFn, options) {
   const currentPage = ref(1);
   const perPage = ref(options.defaultPerPage || 10);
   const search = ref(options.defaultSearch || "");
+  const debouncedSearch = ref(options.defaultSearch || "");
   const sortBy = ref(options.defaultSort?.column || null);
   const sortDirection = ref(options.defaultSort?.direction || "asc");
+  const customFilters = ref({});
+  let searchTimeout;
+  watch(search, (newValue) => {
+    clearTimeout(searchTimeout);
+    searchTimeout = setTimeout(() => {
+      debouncedSearch.value = newValue;
+      currentPage.value = 1;
+    }, options.debounceMs ?? 300);
+  });
+  onScopeDispose(() => clearTimeout(searchTimeout));
   const filters = computed(() => {
     const baseFilters = {
       page: currentPage.value,
       per_page: perPage.value,
-      search: search.value
+      search: debouncedSearch.value,
+      ...customFilters.value
     };
-    if (sortBy.value) {
+    if (sortBy.value && VALID_SORT_COLUMN.test(sortBy.value)) {
       baseFilters[`sort[${sortBy.value}]`] = sortDirection.value;
     }
     return baseFilters;
@@ -91,22 +104,24 @@ function usePagination(fetchFn, options) {
     ...options,
     queryKey: [options.queryKey, filters],
     queryFn: () => fetchFn(filters.value),
+    placeholderData: keepPreviousData,
     refetchOnWindowFocus: false
   });
   const tableData = computed(() => queryResult.data.value?.data || []);
   const pagination = computed(() => queryResult.data.value || null);
   const handlePageChange = (page) => {
-    currentPage.value = page;
+    const lastPage = pagination.value?.meta?.last_page ?? Infinity;
+    currentPage.value = Math.min(Math.max(1, Math.floor(page)), lastPage);
   };
   const handlePerPageChange = (newPerPage) => {
-    perPage.value = newPerPage;
+    perPage.value = Math.max(1, Math.floor(newPerPage));
     currentPage.value = 1;
   };
   const handleSearchChange = (newSearch) => {
     search.value = newSearch;
-    currentPage.value = 1;
   };
   const handleSortChange = (column) => {
+    if (!VALID_SORT_COLUMN.test(column)) return;
     if (sortBy.value === column) {
       sortDirection.value = sortDirection.value === "asc" ? "desc" : "asc";
     } else {
@@ -116,39 +131,41 @@ function usePagination(fetchFn, options) {
     currentPage.value = 1;
   };
   const setFilter = (key, value) => {
-    filters.value[key] = value;
+    customFilters.value = { ...customFilters.value, [key]: value };
     currentPage.value = 1;
   };
   const removeFilter = (key) => {
-    delete filters.value[key];
+    const { [key]: _, ...rest } = customFilters.value;
+    customFilters.value = rest;
+    currentPage.value = 1;
+  };
+  const handleFilterChange = (newFilters) => {
+    customFilters.value = { ...newFilters };
     currentPage.value = 1;
   };
   const resetFilters = () => {
     currentPage.value = 1;
     perPage.value = options.defaultPerPage || 10;
     search.value = options.defaultSearch || "";
+    debouncedSearch.value = options.defaultSearch || "";
     sortBy.value = options.defaultSort?.column || null;
     sortDirection.value = options.defaultSort?.direction || "asc";
+    customFilters.value = {};
   };
-  let searchTimeout;
-  watch(search, () => {
-    clearTimeout(searchTimeout);
-    searchTimeout = window.setTimeout(() => {
-      currentPage.value = 1;
-    }, 300);
-  });
   const { createNumberingColumn } = useTableNumbering();
-  const getNumberingColumn = (options2 = {}) => {
-    return createNumberingColumn(pagination, perPage, options2);
+  const getNumberingColumn = (columnOptions = {}) => {
+    return createNumberingColumn(pagination, perPage, columnOptions);
   };
   return {
     // State
     currentPage,
     perPage,
+    currentPerPage: perPage,
     search,
     sortBy,
     sortDirection,
     filters,
+    customFilters,
     // Query result
     ...queryResult,
     // Computed
@@ -159,6 +176,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.3",
   "description": "Vue 3 composables for Laravel pagination with TanStack Query",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",