@remix-run/ui 0.1.1 → 0.2.0

package/src/animation/README.md

@@ -0,0 +1,316 @@
+# animation
+
+`animation` provides small primitives for entrance, exit, layout, spring, and tween animation. Use these helpers with Remix UI mixins, CSS transitions, the Web Animations API, and imperative `requestAnimationFrame` loops.
+
+## Usage
+
+```tsx
+import { animateEntrance, animateExit, animateLayout, spring } from 'remix/ui/animation'
+
+let panelTransition = spring.transition(['opacity', 'transform'], 'snappy')
+
+function Panel() {
+  return () => (
+    <div
+      style={{ transition: panelTransition }}
+      mix={[
+        animateEntrance({ opacity: 0, duration: 120 }),
+        animateExit({ opacity: 0, duration: 120 }),
+        animateLayout(),
+      ]}
+    >
+      Saved filters
+    </div>
+  )
+}
+```
+
+## Entrance And Exit
+
+`animateEntrance` animates an element from the provided keyframe into its natural styles when the element is inserted.
+
+```tsx
+import { animateEntrance, spring } from 'remix/ui/animation'
+
+function Toast() {
+  return () => (
+    <div
+      mix={[
+        animateEntrance({
+          opacity: 0,
+          transform: 'translateY(8px)',
+          ...spring('snappy'),
+        }),
+      ]}
+    >
+      Saved
+    </div>
+  )
+}
+```
+
+`animateExit` keeps a removed keyed element in the DOM long enough to animate from its natural styles to the provided keyframe.
+
+```tsx
+import type { Handle } from 'remix/ui'
+import { animateExit } from 'remix/ui/animation'
+
+function Item(handle: Handle<{ id: string; label: string }>) {
+  return () => (
+    <li
+      key={handle.props.id}
+      mix={[
+        animateExit({
+          opacity: 0,
+          transform: 'scale(0.96)',
+          duration: 120,
+          easing: 'ease-in',
+        }),
+      ]}
+    >
+      {handle.props.label}
+    </li>
+  )
+}
+```
+
+Passing `true` uses the default opacity animation. Passing `false`, `null`, or `undefined` disables the animation.
+
+```tsx
+<div mix={[animateEntrance(true), animateExit(false)]} />
+```
+
+Animation configs combine WAAPI timing options with style properties for the animated keyframe.
+
+```ts
+type AnimateMixinConfig = {
+  duration: number
+  easing?: string
+  delay?: number
+  composite?: CompositeOperation
+  initial?: boolean
+  [property: string]: unknown
+}
+```
+
+Pass `initial: false` to skip only the first keyed entrance for an element within a parent. Later insertions for the same key can still animate.
+
+```tsx
+<div key={id} mix={[animateEntrance({ opacity: 0, duration: 150, initial: false })]} />
+```
+
+Exit animations can reclaim a removed keyed node if the same keyed element is rendered again before the exit finishes. The reclaimed node retargets toward its natural styles instead of simply reversing the exit animation.
+
+## Layout Animation
+
+`animateLayout` animates layout changes with a FLIP-style transform projection. Use it on elements whose position or size can change between renders.
+
+```tsx
+import type { Handle } from 'remix/ui'
+import { animateLayout, spring } from 'remix/ui/animation'
+
+function Card(handle: Handle<{ expanded: boolean }>) {
+  return () => (
+    <section
+      class={handle.props.expanded ? 'card expanded' : 'card'}
+      mix={[
+        animateLayout({
+          ...spring('smooth'),
+        }),
+      ]}
+    >
+      Details
+    </section>
+  )
+}
+```
+
+Pass `size: false` when the element should animate position only and avoid scale projection.
+
+```tsx
+<div mix={[animateLayout({ duration: 180, easing: 'ease-out', size: false })]} />
+```
+
+Passing `true` or no argument enables the default layout animation. Passing `false`, `null`, or `undefined` disables it. Layout animation skips work when geometry does not change, keeps in-flight animations running when their target geometry has not changed, and continues from the current visual transform when a new layout change interrupts an active animation.
+
+## Spring
+
+`spring` returns a decorated iterator. It can be iterated for JavaScript animation, spread into Web Animations API options, or stringified for CSS transition syntax.
+
+```tsx
+import { spring } from 'remix/ui/animation'
+
+spring('bouncy')
+spring('snappy')
+spring('smooth')
+spring({ duration: 400, bounce: 0.3 })
+```
+
+```ts
+interface SpringIterator extends IterableIterator<number> {
+  duration: number
+  easing: string
+  toString(): string
+}
+```
+
+Use `spring.transition` to build CSS transition entries.
+
+```tsx
+let transition = spring.transition(['opacity', 'transform'], 'bouncy')
+
+function Button() {
+  return () => <button style={{ transition }}>Save</button>
+}
+```
+
+Spread a spring into animation mixin or WAAPI options.
+
+```tsx
+<div
+  mix={[
+    animateEntrance({
+      opacity: 0,
+      transform: 'scale(0.92)',
+      ...spring('bouncy'),
+    }),
+  ]}
+/>
+```
+
+```ts
+element.animate(
+  [
+    { opacity: 0, transform: 'scale(0.92)' },
+    { opacity: 1, transform: 'scale(1)' },
+  ],
+  { ...spring('snappy') },
+)
+```
+
+Use the iterator values as progress from `0` to `1` for imperative animation.
+
+```ts
+let from = 0
+let to = 200
+
+for (let progress of spring('bouncy')) {
+  let x = from + (to - from) * progress
+  element.style.transform = `translateX(${x}px)`
+  await nextFrame()
+}
+```
+
+The built-in presets are:
+
+| Preset   | Bounce | Duration | Character                |
+| -------- | ------ | -------- | ------------------------ |
+| `smooth` | -0.3   | 400ms    | Overdamped, no overshoot |
+| `snappy` | 0      | 200ms    | Quick, no overshoot      |
+| `bouncy` | 0.3    | 400ms    | Underdamped bounce       |
+
+Override preset duration or velocity with the second argument.
+
+```ts
+spring('bouncy', { duration: 300 })
+spring('snappy', { velocity: 2 })
+```
+
+Use explicit options when you need full control.
+
+```ts
+spring({
+  duration: 500,
+  bounce: 0.35,
+  velocity: 0,
+})
+```
+
+## Tween
+
+`tween` creates a generator that interpolates a numeric value over time with a cubic-bezier curve. Call `next()` once to initialize the generator, then pass `requestAnimationFrame` timestamps into `next(timestamp)`.
+
+```ts
+import { easings, tween } from 'remix/ui/animation'
+
+let animation = tween({
+  from: 0,
+  to: 100,
+  duration: 300,
+  curve: easings.easeOut,
+})
+
+animation.next()
+
+function tick(timestamp: number) {
+  let { value, done } = animation.next(timestamp)
+  element.style.transform = `translateX(${value}px)`
+  if (!done) requestAnimationFrame(tick)
+}
+
+requestAnimationFrame(tick)
+```
+
+Animate multiple values with separate tweens.
+
+```ts
+let xAnimation = tween({ from: 0, to: 100, duration: 500, curve: easings.easeOut })
+let scaleAnimation = tween({ from: 1, to: 1.2, duration: 500, curve: easings.easeOut })
+
+xAnimation.next()
+scaleAnimation.next()
+
+function tick(timestamp: number) {
+  let x = xAnimation.next(timestamp)
+  let scale = scaleAnimation.next(timestamp)
+
+  element.style.transform = `translateX(${x.value}px) scale(${scale.value})`
+
+  if (!x.done || !scale.done) {
+    requestAnimationFrame(tick)
+  }
+}
+```
+
+The built-in easing presets are cubic-bezier control points matching common CSS timing functions.
+
+```ts
+easings.linear
+easings.ease
+easings.easeIn
+easings.easeOut
+easings.easeInOut
+```
+
+Custom curves use the same control points as CSS `cubic-bezier(x1, y1, x2, y2)`.
+
+```ts
+let animation = tween({
+  from: 0,
+  to: 100,
+  duration: 500,
+  curve: { x1: 0.68, y1: -0.55, x2: 0.265, y2: 1.55 },
+})
+```
+
+## API
+
+- `animateEntrance(config?)`: mixin that animates an element when it enters the DOM.
+- `animateExit(config?)`: mixin that persists a removed keyed element long enough to run its exit animation.
+- `animateLayout(config?)`: mixin that animates layout changes by comparing geometry between renders.
+- `spring(preset?, overrides?)`: creates a `SpringIterator` from a named preset.
+- `spring(options?)`: creates a `SpringIterator` from explicit spring options.
+- `spring.transition(property, presetOrOptions?, overrides?)`: builds one or more CSS transition entries from a spring.
+- `spring.presets`: named `smooth`, `snappy`, and `bouncy` spring defaults.
+- `tween(options)`: generator that interpolates numeric values over time with a cubic-bezier curve.
+- `easings`: common cubic-bezier presets for `tween`.
+- `SpringIterator`, `SpringPreset`, `SpringOptions`, `TweenOptions`, and `BezierCurve`: public TypeScript types for spring and tween configuration.
+
+## Behavior Notes
+
+- Animation mixin style properties are copied into WAAPI keyframes; `duration`, `easing`, `delay`, `composite`, and `initial` are treated as options.
+- `animateEntrance({ initial: false })` only skips the first keyed entrance tracked for the parent node.
+- `animateExit` needs keyed elements when removed nodes may be reclaimed or persisted across list updates.
+- `animateLayout({ size: false })` animates translation without scale projection.
+- `spring()` yields progress values from `0` to `1`; its `duration` and `easing` properties are enumerable so `{ ...spring() }` works with WAAPI options.
+- `tween(...)` yields the initial value first; advance the generator with frame timestamps via `next(timestamp)` and read `done` to detect completion.

