@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-popover/README.md

@@ -0,0 +1,282 @@
+---
+name: sui-popover
+selector: sui-popover
+resumen: Panel con flecha que señala un elemento de la pantalla y explica algo nuevo, con una o dos acciones; sirve para recorridos de bienvenida
+alternativas: [sui-tooltip (ayuda corta al pasar el mouse, sin acciones), sui-alert (aviso dentro del contenido), sui-modal (algo que pide decidir antes de seguir)]
+---
+
+# sui-popover
+
+<!-- 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-popover`); 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/Popover](https://sui-design-system.web.app/?path=/docs/molecules-popover--docs)
+
+Es **solo el panel**: no se abre solo, no se ancla al elemento ni se cierra al tocar afuera. Quien
+lo usa decide cuándo mostrarlo y dónde ponerlo (un overlay del CDK, o posicionado a mano junto al
+elemento). `position` solo mueve la flecha.
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para **señalar una parte de la pantalla** y decir algo que la persona todavía no sabe,
+con un paso a seguir: el recorrido de bienvenida del panel del local la primera vez que entra, o
+una función nueva que conviene mostrar donde está («Aquí programas tus pedidos»).
+
+**No lo uses** para:
+
+- La explicación de un ícono o un término sin acción: en web es `sui-tooltip`; en mobile, texto
+  visible o un `sui-modal-sheet`.
+- Un aviso que no señala nada en particular: `sui-alert` o `sui-toast`.
+- Pedir una decisión que bloquea («¿Cancelar el pedido?»): `sui-modal`.
+- Un menú de opciones: `sui-dropdown-menu`.
+
+## Qué variante usar
+
+> La guía del DS dice para qué es, pero no cuándo va cada pie ni cada posición. Lo marcado «según la
+> guía del DS» sale de su texto; «canon» es lo ya aprobado en la app; el resto es **propuesta**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (re-medido el 06-10-2026, sin cambios): **0
+> usos** fuera de la página de guía de master-preview, y ningún recorrido de bienvenida hecho a
+> mano. Todo lo de abajo es para el primer flujo que lo necesite.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: llamar la atención sobre **elementos específicos** de la interfaz.
+- Se posiciona arriba, abajo o a los costados del elemento que señala.
+- La guía no dice nada del pie con pasos; eso viene del Figma del DS (pie con puntos, con texto o
+  con dos botones a lo ancho).
+
+### `footer` — el pie
+
+| footer | cuándo | fuente |
+|---|---|---|
+| `stretch` (default) | Un aviso suelto con dos salidas a lo ancho: «Ahora no» / «Probar». Con `doubleButton=false`, una sola: «Entendido». | propuesta |
+| `stepper` | Un **recorrido de varios pasos**: los puntos dicen en cuál va y cuántos faltan. | propuesta |
+| `none` | Solo informa y se cierra con la X: «Aquí ves lo que ganaste hoy». | propuesta |
+| `text-stepper` | Recorridos de más de 5 pasos, donde los puntos ya no se cuentan: «Paso 3 de 7» (en español desde 03-10-2026). | propuesta |
+
+### Botones del pie
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `doubleButton` | `true` (default) | Desde el segundo paso de un recorrido («Atrás» / «Siguiente»), o un aviso suelto con «Ahora no» / «Probar». | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `doubleButton` | `false` | El primer paso de un recorrido o un aviso suelto con una sola salida («Entendido»). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `backLabel` · `nextLabel` | texto en español | Los defaults ya son «Atrás» y «Siguiente» (03-10-2026); el último paso pasa `nextLabel="Listo"`. | canon (CANON-SUI §5.1 y §5.3: sentence case, tuteo) |
+| orden | secundario a la izquierda, primario a la derecha | Ya lo hace el componente (stroke neutral + filled primary), igual que `sui-modal-footer`. | canon (CLAUDE.md, «Botones — composición y orden») |
+| `step` | `{ current, total }` | Con `stepper`. Sin `step`, el componente asume **1 de 4**. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+
+### Flecha, ícono, texto y cierre
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `tail` | `true` (default) | Siempre que señala algo: la flecha es lo que dice «es esto». | según la guía del DS (se posiciona junto al elemento) |
+| `tail` | `false` | No usar hoy. **Cuándo sí:** la bienvenida inicial de un recorrido, centrada, sin elemento al que apuntar. | propuesta |
+| `position` | `top-*` | El popover va **debajo** del elemento (la flecha arriba). Lo normal: el elemento sigue a la vista. | propuesta |
+| `position` | `bottom-*` | El elemento está abajo (la barra de pestañas): el popover va encima. | propuesta |
+| `position` | `left-*` · `right-*` | Elementos de una barra lateral (el sidebar del panel). | propuesta |
+| `position` | `*-left` · `*-center` · `*-right` | Alinea la flecha con el elemento cuando el popover no puede centrarse sobre él (está cerca de un borde). | propuesta |
+| `icon` | el de lo que se explica | Siempre uno que diga el tema (`calendar-schedule-line` para programar). El default es un ícono de persona. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `icon` | `null` | Cuando el texto ya basta y el ícono sería decoración. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `title` | frase corta | Qué es, en sentence case y sin punto final. | canon (CANON-SUI §5.1 y §5.2) |
+| `description` | una o dos frases | Qué hace o por qué importa. | propuesta |
+| `dismissIcon` | `true` (default) | Siempre: un recorrido se puede saltar. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `dismissIcon` | `false` | No usar hoy. **Cuándo sí:** un paso que no se puede saltar porque sin él no funciona lo siguiente. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `slot="body"` | contenido propio | No usar hoy. **Cuándo sí:** el paso necesita una imagen o una lista en vez de título y texto. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+## Tamaño en mobile y en web
+
+El panel mide **320 px** de ancho fijo: cabe en un teléfono de 360 px o más con 16 px de margen a
+cada lado; en uno más angosto se sale. El `size` cambia **los botones del pie**:
+
+| size | botones del pie | fuente |
+|---|---|---|
+| `small` (default) | 36 px (`sui-button` `small`) | Figma |
+| `medium` | 40 px (`sui-button` `medium`) | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+| `large` | 48 px (`sui-button` `large`) | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono. Size nuevo del 04-10-2026 |
+
+La X se ve de 24 y **se toca en 40 × 40** en todos (un `::before` invisible sobre su botón,
+extensión SUI 03-10-2026).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| el panel | 320 px (cabe desde 352 px de pantalla) | 320 px | según el componente |
+| botones del pie | `large` (48), también en la tablet táctil | `medium` (40) | mobile: canon (dueño, 04-10-2026): piso táctil 44 en el teléfono · tablet y web: D16, dueño 05-10-2026; antes `small` (el default del componente: hay que pasarlo) |
+| la X | se ve de 24, se toca en 40 | igual | canon (aprobado por el dueño, 03-10-2026) |
+
+```html
+<sui-popover footer="stretch" size={bp.sizeControl()} … />
+```
+
+`large` es el siguiente de la escala del `sui-button` (48, el del footer de los modales). `medium`
+(40) es el de la computadora, con puntero fino (D16); no llega a 44, por eso no va en lo táctil.
+
+En mobile, si el recorrido es la bienvenida de la app, conviene una pantalla o un
+`sui-modal-sheet` por paso en vez del popover (propuesta, falta aprobación).
+
+### Por dispositivo (D16)
+
+Fila `popover` (botones del pie) de la tabla D16 (dueño, 05-10-2026). Los botones se tocan, así
+que van por tipo de puntero además del ancho. El panel no cambia: 320 px en todos.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `large` (48) | D16 pide `medium` con área tocable de 44; mientras el DS no estire el área de los `medium`, va `large` (interino). El panel de 320 cabe desde 352 px |
+| celular (380–767 px) | `large` (48) | |
+| tablet táctil (`pointer: coarse`) | `large` (48) | se toca con el dedo: Apple pide 44 pt también en el iPad |
+| computadora (`pointer: fine`) | `medium` (40) | el default es `small` (36): hay que pasarlo |
+
+Ultrawide (≥ 1920 px): igual que la computadora, `medium`.
+
+En master-pedidos: `size={bp.sizeControl()}` — el `size` del popover es el de sus `sui-button`,
+así que va el mismo helper del botón (`large` con `bp.tactil()`, `medium` si no). No uses
+`bp.isMobile()`: deja la tablet táctil en `medium`.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Hoy el popover entero tiene **0 usos**; esto es lo que no se usaría aunque llegue un flujo nuevo.
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el componente | no hay recorridos ni funciones nuevas que señalar | el recorrido de bienvenida del panel del local; mostrar dónde está una función nueva |
+| `footer="text-stepper"` | ningún recorrido largo hoy | recorridos de más de 5 pasos, donde los puntos ya no se cuentan («Paso 3 de 7») |
+| `tail=false` | todo popover señala algo | la bienvenida inicial, centrada |
+| `dismissIcon=false` | un recorrido siempre se puede saltar | un paso sin el que no funciona el siguiente |
+| `slot="body"` | título y texto alcanzan | un paso con imagen o lista |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `backLabel` | `back-label` | `string` | `'Atrás'` |
+| `closeLabel` | `close-label` | `string` | `'Cerrar'` |
+| `description` | `description` | `null \| string` | `null` |
+| `dismissIcon` | `dismiss-icon` | `boolean` | `true` |
+| `doubleButton` | `double-button` | `boolean` | `true` |
+| `footer` | `footer` | `"none" \| "stepper" \| "stretch" \| "text-stepper"` | `'stretch'` |
+| `heading` | `heading` | `string` | `''` |
+| `icon` | `icon` | `null \| string` | `'user-6-line'` |
+| `nextLabel` | `next-label` | `string` | `'Siguiente'` |
+| `position` | `position` | `"bottom-center" \| "bottom-left" \| "bottom-right" \| "left-bottom" \| "left-center" \| "left-top" \| "right-bottom" \| "right-center" \| "right-top" \| "top-center" \| "top-left" \| "top-right"` | `'top-left'` |
+| `size` | `size` | `"large" \| "medium" \| "small"` | `'small'` |
+| `step` | — (solo por propiedad JS) | `SuiPopoverStep \| null` | `null` |
+| `tail` | `tail` | `boolean` | `true` |
+
+| evento | `event.detail` |
+|---|---|
+| `back` | `void` |
+| `dismissed` | `void` |
+| `next` | `void` |
+
+Slots: `body`.
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Props solo de aquí:** `closeLabel`, `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 |
+|---|---|---|
+| `comun.cerrar` | Cerrar | — |
+| `popover.atras` | Atrás | `backLabel` |
+| `popover.siguiente` | Siguiente | `nextLabel` |
+| `comun.pasoDe` | Paso {actual} de {total} | — |
+<!-- textos:fin -->
+
+Slot: `slot="body"` reemplaza título y descripción.
+
+## Trampas
+
+- **Textos por defecto en español** (desde 03-10-2026): «Atrás», «Siguiente» y, en `text-stepper`,
+  «Paso X de N» (este último no se puede cambiar).
+- **El ícono por defecto es una persona** (`user-6-line`). Si no quieres ícono, `icon={null}`.
+- **`step` vacío = 1 de 4**: con `stepper` o `text-stepper`, pásalo siempre.
+- Con `stepper`, los puntos se leen como «Paso X de N» (`role="img"` con `aria-label`, desde el
+  04-10-2026; antes eran `aria-hidden` y el lector no sabía en qué paso iba).
+- **No se posiciona solo**: `position` cambia dónde sale la flecha, no dónde aparece el panel.
+  Tampoco se cierra al tocar afuera ni con Escape; cierra quien escucha `dismissed`.
+- `position` se lee «borde de la flecha, luego su lugar»: `top-left` es flecha **arriba a la
+  izquierda**, o sea, el popover queda **debajo** del elemento.
+- El host lleva `role="dialog"` con `aria-label` = `title` y borra el `title` nativo.
+- Los botones del pie no tienen `disabled`: si un paso no puede avanzar, se maneja desde `next`.
+- **`stretch` reparte el ancho entre los dos botones** y en los steppers miden 80 px como mínimo
+  (crecen si el texto no entra). Hasta el 03-10-2026 no pasaba: el `.scss` apuntaba a
+  `.sui-popover__btn` y el template pone `.sui-popover__action`.
+
+## Bien y mal
+
+Botones del pie
+
+```html
+<!-- ❌ mal: sin size queda en small, botones de 36. Sale de la página de guía, no de un uso real
+     (pages/super-admin/master-preview/_guia-moleculas/avisos.ts:224) -->
+<sui-popover position="top-center" icon="wallet-3-line" title="Aquí ves lo que ganaste hoy"
+  double-button="false" next-label="Entendido" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-popover position="top-center" icon="wallet-3-line" title="Aquí ves lo que ganaste hoy"
+  double-button="false" next-label="Entendido" size={bp.sizeControl()} />
+```
+
+Recorrido con puntos
+
+```html
+<!-- ❌ mal: sin step, los puntos dicen «1 de 4» aunque el recorrido tenga 3 pasos -->
+<sui-popover footer="stepper" icon="calendar-schedule-line" title="Programa tus pedidos"
+  size={bp.sizeControl()} onBack={() => anterior()} onNext={() => siguiente()} onDismissed={() => saltar()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-popover footer="stepper" step={{ current: 2, total: 3 }} icon="calendar-schedule-line"
+  title="Programa tus pedidos" size={bp.sizeControl()}
+  onBack={() => anterior()} onNext={() => siguiente()} onDismissed={() => saltar()} />
+```
+
+Ícono del tema
+
+```html
+<!-- ❌ mal: sin icon sale una persona (user-6-line), que no dice nada de programar -->
+<sui-popover title="Programa tus pedidos" description="Elige el día y la hora."
+  size={bp.sizeControl()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-popover icon="calendar-schedule-line" title="Programa tus pedidos"
+  description="Elige el día y la hora." size={bp.sizeControl()} />
+```
+
+## Ejemplo
+
+```html
+<!-- Paso 2 de 3 de un recorrido -->
+<sui-popover position="top-left" icon="calendar-schedule-line"
+  title="Programa tus pedidos" description="Elige el día y la hora, y el pedido entra solo a la cocina."
+  footer="stepper" step={{ current: 2, total: 3 }}
+  back-label="Atrás" next-label="Siguiente" size={bp.sizeControl()}
+  onBack={() => anterior()} onNext={() => siguiente()} onDismissed={() => saltar()} />
+
+<!-- Aviso suelto con una sola salida -->
+<sui-popover position="bottom-center" icon="wallet-3-line" title="Aquí ves lo que ganaste hoy"
+  double-button="false" next-label="Entendido" size={bp.sizeControl()}
+  onNext={() => cerrar()} onDismissed={() => cerrar()} />
+```

