# FileCabinet (file-cabinet)

> SVG cabinet enclosure around a controlled filing drawer whose folders slide out and lift.

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

## Install

```sh
npx shadcn@latest add @jbm/file-cabinet
```

Also installs @jbm/tokens, @jbm/cajon, @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/file-cabinet.json, files[].content).

| Source path | Installs to | Import |
| --- | --- | --- |
| `registry/jbm/ui/file-cabinet.tsx` | `src/jbm/ui/file-cabinet.tsx` | `@/jbm/ui/file-cabinet` |

## API

### `FileCabinet` (component)

An SVG <g> for use inside your own <svg>: a fixed card enclosure with a chamfered top, and a Cajon drawer inset 10px at the sides and 32px from the top. `open` and per-folder `pulled` are controlled 0–1; the enclosure never moves or resizes.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` | none | Left edge of the enclosure in the parent SVG's units. |
| `y` | `number` | none | Top edge of the enclosure. |
| `w` | `number` | none | Enclosure width; the drawer is w − 20. |
| `h` | `number` | none | Enclosure height; the drawer is h − 44. |
| `folders` | `readonly DrawerFolder[]` | required | Folders in the drawer, index 0 nearest the front. Each is a Cajon DrawerFolder: `name` (tab label, drawn whole; long names compress), optional `accent` fill, `pulled` 0–1 lift, light `k`, flap `open`, name `reveal`, and `sublabel`. Count never changes the drawer size; the folders pack within the same 48-unit rise. |
| `open` | `number` | none | Drawer opening from 0 (closed) to 1 (open). Clamped. |
| `depthSpacing` | `number` | none | Rise between folders. Defaults to the packed 48 / max(5, n − 1), so the drawer stays under the enclosure top; pass a larger value to fan the tabs (they then rise above the cabinet). |
| `tabLayout` | `"stair" \| "stagger3"` | none | Tab placement; defaults to "stagger3" (left, center, right) in a cabinet so packed tabs stay readable. "stair" puts every tab at the left edge. |
| `labelSize` | `number` | none | Tab name size in SVG units (default 13). |

Also accepts Partial<Box>.

### `FileCabinetBody` (component)

The enclosure alone, so composites (such as Escritorio) can draw foreground furniture between it and the moving drawer.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` | required | Left edge in the parent SVG's units. |
| `y` | `number` | required | Top edge. |
| `w` | `number` | required | Width. |
| `h` | `number` | required | Height. |

### `fileCabinetLayout` (function)

Computes the enclosure box and the drawer props FileCabinet renders, for composites that draw the parts separately.

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` | `0` | Left edge of the enclosure. |
| `y` | `number` | `0` | Top edge of the enclosure. |
| `w` | `number` | `300` | Enclosure width. |
| `h` | `number` | `360` | Enclosure height. |
| `folders` | `readonly DrawerFolder[]` | required | Drawer folders, passed through to the drawer. |
| `open` | `number` | none | Drawer opening 0–1, passed through to the drawer. |
| `depthSpacing` | `number` | none | Rise, in parent SVG units, from one folder to the next one back. Defaults to tab height plus a band of back panel (the tab and band stay visible up to six folders; more folders pack into the same rise, so the stack never grows past six folders' height). |
| `tabLayout` | `"stair" \| "stagger3"` | none | stair: every tab at its folder's left edge, so the tabs climb as folders narrow toward the back. stagger3: tabs cycle left, center, right. |
| `labelSize` | `number` | none | Tab name size in parent SVG units; the tab height and sublabel size follow it. |

Returns: `{ body: Box, drawer: CajonProps }`: the enclosure box and the inset drawer props (x + 10, y + 32, w − 20, h − 44).

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 300 | 360 |
| Vertical (1080×1920) | 300 | 360 |

Default w 300 by h 360 in the parent SVG's units, placed at x, y. The drawer stays inside the enclosure at every opening, but lifted folders rise above the top by up to about their height plus 24 (roughly 190 units at the default width), so the parent viewBox needs headroom: the gallery uses "0 -260 500 700".

## Examples

### Open cabinet with one folder

```tsx
import { FileCabinet } from "@/jbm/ui/file-cabinet"

<svg viewBox="0 -260 500 650">
  <FileCabinet x={80} folders={[{ name: "datos" }]} open={1} />
</svg>
```

### Lift the front folder

```tsx
import { FileCabinet } from "@/jbm/ui/file-cabinet"

<svg viewBox="0 -260 500 700">
  <FileCabinet x={85} y={-20} w={330} h={350} open={0.8}
    folders={[{ name: "análisis", accent: true, pulled: 0.6 }, { name: "diseño" }]} />
</svg>
```

## QA

- Drag Open through 0, 0.5, and 1: the enclosure never moves or resizes and only the drawer travels toward the viewer.
- Try folder counts 0, 1, 3, 6, and 12: the drawer size is unchanged and extra folders pack toward the back.
- Drag Lift front folder to 1: the folder body is complete behind the drawer front, keeps its size, and stays within the viewBox headroom.
- Check the preview at narrow widths; the SVG scales with its viewBox.

## Family

Folders & drawers

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

Installed by:

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