package/src/animation/animate-layout-mixin.ts

@@ -60,30 +60,6 @@ function calcBoxDelta(delta: Delta, source: Box, target: Box, layoutConfig: Layo
   calcAxisDelta(delta.y, source.y, target.y, origin)
 }
 
-function mixAxisDelta(output: AxisDelta, delta: AxisDelta, progress: number): void {
-  output.translate = mix(delta.translate, 0, progress)
-  output.scale = mix(delta.scale, 1, progress)
-  output.origin = delta.origin
-  output.originPoint = delta.originPoint
-}
-
-function mixDelta(output: Delta, delta: Delta, progress: number): void {
-  mixAxisDelta(output.x, delta.x, progress)
-  mixAxisDelta(output.y, delta.y, progress)
-}
-
-function copyAxisDeltaInto(target: AxisDelta, source: AxisDelta): void {
-  target.translate = source.translate
-  target.scale = source.scale
-  target.origin = source.origin
-  target.originPoint = source.originPoint
-}
-
-function copyDeltaInto(target: Delta, source: Delta): void {
-  copyAxisDeltaInto(target.x, source.x)
-  copyAxisDeltaInto(target.y, source.y)
-}
-
 function buildProjectionTransform(delta: Delta, layoutConfig: LayoutAnimationConfig): string {
   let transform = ''
   if (delta.x.translate || delta.y.translate) {
@@ -133,23 +109,51 @@ function isVisualDeltaZero(delta: Delta, layoutConfig: LayoutAnimationConfig): b
   )
 }
 
