Implement search, status, and page state through Next.js URL parameters.

• Read useSearchParams() as immutable and clone it before updates.
• Parse unknown input defensively: unsupported status becomes all; invalid, fractional, zero, or negative page becomes 1.
• Omit status=all, blank q, and page=1 from the canonical URL.
• Preserve unrelated supported parameters already present in the query string.
• Reset page whenever search or status changes, but preserve filters during pagination.
• Use history intentionally: committed filter and page changes should be recoverable with Back; do not push on every keystroke.
• Local input state may exist as an editing draft, but it must resynchronize when URL state changes.

1. Parse the read-only URL parameters into validated domain values.
2. Keep only the search field as temporary draft state so typing does not navigate on every character; synchronize that draft whenever q changes through Back, Forward, or external navigation.
3. Centralize URL writes in one helper that clones the current parameters and omits defaults.
4. On committed search or status changes, delete page before navigating.
5. On pagination, preserve the existing filter parameters and omit page one.
6. Use router.push for committed user choices so history represents meaningful views. Reserve replace for silent canonicalization or debounced drafts if the product chooses them.
7. Test deep links and history traversal in addition to helper output.

"use client";

import { FormEvent, useEffect, useState } from "react";
import { usePathname, useRouter, useSearchParams } from "next/navigation";

type Status = "all" | "active" | "paused";

function parseStatus(value: string | null): Status {
  return value === "active" || value === "paused" ? value : "all";
}

function parsePage(value: string | null): number {
  if (value === null || !/^\d+$/.test(value)) return 1;
  const page = Number(value);
  return Number.isSafeInteger(page) && page > 0 ? page : 1;
}

export function DrillFilters() {
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();

  const query = searchParams.get("q")?.trim() ?? "";
  const status = parseStatus(searchParams.get("status"));
  const page = parsePage(searchParams.get("page"));
  const [queryDraft, setQueryDraft] = useState(query);

  useEffect(() => {
    setQueryDraft(query);
  }, [query]);

  function navigate(mutator: (params: URLSearchParams) => void) {
    const params = new URLSearchParams(searchParams.toString());
    mutator(params);
    const next = params.toString();
    router.push(next ? `${pathname}?${next}` : pathname, { scroll: false });
  }

  function submitSearch(event: FormEvent<HTMLFormElement>) {
    event.preventDefault();
    const nextQuery = queryDraft.trim();
    navigate((params) => {
      nextQuery ? params.set("q", nextQuery) : params.delete("q");
      params.delete("page");
    });
  }

  function changeStatus(nextStatus: Status) {
    navigate((params) => {
      nextStatus === "all"
        ? params.delete("status")
        : params.set("status", nextStatus);
      params.delete("page");
    });
  }

  function changePage(nextPage: number) {
    if (!Number.isSafeInteger(nextPage) || nextPage < 1) return;
    navigate((params) => {
      nextPage === 1
        ? params.delete("page")
        : params.set("page", String(nextPage));
    });
  }

  return (
    <section aria-label="Drill filters">
      <form onSubmit={submitSearch}>
        <label htmlFor="drill-search">Search</label>
        <input
          id="drill-search"
          type="search"
          value={queryDraft}
          onChange={(event) => setQueryDraft(event.target.value)}
        />
        <button type="submit">Apply search</button>
      </form>

      <label htmlFor="drill-status">Status</label>
      <select
        id="drill-status"
        value={status}
        onChange={(event) => changeStatus(event.target.value as Status)}
      >
        <option value="all">Any status</option>
        <option value="active">Active</option>
        <option value="paused">Paused</option>
      </select>

      <nav aria-label="Pagination">
        <button disabled={page === 1} onClick={() => changePage(page - 1)}>
          Previous
        </button>
        <span>Page {page}</span>
        <button onClick={() => changePage(page + 1)}>Next</button>
      </nav>
    </section>
  );
}

The page or server component can consume the same validated parameters to fetch data. Keeping parsing rules shared prevents the controls and the server query from disagreeing about what a URL means.

Parsing and updating a short query string is O(p) for p parameters, which is negligible here. The main trade-off is behavioral: URL state makes views shareable, reload-safe, observable, and compatible with history, but every committed change becomes navigation and may trigger server work. A submit-based search avoids noisy history. A debounced search can use replace for intermediate edits and push for explicit commits, but that policy must be clear. Parsing should ideally be shared with the server-side data loader so invalid values cannot produce two interpretations.

• Missing, blank, repeated, or unsupported query parameters.
• page=0, page=-2, page=1.5, an enormous unsafe integer, or nonnumeric input.
• Search terms with spaces, Unicode, &, or ?, which must round-trip through URLSearchParams encoding.
• Changing a filter while on a page that does not exist in the new result set.
• Back/Forward changes the URL while the search field contains an unsubmitted draft.
• The pathname changes while this control remains mounted.
• Another supported parameter, such as sort order, must survive a filter update.
• A static route using useSearchParams may need an appropriate Suspense boundary in the surrounding Next.js tree.

• Initialize from a deep URL and assert search, status, and page controls match it.
• Submit a changed search from page three and verify page disappears while status and unrelated parameters survive.
• Select all and navigate to page one; verify both defaults are omitted.
• Feed invalid status and page values and verify the domain values safely fall back.
• Simulate Back/Forward by rerendering with changed search params and verify the search draft resynchronizes.
• Use search text containing Unicode and reserved characters and assert it round-trips correctly.
• Verify typing alone does not navigate and one committed submit creates one meaningful history entry.

• Back changes the URL but not the controls: durable URL state was copied into local state without synchronization.
• Filtering leaves the user on an empty high page: page was not reset when the result set changed.
• Unrelated filters disappear: updates built a new query string instead of cloning the current one.
• The URL accumulates defaults: all, blank search, and page one were written instead of deleted.
• Every keystroke pollutes history: push was tied directly to input changes rather than a committed or carefully debounced action.
• Invalid pages reach the API: parsing checked Number(...) but not positivity, integer form, and safe range.
• Client and server show different results: they use different parsing and defaulting rules.