studio-engine 0.111.1.rc1 → 0.111.2.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 650a35a39685ece1959d6a403014344875cfd107f28dee2bd0594a66667592f3
-  data.tar.gz: 413b0ffb720c3da0e51327700723b126fb6cc88d7404543bdbccde28764e4a21
+  metadata.gz: 8808038af9e2419c0af0177895740230d150828f028ae40be6824c877624b557
+  data.tar.gz: ca450685c591c1414842097435599e658e5a0a68cbf9b05f1405d7c338d35a88
 SHA512:
-  metadata.gz: 8ffc0f710b353aea044308e4e16a687915e120dfee1950aa52c79c7be656a8b2a68d92df9c453182f2dd6b82980428ee0e7d2a4fc433ed20dfa1aeadd47c722d
-  data.tar.gz: bc4149aecbb0ac3c38a3905dec253d44c30459d0b9ba4a624bf18abbdc05613c568015fd4ce827d6d2dc39576b1de6bc244ab989ba56df9e5b875ba93229917b
+  metadata.gz: ae13f4a634c55627b37809d8fb01b39c853a8bec472374aaf5afd30f3f57d84ca99b2d07a92132b8e8ee4ddf28e563ef2fe62befea927262830fb4e7f2065efa
+  data.tar.gz: d900c3a5fcb6aae1d4339fe0a74b078cc9876c11f810f751112e0b2018fbaf54f5205363d8b61d78474c502b501b4f110f9c9eea78e2faaa426c19e92c0bdf1b

data/CHANGELOG.md

@@ -4,6 +4,37 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.111.2 — 2026-10-18
+
+### Fixed
+
+- **The sticky table header's clone sits on the pinned bar.** It placed its
+  `position: fixed` header row at `--nav-h`, re-read only on a scroll, a resize
+  or a header resize. On a scroll-timeline header the compact height is
+  published only once the nav-collapse controller starts, which resizes
+  nothing, so a page loaded at a restored scroll position kept the clone at the
+  expanded height (Turf Monster `/contests`: 96px under a 50px bar, rows showing
+  in the gap) until the first scroll. On a phone the root's `--nav-h` also
+  lagged the collapse, so the clone sat off the bar through a flick. The clone
+  now reads the stack's live bottom (`window.studioPinnedStack.read()`, closing
+  the expanded header's travel on the timeline as `data-pin-edge` does), falls
+  back to `--pin-stack-bottom`, and never reads `--nav-h`. It re-places on
+  `studio:pinned-stack-refresh`, on every stack publish, and synchronously when
+  any `data-pin` layer resizes.
+- **The style guide's section nav sticks under the whole pinned stack**
+  (`--pin-stack-bottom`), not at the header's height, which put it under any
+  chrome stacked above the header.
+
+### Added
+
+- **`studio:pinned-stack-published`.** `studio/pinned_stack` fires it on the
+  document after a publish that moved the stack, with the reading it just made
+  (`{ bottom, timeline, travel }`) as `detail`, so a script that positions off
+  the stack re-places in the same frame. `docs/NAVBAR_SETUP.md`, *Reading the
+  Pinned Stack*.
+- **`layouts/studio/_head` takes a `sticky_table_headers:` local** that answers
+  for one render (nil defers to `config.sticky_table_headers`).
+
 ## 0.111.1 — 2026-10-16
 
 ### Added

data/app/assets/javascripts/studio/sticky_table_header.js

@@ -4,18 +4,69 @@
   const MANUAL_TABLE_SELECTOR = "table[data-sticky-table-header]";
   const AUTO_TABLE_SELECTOR = "table";
   const SKIP_CONTAINER_SELECTOR = "[data-sticky-table-skip]";
+  // What studio/nav_collapse fires when a scroll-timeline header starts,
+  // re-measures its band, or stops: the header's PINNED height changed without
+  // its box resizing, so no ResizeObserver and no scroll hears of it.
+  const PINNED_STACK_REFRESH = "studio:pinned-stack-refresh";
+  // What studio/pinned_stack fires after every publish that moved the stack.
+  const PINNED_STACK_PUBLISHED = "studio:pinned-stack-published";
 
   let stickyTables = [];
   let scheduled = false;
   let bootScheduled = false;
