# Catalog (catalog)

> Catalogue sheet whose interface pieces arrive and get checked off, then unfolds a second row of design-token glyphs.

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

## Install

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

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

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

## API

### `Catalog` (component)

Paper sheet that springs up into place at `at`, with one dashed slot per column. Each item's Piece pops into its slot on its cue and a check badge pops on `checkDelay` seconds later. At `tokensAt` the sheet grows downward over 0.55 s behind a dashed divider to reveal a row of TokenGlyphs that pop in on their own cues. An optional ink title sticker sits over the top edge and a stamp lands across the bottom edge, below the rows; it overlaps only the sheet's bottom padding and extends about half its height below the sheet, so leave room under the component.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `w` | `number` | required | Sheet width in stage pixels; padding, gaps, slot size, pieces, captions, and badges all scale from it. |
| `at` | `number` | required | Sheet entrance in seconds relative to the enclosing Sequence. |
| `title` | `string` | none | Optional ink sticker label over the top-left edge; adds 30px of top padding inside the sheet. |
| `items` | `CatalogItem[]` | required | Top-row slots: `kind` (button, card, or input), a caption `label`, and the `at` second its piece pops in. |
| `tokens` | `CatalogToken[]` | `[]` | Optional second-row slots: `kind` (color, type, or space), a caption `label`, and the `at` second its glyph pops in. Empty means no token row. |
| `tokensAt` | `number` | none | Second at which the token row unfolds. Defaults to 0.6 s before the first token's cue. |
| `stamp` | `{ text: string; at: number }` | none | Optional loud word: `text` and the `at` second it stamps across the sheet's bottom edge, below the rows, never over a slot or caption. |
| `checkDelay` | `number` | `0.5` | Seconds between an item's arrival and its check badge. |

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 1200 | 882 |
| Vertical (1080×1920) | 936 | 699 |

Width is `w` (required); scene specs pass min(usable width, 1200) in landscape and 936 in vertical. Height is computed from w with three items, three tokens, and a title, fully unfolded: top padding (0.038 w + 30) + slot row (card height 0.8 × 0.78 slot width + caption + margin) + bottom padding + 4px border, plus the token block (two gaps of 0.031 w, a 3px divider, and a 0.9 × slot-width glyph row) once unfolded. Before unfolding it is 492 (landscape) / 393 (vertical). The title sticker extends 30px above the top edge. More columns shrink every slot.

## Examples

### Pieces, then tokens

```tsx
import { Catalog } from "@/jbm/motion/catalog"

<Catalog w={936} at={3.2} title="catálogo"
  items={[{ kind: "button", label: "botón", at: 7.4 }]}
  tokens={[{ kind: "color", label: "color", at: 18.2 }]} />
```

### Full sheet with a stamp

```tsx
import { Catalog } from "@/jbm/motion/catalog"

<Catalog w={936} at={0.2} title="catálogo"
  items={[
    { kind: "button", label: "botón", at: 0.8 },
    { kind: "card", label: "tarjeta", at: 1.2 },
    { kind: "input", label: "input", at: 1.6 },
  ]}
  tokensAt={2.6}
  tokens={[
    { kind: "color", label: "color", at: 3.0 },
    { kind: "type", label: "tipografía", at: 3.4 },
    { kind: "space", label: "espaciado", at: 3.8 },
  ]}
  stamp={{ text: "design tokens", at: 4.4 }} />
```

## QA

- Step to the sheet entrance, each item arrival and its check badge, the middle of the unfold (token row partially revealed and clipped), and the end (all glyphs in, stamp settled across the bottom edge without covering any caption, including tipografía).
- Check the fully unfolded sheet plus the title sticker above it fits the safe area in both orientations; the height grows by the token block when it unfolds.
- Without tokens, confirm no divider or empty row appears and the stamp straddles the bottom edge just below the item row.
- Check long captions at the scaled caption size stay inside their slots; captions are not truncated by the component.

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

```tsx
<Catalog w={936} at={0.2} title="catálogo" items={[{ kind: "button", label: "botón", at: 0.8 }, { kind: "card", label: "tarjeta", at: 1.2 }, { kind: "input", label: "input", at: 1.6 }]} tokensAt={2.6} tokens={[{ kind: "color", label: "color", at: 3 }, { kind: "type", label: "tipografía", at: 3.4 }, { kind: "space", label: "espaciado", at: 3.8 }]} stamp={{ text: "design tokens", at: 4.4 }} />
```

| Frame | Seconds | Shows | What to check |
| --- | --- | --- | --- |
| 0 | 0.00 | Empty stage |  |
| 78 | 2.60 | Pieces tested | Button, card, and input sit in their slots with checks; the token row is still folded. |
| 105 | 3.50 | Tokens arriving | The sheet has unfolded and the colour glyph is in; type and spacing are still arriving. |
| 129 | 4.30 | Tokens in | All three token glyphs have landed, just before the stamp. |
| 158 | 5.27 | 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)
- [RebuildScreens (rebuild-screens)](https://jbm-ui.bns.studio/catalog/rebuild-screens.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
