Skip to content

Collaboration refinements: require HocuspocusProvider, context-aware error messages#22564

Merged
akabiru merged 3 commits intodevfrom
refinements/72665-collaboration-improvements
Apr 1, 2026
Merged

Collaboration refinements: require HocuspocusProvider, context-aware error messages#22564
akabiru merged 3 commits intodevfrom
refinements/72665-collaboration-improvements

Conversation

@akabiru
Copy link
Copy Markdown
Member

@akabiru akabiru commented Mar 28, 2026

Ticket

https://community.openproject.org/work_packages/72665

What are you trying to accomplish?

This extracts the non-IndexedDB refinements from #22125 so they can ship independently while we evaluate IndexedDB offline persistence (encryption at rest concern) separately.

The changes clean up the collaboration architecture by removing the test-mode fallback path, making HocuspocusProvider mandatory, and improving the offline/error UX with context-aware messages.

Key changes:

  • Collaboration is now gated on Setting.real_time_text_collaboration_enabled? instead of being hardcoded on
  • The test-mode fallback that created a standalone Y.Doc without a provider is removed — HocuspocusProvider is required
  • useCollaboration hooks are refactored with callback-based timeout, proactive cancel on sync, extracted useProviderAuthError hook, and JSDoc
  • Connection error messages are now context-aware: readonly users see "real-time updates will resume" vs writers see "changes will sync"
  • Blocked offline mode hides the editor when the server is unreachable (prevents empty Y.Doc from overwriting server content on reconnect)
  • Feature specs now use the real hocuspocus shared context instead of stubbing collaboration_enabled

What approach did you choose and why?

Rather than cherry-picking interleaved commits from #22125, each file was manually crafted to include only non-IndexedDB changes. The blockingOffline concept from the full PR collapses here — without IndexedDB there is no local cache, so all offline is blocking. The IndexedDB branch will later rebase on top of this one, re-introducing hasCachedDocument, soft offline mode, and the y-indexeddb dependency.

Merge checklist

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

@akabiru akabiru marked this pull request as draft March 28, 2026 07:43
@akabiru akabiru self-assigned this Mar 28, 2026
@github-actions
Copy link
Copy Markdown

github-actions Bot commented Mar 28, 2026

Deploying openproject with PullPreview

Field Value
Latest commit c76dea5
Job deploy
Status ✅ Deploy successful
Preview URL https://pr-22564-72665-collaborati-ip-168-119-98-63.my.opf.run:443

View logs

…are error messages

Extract non-IndexedDB refinements from PR #22125 so they can ship
independently while IndexedDB offline persistence is evaluated separately.

- Gate collaboration on Setting.real_time_text_collaboration_enabled?
  instead of hardcoding it to true
- Remove the test-mode fallback that created a standalone Y.Doc without
  a provider; HocuspocusProvider is now required for document editing
- Refactor useCollaboration hooks: callback-based timeout with proactive
  cancel on sync, extracted useProviderAuthError hook, JSDoc comments
- Add read/write context-aware connection error messages (readonly users
  see "real-time updates will resume" vs writers see "changes will sync")
- Add blocked offline mode: when the server is unreachable and there is
  no local cache, hide the editor entirely to prevent an empty Y.Doc
  from being synced as authoritative content on reconnect
- Update feature specs to use real hocuspocus shared context instead of
  stubbing collaboration_enabled, add offline blocking tests
@akabiru akabiru force-pushed the refinements/72665-collaboration-improvements branch from 85ade6d to 8272768 Compare March 30, 2026 13:44
@akabiru akabiru marked this pull request as ready for review March 30, 2026 13:50
@akabiru akabiru requested review from a team and ihordubas99 March 30, 2026 13:50
@akabiru akabiru merged commit 8c0d0c2 into dev Apr 1, 2026
20 of 23 checks passed
@akabiru akabiru deleted the refinements/72665-collaboration-improvements branch April 1, 2026 11:15
@github-actions github-actions Bot locked and limited conversation to collaborators Apr 1, 2026
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Development

Successfully merging this pull request may close these issues.

2 participants