Skip to content
zidane
UI kit reference

code/editor/useCodeDocument

import { … } from 'zidane-ui/code/editor'ui/src/code/editor/useCodeDocument.ts

Functions#

useCodeDocumentFunction#

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

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

Type parameters

Type parameters
NameTypeDescription
Dextends CodeDoc

Parameters

Parameters
NameTypeDescription
optionsCodeDocumentOptions<D>

The on-disk file and how to save and reload it.

Returns

CodeDocument<D>

ui/src/code/editor/useCodeDocument.ts:83

Interfaces#

CodeDocInterface#

A file as read from disk.

TypeScript
interface CodeDoc

Properties

CodeDoc properties
NameTypeDescription
contentsstring

The file's text.

mtimeMsnumber

Its modification time (or any version stamp); a save checks it to spot a file that moved on.

ui/src/code/editor/useCodeDocument.ts:24

CodeDocumentInterface#

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

TypeScript
interface CodeDocument<D extends CodeDoc = CodeDoc>

Type parameters

CodeDocument type parameters
NameTypeDefaultDescription
Dextends CodeDocCodeDoc

Properties

CodeDocument properties
NameTypeDescription
baseD

The on-disk text the editor works against.

conflictboolean

The file changed on disk while dirty; the editor shows Reload / Overwrite.

contentsstring

The text shown now: the draft while dirty, else base.

dirtyboolean

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

resetsnumber

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.

seedstring

What the editor is seeded with.

ui/src/code/editor/useCodeDocument.ts:57

CodeDocumentOptionsInterface#

What useCodeDocument takes; D can carry extra fields alongside the text and version.

TypeScript
interface CodeDocumentOptions<D extends CodeDoc>

Type parameters

CodeDocumentOptions type parameters
NameTypeDescription
Dextends CodeDoc

Properties

CodeDocumentOptions properties
NameTypeDescription
docD

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

ui/src/code/editor/useCodeDocument.ts:35

Types#

SaveOutcomeType#

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

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

Type parameters

SaveOutcome type parameters
NameTypeDescription
Dextends CodeDoc

ui/src/code/editor/useCodeDocument.ts:32