master-page-angular

Librería Angular que provee componentes de layout maestro (header, footer, menú lateral) con autenticación OIDC para aplicaciones SISPRO.

📦 Instalación

npm install master-page-angular

🛠️ Guía de implementación paso a paso

1. Instalar dependencias requeridas

La librería requiere las siguientes dependencias en tu proyecto:

npm install bootstrap

Peer dependencies requeridas: | Paquete | Versión mínima | |---|---| | @angular/common | >= 16.0.0 | | @angular/core | >= 16.0.0 | | @angular/router | >= 16.0.0 | | oidc-client-ts | >= 3.0.0 | | bootstrap | >= 5.0.0 (opcional pero recomendado) |

2. Incluir Bootstrap en el proyecto

Opción A — En angular.json (recomendado)

"styles": [
  "node_modules/bootstrap/dist/css/bootstrap.min.css",
  "src/styles.css"
],
"scripts": [
  "node_modules/bootstrap/dist/js/bootstrap.bundle.min.js"
]

Opción B — En src/styles.css

@import 'bootstrap/dist/css/bootstrap.min.css';

3. Configurar la librería en tu aplicación

Aplicaciones Standalone (Angular 16+)

En src/app/app.config.ts:

import { ApplicationConfig } from '@angular/core';
import { provideRouter } from '@angular/router';
import { provideMasterPage } from 'master-page-angular';
import { routes } from './app.routes';

export const appConfig: ApplicationConfig = {
  providers: [
    provideRouter(routes),
    provideMasterPage({
      oidc: {
        authority: environment.authority,
        clientId: environment.clientId,
        clientSecret: environment.clientSecret
      },
      appTitle: 'SISPRO - Mi Aplicación',
      assetsBasePath: 'assets/master-page/',
      enableFetchInterceptor: true,
    })
  ],
};

Aplicaciones con NgModule

En src/app/app.module.ts:

import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { MasterPageModule } from 'master-page-angular';
import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,
    MasterPageModule.forRoot({
      oidc: {
        authority: environment.authority,
        clientId: environment.clientId,
        clientSecret: environment.clientSecret
      },
      appTitle: 'SISPRO - Mi Aplicación',
      assetsBasePath: 'assets/master-page/',
      enableFetchInterceptor: true,
    })
  ],
  bootstrap: [AppComponent],
})
export class AppModule {}

4. Usar el componente en tu plantilla raíz

En src/app/app.component.ts, importa el componente (solo para apps standalone):

import { Component } from '@angular/core';
import { RouterOutlet } from '@angular/router';
import { MasterPageModule } from 'master-page-angular';

@Component({
  selector: 'app-root',
  standalone: true,
  imports: [RouterOutlet, MasterPageModule],
  templateUrl: './app.component.html',
})
export class AppComponent {}

En src/app/app.component.html:

<mp-master-page>
  <router-outlet></router-outlet>
</mp-master-page>

5. Configurar las URIs de redirección en el servidor de identidad

Registra las siguientes URIs en tu servidor OIDC (Keycloak, IdentityServer, etc.):

| Tipo | URI | |---|---| | Redirect URI (login) | https://tu-app.com?op=2 | | Post-logout Redirect URI | https://tu-app.com?op=1 |

En desarrollo local serían: http://localhost:4200?op=2 y http://localhost:4200?op=1

🧩 Uso del componente principal

<mp-master-page>
  <!-- Tu contenido de aplicación aquí -->
  <router-outlet></router-outlet>
</mp-master-page>

⚙️ Opciones de configuración (MasterPageConfig)

| Propiedad | Tipo | Requerido | Descripción | |--------------------------|--------------|-----------|------------------------------------------------------------------------------| | oidc | OidcConfig | ✅ | Configuración de autenticación OIDC | | appTitle | string | ❌ | Título de la aplicación mostrado en el header | | assetsBasePath | string | ❌ | Ruta base para los assets (imágenes, etc.) | | enableFetchInterceptor | boolean | ❌ | Habilita el interceptor global de fetch para inyección automática de token | | registerUrl | string | ❌ | URL de registro de usuarios |

OidcConfig

