@smartbit4all/ng-client 6.0.32 → 7.0.0

package/MIGRATION-7.0.md

@@ -0,0 +1,1641 @@
+# @smartbit4all/ng-client 6.x → 7.0 migration guide
+
+> 7.0.0 targets **Angular 22.0.8 / TypeScript 6.0.3 / Material 22.0.6**, with PrimeNG fully
+> removed (Material/CDK only), every library component `OnPush`, and **no zone.js** — the
+> configuration 7.0 is tested in. Angular's `moment` date adapter is replaced by `date-fns`.
+> It is a major because a host has to act; nothing here is a silent behaviour change that
+> you could ignore.
+
+## Where to start
+
+1. **Run the codemod** — [Migrating a host: the codemod](#migrating-a-host-the-codemod). It
+   does the mechanical part (the module imports, the provider configuration, the dead legacy
+   calls) and prints `file:line` for everything that needs a decision.
+2. Read [Full standalone + `provideSmartNgClient()`](#full-standalone--providesmartngclient-phase-32--the-big-one).
+   That section rewrites your `app.module.ts`; everything else is small next to it.
+3. Read [Dates](#dates-moment--date-fns-and-the-timezone-contract-phase-38). It is the one
+   change that needs action **at install time**, and the one that breaks at *runtime* on the
+   first screen with a date field rather than at build time.
+4. Then the rest in order. The **PrimeNG removal** sections (1.1–1.10) are API changes; the
+   **hop sections** carry the framework defaults you inherit (OnPush, fetch vs XHR, `?.`).
+5. If you write your own widget, `WIDGETS.md` next to this file is the protocol.
+
+Measured across the 12 hosts in scope on 2026-07-28, so you know what to expect: 12–17
+`Smart*Module` imports per host, 1–20 string-keyed providers, `.cssClass =` on an action
+entry at 72 sites in 7 hosts, `this.uiActionModels =` in 5 hosts, `UseUiAction` in 6.
+
+## Migrating a host: the codemod
+
+It lives in the `platform-angular2` repository — `tools/ng-client-7-codemod/` — and you run
+it with plain Node, from a checkout, against your own source directory. Nothing to install.
+
+```bash
+node tools/ng-client-7-codemod/migrate.mjs ../my-host/ui-angular/src --dry-run   # look first
+node tools/ng-client-7-codemod/migrate.mjs ../my-host/ui-angular/src            # then write
+```
+
+It **refuses to run on a dirty git tree** (its diff is how you review it, and `git checkout .`
+is how you undo it), it is **idempotent**, and it prints a verdict for every rule it knows —
+including `no sites found`, because a codemod that silently matched nothing looks exactly
+like one that had nothing to do.
+
+**What it rewrites:** the `Smart*Module` imports (into the standalone declarables of the
+mapping table below), the string-keyed providers and both `forRoot()` payloads (into one
+`provideSmartNgClient(config, ...features)` call), the redundant core services in the root
+providers array, `this.useQueryLists = true` / `handleDataChangeSubscriptions()`,
+`[parentSmartComponent]` and the dead `[parent]` inputs,
+`execute(x.uiAction, x)` → `execute(x)`, the `async` / `await` around
+`getActionDescriptor`, the `SmartdialogService` `super(…)` call and its constructor
+parameters, and PrimeNG module imports **no template in your repository renders**.
+
+**What it refuses to guess at**, printing `file:line` and the section here that explains it:
+`UseUiAction` → `UiActionExecutor`, `this.uiActionModels =`, `entry.cssClass =`, `addForm()`,
+the 4th argument of `addGrid()`, `getActionDescriptor(…).then(…)`, the moment adapter,
+component-level providers, every remaining `primeng/*` import, and `::ng-deep` selectors that
+reach into the form widget.
+
+**What it deliberately does not do:** convert *your* components to standalone. That is
+Angular's own schematic (`ng generate @angular/core:standalone`) and it is not required — an
+NgModule's `imports:` array takes standalone components, which is exactly what the codemod
+puts there. Do the library migration first, get the app running, then decide about standalone
+separately.
+
+Afterwards: run your formatter, swap the date packages ([Dates §1](#1-swap-the-peer-dependency)),
+build (expect one `NG8001` per template element whose component is not imported yet — that
+loop terminates), and **smoke the app**, because the DI changes are invisible to the compiler.
+
+## Breaking changes
+
+### Dialog stack: PrimeNG dynamicdialog → MatDialog (Phase 1.1)
+
+- `SmartdialogService` and `SmartViewContextDialogService` constructors no longer
+  take a PrimeNG `DialogService` parameter. If your host extends or instantiates
+  these services, drop the argument (MatDialog is injected internally).
+
+  Both arguments PrimeNG contributed are gone, so the base constructor lost two of
+  its four parameters:
+
+  ```ts
+  // 6.x
+  constructor(dialog: MatDialog, dialogService: DialogService, inject: Injector,
+              @Inject(COMPONENT_LIBRARY) compLib: ComponentLibrary) {
+    super(dialog, dialogService, inject, compLib);
+  }
+  // 7.0
+  constructor(dialog: MatDialog, inject: Injector) {
+    super(dialog, inject);
+  }
+  ```
+
+  **The codemod does this** (rule `smartdialog-super`), including the constructor
+  parameters and the now-unused `primeng/dynamicdialog` import — except where a
+  dropped parameter carries an accessibility modifier (`protected dialogService: …`),
+  which declares a class *property* the body may still read. Those are reported.
+- The `ComponentLibrary` switch no longer has a PrimeNG branch in the dialog
+  layer — all dialogs open via `MatDialog` regardless of `COMPONENT_LIBRARY`.
+
+### smart-form widgets: PrimeNG removed (Phase 1.2)
+
+- `ComparableDropdownDirective` and `ComparableMultiselectDirective` are removed
+  (they decorated the PrimeNG `p-dropdown` / `p-multiSelect` elements, which no
+  longer exist). Use `SmartformwidgetComponent.compareItems` semantics via
+  `mat-select [compareWith]`, which the widget template already wires up.
+- `SmartformwidgetComponent` constructor no longer takes the injected
+  `COMPONENT_LIBRARY` token; the widget renders Material-only.
+- `SmartformwidgetComponent` removed PrimeNG-only public members:
+  `errorMessages`, `getControlMessages()`, `onPrimeRichTextEditorContentChanged()`,
+  `safeDropDownBlur()`/`onDropDownShow()`/`onDropDownInput()`,
+  `safeCalendarBlur()`/`onCalendarShow()`/`onCalendarInput()`, `defaultDate`.
+- `SmartFormService.setValuesFromModel()` / `toFormGroup()` /
+  `createFormControls()` no longer take a `ComponentLibrary` parameter.
+- `SmartViewContextModule` no longer imports the PrimeNG form modules
+  (Dropdown, MultiSelect, Calendar, Chips, InputSwitch, Checkbox, InputNumber,
+  InputText, InputTextarea, InputMask, FloatLabel, Messages) and no longer
+  provides `Dropdown` / `MultiSelect`.
+
+### fileupload: PrimeNG removed (Phase 1.4)
+
+- `SmartFileUploaderComponent` (selector `smart-file-uploader4sc`) is removed
+  from the public API. It was a PrimeNG `p-fileUpload` wrapper declared in
+  `SmartNgClientModule` but referenced nowhere; the Material-style
+  `SmartfileuploaderComponent` (selector `smartfileuploader`) is the uploader.
+- The internal `PrimeFileUploaderComponent` (selector `prime-file-uploader`)
+  is removed; `smart-upload-widget` always renders `smartfileuploader`.
+- `UploadWidgetComponent` constructor no longer takes the injected
+  `COMPONENT_LIBRARY` token, and its PrimeNG-only members are gone
+  (`fileUploadPrime`, `uploadFiles()`).
+- `SmartNgClientModule` and `SmartViewContextModule` no longer import the
+  PrimeNG `FileUploadModule`; `SmartViewContextModule` also dropped the dead
+  `OverlayPanelModule` import (Phase 1.3).
+
+### editor: Quill 1.3 → 2, quill-emoji removed (Phase 1.5)
+
+- Peer dependencies changed: `quill` `^1.3.7` → `^2.0.3`, `ngx-quill`
+  `16.2.1 - 24.0.5` → `^25.3.3`. Hosts must bump both together (ngx-quill 25.x
+  is the Quill 2 line for Angular 17; later Angular hops will raise it further).
+- `quill-emoji` peer dependency is **removed** (dead, Quill 1-only, unmaintained).
+  If a host needs emoji support, pick a Quill 2-compatible module on its own.
+- `@types/quill` must be removed from host devDependencies — Quill 2 ships its
+  own TypeScript types, and the stale `@types/quill` 1.x conflicts with them.
+- The bundled `quill.snow.css` (imported by the smart-form widget) is now the
+  Quill 2.0.3 stylesheet; hosts that import `quill/dist/quill.snow.css`
+  themselves must serve the Quill 2 version.
+- `SmartViewContextModule` no longer imports the PrimeNG `EditorModule`
+  (`<p-editor>` died with Phase 1.2; RICH_TEXT renders via ngx-quill).
+
+### smart-diagram: p-chart replaced by direct chart.js (Phase 1.6)
+
+- `SmartDiagramComponent` renders its own `<canvas>` and instantiates chart.js
+  directly; the PrimeNG `<p-chart>` wrapper (and the `ChartModule` import in
+  `SmartDiagramModule`) is gone. Chart.js controllers are now registered by the
+  component itself (`Chart.register(...registerables)`), so no `chart.js/auto`
+  import is needed anywhere.
+- The public `chart` property (and `getChart()`) is now the chart.js `Chart`
+  instance instead of the PrimeNG `UIChart` component. `getBase64Image()` and
+  `refresh()` keep their signatures (delegating to `toBase64Image()` /
+  `update()`).
+- `SmartDiagramComponent` constructor no longer takes the injected
+  `COMPONENT_LIBRARY` token; the component has a single render path.
+- DOM/CSS hooks changed: the internal structure is
+  `div.chart-host > div.chart-container > canvas`; host styles targeting
+  `::ng-deep p-chart` no longer match. The aspect-ratio classes
+  (`default-aspect-ratio` / `pie-aspect-ratio`) are now applied on
+  `.chart-host` and size `.chart-container`.
+
+### smart-grid: PrimeNG branch removed (Phase 1.7)
+
+- `SmartGridComponent` renders Material-only. The `@if (compLib === PRIMENG)`
+  template branch (the inline `p-table` / `p-paginator` / `p-menu` /
+  `p-multiSelect` grid) is gone; the grid always renders through the PrimeNG-free
+  `smart-table` (the `#table` slot), `mat-tree`, `app-smart-grid-card`, and
+  `mat-paginator`.
+- `SmartGridComponent` constructor no longer takes the injected
+  `COMPONENT_LIBRARY` token, nor the `SmartDatePipe` / `SmartDateTimePipe` /
+  `SmartTimePipe` (they only fed the removed inline `p-table` cell renderer);
+  those pipes are dropped from the component `providers` too.
+- Removed PrimeNG-only public members: `columns`, `menuButtons`, `menu`,
+  `onOptionsClick()`, `previousmultiSortMeta`, `gridSort()`, `lazyLoad()`,
+  `headerChange()`, `onColOrder()`, `getOrderColumNames()`, `getColValue()`,
+  `onPrimeChangePage()`, `onRowSelect()`, `onRowUnselect()`, `onSelectAllRow()`,
+  `getImageResourceIcons()`, `getImageResourceStyle()`, `getRowColumnAction()`,
+  `showCellToolbar()`, `shouldShowOptionsButton()`, `calculateMenuActions()`,
+  `createCellToActionMap()`, `getRowMenuActionModelArray()`, `rowTrackByFn()`,
+  `cellToActionMap`, `columnMetaByName`, and the `_headerToolbar`
+  (`#headerToolbar`) view child. The `headerToolbar` getter now returns the
+  smart-table's header toolbar unconditionally (its only remaining consumer,
+  `SmartComponentApiClient`, is unaffected).
+- `SmartGridModule` no longer imports the PrimeNG `TableModule`, `ButtonModule`,
+  `MenuModule`, `PaginatorModule`, `MultiSelectModule`; `MatTooltipModule` is
+  added (the grid refresh button is now a Material `mat-icon-button` +
+  `matTooltip` instead of `pButton` + `pTooltip`).
+- Note: this is the PrimeNG-branch deletion only. The `smart-grid` internals
+  rewrite to `mat-table` + `MatPaginator` and the `smart-grid`/`smart-table`
+  merge remain a Phase 3 (post-Angular-22) change.
+
+### misc widgets: PrimeNG branches removed (Phase 1.8)
+
+The remaining components that still carried a dead PrimeNG branch alongside an
+already-active Material one are now Material-only. In every case the Material
+branch was the rendered path under `COMPONENT_LIBRARY = MATERIAL` (the value all
+7.0 hosts use), so this is render-neutral; the `COMPONENT_LIBRARY` token, where
+these components still injected it, is now ignored by them.
+
+- `ExpandableSectionComponent` renders Material-only (the `p-accordion` branch is
+  gone; always `mat-expansion-panel`). Its constructor no longer takes the
+  injected `COMPONENT_LIBRARY` token. `SmartExpandableSectionModule` no longer
+  imports the PrimeNG `AccordionModule`.
+- `UiActionButtonComponent` renders Material-only (the `pButton`/`pRipple` branch
+  is gone; always `mat-button`). Its constructor no longer takes the optional
+  `COMPONENT_LIBRARY` token (it previously defaulted to `PRIMENG` when unset).
+  `getType()` no longer has a PrimeNG class-map branch — it returns the
+  `mat-mdc-*` class strings unconditionally. (The dynamic `getbtnClass()`'s
+  `p-button-<color>` class token was later dropped in Phase 1.9.)
+- `UiActionToolbarComponent` constructor no longer takes the injected
+  `COMPONENT_LIBRARY` token. The dead `getType()` / `getbtnClass()` methods
+  (never referenced by the template) were removed, and the scroll-affordance
+  buttons use the Material icons `arrow_back` / `arrow_forward` unconditionally
+  (the PrimeNG `chevron-left` / `chevron-right` fallback is gone).
+- `UiActionConfirmDialogComponent` and `UiActionInputDialogComponent` render
+  their close button as a Material `mat-icon-button` unconditionally (the `@else`
+  `p-button` branch is gone); both constructors no longer take the injected
+  `COMPONENT_LIBRARY` token.
+- `SmartIconModule` no longer imports the PrimeNG `BadgeModule` (badges render
+  via the custom `ui-badge` component, unaffected).
+- `SmartViewContextModule` no longer imports the PrimeNG `ButtonModule`,
+  `TooltipModule`, `ToastModule`, `ImageModule`, or `OrderListModule` (all
+  unused after the branch deletions). The `primeng/api` `SharedModule`
+  (`PrimeSharedModule`) import was later dropped in Phase 1.9's final sweep.
+
+### PrimeNG package dependency removed (Phase 1.9)
+
+The `primeng` npm package is gone. Most importantly it is dropped from
+`@smartbit4all/ng-client`'s own **`peerDependencies`** (in
+`projects/smart-ng-client/package.json`, which flows into the published
+`npms/smart-ng-client/package.json`) — that entry is what previously forced every
+consuming host to install PrimeNG. It is also removed from the dev workspace
+(`package.json`, `package-lock.json`, `node_modules`), and both PrimeNG theme
+stylesheets (`primeng/resources/themes/saga-blue/theme.css`,
+`primeng/resources/primeng.min.css`) are removed from the app-playground `styles`
+in `angular.json`. Hosts that still list `primeng` as a dependency or load its
+theme CSS should remove both; 7.0 renders entirely on Material/CDK.
+
+#### Your own PrimeNG usage
+
+Removing the peer dependency does not remove PrimeNG from *your* code, and the measured
+hosts carry more of it than their authors expect — mostly as **dead module imports**. Across
+the 12 hosts, `DialogService` is imported 56 times, but 8 of those in p014 turned out to be
+nothing but the base-constructor argument above, and four PrimeNG modules in its
+`app.module.ts` rendered nothing at all.
+
+So the codemod separates the two cases, and the separation is decidable rather than
+guessed:
+
+- **`primeng-modules`** — a PrimeNG NgModule in an `imports:` array is **deleted** when none
+  of its selectors appears in any template in the repository. The scan runs over `.html`
+  *and* `.ts` (for inline templates) before anything is rewritten, and it distinguishes an
+  element (`<p-tree>`) from an attribute directive (`pTooltip`) so that a leftover
+  `class="p-button"` is not read as a component still in use. What the scan found is printed
+  in the header, because it is what licenses the deletions.
+- **`primeng-imports`** — everything else from `primeng/*` is reported with its replacement.
+  These are the real ports.
+
+The replacements, for what the hosts actually import:
+
+| PrimeNG | Material / CDK |
+|---|---|
+| `p-button` / `pButton` | `MatButtonModule` — `mat-button`, `mat-icon-button` |
+| `p-tree` | the library's `<smart-tree>`, or `MatTreeModule` |
+| `p-progressSpinner` | `MatProgressSpinnerModule` — `<mat-spinner>` |
+| `pTooltip` | `MatTooltipModule` (`matTooltip`), or `SmartTooltipDirective` |
+| `p-sidebar` | `MatSidenavModule` |
+| `pInputText` | `MatInputModule` — `matInput` inside `<mat-form-field>` |
+| `p-fieldset` | `MatCardModule`, or `<fieldset>` + `<mat-divider>` |
+| `p-divider` | `MatDividerModule` |
+| `p-accordion` | `MatExpansionModule`, or `<smart-expandable-section>` |
+| `p-table` | the library's `<smart-grid>`, or `MatTableModule` |
+| `p-editor` | ngx-quill's `<quill-editor>` (already a library dependency) |
+| `p-badge` / `pBadge` | `MatBadgeModule`, or `UiBadgeComponent` / `UiBadgeDirective` |
+| `p-menu`, `p-overlayPanel` | `MatMenuModule`, or the CDK Overlay |
+| `p-inputSwitch` | `MatSlideToggleModule` |
+| `p-dialog` | `MatDialog` — open a component instead of toggling `[visible]` |
+| `DialogService` | `MatDialog`. There is **no `header` option**: put `<h2 mat-dialog-title>` in the component |
+| `DynamicDialogRef` | `MatDialogRef` — `afterClosed()` replaces `onClose` |
+| `DynamicDialogConfig` | `MAT_DIALOG_DATA` for the data, `MatDialogRef` for the rest |
+| `PrimeNGConfig` | **delete it.** `setTranslation()` of day and month names is already covered by `MAT_DATE_LOCALE` + `SmartDateFnsAdapter` — the date-fns `hu` locale carries both the names and the Monday week start (see [Dates](#dates-moment--date-fns-and-the-timezone-contract-phase-38)) |
+| `MessageService` | `MatSnackBar` |
+| `ConfirmationService` | the library's `UiActionConfirmDialogService` |
+| `MenuItem` | the library's `UiActionModel`, or a plain `<mat-menu>` item |
+| `SharedModule` (`primeng/api`) / `PrimeTemplate` | a plain `<ng-template>` — PrimeNG needed `pTemplate`, Material does not |
+
+`primeicons` is a separate package. Nothing in 7.0 needs it, but nothing breaks if you keep
+it either — `pi pi-*` class names are just a font.
+
+### `QuillModule.forRoot()` in your root module
+
+`provideSmartNgClient()` calls `importProvidersFrom(QuillModule.forRoot())` itself — ngx-quill
+has no provider function, so the module is the only way to reach its root configuration. A
+root module that also calls it is configuring quill twice, so the codemod removes the call
+and its import. In a *feature* module the same call is that module's own configuration and is
+left alone.
+
+**Keep `ngx-quill` and `quill` in your `package.json`.** They are peer dependencies of the
+library — the host provides them. npm installs peers automatically, which is why hosts have
+got away with not declaring them, but any install that runs with `--legacy-peer-deps` drops
+them silently and the next build fails on an import that has always worked. Two of the twelve
+measured hosts were in exactly that state.
+
+**7.0 adds four peer dependencies 6.x did not have**, and they bite in a way the TypeScript
+errors do not prepare you for:
+
+```bash
+npm install ngx-mask@^22.0.0 fast-equals@^5.0.1 wavesurfer.js@^7.9.5 @angular/youtube-player@^22.0.0
+```
+
+If you install the library the normal way, npm brings these in for you. If you *swap a local
+build into `node_modules` by hand* — which is how you would try the library before it is
+published — npm never runs, so nothing installs them. The symptom arrives **after** the last
+TypeScript error is fixed, as five `Module not found` errors reported against the library's
+own `fesm2022` bundle rather than against any file of yours:
+
+```
+./node_modules/@smartbit4all/ng-client/fesm2022/smartbit4all-ng-client.mjs:7:0-60 -
+  Error: Module not found: Error: Can't resolve 'ngx-mask'
+```
+
+Four packages, five errors: `wavesurfer.js` is missing twice, once for its `record` plugin.
+
+- `UiActionButtonComponent.getbtnClass()` no longer emits the dead
+  `p-button-<color>` class token — it returns only `sb4-<color>` (nothing styled
+  `.p-button-*`; the platform button theme keys off `sb4-<color>` in
+  `custom-theme.scss`). Hosts with their own `.p-button-<color>` overrides for
+  sb4 action buttons should migrate them to `.sb4-<color>`.
+- `SmartViewContextModule` no longer imports the `primeng/api` `SharedModule`
+  (`PrimeSharedModule`); no template in the module used `pTemplate`.
+- `SmartComponentLayoutModule` no longer imports `InputGroupModule` /
+  `InputGroupAddonModule` (they were dead — no `p-inputGroup` template existed).
+
+The `ComponentLibrary` enum still exists with only its `MATERIAL` member in
+active use; its `PRIMENG` member and the remaining dead `ComponentLibrary.PRIMENG`
+code branches (icon/menu/widget components, dead `.p-*`/`.pi` CSS) are removed in
+a follow-up internal-cleanup step (1.10) — they are not a package dependency and
+do not affect hosts. `deviceInfo.componentLibrary` continues to report
+`material` to the backend.
+
+### ComponentLibrary / COMPONENT_LIBRARY removed entirely (Phase 1.10)
+
+7.0 is Material-only, so the `ComponentLibrary` abstraction (which had no second
+implementation once PrimeNG was gone) is deleted outright.
+
+- **Host action required:** `ComponentLibrary` (enum) and `COMPONENT_LIBRARY`
+  (injection token) are no longer exported from `@smartbit4all/ng-client`. Hosts
+  that provide `{ provide: COMPONENT_LIBRARY, useValue: ComponentLibrary.MATERIAL }`
+  in their root providers must **remove that provider and its import** — it now
+  fails to compile (no exported member). No replacement is needed; every component
+  renders Material-only.
+- Every `@Inject(COMPONENT_LIBRARY)` constructor argument is gone from the library
+  (smart-icon, click/hover tiered menu, photo-capture / voice-record widgets,
+  smart-voice-recorder, smart-file-editor, smart-multi-file-editor, sortable
+  widget, smart-filter-editor-content, validation-result-page, message-dialog, the
+  dialog services `SmartdialogService` / `SmartViewContextDialogService` /
+  `SmartViewContextErrorDialogService` / the ui-action confirm/input/file-upload
+  dialog services, and `PdfViewerDialogService` in `@smartbit4all/document-explorer`).
+  The `SmartdialogService` base constructor is now `(dialog, injector)` — subclasses
+  that called `super(dialog, dialogService, injector, compLib)` keep the first and
+  third arguments only. See [Phase 1.1](#dialog-stack-primeng-dynamicdialog--matdialog-phase-11);
+  the codemod rewrites it.
+- `SmartViewContextService` no longer exposes the public `componentLibrary` field
+  and no longer injects the token; it now writes the literal `'material'` into
+  `deviceInfo.componentLibrary` on every view-context update (the backend keys its
+  icon set on this string — `images-playground.properties` has `.material=` vs
+  `.primeng=` variants — so the value keeps flowing; the DTO field is unchanged).
+- All dead `ComponentLibrary.PRIMENG` branches and their PrimeNG icon names
+  (`chevron-right`, `pi pi-*`, `power-off`, `trash`, `file`, `exclamation-circle`,
+  `play-circle`/`stop-circle`, etc.) are removed; the Material icon path is now
+  unconditional. Dead `.p-*` / `.pi` CSS rules were purged from the library
+  (smart-icon, smartform, smartformwidget, the file editors/uploader,
+  ui-action-file-upload-dialog) and from the app-playground `custom-theme.scss`;
+  the app-playground `index.html` no longer loads the `primeicons` CDN stylesheet.
+- After 1.10, `grep -rin primeng projects` reports a single residual: the
+  auto-generated `deviceInfo.ts` DTO doc comment (`(Material, PrimeNg)`), which
+  mirrors the backend OpenAPI field description and is regenerated from it — left
+  untouched by design (the field itself is intentionally kept).
+
+### Angular 18 hop (Phase 2, 17 → 18)
+
+The library line now builds against Angular 18. Host-relevant changes:
+
+- **Peer dependency bumps** (hosts must upgrade together with the lib):
+  `@angular/*` `^18.0.0`, `@angular/youtube-player` `^18.2.14` (was lagging on
+  `^16` — its `^16 || ^17` peer range breaks a strict `npm install` on Angular
+  18, so it can no longer lag), `ngx-quill` `^26.0.0` (the Angular 18 line;
+  quill stays `^2.0.3`), `ngx-mask` `^18.0.0`, and — for
+  `@smartbit4all/document-explorer` — `ngx-extended-pdf-viewer` `^21.0.0`
+  (the 19.x/20.x lines cap their Angular peer below 18).
+- **`parchment` hoisting quirk (ngx-quill 26):** the ngx-quill 26 typings
+  reference `import("parchment")`, but npm may leave `parchment` nested under
+  `node_modules/quill/` (even after `npm dedupe`), which fails the host build
+  with `TS2307: Cannot find module 'parchment'`. Fix: add
+  `"parchment": "^3.0.0"` to the host devDependencies so it is hoisted to the
+  top level (quill 2 depends on parchment 3, so versions cannot conflict).
+- **Material theming (M2 compat APIs):** the `ng update @angular/material@18`
+  schematic rewrites M2 theme SCSS to the prefixed compat API
+  (`mat.define-palette` → `mat.m2-define-palette`,
+  `mat.$indigo-palette` → `mat.$m2-indigo-palette`,
+  `mat.define-light-theme` → `mat.m2-define-light-theme`, …). The theme stays
+  visually **M2** — no M3 switch happens at this hop; hosts running the
+  schematic get this rewrite automatically.
+- **`HttpClientModule` deprecation:** the `ng update @angular/core@18`
+  migration replaces `HttpClientModule` imports with
+  `provideHttpClient(withInterceptorsFromDi())`. Not a library breaking
+  change (the lib's generated API services were migrated internally), but
+  hosts will get the same automatic migration in their own modules.
+- TypeScript requirement raised to `>=5.4` (the repo builds on 5.5).
+
+### Angular 19 hop (Phase 2, 18 → 19)
+
+The library line now builds against Angular 19. Host-relevant changes:
+
+- **Peer dependency bumps** (hosts must upgrade together with the lib):
+  `@angular/*` `^19.0.0`, `@angular/youtube-player` `^19.0.0`,
+  `ngx-quill` `^27.0.0` (the Angular 19 line; quill stays `^2.0.3`),
+  `ngx-mask` `^19.0.0`, and — for `@smartbit4all/document-explorer` —
+  `ngx-extended-pdf-viewer` `^22.0.0` (the 21.x line caps its Angular peer
+  below 19).
+- **ngx-extended-pdf-viewer 22 input rename:** the `[showScrollingButton]`
+  input no longer exists — it is `[showScrollingButtons]` (plural,
+  `ResponsiveVisibility`). Hosts that use `<ngx-extended-pdf-viewer>` directly
+  must rename the binding, otherwise the template fails with NG8002.
+- **Standalone-by-default:** in Angular 19 components/directives/pipes are
+  standalone unless declared otherwise. The `ng update @angular/core@19`
+  migration automatically adds `standalone: false` to every NgModule-declared
+  declarable in the host codebase — run it and review the (large, mechanical)
+  diff. Declarables not referenced by any NgModule are skipped by the
+  schematic.
+- **Material theming:** the `ng update @angular/material@19` schematic splits
+  `@include mat.core()` into `@include mat.elevation-classes()` +
+  `@include mat.app-background()`. No visual change; hosts running the
+  schematic get this rewrite automatically.
+- **New NG8111 extended diagnostic** (warning): "Function in event binding
+  should be invoked". Uninvoked event bindings like
+  `(click)="(someCallback)"` — previously silently dead — are now flagged at
+  build time. Warning only, the build stays green.
+- TypeScript requirement stays satisfied by 5.5 (Angular 19 supports
+  TS 5.5–5.8).
+
+### Angular 20 hop (Phase 2, 19 → 20)
+
+The library line now builds against Angular 20. Host-relevant changes:
+
+- **Peer dependency bumps** (hosts must upgrade together with the lib):
+  `@angular/*` `^20.0.0`, `@angular/youtube-player` `^20.0.0`,
+  `ngx-quill` `^28.0.0` (the Angular 20 line; quill stays `^2.0.3`),
+  `ngx-mask` `^20.0.0`, and — for `@smartbit4all/document-explorer` —
+  `ngx-extended-pdf-viewer` `^23.0.0` (the 22.x line caps its Angular peer
+  below 20). No pdf-viewer API rename at this bump (unlike 22.x).
+- **TypeScript 5.9 required** (Angular 20 supports 5.8–5.9); `ng update`
+  bumps it automatically. TS 5.9 adds **TS2872 "This kind of expression is
+  always truthy"**, which turns previously-silent dead `||` alternatives into
+  build errors — expect one or two in any older codebase.
+- **Material 20 button labels no longer set `white-space: nowrap`.** Material
+  20 dropped the MDC stylesheet (`@material/button`), which used to carry it.
+  Multi-word button labels now wrap, and any rule that lets the button size to
+  its content (the lib's `.mdc-button { height: fit-content }`) makes the
+  button grow taller. The lib restores the pre-20 look inside
+  `ui-action-button` (`.mdc-button__label { white-space: nowrap }`); **hosts
+  that render Material buttons of their own must add the same rule** if they
+  relied on single-line labels (typical symptom: a navigation bar that
+  suddenly wraps and overflows into scroll arrows).
+- **Material 20 renamed the MDC-era CSS custom properties**: e.g.
+  `--mdc-text-button-container-height` → `--mat-button-text-container-height`.
+  The `ng update @angular/material@20` schematic rewrites the ones it finds in
+  `.css`/`.scss` files; token names embedded in TS strings or host templates
+  must be renamed by hand.
+- **`DOCUMENT` moved from `@angular/common` to `@angular/core`.** Automatic
+  migration; `@angular/common`'s re-export is deprecated.
+- **`moduleResolution: "node"` → `"bundler"`** in `tsconfig.json` (and any
+  `tsconfig.lib.json` that sets it explicitly). Automatic migration; it changes
+  how sub-path exports resolve, so a host with hand-written `paths` entries
+  should re-verify its build.
+- **Workspace generation defaults**: the CLI adds a `schematics` block to
+  `angular.json` pinning the pre-20 file-naming style (`type: "component"`,
+  `typeSeparator: "."`). Cosmetic — it only affects newly generated files.
+- Optional migrations **not** run here (deferred to the modernization phase):
+  `use-application-builder` (esbuild), `control-flow-migration`,
+  `router-current-navigation`.
+- The `InjectFlags`, `TestBed.get` → `TestBed.inject` and
+  `provideServerRendering` migrations were no-ops for this codebase.
+- The NG8111 warnings introduced at the 19 hop are no longer emitted by the
+  Angular 20 compiler (the dead bindings themselves are unchanged).
+
+### Angular 21 hop (Phase 2, 20 → 21)
+
+The library line now builds against Angular 21. Host-relevant changes:
+
+- **Peer dependency bumps** (hosts must upgrade together with the lib):
+  `@angular/*` `^21.0.0`, `@angular/youtube-player` `^21.0.0`,
+  `ngx-quill` `^29.0.0` (the Angular 21 line; quill stays `^2.0.3`),
+  `ngx-mask` `^21.0.0`, and — for `@smartbit4all/document-explorer` —
+  `ngx-extended-pdf-viewer` `^25.0.0` (the 24.x line still caps its Angular
+  peer below 21). No pdf-viewer API rename at this bump.
+  - **`ngx-quill` 30.x is intentionally *not* used.** 30.x is the "zoneless"
+    line and drops the `zone.js` peer dependency; the 7.0 lib is still
+    zone-based. Hosts that have already gone zoneless may use 30.x, but the
+    lib is only validated against 29.x.
+- **TypeScript stays 5.9** and **zone.js stays 0.15** (Angular 21 accepts
+  `~0.15.0 || ~0.16.0`). **Node** must satisfy
+  `^20.19.0 || ^22.12.0 || >=24.0.0`.
+- **`MatCommonModule` is removed from `@angular/material/core` (breaking).**
+  It was already deprecated in Material 20 (`@breaking-change 21.0.0`). Any
+  host NgModule that imports it will fail to compile with
+  `Unknown reference` — and because a broken NgModule cascades, the real
+  error usually shows up as a flood of `NG8001: '<some-component>' is not a
+  known element` / `NG6002: … does not appear to be an NgModule class`
+  further down the build log. **Fix: just delete the import and the array
+  entry.** `MatCommonModule` had no template surface; it only
+  (a) applied the `cdk-high-contrast-*` body classes — `A11yModule` still
+  does this, and Material components that need it import `A11yModule`
+  themselves — and (b) re-exported `BidiModule`. If your host actually uses
+  the `Dir` directive or injects `Directionality`, import
+  `BidiModule` from `@angular/cdk/bidi` explicitly.
+  The lib dropped it from all 10 of its own modules.
+- **`provideZoneChangeDetection()` is now added at bootstrap** by the
+  `ng update` migration, e.g.
+  `bootstrapModule(AppModule, { applicationProviders: [provideZoneChangeDetection()] })`.
+  This keeps zone-based change detection explicit; behaviour is unchanged.
+- **The control-flow migration (`*ngIf` → `@if`) now runs as a *mandatory*
+  `ng update` migration**, not an optional one. It rewrites every structural
+  directive in the workspace. The lib **reverted** it to keep the version hop
+  reviewable — `NgIf`/`NgForOf`/`NgSwitch` still ship in Angular 21, so
+  `*ngIf`/`*ngFor` keep working. Hosts may keep or revert it as they prefer;
+  if you want it as a separate change, run
+  `npx ng generate @angular/core:control-flow` on its own commit.
+- **New `NG8107` extended diagnostic** (warning): an optional chain `?.`
+  whose left side can no longer be `null`/`undefined` under Angular 21's
+  sharpened template inference. Warning only — expect a batch of them in any
+  older template set.
+- **`tsconfig.json` loses its explicit `lib` array** (the CLI derives it from
+  `target`). Automatic migration.
+- The Material and CDK v21 migration schematics made no source changes, and
+  the `Router.lastSuccessfulNavigation` migration was a no-op. The optional
+  `router-current-navigation` migration was not run.
+- The `.mdc-button__label { white-space: nowrap }` workaround introduced at
+  the Angular 20 hop is **still required on Material 21** — the class still
+  exists in the button template and Material still ships no `white-space`
+  rule for it.
+
+### Angular 22 hop (Phase 2, 21 → 22) — final hop
+
+The library line now builds against **Angular 22**. This is the biggest
+host-facing hop of the series: it changes the **change-detection default**, the
+**HTTP backend default** and the **meaning of `?.` in templates**. All three are
+handled by `ng update` migrations, but you must let them run.
+
+- **Peer dependency bumps** (hosts must upgrade together with the lib):
+  `@angular/*` `^22.0.0`, `@angular/youtube-player` `^22.0.0`,
+  `ngx-quill` `^31.0.0` (the Angular 22 line; quill stays `^2.0.3`),
+  `ngx-mask` `^22.0.0`, and — for `@smartbit4all/document-explorer` —
+  `ngx-extended-pdf-viewer` `^28.0.0` (25/26/27 all cap their Angular peer
+  below 22). **No pdf-viewer API rename at this bump.**
+  `@ngx-translate/core` `^14` still works (its peer is `>=13`).
+- **TypeScript must be 6.0** (`@angular/compiler-cli` peers `>=6.0 <6.1`);
+  **zone.js stays 0.15** (`~0.15.0 || ~0.16.0`) and **rxjs is unchanged**.
+  **Node** must satisfy `^22.22.3 || ^24.15.0 || >=26.0.0` — note the
+  **22.22.3** floor, which is stricter than Angular 21's `^22.12.0`.
+
+#### 1. `ChangeDetectionStrategy.OnPush` is the new default
+
+In Angular 22 the enum is redefined: `OnPush = 0` (default), `Eager = 1`, and
+`Default = 1` is kept as a **deprecated alias of `Eager`**. Any component
+without an explicit `changeDetection` therefore switches from CheckAlways to
+OnPush — a real behaviour change for components that mutate their own state
+without signals or `markForCheck()`.
+
+An `ng update` schematic **automatically adds
+`changeDetection: ChangeDetectionStrategy.Eager` to every component that had
+none**, which keeps behaviour bit-identical. The lib took exactly this route
+(114 components) and did **not** opt into OnPush at this hop. Recommended host
+approach: let the schematic run, verify your app, and move components to OnPush
+deliberately afterwards.
+
+Watch out for components the schematic can skip — it only touches components it
+can resolve. After updating, grep for `@Component` files with no
+`changeDetection` and decide about each one; a component that is dynamically
+instantiated but never statically declared can slip through.
+
+#### 2. `provideHttpClient` now defaults to the fetch backend
+
+Angular 22 switches `HttpClient` from `XMLHttpRequest` to `fetch`. An
+`ng update` migration inserts **`withXhr()`** into your `provideHttpClient(...)`
+calls to preserve the old backend:
+
+```ts
+provideHttpClient(withXhr(), withInterceptorsFromDi())
+```
+
+The lib does this in `SmartViewContextModule`. **Hosts that call
+`provideHttpClient` themselves must do the same** (or consciously move to
+fetch). This matters most for **upload progress**: `reportProgress` events
+behave differently on the fetch backend, so if your host reports upload
+progress, keep `withXhr()` until you have retested it.
+
+#### 3. `?.` in templates now yields `undefined`, not `null`
+
+Angular 22's safe-navigation operator returns `undefined` where it used to
+return `null`. Where that difference is observable, an `ng update` migration
+wraps the expression in the **`$safeNavigationMigration()` compiler builtin**:
+
+```html
+[ngStyle]="calcStyle($safeNavigationMigration(diagramModel?.descriptor?.style))"
+```
+
+This is an official builtin (handled like `$any()` — the compiler unwraps it and
+the type-checker sees straight through it), not a temporary marker, so wrapped
+templates are safe to keep. The same `ng update` run also sets the
+`nullishCoalescingNotNullable` and `optionalChainNotNullable` extended
+diagnostics to `suppress` in your tsconfigs, which silences the `NG8107`
+warnings the Angular 21 hop introduced.
+
+#### 4. `ComponentFactoryResolver` is removed (breaking)
+
+`ComponentFactoryResolver` is gone and `ComponentFactory` is no longer public
+(it only survives as `ɵRender3ComponentFactory`). Code like this stops
+compiling with `TS2305` / `NG2003`:
+
+```ts
+constructor(private resolver: ComponentFactoryResolver) {}
+ngAfterViewInit() {
+  const factory = this.resolver.resolveComponentFactory(MyComponent);
+  this.vcRef.createComponent(factory);
+}
+```
+
+Replace it with the type-based overload — behaviour is identical (v22 builds the
+same factory internally and resolves the injector from the parent):
+
+```ts
+ngAfterViewInit() {
+  this.vcRef.createComponent(MyComponent);
+}
+```
+
+**Public-API change in the lib:** `ComponentFactoryService` no longer exposes
+its `factory` field. `createComponent()` / `destroyComponent()` keep their
+signatures, so hosts that only call those need no change.
+
+#### 5. TypeScript 6.0 deprecates `baseUrl` and `downlevelIteration`
+
+TS 6.0 raises **`TS5101`** for both options ("deprecated and will stop
+functioning in TypeScript 7.0"). Two ways out:
+
+- Remove them. `downlevelIteration` is a no-op at `target: ES2022`. `baseUrl`
+  can only go once every non-relative first-party import (`from 'projects/…'`,
+  `from 'src/…'`) is relative or covered by a `paths` entry.
+- Or silence them for now with `"ignoreDeprecations": "6.0"` in
+  `compilerOptions`. This is what the lib workspace does, because `baseUrl` is
+  still load-bearing there. It only buys time until TS 7.
+
+#### 6. Other notes
+
+- **Material 22 removed no further modules or tokens** — the CDK and Material
+  v22 migration schematics made no source changes. CDK 22 moves to a
+  package `exports` map (the per-entry-point sub-directories are gone from
+  `node_modules/@angular/cdk`), but every `@angular/cdk/*` import still
+  resolves; this only matters if you referenced those paths on disk.
+- The `.mdc-button__label { white-space: nowrap }` workaround introduced at the
+  Angular 20 hop is **still required on Material 22** — the class still appears
+  in Material's button template and Material still ships no `white-space` rule
+  for it.
+- **The control-flow migration did not re-run at this hop** (it was mandatory at
+  21). The lib still ships `*ngIf`/`*ngFor` templates; `NgIf`/`NgForOf`/
+  `NgSwitch` continue to work in Angular 22.
+- **The webpack-based builders are deprecated.** `@angular-devkit/build-angular`
+  now prints a notice recommending `@angular/build`. Nothing breaks yet, but
+  plan the switch.
+- `strictTemplates` is on by default in v22; the lib workspace was already
+  strict, so nothing changed. If your host was not strict, the `ng update`
+  migration adds `"strictTemplates": false` to keep it that way.
+
+### Housekeeping (Phase 3.0)
+
+#### The dialog's built-in Ok/Cancel buttons are gone
+
+`smartdialog.component.html` no longer renders an `Ok` and a `Cancel` button.
+They were dead: their `(click)` handlers were the no-op expressions
+`(click)="(data.okCallback)"` / `(click)="(data.cancelCallback)"` — a bare
+property read, not a call — so pressing them did nothing, and the whole block
+was behind `*ngIf="!data.customComponent"`, which is never true for a host
+dialog (`SmartDialog.ngAfterViewInit` unconditionally instantiates
+`data.customComponent`).
+
+**The `okCallback` / `cancelCallback` model fields stay.** Hosts set and invoke
+them from their own `customComponent` dialogs, and that keeps working
+unchanged. Only the library-rendered buttons are gone. The `actionCallback` /
+`actionLabel` button — the one with a real handler (`onActionClick()`) — is
+untouched.
+
+Action needed: none, unless you relied on the library rendering those two
+buttons — in which case they never worked, and you should render them in your
+own dialog component.
+
+### Full standalone + `provideSmartNgClient()` (Phase 3.2) — **the big one**
+
+This is the change that rewrites your `app.module.ts`. Everything else in this
+guide is small next to it.
+
+#### Every NgModule is gone
+
+The library no longer ships a single `@NgModule`. All 58 are deleted —
+`SmartNgClientModule`, `SmartViewContextModule`, `SmartSessionModule`,
+`SmartGridModule`, `SmarttableModule`, `SmarttreeModule`, `SmartdialogModule`,
+`SmartIconModule`, `SmartNavbarModule`, `SmartFilterModule`,
+`SmartFilterEditorModule`, `SmartComponentLayoutModule`,
+`SmartExpandableSectionModule`, `SmartMapModule`, `SmartDiagramModule`,
+`SmartNavigationModule`, `SmartValidationModule`, `SmartGenericPagesModule`,
+`ComponentFactoryServiceModule`, `SharedModule`, `SmartTabGroupModule`,
+`SmartDocuStoreExplorerModule` and the generated OpenAPI `ApiModule`s.
+
+Every component, directive and pipe is now **standalone**. Import the ones your
+templates use directly, in the component that uses them:
+
+```ts
+@Component({
+  selector: 'app-my-page',
+  templateUrl: './my-page.component.html',
+  imports: [SmartGridComponent, UiActionToolbarComponent, SmartEmbeddedSlotDirective],
+})
+export class MyPageComponent extends SmartComponent<MyModel> { … }
+```
+
+**The compiler tells you what is missing** — one `NG8001: '<smart-grid>' is not
+a known element` per unresolved element, per template. Work through them; there
+is no guessing involved. In practice ~16 module imports become ~40 component
+imports spread across the components that actually use them.
+
+**The compiler does NOT tell you about the DI changes below.** Nothing fails at
+build time if you get those wrong; you find out on the first page load. Smoke
+your app.
+
+#### `provideSmartNgClient(config, ...features)` replaces the module imports
+
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideAnimations(),
+    provideRouter(ROUTES),
+    provideSmartNgClient(
+      {
+        gridMenuIcon: 'more_horiz',
+        treeMenuIcon: 'more_horiz',
+        aclEditingViewName: Pages.ACL_MATRIX_PAGE,
+        invalidSmartlinkPageName: Pages.INVALID_SMARTLINK_PAGE_NAME,
+        namedValidators: [MY_VALIDATOR_FACTORY],
+      },
+      withSmartMap({ engine: MapEngine.LEAFLET }),
+      withSmartDiagram({ customOptions: [MY_CHART] })
+    ),
+    { provide: HTTP_INTERCEPTORS, useClass: MyLoadingInterceptor, multi: true },
+  ],
+});
+```
+
+The core is always wired and cannot be forgotten: session, view context, the
+three BFF interceptors, layout, form, grid, table, tree, dialog, icon, navbar,
+filter, filter editor, validation, expandable section, navigation, shared and
+the generic pages. That is the point — the session and header interceptors used
+to be easy to leave out, and leaving them out fails *silently* (no
+`Authorization` header).
+
+Only two features are opt-in, because they pull heavy third-party code that not
+every host renders: `withSmartMap()` (leaflet / Google Maps) and
+`withSmartDiagram()` (chart.js). There is **no `withSmartTabGroup()`** —
+`smart-tab-group` had no component left, only an empty module, and is deleted.
+
+`provideSmartNgClient()` calls `provideHttpClient()` itself, with
+`withInterceptorsFromDi()` and its own three functional interceptors, and leaves the backend
+on the framework default (fetch). Your own class-based `HTTP_INTERCEPTORS` keep working and
+still run after the library's three. Pass extra `HttpClient` features in
+`config.httpFeatures` rather than making a second `provideHttpClient()` call — see
+[HTTP](#http-the-library-no-longer-forces-the-xhr-backend-phase-38), which is also where the
+6.x "do not call it twice" trap went.
+
+#### String-keyed providers become typed config fields
+
+Delete these from your providers array and pass them to `provideSmartNgClient`:
+
+| 6.x provider | 7.0 config field |
+|---|---|
+| `{ provide: 'gridMenuIcon', useValue: … }` | `gridMenuIcon` |
+| `{ provide: 'treeMenuIcon', useValue: … }` | `treeMenuIcon` |
+| `{ provide: 'searchPageName' / 'searchComponentName', … }` | `searchPageName` / `searchComponentName` |
+| `{ provide: 'genericPageName' / 'genericComponentName', … }` | `genericPageName` / `genericComponentName` |
+| `{ provide: 'subjectSelectorPageName' / 'subjectSelectorComponentName', … }` | `subjectSelectorPageName` / `subjectSelectorComponentName` |
+| `{ provide: 'validationResultPageName' / 'validationResultComponentName', … }` | `validationResultPageName` / `validationResultComponentName` |
+| `{ provide: 'noPermissionPageName' / 'noPermissionComponentName', … }` | `noPermissionPageName` / `noPermissionComponentName` |
+| `{ provide: 'invalidSmartlinkPageName' / 'invalidSmartlinkComponentName', … }` | `invalidSmartlinkPageName` / `invalidSmartlinkComponentName` |
+| `{ provide: 'aclEditingViewName', useValue: … }` | `aclEditingViewName` |
+| `{ provide: DIALOG_DISABLE_CLOSE, useValue: … }` | `dialogDisableClose` |
+| `{ provide: MAT_DATE_LOCALE, useValue: 'hu-HU' }` | `dateLocale` — **or keep the provider as it is**, which is what the codemod does; see [Dates §2](#2-leave-your-mat_date_locale-provider-alone) |
+| `SmartWidgetSettings.useUtc = true` (a static, not a provider) | **delete it** — the flag is gone with the moment adapter; see [Dates §4](#4-smartngclientconfiguseutcdates-is-removed) |
+| `{ provide: NAMED_VALIDATOR, useValue: F, multi: true }` | `namedValidators: [F]` |
+| `{ provide: SMART_DEFAULT_VIEW_COMPONENTS, useValue: E, multi: true }` | `defaultViewComponents: [E]` |
+| `SmartValidationModule.forRoot([...])` | `namedValidators` — **the element type changes**, see below |
+| `SmartDiagramModule.forRoot([...])` | `withSmartDiagram({ customOptions })` |
+| `{ provide: MAP_ENGINE, useValue: … }` | `withSmartMap({ engine })` |
+
+`'pageName'`, `'componentName'` and `'treeId'` stay as string tokens on purpose:
+they identify one component instance rather than configuring the library, and
+hosts also provide them at component level.
+
+You can also delete these from your **root** providers array — the core provides them:
+`SmartSessionService`, `SmartViewContextService`, `SmartNavigationService`,
+`SmartIconService`, `SmartFilterEditorService`, `SmartFormService`,
+`SmartCookieService`, `NamedValidatorService`, `ComponentFactoryService`, and the date
+adapter wiring (`MAT_DATE_FORMATS`, `DateAdapter`).
+
+⚠️ **`namedValidators` takes factories, not providers.** `SmartValidationModule.forRoot()`
+took `Provider[]`, so hosts wrote the wrapper by hand:
+
+```ts
+// 6.x — validator.factories.ts
+export const VALIDATOR_PROVIDER_EMPTY_INPUT: Provider = {
+  provide: NAMED_VALIDATOR, useValue: VALIDATOR_FACTORY_EMPTY_INPUT, multi: true,
+};
+// app.module.ts
+imports: [SmartValidationModule.forRoot([VALIDATOR_PROVIDER_EMPTY_INPUT])]
+```
+
+`provideSmartNgClient()` adds that wrapper itself, so the config takes the bare
+`ValidatorFactory[]`. Export the factories and pass those:
+
+```ts
+// 7.0
+export const VALIDATOR_FACTORY_EMPTY_INPUT: ValidatorFactory = { … };
+provideSmartNgClient({ namedValidators: [VALIDATOR_FACTORY_EMPTY_INPUT] })
+```
+
+The codemod moves the argument into the config and **reports it**, because the entries are
+normally named constants declared in another file and only you know what each one wraps. If
+you miss the note, `TS2322: Type 'Provider' is not assignable to type 'ValidatorFactory'`
+lands on every element.
+
+⚠️ **The same line on a `@Component` is not the same thing.**
+`providers: [SmartFilterEditorService]` on a page component asks for one instance *per page*,
+which is usually deliberate — p014 does it in five components. Leave those alone; the codemod
+does.
+
+#### The module → standalone mapping
+
+What each `Smart*Module` used to export, reduced to what 7.0 still exports publicly. An
+NgModule's `imports:` array accepts standalone components, so this substitution is all a host
+that is still NgModule-based needs to keep compiling — the codemod performs it.
+
+| 6.x module | 7.0 imports |
+|---|---|
+| `SmartNgClientModule` | the union of the fourteen it re-exported (everything below except the generic pages, the filter editor, the map and the diagram) — trim it to what your templates use |
+| `SmartComponentLayoutModule` | `SmartComponentLayoutComponent` |
+| `SmartViewContextModule` | `UiActionToolbarComponent`, `UiActionButtonComponent`, `UiActionDialogButtonComponent`, `SmartformComponent`, `SmartfileuploaderComponent`, `SmartFileEditorComponent`, `SmartMultiFileEditorComponent`, `SmartVoiceRecorderComponent`, `SmartEmbeddedSlotDirective`, `HighlightPipe` |
+| `SmartGridModule` | `SmartGridComponent` |
+| `SmarttreeModule` | `SmartTreeComponent` |
+| `SmartdialogModule` | `SmartDialog` |
+| `SmartIconModule` | `SmartIconComponent`, `UiBadgeComponent`, `UiBadgeDirective` |
+| `SmartNavbarModule` | `SmartNavbarComponent` |
+| `SmartFilterModule` | `SmartFilterComponent` |
+| `SmartFilterEditorModule` | `SmartFilterEditorContentComponent` |
+| `SmartExpandableSectionModule` | `ExpandableSectionComponent` |
+| `SmartSessionModule` | `SmartSessionTimerComponent` |
+| `SmartGenericPagesModule` | `SearchPageComponent`, `GenericPageComponent`, `SubjectSelectorComponent`, `InvalidSmartlinkComponent` |
+| `SmartMapModule` | `SmartMapComponent` + `withSmartMap({ engine })` |
+| `SmartDiagramModule` | `SmartDiagramComponent` + `withSmartDiagram({ customOptions })` |
+| `SharedModule` | `SmartTooltipDirective`, `SmartDatePipe`, `SmartDateTimePipe`, `SmartTimePipe` |
+| `SmartValidationModule` | nothing — `forRoot()`'s validators become `namedValidators` |
+| `SmarttableModule` | nothing — `SmarttableComponent` is no longer public; render a `<smart-grid>` |
+| `SmartNavigationModule`, `ComponentFactoryServiceModule` | nothing — they only carried services, which the core provides |
+| `SmartTabGroupModule` | nothing — deleted; it had no component left |
+| `SmartDocuStoreExplorerModule` (`@smartbit4all/document-explorer`) | `SmartDocuStoreExplorerComponent`, `FolderContentComponent`, `PdfViewerDialogPageComponent` |
+
+Two things this table will not tell you, and the compiler will not either: an import you no
+longer need is invisible (unused entries in an NgModule `imports:` array are not reported),
+and a name you already bind from elsewhere — a `SmartDatePipe` of your own — must not be
+imported twice. The codemod reports both cases rather than guessing.
+
+#### Your `SmartComponent` subclasses silently become OnPush
+
+This is an **Angular 22 fact rather than something 7.0.0 introduces**, but it
+lands on you at the same moment, so it is worth stating plainly: `SmartComponent`
+is an abstract `@Component`, and each of your subclasses carries its own
+`@Component` decorator. On Angular 22 a component without an explicit
+`changeDetection` gets the new `OnPush` default. p014 has 75 such subclasses,
+p043 has 70.
+
+Let the `ng update` schematic add `changeDetection: ChangeDetectionStrategy.Eager`
+to all of them (that is what the library did), verify your app, and move to
+OnPush deliberately afterwards. A subclass that mutates its own state outside a
+signal and without `markForCheck()` will stop repainting under OnPush.
+
+#### Removed from the public API
+
+A major is the only chance to narrow the surface, so these are no longer
+exported. All of them are library internals; none is used by p014, p043,
+app-formmate or `@smartbit4all/document-explorer`:
+
+- `SmarttableComponent`, `SmarttableService` — use `<smart-grid>`, which renders
+  the table internally. **All `SmartTable*` model types stay** (`SmartTableType`,
+  `SmartTableInterfaceTypeEnum`, `SmartTableHeader`, …). p043 imports
+  `SmarttableComponent` in `ad-groups.component.ts` but never uses it — delete
+  that one import line.
+- `GoogleMap`, `LeafletMap`, `AbstractMap` — select an engine with
+  `withSmartMap({ engine })`.
+- `SmartFilterParamComponent`, `SmartFilterParamsComponent`,
+  `SmartFilterExpressionItemComponent`, `SmartFilterExpressionItemsComponent` —
+  internals of `SmartFilterEditorContentComponent`, which stays public.
+- `HoverMenuComponent`, `ClickMenuComponent` — rendered by the ui-action toolbar.
+- `UiActionConfirmDialogComponent`, `UiActionInputDialogComponent` — opened by
+  their services, which stay public.
+- `UploadWidgetComponent`, `PhotoCaptureWidgetComponent`,
+  `VoiceRecordWidgetComponent` — contents of the ui-action upload dialog.
+- `SmartNgClientService` — deleted; it was an empty stub with no members.
+- The generated `ApiModule`s — they had no usages and their `forRoot()` told you
+  to import `HttpClientModule`, which no longer applies.
+
+Two internal string tokens are gone as well, replaced by real `InjectionToken`s
+(`'confirmDialogService'`, `'textFieldDialogService'`, `'fileUploadDialogService'`).
+No host provided them, so no action is needed.
+
+#### Behaviour notes
+
+- `<mat-slide-toggle>` in the form widget no longer carries a `value` binding,
+  `<mat-nested-tree-node>` no longer carries an interpolated `matTreeNodeToggle`,
+  and the ui-action menus no longer carry `[subActions]`. All four were dead
+  bindings that the NgModules' `CUSTOM_ELEMENTS_SCHEMA` had been hiding — they
+  wrote a DOM property nobody read. Rendering is unchanged.
+- The dead `ExpandableGridComponent` is deleted (it was declared in
+  `SmartGridModule` but its selector was used nowhere).
+
+### Widget ↔ SmartComponent: the model routing is inverted (Phase 3.4)
+
+A widget no longer waits to be collected by the screen component it lives in: it finds its
+`SmartComponentApiClient` through DI and registers itself. `SmartComponent` carries the
+channel as an inherited host directive, so **no host component has to be changed for the
+routing itself** — everything below is the *legacy surface* that went with the old
+collection path. The protocol is written up in `WIDGETS.md` next to this file; the decision
+record behind it is ADR-0005 in the `platform-angular2` working copy.
+
+#### What a host must delete (all of it mechanical, all reported by the compiler)
+
+| Delete | Why |
+|---|---|
+| `this.useQueryLists = true;` | The property is gone. Its setter rejected anything but `true`, so every branch behind it was unreachable — this was a no-op that logged a warning. |
+| `[parentSmartComponent]="this"` on `<smart-component-layout>` | The input is gone; the layout injects the client. `strictTemplates` reports leftovers as **NG8002**. |
+| `this.addForm(id, smartForm, formComponent)` | Gone. A `<smartform>` that displays the client's model registers itself. Two call styles existed; where the return value was used, it was the `smartForm` argument — use that. |
+| `this.widgets.delete(…)` / `this.widgets.set(…)` / `this.formWidgets…` | The maps are gone (they were only written by the legacy path and read by nothing). |
+| the 4th argument of `addGrid(smartGrid, options, useAsDefaultGrid, componentReference)` | `addGrid()` keeps the options and the default-grid role; the services it used to copy into the grid model (`uiActionService`, `uiActionDescriptorService`, `serviceToUse`, `viewContextService`) are the grid's own DI job now. |
+| `override getSmartXxxQL()` (e.g. the two `throw new Error` overrides in a `FilterPageService`) | The eight abstract getters are gone from `SmartComponentApiClient`. |
+| `this.getSmartGridsQL()` and friends | If a component really wants its own widgets, it declares the view query itself: `@ViewChildren(SmartGridComponent) grids!: QueryList<SmartGridComponent>` — same reach as the removed getter had. |
+| `handleDataChangeSubscriptions()` | Gone. A form publishes its own value-change keys when it constructs. |
+
+Removed from the public API in the same step, in case a host imported them directly:
+`SmartComponentLayoutUtility` and its `EmbeddedSlotInfo` interface (the whole file — its
+collectors walked the layout tree for widgets, which nothing does now), and the `[parent]`
+inputs of `<smart-map>` / `<smart-diagram>` (they were bound to `parentSmartComponent` and read
+by nothing; both widgets resolve the client themselves). `initActions()` also runs less often:
+only when the model or its action list changes, no longer after every layout render, grid view
+init and filter model change — a host override that relied on one of those extra calls has to
+key off `dataChanged` instead.
+
+The [codemod](#migrating-a-host-the-codemod) deletes the first two rows and the last one, and
+lists the rest — `addForm()`, the 4th `addGrid()` argument, the getter overrides — with their
+line numbers, because each of those is a small decision rather than a substitution.
+
+#### What stays
+
+- `SmartService` — a view-less client. Its `@ViewChildren` never populated anyway; they are
+  simply gone now.
+- `initActions()` — still the hook a host overrides to build its own action list. The base
+  implementation only asks for a render; toolbars pull their actions themselves.
+- `setUpDefaultTree()` / `createTreeService()`, `addGrid()`, `submitForms()`,
+  `getInvalidFields()`, `uiActionModels` (now a getter over the model's actions).
+
+#### `uiActionModels` is read-only now — assigning to it no longer compiles
+
+It became a getter over the `actionModels` computed, so a host that *replaced* the list in
+place gets `TS2540: Cannot assign to 'uiActionModels' because it is a read-only property`.
+Measured in **p014 and p043**, `document-storage-editor.component.ts`:
+
+```ts
+// before — no longer compiles
+this.uiActionModels = this.uiActionModels.filter((a) => a.uiAction.code !== 'CANCEL');
+
+// after — filter into a field of your own and bind it
+protected readonly visibleActions = signal<UiActionModel[]>([]);
+// …
+this.visibleActions.set(this.uiActionModels.filter((a) => a.uiAction.code !== 'CANCEL'));
+```
+
+```html
+<smart-ui-action-toolbar [uiActionModels]="visibleActions()"></smart-ui-action-toolbar>
+```
+
+A plain field works just as well; what matters is that the **array reference changes**, which
+is what tells the toolbar to re-render. See also the entry-freeze note in the Phase 3.7
+section.
+
+#### Behavioural deltas, accepted
+
+- **Wider reach.** A widget in a host's *own* sub-component now participates, where a view
+  query could not see it (measured on p014/p043: 5 toolbars and 3–4 forms per host). A form
+  takes part only if it displays the client's component model, which is what the forms the
+  queries used to find have in common; a form that renders something else of its own (a
+  search box, a field editor) does not.
+- Two widgets sharing one identifier both reload; the old map kept only the last.
+- `getInvalidFields()` collects in subscription order rather than view order — visible only
+  in the order of the names in the validation dialog.
+- A toolbar entry is tracked by a synthesized key (action code + ordinal among entries with
+  the same code), so a button's DOM node — with its focus and ripple — follows its action
+  across reordering. Rendering is otherwise identical.
+
+#### `[smartComponentDetached]`
+
+The one brake on the automatic registration. 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/validation.
+
+```html
+<div smartComponentDetached>
+  <smart-grid [smartGrid]="ownGrid" [uuid]="ownUuid"></smart-grid>
+</div>
+```
+
+#### `SmartSubject` is deleted
+
+It was a no-op wrapper over `Subject`: `subscription.add(this.unsubscribe$.subscribe())`
+registers the teardown in the wrong direction, so after `destroy$.next()`, `.complete()` or
+`.unsubscribe()` subscribers still received values. Replace `new SmartSubject(destroy$)`
+with `new Subject()`; where a subscription really must die with a component, use
+`takeUntil(this._destroy$)` (which is what actually stopped delivery all along) or
+`takeUntilDestroyed()`. No host used it.
+
+### Toolbars resolve their own actions and own the execution context (Phase 3.5)
+
+One rule decides which actions a toolbar shows, and the toolbar — not each list entry —
+says who performs them. `WIDGETS.md`, *Toolbars*, is the short version; the decision record
+behind it is ADR-0006 in the `platform-angular2` working copy.
+
+> 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 toolbar with neither an id nor a binding shows nothing.
+
+`[uiActionModels]="uiActionModels"` therefore keeps meaning "put my page's unaddressed
+actions here" and needs no change.
+
+#### `UseUiAction` is deleted; `UseUiAction2` is now `UiActionExecutor`
+
+There is one executor interface. If a host class implements `UseUiAction` — a `submit` /
+`reSubscribeToChange` subject handshake — replace the two subjects with the two methods:
+
+```ts
+// before
+export class DelegateInboxDialogService implements UseUiAction {
+  submit: Subject<void> = new Subject();
+  reSubscribeToChange: Subject<void> = new Subject();
+  …
+}
+
+// after
+export class DelegateInboxDialogService implements UiActionExecutor {
+  submitForm(validate: boolean): void {
+    this.submit.next();   // keep the subject if a component subscribes to it
+  }
+  getInvalidFields(): SmartFormInvalidFields {
+    return { invalidFieldKeys: [], invalidFieldNames: [] };
+  }
+  …
+}
+```
+
+`Subject.next()` is synchronous, so a component that subscribed to `submit` has already run
+by the time `submitForm()` returns — which is exactly what the old handshake tried to
+express. Keep `reSubscribeToChange` only if something subscribes to it; the library no longer
+fires it.
+
+This also **fixes a silent hang**: the old branch `await`ed `submit.toPromise()`, which only
+settles when somebody `complete()`s the subject. Three of the five implementors never did, so
+a `submit`/`model` action on those services waited forever.
+
+#### `UiActionService.execute()` lost its first argument
+
+It was always `uiActionModel.uiAction`:
+
+```ts
+- this.uiActionService.execute(uiActionModel.uiAction, uiActionModel);
++ this.uiActionService.execute(uiActionModel);
+```
+
+#### The execution context moved from the entry to the toolbar
+
+| what | bind on the toolbar | entry field (still honoured) |
+|---|---|---|
+| who performs the action | `[executor]` | `serviceToUse` — **deprecated** |
+| which widget it runs against | `[widgetId]` | `widgetId` — **deprecated**, wins if set |
+| which row inside it | `[nodeId]` | `nodeId` — **deprecated**, wins if set |
+| extra params for every action | `[actionParams]` | (clone the `UiAction` — no longer necessary) |
+
+`[executor]` defaults to the screen component the toolbar sits under, which is what almost
+every entry named. Bind it only when the actions belong to another API — a tree service, a
+filter editor, a dialog service of your own:
+
+```html
+<smart-ui-action-toolbar [uiActionModels]="actions" [executor]="myService"></smart-ui-action-toolbar>
+```
+
+`[actionParams]` replaces cloning a `UiAction` per row just to inject a model:
+
+```html
+<smart-ui-action-toolbar
+  [uiActionModels]="rowActions"
+  [widgetId]="gridId"
+  [nodeId]="row.id"
+  [actionParams]="{ model: row }"
+></smart-ui-action-toolbar>
+```
+
+#### Removed from the public API
+
+| Removed | Replacement |
+|---|---|
+| `UseUiAction` | `UiActionExecutor` (see above) |
+| the third `SmartTable` constructor parameter and `getServiceToUse()` | nothing — the executor no longer travels through the table (0 host call sites) |
+| `SmartformComponent.getToolbars()` | nothing collects toolbars any more; each one resolves its own actions |
+| `ISmartFilterEditorService.get/setComplexToolbars()` and the `submit` / `reSubscribeToChange` members | as above |
+| `FileEditorToolbarComponent` | a plain `<smart-ui-action-toolbar>` with `[actionParams]` |
+| `SmartGridComponent.setupToolbar()` / `.toolbar` / `.headerToolbar` | the id is a binding; there is nothing to reach into |
+
+#### Behavioural deltas, accepted
+
+- A widget renders a toolbar exactly when its model carries a `toolbarId`, with no type list.
+  A `toolbarId` on a type whose template has no place for a toolbar (`RECORDING_UPLOADER`)
+  now logs a warning instead of being silently dropped.
+- Only the actions a toolbar actually shows are scheduled. Since 3.4 a toolbar armed every
+  scheduled action of the view, so one action could fire from several toolbars at once.
+- A grid row's actions are no longer cloned per row; the row model travels as
+  `[actionParams]`. The multi-file editor's per-file toolbars appear when their own list
+  resolves rather than when a hidden sibling's did, and the tree's `doAction` clones instead
+  of mutating the caller's `UiAction`.
+
+### The form widget's rendering decisions (Phase 3.6)
+
+Nothing here needs a code change in a host — there is no API to adapt to. What
+changes is what the widget puts on the page, so read this before you compare
+screenshots.
+
+#### Every widget carried a spare empty wrapper; it is gone
+
+The `COMPONENT` branch's wrapper had no type guard, so
+`<div class="widgetContainer"><div class="widgetContent"><ng-template
+#customComponent>` rendered after **every** widget of every type. Measured on the
+playground: 14 widgets, 28 `.widgetContainer` — one spare, empty, per widget.
+
+The library's own CSS puts no box properties on `.widgetContainer`, so most pages
+will look identical. **Yours may not**, if you style that class with anything that
+occupies space. Both in-house hosts do, on one page:
+
+```css
+/* p014 + p043, dossier-publication.component.css */
+:host ::ng-deep .widgetContainer { margin-bottom: 0.5rem !important; }
+```
+
+There, every widget loses half a rem of trailing space. Grep your stylesheets for
+`.widgetContainer` and check the pages the matching selectors reach. Rules that
+need content still match what they always matched — an empty wrapper never
+satisfied `.label.widgetContainer` or `.widgetContainer:has(…)`.
+
+#### `MATRIX` and `YOUTUBE_PLAYER` now obey `isVisible` and get their `cssClass`
+
+Those two branches sat outside the `@if (isVisible)` guard and outside the
+`<div [ngClass]="cssClass" class="container">` every other type lives in, so
+`isVisible: false` did not hide them and `cssClass` never reached them. Both are
+inside now. If a backend view relies on a matrix rendering while marked invisible,
+it will stop rendering.
+
+#### A container keeps its invisible children
+
+A `CONTAINER` widget's `ngOnInit` used to overwrite `widgetInstance.valueList`
+with the visible subset, destroying the invisible children in the model the
+backend sent. The visible subset is derived per check now, so the model stays
+whole and a later `applyConstraints()` that flips a child's `isVisible` brings it
+back — which it could not before. The DOM is unchanged: the same children render.
+
+Side effect worth knowing: the model walks that recurse into a container's
+`valueList` (`applyComponentConstraints`, `copyValueFromFormToWidgetBeans`,
+`translateWidgets`) now see the invisible children too. Their form controls always
+existed — `createFormControls` runs over the whole model before any widget renders
+— so this only makes the widget beans agree with the controls.
+
+#### A YouTube shorts link resolves
+
+`parseYoutubeUrl` threw away its own `replace('/shorts/', '/watch?v=')`, so a
+shorts link produced no player. It plays now.
+
+#### Removed from the public API
+
+| Removed | Replacement |
+|---|---|
+| `SmartformwidgetComponent` | nothing — no host imported the class; `<smartform>` still renders it. 7.1 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
+field altogether**, together with the moment adapter it fed. If you set
+`SmartWidgetSettings.useUtc = true` before bootstrap, delete that line and read
+[Dates §4](#4-smartngclientconfiguseutcdates-is-removed) — the timezone contract is fixed now,
+and the flag defaulted to `false` everywhere anyway.
+
+#### What deliberately did not change
+
+A required field is marked in both label positions, by two different mechanisms:
+a shown label (`showLabel: true`) is the widget's own `<h4>` and carries a literal
+` *`; a `mat-label` sits inside a `mat-form-field`, which renders
+`.mat-mdc-form-field-required-marker` from the control's own validators. That is
+why `getWidgetLabel` ties its asterisk to `showLabel` — dropping the condition
+would mark the floating label twice.
+
+### Change detection: frozen action entries, no zone.js (Phase 3.7)
+
+7.0 runs without zone.js. Every component of the library is `OnPush` — nothing is checked
+just because something, somewhere, ticked — and the library says when its own state changed.
+Two consequences reach a host.
+
+#### A `UiActionModel` is frozen: build an entry, never edit one
+
+Every field is `readonly`, and `[uiActionModels]` takes `readonly UiActionModel[]`.
+
+```ts
+// before — compiles on 6.x, and on 7.0 changes nothing on screen
+entry.cssClass = 'active-nav-action';
+
+// after
+this.actions = this.actions.map((a) =>
+  a.uiAction.code === code ? { ...a, cssClass: 'active-nav-action' } : a
+);
+```
+
+Measured across the 12 hosts in scope (2026-07-28): **72 sites in 7 hosts**, all of them
+`cssClass` — p009-angular alone has 38, p014 and p043 12 each. The codemod prints every one
+of them with its line number; it cannot rewrite them, because only you know which array the
+entry belongs to.
+
+The compile error and the fix are the same thing. Writing into an entry that a toolbar is
+already rendering never reached the screen under zone.js either — it worked only because
+some other event happened to tick the application. Rebuilding the array is what actually
+re-renders.
+
+**The gap this does not close.** `this.actions[0] = { ...this.actions[0], cssClass: 'x' }`
+compiles: `actions` is your field, and the freeze only covers the entries. It keeps the same
+array reference, so the toolbar does not re-render. Reassign the array — or, if you hold it
+in a `signal`, `update()` it.
+
+The descriptor a toolbar resolves is no longer written back into the entry either. Nothing
+outside the toolbar read it; if you did, resolve it yourself through
+`UiActionDescriptorService.getActionDescriptor(uiAction)` — which is
+[synchronous in 7.0](#getactiondescriptor-is-synchronous-phase-39).
+
+#### Client-side translation is gone
+
+`SmartTranslateService`, `viewContext.translateService` and the `translateServiceChanged`
+subject are removed, together with `originalLabel` / `originalPlaceholder` on the widget
+interfaces. No measured host assigned any of them — the three references in p014/p043 were
+unused imports — and the backend localizes server-side.
+
+What the frontend authors itself is now configuration:
+
+```ts
+provideSmartNgClient({
+  errorDialog: { title: 'Hiba', message: 'Váratlan hiba történt.', buttonLabel: 'Rendben' },
+});
+```
+
+`SmartViewContextService.getSmartViewContextApiErrorByCode()` is no longer `async`.
+
+#### If your host still bootstraps with zone.js
+
+Nothing forces you to drop it — the library works either way, because it no longer depends
+on an application-wide tick. The playground runs `provideZonelessChangeDetection()` with no
+`zone.js` polyfill, and that is the configuration 7.0 is tested in.
+
+If you do go zoneless, the same rule applies to your own components: state written from a
+subscription, a promise or a timer needs a signal or a `markForCheck()`; state written from a
+template event or an input does not.
+
+### Dates: moment → date-fns, and the timezone contract (Phase 3.8)
+
+**This section needs action at install time.** The reasoning is ADR-0008 in the
+`platform-angular2` working copy; the contract itself is stated in §4 below.
+
+#### 1. Swap the peer dependency
+
+`@angular/material-moment-adapter` is out of the library's `peerDependencies`;
+`@angular/material-date-fns-adapter` and `date-fns` are in. `date-fns` is listed explicitly
+rather than left transitive, because the library imports `date-fns/locale` itself.
+
+```bash
+npm uninstall @angular/material-moment-adapter moment
+npm install @angular/material-date-fns-adapter@^22.0.0 date-fns@^4
+```
+
+If your own code imports moment for something unrelated, keep it — nothing here forces its
+removal, only the adapter's.
+
+#### 2. Leave your `MAT_DATE_LOCALE` provider alone
+
+If you have this line — p014 and p043 both do — **keep it as it is**:
+
+```ts
+{ provide: MAT_DATE_LOCALE, useValue: 'hu-HU' },
+```
+
+The strict reading of the date-fns adapter would require a `Locale` **object** here, and a bare
+string would throw inside date-fns the first time a user opened a date field. The library's
+`SmartDateFnsAdapter` accepts both: it resolves `'hu'` / `'hu-HU'` / `'en'` / `'en-US'`
+(case-insensitively) to a date-fns locale, passes a real `Locale` object through untouched, and
+falls back to Hungarian with a `console.warn` for anything else.
+
+So: **hosts on Hungarian or English need no change.** For any other language, provide a real
+date-fns locale:
+
+```ts
+import { de } from 'date-fns/locale';
+…
+{ provide: MAT_DATE_LOCALE, useValue: de },
+```
+
+`SmartNgClientConfig.dateLocale` is unchanged — still a `string`, still defaulting to `'hu-HU'`.
+
+#### 3. If you override `MAT_DATE_FORMATS`, your format strings will throw — and you probably want to delete the override
+
+Measured across 12 hosts on 2026-07-28: three of them (**p014**, **p043**, **p009-angular**)
+provide their own formats next to the locale, and two more (`app-vlab`, `app-tournament`) have the
+same line commented out:
+
+```ts
+{ provide: MAT_DATE_FORMATS, useValue: MY_FORMATS },
+```
+
+with
+
+```ts
+export const MY_FORMATS = {
+  parse:   { dateInput: 'YYYY.MM.DD' },
+  display: { dateInput: 'YYYY.MM.DD', monthYearLabel: 'YYYY',
+             dateA11yLabel: 'LL', monthYearA11yLabel: 'YYYY' },
+};
+```
+
+Those are **moment tokens**. date-fns treats `YYYY`, `DD`, `YY` and `D` as *protected* and throws a
+`RangeError` on them, and its `LL` means something else entirely (stand-alone month, not a
+localized long date). So this override **crashes at runtime, on the first screen with a date
+field** — the same failure shape as the string locale above, and just as invisible to the compiler.
+
+**The fix is almost certainly deletion.** That `MY_FORMATS` exists to render `YYYY.MM.DD`, which is
+exactly what the library's own `SMART_DATE_FORMATS` now produces (`2026.07.28.`). Drop the
+provider and the constant and you get the format you wanted, plus the more forgiving parsing.
+
+If you genuinely need a different format, translate the tokens rather than copying them:
+
+| moment | date-fns |
+|---|---|
+| `YYYY` | `yyyy` |
+| `DD` | `dd` |
+| `LL` | `PP` (or spell it out: `yyyy. MMMM d.`) |
+| `MMM YYYY` | `yyyy. LLL` |
+
+Note that the library's `parse.dateInput` is an **array** — `DateFnsAdapter._parse` tries each entry
+in turn (and ISO-8601 first), so you can list several accepted spellings instead of one.
+
+#### 4. `SmartNgClientConfig.useUtcDates` is removed
+
+Delete it if you set it. No known host does. It existed for a client-configurable timezone that
+was abandoned as a requirement; the contract is now fixed and explicit:
+
+> **The browser's zone on screen. Zulu (`…Z`) on the wire. The server converts.**
+
+This is unchanged behaviour in practice — `useUtcDates` defaulted to `false`, and the moment
+adapter with `useUtc: false` behaves exactly like a plain `Date`.
+
+#### 5. What a date widget's value now *is*
+
+Form control values from the date pickers are plain **`Date`** objects, where they were
+`Moment` objects. The values reach your backend through a `UiActionRequest` param, so the wire
+format is `JSON.stringify` of that value — and `Date.toJSON()` emits the same ISO-8601 UTC string
+`Moment.toJSON()` did. **Nothing changes on the wire.** Only host code that read a value out of a
+form control and called a moment method on it (`.format()`, `.add()`, `.startOf()`) needs
+rewriting; the platform APIs never exposed a `Moment` in a signature.
+
+#### 6. The one visible difference
+
+Date inputs render **`2026.07.28.`** where 6.x rendered `2026.7.28.` — the documented `YYYY.MM.DD`
+convention. The old rendering was not a decision: `MAT_MOMENT_DATE_FORMATS` used moment's `'l'`,
+which strips the zero padding off the Hungarian `L`. Typed input is **more** forgiving than 6.x,
+not less: `2026.07.28.`, `2026.07.28`, `2026.7.28.`, `2026.7.28` and ISO-8601 are all accepted.
+
+The month picker is unchanged (`07/2026`), and grid/table date columns were never affected —
+`SmartDatePipe` and friends extend Angular's own `DatePipe` and never used moment.
+
+### HTTP: the library no longer forces the XHR backend (Phase 3.8)
+
+`provideSmartNgClient()` used to pass `withXhr()` to its internal `provideHttpClient()` call,
+overriding the Angular 22 default on your behalf. It no longer does — the application runs on the
+framework default **fetch** backend.
+
+For almost every host this is invisible. The one behavioural difference that matters: **the fetch
+backend does not support upload progress.** A request with `reportProgress: true` and a body
+throws `NG2824` instead of emitting `HttpUploadProgress` events.
+
+Measured 2026-07-28 across 12 hosts: **`reportProgress: true` and `observe: 'events'` appear
+nowhere** outside the generated API services' unused parameters. So this is a theoretical risk for
+the current host set, not a live one. If *your* code does ask for upload progress, pass the
+feature back in:
+
+```ts
+import { withXhr } from '@angular/common/http';
+
+provideSmartNgClient({ httpFeatures: [withXhr()] })
+```
+
+The upside is that the "**do not call `provideHttpClient()` twice**" trap this guide warned about
+is gone rather than merely documented: a second call now re-provides the same backend the library
+already uses. The library's interceptors were never at risk from it — they are `multi` providers.
+
+### `getActionDescriptor()` is synchronous (Phase 3.9)
+
+`UiActionDescriptorService.getActionDescriptor(uiAction)` returns a `UiActionDescriptor`.
+It used to return a `Promise<UiActionDescriptor>`, and it was `async` for exactly one
+reason: the client-side translation layer that [Phase 3.7](#client-side-translation-is-gone)
+retired. Nothing it reads has been asynchronous since, so every caller was awaiting a value
+that was already there.
+
+**If you only `await` the call, you are already fine.** `await` on a non-promise is legal
+TypeScript, so this compiles and behaves identically before and after. The codemod drops the
+`await` anyway, so the code stops claiming an asynchrony that is not there:
+
+```ts
+const descriptor = await this.uiActionDescriptor.getActionDescriptor(uiAction);   // 6.x
+const descriptor = this.uiActionDescriptor.getActionDescriptor(uiAction);         // 7.0
+```
+
+Two shapes genuinely break. Measured 2026-07-28 across the 12 hosts in scope: **5 hosts,
+7 sites** — and none of them in a host's own `getActionDescriptor**s**()` map helper, which
+is an unrelated API and is left alone.
+
+**1. A subclass that overrides it** — `TS2416`, because `Promise<UiActionDescriptor>` is not
+assignable to `UiActionDescriptor`. Found in three hosts, as a byte-identical
+`MdmUiActionDescriptorService`. **The codemod rewrites this one.**
+
+```ts
+// 6.x
+override async getActionDescriptor(uiAction: UiAction): Promise<UiActionDescriptor> {
+  let d: UiActionDescriptor = await super.getActionDescriptor(basicUiAction);
+  …
+}
+
+// 7.0
+override getActionDescriptor(uiAction: UiAction): UiActionDescriptor {
+  let d: UiActionDescriptor = super.getActionDescriptor(basicUiAction);
+  …
+}
+```
+
+This is also the service you hand to a toolbar through `[uiActionDescriptorService]`, so a
+host with a custom one hits this at compile time rather than on screen.
+
+**2. `.then(…)` on the result** — `TS2339`, because a descriptor has no `.then`. Found in
+two hosts, four sites. **The codemod reports this one and does not rewrite it**: turning a
+callback into straight-line code means moving its body, which is a judgment call. The fix is
+mechanical anyway — assign, then inline:
+
+```ts
+// 6.x
+constructForm() {
+  this.actionDescriptorService.getActionDescriptor(this.uiAction).then((d) => {
+    this.buttonTitle = d.title;
+    this.buttonColor = d.color;
+  });
+  …
+}
+
+// 7.0
+constructForm() {
+  const d = this.actionDescriptorService.getActionDescriptor(this.uiAction);
+  this.buttonTitle = d.title;
+  this.buttonColor = d.color;
+  …
+}
+```
+
+If the callback was the reason a field lived in a `signal` — because the value arrived after
+the first render — it no longer needs to. The library made that same simplification in its
+own three action dialogs and its snack bar.
+
+**What went synchronous with it, inside the library:** the toolbar's descriptor resolution,
+`SmartGridComponent`'s header construction, and `SmartTreeGenericService.cacheActionDesciptors()`
+and **`syncTree()`**. `syncTree()` now returns `void`, which is what
+`SmartTreeServiceInterface` always declared; a host that calls it and discards the result —
+the only shape measured — needs no change, and a host that `await`s it still compiles.
+
+#### The same cleanup, elsewhere: `SmartdialogService.closeDialog()` returns `void`
+
+A sweep for the same shape found eight more library functions declared `async` with nothing
+asynchronous in them. Only one of them is on a surface a host touches:
+**`SmartdialogService.closeDialog(stopPropagate?)` returns `void`** instead of
+`Promise<void>`.
+
+**Nothing to do.** Both measured hosts that extend `SmartdialogService` override this method
+as `override async closeDialog(): Promise<void>`, and that **still compiles**: TypeScript
+accepts any return type where the base declares `void`. `await this.closeDialog()` keeps
+compiling too. This is the difference from `getActionDescriptor` above — that one returns a
+*value*, which is why the same override shape fails there with `TS2416` and not here.
+
+You may of course drop the `async` from your own override; nothing requires it.
+
+### Upload actions now wait for the server, and report their failures (Phase 3.9)
+
+**This one changes behaviour, on purpose.** `SmartViewContextService.performUploadAction()`
+and `performUploadMultipleAction()` used to start the upload and resolve immediately,
+without waiting for it and without passing on its failure. Every other action in the family
+(`performAction`, `performWidgetAction`, `performWidgetMainAction`, `dataChanged`) always
+waited; the two upload ones were an omission.
+
+Two things follow, and both are visible in a running app:
+
+1. **An upload action now blocks until the server has answered.** Before, the action was
+   "done" the moment the request went out — so `UiActionService` showed its success snackbar
+   over an upload that was still in flight, and anything the action was sequenced before ran
+   against a view the server had not updated yet. Now the snackbar appears when the upload
+   really has succeeded. On a large file that is a longer wait than 6.x showed you.
+
+2. **A failed upload now reaches your error handling.** The rejection used to be dropped —
+   it became an unhandled promise rejection, `UiActionService`'s `catch` never ran, and the
+   user was told the upload had worked. It now propagates, which means
+   `setActionErrorHandler()` (or the default error dialog) will fire on upload failures it
+   never fired on before. **If your host reports "new" upload errors after upgrading, they
+   are not new** — they were happening silently.
+
+Multi-file uploads also go out **one batch at a time** now. The batches were already being
+computed from the descriptor's `maxSize` and `maxBatchSize`, but they were then all sent at
+once, which put the whole set on the server simultaneously and defeated the split. If your
+backend measured upload concurrency, this is why it drops.
+
+Nothing to change in host code.
+
+### New in 7.0: a grid row can render a backend layout (#29717)
+
+A card-mode grid row that carries `layoutDescriptor.componentLayouts['GRID_ROW_LAYOUT']`
+renders that layout instead of the card component the host registered under
+`'<GRID_ID>Card'`. Both branches stay: a row without the descriptor behaves exactly as
+before, and this needs no host change.
+
+Two consequences worth knowing if you style or extend it:
+
+- The rendered layout's root element gets the `gridCardLayout` class, applied by the card to
+  its own child rather than pushed into the `style.classesToAdd` of the object the backend
+  sent. Nothing mutates the server model.
+- **The row's actions reach the layout's toolbars by a pull, not a walk.** The card provides
+  a `SmartActionHost` for its row subtree and writes the row's action list into it; a toolbar
+  inside the layout resolves that host before falling back to the page client. If you build
+  a component that owns such a subtree, do the same — `WIDGETS.md`, *Toolbars*.
+
+This shipped in 7.0.0 rather than as a 6.0.3x patch because it is built on the inverted
+widget contract that 7.0 introduces.
+
+### Writing your own widget
+
+`WIDGETS.md`, next to this file, is the protocol: how a widget finds its screen component
+through DI and registers itself, when to opt out with `[smartComponentDetached]`, what has to
+be a signal now that there is no zone, how a toolbar resolves its actions, and the three
+traps that have actually bitten (imperatively-fed inputs cannot be signal inputs; `@for`
+tracking over backend objects; clear-then-apply styling).
+
+In 6.x this was not possible at all — `SmartComponentApiClient` collected its children with
+eight `@ViewChildren` over eight concrete widget classes.
+
+### Imperatively created components are given their inputs properly
+
+`ComponentFactoryService` creates the components the library instantiates by hand — grid
+cards, expanded rows, table cell components, the expandable section's content, the form's
+`COMPONENT` widget, the filter editor's field editors — and most of those classes come from a
+host. It used to write their inputs by assigning the field. Two things follow, and both are
+fixed:
+
+- **A declared input is now written with `ref.setInput()`**, i.e. the same way a template
+  binding writes it. So a **signal input** works (assignment used to overwrite the input
+  function with the value, and the component's next `this.x()` threw `x is not a function`),
+  an **aliased** input is addressable under either name, and **`ngOnChanges` runs**.
+- **Falsy values arrive.** The old guard was `if (value)`, so `false`, `0` and `''` never
+  reached the component. Only `undefined` is skipped now, which keeps meaning "not passed".
+
+If your component takes something from the library this way and the key is **not** a declared
+input, the field is still assigned — nothing breaks — but you get one `console.warn` per
+component type and key. Declaring it with `@Input()` (or as a signal input) is the fix.
+
+**Check your falsy defaults.** If a host component relied on the old guard — expecting to
+keep its own default when the library passed `false` or `''` — it now receives the value.
+This is the only part of 7.0 where a bugfix can change what you see on screen without any
+code of yours changing.
+
+### Bugfixes shipped with 7.0
+
+- `SmartformwidgetComponent.ngAfterViewInit` no longer crashes with
+  `Cannot read properties of undefined (reading 'valueChanges')` when the form
+  contains a `MONTH_PICKER` widget (it wrongly subscribed to the non-existent
+  `<key>-time` control; only `DATE_TIME_PICKER` has one).
+- A widget nested in a CONTAINER receives `blurSophisticatedValueChange`; the recursion never
+  passed it down, so a BLUR-mode child would have thrown on blur.
+- `SmartformComponent` reaches widgets nested in a CONTAINER when it changes them in place
+  (values, constraints, the touched state after a failed submit). The view query it used
+  could not see them.
+- `UiActionDescriptorService` no longer shares one dialog object between actions. Any action
+  whose descriptor had no `dialog` of its own was given the service's single placeholder — the
+  same object every time — and had its title and button caption written into it, so resolving
+  one action renamed the dialog every other one was holding. The service is
+  `providedIn: 'root'`, so this outlasted the view.
+
+  What you saw on screen, measured on both versions:
+
+  | The action | 6.x, when the dialog opened | 7.0 |
+  |---|---|---|
+  | described by the backend, no dialog of its own | **another action's code** | its own code |
+  | described by nothing at all | **another action's code**, or empty | empty |
+  | registered client-side, no dialog of its own | its own code | unchanged |
+
+  The middle column is not a typo. An action the backend describes is resolved twice in the
+  normal flow — once when the toolbar renders it, again when the dialog it opens resolves it
+  for itself — and the first resolution wrote a dialog onto the action's own descriptor, so the
+  second one skipped the step that fills in the title. What the dialog then showed was whatever
+  code had last passed through the shared object. An **already open** dialog could change too,
+  since its title is re-read on every change-detection pass.
+
+  An action nothing describes still gets an untitled placeholder dialog: its *button* carries
+  the code, the dialog does not. That is unchanged and deliberate — such an action is a gap in
+  the host's descriptor map, and this is the honest rendering of it.
+
+  A resolved descriptor is now the caller's own object throughout, which also means
+  `getActionDescriptor()` no longer writes a placeholder dialog and a `SNACKBAR` feedbackType
+  into the `descriptor` the backend put on the action itself.