@djangocfg/layouts 2.1.514 → 2.1.516

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.514",
+  "version": "2.1.516",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -89,12 +89,12 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/analytics": "^2.1.514",
-    "@djangocfg/api": "^2.1.514",
-    "@djangocfg/centrifugo": "^2.1.514",
-    "@djangocfg/devtools": "^2.1.514",
-    "@djangocfg/i18n": "^2.1.514",
-    "@djangocfg/ui-core": "^2.1.514",
+    "@djangocfg/analytics": "^2.1.516",
+    "@djangocfg/api": "^2.1.516",
+    "@djangocfg/centrifugo": "^2.1.516",
+    "@djangocfg/devtools": "^2.1.516",
+    "@djangocfg/i18n": "^2.1.516",
+    "@djangocfg/ui-core": "^2.1.516",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
@@ -124,14 +124,14 @@
     "uuid": "^11.1.1"
   },
   "devDependencies": {
-    "@djangocfg/analytics": "^2.1.514",
-    "@djangocfg/api": "^2.1.514",
-    "@djangocfg/centrifugo": "^2.1.514",
-    "@djangocfg/devtools": "^2.1.514",
-    "@djangocfg/i18n": "^2.1.514",
-    "@djangocfg/typescript-config": "^2.1.514",
-    "@djangocfg/ui-core": "^2.1.514",
-    "@djangocfg/ui-tools": "^2.1.514",
+    "@djangocfg/analytics": "^2.1.516",
+    "@djangocfg/api": "^2.1.516",
+    "@djangocfg/centrifugo": "^2.1.516",
+    "@djangocfg/devtools": "^2.1.516",
+    "@djangocfg/i18n": "^2.1.516",
+    "@djangocfg/typescript-config": "^2.1.516",
+    "@djangocfg/ui-core": "^2.1.516",
+    "@djangocfg/ui-tools": "^2.1.516",
     "@types/node": "^25.9.5",
     "@types/react": "19.2.15",
     "@types/react-dom": "19.2.3",

package/src/layouts/PublicLayout/hooks/useNavbarScroll.ts

@@ -2,6 +2,8 @@
 
 import { useEffect, useRef, useState } from 'react';
 
+import { useScroll } from '@djangocfg/ui-core/hooks';
+
 export interface UseNavbarScrollOptions {
   /** Slide navbar up on scroll-down, back on scroll-up. @default false */
   hideNavOnScroll?: boolean;
@@ -18,44 +20,129 @@ export interface UseNavbarScrollReturn {
   scrolled: boolean;
 }
 
+/**
+ * How much accumulated movement in one direction it takes to flip the navbar.
+ *
+ * The whole point: react to *intent*, not to every pixel. A raw
+ * `direction === 'down' → hide` flickers on a trackpad's jittery micro-scrolls
+ * and on Safari's momentum tail, where the delta's sign wobbles frame to frame.
+ * We integrate movement instead and only commit once it clears this gate, then
+ * reset — so one deliberate flick hides, but noise around zero does nothing.
+ */
+const DIRECTION_COMMIT_PX = 8;
+
+/**
+ * Navbar scroll behaviour, built on ui-core's shared `useScroll` store.
+ *
+ * We deliberately do NOT attach our own scroll listener: `useScroll` already
+ * runs a single rAF-throttled, `useSyncExternalStore`-backed listener per
+ * target for the whole page (its own JSDoc points at this hook as the intended
+ * consumer — "for cumulative direction, build on top of this"). Here we add the
+ * navbar-specific *policy* on top of that raw position:
+ *
+ *   - a commit threshold so micro-scroll / momentum jitter can't flip the bar
+ *   - overscroll clamping so Safari rubber-banding at the edges doesn't twitch
+ *   - "always visible near the top" and "don't hide if there's nothing to
+ *     reclaim"
+ *   - `prefers-reduced-motion` opt-out of the hide (the slide, not the fade)
+ *
+ * All of that lives in refs and only touches React state when the derived
+ * boolean actually flips, so a page of scrolling costs at most a couple of
+ * renders.
+ */
 export function useNavbarScroll(options: UseNavbarScrollOptions = {}): UseNavbarScrollReturn {
   const { hideNavOnScroll = false, transparent = false, transparentThreshold = 40 } = options;
 
+  const active = hideNavOnScroll || transparent;
+  // Subscribe to the shared store only when the feature is on. The `y` this
+  // returns is already rAF-coalesced; we run cheap arithmetic on each change.
+  const { y } = useScroll(active ? undefined : NEVER_TARGET);
+
   const [hidden, setHidden] = useState(false);
   const [scrolled, setScrolled] = useState(false);
-  const lastScrollY = useRef(0);
+
+  // Cumulative-direction state — refs so integrating never forces a render.
+  const lastY = useRef(0);
+  const accum = useRef(0);
+  const hiddenRef = useRef(false);
+  const scrolledRef = useRef(false);
 
   useEffect(() => {
-    if (!hideNavOnScroll && !transparent) {
+    if (!active) {
+      // Feature off → make sure we don't leave the bar stuck hidden/opaque.
+      hiddenRef.current = false;
+      scrolledRef.current = false;
+      accum.current = 0;
       setHidden(false);
       setScrolled(false);
       return;
     }
 
-    const handleScroll = () => {
-      const currentY = window.scrollY;
-      const delta = currentY - lastScrollY.current;
+    // Respect the user's motion preference: if they've asked for reduced
+    // motion, never yank the bar out of view — it can be disorienting. The
+    // transparency fade (opacity, not a translate) is still fine.
+    const prefersReducedMotion =
+      typeof window.matchMedia === 'function' &&
+      window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+    const hideEnabled = hideNavOnScroll && !prefersReducedMotion;
 
-      if (transparent) {
-        setScrolled(currentY >= transparentThreshold);
+    // iOS Safari rubber-banding reports negative scrollY at the top and values
+    // past maxScroll at the bottom while the page bounces back; feeding those
+    // into the integrator makes the bar twitch on every overscroll pull.
+    const doc = document.documentElement;
+    const maxScroll = Math.max(0, doc.scrollHeight - window.innerHeight);
+    const clampedY = Math.min(Math.max(0, y), maxScroll);
+
+    if (transparent) {
+      const next = clampedY >= transparentThreshold;
+      if (scrolledRef.current !== next) {
+        scrolledRef.current = next;
+        setScrolled(next);
       }
+    }
 
-      if (hideNavOnScroll) {
-        if (currentY > transparentThreshold) {
-          if (delta > 0) setHidden(true);
-          else if (delta < 0) setHidden(false);
-        } else {
+    if (hideEnabled) {
+      // Near the top there's nowhere to hide *to*, and the header is usually
+      // part of the hero — always show. Same when the page can't scroll a full
+      // viewport (nothing to reclaim by hiding).
+      if (clampedY <= transparentThreshold || maxScroll <= 0) {
+        accum.current = 0;
+        if (hiddenRef.current) {
+          hiddenRef.current = false;
           setHidden(false);
         }
-      }
+      } else {
+        const delta = clampedY - lastY.current;
+        // Reset the integrator whenever direction reverses, so a flick the
+        // other way takes full effect immediately instead of first paying off
+        // the debt built up going the previous way.
+        if ((delta > 0 && accum.current < 0) || (delta < 0 && accum.current > 0)) {
+          accum.current = 0;
+        }
+        accum.current += delta;
 
-      lastScrollY.current = currentY;
-    };
+        if (accum.current >= DIRECTION_COMMIT_PX && !hiddenRef.current) {
+          hiddenRef.current = true;
+          setHidden(true);
+          accum.current = 0;
+        } else if (accum.current <= -DIRECTION_COMMIT_PX && hiddenRef.current) {
+          hiddenRef.current = false;
+          setHidden(false);
+          accum.current = 0;
+        }
+      }
+    }
 
-    handleScroll();
-    window.addEventListener('scroll', handleScroll, { passive: true });
-    return () => window.removeEventListener('scroll', handleScroll);
-  }, [hideNavOnScroll, transparent, transparentThreshold]);
+    lastY.current = clampedY;
+  }, [y, active, hideNavOnScroll, transparent, transparentThreshold]);
 
   return { hidden, scrolled };
 }
+
+/**
+ * A stable ref target whose `.current` is always null, so `useScroll` resolves
+ * to "no target" and never subscribes when the feature is off. Module-level so
+ * its identity is stable across renders (a fresh object each render would make
+ * `useScroll`'s `useCallback` deps churn).
+ */
+const NEVER_TARGET = { current: null } as const;

package/src/layouts/PublicLayout/hooks/useNavbarViewportVars.ts

@@ -3,9 +3,22 @@
 import { type RefObject, useEffect } from 'react';
 
 /**
- * Tracks the bottom edge of the navbar outer element and writes CSS vars:
- *   --public-navbar-mobile-drawer-top
+ * Measures navbar geometry into CSS custom properties on `:root` so the rest of
+ * the page can lay itself out against the real bar — without prop-drilling a
+ * pixel number through React or hardcoding a magic height.
+ *
+ * Writes:
+ *   --public-navbar-height              the bar's own rendered height (px)
+ *   --public-navbar-mobile-drawer-top   y where the mobile drawer should start
  *   --public-navbar-mobile-drawer-max-height
+ *   --dvh                               1% of the *stable* visual-viewport height
+ *
+ * Why `--dvh` and not just the CSS `dvh` unit: a length written in `dvh` with a
+ * CSS transition on it re-animates on every step of the mobile browser chrome
+ * collapsing/expanding — a jittery, stuttering result. This var is updated from
+ * `visualViewport` only on real resize (chrome settled), so heights built on
+ * `calc(var(--dvh) * 100)` stay smooth. Sections that don't animate can keep
+ * using the native `dvh` unit directly.
  *
  * @param navOuterRef - ref on the outermost navbar wrapper div
  * @param deps        - values that should re-trigger observer setup (position, variant, containerClassName)
@@ -15,31 +28,62 @@ export function useNavbarViewportVars(
   deps: readonly unknown[],
 ): void {
   useEffect(() => {
-    const update = () => {
-      const root = document.documentElement;
+    const root = document.documentElement;
+    const vv = window.visualViewport;
+
+    // Navbar height + the mobile-drawer anchoring. Depends on the navbar's own
+    // box, so it belongs on the ResizeObserver + scroll path (a hide-on-scroll
+    // bar's `rect.bottom` moves as it slides).
+    const updateNav = () => {
       const navEl = navOuterRef.current;
       if (!navEl) return;
 
       const rect = navEl.getBoundingClientRect();
+
+      // The bar's intrinsic height (not affected by a hide translate — that's
+      // why we read `height`, not `bottom - top` off a possibly-translated
+      // box). offsetHeight is layout height, stable across the slide.
+      const navHeight = Math.round(navEl.offsetHeight);
+      root.style.setProperty('--public-navbar-height', `${navHeight}px`);
+
       const top = Math.max(0, Math.round(rect.bottom + 8));
       const maxHeight = Math.max(240, window.innerHeight - top - 12);
-
       root.style.setProperty('--public-navbar-mobile-drawer-top', `${top}px`);
       root.style.setProperty('--public-navbar-mobile-drawer-max-height', `${maxHeight}px`);
     };
 
-    update();
+    // Stable viewport-height unit. `visualViewport.height` excludes the mobile
+    // browser chrome and (with `interactive-widget=resizes-content`) the
+    // on-screen keyboard, which is exactly what we want a full-height section
+    // to fit into. Updated only on resize so animated heights don't stutter.
+    const updateDvh = () => {
+      const h = vv?.height ?? window.innerHeight;
+      root.style.setProperty('--dvh', `${h / 100}px`);
+    };
+
+    updateNav();
+    updateDvh();
+
     const navEl = navOuterRef.current;
-    const observer = navEl ? new ResizeObserver(update) : null;
+    const observer = navEl ? new ResizeObserver(updateNav) : null;
     if (navEl && observer) observer.observe(navEl);
-    window.addEventListener('resize', update);
-    window.addEventListener('scroll', update, { passive: true });
+
+    // Nav geometry tracks scroll (the bar slides) + window resize.
+    window.addEventListener('resize', updateNav);
+    window.addEventListener('scroll', updateNav, { passive: true });
+
+    // `--dvh` intentionally does NOT listen to scroll: reacting to the mobile
+    // chrome mid-collapse is the jitter we're avoiding. Only settled resizes.
+    window.addEventListener('resize', updateDvh);
+    vv?.addEventListener('resize', updateDvh);
 
     return () => {
       if (navEl && observer) observer.unobserve(navEl);
       observer?.disconnect();
-      window.removeEventListener('resize', update);
-      window.removeEventListener('scroll', update);
+      window.removeEventListener('resize', updateNav);
+      window.removeEventListener('scroll', updateNav);
+      window.removeEventListener('resize', updateDvh);
+      vv?.removeEventListener('resize', updateDvh);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, deps);

package/src/layouts/PublicLayout/shared/NavbarShell.tsx

@@ -291,7 +291,14 @@ function NavbarShellRaw(props: NavbarShellProps) {
     // Stay above the mobile drawer backdrop (z-[998]) and drawer (z-[1000])
     // so the brand + close button remain visible and clickable.
     mobileMenuOpen ? 'z-[1001]' : 'z-50',
-    hideNavOnScroll && 'transition-transform duration-300 ease-in-out will-change-transform',
+    // Slide timing tuned for a "settled" feel, not a slow drift: a short 220ms
+    // with a gentle ease-out (decelerate into place) reads as the bar snapping
+    // to attention on scroll-up, while `motion-reduce:transition-none` honours
+    // the OS setting (the hook also refuses to set `hidden` under reduced
+    // motion, so the bar simply stays put). `will-change` promotes it to its
+    // own layer so the transform never repaints the page behind it.
+    hideNavOnScroll &&
+      'transition-transform duration-[220ms] ease-[cubic-bezier(0.22,1,0.36,1)] will-change-transform motion-reduce:transition-none',
     hideNavOnScroll && hidden && !mobileMenuOpen && '-translate-y-full',
   );