-  let navResizeObserver = null;
+  let pinResizeObserver = null;
   let tableMutationObserver = null;
 
-  window.StudioStickyTableHeaders = { loaded: true };
+  // WHERE THE CLONE STARTS: THE PINNED STACK'S BOTTOM EDGE, read live.
+  //
+  // This used to read --nav-h off the root, and that was wrong twice. --nav-h
+  // is the header's HEIGHT, not its bottom edge, so chrome stacked above the
+  // header put the clone that much too high. And a root custom property is a
+  // SNAPSHOT this script re-read only on scroll, resize or a header resize: on
+  // a scroll-timeline header the compact height is published only once the
+  // nav-collapse controller starts, which resizes nothing, so a page loaded at
+  // a restored scroll position kept the clone at the expanded height (Turf
+  // Monster /contests: 96px against a 50px bar, rows showing in the gap) until
+  // the first scroll.
+  //
+  // window.studioPinnedStack.read() measures on call, the same reading the
+  // publisher makes. On a scroll-timeline header it reports where the stack
+  // sits once PINNED; at the top of the page the expanded header still reaches
+  // `travel` further down, and closes that gap as the page scrolls, exactly as
+  // engine.css's data-pin-edge does for a fixed reader in CSS. A host that never
+  // started the publisher falls back to --pin-stack-bottom, then to 0: a clone
+  // at the top of the viewport rather than none.
+  function pinnedEdge(reading) {
+    const r = reading || window.studioPinnedStack?.read?.();
+    if (!r) {
+      const raw = getComputedStyle(document.documentElement).getPropertyValue("--pin-stack-bottom");
+      return Number.parseFloat(raw) || 0;
+    }
+    const bottom = Number(r.bottom) || 0;
+    if (!r.timeline) return bottom;
+    return bottom + Math.max(0, (Number(r.travel) || 0) - Math.max(0, window.scrollY));
+  }
 
-  function navOffset() {
-    const raw = getComputedStyle(document.documentElement).getPropertyValue("--nav-h");
-    return Number.parseFloat(raw) || 0;
+  // Where the clone goes for one table, as a pure function of what was measured:
+  // shown once the real header has scrolled up to the edge, and pushed up by the
+  // table's own bottom so it leaves with the table.
+  function placement({ edge, headerTop, tableBottom, cloneHeight }) {
+    const active = headerTop <= edge && tableBottom > edge;
+    return { active, top: active ? Math.min(edge, tableBottom - cloneHeight) : null };
+  }
+
+  window.StudioStickyTableHeaders = { loaded: true, pinnedEdge, placement };
+
+  // One pass over every table, reading the edge ONCE. Called from a frame
+  // callback (scroll, resize, a stack event) and SYNCHRONOUSLY from the
+  // ResizeObserver, which runs after layout and before paint: a script-mode
+  // header changes height every frame of its collapse (studio/nav_collapse
+  // writes --nav-p from its own frame callback, after ours), and a frame-late
+  // clone shows rows through the gap for that frame.
+  function updateAll(reading) {
+    if (!stickyTables.length) return;
+    const edge = pinnedEdge(reading);
+    stickyTables.slice().forEach((stickyTable) => stickyTable.update(edge));
   }
 
   function scheduleUpdate() {
@@ -23,7 +74,7 @@
     scheduled = true;
     requestAnimationFrame(() => {
       scheduled = false;
-      stickyTables.forEach((stickyTable) => stickyTable.update());
+      updateAll();
     });
   }
 
@@ -80,19 +131,20 @@
       });
     }
 
