@impractical-ai/motion 0.1.7 → 0.1.9

package/assets/kits/ensemble.ts

@@ -1,483 +0,0 @@
-// Ensemble choreography — words that move MANY elements as one system.
-//   dropIn   — elements arrive from BEHIND THE CAMERA onto the layout
-//              (reference: raylight.app drop-in film)
-//   assemble — elements fly in from scattered planar directions and settle
-//              into their exact layout slots (Apple tile wall, Firefly
-//              place-on-canvas, Slack puzzle-slots)
-//   scatter  — the inverse: elements explode outward from their layout
-//   fountain — elements fly BALLISTICALLY through the frame: tossed up,
-//              raining down, or bursting radially (Pitch slide fountain,
-//              Apple card pile, Slack icon rain)
-//   confetti — generated celebration particles (Simar's wow-staging beat)
-//
-// SHOWPIECE DOCTRINE (fountain/confetti especially): these are BEAT-LEVEL
-// events — at most 1–2 per film, and they must land on a story payoff (a
-// launch, a celebration, a reveal). A showpiece on an ambient beat is noise.
-//
-// Generalized + deterministic: geometry is measured (layoutRect); poses are
-// closed-form functions of the seeked time (ballistics = parabola, no
-// integration); per-item variation comes from index hashing, never
-// Math.random; every element ends at exact identity or fully exited.
-import { resolveTargets, layoutRect } from './kits'
-
-type Position = number | string | undefined
-
-/** Deterministic per-index variation in [0, 1). */
-function hash01(i: number, salt = 0): number {
-  let x = (i + 1) * 2654435761 + salt * 40503
-  x = ((x >>> 16) ^ x) * 0x45d9f3b
-  x = ((x >>> 16) ^ x) * 0x45d9f3b
-  return (((x >>> 16) ^ x) >>> 0) % 10000 / 10000
-}
-
-export type DropInOpts = {
-  /** Plane blow-up factor the elements start at (default 3.2). */
-  from?: number
-  /** Per-element flight time (default 0.75). */
-  duration?: number
-  /** Stagger between elements (default 0.1). */
-  stagger?: number
-  /** Arrival order (default 'layout' = top-to-bottom, left-to-right). */
-  order?: 'layout' | 'dom' | 'random-ish'
-  /** Soft focus during the approach: brief blur that resolves on landing
-   * (default true; capped well under the 20px ceiling). */
-  soft?: boolean
-  /** Landing overshoot (default 1.02 → 1). `false` disables. */
-  settle?: boolean
-  ease?: string
-}
-
-export function createEnsembleKit(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 dropIn = (
-    targets: string | Element | Element[],
-    opts: DropInOpts = {},
-    position?: Position
-  ): { duration: number } => {
-    const els = resolveTargets(stage, targets, 'dropIn')
-    const s0 = Math.max(1.2, opts.from ?? 3.2)
-    const duration = opts.duration ?? 0.75
-    const stagger = opts.stagger ?? 0.1
-    const ease = opts.ease ?? 'power3.out'
-    const start = at(position)
-    const cx = config.width / 2
-    const cy = config.height / 2
-
-    const entries = els.map((el, i) => {
-      const r = layoutRect(stage, el as HTMLElement)
-      return { el: el as HTMLElement, r, i }
-    })
-    if (opts.order !== 'dom') {
-      if (opts.order === 'random-ish') {
-        // Deterministic shuffle: order by a hash of layout position.
-        entries.sort(
-          (a, b) =>
-            ((a.r.left * 7 + a.r.top * 13) % 97) - ((b.r.left * 7 + b.r.top * 13) % 97)
-        )
-      } else {
-        entries.sort((a, b) => a.r.top - b.r.top || a.r.left - b.r.left)
-      }
-    }
-
-    for (const [order, { el, r }] of entries.entries()) {
-      // Start pose = the element's position if the whole plane were scaled
-      // s0 about the frame center: it sits further out along the radial
-      // direction and s0× larger — i.e., closer to the camera.
-      const ecx = r.left + r.width / 2
-      const ecy = r.top + r.height / 2
-      const x0 = (ecx - cx) * (s0 - 1)
-      const y0 = (ecy - cy) * (s0 - 1)
-      const t = start + order * stagger
-      gsap.set(el, { transformOrigin: '50% 50%' })
-      tl.fromTo(
-        el,
-        { x: x0, y: y0, scale: s0, autoAlpha: 0 },
-        { x: 0, y: 0, scale: opts.settle === false ? 1 : 1.02, autoAlpha: 1, duration, ease, force3D: false },
-        t
-      )
-      if (opts.settle !== false) {
-        tl.to(el, { scale: 1, duration: 0.22, ease: 'promo-soft', force3D: false }, t + duration)
-      }
-      if (opts.soft !== false) {
-        tl.fromTo(
-          el,
-          { filter: 'blur(9px)' },
-          { filter: 'blur(0px)', duration: duration * 0.85, ease: 'power2.out' },
-          t
-        )
-        tl.set(el, { clearProps: 'filter' }, t + duration)
-      }
-    }
-    const total = (entries.length - 1) * stagger + duration + (opts.settle === false ? 0 : 0.22)
-    return { duration: Math.max(0, total) }
-  }
-
-  /** Elements fly in from scattered planar directions and settle into their
-   * exact layout slots. `from`: 'edges' (each from its nearest frame edge),
-   * 'center' (burst outward-in), 'above'. Ends at exact identity. */
-  const assemble = (
-    targets: string | Element | Element[],
-    opts: { from?: 'edges' | 'center' | 'above'; distance?: number; duration?: number; stagger?: number; spin?: number; ease?: string } = {},
-    position?: Position
-  ): { duration: number } => {
-    const els = resolveTargets(stage, targets, 'assemble')
-    const from = opts.from ?? 'edges'
-    const duration = opts.duration ?? 0.7
-    const stagger = opts.stagger ?? 0.07
-    const spin = opts.spin ?? 14
-    const ease = opts.ease ?? 'promo-out'
-    const start = at(position)
-    const cx = config.width / 2
-    const cy = config.height / 2
-    els.forEach((raw, i) => {
-      const el = raw as HTMLElement
-      const r = layoutRect(stage, el)
-      const ecx = r.left + r.width / 2
-      const ecy = r.top + r.height / 2
-      const d = opts.distance ?? Math.max(240, Math.hypot(cx, cy) * 0.5)
-      let dx = 0
-      let dy = 0
-      if (from === 'above') {
-        dx = (hash01(i, 1) - 0.5) * d * 0.5
-        dy = -d
-      } else {
-        // Outward along the radial from frame center (edges) or inward (center).
-        const len = Math.max(1, Math.hypot(ecx - cx, ecy - cy))
-        const sign = from === 'center' ? -1 : 1
-        dx = ((ecx - cx) / len) * d * sign
-        dy = ((ecy - cy) / len) * d * sign
-      }
-      const t = start + i * stagger
-      gsap.set(el, { transformOrigin: '50% 50%' })
-      tl.fromTo(
-        el,
-        { x: dx, y: dy, rotation: (hash01(i, 2) - 0.5) * 2 * spin, autoAlpha: 0 },
-        { x: 0, y: 0, rotation: 0, autoAlpha: 1, duration, ease, force3D: false },
-        t
-      )
-    })
-    return { duration: (els.length - 1) * stagger + duration }
-  }
-
-  /** The inverse of assemble: elements explode outward from their layout
-   * (radially from frame center), fading as they go. They end hidden with
-   * transforms reset, so the layout is clean if re-shown. */
-  const scatter = (
-    targets: string | Element | Element[],
-    opts: { distance?: number; duration?: number; stagger?: number; spin?: number; ease?: string } = {},
-    position?: Position
-  ): { duration: number } => {
-    const els = resolveTargets(stage, targets, 'scatter')
-    const duration = opts.duration ?? 0.6
-    const stagger = opts.stagger ?? 0.05
-    const spin = opts.spin ?? 24
-    const start = at(position)
-    const cx = config.width / 2
-    const cy = config.height / 2
-    els.forEach((raw, i) => {
-      const el = raw as HTMLElement
-      const r = layoutRect(stage, el)
-      const ecx = r.left + r.width / 2
-      const ecy = r.top + r.height / 2
-      const len = Math.max(1, Math.hypot(ecx - cx, ecy - cy))
-      const d = (opts.distance ?? 420) * (0.7 + hash01(i, 3) * 0.6)
-      const t = start + i * stagger
-      gsap.set(el, { transformOrigin: '50% 50%' })
-      tl.to(
-        el,
-        {
-          x: ((ecx - cx) / len) * d,
-          y: ((ecy - cy) / len) * d,
-          rotation: (hash01(i, 4) - 0.5) * 2 * spin,
-          autoAlpha: 0,
-          duration,
-          ease: opts.ease ?? 'promo-in',
-          force3D: false,
-        },
-        t
-      )
-      tl.set(el, { x: 0, y: 0, rotation: 0 }, t + duration)
-    })
-    return { duration: (els.length - 1) * stagger + duration }
-  }
-
-  /** SHOWPIECE. Elements fly BALLISTICALLY through the frame — tossed up and
-   * falling back past the bottom ('up'), raining through ('down'), or
-   * bursting radially from their own position ('burst'). Items EXIT: they
-   * end hidden with transforms reset. Closed-form parabola per item (pure
-   * function of seeked time), spin and velocity varied by index hash.
-   *
-   * WHEN NOT TO USE: on ambient beats. A fountain must be a story payoff —
-   * something launched, generated, or released — and at most one or two
-   * showpieces belong in a whole film. */
-  const fountain = (
-    targets: string | Element | Element[],
-    opts: {
-      direction?: 'up' | 'down' | 'burst'
-      duration?: number
-      stagger?: number
-      gravity?: number
-      power?: number
-      spin?: number
-      ease?: string
-    } = {},
-    position?: Position
-  ): { duration: number } => {
-    const els = resolveTargets(stage, targets, 'fountain')
-    const direction = opts.direction ?? 'up'
-    const duration = opts.duration ?? 2.0
-    const stagger = opts.stagger ?? 0.08
-    const g = opts.gravity ?? 2600
-    const power = opts.power ?? 1
-    const spin = opts.spin ?? 260
-    const start = at(position)
-    const H = config.height
-    els.forEach((raw, i) => {
-      const el = raw as HTMLElement
-      const h1 = hash01(i, 5)
-      const h2 = hash01(i, 6)
-      const h3 = hash01(i, 7)
-      const vx = (h1 - 0.5) * 900 * power
-      const vy =
-        direction === 'down'
-          ? 200 + h2 * 300
-          : direction === 'burst'
-            ? -(600 + h2 * 900) * power
-            : -(1400 + h2 * 900) * power
-      const w = (h3 - 0.5) * 2 * spin
-      const t0 = start + i * stagger
-      gsap.set(el, { transformOrigin: '50% 50%' })
-      const proxy = { t: 0 }
-      tl.set(el, { autoAlpha: 1 }, t0)
-      tl.to(
-        proxy,
-        {
-          t: duration,
-          duration,
-          ease: 'none',
-          onUpdate: () => {
-            const t = proxy.t
-            gsap.set(el, {
-              x: vx * t,
-              y: vy * t + 0.5 * g * t * t + (direction === 'down' ? -H * 0.2 : 0),
-              rotation: w * t,
-              force3D: false,
-            })
-          },
-        },
-        t0
-      )
-      // Items exit; leave the layout clean behind them.
-      tl.set(el, { autoAlpha: 0, x: 0, y: 0, rotation: 0 }, t0 + duration)
-    })
-    return { duration: (els.length - 1) * stagger + duration }
-  }
-
-  /** SHOWPIECE. A generated celebration burst — no authored elements needed:
-   * particles are created, fly ballistically with spin and flutter, fade,
-   * and the whole layer ends hidden. `at` is the origin (element or scene
-   * point); `count` is capped for paint cost.
-   *
-   * WHEN NOT TO USE: anywhere except a genuine payoff beat (shipped,
-   * delivered, launched, won). One confetti per film, maximum. */
-  const confetti = (
-    opts: {
-      at?: string | Element | { x: number; y: number }
-      count?: number
-      palette?: string[]
-      power?: number
-      spread?: number
-      duration?: number
-      size?: number
-    } = {},
-    position?: Position
-  ): { duration: number } => {
-    const count = Math.min(160, opts.count ?? 90)
-    const palette = opts.palette ?? ['#2f6bff', '#7c5cff', '#ff8a5c', '#ffd166', '#06d6a0', '#ef476f']
-    const duration = opts.duration ?? 2.4
-    const power = opts.power ?? 1
-    const spreadDeg = opts.spread ?? 70
-    const start = at(position)
-    let ox = config.width / 2
-    let oy = config.height * 0.6
-    if (opts.at && typeof opts.at === 'object' && !(opts.at instanceof Element) && 'x' in opts.at) {
-      ox = opts.at.x
-      oy = opts.at.y
-    } else if (opts.at) {
-      const el = resolveTargets(stage, opts.at as string | Element, 'confetti')[0] as HTMLElement
-      const r = layoutRect(stage, el)
-      ox = r.left + r.width / 2
-      oy = r.top + r.height / 2
-    }
-    const layer = document.createElement('div')
-    layer.dataset.confetti = ''
-    layer.style.cssText = `position:absolute;left:0;top:0;width:0;height:0;pointer-events:none;z-index:70;visibility:hidden;`
-    stage.appendChild(layer)
-    type P = { el: HTMLElement; vx: number; vy: number; w: number; flutter: number; phase: number; delay: number }
-    const parts: P[] = []
-    for (let i = 0; i < count; i += 1) {
-      const p = document.createElement('div')
-      const s = (opts.size ?? 12) * (0.6 + hash01(i, 8) * 0.9)
-      p.style.cssText =
-        `position:absolute;left:${ox}px;top:${oy}px;width:${s}px;height:${s * (0.5 + hash01(i, 9) * 0.7)}px;` +
-        `border-radius:2px;background:${palette[i % palette.length]};will-change:transform;`
-      layer.appendChild(p)
-      const ang = ((hash01(i, 10) - 0.5) * 2 * spreadDeg * Math.PI) / 180
-      const speed = (900 + hash01(i, 11) * 1100) * power
-      parts.push({
-        el: p,
-        vx: Math.sin(ang) * speed,
-        vy: -Math.cos(ang) * speed,
-        w: (hash01(i, 12) - 0.5) * 1400,
-        flutter: 20 + hash01(i, 13) * 50,
-        phase: hash01(i, 14) * Math.PI * 2,
-        delay: hash01(i, 15) * 0.12,
-      })
-    }
-    const g = 2200
-    tl.set(layer, { visibility: 'visible' }, start)
-    const proxy = { t: 0 }
-    tl.to(
-      proxy,
-      {
-        t: duration,
-        duration,
-        ease: 'none',
-        onUpdate: () => {
-          const T = proxy.t
-          for (const p of parts) {
-            const t = Math.max(0, T - p.delay)
-            const fade = Math.max(0, Math.min(1, (duration - 0.35 - t) / 0.5 + 1))
-            gsap.set(p.el, {
-              x: p.vx * t + Math.sin(p.phase + t * 9) * p.flutter * t,
-              y: p.vy * t + 0.5 * g * t * t,
-              rotation: p.w * t,
-              opacity: t > 0 ? Math.min(1, fade) : 0,
-              force3D: false,
-            })
-          }
-        },
-      },
-      start
-    )
-    tl.set(layer, { visibility: 'hidden' }, start + duration)
-    return { duration }
-  }
-
-  /** A continuous belt of items scrolling through a clipped viewport — the
-   * gallery-scroll (Dash's file reels, Apple's tile river). The container's
-   * children are duplicated once for a seamless wrap and the row translates
-   * linearly; it ends reset to the authored position. Author the row inside
-   * an overflow:hidden viewport.
-   *
-   * WHEN NOT TO USE: as ambient filler behind a reading beat — a river IS a
-   * showcase beat (logos, covers, generated results). */
-  const river = (
-    container: string | Element,
-    opts: { speed?: number; direction?: 'left' | 'right'; duration?: number } = {},
-    position?: Position
-  ): { duration: number } => {
-    const el = resolveTargets(stage, container, 'river')[0] as HTMLElement
-    const duration = opts.duration ?? 6
-    const speed = opts.speed ?? 140
-    const dir = opts.direction === 'right' ? 1 : -1
-    const start = at(position)
-    const kids = Array.from(el.children) as HTMLElement[]
-    const gapPx = parseFloat(getComputedStyle(el).columnGap) || 0
-    // One full period = authored content + the seam gap; translating by
-    // exactly this shows identical pixels, so the wrap is invisible.
-    const loop = el.scrollWidth + gapPx
-    for (const k of kids) el.appendChild(k.cloneNode(true))
-    const proxy = { t: 0 }
-    tl.to(
-      proxy,
-      {
-        t: duration,
-        duration,
-        ease: 'none',
-        onUpdate: () => {
-          const travel = (proxy.t * speed) % loop
-          // Leftward belts reveal their right edge (where the clone sits);
-          // rightward belts reveal their LEFT edge, so start one period back.
-          gsap.set(el, { x: dir < 0 ? -travel : -loop + travel, force3D: false })
-        },
-      },
-      start
-    )
-    tl.set(el, { x: 0 }, start + duration)
-    return { duration }
-  }
-
-  /** Bento reflow: tiles in ONE grid continuously trade space — spans change
-   * state to state and every tile FLIPs (measured, exact) to its new slot,
-   * so the grid stays filled while its cells resize around each other.
-   * Author a CSS grid container (grid-auto-flow: dense recommended); state 0
-   * is the authored layout and the cycle ends exactly back on it. States are
-   * generated deterministically from index hashes. */
-  const bento = (
-    container: string | Element,
-    opts: { states?: number; interval?: number; duration?: number; ease?: string } = {},
-    position?: Position
-  ): { duration: number } => {
-    const el = resolveTargets(stage, container, 'bento')[0] as HTMLElement
-    const tiles = Array.from(el.children) as HTMLElement[]
-    const nStates = Math.max(2, opts.states ?? 4)
-    const interval = opts.interval ?? 1.6
-    const flip = Math.min(opts.duration ?? 0.7, interval)
-    const ease = opts.ease ?? 'promo-inout'
-    const start = at(position)
-    const spansFor = (s: number, i: number): [number, number] =>
-      s === 0
-        ? [1, 1]
-        : [1 + (hash01(i, s * 3 + 1) < 0.28 ? 1 : 0), 1 + (hash01(i, s * 3 + 2) < 0.22 ? 1 : 0)]
-    // Boxes RESIZE (width/height tweens), never scale — scaling squashes the
-    // tile's content (stretched labels). Border-box so measured rects map
-    // straight onto the tweened dimensions.
-    tiles.forEach((tile) => {
-      tile.style.boxSizing = 'border-box'
-    })
-    const apply = (s: number) => {
-      tiles.forEach((tile, i) => {
-        const [w, h] = spansFor(s, i)
-        tile.style.gridColumn = `span ${w}`
-        tile.style.gridRow = `span ${h}`
-      })
-    }
-    // Measure every state's true rects at build time, then restore.
-    const states: Array<Array<{ left: number; top: number; width: number; height: number }>> = []
-    for (let s = 0; s < nStates; s += 1) {
-      apply(s)
-      states.push(tiles.map((tile) => layoutRect(stage, tile)))
-    }
-    apply(0)
-    for (let s = 1; s <= nStates; s += 1) {
-      const to = s % nStates
-      const from = s - 1
-      const t0 = start + s * interval
-      tiles.forEach((tile, i) => {
-        const a = states[from][i]
-        const b = states[to][i]
-        const [w, h] = spansFor(to, i)
-        tl.set(tile, { gridColumn: `span ${w}`, gridRow: `span ${h}` }, t0)
-        tl.fromTo(
-          tile,
-          { x: a.left - b.left, y: a.top - b.top, width: a.width, height: a.height },
-          { x: 0, y: 0, width: b.width, height: b.height, duration: flip, ease, immediateRender: false },
-          t0
-        )
-        // Hand sizing back to the grid once the box has arrived.
-        tl.set(tile, { clearProps: 'width,height' }, t0 + flip)
-      })
-    }
-    return { duration: nStates * interval + flip }
-  }
-
-  return { dropIn, assemble, scatter, fountain, confetti, river, bento }
-}