@moni-labs/moni-ui 0.3.0 → 0.3.2

package/src/components/moni-toolbar.ts

@@ -10,46 +10,46 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Material Design 3 Top App Bar (Toolbar) component.
+ * Componente Material Design 3 Top App Bar (Barra de herramientas superior).
  *
- * Top app bars display information and actions at the top of a screen.
- * They are used for branding, screen titles, navigation, and actions.
+ * Las barras de aplicación superiores muestran información y acciones en la parte superior de una pantalla.
+ * Se utilizan para identidad de marca, títulos de pantalla, navegación y acciones.
  *
- * **M3 spec reference:** `m3-docs/components/top-app-bar/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/top-app-bar/specs.md`
  *
- * **Note:** This is the standard top-level toolbar. For bottom navigation
- * bars (often used on mobile), use `<moni-app-bar>`.
+ * **Nota:** Esta es la barra de herramientas estándar de nivel superior. Para barras de navegación
+ * inferiores (a menudo usadas en móviles), usa `<moni-app-bar>`.
  *
- * **Variants:**
- * - `standard` (default): A full-width bar (64dp height) that sits flush
- *   against the top of the screen.
- * - `floating`: A detached bar with a 4dp margin and rounded 8dp corners,
- *   appearing to float above the content.
+ * **Variantes:**
+ * - `standard` (por defecto): Una barra de ancho completo (altura de 64dp) que se asienta al ras
+ *   contra la parte superior de la pantalla.
+ * - `floating`: Una barra separada con un margen de 4dp y esquinas redondeadas de 8dp,
+ *   que parece flotar sobre el contenido.
  *
- * **Scroll behavior:**
- * When the `scroll` attribute is present, the toolbar visually responds to
- * scrolling by increasing its elevation (shadow) and dynamically shifting
- * its surface color to indicate depth over the scrolling content.
+ * **Comportamiento de desplazamiento (scroll):**
+ * Cuando el atributo `scroll` está presente, la barra de herramientas responde visualmente al
+ * desplazamiento aumentando su elevación (sombra) y cambiando dinámicamente
+ * su color de superficie para indicar profundidad sobre el contenido desplazado.
  *
  * @example
  * ```html
- * <!-- Standard toolbar with navigation and actions -->
- * <moni-toolbar title="Inbox">
+ * <!-- Barra de herramientas estándar con navegación y acciones -->
+ * <moni-toolbar title="Bandeja de entrada">
  *   <moni-icon-button slot="leading" icon="menu"></moni-icon-button>
  *   <moni-icon-button slot="trailing" icon="search"></moni-icon-button>
  *   <moni-icon-button slot="trailing" icon="more_vert"></moni-icon-button>
  * </moni-toolbar>
  *
- * <!-- Floating toolbar with an attached FAB -->
- * <moni-toolbar type="floating" title="Notes">
+ * <!-- Barra de herramientas flotante con un FAB adjunto -->
+ * <moni-toolbar type="floating" title="Notas">
  *   <moni-fab slot="action-button" icon="add"></moni-fab>
  * </moni-toolbar>
  * ```
  *
