@djangocfg/ui-core 2.1.615 → 2.1.617

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.615",
+  "version": "2.1.617",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -46,6 +46,11 @@
       "import": "./src/hooks/index.ts",
       "require": "./src/hooks/index.ts"
     },
+    "./route-progress": {
+      "types": "./src/route-progress/index.ts",
+      "import": "./src/route-progress/index.ts",
+      "require": "./src/route-progress/index.ts"
+    },
     "./theme": {
       "types": "./src/theme/index.ts",
       "import": "./src/theme/index.ts",
@@ -133,8 +138,8 @@
     "check:docs": "node scripts/check-docs.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.615",
-    "@djangocfg/i18n": "^2.1.615",
+    "@djangocfg/api": "^2.1.617",
+    "@djangocfg/i18n": "^2.1.617",
     "consola": "^3.4.2",
     "lucide-react": "^1.68.0",
     "moment": "^2.30.1",
@@ -200,7 +205,6 @@
     "i18n-iso-countries": "^7.14.0",
     "input-otp": "1.5.0",
     "libphonenumber-js": "^1.13.15",
-    "nextjs-toploader": "^3.9.17",
     "react-day-picker": "10.0.2",
     "react-hotkeys-hook": "^5.3.3",
     "react-resizable-panels": "3.0.6",
@@ -210,10 +214,10 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.615",
-    "@djangocfg/eslint-config": "^2.1.615",
-    "@djangocfg/i18n": "^2.1.615",
-    "@djangocfg/typescript-config": "^2.1.615",
+    "@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/index.ts

@@ -68,9 +68,13 @@ export {
   useRouter,
   // useScrollToTop (covers the routes Next's own scroll handler skips)
   useScrollToTop,
+  // Per-page switches for the scroll jump and the loading bar
+  useNavigationBehavior,
 } from './router';
 export type {
   RouterAdapter,
+  RouterNavigateOptions,
+  NavigationBehavior,
   RouterAdapterProviderProps,
   RouterLocation,
   LocationSnapshot,

package/src/hooks/router/README.md

@@ -18,6 +18,7 @@ Framework-agnostic navigation primitives for `@djangocfg/ui-core`. Built on plai
 | `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). |
+| `useNavigationBehavior` | A page or section switches off the scroll jump and the top loading bar while it is mounted. See [Scroll and loading bar](#scroll-and-loading-bar). |
 | `parseAsString` / `parseAsInteger` / `parseAsFloat` / `parseAsBoolean` / `parseAsIsoDate` / `parseAsStringEnum` / `parseAsArrayOf` / `parseAsJson` | Parser builders for `useQueryState`. Each has `.withDefault(value)`. |
 
 ## Decomposition rationale
@@ -101,6 +102,35 @@ export function MyRouterAdapter({ children }: { children: React.ReactNode }) {
 
 **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.
 
+## Scroll and loading bar
+
+`push`/`replace` (and `navigate`) take `{ scroll?, progress? }`, and the Next adapter honours both:
+
+| Option | Absent | `true` | `false` |
+| --- | --- | --- | --- |
+| `scroll` | the page's setting, then `NextRouterAdapter defaultScroll`, then Next's own default | scroll to the top | keep the position |
+| `progress` | the bar shows only when the **pathname** changes; `?query` and `#hash` changes never show it | show it | do not show it |
+
+`useQueryState` passes `scroll: false` and `progress: false` by default (it only ever changes the query); both can be set on the hook or on a single `setValue` call.
+
+A page that navigates inside itself (filters, a board, threads) declares it once instead of on every call, and it also covers `<Link>` clicks and `useScrollToTop`:
+
+```tsx
+useNavigationBehavior({ scroll: false, progress: false }); // while this component is mounted
+```
+
+Later or nested entries win field by field; an explicit option on a call beats the page. `BaseApp progressBar={false}` removes the bar for the whole app; `progressBar={{ shouldShow: (from, to) => ... }}` replaces the default route rule. `<Link scroll={false}>` is still how a single link keeps Next's scroll.
+
+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.
@@ -119,7 +149,7 @@ 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.
+`scroll` and `progress` (both default `false`) are described in [Scroll and loading bar](#scroll-and-loading-bar). `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`).
 

package/src/hooks/router/adapter.tsx

@@ -52,17 +52,40 @@ export interface RouterLocation {
  * Pluggable navigation backend. Implementations must be SSR-safe
  * (mutations should no-op when `typeof window === 'undefined'`).
  */
+export interface RouterNavigateOptions {
+  /**
+   * Scroll to the top after the navigation. Absent: the adapter's own default
+   * (Next: its `scroll: true`). `false` keeps the position, e.g. for a filter.
+   */
+  scroll?: boolean;
+  /**
+   * Show the top loading bar. Absent: only when the pathname changes (a query or
+   * hash change is not a page transition). `true` forces it, `false` suppresses it.
+   * Adapters without a bar ignore it.
+   */
+  progress?: boolean;
+}
+
 export interface RouterAdapter {
   /** Push a new entry onto the history stack. */
-  push: (url: string) => void;
+  push: (url: string, opts?: RouterNavigateOptions) => void;
   /** Replace the current history entry. */
-  replace: (url: string) => void;
+  replace: (url: string, opts?: RouterNavigateOptions) => void;
   /** Go back one entry. */
   back: () => void;
   /** Go forward one entry. */
   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({
@@ -101,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

@@ -34,32 +34,27 @@
 
 import {
   forwardRef,
+  useEffect,
   useMemo,
+  useRef,
   type AnchorHTMLAttributes,
   type ComponentType,
   type ReactNode,
   type Ref,
 } from 'react';
-// Use the toploader-wrapped router so that EVERY programmatic
-// navigation through ui-core hooks (`useNavigate`, `useQueryState`,
-// `useRouter` from `@djangocfg/ui-core/hooks`) starts the
-// `nextjs-toploader` progress bar.
-//
-// Why not `next/navigation` directly: <NextTopLoader> only attaches a
-// document-level click listener for <a> tags and instruments
-// `history.pushState` to call `nprogress.done()` (NOT `.start()`). So
-// `router.push()` from `next/navigation` mutates history but never
-// starts the bar — only `<Link>` clicks do. The `nextjs-toploader/app`
-// entry exposes a thin wrapper around the same `useRouter` whose
-// `push`/`replace` call `nprogress.start()` first. Drop-in shape.
-import { useRouter as useNextRouter } from 'nextjs-toploader/app';
+import { usePathname, useRouter as useNextRouter } from 'next/navigation';
 import NextLink from 'next/link';
 
 import {
   RouterAdapterProvider,
   type RouterAdapter,
   type RouterLocation,
+  type RouterNavigateOptions,
+  writeUrlShallow,
 } from '../adapter';
+import { useRouteProgress } from '../../../route-progress';
+import { shouldStartProgress } from '../../../route-progress/provider/shouldStart';
+import { NAVIGATE_EVENT, patchHistoryOnce } from '../useLocation';
 import {
   LinkProvider,
   type LinkComponent,
@@ -72,6 +67,16 @@ const SSR_LOCATION: RouterLocation = Object.freeze({
   hash: '',
 });
 
+/** `url` resolved against the current page; `null` outside the browser or for an unparsable url. */
+function resolve(url: string): URL | null {
+  if (typeof window === 'undefined') return null;
+  try {
+    return new URL(url, window.location.href);
+  } catch {
+    return null;
+  }
+}
+
 export interface NextRouterAdapterProps {
   children: ReactNode;
   /**
@@ -87,19 +92,50 @@ export interface NextRouterAdapterProps {
  * through Next's App Router. Server components, loaders, and prefetch
  * keep working as if you used `next/navigation` directly.
  */
-export function NextRouterAdapter({
-  children,
-  defaultScroll,
-}: NextRouterAdapterProps) {
+export function NextRouterAdapter({ children, defaultScroll }: NextRouterAdapterProps) {
   const next = useNextRouter();
+  const pathname = usePathname();
+  // The top bar and the page switches live in `RouteProgressProvider` (BaseApp mounts it); without one this adapter shows no bar.
+  const progress = useRouteProgress();
+  const progressRef = useRef(progress);
+  progressRef.current = progress;
+
+  // Every committed navigation ends the bar: Next's `pushState`/`replaceState` on commit, or a new pathname.
+  useEffect(() => {
+    patchHistoryOnce();
+    const stop = () => progressRef.current?.engine.done();
+    window.addEventListener(NAVIGATE_EVENT, stop);
+    return () => window.removeEventListener(NAVIGATE_EVENT, stop);
+  }, []);
+  useEffect(() => {
+    progressRef.current?.engine.done();
+  }, [pathname]);
 
   const adapter = useMemo<RouterAdapter>(
-    () => ({
-      push(url) {
-        next.push(url, defaultScroll === undefined ? undefined : { scroll: defaultScroll });
+    () => {
+      // Priority for scroll: the call, then the page (`useNavigationBehavior`), then `defaultScroll`, then Next's own default.
+      const nextOptions = (opts?: RouterNavigateOptions) => {
+        const scroll = opts?.scroll ?? progressRef.current?.behavior.get().scroll ?? defaultScroll;
+        return scroll === undefined ? undefined : { scroll };
+      };
+      const startBar = (url: string, opts?: RouterNavigateOptions) => {
+        const to = resolve(url);
+        if (to && shouldStartProgress(progressRef.current, new URL(window.location.href), to, opts?.progress)) {
+          progressRef.current?.engine.start();
+        }
+      };
+      return {
+      push(url, opts) {
+        startBar(url, opts);
+        next.push(url, nextOptions(opts));
+      },
+      replace(url, opts) {
+        startBar(url, opts);
+        next.replace(url, nextOptions(opts));
       },
-      replace(url) {
-        next.replace(url, defaultScroll === undefined ? undefined : { scroll: defaultScroll });
+      // 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();
@@ -115,7 +151,8 @@ export function NextRouterAdapter({
           hash: window.location.hash,
         };
       },
-    }),
+      };
+    },
     [next, defaultScroll]
   );
 

package/src/hooks/router/index.ts

@@ -14,6 +14,7 @@ export {
 } from './adapter';
 export type {
   RouterAdapter,
+  RouterNavigateOptions,
   RouterAdapterProviderProps,
   RouterLocation,
 } from './adapter';
@@ -29,6 +30,10 @@ export {
 } from './useLocation';
 export type { LocationSnapshot } from './useLocation';
 
+// Per-page switches for the scroll jump and the loading bar live in ../../route-progress
+export { useNavigationBehavior } from '../../route-progress';
+export type { NavigationBehavior } from '../../route-progress';
+
 // useScrollToTop (fills the gaps in Next's own scroll restoration)
 export { useScrollToTop } from './useScrollToTop';
 export type { UseScrollToTopOptions } from './useScrollToTop';

package/src/hooks/router/useNavigate.ts

@@ -20,7 +20,7 @@
  */
 
 import { useCallback, useMemo } from 'react';
-import { useRouterAdapter } from './adapter';
+import { useRouterAdapter, type RouterNavigateOptions } from './adapter';
 
 export interface NavigateOptions {
   /** Use `replaceState` instead of `pushState`. Default: false. */
@@ -33,6 +33,11 @@ export interface NavigateOptions {
    * transitions where you want the user back at the masthead.
    */
   scroll?: boolean;
+  /**
+   * Show the top loading bar. Default: only when the pathname changes.
+   * `true` forces it, `false` suppresses it.
+   */
+  progress?: boolean;
 }
 
 export interface UseNavigateReturn {
@@ -47,10 +52,16 @@ 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) => void;
+  push: (url: string, opts?: RouterNavigateOptions) => void;
   /** Pass-through: adapter.replace */
-  replace: (url: string) => void;
+  replace: (url: string, opts?: RouterNavigateOptions) => void;
   /** Pass-through: adapter.back */
   back: () => void;
   /** Pass-through: adapter.forward */
@@ -68,10 +79,11 @@ export function useNavigate(): UseNavigateReturn {
     (href: string, opts?: NavigateOptions) => {
       const replace = opts?.replace ?? false;
       const scroll = opts?.scroll ?? false;
+      const adapterOpts = { scroll: opts?.scroll, progress: opts?.progress };
       if (replace) {
-        adapter.replace(href);
+        adapter.replace(href, adapterOpts);
       } else {
-        adapter.push(href);
+        adapter.push(href, adapterOpts);
       }
       if (scroll && typeof window !== 'undefined') {
         window.scrollTo(0, 0);
@@ -80,18 +92,31 @@ 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);
   }, []);
 
-  const push = useCallback((url: string) => adapter.push(url), [adapter]);
-  const replace = useCallback((url: string) => adapter.replace(url), [adapter]);
+  const push = useCallback((url: string, opts?: RouterNavigateOptions) => adapter.push(url, opts), [adapter]);
+  const replace = useCallback((url: string, opts?: RouterNavigateOptions) => adapter.replace(url, opts), [adapter]);
   const back = useCallback(() => adapter.back(), [adapter]);
   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';
@@ -29,6 +30,18 @@ export interface UseQueryStateOptions {
   replace?: boolean;
   /** Scroll to top after navigation. Default: false. */
   scroll?: boolean;
+  /**
+   * Show the top loading bar. Default: false: a query change is not a page
+   * 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 —
@@ -59,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;
 
@@ -93,13 +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,

package/src/hooks/router/useScrollToTop.ts

@@ -47,6 +47,7 @@
 
 import { useEffect, useRef } from 'react';
 
+import { useRouteProgress } from '../../route-progress';
 import { NAVIGATE_EVENT, patchHistoryOnce } from './useLocation';
 
 export interface UseScrollToTopOptions {
@@ -74,6 +75,10 @@ export function useScrollToTop({
    * restoration on a reload.
    */
   const lastPathRef = useRef<string | null>(null);
+  // The page's switches (`useNavigationBehavior`) live in the app's RouteProgressProvider.
+  const progress = useRouteProgress();
+  const progressRef = useRef(progress);
+  progressRef.current = progress;
 
   useEffect(() => {
     if (!enabled || typeof window === 'undefined') return;
@@ -97,6 +102,8 @@ export function useScrollToTop({
 
       // Query-only or state-only writes: the visitor stays where they are.
       if (!changedPath) return;
+      // The page asked to keep its position (`useNavigationBehavior`).
+      if (progressRef.current?.behavior.get().scroll === false) return;
       // The URL names an anchor; it has already said where to land.
       if (hash) return;
 

package/src/route-progress/NOTICE

@@ -0,0 +1,5 @@
+The progress model in engine/createProgressEngine.ts (start position, step size by band,
+the 0.994 cap, fill-then-fade on done) is derived from nprogress 0.2.0.
+
+nprogress, Copyright (c) 2013-2014 Rico Sta. Cruz. MIT License.
+https://github.com/rstacruz/nprogress

package/src/route-progress/README.md

@@ -0,0 +1,26 @@
+# route-progress
+
+The thin bar at the top of the window between pages, and the per-page switches for it and for the scroll jump. Our own code; the progress model comes from `nprogress` (see [NOTICE](NOTICE)). Plan and decisions: `frontend/@dev/planned/route-progress-module/PLAN.md`.
+
+Subpath: `@djangocfg/ui-core/route-progress`. `BaseApp` mounts the provider; apps normally only call `useNavigationBehavior`.
+
+| Folder | Job |
+|---|---|
+| `engine/` | the state machine: `start`, `set`, `inc`, `done`, `cancel`; no DOM, no React |
+| `view/` | `<RouteProgressBar>`: `scaleX` bar, tokens, reduced motion |
+| `triggers/` | which link clicks start the bar; page-hide and bfcache reset |
+| `behavior/` | the lease store behind `useNavigationBehavior` |
+| `provider/` | `RouteProgressProvider`, the context, and the one rule `shouldStartProgress` |
+
+## Who decides, in order
+1. the call's `progress` option (`push(url, { progress })`);
+2. the app switch (`BaseApp progressBar={false}` wins over everything);
+3. a mounted page's `useNavigationBehavior({ progress: false })`;
+4. the app's `shouldShow(from, to)`, if set;
+5. the default: the pathname changes (`?query` and `#hash` do not).
+
+## Styling
+CSS variables on any ancestor: `--route-progress-color` (default `--primary`), `--route-progress-height` (3px), `--route-progress-z` (1600). One anchor can opt out: `<a data-no-route-progress>`.
+
+## Adding a trigger
+A trigger is a function that calls `engine.start()` and returns its unsubscribe; add it to `triggers/attach.ts`. Ending a run is the router wiring's job (`NextRouterAdapter` calls `engine.done()` on commit); the engine's ceiling ends a run nobody finished.

package/src/route-progress/behavior/store.ts

@@ -0,0 +1,58 @@
+/**
+ * What the app currently allows navigation to do: the scroll jump to the top and the top
+ * loading bar. Pages and sections hold a lease for as long as they are mounted; the latest
+ * lease that sets a field decides it. One store per app, created by the provider: no global.
+ */
+
+export interface NavigationBehavior {
+  /** `false`: do not scroll to the top on navigation. */
+  scroll?: boolean;
+  /** `false`: do not show the top loading bar. */
+  progress?: boolean;
+}
+
+export interface NavigationBehaviorStore {
+  /** The effective behaviour. Same object until a lease changes. */
+  get(): NavigationBehavior;
+  subscribe(listener: () => void): () => void;
+  /** Take a lease; returns the function that gives it back. */
+  acquire(lease: NavigationBehavior): () => void;
+}
+
+export function createNavigationBehaviorStore(): NavigationBehaviorStore {
+  const leases: NavigationBehavior[] = [];
+  const listeners = new Set<() => void>();
+  let current: NavigationBehavior = {};
+
+  const recompute = () => {
+    const next: NavigationBehavior = {};
+    for (const l of leases) {
+      if (l.scroll !== undefined) next.scroll = l.scroll;
+      if (l.progress !== undefined) next.progress = l.progress;
+    }
+    if (next.scroll === current.scroll && next.progress === current.progress) return;
+    current = next;
+    listeners.forEach((fn) => fn());
+  };
+
+  return {
+    get: () => current,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    acquire(lease) {
+      const own = { ...lease };
+      leases.push(own);
+      recompute();
+      return () => {
+        const i = leases.indexOf(own);
+        if (i === -1) return;
+        leases.splice(i, 1);
+        recompute();
+      };
+    },
+  };
+}

package/src/route-progress/behavior/useNavigationBehavior.ts

@@ -0,0 +1,23 @@
+'use client';
+
+import { useEffect } from 'react';
+
+import { useRouteProgress } from '../provider/context';
+import type { NavigationBehavior } from './store';
+
+/**
+ * Declare navigation behaviour for as long as the calling component is mounted:
+ *
+ * ```tsx
+ * function Board() {
+ *   useNavigationBehavior({ scroll: false, progress: false });
+ * }
+ * ```
+ *
+ * Needs a `RouteProgressProvider` above (BaseApp mounts one); without it this does nothing.
+ */
+export function useNavigationBehavior({ scroll, progress }: NavigationBehavior): void {
+  const ctx = useRouteProgress();
+  const behavior = ctx?.behavior;
+  useEffect(() => behavior?.acquire({ scroll, progress }), [behavior, scroll, progress]);
+}

package/src/route-progress/engine/createProgressEngine.ts

@@ -0,0 +1,87 @@
+/**
+ * The progress state machine, free of DOM and React. The numbers (start jump, step size by
+ * band, the 0.994 cap) follow the model of `nprogress` 0.2.0 (MIT, see ../NOTICE); the code
+ * is ours: one timer for trickling, one for the ceiling, one for the fade-out.
+ */
+
+import type { ProgressEngine, ProgressEngineOptions, ProgressState } from './types';
+
+const IDLE: ProgressState = Object.freeze({ phase: 'idle', value: 0 });
+const CAP = 0.994;
+
+/** Step size by how far the bar already is. */
+function stepFor(value: number): number {
+  if (value < 0.2) return 0.1;
+  if (value < 0.5) return 0.04;
+  if (value < 0.8) return 0.02;
+  if (value < 0.99) return 0.005;
+  return 0;
+}
+
+export function createProgressEngine(options: ProgressEngineOptions = {}): ProgressEngine {
+  const { minimum = 0.08, trickleMs = 200, maxMs = 15000, finishMs = 400 } = options;
+
+  let state: ProgressState = IDLE;
+  const listeners = new Set<() => void>();
+  let trickleTimer: ReturnType<typeof setInterval> | undefined;
+  let ceilingTimer: ReturnType<typeof setTimeout> | undefined;
+  let finishTimer: ReturnType<typeof setTimeout> | undefined;
+
+  const emit = (next: ProgressState) => {
+    state = next;
+    listeners.forEach((l) => l());
+  };
+
+  const clearTimers = () => {
+    clearInterval(trickleTimer);
+    clearTimeout(ceilingTimer);
+    clearTimeout(finishTimer);
+    trickleTimer = ceilingTimer = finishTimer = undefined;
+  };
+
+  const set = (value: number) => {
+    if (state.phase !== 'running') return;
+    const next = Math.min(CAP, Math.max(0, value));
+    if (next !== state.value) emit({ phase: 'running', value: next });
+  };
+
+  const inc = (amount?: number) => {
+    if (state.phase !== 'running') return;
+    set(state.value + (amount ?? stepFor(state.value)));
+  };
+
+  const done = () => {
+    if (state.phase !== 'running') return;
+    clearTimers();
+    emit({ phase: 'finishing', value: 1 });
+    finishTimer = setTimeout(() => {
+      finishTimer = undefined;
+      emit(IDLE);
+    }, finishMs);
+  };
+
+  return {
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    start() {
+      if (state.phase === 'running') return;
+      clearTimers();
+      emit({ phase: 'running', value: minimum });
+      trickleTimer = setInterval(() => inc(), trickleMs);
+      ceilingTimer = setTimeout(done, maxMs);
+    },
+    set,
+    inc,
+    done,
+    cancel() {
+      if (state === IDLE) return;
+      clearTimers();
+      emit(IDLE);
+    },
+  };
+}

package/src/route-progress/engine/types.ts

@@ -0,0 +1,34 @@
+export type ProgressPhase = 'idle' | 'running' | 'finishing';
+
+/** Immutable snapshot: a new object on every change, so it can feed `useSyncExternalStore`. */
+export interface ProgressState {
+  phase: ProgressPhase;
+  /** 0..1. The bar's width while `running`; 1 while `finishing`; 0 when `idle`. */
+  value: number;
+}
+
+export interface ProgressEngineOptions {
+  /** Where the bar jumps to on `start()`. Default 0.08. */
+  minimum?: number;
+  /** Delay between automatic steps, ms. Default 200. */
+  trickleMs?: number;
+  /** Ceiling: a run that was never finished ends by itself after this many ms. Default 15000. */
+  maxMs?: number;
+  /** How long the full bar stays before it goes idle (the fade-out), ms. Default 400. */
+  finishMs?: number;
+}
+
+export interface ProgressEngine {
+  getState(): ProgressState;
+  subscribe(listener: () => void): () => void;
+  /** Begin a run. Starting while running keeps the current value. */
+  start(): void;
+  /** Jump to `value` (clamped to 0..0.994) while running. */
+  set(value: number): void;
+  /** Move forward by `amount`, or by the step for the current band. */
+  inc(amount?: number): void;
+  /** Finish: fill the bar, then go idle after `finishMs`. No-op when idle. */
+  done(): void;
+  /** Drop the run at once, without the fill. */
+  cancel(): void;
+}

package/src/route-progress/index.ts

@@ -0,0 +1,16 @@
+// Route progress: the thin top bar between pages and the per-page navigation switches.
+// Engine (state machine) -> view (bar) -> triggers (link clicks) -> provider (one per app).
+
+export { RouteProgressProvider } from './provider/RouteProgressProvider';
+export type { RouteProgressProviderProps } from './provider/RouteProgressProvider';
+export { useRouteProgress } from './provider/context';
+export type { RouteProgressContextValue } from './provider/context';
+export { shouldStartProgress } from './provider/shouldStart';
+
+export { useNavigationBehavior } from './behavior/useNavigationBehavior';
+export type { NavigationBehavior } from './behavior/store';
+
+export { RouteProgressBar } from './view/RouteProgressBar';
+export { createProgressEngine } from './engine/createProgressEngine';
+export type { ProgressEngine, ProgressEngineOptions, ProgressState } from './engine/types';
+export { NO_PROGRESS_ATTR } from './triggers/linkClick';

package/src/route-progress/provider/RouteProgressProvider.tsx

@@ -0,0 +1,74 @@
+'use client';
+
+import { useEffect, useMemo, useRef, type ReactNode } from 'react';
+
+import { createNavigationBehaviorStore } from '../behavior/store';
+import { createProgressEngine } from '../engine/createProgressEngine';
+import type { ProgressEngineOptions } from '../engine/types';
+import { attachRouteProgressTriggers } from '../triggers/attach';
+import { RouteProgressBar } from '../view/RouteProgressBar';
+import { RouteProgressContext, type RouteProgressContextValue } from './context';
+import { shouldStartProgress } from './shouldStart';
+
+export interface RouteProgressProviderProps extends ProgressEngineOptions {
+  children: ReactNode;
+  /** `false` turns the bar off for the whole app. Default true. */
+  enabled?: boolean;
+  /**
+   * Route rule for the whole app, replacing the default "the pathname changes".
+   * A page's `useNavigationBehavior({ progress: false })` and a call's `progress` option still win.
+   */
+  shouldShow?: (from: URL, to: URL) => boolean;
+  /** CSS colour of the bar. */
+  color?: string;
+  /** Height of the bar in px. */
+  height?: number;
+}
+
+/**
+ * One progress engine and one behaviour store for the app. Mounts the bar and the link-click
+ * triggers. The router wiring (`NextRouterAdapter`) starts it for programmatic navigation and
+ * ends every run when the navigation commits.
+ */
+export function RouteProgressProvider({
+  children,
+  enabled = true,
+  shouldShow,
+  color,
+  height,
+  ...engineOptions
+}: RouteProgressProviderProps) {
+  const { minimum, trickleMs, maxMs, finishMs } = engineOptions;
+  // One instance per mount; the options only matter the first time.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const engine = useMemo(() => createProgressEngine({ minimum, trickleMs, maxMs, finishMs }), []);
+  const behavior = useMemo(createNavigationBehaviorStore, []);
+
+  const value = useMemo<RouteProgressContextValue>(
+    () => ({ engine, behavior, enabled, shouldShow }),
+    [engine, behavior, enabled, shouldShow],
+  );
+
+  // The triggers read the latest value, so an inline `shouldShow` never re-attaches them (which would cancel a running bar).
+  const latest = useRef(value);
+  latest.current = value;
+
+  useEffect(() => {
+    if (!enabled) return;
+    const detach = attachRouteProgressTriggers({
+      engine,
+      shouldStart: (from, to) => shouldStartProgress(latest.current, from, to),
+    });
+    return () => {
+      detach();
+      engine.cancel();
+    };
+  }, [engine, enabled]);
+
+  return (
+    <RouteProgressContext.Provider value={value}>
+      {children}
+      {enabled && <RouteProgressBar engine={engine} color={color} height={height} />}
+    </RouteProgressContext.Provider>
+  );
+}

package/src/route-progress/provider/context.ts

@@ -0,0 +1,22 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+import type { NavigationBehaviorStore } from '../behavior/store';
+import type { ProgressEngine } from '../engine/types';
+
+export interface RouteProgressContextValue {
+  engine: ProgressEngine;
+  behavior: NavigationBehaviorStore;
+  /** `false`: the app turned the bar off; nothing starts it. */
+  enabled: boolean;
+  /** App-level route rule, see `RouteProgressProvider`. */
+  shouldShow?: (from: URL, to: URL) => boolean;
+}
+
+export const RouteProgressContext = createContext<RouteProgressContextValue | null>(null);
+
+/** The app's engine and behaviour store, or `null` outside a `RouteProgressProvider`. */
+export function useRouteProgress(): RouteProgressContextValue | null {
+  return useContext(RouteProgressContext);
+}

package/src/route-progress/provider/shouldStart.ts

@@ -0,0 +1,19 @@
+import type { RouteProgressContextValue } from './context';
+
+/**
+ * Whether a navigation from `from` to `to` shows the bar. In order:
+ * the call's explicit option; the app switch; a mounted page that said `progress: false`;
+ * the app's `shouldShow`; the default, "the pathname changes" (query and hash do not).
+ */
+export function shouldStartProgress(
+  ctx: RouteProgressContextValue | null,
+  from: URL,
+  to: URL,
+  explicit?: boolean,
+): boolean {
+  if (!ctx || !ctx.enabled) return false;
+  if (explicit !== undefined) return explicit;
+  if (ctx.behavior.get().progress === false) return false;
+  if (ctx.shouldShow) return ctx.shouldShow(from, to);
+  return from.pathname !== to.pathname;
+}

package/src/route-progress/triggers/attach.ts

@@ -0,0 +1,30 @@
+import type { ProgressEngine } from '../engine/types';
+import { clickDestination } from './linkClick';
+
+export interface TriggerOptions {
+  engine: ProgressEngine;
+  /** Whether a navigation from `from` to `to` shows the bar. */
+  shouldStart: (from: URL, to: URL) => boolean;
+}
+
+/**
+ * Start the bar on link clicks; drop it on `pagehide` and when a page comes back from the
+ * back-forward cache, so a frozen bar is never restored. Completion is not decided here:
+ * the router wiring calls `engine.done()` when the navigation commits.
+ */
+export function attachRouteProgressTriggers({ engine, shouldStart }: TriggerOptions): () => void {
+  const onClick = (event: MouseEvent) => {
+    const to = clickDestination(event, window.location.href);
+    if (to && shouldStart(new URL(window.location.href), to)) engine.start();
+  };
+  const reset = () => engine.cancel();
+
+  document.addEventListener('click', onClick);
+  window.addEventListener('pagehide', reset);
+  window.addEventListener('pageshow', reset);
+  return () => {
+    document.removeEventListener('click', onClick);
+    window.removeEventListener('pagehide', reset);
+    window.removeEventListener('pageshow', reset);
+  };
+}

package/src/route-progress/triggers/linkClick.ts

@@ -0,0 +1,42 @@
+/**
+ * Which link clicks are page navigations the bar should react to. Pure: it reads the event,
+ * the anchor and the base URL, and answers with the destination or `null`.
+ */
+
+/** The parts of an anchor we read; a real `HTMLAnchorElement` fits. */
+export interface AnchorLike {
+  href: string;
+  target: string;
+  hasAttribute(name: string): boolean;
+}
+
+export interface ClickLike {
+  button: number;
+  metaKey: boolean;
+  ctrlKey: boolean;
+  shiftKey: boolean;
+  altKey: boolean;
+  target: { closest?(selector: string): AnchorLike | null } | EventTarget | null;
+}
+
+/** Opt-out on one anchor: `<a data-no-route-progress>`. */
+export const NO_PROGRESS_ATTR = 'data-no-route-progress';
+
+/** The URL a plain left click on a same-origin link goes to, else `null`. */
+export function clickDestination(event: ClickLike, baseHref: string): URL | null {
+  if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return null;
+  const el = event.target as { closest?(selector: string): AnchorLike | null } | null;
+  const anchor = el && typeof el.closest === 'function' ? el.closest('a[href]') : null;
+  if (!anchor || typeof anchor.href !== 'string') return null;
+  if (anchor.target && anchor.target !== '_self') return null;
+  if (anchor.hasAttribute('download') || anchor.hasAttribute(NO_PROGRESS_ATTR)) return null;
+  let url: URL;
+  try {
+    url = new URL(anchor.href, baseHref);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+  if (url.origin !== new URL(baseHref).origin) return null;
+  return url;
+}

package/src/route-progress/view/RouteProgressBar.tsx

@@ -0,0 +1,62 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+
+import type { ProgressEngine } from '../engine/types';
+import { useReducedMotion } from './useReducedMotion';
+
+export interface RouteProgressBarProps {
+  engine: ProgressEngine;
+  /** CSS colour. Default: the `--route-progress-color` variable, else `--primary`. */
+  color?: string;
+  /** Height in px. Default 3. */
+  height?: number;
+}
+
+const serverState = { phase: 'idle', value: 0 } as const;
+
+/**
+ * The thin bar at the top of the window. Decoration only (`aria-hidden`): the page owns its
+ * own busy semantics. Styling hooks: `--route-progress-color`, `--route-progress-height`,
+ * `--route-progress-z`. Renders nothing while idle and on the server.
+ */
+export function RouteProgressBar({ engine, color, height = 3 }: RouteProgressBarProps) {
+  const state = useSyncExternalStore(engine.subscribe, engine.getState, () => serverState);
+  const reduced = useReducedMotion();
+  if (state.phase === 'idle') return null;
+
+  const finishing = state.phase === 'finishing';
+  const fill = reduced ? 'none' : 'transform 200ms ease';
+  const fade = reduced ? 'opacity 150ms linear' : 'opacity 300ms ease 100ms';
+  const bar = color ?? 'var(--route-progress-color, var(--primary))';
+
+  return (
+    <div
+      aria-hidden
+      data-route-progress={state.phase}
+      style={{
+        position: 'fixed',
+        top: 0,
+        left: 0,
+        right: 0,
+        height: `var(--route-progress-height, ${height}px)`,
+        zIndex: 'var(--route-progress-z, 1600)' as unknown as number,
+        pointerEvents: 'none',
+        opacity: finishing ? 0 : 1,
+        transition: fade,
+      }}
+    >
+      <div
+        style={{
+          position: 'absolute',
+          inset: 0,
+          background: bar,
+          transformOrigin: 'left center',
+          transform: `scaleX(${state.value})`,
+          transition: fill,
+          boxShadow: reduced ? 'none' : `0 0 10px ${bar}, 0 0 5px ${bar}`,
+        }}
+      />
+    </div>
+  );
+}

package/src/route-progress/view/useReducedMotion.ts

@@ -0,0 +1,16 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/** `prefers-reduced-motion: reduce`, false on the server and until mounted. */
+export function useReducedMotion(): boolean {
+  const [reduced, setReduced] = useState(false);
+  useEffect(() => {
+    const mq = window.matchMedia('(prefers-reduced-motion: reduce)');
+    setReduced(mq.matches);
+    const on = (e: MediaQueryListEvent) => setReduced(e.matches);
+    mq.addEventListener('change', on);
+    return () => mq.removeEventListener('change', on);
+  }, []);
+  return reduced;
+}