@jvsoft/components 0.0.13-alpha.4 → 1.0.0-alpha.10

package/filtro-busqueda/README.md

@@ -0,0 +1,156 @@
+# Documentación de FiltroBusquedaComponent
+
+El componente `@jvsoft/components/filtro-busqueda` es un sistema dinámico de filtrado diseñado para Angular v19+. Utiliza **Signals** para la gestión de estado y ofrece una estética "orgánica" basada en elementos nativos con el poder de Angular Material.
+
+## Características Principales
+
+- **Angular 19+**: Aprovecha `signal()`, `input()`, `output()` y el nuevo flujo de control (`@if`, `@for`).
+- **Estética Orgánica**: Labels sobre el borde (fieldset/legend) con tipografía limpia y bordes continuos.
+- **Carga en Cascada (Niveles)**: Soporta hasta 5 niveles de peticiones asíncronas encadenadas mediante `ordenPeticion`.
+- **Tipos de Control**: Autocomplete, Select, Date, Date Range, Checkbox, Text, Number, y Controles Agrupados.
+- **Resumen Automático**: Genera una cadena legible (`labelResumen`) de todos los filtros aplicados.
+- **Servicio Centralizado**: Gestión de estado reactiva mediante `FiltroBusquedaService`.
+
+---
+
+## 🚀 Instalación e Importación
+
+Importa el componente en tu módulo o componente standalone:
+
+```typescript
+import { FiltroBusquedaComponent } from '@jvsoft/components/filtro-busqueda';
+
+@Component({
+  standalone: true,
+  imports: [FiltroBusquedaComponent],
+  // ...
+})
+export class MiComponente {}
+```
+
+---
+
+## 🛠️ Configuración (CampoFiltro)
+
+El componente se configura mediante un array de `TabSeccion`. Cada sección contiene un array de `CampoFiltro`.
+
+### Propiedades de CampoFiltro
+
+| Propiedad | Tipo | Descripción |
+| :--- | :--- | :--- |
+| `control` | `TiposControl` | `select`, `autocomplete`, `date`, `date_range`, `checkbox`, `text`, `number` |
+| `campo` | `string` | Nombre del campo en el formulario y objeto resultante. |
+| `label` | `string` | Texto descriptivo (se muestra en el legend). |
+| `value` | `any` | Valor inicial (`*fechaActual*`, `*primero*`, etc). |
+| `required` | `boolean` | Indica si el campo es obligatorio. |
+| `select` / `autocomplete` | `Config` | Objeto de configuración específico para estos tipos. |
+| `dateRange` | `Config` | Configuración para rangos de fechas. |
+| `ordenPeticion` | `number (0-4)` | Nivel de carga cuando hay selects dependientes. |
+
+---
+
+## 📊 Carga de Datos en Cascada
+
+El componente utiliza un sistema de niveles para cargar datos del servidor de forma ordenada.
+
+### Ejemplo: País -> Departamento -> Provincia
+
+1. **Nivel 0**: Se carga la lista de Países.
+2. **Nivel 1**: El select de Departamento tiene `ordenPeticion: 1` y espera a que el País tenga valor.
+3. **Nivel 2**: El select de Provincia tiene `ordenPeticion: 2` y espera a Departamento.
+
+Configura `reqParams.fields` para indicar qué campos debe enviar el control dependiente al servidor.
+
+---
+
+## 🔄 Inputs y Outputs
+
+### Inputs
+- `opciones`: Array de `TabSeccion[]` con la configuración.
+- `nombreColeccion`: ID único para el service (ej: `'tramitesBusqueda'`).
+- `defaultTab`: Índice de la pestaña inicial (default `0`).
+- `busquedaAutomatica`: Si es `true`, emite cambios en cada interacción.
+
+### Outputs
+- `buscar`: **NUEVA API (Mejora 2)**. Evento principal de filtrado. Emite la interfaz `FiltroResultante` con los datos listos para API y las etiquetas legibles (`labelResumen`).
+- `resultados`: **@deprecated**. Solo emite el diccionario crudo. Se mantiene temporalmente por retrocompatibilidad. ¡Usa `(buscar)` en su lugar!
+- `dataFiltro`: **@deprecated** (Paradigma Zero-Output). En lugar de escuchar este evento, inyecta el `FiltroBusquedaService` y usa `getFiltroSignal()`.
+- `cargaCompleta`: **@deprecated** (Paradigma Zero-Output). Depender de Signals en el servicio evita la necesidad de este output de sincronización.
+
+---
+
+## � Acceso al Estado (Angular 19+ Signals)
+
+El estado del filtro está centralizado en `FiltroBusquedaService`. Para acceder de forma reactiva y Zero-Cost desde cualquier componente, utiliza la nueva API basada en Signals:
+
+```typescript
+import { Component, inject, computed } from '@angular/core';
+import { FiltroBusquedaService } from '@jvsoft/components/filtro-busqueda';
+
+@Component({ ... })
+export class MiVistaTabla {
+  private filtroService = inject(FiltroBusquedaService);
+
+  // 1. Obtener los valores del formulario continuamente
+  // Retorna un Signal<any>, inicializado con el fallback proveído.
+  readonly dataFiltro = this.filtroService.getFiltroSignal('tramitesBusqueda', { datosFiltro: {} });
+
+  // 2. Obtener metadatos/catálogos que llegaron del servidor para un campo
+  readonly listaDepartamentos = this.filtroService.getDataServidorSignal('tramitesBusqueda', 'departamento_id', []);
+}
+```
+
+> **Nota**: Los métodos `getValue()` y `getDataServidorSuscripcion()` aún existen para retrocompatibilidad síncrona, pero su uso reactivo con RxJS está marcado como **@deprecated**.
+
+---
+
+## �📋 FiltroResultante
+
+El objeto emitido por `resultados` tiene esta estructura:
+
+```typescript
+export interface FiltroResultante {
+  datosFiltro: { [key: string]: any }; // Datos crudos para enviar al API
+  datosFiltroConLabel: DataFiltroAplicado[]; // Metadatos con etiquetas
+  labelResumen: string; // "Periodo: 01/01/2026 - 31/01/2026 | Estado: Activo"
+}
+```
+
+---
+
+## 💉 Token de Servicio de Datos (QUERY_SERVICE_TOKEN)
+
+El componente no sabe cómo llamar a tu API. Debes proveer una implementación del `QUERY_SERVICE_TOKEN`:
+
+```typescript
+{
+  provide: QUERY_SERVICE_TOKEN,
+  useExisting: MiApiService // Debe tener un método .cargar(...)
+}
+```
+
+---
+
+## 🧪 Ejemplo de Autocomplete
+
+```typescript
+{
+  control: 'autocomplete',
+  campo: 'idEntidad',
+  label: 'Entidad',
+  autocomplete: {
+    data: 'entidades', // Nombre de la consulta al servidor
+    camposText: ['nombre', 'ruc'], // Campos para el label
+    campotxtBuscar: 'nombre', // Parámetro de búsqueda al API
+    campotxtBuscarLength: 3 // Mínimo caracteres para disparar búsqueda
+  }
+}
+```
+
+---
+
+## 💡 Mejores Prácticas
+
+- Usa `nombreColeccion` descriptivos para evitar colisiones en el `FiltroBusquedaService`.
+- Aprovecha `labelResumen` para mostrar al usuario qué filtros tiene activos sin ocupar mucho espacio.
+- En `date_range`, usa `value: ['*fechaActual*', '*fechaActual*']` para inicializar el día de hoy cómodamente.

