🧰 AlpuraColumnToggleMenuComponent – Guía de uso

Este documento explica cómo utilizar el componente AlpuraColumnToggleMenuComponent para agregar un menú de visibilidad de columnas a una tabla de Angular Material (mat-table).

---

🏗 Estructura General

Esta implementación se integra con mat-table para ofrecer una experiencia de tabla dinámica donde el usuario puede seleccionar qué columnas mostrar u ocultar.

El componente AlpuraColumnToggleMenuComponent renderiza un menú con checkboxes que controla la visibilidad de las columnas definidas.

---

📁 Importaciones necesarias

En tu componente, importa AlpuraColumnToggleMenuComponent y las interfaces necesarias. Asegúrate de tener MatTableModule y otros módulos de Angular Material que uses.

import { CommonModule } from "@angular/common";
import { Component } from "@angular/core";
import { MatTableModule } from "@angular/material/table";
// ... otros imports de material

// Importaciones de la librería @alpura/commons
import {
  AlpuraColumnToggleMenuComponent,
  IAlpuraColumnToggleMenuConfig,
} from '@alpura/commons';

---

💻 Uso en el Componente (TypeScript)

1. Definir la configuración de las columnas: Crea un arreglo de objetos que implementen la interfaz IAlpuraColumnToggleMenuConfig. Este arreglo será la fuente de verdad para todas las columnas y su estado de visibilidad.

2. Gestionar las columnas visibles: Mantén una propiedad (ej. displayedColumns) que contenga los def de las columnas actualmente visibles. Esta propiedad se pasará a mat-table.

3. Implementar el manejador de eventos: Crea una función para manejar el evento columnToggled emitido por el componente. Esta función actualizará el estado de visibilidad y recalculará displayedColumns.

@Component({
  // ...
})
export class ListRemotoComponent {
  @Input() dataTable: IRemoto[] = [];
  // ... otros inputs y outputs

  /**
   * 1. Definición de TODAS las columnas disponibles y su estado inicial.
   */
  public allColumns: IAlpuraColumnToggleMenuConfig[] = [
    { def: "nombre", label: "Nombre", visible: true },
    { def: "descripcion", label: "Descripción", visible: true },
    { def: "options", label: "Opciones", visible: true },
  ];

  /**
   * 2. Arreglo de strings que controla las columnas que mat-table renderiza.
   *    Se deriva de `allColumns`.
   */
  public displayedColumns: string[] = this.allColumns
    .filter((c) => c.visible)
    .map((c) => c.def);

  /**
   * 3. Manejador que se activa cuando el usuario cambia la visibilidad de una columna.
   * @param toggledColumn La columna que se ha activado/desactivado.
   */
  public toggleColumn(toggledColumn: IAlpuraColumnToggleMenuConfig): void {
    const column = this.allColumns.find((c) => c.def === toggledColumn.def);
    if (column) {
      // Alterna la visibilidad en la fuente de datos principal
      column.visible = !column.visible;
      // Vuelve a calcular las columnas a mostrar para que la tabla se actualice
      this.displayedColumns = this.allColumns
        .filter((c) => c.visible)
        .map((c) => c.def);
    }
  }
}

---

🧩 Uso en la Plantilla (HTML)

1. Contenedor con Posición Relativa: Envuelve la tabla y el menú en un div con position: relative; para que el menú se posicione correctamente sobre la tabla.

2. Añadir el componente de menú: Coloca <alpura-column-toggle-menu> dentro del contenedor. Pasa la configuración completa de columnas (allColumns) y escucha el evento columnToggled.

3. Configurar mat-table: Usa la propiedad displayedColumns en mat-header-row y mat-row para que Angular Material renderice las columnas dinámicamente.

<div class="table-container">
  <!-- 2. Componente del menú de columnas -->
  <alpura-column-toggle-menu
    [allColumns]="allColumns"
    (columnToggled)="toggleColumn($event)"
  ></alpura-column-toggle-menu>

  <!-- 3. Tabla de Angular Material -->
  <table mat-table [dataSource]="dataTable">
    <!-- Definición de Columna 'nombre' -->
    <ng-container matColumnDef="nombre">
      <th mat-header-cell *matHeaderCellDef>Nombre</th>
      <td mat-cell *matCellDef="let element">{{ element.idNombre }}</td>
    </ng-container>

    <!-- Definición de Columna 'descripcion' -->
    <ng-container matColumnDef="descripcion">
      <th mat-header-cell *matHeaderCellDef>Descripción</th>
      <td mat-cell *matCellDef="let element">{{ element.descripcion }}</td>
    </ng-container>

    <!-- Definición de Columna 'options' -->
    <ng-container matColumnDef="options">
      <th mat-header-cell *matHeaderCellDef>Opciones</th>
      <td mat-cell *matCellDef="let element">
        <!-- Botones de acción -->
      </td>
    </ng-container>

    <!-- Filas de encabezado y datos -->
    <tr mat-header-row *matHeaderRowDef="displayedColumns"></tr>
    <tr mat-row *matRowDef="let row; columns: displayedColumns"></tr>
  </table>
</div>

---

📖 API del Componente

Inputs

Propiedad	Tipo	Descripción
allColumns	IAlpuraColumnToggleMenuConfig[]	Requerido. Arreglo con la configuración de todas las columnas (visibles y ocultas) que poblarán el menú.

Outputs

Evento	Parámetros	Descripción
columnToggled	IAlpuraColumnToggleMenuConfig	Se emite cuando el usuario marca o desmarca un checkbox en el menú de columnas.

Interfaces

/**
 * Define la configuración para una columna en el menú de visibilidad.
 */
export interface IAlpuraColumnToggleMenuConfig {
  /**
   * Identificador único de la columna (usado en `mat-table` como `matColumnDef`).
   */
  def: string;
  /**
   * Etiqueta legible por humanos que se muestra en el menú.
   */
  label: string;
  /**
   * Estado de visibilidad actual de la columna. `true` si es visible, `false` si está oculta.
   */
  visible: boolean;
}

---

🚀 Resultado esperado

• Un menú desplegable que permite al usuario controlar la visibilidad de las columnas de una tabla mat-table.
• Sincronización automática entre el estado del menú y las columnas mostradas en la tabla.
• Integración sencilla con la lógica del componente padre a través de inputs y outputs.
• Mejora la experiencia de usuario en tablas con muchas columnas, permitiendo personalizar la vista.

---

📬 Soporte

Para dudas o mantenimiento del componente AlpuraColumnToggleMenuComponent, contactar al equipo de arquitectura.