studio-engine 0.140.0 → 0.141.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 607b184e22c3660009dfc7e342922ca3bdae6b13a7ca7ed32dc618957dfc819a
-  data.tar.gz: 26a6741ca01d65b37d6f16a663f35c6d253f87254af05fd41836d23e2a5ce48b
+  metadata.gz: fdbbb3a4ed38791b34c2acda907501f647b1574dd58c3ae462ebb75a480f20ac
+  data.tar.gz: cd7e60599fd6f9c56896532aa50ab3af7e2032ea0b5b947419f3cfd9609fb642
 SHA512:
-  metadata.gz: 1f6a8450e4862aea8e8f80c214353442eafcf0c56bbcd0d78848dd291fab92ebc95ed41b836b01ba11a6601a66a652cf06153ef97f7e7c4f31910603457572d1
-  data.tar.gz: 24cdd966d0cad48ba9efb03fe6d54c2ec801051c7ccf23f104411fe3a4cf4eac7ea7155b453fb308ba5625be4bd30d7945c83bc2d822026ae4f6b3de194b2f76
+  metadata.gz: 6c4cd34992a2181995c6e111ea61eeef896c210e277a0d6a96ee9842d710af16e401698ac8935684f98ff02a76b100e3be2c48c1f052ec4ee1e2bde2ff405335
+  data.tar.gz: 8bb445755ac725f8455454499ab6987428898e76db15214da7ef930338054954f85b9f0803fe2c3cf3416c592928087cecbe2b994525231265be633acf06bdb1

data/CHANGELOG.md

