@impractical-ai/motion 0.1.5 → 0.1.7

package/assets/kits/highlight.ts

@@ -0,0 +1,374 @@
+// ─── Highlight — annotation primitives for pre-existing components ─────────
+//
+// The "look here" vocabulary: rings that draw themselves around an element,
+// hand-drawn circles, highlighter-marker swipes, underlines, glow pulses, and
+// the inverse spotlight (everything EXCEPT the target dims). One call per
+// annotation, one Tweak row, geometry derived from the target (ring padding
+// from element size, marker height from line height), colors overridable per
+// call. Every highlight is STATE with an explicit end: `persist` says how long
+// it holds, `release` says how it leaves — nothing loiters.
+//
+// Overlays are SVG/div siblings appended to the stage (auto-cleaned per
+// rebuild), positioned from the shared authored-layout measurement, so they
+// land correctly even when authored after entrance tweens.
+
+import gsap from 'gsap'
+import { layoutRect, layoutTextRect, visualRect, resolveTarget } from './kits'
+
+export type HighlightRelease = 'fade' | 'undraw' | 'hold'
+
+export type HighlightOpts = {
+  /** Stroke/fill color. Each primitive has its own sensible default. */
+  color?: string
+  /** Draw-on time in seconds. */
+  duration?: number
+  /** Default 'ease-in-out-cubic'. */
+  ease?: string
+  /** Seconds the highlight holds after drawing, or 'hold' to stay to the end.
+   * Default 'hold' — releasing is a deliberate choice. */
+  persist?: number | 'hold'
+  /** How it leaves when persist is a number: 'fade' (default) or 'undraw'. */
+  release?: Exclude<HighlightRelease, 'hold'>
+  /** Extra space around the target in scene px. Default derives from size. */
+  padding?: number
+  /** Stroke thickness in px. */
+  thickness?: number
+  /** What to fit: 'text' hugs the glyphs (a block element's box spans its
+   * full column — a marker on "99.99%" must not swallow the empty half of
+   * the card); 'box' takes the element box. Marker, circle, and underline
+   * default to 'text'; ring, glow, and spotlight default to 'box'. */
+  fit?: 'text' | 'box'
+}
+
+export type SpotlightOpts = {
+  /** How dark the rest of the frame goes (0..1). Default 0.55. */
+  dim?: number
+  /** Defocus everything OUTSIDE the cutout by this many px (the target stays
+   * sharp). 0 (default) dims only. Engine ceiling: 20. */
+  blur?: number
+  /** Gaussian softness of the cutout edge in px. Default 26. */
+  feather?: number
+  /** Breathing room between the element's edge and the cutout, px. Default 16. */
+  padding?: number
+  duration?: number
+  ease?: string
+  persist?: number | 'hold'
+}
+
+export type HighlightKit = {
+  /** Rounded ring draws itself around the element, following its corner
+   * radius. The workhorse product-tour annotation. */
+  ring: (target: string | Element, opts?: HighlightOpts, position?: gsap.Position) => { duration: number }
+  /** Hand-drawn ellipse loop with overshoot — red-pen annotation energy. */
+  circle: (target: string | Element, opts?: HighlightOpts, position?: gsap.Position) => { duration: number }
+  /** Highlighter-pen swipe behind the glyphs: a skewed band wipes across in
+   * multiply blend, sized from the line height. */
+  marker: (target: string | Element, opts?: HighlightOpts, position?: gsap.Position) => { duration: number }
+  /** Underline draw. Styles: 'straight' | 'marker' | 'sketch'. */
+  underline: (
+    target: string | Element,
+    style?: 'straight' | 'marker' | 'sketch',
+    opts?: HighlightOpts,
+    position?: gsap.Position
+  ) => { duration: number }
+  /** One soft glow pulse as a beat lands — light, not opacity. */
+  glow: (target: string | Element, opts?: HighlightOpts, position?: gsap.Position) => { duration: number }
+  /** Inverse move: everything EXCEPT the target dims behind a feathered
+   * cutout. The strongest "look here" in the vocabulary. */
+  spotlight: (target: string | Element, opts?: SpotlightOpts, position?: gsap.Position) => { duration: number }
+}
+
+export type HighlightDeps = {
+  tl: gsap.core.Timeline
+  stage: HTMLElement
+}
+
+const EASE = 'ease-in-out-cubic'
+
+/** Ring padding derived from target size — small chips get tight rings, large
+ * panels get room to breathe. */
+export function autoPadding(rect: { width: number; height: number }): number {
+  const d = Math.min(rect.width, rect.height)
+  return Math.round(Math.min(18, Math.max(6, d * 0.12)))
+}
+
+const NS = 'http://www.w3.org/2000/svg'
+
+export function createHighlightKit(deps: HighlightDeps): HighlightKit {
+  const { tl, stage } = deps
+
+  const rectFor = (
+    target: string | Element,
+    kind: string,
+    fit: 'text' | 'box' = 'box'
+  ) => {
+    const el = resolveTarget(stage, target, kind)
+    return {
+      el,
+      rect: fit === 'text' ? layoutTextRect(stage, el) : layoutRect(stage, el),
+    }
+  }
+
+  const overlaySvg = (
+    left: number,
+    top: number,
+    width: number,
+    height: number,
+    label: string
+  ): SVGSVGElement => {
+    const svg = document.createElementNS(NS, 'svg')
+    svg.setAttribute(`data-highlight-${label}`, '')
+    svg.setAttribute('viewBox', `0 0 ${width} ${height}`)
+    svg.style.cssText = `position:absolute;left:${left}px;top:${top}px;width:${width}px;height:${height}px;pointer-events:none;overflow:visible;z-index:9900;`
+    stage.appendChild(svg)
+    return svg
+  }
+
+  /** Draw-on via dash offset, then apply the persist/release contract. */
+  const drawAndRelease = (
+    strokeEl: SVGElement,
+    host: Element,
+    length: number,
+    opts: HighlightOpts,
+    at: number
+  ): number => {
+    const duration = opts.duration ?? 0.5
+    const ease = opts.ease ?? EASE
+    strokeEl.setAttribute('stroke-dasharray', String(length))
+    strokeEl.setAttribute('stroke-dashoffset', String(length))
+    tl.to(strokeEl, { strokeDashoffset: 0, duration, ease }, at)
+    const persist = opts.persist ?? 'hold'
+    if (persist === 'hold') return duration
+    const releaseAt = at + duration + persist
+    if ((opts.release ?? 'fade') === 'undraw') {
+      tl.to(strokeEl, { strokeDashoffset: -length, duration: duration * 0.8, ease }, releaseAt)
+      return duration + persist + duration * 0.8
+    }
+    tl.to(host, { autoAlpha: 0, duration: 0.25, ease: 'ease-in-quad' }, releaseAt)
+    return duration + persist + 0.25
+  }
+
+  const fadeRelease = (host: Element, opts: { persist?: number | 'hold' }, endOfIn: number): number => {
+    const persist = opts.persist ?? 'hold'
+    if (persist === 'hold') return 0
+    tl.to(host, { autoAlpha: 0, duration: 0.25, ease: 'ease-in-quad' }, endOfIn + persist)
+    return persist + 0.25
+  }
+
+  const at = (position: gsap.Position | undefined): number =>
+    typeof position === 'number' ? position : tl.duration()
+
+  /** Reposition a stage-space overlay from its build-time layout frame to
+   * wherever its target actually sits when the highlight begins — a container
+   * the direction scales mid-timeline has moved the UI off its resting rects
+   * by then. Resolved via function values at render time; uses css box props,
+   * never transforms, so it cannot fight the draw/skew animations. */
+  const syncToTarget = (
+    host: HTMLElement | SVGSVGElement,
+    el: HTMLElement,
+    frame: { left: number; top: number; width: number; height: number },
+    rect: { left: number; top: number; width: number; height: number },
+    position: number
+  ): void => {
+    const map = () => {
+      const v = visualRect(stage, el)
+      const s = rect.width ? v.width / rect.width : 1
+      return {
+        left: v.left + (frame.left - rect.left) * s,
+        top: v.top + (frame.top - rect.top) * s,
+        width: frame.width * s,
+        height: frame.height * s,
+      }
+    }
+    tl.set(
+      host,
+      {
+        left: () => `${map().left}px`,
+        top: () => `${map().top}px`,
+        width: () => `${map().width}px`,
+        height: () => `${map().height}px`,
+      },
+      position
+    )
+  }
+
+  return {
+    ring: (target, opts = {}, position) => {
+      const { el, rect } = rectFor(target, 'highlight.ring')
+      const pad = opts.padding ?? autoPadding(rect)
+      const thickness = opts.thickness ?? 3
+      const w = rect.width + pad * 2
+      const h = rect.height + pad * 2
+      const radius = Math.min(
+        parseFloat(getComputedStyle(el).borderRadius) + pad || 10,
+        Math.min(w, h) / 2
+      )
+      const svg = overlaySvg(rect.left - pad, rect.top - pad, w, h, 'ring')
+      const inset = thickness / 2
+      const r = document.createElementNS(NS, 'rect')
+      r.setAttribute('x', String(inset))
+      r.setAttribute('y', String(inset))
+      r.setAttribute('width', String(w - thickness))
+      r.setAttribute('height', String(h - thickness))
+      r.setAttribute('rx', String(radius))
+      r.setAttribute('fill', 'none')
+      r.setAttribute('stroke', opts.color ?? '#4c8dff')
+      r.setAttribute('stroke-width', String(thickness))
+      r.setAttribute('stroke-linecap', 'round')
+      svg.appendChild(r)
+      const length = r.getTotalLength()
+      const start = at(position)
+      syncToTarget(svg, el, { left: rect.left - pad, top: rect.top - pad, width: w, height: h }, rect, start)
+      return { duration: drawAndRelease(r, svg, length, opts, start) }
+    },
+
+    circle: (target, opts = {}, position) => {
+      const { el, rect } = rectFor(target, 'highlight.circle', opts.fit ?? 'text')
+      const pad = (opts.padding ?? autoPadding(rect)) + 6
+      const w = rect.width + pad * 2
+      const h = rect.height + pad * 2
+      const svg = overlaySvg(rect.left - pad, rect.top - pad, w, h, 'circle')
+      svg.style.transform = 'rotate(-3deg)'
+      const e = document.createElementNS(NS, 'ellipse')
+      e.setAttribute('cx', String(w / 2))
+      e.setAttribute('cy', String(h / 2))
+      e.setAttribute('rx', String(w / 2 - 3))
+      e.setAttribute('ry', String(h / 2 - 3))
+      e.setAttribute('fill', 'none')
+      e.setAttribute('stroke', opts.color ?? '#ff3b30')
+      e.setAttribute('stroke-width', String(opts.thickness ?? 3.5))
+      e.setAttribute('stroke-linecap', 'round')
+      svg.appendChild(e)
+      // 1.15 loops: the pen overshoots past its starting point — the detail
+      // that reads as hand-drawn rather than geometric.
+      const length = e.getTotalLength()
+      const start = at(position)
+      syncToTarget(svg, el, { left: rect.left - pad, top: rect.top - pad, width: w, height: h }, rect, start)
+      const drawn = drawAndRelease(e, svg, length * 1.15, { duration: 0.6, ...opts }, start)
+      return { duration: drawn }
+    },
+
+    marker: (target, opts = {}, position) => {
+      const { el, rect } = rectFor(target, 'highlight.marker', opts.fit ?? 'text')
+      const band = document.createElement('div')
+      band.setAttribute('data-highlight-marker', '')
+      const h = rect.height * 0.72
+      band.style.cssText =
+        `position:absolute;left:${rect.left - 6}px;top:${rect.top + (rect.height - h) / 2}px;` +
+        `width:${rect.width + 14}px;height:${h}px;background:${opts.color ?? '#ffe066'};` +
+        `opacity:0.55;mix-blend-mode:multiply;border-radius:${h * 0.28}px;` +
+        `transform:skewX(-8deg);transform-origin:0 50%;pointer-events:none;z-index:9890;`
+      stage.appendChild(band)
+      const duration = opts.duration ?? 0.45
+      const start = at(position)
+      syncToTarget(
+        band,
+        el,
+        { left: rect.left - 6, top: rect.top + (rect.height - h) / 2, width: rect.width + 14, height: h },
+        rect,
+        start
+      )
+      tl.fromTo(band, { scaleX: 0 }, { scaleX: 1, duration, ease: opts.ease ?? 'ease-out-quart' }, start)
+      const tail = fadeRelease(band, opts, start + duration)
+      return { duration: duration + tail }
+    },
+
+    underline: (target, style = 'sketch', opts = {}, position) => {
+      const { el, rect } = rectFor(target, 'highlight.underline', opts.fit ?? 'text')
+      const thickness = opts.thickness ?? (style === 'marker' ? 7 : 3)
+      const y = rect.top + rect.height + (opts.padding ?? 4)
+      const svg = overlaySvg(rect.left, y, rect.width, thickness * 3, 'underline')
+      const path = document.createElementNS(NS, 'path')
+      const w = rect.width
+      const mid = thickness * 1.5
+      const d =
+        style === 'sketch'
+          ? // A slight double-back wave: the pen presses through and returns.
+            `M2 ${mid} Q ${w * 0.3} ${mid - 3}, ${w * 0.55} ${mid} T ${w - 2} ${mid - 1}`
+          : `M2 ${mid} L ${w - 2} ${mid}`
+      path.setAttribute('d', d)
+      path.setAttribute('fill', 'none')
+      path.setAttribute('stroke', opts.color ?? (style === 'marker' ? '#ffe066' : '#ff3b30'))
+      path.setAttribute('stroke-width', String(thickness))
+      path.setAttribute('stroke-linecap', 'round')
+      if (style === 'marker') {
+        path.style.mixBlendMode = 'multiply'
+        path.style.opacity = '0.6'
+      }
+      svg.appendChild(path)
+      const start = at(position)
+      syncToTarget(svg, el, { left: rect.left, top: y, width: rect.width, height: thickness * 3 }, rect, start)
+      return { duration: drawAndRelease(path, svg, path.getTotalLength(), { duration: 0.4, ...opts }, start) }
+    },
+
+    glow: (target, opts = {}, position) => {
+      const { el, rect } = rectFor(target, 'highlight.glow')
+      const color = opts.color ?? '#ffb020'
+      const duration = opts.duration ?? 0.7
+      const start = at(position)
+      // A shadow-halo overlay, not a filter on the element — so it cannot
+      // clobber an fx chain already driving the element's filter.
+      const halo = document.createElement('div')
+      halo.setAttribute('data-highlight-glow', '')
+      halo.style.cssText =
+        `position:absolute;left:${rect.left}px;top:${rect.top}px;width:${rect.width}px;` +
+        `height:${rect.height}px;border-radius:${getComputedStyle(el).borderRadius || '8px'};` +
+        `box-shadow:0 0 ${Math.max(24, rect.height * 0.5)}px ${color};opacity:0;` +
+        `pointer-events:none;z-index:9880;`
+      stage.appendChild(halo)
+      syncToTarget(halo, el, { left: rect.left, top: rect.top, width: rect.width, height: rect.height }, rect, start)
+      tl.to(halo, { opacity: 0.85, duration: duration / 2, repeat: 1, yoyo: true, ease: 'ease-in-out-quad' }, start)
+      return { duration }
+    },
+
+    spotlight: (target, opts = {}, position) => {
+      const { el, rect } = rectFor(target, 'highlight.spotlight')
+      const dim = opts.dim ?? 0.55
+      const blur = Math.min(20, opts.blur ?? 0)
+      // Legacy fractional feather values map into px so old calls stay sane.
+      const rawFeather = opts.feather ?? 26
+      const feather = rawFeather <= 1 ? rawFeather * 80 : rawFeather
+      const pad = opts.padding ?? 16
+      const duration = opts.duration ?? 0.4
+      const overlay = document.createElement('div')
+      overlay.setAttribute('data-highlight-spotlight', '')
+      // The cutout is the ELEMENT'S OWN SHAPE — a rounded rect at its
+      // border-radius plus breathing room — feathered by a true Gaussian in
+      // an SVG mask. An elliptical gradient cutout protects a huge oval of
+      // background around a rectangular card and shows a visible ring where
+      // the gradient ends; a blurred shape-hugging hole does neither.
+      const sw = stage.offsetWidth
+      const sh = stage.offsetHeight
+      const radius = (parseFloat(getComputedStyle(el).borderRadius) || 12) + pad
+      const hx = (rect.left - pad).toFixed(1)
+      const hy = (rect.top - pad).toFixed(1)
+      const hw = (rect.width + pad * 2).toFixed(1)
+      const hh = (rect.height + pad * 2).toFixed(1)
+      const svg =
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${sw}" height="${sh}">` +
+        `<defs><filter id="f" x="-50%" y="-50%" width="200%" height="200%">` +
+        `<feGaussianBlur stdDeviation="${feather}"/></filter>` +
+        `<mask id="m"><rect width="100%" height="100%" fill="white"/>` +
+        `<rect x="${hx}" y="${hy}" width="${hw}" height="${hh}" rx="${radius}" fill="black" filter="url(#f)"/>` +
+        `</mask></defs>` +
+        `<rect width="100%" height="100%" fill="white" mask="url(#m)"/></svg>`
+      const maskValue = `url("data:image/svg+xml,${encodeURIComponent(svg)}")`
+      // With `blur`, the overlay defocuses what's BEHIND it (backdrop-filter)
+      // outside the cutout — the target stays sharp while its surroundings
+      // fall out of focus, on top of the dim.
+      overlay.style.cssText =
+        `position:absolute;inset:0;background:rgba(8,8,12,${dim});opacity:0;` +
+        `pointer-events:none;z-index:9870;` +
+        (blur > 0 ? `backdrop-filter:blur(${blur}px);-webkit-backdrop-filter:blur(${blur}px);` : '') +
+        `mask-image:${maskValue};-webkit-mask-image:${maskValue};` +
+        `mask-size:100% 100%;-webkit-mask-size:100% 100%;`
+      stage.appendChild(overlay)
+      const start = at(position)
+      tl.to(overlay, { opacity: 1, duration, ease: opts.ease ?? EASE }, start)
+      const persist = opts.persist ?? 'hold'
+      if (persist === 'hold') return { duration }
+      tl.to(overlay, { opacity: 0, duration: 0.3, ease: 'ease-in-quad' }, start + duration + persist)
+      return { duration: duration + persist + 0.3 }
+    },
+  }
+}

