#DocumentEditor

DocumentEditor is the paginated rich-text surface for DOCX-compatible documents, reports, and long-form content. TipTap owns the logical document and selection model; the A3S Office kernel owns deterministic pagination, shaping, and file semantics.

#Properties

#Content contract

#Built-in navigation

The View ribbon opens a persistent heading outline on wide layouts and a focus-contained drawer on compact layouts. Searching the pane scans body text as well as headings, groups each result under its current section, highlights all matches, and moves the editor selection without adding a history entry. Selecting a compact result closes the drawer before restoring the body focus and exact text range.

The Pages view renders live physical-page thumbnails. Documents above 48 pages mount a window of at most 24 buttons plus the current and keyboard-roving pages when needed. Physical scroll spacers retain the document distance, and Home or End makes the first or last page reachable without mounting every page.

Heading and full-text collections use the same window contract above 48 rows. They mount at most 32 contiguous rows, plus sparse active, selected, and keyboard-roving rows when those fall outside the window. Native scroll distance, global list positions, Arrow traversal, Home/End, and exact search selection are preserved. Long-distance result jumps use an instant programmatic scroll for the selection frame and then restore the editor's normal scroll style.

#Built-in references

The References ribbon inserts captions, cross-references, footnotes, endnotes, page fields, dates, and citations into the controlled TipTap document. Caption numbers are part of each caption's accessible name. Caption deletion and reordering update every linked cross-reference in the same transaction: valid targets are renumbered and a dangling field renders as Missing reference instead of retaining a stale number. Undo restores the caption and its linked field state together.

#Built-in picture properties

Selecting a body image opens the contextual Picture ribbon. Fast wrapping and alignment commands remain available, while Picture Properties edits width and height in centimeters, a per-image aspect-ratio lock, wrapping, alignment, text distance, and alternative text in one responsive dialog.

Apply creates one undo entry and changes only fields edited by the user. An imported pixel dimension that was merely displayed as a rounded centimeter value therefore remains exact. Cancel or Escape leaves the document unchanged, keeps the image selected, and restores keyboard focus to the Picture Properties button.

#Host-defined selection menu

The menu factory receives an immutable selection snapshot with exact selected text, a structured fragment, adjacent context, complete plain text, synchronized HTML, and the current controlled content value. The callback also receives conflict-aware editing commands.

import type {
  DocumentContent,
  GetDocumentSelectionMenuItems,
} from '@a3s-lab/office/core';
import { DocumentEditor } from '@a3s-lab/office/react';

const getSelectionMenuItems: GetDocumentSelectionMenuItems = (snapshot) => [
  {
    id: 'rewrite',
    label: 'Rewrite',
    onSelect: async (context) => {
      const replacement = await rewriteWithModel({
        selection: snapshot.selection.text,
        before: snapshot.selection.beforeText,
        after: snapshot.selection.afterText,
        document: snapshot.document.text,
      });
      context.commands.replaceText(replacement);
    },
  },
];

export function Editor(props: {
  content: DocumentContent;
  onChange: (content: DocumentContent) => void;
}) {
  return (
    <DocumentEditor
      {...props}
      getSelectionMenuItems={getSelectionMenuItems}
    />
  );
}

Return or await asynchronous work so the editor can map the original range through unrelated transactions. If the selected text itself changes, a later replaceText returns stale-selection instead of modifying unrelated content. For an open-ended action such as “Ask AI”, collect the user's question in the host UI before dispatching a request. The Playground demonstrates this with a focused question composer and keeps the attached document context collapsed after submission instead of filling the assistant with raw context.

#Extensions

extensions accepts TipTap extensions. Keep the array identity stable and use unique extension names. A custom Node or Mark also needs DOCX import/export semantics if it must survive a file round trip. See the extension model.