@moni-labs/moni-ui 0.3.0 → 0.3.2

package/src/components/moni-ripple.ts

@@ -10,83 +10,83 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Visual-only ripple decoration component.
+ * Componente de decoración de onda (ripple) puramente visual.
  *
- * Provides a pointer-origin ripple animation — the expanding circle starts
- * at the exact pointer-down coordinates rather than the element's center.
- * This is the full-fidelity M3 ripple; for a simpler CSS-only center-ripple,
- * use the `interactionStyles` `.interactive::after` pseudo-element instead.
+ * Proporciona una animación de onda con origen en el puntero: el círculo expansivo comienza
+ * en las coordenadas exactas donde se pulsó (pointer-down) en lugar de en el centro del elemento.
+ * Esta es la onda M3 de alta fidelidad; para una onda central más simple solo con CSS,
+ * usa el pseudo-elemento `.interactive::after` de `interactionStyles` en su lugar.
  *
- * **Usage:**
- * Drop `<moni-ripple>` as a **child** of any interactive element. The component
- * automatically attaches a `pointerdown` listener to its `parentElement` and
- * calculates the ripple origin in percentage coordinates relative to the parent.
+ * **Uso:**
+ * Coloca `<moni-ripple>` como **hijo** de cualquier elemento interactivo. El componente
+ * adjunta automáticamente un listener de `pointerdown` a su `parentElement` y
+ * calcula el origen de la onda en coordenadas porcentuales relativas al padre.
  *
- * The parent element must NOT have `position: static` (the ripple applies
- * `position: relative` automatically in `connectedCallback`).
+ * El elemento padre NO debe tener `position: static` (la onda aplica
+ * `position: relative` automáticamente en `connectedCallback`).
  *
- * **Timing model:**
- * On `pointerdown`:
- * 1. `active = false` is set (cancels any in-progress ripple).
- * 2. A `requestAnimationFrame` tick ensures the browser has processed the reset.
- * 3. `active = true` triggers the CSS scale animation.
- * 4. A `setTimeout` of `duration` ms (based on `speed`) resets `active = false`.
+ * **Modelo de tiempo:**
+ * En `pointerdown`:
+ * 1. Se establece `active = false` (cancela cualquier onda en progreso).
+ * 2. Un tick de `requestAnimationFrame` asegura que el navegador haya procesado el reinicio.
+ * 3. `active = true` activa la animación de escala CSS.
+ * 4. Un `setTimeout` de duración `duration` ms (basado en `speed`) reinicia `active = false`.
  *
- * The duration matches the CSS transition duration so the opacity fade-out
- * completes before `active` is cleared.
+ * La duración coincide con la duración de la transición CSS para que el desvanecimiento de la opacidad
+ * se complete antes de que se limpie `active`.
  *
- * **Cleanup:**
- * `disconnectedCallback` removes the `pointerdown` listener and clears any
- * pending timeout. Always call `super.disconnectedCallback()` if subclassing.
+ * **Limpieza (Cleanup):**
+ * `disconnectedCallback` elimina el listener de `pointerdown` y borra cualquier
+ * tiempo de espera (timeout) pendiente. Llama siempre a `super.disconnectedCallback()` si usas subclases.
  *
  * @example
  * ```html
- * <!-- Ripple on a custom element -->
+ * <!-- Onda en un elemento personalizado -->
  * <div class="my-button" style="position: relative; overflow: hidden;">
- *   Click me
+ *   Haz clic
  *   <moni-ripple color="primary"></moni-ripple>
  * </div>
  * ```
  *
