Modes and locks

Modes

mode.kind puts the editor under a protection:

Props covers the prop, and Modes describes each kind as a reader experiences it. Nothing about the mode is written to the file.

A command reports false for whatever the protection refuses: under comment, a formatting command reports false while canAddComment still reports true. A control of your own reads the level with editingProtection:

import { editingProtection } from "@portone/docx-editor/commands";

const level = editingProtection(state); // "none" | "readOnly" | "comments"

Who may edit a comment answers the separate question of comment ownership.

Locked content

A lock is part of the document, travels with the file, and is honored in every mode; no prop turns it off. mode: { kind: "edit", locking: true } adds the built-in menu entries that lock and unlock.

import {
  lockSelection,
  selectionLock,
  unlockSelection,
} from "@portone/docx-editor/commands";

const lock = selectionLock(state); // "none" | "shut" | "lockable" | "locked" | "mixed"

selectionLock answers lockable when there is text to lock, locked when the selection reaches a lock to lift, mixed for both, and shut inside a group control. A selection covering nothing but controls with nothing inside them answers locked: there is a lock to lift and nothing to lay a new control over. A group control's contents refuse edits unless a control inside it opens them, and it carries no lock to lift. lockSelection and unlockSelection are ordinary commands and report whether they apply. Only a text selection can be locked, and the lock is written as a control around that text; a caret touching a locked field, or anywhere inside a locked cell, row, or control around paragraphs or tables, is enough to unlock it, except for a control with nothing inside it, which draws nothing and has to be covered by the selection instead.

selectionTouchesLocked(state) answers whether the selection meets locked content at all. documentHasLocked(doc) reports whether the document carries any lock.

When an edit is refused

The editor leaves the document as it was when an edit meets a lock or anything else it refuses. Pass onEditRefused to tell the reader why, in your own words:

import type { EditRefusal } from "@portone/docx-editor";

function explain(refusal: EditRefusal) {
  if (refusal.reason !== "lock") return;
  const [control] = refusal.controls;
  showToast(
    control?.tag === "PRICE_ROWS"
      ? "Unit prices are filled in by the system."
      : "This part of the document is locked."
  );
}

<DocxEditor document={file} mode={mode} onEditRefused={explain} />;

It is called for an edit made in the document body: typing, deleting, pasting, dropping, formatting, or a transaction your own code dispatches. It is called once per refused edit, so a held key calls it repeatedly; debounce a notice if that matters. A command reporting false dispatches nothing and calls nothing.

Each control carries its tag, alias, and id as the file wrote them (null when absent), its lock ("sdtLocked", "contentLocked", "sdtContentLocked", or "unlocked" for a group control), group, level ("inline", "block", "cell", or "row"), and the pos it starts at.

The editor's own right-click menus say "Locked content can't be edited." above their entries when the selection or the table under it holds locked content. Locked content is drawn with a yellow tint, an orange outline, and a not-allowed pointer; Styling covers changing that.