Rich text / foldkit-richtext-dom

Configuring an editor placement

editorAt(hostId, placement) accepts the following optional settings:

  • rendering: Maps marks and node kinds to DOM elements; defaults to foldkit-richtext's built-in names. Marks render inside their text run element so run boundaries remain intact for selection mapping.
  • vocabulary: { marks, nodes } registries that refuse disallowed edits immediately in update rather than waiting for validate.
  • inputRules: Rules run on typed characters, such as markdownInputRules from foldkit-richtext-markdown. When a vocabulary refuses a rule's transformation, the typed text still inserts normally.
  • decorate: Pure (document) => DecorationSet callback evaluated on mount and on every patch—for example, syntax highlighting. Highlights derived from application state (search matches, remote cursors) go through the overlay(hostId, decorations) Command instead, which renders after decorate and preserves the caret. Use focus(hostId, selection) to move focus into the editor from external controls and scroll the target into view.
  • keymap: Custom { chord, command } bindings (where Mod is Ctrl or Cmd) checked before the built-in chords.
  • slashEntries: Custom slash-menu items resolved on Enter and shared with your menu view.
  • label / labelledBy: Accessible name written as aria-label or aria-labelledby on the role="textbox" root. Passing both is a type error. Without either, an editor inside a labelled role="group" (such as a foldkit-mixins-form field) adopts the group's label after hydration.
  • placeholder: Text shown via data-placeholder and aria-placeholder when RichText.isBlank(document) is true. Style [data-placeholder]::before in CSS so placeholder text stays out of the document content.
  • lineHint: Hint text set on data-hint for the empty paragraph holding a collapsed caret (for example, "Type / for blocks"), styled with [contenteditable]:focus [data-hint]::before.
  • serverRendered: Boolean thunk indicating server-rendered markup is already present to adopt on mount.

Empty lines automatically render a <br data-richtext-filler> after their run so the browser can place and display a caret on blank lines; importers strip it and it holds no position.

Each placement option is stored per hostId in foldkit-richtext-dom/host (placeRendering/renderingFor, placeVocabulary/vocabularyFor, and siblings), surviving unmount and remount under the same hostId.

When the document changes outside an edit

body.view keys its host element by the Document object identity produced by editor transitions. When your parent update replaces model.document via an external event (loading a record, resetting a form, restoring a revision), the host mounts fresh. Always commit the exact Document instance returned by an edit rather than cloning it, or every keystroke will remount the editor and drop the caret.

When a replacement continues the live document—such as incoming collaborative edits—return patchTo(hostId, previous, next) in the same transition. Pass the previous and next Document objects along with the mapped next.selection so untouched DOM nodes keep their elements and the caret moves to the right spot.