# zidane-ui/files

Import: `import { … } from 'zidane-ui/files'`. Source: [ui/src/files/index.ts](https://github.com/Tahul/zidane/blob/main/ui/src/files/index.ts).

## Components

### `DiffsTab`

Component.

The Diffs tab: the session's edits and the working tree against HEAD, a file tree beside virtualised diffs with
review comments, find in diffs and search in changes, over the [`FilesProvider`](https://zidane.si/docs/reference/ui-files.md#FilesProvider)'s host. Loads on first render.

```ts
function DiffsTab(props: DiffsTabProps): Element
```

**Parameters**

- `props` (`DiffsTabProps`): The scope, the app's hooks, chat target and requests.

**Returns** `Element`

**Props**

- `chat?` (`FilesChatTarget | null`): The chat review comments go to (`null`: shown disabled).
- `className?` (`string`): Classes on the root.
- `createParseWorker?` (`() => Worker`): Makes the worker that parses working-tree patches (it answers `parseWorkingTree`). Default: parse on this thread.
- `onWorkingTreeTaken?` (`() => void`): The tab took `workingTreeRequest`: the app clears it.
- `scope` (`FilesScope`): The folder the tab works from; bound to a session, it shows that session's edits too.
- `style?` (`CSSProperties`): Styles on the root.
- `useEdits?` (`SessionEditsHook`): The bound session's edit events (a hook). Without it, the Session source is empty.
- `useKeyScope?` (`FilesKeyScopeHook`): Registers the tab's next / previous / close / find keys (a hook).
- `workingTreeRequest?` (`number`): A count the app bumps to open the working tree (the git bar's changes); 0: none asked.

Source: [ui/src/files/lazy-tabs.tsx:35](https://github.com/Tahul/zidane/blob/main/ui/src/files/lazy-tabs.tsx#L35)

### `EditorEnvironmentRoot`

Component.

Provides the editor surfaces' environment from the app's appearance and Editor settings.

```ts
function EditorEnvironmentRoot(props: EditorEnvironmentRootProps): Element
```

**Parameters**

- `props` (`EditorEnvironmentRootProps`): The `children`.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The editor surfaces.

Source: [ui/src/files/EditorEnvironmentRoot.tsx:29](https://github.com/Tahul/zidane/blob/main/ui/src/files/EditorEnvironmentRoot.tsx#L29)

### `FilesProvider`

Component.

Provides a [`FilesHost`](https://zidane.si/docs/reference/ui-files-headless.md#FilesHost) and optional label overrides to the Files and Diffs tabs below it.

```ts
function FilesProvider(props: FilesProviderProps): Element
```

**Parameters**

- `props` (`FilesProviderProps`): Provider props: the `host`, optional `labels`, and the `children` to render.

**Returns** `Element`

**Props**

- `children` (`ReactNode`): The components that read from `host`.
- `host` (`FilesHost`): The host the Files and Diffs tabs below read files, git state and editor preferences from.
- `labels?` (`Partial<{ filesAddToChat: string; filesAddToPrompt: string; filesAddWhatToChat: (what: string) => string; filesAfter: string; filesAllFiles: string; filesBefore: string; filesBinary: string; filesBlankLines: string; filesCancel: string; filesChangedOnly: string; filesCheckedBy: (ran: readonly string[], failed: readonly string[]) => string; filesCheckFailed: (tools: readonly string[]) => string; filesChecking: string; filesClearSearch: string; filesCloseSearch: string; filesCloseSearchHint: string; filesCommentOn: (what: string) => string; filesCommentPlaceholder: string; filesCopy: string; filesCopyPath: string; filesCopyRelativePath: string; filesCopyWhat: (what: string) => string; filesCut: string; filesDelete: string; filesDeleteConfirm: string; filesDeletePermanent: string; filesDeleteTitle: (name: string, count: number) => string; filesDeleteToTrash: string; filesDiffSource: string; filesDiffsToolbar: string; filesDismiss: string; filesDropHere: string; filesDuplicate: string; filesEmptyFolder: string; filesEntryDenied: string; filesEntryExists: string; filesEntryInvalid: string; filesEntryMissing: string; filesEntryTooLarge: string; filesFileNames: string; filesFindInDiff: string; filesFindInDiffs: string; filesGoToDefinition: string; filesHideFileList: string; filesHideIgnored: string; filesHideTree: string; filesImageSize: (name: string, width: number, height: number) => string; filesLanguageServer: string; filesLineHits: (count: number, more: boolean, files: number) => string; filesMatchCase: string; filesMatchingLines: string; filesMatchLine: (path: string, line: number, text: string) => string; filesMediaFailed: (name: string) => string; filesMoreLines: (count: number) => string; filesMoveToTrash: string; filesNameHits: (count: number, more: boolean) => string; filesNewFile: string; filesNewFolder: string; filesNoChanged: string; filesNoChangesHint: string; filesNoChangesYet: string; filesNoChat: string; filesNoFolder: string; filesNoResults: string; filesNotFound: string; filesNoTool: string; filesNoWorkingTree: string; filesOpenEditor: string; filesOpenFiles: string; filesOpenFolderInEditor: string; filesOpenInEditor: string; filesPaste: string; filesPickFile: string; filesPlainView: string; filesRefresh: string; filesRename: string; filesRevealFinder: string; filesRevealInFinder: string; filesSearchFiles: string; filesSearchInChanges: string; filesSearchInFiles: string; filesSearching: string; filesSearchNamesOnly: string; filesSelectedLines: string; filesSelection: string; filesSessionNoFolder: string; filesShowChanges: string; filesShowChangesLarge: string; filesShowFileList: string; filesShowIgnored: string; filesShowTree: string; filesSourceSession: string; filesSourceWorking: string; filesSplit: string; filesToAdd: string; filesTooLarge: (kb: number) => string; filesTruncated: (shown: number, total: number, atLeast: boolean) => string; filesWorkingTreeClean: string; filesWrap: string }>`): Overrides for the built-in strings. Keys you leave out keep the default English label.

Source: [ui/src/files/FilesProvider.tsx:34](https://github.com/Tahul/zidane/blob/main/ui/src/files/FilesProvider.tsx#L34)

### `FilesTab`

Component.

The Files tab: the workspace tree beside the open files (viewer, editor, working-tree diff), search in files,
find, diagnostics and language-server findings, over the [`FilesProvider`](https://zidane.si/docs/reference/ui-files.md#FilesProvider)'s host. Loads on first render.

```ts
function FilesTab(props: FilesTabProps): Element
```

**Parameters**

- `props` (`FilesTabProps`): The scope, the app's layout store, chat target, hooks and hand-overs.

**Returns** `Element`

**Props**

- `chat?` (`FilesChatTarget | null`): The chat "Add to chat" and review comments go to (`null`: shown disabled).
- `className?` (`string`): Classes on the root.
- `fileActions?` (`boolean`): The tree's file actions (new file and folder, rename, move, copy, delete, drops), when the host has them. Default: true.
- `layout?` (`FilesLayoutStore`): Where the scope's layout lives (open tabs, the active file, the tree toggles and width). Default: in memory, per mount.
- `onOpenExternal?` (`(absolutePath: string) => Promise<boolean>`): ⌘/Ctrl-click on a tree row: open the absolute path outside the panel. Resolves false to open it here instead.
- `onRevealTaken?` (`() => void`): The tab took `revealRequest`: the app clears it.
- `readOnly?` (`boolean`): Nothing changes: no saves, no file actions. Default: false.
- `renderTabGlyph?` (`(path: string) => ReactNode`): A file tab's glyph (a stable function). Default: the file's icon.
- `revealRequest?` (`string | null`): An absolute path handed over from elsewhere (a folder ends with `/`): opened, or revealed in the tree.
- `scope` (`FilesScope`): The folder the tab works from, optionally bound to a session (its edits mark changed files).
- `style?` (`CSSProperties`): Styles on the root.
- `takeRevealPosition?` (`(absolutePath: string) => FilesRevealPosition | null`): The position to reveal in a handed-over file, taken once.
- `useEdits?` (`SessionEditsHook`): The bound session's edit events (a hook). Without it, changed files come from git status alone.
- `useKeyScope?` (`FilesKeyScopeHook`): Registers the tab's next / previous / close / find keys (a hook).

Source: [ui/src/files/lazy-tabs.tsx:21](https://github.com/Tahul/zidane/blob/main/ui/src/files/lazy-tabs.tsx#L21)

## Functions

### `attachmentName`

Function.

`snippet-index.ts-L2toL8.md`: what the composer chip shows.

```ts
function attachmentName(prefix: string, filePath: string, label: string | null): string
```

**Parameters**

- `prefix` (`string`): `snippet`, `comment` or `diagnostic` (or an app's own kind).
- `filePath` (`string`): The file the excerpt is from.
- `label` (`string | null`): Its line range (`L2 to L8`), or `null` for a free selection.

**Returns** `string`

Source: [ui/src/files/code-excerpt.ts:132](https://github.com/Tahul/zidane/blob/main/ui/src/files/code-excerpt.ts#L132)

### `codeAttachmentLabel`

Function.

The icon and name a non-image attachment shows: a code attachment (`comment-<file>-L1toL9.md`,
`snippet-<file>.md`, a terminal's lines) shows its source's icon and name with the range, a PDF the PDF
icon, anything else `fallbackIcon`. An app's `attachmentLabel` renderer slot.

```ts
function codeAttachmentLabel(name: string, fallbackIcon?: string): AttachmentLabelParts
```

**Parameters**

- `name` (`string`): The attachment's file name.
- `fallbackIcon?` (`string`, default `'i-ph-file'`): The icon of any other file.

**Returns** `AttachmentLabelParts`

Source: [ui/src/files/code-excerpt.ts:167](https://github.com/Tahul/zidane/blob/main/ui/src/files/code-excerpt.ts#L167)

### `fenceFor`

Function.

Fence long enough to wrap content that itself contains backticks.

```ts
function fenceFor(text: string): string
```

**Parameters**

- `text` (`string`): The content to fence.

**Returns** `string`

Source: [ui/src/files/code-excerpt.ts:94](https://github.com/Tahul/zidane/blob/main/ui/src/files/code-excerpt.ts#L94)

### `parseCodeAttachmentName`

Function.

Inverse of `attachmentName`; null for any other attachment.

```ts
function parseCodeAttachmentName(name: string): CodeAttachmentInfo | null
```

**Parameters**

- `name` (`string`): An attachment's name.

**Returns** `CodeAttachmentInfo | null`

Source: [ui/src/files/code-excerpt.ts:152](https://github.com/Tahul/zidane/blob/main/ui/src/files/code-excerpt.ts#L152)

### `serializeTerminalExcerpt`

Function.

A terminal selection as a composer attachment, named and fenced like code excerpts so its chip reads
`Terminal 1`, then `lines 12–18`.

```ts
function serializeTerminalExcerpt(e: TerminalExcerpt): { body: string; name: string }
```

**Parameters**

- `e` (`TerminalExcerpt`): The selection.

**Returns** `{ body: string; name: string }`

Source: [ui/src/files/code-excerpt.ts:232](https://github.com/Tahul/zidane/blob/main/ui/src/files/code-excerpt.ts#L232)

### `terminalRangeDetail`

Function.

`L12 to L18` → `lines 12–18`, `L3` → `line 3`: the chip's wording.

```ts
function terminalRangeDetail(rangeLabel: string | null): string | undefined
```

**Parameters**

- `rangeLabel` (`string | null`): A [`terminalRangeLabel`](https://zidane.si/docs/reference/ui-files.md#terminalRangeLabel), or `null`.

**Returns** `string | undefined`

Source: [ui/src/files/code-excerpt.ts:214](https://github.com/Tahul/zidane/blob/main/ui/src/files/code-excerpt.ts#L214)

### `terminalRangeLabel`

Function.

A terminal selection's range label: `L12 to L18`, `L3` for one line (either order).

```ts
function terminalRangeLabel(startLine: number, endLine: number): string
```

**Parameters**

- `startLine` (`number`): One end of the selection (1-based).
- `endLine` (`number`): The other end.

**Returns** `string`

Source: [ui/src/files/code-excerpt.ts:203](https://github.com/Tahul/zidane/blob/main/ui/src/files/code-excerpt.ts#L203)

### `useEditorPrefs`

Function.

The editor preferences of the nearest [`FilesProvider`](https://zidane.si/docs/reference/ui-files.md#FilesProvider)'s host (the defaults without a provider or without
`editorPrefs`). Re-renders when they change.

```ts
function useEditorPrefs(): EditorState
```

**Returns** `EditorState`

Source: [ui/src/files/FilesProvider.tsx:55](https://github.com/Tahul/zidane/blob/main/ui/src/files/FilesProvider.tsx#L55)

### `useFilesHost`

Function.

Returns the [`FilesHost`](https://zidane.si/docs/reference/ui-files-headless.md#FilesHost) from the nearest [`FilesProvider`](https://zidane.si/docs/reference/ui-files.md#FilesProvider). Throws when called outside one.

```ts
function useFilesHost(): FilesHost
```

**Returns** `FilesHost`

Source: [ui/src/files/FilesProvider.tsx:43](https://github.com/Tahul/zidane/blob/main/ui/src/files/FilesProvider.tsx#L43)

### `useFilesLabels`

Function.

Returns the Files and Diffs tabs' strings: the defaults merged with any overrides given to `FilesProvider` or `LabelsProvider`.

```ts
function useFilesLabels(): { filesAddToChat: string; filesAddToPrompt: string; filesAddWhatToChat: (what: string) => string; filesAfter: string; filesAllFiles: string; filesBefore: string; filesBinary: string; filesBlankLines: string; filesCancel: string; filesChangedOnly: string; filesCheckedBy: (ran: readonly string[], failed: readonly string[]) => string; filesCheckFailed: (tools: readonly string[]) => string; filesChecking: string; filesClearSearch: string; filesCloseSearch: string; filesCloseSearchHint: string; filesCommentOn: (what: string) => string; filesCommentPlaceholder: string; filesCopy: string; filesCopyPath: string; filesCopyRelativePath: string; filesCopyWhat: (what: string) => string; filesCut: string; filesDelete: string; filesDeleteConfirm: string; filesDeletePermanent: string; filesDeleteTitle: (name: string, count: number) => string; filesDeleteToTrash: string; filesDiffSource: string; filesDiffsToolbar: string; filesDismiss: string; filesDropHere: string; filesDuplicate: string; filesEmptyFolder: string; filesEntryDenied: string; filesEntryExists: string; filesEntryInvalid: string; filesEntryMissing: string; filesEntryTooLarge: string; filesFileNames: string; filesFindInDiff: string; filesFindInDiffs: string; filesGoToDefinition: string; filesHideFileList: string; filesHideIgnored: string; filesHideTree: string; filesImageSize: (name: string, width: number, height: number) => string; filesLanguageServer: string; filesLineHits: (count: number, more: boolean, files: number) => string; filesMatchCase: string; filesMatchingLines: string; filesMatchLine: (path: string, line: number, text: string) => string; filesMediaFailed: (name: string) => string; filesMoreLines: (count: number) => string; filesMoveToTrash: string; filesNameHits: (count: number, more: boolean) => string; filesNewFile: string; filesNewFolder: string; filesNoChanged: string; filesNoChangesHint: string; filesNoChangesYet: string; filesNoChat: string; filesNoFolder: string; filesNoResults: string; filesNotFound: string; filesNoTool: string; filesNoWorkingTree: string; filesOpenEditor: string; filesOpenFiles: string; filesOpenFolderInEditor: string; filesOpenInEditor: string; filesPaste: string; filesPickFile: string; filesPlainView: string; filesRefresh: string; filesRename: string; filesRevealFinder: string; filesRevealInFinder: string; filesSearchFiles: string; filesSearchInChanges: string; filesSearchInFiles: string; filesSearching: string; filesSearchNamesOnly: string; filesSelectedLines: string; filesSelection: string; filesSessionNoFolder: string; filesShowChanges: string; filesShowChangesLarge: string; filesShowFileList: string; filesShowIgnored: string; filesShowTree: string; filesSourceSession: string; filesSourceWorking: string; filesSplit: string; filesToAdd: string; filesTooLarge: (kb: number) => string; filesTruncated: (shown: number, total: number, atLeast: boolean) => string; filesWorkingTreeClean: string; filesWrap: string }
```

**Returns** `{ filesAddToChat: string; filesAddToPrompt: string; filesAddWhatToChat: (what: string) => string; filesAfter: string; filesAllFiles: string; filesBefore: string; filesBinary: string; filesBlankLines: string; filesCancel: string; filesChangedOnly: string; filesCheckedBy: (ran: readonly string[], failed: readonly string[]) => string; filesCheckFailed: (tools: readonly string[]) => string; filesChecking: string; filesClearSearch: string; filesCloseSearch: string; filesCloseSearchHint: string; filesCommentOn: (what: string) => string; filesCommentPlaceholder: string; filesCopy: string; filesCopyPath: string; filesCopyRelativePath: string; filesCopyWhat: (what: string) => string; filesCut: string; filesDelete: string; filesDeleteConfirm: string; filesDeletePermanent: string; filesDeleteTitle: (name: string, count: number) => string; filesDeleteToTrash: string; filesDiffSource: string; filesDiffsToolbar: string; filesDismiss: string; filesDropHere: string; filesDuplicate: string; filesEmptyFolder: string; filesEntryDenied: string; filesEntryExists: string; filesEntryInvalid: string; filesEntryMissing: string; filesEntryTooLarge: string; filesFileNames: string; filesFindInDiff: string; filesFindInDiffs: string; filesGoToDefinition: string; filesHideFileList: string; filesHideIgnored: string; filesHideTree: string; filesImageSize: (name: string, width: number, height: number) => string; filesLanguageServer: string; filesLineHits: (count: number, more: boolean, files: number) => string; filesMatchCase: string; filesMatchingLines: string; filesMatchLine: (path: string, line: number, text: string) => string; filesMediaFailed: (name: string) => string; filesMoreLines: (count: number) => string; filesMoveToTrash: string; filesNameHits: (count: number, more: boolean) => string; filesNewFile: string; filesNewFolder: string; filesNoChanged: string; filesNoChangesHint: string; filesNoChangesYet: string; filesNoChat: string; filesNoFolder: string; filesNoResults: string; filesNotFound: string; filesNoTool: string; filesNoWorkingTree: string; filesOpenEditor: string; filesOpenFiles: string; filesOpenFolderInEditor: string; filesOpenInEditor: string; filesPaste: string; filesPickFile: string; filesPlainView: string; filesRefresh: string; filesRename: string; filesRevealFinder: string; filesRevealInFinder: string; filesSearchFiles: string; filesSearchInChanges: string; filesSearchInFiles: string; filesSearching: string; filesSearchNamesOnly: string; filesSelectedLines: string; filesSelection: string; filesSessionNoFolder: string; filesShowChanges: string; filesShowChangesLarge: string; filesShowFileList: string; filesShowIgnored: string; filesShowTree: string; filesSourceSession: string; filesSourceWorking: string; filesSplit: string; filesToAdd: string; filesTooLarge: (kb: number) => string; filesTruncated: (shown: number, total: number, atLeast: boolean) => string; filesWorkingTreeClean: string; filesWrap: string }`

Source: [ui/src/files/useFilesLabels.ts:11](https://github.com/Tahul/zidane/blob/main/ui/src/files/useFilesLabels.ts#L11)

## Interfaces

### `CodeAttachmentInfo`

Interface.

What a code attachment's name says: its kind, file and line range.

```ts
interface CodeAttachmentInfo
```

**Properties**

- `file` (`string`): Basename of the file the excerpt came from.
- `kind` (`'terminal' | 'comment' | 'snippet' | 'diagnostic'`): `terminal`: lines from a terminal ([`serializeTerminalExcerpt`](https://zidane.si/docs/reference/ui-files.md#serializeTerminalExcerpt)); `file` is then the terminal's label.
- `rangeLabel` (`string | null`): `L12 to L18` or null for a free text selection.

Source: [ui/src/files/code-excerpt.ts:138](https://github.com/Tahul/zidane/blob/main/ui/src/files/code-excerpt.ts#L138)

### `DiffsTabProps`

Interface.

Props for [`DiffsTab`](https://zidane.si/docs/reference/ui-files.md#DiffsTab).

```ts
interface DiffsTabProps
```

**Properties**

- `chat?` (`FilesChatTarget | null`): The chat review comments go to (`null`: shown disabled).
- `className?` (`string`): Classes on the root.
- `createParseWorker?` (`() => Worker`): Makes the worker that parses working-tree patches (it answers `parseWorkingTree`). Default: parse on this thread.
- `onWorkingTreeTaken?` (`() => void`): The tab took `workingTreeRequest`: the app clears it.
- `scope` (`FilesScope`): The folder the tab works from; bound to a session, it shows that session's edits too.
- `style?` (`CSSProperties`): Styles on the root.
- `useEdits?` (`SessionEditsHook`): The bound session's edit events (a hook). Without it, the Session source is empty.
- `useKeyScope?` (`FilesKeyScopeHook`): Registers the tab's next / previous / close / find keys (a hook).
- `workingTreeRequest?` (`number`): A count the app bumps to open the working tree (the git bar's changes); 0: none asked.

Source: [ui/src/files/DiffsTab.tsx:70](https://github.com/Tahul/zidane/blob/main/ui/src/files/DiffsTab.tsx#L70)

### `EditorEnvironmentRootProps`

Interface.

Props for [`EditorEnvironmentRoot`](https://zidane.si/docs/reference/ui-files.md#EditorEnvironmentRoot).

```ts
interface EditorEnvironmentRootProps
```

**Properties**

- `children` (`ReactNode`): The editor surfaces.

Source: [ui/src/files/EditorEnvironmentRoot.tsx:19](https://github.com/Tahul/zidane/blob/main/ui/src/files/EditorEnvironmentRoot.tsx#L19)

### `FilesProviderProps`

Interface.

Props for [`FilesProvider`](https://zidane.si/docs/reference/ui-files.md#FilesProvider).

```ts
interface FilesProviderProps
```

**Properties**

- `children` (`ReactNode`): The components that read from `host`.
- `host` (`FilesHost`): The host the Files and Diffs tabs below read files, git state and editor preferences from.
- `labels?` (`Partial<{ filesAddToChat: string; filesAddToPrompt: string; filesAddWhatToChat: (what: string) => string; filesAfter: string; filesAllFiles: string; filesBefore: string; filesBinary: string; filesBlankLines: string; filesCancel: string; filesChangedOnly: string; filesCheckedBy: (ran: readonly string[], failed: readonly string[]) => string; filesCheckFailed: (tools: readonly string[]) => string; filesChecking: string; filesClearSearch: string; filesCloseSearch: string; filesCloseSearchHint: string; filesCommentOn: (what: string) => string; filesCommentPlaceholder: string; filesCopy: string; filesCopyPath: string; filesCopyRelativePath: string; filesCopyWhat: (what: string) => string; filesCut: string; filesDelete: string; filesDeleteConfirm: string; filesDeletePermanent: string; filesDeleteTitle: (name: string, count: number) => string; filesDeleteToTrash: string; filesDiffSource: string; filesDiffsToolbar: string; filesDismiss: string; filesDropHere: string; filesDuplicate: string; filesEmptyFolder: string; filesEntryDenied: string; filesEntryExists: string; filesEntryInvalid: string; filesEntryMissing: string; filesEntryTooLarge: string; filesFileNames: string; filesFindInDiff: string; filesFindInDiffs: string; filesGoToDefinition: string; filesHideFileList: string; filesHideIgnored: string; filesHideTree: string; filesImageSize: (name: string, width: number, height: number) => string; filesLanguageServer: string; filesLineHits: (count: number, more: boolean, files: number) => string; filesMatchCase: string; filesMatchingLines: string; filesMatchLine: (path: string, line: number, text: string) => string; filesMediaFailed: (name: string) => string; filesMoreLines: (count: number) => string; filesMoveToTrash: string; filesNameHits: (count: number, more: boolean) => string; filesNewFile: string; filesNewFolder: string; filesNoChanged: string; filesNoChangesHint: string; filesNoChangesYet: string; filesNoChat: string; filesNoFolder: string; filesNoResults: string; filesNotFound: string; filesNoTool: string; filesNoWorkingTree: string; filesOpenEditor: string; filesOpenFiles: string; filesOpenFolderInEditor: string; filesOpenInEditor: string; filesPaste: string; filesPickFile: string; filesPlainView: string; filesRefresh: string; filesRename: string; filesRevealFinder: string; filesRevealInFinder: string; filesSearchFiles: string; filesSearchInChanges: string; filesSearchInFiles: string; filesSearching: string; filesSearchNamesOnly: string; filesSelectedLines: string; filesSelection: string; filesSessionNoFolder: string; filesShowChanges: string; filesShowChangesLarge: string; filesShowFileList: string; filesShowIgnored: string; filesShowTree: string; filesSourceSession: string; filesSourceWorking: string; filesSplit: string; filesToAdd: string; filesTooLarge: (kb: number) => string; filesTruncated: (shown: number, total: number, atLeast: boolean) => string; filesWorkingTreeClean: string; filesWrap: string }>`): Overrides for the built-in strings. Keys you leave out keep the default English label.

Source: [ui/src/files/FilesProvider.tsx:20](https://github.com/Tahul/zidane/blob/main/ui/src/files/FilesProvider.tsx#L20)

### `FilesRevealPosition`

Interface.

A position to reveal once a handed-over file opens (a terminal link's `src/app.ts:12:5`), 1-based.

```ts
interface FilesRevealPosition
```

**Properties**

- `column` (`number`): 1-based column.
- `line` (`number`): 1-based line.

Source: [ui/src/files/FilesTab.tsx:63](https://github.com/Tahul/zidane/blob/main/ui/src/files/FilesTab.tsx#L63)

### `FilesTabProps`

Interface.

Props for [`FilesTab`](https://zidane.si/docs/reference/ui-files.md#FilesTab).

```ts
interface FilesTabProps
```

**Properties**

- `chat?` (`FilesChatTarget | null`): The chat "Add to chat" and review comments go to (`null`: shown disabled).
- `className?` (`string`): Classes on the root.
- `fileActions?` (`boolean`): The tree's file actions (new file and folder, rename, move, copy, delete, drops), when the host has them. Default: true.
- `layout?` (`FilesLayoutStore`): Where the scope's layout lives (open tabs, the active file, the tree toggles and width). Default: in memory, per mount.
- `onOpenExternal?` (`(absolutePath: string) => Promise<boolean>`): ⌘/Ctrl-click on a tree row: open the absolute path outside the panel. Resolves false to open it here instead.
- `onRevealTaken?` (`() => void`): The tab took `revealRequest`: the app clears it.
- `readOnly?` (`boolean`): Nothing changes: no saves, no file actions. Default: false.
- `renderTabGlyph?` (`(path: string) => ReactNode`): A file tab's glyph (a stable function). Default: the file's icon.
- `revealRequest?` (`string | null`): An absolute path handed over from elsewhere (a folder ends with `/`): opened, or revealed in the tree.
- `scope` (`FilesScope`): The folder the tab works from, optionally bound to a session (its edits mark changed files).
- `style?` (`CSSProperties`): Styles on the root.
- `takeRevealPosition?` (`(absolutePath: string) => FilesRevealPosition | null`): The position to reveal in a handed-over file, taken once.
- `useEdits?` (`SessionEditsHook`): The bound session's edit events (a hook). Without it, changed files come from git status alone.
- `useKeyScope?` (`FilesKeyScopeHook`): Registers the tab's next / previous / close / find keys (a hook).

Source: [ui/src/files/FilesTab.tsx:71](https://github.com/Tahul/zidane/blob/main/ui/src/files/FilesTab.tsx#L71)

### `TerminalExcerpt`

Interface.

Lines selected in a terminal, to attach to the composer.

```ts
interface TerminalExcerpt
```

**Properties**

- `endLine` (`number`): Its last buffer line (1-based, inclusive).
- `label` (`string`): The terminal's label ("Terminal 1", or the agent's command).
- `startLine` (`number`): The selection's first buffer line (1-based, inclusive).
- `text` (`string`): The selected text.

Source: [ui/src/files/code-excerpt.ts:186](https://github.com/Tahul/zidane/blob/main/ui/src/files/code-excerpt.ts#L186)

## Types

### `FilesKeyScopeHook`

Type.

Registers a tab's key scope on its root element (next / previous / close / find), routed by the app's focus
handling. A hook: the same function on every render.

```ts
type FilesKeyScopeHook = (root: RefObject<HTMLElement | null>, scope: FilesKeyScope) => void
```

Source: [ui/src/files/tab-hooks.ts:15](https://github.com/Tahul/zidane/blob/main/ui/src/files/tab-hooks.ts#L15)

### `SessionEditsHook`

Type.

A session's edit events (`tool` events carrying an `edit`), as a stable array that changes only when an edit
lands (`null`: no session, no edits). A hook: the same function on every render.

```ts
type SessionEditsHook = (sessionId: string | null) => readonly SessionEditEvent[]
```

Source: [ui/src/files/tab-hooks.ts:21](https://github.com/Tahul/zidane/blob/main/ui/src/files/tab-hooks.ts#L21)