@moni-labs/moni-ui 0.3.0 → 0.3.2

package/src/components/moni-color-field.test.ts

@@ -14,7 +14,7 @@ describe('moni-color-field', () => {
 		el.remove();
 	});
 
-	it('renders a swatch and a text input', async () => {
+	it('renderiza una muestra (swatch) y un input de texto', async () => {
 		await el.updateComplete;
 		const swatch = el.shadowRoot?.querySelector('.swatch');
 		const text = el.shadowRoot?.querySelector('input[type="text"]');
@@ -22,14 +22,14 @@ describe('moni-color-field', () => {
 		expect(text).toBeTruthy();
 	});
 
-	it('adds active class to the text input when value is set', async () => {
+	it('agrega la clase active al input de texto cuando se establece el valor', async () => {
 		el.value = '#ff00aa';
 		await el.updateComplete;
 		const text = el.shadowRoot?.querySelector('input[type="text"]');
 		expect(text?.classList.contains('active')).toBe(true);
 	});
 
-	it('forwards value to the text input', async () => {
+	it('reenvía el valor al input de texto', async () => {
 		el.value = '#123456';
 		await el.updateComplete;
 		const text = el.shadowRoot?.querySelector(
@@ -38,7 +38,7 @@ describe('moni-color-field', () => {
 		expect(text.value).toBe('#123456');
 	});
 
-	it('keeps the text input readonly (so the label can be lifted via .active)', async () => {
+	it('mantiene el input de texto en readonly (para que la etiqueta pueda elevarse vía .active)', async () => {
 		await el.updateComplete;
 		const text = el.shadowRoot?.querySelector(
 			'input[type="text"]'
@@ -46,7 +46,7 @@ describe('moni-color-field', () => {
 		expect(text.hasAttribute('readonly')).toBe(true);
 	});
 
-	it('renders label element adjacent to the text input for BeerCSS selector matching', async () => {
+	it('renderiza el elemento label adyacente al input de texto para el selector de BeerCSS', async () => {
 		el.label = 'Pick a color';
 		await el.updateComplete;
 		const text = el.shadowRoot?.querySelector('input[type="text"]');

package/src/components/moni-color-field.ts

@@ -12,63 +12,123 @@ import { classMap } from 'lit/directives/class-map.js';
 import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
 
 /**
- * Material Design 3 Color Field component.
+ * Componente Material Design 3 Color Field (Campo de Color).
  *
- * A specialized text field for color input that combines a native
- * `<input type="color">` with a read-only text display of the selected
- * hex value, wrapped in the standard M3 field shell.
+ * 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.
  *
- * **Visual architecture:**
- * Extends the field styling pattern used by `<moni-text-field>`. The
- * leading icon slot is replaced by a circular color swatch (`.swatch`)
- * which is absolutely positioned over an invisible native color input.
- * Clicking the swatch opens the system color picker. The text input portion
- * displays the selected hex code and is strictly `readOnly`.
+ * **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`.
  *
- * **State syncing:**
- * The component listens to the native `change` event on the color input,
- * updates the `value` property, and re-dispatches a composed `'change'` event.
- * It does not listen to `input` (continuous drag in the color picker) to avoid
- * excessive event firing, but consumers can attach their own `input` listeners
- * directly to the element if live preview is needed.
+ * **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.
  *
- * @fires change - Bubbles and is composed. Fired when the color picker closes
- *                 and the value is committed. Read `element.value`.
+ * @fires change - Burbujea y está compuesto. Se dispara cuando el selector de color se cierra
+ *                 y el valor se confirma. Leer `element.value`.
  *
  * @example
  * ```html
  * <moni-color-field
- *   label="Theme Color"
+ *   label="Color del Tema"
  *   name="primaryColor"
  *   value="#6750a4"
  *   variant="outlined"
  * ></moni-color-field>
  * ```
  *
- * @csspart field       - The outer `.field` div container.
- * @csspart swatch      - The circular color preview element.
- * @csspart input-color - The native, visually hidden `<input type="color">`.
- * @csspart input-text  - The native `<input type="text">` displaying the hex code.
- * @csspart label       - The floating `<label>` element.
+ * @csspart field       - El contenedor div exterior `.field`.
+ * @csspart swatch      - El elemento de vista previa de color circular.
+ * @csspart input-color - El `<input type="color">` nativo, visualmente oculto.
+ * @csspart input-text  - El `<input type="text">` nativo que muestra el código hexadecimal.
+ * @csspart label       - El elemento flotante `<label>`.
  */
 @customElement('moni-color-field')
 export class MoniColorField extends MoniElement {
+	/**
+	 * El nombre del input, enviado con los datos del formulario.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) name = '';
+
+	/**
+	 * El texto de la etiqueta flotante.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) label = '';
+
+	/**
+	 * Variante visual del campo de texto.
+	 * @type {'filled' | 'outlined'}
+	 * @default 'outlined'
+	 */
 	@property({ reflect: true }) variant: 'filled' | 'outlined' = 'outlined';
+
+	/**
+	 * Define las dimensiones del campo de texto.
+	 * @type {'small' | 'medium' | 'large' | 'extra'}
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'small' | 'medium' | 'large' | 'extra' = 'medium';
+
+	/**
+	 * Forma del radio del borde del campo.
+	 * @type {'round' | 'square' | 'no-round'}
+	 * @default 'no-round'
+	 */
 	@property({ reflect: true })
 	shape: 'round' | 'square' | 'no-round' = 'no-round';
+
+	/**
+	 * Deshabilita el campo de color.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
+
+	/**
+	 * Texto de ayuda mostrado debajo del campo.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) helper = '';
+
+	/**
+	 * Texto de error mostrado debajo del campo cuando `error` es true.
+	 * Sobrescribe el texto de ayuda.
+	 * @type {string}
+	 */
 	@property({ reflect: true, attribute: 'error-text' }) errorText = '';
+
+	/**
+	 * Si es true, establece el campo en un estado de error.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) error = false;
+
+	/**
+	 * El valor actual del color hexadecimal.
+	 * @type {string}
+	 * @default '#6750a4'
+	 */
 	@property({ reflect: true }) value = '#6750a4';
 
 	@query('input[type="color"]') private _colorInput!: HTMLInputElement;
 	@query('input[type="text"]') private _textInput!: HTMLInputElement;
 
+	/**
+	 * Hook de ciclo de vida de Lit.
+	 * Sincroniza manualmente el estado reactivo (`value`, `disabled`) con los
+	 * elementos nativos del DOM subyacente. Se hace manualmente porque el input
+	 * de tipo color no despacha eventos de forma natural si mutamos sus atributos.
+	 */
 	override updated(changed: Map<string, unknown>) {
 		if (changed.has('value')) {
 			if (this._colorInput) this._colorInput.value = this.value;
@@ -108,6 +168,30 @@ export class MoniColorField extends MoniElement {
 		`
 	];
 
+	/**
+	 * Ensambla la estructura del Shadow DOM del campo de color.
+	 *
+	 * **Estrategia de input en capas:**
+	 * Dos elementos `<input>` se apilan absolutamente:
+	 * 1. `<input type="color">` (z-index: 2, opacidad: 0) — invisible pero
+	 *    clicable, abre el selector de color nativo del sistema operativo.
+	 * 2. `<input type="text" readonly>` (z-index: 0) — visible, muestra el
+	 *    valor hexadecimal. `tabindex="-1"` en el input de color significa que
+	 *    solo el input de texto es alcanzable por teclado.
+	 *
+	 * El círculo `.swatch` (z-index: 1) está posicionado absolutamente en el
+	 * borde inicial del input de texto y estilizado a través de `--_swatch: ${this.value}`,
+	 * lo cual establece su `background-color` mediante CSS `var(--_swatch)`.
+	 *
+	 * **Composición de `fieldClasses`:**
+	 * El mapa de clases sigue la convención de nomenclatura field-styles de BeerCSS:
+	 * `field`, `label`, `fill`/`border` (variante), `small`/`large`/`extra` (tamaño),
+	 * `prefix` (activa el cambio de padding inicial para la muestra), `invalid`, forma.
+	 *
+	 * **Renderizado condicional de etiqueta / ayuda:**
+	 * Usa el centinela `nothing` de Lit para evitar renderizar nodos DOM vacíos cuando
+	 * `label` o `helper` son cadenas vacías, previniendo saltos de diseño.
+	 */
 	override render() {
 		const isActive = Boolean(this.value);
 		const fieldClasses = {

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

@@ -17,33 +17,33 @@ describe('moni-context-menu (P3.5 — flip)', () => {
 		parent.remove();
 	});
 
-	it('renders a <moni-menu> in the shadow DOM', async () => {
+	it('renderiza un <moni-menu> en el shadow DOM', async () => {
 		await el.updateComplete;
 		const menu = el.shadowRoot?.querySelector('moni-menu');
 		expect(menu).toBeTruthy();
 	});
 
-	it('reflects placement=bottom (default)', async () => {
+	it('refleja placement=bottom (por defecto)', async () => {
 		await el.updateComplete;
 		expect(el.placement).toBe('bottom');
 		const menu = el.shadowRoot?.querySelector('moni-menu');
 		expect(menu?.getAttribute('placement')).toBe('bottom');
 	});
 
-	it('reflects placement changes on the inner menu', async () => {
+	it('refleja los cambios de placement en el menú interno', async () => {
 		el.placement = 'top';
 		await el.updateComplete;
 		const menu = el.shadowRoot?.querySelector('moni-menu');
 		expect(menu?.getAttribute('placement')).toBe('top');
 	});
 
-	it('reflects the 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('opens the menu on right-click on the parent', async () => {
+	it('abre el menú al hacer clic derecho en el padre', async () => {
 		await el.updateComplete;
 		const menu = el.shadowRoot?.querySelector(
 			'moni-menu'
@@ -60,7 +60,7 @@ describe('moni-context-menu (P3.5 — flip)', () => {
 		expect(menu?.hasAttribute('active')).toBe(true);
 	});
 
-	it('closes the menu on document click', async () => {
+	it('cierra el menú al hacer clic en el documento', async () => {
 		await el.updateComplete;
 		const menu = el.shadowRoot?.querySelector(
 			'moni-menu'
@@ -74,7 +74,7 @@ describe('moni-context-menu (P3.5 — flip)', () => {
 		expect(menu?.hasAttribute('active')).toBe(false);
 	});
 
-	it('closes the menu on Escape', async () => {
+	it('cierra el menú al presionar Escape', async () => {
 		await el.updateComplete;
 		const menu = el.shadowRoot?.querySelector(
 			'moni-menu'
@@ -88,10 +88,10 @@ describe('moni-context-menu (P3.5 — flip)', () => {
 		expect(menu?.hasAttribute('active')).toBe(false);
 	});
 
-	it('does not call showPopover (visual-only; no Popover API)', async () => {
-		// Sanity: the component is visual-only. The moni-menu inside handles
-		// the active attribute via CSS visibility/opacity. No native popover
-		// toggling.
+	it('no llama a showPopover (solo visual; sin API Popover)', async () => {
+		// Sanidad: el componente es solo visual. El moni-menu interior maneja
+		// el atributo active vía visibility/opacity de CSS. No hay popover nativo
+		// de cambio.
 		await el.updateComplete;
 		const menu = el.shadowRoot?.querySelector('moni-menu');
 		expect(menu?.hasAttribute('popover')).toBe(false);

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

@@ -11,47 +11,47 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-menu.js';
 
 /**
- * Material Design 3 Context Menu component.
+ * Componente Material Design 3 Context Menu (Menú Contextual).
  *
- * A specialized menu that opens at the exact coordinates of a pointer event,
- * typically triggered by a right-click (`contextmenu` event). It provides
- * contextual actions related to the specific item clicked.
+ * 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.
  *
- * **M3 spec reference:** `m3-docs/components/menus/specs.md` (Contextual menus)
+ * **Referencia de la especificación M3:** `m3-docs/components/menus/specs.md` (Menús contextuales)
  *
- * **Triggering mechanism:**
- * The component does not require programmatic triggering via an `open` property.
- * Instead, it attaches a `contextmenu` event listener to its parent element
- * during `connectedCallback`. When the parent is right-clicked, the menu
- * captures the `clientX`/`clientY` coordinates, prevents the default browser
- * context menu, and opens itself at the cursor position using `position: fixed`.
+ * **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`.
  *
- * **Auto-flip behavior (`flip` attribute):**
- * Per the M3 guidelines, menus should flip to the opposite side of the cursor
- * if opening in the requested `placement` would cause them to overflow the
- * viewport. When `flip=true`, the component dynamically calculates viewport
- * bounds before opening and overrides `placement` if necessary (e.g., flipping
- * from `bottom` to `top` if clicked near the bottom of the screen).
+ * **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-dismiss:**
- * Closes automatically when clicking anywhere outside the menu, or when
- * pressing the `Escape` key.
+ * **Auto-descarte:**
+ * Se cierra automáticamente al hacer clic en cualquier lugar fuera del menú, o al
+ * presionar la tecla `Escape`.
  *
  * @example
  * ```html
- * <!-- Wrap the trigger area and the menu in a container -->
+ * <!-- Envuelve el área de activación y el menú en un contenedor -->
  * <div>
- *   <p>Right-click me for options</p>
+ *   <p>Haz clic derecho para ver las opciones</p>
  *   <moni-context-menu flip>
- *     <moni-menu-item>Copy</moni-menu-item>
- *     <moni-menu-item>Paste</moni-menu-item>
+ *     <moni-menu-item>Copiar</moni-menu-item>
+ *     <moni-menu-item>Pegar</moni-menu-item>
  *     <moni-divider></moni-divider>
- *     <moni-menu-item>Delete</moni-menu-item>
+ *     <moni-menu-item>Eliminar</moni-menu-item>
  *   </moni-context-menu>
  * </div>
  * ```
  *
- * @slot default - The `<moni-menu-item>` elements that make up the menu.
+ * @slot default - Los elementos `<moni-menu-item>` que componen el menú.
  */
 @customElement('moni-context-menu')
 export class MoniContextMenu extends MoniElement {
@@ -67,8 +67,18 @@ export class MoniContextMenu extends MoniElement {
 	@query('moni-menu') private _menuEl?: HTMLElement;
 
 	private _target: HTMLElement | null = null;
+	/**
+	 * Wrapper estático para el manejador de teclado global.
+	 * Conserva la referencia exacta para desregistrar el evento en `disconnectedCallback`.
+	 */
 	private _docKeydown = (e: KeyboardEvent) => this._onDocKeydown(e);
 
+	/**
+	 * Hook de inicialización (Lit).
+	 * Atrapa al elemento padre directo y le inyecta `position: relative` (si era static)
+	 * para que las coordenadas de despliegue del menú floten correctamente.
+	 * Adjunta los eventos nativos de `contextmenu` (clic derecho) al contenedor.
+	 */
 	override connectedCallback() {
 		super.connectedCallback();
 		this._target = this.parentElement;
@@ -84,6 +94,11 @@ export class MoniContextMenu extends MoniElement {
 		document.addEventListener('keydown', this._docKeydown);
 	}
 
+	/**
+	 * Hook de destrucción (Lit).
+	 * Limpia los detectores de clic derecho y atajos de teclado para eludir memory leaks
+	 * al desmontarse del DOM.
+	 */
 	override disconnectedCallback() {
 		if (this._target) {
 			this._target.removeEventListener('contextmenu', this._onContextMenu);
@@ -93,6 +108,11 @@ export class MoniContextMenu extends MoniElement {
 		super.disconnectedCallback();
 	}
 
+	/**
+	 * Intercepta el clic derecho (`contextmenu`) del navegador de forma nativa.
+	 * Previene el menú por defecto del SO y captura las coordenadas X/Y del ratón
+	 * relativas al elemento anfitrión para ubicar milimétricamente el popup personalizado.
+	 */
 	private _onContextMenu = (e: MouseEvent) => {
 		e.preventDefault();
 		if (this._target) {
@@ -105,10 +125,16 @@ export class MoniContextMenu extends MoniElement {
 		}
 		this._resolvedPlacement = this.placement;
 		this._open = true;
-		// After Lit renders the menu, check viewport fit and flip if needed.
+		// Después de que Lit renderice el menú, verificar el ajuste al viewport y voltear si es necesario.
 		this.updateComplete.then(() => this._maybeFlip());
 	};
 
+	/**
+	 * Sistema de Colisión/Desbordamiento de Ventana.
+	 * Si la directiva `flip` está habilitada, examina los límites (BoundingClientRect)
+	 * del menú tras su renderizado y altera su `placement` sobre la marcha si éste
+	 * colisiona con el borde del Viewport, invirtiendo top/bottom o left/right.
+	 */
 	private _maybeFlip() {
 		if (!this.flip) return;
 		const menu = this._menuEl?.shadowRoot?.querySelector('menu') as HTMLElement | null;
@@ -129,12 +155,20 @@ export class MoniContextMenu extends MoniElement {
 		}
 	}
 
+	/**
+	 * Cierra instintivamente el menú contextual si el usuario hace clic en 
+	 * cualquier zona exterior al mismo.
+	 */
 	private _onDocumentClick = () => {
 		if (this._open) {
 			this._open = false;
 		}
 	};
 
+	/**
+	 * Escucha la tecla Escape a nivel documento para cerrar el menú si se
+	 * encuentra desplegado, cumpliendo con los estándares de accesibilidad (WAI-ARIA).
+	 */
 	private _onDocKeydown = (e: KeyboardEvent) => {
 		if (e.key === 'Escape' && this._open) {
 			this._open = false;
@@ -159,10 +193,22 @@ export class MoniContextMenu extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el menú contextual como una superposición de Popover API posicionada en las coordenadas del puntero.
+	 *
+	 * El `<div>` del menú usa `popover="manual"` para que aparezca en la capa superior
+	 * por encima de todo el otro contenido. Sus `top` y `left` se establecen mediante propiedades personalizadas CSS
+	 * `--_x` / `--_y` (inyectadas como estilo en línea) que se calculan
+	 * a partir de `clientX` / `clientY` del evento `contextmenu`.
+	 *
+	 * El `@click` en el fondo (fuera de los límites del menú) llama a `hidePopover()`
+	 * para descartar ligeramente el menú contextual. Los elementos dentro del menú deben llamar a
+	 * `event.stopPropagation()` para evitar el cierre accidental al hacer clic en un elemento.
+	 */
 	override render() {
-		// When the menu is open, prefer the resolved (possibly flipped)
-		// placement; otherwise just use the host's requested placement so
-		// the inner element reflects the attribute synchronously.
+		// Cuando el menú está abierto, preferir la ubicación resuelta (posiblemente volteada);
+		// de lo contrario, simplemente usar la ubicación solicitada por el host para que
+		// el elemento interno refleje el atributo sincrónicamente.
 		const effectivePlacement = this._open
 			? this._resolvedPlacement
 			: this.placement;