studio-engine 0.131.0 → 0.132.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f090aa3b8a00d7e7a62e7395fdc02fff3c0fdf4063350a492e1e835932dc5b26
-  data.tar.gz: 6d2ae853a4bb64281147c1a67721d93e1a8c38b5d3fb43e6897df85c7be964c7
+  metadata.gz: dd2c739840540a736a0ad347abe13b22047ff20070c8e336df86172c6518d848
+  data.tar.gz: fced70c6c90490c2d74732bdae8270b25f0e7717a87623daf734984c6e4fb101
 SHA512:
-  metadata.gz: 7cc84fc8fad2d0b18b53e41b96e8d11bc878d8cdad732bc4a02b3581466fdafb927f3fbec54984e0ca04c839c85417008bef31f6efe21b347ebe4fce7ad7672b
-  data.tar.gz: 2b005e75062ef195f1178074f97efc738d798e69ee9dccbfb58cd88f1155760f4cbc1712da6bbd8de624673fce6d76a2f0982a0b8b3a58d615add5fc2f626c87
+  metadata.gz: fb8cc964841b4eb76cdb6a64a69cf2394f18d7d87863585c1159c2afc12305e5268acb8c508f7922744669793be9364135e79898415a1d6444c57c1e64dbd815
+  data.tar.gz: 3ad57bddb03aaf79c98c1f6f38ac5e92d743f59ce7701e502c092123b8731f0ac1c1d32a209310684662c8c81c6f2a2b44cbdb0a45c29d9265013aaa782ef607

data/CHANGELOG.md

@@ -4,10 +4,20 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+## 0.132.0 — 2026-11-06
+
 ## 0.131.0 — 2026-11-05
 
 ### Added
 
+- **A carousel opens where you tell it: `start:`, and a spotlight opens on its middle
+  slide.** Alex McRitchie saw an empty left half on a spotlight's first slide. `start:`
+  takes an index or `:middle`; it defaults to `:middle` for `style: :spotlight` and to 0
+  for a standard row, so a standard row is unchanged. The slide is the browser's
+  `scroll-initial-target`, so Chromium opens there before the first paint; elsewhere the
+  controller jumps there on connect, with no glide and an empty status line. The dots,
+  `data-current` and both arrows' `aria-disabled` are right from the server. A
+  `#fragment` inside the row wins over the start (task `carousel-start-and-button-glass`).
 - **`.studio-border-glow--clear`.** The border glow on a clear button: no fill, only the
   moving rainbow ring and its halo, with the heading ink as the label (16:1 light, 18:1 dark,
   measured). `<button class="btn studio-border-glow studio-border-glow--clear">`. Under
@@ -36,7 +46,8 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
   same carousel, arrows, dots and keys, but each slide snaps to the centre. The centred
   slide is full size and colour, with an optional `caption:` line under it (a callable on
   the item); its neighbours are smaller (0.75), faded and grey, and the next ones peek at
-  the edges. An arrow or key moves one slide, and every slide gets a dot. Where the browser
+  the edges. An arrow ("Previous slide", "Next slide") or key moves one slide, and every
+  slide gets a dot. It opens on its middle slide (`start:`, below). Where the browser
   has scroll-driven animations (`animation-timeline: view()`), each slide's own view
   timeline drives the look, so it follows the finger; elsewhere the controller marks the
   centred slide `data-current` and CSS transitions it. Reduced motion scales and greys
@@ -84,6 +95,11 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Changed
 
