@mits_pl/use-inertia-filters 1.0.0

package/README.md

@@ -0,0 +1,217 @@
+# @mits/use-inertia-filters
+
+> Headless Vue 3 composable for managing filter state with Inertia.js — debounced, URL-synced, TypeScript-first.
+
+[![npm version](https://img.shields.io/npm/v/@mits/use-inertia-filters.svg)](https://www.npmjs.com/package/@mits/use-inertia-filters)
+[![license](https://img.shields.io/npm/l/@mits/use-inertia-filters.svg)](./LICENSE)
+
+Built and maintained by [MITS](https://mits.pl) — a software house specializing in Laravel + Vue + Inertia.
+
+---
+
+## The problem
+
+Every Laravel + Inertia app has the same boilerplate: a list page with a search input, a status dropdown, a per-page selector. Every time you need to:
+
+1. Keep filter state in sync with the URL query string
+2. Debounce the search input so you don't hammer the server
+3. Fire immediately for sort/per_page changes
+4. Preserve Vue component state so the page doesn't flicker
+5. Reset filters back to defaults
+
+This composable does all of that in **one line**.
+
+---
+
+## Installation
+
+```bash
+npm install @mits/use-inertia-filters
+# or
+yarn add @mits/use-inertia-filters
+# or
+pnpm add @mits/use-inertia-filters
+```
+
+**Peer dependencies:** `vue >= 3.3`, `@inertiajs/vue3 >= 1.0`
+
+---
+
+## Quick start
+
+```vue
+<script setup lang="ts">
+import { useInertiaFilters } from '@mits/use-inertia-filters'
+
+const { filters, reset, isDirty } = useInertiaFilters({
+  search: '',
+  status: null,
+  perPage: 15,
+})
+</script>
+
+<template>
+  <div>
+    <input v-model="filters.search" placeholder="Search..." />
+
+    <select v-model="filters.status">
+      <option :value="null">All</option>
+      <option value="active">Active</option>
+      <option value="inactive">Inactive</option>
+    </select>
+
+    <select v-model="filters.perPage">
+      <option :value="15">15</option>
+      <option :value="25">25</option>
+      <option :value="50">50</option>
+    </select>
+
+    <button v-if="isDirty()" @click="reset">Clear filters</button>
+  </div>
+</template>
+```
+
+That's it. Changes are debounced (300ms by default), the URL is updated, and the page re-renders with fresh data from the server.
+
+---
+
+## How it works
+
+1. On mount, the composable reads the current URL query string and hydrates the filter state (with type casting based on initial values).
+2. When any filter changes, a debounced `router.get()` is called with only the non-default, non-empty values in the query string — keeping the URL clean.
+3. The visit uses `preserveState: true` and `replace: true` by default, so the page updates without a flicker and without polluting browser history.
+
+---
+
+## API
+
+### `useInertiaFilters(initialFilters, options?)`
+
+#### `initialFilters`
+
+A plain object defining your filter keys and their default values. Types are inferred from the initial values and used for URL hydration casting.
+
+```ts
+useInertiaFilters({
+  search: '',      // string
+  status: null,    // null | string
+  page: 1,         // number — cast from URL string automatically
+  archived: false, // boolean — cast from URL string automatically
+})
+```
+
+#### `options`
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `debounce` | `number` | `300` | Debounce delay in ms |
+| `preserveState` | `boolean` | `true` | Preserve Vue component state |
+| `preserveScroll` | `boolean` | `true` | Preserve scroll position |
+| `replace` | `boolean` | `true` | Replace history entry (no back-button spam) |
+| `debounceOnly` | `string[]` | `undefined` | Only debounce these keys; all others fire immediately |
+| `onBeforeVisit` | `(filters) => boolean \| void` | — | Return `false` to cancel the visit |
+| `onAfterVisit` | `(filters) => void` | — | Called after each visit |
+
+#### Return value
+
+| Property | Type | Description |
+|---|---|---|
+| `filters` | `Reactive<T>` | Reactive filters object — bind with `v-model` |
+| `reset()` | `() => void` | Reset all filters to initial values |
+| `resetKeys(...keys)` | `(...keys) => void` | Reset specific keys only |
+| `flush()` | `() => void` | Trigger visit immediately, bypassing debounce |
+| `isDirty()` | `() => boolean` | True if any filter differs from its initial value |
+| `isKeyDirty(key)` | `(key) => boolean` | True if the specific key differs from initial |
+
+---
+
+## Real-world example with `debounceOnly`
+
+You want the `search` field to be debounced (wait for the user to stop typing), but `perPage` and `sort` should fire instantly.
+
+```vue
+<script setup lang="ts">
+import { useInertiaFilters } from '@mits/use-inertia-filters'
+
+const { filters, reset, isDirty } = useInertiaFilters(
+  {
+    search: '',
+    status: null,
+    sort: 'name',
+    direction: 'asc',
+    perPage: 15,
+  },
+  {
+    debounce: 400,
+    debounceOnly: ['search'], // only search is debounced
+  },
+)
+</script>
+```
+
+---
+
+## Laravel controller
+
+Nothing special needed on the backend — standard Inertia pattern:
+
+```php
+public function index(Request $request): Response
+{
+    $users = User::query()
+        ->when($request->search, fn ($q, $v) => $q->where('name', 'like', "%{$v}%"))
+        ->when($request->status, fn ($q, $v) => $q->where('status', $v))
+        ->orderBy($request->sort ?? 'name', $request->direction ?? 'asc')
+        ->paginate($request->perPage ?? 15)
+        ->withQueryString();
+
+    return Inertia::render('Users/Index', [
+        'users' => $users,
+        'filters' => $request->only('search', 'status', 'sort', 'direction', 'perPage'),
+    ]);
+}
+```
+
+---
+
+## Why not use an existing table package?
+
+Packages like `inertiajs-tables-laravel-query-builder` are great but opinionated:
+
+- Require **Spatie Laravel Query Builder** on the backend
+- Require **Tailwind CSS Forms plugin**
+- Bring their own table UI components
+
+`useInertiaFilters` is **headless**. No UI, no backend requirements, no CSS. Use it with any component library — shadcn-vue, PrimeVue, Vuetify, Quasar, or plain HTML.
+
+---
+
+## TypeScript
+
+Full type inference out of the box:
+
+```ts
+const { filters, isKeyDirty } = useInertiaFilters({
+  search: '',
+  perPage: 15,
+})
+
+filters.search  // string ✓
+filters.perPage // number ✓
+filters.nope    // TS error ✓
+
+isKeyDirty('search')  // ✓
+isKeyDirty('nope')    // TS error ✓
+```
+
+---
+
+## Contributing
+
+Issues and PRs welcome at [github.com/mits-software/use-inertia-filters](https://github.com/mits-software/use-inertia-filters).
+
+---
+
+## License
+
+MIT © [MITS Sp. z o.o.](https://mits.pl)

package/dist/index.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const l=require("vue"),g=require("@inertiajs/vue3");function k(n,t){if(n===null)return t??null;if(typeof t=="number"){const o=Number(n);return isNaN(o)?t:o}return typeof t=="boolean"?n==="true":n}function P(n){if(typeof window>"u")return{...n};const t=new URLSearchParams(window.location.search),o={...n};for(const r in n)t.has(r)&&(o[r]=k(t.get(r),n[r]));return o}function M(n,t){const o={};for(const r in n){const s=n[r],a=t[r];!(s==null||s==="")&&!(s===a)&&(o[r]=s)}return o}function N(n,t={}){const{debounce:o=300,preserveState:r=!0,preserveScroll:s=!0,replace:a=!0,debounceOnly:d,onBeforeVisit:m,onAfterVisit:y}=t,c={...n},f=l.reactive(P(n));function p(){if(typeof window>"u")return;const e=l.toRaw(f),i=M(e,c);m&&m(e)===!1||g.router.get(window.location.pathname,i,{preserveState:r,preserveScroll:s,replace:a,onSuccess:()=>y==null?void 0:y(e)})}let u=null;function h(e){u&&clearTimeout(u),(d?d.includes(e):!0)&&o>0?u=setTimeout(p,o):p()}let b=!1;l.onMounted(()=>{b=!0}),l.onUnmounted(()=>{u&&(clearTimeout(u),u=null)});for(const e in n)l.watch(()=>f[e],()=>{b&&h(e)});function w(){for(const e in c)f[e]=c[e]}function v(...e){for(const i of e)f[i]=c[i]}function D(){u&&(clearTimeout(u),u=null),p()}function S(){return Object.keys(c).some(e=>f[e]!==c[e])}function T(e){return f[e]!==c[e]}return{filters:f,reset:w,resetKeys:v,flush:D,isDirty:S,isKeyDirty:T}}exports.useInertiaFilters=N;

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { useInertiaFilters, type FilterValue, type FilterState, type UseInertiaFiltersOptions, type UseInertiaFiltersReturn, } from './useInertiaFilters';

package/dist/index.js

@@ -0,0 +1,97 @@
+import { reactive as S, onMounted as v, onUnmounted as N, watch as P, toRaw as U } from "vue";
+import { router as g } from "@inertiajs/vue3";
+function C(n, t) {
+  if (n === null) return t ?? null;
+  if (typeof t == "number") {
+    const o = Number(n);
+    return isNaN(o) ? t : o;
+  }
+  return typeof t == "boolean" ? n === "true" : n;
+}
+function E(n) {
+  if (typeof window > "u") return { ...n };
+  const t = new URLSearchParams(window.location.search), o = { ...n };
+  for (const r in n)
+    t.has(r) && (o[r] = C(t.get(r), n[r]));
+  return o;
+}
+function K(n, t) {
+  const o = {};
+  for (const r in n) {
+    const s = n[r], l = t[r];
+    !(s == null || s === "") && !(s === l) && (o[r] = s);
+  }
+  return o;
+}
+function j(n, t = {}) {
+  const {
+    debounce: o = 300,
+    preserveState: r = !0,
+    preserveScroll: s = !0,
+    replace: l = !0,
+    debounceOnly: a,
+    onBeforeVisit: d,
+    onAfterVisit: m
+  } = t, c = { ...n }, f = S(E(n));
+  function y() {
+    if (typeof window > "u") return;
+    const e = U(f), i = K(e, c);
+    d && d(e) === !1 || g.get(
+      window.location.pathname,
+      i,
+      {
+        preserveState: r,
+        preserveScroll: s,
+        replace: l,
+        onSuccess: () => m == null ? void 0 : m(e)
+      }
+    );
+  }
+  let u = null;
+  function h(e) {
+    u && clearTimeout(u), (a ? a.includes(e) : !0) && o > 0 ? u = setTimeout(y, o) : y();
+  }
+  let p = !1;
+  v(() => {
+    p = !0;
+  }), N(() => {
+    u && (clearTimeout(u), u = null);
+  });
+  for (const e in n)
+    P(
+      () => f[e],
+      () => {
+        p && h(e);
+      }
+    );
+  function w() {
+    for (const e in c)
+      f[e] = c[e];
+  }
+  function b(...e) {
+    for (const i of e)
+      f[i] = c[i];
+  }
+  function D() {
+    u && (clearTimeout(u), u = null), y();
+  }
+  function T() {
+    return Object.keys(c).some(
+      (e) => f[e] !== c[e]
+    );
+  }
+  function k(e) {
+    return f[e] !== c[e];
+  }
+  return {
+    filters: f,
+    reset: w,
+    resetKeys: b,
+    flush: D,
+    isDirty: T,
+    isKeyDirty: k
+  };
+}
+export {
+  j as useInertiaFilters
+};

package/dist/useInertiaFilters.d.ts

@@ -0,0 +1,52 @@
+export type FilterValue = string | number | boolean | null | undefined;
+export type FilterState = Record<string, FilterValue>;
+export interface UseInertiaFiltersOptions {
+    /**
+     * Debounce delay in ms before triggering a router visit.
+     * Useful for text search inputs. Default: 300
+     */
+    debounce?: number;
+    /**
+     * Whether to preserve Vue component state across navigations.
+     * Default: true
+     */
+    preserveState?: boolean;
+    /**
+     * Whether to preserve scroll position across navigations.
+     * Default: true
+     */
+    preserveScroll?: boolean;
+    /**
+     * Replace current history entry instead of pushing a new one.
+     * Default: true
+     */
+    replace?: boolean;
+    /**
+     * Only watch these keys for debounce. Other keys trigger immediately.
+     * Useful when you want instant sort/per_page but debounced search.
+     */
+    debounceOnly?: string[];
+    /**
+     * Called before each router visit. Return false to cancel.
+     */
+    onBeforeVisit?: (filters: FilterState) => boolean | void;
+    /**
+     * Called after each successful router visit.
+     */
+    onAfterVisit?: (filters: FilterState) => void;
+}
+export interface UseInertiaFiltersReturn<T extends FilterState> {
+    /** Reactive filters object — bind directly with v-model */
+    filters: T;
+    /** Reset all filters to their initial values */
+    reset: () => void;
+    /** Reset specific keys to their initial values */
+    resetKeys: (...keys: (keyof T)[]) => void;
+    /** Trigger a visit immediately, bypassing debounce */
+    flush: () => void;
+    /** Check whether any filter differs from its initial value */
+    isDirty: () => boolean;
+    /** Check whether a specific key differs from its initial value */
+    isKeyDirty: (key: keyof T) => boolean;
+}
+export declare function useInertiaFilters<T extends FilterState>(initialFilters: T, options?: UseInertiaFiltersOptions): UseInertiaFiltersReturn<T>;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@mits_pl/use-inertia-filters",
+  "version": "1.0.0",
+  "description": "Headless Vue 3 composable for managing filter state with Inertia.js — debounced, URL-synced, TypeScript-first.",
+  "keywords": [
+    "inertia",
+    "inertiajs",
+    "vue",
+    "vue3",
+    "composable",
+    "filters",
+    "laravel",
+    "typescript"
+  ],
+  "homepage": "https://mits.pl",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mits-software/use-inertia-filters"
+  },
+  "author": "MITS Sp. z o.o. <hello@mits.pl> (https://mits.pl)",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "vite build && tsc --emitDeclarationOnly --declaration --declarationDir dist",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@inertiajs/vue3": ">=1.0.0",
+    "vue": ">=3.3.0"
+  },
+  "devDependencies": {
+    "@inertiajs/vue3": "^2.0.0",
+    "@vitejs/plugin-vue": "^5.0.0",
+    "jsdom": "^28.1.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.0.0",
+    "vitest": "^1.0.0",
+    "vue": "^3.4.0"
+  }
+}