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

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

## Functions

### `useCodeDocument`

Function.

Keeps one document's draft, dirty state and disk conflicts consistent; see the module comment.

```ts
function useCodeDocument<D extends CodeDoc>(
  options: CodeDocumentOptions<D>,
): CodeDocument<D>
```

**Type parameters**

- `D` (`extends CodeDoc`)

**Parameters**

- `options` (`CodeDocumentOptions<D>`): The on-disk file and how to save and reload it.

**Returns** `CodeDocument<D>`

Source: [ui/src/code/editor/useCodeDocument.ts:83](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/useCodeDocument.ts#L83)

## Interfaces

### `CodeDoc`

Interface.

A file as read from disk.

```ts
interface CodeDoc
```

**Properties**

- `contents` (`string`): The file's text.
- `mtimeMs` (`number`): Its modification time (or any version stamp); a save checks it to spot a file that moved on.

Source: [ui/src/code/editor/useCodeDocument.ts:24](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/useCodeDocument.ts#L24)

### `CodeDocument`

Interface.

The document's live state and actions; pass it to `CodeEditor`.

```ts
interface CodeDocument<D extends CodeDoc = CodeDoc>
```

**Type parameters**

- `D` (`extends CodeDoc`, default `CodeDoc`)

**Properties**

- `base` (`D`): The on-disk text the editor works against.
- `conflict` (`boolean`): The file changed on disk while dirty; the editor shows Reload / Overwrite.
- `contents` (`string`): The text shown now: the draft while dirty, else `base`.
- `dirty` (`boolean`): The text differs from `base`.
- `discard` (`() => void`): Drops the draft and reseeds from the file on disk.
- `onEditorChange` (`(text: string, changes: readonly EditChange[]) => void`): Feed it the editor's changes (`CodeEditor` does).
- `resets` (`number`): Bumps each time the edit session restarts (adopted from disk, discarded): a key for the editor's state.
- `save` (`(force?: boolean) => Promise<void>`): Writes the draft (a no-op when clean or already saving); `force` overwrites a file that moved on. A refused save raises `conflict`, a failed one keeps the draft dirty.
- `seed` (`string`): What the editor is seeded with.

Source: [ui/src/code/editor/useCodeDocument.ts:57](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/useCodeDocument.ts#L57)

### `CodeDocumentOptions`

Interface.

What [`useCodeDocument`](https://zidane.si/docs/reference/ui-code-editor-use-code-document.md#useCodeDocument) takes; `D` can carry extra fields alongside the text and version.

```ts
interface CodeDocumentOptions<D extends CodeDoc>
```

**Type parameters**

- `D` (`extends CodeDoc`)

**Properties**

- `doc` (`D`): The latest on-disk truth.
- `initialBase?` (`D`): The file `initialDraft` was typed against; becomes `base` when a draft is given.
- `initialDraft?` (`string | null`): A draft left by an earlier view, read once at mount, and the file it was typed against.
- `onAdopt?` (`(doc: D, reset: boolean) => void`): `doc` is now the on-disk truth (saved, adopted or reloaded); `reset`: the edit session restarts.
- `onChange?` (`(text: string, changes: readonly EditChange[]) => void`): Every editor change, unthrottled (a language server's sync).
- `onDraft?` (`(text: string | null, base: D) => void`): The live draft, throttled; `null` once it matches `base` again.
- `reload` (`() => Promise<D | null>`): The file as it is on disk now; `null` when it is gone.
- `save` (`(text: string, base: D, force: boolean) => Promise<SaveOutcome<D>>`): Write `text`. `force`: overwrite whatever is on disk now (the conflict bar's Overwrite).
- `throttleMs?` (`number`): Least time between `onDraft` reports while typing, in ms (default 200).

Source: [ui/src/code/editor/useCodeDocument.ts:35](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/useCodeDocument.ts#L35)

## Types

### `SaveOutcome`

Type.

What the owner's `save` reports: the file as written, or `changed` when it moved on since `base`.

```ts
type SaveOutcome<D extends CodeDoc> = 
  | { doc: D; ok: true }
  | { ok: false; reason: 'changed' }
```

**Type parameters**

- `D` (`extends CodeDoc`)

Source: [ui/src/code/editor/useCodeDocument.ts:32](https://github.com/Tahul/zidane/blob/main/ui/src/code/editor/useCodeDocument.ts#L32)