zumly 0.9.11 → 0.92.0

package/README.md

@@ -1,26 +1,51 @@
 <p align="center">
-  <a href="https://zumly.org">
-    <img src="https://raw.githubusercontent.com/zumly/website/gh-pages/images/logo-zumly.png" width="200">
+  <a href="https://github.com/zumerlab/zumly">
+    <!-- Built from docs/zumly-logo.png in this repo; raw URL so the image works on npm too -->
+    <img src="https://raw.githubusercontent.com/zumerlab/zumly/main/docs/zumly-logo.png" alt="Zumly" width="200">
   </a>
 </p>
 
+<h1 align="center">Z over XY</h1>
+
+<p align="center"><strong>Focus-driven navigation.</strong></p>
+<p align="center"><strong>Zoom into what matters.</strong></p>
+
 <p align="center">
-  Zumly is a Javascript library for building zooming user interfaces. Create zooming experiences using web standards.
+  <a href="https://www.npmjs.com/package/zumly"><img src="https://img.shields.io/npm/v/zumly.svg" alt="npm version"></a>
 </p>
 
 <p align="center">
-  <a href="https://www.npmjs.com/package/zumly"><img src="https://img.shields.io/npm/v/zumly.svg"></a>
+  <strong>Zumly</strong> is a JavaScript library for <strong>hierarchical zoom navigation</strong>: you move in <strong>Z</strong> (depth) through discrete views laid out in the <strong>XY</strong> plane, with spatial transitions instead of flat screen swaps. It is inspired by <a href="https://en.wikipedia.org/wiki/Zooming_user_interface">zoomable user interfaces (ZUI)</a> but targets <strong>structured, trigger-driven</strong> zoom—not infinite pan/zoom canvases.
 </p>
 
+## Status
+
+Zumly is under active development. The core stack is stable: depth and lateral navigation, pluggable transition drivers (CSS, WAAPI, none, Anime.js, GSAP, Motion, custom), unified nav UI (depth + lateral, eight positions), view resolver and prefetch cache, optional **plugin** API (<code>.use()</code>), and the **hash router** plugin. View sources include HTML strings, URLs, async functions, objects with <code>render()</code>, DOM nodes, and web component tags.
+
+Zoom-out geometry uses batched DOM reads plus pure math where possible to cut layout thrash before animations (see [Geometry optimization](docs/geometry-optimization.md)).
+
+**Docs:** [Roadmap & topics](docs/roadMap.md) · [Transition drivers](docs/DRIVER_API.md) · [Geometry notes](docs/geometry-optimization.md)
+
 ## Overview
 
