Park an unpushed vaadin/docs patch for the Collaboration Kit to Signals migration guide - #142
Closed
totally-not-ai[bot] wants to merge 7 commits into
Closed
Conversation
Adds an AsciiDoc article that maps every 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. It also states what shared signals do not yet cover: clustering, connection-scoped cleanup, and topic expiration. The article targets the vaadin/docs repository, which cannot be pushed to from here, so it is staged under docs/vaadin-docs/ mirroring its target path, with a README describing how to copy it over.
…tion guide - Pair 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, dropping shared state that is still in use. Adds a note about the grace period a re-attaching view needs. - Stop presenting SharedMapSignal.verifyKey() as the counterpart of CollaborationMap.replace(). It verifies that a key maps to a given child signal, not that the entry holds an expected value; replace() or verifyValue() on the entry signal are the value-based equivalents. - Remove the field highlight entry on blur only while it still belongs to the local user, in a transaction with verifyValue(), so that blurring does not clear an entry a second user has since written. - Guard the nullable supervisor identifier in the entity-valued field example, and cache the identifier so the backend lookup does not run on every change to an unrelated form property.
…Kit migration Adds a 'Gaps and Cases That Can't Be Migrated' section, split into three groups, and retargets the early triage list at it. Blockers: clustering, and session serialization. Serializing a shared signal throws NotSerializableException, since every public constructor creates the asynchronous tree that refuses serialization; 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 beacon that makes tab-close detection prompt, 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, so parameterized value types have to be wrapped in a record; no previous value or change type in effects, unlike MapChangeEvent and ListChangeEvent; no list emptiness conditions; no cluster membership events. Also adds a 'What Isn't a Gap' list for the features that carry over unchanged, and extends the feature checklist with the new rows.
- ListChangeEvent tracks a change type, but the accessor and the enum are
package-private, so subscribers cannot read it. Drop it from the gap and the
checklist row: what signals actually lack is the previous value and the
surrounding keys, both of which are public in Collaboration Kit.
- Narrow the automatic color allocation claim. Sequential allocation applies
only to the local backend, the registry never shrinks so the eighth distinct
user since startup collides with the first, and a non-local backend falls
back to hashing the user id - the same approach the guide suggests.
- CollaborationBinder::forField takes the collection and element types as two
Class arguments; TypeReference belongs to the topic API. Separate the two.
- Say in the README exactly how the cross-file xref targets were checked, since
Asciidoctor on a single file resolves neither {articles} nor inter-document
xrefs.
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.
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.
Four problems in the recipe, all found by checking it against Collaboration Kit's own implementation: - The @NpmPackage and @jsmodule annotations for @vaadin/field-highlighter sit on FieldHighlighterInitializer. A bare executeJs call never references that class, so Flow's production scan drops the module and the custom element is undefined in production while development mode works. Removing Collaboration Kit removes the only thing that referenced it. The recipe now extends FieldHighlighterInitializer, as Collaboration Kit does. - That also fixes initialization: FieldHighlighterInitializer.init() re-runs on every attach, whereas the one-shot executeJs left a re-attached field without the focus observer, silently unreported from then on. - vaadin-highlight-hide removed only the last inserted entry. Two show events can arrive without a hide between them - moving between the parts of a DateTimePicker - orphaning the earlier entry and leaving a highlight nobody can clear. Removal now matches property and user, as FormManager does. - Collaboration Kit declares vaadin-field-highlighter-flow as provided, so it is vaadin-core, not Collaboration Kit, that puts it on the classpath. Also aligns DocumentState with the list-based editor model, moves the FormManager tip back to the section level, and restores the heading spacing. Verified by applying the regenerated patch to a fresh checkout of the PR branch: Vale reports no errors, warnings, or suggestions, and Asciidoctor renders the file cleanly.
totally-not-ai
Bot
changed the title
Author
|
Closing this. The migration guide belongs in 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: |
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.
What this changes
This branch adds a single temporary directory,
pending-vaadin-docs/, containing one commit that could not be pushed to its real home:0001-docs-give-collaborative-binder-users-a-real-migratio.patch— a rewrite of the field-highlighting section of the Collaboration Kit → Signals migration guide, formatted forgit am.README.md— where the patch belongs, how to apply it, and what has already been verified.Nothing else in this repository is touched. The migration guide itself was staged here earlier in the branch and has since been removed: it now lives in vaadin/docs#5888, which is where documentation for this feature belongs. Only the follow-up patch remains, and only because it has nowhere else to sit yet.
Why
The guide was originally committed here because this was the repository the change could be committed to at the time. Once the vaadin/docs PR existed, the guide moved there. The
GITHUB_TOKENthen expired between committing the field-highlighting rewrite and pushing it, so that last commit never reached the PR. Parking it as a patch file keeps the work from being lost.What the parked patch says
The earlier text in the guide claimed the
@vaadin/field-highlighteroverlay couldn't be reused, because its Java wrapper isn't public API, and that a migration therefore couldn't match Collaboration Kit visually. That's wrong: the npm package has a documented static JavaScript API, and Collaboration Kit drives it purely throughElement::executeJs, so application code can do the same and get an identical result.The recipe in the patch follows Collaboration Kit's own implementation rather than reinventing it:
FieldHighlighterInitializerinstead of making a bareexecuteJscall. The@NpmPackageand@JsModuleannotations for@vaadin/field-highlightersit on that class, so a bare call leaves nothing referencing it — Flow's production scan drops the module and the custom element is undefined in production, while development mode works. Subclassing also re-runsinit()on every attach; the one-shot call left a re-attached field without its focus observer, silently unreported from then on.vaadin-highlight-show/vaadin-highlight-hideso composite fields report the right sub-field.FormManagerdoes. Removing only the last inserted entry orphans the earlier one when two show events arrive without a hide between them — for example, moving between the parts of aDateTimePicker— leaving a highlight nobody can clear.vaadin-field-highlighter-flowis declaredprovidedby Collaboration Kit, so it's vaadin-core, not Collaboration Kit, that puts it on the classpath.The patch also aligns
DocumentStatewith the list-based editor model, moves theFormManagertip back to section level, and restores heading spacing. The CSS-only variant is kept as the no-dependency alternative.Verification
Done against a fresh
vaadin/docscheckout of the PR branch with the patch applied:vale --config=.vale-pr.ini articles/tools/collaboration/migrating-to-signals.adoc— 0 errors, 0 warnings, 0 suggestions.asciidoctor -a skip-front-matterrenders the file with no warnings; every internal anchor resolves. Cross-file xref targets were checked by hand, since Asciidoctor on a single file resolves neither{articles}nor inter-document xrefs.Follow-up
Once the patch is applied to vaadin/docs#5888, delete
pending-vaadin-docs/. It is a holding place, not repository content.