zumly 0.92.3 → 0.92.5

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. */
@@ -114,6 +116,14 @@ export interface LateralNavOptions {
   keepAlive?: boolean | 'visible'
   /** Position of the lateral nav bar. Default: 'bottom-center'. */
   position?: 'bottom-center' | 'top-center'
+  /**
+   * Declared sibling order for lateral navigation. Takes precedence over
+   * inferring order/slide direction from trigger positions in the parent view.
+   * Array = one lateral group; map = keyed by parent view name.
+   * @example ['today', 'tomorrow', 'week']
+   * @example { home: ['today', 'tomorrow', 'week'] }
+   */
+  siblings?: string[] | Record<string, string[]>
 }
 
 /** Depth navigation UI configuration. */
@@ -186,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 ─────────────────────────────────────────────────────────