Trees

https://trees.software/docs
Admin
Trees is a path-first file tree component library for React, vanilla JavaScript, and server-side...
Tokens:9,837
Snippets:157
Trust Score:2.8
Update:3 months ago
Show doc for...
Tokens:
Raw
### Get Selected Paths with useFileTreeSelection

Source: https://trees.software/docs

The `useFileTreeSelection` hook is a convenience hook for directly accessing the array of selected paths from the file tree model.

```typescript
const selectedPaths = useFileTreeSelection(model);
// 'selectedPaths' is a readonly string[].
```

--------------------------------

### Custom Derived State with useFileTreeSelector

Source: https://trees.software/docs

Uses the useFileTreeSelector hook to get a custom derived snapshot of the tree state. This hook avoids rerendering on unrelated tree changes.

```javascript
import { useFileTreeSelector } from "@pierre/trees/react";

const selectedPath = useFileTreeSelector(model, (state) => state.selection.focus?.path);

console.log(selectedPath);
```

--------------------------------

### React FileTree Model Initialization

Source: https://trees.software/docs

Initializes the file tree model using the useFileTree hook from @pierre/trees/react. Suitable for small trees using raw paths.

```javascript
import { useFileTree } from "@pierre/trees/react";

const model = useFileTree({
  paths: [
    "src/components/Button.tsx",
    "src/components/Input.tsx",
    "src/utils/helpers.ts",
  ],
});
```

--------------------------------

### FileTree Constructor and Lifecycle

Source: https://trees.software/docs

Instantiate and manage the lifecycle of a FileTree instance. The constructor accepts shared options, and lifecycle methods handle mounting, hydration, unmounting, and cleanup.

```APIDOC
## FileTree Constructor and Lifecycle

### Description
Instantiate a `FileTree` object and manage its lifecycle. The constructor takes an `options` object, and methods like `render`, `hydrate`, `unmount`, and `cleanUp` control its operational state.

### Constructor
`new FileTree(options)`
  * Accepts shared options.
  * Creates the model instance.

### Lifecycle Methods
* `render({ fileTreeContainer } | { containerWrapper })`: Mounts the FileTree instance.
* `hydrate({ fileTreeContainer })`: Attaches the model to server-rendered markup.
* `unmount()`: Removes the mounted runtime while keeping the model.
* `cleanUp()`: Performs final teardown, including unmounting and model destruction.
* `getFileTreeContainer()`: Returns the mounted host element.
```

--------------------------------

### Render Context Menu Element (Vanilla JS)

Source: https://trees.software/docs

In vanilla JavaScript, use `composition.contextMenu.render` to supply the menu element directly from the runtime configuration.

```javascript
composition.contextMenu.render(element);
```

--------------------------------

### Item Handle Actions

Source: https://trees.software/docs

Perform actions on individual file or directory items, such as focusing, selecting, or expanding.

```APIDOC
## Item Handle Actions

### Description
Interact with individual file or directory items obtained via `getItem(path)`. Actions include managing focus, selection, and directory expansion/collapse.

### Shared Actions
* `getPath()`: Returns the path of the item.
* `focus()`: Sets the item as the currently focused item.
* `select()`: Selects the item.
* `toggleSelect()`: Toggles the selection state of the item.
* `deselect()`: Deselects the item.

### Directory-only Actions
* `expand()`: Expands the directory to show its contents.
* `collapse()`: Collapses the directory.
* `toggle()`: Toggles the expanded state of the directory.
```

--------------------------------

### Enable Drag and Drop

Source: https://trees.software/docs

Enable moving files or folders directly in the tree. Use `canDrag` to lock paths, `canDrop` to reject destinations, `onDropComplete` for persistence, and `onDropError` for failures.

```javascript
enable("dragAndDrop", {
  canDrag(paths) { /* ... */ },
  canDrop(event) { /* ... */ },
  onDropComplete(event) { /* ... */ },
  onDropError(error, event) { /* ... */ },
});
```

--------------------------------

### Preparing Presorted Tree Input

Source: https://trees.software/docs

Prepares tree input when the server already knows the final order, optimizing client-side performance by skipping shaping and sorting work.

```javascript
import { preparePresortedFileTreeInput } from "@pierre/trees";

const preparedInput = preparePresortedFileTreeInput({
  paths: [
    "src/components/Button.tsx",
    "src/components/Input.tsx",
    "src/utils/helpers.ts",
  ],
  // ... other options
});
```

--------------------------------

### Vanilla Hydration

Source: https://trees.software/docs

