studio-engine 0.110.0 → 0.111.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc29384322161b3794ff7694c0cb0fad8e0644b3b52089699397ffa0cece7d24
-  data.tar.gz: 9c55995cf09c07410c5fca9b3527faae09212dda08e694130385246ec0f7c96f
+  metadata.gz: 9d7cabff315fe9d235009b89cffbc4409acdec4cb52b5e99f750dbc09a10b2ba
+  data.tar.gz: 4f7b337c79de43cc0c1269570f0bc2947f8e55ceccef13281e2494ee85e70178
 SHA512:
-  metadata.gz: d75adb8fe56a72ea7e48bcb42fcca19f505f2656f644825b6743df6dca43a55cea08e4f9291385634f9ef0cc2701c56a20e4b275ed72372dbc5330b39dc2b0bd
-  data.tar.gz: b054488991e318511e2b77204e02ae5ef338d0832a447e0c6971d75aa41c807c3a8d95c60f09b27276bd7a2d520928c0d3f70f715a014ecdbff8727e60e142d9
+  metadata.gz: a5a8f42972f22be43ad7e325b629bf7d2b5b4e374ffee170e531b0d6c730dbadecd96cebc5f8b36d7024dd476bbd424ee27892b9423c9d5af2f4ce5a2d8b1e19
+  data.tar.gz: 187c2bb411cc2f2a1312379e6998879f44f13bedcdbb5e2fe7d92ca94a11795c89a187d2c36d616ca72bfe3424a361ed1f9d308ac879418d8ebaca6f4e87fbe5

data/CHANGELOG.md

@@ -4,6 +4,28 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.111.0 — 2026-10-16
+
+### Added
+
+- **The navbar can collapse on the browser's scroll timeline** (opt-in:
+  `config.navbar_scroll_timeline = true`, or `scroll_timeline: true` on one
+  render of `layouts/_navbar`). From 768px, in a browser with scroll-driven
+  animations, the header keeps one height and is sticky at minus its band (its
+  expanded height less its collapsed height), so the band scrolls away with the
+  page and the compact bar sticks. The logo, title, avatar and name shrink by
+  transforms on the page's scroll timeline, and the icon rail slides so the
+  gaps stay even. The compositor runs all of it with the scroll: no script per
+  frame, no relayout, so a busy page cannot make the header stutter. The
+  scrolled line and shadow are drawn by `::after` on the same timeline.
+  `studio/nav_collapse` gains a timeline mode for the header: it measures the
+  band and the scales once (on connect, resize, font load and a bar resize)
+  and keeps the `is-scrolled` marker; phones (under 768px) and browsers without
+  scroll timelines (Firefox today) keep the `--nav-p` collapse, and crossing
+  768px swaps modes. On the timeline, `--nav-h` is the compact bar's height,
+  so an anchor's `scroll-margin-top` clears what is pinned. Off by default: a
+  header without the opt-in renders and behaves byte-identical to before.
+
 ## 0.110.0 — 2026-10-15
 
 ### Added

data/app/assets/tailwind/studio_engine/engine.css

@@ -752,6 +752,100 @@ body.modal-open .studio-app-banner {
     }
 }
 
