zumly 0.9.11 → 0.92.0

package/docs/DRIVER_API.md

@@ -0,0 +1,340 @@
+# Writing a Zumly Transition Driver
+
+**Zumly** (*Z over XY* — focus-driven navigation, zoom into what matters) delegates animation to **transition drivers**. A driver controls **how** views move during zoom-in, zoom-out, and lateral navigation. The engine computes **what** moves where (transforms, origins, snapshot); the driver applies motion — CSS keyframes, WAAPI, GSAP, Motion, Anime.js, or a custom timeline.
+
+**See also:** [README.md](../README.md) (options, built-in drivers, plugins) · [geometry-optimization.md](geometry-optimization.md) (how zoom-out layout reads are batched before the driver runs).
+
+## Quick start
+
+A driver is an object with a single method:
+
+```js
+const myDriver = {
+  runTransition(spec, onComplete) {
+    // Animate views from spec.currentStage backward → forward states
+    // Call onComplete() when done — this is mandatory.
+  }
+}
+```
+
+Register it in the constructor:
+
+```js
+new Zumly({
+  mount: '.canvas',
+  initialView: 'home',
+  views: { home, detail },
+  transitions: {
+    driver: myDriver.runTransition, // pass the function directly
+    duration: '600ms',
+    ease: 'ease-in-out',
+  },
+})
+```
+
+Or as a factory function:
+
+```js
+transitions: {
+  driver: (spec, onComplete) => myDriver.runTransition(spec, onComplete),
+}
+```
+
+---
+
+## The `spec` object
+
+Your `runTransition(spec, onComplete)` receives a spec with everything needed:
+
+### Common fields (all transition types)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `type` | `'zoomIn' \| 'zoomOut' \| 'lateral'` | What kind of transition |
+| `currentView` | `HTMLElement` | The incoming view (zoom-in) or outgoing view (zoom-out) |
+| `previousView` | `HTMLElement` | The parent view |
+| `lastView` | `HTMLElement \| null` | Grandparent view (null at depth ≤ 2) |
+| `currentStage` | `object` | Snapshot with computed states (see below) |
+| `duration` | `string` | e.g. `'500ms'`, `'1s'` |
+| `ease` | `string` | CSS easing, e.g. `'ease-in-out'` |
+| `canvas` | `HTMLElement` | The canvas container (zoom-out and lateral only) |
+
+### `currentStage.views[]` — The animation data
+
+An array of view entries, indexed by role:
+
+```
+views[0] → current view  (the one zooming in/out)
+views[1] → previous view (the parent)
+views[2] → last view     (grandparent, when depth > 2)
+```
+
+Each entry has:
+
+```js
+{
+  viewName: 'detail',
+  backwardState: {
+    origin: '125px 100px',    // CSS transform-origin
+    transform: 'translate(50px, 60px) scale(0.25)',  // "start" for zoom-in, "end" for zoom-out
+    duration: '500ms',
+    ease: 'ease-in-out',
+  },
+  forwardState: {
+    origin: '125px 100px',
+    transform: 'translate(100px, 50px)',  // "end" for zoom-in, "start" for zoom-out
+    duration: '500ms',
+    ease: 'ease-in-out',
+  }
+}
+```
+
+**For zoom-in:** animate from `backwardState.transform` → `forwardState.transform`.
+**For zoom-out:** animate from `forwardState.transform` → `backwardState.transform`.
+
+### Lateral-specific fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `backView` | `HTMLElement \| null` | The parent view behind current depth |
+| `backViewState` | `{ transformStart, transformEnd }` | Slide transforms for backView |
+| `lastViewState` | `{ transformStart, transformEnd }` | Slide transforms for lastView |
+| `incomingTransformStart` | `string` | Incoming view start transform |
+| `incomingTransformEnd` | `string` | Incoming view final transform |
+| `outgoingTransform` | `string` | Outgoing view current transform |
+| `outgoingTransformEnd` | `string` | Outgoing view exit transform |
+| `slideDeltaX` | `number` | Horizontal slide distance |
+| `slideDeltaY` | `number` | Vertical slide distance |
+
+---
+
+## What your driver MUST do
+
+### 1. Call `onComplete()` — always, exactly once
+
+This is the #1 rule. The engine sets `blockEvents = true` before calling your driver and only resets it in `onComplete`. If you never call it, the UI freezes permanently.
+
+Use the `createFinishGuard` helper to guarantee this:
+
+```js
+import { createFinishGuard, SAFETY_BUFFER_MS, parseDurationMs } from 'zumly/driver-helpers'
+
+function runTransition(spec, onComplete) {
+  const durationMs = parseDurationMs(spec.duration)
+
+  const { finish } = createFinishGuard(() => {
+    // cleanup work here...
+    onComplete()
+  }, durationMs + SAFETY_BUFFER_MS)
+
+  // Your animation...
+  myAnimation.onfinish = finish
+  // If the animation fails/gets cancelled, the safety timer calls finish() anyway.
+}
+```
+
+*(In this repo, you can import from `../src/drivers/driver-helpers.js` from your own source files.)*
+
+### 2. Apply final DOM state after animation
+
+When the animation ends, the DOM must reflect the final state — the engine does NOT do this for you. Use the shared helpers:
+
+```js
+import {
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  showViews
+} from 'zumly/driver-helpers'
+
+// Before animating — make views visible:
+showViews(spec.currentView, spec.previousView, spec.lastView)
+
+// After zoom-in animation completes:
+applyZoomInEndState(currentView, currentStage)
+applyZoomInEndState(previousView, currentStage)
+if (lastView) applyZoomInEndState(lastView, currentStage)
+
+// After zoom-out animation completes:
+removeViewFromCanvas(currentView, canvas)
+applyZoomOutPreviousState(previousView, currentStage.views[1].backwardState)
+if (lastView) applyZoomOutLastState(lastView, currentStage.views[2].backwardState)
+```
+
+### 3. Handle all three types
+
+Your driver receives `spec.type` which is one of:
+- `'zoomIn'` — drill deeper
+- `'zoomOut'` — go back
+- `'lateral'` — same-level swap
+
+For lateral, the built-in **`waapi`** driver runs a **slide animation**. If you author a minimal custom driver and want **no** lateral motion, call the instant helper:
+
+```js
+import { runLateralInstant } from 'zumly/driver-helpers'
+
+if (spec.type === 'lateral') {
+  runLateralInstant(spec, onComplete)
+  return
+}
+```
+
+---
+
+## Available helpers
+
+Import from `zumly/driver-helpers` (published) or `src/drivers/driver-helpers.js` (monorepo):
+
+| Helper | Purpose |
+|--------|---------|
+| `parseDurationMs(duration)` | Parse `'1s'`/`'500ms'`/number → ms |
+| `parseDurationSec(duration)` | Same but returns seconds |
+| `applyZoomInEndState(el, stage)` | Apply final classes + transforms after zoom-in |
+| `applyZoomOutPreviousState(el, state)` | Final state for previous view after zoom-out |
+| `applyZoomOutLastState(el, state)` | Final state for last view after zoom-out |
+| `removeViewFromCanvas(el, canvas)` | Safe removal (handles wrapped elements) |
+| `showViews(...elements)` | Remove `hide` class + set `contentVisibility: auto` |
+| `runLateralInstant(spec, onComplete)` | Instant lateral transition (no animation) |
+| `createFinishGuard(cleanup, timeoutMs)` | Once-only finish + safety timeout |
+| `SAFETY_BUFFER_MS` | Default safety buffer (150ms) |
+
+### Matrix interpolation toolkit
+
+For drivers that need to interpolate through computed CSS matrices (e.g. when transform-origin varies between states):
+
+| Helper | Purpose |
+|--------|---------|
+| `readComputedMatrix(el, origin, transform)` | Read browser-computed matrix (⚠️ forces reflow) |
+| `interpolateMatrix(from, to, t)` | Lerp between two matrix objects |
+| `matrixToString(m)` | `{ a,b,c,d,e,f }` → `"matrix(...)"` |
+| `parseMatrixString(str)` | `"matrix(...)"` → `{ a,b,c,d,e,f }` |
+| `identityMatrix()` | Returns `{ a:1, b:0, c:0, d:1, e:0, f:0 }` |
+| `lerp(a, b, t)` | Linear interpolation |
+
+---
+
+## Example: minimal custom driver
+
+A complete, minimal driver that does a simple opacity crossfade instead of zoom:
+
+```js
+import {
+  parseDurationMs,
+  showViews,
+  applyZoomInEndState,
+  applyZoomOutPreviousState,
+  applyZoomOutLastState,
+  removeViewFromCanvas,
+  runLateralInstant,
+  createFinishGuard,
+  SAFETY_BUFFER_MS,
+} from 'zumly/driver-helpers'
+
+export function runTransition(spec, onComplete) {
+  const { type, currentView, previousView, lastView, currentStage, duration, canvas } = spec
+
+  if (type === 'lateral') {
+    runLateralInstant(spec, onComplete)
+    return
+  }
+
+  const ms = parseDurationMs(duration)
+  showViews(currentView, previousView, lastView)
+
+  if (type === 'zoomIn') {
+    // Simple crossfade: incoming fades in, outgoing fades out
+    currentView.style.opacity = '0'
+    currentView.style.transition = `opacity ${ms}ms ease`
+    previousView.style.transition = `opacity ${ms}ms ease`
+
+    requestAnimationFrame(() => {
+      currentView.style.opacity = '1'
+      previousView.style.opacity = '0.3'
+    })
+
+    const { finish } = createFinishGuard(() => {
+      currentView.style.transition = ''
+      previousView.style.transition = ''
+      previousView.style.opacity = ''
+      applyZoomInEndState(currentView, currentStage)
+      applyZoomInEndState(previousView, currentStage)
+      if (lastView) applyZoomInEndState(lastView, currentStage)
+      onComplete()
+    }, ms + SAFETY_BUFFER_MS)
+
+    currentView.addEventListener('transitionend', finish, { once: true })
+    return
+  }
+
+  if (type === 'zoomOut') {
+    currentView.style.transition = `opacity ${ms}ms ease`
+    requestAnimationFrame(() => {
+      currentView.style.opacity = '0'
+      previousView.style.opacity = '1'
+    })
+
+    const { finish } = createFinishGuard(() => {
+      currentView.style.transition = ''
+      removeViewFromCanvas(currentView, canvas)
+      applyZoomOutPreviousState(previousView, currentStage.views[1].backwardState)
+      if (lastView) applyZoomOutLastState(lastView, currentStage.views[2].backwardState)
+      onComplete()
+    }, ms + SAFETY_BUFFER_MS)
+
+    currentView.addEventListener('transitionend', finish, { once: true })
+    return
+  }
+
+  onComplete()
+}
+```
+
+---
+
+## Testing your driver
+
+Use `driver: 'none'` as a reference — it applies final state instantly and calls `onComplete()` synchronously. Your driver should produce the same final DOM state, just animated.
+
+Key things to test:
+1. After zoom-in: `.is-current-view` exists with correct `dataset.viewName`
+2. After zoom-out: previous view is now `.is-current-view`, old current is removed from DOM
+3. `onComplete()` is always called, even if elements are removed mid-animation
+4. `blockEvents` is reset (the engine handles this in `onComplete`, but verify your driver calls it)
+
+```js
+const app = new Zumly({
+  mount: '.canvas',
+  initialView: 'home',
+  views: { home, detail },
+  transitions: { driver: myDriver, duration: '100ms' },
+})
+await app.init()
+await app.zoomTo('detail')
+expect(app.getCurrentViewName()).toBe('detail')
+app.back()
+expect(app.getCurrentViewName()).toBe('home')
+```
+
+---
+
+## Registering with `getDriver()`
+
+Built-in drivers are resolved by name (`'css'`, `'waapi'`, `'none'`, etc.) in [`src/drivers/index.js`](../src/drivers/index.js). Community drivers are passed as functions — no registration needed:
+
+```js
+// Direct function — works out of the box:
+transitions: { driver: myDriver.runTransition }
+
+// If you want to publish as a package:
+// npm: zumly-driver-lottie
+import { runTransition } from 'zumly-driver-lottie'
+new Zumly({ transitions: { driver: runTransition } })
+```
+
+---
+
+## See also
+
+- [README.md](../README.md) — installation and transition driver table
+- [roadMap.md](roadMap.md) — architecture notes and animation driver history

