@moni-labs/moni-ui 0.3.1 → 0.3.2

package/src/components/moni-tabs.ts

@@ -10,50 +10,50 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Material Design 3 Tabs container component.
+ * Componente Material Design 3 Tabs container (Contenedor de pestañas).
  *
- * A navigational container that groups multiple `<moni-tab>` elements. Tabs
- * organize content into high-level categories and allow the user to switch
- * between them.
+ * Un contenedor de navegación que agrupa múltiples elementos `<moni-tab>`. Las pestañas
+ * organizan el contenido en categorías de alto nivel y permiten al usuario alternar
+ * entre ellas.
  *
- * **M3 spec reference:** `m3-docs/components/tabs/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/tabs/specs.md`
  *
- * **Modes (Primary vs Secondary):**
- * - `primary` (default): Used for top-level navigation at the highest hierarchy,
- *   often placed directly below a top app bar. They span the full width and
- *   feature a prominent active indicator.
- * - `secondary`: Used for deeper content hierarchies within a specific area
- *   or page. They are typically more subtle.
+ * **Modos (Primario vs Secundario):**
+ * - `primary` (por defecto): Usado para navegación de nivel superior en la jerarquía más alta,
+ *   a menudo colocado directamente debajo de una barra de aplicación superior (top app bar).
+ *   Abarcan todo el ancho y presentan un indicador activo prominente.
+ * - `secondary`: Usado para jerarquías de contenido más profundas dentro de un área
+ *   o página específica. Típicamente son más sutiles.
  *
- * **Layout & Alignment:**
- * - `scrollable`: If the number of tabs exceeds the container width, this
- *   enables horizontal scrolling (`overflow-x: auto`) rather than squishing.
- * - `align`: Controls how the tabs are distributed (`default` space-around,
- *   `left`, `center`, or `right`).
- * - `vertical`: Stacks the icon above the text label inside the child tabs.
+ * **Diseño y alineación:**
+ * - `scrollable`: Si el número de pestañas excede el ancho del contenedor, esto
+ *   habilita el desplazamiento horizontal (`overflow-x: auto`) en lugar de aplastarlas.
+ * - `align`: Controla cómo se distribuyen las pestañas (`default` space-around,
+ *   `left`, `center`, o `right`).
+ * - `vertical`: Apila el icono sobre la etiqueta de texto dentro de las pestañas hijas.
  *
- * **Active Indicator:**
- * The `indicator-size` attribute allows customizing the width of the active
- * underline indicator (`default` fits the tab content, `min` is narrow, `max`
- * fills the full tab width).
+ * **Indicador Activo:**
+ * El atributo `indicator-size` permite personalizar el ancho del
+ * indicador de subrayado activo (`default` se ajusta al contenido de la pestaña, `min` es estrecho, `max`
+ * llena todo el ancho de la pestaña).
  *
  * @example
  * ```html
- * <!-- Primary, scrollable tabs -->
+ * <!-- Pestañas primarias, con desplazamiento (scrollable) -->
  * <moni-tabs scrollable>
- *   <moni-tab active label="Flights"></moni-tab>
- *   <moni-tab label="Trips"></moni-tab>
- *   <moni-tab label="Explore"></moni-tab>
+ *   <moni-tab active label="Vuelos"></moni-tab>
+ *   <moni-tab label="Viajes"></moni-tab>
+ *   <moni-tab label="Explorar"></moni-tab>
  * </moni-tabs>
  *
- * <!-- Secondary, centered tabs with vertical layout -->
+ * <!-- Pestañas secundarias, centradas con diseño vertical -->
  * <moni-tabs mode="secondary" align="center" vertical>
  *   <moni-tab active icon="video_camera_front" label="Video"></moni-tab>
- *   <moni-tab icon="photo_camera" label="Photo"></moni-tab>
+ *   <moni-tab icon="photo_camera" label="Foto"></moni-tab>
  * </moni-tabs>
  * ```
  *
