@scania-nl/tegel-angular-extensions 0.0.6 → 0.0.8

package/README.md

@@ -5,23 +5,30 @@
 
 # @scania-nl/tegel-angular-extensions
 
-Angular services for working with the [Tegel Angular 17](https://www.npmjs.com/package/@scania/tegel-angular-17) component library.
-Provides simple wrappers for toast and modal (TBC) functionality using Angular 19+ **standalone components** and **dependency injection configuration**.
+Angular components, services, and directives for working with the [Tegel Angular 17](https://www.npmjs.com/package/@scania/tegel-angular-17) component library.
+Provides simple wrappers for toast and modal functionality using Angular 19+ **standalone components** and **dependency injection configuration**.
 
 ---
 
-## ✨ Features
+ 
+
+## Features
 
 1. **Runtime environment configuration**
    - Schema-driven configuration and validation using Zod
    - Deep-partial runtime overrides
    - Runtime-required key enforcements
    - Strong TypeScript inference
-2. **ToastService**
-   - Drop-in UI integrations for Tegel Angular
+2. **Toast management**
    - Signal-based `ToastService` for displaying toasts
    - Customizable toast appearance and behavior
-3. **Default Nginx config**
+3. **Modal management**
+   - Strongly typed modal API
+   - Dynamic body content (string, template, or component)
+   - Configurable actions and lifecycle callbacks
+4. **Standalone components and directives**
+   - Drop-in UI integrations for Tegel Angular
+5. **Default Nginx config**
 
 - Zero boilerplate - no Angular modules required
 - Fully typed and configurable via DI
@@ -29,10 +36,12 @@ Provides simple wrappers for toast and modal (TBC) functionality using Angular 1
 
 ---
 
-# 📘 Table of Contents
+ 
+
+# Table of Contents
 
-1. [Installation](#-installation)
-2. [Environment Configuration Overview](#-environment-configuration-overview)
+1. [Installation](#installation)
+2. [Environment Configuration Overview](#environment-configuration-overview)
    1. [Defining your schema with createEnvKit](#defining-your-schema-with-createenvkit)
    2. [Defining Static Environments (Dev/Prod)](#defining-static-environments-devprod)
    3. [Providing Runtime Configuration](#providing-runtime-configuration)
@@ -42,27 +51,39 @@ Provides simple wrappers for toast and modal (TBC) functionality using Angular 1
       2. [`extract-env-vars.sh`](#extract-env-varssh)
       3. [`nginx.conf`](#nginxconf)
       4. [Example Docker Commands](#example-docker-commands)
-3. [Toasts](#-toasts)
-   1. [Quick Start](#-quick-start)
+3. [Toasts](#toasts)
+   1. [Quick Start](#quick-start)
       1. [Add Providers](#add-providers)
       2. [Use in components](#use-in-components)
-   2. [Configuration Options](#️-configuration-options)
-   3. [ToastService API](#-toastservice-api)
-      1. [ToastService Properties](#-toastservice-properties)
-      2. [ToastService Methods](#-toastservice-methods)
-      3. [Toast Lifecycle Hooks](#-toast-lifecycle-hooks)
-4. [Components & Directives](#-components--directives)
-   1. [Components](#-components)
+   2. [Toast Configuration Options](#toast-configuration-options)
+   3. [ToastService API](#toastservice-api)
+      1. [ToastService Properties](#toastservice-properties)
+      2. [ToastService Methods](#toastservice-methods)
+      3. [Toast Lifecycle Hooks](#toast-lifecycle-hooks)
+4. [Modals](#modals)
+   1. [Quick Start](#quick-start-1)
+      1. [Add Providers](#add-providers-1)
+      2. [Use in components](#use-in-components-1)
+   2. [Modal Configuration Options](#modal-configuration-options)
+   3. [ModalService API](#modalservice-api)
+      1. [ModalService Properties](#modalservice-properties)
+      2. [ModalService Methods](#modalservice-methods)
+      3. [Modal Lifecycle Hooks](#modal-lifecycle-hooks)
+5. [Components & Directives](#components--directives)
+   1. [Components](#components)
       1. [Footer](#footer-component-tae-footer)
-   2. [Directives](#-directives)
+   2. [Directives](#directives)
       1. [Hard Refresh](#hard-refresh-directive-taehardrefresh)
-5. [Appendix](#appendix)
+      2. [Barcode Scanner](#barcode-scanner-directive-taebarcodescanner)
+6. [Appendix](#appendix)
    1. [Dockerfile Example](#runtime-config-dockerfile-example)
-6. [License](#-license)
+7. [License](#license)
 
 ---
 
-# 📦 Installation
+ 
+
+# Installation
 
 ```bash
 npm install @scania-nl/tegel-angular-extensions @scania/tegel-angular-17 @traversable/zod zod
@@ -74,16 +95,18 @@ When creating an Angular project, the following dependencies already should have
 
 ```json
 {
-  "@angular/common": "^19.0.0",
-  "@angular/core": "^19.0.0",
-  "@angular/router": "^19.0.0",
+  "@angular/common": ">=19",
+  "@angular/core": ">=19",
+  "@angular/router": ">=19",
   "rxjs": ">=7.8.0"
 }
 ```
 
 ---
 
-# 🌍 Environment Configuration Overview
+ 
+
+# Environment Configuration Overview
 
 The runtime-config system provides:
 
@@ -92,6 +115,8 @@ The runtime-config system provides:
 - Runtime overrides via .env files (shell scripts included)
 - Guaranteed config availability before app bootstrap
 
+ 
+
 ## Defining your schema with createEnvKit
 
 Create a local file: `src/environments/environment-config.ts`
@@ -205,7 +230,7 @@ This setup involves several key steps:
 - At application startup, the code loads `/env/runtime.env`, parses any overrides using Zod (via a deep-partial schema), and merges them with the static configuration.
 - Required configuration keys are enforced **only** in production.
 - The validated configuration is exposed through Angular DI using the `ENV_CONFIG` InjectionToken.
-- The `environment` file is referenced directly here. Angular’s build process replaces the `development` environment with the `production` environment via file replacement based on the selected build configuration.
+- The `environment` file is referenced directly here. Angular's build process replaces the `development` environment with the `production` environment via file replacement based on the selected build configuration.
 
 > The `/env/runtime.env` file must be generated by the container during startup.
 > Shell script binaries to support this are included the package.
@@ -216,12 +241,16 @@ This setup involves several key steps:
 
 This package ships with two lightweight shell scripts used to generate a runtime configuration file inside the container. They enable true runtime configurability without rebuilding the Angular image. Additionally, the package contains a default `nginx.conf` optimized for Angular application. The files are located in the `/docker` directory.
 
+ 
+
 ### `docker-entrypoint.sh`
 
 - Entry point executed every time the container starts
 - Calls the `extract-env-vars.sh` to generate a fresh `runtime.env`
 - Lastly, executes the provided Dockerfile `CMD`
 
+ 
+
 ### `extract-env-vars.sh`
 
 - Reads all container environment variables matching a prefix (default: `NG__`)
@@ -229,6 +258,8 @@ This package ships with two lightweight shell scripts used to generate a runtime
 - Supports nested keys via ** (e.g., `NG**myFeature\_\_myThreshold`)
 - Defaults output to `/usr/share/nginx/html/env/runtime.env`
 
+ 
+
 ### `nginx.conf`
 
 A default Nginx configuration optimized for Angular applications. It provides:
@@ -238,6 +269,8 @@ A default Nginx configuration optimized for Angular applications. It provides:
 - Gzip compression where supported
 - Automatic fallback to `index.html` for client-side routing
 
+ 
+
 ### **Example Docker Commands**
 
 ```Dockerfile
@@ -253,21 +286,24 @@ CMD ["nginx", "-g", "daemon off;"]
 
 For a complete Dockerfile example with the shipped `nginx.conf` config, refer to [Runtime Config Dockerfile Example](#runtime-config-dockerfile-example)
 
- 
-
 ---
 
-# 🔔 Toasts
+ 
+
+# Toasts
 
 A lightweight, standalone toast system that integrates seamlessly with Tegel Angular. Provides configurable, signal-driven notifications for success, error, warning, and information messages.
 
-## 🚀 Quick Start
+ 
+
+## Quick Start
 
 ### Add Providers
 
 In your `app.config.ts`, specify the provider with `provideToast()`:
 
 ```ts
+// app.config.ts
 import { provideToast } from '@scania-nl/tegel-angular-extensions';
 
 export const appConfig: ApplicationConfig = {
@@ -286,6 +322,8 @@ export const appConfig: ApplicationConfig = {
 
 > Note: The configuration is optional, all values shown above are the default settings.
 
+ 
+
 ### Use in components
 
 In any standalone component:
@@ -313,7 +351,7 @@ export class MyToastDemoComponent {
 
  
 
-## ⚙️ Configuration Options
+## Toast Configuration Options
 
 You can configure the default appearance and behavior of toasts by passing a `ToastConfig` object to `provideToast()` in your `app.config.ts`.
 
@@ -334,22 +372,22 @@ All options are optional. Defaults will be applied if values are not provided.
 
  
 
-## 🧩 ToastService API
+## ToastService API
 
 The `ToastService` provides a signal-based API to create, manage, and dismiss toast notifications in Angular standalone apps. It is automatically available after registering `provideToast()` in your `app.config.ts`.
 
----
+ 
 
-### 📦 ToastService Properties
+### ToastService Properties
 
 | Property       | Type              | Description                                           |
 | -------------- | ----------------- | ----------------------------------------------------- |
 | `toasts`       | `Signal<Toast[]>` | Read-only list of all toasts (including closed)       |
 | `activeToasts` | `Signal<Toast[]>` | List of currently active toasts (`Open` or `Closing`) |
 
----
+&nbsp;
 
-### 🔧 ToastService Methods
+### ToastService Methods
 
 #### `create(toastOptions: Partial<ToastOptions>): number`
 
@@ -423,7 +461,9 @@ Force-removes all toasts instantly (no animations).
 
 ---
 
-### 🔁 Toast Lifecycle Hooks
+&nbsp;
+
+### Toast Lifecycle Hooks
 
 Each toast supports optional lifecycle callbacks:
 
@@ -447,12 +487,328 @@ toastService.success({
 
 &nbsp;
 
-# 🧩 Components & Directives
+# Modals
+
+Standalone modal service + host for Tegel's `tds-modal`, with strongly‑typed options and dynamic body support.
+
+&nbsp;
+
+## Quick Start
+
+### Add Providers
+
+In your `app.config.ts`, specify the provider with `provideModal()`:
+
+```ts
+// app.config.ts
+import { provideModal } from '@scania-nl/tegel-angular-extensions';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideModal({
+      size: 'md', // Modal size
+      actionsPosition: 'static', // Actions slot behavior
+      prevent: false, // Prevent overlay click from closing the modal
+      closable: true, // Show or hide the close [X] button
+      alertDialog: 'dialog', // ARIA role of the modal component
+      lazy: false, // Render body only while open
+      startOpen: true, // Open modal on creation
+      removeOnClose: true, // Remove modal from DOM when closed
+    }),
+  ],
+};
+```
+
+Most of these options are inherited from `tds-modal`.
+
+> Note: The configuration is optional, all values shown above are the default settings.
+
+### Use in components
+
+`create()` returns a `ModalRef` that can control the modal instance.
+
+```ts
+import { inject } from '@angular/core';
+import { ModalService } from '@scania-nl/tegel-angular-extensions';
+
+export class MyComponent {
+  private readonly modalService = inject(ModalService);
+
+  openModal() {
+    const ref = this.modalService.create({
+      header: 'Demo Modal',
+      body: 'Hello from modal',
+      startOpen: false,
+      removeOnClose: false,
+    });
+
+    ref.open(); // Opens the modal
+    ref.close(); // Closes (hides) the modal
+    ref.remove(); // Removes the modal from the DOM
+  }
+}
+```
+
+You get a `ModalRef` back from `create()`, which you can use to control that specific modal instance (`open()`, `close()`, `remove()`).
+
+---
+
+&nbsp;
+
+## Modal Configuration Options
+
+| Option            | Type                           | Default  | Description                 |
+| ----------------- | ------------------------------ | -------- | --------------------------- |
+| `size`            | `'xs' \| 'sm' \| 'md' \| 'lg'` | `md`     | Modal size                  |
+| `actionsPosition` | `'static' \| 'sticky'`         | `static` | Actions slot behavior       |
+| `prevent`         | `boolean`                      | `false`  | Prevent overlay close       |
+| `closable`        | `boolean`                      | `true`   | Show/hide close button      |
+| `alertDialog`     | `'dialog' \| 'alertdialog'`    | `dialog` | ARIA role                   |
+| `lazy`            | `boolean`                      | `false`  | Render body only while open |
+| `startOpen`       | `boolean`                      | `true`   | Open immediately on create  |
+| `removeOnClose`   | `boolean`                      | `true`   | Remove modal after close    |
+
+> Be aware that when `removeOnClose` is set to `false`, the modal content is hidden but **not destroyed**. If your body uses a component with active subscriptions, timers, or sockets, they will continue to run while the modal is hidden. Consider `removeOnClose: true` for component bodies if you want their resources to be disposed on close.
+
+---
+
+&nbsp;
+
+### Per-modal options (create)
+
+These options are passed to `modalService.create()` and override defaults from `provideModal()` on a per‑modal basis. For shared defaults like `size`, `actionsPosition`, `prevent`, `closable`, `alertDialog`, `lazy`, `startOpen`, and `removeOnClose`, see [Modal Configuration Options](#modal-configuration-options) above.
+
+| Option        | Type                                                               | Description                                          |
+| ------------- | ------------------------------------------------------------------ | ---------------------------------------------------- |
+| `header`      | `string \| TemplateRef<unknown>`                                   | Modal header text or template                        |
+| `body`        | `string \| TemplateRef<unknown> \| { component, inputs, outputs }` | Modal body content (string, template, or component)  |
+| `buttons`     | `ModalButton[]`                                                    | Action buttons to render in the actions slot         |
+| `selector`    | `string`                                                           | CSS selector for focus return element                |
+| `referenceEl` | `HTMLElement`                                                      | Element to return focus to (preferred over selector) |
+| `onClosed`    | `() => void \| Promise<void>`                                      | Called when the modal is closed                      |
+| `onRemoved`   | `() => void \| Promise<void>`                                      | Called after the modal is removed                    |
+
+> Note: If you want focus to return to the element that opened the modal, pass either `selector` or `referenceEl` when creating the modal. This avoids Tegel's "Missing focus origin" warning.
+
+---
+
+&nbsp;
+
+### Body content options
+
+The modal body can be provided as a simple string, a `TemplateRef`, or a component descriptor.
+
+&nbsp;
+
+#### 1) String body
+
+```ts
+this.modalService.create({
+  header: 'Simple',
+  body: 'This is a simple modal body',
+});
+```
+
+&nbsp;
+
+#### 2) TemplateRef body
+
+```html
+<ng-template #bodyTpl>
+  <strong>Template body</strong>
+</ng-template>
+```
+
+```ts
+const bodyTpl = viewChild<TemplateRef<unknown>>('bodyTpl');
+this.modalService.create({
+  header: 'Template',
+  body: bodyTpl(),
+});
+```
+
+&nbsp;
+
+#### 3) Component body (with inputs/outputs)
+
+When you pass a component as the modal body, the `inputs` and `outputs` objects are fully typed. This means you get IntelliSense for signal inputs/outputs, and any `input.required(...)` fields are enforced at compile time (missing required inputs will fail the build).
+
+```ts
+export class ExampleComponent {
+  readonly requiredField = input.required<string>();
+  readonly optionalField = input<string>();
+  readonly outputField = output<string>();
+}
+```
+
+```ts
+const ref = this.modalService.create({
+  header: 'Example',
+  body: {
+    component: ExampleComponent,
+    inputs: {
+      requiredField: 'Required',
+      // optionalField: 'Optional'
+    },
+    outputs: {
+      outputField: (value: string) => {
+        console.log('Value:', value);
+        ref.close();
+      }
+    },
+  },
+});
+```
+
+&nbsp;
+
+### Action buttons
+
+```ts
+this.modalService.create({
+  header: 'Confirm',
+  body: 'Are you sure?',
+  buttons: [
+    { text: 'OK', variant: 'primary', onClick: async () => console.log('OK') },
+    { text: 'Cancel', variant: 'secondary', dismiss: true },
+  ],
+  startOpen: true,
+});
+```
+
+- `dismiss`: true adds `data-dismiss-modal` for Tegel's built‑in close behavior.
+- `onClick` supports sync or async handlers.
+
+&nbsp;
+
+#### ModalButton options
+
+Modal action buttons map directly to Tegel's `tds-button` configuration. The following options are supported:
+
+| Option     | Type                                                          | Description                                                 |
+| ---------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
+| `text`     | `string`                                                      | Button label text                                           |
+| `variant`  | `'primary' \| 'secondary' \| 'success' \| 'danger'`           | Visual variant                                              |
+| `size`     | `'xs' \| 'sm' \| 'md' \| 'lg'`                                | Button size                                                 |
+| `disabled` | `boolean`                                                     | Disable the button                                          |
+| `dismiss`  | `boolean`                                                     | Adds `data-dismiss-modal` to trigger Tegel's close behavior |
+| `onClick`  | `() => void \| Promise<void>`                                 | Optional click handler (sync or async)                      |
+
+---
+
+&nbsp;
+
+## ModalService API
+
+The `ModalService` provides a signal-based API to create, manage, and dismiss modal instances. It is available after registering `provideModal()` in your `app.config.ts`.
+
+&nbsp;
+
+### ModalService Properties
+
+| Property | Type                         | Description                                        |
+| -------- | ---------------------------- | -------------------------------------------------- |
+| `modals` | `Signal<Map<string, Modal>>` | Read-only map of all registered modals keyed by id |
+
+&nbsp;
+
+### ModalService Methods
+
+#### `create<T>(options?: ModalOptions<T>): ModalRef`
+
+Creates and registers a new modal. Returns a `ModalRef` for controlling that instance.
+
+```ts
+const ref = modalService.create({
+  header: 'Hello',
+  body: 'Modal content',
+  startOpen: false,
+});
+
+ref.open();
+ref.close();
+ref.remove();
+```
+
+&nbsp;
+
+#### ModalRef
+
+`create()` returns a `ModalRef` with `open()`, `close()`, and `remove()` methods to control that specific modal instance.
+
+#### `open(id: string): void`
+
+Opens an existing modal by id.
+
+Example:
+
+```ts
+const ref = modalService.create({
+  header: 'Example',
+  body: 'Hello',
+  startOpen: false,
+});
+modalService.open(ref.id); // Equivalent to ref.open()
+```
+
+&nbsp;
+
+#### `close(id: string): void`
+
+Closes (hides) a modal by id. If `removeOnClose` is `true`, it is removed from the DOM after closing.
+
+&nbsp;
+
+#### `remove(id: string): void`
+
+Removes a modal from the registry/DOM. If the modal is open, it is closed first.
+
+&nbsp;
+
+#### `closeAll(): void`
+
+Closes all registered modals.
+
+&nbsp;
+
+#### `removeAll(): void`
+
+Removes all registered modals.
+
+---
+
+&nbsp;
+
+### Modal Lifecycle Hooks
+
+Each modal supports optional lifecycle callbacks:
+
+| Callback      | Description                                             |
+| ------------- | ------------------------------------------------------- |
+| `onClosed()`  | Called when the modal is closed                         |
+| `onRemoved()` | Called after the modal is removed from the registry/DOM |
+
+Example:
+
+```ts
+modalService.create({
+  header: 'Example',
+  body: 'Hello',
+  onClosed: () => console.log('Modal closed'),
+  onRemoved: () => console.log('Modal removed'),
+});
+```
+
+---
+
+&nbsp;
+
+# Components & Directives
 
 This library includes a set of standalone UI components and utility directives, all prefixed with **`tae`**, designed to extend and complement the Tegel Angular ecosystem. Each piece is lightweight, fully typed, and easy to import into any Angular 19+ application.
 &nbsp;
 
-## 🧱 Components
+## Components
 
 ### Footer Component (`tae-footer`)
 
@@ -478,7 +834,7 @@ This makes it ideal for full-viewport layouts that benefit from space efficiency
 
 &nbsp;
 
-## ⚡ Directives
+## Directives
 
 ### Hard Refresh Directive (`taeHardRefresh`)
 
@@ -488,10 +844,10 @@ This is especially useful for hard-reloading tablet or mobile applications which
 
 **Inputs:**
 
-| Input          | Type   | Default | Description                                                            |
-| -------------- | ------ | ------- | ---------------------------------------------------------------------- |
-| clicksRequired | number | 3       | Number of clicks required within the window to trigger a hard refresh. |
-| clickWindowMs  | number | 500     | Time window in milliseconds between two subsequent clicks.             |
+| Property         | Type     | Default | Description                                                            |
+| ---------------- | -------- | ------- | ---------------------------------------------------------------------- |
+| `clicksRequired` | `number` | `3`     | Number of clicks required within the window to trigger a hard refresh. |
+| `clickWindowMs`  | `number` | `500`   | Time window in milliseconds between two subsequent clicks.             |
 
 **Example:**
 
@@ -505,6 +861,40 @@ This is especially useful for hard-reloading tablet or mobile applications which
 </tds-header-brand-symbol>
 ```
 
+&nbsp;
+
+### Barcode Scanner Directive (`taeBarcodeScanner`)
+
+The `BarcodeScannerDirective` enables global barcode scanning by listening for rapid character input sequences (typically from a hardware scanner) that terminate with a specific key (default is `Enter`).
+
+It operates outside of Angular's zone to prevent unnecessary change detection cycles on every keypress and includes built-in filtering to ignore modifier keys like `Shift`, `Ctrl`, or `Alt`, ensuring only the actual barcode data is captured.
+
+**Inputs:**
+
+| Input           | Type     | Default   | Description                                                        |
+| --------------- | -------- | --------- | ------------------------------------------------------------------ |
+| `inputWindowMs` | `number` | `100`     | Max time allowed between consecutive keypresses before discarding. |
+| `terminatorKey` | `string` | `'Enter'` | The key that signals the end of a barcode sequence.                |
+
+**Outputs:**
+
+| Output           | Type     | Description                                                 |
+| ---------------- | -------- | ----------------------------------------------------------- |
+| `barcodeScanned` | `string` | **Required**. Emits the full barcode string once completed. |
+
+**Example:**
+
+```html
+<ng-container
+  taeBarcodeScanner
+  (barcodeScanned)="handleScan($event)"
+  [inputWindowMs]="100"
+  terminatorKey="Enter"
+>
+  <p>Scanner is active. Please scan a barcode...</p>
+</ng-container>
+```
+
 ---
 
 &nbsp;
@@ -561,7 +951,9 @@ CMD ["nginx", "-c", "/etc/nginx/nginx.conf", "-g", "daemon off;"]
 
 ---
 
-# 📄 License
+&nbsp;
+
+# License
 
 Copyright 2025 Scania CV AB.