@ajuarezso/sui-design-system 0.20.0 → 0.21.0

package/docs/sui-tab-menu-vertical/README.md

@@ -0,0 +1,136 @@
+---
+name: sui-tab-menu-vertical
+selector: sui-tab-menu-vertical
+resumen: Menú apilado para cambiar entre secciones de una página de ajustes en web
+alternativas: [sui-tab-menu-horizontal (pocas secciones arriba del contenido), sui-sidebar (navegación de toda la app), sui-tab-chips (filtros o categorías)]
+---
+
+# sui-tab-menu-vertical
+
+Story: [Molecules/Tabs/Tab Menu Vertical](https://sui-design-system.web.app/?path=/docs/molecules-tabs-tab-menu-vertical--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en **web** para una página con varias secciones que se leen de a una, con el menú a la
+izquierda y el contenido a la derecha: los ajustes del local («Datos del local · Horario · Métodos
+de pago · Repartidores»), el perfil del super admin.
+
+**No lo uses** para:
+
+- **Mobile**: el ítem mide 36 px y ocupa el ancho de la pantalla dejando el contenido debajo. En
+  mobile cada sección es una fila de una lista que abre su propia pantalla.
+- La navegación de toda la app: `sui-sidebar`.
+- 2 a 4 secciones arriba del contenido: `sui-tab-menu-horizontal`.
+- Filtros de una lista: `sui-tab-chips`.
+
+Regla corta: **secciones de una página de ajustes en web → tab menu vertical · en mobile → lista de
+filas que abren pantalla.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: es un layout apilado para **cambiar entre secciones o categorías**.
+> Sus ejemplos son ajustes («Profile Settings · Contact Information · Social Links · Export Data»),
+> uno con **título arriba** (en SUI, `dividerLabel`) y otro con **contenedor con estilo** (en SUI,
+> `menuStyle="card"`). No trae do/don't.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`): **0 usos**.
+
+### `menuStyle`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `card` | El menú flota junto al contenido sobre un fondo gris (`bg-weak-50`): el borde y la sombra lo separan. | según la guía del DS (ejemplo «contenedor con estilo»); el cuándo es propuesta |
+| `list` | El menú vive dentro de una columna que ya tiene fondo o borde propio (una card, un panel). | según la guía del DS (ejemplo base); el cuándo es propuesta |
+
+### `dividerLabel`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| vacío (default) | Un solo grupo de secciones. | propuesta, falta aprobación |
+| texto | Nombra el grupo cuando hay más de un menú apilado («Tu local» · «Tu cuenta»). Sale en MAYÚSCULAS y gris. | según la guía del DS (ejemplo con título) |
+
+### Ítems (`tabs`)
+
+| qué | cuándo | fuente |
+|---|---|---|
+| texto | El nombre de la sección. Una o dos palabras; si es más largo, se corta con «…». | según la guía del DS (ejemplos con texto) |
+| `icon` | Sí, en todos los ítems: en un menú lateral el ícono ayuda a encontrar rápido. El activo se pinta naranja. | propuesta, falta aprobación |
+| `number` | Pendientes que piden acción en esa sección (círculo rojo). | propuesta, falta aprobación |
+| `rightIcon` | Cuando el ítem lleva a otra página en vez de cambiar el panel de al lado. | propuesta, falta aprobación |
+| `disabled` | Una sección que depende del plan. | propuesta, falta aprobación |
+
+Usos de hoy que rompen las reglas: **0** (no se usa).
+
+## Tamaño en mobile y en web
+
+Ítem de **36 px** (8 + 20 + 8), ícono de 20. **No tiene `size`** y no tiene tamaño para mobile.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| secciones de ajustes | no se usa: lista de filas que abren pantalla | `tab-menu-vertical` | propuesta, falta aprobación |
+
+```html
+@if (!bp.isMobile()) {
+  <sui-tab-menu-vertical [tabs]="secciones" [(active)]="seccion" menuStyle="card" />
+}
+```
+
+## «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 | ninguna pantalla de la app tiene hoy un menú lateral de secciones | una página de ajustes en web con 5+ secciones (ajustes del local en desktop) |
+| en mobile | 36 px y sin lugar para el contenido al lado | nunca |
+| `rightIcon` | ningún menú mezcla paneles y páginas | un ítem «Facturación» que sale a otra página mientras el resto cambia el panel |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `tabs` | `SuiTabMenuVerticalItem<T>[]` | — (requerido) |
+| `active` · model, `[(active)]` | `T` | `undefined` |
+| `menuStyle` | `'card' \| 'list'` | `'card'` |
+| `dividerLabel` | `string` | `''` |
+
+| output | payload |
+|---|---|
+| `tabChange` | `T` |
+<!-- api:fin -->
+
+```ts
+interface SuiTabMenuVerticalItem<T = string> {
+  value: T;
+  label: string;
+  icon?: string;        // RemixIcon, 20 px
+  rightIcon?: boolean;  // flecha en píldora con sombra
+  number?: number;      // círculo rojo; 0/undefined no se dibuja
+  disabled?: boolean;
+}
+type SuiTabMenuVerticalStyle = 'card' | 'list';
+```
+
+## Trampas
+
+- **El estilo se llama `menuStyle`**, no `style` ni `variant` (ni `verticalStyle`, que era el nombre
+  viejo de `sui-tabs`).
+- **Sin `active` no se marca ningún ítem.** Pásale un valor inicial.
+- **Ocupa el ancho del padre**: dale un ancho fijo a la columna (240-280 px).
+- **El ícono activo es naranja** (`primary-base`); en el tab menu horizontal es negro. Es a propósito.
+- **Emite dos veces**: `tabChange` y `activeChange`.
+- `role="tablist"`: si cada ítem navega a una ruta, el lector de pantalla lo anuncia mal; para
+  navegación entre rutas, `sui-sidebar`.
+
+## Ejemplo
+
+```html
+<sui-tab-menu-vertical
+  menuStyle="card"
+  dividerLabel="Tu local"
+  [tabs]="[{ value: 'datos', label: 'Datos del local', icon: 'store-2-line' },
+           { value: 'horario', label: 'Horario', icon: 'time-line' },
+           { value: 'pagos', label: 'Métodos de pago', icon: 'bank-card-line' }]"
+  [(active)]="seccion" />
+```

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)" />
+```