@djangocfg/ui-core 2.1.616 → 2.1.617

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.616",
+  "version": "2.1.617",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -138,8 +138,8 @@
     "check:docs": "node scripts/check-docs.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.616",
-    "@djangocfg/i18n": "^2.1.616",
+    "@djangocfg/api": "^2.1.617",
+    "@djangocfg/i18n": "^2.1.617",
     "consola": "^3.4.2",
     "lucide-react": "^1.68.0",
     "moment": "^2.30.1",
@@ -214,10 +214,10 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.616",
-    "@djangocfg/eslint-config": "^2.1.616",
-    "@djangocfg/i18n": "^2.1.616",
-    "@djangocfg/typescript-config": "^2.1.616",
+    "@djangocfg/api": "^2.1.617",
+    "@djangocfg/eslint-config": "^2.1.617",
+    "@djangocfg/i18n": "^2.1.617",
+    "@djangocfg/typescript-config": "^2.1.617",
     "@storybook/react-vite": "^10.6.5",
     "@types/node": "^24.13.3",
     "@types/react": "19.3.0",

package/src/hooks/router/README.md

@@ -123,6 +123,14 @@ Later or nested entries win field by field; an explicit option on a call beats t
 
 The bar is ours: [`route-progress`](../../route-progress/README.md). The adapter starts it for programmatic navigation, link clicks are caught by the provider, and every committed navigation (a new pathname, or Next's `pushState`) ends it, with a 15 s ceiling, so a forced bar on a query change cannot hang. Without a `RouteProgressProvider` above (BaseApp mounts one) there is no bar and `useNavigationBehavior` does nothing.
 
+## Shallow writes (no navigation)
+
+`useQueryState(key, parser, { shallow: true })`, or `setValue(v, { shallow: true })` for one call, writes the URL through the History API and nothing else: no request to the server, no server components re-rendered, no loading bar, no scroll (`scroll` and `progress` are ignored). For state only the client needs (a view mode, a zoom, a slider), above all on `force-dynamic` pages where every router call is a full server render. Precedence: the call, then the hook, then `false`. `replace` still picks `replaceState` or `pushState`; with `push`, Back and Forward restore the earlier value (`useLocation` listens to `popstate`). `useNavigate().shallow(href, { replace })` is the same write without the hook.
+
+The adapter method is `RouterAdapter.shallow?(url, { replace })`; the default and Next adapters implement it, passing `null` as the history state (Next syncs `useSearchParams` only for entries without its own `__NA`/`_N` keys, so `history.state` must not be forwarded). An adapter without it falls back to `push`/`replace` with the bar and scroll off.
+
+Setters read the URL at the moment of the call, not the one the last render saw, so two calls in one tick both land and a functional updater sees the earlier write (this holds for normal mode too, though there the URL changes only when the router commits).
+
 ## `useQueryState` (typed URL state)
 
 Bound to one query key with a typed parser. Inspired by `nuqs` but framework-agnostic via the same adapter context.

package/src/hooks/router/adapter.tsx

@@ -77,6 +77,15 @@ export interface RouterAdapter {
   forward: () => void;
   /** Read the current location (synchronous). */
   getLocation: () => RouterLocation;
+  /**
+   * Write the URL without a navigation: no request to the server, no server
+   * components re-rendered, no loading bar, no scroll. For state that only the
+   * client needs (a view mode, a zoom, a slider). Optional: when an adapter has
+   * none, callers fall back to `push`/`replace` with the bar and the scroll off.
+   * Implementations must pass `null` as the history state: Next syncs
+   * `useSearchParams` only for entries without its own router keys.
+   */
+  shallow?: (url: string, opts?: { replace?: boolean }) => void;
 }
 
 const SSR_LOCATION: RouterLocation = Object.freeze({
@@ -115,8 +124,23 @@ export const defaultAdapter: RouterAdapter = Object.freeze({
       hash: window.location.hash,
     };
   },
+  shallow(url: string, opts?: { replace?: boolean }) {
+    writeUrlShallow(url, opts?.replace ?? false);
+  },
 });
 
+/**
+ * Write the URL through the History API and nothing else. The state is `null`,
+ * never `history.state`: Next marks its own entries (`__NA`, `_N`) and ignores
+ * the ones it did not make when it syncs `useSearchParams`/`usePathname`.
+ * Our patched `pushState`/`replaceState` tell `useLocation`, so hooks update.
+ */
+export function writeUrlShallow(url: string, replace: boolean): void {
+  if (typeof window === 'undefined') return;
+  if (replace) window.history.replaceState(null, '', url);
+  else window.history.pushState(null, '', url);
+}
+
 /**
  * React context carrying the active adapter. `null` means "use default".
  * Kept intentionally nullable so we don't burn a Provider for the default case.

package/src/hooks/router/adapters/nextjs.tsx

@@ -50,6 +50,7 @@ import {
   type RouterAdapter,
   type RouterLocation,
   type RouterNavigateOptions,
+  writeUrlShallow,
 } from '../adapter';
 import { useRouteProgress } from '../../../route-progress';
 import { shouldStartProgress } from '../../../route-progress/provider/shouldStart';
@@ -132,6 +133,10 @@ export function NextRouterAdapter({ children, defaultScroll }: NextRouterAdapter
         startBar(url, opts);
         next.replace(url, nextOptions(opts));
       },
+      // No router call: no RSC request, no bar, no scroll. `null` state so Next syncs `useSearchParams`.
+      shallow(url, opts) {
+        writeUrlShallow(url, opts?.replace ?? false);
+      },
       back() {
         next.back();
       },

package/src/hooks/router/useNavigate.ts

@@ -52,6 +52,12 @@ export interface UseNavigateReturn {
    * Use for logout, OAuth, or any cross-origin handoff.
    */
   navigateExternal: (href: string) => void;
+  /**
+   * Write the URL without a navigation (no server request, no bar, no scroll), see
+   * `RouterAdapter.shallow`. Falls back to `push`/`replace` with bar and scroll off
+   * when the adapter has no shallow write.
+   */
+  shallow: (href: string, opts?: { replace?: boolean }) => void;
   /** Pass-through: adapter.push */
   push: (url: string, opts?: RouterNavigateOptions) => void;
   /** Pass-through: adapter.replace */
@@ -86,6 +92,19 @@ export function useNavigate(): UseNavigateReturn {
     [adapter]
   );
 
+  const shallow = useCallback(
+    (href: string, opts?: { replace?: boolean }) => {
+      if (adapter.shallow) {
+        adapter.shallow(href, opts);
+        return;
+      }
+      const fallback = { scroll: false, progress: false };
+      if (opts?.replace) adapter.replace(href, fallback);
+      else adapter.push(href, fallback);
+    },
+    [adapter]
+  );
+
   const navigateExternal = useCallback((href: string) => {
     if (typeof window === 'undefined') return;
     window.location.assign(href);
@@ -97,7 +116,7 @@ export function useNavigate(): UseNavigateReturn {
   const forward = useCallback(() => adapter.forward(), [adapter]);
 
   return useMemo<UseNavigateReturn>(
-    () => ({ navigate, navigateExternal, push, replace, back, forward }),
-    [navigate, navigateExternal, push, replace, back, forward]
+    () => ({ navigate, navigateExternal, shallow, push, replace, back, forward }),
+    [navigate, navigateExternal, shallow, push, replace, back, forward]
   );
 }

package/src/hooks/router/useQueryState.ts

@@ -20,6 +20,7 @@
  */
 
 import { useCallback, useMemo } from 'react';
+import { useRouterAdapter } from './adapter';
 import { useLocation } from './useLocation';
 import { useNavigate } from './useNavigate';
 import type { QueryParser } from './parsers';
@@ -34,6 +35,13 @@ export interface UseQueryStateOptions {
    * transition. Pass `true` when the change loads a heavy server view.
    */
   progress?: boolean;
+  /**
+   * Write the URL without a navigation: no request to the server, no server
+   * components re-rendered, no bar, no scroll (`scroll` and `progress` are ignored).
+   * For state only the client needs (a view mode, a zoom, a slider). Default:
+   * false. Precedence: the setter call, then the hook, then false.
+   */
+  shallow?: boolean;
   /**
    * When the new value equals the parser's default, drop the key from
    * the URL instead of writing `?page=1`. Default: true (recommended —
@@ -64,25 +72,38 @@ export function useQueryState<T>(
   options?: UseQueryStateOptions
 ): [T | null, (next: QueryStateUpdater<T>, opts?: UseQueryStateOptions) => void] {
   const { pathname, search } = useLocation();
-  const { navigate } = useNavigate();
+  const { navigate, shallow } = useNavigate();
+  const adapter = useRouterAdapter();
 
-  const value = useMemo<T | null>(() => {
-    const raw = new URLSearchParams(search).get(key);
-    if (raw === null) return parser.defaultValue ?? null;
-    const parsed = parser.parse(raw);
-    return parsed === null ? (parser.defaultValue ?? null) : parsed;
-  }, [search, key, parser]);
+  const parse = useCallback(
+    (qs: string): T | null => {
+      const raw = new URLSearchParams(qs).get(key);
+      if (raw === null) return parser.defaultValue ?? null;
+      const parsed = parser.parse(raw);
+      return parsed === null ? (parser.defaultValue ?? null) : parsed;
+    },
+    [key, parser]
+  );
+
+  const value = useMemo<T | null>(() => parse(search), [search, parse]);
 
   const setValue = useCallback(
     (next: QueryStateUpdater<T>, callOpts?: UseQueryStateOptions) => {
+      // Read the URL as it is now, not as this render saw it: two calls in one tick
+      // (or one before the re-render) must both land. The rendered `search` is the fallback on the server.
+      const live = typeof window === 'undefined' ? null : adapter.getLocation();
+      const currentSearch = live ? live.search : search;
+      const currentPathname = live ? live.pathname : pathname;
+      const current = live ? parse(currentSearch) : value;
+
       const resolved =
         typeof next === 'function'
           ? (next as (current: T) => T | null)(
-              (value ?? parser.defaultValue) as T
+              (current ?? parser.defaultValue) as T
             )
           : next;
 
-      const params = new URLSearchParams(search);
+      const params = new URLSearchParams(currentSearch);
       const clearOnDefault =
         callOpts?.clearOnDefault ?? options?.clearOnDefault ?? true;
 
@@ -98,14 +119,20 @@ export function useQueryState<T>(
       }
 
       const qs = params.toString();
-      const href = qs ? `${pathname}?${qs}` : pathname;
+      const href = qs ? `${currentPathname}?${qs}` : currentPathname;
+      const replace = callOpts?.replace ?? options?.replace ?? false;
+      if (callOpts?.shallow ?? options?.shallow ?? false) {
+        // The hash goes with the entry, as `pushState` of a bare path would drop it.
+        shallow(live?.hash ? `${href}${live.hash}` : href, { replace });
+        return;
+      }
       navigate(href, {
-        replace: callOpts?.replace ?? options?.replace ?? false,
+        replace,
         scroll: callOpts?.scroll ?? options?.scroll ?? false,
         progress: callOpts?.progress ?? options?.progress ?? false,
       });
     },
-    [pathname, search, key, parser, navigate, options, value]
+    [adapter, pathname, search, key, parser, parse, navigate, shallow, options, value]
   );
 
   return [value, setValue];

package/src/hooks/router/useRouter.ts

@@ -65,6 +65,7 @@ export function useRouter(): UseRouterReturn {
       // Navigation pass-through
       navigate: nav.navigate,
       navigateExternal: nav.navigateExternal,
+      shallow: nav.shallow,
       push: nav.push,
       replace: nav.replace,
       back: nav.back,