@mnstry/atelier 0.2.0-alpha.16 → 0.2.0-alpha.18

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()
+}

package/src/ui/primitives/render.mjs

@@ -0,0 +1,22 @@
+/** HTML for the carousel controls and live status (tenant-neutral, escaped). */
+const escape = value => String(value ?? '').replace(/[&<>"']/g, character => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[character]))
+const chevron = direction => `<svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="${direction === 'previous' ? 'M15 5l-7 7 7 7' : 'M9 5l7 7-7 7'}"/></svg>`
+const toggleIcons = '<svg class="system-carousel__pause" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><rect x="6" y="5" width="4" height="14"/><rect x="14" y="5" width="4" height="14"/></svg><svg class="system-carousel__play" width="16" height="16" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true"><path d="M7 5l12 7-12 7z"/></svg>'
+
+/**
+ * Controls for a carousel: optional scroll bar, optional autoplay toggle,
+ * previous and next buttons, and a polite status for reader-initiated moves.
+ */
+export function renderCarouselControls({ label = 'Carousel', autoplay = 'off', scrollbar = true, arrows = true } = {}) {
+  const name = escape(label)
+  const parts = []
+  if (scrollbar) parts.push('<div class="system-carousel__scrollbar" data-scrollbar aria-hidden="true"><span></span><span hidden></span></div>')
+  const buttons = []
+  if (autoplay === 'discrete' || autoplay === 'smooth') buttons.push(`<button type="button" class="system-carousel__button system-carousel__toggle" data-autoplay-toggle aria-label="Pause automatic scrolling" hidden>${toggleIcons}</button>`)
+  if (arrows) {
+    buttons.push(`<button type="button" class="system-carousel__button" data-prev aria-label="Previous: ${name}">${chevron('previous')}</button>`)
+    buttons.push(`<button type="button" class="system-carousel__button" data-next aria-label="Next: ${name}">${chevron('next')}</button>`)
+  }
+  if (buttons.length) parts.push(`<div class="system-carousel__buttons">${buttons.join('')}</div>`)
+  return `<div class="system-carousel__controls" data-controls hidden>${parts.join('')}</div><p class="system-carousel__status" data-status aria-live="polite"></p>`
+}

package/src/ui/primitives/scroll-lock.mjs

@@ -0,0 +1,47 @@
+/**
+ * Layout-stable page scroll lock (browser), the contract documented in
+ * portable-presentation.md: measure the scrollbar a lock hides, pay it back as
+ * body end padding, expose it as --scroll-lock-gap for fixed and sticky
+ * elements, and restore both when the last lock is released. Locks are
+ * counted, so one closing overlay cannot release another's.
+ */
+import { scrollLockGap } from './state.mjs'
+
+const holders = new Set()
+let saved = null
+
+/** Lock page scrolling for `owner` (any value). Returns a release function. */
+export function lockScroll(owner = Symbol('scroll-lock')) {
+  holders.add(owner)
+  if (!saved) {
+    const html = document.documentElement
+    const body = document.body
+    // Measure the body's laid-out width, not the root's clientWidth: with a stable
+    // scrollbar gutter some engines report the root inconsistently during the change.
+    const before = body.getBoundingClientRect().width
+    saved = { padding: body.style.paddingInlineEnd, overflow: html.style.overflow, overscroll: html.style.overscrollBehavior }
+    html.style.overflow = 'hidden'
+    html.style.overscrollBehavior = 'none'
+    const gap = scrollLockGap(before, body.getBoundingClientRect().width)
+    const existing = parseFloat(getComputedStyle(body).paddingInlineEnd) || 0
+    if (gap) body.style.paddingInlineEnd = `${existing + gap}px`
+    html.style.setProperty('--scroll-lock-gap', `${gap}px`)
+    html.dataset.scrollLocked = ''
+  }
+  return () => unlockScroll(owner)
+}
+
+/** Release `owner`'s lock; the page unlocks when no holder remains. */
+export function unlockScroll(owner) {
+  holders.delete(owner)
+  if (holders.size || !saved) return
+  const html = document.documentElement
+  document.body.style.paddingInlineEnd = saved.padding
+  html.style.overflow = saved.overflow
+  html.style.overscrollBehavior = saved.overscroll
+  html.style.removeProperty('--scroll-lock-gap')
+  delete html.dataset.scrollLocked
+  saved = null
+}
+
+export const scrollLocked = () => holders.size > 0

package/src/ui/primitives/state.mjs

@@ -0,0 +1,153 @@
+/**
+ * Pure state for Atelier UI primitives. No DOM access, so every rule
+ * here is testable in Node and shared by the browser enhancers.
+ */
+
+/** Visible window of a carousel at `index`, with arrow availability. */
+export function slideWindow(index, length, visible, loop = false) {
+  const count = Math.max(1, Math.min(visible, length))
+  const max = Math.max(0, length - count)
+  const start = loop ? ((index % length) + length) % length : Math.min(max, Math.max(0, index))
+  return { start, end: Math.min(length, start + count), previousDisabled: !loop && start === 0, nextDisabled: !loop && start === max }
+}
+
+/** A horizontal intent must clearly dominate before the page scroll is taken over. */
+export function dragIntent(dx, dy) {
+  if (Math.abs(dx) < 8 && Math.abs(dy) < 8) return 'pending'
+  return Math.abs(dx) > Math.abs(dy) * 1.2 ? 'horizontal' : 'vertical'
+}
+
+/** Release decides the step: enough distance, or a quick flick. */
+export function swipeStep(dx, dy, elapsed = Infinity) {
+  if (Math.abs(dx) <= Math.abs(dy) * 1.2) return 0
+  const flick = elapsed < 300 && Math.abs(dx) >= 24
+  return Math.abs(dx) >= 50 || flick ? (dx < 0 ? 1 : -1) : 0
+}
+
+/** Motion runs only when the reader allows it, nothing paused it and the tab is visible. */
+export function motionAllowed(reduced, paused, hidden = false) {
+  return !reduced && !paused && !hidden
+}
+
+/** Clone sets needed on each side of a looping track to cover `perSide` slides. */
+export function loopSets(length, perSide) {
+  return Math.max(1, Math.ceil(perSide / Math.max(1, length)))
+}
+
+/** The index of the real slide showing the same content as item `index` of a looping track. */
+export function homeIndex(index, length, sets) {
+  return sets * length + ((index % length) + length) % length
+}
+
+/** Shortest signed distance from item `from` to any copy of real slide `to` in a loop. */
+export function nearestCopy(from, to, length) {
+  let delta = ((to - from) % length + length) % length
+  if (delta > length / 2) delta -= length
+  return delta
+}
+
+/** How far a slide has receded: 0 when it is the current slide, 1 from a full step away. */
+export function recede(position, index) {
+  return Math.min(1, Math.abs(position - index))
+}
+
+/** Few cards: when every card fits side by side (no narrower than `min`), show a still row. */
+export function rowFit(length, natural, gap, room, min) {
+  const width = Math.min(natural, (room - gap * (length - 1)) / length)
+  return width >= min ? Math.floor(width) : 0
+}
+
+/** Whole items that fit in the viewport: the size of one page for page-stepping carousels. */
+export function pageSize(viewport, step) {
+  return step > 0 ? Math.max(1, Math.floor((viewport + 1) / step)) : 1
+}
+
+/** Arrow step for page-stepping carousels. A loop only slightly longer than a page steps by the hidden remainder, so Next never reads as going backwards. */
+export function arrowStep(page, length, loop) {
+  if (!loop) return Math.max(1, page)
+  return Math.max(1, Math.min(page, length - page))
+}
+
+/** Wrap a position into [0, period). */
+export function wrap(position, period) {
+  if (!(period > 0)) return position
+  return ((position % period) + period) % period
+}
+
+/** Scroll position for a pointer on a scroll bar; `grab` is where the thumb was taken hold of. */
+export function scrubPosition(pointerX, railLeft, railWidth, thumbWidth, grab, range) {
+  const travel = railWidth - thumbWidth
+  if (travel <= 0 || range <= 0) return 0
+  const ratio = Math.min(1, Math.max(0, (pointerX - railLeft - grab) / travel))
+  return ratio * range
+}
+
+/** Scroll bar thumb geometry, as fractions of the rail, for a viewport over a content range. */
+export function thumbGeometry(position, range, viewport) {
+  const total = range + viewport
+  if (total <= 0) return { width: 1, left: 0 }
+  const width = Math.min(1, viewport / total)
+  const left = Math.min(Math.max(0, position), range) / total
+  return { width, left }
+}
+
+/**
+ * Thumb for a looping strip: one window over a repeating period. `left` can run
+ * past 1; the part beyond the end is drawn again from the start, so the thumb
+ * leaves the right end and re-enters on the left as the loop continues.
+ */
+export function loopThumbGeometry(position, period, viewport) {
+  if (!(period > 0)) return { width: 1, left: 0 }
+  return { width: Math.min(1, viewport / period), left: wrap(position, period) / period }
+}
+
+/** Speed factor for a drift easing back in after a pause: 0 to 1 over `duration` ms (smoothstep). */
+export function rampFactor(elapsed, duration = 1200) {
+  if (!(duration > 0)) return 1
+  const t = Math.min(1, Math.max(0, elapsed / duration))
+  return t * t * (3 - 2 * t)
+}
+
+/** Delay before autoplay resumes after a reader's interaction. */
+export function resumeDelay(value) {
+  const ms = Number(value)
+  return Number.isFinite(ms) ? Math.min(10000, Math.max(0, ms)) : 2000
+}
+
+/** Momentum after a mouse drag: velocity in px/ms, decaying per 16ms frame. */
+export const MAX_GLIDE_VELOCITY = 2.5
+/** Release velocity in px/ms, capped so a fast fling travels a few cards, not the whole strip. */
+export function releaseVelocity(dx, dt) {
+  const velocity = -dx / Math.max(1, dt)
+  return Math.max(-MAX_GLIDE_VELOCITY, Math.min(MAX_GLIDE_VELOCITY, velocity))
+}
+export function glideStep(position, velocity, elapsed, friction = 0.94) {
+  const dt = Math.min(32, Math.max(0, elapsed))
+  return { position: position + velocity * dt, velocity: velocity * Math.pow(friction, dt / 16) }
+}
+
+/** Autoplay modes: a discrete step every interval, or a smooth drift in px/s. */
+export const AUTOPLAY_MODES = Object.freeze(['off', 'discrete', 'smooth'])
+export function autoplayConfig({ mode = 'off', interval = 6000, speed = 28 } = {}) {
+  return {
+    mode: AUTOPLAY_MODES.includes(mode) ? mode : 'off',
+    interval: Math.max(2500, Number(interval) || 6000),
+    speed: Math.min(400, Math.max(4, Number(speed) || 28)),
+  }
+}
+
+/** Advance a smooth drift; loops within `period` when one is given. */
+export function driftStep(position, speed, elapsed, period = 0, max = Infinity) {
+  const next = position + speed * Math.min(64, Math.max(0, elapsed)) / 1000
+  if (period > 0) return wrap(next, period)
+  return next >= max ? 0 : next
+}
+
+/**
+ * Scroll lock (portable-presentation contract): the width a lock must pay back
+ * is the scrollbar it hides, measured as the growth of the body's laid-out width.
+ * It is zero for overlay scrollbars and for gutters the browser keeps.
+ */
+export function scrollLockGap(widthBefore, widthAfter) {
+  return Math.max(0, Math.round((widthAfter - widthBefore) * 100) / 100)
+}

package/src/ui/primitives/styles.mjs

@@ -0,0 +1,127 @@
+/**
+ * Tenant-neutral carousel geometry and interaction styles. Tenants theme only
+ * through the --system-carousel-* custom properties; markup contract in
+ * docs/reference/ui-primitives.md.
+ */
+export const carouselStyles = `
+.system-carousel { position: relative; }
+.system-carousel [data-carousel-viewport] {
+  overflow-x: auto;
+  overscroll-behavior-inline: contain;
+  scroll-snap-type: x mandatory;
+  scroll-padding-inline: var(--system-carousel-inset, 0px);
+  scrollbar-width: none;
+}
+.system-carousel [data-carousel-viewport]::-webkit-scrollbar { display: none; }
+.system-carousel [data-carousel-track] {
+  display: flex;
+  gap: var(--system-carousel-gap, 1.25rem);
+  padding-inline: var(--system-carousel-inset, 0px);
+}
+.system-carousel [data-carousel-track] > * {
+  flex: 0 0 var(--system-carousel-slide, 100%);
+  min-width: 0;
+  scroll-snap-align: var(--system-carousel-align, start);
+}
+.system-carousel[data-peek] [data-carousel-track] > * { scroll-snap-align: center; }
+.system-carousel[data-drift] [data-carousel-viewport] { scroll-snap-type: none; }
+.system-carousel[data-fit="current"] [data-carousel-viewport] { transition: height 0.3s var(--system-carousel-ease, ease); }
+.system-carousel img { -webkit-user-drag: none; }
+@media (hover: hover) and (pointer: fine) {
+  .system-carousel[data-ready][data-overflow="true"] [data-carousel-viewport] { cursor: grab; }
+}
+.system-carousel[data-dragging] [data-carousel-viewport],
+.system-carousel[data-dragging] [data-carousel-viewport] * { cursor: grabbing; user-select: none; -webkit-user-select: none; }
+
+.system-carousel[data-peek] [data-carousel-track] > * {
+  transform: scale(calc(1 - var(--d, 0) * var(--system-carousel-recede-scale, 0.08)));
+  opacity: calc(1 - var(--d, 0) * var(--system-carousel-recede-fade, 0.35));
+}
+.system-carousel[data-row] [data-carousel-track] { justify-content: center; }
+.system-carousel[data-row] [data-carousel-track] > * { flex-basis: var(--slide-fit); transform: none; opacity: 1; }
+
+.system-carousel[data-carousel="fade"] [data-carousel-track] { display: grid; }
+.system-carousel[data-carousel="fade"] [data-carousel-track] > * {
+  grid-area: 1 / 1;
+  transition: opacity var(--system-carousel-fade-ms, 700ms) var(--system-carousel-ease, ease), visibility 0s linear var(--system-carousel-fade-ms, 700ms);
+}
+.system-carousel[data-carousel="fade"][data-ready] [data-carousel-track] > *:not(.is-current) { opacity: 0; visibility: hidden; }
+.system-carousel[data-carousel="fade"][data-ready] [data-carousel-track] > *.is-current { opacity: 1; visibility: visible; transition-delay: 0s; }
+
+.system-carousel__controls {
+  display: flex;
+  align-items: center;
+  justify-content: var(--system-carousel-controls-justify, center);
+  gap: var(--system-carousel-controls-gap, 1.25rem);
+  margin-top: var(--system-carousel-controls-offset, 1.5rem);
+}
+.system-carousel__controls[hidden], .system-carousel__controls [hidden] { display: none; }
+.system-carousel__buttons { display: flex; gap: 0.5rem; }
+.system-carousel__button {
+  display: grid;
+  place-items: center;
+  width: var(--system-carousel-button-size, 44px);
+  height: var(--system-carousel-button-size, 44px);
+  padding: 0;
+  border: 1px solid var(--system-carousel-button-border, currentColor);
+  border-radius: var(--system-carousel-button-radius, 0);
+  background: var(--system-carousel-button-background, transparent);
+  color: inherit;
+  cursor: pointer;
+  transition: background-color 0.24s var(--system-carousel-ease, ease), border-color 0.24s var(--system-carousel-ease, ease), opacity 0.24s var(--system-carousel-ease, ease);
+}
+.system-carousel__button:disabled { opacity: 0.32; cursor: default; }
+.system-carousel__button:active:not(:disabled) { transform: translateY(1px); }
+.system-carousel__button:focus-visible, .system-carousel__page:focus-visible {
+  outline: 2px solid var(--system-carousel-focus, currentColor);
+  outline-offset: 3px;
+}
+@media (hover: hover) and (pointer: fine) {
+  .system-carousel__button:not(:disabled):hover {
+    background: var(--system-carousel-button-hover-background, rgba(0, 0, 0, 0.06));
+    border-color: var(--system-carousel-button-hover-border, currentColor);
+  }
+}
+.system-carousel__toggle .system-carousel__play,
+.system-carousel__toggle[data-state="paused"] .system-carousel__pause { display: none; }
+.system-carousel__toggle[data-state="paused"] .system-carousel__play { display: block; }
+
+.system-carousel__scrollbar {
+  position: relative;
+  width: var(--system-carousel-scrollbar-width, min(260px, 38vw));
+  height: 28px;
+  overflow: hidden;
+  cursor: grab;
+  touch-action: none;
+}
+.system-carousel__scrollbar::before, .system-carousel__scrollbar > span {
+  content: '';
+  position: absolute;
+  top: 50%;
+  height: var(--system-carousel-scrollbar-thickness, 2px);
+  transform: translateY(-50%);
+}
+.system-carousel__scrollbar::before { left: 0; right: 0; background: var(--system-carousel-scrollbar-track, rgba(0, 0, 0, 0.14)); }
+.system-carousel__scrollbar > span { left: 0; width: 25%; background: var(--system-carousel-scrollbar-thumb, currentColor); transition: height 0.16s var(--system-carousel-ease, ease); }
+.system-carousel__scrollbar:hover > span, .system-carousel[data-scrubbing] .system-carousel__scrollbar > span { height: calc(var(--system-carousel-scrollbar-thickness, 2px) * 2); }
+.system-carousel[data-scrubbing] .system-carousel__scrollbar { cursor: grabbing; }
+
+.system-carousel__pages { display: flex; flex-wrap: wrap; justify-content: center; gap: 0.25rem; }
+.system-carousel__page { width: 24px; height: 24px; padding: 0; border: 0; background: none; cursor: pointer; display: grid; place-items: center; color: inherit; }
+.system-carousel__page::before { content: ''; width: 8px; height: 8px; border-radius: 50%; background: currentColor; opacity: 0.3; transition: opacity 0.24s var(--system-carousel-ease, ease); }
+.system-carousel__page[aria-current="true"]::before { opacity: 1; }
+.system-carousel__page[data-thumb] { width: var(--system-carousel-thumb-width, 72px); height: var(--system-carousel-thumb-height, 90px); opacity: 0.55; background: var(--thumb, none) center / cover; outline-offset: 2px; }
+.system-carousel__page[data-thumb]::before { content: none; }
+.system-carousel__page[data-thumb] img { width: 100%; height: 100%; object-fit: cover; }
+.system-carousel__page[data-thumb][aria-current="true"] { opacity: 1; box-shadow: 0 0 0 1px var(--system-carousel-thumb-current, currentColor); }
+.system-carousel__status {
+  position: absolute; width: 1px; height: 1px; margin: -1px; padding: 0; overflow: hidden;
+  clip: rect(0 0 0 0); white-space: nowrap; border: 0;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .system-carousel [data-carousel-track] > *, .system-carousel__button, .system-carousel__scrollbar > span,
+  .system-carousel[data-fit="current"] [data-carousel-viewport] { transition: none; }
+  .system-carousel[data-peek] [data-carousel-track] > * { transform: none; }
+}
+`

package/templates/external-project-workspace/pack-lifecycle.json

@@ -14,7 +14,9 @@
         "0.2.0-alpha.13",
         "0.2.0-alpha.14",
         "0.2.0-alpha.15",
-        "0.2.0-alpha.16"
+        "0.2.0-alpha.16",
+        "0.2.0-alpha.17",
+        "0.2.0-alpha.18"
       ],
       "status": "active"
     }