package/filtro-busqueda/filtro-busqueda.component.d.ts

@@ -0,0 +1,89 @@
+import { InjectionToken, OnDestroy, OnInit } from '@angular/core';
+import { BehaviorSubject, Observable, Subject } from 'rxjs';
+import { FormArray, FormControl, FormGroup } from '@angular/forms';
+import { DataServidor, mostrarValorEnBusqueda, tipoValorFuncion } from '@jvsoft/utils';
+import { CampoFiltro, FiltroResultante, TabFiltroSeccion, TabSeccion } from './interfaces/filtro-busqueda.interface';
+import * as i0 from "@angular/core";
+export interface IQueryService {
+    cargar(objThis: any, reqArray: string[], data: any, anonimo: boolean, prefix: string): Promise<any>;
+}
+export declare const QUERY_SERVICE_TOKEN: InjectionToken<IQueryService>;
+export declare class FiltroBusquedaComponent implements OnInit, OnDestroy {
+    private fb;
+    private toastr;
+    private filtroBusquedaService;
+    private queryService;
+    opciones: import("@angular/core").InputSignal<TabSeccion[]>;
+    nombreColeccionInput: import("@angular/core").InputSignal<string>;
+    prefijoConsulta: import("@angular/core").InputSignal<string>;
+    busquedaAutomatica: import("@angular/core").InputSignal<boolean>;
+    opciones$: import("@angular/core").InputSignal<Observable<TabSeccion[]> | undefined>;
+    modificarOpciones$: import("@angular/core").InputSignal<Observable<{
+        [key: string]: any;
+    }> | undefined>;
+    defaultTab: import("@angular/core").InputSignal<number>;
+    /**
+     * @deprecated Paradigma Zero-Output: Inyecta FiltroBusquedaService y usa `getFiltroSignal('nombreColeccion')` para estado en tiempo real, esto evita renderizados innecesarios del padre.
+     */
+    dataFiltro: import("@angular/core").OutputEmitterRef<any>;
+    /**
+     * @deprecated Su payload de diccionario crudo desaparecerá pronto (Mejora 2). Migra al nuevo evento `(buscar)` que emite la interfaz `FiltroResultante`.
+     * Se mantiene temporalmente para componentes legacy.
+     */
+    resultados: import("@angular/core").OutputEmitterRef<any>;
+    /**
+     * Evento principal explícito de búsqueda (Click en Filtrar). Emite el objeto con metadata y labels.
+     */
+    buscar: import("@angular/core").OutputEmitterRef<FiltroResultante>;
+    /**
+     * @deprecated Paradigma Zero-Output: Maneja la finalización de carga a través de los Signals internos del servicio o asume inmediatez de la arquitectura nueva.
+     */
+    cargaCompleta: import("@angular/core").OutputEmitterRef<boolean>;
+    tabActual: import("@angular/core").WritableSignal<number>;
+    dataOpcionesNuevo: import("@angular/core").WritableSignal<TabFiltroSeccion[]>;
+    isCargaCompleta: import("@angular/core").WritableSignal<boolean>;
+    frmFiltroBusqueda: FormGroup;
+    get opcionesTabs(): FormArray;
+    get frmGroupSeleccionado(): FormGroup;
+    getControl(nombre: string): FormControl;
+    getControlRaiz(nombre: string): FormControl;
+    getAutocompleteLabel(controlData: CampoFiltro, value: any): string;
+    dataServidor: DataServidor;
+    dataServidorSuscripcion: {
+        [key: string]: BehaviorSubject<any>;
+    };
+    filtrados: {
+        [key: string]: any[];
+    };
+    inputParaEnviarAutocomplete: Subject<any>;
+    private destroy$;
+    protected sufixTemporal: string;
+    protected tipoValorFuncion: typeof tipoValorFuncion;
+    private fechaActual;
+    constructor();
+    ngOnInit(): void;
+    private initOpciones;
+    private reorganizarOpcionesNuevas;
+    cargarDatosFiltroNuevo(idTab?: number): Promise<void>;
+    private actualizarEstadoService;
+    private setCustomData;
+    private procesarRetornoDatos;
+    getFiltroResultante(): FiltroResultante;
+    mostrarValorEnBusqueda: typeof mostrarValorEnBusqueda;
+    campoValorEval(campoFiltro: CampoFiltro, itemSelect: any): any;
+    campoTextEval(campoFiltro: CampoFiltro, itemSelect: any): string;
+    concatenarCadenasArray(array: string | string[], objData: any): any;
+    filtrarData(): void;
+    actualizarEnFormArray(name: string, value: any, extra?: {
+        disabled?: boolean;
+    }): void;
+    accionPosteriorCambioAutocomplete(controlData: CampoFiltro, valControl: any): void;
+    cambiarNuevo(campo: CampoFiltro, val: any): void;
+    cambiarSeleccionNuevo(campo: CampoFiltro, event?: any): void;
+    buscarControl(campo: string): CampoFiltro | undefined;
+    generarParams(meta: CampoFiltro, trigger: CampoFiltro): any;
+    limpiarAutocomplete(campo: CampoFiltro, event: Event): void;
+    ngOnDestroy(): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FiltroBusquedaComponent, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<FiltroBusquedaComponent, "jvs-filtro-busqueda", never, { "opciones": { "alias": "opciones"; "required": false; "isSignal": true; }; "nombreColeccionInput": { "alias": "nombreColeccion"; "required": false; "isSignal": true; }; "prefijoConsulta": { "alias": "prefijoConsulta"; "required": false; "isSignal": true; }; "busquedaAutomatica": { "alias": "busquedaAutomatica"; "required": false; "isSignal": true; }; "opciones$": { "alias": "opciones$"; "required": false; "isSignal": true; }; "modificarOpciones$": { "alias": "modificarOpciones$"; "required": false; "isSignal": true; }; "defaultTab": { "alias": "defaultTab"; "required": false; "isSignal": true; }; }, { "dataFiltro": "dataFiltro"; "resultados": "resultados"; "buscar": "buscar"; "cargaCompleta": "cargaCompleta"; }, never, never, true, never>;
+}

