state-in-url 6.1.3 → 6.2.1

package/skills/input-handling/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: input-handling
+description: >
+  Reconcile instant local input feedback with URL write throttling. setState
+  updates internal state synchronously (instant re-render); setUrl is throttled
+  and asynchronous (URL catches up on the next tick). Use this skill for text
+  inputs, search boxes, sliders, range pickers, and any control that fires
+  many updates per second where binding setUrl directly to onChange causes
+  perceived lag or wasted URL writes.
+type: core
+library: state-in-url
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/useUrlStateBase/useUrlStateBase.ts'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/utils.ts'
+  - 'asmyshlyaev177/state-in-url:README.md#update-state-only-and-sync-to-url-manually'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — Input handling
+
+`useUrlState` returns three setters with different timing:
+
+| Setter | What updates | When |
+|---|---|---|
+| `setState(value)` | Internal state only | Synchronous |
+| `setUrl(value)` | Internal state + URL | State sync, URL on next tick (throttled) |
+| `setUrl()` | Flush current state to URL | URL on next tick (diff-checked, no-op if equal) |
+
+State updates always render immediately. URL writes are coalesced through an internal global timer (`TIMEOUT` constant in [useUrlStateBase.ts](https://github.com/asmyshlyaev177/state-in-url/blob/master/packages/urlstate/useUrlStateBase/useUrlStateBase.ts)) so a burst of `setUrl` calls produces one URL update.
+
+## Setup
+
+```typescript
+// features/search/searchState.ts
+export type SearchState = { q: string; sort: 'name' | 'date' };
+export const SEARCH_STATE: SearchState = { q: '', sort: 'name' };
+```
+
+```typescript
+// features/search/useSearchState.ts
+'use client';
+import { useSearchParams } from 'next/navigation';
+import { useUrlState } from 'state-in-url/next';
+import { SEARCH_STATE } from './searchState';
+
+export function useSearchState() {
+  const searchParams = useSearchParams();
+  return useUrlState(SEARCH_STATE, { searchParams });
+}
+```
+
+## Core Patterns
+
+### Instant input, deferred URL write (onBlur)
+
+```typescript
+function SearchBox() {
+  const { urlState, setState, setUrl } = useSearchState();
+
+  return (
+    <input
+      value={urlState.q}
+      onChange={(e) => setState({ q: e.target.value })}
+      onBlur={() => setUrl()}
+    />
+  );
+}
+```
+
+`setState` updates state instantly (input feels native). `setUrl()` with no args flushes current state to the URL when the user finishes typing.
+
+### Discrete controls — `setUrl` directly
+
+For click/select/toggle controls that fire at most a few times per second, skip the split. `setUrl` is already throttled.
+
+```typescript
+<button onClick={() => setUrl({ sort: 'date' })}>Sort by date</button>
+```
+
+## Common Mistakes
+
+### CRITICAL `setUrl` inside `useEffect` → infinite update loop
+
+(Cross-skill failure — also in `feature-state-hook`.)
+
+Wrong:
+
+```typescript
+React.useEffect(() => {
+  setUrl({ q: urlState.q.trim() }); // re-fires every URL change
+}, [urlState, setUrl]);
+```
+
+Correct:
+
+```typescript
+React.useEffect(() => {
+  const trimmed = urlState.q.trim();
+  if (urlState.q !== trimmed) setUrl({ q: trimmed });
+}, [urlState.q, setUrl]);
+```
+
+URL throttling does not break a state→effect→setUrl→state cycle.
+
+Source: Maintainer interview
+
+### HIGH Binding `setUrl` directly to onChange of a typing input
+
+Wrong:
+
+```typescript
+<input
+  value={urlState.q}
+  onChange={(e) => setUrl({ q: e.target.value })}
+/>
+```
+
+Correct:
+
+```typescript
+<input
+  value={urlState.q}
+  onChange={(e) => setState({ q: e.target.value })}
+  onBlur={() => setUrl()}
+/>
+```
+
+Every keystroke fires a URL update. The library coalesces them with an internal timer, but the perceived behavior is laggy URL with extra rerenders (one for state, another when URL settles). Issue #78 was filed exactly for this symptom — the throttling is intentional.
+
+Source: GitHub issue #78 (asmyshlyaev177/state-in-url); README "Update state only and sync to URL manually"
+
+### MEDIUM Expecting `window.location.search` to reflect `setUrl` synchronously
+
+Wrong:
+
+```typescript
+setUrl({ tab: 'b' });
+console.log(window.location.search); // still the old value
+```
+
+Correct:
+
+```typescript
+setUrl({ tab: 'b' });
+// `urlState.tab` already equals 'b' synchronously.
+// `window.location.search` catches up after the throttle tick.
+```
+
+`setUrl` is "last-write-wins" — it coalesces a burst of updates into one URL write on the next macrotask. Read `urlState`, not `window.location`.
+
+Source: useUrlStateBase.ts (global `timer`); GitHub issue #78
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern this skill builds on.
+- `state-in-url/nextjs-ssr` — for SSR-safe wiring of the search input on Next.js App Router.

package/skills/nextjs-ssr/SKILL.md

@@ -0,0 +1,251 @@
+---
+name: nextjs-ssr
+description: >
+  SSR-safe useUrlState in Next.js App Router. Forward searchParams from server
+  pages (awaiting the Promise in Next.js 15+), call useSearchParams() in pure
+  client components, decide between useHistory true/false, and use a Proxy
+  (formerly middleware) to expose query params to server layouts. App Router
+  only — Pages Router is not supported. Load this skill for any use of
+  state-in-url/next or anytime URL state must be correct on first paint.
+type: framework
+library: state-in-url
+framework: react
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/next/useUrlState/useUrlState.ts'
+  - 'asmyshlyaev177/state-in-url:packages/example-nextjs16/src/middleware.ts'
+  - 'asmyshlyaev177/state-in-url:README.md#with-server-side-rendering'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — Next.js App Router SSR
+
+Without `searchParams`, the first render of a `useUrlState` component has no URL knowledge. It renders defaults, then a client `useEffect` re-syncs from the URL → visible flash and a React hydration warning. The fix is to feed the URL into the hook on the server (via `searchParams` prop or a Proxy header) so the very first render is correct.
+
+App Router only. Pages Router uses `next/router`, which `state-in-url/next` does not support — there are no plans to add it.
+
+## Setup
+
+### Server page forwarding `searchParams` (recommended)
+
+```typescript
+// app/jobs/page.tsx  (Server Component)
+import { JobsList } from './JobsList';
+
+export default async function Page({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}) {
+  const sp = await searchParams; // Next.js 15+: searchParams is a Promise
+  return <JobsList searchParams={sp} />;
+}
+```
+
+```typescript
+// app/jobs/JobsList.tsx
+'use client';
+import { useUrlState } from 'state-in-url/next';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+
+export function JobsList({ searchParams }: { searchParams: object }) {
+  const { urlState, setUrl } = useUrlState(JOBS_STATE, { searchParams });
+  return <pre>{JSON.stringify(urlState)}</pre>;
+}
+```
+
+### Pure client component using `useSearchParams`
+
+When you can't (or don't want to) thread `searchParams` from a server parent:
+
+```typescript
+'use client';
+import { useSearchParams } from 'next/navigation';
+import { useUrlState } from 'state-in-url/next';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+
+export function useJobsState() {
+  const searchParams = useSearchParams();
+  return useUrlState(JOBS_STATE, { searchParams });
+}
+```
+
+## Core Patterns
+
+### `useHistory` — choosing the URL update mode
+
+| Setting | Mechanism | Effect | Use when |
+|---|---|---|---|
+| `useHistory: true` (default) | `window.history.pushState` / `replaceState` | No `_rsc` round-trip per URL change | URL state is client-only UI (filters, drawers, tabs) |
+| `useHistory: false` | `next/navigation`'s `router.push` / `router.replace` | RSC refetches on every URL change | URL state must refetch server data (e.g. `searchParams` drives a DB query in the page) |
+
+```typescript
+useUrlState(FORM_STATE, { searchParams, useHistory: false });
+```
+
+Default is `true`. Flip to `false` only when the server page needs to re-render with the new query.
+
+### Decoding state on the server for data fetching
+
+```typescript
+// app/jobs/page.tsx
+import { decodeState } from 'state-in-url/encodeState';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+import { fetchJobs } from 'lib/jobs';
+
+export default async function Page({ searchParams }) {
+  const sp = await searchParams;
+  const state = decodeState(new URLSearchParams(sp as Record<string, string>), JOBS_STATE);
+  const jobs = await fetchJobs({ status: state.status });
+  return <JobsList searchParams={sp} jobs={jobs} />;
+}
+```
+
+### Reading URL state in a server layout (Proxy workaround)
+
+Server layouts don't receive `searchParams`. Set up a Proxy (Next.js 16+ — `middleware.ts` still works as a deprecated alias) to surface the query string as a request header, then decode in the layout. With this setup the layout renders correctly on first paint with no extra rerenders.
+
+```typescript
+// proxy.ts  (or middleware.ts, same content)
+import type { NextRequest } from 'next/server';
+import { NextResponse } from 'next/server';
+
+export function proxy(request: NextRequest) {
+  const sp = (request.url.includes('_next') ? '' : request.url).split('?')[1] ?? '';
+  const headers = new Headers(request.headers);
+  headers.set('searchParams', sp);
+  return NextResponse.next({ request: { headers } });
+}
+```
+
+```typescript
+// app/jobs/layout.tsx
+import { headers } from 'next/headers';
+import { decodeState } from 'state-in-url/encodeState';
+import { JOBS_STATE } from 'features/jobs/jobsState';
+
+export default async function Layout({ children }: { children: React.ReactNode }) {
+  const sp = (await headers()).get('searchParams') ?? '';
+  const initial = decodeState(sp, JOBS_STATE);
+
+  return (
+    <>
+      <LayoutHeader initial={initial} />
+      {children}
+    </>
+  );
+}
+```
+
+## Common Mistakes
+
+### CRITICAL Not passing `searchParams` in Next.js App Router
+
+Wrong:
+
+```typescript
+// page.tsx (server)
+export default function Page() { return <Form />; }
+
+// Form.tsx (client)
+const { urlState } = useUrlState(FORM_STATE);  // missing searchParams
+```
+
+Correct:
+
+```typescript
+// page.tsx
+export default async function Page({ searchParams }) {
+  const sp = await searchParams;
+  return <Form searchParams={sp} />;
+}
+
+// Form.tsx
+const { urlState } = useUrlState(FORM_STATE, { searchParams });
+```
+
+`searchParams` makes the **initial** state correct. Without it, the first render uses defaults, then a client `useEffect` re-syncs from the URL on the next tick — causing a visible flash and a hydration warning. URL state still survives refresh either way (URL is the source of truth), but the initial paint is wrong. With a Proxy feeding the layout, no extra rerender happens at all. Most common Next.js issue (#40, #60).
+
+Source: GitHub issues #40, #60 (asmyshlyaev177/state-in-url); maintainer interview
+
+### HIGH Forgetting to await `searchParams` in Next.js 15+
+
+Wrong:
+
+```typescript
+export default function Page({ searchParams }) {
+  return <Form searchParams={searchParams} />; // Promise, not the value
+}
+```
+
+Correct:
+
+```typescript
+export default async function Page({ searchParams }) {
+  const sp = await searchParams;
+  return <Form searchParams={sp} />;
+}
+```
+
+Next.js 15 changed page-level `searchParams` to a Promise. The library silently decodes nothing from an unresolved Promise.
+
+Source: Next.js 15 migration notes
+
+### HIGH Using `state-in-url/next` in a Pages Router project
+
+Wrong:
+
+```typescript
+// pages/index.tsx
+import { useUrlState } from 'state-in-url/next'; // imports next/navigation
+```
+
+Correct:
+
+Use App Router (`app/` directory). The library does not support Pages Router and there are no plans to add support. If you must stay on Pages Router, build a custom hook with `useUrlStateBase` and a `next/router`-backed router object.
+
+Source: README "Gotchas" #3
+
+### MEDIUM Setting `useHistory: false` unnecessarily
+
+Wrong:
+
+```typescript
+useUrlState(FORM_STATE, { searchParams, useHistory: false });
+// every keystroke triggers a Next.js _rsc payload fetch
+```
+
+Correct:
+
+```typescript
+useUrlState(FORM_STATE, { searchParams });
+// useHistory defaults to true → window.history, no server round-trip
+```
+
+`useHistory: false` is only correct when the server page must re-fetch on URL changes. For UI-only state (filters, drawers, tabs) it triples request traffic.
+
+Source: JSDoc on `useUrlState` params; vercel/next.js#59167
+
+### MEDIUM Trying to read `searchParams` in a server layout directly
+
+Wrong:
+
+```typescript
+export default function Layout({ children, searchParams }: any) {
+  // searchParams is always undefined in layouts
+}
+```
+
+Correct:
+
+Use the Proxy + header pattern shown above (`proxy.ts` setting `searchParams` header → layout reads via `headers()` and `decodeState`). With this in place there is no initial lag or extra rerender.
+
+Source: README "Using hook in layout component"; packages/example-nextjs16/src/middleware.ts; maintainer interview
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern; required reading.
+- `state-in-url/input-handling` — for text-input UX with the Next.js hook.

package/skills/react-router-remix-setup/SKILL.md

@@ -0,0 +1,180 @@
+---
+name: react-router-remix-setup
+description: >
+  Set up useUrlState for React Router v7 (state-in-url/react-router), React
+  Router v6 (state-in-url/react-router6 — moved here in 6.0.0), and Remix v2
+  (state-in-url/remix). The hook API is identical across all three; only the
+  import path and per-call NavigateOptions (preventScrollReset, state, replace)
+  differ. Load this skill when wiring useUrlState into any non-Next.js
+  React router or migrating from an older import path.
+type: framework
+library: state-in-url
+framework: react
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/react-router/useUrlState/'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/react-router6/useUrlState/'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/remix/useUrlState/'
+  - 'asmyshlyaev177/state-in-url:CHANGELOG.md#600-2025-08-05'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — React Router and Remix
+
+The hook signature, return shape, and behavior of `useUrlState` are identical across React Router v6, v7, and Remix v2. Three things differ:
+
+| Aspect | Difference |
+|---|---|
+| Import path | `state-in-url/react-router` (v7), `state-in-url/react-router6` (v6), `state-in-url/remix` (Remix v2) |
+| `setUrl` per-call options | Accepts `NavigateOptions` from `react-router` (e.g. `preventScrollReset`, `state`, `replace`) |
+| SSR | Remix v2 routes can hydrate from loader data; React Router CSR-only by default |
+
+## Setup
+
+### React Router v7
+
+```typescript
+import { useUrlState } from 'state-in-url/react-router';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE);
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
+}
+```
+
+### React Router v6 (since state-in-url 6.0.0)
+
+```typescript
+// Note the /react-router6 subpath
+import { useUrlState } from 'state-in-url/react-router6';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export function FiltersBar() {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE);
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
+}
+```
+
+### Remix v2
+
+```typescript
+import { useUrlState } from 'state-in-url/remix';
+
+type FiltersState = { sort: 'name' | 'date'; page: number };
+const FILTERS_STATE: FiltersState = { sort: 'name', page: 1 };
+
+export default function Route() {
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE);
+  return <button onClick={() => setUrl({ page: urlState.page + 1 })}>Next</button>;
+}
+```
+
+## Core Patterns
+
+### Pass NavigateOptions per call
+
+```typescript
+setUrl({ tab: 'b' }, { replace: false, preventScrollReset: true });
+```
+
+`replace: false` creates a new history entry (push) instead of replacing.
+`preventScrollReset: true` keeps the page scroll position after the navigation — important when URL state controls in-page UI rather than route content.
+
+### `basename` support
+
+Both `useUrlState` hooks for React Router respect the router's `basename`. No extra configuration is needed in the hook.
+
+```typescript
+// router setup
+<BrowserRouter basename="/admin">
+  <App />
+</BrowserRouter>
+// URL state updates happen at /admin?... not /...
+```
+
+### Functional update preserving other fields
+
+```typescript
+setUrl((curr) => ({ ...curr, page: curr.page + 1 }));
+```
+
+## Common Mistakes
+
+### CRITICAL Importing `/react-router` for a React Router v6 project
+
+Wrong:
+
+```typescript
+// react-router v6 project
+import { useUrlState } from 'state-in-url/react-router'; // targets v7 since 6.0.0
+```
+
+Correct:
+
+```typescript
+import { useUrlState } from 'state-in-url/react-router6';
+```
+
+As of state-in-url v6.0.0 (Aug 2025) the v6 implementation moved to its own subpath. `/react-router` now targets React Router v7 only. Agents trained on older code will use the wrong import.
+
+Source: CHANGELOG v6.0.0 BREAKING CHANGES (asmyshlyaev177/state-in-url)
+
+### HIGH Using the deprecated `useUrlState({ allParamsObj })` signature
+
+Wrong:
+
+```typescript
+useUrlState({ defaultState: FORM_STATE, replace: true }); // removed in v5.0.0
+```
+
+Correct:
+
+```typescript
+useUrlState(FORM_STATE, { replace: true });
+```
+
+state-in-url v5.0.0 removed the old object-wrapped call shape. Defaults are now passed positionally; options go in the second argument.
+
+Source: CHANGELOG v5.0.0 BREAKING CHANGES (asmyshlyaev177/state-in-url)
+
+### CRITICAL `defaultState` defined inside the React component
+
+(Cross-skill failure — also in `feature-state-hook`.)
+
+Wrong:
+
+```typescript
+export function Filters() {
+  const defaults = { sort: 'name' };
+  const { urlState } = useUrlState(defaults);
+}
+```
+
+Correct:
+
+```typescript
+type FiltersState = { sort: 'name' | 'date' };
+const FILTERS_STATE: FiltersState = { sort: 'name' };
+
+export function Filters() {
+  const { urlState } = useUrlState(FILTERS_STATE);
+}
+```
+
+Same identity rule as Next.js. A fresh default object each render breaks sharing and initial-state seeding.
+
+Source: GitHub issues #57, #60, #69 (asmyshlyaev177/state-in-url)
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern.
+- `state-in-url/input-handling` — for text-input UX inside a router-driven page.
+- `state-in-url/form-library-integration` — for pairing with `react-hook-form`.