@moni-labs/moni-ui 0.3.0 → 0.3.2

package/dist/components/moni-side-sheet.d.ts

@@ -9,55 +9,55 @@ import { MoniElement } from './_base/index.js';
 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.
  */
 export declare class MoniSideSheet extends MoniElement {
     open: boolean;
@@ -79,15 +79,77 @@ export declare class MoniSideSheet extends MoniElement {
     private _defaultWidth;
     private _justDragged;
     private _getMaxWidthPx;
+    /**
+     * 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.
+     */
     updated(changedProperties: PropertyValues): void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Manejador del botón "Cerrar" explícito (X).
+     * Modifica la propiedad `open` a false y despacha el evento de cierre.
+     */
     private _onCloseClick;
+    /**
+     * 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;
+    /**
+     * 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;
     static styles: import("lit").CSSResult[];
+    /**
+     * 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`.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/moni-side-sheet.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-side-sheet.d.ts","sourceRoot":"","sources":["../../src/components/moni-side-sheet.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAa,cAAc,EAAE,MAAM,KAAK,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBACa,aAAc,SAAQ,WAAW;IACD,IAAI,UAAS;IACb,KAAK,UAAS;IAC7B,IAAI,EAAE,OAAO,GAAG,MAAM,CAAW;IACjC,KAAK,SAAM;IACI,QAAQ,UAAS;IACO,QAAQ,UAAS;IACjB,QAAQ,UAAS;IACf,UAAU,UAAS;IACpB,SAAS,UAAS;IAC7B,aAAa,SAAW;IAC7B,QAAQ,SAAM;IAElD,OAAO,CAAC,OAAO,CAAqB;IAErD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO,CAAC,cAAc;IAcb,OAAO,CAAC,iBAAiB,EAAE,cAAc;IAyDlD,OAAO,CAAC,cAAc;IAmBtB,OAAO,CAAC,cAAc;IAkCtB,OAAO,CAAC,YAAY;IAiFpB,OAAO,CAAC,gBAAgB;IAUxB,OAAO,CAAC,aAAa;IAKrB,OAAO,CAAC,YAAY;IAIpB,OAAO,CAAC,cAAc;IAUtB,OAAgB,MAAM,4BAgMpB;IAEO,MAAM;CA0Df;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,iBAAiB,EAAE,aAAa,CAAC;KACjC;CACD;AAED,eAAe,aAAa,CAAC"}
+{"version":3,"file":"moni-side-sheet.d.ts","sourceRoot":"","sources":["../../src/components/moni-side-sheet.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAa,cAAc,EAAE,MAAM,KAAK,CAAC;AAEhD,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAC7D,OAAO,gBAAgB,CAAC;AACxB,OAAO,kBAAkB,CAAC;AAE1B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,qBACa,aAAc,SAAQ,WAAW;IACD,IAAI,UAAS;IACb,KAAK,UAAS;IAC7B,IAAI,EAAE,OAAO,GAAG,MAAM,CAAW;IACjC,KAAK,SAAM;IACI,QAAQ,UAAS;IACO,QAAQ,UAAS;IACjB,QAAQ,UAAS;IACf,UAAU,UAAS;IACpB,SAAS,UAAS;IAC7B,aAAa,SAAW;IAC7B,QAAQ,SAAM;IAElD,OAAO,CAAC,OAAO,CAAqB;IAErD,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,oBAAoB,CAAK;IACjC,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,YAAY,CAAS;IAE7B,OAAO,CAAC,cAAc;IActB;;;;;;;OAOG;IACM,OAAO,CAAC,iBAAiB,EAAE,cAAc;IAyDlD;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;;;OAMG;IACH,OAAO,CAAC,cAAc;IAkCtB;;;;;;;;OAQG;IACH,OAAO,CAAC,YAAY;IAiFpB;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAUxB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAKrB;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAIpB;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAUtB,OAAgB,MAAM,4BAgMpB;IAEF;;;;;;;;;;;OAWG;IACM,MAAM;CA0Df;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,iBAAiB,EAAE,aAAa,CAAC;KACjC;CACD;AAED,eAAe,aAAa,CAAC"}

package/dist/components/moni-side-sheet.js

@@ -16,55 +16,55 @@ import { MoniElement, sharedStyles } from './_base/index.js';
 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.
  */
 let MoniSideSheet = class MoniSideSheet extends MoniElement {
     constructor() {
@@ -100,6 +100,14 @@ let MoniSideSheet = 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.
+     */
     updated(changedProperties) {
         super.updated(changedProperties);
         if (changedProperties.has('expandedWidth')) {
@@ -158,6 +166,12 @@ let MoniSideSheet = 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.
+     */
     _onPointerDown(e) {
         if (!this.withHandle)
             return;
@@ -175,6 +189,13 @@ let MoniSideSheet = class MoniSideSheet extends MoniElement {
         target.setPointerCapture(e.pointerId);
         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`).
+     */
     _onPointerMove(e) {
         if (!this._isDragging)
             return;
@@ -210,6 +231,15 @@ let MoniSideSheet = 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.
+     */
     _onPointerUp(e) {
         if (!this._isDragging)
             return;
@@ -293,6 +323,11 @@ let MoniSideSheet = 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.
+     */
     _onPointerCancel(e) {
         if (!this._isDragging)
             return;
@@ -303,13 +338,28 @@ let MoniSideSheet = class MoniSideSheet extends MoniElement {
         this._dialog.style.transform = '';
         this._dialog.style.width = '';
     }
+    /**
+     * Manejador del botón "Cerrar" explícito (X).
+     * Modifica la propiedad `open` a false y despacha el evento de cierre.
+     */
     _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.
+     */
     _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.
+     */
     _onDialogClick(e) {
         if (this._justDragged) {
             this._justDragged = false;
@@ -512,6 +562,18 @@ let MoniSideSheet = 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`.
+     */
     render() {
         const classes = [
             this.side,

package/dist/components/moni-slider.d.ts

@@ -7,92 +7,203 @@
 import { MoniElement } 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.
  */
 export declare class MoniSlider extends MoniElement {
+    /**
+     * Nombre del input del slider, usado en el envío de formularios.
+     * @type {string}
+     */
     name: string;
+    /**
+     * Valor mínimo del slider.
+     * @type {string}
+     * @default '0'
+     */
     min: string;
+    /**
+     * Valor máximo del slider.
+     * @type {string}
+     * @default '100'
+     */
     max: string;
+    /**
+     * Granularidad del slider. Debe ser un número positivo.
+     * @type {string}
+     */
     step: string;
+    /**
+     * Anula (overrides) el intervalo predeterminado de las marcas cuando `ticks` es verdadero.
+     * @type {number | null}
+     */
     tickInterval: number | null;
+    /**
+     * Nombre del icono (Material Symbols) mostrado dentro del control (thumb) del slider.
+     * @type {string}
+     */
     insetIcon: string;
+    /**
+     * Ubicación del tooltip indicador de valor.
+     * @type {'top' | 'bottom'}
+     * @default 'top'
+     */
     indicatorPlacement: 'top' | 'bottom';
+    /**
+     * Grosor/tamaño de la pista y el control (thumb) del slider.
+     * @type {'tiny' | 'small' | 'medium' | 'large' | 'extra'}
+     * @default 'medium'
+     */
     size: 'tiny' | 'small' | 'medium' | 'large' | 'extra';
+    /**
+     * Habilita el modo de rango (dos controles: `value` y `valueEnd`).
+     * @type {boolean}
+     */
     range: boolean;
+    /**
+     * Deshabilita el slider.
+     * @type {boolean}
+     */
     disabled: boolean;
+    /**
+     * Renderiza marcas (tick marks) a lo largo de la pista en cada intervalo de paso.
+     * @type {boolean}
+     */
     ticks: boolean;
+    /**
+     * Muestra un indicador de tooltip mostrando el(los) valor(es) actual(es) mientras se arrastra.
+     * @type {boolean}
+     */
     indicator: boolean;
+    /**
+     * Renderiza el slider de forma vertical en lugar de horizontal.
+     * @type {boolean}
+     */
     isVertical: boolean;
-    /** Internal reactive state — triggers CSS var updates on every input event */
+    /** Estado reactivo interno — dispara actualizaciones de variables CSS en cada evento de input */
     private _value;
     private _valueEnd;
+    /**
+     * El valor primario actual del slider (o el límite inferior en modo de rango).
+     * @type {string}
+     */
     get value(): string;
+    /**
+     * Intercepta asignaciones imperativas (`element.value = "X"`) para actualizar
+     * el estado interno de Lit, garantizando reactividad instantánea del DOM.
+     */
     set value(v: string);
+    /**
+     * El valor límite superior actual (solo usado cuando `range` es verdadero).
+     * @type {string}
+     */
     get valueEnd(): string;
+    /**
+     * Setter reactivo para el límite superior (usado exclusivamente en modo `range`).
+     */
     set valueEnd(v: string);
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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;
     /**
-     * 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;
     static styles: import("lit").CSSResult[];
+    /**
+     * 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.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {