@djangocfg/ui-core 2.1.560 → 2.1.561

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.560",
+  "version": "2.1.561",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -130,7 +130,7 @@
     "check:contrast": "node scripts/check-preset-contrast.mjs"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.560",
+    "@djangocfg/i18n": "^2.1.561",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -206,9 +206,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/eslint-config": "^2.1.560",
-    "@djangocfg/i18n": "^2.1.560",
-    "@djangocfg/typescript-config": "^2.1.560",
+    "@djangocfg/eslint-config": "^2.1.561",
+    "@djangocfg/i18n": "^2.1.561",
+    "@djangocfg/typescript-config": "^2.1.561",
     "@storybook/react-vite": "^10.5.0",
     "@types/node": "^24.13.3",
     "@types/react": "19.2.15",

package/src/hooks/index.ts

@@ -66,6 +66,8 @@ export {
   parseAsJson,
   // useRouter (composite facade)
   useRouter,
+  // useScrollToTop (covers the routes Next's own scroll handler skips)
+  useScrollToTop,
 } from './router';
 export type {
   RouterAdapter,
@@ -93,4 +95,5 @@ export type {
   QueryParser,
   QueryParserBuilder,
   UseRouterReturn,
+  UseScrollToTopOptions,
 } from './router';

package/src/hooks/router/index.ts

@@ -22,12 +22,17 @@ export type {
 export {
   useLocation,
   useLocationProperty,
+  patchHistoryOnce,
   NAVIGATE_EVENT,
   PUSH_STATE_EVENT,
   REPLACE_STATE_EVENT,
 } from './useLocation';
 export type { LocationSnapshot } from './useLocation';
 
+// useScrollToTop (fills the gaps in Next's own scroll restoration)
+export { useScrollToTop } from './useScrollToTop';
+export type { UseScrollToTopOptions } from './useScrollToTop';
+
 // useNavigate
 export { useNavigate } from './useNavigate';
 export type { NavigateOptions, UseNavigateReturn } from './useNavigate';

package/src/hooks/router/useLocation.ts

@@ -54,7 +54,16 @@ const SSR_SNAPSHOT: LocationSnapshot = Object.freeze({
 // (us or them) has installed a patch, the marker stays until full reload.
 const PATCH_KEY = Symbol.for('djc.router.historyPatched');
 
-function patchHistoryOnce(): void {
+/**
+ * Installs the `pushState`/`replaceState` patch that makes SPA navigations
+ * observable, exactly once per document.
+ *
+ * Exported because `useLocation` is no longer the only subscriber: a hook may
+ * listen for `NAVIGATE_EVENT` without reading the location through
+ * `useSyncExternalStore` (see `useScrollToTop`), and without this call it
+ * would subscribe to an event nothing dispatches — silently doing nothing.
+ */
+export function patchHistoryOnce(): void {
   if (typeof window === 'undefined') return;
   const w = window as Window & { [PATCH_KEY]?: true };
   if (w[PATCH_KEY]) return;

package/src/hooks/router/useScrollToTop.ts

@@ -0,0 +1,120 @@
+'use client';
+
+/**
+ * useScrollToTop — land at the top of the page after a forward navigation.
+ *
+ * WHY THIS EXISTS AT ALL — Next.js App Router already scrolls, sometimes
+ *
+ * `layout-router.tsx` walks the navigated segment looking for an element to
+ * scroll to, and **gives up silently** in two cases that are ordinary in our
+ * apps:
+ *
+ *   1. It takes the segment's first DOM node and skips it when the node is
+ *      `position: sticky|fixed` OR when `getBoundingClientRect()` is all
+ *      zeroes — then moves to `nextElementSibling`, and `return`s outright
+ *      when there is none. A page whose root is `display: contents` (a width
+ *      wrapper), or whose first child renders `null`, `<script type=
+ *      "application/ld+json">`, or any other zero-box node, therefore gets no
+ *      scroll at all.
+ *   2. Having found a node, it exits early when that node's top edge is
+ *      ALREADY within the viewport. Land mid-page on a long route whose next
+ *      route starts with a tall block, and the check passes while the visitor
+ *      is looking at the middle of the new page.
+ *
+ * Both are position-dependent, which is why the bug reads as intermittent:
+ * clicking from the top of a page (what an automated run usually does) hits
+ * neither branch, so the symptom only shows up when a person scrolls first.
+ *
+ * WHAT IT DELIBERATELY DOES NOT DO
+ *
+ * - **Back/forward are left alone.** The browser restores the previous scroll
+ *   position on a `popstate`, and overriding that is a worse bug than the one
+ *   being fixed. Only `pushState`/`replaceState` navigations scroll.
+ * - **`#hash` links are left alone.** A URL naming an anchor has already said
+ *   where it wants to land.
+ * - **Query-only changes are left alone.** Filters, pagination and tab state
+ *   write the query string; yanking the visitor to the top as they tick a
+ *   checkbox is the complaint this hook would otherwise cause. Only a
+ *   `pathname` change scrolls.
+ *
+ * It is idempotent with Next's own handler: when Next succeeds we are already
+ * at the top and the write is a no-op.
+ *
+ * @example
+ *   // Once, at the app root — `BaseApp` already does this for Next.js hosts.
+ *   useScrollToTop();
+ */
+
+import { useEffect, useRef } from 'react';
+
+import { NAVIGATE_EVENT, patchHistoryOnce } from './useLocation';
+
+export interface UseScrollToTopOptions {
+  /** Turn the behaviour off without unmounting the host. Default: true. */
+  enabled?: boolean;
+  /**
+   * Scroll animation. Default `'auto'` (instant), matching a hard navigation.
+   * `'smooth'` animates a full page height on every route change, which reads
+   * as lag rather than polish.
+   */
+  behavior?: ScrollBehavior;
+}
+
+/**
+ * Scrolls the window to the top after each forward navigation to a new path.
+ * Mount ONCE per app — a second mount just writes `scrollTo(0, 0)` twice.
+ */
+export function useScrollToTop({
+  enabled = true,
+  behavior = 'auto',
+}: UseScrollToTopOptions = {}): void {
+  /**
+   * The path we last saw. Seeded on mount rather than from `''`, so the first
+   * paint does not count as a navigation — that would fight the browser's own
+   * restoration on a reload.
+   */
+  const lastPathRef = useRef<string | null>(null);
+
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return;
+
+    // `pushState`/`replaceState` do not emit an event on their own. Without
+    // this the listener below is subscribed to something nothing dispatches.
+    patchHistoryOnce();
+    lastPathRef.current = window.location.pathname;
+
+    /*
+     * NAVIGATE_EVENT only, and that is what keeps back/forward working: the
+     * patch in `useLocation` dispatches it from `pushState`/`replaceState`
+     * exclusively, so a `popstate` never reaches this handler and the
+     * browser's restored position is never overwritten. Subscribing to
+     * `popstate` here — or to `hashchange` — would undo exactly that.
+     */
+    const onNavigate = () => {
+      const { pathname, hash } = window.location;
+      const changedPath = pathname !== lastPathRef.current;
+      lastPathRef.current = pathname;
+
+      // Query-only or state-only writes: the visitor stays where they are.
+      if (!changedPath) return;
+      // The URL names an anchor; it has already said where to land.
+      if (hash) return;
+
+      /*
+       * Deferred by one frame, and this is load-bearing. Our navigate event
+       * fires from a microtask right after `pushState`, while the destination
+       * is still the OLD document — React has not committed the new segment
+       * yet. Scrolling then is correct but immediately undone: Next's own
+       * handler runs on the commit that follows and may scroll back down to
+       * an element it found mid-page. Running after paint means we write
+       * last, over a document whose real height is known.
+       */
+      requestAnimationFrame(() => {
+        window.scrollTo({ top: 0, left: 0, behavior });
+      });
+    };
+
+    window.addEventListener(NAVIGATE_EVENT, onNavigate);
+    return () => window.removeEventListener(NAVIGATE_EVENT, onNavigate);
+  }, [enabled, behavior]);
+}