@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-slider/README.md

@@ -0,0 +1,240 @@
+---
+name: sui-slider
+selector: sui-slider
+resumen: Barra para elegir un valor, o un rango, dentro de una escala donde importa ver la posición
+alternativas: [sui-counter-input (cantidad chica y exacta con − y +), sui-input type="number" (valor exacto o rango abierto), sui-progress-bar (avance de solo lectura)]
+---
+
+# sui-slider
+
+<!-- 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-slider`); 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.
+
+Story: [Atoms/Slider](https://sui-design-system.web.app/?path=/docs/atoms-slider--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando el valor vive en una escala con mínimo y máximo y **ver dónde cae** ayuda a
+decidir: el radio de cobertura del repartidor en km, un rango de precios en un filtro, un
+porcentaje.
+
+**No lo uses** para:
+
+- Una cantidad chica y exacta (unidades, comensales): `sui-counter-input`.
+- Un valor exacto o sin tope (un monto, un DNI): `sui-input`.
+- Mostrar avance sin que se pueda mover: `sui-progress-bar`.
+- Dinero que se cobra: el arrastre no da precisión; va un `sui-input type="amount"`.
+
+Regla corta: **escala con tope y la posición importa → slider · número exacto → input · cantidad chica → counter.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como selección «precisa de un valor dentro de un rango»** y muestra
+> tres ejemplos: valor único, rango (dos manijas) y con tooltip. No dice cuándo va cada uno.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **1 uso**, `components/driver-coverage-modal/driver-coverage-modal.html:83` (radio de
+> cobertura, 1–15 km, con `label`, `amount` y `tooltip`). Más **1 `<input type="range">` nativo**.
+
+### `type`
+
+| type | cuándo | fuente |
+|---|---|---|
+| `single` (default) | Un valor: radio de cobertura, porcentaje. | según la guía del DS |
+| `range` | Un mínimo y un máximo en la misma escala: rango de precios de un filtro. Una sola barra con dos manijas, nunca dos sliders. | según la guía del DS (existe); el «cuándo», canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre que el slider no esté dentro de un campo que ya lo titula. Sin `label` desaparece toda la fila de arriba, `amount` incluido. | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `amount` | El valor con su unidad, a la derecha del label: «12 km», «S/ 10 – S/ 40». Sin `amount` escribe el número pelado. | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `sublabel` | Una precisión corta junto al label: «(máximo 15)». | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `tooltip` | Solo **sin** `amount`: el número flota sobre la manija mientras se arrastra. Con `amount` repite el valor y sin unidad. | según la guía del DS (existe); el «cuándo», canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `tooltipAlways` | No usar (ver abajo). | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `min` / `max` / `step` | La escala real del negocio (1–15 km, paso 1). | API |
+| `disabled` | La escala existe pero hoy no se puede mover (falta un dato antes). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `size` | `medium` (default, Figma): manija 16, riel 6, label 12/16. `large`: manija 24, riel 8, punto interno 8, label 14/20 — para mobile. | `medium`: según la guía del DS · `large`: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+**Usos de hoy que rompen la propuesta:**
+
+- **1 con `amount` y `tooltip` a la vez:** `components/driver-coverage-modal/driver-coverage-modal.html:83`
+  muestra «12 km» arriba y «12» flotando al arrastrar.
+- **El mismo uso va sin `size`** (`medium`: manija 16, riel 6) en una pantalla del repartidor, que
+  se usa en el teléfono: rompe la tabla de «Tamaño en mobile y en web» (`large` en mobile).
+- **1 nativo → `sui-slider`:** `components/image-cropper/image-cropper.html:57` (zoom del recorte).
+  A discutir: es un control de herramienta sin label, con botones − y + al lado.
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: el área táctil tiene que medir **44 px o más**. En web, con mouse,
+va un tamaño más chico. La app ya lo resuelve con `BreakpointsService`
+(`src/app/services/breakpoints.service.ts`, mobile = hasta 767 px). Regla del dueño, 03-10-2026.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| slider con label (radio de cobertura, filtro de precio) | `large` (manija 24, riel 8) | `medium` (manija 16, riel 6) | canon (aprobado por el dueño, 03-10-2026) |
+
+```html
+<!-- D16, dueño 05-10-2026: `large` en todo lo táctil, `medium` con mouse -->
+<sui-slider size={(bp.isMobile() || bp.toque()) ? 'large' : 'medium'} label="Radio de cobertura" amount="12 km"
+            min="1" max="15" value={radioKm} onValueChange={(e) => (radioKm = e.detail)} />
+```
+
+Toda la barra responde al toque (24 de alto en `large`), así que no hace falta acertarle a la
+manija. Igual la barra mide menos de 44: el slider necesita aire arriba y abajo en la fila. La
+manija en 0 o en 100 sobresale media manija (12 px en `large`) del borde de la barra: el
+contenedor tiene que tener margen lateral.
+
+### Por dispositivo (D16)
+
+Fila `slider` de la tabla D16 (dueño, 05-10-2026). A diferencia del botón o el campo, el slider **no** tiene la excepción
+«`medium` + área 44» en el celular chico: va `large` en todo lo que se toca.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `large` | manija 24, riel 8; con `medium` la manija de 16 es difícil de agarrar |
+| celular (380–767 px) | `large` | |
+| tablet táctil (`pointer: coarse`) | `large` | también se arrastra con el dedo |
+| computadora (`pointer: fine`) | `medium` | manija 16, riel 6 (el de la guía del DS) |
+
+Ultrawide (≥ 1920 px): igual que la computadora, `medium`.
+
+En master-pedidos: `size={(bp.isMobile() || bp.toque()) ? 'large' : 'medium'}`. No hay helper propio. Hoy da lo mismo que
+`bp.tactil()`, pero el servicio anuncia que `tactil` dejará fuera al celular chico cuando el DS estire el área de los
+`medium`, y el slider tiene que seguir en `large` ahí.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="range"` (0 usos) | ningún filtro de la app pide mínimo y máximo | un filtro de rango de precios o de distancia en la búsqueda del cliente |
+| `tooltipAlways` | un número fijo encima de la manija tapa el contenido de arriba y repite el `amount` | un slider sin `label` dentro de una herramienta (zoom del recorte), donde el número es lo único que orienta |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `amount` | `amount` | `null \| string` | `null` |
+| `ariaLabel` | `aria-label` | `null \| string` | `null` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `label` | `label` | `string` | `''` |
+| `max` | `max` | `number` | `100` |
+| `maxValue` | `max-value` | `number` | `0` |
+| `min` | `min` | `number` | `0` |
+| `minValue` | `min-value` | `number` | `0` |
+| `size` | `size` | `"large" \| "medium"` | `'medium'` |
+| `step` | `step` | `number` | `1` |
+| `sublabel` | `sublabel` | `string` | `''` |
+| `tooltip` | `tooltip` | `boolean` | `false` |
+| `tooltipAlways` | `tooltip-always` | `boolean` | `false` |
+| `type` | `type` | `"range" \| "single"` | `'single'` |
+| `unit` | `unit` | `null \| string` | `null` |
+| `value` | `value` | `number` | `0` |
+
+| evento | `event.detail` |
+|---|---|
+| `maxValueChange` | `number` |
+| `minValueChange` | `number` |
+| `valueChange` | `number` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- 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 |
+|---|---|---|
+| `deslizador.minimo` | mínimo | — |
+| `deslizador.maximo` | máximo | — |
+<!-- textos:fin -->
+
+Implementa `ControlValueAccessor` **solo para `single`**.
+
+## Trampas
+
+- **`label=""` borra toda la fila**, `amount` incluido. No hay forma de tener solo el valor.
+- **El tooltip va 28 px arriba de la manija**: deja aire arriba o queda cortado.
+- En `range`, `amount` vacío escribe «min–max» con guion largo; el formulario no lo cubre: usa
+  `minValue` + `minValueChange` y `maxValue` + `maxValueChange`.
+- Con `formControlName` ignora `value`. No mezcles las dos formas.
+- `value` es input + output (`value` + `valueChange` funciona), no un model.
+- El punto de la manija queda **gris** cuando el valor está en el mínimo: es a propósito.
+- Mide el ancho con el DOM: si arranca oculto (`display: none`, una pestaña cerrada) el arrastre
+  calcula mal hasta que se muestra.
+- Las flechas, Inicio y Fin lo mueven con teclado.
+- **Accesibilidad (04-10-2026)**: el `label` visible nombra la manija; sin label, pasa `ariaLabel`.
+  El lector lee el valor con su unidad: en single, el texto de `amount` («12 km»); en range (o sin
+  `amount`), el número + `unit`. En range cada manija se anuncia «<label>, mínimo» / «…, máximo».
+
+## Bien y mal
+
+**El valor arriba y flotando a la vez**
+
+```html
+<!-- ❌ mal: `amount` muestra «12 km» y el tooltip repite «12» sin unidad (components/driver-coverage-modal/driver-coverage-modal.html:83) -->
+<sui-slider label="Radio de cobertura" amount={radiusKm() + ' km'}
+            min={minKm} max={maxKm} tooltip
+            value={radiusKm()} onValueChange={(e) => onRadiusChange(e.detail)} />
+```
+
+```html
+<!-- ✅ bien: con `amount`, sin tooltip -->
+<sui-slider size={(bp.isMobile() || bp.toque()) ? 'large' : 'medium'}
+            label="Radio de cobertura" amount={radiusKm() + ' km'} min={minKm} max={maxKm}
+            value={radiusKm()} onValueChange={(e) => onRadiusChange(e.detail)} />
+```
+
+**El size en una pantalla del repartidor**
+
+```html
+<!-- ❌ mal: sin `size` sale `medium` (manija 16) en el teléfono (components/driver-coverage-modal/driver-coverage-modal.html:83) -->
+<sui-slider label="Radio de cobertura" amount={radiusKm() + ' km'} min={minKm} max={maxKm}
+            value={radiusKm()} onValueChange={(e) => onRadiusChange(e.detail)} />
+```
+
+```html
+<!-- ✅ bien: D16, `large` en todo lo táctil -->
+<sui-slider size={(bp.isMobile() || bp.toque()) ? 'large' : 'medium'}
+            label="Radio de cobertura" amount={radiusKm() + ' km'} min={minKm} max={maxKm}
+            value={radiusKm()} onValueChange={(e) => onRadiusChange(e.detail)} />
+```
+
+**Un mínimo y un máximo**
+
+```html
+<!-- ❌ mal: dos sliders sueltos para un rango; nada impide que el mínimo pase al máximo -->
+<sui-slider label="Precio mínimo" min="0" max="100" value={precioMin} onValueChange={(e) => (precioMin = e.detail)} />
+<sui-slider label="Precio máximo" min="0" max="100" value={precioMax} onValueChange={(e) => (precioMax = e.detail)} />
+```
+
+```html
+<!-- ✅ bien: una barra con dos manijas -->
+<sui-slider type="range" label="Precio" amount={'S/ ' + precioMin() + ' – S/ ' + precioMax()}
+            min="0" max="100" minValue={precioMin} onMinValueChange={(e) => (precioMin = e.detail)} maxValue={precioMax} onMaxValueChange={(e) => (precioMax = e.detail)} />
+```
+
+## Ejemplo
+
+```html
+<sui-slider
+  size={(bp.isMobile() || bp.toque()) ? 'large' : 'medium'}
+  label="Radio de cobertura"
+  amount={radioKm() + ' km'}
+  min="1" max="15" step="1"
+  value={radioKm()}
+  onValueChange={(e) => radioKm.set(e.detail)} />
+```