@@ -4,6 +4,19 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.141.0 — 2026-11-09
+
+### Changed
+
+- **The shared reveal waits need a selector.** `revealed`, `settled` and `arrivalSettled` in `e2e_helpers.js` now refuse a call with no selector. Right after a click the old page is still the document and has revealed too, so a wait with nothing of the new page's to find first read the old page and returned at once. Pass a selector that only the new page has.
+
+### Fixed
+
+- **A caption stage opened on a `#fragment` shows the open slide's caption.** Both carousel controllers load lazily, so a row could open on the fragment's slide and announce it before `carousel-captions` listened, leaving the first slide's caption up. The captions controller now reads the row's open slide (`data-current`, a looping row's copies not counted: `studio/carousel` `markedSlide`) when it connects, then follows `studio:carousel:change`. Nothing to change in a host.
+- **A caption wrapper follows only its own row.** A change event from a second carousel inside the wrapper moved its captions. The captions now follow the row marked `data-carousel-captions-target="carousel"`, else the first carousel inside the wrapper; the README says one row per caption wrapper.
+- **A narrow cascade no longer cuts the open card's shadow.** The narrow region's edge mask paints only inside the track's box, so a `shadow-xl` under the front card ended in a hard line at phone width. The track now keeps `--carousel-cascade-shadow-room` (2.5rem) under the cards and gives it back with a negative margin, so nothing moves, and the controls over that room keep their presses. A deeper shadow raises the variable.
+- **The image-only pattern respects reduced motion.** The README pattern and the style guide specimen carry `motion-reduce:transition-none` on each caption and on the card ring; copy it into a host's markup.
+
 ## 0.140.0 — 2026-11-09
 
 ### Fixed

data/README.md

@@ -458,13 +458,13 @@ grid cell. The engine's `carousel-captions` controller (lazy) marks the open one
         locals: { label: "Portfolio", items: @apps, style: :cascade, loop: true, dots: false,
                   slide_label: ->(app) { app.name } } do |app| %>
     <%= link_to app.url, aria: { label: app.name },
-          class: "block aspect-[4/3] overflow-hidden rounded-2xl transition-shadow duration-300 in-data-current:ring-2 in-data-current:ring-primary" do %>
+          class: "block aspect-[4/3] overflow-hidden rounded-2xl transition-shadow duration-300 motion-reduce:transition-none in-data-current:ring-2 in-data-current:ring-primary" do %>
       <%= image_tag app.image, alt: "", class: "h-full w-full object-cover" %>
     <% end %>
   <% end %>
   <div class="grid pt-4 text-center">
     <% @apps.each_with_index do |app, index| %>
-      <div class="col-start-1 row-start-1 opacity-0 invisible transition-opacity data-current:opacity-100 data-current:visible"
+      <div class="col-start-1 row-start-1 opacity-0 invisible transition-opacity motion-reduce:transition-none data-current:opacity-100 data-current:visible"
            data-carousel-captions-target="caption"<%= " data-current".html_safe if index.zero? %><%= ' aria-hidden="true"'.html_safe unless index.zero? %>>
         <h2 class="type-h4 text-heading"><%= app.name %></h2>
         <p class="text-sm text-secondary"><%= app.blurb %></p>
@@ -475,11 +475,28 @@ grid cell. The engine's `carousel-captions` controller (lazy) marks the open one
 ```
 
 The server marks the caption of the slide the row opens on (`start:`; index 0 for a
-looping row). The ring keys on `data-current`, which the cascade and the spotlight set on
-the open slide (`in-data-current:` matches the card inside it). The row's status line
+looping row). Both controllers load lazily, so a row that opens elsewhere (a `#fragment`)
+may announce it before the captions connect: `carousel-captions` reads the row's open slide
+(`data-current`) when it connects, then follows the change event. The ring keys on
+`data-current`, which the cascade and the spotlight set on the open slide
+(`in-data-current:` matches the card inside it). The row's status line
 already says which slide is open, so the caption stack is not a live region. A host that
 needs more than a caption listens for `studio:carousel:change` itself.
 
+**One row per caption wrapper.** The captions follow the wrapper's own row: the region
+marked `data-carousel-captions-target="carousel"` (pass `data: { carousel_captions_target:
+"carousel" }` to the partial), else the first carousel inside the wrapper. A change event
+from any other row inside it moves nothing. Keep `motion-reduce:transition-none` on the
+caption fade and the card's ring: under reduced motion both swap at once, as the stack
+does.
+
+**A shadow under a narrow stack.** A narrow region's cascade fades its side cards at the
+track's edge with a mask, and a mask paints only inside the track's box. The track keeps
+`--carousel-cascade-shadow-room` (2.5rem, Tailwind's `shadow-xl`) of room under the cards
+for the open card's shadow and gives it back with a negative margin, so nothing moves. A
+deeper shadow (`shadow-2xl`) raises it: `[--carousel-cascade-shadow-room:4rem]` on the
+partial's `class_name:`.
+
 ### The "at" time stamp — `at_time_tag`
 
 Stamps WHEN something happened, on the reader's own clock: `at 3:53p`, gaining a

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

@@ -1175,16 +1175,37 @@ body.modal-open .studio-app-banner {
   }
 
   /* A narrow region shows one each side, on wider cards. Those side cards run past
-     the track's edge, so the edge fades them out instead of cutting them hard. */
+     the track's edge, so the edge fades them out instead of cutting them hard.
+
+     The mask fades only the sides, but it paints only inside the track's own box: a
+     card's outer shadow below the box would end in a hard line. So the box takes room
+     under the cards for the shadow (--carousel-cascade-shadow-room, 2.5rem: Tailwind's
+     shadow-xl; raise it for a deeper shadow) and gives it back with a matching negative
+     margin, so nothing below moves. The controls, which now sit over that room, are
+     lifted above the track (its perspective makes it a stacking context) so they keep
+     every press. */
   @container (width < 36rem) {
     & > .carousel-track {
       --carousel-cascade-reach: 1;
       --cascade-w: 64cqi;
       --cascade-shift: 0.44;
       --cascade-depth: 3.5rem;
+      padding-block-end: calc(0.75rem + var(--carousel-cascade-shadow-room, 2.5rem));
+      margin-block-end: calc(-1 * var(--carousel-cascade-shadow-room, 2.5rem));
       -webkit-mask-image: linear-gradient(to right, transparent, #000 var(--carousel-cascade-fade, 10%), #000 calc(100% - var(--carousel-cascade-fade, 10%)), transparent);
               mask-image: linear-gradient(to right, transparent, #000 var(--carousel-cascade-fade, 10%), #000 calc(100% - var(--carousel-cascade-fade, 10%)), transparent);
     }
+
+    & > .carousel-controls {
+      position: relative;
+      z-index: 1;
+    }
+
+    /* A row with no controls (one slide, or a failed controller) keeps the room: with
+       nothing over it, the track's box would cover what follows and take its presses. */
+    &:is([data-carousel-static], [data-studio-controller-failed]) > .carousel-track {
+      margin-block-end: 0;
+    }
   }
 
   &[data-carousel-dragging] > .carousel-track {

data/app/javascript/studio/carousel.js

@@ -344,6 +344,16 @@ export function changeDetail(previous, index, slides) {
   return { index, previous: Number.isInteger(previous) ? previous : null, slide: list[index], total: list.length }
 }
 
+// The open slide's index among a region's real slides: the first that carries
+// data-current, a looping row's copies (data-carousel-clone) not counted. -1 when none
+// is marked (a standard row marks none). A host that connects after the row opened
+// (a #fragment, a lazy controller) reads where it stands with it, then follows
+// CHANGE_EVENT.
+export function markedSlide(slides) {
+  const real = Array.from(slides || []).filter((slide) => !slide.hasAttribute("data-carousel-clone"))
+  return real.findIndex((slide) => slide.hasAttribute("data-current"))
+}
+
 // -- the cascade's press --------------------------------------------------------
 
 // The slide a click on a cascade belongs to. A mouse press on a side slide records

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

@@ -2,7 +2,8 @@
 // image-only pattern, README "The carousel"). A caption inside each slide would ride
 // a cascade's 3D move, so the captions live outside the row: one per item, in item
 // order, laid in one grid cell, and this marks the open slide's caption data-current
-// and hides the rest from assistive tech (aria-hidden). The page styles the cross-fade.
+// and hides the rest from assistive tech (aria-hidden). The page styles the cross-fade
+// (with motion-reduce:transition-none, so reduced motion swaps it at once).
 //
 //   <div data-studio-controller="carousel-captions">
 //     <%= render layout: "studio/carousel", ... %>
@@ -10,26 +11,44 @@
 //     <div data-carousel-captions-target="caption" aria-hidden="true">second</div>
 //   </div>
 //
+// ONE ROW PER WRAPPER. It follows its own row: the region marked
+// data-carousel-captions-target="carousel" (pass it as the partial's data:), else the
+// first carousel region inside it. A change event from any other row inside the
+// wrapper moves nothing.
+//
 // It listens for the carousel's change event (studio/carousel CHANGE_EVENT), which
-// bubbles from the region inside it, so it needs no observer and no timer. The server
-// marks the caption of the slide the row opens on. A lazy controller (studio/stimulus):
-// a page with no caption stage fetches nothing; one whose controller failed keeps the
-// server's caption.
+// bubbles from the region inside it, so it needs no observer and no timer. Both
+// controllers load lazily (studio/stimulus), so the row may open somewhere else (a
+// #fragment) and announce it before this connects: connect() reads the row's open
+// slide (studio/carousel markedSlide) first, then follows the event. The server marks
+// the caption of the slide the row opens on, so a page with no caption stage fetches
+// nothing, and one whose controller failed keeps the server's caption.
 import { Controller } from "@hotwired/stimulus"
-import { CHANGE_EVENT } from "studio/carousel"
+import { CHANGE_EVENT, markedSlide } from "studio/carousel"
+
+const REGION = ".carousel[data-studio-controller~='carousel']"
 
 export default class extends Controller {
-  static targets = ["caption"]
+  static targets = ["caption", "carousel"]
 
   connect() {
-    this.follow = (event) => this.show(event.detail?.index)
+    this.follow = (event) => {
+      if (event.target === this.region()) this.show(event.detail?.index)
+    }
     this.element.addEventListener(CHANGE_EVENT, this.follow)
+    const region = this.region()
+    if (region) this.show(markedSlide(region.querySelectorAll(":scope > .carousel-track > .carousel-slide")))
   }
 
   disconnect() {
     this.element.removeEventListener(CHANGE_EVENT, this.follow)
   }
 
+  // The row these captions follow: the carousel target, else the first row inside.
+  region() {
+    return this.hasCarouselTarget ? this.carouselTarget : this.element.querySelector(REGION)
+  }
+
   show(index) {
     if (!Number.isInteger(index) || index < 0 || index >= this.captionTargets.length) return
     this.captionTargets.forEach((caption, at) => {

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

@@ -291,12 +291,12 @@
               locals: { label: "Image-only specimen", items: (1..5).to_a, style: :cascade, loop: true, dots: false,
                         id: "style-carousel-image-only-specimen", slide_label: ->(n) { "Picture #{n}" } } do |n| %>
           <div role="img" aria-label="Picture <%= n %>"
-               class="aspect-[4/3] overflow-hidden rounded-2xl transition-shadow duration-300 in-data-current:ring-2 in-data-current:ring-primary"
+               class="aspect-[4/3] overflow-hidden rounded-2xl transition-shadow duration-300 motion-reduce:transition-none in-data-current:ring-2 in-data-current:ring-primary"
                style="background-image: linear-gradient(<%= 120 + n * 30 %>deg, rgb(var(--color-primary-rgb) / <%= 0.25 + n * 0.12 %>), rgb(var(--color-primary-rgb) / 0.08))"></div>
         <% end %>
         <div class="grid pt-3 text-center">
           <% (1..5).each do |n| %>
-            <div class="col-start-1 row-start-1 opacity-0 invisible transition-opacity duration-200 data-current:opacity-100 data-current:visible"
+            <div class="col-start-1 row-start-1 opacity-0 invisible transition-opacity duration-200 motion-reduce:transition-none data-current:opacity-100 data-current:visible"
                  data-carousel-captions-target="caption"<%= " data-current".html_safe if n == 1 %><%= ' aria-hidden="true"'.html_safe unless n == 1 %>>
               <p class="text-sm font-semibold text-heading">Picture <%= n %></p>
               <p class="text-xs text-secondary">One caption under the stack.</p>

data/lib/studio/node_tooling/README.md

@@ -11,14 +11,16 @@ host gets it with the engine it already bundles: no npm registry, no token.
 - `e2e_helpers.js`: `watchPageErrors` and `blockOffsiteRequests`; for a page
   transition spec, the reveal waits (`watchReveal`, `revealed`, `settled`,
   `arrivalSettled`, `frames`) and the log-on-red hook (`sessionLog`, `logOnRed`).
-  The waits read events the browser fires, never a clock.
+  The waits read events the browser fires, never a clock. Each wait takes a
+  selector that only the new page has, and refuses without one: right after a
+  click, the old page has revealed too.
+- `node_test/register.mjs` and `node_test/importmap_hooks.mjs`: let `node --test`
+  import a module by the bare name the importmap pins it under.
 
 A local run reuses a server already on the e2e port only when that server's
 working directory is inside this tree (`mayReuseServer` in `playwright_base.js`,
 read with `lsof`). Any other server there is refused, with a warning that names
 its root: give the run its own port with `E2E_PORT=<free port>`.
-- `node_test/register.mjs` and `node_test/importmap_hooks.mjs`: let `node --test`
-  import a module by the bare name the importmap pins it under.
 
 Every file here requires only `node:` builtins and its own siblings, because it
 is loaded from the gem's directory, which has no `node_modules`.

data/lib/studio/node_tooling/e2e_helpers.js

@@ -100,8 +100,13 @@ function watchReveal(target) {
 // as visible, before its first render. A render-blocking sheet, or the reveal script's own
 // hold to the end of parse, keeps pagereveal back, and until then no mark is set and no
 // pseudo runs (engine CI run 42503970890 read an empty log at 312 ms).
+//
+// THE SELECTOR IS REQUIRED, and it must name something only the new page has. Right after a
+// click the old page is still the document, and its own reveal has already happened, so a wait
+// with nothing to find first would read the old page and return at once.
 async function revealed(page, selector) {
-  if (selector) await page.locator(selector).first().waitFor({ state: "visible" });
+  if (!selector) throw new TypeError("revealed() needs a selector only the new page has: the old page has revealed too");
+  await page.locator(selector).first().waitFor({ state: "visible" });
   await page.waitForFunction(() => window.__studioReveal && window.__studioReveal.revealed === true);
 }
 

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.140.0"
+  VERSION = "0.141.0"
 end

metadata

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