# Shelf (shelf)

> A pile of tilted library cards that slide in on their own cues, plus Twice: a button, the same button again, and a vermilion cross drawn over the second.

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

## Install

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

Also installs @jbm/tokens, @jbm/motion-hooks, @jbm/pop, @jbm/paper, @jbm/ui-bits (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/shelf.json, files[].content).

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

## API

### `Shelf` (component)

Column of wide Paper cards, each sliding in from the left (60px) with a spring at its own `at`, tilted −1.2°, 1°, −0.8° in turn. Each card shows its name in mono type and three tiny pieces (card, input without cursor, button). The button is accent on paper and ink cards, paper on an accent card.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | required | Width of every card in stage pixels. |
| `items` | `{ text: string; at: number; tone?: PaperTone }[]` | required | Cards from top to bottom: `text` (mono label, one line, not truncated), `at` (entrance in seconds), and optional `tone` (paper default, accent for the one that is yours, or ink). |
| `cardH` | `number` | none | Card height in stage pixels; defaults to round(0.16 × w). Label size, padding, radius, and piece size follow it. |
| `gap` | `number` | `22` | Vertical space between cards in stage pixels. |

### `Twice` (component)

Closing gag: an ink button scales in at `at`, an identical one beside it at `second`, then two vermilion strokes draw a cross over the second (each 0.25 s, the second stroke 0.2 s after the first).

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | required | Row width in stage pixels; the buttons are centred with a gap of 5% of w. |
| `at` | `number` | required | Seconds when the first button scales in. |
| `second` | `number` | required | Seconds when the second, identical button scales in. |
| `strike` | `number` | none | Seconds when the cross starts drawing; defaults to second + 0.5. |
| `bw` | `number` | none | Button width in stage pixels; defaults to min(420, half the row minus the gap). |
| `bh` | `number` | none | Button height in stage pixels; defaults to round(0.34 × button width). |

## Stage

fluid: Shelf is w wide and grows with its items: n × cardH + (n − 1) × gap, with cardH = round(0.16 × w) by default (three cards at w = 936 are 494px tall). Twice is w wide and bh + 52 tall (about 211px at w = 936). SceneFromSpec gives both min(W, 1100) and min(W, 1000) in landscape and the full safe-area width in vertical. Card tilt, the left slide, and the cross strokes reach past these boxes.

## Examples

### Library shelf, then the gag

```tsx
import { Shelf, Twice } from "@/jbm/motion/shelf"

<Shelf w={936} items={[
  { text: "shadcn/ui", at: 0.2 },
  { text: "Material UI", at: 0.6 },
  { text: "jbm-ui", at: 1.0, tone: "accent" },
]} />
<Twice w={936} at={2} second={2.8} strike={3.6} />
// Render inside a Remotion <Composition> or <Player>.
```

## QA

- Step through each card cue: cards slide in from the left in order and settle at alternating tilts; the accent card's button turns paper.
- Try a long label at narrow w: the mono label does not wrap or truncate and can collide with the three pieces.
- For Twice, inspect first button, second button, mid-strike, and final frame: both strokes fully drawn tail to head and the cross stays within the row's 26px padding.
- Check the full stack height (items plus Twice) fits the safe area in both orientations.

## 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 123 frames (0–122); see them side by side at https://jbm-ui.bns.studio/c/shelf?view=strip, or open one frame with ?frame=<frame>.

```tsx
<Shelf w={936} items={[{ text: "shadcn/ui", at: 0.2 }, { text: "Material UI", at: 0.6 }, { text: "jbm-ui", at: 1, tone: "accent" }]} />
<Twice w={936} at={2} second={2.8} strike={3.6} />
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Empty stage |  |
| 57 | 1.90 | Libraries stacked | All three library cards have landed with alternating tilt; the button row is still empty. |
| 81 | 2.70 | One button | The first button has settled alone before its twin arrives. |
| 104 | 3.45 | Built twice | Both buttons have settled side by side at full size; the vermilion cross has not started drawing. |
| 122 | 4.07 | End |  |

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [MotionHooks (motion-hooks)](https://jbm-ui.bns.studio/catalog/motion-hooks.md)
- [Pop (pop)](https://jbm-ui.bns.studio/catalog/pop.md)
- [Paper (paper)](https://jbm-ui.bns.studio/catalog/paper.md)
- [UiBits (ui-bits)](https://jbm-ui.bns.studio/catalog/ui-bits.md)

Installed by:

- [SceneFromSpec (scene-spec)](https://jbm-ui.bns.studio/catalog/scene-spec.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
