sapenlinea-components 0.11.92 → 0.11.94

package/README.md

@@ -1,6 +1,6 @@
 # Componentes de la librería `sapenlinea-components`
 
-Esta librería incluye una colección de componentes reutilizables para formularios, tablas y filtros.
+Esta librería incluye una colección de componentes reutilizables para formularios, tablas, filtros, dashboards, gestión de menús/sidebar y más.
 A continuación se documenta **qué hace cada componente** y **cómo se utiliza**.
 
 > Nota: todos los componentes son _standalone_ de Angular, por lo que se importan directamente en el `imports` del componente donde se usen.
@@ -1851,3 +1851,307 @@ infracciones: GeoPoint[] = [
   }
 ];
 ```
+
+---
+
+### 45. `lib-rol-card` (RolCard)
+
+**Qué hace**  
+Tarjeta resumen de un **rol de usuario**, con nombre, descripción, color identificador, contador de usuarios asignados y accesos rápidos a editar o gestionar permisos.
+
+**Selector:** `lib-rol-card`
+
+**Inputs:**
+
+| Input | Tipo | Default | Descripción |
+|---|---|---|---|
+| `roleName` | `string` | (requerido) | Nombre del rol |
+| `description` | `string` | `''` | Descripción breve |
+| `color` | `string` | `'#596300'` | Color de acento (borde / badge) |
+| `userCount` | `number` | `0` | Cantidad de usuarios con ese rol |
+
+**Outputs:**
+
+- `edit: void` – Al pulsar editar rol.
+- `permissions: void` – Al pulsar gestionar permisos.
+
+**Ejemplo de uso:**
+
+```html
+<lib-rol-card
+  [roleName]="'Administrador'"
+  [description]="'Acceso completo al sistema'"
+  [color]="'#596300'"
+  [userCount]="12"
+  (edit)="onEditRol()"
+  (permissions)="onManagePermissions()" />
+```
+
+---
+
+### 46. `lib-module-card` y `lib-module-card-list` (ModuleCard / ModuleCardList)
+
+**Qué hacen**  
+Componentes para **administrar la estructura del sidebar/menú** de la aplicación: módulos, submódulos y aplicativos (pantallas/rutas). Permiten expandir/colapsar, mostrar/ocultar, reordenar con animación FLIP y gestionar acciones (permisos granulares) por aplicativo.
+
+Pensados como **pieza de UI** dentro de un módulo de roles y permisos: el componente maneja la interacción visual; la persistencia, reglas de negocio y autorización las implementa el contenedor.
+
+> **Guía de implementación para roles y permisos:** ver [`GUIA-MODULE-CARD-LIST.md`](./src/lib/components/module-card/GUIA-MODULE-CARD-LIST.md).
+
+**Selectores:** `lib-module-card`, `lib-module-card-list`
+
+#### Jerarquía de datos
+
+```
+ModuleData
+├── submodules[]          → Submódulos del menú
+│   └── aplicativos[]     → Aplicativos anidados en el submódulo
+├── aplicativos[]         → Aplicativos directos del módulo (sin submódulo)
+└── childOrder?[]         → Orden mixto submódulos + aplicativos directos
+```
+
+**Interfaces principales:**
+
+```ts
+export interface ModuleCardAction {
+  key: string;
+  label: string;
+}
+
+export interface ModuleApplicativo {
+  id: string | number;
+  name: string;
+  icon?: string;           // SVG inline como string
+  visible: boolean;
+  actions: ModuleCardAction[];
+}
+
+export interface ModuleSubmodule {
+  id: string | number;
+  name: string;
+  icon?: string;
+  visible: boolean;
+  aplicativos: ModuleApplicativo[];
+}
+
+export type ModuleChildType = 'submodule' | 'aplicativo';
+
+export interface ModuleChildRef {
+  type: ModuleChildType;
+  id: string | number;
+}
+
+export interface ModuleData {
+  id: string | number;
+  name: string;
+  icon?: string;
+  visible: boolean;
+  submodules: ModuleSubmodule[];
+  aplicativos: ModuleApplicativo[];
+  /** Orden unificado de hijos directos del módulo (submódulos + aplicativos) */
+  childOrder?: ModuleChildRef[];
+}
+```
+
+#### Orden unificado (`childOrder`)
+
+Dentro de cada módulo, **submódulos y aplicativos directos comparten una sola lista ordenable**. Un aplicativo directo puede quedar antes, entre o después de submódulos.
+
+| Situación | Comportamiento |
+|---|---|
+| Sin `childOrder` | Orden por defecto: todos los submódulos primero, luego aplicativos directos |
+| Con `childOrder` | Se respeta el orden definido; ítems nuevos se agregan al final si faltan en el array |
+| Reordenar ↑/↓ | Actualiza `childOrder` y anima con FLIP |
+
+**Helpers exportados:**
+
+```ts
+import { getModuleChildOrder, resolveModuleChildren } from 'sapenlinea-components';
+
+// Obtiene el orden efectivo (default o childOrder normalizado)
+const order = getModuleChildOrder(module);
+
+// Resuelve refs → objetos completos para renderizar
+const children = resolveModuleChildren(order, module.submodules, module.aplicativos);
+```
+
+#### `lib-module-card-list` — lista de módulos
+
+Orquesta varias tarjetas de módulo, persiste cambios en el modelo y aplica animación FLIP al reordenar módulos.
+
+**Inputs / model:**
+
+- `[(modules)]="ModuleData[]"` – Lista de módulos (two-way binding con `model`).
+
+**Outputs:**
+
+| Output | Descripción |
+|---|---|
+| `moduleEvent` | Eventos del encabezado del módulo |
+| `submoduleEvent` | Eventos de submódulos |
+| `applicativoEvent` | Eventos de aplicativos |
+| *(interno)* | Actualiza `modules` y `childOrder` automáticamente en move/visibleChange |
+
+**Ejemplo completo:**
+
+```html
+<lib-module-card-list
+  [modules]="menuModules()"
+  (modulesChange)="menuModules.set($event)"
+  (moduleEvent)="onModuleEvent($event)"
+  (submoduleEvent)="onSubmoduleEvent($event)"
+  (applicativoEvent)="onApplicativoEvent($event)" />
+```
+
+```ts
+menuModules = signal<ModuleData[]>([
+  {
+    id: 'mod1',
+    name: 'Administración',
+    icon: '<svg>...</svg>',
+    visible: true,
+    submodules: [
+      {
+        id: 'sub1',
+        name: 'Usuarios',
+        visible: true,
+        aplicativos: [
+          { id: 'app1', name: 'Crear Usuario', visible: true, actions: [{ key: 'bulk', label: 'Creación masiva' }] },
+        ],
+      },
+    ],
+    aplicativos: [
+      { id: 'app2', name: 'Panel General', visible: true, actions: [] },
+    ],
+    childOrder: [
+      { type: 'aplicativo', id: 'app2' },   // aplicativo directo primero
+      { type: 'submodule', id: 'sub1' },
+    ],
+  },
+]);
+```
+
+#### `lib-module-card` — tarjeta individual
+
+Usar directamente cuando solo se necesita un módulo, o dejar que `lib-module-card-list` lo renderice internamente.
+
+**Inputs:**
+
+| Input | Tipo | Descripción |
+|---|---|---|
+| `moduleId` | `string \| number` | Id del módulo |
+| `moduleName` | `string` | Nombre visible |
+| `moduleIcon` | `string` | SVG inline (opcional) |
+| `visible` | `boolean` | Visible en sidebar |
+| `submodules` | `ModuleSubmodule[]` | Submódulos |
+| `aplicativos` | `ModuleApplicativo[]` | Aplicativos directos |
+| `childOrder` | `ModuleChildRef[]` | Orden unificado (opcional) |
+| `isFirst` | `boolean` | Deshabilita ↑ si es el primer módulo de la lista |
+| `isLast` | `boolean` | Deshabilita ↓ si es el último módulo de la lista |
+
+**Outputs:**
+
+| Output | Descripción |
+|---|---|
+| `moduleEvent` | Acciones del encabezado del módulo |
+| `submoduleEvent` | Acciones de submódulos |
+| `applicativoEvent` | Acciones de aplicativos |
+| `childOrderChange` | Nuevo `childOrder` tras reordenar hijos |
+
+#### Eventos
+
+**`ModuleEvent`** — encabezado del módulo:
+
+```ts
+type: 'moveUp' | 'moveDown' | 'edit' | 'delete' | 'visibleChange'
+      | 'addApplicativo' | 'addSubmodule';
+moduleId: string | number;
+data?: any;  // En moveUp/moveDown: índice nuevo en la lista de módulos
+```
+
+**`SubmoduleEvent`** — submódulo:
+
+```ts
+type: 'moveUp' | 'moveDown' | 'edit' | 'delete' | 'visibleChange';
+submoduleId: string | number;
+moduleId: string | number;
+data?: any;  // En moveUp/moveDown: índice nuevo en childOrder unificado
+```
+
+**`ApplicativoEvent`** — aplicativo:
+
+```ts
+type: 'moveUp' | 'moveDown' | 'edit' | 'delete' | 'visibleChange'
+      | 'addAction' | 'removeAction';
+moduleId: string | number;       // Siempre presente
+applicativoId: string | number;
+submoduleId?: string | number | null;
+data?: any;
+```
+
+**Interpretación de `submoduleId` en aplicativos:**
+
+| Valor | Ubicación del aplicativo |
+|---|---|
+| `null` | `module.aplicativos[]` (directo del módulo) |
+| `'sub1'` (id) | `module.submodules[].aplicativos[]` |
+
+**Ejemplo de resolución en el contenedor:**
+
+```ts
+onApplicativoEvent(event: ApplicativoEvent) {
+  const module = this.modules().find(m => m.id === event.moduleId);
+  if (!module) return;
+
+  const apps = event.submoduleId == null
+    ? module.aplicativos
+    : module.submodules.find(s => s.id === event.submoduleId)?.aplicativos;
+
+  const app = apps?.find(a => a.id === event.applicativoId);
+
+  if (event.type === 'addAction') {
+    // Abrir modal para agregar permiso/acción a `app`
+  }
+  if (event.type === 'moveDown') {
+    // event.data → nueva posición (índice en childOrder o en lista de apps del submódulo)
+  }
+}
+```
+
+**Valores de `data` en reordenamiento:**
+
+| Evento | `data` en moveUp / moveDown |
+|---|---|
+| `ModuleEvent` | Índice nuevo del módulo en la lista |
+| `SubmoduleEvent` | Índice nuevo en `childOrder` (lista unificada del módulo) |
+| `ApplicativoEvent` (directo) | Índice nuevo en `childOrder` |
+| `ApplicativoEvent` (en submódulo) | Índice nuevo dentro de `sub.aplicativos[]` |
+
+#### Comportamiento de botones ↑ / ↓
+
+Los botones de mover se **deshabilitan visualmente** (sin hover activo) cuando no aplican:
+
+- Primer ítem de su lista → ↑ deshabilitado
+- Último ítem de su lista → ↓ deshabilitado
+
+Aplica a módulos, hijos unificados del módulo y aplicativos dentro de submódulos.
+
+#### Acciones por aplicativo (permisos granulares)
+
+Al expandir un aplicativo se muestran **chips de acciones** (`ModuleCardAction`). Cada chip representa un permiso o acción asociada (ej. "Exportar Excel", "Creación masiva").
+
+- `addAction` – solicita agregar una acción (`data` no incluido; abrir selector en el padre).
+- `removeAction` – `data` contiene el `key` de la acción a quitar.
+
+#### Animación FLIP
+
+Al reordenar módulos (`lib-module-card-list`) o hijos de un módulo (`lib-module-card`), los ítems se animan con transición suave y sombra durante el movimiento.
+
+#### Notas de integración
+
+1. **Persistencia:** escuchar eventos y/o `childOrderChange` / `modulesChange` para guardar en API.
+2. **Alta de ítems:** al crear submódulo o aplicativo, agregar también su entrada en `childOrder` si ya existe uno definido.
+3. **Iconos:** pasar SVG como string en `icon`; el componente lo sanitiza con `DomSanitizer`.
+4. **Separación de responsabilidades:** `visible` controla visibilidad en menú; la autorización real por rol la define el módulo contenedor.
+
+---