@mnstry/atelier 0.2.0-alpha.15 → 0.2.0-alpha.17

package/src/ui/primitives/carousel.mjs

@@ -0,0 +1,551 @@
+/**
+ * Carousel enhancer (browser). Progressive enhancement over plain HTML: without
+ * script every slide is a native horizontal scroller (track) or a stacked list
+ * (fade). See docs/reference/ui-primitives.md for the markup contract.
+ *
+ * Track carousels scroll natively (CSS scroll snap), so touch, trackpad, wheel
+ * and keyboard keep the platform's physics. Script adds seamless loops over
+ * inert clones, mouse drag (with momentum for multi-card strips), a draggable
+ * scroll bar, arrows, pages or thumbnails, a live status, height that follows
+ * the current slide, receding neighbours, a still row when every card fits,
+ * and discrete or smooth autoplay with a pause control.
+ */
+import {
+  arrowStep, autoplayConfig, dragIntent, driftStep, glideStep, homeIndex, loopSets, nearestCopy, releaseVelocity,
+  pageSize, recede, rowFit, scrubPosition, slideWindow, swipeStep, thumbGeometry, wrap,
+} from './state.mjs'
+import { animationAllowed, onMotionChange } from './motion.mjs'
+
+const q = (root, selectors) => root.querySelector(selectors)
+const qa = (root, selectors) => [...root.querySelectorAll(selectors)]
+const finePointer = () => matchMedia('(hover: hover) and (pointer: fine)').matches
+
+// Move keyboard focus before its slide becomes inert or hidden.
+function focusAvailable(candidates, reveal = false) {
+  const target = candidates.find(element => element && !element.matches(':disabled') && !element.closest('[inert], [hidden]') && element.getClientRects().length && getComputedStyle(element).visibility !== 'hidden')
+  target?.focus({ preventScroll: !reveal })
+  return !!target && document.activeElement === target
+}
+function revealControlFocus(controls) {
+  const focused = document.activeElement
+  if (focused instanceof HTMLElement && controls?.contains(focused) && focused.getClientRects().length) focused.scrollIntoView({ block: 'nearest', inline: 'nearest', behavior: 'instant' })
+}
+function preserveSlideFocus(slides, shown, control) {
+  if (!slides.some(slide => slide !== shown && slide.contains(document.activeElement))) return
+  const controls = control?.closest('[data-controls]')
+  focusAvailable([control, ...(controls ? controls.querySelectorAll('button') : [])])
+}
+
+/** Enhance every `[data-carousel]` under `root`. Safe to call more than once. */
+export function enhanceCarousels(root = document) {
+  return qa(root, '[data-carousel]').map(enhanceCarousel).filter(Boolean)
+}
+
+export function enhanceCarousel(root) {
+  if (root.dataset.ready !== undefined) return null
+  const track = q(root, '[data-carousel-track], .carousel__track')
+  if (!track) return null
+  // Slides are the track's children; `data-slide` narrows that when a track holds other elements.
+  const children = [...track.children].filter(element => !element.hasAttribute('data-clone'))
+  const slides = children.some(element => element.hasAttribute('data-slide')) ? children.filter(element => element.hasAttribute('data-slide')) : children
+  const parts = {
+    root, track, slides, n: slides.length,
+    label: root.getAttribute('aria-label') ?? 'Carousel',
+    viewport: q(root, '[data-carousel-viewport], .carousel__viewport') || track,
+    controls: q(root, '[data-controls]'),
+    back: q(root, '[data-prev]'),
+    next: q(root, '[data-next]'),
+    pages: qa(root, '[data-page]'),
+    status: q(root, '[data-status]'),
+    count: q(root, '[data-count]'),
+    scrollbar: q(root, '[data-scrollbar]'),
+    toggle: q(root, '[data-autoplay-toggle]'),
+    autoplay: autoplayConfig({ mode: root.dataset.autoplay, interval: root.dataset.interval, speed: root.dataset.speed }),
+  }
+  if (parts.n < 2) { if (parts.controls) parts.controls.hidden = true; root.dataset.ready = ''; return null }
+  slides.forEach((slide, i) => {
+    slide.setAttribute('role', 'group')
+    slide.setAttribute('aria-roledescription', 'slide')
+    if (!slide.hasAttribute('aria-label')) slide.setAttribute('aria-label', `${i + 1} of ${parts.n}`)
+  })
+  root.querySelectorAll('img, a').forEach(element => element.setAttribute('draggable', 'false'))
+  // Thumbnail pages without their own image show the slide's image.
+  parts.pages.forEach((page, i) => {
+    if (!page.hasAttribute('data-thumb') || page.querySelector('img')) return
+    const img = slides[i]?.querySelector('img')
+    const set = () => img?.currentSrc && page.style.setProperty('--thumb', `url("${img.currentSrc}")`)
+    img?.complete ? set() : img?.addEventListener('load', set, { once: true })
+  })
+  return root.dataset.carousel === 'fade' ? initFade(parts) : initTrack(parts)
+}
+
+/* ------------------------------------------------------------------ autoplay */
+
+function createAutoplay({ root, toggle, autoplay }, { advance, startDrift, stopDrift, canRun }) {
+  const reasons = new Set()
+  let userPaused = root.dataset.autoplayPaused !== undefined
+  let onScreen = true
+  let timer = 0
+  const enabled = () => autoplay.mode !== 'off' && animationAllowed() && canRun()
+  const running = () => enabled() && !userPaused && !reasons.size && onScreen
+  const stop = () => { clearTimeout(timer); timer = 0; stopDrift() }
+  const start = () => {
+    stop()
+    if (!running()) return
+    if (autoplay.mode === 'discrete') timer = setTimeout(() => { advance(); start() }, autoplay.interval)
+    else startDrift()
+  }
+  const sync = () => {
+    root.dataset.autoplayState = enabled() ? (userPaused ? 'paused' : reasons.size ? 'held' : 'playing') : 'off'
+    if (!toggle) return
+    toggle.hidden = !enabled()
+    toggle.setAttribute('aria-label', userPaused ? 'Play automatic scrolling' : 'Pause automatic scrolling')
+    toggle.dataset.state = userPaused ? 'paused' : 'playing'
+  }
+  const hold = reason => { reasons.add(reason); stop(); sync() }
+  const release = (reason, delay = 0) => {
+    const go = () => { reasons.delete(reason); start(); sync() }
+    delay ? setTimeout(go, delay) : go()
+  }
+  if (autoplay.mode !== 'off') {
+    toggle?.addEventListener('click', () => { userPaused = !userPaused; start(); sync() })
+    root.addEventListener('mouseenter', () => { if (finePointer()) hold('hover') })
+    root.addEventListener('mouseleave', () => release('hover'))
+    root.addEventListener('focusin', event => { if (!toggle?.contains(event.target)) hold('focus') })
+    root.addEventListener('focusout', event => { if (!root.contains(event.relatedTarget)) release('focus') })
+    root.addEventListener('pointerdown', event => { if (event.pointerType !== 'mouse') hold('touch') })
+    const lift = event => { if (event.pointerType !== 'mouse') release('touch', 2500) }
+    root.addEventListener('pointerup', lift)
+    root.addEventListener('pointercancel', lift)
+    let wheelTimer = 0
+    root.addEventListener('wheel', () => { hold('wheel'); clearTimeout(wheelTimer); wheelTimer = setTimeout(() => release('wheel'), 2500) }, { passive: true })
+    onMotionChange(() => { start(); sync() })
+    if ('IntersectionObserver' in window) new IntersectionObserver(entries => { onScreen = entries.some(entry => entry.isIntersecting); start(); sync() }, { threshold: 0.25 }).observe(root)
+  }
+  return { start, stop, hold, release, sync, restart: () => { if (autoplay.mode === 'discrete') start() }, smooth: autoplay.mode === 'smooth', active: running }
+}
+
+/* ------------------------------------------------------------- scroll bar */
+
+function bindScrollbar({ root, scrollbar }, { geometry, scrubTo, begin, end }) {
+  const thumb = scrollbar?.querySelector('span, [data-scrollbar-thumb]')
+  if (!scrollbar || !thumb) return () => {}
+  scrollbar.addEventListener('pointerdown', event => {
+    if (event.button > 0) return
+    event.preventDefault()
+    const rail = scrollbar.getBoundingClientRect()
+    const box = thumb.getBoundingClientRect()
+    const onThumb = event.clientX >= box.left && event.clientX <= box.right
+    const grab = onThumb ? event.clientX - box.left : box.width / 2
+    scrollbar.setPointerCapture(event.pointerId)
+    root.dataset.scrubbing = ''
+    begin()
+    const move = x => scrubTo(scrubPosition(x, rail.left, rail.width, box.width, grab, geometry().range))
+    move(event.clientX)
+    const onMove = moveEvent => move(moveEvent.clientX)
+    const onUp = () => { scrollbar.removeEventListener('pointermove', onMove); delete root.dataset.scrubbing; end() }
+    scrollbar.addEventListener('pointermove', onMove)
+    scrollbar.addEventListener('pointerup', onUp, { once: true })
+    scrollbar.addEventListener('pointercancel', onUp, { once: true })
+  })
+  return () => {
+    const { position, range, viewport } = geometry()
+    const { width, left } = thumbGeometry(position, range, viewport)
+    thumb.style.width = `${width * 100}%`
+    thumb.style.left = `${left * 100}%`
+    scrollbar.hidden = range <= 1
+  }
+}
+
+/* ------------------------------------------------------------------ track */
+
+function initTrack(parts) {
+  const { root, viewport, track, slides, n, label, controls, back, next, pages, status, count } = parts
+  const loop = root.hasAttribute('data-loop')
+  const peek = root.hasAttribute('data-peek') || root.classList.contains('carousel--peek')
+  // select="current": one slide is current and the rest are inert (slideshows).
+  // select="visible": every card on screen stays interactive (product strips).
+  const visibleMode = root.dataset.select === 'visible'
+  const pageStep = (root.dataset.step || (visibleMode ? 'page' : 'item')) === 'page'
+  // fit="current": the strip is as tall as the slide in view, blending between heights as they pass.
+  const fitCurrent = root.dataset.fit === 'current'
+  const rowMin = Number(root.dataset.rowMin) || 400
+  let sets = 0
+  let items = slides
+  let step = 0, current = -1, target = null, announce = false, row = false, timer = 0, realigned = false
+  let home = 0, intent = false, drifting = false, gliding = 0, scrubbing = false
+  let heights = [], padY = 0, padTop = 0
+  let drag = null, suppressClick = false
+
+  const buildClones = perSide => {
+    track.querySelectorAll('[data-clone]').forEach(clone => clone.remove())
+    sets = loop ? loopSets(n, perSide) : 0
+    if (sets) {
+      const clone = slide => {
+        const copy = slide.cloneNode(true)
+        copy.removeAttribute('id'); copy.querySelectorAll('[id]').forEach(element => element.removeAttribute('id'))
+        copy.dataset.clone = ''; copy.inert = true; copy.setAttribute('aria-hidden', 'true')
+        return copy
+      }
+      const copies = () => Array.from({ length: sets }, () => slides.map(clone)).flat()
+      track.prepend(...copies()); track.append(...copies())
+    }
+    items = [...track.children]
+  }
+  const first = () => sets * n
+  const position = () => (step ? viewport.scrollLeft / step : 0)
+  const scrollToIndex = (index, smooth) => viewport.scrollTo({ left: index * step, behavior: smooth && animationAllowed() ? 'smooth' : 'instant' })
+  const perPage = () => (pageStep ? arrowStep(pageSize(viewport.clientWidth, step), n, loop) : 1)
+  const lastIndex = () => (step ? Math.max(0, Math.round((viewport.scrollWidth - viewport.clientWidth) / step)) : 0)
+
+  const fitHeight = pos => {
+    if (!fitCurrent || row || !heights.length) return
+    const a = Math.floor(pos), h = i => heights[((i % n) + n) % n]
+    viewport.style.height = `${h(a) + (h(a + 1) - h(a)) * (pos - a) + padY}px`
+  }
+  const placeArrows = () => {
+    const middle = fitCurrent && heights.length ? padTop + Math.min(...heights) / 2 : viewport.offsetHeight / 2
+    root.style.setProperty('--mid', `${viewport.offsetTop + middle}px`)
+  }
+  const measureHeights = () => {
+    if (!fitCurrent) return
+    const style = getComputedStyle(viewport)
+    padTop = parseFloat(style.paddingTop); padY = padTop + parseFloat(style.paddingBottom)
+    heights = slides.map(slide => slide.offsetHeight)
+  }
+
+  const geometry = () => {
+    if (sets) {
+      const period = n * step
+      return { position: wrap(viewport.scrollLeft - first() * step, period), range: Math.max(0, period - viewport.clientWidth), viewport: viewport.clientWidth }
+    }
+    return { position: viewport.scrollLeft, range: Math.max(0, viewport.scrollWidth - viewport.clientWidth), viewport: viewport.clientWidth }
+  }
+  const paintScrollbar = bindScrollbar(parts, {
+    geometry,
+    scrubTo: offset => { viewport.scrollLeft = (sets ? first() * step : 0) + offset },
+    begin: () => { stopGlide(); scrubbing = true; intent = true; viewport.style.scrollSnapType = 'none'; player.hold('scrub') },
+    end: () => { scrubbing = false; intent = true; settleSoon(); player.release('scrub') },
+  })
+
+  const paint = () => {
+    if (row || !step) return
+    const pos = position(), c = Math.max(0, Math.min(items.length - 1, Math.round(pos)))
+    if (peek) items.forEach((item, i) => item.style.setProperty('--d', recede(pos, i).toFixed(3)))
+    fitHeight(pos)
+    paintScrollbar()
+    if (c === current) return
+    current = c
+    if (!loop && back && next) { back.disabled = c <= 0; next.disabled = c >= lastIndex() }
+    if (!visibleMode) preserveSlideFocus(items, items[c], pages[c % n])
+    items.forEach((item, i) => {
+      const shown = i === c
+      item.classList.toggle('is-current', shown)
+      if (!visibleMode && !item.hasAttribute('data-clone')) { item.inert = !shown; item.toggleAttribute('aria-hidden', !shown) }
+    })
+    pages.forEach((page, i) => page.setAttribute('aria-current', String(i === c % n)))
+    if (count) count.textContent = `${(c % n) + 1} / ${n}`
+  }
+
+  // Once still: step back onto the real slide showing the same content (identical, so invisible).
+  const settle = () => {
+    if (row || !step || drag || gliding || scrubbing) return
+    if (drifting) return
+    if (player.smooth && player.active()) return
+    if (!intent) {
+      if (!player.smooth) viewport.style.removeProperty('scroll-snap-type')
+      const goal = (first() + home) * step
+      if (Math.abs(viewport.scrollLeft - Math.min(goal, viewport.scrollWidth - viewport.clientWidth)) > 1) scrollToIndex(first() + home, false)
+      paint(); return
+    }
+    const c = Math.round(position())
+    if (!player.smooth && !realigned && Math.abs(viewport.scrollLeft - c * step) > 2 && c < lastIndex()) {
+      realigned = true; viewport.style.removeProperty('scroll-snap-type'); scrollToIndex(c, true)
+      if (!animationAllowed()) settle()
+      return
+    }
+    realigned = false
+    if (sets && (c < first() || c >= first() + n)) viewport.scrollTo({ left: viewport.scrollLeft + (homeIndex(c, n, sets) - c) * step, behavior: 'instant' })
+    home = ((Math.round(position()) % n) + n) % n
+    if (!sets) home = Math.round(position())
+    intent = false; target = null
+    if (!player.smooth) viewport.style.removeProperty('scroll-snap-type')
+    paint()
+    if (announce && status) { status.textContent = `${label}: ${(current % n) + 1} of ${n}`; announce = false }
+  }
+  const settleSoon = () => { if (!('onscrollend' in window)) { clearTimeout(timer); timer = setTimeout(settle, 140) } else requestAnimationFrame(() => settle()) }
+
+  const go = (delta, { user = true } = {}) => {
+    if (row || !step) return
+    stopGlide()
+    intent = true
+    let base = target ?? Math.round(position())
+    if (sets) {
+      const equivalent = homeIndex(base, n, sets)
+      if (equivalent !== base) { viewport.scrollTo({ left: viewport.scrollLeft + (equivalent - base) * step, behavior: 'instant' }); base = equivalent }
+    } else if (loop && delta > 0 && base >= lastIndex()) {
+      delta = -base // a loop too short for clones still wraps
+    } else if (loop && delta < 0 && base <= 0) {
+      delta = lastIndex()
+    }
+    const to = sets ? base + delta : Math.max(0, Math.min(lastIndex(), base + delta))
+    target = to; announce = user
+    scrollToIndex(to, true)
+  }
+  const goTo = index => go(sets ? nearestCopy(target ?? Math.round(position()), index, n) : index - (target ?? Math.round(position())))
+
+  const measure = () => {
+    const focusedSlide = slides.findIndex(slide => slide.contains(document.activeElement))
+    const keep = row && focusedSlide >= 0 ? focusedSlide : home
+    home = keep
+    const controlFocused = controls?.contains(document.activeElement)
+    const focusedPage = pages.findIndex(page => page.contains(document.activeElement))
+    root.style.removeProperty('--slide-fit'); delete root.dataset.row
+    const gap = parseFloat(getComputedStyle(track).columnGap) || 0
+    const fit = peek ? rowFit(n, slides[0].offsetWidth, gap, root.clientWidth, rowMin) : 0
+    row = fit > 0
+    viewport.style.removeProperty('height')
+    if (row) {
+      root.dataset.row = ''; root.style.setProperty('--slide-fit', `${fit}px`)
+      slides.forEach(slide => { slide.inert = false; slide.removeAttribute('aria-hidden'); slide.classList.remove('is-current'); slide.style.removeProperty('--d') })
+      if (controlFocused) {
+        const shown = slides[focusedPage >= 0 ? focusedPage : keep]
+        if (!focusAvailable([...shown.querySelectorAll('a[href], button, [tabindex]:not([tabindex="-1"])')], true)) { root.tabIndex = -1; root.focus() }
+      }
+      if (controls) controls.hidden = true
+      current = -1
+      return
+    }
+    // Fractional widths matter: offsetLeft rounds, and the error grows per card.
+    const width = parseFloat(getComputedStyle(slides[0]).width)
+    step = width + gap
+    root.style.setProperty('--slide-px', `${width}px`)
+    const fitsAll = !sets && viewport.scrollWidth - viewport.clientWidth <= 1
+    if (loop) {
+      const needed = pageSize(viewport.clientWidth, step) + (peek ? 4 : 1)
+      if (!sets || loopSets(n, needed) !== sets) buildClones(needed)
+      // A loop that cannot fill the screen with one set falls back to plain wrapping arrows.
+      if (n * step < viewport.clientWidth) { track.querySelectorAll('[data-clone]').forEach(clone => clone.remove()); sets = 0; items = slides }
+    }
+    root.dataset.overflow = String(!(fitsAll || (!sets && viewport.scrollWidth - viewport.clientWidth <= 1)))
+    if (controls) controls.hidden = root.dataset.overflow === 'false'
+    measureHeights()
+    current = -1; target = null
+    scrollToIndex(first() + keep, false)
+    paint()
+    placeArrows()
+    revealControlFocus(controls)
+    player.sync()
+  }
+
+  // Momentum for multi-card strips; slideshows step one slide per swipe instead.
+  function stopGlide() { cancelAnimationFrame(gliding); gliding = 0 }
+  const glide = velocity => {
+    if (!animationAllowed() || Math.abs(velocity) < 0.05) { settle(); return }
+    let last = performance.now(), pos = viewport.scrollLeft
+    const frame = now => {
+      const next = glideStep(pos, velocity, now - last)
+      last = now; pos = next.position; velocity = next.velocity
+      viewport.scrollLeft = pos
+      const atEdge = !sets && (pos <= 0 || pos >= viewport.scrollWidth - viewport.clientWidth)
+      if (Math.abs(velocity) > 0.03 && !atEdge) gliding = requestAnimationFrame(frame)
+      else { gliding = 0; settle() }
+    }
+    gliding = requestAnimationFrame(frame)
+  }
+
+  // Smooth autoplay keeps its own sub-pixel position so slow speeds never stall on rounding.
+  let driftFrame = 0
+  const player = createAutoplay(parts, {
+    advance: () => go(perPage(), { user: false }),
+    canRun: () => !row && root.dataset.overflow !== 'false',
+    startDrift: () => {
+      drifting = true
+      viewport.style.scrollSnapType = 'none'
+      let pos = viewport.scrollLeft, last = 0
+      const frame = now => {
+        if (last) {
+          if (sets) pos = first() * step + driftStep(pos - first() * step, parts.autoplay.speed, now - last, n * step)
+          else pos = driftStep(pos, parts.autoplay.speed, now - last, 0, viewport.scrollWidth - viewport.clientWidth)
+          viewport.scrollLeft = pos
+        }
+        last = now
+        driftFrame = requestAnimationFrame(frame)
+      }
+      driftFrame = requestAnimationFrame(frame)
+    },
+    stopDrift: () => {
+      if (!driftFrame) return
+      cancelAnimationFrame(driftFrame); driftFrame = 0; drifting = false
+      home = ((Math.round(position()) - first()) % n + n) % n
+    },
+  })
+  if (player.smooth) root.dataset.drift = ''
+
+  viewport.addEventListener('scroll', () => {
+    requestAnimationFrame(paint)
+    if (!('onscrollend' in window)) { clearTimeout(timer); timer = setTimeout(settle, 140) }
+  }, { passive: true })
+  viewport.addEventListener('scrollend', settle)
+  const user = () => { intent = true; stopGlide() }
+  for (const type of ['pointerdown', 'touchstart', 'wheel', 'keydown']) viewport.addEventListener(type, user, { passive: true })
+
+  back?.addEventListener('click', () => { go(-perPage()); player.restart() })
+  next?.addEventListener('click', () => { go(perPage()); player.restart() })
+  pages.forEach((page, i) => page.addEventListener('click', () => { goTo(i); player.restart() }))
+  root.addEventListener('keydown', event => {
+    if (row || event.altKey || event.ctrlKey || event.metaKey) return
+    if (event.target.closest?.('input, select, textarea, [contenteditable]')) return
+    const keys = { ArrowLeft: () => go(-1), ArrowRight: () => go(1), Home: () => goTo(0), End: () => goTo(n - 1) }
+    if (!keys[event.key]) return
+    event.preventDefault(); keys[event.key]()
+  })
+
+  // Mouse drag (touch and trackpads already scroll natively): follow the pointer, then settle.
+  root.addEventListener('pointerdown', event => {
+    if (row || event.pointerType !== 'mouse' || event.button !== 0 || event.target.closest('button, [data-scrollbar], input, select, textarea')) return
+    if (!viewport.contains(event.target)) return
+    stopGlide()
+    drag = { id: event.pointerId, x: event.clientX, y: event.clientY, t: event.timeStamp, left: viewport.scrollLeft, state: 'pending', samples: [{ x: event.clientX, t: event.timeStamp }] }
+    suppressClick = false
+  })
+  root.addEventListener('pointermove', event => {
+    if (!drag || event.pointerId !== drag.id) return
+    const dx = event.clientX - drag.x, dy = event.clientY - drag.y
+    if (drag.state === 'pending') {
+      drag.state = dragIntent(dx, dy)
+      if (drag.state === 'vertical') { drag = null; return }
+      if (drag.state === 'horizontal') {
+        root.setPointerCapture(event.pointerId); root.dataset.dragging = ''
+        viewport.style.scrollSnapType = 'none'; intent = true; player.hold('drag')
+      }
+    }
+    if (drag.state === 'horizontal') {
+      viewport.scrollLeft = drag.left - dx
+      drag.samples.push({ x: event.clientX, t: event.timeStamp })
+      if (drag.samples.length > 6) drag.samples.shift()
+    }
+  })
+  const release = (event, cancelled) => {
+    if (!drag || event.pointerId !== drag.id) return
+    const { x, y, t, left, state, samples } = drag
+    drag = null; delete root.dataset.dragging
+    if (state !== 'horizontal') return
+    suppressClick = true
+    player.release('drag')
+    if (visibleMode || player.smooth) {
+      const a = samples[0], b = samples.at(-1)
+      glide(cancelled ? 0 : releaseVelocity(b.x - a.x, b.t - a.t))
+      return
+    }
+    const start = Math.round(left / step), near = Math.round(position())
+    const flick = cancelled ? 0 : swipeStep(event.clientX - x, event.clientY - y, event.timeStamp - t)
+    let to = near === start ? start + flick : near
+    if (!sets) to = Math.max(0, Math.min(lastIndex(), to))
+    announce = to !== start; target = to
+    scrollToIndex(to, true)
+    if (Math.abs(viewport.scrollLeft - to * step) < 1) settle()
+  }
+  root.addEventListener('pointerup', event => release(event, false))
+  root.addEventListener('pointercancel', event => release(event, true))
+  root.addEventListener('dragstart', event => event.preventDefault())
+  root.addEventListener('click', event => {
+    if (suppressClick) { event.preventDefault(); event.stopPropagation(); suppressClick = false; return }
+    // A click on a receding neighbour brings it to the centre instead of following its link.
+    if (visibleMode || !peek || row || !step || event.detail === 0 || !viewport.contains(event.target)) return
+    const box = viewport.getBoundingClientRect()
+    const offset = Math.round((event.clientX - (box.left + box.width / 2)) / step)
+    if (offset) { event.preventDefault(); event.stopPropagation(); go(offset) }
+  }, true)
+
+  let lastWidth = 0
+  new ResizeObserver(() => requestAnimationFrame(() => { const w = root.clientWidth; if (Math.abs(w - lastWidth) > 0.5) { lastWidth = w; measure() } })).observe(root)
+  if (fitCurrent) {
+    const watch = new ResizeObserver(() => requestAnimationFrame(() => { if (row || !step) return; measureHeights(); fitHeight(position()); placeArrows() }))
+    slides.forEach(slide => watch.observe(slide))
+  }
+  root.dataset.ready = ''
+  measure()
+  player.start()
+  player.sync()
+  return { root, go, goTo, pause: () => player.hold('api'), play: () => player.release('api') }
+}
+
+/* ------------------------------------------------------------------- fade */
+
+function initFade(parts) {
+  const { root, viewport, slides, n, label, controls, back, next, pages, status, count } = parts
+  const loop = root.hasAttribute('data-loop')
+  const fit = root.dataset.fit === 'current'
+  let active = 0
+  const fitHeight = () => { if (fit) viewport.style.height = `${slides[active].offsetHeight}px` }
+  const placeArrows = () => {
+    const height = fit ? Math.min(...slides.map(slide => slide.offsetHeight)) : viewport.offsetHeight
+    root.style.setProperty('--mid', `${viewport.offsetTop + height / 2}px`)
+  }
+  let lastWidth = root.clientWidth
+  const watch = new ResizeObserver(() => requestAnimationFrame(() => {
+    const width = root.clientWidth, resized = Math.abs(width - lastWidth) > 0.5
+    lastWidth = width
+    fitHeight(); placeArrows()
+    if (resized) revealControlFocus(controls)
+  }))
+  watch.observe(root); slides.forEach(slide => watch.observe(slide))
+  const render = announce => {
+    const state = slideWindow(active, n, 1, loop)
+    active = state.start
+    if (back) back.disabled = state.previousDisabled
+    if (next) next.disabled = state.nextDisabled
+    preserveSlideFocus(slides, slides[active], pages[active])
+    slides.forEach((slide, i) => { const shown = i === active; slide.classList.toggle('is-current', shown); slide.inert = !shown })
+    pages.forEach((page, i) => page.setAttribute('aria-current', String(i === active)))
+    if (count) count.textContent = `${active + 1} / ${n}`
+    fitHeight()
+    if (announce && status) status.textContent = `${label}: ${active + 1} of ${n}`
+    root.dispatchEvent(new CustomEvent('carousel:change', { detail: { index: active } }))
+  }
+  const go = (targetIndex, announce = true) => { active = loop ? ((targetIndex % n) + n) % n : Math.max(0, Math.min(n - 1, targetIndex)); render(announce) }
+  const player = createAutoplay(parts, { advance: () => go(active + 1, false), canRun: () => true, startDrift: () => {}, stopDrift: () => {} })
+
+  back?.addEventListener('click', () => { go(active - 1); player.restart() })
+  next?.addEventListener('click', () => { go(active + 1); player.restart() })
+  pages.forEach((page, i) => page.addEventListener('click', () => { go(i); player.restart() }))
+  root.addEventListener('keydown', event => {
+    if (event.altKey || event.ctrlKey || event.metaKey) return
+    const keys = { ArrowLeft: () => go(active - 1), ArrowRight: () => go(active + 1), Home: () => go(0), End: () => go(n - 1) }
+    if (!keys[event.key]) return
+    event.preventDefault(); keys[event.key]()
+  })
+
+  // Swipes: a horizontal gesture changes slide; a vertical one stays a page scroll.
+  let drag = null, suppressClick = false
+  root.addEventListener('pointerdown', event => {
+    if (!event.isPrimary || event.button > 0 || event.target.closest('button')) return
+    drag = { id: event.pointerId, x: event.clientX, y: event.clientY, t: event.timeStamp, state: 'pending' }
+    suppressClick = false
+  })
+  root.addEventListener('pointermove', event => {
+    if (!drag || event.pointerId !== drag.id || drag.state !== 'pending') return
+    drag.state = dragIntent(event.clientX - drag.x, event.clientY - drag.y)
+    if (drag.state === 'vertical') drag = null
+    else if (drag.state === 'horizontal') { root.setPointerCapture(event.pointerId); root.dataset.dragging = '' }
+  })
+  const release = (event, cancelled) => {
+    if (!drag || event.pointerId !== drag.id) return
+    const horizontal = drag.state === 'horizontal', delta = cancelled ? 0 : swipeStep(event.clientX - drag.x, event.clientY - drag.y, event.timeStamp - drag.t)
+    drag = null; delete root.dataset.dragging
+    if (!horizontal) return
+    suppressClick = true
+    if (delta) { go(active + delta); player.restart() }
+  }
+  root.addEventListener('pointerup', event => release(event, false))
+  root.addEventListener('pointercancel', event => release(event, true))
+  root.addEventListener('click', event => { if (suppressClick) { event.preventDefault(); event.stopPropagation(); suppressClick = false } }, true)
+
+  if (controls) controls.hidden = false
+  root.dataset.ready = ''
+  render(false)
+  placeArrows()
+  player.start(); player.sync()
+  return { root, go, pause: () => player.hold('api'), play: () => player.release('api') }
+}