package/docs/sui-social-button/README.md

@@ -0,0 +1,253 @@
+---
+name: sui-social-button
+selector: sui-social-button
+resumen: Botón para iniciar sesión o registrarse con una cuenta de Google o Apple
+alternativas: [sui-button (cualquier otra acción, aunque mencione una marca), sui-app-store-badge (descargar la app de una tienda)]
+---
+
+# sui-social-button
+
+<!-- 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-social-button`); 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.
+
+Story: [Atoms/Button/Social Button](https://sui-design-system.web.app/?path=/docs/atoms-button-social-button--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** solo en las pantallas de iniciar sesión y registrarse, para entrar con una cuenta de
+otra marca: hoy Google y Apple.
+
+**No lo uses** para:
+
+- **Abrir WhatsApp, el mapa u otra app**: `sui-button` `filled` `neutral` con su ícono.
+- **Descargar la app**: `sui-app-store-badge`.
+- **Una marca sin login implementado** «para que se vea completo»: un botón que no hace nada es
+  peor que no tenerlo.
+
+## Qué variante usar
+
+> **La guía del DS no dice cuándo usar cada marca ni cada estilo.** Su página lo presenta como
+> «simplificar el inicio de sesión y el registro» y muestra las siete marcas en lleno y en borde,
+> sin do/don't. Las reglas de abajo son **canon (aprobado por el dueño, 03-10-2026)** salvo donde
+> dice otra fuente.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 5 social-buttons en 2 archivos, sin contar
+> prototipos ni vitrinas. Marcas: 2 `google`, 1 `apple`, 1 `x-twitter`, 1 `linkedin`. Estilos:
+> 4 `stroke`, 1 `filled`. 3 con `onlyIcon`, 3 con `loading`.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: simplificar el inicio de sesión y el registro.
+- **Defaults**: `apple` + `filled`. SUI también arranca en `filled`, pero `brand` es obligatorio.
+- **Siete marcas**: Apple, X (en la guía, `twitter`), Google, Facebook, LinkedIn, GitHub y Dropbox,
+  cada una en lleno (`filled`, el color de la marca) y en borde (`stroke`, fondo blanco y logo a
+  color). La guía llama `mode` a lo que SUI llama `variantStyle`.
+- **No trae `onlyIcon` ni `loading`**: el primero sale del Figma y el segundo es extensión de SUI.
+
+### `brand` + `variantStyle`
+
+| brand + estilo | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `google` + `stroke` | Iniciar sesión o registrarse con Google: fondo blanco, logo a color. | `pages/auth/login/login.html:39` («Continuar con Google») | canon (aprobado por el dueño, 03-10-2026) |
+| `apple` + `filled` | Iniciar sesión con Apple: negro lleno, como pide Apple. | `pages/auth/login/login.html:50` («Continuar con Apple») | canon (aprobado por el dueño, 03-10-2026) |
+| `google` + `filled` (rojo) | No: el botón de Google va en blanco. Es lo que sale si se olvida `variantStyle`. | — | canon (aprobado por el dueño, 05-10-2026, bloque B3) |
+| `apple` + `stroke` | No: Apple va negro lleno en tema claro. | — | canon (aprobado por el dueño, 05-10-2026, bloque B3) |
+| `facebook`, `x-twitter`, `linkedin`, `github`, `dropbox` (cualquier estilo) | No hay login con esas cuentas. | — | no usar · canon (aprobado por el dueño, 03-10-2026) |
+
+### `onlyIcon`
+
+| onlyIcon | cuándo | fuente |
+|---|---|---|
+| `false` (default) | Siempre en el login: logo + «Continuar con …». | canon (aprobado por el dueño, 03-10-2026) |
+| `true` | No: Apple exige el texto en su botón de login. | no usar · canon (aprobado por el dueño, 03-10-2026) |
+
+**Usos de hoy que rompen la regla:**
+
+- **3 casos, todos en `pages/auth/register/register.html`**: `:86` (`x-twitter`), `:87` (`google`) y
+  `:94` (`linkedin`), los tres con `onlyIcon`. X y LinkedIn además están deshabilitados porque no
+  hay login con esas cuentas (el comentario del HTML lo dice: son decorativos). Pasar a lo mismo que
+  el login: `google` `stroke` con texto (y `apple` `filled` si el registro ofrece Apple), y quitar
+  X y LinkedIn.
+
+### `label`, `loading`, `disabled`, `href`
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Sin pasarlo sale «Continuar con Google» / «Continuar con Apple», que sirve igual para entrar y para registrarse. Pasarlo solo si el texto tiene que decir otra cosa. | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `loading` | Desde el toque hasta que vuelve la ventana de la marca: cambia el logo por un spinner y deshabilita el botón. | canon (aprobado por el dueño, 05-10-2026, bloque B8); ya es la práctica del login |
+| `disabled` | Mientras otro login está en curso, para que no se abran dos (en el login: `processingRedirect`). Nunca para una marca que no tiene login. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `href` | Solo si el login se hace navegando a una URL (OAuth por redirect web). Pinta un `<a>`. | canon (aprobado por el dueño, 05-10-2026, bloque B10) |
+| `ariaLabel` | No hace falta: con texto se lee el texto; con `onlyIcon` el componente usa el label. | canon (aprobado por el dueño, 05-10-2026, bloque B5) |
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: el área táctil tiene que medir **44 px o más** (canon (dueño, 04-10-2026): piso táctil 44 en el teléfono). En web,
+con mouse, va un tamaño más chico. La app ya lo resuelve con `BreakpointsService`
+(`src/app/services/breakpoints.service.ts`, mobile = hasta 767 px).
+
+| size | alto | texto | solo ícono | fuente |
+|---|---|---|---|---|
+| `large` | 48 | 16 (Label/Medium) | 48 × 48 | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono. Size nuevo del 04-10-2026 |
+| `medium` (default) | 40 | 14 | 40 × 40 | Figma |
+
+**Por qué `large` = 48 y no 44**: el social-button es «el mismo botón con otro acabado» que
+`sui-button` y su único tamaño (40) es el `medium` de sui-button. El siguiente de esa escala es
+`large`, que mide 48: en el login queda del mismo alto que el CTA de al lado. El texto sube a 16
+(regla de tamaños del 03-10-2026); el logo sigue en 20.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| login con Google o Apple | `large` (48), **ancho completo** (`width: 100%`) | `medium` (40), ancho del formulario | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono (alto) · ancho: canon (aprobado por el dueño, 05-10-2026, bloque B1; es lo que ya hace `pages/auth/login/login.html` con `.auth-page__provider-btn`) |
+
+```html
+<sui-social-button brand="google" variant-style="stroke" style="width: 100%"
+                   size={bp.sizeControl()} onClicked={() => loginGoogle()} />   <!-- D16, dueño 05-10-2026 -->
+```
+
+**Ancho completo**: `width: 100%` en el host estira el botón (arreglado en el DS el 03-10-2026 con
+`flex: 1 1 auto` en `.sui-social-button__el`; antes el host medía 360 y el botón 193). Sin
+`width` sigue midiendo lo que su texto, como siempre. Con `onlyIcon` el cuadrado (40 o 48) no se
+estira nunca. El host sigue siendo `inline-flex`: para el ancho completo va `width: 100%`, no
+`display: block`. El `::ng-deep .sui-social-button__el { width: 100% }` de
+`pages/auth/auth-shared.scss` queda de más con la versión que trae el arreglo.
+
+No se estira el alto con CSS desde afuera: el logo y el padding no escalan. Para el teléfono va
+`size="large"`.
+
+### Por dispositivo (D16)
+
+Fila `social-button` de la tabla D16 (dueño, 05-10-2026), la misma que `sui-button`.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `large` (48) | interino: D16 pide `medium` con área tocable de 44; hasta que el DS la estire, se queda el grande (nota ¹ de D16) |
+| celular (380–767 px) | `large` (48) | ancho completo, del mismo alto que el CTA de al lado |
+| tablet táctil (`pointer: coarse`) | `large` (48) | con `bp.isMobile()` el iPad quedaba en `medium` 40 |
+| computadora (`pointer: fine`) | `medium` (40) | |
+
+Ultrawide (≥ 1920 px): igual que la computadora, `medium`; el formulario de login no se ensancha.
+
+En master-pedidos: `size={bp.sizeControl()}`, el mismo helper que `sui-button` (devuelve `'large' | 'medium'`, los dos
+sizes que tiene el componente). Hoy los 5 usos van con `bp.isMobile() ? 'large' : 'medium'`
+(`pages/auth/login/login.html:39` y `:50`, `pages/auth/register/register.html:86`, `:87` y `:94`): se migran.
+
+## «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 |
+|---|---|---|
+| `facebook`, `x-twitter`, `linkedin`, `github`, `dropbox` | no hay login con esas cuentas | si se agrega «Continuar con Facebook» (muy usado en Perú) o botones de compartir en redes |
+| `onlyIcon` | Apple exige el texto en su botón de login | una fila de «compartir en» con íconos de redes, fuera del login |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `ariaLabel` | `aria-label` | `null \| string` | `null` |
+| `brand` | `brand` | `"apple" \| "dropbox" \| "facebook" \| "github" \| "google" \| "linkedin" \| "x-twitter"` | — (requerido) |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `href` | `href` | `null \| string` | `null` |
+| `label` | `label` | `null \| string` | `null` |
+| `loading` | `loading` | `boolean` | `false` |
+| `onlyIcon` | `only-icon` | `boolean` | `false` |
+| `rel` | `rel` | `null \| string` | `'noopener noreferrer'` |
+| `size` | `size` | `"large" \| "medium"` | `'medium'` |
+| `target` | `target` | `null \| string` | `null` |
+| `type` | `type` | `"button" \| "reset" \| "submit"` | `'button'` |
+| `variantStyle` | `variant-style` | `"filled" \| "stroke"` | `'filled'` |
+
+| evento | `event.detail` |
+|---|---|
+| `clicked` | `MouseEvent` |
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- 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.continuarCon` | Continuar con {marca} | `label` |
+<!-- textos:fin -->
+
+## Trampas
+
+- **`brand` es obligatorio** y **`variantStyle` arranca en `filled`**: `<sui-social-button brand="google" />`
+  sale rojo lleno. Para el login de Google hay que pasar `variantStyle="stroke"`.
+- **El estilo se llama `variantStyle`** (en la guía, `mode`) y **X se llama `x-twitter`** (en la
+  guía, `twitter`).
+- **`size` va de `medium` (40, default) a `large` (48, para el teléfono, 04-10-2026).** Con `width: 100%` en el host el botón se estira al ancho completo (arreglado en el DS el 03-10-2026; antes no estiraba). El de solo ícono queda en 40 × 40 (48 × 48 en `large`).
+- **`loading` también deshabilita**: no emite `clicked` mientras está en `true`.
+- El logo es una imagen distinta por tema: en modo oscuro, Apple, X y GitHub en `stroke` usan el
+  logo blanco para no perderse. El componente lo resuelve solo leyendo `data-theme`.
+- El radio es 10 px, no pill como `sui-button`.
+- El output es `clicked`.
+- Ya trae el arreglo de iOS para el `:active` pegado: no lo agregues.
+
+## Bien y mal
+
+**Google sin estilo**
+
+```html
+<!-- ❌ mal: `variantStyle` arranca en `filled` y el botón de Google sale rojo lleno -->
+<sui-social-button brand="google" size={bp.sizeControl()} onClicked={() => entrarConGoogle()} />
+```
+
+```html
+<!-- ✅ bien: Google en blanco con logo a color -->
+<sui-social-button brand="google" variant-style="stroke" size={bp.sizeControl()} onClicked={() => entrarConGoogle()} />
+```
+
+**La fila de marcas en el registro**
+
+```html
+<!-- ❌ mal: solo ícono y dos marcas sin login, deshabilitadas de adorno (pages/auth/register/register.html:86-94) -->
+<sui-social-button brand="x-twitter" variant-style="stroke" only-icon disabled />
+<sui-social-button brand="google" variant-style="stroke" only-icon onClicked={() => onGoogleRegister()} />
+<sui-social-button brand="linkedin" variant-style="stroke" only-icon disabled />
+```
+
+```html
+<!-- ✅ bien: lo mismo que el login, con texto y solo las marcas que tienen login -->
+<sui-social-button brand="google" variant-style="stroke" size={bp.sizeControl()}
+                   style="width: 100%" loading={loading()} onClicked={() => onGoogleRegister()} />
+```
+
+**El size por dispositivo**
+
+```html
+<!-- ❌ mal: solo mira el ancho; en el iPad (≥ 768, táctil) queda en `medium` 40 (pages/auth/login/login.html:39) -->
+<sui-social-button brand="google" variant-style="stroke"
+                   size={bp.isMobile() ? 'large' : 'medium'} onClicked={() => entrarConGoogle()} />
+```
+
+```html
+<!-- ✅ bien: el helper de D16 -->
+<sui-social-button brand="google" variant-style="stroke"
+                   size={bp.sizeControl()} onClicked={() => entrarConGoogle()} />
+```
+
+## Ejemplo
+
+```html
+<!-- Login: Google en blanco, Apple negro lleno, los dos con texto -->
+<sui-social-button brand="google" variant-style="stroke" size={bp.sizeControl()} loading={cargandoGoogle()}
+                   disabled={procesando()} onClicked={() => entrarConGoogle()} />
+<sui-social-button brand="apple" variant-style="filled" size={bp.sizeControl()} loading={cargandoApple()}
+                   disabled={procesando()} onClicked={() => entrarConApple()} />
+```