# ToolCaddy (tool-caddy)

> An empty divided desktop organizer.

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

## Install

```sh
npx shadcn@latest add @jbm/tool-caddy
```

Also installs @jbm/tokens (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/tool-caddy.json, files[].content).

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

## API

### `ToolCaddy` (component)

SVG <g> of an empty desktop organizer in three-quarter view: card front, darker side and back, an ink opening, and a carry handle rising above the rim. Tools are separate objects placed by the caller. Render inside an <svg>.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `x` | `number` | `0` | Left edge in the parent SVG's user units. |
| `y` | `number` | `0` | Top of the rim in parent SVG units; the handle rises 36 × (w / 240) above it. |
| `w` | `number` | `240` | Width in parent SVG units; the whole drawing scales uniformly by w / 240, except the stroke, which stays the shared outline (stroke.outline) in parent units. |

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 240 | 200 |
| Vertical (1080×1920) | 240 | 200 |

Parent SVG user units at w 240: from the handle top at y − 36 to the base at y + 164. Everything scales by w / 240 (300 wide is 250 tall). Place y at least 36 × w / 240 below the viewBox top.

## Examples

### Empty caddy

```tsx
import { ToolCaddy } from "@/jbm/motion/tool-caddy"

<svg viewBox="0 0 400 250">
  <ToolCaddy x={80} y={40} />
</svg>
```

## QA

- The gallery preview is a still at w 300; there are no controls to exercise.
- Check the handle is fully inside the viewBox (it sits above y) and its gap reads as a hole.
- Scale w up and down: the ink stroke stays the shared outline in parent units at every size; confirm it matches nearby objects.

## 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)

## 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
