@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-fancy-button/README.md

@@ -0,0 +1,230 @@
+---
+name: sui-fancy-button
+selector: sui-fancy-button
+resumen: Botón con brillo y degradé para el CTA de una landing o campaña
+alternativas: [sui-button (toda acción dentro de la app), sui-app-store-badge (descargar la app desde una landing)]
+---
+
+# sui-fancy-button
+
+<!-- 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-fancy-button`); 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.
+
+Story: [Atoms/Button/Fancy Button](https://sui-design-system.web.app/?path=/docs/atoms-button-fancy-button--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Hoy no se usa** (0 usos en la app). Es el mismo botón que `sui-button` con un acabado de
+marketing: brillo arriba, borde interior claro y un anillo del color del botón.
+
+**Cuándo sí, en un flujo nuevo**: el CTA principal de una landing (`/empresas`, `/repartidores`),
+«Mejorar plan» o una campaña puntual. Uno por pantalla.
+
+**No lo uses** para:
+
+- **Cualquier acción dentro de la app**: `sui-button`. Al lado de botones normales, el fancy
+  compite con todo y rompe la jerarquía.
+- **Una acción destructiva**: `sui-button` `color="error"`.
+- **Descargar la app**: `sui-app-store-badge`.
+
+## Qué variante usar
+
+> **La guía del DS no dice cuándo usar cada tipo.** Su página lo presenta como «botones normales
+> con una apariencia vistosa» y muestra los cuatro tipos, los tres tamaños, los íconos y el
+> deshabilitado, sin do/don't. Todo el componente está en **«no usar» (canon, aprobado por el
+> dueño, 03-10-2026)**; la tabla dice dónde iría cada tipo si aparece el caso.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0** fancy-buttons, sin contar
+> prototipos ni vitrinas.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: un botón normal con un acabado más vistoso.
+- **Default**: `neutral` (negro) en la guía; **`primary` en SUI**.
+- **Tamaños**: `medium` (40), `small` (36) y `xsmall` (32). SUI agrega `large` (48) para el teléfono (04-10-2026).
+- **Hover**: el brillo se aclara, no se oscurece. `basic` pasa a fondo gris plano.
+- **Deshabilitado**: fondo gris plano, sin brillo, sin anillo ni sombra, igual en los cuatro tipos.
+
+### `type` (el relleno)
+
+| type | dónde iría, en un flujo nuevo | ejemplo de copy | fuente |
+|---|---|---|---|
+| `primary` (default SUI) | El CTA principal de una landing o una campaña. Uno por pantalla. | «Empieza gratis», «Mejorar plan» | no usar hoy · cuándo sí: canon (aprobado por el dueño, 03-10-2026) |
+| `neutral` (default de la guía) | El CTA de una landing sobre una sección clara donde el naranja ya se usó arriba. | «Ver planes» | no usar hoy (en la app va `sui-button`) · cuándo sí: propuesta |
+| `basic` | El secundario al lado de un fancy `primary` en la misma landing. | «Saber más» | no usar hoy (en la app va `sui-button`) · cuándo sí: propuesta |
+| `destructive` | Ninguno a la vista: una acción destructiva nunca es marketing. | — | no usar (en la app va `sui-button` `error`) · canon (aprobado por el dueño, 03-10-2026) |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `large` (48) | El CTA en el teléfono. Texto 16. | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono; extensión de SUI, la guía no lo tiene |
+| `medium` (40, default) | El CTA de la landing en la computadora, también dentro de la card de un plan. | escala y default según la guía del DS · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) · la card de un plan: canon (dueño, 05-10-2026, D16) |
+| `small` (36) | No usar: es chico. El CTA dentro de la card de un plan va `medium`. | escala según la guía del DS · no usarlo: canon (dueño, 05-10-2026, D16), reemplaza el «cuándo» del bloque B1 |
+| `xsmall` (32) | Sin caso: en una landing el CTA nunca es tan chico. | escala según la guía del DS · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+### Íconos y `disabled`
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `rightIcon` (`arrow-right-line`) | El CTA lleva a otra página: «Empieza gratis →». | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `leftIcon` | El ícono dice la acción (descargar, WhatsApp). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `disabled` | Casi nunca: un CTA de marketing no se deshabilita, se esconde. | cómo se ve: según la guía del DS · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `href` | El CTA navega (lo normal en una landing): pinta un `<a>`; `rel` ya viene en `'noopener noreferrer'`. | canon (aprobado por el dueño, 05-10-2026, bloque B10) |
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: el área táctil tiene que medir **44 px o más** (canon (dueño, 04-10-2026): piso táctil 44 en el teléfono). En la tablet
+(`pointer: coarse`) va igual que en el celular; en la computadora (`pointer: fine`), `medium`; en el celular
+chico (< 380 px), `medium` a la vista sin bajar el área de 44. Nada en `small` ni `xsmall` (canon, dueño,
+05-10-2026, D16). Hoy la app lo resuelve con `BreakpointsService` (`src/app/services/breakpoints.service.ts`,
+mobile = hasta 767 px).
+
+| size | alto | texto | cuándo | fuente |
+|---|---|---|---|---|
+| `large` | 48 | 16 (Label/Medium) | CTA en el teléfono | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono. Size nuevo del 04-10-2026 |
+| `medium` (default) | 40 | 14 | CTA en web | Figma |
+| `small` | 36 | 14 | — (no se usa: D16) | Figma |
+| `xsmall` | 32 | 14 | — | Figma |
+
+**Por qué `large` = 48 y no 44**: el fancy es «el mismo botón con otro acabado» que `sui-button` y su
+escala lo espeja tal cual (medium 40 / small 36 / xsmall 32). El siguiente es `large`, y el
+`large` de sui-button mide 48: el fancy en el teléfono queda del mismo alto que el botón normal
+que va al lado. El texto sube a 16 (regla de tamaños del 03-10-2026); los íconos siguen en 20.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| CTA principal de una landing | `large` (48) | `medium` (40) | mobile: canon (decisión del dueño 04-10-2026, piso táctil 44) · web: canon (dueño, 05-10-2026, D16) |
+| CTA dentro de la card de un plan | `large` (48) | `medium` (40) | mobile: canon (decisión del dueño 04-10-2026, piso táctil 44) · web: canon (dueño, 05-10-2026, D16) |
+
+```html
+<sui-fancy-button type="primary" size={bp.sizeControl()}>Empieza gratis</sui-fancy-button>
+```
+
+Hoy no hay usos (todo el componente está en «no usar»).
+
+### Por dispositivo (D16)
+
+Se toca, así que va como «lo que se toca»; la fila de `fancy-button` de la tabla D16 manda
+(canon, dueño, 05-10-2026, D16).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `medium` + área de 44 ¹ | ¹ el DS todavía no estira a 44 el área del `medium` (40): hasta que lo haga, va `large`, que es lo que ya da el helper |
+| celular (380–767 px) | `large` (48) | del mismo alto que el `large` de `sui-button` que va al lado |
+| tablet táctil (`pointer: coarse`) | `large` (48) | Apple pide 44 pt también en el iPad; `bp.isMobile()` sola la deja en `medium` |
+| computadora (`pointer: fine`) | `medium` (40) | también dentro de la card de un plan; `small` y `xsmall` no se usan |
+
+Ultrawide (≥ 1920 px): igual que la computadora, `medium`. El espacio extra va al ancho de la
+sección, no a un CTA más grande.
+
+En master-pedidos: `size={bp.sizeControl()}` (`large` en el celular y en toda pantalla táctil,
+`medium` en la computadora).
+
+## «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 |
+|---|---|---|
+| `sui-fancy-button` (los 4 tipos) | Es estilo de marketing (brillo, degradé); en la app compite con todo | el CTA principal de una landing (`/empresas`, `/repartidores`), «Mejorar plan» o una campaña |
+| `type="destructive"` | Una acción destructiva va con `sui-button` `error` | no se ve un caso: una destructiva no es marketing |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `ariaLabel` | `aria-label` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `href` | `href` | `null \| string` | `null` |
+| `htmlType` | `html-type` | `"button" \| "reset" \| "submit"` | `'button'` |
+| `leftIcon` | `left-icon` | `null \| string` | `null` |
+| `rel` | `rel` | `null \| string` | `'noopener noreferrer'` |
+| `rightIcon` | `right-icon` | `null \| string` | `null` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xsmall"` | `'medium'` |
+| `target` | `target` | `null \| string` | `null` |
+| `type` | `type` | `"basic" \| "destructive" \| "neutral" \| "primary"` | `'primary'` |
+
+| evento | `event.detail` |
+|---|---|
+| `clicked` | `MouseEvent` |
+
+Slots: `(por defecto)`.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+El clic se escucha con `clicked`. Slots: `<slot>` (el texto).
+
+## Trampas
+
+- **Con `href` el texto se veía vacío** hasta la rama `ssr-fixes` (19-10-2026): el `<slot>` del `<a>` no recibía nada. Ahora las dos ramas comparten un solo `<slot>` (como `sui-link-button`).
+
+- **`type` es el relleno**, no el `type` HTML: ese se llama **`htmlType`**. `type="submit"` no
+  compila (no es un tipo válido) y no hace un submit.
+- **El radio es 10 px, no pill.** Al lado de un `sui-button` (pill en SUI) se ven de dos familias.
+- **`large` (48) es de SUI** (04-10-2026), no de la guía: en el teléfono va ese, del mismo alto que
+  el `large` de `sui-button`. No hay `xlarge`.
+- **El default es `primary`**; en la guía es `neutral`.
+- El anillo del `neutral` es un hex crudo (`#242628`): no hay token para ese gris.
+- Ya trae el arreglo de iOS para el `:active` pegado: no lo agregues.
+
+## Bien y mal
+
+**El CTA en el teléfono y en la computadora**
+
+```html
+<!-- ❌ mal: dos componentes para el mismo CTA. La vitrina (master-preview/_guia-atomos/botones.ts:138)
+     todavía pone sui-button large en mobile «porque el fancy mide 40»; desde el 04-10 tiene large (48) -->
+<sui-button size="large">Empieza gratis</sui-button>
+<sui-fancy-button type="primary" size="medium">Empieza gratis</sui-fancy-button>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-fancy-button type="primary" size={bp.sizeControl()}>Empieza gratis</sui-fancy-button>
+```
+
+**Un formulario que se envía**
+
+```html
+<!-- ❌ mal: `type` es el relleno, no el type HTML; no compila y no hace submit (Trampas) -->
+<sui-fancy-button type="submit">Crear cuenta</sui-fancy-button>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-fancy-button type="primary" html-type="submit" size={bp.sizeControl()}>Crear cuenta</sui-fancy-button>
+```
+
+**Una acción destructiva**
+
+```html
+<!-- ❌ mal: una destructiva no es marketing («No usar»), y el brillo la vuelve llamativa -->
+<sui-fancy-button type="destructive">Eliminar cuenta</sui-fancy-button>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-button variant="filled" color="error" size={bp.sizeControl()}>Eliminar cuenta</sui-button>
+```
+
+## Ejemplo
+
+```html
+<!-- Solo en una landing: el CTA principal -->
+<sui-fancy-button type="primary" right-icon="arrow-right-line" href="/auth/empresa/registro">
+  Empieza gratis
+</sui-fancy-button>
+```

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