- * @slot default - `<moni-tab>` child elements.
+ * @slot default - Elementos hijos `<moni-tab>`.
  */
 @customElement('moni-tabs')
 export class MoniTabs extends MoniElement {
@@ -106,6 +106,12 @@ export class MoniTabs extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el contenedor de navegación.
+	 * Construye dinámicamente las clases CSS que habilitan los selectores estructurales
+	 * (`mode`, `align`, `indicatorSize`) permitiendo que el componente hijo `moni-tab`
+	 * herede estilos contextuales sin necesidad de inyectar variables complejas.
+	 */
 	override render() {
 		const classes = [
 			'tabs',

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

@@ -14,7 +14,7 @@ describe('moni-text-field', () => {
 		el.remove();
 	});
 
-	it('renders a field wrapper and an input', async () => {
+	it('renderiza un contenedor de campo (field wrapper) y un input', async () => {
 		await el.updateComplete;
 		const field = el.shadowRoot?.querySelector('.field');
 		const input = el.shadowRoot?.querySelector('input');
@@ -22,49 +22,49 @@ describe('moni-text-field', () => {
 		expect(input).toBeTruthy();
 	});
 
-	it('renders a leading icon when icon attribute is set', async () => {
+	it('renderiza un icono inicial (leading) cuando se establece el atributo icon', async () => {
 		el.icon = 'search';
 		await el.updateComplete;
 		const leading = el.shadowRoot?.querySelector('.leading-icon');
 		expect(leading).toBeTruthy();
 	});
 
-	it('renders a trailing icon when trailing-icon attribute is set', async () => {
+	it('renderiza un icono final (trailing) cuando se establece el atributo trailing-icon', async () => {
 		el.setAttribute('trailing-icon', 'close');
 		await el.updateComplete;
 		const trailing = el.shadowRoot?.querySelector('.trailing-icon');
 		expect(trailing).toBeTruthy();
 	});
 
-	it('renders prefix text when prefix attribute is set', async () => {
+	it('renderiza un texto prefijo cuando se establece el atributo prefix', async () => {
 		el.prefix = 'https://';
 		await el.updateComplete;
 		const leading = el.shadowRoot?.querySelector('.leading-icon');
 		expect(leading?.textContent?.trim()).toBe('https://');
 	});
 
-	it('renders suffix text when suffix attribute is set', async () => {
+	it('renderiza un texto sufijo cuando se establece el atributo suffix', async () => {
 		el.suffix = '.com';
 		await el.updateComplete;
 		const trailing = el.shadowRoot?.querySelector('.trailing-icon');
 		expect(trailing?.textContent?.trim()).toBe('.com');
 	});
 
-	it('applies square class on the field wrapper for shape=no-round', async () => {
+	it('aplica la clase square en el contenedor de campo para shape=no-round', async () => {
 		el.shape = 'no-round';
 		await el.updateComplete;
 		const field = el.shadowRoot?.querySelector('.field');
 		expect(field?.classList.contains('square')).toBe(true);
 	});
 
-	it('applies round class on the field wrapper for shape=round', async () => {
+	it('aplica la clase round en el contenedor de campo para shape=round', async () => {
 		el.shape = 'round';
 		await el.updateComplete;
 		const field = el.shadowRoot?.querySelector('.field');
 		expect(field?.classList.contains('round')).toBe(true);
 	});
 
-	it('does not apply shape class on the field wrapper for shape=square', async () => {
+	it('no aplica la clase de forma (shape) en el contenedor de campo para shape=square', async () => {
 		el.shape = 'square';
 		await el.updateComplete;
 		const field = el.shadowRoot?.querySelector('.field');
@@ -72,7 +72,7 @@ describe('moni-text-field', () => {
 		expect(field?.classList.contains('round')).toBe(false);
 	});
 
-	it('shows the loading spinner when loading is true', async () => {
+	it('muestra el indicador de carga cuando loading es true', async () => {
 		el.loading = true;
 		await el.updateComplete;
 		const trailing = el.shadowRoot?.querySelector('.trailing-icon');
@@ -80,13 +80,13 @@ describe('moni-text-field', () => {
 		expect(progress).toBeTruthy();
 	});
 
-	it('does not render a leading icon by default', async () => {
+	it('no renderiza un icono inicial por defecto', async () => {
 		await el.updateComplete;
 		const leading = el.shadowRoot?.querySelector('.leading-icon');
 		expect(leading).toBeFalsy();
 	});
 
-	it('forwards value to the input', async () => {
+	it('reenvía value al input', async () => {
 		el.value = 'hello world';
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
@@ -95,14 +95,14 @@ describe('moni-text-field', () => {
 		expect(input.value).toBe('hello world');
 	});
 
-	it('adds active class to input when value is set', async () => {
+	it('agrega la clase active al input cuando se establece el valor', async () => {
 		el.value = 'something';
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector('input');
 		expect(input?.classList.contains('active')).toBe(true);
 	});
 
-	it('renders label and toggles active class based on value', async () => {
+	it('renderiza el label y alterna la clase active basándose en el valor', async () => {
 		el.label = 'Email';
 		await el.updateComplete;
 		const label = el.shadowRoot?.querySelector('label');

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

@@ -10,70 +10,109 @@ import { customElement, property, query } from 'lit/decorators.js';
 import { ifDefined } from 'lit/directives/if-defined.js';
 import { classMap } from 'lit/directives/class-map.js';
 import { MoniElement, sharedStyles, fieldStyles } from './_base/index.js';
+import { emitMoniEvent } from '../utils/event-emitter.js';
 import './moni-icon.js';
 import './moni-progress.js';
 
 /**
- * Material Design 3 Text Field component.
+ * Componente Material Design 3 Text Field (Campo de texto).
  *
- * A full-featured input field that wraps a native `<input>` inside the M3
- * field shell (`.field` class from `fieldStyles`). Supports floating labels,
- * filled and outlined variants, leading/trailing icons, helper text, and
- * error states.
+ * Un campo de entrada con todas las funciones que envuelve un `<input>` nativo dentro de la
+ * estructura de campo M3 (clase `.field` de `fieldStyles`). Soporta etiquetas flotantes,
+ * variantes llenas (filled) y contorneadas (outlined), iconos iniciales/finales (leading/trailing),
+ * texto de ayuda y estados de error.
  *
- * **M3 spec reference:** `m3-docs/components/text-fields/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/text-fields/specs.md`
  *
- * **Visual architecture:**
- * Uses `fieldStyles` for the complete CSS field shell. The field container
- * is a `<div class="field [modifiers]">` wrapping:
- * 1. Optional leading icon.
- * 2. Native `<input>` element.
- * 3. Floating `<label>` (when `label` is set).
- * 4. Optional trailing icon or loading spinner.
- * 5. `<output>` for helper/error text.
+ * **Arquitectura visual:**
+ * Utiliza `fieldStyles` para toda la estructura CSS del campo. El contenedor del campo
+ * es un `<div class="field [modifiers]">` que envuelve:
+ * 1. Icono inicial (leading) opcional.
+ * 2. Elemento `<input>` nativo.
+ * 3. `<label>` flotante (cuando se establece `label`).
+ * 4. Icono final (trailing) opcional o indicador de carga (spinner).
+ * 5. `<output>` para texto de ayuda/error.
  *
- * **Visual-only contract:**
- * This component does **not** listen to `@input` events to sync the `value`
- * attribute back from the underlying `<input>`. Consumers must either:
- * - Submit the native form (the `<input name>` participates in form submission).
- * - Listen to `change` or `input` events via standard DOM event handling.
- * - Use a framework binding (e.g. `bind:value` in Svelte, `v-model` in Vue).
+ * **Sincronización de eventos:**
+ * Emite `moni-input` en cada tipeo y `moni-change` al consolidar el valor (blur/enter).
+ * El valor interno del componente (`this.value`) se mantiene sincronizado automáticamente.
  *
  * @example
  * ```html
  * <moni-text-field
- *   label="Email address"
+ *   label="Dirección de correo"
  *   type="email"
  *   name="email"
  *   icon="mail"
  *   variant="outlined"
- *   helper="We'll never share your email."
+ *   helper="Nunca compartiremos tu correo."
  * ></moni-text-field>
  *
  * <moni-text-field
- *   label="Amount"
+ *   label="Monto"
  *   type="number"
  *   prefix="$"
  *   error
- *   error-text="Value must be positive"
+ *   error-text="El valor debe ser positivo"
  * ></moni-text-field>
  * ```
  *
- * @csspart field         - The outer `.field` div container.
- * @csspart input         - The native `<input>` element.
- * @csspart label         - The floating `<label>` element.
- * @csspart helper        - The helper `<output>` element.
- * @csspart error-output  - The error `<output>` element.
+ * @csspart field         - El contenedor div `.field` exterior.
+ * @csspart input         - El elemento `<input>` nativo.
+ * @csspart label         - El elemento `<label>` flotante.
+ * @csspart helper        - El elemento `<output>` de ayuda.
+ * @csspart error-output  - El elemento `<output>` de error.
  */
 @customElement('moni-text-field')
 export class MoniTextField extends MoniElement {
+	static formAssociated = true;
+	private _internals: ElementInternals;
+
+	constructor() {
+		super();
+		this._internals = this.attachInternals();
+	}
+
+	/**
+	 * 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 'filled'
+	 */
 	@property({ reflect: true }) variant: 'filled' | 'outlined' = 'filled';
+
+	/**
+	 * 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 (border-radius) del campo.
+	 * @type {'round' | 'square' | 'no-round'}
+	 * @default 'no-round'
+	 */
 	@property({ reflect: true })
 	shape: 'round' | 'square' | 'no-round' = 'no-round';
+
+	/**
+	 * El tipo de input HTML nativo.
+	 * @type {'text' | 'password' | 'email' | 'number' | 'tel' | 'url' | 'search'}
+	 * @default 'text'
+	 */
 	@property({ reflect: true })
 	type:
 		| 'text'
@@ -83,29 +122,139 @@ export class MoniTextField extends MoniElement {
 		| 'tel'
 		| 'url'
 		| 'search' = 'text';
+
+	/**
+	 * Nombre del icono inicial (leading) (Material Symbols).
+	 * @type {string}
+	 */
 	@property({ reflect: true }) icon = '';
+
+	/**
+	 * Nombre del icono final (trailing) (Material Symbols).
+	 * @type {string}
+	 */
 	@property({ reflect: true, attribute: 'trailing-icon' }) trailingIcon = '';
+
+	/**
+	 * Prefijo de texto corto mostrado antes del valor del input.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) prefix = '';
+
+	/**
+	 * Sufijo de texto corto mostrado después del valor del input.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) suffix = '';
+
+	/**
+	 * 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;
+
+	/**
+	 * Si es true, muestra un indicador de carga (progreso lineal/circular) al final.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) loading = false;
+
+	/**
+	 * Deshabilita el campo de texto.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
+
+	/**
+	 * El valor actual del input.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) value = '';
+
+	/**
+	 * Texto de marcador de posición (placeholder) mostrado cuando el input está vacío y la etiqueta es flotante.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) placeholder = '';
 
 	@query('input') private _input!: HTMLInputElement;
 
+	/**
+	 * Sincroniza imperativamente las propiedades DOM del `<input>` nativo después de cada actualización reactiva.
+	 *
+	 * Las vinculaciones `?value` y `?disabled` de Lit establecen *atributos* HTML, no *propiedades* DOM.
+	 * Para un `<input>`, el atributo `value` solo establece el valor *inicial*; la propiedad DOM
+	 * `input.value` refleja el valor actual tecleado por el usuario. Después de una actualización reactiva que
+	 * cambia `this.value` (ej. reinicio programático), debemos escribir directamente a la propiedad
+	 * DOM para sobrescribir lo que el usuario ha tecleado. Esto también es crítico para los consumidores
+	 * de React y Vue que mutan la propiedad del Custom Element directamente, omitiendo el flujo
+	 * de atributos de Lit.
+	 *
+	 * @param changed - Mapa de los nombres de propiedades a sus valores anteriores que causaron esta actualización.
+	 */
 	override updated(changed: Map<string, unknown>) {
 		if (this._input) {
-			if (changed.has('value')) this._input.value = this.value;
+			if (changed.has('value')) {
+				this._input.value = this.value;
+				this._internals?.setFormValue?.(this.value);
+			}
 			if (changed.has('disabled')) this._input.disabled = this.disabled;
 		}
 	}
 
+	private _handleInput(e: Event) {
+		const target = e.target as HTMLInputElement;
+		this.value = target.value;
+		emitMoniEvent(this, 'moni-input', {
+			detail: { value: this.value, originalEvent: e }
+		});
+	}
+
+	private _handleChange(e: Event) {
+		const target = e.target as HTMLInputElement;
+		this.value = target.value;
+		emitMoniEvent(this, 'moni-change', {
+			detail: { value: this.value, originalEvent: e }
+		});
+	}
+
 	static override styles = [sharedStyles, fieldStyles];
 
+	/**
+	 * Renderiza el campo de texto con animación de etiqueta flotante, iconos iniciales/finales, y texto de ayuda.
+	 *
+	 * **Composición de `fieldClasses`:**
+	 * - `field` — siempre presente; diseño base del campo.
+	 * - `label` — habilita el comportamiento de la etiqueta flotante vía CSS.
+	 * - `fill` / `border` — variante filled vs outlined.
+	 * - `small` / `large` / `extra` — modificador de tamaño.
+	 * - `prefix` — desplaza la etiqueta cuando hay un icono inicial (leading) presente.
+	 * - `suffix` — reserva espacio final (trailing) para el icono/texto de sufijo.
+	 * - `invalid` — aplica colores de error cuando `error=true` o falla la validación nativa.
+	 *
+	 * **Flotación de la etiqueta (Label float):**
+	 * `isActive` es true cuando `value` no está vacío o se establece un `placeholder`.
+	 * Los selectores CSS `.field.label input:focus ~ label`, `.field.label.active label`
+	 * flotan la etiqueta a la parte superior del borde del campo. Este componente
+	 * establece `isActive` para evitar que la etiqueta colapse cuando un valor está preestablecido.
+	 *
+	 * **Zonas inicial / final (Leading / trailing):**
+	 * `hasLeading` y `hasTrailing` añaden condicionalmente las clases CSS `prefix`/`suffix`
+	 * y renderizan el icono o los elementos de texto de prefijo/sufijo.
+	 */
 	override render() {
 		const hasLeading = Boolean(this.icon) || Boolean(this.prefix);
 		const hasTrailing =
@@ -166,6 +315,8 @@ export class MoniTextField extends MoniElement {
 				.value=${this.value}
 				name=${ifDefined(this.name || undefined)}
 				class=${isActive ? 'active' : ''}
+				@input=${this._handleInput}
+				@change=${this._handleChange}
 			/>
 			${this.label
 				? html`<label

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

@@ -14,7 +14,7 @@ describe('moni-textarea', () => {
 		el.remove();
 	});
 
-	it('renders a field wrapper and a textarea', async () => {
+	it('renderiza un contenedor de campo (field wrapper) y un textarea', async () => {
 		await el.updateComplete;
 		const field = el.shadowRoot?.querySelector('.field');
 		const textarea = el.shadowRoot?.querySelector('textarea');
@@ -22,35 +22,35 @@ describe('moni-textarea', () => {
 		expect(textarea).toBeTruthy();
 	});
 
-	it('renders a leading icon when icon attribute is set', async () => {
+	it('renderiza un icono inicial (leading) cuando se establece el atributo icon', async () => {
 		el.icon = 'edit';
 		await el.updateComplete;
 		const leading = el.shadowRoot?.querySelector('.leading-icon');
 		expect(leading).toBeTruthy();
 	});
 
-	it('renders a trailing icon when trailing-icon attribute is set', async () => {
+	it('renderiza un icono final (trailing) cuando se establece el atributo trailing-icon', async () => {
 		el.setAttribute('trailing-icon', 'send');
 		await el.updateComplete;
 		const trailing = el.shadowRoot?.querySelector('.trailing-icon');
 		expect(trailing).toBeTruthy();
 	});
 
-	it('renders prefix text when prefix attribute is set', async () => {
+	it('renderiza un texto prefijo cuando se establece el atributo prefix', async () => {
 		el.prefix = '~';
 		await el.updateComplete;
 		const leading = el.shadowRoot?.querySelector('.leading-icon');
 		expect(leading?.textContent?.trim()).toBe('~');
 	});
 
-	it('renders suffix text when suffix attribute is set', async () => {
+	it('renderiza un texto sufijo cuando se establece el atributo suffix', async () => {
 		el.suffix = 'chars';
 		await el.updateComplete;
 		const trailing = el.shadowRoot?.querySelector('.trailing-icon');
 		expect(trailing?.textContent?.trim()).toBe('chars');
 	});
 
-	it('shows the loading spinner when loading is true', async () => {
+	it('muestra el indicador de carga cuando loading es true', async () => {
 		el.loading = true;
 		await el.updateComplete;
 		const trailing = el.shadowRoot?.querySelector('.trailing-icon');
@@ -58,7 +58,7 @@ describe('moni-textarea', () => {
 		expect(progress).toBeTruthy();
 	});
 
-	it('forwards rows attribute to the textarea', async () => {
+	it('reenvía el atributo rows al textarea', async () => {
 		el.rows = 5;
 		await el.updateComplete;
 		const textarea = el.shadowRoot?.querySelector(
@@ -67,7 +67,7 @@ describe('moni-textarea', () => {
 		expect(textarea.rows).toBe(5);
 	});
 
-	it('forwards value to the textarea', async () => {
+	it('reenvía value al textarea', async () => {
 		el.value = 'multi\nline\ntext';
 		await el.updateComplete;
 		const textarea = el.shadowRoot?.querySelector(
@@ -76,28 +76,28 @@ describe('moni-textarea', () => {
 		expect(textarea.value).toBe('multi\nline\ntext');
 	});
 
-	it('adds active class to textarea when value is set', async () => {
+	it('agrega la clase active al textarea cuando se establece el valor', async () => {
 		el.value = 'content';
 		await el.updateComplete;
 		const textarea = el.shadowRoot?.querySelector('textarea');
 		expect(textarea?.classList.contains('active')).toBe(true);
 	});
 
-	it('applies square class on the field wrapper for shape=no-round', async () => {
+	it('aplica la clase square en el contenedor de campo para shape=no-round', async () => {
 		el.shape = 'no-round';
 		await el.updateComplete;
 		const field = el.shadowRoot?.querySelector('.field');
 		expect(field?.classList.contains('square')).toBe(true);
 	});
 
-	it('applies round class on the field wrapper for shape=round', async () => {
+	it('aplica la clase round en el contenedor de campo para shape=round', async () => {
 		el.shape = 'round';
 		await el.updateComplete;
 		const field = el.shadowRoot?.querySelector('.field');
 		expect(field?.classList.contains('round')).toBe(true);
 	});
 
-	it('does not apply shape class on the field wrapper for shape=square', async () => {
+	it('no aplica la clase de forma (shape) en el contenedor de campo para shape=square', async () => {
 		el.shape = 'square';
 		await el.updateComplete;
 		const field = el.shadowRoot?.querySelector('.field');
@@ -107,20 +107,20 @@ describe('moni-textarea', () => {
 
 	// ─── P3.3: maxlength + character counter ───
 
-	it('does not render a counter by default', async () => {
+	it('no renderiza un contador por defecto', async () => {
 		await el.updateComplete;
 		const counter = el.shadowRoot?.querySelector('.counter');
 		expect(counter).toBeFalsy();
 	});
 
-	it('renders a counter when maxlength is set', async () => {
+	it('renderiza un contador cuando se establece maxlength', async () => {
 		el.maxlength = 100;
 		await el.updateComplete;
 		const counter = el.shadowRoot?.querySelector('.counter');
 		expect(counter).toBeTruthy();
 	});
 
-	it('counter shows value.length / maxlength', async () => {
+	it('el contador muestra value.length / maxlength', async () => {
 		el.maxlength = 100;
 		el.value = 'Hello';
 		await el.updateComplete;
@@ -128,7 +128,7 @@ describe('moni-textarea', () => {
 		expect(counter?.textContent?.trim()).toBe('5 / 100');
 	});
 
-	it('no-counter suppresses the counter even when maxlength is set', async () => {
+	it('no-counter suprime el contador incluso cuando maxlength está establecido', async () => {
 		el.maxlength = 100;
 		el.noCounter = true;
 		await el.updateComplete;
@@ -136,7 +136,7 @@ describe('moni-textarea', () => {
 		expect(counter).toBeFalsy();
 	});
 
-	it('forwards maxlength to the inner textarea as maxLength', async () => {
+	it('reenvía maxlength al textarea interno como maxLength', async () => {
 		el.maxlength = 50;
 		await el.updateComplete;
 		const textarea = el.shadowRoot?.querySelector(