# @pierre/trees

An open-source file-tree rendering library for the web, from The Pierre Computer Co., built for extreme performance on large trees. Like its sibling [[toolbox/pierre-diffs|@pierre/diffs]] (same `pierrecomputer/pierre` monorepo), it offers both React and vanilla-JS APIs with SSR support and heavy theming — the file-explorer counterpart to the diff/code renderer.

## The model: path-first

The organizing idea is a **path-first identity** model. Items are identified by their path, and the API is built around that shared model across both integrations. You feed it tree data (paths, or a "prepared input" form for speed), and it handles selection, focus, keyboard navigation, search, rename, drag-and-drop, and git-status annotations. The docs push you toward *prepared* (and *presorted prepared*) input for large trees — precomputing the shape so rendering stays cheap — which is where the "extreme performance on large trees" claim comes from, together with virtualization.

## What's in it

- **React quickstart** — `useFileTree` hook, `FileTree` component, selector hooks, and prepared input.
- **Vanilla quickstart** — `new FileTree`, `render`, imperative model methods, and prepared input.
- **Navigation** — selection, focus, keyboard movement, and a configurable `fileTreeSearchMode`.
- **Mutation** — inline rename, drag-and-drop, and optional context-menu / item-action workflows.
- **Git status & row annotations** — built-in `gitStatus` signals plus custom row decorations (badges, colors) per item.
- **Icons** — built-in icon sets, remaps, color modes, and a sprite-sheet extension mechanism (`FileTreeIconConfig`, remap precedence).
- **Virtualization** — settings tuned for large trees so only visible rows render.
- **SSR** — `preloadFileTree` on the server, `serializeFileTreeSsrPayload`, and React/vanilla hydration with an opaque SSR handoff.

## Styling and theming

Host styling plus CSS-variable families with a defined fallback precedence, theme helpers (`themeToTreeStyles`), and an `unsafeCSS` escape hatch — the same theming philosophy as [[toolbox/pierre-diffs]].

## Usage

```bash
npm install @pierre/trees
```

```jsx
import { useFileTree, FileTree } from "@pierre/trees/react";

const tree = useFileTree({ files: preparedInput });
<FileTree tree={tree} />
```

Vanilla JS constructs `new FileTree(...)`, calls `render`, and drives it through imperative methods and subscriptions.

## Notes

- Package `@pierre/trees` is at **v1.0.0-beta.x** — younger than `@pierre/diffs` (v1.2.x) and still pre-stable. Apache-2.0.
- Part of the broader `pierrecomputer/pierre` monorepo (~5.5k★ across all of Pierre's open-source code).
- Docs: [trees.software/docs](https://trees.software/docs) (with `llms.txt` / `llms-full.txt`).

## Related

- [[toolbox/pierre-diffs]] — the sibling diff/code renderer; the two compose into a full code-review UI (file tree + diffs)
- [[developer-icons]] — comparable developer-UI primitive library in the toolbox