Skip to content
zidane
UI kit reference

zidane-ui/files

import { … } from 'zidane-ui/files'ui/src/files/index.ts

Components#

DiffsTabComponent#

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's host. Loads on first render.

TypeScript
function DiffsTab(props: DiffsTabProps): Element

Parameters

Parameters
NameTypeDescription
propsDiffsTabProps

The scope, the app's hooks, chat target and requests.

Returns

Element

Props

DiffsTab props
NameTypeDescription
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.

scopeFilesScope

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.

ui/src/files/lazy-tabs.tsx:35

EditorEnvironmentRootComponent#

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

TypeScript
function EditorEnvironmentRoot(props: EditorEnvironmentRootProps): Element

Parameters

Parameters
NameTypeDescription
propsEditorEnvironmentRootProps

The children.

Returns

Element

Props

EditorEnvironmentRoot props
NameTypeDescription
childrenReactNode

The editor surfaces.

ui/src/files/EditorEnvironmentRoot.tsx:29

FilesProviderComponent#

Provides a FilesHost and optional label overrides to the Files and Diffs tabs below it.

TypeScript
function FilesProvider(props: FilesProviderProps): Element

Parameters

Parameters
NameTypeDescription
propsFilesProviderProps

Provider props: the host, optional labels, and the children to render.

Returns

Element

Props

FilesProvider props
NameTypeDescription
childrenReactNode

The components that read from host.

hostFilesHost

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.

ui/src/files/FilesProvider.tsx:34

FilesTabComponent#

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's host. Loads on first render.

TypeScript
function FilesTab(props: FilesTabProps): Element

Parameters

Parameters
NameTypeDescription
propsFilesTabProps

The scope, the app's layout store, chat target, hooks and hand-overs.

Returns

Element

Props

FilesTab props
NameTypeDescription
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.

scopeFilesScope

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).

ui/src/files/lazy-tabs.tsx:21

Functions#

attachmentNameFunction#

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

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

Parameters

Parameters
NameTypeDescription
prefixstring

snippet, comment or diagnostic (or an app's own kind).

filePathstring

The file the excerpt is from.

labelstring | null

Its line range (L2 to L8), or null for a free selection.

Returns

string

ui/src/files/code-excerpt.ts:132

codeAttachmentLabelFunction#

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.

TypeScript
function codeAttachmentLabel(name: string, fallbackIcon?: string): AttachmentLabelParts

Parameters

Parameters
NameTypeDefaultDescription
namestring

The attachment's file name.

fallbackIcon?string'i-ph-file'

The icon of any other file.

ui/src/files/code-excerpt.ts:167

fenceForFunction#

Fence long enough to wrap content that itself contains backticks.

TypeScript
function fenceFor(text: string): string

Parameters

Parameters
NameTypeDescription
textstring

The content to fence.

Returns

string

ui/src/files/code-excerpt.ts:94

parseCodeAttachmentNameFunction#

Inverse of attachmentName; null for any other attachment.

TypeScript
function parseCodeAttachmentName(name: string): CodeAttachmentInfo | null

Parameters

Parameters
NameTypeDescription
namestring

An attachment's name.

Returns

CodeAttachmentInfo | null

ui/src/files/code-excerpt.ts:152

serializeTerminalExcerptFunction#

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

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

Parameters

Parameters
NameTypeDescription
eTerminalExcerpt

The selection.

Returns

{ body: string; name: string }

ui/src/files/code-excerpt.ts:232

terminalRangeDetailFunction#

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

TypeScript
function terminalRangeDetail(rangeLabel: string | null): string | undefined

Parameters

Parameters
NameTypeDescription
rangeLabelstring | null

A terminalRangeLabel, or null.

Returns

string | undefined

ui/src/files/code-excerpt.ts:214

terminalRangeLabelFunction#

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

TypeScript
function terminalRangeLabel(startLine: number, endLine: number): string

Parameters

Parameters
NameTypeDescription
startLinenumber

One end of the selection (1-based).

endLinenumber

The other end.

Returns

string

ui/src/files/code-excerpt.ts:203

useEditorPrefsFunction#

The editor preferences of the nearest FilesProvider's host (the defaults without a provider or without editorPrefs). Re-renders when they change.

TypeScript
function useEditorPrefs(): EditorState

ui/src/files/FilesProvider.tsx:55

useFilesHostFunction#

Returns the FilesHost from the nearest FilesProvider. Throws when called outside one.

TypeScript
function useFilesHost(): FilesHost

Returns

FilesHost

ui/src/files/FilesProvider.tsx:43

useFilesLabelsFunction#

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

TypeScript
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 }

ui/src/files/useFilesLabels.ts:11

Interfaces#

CodeAttachmentInfoInterface#

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

TypeScript
interface CodeAttachmentInfo

Properties

CodeAttachmentInfo properties
NameTypeDescription
filestring

Basename of the file the excerpt came from.

kind'terminal' | 'comment' | 'snippet' | 'diagnostic'

terminal: lines from a terminal (serializeTerminalExcerpt); file is then the terminal's label.

rangeLabelstring | null

L12 to L18 or null for a free text selection.

ui/src/files/code-excerpt.ts:138

DiffsTabPropsInterface#

Props for DiffsTab.

TypeScript
interface DiffsTabProps

Properties

DiffsTabProps properties
NameTypeDescription
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.

scopeFilesScope

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.

ui/src/files/DiffsTab.tsx:70

EditorEnvironmentRootPropsInterface#

Props for EditorEnvironmentRoot.

TypeScript
interface EditorEnvironmentRootProps

Properties

EditorEnvironmentRootProps properties
NameTypeDescription
childrenReactNode

The editor surfaces.

ui/src/files/EditorEnvironmentRoot.tsx:19

FilesProviderPropsInterface#

Props for FilesProvider.

TypeScript
interface FilesProviderProps

Properties

FilesProviderProps properties
NameTypeDescription
childrenReactNode

The components that read from host.

hostFilesHost

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.

ui/src/files/FilesProvider.tsx:20

FilesRevealPositionInterface#

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

TypeScript
interface FilesRevealPosition

Properties

FilesRevealPosition properties
NameTypeDescription
columnnumber

1-based column.

linenumber

1-based line.

ui/src/files/FilesTab.tsx:63

FilesTabPropsInterface#

Props for FilesTab.

TypeScript
interface FilesTabProps

Properties

FilesTabProps properties
NameTypeDescription
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.

scopeFilesScope

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).

ui/src/files/FilesTab.tsx:71

TerminalExcerptInterface#

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

TypeScript
interface TerminalExcerpt

Properties

TerminalExcerpt properties
NameTypeDescription
endLinenumber

Its last buffer line (1-based, inclusive).

labelstring

The terminal's label ("Terminal 1", or the agent's command).

startLinenumber

The selection's first buffer line (1-based, inclusive).

textstring

The selected text.

ui/src/files/code-excerpt.ts:186

Types#

FilesKeyScopeHookType#

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.

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

ui/src/files/tab-hooks.ts:15

SessionEditsHookType#

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.

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

ui/src/files/tab-hooks.ts:21