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

package/README.md

@@ -1,3 +1,8 @@
+![npm version](https://img.shields.io/npm/v/@scania-nl/tegel-angular-extensions)
+![angular](https://img.shields.io/badge/angular-19%2B-DD0031?logo=angular)
+![typescript](https://img.shields.io/badge/typescript-5%2B-3178C6?logo=typescript)
+![zod](https://img.shields.io/badge/zod-schema-3066BE)
+
 # @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.
@@ -7,38 +12,260 @@ Provides simple wrappers for toast and modal (TBC) functionality using Angular 1
 
 ## ✨ Features
 
-- ✅ Drop-in `ToastService` for displaying toasts
-- ✅ Zero boilerplate — no Angular modules required
-- ✅ Fully typed and configurable via DI
-- ✅ Built for Angular 19+ standalone architecture
+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
+   - Signal-based `ToastService` for displaying toasts
+   - Customizable toast appearance and behavior
+3. **Default Nginx config**
+
+- Zero boilerplate - no Angular modules required
+- Fully typed and configurable via DI
+- Built for Angular 19+ standalone architecture
 
 ---
 
-## 📦 Installation
+# 📘 Table of Contents
+
+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)
+   4. [Using the ENV_CONFIG Token](#using-the-env_config-token)
+   5. [Runtime Configuration Binaries](#runtime-configuration-binaries)
+      1. [`docker-entrypoint.sh`](#docker-entrypointsh)
+      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)
+      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)
+      1. [Footer](#footer-component-tae-footer)
+   2. [Directives](#-directives)
+      1. [Hard Refresh](#hard-refresh-directive-taehardrefresh)
+5. [Appendix](#appendix)
+   1. [Dockerfile Example](#runtime-config-dockerfile-example)
+6. [License](#-license)
+
+---
+
+# 📦 Installation
 
 ```bash
-npm install @scania-nl/tegel-angular-extensions @scania/tegel-angular-17
+npm install @scania-nl/tegel-angular-extensions @scania/tegel-angular-17 @traversable/zod zod
 ```
 
-> Note: `@scania/tegel-angular-17` is a peer dependency and must be installed separately.
+> Note: `@scania/tegel-angular-17`, `@traversable/zod`, and `zod` are peer dependencies and must be installed separately.
 
-The following peer dependencies should be included automatically when creating an Angular 19+ project:
+When creating an Angular project, the following dependencies already should have been installed:
 
 ```json
 {
   "@angular/common": "^19.0.0",
   "@angular/core": "^19.0.0",
   "@angular/router": "^19.0.0",
-  "rxjs": "~7.8.0"
+  "rxjs": ">=7.8.0"
 }
 ```
 
 ---
 
+# 🌍 Environment Configuration Overview
+
+The runtime-config system provides:
+
+- Type-safe configuration via Zod schemas
+- Static environment validation
+- 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`
+
+```ts
+import { InjectionToken } from '@angular/core';
+import { createEnvKit } from '@scania-nl/tegel-angular-extensions';
+import { z } from 'zod';
+
+// Create the EnvKit by defining a Zod-schema
+export const EnvKit = createEnvKit({
+  schema: z
+    .object({
+      envType: z.enum(['dev', 'preprod', 'staging', 'prod']),
+      production: z.boolean(),
+      apiUrl: z.url(),
+    })
+    .strict(),
+  runtimeRequiredKeys: ['apiUrl'],
+});
+
+// Re-export for static env files
+type EnvConfig = typeof EnvKit.types.EnvConfig;
+export type StaticEnv = typeof EnvKit.types.StaticEnv;
+
+// Injection Token for EnvConfig
+export const ENV_CONFIG = new InjectionToken<EnvConfig>('ENV_CONFIG');
+```
+
+&nbsp;
+
+## Defining Static Environments (Dev/Prod)
+
+Initialize the environments using Nx:
+
+```bash
+nx g environments
+```
+
+This will create two files: `environment.ts` for the production environment configuration and `environment.development.ts` for the local development environment configuration.
+
+`environment.development.ts`:
+
+```ts
+import { StaticEnv } from './environment-config';
+
+export const environment: StaticEnv = {
+  envType: 'dev',
+  production: false,
+  apiUrl: 'https://www.company.com/api/',
+} satisfies StaticEnv;
+```
+
+`environment.ts`:
+
+```ts
+import { StaticEnv } from './environment-config';
+
+export const environment: StaticEnv = {
+  envType: 'prod',
+  production: true,
+  // apiUrl: 'https://www.company.com/api/' // apiUrl cannot be defined here
+} satisfies StaticEnv;
+```
+
+&nbsp;
+
+## Providing Runtime Configuration
+
+Add to `app.config.ts`:
+
+```ts
+import { provideRuntimeConfig } from '@scania-nl/tegel-angular-extensions';
+import { EnvKit, ENV_CONFIG } from '../environments/environment-config';
+import { environment } from '../environments/environment';
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    // ...
+    provideRuntimeConfig(EnvKit, environment, {
+      envPath: '/env/runtime.env', // Default
+      debug: !isDevMode(), // Defaults to false
+      stopOnError: true, // Default
+      token: ENV_CONFIG,
+    }),
+  ],
+};
+```
+
+&nbsp;
+
+## Using the ENV_CONFIG Token
+
+```ts
+import { inject } from '@angular/core';
+import { ENV_CONFIG } from '../environments/environment-config';
+
+@Injectable()
+export class ApiService {
+  private readonly envConfig = inject(ENV_CONFIG);
+
+  constructor() {
+    console.log('API base URL:', this.envConfig.apiUrl);
+  }
+}
+```
+
+&nbsp;
+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 `/env/runtime.env` file must be generated by the container during startup.
+> Shell script binaries to support this are included the package.
+
+&nbsp;
+
+## Runtime Configuration Binaries
+
+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__`)
+- Strips the prefix and writes cleaned `KEY=VALUE` pairs to `runtime.env`
+- 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:
+
+- Performance tuning for static file serving
+- Browser caching of compiled assets
+- Gzip compression where supported
+- Automatic fallback to `index.html` for client-side routing
+
+### **Example Docker Commands**
+
+```Dockerfile
+# Copy the shell scripts to /usr/local/bin
+COPY --from=build /app/node_modules/@scania-nl/tegel-angular-extensions/docker/*.sh /usr/local/bin/
+# Ensure they shell scripts are executable
+RUN chmod +x /usr/local/bin/*
+# Use the shared entrypoint from the @scania-nl/tegel-angular-extensions npm package
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
+# Start the nginx web server in the foreground and keep it running
+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)
+
+&nbsp;
+
+---
+
+# 🔔 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
 
-### 1. Add Providers
-In your `app.config.ts`, specifiy the provider with `provideToast()`:
+### Add Providers
+
+In your `app.config.ts`, specify the provider with `provideToast()`:
 
 ```ts
 import { provideToast } from '@scania-nl/tegel-angular-extensions';
@@ -46,19 +273,21 @@ import { provideToast } from '@scania-nl/tegel-angular-extensions';
 export const appConfig: ApplicationConfig = {
   providers: [
     provideToast({
-      type: 'information',      // Default toast type
-      title: 'Notification',    // Default title
-      description: '',          // Default description
-      duration: 7500,           // Auto-dismiss delay (ms)
-      closeDuration: 300,       // Fade-out animation duration (ms)
-      closable: true,           // Show a close button
+      type: 'information', // Default toast type
+      title: 'Notification', // Default title
+      description: '', // Default description
+      duration: 7500, // Auto-dismiss delay (ms)
+      closeDuration: 300, // Fade-out animation duration (ms)
+      closable: true, // Show a close button
     }),
   ],
 };
 ```
+
 > Note: The configuration is optional, all values shown above are the default settings.
 
-### 2. Use in components
+### Use in components
+
 In any standalone component:
 
 ```ts
@@ -72,9 +301,9 @@ export class MyToastDemoComponent {
 
   showToast() {
     this.toastService.create({
-        type: 'success',
-        title: 'Hello Toast',
-        description: 'Toast created successfully!'
+      type: 'success',
+      title: 'Hello Toast',
+      description: 'Toast created successfully!',
     });
   }
 }
@@ -82,6 +311,8 @@ export class MyToastDemoComponent {
 
 ---
 
+&nbsp;
+
 ## ⚙️ Configuration Options
 
 You can configure the default appearance and behavior of toasts by passing a `ToastConfig` object to `provideToast()` in your `app.config.ts`.
@@ -101,13 +332,15 @@ All options are optional. Defaults will be applied if values are not provided.
 
 ---
 
+&nbsp;
+
 ## 🧩 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`.
 
 ---
 
-### 📦 Properties
+### 📦 ToastService Properties
 
 | Property       | Type              | Description                                           |
 | -------------- | ----------------- | ----------------------------------------------------- |
@@ -116,7 +349,7 @@ The `ToastService` provides a signal-based API to create, manage, and dismiss to
 
 ---
 
-### 🔧 Methods
+### 🔧 ToastService Methods
 
 #### `create(toastOptions: Partial<ToastOptions>): number`
 
@@ -135,7 +368,7 @@ toastService.create({
 
 Returns the unique toast ID.
 
----
+&nbsp;
 
 #### Convenience Methods
 
@@ -148,13 +381,13 @@ toastService.warning({ title: 'Heads up!' });
 toastService.info({ title: 'FYI' });
 ```
 
----
+&nbsp;
 
 #### `getToast(id: number): Toast | undefined`
 
 Gets a toast by its ID.
 
----
+&nbsp;
 
 #### `createRandomToast(props?: Partial<ToastOptions>): number`
 
@@ -164,25 +397,25 @@ Creates a random toast with random type and title. Useful for testing. Returns t
 toastService.createRandomToast();
 ```
 
----
+&nbsp;
 
 #### `close(id: number): void`
 
 Triggers the fade-out animation and schedules removal.
 
----
+&nbsp;
 
 #### `closeAll(): void`
 
 Closes all currently open toasts.
 
----
+&nbsp;
 
 #### `remove(id: number): void`
 
 Immediately removes a toast (no animation).
 
----
+&nbsp;
 
 #### `removeAll(): void`
 
@@ -206,12 +439,136 @@ Example:
 toastService.success({
   title: 'Logged out',
   duration: 5000,
-  onRemoved: (toast) => console.log(`Toast ${toast.id} removed`)
+  onRemoved: (toast) => console.log(`Toast ${toast.id} removed`),
 });
 ```
 
 ---
 
-## 📄 License
+&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
+
+### Footer Component (`tae-footer`)
+
+`TaeFooterComponent` is an enhanced footer based on the Tegel `TdsFooterComponent`. It preserves the same visual appearance while adding two key improvements:
+
+- A **compact “small” variant** for constrained layouts.
+- An optional **version display**, allowing applications to show their build or release version directly in the footer.
+
+This makes it ideal for full-viewport layouts that benefit from space efficiency and clear version visibility.
+
+**Inputs:**
+
+| Input   | Type                  | Default | Description                                                                                |
+| ------- | --------------------- | ------- | ------------------------------------------------------------------------------------------ |
+| variant | `'normal' \| 'small'` | normal  | Layout style of the footer. `'small'` produces a more compact version.                     |
+| version | `string \| undefined` | —       | Optional application version string. If provided, it is displayed left of the Scania logo. |
+
+**Example:**
+
+```html
+<tae-footer variant="small" version="v1.0.0" />
+```
+
+&nbsp;
+
+## ⚡ Directives
+
+### Hard Refresh Directive (`taeHardRefresh`)
+
+The `HardRefreshDirective` provides a small UX shortcut: it performs a **full page reload** when the host element is clicked **N times in rapid succession**, where each click must occur within `clickWindowMs` milliseconds of the previous one.
+
+This is especially useful for hard-reloading tablet or mobile applications which are locked in full-screen mode, and thus have no browser buttons like refresh.
+
+**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.             |
+
+**Example:**
+
+```html
+<tds-header-brand-symbol
+  taeHardRefresh
+  [clicksRequired]="3"
+  [clickWindowMs]="500"
+>
+  <a aria-label="Scania - red gryphon on blue shield"></a>
+</tds-header-brand-symbol>
+```
+
+---
+
+&nbsp;
+
+# Appendix
+
+## Runtime Config Dockerfile Example
+
+```Dockerfile
+ARG NODE_VERSION=25-alpine
+ARG NGINX_VERSION=1.29.3-alpine
+
+# Stage 1: Build the Angular Application
+FROM node:${NODE_VERSION} AS build
+
+WORKDIR /app
+
+# Copy package-related files
+COPY package*.json ./
+
+# Install project dependencies using npm ci (ensures a clean, reproducible install)
+RUN --mount=type=cache,target=/root/.npm npm ci
+
+# Copy the rest of the application source code into the container
+COPY . .
+
+# Build the Angular application with the specified app version
+RUN npm run build
+
+
+# Stage 2: Prepare Nginx to Serve Static Files
+FROM nginx:${NGINX_VERSION}
+
+# Copy the static build output from the build stage to Nginx's default HTML serving directory
+COPY --from=build /app/dist/*/browser /usr/share/nginx/html
+
+# Copy the shell scripts from the @scania-nl/tegel-angular-extensions npm package
+COPY --from=build /app/node_modules/@scania-nl/tegel-angular-extensions/docker/*.sh /usr/local/bin/
+# Copy the custom Nginx configuration file from the @scania-nl/tegel-angular-extensions npm package
+COPY --from=build /app/node_modules/@scania-nl/tegel-angular-extensions/docker/nginx.conf /etc/nginx/nginx.conf
+
+# Ensure the shell scripts are executable
+RUN chmod +x /usr/local/bin/*
+
+# Expose ports 80 and 443 to allow HTTP and HTTPS traffic
+EXPOSE 80 443
+
+# Use the shared entrypoint from the @scania-nl/tegel-angular-extensions npm package
+ENTRYPOINT ["/usr/local/bin/docker-entrypoint.sh"]
+
+# Start the nginx web server with custom config in the foreground and keep it running
+CMD ["nginx", "-c", "/etc/nginx/nginx.conf", "-g", "daemon off;"]
+```
+
+---
+
+# 📄 License
+
+Copyright 2025 Scania CV AB.
+
+All files are available under the MIT license. The Scania brand identity, logos and photographs found in this repository are copyrighted Scania CV AB and are not available on an open source basis or to be used as examples or in any other way, if not specifically ordered by Scania CV AB.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-All CSS, HTML and JS code are available under the MIT license. The Scania brand identity, logos and photographs found in this repository are copyrighted Scania CV AB and are not available on an open source basis or to be used as examples or in any other way, if not specifically ordered by Scania CV AB.
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/docker/docker-entrypoint.sh

@@ -0,0 +1,13 @@
+#!/bin/sh
+
+ENV_OUTPUT_PATH="/usr/share/nginx/html/env/runtime.env"
+
+rm -f "$ENV_OUTPUT_PATH"  # Remove the runtime config if it exists
+
+# Generate the runtime config from env vars
+if ! /usr/local/bin/extract-env-vars.sh "" "$ENV_OUTPUT_PATH"; then
+  echo "Failed to extract runtime environment variables, continuing with defaults..."
+fi
+
+# Then start Nginx
+exec "$@"

package/docker/extract-env-vars.sh

@@ -0,0 +1,114 @@
+#!/bin/sh
+
+# --------------
+# Configuration
+# --------------
+
+PREFIX="${1:-NG__}"                 # First argument = prefix, defaults to NG__
+OUTPUT_FILE="${2:-./runtime.env}"  # Second argument = output path, defaults to current dir
+shift 2                             # Remaining arguments = manual test vars like NG__key=value
+
+OUTPUT_DIR=$(dirname "$OUTPUT_FILE") # Output directory
+TMP_FILE="/tmp/runtime_env_$$.tmp" # Temp file for writing
+: > "$TMP_FILE"  # Create/empty the temp file
+
+# --------------
+# Logging Helpers
+# --------------
+
+log_info()  { echo "[INFO] $*"; }
+log_warn()  { echo "[WARN] $*"; }
+log_debug() { echo "[DEBUG] $*"; }
+
+# --------------
+# Validation
+# --------------
+
+validate_var() {
+  raw="$1"
+  key="${raw%%=*}"
+
+  # Must start with prefix
+  case "$key" in
+    "$PREFIX") return 1 ;; # only prefix, no key
+    "$PREFIX"*) ;;
+    *) return 1 ;;
+  esac
+
+  # Strip prefix
+  trimmed="${key#$PREFIX}"
+
+  # Key must not start with a digit
+  first_segment=$(printf '%s' "$trimmed" | cut -d'_' -f1)
+  case "$first_segment" in
+    [0-9]*)
+      return 1 ;;
+  esac
+
+  return 0
+}
+
+strip_prefix() {
+  printf '%s\n' "$1" | sed "s/^$PREFIX//"
+}
+
+# --------------
+# Extract ENV vars
+# --------------
+
+log_info "Using prefix: '$PREFIX'"
+log_info "Output file: $OUTPUT_FILE"
+
+env | grep "^$PREFIX" | while IFS= read -r line; do
+  if validate_var "$line"; then
+    key="${line%%=*}"
+    val="${line#*=}"
+    clean_key=$(strip_prefix "$key")
+    printf '%s=%s\n' "$clean_key" "$val" >> "$TMP_FILE"
+    log_debug "Added from environment: $clean_key=$val"
+  else
+    log_warn "Skipped invalid env var: $line"
+  fi
+done
+
+# --------------
+# Manual vars
+# --------------
+
+for var in "$@"; do
+  if validate_var "$var"; then
+    key="${var%%=*}"
+    val="${var#*=}"
+    clean_key=$(strip_prefix "$key")
+    printf '%s=%s\n' "$clean_key" "$val" >> "$TMP_FILE"
+    log_debug "Added from CLI: $clean_key=$val"
+  else
+    log_warn "Skipped invalid manual var: $var"
+  fi
+done
+
+# --------------
+# Output
+# --------------
+# Ensure the output directory exists
+if [ ! -d "$OUTPUT_DIR" ]; then
+  log_info "Creating output directory: $OUTPUT_DIR"
+  if ! mkdir -p "$OUTPUT_DIR"; then
+    log_warn "Failed to create directory '$OUTPUT_DIR'"
+    rm -f "$TMP_FILE"
+    exit 1
+  fi
+fi
+
+if [ -s "$TMP_FILE" ]; then
+  if mv "$TMP_FILE" "$OUTPUT_FILE"; then
+    log_info "Wrote cleaned env vars to $OUTPUT_FILE"
+  else
+    log_warn "Failed to move temp file to $OUTPUT_FILE"
+    rm -f "$TMP_FILE"
+    exit 1
+  fi
+else
+  rm -f "$TMP_FILE"
+  log_warn "No valid env vars found with prefix '$PREFIX'. Skipping output."
+fi