package/src/ui/primitives/disclosure.mjs

@@ -0,0 +1,50 @@
+/**
+ * Native <details> disclosures with interruptible open and close motion
+ * (browser). Keyboard and no-script behaviour stay native. data-state follows
+ * the reader's intent at once, so icons turn with the click while the panel
+ * is still moving. Reduced motion opens and closes instantly.
+ */
+import { animationAllowed } from './motion.mjs'
+
+const PROPERTIES = ['height', 'paddingTop', 'paddingBottom', 'marginTop', 'marginBottom', 'opacity']
+
+export function enhanceDisclosures(root = document, { openMs = 360, closeMs = 280 } = {}) {
+  root.querySelectorAll('details').forEach(details => {
+    const summary = details.querySelector(':scope > summary')
+    const content = summary?.nextElementSibling
+    if (!summary || !content || details.dataset.disclosureReady !== undefined) return
+    details.dataset.disclosureReady = ''
+    details.dataset.state = details.open ? 'open' : 'closed'
+    if (!content.animate) return
+    let animation = null
+    let opening = details.open
+    const values = () => {
+      const style = getComputedStyle(content)
+      return Object.fromEntries(PROPERTIES.map(property => [property, style[property]]))
+    }
+    const clear = () => { content.style.overflow = ''; content.style.boxSizing = '' }
+    summary.addEventListener('click', event => {
+      event.preventDefault()
+      if (!animation) opening = details.open
+      opening = !opening
+      details.dataset.state = opening ? 'open' : 'closed'
+      if (!opening && content.contains(document.activeElement)) summary.focus()
+      const current = animation ? values() : null
+      animation?.cancel()
+      animation = null
+      if (!animationAllowed()) { details.open = opening; clear(); return }
+      details.open = true
+      content.style.overflow = 'hidden'
+      content.style.boxSizing = 'border-box'
+      const expanded = values()
+      const collapsed = Object.fromEntries(PROPERTIES.map(property => [property, property === 'opacity' ? '0' : '0px']))
+      animation = content.animate([current || (opening ? collapsed : expanded), opening ? expanded : collapsed], {
+        duration: opening ? openMs : closeMs,
+        easing: opening ? 'cubic-bezier(.22, 1, .36, 1)' : 'cubic-bezier(.4, 0, 1, 1)',
+        fill: 'both',
+      })
+      animation.onfinish = () => { details.open = opening; animation.cancel(); animation = null; clear() }
+    })
+    details.addEventListener('toggle', () => { if (!animation) details.dataset.state = details.open ? 'open' : 'closed' })
+  })
+}

