sapenlinea-components 0.13.100 → 0.13.101

package/README.md

@@ -482,7 +482,7 @@ Componente de **paginación** para tablas o listas, con opción de selector de t
 ### 10. `lib-table` (Table)
 
 **Qué hace**
-Componente de **tabla dinámica** con soporte de ordenamiento, acciones por fila, estados con tonos configurables y traducción de estados mediante enum.
+Componente de **tabla dinámica** con soporte de ordenamiento, acciones por fila, filas expandibles, selección múltiple, totales, column groups, estados con tonos configurables y traducción de estados mediante enum.
 
 **Selector:** `lib-table`
 
@@ -495,8 +495,14 @@ Componente de **tabla dinámica** con soporte de ordenamiento, acciones por fila
 - `subColumns: SubColumn[]` – Columnas de las sub-filas expandibles.
 - `subActions: TableAction[] | ((row: TableRow) => TableAction[])` – Acciones por sub-fila.
 - `showSubActions: boolean = false` – Muestra/oculta acciones en sub-filas.
+- `isRowExpandable: (row: TableRow) => boolean = () => false` – Determina si una fila puede expandirse.
+- `expandedChildren: (row: TableRow) => TableRow[] | null = () => null` – Proveedor de sub-filas al expandir.
+- `rowIdKey: string = 'id'` – Propiedad del row usada como identificador para expansión y selección.
+- `showSelection: boolean = false` – Muestra columna de checkboxes para selección múltiple.
+- `showTotals: boolean = false` – Muestra fila de totales (columnas `money` con `totalizable: true`).
+- `columnGroups: ColumnGroup[] = []` – Grupos de columnas adicionales (checkbox, número, icon-button, porcentaje).
 - `statusToneMap: StatusToneMap` – Mapa de estado normalizado → tono visual.
-- `statusEnumMap: Record<string, string>` – Traduce el valor crudo del estado a la etiqueta visible.
+- `statusEnumMap: Record<number | string, string>` – Traduce el valor crudo del estado a la etiqueta visible.
 
 **Tipos de columna (`type`):**
 