package/package.json

@@ -1,61 +1,72 @@
 {
   "name": "zumly",
-  "version": "0.9.11",
+  "version": "0.92.0",
   "description": "Javascript library for building zooming user interfaces",
-  "author": {
-    "name": "Juan Martín Muda",
-    "email": "zumly.js@gmail.com"
-  },
+  "type": "module",
+  "author": "Juan Martin Muda - Zumerlab",
   "license": "MIT",
-  "homepage": "https://zumly.org",
+  "homepage": "https://zumerlab.github.io/zumly-docs",
   "repository": {
     "type": "git",
-    "url": "https://github.com/zumly/zumly.git"
+    "url": "https://github.com/zumerlab/zumly.git"
   },
   "bugs": {
-    "url": "https://github.com/zumly/zumly/issues"
+    "url": "https://github.com/zumerlab/zumly/issues"
   },
   "keywords": [
     "zumly",
     "zooming",
     "javascript",
     "UI",
-    "library"
+    "library",
+    "ZUI"
   ],
-  "main": "dist/zumly.min.mjs",
+  "main": "dist/zumly.js",
   "module": "dist/zumly.mjs",
-  "browser": "dist/zumly.umd.js",
-  "scripts": {
-    "art": "ascii-art image src/assets/zumly_art.svg",
-    "watch": "rollup --config rollup.config.dev.js -w",
-    "dev": "npm-run-all -s --silent art watch",
-    "build": "rollup --config rollup.config.prod.js",
-    "lint": "standard --fix 'src/*.js' | snazzy",
-    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --verbose --silent"
-  },
-  "devDependencies": {
-    "@rollup/plugin-commonjs": "^14.0.0",
-    "@rollup/plugin-node-resolve": "^8.4.0",
-    "ascii-art": "^2.5.0",
-    "jest": "^26.1.0",
-    "jest-environment-jsdom-sixteen": "^1.0.3",
-    "npm-run-all": "^4.1.5",
-    "postcss": "^7.0.27",
-    "postcss-banner": "^3.0.2",
-    "rollup": "^2.2.1",
-    "rollup-plugin-copy": "^3.3.0",
-    "rollup-plugin-live-server": "^1.0.3",
-    "rollup-plugin-postcss": "^3.1.2",
-    "rollup-plugin-terser": "^6.1.0",
-    "snazzy": "^8.0.0",
-    "standard": "^14.3.3"
+  "types": "types/zumly.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/zumly.d.ts",
+      "import": "./dist/zumly.mjs",
+      "require": "./dist/zumly.js",
+      "default": "./dist/zumly.mjs"
+    },
+    "./style.css": "./dist/zumly.css",
+    "./css": "./dist/zumly.css",
+    "./drivers": {
+      "import": "./src/drivers/index.js"
+    },
+    "./driver-helpers": {
+      "import": "./src/drivers/driver-helpers.js"
+    }
   },
