@ajuarezso/sui-design-system 0.18.10 → 0.20.0

package/docs/sui-tag/README.md

@@ -0,0 +1,145 @@
+---
+name: sui-tag
+selector: sui-tag
+resumen: Chip neutro que nombra algo elegido o aplicado y que la persona puede quitar
+alternativas: [sui-badge (etiqueta de solo lectura, con color y significado), sui-status-badge (resultado de un ciclo), sui-tab-chips / sui-filter (chips para elegir), sui-tag-input (campo que junta tags)]
+---
+
+# sui-tag
+
+Story: [Atoms/Tag](https://sui-design-system.web.app/?path=/docs/atoms-tag--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para nombrar algo que la persona **eligió o aplicó y puede quitar**: un filtro activo
+(«Abierto ahora ✕»), un local o una persona elegidos en una lista, una zona agregada. También
+cuando la etiqueta lleva **avatar, logo o bandera** a la izquierda.
+
+El tag **no tiene color**: es siempre gris neutro, así que nunca dice un estado.
+
+**No lo uses** para:
+
+- Una etiqueta de solo lectura sin nada a la izquierda: `sui-badge` gray (más liviano, va al lado
+  de un nombre).
+- Algo con significado de color (pendiente, error, nuevo): `sui-badge` o `sui-status-badge`.
+- **Elegir** entre opciones (chips que se prenden y apagan): `sui-tab-chips`, `sui-filter` o
+  `sui-segmented-control`. El tag no tiene estado «seleccionado».
+- Escribir varios valores en un campo: `sui-tag-input`.
+
+Regla corta: **se quita o lleva avatar/logo/bandera → tag · solo se lee → badge · se elige →
+tab-chips o filter.**
+
+## Qué variante usar
+
+> **La guía del DS dice para qué es, no cuándo usar cada estilo.** Su página lo define como
+> «categorizar y etiquetar contenido» y muestra `stroke` (default), `gray`, deshabilitado, con
+> imagen, con avatar y con botón de quitar. No trae do/don't. Lo marcado «según la guía del DS»
+> sale de ahí; el resto es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 tags**, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `_guia-*`,
+> `master-rutina`, `master-medico`, `master-ejercicios`, `dev-index`). Tampoco hay chips hechos a
+> mano con botón de quitar: los chips de la app son para elegir (`rate-order`,
+> `product-detail-view`, `driver-schedule`), y eso no es un tag.
+
+| propiedad | valor | cuándo | ejemplo | fuente |
+|---|---|---|---|---|
+| `tagStyle` | `stroke` (default) | Lo normal. Sirve sobre cualquier fondo (blanco o gris claro). | — | según la guía del DS (default) |
+| `tagStyle` | `gray` | Solo sobre blanco, cuando hay muchos tags juntos y el borde hace ruido. **Sobre gris claro desaparece.** | Varios filtros aplicados en fila | propuesta, falta aprobación |
+| `dismissible` | `true` | Lo que se nombra se puede quitar. Emite `(dismiss)`; la pantalla lo saca. | «Abierto ahora ✕» | según la guía del DS |
+| `dismissLabel` | texto | Siempre «Quitar» + el nombre: el lector de pantalla no ve el texto del tag desde la X. | `dismissLabel="Quitar Abierto ahora"` | propuesta, falta aprobación |
+| `leading` + `[data-slot=start]` | avatar | Nombra a una persona o un local. | «Burger House» con su logo | según la guía del DS (con avatar, con imagen) |
+| `leading` + `[data-slot=start]` | ícono de 16 | El ícono dice qué tipo de dato es. | «Andahuaylas» con un pin | según la guía del DS (`Tag.Icon`) |
+| `sublabel` | texto | Cuántos resultados trae ese filtro, entre paréntesis. | «Pollerías (12)» | propuesta, falta aprobación |
+| `disabled` | `true` | **No usar** hoy (ver abajo). | — | según la guía del DS (existe) · propuesta (cuándo) |
+| `interactive` | `true` | **No usar** hoy (ver abajo). | — | propuesta, falta aprobación |
+
+Usos de hoy que rompen la regla: **0** (no hay usos).
+
+## 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) | No hay filtros aplicados que se quiten ni listas de elegidos con avatar. | Filtros aplicados en las tablas del super admin; los locales elegidos para una campaña; las zonas que cubre un repartidor. |
+| `disabled` | No hay filtros fijos. | Un filtro que el sistema pone y la persona no puede quitar («Tu distrito»). |
+| `interactive` | Un tag tocable se confunde con un chip para elegir. | Un tag que abre la ficha de lo que nombra (el local de una lista de locales vinculados). |
+
+## Tamaño en mobile y en web
+
+Criterio de la app: **en mobile se lee y se toca con el dedo, así que va más grande; en web
+(desktop), más chico.** Mobile es `≤ 767 px`, el mismo corte de `BreakpointsService.isMobile()`
+en master-pedidos. Fuente: canon del dueño (03-10-2026), el mismo patrón que ya usan 27 controles
+de la app.
+
+| size | alto | texto | leading | X de quitar (área táctil) |
+|---|---|---|---|---|
+| `medium` (default) | 24 px | `label-xs` 12/16 | 16 | 16 (16) |
+| `large` | 32 px | `label-sm` 14/20 | 20 | 20 (32) |
+| `xlarge` | 40 px | `label-md` 16/24 | 20 | 24 (40) |
+
+`medium` es el de Figma; `large` y `xlarge` son extensión SUI (03-10-2026), en la escala del
+`sui-button` (32 · 40). En los dos grandes la X tiene un área táctil invisible que llega al alto
+del tag, sin cambiar cómo se ve.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Tag con X (filtro aplicado, elegido que se quita) | `xlarge` (40) | `medium` (24) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+| Tag de solo lectura (sin X) | `large` (32) | `medium` (24) | propuesta: el tamaño es extensión SUI aprobada (03-10-2026); el «cuándo» falta aprobarlo |
+| Separación entre tags | 8 px | 4–6 px | propuesta, falta aprobación |
+
+```html
+<sui-tag [size]="bp.isMobile() ? 'xlarge' : 'medium'" [dismissible]="true" (dismiss)="quitar(f)">{{ f.nombre }}</sui-tag>
+```
+
+El leading proyectado (ícono, avatar, bandera) se escala solo a la caja de 20 en los grandes; un
+`<i class="ri-…">` necesita además su `font-size` en 20.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `tagStyle` | `'stroke' \| 'gray'` | `'stroke'` |
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `leading` | `boolean` | `false` |
+| `sublabel` | `string` | `''` |
+| `dismissible` | `boolean` | `false` |
+| `interactive` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `dismissLabel` | `string` | `'Quitar'` |
+
+| output | payload |
+|---|---|
+| `dismiss` | `void` |
+<!-- api:fin -->
+
+Slots: `[data-slot=start]` (avatar, logo, bandera o ícono de 16 px) y `<ng-content>` (el texto).
+
+## Trampas
+
+- **`leading` no se prende solo**: si proyectas algo en `[data-slot=start]` y no pones
+  `[leading]="true"`, el padding queda mal.
+- El estilo se llama **`tagStyle`** (en badge es `variant`, en status-badge `appearance`).
+- **No tiene `color`**. Si hace falta color, no es un tag.
+- El tag no saca nada de la lista: `(dismiss)` avisa y la pantalla lo quita.
+- `disabled` bloquea también la X.
+- Un avatar o una bandera proyectados no se ponen grises con `disabled`: los atenúa la pantalla.
+- `sui-avatar` no tiene 16 px: el `xs` (20) se escala por CSS dentro del slot.
+- Radio de 6 px, 24 px de alto, sin mayúsculas: no es un badge (radio completo).
+
+## Ejemplo
+
+```html
+<!-- Filtro aplicado que se puede quitar -->
+<sui-tag [dismissible]="true" dismissLabel="Quitar Abierto ahora" (dismiss)="quitarFiltro('abierto')">
+  Abierto ahora
+</sui-tag>
+
+<!-- Un local elegido, con su logo -->
+<sui-tag [leading]="true" [dismissible]="true" dismissLabel="Quitar Burger House">
+  <sui-avatar data-slot="start" size="xs" [src]="local.imageUrl" [initials]="'B'" />
+  Burger House
+</sui-tag>
+```