@moni-labs/moni-ui 0.3.0 → 0.3.2

package/src/components/moni-menu.ts

@@ -10,44 +10,44 @@ import { customElement, property, query, state } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Material Design 3 Menu component.
+ * Componente Material Design 3 Menu (Menú).
  *
- * Menus display a list of choices on a temporary surface. They appear when
- * users interact with a button, action, or other control.
+ * 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.
  *
- * **M3 spec reference:** `m3-docs/components/menus/guidelines.md`
+ * **Referencia de la especificación M3:** `m3-docs/components/menus/guidelines.md`
  *
- * **Positioning architecture:**
- * The menu uses `position: absolute` relative to its nearest positioned
- * ancestor. The component's `:host` uses `display: contents`, meaning the
- * inner `<menu>` element directly participates in the consumer's layout context.
- * **Crucial:** The consumer must apply `position: relative` to the wrapper
- * element that contains both the trigger and the `<moni-menu>`.
+ * **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>`.
  *
- * **Auto-flip positioning:**
- * Per M3 guidelines, menus should flip to the opposite side of the anchor
- * if they overflow the viewport.
- * - **Modern browsers (Chrome/Edge 125+, Safari 18+):** Uses CSS anchor
- *   positioning and `@position-try-fallback` natively when `flip=true`.
- * - **Fallback:** A JavaScript polyfill measures the menu after it opens. If
- *   it overflows the requested `placement`, it sets an internal state to flip
- *   the placement classes.
+ * **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.
  *
- * **State management:**
- * The `active` attribute controls visibility. Consumers must listen to trigger
- * events (like `click`) and toggle the `active` property.
+ * **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`.
  *
  * @example
  * ```html
- * <!-- Wrapper must have position: relative -->
+ * <!-- El contenedor debe tener position: relative -->
  * <div style="position: relative; display: inline-block;">
- *   <moni-button id="menu-trigger">Open Menu</moni-button>
+ *   <moni-button id="menu-trigger">Abrir Menú</moni-button>
  *
  *   <moni-menu placement="bottom" flip id="my-menu">
- *     <moni-menu-item icon="edit">Edit</moni-menu-item>
- *     <moni-menu-item icon="content_copy">Copy</moni-menu-item>
+ *     <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">Delete</moni-menu-item>
+ *     <moni-menu-item icon="delete">Eliminar</moni-menu-item>
  *   </moni-menu>
  * </div>
  *
@@ -58,16 +58,37 @@ import { MoniElement, sharedStyles } from './_base/index.js';
  * </script>
  * ```
  *
- * @slot default - `<moni-menu-item>`, `<moni-divider>`, or raw `<li>` elements.
+ * @slot default - Elementos `<moni-menu-item>`, `<moni-divider>`, o elementos `<li>` en bruto.
  *
