# Modes and locks

Source: https://docx-editor.portone.io/docs/editor-api/modes-and-locks

What each mode lets through, and the locks the document itself carries.

## Modes [#modes]

`mode.kind` puts the editor under a protection:

| `mode.kind` | What goes through                                                              |
| ----------- | ------------------------------------------------------------------------------ |
| `readOnly`  | Nothing. The text can be selected and copied; comments can be read.            |
| `comment`   | Comments alone: adding, editing, deleting, replying, resolving, and reopening. |
| `edit`      | Everything.                                                                    |

[Props](https://docx-editor.portone.io/docs/props.md#mode) covers the prop, and [Modes](https://docx-editor.portone.io/docs/features/modes.md) 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`:

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

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

[Who may edit a comment](https://docx-editor.portone.io/docs/editor-api/comments-and-notes.md#who-may-edit-a-comment) answers the
separate question of comment ownership.

## Locked content [#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.

```tsx
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 [#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:

```tsx
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.

| Field      | What it holds                                                                                                                                                                                                                                                                                                                                 |
| ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `reason`   | `"lock"`, `"protection"` (the `mode` takes no such edit), `"controlEdge"` (a keystroke would join text across the edge of a content control around paragraphs), `"preserved"` (the edit would remove or reorder content the editor keeps without editing, such as a bookmark's ends), or `"section"` (the edit would remove a section break). |
| `action`   | `"insert"`, `"delete"`, `"replace"`, or `"format"`.                                                                                                                                                                                                                                                                                           |
| `pos`      | Where the refused edit starts.                                                                                                                                                                                                                                                                                                                |
| `controls` | For `"lock"`, the locked controls the edit reached, innermost first; empty otherwise.                                                                                                                                                                                                                                                         |

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](https://docx-editor.portone.io/docs/styling.md#locked-content-and-content-controls) covers changing that.