studio-engine 0.129.0 → 0.130.0

data/app/helpers/studio/fizz_helper.rb

@@ -73,6 +73,11 @@ module Studio
         "--fd:#{bit[:delay]}s;--ft:#{bit[:duration]}s;--fc:#{fizz_color(bit)}"
     end
 
+    # A fixed palette as the inline style a stack carries: `--fizz-c-1:red;...`.
+    def fizz_stack_style(colors)
+      Array(colors).first(SLOTS).each_with_index.map { |c, i| "--fizz-c-#{i + 1}:#{c}" }.join(";")
+    end
+
     private
 
     # Where in its own zone a bubble sits. The outer columns each throw one

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

@@ -11,10 +11,10 @@ import { activeIndex } from "studio/style_section_nav"
 
 const ACTIVE = "btn-primary"
 const REST = "btn-neutral"
-// A jump lands a section by its scroll-margin (--nav-h + 5rem), read while the
-// header may still be tall; the header then collapses, so the row rises and the
-// section does not. The full margin keeps the clicked section past the line,
-// with the collapse's height to spare, for any later scroll or resize.
+// A jump lands a section by its scroll margin, the stack's pinned heights, read while the
+// header may still be tall; the header then collapses, so the row rises and the section
+// does not (76px on the hub at phone width). The slack keeps the clicked section past the
+// line, for any later scroll or resize.
 const LINE_SLACK = 80
 
 export default class extends Controller {

data/app/javascript/studio/pinned_stack.js

@@ -37,6 +37,11 @@
 // SIZE something as tall as the header; use --nav-bottom to START something
 // underneath it. Same distinction for --pin-<name>-h vs --pin-<name>-bottom.
 //
+// THE SECTION LAYER (studio/_section_header, docs/PAGE_HEADER.md) IS THE ONE LAYER
+// THAT IS NOT A data-pin. A page has many section headers and only one is stuck, so
+// each carries `data-pin-section`, and together they publish as one layer, `section`.
+// See stuckSection below.
+//
 // Started once per document by studio/application. The listeners it adds live
 // for the document, and a Turbo visit republishes through them rather than
 // starting it again.
@@ -152,6 +157,62 @@ export function documentIndex(list, el) {
   return list.length;
 }
 
+// THE SECTION LAYER: MANY HEADERS, ONE LAYER, ONLY THE STUCK ONE COUNTS.
+//
+// A section header is sticky inside its own <section>, so the browser does the
+// swap: the next section's header arrives as the last one is pushed out. It joins
+// the stack so that a table's sticky header and any other reader of
+// --pin-stack-bottom sit under it. It cannot be a plain [data-pin]: composed() takes
+// the lowest edge of every layer, so a header waiting below the fold would drag
+// --pin-stack-bottom down the page, and headers sharing a name would overwrite each
+// other's values.
+//
+// So all of them are one layer named `section`, always in the registry while any is
+// on the page. The roster never changes per swap, so a swap is not a structural write,
+// and --pin-section-top, which every header positions off, stays published when none
+// is stuck. That layer's height is 0 until one is stuck, and then it is the part of the
+// bar still below the layers above, so a header being pushed out gives its room back
+// frame by frame.
+//
+// rects are { top, bottom, parentTop, parentBottom }, in page order; line is
+// --pin-section-top. A header is stuck once it has left its place in the flow and part
+// of it still shows below the line. Its section's top is that place, since it is the
+// section's first child and the section has no top padding.
+//
+// NEITHER FACT READS THE HEADER'S OWN EDGE AGAINST THE LINE. While the navbar collapses
+// the line moves first and the header's `top` follows a publish later, so a comparison
+// would drop the bar for the whole collapse, and a bottom read off the rect would be
+// published one step stale, with nothing left to correct it once the page is still. So
+// the bar's bottom is what sticky will make it: one height under the line, or the end of
+// its section while that pushes it out.
+export function sectionBottom(r, line) {
+  return Math.min(line + (r.bottom - r.top), r.parentBottom);
+}
+
+export function stuckSection(rects, line) {
+  var found = -1;
+  for (var i = 0; i < rects.length; i++) {
+    var r = rects[i];
+    if (r.top - r.parentTop > 0.5 && sectionBottom(r, line) > line + 0.5) found = i;
+  }
+  return found;
+}
+
+function measureSections(nodes, line) {
+  // Below the short-screen floor, or before the publisher runs, the CSS leaves these in
+  // the flow (engine.css, @utility section-header). A header scrolling past the line
+  // there is not stuck, so it must not count.
+  if (window.getComputedStyle(nodes[0]).position !== 'sticky') return null;
+  var rects = [];
+  for (var i = 0; i < nodes.length; i++) {
+    var r = nodes[i].getBoundingClientRect();
+    var parent = nodes[i].parentElement.getBoundingClientRect();
+    rects.push({ top: r.top, bottom: r.bottom, parentTop: parent.top, parentBottom: parent.bottom });
+  }
+  var at = stuckSection(rects, line);
+  return at < 0 ? null : { el: nodes[at], bottom: sectionBottom(rects[at], line) };
+}
+
 // THE REGISTRY IS DERIVED, NEVER CACHED — and that is a correctness rule.
 //
 // This used to build a `pins` array once and hold each element by reference
@@ -168,8 +229,9 @@ export function documentIndex(list, el) {
 // reference IMPOSSIBLE rather than merely unlikely: there is no window between
 // a DOM patch and a re-scan in which this can be pointed at the wrong node.
 //
-// Returns { pins, stack, timeline }: every layer measured and composed, the
-// stack's bottom, and whether the header is on the scroll timeline.
+// Returns { pins, stack, timeline, travel, sections, stuck }: every layer measured and
+// composed, the stack's bottom, whether the header is on the scroll timeline and how
+// far it travels, the section headers, and which of them is stuck.
 export function readStack() {
   var header = document.querySelector('header');
   var timeline = onTimeline(header);
@@ -191,11 +253,28 @@ export function readStack() {
   // never publish at all. Both live consumers own their header, so it is
   // adopted as a pin even when it does not ask to be.
   if (header && !headerPinned) list.splice(documentIndex(list, header), 0, measurePin(header, 'nav', true, timeline));
+  // In the registry at height 0 first, so the composition says where its line is.
+  var sections = document.querySelectorAll('[data-pin-section]');
+  var section = null;
+  if (sections.length) {
+    section = { el: sections[0], name: 'section', legacy: false, h: 0, bottom: 0 };
+    list.splice(documentIndex(list, sections[0]), 0, section);
+  }
+  var stack = timeline ? pinnedAt(list) : composed(list);
+  var stuck = section ? measureSections(sections, section.top) : null;
+  if (stuck) {
+    section.el = stuck.el;
+    section.h = stuck.bottom - section.top;
+    section.bottom = stuck.bottom;
+    stack = timeline ? pinnedAt(list) : composed(list);
+  }
   return {
     pins: list,
-    stack: timeline ? pinnedAt(list) : composed(list),
+    stack: stack,
     timeline: timeline,
-    travel: timeline ? timelineTravel(header) : 0
+    travel: timeline ? timelineTravel(header) : 0,
+    sections: sections,
+    stuck: stuck ? stuck.el : null
   };
 }
 
@@ -414,6 +493,9 @@ export function startPinnedStack() {
     settleTimer = null;
     publishAll();
     releaseFollowers();
+    // That publish measured the layers while they still held their last copies. Given back,
+    // they move to the root's values, so their edges are read once more.
+    schedule();
   }
 
   // The registry and the measurement are module-level (readStack, measurePin
@@ -505,12 +587,38 @@ export function startPinnedStack() {
     }
   }
 
+  // WHO WEARS THE BAR, written after every read of the publish. The box does not change
+  // with the attribute, so this resizes nothing and moves nothing. The root's attribute
+  // squares the page row's corners against the bar under it (engine.css, glass).
+  function syncSections(reading) {
+    for (var i = 0; i < reading.sections.length; i++) {
+      var node = reading.sections[i];
+      var on = node === reading.stuck;
+      if (node.hasAttribute('data-stuck') !== on) node.toggleAttribute('data-stuck', on);
+    }
+    var root = document.documentElement;
+    if (root.hasAttribute('data-pin-section-stuck') !== !!reading.stuck) root.toggleAttribute('data-pin-section-stuck', !!reading.stuck);
+  }
+
   var lastPublished = null;
+  var lastTops = null;
   function publishAll() {
+    // What lets a section header stick at all (engine.css): with no publisher its bar
+    // would never come, and it would lay a clear title over the page. Before the read,
+    // so the first publish on a restored scroll already sees it sticky.
+    var html = document.documentElement;
+    if (!html.hasAttribute('data-pin-live')) html.setAttribute('data-pin-live', '');
     var reading = readStack();
     var pins = reading.pins;
     write(pins, reading.stack, reading.timeline, reading.travel);
+    syncSections(reading);
     syncObserver(pins);
+    // A LAYER UNDER A LAYER SETTLES ONE PUBLISH LATER. A new --pin-page-top moves the page
+    // row without resizing it, so nothing wakes the publisher to read the row's new edge,
+    // and the layer under the row would keep a stale line once the page is still. So a
+    // publish that moved any layer's top asks for one more frame. It ends when none moved.
+    var tops = pins.map(function (p) { return p.top; }).join('|');
+    if (tops !== lastTops) { lastTops = tops; schedule(); }
     var key = publishedKey(reading);
     if (key !== lastPublished) {
       lastPublished = key;

data/app/views/studio/_fizz.html.erb

@@ -0,0 +1,26 @@
+<%#
+  Fizz around any button: bubbles that rise from behind it. Render it as a layout,
+  with the button as the block.
+
+    render layout: "studio/fizz", locals: { seed: "save" } do
+      <button class="btn btn-primary">Save</button>
+    end
+
+  Locals:
+    seed   - the string the bubble table is seeded from, so the scatter is stable
+             for this button and differs from its neighbours
+    level  - :lively (default), which boils at rest and adds a layer on hover, or
+             :calm, which simmers at rest and boils on hover
+    colors - optional palette, up to 18, three per zone (--fizz-c-1..18)
+
+  Decoration only. The hold button keeps its own stack (studio/_hold_button).
+%>
+<% lively = local_assigns.fetch(:level, :lively).to_s == "lively" %>
+<% fizz_style = fizz_stack_style(local_assigns[:colors]) %>
+<span class="fizz-stack<%= " fizz-lively" if lively %>"<% if fizz_style.present? %> style="<%= fizz_style %>"<% end %>>
+  <%= render "studio/fizz_layer", seed: seed, neutral: true %>
+  <% if lively %>
+    <%= render "studio/fizz_layer", seed: "#{seed}~extra", extra: true, neutral: true %>
+  <% end %>
+  <%= yield %>
+</span>

data/app/views/studio/_fizz_layer.html.erb

@@ -7,10 +7,13 @@
             in each other's gaps rather than on top of each other)
     extra - true for the hover-only layer, which rests invisible and fades in
             when the pointer arrives (default: false)
+    neutral - true inside a .fizz-stack (studio/_fizz), a button with no hold, so
+            the layer carries the neutral class names (default: false)
 
   The two layers also split each zone's three colour slots: the resting one
   takes the first, the hover one alternates the second and third.
   Decoration only: aria-hidden here, pointer-events off in CSS.
 %>
 <% extra ||= false %>
-<span class="hold-fizz<%= " hold-fizz-extra" if extra %>" aria-hidden="true"><% fizz_bits(seed, layer: extra ? :hover : :base).each do |bit| %><i class="fizz-bit" style="<%= fizz_bit_style(bit) %>"></i><% end %></span>
+<% neutral ||= false %>
+<span class="<%= neutral ? "fizz-layer" : "hold-fizz" %><%= (neutral ? " fizz-layer-extra" : " hold-fizz-extra") if extra %>" aria-hidden="true"><% fizz_bits(seed, layer: extra ? :hover : :base).each do |bit| %><i class="fizz-bit" style="<%= fizz_bit_style(bit) %>"></i><% end %></span>

data/app/views/studio/_hold_button.html.erb

@@ -74,8 +74,7 @@
 <% fizz_portal = fizz && local_assigns[:fizz_portal] %>
 <%# Static palette (gallery, or any call site with fixed colors). A runtime
     palette rides fizz_bind instead. %>
-<% fizz_style = Array(fizz_colors).first(Studio::FizzHelper::SLOTS)
-                                  .each_with_index.map { |c, i| "--fizz-c-#{i + 1}:#{c}" }.join(";") %>
+<% fizz_style = fizz_stack_style(fizz_colors) %>
 
 <%# The stack exists so the fizz can sit BEHIND the button. Inside the button
     a negative z-index still paints above its own background (the button's

data/app/views/studio/_page_header.html.erb

@@ -1,6 +1,7 @@
 <%# locals: (title:, meta: nil, meta_title: nil, label: nil, tabs: [], tabs_data: {}, actions_html: nil, data: {}, row_class: "-mx-4 px-4") %>
-<%# THE PAGE HEADER: the second layer of the triple stack (docs/PAGE_HEADER.md).
-    navbar, then this row, then a table's sticky header, each below the last.
+<%# THE PAGE HEADER: the second layer of the pinned stack (docs/PAGE_HEADER.md).
+    navbar, then this row, then a section's header (studio/_section_header), then a
+    table's sticky header, each below the last.
 
     AT REST it has no background and no border: a title on the left, tabs on the
     right. ONCE STUCK under the navbar it takes the bar. Its box never changes

data/app/views/studio/_section_header.html.erb

@@ -0,0 +1,23 @@
+<%# locals: (title:, level: :h2, row_class: "-mx-4 px-4") %>
+<%# THE SECTION HEADER: a section's title that sticks under the rest of the pinned stack
+    until the next section's header takes its place (docs/PAGE_HEADER.md).
+
+    RENDER IT AS THE FIRST DIRECT CHILD OF ITS <section>. A sticky element travels only
+    inside its parent, and that is what gives the swap: inside a wrapper div, it would
+    leave with the wrapper. No backdrop-filter, transform or overflow on an ancestor.
+
+      title      the heading's text. The heading is the sticky element, so an intro can
+                 follow as its next sibling.
+      level      the tag. A page should stick one level only: one bar at a time.
+      row_class  the bleed. The default fits a container with px-4, as the page row's does.
+
+    AT REST a normal title. STUCK it takes the bar. Its box never changes between the two.
+
+    IT JOINS THE STACK WITH data-pin-section, NOT data-pin. Every header on the page shares
+    one layer, `section`, and only the stuck one counts (studio/pinned_stack, stuckSection).
+    So it positions off --pin-section-top, which also stands when none is stuck. Anything
+    under the stack, such as a table's sticky header, sits under it with no edit. %>
+<%= content_tag(level, title,
+      class: "section-header #{row_class}".strip,
+      style: "top: var(--pin-section-top, var(--nav-bottom, var(--nav-h, 0px))); z-index: calc(var(--z-sticky, 30) - 1)",
+      data: { pin_section: "" }) %>

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

@@ -5,11 +5,9 @@
     An app that does not draw the gallery here (lookbook not in its bundle, or
     production without Studio.lookbook_in_production) says so instead of linking
     to a 404. -%>
-<section id="components" class="space-y-6" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
-  <div class="space-y-1">
-    <h2 class="type-h3 text-heading">Components</h2>
-    <p class="text-muted text-sm max-w-2xl">One preview per state, in the component gallery.</p>
-  </div>
+<section id="components" class="section-target space-y-6">
+  <%= render "studio/section_header", title: "Components" %>
+  <p class="text-muted text-sm max-w-2xl">One preview per state, in the component gallery.</p>
 
   <% if Studio.lookbook_mounted? %>
     <ul class="grid gap-4 sm:grid-cols-2" data-component-previews>

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

@@ -90,12 +90,9 @@
      A reader who assumes dsModals will build a mirror instead: a second copy of
      every card, free to drift from the one the app actually ships, which is the
      opposite of what a living style guide is for. %>
-<section id="host-modals" class="space-y-8" x-data="{}"
-         style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
-  <div class="space-y-1">
-    <h2 class="type-h3 text-heading"><%= Studio.app_name %></h2>
-    <p class="text-muted text-sm max-w-2xl">This app&rsquo;s own modals, from <code class="font-mono text-2xs">app/views/style/host/_modals.html.erb</code>.</p>
-  </div>
+<section id="host-modals" class="section-target space-y-8" x-data="{}">
+  <%= render "studio/section_header", title: Studio.app_name %>
+  <p class="text-muted text-sm max-w-2xl">This app&rsquo;s own modals, from <code class="font-mono text-2xs">app/views/style/host/_modals.html.erb</code>.</p>
 
   <%# The app's content. Reached only when it resolves - style/index.html.erb
       owns that guard, because the section nav needs the same answer. %>

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

@@ -9,11 +9,11 @@
          page when chatting (item 1).
        - an optional row of option toggles lets the user configure the modal
          before opening; their clicks/keys do NOT bubble to the card open (item 2).
-       - an optional active-card GLOW (.studio-team-glow) that reactively lights
+       - an optional active-card GLOW (.edge-rotate-glow) that reactively lights
          when this card represents the currently-open modal + step, and slides to
          the next card as the step machine advances (items 5/6). The glow rides an
          un-clipped wrapper (the card itself is overflow-hidden), mirroring TM's
-         holo-wrap / holo-card split, and fades via --studio-team-glow-opacity so
+         holo-wrap / holo-card split, and fades via --edge-rotate-glow-opacity so
          it transitions smoothly between cards.
 
      Locals:
@@ -53,10 +53,10 @@
 <%# Wrapper — carries the active-card glow (un-clipped) + the shared x-data. %>
 <%# h-full so the card stretches to its grid row's tallest (per-row equal
     height via the grid's default align-items: stretch). %>
-<div class="relative h-full<%= " studio-team-glow rounded-xl" if glow_when %>"
+<div class="relative h-full<%= " edge-rotate-glow rounded-xl" if glow_when %>"
      x-data="<%= card_x_data %>"
      <%# Fail-closed default: a STATIC inline 0 out-specifies the primitive's CSS
-         default (--studio-team-glow-opacity of 1) so the ring is OFF at first
+         default (--edge-rotate-glow-opacity of 1) so the ring is OFF at first
          paint, BEFORE Alpine hydrates the reactive :style below. Without it every
          glow card shows its ring until Alpine boots (the fail-open flash). The
          :style then drives 0 to 0.95 with the 0.4s cross-fade. Keep BOTH.
@@ -67,7 +67,7 @@
          the Turbo-nav store gap fixed in 0.26.1 (style/_modals dual-guards the
          dsModals registration so it survives Turbo visits, not just first load).
          So the guarantee is: static inline 0 PLUS a registered dsModals. %>
-     <% if glow_when %>style="--studio-team-glow-opacity: 0" :style="{ '--studio-team-glow-opacity': (<%= glow_when %>) ? '0.95' : '0' }"<% end %>>
+     <% if glow_when %>style="--edge-rotate-glow-opacity: 0" :style="{ '--edge-rotate-glow-opacity': (<%= glow_when %>) ? '0.95' : '0' }"<% end %>>
   <article
       class="card overflow-hidden flex flex-col h-full<%= " opacity-95" if disabled %><%= " cursor-pointer" if clickable %>"
       <%= 'aria-disabled="true"'.html_safe if disabled %>

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

@@ -150,14 +150,12 @@
     target moved. The engine primitive is untouched; its real submit still posts
     to the app-supplied submit_url. Kept on the section (always mounted) so it
     fires even as the age-gate card closes. %>
-<section id="modals" class="space-y-10" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)"
+<section id="modals" class="section-target space-y-10"
          data-studio-controller="style-modals"
          x-data="{}" @ds-modal-close.window="$store.dsModals.close()"
          @age-verified.window="$store.dsModals.open('entry-confirmed', { txSignature: null, lobbyUrl: null, seedsEarned: 0 })">
-  <div class="space-y-1">
-    <h2 class="type-h3 text-heading">Modals</h2>
-    <p class="text-muted text-sm">Click a card to open the real modal.</p>
-  </div>
+  <%= render "studio/section_header", title: "Modals" %>
+  <p class="text-muted text-sm">Click a card to open the real modal.</p>
 
   <%# ---- The section's own modal host (dsModals) --------------------------
       $store.dsModals is the engine's modal stack under the guide's own name:

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

@@ -33,7 +33,7 @@
   sample_page  = [ [ "Google's header", 0, 200, false ], [ "Select an appointment time", 200, 600, true ],
                    [ "Google's credit lines", 600, 720, false ] ]
 %>
-<section id="site-footer" class="space-y-5" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
+<section id="site-footer" class="section-subtarget space-y-5">
   <div class="space-y-1">
     <h3 class="type-h4 text-heading">Site footer and booking</h3>
     <p class="text-muted text-sm max-w-2xl">One layout line renders the footer, and <code class="font-mono text-2xs">config.booking_url</code> turns on booking.</p>

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

@@ -6,6 +6,7 @@
        klass          (String, required) - the class label, shown prominently with a
                        copy button so an agent can grab the exact class list.
        usage          (String, optional) - a copyable usage snippet.
+       note           (String, optional) - one short sentence on what it does.
        disabled       (Boolean, optional) - render "disabled but present": the
                        primitive stays visible + previewable but is muted/greyed
                        and flagged, for a capability the host app has turned off
@@ -38,6 +39,9 @@
     <% end %>
   </div>
   <div class="border-t border-subtle p-3 space-y-2">
+    <% if local_assigns[:note].present? %>
+      <p class="text-sm text-body"><%= local_assigns[:note] %></p>
+    <% end %>
     <%# Class name — prominent, with a one-click copy so an agent can grab it. %>
     <div class="flex items-start justify-between gap-2" x-data="{ copied: false }">
       <code x-ref="klass" class="font-mono text-xs font-bold text-heading break-all leading-relaxed flex-1 min-w-0"><%= local_assigns[:klass] %></code>

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

@@ -63,11 +63,9 @@
     "stage-shipped"    => [{ title: "SES email backend",    repo: "mcritchie",     who: "ST" }]
   }
 %>
-<section id="tasks" class="space-y-8" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)">
-  <div class="space-y-1">
-    <h2 class="type-h3 text-heading">Tasks</h2>
-    <p class="text-muted text-sm max-w-2xl">The real board primitive in demo mode, so a drag saves nothing.</p>
-  </div>
+<section id="tasks" class="section-target space-y-8">
+  <%= render "studio/section_header", title: "Tasks" %>
+  <p class="text-muted text-sm max-w-2xl">The real board primitive in demo mode, so a drag saves nothing.</p>
 
   <%# ---- The LIVE primitive (demo mode) --------------------------------- %>
   <%# demo: true → drag animates + toasts locally, nothing POSTs. %>

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

@@ -53,11 +53,11 @@
 
   csrf_ok = respond_to?(:protect_against_forgery?) && protect_against_forgery?
 %>
-<section id="theme" class="space-y-8" style="scroll-margin-top: calc(var(--nav-h, 0px) + 5rem)"
+<section id="theme" class="section-target space-y-8"
          x-data="dsThemeEditor(<%= seed_colors.to_json %>)">
+  <%= render "studio/section_header", title: "Theme" %>
   <div class="flex flex-wrap items-start justify-between gap-3">
     <div class="space-y-1">
-      <h2 class="type-h3 text-heading">Theme</h2>
       <p class="text-muted text-sm max-w-2xl">Every specimen on this page restyles from these 7 color roles.</p>
     </div>
     <form action="/admin/theme/regenerate" method="post" accept-charset="UTF-8" @submit.prevent="regenerate($event)">