@jvsoft/components 1.0.0-alpha.15 → 1.0.0-alpha.16

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (92) hide show
  1. package/fesm2022/jvsoft-components-alerta.mjs +19 -20
  2. package/fesm2022/jvsoft-components-alerta.mjs.map +1 -1
  3. package/fesm2022/jvsoft-components-dialog-flotante.mjs +15 -15
  4. package/fesm2022/jvsoft-components-dialog-flotante.mjs.map +1 -1
  5. package/fesm2022/jvsoft-components-filtro-busqueda.mjs +19 -19
  6. package/fesm2022/jvsoft-components-filtro-busqueda.mjs.map +1 -1
  7. package/fesm2022/jvsoft-components-foto-persona.mjs +481 -0
  8. package/fesm2022/jvsoft-components-foto-persona.mjs.map +1 -0
  9. package/fesm2022/jvsoft-components-lista-arbol.mjs +32 -34
  10. package/fesm2022/jvsoft-components-lista-arbol.mjs.map +1 -1
  11. package/fesm2022/jvsoft-components-luces-navidad.mjs +4 -8
  12. package/fesm2022/jvsoft-components-luces-navidad.mjs.map +1 -1
  13. package/fesm2022/jvsoft-components-mat-suffix-search-button.mjs +3 -3
  14. package/fesm2022/jvsoft-components-mat-suffix-search-button.mjs.map +1 -1
  15. package/fesm2022/jvsoft-components-menu.mjs +9 -12
  16. package/fesm2022/jvsoft-components-menu.mjs.map +1 -1
  17. package/fesm2022/jvsoft-components-tabla-mantenimiento-components-progress-bar.mjs +4 -4
  18. package/fesm2022/jvsoft-components-tabla-mantenimiento-components-progress-bar.mjs.map +1 -1
  19. package/fesm2022/jvsoft-components-tabla-mantenimiento.mjs +76 -78
  20. package/fesm2022/jvsoft-components-tabla-mantenimiento.mjs.map +1 -1
  21. package/fesm2022/jvsoft-components.mjs +9 -3015
  22. package/fesm2022/jvsoft-components.mjs.map +1 -1
  23. package/foto-persona/README.md +341 -0
  24. package/package.json +22 -17
  25. package/src/styles/base-jvsoft-components.css +1542 -5
  26. package/types/jvsoft-components-alerta.d.ts +33 -0
  27. package/types/jvsoft-components-dialog-flotante.d.ts +34 -0
  28. package/types/jvsoft-components-filtro-busqueda.d.ts +217 -0
  29. package/types/jvsoft-components-foto-persona.d.ts +300 -0
  30. package/types/jvsoft-components-lista-arbol.d.ts +60 -0
  31. package/{luces-navidad/luces-navidad.component.d.ts → types/jvsoft-components-luces-navidad.d.ts} +5 -2
  32. package/{mat-suffix-search-button/mat-suffix-search-button.component.d.ts → types/jvsoft-components-mat-suffix-search-button.d.ts} +5 -2
  33. package/{menu/menu.component.d.ts → types/jvsoft-components-menu.d.ts} +24 -4
  34. package/{tabla-mantenimiento/components/progress-bar/progress-bar.component.d.ts → types/jvsoft-components-tabla-mantenimiento-components-progress-bar.d.ts} +7 -3
  35. package/types/jvsoft-components-tabla-mantenimiento.d.ts +469 -0
  36. package/types/jvsoft-components.d.ts +9 -0
  37. package/alerta/alerta.component.d.ts +0 -29
  38. package/alerta/index.d.ts +0 -5
  39. package/alerta/public-api.d.ts +0 -1
  40. package/dialog-flotante/dialog-flotante.component.d.ts +0 -23
  41. package/dialog-flotante/dialog-flotante.interface.d.ts +0 -11
  42. package/dialog-flotante/index.d.ts +0 -5
  43. package/dialog-flotante/public-api.d.ts +0 -1
  44. package/filtro-busqueda/filtro-busqueda.component.d.ts +0 -89
  45. package/filtro-busqueda/filtro-busqueda.service.d.ts +0 -40
  46. package/filtro-busqueda/index.d.ts +0 -5
  47. package/filtro-busqueda/interfaces/filtro-busqueda.interface.d.ts +0 -86
  48. package/filtro-busqueda/public-api.d.ts +0 -3
  49. package/index.d.ts +0 -9
  50. package/lista-arbol/index.d.ts +0 -5
  51. package/lista-arbol/lista-arbol.component.d.ts +0 -57
  52. package/lista-arbol/lista-arbol.functions.d.ts +0 -8
  53. package/lista-arbol/public-api.d.ts +0 -1
  54. package/luces-navidad/index.d.ts +0 -5
  55. package/luces-navidad/public-api.d.ts +0 -1
  56. package/mat-suffix-search-button/index.d.ts +0 -5
  57. package/mat-suffix-search-button/public-api.d.ts +0 -1
  58. package/menu/index.d.ts +0 -5
  59. package/menu/menu.interface.d.ts +0 -16
  60. package/menu/public-api.d.ts +0 -2
  61. package/tabla-mantenimiento/classes/data-model.d.ts +0 -25
  62. package/tabla-mantenimiento/components/progress-bar/index.d.ts +0 -5
  63. package/tabla-mantenimiento/components/progress-bar/public-api.d.ts +0 -1
  64. package/tabla-mantenimiento/index.d.ts +0 -5
  65. package/tabla-mantenimiento/interfaces/Implements/incluye-tabla-mantenimiento.d.ts +0 -12
  66. package/tabla-mantenimiento/interfaces/Implements/index.d.ts +0 -1
  67. package/tabla-mantenimiento/interfaces/archivo.d.ts +0 -26
  68. package/tabla-mantenimiento/interfaces/global/boton-mantenimiento.d.ts +0 -41
  69. package/tabla-mantenimiento/interfaces/global/columnas-tabla.d.ts +0 -142
  70. package/tabla-mantenimiento/interfaces/global/index.d.ts +0 -3
  71. package/tabla-mantenimiento/interfaces/global/no-export.d.ts +0 -2
  72. package/tabla-mantenimiento/interfaces/global/otros.d.ts +0 -28
  73. package/tabla-mantenimiento/interfaces/index.d.ts +0 -3
  74. package/tabla-mantenimiento/mat-row-keyboard-selection.directive.d.ts +0 -19
  75. package/tabla-mantenimiento/pipes/no-sanitize.pipe.d.ts +0 -10
  76. package/tabla-mantenimiento/pipes/zero-fill.pipe.d.ts +0 -8
  77. package/tabla-mantenimiento/public-api.d.ts +0 -4
  78. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/column-type/column-type-date/column-type-date.component.d.ts +0 -8
  79. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/column-type/column-type-icons/column-type-icons.component.d.ts +0 -9
  80. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/column-type/column-type-money/column-type-money.component.d.ts +0 -9
  81. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/column-type/column-type-number/column-type-number.component.d.ts +0 -8
  82. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/column-type/column-type-progressbar/column-type-progressbar.component.d.ts +0 -8
  83. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/column-type/column-type-sino/column-type-sino.component.d.ts +0 -9
  84. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/column-type/column-type-text/column-type-text.component.d.ts +0 -8
  85. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/column-type/column-type.component.d.ts +0 -18
  86. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/column-type/column-type.module.d.ts +0 -24
  87. package/tabla-mantenimiento/tabla-mantenimiento-column-defs/tabla-mantenimiento-column-defs.component.d.ts +0 -21
  88. package/tabla-mantenimiento/tabla-mantenimiento-menu/tabla-mantenimiento-menu.component.d.ts +0 -18
  89. package/tabla-mantenimiento/tabla-mantenimiento.component.d.ts +0 -159
  90. package/tabla-mantenimiento/tabla-mantenimiento.functions.d.ts +0 -5
  91. package/tabla-mantenimiento/tabla-mantenimiento.service.d.ts +0 -8
  92. package/tabla-mantenimiento/table-util.d.ts +0 -11
