Documents and saving

​

Document identity

​

What changes the revision

​

Load a document

• Sets the revision to 0 and clears the undo history.
• Returns a Markdown document to formatted mode.
• Cancels pending image imports and any copy or print still in progress.
• Puts the caret at the end, takes focus off the editor’s text surfaces and leaves focus in a host control where it is. It doesn’t scroll to the caret.
• Sends one commandStateChanged and no changed.
• Works while the editor is read-only, and keeps editability, input preferences and the keymap as they are.

​

Reload a changed document

• The selection, where it still fits the new text.
• Focus and scroll position.
• Source mode, when both the old and the new text are Markdown.

​

Save the document

import { InkKitError } from '@aicayzer/inkkit'

declare function writeFile(path: string, text: string): Promise<void>

/** Writes the current text. Returns false when nothing was written. */
async function save(generation: number): Promise<boolean> {
  let snapshot
  try {
    snapshot = editor.snapshot(generation)
  } catch (error) {
    if (!(error instanceof InkKitError)) throw error
    console.error('Not saved:', error.code, error.message)
    return false
  }
  await writeFile(snapshot.documentId, snapshot.text)
  return true
}

​

Unsaved changes and dirty

​

Expected generations

• Required: insertText and keyDown, which carry native input.
• Optional, the last argument: the calls that read or change the document, its selection or focus, such as snapshot, commandState, format, paste, undo, printableSnapshot, clipboardSnapshot, focus and blur.
• Optional, checked only when given: reloadDocument.
• Carried by the argument: calls that take a text range or a heading check the version that the range’s snapshotId or the heading names.
• None: loadDocument, which brings its own generation, and editor settings such as setEditable, setTextInputPreferences, setKeymap, setViewport and setCommentsVisible.

​

Read-only mode

• Still allowed: selection, copying, find, navigation, folding callouts, snapshot, printableSnapshot, clipboardSnapshot, switching between formatted and source modes, and loading and reloading.
• Refused: every method that changes the document throws read-only, and so do undo and redo, which keep their history for when editing returns. Typing, paste, drop, cut, task toggles and image resizing don’t change content.
• When it starts: pending image imports are canceled, and a cut still waiting for your clipboard handler removes nothing.
• What it keeps: the text, revision, dirty, selection, focus and undo history. Editability also stays as it is across loads and reloads.

​

Switch and close documents

import { InkKitError, type DocumentSnapshot } from '@aicayzer/inkkit'

declare function writeFile(path: string, text: string): Promise<void>

let generation = 1

/** The current text, or undefined when it can't be saved now. */
function capture(): DocumentSnapshot | undefined {
  try {
    return editor.snapshot(generation)
  } catch (error) {
    if (!(error instanceof InkKitError)) throw error
    console.error('Not saved:', error.code, error.message)
    return undefined
  }
}

async function switchTo(path: string, text: string): Promise<boolean> {
  const previous = capture()
  if (!previous) return false
  editor.loadDocument({
    documentId: path,
    generation: generation + 1,
    format: 'md',
    text,
  })
  generation += 1
  await writeFile(previous.documentId, previous.text)
  return true
}

async function close(): Promise<boolean> {
  const last = capture()
  if (!last) return false
  await editor.destroy()
  await writeFile(last.documentId, last.text)
  return true
}