# Pop (pop)

> Spring entrances for Remotion: Pop slides or scales one block in, Stagger cascades a list, and Leave fades a block out.

- Entry: component
- Category: Motion
- Preview capabilities: replay, player
- Runtime: Remotion
- Needs Remotion: yes
- QA page: https://jbm-ui.bns.studio/c/pop
- JSON: https://jbm-ui.bns.studio/catalog/pop.json
- Registry item: https://jbm-ui.bns.studio/r/pop.json (source code in files[].content)

## Install

```sh
npx shadcn@latest add @jbm/pop
```

Also installs @jbm/motion-hooks (registry dependencies install automatically).

## Required setup

1. Add the `@jbm` registry to components.json (keep any entries already there):

   ```json
   {
     "registries": {
       "@jbm": "https://jbm-ui.bns.studio/r/{name}.json"
     }
   }
   ```

2. Map `@/*` to `./src/*` in tsconfig.json `compilerOptions.paths`, so `@/jbm/…` imports resolve to src/jbm/.
3. Install `remotion` and render inside a Remotion `<Composition>` or `<Player>`, not a plain React tree. Timing values are in seconds.

## Files

Each file's source code is in the registry item JSON (https://jbm-ui.bns.studio/r/pop.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/motion/pop.tsx` | `src/jbm/motion/pop.tsx` | `@/jbm/motion/pop` |

## API

### `Pop` (component)

Wraps children in a div whose opacity follows a useIn spring from `at`, while it translates in from one side by `dist` or scales from 0.6 to 1.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `at` | `number` | required | Entrance start in seconds relative to the enclosing Sequence. |
| `children` | `React.ReactNode` | required | Content to reveal. |
| `style` | `React.CSSProperties` | none | Inline styles merged onto the wrapper (after opacity and transform, so a transform here replaces the motion). |
| `from` | `"up" \| "down" \| "left" \| "right" \| "scale"` | `"up"` | Entrance direction: `up` rises from below, `down` drops from above, `left`/`right` slide in from that side, `scale` grows from 0.6×. |
| `dist` | `number` | `40` | Travel distance in stage pixels for the directional entrances; ignored by `scale`. |

### `Stagger` (component)

Wraps each child in a Pop; child i enters at `at + i × step` seconds.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `at` | `number` | required | Start of the first child, in seconds relative to the enclosing Sequence. |
| `step` | `number` | `0.3` | Seconds between consecutive children. |
| `from` | `"up" \| "down" \| "left" \| "right" \| "scale"` | `"up"` | Entrance direction applied to every child (see Pop). |
| `dist` | `number` | `14` | Travel distance in stage pixels for every child. |
| `children` | `React.ReactNode[]` | required | Array of children to cascade; each becomes its own Pop wrapper. |

### `Leave` (component)

Exit: from `at`, the wrapper fades out with cubic-out easing and drifts up by `dist` over 0.4 s, keeping its layout space.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `at` | `number` | required | Exit start in seconds relative to the enclosing Sequence. |
| `children` | `React.ReactNode` | required | Content that leaves. |
| `style` | `React.CSSProperties` | none | Inline styles merged onto the wrapper (after opacity and transform). |
| `dist` | `number` | `30` | Upward drift in stage pixels at the end of the exit. |

## Stage

fluid: Each wrapper is a plain block div sized by its children; Pop, Stagger, and Leave add no box of their own. Translations and scale do not change layout size, so reserve room for `dist` travel near the safe-area edge.

## Examples

### Cascade chips

```tsx
import { Stagger } from "@/jbm/motion/pop"
import { Chip } from "@/jbm/ui/chip" // install @jbm/chip separately

<Stagger at={0.2} step={0.35}>
  {["Idea", "Datos"].map(text => <Chip key={text}>{text}</Chip>)}
</Stagger>
```

### Enter, then leave before the scene ends

```tsx
import { Pop, Leave } from "@/jbm/motion/pop"

<Leave at={3}>
  <Pop at={0.4} from="left" dist={60}>
    <h2>Primero esto.</h2>
  </Pop>
</Leave>
// Render inside a Remotion <Composition> or <Player>.
```

## QA

- Step through the first frame (children invisible), mid-cascade (earlier children settled, later ones entering), and the last frame (all fully opaque at rest).
- Try each `from` value: directional entrances move by `dist` and settle at 0 offset; `scale` grows without translating.
- Check the spring overshoot does not push content past the safe area, especially with large `dist` values in vertical.
- For Leave, confirm the block is fully transparent 0.4 s after `at` and its layout space remains.

## Gallery preview cues

Cue times are seconds on the gallery preview's timeline, which renders the demo below; the Usage examples may use other timings. Map a cue to your own props by its place in the demo. The preview runs at 30 fps for 46 frames (0–45); see them side by side at https://jbm-ui.bns.studio/c/pop?view=strip, or open one frame with ?frame=<frame>.

```tsx
<Stagger at={0.2} step={0.35} from="scale">
  <Chip>Idea</Chip>
  <Chip>Datos</Chip>
  <Chip>Historia</Chip>
</Stagger>
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Empty stage |  |
| 15 | 0.50 | First chip lands | “Idea” has scaled in; “Datos” is just starting. |
| 27 | 0.90 | Second chip lands | “Datos” is nearly settled and “Historia” starts to scale in. |
| 45 | 1.50 | End |  |

## Related

Installs:

- [MotionHooks (motion-hooks)](https://jbm-ui.bns.studio/catalog/motion-hooks.md)

Installed by:

- [ProbBar (prob-bar)](https://jbm-ui.bns.studio/catalog/prob-bar.md)
- [RebuildScreens (rebuild-screens)](https://jbm-ui.bns.studio/catalog/rebuild-screens.md)
- [Catalog (catalog)](https://jbm-ui.bns.studio/catalog/catalog.md)
- [Propagate (propagate)](https://jbm-ui.bns.studio/catalog/propagate.md)
- [Shelf (shelf)](https://jbm-ui.bns.studio/catalog/shelf.md)
- [SceneFromSpec (scene-spec)](https://jbm-ui.bns.studio/catalog/scene-spec.md)

Imported in examples:

- [Chip (chip)](https://jbm-ui.bns.studio/catalog/chip.md)

## More

- [llms.txt](https://jbm-ui.bns.studio/llms.txt): index of every item
- [catalog.json](https://jbm-ui.bns.studio/catalog.json): every item as JSON
- [Agent contract](https://jbm-ui.bns.studio/docs/agent-contract.md): what each field means