- * @csspart ripple - The inner `<span>` that performs the scale animation.
+ * @csspart ripple - El `<span>` interno que realiza la animación de escala.
  */
 @customElement('moni-ripple')
 export class MoniRipple extends MoniElement {
 	/**
-	 * Horizontal origin of the ripple as a percentage of the parent's width.
+	 * Origen horizontal de la onda como porcentaje del ancho del padre.
 	 *
-	 * Set automatically by `_onPointerDown` based on the pointer coordinates.
-	 * Can be set manually to trigger a ripple at a specific location.
+	 * Se establece automáticamente por `_onPointerDown` basándose en las coordenadas del puntero.
+	 * Se puede configurar manualmente para activar una onda en una ubicación específica.
 	 *
 	 * @default 50
 	 */
 	@property({ type: Number, reflect: true }) x = 50;
 
 	/**
-	 * Vertical origin of the ripple as a percentage of the parent's height.
+	 * Origen vertical de la onda como porcentaje de la altura del padre.
 	 *
-	 * Set automatically by `_onPointerDown` based on the pointer coordinates.
+	 * Se establece automáticamente por `_onPointerDown` basándose en las coordenadas del puntero.
 	 *
 	 * @default 50
 	 */
 	@property({ type: Number, reflect: true }) y = 50;
 
 	/**
-	 * When `true`, the ripple is visible and animating.
+	 * Cuando es `true`, la onda es visible y se está animando.
 	 *
-	 * Toggled automatically by `_onPointerDown`. Can be set manually for
-	 * programmatically-triggered ripple effects.
+	 * Alternado automáticamente por `_onPointerDown`. Se puede configurar manualmente para
+	 * efectos de onda disparados programáticamente.
 	 *
 	 * @default false
 	 */
 	@property({ type: Boolean, reflect: true }) active = false;
 
 	/**
-	 * Animation speed of the ripple expand-and-fade sequence.
+	 * Velocidad de animación de la secuencia de expansión y desvanecimiento de la onda.
 	 *
-	 * Maps to the `--_dur` CSS custom property:
+	 * Se asigna a la propiedad personalizada CSS `--_dur`:
 	 * - `'fast'`   — 300ms
-	 * - `'normal'` — 600ms (default)
+	 * - `'normal'` — 600ms (por defecto)
 	 * - `'slow'`   — 1200ms
 	 *
 	 * @default 'normal'
@@ -95,14 +95,14 @@ export class MoniRipple extends MoniElement {
 	speed: 'fast' | 'normal' | 'slow' = 'normal';
 
 	/**
-	 * Color token for the ripple overlay.
+	 * Token de color para la superposición de la onda.
 	 *
-	 * Sets the `color` CSS property on `:host`, which the `.ripple` span
-	 * inherits via `background-color: currentColor`.
+	 * Establece la propiedad CSS `color` en `:host`, que el span `.ripple`
+	 * hereda a través de `background-color: currentColor`.
 	 *
-	 * - `'primary'`   — `--primary` (default)
+	 * - `'primary'`   — `--primary` (por defecto)
 	 * - `'secondary'` — `--secondary`
-	 * - `'surface'`   — `--surface-variant` (subtle, for surface containers)
+	 * - `'surface'`   — `--surface-variant` (sutil, para contenedores de superficie)
 	 *
 	 * @default 'primary'
 	 */
@@ -110,25 +110,25 @@ export class MoniRipple extends MoniElement {
 	color: 'primary' | 'secondary' | 'surface' = 'primary';
 
 	/**
-	 * Reference to the parent element that the ripple is anchored to.
-	 * Populated in `connectedCallback`, cleared in `disconnectedCallback`.
+	 * Referencia al elemento padre al que está anclada la onda.
+	 * Poblado en `connectedCallback`, borrado en `disconnectedCallback`.
 	 */
 	private _target: HTMLElement | null = null;
 
 	/**
-	 * ID of the pending `setTimeout` that clears `active` after the animation.
-	 * Stored so it can be cancelled if a second pointer event fires before the
-	 * first ripple finishes (rapid double-tap prevention).
+	 * ID del `setTimeout` pendiente que borra `active` después de la animación.
+	 * Almacenado para que pueda cancelarse si se dispara un segundo evento de puntero antes
+	 * de que termine la primera onda (prevención de doble toque rápido).
 	 */
 	private _timeoutId: any = null;
 
 	/**
-	 * Attaches the ripple to its parent element.
+	 * Adjunta la onda a su elemento padre.
 	 *
-	 * - Stores a reference to `parentElement` for pointer event listening.
-	 * - Ensures the parent has `position: relative` so the ripple's `position: absolute`
-	 *   stays within bounds.
-	 * - Registers the `_onPointerDown` event listener.
+	 * - Almacena una referencia a `parentElement` para la escucha de eventos del puntero.
+	 * - Asegura que el padre tenga `position: relative` para que el `position: absolute`
+	 *   de la onda se mantenga dentro de los límites.
+	 * - Registra el listener de eventos `_onPointerDown`.
 	 */
 	override connectedCallback() {
 		super.connectedCallback();
@@ -143,10 +143,10 @@ export class MoniRipple extends MoniElement {
 	}
 
 	/**
-	 * Detaches the ripple from its parent element.
+	 * Desvincula la onda de su elemento padre.
 	 *
-	 * Removes the `pointerdown` listener and clears any pending timeout to
-	 * prevent the `active` flag from being set after the element is removed.
+	 * Elimina el listener de `pointerdown` y borra cualquier timeout pendiente para
+	 * evitar que la bandera `active` se establezca después de que se elimine el elemento.
 	 */
 	override disconnectedCallback() {
 		if (this._target) {
@@ -159,13 +159,13 @@ export class MoniRipple extends MoniElement {
 	}
 
 	/**
-	 * Handles pointer-down events on the parent element.
+	 * Maneja los eventos de puntero (pointer-down) en el elemento padre.
 	 *
-	 * Computes the ripple origin as a percentage of the parent's bounding rect,
-	 * cancels any in-progress ripple, then triggers a new one after one
-	 * animation frame to guarantee the CSS transition fires from the new position.
+	 * Calcula el origen de la onda como un porcentaje del rectángulo delimitador (bounding rect) del padre,
+	 * cancela cualquier onda en curso y luego activa una nueva después de un
+	 * frame de animación para garantizar que la transición CSS se dispare desde la nueva posición.
 	 *
-	 * @param e - The `PointerEvent` from the parent's `pointerdown` listener.
+	 * @param e - El `PointerEvent` del listener `pointerdown` del padre.
 	 */
 	private _onPointerDown = (e: PointerEvent) => {
 		if (!this._target) return;
@@ -245,6 +245,21 @@ export class MoniRipple extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el elemento `<span>` de la onda con las coordenadas de origen actuales.
+	 *
+	 * Este método de renderizado intencionalmente hace muy poco: la onda es fundamentalmente
+	 * una animación CSS (`scale`, `opacity`) impulsada por la clase `.active` que es
+	 * alternada por la API de activación de JavaScript (`MoniRipple.activate()`).
+	 *
+	 * `--_x` y `--_y` inyectan el origen del toque/clic como valores porcentuales:
+	 * - `x=0%, y=0%` — la onda se origina desde la esquina superior izquierda.
+	 * - `x=50%, y=50%` — origen central (por defecto para activación por teclado).
+	 * - `x=clientX%, y=clientY%` — onda con origen en el puntero para una sensación táctil natural.
+	 *
+	 * La clase CSS `.ripple` maneja la animación de expansión `scale(0)` → `scale(1)`
+	 * y el desvanecimiento `opacity 1` → `opacity 0` a través de transiciones CSS en `.active`.
+	 */
 	override render() {
 		return html`<span
 			class="ripple"

package/src/components/moni-segmented-button.test.ts

@@ -16,7 +16,7 @@ describe('moni-segmented-button', () => {
 		group.remove();
 	});
 
-	it('sets positioning shape properties on child segments', async () => {
+	it('establece propiedades de forma de posicionamiento en los segmentos hijos', async () => {
 		const seg1 = document.createElement('moni-button-segment') as MoniButtonSegment;
 		const seg2 = document.createElement('moni-button-segment') as MoniButtonSegment;
 		const seg3 = document.createElement('moni-button-segment') as MoniButtonSegment;
@@ -34,7 +34,7 @@ describe('moni-segmented-button', () => {
 		expect(seg3.position).toBe('last');
 	});
 
-	it('preserves positioning first/last when gap is set', async () => {
+	it('preserva el posicionamiento first/last cuando se establece gap', async () => {
 		group.gap = 'small';
 		const seg1 = document.createElement('moni-button-segment') as MoniButtonSegment;
 		const seg2 = document.createElement('moni-button-segment') as MoniButtonSegment;
@@ -49,7 +49,7 @@ describe('moni-segmented-button', () => {
 		expect(seg2.position).toBe('last');
 	});
 
-	it('manages checked state when clicked in single select mode', async () => {
+	it('maneja el estado checked al hacer clic en modo de selección única', async () => {
 		const seg1 = document.createElement('moni-button-segment') as MoniButtonSegment;
 		seg1.value = 'one';
 		const seg2 = document.createElement('moni-button-segment') as MoniButtonSegment;
@@ -74,7 +74,7 @@ describe('moni-segmented-button', () => {
 		expect(group.value).toBe('two');
 	});
 
-	it('manages checked state when clicked in multi select mode', async () => {
+	it('maneja el estado checked al hacer clic en modo de selección múltiple', async () => {
 		group.multi = true;
 		const seg1 = document.createElement('moni-button-segment') as MoniButtonSegment;
 		seg1.value = 'one';

package/src/components/moni-segmented-button.ts

@@ -11,37 +11,37 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import { MoniButtonSegment } from './moni-button-segment.js';
 
 /**
- * Material Design 3 Segmented Button component (Legacy).
+ * Componente Material Design 3 Segmented Button (Botón Segmentado) (Heredado).
  *
- * A form-associated group of selectable segmented buttons.
+ * Un grupo de botones segmentados seleccionables asociado a formularios.
  *
- * **Deprecation Notice:** The M3 spec (`m3-docs/components/segmented-buttons/overview.md`)
- * has updated the segmented button pattern. The bespoke segments have been
- * replaced with standard `<moni-button>` elements grouped inside a
+ * **Aviso de obsolescencia (Deprecation Notice):** La especificación M3 (`m3-docs/components/segmented-buttons/overview.md`)
+ * ha actualizado el patrón de botones segmentados. Los segmentos a medida han sido
+ * reemplazados por elementos estándar `<moni-button>` agrupados dentro de un
  * `<moni-button-group variant="connected">`.
  *
- * This component continues to work for backward compatibility but will be
- * removed in v1.0. A deprecation warning is logged to the console when the
- * element is connected to the DOM.
+ * Este componente sigue funcionando para mantener la compatibilidad con versiones anteriores, pero será
+ * eliminado en la v1.0. Se registra una advertencia de obsolescencia en la consola cuando el
+ * elemento se conecta al DOM.
  *
- * @deprecated Use `<moni-button-group variant="connected">` instead.
+ * @deprecated Usa `<moni-button-group variant="connected">` en su lugar.
  *
  * @example
  * ```html
- * <!-- Legacy usage (not recommended) -->
+ * <!-- Uso heredado (no recomendado) -->
  * <moni-segmented-button name="view" multi>
- *   <moni-button-segment value="day">Day</moni-button-segment>
- *   <moni-button-segment value="week">Week</moni-button-segment>
+ *   <moni-button-segment value="day">Día</moni-button-segment>
+ *   <moni-button-segment value="week">Semana</moni-button-segment>
  * </moni-segmented-button>
  *
- * <!-- Modern M3 equivalent -->
+ * <!-- Equivalente M3 moderno -->
  * <moni-button-group variant="connected">
- *   <moni-button>Day</moni-button>
- *   <moni-button>Week</moni-button>
+ *   <moni-button>Día</moni-button>
+ *   <moni-button>Semana</moni-button>
  * </moni-button-group>
  * ```
  *
- * @slot default - `<moni-button-segment>` elements.
+ * @slot default - elementos `<moni-button-segment>`.
  */
 @customElement('moni-segmented-button')
 export class MoniSegmentedButton extends MoniElement {
@@ -49,18 +49,39 @@ export class MoniSegmentedButton extends MoniElement {
 
 	private static _deprecationWarned = false;
 
+	/**
+	 * Nombre del botón segmentado, usado para el envío del formulario.
+	 * @type {string}
+	 */
 	@property({ reflect: true })
 	name = '';
 
+	/**
+	 * Permite seleccionar múltiples segmentos simultáneamente.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true })
 	multi = false;
 
+	/**
+	 * Tamaño de los segmentos del botón.
+	 * @type {'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'extra'}
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'extra' = 'medium';
 
+	/**
+	 * Oculta el icono de marca de verificación principal (leading checkmark) cuando se selecciona un segmento.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true, attribute: 'hide-check' })
 	hideCheck = false;
 
+	/**
+	 * Define un espaciado personalizado entre segmentos.
+	 * @type {string}
+	 */
 	@property()
 	gap = '';
 
@@ -69,6 +90,11 @@ export class MoniSegmentedButton extends MoniElement {
 
 	private internals: ElementInternals;
 
+	/**
+	 * Constructor del componente.
+	 * Inicializa ElementInternals (`attachInternals`) para integrar el custom element
+	 * nativamente en formularios HTML, permitiéndole participar en validaciones y envíos de datos.
+	 */
 	constructor() {
 		super();
 		this.internals = this.attachInternals();
@@ -89,10 +115,17 @@ export class MoniSegmentedButton extends MoniElement {
 		}
 	}
 
+	/**
+	 * Expone el formulario anfitrión al que pertenece este componente,
+	 * derivado de la API de ElementInternals.
+	 */
 	get form() {
 		return this.internals.form;
 	}
 
+	/**
+	 * Define el tipo semántico del control de formulario.
+	 */
 	get type() {
 		return 'segmented-button';
 	}
@@ -132,6 +165,12 @@ export class MoniSegmentedButton extends MoniElement {
 		`
 	];
 
+	/**
+	 * Hook del ciclo de vida reactivo (Lit).
+	 * Enlaza propiedades estructurales (como el gap o la visibilidad de los checks)
+	 * desde el contenedor padre hacia los segmentos hijos y comunica el nuevo valor
+	 * consolidado al formulario subyacente cada vez que el estado cambia.
+	 */
 	protected override updated(changedProperties: Map<string | number | symbol, unknown>) {
 		super.updated(changedProperties);
 		if (changedProperties.has('hideCheck') || changedProperties.has('size') || changedProperties.has('gap')) {
@@ -140,6 +179,11 @@ export class MoniSegmentedButton extends MoniElement {
 		this.updateFormValue();
 	}
 
+	/**
+	 * Manejador del Slot Change.
+	 * Re-evalúa jerárquicamente a los hijos proyectados si el DOM muta, 
+	 * reactualizando su topología visual (`border-radius`) y su valor en el form.
+	 */
 	private handleSlotChange() {
 		this.updateChildren();
 		this.updateFormValue();
@@ -156,6 +200,12 @@ export class MoniSegmentedButton extends MoniElement {
 		return gap;
 	}
 
+	/**
+	 * Patrón "Top-Down" para inyectar configuración visual y de posición a los segmentos hijos.
+	 * Dado que CSS no puede pasar atributos reactivos fácilmente a hijos proyectados (<slot>),
+	 * JS itera los hijos y les asigna si son 'first', 'middle' o 'last' para manejar
+	 * el `border-radius` continuo.
+	 */
 	private updateChildren() {
 		const segments = this.segments;
 		const len = segments.length;
@@ -176,12 +226,22 @@ export class MoniSegmentedButton extends MoniElement {
 		});
 	}
 
+	/**
+	 * Sincroniza el valor interno del componente (`this.value`) con
+	 * la estructura nativa del formulario utilizando la API de `ElementInternals.setFormValue`.
+	 * Permite que los datos viajen de forma natural al hacer submit.
+	 */
 	private updateFormValue() {
 		if (typeof this.internals.setFormValue === 'function') {
 			this.internals.setFormValue(this.value);
 		}
 	}
 
+	/**
+	 * Delegación de eventos (Event Delegation) capturando el click en el contenedor padre.
+	 * Maneja la lógica de exclusión mutua (single selection) estilo Radio Button
+	 * o la selección aditiva estilo Checkbox cuando `multi` es true.
+	 */
 	private handleClick(e: Event) {
 		const target = e.target as HTMLElement;
 		const clickedSegment = target.closest('moni-button-segment') as MoniButtonSegment | null;
@@ -193,11 +253,13 @@ export class MoniSegmentedButton extends MoniElement {
 		const segments = this.segments;
 
 		if (this.multi) {
+			// Toggle independiente
 			clickedSegment.checked = !clickedSegment.checked;
 		} else {
+			// Comportamiento de grupo radio: deseleccionar hermanos
 			segments.forEach((seg) => {
 				if (seg === clickedSegment) {
-					seg.checked = !seg.checked;
+					seg.checked = !seg.checked; // Permite toggle off incluso en single mode (comportamiento M3)
 				} else {
 					seg.checked = false;
 				}
@@ -219,6 +281,21 @@ export class MoniSegmentedButton extends MoniElement {
 		);
 	}
 
+	/**
+	 * Renderiza el contenedor del botón segmentado con un `role="group"` y su superposición de indicador GSAP.
+	 *
+	 * **Indicador deslizante:**
+	 * Un `<div>` `.indicator` se posiciona de forma absoluta dentro del contenedor del grupo.
+	 * GSAP anima su `left` y `width` para deslizarse de un segmento a otro
+	 * cuando la selección cambia (resaltado del segmento seleccionado del Segmented Button M3).
+	 * En el primer renderizado, el indicador se posiciona instantáneamente (sin transición); los cambios
+	 * posteriores usan `gsap.to()` con la curva de animación (easing) `_speed2` para un deslizamiento suave.
+	 *
+	 * **Sincronización `@slotchange`:**
+	 * Cuando los segmentos se agregan/eliminan en tiempo de ejecución, `_syncSegments()` vuelve a leer
+	 * los elementos asignados a la ranura (slot) y actualiza los atributos `first` / `last` de cada segmento
+	 * para controlar el border-radius en los segmentos terminales.
+	 */
 	override render() {
 		const resolvedGap = this.getGapValue(this.gap);
 		const inlineStyles = resolvedGap

package/src/components/moni-select-option.ts

@@ -10,42 +10,41 @@ import { customElement, property } from 'lit/decorators.js';
 import { MoniElement, sharedStyles } from './_base/index.js';
 
 /**
- * Material Design 3 Select Option component.
+ * Componente Material Design 3 Select Option (Opción de Selección).
  *
- * An individual selectable item designed to be placed inside a
- * `<moni-select>` dropdown.
+ * Un elemento individual seleccionable diseñado para colocarse dentro de un
+ * menú desplegable `<moni-select>`.
  *
- * **Interaction and layout:**
- * Options are rendered as accessible `<li>` elements styled identically to
- * `<moni-menu-item>`. When slotted into a `<moni-select>`, the parent
- * component extracts their `value`, `label`, and `group` attributes to build
- * its internal data model and handles the actual selection logic, keyboard
- * navigation, and rendering within the dropdown popup.
+ * **Interacción y diseño (layout):**
+ * Las opciones se renderizan como elementos `<li>` accesibles estilizados de forma idéntica a
+ * `<moni-menu-item>`. Cuando se insertan en un `<moni-select>`, el componente
+ * padre extrae sus atributos `value`, `label` y `group` para construir
+ * su modelo de datos interno y maneja la lógica de selección real, la navegación
+ * por teclado y el renderizado dentro del popup desplegable.
  *
- * **Grouping:**
- * Options can be categorized into subcategories by providing a `group`
- * attribute. The parent `<moni-select>` uses this to automatically generate
- * group headers (`<moni-select-group>`) in the dropdown list.
+ * **Agrupación:**
+ * Las opciones se pueden clasificar en subcategorías proporcionando un atributo
+ * `group`. El `<moni-select>` padre usa esto para generar automáticamente
+ * encabezados de grupo (`<moni-select-group>`) en la lista desplegable.
  *
  * @example
  * ```html
- * <moni-select label="Favorite framework">
- *   <!-- Standard option -->
+ * <moni-select label="Framework favorito">
+ *   <!-- Opción estándar -->
  *   <moni-select-option value="lit">Lit Element</moni-select-option>
  *
- *   <!-- Disabled option -->
- *   <moni-select-option value="react" disabled>React (not allowed)</moni-select-option>
+ *   <!-- Opción deshabilitada -->
+ *   <moni-select-option value="react" disabled>React (no permitido)</moni-select-option>
  *
- *   <!-- Grouped option -->
- *   <moni-select-option value="vue" group="Other">Vue.js</moni-select-option>
+ *   <!-- Opción agrupada -->
+ *   <moni-select-option value="vue" group="Otros">Vue.js</moni-select-option>
  * </moni-select>
  * ```
  *
- * @slot default - The text label for the option. If the `label` attribute is
- *                omitted, the parent `<moni-select>` will read this slot's
- *                `textContent`.
+ * @slot default - La etiqueta de texto para la opción. Si se omite el atributo `label`,
+ *                 el `<moni-select>` padre leerá el `textContent` de esta ranura (slot).
  *
- * @csspart item - The outer `<li>` element.
+ * @csspart item - El elemento `<li>` exterior.
  */
 @customElement('moni-select-option')
 export class MoniSelectOption extends MoniElement {
@@ -101,6 +100,14 @@ export class MoniSelectOption extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza la fila de la opción como un elemento de lista accesible con `role="option"`.
+	 *
+	 * `aria-selected=${this.selected}` permite a los lectores de pantalla anunciar el estado
+	 * de selección actual cuando el usuario navega por el cuadro de lista con las teclas de flecha.
+	 * Cuando `selected=true`, se renderiza un icono de marca de verificación principal (leading checkmark) a través de `<moni-icon name="check">`
+	 * en lugar del slot del icono principal, según la especificación de opciones de Select de M3.
+	 */
 	override render() {
 		return html`<li
 			part="option"