studio-engine 0.138.0 → 0.139.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cb1274e13e7eca7030835c5ff43a48a897f01e723273ec60e4f5eb334e190c85
-  data.tar.gz: a8e5bb472135b9f72a8662026dac450d2b0830dd30d6913a504c0ced09e57dd2
+  metadata.gz: a9937bbeb00f70902af7404d9ded16f10216e7123dba4d929eef0d04fe8c1f80
+  data.tar.gz: ff26fdac225b730cc611af898fe0fc786ee968545a5ee674f89131cfe183f035
 SHA512:
-  metadata.gz: 4184a55e11cf2e7c3146c73520878a5e1edbc6802bcb19eb9a3c61b09d6d73912a867c98bbd56772d664dc4bf2bace1a152a864c36c1447102bf83d7d0d444df
-  data.tar.gz: d06d58547262873513c597eb54f8313e76ac8bbbc3dcc7d6693a5a12ffbc23b4c08eeb782a94edf384d4af09bc3f83eda27845f5fc5a112af339c8ada5269bc0
+  metadata.gz: d3721562277466c4af36db5835ad05ad5fba414d4a091c9a447787f95d5d8bbe8ae053b5ff0a0563422a732169130aedd77e2bf5f721e6026b099e99172b7e6f
+  data.tar.gz: 2b2405866b62361954dc69c30d66b5dbcd56536ef40b9e26d5b64094d3ed7a07bfb36cda26483ae872cc370f95a1f7f69a7a79dd4c24c4744c1d2ce1a59a8504

data/CHANGELOG.md

@@ -4,6 +4,21 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.139.0 — 2026-11-08
+
+### Added
+
+- **`studio/_carousel` dispatches `studio:carousel:change`.** Every style (standard, spotlight, cascade) dispatches it from the region, bubbling, once each time the open slide changes, after `data-current` has moved. `event.detail` is `{ index, previous, slide, total }`. A host that follows the open slide (a caption under the row, a counter) listens for it instead of a `MutationObserver` on `data-current`. The first paint's slide fires nothing; a looping row fires once, for the real slide, when it lands home off the seam copy.
+- **`studio/_carousel` takes `dots:`.** `dots: false` draws no dot group, so nothing for Tab or a screen reader to meet; the arrows, keys, swipe and status line stay. The default, `dots: true`, renders byte for byte what leaving it out does (render digests for standard, spotlight and cascade). A host that hid the dots with CSS passes `dots: false` instead.
+- **The image-only cascade pattern is documented and on `/admin/style`.** Each card is only its picture, the open card wears a ring (`in-data-current:`), and one caption under the stack follows the open card. The new lazy `carousel-captions` controller does the following: wrap the row and its captions in `data-studio-controller="carousel-captions"` and mark each caption `data-carousel-captions-target="caption"`; no page script. The README gives the markup to copy.
+
+### Fixed
+
+- **A cascade press released off the track no longer hijacks Enter.** A mouse press on a side card that let go outside the track left its card recorded, so Enter on the front card's link later moved the stack to that card instead of following the link. A click with no press (Enter or Space) now reads only the card it lands in, and the next press replaces a stale one.
+- **A cascade card that crosses a looping stack's seam fades in on every move.** Next then Previous on a five-card loop took the same card round the seam twice, and the second jump did not fade in. The fade now replays each time and leaves no finished animation behind.
+- **A narrow cascade fades its side cards at the track's edge** instead of cutting them hard; a wide stack and a failed controller's scrolling row keep no mask.
+- **The cascade's Tab wording is exact.** The partial, the controller and the README now say that Tab skips the cards past the window, and that a cascade which does not loop and opens mid-row reaches the cards before the window by Shift+Tab, Home, the arrow keys, Previous and the dots.
+
 ## 0.138.0 — 2026-11-08
 
 ### Added

data/README.md

@@ -350,6 +350,10 @@ as a layout; the block draws each slide. `per_view:` is the wide row's count
 
 `caption:` (a callable on the item) writes a small line under each slide.
 