-  "type": "module",
-  "jest": {
-    "transform": {},
-    "testEnvironment": "jest-environment-jsdom-sixteen"
+  "sideEffects": [
+    "dist/zumly.css",
+    "dist/zumly.min.css"
+  ],
+  "scripts": {
+    "compile": "node esbuild.config.mjs",
+    "build": "npm run compile && npm pack",
+    "dev": "npm run compile && npx serve . -p 9090 -c ./serve.json",
+    "test": "npx vitest run --browser.headless --reporter=verbose",
+    "test:unit": "npx vitest run __tests__/utils.test.js --reporter=verbose",
+    "test:coverage": "npx vitest run --browser.headless --coverage",
+    "test:install-browsers": "npx playwright install chromium",
+    "bump": "npx @zumerbox/bump && npx @zumerbox/changelog",
+    "prebuild": "git add CHANGELOG.md && git commit -m \"Bumped version\" && git push --follow-tags"
   },
   "files": [
-    "dist"
-  ]
+    "dist",
+    "src/drivers/driver-helpers.js",
+    "src/drivers/index.js",
+    "docs/DRIVER_API.md",
+    "README.md"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.24.0",
+    "@vitest/browser": "^3.1.2",
+    "@vitest/coverage-v8": "^3.1.2",
+    "playwright": "^1.52.0",
+    "vitest": "^3.1.2"
+  }
 }