@@ -554,9 +560,70 @@ subColumns: SubColumn[] = [
 { key: 'placa', label: 'PLACA', type: 'text', widthProfile: 'fixed', maxWidth: 120 }
 ```
 
-`columnGroups` (anexos/checkbox) mantienen celdas estrechas fijas (~56px) sin configuración adicional.
+**Column groups (`columnGroups`):**
 
-Helpers exportados: `resolveTableColumnLayout`, `getTableMinWidth`, `buildChildGridTemplateColumns`.
+Grupos de columnas adicionales al final de la tabla (anexos, checkboxes, acciones inline). Mantienen celdas estrechas fijas (~56px) sin configuración adicional.
+
+```ts
+export interface ColumnGroup {
+  groupLabel: string;
+  columns: ColumnGroupItem[];
+}
+
+export interface ColumnGroupItem {
+  key: string;
+  label: string;
+  description: string;
+  type?: 'checkbox' | 'number' | 'icon-button' | 'percentage';
+  icon?: string;
+  iconAlternate?: string;
+  iconActiveKey?: string;
+  isIconActive?: (row: TableRow) => boolean;
+  disabledKey?: string;
+  isIconDisabled?: (row: TableRow) => boolean;
+  iconColor?: string;
+  iconAlternateColor?: string;
+  /** Key del row con URL(s) del archivo a visualizar al hacer clic en checkbox marcado */
+  fileUrlKey?: string;
+  /** Key del row para el nombre del archivo en el visor (default: label de la columna) */
+  fileNameKey?: string;
+}
+```
+
+- Checkbox marcado con `fileUrlKey` (o valor string en la celda) abre el visor PDF/imagen vía `PdfViewerService`.
+- Cambios en checkbox emiten `columnGroupChange`.
+
+**Filas expandibles:**
+
+```html
+<lib-table
+  [columns]="columns"
+  [data]="rows"
+  [subColumns]="subColumns"
+  [isRowExpandable]="canExpand"
+  [expandedChildren]="getChildren"
+  rowIdKey="id"
+/>
+```
+
+```ts
+canExpand = (row: TableRow) => !!row.hasChildren;
+getChildren = (row: TableRow) => row.children ?? [];
+```
+
+**Selección múltiple (`showSelection`):**
+
+Activa checkboxes en encabezado y filas. El estado interno (`selectedRows`) se gestiona en el componente; expone métodos `toggleRow`, `toggleAllRows`, `isRowSelected`, `isAllSelected` vía la instancia.
+
+**Fila de totales (`showTotals`):**
+
+Suma automáticamente columnas con `type: 'money'` y `totalizable: true`.
+
+**Menú de acciones:**
+
+El panel contextual se renderiza con `position: fixed` adjunto a `document.body`, se reposiciona en scroll/resize y elige abrir hacia arriba o abajo según el espacio disponible.
+
+Helpers exportados: `resolveTableColumnLayout`, `getTableMinWidth`, `buildChildGridTemplateColumns`, `isMultilineHeaderLabel`, `ColumnWidthProfile`, `ResolvedTableColumnLayout`.
 
 **Iconos en acciones y columnas `icon-button`:**
 
@@ -588,7 +655,8 @@ Propiedades de columna `icon-button`: `icon`, `iconAlternate`, `iconActiveKey`,
 
 - `optionSelected: EventEmitter<{ action: string; row: TableRow }>` – Emite la acción seleccionada y la fila principal.
 - `subOptionSelected: EventEmitter<{ action: string; row: TableRow }>` – Emite la acción seleccionada y la sub-fila.
-- `iconAction: EventEmitter<{ action: string; row: TableRow }>` – Emite al hacer clic en un `icon-button`.
+- `iconAction: EventEmitter<{ action: string; row: TableRow }>` – Emite al hacer clic en un `icon-button` (columnas o column groups).
+- `columnGroupChange: EventEmitter<{ key: string; row: TableRow; value: any }>` – Emite al cambiar un valor en `columnGroups` (p. ej. checkbox).
 
 **Sub-filas con acciones (`subActions` + `showSubActions`):**
 
@@ -954,7 +1022,7 @@ Carrusel horizontal de tarjetas de dispositivo con estado (batería, geocerca, c
 ### 23. `lib-title-filters` (TitleFilters)
 
 **Qué hace**
-Encabezado de sección con título, botones de acción configurables y grupo de filtros (texto, número, select, fecha, hora).
+Encabezado de sección con título, botones de acción configurables y grupo de filtros (texto, número, select, fecha, datetime, hora).
 
 **Selector:** `lib-title-filters`
 
@@ -963,16 +1031,18 @@ Encabezado de sección con título, botones de acción configurables y grupo de
 | Valor | Descripción |
 |---|---|
 | `'toggle'` | Botón "Filtros" que muestra/oculta el panel de filtros (default) |
-| `'action'` | Botón "Ir al Mapa" — fijo, en producción, no modificar |
-| `'click'` | Botón primario reutilizable con ícono y texto configurables |
+| `'action'` | Botón "Ir al Mapa" con ícono SVG fijo; emite `filterButtonClicked` |
+| `'click'` | Botón primario (`lib-button`) con ícono y texto configurables; emite `filterButtonClicked` |
+| `'clickRight'` | Igual que `click`, pero el botón primario se renderiza al final de la fila (junto a secundario/exportar) |
+| `'none'` | No muestra botón de acción/filtros en la barra del título |
 
 **Inputs:**
 
 - `title: string = 'Listado'`
 - `filtersConfig: TitleFilterConfig[]`
-- `buttonMode: 'toggle' | 'action' | 'click' = 'toggle'`
-- `clickButtonLabel: string = 'Acción'` — texto del botón en modo `click`
-- `clickButtonIcon: string = ''` — clase CSS del ícono en modo `click`
+- `buttonMode: 'toggle' | 'action' | 'click' | 'clickRight' | 'none' = 'toggle'`
+- `clickButtonLabel: string = 'Acción'` — texto del botón en modo `click` / `clickRight`
+- `clickButtonIcon: string = ''` — clase CSS del ícono en modo `click` / `clickRight`
 - `alwaysShowFilters: boolean = false` — muestra los filtros permanentemente sin necesidad de toggle
 - `showSecondaryButton: boolean = false` — muestra un botón secundario (ej. "Exportar PDF")
 - `secondaryButtonLabel: string = 'Exportar PDF'`
@@ -981,7 +1051,7 @@ Encabezado de sección con título, botones de acción configurables y grupo de
 - `exportButtonLabel: string = 'Exportar CSV'`
 - `exportButtonIcon: string = 'icon-export'`
 - `showButtonBack: boolean = false`
-- `initialFilters: Record<string, string | number | Date | null> = {}` — estado previo de filtros para restaurar al volver a la pantalla. La estructura es la misma que emite `filtersChange`. Soporta todos los tipos de filtro: texto, número, select (por value) y fecha.
+- `initialFilters: Record<string, string | number | Date | null> = {}` — estado previo de filtros para restaurar al volver a la pantalla. La estructura es la misma que emite `filtersChange`. Soporta todos los tipos de filtro: texto, número, select (por value), fecha, datetime y hora.
 
 > Los botones secundario y de exportación se agrupan automáticamente al final de la fila del título.
 
@@ -1016,7 +1086,7 @@ onFiltersChange(filters: Record<string, string | number | Date | null>) {
 - `filtersChange: Record<string, string | number | Date | null>`
 - `applyFilters: void`
 - `clearFilters: void`
-- `filterButtonClicked: void` — emitido al hacer clic en el botón `click` o `action`
+- `filterButtonClicked: void` — emitido al hacer clic en el botón `click`, `clickRight` o `action`
 - `secondaryButtonClicked: void`
 - `exportButtonClicked: void`
 - `clickButtonBack: void`
@@ -1053,11 +1123,37 @@ onFiltersChange(filters: Record<string, string | number | Date | null>) {
 
 ```ts
 export interface TitleFilterConfig {
-  type: 'text' | 'number' | 'select' | 'date' | 'datetime' | 'time';
+  type: FilterType; // 'text' | 'number' | 'select' | 'date' | 'datetime' | 'time'
   filters: FilterItem[];
 }
 ```
 
+Cada entrada de `filtersConfig` renderiza un componente de filtro según su `type`:
+
+| `type` | Componente interno |
+|---|---|
+| `text` | `lib-input-text-filter` |
+| `number` | `lib-input-number-filter` |
+| `select` | `lib-input-select-filter` |
+| `date` / `datetime` | `lib-date-time-filter` |
+| `time` | `lib-input-time-filter` |
+
+**Navegación con Enter:** al presionar Enter en un filtro, el foco avanza al siguiente campo visible; en el último filtro se dispara `applyFilters`.
+
+**Ejemplo — modo `clickRight` con botón de acción alineado a la derecha:**
+
+```html
+<lib-title-filters
+  title="Reportes"
+  buttonMode="clickRight"
+  clickButtonLabel="Nuevo reporte"
+  clickButtonIcon="icon-add"
+  [showSecondaryButton]="true"
+  (filterButtonClicked)="onNuevoReporte()"
+  (secondaryButtonClicked)="onExportPDF()"
+/>
+```
+
 ---
 
 ### 24. `lib-notification-modal` (NotificationModal)
@@ -2341,3 +2437,293 @@ readonly brandColors = ['#596300', '#006D2F', '#CF0707', ...];
 ```
 
 ---
+
+### 49. `lib-sidebar` (Sidebar) y `SidebarService`
+
+**Qué hace**  
+Barra lateral reutilizable de tres niveles (módulo → submódulo → aplicativo). Recibe ítems por `@Input`, delega navegación y acciones al contenedor, y es compatible con `ModuleData` de `lib-module-card-list`.
+
+**Selector:** `lib-sidebar`
+
+> **Documentación detallada:** [`src/lib/components/sidebar/README.md`](./src/lib/components/sidebar/README.md)
+
+**Inputs principales:**
+
+| Input | Default | Descripción |
+|---|---|---|
+| `menuItems` | `[]` | Menú principal |
+| `userMenuItems` | `[]` | Ítems inferiores (configuración, logout, etc.) |
+| `expanded` | `false` | Two-way: estado expandido/colapsado |
+| `autoNavigate` | `false` | Navega con `Router` internamente |
+| `closeOnNavigate` | `true` | Colapsa al navegar |
+| `closeOnOutsideClick` | `true` | Colapsa al clic fuera |
+| `closeOnEscape` | `true` | Colapsa con Escape |
+| `hoverExpand` | `true` | Expansión temporal al mantener hover |
+| `hoverExpandDelay` | `1000` | Retardo en ms antes de expandir por hover |
+| `topOffset` | `'75px'` | Distancia desde el borde superior |
+| `expandedWidth` | `'280px'` | Ancho expandido |
+| `collapsedWidth` | `'70px'` | Ancho colapsado |
+| `dangerAction` | `'logout'` | `action` del menú inferior pintado en rojo |
+| `iconColor` | `'#454733'` | Color de iconos |
+
+**Outputs:**
+
+| Output | Descripción |
+|---|---|
+| `navigate` | Clic en ítem con `route` |
+| `userAction` | Clic en ítem del menú inferior con `action` |
+| `itemClick` | Cualquier clic (auditoría / analytics) |
+
+**Utilidades exportadas:**
+
+```ts
+import {
+  mapModuleDataToSidebarItems,
+  markActiveSidebarItems,
+  filterVisibleSidebarItems,
+  getInitialOpenState,
+  submoduleOpenKey,
+  SidebarMenuItem,
+  SidebarRouteResolver,
+} from 'sapenlinea-components';
+```
+
+**`SidebarService`** — estado compartido opcional (solo expandido/colapsado):
+
+```ts
+readonly sidebar = inject(SidebarService);
+sidebar.toggleSidebar();
+sidebar.sidebarExpanded();
+```
+
+**Ejemplo mínimo:**
+
+```html
+<lib-sidebar
+  [menuItems]="menuItems()"
+  [userMenuItems]="userMenuItems"
+  [(expanded)]="sidebarExpanded"
+  [topOffset]="'75px'"
+  (navigate)="onNavigate($event)"
+  (userAction)="onUserAction($event)"
+/>
+```
+
+---
+
+### 50. `lib-header` (Header)
+
+**Qué hace**  
+Encabezado de aplicación con menú hamburguesa, título activo, acción contextual configurable por microfrontend, campana de notificaciones y menú de usuario. Todas las entradas son opcionales para uso como custom element, module federation o dentro del monolito.
+
+**Selector:** `lib-header`
+
+**Interfaz:**
+
+```ts
+export interface HeaderAction {
+  /** Texto del botón, p. ej. "Nuevo Usuario". */
+  label: string;
+  /** Ruta interna; si se define, el header emite `navigateTo`. */
+  route?: string;
+  /** Nombre del CustomEvent a despachar en `window` (para abrir modales en MFs remotos). */
+  customEvent?: string;
+}
+```
+
+**Inputs:**
+
+| Input | Default | Descripción |
+|---|---|---|
+| `isExpanded` | `false` | Estado del sidebar (cambia ícono ☰ / ✕) |
+| `activeTitle` | `''` | Título de la pantalla activa |
+| `action` | `null` | Acción contextual del botón `+` (recomendado). Ver `HeaderAction` |
+| `mfId` | `''` | Identificador del MF. **Deprecated** como driver de la acción; usar `[action]` |
+| `isMfFailed` | `false` | Oculta la acción si el MF falló al cargar |
+| `userRole` | `'Administrador'` | Rol mostrado en el menú de usuario |
+| `notifications` | `[]` | Lista de notificaciones (`LibNotification[]`) |
+| `notificationsLoading` | `false` | Indica carga de página de notificaciones |
+| `notificationsHasMore` | `false` | Indica si hay más notificaciones por cargar |
+| `unreadCount` | `null` | Total real de no leídas (prevalece sobre conteo derivado) |
+
+**Outputs:**
+
+| Output | Descripción |
+|---|---|
+| `navigateTo` | Navegación a ruta (p. ej. `/home`, `/child/infractions/register`) |
+| `menuClick` | Clic en botón hamburguesa |
+| `profileClick` | Clic en perfil de usuario |
+| `logoutClick` | Clic en cerrar sesión |
+| `actionClick` | Clic en acción contextual (emite `mfId`) |
+| `markAllRead` | Marcar todas las notificaciones como leídas |
+| `notificationClick` | Clic en una notificación |
+| `loadMoreNotifications` | Solicitud de siguiente página de notificaciones |
+
+**Acción contextual (`[action]`)**
+
+El botón `+` se configura desde el **shell host** sin modificar la librería. Al hacer clic:
+
+1. Si `action.route` está definido → emite `navigateTo` con esa ruta.
+2. Si `action.customEvent` está definido → despacha `window.dispatchEvent(new CustomEvent(...))` para que el MF remoto abra un modal.
+3. Siempre emite `actionClick` con el valor de `mfId`.
+
+**Prioridad:** `[action]` prevalece sobre el mapa legacy interno por `mfId`. El mapa legacy se mantiene solo por compatibilidad con integraciones existentes.
+
+**Ejemplo — navegación por ruta:**
+
+```html
+<lib-header
+  [activeTitle]="pageTitle()"
+  [mfId]="currentMfId()"
+  [action]="{ label: 'Nueva Infracción', route: '/child/infractions/register' }"
+  (navigateTo)="router.navigateByUrl($event)"
+/>
+```
+
+**Ejemplo — abrir modal en MF remoto (CustomEvent):**
+
+Configuración en el shell:
+
+```html
+<lib-header
+  [activeTitle]="'Usuarios'"
+  [mfId]="'users'"
+  [action]="{ label: 'Nuevo Usuario', customEvent: 'mf-action-user-nuevo' }"
+/>
+```
+
+Escucha en el MF hijo:
+
+```ts
+@HostListener('window:mf-action-user-nuevo')
+onNuevoDesdeShell(): void {
+  this.abrirModalNuevoUsuario();
+}
+```
+
+**Ejemplo — config centralizada en el shell:**
+
+```ts
+import { HeaderAction } from 'sapenlinea-components';
+
+const HEADER_ACTIONS: Record<string, HeaderAction> = {
+  users: { label: 'Nuevo Usuario', customEvent: 'mf-action-user-nuevo' },
+  infractions: { label: 'Nueva Infracción', route: '/child/infractions/register' },
+  paymentAgreementParameters: { label: 'Nuevo Parámetro', customEvent: 'mf-action-register-parameter' },
+};
+
+headerAction = computed(() => HEADER_ACTIONS[this.currentMfId()] ?? null);
+```
+
+```html
+<lib-header
+  [isExpanded]="sidebarExpanded()"
+  [activeTitle]="pageTitle()"
+  [mfId]="currentMfId()"
+  [action]="headerAction()"
+  [notifications]="notifications()"
+  [unreadCount]="unreadTotal()"
+  [notificationsHasMore]="hasMore()"
+  (menuClick)="toggleSidebar()"
+  (navigateTo)="router.navigateByUrl($event)"
+  (logoutClick)="onLogout()"
+  (notificationClick)="onNotification($event)"
+  (loadMoreNotifications)="loadNextPage()"
+/>
+```
+
+**Compatibilidad legacy (`mfId` sin `[action]`)**
+
+Si no se pasa `[action]`, el header resuelve la acción desde mapas internos según `mfId`:
+
+| `mfId` | Comportamiento |
+|---|---|
+| `infractions` | Navega a `/child/infractions/register` |
+| `paymentAgreements` | Navega a `/child/paymentAgreements/register` |
+| `trainingCourses-programar` | Navega a `/child/trainingCourses/programacion` |
+| `paymentAgreementParameters` | Despacha `mf-action-register-parameter` |
+| `trainingCourses-administrar` | Despacha `mf-action-training-course-nuevo` |
+| `trainingCourses-catalogos-cia` | Despacha `mf-action-catalogo-cia-nuevo` |
+| `trainingCourses-catalogos-salones` | Despacha `mf-action-catalogo-salon-nuevo` |
+| `trainingCourses-catalogos-instructores` | Despacha `mf-action-catalogo-instructor-nuevo` |
+
+Para nuevos MFs, usar siempre `[action]` desde el shell.
+
+---
+
+### 51. `lib-notification-center` (NotificationCenter)
+
+**Qué hace**  
+Panel desplegable de notificaciones con filtro por categoría, scroll infinito y acción "Marcar todas como leídas". Se usa internamente en `lib-header` pero también puede consumirse de forma independiente.
+
+**Selector:** `lib-notification-center`
+
+**Interfaz:**
+
+```ts
+export interface LibNotification {
+  id: string;
+  title: string;
+  description: string;
+  category: string;
+  timeAgo: string;
+  isRead: boolean;
+}
+```
+
+**Inputs:**
+
+| Input | Default | Descripción |
+|---|---|---|
+| `notifications` | `[]` | Lista de notificaciones |
+| `isOpen` | `false` | Controla visibilidad del panel |
+| `loading` | `false` | Indica carga de página en curso |
+| `hasMore` | `false` | Indica si quedan más registros por cargar |
+
+**Outputs:**
+
+| Output | Descripción |
+|---|---|
+| `markAllRead` | Usuario solicita marcar todas como leídas |
+| `notificationClick` | Clic en una notificación |
+| `close` | Cierre del panel |
+| `loadMore` | El sentinel al final de la lista entró en viewport (scroll infinito) |
+
+**Comportamiento:**
+
+- Pestañas de categoría generadas automáticamente desde `category` de cada notificación, más "Todas".
+- Colores e iconos por categoría inferidos por palabras clave (`ACUERDO`, `FINAN`, `INFRAC`, `SISTEMA`).
+- `IntersectionObserver` en un sentinel al final de la lista dispara `loadMore` cuando `hasMore` es `true` y no hay carga en curso.
+
+---
+
+### 52. `lib-bell-with-badge` (BellWithBadge)
+
+**Qué hace**  
+Icono de campana con badge numérico de notificaciones no leídas. Componente atómico usado por `lib-header`.
+
+**Selector:** `lib-bell-with-badge`
+
+**Inputs:**
+
+| Input | Default | Descripción |
+|---|---|---|
+| `count` | `0` | Número a mostrar en el badge (oculto si es 0) |
+| `active` | `false` | Estado visual activo (panel abierto) |
+| `ariaLabel` | `'Notificaciones'` | Etiqueta de accesibilidad |
+
+**Outputs:**
+
+- `bellClick: void` — emitido al hacer clic en la campana.
+
+**Ejemplo:**
+
+```html
+<lib-bell-with-badge
+  [count]="unreadCount()"
+  [active]="panelOpen()"
+  (bellClick)="togglePanel()"
+/>
+```
+
+---