@moni-labs/moni-ui 0.4.4 → 0.4.5

package/docs/components/progress.md

@@ -0,0 +1,172 @@
+# Progress
+
+Material 3 Expressive progress indicator.
+
+- Tag: `moni-progress`
+- Clase: `MoniProgress`
+- Fuente: `src/components/moni-progress.ts`
+
+## Cuándo usarlo
+
+Usa `moni-progress` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```html
+<moni-progress></moni-progress>
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-progress label="Ejemplo"></moni-progress>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-progress` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- En formularios controlados, sincroniza la propiedad `value` y escucha el evento documentado; no dependas solo del atributo inicial.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `value` | `value` | `number` | `0` | Current progress value. |
+| `max` | `max` | `number` | `100` | Maximum progress value. |
+| `variant` | `variant` | `MoniProgressVariant` | `'linear'` | Visual indicator family. |
+| `size` | `size` | `MoniProgressSize` | `'medium'` | Current M3 size token. |
+| `indeterminate` | `indeterminate` | `boolean` | `false` | Shows the animated state used when progress cannot be measured. |
+| `mode` | `mode` | `MoniProgressMode` | `'determinate'` | Linear progress behavior. Buffer adds loaded and pending regions. |
+| `buffer-value` | `bufferValue` | `number` | `0` | Buffered progress value used when mode is buffer. |
+| `stop-indicator` | `stopIndicator` | `boolean` | `false` | Shows the optional 4px M3 stop indicator at the end of a linear track. |
+| `wave-transition` | `waveTransition` | `boolean` | `false` | Smoothly morphs wavy indicators to flat and back without changing progress. |
+| `aria-label` | `label` | `string` | `'Progress'` | Accessible name announced by assistive technology. |
+
+## Slots
+
+Este componente no declara slots públicos.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `buffer`: Parte interna personalizable.
+- `indicator`: Parte interna personalizable.
+- `progress`: Parte interna personalizable.
+- `stop-indicator`: Parte interna personalizable.
+- `svg`: Parte interna personalizable.
+- `track`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_active-color`
+- `--_active-end`
+- `--_buffer-end`
+- `--_buffer-gap-start`
+- `--_buffer-start`
+- `--_circular-size`
+- `--_gap`
+- `--_linear-height`
+- `--_stop`
+- `--_thickness`
+- `--_track-color`
+- `--active`
+- `--moni-progress-active`
+- `--moni-progress-track`
+- `--primary`
+- `--secondary-container`
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `value`
+
+Current progress value.
+
+![moni-progress — value=default](../assets/moni-progress/value--default.png)
+
+### `max`
+
+Maximum progress value.
+
+![moni-progress — max=default](../assets/moni-progress/max--default.png)
+
+### `variant`
+
+Visual indicator family.
+
+![moni-progress — variant=default](../assets/moni-progress/variant--default.png)
+
+### `size`
+
+Current M3 size token.
+
+![moni-progress — size=default](../assets/moni-progress/size--default.png)
+
+### `indeterminate`
+
+Shows the animated state used when progress cannot be measured.
+
+![moni-progress — indeterminate=false](../assets/moni-progress/indeterminate--false.png)
+
+![moni-progress — indeterminate=true](../assets/moni-progress/indeterminate--true.png)
+
+### `mode`
+
+Linear progress behavior. Buffer adds loaded and pending regions.
+
+![moni-progress — mode=default](../assets/moni-progress/mode--default.png)
+
+### `buffer-value`
+
+Buffered progress value used when mode is buffer.
+
+![moni-progress — buffer-value=default](../assets/moni-progress/bufferValue--default.png)
+
+### `stop-indicator`
+
+Shows the optional 4px M3 stop indicator at the end of a linear track.
+
+![moni-progress — stop-indicator=false](../assets/moni-progress/stopIndicator--false.png)
+
+![moni-progress — stop-indicator=true](../assets/moni-progress/stopIndicator--true.png)
+
+### `wave-transition`
+
+Smoothly morphs wavy indicators to flat and back without changing progress.
+
+![moni-progress — wave-transition=false](../assets/moni-progress/waveTransition--false.png)
+
+![moni-progress — wave-transition=true](../assets/moni-progress/waveTransition--true.png)
+
+### `aria-label`
+
+Accessible name announced by assistive technology.
+
+![moni-progress — aria-label=default](../assets/moni-progress/label--default.png)

package/docs/components/radio.md

@@ -0,0 +1,200 @@
+# Radio
+
+Componente Material Design 3 Radio Button (Botón de Opción).
+
+Los botones de opción permiten a los usuarios seleccionar exactamente un elemento de un conjunto de opciones
+mutuamente excluyentes. Comparten la misma arquitectura visual que
+`<moni-checkbox>` pero usan `type="radio"` e implementan la deselección de grupo.
+
+**Referencia a la especificación M3:** `m3-docs/components/radio/specs.md`
+
+**Arquitectura visual (Patrón BeerCSS):**
+Idéntico al patrón de checkbox: el `<input type="radio">` nativo ocupa
+espacio de diseño real a `--_size` × `--_size` pero se oculta mediante `opacity: 0`.
+Un `<span>` hermano renderiza:
+- `::before` — el icono de radio (`radio_button_unchecked` / `radio_button_checked`).
+- `::after`  — el anillo de onda (ripple) de hover/foco.
+
+**Deselección de grupo:**
+Cuando se marca un radio, `_onChange` consulta el `getRootNode()` del componente
+para encontrar todos los elementos `moni-radio` que comparten el mismo atributo `name` y establece
+su propiedad `checked` en `false`. Esto refleja el comportamiento nativo del navegador
+para grupos de radio a través de los límites del shadow DOM, donde la agrupación por `name` no
+funciona de forma nativa.
+
+- Tag: `moni-radio`
+- Clase: `MoniRadio`
+- Fuente: `src/components/moni-radio.ts`
+
+## Cuándo usarlo
+
+Usa `moni-radio` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```html
+<moni-radio name="color" value="red"   label="Rojo"></moni-radio>
+<moni-radio name="color" value="green" label="Verde"></moni-radio>
+<moni-radio name="color" value="blue"  label="Azul" checked></moni-radio>
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-radio label="Ejemplo"></moni-radio>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-radio` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- Durante una operación asíncrona combina el estado `loading` —si existe— con `disabled` para evitar envíos duplicados.
+- En formularios controlados, sincroniza la propiedad `value` y escucha el evento documentado; no dependas solo del atributo inicial.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `label` | `label` | `string` | `''` | Etiqueta de texto mostrada a la derecha del icono de radio.  Cuando no está vacía, se renderiza como un nodo de texto. Cuando está vacía, se renderiza la ranura (slot) por defecto, permitiendo contenido HTML en la ranura como etiqueta. |
+| `checked` | `checked` | `boolean` | `false` | Indica si este botón de opción está actualmente seleccionado.  Se refleja como un atributo para que los selectores CSS puedan apuntarlo. Se sincroniza con el input nativo a través de `updated()`. |
+| `disabled` | `disabled` | `boolean` | `false` | Cuando es `true`, el radio no es interactivo y se renderiza a un 50% de opacidad. |
+| `unchecked-icon` | `uncheckedIcon` | `string` | `''` | Material Symbol mostrado cuando el radio no está seleccionado. |
+| `checked-icon` | `checkedIcon` | `string` | `''` | Material Symbol mostrado cuando el radio está seleccionado. |
+| `icon-container` | `iconContainer` | `'circle' \| 'none'` | `'circle'` | Contenedor visual de los iconos personalizados. |
+| `size` | `size` | `'small' \| 'medium' \| 'large' \| 'extra'` | `'medium'` | Tamaño visual del icono de radio y su área de interacción (hit area) invisible.  \| Valor      \| `--_size` \| \|------------\|-----------\| \| `'small'`  \| 1rem      \| \| `'medium'` \| 1.5rem    \| \| `'large'`  \| 2rem      \| \| `'extra'`  \| 2.5rem    \| |
+| `name` | `name` | `string` | `''` | Nombre del grupo de radio. Los radios con el mismo `name` en el mismo nodo raíz se tratan como un grupo de exclusión mutua por `_onChange`.  Nota: Los grupos nativos de `<input type="radio">` solo funcionan dentro de la misma raíz de documento. Dado que `moni-radio` usa shadow DOM, la deselección de los hermanos se maneja imperativamente en `_onChange`. |
+| `value` | `value` | `string` | `''` | Se retransmite al atributo nativo `<input value>`. El valor enviado en un formulario cuando este radio es seleccionado. |
+
+## Slots
+
+Este componente no declara slots públicos.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `radio`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_size`
+- `--font`
+- `--font-icon`
+- `--on-primary`
+- `--on-surface`
+- `--on-surface-variant`
+- `--primary`
+- `--speed1`
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `label`
+
+Etiqueta de texto mostrada a la derecha del icono de radio.
+
+Cuando no está vacía, se renderiza como un nodo de texto. Cuando está vacía, se renderiza la ranura (slot)
+por defecto, permitiendo contenido HTML en la ranura como etiqueta.
+
+![moni-radio — label=default](../assets/moni-radio/label--default.png)
+
+### `checked`
+
+Indica si este botón de opción está actualmente seleccionado.
+
+Se refleja como un atributo para que los selectores CSS puedan apuntarlo. Se sincroniza con
+el input nativo a través de `updated()`.
+
+![moni-radio — checked=false](../assets/moni-radio/checked--false.png)
+
+![moni-radio — checked=true](../assets/moni-radio/checked--true.png)
+
+### `disabled`
+
+Cuando es `true`, el radio no es interactivo y se renderiza a un 50% de opacidad.
+
+![moni-radio — disabled=false](../assets/moni-radio/disabled--false.png)
+
+![moni-radio — disabled=true](../assets/moni-radio/disabled--true.png)
+
+### `unchecked-icon`
+
+Material Symbol mostrado cuando el radio no está seleccionado.
+
+![moni-radio — unchecked-icon=default](../assets/moni-radio/uncheckedIcon--default.png)
+
+### `checked-icon`
+
+Material Symbol mostrado cuando el radio está seleccionado.
+
+![moni-radio — checked-icon=default](../assets/moni-radio/checkedIcon--default.png)
+
+### `icon-container`
+
+Contenedor visual de los iconos personalizados.
+
+![moni-radio — icon-container=circle](../assets/moni-radio/iconContainer--circle.png)
+
+![moni-radio — icon-container=none](../assets/moni-radio/iconContainer--none.png)
+
+### `size`
+
+Tamaño visual del icono de radio y su área de interacción (hit area) invisible.
+
+| Valor      | `--_size` |
+|------------|-----------|
+| `'small'`  | 1rem      |
+| `'medium'` | 1.5rem    |
+| `'large'`  | 2rem      |
+| `'extra'`  | 2.5rem    |
+
+![moni-radio — size=small](../assets/moni-radio/size--small.png)
+
+![moni-radio — size=medium](../assets/moni-radio/size--medium.png)
+
+![moni-radio — size=large](../assets/moni-radio/size--large.png)
+
+![moni-radio — size=extra](../assets/moni-radio/size--extra.png)
+
+### `name`
+
+Nombre del grupo de radio. Los radios con el mismo `name` en el mismo nodo raíz
+se tratan como un grupo de exclusión mutua por `_onChange`.
+
+Nota: Los grupos nativos de `<input type="radio">` solo funcionan dentro de la misma
+raíz de documento. Dado que `moni-radio` usa shadow DOM, la deselección
+de los hermanos se maneja imperativamente en `_onChange`.
+
+![moni-radio — name=default](../assets/moni-radio/name--default.png)
+
+### `value`
+
+Se retransmite al atributo nativo `<input value>`.
+El valor enviado en un formulario cuando este radio es seleccionado.
+
+![moni-radio — value=default](../assets/moni-radio/value--default.png)