+- **A dark, full-size lit button's fill drops from 0.85 to 0.65 alpha** (`--lit-fill-alpha`),
+  Alex McRitchie's "even more transparent". White label on the primary, measured from painted
+  pixels at the label's median: a dark page 3.95 to 5.62, the lab photo 3.16 to 3.29, a mid-grey
+  backdrop (#808080) 3.25 to 3.42, a lighter one (#a0a0a0) 3.06 to 2.98. Light pages stay solid
+  (3.10).
 - **Back plays the app's page move the other way.** Browser Back (a Turbo restore that Turbo
   marks `back`, or a full load that traverses to an earlier entry) and a click on a link with
   `data-page-transition-back` (every ancestor crumb and the phone's parent link) play the
@@ -95,6 +111,8 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Fixed
 
+- **A standard carousel's `caption:` is a styled line** (small body text under each slide),
+  not bare text; the partial's docs and the README say which style shows which captions.
 - **Review follow-ups on the sidebar, the carousel and the page header** (/tasks/engine-ui-polish-follow-ups).
   The link sidebar's focus ring (its rows, close button, Log out, trigger and geo rows) is
   `ring-primary-ink`, a new ring colour from the theme's primary ink: measured 5.4 to 8.9:1

data/README.md

@@ -328,11 +328,20 @@ as a layout; the block draws each slide. `per_view:` is the wide row's count
 <% end %>
 ```
 
+`caption:` (a callable on the item) writes a small line under each slide.
+
 `style: :spotlight` snaps each slide to the centre: the centred slide is full size and
-colour, with its `caption:` line (a callable on the item) under it, and its neighbours
-are smaller, faded and grey. The arrows and keys move one slide. Where the browser has
-scroll-driven animations the look follows the scroll; elsewhere the controller marks the
-centred slide (`data-current`) and CSS transitions it. Reduced motion only dims.
+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
+keys move one slide. Where the browser has scroll-driven animations the look follows the
+scroll; elsewhere the controller marks the centred slide (`data-current`) and CSS
+transitions it. Reduced motion only dims.
+
+`start:` is the slide the row opens on: an index from 0, or `:middle`. A spotlight opens
+on its middle slide by default, so neither half of the row is empty at load; a standard
+row opens on its first. The browser sets it before the first paint where it has
+`scroll-initial-target`; elsewhere the controller jumps there when it connects, with no
+glide and nothing announced. A `#fragment` link to an element inside the row wins.
 
 ```erb
 <%= render layout: "studio/carousel",

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

@@ -685,6 +685,20 @@ body.modal-open .studio-app-banner {
   flex: 0 0 calc((100% - var(--carousel-n) * var(--carousel-gap)) / (var(--carousel-n) + var(--carousel-peek)));
   min-width: 0;
   scroll-snap-align: start;
+
+  /* The partial's start: past the first slide. A browser with scroll-initial-target
+     opens the row on this slide before the first paint, so the start costs no jump;
+     elsewhere the controller sets it when it connects. */
+  &[data-carousel-start-slide] {
+    scroll-initial-target: nearest;
+  }
+}
+
+/* The caption's line under a slide (the partial's caption:). A standard row shows it
+   under every slide; the spotlight (below) shows it under the centred slide only. */
+@utility carousel-caption {
+  margin-top: 0.5rem;
+  @apply text-sm text-body;
 }
 
 @utility carousel-controls {
@@ -2279,13 +2293,14 @@ html[data-theme-flip]::view-transition-new(*) {
        stop. The violet, centered on the brand colour, is bright enough at its low stop. */
     html.dark[data-surface-style="glass"] :is(.btn-secondary, .btn-danger, .btn-warning, .btn-success) { --lit-glow-stop: var(--lit-top-stop); }
     /* A TOUCH OF TRANSPARENCY on a full-size filled button, dark theme only: a photo behind it
-       shows subtly, and white text holds its contrast at the midpoint. An outer shadow is not painted
+       shows through. At 0.65 (Alex McRitchie, 2026-11-05) white text on the primary measures 5.6:1
+       on a dark page, 3.4:1 over a mid-grey photo and 3.0:1 over a light-mid one (#a0a0a0). An outer shadow is not painted
        under its own box, so the glow never brightens the fill. On a light page the backdrop would
        lift the fill and cost contrast, so it stays solid there. Without a blur, or without relative
        oklch (the gradient would drop out and leave white text on nothing), it stays solid. */
     @supports ((backdrop-filter: blur(1px)) or (-webkit-backdrop-filter: blur(1px))) and (color: oklch(from red l c h)) {
       html.dark[data-surface-style="glass"] :is(.btn-primary, .btn-secondary, .btn-danger, .btn-warning, .btn-success):not(.btn-sm, :disabled, [aria-disabled="true"], [class*=" bg-"], [class^="bg-"]) {
-        --lit-fill-alpha: 0.85;
+        --lit-fill-alpha: 0.65;
         background-color: transparent;
         -webkit-backdrop-filter: blur(6px);
         backdrop-filter: blur(6px);

data/app/javascript/studio/carousel.js

@@ -97,3 +97,11 @@ export function centerStops(slides, clientWidth, max) {
   if (slides.length === 0) return [0]
   return slides.map(({ left, width }) => Math.min(max, Math.max(0, left + width / 2 - clientWidth / 2)))
 }
+
+// The stop a row opens on, from the partial's start index: a standard row with
+// more slides than stops opens at its last stop.
+export function startStop(start, count) {
+  if (!(count > 0)) return 0
+  const index = Math.floor(Number(start)) || 0
+  return Math.min(count - 1, Math.max(0, index))
+}

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

@@ -19,9 +19,14 @@
 // slide is a stop, an arrow moves one slide, and the slide nearest the centre
 // carries data-current, which the CSS styles where scroll-driven animations are
 // missing and under reduced motion.
-import { centerStops } from "studio/carousel"
+//
+// THE START (the partial's start:, data-carousel-start): a row that opens past its
+// first slide. The browser lands there before the first paint where it has
+// scroll-initial-target (engine.css); elsewhere connect() jumps there, with no glide
+// and nothing in the status line. A row already moved (the browser's own start, a
+// restored scroll, a #fragment inside it) is left where it is.
 import { Controller } from "@hotwired/stimulus"
-import { currentStop, hiddenEnds, keyAction, ownsKey, perPage, positionText, stops, targetStop } from "studio/carousel"
+import { TOLERANCE, centerStops, currentStop, hiddenEnds, keyAction, ownsKey, perPage, positionText, startStop, stops, targetStop } from "studio/carousel"
 
 export default class extends Controller {
   static targets = ["track", "slide", "prev", "next", "dot", "status"]
@@ -34,9 +39,27 @@ export default class extends Controller {
       this.observer.observe(this.trackTarget)
     }
     this.element.setAttribute("data-carousel-ready", "")
+    this.openAtStart()
     this.sync()
   }
 
+  openAtStart() {
+    const start = Number(this.element.dataset.carouselStart)
+    if (!(start > 0)) return
+    const track = this.trackTarget
+    if (Math.abs(track.scrollLeft) > TOLERANCE) return
+    const hash = window.location?.hash
+    if (hash && hash.length > 1) {
+      let target = null
+      try { target = document.getElementById(decodeURIComponent(hash.slice(1))) } catch { target = null }
+      if (target && track.contains(target)) return
+    }
+    const { positions } = this.measure()
+    const left = positions[startStop(start, positions.length)]
+    if (left === undefined) return
+    track.scrollTo({ left, behavior: "instant" })
+  }
+
   disconnect() {
     this.trackTarget.removeEventListener("scroll", this.schedule)
     this.observer?.disconnect()

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) %>
+<%# locals: (label:, items:, per_view: 3, id: nil, slide_label: nil, data: {}, class_name: nil, style: :standard, caption: nil, start: nil) %>
 <%# 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:
 
@@ -21,8 +21,16 @@
       style        :standard (slides snap to the start) or :spotlight (the
                    centred slide is full size and colour, its neighbours smaller,
                    faded and grey, and the arrows and keys move one slide).
-      caption      a callable that writes a line under a slide from its item.
-                   The spotlight shows it under the centred slide only.
+      caption      a callable that writes a line under a slide from its item. A
+                   standard row shows a small line under every slide; the
+                   spotlight shows it under the centred slide only.
+      start        the slide the row opens on: an index from 0, or :middle (the
+                   slide at items.size / 2). Defaults to :middle for the spotlight,
+                   so both halves of the row hold a slide at load, and to 0 for a
+                   standard row. The browser sets it before the first paint where
+                   it has scroll-initial-target; elsewhere the controller sets it
+                   when it connects, with no glide and nothing announced. A link
+                   to an id inside the row (#fragment) wins over the start.
 
     THE SPOTLIGHT (engine.css, carousel-spotlight) snaps each slide to the centre.
     Where the browser has scroll-driven animations, each slide's own view timeline
@@ -56,13 +64,20 @@
               when "spotlight" then true
               else raise ArgumentError, "studio/carousel style: #{style.inspect} is not :standard or :spotlight"
               end
+  start = spotlight ? :middle : 0 if start.nil?
+  start_index = case start
+                when :middle, "middle" then total / 2
+                when Integer then start.clamp(0, [total - 1, 0].max)
+                else raise ArgumentError, "studio/carousel start: #{start.inspect} is not an index or :middle"
+                end
+  arrow_noun = spotlight ? "slide" : "slides"
   track_id = id.presence || "carousel-#{label.to_s.parameterize.presence || 'slides'}"
 %>
 <%= tag.section(class: ["carousel", ("carousel-spotlight" if spotlight), class_name].compact.join(" "),
       role: "region",
       aria: { roledescription: "carousel", label: label },
       style: "--carousel-per-view: #{per_view}",
-      data: { studio_controller: "carousel", studio_action: "keydown->carousel#key" }.merge(data)) do %>
+      data: { studio_controller: "carousel", studio_action: "keydown->carousel#key", carousel_start: (start_index.to_s if start_index.positive?) }.compact.merge(data)) do %>
   <%# The track takes focus for the keys, so it carries a name: a group, since a
       bare div may not be named. %>
   <div id="<%= track_id %>" class="carousel-track" tabindex="0" role="group"
@@ -70,25 +85,25 @@
     <% items.each_with_index do |item, index| %>
       <div class="carousel-slide" role="group" aria-roledescription="slide"
            aria-label="<%= slide_label ? slide_label.call(item) : "#{index + 1} of #{total}" %>"
-           data-carousel-target="slide"><% if spotlight %><div class="carousel-spotlight-body"><%= yield(item) %></div><% else %><%= yield(item) %><% end %><% if caption %><div class="carousel-caption"><%= caption.call(item) %></div><% end %></div>
+           data-carousel-target="slide"<%= ' data-carousel-start-slide'.html_safe if start_index.positive? && index == start_index %><%= ' data-current'.html_safe if spotlight && index == start_index %>><% if spotlight %><div class="carousel-spotlight-body"><%= yield(item) %></div><% else %><%= yield(item) %><% end %><% if caption %><div class="carousel-caption"><%= caption.call(item) %></div><% end %></div>
     <% end %>
   </div>
   <div class="carousel-controls">
     <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 %>"
-                aria-controls="<%= track_id %>"<%= ' aria-current="true"'.html_safe if index.zero? %>
+                aria-controls="<%= track_id %>"<%= ' aria-current="true"'.html_safe if index == start_index %>
                 data-carousel-target="dot" data-carousel-index="<%= index %>"
                 data-studio-action="click->carousel#goTo"></button>
       <% end %>
     </div>
     <div class="carousel-arrows">
-      <button type="button" class="carousel-button" aria-label="Previous slides" aria-controls="<%= track_id %>"
-              aria-disabled="true" data-carousel-target="prev" data-studio-action="click->carousel#prev">
+      <button type="button" class="carousel-button" aria-label="Previous <%= arrow_noun %>" aria-controls="<%= track_id %>"
+              aria-disabled="<%= start_index.zero? %>" data-carousel-target="prev" data-studio-action="click->carousel#prev">
         <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="M12.5 15 7.5 10l5-5" stroke-linecap="round" stroke-linejoin="round"/></svg>
       </button>
-      <button type="button" class="carousel-button" aria-label="Next slides" aria-controls="<%= track_id %>"
-              data-carousel-target="next" data-studio-action="click->carousel#next">
+      <button type="button" class="carousel-button" aria-label="Next <%= arrow_noun %>" aria-controls="<%= track_id %>"
+              <%= 'aria-disabled="true" '.html_safe if total.positive? && start_index == total - 1 %>data-carousel-target="next" data-studio-action="click->carousel#next">
         <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="2" aria-hidden="true"><path d="m7.5 5 5 5-5 5" stroke-linecap="round" stroke-linejoin="round"/></svg>
       </button>
     </div>

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

@@ -264,7 +264,7 @@
 
     <%= render layout: "style/specimen",
           locals: { klass: "studio/_carousel (style: :spotlight)",
-                    note: "Centres one slide at full size and colour, with its caption, and shrinks, fades and greys its neighbours as they scroll by.",
+                    note: "Centres one slide at full size and colour, with its caption, and shrinks, fades and greys its neighbours as they scroll by. It opens on its middle slide; start: takes an index instead.",
                     usage: %(<%= render layout: "studio/carousel",\n      locals: { label: "Team", items: @people, style: :spotlight,\n                caption: ->(person) { person.title } } do |person| %\>\n  <%= render "people/card", person: person %\>\n<% end %\>) } do %>
       <div class="w-full min-w-0" data-carousel-spotlight-specimen>
         <%= render layout: "studio/carousel",

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.131.0"
+  VERSION = "0.132.0"
 end

metadata

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