@impractical-ai/motion 0.1.6 → 0.1.7

package/assets/kits/morphkit.ts

@@ -0,0 +1,438 @@
+// Universal shape morph — the shared-element architecture (how Framer
+// Motion's layoutId / iOS matchedGeometryEffect / Flutter Hero do it):
+// NO snapshots, NO carrier. Both REAL elements ride one interpolated box
+// path (position + size + corner radius, with an arc lift); each is scaled
+// to the path's box from its own natural geometry and they crossfade
+// mid-flight, so each side is only visible while near its natural shape —
+// distortion is never seen, and the target that lands IS the live element.
+//
+// Why this beats the snapshot-carrier approach it replaced:
+//   · the content that arrives is the real element — "part of the morph"
+//     by construction, not a bitmap dissolve
+//   · real box-shadows ride along (nothing goes flat mid-flight)
+//   · a spring ease rides the shared path — box, corners, and travel ring
+//     together with no delayed settle
+//   · the target's children are live and arrive individually (staggered)
+//
+// Determinism: geometry measured at build; per-frame updates are pure
+// functions of one proxy tween; all end states are exact identities.
+import { resolveTarget, layoutRect } from './kits'
+
+type Position = number | string | undefined
+type Rect = { left: number; top: number; width: number; height: number }
+type Corners = { tl: number; tr: number; br: number; bl: number }
+
+const EASE = 'ease-in-out-cubic'
+
+function cornersOf(el: HTMLElement | null, rect: Rect): Corners {
+  if (!el) return { tl: 0, tr: 0, br: 0, bl: 0 }
+  const s = getComputedStyle(el)
+  const parse = (v: string): number => {
+    const n = parseFloat(v)
+    if (v.trim().endsWith('%')) return (n / 100) * Math.min(rect.width, rect.height)
+    return isNaN(n) ? 0 : n
+  }
+  const cap = Math.min(rect.width, rect.height) / 2
+  return {
+    tl: Math.min(cap, parse(s.borderTopLeftRadius)),
+    tr: Math.min(cap, parse(s.borderTopRightRadius)),
+    br: Math.min(cap, parse(s.borderBottomRightRadius)),
+    bl: Math.min(cap, parse(s.borderBottomLeftRadius)),
+  }
+}
+
+export type MorphOpts = {
+  /** 'apple' = expo-out flight (~90% of the change in the first ~15% of the
+   * time, long soft landing). 'spring' = the reference bounce: expo-out
+   * flight, then a LIGHT damped sine rides the same path — calibrated from
+   * the dnyxstudios AE expression (amp .04·v, freq 1.8Hz, decay e^-3t,
+   * eased envelope). One motion, no delayed settle, ~one visible overshoot. */
+  feel?: 'apple' | 'spring'
+  /** Tune the 'spring' bounce. `amp` = first overshoot as a fraction of the
+   * travel (default 0.025 — light), `freq` Hz (default 1.8), `decay` per
+   * second (default 3), `flight` = fraction of `duration` spent on the main
+   * move before the bounce tail (default 0.55). */
+  bounce?: { amp?: number; freq?: number; decay?: number; flight?: number }
+  duration?: number
+  /** Flight curve — ANY GSAP ease works: house names, 'elastic.out(1, 0.4)',
+   * 'back.out(1.8)'… Overshoots extrapolate past the target (kept renderable). */
+  ease?: string
+  /** 0..1 — center of the A→B crossfade along the flight. */
+  handoff?: number
+  /** Width of the crossfade as a fraction of the flight (default 0.3 —
+   * tight; each side shows only near its natural shape). */
+  crossfade?: number
+  /** Arc lift in px (0 disables). Default: auto from travel distance. */
+  arc?: number
+  /** Part choreography (default 'stagger'): the target's direct children
+   * arrive individually inside the landing box; the source's children are
+   * absorbed as it leaves. `false` = containers only. */
+  parts?: 'stagger' | false
+  /** Sub-component matching (default 'auto'): elements tagged
+   * `data-morph="name"` on BOTH sides (any depth) morph INTO each other —
+   * each pair rides its own interpolated box inside the flight, so the
+   * source's sub-component visibly becomes the target's. Untagged direct
+   * children are greedily auto-paired by text overlap. `false` disables. */
+  match?: 'auto' | false
+  /** Landing overshoot on top of a non-spring flight. `true`/default object
+   * for the soft house settle, `{ scale, duration, ease }` to tune (elastic
+   * landings live here), `false` for none. 'spring' feel ignores this — its
+   * ring is already in the flight. */
+  settle?: boolean | { scale?: number; duration?: number; ease?: string }
+  zIndex?: number
+}
+
+export function createMorphKit(deps: {
+  tl: any
+  gsap: any
+  stage: HTMLElement
+  config: { width: number; height: number }
+}) {
+  const { tl, gsap, stage, config } = deps
+  const at = (position: Position): number => (typeof position === 'number' ? position : tl.duration())
+
+  const resolveEnd = (
+    target: string | Element | Rect | 'frame'
+  ): { el: HTMLElement | null; rect: Rect } => {
+    if (target === 'frame') {
+      return { el: null, rect: { left: 0, top: 0, width: config.width, height: config.height } }
+    }
+    if (typeof target === 'object' && target !== null && !(target instanceof Element)) {
+      return { el: null, rect: target as Rect }
+    }
+    const el = resolveTarget(stage, target as string | Element, 'morph')
+    return { el, rect: layoutRect(stage, el) }
+  }
+
+  // KNOWN LIMIT: morph and expand measure at build time via layoutRect. Inside
+  // a container the direction scales mid-timeline the flight path lands off —
+  // do the container zoom with camera.move (stage-level, measured out), or
+  // morph before/after the zoom. actions and highlight resolve lazily; morph's
+  // corner interpolation bakes its geometry and has not been converted.
+  const morph = (
+    from: string | Element,
+    to: string | Element | Rect | 'frame',
+    opts: MorphOpts = {},
+    position?: Position
+  ): { duration: number } => {
+    const aEl = resolveTarget(stage, from, 'morph')
+    const aRect = layoutRect(stage, aEl)
+    const bEnd = resolveEnd(to)
+    const bEl = bEnd.el
+    const bRect = bEnd.rect
+    const apple = opts.feel === 'apple'
+    const springy = opts.feel === 'spring'
+    const duration = opts.duration ?? (apple ? 0.6 : springy ? 1.15 : 0.7)
+    const handoff = Math.max(0.1, Math.min(0.9, opts.handoff ?? 0.5))
+    const cross = Math.max(0.08, Math.min(0.8, opts.crossfade ?? 0.3))
+    const start = at(position)
+    const travel = Math.hypot(bRect.left - aRect.left, bRect.top - aRect.top)
+    const arc = opts.arc ?? (apple || springy ? Math.min(24, travel * 0.05) : Math.min(40, travel * 0.08))
+    const ca = cornersOf(aEl, aRect)
+    const cb = cornersOf(bEl, bRect)
+    let eased: (p: number) => number
+    if (springy) {
+      // The reference bounce (dnyxstudios AE expression): main move, then
+      // value + v·amp·sin(2π·freq·t)/e^(decay·t)·easeOut-envelope. Ported
+      // with amp normalized to "first overshoot as a fraction of travel".
+      const bo = opts.bounce ?? {}
+      const amp = bo.amp ?? 0.025
+      const freq = bo.freq ?? 1.8
+      const decay = bo.decay ?? 3
+      const flight = Math.max(0.2, Math.min(0.9, bo.flight ?? 0.55))
+      // power3.out, not expo.out: expo parks motionless for the last ~30% of
+      // the flight, and a bounce after a stall reads as LAG. The wobble also
+      // OVERLAPS the flight's tail so the arrival momentum flows straight
+      // into the first overshoot — motion never stops.
+      const base = gsap.parseEase(opts.ease ?? 'power3.out')
+      // Normalize so the first sine peak equals `amp` exactly.
+      const tPeak = 1 / (4 * freq)
+      const peak = Math.sin(2 * Math.PI * freq * tPeak) * Math.exp(-decay * tPeak)
+      const scale = amp / Math.max(1e-6, peak)
+      const Dm = duration * flight
+      const overlap = Math.min(0.12, Dm * 0.25)
+      eased = (p: number) => {
+        const tAbs = p * duration
+        let v = base(Math.min(1, tAbs / Math.max(1e-6, Dm)))
+        const t = tAbs - (Dm - overlap)
+        if (t > 0) {
+          const envelope = Math.max(0, 1 - t / 3)
+          v += scale * Math.sin(2 * Math.PI * freq * t) * Math.exp(-decay * t) * envelope
+        }
+        return v
+      }
+    } else {
+      eased = gsap.parseEase(opts.ease ?? (apple ? 'expo.out' : EASE))
+    }
+
+    // Both elements need transform-from-origin-0 semantics for the box math.
+    gsap.set(aEl, { transformOrigin: '0 0' })
+    if (bEl) gsap.set(bEl, { transformOrigin: '0 0' })
+    // Authors set radius INLINE (React styles) — clearProps would delete it,
+    // so capture the original declarations to restore at the end.
+    const aRadius0 = aEl.style.borderRadius
+    const bRadius0 = bEl ? bEl.style.borderRadius : ''
+
+    // ── Sub-component matching: pairs ride their own box inside the flight ──
+    const wrapLooseText = (el: HTMLElement | null) => {
+      if (!el) return
+      for (const node of Array.from(el.childNodes)) {
+        if (node.nodeType === 3 && node.textContent && node.textContent.trim()) {
+          const span = document.createElement('span')
+          span.style.display = 'inline-block'
+          node.parentNode?.insertBefore(span, node)
+          span.appendChild(node)
+        }
+      }
+    }
+    wrapLooseText(aEl)
+    wrapLooseText(bEl)
+    type Pair = { a: HTMLElement; b: HTMLElement; ar: Rect; br: Rect }
+    const pairs: Pair[] = []
+    if ((opts.match ?? 'auto') !== false && bEl) {
+      // Explicit: data-morph names present on both sides, any depth.
+      const named = (root: HTMLElement) => {
+        const map = new Map<string, HTMLElement>()
+        for (const el of Array.from(root.querySelectorAll<HTMLElement>('[data-morph]'))) {
+          const name = el.dataset.morph
+          if (name && !map.has(name)) map.set(name, el)
+        }
+        return map
+      }
+      const aNamed = named(aEl)
+      const bNamed = named(bEl)
+      for (const [name, a] of aNamed) {
+        const b = bNamed.get(name)
+        if (b) pairs.push({ a, b, ar: layoutRect(stage, a), br: layoutRect(stage, b) })
+      }
+      // Greedy auto-match of untagged DIRECT children by text-token overlap.
+      const tokens = (el: HTMLElement) =>
+        new Set(
+          (el.textContent ?? '')
+            .toLowerCase()
+            .replace(/[^a-z0-9\s]/g, ' ')
+            .split(/\s+/)
+            .filter((w) => w.length > 1)
+        )
+      const taken = new Set(pairs.flatMap((p) => [p.a, p.b]))
+      const free = (el: HTMLElement) =>
+        !taken.has(el) && !el.querySelector('[data-morph]') && !el.dataset.morph
+      const aFree = (Array.from(aEl.children) as HTMLElement[]).filter(free)
+      const bFree = bEl ? (Array.from(bEl.children) as HTMLElement[]).filter(free) : []
+      for (const a of aFree) {
+        const ta = tokens(a)
+        if (!ta.size) continue
+        let best: HTMLElement | null = null
+        let bestScore = 0
+        for (const b of bFree) {
+          if (taken.has(b)) continue
+          let s = 0
+          for (const w of tokens(b)) if (ta.has(w)) s += 1
+          if (b.tagName === a.tagName) s += 0.25
+          if (s > bestScore) {
+            bestScore = s
+            best = b
+          }
+        }
+        if (best && bestScore >= 1) {
+          taken.add(a)
+          taken.add(best)
+          pairs.push({ a, b: best, ar: layoutRect(stage, a), br: layoutRect(stage, best) })
+        }
+      }
+    }
+    // An element that is (or contains) a matched pair must not be absorbed
+    // or arrival-staggered — the pair choreography owns it.
+    const ownedByPair = (el: HTMLElement) =>
+      pairs.some((p) => el === p.a || el === p.b || el.contains(p.a) || el.contains(p.b))
+
+    // ── The shared box path — one pure function both elements ride ──
+    const proxy = { p: 0 }
+    const pose = (p: number) => {
+      const e = eased(p)
+      const w = Math.max(2, aRect.width + (bRect.width - aRect.width) * e)
+      const h = Math.max(2, aRect.height + (bRect.height - aRect.height) * e)
+      const x = aRect.left + (bRect.left - aRect.left) * e
+      const y =
+        aRect.top +
+        (bRect.top - aRect.top) * e -
+        Math.sin(Math.PI * Math.min(1, Math.max(0, e))) * arc
+      const cap = Math.min(w, h) / 2
+      const cl = (v: number) => Math.max(0, Math.min(cap, v))
+      const radius = cl((ca.tl + ca.tr + ca.br + ca.bl) / 4 + ((cb.tl + cb.tr + cb.br + cb.bl) / 4 - (ca.tl + ca.tr + ca.br + ca.bl) / 4) * e)
+      // Two-axis radius compensation: under non-uniform scale a single
+      // radius renders elliptical, so counter each axis separately.
+      const sxA0 = w / Math.max(1, aRect.width)
+      const syA0 = h / Math.max(1, aRect.height)
+      gsap.set(aEl, {
+        x: x - aRect.left,
+        y: y - aRect.top,
+        scaleX: sxA0,
+        scaleY: syA0,
+        borderRadius: `${radius / Math.max(0.01, sxA0)}px / ${radius / Math.max(0.01, syA0)}px`,
+        force3D: false,
+      })
+      if (bEl) {
+        const sxB0 = w / Math.max(1, bRect.width)
+        const syB0 = h / Math.max(1, bRect.height)
+        gsap.set(bEl, {
+          x: x - bRect.left,
+          y: y - bRect.top,
+          scaleX: sxB0,
+          scaleY: syB0,
+          borderRadius: `${radius / Math.max(0.01, sxB0)}px / ${radius / Math.max(0.01, syB0)}px`,
+          force3D: false,
+        })
+      }
+      // Matched pairs: counter-transform each side inside its parent so both
+      // occupy the SAME interpolated scene box — during the crossfade they
+      // are geometrically aligned, and one sub-component becomes the other.
+      if (pairs.length) {
+        const arcTerm = Math.sin(Math.PI * Math.min(1, Math.max(0, e))) * arc
+        const sxA = w / Math.max(1, aRect.width)
+        const syA = h / Math.max(1, aRect.height)
+        const sxB = w / Math.max(1, bRect.width)
+        const syB = h / Math.max(1, bRect.height)
+        for (const pr of pairs) {
+          const cw = pr.ar.width + (pr.br.width - pr.ar.width) * e
+          const chh = pr.ar.height + (pr.br.height - pr.ar.height) * e
+          const px = pr.ar.left + (pr.br.left - pr.ar.left) * e
+          const py = pr.ar.top + (pr.br.top - pr.ar.top) * e - arcTerm
+          gsap.set(pr.a, {
+            transformOrigin: '0 0',
+            x: (px - x) / sxA - (pr.ar.left - aRect.left),
+            y: (py - y) / syA - (pr.ar.top - aRect.top),
+            scaleX: cw / Math.max(0.01, sxA * pr.ar.width),
+            scaleY: chh / Math.max(0.01, syA * pr.ar.height),
+            force3D: false,
+          })
+          gsap.set(pr.b, {
+            transformOrigin: '0 0',
+            x: (px - x) / sxB - (pr.br.left - bRect.left),
+            y: (py - y) / syB - (pr.br.top - bRect.top),
+            scaleX: cw / Math.max(0.01, sxB * pr.br.width),
+            scaleY: chh / Math.max(0.01, syB * pr.br.height),
+            force3D: false,
+          })
+        }
+      }
+    }
+
+    // ── Crossfade: each side is visible only near its natural shape ──
+    const fadeStart = start + duration * (handoff - cross / 2)
+    const fadeSpan = duration * cross
+    if (bEl) gsap.set(bEl, { autoAlpha: 0 })
+    tl.to(aEl, { autoAlpha: 0, duration: fadeSpan * 0.6, ease: 'ease-in-quad' }, fadeStart + fadeSpan * 0.2)
+    if (bEl) {
+      tl.to(bEl, { autoAlpha: 1, duration: fadeSpan * 0.7, ease: 'ease-out-quad' }, fadeStart)
+    }
+
+    // ── Parts: the target's children ARRIVE as live elements; the source's
+    // are absorbed as it leaves. All end states are exact identities. ──
+    if ((opts.parts ?? 'stagger') !== false) {
+      const kids = (el: HTMLElement | null): HTMLElement[] =>
+        el ? (Array.from(el.children) as HTMLElement[]).filter((k) => !ownedByPair(k)) : []
+      const absorbSpan = Math.max(0.15, duration * handoff * 0.7)
+      for (const [i, kid] of kids(aEl).entries()) {
+        tl.to(
+          kid,
+          { scale: 0.88, y: 8, autoAlpha: 0, duration: absorbSpan, ease: 'ease-in-quad', force3D: false },
+          start + i * 0.05
+        )
+        // The source ends hidden; restore its children for a clean baseline.
+        tl.set(kid, { scale: 1, y: 0, autoAlpha: 1 }, start + duration)
+      }
+      for (const [i, kid] of kids(bEl).entries()) {
+        gsap.set(kid, { autoAlpha: 0, y: 12, scale: 0.94 })
+        tl.to(
+          kid,
+          { autoAlpha: 1, y: 0, scale: 1, duration: 0.36, ease: 'promo-out', force3D: false },
+          start + duration * handoff + i * 0.07
+        )
+      }
+    }
+
+    // ── The flight ──
+    tl.to(proxy, { p: 1, duration, ease: 'none', onUpdate: () => pose(proxy.p) }, start)
+    // Exact end states: A hidden and reset, B at true identity.
+    // Restore the author's inline radius; if it lived in a stylesheet,
+    // clearing the inline override reveals it again.
+    tl.set(
+      aEl,
+      { autoAlpha: 0, x: 0, y: 0, scaleX: 1, scaleY: 1, ...(aRadius0 ? { borderRadius: aRadius0 } : { clearProps: 'borderRadius' }) },
+      start + duration
+    )
+    if (bEl) {
+      tl.set(
+        bEl,
+        { x: 0, y: 0, scaleX: 1, scaleY: 1, ...(bRadius0 ? { borderRadius: bRadius0 } : { clearProps: 'borderRadius' }) },
+        start + duration
+      )
+    }
+    for (const pr of pairs) {
+      tl.set(pr.a, { x: 0, y: 0, scaleX: 1, scaleY: 1 }, start + duration)
+      tl.set(pr.b, { x: 0, y: 0, scaleX: 1, scaleY: 1 }, start + duration)
+    }
+
+    // ── Optional landing settle (spring feel needs none — it rang in-flight) ──
+    const settle = opts.settle === undefined ? !springy : opts.settle !== false
+    if (settle && bEl) {
+      const s = typeof opts.settle === 'object' ? opts.settle : {}
+      tl.fromTo(
+        bEl,
+        { scale: s.scale ?? (apple ? 1.03 : 1.05), transformOrigin: '50% 50%' },
+        {
+          scale: 1,
+          duration: s.duration ?? (apple ? 0.4 : 0.26),
+          ease: s.ease ?? 'promo-soft',
+          force3D: false,
+          immediateRender: false,
+        },
+        start + duration + 0.001
+      )
+    }
+    // Anticipation: the source contracts just before leaving.
+    if (opts.settle !== false && start >= 0.14) {
+      tl.to(aEl, { scale: 0.985, duration: 0.14, ease: 'ease-in-quad', force3D: false }, start - 0.14)
+      tl.set(aEl, { scale: 1 }, start)
+    }
+    return { duration }
+  }
+
+  /** The chip⇄full-bleed round trip. Meant for MEDIA (a thumbnail, a video) —
+   * the element persists and fills the frame; 'cover' bleeds on aspect
+   * mismatch, 'contain' letterboxes. Expanding a text-heavy card reads as a
+   * mistake — expand its media child. */
+  const expand = (
+    target: string | Element,
+    opts: { duration?: number; hold?: number; back?: boolean; inset?: number; fit?: 'cover' | 'contain' } = {},
+    position?: Position
+  ): { duration: number } => {
+    const el = resolveTarget(stage, target, 'expand')
+    const rect = layoutRect(stage, el)
+    const inset = opts.inset ?? 0
+    const frame: Rect = {
+      left: inset,
+      top: inset,
+      width: config.width - inset * 2,
+      height: config.height - inset * 2,
+    }
+    const duration = opts.duration ?? 0.7
+    const hold = opts.hold ?? 1.2
+    const start = at(position)
+    const scale = (opts.fit === 'contain' ? Math.min : Math.max)(
+      frame.width / rect.width,
+      frame.height / rect.height
+    )
+    const cx = rect.left + rect.width / 2
+    const cy = rect.top + rect.height / 2
+    const dx = frame.left + frame.width / 2 - cx
+    const dy = frame.top + frame.height / 2 - cy
+    tl.to(el, { x: dx, y: dy, scale, duration, ease: EASE, force3D: false }, start)
+    if (opts.back === false) return { duration: duration + hold }
+    tl.to(el, { x: 0, y: 0, scale: 1, duration: duration * 0.85, ease: EASE, force3D: false }, start + duration + hold)
+    return { duration: duration + hold + duration * 0.85 }
+  }
+
+  return { morph, expand }
+}