+function isTargetBoxSame(source: Box, target: Box, layoutConfig: LayoutAnimationConfig): boolean {
+  return (
+    isNear(source.x.min, target.x.min, TRANSLATE_PRECISION) &&
+    isNear(source.y.min, target.y.min, TRANSLATE_PRECISION) &&
+    (layoutConfig.size === false ||
+      (isNear(source.x.max, target.x.max, TRANSLATE_PRECISION) &&
+        isNear(source.y.max, target.y.max, TRANSLATE_PRECISION)))
+  )
+}
+
+function measureAnimationTargetBox(
+  node: HTMLElement,
+  animation: Animation,
+  animationEndTime: number,
+): Box {
+  let currentTime = animation.currentTime
+  let wasRunning = animation.playState === 'running'
+
+  animation.currentTime = animationEndTime
+  let box = measureNaturalBox(node)
+  animation.currentTime = currentTime
+
+  if (wasRunning && animation.playState !== 'running') {
+    animation.play()
+  }
+
+  return box
+}
+
 const animateLayoutMixin = createMixin<Element, [config?: LayoutConfig], ElementProps>((handle) => {
   let snapshot: Box | null = null
   let currentConfig: LayoutConfig = true
-  let currentDelta: Delta | null = null
-  let animationProgress = 0
   let animation: Animation | null = null
+  let animationTarget: Box | null = null
+  let animationEndTime = 0
 
-  let scheduleProgressTracking = (duration: number, active: Animation) => {
-    let start = performance.now()
-    let tick = () => {
-      if (animation !== active) return
-      animationProgress = Math.min(1, (performance.now() - start) / duration)
-      if (animationProgress < 1) {
-        requestAnimationFrame(tick)
-      }
-    }
-    requestAnimationFrame(tick)
+  let clearActiveAnimationState = () => {
+    animation = null
+    animationTarget = null
+    animationEndTime = 0
+  }
+
+  let clearLayoutState = () => {
+    clearActiveAnimationState()
+    snapshot = null
   }
 
   let clearProjectionStyles = (node: HTMLElement) => {
@@ -157,33 +161,48 @@ const animateLayoutMixin = createMixin<Element, [config?: LayoutConfig], Element
     node.style.transformOrigin = ''
   }
 
-  let resetAnimation = () => {
-    animation = null
-    currentDelta = null
-    animationProgress = 0
-  }
-
   handle.addEventListener('beforeUpdate', (event) => {
     let layoutConfig = resolveLayoutConfig(currentConfig)
     if (!layoutConfig) return
-    snapshot = measureNaturalBox(event.node as HTMLElement)
+    let htmlNode = event.node as HTMLElement
+    // Capture the live on-screen position so the next animation can pick up
+    // where this one was interrupted if this update changes the target box.
+    if (animation && animation.playState === 'running') {
+      snapshot = rectToBox(htmlNode.getBoundingClientRect())
+    } else {
+      snapshot = measureNaturalBox(htmlNode)
+    }
   })
 
   handle.addEventListener('commit', (event) => {
     let layoutConfig = resolveLayoutConfig(currentConfig)
     let htmlNode = event.node as HTMLElement
-    let latest = measureNaturalBox(htmlNode)
+    let runningAnimation = animation?.playState === 'running' ? animation : null
+    let latest: Box | null = null
+
+    if (runningAnimation && animationTarget && layoutConfig) {
+      latest = measureAnimationTargetBox(htmlNode, runningAnimation, animationEndTime)
+      if (isTargetBoxSame(latest, animationTarget, layoutConfig)) {
+        snapshot = null
+        return
+      }
+    }
+
+    // Defensive cleanup for cases where beforeUpdate didn't run (e.g. the
+    // mixin was just attached, layoutConfig was disabled this render, or an
+    // in-flight animation needs to retarget to a new final box).
+    animation?.cancel()
+    clearActiveAnimationState()
+    clearProjectionStyles(htmlNode)
+    latest ??= measureNaturalBox(htmlNode)
 
     if (!layoutConfig) {
-      animation?.cancel()
-      clearProjectionStyles(htmlNode)
-      resetAnimation()
-      snapshot = latest
+      clearLayoutState()
       return
     }
 
     if (!snapshot) {
-      snapshot = latest
+      snapshot = null
       return
     }
 
@@ -191,26 +210,10 @@ const animateLayoutMixin = createMixin<Element, [config?: LayoutConfig], Element
     calcBoxDelta(targetDelta, latest, snapshot, layoutConfig)
 
     if (isVisualDeltaZero(targetDelta, layoutConfig)) {
-      snapshot = latest
+      snapshot = null
       return
     }
 
-    if (animation && animation.playState === 'running') {
-      animation.cancel()
-      if (currentDelta && animationProgress > 0 && animationProgress < 1) {
-        let visual = createDelta()
-        mixDelta(visual, currentDelta, animationProgress)
-        targetDelta.x.translate += visual.x.translate
-        targetDelta.y.translate += visual.y.translate
-        targetDelta.x.scale *= visual.x.scale
-        targetDelta.y.scale *= visual.y.scale
-      }
-    }
-
-    if (!currentDelta) currentDelta = createDelta()
-    copyDeltaInto(currentDelta, targetDelta)
-    animationProgress = 0
-
     let invert = buildProjectionTransform(targetDelta, layoutConfig)
     let origin = buildTransformOrigin(targetDelta)
     htmlNode.style.transform = invert
@@ -226,21 +229,26 @@ const animateLayoutMixin = createMixin<Element, [config?: LayoutConfig], Element
       { duration, easing, fill: 'forwards' },
     )
     animation = active
-    scheduleProgressTracking(duration, active)
+    animationTarget = latest
+    animationEndTime = duration
+    snapshot = null
     active.finished
       .then(() => {
         if (animation !== active) return
+        // Cancel even though the animation finished naturally. A fill:forwards
+        // animation in 'finished' state remains an effective animation on
+        // transform, which makes commitStyles() throw on the next interrupted
+        // animation because more than one effect targets the same property.
+        active.cancel()
         clearProjectionStyles(htmlNode)
-        resetAnimation()
-        snapshot = rectToBox(htmlNode.getBoundingClientRect())
+        clearLayoutState()
       })
       .catch(() => {})
   })
 
   handle.addEventListener('remove', () => {
     animation?.cancel()
-    resetAnimation()
-    snapshot = null
+    clearLayoutState()
   })
 
   return (config = true) => {

package/src/animation/spring.ts

@@ -38,6 +38,17 @@ export interface SpringIterator extends IterableIterator<number> {
   toString(): string
 }
 
+export interface SpringFunction {
+  (preset: SpringPreset, overrides?: Omit<SpringOptions, 'bounce'>): SpringIterator
+  (options?: SpringOptions): SpringIterator
+  transition(
+    property: string | string[],
+    presetOrOptions?: SpringPreset | SpringOptions,
+    overrides?: Omit<SpringOptions, 'bounce'>,
+  ): string
+  presets: Record<SpringPreset, { duration: number; bounce: number }>
+}
+
 const presets: Record<SpringPreset, { duration: number; bounce: number }> = {
   smooth: { duration: 400, bounce: -0.3 },
   snappy: { duration: 200, bounce: 0 },
@@ -74,7 +85,7 @@ const frameMs = 1000 / 60 // ~16.67ms per frame
  * @param overrides Optional preset overrides.
  * @returns A spring iterator.
  */
-export function spring(
+function createSpring(
   preset: SpringPreset,
   overrides?: Omit<SpringOptions, 'bounce'>,
 ): SpringIterator
@@ -84,8 +95,8 @@ export function spring(
  * @param options Spring parameters.
  * @returns A spring iterator.
  */
-export function spring(options?: SpringOptions): SpringIterator
-export function spring(
+function createSpring(options?: SpringOptions): SpringIterator
+function createSpring(
   presetOrOptions?: SpringPreset | SpringOptions,
   overrides?: Omit<SpringOptions, 'bounce'>,
 ): SpringIterator {
@@ -119,23 +130,24 @@ export function spring(
   return iter as unknown as SpringIterator
 }
 
-// Transition helper for CSS transition property
-spring.transition = function transition(
+function transition(
   property: string | string[],
   presetOrOptions?: SpringPreset | SpringOptions,
   overrides?: Omit<SpringOptions, 'bounce'>,
 ): string {
   let s =
     typeof presetOrOptions === 'string'
-      ? spring(presetOrOptions, overrides)
-      : spring(presetOrOptions)
+      ? createSpring(presetOrOptions, overrides)
+      : createSpring(presetOrOptions)
 
   let properties = Array.isArray(property) ? property : [property]
   return properties.map((p) => `${p} ${s}`).join(', ')
 }
 
-// Access preset defaults
-spring.presets = presets
+export const spring: SpringFunction = Object.assign(createSpring, {
+  transition,
+  presets,
+})
 
 function resolveOptions(
   presetOrOptions?: SpringPreset | SpringOptions,