-Zumly is a frontend library for creating zoomable user interfaces ([ZUI](https://en.wikipedia.org/wiki/Zooming_user_interface)). Instead of hyperlinks and windows, Zumly uses zooming as a metaphor for browsing through information. This way it offers an infinite virtual canvas in which elements can be zoomed themselves to reveal further details. 
+Unlike free-pan ZUIs, Zumly focuses on **discrete, hierarchical navigation**: users zoom into a focused element (<code>.zoom-me</code>) to open the next view, so **attention** (focus) and **depth** (Z) stay aligned with **layout** (XY).
+
+The engine is **UI-agnostic**—you supply markup and CSS. Transforms and timing are handled for you; design systems and frameworks integrate by resolving each view to a DOM subtree (see **View sources** and **Framework integration** below).
 
-To be more flexible Zumly is primarily focused on zooming transitions without caring about visual design. Most CSS frameworks or custom designs work with Zumly.
+## What Zumly is
+
+Zumly is **not** a freeform zooming canvas or map-like navigation system. It is a **discrete, hierarchical zoom interface**: screens are **views** at different depths, connected by **triggers**, with continuous motion between them.
+
+It fits especially well when:
+
+* you want **focus-driven** flow (zoom into what matters)
+* **spatial context** between parent and child should persist
+* you are building menus, stories, dashboards, or exploratory UIs without a classic router-only metaphor
 
 ## Installation
 
 ### NPM
+
 ```sh
 npm install zumly
 
@@ -29,235 +54,402 @@ npm install zumly
 yarn add zumly
 ```
 
-### Content delivery networks (CDN)
-Include https://unpkg.com/zumly in your project in a `<script>` tag. 
+### CDN
 
+Include Zumly in your project via a `<script>` tag from [unpkg.com/zumly](https://unpkg.com/zumly).
 
 ### Direct download
 
-Download Zumly files from [unpkg.com](https://unpkg.com/zumly/). Files are in `dist` folder.
-
+Download the built files from [unpkg.com/zumly](https://unpkg.com/zumly/) (see the `dist` folder).
 
 ## Setup
 
+### Browser bundle (global)
 
-### ES6 modules
+1. Add the CSS in your `<head>`:
 
-1. Add CSS inside `<head>` tag: 
 ```html
-
 <link rel="stylesheet" href="zumly/dist/zumly.css">
+<!-- or https://unpkg.com/zumly/dist/zumly.css -->
+```
 
-<!-- Or "https://unpkg.com/zumly@0.9.11/dist/zumly.css" -->
+2. Load the JS bundle (it exposes `window.Zumly`):
 
+```html
+<script src="zumly/dist/zumly.js"></script>
+<!-- or https://unpkg.com/zumly/dist/zumly.js -->
 ```
 
-2. Add Zumly as ES6 module: 
-```html
-<script type="module">
-  import Zumly from "zumly/dist/zumly.mjs"
+## Hello World
+
+1. Add a container with the class `zumly-canvas`:
 
-  // Or "https://unpkg.com/zumly@0.9.11/dist/zumly.mjs"
-</script>
+```html
+<div class="example zumly-canvas"></div>
 ```
 
-### UMD modules
+2. Create your views and start Zumly:
 
-1. Add Zumly CSS Styles inside `<head>` tag: 
-```html
+```js
+const hello = `
+<div class="z-view">
+  H E L L O <br>
+  W <span class="zoom-me" data-to="world">O</span> R L D!
+</div>
+`;
 
-<link rel="stylesheet" href="zumly/dist/zumly.css">
+const world = `
+<div class="z-view">
+  <img src="https://raw.githubusercontent.com/zumly/website/gh-pages/images/world.png" alt="World">
+</div>
+`;
 
-<!-- Or "https://unpkg.com/zumly@0.9.11/dist/zumly.css" -->
+const app = new Zumly({
+  mount: '.example',
+  initialView: 'hello',
+  views: { hello, world },
+});
 
+await app.init();
 ```
 
-2. Add Zumly as UMD module: 
-```html
+- Live example: [CodePen](https://codepen.io/zircle/pen/yyaXvRN)
+
+### Options
 
-<script src="zumly/dist/zumly.umd.js"></script>
+**Zumly constructor:**
 
-// Or "https://unpkg.com/zumly"
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `mount` | string | Yes | CSS selector for the canvas element (must have class `zumly-canvas`). |
+| `initialView` | string | Yes | Name of the first view to show. |
+| `views` | object | Yes | Map of view names to view sources (see View sources below). |
+| `preload` | string[] | No | View names to resolve and cache when the app initializes. |
+| `transitions` | object | No | Duration, ease, cover, driver, effects, stagger, hideTrigger for zoom transitions. |
+| `deferred` | boolean | No | Defer content rendering until after animation completes (default: `false`). |
+| `debug` | boolean | No | Enable debug messages (default: `false`). |
+| `lateralNav` | boolean \| object | No | Lateral navigation UI: `{ mode, arrows, dots, keepAlive }`. |
+| `depthNav` | boolean \| object | No | Depth navigation UI: `{ button, indicator }`. |
+| `navPosition` | string | No | Nav bar position preset (default: `'bottom-center'`). |
+| `inputs` | boolean \| object | No | Input methods: `{ click, keyboard, wheel, touch }`. |
+| `componentContext` | object | No | Context passed to component-style views. |
 
+**Transitions (optional):**
+
+```js
+transitions: {
+  driver: 'css',       // 'css' | 'waapi' | 'anime' | 'gsap' | 'motion' | 'none' or custom function(spec, onComplete)
+  cover: 'width',      // or 'height' — how the previous view scales to cover the trigger
+  duration: '1s',
+  ease: 'ease-in-out',
+  effects: ['blur(3px) brightness(0.7)', 'blur(8px) saturate(0)'],  // CSS filters for [previous, last] background views
+  stagger: 0,          // delay (ms) between layers during transition
+  hideTrigger: false,  // false | true (visibility:hidden) | 'fade' (opacity crossfade)
+  // threshold: { enabled: true, duration: 300, commitAt: 0.5 }  // parsed but not wired in the engine yet
+}
 ```
 
+`transitions.parallax` is accepted for compatibility but **not applied** (reserved; intensity is fixed to `0` in the engine).
 
-## Hello World
+**Transition drivers:** Zoom animations are handled by a pluggable driver (`transitions.driver`). You can swap implementations without changing app logic. To author your own, see [docs/DRIVER_API.md](docs/DRIVER_API.md) and the `zumly/driver-helpers` export.
 
-1. Create a container for your Zumly app with `.zumly-canvas`: 
+| Driver | Description |
+|--------|-------------|
+| `'css'` (default) | CSS keyframes and `animationend`; uses `zumly.css` variables. |
+| `'waapi'` | Web Animations API (`element.animate()`). No extra dependency. |
+| `'none'` | No animation; applies final state immediately. Useful for tests or instant UX. |
+| `'anime'` | [Anime.js](https://animejs.com/) — requires global `anime` (load from CDN before use). |
+| `'gsap'` | [GSAP](https://greensock.com/gsap/) — requires global `gsap` (load from CDN before use). |
+| `'motion'` | [Motion](https://motion.dev/) — requires global `Motion` (load from CDN before use). |
+| `function(spec, onComplete)` | Custom driver. Receives `{ type, currentView, previousView, lastView, currentStage, duration, ease }` and must call `onComplete()` when done. |
 
-```html
+Example with instant transitions (e.g. for tests):
 
-<div class="example zumly-canvas"></div>
+```js
+const app = new Zumly({
+  mount: '.canvas',
+  initialView: 'home',
+  views: { home, detail },
+  transitions: { driver: 'none', duration: '0s' },
+});
+```
+
+**Lateral navigation:**
 
+```js
+lateralNav: true                            // mode: 'auto' (default)
+lateralNav: false                           // disabled
+lateralNav: { mode: 'always' }              // always show when siblings exist
+lateralNav: { mode: 'auto', dots: false }   // auto mode, no dots
 ```
 
-2. Inside `script` tag write this code:
+| Mode | Description |
+|------|-------------|
+| `'auto'` (default) | Shows lateral nav only when the current view doesn't cover the full canvas — preserving spatial context. |
+| `'always'` | Always shows lateral nav when siblings exist, regardless of coverage. |
+
+In `'auto'` mode, when a view covers 100% of the canvas the user perceives a new independent space, so the lateral nav is suppressed to avoid a floating control with no visual context.
+
+**Navigation position (`navPosition`):**
 
 ```js
-// Some views
-const hello = `
-<div class="z-view">
-H E L L O <br>
-W <span class="zoom-me" data-to="world">O</span> R L D!
-</div>
-`;
+navPosition: 'bottom-center'   // default
+```
 
-const world = `
+| Preset | Position | Layout |
+|--------|----------|--------|
+| `'bottom-center'` | Bottom center | Horizontal |
+| `'bottom-left'` | Bottom left | Horizontal |
+| `'bottom-right'` | Bottom right | Horizontal |
+| `'top-center'` | Top center | Horizontal |
+| `'top-left'` | Top left | Horizontal |
+| `'top-right'` | Top right | Horizontal |
+| `'middle-left'` | Left center | Vertical |
+| `'middle-right'` | Right center | Vertical |
+
+The `'middle-left'` and `'middle-right'` presets render the nav bar vertically with rotated arrows.
+
+**Zoomable elements:**
+
+- Give the view root the class `z-view`.
+- Add class `zoom-me` and `data-to="viewName"` to the element that triggers zoom-in.
+- Per-trigger overrides via `data-*` attributes:
+
+| Attribute | Description |
+|-----------|-------------|
+| `data-to` | **Required.** Target view name. |
+| `data-with-duration` | Override transition duration (e.g. `"2s"`). |
+| `data-with-ease` | Override easing function. |
+| `data-with-cover` | Override cover dimension (`"width"` or `"height"`). |
+| `data-with-stagger` | Override stagger delay in ms (e.g. `"100"`). |
+| `data-with-effects` | Override effects (pipe-separated: `"blur(5px)\|blur(10px)"`). |
+| `data-hide-trigger` | Override hideTrigger (`"fade"` or presence = hide). |
+| `data-deferred` | Override deferred rendering (presence = true). |
+| `data-*` | Any other data attribute becomes a prop in `ViewContext.props`. |
+
+```html
 <div class="z-view">
-<img src="https://raw.githubusercontent.com/zumly/website/gh-pages/images/world.png"/>
+  <div class="zoom-me" data-to="detail"
+       data-with-duration="2s"
+       data-with-ease="ease-in"
+       data-with-cover="height"
+       data-with-stagger="100"
+       data-id="42">
+    Zoom in
+  </div>
 </div>
-`;
+```
 
-// Zumly instance
-const app = new Zumly({
-  mount: '.example',
-  initialView: 'hello',
-  views: {
-    hello,
-    world
-  }
-})
+### View sources
 
-app.init()
+Each entry in `views` is a **view source**. The resolver detects the type and resolves to a DOM node. Hyphenated view names (e.g. `'my-dashboard'`) are resolved as keys in `views` first; only raw template strings with a hyphen are treated as web components.
 
-```
+| Type | Example | Cached? |
+|------|---------|---------|
+| **HTML string** | `'<div class="z-view">…</div>'` | Yes (indefinitely) |
+| **URL** | `'/views/detail.html'`, `https://…` | Yes (5 min TTL) |
+| **Async function** | `(ctx) => fetch(...).then(r => r.text())` or return `HTMLElement` | No |
+| **Object with `render()`** | `{ render(ctx) { return '<div>…</div>' }, mounted?() }` | No |
+| **Web component** | `'my-view'` (string with hyphen, not a key in `views`) | No |
 
-- See this example live at [codePen](https://codepen.io/zumly/pen/gOPQovd)
+**View pipeline:** Resolve → normalize `.z-view` → insert into canvas → call `mounted()` (if present). Static/URL views are cloned from cache on each `get()` so consumers cannot mutate the stored node.
 
-### Zumly options
+### Framework integration
 
-1. The Zumly instance:
+Zumly is framework-agnostic. Since views resolve to DOM elements, any framework that can mount into a container works out of the box. Use **function views** or **object views** to bridge your framework:
+
+**React**
+
+```jsx
+import { createRoot } from 'react-dom/client'
+import Dashboard from './Dashboard'
 
-```js
 const app = new Zumly({
-  // Mount DOM Element. String. Required
-  mount: '.className',
-  // First rendered view name. String. Required
-  initialView: 'viewName',
-  // Store all views. Object. Required
+  mount: '.canvas',
+  initialView: 'home',
   views: {
-    view1,
-    view2,
-    . . .
-  }, 
-  // Customize transitions. Object. Optional
-  transitions: {
-    // Effects for background views. Array. ['blur', 'sepia', 'saturate']
-    effects: ['sepia'],
-    // How new injected view is adapted. String. Default 'width'
-    cover: 'height',
-    // Transition duration. String. Default '1s'
-    duration: '1300ms' ,
-    // Transition ease. String. Default 'ease-in-out'
-    ease: 'cubic-bezier(0.25,0.1,0.25,1)'
-  },
-  // Activate debug notifications. Boolean. Default false
-  debug: true
+    home: '<div class="z-view"><div class="zoom-me" data-to="dashboard" data-id="42">Open</div></div>',
+    dashboard: ({ target, props }) => {
+      const root = createRoot(target)
+      root.render(<Dashboard id={props.id} />)
+    }
+  }
 })
-// Initialize instance
-app.init()
 ```
 
-2. Options for each zoomable element:
+**Vue**
 
-- Add `z-view` class in you view container:
+```js
+import { createApp } from 'vue'
+import Dashboard from './Dashboard.vue'
 
-```html
+views: {
+  dashboard: ({ target, props }) => {
+    createApp(Dashboard, { id: props.id }).mount(target)
+  }
+}
+```
+
+**Svelte**
 
-<div class="z-view"></div>
+```js
+import Dashboard from './Dashboard.svelte'
 
+views: {
+  dashboard: ({ target, props }) => {
+    new Dashboard({ target, props: { id: props.id } })
+  }
+}
 ```
 
-- Add `zoom-me` class to an HTML element to make it zoomable and add `data-to` attribute with the name of the target view
+**Angular**
 
-```html
+```ts
+views: {
+  dashboard: ({ target, props }) => {
+    const compRef = viewContainerRef.createComponent(DashboardComponent)
+    compRef.instance.id = props.id
+    target.appendChild(compRef.location.nativeElement)
+  }
+}
+```
+
+**Key points:**
+
+- The `target` parameter is a fresh `<div>` created by Zumly — mount your component there.
+- `props` contains data attributes from the trigger element (`data-id="42"` → `props.id`).
+- `componentContext` (constructor option) is passed as `context` to all function/object views — use it for shared state (router, store, API client).
+- Function views are **never cached** — they resolve fresh each time, so framework components get proper lifecycle management.
+- Use `mounted()` (object views) for post-insertion setup — it runs after the node is in the DOM.
+- Zumly handles wrapped elements (e.g. Svelte's extra parent div) in its cleanup logic.
 
-<div class="zoom-me" data-to="anotherView">Zoom me!</div>
+### Preload and prefetch
 
+- **Eager preload:** `preload: ['viewA', 'viewB']` — those views are resolved and cached during `init()`.
+- **Hover prefetch:** `mouseover` on a `.zoom-me[data-to]` trigger prefetches its target in the background.
+- **Focus prefetch:** `focusin` on a `.zoom-me[data-to]` also prefetches (for keyboard/accessibility).
+- **Scan prefetch:** When a view becomes current, all `.zoom-me[data-to]` targets inside it are prefetched in the background. This works on touch devices where hover is unavailable.
+
+### Plugins
+
+Zumly has a lightweight plugin system. Register plugins with `.use()` before or after `init()`:
+
+```js
+app.use(plugin, options)
 ```
 
-- Each zooming transition can be customized by adding some `data-` attributes:
+A plugin is an object with `install(instance, options)` or a plain function `(instance, options) => void`.
 
-```html
+#### Router plugin
 
-<div class="zoom-me" data-to="anotherView" data-with-duration="2s" data-with-ease="ease-in">
-  Zoom me!
-</div>
+Syncs the browser URL hash with Zumly's navigation state. Browser back triggers zoom-out or lateral navigation. Forward is intentionally blocked — in a ZUI, zoom-in requires a trigger element for proper origin and animation context.
 
+```js
+// Script tag
+const app = new Zumly({ ... })
+app.use(Zumly.Router)
+await app.init()
+
+// ES Module (named export from the package entry)
+import { Zumly, ZumlyRouter } from 'zumly'
+const app = new Zumly({ ... })
+app.use(ZumlyRouter)
+await app.init()
 ```
 
-## Development 
+The UMD/IIFE bundle attaches the same plugin as `Zumly.Router`. There is no separate published subpath for the router; import it from `'zumly'` or use `Zumly.Router` on `window` when using a script tag.
 
-### Developer environment requirements
+**Options:**
 
-To run this project, you will need:
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `separator` | string | `'/'` | Character used to join view path segments in the hash. |
+| `prefix` | string | `'/'` | Prefix before the path in the hash. |
 
-- Node.js >= v10.5.0
+**Behavior:**
 
-### Dev mode
+| Action | Hash update | History |
+|--------|-------------|---------|
+| Zoom in | `pushState` | Enables browser back |
+| Lateral | `pushState` | Enables browser back |
+| Zoom out | `replaceState` | No forward entry |
+| Browser back | Triggers `zoomOut()` or lateral `goTo()` | — |
+| Browser forward | Blocked (`history.back()`) | — |
 
-When developing you can run:
+**Example URL:** `#/home/showcases/mercedes`
 
-```sh
-npm run dev
+### Limitations and non-goals
 
-# or
+- **No deep-linking:** The router plugin syncs hash on navigation and supports browser back, but does not support forward or deep-linking (entering a multi-level URL directly). In a ZUI, zoom-in requires a trigger element for proper spatial context.
+- **Resize handling:** Cheap correction when canvas resizes — translate and origin scaled by ratio; scale preserved. Correction is deferred if a transition is running.
+- **Remote views:** URL-backed views use `innerHTML`; sanitize external content to avoid XSS.
 
-yarn dev
-```
+## Development
+
+### Requirements
 
-This will regenerate the build files each time a source file is changed and serve on http://localhost:9090
+- Node.js >= 18 (or 16+ with ES module support)
 
-### Running tests
+### Commands
 
 ```sh
+# Build the library
+npm run compile
+
+# Build and serve the demo at http://localhost:9090
+npm run dev
+
+# Run tests (Vitest + Playwright). Install browsers first:
+npm run test:install-browsers
 npm run test
 
-# or
+# Run tests with coverage
+npm run test:coverage
 
-yarn test
+# Build and pack for publish
+npm run build
 ```
 
+Tests use [Vitest](https://vitest.dev/) with the browser provider ([Playwright](https://playwright.dev/)), same setup as [SnapDOM](https://github.com/zumerlab/snapdom). Run `npm run test:install-browsers` once (or after upgrading Playwright) to install Chromium.
+
 ### Building
 
 ```sh
-npm run build
-
-# or
-
-yarn build
+npm run compile
 ```
 
-## Changelog
+Output is in the `dist/` folder.
 
-Please see [CHANGELOG](CHANGELOG.md) for more information what has changed recently.
+## Changelog
 
-### Status: beta
+See [CHANGELOG.md](CHANGELOG.md) for version history.
 
-Zumly is on early stages of development.
+## Roadmap
 
-### Roadmap
+**Done:**
+- Depth and lateral navigation (`zoomIn`, `zoomOut`, `goTo`, `back`, `zoomTo`)
+- Lateral nav UI (`lateralNav`: `mode` auto/always, arrows, dots, `keepAlive`)
+- Depth nav UI (`depthNav`) and `navPosition` presets
+- Inputs toggles (`inputs`: wheel, keyboard, click, touch)
+- Plugin system (`use()`), router plugin (hash sync, back, forward blocked)
+- Resize correction (translate/origin scaling; deferred while transitioning)
+- Pluggable drivers (CSS, WAAPI, none, Anime.js, GSAP, Motion, custom)
+- Batched zoom-out reads + math helpers to reduce reflow (see [geometry-optimization.md](docs/geometry-optimization.md))
 
-- Allow different template engines. Currently Zumly only accepts string literal templates.
-- Add lateral navigation for same zoom level elements.
-- Add a navegation widget.
-- Add programmatic navigation.
-- Add preseted navigation.
-- Add router. [#3](https://github.com/zumly/zumly/issues/3)
-- Allow recalculate zoom position on resize events.
+**Planned:**
+- Router deep-linking (open a multi-level hash cold)
+- Accessibility (focus moves, broader ARIA)
 
+Details and more topics: [docs/roadMap.md](docs/roadMap.md). Driver contract and helpers: [docs/DRIVER_API.md](docs/DRIVER_API.md).
 
-## Stay in touch
+## Community
 
 - [Telegram group](https://t.me/ZumlyCommunity)
 
-## Original idea
+## Origin
 
-Zumly is a new approach based on another library I made, [Zircle UI](https://github.com/zircleUI/zircleUI)
+Zumly is a reimagined, framework-agnostic zoom engine inspired by [Zircle UI](https://github.com/zircleUI/zircleUI). Part of the [Zumerlab](https://github.com/zumerlab) ecosystem — use it with [Orbit](https://github.com/zumerlab/orbit) for radial layouts and [SnapDOM](https://github.com/zumerlab/snapdom) for lightweight DOM diffing.
 
 ## License
 
-The MIT License (MIT). Please see [License File](LICENSE) for more information.
-
-
+MIT. See [LICENSE](LICENSE).