@kaufmann-lab/ui 0.1.26 → 0.1.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaufmann-lab/ui",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "Shared Angular component library for the Kaufmann frontends",
   "license": "MIT",
   "author": "Kaufmann Lab",

package/types/kaufmann-lab-ui-core.d.ts

@@ -220,11 +220,44 @@ declare class Button {
 type AlertTone = 'info' | 'ok' | 'warn' | 'error';
 /** Forma del aviso: `card` (default, con borde y esquinas) o `bar` (franja compacta de ancho completo). */
 type AlertVariant = 'card' | 'bar';
+/**
+ * Apariencia de la variante `card`: `tile` (default), `tint` o `rail`. Ver el
+ * JSDoc de `Alert` para cuándo usar cada una.
+ */
+type AlertAppearance = 'tile' | 'tint' | 'rail';
 /**
  * Banner contextual que vive dentro del flujo: validaciones, avisos de
  * vencimiento, confirmaciones. Persiste hasta que se descarta o hasta que la
  * condición que lo causó desaparece — para feedback efímero está el toast.
  *
+ * Diseño sobrio: el título va en peso 600 con la tipografía de cuerpo y el
+ * mensaje con medida de lectura limitada, ambos en los neutros del sistema (el
+ * color del tono nunca se usa para texto). El ícono va centrado en vertical
+ * respecto al aviso. El color sale siempre de los tokens (`*-strong`), nunca de
+ * un input. Ninguna apariencia lleva borde ni acento lateral de color.
+ *
+ * `appearance` elige cómo se muestra el tono (solo aplica a `variant="card"`):
+ *
+ * - `tile` (default): aviso estándar dentro de pantallas y cards. Tarjeta de
+ *   superficie y borde neutros; el color vive solo en el ícono, un tile sólido de
+ *   40px con glifo blanco.
+ *
+ *     <kf-alert tone="warn" title="SOAT por vencer">Vence el 15/08.</kf-alert>
+ *
+ * - `tint`: aviso liviano sobre fondos neutros o en zonas densas, donde el tinte
+ *   basta. Relleno suave del tono, sin borde ni tile; glifo de 24px en el color
+ *   fuerte del tono.
+ *
+ *     <kf-alert appearance="tint" tone="info">Cita confirmada para el jueves.</kf-alert>
+ *
+ * - `rail`: aviso destacado que debe notarse al primer vistazo, p. ej. errores o
+ *   bloqueos. Panel de ícono de 56px a todo el alto, con el fondo del tono más
+ *   intenso, y cuerpo neutro con borde neutro.
+ *
+ *     <kf-alert appearance="rail" tone="error" title="Pago rechazado">
+ *       Tu banco no autorizó el cargo.
+ *     </kf-alert>
+ *
  * `open` es two-way: el botón de cerrar lo pone en `false` y el componente
  * deja de renderizar. El consumidor puede volver a abrirlo poniéndolo en
  * `true` (ej. cuando la validación falla otra vez).
@@ -238,15 +271,32 @@ type AlertVariant = 'card' | 'bar';
  * tonos y mismo `role` (`alert` para `error`/`warn`, `status` para el resto)
  * que la variante `card`. Pensada para el borde de una página o de un panel
  * (ej. "Estás viendo datos de otro cliente"), donde una tarjeta con margen
- * sobra.
+ * sobra. `variant="bar"` ignora `appearance`: la franja siempre usa su propia
+ * superficie tintada.
  *
  *   <kf-alert variant="bar" tone="warn" title="Modo suplantación">Viendo como Ana Pérez.</kf-alert>
+ *
+ * Los elementos con el atributo `kfAlertActions` se proyectan a la derecha del
+ * mensaje cuando hay ancho y, si no caben, en una fila propia bajo él, apilados
+ * y alineados al inicio (en la variante `bar` siempre van en fila propia). Si los
+ * envuelves en un solo `<div kfAlertActions>`, el aviso separa a sus hijos (12px).
+ * Sin ellos la zona no existe y el aviso queda igual.
+ *
+ *   <kf-alert tone="warn" title="SOAT por vencer">
+ *     Vence el 15/08.
+ *     <div kfAlertActions><kf-button size="sm">Renovar</kf-button></div>
+ *   </kf-alert>
  */
 declare class Alert {
     readonly tone: _angular_core.InputSignal<AlertTone>;
     /** `card` (default) o `bar` (franja compacta de ancho completo). */
     readonly variant: _angular_core.InputSignal<AlertVariant>;
-    /** Línea en negrita arriba del mensaje. Vacío deja solo el contenido proyectado. */
+    /**
+     * `tile` (default), `tint` o `rail`. Solo aplica a `variant="card"`; `bar` la
+     * ignora. Se expone en el host como `data-appearance`.
+     */
+    readonly appearance: _angular_core.InputSignal<AlertAppearance>;
+    /** Título (peso 600) arriba del mensaje. Vacío deja solo el contenido proyectado. */
     readonly title: _angular_core.InputSignal<string>;
     readonly dismissible: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Visibilidad, two-way: `[(open)]="hasError"`. */
@@ -257,8 +307,10 @@ declare class Alert {
      */
     protected readonly ariaRole: _angular_core.Signal<"alert" | "status">;
     protected readonly toneIcon: _angular_core.Signal<IconName>;
+    /** Glifo: 16px en `bar`, 20px en `tile` y 24px en `tint`/`rail`. */
+    protected readonly iconSize: _angular_core.Signal<IconSize>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Alert, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Alert, "kf-alert", never, { "tone": { "alias": "tone"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "dismissible": { "alias": "dismissible"; "required": false; "isSignal": true; }; "open": { "alias": "open"; "required": false; "isSignal": true; }; }, { "open": "openChange"; }, never, ["*"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Alert, "kf-alert", never, { "tone": { "alias": "tone"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "appearance": { "alias": "appearance"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "dismissible": { "alias": "dismissible"; "required": false; "isSignal": true; }; "open": { "alias": "open"; "required": false; "isSignal": true; }; }, { "open": "openChange"; }, never, ["*", "[kfAlertActions]"], true, never>;
 }
 
 type AlertRowTone = 'warn' | 'error' | 'neutral';
@@ -938,6 +990,12 @@ type DataTableDensity = 'comfortable' | 'compact';
 /** `key:direction` — mismo formato que `sort` de `kf-quote-picker`, para
  * que un consumidor que ya conoce ese patrón no aprenda uno nuevo acá. */
 type DataTableSort = `${string}:${'asc' | 'desc'}`;
+/** Nombre de la entidad listada: un `string` (plural fijo) o `{ one, other }`
+ * para usar el singular cuando el total es 1. */
+type DataTableItemLabel = string | {
+    one: string;
+    other: string;
+};
 /**
  * Tabla estandarizada con soporte opcional de toggle tabla/cards.
  *
@@ -1002,9 +1060,11 @@ type DataTableSort = `${string}:${'asc' | 'desc'}`;
  * por página" viene activo por defecto con `DEFAULT_PAGE_SIZE_OPTIONS`
  * ([10, 25, 50], estándar del portal) — pasar `pageSizeOptions` propio lo
  * pisa, y pasar `[]` lo desactiva (paginación sin selector). `itemLabel`
- * completa el texto informativo ("1–10 de 42 beneficios").
+ * completa el texto informativo ("1–10 de 42 beneficios"); con
+ * `{ one, other }` usa el singular cuando el total es 1 ("1–1 de 1 beneficio").
  *
  *   <kf-data-table [columns]="columns" [rows]="rows" [pageSize]="25" itemLabel="beneficios" />
+ *   <kf-data-table [columns]="columns" [rows]="rows" [pageSize]="25" [itemLabel]="{ one: 'unidad', other: 'unidades' }" />
  *   <kf-data-table [columns]="columns" [rows]="rows" [pageSize]="25" [pageSizeOptions]="[]" />
  *
  * La página es `[(page)]` (el consumidor puede llevarla a la URL) y se
@@ -1225,10 +1285,13 @@ declare class DataTable<T = unknown> {
     readonly pageSizeChange: _angular_core.OutputEmitterRef<number>;
     /** Nombre de la entidad listada (ej. "beneficios", "facturas"), en
      * plural — se agrega al final del texto informativo de la paginación
-     * interna ("1–5 de 7 beneficios"). Sin esto, el texto queda solo con
-     * números ("1–5 de 7"): la librería no impone un idioma ni un nombre
-     * fijo, cada consumidor decide el suyo. */
-    readonly itemLabel: _angular_core.InputSignal<string>;
+     * interna ("1–5 de 7 beneficios"). Acepta `{ one, other }` para usar el
+     * singular cuando el total es 1 ("1–1 de 1 beneficio"); un `string`
+     * conserva el comportamiento de siempre (mismo texto para cualquier
+     * total). Sin esto, el texto queda solo con números ("1–5 de 7"): la
+     * librería no impone un idioma ni un nombre fijo, cada consumidor decide
+     * el suyo. */
+    readonly itemLabel: _angular_core.InputSignal<DataTableItemLabel>;
     private readonly internalPageSize;
     /** Tamaño de página efectivo: el que el usuario elija en el selector
      * (si `pageSizeOptions` está activo), o el `pageSize` del consumidor. */
@@ -1438,7 +1501,7 @@ declare class SkeletonPreset {
     protected readonly items: _angular_core.Signal<number[]>;
     /** Columnas de la tabla sintética (encabezados en blanco: lo real aún no llegó). */
     protected readonly tableColumns: _angular_core.Signal<DataTableColumn[]>;
-    protected readonly formColumns: _angular_core.Signal<1 | 2>;
+    protected readonly formColumns: _angular_core.Signal<2 | 1>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SkeletonPreset, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SkeletonPreset, "kf-skeleton-preset", never, { "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "count": { "alias": "count"; "required": false; "isSignal": true; }; "columns": { "alias": "columns"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
@@ -4341,6 +4404,12 @@ declare class Select {
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Borde en rojo y `aria-invalid` en el trigger. Ver `errorMessage` para el mensaje asociado — mismo contrato que `kf-input`. */
     readonly invalid: _angular_core.InputSignalWithTransform<boolean, unknown>;
+    /**
+     * Pone el asterisco rojo en la etiqueta (igual que `kf-input`) y
+     * `aria-required="true"` en el trigger. Solo señaliza: la validación sigue
+     * en el formulario del consumidor.
+     */
+    readonly required: _angular_core.InputSignalWithTransform<boolean, unknown>;
     /** Mensaje de error con `role="alert"`, debajo del trigger. */
     readonly errorMessage: _angular_core.InputSignal<string | undefined>;
     readonly variant: _angular_core.InputSignal<"field" | "compact">;
@@ -4501,7 +4570,7 @@ declare class Select {
     private scrollActiveIntoView;
     selectActive(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Select, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Select, "kf-select", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "hideLabel": { "alias": "hideLabel"; "required": false; "isSignal": true; }; "prefix": { "alias": "prefix"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": true; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "errorMessage": { "alias": "errorMessage"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "searchThreshold": { "alias": "searchThreshold"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "panelTitle": { "alias": "panelTitle"; "required": false; "isSignal": true; }; "panelWidth": { "alias": "panelWidth"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Select, "kf-select", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "hideLabel": { "alias": "hideLabel"; "required": false; "isSignal": true; }; "prefix": { "alias": "prefix"; "required": false; "isSignal": true; }; "options": { "alias": "options"; "required": true; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "errorMessage": { "alias": "errorMessage"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "width": { "alias": "width"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "searchable": { "alias": "searchable"; "required": false; "isSignal": true; }; "searchThreshold": { "alias": "searchThreshold"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "panelTitle": { "alias": "panelTitle"; "required": false; "isSignal": true; }; "panelWidth": { "alias": "panelWidth"; "required": false; "isSignal": true; }; }, { "valueChange": "valueChange"; }, never, never, true, never>;
 }
 
 interface SelectableCardOption {
@@ -4629,8 +4698,13 @@ declare class SidebarShell {
      * muestra todo expandido.
      */
     readonly itemsCollapsed: _angular_core.Signal<boolean>;
-    /** Cierra el panel mobile con Escape — mismo criterio que `Dropdown`/`Modal`/`Drawer`. */
-    protected onEscape(): void;
+    /**
+     * Cierra el panel mobile con Escape — mismo criterio que `Drawer`: si un
+     * panel flotante de adentro (`kf-dropdown`, `kf-select`) ya consumió la
+     * tecla en captura (`defaultPrevented`), el panel mobile sigue abierto y
+     * solo cierra la capa superior.
+     */
+    protected onEscape(event: Event): void;
     protected onNavItemClick(event: Event, item: SidebarNavItemData): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<SidebarShell, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<SidebarShell, "kf-sidebar-shell", never, { "navItems": { "alias": "navItems"; "required": false; "isSignal": true; }; "collapsed": { "alias": "collapsed"; "required": false; "isSignal": true; }; "mobileOpen": { "alias": "mobileOpen"; "required": false; "isSignal": true; }; }, { "collapsed": "collapsedChange"; "mobileOpen": "mobileOpenChange"; "navItemClick": "navItemClick"; }, never, ["[kf-sidebar-brand]", "[kf-sidebar-brand-collapsed]", "[kf-sidebar-footer]", "[kf-sidebar-brand-mobile]"], true, never>;
@@ -4689,6 +4763,8 @@ declare class Spinner {
 }
 
 type StatCardTone = 'primary' | 'success' | 'error' | 'purple' | 'warn' | 'info' | 'neutral';
+/** Tono de la insignia (`badge`): los roles semánticos de `kf-badge` salvo `service`. */
+type StatCardBadgeTone = 'neutral' | 'ok' | 'warn' | 'error' | 'info';
 /** Densidad de la card: `'compact'` reduce el padding, el ícono y el valor. */
 type StatCardDensity = 'default' | 'compact';
 /**
@@ -4715,6 +4791,21 @@ type StatCardDensity = 'default' | 'compact';
  *   <kf-stat-card icon="clock" tone="warn" value="7" label="Por vencer" [bar]="35" hint="7 de 20"
  *     clickable [pressed]="filter() === 'due'" (cardClick)="toggle('due')" />
  *
+ * - `badge` (+ `badgeTone`, default `'neutral'`): insignia (`kf-badge`) a la
+ *   derecha de la etiqueta, para un estado puntual ("Urgente", "Nuevo"). Es
+ *   texto real en el DOM, así que un lector de pantalla lo lee tras la
+ *   etiqueta: el tono refuerza el significado, no lo porta solo. Si el
+ *   ancho no alcanza, baja a la línea siguiente en vez de recortarse. Sin
+ *   `badge` (o con texto vacío) la card no cambia. Funciona con `density`,
+ *   `clickable` y `loading`.
+ *
+ *   <kf-stat-card icon="clock" tone="warn" value="7" label="Por vencer" badge="Urgente" badgeTone="error" />
+ *
+ * Alto: la card ocupa el 100% del alto de su contenedor cuando este lo fija
+ * (celda de una grilla o ítem estirado de un flex), de modo que las cards de
+ * una misma fila miden igual sin `::ng-deep`. En un contenedor de alto
+ * automático mide lo que su contenido, como siempre.
+ *
  * `density` (`'default'` | `'compact'`): `'compact'` es la variante para
  * pantallas angostas — padding de `--kf-space-md`, ícono de 40px y valor de
  * `--kf-font-size-title-sm`, con el mismo contenido. Si la card mide 210px de
@@ -4730,7 +4821,7 @@ type StatCardDensity = 'default' | 'compact';
  * `loading` (default `false`): mientras es `true` la card dibuja su esqueleto
  * en vez del contenido, con el MISMO cascarón (borde, padding, ícono de 50px)
  * y líneas del alto real de cada texto — valor, etiqueta y, si se pasaron,
- * nota, barra y `hint` —, así que al llegar los datos no hay salto de
+ * nota, barra, `hint` e insignia —, así que al llegar los datos no hay salto de
  * layout. Pasa los mismos inputs que usarás cargada para que el esqueleto
  * reserve las mismas líneas. Marca la card con `aria-busy="true"`, no es
  * clicable ni expone su texto a lectores de pantalla mientras carga.
@@ -4747,6 +4838,10 @@ declare class StatCard {
     readonly bar: _angular_core.InputSignal<number | null | undefined>;
     /** Texto secundario bajo la barra (o bajo la nota si no hay barra). */
     readonly hint: _angular_core.InputSignal<string | undefined>;
+    /** Texto de la insignia a la derecha de la etiqueta; vacío/ausente = sin insignia. */
+    readonly badge: _angular_core.InputSignal<string | undefined>;
+    /** Tono semántico de la insignia (`kf-badge`). */
+    readonly badgeTone: _angular_core.InputSignal<StatCardBadgeTone>;
     /**
      * Estado de alternancia (`aria-pressed`) cuando la card es `clickable`.
      * `null` (default) = no aplica: el atributo no se emite.
@@ -4762,7 +4857,7 @@ declare class StatCard {
     protected readonly barTone: _angular_core.Signal<ProgressTone>;
     protected readonly hasBar: _angular_core.Signal<boolean>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<StatCard, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StatCard, "kf-stat-card", never, { "icon": { "alias": "icon"; "required": true; "isSignal": true; }; "tone": { "alias": "tone"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": true; "isSignal": true; }; "note": { "alias": "note"; "required": false; "isSignal": true; }; "bar": { "alias": "bar"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "pressed": { "alias": "pressed"; "required": false; "isSignal": true; }; "density": { "alias": "density"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "clickable": { "alias": "clickable"; "required": false; "isSignal": true; }; }, { "cardClick": "cardClick"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StatCard, "kf-stat-card", never, { "icon": { "alias": "icon"; "required": true; "isSignal": true; }; "tone": { "alias": "tone"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": true; "isSignal": true; }; "label": { "alias": "label"; "required": true; "isSignal": true; }; "note": { "alias": "note"; "required": false; "isSignal": true; }; "bar": { "alias": "bar"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "badge": { "alias": "badge"; "required": false; "isSignal": true; }; "badgeTone": { "alias": "badgeTone"; "required": false; "isSignal": true; }; "pressed": { "alias": "pressed"; "required": false; "isSignal": true; }; "density": { "alias": "density"; "required": false; "isSignal": true; }; "loading": { "alias": "loading"; "required": false; "isSignal": true; }; "clickable": { "alias": "clickable"; "required": false; "isSignal": true; }; }, { "cardClick": "cardClick"; }, never, never, true, never>;
 }
 
 /** Vocabulario semántico único de tono, compartido con `TextTone`. */
@@ -4811,6 +4906,11 @@ declare class StatTile {
     readonly tone: _angular_core.InputSignal<StatTileTone>;
     /** Tercera línea bajo el valor. Vacía cae en `notePlaceholder`. */
     readonly note: _angular_core.InputSignal<string | null | undefined>;
+    /** Máximo de líneas visibles de la nota antes de la elipsis (`…`); el texto
+     * completo sigue en el DOM y en el `title`. Default 2, como siempre. Un
+     * valor menor a 1 o no numérico no limita la altura: la nota se muestra
+     * entera. */
+    readonly noteLines: _angular_core.InputSignalWithTransform<number, unknown>;
     /** Qué dice la tercera línea cuando no hay nota. Cada consumidor debería
      * pasar el motivo real de SU dato ausente, no un texto genérico. */
     readonly notePlaceholder: _angular_core.InputSignal<string | undefined>;
@@ -4858,9 +4958,11 @@ declare class StatTile {
      */
     protected onKeydown(event: KeyboardEvent): void;
     protected onKeyup(event: KeyboardEvent): void;
+    /** Valor de `line-clamp`: entero ≥ 1, o `none` para mostrar la nota entera. */
+    protected readonly noteClamp: _angular_core.Signal<string>;
     protected readonly noteIsPlaceholder: _angular_core.Signal<boolean>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<StatTile, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StatTile, "kf-stat-tile", never, { "cta": { "alias": "cta"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "tone": { "alias": "tone"; "required": false; "isSignal": true; }; "note": { "alias": "note"; "required": false; "isSignal": true; }; "notePlaceholder": { "alias": "notePlaceholder"; "required": false; "isSignal": true; }; "valueMissing": { "alias": "valueMissing"; "required": false; "isSignal": true; }; "hasProjectedValue": { "alias": "hasProjectedValue"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "actionLabel": { "alias": "actionLabel"; "required": false; "isSignal": true; }; "actionHref": { "alias": "actionHref"; "required": false; "isSignal": true; }; "interactive": { "alias": "interactive"; "required": false; "isSignal": true; }; "pressed": { "alias": "pressed"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; }, { "actionClick": "actionClick"; "tileClick": "tileClick"; }, never, ["[valueContent]"], true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<StatTile, "kf-stat-tile", never, { "cta": { "alias": "cta"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": false; "isSignal": true; }; "value": { "alias": "value"; "required": false; "isSignal": true; }; "icon": { "alias": "icon"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "tone": { "alias": "tone"; "required": false; "isSignal": true; }; "note": { "alias": "note"; "required": false; "isSignal": true; }; "noteLines": { "alias": "noteLines"; "required": false; "isSignal": true; }; "notePlaceholder": { "alias": "notePlaceholder"; "required": false; "isSignal": true; }; "valueMissing": { "alias": "valueMissing"; "required": false; "isSignal": true; }; "hasProjectedValue": { "alias": "hasProjectedValue"; "required": false; "isSignal": true; }; "title": { "alias": "title"; "required": false; "isSignal": true; }; "description": { "alias": "description"; "required": false; "isSignal": true; }; "actionLabel": { "alias": "actionLabel"; "required": false; "isSignal": true; }; "actionHref": { "alias": "actionHref"; "required": false; "isSignal": true; }; "interactive": { "alias": "interactive"; "required": false; "isSignal": true; }; "pressed": { "alias": "pressed"; "required": false; "isSignal": true; }; "expanded": { "alias": "expanded"; "required": false; "isSignal": true; }; }, { "actionClick": "actionClick"; "tileClick": "tileClick"; }, never, ["[valueContent]"], true, never>;
 }
 
 /**
@@ -4954,12 +5056,19 @@ type SwitchSize = 'sm' | 'md';
  * switch hace que el valor llegue dos veces al consumidor: usar una sola de
  * las dos vías, o ignorar en el handler el eco que no cambia el valor.
  *
+ * `describedBy` recibe el `id` de un texto de ayuda externo (ej. el `<p>` de
+ * una fila de preferencias) y lo enlaza con `aria-describedby` del botón, para
+ * que el lector de pantalla lo anuncie junto al nombre y el estado. Sin valor,
+ * el atributo no se renderiza.
+ *
  * El color sale de roles (`--kf-color-primary` encendido,
  * `--kf-color-border-control` apagado) y el foco de `--kf-shadow-focus`; no
  * recibe colores.
  *
  *   <kf-switch label="Fijar indicadores" [(checked)]="pinned" />
  *   <kf-switch label="Mapa junto a la tabla" hideLabel size="sm" formControlName="splitMap" />
+ *   <kf-switch label="Alertas por correo" describedBy="mail-hint" [(checked)]="mail" />
+ *   <p id="mail-hint">Se envía un resumen cada hora.</p>
  */
 declare class Switch implements ControlValueAccessor {
     /** Nombre accesible y texto visible (salvo con `hideLabel`). */
@@ -4968,6 +5077,8 @@ declare class Switch implements ControlValueAccessor {
     readonly hideLabel: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;
     readonly size: _angular_core.InputSignal<SwitchSize>;
+    /** `id` del texto de ayuda que describe al interruptor (`aria-describedby`). */
+    readonly describedBy: _angular_core.InputSignal<string | null>;
     /** Estado encendido, two-way: `[(checked)]="pinned"`. */
     readonly checked: _angular_core.ModelSignal<boolean>;
     private readonly disabledByForm;
@@ -4981,7 +5092,7 @@ declare class Switch implements ControlValueAccessor {
     registerOnTouched(fn: () => void): void;
     setDisabledState(isDisabled: boolean): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Switch, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Switch, "kf-switch", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "hideLabel": { "alias": "hideLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "checked": { "alias": "checked"; "required": false; "isSignal": true; }; }, { "checked": "checkedChange"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Switch, "kf-switch", never, { "label": { "alias": "label"; "required": true; "isSignal": true; }; "hideLabel": { "alias": "hideLabel"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "describedBy": { "alias": "describedBy"; "required": false; "isSignal": true; }; "checked": { "alias": "checked"; "required": false; "isSignal": true; }; }, { "checked": "checkedChange"; }, never, never, true, never>;
 }
 
 interface TabOption {
@@ -5073,6 +5184,16 @@ declare class FolderTabs {
  *
  *   <kf-textarea label="Detalle" formControlName="detail" [maxRows]="12" />
  *
+ * `maxlength` limita el texto (`maxlength` nativo, entero positivo) y
+ * `showCounter` agrega el contador «0 / 500» pegado bajo el campo, en la misma
+ * fila que el `hint`/`errorMessage`. Ambos son opt-in: sin ellos el campo no
+ * cambia. El contador sin `maxlength` no se muestra (no hay tope que contar).
+ * Visualmente pasa a rojo al llegar al tope; para lectores de pantalla solo
+ * anuncia (`aria-live="polite"`) al cruzar el 90 % y al llegar al límite, no
+ * en cada tecla.
+ *
+ *   <kf-textarea label="Motivo" formControlName="reason" [maxlength]="500" showCounter />
+ *
  * `invalid` + `errorMessage` y `readonly`/`disabled` siguen el mismo
  * contrato que `kf-input` — ver su JSDoc para la diferencia entre ambos
  * estados.
@@ -5099,15 +5220,29 @@ declare class Textarea implements ControlValueAccessor, AfterViewInit {
     readonly minRows: _angular_core.InputSignal<number>;
     /** Filas máximas antes de que el contenido pase a scroll interno en vez de seguir creciendo. */
     readonly maxRows: _angular_core.InputSignal<number>;
+    /** Largo máximo del texto (`maxlength` nativo), entero positivo. */
+    readonly maxlength: _angular_core.InputSignalWithTransform<number | null, string | number | null | undefined>;
+    /** Muestra el contador «n / maxlength» bajo el campo. Requiere `maxlength`. */
+    readonly showCounter: _angular_core.InputSignalWithTransform<boolean, unknown>;
     protected readonly textareaId: string;
     protected readonly hintId: string;
     protected readonly errorId: string;
+    protected readonly counterId: string;
     protected readonly value: _angular_core.WritableSignal<string>;
     protected readonly focused: _angular_core.WritableSignal<boolean>;
     /** Deshabilitado por Reactive Forms (formControl.disable()). */
     private readonly disabledByForm;
     /** Disabled real: por input() directo o por el FormControl asociado. */
     protected readonly isDisabled: _angular_core.Signal<boolean>;
+    protected readonly counterVisible: _angular_core.Signal<boolean>;
+    protected readonly atLimit: _angular_core.Signal<boolean>;
+    /**
+     * Texto del `aria-live`: cambia solo al cruzar un umbral (90 % y tope), así
+     * el lector no lee cada carácter escrito cerca del límite.
+     */
+    protected readonly counterAnnouncement: _angular_core.Signal<string>;
+    /** Hint o error, más el contador cuando se muestra. */
+    protected readonly describedBy: _angular_core.Signal<string | null>;
     private onChange;
     private onTouched;
     ngAfterViewInit(): void;
@@ -5126,7 +5261,7 @@ declare class Textarea implements ControlValueAccessor, AfterViewInit {
      */
     private adjustHeight;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<Textarea, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Textarea, "kf-textarea", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "errorMessage": { "alias": "errorMessage"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "minRows": { "alias": "minRows"; "required": false; "isSignal": true; }; "maxRows": { "alias": "maxRows"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<Textarea, "kf-textarea", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "invalid": { "alias": "invalid"; "required": false; "isSignal": true; }; "errorMessage": { "alias": "errorMessage"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "readonly": { "alias": "readonly"; "required": false; "isSignal": true; }; "placeholder": { "alias": "placeholder"; "required": false; "isSignal": true; }; "minRows": { "alias": "minRows"; "required": false; "isSignal": true; }; "maxRows": { "alias": "maxRows"; "required": false; "isSignal": true; }; "maxlength": { "alias": "maxlength"; "required": false; "isSignal": true; }; "showCounter": { "alias": "showCounter"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 /**
@@ -5466,4 +5601,4 @@ declare class ViewToggle {
 }
 
 export { ActionTile, AdminBadge, Alert, AlertRow, Avatar, Badge, Breadcrumb, BucketProgress, Button, Calendar, Card, Carousel, CarouselSlide, Checkbox, Chip, Collapsible, ContactPopover, ContentSlot, ContentState, ContentStateLoading, ContentViewer, CursorPager, DATA_TABLE_MAX_SKELETON_ROWS, DEFAULT_MILESTONE_TIMELINE_LABELS, DEFAULT_PAGE_SIZE_OPTIONS, DataTable, Divider, DocumentRow, Drawer, Dropdown, DropdownItem, DropdownPanel, EmptyState, EventTimeline, FeatureCard, Field, FieldLabel, FileInput, Filter, FilterChips, FolderTabs, FolderTabsPanel, Footer, FormatInputDirective, Icon, Input, JourneyStepper, LIST_TOOLBAR_HYSTERESIS, Link, ListToolbar, MetricCard, MilestoneTimeline, Modal, MultiSelect, NoteBlock, OptionList, PROGRESS_STATUS, PROGRESS_STATUS_LABEL, PageHeader, Pagination, Panel, PopoverDirective, PortalHeader, Progress, PulseDot, RowActions, SKELETON_PRESET_MAX_COUNT, SectionHeader, SectionNav, SectionNavItem, SectionNavSubsection, Segmented, Select, SelectableCardGroup, SidebarShell, Skeleton, SkeletonPreset, Spinner, StatCard, StatTile, StatusMark, StatusNode, StatusPill, Switch, TOAST_DEFAULT_DURATION_MS, Tabs, Text, Textarea, TileGrid, TimeSlotPicker, ToastHost, ToastService, TooltipDirective, ViewToggle, dataTableViewSignal, formatFileSize, resolveListToolbarMode };
-export type { AlertRowTone, AlertTone, AlertVariant, BreadcrumbItem, BucketProgressItem, CalendarDay, ContentStateKind, ContentStateLoad, ContentViewerType, DataTableCardRole, DataTableCellClick, DataTableColumn, DataTableDensity, DataTableSort, DataTableView, DividerOrientation, DocumentRowTone, DrawerRole, DrawerSide, DropdownItemTone, DropdownPanelRole, DropdownPanelVariant, EmptyStateTone, EventTimelineItem, EventTimelineTone, FileRejection, FileRejectionReason, FilterChipOption, FilterFieldChange, FilterFieldConfig, FilterFieldType, FilterValue, FolderTabOption, FooterLink, IconName, IconRotation, IconSize, InputBound, JourneyStep, JourneyStepStatus, JourneyStepperColorScheme, JourneyStepperOrientation, JourneyStepperSurface, LinkVariant, ListToolbarMode, MilestoneGroup, MilestoneItem, MilestoneTimelineLabels, ModalSize, MultiSelectOption, NoteBlockTone, OptionListOption, PageHeaderTitleSize, PaginationItem, PopoverPlacement, PortalHeaderAdminAction, PortalHeaderNavItem, ProgressSize, ProgressStatus, ProgressTone, RowAction, RowActionKind, RowActionsMode, SectionNavSubsectionData, SegmentedOption, SelectOption, SelectableCardOption, SidebarNavItemData, SkeletonPresetVariant, SkeletonVariant, SpinnerSize, StatCardDensity, StatCardTone, StatTileTone, StatTileVariant, SwitchSize, TabOption, TextAs, TextTone, TextVariant, TimeSlot, ToastAction, ToastOptions, ToastPromiseMessages, ToastState, ToastTone, TooltipPosition, ViewToggleOption };
+export type { AlertAppearance, AlertRowTone, AlertTone, AlertVariant, BreadcrumbItem, BucketProgressItem, CalendarDay, ContentStateKind, ContentStateLoad, ContentViewerType, DataTableCardRole, DataTableCellClick, DataTableColumn, DataTableDensity, DataTableItemLabel, DataTableSort, DataTableView, DividerOrientation, DocumentRowTone, DrawerRole, DrawerSide, DropdownItemTone, DropdownPanelRole, DropdownPanelVariant, EmptyStateTone, EventTimelineItem, EventTimelineTone, FileRejection, FileRejectionReason, FilterChipOption, FilterFieldChange, FilterFieldConfig, FilterFieldType, FilterValue, FolderTabOption, FooterLink, IconName, IconRotation, IconSize, InputBound, JourneyStep, JourneyStepStatus, JourneyStepperColorScheme, JourneyStepperOrientation, JourneyStepperSurface, LinkVariant, ListToolbarMode, MilestoneGroup, MilestoneItem, MilestoneTimelineLabels, ModalSize, MultiSelectOption, NoteBlockTone, OptionListOption, PageHeaderTitleSize, PaginationItem, PopoverPlacement, PortalHeaderAdminAction, PortalHeaderNavItem, ProgressSize, ProgressStatus, ProgressTone, RowAction, RowActionKind, RowActionsMode, SectionNavSubsectionData, SegmentedOption, SelectOption, SelectableCardOption, SidebarNavItemData, SkeletonPresetVariant, SkeletonVariant, SpinnerSize, StatCardBadgeTone, StatCardDensity, StatCardTone, StatTileTone, StatTileVariant, SwitchSize, TabOption, TextAs, TextTone, TextVariant, TimeSlot, ToastAction, ToastOptions, ToastPromiseMessages, ToastState, ToastTone, TooltipPosition, ViewToggleOption };

package/types/kaufmann-lab-ui-map.d.ts

@@ -306,6 +306,7 @@ interface MapMarker {
  *   <kf-map label="Ubicación del vehículo y del destino" [markers]="markers()" />
  *   <kf-map size="sm" variant="preview" label="Vista previa de la ruta" [route]="route()" />
  *   <kf-map label="Flota completa" [markers]="fleet()" [controls]="['zoom', 'recenter', 'cluster', 'follow']" />
+ *   <kf-map label="Flota completa" [markers]="fleet()" [clusterAbove]="50" />
  */
 declare class MapView {
     readonly size: _angular_core.InputSignal<MapSize>;
@@ -329,6 +330,15 @@ declare class MapView {
     readonly theme: _angular_core.InputSignal<MapTheme>;
     /** Controles flotantes a mostrar — ver JSDoc de la clase y `MapControls.ts`. */
     readonly controls: _angular_core.InputSignal<MapControlKind[]>;
+    /**
+     * Umbral de agrupado automático: con `markers().length > clusterAbove` el
+     * mapa entra en modo cluster (el mismo que activa el control `cluster`),
+     * en vez de apilar cientos de pins y de paradas de Tab. `null` (default)
+     * conserva el comportamiento de siempre: nunca agrupa solo. Con el control
+     * `cluster` visible, el botón sigue mandando: un clic reemplaza lo
+     * automático hasta que se destruya el mapa.
+     */
+    readonly clusterAbove: _angular_core.InputSignal<number | null>;
     /**
      * Descripción accesible real del mapa — el `<div>` donde Mapbox renderiza
      * su canvas queda vacío de semántica para un lector de pantalla. Requerido
@@ -369,7 +379,10 @@ declare class MapView {
     /** Igual que `resolvedTheme()` pero público para el template — lo necesita
      * `MapThemePicker` (vía `MapControls`) para marcar la opción activa. */
     protected readonly activeTheme: _angular_core.Signal<MapTheme>;
-    protected readonly clusterActive: _angular_core.WritableSignal<boolean>;
+    /** Elección manual del botón `cluster`; `null` = sin elegir, manda `clusterAbove`. */
+    private readonly clusterChoice;
+    private readonly clusterAutomatic;
+    protected readonly clusterActive: _angular_core.Signal<boolean>;
     protected readonly followActive: _angular_core.WritableSignal<boolean>;
     protected readonly hasLiveMarker: _angular_core.Signal<boolean>;
     protected readonly isFullscreen: _angular_core.WritableSignal<boolean>;
@@ -624,7 +637,7 @@ declare class MapView {
     protected handleThemeSelect(theme: MapTheme): void;
     protected handleFullscreenToggle(): void;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<MapView, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MapView, "kf-map", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "markers": { "alias": "markers"; "required": false; "isSignal": true; }; "route": { "alias": "route"; "required": false; "isSignal": true; }; "fitToMarkers": { "alias": "fitToMarkers"; "required": false; "isSignal": true; }; "center": { "alias": "center"; "required": false; "isSignal": true; }; "zoom": { "alias": "zoom"; "required": false; "isSignal": true; }; "theme": { "alias": "theme"; "required": false; "isSignal": true; }; "controls": { "alias": "controls"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": true; "isSignal": true; }; }, { "markerSelect": "markerSelect"; "markerAction": "markerAction"; }, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<MapView, "kf-map", never, { "size": { "alias": "size"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "markers": { "alias": "markers"; "required": false; "isSignal": true; }; "route": { "alias": "route"; "required": false; "isSignal": true; }; "fitToMarkers": { "alias": "fitToMarkers"; "required": false; "isSignal": true; }; "center": { "alias": "center"; "required": false; "isSignal": true; }; "zoom": { "alias": "zoom"; "required": false; "isSignal": true; }; "theme": { "alias": "theme"; "required": false; "isSignal": true; }; "controls": { "alias": "controls"; "required": false; "isSignal": true; }; "clusterAbove": { "alias": "clusterAbove"; "required": false; "isSignal": true; }; "label": { "alias": "label"; "required": true; "isSignal": true; }; }, { "markerSelect": "markerSelect"; "markerAction": "markerAction"; }, never, never, true, never>;
 }
 
 export { MAP_CONFIG, MapControls, MapView, STYLE_BY_THEME, THEME_LABEL, THEME_ORDER, provideMapConfig };