zumly 0.92.4 → 0.92.6

package/src/drivers/motion-transition.js

@@ -0,0 +1,178 @@
+/**
+ * Motion (motion.dev) transition driver.
+ * Interpolates computed transform matrices during animation.
+ * Load Motion before use:
+ * <script src="https://cdn.jsdelivr.net/npm/motion@11/dist/motion.min.js"></script>
+ *
+ * @param {Object} spec - Transition spec from the engine
+ * @param {function} onComplete - MUST be called exactly once when done
+ */
+import {
+  parseDurationSec,
+  showViews,
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  runLateralInstant,
+  readComputedMatrix,
+  interpolateMatrix,
+  matrixToString,
+} from './driver-helpers.js'
+
+export function runTransition (spec, onComplete) {
+  const animate = getMotionAnimate()
+  if (!animate || typeof animate !== 'function') {
+    console.warn('Zumly Motion driver: Motion not loaded. Add <script src="https://cdn.jsdelivr.net/npm/motion@11/dist/motion.min.js"></script>')
+    onComplete()
+    return
+  }
+
+  const { type, currentView, previousView, lastView, currentStage, duration, ease, canvas } = spec
+  if (!currentView || !previousView || !currentStage) {
+    onComplete()
+    return
+  }
+
+  const durationSec = parseDurationSec(duration)
+
+  if (type === 'lateral') {
+    runLateralInstant(spec, onComplete)
+  } else if (type === 'zoomIn') {
+    runZoomIn(animate, currentView, previousView, lastView, currentStage, durationSec, ease, onComplete)
+  } else if (type === 'zoomOut') {
+    runZoomOut(animate, currentView, previousView, lastView, currentStage, durationSec, ease, canvas, onComplete)
+  } else {
+    onComplete()
+  }
+}
+
+// ─── Zoom In ─────────────────────────────────────────────────────────
+
+function runZoomIn (animate, currentView, previousView, lastView, currentStage, durationSec, ease, onComplete) {
+  showViews(currentView, previousView, lastView)
+
+  const matrices = computeMatrixPairs(
+    currentView, previousView, lastView, currentStage, 'forward'
+  )
+  applyMatricesAtProgress(matrices, 0)
+
+  const stagger = currentStage.stagger || 0
+  const staggerSec = stagger / 1000
+  const durationMs = durationSec * 1000
+  const totalSec = durationSec + (matrices.length > 2 ? staggerSec * 2 : staggerSec)
+
+  const controls = animate(0, 1, {
+    duration: totalSec,
+    ease: normalizeEasing(ease),
+    onUpdate: t => {
+      const elapsed = t * totalSec * 1000
+      applyStaggeredMatrices(matrices, elapsed, durationMs, stagger)
+    },
+  })
+
+  controls.then(() => {
+    applyZoomInEndState(currentView, currentStage)
+    applyZoomInEndState(previousView, currentStage)
+    if (lastView) applyZoomInEndState(lastView, currentStage)
+    onComplete()
+  }).catch(() => onComplete())
+}
+
+// ─── Zoom Out ────────────────────────────────────────────────────────
+
+function runZoomOut (animate, currentView, previousView, lastView, currentStage, durationSec, ease, canvas, onComplete) {
+  const v1 = currentStage.views[1]
+  const v2 = lastView && currentStage.views[2] ? currentStage.views[2] : null
+  const to1 = v1.backwardState
+  const to2 = v2 ? v2.backwardState : null
+
+  const matrices = computeMatrixPairs(
+    currentView, previousView, lastView, currentStage, 'backward'
+  )
+  applyMatricesAtProgress(matrices, 0)
+
+  const stagger = currentStage.stagger || 0
+  const staggerSec = stagger / 1000
+  const durationMs = durationSec * 1000
+  const totalSec = durationSec + (matrices.length > 2 ? staggerSec * 2 : staggerSec)
+
+  const controls = animate(0, 1, {
+    duration: totalSec,
+    ease: normalizeEasing(ease),
+    onUpdate: t => {
+      const elapsed = t * totalSec * 1000
+      applyStaggeredMatrices(matrices, elapsed, durationMs, stagger)
+    },
+  })
+
+  controls.then(() => {
+    removeViewFromCanvas(currentView, canvas)
+    applyZoomOutPreviousState(previousView, to1)
+    if (lastView && to2) applyZoomOutLastState(lastView, to2)
+    onComplete()
+  }).catch(() => onComplete())
+}
+
+// ─── Matrix computation ──────────────────────────────────────────────
+
+function computeMatrixPairs (currentView, previousView, lastView, currentStage, direction) {
+  const v0 = currentStage.views[0]
+  const v1 = currentStage.views[1]
+  const v2 = lastView && currentStage.views[2] ? currentStage.views[2] : null
+
+  const entries = [
+    { el: currentView, backward: v0.backwardState, forward: v0.forwardState },
+    { el: previousView, backward: v1.backwardState, forward: v1.forwardState },
+  ]
+  if (v2) entries.push({ el: lastView, backward: v2.backwardState, forward: v2.forwardState })
+
+  return entries.map(({ el, backward, forward }) => {
+    if (direction === 'forward') {
+      return {
+        el,
+        from: readComputedMatrix(el, backward.origin, backward.transform),
+        to: readComputedMatrix(el, backward.origin, forward.transform),
+      }
+    } else {
+      return {
+        el,
+        from: readComputedMatrix(el, forward.origin, forward.transform),
+        to: readComputedMatrix(el, forward.origin, backward.transform),
+      }
+    }
+  })
+}
+
+function applyMatricesAtProgress (matrices, t) {
+  for (const { el, from, to } of matrices) {
+    el.style.transform = matrixToString(interpolateMatrix(from, to, t))
+  }
+}
+
+function applyStaggeredMatrices (matrices, elapsed, durationMs, stagger) {
+  for (let i = 0; i < matrices.length; i++) {
+    const { el, from, to } = matrices[i]
+    const delay = i * stagger
+    const localElapsed = Math.max(0, elapsed - delay)
+    const t = durationMs > 0 ? Math.min(1, localElapsed / durationMs) : 1
+    el.style.transform = matrixToString(interpolateMatrix(from, to, t))
+  }
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function getMotionAnimate () {
+  const g = typeof globalThis !== 'undefined' ? globalThis : typeof window !== 'undefined' ? window : {}
+  return g.motion?.animate || g.Motion?.animate || g.animate
+}
+
+function normalizeEasing (ease) {
+  if (typeof ease !== 'string') return 'easeInOut'
+  const s = ease.toLowerCase()
+  if (s === 'linear') return 'linear'
+  if (s.includes('ease-in-out')) return 'easeInOut'
+  if (s.includes('ease-in')) return 'easeIn'
+  if (s.includes('ease-out')) return 'easeOut'
+  return ease
+}

package/src/drivers/none-transition.js

@@ -0,0 +1,54 @@
+/**
+ * No-animation transition driver.
+ * Applies final state immediately and calls onComplete synchronously.
+ * Useful for tests, instant UX, or reduced-motion preference.
+ *
+ * This is the simplest possible Zumly driver — a good starting point
+ * for writing your own. See docs/DRIVER_API.md for the full guide.
+ *
+ * @param {Object} spec - Transition spec from the engine
+ * @param {function} onComplete - MUST be called exactly once when done
+ */
+import {
+  showViews,
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  runLateralInstant,
+} from './driver-helpers.js'
+
+export function runTransition (spec, onComplete) {
+  const { type, currentView, previousView, lastView, currentStage, canvas } = spec
+
+  if (!currentView || !previousView || !currentStage) {
+    onComplete()
+    return
+  }
+
+  if (type === 'lateral') {
+    runLateralInstant(spec, onComplete)
+    return
+  }
+
+  if (type === 'zoomIn') {
+    showViews(currentView, previousView, lastView)
+    applyZoomInEndState(currentView, currentStage)
+    applyZoomInEndState(previousView, currentStage)
+    if (lastView) applyZoomInEndState(lastView, currentStage)
+    onComplete()
+    return
+  }
+
+  if (type === 'zoomOut') {
+    removeViewFromCanvas(currentView, canvas)
+    showViews(previousView, lastView)
+    applyZoomOutPreviousState(previousView, currentStage.views[1].backwardState)
+    if (lastView) applyZoomOutLastState(lastView, currentStage.views[2].backwardState)
+    onComplete()
+    return
+  }
+
+  // Unknown type — still must call onComplete
+  onComplete()
+}

package/src/drivers/waapi-transition.js

@@ -0,0 +1,243 @@
+/**
+ * Web Animations API transition driver.
+ * Uses element.animate() — no external dependencies.
+ *
+ * @param {Object} spec - Transition spec from the engine
+ * @param {function} onComplete - MUST be called exactly once when done
+ */
+import {
+  parseDurationMs,
+  showViews,
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  createFinishGuard,
+  SAFETY_BUFFER_MS,
+} from './driver-helpers.js'
+
+// Re-export for tests that import it directly
+export { parseDurationMs }
+
+export function runTransition (spec, onComplete) {
+  const { type, currentView, previousView, lastView, currentStage, duration, ease, canvas } = spec
+
+  if (!currentView || !previousView || !currentStage) {
+    onComplete()
+    return
+  }
+
+  const durationMs = parseDurationMs(duration)
+
+  if (type === 'lateral') {
+    runLateralAnimated(spec, durationMs, ease, onComplete)
+    return
+  }
+
+  if (type === 'zoomIn') {
+    runZoomIn(currentView, previousView, lastView, currentStage, durationMs, ease, onComplete)
+    return
+  }
+
+  if (type === 'zoomOut') {
+    runZoomOut(currentView, previousView, lastView, currentStage, durationMs, ease, canvas, onComplete)
+    return
+  }
+
+  onComplete()
+}
+
+// ─── Zoom In ─────────────────────────────────────────────────────────
+
+function runZoomIn (currentView, previousView, lastView, currentStage, durationMs, ease, onComplete) {
+  showViews(currentView, previousView, lastView)
+
+  const v0 = currentStage.views[0]
+  const v1 = currentStage.views[1]
+  const v2 = lastView && currentStage.views[2] ? currentStage.views[2] : null
+
+  // Set initial state from snapshot
+  currentView.style.transformOrigin = v0.backwardState.origin
+  currentView.style.transform = v0.backwardState.transform
+  previousView.style.transformOrigin = v1.backwardState.origin
+  previousView.style.transform = v1.backwardState.transform
+  if (v2) {
+    lastView.style.transformOrigin = v2.backwardState.origin
+    lastView.style.transform = v2.backwardState.transform
+  }
+
+  // Start WAAPI animations with stagger delay
+  const stagger = currentStage.stagger || 0
+  const anims = []
+  anims.push(currentView.animate(
+    [{ transform: v0.backwardState.transform }, { transform: v0.forwardState.transform }],
+    { duration: durationMs, easing: ease, fill: 'forwards' }
+  ))
+  anims.push(previousView.animate(
+    [{ transform: v1.backwardState.transform }, { transform: v1.forwardState.transform }],
+    { duration: durationMs, delay: stagger, easing: ease, fill: 'forwards' }
+  ))
+  if (v2) {
+    anims.push(lastView.animate(
+      [{ transform: v2.backwardState.transform }, { transform: v2.forwardState.transform }],
+      { duration: durationMs, delay: stagger * 2, easing: ease, fill: 'forwards' }
+    ))
+  }
+
+  const maxDelay = v2 ? stagger * 2 : stagger
+  const { finish } = createFinishGuard(() => {
+    cancelAll(anims)
+    try {
+      applyZoomInEndState(currentView, currentStage)
+      applyZoomInEndState(previousView, currentStage)
+      if (lastView) applyZoomInEndState(lastView, currentStage)
+    } catch (e) { /* DOM cleanup should not block onComplete */ }
+    onComplete()
+  }, durationMs + maxDelay + SAFETY_BUFFER_MS)
+
+  Promise.all(anims.map(a => a.finished)).then(finish).catch(finish)
+}
+
+// ─── Zoom Out ────────────────────────────────────────────────────────
+
+function runZoomOut (currentView, previousView, lastView, currentStage, durationMs, ease, canvas, onComplete) {
+  const v0 = currentStage.views[0]
+  const v1 = currentStage.views[1]
+  const v2 = lastView && currentStage.views[2] ? currentStage.views[2] : null
+  const to1 = v1.backwardState
+  const to2 = v2 ? v2.backwardState : null
+
+  // Set current view initial state
+  currentView.style.transformOrigin = v0.forwardState.origin
+  currentView.style.transform = v0.forwardState.transform
+
+  // Defer animation start to ensure computed styles are flushed
+  requestAnimationFrame(() => {
+    requestAnimationFrame(() => {
+      previousView.style.transformOrigin = v1.forwardState.origin
+      if (lastView && v2) lastView.style.transformOrigin = v2.forwardState.origin
+
+      // Use computed transform as "from" so animation runs from actual position
+      const from1 = previousView.style.transform || getComputedStyle(previousView).transform || v1.forwardState.transform
+      const from2 = lastView && v2
+        ? (lastView.style.transform || getComputedStyle(lastView).transform || v2.forwardState.transform)
+        : null
+
+      const stagger = currentStage.stagger || 0
+      const anims = []
+      anims.push(currentView.animate(
+        [{ transform: v0.forwardState.transform }, { transform: v0.backwardState.transform }],
+        { duration: durationMs, easing: ease, fill: 'forwards' }
+      ))
+      anims.push(previousView.animate(
+        [{ transform: from1 }, { transform: to1.transform }],
+        { duration: durationMs, delay: stagger, easing: ease, fill: 'both' }
+      ))
+      if (lastView && to2) {
+        anims.push(lastView.animate(
+          [{ transform: from2 }, { transform: to2.transform }],
+          { duration: durationMs, delay: stagger * 2, easing: ease, fill: 'both' }
+        ))
+      }
+
+      // Let WAAPI drive transforms — remove inline styles so WAAPI fill takes over
+      previousView.style.removeProperty('transform')
+      if (lastView) lastView.style.removeProperty('transform')
+
+      const maxDelay = (lastView && to2) ? stagger * 2 : stagger
+      const { finish } = createFinishGuard(() => {
+        cancelAll(anims)
+        try {
+          removeViewFromCanvas(currentView, canvas)
+          applyZoomOutPreviousState(previousView, to1)
+          if (lastView && to2) applyZoomOutLastState(lastView, to2)
+        } catch (e) { /* DOM cleanup should not block onComplete */ }
+        onComplete()
+      }, durationMs + maxDelay + SAFETY_BUFFER_MS)
+
+      Promise.all(anims.map(a => a.finished)).then(finish).catch(finish)
+    })
+  })
+}
+
+// ─── Lateral ────────────────────────────────────────────────────────
+
+function runLateralAnimated (spec, durationMs, ease, onComplete) {
+  const {
+    currentView: incomingView,
+    previousView: outgoingView,
+    backView,
+    backViewState,
+    lastView,
+    lastViewState,
+    incomingTransformStart,
+    incomingTransformEnd,
+    outgoingTransform,
+    outgoingTransformEnd,
+    currentStage,
+    canvas
+  } = spec
+  const v0 = currentStage.views[0]
+
+  showViews(incomingView)
+  incomingView.classList.replace('is-new-current-view', 'is-current-view')
+  incomingView.classList.remove('zoom-current-view', 'has-no-events')
+  incomingView.style.transformOrigin = v0.forwardState.origin
+
+  const anims = []
+
+  // Incoming view slides in
+  anims.push(incomingView.animate(
+    [{ transform: incomingTransformStart, opacity: 0 }, { transform: incomingTransformEnd, opacity: 1 }],
+    { duration: durationMs, easing: ease, fill: 'forwards' }
+  ))
+
+  // Outgoing view slides out (skip animation in 'visible' keepAlive mode)
+  if (spec.keepAlive !== 'visible') {
+    anims.push(outgoingView.animate(
+      [{ transform: outgoingTransform, opacity: 1 }, { transform: outgoingTransformEnd, opacity: 0 }],
+      { duration: durationMs, easing: ease, fill: 'forwards' }
+    ))
+  }
+
+  // Back view shifts
+  if (backView && backViewState) {
+    anims.push(backView.animate(
+      [{ transform: backViewState.transformStart }, { transform: backViewState.transformEnd }],
+      { duration: durationMs, easing: ease, fill: 'forwards' }
+    ))
+  }
+
+  // Last view shifts
+  if (lastView && lastViewState) {
+    anims.push(lastView.animate(
+      [{ transform: lastViewState.transformStart }, { transform: lastViewState.transformEnd }],
+      { duration: durationMs, easing: ease, fill: 'forwards' }
+    ))
+  }
+
+  const { finish } = createFinishGuard(() => {
+    cancelAll(anims)
+    // Apply final state
+    incomingView.style.transform = incomingTransformEnd || v0.forwardState.transform
+    if (backView && backViewState) backView.style.transform = backViewState.transformEnd
+    if (lastView && lastViewState) lastView.style.transform = lastViewState.transformEnd
+    if (spec.keepAlive) {
+      outgoingView.style.opacity = ''
+      outgoingView.style.transform = outgoingTransformEnd
+    } else {
+      removeViewFromCanvas(outgoingView, canvas)
+    }
+    onComplete()
+  }, durationMs + SAFETY_BUFFER_MS)
+
+  Promise.all(anims.map(a => a.finished)).then(finish).catch(finish)
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────────
+
+function cancelAll (anims) {
+  for (const a of anims) {
+    try { a.cancel() } catch (e) { /* already finished or removed */ }
+  }
+}

package/types/zumly.d.ts

@@ -77,7 +77,7 @@ export interface ViewEntry {
 
 /** Zoom snapshot stored in the storedViews stack. */
 export interface ZoomSnapshot {
-  level: number
+  zoomLevel: number
   views: [ViewEntry, ViewEntry, ViewEntry | null, ViewEntry | null]
   scale?: number
   stagger?: number
@@ -98,8 +98,10 @@ export interface TransitionOptions {
   effects?: [string] | [string, string]
   /** Progressive delay (ms) between view layers during zoom. Default: 0. */
   stagger?: number
-  /** Parallax intensity (0-1). Default: 0. */
+  /** Accepted for compatibility but not applied yet (always treated as 0). */
   parallax?: number
+  /** Hide the trigger element during zoom: 'fade' (crossfade), true (hide), or false. Default: false. */
+  hideTrigger?: 'fade' | boolean
 }
 
 /** Lateral navigation UI configuration. */
@@ -194,8 +196,6 @@ export interface ZumlyOptions {
   inputs?: InputsOptions
   /** Enable deferred rendering (view content inserted after zoom animation). */
   deferred?: boolean
-  /** Hide trigger mode during zoom: 'fade', 'remove', or falsy. */
-  hideTrigger?: string | false
 }
 
 // ─── Events ─────────────────────────────────────────────────────────