For Vanilla JavaScript, hydrate the server-rendered tree on the client using `hydrate({ fileTreeContainer })` after creating a new `FileTree` instance. Ensure matching options between server and client.

```javascript
fileTree.hydrate({ fileTreeContainer })
```

--------------------------------

### Render File Tree Component

Source: https://trees.software/docs

Use the `<FileTree />` component to mount the file tree model into a host element. Pass the model and standard HTML attributes, along with React-specific props like `header` or `renderContextMenu`.

```typescript
<FileTree model={model} className="my-file-tree" />
```

--------------------------------

### Hydration with Preloaded Data

Source: https://trees.software/docs

Enable client-side hydration by providing `preloadedData` to the `<FileTree />` component. The client model is still initialized via `useFileTree(...)`, and must use matching tree-defining options.

```typescript
// On the server or client, initialize the model
const model = useFileTree(options);

// Pass preloaded data to the component if available
<FileTree model={model} preloadedData={serverPreloadedData} />
```

--------------------------------

### Server Preload Function

Source: https://trees.software/docs

Call `preloadFileTree` on the server to pre-render the tree for the first paint. It accepts shared `FileTreeOptions` and returns an opaque SSR payload.

```typescript
preloadFileTree(options)
```

--------------------------------

### Render Context Menu Content (React)

Source: https://trees.software/docs

In React, the wrapper can render the menu content for you. This allows for dynamic menu generation within the tree component.

```javascript
wrapper.render({
  // ...
  composition: {
    contextMenu: {
      render() {
        // return React menu element
      }
    }
  }
});
```

--------------------------------

### React FileTree Component Rendering

Source: https://trees.software/docs

Renders the FileTree component, which mounts the provided model into a host element. It accepts standard host props and can hydrate server output.

```javascript
import { FileTree } from "@pierre/trees/react";

<FileTree model={model} className="my-tree" />;
```

--------------------------------

### Write and Control APIs

Source: https://trees.software/docs

Modify the state of the file tree, control focus and selection, manage search, and perform data mutations.

```APIDOC
## Write and Control APIs

### Description
APIs for controlling focus, selection, search, and performing data mutations like adding, removing, or moving items. Also includes runtime reconfiguration helpers.

### Focus and Selection Control
* `focusPath(path)`: Sets focus to the item at the specified path.
* `focusNearestPath(path | null)`: Focuses the nearest item to the given path.
* `scrollToPath(path, { offset: 'top' | 'center' | 'nearest', focus?: boolean })`: Scrolls to a path without changing DOM focus by default.
* `startRenaming(path?)`: Initiates renaming for an item.

### Search Control
* `setSearch(value)`: Sets the search query value.
* `openSearch(initialValue?)`: Opens the search interface with an optional initial value.
* `closeSearch()`: Closes the search interface.
* `focusNextSearchMatch()`: Moves focus to the next search result.
* `focusPreviousSearchMatch()`: Moves focus to the previous search result.

### Data and Mutation Control
* `add(path)`: Adds a new item at the specified path.
* `remove(path, options?)`: Removes an item at the specified path.
* `move(fromPath, toPath, options?)`: Moves an item from one path to another.
* `batch(operations)`: Executes a batch of operations.
* `resetPaths(paths, options?)`: Resets items at the specified paths.
* `onMutation(type, handler)`: Subscribes to mutation events (add, remove, move, reset, batch).

### Runtime Reconfiguration
* `setComposition(composition?)`: Updates the composition settings.
* `setGitStatus(gitStatus?)`: Sets the Git status for items.
* `setIcons(icons?)`: Sets custom icons.
```

--------------------------------

### Enable Renaming in Place

Source: https://trees.software/docs

Enable inline renaming for rows. Use `canRename` to block protected files, `onRename` to respond to path changes, and `onError` for invalid attempts.

```javascript
enable("renaming", {
  canRename(item) { /* ... */ },
  onRename(event) { /* ... */ },
  onError(error) { /* ... */ },
});
```

--------------------------------

### Composition Surface

Source: https://trees.software/docs

Control and interact with the composition aspects of the FileTree, such as header, context menus, and runtime updates.

```APIDOC
## Composition Surface

### Description
Manage and configure the composition elements of the FileTree, including header and context menu appearances, and update runtime configurations.

### Methods
* `setComposition(composition?)`: Updates the composition settings for the FileTree.
```

--------------------------------

### Initialize File Tree Model in React

Source: https://trees.software/docs

Use the `useFileTree` hook to create and manage the file tree model within a React component. This hook ensures the model is created once and cleaned up on unmount.

```typescript
const model = useFileTree(options);
// Use model methods to update the tree state after mount.
```

