@telcomdev/ui 0.1.16 → 0.1.18

package/README.md

@@ -76,13 +76,114 @@ el borde outline permanecen visibles en todos los estados.
 />
 ```
 
-Ambos controles usan `TdSelectOption<T>`, son compatibles con formularios
-Angular y muestran su panel mediante Angular CDK Overlay.
+Ambos controles son compatibles con formularios Angular y muestran su panel
+mediante Angular CDK Overlay.
+
+`td-autocomplete-select` soporta dos formas de trabajo:
+
+### Modo estándar
+
+Usa `TdSelectOption<T>` cuando ya tienes opciones normalizadas:
+
+```ts
+readonly proveedores = [
+  { value: 1, label: 'AMERICA MOVIL PERU S.A.C.', description: '20467534026' },
+];
+
+proveedorId: number | null = 1;
+```
+
+```html
+<td-autocomplete-select
+  label="Proveedor"
+  [options]="proveedores"
+  [(ngModel)]="proveedorId"
+/>
+```
+
+### Modo mapeado
+
+Usa `valueKey`, `labelKey` y, opcionalmente, `descriptionKey`, `iconKey` o
+`disabledKey` cuando quieres consumir DTOs reales sin mapearlos manualmente:
+
+```ts
+readonly proveedores = [
+  {
+    proveedorId: 1,
+    tipoDocumentoIdentidadId: 4,
+    numeroDocumento: '20467534026',
+    nombre: 'AMERICA MOVIL PERU S.A.C.',
+  },
+];
+
+proveedorId: number | null = 1;
+```
+
+```html
+<td-autocomplete-select
+  label="Proveedor"
+  [options]="proveedores"
+  valueKey="proveedorId"
+  labelKey="nombre"
+  descriptionKey="numeroDocumento"
+  [(ngModel)]="proveedorId"
+/>
+```
+
+Si el valor llega antes que las opciones, o las opciones llegan antes que el
+valor, el texto visible se sincroniza automáticamente. Esta sincronización no
+emite `selectionChange`; ese evento se reserva para selección o limpieza
+realizada por el usuario.
 
 El comportamiento predeterminado durante el scroll es `reposition`, por lo que
 el panel permanece unido al control. Puede cambiarse con
 `scrollBehavior="close"`.
 
+## File Upload
+
+Selector de archivos con soporte para formularios Angular, drag and drop,
+validación de formatos y previsualización de imágenes/PDF mediante el visor de
+archivos de la librería.
+
+### Variante input
+
+```html
+<td-file-upload
+  label="Logo del proveedor"
+  variant="input"
+  accept="image/*"
+  [maxSizeMb]="2"
+  [(ngModel)]="logo"
+/>
+```
+
+```ts
+logo: File | null = null;
+```
+
+### Variante dropzone con preview
+
+```html
+<td-file-upload
+  label="Adjuntos del expediente"
+  description="Arrastra contrato, evidencia o documentos."
+  accept="image/*,.pdf,.xml,.xlsx,.zip"
+  [multiple]="true"
+  [maxFiles]="5"
+  [maxSizeMb]="8"
+  [(ngModel)]="adjuntos"
+  (filesChange)="actualizarArchivos($event)"
+  (rejected)="mostrarRechazos($event)"
+/>
+```
+
+```ts
+adjuntos: File[] = [];
+```
+
+Cuando `multiple` está desactivado el valor del formulario es `File | null`.
+Cuando `multiple` está activado el valor es `File[]`.
+
 ## Tabs
 
 ```html
@@ -401,6 +502,41 @@ También funciona con formularios tradicionales:
 <td-checkbox label="Principal" [formControl]="controlPrincipal" />
 ```
 
+## Radio Button
+
+`TdRadioGroup` permite selección única tipada y mantiene compatibilidad con
+Signal Forms, `ngModel` y Reactive Forms.
+
+```html
+<td-radio-group
+  label="Tipo de documento"
+  [options]="tiposDocumento"
+  [(ngModel)]="tipoDocumento"
+/>
+```
+
+```ts
+readonly tiposDocumento = [
+  { value: 'dni', label: 'DNI' },
+  { value: 'ruc', label: 'RUC' },
+  { value: 'ce', label: 'Carné de extranjería' },
+];
+
+tipoDocumento: 'dni' | 'ruc' | 'ce' | null = 'ruc';
+```
+
+También cuenta con variante tipo tarjeta:
+
+```html
+<td-radio-group
+  label="Canal de notificación"
+  variant="card"
+  direction="horizontal"
+  [options]="canales"
+  [formField]="fields.canal"
+/>
+```
+
 Con Signal Forms no se necesita una variable intermedia ni eventos manuales. El
 modelo debe inicializar el campo como `true` o `false`, nunca como `null`.