- * @slot default       - The title text or center content.
- * @slot leading       - Navigation icon/button placed on the far left.
- * @slot trailing      - Action icons/buttons placed on the far right.
- * @slot action-button - A floating action button (FAB) anchored to the right side.
+ * @slot default       - El texto del título o contenido central.
+ * @slot leading       - Icono/botón de navegación colocado en el extremo izquierdo.
+ * @slot trailing      - Iconos/botones de acción colocados en el extremo derecho.
+ * @slot action-button - Un botón de acción flotante (FAB) anclado al lado derecho.
  */
 @customElement('moni-toolbar')
 export class MoniToolbar extends MoniElement {
@@ -123,6 +123,20 @@ export class MoniToolbar extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el diseño `<header>` de 3 zonas de la barra de herramientas.
+	 *
+	 * **Zonas:**
+	 * - `.leading` — slot inicial para iconos de navegación o controles de migas de pan (breadcrumb).
+	 * - `.title` — zona del título central; renderiza `this.title` como texto si el atributo
+	 *   está configurado, de lo contrario recurre al slot por defecto para contenido rico.
+	 * - `.trailing` — slot final para iconos de acción (buscar, más, etc.).
+	 *
+	 * **Slot `action-button`:**
+	 * Un slot nombrado separado, fuera del `<header>`, para un botón de acción flotante
+	 * (FAB) o disparador de menú contextual que no debe participar en el diseño
+	 * flex de la fila del título.
+	 */
 	override render() {
 		return html`
 			<header class="container" part="container">

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

@@ -18,24 +18,24 @@ describe('moni-tooltip (P3.1)', () => {
 		parent.remove();
 	});
 
-	it('renders role="tooltip" on the inner element (M3 a11y)', async () => {
+	it('renderiza role="tooltip" en el elemento interno (accesibilidad M3)', async () => {
 		await el.updateComplete;
 		const tip = el.shadowRoot?.querySelector('[role="tooltip"]');
 		expect(tip).toBeTruthy();
 	});
 
-	it('reflects the text on the host', async () => {
+	it('refleja el texto en el host', async () => {
 		await el.updateComplete;
 		expect(el.text).toBe('Save changes');
 	});
 
-	it('reflects position (default top)', async () => {
+	it('refleja la posición (top por defecto)', async () => {
 		await el.updateComplete;
 		const tip = el.shadowRoot?.querySelector('.tooltip');
 		expect(tip?.classList.contains('top')).toBe(true);
 	});
 
-	it('accepts all 6 M3 placements (top/top-start/top-end/bottom/bottom-start/bottom-end)', async () => {
+	it('acepta los 6 posicionamientos M3 (top/top-start/top-end/bottom/bottom-start/bottom-end)', async () => {
 		const positions: Array<'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'> = [
 			'top',
 			'top-start',
@@ -52,20 +52,20 @@ describe('moni-tooltip (P3.1)', () => {
 		}
 	});
 
-	it('defaults to plain (rich=false)', async () => {
+	it('es plano (plain) por defecto (rich=false)', async () => {
 		await el.updateComplete;
 		expect(el.rich).toBe(false);
 		expect(el.hasAttribute('rich')).toBe(false);
 	});
 
-	it('rich=true enables rich content mode (rich attribute reflected)', async () => {
+	it('rich=true habilita el modo de contenido enriquecido (atributo rich reflejado)', async () => {
 		el.rich = true;
 		await el.updateComplete;
 		expect(el.rich).toBe(true);
 		expect(el.hasAttribute('rich')).toBe(true);
 	});
 
-	it('shows the tooltip on mouseenter and hides on mouseleave', async () => {
+	it('muestra el tooltip en mouseenter y lo oculta en mouseleave', async () => {
 		await el.updateComplete;
 		const tip = el.shadowRoot?.querySelector('.tooltip') as HTMLElement;
 		expect(tip?.classList.contains('visible')).toBe(false);
@@ -79,7 +79,7 @@ describe('moni-tooltip (P3.1)', () => {
 		expect(tip?.classList.contains('visible')).toBe(false);
 	});
 
-	it('shows the tooltip on focusin and hides on focusout', async () => {
+	it('muestra el tooltip en focusin y lo oculta en focusout', async () => {
 		await el.updateComplete;
 		const tip = el.shadowRoot?.querySelector('.tooltip') as HTMLElement;
 		parent.dispatchEvent(new FocusEvent('focusin', { bubbles: true }));
@@ -91,7 +91,7 @@ describe('moni-tooltip (P3.1)', () => {
 		expect(tip?.classList.contains('visible')).toBe(false);
 	});
 
-	it('Escape key closes a visible tooltip', async () => {
+	it('la tecla Escape cierra un tooltip visible', async () => {
 		await el.updateComplete;
 		const tip = el.shadowRoot?.querySelector('.tooltip') as HTMLElement;
 		parent.dispatchEvent(new MouseEvent('mouseenter', { bubbles: true }));
@@ -103,20 +103,20 @@ describe('moni-tooltip (P3.1)', () => {
 		expect(tip?.classList.contains('visible')).toBe(false);
 	});
 
-	it('applies size variants (small/medium/large)', async () => {
+	it('aplica las variantes de tamaño (small/medium/large)', async () => {
 		for (const size of ['small', 'medium', 'large'] as const) {
 			el.size = size;
 			await el.updateComplete;
 			const tip = el.shadowRoot?.querySelector('.tooltip');
-			expect(tip?.classList.contains(size), `expected class ${size}`).toBe(true);
+			expect(tip?.classList.contains(size), `esperada clase ${size}`).toBe(true);
 		}
 	});
 
-	it('cleans up listeners on disconnect', () => {
-		// Sanity: removing the parent cleans up.
+	it('limpia los listeners al desconectarse', () => {
+		// Sanidad: remover el padre limpia todo.
 		parent.remove();
-		// No assertion needed; if listeners leaked, the next beforeEach would
-		// accumulate them but vitest would still pass. Visual coverage only.
+		// No se necesita aserción; si los listeners se fugaran, el siguiente beforeEach
+		// acumularía listeners pero vitest pasaría. Solo cobertura visual.
 		expect(parent.isConnected).toBe(false);
 	});
 });

package/src/components/moni-tooltip.ts

@@ -10,62 +10,72 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Material Design 3 Tooltip component.
+ * Componente Material Design 3 Tooltip (Información sobre herramientas).
  *
- * Tooltips provide contextual text labels or rich content that appear when
- * users hover over, focus on, or tap an element. They surface supplementary
- * information that helps users understand interface elements without
- * permanently occupying screen space.
+ * Los tooltips proporcionan etiquetas de texto contextual o contenido enriquecido que aparecen cuando
+ * los usuarios pasan el cursor por encima, enfocan o tocan un elemento. Muestran información
+ * complementaria que ayuda a los usuarios a entender los elementos de la interfaz sin
+ * ocupar permanentemente espacio en la pantalla.
  *
- * **M3 spec reference:** `m3-docs/components/tooltips/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/tooltips/specs.md`
  *
- * **Types:**
- * - **Plain** (default) — Text-only label for simple descriptions (max 1 line).
- * - **Rich** (`rich` attribute) — HTML content including formatted text,
- *   links, and icons. Rich tooltips can contain multiple lines and action links.
+ * **Tipos:**
+ * - **Plain** (por defecto) — Etiqueta solo de texto para descripciones simples (máx. 1 línea).
+ * - **Rich** (atributo `rich`) — Contenido HTML que incluye texto formateado,
+ *   enlaces e iconos. Los tooltips enriquecidos pueden contener múltiples líneas y enlaces de acción.
  *
- * **Placements:**
- * - `top` (default), `top-start`, `top-end`
+ * **Ubicaciones (Placements):**
+ * - `top` (por defecto), `top-start`, `top-end`
  * - `bottom`, `bottom-start`, `bottom-end`
  *
- * **Trigger mechanism:**
- * The tooltip uses `position: absolute` inside the parent element. The parent
- * must have `position: relative` (set automatically via `connectedCallback`).
- * Hover/focus events on the parent trigger the tooltip's CSS `:hover` and
- * `:focus-within` selectors, which drive the show/hide transition.
+ * **Mecanismo de activación (Trigger):**
+ * El tooltip usa `position: absolute` dentro del elemento padre. El padre
+ * debe tener `position: relative` (establecido automáticamente vía `connectedCallback`).
+ * Los eventos hover/focus en el padre activan los selectores CSS `:hover` y
+ * `:focus-within` del tooltip, los cuales impulsan la transición de mostrar/ocultar.
  *
- * **Accessibility:**
- * - The tooltip has `role="tooltip"`.
- * - For keyboard accessibility, the parent should have `aria-describedby`
- *   pointing to the tooltip's `id` attribute. The component exposes a
- *   `tooltipId` getter for this purpose.
- * - The `Escape` key closes rich tooltips.
+ * **Accesibilidad:**
+ * - El tooltip tiene `role="tooltip"`.
+ * - Para accesibilidad por teclado, el padre debe tener `aria-describedby`
+ *   apuntando al atributo `id` del tooltip. El componente expone un
+ *   getter `tooltipId` para este propósito.
+ * - La tecla `Escape` cierra los tooltips enriquecidos.
  *
  * @example
  * ```html
- * <!-- Plain tooltip -->
+ * <!-- Tooltip simple (Plain) -->
  * <button aria-describedby="save-tip">
- *   Save
+ *   Guardar
  *   <moni-tooltip id="save-tip" text="Ctrl+S"></moni-tooltip>
  * </button>
  *
- * <!-- Rich tooltip -->
+ * <!-- Tooltip enriquecido (Rich) -->
  * <button>
- *   Filter
+ *   Filtrar
  *   <moni-tooltip rich position="bottom">
- *     <strong>Filter by date</strong>
- *     <p>Select a date range to filter results.</p>
+ *     <strong>Filtrar por fecha</strong>
+ *     <p>Selecciona un rango de fechas para filtrar resultados.</p>
  *   </moni-tooltip>
  * </button>
  * ```
  *
- * @slot default - Rich content for the tooltip body (only used when `rich=true`).
+ * @slot default - Contenido enriquecido para el cuerpo del tooltip (solo usado cuando `rich=true`).
  *
- * @csspart tooltip - The tooltip container element.
+ * @csspart tooltip - El elemento contenedor del tooltip.
  */
 @customElement('moni-tooltip')
 export class MoniTooltip extends MoniElement {
+	/**
+	 * Contenido de texto simple para mostrar. Utilizado cuando `rich` es falso.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) text = '';
+
+	/**
+	 * Ubicación preferida relativa al ancla/activador.
+	 * @type {'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end'}
+	 * @default 'top'
+	 */
 	@property({ reflect: true })
 	position:
 		| 'top'
@@ -74,25 +84,47 @@ export class MoniTooltip extends MoniElement {
 		| 'bottom'
 		| 'bottom-start'
 		| 'bottom-end' = 'top';
+
+	/**
+	 * Mapeo de tamaño opcional (usado por hojas de estilo internas para escalar fuente/relleno).
+	 * @type {'' | 'small' | 'medium' | 'large'}
+	 * @default ''
+	 */
 	@property({ reflect: true })
 	size: '' | 'small' | 'medium' | 'large' = '';
+
+	/**
+	 * Si es true, cambia al modo de Tooltip Enriquecido (permite HTML/componentes en el slot por defecto).
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) rich = false;
 
 	private _target: HTMLElement | null = null;
 	private _tooltipEl: HTMLElement | null = null;
+	/**
+	 * Wrapper estático para el evento de teclado global.
+	 * Mantiene fijo el contexto léxico para registrar/desregistrar limpiamente.
+	 */
 	private _docKeydown = (e: KeyboardEvent) => this._handleDocKeydown(e);
 	/**
-	 * CSS `anchor-name` registered on the parent trigger so the tooltip
-	 * can use `position-anchor` to bind to it. Generated per-instance via
-	 * `crypto.randomUUID()` when CSS anchor positioning is supported.
+	 * Nombre de anclaje CSS (`anchor-name`) registrado en el activador padre para que el tooltip
+	 * pueda usar `position-anchor` para vincularse a él. Generado por instancia vía
+	 * `crypto.randomUUID()` cuando el posicionamiento de anclaje CSS está soportado.
 	 */
 	private _anchorName: string | null = null;
 
+	/**
+	 * Hook de inicialización (Lit).
+	 * Resuelve la asociación nativa con su elemento padre (trigger), forzando un contexto
+	 * de posicionamiento relativo (`position: relative`) si es necesario. Vincula dinámicamente
+	 * listeners de `mouseenter/leave` y `focusin/out` para controlar la visibilidad del globo.
+	 * También auto-registra la revolucionaria CSS Anchor Positioning API si el navegador la soporta.
+	 */
 	override connectedCallback() {
 		super.connectedCallback();
 		this._target = this.parentElement;
 		if (this._target) {
-			// Ensure parent has position: relative so absolute tooltip is anchored
+			// Asegura que el padre tenga position: relative para anclar el tooltip absoluto
 			const style = getComputedStyle(this._target);
 			if (style.position === 'static') {
 				this._target.style.position = 'relative';
@@ -102,9 +134,9 @@ export class MoniTooltip extends MoniElement {
 			this._target.addEventListener('mouseleave', this._hide);
 			this._target.addEventListener('focusout', this._hide);
 
-			// Auto-register a CSS anchor name on the parent trigger when the
-			// browser supports anchor positioning. Consumers can opt out by
-			// setting `data-no-anchor` on the trigger.
+			// Auto-registra un nombre de ancla CSS en el activador padre cuando el
+			// navegador soporta posicionamiento de ancla. Los consumidores pueden excluirse
+			// estableciendo `data-no-anchor` en el activador.
 			const cssSupports = (globalThis as unknown as {
 				CSS?: { supports?: (k: string) => boolean };
 			}).CSS?.supports;
@@ -124,6 +156,11 @@ export class MoniTooltip extends MoniElement {
 		document.addEventListener('keydown', this._docKeydown);
 	}
 
+	/**
+	 * Hook de destrucción (Lit).
+	 * Remueve diligentemente todos los detectores de eventos del padre (trigger)
+	 * y limpia las declaraciones generadas dinámicamente en estilos inline (`anchor-name`).
+	 */
 	override disconnectedCallback() {
 		if (this._target) {
 			this._target.removeEventListener('mouseenter', this._show);
@@ -139,6 +176,10 @@ export class MoniTooltip extends MoniElement {
 		super.disconnectedCallback();
 	}
 
+	/**
+	 * Inyecta la clase activa (`.visible`) desencadenando la animación de opacidad/escalado.
+	 * Cached-query: Recupera asíncronamente el tooltip del Shadow DOM si no lo había hecho.
+	 */
 	private _show = () => {
 		if (!this._tooltipEl) {
 			this._tooltipEl = this.shadowRoot?.querySelector('.tooltip') as HTMLElement;
@@ -148,6 +189,9 @@ export class MoniTooltip extends MoniElement {
 		}
 	};
 
+	/**
+	 * Retira la clase activa (`.visible`), desvaneciendo el globo con gracia.
+	 */
 	private _hide = () => {
 		if (!this._tooltipEl) {
 			this._tooltipEl = this.shadowRoot?.querySelector('.tooltip') as HTMLElement;
@@ -157,6 +201,11 @@ export class MoniTooltip extends MoniElement {
 		}
 	};
 
+	/**
+	 * Manejador global del teclado (a11y).
+	 * Permite disipar instantáneamente el tooltip presionando `Escape`
+	 * sin necesidad de mover el ratón o perder el foco.
+	 */
 	private _handleDocKeydown(e: KeyboardEvent) {
 		if (e.key !== 'Escape') return;
 		if (!this._tooltipEl?.classList.contains('visible')) return;
@@ -164,8 +213,8 @@ export class MoniTooltip extends MoniElement {
 	}
 
 	/**
-	 * Public ID of the tooltip element, suitable for `aria-describedby` on
-	 * the trigger parent. Auto-generated if the consumer did not set `id`.
+	 * ID público del elemento tooltip, adecuado para `aria-describedby` en
+	 * el padre activador. Generado automáticamente si el consumidor no estableció un `id`.
 	 */
 	get tooltipId(): string {
 		return this._tooltipEl?.id || '';
@@ -328,6 +377,24 @@ export class MoniTooltip extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el `<div>` del tooltip con su lista de clases calculada y atributos ARIA.
+	 *
+	 * **Composición de clases:**
+	 * - `'tooltip'` — siempre presente; estilos base.
+	 * - `this.position` — variante de ubicación (ej. `'top'`, `'bottom-start'`).
+	 * - `this.size` — modificador de tamaño (`'small'`, `'medium'`, `'large'`).
+	 *
+	 * **CSS Anchor Positioning:**
+	 * Si `_anchorName` está poblado, lo inyecta como la propiedad personalizada `--_anchor-name`. 
+	 * La declaración CSS `@anchor-name` conecta este tooltip a su elemento activador
+	 * a través de la API CSS Anchor Positioning (Chrome 125+).
+	 * En navegadores no compatibles, se utiliza un posicionamiento absoluto clásico como respaldo.
+	 *
+	 * **Respaldo de contenido:**
+	 * El slot por defecto renderiza el contenido distribuido (slotted); si no hay hijos,
+	 * el valor del atributo `text` se muestra como la etiqueta del tooltip.
+	 */
 	override render() {
 		const classes = [
 			'tooltip',

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

@@ -14,13 +14,13 @@ describe('moni-typography (P5.2 — recreated)', () => {
 		el.remove();
 	});
 
-	it('defaults to variant=body, size=medium', async () => {
+	it('variant=body, size=medium por defecto', async () => {
 		await el.updateComplete;
 		expect(el.variant).toBe('body');
 		expect(el.size).toBe('medium');
 	});
 
-	it('renders the default <p> tag for body variant', async () => {
+	it('renderiza la etiqueta <p> por defecto para la variante body', async () => {
 		el.text = 'Hello';
 		await el.updateComplete;
 		const el_tag = el.shadowRoot?.querySelector('p');
@@ -28,7 +28,7 @@ describe('moni-typography (P5.2 — recreated)', () => {
 		expect(el_tag?.textContent?.trim()).toBe('Hello');
 	});
 
-	it('renders <h1> for display variant', async () => {
+	it('renderiza <h1> para la variante display', async () => {
 		el.variant = 'display';
 		el.text = 'Big text';
 		await el.updateComplete;
@@ -37,7 +37,7 @@ describe('moni-typography (P5.2 — recreated)', () => {
 		expect(h1?.classList.contains('display')).toBe(true);
 	});
 
-	it('renders <h2> for headline variant', async () => {
+	it('renderiza <h2> para la variante headline', async () => {
 		el.variant = 'headline';
 		el.text = 'Section';
 		await el.updateComplete;
@@ -46,21 +46,21 @@ describe('moni-typography (P5.2 — recreated)', () => {
 		expect(h2?.classList.contains('headline')).toBe(true);
 	});
 
-	it('renders <h3> for title variant', async () => {
+	it('renderiza <h3> para la variante title', async () => {
 		el.variant = 'title';
 		await el.updateComplete;
 		const h3 = el.shadowRoot?.querySelector('h3');
 		expect(h3).toBeTruthy();
 	});
 
-	it('renders <label> for label variant', async () => {
+	it('renderiza <label> para la variante label', async () => {
 		el.variant = 'label';
 		await el.updateComplete;
 		const label = el.shadowRoot?.querySelector('label');
 		expect(label).toBeTruthy();
 	});
 
-	it('overrides the tag via the as attribute', async () => {
+	it('sobrescribe la etiqueta mediante el atributo as', async () => {
 		el.variant = 'headline';
 		el.as = 'span';
 		await el.updateComplete;
@@ -69,7 +69,7 @@ describe('moni-typography (P5.2 — recreated)', () => {
 		expect(span?.classList.contains('headline')).toBe(true);
 	});
 
-	it('reflects size variations', async () => {
+	it('refleja las variaciones de tamaño', async () => {
 		el.variant = 'title';
 		for (const size of ['large', 'medium', 'small'] as const) {
 			el.size = size;
@@ -79,7 +79,7 @@ describe('moni-typography (P5.2 — recreated)', () => {
 		}
 	});
 
-	it('supports all 5 variants × 3 sizes', async () => {
+	it('soporta las 5 variantes × 3 tamaños', async () => {
 		const variants: Array<'display' | 'headline' | 'title' | 'body' | 'label'> = [
 			'display',
 			'headline',
@@ -106,7 +106,7 @@ describe('moni-typography (P5.2 — recreated)', () => {
 		}
 	});
 
-	it('renders slot content when text attribute is empty', async () => {
+	it('renderiza el contenido del slot cuando el atributo text está vacío', async () => {
 		el.text = '';
 		el.textContent = 'Slotted content';
 		await el.updateComplete;