@moni-labs/moni-ui 0.4.4 → 0.4.6

package/docs/components/color-field.md

@@ -0,0 +1,195 @@
+# Color Field
+
+Componente Material Design 3 Color Field (Campo de Color).
+
+Un campo de texto especializado para la entrada de color que combina un
+`<input type="color">` nativo con una visualización de texto de solo lectura del
+valor hexadecimal seleccionado, envuelto en la carcasa estándar de campo M3.
+
+**Arquitectura visual:**
+Extiende el patrón de estilo de campo usado por `<moni-text-field>`. El
+slot de icono inicial se reemplaza por una muestra de color circular (`.swatch`)
+que se posiciona absolutamente sobre una entrada de color nativa invisible.
+Al hacer clic en la muestra se abre el selector de color del sistema. La parte de entrada de texto
+muestra el código hexadecimal seleccionado y es estrictamente `readOnly`.
+
+**Sincronización de estado:**
+El componente escucha el evento nativo `change` en la entrada de color,
+actualiza la propiedad `value`, y re-despacha un evento compuesto `'change'`.
+No escucha `input` (arrastre continuo en el selector de color) para evitar
+el disparo excesivo de eventos, pero los consumidores pueden adjuntar sus propios
+escuchas de `input` directamente al elemento si se necesita una vista previa en vivo.
+
+- Tag: `moni-color-field`
+- Clase: `MoniColorField`
+- Fuente: `src/components/moni-color-field.ts`
+
+## Cuándo usarlo
+
+Usa `moni-color-field` 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-color-field
+  label="Color del Tema"
+  name="primaryColor"
+  value="#6750a4"
+  variant="outlined"
+></moni-color-field>
+```
+
+## 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-color-field label="Ejemplo"></moni-color-field>
+</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-color-field` 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 |
+|---|---|---|---|---|
+| `name` | `name` | `string` | `''` | El nombre del input, enviado con los datos del formulario. |
+| `label` | `label` | `string` | `''` | El texto de la etiqueta flotante. |
+| `variant` | `variant` | `'filled' \| 'outlined'` | `'outlined'` | Variante visual del campo de texto. |
+| `size` | `size` | `'small' \| 'medium' \| 'large' \| 'extra'` | `'medium'` | Define las dimensiones del campo de texto. |
+| `shape` | `shape` | `'round' \| 'square' \| 'no-round'` | `'no-round'` | Forma del radio del borde del campo. |
+| `disabled` | `disabled` | `boolean` | `false` | Deshabilita el campo de color. |
+| `helper` | `helper` | `string` | `''` | Texto de ayuda mostrado debajo del campo. |
+| `error-text` | `errorText` | `string` | `''` | Texto de error mostrado debajo del campo cuando `error` es true. Sobrescribe el texto de ayuda. |
+| `error` | `error` | `boolean` | `false` | Si es true, establece el campo en un estado de error. |
+| `value` | `value` | `string` | `'#6750a4'` | El valor actual del color hexadecimal. |
+
+## 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
+
+- `field`: Parte interna personalizable.
+- `swatch`: El elemento de vista previa de color circular.
+- `input-color`: El `<input type="color">` nativo, visualmente oculto.
+- `input-text`: El `<input type="text">` nativo que muestra el código hexadecimal.
+- `label`: Parte interna personalizable.
+- `color`: Parte interna personalizable.
+- `helper`: Parte interna personalizable.
+- `text`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_swatch`
+- `--outline`
+
+## 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`
+
+El nombre del input, enviado con los datos del formulario.
+
+![moni-color-field — name=default](../assets/moni-color-field/name--default.png)
+
+### `label`
+
+El texto de la etiqueta flotante.
+
+![moni-color-field — label=default](../assets/moni-color-field/label--default.png)
+
+### `variant`
+
+Variante visual del campo de texto.
+
+![moni-color-field — variant=filled](../assets/moni-color-field/variant--filled.png)
+
+![moni-color-field — variant=outlined](../assets/moni-color-field/variant--outlined.png)
+
+### `size`
+
+Define las dimensiones del campo de texto.
+
+![moni-color-field — size=small](../assets/moni-color-field/size--small.png)
+
+![moni-color-field — size=medium](../assets/moni-color-field/size--medium.png)
+
+![moni-color-field — size=large](../assets/moni-color-field/size--large.png)
+
+![moni-color-field — size=extra](../assets/moni-color-field/size--extra.png)
+
+### `shape`
+
+Forma del radio del borde del campo.
+
+![moni-color-field — shape=round](../assets/moni-color-field/shape--round.png)
+
+![moni-color-field — shape=square](../assets/moni-color-field/shape--square.png)
+
+![moni-color-field — shape=no-round](../assets/moni-color-field/shape--no-round.png)
+
+### `disabled`
+
+Deshabilita el campo de color.
+
+![moni-color-field — disabled=false](../assets/moni-color-field/disabled--false.png)
+
+![moni-color-field — disabled=true](../assets/moni-color-field/disabled--true.png)
+
+### `helper`
+
+Texto de ayuda mostrado debajo del campo.
+
+![moni-color-field — helper=default](../assets/moni-color-field/helper--default.png)
+
+### `error-text`
+
+Texto de error mostrado debajo del campo cuando `error` es true.
+Sobrescribe el texto de ayuda.
+
+![moni-color-field — error-text=default](../assets/moni-color-field/errorText--default.png)
+
+### `error`
+
+Si es true, establece el campo en un estado de error.
+
+![moni-color-field — error=false](../assets/moni-color-field/error--false.png)
+
+![moni-color-field — error=true](../assets/moni-color-field/error--true.png)
+
+### `value`
+
+El valor actual del color hexadecimal.
+
+![moni-color-field — value=default](../assets/moni-color-field/value--default.png)