--------------------------------

### Subscriptions

Source: https://trees.software/docs

Manage subscriptions to tree changes for derived state updates or to listen for specific mutation events.

```APIDOC
## Subscriptions

### Description
Subscribe to changes in the FileTree model. Use `subscribe` for general state refreshes and `onMutation` for specific data modification events.

### Methods
* `subscribe(listener)`: Registers a listener that is called when any tree change occurs, useful for refreshing derived snapshots.
* `onMutation(type, handler)`: Registers a handler for specific mutation types (add, remove, move, reset, batch), allowing for semantic side effects.
```

--------------------------------

### Read APIs

Source: https://trees.software/docs

Access information about the file tree state, including items, focus, selection, and search status.

```APIDOC
## Read APIs

### Description
Retrieve various states and information from the FileTree model without altering it. These methods provide path-oriented and model-oriented access to data.

### Methods
* `getItem(path)`: Returns a file or directory handle, or null.
* `getFocusedItem()`: Returns the currently focused item.
* `getFocusedPath()`: Returns the path of the currently focused item.
* `getSelectedPaths()`: Returns an array of selected item paths.
* `getComposition()`: Retrieves composition-related information.
* `isSearchOpen()`: Checks if the search interface is open.
* `getSearchValue()`: Returns the current search query value.
* `getSearchMatchingPaths()`: Returns paths that match the current search query.
```

--------------------------------

### Manage Search State with useFileTreeSearch

Source: https://trees.software/docs

Use the `useFileTreeSearch` hook to access the current search state and associated actions. This includes search input value, matching paths, and methods to open, close, and update the search.

```typescript
const { isOpen, matchingPaths, value, open, close, setValue } = useFileTreeSearch(model);
// Use these to build search interfaces.
```

--------------------------------

### React-Rendered Context Menu

Source: https://trees.software/docs

Define custom context menus using React by passing a `renderContextMenu` function to the `<FileTree />` component. This function receives the item and context for rendering.

```typescript
const renderContextMenu = (item, context) => (
  <MyContextMenu item={item} context={context} />
);
<FileTree model={model} renderContextMenu={renderContextMenu} />
```

--------------------------------

### React-Rendered Header Content

Source: https://trees.software/docs

Provide custom React-rendered content for the file tree header using the `header` prop on the `<FileTree />` component.

```typescript
const MyCustomHeader = () => <div>My Header</div>;
<FileTree model={model} header={<MyCustomHeader />} />
```

--------------------------------

### React Handoff with Preloaded Data

Source: https://trees.software/docs

In React, pass the server-preloaded payload to the `FileTree` component via the `preloadedData` prop. Ensure server and client options match to avoid hydration issues.

```jsx
<FileTree model={model} preloadedData={payload} />
```

--------------------------------

### Serialize SSR Payload

Source: https://trees.software/docs

Use `serializeFileTreeSsrPayload` to convert the preloaded payload into a full host-markup string when your server integration requires serialized HTML. The payload remains opaque at the docs level.

```typescript
serializeFileTreeSsrPayload(payload, mode?)
```

--------------------------------

### Select Tree State with useFileTreeSelector

Source: https://trees.software/docs

Use the `useFileTreeSelector` hook to read specific parts of the file tree model's state within your React components. An optional equality function can be provided for custom comparisons.

```typescript
const selectedPaths = useFileTreeSelector(model, (state) => state.selectedPaths);
// Use 'selectedPaths' in your component's UI.
```

--------------------------------

### Update Model State from React

Source: https://trees.software/docs

React components can write to the file tree model using imperative methods exposed by the model. This includes methods for focusing, selection, search, mutations, and runtime reconfiguration.

```typescript
// Example: Adding a new path
model.add(newPath);

// Example: Resetting paths
model.resetPaths(pathsToReset);

// Example: Setting composition options
model.setComposition(newCompositionOptions);
```

--------------------------------

### Subscribe to Model Mutations in React

Source: https://trees.software/docs

For semantic side effects like persistence or analytics, subscribe to model mutation events using `model.onMutation(...)`. This allows reacting to add, remove, move, or batch operations.

```typescript
model.onMutation((mutation) => {
  console.log('Mutation occurred:', mutation);
  // e.g., persist changes
});
```

--------------------------------

### Manually Lock Window Scroll for Non-Modal Menu

Source: https://trees.software/docs

Manually lock window scroll when a non-modal context menu is open to keep it attached to its row. Release the lock when the menu closes.

```javascript
lockScroll();
// ... menu is open ...
menu.onClose = releaseScroll;
releaseScroll();
```
Tokens:
Raw