@moni-labs/moni-ui 0.4.4 → 0.4.6

package/docs/components/list.md

@@ -0,0 +1,121 @@
+# List
+
+Componente Material Design 3 List (Lista).
+
+Las listas son índices continuos y verticales de texto o imágenes. Son
+elementos contenedores que proporcionan agrupación estructural y opcionalmente
+líneas divisorias para los hijos `<moni-list-item>`.
+
+**Referencia de la especificación M3:** `m3-docs/components/lists/specs.md`
+
+**Rol de contenedor:**
+La lista en sí no aplica relleno (padding) ni márgenes a sus hijos. El espaciado
+y el relleno interno están controlados enteramente por los propios elementos `<moni-list-item>`
+para asegurar áreas táctiles (hit targets) y alineación correctas.
+
+**Variantes:**
+- `default` (cadena vacía) — Un contenedor de lista limpio y sin bordes.
+- `border` — Añade un borde inferior a la lista y muestra divisores
+  horizontales (color `outline-variant`) entre los elementos de la lista.
+
+- Tag: `moni-list`
+- Clase: `MoniList`
+- Fuente: `src/components/moni-list.ts`
+
+## Cuándo usarlo
+
+Usa `moni-list` 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
+<!-- Lista estándar -->
+<moni-list>
+  <moni-list-item headline="Elemento 1"></moni-list-item>
+  <moni-list-item headline="Elemento 2"></moni-list-item>
+</moni-list>
+
+<!-- Lista con divisores y elementos redondeados -->
+<moni-list variant="border" rounded>
+  <moni-list-item icon="inbox" headline="Bandeja de entrada"></moni-list-item>
+  <moni-list-item icon="send" headline="Enviados"></moni-list-item>
+</moni-list>
+```
+
+## 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-list></moni-list>
+</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-list` 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 |
+|---|---|---|---|---|
+| `variant` | `variant` | `'' \| 'border'` | `''` | Selecciona la variante visual y su nivel de énfasis. |
+| `rounded` | `rounded` | `boolean` | `false` | Activa o desactiva el comportamiento `rounded`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+
+## Slots
+
+- `default`: Elementos `<moni-list-item>`.
+
+## 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`
+- `--on-surface`
+- `--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.
+
+### `variant`
+
+Selecciona la variante visual y su nivel de énfasis.
+
+![moni-list — variant=](../assets/moni-list/variant--empty.png)
+
+![moni-list — variant=border](../assets/moni-list/variant--border.png)
+
+### `rounded`
+
+Activa o desactiva el comportamiento `rounded`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-list — rounded=false](../assets/moni-list/rounded--false.png)
+
+![moni-list — rounded=true](../assets/moni-list/rounded--true.png)

package/docs/components/loading-indicator.md

@@ -0,0 +1,124 @@
+# Loading Indicator
+
+Componente Material Design 3 Loading Indicator (Indicador de carga).
+
+Un indicador de carga indeterminado que representa visualmente un tiempo de espera
+no especificado. A diferencia de los spinners circulares estándar, este componente usa una animación
+de polígono cambiante que cambia entre formas (círculo, cuadrado redondeado, etc.)
+de acuerdo con las especificaciones de movimiento de alta fidelidad M3 Expressive.
+
+**Variantes:**
+- `uncontained` (por defecto) — Una forma cambiante independiente que hereda el color
+  de su contexto de texto (o por defecto es `primary`).
+- `contained` — La forma cambiante se coloca dentro de un contenedor circular
+  con un color de fondo distinto, útil para estados de carga de alto contraste
+  o superposición de imágenes.
+
+**Animación y Accesibilidad:**
+El componente gestiona sus propias etiquetas `<animate>` SVG. La animación se
+inicia/detiene automáticamente a través de `connectedCallback`/`disconnectedCallback`
+para ahorrar ciclos de CPU cuando el elemento está fuera de la pantalla. Aplica los atributos de valor
+y roles ARIA estándar (`role="progressbar"`) para asegurar que los lectores de pantalla
+lo identifiquen correctamente como un estado de carga indeterminado.
+
+- Tag: `moni-loading-indicator`
+- Clase: `MoniLoadingIndicator`
+- Fuente: `src/components/moni-loading-indicator.ts`
+
+## Cuándo usarlo
+
+Usa `moni-loading-indicator` 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
+<!-- Indicador no contenido -->
+<moni-loading-indicator></moni-loading-indicator>
+
+<!-- Indicador contenido (el contenedor por defecto es secondary-container) -->
+<moni-loading-indicator variant="contained"></moni-loading-indicator>
+```
+
+## 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-loading-indicator></moni-loading-indicator>
+</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-loading-indicator` 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 |
+|---|---|---|---|---|
+| `variant` | `variant` | `'uncontained' \| 'contained'` | `'uncontained'` | Selecciona la variante visual y su nivel de énfasis. |
+
+## 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
+
+- `container`: El envoltorio exterior `.container`.
+- `svg`: El elemento `<svg>` interior.
+- `shape`: El elemento `<path>` que se transforma.
+
+## CSS Custom Properties consumidas
+
+- `--_polygon-4-sided-cookie`
+- `--_polygon-9-sided-cookie`
+- `--_polygon-oval`
+- `--_polygon-pentagon`
+- `--_polygon-pill`
+- `--_polygon-soft-burst`
+- `--_polygon-sunny`
+- `--moni-loading-indicator-active-color`
+- `--moni-loading-indicator-contained-active-color`
+- `--moni-loading-indicator-contained-container-color`
+- `--moni-loading-indicator-container-shape`
+- `--moni-loading-indicator-container-size`
+- `--moni-loading-indicator-size`
+- `--on-primary-container`
+- `--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.
+
+### `variant`
+
+Selecciona la variante visual y su nivel de énfasis.
+
+![moni-loading-indicator — variant=uncontained](../assets/moni-loading-indicator/variant--uncontained.png)
+
+![moni-loading-indicator — variant=contained](../assets/moni-loading-indicator/variant--contained.png)