+`dots: false` draws no dots: the row has no dot group in the tab order or the
+accessibility tree, and the arrows, keys, swipe and status line stay. The default,
+`dots: true`, renders exactly what leaving it out does.
+
 `style: :spotlight` snaps each slide to the centre: the centred slide is full size and
 colour, with its caption under it (the spotlight shows the centred slide's only), and its
 neighbours are smaller, faded and grey. The arrows ("Previous slide", "Next slide") and
@@ -412,7 +416,15 @@ status line says "Slide N of M". `start:`, `caption:` (under the open slide only
 `autoplay:` and `loop:` behave as on the spotlight; a looping cascade needs no clones,
 since the steps wrap round the set. Under reduced motion the stack lays flat as a spotlight
 row, the neighbours only dimmed, and a move swaps at once. A controller that fails leaves
-a plain scrolling row.
+a plain scrolling row. A region under 36rem wide fades its side cards at the track's edge
+instead of cutting them, and a card that crosses a looping stack round the seam fades in at
+its new place on every move.
+
+Tab skips the cards past the window (they are hidden). Tab from the track lands on the
+first card in view and brings it to the front, and each Tab after moves one card on. A
+cascade that does not loop and opens mid-row (the default) has cards before the window that
+forward Tab never reaches: Shift+Tab from the first card in view, Home, the arrow keys,
+Previous and the dots reach them.
 
 ```erb
 <%= render layout: "studio/carousel",
@@ -421,6 +433,53 @@ a plain scrolling row.
 <% end %>
 ```
 
+**The change event.** Every style dispatches `studio:carousel:change` from the region
+(`section.carousel`), bubbling, once each time the open slide changes, after the
+controller has moved `data-current`. `event.detail` is `{ index, previous, slide, total }`:
+the open slide's index among the real slides (from 0), the one open before, its element
+(never a looping row's copy) and the count. Follow the open slide with it; do not observe
+`data-current`. The first paint's slide fires nothing, and a row that opens elsewhere
+when its controller connects (a `#fragment`, a restored scroll) fires once. A cascade
+fires once per move. A scrolling row (standard or spotlight) fires for each slide its
+glide passes, as its `data-current` moves; a looping one fires for the real slide once it
+has jumped home off the seam copy. A standard row's open slide is the one at its first
+stop, and it marks none `data-current`.
+
+**The image-only pattern** (the hub Portfolio, `/lab/carousel_cascade`, `/admin/style`):
+each card is only its picture, filling the card; the open card wears a ring; and one caption
+sits under the stack and follows the open card. A caption inside each slide would ride the
+slide's 3D move, so the captions live outside the row, one per item in item order, all in one
+grid cell. The engine's `carousel-captions` controller (lazy) marks the open one
+`data-current` and the rest `aria-hidden` on each change event; the page needs no script:
+
+```erb
+<div data-studio-controller="carousel-captions">
+  <%= render layout: "studio/carousel",
+        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 %>
+      <%= 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"
+           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>
+      </div>
+    <% end %>
+  </div>
+</div>
+```
+
+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
+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.
+
 ### 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

@@ -1174,13 +1174,16 @@ body.modal-open .studio-app-banner {
     --cascade-shift: 0.62;
   }
 
-  /* A narrow region shows one each side, on wider cards. */
+  /* 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. */
   @container (width < 36rem) {
     & > .carousel-track {
       --carousel-cascade-reach: 1;
       --cascade-w: 64cqi;
       --cascade-shift: 0.44;
       --cascade-depth: 3.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);
     }
   }
 
@@ -1264,7 +1267,9 @@ body.modal-open .studio-app-banner {
   /* Round the seam: no glide across the stack, a fade in at the new place. */
   & > .carousel-track > .carousel-slide[data-cascade-jump] {
     transition: none;
-    animation: carousel-cascade-in 320ms ease both;
+    /* backwards, not both: a fade that has ended leaves nothing running, so the
+       slide holds no finished animation until its next move. */
+    animation: carousel-cascade-in 320ms ease backwards;
   }
 
   & > .carousel-track > .carousel-slide[data-cascade-jump]:is([data-cascade-step="before"], [data-cascade-step="after"]) {
@@ -1322,6 +1327,8 @@ body.modal-open .studio-app-banner {
     overflow-x: auto;
     scroll-snap-type: x mandatory;
     perspective: none;
+    -webkit-mask-image: none;
+            mask-image: none;
   }
 
   &[data-studio-controller-failed] > .carousel-track > .carousel-slide {

data/app/javascript/studio/carousel.js

@@ -312,3 +312,46 @@ export function cascadeTarget(active, by, total, loop = false) {
   if (loop) return wrapIndex(to, total)
   return Math.min(total - 1, Math.max(0, to))
 }
+
+// -- the change event ----------------------------------------------------------
+//
+// THE CHANGE EVENT: the region dispatches CHANGE_EVENT once each time its open slide
+// changes, on every style, after the controller has moved data-current (a spotlight
+// and a cascade mark the open slide; a standard row marks none). It bubbles, so a
+// host listens on the region or the document and needs no MutationObserver:
+//
+//   region.addEventListener("studio:carousel:change", ({ detail }) => {
+//     detail.index     // the open slide, 0-based among the real slides
+//     detail.previous  // the one open before
+//     detail.slide     // that slide's element (never a looping row's copy)
+//     detail.total     // the real slides
+//   })
+//
+// A standard row's "open slide" is the one at its first stop. The first paint's
+// slide (start:) fires nothing; a row that opens elsewhere when its controller
+// connects (a #fragment, a restored scroll) fires once. A looping row's glide round
+// the seam fires once, for the real slide, when the row has jumped home onto it, not
+// for the copy it rests on first. A scrolling row's glide across several slides fires
+// for each slide it passes, as data-current moves; a cascade does not glide, so a dot
+// or End fires once.
+export const CHANGE_EVENT = "studio:carousel:change"
+
+// The event's detail when the open slide moved from `previous` to `index`, else null.
+export function changeDetail(previous, index, slides) {
+  if (!Number.isInteger(index) || index < 0 || index === previous) return null
+  const list = slides || []
+  if (index >= list.length) return null
+  return { index, previous: Number.isInteger(previous) ? previous : null, slide: list[index], total: list.length }
+}
+
+// -- the cascade's press --------------------------------------------------------
+
+// The slide a click on a cascade belongs to. A mouse press on a side slide records
+// it (pressed), since a link whose focus already moved the stack still counts as a
+// side slide's. A click with no press (detail 0: Enter or Space on a focused link, or
+// a script's click()) never reads a record a press left behind: it is the slide it
+// lands in, so Enter on the open card follows its link.
+export function clickedSlide(pressed, detail, hit) {
+  if (detail === 0) return hit
+  return pressed ?? hit
+}

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

@@ -0,0 +1,42 @@
+// carousel-captions: one caption under a carousel that follows its open slide (the
+// 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.
+//
+//   <div data-studio-controller="carousel-captions">
+//     <%= render layout: "studio/carousel", ... %>
+//     <div data-carousel-captions-target="caption" data-current>first</div>
+//     <div data-carousel-captions-target="caption" aria-hidden="true">second</div>
+//   </div>
+//
+// 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.
+import { Controller } from "@hotwired/stimulus"
+import { CHANGE_EVENT } from "studio/carousel"
+
+export default class extends Controller {
+  static targets = ["caption"]
+
+  connect() {
+    this.follow = (event) => this.show(event.detail?.index)
+    this.element.addEventListener(CHANGE_EVENT, this.follow)
+  }
+
+  disconnect() {
+    this.element.removeEventListener(CHANGE_EVENT, this.follow)
+  }
+
+  show(index) {
+    if (!Number.isInteger(index) || index < 0 || index >= this.captionTargets.length) return
+    this.captionTargets.forEach((caption, at) => {
+      const open = at === index
+      caption.toggleAttribute("data-current", open)
+      if (open) caption.removeAttribute("aria-hidden")
+      else caption.setAttribute("aria-hidden", "true")
+    })
+  }
+}

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

@@ -57,13 +57,24 @@
 // and autoplay move it as they move a spotlight, through the same move() and
 // scrollToStop(). A swipe or a drag (pointer events, past DRAG_THRESHOLD) moves it
 // too; a click on a side slide brings that slide to the front and follows no link,
-// and keyboard focus landing in a side slide does the same, so Tab walks the set. A
-// looping cascade takes no clones: the steps wrap round the set, and a slide that
-// crosses the stack round the seam (cascadeJumps) takes no glide. A focused slide
-// that leaves the window hands focus to the track, so the keys keep working.
+// and keyboard focus landing in a side slide in view does the same. TAB: a slide past
+// the window is hidden, so Tab skips it. Tab from the track lands on the first slide
+// in view and brings it to the front, and each Tab after moves one slide on. A cascade
+// that does not loop and opens mid-row (the default :middle) has slides before the
+// window that forward Tab never reaches: Shift+Tab from the first slide in view (its
+// focus has moved the stack, so the slide before it is in view), Home, the arrow keys,
+// the Previous arrow and the dots reach them. A looping cascade takes no clones: the
+// steps wrap round the set, and a slide that crosses the stack round the seam
+// (cascadeJumps) takes no glide but fades in, every time. A focused slide that leaves
+// the window hands focus to the track, so the keys keep working.
+//
+// THE CHANGE EVENT (studio/carousel CHANGE_EVENT, "studio:carousel:change"): every
+// style dispatches it from the region, bubbling, once per change of the open slide,
+// after data-current has moved (announceChange). detail: { index, previous, slide,
+// total }. A host follows the open slide with it instead of observing data-current.
 import { Controller } from "@hotwired/stimulus"
 import {
-  CLONE_STRIP, TOLERANCE, autoplayRunning, autoplaySeconds, autoplayStop, cascadeJumps, cascadeReach, cascadeSlot,
+  CHANGE_EVENT, CLONE_STRIP, TOLERANCE, autoplayRunning, changeDetail, clickedSlide, autoplaySeconds, autoplayStop, cascadeJumps, cascadeReach, cascadeSlot,
   cascadeStep, cascadeSteps, cascadeTarget, centerStops, cloneCount, cloneLayout, dragSteps,
   currentStop, hiddenEnds, idleDelay, initialReasons, keyAction, loopPositionText, loopStop, nearestVirtual, ownsKey,
   perPage, positionText, seamJump, startStop, stops, targetStop, toggleLabel, withReason, wrapIndex
@@ -95,6 +106,8 @@ export default class extends Controller {
       this.observer.observe(this.trackTarget)
     }
     this.element.setAttribute("data-carousel-ready", "")
+    // The first paint's slide: the change event fires only when the open slide leaves it.
+    this.opened = Math.max(0, Number(this.element.dataset.carouselStart) || 0)
     this.openAtStart()
     this.addClones()
     this.sync()
@@ -107,6 +120,7 @@ export default class extends Controller {
     const slides = this.slideTargets
     const marked = slides.findIndex((slide) => slide.hasAttribute("data-current"))
     this.active = marked >= 0 ? marked : 0
+    this.opened = this.active
     // A #fragment inside a slide opens on that slide.
     const hash = window.location?.hash
     if (hash && hash.length > 1) {
@@ -119,7 +133,7 @@ export default class extends Controller {
       ["pointerdown", (event) => this.dragStart(event)],
       ["pointermove", (event) => this.dragMove(event)],
       ["pointerup", (event) => this.dragEnd(event)],
-      ["pointercancel", () => this.dragCancel()],
+      ["pointercancel", () => { this.pressed = null; this.dragCancel() }],
       ["click", (event) => this.clickSide(event), true],
       ["focusin", (event) => this.focusSide(event)],
       ["dragstart", (event) => event.preventDefault()]
@@ -159,6 +173,14 @@ export default class extends Controller {
     if (this.hasNextTarget) this.nextTarget.setAttribute("aria-disabled", String(!wraps && this.active >= total - 1))
     const steps = cascadeSteps(total, this.active, this.loop)
     const jumps = this.laid ? cascadeJumps(this.laid, steps, this.active) : steps.map(() => false)
+    // A jumping slide's fade replays only if the style saw it without the mark first.
+    // It may still wear the mark from its last jump (Next then Previous round the
+    // seam), or have lost it earlier in this same task (move() syncs before it moves),
+    // which the style never saw: drop the mark, settle the style, then set it.
+    if (jumps.some(Boolean)) {
+      this.slideTargets.forEach((slide, index) => { if (jumps[index]) slide.removeAttribute("data-cascade-jump") })
+      void this.trackTarget.offsetWidth
+    }
     this.slideTargets.forEach((slide, index) => {
       slide.setAttribute("data-cascade-step", cascadeSlot(steps[index]))
       slide.toggleAttribute("data-cascade-jump", jumps[index])
@@ -170,6 +192,16 @@ export default class extends Controller {
       if (index === this.active) dot.setAttribute("aria-current", "true")
       else dot.removeAttribute("aria-current")
     })
+    this.announceChange(this.active)
+  }
+
+  // THE CHANGE EVENT (studio/carousel CHANGE_EVENT): once per change of the open
+  // slide, after data-current has moved, bubbling from the region.
+  announceChange(index) {
+    const detail = changeDetail(this.opened, index, this.slideTargets)
+    if (!detail) return
+    this.opened = index
+    this.element.dispatchEvent(new CustomEvent(CHANGE_EVENT, { bubbles: true, detail }))
   }
 
   // Brings slide `index` to the front. A focused slide that leaves the window hands
@@ -192,7 +224,9 @@ export default class extends Controller {
 
   // A press on a side slide: the click that follows brings it to the front and opens
   // nothing. The slide is read at the press, so a link whose focus already moved the
-  // stack still counts as a side slide's.
+  // stack still counts as a side slide's. A click with no press (event.detail 0:
+  // Enter or Space on a focused link) is read where it lands (clickedSlide), so a
+  // press released off the track leaves nothing behind for Enter on the open card.
   clickSide(event) {
     if (this.dragged) {
       this.dragged = false
@@ -200,7 +234,7 @@ export default class extends Controller {
       event.stopPropagation()
       return
     }
-    const index = this.pressed ?? this.slideAt(event.target)
+    const index = clickedSlide(this.pressed, event.detail, this.slideAt(event.target))
     this.pressed = null
     if (index < 0 || index === this.active) return
     event.preventDefault()
@@ -209,7 +243,8 @@ export default class extends Controller {
     this.scrollToStop(index)
   }
 
-  // Keyboard focus in a side slide brings it to the front, so Tab walks the set. A
+  // Keyboard focus in a side slide brings it to the front, so Tab moves one slide on
+  // from the first slide in view (see TAB above for the slides before the window). A
   // mouse press focuses without :focus-visible and leaves the move to its click.
   focusSide(event) {
     const index = this.slideAt(event.target)
@@ -221,8 +256,10 @@ export default class extends Controller {
     this.scrollToStop(index, { announce: false })
   }
 
+  // A press released off the track sends no pointerup here, so its record is stale:
+  // the next press of the same pointer replaces it. A second finger is ignored.
   dragStart(event) {
-    if (event.button > 0 || this.drag) return
+    if (event.button > 0 || (this.drag && this.drag.id !== event.pointerId)) return
     const index = this.slideAt(event.target)
     this.pressed = index >= 0 && index !== this.active ? index : null
     this.dragged = false
@@ -564,6 +601,9 @@ export default class extends Controller {
       if (index === this.current) dot.setAttribute("aria-current", "true")
       else dot.removeAttribute("aria-current")
     })
+    // A looping row resting on a copy is on its way home (settle): it announces the
+    // real slide once it lands there, so the slide the event names carries the mark.
+    if (!this.cloned || this.virtual === this.current) this.announceChange(this.current)
   }
 
   prev() { this.move("prev") }

data/app/javascript/studio/stimulus.js

@@ -71,7 +71,8 @@ export const schema = {
 // So is the page header: its tabs are links, and a row whose controller failed
 // keeps its bar at all times (data-studio-controller-failed="page-header").
 // So is the carousel: its track is a native scroll row, and one whose controller
-// failed keeps a scrollbar and hides the arrows and dots it cannot drive.
+// failed keeps a scrollbar and hides the arrows and dots it cannot drive. So are
+// the carousel's captions: a stage whose controller failed keeps the server's caption.
 // So is infinite scroll: a list whose controller failed keeps its "Load more"
 // link, which loads the next page by itself. So is pull to refresh: nothing
 // depends on it, and the browser's own reload still works.
@@ -93,6 +94,7 @@ export const LAZY = {
   "copy-text": () => import("studio/controllers/copy_text_controller"),
   "page-header": () => import("studio/controllers/page_header_controller"),
   "carousel": () => import("studio/controllers/carousel_controller"),
+  "carousel-captions": () => import("studio/controllers/carousel_captions_controller"),
   "infinite-scroll": () => import("studio/controllers/infinite_scroll_controller"),
   "pull-to-refresh": () => import("studio/controllers/pull_to_refresh_controller")
 }

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

@@ -1,4 +1,4 @@
-<%# locals: (label:, items:, per_view: 3, id: nil, slide_label: nil, data: {}, class_name: nil, style: :standard, caption: nil, start: nil, autoplay: nil, loop: false, visible: nil) %>
+<%# locals: (label:, items:, per_view: 3, id: nil, slide_label: nil, data: {}, class_name: nil, style: :standard, caption: nil, start: nil, autoplay: nil, loop: false, visible: nil, dots: true) %>
 <%# THE CAROUSEL: one sideways row of slides, the apps' standard for a set too
     long to grid. Render it as a layout, so each slide is your own block:
 
@@ -51,6 +51,9 @@
                    so a screen reader and Tab meet each slide once, a #fragment
                    finds the real slide, and the dots and "slide N of M" count the
                    real slides. Every slide of a looping row is a stop.
+      dots         true (the default) draws a dot per slide under the row; false
+                   draws none, so the row has no dot group in the tab order or the
+                   accessibility tree. The arrows, keys, swipe and status line stay.
       autoplay     seconds between moves (a number above 0); nil, the default, is
                    off. The row moves one slide each interval and holds still while
                    the pointer is over the slides, while keyboard focus is in it,
@@ -74,10 +77,21 @@
     lays the stack out (perspective, translateZ, a slight turn toward the centre)
     and transitions it. An arrow, a dot, a key, a swipe or drag, autoplay, a click
     on a side slide and keyboard focus in one bring that slide to the front; a
-    click on a side slide opens nothing. A looping cascade needs no clones: the
-    steps wrap round the set, so the window is never wider than the set. Under
-    reduced motion it lays flat, as a spotlight does, and swaps with no glide. If
-    its controller fails it falls back to a plain scrolling row.
+    click on a side slide opens nothing. Tab skips the slides past the window (they
+    are hidden): it lands on the first slide in view and moves one on each press.
+    A cascade that does not loop and opens mid-row has slides before the window
+    that forward Tab never reaches; Shift+Tab from the first slide in view, Home,
+    the arrow keys, Previous and the dots do. A looping cascade needs no clones: the
+    steps wrap round the set, so the window is never wider than the set. A narrow
+    region fades its side slides at the track's edge. Under reduced motion it lays
+    flat, as a spotlight does, and swaps with no glide. If its controller fails it
+    falls back to a plain scrolling row.
+
+    THE CHANGE EVENT. Every style dispatches "studio:carousel:change" from the
+    region, bubbling, once each time the open slide changes, after data-current
+    has moved: detail { index, previous, slide, total }. A host that follows the
+    open slide listens for it. One caption under the row needs no script: the
+    carousel-captions controller follows it (README, the image-only pattern).
 
     THE TRACK IS A NATIVE SCROLL-SNAP ROW (engine.css, carousel). A swipe, a
     trackpad, a wheel and a focused link move it with no script. The carousel
@@ -164,6 +178,7 @@
     <% end %>
   </div>
   <div class="carousel-controls">
+    <% if dots %>
     <div class="carousel-dots" role="group" aria-label="Choose a slide">
       <% total.times do |index| %>
         <button type="button" class="carousel-dot" aria-label="Go to slide <%= index + 1 %>"
@@ -172,6 +187,7 @@
                 data-studio-action="click->carousel#goTo"></button>
       <% end %>
     </div>
+    <% end %>
     <div class="carousel-arrows">
       <% if autoplay %>
         <%# The pause button (WCAG 2.2.2). The controller renames it "Play slideshow"

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

@@ -281,6 +281,29 @@
           </div>
         <% end %>
       </div>
+
+      <%# The image-only pattern (README, The carousel): each card is only its picture,
+          the open card wears a ring, the row draws no dots, and one caption under the
+          stack follows the open card (the carousel-captions controller, on
+          studio:carousel:change). %>
+      <div class="w-full min-w-0" data-studio-controller="carousel-captions" data-carousel-image-only-specimen>
+        <%= render layout: "studio/carousel",
+              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"
+               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"
+                 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>
+            </div>
+          <% end %>
+        </div>
+      </div>
     <% end %>
   </section>
 

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.138.0"
+  VERSION = "0.139.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.138.0
+  version: 0.139.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -516,6 +516,7 @@ files:
 - app/javascript/studio/controllers/agent_chat_voice_controller.js
 - app/javascript/studio/controllers/board_controller.js
 - app/javascript/studio/controllers/booking_controller.js
+- app/javascript/studio/controllers/carousel_captions_controller.js
 - app/javascript/studio/controllers/carousel_controller.js
 - app/javascript/studio/controllers/copy_text_controller.js
 - app/javascript/studio/controllers/email_banner_scale_controller.js