package/filtro-busqueda/filtro-busqueda.component.scss

@@ -0,0 +1,98 @@
+@use '@angular/material' as mat;
+
+.jvsFiltroBusqueda {
+  @include mat.all-component-densities(-3);
+  @apply py-1;
+
+
+  .mat-mdc-tab,
+  .mat-mdc-tab-label,
+  .mat-tab-label {
+    height: 24px !important;
+  }
+
+  [aria-label=primary] {
+    color: rgb(var(--color-primary-contrast));
+  }
+
+  .mat-mdc-tab {
+    border-bottom: solid 2px !important;
+    border-bottom-color: rgb(var(--color-primary)) !important;
+  }
+
+  .mat-mdc-tab.mdc-tab--active {
+    @apply bg-primary/20;
+  }
+
+  .mat-mdc-tab.mdc-tab--active .mdc-tab__text-label {
+    color: rgb(var(--color-primary-selected-tab)) !important;
+    font-weight: bold;
+  }
+
+  fieldset.contenedorCampo {
+    @apply w-full sm:w-auto rounded-sm bg-transparent pt-0 pb-1 px-1 border-0;
+
+    legend {
+      @apply px-2 text-2xs font-light border-0 bg-transparent;
+      width: auto;
+    }
+
+    .formcontrol-container,
+    .daterange-container,
+    .date-container,
+    .campos-container,
+    select, input, textarea {
+      @apply w-full bg-white border border-gray-300 rounded-sm leading-tight focus:outline-none focus:border-blue-500 /*dark:*/
+      bg-transparent;
+    }
+
+    input {
+      padding-left: 2px;
+    }
+
+    .formcontrol-container {
+      textarea, input {
+        @apply text-xs border-0;
+      }
+    }
+
+    .daterange-container {
+      width: 200px;
+
+      input {
+        @apply text-xs text-center border-0;
+      }
+    }
+
+    .date-container {
+      width: 100px;
+
+      input {
+        @apply text-xs border-0;
+      }
+    }
+    .campos-container {
+      select, input, textarea {
+        @apply text-xs border-0 rounded-none;
+      }
+      input, textarea {
+        @apply border-l px-1;
+      }
+      .formcontrol-container {
+        @apply border-none;
+      }
+    }
+
+    .mat-datepicker-toggle {
+      //@apply w-auto h-auto;
+      height: 18px !important;
+      width: 18px !important;
+
+      button {
+        height: unset !important;
+        width: unset !important;
+        padding: 0 !important;
+      }
+    }
+  }
+}

