stagger-children

1import {
2  Children,
3  cloneElement,
4  isValidElement,
5  type ReactElement,
6  type ReactNode,
7} from "react";
8import { Sequence, useVideoConfig } from "remotion";
9import {
10  defaultExitFrames,
11  DEFAULT_ENTER_FRAMES,
12  type EnterExitOptions,
13} from "@/remotion/lib/motion-primitive";
14import { staggerDelay } from "@/remotion/lib/timing";
15 
16export type StaggerOrder = "forward" | "reverse" | "center" | "edges";
17 
18export type StaggerChildrenProps = {
19  children: ReactNode;
20  /** Frames between one child starting and the next. */
21  staggerInFrames?: number;
22  /** Frames before the first child starts. */
23  baseDelayInFrames?: number;
24  /**
25   * Which child goes first. `center` runs outwards from the middle, `edges`
26   * runs inwards — both read as one gesture across a row rather than a queue.
27   */
28  order?: StaggerOrder;
29  /**
30   * Frames between one child leaving and the next, in the order they arrived.
31   * Only affects children that animate out; 0 lands the group together.
32   */
33  exitStaggerInFrames?: number;
34};
35 
36/** Position in the run order, 0 = first to start. */
37function rankOf(index: number, count: number, order: StaggerOrder): number {
38  const mid = (count - 1) / 2;
39 
40  switch (order) {
41    case "reverse":
42      return count - 1 - index;
43    case "center":
44      return Math.round(Math.abs(index - mid));
45    case "edges":
46      return Math.round(mid - Math.abs(index - mid));
47    default:
48      return index;
49  }
50}
51 
52/** Host elements would render an unknown attribute; only components take props. */
53function acceptsMotionProps(child: ReactElement): boolean {
54  return typeof child.type !== "string";
55}
56 
57/**
58 * Offsets each child onto its own slot with `<Sequence layout="none">`, so
59 * every child animates from its local frame 0 and needs no delay of its own.
60 *
61 * Inside a bounded window each slot is given an end as well, which is what
62 * lets children with `exit` land out on time. `exitStaggerInFrames` moves each
63 * child's exit earlier instead of shortening its slot — cutting slots short
64 * would unmount children one by one and collapse the layout under them.
65 *
66 * @see skills/remotion/remotion-markup/sequencing.md
67 */
68export const StaggerChildren: React.FC<StaggerChildrenProps> = ({
69  children,
70  staggerInFrames = 8,
71  baseDelayInFrames = 0,
72  order = "forward",
73  exitStaggerInFrames = 0,
74}) => {
75  const { durationInFrames: windowFrames } = useVideoConfig();
76  const items = Children.toArray(children);
77  const bounded = Number.isFinite(windowFrames);
78 
79// … truncated