package/docs/sui-product-card/README.md

@@ -0,0 +1,257 @@
+---
+name: sui-product-card
+selector: sui-product-card
+resumen: Tarjeta de un producto de la carta con foto, nombre, descripción, precio y el botón para agregar (o editar)
+alternativas: [sui-store-card (un local, no un producto), sui-card (cualquier otro contenido), sui-content-card (un producto en una fila, sin foto grande)]
+---
+
+# sui-product-card
+
+<!-- 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-product-card`); 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: [Molecules/Product Card](https://sui-design-system.web.app/?path=/docs/molecules-product-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para cada producto en una grilla de la carta: la carta del local que ve el cliente y la
+grilla de productos que ve el dueño del local (con el lápiz).
+
+**No lo uses** para:
+
+- Un producto dentro del carrito, del checkout o del detalle de un pedido: ahí va una fila (sin
+  foto grande, con cantidad y subtotal).
+- Un local: `sui-store-card`.
+- Una promo o una campaña: tienen su propio carrusel.
+
+Regla corta: **producto en la grilla de la carta → product-card · producto en una lista de pedido
+→ fila.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la product card.** Es un componente propio de SUI, portado
+> de la carta de la app. La card **dibuja, no decide**: el precio, si se vende ahora y la
+> etiqueta de no disponible le llegan ya resueltos.
+>
+> Uso medido el 03-10-2026 y re-medido el 06-10-2026 en `master-pedidos/src/app` (misma exclusión
+> que `sui-card`; las líneas son las del 06-10-2026): **3
+> product-cards en 2 archivos**: la carta del cliente
+> (`pages/customer/restaurant-menu/restaurant-menu.html:323` y `:386`) y la grilla del local
+> (`pages/products/products.html:147`, con `action="edit"`).
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `name`, `price` (obligatorios) | Siempre. El precio sale con 2 decimales y punto: «S/ 35.00». | canon (CANON-SUI §5.5: «S/ » + espacio, punto decimal y 2 decimales; el precio se pasa como número y el componente formatea) |
+| `description` | Una línea que diga qué trae: «Con hierbas aromáticas y papas nativas». | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `image` como objeto `{ url, fallbackUrl, position }` | Lo normal: `url` = la miniatura, `fallbackUrl` = la foto grande por si la miniatura no carga, `position` = encuadre vertical guardado. | canon (aprobado por el dueño, 05-10-2026, bloque B9) (así lo hace la carta) |
+| `image` como string | Solo la url, sin respaldo. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `image = null` + `fallback` | Sin foto: banda de color con el nombre (default). La carta pasa `{ color }` para variar el color por visita con `SUI_PRODUCT_FALLBACK_COLORS`. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `available=false` + `unavailableLabel` | Agotado o fuera de horario; la etiqueta dice cuál («Agotado», «Desde las 12 m.»). Se atenúa y pierde el «+». | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `quantity` | Cuántos hay en el carrito: con más de 0, el «+» pasa a stepper (− / cantidad / +). | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `closed` | El local no recibe pedidos: se ve, no se agrega. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `action="add"` (default) | La carta del cliente. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `action="edit"` | La grilla del dueño: lápiz siempre (también en agotado, que es justo el que quiere tocar), nunca stepper. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `currencySymbol` | Default `S/`. No se cambia: la app cobra en soles. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `fallback.variant="icon"` | Ver «No usar». | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+Outputs: `openDetail` (toque en la card), `add`, `increment`, `decrement`, `edit`.
+
+**Usos de hoy que rompen las reglas:** 3 (medido el 06-10-2026). Las 3 cards pasan
+`size={bp.isMobile() ? 'large' : 'small'}` (`products.html:147`, `restaurant-menu.html:323` y
+`:386`): `small` en la computadora y en la tablet táctil, cuando D16 pide `medium` y `large`. Va
+`bp.sizeControl()` (ver «Por dispositivo (D16)»). **Pendiente de migrar:** el precio tachado y la
+chapa de descuento ya existen en el DS (`precioLista`, ver «Precio con descuento»), pero la carta
+los sigue dibujando afuera (`pages/customer/restaurant-menu/restaurant-menu.scss:426`, deuda
+anotada) y ninguna de las 3 cards pasa `precioLista`.
+
+## Tamaño en mobile y en web
+
+El ancho lo da la grilla y la card llena su celda. El `size` cambia **los botones del pie**
+(«+», lápiz y stepper), en la escala del `sui-button`:
+
+| size | «+» / lápiz | stepper (cada lado) | glyph | fuente |
+|---|---|---|---|---|
+| `small` (default) | 36 × 36 | 34 × 36 | 18 / 16 | lo que había en el DS |
+| `medium` | 40 × 40 | 40 × 40 (pill de 104) | 20 | canon (aprobado por el dueño, 03-10-2026): extensión SUI |
+| `large` | 44 × 44 | 44 × 44 (pill de 112) | 20 | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono. Size nuevo del 04-10-2026 |
+
+En `medium` y `large` el stepper (104 / 112 px) no entra al lado del precio en la grilla de 2
+columnas de mobile: el pie envuelve y el stepper baja a su propia línea, a la derecha. El «+» y el
+lápiz sí siguen al lado del precio.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| grilla de la carta | 2 columnas (`1fr 1fr`, gap 12) | `repeat(auto-fill, minmax(220px, 1fr))` desde 600 px y `minmax(180px, 1fr)` en desktop | lo que hay en la app |
+| botón «+», lápiz, stepper | `large` (44), también en la tablet táctil | `medium` (40) | mobile: canon (dueño, 04-10-2026): piso táctil 44 en el teléfono · tablet y web: D16, dueño 05-10-2026; antes `small` (el default del componente: hay que pasarlo) |
+
+```html
+<sui-product-card size={bp.sizeControl()} … />
+```
+
+`medium` (40) es el de la computadora (D16); la tablet va como el teléfono, porque se toca.
+
+### Por dispositivo (D16)
+
+Fila `product-card` de la tabla D16 (dueño, 05-10-2026). El «+», el lápiz y el stepper se tocan,
+así que van por tipo de puntero además del ancho.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `large` (44) | D16 pide `medium` con área tocable de 44; mientras el DS no estire el área de los `medium`, va `large` (interino). El stepper baja a su propia línea |
+| celular (380–767 px) | `large` (44) | grilla de 2 columnas: el stepper baja a su propia línea |
+| tablet táctil (`pointer: coarse`) | `large` (44) | se toca con el dedo: Apple pide 44 pt también en el iPad |
+| computadora (`pointer: fine`) | `medium` (40) | el default es `small` (36): hay que pasarlo |
+
+Ultrawide (≥ 1920 px): igual que la computadora, `medium`; el espacio extra va a más columnas de
+la grilla, no a botones más grandes.
+
+En master-pedidos: `size={bp.sizeControl()}` — el «+» y el lápiz son la escala del `sui-button`,
+así que va el mismo helper (`large` con `bp.tactil()`, `medium` si no). No uses
+`bp.isMobile() ? 'large' : 'small'`: deja la tablet táctil y la computadora en `small`.
+
+## Precio con descuento
+
+`precioLista` es el precio de referencia. Si es **mayor** que `price`, la card pinta el precio en
+rojo con la chapa del ahorro al lado (`-25%`, calculada: no se pasa) y el de referencia tachado
+debajo. Igual o menor, o `null`, se ignora. Rojo `--sui-red-700` (5.26:1 sobre blanco, AA) y en
+oscuro `--sui-red-400`; no `--sui-state-error-base`, que da 3.66:1. Propuesta, falta aprobación
+del dueño: reemplaza el bloque que la app dibuja afuera en `restaurant-menu.scss` (precio tachado
+por `::after` y chapa por `::before` sobre `.product__price`), que se borra al migrar.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `fallback: { variant: 'icon' }` | la banda con el nombre dice más que un ícono | una carta de códigos (repuestos, ferretería) donde el nombre no ayuda a reconocerlo |
+| `currencySymbol` distinto de `S/` | la app solo cobra en soles | si algún día se cobra en dólares |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `action` | `action` | `"add" \| "edit"` | `'add'` |
+| `available` | `available` | `boolean` | `true` |
+| `closed` | `closed` | `boolean` | `false` |
+| `currencySymbol` | `currency-symbol` | `string` | `'S/'` |
+| `description` | `description` | `string` | `''` |
+| `fallback` | — (solo por propiedad JS) | `SuiProductCardFallback \| null` | `null` |
+| `image` | `image` | `SuiProductCardImage \| null \| string` | `null` |
+| `name` | `name` | `string` | — (requerido) |
+| `precioLista` | `precio-lista` | `null \| number` | `null` |
+| `price` | `price` | `number` | — (requerido) |
+| `quantity` | `quantity` | `number` | `0` |
+| `size` | `size` | `"large" \| "medium" \| "small"` | `'small'` |
+| `unavailableLabel` | `unavailable-label` | `string` | `'Agotado'` |
+
+| evento | `event.detail` |
+|---|---|
+| `add` | `void` |
+| `decrement` | `void` |
+| `edit` | `void` |
+| `increment` | `void` |
+| `openDetail` | `void` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+```ts
+interface SuiProductCardImage { url: string; fallbackUrl?: string; position?: number; }
+interface SuiProductCardFallback { variant?: 'name' | 'icon'; color?: string | null; }
+```
+
+`SUI_PRODUCT_FALLBACK_COLORS` (exportada): los colores `--sui-state-*-base` para la banda.
+
+## Trampas
+
+- **El host lleva `content-visibility: auto`**: las cards fuera de pantalla no se pintan. Al
+  imprimir ya no pasa (el componente lo apaga en `@media print`). En una captura de página
+  completa (shot-scraper `--full`) sí pueden salir en blanco: el opt-out es
+  `sui-product-card { content-visibility: visible; }` desde afuera.
+- **Necesita una celda con alto**: el host es `height: 100%` y la foto usa `NgOptimizedImage`
+  `fill`. En un contenedor sin alto la card colapsa; ponla en una grilla.
+- **La card es un `<div>`, no un `<button>`** (desde 03-10-2026): lo que abre el detalle es
+  `.product__hit`, un botón invisible estirado sobre toda la card con el nombre como
+  `aria-label`; los botones del pie van por encima (`z-index` 2). Así no hay un botón dentro de
+  otro. Un estilo de afuera que apunte a `button.product` ya no engancha.
+- **La app pinta hoy el descuento por fuera** con `::before`/`::after` sobre `.product__price`: si
+  se pasa `precioLista` hay que borrar ese bloque en el mismo cambio, o salen dos tachados.
+- Con `quantity === 1` el «−» pasa a basurero («Quitar del carrito»).
+- El color sin foto es determinista por nombre: el mismo producto siempre sale del mismo color,
+  salvo que pases `fallback.color`.
+- Cada url nueva vuelve a mostrar el barrido de carga; si la miniatura falla, intenta con
+  `fallbackUrl` antes de apagarlo.
+
+## Bien y mal
+
+Tamaño de los botones del pie
+
+```html
+<!-- ❌ mal: small (36) en la computadora y en la tablet táctil (pages/customer/restaurant-menu/restaurant-menu.html:323) -->
+<sui-product-card size={bp.isMobile() ? 'large' : 'small'}
+  name={product.name} price={product.price} onAdd={() => onCardAdd(product)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-product-card size={bp.sizeControl()}
+  name={product.name} price={product.price} onAdd={() => onCardAdd(product)} />
+```
+
+La grilla del dueño del local
+
+```html
+<!-- ❌ mal: sin action="edit" el dueño ve el «+» del cliente, y en agotado ni eso -->
+<sui-product-card size={bp.sizeControl()} name={p.name} price={p.priceNum}
+  available={seVendeAhora(p)} onOpenDetail={() => editProduct(p)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-product-card size={bp.sizeControl()} action="edit" name={p.name} price={p.priceNum}
+  available={seVendeAhora(p)} onOpenDetail={() => editProduct(p)} onEdit={() => editProduct(p)} />
+```
+
+Foto del producto
+
+```html
+<!-- ❌ mal: como string no hay respaldo si la miniatura falla, ni encuadre guardado -->
+<sui-product-card size={bp.sizeControl()} name={p.name} price={p.price}
+  image={p.thumbnailUrl} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-product-card size={bp.sizeControl()} name={p.name} price={p.price}
+  image={p.thumbnailUrl ? { url: p.thumbnailUrl, fallbackUrl: p.imageUrl, position: p.imagePosition ?? 50 } : null} />
+```
+
+## Ejemplo
+
+```html
+<sui-product-card
+  size={bp.sizeControl()}
+  name={p.name}
+  description={p.description ?? ''}
+  price={p.price}
+  image={p.thumbnailUrl ? { url: p.thumbnailUrl, fallbackUrl: p.imageUrl, position: p.imagePosition ?? 50 } : null}
+  available={disponibleAhora(p)}
+  unavailableLabel={etiquetaNoDisponible(p)}
+  quantity={cantidadEnCarrito(p)}
+  closed={noSePuedePedir()}
+  onOpenDetail={() => abrirDetalle(p)}
+  onAdd={() => agregar(p)}
+  onIncrement={() => sumar(p)}
+  onDecrement={() => restar(p)} />
+```