@smartbit4all/ng-client 6.0.35 → 7.0.1

package/README.md

@@ -1,386 +1,199 @@
-# Smart Ng Client
-
----
-
-## How to use
-
-### Installation
-
-Go to your project, open the terminal and use the following command:
-
-    npm i @smartbit4all/ng-client
-
-Provide the `SmartNgClientModule` in the app.module:
-
-`app.module.ts:`
-
-    @NgModule({
-        declarations: [...],
-        imports: [
-            SmartNgClientModule,
-            ...
-        ],
-        providers: [
-            SmartSessionService,
-    	    SmartViewContextService,
-            ...
-        ],
-        ...
-    })
-
-### Usage
-
-In order to use the SmartSessionService I recommend to follow the guideline belove.
-
-**Generate a service** which will **handle the session and the authentication**.
-
-`Terminal:`
-
-    >>> cd src/app
-
-    >>> mkdir services
-
-    >>> cd ./services
-
-    >>> ng g s authentication
-
-Provide this new service as a **global service**:
-
-`app.module.ts:`
-
-    @NgModule({
-        declarations: [...],
-        imports: [...],
-        providers: [
-            SmartSessionService,
-            AuthenticationService,
-            ...
-        ],
-        ...
-    })
-
-### Authentication state changed
-
-The change of authentication state can be detected in any components. To handle it you must subscribe to the change itself.
-
-**Note that in this version a user is authenticated when the response of the GET session contains a list of authentications.**
-
-    this.isAuthenticated = response.authentications.length > 0
-
-`any.component.ts:`
-
-    constructor(
-    	private auth: AuthenticationService,
-    	private session: SmartSessionService
-    ) {
-    	this.session.authenticationStateChanged.subscribe((isAuth: boolean) => {
-    		if (!isAuth) {
-    			this.router.navigate(['/login']);
-    		}
-    	});
-    }
-
-### Using locales
-
-The `SmartSessionService` supports the usage of locales in you application. It is important to note that the language is related to the session!
-
-This example uses the [NgxTranslate/core](https://www.npmjs.com/package/@ngx-translate/core) package.
-
-`authentication.service.ts:`
-
-    import { TranslateService } from '@ngx-translate/core';
-    ...
-
-    export class AuthenticationService {
-        ...
-
-        constructor(
-            ...
-            private translate: TranslateService
-        ) {
-            this.session.localeChanged.subscribe(() => {
-                this.translate.use(this.session.getLocale());
-            });
-        }
-
-        async changeLocale(locale: string): Promise<void> {
-            await this.session.changeLocale(locale);
-        }
-
-        getLocale(): string {
-            return this.session.getLocale();
-        }
-    }
-
-### SmartDevTool usage
-
-Turn on and off the devTool:
-
-    // active
-    localStorage.setItem('smartDevToolActive', 'true');
-    // inactive
-    localStorage.setItem('smartDevToolActive', 'false');
-
-Set the devTool's button visibility
-
-    // visible
-    localStorage.setItem('useDevTool', 'true');
-    // invisible
-    localStorage.setItem('useDevTool', 'false');
-
-In order to use this package properly, please create a folder called `viewcontext` in which a `view-context.pages.model.ts` shall be created:
-
--   src/app/viewcontext/
-    -   view-context.pages.ts
-    -   view-context.handlers.ts
-
-`view-context.pages.ts:`
-
-    export enum Pages {
-        // mandatory
-        VIEW_CONTEXT = 'viewContextUuid',
-
-        // optionals
-        ANY_PAGE = 'anyPage',
-        ANY_DIALOG = 'anyDialog,
-        ANY_COMPONENT = 'anyComponent,
-        ...
-    }
-
-`view-context.handlers.ts:`
-
-    import { SmartViewHandlerModel, ViewType } from '@smartbit4all/view-context';
-    import { Pages } from './view-context.pages';
-    import { AnyDialogService } from '../any-dialog/any-dialog.service';
-
-    export const viewContextHandlers: SmartViewHandlerModel[] = [
-        // ViewType.Normal
-        {
-            name: Pages.ANY_PAGE,
-            route: 'any'
-        },
-        // ViewType.Dialog
-        {
-            name: Pages.ANY_DIALOG,
-            component: AnyDialogComponent
-        },
-        // ViewType.Normal or ViewType.Dialog
-        {
-            name: Pages.ANY_COMPONENT,
-            route: 'any',
-            component: AnyComponent
-        }
-    ];
-
-Don't forget to define some ApiErrors and inject it into the **AuthenticationService**:
-
-`view-context.api-errors.ts:`
-
-    const viewContextApiErrors: SmartViewContextApiErrors = {
-        viewContextApiErrors:  [
-            {
-                code: "001",
-                dialogTitle?: "Error"
-                message: "An error message"
-                buttonLabel?: "Ok"
-            }
-        ]
-    }
-
-### SmartLink
-
-In order to use SmartLinks in your application, follow the instruction:
-
-Firstly, set up the routing:
-
-`app-routing.module.ts:`
-
-    const routes: Routes = [
-        // Out of the box solution
-        {
-            path: `redirect/:${SmartLinkChannelVariableInPath}/:${SmartLinkUuidVariableInPath}`,
-            component: SmartViewRedirect,
-        },
-        // Custom solution
-        {
-            path: `customRedirect/:${SmartLinkChannelVariableInPath}/:${SmartLinkUuidVariableInPath}`,
-            component: RedirectComponent,
-        },
-        ...
-    ]
-
-Then you can set up your custom redirect component as you wish:
-
-`redirect.component.ts:`
-
-    @Component({
-        selector: "app-redirect",
-        templateUrl: "./redirect.component.html",
-        styleUrls: ["./redirect.component.css"],
-    })
-    export class RedirectComponent extends SmartViewRedirect {
-        constructor(
-            service: SmartViewContextService,
-            navigation: SmartNavigationService,
-            route: ActivatedRoute
-        ) {
-            super(
-                service,
-                navigation,
-                route
-            );
-        }
-    }
-
-Then subscribe for the _openSmartLink_ event and handle it in your AuthenticationService:
-
-`authentication.service.ts:`
-
-    constructor(...) {
-        ...
-        this.viewContext.openSmartLink.subscribe(() => {
-            this.handleOpenSmartLinkEvent();
-        })
-    }
-
-    private async handleOpenSmartLinkEvent(): Promise<void> {
-        // Do your business logic here
-
-        // If authentication is needed to open the link:
-        let isAuthenticated = await this.isAuthenticated();
-        if (isAuthenticated) {
-            this.viewContext.openSmartLink.complete();
-        } else {
-            // Navigate to login screen without reloading the site!
-        }
-    }
-
-    // Modify this if authentication is needed to open links
-    async login(request: LocalAuthenticationLoginRequest): Promise<boolean> {
-        await this.auth.login(request);
-        let isAuth = await this.session.getIsAuthenticated();
-        if (isAuth) {
-            await this.viewContext.initialize();
-
-            await this.anyBffApi.startAnyPage().toPromise();
-
-            // If there is a smart link waiting for opening...
-            if (this.viewContext.isOpeningSmartLink) {
-                this.viewContext.openSmartLink.complete();
-                return isAuth;
-            }
-
-            let uuid = this.viewContext.getUuidOfPage(Pages.VIEW_CONTEXT);
-            await this.viewContext.getAndSyncViewContext(uuid);
-        }
-        return isAuth;
-    }
-
-### UiActions
-
-The ViewContext package contains a common manager for the UiActions. To use this tool, please follow the instructions.
-
-`action.descriptors.ts:`
-
-    import {
-        UiActionButtonIconPos,
-        UiActionButtonType,
-        UiActionDescriptor
-    } from '@smartbit4all/view-context';
-
-    // Build your own action descriptors
-    export const ActionDescriptors: Map<string, UiActionDescriptor> = new Map([
-        [
-            'EXAMPLE',
-            {
-                title: 'Example action',
-    	        type: UiActionButtonType.Raised,
-    	        color: 'primary',
-                dialog: {
-                    title: 'Example dialog title',
-                    text: 'Example dialog text',
-                    actionButton: {
-                        caption: 'Example action',
-                        color: 'primary'
-                    },
-                    cancelButton: {
-                        caption: 'Cancel',
-                        color: ''
-                    }
-                },
-                inputDialog: { ... },
-                confirmDialog: { ... },
-                feedbackType: UiActionFeedbackType.SNACKBAR;
-                feedbackText: "Example feedback";
-            }
-        ]
-    ])
-
-`authentication.service.ts:`
-
-    constructor(...) {
-        ...
-        // Set your descriptors
-        this.viewContext.setActionDescriptors(ActionDescriptors);
-
-        // Set basic feedback
-        this.viewContext.commonFeedbackText = "Basic feedback."
-        ...
-    }
-
-`example.component.ts:`
-
-    @Component({
-        selector: 'app-example',
-        templateUrl: './example.component.html',
-        styleUrls: ['./example.component.css']
-    })
-    export class ExampleComponent implements UseUiAction {
-        possibleActions: UiAction[]; // Comes from the backend
-        actions: UiActionModel[] = [];
-
-        // UseUiAction properties
-        submit: Subject<void> = new Subject();
-    	reSubscribeToChange: Subject<void> = new Subject();
-
-        constructor(private service: ExampleService) {}
-
-        // UseUiAction functions
-        getAdditionalParams(uiAction: UiAction): UiActionAdditionalParams {
-            // return additional parameters if needed
-            throw new Error('Method not implemented.');
-        }
-        getModel() {
-            // return the model of the page
-            throw new Error('Method not implemented.');
-        }
-        async performUiActionRequest(uiActionRequest: UiActionRequest): Promise<any> {
-            // perform the uiActionRequest on the proper service
-            await this.service.performAction(uiActionRequest)
-        }
-        handleSpecificDemandsAsynchronously(uiAction: UiAction): Promise<UiActionSpecificDemandResponse> {
-            // handle specific demands if needed
-            throw new Error('Method not implemented.');
-        }
-
-        // Construct
-        constructActions(): void {
-            this.actions = [];
-            let exceptions = ['EXCEPTION'];
-            this.possibleActions.map((uiAction: UiAction) => {
-                this.actions?.push({
-                    uiAction,
-                    serviceToUse: this, // bind a class which implements the UseUiAction
-                    exception: exceptions.includes(uiAction.code!)
-                });
-            });
-        }
-    }
-
-`example.component.html:`
-
-    <smart-ui-action-toolbar [uiActionModels]="actions"></smart-ui-action-toolbar>
-
----
-
-## Version logs
+# @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`.