@smartbit4all/ng-client 7.0.10 → 7.1.0

package/MIGRATION-7.0.md

@@ -1252,7 +1252,7 @@ shorts link produced no player. It plays now.
 
 | Removed | Replacement |
 |---|---|
-| `SmartformwidgetComponent` | nothing — no host imported the class; `<smartform>` still renders it. 7.1 splits it into per-type components |
+| `SmartformwidgetComponent` | nothing — no host imported the class; `<smartform>` still renders it. 7.2 splits it into per-type components |
 | `SmartWidgetSettings` (its only member was `static useUtc`) | nothing — **delete the assignment** |
 
 3.6 moved the `useUtc` static into `SmartNgClientConfig.useUtcDates`; **3.8 then removed the
@@ -1717,6 +1717,133 @@ keep its own default when the library passed `false` or `''` — it now receives
 This is the only part of 7.0 where a bugfix can change what you see on screen without any
 code of yours changing.
 
+### Model sync: the client's models travel with every call (7.1.0)
+
+Whether an action carried the page model used to be a per-action decision of the backend
+(`UiAction.submit` / `model` / `composite`) plus one hidden rule (an action with no params sent
+it anyway), and the model travelled under three ad-hoc `params` keys (`model`, `clientPageModel`,
+`compositeModel`) that only one endpoint wrote into the backend view automatically. The bug that
+forced the change: an action on an embedded view sent only its own model, the handler changed the
+container's model, the container's whole component model came back, and whatever the user had
+typed into the container since the last round-trip was gone.
+
+From 7.1.0 the client sends, with **every** action, widget action, upload and grid selection
+call, the data of **every open view that changed since it was last synced** — slot-hosted and
+dialog views alike — in a new `UiActionRequest.modelSync.models` map keyed by view uuid. The
+backend writes each one into the matching view **before the handler runs and before it takes the
+base of its change push**, so a handler always sees what is on screen and the client's own values
+are never echoed back. A view equal to its last synced copy is left out; a view without a copy is
+always sent.
+
+**Backend minimum, and the server switch.** The platform build that ships
+`UiActionRequest.modelSync` (platform ADR-0011 on the server side), **with model sync switched
+on**: `view.model-sync.enabled=true` in the host's `application.properties`. The switch defaults
+to `false`, and in that mode the server behaves exactly as before model sync existed: nothing is
+written into the views before the handler, and a request that carries `modelSync` is **rejected**
+with an error naming the property, not ignored. A 7.1.0 client sends the envelope with every
+call, so against a server with the switch off every call fails loudly; against an older platform
+the field is silently ignored and every handler that read `params.model` sees nothing. **Order:
+upgrade the backend, set the flag, then upgrade the client.** Server code can read the mode as
+`viewApi.isModelSyncEnabled()`.
+
+**A 6.x client against a backend with the switch on** is rejected too: with
+`view.model-sync.enabled=true` every request that can carry `modelSync` — an action, a widget or
+upload action, a tree action, a grid selection change — must carry it, and one without it (an
+old client, or host code that builds a `UiActionRequest` by hand and calls the view context
+service directly) gets an error saying so. A call that cannot carry it (loading a view, a
+message result, expanding a tree node, a map interaction) is neither synced nor refused. The old `params.model` / `clientPageModel` / `compositeModel`
+keys are never read as a sync source; they are only *filled* by the backend, see below. So the
+switch and the client upgrade go together per host: flip the flag in the same deploy that ships
+the 7.1.0 client. Internal Java callers with nothing to sync send an empty `new ModelSync()`.
+
+#### What changed on the client
+
+- `UiAction.model` and `UiAction.composite` are **deprecated no-ops** for a view's own actions.
+  `submit` keeps one meaning: validate before sending, the embedded views' forms included. For an
+  executor that is not a view (a tree, the filter editor) `model` still flushes its form and its
+  model still rides on `params.model` as before, because it has no view to sync.
+- Forms are flushed into their data (`submitForm(false)`) on every open view before a call, so an
+  unsaved field value is part of what is compared and sent. **Only the user's edits are
+  flushed**: the form remembers, per control, the value it last exchanged with the data (built
+  or refreshed from it, or written into it), and a control still equal to that writes nothing.
+  This is what keeps an untouched `false` or `0` from turning into `''` on a round trip (the
+  control is now built with `value ?? ''`, and a value written back takes the type the field has
+  in the data: `'true'` → `true`, `'12'` → `12`, `''` → `null`), and a backend push from
+  reaching the data only to be overwritten by the control's stale value on the next call. The
+  same rule the other way: a data field the backend changed reaches its control even when the
+  user edited it (the backend wins on a field it changed), a field it did not change keeps what
+  the user typed. `SmartFormService.resetExchangedValues()` starts over when a form is rebuilt.
+  The form's own dirty flag is not involved: it lives until the form is rebuilt and says nothing
+  about what the data holds.
+- A push of some `data.*` paths marks only those paths as synced; whatever else the view holds
+  keeps its standing, so a value written into the data outside a form while a call was in flight
+  is still sent by the next one. A whole-model push and the initial load mark all of it.
+- Calls run concurrently, and an envelope built earlier may complete later: its copies are never
+  written over the copies a later envelope or push already settled. The server-side ordering of
+  rapid per-field actions stays out of scope (ADR-0010).
+- A dialog the backend closed (`ViewState.TO_CLOSE`) no longer fires a `DEFAULT_CLOSE` action of
+  its own on top of the response that closed it; only the user's own close does.
+- The per-field actions a widget's `valueChangeMode` fires are ordinary actions and inherit the
+  sync; they no longer set `model: true`, and still carry `params.item`.
+
+#### Removed from the public API
+
+| Gone | What to do |
+|---|---|
+| `SmartComponentApiClient.sendModelOnWidgetAction` | Delete the assignment. Every widget action carries the changed models now. Loud: `this.sendModelOnWidgetAction = true` no longer compiles. |
+| `SmartComponentApiClient.addModelToWidgetParams()` / `addModelToWidgetAction()` | Delete. The grid service builds its own envelope. |
+| `SmartViewContextService.getCompositeModel()` | Delete. The backend gets every changed view. |
+| `SmartViewContextService.submitEmbeddedForms()` | `validateEmbeddedForms(containerUuid)` — validation only; the flush is part of every call. |
+| `SmartViewContextService.dataChanged()` | Delete. It was never wired on the client (`handleValueChanges` had no caller); a field change is a uiAction. |
+
+New on `SmartViewContextService`: `joinModelSync(uuid, participant)` / `leaveModelSync(uuid,
+participant)` (the client does this on its own uuid; leaving only takes effect for the participant
+that is registered, so a component destroyed after its successor joined under the same uuid does
+not take the successor with it), `markModelSynced(uuid, keys?)` (the client calls it whenever the
+backend's model reached it: without keys the whole data, with keys the pushed `data` paths), and `withModelSync(carrier, call)` for a host that issues its own backend call on a request
+that can carry the envelope (a `UiActionRequest`, a `GridSelectionChange`): it puts the envelope
+on the carrier, runs the call with it and settles the copies on success, and hands back the raw
+`ViewContextChange` — what to do with the response stays with the caller. The grid and tree
+services are the in-tree examples; `beginModelSync()` / `completeModelSync()` underneath are
+public too.
+
+#### The Java side of the host: three kinds of handler
+
+The backend **backfills** the old `params` keys from the synced model on every request (with the
+switch on, every request carries `modelSync`), so no handler has to change on the day the client
+is upgraded. Two kinds must be
+looked at anyway, and one of them breaks without a compiler error. Run
+`node tools/model-sync-audit/cli.mjs ../<host>` — it lists every read of the request model with
+one of these categories and a reason ([its README](../../tools/model-sync-audit/README.md)):
+
+| | The handler | What to do |
+|---|---|---|
+| **A** | reads `params.model` (`extractClientModel(request)`, `actionRequestHelper(request).get(UiActions.MODEL, …)`) and only passes it to `setModel(viewUuid, …)` | Delete both statements. The sync already wrote the client's model into the view. |
+| **B** | reads it for something else: saves it, validates it, forwards it, mutates it before setting it back | Nothing required. `getModel(viewUuid)` is the honest read now; `extractClientModel` is `@Deprecated`. A grid row action's `params.model` is still the clicked row and is never synced. |
+| **C** | reads the view's model too (`getModel(viewUuid)`, `view.getModel()`) and uses the two together — a diff, a merge, "what changed" | **Breaks silently.** After the sync `getModel` *is* the client's model, so the comparison compares a thing with itself. The server-side read must become `viewApi.isModelSyncEnabled() ? getPreviousModel(viewUuid) : getModel(viewUuid)`: the model as the server knew it before this call, request-scoped (`viewApi.getPreviousModel(uuid, Class)` outside a `PageApiImpl`). The off branch is the old code. |
+
+A handler that must work in both server modes — a shared module deployed to hosts with the
+switch off as well as on — branches inline on `viewApi.isModelSyncEnabled()` and keeps its old
+code verbatim in the off branch: an A site becomes
+`if (!viewApi.isModelSyncEnabled()) { setModel(viewUuid, extractClientModel(request)); }`, a
+client read `viewApi.isModelSyncEnabled() ? getModel(viewUuid) : extractClientModel(request)`, a
+C site's server read the ternary above. No wrapper helper on purpose: once every host runs with
+the switch on, the off branches are deleted line by line and what remains is the plain new code.
+The platform's own handlers are written this way. `getPreviousModel` with the switch off returns
+`getModel` and logs an ERROR: that code assumes a mode the server is not running in.
+
+Two traps the audit cannot see:
+
+- A handler that forwards the *request* to a callback which reads `params.model` (the platform's
+  password editor does this) depends on `extractClientModel` writing the typed instance back into
+  the params. Keep `extractClientModel` there, or hand the model over explicitly.
+- A handler that reads `compositeModel` by hand gets it backfilled only when its action still
+  has `composite=true`. Read the children's models from `viewApi` instead; the flag goes away
+  once no host reads the key.
+
+The measured spread, over the 56 host repositories that were audited when this shipped: 1061 read
+sites, 301 A, 671 B, 77 C.
+
 ### Bugfixes shipped with 7.0
 
 - `SmartformwidgetComponent.ngAfterViewInit` no longer crashes with