Move the Collaboration Kit to Signals migration guide to vaadin/docs (no net change here)

[totally-not-ai]

Summary

This branch is a no-op against origin/main — git diff origin/main...HEAD is empty. It exists only as the commit history of a documentation effort that was drafted here and then delivered to its real home in vaadin/docs#5888.

The guide itself, Migrating from Collaboration Kit to Signals, lives entirely in vaadin/docs at articles/tools/collaboration/migrating-to-signals.adoc. Nothing in this repository is added, changed, or removed.

Why the round trip

At the time the writing started, this repository was the only one the change could be committed to, so the article was staged under docs/vaadin-docs/ with a README describing how to copy it across. Later, a GITHUB_TOKEN expired between committing and pushing a follow-up rewrite, so that patch was parked under pending-vaadin-docs/ to keep the work from being lost. Both holding directories have now served their purpose and were deleted once the content landed in vaadin/docs.

What the delivered guide covers

For reviewers who want the substance rather than the file moves, the article that landed in vaadin/docs maps every Collaboration Kit concept onto its shared signals equivalent:

• Concept mapping and migration steps — topics to an application-scoped signal registry, UserInfo to an application record, PresenceManager/CollaborationAvatarGroup to a SharedListSignal bound with AvatarGroup.bindItems(), collaborative forms, field highlighting, chat and messages, the low-level map/list topic API, and background threads.
• Gaps and cases that can't be migrated, split into three groups:
  • Blockers: clustering, and session serialization — serializing a shared signal throws NotSerializableException because every public constructor creates the asynchronous tree that refuses serialization, and both view fields and the lambdas captured by bind*() keep the signal reachable from the session, so Kubernetes Kit session replication cannot work.
  • Behavior that has to be rebuilt: connection-scoped cleanup and the tab-close beacon, topic and entry expiration, automatic user color assignment, the field highlighter overlay with multiple editors and sub-field indexes, and the message persister fetch protocol.
  • API-level differences: no TypeReference overloads, no previous value in effects, no list emptiness conditions, no cluster membership events.
• What isn't a gap — the features that carry over unchanged — plus a feature checklist table.

Corrections made along the way

Several claims and examples were tightened before the content was handed over:

• Paired retain/release across attach and detach in the topic registry example; registering only a detach listener releases more times than it retains when a view is reattached.
• Stopped presenting SharedMapSignal.verifyKey() as the counterpart of CollaborationMap.replace() — it verifies that a key maps to a given child signal, not that an entry holds an expected value.
• Removed the field highlight entry on blur only while it still belongs to the local user, inside a transaction with verifyValue().
• Guarded the nullable supervisor identifier in the entity-valued field example and cached it so the backend lookup does not run on every unrelated form change.
• Narrowed the automatic color allocation claim (sequential allocation is local-backend only; the registry never shrinks, so the eighth distinct user since startup collides with the first).
• Dropped the ListChangeEvent change-type claim: the accessor and enum are package-private, so subscribers cannot read it. What signals actually lack is the previous value and the surrounding keys.
• Field highlighting now extends FieldHighlighterInitializer rather than issuing a bare executeJs call — the @NpmPackage/@JsModule annotations sit on that class, so without it Flow's production scan drops the module and the custom element is undefined in production. It also fixes re-initialization on reattach, and vaadin-highlight-hide now matches on property and user so two show events without an intervening hide cannot orphan an entry.

Verification

The regenerated patch was applied to a fresh checkout of the vaadin/docs PR branch: vale --config=.vale-pr.ini reports 0 errors, 0 warnings, and 0 suggestions, and asciidoctor -a skip-front-matter renders the file cleanly. Cross-file xref targets were checked by hand, since Asciidoctor on a single file resolves neither {articles} nor inter-document xrefs.

Review notes

There is nothing to review in this repository's tree. Review the documentation in vaadin/docs#5888. This PR can be closed without merging, or merged as an empty history record — whichever the team prefers.

[totally-not-ai]

Closing this. The migration guide belongs in vaadin/docs, and that's where it now lives: vaadin/docs#5888.

This PR only ever existed as a holding place — first for the guide itself, then for a patch that couldn't be pushed while a token was expired. That patch has been applied to vaadin/docs#5888, so this branch no longer changes anything in this repository.

Context for anyone following the migration work: vaadin/collaboration-kit#138 and vaadin/flow#23868.