@smartbit4all/ng-client 6.0.35 → 7.0.1

package/WIDGETS.md

@@ -0,0 +1,206 @@
+# Writing a widget for `@smartbit4all/ng-client` 7.0
+
+A **widget** is a component that renders one part of a screen component's backend model and
+reloads itself when the backend says that part changed: a grid, a tree, a form, a map, a
+diagram — or one of your own.
+
+Until 7.0 only the library could have widgets. `SmartComponentApiClient` collected its
+children through eight `@ViewChildren` over eight concrete widget classes and dispatched on
+`instanceof`, so a host-authored widget could not join model-change routing at all, and the
+base class statically imported every widget type (which is why `chart.js` landed in every
+host bundle). 7.0 inverts that dependency: **a widget finds its client through DI and
+registers itself, and the client knows no widget type**.
+
+This document is the protocol. It is deliberately kept next to the library, in git, because
+it is what a new widget author needs; the reasoning behind each decision lives in the
+project's ADRs (`docs/adr/0005`–`0008` in the `platform-angular2` working copy), which are
+not part of the published package.
+
+## The whole contract
+
+```ts
+import {
+  injectSmartComponent,
+  registerSmartWidget,
+} from '@smartbit4all/ng-client';
+
+@Component({
+  selector: 'my-widget',
+  template: `…`,
+})
+export class MyWidgetComponent {
+  /** The identifier the backend knows this widget by. */
+  readonly identifier = input.required<string>();
+
+  /** The nearest screen component above this one, or undefined if there is none. */
+  private readonly smartComponent = injectSmartComponent();
+
+  private readonly model = signal<MyModel | undefined>(undefined);
+
+  constructor() {
+    registerSmartWidget(this.smartComponent, {
+      identifier: () => this.identifier(),
+      reload: () => this.load(),
+    });
+  }
+
+  private async load(): Promise<void> {
+    this.model.set(await lastValueFrom(this.api.get(this.identifier())));
+  }
+}
+```
+
+That is the entire registration. No module, no provider in the host, no entry in a registry,
+nothing to add to `SmartComponent`. Put `<my-widget identifier="…">` anywhere inside a screen
+component — including inside a layout the backend drives, inside a dialog, or inside one of
+your own sub-components — and it participates.
+
+### Six rules that follow from it
+
+1. **The nearest client above wins.** Resolution is plain element-injector resolution. An
+   embedded view rendered into a layout slot shadows its container for its own widgets; a
+   dialog page is its own root, because the library opens dialogs without a
+   `viewContainerRef`.
+
+2. **`identifier` is read lazily, every time.** It is a function in the registration, not a
+   value, because the identifier usually arrives with an input *after* the widget was
+   constructed. Never capture it.
+
+3. **To opt out, use `[smartComponentDetached]`.** Put it on an element whose subtree
+   deliberately renders something other than the client's model. Widgets below it resolve an
+   empty slot and neither reload nor take part in submit or validation.
+
+   ```html
+   <div smartComponentDetached>
+     <smart-grid [smartGrid]="myOwnGrid" [uuid]="myOwnUuid"></smart-grid>
+   </div>
+   ```
+
+4. **A widget outside any screen component is legal.** `injectSmartComponent()` returns
+   `undefined`, `registerSmartWidget` does nothing, and the widget works standalone from its
+   inputs. Do not guard against it.
+
+5. **Command handlers must be synchronous.** The client's `commands` stream is an RxJS
+   `Subject`, and the two commands that need an answer — `collectInvalidFields` and
+   `widgetChanged` — pass a mutable object that the caller reads back the moment `next()`
+   returns. A handler that defers (a `debounce`, an `await` before writing) silently
+   contributes nothing, and nothing at compile time will tell you.
+
+6. **`reloadDuringInitialSync` is a per-widget decision.** Right after the client's own
+   `load()` it replays the model's widget list with `skipLoad` set. A widget that fetches
+   from its own `ngAfterViewInit` leaves the flag off — that is the only reason it exists.
+   A widget that only fetches when told to sets it.
+
+## State is a signal
+
+7.0 runs without zone.js. Every component of the library is `OnPush`, and nothing is checked
+just because something, somewhere, ticked. So:
+
+- **What the widget writes and the template reads is a signal.** State written from a
+  subscription, a promise, a timer or a third-party callback needs one. State written from a
+  template event or an input does not.
+- **`markForCheck()` still works** — the scheduler ticks on it — and it remains the honest
+  answer for state the widget does not own: a host-supplied object mutated in place,
+  Angular's or Material's own state (`touched`, a `MatTree` data source), a third-party
+  callback.
+- **Anything the backend mutates *in place* needs its own signal or an explicit bump.** This
+  is the single hazard the library hit most often while converting. The model object arriving
+  with a field replaced inside it is invisible to a `computed` over the model signal.
+
+A convention worth copying, if you are converting an existing widget: keep a private signal
+and expose a getter/setter pair of the same name, so no read site and no template moves.
+
+```ts
+private readonly modelState = signal<MyModel | undefined>(undefined);
+@Input() set model(value: MyModel | undefined) { this.modelState.set(value); }
+get model(): MyModel | undefined { return this.modelState(); }
+```
+
+## Toolbars
+
+A toolbar renders the actions **addressed to its `id`** (`uiAction.toolbar == id`). The list
+comes from an explicit `[uiActionModels]` binding if there is one, otherwise from the screen
+component above it in the DOM. **Without an `id` it never pulls** — "unaddressed" is not an
+address.
+
+So a widget that carries a `toolbarId` in its model renders:
+
+```html
+<smart-ui-action-toolbar [id]="toolbarId"></smart-ui-action-toolbar>
+```
+
+and needs nothing else: the actions find it. Bind `[executor]` only when the actions are
+performed by something other than the screen component (a tree service, a dialog service of
+your own); `[widgetId]`, `[nodeId]` and `[actionParams]` belong on the toolbar too, not on
+each entry.
+
+If your widget *owns* a subtree whose toolbars must render a list it computed — the case the
+grid card hits, where the backend's row layout carries toolbar ids that no template in this
+library can bind — provide a `SmartActionHost` for that subtree and write the list into it:
+
+```ts
+@Component({ …, providers: [SmartActionHost] })
+export class MyRowComponent {
+  private readonly actionHost = inject(SmartActionHost);
+  // …
+  this.actionHost.actionModels.set(this.row.actions);
+}
+```
+
+Leaving it `undefined` means "not my business", and the toolbars below fall back to the
+client — which is what makes providing it unconditionally safe.
+
+**A `UiActionModel` is frozen.** Every field is `readonly`, and `[uiActionModels]` takes
+`readonly UiActionModel[]`. Build a new entry; never edit one. Writing into an entry a
+toolbar is already rendering never reached the screen under zone.js either — it only appeared
+to work when some other event happened to tick the application.
+
+```ts
+this.actions = this.actions.map((a) =>
+  a.uiAction.code === code ? { ...a, cssClass: 'active' } : a
+);
+```
+
+Reassigning the **array** is what re-renders. `this.actions[0] = { …this.actions[0] }`
+compiles and does nothing.
+
+## Three traps that have actually bitten
+
+1. **Declare your inputs — a plain public field is not one.**
+   `ComponentFactoryService` instantiates the components the library creates imperatively
+   (grid cards, expandable content, table cell components, the form's `COMPONENT` widget). It
+   writes every **declared** input with `ref.setInput()`, so a signal input, an aliased input
+   and `ngOnChanges` all behave exactly as they would under a template binding. An
+   **undeclared** field is still assigned — host components are free to have plain public
+   fields and 7.0 does not break them — but it warns, and such a field can never become a
+   signal input.
+
+   Until 7.0 the service assigned the field in every case, which *destroyed* a signal input:
+   the input is a function on the instance, so assigning over it replaced the function with
+   the value and the next `this.x()` threw `x is not a function`. That cost two debugging
+   rounds in the library (`parentLayoutComponent`, `gridRow`). If you are porting a widget
+   that carries a comment about this, the constraint is gone.
+
+2. **`@for (… ; track item)` over objects the backend rebuilds destroys the subtree every
+   refresh** (`NG0956`), and the DOM churn is real — a form inside is rebuilt. The backend
+   hands back new objects on each model refresh, so track by `$index`, or by a key you
+   synthesize yourself. Do not reach for a backend `identifier` field that is only sometimes
+   set: an all-`undefined` sibling list is `NG0955`, which is worse.
+
+3. **Style application is clear-then-apply.** `SmartStyleUtility.applyStyle` remembers what
+   it applied to an element and removes exactly that before applying the next set. If you
+   decorate an element the library also styles, decorate your *own* child element instead of
+   pushing classes into the object the backend sent — that object is shared, and mutating it
+   is invisible to change detection anyway.
+
+## The executable version
+
+Two specs in the library are written to be read as examples, and they travel with the source:
+
+- `src/lib/smart-client/smart-component-host.spec.ts` — a widget the library knows nothing
+  about joining model-change routing, the detach brake, and the nearest-client rule.
+- `src/lib/view-context/smart-ui-action/smart-action-host.spec.ts` — a subtree supplying the
+  actions its toolbars render, and the fallback when it does not.
+
+If a rule here and one of those specs disagree, the spec is right — say so and this document
+gets fixed.