docs: add a Collaboration Kit to Signals migration guide - #5888
Open
totally-not-ai[bot] wants to merge 4 commits into
Open
docs: add a Collaboration Kit to Signals migration guide#5888totally-not-ai[bot] wants to merge 4 commits into
totally-not-ai[bot] wants to merge 4 commits into
Conversation
Adds articles/tools/collaboration/migrating-to-signals.adoc, mapping each Collaboration Kit concept to its shared signals equivalent: topics to an application-scoped signal registry, UserInfo to an application record, PresenceManager and CollaborationAvatarGroup to a SharedListSignal bound with AvatarGroup.bindItems(), CollaborationBinder to a SharedValueSignal with map()/updater() alongside a regular Binder, field highlighting to CSS bindings, chat to a SharedListSignal with MessageList.bindItems(), and the low-level map and list APIs operation by operation. A 'Gaps and Cases That Can't Be Migrated' section covers what does not map. Blockers: clustering, and session serialization, since serializing a shared signal throws NotSerializableException and both view fields and the lambdas captured by bind*() keep the signal reachable from the session. Behavior that has to be rebuilt: connection-scoped cleanup and tab-close detection, topic expiration, user color allocation, the field highlighter overlay, and the message persister fetch protocol. API-level differences: no TypeReference overloads, no previous value in effects, no list emptiness conditions, and no cluster membership events. Also links the guide from the Collaboration Kit landing page.
Preview DeploymentThis PR has been deployed for preview. URL: https://docs-preview-pr-5888.fly.dev Changed pagesAdded content is highlighted in green; removed content is marked in red on each page.
Built from 07f9eca |
Reframes the gaps as work not yet done rather than permanent omissions, and links each one to where its status can be checked: - Serialization and clustering: flow#23413. The NotSerializableException is the outcome that issue asked for - fail with a clear message while sharing signals across a cluster is unimplemented - so the issue is closed without clustering having landed. Says so explicitly rather than implying it is open. - Field highlighting: flow#23868, which proposes a collaborative binder in Flow built on signals, and is the more productive thing to follow than rebuilding the highlight overlay. - Overall direction: collaboration-kit#138, which tracks moving the remaining features into Flow and deprecating Collaboration Kit. Also documents one further gap found while checking the trackers: a shared list rendered in a Grid or Combo Box still needs an effect calling setItems(), which refreshes the whole data set and rules out lazy loading, unlike bindChildren() in a layout. Tracked in flow#23659.
totally-not-ai Bot
added a commit
to vaadin/collaboration-kit
that referenced
this pull request
Aug 21, 2026
The guide now lives in vaadin/docs, where it belongs: vaadin/docs#5888 It was staged here only because this was the repository the change could be committed to at the time.
totally-not-ai Bot
added a commit
to vaadin/collaboration-kit
that referenced
this pull request
Aug 21, 2026
The GITHUB_TOKEN expired between committing and pushing the field-highlighting rewrite for vaadin/docs#5888. Parking the patch here so the work survives; it should be applied to that PR and this directory deleted.
The previous text claimed the field highlight overlay could not be reused because its Java side is not public API, and that a migration therefore could not match Collaboration Kit visually. That was wrong. The npm package @vaadin/field-highlighter has a documented static JavaScript API, and Collaboration Kit drives it purely through Element::executeJs - init(), setUsers(), and the vaadin-highlight-show / vaadin-highlight-hide events that carry a fieldIndex. Application code can do the same. Rewrites Step 5 around that: a SharedListSignal of editor entries keyed by property, user, and sub-field, so no user can clear another user's entry; adding and removing the local entry from the highlight events rather than from focus and blur, so composite fields work; and an effect that pushes the filtered editor list to the component. Keeps the CSS-only variant as the no-dependency alternative. Reframes the corresponding gap: what is missing is the wiring CollaborationBinder performs, not the component. Collaborative form editing is migratable today by writing more code, and flow#23868 would make it shorter rather than make it possible.
The guide claimed push was the same requirement for both products, so an application already using Collaboration Kit was already configured correctly. That is backwards. Collaboration Kit activates push itself: when a topic connection activates in a UI with neither push nor polling, ComponentConnection Context sets PushMode.AUTOMATIC and logs a warning. Signals never touch the push configuration. An application that relied on that default has no @Push anywhere, and the migration removes what was compensating for it. The failure is quiet - the user making a change still sees it, and everyone else sees it at their next interaction - so it is easy to miss in testing. Says to add @Push before migrating, while both behave the same, and adds a checklist row.
This was referenced Aug 21, 2026
Open
Open
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
articles/tools/collaboration/migrating-to-signals.adoc, a guide for moving an application from Collaboration Kit to Vaadin Flow's built-in shared signals, and links it from the Collaboration Kit landing page.What the guide covers
A concept mapping table, then a worked migration in eight steps:
setExpirationTimeout().UserInfo→ an application record, with color index allocation.PresenceManager/CollaborationAvatarGroup→ aSharedListSignalof collaborators bound withAvatarGroup.bindItems(), and attach/detach listeners in place ofEntryScope.CONNECTION.CollaborationBinder→ aSharedValueSignalof an immutable form record, usingmap()to read andupdater()to write, with a regularBinderkept for validation. Notes which Collaboration Kit restrictions disappear (readBean(),setBean(), getter/setter binding) and how entity-valued fields work without a custom serializer.SharedMapSignalof editors plus CSS bindings, since the@vaadin/field-highlighterJava API isn't public.SharedListSignalwithMessageList.bindItems(), which replacesCollaborationMessageList,CollaborationMessageInput, andMessageManagerat once, plus write-through persistence in place ofCollaborationMessagePersister.CollaborationMap/CollaborationList→SharedMapSignal/SharedListSignal, operation by operation, withListOperationconditions becoming transactions withverify*().SystemConnectionContext.Gaps
A dedicated section documents what can't be migrated, split into blockers, behavior that has to be rebuilt, and API-level differences:
NotSerializableException, and since both view fields and the lambdas captured bybind*()keep the signal reachable from the session, Kubernetes Kit session replication can't work.TypeReferenceoverloads, so parameterized value types need a record wrapper; effects see current state only, with no previous value asMapChangeEventandListChangeEventprovide; no list emptiness conditions; no cluster membership events.A "What Isn't a Gap" list covers the features that carry over unchanged, and a feature checklist summarizes everything as Direct / Build it / Missing.
Notes for review
src/, per the guidance for how-to guides that compare snippets side by side.com.vaadin.flow.signalsinvaadin/flowandMessageList.bindItems()/AvatarGroup.bindItems()invaadin/flow-components; the Collaboration Kit claims againstvaadin/collaboration-kit.vale --config=.vale-pr.inireports no errors, warnings, or suggestions on the new file. The one error it reports onindex.adoc("Collaboration Engine") is pre-existing onmainand untouched here.asciidoctorrenders both files without warnings; all internal anchors and cross-file xref targets resolve.