@@ -0,0 +1,341 @@
1
+ # foto-persona
2
+
3
+ `@jvsoft/components/foto-persona` resuelve y pinta la foto de una persona a partir de su
4
+ `iPersId`. Es **una sola** entry point con las dos piezas del feature — antes vivían separadas
5
+ en `@jvsoft/utils/foto-persona` (el servicio) y `@jvsoft/components/foto-persona` (el
6
+ componente), lo que no seguía el patrón real de esta librería: `mat-form-controls` agrupa cada
7
+ feature completo (servicio + componente) en un único entry point, como `jvs-file-upload` y
8
+ `jvs-autocomplete`. Aquí pasa lo mismo:
9
+
10
+ - **`FotoPersonaService`** — consulta el manifiesto central `POST /api/imagenes/persona/lote`,
11
+ **acumulando** las peticiones que llegan en el mismo ciclo de detección de cambios para que una
12
+ tabla de cien filas cueste una sola petición HTTP en vez de cien.
13
+ - **`FotoPersonaComponent`** (selector `jvs-foto-persona`) — consume el servicio y traduce un
14
+ tamaño semántico (`tabla`, `tarjeta`, `ficha`) a lo que hay que pintar, sin que la plantilla
15
+ tenga que nombrar un preset ni un número de píxeles.
16
+
17
+ Ambos son **Standalone** y usan **Signals**. Ver el diseño completo del feature en
18
+ `docs/superpowers/specs/2026-09-06-fotos-s3-central-design.md` § 8.3 del backend.
19
+
20
+ ## 🚀 Uso básico
21
+
22
+ La mayoría de consumidores solo necesita el componente:
23
+
24
+ ```typescript
25
+ import { FotoPersonaComponent } from '@jvsoft/components/foto-persona';
26
+
27
+ @Component({
28
+ imports: [FotoPersonaComponent, ...],
29
+ // ...
30
+ })
31
+ export class MiComponente {}
32
+ ```
33
+
34
+ ```html
35
+ <jvs-foto-persona [iPersId]="fila.iPersId" tamano="tabla" [alt]="fila.cPersNombreCompleto" />
36
+ ```
37
+
38
+ Si el caso de uso necesita la URL directamente (sin pintar un `<img>`), se puede inyectar el
39
+ servicio a mano:
40
+
41
+ ```typescript
42
+ import { FotoPersonaService } from '@jvsoft/components/foto-persona';
43
+
44
+ @Component({ /* ... */ })
45
+ export class MiComponente {
46
+ private readonly fotoPersona = inject(FotoPersonaService);
47
+
48
+ iPersId = input<number | null>(null);
49
+ foto = this.fotoPersona.urlFoto(this.iPersId, 'avatar');
50
+ // foto() => { url: string|null, default: string|null, cargando: boolean }
51
+ }
52
+ ```
53
+
54
+ Para que una tabla anuncie de golpe lo que va a necesitar (por ejemplo, antes de renderizar
55
+ cien filas), usa `precargar()`:
56
+
57
+ ```typescript
58
+ this.fotoPersona.precargar(filas.map(f => f.iPersId), ['avatar']);
59
+ ```
60
+
61
+ ## Requisito: cablear `FOTO_PERSONA_CONFIG`
62
+
63
+ Ni el servicio ni el componente registran nada por su cuenta. La app consumidora debe:
64
+
65
+ 1. Tener `HttpClient` disponible (`provideHttpClient()`).
66
+ 2. Registrar `provideFotoPersona({ apiUrl })` en los providers de la aplicación. **Es
67
+ obligatorio**: sin `apiUrl`, la primera petición lanza
68
+ `FotoPersonaService: falta la URL del API`. No hay un "mismo origen" por defecto, a propósito:
69
+ un default silencioso escondía un token `FOTO_PERSONA_CONFIG` duplicado como un 404. Ver
70
+ "Configuración" más abajo.
71
+
72
+ ## 🛠 API del componente (`FotoPersonaComponent` / `<jvs-foto-persona>`)
73
+
74
+ ### Inputs (Signals)
75
+
76
+ | Input | Tipo | Default | Descripción |
77
+ |-------|------|---------|-------------|
78
+ | `iPersId` | `number \| null` | `null` | Id de la persona. `null` no pide nada al servicio, pero sí pinta el estático genérico `falta` en el tamaño que le toca — así un formulario sin persona elegida todavía reserva el hueco, en vez de una caja vacía que salta cuando se elige a alguien. |
79
+ | `tamano` | `TamanoFoto` | `'tabla'` | Tamaño semántico: `'tabla' \| 'tarjeta' \| 'ficha'`. |
80
+ | `alt` | `string` | `'Fotografía'` | Texto alternativo del `<img>` (o `aria-label` del placeholder). |
81
+ | `clases` | `string` | `''` | Clases CSS adicionales para el `<img>` o el placeholder. |
82
+
83
+ ### Tabla de tamaños
84
+
85
+ | `tamano` | contenedor | preset pedido | `width`×`height` fijados |
86
+ |---|---|---|---|
87
+ | `tabla` | 36×36 | `avatar` (80×80) | 36×36 |
88
+ | `tarjeta` | 80×80 | `avatar-grande` (160×160) | 80×80 |
89
+ | `ficha` | libre | `full` (hoy 160×225, el original) | 160×225 |
90
+
91
+ Los presets salen más grandes que el contenedor a propósito, para pantallas de densidad doble
92
+ (retina). `width`/`height` se fijan siempre, aunque `ficha` no tenga un contenedor fijo en el
93
+ diseño, para que el navegador reserve el hueco y la vista no salte al cargar.
94
+
95
+ ### Qué se pinta según el estado
96
+
97
+ | Estado del servicio | Qué pinta el componente |
98
+ |---|---|
99
+ | `iPersId` en `null` | El estático genérico `falta` (no se pide nada al servicio: nunca hay `cargando`). |
100
+ | `cargando: true` (todavía sin respuesta) | Un placeholder (`div`) del mismo `width`/`height`, con un fondo neutro. Nunca un `<img>` roto. |
101
+ | Foto real (`url`) | `<img [src]="url">`, con `loading="lazy"` y `decoding="async"`. |
102
+ | Sin foto, con `default` del servidor | El estático que indicó el servidor (`natural-f`, `entidad`, …), pedido al backend vía `FotoPersonaService.urlDefecto()`. |
103
+ | Falla de red ya resuelta (sin `url` ni `default`) | El estático genérico `falta`, también pedido al backend. No se reintenta sola con el paso del tiempo: reintenta si este componente se destruye y se vuelve a crear después del cooldown (ver "Reintentos" abajo). |
104
+
105
+ ### Imágenes de falta: asset local si la app lo configuró, backend si no
106
+
107
+ El componente prefiere un **asset local** para los estáticos de falta: si la app consumidora
108
+ configuró `assetsBasePath` en `provideFotoPersona()` (ver "Configuración" abajo), pinta
109
+ `${assetsBasePath}/${archivo}` — donde `archivo` sale del nombre que indicó el manifiesto
110
+ (`UrlFoto.default`) o `falta` si no hay ninguno. Si la app **no** configuró esa ruta, cae a pedir
111
+ `GET /api/imagenes/default/{nombre}/{preset}.{ext}` al backend (pública, sin autenticar, cacheada
112
+ un año) vía `FotoPersonaService.urlDefecto(nombre, preset)`, con el `preset` que le tocó a su
113
+ `tamano` — el comportamiento de siempre, sin cambios, para quien no empaquetó los archivos.
114
+
115
+ **Por qué empaquetar conviene:** las seis imágenes son chicas e idénticas para todas las
116
+ instalaciones; pedirlas por HTTP en cada instalación con caché fría no compra nada. Copiarlas a la
117
+ app resuelve eso con un asset del bundle en vez de una petición de red.
118
+
119
+ **Ojo con las extensiones mezcladas.** En origen (`backend/public/img/falta/`), `natural-m`,
120
+ `natural-f`, `entidad`, `extranjero-m` y `extranjero-f` son `.png`, pero `falta` —el último
121
+ recurso— es `.jpg`. Componer siempre `.png` se rompe justo ahí. `FotoPersonaService` resuelve esto
122
+ con un único mapa nombre→archivo (`rutaLocalDefecto()`); el componente nunca reconstruye el
123
+ nombre de archivo por su cuenta.
124
+
125
+ Los seis nombres posibles: `natural-m`, `natural-f`, `entidad`, `extranjero-m`, `extranjero-f` y
126
+ `falta` (genérico, cuando no hay ni foto ni un `default` específico — por ejemplo, tras una falla
127
+ de red). El backend responde 404 a cualquier otro nombre; el asset local cae al archivo de `falta`.
128
+
129
+ ## 🛠 API del servicio (`FotoPersonaService`)
130
+
131
+ ### `urlFoto(iPersId, preset)`
132
+
133
+ ```typescript
134
+ urlFoto(iPersId: Signal<number | null>, preset: Preset): Signal<UrlFoto>
135
+ ```
136
+
137
+ Devuelve una signal reactiva: cambia sola cuando `iPersId` cambia o cuando la petición pendiente
138
+ se resuelve. Dispara la petición la primera vez que se lee, si en ese momento la clave no está
139
+ confirmada, en curso ni en cooldown por una falla reciente (ver "Reintentos" abajo) — por eso un
140
+ `urlFoto()` nuevo (típicamente un componente que se crea) reintenta si el cooldown de una falla
141
+ anterior ya venció, pero la signal de un componente que ya estaba montado cuando falló **no** se
142
+ reintenta sola con el simple paso del tiempo: hace falta una lectura de verdad nueva. `iPersId` en
143
+ `null` no pide nada: devuelve el resultado vacío tal cual (url y default en `null`,
144
+ `cargando: false`).
145
+
146
+ ```typescript
147
+ interface UrlFoto {
148
+ url: string | null; // URL absoluta de la foto real, o null.
149
+ default: string | null; // nombre del estático de falta (natural-f, entidad, …), o null.
150
+ cargando: boolean; // true mientras el manifiesto todavía no responde.
151
+ }
152
+ ```
153
+
154
+ ### `precargar(ids, presets)`
155
+
156
+ ```typescript
157
+ precargar(ids: number[], presets: Preset[]): void
158
+ ```
159
+
160
+ Encola una petición para cada combinación id/preset que todavía no esté confirmada por el
161
+ servidor. También es el mecanismo de **reintento inmediato**: a diferencia de un `urlFoto()`
162
+ nuevo (que respeta el cooldown), `precargar()` vuelve a pedir de inmediato un id que quedó en
163
+ «sin foto» por una falla de red anterior, aunque siga en cooldown.
164
+
165
+ ### `urlDefecto(nombre, preset)`
166
+
167
+ ```typescript
168
+ urlDefecto(nombre: string, preset: Preset): string
169
+ ```
170
+
171
+ Arma la URL pública del estático de falta (`GET /api/imagenes/default/{nombre}/{preset}.{ext}`,
172
+ sin autenticar, cacheado un año) para el `nombre` que devolvió el manifiesto en `UrlFoto.default`.
173
+ La extensión sale del preset (WebP para `thumbnail`/`avatar`/`avatar-grande`, JPEG para
174
+ `full`/`medium` hoy), no del archivo real en el backend.
175
+
176
+ Es el **fallback**: se usa cuando la app no configuró `assetsBasePath` (ver abajo), o como
177
+ mecanismo de compatibilidad para cualquier instalación que no haya empaquetado los seis archivos.
178
+
179
+ Los seis nombres posibles: `natural-m`, `natural-f`, `entidad`, `extranjero-m`, `extranjero-f` y
180
+ `falta` (genérico). El backend responde 404 a cualquier otro nombre.
181
+
182
+ ### `rutaLocalDefecto(nombre)`
183
+
184
+ ```typescript
185
+ rutaLocalDefecto(nombre: string): string | null
186
+ ```
187
+
188
+ Arma la ruta del **asset local** para el estático de falta `nombre`, si la app configuró
189
+ `assetsBasePath`; `null` si no lo configuró (en ese caso el consumidor debe caer a `urlDefecto()`
190
+ — es justo lo que hace `FotoPersonaComponent`). A diferencia de `urlDefecto()`, **no recibe
191
+ `preset`**: las seis imágenes bundleadas son un solo archivo chico por nombre, no variantes
192
+ generadas por tamaño como las que sirve el backend.
193
+
194
+ Las seis imágenes viven en `backend/public/img/falta/` con extensiones mezcladas — cinco `.png`
195
+ (`natural-m`, `natural-f`, `entidad`, `extranjero-m`, `extranjero-f`) y una `.jpg` (`falta`, el
196
+ último recurso). Este método es la única fuente de verdad de esos nombres de archivo (mapa interno
197
+ `ARCHIVO_POR_DEFECTO`); ningún consumidor debe reconstruir `${nombre}.png` a mano — eso se rompía
198
+ justo en `falta`.
199
+
200
+ ```typescript
201
+ service.rutaLocalDefecto('natural-f'); // 'assets/img/falta/natural-f.png' (si assetsBasePath está configurado)
202
+ service.rutaLocalDefecto('falta'); // 'assets/img/falta/falta.jpg'
203
+ service.rutaLocalDefecto('natural-f'); // null (si assetsBasePath NO está configurado)
204
+ ```
205
+
206
+ Un `nombre` que no sea uno de los seis conocidos cae al archivo de `falta`.
207
+
208
+ ### `Preset`
209
+
210
+ ```typescript
211
+ type Preset = 'thumbnail' | 'avatar' | 'avatar-grande' | 'full' | 'medium';
212
+ ```
213
+
214
+ Corresponde 1:1 al enum PHP `JvSoft\Utils\Fotos\Preset` del backend.
215
+
216
+ ## ⚙️ Configuración (`FOTO_PERSONA_CONFIG` / `provideFotoPersona()`)
217
+
218
+ Sigue el mismo patrón que `ENCRYPTION_CONFIG`/`provideEncryption()`: un `InjectionToken` con
219
+ valores por defecto sensatos (lote de 200 ids, cooldown de 5 s, TTL de 8 h), salvo `apiUrl`, que
220
+ es obligatorio. `provideFotoPersona()` es el azúcar recomendado para registrarlo — acepta un objeto estático o una
221
+ **fábrica** que corre en contexto de inyección:
222
+
223
+ ```typescript
224
+ import { provideFotoPersona } from '@jvsoft/components/foto-persona';
225
+
226
+ providers: [
227
+ provideFotoPersona(() => {
228
+ const cfg = inject(ConfiguracionWebService);
229
+ return { apiUrl: () => cfg.backendApi };
230
+ }),
231
+ ]
232
+ ```
233
+
234
+ **`apiUrl` casi siempre debe ser un thunk (`() => string`), no un `string` ya leído.** En las apps
235
+ de JVSoft, `ConfiguracionWebService.apiData` se resuelve de forma **asíncrona** (un
236
+ `BehaviorSubject` que arranca en `null` y se llena después). Este servicio es `providedIn: 'root'`,
237
+ así que la fábrica de arriba corre **una sola vez**, la primera vez que algo lo inyecta — si en
238
+ ese momento se leyera `cfg.backendApi` como un valor plano (`{ apiUrl: cfg.backendApi }`), quedaría
239
+ congelado con lo que hubiera en ese instante (típicamente vacío, antes de que cargue `apiData`), y
240
+ **toda** petición futura saldría con esa base vieja o vacía. El thunk `() => cfg.backendApi`
241
+ evita esto: se vuelve a llamar en cada petición, así que siempre lee el valor más reciente.
242
+
243
+ Además, `apiUrl` es la **base del API completa**, `/api` incluido (lo mismo que ya resuelve
244
+ `backendApi`) — este servicio nunca concatena un `/api` propio. Antes el campo se llamaba
245
+ `backendUrl` y era solo el host (`apiData.backend`); el servicio le agregaba `/api` por su cuenta,
246
+ duplicando una decisión que ya le pertenece a la app y que no siempre es "host + /api" a secas
247
+ (`backendApi` puede venir configurado distinto por instalación).
248
+
249
+ También se puede registrar el token a mano, si se prefiere:
250
+
251
+ ```typescript
252
+ import { FOTO_PERSONA_CONFIG } from '@jvsoft/components/foto-persona';
253
+
254
+ providers: [
255
+ {
256
+ provide: FOTO_PERSONA_CONFIG,
257
+ useFactory: () => {
258
+ const cfg = inject(ConfiguracionWebService);
259
+ return { apiUrl: () => cfg.backendApi };
260
+ },
261
+ },
262
+ ]
263
+ ```
264
+
265
+ | Opción | Tipo | Default | Descripción |
266
+ |---|---|---|---|
267
+ | `apiUrl` | `string \| (() => string)` | *(obligatorio)* | Base del API, `/api` incluido, sin slash final. Vacío o ausente lanza `FotoPersonaService: falta la URL del API` en la primera petición. Prefiere un thunk si el valor real se resuelve de forma asíncrona (ver arriba). |
268
+ | `loteMax` | `number` | `200` | Tope de ids por petición de manifiesto. Debe coincidir con `jvsoft.fotos.lote_max` del backend. |
269
+ | `cooldownMs` | `number` | `5000` | Cuánto espera una clave que falló por red antes de volverse elegible para un reintento automático (ver abajo). |
270
+ | `ttlUrlMs` | `number` | `28800000` (8 h) | Cuánto se reutiliza en memoria una URL antes de volver a pedirla. Normalmente no hace falta tocarlo: el manifiesto anuncia el valor bueno en `X-Fotos-Ttl` y el servicio lo adopta. Ver "Las URL caducan" abajo. |
271
+ | `assetsBasePath` | `string` | *(sin configurar)* | Carpeta de assets donde la app empaquetó las seis imágenes de falta, sin slash final (p. ej. `assets/img/falta`, si siguió la convención de `angular.json` de servir `assets/` en la raíz). **Sin configurar, el comportamiento no cambia**: el estático de falta se sigue pidiendo al backend. Ver `rutaLocalDefecto()`. |
272
+
273
+ ### Empaquetar las seis imágenes de falta en la app (`assetsBasePath`)
274
+
275
+ Las seis imágenes (`natural-m`, `natural-f`, `entidad`, `extranjero-m`, `extranjero-f`, `falta`)
276
+ son chicas e idénticas para todas las instalaciones — pedirlas por HTTP en cada instalación con
277
+ caché fría no compra nada. Si la app las copia a su carpeta de assets (ver
278
+ `backend/public/img/falta/` como origen) y las declara en `angular.json`, basta con configurar
279
+ `assetsBasePath` en `provideFotoPersona()` para que `FotoPersonaComponent` las resuelva localmente
280
+ en vez de pedirlas al backend — el manifiesto sigue siendo quien decide *cuál* de las seis mostrar
281
+ (`UrlFoto.default`), solo cambia de dónde sale el archivo.
282
+
283
+ Si la app **no** copia los archivos, no hace falta tocar nada: sin `assetsBasePath`, el
284
+ comportamiento es exactamente el de antes (`urlDefecto()`, pedido al backend).
285
+
286
+ ## 🧠 Cómo funciona la acumulación
287
+
288
+ 1. Cada llamada a `urlFoto()` que no tiene nada confirmado, en curso ni en cooldown encola su id
289
+ bajo el preset pedido y programa un `queueMicrotask()` (si no hay uno ya programado).
290
+ 2. Al vaciarse la cola de microtasks, el servicio agrupa lo pendiente **por preset**, lo parte en
291
+ trozos de `loteMax` si hace falta, y dispara un `POST /api/imagenes/persona/lote` por trozo.
292
+ 3. La respuesta reparte cada resultado a su id y avisa a todas las signals abiertas.
293
+ 4. Los resultados confirmados por el servidor se guardan en memoria: pedir el mismo id + preset
294
+ otra vez no vuelve a llamar al backend, hasta que la URL caduque (ver abajo).
295
+
296
+ ## ⏳ Las URL caducan
297
+
298
+ Las URL de foto real van **firmadas** por el backend y tienen fecha de vencimiento (12 h como
299
+ máximo). Guardarlas para siempre acabaría pintando `<img>` con una firma vencida, así que la
300
+ memoria del servicio caduca:
301
+
302
+ - Una entrada que apunta a una **foto real** vive `ttlUrlMs`. Pasado ese tiempo, la siguiente
303
+ lectura la vuelve a pedir al manifiesto y obtiene una URL recién firmada.
304
+ - Una persona **sin foto** no caduca nunca: se resuelve con un estático (empaquetado en la app o
305
+ servido por la ruta pública `/api/imagenes/default/…`), que no lleva firma.
306
+
307
+ El valor efectivo lo manda el servidor en la cabecera `X-Fotos-Ttl` de cada manifiesto, y el
308
+ servicio lo adopta en cuanto lo ve. `ttlUrlMs` es solo el valor inicial y el respaldo para cuando
309
+ la cabecera no llega —por ejemplo si el backend está en otro origen y nadie la declaró en
310
+ `exposed_headers` de su CORS—. Una cabecera ausente o ilegible se ignora: nunca deja el TTL en
311
+ cero, que pediría el manifiesto en cada lectura.
312
+
313
+ Los tres plazos forman una escalera que el backend valida al arrancar: **firma (12 h) > caché del
314
+ navegador (11 h) > memoria del cliente (8 h)**.
315
+
316
+ ## 🔁 Reintentos: una falla de red no es una respuesta
317
+
318
+ Hay una diferencia entre **«el servidor contestó que no hay foto»** (una respuesta real, se
319
+ cachea para siempre) y **«no pudimos ni preguntar»** (una falla de red, que no es una respuesta y
320
+ no debe tratarse como una). Antes, una falla se guardaba igual que una respuesta confirmada y
321
+ solo `precargar()` podía destrabarla — como ningún componente llama a `precargar()` por su cuenta,
322
+ un corte de red pasajero dejaba a esa persona sin foto por el resto de la sesión. Ahora:
323
+
324
+ - Una falla deja el resultado inmediato en «sin foto» (no se cuelga en `cargando`, no lanza —
325
+ eso no cambió), pero la clave **no** queda confirmada.
326
+ - Entra en un cooldown corto (`cooldownMs`, 5 s por defecto). Mientras dura, nada la reintenta
327
+ sola — ni siquiera `urlFoto()` — salvo `precargar()`, que fuerza un reintento inmediato.
328
+ - Pasado el cooldown, la clave queda **elegible**, pero eso **no reintenta nada por sí solo**.
329
+ Hace falta una lectura de verdad nueva: un `urlFoto()` que se llama por primera vez (lo típico
330
+ es un componente que se crea — una fila nueva en una tabla, una navegación), o `precargar()`.
331
+ Un componente que ya estaba montado cuando la petición falló **se queda mostrando el estático**
332
+ hasta que algo lo lleve a pedir de nuevo (recargar la tabla con filas nuevas, navegar y volver,
333
+ o un `precargar()` explícito) — no reintenta solo con el paso del tiempo.
334
+ - **El cooldown venciendo no despierta a nadie.** Es deliberado, y fue un bug real en una versión
335
+ anterior: si vencer el cooldown volviera a evaluar las signals ya abiertas, cada componente que
336
+ falló reintentaría, fallaría de nuevo (si el backend sigue caído), programaría otro cooldown, y
337
+ ese cooldown, al vencer, repetiría el ciclo — un *poll* perpetuo contra el servidor, uno por
338
+ cada foto fallida, cada `cooldownMs`, sin que nadie lo pidiera. Por eso vencer el cooldown solo
339
+ cambia lo que una petición **nueva** va a encontrar; no dispara ninguna por su cuenta.
340
+ - Cada falla se registra con `console.warn()` (ids, preset y el error), para poder distinguir un
341
+ corte de red real de una petición malformada al revisar los logs.
package/package.json CHANGED
@@ -1,17 +1,17 @@
1
1
  {
2
2
  "name": "@jvsoft/components",
3
- "version": "1.0.0-alpha.15",
3
+ "version": "1.0.0-alpha.16",
4
4
  "description": "JVSOFT Angular Components",
5
5
  "publishConfig": {
6
6
  "tag": "alpha",
7
7
  "access": "public"
8
8
  },
9
9
  "peerDependencies": {
10
- "@angular/common": ">=16.0.0",
11
- "@angular/core": ">=16.0.0",
12
- "@angular/forms": ">=16.0.0",
13
- "@angular/material": ">=16.0.0",
14
- "@jvsoft/utils": "workspace:*",
10
+ "@angular/common": ">=17.1.0",
11
+ "@angular/core": ">=17.1.0",
12
+ "@angular/forms": ">=17.1.0",
13
+ "@angular/material": ">=17.1.0",
14
+ "@jvsoft/utils": "1.0.0-alpha.16",
15
15
  "tailwindcss": "3",
16
16
  "xlsx": "^0.18.5"
17
17
  },
@@ -23,7 +23,7 @@
23
23
  ".": {
24
24
  "sass": "./src/styles/base.scss",
25
25
  "default": "./fesm2022/jvsoft-components.mjs",
26
- "types": "./index.d.ts"
26
+ "types": "./types/jvsoft-components.d.ts"
27
27
  },
28
28
  "./tailwind": "./src/tailwind/index.js",
29
29
  "./base.scss": "./src/styles/base.scss",
@@ -31,42 +31,47 @@
31
31
  "default": "./package.json"
32
32
  },
