🧰 AlpuraActionsComponent – Guía de uso

AlpuraActionsComponent es un componente avanzado que gestiona un formulario dinámico junto con un conjunto de acciones estándar (Nuevo, Aceptar, Cancelar, Buscar). Cambia su estado y comportamiento entre los modos Búsqueda, Creación y Edición, e integra atajos de teclado para una navegación fluida.

📁 Importaciones necesarias

AlpuraActionsComponent es un componente standalone. Para utilizarlo, impórtalo y añádelo al arreglo imports de tu componente o NgModule.

// En tu componente.ts
import { AlpuraActionsComponent } from "@alpura/commons";

@Component({
  selector: "app-mi-componente",
  standalone: true,
  imports: [
    // ... otros imports
    AlpuraActionsComponent,
  ],
  templateUrl: "./mi-componente.html",
})
export class MiComponente {
  /* ... */
}

🚀 Uso Básico

En tu plantilla HTML, puedes usar el componente de la siguiente manera:

<alpura-alpura-actions
  #actionsComponent
  [formConfig]="formConfig"
  [validatorConfig]="validatorConfig"
  [shortcutsBtn]="shortcutsConfig"
  (submitEvent)="onFormSubmit($event)"
  (createEvent)="handleCreate()"
  (searchEvent)="handleSearch()"
  (cleanFiltersEvent)="handleClean()"
>
</alpura-alpura-actions>

🧠 Inputs

Nombre	Tipo	Descripción
`formConfig`	`IAlpuraActions[]`	Requerido. Lista de objetos que definen cada campo del formulario.
`shortcutsBtn`	`IAlpuraShortcutsBtn`	Configuración para mostrar botones de acción adicionales (Exportar, Descargar, etc.) y botones personalizados.
`collapsed`	`boolean`	Si es `true`, el panel del formulario se mostrará colapsado inicialmente. Default: `false`.
`itemColClass`	`string`	Clases CSS de columna (ej. Bootstrap) para cada campo. Default: `'mb-1 col-md-6 col-lg-3'`.
`validatorConfig`	`IAlpuraValidatorConfig`	Configuración de validadores personalizados a nivel de formulario (ej. para rangos de fechas).

📤 Outputs

Nombre	Tipo	Descripción
`submitEvent`	`EventEmitter<unknown>`	Se emite con los valores del formulario cuando se envía y es válido (al presionar "Aceptar").
`createEvent`	`EventEmitter<void>`	Se emite cuando el componente entra en modo "Creación" (al presionar "Nuevo" o `alt+n`).
`searchEvent`	`EventEmitter<void>`	Se emite cuando el componente entra en modo "Búsqueda" (al presionar "Buscar" o `alt+b`).
`cleanFiltersEvent`	`EventEmitter<void>`	Se emite al limpiar el formulario (al presionar "Cancelar" o `alt+q`).

🧪 Estructura del formulario (`IAlpuraActions`)

La estructura de formConfig es idéntica a la de filterConfig en AlpuraFiltersComponent. Define los campos del formulario que se mostrarán.

Ejemplo de configuración:

import { IAlpuraActions } from '@alpura/commons'

public formConfig: IAlpuraActions[] = [
  {
    type: 'input',
    name: 'codigo',
    label: 'Código de Producto',
    validations: {
      required: true,
      maxLength: 10,
    },
  },
  {
    type: 'select',
    name: 'linea',
    label: 'Línea de Producto',
    data: [
      { id: 'leches', name: 'Leches' },
      { id: 'yogures', name: 'Yogures' },
    ],
    validations: { required: true },
  },
  {
    type: 'date',
    name: 'fechaCaducidad',
    label: 'Fecha de Caducidad',
  }
];

⌨️ Atajos de Teclado y Modos de Operación

El componente utiliza KeyboardShortcutsService internamente para gestionar su estado y facilitar la interacción del usuario.

Modos

