Documentation by gohabereg · Pull Request #131 · editor-js/document-model

gohabereg · 2026-04-29T23:22:56Z

All generated, then fact-check by another model. I skimmed, looks legit.

Leave your suggestions, I'll feed it back to AI!

…nputs-registration

github-actions · 2026-04-29T23:23:59Z

⏭️ No files to mutate for ./packages/model

github-actions · 2026-04-29T23:23:59Z

⏭️ No files to mutate for ./packages/core

github-actions · 2026-04-29T23:24:33Z

Coverage report for `./packages/model`

St.^❔	Category	Percentage	Covered / Total
🟢	Statements	99.71%	1044/1047
🟢	Branches	98.44%	315/320
🟢	Functions	98.39%	244/248
🟢	Lines	99.7%	1002/1005

Test suite run success

563 tests passing in 26 suites.

Report generated by 🧪jest coverage report action from 25b5d3c

github-actions · 2026-04-29T23:24:33Z

Coverage report for `./packages/core`

St.^❔	Category	Percentage	Covered / Total
🟢	Statements	94.24%	278/295
🟢	Branches	91.3%	105/115
🟡	Functions	75.41%	46/61
🟢	Lines	93.91%	262/279

Test suite run success

143 tests passing in 8 suites.

Report generated by 🧪jest coverage report action from 25b5d3c

github-actions · 2026-04-29T23:24:55Z

⏭️ No files to mutate for ./packages/dom-adapters

github-actions · 2026-04-29T23:25:00Z

Coverage report for `./packages/collaboration-manager`

St.^❔	Category	Percentage	Covered / Total
🟢	Statements	91.88%	396/431
🟢	Branches	85.82%	121/141
🟢	Functions	88.16%	67/76
🟢	Lines	91.71%	387/422

Test suite run success

130 tests passing in 7 suites.

Report generated by 🧪jest coverage report action from 25b5d3c

github-actions · 2026-04-29T23:25:03Z

Coverage report for `./packages/ot-server`

St.^❔	Category	Percentage	Covered / Total
🟡	Statements	70.97%	22/31
🔴	Branches	20%	1/5
🔴	Functions	50%	6/12
🟡	Lines	68.97%	20/29

Test suite run success

4 tests passing in 1 suite.

Report generated by 🧪jest coverage report action from 25b5d3c

github-actions · 2026-04-29T23:25:10Z

Coverage report for `./packages/dom-adapters`

St.^❔	Category	Percentage	Covered / Total
🟢	Statements	96.43%	27/28
🟢	Branches	86.96%	20/23
🟢	Functions	100%	5/5
🟢	Lines	96.43%	27/28

Test suite run success

11 tests passing in 2 suites.

Report generated by 🧪jest coverage report action from 25b5d3c

Copilot

Pull request overview

Adds a new documentation set for the @editorjs/document-model monorepo, describing architecture boundaries, the data model, event system, plugin/tool lifecycle, input handling flows, and collaboration/OT mechanics, with supporting Mermaid diagrams and updated entry-point READMEs.

Changes:

Introduces new docs pages under docs/ covering architecture, model, events, plugins/tools, input handling, and collaboration.
Adds Mermaid diagrams under docs/diagrams/ to visualize key flows (lifecycle, events catalog, OT, undo/redo, selection, formatting, etc.).
Updates root README.md and adds a docs maintenance agent instruction file at .github/agents/docs-updater.md.

Reviewed changes

Copilot reviewed 18 out of 18 changed files in this pull request and generated 13 comments.

Show a summary per file

