@moni-labs/moni-ui 0.3.1 → 0.3.2

package/src/components/moni-list-item.ts

@@ -11,60 +11,60 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Material Design 3 List Item component.
+ * Componente Material Design 3 List Item (Elemento de Lista).
  *
- * A single row within a `<moni-list>`. List items display a headline and
- * optional supporting text, metadata, icons, or avatars.
+ * Una sola fila dentro de un `<moni-list>`. Los elementos de lista muestran un titular y
+ * opcionalmente texto de soporte, metadatos, iconos o avatares.
  *
- * **M3 spec reference:** `m3-docs/components/lists/specs.md`
+ * **Referencia de la especificación M3:** `m3-docs/components/lists/specs.md`
  *
- * **Line configurations:**
- * The `lines` attribute configures the layout and minimum height of the item:
- * - `lines="1"` (default) — 56dp min height. Only the headline slot is shown.
- * - `lines="2"` — 72dp min height. Shows headline and supporting text.
- * - `lines="3"` — 88dp min height. Shows headline, supporting text, and meta text.
+ * **Configuraciones de línea:**
+ * El atributo `lines` configura el diseño y la altura mínima del elemento:
+ * - `lines="1"` (por defecto) — altura mínima de 56dp. Solo se muestra el slot del titular.
+ * - `lines="2"` — altura mínima de 72dp. Muestra el titular y el texto de soporte.
+ * - `lines="3"` — altura mínima de 88dp. Muestra el titular, el texto de soporte y el texto meta.
  *
- * **Interactive behavior:**
- * By default, items render as `<button>` elements, gaining the M3 state layer
- * (hover, focus, and press ripple effects).
- * If the `href` attribute is provided, the item internally renders as an `<a>`
- * element, allowing native link routing and interactions while preserving the
- * list item styling.
+ * **Comportamiento interactivo:**
+ * Por defecto, los elementos se renderizan como elementos `<button>`, adquiriendo la capa de estado de M3
+ * (efectos de ondulación de hover, focus y press).
+ * Si se proporciona el atributo `href`, el elemento se renderiza internamente como un elemento `<a>`,
+ * permitiendo enrutamiento de enlaces nativos e interacciones mientras se preserva el
+ * estilo del elemento de lista.
  *
- * **Visual elements:**
- * - `icon` (attribute) — Material Symbol name for the leading icon (24dp).
- * - `avatar` (attribute) — URL for a leading circular image (40dp).
- * - `trailing-icon` (attribute) — Material Symbol name for the trailing icon.
+ * **Elementos visuales:**
+ * - `icon` (atributo) — Nombre de Material Symbol para el icono inicial (24dp).
+ * - `avatar` (atributo) — URL para una imagen circular inicial (40dp).
+ * - `trailing-icon` (atributo) — Nombre de Material Symbol para el icono final.
  *
  * @example
  * ```html
- * <!-- 1-line item with icon -->
+ * <!-- Elemento de 1 línea con icono -->
  * <moni-list-item icon="inbox">
- *   Inbox
+ *   Bandeja de entrada
  * </moni-list-item>
  *
- * <!-- 2-line item with avatar and trailing meta -->
+ * <!-- Elemento de 2 líneas con avatar y meta final -->
  * <moni-list-item lines="2" avatar="/user.jpg">
  *   Ali Connors
- *   <span slot="supporting">Brunch this weekend?</span>
+ *   <span slot="supporting">¿Brunch este fin de semana?</span>
  *   <span slot="trailing-meta">10 min</span>
  * </moni-list-item>
  *
- * <!-- Link item -->
+ * <!-- Elemento de enlace -->
  * <moni-list-item href="/settings" icon="settings">
- *   Settings
+ *   Ajustes
  * </moni-list-item>
  * ```
  *
- * @slot default       - Headline text (Line 1).
- * @slot supporting    - Supporting text (Line 2, requires `lines>=2`).
- * @slot meta          - Additional meta text (Line 3, requires `lines=3`).
- * @slot trailing-meta - Small text displayed on the far right edge.
+ * @slot default       - Texto del titular (Línea 1).
+ * @slot supporting    - Texto de soporte (Línea 2, requiere `lines>=2`).
+ * @slot meta          - Texto meta adicional (Línea 3, requiere `lines=3`).
+ * @slot trailing-meta - Texto pequeño mostrado en el borde derecho lejano.
  *
