studio-engine 0.90.0 → 0.91.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c11c676d845c483117f043e7925f84cc0d7128dfa170740dd3d3c1c484438259
-  data.tar.gz: a873622a9676a51d1864612008e09a4e7f8822a371e275b5e0586ea9b252ad9e
+  metadata.gz: 0cf7b3c1fa31a2eb5f9746838c8c4976d026920c986504c674f760c57c73a33d
+  data.tar.gz: c39625c99d384e68eedfee1a31dde4816e6f3aa2f004f6ab2f88c4e10d447b00
 SHA512:
-  metadata.gz: eb5630d5317933c839f352af196f567be745f13c53ba90c503f373ae0869f2084ce0bff41a47489056a85cf36731dd39974f30f7ab553b9f6b43d920f353a6a4
-  data.tar.gz: a4651700a47b3700f99ed6c00f9e56d5e9682b8771843d4156ca1566b66844a03e1d7a846889f3d5283bf301d537e301bc59284149f0ac97a9f0ad8e6fcbed7c
+  metadata.gz: bfeb555efeae9e981014cf5afb73c8e1eb7b01c90d92dc0c1ba6838d5c1acc950ddc908846be93d15d23ac07a9f5acf277c103c3d95b4611e85b758de5c940f0
+  data.tar.gz: 728932ef4510055ab9b8cd3d6f472abe228ee632febfe007251beb242aec114a1e11c77381a63e44167fb7817c79d8d6716d24687e4261b4c660968e23ffef8c

data/CHANGELOG.md

@@ -4,6 +4,17 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.91.0 — 2026-10-06
+
+### Added
+
+- **`fizz_portal: true` on `studio/hold_button`** lifts the bubbles out of a card
+  that clips them: the layers move to `<body>` in a fixed box that tracks the
+  button through scroll and resize, paints one rung above the button's highest
+  ancestor z-index, and mirrors its state and palette. The default is off, so
+  every existing caller renders as before. The style guide's live hold button
+  uses it.
+
 ## 0.90.0 — 2026-10-06
 
 ### Removed

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

@@ -1315,6 +1315,8 @@ body.modal-open { overflow: visible; }
      span.hold-stack            positioning + z-order context
        span.hold-fizz             resting bubble layer   (behind the button)
        span.hold-fizz.hold-fizz-extra   hover-only layer (lively level only)
+       span.hold-fizz-portal      wraps both layers with fizz_portal: true, and
+                                  moves to <body> (see THE PORTAL below)
        button.hold-btn            the button itself, painted OVER the bubbles
          div.hold-icon            progress ring + tick
          ul.hold-text             four sliding labels: idle/hold/done/blocked
@@ -1731,14 +1733,17 @@ body.modal-open { overflow: visible; }
   z-index: 1;
 }
 
