@moni-labs/moni-ui 0.3.0 → 0.3.2

package/src/components/moni-stepper.ts

@@ -11,43 +11,43 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import type { MoniStep } from './moni-step.js';
 
 /**
- * Material Design 3 Stepper component.
+ * Componente Material Design 3 Stepper (Pasos/Progresión).
  *
- * A container for a linear progression of `<moni-step>` elements. Steppers
- * convey progress through numbered steps and indicate the user's current
- * position within a flow.
+ * Un contenedor para una progresión lineal de elementos `<moni-step>`. Los steppers
+ * transmiten el progreso a través de pasos numerados e indican la posición
+ * actual del usuario dentro de un flujo.
  *
- * **M3 spec reference:** `m3-docs/components/progress-indicators/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/progress-indicators/specs.md`
  *
- * **Orchestration:**
- * This component acts as the orchestrator for its slotted `<moni-step>` children.
- * Whenever the `current` property changes, or children are added/removed, the
- * stepper iterates over all child steps and injects their state:
- * - Assigns the sequential `index` (0-based) to each step.
- * - Sets `active=true` on the step matching the `current` index.
- * - Sets `completed=true` on all steps prior to the `current` index.
+ * **Orquestación:**
+ * Este componente actúa como orquestador para sus hijos `<moni-step>` en los slots.
+ * Cada vez que cambia la propiedad `current` o se añaden/eliminan hijos, el
+ * stepper itera sobre todos los pasos hijos e inyecta su estado:
+ * - Asigna el `index` secuencial (basado en 0) a cada paso.
+ * - Establece `active=true` en el paso que coincide con el índice `current`.
+ * - Establece `completed=true` en todos los pasos anteriores al índice `current`.
  *
- * **Visual layout:**
- * The stepper manages the layout (flex row or column based on `orientation`)
- * and ensures the connector lines between steps are rendered correctly via
- * CSS pseudo-elements defined in the child `<moni-step>` styling.
+ * **Diseño visual:**
+ * El stepper maneja el diseño (flex row o column basado en `orientation`)
+ * y asegura que las líneas conectoras entre los pasos se rendericen correctamente a través de
+ * pseudo-elementos CSS definidos en los estilos del `<moni-step>` hijo.
  *
  * @example
  * ```html
  * <moni-stepper current="1" orientation="horizontal">
- *   <moni-step title="Step 1"></moni-step>
- *   <moni-step title="Step 2"></moni-step>
- *   <moni-step title="Step 3"></moni-step>
+ *   <moni-step title="Paso 1"></moni-step>
+ *   <moni-step title="Paso 2"></moni-step>
+ *   <moni-step title="Paso 3"></moni-step>
  * </moni-stepper>
  *
  * <script>
  *   const stepper = document.querySelector('moni-stepper');
- *   // Move to next step
+ *   // Mover al siguiente paso
  *   stepper.current = 2;
  * </script>
  * ```
  *
- * @slot default - `<moni-step>` elements.
+ * @slot default - Elementos `<moni-step>`.
  */
 @customElement('moni-stepper')
 export class MoniStepper extends MoniElement {
@@ -58,6 +58,11 @@ export class MoniStepper extends MoniElement {
 	@queryAssignedElements({ selector: 'moni-step' })
 	private _steps!: MoniStep[];
 
+	/**
+	 * Hook del ciclo de vida reactivo (Lit).
+	 * Cuando la orientación o el índice actual cambian, sincroniza
+	 * el estado hacia todos los elementos hijos (`<moni-step>`).
+	 */
 	override updated(changed: Map<string, unknown>) {
 		if (
 			changed.has('current') ||
@@ -69,24 +74,39 @@ export class MoniStepper extends MoniElement {
 	}
 
 	/**
-	 * Propagate the `current` index to each child <moni-step>:
-	 *  - sets `index` from the child's position
-	 *  - sets `completed` on every step before `current`
-	 *  - sets `active` on the step at `current`
+	 * Propaga el índice del paso actual a cada elemento hijo `<moni-step>` en los slots,
+	 * calculando e inyectando el estado de `index`, `completed` y `active`.
+	 *
+	 * **Diferimiento por microtarea (`Promise.resolve().then(...)`):**
+	 * `@queryAssignedElements` de Lit se ejecuta sincrónicamente y no está disponible hasta
+	 * después del primer renderizado conectado. Diferirlo a una microtarea asegura que los hijos
+	 * en los slots hayan terminado su propio ciclo de vida `firstUpdated()` antes de que les escribamos
+	 * el estado. Sin este diferimiento, escribir `step.active = true` durante el `updated()`
+	 * del padre puede desencadenar renderizados hijos antes de que se apliquen sus estilos.
 	 *
-	 * Deferred to a microtask so that slotted children are guaranteed
-	 * to have finished their first update cycle before we write to them.
+	 * **Respaldo de `querySelectorAll`:**
+	 * `_steps` (de `@queryAssignedElements`) devuelve un array vacío antes del primer
+	 * renderizado o cuando no hay elementos `<moni-step>` presentes en el slot. El respaldo
+	 * a `querySelectorAll('moni-step')` maneja casos extremos donde se añaden pasos
+	 * programáticamente sin pasar por el mecanismo de slots de Lit.
+	 *
+	 * **Bucle de inyección de estado:**
+	 * Para cada `<moni-step>` en la posición `stepIndex`:
+	 * - `stepElement.index = stepIndex` — proporciona el número de paso para su etiqueta.
+	 * - `stepElement.completed = stepIndex < current` — verdadero para todos los pasos anteriores a `current`.
+	 * - `stepElement.active = stepIndex === current` — verdadero solo para el paso en `current`.
 	 */
 	private _syncSteps() {
 		Promise.resolve().then(() => {
-			let steps = this._steps || [];
-			if (steps.length === 0) {
-				steps = Array.from(this.querySelectorAll('moni-step')) as MoniStep[];
+			// Usa el resultado de @queryAssignedElements de Lit primero; usa una consulta DOM en vivo como respaldo.
+			let stepElements = this._steps || [];
+			if (stepElements.length === 0) {
+				stepElements = Array.from(this.querySelectorAll('moni-step')) as MoniStep[];
 			}
-			steps.forEach((step, i) => {
-				step.index = i;
-				step.completed = i < this.current;
-				step.active = i === this.current;
+			stepElements.forEach((stepElement, stepIndex) => {
+				stepElement.index = stepIndex;
+				stepElement.completed = stepIndex < this.current;
+				stepElement.active = stepIndex === this.current;
 			});
 		});
 	}
@@ -117,12 +137,30 @@ export class MoniStepper extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el contenedor de lista ordenada (`<ol>`) que contiene los hijos `<moni-step>` en los slots.
+	 *
+	 * **Anatomía:**
+	 * - El `<ol>` usa `list-style: none` y un diseño flex (fila o columna, basado en
+	 *   `orientation`) en lugar del renderizado nativo de lista ordenada, porque la
+	 *   visualización del número de paso es manejada por cada hijo `<moni-step>`.
+	 * - La vinculación del evento `@slotchange` asegura que se llame a `_syncSteps()`
+	 *   cada vez que el consumidor añade o elimina elementos `<moni-step>` en tiempo de ejecución,
+	 *   manteniendo los estados `index`, `active` y `completed` sincronizados.
+	 * - Cada `<moni-step>` en el slot está estilizado con `flex: 1` para que todos los pasos
+	 *   compartan el ancho disponible equitativamente (horizontal) o la altura (vertical).
+	 */
 	override render() {
 		return html`<ol class="list" part="stepper">
 			<slot @slotchange=${this._onSlotChange}></slot>
 		</ol>`;
 	}
 
+	/**
+	 * Handler dinámico del slot.
+	 * Detecta si el usuario añade o elimina pasos nativos (`<moni-step>`)
+	 * desde el DOM en tiempo de ejecución, forzando una re-sincronización.
+	 */
 	private _onSlotChange = () => {
 		// Steps may have been added/removed; re-sync.
 		this._syncSteps();

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

@@ -14,7 +14,7 @@ describe('moni-switch', () => {
 		el.remove();
 	});
 
-	it('renders an input and a span containing track/thumb pseudo-elements', async () => {
+	it('renderiza un input y un span que contiene pseudo-elementos track/thumb', async () => {
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector('input');
 		const span = el.shadowRoot?.querySelector('span');
@@ -22,7 +22,7 @@ describe('moni-switch', () => {
 		expect(span).toBeTruthy();
 	});
 
-	it('input has role=switch', async () => {
+	it('el input tiene role=switch', async () => {
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
 			'input'
@@ -30,7 +30,7 @@ describe('moni-switch', () => {
 		expect(input.getAttribute('role')).toBe('switch');
 	});
 
-	it('input is contained in the label (for click handling)', async () => {
+	it('el input está contenido en el label (para el manejo de clics)', async () => {
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
 			'input'
@@ -39,7 +39,7 @@ describe('moni-switch', () => {
 		expect(label?.contains(input)).toBe(true);
 	});
 
-	it('forwards checked state to the input', async () => {
+	it('reenvía el estado checked al input', async () => {
 		el.checked = true;
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
@@ -52,14 +52,14 @@ describe('moni-switch', () => {
 		expect(input.checked).toBe(false);
 	});
 
-	it('renders a label span when label attribute is set', async () => {
+	it('renderiza un span de label cuando se establece el atributo label', async () => {
 		el.label = 'Wi-Fi';
 		await el.updateComplete;
 		const label = el.shadowRoot?.querySelector('.label');
 		expect(label?.textContent?.trim()).toBe('Wi-Fi');
 	});
 
-	it('forwards disabled to the input', async () => {
+	it('reenvía disabled al input', async () => {
 		el.disabled = true;
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
@@ -68,13 +68,13 @@ describe('moni-switch', () => {
 		expect(input.disabled).toBe(true);
 	});
 
-	it('reflects the checked attribute', async () => {
+	it('refleja el atributo checked', async () => {
 		el.checked = true;
 		await el.updateComplete;
 		expect(el.hasAttribute('checked')).toBe(true);
 	});
 
-	it('renders close and check icons when icon=true', async () => {
+	it('renderiza iconos de cierre y verificación cuando icon=true', async () => {
 		el.icon = true;
 		await el.updateComplete;
 		const icons = el.shadowRoot?.querySelectorAll('span > i');
@@ -84,14 +84,14 @@ describe('moni-switch', () => {
 		expect(icons?.[1].textContent).toBe('check');
 	});
 
-	it('does not render a thumb icon when icon=false', async () => {
+	it('no renderiza un icono de pulgar cuando icon=false', async () => {
 		el.icon = false;
 		await el.updateComplete;
 		const icons = el.shadowRoot?.querySelectorAll('span > i');
 		expect(icons?.length).toBe(0);
 	});
 
-	it('forwards name to the input', async () => {
+	it('reenvía name al input', async () => {
 		el.name = 'wifi';
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
@@ -100,7 +100,7 @@ describe('moni-switch', () => {
 		expect(input.name).toBe('wifi');
 	});
 
-	it('forwards value to the input', async () => {
+	it('reenvía value al input', async () => {
 		el.value = 'on';
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector(
@@ -109,7 +109,7 @@ describe('moni-switch', () => {
 		expect(input.value).toBe('on');
 	});
 
-	it('input is rendered inside the switch label', async () => {
+	it('el input se renderiza dentro del label del switch', async () => {
 		await el.updateComplete;
 		const input = el.shadowRoot?.querySelector('input');
 		expect(input).toBeTruthy();

package/src/components/moni-switch.ts

@@ -12,125 +12,136 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Material Design 3 Switch component.
+ * Componente Material Design 3 Switch (Interruptor).
  *
- * Switches toggle the state of a single setting on or off. They are the
- * binary on/off equivalent of a checkbox, but optimized for toggling a
- * single state rather than selecting from a list.
+ * Los switches alternan el estado de una configuración individual entre encendido y apagado.
+ * Son el equivalente binario encendido/apagado de una casilla de verificación (checkbox),
+ * pero optimizados para alternar un solo estado en lugar de seleccionar de una lista.
  *
- * **M3 spec reference:** `m3-docs/components/switch/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/switch/specs.md`
  *
- * **M3 measurements:**
- * - Track: 52dp × 32dp, 2dp border, full-radius pill shape.
- * - Handle (thumb): 16dp unselected → 24dp selected → 28dp pressed.
- * - State layer: 40dp circular ripple on hover/focus/pressed states.
- * - Icon (optional): 16dp icon rendered inside the thumb when `icon` is set.
+ * **Medidas M3:**
+ * - Pista (Track): 52dp × 32dp, borde de 2dp, forma de píldora con radio completo.
+ * - Control (Thumb): 16dp no seleccionado → 24dp seleccionado → 28dp presionado.
+ * - Capa de estado (State layer): ripple circular de 40dp en estados de hover/focus/pressed.
+ * - Icono (opcional): icono de 16dp renderizado dentro del control (thumb) cuando `icon` está activado.
  *
- * **Visual architecture:**
- * Like `<moni-checkbox>`, the native `<input type="checkbox" role="switch">`
- * occupies real layout space but is visually hidden via `opacity: 0`. Two
- * `<span>` pseudo-elements render the track (`::after`) and thumb (`::before`).
- * When `icon=true`, `<i>` elements render `close` and `check` glyphs inside
- * the thumb, with visibility toggled via CSS based on the checked state.
+ * **Arquitectura visual:**
+ * Al igual que `<moni-checkbox>`, el `<input type="checkbox" role="switch">` nativo
+ * ocupa espacio real en el diseño pero está oculto visualmente mediante `opacity: 0`. Dos
+ * pseudo-elementos de un `<span>` renderizan la pista (`::after`) y el control (`::before`).
+ * Cuando `icon=true`, los elementos `<i>` renderizan los glifos `close` y `check` dentro
+ * del control, y su visibilidad se alterna mediante CSS en base al estado verificado (checked).
  *
- * @fires change - Bubbles and is composed. Fired when the switch is toggled.
- *                 Read `element.checked` for the new state.
+ * @fires change - Burbujea y está compuesto. Se dispara cuando el switch se alterna.
+ *                 Lee `element.checked` para obtener el nuevo estado.
  *
  * @example
  * ```html
- * <moni-switch label="Dark mode" name="dark-mode"></moni-switch>
- * <moni-switch icon checked label="Notifications"></moni-switch>
+ * <moni-switch label="Modo oscuro" name="dark-mode"></moni-switch>
+ * <moni-switch icon checked label="Notificaciones"></moni-switch>
  *
  * <script>
  *   document.querySelector('moni-switch').addEventListener('change', (e) => {
- *     console.log('enabled:', e.target.checked);
+ *     console.log('activado:', e.target.checked);
  *   });
  * </script>
  * ```
  *
- * @csspart switch - The outer `<label>` element containing the switch.
+ * @csspart switch - El elemento `<label>` exterior que contiene el switch.
  */
 @customElement('moni-switch')
 export class MoniSwitch extends MoniElement {
+	static formAssociated = true;
+	private _internals: ElementInternals;
+
+	constructor() {
+		super();
+		this._internals = this.attachInternals();
+	}
+
 	/**
-	 * Text label displayed to the right of the switch.
+	 * Etiqueta de texto mostrada a la derecha del switch.
 	 *
-	 * When non-empty, renders as a padded text span after the track.
-	 * When empty, the default slot is rendered, allowing custom HTML labels.
+	 * Cuando no está vacía, se renderiza como un span de texto con padding después de la pista.
+	 * Cuando está vacía, se renderiza el slot por defecto, permitiendo etiquetas HTML personalizadas.
 	 *
 	 * @default ''
 	 */
 	@property({ reflect: true }) label = '';
 
 	/**
-	 * Whether the switch is in the "on" (checked) state.
+	 * Indica si el switch está en el estado "encendido" (marcado/checked).
 	 *
-	 * When `true`:
-	 * - Track fills with `--primary` color.
-	 * - Thumb grows from 16dp to 24dp and slides to the trailing edge.
-	 * - Thumb color changes to `--on-primary`.
+	 * Cuando es `true`:
+	 * - La pista se llena con el color `--primary`.
+	 * - El control (thumb) crece de 16dp a 24dp y se desliza hacia el borde final (trailing).
+	 * - El color del control cambia a `--on-primary`.
 	 *
 	 * @default false
 	 */
 	@property({ type: Boolean, reflect: true }) checked = false;
 
 	/**
-	 * When `true`, the switch is non-interactive and renders at 50% opacity.
+	 * Cuando es `true`, el switch no es interactivo y se renderiza al 50% de opacidad.
 	 *
 	 * @default false
 	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
 
 	/**
-	 * When `true`, renders icon glyphs inside the thumb.
+	 * Cuando es `true`, renderiza glifos de iconos dentro del control (thumb).
 	 *
-	 * Uses Material Symbols ligatures:
-	 * - Unchecked state: `close` icon.
-	 * - Checked state: `check` icon.
+	 * Utiliza ligaduras de Material Symbols:
+	 * - Estado desmarcado (Unchecked): icono `close`.
+	 * - Estado marcado (Checked): icono `check`.
 	 *
-	 * The icon size (16dp) is set via the `--_thumb` CSS custom property.
+	 * El tamaño del icono (16dp) se establece a través de la propiedad CSS `--_thumb`.
 	 *
 	 * @default false
 	 */
 	@property({ type: Boolean, reflect: true }) icon = false;
 
 	/**
-	 * Forwarded to the native `<input name>` attribute for form participation.
+	 * Reenviado al atributo nativo `<input name>` para participar en formularios.
 	 *
 	 * @default ''
 	 */
 	@property({ reflect: true }) name = '';
 
 	/**
-	 * Forwarded to the native `<input value>` attribute.
-	 * The value submitted in a form when this switch is checked.
+	 * Reenviado al atributo nativo `<input value>`.
+	 * El valor enviado en un formulario cuando este switch está marcado.
 	 *
 	 * @default ''
 	 */
 	@property({ reflect: true }) value = '';
 
-	/** Direct reference to the native input element for programmatic access. */
+	/** Referencia directa al elemento input nativo para acceso programático. */
 	@query('input') private _input!: HTMLInputElement;
 
 	/**
-	 * Syncs `checked` and `disabled` imperatively to the native input after render.
+	 * Sincroniza `checked` y `disabled` de forma imperativa en el input nativo después del renderizado.
 	 *
-	 * @param changed - Map of changed property names to their previous values.
+	 * @param changed - Mapa de los nombres de las propiedades modificadas a sus valores anteriores.
 	 */
 	override updated(changed: Map<string, unknown>) {
 		if (this._input) {
-			if (changed.has('checked')) this._input.checked = this.checked;
+			if (changed.has('checked')) {
+				this._input.checked = this.checked;
+				this._internals?.setFormValue?.(this.checked ? (this.value || 'on') : null);
+			}
 			if (changed.has('disabled')) this._input.disabled = this.disabled;
 		}
 	}
 
 	/**
-	 * Handles the native input `change` event.
+	 * Maneja el evento nativo `change` del input.
 	 *
-	 * Updates `this.checked` and re-dispatches a composed `'change'` event
-	 * so it bubbles across shadow DOM boundaries.
+	 * Actualiza `this.checked` y vuelve a despachar un evento `'change'` compuesto
+	 * para que burbujee a través de los límites del shadow DOM.
 	 *
-	 * @param e - The native `change` event from the hidden `<input>`.
+	 * @param e - El evento nativo `change` desde el `<input>` oculto.
 	 */
 	private _onChange(e: Event) {
 		this.checked = (e.target as HTMLInputElement).checked;
@@ -300,6 +311,14 @@ export class MoniSwitch extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el switch como un `<input type="checkbox">` oculto + pista visual mediante `<span>`.
+	 *
+	 * El input oculto ocupa espacio de diseño real (para el área de clic/hit area) pero tiene opacidad 0;
+	 * el `<span>` proporciona la píldora visual y el control (thumb) (vía `::before`/`::after`).
+	 * La vinculación `.checked` asegura que el estado del input en el DOM se mantenga sincronizado con
+	 * `this.checked`.
+	 */
 	override render() {
 		return html`<label class=${this.icon ? 'switch icon' : 'switch'} part="switch">
 			<input

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

@@ -21,31 +21,31 @@ describe('moni-tab indicator-size', () => {
 		tabs.remove();
 	});
 
-	it('reflects indicatorSize on the host', async () => {
+	it('refleja indicatorSize en el host', async () => {
 		tabs.indicatorSize = 'min';
 		await tabs.updateComplete;
 		expect(tabs.getAttribute('indicator-size')).toBe('min');
 	});
 
-	it('reflects indicatorSize="max" on the host', async () => {
+	it('refleja indicatorSize="max" en el host', async () => {
 		tabs.indicatorSize = 'max';
 		await tabs.updateComplete;
 		expect(tabs.getAttribute('indicator-size')).toBe('max');
 	});
 
-	it('reflects indicatorSize="default" on the host', async () => {
+	it('refleja indicatorSize="default" en el host', async () => {
 		tabs.indicatorSize = 'default';
 		await tabs.updateComplete;
 		expect(tabs.getAttribute('indicator-size')).toBe('default');
 	});
 
-	it('vertical orientation is reflected on the tabs host', async () => {
+	it('la orientación vertical se refleja en el host de las pestañas (tabs)', async () => {
 		tabs.vertical = true;
 		await tabs.updateComplete;
 		expect(tabs.hasAttribute('vertical')).toBe(true);
 	});
 
-	it('tab active state reflects aria-selected=true', async () => {
+	it('el estado activo de la pestaña refleja aria-selected=true', async () => {
 		tab.active = true;
 		await tab.updateComplete;
 		const a = tab.shadowRoot?.querySelector('a');

package/src/components/moni-tab.ts

@@ -11,35 +11,35 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Material Design 3 Tab component.
+ * Componente Material Design 3 Tab (Pestaña).
  *
- * An individual interactive tab element designed to be placed inside a
- * `<moni-tabs>` container. Tabs organize content across different screens,
- * data sets, and other interactions.
+ * Un elemento interactivo de pestaña individual diseñado para ser colocado dentro de un
+ * contenedor `<moni-tabs>`. Las pestañas organizan el contenido en diferentes pantallas,
+ * conjuntos de datos y otras interacciones.
  *
- * **M3 spec reference:** `m3-docs/components/tabs/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/tabs/specs.md`
  *
- * **Visual layout & interaction:**
- * Internally renders as an `<a>` element to support native link behavior when
- * an `href` is provided, but behaves visually as a tab button. It displays a
- * text label and an optional Material icon. If the parent `<moni-tabs>` has the
- * `vertical` attribute set, the layout automatically adjusts to stack the icon
- * above the text.
+ * **Diseño visual e interacción:**
+ * Internamente se renderiza como un elemento `<a>` para soportar el comportamiento nativo
+ * de enlace cuando se proporciona un `href`, pero se comporta visualmente como un botón de pestaña.
+ * Muestra una etiqueta de texto y un icono opcional de Material. Si el `<moni-tabs>` padre tiene el
+ * atributo `vertical` configurado, el diseño se ajusta automáticamente para apilar el icono
+ * encima del texto.
  *
- * **State:**
- * The `active` attribute highlights the tab, applying the primary color to the
- * text and rendering the active indicator line (handled via CSS in the parent
- * container or pseudo-elements).
+ * **Estado:**
+ * El atributo `active` resalta la pestaña, aplicando el color principal (primary) al
+ * texto y renderizando la línea indicadora activa (manejado vía CSS en el contenedor
+ * padre o mediante pseudo-elementos).
  *
  * @example
  * ```html
  * <moni-tabs>
- *   <moni-tab active icon="home" label="Home"></moni-tab>
- *   <moni-tab icon="settings" label="Settings" href="/settings"></moni-tab>
+ *   <moni-tab active icon="home" label="Inicio"></moni-tab>
+ *   <moni-tab icon="settings" label="Ajustes" href="/settings"></moni-tab>
  * </moni-tabs>
  * ```
  *
- * @csspart tab - The inner `<a>` element acting as the tab button.
+ * @csspart tab - El elemento `<a>` interno que actúa como botón de pestaña.
  */
 @customElement('moni-tab')
 export class MoniTab extends MoniElement {
@@ -113,8 +113,8 @@ export class MoniTab extends MoniElement {
 				block-size: auto;
 			}
 
-			/* M3 indicator-size='min': 24dp tall (centered on tab) with
-			   8dp top/bottom radius — matches M3 spec § Indicator anatomy. */
+			/* M3 indicator-size='min': 24dp de altura (centrado en la pestaña) con
+			   radio superior/inferior de 8dp — coincide con la especificación M3 § Indicator anatomy. */
 			:host-context(moni-tabs[indicator-size='min']) a.active::before {
 				margin: 0 auto;
 				max-inline-size: min(100%, 4rem);
@@ -130,13 +130,21 @@ export class MoniTab extends MoniElement {
 				border-radius: 0.5rem;
 			}
 
-			/* M3 indicator-size='max': full tab height, no rounding. */
+			/* M3 indicator-size='max': altura completa de la pestaña, sin redondeo. */
 			:host-context(moni-tabs[indicator-size='max']) a.active::before {
 				border-radius: 0;
 			}
 		`
 	];
 
+	/**
+	 * Renderiza el botón de pestaña con un icono opcional y etiqueta.
+	 *
+	 * El botón de pestaña es un elemento `<a>` con `aria-selected` para
+	 * cumplimiento WCAG. La clase `active` controla la transición de subrayado
+	 * del indicador CSS (a través del pseudo-elemento `::before`). El `<moni-icon>`
+	 * opcional se renderiza antes del texto de la etiqueta cuando se establece `icon`.
+	 */
 	override render() {
 		return html`<a
 			href=${this.href || '#'}