@@ -0,0 +1,184 @@
+---
+name: sui-file-icon
+selector: sui-file-icon
+resumen: El ícono de un archivo con su extensión (PDF, XLSX, JPG…) en el color de su tipo
+alternativas: [sui-file-upload-card (el archivo que se está subiendo, con progreso), sui-icon (un ícono genérico de documento)]
+---
+
+# sui-file-icon
+
+<!-- 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-file-icon`); 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.
+
+Story: [Atoms/Icon/File Icon](https://sui-design-system.web.app/?path=/docs/atoms-icon-file-icon--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en una **lista de archivos**: comprobantes, documentos del repartidor, un reporte para
+descargar. La etiqueta con la extensión le dice a la persona qué va a abrir.
+
+**No lo uses** para:
+
+- Un archivo que se está subiendo: `sui-file-upload-card` (ya lo trae adentro).
+- Una foto: si se puede ver, se muestra la miniatura.
+- Un ícono de «documento» en general, sin archivo detrás: `sui-icon`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente.** Las reglas marcadas canon
+> están aprobadas; la tabla de mobile y web quedó en canon el 05-10-2026 (P1 b y D16).
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. Lo usa por dentro
+> `sui-file-upload-card`.
+
+### `filename`, `extension`, `color`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `filename` | Siempre que haya nombre: saca la extensión y el color solo (`comprobante.pdf` → PDF en rojo). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `extension` | Solo si el nombre no la trae (un archivo de Storage sin extensión). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `color` | No usar: el color dice el tipo y forzarlo miente (un CSV en rojo parece PDF). | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+Colores automáticos: PDF rojo · Word y texto azul · Excel y CSV verde · PowerPoint naranja ·
+imágenes rosa · video morado · audio celeste · comprimidos amarillo · el resto gris.
+
+### `size`
+
+| valor | px | cuándo | fuente |
+|---|---|---|---|
+| `medium` (default) | 40 | Siempre: listas de documentos, filas y tablas, en el celular, la tablet y la computadora. | canon (aprobado por el dueño, 05-10-2026, bloque B1) · también filas y tablas: canon (dueño, 05-10-2026, D16) |
+| `xsmall` | 32 | No usar: es chico. Las filas densas y las tablas van en `medium`. | canon (dueño, 05-10-2026, D16); reemplaza el «filas densas, tablas» del bloque B1 |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+En mobile se lee y se toca con el dedo, así que va más grande; en web, más chico. En las
+pantallas que se usan en los dos (panel del local, super admin) se elige con el servicio de
+breakpoints de la app (`bp`, en `services/breakpoints.service.ts`); en las que solo existen en
+el celular (cliente, repartidor) va directo el valor de mobile. No se toca, así que la tablet va
+con el valor de web, y el celular chico (< 380 px) también (D16).
+Es **canon (dueño, 05-10-2026, P1 b y D16)**.
+
+| uso | mobile | web |
+|---|---|---|
+| fila de una lista | `medium` (40) | `medium` (40) |
+
+```html
+<sui-file-icon filename={doc.nombre} size="medium" />
+```
+
+El ícono no se toca: si la fila abre el archivo, la fila da los 44 px. `medium` es el tamaño más
+grande que tiene y `xsmall` es chico (D16), así que va igual en las dos: es la excepción a P1 b
+(«un paso más grande en el celular»), porque no hay un paso más.
+
+### Por dispositivo (D16)
+
+No se toca; la fila de `file-icon` de la tabla D16 manda (canon, dueño, 05-10-2026, D16).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `medium` (40) | |
+| celular (380–767 px) | `medium` (40) | es el más grande que tiene: no hay un paso más para subir (P1 b) |
+| tablet táctil (`pointer: coarse`) | `medium` (40) | si la fila abre el archivo, los 44 los da la fila |
+| computadora (`pointer: fine`) | `medium` (40) | también en filas densas y tablas; `xsmall` no se usa |
+
+Ultrawide (≥ 1920 px): igual, `medium`.
+
+En master-pedidos: `size="medium"` fijo, o se omite (es el default). No hay helper ni hace falta `bp`.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos directos) | no hay listas de archivos | los documentos del repartidor (DNI, licencia, SOAT) o un reporte para descargar en CSV |
+| `color` | el color dice el tipo; forzarlo miente | ninguno: si la extensión no se reconoce, sale gris y está bien |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `color` | `color` | `"" \| "blue" \| "gray" \| "green" \| "orange" \| "pink" \| "purple" \| "red" \| "teal" \| "yellow"` | `''` |
+| `extension` | `extension` | `string` | `''` |
+| `filename` | `filename` | `string` | `''` |
+| `size` | `size` | `"medium" \| "xsmall"` | `'medium'` |
+
+Eventos: ninguno.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- 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 |
+|---|---|---|
+| `archivo.tipo` | Archivo {ext} | — |
+| `archivo.icono` | Archivo | — |
+<!-- textos:fin -->
+
+## Trampas
+
+- **La extensión se corta a 4 letras** y va en mayúsculas: `.jpeg` → `JPEG`, `.numbers` → `NUMB`.
+- **`extension` gana sobre `filename`.**
+- El nombre para el lector de pantalla es «Archivo PDF» (en español desde el 04-10-2026) y no se puede cambiar.
+- `size` es `xsmall` o `medium`: no hay `small` ni `large`.
+
+## Bien y mal
+
+**Un archivo en una tabla**
+
+```html
+<!-- ❌ mal: xsmall es chico (D16). La vitrina (master-preview/_guia-atomos/identidad.ts:422)
+     todavía lo ofrece para «filas densas, tablas» -->
+<sui-file-icon filename={doc.nombre} size="xsmall" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-file-icon filename={doc.nombre} size="medium" />
+```
+
+**El color del tipo**
+
+```html
+<!-- ❌ mal: forzar el color miente; un CSV en rojo parece PDF (vitrina identidad.ts:424) -->
+<sui-file-icon filename="ventas.csv" color="red" />
+```
+
+```html
+<!-- ✅ bien: el color sale solo de la extensión (CSV en verde) -->
+<sui-file-icon filename="ventas.csv" />
+```
+
+**Un archivo que se está subiendo**
+
+```html
+<!-- ❌ mal: el ícono solo no dice cómo va la subida («Cuándo no») -->
+<sui-file-icon filename="carta-octubre.pdf" />
+```
+
+```html
+<!-- ✅ bien: la card ya trae el ícono, la barra y el estado -->
+<sui-file-upload-card file="carta-octubre.pdf" state="in-progress" progress="45"
+                      description="1.2 MB de 2.6 MB" />
+```
+
+## Ejemplo
+
+```html
+<sui-file-icon filename="comprobante-yape.pdf" />
+<sui-file-icon filename="ventas-setiembre.csv" size="medium" />
+```

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

@@ -0,0 +1,246 @@
+---
+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
+
+<!-- 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-file-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/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. Lo de abajo marcado canon
+> está aprobado; el `small` en mobile sigue en propuesta: lo cubre **P13, pendiente**. D16 en
+> general no usa `small`, pero la hoja de decisiones (05-10-2026) dejó estas filas esperando la
+> respuesta a P13.
+>
+> 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, canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+
+### `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. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `multiple` | Varios archivos del mismo tipo (las boletas del mes). Con `multiple` cada archivo va en su `sui-file-upload-card`. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `maxSize` | Siempre, en **bytes** (`10 * 1024 * 1024`), y el mismo número en el `subtitle`. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+
+### `size`
+
+| valor | padding | cuándo | fuente |
+|---|---|---|---|
+| `small` | 24 | Propuesta: en mobile y dentro de un modal o una card. Pendiente (P13): la opción recomendada es que no (en mobile `medium` o `large`, por D8), y D16 en general no usa `small`, pero el dueño todavía no respondió. | pendiente (P13) |
+| `medium` (default) | 32 | En web, en una página o un modal ancho. En mobile: pendiente (P13). | guía (es el único tamaño que muestra) |
+| `large` | 40 | Cuando subir el archivo es lo único de la pantalla (importar la carta). | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| `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. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `disabled` | Mientras se sube, o si ya se llegó al máximo de archivos. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+
+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 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 | pendiente (P13) | `medium` | mobile: pendiente (P13; la propuesta era `small`) · web: guía |
+| subir es lo único de la pantalla | `medium` | `large` | canon (aprobado por el dueño, 05-10-2026, bloque B1) · va al revés de D16: ver abajo |
+
+```html
+<!-- en web, en un formulario o modal; el size en mobile espera P13 -->
+<sui-file-upload size="medium"
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB"
+                 accept=".pdf" maxSize={10 * 1024 * 1024} onFilesSelected={(e) => subir(e.detail)} />
+```
+
+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.
+
+### Por dispositivo (D16)
+
+**Pendiente (P13).** `file-upload` no está en la tabla por componente de D16, y la hoja de
+decisiones (05-10-2026, «Lo que esta hoja no cierra») deja sus dos filas de tamaño esperando P13.
+Se toca, así que la regla general de D16 sería «lo que se toca»: grande en el celular y en la
+tablet, `medium` en la computadora (y en ultrawide). Eso choca con la fila de B1 («subir es lo
+único de la pantalla»: `medium` en mobile y `large` en web), que va en la dirección contraria, y
+D16 dice que reemplaza el tamaño por plataforma. Cuál manda no está decidido: se resuelve con P13.
+
+Hasta entonces, lo cerrado es: `medium` en la computadora en un formulario o modal (guía) y
+`xlarge` no se usa. Si P13 cierra con la regla general de D16, en master-pedidos quedaría
+`size={bp.tactil() ? 'large' : 'medium'}` (no hay helper propio; `sizeControl()` es de
+botón, input, select y textarea).
+
+## «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` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `accept` | `accept` | `string` | `''` |
+| `browseLabel` | `browse-label` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `error` | `error` | `boolean` | `false` |
+| `errorMessage` | `error-message` | `null \| string` | `null` |
+| `heading` | `heading` | `null \| string` | `null` |
+| `maxSize` | `max-size` | `number` | `0` |
+| `multiple` | `multiple` | `boolean` | `false` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xlarge"` | `'medium'` |
+| `subtitle` | `subtitle` | `null \| string` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `errorEvent` | `string` |
+| `filesSelected` | `File[]` |
+
+### 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 |
+|---|---|---|
+| `archivo.buscar` | Buscar archivo | `browseLabel` |
+| `archivo.soltarVarios` | Arrastra y suelta los archivos aquí | `title` |
+| `archivo.soltarUno` | Arrastra y suelta el archivo aquí | `title` |
+| `archivo.oClic` | o haz clic para seleccionar | `subtitle` |
+<!-- textos:fin -->
+
+## Trampas
+
+- `browseLabel` dice «Buscar archivo» por defecto (antes «Browse File»).
+- **Con teclado el control es «Buscar archivo»**, no el área. Desde el 04-10-2026 el host ya no
+  es `role="button"` ni entra en el Tab (era un control con otro adentro y Enter pedía el selector
+  dos veces). Con el mouse o el dedo, tocar cualquier parte del área sigue abriendo el selector.
+- **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).
+
+## Bien y mal
+
+**El error que se pasa a mano**
+
+```html
+<!-- ❌ mal: el componente ya muestra solo el aviso de tamaño debajo del área (y lo emite por errorEvent); este errorMessage lo tapa con otro texto -->
+<sui-file-upload accept=".pdf" maxSize={10 * 1024 * 1024}
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB"
+                 error={pesaDeMas()} error-message="El archivo pesa más de 10 MB" />
+```
+
+```html
+<!-- ✅ bien: errorMessage solo para lo que rechaza el servidor después de subirlo -->
+<sui-file-upload accept=".pdf" maxSize={10 * 1024 * 1024}
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB"
+                 error={rechazado()} error-message="El PDF está protegido con clave" />
+```
+
+**El límite de tamaño**
+
+```html
+<!-- ❌ mal: maxSize va en bytes (10 = 10 bytes) y el subtitle no dice formatos ni tamaño (Trampas) -->
+<sui-file-upload accept=".pdf" max-size="10" title="Sube tu carta" />
+```
+
+```html
+<!-- ✅ bien: el mismo límite en el filtro y en el texto -->
+<sui-file-upload accept=".pdf" maxSize={10 * 1024 * 1024}
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB" />
+```
+
+**El filtro y el texto**
+
+```html
+<!-- ❌ mal: el subtitle promete Excel y accept lo rechaza: la persona elige un archivo que no entra -->
+<sui-file-upload accept=".pdf" title="Sube tu carta" subtitle="PDF o Excel, hasta 10 MB" />
+```
+
+```html
+<!-- ✅ bien: lo que promete el subtitle es lo que dejan pasar accept y maxSize -->
+<sui-file-upload accept=".pdf,.xlsx" maxSize={10 * 1024 * 1024}
+                 title="Sube tu carta" subtitle="PDF o Excel, hasta 10 MB" />
+```
+
+## Ejemplo
+
+```html
+<sui-file-upload title="Sube tu carta en PDF o Excel" subtitle="PDF o Excel, hasta 10 MB"
+                 browse-label="Buscar archivo" accept=".pdf,.xlsx" maxSize={10 * 1024 * 1024}
+                 onFilesSelected={(e) => subirCarta(e.detail)} onErrorEvent={(e) => avisar(e.detail)} />
+```