+/* THE SCROLL-DRIVEN COLLAPSE (opt-in: config.navbar_scroll_timeline, which puts
+   data-nav-timeline on layouts/_navbar's header).
+
+   The band table above interpolates real sizes off --nav-p, which
+   studio/nav_collapse writes from script once per frame. Every one of those
+   frames is a style-and-layout pass on the main thread, so the header can only
+   be as smooth as the page around it: on a busy page (the hub's /deployments,
+   2026-10-15) a flick dropped frames and the header stepped.
+
+   Here nothing changes size, so nothing reflows and no script runs per frame:
+
+     THE BOX IS FIXED at its expanded height, and sticky at minus the BAND (its
+     expanded height less its collapsed height, measured by the controller and
+     published as --nav-band). So the band scrolls away with the page by the
+     browser's own scrolling, and the compact bar is what sticks. The document
+     never changes height; the page cannot move by itself.
+
+     THE SHRINK IS A SCROLL TIMELINE on transforms: the row slides down half the
+     band so it stays centred on the visible bar, the brand scales from its left
+     edge, the avatar and name from the right (the name by the avatar's ratio,
+     the rule of 3), and the icon rail slides right by what the account gave up
+     so the gaps stay even. The compositor runs these with the scroll itself.
+
+     THE SCROLLED LINE AND SHADOW are drawn by ::after on the same timeline,
+     not by border-b (which would add a pixel of height and reflow).
+
+   --nav-start is where the header meets the top of the window: the height of
+   the bars above it in flow (studio/banners/_stack). Both it and the scales
+   are measured once (on connect, resize, font load, a bar resize), never per
+   frame; studio/nav_collapse's timeline mode owns them.
+
+   Only from 768px, and only where the browser has scroll timelines (Firefox
+   does not yet): the controller tests the same two conditions and runs the
+   --nav-p collapse otherwise, so the two can never both drive the header. */
+@layer utilities {
+  @supports (animation-timeline: scroll()) {
+    @media (min-width: 768px) {
+      .nav-shell[data-nav-timeline] {
+        --nav-band: 40px;
+        top: calc(-1 * var(--nav-band));
+      }
+      .nav-shell[data-nav-timeline]::after {
+        content: "";
+        position: absolute;
+        inset: auto 0 0 0;
+        height: 1px;
+        background: var(--color-border);
+        box-shadow: 0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1);
+        pointer-events: none;
+        opacity: 0;
+        animation: nav-tl-lit linear both;
+        animation-timeline: scroll(root block);
+        animation-range: calc(var(--nav-start, 0px) + var(--nav-band) - 8px) calc(var(--nav-start, 0px) + var(--nav-band) + 16px);
+      }
+      /* The row slides down half the band to stay centred on the bar, so its
+         bottom padding (empty, transparent) overhangs the header by that much,
+         and an overhang still takes the pointer: it ate clicks on the top 20px
+         of the hub's pinned board lane headers. The row lets the pointer
+         through; its contents, which sit inside the bar, still take it. */
+      .nav-shell[data-nav-timeline] > .nav-row { pointer-events: none; }
+      .nav-shell[data-nav-timeline] > .nav-row > * { pointer-events: auto; }
+      .nav-shell[data-nav-timeline] > .nav-row {
+        animation: nav-tl-row linear both;
+        animation-timeline: scroll(root block);
+        animation-range: var(--nav-start, 0px) calc(var(--nav-start, 0px) + var(--nav-band));
+      }
+      .nav-shell[data-nav-timeline] .nav-logo-link,
+      .nav-shell[data-nav-timeline] [data-nav-account] > [aria-hidden],
+      .nav-shell[data-nav-timeline] [data-nav-account] > span:first-child,
+      .nav-shell[data-nav-timeline] [data-nav-tools] {
+        animation-timing-function: ease-in-out;
+        animation-fill-mode: both;
+        animation-timeline: scroll(root block);
+        animation-range: var(--nav-start, 0px) calc(var(--nav-start, 0px) + var(--nav-ramp));
+      }
+      .nav-shell[data-nav-timeline] .nav-logo-link { transform-origin: left center; animation-name: nav-tl-brand; }
+      .nav-shell[data-nav-timeline] [data-nav-account] > [aria-hidden] { transform-origin: right center; animation-name: nav-tl-avatar; }
+      .nav-shell[data-nav-timeline] [data-nav-account] > span:first-child { transform-origin: right center; animation-name: nav-tl-name; }
+      .nav-shell[data-nav-timeline] [data-nav-tools] { animation-name: nav-tl-tools; }
+    }
+    /* Reduced motion: the shrink snaps at the first pixel, as --nav-p's 0/1
+       snap does on the script path. */
+    @media (min-width: 768px) and (prefers-reduced-motion: reduce) {
+      .nav-shell[data-nav-timeline] { --nav-ramp: 1px; }
+    }
+  }
+}
+@keyframes nav-tl-row { to { transform: translateY(calc(var(--nav-band) / 2)); } }
+@keyframes nav-tl-brand { to { transform: scale(var(--nav-brand-scale, 1)); } }
+@keyframes nav-tl-avatar { to { transform: scale(var(--nav-avatar-scale, 1)); } }
+@keyframes nav-tl-name { to { transform: translateX(var(--nav-avatar-shrink, 0px)) scale(var(--nav-avatar-scale, 1)); } }
+@keyframes nav-tl-tools { to { transform: translateX(var(--nav-tools-shift, 0px)); } }
+@keyframes nav-tl-lit { to { opacity: 1; } }
+
 /* A board whose controller failed to load (studio/lazy_controllers marks its
    section data-studio-controller-failed="board") shows the notice
    studio/board/_board renders with an inline display: none. !important is what

data/app/javascript/studio/controllers/nav_collapse_controller.js

@@ -16,7 +16,13 @@ export default class extends Controller {
   connect() {
     this.collapse = new NavCollapse(this.element, (lit) => {
       if (!this.hasScrolledClass) return
-      for (const name of this.scrolledClasses) this.element.classList.toggle(name, lit)
+      // On the scroll timeline the line and shadow are the stylesheet's
+      // (::after, so no border adds a pixel of height); only the marker
+      // toggles, and the rest stay off.
+      const timeline = this.collapse && this.collapse.timeline
+      for (const name of this.scrolledClasses) {
+        this.element.classList.toggle(name, lit && (!timeline || name === "is-scrolled"))
+      }
     })
     this.collapse.start()
   }

data/app/javascript/studio/nav_collapse.js

@@ -197,6 +197,63 @@ export function readTuning(style) {
   };
 }
 
+// THE SCROLL-DRIVEN MODE (engine.css, THE SCROLL-DRIVEN COLLAPSE). A header
+// carrying data-nav-timeline, from 768px, in a browser with scroll timelines,
+// collapses in CSS on the compositor, and this controller stops driving --nav-p.
+// What CSS cannot know it is told once, not per frame: the band that scrolls
+// away, the scales, and where the header meets the window. The query is the
+// stylesheet's own; the two must agree, or both would drive the header.
+export var TIMELINE_QUERY = '(min-width: 768px)';
+
+export function timelineSupported() {
+  return typeof CSS !== 'undefined' && !!CSS.supports && CSS.supports('animation-timeline: scroll()');
+}
+
+export function timelineOn(el, wide) {
+  return el.hasAttribute('data-nav-timeline') && wide && timelineSupported();
+}
+
+// The timeline's custom properties, from the header measured at both ends of
+// the band table (--nav-p 0 and 1). Layout sizes only (offsetHeight and
+// offsetWidth), which a transform does not change, so the reading is the same
+// at any scroll position.
+//
+//   rest, collapsed   the header's height expanded and collapsed
+//   brand0, brand1    the brand link's height expanded and collapsed
+//   avatar0, avatar1  the avatar's height expanded and collapsed (0: none)
+//   nameW             the account name's width
+//
+// The name scales by the avatar's ratio (the rule of 3), and the icon rail
+// slides right by what the name and avatar give up, so the gaps stay even.
+// Without an avatar (signed out) nothing on the right moves.
+export function timelineVars({ rest, collapsed, brand0, brand1, avatar0, avatar1, nameW }) {
+  var avatarScale = avatar0 > 0 ? avatar1 / avatar0 : 1;
+  var avatarShrink = avatar0 > 0 ? Math.max(0, avatar0 - avatar1) : 0;
+  return {
+    band: Math.max(0, rest - collapsed),
+    brandScale: brand0 > 0 ? brand1 / brand0 : 1,
+    avatarScale: avatarScale,
+    avatarShrink: avatarShrink,
+    toolsShift: avatar0 > 0 ? nameW * (1 - avatarScale) + avatarShrink : 0
+  };
+}
+
+var TIMELINE_PROPS = ['--nav-band', '--nav-start', '--nav-brand-scale', '--nav-avatar-scale',
+  '--nav-avatar-shrink', '--nav-tools-shift'];
+
+// What the timeline mode leaves on the header. stopTimeline() clears it, and
+// so does the --nav-p path's start(): a Turbo snapshot taken wide and restored
+// below 768px (a phone rotated, then Back) arrives still carrying it, and
+// pinned_stack would subtract the stale band from --nav-h.
+export function clearTimeline(el) {
+  TIMELINE_PROPS.forEach(function (name) { el.style.removeProperty(name); });
+  el.removeAttribute('data-nav-timeline-on');
+}
+
+function round(n) {
+  return Math.round(n * 1000) / 1000;
+}
+
 // THE BINDING: one header, its listeners, and the frame loop. The Stimulus
 // controller and the Alpine shim both drive this, so the two cannot drift.
 // onScrolled(lit) fires when the shadow's hysteresis flips.
@@ -220,10 +277,22 @@ export class NavCollapse {
     this.lastHeight = null;
     this._observer = null;
     this._remeasure = this.remeasure.bind(this);
+    this.timeline = false;
+    this._wide = null;
+    this._onWide = this.onWide.bind(this);
+    this._onTimelineScroll = this.onTimelineScroll.bind(this);
+    this._onTimelineResize = this.measureTimeline.bind(this);
+    this._bars = null;
   }
 
   start() {
     this.stopped = false;
+    this._wide = window.matchMedia(TIMELINE_QUERY);
+    if (this._wide.addEventListener) this._wide.addEventListener('change', this._onWide);
+    if (timelineOn(this.el, this._wide.matches)) {
+      this.startTimeline();
+      return;
+    }
     this._reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
     // A HEADER RESTORED FROM TURBO'S SNAPSHOT CACHE arrives as it was left:
     // its scrolled classes on, and this controller's own hold still inline
@@ -232,6 +301,7 @@ export class NavCollapse {
     // under the header, 39-43px on turf-monster's contest page. So the
     // controller clears what it owns before it reads anything.
     this.onScrolled(false);
+    clearTimeline(this.el);
     this.el.style.marginBottom = '';
     this.el.style.removeProperty('--nav-hold');
     this.el.style.removeProperty('--nav-hold-fix');
@@ -278,6 +348,12 @@ export class NavCollapse {
   // every visit would stack another listener on window.
   stop() {
     this.stopped = true;
+    if (this._wide && this._wide.removeEventListener) this._wide.removeEventListener('change', this._onWide);
+    this._wide = null;
+    if (this.timeline) {
+      this.stopTimeline();
+      return;
+    }
     window.removeEventListener('scroll', this._onScroll);
     window.removeEventListener('resize', this._onResize);
     if (this._observer) this._observer.disconnect();
@@ -292,6 +368,103 @@ export class NavCollapse {
     }
   }
 
+  // Crossing 768px swaps modes: undo the one running, start the one that
+  // now applies.
+  onWide() {
+    if (this.stopped) return;
+    this.stop();
+    this.start();
+  }
+
+  startTimeline() {
+    this.timeline = true;
+    this.held = false;
+    this.p = 0;
+    // A header restored from Turbo's cache, or crossing 768px, can carry
+    // what the --nav-p path left inline; it goes.
+    this.el.style.marginBottom = '';
+    this.el.style.removeProperty('--nav-hold');
+    this.el.style.removeProperty('--nav-hold-fix');
+    this.el.style.removeProperty('--nav-p');
+    this.el.setAttribute('data-nav-timeline-on', '');
+    this.scrolled = false;
+    this.onScrolled(false);
+    this.measureTimeline();
+    this.onTimelineScroll();
+    window.addEventListener('scroll', this._onTimelineScroll, { passive: true });
+    window.addEventListener('resize', this._onTimelineResize, { passive: true });
+    var bars = document.querySelector('[data-studio-bar-stack]');
+    if (bars && typeof ResizeObserver === 'function') {
+      this._bars = new ResizeObserver(this._onTimelineResize);
+      this._bars.observe(bars);
+    }
+    if (document.fonts && document.fonts.ready) document.fonts.ready.then(this._onTimelineResize);
+  }
+
+  stopTimeline() {
+    this.timeline = false;
+    window.removeEventListener('scroll', this._onTimelineScroll);
+    window.removeEventListener('resize', this._onTimelineResize);
+    if (this._bars) this._bars.disconnect();
+    this._bars = null;
+    clearTimeline(this.el);
+  }
+
+  // Reads the header at both ends of the band table and publishes what the
+  // timeline needs. Runs on start, resize, font load and a bar resize; a
+  // scroll never calls it. Writes only a value that changed.
+  measureTimeline() {
+    if (this.stopped || !this.timeline) return;
+    var el = this.el;
+    var brand = el.querySelector('.nav-logo-link');
+    var avatar = el.querySelector('[data-nav-account] > [aria-hidden]');
+    var name = el.querySelector('[data-nav-account] > span:first-child');
+    var read = function () {
+      return {
+        h: el.offsetHeight,
+        brand: brand ? brand.offsetHeight : 0,
+        avatar: avatar ? avatar.offsetHeight : 0
+      };
+    };
+    el.style.removeProperty('--nav-p');
+    var open = read();
+    el.style.setProperty('--nav-p', '1');
+    var shut = read();
+    el.style.removeProperty('--nav-p');
+    var vars = timelineVars({
+      rest: open.h, collapsed: shut.h,
+      brand0: open.brand, brand1: shut.brand,
+      avatar0: open.avatar, avatar1: shut.avatar,
+      nameW: name ? name.offsetWidth : 0
+    });
+    // Where the header meets the top of the window: the bars above it in flow.
+    var bars = document.querySelector('[data-studio-bar-stack]');
+    var start = bars && (bars.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING)
+      ? bars.offsetHeight : 0;
+    var props = {
+      '--nav-band': round(vars.band) + 'px',
+      '--nav-start': start + 'px',
+      '--nav-brand-scale': String(round(vars.brandScale)),
+      '--nav-avatar-scale': String(round(vars.avatarScale)),
+      '--nav-avatar-shrink': round(vars.avatarShrink) + 'px',
+      '--nav-tools-shift': round(vars.toolsShift) + 'px'
+    };
+    for (var key in props) {
+      if (el.style.getPropertyValue(key) !== props[key]) el.style.setProperty(key, props[key]);
+    }
+  }
+
+  // The scrolled marker on the controller's own hysteresis, written only when
+  // it flips. No frame is scheduled: the collapse itself is the stylesheet's.
+  onTimelineScroll() {
+    if (this.stopped || !this.timeline) return;
+    var lit = shadowLit(this.scrolled, Math.max(0, window.scrollY));
+    if (lit !== this.scrolled) {
+      this.scrolled = lit;
+      this.onScrolled(lit);
+    }
+  }
+
   onScroll() {
     if (this.queued) return;
     this.queued = true;

data/app/javascript/studio/pinned_stack.js

@@ -288,7 +288,11 @@ export function startPinnedStack() {
     // own. That is what lets a layer come and go without anyone declaring a
     // stacking order, and it is load-bearing rather than incidental.
     var r = el.getBoundingClientRect();
-    return { el: el, name: name, legacy: legacy, h: el.offsetHeight, bottom: Math.max(0, r.bottom) };
+    // A header on the scroll timeline (studio/nav_collapse) keeps its expanded
+    // box, and its top band scrolls away above the window; what pins is the
+    // compact bar, so that is its height here. An inline read, no layout.
+    var band = el.hasAttribute('data-nav-timeline-on') ? parseFloat(el.style.getPropertyValue('--nav-band')) || 0 : 0;
+    return { el: el, name: name, legacy: legacy, h: el.offsetHeight - band, bottom: Math.max(0, r.bottom) };
   }
 
 

data/app/views/layouts/_navbar.html.erb

@@ -63,7 +63,11 @@
     through ($store.devMode on the user nav, the sidebar trigger's @click):
     Alpine initializes directives only inside a component, and the header was
     that component while navCollapse() lived on it. %>
-<header data-pin="nav"<% unless is_preview %> x-data data-studio-controller="nav-collapse" data-nav-collapse-scrolled-class="shadow-lg border-b border-subtle is-scrolled"<% end %>
+<%# data-nav-timeline opts into the scroll-driven collapse (Studio.navbar_scroll_timeline,
+    or a scroll_timeline: local for one render; engine.css, THE SCROLL-DRIVEN
+    COLLAPSE). Never on a preview: the /navbar page drives --nav-p itself. %>
+<% scroll_timeline = local_assigns.fetch(:scroll_timeline, Studio.navbar_scroll_timeline) %>
+<header data-pin="nav"<% unless is_preview %> x-data data-studio-controller="nav-collapse" data-nav-collapse-scrolled-class="shadow-lg border-b border-subtle is-scrolled"<%= " data-nav-timeline" if scroll_timeline %><% end %>
         <%# top-0, a STATIC value, and never a custom property. Any bars render as
             this header's sibling in normal flow (studio/banners/_stack), so they
             already occupy their own height above it and there is nothing to

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.110.0"
+  VERSION = "0.111.0"
 end

data/lib/studio.rb

@@ -248,6 +248,17 @@ module Studio
 
   mattr_reader :sign_in_label, default: NavbarIdentity::DEFAULT_SIGN_IN_LABEL
 
+  # ---- Navbar scroll timeline ----
+  # true opts layouts/_navbar's header into the scroll-driven collapse
+  # (engine.css, THE SCROLL-DRIVEN COLLAPSE): from 768px, in a browser with
+  # scroll timelines, the header keeps one height, its top band scrolls away,
+  # and the shrink runs as compositor transforms with no script per frame.
+  # Phones and other browsers keep the --nav-p collapse. false, the default,
+  # renders the header byte-identical to before.
+  #
+  #   config.navbar_scroll_timeline = true
+  mattr_accessor :navbar_scroll_timeline, default: false
+
   # ---- Navbar wordmark ----
   # A brand lockup image (icon plus words as one artwork) drawn in place of the
   # "Navbar Logo" and the app_name text. nil, the default, renders the navbar

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.110.0
+  version: 0.111.0
 platform: ruby
 authors:
 - Alex McRitchie