@moni-labs/moni-ui 0.3.1 → 0.3.2

package/src/components/moni-side-sheet.test.ts

@@ -14,7 +14,7 @@ describe('moni-side-sheet', () => {
 		el.remove();
 	});
 
-	it('initializes with default values', async () => {
+	it('se inicializa con valores por defecto', async () => {
 		await el.updateComplete;
 		expect(el.open).toBe(false);
 		expect(el.modal).toBe(false);
@@ -25,7 +25,7 @@ describe('moni-side-sheet', () => {
 		expect(el.showBack).toBe(false);
 	});
 
-	it('reflects open state to underlaying dialog', async () => {
+	it('refleja el estado open al dialog subyacente', async () => {
 		await el.updateComplete;
 		const dialog = el.shadowRoot?.querySelector('dialog') as HTMLDialogElement;
 		expect(dialog.open).toBe(false);
@@ -35,7 +35,7 @@ describe('moni-side-sheet', () => {
 		expect(dialog.open).toBe(true);
 	});
 
-	it('renders title and handles close click', async () => {
+	it('renderiza el título y maneja el clic de cerrar', async () => {
 		el.title = 'Configuración';
 		el.open = true;
 		await el.updateComplete;
@@ -57,7 +57,7 @@ describe('moni-side-sheet', () => {
 		expect(eventFired).toBe(true);
 	});
 
-	it('fires back event when back button clicked', async () => {
+	it('dispara el evento back cuando se hace clic en el botón de volver', async () => {
 		el.showBack = true;
 		await el.updateComplete;
 
@@ -73,7 +73,7 @@ describe('moni-side-sheet', () => {
 		expect(backFired).toBe(true);
 	});
 
-	it('applies correct class for noBorder', async () => {
+	it('aplica la clase correcta para noBorder', async () => {
 		const dialog = el.shadowRoot?.querySelector('dialog');
 		expect(dialog?.classList.contains('no-border')).toBe(false);
 
@@ -82,7 +82,7 @@ describe('moni-side-sheet', () => {
 		expect(dialog?.classList.contains('no-border')).toBe(true);
 	});
 
-	it('renders handle and supports drag dismissal when withHandle is true', async () => {
+	it('renderiza el tirador (handle) y soporta el cierre por arrastre cuando withHandle es true', async () => {
 		el.withHandle = true;
 		el.open = true;
 		await el.updateComplete;
@@ -113,7 +113,7 @@ describe('moni-side-sheet', () => {
 			closeFired = true;
 		});
 
-		// Trigger pointer drag to the right on a right aligned sheet
+		// Activar el arrastre del puntero hacia la derecha en una hoja alineada a la derecha
 		handle.dispatchEvent(new PointerEvent('pointerdown', { bubbles: true, clientX: 300, pointerId: 1 }));
 		dialog.dispatchEvent(new PointerEvent('pointermove', { bubbles: true, clientX: 550, pointerId: 1 })); // 250px right (greater than 400 * 0.4 = 160px)
 		handle.dispatchEvent(new PointerEvent('pointerup', { bubbles: true, clientX: 550, pointerId: 1 }));

package/src/components/moni-side-sheet.ts

@@ -12,55 +12,55 @@ import './moni-icon.js';
 import './moni-button.js';
 
 /**
- * Material Design 3 Side Sheet component.
+ * Componente Material Design 3 Side Sheet (Hoja o panel lateral).
  *
- * Side sheets show supplementary content that is anchored to the left or right
- * edge of the screen. They can be standard (inline with content) or modal
- * (overlaying content with a scrim).
+ * Los paneles laterales muestran contenido complementario que está anclado al borde
+ * izquierdo o derecho de la pantalla. Pueden ser estándar (en línea con el contenido)
+ * o modales (superpuestos al contenido con un fondo/scrim oscurecido).
  *
- * **M3 spec reference:** `m3-docs/components/side-sheets/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/side-sheets/specs.md`
  *
- * **Dialog behavior:**
- * Internally, this component uses the native HTML `<dialog>` element for robust
- * accessibility, focus trapping, and top-layer rendering.
- * - When `modal=true`, the sheet uses `dialog.showModal()`, rendering a scrim
- *   backdrop and trapping focus. Pressing `Escape` closes it.
- * - When `modal=false`, the sheet uses `dialog.show()` and remains interactive
- *   alongside the main page content.
+ * **Comportamiento del cuadro de diálogo (Dialog behavior):**
+ * Internamente, este componente utiliza el elemento HTML nativo `<dialog>` para una
+ * accesibilidad robusta, captura de foco y renderizado en la capa superior (top-layer).
+ * - Cuando `modal=true`, el panel usa `dialog.showModal()`, renderizando un fondo
+ *   (scrim backdrop) y capturando el foco. Al presionar `Escape` se cierra.
+ * - Cuando `modal=false`, el panel usa `dialog.show()` y permanece interactivo
+ *   junto al contenido de la página principal.
  *
- * **Drag & Resize (Moni feature):**
- * Setting the `with-handle` attribute adds a draggable grab handle to the inner
- * edge of the sheet. Users can click and drag this handle to resize the sheet's
- * width up to the `max-width` limit. If the user drags the sheet towards the
- * screen edge quickly or beyond a certain threshold, it automatically closes.
+ * **Arrastrar y redimensionar (Característica Moni):**
+ * Al configurar el atributo `with-handle`, se agrega un controlador de arrastre en el borde
+ * interior del panel. Los usuarios pueden hacer clic y arrastrar este controlador para 
+ * redimensionar el ancho del panel hasta el límite `max-width`. Si el usuario arrastra
+ * el panel hacia el borde de la pantalla rápidamente o más allá de cierto umbral, se cierra automáticamente.
  *
- * **Animations:**
- * Side sheets slide in from the specified `side` (`left` or `right`). The open
- * and close animations are handled via CSS transitions tied to the `open` property.
+ * **Animaciones:**
+ * Los paneles laterales se deslizan desde el `side` (lado) especificado (`left` o `right`).
+ * Las animaciones de apertura y cierre se manejan a través de transiciones CSS vinculadas a la propiedad `open`.
  *
- * @fires close - Fired when the side sheet is completely closed (after animations
- *                finish), either via the close button, scrim click, drag-to-close,
- *                or `Escape` key.
+ * @fires close - Se dispara cuando el panel lateral está completamente cerrado (después de
+ *                que terminan las animaciones), ya sea a través del botón de cierre, clic en el fondo (scrim),
+ *                arrastrar para cerrar o la tecla `Escape`.
  *
  * @example
  * ```html
- * <!-- Modal side sheet on the right -->
- * <moni-side-sheet id="details-sheet" modal title="Item Details">
- *   <p>Here is more information about the selected item.</p>
+ * <!-- Panel lateral modal a la derecha -->
+ * <moni-side-sheet id="details-sheet" modal title="Detalles del artículo">
+ *   <p>Aquí hay más información sobre el artículo seleccionado.</p>
  *   <div slot="footer">
- *     <moni-button>Save</moni-button>
+ *     <moni-button>Guardar</moni-button>
  *   </div>
  * </moni-side-sheet>
  *
- * <!-- Resizable, detached side sheet on the left -->
+ * <!-- Panel lateral a la izquierda, desvinculado (detached) y redimensionable -->
  * <moni-side-sheet side="left" detached with-handle max-width="50vw">
- *   <p>Navigation options</p>
+ *   <p>Opciones de navegación</p>
  * </moni-side-sheet>
  * ```
  *
- * @slot default - Main body content.
- * @slot header  - Custom header content (overrides `title`, close/back buttons remain).
- * @slot footer  - Bottom-anchored action area.
+ * @slot default - Contenido del cuerpo principal.
+ * @slot header  - Contenido de encabezado personalizado (anula `title`, los botones de cerrar/volver permanecen).
+ * @slot footer  - Área de acción anclada en la parte inferior.
  */
 @customElement('moni-side-sheet')
 export class MoniSideSheet extends MoniElement {
@@ -99,6 +99,14 @@ export class MoniSideSheet extends MoniElement {
 		return 600;
 	}
 
+	/**
+	 * Hook del ciclo de vida reactivo (Lit).
+	 * Coordina la transición del elemento `<dialog>` nativo.
+	 * Utiliza `showModal()` para Side Sheets modales (con backdrop) y `show()` 
+	 * para Side Sheets estándar. Administra manualmente la clase `.opened` y escucha
+	 * eventos `transitionend` para cerrar limpiamente el `<dialog>` sólo cuando 
+	 * las animaciones CSS terminan.
+	 */
 	override updated(changedProperties: PropertyValues) {
 		super.updated(changedProperties);
 
@@ -156,6 +164,12 @@ export class MoniSideSheet extends MoniElement {
 		}
 	}
 
+	/**
+	 * Inicia la interacción de arrastre (Drag) del Side Sheet.
+	 * Verifica si el usuario agarró el componente desde el "handle" o la cabecera.
+	 * Captura el ancho actual para determinar si el usuario pretende expandir o contraer
+	 * el panel lateral mediante gestos.
+	 */
 	private _onPointerDown(e: PointerEvent) {
 		if (!this.withHandle) return;
 		const target = e.target as HTMLElement;
@@ -175,6 +189,13 @@ export class MoniSideSheet extends MoniElement {
 		this._dialog.classList.add('dragging');
 	}
 
+	/**
+	 * Procesa el movimiento del arrastre y aplica transformaciones CSS inline
+	 * imperativamente a 60FPS. Diferencia la lógica dependiendo de la posición 
+	 * de anclaje (izquierdo vs derecho) y del estado actual (expandido vs contraído).
+	 * Introduce una "resistencia elástica" si el usuario intenta expandir el panel
+	 * más allá de su ancho máximo permitido (`maxWidth`).
+	 */
 	private _onPointerMove(e: PointerEvent) {
 		if (!this._isDragging) return;
 
@@ -209,6 +230,15 @@ export class MoniSideSheet extends MoniElement {
 		}
 	}
 
+	/**
+	 * Evalúa el resultado de la interacción de arrastre (Pointer Up).
+	 * 
+	 * Basado en umbrales de distancia física (`threshold`) y el estado actual, decide:
+	 * 1. Expandir el panel por completo (modo "expanded").
+	 * 2. Contraer el panel de vuelta a su tamaño estándar.
+	 * 3. Cerrar el Side Sheet totalmente y disparar el evento `close`.
+	 * Utiliza transiciones CSS nativas en vez de animar por frame para la resolución final.
+	 */
 	private _onPointerUp(e: PointerEvent) {
 		if (!this._isDragging) return;
 
@@ -290,6 +320,11 @@ export class MoniSideSheet extends MoniElement {
 		}
 	}
 
+	/**
+	 * Aborta limpiamente la interacción de arrastre (Pointer Cancel).
+	 * Remueve estilos imperativos y clases de estado (`dragging`) si el navegador
+	 * toma el control o la interacción se interrumpe prematuramente.
+	 */
 	private _onPointerCancel(e: PointerEvent) {
 		if (!this._isDragging) return;
 		const target = e.target as HTMLElement;
@@ -300,15 +335,30 @@ export class MoniSideSheet extends MoniElement {
 		this._dialog.style.width = '';
 	}
 
+	/**
+	 * Manejador del botón "Cerrar" explícito (X).
+	 * Modifica la propiedad `open` a false y despacha el evento de cierre.
+	 */
 	private _onCloseClick() {
 		this.open = false;
 		this.dispatchEvent(new CustomEvent('close', { bubbles: true, composed: true }));
 	}
 
+	/**
+	 * Manejador del botón "Atrás".
+	 * Emite un evento especializado `back` útil para Side Sheets de navegación anidada,
+	 * permitiendo a los controladores padres reaccionar cambiando la vista interna.
+	 */
 	private _onBackClick() {
 		this.dispatchEvent(new CustomEvent('back', { bubbles: true, composed: true }));
 	}
 
+	/**
+	 * Intercepta clics en el backdrop nativo del `<dialog>`.
+	 * Si el componente es `modal`, hacer clic fuera del panel cierra la interfaz.
+	 * Verifica `_justDragged` para evitar cerrar si el usuario hizo un click
+	 * "accidental" derivado del final de un arrastre.
+	 */
 	private _onDialogClick(e: MouseEvent) {
 		if (this._justDragged) {
 			this._justDragged = false;
@@ -513,6 +563,18 @@ export class MoniSideSheet extends MoniElement {
 		`
 	];
 
+	/**
+	 * Renderiza el panel lateral usando un elemento `<dialog>` nativo.
+	 *
+	 * **Manejo de estados:**
+	 * Utiliza clases dinámicas para controlar el lado (`left`/`right`), el modo (`modal`/`standard`),
+	 * y el estilo desvinculado (`detached`).
+	 *
+	 * **Atributo `[open]`:**
+	 * La vinculación `?open=${this.open}` añade o remueve el atributo `open` nativo de HTML.
+	 * Las transiciones visuales (slide-in/slide-out) son manejadas por el evento `transitionend` 
+	 * en el método `updated()` usando la clase `.opened`.
+	 */
 	override render() {
 		const classes = [
 			this.side,

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

@@ -14,13 +14,13 @@ describe('moni-slider (P3.4 — ticks)', () => {
 		el.remove();
 	});
 
-	it('does not render a datalist by default', async () => {
+	it('no renderiza un datalist por defecto', async () => {
 		await el.updateComplete;
 		const datalist = el.shadowRoot?.querySelector('datalist');
 		expect(datalist).toBeFalsy();
 	});
 
-	it('ticks=true renders a datalist with min and max options', async () => {
+	it('ticks=true renderiza un datalist con opciones min y max', async () => {
 		el.ticks = true;
 		await el.updateComplete;
 		const datalist = el.shadowRoot?.querySelector('datalist');
@@ -31,7 +31,7 @@ describe('moni-slider (P3.4 — ticks)', () => {
 		expect(options?.[1].getAttribute('value')).toBe('100');
 	});
 
-	it('tick-interval generates datalist options at every N units', async () => {
+	it('tick-interval genera opciones de datalist cada N unidades', async () => {
 		el.min = '0';
 		el.max = '10';
 		el.tickInterval = 2;
@@ -43,7 +43,7 @@ describe('moni-slider (P3.4 — ticks)', () => {
 		expect(values).toEqual(['0', '2', '4', '6', '8', '10']);
 	});
 
-	it('tick-interval respects a non-zero min', async () => {
+	it('tick-interval respeta un min distinto de cero', async () => {
 		el.min = '5';
 		el.max = '15';
 		el.tickInterval = 5;
@@ -54,7 +54,7 @@ describe('moni-slider (P3.4 — ticks)', () => {
 		expect(values).toEqual(['5', '10', '15']);
 	});
 
-	it('tick-interval takes precedence over the ticks boolean', async () => {
+	it('tick-interval tiene precedencia sobre el booleano ticks', async () => {
 		el.ticks = true;
 		el.min = '0';
 		el.max = '4';
@@ -66,13 +66,13 @@ describe('moni-slider (P3.4 — ticks)', () => {
 		expect(options.length).toBe(5);
 	});
 
-	it('reflects the tick-interval attribute on the host', async () => {
+	it('refleja el atributo tick-interval en el host', async () => {
 		el.tickInterval = 5;
 		await el.updateComplete;
 		expect(el.getAttribute('tick-interval')).toBe('5');
 	});
 
-	it('reflects min and max on the host', async () => {
+	it('refleja min y max en el host', async () => {
 		el.min = '10';
 		el.max = '20';
 		await el.updateComplete;

package/src/components/moni-slider.ts

@@ -12,99 +12,190 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 import './moni-icon.js';
 
 /**
- * Material Design 3 Slider component.
+ * Componente Material Design 3 Slider (Control deslizante).
  *
- * Sliders allow users to select a single value or a range of values from a
- * continuous or discrete scale.
+ * Los sliders permiten a los usuarios seleccionar un solo valor o un rango de valores
+ * desde una escala continua o discreta.
  *
- * **M3 spec reference:** `m3-docs/components/sliders/specs.md`
+ * **Referencia a la especificación M3:** `m3-docs/components/sliders/specs.md`
  *
- * **Slider modes:**
- * - **Continuous** (default) — Smooth drag between `min` and `max`. Use when
- *   the exact value does not need to be defined by the user (e.g. volume).
- * - **Discrete** — Set `step` to snap to discrete intervals. Tick marks
- *   appear via the native `<datalist>` element in Chrome/Edge. Firefox does
- *   not render datalist ticks for range inputs.
- * - **Range** (`range` attribute) — Two thumbs that define a minimum and
- *   maximum value within the slider's extent.
- * - **Vertical** (`vertical` attribute) — 90° rotated slider.
+ * **Modos de Slider:**
+ * - **Continuo (Continuous)** (por defecto) — Arrastre suave entre `min` y `max`. Úsalo cuando
+ *   no sea necesario que el usuario defina un valor exacto (ej. volumen).
+ * - **Discreto (Discrete)** — Configura `step` para ajustarse a intervalos discretos. Las marcas
+ *   (tick marks) aparecen a través del elemento nativo `<datalist>` en Chrome/Edge. Firefox no
+ *   renderiza marcas de datalist para inputs de tipo rango.
+ * - **Rango (Range)** (atributo `range`) — Dos controles (thumbs) que definen un valor mínimo y
+ *   máximo dentro de la extensión del slider.
+ * - **Vertical** (atributo `vertical`) — Slider rotado 90°.
  *
- * **Value label tooltip:**
- * When `indicator` is set, the current value is displayed in a tooltip above
- * (or below, via `indicator-placement`) the active thumb during focus/drag.
+ * **Tooltip indicador de valor (Value label tooltip):**
+ * Cuando se configura `indicator`, el valor actual se muestra en un tooltip por encima
+ * (o por debajo, a través de `indicator-placement`) del control activo durante el foco/arrastre.
  *
- * **Tick marks:**
- * - `ticks` attribute: adds datalist with marks at `min` and `max` only.
- * - `tick-interval` attribute: generates datalist options at every N units
- *   between `min` and `max`, creating visible tick marks at those positions.
+ * **Marcas (Tick marks):**
+ * - Atributo `ticks`: agrega datalist con marcas solo en `min` y `max`.
+ * - Atributo `tick-interval`: genera opciones de datalist cada N unidades
+ *   entre `min` y `max`, creando marcas visibles en esas posiciones.
  *
- * **Internal state management:**
- * Uses `@state()` for `_value` and `_valueHigh` so the fill track width and
- * tooltip position update reactively on every drag `input` event without
- * waiting for the `change` event.
+ * **Manejo del estado interno:**
+ * Usa `@state()` para `_value` y `_valueHigh` de modo que el ancho de la pista de llenado y
+ * la posición del tooltip se actualicen de forma reactiva en cada evento `input` de arrastre sin
+ * esperar al evento `change`.
  *
- * @fires change - Bubbles and is composed. Fired when dragging ends and the
- *                 value is committed. Read `element.value` for the new value.
- * @fires input  - Fired on every drag step. Read `element.value` for the
- *                 live value during drag.
+ * @fires change - Burbujea y está compuesto. Se dispara cuando termina el arrastre y el
+ *                 valor se confirma. Lee `element.value` para el nuevo valor.
+ * @fires input  - Se dispara en cada paso del arrastre. Lee `element.value` para el
+ *                 valor en vivo durante el arrastre.
  *
  * @example
  * ```html
- * <!-- Continuous slider -->
+ * <!-- Slider continuo -->
  * <moni-slider name="volume" min="0" max="100" value="60"></moni-slider>
  *
- * <!-- Discrete slider with ticks every 10 units -->
+ * <!-- Slider discreto con marcas cada 10 unidades -->
  * <moni-slider step="10" tick-interval="10" indicator></moni-slider>
  *
- * <!-- Range slider -->
+ * <!-- Slider de rango -->
  * <moni-slider range min="0" max="100" value="20" value-high="80"></moni-slider>
  * ```
  *
- * @csspart slider    - The outer slider container.
- * @csspart track     - The track background.
- * @csspart fill      - The filled portion of the track.
- * @csspart indicator - The value label tooltip.
+ * @csspart slider    - El contenedor exterior del slider.
+ * @csspart track     - El fondo de la pista.
+ * @csspart fill      - La porción llena de la pista.
+ * @csspart indicator - El tooltip de la etiqueta de valor.
  */
 @customElement('moni-slider')
 export class MoniSlider extends MoniElement {
+	/**
+	 * Nombre del input del slider, usado en el envío de formularios.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) name = '';
+
+	/**
+	 * Valor mínimo del slider.
+	 * @type {string}
+	 * @default '0'
+	 */
 	@property({ reflect: true }) min = '0';
+
+	/**
+	 * Valor máximo del slider.
+	 * @type {string}
+	 * @default '100'
+	 */
 	@property({ reflect: true }) max = '100';
+
+	/**
+	 * Granularidad del slider. Debe ser un número positivo.
+	 * @type {string}
+	 */
 	@property({ reflect: true }) step = '';
+
+	/**
+	 * Anula (overrides) el intervalo predeterminado de las marcas cuando `ticks` es verdadero.
+	 * @type {number | null}
+	 */
 	@property({ type: Number, reflect: true, attribute: 'tick-interval' })
 	tickInterval: number | null = null;
+
+	/**
+	 * Nombre del icono (Material Symbols) mostrado dentro del control (thumb) del slider.
+	 * @type {string}
+	 */
 	@property({ reflect: true, attribute: 'inset-icon' }) insetIcon = '';
+
+	/**
+	 * Ubicación del tooltip indicador de valor.
+	 * @type {'top' | 'bottom'}
+	 * @default 'top'
+	 */
 	@property({ reflect: true, attribute: 'indicator-placement' })
 	indicatorPlacement: 'top' | 'bottom' = 'top';
+
+	/**
+	 * Grosor/tamaño de la pista y el control (thumb) del slider.
+	 * @type {'tiny' | 'small' | 'medium' | 'large' | 'extra'}
+	 * @default 'medium'
+	 */
 	@property({ reflect: true })
 	size: 'tiny' | 'small' | 'medium' | 'large' | 'extra' = 'medium';
 
-	// Boolean attributes
+	/**
+	 * Habilita el modo de rango (dos controles: `value` y `valueEnd`).
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) range = false;
+
+	/**
+	 * Deshabilita el slider.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) disabled = false;
+
+	/**
+	 * Renderiza marcas (tick marks) a lo largo de la pista en cada intervalo de paso.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) ticks = false;
+
+	/**
+	 * Muestra un indicador de tooltip mostrando el(los) valor(es) actual(es) mientras se arrastra.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true }) indicator = false;
+
+	/**
+	 * Renderiza el slider de forma vertical en lugar de horizontal.
+	 * @type {boolean}
+	 */
 	@property({ type: Boolean, reflect: true, attribute: 'vertical' }) isVertical = false;
 
-	/** Internal reactive state — triggers CSS var updates on every input event */
+	/** Estado reactivo interno — dispara actualizaciones de variables CSS en cada evento de input */
 	@state() private _value = '50';
 	@state() private _valueEnd = '75';
 
+	/**
+	 * El valor primario actual del slider (o el límite inferior en modo de rango).
+	 * @type {string}
+	 */
 	@property({ reflect: true })
 	get value() { return this._value; }
+	/**
+	 * Intercepta asignaciones imperativas (`element.value = "X"`) para actualizar
+	 * el estado interno de Lit, garantizando reactividad instantánea del DOM.
+	 */
 	set value(v: string) { this._value = v; }
 
+	/**
+	 * El valor límite superior actual (solo usado cuando `range` es verdadero).
+	 * @type {string}
+	 */
 	@property({ reflect: true, attribute: 'value-end' })
 	get valueEnd() { return this._valueEnd; }
+	/**
+	 * Setter reactivo para el límite superior (usado exclusivamente en modo `range`).
+	 */
 	set valueEnd(v: string) { this._valueEnd = v; }
 
+	/**
+	 * Calcula el porcentaje de llenado de la barra (0-100) basándose en el valor actual,
+	 * el mínimo y el máximo. Se utiliza intensivamente para definir variables CSS (como `--_pct`).
+	 */
 	private _pct(v: string) {
 		const min = parseFloat(this.min) || 0;
 		const max = parseFloat(this.max) || 100;
 		const val = parseFloat(v) || 0;
+		// Math.max/min asegura que no desborde si por alguna razón val > max o val < min
 		return Math.max(0, Math.min(100, ((val - min) / (max - min)) * 100));
 	}
 
+	/**
+	 * Maneja el evento nativo "input" de los inputs type="range" subyacentes.
+	 * Se dispara contínuamente mientras el usuario arrastra el slider.
+	 * Actualiza el estado reactivo inmediatamente para que la UI responda en tiempo real (60fps).
+	 */
 	private _onInput(e: Event, index: number) {
 		const target = e.target as HTMLInputElement;
 		if (index === 0) {
@@ -112,9 +203,14 @@ export class MoniSlider extends MoniElement {
 		} else {
 			this._valueEnd = target.value;
 		}
+		// Redisparamos el evento hacia afuera para que los frameworks (React/Vue/Angular) puedan atraparlo
 		this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
 	}
 
+	/**
+	 * Maneja el evento nativo "change", que se dispara solo cuando el usuario SUELTA el slider
+	 * (al terminar la interacción). Útil para peticiones HTTP pesadas o validaciones finales.
+	 */
 	private _onChange(e: Event, index: number) {
 		const target = e.target as HTMLInputElement;
 		if (index === 0) {
@@ -126,11 +222,11 @@ export class MoniSlider extends MoniElement {
 	}
 
 	/**
-	 * Render a `<datalist>` element with tick options. When `tick-interval`
-	 * is set, generates options at every N units between min and max.
-	 * Otherwise, if `ticks` is set, just min and max.
-	 * Browsers that support datalist ticks for range (Chrome, Edge) will
-	 * render visual marks; Firefox ignores them.
+	 * Renderiza un elemento `<datalist>` con opciones de marcas. Cuando se establece
+	 * `tick-interval`, genera opciones cada N unidades entre el mínimo y el máximo.
+	 * De lo contrario, si se establece `ticks`, solo mínimo y máximo.
+	 * Los navegadores que soportan marcas de datalist para inputs de rango (Chrome, Edge)
+	 * renderizarán marcas visuales; Firefox las ignora.
 	 */
 	private _renderDatalist() {
 		if (this.tickInterval != null && this.tickInterval > 0) {
@@ -358,6 +454,33 @@ export class MoniSlider extends MoniElement {
 		`
 	];
 
+	/**
+	 * Ensambla la estructura del Shadow DOM del slider.
+	 *
+	 * **Cálculo de la pista llena:**
+	 * `pct` y `pctEnd` son valores porcentuales (0–100) derivados de
+	 * `_pct(value)`. Se inyectan como propiedades CSS personalizadas `--_start` y `--_end`
+	 * en el contenedor `.slider`. El pseudo-elemento CSS `::before`
+	 * utiliza estos valores en un `clip-path: polygon(...)` para renderizar la parte
+	 * no llena de la pista, mientras que el `<span>` renderiza la parte llena.
+	 *
+	 * **Modo Rango (`range=true`):**
+	 * - Se renderizan dos elementos `<input type="range">` (uno para el límite inferior,
+	 *   otro para el límite superior).
+	 * - El CSS los superpone absolutamente para que los controles (thumbs) compartan la misma línea de pista.
+	 * - `--_start` equivale al porcentaje del control inferior; `--_end` equivale a `100 - pctEnd`.
+	 *
+	 * **Tooltip indicador:**
+	 * Los elementos tooltip `.tooltip-1` / `.tooltip-2` están posicionados absolutamente
+	 * utilizando `inset-inline-start: ${pct}%` de modo que siguen al control activo
+	 * por encima (o por debajo) a medida que el usuario arrastra. La visibilidad se controla
+	 * puramente a través de selectores CSS `:focus` — no se requiere JavaScript.
+	 *
+	 * **Datalist de marcas (Tick datalist):**
+	 * `_renderDatalist()` emite un `<datalist id="ticks">` solo cuando `ticks` o
+	 * `tick-interval` está establecido. Chrome/Edge renderizan marcas nativas en inputs de rango
+	 * que referencian un datalist a través del atributo `list`; Firefox lo ignora.
+	 */
 	override render() {
 		const pct = this._pct(this._value);
 		const pctEnd = this._pct(this._valueEnd);