@djangocfg/ui-core 2.1.293 → 2.1.297

package/src/components/select/combobox.tsx

@@ -4,7 +4,7 @@ import { Check, ChevronsUpDown } from 'lucide-react';
 import * as React from 'react';
 
 import { useAppT } from '@djangocfg/i18n';
-import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../hooks/useStoredValue';
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../hooks';
 import { cn } from '../../lib/utils';
 import { Badge } from '../data/badge';
 import { Button } from '../forms/button';

package/src/components/select/multi-select.tsx

@@ -4,7 +4,7 @@ import { Check, ChevronsUpDown, X } from 'lucide-react';
 import * as React from 'react';
 
 import { useAppT } from '@djangocfg/i18n';
-import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../hooks/useStoredValue';
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../hooks';
 import { cn } from '../../lib/utils';
 import { Badge } from '../data/badge';
 import { Button } from '../forms/button';

package/src/components/specialized/image-with-fallback/index.tsx

@@ -7,7 +7,7 @@
 import { Car, ImageIcon, MapPin, Package, User } from 'lucide-react';
 import React, { forwardRef } from 'react';
 
-import { useImageLoader } from '../../../hooks/useImageLoader';
+import { useImageLoader } from '../../../hooks';
 import { cn } from '../../../lib/utils';
 
 export interface ImageWithFallbackProps extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'onLoad' | 'onError'> {

package/src/hooks/debug/index.ts

@@ -0,0 +1,3 @@
+'use client';
+
+export { useDebugTools } from './useDebugTools';

package/src/hooks/device/index.ts

@@ -0,0 +1,7 @@
+'use client';
+
+export { useBrowserDetect } from './useBrowserDetect';
+export type { BrowserInfo } from './useBrowserDetect';
+export { useDeviceDetect } from './useDeviceDetect';
+export type { DeviceDetectResult } from './useDeviceDetect';
+export { useShortcutModLabel } from './useShortcutModLabel';

package/src/hooks/dom/index.ts

@@ -0,0 +1,12 @@
+'use client';
+
+export { useBodyScrollLock } from './useBodyScrollLock';
+export { useCopy } from './useCopy';
+export { useImageLoader } from './useImageLoader';
+export {
+  useScroll,
+  useScrollPosition,
+  useScrollDirection,
+  useIsScrolling,
+} from './useScroll';
+export type { ScrollSnapshot, ScrollDirection, ScrollTarget } from './useScroll';

package/src/hooks/{useBodyScrollLock.ts → dom/useBodyScrollLock.ts}

@@ -2,7 +2,7 @@
 
 import { useEffect } from 'react';
 
-import { useDeviceDetect } from './useDeviceDetect';
+import { useDeviceDetect } from '../device/useDeviceDetect';
 
 /**
  * useBodyScrollLock — locks body scroll while `locked` is true.

package/src/hooks/{useCopy.ts → dom/useCopy.ts}

@@ -2,7 +2,7 @@
 
 import { useCallback } from 'react';
 
-import { useToast } from './useToast';
+import { useToast } from '../feedback/useToast';
 
 interface UseCopyOptions {
     successMessage?: string;

package/src/hooks/dom/useScroll.ts

@@ -0,0 +1,322 @@
+'use client';
+
+/**
+ * useScroll — reactive snapshot of `scrollX` / `scrollY` for window or any
+ * scrollable element.
+ *
+ * WHY:
+ *   The DOM exposes scroll position via mutating `Element.scrollTop` /
+ *   `Element.scrollLeft`, with the only signal being a flood of `scroll`
+ *   events. To bridge this to React safely we:
+ *
+ *     1. **`useSyncExternalStore`** — the React-19-blessed primitive for
+ *        external mutable sources. Solves SSR (`getServerSnapshot` returns
+ *        zeros) and concurrent-mode tearing for free. Existing libraries
+ *        (`react-use`, `usehooks-ts`, `@uidotdev/usehooks`) all predate
+ *        this API and use plain `useState` + `useEffect`, which costs
+ *        them re-renders on every frame at rest if their equality bailout
+ *        is wrong (see react-use issue #1473).
+ *
+ *     2. **rAF-throttled writes, not subscribes** — scroll fires up to
+ *        ~120 events/s on a Magic Trackpad. Reading `scrollX` is cheap
+ *        but waking React isn't. We coalesce to one snapshot per frame
+ *        per target, then notify subscribers once.
+ *
+ *     3. **Module-level store keyed by EventTarget** — many components
+ *        on a page subscribe to the same `window` scroll. Without a
+ *        shared store you'd attach N listeners and run rAF N times per
+ *        frame. The store deduplicates: one listener + one rAF per
+ *        unique target, regardless of subscriber count.
+ *
+ *     4. **`{ passive: true }`** — non-passive scroll listeners block
+ *        compositor scrolling on mobile (Chrome warns about this in
+ *        DevTools). Always opt in.
+ *
+ * @example
+ *   const { y, direction, isScrolling } = useScroll();
+ *   <header className={direction === 'down' && isScrolling ? 'hidden' : ''} />
+ *
+ * @example
+ *   // Scroll inside a panel:
+ *   const ref = useRef<HTMLDivElement>(null);
+ *   const { y } = useScrollPosition(ref);
+ *
+ * @example
+ *   // Subscribe to ONE field — re-renders only when direction flips,
+ *   // not on every pixel of scroll:
+ *   const direction = useScrollDirection();
+ */
+
+import { useCallback, useSyncExternalStore, type RefObject } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type ScrollDirection = 'up' | 'down' | 'left' | 'right' | null;
+
+/** Frozen snapshot returned to React. Identity changes only when contents change. */
+export interface ScrollSnapshot {
+  /** Horizontal scroll offset in CSS pixels. */
+  x: number;
+  /** Vertical scroll offset in CSS pixels. */
+  y: number;
+  /**
+   * Direction of the LAST delta. Resets to `null` after `isScrolling`
+   * falls to `false`. For cumulative direction (e.g. hide-on-scroll
+   * navbar), build on top of this.
+   */
+  direction: ScrollDirection;
+  /** True until 150 ms have passed since the last scroll event. */
+  isScrolling: boolean;
+}
+
+export type ScrollTarget = RefObject<Element | null> | Window;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SSR snapshot
+// ─────────────────────────────────────────────────────────────────────────────
+
+const SSR_SNAPSHOT: ScrollSnapshot = Object.freeze({
+  x: 0,
+  y: 0,
+  direction: null,
+  isScrolling: false,
+});
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Per-target store
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface TargetState {
+  snapshot: ScrollSnapshot;
+  subscribers: Set<() => void>;
+  rafId: number | null;
+  idleTimer: ReturnType<typeof setTimeout> | null;
+  removeListener: () => void;
+}
+
+/**
+ * One entry per unique scroll source on the page (typically just `window`,
+ * plus any scrollable panels). Lives at module scope so every consumer
+ * shares the same listener + rAF.
+ */
+const stores = new WeakMap<EventTarget, TargetState>();
+
+const IDLE_MS = 150;
+
+/** Reads the current scroll offsets from a target. */
+function readScroll(target: EventTarget): { x: number; y: number } {
+  if (target === window) {
+    return { x: window.scrollX, y: window.scrollY };
+  }
+  const el = target as Element;
+  return { x: el.scrollLeft, y: el.scrollTop };
+}
+
+function deriveDirection(
+  prev: { x: number; y: number },
+  next: { x: number; y: number }
+): ScrollDirection {
+  const dx = next.x - prev.x;
+  const dy = next.y - prev.y;
+  // Vertical wins on ties — most pages scroll vertically.
+  if (Math.abs(dy) >= Math.abs(dx)) {
+    if (dy > 0) return 'down';
+    if (dy < 0) return 'up';
+    return null;
+  }
+  if (dx > 0) return 'right';
+  if (dx < 0) return 'left';
+  return null;
+}
+
+function getOrCreateStore(target: EventTarget): TargetState {
+  const existing = stores.get(target);
+  if (existing) return existing;
+
+  // Initial read so the first snapshot is correct (don't wait for first event).
+  const initial = readScroll(target);
+
+  const state: TargetState = {
+    snapshot: Object.freeze({
+      x: initial.x,
+      y: initial.y,
+      direction: null,
+      isScrolling: false,
+    }),
+    subscribers: new Set(),
+    rafId: null,
+    idleTimer: null,
+    removeListener: () => {},
+  };
+
+  const onScroll = () => {
+    // Coalesce bursts of scroll events to one rAF tick. Reading scrollX
+    // mid-event is cheap, but notifying React isn't.
+    if (state.rafId !== null) return;
+    state.rafId = requestAnimationFrame(() => {
+      state.rafId = null;
+      const next = readScroll(target);
+      const direction = deriveDirection(state.snapshot, next);
+      // Equality bailout: if nothing changed AND we're already marked as
+      // scrolling, skip the snapshot mint and the React notification.
+      // This catches duplicate scroll events on the same frame.
+      if (
+        next.x === state.snapshot.x &&
+        next.y === state.snapshot.y &&
+        state.snapshot.isScrolling
+      ) {
+        return;
+      }
+      state.snapshot = Object.freeze({
+        x: next.x,
+        y: next.y,
+        direction,
+        isScrolling: true,
+      });
+      // Reset idle timer — fires once user pauses for IDLE_MS.
+      if (state.idleTimer !== null) clearTimeout(state.idleTimer);
+      state.idleTimer = setTimeout(() => {
+        state.idleTimer = null;
+        state.snapshot = Object.freeze({
+          x: state.snapshot.x,
+          y: state.snapshot.y,
+          // Direction also resets — fresh scroll restarts the signal.
+          direction: null,
+          isScrolling: false,
+        });
+        for (const cb of state.subscribers) cb();
+      }, IDLE_MS);
+      for (const cb of state.subscribers) cb();
+    });
+  };
+
+  target.addEventListener('scroll', onScroll, { passive: true, capture: false });
+  state.removeListener = () => {
+    target.removeEventListener('scroll', onScroll, { capture: false });
+  };
+
+  stores.set(target, state);
+  return state;
+}
+
+function teardownStore(target: EventTarget): void {
+  const state = stores.get(target);
+  if (!state || state.subscribers.size > 0) return;
+  state.removeListener();
+  if (state.rafId !== null) cancelAnimationFrame(state.rafId);
+  if (state.idleTimer !== null) clearTimeout(state.idleTimer);
+  stores.delete(target);
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Subscribe / getSnapshot factories
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Resolves a `RefObject | Window | undefined` to an actual EventTarget at
+ * call time. Must be called inside subscribe/getSnapshot — if the ref's
+ * `.current` flips between renders, we want to follow it.
+ */
+function resolveTarget(target: ScrollTarget | undefined): EventTarget | null {
+  if (typeof window === 'undefined') return null;
+  if (!target || target === window) return window;
+  // RefObject — read current at call site, may be null before mount.
+  return (target as RefObject<Element | null>).current ?? null;
+}
+
+function subscribeFactory(target: ScrollTarget | undefined) {
+  return (onChange: () => void): (() => void) => {
+    const t = resolveTarget(target);
+    if (!t) return () => {};
+    const state = getOrCreateStore(t);
+    state.subscribers.add(onChange);
+    return () => {
+      state.subscribers.delete(onChange);
+      teardownStore(t);
+    };
+  };
+}
+
+function getSnapshotFactory(target: ScrollTarget | undefined) {
+  return (): ScrollSnapshot => {
+    const t = resolveTarget(target);
+    if (!t) return SSR_SNAPSHOT;
+    const state = stores.get(t);
+    return state ? state.snapshot : SSR_SNAPSHOT;
+  };
+}
+
+const getServerSnapshot = (): ScrollSnapshot => SSR_SNAPSHOT;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Public hooks
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Reactive snapshot of scroll position + direction + isScrolling for the
+ * given target (default: `window`). Returns a stable object reference until
+ * something actually changes — safe to put in deps arrays.
+ *
+ * If you only need ONE field, prefer `useScrollPosition`,
+ * `useScrollDirection`, or `useIsScrolling` — they subscribe to the same
+ * underlying store but let React skip re-renders when other fields change.
+ */
+export function useScroll(target?: ScrollTarget): ScrollSnapshot {
+  const subscribe = useCallback(subscribeFactory(target), [target]);
+  const getSnapshot = useCallback(getSnapshotFactory(target), [target]);
+  return useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+}
+
+/**
+ * Subscribe to just `{x, y}`. Re-renders only when the scroll offsets
+ * change — direction flips and isScrolling transitions are ignored.
+ */
+export function useScrollPosition(target?: ScrollTarget): { x: number; y: number } {
+  const subscribe = useCallback(subscribeFactory(target), [target]);
+  const getServerXY = useCallback(() => SSR_XY, []);
+  const getXY = useCallback(() => {
+    const snap = getSnapshotFactory(target)();
+    // Cache by snapshot identity — every snapshot is frozen, so identity
+    // change ⇔ content change. Avoids minting a new {x,y} on every read.
+    return positionCache.get(snap) ?? cachePosition(snap);
+  }, [target]);
+  return useSyncExternalStore(subscribe, getXY, getServerXY);
+}
+
+const SSR_XY = Object.freeze({ x: 0, y: 0 });
+const positionCache = new WeakMap<ScrollSnapshot, { x: number; y: number }>();
+function cachePosition(snap: ScrollSnapshot): { x: number; y: number } {
+  const xy = Object.freeze({ x: snap.x, y: snap.y });
+  positionCache.set(snap, xy);
+  return xy;
+}
+
+/**
+ * Subscribe to just the direction signal. Re-renders only when direction
+ * flips (e.g. user reverses scroll).
+ */
+export function useScrollDirection(target?: ScrollTarget): ScrollDirection {
+  const subscribe = useCallback(subscribeFactory(target), [target]);
+  const getDirection = useCallback(
+    () => getSnapshotFactory(target)().direction,
+    [target]
+  );
+  const getServerDirection = useCallback((): ScrollDirection => null, []);
+  return useSyncExternalStore(subscribe, getDirection, getServerDirection);
+}
+
+/**
+ * `true` while the user is actively scrolling, `false` after a 150 ms
+ * idle gap. Useful for hiding hover overlays while scrolling.
+ */
+export function useIsScrolling(target?: ScrollTarget): boolean {
+  const subscribe = useCallback(subscribeFactory(target), [target]);
+  const getIsScrolling = useCallback(
+    () => getSnapshotFactory(target)().isScrolling,
+    [target]
+  );
+  const getServerIsScrolling = useCallback(() => false, []);
+  return useSyncExternalStore(subscribe, getIsScrolling, getServerIsScrolling);
+}

package/src/hooks/events/index.ts

@@ -0,0 +1,3 @@
+'use client';
+
+export { useEventListener, events } from './useEventsBus';

package/src/hooks/feedback/index.ts

@@ -0,0 +1,3 @@
+'use client';
+
+export { useToast, toast } from './useToast';

package/src/hooks/hotkey/index.ts

@@ -0,0 +1,4 @@
+'use client';
+
+export { useHotkey, useHotkeysContext, HotkeysProvider, isHotkeyPressed } from './useHotkey';
+export type { UseHotkeyOptions, HotkeyCallback, Keys, HotkeyRefType } from './useHotkey';

package/src/hooks/index.ts

@@ -1,33 +1,89 @@
 // ============================================================================
 // Hooks - Reusable React Hooks (No Next.js/Browser Storage dependencies)
 // For use in Electron, Vite, CRA apps
+//
+// Hooks are grouped by domain (see ./<group>/index.ts). This top-level barrel
+// re-exports everything for convenience: `from '@djangocfg/ui-core/hooks'`.
+// For tree-shaking or clarity, import the group directly:
+//   `from '@djangocfg/ui-core/hooks/dom'`, etc.
 // ============================================================================
 
 'use client';
 
-export { useCountdown, useCountdownFromSeconds } from './useCountdown';
-export type { CountdownState } from './useCountdown';
-export { useDebouncedCallback } from './useDebouncedCallback';
-export { useDebounce } from './useDebounce';
-export { useDebugTools } from './useDebugTools';
-export { useEventListener, events } from './useEventsBus';
-export { useIsMobile, useIsPhone, useIsTabletOrBelow, BREAKPOINTS } from './useMobile';
-export { useBodyScrollLock } from './useBodyScrollLock';
-export type { Breakpoint } from './useMobile';
-export { useMediaQuery, BREAKPOINTS as MEDIA_BREAKPOINTS } from './useMediaQuery';
-export { useCopy } from './useCopy';
-export { useImageLoader } from './useImageLoader';
-export { useToast, toast } from './useToast';
-export { useResolvedTheme } from './useResolvedTheme';
-export type { ResolvedTheme } from './useResolvedTheme';
-export { useLocalStorage } from './useLocalStorage';
-export { useSessionStorage } from './useSessionStorage';
-export { useStoredValue } from './useStoredValue';
-export type { UseStoredValueOptions, StorageType } from './useStoredValue';
-export { useHotkey, useHotkeysContext, HotkeysProvider, isHotkeyPressed } from './useHotkey';
-export type { UseHotkeyOptions, HotkeyCallback, Keys, HotkeyRefType } from './useHotkey';
-export { useShortcutModLabel } from './useShortcutModLabel';
-export { useBrowserDetect } from './useBrowserDetect';
-export type { BrowserInfo } from './useBrowserDetect';
-export { useDeviceDetect } from './useDeviceDetect';
-export type { DeviceDetectResult } from './useDeviceDetect';
+export * from './dom';
+export * from './state';
+export * from './media';
+export * from './device';
+export * from './feedback';
+export * from './theme';
+export * from './time';
+export * from './events';
+export * from './hotkey';
+export * from './debug';
+
+// ----------------------------------------------------------------------------
+// Router — framework-agnostic navigation primitives.
+// See ./router/README.md for design notes and the Next.js adapter example.
+// ----------------------------------------------------------------------------
+export {
+  // Adapter
+  RouterAdapterContext,
+  RouterAdapterProvider,
+  defaultAdapter,
+  useRouterAdapter,
+  // useLocation
+  useLocation,
+  NAVIGATE_EVENT,
+  // useNavigate
+  useNavigate,
+  // useQueryParams
+  useQueryParams,
+  // useBackOrFallback
+  useBackOrFallback,
+  // useUrlBuilder
+  useUrlBuilder,
+  buildUrl,
+  buildQueryString,
+  // useSmartLink
+  useSmartLink,
+  // useIsActive
+  useIsActive,
+  // useQueryState (typed single-key URL state)
+  useQueryState,
+  // Parsers
+  parseAsString,
+  parseAsInteger,
+  parseAsFloat,
+  parseAsBoolean,
+  parseAsIsoDate,
+  parseAsStringEnum,
+  parseAsArrayOf,
+  parseAsJson,
+  // useRouter (composite facade)
+  useRouter,
+} from './router';
+export type {
+  RouterAdapter,
+  RouterAdapterProviderProps,
+  RouterLocation,
+  LocationSnapshot,
+  NavigateOptions,
+  UseNavigateReturn,
+  QueryParamsSnapshot,
+  QueryParamValue,
+  QueryParamUpdates,
+  SetQueryParamsOptions,
+  UseQueryParamsReturn,
+  UseBackOrFallbackReturn,
+  QueryValue,
+  QueryParamsInput,
+  UseUrlBuilderReturn,
+  UseSmartLinkOptions,
+  SmartLinkHandlers,
+  UseIsActiveOptions,
+  UseQueryStateOptions,
+  QueryStateUpdater,
+  QueryParser,
+  QueryParserBuilder,
+  UseRouterReturn,
+} from './router';

package/src/hooks/media/index.ts

@@ -0,0 +1,5 @@
+'use client';
+
+export { useMediaQuery, BREAKPOINTS as MEDIA_BREAKPOINTS } from './useMediaQuery';
+export { useIsMobile, useIsPhone, useIsTabletOrBelow, BREAKPOINTS } from './useMobile';
+export type { Breakpoint } from './useMobile';

package/src/hooks/router/README.md

@@ -0,0 +1,121 @@
+# Router hooks
+
+Framework-agnostic navigation primitives for `@djangocfg/ui-core`. Built on plain browser APIs (`window.history`, `window.location`, `URLSearchParams`, `popstate`). No `next/*`, no `react-router`, no third-party deps.
+
+## Surface
+
+| Hook | Purpose |
+| --- | --- |
+| `useLocation` | Reactive snapshot of `window.location` (`pathname`, `search`, `hash`, `href`). |
+| `useNavigate` | Programmatic navigation: `navigate`, `navigateExternal`, `push`, `replace`, `back`, `forward`. |
+| `useQueryParams` | Read/write `?key=value` URL state with typed coercion (`get`, `getNumber`, `getBoolean`, `set`, `remove`, `clear`). |
+| `useBackOrFallback` | Smart "back" that falls back to a route when there's no in-app history. |
+| `useUrlBuilder` | Pure URL/querystring assembly: `build`, `withCurrentParams`. |
+| `useSmartLink` | Click + keyboard handlers that turn any element into a proper link (cmd-click, middle-click, Enter, Space). |
+| `useIsActive` | `boolean` for "current pathname matches this href" — for nav-item highlighting. |
+| `useQueryState` | Typed `useState`-style hook bound to ONE URL key (with parsers + `clearOnDefault`). |
+| `useLocationProperty` | Subscribe to ONE derived field of `window.location` (avoids re-renders on unrelated fields). |
+| `useRouter` | Convenience facade composing the above. |
+| `RouterAdapterProvider` | Swap the navigation backend (e.g. Next.js's router). |
+| `parseAsString` / `parseAsInteger` / `parseAsFloat` / `parseAsBoolean` / `parseAsIsoDate` / `parseAsStringEnum` / `parseAsArrayOf` / `parseAsJson` | Parser builders for `useQueryState`. Each has `.withDefault(value)`. |
+
+## Decomposition rationale
+
+Each atomic hook subscribes to exactly what it needs. A component that only calls `navigate(...)` shouldn't re-render every time the querystring changes — `useNavigate` doesn't subscribe to location, so it doesn't. Same for `useUrlBuilder` (only re-renders on `search` change), `useQueryParams` (same), and so on.
+
+`useRouter` exists for convenience and ergonomic familiarity. Use it when you want everything in one return; use the atomic hooks for fewer re-renders and better tree-shaking.
+
+## Adapter pattern
+
+Default behavior uses `window.history.pushState` + `window.location` and works in any browser (Wails / Electron / Vite / CRA — nothing to mount, it just works).
+
+For Next.js — mount both adapters once near the root. They bridge router hooks to `next/navigation` and `<Link>` to `next/link` so server components, route loaders, and prefetch fire correctly:
+
+```tsx
+// app/[locale]/layout.tsx (or wherever your client provider stack lives)
+import { NextRouterAdapter, NextLinkProvider } from '@djangocfg/ui-core/adapters/nextjs';
+
+<I18nProvider locale={locale} messages={messages}>
+  <NextRouterAdapter>
+    <NextLinkProvider>
+      <AppLayout>{children}</AppLayout>
+    </NextLinkProvider>
+  </NextRouterAdapter>
+</I18nProvider>
+```
+
+`next` is an **optional peer dependency** — the package never imports from `next/*` from the main entry. The Next adapter lives behind the `/adapters/nextjs` sub-path entry, so non-Next consumers don't pull `next` into their bundle.
+
+For other routers (TanStack Router, wouter, Remix, custom transports) — write a ~20-line custom adapter:
+
+```tsx
+'use client';
+
+import { useMemo } from 'react';
+import { RouterAdapterProvider, type RouterAdapter } from '@djangocfg/ui-core/hooks';
+
+export function MyRouterAdapter({ children }: { children: React.ReactNode }) {
+  const myRouter = useMyRouter();
+  const adapter = useMemo<RouterAdapter>(() => ({
+    push:    (url) => myRouter.push(url),
+    replace: (url) => myRouter.replace(url),
+    back:    () => myRouter.back(),
+    forward: () => myRouter.forward(),
+    getLocation: () => ({
+      pathname: window.location.pathname,
+      search:   window.location.search,
+      hash:     window.location.hash,
+    }),
+  }), [myRouter]);
+
+  return <RouterAdapterProvider value={adapter}>{children}</RouterAdapterProvider>;
+}
+```
+
+**Adapter contract gotcha:** custom `push` / `replace` implementations should ultimately route through `window.history.pushState` (Next does, so does react-router). If yours doesn't, dispatch `'djc:navigate'` after each navigation manually so `useLocation` re-reads.
+
+## `useQueryState` (typed URL state)
+
+Bound to one query key with a typed parser. Inspired by `nuqs` but framework-agnostic via the same adapter context.
+
+```tsx
+import {
+  useQueryState,
+  parseAsInteger,
+  parseAsStringEnum,
+} from '@djangocfg/ui-core/hooks';
+
+const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
+const [tab,  setTab]  = useQueryState('tab',  parseAsStringEnum(['list', 'grid']).withDefault('list'));
+
+setPage((prev) => prev + 1); // functional updater, just like useState
+setPage(null);               // clears the key from the URL
+```
+
+`clearOnDefault` (default `true`) drops the key from the URL when the value equals the parser default — keeps URLs short. Pass `{ clearOnDefault: false }` to keep explicit `?page=1` for shareable links.
+
+Parsers: `parseAsString`, `parseAsInteger`, `parseAsFloat`, `parseAsBoolean`, `parseAsIsoDate`, `parseAsStringEnum([...])`, `parseAsArrayOf(item)`, `parseAsJson<T>()`. Each has `.withDefault(value)`. Build your own by satisfying the `QueryParser<T>` interface — it's three functions (`parse`, `serialize`, `eq`).
+
+## How `useLocation` knows about `pushState`
+
+Browsers don't fire `popstate` for programmatic `pushState` / `replaceState`. We monkey-patch both methods once (idempotent, module-level guard) on first mount and dispatch a custom `'djc:navigate'` event after each call. Anyone calling history APIs anywhere in the page will trigger an update — including the consumer's own router, third-party scripts, and our default adapter.
+
+## SSR
+
+- All hooks return safe defaults on the server (`pathname: '/'`, etc.).
+- `useSyncExternalStore`'s `getServerSnapshot` is wired up correctly.
+- Mutating methods (`push`, `replace`, `navigate`, `navigateExternal`) no-op when `window` is undefined.
+- No hydration mismatches — first client render reads real `window.location` after mount via `useSyncExternalStore`'s `getSnapshot`.
+
+## Trade-offs vs. `next/navigation`
+
+| Concern | `next/navigation` | This library |
+| --- | --- | --- |
+| Server components fire | yes (built-in) | only if you mount the Next adapter |
+| Pending state (`useTransition`) | bundled in | wrap calls yourself |
+| Locale-prefix handling | yes | no — wrap if needed |
+| Route matching / dynamic segments | yes | no — out of scope |
+| Works outside Next | no | yes — anywhere React runs |
+| `<Link>` component | yes | yes — `<Link>` / `<ButtonLink>` in `@djangocfg/ui-core/components` (Next-aware via `NextLinkProvider`) |
+
+Out of scope: locale prefixes, route matching, dynamic segments, transitions. Add them in consumer code or in higher-level packages.