| Propiedad | Tipo | Requerido | Por defecto | Descripción | |-------------------------|----------|-----------|------------------------------------------------|------------------------------------------------| | authority | string | ✅ | — | URL del servidor de identidad | | clientId | string | ✅ | — | ID del cliente OAuth | | clientSecret | string | ❌ | — | Secreto del cliente (clientes confidenciales) | | redirectUri | string | ❌ | window.location.origin + '?op=2' | URI de redirección post-login | | postLogoutRedirectUri | string | ❌ | window.location.origin + '?op=1' | URI de redirección post-logout | | scope | string | ❌ | openid profile email roles offline_access | Scopes OAuth | | responseType | string | ❌ | code | Tipo de respuesta OAuth |

🧱 Componentes exportados

<mp-master-page>

Componente contenedor principal. Incluye header, footer y menú lateral. Usa <ng-content> para proyectar el contenido de la aplicación.

<mp-header>

Barra de navegación superior fija con:

• Logo y título de la aplicación
• Botón de toggle del menú lateral (cuando el usuario está autenticado)
• Menú de usuario con opciones de configuración y cierre de sesión
• Botones de Ingresar y Registrarse (cuando no está autenticado)

Output: | Evento | Descripción | |--------------|----------------------------------------------| | menuToggle | Emitido al hacer clic en el toggle del menú |

<mp-footer>

Pie de página con información institucional de SISPRO:

• Logos institucionales
• Dirección física
• Información de contacto y teléfonos
• Correo de notificaciones judiciales
• Enlace a términos y condiciones

<mp-menu>

Menú lateral deslizante con soporte para ítems anidados (hasta 3 niveles). Los ítems se cargan automáticamente desde el endpoint /connect/userinfo del servidor de identidad.

Input: | Propiedad | Tipo | Descripción | |-----------|-----------|----------------------------------| | isOpen | boolean | Controla si el menú está visible |

🔐 Servicio de autenticación (AuthService)

import { AuthService } from 'master-page-angular';

@Component({ ... })
export class MyComponent {
  constructor(private authService: AuthService) {}
}

Observables

| Observable | Tipo | Descripción | |--------------------|--------------------------------|-------------------------------------------| | isAuthenticated$ | Observable<boolean> | Estado de autenticación del usuario | | userProfile$ | Observable<UserProfile> | Perfil del usuario autenticado | | menuItems$ | Observable<MenuItemConfig[]> | Ítems de menú autorizados | | isLoading$ | Observable<boolean> | Estado de carga durante la inicialización |

Métodos

| Método | Descripción | |-----------------------------|-----------------------------------------------------------| | login() | Redirige al servidor de identidad para iniciar sesión | | logout() | Cierra la sesión y redirige | | openAccountSettings() | Navega a la gestión de cuenta en el servidor de identidad | | getAccessToken() | Retorna el access token actual (async) | | getConfig() | Retorna la configuración actual | | destroyFetchInterceptor() | Elimina el interceptor global de fetch |

🔄 Interceptor de Fetch

Cuando enableFetchInterceptor está habilitado (por defecto: true), la librería instala un interceptor global sobre window.fetch que:

1. Inyecta automáticamente el header Authorization: Bearer <token> en todas las peticiones que no sean al servidor de identidad.
2. Renueva silenciosamente el token cuando recibe una respuesta 401.
3. Redirige al logout si la renovación silenciosa falla.

📐 Modelos / Interfaces

// Perfil del usuario autenticado
interface UserProfile {
  firstName: string;
  middleName: string;
  lastName: string;
  secondLastName: string;
  enterpriseName: string;
  displayName: string;   // Calculado automáticamente
  email?: string;
  accessToken: string;
  rawClaims: Record<string, unknown>;
}

// Ítem de menú (recursivo para submenús)
interface MenuItemConfig {
  nombre: string;
  url?: string;
  hijos?: MenuItemConfig[];
}

🏗️ Compilar la librería

npm run build

El artefacto se genera en dist/master-page-angular/.

Publicar en npm

npm publish

El script prepublishOnly ejecuta el build automáticamente antes de publicar.

📁 Estructura del proyecto

master-page-angular/
├── src/
│   ├── assets/
│   │   └── img/
│   │       ├── logo.svg
│   │       ├── logo_gov.co.png
│   │       └── colombia.png
│   ├── components/
│   │   ├── header/
│   │   │   └── header.component.ts
│   │   ├── footer/
│   │   │   └── footer.component.ts
│   │   ├── menu/
│   │   │   └── menu.component.ts
│   │   └── master-page/
│   │       └── master-page.component.ts
│   ├── models/
│   │   └── master-page.models.ts
│   ├── services/
│   │   └── auth.service.ts
│   ├── master-page.module.ts
│   └── public-api.ts
├── ng-package.json
├── package.json
└── tsconfig.json