@ajuarezso/sui-design-system 0.19.0 → 0.21.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>
+```

package/docs/sui-tag-input/README.md

@@ -0,0 +1,120 @@
+---
+name: sui-tag-input
+selector: sui-tag-input
+resumen: Campo donde se escriben varios valores cortos que se van sumando como chips (palabras clave)
+alternativas: [sui-input (un solo valor), sui-select (una opción de una lista), sui-checkbox-label (varias opciones fijas)]
+---
+
+# sui-tag-input
+
+Story: [Molecules/Input/Tag Input](https://sui-design-system.web.app/?path=/docs/molecules-input-tag-input--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para una lista de valores **libres y cortos** que la persona escribe uno por uno: palabras
+clave, rubros, sinónimos. Enter (y la coma, si se pide) convierte lo escrito en un chip; la ✕ de
+cada chip lo quita; borrar con el campo vacío quita el último.
+
+**No lo uses** para:
+
+- Elegir varias opciones que ya existen: casillas (`sui-checkbox-label`).
+- Un solo valor: `sui-input`.
+- Una lista que se guarda como texto separado por comas y nadie ve como lista.
+
+Regla corta: **varios valores libres → tag-input · varias opciones fijas → casillas.**
+
+## Qué variante usar
+
+> **En la guía del DS es un ejemplo de su página del input** («With Tags»: un campo con los chips
+> Berlin, London, Paris debajo). No dice cuándo usarlo.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. Candidato: «Rubros que entran»
+> en `pages/super-admin/master-settings/master-settings.html:134`, un `sui-input` donde se escriben
+> palabras separadas por coma («ferreteria, ferretería, construcción») y la pantalla las parte a mano.
+
+| prop / evento | cuándo | fuente |
+|---|---|---|
+| `label` · `required` · `sublabel` · `tooltip` · `hint` | Igual que `sui-input`. El hint dice cómo se agrega: «Escribe y presiona Enter». | según la guía del DS (ejemplo con label «Tag Input») |
+| `placeholder` | **Siempre**: el default es «Add tags...». «Agrega una palabra…». | propuesta, falta aprobación |
+| `commaSeparator` | `true` cuando la gente ya escribe con comas (rubros, sinónimos). | propuesta, falta aprobación |
+| `addOnBlur` | `true` en mobile: si sale del campo sin Enter, lo escrito no se pierde. | propuesta, falta aprobación |
+| `maxTags` | Cuando hay un tope real. Hoy no hay. | propuesta, falta aprobación |
+| `allowDuplicates` | `false` (default). | propuesta, falta aprobación |
+| `rightIcon` | No usar hoy (ícono de info a la derecha). | — |
+| `error` + `errorMessage` | Falta al menos un valor en un campo obligatorio. | según la guía del DS (estado de error del Figma) |
+| `disabled` | Mientras se guarda. | API |
+| `(tagAdded)` · `(tagRemoved)` | Guardar al momento, sin botón. | API |
+
+## Tamaño en mobile y en web
+
+Publicado (0.19.0): `xsmall` (32), `small` (36), `medium` (40). **En el repo del DS, sin publicar:**
+`large` (48) y `xlarge` (52), los mismos altos de `sui-input`, y el texto a 16 px en mobile (en
+0.19.0 queda en 14). Los chips de abajo son `sui-tag` de tamaño fijo: **la ✕ para quitar un chip
+no crece** con el campo.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| campo de formulario | `large` (48) **cuando se publique**; hasta entonces `medium` (40) | `medium` (40) | propuesta, falta aprobación |
+
+```html
+<sui-tag-input [size]="bp.isMobile() ? 'large' : 'medium'" … />   <!-- 'large' desde la próxima versión -->
+```
+
+## «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) | nadie carga listas de palabras | «Rubros que entran» de una categoría del home (`master-settings.html:134`), o sinónimos de un producto para el buscador |
+| `rightIcon` | el hint explica mejor | — |
+| `maxTags` | no hay topes | un máximo de 5 palabras clave por producto |
+| `allowDuplicates` | repetir no sirve | — |
+| `size` `xsmall` / `small` | no hay tag-inputs en tablas | un filtro denso del panel |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `placeholder` | `string` | `'Add tags...'` |
+| `disabled` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `errorMessage` | `string \| null` | `null` |
+| `rightIcon` | `string \| boolean` | `false` |
+| `label` | `string \| null` | `null` |
+| `sublabel` | `string \| null` | `null` |
+| `required` | `boolean` | `false` |
+| `tooltip` | `string \| null` | `null` |
+| `hint` | `string \| null` | `null` |
+| `commaSeparator` | `boolean` | `false` |
+| `allowDuplicates` | `boolean` | `false` |
+| `maxTags` | `number \| null` | `null` |
+| `addOnBlur` | `boolean` | `false` |
+| `value` · model, `[(value)]` | `string[]` | `[]` |
+
+| output | payload |
+|---|---|
+| `tagAdded` | `string` |
+| `tagRemoved` | `string` |
+<!-- api:fin -->
+
+`value` es `model<string[]>`. Implementa `ControlValueAccessor`: lo que está escrito sin confirmar
+no es parte del valor. Slot `[slot=right]` para un contenido propio a la derecha.
+
+## Trampas
+
+- **Placeholder en inglés por default** («Add tags...»). Pásalo siempre.
+- Sin `commaSeparator` la coma es un carácter más: «a, b» queda como un solo chip.
+- Sin `addOnBlur`, lo que se escribió y no se confirmó con Enter se pierde al salir.
+- Los chips van **debajo** del campo, no adentro.
+- El hover quita el borde (a diferencia de `sui-input`, que lo oscurece).
+
+## Ejemplo
+
+```html
+<sui-tag-input label="Rubros que entran" placeholder="Agrega una palabra…"
+               hint="Un local entra si su rubro contiene alguna" [commaSeparator]="true"
+               [addOnBlur]="true" [(value)]="rubros" />
+```

package/docs/sui-textarea/README.md

@@ -0,0 +1,157 @@
+---
+name: sui-textarea
+selector: sui-textarea
+resumen: Campo de varias líneas para un texto libre (motivo, nota al repartidor, descripción)
+alternativas: [sui-input (un dato de una línea), sui-rich-editor (texto con formato, hoy sin uso), sui-select (motivos que se pueden elegir de una lista)]
+---
+
+# sui-textarea
+
+Story: [Molecules/Input/Textarea](https://sui-design-system.web.app/?path=/docs/molecules-input-textarea--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para un texto que la persona redacta y que puede ocupar más de una línea: el motivo de
+un rechazo o una cancelación, la nota para el repartidor, la descripción de un producto, un
+comentario al calificar.
+
+**No lo uses** para:
+
+- Un dato de una línea (nombre, referencia corta, URL, un slug): `sui-input`. Hoy hay uno así:
+  «Personaliza tu url» en `pages/mi-negocio/mi-negocio.html:706`.
+- Un motivo que se puede elegir de una lista cerrada: radios o `sui-select`, y la opción «Otro»
+  abre el textarea (como ya hace `pages/envios/envios.html:819`, que además corta a 200 a mano con
+  `.slice(0, 200)` en vez de `[maxLength]="200"`).
+- Texto con negritas o enlaces: no hay caso hoy (ver `sui-rich-editor`).
+- Un `<textarea>` nativo: queda **1** (`pages/products/add-product/add-product.html:155`).
+
+Regla corta: **se redacta y puede pasar de una línea → textarea · una línea → input · se elige → select.**
+
+## Qué variante usar
+
+> **La guía del DS lo presenta con contador de caracteres y su propia manija para agrandarlo**
+> («78/200»), y aparte una versión simple sin contador. No dice cuándo va cada una.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`, más
+> `master-ejercicios`): **50 usos en 29 archivos**. `rows`: 32 en 3, 13 en 2, 4 en 4, 1 en 8.
+> Con `maxLength`: 8. Con `resizable=false`: 2. 38 con label, 12 sin.
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre, salvo cuando la pregunta ya está escrita justo encima (la calificación: «¿Qué te gustó?»). | según la guía del DS (ejemplo con label) |
+| `required` | Motivo obligatorio (rechazar, anular). | según la guía del DS (`Enter Your Message*`) |
+| `sublabel` | **«(Opcional)»**, con paréntesis, cuando no es obligatorio, en vez de «(opcional)» dentro del label. Sin paréntesis queda pegado al label. | según la guía del DS (`(Optional)`) y canon (README de `sui-form-label`) |
+| `tooltip` | Hoy sin caso. | según la guía del DS (ícono de info del label) |
+| `hint` | Para quién es el texto: «Lo va a leer el cliente», «Solo lo ve tu equipo». | según la guía del DS (ejemplo con hint) |
+| `error` + `errorMessage` | Motivo obligatorio vacío. El mensaje reemplaza al hint y el contador se pone rojo. | según la guía del DS (`Has Error`) |
+| `placeholder` | Un ejemplo de lo que se espera: «Ej. frágil, tocar el timbre, entregar en recepción». Elipsis `…`. | canon (CANON-SUI §5.2) |
+| `maxLength` | **Siempre que otro lo va a leer** (cliente, repartidor, local) o se guarda en la base: muestra «n/200» y corta el exceso. 200 para motivos y notas; 500 para descripciones. | según la guía del DS (su ejemplo principal lleva contador); los topes son propuesta |
+| `size` | El mismo de los inputs del formulario: `large` en mobile, `medium` en web. Ver «Tamaño en mobile y en web». | canon (aprobado por el dueño, 03-10-2026), extensión SUI; el «cuándo» es propuesta, falta aprobación |
+| `rows` | `3` por defecto (motivos, notas). `2` para una nota corta en un formulario largo. `4` o más solo para una descripción larga. | propuesta, falta aprobación |
+| `resizable` | `true` en web. En mobile **`false`**: la manija no se puede arrastrar con el dedo y parece un adorno. | según la guía del DS (versión con y sin manija); el «cuándo» es propuesta |
+| `readonly` | Mostrar un texto ya enviado con la misma forma del campo (copiar un mensaje). | propuesta, falta aprobación |
+| `disabled` | Mientras se envía. | según la guía del DS |
+| `autocomplete` | No hace falta: ningún texto libre se autocompleta. | propuesta, falta aprobación |
+
+**Usos de hoy que rompen la regla:**
+
+- **3 `sublabel="Opcional"` sin paréntesis** (se lee «Notas adicionalesOpcional») → «(Opcional)»:
+  `pages/customer/checkout/checkout.html:209`, `pages/self-delivery/self-delivery.html:101`,
+  `components/add-product-modal/add-product-modal.html:184`.
+- **9 «(opcional)» dentro del label** → `sublabel="(Opcional)"`: `pages/super-admin/super-admin.html:333`
+  («Notas (opcional)»), `pages/super-admin/master-orders/master-orders.html:795`,
+  `components/cuenta-bloqueada/cuenta-bloqueada.html:21`.
+- **Textos que lee otra persona sin `maxLength`** (42 de 50 no lo tienen). Los que más importan:
+  `pages/envios/envios.html:419` («Nota para el repartidor»), `pages/customer/checkout/checkout.html:209`
+  («Notas adicionales»), `pages/super-admin/master-users/master-users.html:266` («Motivo (lo va a leer)»).
+- **4 placeholders con `...`**: `pages/customer/checkout/checkout.html:209`,
+  `pages/self-delivery/self-delivery.html:101`, `pages/driver/driver-order-detail/driver-order-detail.html:823`.
+
+## Tamaño en mobile y en web
+
+Tiene `size` con **los mismos nombres que `sui-input`** (`xsmall` · `small` · `medium` · `large` ·
+`xlarge`): cambia el padding y el radio, y el texto arranca en la misma línea vertical que el del
+input del mismo tamaño. El alto lo siguen poniendo las `rows`. `medium` es el de la guía del DS y el
+default (padding 10/12, radio 12); el resto es extensión SUI.
+
+| size | padding (arriba/der · izq) | radio | fuente |
+|---|---|---|---|
+| `xlarge` | 14 · 16 | 12 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `large` | 12 · 14 | 12 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `medium` (default) | 10 · 12 | 12 | según la guía del DS |
+| `small` | 8 · 10 | 10 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `xsmall` | 6 · 8 | 8 | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+**En mobile (≤ 767 px) la letra sube sola a 16/24** (Paragraph/Medium), como el input sube a 16:
+evita el zoom de iOS al enfocar y el textarea deja de verse más chico que los campos de arriba. Por
+eso cada fila mide 24 px en el teléfono y 20 en web (3 filas ≈ 72 + padding en mobile, 60 + padding
+en web): el área que se toca siempre pasa los 44 px.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| motivo, nota | el `size` del formulario (`large` si los inputs van en `large`), `rows=3`, `[resizable]="false"` | `medium`, `rows=3`, manija | propuesta, falta aprobación |
+| descripción larga | igual, `rows=4` | `medium`, `rows=4` | propuesta, falta aprobación |
+
+```html
+<sui-textarea [size]="bp.isMobile() ? 'large' : 'medium'" [rows]="3"
+              [resizable]="!bp.isMobile()" … />   <!-- bp = BreakpointsService -->
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `tooltip` | el hint alcanza | un campo del panel con una regla que no entra en una línea («qué puede ver el cliente») |
+| `rows` 6 o más | ningún texto de la app es tan largo | términos y condiciones propios de un local, o la descripción larga de una campaña |
+| `autocomplete` | un texto libre no se autocompleta | — |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `rows` | `number` | `4` |
+| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `placeholder` | `string` | `''` |
+| `disabled` | `boolean` | `false` |
+| `readonly` | `boolean` | `false` |
+| `error` | `boolean` | `false` |
+| `errorMessage` | `string \| null` | `null` |
+| `label` | `string \| null` | `null` |
+| `hint` | `string \| null` | `null` |
+| `autocomplete` | `string \| null` | `null` |
+| `resizable` | `boolean` | `true` |
+| `maxLength` | `number \| null` | `null` |
+| `sublabel` | `string \| null` | `null` |
+| `required` | `boolean` | `false` |
+| `tooltip` | `string \| null` | `null` |
+| `value` · model, `[(value)]` | `string` | `''` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+`value` es `model<string>`. Implementa `ControlValueAccessor` (`formControlName`, `[(ngModel)]`).
+
+## Trampas
+
+- **`maxLength` con L mayúscula** (en `sui-input` es `maxlength`). Con el nombre equivocado Angular
+  no avisa en un atributo plano y el tope no se aplica.
+- Sin `maxLength` **no hay contador**; la manija sale igual mientras `resizable` sea `true`.
+- El tope también corta lo que se pega (no solo lo que se tipea).
+- El hint lleva siempre el ícono `information-fill`, también el neutro (así está en el Figma).
+- El `size` no cambia el alto: eso lo deciden las `rows`. Lo que alinea con el input es el padding.
+- `error` sin `errorMessage` pinta el borde y no dice qué falta.
+
+## Ejemplo
+
+```html
+<sui-textarea label="Nota para el repartidor" sublabel="(Opcional)" [rows]="3" [maxLength]="200"
+              [size]="bp.isMobile() ? 'large' : 'medium'" placeholder="Ej. frágil, tocar el timbre, entregar en recepción"
+              [resizable]="!bp.isMobile()" [(value)]="nota" />
+
+<sui-textarea label="Motivo del rechazo" [required]="true" [rows]="3" [maxLength]="200"
+              hint="Lo va a leer el local" [error]="intentado() && !motivo()"
+              errorMessage="Escribe el motivo" [(value)]="motivo" />
+```

package/docs/sui-time-picker/README.md

@@ -0,0 +1,237 @@
+---
+name: sui-time-picker
+selector: sui-time-picker
+resumen: Campo para elegir una hora del día, con columnas de hora, minuto y AM/PM
+alternativas: [sui-tab-chips + sui-radio-label (día y franja de entrega de un pedido programado), sui-select (pocas horas fijas), sui-input type="time" (hora libre con el selector del sistema)]
+---
+
+# sui-time-picker
+
+Story: [Molecules/Date & Time/Time Picker](https://sui-design-system.web.app/?path=/docs/molecules-date-time-time-picker--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para una **hora del día** que la persona escribe con libertad: el horario de apertura y
+cierre del local, el turno del repartidor, «Cerrar hasta las 9:30 PM».
+
+**No lo uses** para:
+
+- **La hora de entrega de un pedido programado**: no se elige una hora libre, se elige una
+  **franja** que el local puede cumplir. Va la hoja del checkout (`sui-tab-chips` para el día y
+  `sui-radio-label` con `flip` para cada franja). Es la maqueta aprobada, y el propio código
+  descartó `sui-time-picker-item` para esas filas porque son densas y sin separación
+  (`checkout.html:475`).
+- Pocas horas fijas («12:00», «13:00», «14:00»): `sui-select`.
+- Una duración («30 min», «1 h»): no hay componente de duración; un `sui-select` o
+  `sui-tab-chips` con los valores (ver Trampas: los presets de este componente no son duraciones).
+
+Regla corta: **hora libre del día → time-picker · franja de entrega → la hoja del checkout ·
+pocas horas → select.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente.** Todo es **propuesta, falta
+> aprobación**, aunque ya sea práctica de la app.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **7 usos en
+> 4 pantallas** — horario del local (`weekly-schedule-editor`, 2), turnos del repartidor
+> (`driver-schedule`, 2), votaciones de cierre y recargo (`driver-dashboard`, 2) y el cierre del
+> local en la central (`central-inicio`, 1). Los 7 van con `size="medium"`, `format="12h"`,
+> `[durationPresets]="[]"` y footer. `step`: 5 en 5 usos, 30 en 2.
+
+### `format`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `12h` (default) | Siempre: en Perú la hora se dice «9:30 PM». Los 7 usos lo llevan. | propuesta |
+| `24h` | No usar en la app. | no usar |
+
+### `step`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `5` (default) | Horas reales que la persona conoce al minuto: apertura y cierre del local, «cerrar hasta». Con saltos de 30 se redondeaban cierres reales (comentario en `weekly-schedule-editor.html:41`). | propuesta |
+| `30` | Bloques de un turno, que se planifican por media hora (`driver-schedule.html:142`). | propuesta |
+| `15` | Citas o reservas en cuartos de hora. Sin caso hoy. | propuesta |
+| `1` | No usar: 60 opciones en la columna para una precisión que nadie pide. | no usar |
+
+### `durationPresets`, `showFooter`, `inline`
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `durationPresets` | `[]` | **Siempre.** Los presets de fábrica (15 min, 30 min, 45 min, 1 h) ponen la hora como «tiempo desde la medianoche»: «30 min» deja 12:30 AM. Los 7 usos los apagan. | propuesta |
+| `durationPresets` | lista propia | No usar mientras se lean como hora del día. | no usar |
+| `showFooter` | `true` (default) | Cancelar/Aplicar: la hora no cambia hasta confirmar. Es lo correcto cuando la hora se guarda o publica algo (el horario del local). | propuesta |
+| `showFooter` | `false` | Se aplica al tocar cada columna. Solo dentro de un formulario que ya tiene su propio «Guardar». | propuesta |
+| `inline` | `true` | El panel es el contenido, dentro de un `sui-modal` (sin campo ni popover). | propuesta |
+
+### `size`, `label`, `hint`, `error`, `required`, `disabled`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `size="medium"` (40 px, default) | Siempre: es el más grande que hay (ver «Tamaño»). | propuesta |
+| `size="small"` (36 px) | Filas densas en web. | propuesta |
+| `label` | Siempre, corto y en verbo o momento: «Abre», «Cierra», «Inicio», «Cerrar hasta». | propuesta |
+| `sublabel` / `tooltip` | «Opcional» o una aclaración que no entra en el label. | propuesta |
+| `hint` | Qué pasa con esa hora: «Se reabre sola a medianoche». | propuesta |
+| `error` + `errorMessage` | La hora no cuadra: «Cierra antes de abrir». | propuesta |
+| `required` | La hora es obligatoria para guardar. | propuesta |
+| `disabled` | Mientras se guarda (como hacen el horario y los turnos). | propuesta |
+| `placeholder` | Lo que se elige: «Hora de cierre». El default «Seleccionar hora» sirve. | propuesta |
+
+Usos de hoy que rompen la regla: **0**. Los 7 cumplen `12h`, `durationPresets=[]` y `label`.
+
+### Las piezas que trae (exportadas, sin carpeta ni story propias)
+
+| pieza | qué es | cuándo suelta | fuente |
+|---|---|---|---|
+| `sui-time-picker-item` | una fila de la columna (36 px) | No usar: para filas de horario que se tocan con el pulgar va `sui-radio-label` (`checkout.html:475`). | no usar |
+| `sui-time-picker-duration` | la pastilla de un preset | No usar: es la de los presets de duración. | no usar |
+| `sui-time-picker-status` | pastilla Disponible/Ocupado/En reunión/Desconectado | No usar: sus textos de fábrica están en inglés y el estado del repartidor ya tiene su badge. | no usar |
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: lo que se toca mide **44 px o más**. En web, con mouse, va más
+chico. En pantallas de los dos se elige con el servicio de breakpoints de la app (`bp`, en
+`services/breakpoints.service.ts`).
+
+`size` tiene `small` (36), `medium` (40, default) y **`large` (48)**, extensión SUI: mide lo mismo
+que `sui-input` y `sui-select` `large`, que van al lado en los formularios de horario. Con `large`
+el panel también crece: **filas de 44** y **Cancelar / Aplicar en `large` (48)**. En mobile
+(≤ 767 px) las filas miden 44 con cualquier `size`.
+
+| pieza | `small` · `medium` en web | `large` | mobile (cualquier size) | fuente |
+|---|---|---|---|---|
+| campo (trigger) | 36 · 40 | 48 | el del `size` | 36/40: medido · 48: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| fila de la columna | 36 | 44 | 44 | 36: Figma · 44: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| Cancelar / Aplicar | 36 | 48 | el del `size` | canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| horario en un formulario | `large` | `medium`, o `small` en filas densas | propuesta, falta aprobación |
+
+```html
+<sui-time-picker label="Cierra" format="12h" [step]="5" [durationPresets]="[]"
+                 [size]="bp.isMobile() ? 'large' : 'medium'"
+                 [value]="cierre()" (valueChange)="cierre.set($event)" />
+```
+
+## «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 |
+|---|---|---|
+| `format="24h"` | en Perú se dice «9:30 PM» | una pantalla técnica del super admin (registro de eventos) donde se comparan horas |
+| `step="1"` | 60 opciones sin necesidad | registrar la hora exacta de un hecho (hora real de entrega en un reclamo) |
+| `durationPresets` (cualquiera) | se leen como hora desde la medianoche, no como duración | si el DS los cambia para sumar sobre la hora elegida («en 30 min») |
+| `sui-time-picker-item` suelto | fila de 36 px, densa | una lista desplegable de horas en web |
+| `sui-time-picker-duration` suelto | es parte de los presets | — |
+| `sui-time-picker-status` | textos en inglés; el estado del repartidor ya tiene su badge | un panel de disponibilidad del equipo del local, con los textos en español |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-time-picker`
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string \| null` | `null` |
+| `sublabel` | `string \| null` | `null` |
+| `required` | `boolean` | `false` |
+| `tooltip` | `string \| null` | `null` |
+| `hint` | `string \| null` | `null` |
+| `errorMessage` | `string \| null` | `null` |
+| `error` | `boolean` | `false` |
+| `placeholder` | `string` | `'Seleccionar hora'` |
+| `disabled` | `boolean` | `false` |
+| `size` | `'small' \| 'medium' \| 'large'` | `'medium'` |
+| `format` | `'12h' \| '24h'` | `'12h'` |
+| `step` | `number` | `5` |
+| `durationPresets` | `readonly SuiTimeDurationPreset[]` | `DEFAULT_DURATION_PRESETS` |
+| `inline` | `boolean` | `false` |
+| `showFooter` | `boolean` | `true` |
+| `value` · model, `[(value)]` | `SuiTimeValue \| null` | `null` |
+
+Outputs: ninguno.
+
+### `sui-time-picker-duration`
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | — (requerido) |
+| `active` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `Event` |
+
+### `sui-time-picker-item`
+
+| input | tipo | default |
+|---|---|---|
+| `time` | `string` | — (requerido) |
+| `meridiem` | `string \| null` | `null` |
+| `rightTime` | `string \| null` | `null` |
+| `rightMeridiem` | `string \| null` | `null` |
+| `direction` | `'right' \| 'center'` | `'right'` |
+| `active` | `boolean` | `false` |
+| `highlighted` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `Event` |
+
+### `sui-time-picker-status`
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'available' \| 'busy' \| 'in-meeting' \| 'offline'` | `'available'` |
+| `label` | `string \| null` | `null` |
+| `selected` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `clicked` | `Event` |
+<!-- api:fin -->
+
+Es `ControlValueAccessor`; `writeValue` acepta también un string `"21:30"`.
+
+```ts
+interface SuiTimeValue { hours: number; minutes: number; }   // hours en 0–23 aunque el format sea 12h
+interface SuiTimeDurationPreset { label: string; minutes: number; }
+```
+
+## Trampas
+
+- **Los presets de duración no son duraciones**: «30 min» pone la hora en 00:30 (12:30 AM). Por eso
+  se pasan siempre `[durationPresets]="[]"`. Sin eso, el panel muestra cuatro pastillas que
+  rompen la hora.
+- **`value.hours` va de 0 a 23** aunque se muestre en 12h: 9:30 PM es `{ hours: 21, minutes: 30 }`.
+- **Al abrir sin valor arranca en 9:00 AM**, no vacío.
+- **Cerrar con clic afuera o Escape descarta** lo elegido, igual que Cancelar.
+- Con `step` que no contiene el minuto guardado (21:37 con step 5), la columna de minutos no
+  marca ninguno.
+- Cancelar / Aplicar solo crecen con `size="large"`: con `medium` en mobile siguen en 36. En el
+  teléfono va `large`.
+- El panel flota con el overlay del DS (como `sui-select`): se da vuelta si no entra abajo.
+- `sui-time-picker-status` dice «Disponible», «Ocupado», «En reunión» y «Desconectado» por
+  defecto (antes venían en inglés del Figma); `label` sigue sirviendo para cambiarlo.
+- El atributo `title` del host se borra solo (no sale el tooltip gris del navegador).
+
+## Ejemplo
+
+```html
+<!-- Horario del local: abre / cierra -->
+<sui-time-picker label="Abre" format="12h" [step]="5" [durationPresets]="[]"
+                 [value]="apertura()" (valueChange)="apertura.set($event)" />
+<sui-time-picker label="Cierra" format="12h" [step]="5" [durationPresets]="[]"
+                 [error]="cierraAntes()" errorMessage="Cierra antes de abrir"
+                 [value]="cierre()" (valueChange)="cierre.set($event)" />
+```