package/docs/components/menu-item.md

@@ -0,0 +1,131 @@
+# Menu Item
+
+Componente Material Design 3 Menu Item (Elemento de Menú).
+
+Un elemento interactivo individual dentro de un `<moni-menu>` o `<moni-context-menu>`.
+Proporciona el estilo estándar de elemento de menú M3, estados hover, e iconos
+iniciales opcionales.
+
+**Referencia de la especificación M3:** `m3-docs/components/menus/specs.md`
+
+**Estados de interacción:**
+- Hover: aplica una capa de opacidad.
+- Activo (`active=true`): aplica un fondo resaltado `tertiary-container`,
+  útil para indicar la opción actualmente seleccionada en una lista.
+- Deshabilitado (`disabled=true`): reduce la opacidad y deshabilita los eventos del puntero.
+
+- Tag: `moni-menu-item`
+- Clase: `MoniMenuItem`
+- Fuente: `src/components/moni-menu-item.ts`
+
+## Cuándo usarlo
+
+Usa `moni-menu-item` 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-menu-item icon="edit">Editar texto</moni-menu-item>
+<moni-menu-item icon="content_copy" disabled>Copiar</moni-menu-item>
+<moni-menu-item active>Actualmente seleccionado</moni-menu-item>
+```
+
+## 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-menu-item label="Ejemplo"></moni-menu-item>
+</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-menu-item` 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.
+- Cuando el control muestre únicamente un icono, añade siempre un `aria-label` descriptivo.
+- 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 |
+|---|---|---|---|---|
+| `active` | `active` | `boolean` | `false` | Indica si el elemento está activo. |
+| `disabled` | `disabled` | `boolean` | `false` | Impide la interacción y aplica el estado visual deshabilitado. |
+| `icon` | `icon` | `string` | `''` | Nombre de Material Symbol mostrado por el componente. |
+| `label` | `label` | `string` | `''` | Etiqueta visible y accesible del control. |
+
+## Slots
+
+- `default`: La etiqueta de texto para el elemento de menú.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `item`: Parte interna personalizable.
+- `icon`: Parte interna personalizable.
+- `label`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--active`
+- `--font`
+- `--on-surface`
+- `--on-tertiary-container`
+- `--speed2`
+- `--tertiary-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.
+
+### `active`
+
+Indica si el elemento está activo.
+
+![moni-menu-item — active=false](../assets/moni-menu-item/active--false.png)
+
+![moni-menu-item — active=true](../assets/moni-menu-item/active--true.png)
+
+### `disabled`
+
+Impide la interacción y aplica el estado visual deshabilitado.
+
+![moni-menu-item — disabled=false](../assets/moni-menu-item/disabled--false.png)
+
+![moni-menu-item — disabled=true](../assets/moni-menu-item/disabled--true.png)
+
+### `icon`
+
+Nombre de Material Symbol mostrado por el componente.
+
+![moni-menu-item — icon=default](../assets/moni-menu-item/icon--default.png)
+
+### `label`
+
+Etiqueta visible y accesible del control.
+
+![moni-menu-item — label=default](../assets/moni-menu-item/label--default.png)

package/docs/components/menu.md

