@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,320 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-image-upload`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+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`). Las reglas
+> marcadas canon están aprobadas y las de «según el código» describen el componente; lo que sigue
+> en **propuesta** espera decisió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`. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `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. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+
+### `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. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `xl` | 200 | **Imágenes cuadradas**: logo, foto del producto, foto de perfil. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `lg` (default) | 160 | Imagen cuadrada al lado de otra cosa en la misma fila (el logo junto al nombre del local en web). | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `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). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `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 en imperativo con tuteo + qué: «Sube tu logo», «Sube el comprobante», «Sube la captura del pago». Sin `title`: «Sube tu foto» (`circle`) o «Sube tu logo» (`rect`). | canon (dueño, 05-10-2026, P4 a); el default cambió en la 0.25.0 (antes «Subir foto» / «Subir logo») |
+| `subtitle` | Formatos y tamaño, **solo los que el componente acepta** (JPG, PNG, WebP, GIF o HEIC), o el encuadre que se va a aplicar («se recorta a 16:9»). Mientras procesa: «Procesando…». | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+
+### `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. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `disabled` | Mientras se comprime o se sube (`subiendo()`), para que no se elija otra encima. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `src` (model) | La URL guardada, o la vista previa local mientras se sube. Con `src` + `srcChange` el componente la pone solo al elegir. | según el código |
+
+### Usos de hoy que rompen la regla
+
+- **5 subtítulos prometen HEIC**: hasta el 03-10-2026 el componente lo rechazaba; desde la 0.22.0
+  (la que usa la app) ya lo acepta, así que **ya no rompen nada**. Lo que queda es la vista previa en
+  blanco en Chrome hasta que la pantalla ponga el JPG comprimido (ver Trampas):
+  `components/plan-change-modal/plan-change-modal.html:157`, `pages/driver/driver-wallet/driver-wallet.html:252`,
+  `pages/promociones/promociones.html:194` y `:279`, `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:520` 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:574` (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:978` (cliente, solo celular),
+  `components/plan-change-modal/plan-change-modal.html:150`, `pages/central/central-gastos/central-gastos.html:118`,
+  `pages/promociones/promociones.html:186` y `:271`, 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** (canon (dueño, 04-10-2026): piso táctil 44 en el teléfono). El área vacía se
+toca entera (80 a 200 px), así que pasa. Los botones con imagen se **ven** de 40 (lápiz y tacho) y
+32 («Quitar»), pero en el teléfono (≤ 767 px) **se tocan en 44 de alto** con un `::before`
+invisible (04-10-2026). Aquí `bp` no elige nada: `size` va por la forma de la imagen y lo que se
+toca ya tiene su área sola (ver «Por dispositivo (D16)»).
+
+**Por qué no hay un size nuevo**: aquí `size` (`sm`/`md`/`lg`/`xl`) es el tamaño de la **foto**, no
+el de los botones. Un `2xl` agrandaría la imagen sin que nadie lo pida; el área invisible lleva lo
+que se toca a 44 sin cambiar el dibujo ni los sizes de hoy.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| comprobante, captura, QR, portada, banner | `fluid` | `fluid` (en una columna de ≤ 480 px) | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| logo, foto de producto, foto de perfil | `xl` (200) | `xl` (200), o `lg` (160) al lado del nombre | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| lápiz y tacho (`editable`) | se ven de 40 (32 en `sm`), se tocan en 44 de alto; a los lados el área crece la mitad del espacio entre los dos (3; 2 en `sm`) para no pisarse | 40 px | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono (área) · canon (aprobado por el dueño, 03-10-2026), extensión SUI (40) |
+| «Quitar» (sin `editable`) | se ve de 32 (`sui-button` `xsmall`), se toca en 44 de alto: crece 4 hacia la foto (la mitad del gap de 8) y 8 hacia abajo | 32 px | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono (área) · canon (aprobado por el dueño, 03-10-2026) |
+
+```html
+<sui-image-upload shape="rect" size="xl" editable
+                  src={logo()} maxSize={50 * 1024 * 1024} title="Sube tu logo"
+                  subtitle="JPG, PNG o WebP — máx 50 MB"
+                  onImageSelected={(e) => alElegirLogo(e.detail)} onEditRequested={() => abrirRecortador()}
+                  onRemoved={() => 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. Lo que haya justo debajo del «Quitar»
+pierde 8 px de toque en el teléfono: no pegarle otro control sin margen.
+
+### Por dispositivo (D16)
+
+D16 (dueño, 05-10-2026) no mueve `size`: aquí `size` es el tamaño de la **foto**, no el de lo que
+se toca, así que no sigue la escala «lo que se toca / lo que no se toca». Se elige por la forma de
+la imagen (`xl` para lo cuadrado, `fluid` para capturas y apaisadas) y por el layout, igual que en
+la tabla de arriba: `xl` en una columna, que es lo que hay en el celular, el celular chico y la
+tablet; `lg` solo cuando la foto comparte la fila con el nombre (hoy ninguna pantalla lo hace:
+los 3 `lg` medidos son el logo del onboarding y el banner y el comprobante de promociones, que
+además van `fluid`; ninguno está en una fila).
+Lo que decide entre `xl` y `lg` es si hay fila, no el dispositivo: cuando una pantalla arme esa
+fila según el ancho, la condición es el mismo corte del layout de la pantalla, no
+`bp.celular()` ni `bp.tactil()`.
+
+Lo que se toca (lápiz, tacho, «Quitar») ya llega a 44 de alto en el celular y en el celular chico
+con el área invisible (`@media (max-width: 767px)`). En la **tablet táctil** (`pointer: coarse`,
+más de 767 px) esa área no se prende y quedan en 40 y 32: **pendiente**, espera el mixin
+`sui-tactil` del DS que propone §0 de las decisiones (sin el sí del dueño todavía).
+
+En master-pedidos: no hay helper de D16; `size="xl"` para lo cuadrado y `fluid` para
+capturas y apaisadas. `lg` solo en la fila del nombre, con la condición del layout de esa pantalla.
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `disabled` | `disabled` | `boolean` | `false` |
+| `editable` | `editable` | `boolean` | `false` |
+| `fluid` | `fluid` | `boolean` | `false` |
+| `heading` | `heading` | `null \| string` | `null` |
+| `maxSize` | `max-size` | `number` | `0` |
+| `shape` | `shape` | `"circle" \| "rect"` | `'circle'` |
+| `size` | `size` | `"lg" \| "md" \| "sm" \| "xl"` | `'lg'` |
+| `src` | `src` | `null \| string` | `null` |
+| `subtitle` | `subtitle` | `null \| string` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `editRequested` | `void` |
+| `errorEvent` | `string` |
+| `imageSelected` | `File` |
+| `removed` | `void` |
+| `srcChange` | `null \| string` |
+
+| método | firma |
+|---|---|
+| `abrirSelector` | `abrirSelector() => Promise<void>` |
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Props solo de aquí:** `heading`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `imagen.vistaPrevia` | Vista previa | — |
+| `imagen.editar` | Editar imagen | — |
+| `imagen.quitar` | Quitar imagen | — |
+| `imagen.cambiar` | Cambiar imagen | — |
+| `imagen.subeFoto` | Sube tu foto | `title` |
+| `imagen.subeLogo` | Sube tu logo | `title` |
+| `imagen.tipoNoSoportado` | Tipo no soportado. Usa JPG, PNG, WebP, GIF o HEIC. | — |
+| `imagen.superaTamano` | Imagen supera el tamaño máximo ({tamano}) | — |
+| `imagen.formatosMax` | {formatos} — máx {tamano} | `subtitle` |
+| `imagen.formatos` | JPG, PNG, WebP o HEIC | `subtitle` |
+<!-- textos: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:186` 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()`.
+- **Teclado (04-10-2026):** vacío, el host es el botón (`role="button"`, Enter/Espacio abren el
+  selector). Con imagen deja de serlo, porque adentro hay botones: sin `editable` la foto entera es
+  un `<button>` «Cambiar imagen» (antes un `div` que solo respondía al mouse) y «Quitar» va aparte;
+  con `editable`, el lápiz y el tacho.
+- 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.
+
+## Bien y mal
+
+Logo del local
+
+```html
+<!-- ❌ mal: el logo se ve cuadrado en el home, no en círculo; en 160 (lg) en una columna, donde va xl; y sin lápiz (pages/business-onboarding/step-info/step-info.html:42) -->
+<sui-image-upload shape="circle" size="lg" src={logoPreview} onSrcChange={(e) => (logoPreview = e.detail)} title="Subir logo"
+                  onImageSelected={(e) => onLogoSelected(e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-image-upload shape="rect" size="xl" editable src={logoPreview} onSrcChange={(e) => (logoPreview = e.detail)} title="Sube tu logo"
+                  onImageSelected={(e) => onLogoSelected(e.detail)} onEditRequested={() => abrirRecortador()} />
+```
+
+Comprobante de pago
+
+```html
+<!-- ❌ mal: una captura vertical se recorta en el cuadrado de 200 y el «Quitar» queda en 32 (pages/central/central-gastos/central-gastos.html:118) -->
+<sui-image-upload shape="rect" size="xl" src={vistaComprobante()} maxSize={10 * 1024 * 1024}
+  title="Subir comprobante" onImageSelected={(e) => onComprobante(e.detail)} onRemoved={() => quitarComprobante()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-image-upload #comprobante shape="rect" fluid editable src={vistaComprobante()}
+  maxSize={10 * 1024 * 1024} title="Sube el comprobante" onImageSelected={(e) => onComprobante(e.detail)}
+  onEditRequested={() => comprobante.abrirSelector()} onRemoved={() => quitarComprobante()} />
+```
+
+Banner apaisado
+
+```html
+<!-- ❌ mal: con fluid, size no hace nada; y sin editable (pages/promociones/promociones.html:186) -->
+<sui-image-upload shape="rect" size="lg" fluid src={campaignBannerPreview()}
+                  title="Subir banner" onImageSelected={(e) => onBannerImage(e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-image-upload #banner shape="rect" fluid editable src={campaignBannerPreview()}
+                  title="Sube el banner" onImageSelected={(e) => onBannerImage(e.detail)}
+                  onEditRequested={() => banner.abrirSelector()} onRemoved={() => onBannerRemoved()} />
+```
+
+## Ejemplo
+
+```html
+<!-- Comprobante: ancho completo, el lápiz elige otra captura -->
+<sui-image-upload #comprobante shape="rect" fluid editable
+                  src={vistaPrevia()} maxSize={10 * 1024 * 1024}
+                  title="Sube el comprobante" subtitle="Captura del Yape o del banco — máx 10 MB"
+                  onImageSelected={(e) => alElegir(e.detail)} onEditRequested={() => comprobante.abrirSelector()}
+                  onRemoved={() => quitar()} />
+
+<!-- Foto del producto: cuadrada, el lápiz abre el recortador -->
+<sui-image-upload shape="rect" size="xl" editable src={foto()}
+                  title="Sube tu foto" subtitle="JPG, PNG o WebP — se comprime sola"
+                  onImageSelected={(e) => alElegir(e.detail)} onEditRequested={() => abrirRecortador()}
+                  onRemoved={() => quitarFoto()} />
+```

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

@@ -0,0 +1,236 @@
+---
+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
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-image-upload-profile`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+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). Las reglas marcadas canon están aprobadas y las de «según el código» describen
+> el componente; lo que sigue en **propuesta** espera decisió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. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `company` | Un negocio. Vacío muestra edificios. Ojo: lo muestra en círculo. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+
+### `alignment`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `vertical` (default) | Con texto: título y requisitos («Mín. 400 × 400 px, PNG o JPEG»), avatar de 64. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `horizontal` | Sin texto, solo los botones al lado del avatar de 56. Cuando el label ya está arriba (`sui-form-label`). | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+
+### Textos y estados
+
+| input | cuándo | fuente |
+|---|---|---|
+| `title` | Qué es: «Tu foto», «Foto de perfil». Solo se ve en `vertical`. | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `subtitle` | Requisitos reales: formatos que se aceptan y para qué se usa («La ve el cliente cuando llevas su pedido»). | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `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. | según el código |
+| `companyLogoSrc` | Solo con `type="company"`: el logo, que gana sobre `imageUrl`. | según el código |
+| `loading` | **Siempre** mientras se comprime y se sube: deshabilita los botones y atenúa la foto. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `disabled` | La persona no puede cambiarla (cuenta verificada con foto bloqueada). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+
+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()}
+                          onUpload={() => input.click()} onChange={() => input.click()} onRemove={() => quitar()} />
+<input #input type="file" accept="image/jpeg,image/png,image/webp" hidden onChange={(e) => alElegir(e)} />
+```
+
+**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`.
+
+### Por dispositivo (D16)
+
+No aplica: **no tiene `size`** y nada cambia por dispositivo (avatar de 64/56 y botones `xsmall`
+de 32 fijos). Con D16 (dueño, 05-10-2026) lo que se toca va `large` en el celular y en la tablet
+táctil, y esos botones no llegan a 44, así que en una pantalla táctil no se usa:
+
+| dispositivo | qué va | ¿llega a 44? |
+|---|---|---|
+| celular y celular chico (≤ 767) | `sui-image-upload` `circle` `xl` con `editable` | sí: su lápiz y su tacho se tocan en 44 con el área invisible |
+| tablet táctil (`pointer: coarse`, > 767) | `sui-image-upload` `circle` `xl` con `editable` (40 contra 32, el que más se acerca) | **no, pendiente**: el área de 44 de `sui-image-upload` se prende solo hasta 767 px y en la tablet quedan en 40; espera el mixin `sui-tactil` del DS (§0 de las decisiones, sin el sí del dueño todavía) |
+| computadora y ultrawide | este componente, botones de 32 | no hace falta 44; se queda en 32 porque solo tiene ese tamaño de botón. Subirlo a `medium` es código del DS (un `size`), **pendiente** |
+
+En master-pedidos: no lleva `size`; si la pantalla se usa en un dispositivo táctil,
+`@if (!bp.tactil())` para este componente y `sui-image-upload` en el otro caso (con la tablet
+todavía en 40, ver la tabla).
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `alignment` | `alignment` | `"horizontal" \| "vertical"` | `'vertical'` |
+| `companyLogoSrc` | `company-logo-src` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `heading` | `heading` | `null \| string` | `null` |
+| `imageUrl` | `image-url` | `null \| string` | `null` |
+| `labels` | — (solo por propiedad JS) | `SuiImageUploadProfileLabels` | `{}` |
+| `loading` | `loading` | `boolean` | `false` |
+| `subtitle` | `subtitle` | `null \| string` | `null` |
+| `type` | `type` | `"avatar" \| "company"` | `'avatar'` |
+
+| evento | `event.detail` |
+|---|---|
+| `imageChange` | `void` |
+| `remove` | `void` |
+| `upload` | `void` |
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Eventos de Angular que aquí no existen:** `change`
+- **Props solo de aquí:** `heading`
+- **Eventos solo de aquí:** `imageChange`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `imagen.perfilTitulo` | Subir imagen | `title` |
+| `imagen.perfilSubtitulo` | Mín. 400x400px, PNG o JPEG | `subtitle` |
+| `imagen.subir` | Subir | `labels.upload` |
+| `imagen.eliminar` | Eliminar | `labels.remove` |
+| `imagen.cambiarCorto` | Cambiar | `labels.change` |
+<!-- textos: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.
+
+## Bien y mal
+
+Logo del local
+
+```html
+<!-- ❌ mal: company lo muestra en círculo y el logo se ve cuadrado en el home (vitrina: pages/super-admin/master-preview/_guia-moleculas/fechas.ts:233) -->
+<sui-image-upload-profile type="company" title="Logo del local" subtitle="JPG o PNG, cuadrado" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-image-upload shape="rect" size="xl" editable src={logo()} title="Sube tu logo"
+                  onImageSelected={(e) => alElegirLogo(e.detail)} onEditRequested={() => abrirRecortador()} />
+```
+
+Subir la foto
+
+```html
+<!-- ❌ mal: no tiene input de archivo; «Subir» y «Cambiar» solo emiten y no abren nada (Trampas) -->
+<sui-image-upload-profile title="Foto de perfil" imageUrl={foto()} onUpload={() => subir()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-image-upload-profile title="Foto de perfil" imageUrl={foto()} loading={subiendo()}
+                          onUpload={() => input.click()} onChange={() => input.click()} onRemove={() => quitar()} />
+<input #input type="file" accept="image/jpeg,image/png,image/webp" hidden onChange={(e) => alElegir(e)} />
+```
+
+Foto de perfil en el celular
+
+```html
+<!-- ❌ mal: los botones miden 32 y en una pantalla táctil no llegan a 44 (D16) -->
+<sui-image-upload-profile title="Tu foto" imageUrl={foto()} onUpload={() => input.click()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-image-upload shape="circle" size="xl" editable src={foto()} title="Sube tu foto"
+                  onImageSelected={(e) => alElegir(e.detail)} onEditRequested={() => abrirRecortador()} />
+```
+
+## Ejemplo
+
+```html
+<sui-image-upload-profile title="Foto de perfil" subtitle="La ve el cliente cuando llevas su pedido"
+                          imageUrl={foto()} loading={subiendo()}
+                          onUpload={() => elegir()} onChange={() => elegir()} onRemove={() => quitar()} />
+```