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

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

## Components

### `FileView`

Component.

A file's text with syntax colors, line selection, token hovers and annotations; editable when `edit` is set.

```ts
function FileView<A>(props: FileViewProps<A>): Element
```

**Type parameters**

- `A`

**Parameters**

- `props` (`FileViewProps<A>`): See [`FileViewProps`](https://zidane.si/docs/reference/ui-code-editor-file-view.md#FileViewProps).

**Returns** `Element`

**Props**

- `annotations?` (`readonly LineAnnotation<A>[]`): Content anchored under lines (review comments); rendered by `renderAnnotation`.
- `className?` (`string`): Classes on pierre's file element.
- `contents` (`string`): The text to show (the initial text when editing; pierre owns the draft after that).
- `edit?` (`{ onChange: (contents: string, changes: readonly EditChange[]) => void; onComplete?: FileEditCompleteHandler<A, undefined>; options: EditorOptions<'file', A, undefined>; stateKey?: string }`): Editable session (pierre edit mode). `onEditChange` gets the live contents.
- `hideHeader?` (`boolean`): Drop pierre's file-name header.
- `name` (`string`): Display name; the language is inferred from its extension.
- `onContextMenu?` (`(e: MouseEvent<HTMLDivElement>) => void`): Right-click anywhere in the view (the host element, so shadow paths are intact).
- `onGutterAction?` (`(range: SelectedLineRange) => void`): Gutter "+" on hover / at the selection end; called with the range it covers.
- `onHighlighted?` (`() => void`): Fires once the rendered lines carry syntax tokens (the async highlight landed).
- `onSelectionEnd?` (`(range: SelectedLineRange | null) => void`): Gutter line selection finished; passing it turns line selection on.
- `onTokenClick?` (`(token: CodeToken, event: MouseEvent) => void`): Click on an identifier; the token carries the word and column under the pointer.
- `onTokenEnter?` (`(token: CodeToken, event: PointerEvent) => void`): Pointer entered / left a token (for hovers). Positions are 1-based line, 0-based char offset.
- `onTokenLeave?` (`() => void`): The pointer left the token it entered.
- `renderAnnotation?` (`(annotation: LineAnnotation<A>) => ReactNode`): Renders one entry of `annotations`.
- `selectedLines?` (`SelectedLineRange | null`): The selected line range, controlled by the owner; needs `onSelectionEnd`.
- `tabSize?` (`number`): CSS `tab-size` on the code root (pierre measures it from there).
- `virtualize?` (`{ className: string }`): Render only the visible lines: the view becomes its own scroll container
  (pierre's Virtualizer) with these classes. Big files open in one frame
  instead of building thousands of rows up front.
- `wrap?` (`boolean`): Wrap long lines instead of scrolling sideways.

Source: [ui/src/code/editor/FileView.tsx:452](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileView.tsx#L452)

## Constants

### `LINK_HIGHLIGHT`

Constant.

Name of the CSS custom highlight carrying the link underline (styled in `DIFFS_UNSAFE_CSS`).

```ts
const LINK_HIGHLIGHT = 'zg-link'
```

Source: [ui/src/code/editor/FileView.tsx:273](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileView.tsx#L273)

## Interfaces

### `CodeToken`

Interface.

The symbol under the pointer. Shiki paints `{ Foo, Bar }` or a whole
import line as one span and pierre reports hover per span, so `FileView`
resolves the identifier at the pointer itself: `word` is that identifier
(offsets relative to `text`), `column` the 1-based column of the character
under the pointer, which is what a language server wants. `onTokenEnter`
fires again when the pointer crosses into another word of the same span;
a drawn link counts as one symbol (see `link`).

```ts
interface CodeToken
```

**Properties**

- `column` (`number`): 1-based column of the character under the pointer.
- `element` (`HTMLElement`): The span's element, inside pierre's shadow root.
- `lineCharStart` (`number`): 0-based start of the highlighter span.
- `lineNumber` (`number`): 1-based line of the token.
- `link` (`(on: boolean, columns?: { column: number; endColumn: number }) => void`): Underline this word, or `columns` of its line (1-based, `endColumn`
  exclusive; may cross highlighter spans), for the go-to-definition
  affordance; `false` removes it. Until removed, the link counts as one
  symbol: moving inside it fires nothing, and a click anywhere in it is a
  click on it.
- `text` (`string`): The span's source text.
- `word` (`WordSpan`): The identifier under the pointer, offsets relative to `text`.

Source: [ui/src/code/editor/FileView.tsx:37](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileView.tsx#L37)

### `EditChange`

Interface.

One editor change: replaced range (0-based, before the change) and the inserted text.

```ts
interface EditChange
```

**Properties**

- `range` (`{ end: { character: number; line: number }; start: { character: number; line: number } }`): The replaced span, 0-based, in the document as it was before this change.
- `text` (`string`): What replaced it (empty for a deletion).

Source: [ui/src/code/editor/FileView.tsx:21](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileView.tsx#L21)

### `FileViewProps`

Interface.

Props of [`FileView`](https://zidane.si/docs/reference/ui-code-editor-file-view.md#FileView); `A` is the annotation payload type.

```ts
interface FileViewProps<A = unknown>
```

**Type parameters**

- `A` (default `unknown`)

**Properties**

- `annotations?` (`readonly LineAnnotation<A>[]`): Content anchored under lines (review comments); rendered by `renderAnnotation`.
- `className?` (`string`): Classes on pierre's file element.
- `contents` (`string`): The text to show (the initial text when editing; pierre owns the draft after that).
- `edit?` (`{ onChange: (contents: string, changes: readonly EditChange[]) => void; onComplete?: FileEditCompleteHandler<A, undefined>; options: EditorOptions<'file', A, undefined>; stateKey?: string }`): Editable session (pierre edit mode). `onEditChange` gets the live contents.
- `hideHeader?` (`boolean`): Drop pierre's file-name header.
- `name` (`string`): Display name; the language is inferred from its extension.
- `onContextMenu?` (`(e: MouseEvent<HTMLDivElement>) => void`): Right-click anywhere in the view (the host element, so shadow paths are intact).
- `onGutterAction?` (`(range: SelectedLineRange) => void`): Gutter "+" on hover / at the selection end; called with the range it covers.
- `onHighlighted?` (`() => void`): Fires once the rendered lines carry syntax tokens (the async highlight landed).
- `onSelectionEnd?` (`(range: SelectedLineRange | null) => void`): Gutter line selection finished; passing it turns line selection on.
- `onTokenClick?` (`(token: CodeToken, event: MouseEvent) => void`): Click on an identifier; the token carries the word and column under the pointer.
- `onTokenEnter?` (`(token: CodeToken, event: PointerEvent) => void`): Pointer entered / left a token (for hovers). Positions are 1-based line, 0-based char offset.
- `onTokenLeave?` (`() => void`): The pointer left the token it entered.
- `renderAnnotation?` (`(annotation: LineAnnotation<A>) => ReactNode`): Renders one entry of `annotations`.
- `selectedLines?` (`SelectedLineRange | null`): The selected line range, controlled by the owner; needs `onSelectionEnd`.
- `tabSize?` (`number`): CSS `tab-size` on the code root (pierre measures it from there).
- `virtualize?` (`{ className: string }`): Render only the visible lines: the view becomes its own scroll container
  (pierre's Virtualizer) with these classes. Big files open in one frame
  instead of building thousands of rows up front.
- `wrap?` (`boolean`): Wrap long lines instead of scrolling sideways.

Source: [ui/src/code/editor/FileView.tsx:61](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/FileView.tsx#L61)