Búsqueda (Default): El estado inicial. El título es "Búsqueda" y los botones activos son "Nuevo" y "Buscar". El formulario sirve para filtrar datos.
Creación: Se activa al presionar alt+n o el botón "Nuevo". El título cambia a "Creación" y los botones activos son "Aceptar" y "Cancelar". El formulario se usa para ingresar nuevos datos.
Edición: Se activa externamente llamando al método actionEdit(). El título cambia a "Edición" y los botones son "Aceptar" y "Cancelar". El formulario se usa para modificar datos existentes.

Atajos de Teclado Fijos

Atajo	Acción	Modo Resultante
`alt+n`	Activa el modo de creación y emite `createEvent`.	Creación
`alt+a`	Envía el formulario (si es válido) y emite `submitEvent`.	Aceptar
`alt+q`	Limpia el formulario, emite `cleanFiltersEvent` y vuelve a búsqueda.	Cancel
`alt+b`	Activa el modo de búsqueda y emite `searchEvent`.	Búsqueda
`alt+h`	Muestra/oculta el componente de actions(botones)	Ayuda
`alt+w`	Activa el modo de exportar información en formato word	Export_Word
`alt+e`	Activa el modo de exportar información en formato excel	Export_Excel
`alt+s`	Activa el modo de enviar	Send
`alt+p`	Activa el modo de exportar información en formato PDF	Export_PDF
`alt+d`	Activa el modo de descarga	Download
`alt+t`	Activa el modo toogle a un elemento en especifico	Toggle_Option
`alt+s`	Activa el modo de enviar	Send

El componente se encarga de registrar y desregistrar estos atajos automáticamente al ser creado y destruido.

Configuración de Botones y Atajos Adicionales (`shortcutsBtn`)

Puedes habilitar botones predefinidos o añadir botones personalizados a través del input shortcutsBtn.

Ejemplo de configuración:

import { IAlpuraShortcutsBtn } from '@alpura/commons';

public shortcutsConfig: IAlpuraShortcutsBtn = {
  // Habilita el botón de exportar a Excel
  EXPORT_EXCEL: { show: true },

  // Habilita el botón de descarga y personaliza su ícono y color
  DOWNLOAD: { show: true, icon: 'get_app', background: '#2196f3' },

  // Añade un botón personalizado
  CUSTOM: [
    {
      name: 'IMPRIMIR_TICKET', // Nombre único para el evento
      customShortcut: { modifier: 'ctrl', key: 'p' },
      icon: 'print',
      background: '#9c27b0',
    },
  ],
};

Cuando un usuario hace clic en un botón de atajo (o usa la combinación de teclas), se emite el evento shortcutsEvent con el nombre de la acción (ej. 'EXPORT_EXCEL', 'DOWNLOAD', 'IMPRIMIR_TICKET').

<alpura-alpura-actions
  [shortcutsBtn]="shortcutsConfig"
  (shortcutsEvent)="onShortcutAction($event)"
  ...
>
</alpura-alpura-actions>

📞 Métodos Públicos

Puedes interactuar con el componente desde el componente padre usando @ViewChild.

// En tu componente padre
import { ViewChild } from "@angular/core";
import { AlpuraActionsComponent } from "@alpura/commons";

export class MiComponente {
  @ViewChild("actionsComponent") actionsComponent: AlpuraActionsComponent;

  // ...

  editarRegistro(datos: any) {
    // Cambia el componente al modo "Edición"
    this.actionsComponent.actionEdit();

    // Llena el formulario con los datos del registro
    this.actionsComponent.formGroup.patchValue(datos);
  }
}

Métodos clave:

actionEdit(): void Pone el componente en modo Edición. Este es el método principal para la interacción padre-hijo.
cleanForm(): void Limpia el formulario y regresa el componente al modo Búsqueda. Es equivalente a presionar "Cancelar".
formGroup: FormGroup Puedes acceder directamente al FormGroup para manipular sus valores o estado (ej. patchValue, reset).