@@ -0,0 +1,181 @@
+# Menu
+
+Componente Material Design 3 Menu (Menú).
+
+Los menús muestran una lista de opciones en una superficie temporal. Aparecen cuando
+los usuarios interactúan con un botón, acción u otro control.
+
+**Referencia de la especificación M3:** `m3-docs/components/menus/guidelines.md`
+
+**Arquitectura de posicionamiento:**
+El menú usa `position: absolute` relativo a su ancestro posicionado más cercano.
+El `:host` del componente usa `display: contents`, lo que significa que el
+elemento interior `<menu>` participa directamente en el contexto de diseño del consumidor.
+**Crucial:** El consumidor debe aplicar `position: relative` al elemento contenedor
+que contiene tanto el activador (trigger) como el `<moni-menu>`.
+
+**Posicionamiento de auto-volteo (auto-flip):**
+Según las pautas de M3, los menús deben voltearse hacia el lado opuesto del anclaje
+si se desbordan de la ventana gráfica (viewport).
+- **Navegadores modernos (Chrome/Edge 125+, Safari 18+):** Utiliza el posicionamiento
+  de anclaje de CSS y `@position-try-fallback` nativamente cuando `flip=true`.
+- **Alternativa (Fallback):** Un polyfill de JavaScript mide el menú después de que se abre. Si
+  se desborda de la posición `placement` solicitada, establece un estado interno para voltear
+  las clases de posicionamiento.
+
+**Gestión del estado:**
+El atributo `active` controla la visibilidad. Los consumidores deben escuchar los eventos
+del activador (como `click`) y alternar la propiedad `active`.
+
+- Tag: `moni-menu`
+- Clase: `MoniMenu`
+- Fuente: `src/components/moni-menu.ts`
+
+## Cuándo usarlo
+
+Usa `moni-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
+<!-- El contenedor debe tener position: relative -->
+<div style="position: relative; display: inline-block;">
+  <moni-button id="menu-trigger">Abrir Menú</moni-button>
+
+  <moni-menu placement="bottom" flip id="my-menu">
+    <moni-menu-item icon="edit">Editar</moni-menu-item>
+    <moni-menu-item icon="content_copy">Copiar</moni-menu-item>
+    <moni-divider></moni-divider>
+    <moni-menu-item icon="delete">Eliminar</moni-menu-item>
+  </moni-menu>
+</div>
+
+<script>
+  const btn = document.getElementById('menu-trigger');
+  const menu = document.getElementById('my-menu');
+  btn.addEventListener('click', () => menu.active = !menu.active);
+</script>
+```
+
+## 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-menu></moni-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-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.
+- 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 |
+|---|---|---|---|---|
+| `placement` | `placement` | `'bottom' \| 'top' \| 'left' \| 'right' \| 'min' \| 'max'` | `'bottom'` | Posición preferida en relación con el anclaje padre. |
+| `no-wrap` | `noWrap` | `boolean` | `false` | Deshabilita el ajuste de texto dentro del menú. |
+| `active` | `active` | `boolean` | `false` | Controla si el menú está visible. |
+| `space` | `space` | `'no-space' \| 'space' \| 'small-space' \| 'medium-space' \| 'large-space' \| 'extra-space'` | `'no-space'` | Lógica de espaciado entre el anclaje y el menú. |
+| `flip` | `flip` | `boolean` | `false` | Habilita la evitación de colisiones basada en JS (volteando la posición si está fuera de los límites). Útil para navegadores que carecen de soporte para anclaje CSS. |
+
+## Slots
+
+- `default`: Elementos `<moni-menu-item>`, `<moni-divider>`, o elementos `<li>` en bruto.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `menu`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--elevate2`
+- `--font`
+- `--on-surface`
+- `--speed2`
+- `--surface-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.
+
+### `placement`
+
+Posición preferida en relación con el anclaje padre.
+
+![moni-menu — placement=bottom](../assets/moni-menu/placement--bottom.png)
+
+![moni-menu — placement=top](../assets/moni-menu/placement--top.png)
+
+![moni-menu — placement=left](../assets/moni-menu/placement--left.png)
+
+![moni-menu — placement=right](../assets/moni-menu/placement--right.png)
+
+![moni-menu — placement=min](../assets/moni-menu/placement--min.png)
+
+![moni-menu — placement=max](../assets/moni-menu/placement--max.png)
+
+### `no-wrap`
+
+Deshabilita el ajuste de texto dentro del menú.
+
+![moni-menu — no-wrap=false](../assets/moni-menu/noWrap--false.png)
+
+![moni-menu — no-wrap=true](../assets/moni-menu/noWrap--true.png)
+
+### `active`
+
+Controla si el menú está visible.
+
+![moni-menu — active=true](../assets/moni-menu/active--true.png)
+
+### `space`
+
+Lógica de espaciado entre el anclaje y el menú.
+
+![moni-menu — space=no-space](../assets/moni-menu/space--no-space.png)
+
+![moni-menu — space=space](../assets/moni-menu/space--space.png)
+
+![moni-menu — space=small-space](../assets/moni-menu/space--small-space.png)
+
+![moni-menu — space=medium-space](../assets/moni-menu/space--medium-space.png)
+
+![moni-menu — space=large-space](../assets/moni-menu/space--large-space.png)
+
+![moni-menu — space=extra-space](../assets/moni-menu/space--extra-space.png)
+
+### `flip`
+
+Habilita la evitación de colisiones basada en JS (volteando la posición si está fuera de los límites).
+Útil para navegadores que carecen de soporte para anclaje CSS.
+
+![moni-menu — flip=false](../assets/moni-menu/flip--false.png)
+
+![moni-menu — flip=true](../assets/moni-menu/flip--true.png)