package/assets/kits/impact.ts

@@ -0,0 +1,103 @@
+// Impact moves — the "slam": type or a card that hits the frame hard, or
+// tips away out of it.
+//
+// THE RULE THIS KIT EXISTS TO ENFORCE: distortion belongs to MOTION, never to
+// rest. A slam is legible because the element is perspective-turned only while
+// it is travelling too fast to read, and lands (or leaves) undistorted. The
+// failure mode — seen in a shipped film — is an element that POPS into a
+// sheared pose in one frame and then sits there: the viewer reads a broken
+// font, not a moving object. So:
+//   · the big change is the visible travel, not a jump into the end pose
+//   · 'in' ends at exact identity (rotation 0, scale 1) — never mid-turn
+//   · 'away' ends fully invisible, so the turned pose is never a resting one
+//   · pair with ctx.blur() across the fast window: real smear sells the speed
+//     that a 30fps frame cannot show on its own
+//
+// Perspective is applied to the ELEMENT, never the camera-scaled stage
+// (promoting the whole scaled stage to a 3D layer blows Chromium's texture
+// budget — see camera.set).
+import { resolveTargets } from './kits'
+
+type Position = number | string | undefined
+
+export type SlamOpts = {
+  /** 'in' = arrives and lands flat (the impact). 'away' = tips back and
+   * leaves (the hand-off). Default 'in'. */
+  direction?: 'in' | 'away'
+  /** Perspective turn in degrees at the extreme of the move. Default 34. */
+  tilt?: number
+  /** Travel along Y in px. Default 240 ('in' comes from above, 'away' falls). */
+  distance?: number
+  /** Scale at the extreme. Default 1.55 for 'in', 0.86 for 'away'. */
+  scale?: number
+  /** Default 0.34s — a slam is fast; past ~0.5s it stops reading as impact. */
+  duration?: number
+  /** Hinge. Default '50% 100%' (the baseline) so the plane TIPS rather than
+   * spins; use '50% 50%' for a card, '0% 50%' to swing from the left edge. */
+  origin?: string
+  perspective?: number
+  ease?: string
+  /** Stagger when several elements are handed in. Default 0.06. */
+  stagger?: number
+}
+
+export type ImpactKit = {
+  slam: (target: string | Element | Element[], opts?: SlamOpts, position?: Position) => { duration: number }
+}
+
+export function createImpactKit(deps: { tl: any; gsap: any; stage: HTMLElement }): ImpactKit {
+  const { tl, gsap, stage } = deps
+  const at = (position: Position): number => (typeof position === 'number' ? position : tl.duration())
+
+  const slam: ImpactKit['slam'] = (target, opts = {}, position) => {
+    const els = resolveTargets(stage, target, 'slam')
+    const away = opts.direction === 'away'
+    const tilt = opts.tilt ?? 34
+    const distance = opts.distance ?? 240
+    const scale = opts.scale ?? (away ? 0.86 : 1.55)
+    const duration = opts.duration ?? 0.34
+    const origin = opts.origin ?? '50% 100%'
+    const perspective = opts.perspective ?? 900
+    const stagger = opts.stagger ?? 0.06
+    // Entrances land hard (launch-out puts ~80% of the travel in the first
+    // ~20% of the time); exits accelerate away.
+    const ease = opts.ease ?? (away ? 'ease-in-quart' : 'launch-out')
+    const start = at(position)
+
+    els.forEach((raw, i) => {
+      const el = raw as HTMLElement
+      const t = start + i * stagger
+      gsap.set(el, { transformOrigin: origin, transformPerspective: perspective })
+      if (away) {
+        tl.to(
+          el,
+          {
+            rotationX: -tilt,
+            y: distance,
+            scale,
+            autoAlpha: 0,
+            duration,
+            ease,
+            force3D: false,
+          },
+          t
+        )
+        // Ends fully gone AND reset: the turned pose is never a resting one,
+        // and a cold-seeking export worker lands on a clean state.
+        tl.set(el, { rotationX: 0, y: 0, scale: 1, autoAlpha: 0 }, t + duration)
+      } else {
+        tl.fromTo(
+          el,
+          { rotationX: tilt, y: -distance, scale, autoAlpha: 0 },
+          { rotationX: 0, y: 0, scale: 1, autoAlpha: 1, duration, ease, force3D: false },
+          t
+        )
+        // Exact identity at the landing frame.
+        tl.set(el, { rotationX: 0, y: 0, scale: 1 }, t + duration)
+      }
+    })
+    return { duration: (els.length - 1) * stagger + duration }
+  }
+
+  return { slam }
+}