- * @csspart menu - The inner `<menu>` container.
+ * @csspart menu - El contenedor interior `<menu>`.
  */
 @customElement('moni-menu')
 export class MoniMenu extends MoniElement {
+	/**
+	 * Posición preferida en relación con el anclaje padre.
+	 * @type {'bottom' | 'top' | 'left' | 'right' | 'min' | 'max'}
+	 * @default 'bottom'
+	 */
 	@property({ reflect: true })
 	placement: 'bottom' | 'top' | 'left' | 'right' | 'min' | 'max' = 'bottom';
+
+	/**
+	 * Deshabilita el ajuste de texto dentro del menú.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true, attribute: 'no-wrap' }) noWrap = false;
+
+	/**
+	 * Controla si el menú está visible.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) active = false;
+
+	/**
+	 * Lógica de espaciado entre el anclaje y el menú.
+	 * @type {'no-space' | 'space' | 'small-space' | 'medium-space' | 'large-space' | 'extra-space'}
+	 * @default 'no-space'
+	 */
 	@property({ reflect: true })
 	space:
 		| 'no-space'
@@ -76,6 +97,12 @@ export class MoniMenu extends MoniElement {
 		| 'medium-space'
 		| 'large-space'
 		| 'extra-space' = 'no-space';
+
+	/**
+	 * 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.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) flip = false;
 
 	@state() private _resolvedPlacement:
@@ -88,25 +115,36 @@ export class MoniMenu extends MoniElement {
 
 	@query('menu') private _menuEl?: HTMLElement;
 
+	/**
+	 * Hook de ciclo de vida de Lit.
+	 * Detecta si el menú se acaba de abrir (active = true) con la propiedad de 'flip' habilitada.
+	 * Usa una Promesa (`updateComplete`) para esperar a que Lit termine de renderizar el DOM y 
+	 * el navegador haga el reflow antes de medir sus dimensiones.
+	 */
 	override updated(changed: Map<string, unknown>) {
 		super.updated(changed);
 		if (changed.has('active') && this.active && this.flip) {
-			// JS polyfill for browsers without @position-try-fallback.
-			// Wait one frame so the menu is laid out, then measure.
 			this.updateComplete.then(() => this._maybeFlip());
 		}
 	}
 
+	/**
+	 * Polyfill manual en JS para "position-try-fallbacks" (CSS Anchoring API).
+	 * Si el menú desborda el viewport en su posición actual, invierte lógicamente
+	 * su colocación (ej. de 'bottom' a 'top') calculando los BoundingClientRect.
+	 */
 	private _maybeFlip() {
 		const menu = this._menuEl;
 		if (!menu || !this.flip) return;
 		const rect = menu.getBoundingClientRect();
 		const vw = window.innerWidth;
 		const vh = window.innerHeight;
+		
 		const overflowsBottom = rect.bottom > vh;
 		const overflowsTop = rect.top < 0;
 		const overflowsRight = rect.right > vw;
 		const overflowsLeft = rect.left < 0;
+		
 		if (this.placement === 'bottom' && overflowsBottom) {
 			this._resolvedPlacement = 'top';
 		} else if (this.placement === 'top' && overflowsTop) {
@@ -284,6 +322,25 @@ export class MoniMenu extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el menú como una superposición Popover API o un `<div>` posicionado.
+	 *
+	 * **Popover API (`popover="auto"`):**
+	 * Cuando se establece `popover`, el menú usa la Popover API nativa del navegador.
+	 * Esto proporciona descarte ligero (light-dismiss) automático (clic fuera para cerrar) y
+	 * apilamiento en la capa superior sin gestión de `z-index`.
+	 *
+	 * **Patrón de menú ARIA:**
+	 * El contenedor del menú lleva `role="menu"`. Cada hijo `<moni-menu-item>`
+	 * debe llevar `role="menuitem"`. La navegación con las teclas de flecha se maneja a través de
+	 * `@keydown` en el contenedor del menú, ciclando a través de los elementos usando
+	 * `_focusedItemIndex` (incrementado/decrementado con ciclo continuo).
+	 *
+	 * **Posicionamiento:**
+	 * Cuando se establece `anchor`, `_computeStyle()` calcula `top`/`left` desde
+	 * `getBoundingClientRect()` del elemento anclaje y los inyecta como
+	 * estilos en línea en el `<div>` del menú.
+	 */
 	override render() {
 		const effectivePlacement = this.active && this.flip
 			? this._resolvedPlacement

package/src/components/moni-morph-modal.test.ts

@@ -74,11 +74,11 @@ describe('moni-morph-modal', () => {
 		target.remove();
 	});
 
-	it('registers the custom element', () => {
+	it('registra el elemento personalizado', () => {
 		expect(customElements.get('moni-morph-modal')).toBeTruthy();
 	});
 
-	it('renders a panel and a backdrop in shadow root', async () => {
+	it('renderiza un panel y un backdrop en el shadow root', async () => {
 		await el.updateComplete;
 		const panel = el.shadowRoot?.querySelector('.panel');
 		const backdrop = el.shadowRoot?.querySelector('.backdrop');
@@ -86,18 +86,18 @@ describe('moni-morph-modal', () => {
 		expect(backdrop).toBeTruthy();
 	});
 
-	it('reflects the target attribute', async () => {
+	it('refleja el atributo target', async () => {
 		await el.updateComplete;
 		expect(el.getAttribute('target')).toBe('#test-target');
 	});
 
-	it('reflects the open attribute', async () => {
+	it('refleja el atributo open', async () => {
 		el.open = true;
 		await el.updateComplete;
 		expect(el.hasAttribute('open')).toBe(true);
 	});
 
-	it('projects the default slot content', async () => {
+	it('proyecta el contenido del slot por defecto', async () => {
 		const content = document.createElement('p');
 		content.textContent = 'Hello';
 		el.appendChild(content);
@@ -108,7 +108,7 @@ describe('moni-morph-modal', () => {
 		expect(slot).toBeTruthy();
 	});
 
-	it('projects the header slot content', async () => {
+	it('proyecta el contenido del slot header', async () => {
 		const header = document.createElement('div');
 		header.setAttribute('slot', 'header');
 		header.textContent = 'Title';
@@ -118,7 +118,7 @@ describe('moni-morph-modal', () => {
 		expect(headerSlot).toBeTruthy();
 	});
 
-	it('projects the footer slot content', async () => {
+	it('proyecta el contenido del slot footer', async () => {
 		const footer = document.createElement('div');
 		footer.setAttribute('slot', 'footer');
 		footer.textContent = 'Actions';
@@ -128,14 +128,14 @@ describe('moni-morph-modal', () => {
 		expect(footerSlot).toBeTruthy();
 	});
 
-	it('shows the close button when show-close-button is true', async () => {
+	it('muestra el botón de cerrar cuando show-close-button es true', async () => {
 		el.showCloseButton = true;
 		await el.updateComplete;
 		const closeBtn = el.shadowRoot?.querySelector('.close-btn');
 		expect(closeBtn).toBeTruthy();
 	});
 
-	it('toggles open state when show() and hide() are called', async () => {
+	it('alterna el estado open cuando se llaman a show() y hide()', async () => {
 		expect(el.open).toBe(false);
 		el.show();
 		await waitForRaf();
@@ -145,7 +145,7 @@ describe('moni-morph-modal', () => {
 		expect(el.open).toBe(false);
 	});
 
-	it('toggles open state when toggle() is called', async () => {
+	it('alterna el estado open cuando se llama a toggle()', async () => {
 		el.toggle();
 		await waitForRaf();
 		expect(el.open).toBe(true);
@@ -154,11 +154,12 @@ describe('moni-morph-modal', () => {
 		expect(el.open).toBe(false);
 	});
 
-	it('warns when target is not found', () => {
+	it('advierte cuando no se encuentra el objetivo (target)', () => {
 		const warnSpy = vi.spyOn(console, 'warn').mockImplementation(() => {});
 		const modal = document.createElement('moni-morph-modal') as MoniMorphModal;
 		modal.target = '#missing-target';
 		document.body.appendChild(modal);
+		modal.show();
 		const call = warnSpy.mock.calls.find((c) =>
 			String(c[0]).includes('[moni-morph-modal]')
 		);
@@ -167,7 +168,7 @@ describe('moni-morph-modal', () => {
 		warnSpy.mockRestore();
 	});
 
-	it('supports recursive declaration of nested morph modals', async () => {
+	it('soporta la declaración recursiva de modales morph anidados', async () => {
 		const innerTarget = document.createElement('button');
 		innerTarget.id = 'inner-target';
 		el.appendChild(innerTarget);
@@ -188,14 +189,14 @@ describe('moni-morph-modal', () => {
 		innerTarget.remove();
 	});
 
-	it('does not create morph elements by default', async () => {
+	it('no crea elementos morph por defecto', async () => {
 		el.show();
 		await waitForRaf();
 		expect(el.shadowRoot?.querySelector('.morph-text')).toBeFalsy();
 		expect(el.shadowRoot?.querySelector('.morph-icon')).toBeFalsy();
 	});
 
-	it('creates and cleans up morph-text when morph-label is true', async () => {
+	it('crea y limpia morph-text cuando morph-label es true', async () => {
 		(el as unknown as { _hasHeader: boolean })._hasHeader = true;
 		el.morphLabel = true;
 		await el.updateComplete;
@@ -212,7 +213,7 @@ describe('moni-morph-modal', () => {
 		createSpy.mockRestore();
 	});
 
-	it('uses trigger-label slot content when provided', async () => {
+	it('usa el contenido del slot trigger-label cuando se proporciona', async () => {
 		const triggerLabel = document.createElement('span');
 		triggerLabel.setAttribute('slot', 'trigger-label');
 		triggerLabel.textContent = 'Custom label';
@@ -237,7 +238,7 @@ describe('moni-morph-modal', () => {
 		getNodes.mockRestore();
 	});
 
-	it('runs label FLIP on close when morph-label is true', async () => {
+	it('ejecuta la animación FLIP de label al cerrar cuando morph-label es true', async () => {
 		(el as unknown as { _hasHeader: boolean })._hasHeader = true;
 		el.morphLabel = true;
 		await el.updateComplete;
@@ -257,7 +258,7 @@ describe('moni-morph-modal', () => {
 		closeSpy.mockRestore();
 	});
 
-	it('does not create morph elements when reduced motion is preferred', async () => {
+	it('no crea elementos morph cuando se prefiere movimiento reducido (reduced motion)', async () => {
 		(el as unknown as { _hasHeader: boolean })._hasHeader = true;
 		el.morphLabel = true;
 		await el.updateComplete;