@llui/transitions

Animation helpers for LLui structural primitives. Works with show, branch, and each.

pnpm add @llui/transitions

Usage

import { fade, slide, mergeTransitions } from '@llui/transitions'
import { div } from '@llui/dom'

// Fade + slide on a show block
view({ show, text }) {
  show({
    when: (s) => s.visible,
    render: () => div({}, text((s) => s.message)),
    ...mergeTransitions(fade(), slide({ direction: 'down' })),
  })
}

API

Core

| Function | Description | | ------------------------------ | ------------------------------------------------------- | | transition({ enter, leave }) | Core transition -- define custom enter/leave animations | | mergeTransitions(a, b) | Combine two transitions into one |

Presets

| Function | Options | Description | | -------------------- | --------------------------------- | ---------------------------------------------------- | | fade(options?) | duration, easing | Fade in/out | | slide(options?) | direction, duration, easing | Slide from direction (up, down, left, right) | | scale(options?) | from, duration, easing | Scale transform in/out | | collapse(options?) | duration, easing | Height collapse/expand | | flip(options?) | duration, easing | FLIP reorder animation for each() |

Spring Physics

| Function | Options | Description | | ------------------ | --------------------------------------------------------------------- | -------------------------------- | | spring(options?) | stiffness, damping, mass, precision, property, from, to | Spring-physics animation via rAF |

Uses a damped spring simulation instead of CSS easing. The animation runs via requestAnimationFrame and settles naturally based on physics parameters.

import { spring } from '@llui/transitions'

// Default: opacity 0 → 1 with react-spring-like defaults
show({ when: (s) => s.open, render: () => content(), ...spring() })

// Custom spring feel
show({
  when: (s) => s.open,
  render: () => content(),
  ...spring({ stiffness: 300, damping: 15, property: 'opacity' }),
})

Route Transitions

| Function | Options | Description | | --------------------------- | ---------------------------------------------- | -------------------------------------------- | | routeTransition(options?) | duration, easing, slide, slideDistance | Fade + slide for branch() page transitions |

Convenience wrapper for animating page transitions in a branch():

import { routeTransition, fade } from '@llui/transitions'

// Default: fade + slight upward slide (250ms)
branch({
  on: (s) => s.route.page,
  cases: { home: () => [...], about: () => [...] },
  ...routeTransition(),
})

// Custom duration
branch({ on, cases, ...routeTransition({ duration: 200 }) })

// Fade only (no slide)
branch({ on, cases, ...routeTransition({ duration: 200, slide: false }) })

// Pass any preset directly
branch({ on, cases, ...routeTransition(fade({ duration: 200 })) })

Stagger

| Function | Options | Description | | ------------------------------- | ---------------------------- | ------------------------------------------------- | | stagger(transition, options?) | delayPerItem, leaveOrder | Stagger enter/leave animations for each() items |

Wraps any transition preset so batch-entered items animate with incremental delays:

import { stagger, fade, slide } from '@llui/transitions'

each({
  items: (s) => s.items,
  key: (i) => i.id,
  render: ({ item }) => [...],
  ...stagger(fade({ duration: 150 }), { delayPerItem: 30 }),
})

// Works with any preset
each({
  items: (s) => s.items,
  key: (i) => i.id,
  render: ({ item }) => [...],
  ...stagger(slide({ direction: 'up' }), { delayPerItem: 50 }),
})

// Stagger leave animations too (default is simultaneous)
each({
  ...stagger(fade(), { delayPerItem: 30, leaveOrder: 'sequential' }),
})

Items entering within the same microtask are considered a "batch" and get sequential delays. The counter resets after the microtask boundary, so the next batch starts from index 0.

Integration

Presets return { enter, leave } objects that spread directly into show, branch, or each:

// show with fade
show({ when: (s) => s.open, render: () => content(), ...fade() })

// each with FLIP reorder
each({
  items: (s) => s.list,
  key: (item) => item.id,
  render: (item) =>
    li(
      {},
      text(() => item.name),
    ),
  ...flip({ duration: 200 }),
})

License

MIT