@toniel/laravel-tanstack-pagination 0.1.0 → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Toniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,23 +1,51 @@
 # Laravel TanStack Pagination
 
-Vue 3 composables untuk Laravel pagination dengan TanStack Query.
+[![npm version](https://img.shields.io/npm/v/@toniel/laravel-tanstack-pagination)](https://www.npmjs.com/package/@toniel/laravel-tanstack-pagination)
+[![npm downloads](https://img.shields.io/npm/dm/@toniel/laravel-tanstack-pagination)](https://www.npmjs.com/package/@toniel/laravel-tanstack-pagination)
+[![GitHub](https://img.shields.io/github/license/toniel/laravel-tanstack-pagination)](https://github.com/toniel/laravel-tanstack-pagination/blob/main/LICENSE)
+[![GitHub stars](https://img.shields.io/github/stars/toniel/laravel-tanstack-pagination)](https://github.com/toniel/laravel-tanstack-pagination)
 
-## Installation
+Vue 3 composables untuk Laravel pagination dengan TanStack Query - **Headless & Framework Agnostic**.
+
+> 💡 **Looking for ready-to-use UI components?** Check out [`@toniel/laravel-tanstack-datatable`](https://github.com/toniel/laravel-tanstack-datatable) - Pre-built DataTable components with this library.
+
+## 📦 Installation
 
 ```bash
 npm install @toniel/laravel-tanstack-pagination
+# or
+yarn add @toniel/laravel-tanstack-pagination
+# or
+pnpm add @toniel/laravel-tanstack-pagination
+# or
+bun add @toniel/laravel-tanstack-pagination
 ```
 
-## Usage
+### Peer Dependencies
+
+```bash
+npm install vue @tanstack/vue-query
+```
+
+## 🚀 Quick Start
 
 ```typescript
 import { usePagination } from '@toniel/laravel-tanstack-pagination'
+import axios from 'axios'
 
 const {
   tableData,
   pagination,
+  search,
+  currentPerPage,
+  sortBy,
+  sortDirection,
+  isLoading,
+  error,
   handlePageChange,
-  handleSearchChange
+  handlePerPageChange,
+  handleSearchChange,
+  handleSortChange,
 } = usePagination(
   (filters) => axios.get('/api/users', { params: filters }),
   {
@@ -27,47 +55,456 @@ const {
 )
 ```
 
-## Features
+## ✨ Features
 
-- ✅ Laravel pagination support
-- ✅ TanStack Query integration
-- ✅ Search with debounce
-- ✅ Sorting
-- ✅ Table numbering helper
-- ✅ TypeScript support
+- ✅ **Headless** - Bring your own UI components
+- ✅ **Laravel pagination** support out of the box
+- ✅ **TanStack Query** integration for caching & refetching
+- ✅ **Search** with automatic debounce
+- ✅ **Sorting** (server-side)
+- ✅ **Filtering** with flexible API
+- ✅ **Table numbering** helper for sequential row numbers
+- ✅ **TypeScript** fully typed
+- ✅ **Framework agnostic** - Works with any UI library
 
-## API
+## 📖 API Reference
 
 ### `usePagination(fetchFn, options)`
 
 Main composable for handling Laravel pagination.
 
 **Parameters:**
-- `fetchFn`: Function that fetches data from Laravel API
-- `options`: Configuration options
-  - `queryKey`: Unique key for the query
-  - `defaultPerPage`: Items per page (default: 10)
+- `fetchFn`: `(filters: PaginationFilters) => Promise<LaravelPaginationResponse<T>>`
+  - Function that fetches data from Laravel API
+- `options`: `UsePaginationOptions<T>`
+  - `queryKey`: `string` - Unique key for the query (required)
+  - `defaultPerPage`: `number` - Items per page (default: `10`)
+  - `defaultSearch`: `string` - Default search query (default: `''`)
+  - `defaultSort`: `SortState` - Default sort state (default: `null`)
+  - ...all other TanStack Query options
 
 **Returns:**
-- `tableData`: Computed array of data items
-- `pagination`: Reactive pagination state
-- `handlePageChange`: Function to change page
-- `handleSearchChange`: Function to handle search input
-- `handleSortChange`: Function to handle sorting
-- `isLoading`: Loading state
-- `error`: Error state
 
-### `useTableNumbering(currentPage, perPage)`
+| Property | Type | Description |
+|----------|------|-------------|
+| `tableData` | `Ref<T[]>` | Computed array of data items |
+| `pagination` | `Ref<LaravelPaginationResponse \| null>` | Full Laravel pagination response |
+| `currentPage` | `Ref<number>` | Current page number |
+| `perPage` | `Ref<number>` | Items per page |
+| `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 (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 |
+| `getNumberingColumn` | `(options?) => ColumnDef` | Get numbering column for TanStack Table |
+| `refetch` | TanStack Query refetch function |
+| `...queryResult` | All other TanStack Query return values |
 
-Helper composable for table row numbering.
+### `useTableNumbering()`
 
-**Parameters:**
-- `currentPage`: Current page number
-- `perPage`: Items per page
+Helper composable for creating table row numbering columns.
 
 **Returns:**
-- `getRowNumber(index)`: Function to get row number for index
+- `createNumberingColumn(pagination, perPage, options?)`: Function to create a numbering column definition for TanStack Table
+
+**Example:**
+```ts
+const { createNumberingColumn } = useTableNumbering()
+
+const numberingColumn = createNumberingColumn(
+  pagination, // ref from usePagination
+  perPage,    // ref from usePagination
+  {
+    header: '#',
+    enableSorting: false
+  }
+)
+```
+
+## 🔗 TypeScript Types
+
+```typescript
+// Laravel Pagination Response
+type LaravelPaginationResponse<T = any> = {
+  data: T[]
+  links: {
+    first: string | null
+    last: string | null
+    next: string | null
+    prev: string | null
+  }[]
+  meta: {
+    current_page: number
+    from: number
+    last_page: number
+    links: Array<{
+      url: string | null
+      label: string
+      active: boolean
+    }>
+    path: string
+    per_page: number
+    to: number
+    total: number
+  }
+}
+
+// Pagination Filters
+interface PaginationFilters {
+  page?: number
+  per_page?: number
+  search?: string
+  [key: string]: any // Custom filters
+}
+
+// Sort State
+interface SortState {
+  column: string | null
+  direction: 'asc' | 'desc'
+}
+```
+
+## 🎯 Usage with UI Libraries
+
+### With Custom Table Component
+
+```vue
+<template>
+  <div>
+    <!-- Search -->
+    <input v-model="search" @input="handleSearchChange" />
+    
+    <!-- Table -->
+    <table>
+      <thead>
+        <tr>
+          <th @click="handleSortChange('name')">Name</th>
+          <th @click="handleSortChange('email')">Email</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr v-for="user in tableData" :key="user.id">
+          <td>{{ user.name }}</td>
+          <td>{{ user.email }}</td>
+        </tr>
+      </tbody>
+    </table>
+    
+    <!-- Pagination -->
+    <button 
+      :disabled="pagination?.meta.current_page === 1"
+      @click="handlePageChange(pagination.meta.current_page - 1)"
+    >
+      Previous
+    </button>
+    <span>Page {{ pagination?.meta.current_page }} of {{ pagination?.meta.last_page }}</span>
+    <button 
+      :disabled="pagination?.meta.current_page === pagination?.meta.last_page"
+      @click="handlePageChange(pagination.meta.current_page + 1)"
+    >
+      Next
+    </button>
+  </div>
+</template>
+```
+
+### With TanStack Table
+
+```vue
+<script setup lang="ts">
+import { usePagination } from '@toniel/laravel-tanstack-pagination'
+import { createColumnHelper, FlexRender, getCoreRowModel, useVueTable } from '@tanstack/vue-table'
+
+const columnHelper = createColumnHelper<User>()
+
+const {
+  tableData,
+  pagination,
+  perPage,
+  getNumberingColumn,
+  // ... other returns
+} = usePagination(fetchUsers, { queryKey: 'users' })
+
+const columns = [
+  getNumberingColumn({ header: '#' }),
+  columnHelper.accessor('name', { header: 'Name' }),
+  columnHelper.accessor('email', { header: 'Email' }),
+]
+
+const table = useVueTable({
+  get data() { return tableData.value },
+  columns,
+  getCoreRowModel: getCoreRowModel(),
+})
+</script>
+```
+
+### With Shadcn-vue or Radix-vue
+
+For ready-to-use DataTable component with shadcn-vue styling, use:
+
+```bash
+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:
+
+```php
+// UserController.php
+public function index(Request $request)
+{
+    $query = User::query();
+    
+    // Search
+    if ($request->has('search')) {
+        $query->where('name', 'like', "%{$request->search}%")
+              ->orWhere('email', 'like', "%{$request->search}%");
+    }
+    
+    // Sorting (format: sort[column]=direction)
+    foreach ($request->all() as $key => $value) {
+        if (str_starts_with($key, 'sort[')) {
+            preg_match('/sort\[(.*?)\]/', $key, $matches);
+            $column = $matches[1] ?? null;
+            if ($column) {
+                $query->orderBy($column, $value);
+            }
+        }
+    }
+    
+    // Paginate
+    $perPage = $request->input('per_page', 10);
+    return $query->paginate($perPage);
+}
+```
+
+The response will automatically be in the correct format:
+```json
+{
+  "data": [...],
+  "links": {...},
+  "meta": {
+    "current_page": 1,
+    "from": 1,
+    "to": 10,
+    "total": 100,
+    "per_page": 10,
+    "last_page": 10
+  }
+}
+```
+
+## 🔗 Related Packages
+
+- [`@toniel/laravel-tanstack-datatable`](https://github.com/toniel/laravel-tanstack-datatable) - Pre-built DataTable components
+- [`@tanstack/vue-query`](https://tanstack.com/query/latest/docs/vue/overview) - Data fetching & caching library
+- [`@tanstack/vue-table`](https://tanstack.com/table/latest/docs/framework/vue/vue-table) - Headless table library
+
+## 🌟 Show Your Support
+
+If this package helped you, please consider:
+- ⭐ Starring the [GitHub repository](https://github.com/toniel/laravel-tanstack-pagination)
+- 🐛 [Reporting bugs](https://github.com/toniel/laravel-tanstack-pagination/issues)
+- 💡 [Suggesting new features](https://github.com/toniel/laravel-tanstack-pagination/issues)
+- 🔧 [Contributing code](https://github.com/toniel/laravel-tanstack-pagination/pulls)
+
+## 📄 License
+
+[MIT](https://github.com/toniel/laravel-tanstack-pagination/blob/main/LICENSE) © [Toniel](https://github.com/toniel)
+
+## 🤝 Contributing
+
+Contributions, issues and feature requests are welcome!
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'Add some amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for more details.
+
+## 📮 Contact
+
+- GitHub: [@toniel](https://github.com/toniel)
+- NPM: [@toniel](https://www.npmjs.com/~toniel)
+
+## 🙏 Acknowledgments
+
+Built with these amazing libraries:
+- [Vue 3](https://vuejs.org/)
+- [TanStack Query](https://tanstack.com/query/latest)
+- [Laravel](https://laravel.com/)
+
+---
 
-## License
+<div align="center">
+  Made with ❤️ by <a href="https://github.com/toniel">Toniel</a>
+</div>
 
-MIT

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.0",
+  "version": "0.1.2",
   "description": "Vue 3 composables for Laravel pagination with TanStack Query",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -26,10 +26,22 @@
     "laravel",
     "pagination",
     "composable",
-    "tanstack-query"
+    "tanstack-query",
+    "headless",
+    "typescript",
+    "vue-composables",
+    "laravel-api"
   ],
-  "author": "Your Name",
+  "author": "Toniel <toniel@example.com>",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/toniel/laravel-tanstack-pagination.git"
+  },
+  "homepage": "https://github.com/toniel/laravel-tanstack-pagination#readme",
+  "bugs": {
+    "url": "https://github.com/toniel/laravel-tanstack-pagination/issues"
+  },
   "peerDependencies": {
     "vue": "^3.0.0",
     "@tanstack/vue-query": "^5.0.0"