[ihordubas99]

Ticket

https://community.openproject.org/wp/SE-641

Moved from opf/op-blocknote-extensions#274, where the earlier review discussion lives. The OpenProject side is a separate PR, #25917. The notification endpoint this calls comes from #26028.

What are you trying to accomplish?

Users can mention people in a document. Typing @ opens a menu with the members of the document's project who are not locked. Picking someone inserts an inline mention with their avatar and name, linking to their profile, and notifies that person.

The mention is stored in the document markdown in exactly the form CKEditor uses, so OpenProject renders it as a user link with a hover card without special cases.

Inside the editor a mention behaves like an inline work package. Clicking it selects it and opens a popover to open the profile or remove the mention. A selected mention can be removed with Backspace and moved with drag and drop.

Screenshots

What approach did you choose and why?

Stored format. BlockNote's markdown export keeps only the text of elements it does not know, so a real <mention> element would be saved as a plain "@name" and lose its id. Text nodes are copied verbatim, so the server-side spec writes the canonical tag as text. A markdown test pins the exact output in case BlockNote ever starts escaping text. In the browser the clipboard gets a real <mention> element, and a mention copied from a CKEditor field pastes as a mention.

Notifications. Hocuspocus saves the changes of everyone editing with the token of the first user who connected, so OpenProject can't tell from a save who added a mention. Instead, the editor calls POST /api/v3/notifications when a mention is inserted, and the author is the user whose session makes the request. initializeOpBlockNoteExtensions takes the documentId for this, and UserMentionNotificationExtension sends one request per mentioned user whenever mentions are picked, pasted or duplicated locally. Moving a mention or its block and changes arriving from collaborators through Yjs don't notify. Cut and paste counts as a new insert.

Search. The menu asks /api/v3/principals for users who are not locked and are members of the document's project, matching name, login or email. Like CKEditor, it only opens where a word starts, so typing an email address does not open it.

Shared building blocks. A mention needs what the inline work package already had, such as the options popover, node selection, closing on an outside press and a suggestion menu. Instead of copying these, they moved into lib/components/shared and a few generic hooks, and the work package code now uses them too. That is why the diff touches many work package files. The first three commits are this refactoring without behaviour changes and can be reviewed on their own.

Two small fixes come with the refactoring. Clicking an open inline work package again now closes its popover inside a shadow root instead of reopening it, and a blank # search cancels a pending search again.

Public API. Only additions. The client gets openProjectUserMentionSpec, OpenProjectMentionMenu, UserMentionNotificationExtension, the trigger constants and the optional documentId in initializeOpBlockNoteExtensions. The extension has to be passed in the editor's extensions, because BlockNote doesn't register extensions of inline content specs. The server entry gets openProjectUserMentionStaticSpec and the stored-format helpers for hocuspocus.

Merge checklist

• Added/updated tests
• Added/updated documentation in Lookbook (patterns, previews, etc)
• Tested major browsers (Chrome, Firefox, Edge, ...)

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[github-actions]

Warning

Flaky specs

• rspec ./modules/bim/spec/features/viewer/create_viewpoint_spec.rb[1:1:1:1]
• rspec ./spec/features/work_packages/cancel_editing_spec.rb[1:5]

🤖 Ask Copilot to investigate

Copy the prompt below into a new comment on this PR to delegate the investigation to GitHub Copilot. It will look into the flakiness and open a separate pull request with you as reviewer.

@copilot The following spec(s) are flaky in CI (first seen on PR #26018, linked for reference only):

- `rspec ./modules/bim/spec/features/viewer/create_viewpoint_spec.rb[1:1:1:1]`
- `rspec ./spec/features/work_packages/cancel_editing_spec.rb[1:5]`

Treat this as a standalone task, unrelated to PR #26018. Create a new branch from origin/dev and open a new pull request targeting dev — do not stack it on PR #26018 or reuse that branch.

Follow the playbook in docs/development/testing/handling-flaky-tests/README.md to find the root cause and fix the underlying race — do not skip, delete, or weaken the spec to make it pass; disabling is a last resort per the playbook, and only with a bug ticket. Verify the fix by running the spec(s) repeatedly (e.g. `script/bulk_run_rspec --run-count 10`).

If you cannot reproduce the flake or are not confident in a fix after reasonable investigation, do not fabricate a change or skip the spec to force CI green. Instead, leave the pull request in draft and document what you tried, the suspected cause, and any leads in its description, then assign @ihordubas99 to take over.

Once the fix is verified, title the PR after the spec(s) it fixes, and use the PR description to explain the root cause, how the change resolves it, and the before/after results. Label the PR `flaky-spec`, assign @ihordubas99, and request a review from @ihordubas99.
On every commit, set @ihordubas99 as the sole co-author with a `Co-authored-by:` trailer (use their GitHub no-reply email so it links to their account), so it is traceable who dispatched the fix.

[github-actions]

Warning

Flaky specs

• rspec ./spec/features/work_packages/table/delete_work_packages_with_descendants_spec.rb[1:2:1]

🤖 Ask Copilot to investigate

Copy the prompt below into a new comment on this PR to delegate the investigation to GitHub Copilot. It will look into the flakiness and open a separate pull request with you as reviewer.

@copilot The following spec(s) are flaky in CI (first seen on PR #26018, linked for reference only):

- `rspec ./spec/features/work_packages/table/delete_work_packages_with_descendants_spec.rb[1:2:1]`

Treat this as a standalone task, unrelated to PR #26018. Create a new branch from origin/dev and open a new pull request targeting dev — do not stack it on PR #26018 or reuse that branch.

Follow the playbook in docs/development/testing/handling-flaky-tests/README.md to find the root cause and fix the underlying race — do not skip, delete, or weaken the spec to make it pass; disabling is a last resort per the playbook, and only with a bug ticket. Verify the fix by running the spec(s) repeatedly (e.g. `script/bulk_run_rspec --run-count 10`).

If you cannot reproduce the flake or are not confident in a fix after reasonable investigation, do not fabricate a change or skip the spec to force CI green. Instead, leave the pull request in draft and document what you tried, the suspected cause, and any leads in its description, then assign @ihordubas99 to take over.

Once the fix is verified, title the PR after the spec(s) it fixes, and use the PR description to explain the root cause, how the change resolves it, and the before/after results. Label the PR `flaky-spec`, assign @ihordubas99, and request a review from @ihordubas99.
On every commit, set @ihordubas99 as the sole co-author with a `Co-authored-by:` trailer (use their GitHub no-reply email so it links to their account), so it is traceable who dispatched the fix.