33
33
  "./alerta": {
34
- "types": "./alerta/index.d.ts",
34
+ "types": "./types/jvsoft-components-alerta.d.ts",
35
35
  "default": "./fesm2022/jvsoft-components-alerta.mjs"
36
36
  },
37
37
  "./dialog-flotante": {
38
- "types": "./dialog-flotante/index.d.ts",
38
+ "types": "./types/jvsoft-components-dialog-flotante.d.ts",
39
39
  "default": "./fesm2022/jvsoft-components-dialog-flotante.mjs"
40
40
  },
41
41
  "./filtro-busqueda": {
42
- "types": "./filtro-busqueda/index.d.ts",
42
+ "types": "./types/jvsoft-components-filtro-busqueda.d.ts",
43
43
  "default": "./fesm2022/jvsoft-components-filtro-busqueda.mjs"
44
44
  },
45
+ "./foto-persona": {
46
+ "types": "./types/jvsoft-components-foto-persona.d.ts",
47
+ "default": "./fesm2022/jvsoft-components-foto-persona.mjs"
48
+ },
45
49
  "./lista-arbol": {
46
- "types": "./lista-arbol/index.d.ts",
50
+ "types": "./types/jvsoft-components-lista-arbol.d.ts",
47
51
  "default": "./fesm2022/jvsoft-components-lista-arbol.mjs"
48
52
  },
