# FolderContents (folder-contents)

> Folder that opens to reveal a sheet and a fan of nested folders whose documents extract independently.

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

## Install

```sh
npx shadcn@latest add @jbm/folder-contents
```

Also installs @jbm/tokens, @jbm/scene-geometry, @jbm/folder (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/folder-contents.json, files[].content).

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

## API

### `FolderContents` (component)

Fills Folder's children slot with a front sheet and nested folders, each with an optional document. Every part is a rigid object that translates into view; nothing stretches. Pure React: `open`, per-entry `reveal` and `documentReveal`, and `lift` are independent 0–1 controls with no internal timer. Other SVG props pass through to the Folder svg.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `label` | `string` | none | Mono label for the outer folder; also names the image for assistive technology. On the front panel (accent and ink) it follows Folder's fitLine rule (compressed to 0.8, then an ellipsis); on the tab (card tone default, or labelOn "tab") it is a Geist 800 tab name drawn whole. |
| `tone` | `FolderTone` | none | Outer folder fill: vermilion accent, ink, or plain cream card. |
| `open` | `number` | none | Outer folder opening from 0 (closed, contents hidden) to 1 (contents shown). Clamped. Defaults to 1 here, unlike Folder's 0; every reveal is multiplied by it. |
| `sublabel` | `string` | none | Short line printed on the front panel: under the label, or near the panel top when the label is on the tab. |
| `labelOn` | `"front" \| "tab"` | none | Where the label prints while the folder is closed. Defaults to the tab for the card tone, the front panel otherwise. Once open is above 0 the sheet stands in front of the tab, so the label prints on the front panel. |
| `entries` | `FolderEntry[]` | `[]` | Nested folders, back to front. Their tabs pack between y 24 and 72 of the folder space, so more entries overlap more tightly instead of growing the folder. Empty by default. |
| `sheet` | `string` | `"README.md"` | Label printed on the front sheet (first 15 characters). An empty string removes the sheet. |
| `lift` | `number` | `0` | Raises all contents together by up to 240 folder units (0–1), clipped at the folder's top, for handing the whole group out. |

Also accepts Omit<ComponentProps<typeof Folder>, "children">.

### `FolderEntry` (type)

One nested folder: `id` (React key), `label` (truncated after 15 characters), `reveal` 0–1 (default 1; rises from the folder bottom), optional `document` label (12 characters shown), and `documentReveal` 0–1 (default 0; lifts the document 45 units out of its folder).

## Stage

Declared in stage pixels at the documented defaults.

| Orientation | Width | Height |
| --- | --- | --- |
| Landscape (1920×1080) | 260 | 220 |
| Vertical (1080×1920) | 260 | 220 |

Renders Folder's fixed 260×220 viewBox at 260×220 stage pixels; entry count, reveals, and lift never change the box. Pass width (or style.width) to scale with height auto, and it shrinks to maxWidth 100%. The gallery uses width={320} with overflow visible so the opened sheet above the viewBox stays visible.

## Examples

### Open project folder with one extracted document

```tsx
import { FolderContents } from "@/jbm/ui/folder-contents"

<FolderContents
  label="proyecto"
  open={1}
  sheet="README.md"
  entries={[
    { id: "scripts", label: "scripts/" },
    { id: "assets", label: "assets/", document: "notas.md", documentReveal: 1 },
  ]}
  width={320}
  style={{ overflow: "visible" }}
/>
```

## QA

- Drag Open folder through 0, 0.5, and 1: the sheet and nested folders slide up as rigid shapes and never cut through the front panel.
- Drag Extract documents and Lift contents independently; each moves only its own objects.
- Set Nested folders to 0 and 8: zero entries with an empty sheet reads as an empty folder; eight entries pack tighter without resizing the folder.
- Toggle Reveal nested folders: hidden folders sit fully below the rim with complete outlines, clipped only at the container bottom.
- Uncertain: at open 1 the sheet and front folders extend above the 220-unit viewBox, so they rely on overflow visible; check clipping when overflow is left hidden.

## Family

Folders & drawers

## Docs

- [Paper and filing illustrations guide](https://jbm-ui.bns.studio/docs/design-video-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)
- [Folder (folder)](https://jbm-ui.bns.studio/catalog/folder.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