🧩 Ejemplo de Integración Completa

Este ejemplo muestra cómo un componente padre puede usar AlpuraActionsComponent para crear y editar registros en una tabla.

`mi-vista.component.ts`

import { Component, ViewChild, OnInit } from "@angular/core";
import { CommonModule } from "@angular/common";
import { AlpuraActionsComponent, IAlpuraActions } from "@alpura/commons";

@Component({
  selector: "app-mi-vista",
  standalone: true,
  imports: [CommonModule, AlpuraActionsComponent],
  templateUrl: "./mi-vista.component.html",
})
export class MiVistaComponent implements OnInit {
  @ViewChild("actions") actionsComponent: AlpuraActionsComponent;

  public formConfig: IAlpuraActions[] = [
    { type: "input", name: "id", label: "ID", validations: { required: true } },
    {
      type: "input",
      name: "nombre",
      label: "Nombre",
      validations: { required: true },
    },
  ];

  private editandoId: string | null = null;

  onFormSubmit(formData: { id: string; nombre: string }) {
    if (this.editandoId) {
      console.log("Actualizando registro:", this.editandoId, formData);
    } else {
      console.log("Creando nuevo registro:", formData);
    }
    this.editandoId = null;
  }

  handleCreate() {
    console.log("Modo creación activado. Listo para ingresar datos.");
    this.editandoId = null;
  }

  iniciarEdicion(registro: { id: string; nombre: string }) {
    this.editandoId = registro.id;
    // 1. Activar modo edición en el componente hijo
    this.actionsComponent.actionEdit();
    // 2. Poblar el formulario con los datos
    this.actionsComponent.formGroup.patchValue(registro);
  }
}

`mi-vista.component.html`

<h2>Gestión de Productos</h2>

<alpura-alpura-actions
  #actions
  [formConfig]="formConfig"
  (submitEvent)="onFormSubmit($event)"
  (createEvent)="handleCreate()"
>
</alpura-alpura-actions>

<hr />

<!-- Tabla de ejemplo para simular datos -->
<h4>Registros existentes</h4>
<p>Haz clic en "Editar" para poblar el formulario.</p>
<ul>
  <li>
    ID: 1, Nombre: Leche Entera
    <button (click)="iniciarEdicion({ id: '1', nombre: 'Leche Entera' })">
      Editar
    </button>
  </li>
  <li>
    ID: 2, Nombre: Yoghurt Fresa
    <button (click)="iniciarEdicion({ id: '2', nombre: 'Yoghurt Fresa' })">
      Editar
    </button>
  </li>
</ul>

📬 Soporte

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

📁 Importaciones necesarias​

🚀 Uso Básico​

🧠 Inputs​

📤 Outputs​

🧪 Estructura del formulario (IAlpuraActions)​

Ejemplo de configuración:​

⌨️ Atajos de Teclado y Modos de Operación​

Modos​

Atajos de Teclado Fijos​

Configuración de Botones y Atajos Adicionales (shortcutsBtn)​

Ejemplo de configuración:​

📞 Métodos Públicos​

Métodos clave:​

🧩 Ejemplo de Integración Completa​

mi-vista.component.ts​

mi-vista.component.html​

📬 Soporte​

📁 Importaciones necesarias

🚀 Uso Básico

🧠 Inputs

📤 Outputs

🧪 Estructura del formulario (`IAlpuraActions`)

Ejemplo de configuración:

⌨️ Atajos de Teclado y Modos de Operación

Modos

Atajos de Teclado Fijos

Configuración de Botones y Atajos Adicionales (`shortcutsBtn`)

Ejemplo de configuración:

📞 Métodos Públicos

Métodos clave:

🧩 Ejemplo de Integración Completa

`mi-vista.component.ts`

`mi-vista.component.html`

📬 Soporte