@ajuarezso/sui-design-system 0.20.0 → 0.21.0

package/docs/sui-file-upload/README.md

@@ -0,0 +1,154 @@
+---
+name: sui-file-upload
+selector: sui-file-upload
+resumen: Área para arrastrar o elegir archivos que no son una foto (PDF, Excel, CSV)
+alternativas: [sui-image-upload (una sola imagen con vista previa: logo, portada, comprobante), sui-image-upload-profile (foto de perfil con botones Subir/Cambiar/Eliminar), sui-file-upload-card (el archivo ya elegido, con su progreso)]
+---
+
+# sui-file-upload
+
+Story: [Molecules/Upload/File Upload](https://sui-design-system.web.app/?path=/docs/molecules-upload-file-upload--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para subir **documentos**: un PDF, un Excel, un CSV, o varios archivos a la vez. La
+persona arrastra el archivo o toca para buscarlo.
+
+**No lo uses** para:
+
+- **Una imagen** (logo, portada, foto del producto, captura del Yape): `sui-image-upload`, que
+  muestra la vista previa y se integra con el recortador y el compresor de la app.
+- Una foto de perfil con botones: `sui-image-upload-profile`.
+- Mostrar el archivo que ya se eligió: va `sui-file-upload-card` debajo.
+
+Regla corta: **foto → image-upload · documento o varios archivos → file-upload · el archivo ya
+elegido → file-upload-card.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS** (página del file upload): es la forma de **arrastrar y soltar, o
+> buscar en el equipo**, para subir un archivo. Su ejemplo arma el texto así: una línea que invita
+> («Elige un archivo o arrástralo aquí»), una línea con **formatos y tamaño máximo** («JPEG, PNG,
+> PDF y MP4, hasta 50 MB») y el botón **«Buscar archivo»**. Trae aparte el ícono por tipo de
+> archivo (en SUI, `sui-file-icon`). No dice cuándo usar cada tamaño. El resto es **propuesta,
+> falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. Hoy todo lo que se sube es
+> imagen y va con `sui-image-upload` (13) o con un `<input type="file">` a mano (3: `renewal-modal`,
+> `add-product` y la miniatura de `option-image`; ver el README de `sui-image-upload`).
+
+### Textos: `title`, `subtitle`, `browseLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `title` | Qué se sube, en la voz de la persona: «Sube tu carta en PDF», «Arrastra tu Excel aquí». Si se omite, sale «Arrastra y suelta el archivo aquí». | guía (línea que invita) |
+| `subtitle` | **Formatos y tamaño máximo**, siempre: «PDF o Excel, hasta 10 MB». El default «o haz clic para seleccionar» no dice nada que el área no diga. | guía (formatos y tamaño) |
+| `browseLabel` | El default ya es «Buscar archivo»; se pasa solo para otro texto («Elegir foto»). | guía (el botón) · el texto es propuesta |
+
+### `accept`, `multiple`, `maxSize`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `accept` | Siempre, con lo mismo que dice el `subtitle`: `".pdf,.xlsx,.csv"`. Si el texto y el filtro no coinciden, la persona elige un archivo que se rechaza. | propuesta |
+| `multiple` | Varios archivos del mismo tipo (las boletas del mes). Con `multiple` cada archivo va en su `sui-file-upload-card`. | propuesta |
+| `maxSize` | Siempre, en **bytes** (`10 * 1024 * 1024`), y el mismo número en el `subtitle`. | propuesta |
+
+### `size`
+
+| valor | padding | cuándo | fuente |
+|---|---|---|---|
+| `small` | 24 | En mobile y dentro de un modal o una card. | propuesta |
+| `medium` (default) | 32 | En web, en una página o un modal ancho. | guía (es el único tamaño que muestra) |
+| `large` | 40 | Cuando subir el archivo es lo único de la pantalla (importar la carta). | propuesta |
+| `xlarge` | 48 | No usar: más aire no ayuda a soltar el archivo. | no usar |
+
+### Estados: `error`, `errorMessage`, `disabled`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `error` + `errorMessage` | El archivo se subió y el servidor lo rechazó («El PDF está protegido con clave»). Lo de tamaño y tipo ya lo avisa solo. | propuesta |
+| `disabled` | Mientras se sube, o si ya se llegó al máximo de archivos. | propuesta |
+
+Usos de hoy que rompen la regla: **0** (no hay file-upload).
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: lo que se toca mide **44 px o más**. Aquí **toda el área se toca**
+(abre el selector), así que pasa en cualquier tamaño; en el celular no se arrastra, por eso va
+más compacta. En pantallas de los dos, con el servicio de breakpoints de la app (`bp`, en
+`services/breakpoints.service.ts`).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| subir un documento en un formulario o modal | `small` | `medium` | propuesta |
+| subir es lo único de la pantalla | `medium` | `large` | propuesta |
+
+```html
+<sui-file-upload [size]="bp.isMobile() ? 'small' : 'medium'"
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB"
+                 accept=".pdf" [maxSize]="10 * 1024 * 1024" (filesSelected)="subir($event)" />
+```
+
+Llena el ancho del contenedor (antes 400 fijo; extensión SUI, 03-10-2026). El botón «Buscar
+archivo» mide 32 px (`xsmall`) en todos los tamaños: solo, en mobile **no
+llegaría**; pasa porque el área entera también abre el selector.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | todo lo que se sube hoy es una imagen | la carta del local en PDF o Excel para cargarla, la ficha RUC, los documentos del repartidor escaneados en PDF |
+| `multiple` | no hay subidas de varios archivos | las boletas del mes de un gasto, varias fotos de un reclamo |
+| `size="xlarge"` | más aire no ayuda | ninguno |
+| para imágenes | no muestra la vista previa ni pasa por el recortador | — |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `accept` | `string` | `''` |
+| `multiple` | `boolean` | `false` |
+| `maxSize` | `number` | `0` |
+| `title` | `string \| null` | `null` |
+| `subtitle` | `string \| null` | `null` |
+| `browseLabel` | `string` | `'Buscar archivo'` |
+| `disabled` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `errorMessage` | `string \| null` | `null` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+
+| output | payload |
+|---|---|
+| `filesSelected` | `File[]` |
+| `errorEvent` | `string` |
+<!-- api:fin -->
+
+## Trampas
+
+- `browseLabel` dice «Buscar archivo» por defecto (antes «Browse File»).
+- **Llena el ancho del contenedor** desde el 03-10-2026 (antes medía 400 fijo y había que forzar
+  `style="width: 100%"`). Las pantallas que lo dejaban en 400 en un contenedor ancho ahora se
+  estiran; para un ancho fijo, se lo pone el consumer al host.
+- **`maxSize` va en bytes**, no en MB. `0` = sin límite.
+- **Emite solo los archivos válidos**: si de tres uno pesa de más, `filesSelected` trae dos y
+  `errorEvent` avisa del tercero (con el texto ya armado: «"x.pdf" supera el tamaño máximo (10.0 MB)»).
+- Sin `multiple`, aunque se suelten varios, **emite solo el primero**.
+- `accept` filtra al elegir **y** al soltar, por extensión (`.pdf`) o por tipo (`image/*`).
+- El error interno queda pegado hasta el próximo intento válido; `errorMessage` gana sobre él.
+- **No sube nada**: entrega los `File` y la subida (y el progreso en `sui-file-upload-card`) la
+  hace quien lo usa.
+- El atributo `title` del host se borra solo (no sale el tooltip gris del navegador).
+
+## Ejemplo
+
+```html
+<sui-file-upload title="Sube tu carta en PDF o Excel" subtitle="PDF o Excel, hasta 10 MB"
+                 browseLabel="Buscar archivo" accept=".pdf,.xlsx" [maxSize]="10 * 1024 * 1024"
+                 (filesSelected)="subirCarta($event)" (errorEvent)="avisar($event)" />
+```

package/docs/sui-file-upload-card/README.md

@@ -0,0 +1,129 @@
+---
+name: sui-file-upload-card
+selector: sui-file-upload-card
+resumen: La fila de un archivo que se está subiendo, con su progreso, listo o error para reintentar
+alternativas: [sui-file-upload (el área para elegir el archivo), sui-image-upload (una imagen: muestra la vista previa en vez de la fila), sui-file-icon (un archivo en una lista, sin subida)]
+---
+
+# sui-file-upload-card
+
+Story: [Molecules/Upload/File Upload Card](https://sui-design-system.web.app/?path=/docs/molecules-upload-file-upload-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** debajo de un `sui-file-upload`, una fila por archivo, para mostrar **cómo va la subida**:
+subiendo con su barra, listo, o falló con «Reintentar».
+
+**No lo uses** para:
+
+- Una imagen: `sui-image-upload` muestra la vista previa, que dice más que un nombre de archivo.
+- Una lista de archivos ya guardados (sin subida): `sui-file-icon` en una fila normal.
+- Un progreso que no es de un archivo: `sui-progress-bar`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente** (su página del file upload solo muestra
+> el área y el ícono por tipo). Todo es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. Las subidas de hoy son de
+> imágenes y avisan con el `subtitle` del image-upload («Procesando…») o lo deshabilitan.
+
+### `state`
+
+| valor | cuándo | qué muestra | fuente |
+|---|---|---|---|
+| `in-progress` (default) | Mientras sube. Va con `progress`. | barra azul, ícono de carga, X para cancelar | propuesta |
+| `success` | Subió. | check verde, tacho para quitar | propuesta |
+| `error` | Falló. Va con `statusText` que diga por qué. | ícono rojo, «Reintentar», tacho | propuesta |
+
+### Textos y datos
+
+| input | cuándo | fuente |
+|---|---|---|
+| `file` | El nombre real del archivo (`'carta-octubre.pdf'`). La extensión da el ícono y el color. | propuesta |
+| `description` | **Siempre** se pasa: el default es un texto de ejemplo («0 KB de 120 KB»). Subiendo: «1,2 MB de 3,4 MB»; listo: «3,4 MB». | propuesta |
+| `progress` | 0–100, solo en `in-progress`. | propuesta |
+| `statusText` | Los defaults ya están en español («Subiendo…», «Completado», «Falló»); en error, mejor el motivo: «Se cortó la conexión». | propuesta |
+| `showStatus=false` | Solo en `success`, cuando el check sobra porque la lista ya dice «Archivos subidos». | propuesta |
+| `retryLabel` | El default ya es «Reintentar». | propuesta |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+**No tiene `size`.** Llena el ancho del contenedor (antes 400 fijo) y la X o el tacho de la derecha
+es un `sui-compact-button` `2xlarge` de **32 px** (Figma: 24), que con el aire de la tarjeta (16 de
+padding, 72 de alto mínimo) se toca bien con el dedo. «Reintentar» sigue siendo un link de 20 px de
+alto: en mobile conviene que la fila entera también reintente.
+
+| pieza | mobile | web | fuente |
+|---|---|---|---|
+| ancho | el del contenedor | el del contenedor | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| X / tacho | 32 px | 32 px | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| «Reintentar» | link de 20 px — **no llega** | link | medido |
+
+```html
+<sui-file-upload-card [file]="a.nombre" [state]="a.estado" [progress]="a.pct"
+                      [description]="a.peso" (actionClicked)="quitar(a)" (retryClicked)="reintentar(a)" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | todo lo que se sube es una imagen y se ve con su vista previa | junto a `sui-file-upload`: la carta en PDF, varias boletas de un gasto, documentos del repartidor |
+| para imágenes | la vista previa dice más que el nombre del archivo | — |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `file` | `SuiFileUploadCardFile \| string` | `'file.pdf'` |
+| `description` | `string` | `'0 KB de 120 KB'` |
+| `state` | `'in-progress' \| 'success' \| 'error'` | `'in-progress'` |
+| `progress` | `number` | `10` |
+| `statusText` | `string \| null` | `null` |
+| `showStatus` | `boolean` | `true` |
+| `cancelLabel` | `string` | `'Cancelar subida'` |
+| `removeLabel` | `string` | `'Quitar archivo'` |
+| `progressLabel` | `string` | `'Progreso de la subida'` |
+| `retryLabel` | `string` | `'Reintentar'` |
+
+| output | payload |
+|---|---|
+| `actionClicked` | `void` |
+| `retryClicked` | `void` |
+<!-- api:fin -->
+
+```ts
+interface SuiFileUploadCardFile { filename: string; extension?: string; }
+```
+
+## Trampas
+
+- Los textos de fábrica están en español desde el 03-10-2026: «0 KB de 120 KB», «Subiendo…»,
+  «Completado», «Falló», «Reintentar», y para el lector de pantalla «Cancelar subida», «Quitar
+  archivo» y «Progreso de la subida» (estos tres, con `cancelLabel`, `removeLabel` y
+  `progressLabel`).
+- Llena el ancho del contenedor, igual que `sui-file-upload` (antes 400 fijo).
+- **`progress` arranca en 10**, no en 0.
+- **`actionClicked` significa dos cosas**: cancelar mientras sube y quitar cuando terminó. Quien lo
+  usa mira `state` para saber cuál.
+- La barra de progreso es azul, no naranja.
+- No sube nada: refleja el estado que le pasan.
+
+## Ejemplo
+
+```html
+<sui-file-upload-card file="carta-octubre.pdf" state="in-progress" [progress]="45"
+                      description="1,2 MB de 2,6 MB" statusText="Subiendo…" />
+<sui-file-upload-card file="carta-octubre.pdf" state="error" description="2,6 MB"
+                      statusText="Se cortó la conexión" retryLabel="Reintentar"
+                      (retryClicked)="reintentar()" (actionClicked)="quitar()" />
+```

package/docs/sui-image-upload/README.md

@@ -0,0 +1,200 @@
+---
+name: sui-image-upload
+selector: sui-image-upload
+resumen: Subir una imagen y ver su vista previa en el mismo lugar (logo, portada, foto de producto, comprobante)
+alternativas: [sui-image-upload-profile (foto de perfil con botones Subir/Cambiar/Eliminar al lado), sui-file-upload (documentos que no son foto: PDF, Excel), app-image-cropper (el recortador de la app, que se abre desde el lápiz)]
+---
+
+# sui-image-upload
+
+Story: [Molecules/Upload/Image Upload](https://sui-design-system.web.app/?path=/docs/molecules-upload-image-upload--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para subir **una imagen** y que la persona la vea apenas la elige: el logo y la portada
+del local, la foto de un producto, la foto de perfil, la captura del Yape o del comprobante, el QR
+de cobro del repartidor, el banner de una campaña.
+
+**No lo uses** para:
+
+- Documentos que no son foto (PDF, Excel): `sui-file-upload`.
+- Varias imágenes a la vez: no lo soporta; una por campo.
+- La miniatura de una opción de producto (36 px dentro de una fila): `option-image` de la app.
+
+El archivo que entrega **no se sube tal cual**: pasa por `ImageCompressorService` (HEIC → JPEG,
+1200 px + miniatura de 400) y, si hay que encuadrarlo, por `app-image-cropper` antes. Ver Trampas.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente** (el «Image Upload» del Figma de origen
+> es otra cosa: la foto con botones, que en SUI es `sui-image-upload-profile`). Todo es
+> **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **13 usos en
+> 10 pantallas**. `shape`: 11 `rect`, 2 `circle`. `size`: 7 `xl`, 3 `lg`, 3 sin size (fluidos).
+> `fluid`: 6. `editable`: 3 `true`, 2 según haya imagen, 1 `false`, 7 sin poner.
+
+### `shape` — según cómo se va a ver la imagen después
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `circle` (default) | **Solo la foto de una persona** (perfil del cliente, del repartidor, del usuario del local). Así se ve después en `sui-avatar`. | propuesta |
+| `rect` | **Todo lo demás**: el logo del local (en el home se ve como cuadrado redondeado), la portada, la foto del producto, comprobantes, QR, banners. | propuesta |
+
+### `size` y `fluid` — según la forma de la imagen
+
+| valor | px | cuándo | fuente |
+|---|---|---|---|
+| `fluid` | ancho del contenedor, alto hasta 320 | **Capturas y documentos** (comprobante, Yape, QR) y **imágenes apaisadas** (portada 16:9, banner). Una captura de celular es vertical: en un cuadrado se recorta. | propuesta |
+| `xl` | 200 | **Imágenes cuadradas**: logo, foto del producto, foto de perfil. | propuesta |
+| `lg` (default) | 160 | Imagen cuadrada al lado de otra cosa en la misma fila (el logo junto al nombre del local en web). | propuesta |
+| `md` | 120 | No usar: chico para ver si la foto quedó bien. | no usar |
+| `sm` | 80 | No usar: no entra el texto (el subtítulo se esconde). | no usar |
+
+### `editable` — qué hace el lápiz
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `true` | **Siempre.** Con imagen muestra dos botones a la vista: lápiz y tacho. El lápiz emite `editRequested`: si la pantalla tiene recortador, lo abre (`app-image-cropper`); si no, llama a `abrirSelector()` para elegir otra (como el Yape del repartidor). | propuesta |
+| `false` (default) | No usar: con imagen, el lápiz aparece **solo al pasar el mouse** (en el celular no se ve) y el «Quitar» de abajo es un botón aparte (32 px). | no usar |
+
+### Textos: `title`, `subtitle`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `title` | Verbo + qué: «Subir logo», «Subir comprobante», «Subir captura del pago». | propuesta |
+| `subtitle` | Formatos y tamaño, **solo los que el componente acepta** (JPG, PNG o WebP), o el encuadre que se va a aplicar («se recorta a 16:9»). Mientras procesa: «Procesando…». | propuesta |
+
+### `maxSize`, `disabled`, `src`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `maxSize` | Siempre, en **bytes**. 10 MB para capturas y comprobantes, 20–50 MB para fotos que se van a comprimir. | propuesta |
+| `disabled` | Mientras se comprime o se sube (`subiendo()`), para que no se elija otra encima. | propuesta |
+| `src` (model) | La URL guardada, o la vista previa local mientras se sube. Con `[(src)]` el componente la pone solo al elegir. | propuesta |
+
+### Usos de hoy que rompen la propuesta
+
+- **5 subtítulos prometen HEIC**: hasta el 03-10-2026 el componente lo rechazaba; con la versión
+  nueva del DS ya pasa (ver Trampas por la vista previa en Chrome):
+  `components/plan-change-modal/plan-change-modal.html:150`, `pages/driver/driver-wallet/driver-wallet.html:243`,
+  `pages/promociones/promociones.html:185` y `:269`, `pages/customer/order-tracking/order-tracking.html:985`.
+- **1 logo en círculo** → `rect`: `pages/business-onboarding/step-info/step-info.html:42` (en
+  `mi-negocio.html:518` el mismo logo es `rect`, y en el home del cliente se ve cuadrado).
+- **3 imágenes en cuadrado que deberían ir `fluid`**: comprobantes en
+  `components/plan-change-modal/plan-change-modal.html:150` y `pages/central/central-gastos/central-gastos.html:118`;
+  la portada 16:9 en `pages/mi-negocio/mi-negocio.html:572` (en el onboarding ya va `fluid`).
+- **8 sin `editable`**: `components/avatar-editor/avatar-editor.ts:33` (pone `false` aunque tiene
+  recortador), `pages/customer/order-tracking/order-tracking.html:985` (cliente, solo celular),
+  `components/plan-change-modal/plan-change-modal.html:150`, `pages/central/central-gastos/central-gastos.html:118`,
+  `pages/promociones/promociones.html:185` y `:269`, y `pages/business-onboarding/step-info/step-info.html:42` y `:56`.
+- **2 áreas de subida armadas a mano** que van con este componente (`rect`, `fluid`, `editable`):
+  `components/renewal-modal/renewal-modal.html:64` (comprobante, con SVG propio) y
+  `pages/products/add-product/add-product.html:223` (foto del producto, con dropzone propia).
+  No cuenta `components/option-image/option-image.ts:68`: es una miniatura de 36 px en una fila.
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: lo que se toca mide **44 px o más**. El área vacía se toca entera
+(80 a 200 px), así que pasa; los botones con imagen, no. En pantallas de los dos se elige con el
+servicio de breakpoints de la app (`bp`, en `services/breakpoints.service.ts`).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| comprobante, captura, QR, portada, banner | `fluid` | `fluid` (en una columna de ≤ 480 px) | propuesta |
+| logo, foto de producto, foto de perfil | `xl` (200) | `xl` (200), o `lg` (160) al lado del nombre | propuesta |
+| lápiz y tacho (`editable`) | 40 px (32 en `sm`) | 40 px | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| «Quitar» (sin `editable`) | 32 px (`sui-button` `xsmall`) | 32 px | canon (aprobado por el dueño, 03-10-2026) |
+
+```html
+<sui-image-upload shape="rect" [size]="bp.isMobile() ? 'xl' : 'lg'" [editable]="true"
+                  [src]="logo()" [maxSize]="50 * 1024 * 1024" title="Subir logo"
+                  subtitle="JPG, PNG o WebP — máx 50 MB"
+                  (imageSelected)="alElegirLogo($event)" (editRequested)="abrirRecortador()"
+                  (removed)="quitarLogo()" />
+```
+
+Desde el 03-10-2026 el lápiz y el tacho miden **40** (antes 34; en `sm`, de 80 de lado, no entran dos
+de 40 y quedan en 32) y el «Quitar» es un `sui-button` `xsmall` de **32** (antes 28). En `circle`
+los dos botones van centrados abajo, dentro del círculo.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `size="md"` (120) | chico para ver si la foto quedó bien | una grilla de fotos extra del producto (galería) |
+| `size="sm"` (80) | no entra el texto | una fila de varias miniaturas con su «+» |
+| `editable=false` | el lápiz solo aparece con el mouse; en el celular no se ve | una pantalla solo de web donde reemplazar al pasar el mouse sea lo esperado |
+| `shape="circle"` para algo que no es una persona | el logo y los productos se ven cuadrados | — |
+| para PDF | no muestra vista previa de documentos | — (va `sui-file-upload`) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `fluid` | `boolean` | `false` |
+| `shape` | `'circle' \| 'rect'` | `'circle'` |
+| `size` | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'lg'` |
+| `src` · model, `[(src)]` | `string \| null` | `null` |
+| `maxSize` | `number` | `0` |
+| `title` | `string \| null` | `null` |
+| `subtitle` | `string \| null` | `null` |
+| `disabled` | `boolean` | `false` |
+| `editable` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `imageSelected` | `File` |
+| `removed` | `void` |
+| `editRequested` | `void` |
+| `errorEvent` | `string` |
+<!-- api:fin -->
+
+Método público: `abrirSelector()` — abre el selector de archivo (para el lápiz cuando no hay
+recortador; se llama con una referencia: `#qr` → `qr.abrirSelector()`).
+
+## Trampas
+
+- **Acepta HEIC/HEIF** desde el 03-10-2026 (por tipo y, como Chrome suele dejar el tipo vacío, por
+  extensión). **La vista previa de un HEIC no se ve en Chrome** (solo Safari lo dibuja): el
+  componente pone el archivo crudo como `src`, así que en Android o en la compu queda en blanco
+  hasta que la pantalla lo pasa por `ImageCompressorService` y pone el JPG en `src`.
+- El mensaje de tipo no soportado dice «Tipo no soportado. Usa JPG, PNG, WebP, GIF o HEIC.»
+  (antes en voseo).
+- **El default de `shape` es `circle`** y el de `size` es `lg`: para un logo o un comprobante hay
+  que pasar los dos.
+- **Con `fluid`, `size` no hace nada** (`promociones.html:185` pasa `size="lg"` y `fluid` a la vez).
+- **`removed` ya vacía `src`** por dentro; quien lo usa solo limpia su `File` y su estado.
+- **Al elegir, pone la vista previa sola** (`src` = data URL) y emite el `File` original, sin
+  comprimir ni recortar. Comprimir y recortar es trabajo de la pantalla.
+- Con imagen y sin `editable`, **el componente mide el cuadrado + 8 + 32** (el «Quitar» queda
+  dentro; antes se salía y tapaba lo de abajo). Al reservar espacio en un layout, contar ese alto.
+- Con `circle` + `editable` los botones van centrados abajo, sobre la foto (antes, en la esquina, el
+  círculo recortaba el tacho).
+- Con `src` puesto, tocar el área vacía no hace nada: para elegir otra va el lápiz o `abrirSelector()`.
+- El `alt` de la vista previa dice «Vista previa».
+- El atributo `title` del host se borra solo (no sale el tooltip gris del navegador).
+- Ya trae el arreglo de iOS para el `:active` pegado.
+
+## Ejemplo
+
+```html
+<!-- Comprobante: ancho completo, el lápiz elige otra captura -->
+<sui-image-upload #comprobante shape="rect" [fluid]="true" [editable]="true"
+                  [src]="vistaPrevia()" [maxSize]="10 * 1024 * 1024"
+                  title="Subir comprobante" subtitle="Captura del Yape o del banco — máx 10 MB"
+                  (imageSelected)="alElegir($event)" (editRequested)="comprobante.abrirSelector()"
+                  (removed)="quitar()" />
+
+<!-- Foto del producto: cuadrada, el lápiz abre el recortador -->
+<sui-image-upload shape="rect" size="xl" [editable]="true" [src]="foto()"
+                  title="Subir foto" subtitle="JPG, PNG o WebP — se comprime sola"
+                  (imageSelected)="alElegir($event)" (editRequested)="abrirRecortador()"
+                  (removed)="quitarFoto()" />
+```

package/docs/sui-image-upload-profile/README.md

@@ -0,0 +1,145 @@
+---
+name: sui-image-upload-profile
+selector: sui-image-upload-profile
+resumen: Foto de perfil o logo en círculo con los botones Subir, o Eliminar y Cambiar, al lado
+alternativas: [sui-image-upload (la imagen grande con su vista previa y el lápiz que abre el recortador; es lo que usa hoy la app), sui-avatar (solo mostrar la foto)]
+---
+
+# sui-image-upload-profile
+
+Story: [Molecules/Upload/Image Upload Profile](https://sui-design-system.web.app/?path=/docs/molecules-upload-image-upload-profile--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en una **pantalla de ajustes** donde la foto es un dato más de la cuenta: un círculo
+chico (56–64 px) con su texto y los botones al lado, en una fila de un formulario.
+
+**No lo uses** para:
+
+- **La foto de perfil de la app hoy**: `app-avatar-editor` usa `sui-image-upload` `circle` `xl`
+  con el recortador, en las tres pantallas de perfil (cliente, repartidor, local). Una foto de
+  200 px que se ve antes de guardar es mejor para quien se sube su cara por primera vez.
+- El logo del local: en la app el logo se ve **cuadrado** (home del cliente) y este componente lo
+  muestra en círculo.
+- Comprobantes, portadas o fotos de productos: `sui-image-upload`.
+- Solo mostrar la foto: `sui-avatar`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente** (existe en el Figma de origen, sin
+> texto de uso). Todo es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. La foto de perfil va con
+> `app-avatar-editor` (3 pantallas).
+
+### `type`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `avatar` (default) | La foto de una persona. Vacío muestra una silueta. | propuesta |
+| `company` | Un negocio. Vacío muestra edificios. Ojo: lo muestra en círculo. | propuesta |
+
+### `alignment`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `vertical` (default) | Con texto: título y requisitos («Mín. 400 × 400 px, PNG o JPEG»), avatar de 64. | propuesta |
+| `horizontal` | Sin texto, solo los botones al lado del avatar de 56. Cuando el label ya está arriba (`sui-form-label`). | propuesta |
+
+### Textos y estados
+
+| input | cuándo | fuente |
+|---|---|---|
+| `title` | Qué es: «Tu foto», «Foto de perfil». Solo se ve en `vertical`. | propuesta |
+| `subtitle` | Requisitos reales: formatos que se aceptan y para qué se usa («La ve el cliente cuando llevas su pedido»). | propuesta |
+| `labels` | Ya vienen en español con tuteo (Subir, Eliminar, Cambiar). Cambiarlos solo si el contexto pide otro verbo («Quitar»). | propuesta |
+| `imageUrl` | La URL guardada. Con imagen muestra Eliminar + Cambiar. | propuesta |
+| `companyLogoSrc` | Solo con `type="company"`: el logo, que gana sobre `imageUrl`. | propuesta |
+| `loading` | **Siempre** mientras se comprime y se sube: deshabilita los botones y atenúa la foto. | propuesta |
+| `disabled` | La persona no puede cambiarla (cuenta verificada con foto bloqueada). | propuesta |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+**No tiene `size`.** El avatar mide 64 (vertical) o 56 (horizontal) y los botones son `sui-button`
+`xsmall` de **32 px**: en mobile **no llegan** a los 44 px.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| foto en una pantalla de ajustes | — **no hay tamaño**: botones de 32 | `vertical`, botones de 32 | medido |
+
+```html
+<!-- Solo web, hasta que tenga size -->
+<sui-image-upload-profile title="Foto de perfil" subtitle="JPG o PNG, mín. 400 × 400 px"
+                          [imageUrl]="foto()" [loading]="subiendo()"
+                          (upload)="input.click()" (change)="input.click()" (remove)="quitar()" />
+<input #input type="file" accept="image/jpeg,image/png,image/webp" hidden (change)="alElegir($event)" />
+```
+
+**Sin tamaño suficiente para mobile.** Hace falta en el DS un `size` que lleve los botones a
+`large` (48 px). Mientras tanto, en el celular va `sui-image-upload` `circle` `xl`.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | la foto de perfil va con `app-avatar-editor` (grande, con recortador) | ajustes del equipo del local en web (foto de cada usuario en una fila) |
+| `type="company"` | el logo del local se ve cuadrado, no en círculo | si el DS le suma la forma cuadrada |
+| `alignment="horizontal"` | sin caso | una fila de una tabla de usuarios del local, con el nombre en la columna de al lado |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `imageUrl` | `string \| null` | `null` |
+| `companyLogoSrc` | `string \| null` | `null` |
+| `title` | `string` | `'Subir imagen'` |
+| `subtitle` | `string` | `'Mín. 400x400px, PNG o JPEG'` |
+| `alignment` | `'vertical' \| 'horizontal'` | `'vertical'` |
+| `type` | `'avatar' \| 'company'` | `'avatar'` |
+| `labels` | `SuiImageUploadProfileLabels` | `{}` |
+| `disabled` | `boolean` | `false` |
+| `loading` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `upload` | `void` |
+| `remove` | `void` |
+| `change` | `void` |
+<!-- api:fin -->
+
+Es `ControlValueAccessor` de la URL (`string | null`); `remove` la deja en `null`.
+
+```ts
+interface SuiImageUploadProfileLabels { upload?: string; remove?: string; change?: string; }
+```
+
+## Trampas
+
+- **No abre el selector de archivos**: no tiene `<input type="file">`. «Subir» y «Cambiar» solo
+  emiten `upload` y `change`; quien lo usa pone su propio input (y luego el compresor y el
+  recortador).
+- **El avatar siempre es gris** (`color="gray"` fijo): no sigue el color por rol aprobado (local
+  naranja, repartidor verde, cliente azul) para el estado vacío.
+- **El orden de los botones lo fija el componente**: Eliminar (rojo) a la izquierda, Cambiar a la
+  derecha. No sigue el orden del footer (secundario a la izquierda, principal a la derecha).
+- `type="company"` es un círculo igual que el avatar.
+- En `horizontal` no se ve el texto aunque se pase `title`.
+- `loading` también deshabilita; no muestra spinner.
+- El atributo `title` del host se borra solo (no sale el tooltip gris del navegador); el `title`
+  sí se usa como `alt` de la foto.
+
+## Ejemplo
+
+```html
+<sui-image-upload-profile title="Foto de perfil" subtitle="La ve el cliente cuando llevas su pedido"
+                          [imageUrl]="foto()" [loading]="subiendo()"
+                          (upload)="elegir()" (change)="elegir()" (remove)="quitar()" />
+```