File	Description
`docs/plugins.md`	Documents plugin/tool registration, initialization sequence, and `EditorAPI` surface.
`docs/model.md`	Documents the model tree, mutation/event invariants, caret/selection concepts, and `Index`.
`docs/input-handling.md`	Documents the typing/selection pipeline and adapter interactions.
`docs/events.md`	Documents model vs core/UI event transports and event reference tables.
`docs/collaboration.md`	Documents OT flow, wire protocol, batching, and undo/redo behavior.
`docs/architecture.md`	Documents package layering and dependency rules with a high-level overview diagram link.
`docs/README.md`	Provides a guided reading order, lifecycle summary, and canonical terminology glossary.
`docs/diagrams/architecture-overview.mmd`	High-level package/class relationship diagram.
`docs/diagrams/plugin-lifecycle-flow.mmd`	Sequence diagram for `Core`/plugins/tools initialization lifecycle.
`docs/diagrams/model-tree-structure.mmd`	Class diagram for model/document/caret structures.
`docs/diagrams/events-catalog.mmd`	Class diagram cataloging event classes by transport/package.
`docs/diagrams/block-adapter-input-flow.mmd`	Sequence diagram for block insertion + adapter/input registration + typing flow.
`docs/diagrams/caret-selection-flow.mmd`	Sequence diagram for selection tracking and selection-changed signaling.
`docs/diagrams/inline-formatting-flow.mmd`	Sequence diagram for inline tool application and targeted DOM rerendering.
`docs/diagrams/collaboration-ot-flow.mmd`	Sequence diagram for handshake, local/remote ops, and OT transformation.
`docs/diagrams/undo-redo-flow.mmd`	Sequence diagram for batching and undo/redo inversion/apply.
`README.md`	Expands repo overview with package list, docs links, and dev commands.
`.github/agents/docs-updater.md`	Adds a process/style guide for keeping docs/diagrams synced with code changes.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+
+| Method | Description |
+|---|---|
+| `insert(type?, data?, index?, focus?, replace?)` | Insert a block of the given tool type |


+- `core` wires runtime dependencies; it should be the only orchestrator.
+- `model` does not depend on DOM concerns.
+- `dom-adapters` and `collaboration-manager` observe/apply model changes through public APIs and events.
+- `ui` depends on `sdk` only; it is registered as an `EditorjsPlugin` via `core.use()`.


+- `EditorjsPlugin`: general UI/behavior plugin registered via `core.use()` with `PluginType.Plugin`.
+- `UiComponentType`: reserved string keys for UI component slots (`shell`, `blocks`, `inline-toolbar`, `toolbox`, `toolbar`). These name components in the UI layer but are **not** used as arguments to `core.use()` — plugins are registered by `PluginType` or `ToolType` values.


+  Plugins-->>Core: [[SomeTool, settings], ...]
+  Core->>ToolsManager: prepareTools(blockTools, inlineTools, blockTunes)
+  loop for each tool
+    ToolsManager->>Tool: Tool.prepare(toolName, config)