package/docs/components/context-menu.md

@@ -0,0 +1,132 @@
+# Context Menu
+
+Componente Material Design 3 Context Menu (Menú Contextual).
+
+Un menú especializado que se abre en las coordenadas exactas de un evento de puntero,
+típicamente desencadenado por un clic derecho (evento `contextmenu`). Proporciona
+acciones contextuales relacionadas con el elemento específico clicado.
+
+**Referencia de la especificación M3:** `m3-docs/components/menus/specs.md` (Menús contextuales)
+
+**Mecanismo de activación:**
+El componente no requiere activación programática a través de una propiedad `open`.
+En su lugar, adjunta un detector de eventos `contextmenu` a su elemento padre
+durante `connectedCallback`. Cuando se hace clic derecho en el padre, el menú
+captura las coordenadas `clientX`/`clientY`, previene el menú contextual predeterminado
+del navegador, y se abre en la posición del cursor usando `position: fixed`.
+
+**Comportamiento de auto-inversión (atributo `flip`):**
+Según las pautas de M3, los menús deben invertirse al lado opuesto del cursor
+si al abrirse en la `placement` solicitada causarían un desbordamiento de la
+ventana gráfica. Cuando `flip=true`, el componente calcula dinámicamente los límites
+de la ventana antes de abrir y anula `placement` si es necesario (ej., invirtiendo
+de `bottom` a `top` si se hace clic cerca de la parte inferior de la pantalla).
+
+**Auto-descarte:**
+Se cierra automáticamente al hacer clic en cualquier lugar fuera del menú, o al
+presionar la tecla `Escape`.
+
+- Tag: `moni-context-menu`
+- Clase: `MoniContextMenu`
+- Fuente: `src/components/moni-context-menu.ts`
+
+## Cuándo usarlo
+
+Usa `moni-context-menu` 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
+<!-- Envuelve el área de activación y el menú en un contenedor -->
+<div>
+  <p>Haz clic derecho para ver las opciones</p>
+  <moni-context-menu flip>
+    <moni-menu-item>Copiar</moni-menu-item>
+    <moni-menu-item>Pegar</moni-menu-item>
+    <moni-divider></moni-divider>
+    <moni-menu-item>Eliminar</moni-menu-item>
+  </moni-context-menu>
+</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-context-menu></moni-context-menu>
+</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-context-menu` 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 |
+|---|---|---|---|---|
+| `placement` | `placement` | `'bottom' \| 'top' \| 'left' \| 'right'` | `'bottom'` | Selecciona el valor de `placement` entre las opciones documentadas. |
+| `flip` | `flip` | `boolean` | `false` | Activa o desactiva el comportamiento `flip`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+
+## Slots
+
+- `default`: Los elementos `<moni-menu-item>` que componen el menú.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+No declara CSS Parts.
+
+## CSS Custom Properties consumidas
+
+- `--_x`
+- `--_y`
+- `--font`
+
+## 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.
+
+### `placement`
+
+Selecciona el valor de `placement` entre las opciones documentadas.
+
+![moni-context-menu — placement=bottom](../assets/moni-context-menu/placement--bottom.png)
+
+![moni-context-menu — placement=top](../assets/moni-context-menu/placement--top.png)
+
+![moni-context-menu — placement=left](../assets/moni-context-menu/placement--left.png)
+
+![moni-context-menu — placement=right](../assets/moni-context-menu/placement--right.png)
+
+### `flip`
+
+Activa o desactiva el comportamiento `flip`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-context-menu — flip=false](../assets/moni-context-menu/flip--false.png)
+
+![moni-context-menu — flip=true](../assets/moni-context-menu/flip--true.png)

package/docs/components/dialog.md

@@ -0,0 +1,193 @@
+# Dialog
+
+Componente Material Design 3 Dialog (Diálogo).
+
+Los diálogos informan a los usuarios sobre una tarea y pueden contener información crítica,
+requerir decisiones o implicar múltiples tareas. Interrumpen el flujo de trabajo del
+usuario y deben usarse con moderación.
+
+**Referencia de la especificación M3:** `m3-docs/components/dialogs/specs.md`
+
+**Nota de implementación — elemento nativo `<dialog>`:**
+Este componente envuelve el elemento HTML nativo `<dialog>`. La apertura y cierre
+se controlan mediante el atributo `open` (y su propiedad JS). El componente
+sincroniza los cambios de `open` al `<dialog>` nativo en `updated()`:
+- `modal=true` → llama a `dialog.showModal()` (bloquea el foco, añade fondo oscuro).
+- `modal=false` → llama a `dialog.show()` (no bloquea, sin fondo oscuro).
+- `open=false` → llama a `dialog.close()`.
+
+**Colocación (atributo `side`):**
+- `center` (por defecto) — Centrado en la ventana gráfica. Diálogo M3 estándar.
+- `top`, `right`, `bottom`, `left` — Paneles anclados a los bordes (patrón side sheet).
+- `max` — Diálogo a pantalla completa para flujos complejos.
+
+- Tag: `moni-dialog`
+- Clase: `MoniDialog`
+- Fuente: `src/components/moni-dialog.ts`
+
+## Cuándo usarlo
+
+Usa `moni-dialog` 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
+<!-- Diálogo modal básico -->
+<moni-dialog open modal title="Eliminar elemento?" size="small">
+  <p>Esta acción no se puede deshacer.</p>
+  <div slot="footer">
+    <moni-button variant="text">Cancelar</moni-button>
+    <moni-button>Eliminar</moni-button>
+  </div>
+</moni-dialog>
+```
+
+## 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-dialog></moni-dialog>
+</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-dialog` 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 |
+|---|---|---|---|---|
+| `open` | `open` | `boolean` | `false` | Controla el estado abierto/cerrado del diálogo.  Cuando se establece en `true`, el componente llama a `dialog.showModal()` (si `modal`) o `dialog.show()`. Cuando se establece en `false`, llama a `dialog.close()`. Reflejado como un atributo HTML para CSS y lectores de estado externos. |
+| `modal` | `modal` | `boolean` | `false` | Cuando es `true`, abre el diálogo como un modal usando `<dialog>.showModal()`.  Diálogos modales: - Bloquean que el foco del teclado salga del diálogo. - Renderizan una capa `::backdrop` sobre el resto de la página. - Se pueden cerrar presionando `Escape` (comportamiento nativo del navegador).  Cuando es `false`, usa `<dialog>.show()` que no es bloqueante (sin trampa de foco y sin capa de fondo). |
+| `side` | `side` | `'center' \| 'top' \| 'right' \| 'bottom' \| 'left' \| 'max'` | `'center'` | Colocación del diálogo dentro de la ventana gráfica.  - `'center'` (por defecto) — Centrado. Colocación de diálogo M3 estándar. - `'top'`    — Anclado al borde superior (cajón desde arriba). - `'right'`  — Anclado al borde derecho (patrón de hoja lateral). - `'bottom'` — Anclado al borde inferior (alternativa de hoja inferior). - `'left'`   — Anclado al borde izquierdo (patrón de cajón de navegación). - `'max'`    — Pantalla completa (cubre toda la ventana gráfica). |
+| `size` | `size` | `'small' \| 'medium' \| 'large'` | `'medium'` | Tamaño del contenedor del diálogo.  - `'small'`  — Diálogo estrecho; ideal para confirmaciones simples. - `'medium'` — Ancho de diálogo estándar (por defecto). - `'large'`  — Diálogo ancho; para formularios o contenido complejo. |
+| `title` | `title` | `string` | `''` | Texto mostrado en el área del encabezado del diálogo.  Cuando no está vacío, se renderiza como un encabezado estilizado dentro del contenedor del encabezado. El slot `header` tiene prioridad sobre este atributo cuando ambos están presentes. |
+
+## Slots
+
+- `default`: El contenido del cuerpo del diálogo.
+- `header`: Contenido personalizado del encabezado (sobrescribe el atributo `title`).
+- `footer`: Fila de botones de acción en la parte inferior del diálogo.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `dialog`: Parte interna personalizable.
+- `header`: Parte interna personalizable.
+- `body`: El envoltorio del contenido del cuerpo.
+- `footer`: Parte interna personalizable.
+- `content`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_bottom`
+- `--_padding`
+- `--_top`
+- `--elevate2`
+- `--moni-dialog-scale`
+- `--on-surface`
+- `--speed3`
+- `--surface`
+- `--surface-container-high`
+
+## 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.
+
+### `open`
+
+Controla el estado abierto/cerrado del diálogo.
+
+Cuando se establece en `true`, el componente llama a `dialog.showModal()` (si `modal`)
+o `dialog.show()`. Cuando se establece en `false`, llama a `dialog.close()`.
+Reflejado como un atributo HTML para CSS y lectores de estado externos.
+
+![moni-dialog — open=true](../assets/moni-dialog/open--true.png)
+
+### `modal`
+
+Cuando es `true`, abre el diálogo como un modal usando `<dialog>.showModal()`.
+
+Diálogos modales:
+- Bloquean que el foco del teclado salga del diálogo.
+- Renderizan una capa `::backdrop` sobre el resto de la página.
+- Se pueden cerrar presionando `Escape` (comportamiento nativo del navegador).
+
+Cuando es `false`, usa `<dialog>.show()` que no es bloqueante (sin trampa de foco
+y sin capa de fondo).
+
+![moni-dialog — modal=false](../assets/moni-dialog/modal--false.png)
+
+![moni-dialog — modal=true](../assets/moni-dialog/modal--true.png)
+
+### `side`
+
+Colocación del diálogo dentro de la ventana gráfica.
+
+- `'center'` (por defecto) — Centrado. Colocación de diálogo M3 estándar.
+- `'top'`    — Anclado al borde superior (cajón desde arriba).
+- `'right'`  — Anclado al borde derecho (patrón de hoja lateral).
+- `'bottom'` — Anclado al borde inferior (alternativa de hoja inferior).
+- `'left'`   — Anclado al borde izquierdo (patrón de cajón de navegación).
+- `'max'`    — Pantalla completa (cubre toda la ventana gráfica).
+
+![moni-dialog — side=center](../assets/moni-dialog/side--center.png)
+
+![moni-dialog — side=top](../assets/moni-dialog/side--top.png)
+
+![moni-dialog — side=right](../assets/moni-dialog/side--right.png)
+
+![moni-dialog — side=bottom](../assets/moni-dialog/side--bottom.png)
+
+![moni-dialog — side=left](../assets/moni-dialog/side--left.png)
+
+![moni-dialog — side=max](../assets/moni-dialog/side--max.png)
+
+### `size`
+
+Tamaño del contenedor del diálogo.
+
+- `'small'`  — Diálogo estrecho; ideal para confirmaciones simples.
+- `'medium'` — Ancho de diálogo estándar (por defecto).
+- `'large'`  — Diálogo ancho; para formularios o contenido complejo.
+
+![moni-dialog — size=small](../assets/moni-dialog/size--small.png)
+
+![moni-dialog — size=medium](../assets/moni-dialog/size--medium.png)
+
+![moni-dialog — size=large](../assets/moni-dialog/size--large.png)
+
+### `title`
+
+Texto mostrado en el área del encabezado del diálogo.
+
+Cuando no está vacío, se renderiza como un encabezado estilizado dentro del contenedor del encabezado.
+El slot `header` tiene prioridad sobre este atributo cuando ambos están presentes.
+
+![moni-dialog — title=default](../assets/moni-dialog/title--default.png)

