@brandocms/jupiter 5.0.0-beta.17 → 5.0.0-beta.18

package/README.md

@@ -949,6 +949,10 @@ when the original header is visible.
   - Pin header when scroll is forced (`application.scrollTo`, clicking anchors etc)
 - `unPinOnResize` - default `false`
   - Unpin header when window is resized
+- `headerHeightTracksPin` - default `true`
+  - Set per section (under `default` / `sections`). Whether `--header-height` drops
+    to `0px` while the header is unpinned. Set `false` for a header that never
+    retracts — see [CSS variables](#css-variables) under FixedHeader.
 
 - Events
   - `onMainVisible`
@@ -978,7 +982,8 @@ its space is still reserved.
 
 ### Options
 
-Same options as FixedHeader - see FixedHeader documentation below.
+Same options as FixedHeader - see FixedHeader documentation below, including
+`headerHeightTracksPin` and the [CSS variables](#css-variables) section.
 
 
 ## FixedHeader

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brandocms/jupiter",
-  "version": "5.0.0-beta.17",
+  "version": "5.0.0-beta.18",
   "description": "Frontend helpers.",
   "author": "Univers/Twined",
   "license": "UNLICENSED",

package/src/modules/DoubleHeader/index.js

@@ -80,6 +80,7 @@ const DEFAULT_OPTIONS = {
 
   default: {
     onClone: (h) => h.el.cloneNode(true),
+    headerHeightTracksPin: true,
     canvas: window,
     beforeEnter: (h) => {
       set(h.el, { opacity: 0 })
@@ -450,11 +451,25 @@ export default class DoubleHeader {
 
   /**
    * Update the --header-height CSS variable on :root.
-   * Uses el height when pinned (el is the main header, auxEl is secondary).
-   * Set to 0px when unpinned.
+   *
+   * Measured from `el`, the main header — `auxEl` is the clone. By default this
+   * is how much header is *visible*, the measured height when pinned and 0 when
+   * unpinned, so anything positioned under the bar follows it out of the way as
+   * the clone retracts.
+   *
+   * That is wrong for a header configured never to retract, whether through
+   * `preventUnpin` or by no-opping `onPin` / `onUnpin`. The bar stays put, but
+   * `_pinned` still flips on every change of scroll direction, so the variable
+   * drops to 0 and back while nothing moves. Any layout sized from it then grows
+   * and shrinks the document under the reader. Scroll anchoring absorbs that
+   * mid-page, but not at the very bottom, where the scroll offset is clamped to
+   * the document and the page visibly jumps instead.
+   *
+   * `headerHeightTracksPin: false` publishes the measured height throughout.
    */
   _updateHeaderHeight() {
-    const height = this._pinned ? `${this.el.clientHeight}px` : '0px'
+    const tracksPin = this.opts.headerHeightTracksPin !== false
+    const height = tracksPin && !this._pinned ? '0px' : `${this.el.clientHeight}px`
     document.documentElement.style.setProperty('--header-height', height)
   }
 

package/src/modules/StickyHeader/index.js

@@ -52,6 +52,7 @@ import { set } from '../../utils/motion-helpers'
 /**
  * @typedef {Object} StickyHeaderSectionOptions
  * @property {boolean} [unPinOnResize=true] - Whether to unpin header on window resize
+ * @property {boolean} [headerHeightTracksPin=true] - Whether --header-height drops to 0 when the header unpins. Set false for a header that never retracts.
  * @property {Window|HTMLElement} [canvas=window] - Scrolling element
  * @property {string|null} [intersects=null] - Selector for elements to check intersection with
  * @property {Function} [beforeEnter] - Called before header enters
@@ -155,6 +156,7 @@ const DEFAULT_OPTIONS = {
 
   default: {
     unPinOnResize: true,
+    headerHeightTracksPin: true,
     canvas: window,
     intersects: null,
     beforeEnter: (h) => {
@@ -609,10 +611,24 @@ export default class StickyHeader {
 
   /**
    * Update the --header-height CSS variable on :root.
-   * Set to the header's current height when pinned, 0px when unpinned.
+   *
+   * By default this is how much header is *visible* — the measured height when
+   * pinned, 0 when unpinned — so anything positioned under the bar follows it
+   * out of the way as it retracts.
+   *
+   * That is wrong for a header configured never to retract, whether through
+   * `preventUnpin` or by no-opping `onPin` / `onUnpin`. The bar stays put, but
+   * `_pinned` still flips on every change of scroll direction, so the variable
+   * drops to 0 and back while nothing moves. Any layout sized from it then grows
+   * and shrinks the document under the reader. Scroll anchoring absorbs that
+   * mid-page, but not at the very bottom, where the scroll offset is clamped to
+   * the document and the page visibly jumps instead.
+   *
+   * `headerHeightTracksPin: false` publishes the measured height throughout.
    */
   _updateHeaderHeight() {
-    const height = this._pinned ? `${this.el.clientHeight}px` : '0px'
+    const tracksPin = this.opts.headerHeightTracksPin !== false
+    const height = tracksPin && !this._pinned ? '0px' : `${this.el.clientHeight}px`
     document.documentElement.style.setProperty('--header-height', height)
   }
 

package/types/modules/DoubleHeader/index.d.ts

@@ -48,8 +48,21 @@ export default class DoubleHeader {
     small(): void;
     /**
      * Update the --header-height CSS variable on :root.
-     * Uses el height when pinned (el is the main header, auxEl is secondary).
-     * Set to 0px when unpinned.
+     *
+     * Measured from `el`, the main header — `auxEl` is the clone. By default this
+     * is how much header is *visible*, the measured height when pinned and 0 when
+     * unpinned, so anything positioned under the bar follows it out of the way as
+     * the clone retracts.
+     *
+     * That is wrong for a header configured never to retract, whether through
+     * `preventUnpin` or by no-opping `onPin` / `onUnpin`. The bar stays put, but
+     * `_pinned` still flips on every change of scroll direction, so the variable
+     * drops to 0 and back while nothing moves. Any layout sized from it then grows
+     * and shrinks the document under the reader. Scroll anchoring absorbs that
+     * mid-page, but not at the very bottom, where the scroll offset is clamped to
+     * the document and the page visibly jumps instead.
+     *
+     * `headerHeightTracksPin: false` publishes the measured height throughout.
      */
     _updateHeaderHeight(): void;
     shouldUnpin(toleranceExceeded: any): any;

package/types/modules/StickyHeader/index.d.ts

@@ -59,7 +59,20 @@ export default class StickyHeader {
     small(): void;
     /**
      * Update the --header-height CSS variable on :root.
-     * Set to the header's current height when pinned, 0px when unpinned.
+     *
+     * By default this is how much header is *visible* — the measured height when
+     * pinned, 0 when unpinned — so anything positioned under the bar follows it
+     * out of the way as it retracts.
+     *
+     * That is wrong for a header configured never to retract, whether through
+     * `preventUnpin` or by no-opping `onPin` / `onUnpin`. The bar stays put, but
+     * `_pinned` still flips on every change of scroll direction, so the variable
+     * drops to 0 and back while nothing moves. Any layout sized from it then grows
+     * and shrinks the document under the reader. Scroll anchoring absorbs that
+     * mid-page, but not at the very bottom, where the scroll offset is clamped to
+     * the document and the page visibly jumps instead.
+     *
+     * `headerHeightTracksPin: false` publishes the measured height throughout.
      */
     _updateHeaderHeight(): void;
     notAltBg(): void;
@@ -143,6 +156,10 @@ export type StickyHeaderSectionOptions = {
      * - Whether to unpin header on window resize
      */
     unPinOnResize?: boolean;
+    /**
+     * - Whether --header-height drops to 0 when the header unpins. Set false for a header that never retracts.
+     */
+    headerHeightTracksPin?: boolean;
     /**
      * - Scrolling element
      */