@smartbit4all/ng-client 7.0.5 → 7.0.6

package/README.md

@@ -1,199 +1,199 @@
-# @smartbit4all/ng-client
-
-The Angular client of the smartbit4all platform: a backend-driven UI layer where the server
-owns the view lifecycle and the client renders it. Screen components extend
-`SmartComponent`, talk to the platform's BFF (`ViewApi` / `PageApi`), and the widgets inside
-them — grid, tree, form, filter, map, diagram, toolbars — reload themselves when the backend
-says their part of the model changed.
-
-**Requires Angular 22 and Material 22.** Everything is standalone; there are no NgModules.
-
-- Upgrading from 6.x? **`MIGRATION-7.0.md`**, shipped next to this file, is the whole change
-  list, and there is a codemod for the mechanical part.
-- Writing your own widget? **`WIDGETS.md`**, also next to this file.
-
----
-
-## Installation
-
-```bash
-npm i @smartbit4all/ng-client
-npm i @angular/material-date-fns-adapter@^22.0.0 date-fns@^4
-```
-
-## Wiring it up
-
-One call provides the whole library. It is deliberately not optional per module: the session
-and header interceptors used to be easy to leave out, and leaving them out failed *silently*
-— with no `Authorization` header.
-
-```ts
-bootstrapApplication(AppComponent, {
-  providers: [
-    provideAnimations(),
-    provideRouter(ROUTES),
-
-    provideSmartNgClient(
-      {
-        gridMenuIcon: 'more_horiz',
-        aclEditingViewName: Pages.ACL_MATRIX_PAGE,
-        namedValidators: [MY_VALIDATOR_FACTORY],
-      },
-      withSmartMap({ engine: MapEngine.LEAFLET }),   // optional: pulls in a map engine
-      withSmartDiagram({ customOptions: [MY_CHART] }) // optional: pulls in chart.js
-    ),
-
-    { provide: HTTP_INTERCEPTORS, useClass: MyLoadingInterceptor, multi: true },
-  ],
-});
-```
-
-`SmartNgClientConfig` is the entire configuration surface — see its doc comments for the
-fields. Only the map and the diagram are opt-in, because they are the only features that pull
-heavy third-party code.
-
-Components are standalone: import the ones your templates use 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> { … }
-```
-
-## Session and view context
-
-`SmartBackendBootstrapService` owns the startup sequence. Configure it once, then choose one
-entry point — `start()` for a normal web app, `bootstrapWith(creds)` when a native shell
-hands the session over. They are mutually exclusive; `reset()` switches.
-
-```ts
-@Injectable({ providedIn: 'root' })
-export class AppAuthBootstrap {
-  constructor(
-    private bootstrap: SmartBackendBootstrapService,
-    defaultErrorUi: SmartDefaultErrorUiService
-  ) {
-    this.bootstrap.configure({
-      url: 'https://my-host/api',
-      cookieName: 'my-app',
-      viewHandlers: HANDLERS,
-      actionDescriptors: ACTION_DESCRIPTORS,
-      ...defaultErrorUi.hooks({ language: 'hu' }),
-    });
-    this.bootstrap.start();
-  }
-}
-```
-
-```ts
-providers: [provideAppInitializer(() => { inject(AppAuthBootstrap); })]
-```
-
-Every screen component `await`s `bootstrap.whenReady()` before its first BFF call —
-`SmartComponentApiClient.run()` does it for you. The config hooks (`onStartError`,
-`onSessionError`, `onViewContextLost`, `onSmartLink`) are where host-specific behaviour goes;
-the error interceptor routes backend session errors into them.
-
-### View handlers
-
-The backend names the view; the host says what renders it.
-
-```ts
-export const HANDLERS: SmartViewHandlerModel[] = [
-  { name: Pages.ANY_PAGE, route: 'any' },                        // ViewType.NORMAL
-  { name: Pages.ANY_DIALOG, component: AnyDialogComponent },     // ViewType.DIALOG
-  { name: Pages.ANY_COMPONENT, route: 'any', component: AnyComponent },
-];
-```
-
-A view the host did not register still renders, through the library's default components;
-add your own with `defaultViewComponents`.
-
-### Smartlinks
-
-Route `/redirect/:channel/:uuid` to `SmartViewRedirect` (or to your own component extending
-it) and handle the hand-off in `configure({ onSmartLink })`.
-
-```ts
-const routes: Routes = [
-  {
-    path: `redirect/:${SmartLinkChannelVariableInPath}/:${SmartLinkUuidVariableInPath}`,
-    component: SmartViewRedirect,
-  },
-];
-```
-
-## UiActions
-
-The backend sends the actions; the host supplies their *descriptors* — caption, icon, button
-type, confirm/input dialog, feedback:
-
-```ts
-this.viewContext.setActionDescriptors(ACTION_DESCRIPTORS);
-this.viewContext.commonFeedbackText = 'Done.';
-```
-
-A toolbar renders the actions **addressed to its `id`** (`uiAction.toolbar == id`), pulling
-them from the screen component above it; an explicit `[uiActionModels]` binding wins. Without
-an `id` and without a binding it shows nothing.
-
-```html
-<smart-ui-action-toolbar [id]="'myToolbar'"></smart-ui-action-toolbar>
-<smart-ui-action-toolbar [uiActionModels]="myActions" [executor]="myService"></smart-ui-action-toolbar>
-```
-
-`[executor]` defaults to the screen component the toolbar sits under. Bind it only when the
-actions belong to another API — a tree service, a dialog service of your own — and implement
-`UiActionExecutor` there:
-
-```ts
-export class MyDialogService implements UiActionExecutor {
-  submitForm(validate: boolean): void { … }
-  getInvalidFields(): SmartFormInvalidFields { … }
-  getAdditionalParams(uiAction: UiAction): UiActionAdditionalParams { … }
-  getModel(): any { … }
-  performUiActionRequest(request: UiActionRequest): Promise<any> { … }
-  handleSpecificDemandsAsynchronously(…): Promise<UiActionSpecificDemandResponse> { … }
-}
-```
-
-A `UiActionModel` is **frozen**: build an entry, never edit one. To change how an action
-looks, rebuild the array — `actions.map(a => a.uiAction.code === c ? { ...a, cssClass: 'x' } : a)`
-— because it is the array reference changing that re-renders the toolbar.
-
-## Change detection
-
-7.0 runs without zone.js and every library component is `OnPush`. Nothing forces your host to
-drop zone.js — the library works either way — but if you do, 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
-
-The browser's timezone on screen, Zulu (`…Z`) on the wire, the server converts. Date widgets
-hold plain `Date` values and render `yyyy.MM.dd.`; the adapter is date-fns. If you provide
-`MAT_DATE_LOCALE`, the string `'hu-HU'` keeps working — see `MIGRATION-7.0.md`, *Dates*.
-
-## Dev tool
-
-```ts
-localStorage.setItem('smartDevToolActive', 'true');  // active
-localStorage.setItem('useDevTool', 'true');          // button visible
-```
-
----
-
-## Further reading
-
-| File | What it is |
-|---|---|
-| `MIGRATION-7.0.md` | the 6.x → 7.0 change list, and the codemod that does the mechanical part |
-| `WIDGETS.md` | the widget-authoring protocol |
-| `MIGRATION-6.0.md`, `MIGRATION-4.5.md` | the previous two majors |
-
-Per-module notes and version logs live next to the sources, in
-`src/lib/<module>/README.md` and `src/lib/<module>/versionLogs.md`.
+# @smartbit4all/ng-client
+
+The Angular client of the smartbit4all platform: a backend-driven UI layer where the server
+owns the view lifecycle and the client renders it. Screen components extend
+`SmartComponent`, talk to the platform's BFF (`ViewApi` / `PageApi`), and the widgets inside
+them — grid, tree, form, filter, map, diagram, toolbars — reload themselves when the backend
+says their part of the model changed.
+
+**Requires Angular 22 and Material 22.** Everything is standalone; there are no NgModules.
+
+- Upgrading from 6.x? **`MIGRATION-7.0.md`**, shipped next to this file, is the whole change
+  list, and there is a codemod for the mechanical part.
+- Writing your own widget? **`WIDGETS.md`**, also next to this file.
+
+---
+
+## Installation
+
+```bash
+npm i @smartbit4all/ng-client
+npm i @angular/material-date-fns-adapter@^22.0.0 date-fns@^4
+```
+
+## Wiring it up
+
+One call provides the whole library. It is deliberately not optional per module: the session
+and header interceptors used to be easy to leave out, and leaving them out failed *silently*
+— with no `Authorization` header.
+
+```ts
+bootstrapApplication(AppComponent, {
+  providers: [
+    provideAnimations(),
+    provideRouter(ROUTES),
+
+    provideSmartNgClient(
+      {
+        gridMenuIcon: 'more_horiz',
+        aclEditingViewName: Pages.ACL_MATRIX_PAGE,
+        namedValidators: [MY_VALIDATOR_FACTORY],
+      },
+      withSmartMap({ engine: MapEngine.LEAFLET }),   // optional: pulls in a map engine
+      withSmartDiagram({ customOptions: [MY_CHART] }) // optional: pulls in chart.js
+    ),
+
+    { provide: HTTP_INTERCEPTORS, useClass: MyLoadingInterceptor, multi: true },
+  ],
+});
+```
+
+`SmartNgClientConfig` is the entire configuration surface — see its doc comments for the
+fields. Only the map and the diagram are opt-in, because they are the only features that pull
+heavy third-party code.
+
+Components are standalone: import the ones your templates use 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> { … }
+```
+
+## Session and view context
+
+`SmartBackendBootstrapService` owns the startup sequence. Configure it once, then choose one
+entry point — `start()` for a normal web app, `bootstrapWith(creds)` when a native shell
+hands the session over. They are mutually exclusive; `reset()` switches.
+
+```ts
+@Injectable({ providedIn: 'root' })
+export class AppAuthBootstrap {
+  constructor(
+    private bootstrap: SmartBackendBootstrapService,
+    defaultErrorUi: SmartDefaultErrorUiService
+  ) {
+    this.bootstrap.configure({
+      url: 'https://my-host/api',
+      cookieName: 'my-app',
+      viewHandlers: HANDLERS,
+      actionDescriptors: ACTION_DESCRIPTORS,
+      ...defaultErrorUi.hooks({ language: 'hu' }),
+    });
+    this.bootstrap.start();
+  }
+}
+```
+
+```ts
+providers: [provideAppInitializer(() => { inject(AppAuthBootstrap); })]
+```
+
+Every screen component `await`s `bootstrap.whenReady()` before its first BFF call —
+`SmartComponentApiClient.run()` does it for you. The config hooks (`onStartError`,
+`onSessionError`, `onViewContextLost`, `onSmartLink`) are where host-specific behaviour goes;
+the error interceptor routes backend session errors into them.
+
+### View handlers
+
+The backend names the view; the host says what renders it.
+
+```ts
+export const HANDLERS: SmartViewHandlerModel[] = [
+  { name: Pages.ANY_PAGE, route: 'any' },                        // ViewType.NORMAL
+  { name: Pages.ANY_DIALOG, component: AnyDialogComponent },     // ViewType.DIALOG
+  { name: Pages.ANY_COMPONENT, route: 'any', component: AnyComponent },
+];
+```
+
+A view the host did not register still renders, through the library's default components;
+add your own with `defaultViewComponents`.
+
+### Smartlinks
+
+Route `/redirect/:channel/:uuid` to `SmartViewRedirect` (or to your own component extending
+it) and handle the hand-off in `configure({ onSmartLink })`.
+
+```ts
+const routes: Routes = [
+  {
+    path: `redirect/:${SmartLinkChannelVariableInPath}/:${SmartLinkUuidVariableInPath}`,
+    component: SmartViewRedirect,
+  },
+];
+```
+
+## UiActions
+
+The backend sends the actions; the host supplies their *descriptors* — caption, icon, button
+type, confirm/input dialog, feedback:
+
+```ts
+this.viewContext.setActionDescriptors(ACTION_DESCRIPTORS);
+this.viewContext.commonFeedbackText = 'Done.';
+```
+
+A toolbar renders the actions **addressed to its `id`** (`uiAction.toolbar == id`), pulling
+them from the screen component above it; an explicit `[uiActionModels]` binding wins. Without
+an `id` and without a binding it shows nothing.
+
+```html
+<smart-ui-action-toolbar [id]="'myToolbar'"></smart-ui-action-toolbar>
+<smart-ui-action-toolbar [uiActionModels]="myActions" [executor]="myService"></smart-ui-action-toolbar>
+```
+
+`[executor]` defaults to the screen component the toolbar sits under. Bind it only when the
+actions belong to another API — a tree service, a dialog service of your own — and implement
+`UiActionExecutor` there:
+
+```ts
+export class MyDialogService implements UiActionExecutor {
+  submitForm(validate: boolean): void { … }
+  getInvalidFields(): SmartFormInvalidFields { … }
+  getAdditionalParams(uiAction: UiAction): UiActionAdditionalParams { … }
+  getModel(): any { … }
+  performUiActionRequest(request: UiActionRequest): Promise<any> { … }
+  handleSpecificDemandsAsynchronously(…): Promise<UiActionSpecificDemandResponse> { … }
+}
+```
+
+A `UiActionModel` is **frozen**: build an entry, never edit one. To change how an action
+looks, rebuild the array — `actions.map(a => a.uiAction.code === c ? { ...a, cssClass: 'x' } : a)`
+— because it is the array reference changing that re-renders the toolbar.
+
+## Change detection
+
+7.0 runs without zone.js and every library component is `OnPush`. Nothing forces your host to
+drop zone.js — the library works either way — but if you do, 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
+
+The browser's timezone on screen, Zulu (`…Z`) on the wire, the server converts. Date widgets
+hold plain `Date` values and render `yyyy.MM.dd.`; the adapter is date-fns. If you provide
+`MAT_DATE_LOCALE`, the string `'hu-HU'` keeps working — see `MIGRATION-7.0.md`, *Dates*.
+
+## Dev tool
+
+```ts
+localStorage.setItem('smartDevToolActive', 'true');  // active
+localStorage.setItem('useDevTool', 'true');          // button visible
+```
+
+---
+
+## Further reading
+
+| File | What it is |
+|---|---|
+| `MIGRATION-7.0.md` | the 6.x → 7.0 change list, and the codemod that does the mechanical part |
+| `WIDGETS.md` | the widget-authoring protocol |
+| `MIGRATION-6.0.md`, `MIGRATION-4.5.md` | the previous two majors |
+
+Per-module notes and version logs live next to the sources, in
+`src/lib/<module>/README.md` and `src/lib/<module>/versionLogs.md`.