editor/docs/reference/jsx/keyframes.md
konstantin-paulus 7372c40429 Update documentation references and refactor knowledge handling
- Changed references from `knowledge` to `docs` in README and various files to reflect the new documentation structure.
- Updated `.gitignore` to exclude the `docs` directory instead of `knowledge`.
- Refactored `forge.config.ts` and `main.ts` to utilize the new `docs` directory for staging resources.
- Introduced `stage-docs.mjs` script to manage the staging of documentation files.
- Added new documentation files under `docs/`, including `INSTRUCTIONS.md`, brand guidelines, and design specifications.
- Removed outdated `knowledge` related tests and files to streamline the codebase.
2026-09-11 20:33:57 +02:00

58 lines
4.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Keyframes
A `<keyframeTrack>` animates one prop of the element holding it over the node's local time; its `<keyframe>` children are the values along the way:
```tsx
<image src="stills/photo.jpg" start={0} end={5}>
<keyframeTrack property="x">
<keyframe time={0} value={-400} easing="easeOut" />
<keyframe time={1} value={200} />
</keyframeTrack>
<keyframeTrack property="opacity">
<keyframe time={0} value={0} />
<keyframe time="15f" value={1} />
</keyframeTrack>
</image>
```
| Element | Props | Meaning |
| ------- | ----- | ------- |
| `<keyframeTrack>` | `property` (**required**) | The prop of the holding element it drives, by name. One track per prop. |
| `<keyframe>` | `time` (**required**), `value` (**required**), `easing` | One keyframe: source-local time in any [time format](./timing.md#time-formats), the value at that time (a number, or any CSS color on a `color` track), and the easing into the next keyframe. |
Animatable props (`property`): `x`, `y`, `offsetX`, `offsetY`, `width`, `height`, `rotation`, `scale`, `scaleX`, `scaleY`, `opacity`, `cornerRadius`, `cornerRadiusTopLeft`, `cornerRadiusTopRight`, `cornerRadiusBottomRight`, `cornerRadiusBottomLeft`, `volume`, `color`, `offset`, `blur`, `value`. Whose prop is the track's holder's: a track under a [paint or color stop](./paints.md) animates the paint (`color`, `opacity`, `offset`), and one under a [`<stroke>`, `<shadow>` or `<effect>`](./styles.md) that style's own — `width` is a stroke's line width, `blur`/`offsetX`/`offsetY` a shadow's, `value` an effect's amount. For preset in/out effects (fade, slides, text reveals, ...) use [`<animation>`](./animations.md) instead.
## Semantics
- `time` is **source-local**: `0` is the first frame of the node's **source**, not where the clip sits on the timeline. A keyframe fires when playback reaches that moment of the content, so animation moves with the clip and stays pinned to the same footage when the head is trimmed. On a clip with [`sourceIn`](./timing.md), a keyframe at `time={t}` therefore plays at clip-relative moment `t - sourceIn`; anything meant relative to the clip's first visible frame must be authored at `sourceIn + t`. For an untrimmed clip (and any node without a source) `0` coincides with the clip's start.
```tsx
{/* sourceIn trims 2s off the head, so the clip's first visible frame is source time 2.
The fade over its first half second is authored at 2–2.5, not 0–0.5. */}
<video src="footage/clip.mp4" start={0} sourceIn={2} sourceOut={7}>
<keyframeTrack property="opacity">
<keyframe time={2} value={0} />
<keyframe time={2.5} value={1} />
</keyframeTrack>
</video>
```
- At a [`playbackRate`](./timing.md#playback-rate) other than `1`, keyframe times stay on the source clock: a keyframe lands on the same content frame at any speed, and the animation speeds up or slows down with the footage.
- Keyframes may be written in any order; they sort by `time`. Outside the keyframed range the value holds at the first/last keyframe.
- `easing` shapes the segment from its keyframe to the next; the last keyframe's easing is ignored. Default `"linear"`.
- The prop's static value (`x={10}` on the element) is what holds when the track has no keyframes; while it has any, the track wins.
- Tracks and keyframes are elements like any other: each has an `id`, the editor writes a moved keyframe back to it, and they are copied with their element.
## Easing
| Easing | Use for |
| ------ | ------- |
| `"linear"` (default) | Constant-rate change. |
| `"easeIn"`, `"easeOut"`, `"easeInOut"` | Standard acceleration curves (CSS equivalents). |
| `"gentle"`, `"snappy"`, `"bouncy"`, `"strong"` | Spring presets, from soft settle to hard overshoot. |
| `"cubicBezier(x1,y1,x2,y2)"` | Custom curve, CSS control points. |
| `"spring(bounce,duration)"` | Custom spring: bounce `0`-`1`, duration in ms. |
| `"steps(n)"` | Discrete hold: n equal steps, no interpolation. |
Named presets expand to the same descriptors the editor's interpolation inspector writes, so they round-trip cleanly.