- * @csspart item          - The outer `<button>` or `<a>` container.
- * @csspart leading-icon  - Container for the leading icon/avatar.
- * @csspart text          - Container for the multi-line text block.
- * @csspart trailing-icon - Container for the trailing icon.
+ * @csspart item          - El contenedor externo `<button>` o `<a>`.
+ * @csspart leading-icon  - Contenedor para el icono/avatar inicial.
+ * @csspart text          - Contenedor para el bloque de texto multilínea.
+ * @csspart trailing-icon - Contenedor para el icono final.
  */
 @customElement('moni-list-item')
 export class MoniListItem extends MoniElement {
@@ -82,18 +82,25 @@ export class MoniListItem extends MoniElement {
 		sharedStyles,
 		css`
 			:host {
+				display: block;
+				color: var(--on-surface);
+				background-color: transparent;
+				position: relative;
+				font-family: var(--font);
+				transition: background-color var(--speed2);
+			}
+
+			.row {
 				display: flex;
 				align-items: center;
 				gap: 1rem;
 				padding: 0.5rem 1rem;
 				min-block-size: 3.5rem;
-				color: var(--on-surface);
-				background-color: transparent;
+				box-sizing: border-box;
+				color: inherit;
 				text-decoration: none;
 				cursor: pointer;
-				position: relative;
-				font-family: var(--font);
-				transition: background-color var(--speed2);
+				width: 100%;
 			}
 
 			:host([active]) {
@@ -111,10 +118,10 @@ export class MoniListItem extends MoniElement {
 				border-block-end: 0.0625rem solid var(--outline-variant);
 			}
 
-			:host([lines='2']) {
+			:host([lines='2']) .row {
 				min-block-size: 4.5rem;
 			}
-			:host([lines='3']) {
+			:host([lines='3']) .row {
 				min-block-size: 5.5rem;
 			}
 
@@ -196,6 +203,19 @@ export class MoniListItem extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el diseño de 3 zonas del elemento de lista: medios iniciales, contenido y elemento final.
+	 *
+	 * **Anatomía del elemento de lista M3:**
+	 * - Zona inicial: avatar, icono o miniatura (`[slot="leading"]`).
+	 * - Zona de contenido: `overline` opcional (etiqueta pequeña en mayúsculas), `title` (texto primario),
+	 *   y `description` (texto secundario/de soporte). Cada uno se renderiza condicionalmente
+	 *   solo cuando el atributo correspondiente no está vacío para evitar nodos DOM vacíos.
+	 * - Zona final: metadatos, botón de icono, o radio/checkbox (`[slot="trailing"]`).
+	 *
+	 * Un `<slot>` vacío se renderiza en la zona de contenido como respaldo para que los consumidores
+	 * puedan proyectar texto sin formato o marcado complejo directamente en el elemento.
+	 */
 	override render() {
 		const leading = this.avatar
 			? html`<span
@@ -241,7 +261,7 @@ export class MoniListItem extends MoniElement {
 					href=${this.href}
 					>${inner}</a
 				>`
-			: inner;
+			: html`<div class="row" part="row">${inner}</div>`;
 	}
 }
 

package/src/components/moni-list.ts

@@ -8,42 +8,43 @@
 import { html, css } from 'lit';
 import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
+import { emitMoniEvent } from '../utils/event-emitter.js';
 
 /**
- * Material Design 3 List component.
+ * Componente Material Design 3 List (Lista).
  *
- * Lists are continuous, vertical indexes of text or images. They are
- * container elements that provide structural grouping and optional
- * divider lines for `<moni-list-item>` children.
+ * 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>`.
  *
- * **M3 spec reference:** `m3-docs/components/lists/specs.md`
+ * **Referencia de la especificación M3:** `m3-docs/components/lists/specs.md`
  *
- * **Container role:**
- * The list itself does not apply padding or margins to its children. Spacing
- * and internal padding are controlled entirely by the `<moni-list-item>`
- * elements themselves to ensure proper hit targets and alignment.
+ * **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.
  *
- * **Variants:**
- * - `default` (empty string) — A clean, borderless list container.
- * - `border` — Adds a bottom border to the list and displays horizontal
- *   dividers (`outline-variant` color) between list items.
+ * **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.
  *
  * @example
  * ```html
- * <!-- Standard list -->
+ * <!-- Lista estándar -->
  * <moni-list>
- *   <moni-list-item headline="Item 1"></moni-list-item>
- *   <moni-list-item headline="Item 2"></moni-list-item>
+ *   <moni-list-item headline="Elemento 1"></moni-list-item>
+ *   <moni-list-item headline="Elemento 2"></moni-list-item>
  * </moni-list>
  *
- * <!-- List with dividers and rounded items -->
+ * <!-- Lista con divisores y elementos redondeados -->
  * <moni-list variant="border" rounded>
- *   <moni-list-item icon="inbox" headline="Inbox"></moni-list-item>
- *   <moni-list-item icon="send" headline="Sent"></moni-list-item>
+ *   <moni-list-item icon="inbox" headline="Bandeja de entrada"></moni-list-item>
+ *   <moni-list-item icon="send" headline="Enviados"></moni-list-item>
  * </moni-list>
  * ```
  *
- * @slot default - `<moni-list-item>` elements.
+ * @slot default - Elementos `<moni-list-item>`.
  */
 @customElement('moni-list')
 export class MoniList extends MoniElement {
@@ -70,8 +71,23 @@ export class MoniList extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el contenedor de la lista como un elemento semánticamente apropiado.
+	 *
+	 * El elemento raíz por defecto es `<ul>` (lista desordenada). Cuando `ordered=true`,
+	 * cambia a `<ol>` para secuencias numeradas. Para listas de navegación, el
+	 * consumidor debe usar `role="navigation"` en el elemento host o establecer `as="nav"`.
+	 * Los hijos `<moni-list-item>` en el slot reciben su `tabindex` y rol ARIA
+	 * de la implementación de su propio componente.
+	 */
+	private _handleSlotChange(e: Event) {
+		const slot = e.target as HTMLSlotElement;
+		const nodes = slot.assignedNodes({ flatten: true }).filter(n => n.nodeType === Node.ELEMENT_NODE);
+		emitMoniEvent(this, 'moni-slot-items-changed', { detail: { nodes } });
+	}
+
 	override render() {
-		return html`<slot></slot>`;
+		return html`<slot @slotchange=${this._handleSlotChange}></slot>`;
 	}
 }
 

package/src/components/moni-loading-indicator.test.ts

@@ -14,7 +14,7 @@ describe('moni-loading-indicator', () => {
 		el.remove();
 	});
 
-	it('renders a container with active indicator', async () => {
+	it('renderiza un contenedor con indicador activo', async () => {
 		await el.updateComplete;
 		const container = el.shadowRoot?.querySelector('.container');
 		const activeIndicator = el.shadowRoot?.querySelector('.active-indicator');
@@ -22,7 +22,7 @@ describe('moni-loading-indicator', () => {
 		expect(activeIndicator).toBeTruthy();
 	});
 
-	it('reflects and respects the variant attribute', async () => {
+	it('refleja y respeta el atributo variant', async () => {
 		expect(el.variant).toBe('uncontained');
 		el.variant = 'contained';
 		await el.updateComplete;
@@ -33,7 +33,7 @@ describe('moni-loading-indicator', () => {
 		expect(el.getAttribute('variant')).toBe('uncontained');
 	});
 
-	it('has progressbar role and min/max values set', () => {
+	it('tiene el rol progressbar y valores min/max establecidos', () => {
 		expect(el.getAttribute('role')).toBe('progressbar');
 		expect(el.ariaValueMin).toBe('0');
 		expect(el.ariaValueMax).toBe('100');

package/src/components/moni-loading-indicator.ts

@@ -11,39 +11,39 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import { loadingIndicatorPolygons } from './loading-shapes.js';
 
 /**
- * Material Design 3 Loading Indicator component.
+ * Componente Material Design 3 Loading Indicator (Indicador de carga).
  *
- * An indeterminate loading indicator that visually represents an unspecified
- * wait time. Unlike standard circular spinners, this component uses a morphing
- * polygon animation that shifts between shapes (circle, rounded square, etc.)
- * in accordance with the high-fidelity M3 Expressive motion specifications.
+ * 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.
  *
- * **Variants:**
- * - `uncontained` (default) — A standalone morphing shape that inherits color
- *   from its text context (or defaults to `primary`).
- * - `contained` — The morphing shape is placed inside a circular container
- *   with a distinct background color, useful for high-contrast loading states
- *   or overlaying imagery.
+ * **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.
  *
- * **Animation & Accessibility:**
- * The component manages its own SVG `<animate>` tags. The animation is
- * automatically started/stopped via `connectedCallback`/`disconnectedCallback`
- * to save CPU cycles when the element is off-screen. It applies standard ARIA
- * roles (`role="progressbar"`) and value attributes to ensure screen readers
- * identify it correctly as an indeterminate loading state.
+ * **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.
  *
  * @example
  * ```html
- * <!-- Uncontained indicator -->
+ * <!-- Indicador no contenido -->
  * <moni-loading-indicator></moni-loading-indicator>
  *
- * <!-- Contained indicator (default container is secondary-container) -->
+ * <!-- Indicador contenido (el contenedor por defecto es secondary-container) -->
  * <moni-loading-indicator variant="contained"></moni-loading-indicator>
  * ```
  *
- * @csspart container - The outer `.container` wrapper.
- * @csspart svg       - The inner `<svg>` element.
- * @csspart shape     - The `<path>` element that morphs.
+ * @csspart container - El envoltorio exterior `.container`.
+ * @csspart svg       - El elemento `<svg>` interior.
+ * @csspart shape     - El elemento `<path>` que se transforma.
  */
 @customElement('moni-loading-indicator')
 export class MoniLoadingIndicator extends MoniElement {
@@ -52,6 +52,11 @@ export class MoniLoadingIndicator extends MoniElement {
 
 	@query('.container') private _container?: HTMLElement;
 
+	/**
+	 * Hook de inicialización (Lit).
+	 * Configura roles ARIA (progressbar) por defecto y asegura
+	 * el encendido inicial de la animación infinita en el Shadow DOM.
+	 */
 	override connectedCallback() {
 		super.connectedCallback();
 		this.ariaValueMin = this.ariaValueMin || '0';
@@ -60,15 +65,30 @@ export class MoniLoadingIndicator extends MoniElement {
 		this._toggleAnimation(true);
 	}
 
+	/**
+	 * Hook de destrucción (Lit).
+	 * Apaga formalmente la animación CSS (`.animate`) para frenar el GPU repaint
+	 * cuando el componente es destruido, reduciendo el consumo de batería.
+	 */
 	override disconnectedCallback() {
 		super.disconnectedCallback();
 		this._toggleAnimation(false);
 	}
 
+	/**
+	 * Hook de primera actualización (Lit).
+	 * Dispara explícitamente el estado de animación una vez que el DOM 
+	 * interno (`this._container`) ha sido montado y es seleccionable.
+	 */
 	protected override firstUpdated() {
 		this._toggleAnimation(true);
 	}
 
+	/**
+	 * Controlador imperativo de las clases de animación.
+	 * Permite pausar/reanudar el loader mediante CSS, muy útil cuando se integra
+	 * con observadores de visibilidad (IntersectionObserver) para mejorar el rendimiento.
+	 */
 	private _toggleAnimation(enable: boolean) {
 		if (this._container) {
 			this._container.classList.toggle('animate', enable);
@@ -196,6 +216,18 @@ export class MoniLoadingIndicator extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza la superposición de carga de pantalla completa con un spinner centrado y una etiqueta opcional.
+	 *
+	 * La superposición utiliza `position: fixed; inset: 0` para cubrir toda la ventana gráfica,
+	 * y `z-index` para aparecer por encima del resto del contenido. El spinner `<moni-progress>`
+	 * se centra mediante CSS flexbox en el elemento `:host`.
+	 *
+	 * **Región ARIA en vivo:**
+	 * `aria-live="polite"` y `aria-label` en el contenedor anuncian los cambios de estado
+	 * de carga a los lectores de pantalla sin interrumpir el flujo de lectura del usuario.
+	 * El `role="status"` da a los lectores de pantalla un punto de referencia implícito similar a una alerta.
+	 */
 	override render() {
 		return html`
 			<div class="container animate" aria-hidden="true">

package/src/components/moni-menu-item.ts

@@ -11,31 +11,31 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Material Design 3 Menu Item component.
+ * Componente Material Design 3 Menu Item (Elemento de Menú).
  *
- * A single interactive item within a `<moni-menu>` or `<moni-context-menu>`.
- * It provides standard M3 menu item styling, hover states, and optional
- * leading icons.
+ * 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.
  *
- * **M3 spec reference:** `m3-docs/components/menus/specs.md`
+ * **Referencia de la especificación M3:** `m3-docs/components/menus/specs.md`
  *
- * **Interaction states:**
- * - Hover: applies an opacity layer.
- * - Active (`active=true`): applies a `tertiary-container` background highlight,
- *   useful for indicating the currently selected option in a list.
- * - Disabled (`disabled=true`): reduces opacity and disables pointer events.
+ * **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.
  *
  * @example
  * ```html
- * <moni-menu-item icon="edit">Edit text</moni-menu-item>
- * <moni-menu-item icon="content_copy" disabled>Copy</moni-menu-item>
- * <moni-menu-item active>Currently selected</moni-menu-item>
+ * <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>
  * ```
  *
- * @slot default - The text label for the menu item.
+ * @slot default - La etiqueta de texto para el elemento de menú.
  *
- * @csspart item - The outer `<li>` element.
- * @csspart icon - The container for the leading icon.
+ * @csspart item - El elemento exterior `<li>`.
+ * @csspart icon - El contenedor para el icono inicial.
  */
 @customElement('moni-menu-item')
 export class MoniMenuItem extends MoniElement {
@@ -90,6 +90,13 @@ export class MoniMenuItem extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el elemento de menú como un `<li>` con un icono inicial opcional y un atajo final.
+	 *
+	 * El `<moni-icon>` inicial solo se renderiza cuando se establece `icon` (evita nodos DOM vacíos).
+	 * `shortcut` se muestra como texto silenciado alineado a la derecha (ej. `Ctrl+K`) usando el estilo
+	 * de tipografía `body-small` de M3. El slot proyecta contenido personalizado junto a la etiqueta.
+	 */
 	override render() {
 		return html`<li part="item">
 			${this.icon

package/src/components/moni-menu.test.ts

@@ -14,26 +14,26 @@ describe('moni-menu (P3.2 — flip attribute)', () => {
 		el.remove();
 	});
 
-	it('defaults to placement=bottom and flip=false', async () => {
+	it('por defecto es placement=bottom y flip=false', async () => {
 		await el.updateComplete;
 		expect(el.placement).toBe('bottom');
 		expect(el.flip).toBe(false);
 	});
 
-	it('reflects flip attribute on the host', async () => {
+	it('refleja el atributo flip en el host', async () => {
 		el.flip = true;
 		await el.updateComplete;
 		expect(el.hasAttribute('flip')).toBe(true);
 	});
 
-	it('renders the placement class on the inner <menu>', async () => {
+	it('renderiza la clase de placement en el <menu> interno', async () => {
 		el.placement = 'top';
 		await el.updateComplete;
 		const menu = el.shadowRoot?.querySelector('menu');
 		expect(menu?.classList.contains('top')).toBe(true);
 	});
 
-	it('reflects active as a class on the <menu>', async () => {
+	it('refleja active como una clase en el <menu>', async () => {
 		el.active = true;
 		await el.updateComplete;
 		const menu = el.shadowRoot?.querySelector('menu');
@@ -44,7 +44,7 @@ describe('moni-menu (P3.2 — flip attribute)', () => {
 		expect(menu?.classList.contains('active')).toBe(false);
 	});
 
-	it('reflects all 6 placements (bottom/top/left/right/min/max)', async () => {
+	it('refleja todos los 6 placements (bottom/top/left/right/min/max)', async () => {
 		const placements: Array<'bottom' | 'top' | 'left' | 'right' | 'min' | 'max'> = [
 			'bottom',
 			'top',
@@ -61,7 +61,7 @@ describe('moni-menu (P3.2 — flip attribute)', () => {
 		}
 	});
 
-	it('space variants (no-space/space/small-space/medium-space/large-space/extra-space) apply a gap class', async () => {
+	it('las variantes de espacio (no-space/space/small-space/medium-space/large-space/extra-space) aplican una clase de gap', async () => {
 		const spaces = [
 			'no-space',
 			'space',
@@ -78,7 +78,7 @@ describe('moni-menu (P3.2 — flip attribute)', () => {
 		}
 	});
 
-	it('no-wrap attribute forwards to a no-wrap class', async () => {
+	it('el atributo no-wrap se reenvía a una clase no-wrap', async () => {
 		el.noWrap = true;
 		await el.updateComplete;
 		const menu = el.shadowRoot?.querySelector('menu');