package/src/ui/primitives/index.mjs

@@ -0,0 +1,7 @@
+/**
+ * Atelier UI primitives (Node-safe): pure state, styles and markup
+ * helpers. Browser enhancers live in ./browser.mjs (@mnstry/atelier/ui/primitives/browser).
+ */
+export * from './state.mjs'
+export { carouselStyles } from './styles.mjs'
+export { renderCarouselControls } from './render.mjs'

package/src/ui/primitives/motion.mjs

@@ -0,0 +1,50 @@
+/**
+ * One owner for motion (browser): the reduced-motion preference and hidden tabs
+ * stop every effect started through these helpers.
+ */
+import { motionAllowed } from './state.mjs'
+
+const listeners = new Set()
+const running = new Set()
+let reduced = null
+let started = false
+
+function preference() {
+  if (!reduced && typeof matchMedia === 'function') reduced = matchMedia('(prefers-reduced-motion: reduce)')
+  return reduced
+}
+
+/** True when animation may run now. */
+export function animationAllowed() {
+  return motionAllowed(Boolean(preference()?.matches), false, typeof document !== 'undefined' && document.hidden)
+}
+
+/** Call `listener` whenever the motion preference or tab visibility changes. */
+export function onMotionChange(listener) {
+  listeners.add(listener)
+  startMotionWatch()
+  return () => listeners.delete(listener)
+}
+
+/** A Web Animation owned by the motion layer: skipped when motion is off, finished when it turns off. */
+export function animate(element, frames, options) {
+  if (!animationAllowed() || !element.animate) return null
+  const animation = element.animate(frames, options)
+  running.add(animation)
+  animation.finished.catch(() => {}).finally(() => running.delete(animation))
+  return animation
+}
+
+function sync() {
+  document.documentElement.classList.toggle('motion-paused', Boolean(preference()?.matches))
+  if (!animationAllowed()) running.forEach(animation => animation.finish())
+  listeners.forEach(listener => listener())
+}
+
+export function startMotionWatch() {
+  if (started || typeof document === 'undefined') return
+  started = true
+  preference()?.addEventListener('change', sync)
+  document.addEventListener('visibilitychange', sync)
+  sync()
+}