# Lively Documentation & API Reference

> Lively is a lightweight React animation library featuring automatic layout transitions, morph animations, preset components, and reactive hooks.

## Installation & Imports

```bash
npm install @infinityfx/lively
```

```tsx
// Core components and types
import { Animate, LayoutGroup, Animator, Clip } from '@infinityfx/lively';

// Animation presets
import { TextAnimation, ViewAnimation } from '@infinityfx/lively/presets';

// Reactive hooks
import {
    useAudio,
    useHover,
    useLink,
    useReducedMotion,
    useScroll,
    useSpring,
    useTap,
    useViewport,
    useVisible
} from '@infinityfx/lively/hooks';
```

---

## Core Components

### Animate
The primary animation component. Wraps child elements to control keyframe animations, triggers, staggering, and morphing.

#### Properties
- `children`: `React.ReactNode` — Target elements to animate.
- `animate`: `ClipOptions | Clip` — Keyframes played on mount or bound to reactive AnimationLinks.
- `initial`: `ClipInitials | string` — Initial property values assigned before playback.
- `clips`: `{ [name: string]: ClipOptions | Clip }` — Named animation clips referenced by triggers.
- `triggers`: `AnimateTriggers` — Maps animation clips to reactive trigger values or lifecycle events (e.g. `'mount'`, `'unmount'`).
- `inherit`: `boolean | number` — Inherit animation clips from parent `Animate` components.
- `stagger`: `number` (default `0.07`) — Delay in seconds between staggering child elements.
- `staggerLimit`: `number` (default `10`) — Maximum child elements to stagger before animating remaining elements together.
- `correction`: `CorrectionAlignment | ScaleCorrection` — Scale distortion correction for border-radius and nested elements.
- `transition`: `TransitionOptions | boolean` — Transition config for layout changes or morphing.
- `morph`: `string` — Globally unique ID to enable morphing animations between elements.
- `paused`: `boolean` — Pauses or resumes animation playback.
- `onAnimationEnd`: `(animation?: string) => void` — Callback when an animation finishes.

#### Usage
```tsx
import { Animate } from '@infinityfx/lively';

export default function Page() {
    return (
        <Animate animate={{ opacity: [0, 1] }}>
            <div style={{ width: 100, height: 100, backgroundColor: 'var(--f-clr-primary-100)' }} />
        </Animate>
    );
}
```

---

### LayoutGroup
Utility component enabling child `Animate` elements to animate between layout shifts and play unmount animations.

#### Properties
- `children`: `React.ReactNode` — Child elements wrapped by the layout group.
- `skipInitialMount`: `boolean` (default `false`) — Skip mount animations when `LayoutGroup` first mounts.
- `mode`: `'wait' | 'sync'` (default `'wait'`) — Wait for unmount animations to complete before mounting new elements.
- `ignoreWarnings`: `boolean` — Suppress missing `key` prop warnings.

#### Usage
```tsx
import { Animate, LayoutGroup } from '@infinityfx/lively';
import { useState } from 'react';

export default function Page() {
    const [items, setItems] = useState(['#4f46e5', '#06b6d4']);

    return (
        <LayoutGroup>
            {items.map(color => (
                <Animate
                    key={color}
                    transition
                    animate={{ opacity: [0, 1], scale: [0.8, 1] }}
                    triggers={{ animate: ['mount', { on: 'unmount', reverse: true }] }}
                >
                    <div style={{ width: 140, height: 32, backgroundColor: color }} />
                </Animate>
            ))}
        </LayoutGroup>
    );
}
```

---

## Preset Components

### TextAnimation
Splits text into characters (`'char'`) or words (`'word'`) with staggered entrance animations.

#### Properties
- `children`: `ReactText | ReactText[]` — Direct text string child to animate.
- `duration`: `number` (default `1`) — Total animation duration in seconds.
- `split`: `'char' | 'word'` (default `'char'`) — Text splitting mode.
- `animate`: `ClipOptions | Clip` — Animation properties applied to each split character or word.

#### Usage
```tsx
import { TextAnimation } from '@infinityfx/lively/presets';

export default function Page() {
    return (
        <TextAnimation duration={0.8} animate={{ opacity: [0, 1], y: [16, 0] }}>
            Smooth text animations with Lively!
        </TextAnimation>
    );
}
```

---

### ViewAnimation
Animates an element automatically upon entering or exiting the viewport.

#### Properties
- `children`: `React.ReactElement` — Single child element to observe.
- `enter`: `ClipOptions | Clip` — Enter animation keyframes.
- `exit`: `ClipOptions | Clip` — Exit animation keyframes.
- `maxEnters`: `number` (default `1`) — Max times to trigger enter animation.
- `maxExits`: `number` (default `0`) — Max times to trigger exit animation.

#### Usage
```tsx
import { ViewAnimation } from '@infinityfx/lively/presets';

export default function Page() {
    return (
        <ViewAnimation
            enter={{ opacity: [0, 1], scale: [0.8, 1] }}
            exit={{ opacity: [1, 0], scale: [1, 0.8] }}
        >
            <div style={{ width: 100, height: 100, backgroundColor: 'var(--f-clr-primary-100)' }} />
        </ViewAnimation>
    );
}
```

---

## Reactive Hooks

### useLink
Creates a reactive `AnimationLink` for high-performance updates without triggering React component re-renders. Transformed links must be created by passing a source link to `useLink(sourceLink, transformFn)`.

