# Bandeja (bandeja)

> A shallow paper tray with optional sheets.

- Entry: component
- Category: UI Bits
- Preview capabilities: controls
- Runtime: React
- Needs Remotion: no
- QA page: https://jbm-ui.bns.studio/c/bandeja
- JSON: https://jbm-ui.bns.studio/catalog/bandeja.json
- Registry item: https://jbm-ui.bns.studio/r/bandeja.json (source code in files[].content)

## Install

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

Also installs @jbm/tokens, @jbm/scene-geometry (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/.

## Files

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

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

## API

### `Bandeja` (component)

SVG <g> of a shallow tray: back well, stacked card sheets, and a front lip with a finger notch that occludes their lower edges. Controlled by layers and landing; no internal timer. Render inside an <svg>.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` | none | Left edge of the tray in the parent SVG's user units. |
| `y` | `number` | none | Top reference of the tray in parent SVG units; the back rim is at y + 16 and the base at y + 68. |
| `w` | `number` | none | Tray width in parent SVG units; the rim, sheets, and front notch scale with it. |
| `layers` | `number` | none | Settled sheet count. The bottom sheet lies in the well (top edge at y + 24); the second clears the back rim (y + 11) and each further sheet sits 5 units above the last (the shared 3-unit outline plus a 2-unit gap), so no edge fuses with the rim. Sheets under the top one show only their near edges, between upright stack sides. Floored; negative or non-finite values show none. |
| `landing` | `number` | none | Arrival of one extra incoming sheet, 0–1: it drops from 90 units above the stack top and fades in, settling at 1. Clamped; 0 hides it. |

### `bandejaLayout` (function)

Tray geometry for composites that drop or pick up sheets.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` | `0` | Left edge of the tray in the parent SVG's user units. |
| `y` | `number` | `0` | Top reference of the tray in parent SVG units; the back rim is at y + 16 and the base at y + 68. |
| `w` | `number` | `280` | Tray width in parent SVG units; the rim, sheets, and front notch scale with it. |
| `layers` | `number` | `0` | Settled sheet count. The bottom sheet lies in the well (top edge at y + 24); the second clears the back rim (y + 11) and each further sheet sits 5 units above the last (the shared 3-unit outline plus a 2-unit gap), so no edge fuses with the rim. Sheets under the top one show only their near edges, between upright stack sides. Floored; negative or non-finite values show none. |
| `landing` | `number` | none | Accepted for parity with Bandeja's props; the layout ignores it. |

Returns: { x, y, w, count, floor, stackTop }: the floored sheet count, the tray floor centre (y + 41), and where the next sheet lands (17 units below its top edge: y + 41 with no sheets, y + 33 − 5 × count after), in parent SVG units.

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 280 | 52 |
| Vertical (1080×1920) | 280 | 52 |

Parent SVG user units at w 280: from the back rim at y + 16 to the base at y + 68. From two layers the top sheet rises over the back rim (top sheet at y + 16 − 5 × (layers − 1)), and a landing sheet starts 90 units above the stack, so leave headroom above y.

## Examples

### Tray with three sheets

```tsx
import { Bandeja } from "@/jbm/motion/bandeja"

<svg viewBox="0 0 400 250">
  <Bandeja x={60} y={120} layers={3} />
</svg>
```

### Land a sheet and aim at the stack

```tsx
import { Bandeja, bandejaLayout } from "@/jbm/motion/bandeja"

const tray = { x: 70, y: 160, w: 360, layers: 4 }
const target = bandejaLayout(tray).stackTop // where the next sheet lands
<svg viewBox="0 0 500 340">
  <Bandeja {...tray} landing={0.6} />
  <circle cx={target.x} cy={target.y} r={4} />
</svg>
```

## QA

- Drag Sheets from 0 to 12: the second sheet jumps clear of the back rim, then each steps up 5 units; no sheet edge fuses with the rim, a wall, or the sheet below, the stack's sides stay upright inside the wall posts, and tall stacks stay inside the viewBox.
- Step landing through 0, 0.5, and 1: the incoming sheet fades in while descending and rests exactly on the stack at 1, then increment layers to settle it.
- Check the front notch stays centred when w changes.

## Family

Desk objects

## Docs

- [Desk illustrations guide](https://jbm-ui.bns.studio/docs/desk-components.md)

## Related

Installs:

- [Tokens (tokens)](https://jbm-ui.bns.studio/catalog/tokens.md)
- [SceneGeometry (scene-geometry)](https://jbm-ui.bns.studio/catalog/scene-geometry.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
