# code/editor/FileTree (zidane-ui/code/editor)

Import: `import { … } from 'zidane-ui/code/editor'`. Source: [ui/src/code/editor/FileTree.tsx](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileTree.tsx).

## Components

### `FileTree`

Component.

The workspace file tree: rows from `entries`, painted with `gitStatus`, reporting selection,
opens and right-clicks.

```ts
function FileTree(props: FileTreeProps): Element
```

**Parameters**

- `props` (`FileTreeProps`): The paths, git status and selection to show, and the handlers it reports to.

**Returns** `Element`

**Props**

- `className?` (`string`): Extra classes on the root element.
- `controlRef?` (`RefObject<FileTreeControl | null>`): Receives the imperative handle for search and reveal.
- `editing?` (`FileTreeEditing`): Rename, create, drag and drop. Absent: the tree only browses. Read when the tree is created.
- `entries` (`readonly TreeEntry[]`): The paths to show, flat.
- `gitStatus` (`readonly TreeGitStatus[]`): Git status painted on the rows.
- `label?` (`string`): Accessible name. Default: the `fileTree` label.
- `onContextMenu?` (`(target: { kind: 'file' | 'folder'; path: string }, at: { x: number; y: number }) => void`): Right-click on a row.
- `onExpandFolder?` (`(path: string) => void`): An ignored folder listed as one node was expanded (its path, without the trailing `/`).
- `onOpen` (`(path: string, modifiers: { ctrlKey: boolean; metaKey: boolean }) => void`): Fired when the user activates a file (click / Enter), with the modifiers held.
- `onSelect` (`(path: string | null) => void`): Called with the newly selected path, or `null` when the selection clears.
- `openPaths?` (`readonly string[]`): Files open in the editor: the folders holding them start expanded, every
  other folder starts collapsed. Read when the tree is created only.
- `selectedPath` (`string | null`): The selected row's path; `null` for none.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/code/editor/FileTree.tsx:131](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileTree.tsx#L131)

## Functions

### `ancestorDirs`

Function.

Every folder holding one of `paths` (`src/`, `src/chat/`), as tree ids.

```ts
function ancestorDirs(paths: readonly string[]): string[]
```

**Parameters**

- `paths` (`readonly string[]`): File paths relative to the tree's root.

**Returns** `string[]`

Source: [ui/src/code/editor/FileTree.tsx:439](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileTree.tsx#L439)

## Constants

### `TREE_PATH_MIME`

Constant.

The drag data type a tree row carries (its path, relative to the tree's root): what an editor takes to open it.

```ts
const TREE_PATH_MIME = 'application/x-zidane-tree-path'
```

Source: [ui/src/code/editor/FileTree.tsx:39](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileTree.tsx#L39)

## Interfaces

### `FileTreeControl`

Interface.

Imperative handle for the bits of the model the tab drives itself.

```ts
interface FileTreeControl
```

**Properties**

- `resync` (`() => void`): Drops what the tree changed on its own (an optimistic rename or move that failed) and shows `entries` again.
- `reveal` (`(path: string) => boolean`): Expand ancestors, scroll to and select only `path` (a folder expands too). `false`: the tree has no such row.
- `revealSoon` (`(path: string) => void`): Reveals `path` now, or once the next `entries` hold it (a row the host just made).
- `setSearch` (`(value: string | null) => void`): Filter rows by substring; `null` clears.
- `startCreate` (`(dir: string, kind: 'file' | 'folder', name: string) => boolean`): With `editing`: a placeholder row named `name` (or the next free variant) in folder `dir` (`''`: the root),
  renamed in place; the chosen name goes to `editing.onCreate`. `false` when the tree can't.
- `startRename` (`(path: string) => boolean`): With `editing`: renames `path` in place. `false` when the tree has no such row.

Source: [ui/src/code/editor/FileTree.tsx:60](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileTree.tsx#L60)

### `FileTreeEditing`

Interface.

What the tree reports when it is editable. Paths are relative to its root, without a trailing `/`.

```ts
interface FileTreeEditing
```

**Properties**

- `onCreate` (`(path: string, kind: 'file' | 'folder') => void`): A placeholder row (`control.startCreate`) named: create it.
- `onDropFiles?` (`(toDir: string, data: DataTransfer) => void`): Files dragged in from outside the page, dropped on folder `toDir`. Read `data` now: it empties after the drop.
- `onError?` (`(message: string) => void`): The tree refused a name itself (a sibling has it, or it is empty).
- `onMove` (`(paths: readonly string[], toDir: string, copy: boolean) => void`): Rows dragged onto folder `toDir` (`''`: the root); `copy`: ⌥ was held.
- `onRename` (`(from: string, to: string, kind: 'file' | 'folder') => void`): A row renamed in place.

Source: [ui/src/code/editor/FileTree.tsx:79](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileTree.tsx#L79)

### `FileTreeProps`

Interface.

Props for [`FileTree`](https://zidane.si/docs/reference/ui-code-editor-file-tree.md#FileTree).

```ts
interface FileTreeProps
```

**Properties**

- `className?` (`string`): Extra classes on the root element.
- `controlRef?` (`RefObject<FileTreeControl | null>`): Receives the imperative handle for search and reveal.
- `editing?` (`FileTreeEditing`): Rename, create, drag and drop. Absent: the tree only browses. Read when the tree is created.
- `entries` (`readonly TreeEntry[]`): The paths to show, flat.
- `gitStatus` (`readonly TreeGitStatus[]`): Git status painted on the rows.
- `label?` (`string`): Accessible name. Default: the `fileTree` label.
- `onContextMenu?` (`(target: { kind: 'file' | 'folder'; path: string }, at: { x: number; y: number }) => void`): Right-click on a row.
- `onExpandFolder?` (`(path: string) => void`): An ignored folder listed as one node was expanded (its path, without the trailing `/`).
- `onOpen` (`(path: string, modifiers: { ctrlKey: boolean; metaKey: boolean }) => void`): Fired when the user activates a file (click / Enter), with the modifiers held.
- `onSelect` (`(path: string | null) => void`): Called with the newly selected path, or `null` when the selection clears.
- `openPaths?` (`readonly string[]`): Files open in the editor: the folders holding them start expanded, every
  other folder starts collapsed. Read when the tree is created only.
- `selectedPath` (`string | null`): The selected row's path; `null` for none.
- `style?` (`CSSProperties`): Inline styles on the root element, merged after the component's own.

Source: [ui/src/code/editor/FileTree.tsx:93](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileTree.tsx#L93)

### `TreeEntry`

Interface.

One path in the tree.

```ts
interface TreeEntry
```

**Properties**

- `ignored?` (`boolean`): Dimmed (gitignored).
- `kind` (`'dir' | 'file'`): A file or a directory.
- `path` (`string`): Relative to the tree's root; directories end with `/` (listed only when empty).

Source: [ui/src/code/editor/FileTree.tsx:42](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileTree.tsx#L42)

### `TreeGitStatus`

Interface.

A path's git status, painted on its row.

```ts
interface TreeGitStatus
```

**Properties**

- `path` (`string`): Relative to the tree's root, without a trailing `/`.
- `status` (`'added' | 'deleted' | 'ignored' | 'modified' | 'renamed' | 'untracked'`): The change git reports for the path; `ignored` dims the row.

Source: [ui/src/code/editor/FileTree.tsx:52](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileTree.tsx#L52)