zumly 0.92.5 → 0.97.0

package/src/drivers/driver-helpers.js

@@ -1,4 +1,5 @@
 import { showViewContent } from '../view-visibility.js'
+import { disposeView } from '../view-lifecycle.js'
 
 /**
  * Shared helpers for Zumly transition drivers.
@@ -129,11 +130,15 @@ export function applyZoomOutLastState (element, backwardState) {
  * @param {HTMLElement} canvas - The canvas container
  */
 export function removeViewFromCanvas (element, canvas) {
+  disposeView(element)
   try {
     if (canvas) canvas.removeChild(element)
   } catch (e) {
     try {
-      if (element.parentElement) canvas.removeChild(element.parentElement)
+      if (element?.parentElement && canvas) {
+        disposeView(element.parentElement)
+        canvas.removeChild(element.parentElement)
+      }
     } catch (e2) {
       // Element already removed or re-parented — safe to ignore.
     }
@@ -211,10 +216,10 @@ export const SAFETY_BUFFER_MS = 150
  *
  * @param {function} cleanup - The actual cleanup + onComplete work
  * @param {number} timeoutMs - Safety timeout duration
- * @returns {{ finish: function, safetyTimer: number }}
+ * @returns {{ finish: function, extend: function, safetyTimer: number }}
  *
  * @example
- *   const { finish, safetyTimer } = createFinishGuard(() => {
+ *   const { finish, extend } = createFinishGuard(() => {
  *     cancelAnimations()
  *     applyFinalState()
  *     onComplete()
@@ -224,10 +229,13 @@ export const SAFETY_BUFFER_MS = 150
  *   animation.onfinish = finish
  *
  *   // The safetyTimer ensures finish() runs even if onfinish never fires.
+ *   // Call extend(ms) when the animation actually starts to re-arm the
+ *   // deadline from that moment (styles flush on the next render frame,
+ *   // which can lag far behind the JS call on heavy views).
  */
 export function createFinishGuard (cleanup, timeoutMs) {
   let completed = false
-  const safetyTimer = setTimeout(() => {
+  let safetyTimer = setTimeout(() => {
     if (!completed) { completed = true; cleanup() }
   }, timeoutMs)
 
@@ -238,6 +246,13 @@ export function createFinishGuard (cleanup, timeoutMs) {
       clearTimeout(safetyTimer)
       cleanup()
     },
+    extend (ms) {
+      if (completed) return
+      clearTimeout(safetyTimer)
+      safetyTimer = setTimeout(() => {
+        if (!completed) { completed = true; cleanup() }
+      }, ms)
+    },
     safetyTimer
   }
 }
@@ -263,10 +278,10 @@ export function parseMatrixString (mStr) {
   )
   if (!m) return identityMatrix()
   return {
-    a: parseFloat(m[1]) || 1,
+    a: parseFloat(m[1]),
     b: parseFloat(m[2]) || 0,
     c: parseFloat(m[3]) || 0,
-    d: parseFloat(m[4]) || 1,
+    d: parseFloat(m[4]),
     e: parseFloat(m[5]) || 0,
     f: parseFloat(m[6]) || 0,
   }

package/src/drivers/motion-transition.js

@@ -15,10 +15,10 @@ import {
   applyZoomOutLastState,
   removeViewFromCanvas,
   runLateralInstant,
-  readComputedMatrix,
   interpolateMatrix,
   matrixToString,
 } from './driver-helpers.js'
+import { readTransitionMatrix } from './transform-matrix.js'
 
 export function runTransition (spec, onComplete) {
   const animate = getMotionAnimate()
@@ -131,14 +131,14 @@ function computeMatrixPairs (currentView, previousView, lastView, currentStage,
     if (direction === 'forward') {
       return {
         el,
-        from: readComputedMatrix(el, backward.origin, backward.transform),
-        to: readComputedMatrix(el, backward.origin, forward.transform),
+        from: readTransitionMatrix(el, backward.origin, backward.transform),
+        to: readTransitionMatrix(el, backward.origin, forward.transform),
       }
     } else {
       return {
         el,
-        from: readComputedMatrix(el, forward.origin, forward.transform),
-        to: readComputedMatrix(el, forward.origin, backward.transform),
+        from: readTransitionMatrix(el, forward.origin, forward.transform),
+        to: readTransitionMatrix(el, forward.origin, backward.transform),
       }
     }
   })

package/src/drivers/transform-matrix.js

@@ -0,0 +1,34 @@
+import { identityMatrix, readComputedMatrix } from './driver-helpers.js'
+
+// Zumly emits translate(px, px) followed by an optional uniform scale. These
+// matrices are independent of layout and transform-origin: the browser applies
+// the origin separately when it paints the matrix. Keep other CSS syntax on the
+// computed-style path, including an empty inline value that can expose author CSS.
+const number = '[-+]?(?:\\d*\\.\\d+|\\d+)(?:[eE][-+]?\\d+)?'
+const length = `(${number})(px)?`
+const zumlyTransform = new RegExp(`^(?:translate\\(\\s*${length}\\s*,\\s*${length}\\s*\\)\\s*)?(?:scale\\(\\s*(${number})\\s*\\))?$`)
+
+function parseZumlyMatrix (transformStr) {
+  if (typeof transformStr !== 'string') return null
+  const value = transformStr.trim()
+  if (value === 'none') return identityMatrix()
+  if (!value) return null
+  const match = value.match(zumlyTransform)
+  if (!match) return null
+  const tx = Number(match[1] ?? 0)
+  const ty = Number(match[3] ?? 0)
+  const scale = Number(match[5] ?? 1)
+  // CSS permits unitless zero lengths, but not other unitless translations.
+  if ((tx !== 0 && !match[2]) || (ty !== 0 && !match[4])) return null
+  if (![tx, ty, scale].every(Number.isFinite)) return null
+  return { a: scale, b: 0, c: 0, d: scale, e: tx, f: ty }
+}
+
+/** Apply a driver state, resolving engine transforms without layout reads. */
+export function readTransitionMatrix (element, origin, transformStr) {
+  const matrix = parseZumlyMatrix(transformStr)
+  if (!matrix) return readComputedMatrix(element, origin, transformStr)
+  element.style.transformOrigin = origin
+  element.style.transform = transformStr
+  return matrix
+}

package/src/view-lifecycle.js

@@ -0,0 +1,70 @@
+/** Cleanup belongs to a resolved view instance, never to a cached template. */
+// Drivers can be imported from a separate package entry point, so a module-local
+// WeakMap would not see registrations made by the bundled core. A non-enumerable
+// symbol property shares the scope through the node and is not copied by cloneNode.
+const lifecycleKey = Symbol.for('zumly.viewLifecycles')
+
+function runCleanup (cleanup) {
+  try {
+    const result = cleanup()
+    if (result && typeof result.then === 'function') {
+      result.catch(error => console.error('Zumly: view cleanup failed:', error)) // eslint-disable-line no-console
+    }
+  } catch (error) {
+    console.error('Zumly: view cleanup failed:', error) // eslint-disable-line no-console
+  }
+}
+
+/** Internal scope: accepts registrations before or after resolution finishes. */
+export function createViewLifecycle () {
+  let disposed = false
+  const callbacks = []
+  const lifecycle = {
+    onCleanup (cleanup) {
+      if (typeof cleanup !== 'function') throw new TypeError('Zumly: onCleanup expects a function')
+      if (disposed) runCleanup(cleanup)
+      else callbacks.push(cleanup)
+    },
+    attach (node) {
+      let entries = node[lifecycleKey]
+      if (!entries) {
+        entries = new Set()
+        Object.defineProperty(node, lifecycleKey, { value: entries, configurable: true })
+      }
+      entries.add(lifecycle)
+    },
+    dispose () {
+      if (disposed) return
+      disposed = true
+      for (const cleanup of callbacks.splice(0).reverse()) runCleanup(cleanup)
+    }
+  }
+  return lifecycle
+}
+
+/**
+ * Dispose a view and registered descendants once. Call before permanent removal,
+ * or for an unused async result; temporary detach/keepAlive must not call this.
+ * Async cleanup is started here, with rejections handled, but is not awaited.
+ */
+export function disposeView (node) {
+  if (!node) return
+  // Snapshot only registered nodes before callbacks can mutate the subtree.
+  // A TreeWalker keeps the old reverse document order without allocating an
+  // array/NodeList containing every element of a large component.
+  const nodes = []
+  if (node[lifecycleKey]) nodes.push(node)
+  const document = node.ownerDocument || node
+  const walker = document.createTreeWalker(node, 1) // NodeFilter.SHOW_ELEMENT
+  let descendant
+  while ((descendant = walker.nextNode())) {
+    if (descendant[lifecycleKey]) nodes.push(descendant)
+  }
+  for (let i = nodes.length - 1; i >= 0; i--) {
+    const child = nodes[i]
+    const entries = child[lifecycleKey]
+    if (!entries) continue
+    for (const lifecycle of entries) lifecycle.dispose()
+    delete child[lifecycleKey]
+  }
+}

package/src/view-visibility.js

@@ -0,0 +1,43 @@
+/**
+ * Centralized `content-visibility` handling for view layers during zoom prep / teardown.
+ * Single source of truth — .z-view.hide only handles opacity; this module controls content-visibility.
+ */
+
+// Shared across the bundled engine and separately imported driver helpers.
+const visibilityKey = Symbol.for('zumly.viewVisibility')
+
+function rememberVisibility (element) {
+  if (element[visibilityKey]) return
+  Object.defineProperty(element, visibilityKey, {
+    configurable: true,
+    value: {
+      value: element.style.getPropertyValue('content-visibility'),
+      priority: element.style.getPropertyPriority('content-visibility')
+    }
+  })
+}
+
+/** @param {HTMLElement | null | undefined} element */
+export function hideViewContent (element) {
+  if (!element) return
+  rememberVisibility(element)
+  element.style.contentVisibility = 'hidden'
+}
+
+/**
+ * @param {HTMLElement | null | undefined} element
+ */
+export function showViewContent (element) {
+  if (!element) return
+  rememberVisibility(element)
+  element.style.contentVisibility = 'visible'
+}
+
+/** Release the temporary transition override, preserving the host's CSS policy. */
+export function restoreViewContent (element) {
+  const original = element?.[visibilityKey]
+  if (!original) return
+  if (original.value) element.style.setProperty('content-visibility', original.value, original.priority)
+  else element.style.removeProperty('content-visibility')
+  delete element[visibilityKey]
+}

package/types/zumly.d.ts

@@ -12,7 +12,9 @@ export interface ViewContext {
   /** The componentContext from Zumly constructor options. */
   context: Map<string, unknown> | Record<string, unknown>
   /** Data attributes from the trigger element (e.g. data-id="42" → props.id). */
-  props: Record<string, string>
+  props: Record<string, unknown>
+  /** Register component unmount or resource cleanup, run once when this view is discarded. */
+  onCleanup(callback: () => void | Promise<void>): void
 }
 
 /** A function that receives context and returns a view. */
@@ -53,7 +55,7 @@ export interface TransitionSpec {
   slideDeltaX?: number
   slideDeltaY?: number
   /** When true, driver should not remove the outgoing view from DOM (lateral keepAlive). */
-  keepAlive?: boolean
+  keepAlive?: boolean | 'visible'
 }
 
 /** Custom driver function signature. */
@@ -136,7 +138,7 @@ export interface DepthNavOptions {
 export interface InputsOptions {
   /** Enable wheel zoom-out. Default: true. */
   wheel?: boolean
-  /** Enable keyboard navigation (arrow keys). Default: true. */
+  /** Enable keyboard navigation (Enter/Space on triggers, arrow keys for back). Default: true. */
   keyboard?: boolean
   /** Enable click/mouseup navigation. Default: true. */
   click?: boolean
@@ -193,7 +195,7 @@ export interface ZumlyOptions {
   /** Depth navigation UI. true = default (back button, bottom-left), false = disabled. */
   depthNav?: boolean | DepthNavOptions
   /** Input types to enable/disable. All enabled by default. */
-  inputs?: InputsOptions
+  inputs?: boolean | InputsOptions
   /** Enable deferred rendering (view content inserted after zoom animation). */
   deferred?: boolean
 }
@@ -278,27 +280,28 @@ export class Zumly {
   getCurrentViewName(): string | null
 
   /**
-   * Navigate to a view by name. Unified API for depth and lateral navigation.
+   * Navigate to a view by name. Resolves after the transition completes.
+   * Calls made while another navigation is loading/animating are ignored.
    */
   goTo(viewName: string, options?: GoToOptions): Promise<void>
 
   /**
    * Programmatic zoom to a named view (depth navigation).
-   * Uses a centered synthetic trigger for the transition.
+   * Uses a centered synthetic trigger for the transition. Resolves after animation.
    */
   zoomTo(viewName: string, options?: ZoomToOptions): Promise<void>
 
   /** Zoom into the view indicated by a trigger element with data-to="viewName". */
   zoomIn(el: HTMLElement): Promise<void>
 
-  /** Zoom out one level. No-op at root. */
-  zoomOut(): void
+  /** Zoom out one level. Resolves after animation; no-op at root. */
+  zoomOut(): Promise<void>
 
   /**
    * Navigate back. Pops lateral history first, then zooms out.
-   * Returns a Promise when navigating laterally.
+   * Resolves after the navigation completes.
    */
-  back(): Promise<void> | void
+  back(): Promise<void>
 }
 
 export default Zumly