-    update() {
+    update(edge = pinnedEdge()) {
       if (!document.body.contains(this.table) || !this.table.tHead || !this.scroller) {
         this.destroy();
         stickyTables = stickyTables.filter((stickyTable) => stickyTable !== this);
         return;
       }
 
-      const offset = navOffset();
       const headerRect = this.table.tHead.getBoundingClientRect();
       const tableRect = this.table.getBoundingClientRect();
       const scrollerRect = this.scroller.getBoundingClientRect();
       const cloneHeight = headerRect.height || this.cloneShell.getBoundingClientRect().height;
-      const active = headerRect.top <= offset && tableRect.bottom > offset;
+      const { active, top } = placement({
+        edge, headerTop: headerRect.top, tableBottom: tableRect.bottom, cloneHeight
+      });
 
       if (!active) {
         this.cloneShell.style.display = "none";
@@ -102,7 +154,6 @@
 
       this.syncColumnWidths();
 
-      const top = Math.min(offset, tableRect.bottom - cloneHeight);
       const translateX = tableRect.left - scrollerRect.left;
 
       this.cloneShell.style.display = "block";
@@ -119,12 +170,17 @@
   function bootStickyTables() {
     startTableObserver();
 
-    if (navResizeObserver) navResizeObserver.disconnect();
+    // EVERY LAYER OF THE PINNED STACK, not the header alone: a bar above the
+    // header that grows or goes moves the edge too. Re-observed on every boot.
+    if (pinResizeObserver) pinResizeObserver.disconnect();
+    pinResizeObserver = null;
     if (window.ResizeObserver) {
+      const layers = new Set(document.querySelectorAll("[data-pin]"));
       const header = document.querySelector("header");
-      if (header) {
-        navResizeObserver = new ResizeObserver(scheduleUpdate);
-        navResizeObserver.observe(header);
+      if (header) layers.add(header);
+      if (layers.size) {
+        pinResizeObserver = new ResizeObserver(() => updateAll());
+        layers.forEach((layer) => pinResizeObserver.observe(layer));
       }
     }
 
@@ -187,13 +243,19 @@
   document.addEventListener("turbo:load", bootStickyTables);
   document.addEventListener("DOMContentLoaded", bootStickyTables);
   document.addEventListener("turbo:before-cache", () => {
-    if (navResizeObserver) navResizeObserver.disconnect();
+    if (pinResizeObserver) pinResizeObserver.disconnect();
     if (tableMutationObserver) tableMutationObserver.disconnect();
-    navResizeObserver = null;
+    pinResizeObserver = null;
     tableMutationObserver = null;
     stickyTables.forEach((stickyTable) => stickyTable.destroy());
     stickyTables = [];
   });
+  // A STACK REPUBLISH RE-PLACES THE CLONE. The refresh is the timeline header
+  // changing its pinned height (on start, which is the restored-scroll case);
+  // the publish carries the reading the publisher just made, so the clone moves
+  // in the same frame and with the same number.
+  document.addEventListener(PINNED_STACK_REFRESH, scheduleUpdate);
+  document.addEventListener(PINNED_STACK_PUBLISHED, (event) => updateAll(event.detail || undefined));
   window.addEventListener("scroll", scheduleUpdate, { passive: true });
   window.addEventListener("resize", scheduleUpdate, { passive: true });
 })();

data/app/javascript/studio/pinned_stack.js

@@ -232,6 +232,23 @@ if (typeof window !== 'undefined') {
 // without its box resizing, which the ResizeObserver cannot see.
 export var REFRESH_EVENT = 'studio:pinned-stack-refresh';
 
+// What this publisher fires on the document after a publish that MOVED the
+// stack: its bottom, whether the header is on the scroll timeline, or its
+// travel. The detail is the reading it just made, { bottom, timeline, travel },
+// the same shape window.studioPinnedStack.read() gives. It is for a SCRIPT that
+// positions off the stack (studio/sticky_table_header's clone): a value written
+// to the root reaches CSS on its own, but a script has to be told, and without
+// this it heard only of a scroll, a resize or a box it observed itself.
+// Fired synchronously from inside the publish, so a listener that places
+// something lands it in the same frame. Not fired when nothing moved, so a
+// scroll frame on the timeline (where the stack never moves) fires nothing.
+export var PUBLISHED_EVENT = 'studio:pinned-stack-published';
+
+// The key a publish is compared on, so an unchanged stack fires nothing.
+export function publishedKey(reading) {
+  return reading.stack + '|' + (reading.timeline ? 1 : 0) + '|' + reading.travel;
+}
+
 var started = false
 
 // THE READERS OF THE STACK, found rather than declared.
@@ -477,11 +494,19 @@ export function startPinnedStack() {
     }
   }
 
+  var lastPublished = null;
   function publishAll() {
     var reading = readStack();
     var pins = reading.pins;
     write(pins, reading.stack, reading.timeline, reading.travel);
     syncObserver(pins);
+    var key = publishedKey(reading);
+    if (key !== lastPublished) {
+      lastPublished = key;
+      document.dispatchEvent(new CustomEvent(PUBLISHED_EVENT, {
+        detail: { bottom: reading.stack, timeline: reading.timeline, travel: reading.travel }
+      }));
+    }
   }
 
   // Observe whatever is pinned RIGHT NOW. observe() on an already-observed node

data/app/views/layouts/studio/_head.html.erb

@@ -180,7 +180,10 @@
 
 <%= stylesheet_link_tag "tailwind", "data-turbo-track": "reload" %>
 <%= stylesheet_link_tag "application", "data-turbo-track": "reload" %>
-<% if Studio.sticky_table_headers %>
+<%# config.sticky_table_headers, unless the caller answers for this render with
+    the sticky_table_headers local (true or false; nil defers to the config). %>
+<% sticky_table_headers = local_assigns[:sticky_table_headers].nil? ? Studio.sticky_table_headers : local_assigns[:sticky_table_headers] %>
+<% if sticky_table_headers %>
   <%= stylesheet_link_tag "studio/sticky_table_header", "data-turbo-track": "reload" %>
 <% end %>
 <%= javascript_importmap_tags %>
@@ -253,6 +256,6 @@
     day, 2026-08-15). This removes a real source of run-to-run variance; it does NOT
     claim to be that flake's cause, and the remaining suspect there is untouched. %>
 <%= javascript_include_tag "studio/alpine", defer: true, "data-turbo-track": "reload" %>
-<% if Studio.sticky_table_headers %>
+<% if sticky_table_headers %>
   <%= javascript_include_tag "studio/sticky_table_header", defer: true, "data-turbo-track": "reload" %>
 <% end %>

data/app/views/studio/profiles/_identity_mini.html.erb

@@ -9,10 +9,10 @@
     push every row down by 56px whether or not it is showing. Fixed takes it out
     of flow: nothing moves, and the bar simply is not there until it is.
 
-    Pinned to `var(--nav-h, 0px)` — the height the host navbar publishes, which
-    /admin/style already uses to stick its section nav. The 0px fallback means an
-    app that publishes nothing gets a bar at the top of the viewport rather than
-    a broken one.
+    Pinned to the header's bottom edge, `var(--nav-bottom, var(--nav-h, 0px))`
+    (studio/profiles/_identity_styles says why the edge and not the height). The
+    0px fallback means an app that publishes nothing gets a bar at the top of the
+    viewport rather than a broken one.
 
     THE IDENTITY HALF IS aria-hidden, and only that half. It duplicates content
     that is already on the page and already reachable: the full card above is the

data/app/views/style/index.html.erb

@@ -66,13 +66,16 @@
     </p>
   </header>
 
-  <%# Section nav — sticky under the host navbar (--nav-h, 0 fallback). A pill per
+  <%# Section nav — sticky under the whole pinned stack (--pin-stack-bottom; then
+      --nav-bottom and --nav-h for a host on an older publisher; then 0). Not --nav-h first: that
+      is the header's HEIGHT, and chrome stacked above the header would sit over
+      the nav by its own height. A pill per
       section; the row scrolls horizontally on narrow screens, its edges softened
       by the .fade-edge-x primitive. Order leads with Theme (the color foundation).
       It sits at --z-sticky, above --z-raised, so the live hold button's portal
       bubbles scroll under it rather than over it. %>
   <nav class="sticky -mx-4 px-4 py-3 bg-surface border-y border-subtle"
-       style="top: var(--nav-h, 0px); z-index: var(--z-sticky, 30)" aria-label="Style guide sections">
+       style="top: var(--pin-stack-bottom, var(--nav-bottom, var(--nav-h, 0px))); z-index: var(--z-sticky, 30)" aria-label="Style guide sections">
     <div class="fade-edge-x overflow-x-auto">
       <div class="flex items-center gap-2 min-w-max">
         <% sections.each do |anchor, label| %>

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.111.1.rc1"
+  VERSION = "0.111.2.rc1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.111.1.rc1
+  version: 0.111.2.rc1
 platform: ruby
 authors:
 - Alex McRitchie
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-17 00:00:00.000000000 Z
+date: 2026-10-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails