@moni-labs/moni-ui 0.3.1 → 0.3.2

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

@@ -12,49 +12,49 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Material Design 3 Navigation Item component.
+ * Componente Material Design 3 Navigation Item (Elemento de Navegación).
  *
- * A single destination item within a `<moni-nav>` container. Renders as an
- * accessible `<a>` element with an icon, label, and M3 state layer.
+ * Un elemento de destino individual dentro de un contenedor `<moni-nav>`. Se renderiza como un
+ * elemento `<a>` accesible con un icono, etiqueta y capa de estado M3.
  *
- * **M3 spec references:**
- * - Navigation bar item: `m3-docs/components/navigation-bar/specs.md`
- * - Navigation rail item: `m3-docs/components/navigation-rail/specs.md`
- * - Navigation drawer item: `m3-docs/components/navigation-drawer/specs.md`
+ * **Referencias a la especificación M3:**
+ * - Elemento de barra de navegación: `m3-docs/components/navigation-bar/specs.md`
+ * - Elemento de riel de navegación: `m3-docs/components/navigation-rail/specs.md`
+ * - Elemento de cajón de navegación: `m3-docs/components/navigation-drawer/specs.md`
  *
- * **Layout adaptation:**
- * The `placement`, `variant`, and `layout` properties are forwarded from
- * the parent `<moni-nav>` (typically via attribute binding in the parent's
- * render method). The nav item uses these to conditionally render:
- * - Icon + label below (navigation bar).
- * - Icon only + horizontal label (rail).
- * - Icon + full label (drawer).
+ * **Adaptación de diseño:**
+ * Las propiedades `placement`, `variant` y `layout` son retransmitidas desde
+ * el padre `<moni-nav>` (típicamente a través de vinculación de atributos en el
+ * método render del padre). El elemento de navegación las usa para renderizar condicionalmente:
+ * - Icono + etiqueta abajo (barra de navegación).
+ * - Solo icono + etiqueta horizontal (riel).
+ * - Icono + etiqueta completa (cajón).
  *
- * **Responsive behavior:**
- * Uses `window.matchMedia('(min-width: 601px)')` to detect medium screens
- * and stores the result in `_isMediumScreen`. This drives automatic layout
- * switching between bar and rail styles.
+ * **Comportamiento responsivo:**
+ * Usa `window.matchMedia('(min-width: 601px)')` para detectar pantallas medianas
+ * y almacena el resultado en `_isMediumScreen`. Esto impulsa el cambio de diseño
+ * automático entre estilos de barra y riel.
  *
- * **Active state:**
- * The `active` attribute applies the M3 active indicator: a pill-shaped
- * `secondary-container` background behind the icon and a darker label color.
+ * **Estado activo:**
+ * El atributo `active` aplica el indicador activo M3: un fondo `secondary-container`
+ * en forma de píldora detrás del icono y un color de etiqueta más oscuro.
  *
  * @example
  * ```html
  * <moni-nav placement="bottom">
- *   <moni-nav-item href="/" icon="home" label="Home" active></moni-nav-item>
- *   <moni-nav-item href="/search" icon="search" label="Search"></moni-nav-item>
- *   <moni-nav-item href="/profile" icon="person" label="Profile">
- *     <moni-badge value="3"></moni-badge>  <!-- notification badge -->
+ *   <moni-nav-item href="/" icon="home" label="Inicio" active></moni-nav-item>
+ *   <moni-nav-item href="/search" icon="search" label="Buscar"></moni-nav-item>
+ *   <moni-nav-item href="/profile" icon="person" label="Perfil">
+ *     <moni-badge value="3"></moni-badge>  <!-- insignia de notificación -->
  *   </moni-nav-item>
  * </moni-nav>
  * ```
  *
- * @slot default - Additional content slotted after the icon (e.g. `<moni-badge>`).
+ * @slot default - Contenido adicional colocado después del icono (ej. `<moni-badge>`).
  *
- * @csspart item   - The outer `<a>` element.
- * @csspart icon   - The icon container.
- * @csspart label  - The label text element.
+ * @csspart item   - El elemento exterior `<a>`.
+ * @csspart icon   - El contenedor del icono.
+ * @csspart label  - El elemento de texto de la etiqueta.
  */
 @customElement('moni-nav-item')
 export class MoniNavItem extends MoniElement {
@@ -74,6 +74,12 @@ export class MoniNavItem extends MoniElement {
 		? window.matchMedia('(min-width: 601px)')
 		: null;
 
+	/**
+	 * Hook de inicialización (Lit).
+	 * Vincula un listener de `MediaQueryList` nativo para poder reaccionar en tiempo real
+	 * cuando la pantalla cruza el breakpoint de 600px, adaptando la disposición
+	 * (horizontal vs vertical) del ícono y la etiqueta automáticamente.
+	 */
 	override connectedCallback() {
 		super.connectedCallback();
 		if (this._query) {
@@ -82,6 +88,11 @@ export class MoniNavItem extends MoniElement {
 		}
 	}
 
+	/**
+	 * Hook de destrucción (Lit).
+	 * Desvincula rigurosamente el listener del `matchMedia` para
+	 * prevenir fugas de memoria (memory leaks).
+	 */
 	override disconnectedCallback() {
 		super.disconnectedCallback();
 		if (this._query) {
@@ -89,6 +100,11 @@ export class MoniNavItem extends MoniElement {
 		}
 	}
 
+	/**
+	 * Callback asíncrono disparado nativamente por el navegador cuando
+	 * cambian las condiciones del Media Query. 
+	 * Actualiza el estado reactivo `_isMediumScreen` lo que fuerza a Lit a re-renderizar.
+	 */
 	private _handleQueryChange = (e: MediaQueryListEvent) => {
 		this._isMediumScreen = e.matches;
 	};
@@ -236,6 +252,20 @@ export class MoniNavItem extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el elemento de navegación como un `<a>` o `<button>` con ranura de icono, etiqueta y badge (insignia).
+	 *
+	 * **Indicador activo:**
+	 * La barra de navegación M3 usa un indicador en forma de píldora detrás del icono del
+	 * elemento activo. Esto se implementa como el pseudo-elemento `::before` en
+	 * `.item` que crece de `0` a `64px` de ancho usando una transición CSS.
+	 * La clase `active` en `.item` activa la transición y también establece
+	 * `aria-current="page"` para lectores de pantalla.
+	 *
+	 * **Ranura para badge (insignia):**
+	 * `[slot="badge"]` se renderiza posicionado absolutamente sobre la esquina superior final del icono.
+	 * Los consumidores colocan un `<moni-badge>` aquí para cuentas de notificaciones.
+	 */
 	override render() {
 		const isHorizontal = this.computedLayout === 'horizontal';
 

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

@@ -16,7 +16,7 @@ describe('moni-nav / moni-nav-item', () => {
 		el.remove();
 	});
 
-	it('renders a <nav> with a slot', async () => {
+	it('renderiza un <nav> con un slot', async () => {
 		await el.updateComplete;
 		const nav = el.shadowRoot?.querySelector('nav');
 		const slot = el.shadowRoot?.querySelector('slot');
@@ -24,14 +24,14 @@ describe('moni-nav / moni-nav-item', () => {
 		expect(slot).toBeTruthy();
 	});
 
-	it('applies the placement class to the nav', async () => {
+	it('aplica la clase de placement al nav', async () => {
 		el.placement = 'bottom';
 		await el.updateComplete;
 		const nav = el.shadowRoot?.querySelector('nav');
 		expect(nav?.classList.contains('bottom')).toBe(true);
 	});
 
-	it('applies the variant class (rail/drawer)', async () => {
+	it('aplica la clase de variante (rail/drawer)', async () => {
 		el.placement = 'left';
 		el.variant = 'drawer';
 		await el.updateComplete;
@@ -40,19 +40,19 @@ describe('moni-nav / moni-nav-item', () => {
 		expect(nav?.classList.contains('max')).toBe(true);
 	});
 
-	it('reflects the placement attribute', async () => {
+	it('refleja el atributo placement', async () => {
 		el.placement = 'right';
 		await el.updateComplete;
 		expect(el.getAttribute('placement')).toBe('right');
 	});
 
-	it('reflects the variant attribute', async () => {
+	it('refleja el atributo variant', async () => {
 		el.variant = 'rail';
 		await el.updateComplete;
 		expect(el.getAttribute('variant')).toBe('rail');
 	});
 
-	it('forwards icon, label and active to nav-item', async () => {
+	it('reenvía icon, label y active al nav-item', async () => {
 		const item = document.createElement('moni-nav-item') as MoniNavItem;
 		item.icon = 'home';
 		item.label = 'Home';
@@ -68,7 +68,7 @@ describe('moni-nav / moni-nav-item', () => {
 		expect(a?.querySelector('moni-icon')).toBeTruthy();
 	});
 
-	it('forwards href and target to the inner <a>', async () => {
+	it('reenvía href y target al <a> interno', async () => {
 		const item = document.createElement('moni-nav-item') as MoniNavItem;
 		item.href = '/home';
 		item.target = '_blank';
@@ -79,7 +79,7 @@ describe('moni-nav / moni-nav-item', () => {
 		expect(a?.getAttribute('target')).toBe('_blank');
 	});
 
-	it('propagates layout property to items and sets computed layout', async () => {
+	it('propaga la propiedad layout a los ítems y establece el layout computado', async () => {
 		const item = document.createElement('moni-nav-item') as MoniNavItem;
 		el.appendChild(item);
 		el.layout = 'horizontal';
@@ -93,7 +93,7 @@ describe('moni-nav / moni-nav-item', () => {
 		expect(a?.getAttribute('data-layout')).toBe('horizontal');
 	});
 
-	it('modal drawer renders a scrim and dialog semantics', async () => {
+	it('el modal drawer renderiza un scrim y semántica de dialog', async () => {
 		el.placement = 'left';
 		el.variant = 'drawer';
 		el.modal = true;
@@ -108,7 +108,7 @@ describe('moni-nav / moni-nav-item', () => {
 		expect(nav?.getAttribute('aria-expanded')).toBe('true');
 	});
 
-	it('modal drawer closes when the scrim is clicked', async () => {
+	it('el modal drawer se cierra cuando se hace clic en el scrim', async () => {
 		el.placement = 'left';
 		el.variant = 'drawer';
 		el.modal = true;
@@ -124,7 +124,7 @@ describe('moni-nav / moni-nav-item', () => {
 		expect(nav?.getAttribute('aria-expanded')).toBe('false');
 	});
 
-	it('modal drawer closes on Escape key', async () => {
+	it('el modal drawer se cierra con la tecla Escape', async () => {
 		el.placement = 'left';
 		el.variant = 'drawer';
 		el.modal = true;

package/src/components/moni-nav.ts

@@ -10,56 +10,56 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Material Design 3 Navigation container component.
+ * Componente contenedor de Navegación Material Design 3.
  *
- * `<moni-nav>` is the container that wraps `<moni-nav-item>` elements and
- * controls the M3 navigation pattern: navigation bar, navigation rail, or
- * navigation drawer.
+ * `<moni-nav>` es el contenedor que envuelve los elementos `<moni-nav-item>` y
+ * controla el patrón de navegación M3: barra de navegación, riel de navegación o
+ * cajón de navegación.
  *
- * **M3 spec references:**
- * - Navigation bar: `m3-docs/components/navigation-bar/specs.md`
- * - Navigation rail: `m3-docs/components/navigation-rail/specs.md`
- * - Navigation drawer: `m3-docs/components/navigation-drawer/specs.md`
+ * **Referencias a la especificación M3:**
+ * - Barra de navegación: `m3-docs/components/navigation-bar/specs.md`
+ * - Riel de navegación: `m3-docs/components/navigation-rail/specs.md`
+ * - Cajón de navegación: `m3-docs/components/navigation-drawer/specs.md`
  *
- * **Navigation patterns:**
- * - **Navigation bar** (`placement="bottom"`) — Horizontal bar of icon+label
- *   items at the bottom of the screen. Best for 3–5 top-level destinations.
- * - **Navigation rail** (`variant="rail"`) — Vertical rail of icon+label items
- *   on the side of the screen. Best for medium/expanded breakpoints.
- * - **Standard drawer** (`variant="drawer"`) — Always-visible vertical panel
- *   with full text labels. No scrim. Best for large screens.
- * - **Modal drawer** (`variant="drawer" modal`) — Overlay drawer with scrim.
- *   Opened/closed via the `open` property. Traps keyboard focus while open.
- *   Closes on `Escape` key press.
+ * **Patrones de navegación:**
+ * - **Barra de navegación** (`placement="bottom"`) — Barra horizontal de elementos de icono+etiqueta
+ *   en la parte inferior de la pantalla. Ideal para 3–5 destinos de nivel superior.
+ * - **Riel de navegación** (`variant="rail"`) — Riel vertical de elementos de icono+etiqueta
+ *   en el lateral de la pantalla. Ideal para puntos de interrupción medianos/expandidos.
+ * - **Cajón estándar** (`variant="drawer"`) — Panel vertical siempre visible
+ *   con etiquetas de texto completo. Sin atenuación (scrim). Ideal para pantallas grandes.
+ * - **Cajón modal** (`variant="drawer" modal`) — Cajón superpuesto con atenuación (scrim).
+ *   Se abre/cierra a través de la propiedad `open`. Atrapa el foco del teclado mientras está abierto.
+ *   Se cierra al presionar la tecla `Escape`.
  *
- * **Keyboard handling:**
- * When `modal=true`, the component adds a global `keydown` listener in
- * `connectedCallback` that closes the drawer on `Escape`. The listener is
- * removed in `disconnectedCallback`.
+ * **Manejo del teclado:**
+ * Cuando `modal=true`, el componente añade un listener global de `keydown` en
+ * `connectedCallback` que cierra el cajón con `Escape`. El listener se
+ * elimina en `disconnectedCallback`.
  *
  * @example
  * ```html
- * <!-- Bottom navigation bar -->
+ * <!-- Barra de navegación inferior -->
  * <moni-nav placement="bottom">
- *   <moni-nav-item icon="home" label="Home" active></moni-nav-item>
- *   <moni-nav-item icon="search" label="Search"></moni-nav-item>
- *   <moni-nav-item icon="person" label="Profile"></moni-nav-item>
+ *   <moni-nav-item icon="home" label="Inicio" active></moni-nav-item>
+ *   <moni-nav-item icon="search" label="Buscar"></moni-nav-item>
+ *   <moni-nav-item icon="person" label="Perfil"></moni-nav-item>
  * </moni-nav>
  *
- * <!-- Modal navigation drawer -->
+ * <!-- Cajón de navegación modal -->
  * <moni-nav variant="drawer" modal open placement="left">
- *   <h3 slot="header">My App</h3>
- *   <moni-nav-item icon="home" label="Home" active></moni-nav-item>
- *   <moni-nav-item icon="settings" label="Settings"></moni-nav-item>
+ *   <h3 slot="header">Mi App</h3>
+ *   <moni-nav-item icon="home" label="Inicio" active></moni-nav-item>
+ *   <moni-nav-item icon="settings" label="Ajustes"></moni-nav-item>
  * </moni-nav>
  * ```
  *
- * @slot default - `<moni-nav-item>` children.
- * @slot header  - Content above the nav items (drawer variant only).
- * @slot footer  - Content below the nav items (drawer variant only).
+ * @slot default - Hijos `<moni-nav-item>`.
+ * @slot header  - Contenido encima de los elementos de navegación (solo variante drawer).
+ * @slot footer  - Contenido debajo de los elementos de navegación (solo variante drawer).
  *
- * @csspart nav     - The inner `<nav>` element.
- * @csspart scrim   - The backdrop scrim (modal drawer only).
+ * @csspart nav     - El elemento `<nav>` interior.
+ * @csspart scrim   - El atenuador de fondo (scrim) (solo cajón modal).
  */
 @customElement('moni-nav')
 export class MoniNav extends MoniElement {
@@ -72,29 +72,59 @@ export class MoniNav extends MoniElement {
 	@property({ reflect: true })
 	layout: 'vertical' | 'horizontal' | 'auto' = 'auto';
 
+	/**
+	 * Hook de inicialización (Lit).
+	 * Vincula el listener global para teclado, asegurando que `_onKeydown` mantenga
+	 * el contexto correcto de `this` al ser disparado por el documento.
+	 */
 	override connectedCallback() {
 		super.connectedCallback();
 		this._onKeydown = this._onKeydown.bind(this);
 		document.addEventListener('keydown', this._onKeydown);
 	}
 
+	/**
+	 * Hook de destrucción (Lit).
+	 * Remueve el listener de teclado global para evitar fugas de memoria (memory leaks)
+	 * cuando el componente de navegación es retirado del DOM.
+	 */
 	override disconnectedCallback() {
 		super.disconnectedCallback();
 		document.removeEventListener('keydown', this._onKeydown);
 	}
 
+	/**
+	 * Manejador global de eventos de teclado.
+	 * Implementa el patrón de accesibilidad estándar: Si el drawer es modal y está abierto,
+	 * presionar la tecla Escape forzará su cierre inmediato.
+	 */
 	private _onKeydown(e: KeyboardEvent) {
 		if (e.key === 'Escape' && this.modal && this.open) {
 			this.open = false;
 		}
 	}
 
+	/**
+	 * Función de cierre rápido invocada típicamente al hacer clic en el backdrop/scrim.
+	 * Modifica directamente la propiedad `open` a false si la navegación opera en modo modal.
+	 */
 	private _closeModal() {
 		if (this.modal) {
 			this.open = false;
 		}
 	}
 
+	/**
+	 * Propaga los cambios estructurales a todos los hijos `<moni-nav-item>` insertados en la ranura.
+	 *
+	 * Cuando `placement`, `variant`, `layout`, `modal` o `open` cambian en el
+	 * `<moni-nav>` padre, los elementos hijos `<moni-nav-item>` también deben actualizar su estado
+	 * de diseño calculado (layout) y de apertura. Esto se hace imperativamente a través de `_propagateToItems()` en lugar
+	 * de a través de la API de Contexto de Lit para evitar la sobrecarga del Proveedor de Contexto para una simple
+	 * relación padre→hijo.
+	 *
+	 * @param changed - Mapa de los nombres de las propiedades reactivas que desencadenaron este ciclo de actualización.
+	 */
 	override updated(changed: Map<string, unknown>) {
 		if (
 			changed.has('placement') ||
@@ -107,6 +137,12 @@ export class MoniNav extends MoniElement {
 		}
 	}
 
+	/**
+	 * Patrón de inyección de propiedades "Top-Down" sin usar Context API.
+	 * Pasa las variables arquitectónicas (`placement`, `variant`, `layout`) a los `moni-nav-item`
+	 * hijos para que ellos puedan adaptar su CSS (ej: ocultar la etiqueta en la variante 'rail').
+	 * Se lanza al inicializar o cada vez que cambia una prop en el contenedor.
+	 */
 	private _propagateToItems = () => {
 		const items = this.querySelectorAll('moni-nav-item');
 		items.forEach(item => {
@@ -266,6 +302,29 @@ export class MoniNav extends MoniElement {
 		`,
 	];
 
+	/**
+	 * Renderiza el contenedor de navegación con su superposición opcional de atenuación (scrim).
+	 *
+	 * **Composición de clases:**
+	 * - `this.placement` (`'left'`, `'right'`, `'bottom'`) — posiciona el cajón
+	 *   o la barra de navegación inferior contra el borde correcto de la ventana gráfica.
+	 * - `'max'` — agregado cuando `variant='drawer'`; expande la navegación a toda altura
+	 *   y ancho según la especificación M3 Navigation Drawer.
+	 *
+	 * **Atenuación de cajón modal (Modal drawer scrim):**
+	 * `isModalDrawer` es `true` cuando `variant='drawer'` Y `modal=true`. En este
+	 * caso, se renderiza un div `.scrim` detrás del cajón como una superposición
+	 * de hacer-clic-para-descartar. La atenuación tiene `aria-hidden="true"` ya que es puramente visual.
+	 *
+	 * **Atributo `[open]`:**
+	 * La vinculación `?open=${this.open}` agrega/elimina el atributo `open` en el
+	 * elemento `<nav>`. Los selectores de atributo CSS `[open]` impulsan la transición
+	 * de deslizamiento hacia adentro/afuera, manteniendo la animación completamente en CSS (no se requiere GSAP para este componente).
+	 *
+	 * **Punto de referencia ARIA (ARIA landmark):**
+	 * El elemento `<nav>` se usa directamente (no un `<div role="navigation">`) para
+	 * proporcionar un punto de referencia ARIA implícito al que pueden saltar los lectores de pantalla.
+	 */
 	override render() {
 		const isModalDrawer = this.variant === 'drawer' && this.modal;
 		const classes = [this.placement, this.variant === 'drawer' ? 'max' : '']

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

@@ -14,26 +14,26 @@ describe('moni-progress', () => {
 		el.remove();
 	});
 
-	it('renders a progress bar container', async () => {
+	it('renderiza un contenedor de barra de progreso', async () => {
 		await el.updateComplete;
 		const progress = el.shadowRoot?.querySelector('[role="progressbar"]');
 		expect(progress).toBeTruthy();
 	});
 
-	it('applies the indeterminate class to the progress bar container', async () => {
+	it('aplica la clase indeterminate al contenedor de la barra de progreso', async () => {
 		el.indeterminate = true;
 		await el.updateComplete;
 		const progress = el.shadowRoot?.querySelector('[role="progressbar"]');
 		expect(progress?.classList.contains('indeterminate')).toBe(true);
 	});
 
-	it('does not apply the indeterminate class by default', async () => {
+	it('no aplica la clase indeterminate por defecto', async () => {
 		await el.updateComplete;
 		const progress = el.shadowRoot?.querySelector('[role="progressbar"]');
 		expect(progress?.classList.contains('indeterminate')).toBe(false);
 	});
 
-	it('forwards value and max via aria attributes on progressbar', async () => {
+	it('reenvía value y max a través de los atributos aria en el progressbar', async () => {
 		el.value = 42;
 		el.max = 100;
 		await el.updateComplete;
@@ -44,7 +44,7 @@ describe('moni-progress', () => {
 		expect(progress.getAttribute('aria-valuemax')).toBe('100');
 	});
 
-	it('clamps the rendered percentage between 0 and 100', async () => {
+	it('limita el porcentaje renderizado entre 0 y 100', async () => {
 		el.value = 150;
 		el.max = 100;
 		await el.updateComplete;
@@ -61,28 +61,28 @@ describe('moni-progress', () => {
 		expect(style2).toContain('--_p: 0');
 	});
 
-	it('renders the progress-circular container for circular variant', async () => {
+	it('renderiza el contenedor progress-circular para la variante circular', async () => {
 		el.variant = 'circular';
 		await el.updateComplete;
 		const progress = el.shadowRoot?.querySelector('[role="progressbar"]');
 		expect(progress?.classList.contains('progress-circular')).toBe(true);
 	});
 
-	it('renders circle wavy for circular-wavy variant', async () => {
+	it('renderiza circle wavy para la variante circular-wavy', async () => {
 		el.variant = 'circular-wavy';
 		await el.updateComplete;
 		const progress = el.shadowRoot?.querySelector('[role="progressbar"]');
 		expect(progress?.classList.contains('progress-circular')).toBe(true);
 	});
 
-	it('renders progress-wavy container for wavy variant', async () => {
+	it('renderiza el contenedor progress-wavy para la variante wavy', async () => {
 		el.variant = 'wavy';
 		await el.updateComplete;
 		const progress = el.shadowRoot?.querySelector('[role="progressbar"]');
 		expect(progress?.classList.contains('progress-wavy')).toBe(true);
 	});
 
-	it('reflects the size attribute', async () => {
+	it('refleja el atributo size', async () => {
 		el.size = 'large';
 		await el.updateComplete;
 		expect(el.getAttribute('size')).toBe('large');