@underlying/flip 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) underlyi.ng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,55 @@
+<div align="center">
+
+# @underlying/flip
+
+**Layout and shared-element transitions, physics-first.**
+
+</div>
+
+Animate an element from its old place to its new one - both position and size - by measuring its box before and after a DOM change and springing the difference away. The play is a real spring, so it is interruptible: change the layout again mid-flight and each element retargets from its live position and velocity, bending into the new layout instead of restarting. Built on [`@underlying/core`](https://github.com/underlyingjs/underlying/tree/main/packages/core); about 0.9 kB gzip on top of it.
+
+```bash
+npm install @underlying/core @underlying/flip
+```
+
+## Layout: `flip(targets, mutate)`
+
+Wrap any DOM change. `flip` measures First, runs your mutation, measures Last, applies the inverse transform so nothing jumps, then springs to identity.
+
+```ts
+import { flip } from '@underlying/flip'
+
+// reorder, filter, resize - the tiles spring to their new places
+flip(tiles, () => grid.append(...reordered), { stiffness: 320, damping: 26 })
+
+// position AND size: a grid <-> list toggle resizes every tile smoothly
+flip(tiles, () => grid.classList.toggle('list'))
+```
+
+By default it inverts position and size (translate + scale, pinned to the top-left). Pass `{ scale: false }` for position only.
+
+## Shared element: `snapshot()` + `play()`
+
+When the old and new elements are different DOM nodes (a thumbnail expanding into a detail view, a route change), capture the old set, change the DOM, then play the new set from the captured boxes - matched by `data-flip-id`.
+
+```ts
+import { snapshot, play } from '@underlying/flip'
+
+const state = snapshot(thumbnails)   // data-flip-id on each
+// ... navigate / re-render: the detail view mounts ...
+play(state, { targets: detailEls, stiffness: 260, damping: 24 })
+```
+
+A target with no matching key in the snapshot is left alone.
+
+## Interruption
+
+Every `flip()` / `play()` retargets from the live spring, velocity conserved - press the button again while the tiles are still moving and the motion redirects, never restarts. That is the whole point.
+
+## Options
+
+`FlipOptions` extends the core `SpringOptions` (`stiffness`, `damping`, `mass`, ...) plus `scale?: boolean` and `scheduler?`.
+
+## License
+
+MIT (c) underlyi.ng

package/dist/flip.d.ts

@@ -0,0 +1,46 @@
+import { type Scheduler, type SpringOptions } from '@underlying/core';
+export type FlipTargets = HTMLElement | Iterable<HTMLElement>;
+export interface FlipOptions extends SpringOptions {
+    scheduler?: Scheduler;
+    /** Invert and animate size changes too (scale), not only position. Default true. */
+    scale?: boolean;
+}
+export interface FlipPlayOptions extends FlipOptions {
+    /** The elements to animate from the snapshot boxes, matched by `data-flip-id`. */
+    targets: FlipTargets;
+}
+interface Box {
+    readonly left: number;
+    readonly top: number;
+    readonly width: number;
+    readonly height: number;
+}
+/** A captured set of element boxes, keyed by `data-flip-id` (or the element itself). */
+export interface FlipSnapshot {
+    readonly boxes: ReadonlyMap<string | HTMLElement, Box>;
+}
+/**
+ * Physics-first FLIP. Measures each element's box (First), runs `mutate` to
+ * change the DOM, measures again (Last), applies the inverse transform - both
+ * position AND size - so nothing visibly jumps, then springs every element to
+ * its new place. The play is a spring, not a baked tween: call flip() again
+ * mid-flight and each element retargets from its live position and velocity, so
+ * the motion bends into the new layout instead of restarting. That
+ * interruptibility is the whole point.
+ */
+export declare function flip(targets: FlipTargets, mutate: () => void, options?: FlipOptions): void;
+/**
+ * Capture each target's box, keyed by its `data-flip-id` (or the element
+ * itself). Pair with `play()` for shared-element / route transitions, where the
+ * old elements and the new ones are different DOM nodes: snapshot the old set,
+ * change the DOM, then play the new set from the captured boxes.
+ */
+export declare function snapshot(targets: FlipTargets): FlipSnapshot;
+/**
+ * Animate each target from its matching box in the snapshot to its current
+ * place - matched by `data-flip-id`. A target with no match in the snapshot is
+ * left alone. Interruptible like `flip()`.
+ */
+export declare function play(snap: FlipSnapshot, options: FlipPlayOptions): void;
+export {};
+//# sourceMappingURL=flip.d.ts.map

package/dist/flip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flip.d.ts","sourceRoot":"","sources":["../src/flip.ts"],"names":[],"mappings":"AAAA,OAAO,EAA+B,KAAK,SAAS,EAAE,KAAK,aAAa,EAAE,MAAM,kBAAkB,CAAA;AAElG,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC,WAAW,CAAC,CAAA;AAE7D,MAAM,WAAW,WAAY,SAAQ,aAAa;IAChD,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,oFAAoF;IACpF,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,eAAgB,SAAQ,WAAW;IAClD,kFAAkF;IAClF,OAAO,EAAE,WAAW,CAAA;CACrB;AAED,UAAU,GAAG;IACX,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB;AAED,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,GAAG,WAAW,EAAE,GAAG,CAAC,CAAA;CACvD;AA6GD;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,OAAO,GAAE,WAAgB,GAAG,IAAI,CAsB9F;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,YAAY,CAI3D;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAQvE"}

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const y=require("@underlying/core"),x={x:0,y:0,sx:0,sy:0},g=new WeakMap,u=s=>s instanceof HTMLElement?[s]:Array.from(s),d=s=>{const t=s.getBoundingClientRect();return{left:t.left,top:t.top,width:t.width,height:t.height}},p=s=>s.dataset.flipId??s,v=(s,t,e,n,c)=>{if(t===0&&e===0&&n===1&&c===1){s.style.transform="";return}const i=n===1&&c===1?"":` scale(${n}, ${c})`;s.style.transform=`translate3d(${t}px, ${e}px, 0)${i}`},b=(s,t)=>{let e=g.get(s);if(e===void 0){const n=t.scheduler!==void 0?{scheduler:t.scheduler}:{},c=y.animatable(0,n),i=y.animatable(0,n),o=y.animatable(1,n),r=y.animatable(1,n),a=()=>v(s,c.get(),i.get(),o.get(),r.get());c.on("change",a),i.on("change",a),o.on("change",a),r.on("change",a),s.style.transformOrigin="0 0",e={x:c,y:i,sx:o,sy:r},g.set(s,e)}return e},m=s=>{const t=g.get(s);if(t===void 0)return x;const e={x:t.x.velocity(),y:t.y.velocity(),sx:t.sx.velocity(),sy:t.sy.velocity()};return t.x.stop(),t.y.stop(),t.sx.stop(),t.sy.stop(),e},w=(s,t,e,n)=>{const c=n.scale!==!1,i=d(s),o=t.left-i.left,r=t.top-i.top,a=c&&i.width>0?t.width/i.width:1,h=c&&i.height>0?t.height/i.height:1;if(o===0&&r===0&&a===1&&h===1){const f=g.get(s);f!==void 0&&(f.x.set(0),f.y.set(0),f.sx.set(1),f.sy.set(1)),s.style.transform="";return}const l=b(s,n);v(s,o,r,a,h),l.x.set(o,{velocity:e.x}),l.y.set(r,{velocity:e.y}),l.sx.set(a,{velocity:e.sx}),l.sy.set(h,{velocity:e.sy}),l.x.spring(0,n),l.y.spring(0,n),l.sx.spring(1,n),l.sy.spring(1,n)};function M(s,t,e={}){const n=u(s),c=new Map,i=new Map;for(const o of n)c.set(o,d(o)),i.set(o,m(o));for(const o of n)o.style.transform="";t();for(const o of n){const r=c.get(o);r!==void 0&&w(o,r,i.get(o)??x,e)}}function O(s){const t=new Map;for(const e of u(s))t.set(p(e),d(e));return{boxes:t}}function S(s,t){for(const e of u(t.targets)){const n=s.boxes.get(p(e));if(n===void 0)continue;const c=m(e);e.style.transform="",w(e,n,c,t)}}exports.flip=M;exports.play=S;exports.snapshot=O;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/flip.ts"],"sourcesContent":["import { animatable, type Animatable, type Scheduler, type SpringOptions } from '@underlying/core'\n\nexport type FlipTargets = HTMLElement | Iterable<HTMLElement>\n\nexport interface FlipOptions extends SpringOptions {\n  scheduler?: Scheduler\n  /** Invert and animate size changes too (scale), not only position. Default true. */\n  scale?: boolean\n}\n\nexport interface FlipPlayOptions extends FlipOptions {\n  /** The elements to animate from the snapshot boxes, matched by `data-flip-id`. */\n  targets: FlipTargets\n}\n\ninterface Box {\n  readonly left: number\n  readonly top: number\n  readonly width: number\n  readonly height: number\n}\n\n/** A captured set of element boxes, keyed by `data-flip-id` (or the element itself). */\nexport interface FlipSnapshot {\n  readonly boxes: ReadonlyMap<string | HTMLElement, Box>\n}\n\ninterface FlipState {\n  readonly x: Animatable\n  readonly y: Animatable\n  readonly sx: Animatable\n  readonly sy: Animatable\n}\n\ninterface Velocity {\n  readonly x: number\n  readonly y: number\n  readonly sx: number\n  readonly sy: number\n}\n\nconst ZERO_VELOCITY: Velocity = { x: 0, y: 0, sx: 0, sy: 0 }\n\n// FLIP owns the element's transform directly: the writes must be SYNCHRONOUS so\n// the inverted box paints before the browser shows the new layout (no flash) -\n// which is why this drives style.transform itself instead of bindStyle (whose\n// flush is deferred to the render phase). One spring set per element, reused.\nconst states = new WeakMap<HTMLElement, FlipState>()\n\nconst toElements = (targets: FlipTargets): HTMLElement[] =>\n  targets instanceof HTMLElement ? [targets] : Array.from(targets)\n\nconst measure = (element: HTMLElement): Box => {\n  const r = element.getBoundingClientRect()\n  return { left: r.left, top: r.top, width: r.width, height: r.height }\n}\n\nconst keyOf = (element: HTMLElement): string | HTMLElement => element.dataset.flipId ?? element\n\nconst writeTransform = (element: HTMLElement, x: number, y: number, sx: number, sy: number): void => {\n  if (x === 0 && y === 0 && sx === 1 && sy === 1) {\n    element.style.transform = ''\n    return\n  }\n  const scale = sx === 1 && sy === 1 ? '' : ` scale(${sx}, ${sy})`\n  element.style.transform = `translate3d(${x}px, ${y}px, 0)${scale}`\n}\n\nconst ensureState = (element: HTMLElement, options: FlipOptions): FlipState => {\n  let state = states.get(element)\n  if (state === undefined) {\n    const valueOptions = options.scheduler !== undefined ? { scheduler: options.scheduler } : {}\n    const x = animatable(0, valueOptions)\n    const y = animatable(0, valueOptions)\n    const sx = animatable(1, valueOptions)\n    const sy = animatable(1, valueOptions)\n    const write = (): void => writeTransform(element, x.get(), y.get(), sx.get(), sy.get())\n    x.on('change', write)\n    y.on('change', write)\n    sx.on('change', write)\n    sy.on('change', write)\n    element.style.transformOrigin = '0 0' // pin the top-left so scale and translate align\n    state = { x, y, sx, sy }\n    states.set(element, state)\n  }\n  return state\n}\n\n// Stop any in-flight spring and read its live velocity, so the next play carries\n// the momentum instead of restarting (the interruptible handoff).\nconst seizeVelocity = (element: HTMLElement): Velocity => {\n  const state = states.get(element)\n  if (state === undefined) return ZERO_VELOCITY\n  const velocity = { x: state.x.velocity(), y: state.y.velocity(), sx: state.sx.velocity(), sy: state.sy.velocity() }\n  state.x.stop()\n  state.y.stop()\n  state.sx.stop()\n  state.sy.stop()\n  return velocity\n}\n\n// Invert (First minus the element's current natural box) and spring to identity.\nconst invertAndSpring = (element: HTMLElement, first: Box, velocity: Velocity, options: FlipOptions): void => {\n  const useScale = options.scale !== false\n  const last = measure(element)\n  const dx = first.left - last.left\n  const dy = first.top - last.top\n  const sx = useScale && last.width > 0 ? first.width / last.width : 1\n  const sy = useScale && last.height > 0 ? first.height / last.height : 1\n\n  if (dx === 0 && dy === 0 && sx === 1 && sy === 1) {\n    const existing = states.get(element)\n    if (existing !== undefined) {\n      existing.x.set(0)\n      existing.y.set(0)\n      existing.sx.set(1)\n      existing.sy.set(1)\n    }\n    element.style.transform = ''\n    return\n  }\n\n  const state = ensureState(element, options)\n  writeTransform(element, dx, dy, sx, sy) // appear at First synchronously - no flash\n  state.x.set(dx, { velocity: velocity.x })\n  state.y.set(dy, { velocity: velocity.y })\n  state.sx.set(sx, { velocity: velocity.sx })\n  state.sy.set(sy, { velocity: velocity.sy })\n  state.x.spring(0, options)\n  state.y.spring(0, options)\n  state.sx.spring(1, options)\n  state.sy.spring(1, options)\n}\n\n/**\n * Physics-first FLIP. Measures each element's box (First), runs `mutate` to\n * change the DOM, measures again (Last), applies the inverse transform - both\n * position AND size - so nothing visibly jumps, then springs every element to\n * its new place. The play is a spring, not a baked tween: call flip() again\n * mid-flight and each element retargets from its live position and velocity, so\n * the motion bends into the new layout instead of restarting. That\n * interruptibility is the whole point.\n */\nexport function flip(targets: FlipTargets, mutate: () => void, options: FlipOptions = {}): void {\n  const elements = toElements(targets)\n\n  // First: current visual box (with any in-flight transform), plus the live\n  // velocity of a running spring.\n  const first = new Map<HTMLElement, Box>()\n  const velocity = new Map<HTMLElement, Velocity>()\n  for (const element of elements) {\n    first.set(element, measure(element))\n    velocity.set(element, seizeVelocity(element))\n  }\n\n  // Strip transforms so the Last measurement is the natural layout box.\n  for (const element of elements) element.style.transform = ''\n\n  mutate()\n\n  for (const element of elements) {\n    const box = first.get(element)\n    if (box === undefined) continue\n    invertAndSpring(element, box, velocity.get(element) ?? ZERO_VELOCITY, options)\n  }\n}\n\n/**\n * Capture each target's box, keyed by its `data-flip-id` (or the element\n * itself). Pair with `play()` for shared-element / route transitions, where the\n * old elements and the new ones are different DOM nodes: snapshot the old set,\n * change the DOM, then play the new set from the captured boxes.\n */\nexport function snapshot(targets: FlipTargets): FlipSnapshot {\n  const boxes = new Map<string | HTMLElement, Box>()\n  for (const element of toElements(targets)) boxes.set(keyOf(element), measure(element))\n  return { boxes }\n}\n\n/**\n * Animate each target from its matching box in the snapshot to its current\n * place - matched by `data-flip-id`. A target with no match in the snapshot is\n * left alone. Interruptible like `flip()`.\n */\nexport function play(snap: FlipSnapshot, options: FlipPlayOptions): void {\n  for (const element of toElements(options.targets)) {\n    const first = snap.boxes.get(keyOf(element))\n    if (first === undefined) continue\n    const velocity = seizeVelocity(element)\n    element.style.transform = '' // ensure Last is the natural box\n    invertAndSpring(element, first, velocity, options)\n  }\n}\n"],"names":["ZERO_VELOCITY","states","toElements","targets","measure","element","r","keyOf","writeTransform","x","y","sx","sy","scale","ensureState","options","state","valueOptions","animatable","write","seizeVelocity","velocity","invertAndSpring","first","useScale","last","dx","dy","existing","flip","mutate","elements","box","snapshot","boxes","play","snap"],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { flip, play, snapshot } from './flip';
+export type { FlipOptions, FlipPlayOptions, FlipSnapshot, FlipTargets } from './flip';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,QAAQ,CAAA"}

package/dist/index.js

@@ -0,0 +1,63 @@
+import { animatable as y } from "@underlying/core";
+const u = { x: 0, y: 0, sx: 0, sy: 0 }, g = /* @__PURE__ */ new WeakMap(), h = (s) => s instanceof HTMLElement ? [s] : Array.from(s), d = (s) => {
+  const t = s.getBoundingClientRect();
+  return { left: t.left, top: t.top, width: t.width, height: t.height };
+}, p = (s) => s.dataset.flipId ?? s, v = (s, t, e, n, c) => {
+  if (t === 0 && e === 0 && n === 1 && c === 1) {
+    s.style.transform = "";
+    return;
+  }
+  const r = n === 1 && c === 1 ? "" : ` scale(${n}, ${c})`;
+  s.style.transform = `translate3d(${t}px, ${e}px, 0)${r}`;
+}, M = (s, t) => {
+  let e = g.get(s);
+  if (e === void 0) {
+    const n = t.scheduler !== void 0 ? { scheduler: t.scheduler } : {}, c = y(0, n), r = y(0, n), o = y(1, n), i = y(1, n), a = () => v(s, c.get(), r.get(), o.get(), i.get());
+    c.on("change", a), r.on("change", a), o.on("change", a), i.on("change", a), s.style.transformOrigin = "0 0", e = { x: c, y: r, sx: o, sy: i }, g.set(s, e);
+  }
+  return e;
+}, m = (s) => {
+  const t = g.get(s);
+  if (t === void 0) return u;
+  const e = { x: t.x.velocity(), y: t.y.velocity(), sx: t.sx.velocity(), sy: t.sy.velocity() };
+  return t.x.stop(), t.y.stop(), t.sx.stop(), t.sy.stop(), e;
+}, w = (s, t, e, n) => {
+  const c = n.scale !== !1, r = d(s), o = t.left - r.left, i = t.top - r.top, a = c && r.width > 0 ? t.width / r.width : 1, x = c && r.height > 0 ? t.height / r.height : 1;
+  if (o === 0 && i === 0 && a === 1 && x === 1) {
+    const l = g.get(s);
+    l !== void 0 && (l.x.set(0), l.y.set(0), l.sx.set(1), l.sy.set(1)), s.style.transform = "";
+    return;
+  }
+  const f = M(s, n);
+  v(s, o, i, a, x), f.x.set(o, { velocity: e.x }), f.y.set(i, { velocity: e.y }), f.sx.set(a, { velocity: e.sx }), f.sy.set(x, { velocity: e.sy }), f.x.spring(0, n), f.y.spring(0, n), f.sx.spring(1, n), f.sy.spring(1, n);
+};
+function $(s, t, e = {}) {
+  const n = h(s), c = /* @__PURE__ */ new Map(), r = /* @__PURE__ */ new Map();
+  for (const o of n)
+    c.set(o, d(o)), r.set(o, m(o));
+  for (const o of n) o.style.transform = "";
+  t();
+  for (const o of n) {
+    const i = c.get(o);
+    i !== void 0 && w(o, i, r.get(o) ?? u, e);
+  }
+}
+function b(s) {
+  const t = /* @__PURE__ */ new Map();
+  for (const e of h(s)) t.set(p(e), d(e));
+  return { boxes: t };
+}
+function E(s, t) {
+  for (const e of h(t.targets)) {
+    const n = s.boxes.get(p(e));
+    if (n === void 0) continue;
+    const c = m(e);
+    e.style.transform = "", w(e, n, c, t);
+  }
+}
+export {
+  $ as flip,
+  E as play,
+  b as snapshot
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/flip.ts"],"sourcesContent":["import { animatable, type Animatable, type Scheduler, type SpringOptions } from '@underlying/core'\n\nexport type FlipTargets = HTMLElement | Iterable<HTMLElement>\n\nexport interface FlipOptions extends SpringOptions {\n  scheduler?: Scheduler\n  /** Invert and animate size changes too (scale), not only position. Default true. */\n  scale?: boolean\n}\n\nexport interface FlipPlayOptions extends FlipOptions {\n  /** The elements to animate from the snapshot boxes, matched by `data-flip-id`. */\n  targets: FlipTargets\n}\n\ninterface Box {\n  readonly left: number\n  readonly top: number\n  readonly width: number\n  readonly height: number\n}\n\n/** A captured set of element boxes, keyed by `data-flip-id` (or the element itself). */\nexport interface FlipSnapshot {\n  readonly boxes: ReadonlyMap<string | HTMLElement, Box>\n}\n\ninterface FlipState {\n  readonly x: Animatable\n  readonly y: Animatable\n  readonly sx: Animatable\n  readonly sy: Animatable\n}\n\ninterface Velocity {\n  readonly x: number\n  readonly y: number\n  readonly sx: number\n  readonly sy: number\n}\n\nconst ZERO_VELOCITY: Velocity = { x: 0, y: 0, sx: 0, sy: 0 }\n\n// FLIP owns the element's transform directly: the writes must be SYNCHRONOUS so\n// the inverted box paints before the browser shows the new layout (no flash) -\n// which is why this drives style.transform itself instead of bindStyle (whose\n// flush is deferred to the render phase). One spring set per element, reused.\nconst states = new WeakMap<HTMLElement, FlipState>()\n\nconst toElements = (targets: FlipTargets): HTMLElement[] =>\n  targets instanceof HTMLElement ? [targets] : Array.from(targets)\n\nconst measure = (element: HTMLElement): Box => {\n  const r = element.getBoundingClientRect()\n  return { left: r.left, top: r.top, width: r.width, height: r.height }\n}\n\nconst keyOf = (element: HTMLElement): string | HTMLElement => element.dataset.flipId ?? element\n\nconst writeTransform = (element: HTMLElement, x: number, y: number, sx: number, sy: number): void => {\n  if (x === 0 && y === 0 && sx === 1 && sy === 1) {\n    element.style.transform = ''\n    return\n  }\n  const scale = sx === 1 && sy === 1 ? '' : ` scale(${sx}, ${sy})`\n  element.style.transform = `translate3d(${x}px, ${y}px, 0)${scale}`\n}\n\nconst ensureState = (element: HTMLElement, options: FlipOptions): FlipState => {\n  let state = states.get(element)\n  if (state === undefined) {\n    const valueOptions = options.scheduler !== undefined ? { scheduler: options.scheduler } : {}\n    const x = animatable(0, valueOptions)\n    const y = animatable(0, valueOptions)\n    const sx = animatable(1, valueOptions)\n    const sy = animatable(1, valueOptions)\n    const write = (): void => writeTransform(element, x.get(), y.get(), sx.get(), sy.get())\n    x.on('change', write)\n    y.on('change', write)\n    sx.on('change', write)\n    sy.on('change', write)\n    element.style.transformOrigin = '0 0' // pin the top-left so scale and translate align\n    state = { x, y, sx, sy }\n    states.set(element, state)\n  }\n  return state\n}\n\n// Stop any in-flight spring and read its live velocity, so the next play carries\n// the momentum instead of restarting (the interruptible handoff).\nconst seizeVelocity = (element: HTMLElement): Velocity => {\n  const state = states.get(element)\n  if (state === undefined) return ZERO_VELOCITY\n  const velocity = { x: state.x.velocity(), y: state.y.velocity(), sx: state.sx.velocity(), sy: state.sy.velocity() }\n  state.x.stop()\n  state.y.stop()\n  state.sx.stop()\n  state.sy.stop()\n  return velocity\n}\n\n// Invert (First minus the element's current natural box) and spring to identity.\nconst invertAndSpring = (element: HTMLElement, first: Box, velocity: Velocity, options: FlipOptions): void => {\n  const useScale = options.scale !== false\n  const last = measure(element)\n  const dx = first.left - last.left\n  const dy = first.top - last.top\n  const sx = useScale && last.width > 0 ? first.width / last.width : 1\n  const sy = useScale && last.height > 0 ? first.height / last.height : 1\n\n  if (dx === 0 && dy === 0 && sx === 1 && sy === 1) {\n    const existing = states.get(element)\n    if (existing !== undefined) {\n      existing.x.set(0)\n      existing.y.set(0)\n      existing.sx.set(1)\n      existing.sy.set(1)\n    }\n    element.style.transform = ''\n    return\n  }\n\n  const state = ensureState(element, options)\n  writeTransform(element, dx, dy, sx, sy) // appear at First synchronously - no flash\n  state.x.set(dx, { velocity: velocity.x })\n  state.y.set(dy, { velocity: velocity.y })\n  state.sx.set(sx, { velocity: velocity.sx })\n  state.sy.set(sy, { velocity: velocity.sy })\n  state.x.spring(0, options)\n  state.y.spring(0, options)\n  state.sx.spring(1, options)\n  state.sy.spring(1, options)\n}\n\n/**\n * Physics-first FLIP. Measures each element's box (First), runs `mutate` to\n * change the DOM, measures again (Last), applies the inverse transform - both\n * position AND size - so nothing visibly jumps, then springs every element to\n * its new place. The play is a spring, not a baked tween: call flip() again\n * mid-flight and each element retargets from its live position and velocity, so\n * the motion bends into the new layout instead of restarting. That\n * interruptibility is the whole point.\n */\nexport function flip(targets: FlipTargets, mutate: () => void, options: FlipOptions = {}): void {\n  const elements = toElements(targets)\n\n  // First: current visual box (with any in-flight transform), plus the live\n  // velocity of a running spring.\n  const first = new Map<HTMLElement, Box>()\n  const velocity = new Map<HTMLElement, Velocity>()\n  for (const element of elements) {\n    first.set(element, measure(element))\n    velocity.set(element, seizeVelocity(element))\n  }\n\n  // Strip transforms so the Last measurement is the natural layout box.\n  for (const element of elements) element.style.transform = ''\n\n  mutate()\n\n  for (const element of elements) {\n    const box = first.get(element)\n    if (box === undefined) continue\n    invertAndSpring(element, box, velocity.get(element) ?? ZERO_VELOCITY, options)\n  }\n}\n\n/**\n * Capture each target's box, keyed by its `data-flip-id` (or the element\n * itself). Pair with `play()` for shared-element / route transitions, where the\n * old elements and the new ones are different DOM nodes: snapshot the old set,\n * change the DOM, then play the new set from the captured boxes.\n */\nexport function snapshot(targets: FlipTargets): FlipSnapshot {\n  const boxes = new Map<string | HTMLElement, Box>()\n  for (const element of toElements(targets)) boxes.set(keyOf(element), measure(element))\n  return { boxes }\n}\n\n/**\n * Animate each target from its matching box in the snapshot to its current\n * place - matched by `data-flip-id`. A target with no match in the snapshot is\n * left alone. Interruptible like `flip()`.\n */\nexport function play(snap: FlipSnapshot, options: FlipPlayOptions): void {\n  for (const element of toElements(options.targets)) {\n    const first = snap.boxes.get(keyOf(element))\n    if (first === undefined) continue\n    const velocity = seizeVelocity(element)\n    element.style.transform = '' // ensure Last is the natural box\n    invertAndSpring(element, first, velocity, options)\n  }\n}\n"],"names":["ZERO_VELOCITY","states","toElements","targets","measure","element","r","keyOf","writeTransform","x","y","sx","sy","scale","ensureState","options","state","valueOptions","animatable","write","seizeVelocity","velocity","invertAndSpring","first","useScale","last","dx","dy","existing","flip","mutate","elements","box","snapshot","boxes","play","snap"],"mappings":"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"}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@underlying/flip",
+  "version": "0.1.0-beta.0",
+  "description": "Physics-first FLIP for @underlying/core: animate layout and shared-element transitions from old place to new, position and size - interruptible, retargeting mid-flight from live velocity.",
+  "license": "MIT",
+  "author": "underlyi.ng <contact@underlyi.ng>",
+  "keywords": [
+    "animation",
+    "flip",
+    "layout",
+    "transition",
+    "shared-element",
+    "physics",
+    "spring"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/underlyingjs/underlying.git",
+    "directory": "packages/flip"
+  },
+  "homepage": "https://github.com/underlyingjs/underlying#readme",
+  "bugs": "https://github.com/underlyingjs/underlying/issues",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@underlying/core": "0.1.0-beta.6"
+  },
+  "devDependencies": {
+    "esbuild": "^0.25.0",
+    "jsdom": "^26.1.0",
+    "typescript": "^5.8.3",
+    "vite": "^6.3.5",
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "size": "node scripts/check-size.mjs"
+  }
+}