state-in-url 6.1.2 → 6.2.0

package/skills/feature-state-hook/SKILL.md

@@ -0,0 +1,352 @@
+---
+name: feature-state-hook
+description: >
+  Define typed, module-scoped state and wrap useUrlState in a feature-scoped
+  custom hook so unrelated React components share the same URL-synced state.
+  Covers drawer/modal open-state, tab switching, multi-select toggles,
+  reset/defaults semantics, and the object-identity-based sharing model.
+  Load this skill when storing filters, tabs, drawers, selections, paginators,
+  or any UI state that should survive reloads and be shareable by URL.
+type: core
+library: state-in-url
+library_version: '6.1.3'
+sources:
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/next/useUrlState/useUrlState.ts'
+  - 'asmyshlyaev177/state-in-url:packages/urlstate/utils.ts'
+  - 'asmyshlyaev177/state-in-url:README.md'
+---
+
+# state-in-url — Feature state hook
+
+`state-in-url` stores a typed JSON-serializable object in the URL query string. State across components is shared by passing the **same module-scoped default-state object** to `useUrlState`. The library uses object identity, not deep equality, to wire up subscriptions — so the default state must be a static `const`, defined once, outside any component.
+
+## Setup
+
+```typescript
+// features/jobs/jobsState.ts
+export type JobsState = {
+  status: '' | 'active' | 'closed';
+  tab: 'details' | 'qa' | 'applicants';
+  jobId: string;
+};
+
+export const JOBS_STATE: JobsState = {
+  status: '',
+  tab: 'details',
+  jobId: '',
+};
+```
+
+```typescript
+// features/jobs/useJobsState.ts
+'use client';
+import { useSearchParams } from 'next/navigation';
+import { useUrlState } from 'state-in-url/next';
+import { JOBS_STATE } from './jobsState';
+
+export function useJobsState() {
+  const searchParams = useSearchParams();
+  return useUrlState(JOBS_STATE, { searchParams });
+}
+```
+
+```typescript
+// any component
+import { useJobsState } from 'features/jobs/useJobsState';
+
+export function JobsTabs() {
+  const { urlState, setUrl, reset } = useJobsState();
+
+  return (
+    <>
+      <button onClick={() => setUrl({ tab: 'qa' })}>Q&A</button>
+      <button onClick={reset}>Reset</button>
+    </>
+  );
+}
+```
+
+The same `useJobsState()` called in two different components reads and writes the same URL state — no Context, no Provider.
+
+## Core Patterns
+
+### Drawer / modal open-close via URL
+
+Pick an empty-string default for the ID field. Empty = closed (and the URL stays clean); non-empty = open.
+
+```typescript
+type MembersState = { memberId: string; tab: 'profile' | 'activity' };
+const MEMBERS_STATE: MembersState = { memberId: '', tab: 'profile' };
+
+const open  = (id: string) => setUrl({ memberId: id, tab: 'profile' });
+const close = ()           => setUrl({ ...MEMBERS_STATE });
+```
+
+`setUrl({ ...MEMBERS_STATE })` returns every field to default → all related URL params disappear in one call.
+
+### Multi-select toggle (functional update)
+
+```typescript
+const toggle = (id: string) =>
+  setUrl((curr) => ({
+    ...curr,
+    tags: curr.tags.includes(id)
+      ? curr.tags.filter((t) => t !== id)
+      : curr.tags.concat(id),
+  }));
+```
+
+### Reset to defaults
+
+```typescript
+<button onClick={reset}>Reset</button>
+// or, equivalently:
+<button onClick={() => setUrl((_, initial) => initial)}>Reset</button>
+```
+
+### Multiple independent state objects on one page
+
+Different default-state objects → independent stores. Choose non-overlapping top-level field names.
+
+```typescript
+type FiltersState = { search: string; sortBy: 'name' | 'date' };
+type DrawerState  = { open: boolean; view: 'profile' | 'settings' };
+
+const FILTERS_STATE: FiltersState = { search: '', sortBy: 'name' };
+const DRAWER_STATE:  DrawerState  = { open: false, view: 'profile' };
+```
+
+## Common Mistakes
+
+### CRITICAL defaultState defined inside the React component
+
+Wrong:
+
+```typescript
+function MyFeature({ initialTab }: Props) {
+  const defaults = { tab: initialTab, open: false }; // recreated every render
+  const { urlState } = useUrlState(defaults);
+}
+```
+
+Correct:
+
+```typescript
+type FeatureState = { tab: 'a' | 'b'; open: boolean };
+const FEATURE_STATE: FeatureState = { tab: 'a', open: false };
+
+function MyFeature() {
+  const { urlState } = useUrlState(FEATURE_STATE);
+}
+```
+
+The library uses object identity of the default-state argument to wire subscriptions and seed initial state. A new object on every render breaks sharing, breaks SSR hydration, and silently loses URL values on first paint. Maintainer-confirmed on issues #57, #60, #69.
+
+Source: GitHub issues #57, #60, #69 (asmyshlyaev177/state-in-url)
+
+### CRITICAL Using `interface` instead of `type` for the state shape
+
+Wrong:
+
+```typescript
+interface FeatureState { tab: string; open: boolean }
+const initial: FeatureState = { tab: 'a', open: false };
+useUrlState(initial); // TS error on JSONCompatible<T>
+```
+
+Correct:
+
+```typescript
+type FeatureState = { tab: string; open: boolean };
+const initial: FeatureState = { tab: 'a', open: false };
+useUrlState(initial);
+```
+
+The hook's generic constraint `JSONCompatible<T>` accepts `type` aliases but rejects `interface` declarations due to how TypeScript handles index signatures in mapped types. **Always** declare an explicit `type` for the state shape and annotate the default-state const with it (`const FOO_STATE: FooState = { ... }`) — don't rely on inferred types from a plain `const`, since narrowing surprises (`tab: 'a'` inferred as the literal `'a'`, not the union) lead to confusing type errors at every `setUrl` call site.
+
+Source: GitHub issue #21 (asmyshlyaev177/state-in-url)
+
+### CRITICAL `setUrl` inside `useEffect` → infinite update loop
+
+Wrong:
+
+```typescript
+React.useEffect(() => {
+  setUrl({ tab: urlState.tab.toLowerCase() }); // re-fires effect
+}, [urlState, setUrl]);
+```
+
+Correct:
+
+```typescript
+// Derive on read instead
+const tab = urlState.tab.toLowerCase();
+
+// Or, if a sync truly must happen, gate on the actual change
+React.useEffect(() => {
+  const lower = urlState.tab.toLowerCase();
+  if (urlState.tab !== lower) setUrl({ tab: lower });
+}, [urlState.tab, setUrl]);
+```
+
+URL throttling does not break a state→effect→setUrl→state cycle. The state updates first, the effect re-fires, repeat.
+
+Source: Maintainer interview
+
+### HIGH Calling `useUrlState` directly with separate default objects in N components
+
+Wrong:
+
+```typescript
+// ComponentA.tsx
+const DEFAULTS = { tab: 'a' };
+const { urlState } = useUrlState(DEFAULTS);
+
+// ComponentB.tsx  (different file → different identity)
+const DEFAULTS = { tab: 'a' };
+const { urlState } = useUrlState(DEFAULTS); // not sharing with A
+```
+
+Correct:
+
+```typescript
+// hooks/useFeatureState.ts — one source of truth
+export type FeatureState = { tab: 'a' | 'b' };
+export const FEATURE_STATE: FeatureState = { tab: 'a' };
+export const useFeatureState = () => useUrlState(FEATURE_STATE);
+
+// every component imports the hook, never useUrlState directly
+```
+
+Sharing is keyed by default-state object identity. Two components each declaring their own `const DEFAULTS = {...}` produce two independent stores even with identical shape.
+
+Source: Maintainer interview — highest-impact production hazard
+
+### HIGH `setUrl` or `setState` called during render
+
+Wrong:
+
+```typescript
+function Component() {
+  const { urlState, setUrl } = useFeatureState();
+  if (!urlState.initialized) setUrl({ initialized: true });
+  return <div>...</div>;
+}
+```
+
+Correct:
+
+```typescript
+function Component() {
+  const { urlState, setUrl } = useFeatureState();
+  React.useEffect(() => {
+    if (!urlState.initialized) setUrl({ initialized: true });
+  }, [urlState.initialized, setUrl]);
+}
+```
+
+State setters must run in effects or handlers, never during render. React surfaces this with "Cannot update a component while rendering a different component."
+
+Source: Maintainer interview
+
+### HIGH Storing non-JSON-serializable values
+
+Wrong:
+
+```typescript
+const STATE = { onChange: () => {}, items: new Set([1, 2]) };
+```
+
+Correct:
+
+```typescript
+const STATE = { items: [1, 2] as number[], updatedAt: new Date() };
+```
+
+Functions, Symbols, BigInt, Map, Set, ArrayBuffer, and class instances are not JSON-serializable and won't round-trip. Dates **are** supported (the encoder has special-case handling).
+
+Source: packages/urlstate/utils.ts (JSONCompatible type); README Gotchas
+
+### MEDIUM Mutating `urlState` directly
+
+Wrong:
+
+```typescript
+urlState.tab = 'b';  // no-op
+```
+
+Correct:
+
+```typescript
+setUrl({ tab: 'b' });
+```
+
+`urlState` is a reference to internal state; mutating it bypasses subscribers and URL sync.
+
+Source: JSDoc on `useUrlState` return type
+
+### MEDIUM Expecting reset to keep default-valued fields in the URL
+
+Wrong:
+
+```typescript
+// Wanting ?tab=features to persist after a reset
+const STATE = { tab: 'features' };
+reset(); // URL becomes clean — no ?tab= at all
+```
+
+Correct:
+
+```typescript
+// Pick a default that means "no selection". The URL stays clean at default;
+// ?tab=qa appears only when the user selects something non-default.
+const STATE = { tab: 'details' | 'qa' | 'applicants' };
+```
+
+The library only encodes fields whose value differs from the default — this is what keeps URLs short.
+
+Source: README "Best Practices"
+
+### MEDIUM Namespace collision between two features
+
+Wrong:
+
+```typescript
+const JOBS_STATE     = { tab: 'details' };
+const SETTINGS_STATE = { tab: 'profile' };
+// both mounted on same page → fight over ?tab=
+```
+
+Correct:
+
+```typescript
+type JobsState     = { jobs_tab: 'details' | 'qa' | 'applicants' };
+type SettingsState = { settings_tab: 'profile' | 'account' };
+
+const JOBS_STATE:     JobsState     = { jobs_tab: 'details' };
+const SETTINGS_STATE: SettingsState = { settings_tab: 'profile' };
+```
+
+Each `useUrlState` instance reads/writes its keys against the global query string. Two features defining the same field name overwrite each other.
+
+Source: Maintainer interview
+
+## Sensitive data
+
+Entity IDs (`jobId`, `memberId`, `channelId`) referencing public or semi-public DB rows are fine — they already appear in route paths and have no secrecy expectation. Never put **true secrets** in the URL: auth tokens, API keys, passwords, PII (email, SSN, phone).
+
+## Other primitives — when to reach for them
+
+- **`useSharedState`** — cross-component state without URL sync. See `state-in-url/shared-state-no-url`.
+- **`encodeState` / `decodeState`** — server-side or Node.js encoding/decoding of state strings (e.g. inside Next.js Proxy or a layout). Imported from `state-in-url/encodeState`.
+- **`useUrlStateBase`** — build a `useUrlState` for an unsupported router (TanStack Router etc.). Imported from `state-in-url/useUrlStateBase`.
+
+## URL size
+
+Keep total query-string size well under ~12 KB to stay safe across CDNs and Vercel's 14 KB header limit. See [Limits.md](https://github.com/asmyshlyaev177/state-in-url/blob/master/Limits.md).
+
+## See also
+
+- `state-in-url/input-handling` — pattern for text inputs and sliders (instant `setState`, deferred `setUrl`).
+- `state-in-url/nextjs-ssr` — required when using this skill in Next.js to avoid hydration mismatches.
+- `state-in-url/form-library-integration` — when the feature is a `react-hook-form` form.