package/docs/components/divider.md

@@ -0,0 +1,123 @@
+# Divider
+
+Componente Material Design 3 Divider (Separador).
+
+Una regla delgada horizontal (o vertical) utilizada para separar visualmente secciones
+de contenido dentro de listas, diseños y tarjetas.
+
+**Referencia de la especificación M3:** `m3-docs/components/divider/specs.md`
+
+**Medidas M3:**
+- Grosor: 1dp (`0.0625rem`).
+- Color: `outline-variant` — sutil en todos los fondos de superficie.
+- Las variantes insertadas (inset) alinean la línea con el contenido de la lista:
+  - `leading` — margen de 16dp desde el borde inicial (se alinea con el texto del icono).
+  - `middle`  — margen de 16dp en ambos bordes.
+  - `none`    — sangría completa (sin margen).
+
+**Uso vertical:**
+Aunque todavía no se expone como un atributo, el selector de atributos CSS `[vertical]`
+está soportado. Establezca `vertical` como un atributo HTML para renderizar un separador
+vertical de 1dp de ancho que se estira para coincidir con el eje transversal de su contenedor flex.
+
+- Tag: `moni-divider`
+- Clase: `MoniDivider`
+- Fuente: `src/components/moni-divider.ts`
+
+## Cuándo usarlo
+
+Usa `moni-divider` 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
+<!-- Separador de sangría completa entre secciones -->
+<moni-divider inset="none"></moni-divider>
+
+<!-- Separador de inserción inicial en una lista (se alinea con el texto del elemento de lista) -->
+<moni-divider></moni-divider>
+
+<!-- Separador vertical dentro de un contenedor flex -->
+<div style="display:flex; height: 3rem; align-items:center; gap: 1rem;">
+  <span>Sección A</span>
+  <moni-divider vertical></moni-divider>
+  <span>Sección B</span>
+</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-divider></moni-divider>
+</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-divider` 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 |
+|---|---|---|---|---|
+| `inset` | `inset` | `'leading' \| 'middle' \| 'none'` | `'leading'` | Controla el margen horizontal en la línea del separador.  - `'leading'` (por defecto) — Margen de 16dp solo desde el borde inicial (inicio).   Usar en listas para alinear el separador con el texto principal de los elementos de la lista. - `'middle'`  — Margen de 16dp tanto en el borde inicial como en el final.   Usar para separar secciones donde una sangría completa sería visualmente demasiado pesada. - `'none'`    — Sin margen; la línea abarca todo el ancho del padre.   Usar como separador de secciones o entre tarjetas. |
+
+## 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
+
+No declara CSS Parts.
+
+## CSS Custom Properties consumidas
+
+- `--font`
+- `--outline-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.
+
+### `inset`
+
+Controla el margen horizontal en la línea del separador.
+
+- `'leading'` (por defecto) — Margen de 16dp solo desde el borde inicial (inicio).
+  Usar en listas para alinear el separador con el texto principal de los elementos de la lista.
+- `'middle'`  — Margen de 16dp tanto en el borde inicial como en el final.
+  Usar para separar secciones donde una sangría completa sería visualmente demasiado pesada.
+- `'none'`    — Sin margen; la línea abarca todo el ancho del padre.
+  Usar como separador de secciones o entre tarjetas.
+
+![moni-divider — inset=leading](../assets/moni-divider/inset--leading.png)
+
+![moni-divider — inset=middle](../assets/moni-divider/inset--middle.png)
+
+![moni-divider — inset=none](../assets/moni-divider/inset--none.png)