package/filtro-busqueda/filtro-busqueda.service.d.ts

@@ -0,0 +1,40 @@
+import * as i0 from "@angular/core";
+export declare class FiltroBusquedaService {
+    private _filtrosActivos;
+    private _dataServidorActivos;
+    filtrosActivos: import("@angular/core").Signal<Map<string, any>>;
+    dataServidorActivos: import("@angular/core").Signal<Map<string, Map<string, any>>>;
+    /**
+     * Establece un valor para un filtro reactivo
+     */
+    setValue(nombreFiltro: string, val: any): void;
+    /**
+     * @deprecated Usa `getFiltroSignal(nombreFiltro)` en componentes modernos.
+     * Retorna el snapshot sincrónico actual (para componentes legacy).
+     */
+    getValue(nombreFiltro: string): any;
+    /**
+     * Actualiza la metadata del servidor (Signals).
+     */
+    setDataServidorSuscripcion(nombreFiltro: string, campo: string, data: any): void;
+    /**
+     * @deprecated Usa `getDataServidorSignal(nombreFiltro, campo)` en componentes modernos.
+     * Retorna el snapshot sincrónico actual de metadata (para componentes legacy).
+     */
+    getDataServidorSuscripcion(nombreFiltro: string, campo: string): any;
+    /**
+     * Crea y devuelve un Signal reactivo continuo para observar los valores aplicados de un filtro particular.
+     * @param nombreFiltro Nombre del filtro que se desea escuchar
+     * @param defaultValue Valor de respaldo seguro si aún no se ha inicializado el filtro.
+     */
+    getFiltroSignal<T = any>(nombreFiltro: string, defaultValue?: T): import("@angular/core").Signal<T>;
+    /**
+     * Crea y devuelve un Signal reactivo continuo para escuchar la metadata/catálogo recibida del backend para un campo.
+     * @param nombreFiltro Nombre de la colección del filtro principal
+     * @param campo Campo específico (ej: id_usuario, categoria) del que se espera escuchar la lista u objeto servidor
+     * @param defaultValue Valor de respaldo seguro si aún no hay data del servidor.
+     */
+    getDataServidorSignal<T = any>(nombreFiltro: string, campo: string, defaultValue?: T): import("@angular/core").Signal<T>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<FiltroBusquedaService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<FiltroBusquedaService>;
+}