+      detail.index: SerializedIndex or null
+      detail.userId: string or number
+    }
+    class CaretManagerCaretAddedEvent {
+      <<CustomEvent~CaretSerialized~>>
+      detail.index: SerializedIndex
+      detail.userId: string or number
+    }
+    class CaretManagerCaretRemovedEvent {
+      <<CustomEvent~CaretSerialized~>>


+| `BlockAddedCoreEvent` | `core:block-added` | `{ tool, data, index, ui: HTMLElement }` | `BlockRenderer` |
+| `BlockRemovedCoreEvent` | `core:block-removed` | `{ tool, index }` | `BlockRenderer` |
+| `ToolLoadedCoreEvent` | `core:tool-loaded` | `{ tool: ToolFacadeClass }` | `ToolsManager` |
+| `SelectionChangedCoreEvent` | `core:selection-changed` | `{ index, availableInlineTools, fragments }` | `SelectionManager` |


+| `SelectionChangedCoreEvent` | `core:selection-changed` | `{ index, availableInlineTools, fragments }` | `SelectionManager` |
+| `UndoCoreEvent` | `core:undo` | — | `BlocksUI` (Cmd/Ctrl+Z) |
+| `RedoCoreEvent` | `core:redo` | — | `BlocksUI` (Cmd/Ctrl+Shift+Z) |
+| `BeforeInputUIEvent` | `ui:before-input` | `{ data, inputType, targetRanges, isCrossInputSelection }` | `BlocksUI` |


+  %% ── Constructor ──────────────────────────────────
+  Dev->>Core: new Core(config)
+  Core->>IoC: bind EditorConfig, EventBus, EditorJSModel, ToolsManager
+  Core->>Plugins: bind DOMAdapters, Paragraph, Bold, Italic, Link, ShortcutsPlugin


+  %% ── await initialize() ───────────────────────────
+  Dev->>Core: await initialize()
+
+  Core->>IoC: bind TOKENS.Adapter as toDynamicValue(ctx => new Adapter(model, config, api, eventBus))


+
+  Core->>IoC: get SelectionManager, BlocksManager, BlockRenderer
+
+  Core->>EditorJSModel: initializeDocument(blocks)


…/docs

gohabereg added 15 commits April 17, 2026 20:55

Fix inputs and values attachments to be data-first

0d5817e

Merge branch 'main' of github.com:editor-js/document-model into fix/i…

c5ff274

…nputs-registration

Load adapters as plugin

e4c246d

Merge branch 'main' of github.com:editor-js/document-model into fix/i…

40a6409

…nputs-registration

Fix tests

abe46db

Review comments

40c4284

(try to) fix test run for core package

ba5077d

Run base branch coverage manually

e424775

Fix unit-tests action: use ArtiomTr with pre-generated coverage files

5990de3

Try just PR branch tests

208c95d

Try clear before build

0996eac

Try no cache

8958a51

Use latest node

0ea33bc

Review comments resolved

d265bd3

Docs

5c5e5be

gohabereg requested a review from Copilot April 29, 2026 23:23

Copilot started reviewing on behalf of gohabereg April 29, 2026 23:24 View session

Copilot AI reviewed Apr 29, 2026

View reviewed changes

Base automatically changed from fix/inputs-registration to main May 5, 2026 00:21

gohabereg added 3 commits May 7, 2026 21:22

Merge branch 'main' of github.com:editor-js/document-model into chore…

a70b2fc

…/docs

Remove conflicts

8257fba

Merge branch 'main' of github.com:editor-js/document-model into chore…

d4cf6f2

…/docs

gohabereg added 3 commits June 1, 2026 21:01

Updates

2ded725

Reflect collaboration manager is a plugin

f12fda5

Update readme

25b5d3c

neSpecc approved these changes Jun 1, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Documentation#131

Documentation#131
gohabereg wants to merge 21 commits into
mainfrom
chore/docs

gohabereg commented Apr 29, 2026

Uh oh!

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

		- `EditorjsPlugin`: general UI/behavior plugin registered via `core.use()` with `PluginType.Plugin`.
		- `UiComponentType`: reserved string keys for UI component slots (`shell`, `blocks`, `inline-toolbar`, `toolbox`, `toolbar`). These name components in the UI layer but are not used as arguments to `core.use()` — plugins are registered by `PluginType` or `ToolType` values.


		Core->>IoC: get SelectionManager, BlocksManager, BlockRenderer

		Core->>EditorJSModel: initializeDocument(blocks)

Conversation

gohabereg commented Apr 29, 2026

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report for ./packages/model

Test suite run success

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report for ./packages/core

Test suite run success

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report for ./packages/collaboration-manager

Test suite run success

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report for ./packages/ot-server

Test suite run success

Uh oh!

github-actions Bot commented Apr 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Coverage report for ./packages/dom-adapters

Test suite run success

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot commented Apr 29, 2026 •

edited

Loading

github-actions Bot commented Apr 29, 2026 •

edited

Loading

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Coverage report for `./packages/model`

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Coverage report for `./packages/core`

github-actions Bot commented Apr 29, 2026 •

edited

Loading

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Coverage report for `./packages/collaboration-manager`

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Coverage report for `./packages/ot-server`

github-actions Bot commented Apr 29, 2026 •

edited

Loading

Coverage report for `./packages/dom-adapters`