sapenlinea-components 0.0.21 → 0.0.23

package/README.md

@@ -1,63 +1,426 @@
-# SapenlineaComponents
+# Componentes de la librería `sapenlinea-components`
 
-This project was generated using [Angular CLI](https://github.com/angular/angular-cli) version 20.3.0.
+Esta librería incluye una colección de componentes reutilizables para formularios, tablas y filtros.
+A continuación se documenta **qué hace cada componente** y **cómo se utiliza**.
 
-## Code scaffolding
+> Nota: todos los componentes son _standalone_ de Angular, por lo que se importan directamente en el `imports` del componente donde se usen.
 
-Angular CLI includes powerful code scaffolding tools. To generate a new component, run:
+### 1. `lib-date-time-filter` (DateTimeFilter)
 
-```bash
-ng generate component component-name
+**Qué hace**  
+Componente para gestionar **filtros de fecha y fecha/hora** a partir de una lista de filtros configurables. Implementa `ControlValueAccessor` para integrarse con formularios reactivos.
+
+**Selector:** `lib-date-time-filter`
+
+**Inputs:**
+
+- `filters: FilterItem[]` (requerido)
+  - Cada `FilterItem` define un filtro disponible:
+  - `label: string` – Texto visible en el chip/botón.
+  - `value: string` – Identificador interno del filtro.
+  - `type: 'date' | 'datetime'` – Tipo de filtro.
+  - `placeholder?: string` – Placeholder específico.
+  - `minDate?: Date` / `maxDate?: Date` – Rango permitido.
+
+**Outputs:**
+
+- `dateSelected: EventEmitter<DateFilterSelection>` – Emite `{ filter: string; value: Date }` con el filtro activo y la fecha seleccionada.
+- `dateChange: EventEmitter<Date | null>` – Emite la fecha seleccionada al cambiar (o `null` si se limpia).
+
+**Uso con formularios reactivos:**
+
+```html
+<lib-date-time-filter
+  [filters]="dateFilters"
+  (dateSelected)="onDateSelected($event)"
+  (dateChange)="onDateChange($event)"
+  formControlName="fechaFiltro"
+></lib-date-time-filter>
+```
+
+```ts
+const form = this.fb.group({
+  fechaFiltro: [null],
+});
+
+dateFilters: FilterItem[] = [
+  { label: 'Fecha inicio', value: 'startDate', type: 'date', placeholder: 'Seleccionar fecha inicio' },
+  { label: 'Fecha fin', value: 'endDate', type: 'date', placeholder: 'Seleccionar fecha fin' },
+];
+```
+
+---
+
+### 2. `lib-date-time-picker` (DateTimePicker)
+
+**Qué hace**  
+Componente de **selector de fecha o fecha/hora** independiente (sin lista de filtros). Implementa `ControlValueAccessor`.
+
+**Selector:** `lib-date-time-picker`
+
+**Inputs:**
+
+- `mode: 'date' | 'datetime' = 'date'` – Modo fecha sola o fecha + hora.
+- `placeholder: string = 'Seleccionar fecha'` – Texto cuando no hay valor.
+- `minDate: Date | null = null` – Fecha mínima.
+- `maxDate: Date | null = null` – Fecha máxima.
+
+**Outputs:**
+
+- `dateChange: EventEmitter<Date | null>` – Emite la fecha seleccionada.
+
+**Ejemplo de uso:**
+
+```html
+<lib-date-time-picker
+  mode="datetime"
+  [minDate]="minDate"
+  [maxDate]="maxDate"
+  (dateChange)="onDateChange($event)"
+  formControlName="fechaEvento"
+></lib-date-time-picker>
+```
+
+---
+
+### 3. `lib-dialog-alert-component` (DialogAlertComponent)
+
+**Qué hace**  
+Componente de **diálogo/modal de alerta/confirmación**, con opción de exigir una razón (select + textarea) antes de confirmar.
+
+**Selector:** `lib-dialog-alert-component`
+
+**Inputs:**
+
+- `title: string = 'Mensaje'` – Título del diálogo.
+- `message: string` – Mensaje principal.
+- `type: 'warning' | 'error' | 'info' | 'success' = 'info'` – Tipo visual de alerta.
+- `action?: string` – Acción asociada (ej. `'deactivate'`, `'delete'`, `'anulate'`, `'sancionar'`, `'active'`).
+- `showReason: boolean = false` – Forzar mostrar campo de razón.
+- `confirm: boolean = false` – Indica si muestra botón de confirmación principal.
+- `confirmLabel: string = 'Aceptar'` – Texto del botón de confirmación.
+- `reasonOptions: { label: string; value: any }[] = []` – Opciones para el campo "Razón" cuando se requiere.
+
+**Outputs:**
+
+- `close: EventEmitter<boolean>` – Emite `true` al confirmar y `false` al cancelar.
+- `confirmReason: EventEmitter<string | undefined>` – Emite la razón seleccionada (o `undefined`).
+
+**Ejemplo de uso:**
+
+```html
+<lib-dialog-alert-component
+  [title]="'Desactivar usuario'"
+  [message]="'¿Está seguro que desea desactivar este usuario?'"
+  type="warning"
+  action="deactivate"
+  [showReason]="true"
+  [reasonOptions]="reasonOptions"
+  (close)="onClose($event)"
+  (confirmReason)="onConfirmReason($event)"
+></lib-dialog-alert-component>
+```
+
+---
+
+### 4. `lib-dynamic-form-fields` (DynamicFormFields)
+
+**Qué hace**  
+Componente que **renderiza dinámicamente campos de formulario** a partir de una configuración (`sections` y `fields`), soportando textos, números, selects, checkboxes, radios, textarea, fechas y más. Maneja lógicas de copiado automático entre campos.
+
+**Selector:** `lib-dynamic-form-fields`
+
+**Inputs:**
+
+- `form: FormGroup` (requerido) – Formulario reactivo que contiene los controles.
+- `sections: SectionConfig[] = []` – Secciones y campos del formulario.
+- `compact: boolean = false` – Permite estilos compactos.
+
+**Tipos principales:**
+
+```ts
+export interface FieldConfig {
+  key: string;
+  label?: string;
+  type: 'text' | 'email' | 'number' | 'date' | 'datetime-local' | 'select' | 'radio' | 'checkbox' | 'textarea' | 'disabled' | 'password' | 'time' | 'file';
+  placeholder?: string;
+  required?: boolean;
+  options?: { value: string | number | boolean; label: string }[];
+  col?: number;
+  disabled?: boolean;
+  readonly?: boolean;
+  matchWith?: string;
+  copyFrom?: string;
+  pattern?: string;
+  patternType?: 'numbers' | 'phone' | 'custom' | 'text' | 'username' | 'alphanumeric';
+  minDate?: Date;
+  maxDate?: Date;
+}
+
+export interface SectionConfig {
+  title?: string;
+  description?: string;
+  fields: FieldConfig[];
+}
+```
+
+**Ejemplo de uso:**
+
+```html
+<lib-dynamic-form-fields
+  [form]="form"
+  [sections]="sections"
+  [compact]="true"
+></lib-dynamic-form-fields>
+```
+
+---
+
+### 5. `lib-input-text-filter` (InputTextFilter)
+
+**Qué hace**  
+Componente de **filtro por texto** con chips de filtros configurables (por ejemplo, buscar por nombre, documento, etc.). Implementa `ControlValueAccessor`.
+
+**Selector:** `lib-input-text-filter`
+
+**Inputs:**
+
+- `filters: FilterItem[]` (requerido) – Filtros disponibles de texto.
+- `clearTrigger: number = 0` – Al incrementar este valor desde el padre se limpian todos los filtros.
+
+**Outputs:**
+
+- `filterSelected: EventEmitter<{ filter: string; value: string }>` – Emite el filtro y el valor aplicado.
+- `valueChange: EventEmitter<string | null>` – Emite el valor actual del filtro de texto.
+
+**Ejemplo de uso:**
+
+```html
+<lib-input-text-filter
+  [filters]="textFilters"
+  [clearTrigger]="clearVersion"
+  (filterSelected)="onTextFilter($event)"
+  (valueChange)="onTextValueChange($event)"
+></lib-input-text-filter>
 ```
 
-For a complete list of available schematics (such as `components`, `directives`, or `pipes`), run:
+---
 
-```bash
-ng generate --help
+### 6. `lib-input-number-filter` (InputNumberFilter)
+
+**Qué hace**  
+Componente de **filtro numérico** con múltiples chips (ej. "monto mínimo", "monto máximo"). Implementa `ControlValueAccessor`.
+
+**Selector:** `lib-input-number-filter`
+
+**Inputs:**
+
+- `filters: FilterItem[]` (requerido) – Filtros numéricos.
+- `clearTrigger: number = 0` – Limpia filtros al cambiar.
+
+**Outputs:**
+
+- `filterSelected: EventEmitter<{ filter: string; value: string }>` – Filtro seleccionado y valor.
+- `valueChange: EventEmitter<string | null>` – Valor numérico aplicado.
+
+**Ejemplo de uso:**
+
+```html
+<lib-input-number-filter
+  [filters]="numberFilters"
+  (filterSelected)="onNumberFilter($event)"
+></lib-input-number-filter>
+```
+
+---
+
+### 7. `lib-input-select-filter` (InputSelectFilter)
+
+**Qué hace**  
+Componente de **filtro basado en select** con chips. Permite seleccionar una opción por cada tipo de filtro configurado.
+
+**Selector:** `lib-input-select-filter`
+
+**Inputs:**
+
+- `filters: FilterItem[]` (requerido) – Deben incluir `options` con `{ label, value }`.
+- `clearTrigger: number = 0` – Limpia filtros.
+
+**Outputs:**
+
+- `filterSelected: EventEmitter<{ filter: string; value: string }>` – Filtro e identificador de opción seleccionada.
+- `valueChange: EventEmitter<string | null>` – Valor del select actual.
+
+**Ejemplo de uso:**
+
+```html
+<lib-input-select-filter
+  [filters]="statusFilters"
+  (filterSelected)="onStatusFilter($event)"
+></lib-input-select-filter>
+```
+
+---
+
+### 8. `lib-select-custom-search` (SelectCustomSearch)
+
+**Qué hace**  
+Componente de **select con buscador** y filtrado en tiempo real sobre las opciones. Implementa `ControlValueAccessor`.
+
+**Selector:** `lib-select-custom-search`
+
+**Inputs:**
+
+- `options: { value: any; label: string }[] = []` – Opciones disponibles.
+- `placeholder: string = 'Seleccionar opción'` – Texto cuando no hay selección.
+
+**Outputs:**
+
+- `selectionChange: EventEmitter<Option | null>` – Emite la opción seleccionada (o `null`).
+
+**Ejemplo de uso:**
+
+```html
+<lib-select-custom-search
+  [options]="userOptions"
+  (selectionChange)="onUserSelected($event)"
+  formControlName="usuarioId"
+></lib-select-custom-search>
 ```
 
-## Building
+---
+
+### 9. `lib-pagination` (PaginationComponent)
+
+**Qué hace**  
+Componente de **paginación** para tablas o listas, con opción de selector de tamaño de página.
+
+**Selector:** `lib-pagination`
+
+**Inputs:**
+
+- `page: number = 1` – Página actual.
+- `pageSize: number = 10` – Elementos por página (valor inicial).
+- `totalItems: number = 0` – Total de elementos.
+- `showPageSizeSelector: boolean = false` – Muestra/oculta el selector de tamaño de página.
+- `pageSizeOptions: number[] = [5, 10, 20, 50]` – Opciones disponibles.
 
-To build the library, run:
+**Outputs:**
 
-```bash
-ng build sapenlinea-components
+- `pageChange: EventEmitter<number>` – Emite la nueva página seleccionada.
+- `pageSizeChange: EventEmitter<number>` – Emite el nuevo tamaño de página.
+
+**Ejemplo de uso:**
+
+```html
+<lib-pagination
+  [page]="currentPage"
+  [pageSize]="pageSize"
+  [totalItems]="totalItems"
+  [showPageSizeSelector]="true"
+  [pageSizeOptions]="[10, 20, 50]"
+  (pageChange)="onPageChange($event)"
+  (pageSizeChange)="onPageSizeChange($event)"
+></lib-pagination>
 ```
 
-This command will compile your project, and the build artifacts will be placed in the `dist/` directory.
+---
+
+### 10. `lib-table` (Table)
+
+**Qué hace**  
+Componente de **tabla dinámica** con soporte de ordenamiento, acciones por fila y estado con tonos configurables.
+
+**Selector:** `lib-table`
+
+**Inputs:**
+
+- `columns: TableColumn[]` (requerido) – Definición de columnas.
+- `data: TableRow[]` (requerido) – Datos a mostrar.
+- `actions: TableAction[] | ((row: TableRow) => TableAction[])` – Acciones por fila.
+- `showActions: boolean = true` – Muestra/oculta columna de acciones.
+- `statusToneMap: StatusToneMap` – Mapa para estilo de estados (`success`, `error`, `warning`, `info`, `neutral`).
 
-### Publishing the Library
+**Outputs:**
 
-Once the project is built, you can publish your library by following these steps:
+- `optionSelected: EventEmitter<{ action: string; row: TableRow }>` – Emite la acción seleccionada y la fila.
 
-1. Navigate to the `dist` directory:
-   ```bash
-   cd dist/sapenlinea-components
-   ```
+**Ejemplo de uso:**
 
-2. Run the `npm publish` command to publish your library to the npm registry:
-   ```bash
-   npm publish
-   ```
+```html
+<lib-table
+  [columns]="columns"
+  [data]="rows"
+  [actions]="rowActions"
+  [statusToneMap]="statusToneMap"
+  (optionSelected)="onTableAction($event)"
+></lib-table>
+```
+
+---
+
+### 11. `lib-modal-form` (ModalForm)
+
+**Qué hace**  
+Componente de **modal genérico de formulario multi-paso**, que delega la navegación de pasos a `lib-wizard-form`.
 
-## Running unit tests
+**Selector:** `lib-modal-form`
 
-To execute unit tests with the [Karma](https://karma-runner.github.io) test runner, use the following command:
+**Inputs:**
 
-```bash
-ng test
+- `title: string = 'Formulario'` – Título del modal.
+- `submitLabel: string = 'Guardar'` – Texto del botón de guardar.
+- `form: FormGroup` – Formulario reactivo principal.
+- `steps: ModalFormStep[] = []` – Pasos del formulario.
+
+```ts
+export interface ModalFormStep {
+  key: string;          // Nombre del subgrupo dentro de form
+  label: string;        // Texto visible del paso
+  component: Type<any>; // Componente que se renderiza en ese paso
+}
 ```
 
-## Running end-to-end tests
+**Outputs:**
+
+- `onSubmit: EventEmitter<any>` – Emite el valor completo del formulario.
+- `onCancel: EventEmitter<void>` – Emite cuando se cancela el modal.
 
-For end-to-end (e2e) testing, run:
+**Ejemplo de uso:**
 
-```bash
-ng e2e
+```html
+<lib-modal-form
+  [title]="'Registro de usuario'"
+  [submitLabel]="'Guardar'"
+  [form]="form"
+  [steps]="steps"
+  (onSubmit)="onSubmit($event)"
+  (onCancel)="onCancel()"
+></lib-modal-form>
 ```
 
-Angular CLI does not come with an end-to-end testing framework by default. You can choose one that suits your needs.
+---
+
+### 12. `lib-wizard-form` (WizardForm)
+
+**Qué hace**  
+Componente que **orquesta la lógica de pasos** de un formulario tipo wizard, validando el sub-formulario del paso actual y notificando si se puede continuar.
+
+**Selector:** `lib-wizard-form`
+
+**Inputs:**
+
+- `form: FormGroup` – Formulario principal que contiene subgrupos.
+- `currentStep: number = 1` – Paso actual (1-based).
+- `steps: ModalFormStep[] = []` – Definición de los pasos.
+
+**Outputs:**
+
+- `canContinue: EventEmitter<boolean>` – Emite si el grupo del paso actual es válido.
+
+**Uso habitual (interno de `lib-modal-form`):**  
+No suele consumirse directamente, pero puede utilizarse si se quiere un wizard sin modal.
 
-## Additional Resources
+---
 
-For more information on using the Angular CLI, including detailed command references, visit the [Angular CLI Overview and Command Reference](https://angular.dev/tools/cli) page.
+Si necesitas que adapte los ejemplos a un caso concreto de tu aplicación (por ejemplo, filtros específicos o estructura de formularios), coméntame qué escenario quieres documentar y lo ajustamos.