# Editor API

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

Commands, queries, presets, and plugins for controls of your own.

These pages cover what a mounted `DocxEditor` exposes to the application around it: the commands
and queries your own controls call, and the plugins and presets it takes.
[Core API](https://docx-editor.portone.io/docs/core.md) covers import and export without an editor.

## Hide the built-in controls [#hide-the-built-in-controls]

`mode.toolbar` turns the toolbar off, and `contextMenus` leaves the right button to the browser:

```tsx
<DocxEditor
  document={file}
  mode={{
    kind: "edit",
    author: { id: user.id, name: user.name },
    toolbar: false,
  }}
  contextMenus={false}
/>
```

A `comment` editor has no toolbar, and its right-click menu offers Copy and Add comment only.

## Commands and queries [#commands-and-queries]

Commands follow the ProseMirror command contract: called with an `EditorState` alone, a command
reports whether it applies; called with a dispatch function, it performs the edit.

```tsx
import type {
  Command,
  EditorState,
  EditorView,
} from "@portone/docx-editor";
import { isBoldActive, toggleBold, undo } from "@portone/docx-editor/commands";

function Toolbar({ view, state }: { view: EditorView; state: EditorState }) {
  const run = (command: Command) => {
    command(state, (transaction) => view.dispatch(transaction), view);
    view.focus();
  };

  return (
    <div>
      <button
        type="button"
        aria-pressed={isBoldActive(state)}
        onClick={() => run(toggleBold)}
      >
        Bold
      </button>
      <button type="button" disabled={!undo(state)} onClick={() => run(undo)}>
        Undo
      </button>
    </div>
  );
}
```

`onReady` hands over the editor view, and `onChange` fires on every state change, selection moves
included.

| Import                          | What it holds                                                                                                                                |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `@portone/docx-editor/commands` | Text, paragraph, list, break, tab, history, image, link, comment, note and lock commands and queries, the export queries, and `insertTable`. |
| `@portone/docx-editor/table`    | Everything acting on a table already in the document: rows, columns, merging, and cell formatting.                                           |
| `@portone/docx-editor`          | The component, the `DEFAULT_*` preset lists, `docxSchema`, and the shared types.                                                             |

Name prefixes say what a function returns: `is*Active` a boolean toggle, `active*` the current
value or `"mixed"`, `can*` whether the action applies, `isIn*` containment, `selection*` and
`document*` a reading of the selection or the whole document, `editing*` the protection level,
and `DEFAULT_X` the built-in default of the prop or field `x`.

Every command already accounts for locked content, the editor's mode, and preserved markers, so
it reports that it does not apply wherever the edit would be refused.
Wrap a command from elsewhere in `canRunCommand(command, state)` to hold it to the same rules.

## Export controls [#export-controls]

`canExport` reports whether the document can be written back.
`documentExportProblems` lists every reason it could not, each with the `DocxExportError` code, a
`reason` naming the content it is about, and the `pos` a panel can select.
[Checking before export](https://docx-editor.portone.io/docs/core/errors.md#checking-before-export) lists the reasons and the codes.

`documentFidelity` lists what the main body holds that the editor cannot model: markup kept
but invisible, and the placeholders standing in for content it could not open for editing.
Each note carries a `pos` a panel can select.
[Core API](https://docx-editor.portone.io/docs/core.md#what-a-document-loses) describes the fields and coverage.

## Guides [#guides]

- [Text and paragraphs](https://docx-editor.portone.io/docs/editor-api/text-and-paragraphs.md): Character formatting, fonts, paragraph styles, lists, breaks, tabs, and history.
- [Tables](https://docx-editor.portone.io/docs/editor-api/tables.md): Insert a table, edit its rows and columns, and format its cells.
- [Images and links](https://docx-editor.portone.io/docs/editor-api/images-and-links.md): Take an image file into the document, and create or change a hyperlink.
- [Comments and notes](https://docx-editor.portone.io/docs/editor-api/comments-and-notes.md): Write, edit, resolve and read comment threads, and insert, edit and read footnotes and endnotes.
- [Zoom](https://docx-editor.portone.io/docs/editor-api/zoom.md): Let the editor own the zoom level, or own it from the host application.
- [Modes and locks](https://docx-editor.portone.io/docs/editor-api/modes-and-locks.md): What each mode lets through, and the locks the document itself carries.
- [Plugins and presets](https://docx-editor.portone.io/docs/editor-api/plugins-and-presets.md): Replace the picker values, add ProseMirror plugins, and what a plugin may rely on.