@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-input/README.md

@@ -0,0 +1,340 @@
+---
+name: sui-input
+selector: sui-input
+resumen: Campo de una sola línea para escribir un dato (nombre, teléfono, monto, búsqueda)
+alternativas: [sui-textarea (texto de varias líneas), sui-select (elegir de una lista), sui-counter-input (una cantidad con − y +), sui-tag-input (varios valores cortos), sui-otp-input (código de verificación), sui-inline-input (editar un dato en su lugar, con lápiz)]
+---
+
+# sui-input
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-input`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+Story: [Molecules/Input/Input](https://sui-design-system.web.app/?path=/docs/molecules-input-input--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para todo dato de una línea que la persona escribe: nombre, correo, teléfono, DNI,
+placa, dirección, referencia, monto, fecha, y para los buscadores. Trae adentro el label, el
+hint, el error, el prefijo `S/`, la X de limpiar y el ojo de la contraseña: no se arman a mano.
+
+**No lo uses** para:
+
+- Texto que puede ocupar más de una línea (motivo, nota al repartidor, descripción): `sui-textarea`.
+- Elegir entre opciones que ya existen: `sui-select` (o radio / segmented si son pocas).
+- Una cantidad que se sube y se baja de a uno: `sui-counter-input`.
+- Un código de verificación de N dígitos: `sui-otp-input`.
+- Varios valores cortos que se van sumando: `sui-tag-input`.
+- Un `<input>` nativo con CSS propio: hoy quedan **6** (`pages/products/add-product/add-product.html:130`,
+  `:143`, `:189`, `:275`, `pages/apps/apps.html:12`, `pages/employees/employees.html:43`).
+
+Regla corta: **una línea → input · varias → textarea · de una lista → select · cantidad → counter.**
+
+## Qué variante usar
+
+> **La guía del DS casi no dice «cuándo».** Su página del input lo define como el campo para
+> escribir un valor de una sola línea y muestra ejemplos (ícono, tamaños, afijos, label y hint,
+> contraseña con ojo, contraseña con niveles, error, con botón, tarjeta, con select, con tags,
+> fecha y contador) sin do/don't. Lo marcado «según la guía del DS» sale de esos ejemplos; el
+> resto es canon (CLAUDE.md, CANON-SUI o aprobado por el dueño el 05-10-2026); lo que sigue en **propuesta** espera decisión.
+>
+> Uso medido el 06-10-2026 en `master-pedidos/src/app` @ `9f0e54c3` (misma exclusión que
+> `sui-badge`, más `master-ejercicios`): **200 usos en 66 archivos** — 196 en 63 `.html` y 4 en
+> templates inline de 3 `.ts` (`components/option-image/option-image.ts`, `pages/dx/modal-test/modal-test.ts`,
+> `pages/dx/sandbox/sandbox.ts`). Tipos: 45 `text`, 35 sin `type` (`text`), 35 `amount`,
+> 22 `search`, 22 `tel`, 18 `number`, 10 `email`, 7 `date`, 3 `password-toggle`, 2 `url`,
+> 1 `datetime-local`. Tamaños, tras la migración a D16: 195 `bp.sizeControl()` (191 en `.html`
+> y los 4 inline), 3 `xlarge` (los buscadores principales del cliente), 1 `bp.controlSize()` y
+> 1 dinámico propio (`components/product-detail-view/product-detail-view.html:223`). Ninguno sin `size`.
+
+### `type` — qué dato es
+
+El `type` decide el teclado del teléfono y el filtro de teclas. Por dentro, `number`, `tel`,
+`amount` y `card` son un `<input type="text">`: el componente filtra lo que se tipea.
+
+| type | cuándo | fuente |
+|---|---|---|
+| `text` (default) | Nombre, dirección, referencia, placa, DNI (con `inputmode="numeric"`). | según la guía del DS (tipo nativo) |
+| `email` | Correo. Pide el teclado con `@`. Va con `autocomplete="email"`. | según la guía del DS (ejemplo con label y hint) |
+| `tel` | Celular peruano de 9 dígitos, con `maxlength="9"` y placeholder `987 654 321`. | según la guía del DS (tipo nativo); el formato es propuesta |
+| `amount` | **Todo monto en soles**, siempre con `prefix="S/"` y placeholder `0.00`. Pone comas de miles y dos decimales al salir. | canon (CANON-SUI §5.5, 27-07-2026) |
+| `number` | Un entero que no es dinero: minutos, kilómetros, cupos, porcentaje. Si es dinero, `amount`. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `search` | **Todo buscador.** Pide la lupa en el teclado sola (y no lleva `inputmode`). | canon (CLAUDE.md «La lupa del teclado», 14-08-2026) |
+| `password-toggle` | **Toda contraseña**: login y registro. El ojo deja revisar lo escrito en el teléfono. | según la guía del DS (sus dos ejemplos de contraseña traen el ojo) |
+| `password` | No usar: sin ojo, en el teléfono no se puede revisar lo tipeado. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `date` / `datetime-local` | Una fecha suelta en un formulario del panel («Válido hasta», «Fecha del gasto»). Abre el selector nativo. Para un calendario propio, ver `sui-datepicker`. | propuesta, falta aprobación |
+| `url` | Un enlace (imagen de campaña). | según la guía del DS (ejemplo con afijo `https://`) |
+| `card` | No usar hoy: no hay pago con tarjeta. | según la guía del DS (ejemplo «Payment Input») |
+| `button` | No usar hoy: campo de solo lectura con una acción al lado (copiar enlace). | según la guía del DS (ejemplo «With Button») |
+
+**Usos de hoy que rompen la regla:** ninguno (medido el 04-10-2026). Los 11 buscadores con
+`type="text"`, los 21 `amount` sin `prefix="S/"`, los 2 montos con `type="number"` y los 3
+`password` sin ojo se corrigieron en la app el 03-10-2026 (merge `70f937e4`).
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre, salvo en un buscador (ahí el placeholder y la lupa ya dicen qué es). Una a tres palabras, sentence case. | según la guía del DS (ejemplo con label); largo: canon (CANON-SUI §5.4) |
+| `required` | Campo obligatorio: asterisco rojo. | según la guía del DS (`Email Address*`) |
+| `sublabel` | **«(Opcional)»**, entre paréntesis, en un campo que no es obligatorio, en vez de escribir «(opcional)» en el label. También «(No editable)». El componente no pone los paréntesis: sin ellos queda pegado («ReferenciaOpcional»). | según la guía del DS (`Optional`) y canon (README de `sui-form-label`) |
+| `tooltip` | Una aclaración que no entra en el hint. Hoy sin uso. | según la guía del DS (ícono de info del label) |
+| `hint` | Una línea que ayuda a llenar bien: «9 dígitos, empezando con 9», «Mínimo 6 caracteres». | según la guía del DS |
+| `hintIcon` | No usar hoy: el hint se lee solo; el ícono suma ruido en formularios largos. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `error` + `errorMessage` | El error va **con** su mensaje, que reemplaza al hint. `error` solo pinta el borde. | según la guía del DS (`Has Error`) |
+| `placeholder` | Un ejemplo del formato, no el nombre del campo: «987 654 321», «Ej: Av. Perú 224», «0.00». Elipsis `…`, no `...`. | canon (CANON-SUI §5.2 y §5.5) |
+| `prefix` | `S/` en los montos. Nada más hoy. | canon (CANON-SUI §5.5) |
+| `icon` + `iconPosition` | `search-line` a la izquierda en buscadores; `map-pin-2-line` en un campo de dirección de solo lectura. `right` no tiene caso hoy. | según la guía del DS (ejemplo con ícono); el «cuándo»: canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `showClear` | Buscadores: la X borra la búsqueda de un toque. | propuesta, falta aprobación (ya lo hacen los 3 buscadores del cliente) |
+| `fullRadius` | Solo el buscador principal del cliente (home, carta del local, rubro), que va encima de chips redondos. Los formularios, con el radio normal. | canon (aprobado por el dueño, 05-10-2026, bloque B9) (ya es práctica: `pages/customer/store-browser/store-browser.html:43`) |
+| `maxlength` | Teléfono (9), nombres con tope, códigos. | propuesta, falta aprobación |
+| `inputmode` | Solo cuando el `type` no pide el teclado correcto: un DNI o un número de cuenta en `type="text"` → `numeric`. **Nunca `search`.** | canon (CLAUDE.md «La lupa del teclado», 14-08-2026) |
+| `enterkeyhint` | `next` en formularios de varios pasos, `send` en un chat, `done` en el último campo. El buscador ya pide `search` solo. | propuesta, falta aprobación |
+| `autocomplete` | Siempre en datos de la persona: `name`, `given-name`, `email`, `tel`, `current-password`, `new-password`. `off` en buscadores. | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+| `readonly` | Un dato que se muestra en forma de campo pero se elige en otro lado (el distrito que sale del mapa). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `disabled` | Mientras se envía, o cuando el campo no aplica todavía. | según la guía del DS |
+| `min` / `max` | **No hacen nada** (el `<input>` real es `text`). Validar en el componente que lo usa. | código del DS |
+| `paste` | `false` solo si pegar un monto armaría un valor equivocado. Hoy sin uso. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `closeOnOutsideClick` | Déjalo en `true`: tocar fuera baja el teclado. `false` solo si la pantalla maneja el foco a mano (1 uso). | código del DS |
+| `leadingControl` / `trailingControl` / `leadingDivider` / `trailingDivider` | Componer un control adentro: el país del teléfono (`sui-compact-select-for-input` en `slot="start"`) o una acción al lado. Hoy sin uso. | según la guía del DS (ejemplos «With Select» y «With Button») |
+
+**Usos de hoy que rompen la regla** (medido el 04-10-2026; los `sublabel` sin paréntesis, los
+«(opcional)» en el label y los placeholders con `...` ya se corrigieron en la app, commits
+`ce4a2d12` y `e0470b34`):
+
+- **2 campos sin label en el login** (el placeholder hace de rótulo): `pages/auth/login/login.html:64`, `:72`.
+- **6 campos con el label afuera** (`<sui-form-label>` suelto encima) en el onboarding del
+  repartidor: `pages/driver-onboarding/step-info/step-info.html:37`. Funciona, pero el error y el
+  `required` quedan desconectados del campo: va el `label` del propio input.
+
+## Tamaño en mobile y en web
+
+Los altos de `sui-input` son **los del botón a propósito** (`large` 48 y `xlarge` 52 son
+extensión de SUI): un campo y un botón puestos lado a lado miden lo mismo. La guía del DS solo
+tiene `medium` (40), `small` (36) y `xsmall` (32).
+
+En large y xlarge el texto sube a 16 px (canon, aprobado por el dueño el 03-10-2026): el valor, el placeholder y el
+prefijo van en 16/24 también en desktop. En mobile el valor y el placeholder ya iban en 16 en
+cualquier tamaño (por el zoom de iOS), y desde el 04-10-2026 el prefijo `S/` los acompaña: en el
+teléfono también va en 16 en todos los tamaños (antes se quedaba en 14 al lado de un monto de 16).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| campo de formulario | `large` (48), igual que el botón del footer | `medium` (40) | mobile `large`: canon (decisión del dueño 04-10-2026, piso táctil 44: `medium` 40 no llega y `large` 48 es el primer size que sí) · web `medium`: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| buscador principal del cliente (home, carta, rubro) | `xlarge` (52) + `fullRadius` | `xlarge` + `fullRadius` | canon (aprobado por el dueño, 05-10-2026, bloque B1) (ya es práctica en las 3 pantallas) |
+| buscador o filtro de una lista del panel | `large` (48) | `medium` (40) | mobile `large`: canon (decisión del dueño 04-10-2026, piso táctil 44: `large` 48 es el primer size que llega) · web `medium`: canon (dueño, 05-10-2026, D16) (`pages/orders/orders.html:73` ya va con `bp.sizeControl()`; medido el 06-10-2026) |
+| campo dentro de una tabla o fila densa | no aplica | `medium` (40) | canon (dueño, 05-10-2026, D16): nada en `xsmall` (la guía del DS lo usa ahí) |
+
+```html
+<sui-input size={bp.sizeControl()} label="Teléfono" type="tel" … />
+<!-- bp = BreakpointsService de la app -->
+```
+
+No uses `bp.controlSize()` en campos: es el de checkbox/radio/switch, da `xlarge` (52) en mobile,
+más alto que el botón `large` del footer, y `large` en la computadora (1 uso hoy:
+`pages/customer/checkout/checkout.html:385`, el cupón). El texto sube solo a 16 px en mobile (evita
+el zoom de iOS): no hace falta pedirlo.
+
+Hoy (medido el 06-10-2026): **195 de los 200 usos** ya van con `bp.sizeControl()` (191 en `.html` y
+4 en templates inline de `.ts`); quedan los 3 buscadores principales en `xlarge` fijo (van bien), el cupón con `bp.controlSize()` y un dinámico propio.
+
+### Por dispositivo (D16)
+
+Fila `input` de la tabla D16 (dueño, 05-10-2026). Se toca, así que va por tipo de puntero además
+del ancho, igual que `sui-button`: campo y botón de al lado miden lo mismo en cada dispositivo.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `large` (48) | D16 pide `medium` con área tocable de 44; mientras el DS no estire el área de los `medium`, va `large` (interino) |
+| celular (380–767 px) | `large` (48) | mismo alto que el botón `large` del footer |
+| tablet táctil (`pointer: coarse`) | `large` (48) | también se toca con el dedo; `bp.isMobile()` la dejaba en `medium` |
+| computadora (`pointer: fine`) | `medium` (40) | también filtros y campos dentro de tablas; `small` y `xsmall` no se usan |
+
+Buscador principal del cliente (home, carta, rubro): `xlarge` (52) + `fullRadius` en todos los
+dispositivos (B1). Ultrawide (≥ 1920 px): igual que la computadora, `medium`; el espacio extra va a
+ancho y columnas, no a campos más altos.
+
+En master-pedidos: `size={bp.sizeControl()}` · buscador principal: `size="xlarge"` + `full-radius`.
+
+## «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.
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="card"` | no hay pago con tarjeta | el día que entre Culqi o Niubiz y el número se tipee en la app |
+| `type="button"` | no hay campos con acción pegada | «Copia tu enlace de invitación» o el link público de la tienda con botón de copiar |
+| `type="password"` | sin ojo no se puede revisar en el teléfono | nunca en login; quizá un PIN que no debe mostrarse |
+| `type="time"` | los horarios usan `sui-time-picker` | una hora suelta en un formulario del panel |
+| `hintIcon` | el hint se lee solo | un hint que es advertencia («No se puede cambiar después») |
+| `tooltip` | el hint alcanza | un término técnico del panel (CCI, RUC) que no entra en una línea |
+| `iconPosition="right"` | el ícono de la derecha se confunde con una acción | un dato con unidad visual (un ícono de moto en «Placa») |
+| `paste=false` | pegar ayuda más de lo que rompe | un monto que llega con formato raro desde otra app |
+| afijos con control (`leadingControl`…) | solo hay teléfonos de Perú (+51) | teléfono con código de país, o monto con moneda (ver `sui-compact-select-for-input`) |
+| `size="xsmall"` | es chico (D16, 05-10-2026) | nunca: la edición rápida de un precio dentro de una tabla va `medium` |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `autocomplete` | `autocomplete` | `null \| string` | `null` |
+| `closeOnOutsideClick` | `close-on-outside-click` | `boolean` | `true` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `enterkeyhint` | `enterkeyhint` | `"done" \| "enter" \| "go" \| "next" \| "previous" \| "search" \| "send" \| null` | `null` |
+| `error` | `error` | `boolean` | `false` |
+| `errorMessage` | `error-message` | `null \| string` | `null` |
+| `fullRadius` | `full-radius` | `boolean` | `false` |
+| `hint` | `hint` | `null \| string` | `null` |
+| `hintIcon` | `hint-icon` | `null \| string` | `null` |
+| `icon` | `icon` | `null \| string` | `null` |
+| `iconPosition` | `icon-position` | `"left" \| "right"` | `'left'` |
+| `inputPrefix` | `input-prefix` | `null \| string` | `null` |
+| `inputmode` | `inputmode` | `"decimal" \| "email" \| "none" \| "numeric" \| "search" \| "tel" \| "text" \| "url" \| null` | `null` |
+| `label` | `label` | `null \| string` | `null` |
+| `leadingControl` | `leading-control` | `boolean` | `false` |
+| `leadingDivider` | `leading-divider` | `boolean` | `false` |
+| `max` | `max` | `null \| number` | `null` |
+| `maxlength` | `maxlength` | `null \| number` | `null` |
+| `min` | `min` | `null \| number` | `null` |
+| `paste` | `paste` | `boolean` | `true` |
+| `placeholder` | `placeholder` | `string` | `''` |
+| `readonly` | `readonly` | `boolean` | `false` |
+| `required` | `required` | `boolean` | `false` |
+| `showClear` | `show-clear` | `boolean` | `false` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xlarge" \| "xsmall"` | `'medium'` |
+| `sublabel` | `sublabel` | `null \| string` | `null` |
+| `tooltip` | `tooltip` | `null \| string` | `null` |
+| `trailingControl` | `trailing-control` | `boolean` | `false` |
+| `trailingDivider` | `trailing-divider` | `boolean` | `false` |
+| `type` | `type` | `"amount" \| "button" \| "card" \| "date" \| "datetime-local" \| "email" \| "number" \| "password" \| "password-toggle" \| "search" \| "tel" \| "text" \| "time" \| "url"` | `'text'` |
+| `value` | `value` | `string` | `''` |
+
+| evento | `event.detail` |
+|---|---|
+| `suiBlur` | `void` |
+| `suiFocus` | `void` |
+| `valueChange` | `string` |
+
+| método | firma |
+|---|---|
+| `clearValue` | `clearValue() => Promise<void>` |
+
+Slots: `start`, `end`.
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `prefix`
+- **Props solo de aquí:** `inputPrefix`
+- **Eventos solo de aquí:** `suiBlur`, `suiFocus`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `comun.limpiar` | Limpiar | — |
+| `input.ocultarContrasena` | Ocultar contraseña | — |
+| `input.mostrarContrasena` | Mostrar contraseña | — |
+<!-- textos:fin -->
+
+`value` es `model<string>`: `value` + `valueChange` o `value` + `valueChange`. También funciona con
+`formControlName` y `ngModel` + `ngModelChange` (implementa `ControlValueAccessor`).
+
+Slots: `slot="start"` y `slot="end"` (íconos que no son RemixIcon o controles
+proyectados con `leadingControl` / `trailingControl`).
+
+## Trampas
+
+- **`maxlength` va en minúscula** aquí; en `sui-textarea` es `maxLength`.
+- **`min` y `max` no validan nada**: el `<input>` real es `type="text"` y el navegador los ignora.
+- **`amount` devuelve el número sin comas** («1234.50») aunque muestre «1,234.50», y rellena los
+  decimales al salir del campo. Si el padre hace `toFixed` y lo devuelve, compara con `parseFloat`,
+  no como texto (ver CLAUDE.md, bug de minOrder). Lo cubren 26 tests en `sui-input.spec.ts`.
+- **Nunca `inputmode="search"`**: en Android tapa la lupa del teclado. `type="search"` ya la pide.
+- **Un `tel` con `maxlength="9"` y placeholder `987 654 321`**: el filtro deja escribir espacios;
+  quien copie el formato del placeholder llega al tope antes del último dígito. Limpiar espacios en
+  el `valueChange` o no poner espacios en el placeholder.
+- `showClear` solo aparece con texto escrito y si el campo no está `disabled` ni `readonly`.
+- `error` sin `errorMessage` pinta el borde y no dice qué pasa.
+- El label no crece con el campo: en `large` y `xlarge` se queda en `medium` a propósito.
+- Tocar fuera baja el teclado (`closeOnOutsideClick`). Ya distingue tocar otro campo: no hace falta
+  agregar lógica de blur en la pantalla.
+- El `(keydown.enter)` puesto en el host funciona: el evento sube desde el `<input>` de adentro.
+- **Accesibilidad (04-10-2026)**: cada campo trae su `id`; el `label` interno apunta a él con `for`,
+  el hint o el error se enlazan con `aria-describedby` y `error` pone `aria-invalid`. No hace
+  falta agregarlos a mano. Un `sui-form-label` puesto **afuera** no conoce ese `id`: usa `label`.
+- En el teléfono la X de limpiar y el ojo se ven de 12-20 px pero se tocan en 44 × 44 (área
+  invisible, 04-10-2026).
+
+## Bien y mal
+
+Tamaño del campo del cupón
+
+```html
+<!-- ❌ mal: bp.controlSize() es de checkbox/radio/switch: xlarge en el celular y large en la computadora (pages/customer/checkout/checkout.html:385) -->
+<sui-input size={bp.controlSize()} placeholder="Código de descuento" value={cupon} onValueChange={(e) => (cupon = e.detail)} />
+```
+
+```html
+<!-- ✅ bien (y el botón «Aplicar» de al lado, también con bp.sizeControl()) -->
+<sui-input size={bp.sizeControl()} placeholder="Código de descuento" value={cupon} onValueChange={(e) => (cupon = e.detail)} />
+```
+
+DNI con el label afuera
+
+```html
+<!-- ❌ mal: el label suelto no conoce el id del campo (su for no apunta a nada) y el DNI no es un número (pages/driver-onboarding/step-info/step-info.html:56 y :60) -->
+<sui-form-label label="DNI" required for="ob-dni" />
+<sui-input size={bp.sizeControl()} type="number" inputmode="numeric" placeholder="74523618"
+           maxlength="8" value={dni} onValueChange={(e) => (dni = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-input label="DNI" required type="text" inputmode="numeric" placeholder="74523618"
+           maxlength="8" hint="8 dígitos" size={bp.sizeControl()} value={dni} onValueChange={(e) => (dni = e.detail)} />
+```
+
+Teléfono con espacios en el placeholder
+
+```html
+<!-- ❌ mal: con maxlength="9", quien copia los espacios del placeholder llega al tope antes del último dígito (pages/mi-negocio/mi-negocio.html:689) -->
+<sui-input size={bp.sizeControl()} type="tel" placeholder="987 654 321" maxlength="9" value={telefono} onValueChange={(e) => (telefono = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-input label="Teléfono" type="tel" maxlength="9" autocomplete="tel" placeholder="987654321"
+           size={bp.sizeControl()} value={telefono} onValueChange={(e) => (telefono = e.detail)} />
+```
+
+## Ejemplo
+
+```html
+<!-- Campo de formulario -->
+<sui-input label="Teléfono" required type="tel" maxlength="9" autocomplete="tel"
+           placeholder="987654321" hint="9 dígitos, empezando con 9"
+           size={bp.sizeControl()} value={telefono} onValueChange={(e) => (telefono = e.detail)} />
+
+<!-- Monto -->
+<sui-input label="Monto de la compra" type="amount" prefix="S/" placeholder="0.00" value={monto} onValueChange={(e) => (monto = e.detail)} />
+
+<!-- Buscador principal del cliente -->
+<sui-input type="search" icon="search-line" placeholder="Busca negocios…" size="xlarge"
+           full-radius show-clear autocomplete="off" value={busqueda} onValueChange={(e) => (busqueda = e.detail)} />
+```