package/docs/components/ripple.md

@@ -0,0 +1,177 @@
+# Ripple
+
+Componente de decoración de onda (ripple) puramente visual.
+
+Proporciona una animación de onda con origen en el puntero: el círculo expansivo comienza
+en las coordenadas exactas donde se pulsó (pointer-down) en lugar de en el centro del elemento.
+Esta es la onda M3 de alta fidelidad; para una onda central más simple solo con CSS,
+usa el pseudo-elemento `.interactive::after` de `interactionStyles` en su lugar.
+
+**Uso:**
+Coloca `<moni-ripple>` como **hijo** de cualquier elemento interactivo. El componente
+adjunta automáticamente un listener de `pointerdown` a su `parentElement` y
+calcula el origen de la onda en coordenadas porcentuales relativas al padre.
+
+El elemento padre NO debe tener `position: static` (la onda aplica
+`position: relative` automáticamente en `connectedCallback`).
+
+**Modelo de tiempo:**
+En `pointerdown`:
+1. Se establece `active = false` (cancela cualquier onda en progreso).
+2. Un tick de `requestAnimationFrame` asegura que el navegador haya procesado el reinicio.
+3. `active = true` activa la animación de escala CSS.
+4. Un `setTimeout` de duración `duration` ms (basado en `speed`) reinicia `active = false`.
+
+La duración coincide con la duración de la transición CSS para que el desvanecimiento de la opacidad
+se complete antes de que se limpie `active`.
+
+**Limpieza (Cleanup):**
+`disconnectedCallback` elimina el listener de `pointerdown` y borra cualquier
+tiempo de espera (timeout) pendiente. Llama siempre a `super.disconnectedCallback()` si usas subclases.
+
+- Tag: `moni-ripple`
+- Clase: `MoniRipple`
+- Fuente: `src/components/moni-ripple.ts`
+
+## Cuándo usarlo
+
+Usa `moni-ripple` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```html
+<!-- Onda en un elemento personalizado -->
+<div class="my-button" style="position: relative; overflow: hidden;">
+  Haz clic
+  <moni-ripple color="primary"></moni-ripple>
+</div>
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-ripple></moni-ripple>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-ripple` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- Mantén el estado de apertura en una única fuente de verdad y devuelve el foco al disparador al cerrar.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `x` | `x` | `number` | `50` | Origen horizontal de la onda como porcentaje del ancho del padre.  Se establece automáticamente por `_onPointerDown` basándose en las coordenadas del puntero. Se puede configurar manualmente para activar una onda en una ubicación específica. |
+| `y` | `y` | `number` | `50` | Origen vertical de la onda como porcentaje de la altura del padre.  Se establece automáticamente por `_onPointerDown` basándose en las coordenadas del puntero. |
+| `active` | `active` | `boolean` | `false` | Cuando es `true`, la onda es visible y se está animando.  Alternado automáticamente por `_onPointerDown`. Se puede configurar manualmente para efectos de onda disparados programáticamente. |
+| `speed` | `speed` | `'fast' \| 'normal' \| 'slow'` | `'normal'` | Velocidad de animación de la secuencia de expansión y desvanecimiento de la onda.  Se asigna a la propiedad personalizada CSS `--_dur`: - `'fast'`   — 300ms - `'normal'` — 600ms (por defecto) - `'slow'`   — 1200ms |
+| `color` | `color` | `'primary' \| 'secondary' \| 'surface'` | `'primary'` | Token de color para la superposición de la onda.  Establece la propiedad CSS `color` en `:host`, que el span `.ripple` hereda a través de `background-color: currentColor`.  - `'primary'`   — `--primary` (por defecto) - `'secondary'` — `--secondary` - `'surface'`   — `--surface-variant` (sutil, para contenedores de superficie) |
+
+## Slots
+
+Este componente no declara slots públicos.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `ripple`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_dur`
+- `--_x`
+- `--_y`
+- `--primary`
+- `--secondary`
+- `--surface-variant`
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `x`
+
+Origen horizontal de la onda como porcentaje del ancho del padre.
+
+Se establece automáticamente por `_onPointerDown` basándose en las coordenadas del puntero.
+Se puede configurar manualmente para activar una onda en una ubicación específica.
+
+![moni-ripple — x=default](../assets/moni-ripple/x--default.png)
+
+### `y`
+
+Origen vertical de la onda como porcentaje de la altura del padre.
+
+Se establece automáticamente por `_onPointerDown` basándose en las coordenadas del puntero.
+
+![moni-ripple — y=default](../assets/moni-ripple/y--default.png)
+
+### `active`
+
+Cuando es `true`, la onda es visible y se está animando.
+
+Alternado automáticamente por `_onPointerDown`. Se puede configurar manualmente para
+efectos de onda disparados programáticamente.
+
+![moni-ripple — active=false](../assets/moni-ripple/active--false.png)
+
+![moni-ripple — active=true](../assets/moni-ripple/active--true.png)
+
+### `speed`
+
+Velocidad de animación de la secuencia de expansión y desvanecimiento de la onda.
+
+Se asigna a la propiedad personalizada CSS `--_dur`:
+- `'fast'`   — 300ms
+- `'normal'` — 600ms (por defecto)
+- `'slow'`   — 1200ms
+
+![moni-ripple — speed=fast](../assets/moni-ripple/speed--fast.png)
+
+![moni-ripple — speed=normal](../assets/moni-ripple/speed--normal.png)
+
+![moni-ripple — speed=slow](../assets/moni-ripple/speed--slow.png)
+
+### `color`
+
+Token de color para la superposición de la onda.
+
+Establece la propiedad CSS `color` en `:host`, que el span `.ripple`
+hereda a través de `background-color: currentColor`.
+
+- `'primary'`   — `--primary` (por defecto)
+- `'secondary'` — `--secondary`
+- `'surface'`   — `--surface-variant` (sutil, para contenedores de superficie)
+
+![moni-ripple — color=primary](../assets/moni-ripple/color--primary.png)
+
+![moni-ripple — color=secondary](../assets/moni-ripple/color--secondary.png)
+
+![moni-ripple — color=surface](../assets/moni-ripple/color--surface.png)

package/docs/components/segmented-button.md

@@ -0,0 +1,145 @@
+# Segmented Button
+
+Componente Material Design 3 Segmented Button (Botón Segmentado) (Heredado).
+
+Un grupo de botones segmentados seleccionables asociado a formularios.
+
+**Aviso de obsolescencia (Deprecation Notice):** La especificación M3 (`m3-docs/components/segmented-buttons/overview.md`)
+ha actualizado el patrón de botones segmentados. Los segmentos a medida han sido
+reemplazados por elementos estándar `<moni-button>` agrupados dentro de un
+`<moni-button-group variant="connected">`.
+
+Este componente sigue funcionando para mantener la compatibilidad con versiones anteriores, pero será
+eliminado en la v1.0. Se registra una advertencia de obsolescencia en la consola cuando el
+elemento se conecta al DOM.
+
+- Tag: `moni-segmented-button`
+- Clase: `MoniSegmentedButton`
+- Fuente: `src/components/moni-segmented-button.ts`
+
+## Cuándo usarlo
+
+Usa `moni-segmented-button` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```html
+<!-- Uso heredado (no recomendado) -->
+<moni-segmented-button name="view" multi>
+  <moni-button-segment value="day">Día</moni-button-segment>
+  <moni-button-segment value="week">Semana</moni-button-segment>
+</moni-segmented-button>
+
+<!-- Equivalente M3 moderno -->
+<moni-button-group variant="connected">
+  <moni-button>Día</moni-button>
+  <moni-button>Semana</moni-button>
+</moni-button-group>
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-segmented-button></moni-segmented-button>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-segmented-button` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `name` | `name` | `string` | `''` | Nombre del botón segmentado, usado para el envío del formulario. |
+| `multi` | `multi` | `boolean` | `false` | Permite seleccionar múltiples segmentos simultáneamente. |
+| `size` | `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge' \| 'extra'` | `'small'` | Tamaño de los segmentos del botón. |
+| `hide-check` | `hideCheck` | `boolean` | `false` | Oculta el icono de marca de verificación principal (leading checkmark) cuando se selecciona un segmento. |
+| `gap` | `gap` | `string` | `''` | Define un espaciado personalizado entre segmentos. |
+
+## Slots
+
+- `default`: elementos `<moni-button-segment>`.
+
+## Eventos
+
+- `change`: evento compuesto y burbujeante emitido por el componente.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `group`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+No consume variables CSS propias.
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `name`
+
+Nombre del botón segmentado, usado para el envío del formulario.
+
+![moni-segmented-button — name=default](../assets/moni-segmented-button/name--default.png)
+
+### `multi`
+
+Permite seleccionar múltiples segmentos simultáneamente.
+
+![moni-segmented-button — multi=false](../assets/moni-segmented-button/multi--false.png)
+
+![moni-segmented-button — multi=true](../assets/moni-segmented-button/multi--true.png)
+
+### `size`
+
+Tamaño de los segmentos del botón.
+
+![moni-segmented-button — size=xsmall](../assets/moni-segmented-button/size--xsmall.png)
+
+![moni-segmented-button — size=small](../assets/moni-segmented-button/size--small.png)
+
+![moni-segmented-button — size=medium](../assets/moni-segmented-button/size--medium.png)
+
+![moni-segmented-button — size=large](../assets/moni-segmented-button/size--large.png)
+
+![moni-segmented-button — size=xlarge](../assets/moni-segmented-button/size--xlarge.png)
+
+![moni-segmented-button — size=extra](../assets/moni-segmented-button/size--extra.png)
+
+### `hide-check`
+
+Oculta el icono de marca de verificación principal (leading checkmark) cuando se selecciona un segmento.
+
+![moni-segmented-button — hide-check=false](../assets/moni-segmented-button/hideCheck--false.png)
+
+![moni-segmented-button — hide-check=true](../assets/moni-segmented-button/hideCheck--true.png)
+
+### `gap`
+
+Define un espaciado personalizado entre segmentos.
+
+![moni-segmented-button — gap=default](../assets/moni-segmented-button/gap--default.png)