@ajuarezso/sui-design-system 0.20.0 → 0.21.0

package/docs/sui-password-strength/README.md

@@ -0,0 +1,99 @@
+---
+name: sui-password-strength
+selector: sui-password-strength
+resumen: Barra de 3 niveles y lista de condiciones que acompaña al campo de una contraseña nueva
+alternativas: [sui-input con hint (una sola regla, como «Mínimo 6 caracteres»)]
+---
+
+# sui-password-strength
+
+Story: [Molecules/Input/Password Strength](https://sui-design-system.web.app/?path=/docs/molecules-input-password-strength--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** debajo del campo de una **contraseña nueva** cuando hay **dos o más reglas** que cumplir:
+la barra se llena (rojo, naranja, verde) y cada condición se marca a medida que se escribe.
+
+**No lo uses** para:
+
+- El login: la contraseña ya existe, no se evalúa.
+- Una sola regla («Mínimo 6 caracteres»): alcanza el `hint` del `sui-input`, como hoy en
+  `pages/auth/register/register.html:121`.
+
+Regla corta: **contraseña nueva con 2+ reglas → este · una regla → hint.**
+
+## Qué variante usar
+
+> **En la guía del DS es un ejemplo de su página del input** («Password With Levels»: campo, barra
+> de niveles y «Debe contener al menos» con tres condiciones). No dice cuándo usarlo.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. El registro pide solo 6
+> caracteres (lo que exige Firebase).
+
+| prop / evento | cuándo | fuente |
+|---|---|---|
+| `value` | La contraseña que se está escribiendo. | API |
+| `conditions` | **Las reglas reales de la app.** Los defaults (mayúscula, número, 8 caracteres) no son las de Master Pedidos. `[]` deja solo la barra. | según la guía del DS (condiciones bajo la barra); qué reglas, propuesta |
+| `caption` | «Debe contener al menos:» (default). `''` lo oculta. | según la guía del DS |
+| `strength` | Forzar el nivel cuando lo calcula el servidor. Hoy sin caso. | API |
+| `levelLabels` · `ariaLabel` | Lo que lee el lector de pantalla. Los defaults en español sirven. | API |
+| `(strengthChange)` | Apagar «Crear cuenta» hasta llegar a `strong`. | propuesta, falta aprobación |
+
+## Tamaño en mobile y en web
+
+No se toca: es texto (12 px) y una barra de 4 px a todo el ancho. **No necesita `bp`.**
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| el componente entero (0 usos) | el registro pide una sola regla (6 caracteres) | si las cuentas con dinero (local, super admin) pasan a exigir contraseña más fuerte |
+| `strength` forzado | nadie calcula el nivel afuera | si el servidor rechaza contraseñas filtradas y devuelve el nivel |
+| condiciones default | no son las reglas de la app | — (siempre pasar las propias) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` | `string` | `''` |
+| `strength` | `'empty' \| 'weak' \| 'moderate' \| 'strong' \| null` | `null` |
+| `caption` | `string` | `'Debe contener al menos:'` |
+| `conditions` | `SuiPasswordStrengthCondition[]` | `SUI_PASSWORD_STRENGTH_DEFAULT_CONDITIONS` |
+| `levelLabels` | `Partial<Record<SuiPasswordStrengthLevel, string>>` | `{}` |
+| `ariaLabel` | `string` | `'Seguridad de la contraseña'` |
+
+| output | payload |
+|---|---|
+| `strengthChange` | `'empty' \| 'weak' \| 'moderate' \| 'strong'` |
+<!-- api:fin -->
+
+Exporta `SUI_PASSWORD_STRENGTH_DEFAULT_CONDITIONS` y `SUI_PASSWORD_STRENGTH_DEFAULT_LEVEL_LABELS`.
+
+```ts
+interface SuiPasswordStrengthCondition {
+  label: string;
+  test?: RegExp | ((value: string) => boolean);
+  met?: boolean;   // si está, gana sobre test
+}
+```
+
+## Trampas
+
+- **Las condiciones default piden 8 caracteres, una mayúscula y un número**: más que lo que pide la
+  app (6). Sin `[conditions]` propias, la barra marca «débil» contraseñas que el registro acepta.
+- Los segmentos tienen color fijo (1 rojo, 2 naranja, 3 verde): en «fuerte» la barra es de tres
+  colores, no toda verde.
+- `strengthChange` no emite el nivel inicial.
+- No incluye el campo: va debajo de un `sui-input type="password-toggle"`.
+
+## Ejemplo
+
+```html
+<sui-input label="Contraseña" type="password-toggle" autocomplete="new-password" [(value)]="clave" />
+<sui-password-strength [value]="clave()" [conditions]="reglas" />
+<!-- reglas = [{ label: 'Al menos 8 caracteres', test: v => v.length >= 8 },
+               { label: 'Al menos 1 número', test: /\d/ }] -->
+```

package/docs/sui-period-range/README.md

@@ -0,0 +1,93 @@
+---
+name: sui-period-range
+selector: sui-period-range
+resumen: Un período predefinido (Hoy, Últimos 7 días) en la columna de presets del calendario de rango
+alternativas: [sui-datepicker mode="range" (ya los trae), sui-tab-chips (períodos fijos a la vista: super admin, ganancias del repartidor), sui-select (períodos fijos en poco espacio: resumen del local)]
+---
+
+# sui-period-range
+
+Story: [Molecules/Date & Time/Period Range](https://sui-design-system.web.app/?path=/docs/molecules-date-time-period-range--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** solo dentro de un **selector de rango** armado a mano, como la columna de atajos al
+costado del calendario.
+
+**No lo uses** para:
+
+- El rango normal: `sui-datepicker mode="range"` ya pinta los presets con este componente y los
+  cambia por `[presets]`.
+- **Cambiar de período en un resumen** («Hoy · 7 días · 30 días»): `sui-tab-chips`, como hoy en
+  el super admin (`master-overview.html:13`) y en las ganancias del repartidor; o `sui-select`,
+  como el resumen del local (`overview.html:46`).
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente** (vive dentro del datepicker). Todo es
+> **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. Lo usa por dentro
+> `sui-datepicker`.
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `label` | texto | El período en palabras de la persona: «Hoy», «Últimos 7 días», «Este mes». Sin fechas: para eso está el calendario al lado. | propuesta |
+| `active` | `true` | El preset que coincide con el rango elegido. Uno solo; si el rango se tocó a mano, ninguno. | propuesta |
+| `disabled` | `true` | El período no tiene datos (un local que abrió hace 10 días con «Últimos 3 meses»). Mejor sacarlo de la lista si nunca va a tener datos. | propuesta |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+**No tiene `size`.** Mide 168 × 36: en mobile **no llega** a los 44 px. En el datepicker, en
+mobile, los presets pasan a una fila que se desplaza de costado.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| preset de un rango | 36 px de alto — **no llega** | 168 × 36 | medido |
+
+```html
+<!-- Web: columna de presets -->
+<sui-period-range label="Últimos 7 días" [active]="preset() === '7d'" (clicked)="aplicar('7d')" />
+```
+
+**Sin tamaño suficiente para mobile.** En el celular, los períodos fijos van en `sui-tab-chips`,
+como ya hacen el super admin y las ganancias del repartidor.
+
+## «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 suelto (0 usos) | los períodos de la app son fijos y van en tab-chips o select | una columna de atajos al lado de un calendario propio, en web |
+| `disabled` | ningún período queda sin datos hoy | presets de un local nuevo («Últimos 12 meses» con 2 semanas de vida) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | — (requerido) |
+| `active` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `void` |
+<!-- api:fin -->
+
+## Trampas
+
+- **No calcula fechas**: solo emite `clicked`. El rango lo resuelve quien lo usa (en el datepicker,
+  `DatepickerPreset.resolve`).
+- Ancho fijo de 168 px.
+- `active` no se apaga solo: lo maneja quien lo usa.
+
+## Ejemplo
+
+```html
+<sui-period-range label="Hoy" [active]="true" />
+<sui-period-range label="Últimos 30 días" (clicked)="aplicar('30d')" />
+```

package/docs/sui-popover/README.md

@@ -0,0 +1,178 @@
+---
+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
+
+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`: **0 usos**, 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». | propuesta |
+| `doubleButton` | `false` | El primer paso de un recorrido o un aviso suelto con una sola salida («Entendido»). | propuesta |
+| `backLabel` · `nextLabel` | texto en español | Los defaults ya son «Atrás» y «Siguiente» (03-10-2026); el último paso pasa `nextLabel="Listo"`. | canon (copy de la app: tuteo, sentence case) |
+| orden | secundario a la izquierda, primario a la derecha | Ya lo hace el componente (stroke neutral + filled primary), igual que `sui-modal-footer`. | canon (orden de botones de la app) |
+| `step` | `{ current, total }` | Con `stepper`. Sin `step`, el componente asume **1 de 4**. | propuesta |
+
+### 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. | propuesta |
+| `icon` | `null` | Cuando el texto ya basta y el ícono sería decoración. | propuesta |
+| `title` | frase corta | Qué es, en sentence case y sin punto final. | canon (copy de la app) |
+| `description` | una o dos frases | Qué hace o por qué importa. | propuesta |
+| `dismissIcon` | `true` (default) | Siempre: un recorrido se puede saltar. | propuesta |
+| `dismissIcon` | `false` | No usar hoy. **Cuándo sí:** un paso que no se puede saltar porque sin él no funciona lo siguiente. | propuesta |
+| `[data-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. | propuesta |
+
+## 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 |
+
+La X se ve de 24 y **se toca en 40 × 40** en los dos (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 | `medium` (40) | `small` (36) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+| 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.isMobile() ? 'medium' : 'small'" … />
+```
+
+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).
+
+## «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 |
+| `[data-slot=body]` | título y texto alcanzan | un paso con imagen o lista |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `position` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right' \| 'right-top' \| 'right-center' \| 'right-bottom' \| 'left-top' \| 'left-center' \| 'left-bottom'` | `'top-left'` |
+| `tail` | `boolean` | `true` |
+| `icon` | `string \| null` | `'user-6-line'` |
+| `title` | `string` | `''` |
+| `description` | `string \| null` | `null` |
+| `dismissIcon` | `boolean` | `true` |
+| `footer` | `'none' \| 'stretch' \| 'text-stepper' \| 'stepper'` | `'stretch'` |
+| `backLabel` | `string` | `'Atrás'` |
+| `nextLabel` | `string` | `'Siguiente'` |
+| `doubleButton` | `boolean` | `true` |
+| `step` | `{ current: number; total: number } \| null` | `null` |
+| `size` | `'small' \| 'medium'` | `'small'` |
+
+| output | payload |
+|---|---|
+| `dismissed` | `void` |
+| `back` | `void` |
+| `next` | `void` |
+<!-- api:fin -->
+
+Slot: `[data-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.
+- **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`.
+
+## 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 }"
+  backLabel="Atrás" nextLabel="Siguiente"
+  (back)="anterior()" (next)="siguiente()" (dismissed)="saltar()" />
+
+<!-- Aviso suelto con una sola salida -->
+<sui-popover position="bottom-center" icon="wallet-3-line" title="Aquí ves lo que ganaste hoy"
+  [doubleButton]="false" nextLabel="Entendido" (next)="cerrar()" (dismissed)="cerrar()" />
+```

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

@@ -0,0 +1,173 @@
+---
+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
+
+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 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **3
+> product-cards en 2 archivos**: la carta del cliente
+> (`pages/customer/restaurant-menu/restaurant-menu.html:324` y `:387`) y la grilla del local
+> (`pages/products/products.html:145`, con `action="edit"`).
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `name`, `price` (obligatorios) | Siempre. El precio sale con 2 decimales y punto: «S/ 35.00». | propuesta |
+| `description` | Una línea que diga qué trae: «Con hierbas aromáticas y papas nativas». | propuesta |
+| `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. | propuesta (así lo hace la carta) |
+| `image` como string | Solo la url, sin respaldo. | propuesta |
+| `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`. | propuesta |
+| `available=false` + `unavailableLabel` | Agotado o fuera de horario; la etiqueta dice cuál («Agotado», «Desde las 12 m.»). Se atenúa y pierde el «+». | propuesta |
+| `quantity` | Cuántos hay en el carrito: con más de 0, el «+» pasa a stepper (− / cantidad / +). | propuesta |
+| `closed` | El local no recibe pedidos: se ve, no se agrega. | propuesta |
+| `action="add"` (default) | La carta del cliente. | propuesta |
+| `action="edit"` | La grilla del dueño: lápiz siempre (también en agotado, que es justo el que quiere tocar), nunca stepper. | propuesta |
+| `currencySymbol` | Default `S/`. No se cambia: la app cobra en soles. | propuesta |
+| `fallback.variant="icon"` | Ver «No usar». | propuesta |
+
+Outputs: `openDetail` (toque en la card), `add`, `increment`, `decrement`, `edit`.
+
+**Usos de hoy que rompen las reglas:** 0. **Falta en el DS:** el precio tachado y la chapa de
+descuento. La carta los dibuja afuera (`pages/customer/restaurant-menu/restaurant-menu.scss:426`,
+deuda anotada): cuando se pueda publicar, va un input `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 |
+
+En `medium` el stepper (104 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 | `medium` (40) | `small` (36) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+
+```html
+<sui-product-card [size]="bp.isMobile() ? 'medium' : '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` -->
+
+| input | tipo | default |
+|---|---|---|
+| `name` | `string` | — (requerido) |
+| `description` | `string` | `''` |
+| `price` | `number` | — (requerido) |
+| `image` | `SuiProductCardImage \| string \| null` | `null` |
+| `available` | `boolean` | `true` |
+| `quantity` | `number` | `0` |
+| `closed` | `boolean` | `false` |
+| `currencySymbol` | `string` | `'S/'` |
+| `fallback` | `SuiProductCardFallback \| null` | `null` |
+| `unavailableLabel` | `string` | `'Agotado'` |
+| `action` | `'add' \| 'edit'` | `'add'` |
+| `precioLista` | `number \| null` | `null` |
+| `size` | `'small' \| 'medium'` | `'small'` |
+
+| output | payload |
+|---|---|
+| `openDetail` | `void` |
+| `add` | `void` |
+| `increment` | `void` |
+| `decrement` | `void` |
+| `edit` | `void` |
+<!-- 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.
+
+## Ejemplo
+
+```html
+<sui-product-card
+  [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()"
+  (openDetail)="abrirDetalle(p)"
+  (add)="agregar(p)"
+  (increment)="sumar(p)"
+  (decrement)="restar(p)" />
+```