package/skills/form-library-integration/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: form-library-integration
+description: >
+  Use the URL as a form draft store by pairing useUrlState with
+  react-hook-form (or formik). Share one module-scoped defaults object
+  between both libraries; hydrate useForm.defaultValues from urlState;
+  push form changes back into setUrl via RHF subscribe() (NOT watch()).
+  Load this skill when a form should round-trip its values through the
+  URL — filter forms, search forms, multi-step wizards with shareable
+  draft links.
+type: composition
+library: state-in-url
+library_version: '6.1.3'
+requires:
+  - feature-state-hook
+sources:
+  - 'asmyshlyaev177/state-in-url:issue#57'
+  - 'asmyshlyaev177/state-in-url:README.md'
+---
+
+This skill builds on `state-in-url/feature-state-hook`. Read it first for the module-scoped default-state rule.
+
+# state-in-url — Form library integration (react-hook-form)
+
+The canonical pattern: one module-scoped defaults object owns the form shape, both `useUrlState` and `useForm` consume it, RHF's `subscribe()` callback pushes form changes into `setUrl`. Hydration from URL happens through `defaultValues: urlState`.
+
+## Setup
+
+```typescript
+// features/filters/filtersState.ts
+import { z } from 'zod';
+
+export const filtersSchema = z.object({
+  q: z.string(),
+  sort: z.enum(['name', 'date']),
+  tags: z.array(z.string()),
+});
+export type FiltersState = z.infer<typeof filtersSchema>;
+
+export const FILTERS_STATE: FiltersState = {
+  q: '',
+  sort: 'name',
+  tags: [],
+};
+```
+
+```typescript
+// features/filters/FiltersForm.tsx
+'use client';
+import React from 'react';
+import { useSearchParams } from 'next/navigation';
+import { useForm } from 'react-hook-form';
+import { zodResolver } from '@hookform/resolvers/zod';
+import { useUrlState } from 'state-in-url/next';
+import { FILTERS_STATE, filtersSchema, type FiltersState } from './filtersState';
+
+export function FiltersForm() {
+  const searchParams = useSearchParams();
+  const { urlState, setUrl } = useUrlState(FILTERS_STATE, { searchParams });
+
+  const form = useForm<FiltersState>({
+    resolver: zodResolver(filtersSchema),
+    defaultValues: urlState, // hydrate from URL on mount
+  });
+
+  React.useEffect(() => {
+    const sub = form.subscribe({
+      formState: { values: true },
+      callback: ({ values }) => setUrl(values),
+    });
+    return () => sub();
+  }, [form, setUrl]);
+
+  return (
+    <form>
+      <input {...form.register('q')} />
+      <select {...form.register('sort')}>
+        <option value="name">Name</option>
+        <option value="date">Date</option>
+      </select>
+    </form>
+  );
+}
+```
+
+## Core Patterns
+
+### Hydrate `useForm` from `urlState`
+
+`defaultValues: urlState` runs once on mount; the form is initialized with whatever the URL contained (or `FILTERS_STATE` defaults if URL is empty).
+
+### Push form → URL with `subscribe()`
+
+RHF's `subscribe()` is push-based — it fires the callback without re-rendering the host component. Inside, call `setUrl(values)` to coalesce the change into the URL (the library content-diffs internally so no-ops are free).
+
+### Reset
+
+```typescript
+const onReset = () => {
+  form.reset(FILTERS_STATE); // reset form
+  setUrl((_, initial) => initial); // reset URL
+};
+```
+
+## Common Mistakes
+
+### HIGH Building `defaultValues` from `urlState` inline (not the module-scoped shape)
+
+Wrong:
+
+```typescript
+const defaults = { ...formValues, ...overrides }; // new object each render
+const { urlState } = useUrlState(defaults);
+const form = useForm({ defaultValues: defaults });
+```
+
+Correct:
+
+```typescript
+// One module-scoped const, shared by both hooks
+export const FILTERS_STATE: FiltersState = { q: '', sort: 'name', tags: [] };
+
+const { urlState } = useUrlState(FILTERS_STATE, { searchParams });
+const form = useForm({ defaultValues: urlState }); // hydrate from URL
+```
+
+A fresh `defaults` on each render breaks `useUrlState`'s identity-based sharing (same root cause as the cross-skill failure). Use the module-scoped shape for `useUrlState`; pass `urlState` (the live value) to `useForm`.
+
+Source: GitHub issue #57 (asmyshlyaev177/state-in-url, maintainer reply)
+
+### MEDIUM Using `watch()` instead of `subscribe()` to sync RHF → URL
+
+Wrong:
+
+```typescript
+const values = form.watch();
+React.useEffect(() => {
+  setUrl(values);
+}, [values, setUrl]);
+```
+
+Correct:
+
+```typescript
+React.useEffect(() => {
+  const sub = form.subscribe({
+    formState: { values: true },
+    callback: ({ values }) => setUrl(values),
+  });
+  return () => sub();
+}, [form, setUrl]);
+```
+
+`watch()` re-renders the host component on every field change. `subscribe()` is push-based and avoids the rerender, which matters in large forms.
+
+Source: GitHub issue #57 (asmyshlyaev177/state-in-url, maintainer reply)
+
+### CRITICAL `defaultState` defined inside the React component
+
+(Cross-skill failure — also in `feature-state-hook`.)
+
+Wrong:
+
+```typescript
+function FiltersForm({ initialSort }: Props) {
+  const defaults = { q: '', sort: initialSort, tags: [] }; // each render
+  const { urlState } = useUrlState(defaults);
+}
+```
+
+Correct: Move the shape to a module-scoped `const` (`FILTERS_STATE`) and import it.
+
+Source: GitHub issues #57, #60, #69 (asmyshlyaev177/state-in-url)
+
+## formik variant
+
+Same idea: subscribe to `formik.values` and call `setUrl`. With formik, use a `useEffect` on `values` since formik does re-render on changes by design.
+
+```typescript
+const formik = useFormik({ initialValues: urlState, onSubmit: () => {} });
+
+React.useEffect(() => {
+  setUrl(formik.values);
+}, [formik.values, setUrl]);
+```
+
+## See also
+
+- `state-in-url/feature-state-hook` — base pattern; required reading.
+- `state-in-url/nextjs-ssr` — for SSR hydration of the filter form on Next.js.
+- `state-in-url/input-handling` — for non-form inputs (search box not inside a form).

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.