@brandocms/jupiter 5.0.0-beta.16 → 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
@@ -994,6 +999,8 @@ Same options as FixedHeader - see FixedHeader documentation below.
 - `sections`
   - Here you can set a config per section (body[data-script="section"])
   - `unPinOnResize` - auto unpin while resizing
+  - `headerHeightTracksPin` - default `true`. Whether `--header-height` drops to `0px`
+    while the header is unpinned. Set `false` for a header that never retracts.
   - `offset` - when is header triggered
   - `offsetBg` - when is offset background triggered (i.e. if there's another bg for content)
   - events are same as under default.
@@ -1034,6 +1041,22 @@ Same options as FixedHeader - see FixedHeader documentation below.
   - `onMobileMenuClose`
     - Triggers when mobile menu closes
 
+### CSS variables
+
+`--header-height` is kept up to date on `:root`, republished whenever the header pins,
+unpins or toggles small/big. By default it is how much header is *visible* — the
+measured height while pinned, `0px` while unpinned — so anything positioned under the
+bar follows it out of the way as it retracts.
+
+For a header that never retracts — through `preventUnpin`, or by no-opping
+`onPin`/`onUnpin` — set `headerHeightTracksPin: false`. The bar stays put, but the
+pinned state still flips on every change of scroll direction, so the variable would
+otherwise drop to `0px` and back while nothing moves. Any layout sized from it (a
+`padding-top` standing in for the fixed bar, say) 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.
+`headerHeightTracksPin: false` publishes the measured height throughout.
+
  ```
  header[data-nav] {
   @include container();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brandocms/jupiter",
-  "version": "5.0.0-beta.16",
+  "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/FixedHeader/index.js

@@ -50,6 +50,7 @@ import { set } from '../../utils/motion-helpers'
 /**
  * @typedef {Object} FixedHeaderSectionOptions
  * @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
@@ -153,6 +154,7 @@ const DEFAULT_OPTIONS = {
 
   default: {
     unPinOnResize: true,
+    headerHeightTracksPin: true,
     canvas: window,
     intersects: null,
     beforeEnter: (h) => {
@@ -612,10 +614,25 @@ export default class FixedHeader {
 
   /**
    * 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 — a
+   * `padding-top` standing in for the fixed bar, say — 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/FixedHeader/index.d.ts

@@ -15,6 +15,10 @@ export default class FixedHeader {
              * - 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
              */
@@ -110,7 +114,21 @@ export default class FixedHeader {
     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 — a
+     * `padding-top` standing in for the fixed bar, say — 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;
@@ -200,6 +218,10 @@ export type FixedHeaderSectionOptions = {
      * - 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
      */

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
      */