-.hold-stack > .hold-fizz {
+.hold-stack > .hold-fizz,
+.hold-stack > .hold-fizz-portal,
+.hold-fizz-portal > .hold-fizz {
   position: absolute;
   inset: 0;
   z-index: 0;
   pointer-events: none;
 }
 
-.hold-stack .fizz-bit {
+.hold-stack .fizz-bit,
+.hold-fizz-portal .fizz-bit {
   position: absolute;
   width: var(--fs, 4px);
   height: var(--fs, 4px);
@@ -1760,17 +1765,20 @@ body.modal-open { overflow: visible; }
 /* Hover and the nudge shake both mean "look at me" — boil for the moment.
    Calm only: lively rests at this boil already and answers hover its own way,
    below, so it must not pick this rule up (it outranks lively's rest rule). */
-.hold-stack:not(.fizz-lively):has(> .hold-btn:hover:not(.process):not(.loading):not(.success):not(.error)) .fizz-bit {
+.hold-stack:not(.fizz-lively):has(> .hold-btn:hover:not(.process):not(.loading):not(.success):not(.error)) .fizz-bit,
+.hold-fizz-portal:not(.fizz-lively).is-hover:not(.is-process):not(.is-loading):not(.is-success):not(.is-error) .fizz-bit {
   animation: fizz-boil calc(var(--ft, 1.8s) * 0.62) linear calc(var(--fd, 0s) * 0.35) infinite;
 }
 
-.hold-stack.fizz-lively .fizz-bit {
+.hold-stack.fizz-lively .fizz-bit,
+.hold-fizz-portal.fizz-lively .fizz-bit {
   animation: fizz-boil calc(var(--ft, 1.8s) * 0.62) linear calc(var(--fd, 0s) * 0.35) infinite;
 }
 
 /* The hover layer keeps running while hidden. It has to: killing the animation
    would snap the bubbles to their base opacity: 0 and leave nothing to fade. */
-.hold-stack > .hold-fizz-extra {
+.hold-stack > .hold-fizz-extra,
+.hold-fizz-portal > .hold-fizz-extra {
   opacity: 0;
   transition: opacity 0.45s ease;
 }
@@ -1778,29 +1786,69 @@ body.modal-open { overflow: visible; }
 /* The guard list is as much the point as the hover: a held, submitting,
    confirmed or blocked button speaks for itself, so the hover crowd fades away
    and leaves the ring and the burst to read cleanly. */
-.hold-stack.fizz-lively:has(> .hold-btn:hover:not(.process):not(.loading):not(.success):not(.error)) > .hold-fizz-extra {
+.hold-stack.fizz-lively:has(> .hold-btn:hover:not(.process):not(.loading):not(.success):not(.error)) > .hold-fizz-extra,
+.hold-fizz-portal.fizz-lively.is-hover:not(.is-process):not(.is-loading):not(.is-success):not(.is-error) > .hold-fizz-extra {
   opacity: 1;
 }
 
 .hold-stack:has(> .hold-btn.nudge) .fizz-bit,
-.hold-stack:has(> .hold-btn.nudge-soft) .fizz-bit {
+.hold-stack:has(> .hold-btn.nudge-soft) .fizz-bit,
+.hold-fizz-portal.is-nudge .fizz-bit,
+.hold-fizz-portal.is-nudge-soft .fizz-bit {
   animation: fizz-boil calc(var(--ft, 1.8s) * 0.55) linear calc(var(--fd, 0s) * 0.25) infinite;
 }
 
 .hold-stack:has(> .hold-btn.process) .fizz-bit,
-.hold-stack:has(> .hold-btn.loading) .fizz-bit {
+.hold-stack:has(> .hold-btn.loading) .fizz-bit,
+.hold-fizz-portal.is-process .fizz-bit,
+.hold-fizz-portal.is-loading .fizz-bit {
   animation: fizz-boil calc(var(--ft, 1.8s) * 0.45) linear calc(var(--fd, 0s) * 0.2) infinite;
 }
 
-.hold-stack:has(> .hold-btn.success) .fizz-bit {
+.hold-stack:has(> .hold-btn.success) .fizz-bit,
+.hold-fizz-portal.is-success .fizz-bit {
   animation: fizz-burst 1.1s cubic-bezier(0.12, 0.72, 0.24, 1) forwards;
 }
 
-.hold-stack:has(> .hold-btn.error) .fizz-bit {
+.hold-stack:has(> .hold-btn.error) .fizz-bit,
+.hold-fizz-portal.is-error .fizz-bit {
   animation: none;
   opacity: 0;
 }
 
+/* THE PORTAL (studio/hold_button, fizz_portal: true). A button inside an
+   overflow-hidden card has its bubbles cut off at the card's edge, because the
+   layer is absolutely positioned inside the card's clip. With the option set,
+   the button's script moves the layers out of the stack into one fixed box on
+   <body> that tracks the stack's rect, so the bubbles rise past the card's edge
+   instead.
+
+   Out of the stack, the state rules above cannot read the button through
+   :has(), so the script mirrors its state onto the box as .is-process,
+   .is-loading, .is-success, .is-error, .is-nudge, .is-nudge-soft and .is-hover,
+   and copies the stack's --fizz-c-* palette onto it.
+
+   It paints one rung above the highest z-index among the button's ancestors
+   (never below --z-raised), which the script sets inline. A page's own sticky
+   or fixed bar must therefore sit ABOVE --z-raised (--z-sticky is the rung for
+   one); a bar at z 20 or lower, such as Tailwind's sticky z-10 or z-20, ties or
+   loses to the box, and the bubbles paint over it. Painting above the
+   button would put bubbles on its face, so the clip path cuts the button's own
+   rect out of the box: the bubbles show only outside it, as they do in the
+   stack. The 50vmax margin is the room they have to rise. */
+.hold-fizz-portal.is-portaled {
+  position: fixed;
+  top: 0;
+  left: 0;
+  z-index: var(--z-raised, 20);
+  pointer-events: none;
+  clip-path: polygon(evenodd,
+    -50vmax -50vmax, calc(100% + 50vmax) -50vmax,
+    calc(100% + 50vmax) calc(100% + 50vmax), -50vmax calc(100% + 50vmax),
+    -50vmax -50vmax,
+    0 0, 100% 0, 100% 100%, 0 100%, 0 0);
+}
+
 @keyframes hold-tick {
   100% { transform: rotate(-90deg) translate(0, -5px) scale(var(--progress-scale)); }
 }
@@ -1867,7 +1915,9 @@ body.modal-open { overflow: visible; }
    it not to. */
 @media (prefers-reduced-motion: reduce) {
   .hold-stack .fizz-bit,
-  .hold-stack .hold-fizz-extra {
+  .hold-stack .hold-fizz-extra,
+  .hold-fizz-portal .fizz-bit,
+  .hold-fizz-portal .hold-fizz-extra {
     animation: none !important;
     opacity: 0 !important;
     transition: none !important;

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

@@ -39,6 +39,13 @@
                          layer, for a button that should not compete.
     fizz_colors        - Up to 12 CSS colors the bubbles wear, as a static
                          array (default: none = the built-in candy palette).
+    fizz_portal        - Lift the bubbles out of the stack into a fixed layer on
+                         <body> that tracks the button (default: false). For a
+                         button inside an overflow-hidden card, whose bubbles
+                         are otherwise cut off at the card's edge: with it set
+                         they rise past the edge. The button, its timers and its
+                         states are the same either way. See THE PORTAL in
+                         engine-motion.css.
     fizz_bind          - Alpine expression bound to the stack's :style, for a
                          palette that changes at runtime (default: none). The
                          turf-monster's board passes "fizzPalette", mapping
@@ -65,6 +72,7 @@
 <% fizz_colors ||= nil %>
 <% fizz_bind ||= nil %>
 <% fizz_level ||= :lively %>
+<% 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)
@@ -75,11 +83,17 @@
     transform makes it a stacking context), so the bubbles have to be a
     sibling the button paints over — they only show where they escape its
     edges, like carbonation coming off the sides. %>
-<span class="hold-stack<%= " fizz-lively" if fizz_level.to_s == "lively" %>"<% if fizz_bind %> :style="<%= fizz_bind %>"<% end %><% if fizz_style.present? %> style="<%= fizz_style %>"<% end %>>
+<span class="hold-stack<%= " fizz-lively" if fizz_level.to_s == "lively" %>"<% if fizz_bind %> :style="<%= fizz_bind %>"<% end %><% if fizz_style.present? %> style="<%= fizz_style %>"<% end %><% if fizz_portal %> data-fizz-portal x-init="window.studioFizzPortal && window.studioFizzPortal.mount($el)"<% end %>>
   <%# Fizz layer — bubbles that simmer at rest, boil while the button is held,
       and burst outward on success. Purely decorative, so it is aria-hidden and
       pointer-events:none; the table behind it is seeded per hold_id (see Studio::FizzHelper). %>
   <% if fizz %>
+    <%# With fizz_portal the layers ride one wrapper, which the script below
+        moves to <body>. Until it does, the wrapper sits in the stack exactly
+        where the layers would. %>
+    <% if fizz_portal %>
+    <span class="hold-fizz-portal<%= " fizz-lively" if fizz_level.to_s == "lively" %>" aria-hidden="true">
+    <% end %>
     <%= render "studio/fizz_layer", seed: hold_id %>
     <%# Lively's hover doubles the COUNT, not the speed: a second scatter that
         rests invisible, fades in over the gaps in the first, and fades back
@@ -87,6 +101,9 @@
     <% if fizz_level.to_s == "lively" %>
       <%= render "studio/fizz_layer", seed: "#{hold_id}~extra", extra: true %>
     <% end %>
+    <% if fizz_portal %>
+    </span>
+    <% end %>
   <% end %>
 <button class="hold-btn"
         data-hold-id="<%= hold_id %>"
@@ -236,6 +253,151 @@
       Object.keys(nudgeTimers).forEach(function(id) { stopNudgeCycle(id); });
     });
 
+    // ── The fizz portal (fizz_portal: true) ─────────────────────────────
+    // Moves a stack's bubble layers to the document body in one fixed box that tracks the
+    // stack's rect, so a card's overflow clip cannot cut them off. The box
+    // mirrors the button's state classes and the stack's palette, because the
+    // CSS can no longer read either through the stack. engine-motion.css,
+    // THE PORTAL, holds the other half.
+    var PORTAL_STATES = ['process', 'loading', 'success', 'error', 'nudge', 'nudge-soft'];
+    var portals = [];
+
+    // One rung above the highest z-index among the stack's ancestors, so the
+    // bubbles clear the card, the panel or the modal the button sits in,
+    // and never below --z-raised.
+    function portalZ(stack) {
+      var floor = parseInt(getComputedStyle(document.documentElement).getPropertyValue('--z-raised'), 10);
+      var top = isNaN(floor) ? 20 : floor;
+      for (var n = stack.parentElement; n && n !== document.body; n = n.parentElement) {
+        var z = parseInt(getComputedStyle(n).zIndex, 10);
+        if (!isNaN(z) && z + 1 > top) top = z + 1;
+      }
+      return top;
+    }
+
+    function syncPortalState(p) {
+      PORTAL_STATES.forEach(function(s) {
+        p.box.classList.toggle('is-' + s, p.button.classList.contains(s));
+      });
+    }
+
+    function syncPortalPalette(p) {
+      var cs = getComputedStyle(p.stack);
+      for (var i = 1; i <= <%= Studio::FizzHelper::SLOTS %>; i++) {
+        var v = cs.getPropertyValue('--fizz-c-' + i).trim();
+        if (v) p.box.style.setProperty('--fizz-c-' + i, v);
+        else p.box.style.removeProperty('--fizz-c-' + i);
+      }
+    }
+
+    function placePortal(p) {
+      if (!p.stack.isConnected) { unmountPortal(p, false); return; }
+      var r = p.stack.getBoundingClientRect();
+      var shown = p.visible && r.width > 0 && r.height > 0;
+      p.box.style.visibility = shown ? '' : 'hidden';
+      if (shown) {
+        p.box.style.transform = 'translate(' + r.left + 'px, ' + r.top + 'px)';
+        p.box.style.width = r.width + 'px';
+        p.box.style.height = r.height + 'px';
+        if (p.parked) { clearInterval(p.parked); p.parked = null; }
+        p.frame = requestAnimationFrame(function() { placePortal(p); });
+      } else {
+        p.frame = null;
+        // Parked: no frames run, so nothing would notice the stack leaving the
+        // DOM (an x-if, a Turbo stream, a closed modal) until the next page
+        // load. A slow check tears the box and its observers down when it does.
+        if (!p.parked) {
+          p.parked = setInterval(function() {
+            if (!p.stack.isConnected) unmountPortal(p, false);
+          }, 1000);
+        }
+      }
+    }
+
+    function unmountPortal(p, restore) {
+      if (p.frame) cancelAnimationFrame(p.frame);
+      if (p.parked) clearInterval(p.parked);
+      p.observers.forEach(function(o) { o.disconnect(); });
+      p.button.removeEventListener('mouseenter', p.enter);
+      p.button.removeEventListener('mouseleave', p.leave);
+      if (restore && p.stack.isConnected) {
+        // Back where the server rendered it, with nothing the script added,
+        // so a cached snapshot restores to the markup it came from.
+        p.box.className = p.box.className.replace(/\s*\bis-[\w-]+/g, '');
+        p.box.removeAttribute('style');
+        p.box.removeAttribute('data-fizz-portal-for');
+        p.stack.insertBefore(p.box, p.stack.firstChild);
+      } else {
+        p.box.remove();
+      }
+      delete p.stack._fizzPortal;
+      portals = portals.filter(function(q) { return q !== p; });
+    }
+
+    function mountPortal(stack) {
+      if (stack._fizzPortal) return stack._fizzPortal;
+      var box = stack.querySelector(':scope > .hold-fizz-portal');
+      var button = stack.querySelector(':scope > .hold-btn');
+      if (!box || !button) return null;
+
+      var p = { stack: stack, box: box, button: button, visible: true, frame: null, parked: null, observers: [] };
+      stack._fizzPortal = p;
+      portals.push(p);
+
+      document.body.appendChild(box);
+      box.classList.add('is-portaled');
+      box.setAttribute('data-fizz-portal-for', button.dataset.holdId || 'hold');
+      box.style.zIndex = portalZ(stack);
+      syncPortalState(p);
+      syncPortalPalette(p);
+
+      p.enter = function() { box.classList.add('is-hover'); };
+      p.leave = function() { box.classList.remove('is-hover'); };
+      button.addEventListener('mouseenter', p.enter);
+      button.addEventListener('mouseleave', p.leave);
+
+      var states = new MutationObserver(function() { syncPortalState(p); });
+      states.observe(button, { attributes: true, attributeFilter: ['class'] });
+      var palette = new MutationObserver(function() { syncPortalPalette(p); });
+      palette.observe(stack, { attributes: true, attributeFilter: ['style'] });
+      p.observers.push(states, palette);
+
+      // Track the rect every frame while the stack is on screen: a visible
+      // portal reads one rect per frame. Park the box while the stack is not
+      // on screen (scrolled away, inside a closed panel, or clipped out of a
+      // scroll container): no frames, only a once-a-second check that the
+      // stack is still in the DOM.
+      if ('IntersectionObserver' in window) {
+        var seen = new IntersectionObserver(function(entries) {
+          p.visible = entries[entries.length - 1].isIntersecting;
+          if (!p.stack.isConnected) { unmountPortal(p, false); return; }
+          if (p.visible && !p.frame) placePortal(p);
+          if (!p.visible) placePortal(p);
+        });
+        seen.observe(stack);
+        p.observers.push(seen);
+      }
+      placePortal(p);
+      return p;
+    }
+
+    function mountAllPortals() {
+      portals.slice().forEach(function(p) { if (!p.stack.isConnected) unmountPortal(p, false); });
+      document.querySelectorAll('.hold-stack[data-fizz-portal]').forEach(mountPortal);
+    }
+
+    window.studioFizzPortal = {
+      mount: mountPortal,
+      mountAll: mountAllPortals,
+      count: function() { return portals.length; }
+    };
+    document.addEventListener('turbo:load', mountAllPortals);
+    document.addEventListener('turbo:before-cache', function() {
+      portals.slice().forEach(function(p) { unmountPortal(p, true); });
+    });
+    if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', mountAllPortals);
+    else mountAllPortals();
+
     window.holdBtnStart = function(el) {
       var holdId = el.dataset.holdId || 'hold';
       var scope = el.closest('[x-data]');

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

@@ -344,6 +344,8 @@
         brand — and every color also reads a <code class="font-mono text-2xs">--hold-*</code>
         input, so one instance can be re-themed from any ancestor.
         <code class="font-mono text-2xs">prefers-reduced-motion</code> switches the bubbles off.
+        Inside a card that clips, pass <code class="font-mono text-2xs">fizz_portal: true</code>
+        and the bubbles rise past the card&rsquo;s edge instead of stopping at it.
       </p>
     </div>
     <div class="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
@@ -360,12 +362,14 @@
         </div>
       <% end %>
 
-      <%# 2. The button itself, live: press and hold for two seconds. %>
+      <%# 2. The button itself, live: press and hold for two seconds. The card
+          clips, so this one sets fizz_portal and its bubbles rise past the
+          card's edge. %>
       <%= render layout: "style/specimen",
             locals: { klass: ".hold-btn  (studio/hold_button)",
-                      usage: %(render "studio/hold_button", hold_id: "confirm", duration: 2000) } do %>
+                      usage: %(render "studio/hold_button", hold_id: "confirm", duration: 2000, fizz_portal: true) } do %>
         <div class="w-full max-w-xs" x-data="{ submitting: false }">
-          <%= render "studio/hold_button", hold_id: "style-hold", duration: 2000,
+          <%= render "studio/hold_button", hold_id: "style-hold", duration: 2000, fizz_portal: true,
                 default_text: "Hold to Confirm", hold_text: "Almost there…", success_text: "Confirmed!" %>
           <button type="button" class="btn btn-neutral btn-sm mt-3 mx-auto block"
                   @click="document.querySelector('.hold-btn[data-hold-id=style-hold]').classList.remove('process','success','error','loading')">Reset</button>

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

@@ -65,9 +65,11 @@
 
   <%# Section nav — sticky under the host navbar (--nav-h, 0 fallback). 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). %>
-  <nav class="sticky z-20 -mx-4 px-4 py-3 bg-surface border-y border-subtle"
-       style="top: var(--nav-h, 0px)" aria-label="Style guide sections">
+      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">
     <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.90.0"
+  VERSION = "0.91.0"
 end

metadata

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