package/filtro-busqueda/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Generated bundle index. Do not edit.
+ */
+/// <amd-module name="@jvsoft/components/filtro-busqueda" />
+export * from './public-api';

package/filtro-busqueda/interfaces/filtro-busqueda.interface.d.ts

@@ -0,0 +1,86 @@
+import { TemplateRef } from '@angular/core';
+import { TipoValorFuncion } from '@jvsoft/utils';
+export type TiposControl = 'select' | 'autocomplete' | 'date' | 'text' | 'number' | 'date_range' | 'controlAgrupado' | 'checkbox';
+export type TiposValores = '*primero*' | '*deUsuario*' | '*fechaActual*' | any;
+export interface TabSeccion {
+    id?: string;
+    label?: string;
+    campos?: CampoFiltro[];
+    esVisible?: TipoValorFuncion<boolean>;
+}
+export interface CampoFiltroChange {
+    filter?: boolean;
+    filterFields?: string[];
+}
+export interface CampoFiltroSelectAutocompleteComun {
+    ordenPeticion?: number;
+    data?: string;
+    customData?: any[];
+    dataCuandoVacio?: any[];
+    campoValor?: string | '*objeto*';
+    camposText?: string[];
+    textoCuandoNulo?: string;
+    optionText?(row: any): string;
+    cssClass?: {
+        class?: string;
+        option?: string;
+    };
+}
+export interface CampoFiltroDateRange {
+    campo?: [string, string];
+    value?: [TiposValores, TiposValores];
+}
+export interface CampoFiltroSelect extends CampoFiltroSelectAutocompleteComun {
+}
+export interface CampoFiltroAutocomplete extends CampoFiltroSelectAutocompleteComun {
+    controlType?: 'textarea' | 'text';
+    class?: string;
+    searchFields?: string[];
+    campotxtBuscar?: string;
+    campotxtBuscarLength?: number;
+    optionTemplate?: TemplateRef<any>;
+    optionInnerHtml?(row: any): string;
+}
+export interface CampoFiltro {
+    control: TiposControl;
+    templateName?: string;
+    campo: string;
+    aliasCampoEnviar?: string;
+    label?: string;
+    cssClass?: string;
+    value?: TiposValores;
+    reqParams?: {
+        params?: object;
+        fields?: string[];
+    };
+    disabled?: boolean;
+    required?: boolean;
+    keyUpEnter?: boolean;
+    change?: CampoFiltroChange;
+    checkbox?: {
+        text: TipoValorFuncion<string>;
+    };
+    dateRange?: CampoFiltroDateRange;
+    select?: CampoFiltroSelect;
+    autocomplete?: CampoFiltroAutocomplete;
+    controlAgrupado?: CampoFiltro[];
+    modificadorDatos?(control: CampoFiltro): any;
+}
+export interface TabFiltroSeccion extends Omit<TabSeccion, 'id'> {
+    campos: CampoFiltro[];
+}
+export interface DataFiltroAplicado {
+    campo: string;
+    label: string;
+    value: any;
+    list?: any[];
+    valueString?: string;
+    valueObject?: any;
+}
+export interface FiltroResultante {
+    datosFiltro: {
+        [key: string]: any;
+    };
+    datosFiltroConLabel: DataFiltroAplicado[];
+    labelResumen: string;
+}

package/filtro-busqueda/public-api.d.ts

@@ -0,0 +1,3 @@
+export * from './filtro-busqueda.component';
+export * from './filtro-busqueda.service';
+export * from './interfaces/filtro-busqueda.interface';

package/index.d.ts

@@ -5,3 +5,4 @@ export * from './luces-navidad';
 export * from './mat-suffix-search-button';
 export * from './menu';
 export * from './lista-arbol/public-api';
+export * from './filtro-busqueda';