@moni-labs/moni-ui 0.3.0 → 0.3.2

package/src/components/moni-textarea.ts

@@ -14,81 +14,192 @@ import './moni-icon.js';
 import './moni-progress.js';
 
 /**
- * Material Design 3 Textarea component.
+ * Componente Material Design 3 Textarea (Área de texto).
  *
- * A multi-line text input field designed for collecting longer amounts of text,
- * such as comments, descriptions, or messages.
+ * Un campo de entrada de texto multilínea diseñado para recolectar cantidades mayores de texto,
+ * como comentarios, descripciones o mensajes.
  *
- * **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:**
- * It shares the exact same `.field` shell and styling engine as
- * `<moni-text-field>`, but internally renders a native `<textarea>` instead
- * of an `<input>`. This ensures visual consistency across all form elements
- * regarding floating labels, helper text, error states, and icons.
+ * **Arquitectura visual:**
+ * Comparte exactamente el mismo contenedor `.field` y motor de estilos que
+ * `<moni-text-field>`, pero internamente renderiza un `<textarea>` nativo en lugar
+ * de un `<input>`. Esto asegura la consistencia visual en todos los elementos del formulario
+ * en cuanto a etiquetas flotantes, texto de ayuda, estados de error e iconos.
  *
- * **Character Counter:**
- * If the `maxlength` attribute is set, the textarea automatically displays
- * a character counter (`{current length} / {maxlength}`) positioned at the
- * trailing edge of the supporting text area (bottom right). This can be
- * suppressed by setting the `no-counter` attribute.
+ * **Contador de caracteres:**
+ * Si se establece el atributo `maxlength`, el área de texto muestra automáticamente
+ * un contador de caracteres (`{longitud actual} / {maxlength}`) ubicado en el
+ * borde final (trailing) del área de texto de soporte (abajo a la derecha). Esto puede
+ * suprimirse estableciendo el atributo `no-counter`.
  *
- * **State management:**
- * This component is purely visual and presentational. It reflects attributes
- * down to the native textarea, but it does NOT attach internal `@input` or
- * `@change` listeners. Consumers should attach standard DOM listeners directly
- * to this element to capture user input, just as they would with a native
- * textarea.
+ * **Gestión del estado:**
+ * Este componente es puramente visual y representacional. Refleja los atributos
+ * hacia el textarea nativo, pero NO adjunta listeners internos para `@input` o
+ * `@change`. Los consumidores deben adjuntar listeners estándar del DOM directamente
+ * a este elemento para capturar la entrada del usuario, tal como lo harían con un
+ * textarea nativo.
  *
  * @example
  * ```html
- * <!-- Standard filled textarea -->
- * <moni-textarea label="Description" rows="4"></moni-textarea>
+ * <!-- Textarea llenado (filled) estándar -->
+ * <moni-textarea label="Descripción" rows="4"></moni-textarea>
  *
- * <!-- Outlined textarea with character counter -->
+ * <!-- Textarea contorneado (outlined) con contador de caracteres -->
  * <moni-textarea
  *   variant="outlined"
- *   label="Bio"
+ *   label="Biografía"
  *   maxlength="160"
  * ></moni-textarea>
  * ```
  *
- * @csspart field     - The outer `.field` div container.
- * @csspart input     - The native `<textarea>` element.
- * @csspart label     - The floating `<label>` element.
- * @csspart helper    - The helper/error text area.
- * @csspart counter   - The character counter element.
+ * @csspart field     - El contenedor div `.field` exterior.
+ * @csspart input     - El elemento `<textarea>` nativo.
+ * @csspart label     - El elemento `<label>` flotante.
+ * @csspart helper    - El área de texto de ayuda/error.
+ * @csspart counter   - El elemento contador de caracteres.
  */
 @customElement('moni-textarea')
 export class MoniTextarea extends MoniElement {
+	static formAssociated = true;
+	private _internals: ElementInternals;
+
+	constructor() {
+		super();
+		this._internals = this.attachInternals();
+	}
+
+	/**
+	 * El nombre del textarea, 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 área de texto.
+	 * @type {'filled' | 'outlined'}
+	 * @default 'filled'
+	 */
 	@property({ reflect: true }) variant: 'filled' | 'outlined' = 'filled';
+
+	/**
+	 * Define las dimensiones del área 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';
+
+	/**
+	 * 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 = '';
+
+	/**
+	 * Número por defecto de líneas de texto visibles.
+	 * @type {number}
+	 * @default 3
+	 */
 	@property({ type: Number, reflect: true }) rows = 3;
+
+	/**
+	 * Número máximo de caracteres permitidos en el área de texto.
+	 * También habilita la visualización del contador de caracteres a menos que `noCounter` sea true.
+	 * @type {number | null}
+	 */
 	@property({ type: Number, reflect: true }) maxlength: number | null = null;
+
+	/**
+	 * Oculta la visualización del contador de caracteres cuando se establece `maxlength`.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true, attribute: 'no-counter' })
 	noCounter = false;
+
+	/**
+	 * Si es true, muestra un indicador de carga (progreso circular) al final.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) loading = false;
+
+	/**
+	 * Deshabilita el área de texto.
+	 * @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 área de texto.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) value = '';
+
+	/**
+	 * Texto de marcador de posición (placeholder) mostrado cuando el textarea está vacío y la etiqueta es flotante.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) placeholder = '';
 
 	@query('textarea') private _input!: HTMLTextAreaElement;
 
 	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;
 			if (changed.has('maxlength') && this.maxlength != null) {
 				this._input.maxLength = this.maxlength;
@@ -98,6 +209,19 @@ export class MoniTextarea extends MoniElement {
 
 	static override styles = [sharedStyles, fieldStyles];
 
+	/**
+	 * Renderiza el campo del área de texto con etiqueta, iconos de prefijo/sufijo y contador de caracteres.
+	 *
+	 * **Composición de `fieldClasses`:**
+	 * Sigue la convención de nomenclatura field-styles. `prefix` se añade
+	 * cuando el texto de `icon` o `prefix` está presente (desplaza el inicio en línea de la etiqueta).
+	 * `suffix` se añade cuando `trailingIcon`, el texto `suffix` o `loading` es true.
+	 *
+	 * **Contador de caracteres:**
+	 * `showCounter` es true cuando `maxlength > 0` y `noCounter` no está configurado.
+	 * El contador muestra `${this.value.length} / ${this.maxlength}` y puede volverse rojo
+	 * (vía CSS `invalid`) dependiendo de la validación.
+	 */
 	override render() {
 		const hasLeading = Boolean(this.icon) || Boolean(this.prefix);
 		const hasTrailing =
@@ -152,7 +276,7 @@ export class MoniTextarea extends MoniElement {
 						>`
 					: nothing;
 
-		// M3 spec: supporting text on the left, character counter on the right.
+		// Especificación M3: texto de soporte a la izquierda, contador de caracteres a la derecha.
 		const counter = showCounter
 			? html`<output part="counter" class="counter"
 						>${this.value.length} / ${this.maxlength}</output

package/src/components/moni-time-picker.test.ts

@@ -14,21 +14,21 @@ describe('moni-time-picker', () => {
 		el.remove();
 	});
 
-	it('initializes with default values', async () => {
+	it('se inicializa con valores por defecto', async () => {
 		await el.updateComplete;
 		expect(el.value).toBe('00:00');
 		expect(el.mode).toBe('dial');
 		expect(el.use24Hour).toBe(false);
 	});
 
-	it('parses input value correctly', async () => {
+	it('analiza el valor de entrada correctamente', async () => {
 		el.value = '14:45';
 		await el.updateComplete;
-		// Since use24Hour is false, PM is set
+		// Como use24Hour es false, PM está establecido
 		expect(el.value).toBe('14:45');
 	});
 
-	it('toggles mode', async () => {
+	it('alterna el modo', async () => {
 		await el.updateComplete;
 		const toggleBtn = el.shadowRoot?.querySelector('.mode-toggle-btn') as HTMLButtonElement;
 		expect(toggleBtn).toBeTruthy();
@@ -42,7 +42,7 @@ describe('moni-time-picker', () => {
 		expect(el.mode).toBe('dial');
 	});
 
-	it('allows typing time in input mode', async () => {
+	it('permite escribir la hora en modo input', async () => {
 		el.mode = 'input';
 		el.use24Hour = true;
 		await el.updateComplete;

package/src/components/moni-time-picker.ts

@@ -12,40 +12,40 @@ import './moni-icon.js';
 import './moni-button.js';
 
 /**
- * Material Design 3 Time Picker component.
+ * Componente Material Design 3 Time Picker (Selector de hora).
  *
- * A highly interactive control that allows users to select a specific time.
- * It provides two distinct input modes:
- * 1. **Dial mode:** An interactive clock face where users can drag or click
- *    to select hours and minutes.
- * 2. **Input mode:** Standard text inputs for precise keyboard entry.
+ * Un control altamente interactivo que permite a los usuarios seleccionar una hora específica.
+ * Proporciona dos modos de entrada distintos:
+ * 1. **Modo dial (analógico):** Una carátula de reloj interactiva donde los usuarios pueden arrastrar o hacer clic
+ *    para seleccionar horas y minutos.
+ * 2. **Modo input (texto):** Entradas de texto estándar para una introducción precisa por teclado.
  *
- * **M3 spec reference:** `m3-docs/components/time-pickers/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/time-pickers/specs.md`
  *
- * **Time formats & modes:**
- * - The `value` property expects and always outputs a 24-hour formatted string
- *   (`HH:MM`, e.g., `"14:30"`).
- * - Setting `use-24-hour` configures the visual presentation to use a 24-hour
- *   clock dial (inner and outer rings) and removes the AM/PM toggle. Otherwise,
- *   it uses a standard 12-hour dial with an AM/PM toggle.
+ * **Formatos de hora y modos:**
+ * - La propiedad `value` espera y siempre emite un string en formato de 24 horas
+ *   (`HH:MM`, ej. `"14:30"`).
+ * - Establecer `use-24-hour` configura la presentación visual para usar un
+ *   reloj de 24 horas (anillos interior y exterior) y elimina el selector AM/PM. De lo contrario,
+ *   utiliza un dial estándar de 12 horas con un selector AM/PM.
  *
- * **Responsive design:**
- * The `orientation` attribute configures the layout. `vertical` stacks the
- * time display above the clock face, `horizontal` places them side-by-side,
- * and `auto` responds to the container/viewport width automatically.
+ * **Diseño responsivo:**
+ * El atributo `orientation` configura el diseño. `vertical` apila la
+ * visualización de la hora sobre la carátula del reloj, `horizontal` los coloca lado a lado,
+ * y `auto` responde automáticamente al ancho del contenedor/viewport.
  *
- * @fires change - Fired when the selected time changes interactively. The
- *                 `detail.value` contains the new time in `HH:MM` format.
- * @fires cancel - Fired when the 'Cancel' button is clicked.
- * @fires ok     - Fired when the 'OK' button is clicked. The `detail.value`
- *                 contains the final confirmed time.
+ * @fires change - Se dispara cuando la hora seleccionada cambia interactivamente. El
+ *                 `detail.value` contiene la nueva hora en formato `HH:MM`.
+ * @fires cancel - Se dispara cuando se hace clic en el botón 'Cancelar'.
+ * @fires ok     - Se dispara cuando se hace clic en el botón 'OK'. El `detail.value`
+ *                 contiene la hora final confirmada.
  *
  * @example
  * ```html
- * <!-- 12-hour format (AM/PM) -->
+ * <!-- Formato 12 horas (AM/PM) -->
  * <moni-time-picker value="14:30"></moni-time-picker>
  *
- * <!-- 24-hour format -->
+ * <!-- Formato 24 horas -->
  * <moni-time-picker use-24-hour value="14:30"></moni-time-picker>
  * ```
  */
@@ -66,12 +66,24 @@ export class MoniTimePicker extends MoniElement {
 
 	private isDragging = false;
 
+	/**
+	 * Hook del ciclo de vida (Lit) previo al renderizado.
+	 * 
+	 * Si la propiedad externa `value` o el modo `use24Hour` cambian (vía binding o atributo HTML),
+	 * dispara el `parseValue()` de inmediato para mantener sincronizado el estado interno de 
+	 * horas y minutos (y recalcular AM/PM) antes de mutar el DOM real.
+	 */
 	protected override willUpdate(changedProperties: PropertyValues) {
 		if (changedProperties.has('value') || changedProperties.has('use24Hour')) {
 			this.parseValue();
 		}
 	}
 
+	/**
+	 * Interpreta el string `value` (formato "HH:MM") y lo descompone en enteros para
+	 * el estado interno. Automáticamente corrige valores fuera de rango y determina
+	 * si estamos en AM o PM (cuando no se usa formato de 24 horas).
+	 */
 	private parseValue() {
 		const parts = this.value.split(':');
 		let h = parseInt(parts[0], 10);
@@ -92,6 +104,11 @@ export class MoniTimePicker extends MoniElement {
 		}
 	}
 
+	/**
+	 * Reconstruye el string `value` a partir del estado interno (`currentHour`, `currentMinute`).
+	 * Formatea con ceros a la izquierda e incluye la lógica de conversión AM/PM a 24hrs
+	 * para garantizar que el valor expuesto hacia afuera sea siempre un estándar ISO ("14:30").
+	 */
 	private updateValue() {
 		let h = this.currentHour;
 		const m = this.currentMinute;
@@ -101,7 +118,7 @@ export class MoniTimePicker extends MoniElement {
 				if (h < 12) h += 12;
 			} else {
 				if (h === 12) h = 0;
-				else if (h > 12) h -= 12; // Adjust if out of bounds
+				else if (h > 12) h -= 12; // Ajuste por si quedó fuera de límites
 			}
 		}
 
@@ -116,20 +133,41 @@ export class MoniTimePicker extends MoniElement {
 		}));
 	}
 
+	/**
+	 * Alterna el modo de interacción visual entre el Reloj Analógico (dial) 
+	 * y el modo de Entrada de Texto manual (input).
+	 */
 	private toggleMode() {
 		this.mode = this.mode === 'dial' ? 'input' : 'dial';
 	}
 
+	/**
+	 * Define el nivel de selección activo ('hour' o 'minute').
+	 * Cambia dinámicamente qué anillo o qué matemáticas (12 vs 60 items)
+	 * utilizará el componente principal y el reloj.
+	 */
 	private setSelection(type: 'hour' | 'minute') {
 		this.activeSelection = type;
 	}
 
+	/**
+	 * Cambia forzosamente el periodo del día ('AM' o 'PM') cuando el usuario 
+	 * presiona los conmutadores laterales (sólo visible en formato 12h).
+	 * Inmediatamente propaga el cambio hacia `updateValue()` para recalcular
+	 * y despachar la hora formateada.
+	 */
 	private setPeriod(p: 'AM' | 'PM') {
 		this.period = p;
 		this.updateValue();
 	}
 
 	// Clock Math and Interaction
+	/**
+	 * Inicia el proceso de arrastre en la carátula del reloj (Pointer Down).
+	 * Utiliza `setPointerCapture` nativo para asegurar que el movimiento (drag) siga
+	 * siendo rastreado aunque el puntero del usuario salga físicamente del contenedor,
+	 * garantizando una interacción "Touch" a prueba de errores.
+	 */
 	private handleClockPointerDown(e: PointerEvent) {
 		if (!this.clockFaceEl) return;
 		this.isDragging = true;
@@ -138,42 +176,52 @@ export class MoniTimePicker extends MoniElement {
 		this.handleClockPointerMove(e);
 	}
 
+	/**
+	 * Corazón matemático del reloj radial (Time Picker analógico).
+	 * Convierte las coordenadas cartesianas del ratón/dedo en un ángulo polar (0-360º),
+	 * y dependiendo si medimos horas o minutos, lo mapea al número correspondiente.
+	 */
 	private handleClockPointerMove(e: PointerEvent) {
 		if (!this.isDragging || !this.clockFaceEl) return;
+		
 		const rect = this.clockFaceEl.getBoundingClientRect();
+		// Encontramos el centro geométrico absoluto del reloj
 		const centerX = rect.left + rect.width / 2;
 		const centerY = rect.top + rect.height / 2;
 
 		const dx = e.clientX - centerX;
 		const dy = e.clientY - centerY;
+		// Teorema de Pitágoras para saber a qué distancia del centro está apuntando el usuario
 		const distance = Math.sqrt(dx * dx + dy * dy);
 
-		// Calculate angle in degrees from 12 o'clock position (clockwise)
+		// Calculamos el ángulo en grados partiendo desde las 12 (sentido horario).
+		// Math.atan2 devuelve de -PI a PI, sumamos 90º para desfasar el origen arriba (eje Y).
 		let angle = Math.atan2(dy, dx) * (180 / Math.PI) + 90;
 		if (angle < 0) angle += 360;
 
 		if (this.activeSelection === 'hour') {
 			if (this.use24Hour) {
-				// Outer circle for 13-00, inner circle for 1-12
+				// Reloj de 24 horas M3: Un círculo externo (13-00) y uno interno (1-12)
+				// El umbral (0.32) fue medido visualmente para coincidir con el diseño radial interno.
 				const isInner = distance < rect.width * 0.32;
-				let hour = Math.round(angle / 30) % 12;
+				let hour = Math.round(angle / 30) % 12; // 360 / 12 horas = 30 grados por hora
 				if (hour === 0) hour = 12;
 
 				if (isInner) {
-					// Inner circle: 1 to 12
+					// Círculo interno: 1 a 12 (AM/PM)
 					this.currentHour = hour;
 				} else {
-					// Outer circle: 13 to 00/24
+					// Círculo externo: 13 a 24 (donde las 24 = 0)
 					this.currentHour = hour === 12 ? 0 : hour + 12;
 				}
 			} else {
-				// 12-hour face: 1 to 12
+				// Reloj estándar de 12 horas: solo 1 a 12
 				let hour = Math.round(angle / 30) % 12;
 				if (hour === 0) hour = 12;
 				this.currentHour = hour;
 			}
 		} else {
-			// Minutes: 0 to 59
+			// Modo minutos: 360 / 60 minutos = 6 grados por minuto
 			const minute = Math.round(angle / 6) % 60;
 			this.currentMinute = minute;
 		}
@@ -181,12 +229,19 @@ export class MoniTimePicker extends MoniElement {
 		this.updateValue();
 	}
 
+	/**
+	 * Finaliza la interacción de arrastre en la carátula del reloj (Pointer Up).
+	 * 
+	 * Como heurística de usabilidad, si el usuario acaba de seleccionar la Hora,
+	 * el componente espera 300ms y automáticamente transiciona a la vista de Minutos.
+	 * Esto reduce los clics necesarios en interacciones de Time Pickers de un solo toque.
+	 */
 	private handleClockPointerUp() {
 		if (this.isDragging) {
 			this.isDragging = false;
 			this.clockFaceEl?.classList.remove('dragging');
 			if (this.activeSelection === 'hour') {
-				// Automatically switch to minute selection after choosing hour
+				// Cambiar automáticamente a la selección de minutos después de elegir la hora
 				setTimeout(() => {
 					this.activeSelection = 'minute';
 				}, 300);
@@ -194,6 +249,11 @@ export class MoniTimePicker extends MoniElement {
 		}
 	}
 
+	/**
+	 * Handler para entradas directas desde el `<input>` de horas (Modo 'input' texto).
+	 * Implementa clamping (límites mínimos y máximos) para asegurar que el usuario
+	 * nunca pueda introducir valores erróneos mayores a 23h o menores a 0h.
+	 */
 	private handleHourInputChange(e: Event) {
 		const target = e.target as HTMLInputElement;
 		let val = parseInt(target.value, 10);
@@ -211,6 +271,10 @@ export class MoniTimePicker extends MoniElement {
 		this.updateValue();
 	}
 
+	/**
+	 * Handler para entradas directas desde el `<input>` de minutos (Modo 'input' texto).
+	 * Trunca cualquier input alfanumérico a enteros y realiza un clamp a 0-59.
+	 */
 	private handleMinuteInputChange(e: Event) {
 		const target = e.target as HTMLInputElement;
 		let val = parseInt(target.value, 10);
@@ -598,6 +662,13 @@ export class MoniTimePicker extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderizador de la carátula circular (Dial Face).
+	 * 
+	 * Utiliza trigonometría básica (`sin` y `cos`) para distribuir los números equitativamente
+	 * a lo largo del perímetro del círculo en CSS absoluto. En formato 24h, renderiza
+	 * dos anillos concéntricos manipulando el radio relativo (`50%` vs `32%`).
+	 */
 	private renderDialClockFace() {
 		const isHour = this.activeSelection === 'hour';
 		let degrees = 0;
@@ -734,6 +805,30 @@ export class MoniTimePicker extends MoniElement {
 		`;
 	}
 
+	/**
+	 * Renderiza el selector de hora (time picker) en modo `dial` o `input`.
+	 *
+	 * **Visualización 12 vs 24 horas:**
+	 * `hourVal` convierte `currentHour` (0–23) al formato de visualización:
+	 * - Modo 24 horas: string con ceros a la izquierda (ej. `'09'`, `'14'`).
+	 * - Modo 12 horas: `0` → `12`, `13` → `1`, preservando la visualización AM/PM.
+	 * `minuteVal` siempre tiene ceros a la izquierda para tener 2 dígitos.
+	 *
+	 * **Modo dial:**
+	 * Renderiza una carátula de reloj DOM (HTML/CSS) con números distribuidos
+	 * circularmente para cada hora/minuto. El sub-método `renderDialClockFace()` 
+	 * maneja la geometría y estilos que mueven la manecilla selectora mientras
+	 * el usuario arrastra.
+	 *
+	 * **Modo input:**
+	 * Renderiza dos elementos `<input type="number">` para la hora y el minuto con
+	 * un selector AM/PM. El modo input es la alternativa (fallback) para accesibilidad
+	 * y entornos no táctiles.
+	 *
+	 * **Alternador de modo:**
+	 * Un icono de teclado cambia de modo `dial` a `input`; un icono de reloj
+	 * cambia de vuelta.
+	 */
 	override render() {
 		const hourVal = !this.use24Hour
 			? String(this.currentHour > 12 ? this.currentHour - 12 : this.currentHour === 0 ? 12 : this.currentHour).padStart(2, '0')

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

@@ -14,27 +14,27 @@ describe('moni-toolbar (P5.4 — recreated)', () => {
 		el.remove();
 	});
 
-	it('defaults to type=standard', async () => {
+	it('type=standard por defecto', async () => {
 		await el.updateComplete;
 		expect(el.type).toBe('standard');
 		expect(el.getAttribute('type')).toBe('standard');
 	});
 
-	it('renders a <header> container', async () => {
+	it('renderiza un contenedor <header>', async () => {
 		await el.updateComplete;
 		const header = el.shadowRoot?.querySelector('header');
 		expect(header).toBeTruthy();
 		expect(header?.getAttribute('part')).toBe('container');
 	});
 
-	it('renders the title attribute in the title span', async () => {
+	it('renderiza el atributo title en el span de título', async () => {
 		el.title = 'My App';
 		await el.updateComplete;
 		const title = el.shadowRoot?.querySelector('[part="title"]');
 		expect(title?.textContent?.trim()).toBe('My App');
 	});
 
-	it('supports slot fallback when title attribute is empty', async () => {
+	it('soporta slot de respaldo (fallback) cuando el atributo title está vacío', async () => {
 		const heading = document.createElement('h1');
 		heading.textContent = 'Slotted Title';
 		el.appendChild(heading);
@@ -46,7 +46,7 @@ describe('moni-toolbar (P5.4 — recreated)', () => {
 		expect(text).toBe('Slotted Title');
 	});
 
-	it('renders leading and trailing slots', async () => {
+	it('renderiza los slots leading y trailing', async () => {
 		const leading = document.createElement('button');
 		leading.setAttribute('slot', 'leading');
 		leading.textContent = 'Menu';
@@ -66,7 +66,7 @@ describe('moni-toolbar (P5.4 — recreated)', () => {
 		expect(trailingSlot?.assignedNodes({ flatten: true }).length).toBeGreaterThan(0);
 	});
 
-	it('switches to floating type', async () => {
+	it('cambia al tipo floating', async () => {
 		el.type = 'floating';
 		await el.updateComplete;
 		expect(el.getAttribute('type')).toBe('floating');
@@ -74,13 +74,13 @@ describe('moni-toolbar (P5.4 — recreated)', () => {
 		expect(header).toBeTruthy();
 	});
 
-	it('reflects scroll attribute', async () => {
+	it('refleja el atributo scroll', async () => {
 		el.scrolled = true;
 		await el.updateComplete;
 		expect(el.hasAttribute('scroll')).toBe(true);
 	});
 
-	it('reserves a slot for the action-button', async () => {
+	it('reserva un slot para el action-button', async () => {
 		const fab = document.createElement('button');
 		fab.setAttribute('slot', 'action-button');
 		fab.textContent = '+';