49
53
  "./luces-navidad": {
50
- "types": "./luces-navidad/index.d.ts",
54
+ "types": "./types/jvsoft-components-luces-navidad.d.ts",
51
55
  "default": "./fesm2022/jvsoft-components-luces-navidad.mjs"
52
56
  },
53
57
  "./mat-suffix-search-button": {
54
- "types": "./mat-suffix-search-button/index.d.ts",
58
+ "types": "./types/jvsoft-components-mat-suffix-search-button.d.ts",
55
59
  "default": "./fesm2022/jvsoft-components-mat-suffix-search-button.mjs"
56
60
  },
57
61
  "./menu": {
58
- "types": "./menu/index.d.ts",
62
+ "types": "./types/jvsoft-components-menu.d.ts",
59
63
  "default": "./fesm2022/jvsoft-components-menu.mjs"
60
64
  },
61
65
  "./tabla-mantenimiento": {
62
- "types": "./tabla-mantenimiento/index.d.ts",
66
+ "types": "./types/jvsoft-components-tabla-mantenimiento.d.ts",
63
67
  "default": "./fesm2022/jvsoft-components-tabla-mantenimiento.mjs"
64
68
  },
65
69
  "./tabla-mantenimiento/components/progress-bar": {
66
- "types": "./tabla-mantenimiento/components/progress-bar/index.d.ts",
70
+ "types": "./types/jvsoft-components-tabla-mantenimiento-components-progress-bar.d.ts",
67
71
  "default": "./fesm2022/jvsoft-components-tabla-mantenimiento-components-progress-bar.mjs"
68
72
  }
69
73
  },
70
74
  "module": "fesm2022/jvsoft-components.mjs",
71
- "typings": "index.d.ts"
75
+ "typings": "types/jvsoft-components.d.ts",
76
+ "type": "module"
72
77
  }