studio-engine 0.131.0 → 0.133.0

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

@@ -19,22 +19,65 @@
 // 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.
+//
+// A LOOPING row (loop:, data-carousel-loop) wraps: Next at the last stop goes back
+// to the first, Previous at the first to the last, and neither arrow is ever
+// aria-disabled. There are no cloned slides, so a screen reader reads each once:
+// the row glides back across itself.
+//
+// AUTOPLAY (autoplay: seconds, data-carousel-autoplay) moves the row one stop each
+// interval. It holds still while the pointer is over the slides, while keyboard focus
+// is in it, while the tab is hidden or the row is off screen, and after a swipe,
+// wheel, arrow, dot or key until the reader has left it alone a while (idleDelay).
+// The pause button (WCAG 2.2.2) stops it until pressed again; under reduced motion
+// the row starts stopped. A move by autoplay writes nothing to the status line
+// (APG: a rotating carousel does not announce). Without loop it stops at the end.
 import { Controller } from "@hotwired/stimulus"
-import { currentStop, hiddenEnds, keyAction, ownsKey, perPage, positionText, stops, targetStop } from "studio/carousel"
+import {
+  TOLERANCE, autoplayRunning, autoplaySeconds, autoplayStop, centerStops, currentStop, hiddenEnds, idleDelay,
+  initialReasons, keyAction, ownsKey, perPage, positionText, startStop, stops, targetStop, toggleLabel, withReason
+} from "studio/carousel"
+
+const REDUCE = "(prefers-reduced-motion: reduce)"
 
 export default class extends Controller {
-  static targets = ["track", "slide", "prev", "next", "dot", "status"]
+  static targets = ["track", "slide", "prev", "next", "dot", "status", "toggle"]
 
   connect() {
     this.schedule = this.schedule.bind(this)
+    this.loop = this.element.hasAttribute("data-carousel-loop")
     this.trackTarget.addEventListener("scroll", this.schedule, { passive: true })
     if (typeof ResizeObserver === "function") {
       this.observer = new ResizeObserver(this.schedule)
       this.observer.observe(this.trackTarget)
     }
     this.element.setAttribute("data-carousel-ready", "")
+    this.openAtStart()
     this.sync()
+    this.startAutoplay()
+  }
+
+  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() {
@@ -42,6 +85,112 @@ export default class extends Controller {
     this.observer?.disconnect()
     if (this.frame) cancelAnimationFrame(this.frame)
     this.frame = null
+    this.stopAutoplay()
+  }
+
+  // -- autoplay ---------------------------------------------------------------
+
+  startAutoplay() {
+    this.seconds = autoplaySeconds(this.element.dataset.carouselAutoplay)
+    if (this.seconds === null) return
+
+    this.motion = window.matchMedia?.(REDUCE)
+    this.reasons = initialReasons({ reducedMotion: !!this.motion?.matches, hidden: document.hidden })
+    this.listeners = [
+      [this.trackTarget, "pointerenter", (event) => { if (event.pointerType !== "touch") this.pause("hover", true) }],
+      [this.trackTarget, "pointerleave", (event) => { if (event.pointerType !== "touch") this.pause("hover", false) }],
+      [this.element, "focusin", (event) => this.pause("focus", this.keyboardFocus(event.target))],
+      [this.element, "focusout", (event) => { if (!this.element.contains(event.relatedTarget)) this.pause("focus", false) }],
+      [this.trackTarget, "pointerdown", () => this.interacted()],
+      [this.trackTarget, "wheel", () => this.interacted()],
+      [this.trackTarget, "touchstart", () => this.interacted()],
+      [document, "visibilitychange", () => this.pause("hidden", document.hidden)],
+      [this.motion, "change", (event) => { if (event.matches) this.pause("stopped", true) }]
+    ].filter(([target]) => target?.addEventListener)
+    this.listeners.forEach(([target, type, handler]) => target.addEventListener(type, handler, { passive: true }))
+
+    if (typeof IntersectionObserver === "function") {
+      this.viewport = new IntersectionObserver(([entry]) => this.pause("offscreen", !entry.isIntersecting))
+      this.viewport.observe(this.element)
+    }
+    this.refresh()
+  }
+
+  stopAutoplay() {
+    this.listeners?.forEach(([target, type, handler]) => target.removeEventListener(type, handler))
+    this.listeners = null
+    this.viewport?.disconnect()
+    this.viewport = null
+    clearTimeout(this.timer)
+    clearTimeout(this.idle)
+    this.timer = this.idle = null
+  }
+
+  // Focus by keyboard holds the row; a mouse click that focuses an arrow does not.
+  // The pause button is the exception: a reader who tabs to it and presses Play
+  // means it to play.
+  keyboardFocus(target) {
+    if (this.hasToggleTarget && this.toggleTarget.contains(target)) return false
+    try { return target.matches(":focus-visible") } catch { return true }
+  }
+
+  pause(reason, on) {
+    if (this.seconds === null || !this.reasons) return
+    this.reasons = withReason(this.reasons, reason, on)
+    this.refresh()
+  }
+
+  // A swipe, a wheel, an arrow, a dot or a key: hold still until the reader has
+  // left the row alone for idleDelay.
+  interacted() {
+    if (this.seconds === null || !this.reasons) return
+    clearTimeout(this.idle)
+    this.idle = setTimeout(() => { this.idle = null; this.pause("interaction", false) }, idleDelay(this.seconds))
+    this.pause("interaction", true)
+  }
+
+  // The pause button.
+  toggle() {
+    if (this.seconds === null || !this.reasons) return
+    const stopped = !this.reasons.has("stopped")
+    if (!stopped) {
+      // Play at the end of a row that does not loop starts it again from the first.
+      this.sync()
+      if (!this.loop && autoplayStop(this.current, this.positions.length, false) === null && this.current > 0) {
+        this.scrollToStop(0, { announce: false })
+      }
+    }
+    this.pause("stopped", stopped)
+  }
+
+  refresh() {
+    const running = autoplayRunning(this.seconds, this.reasons)
+    const stopped = this.reasons.has("stopped")
+    this.element.toggleAttribute("data-carousel-playing", running)
+    if (this.hasToggleTarget) {
+      this.toggleTarget.setAttribute("aria-label", toggleLabel(stopped))
+      this.toggleTarget.toggleAttribute("data-carousel-stopped", stopped)
+    }
+    if (!running) {
+      clearTimeout(this.timer)
+      this.timer = null
+    } else if (!this.timer) {
+      this.timer = setTimeout(() => this.tick(), this.seconds * 1000)
+    }
+  }
+
+  tick() {
+    this.timer = null
+    this.sync()
+    const count = this.positions.length
+    const to = autoplayStop(this.current, count, this.loop)
+    if (to === null && count > 1) {
+      // The end of a row that does not loop: autoplay is done until Play.
+      this.pause("stopped", true)
+      return
+    }
+    if (to !== null) this.scrollToStop(to, { announce: false })
+    this.refresh()
   }
 
   schedule() {
@@ -81,8 +230,10 @@ export default class extends Controller {
     this.element.toggleAttribute("data-carousel-static", positions.length < 2)
     track.toggleAttribute("data-fade-start", ends.start)
     track.toggleAttribute("data-fade-end", ends.end)
-    if (this.hasPrevTarget) this.prevTarget.setAttribute("aria-disabled", String(!ends.start))
-    if (this.hasNextTarget) this.nextTarget.setAttribute("aria-disabled", String(!ends.end))
+    // A looping row never disables an arrow: each end leads round to the other.
+    const wraps = this.loop && positions.length > 1
+    if (this.hasPrevTarget) this.prevTarget.setAttribute("aria-disabled", String(!wraps && !ends.start))
+    if (this.hasNextTarget) this.nextTarget.setAttribute("aria-disabled", String(!wraps && !ends.end))
     if (this.element.classList.contains("carousel-spotlight")) {
       this.slideTargets.forEach((slide, index) => slide.toggleAttribute("data-current", index === this.current))
     }
@@ -98,6 +249,7 @@ export default class extends Controller {
   next() { this.move("next") }
 
   goTo(event) {
+    this.interacted()
     this.sync()
     this.scrollToStop(Number(event.currentTarget.dataset.carouselIndex))
   }
@@ -116,20 +268,22 @@ export default class extends Controller {
   // A press that goes nowhere (an arrow at its end, Home at the start) scrolls
   // nothing and says nothing: the status line speaks only when the row moves.
   move(action) {
+    this.interacted()
     this.sync()
-    const to = targetStop(action, this.current, this.page, this.positions.length)
+    const to = targetStop(action, this.current, this.page, this.positions.length, this.loop)
     if (to === this.current) return
     this.scrollToStop(to)
   }
 
-  scrollToStop(index) {
+  // announce: false for autoplay, which moves the row without a word.
+  scrollToStop(index, { announce = true } = {}) {
     const left = this.positions[index]
     if (left === undefined) return
 
-    const reduce = window.matchMedia?.("(prefers-reduced-motion: reduce)").matches
+    const reduce = window.matchMedia?.(REDUCE).matches
     this.trackTarget.scrollTo({ left, behavior: reduce ? "auto" : "smooth" })
 
-    if (!this.hasStatusTarget) return
+    if (!announce || !this.hasStatusTarget) return
     const total = this.slideTargets.length
     const last = index === this.positions.length - 1
     const first = last ? Math.max(0, total - this.page) : index

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

@@ -9,8 +9,14 @@
 // row's tabs are links, so they work without it. If it fails to load, the sentinel
 // carries data-studio-controller-failed and engine.css gives the row its bar at
 // all times, so a stuck row never lays a transparent title over the page.
+//
+// It also keeps each quick-links menu's button honest: aria-expanded follows the
+// popover, ArrowDown from the button walks into the list, and where the browser has
+// no anchor positioning it places the list under the button. The popover itself
+// opens, closes on Escape and gives focus back with no script, so a failed load
+// leaves a menu that still works.
 import { Controller } from "@hotwired/stimulus"
-import { hiddenEnds, isStuck, revealBy, sentinelMarksThePlace } from "studio/page_header"
+import { hiddenEnds, isStuck, menuPlacement, revealBy, sentinelMarksThePlace } from "studio/page_header"
 
 export default class extends Controller {
   connect() {
@@ -22,6 +28,7 @@ export default class extends Controller {
     window.addEventListener("resize", this.schedule, { passive: true })
     this.tabs?.addEventListener("scroll", this.schedule, { passive: true })
     this.revealOpenTab()
+    this.connectMenus()
     this.sync()
   }
 
@@ -31,6 +38,53 @@ export default class extends Controller {
     this.tabs?.removeEventListener("scroll", this.schedule)
     if (this.frame) cancelAnimationFrame(this.frame)
     this.frame = null
+    this.disconnectMenus()
+  }
+
+  connectMenus() {
+    this.menus = [...this.row.querySelectorAll(".page-header-menu")].map((menu) => {
+      const button = menu.querySelector("[popovertarget]")
+      const list = menu.querySelector("[popover]")
+      if (!button || !list) return null
+      button.setAttribute("aria-expanded", "false")
+      const onToggle = (event) => this.menuToggled(button, list, event.newState === "open")
+      const onKey = (event) => {
+        if (event.key !== "ArrowDown") return
+        event.preventDefault()
+        if (!list.matches(":popover-open")) list.showPopover?.()
+        list.querySelector("a")?.focus()
+      }
+      list.addEventListener("toggle", onToggle)
+      button.addEventListener("keydown", onKey)
+      return { button, list, onToggle, onKey }
+    }).filter(Boolean)
+  }
+
+  disconnectMenus() {
+    for (const { button, list, onToggle, onKey } of this.menus || []) {
+      list.removeEventListener("toggle", onToggle)
+      button.removeEventListener("keydown", onKey)
+      if (list.matches?.(":popover-open")) list.hidePopover?.()
+    }
+    this.menus = []
+  }
+
+  menuToggled(button, list, open) {
+    button.setAttribute("aria-expanded", String(open))
+    if (open) {
+      if (!anchorsSupported()) this.placeMenu(button, list)
+      return
+    }
+    // The browser gives focus back on Escape; a focus left on nothing comes back too.
+    if (document.activeElement === document.body || list.contains(document.activeElement)) button.focus()
+  }
+
+  placeMenu(button, list) {
+    const place = menuPlacement(button.getBoundingClientRect(), list.getBoundingClientRect(),
+      { width: window.innerWidth, height: window.innerHeight })
+    list.style.top = `${place.top}px`
+    list.style.left = `${place.left}px`
+    list.style.right = "auto"
   }
 
   schedule() {
@@ -46,6 +100,11 @@ export default class extends Controller {
     const ends = this.tabs ? hiddenEnds(this.tabs) : null
 
     this.row.toggleAttribute("data-stuck", stuck)
+    if (!anchorsSupported()) {
+      for (const { button, list } of this.menus || []) {
+        if (list.matches(":popover-open")) this.placeMenu(button, list)
+      }
+    }
     if (!ends) return
     this.tabs.toggleAttribute("data-fade-start", ends.start)
     this.tabs.toggleAttribute("data-fade-end", ends.end)
@@ -72,3 +131,7 @@ export default class extends Controller {
     this.tabs.scrollLeft += revealBy(this.tabs.getBoundingClientRect(), open.getBoundingClientRect())
   }
 }
+
+function anchorsSupported() {
+  return typeof CSS !== "undefined" && CSS.supports?.("anchor-name: --a") && CSS.supports("position-anchor: --a")
+}

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

@@ -6,8 +6,13 @@
 //       <a href="#theme" data-style-section-nav-target="link">Theme</a>
 //
 // Registered by studio/style_guide, which only the style guide loads.
+//
+// A tab's click is studio/in_page_links': a smooth scroll down the page. The clicked tab
+// holds the highlight until that scroll settles, so the row does not run through every tab
+// the scroll passes on its way.
 import { Controller } from "@hotwired/stimulus"
 import { activeIndex } from "studio/style_section_nav"
+import { SCROLL_EVENT, SCROLL_END_EVENT } from "studio/in_page_links"
 
 const ACTIVE = "btn-primary"
 const REST = "btn-neutral"
@@ -22,14 +27,21 @@ export default class extends Controller {
 
   connect() {
     this.schedule = this.schedule.bind(this)
+    this.hold = this.hold.bind(this)
+    this.release = this.release.bind(this)
     window.addEventListener("scroll", this.schedule, { passive: true })
     window.addEventListener("resize", this.schedule)
+    this.element.addEventListener(SCROLL_EVENT, this.hold)
+    document.addEventListener(SCROLL_END_EVENT, this.release)
     this.sync()
   }
 
   disconnect() {
     window.removeEventListener("scroll", this.schedule)
     window.removeEventListener("resize", this.schedule)
+    this.element.removeEventListener(SCROLL_EVENT, this.hold)
+    document.removeEventListener(SCROLL_END_EVENT, this.release)
+    this.held = null
     if (this.frame) cancelAnimationFrame(this.frame)
     this.frame = null
   }
@@ -42,7 +54,21 @@ export default class extends Controller {
     })
   }
 
+  hold(event) {
+    const link = event.detail && event.detail.link
+    if (!this.linkTargets.includes(link)) return
+    this.held = link
+    this.highlight(link)
+  }
+
+  release() {
+    if (!this.held) return
+    this.held = null
+    this.sync()
+  }
+
   sync() {
+    if (this.held) return
     const links = this.linkTargets
     const tops = links.map((link) => {
       const section = document.getElementById(link.getAttribute("href").slice(1))