```tsx
import { Animate } from '@infinityfx/lively';
import { useLink } from '@infinityfx/lively/hooks';

export default function Page() {
    const link = useLink(0);
    const rotate = useLink(link, val => `${val}deg`);

    return (
        <Animate animate={{ rotate }}>
            <div onClick={() => link.set((link.get() + 90) % 360, { duration: 0.4 })}>
                Rotate
            </div>
        </Animate>
    );
}
```

---

### useHover
Tracks element hover state (boolean) to use directly within `<Animate animate={{ ... }}>`.

```tsx
import { Animate } from '@infinityfx/lively';
import { useHover } from '@infinityfx/lively/hooks';

export default function Page() {
    const [ref, hovering] = useHover<HTMLDivElement>();

    return (
        <Animate animate={{ scale: hovering ? 1.1 : 1 }}>
            <div ref={ref} style={{ width: 100, height: 100, backgroundColor: 'var(--f-clr-primary-100)' }}>
                Hover me
            </div>
        </Animate>
    );
}
```

---

### useTap
Tracks element pointerdown state (boolean) to use directly within `<Animate animate={{ ... }}>`.

```tsx
import { Animate } from '@infinityfx/lively';
import { useTap } from '@infinityfx/lively/hooks';

export default function Page() {
    const [ref, tapping] = useTap<HTMLDivElement>();

    return (
        <Animate animate={{ scale: tapping ? 0.92 : 1 }}>
            <div ref={ref} style={{ width: 100, height: 100, backgroundColor: 'var(--f-clr-primary-100)' }}>
                Press me
            </div>
        </Animate>
    );
}
```

---

### useReducedMotion
Returns a boolean for system reduced motion preference, passed to `<Animate paused={prefersReducedMotion}>`.

```tsx
import { Animate } from '@infinityfx/lively';
import { useReducedMotion } from '@infinityfx/lively/hooks';

export default function Page() {
    const prefersReducedMotion = useReducedMotion();

    return (
        <Animate paused={prefersReducedMotion} animate={{ rotate: [0, 360], repeat: Infinity, duration: 2 }}>
            <div style={{ width: 100, height: 100, backgroundColor: 'var(--f-clr-primary-100)' }} />
        </Animate>
    );
}
```

---

### useScroll
Returns an `AnimationLink<{ x: number, y: number }>` for normalized scroll progress.

```tsx
import { useRef } from 'react';
import { Animate } from '@infinityfx/lively';
import { useScroll, useLink } from '@infinityfx/lively/hooks';

export default function Page() {
    const containerRef = useRef<HTMLDivElement>(null);
    const scrollLink = useScroll(containerRef);
    const scale = useLink(scrollLink, val => `${Math.max(val.y, 0.1)} 1`);

    return (
        <div>
            <div ref={containerRef} style={{ height: 120, overflowY: 'scroll' }}>
                <div style={{ height: 360 }} />
            </div>
            <Animate animate={{ scale }}>
                <div style={{ height: 8, width: 200, backgroundColor: 'var(--f-clr-primary-100)' }} />
            </Animate>
        </div>
    );
}
```

---

### useSpring
Physics-driven spring link updated via `spring.set(targetValue)`. Use the `translate` property for spatial movement.

```tsx
import { Animate } from '@infinityfx/lively';
import { useSpring, useLink } from '@infinityfx/lively/hooks';

export default function Page() {
    const spring = useSpring(0, { stiffness: 4, damping: 0.15 });
    const translate = useLink(spring, val => `${val}px 0px`);

    return (
        <Animate animate={{ translate }}>
            <div onClick={() => spring.set(80)} style={{ width: 70, height: 70, backgroundColor: 'var(--f-clr-primary-100)' }}>
                Spring
            </div>
        </Animate>
    );
}
```

---

### useVisible
Returns enter/exit count numbers to drive animation triggers.

```tsx
import { Animate } from '@infinityfx/lively';
import { useVisible } from '@infinityfx/lively/hooks';

export default function Page() {
    const [ref, entered] = useVisible();

    return (
        <Animate triggers={{ animate: [{ on: entered }] }} animate={{ opacity: [0, 1], scale: [0.8, 1] }}>
            <div ref={ref} style={{ width: 100, height: 100, backgroundColor: 'var(--f-clr-primary-100)' }} />
        </Animate>
    );
}
```

---

### useAudio
Returns `[ref, link]` where `link` is an `AnimationLink<number[]>` containing normalized audio frequency spectrum values.

```tsx
import { Animate } from '@infinityfx/lively';
import { useAudio, useLink } from '@infinityfx/lively/hooks';

export default function Page() {
    const [ref, link] = useAudio({ bands: 8 });
    const scale = useLink(link, (vals, i) => `1 ${Math.max(vals[i], 0.08)}`);

    return (
        <div>
            <Animate animate={{ scale }}>
                {new Array(8).fill(0).map((_, i) => (
                    <div key={i} style={{ width: 8, height: 100, backgroundColor: 'var(--f-clr-primary-100)' }} />
                ))}
            </Animate>
            <audio ref={ref} src="/audio/lost-company-22.mp3" controls />
        </div>
    );
}
```

---

### useViewport
Returns `[ref, link]` containing an `AnimationLink<{ x: number, y: number }>` for position ratios relative to the viewport.

```tsx
import { Animate } from '@infinityfx/lively';
import { useViewport, useLink } from '@infinityfx/lively/hooks';

export default function Page() {
    const [ref, link] = useViewport(0.5);
    const rotate = useLink(link, pos => `${(pos.y > 0 && pos.y < 1 ? pos.y : 0) * 360}deg`);

    return (
        <Animate animate={{ rotate }}>
            <div ref={ref} style={{ width: 100, height: 100, backgroundColor: 'var(--f-clr-primary-100)' }} />
        </Animate>
    );
}
```