package/docs/sui-integration-switch/README.md

@@ -0,0 +1,244 @@
+---
+name: sui-integration-switch
+selector: sui-integration-switch
+resumen: Integración con otro servicio — logo, nombre, qué hace, botón «Administrar» y el interruptor para prenderla
+alternativas: [sui-switch-card (un ajuste propio de la app, sin logo ni «Administrar»), sui-switch-label (un ajuste en una lista), sui-content-card type="brand" (mostrar que un servicio está conectado, sin prender ni apagar)]
+---
+
+# sui-integration-switch
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-integration-switch`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+Story: [Molecules/Integration Switch](https://sui-design-system.web.app/?path=/docs/molecules-integration-switch--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para conectar o desconectar un servicio de terceros que además tiene su propia
+configuración: cobrar con tarjeta por Culqi o Izipay, avisar por WhatsApp Business, calcular el
+envío con Mapbox.
+
+**No lo uses** para:
+
+- Un ajuste de la app (notificaciones, ubicación, disponible): `sui-switch-card` o
+  `sui-switch-label`.
+- Mostrar que algo está conectado sin dejar apagarlo: `sui-content-card type="brand"` con un badge.
+- Elegir uno de varios servicios: `sui-radio-card type="brand"`.
+
+Regla corta: **servicio externo que se prende y se configura → integration-switch · ajuste propio
+→ switch-card.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la integration switch.** De la guía sale lo del switch que
+> lleva adentro: **«para prender o apagar un ajuste de forma inmediata»**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **0
+> usos**. La app no conecta servicios de terceros desde la interfaz: todo lo de abajo es para
+> cuando lo haga.
+
+### `type` × `appearance`
+
+| combinación | cuándo | fuente |
+|---|---|---|
+| `horizontal` · `card` (default) | Una integración suelta en una pantalla de ajustes de web. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `vertical` · `card` | Una grilla de integraciones, o la misma en mobile (el «Administrar» baja a ancho completo). | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `horizontal` · `list` | Una lista de integraciones dentro de una card que ya pone el borde. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `vertical` · `list` | Ver «No usar». | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `title` | Siempre. El nombre del servicio: «WhatsApp Business». | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `description` | Qué hace conectarlo, en una línea: «Avisa al cliente por WhatsApp cuando su pedido sale del local.» | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `brandIconSrc` | El logo del servicio (`assets/brand/brand-logos/<marca>-original.svg`). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `brandIcon` | Un ícono Remix cuando no hay logo. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| logo proyectado `[sui-integration-brand]` | Un `sui-brand-logo` u otro elemento propio. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `manage` (`true`, dice «Administrar») | Siempre que el servicio tenga configuración. El default ya está en español (03-10-2026). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `manage="false"` | El servicio no se configura: solo se prende. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `showToggle=false` | Se administra pero no se apaga desde aquí. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `badge` | Integración nueva. Con string sale naranja `light`; pasa el objeto (`purple` para lo nuevo, según el badge). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `disabled` | Falta un dato para conectarla (el RUC, la cuenta). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `active` + `activeChange` | El estado. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+
+**Usos de hoy que rompen las reglas:** 0 (no hay usos).
+
+## Tamaño en mobile y en web
+
+| size | «Administrar» | interruptor | fuente |
+|---|---|---|---|
+| `medium` (default) | 38 (8 + 20 + 8 de padding y 2 de borde), texto 14 | `sui-switch` `medium`, 32 × 20 | Figma |
+| `large` | 44 (9 + 24 + 9 + 2), texto 16 | igual: 32 × 20 | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono. Size nuevo del 04-10-2026 |
+
+| uso | mobile | web |
+|---|---|---|
+| «Administrar» | `large` (44) | `medium` (38) |
+| layout | `vertical` | `horizontal` |
+
+```html
+<sui-integration-switch size={bp.sizeControl()}
+                        type={bp.isMobile() ? 'vertical' : 'horizontal'} … />
+```
+
+**El interruptor sigue bajo el piso**: es `sui-switch` `medium` fijo (20 de alto) en los dos sizes,
+y a diferencia de `sui-switch-card`, tocar la tarjeta no prende nada: solo responde el
+interruptor. Para algo que se prende y apaga en el teléfono, `sui-switch-card` es la salida.
+
+### Por dispositivo (D16)
+
+No está en la tabla D16 por componente: va como **lo que se toca**, porque el `size` solo agranda
+«Administrar», que es un botón. Fuente: D16, dueño 05-10-2026.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `large` (44) | D16 pide `medium` con área tocable de 44; mientras el DS no estire el área de los `medium`, va `large` (interino) |
+| celular (380–767) | `large` (44) | |
+| tablet táctil (`pointer: coarse`) | `large` (44) | también se toca con el dedo: Apple pide 44 pt en el iPad |
+| computadora (`pointer: fine`) | `medium` (38) | nunca más chico |
+
+En el ultrawide, igual que en la computadora: el espacio extra va a más columnas, no a un
+«Administrar» más grande.
+
+D16 no alcanza al interruptor: es `sui-switch` `medium` fijo dentro del componente, aunque los
+switches sueltos vayan en `xlarge`/`large`. El badge interno arranca en `small`: pásalo como objeto
+con `size: bp.sizeBadge()`.
+
+En master-pedidos: `size={bp.sizeControl()}`. El `type` sigue por ancho
+(`bp.isMobile() ? 'vertical' : 'horizontal'`): es layout, no tamaño.
+
+## «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 (0 usos) | no hay integraciones (el tamaño para mobile ya existe: `large`, 04-10-2026) | conectar Culqi / Izipay o WhatsApp Business desde el panel del local (web primero) |
+| `vertical` · `list` | sin borde y en columna, el bloque se pierde | casi nunca: una sola integración destacada en una pantalla vacía |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `active` | `active` | `boolean` | `false` |
+| `appearance` | `appearance` | `"card" \| "list"` | `'card'` |
+| `badge` | `badge` | `SuiIntegrationBadgeConfig \| null \| string` | `null` |
+| `brandIcon` | `brand-icon` | `null \| string` | `null` |
+| `brandIconSrc` | `brand-icon-src` | `null \| string` | `null` |
+| `componentTitle` | `component-title` | `string` | `''` |
+| `description` | `description` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `manage` | `manage` | `SuiIntegrationManageConfig \| boolean \| null \| string` | `true` |
+| `showToggle` | `show-toggle` | `boolean` | `true` |
+| `size` | `size` | `"large" \| "medium"` | `'medium'` |
+| `type` | `type` | `"horizontal" \| "vertical"` | `'horizontal'` |
+
+| evento | `event.detail` |
+|---|---|
+| `activeChange` | `boolean` |
+| `manageClick` | `MouseEvent` |
+
+Slots: `brand`.
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Props solo de aquí:** `componentTitle`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `varios.administrar` | Administrar | `manage` |
+<!-- textos:fin -->
+
+```ts
+interface SuiIntegrationManageConfig { label?: string; icon?: string; }   // icon default 'settings-2-line'
+```
+
+Slot: `[sui-integration-brand]` (reemplaza al logo). Implementa `ControlValueAccessor`.
+
+## Trampas
+
+- **`manage` arranca en `true` y dice «Administrar»** (hasta el 03-10-2026 decía «Manage»). Sin
+  configuración, `manage="false"`.
+- **Es controlada**: `active` es input y `activeChange` solo avisa; sin actualizar tu señal el
+  interruptor no se mueve.
+- El estado se llama `active`, no `checked` (como en `sui-switch-label`).
+- El interruptor no cambia con `size`: siempre `sui-switch` `medium`. El `size` del componente (04-10-2026) solo agranda «Administrar».
+- En `vertical` el interruptor va arriba a la derecha y «Administrar» abajo a ancho completo.
+- `appearance="list"` no tiene borde ni fondo ni padding: va dentro de algo que los ponga.
+- El host borra el atributo `title` del DOM; el título se ve como texto, no como `aria-label`.
+  El interruptor toma su nombre de ese título (y su descripción de `description`) con
+  `aria-labelledby` (revisión 04-10-2026); antes el lector decía solo «interruptor».
+
+## Bien y mal
+
+La app no tiene usos todavía: los pares salen de «Cuándo usarlo» y de «Trampas».
+
+Un ajuste propio de la app
+
+```html
+<!-- ❌ mal: avisar de pedidos nuevos es un ajuste de la app, no un servicio externo -->
+<sui-integration-switch title="Notificaciones" brand-icon="notification-3-line"
+  manage="false" active={avisos()} onActiveChange={(e) => avisos.set(e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-switch-card label="Notificaciones" size={bp.controlSize()}
+  checked={avisos()} onCheckedChange={(e) => avisos.set(e.detail)} />
+```
+
+Servicio que solo se prende
+
+```html
+<!-- ❌ mal: manage arranca en true y pinta «Administrar» aunque no haya nada que configurar -->
+<sui-integration-switch title="Mapbox" brand-icon="map-2-line" size={bp.sizeControl()}
+  active={mapbox()} onActiveChange={(e) => mapbox.set(e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-integration-switch title="Mapbox" brand-icon="map-2-line" manage="false"
+  active={mapbox()} onActiveChange={(e) => mapbox.set(e.detail)} />
+```
+
+Integración nueva
+
+```html
+<!-- ❌ mal: el string sale naranja light y en small, que D16 no usa -->
+<sui-integration-switch title="Culqi" brand-icon="bank-card-line" badge="Nuevo" … />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-integration-switch title="Culqi" brand-icon="bank-card-line" size={bp.sizeControl()}
+  badge={{ label: 'Nuevo', color: 'purple', size: bp.sizeBadge() }} … />
+```
+
+## Ejemplo
+
+```html
+<sui-integration-switch
+  title="WhatsApp Business"
+  description="Avisa al cliente por WhatsApp cuando su pedido sale del local."
+  brand-icon-src="assets/brand/brand-logos/whatsapp-original.svg"
+  manage="Administrar"
+  active={whatsappActivo()}
+  onActiveChange={(e) => cambiarWhatsapp(e.detail)}
+  onManageClick={() => abrirAjustesWhatsapp()} />
+```