@moni-labs/moni-ui 0.3.0 → 0.3.2

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

@@ -6,151 +6,582 @@
  */
 import { MoniElement } from './_base/index.js';
 /**
- * Data model for a single item in a `<moni-carousel>`.
+ * Modelo de datos para un solo elemento en un `<moni-carousel>`.
  */
 export interface CarouselItem {
-    /** Display title overlaid on the item. */
+    /** Título a mostrar sobre el elemento. */
     title: string;
-    /** URL or path to the background image. */
+    /** URL o ruta a la imagen de fondo. */
     img: string;
-    /** Optional link target. If provided, the item renders as an `<a>` element. */
+    /** Objetivo de enlace opcional. Si se proporciona, el elemento se renderiza como un `<a>`. */
     href?: string;
-    /** Link target attribute (e.g. `'_blank'`). Only applies if `href` is set. */
+    /** Atributo target del enlace (ej. `'_blank'`). Solo se aplica si se establece `href`. */
     target?: string;
 }
 /**
- * Material Design 3 Expressive Carousel component.
+ * Componente Material Design 3 Expressive Carousel.
  *
- * Carousels display a collection of related items in a scrollable, horizontal list.
- * They allow users to quickly browse through items like images, cards, or products.
+ * Los carruseles muestran una colección de elementos relacionados en una lista horizontal desplazable.
+ * Permiten a los usuarios navegar rápidamente a través de elementos como imágenes, tarjetas, o productos.
  *
- * **M3 spec reference:** `m3-docs/components/carousel/specs.md`
+ * **Referencia de la especificación M3:** `m3-docs/components/carousel/specs.md`
  *
- * **Layout variants:**
- * - `multi-browse` (default) — Shows a mix of large, medium, and small (peeking)
- *   items. Best for exploring a large number of items.
- * - `hero` — Focuses on one large primary item while showing a sliver of the
- *   next item. Best for featuring important content.
- * - `uncontained` — Standard layout where all items have the same width and
- *   bleed off the edges of the container.
+ * **Variantes de diseño:**
+ * - `multi-browse` (por defecto) — Muestra una mezcla de elementos grandes, medianos y pequeños (asomando).
+ *   Mejor para explorar un gran número de elementos.
+ * - `hero` — Se enfoca en un elemento primario grande mientras muestra una fracción del
+ *   siguiente elemento. Mejor para destacar contenido importante.
+ * - `uncontained` — Diseño estándar donde todos los elementos tienen el mismo ancho y
+ *   se desbordan por los bordes del contenedor.
  *
- * **Animation & Gestures:**
- * This component uses GSAP for smooth drag, flick, and snap animations,
- * mirroring the high-fidelity M3 Expressive motion specs. It handles touch
- * gestures for mobile and mouse-drag for desktop.
+ * **Animación y Gestos:**
+ * Este componente usa GSAP para animaciones suaves de arrastre, deslizamiento y ajuste,
+ * reflejando las especificaciones de movimiento de alta fidelidad de M3 Expressive. Maneja
+ * gestos táctiles para móviles y arrastre del ratón para escritorio.
  *
- * **Auto-sizing (`auto` mode):**
- * When `auto=true` (default), the carousel measures its own width and
- * dynamically calculates the optimal sizes for large, medium, and small items
- * based on the active `layout` to ensure they fit perfectly without awkward gaps
- * or clipping at the edges.
+ * **Auto-tamaño (modo `auto`):**
+ * Cuando `auto=true` (por defecto), el carrusel mide su propio ancho y
+ * calcula dinámicamente los tamaños óptimos para los elementos grandes, medianos y pequeños
+ * basados en el `layout` activo para asegurar que encajen perfectamente sin huecos incómodos
+ * ni recortes en los bordes.
  *
  * @example
  * ```html
- * <!-- Declarative usage via DOM properties (recommended) -->
+ * <!-- Uso declarativo a través de propiedades DOM (recomendado) -->
  * <moni-carousel layout="hero"></moni-carousel>
  * <script>
  *   const carousel = document.querySelector('moni-carousel');
  *   carousel.items = [
- *     { title: 'Item 1', img: '/img1.jpg', href: '/link1' },
- *     { title: 'Item 2', img: '/img2.jpg' }
+ *     { title: 'Elemento 1', img: '/img1.jpg', href: '/link1' },
+ *     { title: 'Elemento 2', img: '/img2.jpg' }
  *   ];
  * </script>
  *
- * <!-- Slot-based usage (for SSR or simple static content) -->
+ * <!-- Uso basado en slots (para SSR o contenido estático simple) -->
  * <moni-carousel layout="uncontained">
  *   <div slot="item">
  *     <img src="/img1.jpg" />
- *     <h3>Static Item</h3>
+ *     <h3>Elemento Estático</h3>
  *   </div>
  * </moni-carousel>
  * ```
  *
- * @slot item - Alternative to the `items` property. Slot individual HTML elements
- *              instead of passing data objects.
+ * @slot item - Alternativa a la propiedad `items`. Inserta elementos HTML individuales
+ *              en lugar de pasar objetos de datos.
  *
- * @csspart carousel - The outer wrapper.
- * @csspart track    - The scrolling track element.
- * @csspart item     - Individual carousel item containers.
- * @csspart img      - The image elements inside the items.
- * @csspart title    - The title text elements inside the items.
+ * @csspart carousel - El envoltorio exterior.
+ * @csspart track    - El elemento de la pista desplazable.
+ * @csspart item     - Contenedores de elementos del carrusel individuales.
+ * @csspart img      - Los elementos de imagen dentro de los elementos.
+ * @csspart title    - Los elementos de texto de título dentro de los elementos.
  */
 export declare class MoniCarousel extends MoniElement {
+    /**
+     * Array de elementos a mostrar en el carrusel.
+     * Cada elemento requiere al menos `title` e `img`. El opcional `href` renderiza la tarjeta como un enlace.
+     * @default []
+     */
     items: CarouselItem[];
+    /**
+     * Variante de diseño visual. Determina cuántos elementos son visibles y cómo escalan.
+     * - `'multi-browse'` (por defecto) — Elementos grandes + medianos + pequeños (asomando).
+     * - `'hero'` — Uno o más elementos grandes + elemento pequeño asomando.
+     * - `'uncontained'` — Elementos de igual ancho que se desbordan por el borde.
+     * @default 'multi-browse'
+     */
     layout: 'multi-browse' | 'hero' | 'uncontained';
+    /**
+     * Cuando es `true`, el carrusel calcula los tamaños óptimos de los elementos automáticamente
+     * basado en el ancho del contenedor y la variante de `layout` activa.
+     * Cuando es `false`, usa los valores explícitos `largeWidth`, `mediumWidth`, `smallWidth`.
+     * @default true
+     */
     auto: boolean;
+    /**
+     * Ancho en píxeles para el elemento grande (enfoque principal) del carrusel.
+     * Solo se usa cuando `auto=false`.
+     * @default 220
+     */
     largeWidth: number;
+    /**
+     * Ancho en píxeles para el elemento de tamaño mediano (secundario) del carrusel.
+     * Solo se usa cuando `auto=false` y `layout='multi-browse'`.
+     * @default 96
+     */
     mediumWidth: number;
+    /**
+     * Ancho en píxeles para el elemento pequeño (asomando) del carrusel.
+     * Solo se usa cuando `auto=false`.
+     * @default 48
+     */
     smallWidth: number;
+    /**
+     * Espacio en píxeles entre los elementos del carrusel.
+     * @default 8
+     */
     gap: number;
+    /**
+     * Relleno horizontal en píxeles aplicado al inicio de la pista del carrusel.
+     * @default 16
+     */
     padding: number;
+    /**
+     * Radio del borde en píxeles aplicado a cada tarjeta.
+     * @default 28
+     */
     borderRadius: number;
+    /**
+     * Cuando es `true`, renderiza un enlace "Mostrar todo" en el encabezado.
+     * @default false
+     */
     showAll: boolean;
+    /**
+     * Texto de etiqueta para el enlace "Mostrar todo".
+     * @default 'Show all'
+     */
     showAllText: string;
+    /**
+     * Encabezado de sección opcional renderizado sobre la pista del carrusel.
+     * @default ''
+     */
     headerText: string;
+    /**
+     * Cuando es `true`, oculta los botones de flecha de navegación anterior/siguiente.
+     * @default false
+     */
     hideNav: boolean;
+    /**
+     * Cuando es `true`, habilita el bucle infinito sin interrupciones clonando la lista de elementos
+     * a través de un búfer de desplazamiento virtual grande, luego reposicionando silenciosamente
+     * el desplazamiento cuando el usuario se acerca a cualquier borde.
+     * @default false
+     */
+    infinite: boolean;
+    /**
+     * Cuando es `true`, avanza automáticamente el carrusel en el intervalo definido
+     * por `autoplayInterval`. La reproducción automática se detiene durante las interacciones de arrastre activas.
+     * @default false
+     */
+    autoplay: boolean;
+    /**
+     * Milisegundos entre los avances automáticos de diapositivas cuando `autoplay=true`.
+     * @default 3000
+     */
+    autoplayInterval: number;
+    /**
+     * Ancho medido del elemento host del carrusel en píxeles.
+     * Actualizado por el `ResizeObserver` en cada redimensionamiento del contenedor y usado por
+     * `computedLayout` para calcular cuántos elementos caben en la pantalla.
+     */
     private _containerWidth;
+    /**
+     * Elementos analizados desde el slot Light DOM (uso declarativo).
+     * Poblado por `_handleSlotChange` cuando los usuarios insertan elementos `<img>` o `<a><img></a>`.
+     */
     private _slottedItems;
+    /**
+     * Si el slot `show-all` contiene contenido proyectado por el usuario.
+     * Controla si se renderiza el área "Mostrar todo" del encabezado.
+     */
     private _hasSlottedShowAll;
+    /**
+     * Devuelve la fuente del elemento activo.
+     * La propiedad programática `items` tiene prioridad sobre los hijos Light DOM en slots.
+     * Recurre a `_slottedItems` cuando no se proporcionan elementos programáticos.
+     */
     get effectiveItems(): CarouselItem[];
+    /**
+     * Referencia directa al div contenedor de desplazamiento.
+     * Usado para leer `scrollLeft`, modificar `scrollBehavior`, y calcular `scrollWidth`.
+     */
     private _scrollContainer;
+    /**
+     * NodeList en vivo de todos los elementos de tarjeta renderizados.
+     * Usado por el motor de diseño para aplicar actualizaciones de transform/width por cuadro a través de GSAP quickSetters.
+     */
     private _cards;
+    /** Instancia ResizeObserver que observa las dimensiones del elemento host. */
     private _resizeObserver;
-    private _isDown;
-    private _startX;
-    private _scrollLeftStart;
-    private _velocity;
-    private _lastTime;
-    private _lastX;
-    private _draggedDistance;
-    private _rafId;
+    /** Estado interno de visibilidad (por índice lógico) para evitar falsos eventos al ciclar el scroll infinito */
+    private _logicalItemInViewport;
+    /** `true` mientras el usuario arrastra activamente (ratón o toque presionado). */
+    private _isDragging;
+    /** Coordenada X en el inicio del gesto de arrastre actual (relativa al contenedor de desplazamiento). */
+    private _dragStartX;
+    /** Valor `scrollLeft` del contenedor en el momento en que comenzó el arrastre. */
+    private _scrollLeftAtDragStart;
+    /**
+     * Velocidad del puntero en píxeles por milisegundo.
+     * Calculada gradualmente durante el arrastre y usada para el impulso/inercia al soltar.
+     */
+    private _pointerVelocity;
+    /** Marca de tiempo (de `performance.now()`) del último evento de movimiento del puntero/toque. */
+    private _lastPointerTime;
+    /** Coordenada X del puntero en el cuadro del evento de movimiento anterior. */
+    private _lastPointerX;
+    /**
+     * Distancia horizontal absoluta acumulada (en píxeles) recorrida durante el arrastre actual.
+     * Usada para distinguir un deslizamiento intencional de un clic accidental (umbral: 8px).
+     */
+    private _totalDraggedDistance;
+    /**
+     * ID de `requestAnimationFrame` activo del bucle de desplazamiento por inercia.
+     * Almacenado para que pueda cancelarse cuando el usuario inicia un nuevo arrastre.
+     */
+    private _animationFrameId;
+    /** `true` cuando el ancho de la ventana gráfica coincide con el punto de ruptura móvil (`max-width: 600px`). */
     private _isMobile;
+    /**
+     * La posición de desplazamiento hacia la que el ticker de GSAP está interpolando (lerping) **en cada cuadro**.
+     * Expresada en unidades de `itemSize` (no píxeles) para matemáticas independientes del diseño.
+     */
     private _tickerTarget;
+    /**
+     * La posición de desplazamiento interpolada actual usada para impulsar el diseño visual.
+     * Interpola hacia `_tickerTarget` en cada cuadro, creando el efecto de suavizado.
+     */
     private _tickerCurrent;
+    /**
+     * `true` mientras el callback del ticker de GSAP (`_tick`) está registrado y en ejecución.
+     * Evita añadir el callback del ticker múltiples veces en llamadas concurrentes.
+     */
     private _isTicking;
+    /**
+     * Protege la inicialización de una sola vez de la posición del búfer de desplazamiento infinito.
+     * Se establece en `true` una vez que el contenedor de desplazamiento se ha reposicionado
+     * silenciosamente al centro del búfer virtual después del primer renderizado.
+     */
+    private _infiniteInitialized;
+    /** ID del temporizador devuelto por `setInterval()` para la función de reproducción automática. */
+    private _autoplayTimer;
+    /** Array de quickSetters de GSAP para el CSS `transform: translateX()` de cada tarjeta. */
     private _cardSetX;
+    /** Array de quickSetters de GSAP para el `width` en línea de cada tarjeta. */
     private _cardSetWidth;
+    /** Array de quickSetters de GSAP para el parallax `translateX` del `<img>` de cada tarjeta. */
     private _imgSetX;
+    /** Array de quickSetters de GSAP para la `opacity` del elemento `.card-title` de cada tarjeta. */
     private _titleSetOpacity;
     static styles: import("lit").CSSResult[];
+    /**
+     * Hook del ciclo de vida (Lit).
+     * Inicializa el `ResizeObserver` para reaccionar a cambios en el tamaño del contenedor,
+     * lo que es crucial para recalcular el `computedLayout` (cuántas cards caben en el viewport).
+     * También añade listeners globales pasivos para eventos de redimensionamiento de ventana.
+     */
     connectedCallback(): void;
+    /**
+     * Hook del ciclo de vida (Lit).
+     * Limpia y desconecta el `ResizeObserver`, el `IntersectionObserver` y elimina
+     * los event listeners globales para evitar fugas de memoria (memory leaks).
+     */
     disconnectedCallback(): void;
+    /**
+     * Hook del ciclo de vida (Lit) ejecutado tras el primer render.
+     * Inspecciona el Shadow DOM para ubicar el slot por defecto y procesar
+     * las cards iniciales (`_handleSlotChange` invocado manualmente).
+     */
     firstUpdated(): void;
+    /**
+     * Hook del ciclo de vida (Lit). Se invoca tras cada actualización reactiva.
+     *
+     * Lógica principal:
+     * - Si cambian propiedades estructurales (`autoplay`, `infinite`, `gap`), reconstruye el
+     *   layout y detiene/inicia el timer de autoplay.
+     * - Delega en `_checkInfiniteWrap()` para reposicionar el scroll si estamos cerca
+     *   de los bordes del carrusel infinito.
+     */
     updated(changedProperties: Map<string, any>): void;
+    /**
+     * Motor de cálculo del Layout.
+     *
+     * Basado en las proporciones de Material 3 para carruseles:
+     * Calcula el ancho disponible (`W_c`) y determina el número de ítems grandes (`L`),
+     * medianos (`M`) y pequeños (`S`) que caben en pantalla, usando la fórmula de la
+     * especificación (multi-browse, hero o uncontained).
+     *
+     * Retorna `{ L, M, S, N }` donde `N` es el divisor base para calcular tamaños proporcionales.
+     */
     get computedLayout(): {
-        L: number;
-        M: number;
-        S: number;
-        N: number;
+        largeItemWidth: number;
+        mediumItemWidth: number;
+        smallItemWidth: number;
+        largeItemCount: number;
     };
+    /**
+     * Calcula el ancho total (incluyendo el gap) de un ítem de tamaño 'L' (Large).
+     * Este valor se utiliza como unidad de medida (step) para el Scroll Snapping
+     * y el cálculo de desplazamiento de páginas (sets).
+     */
     get itemSize(): number;
+    /**
+     * Algoritmo Central del Carrusel M3.
+     *
+     * Calcula el ancho visual, la posición horizontal y la opacidad para una sola tarjeta del carrusel
+     * basándose en su posición normalizada en relación con la ventana gráfica actualmente visible.
+     *
+     * Este es el corazón del efecto "Masked Carousel" de M3: a medida que una tarjeta transita de
+     * fuera de pantalla a en pantalla (posición -1 → 0 → N), su ancho se interpola de
+     * `smallItemWidth` → `largeItemWidth`, y su opacidad aumenta.
+     *
+     * Semántica de posición:
+     *   - `normalizedPosition < -1` → tarjeta está fuera de pantalla a la izquierda (oculta)
+     *   - `normalizedPosition = 0`  → tarjeta está en la ranura grande más a la izquierda (enfoque principal)
+     *   - `normalizedPosition = N-1` → tarjeta está en la ranura grande más a la derecha
+     *   - `normalizedPosition > N`  → tarjeta está fuera de pantalla a la derecha (oculta)
+     *
+     * @param normalizedPosition - El índice de posición fraccional de la tarjeta en relación con el progreso
+     *   de desplazamiento actual. Un valor de `0` significa que la tarjeta está perfectamente alineada con la ranura
+     *   grande inicial; los valores fraccionales representan transiciones parciales.
+     * @returns Objeto con `{ width, x, opacity }` para aplicar directamente al elemento de la tarjeta.
+     */
     private _getCardLayout;
     /**
-     * Rebuild quickSetter caches after cards change.
-     * quickSetter avoids gsap.set() overhead for properties updated every frame.
+     * Reconstruye las cachés de quickSetter después de que cambian las tarjetas.
+     * quickSetter evita la sobrecarga de gsap.set() para las propiedades actualizadas en cada cuadro.
      */
     private _buildQuickSetters;
     /**
-     * RAF-gated version of updateLayout for scroll events.
-     * Prevents multiple layout recalculations per frame.
+     * Callback del Ticker de GSAP — el bucle de animación principal para el carrusel.
+     *
+     * Esta función está registrada con `gsap.ticker.add()` y se ejecuta en cada
+     * cuadro de animación (sincronizado con `requestAnimationFrame`). Implementa
+     * **interpolación exponencial (smoothstep)** para interpolar `_tickerCurrent` hacia
+     * `_tickerTarget`, creando una desaceleración de suavizado físicamente plausible.
+     *
+     * La fórmula de interpolación: `current += (target - current) × easeStrength × deltaTimeRatio`
+     *
+     * - `easeStrength = 0.08` en móvil: acoplamiento más estrecho para evitar que el carrusel
+     *   se sienta "lento" o desincronizado con un dedo.
+     * - `easeStrength = 0.15` en escritorio: ligeramente más suelto para una sensación más cinematográfica.
+     * - `deltaTimeRatio` normaliza la velocidad de animación a través de diferentes velocidades de cuadro
+     *   (60fps vs 120fps), manteniendo la atenuación percibida constante.
+     *
+     * Una vez que la diferencia entre el objetivo y el actual cae por debajo de 0.0005 (medio
+     * sub-píxel), la animación se considera completa y el ticker se elimina
+     * para conservar los recursos de CPU/GPU entre interacciones.
      */
     private _tick;
+    /**
+     * Lee la posición real del scroll nativo y arranca el ticker de animación si no está corriendo.
+     * Esta separación es crucial para el rendimiento: leemos el DOM aquí (scrollLeft) pero
+     * escribimos los estilos en `_tick` -> `_applyLayout`.
+     */
     private _scheduleLayout;
+    /**
+     * Función principal de sincronización de estado.
+     * Refresca la lógica del scroll infinito y fuerza una recolección de los setters de GSAP
+     * si la cantidad de tarjetas cambió. Puede saltarse el ticker y ser instantánea (ej. al redimensionar la ventana).
+     */
     updateLayout: (instant?: boolean) => void;
+    /**
+     * Bucle de renderizado principal — aplica el diseño calculado a cada tarjeta en el DOM.
+     *
+     * Llamado en cada cuadro del ticker de GSAP a través de `_tick()`. Itera sobre todos los elementos físicos
+     * de las tarjetas y aplica ancho, posición, paralaje y opacidad del título
+     * usando quickSetters de GSAP pre-almacenados en caché para un rendimiento máximo de velocidad de fotogramas.
+     *
+     * **Bucle de desplazamiento infinito:**
+     * Cuando `infinite=true`, la posición normalizada se calcula usando aritmética
+     * modular para que las tarjetas se repitan sin problemas alrededor del centro virtual del búfer.
+     * Una corrección de envoltura asegura que cada tarjeta permanezca dentro de una distancia de medio ancho de búfer
+     * de la posición de desplazamiento actual.
+     *
+     * **Optimización fuera de pantalla:**
+     * Las tarjetas que están a más de 15 posiciones fuera de la pantalla se mueven a `x = -9999` y sus
+     * títulos se ocultan. Esto evita que el navegador gaste el presupuesto de composición
+     * en elementos invisibles.
+     *
+     * @param scrollProgress - La posición de desplazamiento interpolada actual en unidades de `itemSize`.
+     *   Un valor de `1.0` significa que el contenedor de desplazamiento ha avanzado exactamente el ancho de un elemento + espacio.
+     */
     private _applyLayout;
+    /**
+     * Calcula el multiplicador necesario para rellenar visualmente el carrusel infinito.
+     * Si la lista original de ítems es corta (ej: 3 ítems) pero el viewport puede
+     * mostrar 5, necesitamos multiplicar la lista original para cubrir el ancho de
+     * la pantalla e interactuar de forma ininterrumpida (Infinity Wrap).
+     */
+    private get _visualCardsMultiplier();
+    /**
+     * Calcula cuántos "sets" completos de las cards originales se deben clonar
+     * hacia los lados para habilitar el Infinite Scroll.
+     * Usualmente es de 3 a 5 "sets" multiplicados para crear un buffer circular
+     * invisible para el usuario final.
+     */
+    private get _snapSetsCount();
+    /**
+     * Determina el conteo total físico de cards (`li`) que serán montados en el DOM.
+     * Es el producto de `effectiveItems.length` multiplicado por `_snapSetsCount`.
+     * Para carruseles finitos (no infinite), esto simplemente retorna la cantidad original.
+     */
+    private get _snapItemsCount();
+    /**
+     * Lógica de Bucle Infinito (Infinite Wrap).
+     *
+     * Analiza el valor actual del `scrollLeft` del contenedor. Si el usuario se
+     * acerca demasiado al límite del buffer (físico izquierdo o derecho) de los ítems
+     * clonados, este método reposiciona instantáneamente (saltándose animaciones/scroll-behavior)
+     * el scrollLeft hacia el bloque central equivalente.
+     * El usuario nunca nota el salto visual porque los ítems en esas coordenadas lucen idénticos.
+     */
+    private _checkInfiniteWrap;
+    /**
+     * Inicia el temporizador de reproducción automática (Autoplay).
+     * Evalúa si el usuario no está interactuando activamente (`_isDown`)
+     * antes de forzar el scroll hacia la siguiente vista.
+     */
+    private _startAutoplay;
+    /**
+     * Detiene y limpia el temporizador de reproducción automática (Autoplay).
+     * Invocado durante interacciones del usuario (hover, drag) o al desmontar.
+     */
+    private _stopAutoplay;
+    /**
+     * Manejador de evento: `mouseenter`.
+     * Expuesto por si se requiere pausar el autoplay al hacer hover (actualmente en desuso).
+     */
+    private _handleMouseEnter;
+    /**
+     * Manejador de evento: `mouseleave`.
+     * Finaliza forzosamente cualquier secuencia de drag o interacción táctil en progreso
+     * si el puntero abandona el área de bounding box del carrusel.
+     */
+    private _handleMouseLeave;
+    /**
+     * Inicia la secuencia de arrastre (Pointer/Mouse Down).
+     * - Elimina las animaciones GSAP en vuelo para evitar conflictos elásticos.
+     * - Captura la posición de inicio X y resetea el acumulador de fricción y velocidad.
+     * - Realiza una comprobación de Infinite Wrap preliminar por si el usuario
+     *   comienza a arrastrar desde el límite del buffer.
+     */
     private _handleMouseDown;
+    /**
+     * Maneja el evento de movimiento del puntero durante un arrastre (Drag).
+     *
+     * @logic
+     * 1. Calcula el delta (`walk`) respecto a la posición original X.
+     * 2. Si excede el threshold de arrastre (3px), comienza a inyectar el scroll.
+     * 3. En carruseles finitos (no infinite), si el usuario sobrepasa el inicio o el final,
+     *    aplica una fricción exponencial al `walk` para simular la "resistencia elástica" (Overscroll).
+     * 4. Captura la velocidad (`_velocity`) calculando el delta dividido por el lapso de tiempo.
+     */
     private _handleMouseMove;
+    /**
+     * Finaliza la secuencia de arrastre (Pointer/Mouse Up).
+     *
+     * @logic
+     * Restaura el "Scroll Snap" que fue desactivado durante el drag (para permitir un
+     * arrastre libre píxel por píxel). Adicionalmente, si el arrastre acumuló suficiente
+     * velocidad (Inercia), inyecta esa inercia desplazando imperativamente el contenedor.
+     */
     private _handleMouseUp;
+    /**
+     * Inicia la secuencia de arrastre táctil (Touch Start).
+     * Funciona análogamente a `_handleMouseDown`: detiene animaciones GSAP, evalúa el Infinite Wrap
+     * y captura las coordenadas táctiles iniciales (`e.touches[0]`).
+     */
     private _handleTouchStart;
+    /**
+     * Maneja el evento de movimiento táctil (Touch Move).
+     * Actualiza el `scrollLeft` del contenedor imperativamente según el delta de arrastre.
+     * Calcula la velocidad del dedo para la simulación de inercia posterior.
+     */
     private _handleTouchMove;
+    /**
+     * Finaliza la secuencia de arrastre táctil (Touch End).
+     * Delega en `_handleMouseUp()` para aplicar inercia y restaurar el Snap.
+     */
     private _handleTouchEnd;
+    /**
+     * Manejador del evento Scroll/Wheel.
+     *
+     * @logic
+     * 1. Filtra para procesar únicamente el scroll vertical (`deltaY > deltaX`), típico de ruedas de ratón.
+     * 2. Si el usuario está en los bordes extremos del carrusel, permite que el evento de scroll
+     *    haga bubble hacia arriba para hacer scroll a la página completa, logrando una interacción fluida.
+     * 3. Si no, previene el scroll de la página (`e.preventDefault`) y lo convierte en scroll horizontal
+     *    para el carrusel.
+     * 4. Desactiva temporalmente el "CSS Scroll Snap" para que el movimiento sea suave, restaurándolo
+     *    tras 150ms de inactividad (`_wheelTimeout`).
+     */
     private _handleWheel;
+    /**
+     * Maneja los eventos de clic en las tarjetas individuales del carrusel.
+     *
+     * Distingue entre toques/clics genuinos y eventos accidentales de levantar el puntero
+     * que ocurrieron después de un gesto de arrastre. Si la distancia total arrastrada excede
+     * los 8px (el umbral mínimo de desplazamiento intencional de M3), el clic se suprime
+     * para evitar una navegación involuntaria o el disparo de acciones.
+     *
+     * Despacha `'item-click'` con `{ item, index }` para que los consumidores puedan
+     * responder a la selección de la tarjeta (ej. navegar a una página de detalles).
+     *
+     * @param e     - El evento de clic del elemento de la tarjeta.
+     * @param item  - Los datos `CarouselItem` asociados con la tarjeta clicada.
+     * @param cardDomIndex - El índice de la tarjeta en el DOM renderizado (puede diferir
+     *   del índice lógico en modo infinito debido a la clonación de elementos).
+     */
     private _handleCardClick;
+    /**
+     * Acción Imperativa: Scroll hacia el elemento anterior.
+     * Desplaza el contenedor una distancia equivalente al tamaño exacto de un ítem `L` (Large) + gap.
+     * Restaura el comportamiento `smooth` de CSS nativo.
+     */
     private _scrollPrevious;
+    /**
+     * Acción Imperativa: Scroll hacia el elemento siguiente.
+     * Desplaza el contenedor una distancia equivalente al tamaño exacto de un ítem `L` (Large) + gap.
+     */
     private _scrollNext;
+    /**
+     * Manejador del botón o enlace "Mostrar Todo" (Show All).
+     * Intercepta clics en enlaces nulos (`#`) y despacha el evento CustomEvent `show-all-click`.
+     */
     private _handleShowAllClick;
+    /**
+     * Hook invocado por Lit cuando el contenido del slot `"show-all"` muta en el Light DOM.
+     * Detecta si hay contenido proyectado para ocultar/mostrar la interfaz correspondiente,
+     * proveyendo un fallback manual para entornos DOM limitados (como JSDOM en test unitarios).
+     */
     private _handleShowAllSlotChange;
+    /**
+     * Hook invocado por Lit cuando los hijos directos proyectados en el `<slot>` por defecto cambian.
+     *
+     * @logic
+     * Parsea el Light DOM proporcionado por el usuario (ej: lista de `<img>` o `<a><img></a>`).
+     * Extrae los atributos `src`, `title`, y `href` de esos nodos nativos y los convierte en
+     * un array estructurado interno de objetos `CarouselItem`, que el componente usará
+     * subsecuentemente para renderizar su propio DOM Shadow infinito.
+     */
     private _handleSlotChange;
+    /**
+     * Ensambla la estructura del Shadow DOM del carrusel para cada ciclo de renderizado de Lit.
+     *
+     * **Extracción de `computedLayout`:**
+     * `largeItemWidth`, `mediumItemWidth` y `smallItemWidth` se desestructuran
+     * del getter `computedLayout` (que devuelve tamaños según la especificación M3 basados en
+     * el ancho del contenedor a través de `_containerWidth`). Se inyectan como propiedades personalizadas
+     * CSS en la pista para que el CSS de tamaño de ranura pueda referenciarlos.
+     *
+     * **Puerta `showHeader`:**
+     * El elemento `.header` solo se renderiza cuando hay algo que mostrar:
+     * un `headerText`, un atributo `showAll`, o un elemento `[slot="show-all"]`.
+     * Esto evita un espaciador de encabezado vacío cuando el carrusel no tiene fila de título.
+     *
+     * **Cálculo de `rightPadding`:**
+     * Asegura que la última tarjeta pueda desplazarse a ras de la posición focal del elemento grande:
+     * - Diseño `hero`: sin relleno adicional (el elemento derecho que asoma proporciona espacio natural).
+     * - Diseños de ancho completo / lista: también relleno mínimo.
+     * - Todos los demás diseños: `128px` (≈ ancho de la tarjeta pequeña) para que la última tarjeta pueda
+     *   alcanzar la ranura de enfoque principal sin que el usuario se desplace demasiado.
+     *
+     * **Ciclo de vida del ticker de GSAP:**
+     * El ticker de GSAP (`gsap.ticker.add(_tick)`) se inicia en `firstUpdated()`
+     * y se detiene en `disconnectedCallback()`. Este método de renderizado NO
+     * interactúa con el ticker; el ticker impulsa las actualizaciones de posición por cuadro
+     * independientemente del ciclo de actualización reactiva de Lit.
+     */
     render(): import("lit").TemplateResult<1>;
 }
 declare global {

package/dist/components/moni-carousel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"moni-carousel.d.ts","sourceRoot":"","sources":["../../src/components/moni-carousel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,WAAW,EAAgB,MAAM,kBAAkB,CAAC;AAG7D;;GAEG;AACH,MAAM,WAAW,YAAY;IAC5B,0CAA0C;IAC1C,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,GAAG,EAAE,MAAM,CAAC;IACZ,+EAA+E;IAC/E,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AACH,qBACa,YAAa,SAAQ,WAAW;IACjB,KAAK,EAAE,YAAY,EAAE,CAAM;IACzB,MAAM,EAAE,cAAc,GAAG,MAAM,GAAG,aAAa,CAAkB;IAClD,IAAI,UAAQ;IACF,UAAU,SAAO;IAChB,WAAW,SAAM;IAClB,UAAU,SAAM;IAC1C,GAAG,SAAK;IACR,OAAO,SAAM;IACe,YAAY,SAAM;IACtB,OAAO,UAAS;IAC1B,WAAW,SAAc;IAC3B,UAAU,SAAM;IACJ,OAAO,UAAS;IAE3D,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,aAAa,CAAsB;IAC3C,OAAO,CAAC,kBAAkB,CAAS;IAE5C,IAAI,cAAc,IAAI,YAAY,EAAE,CAEnC;IAE2B,OAAO,CAAC,gBAAgB,CAAkB;IACnD,OAAO,CAAC,MAAM,CAA8B;IAE/D,OAAO,CAAC,eAAe,CAA+B;IACtD,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,gBAAgB,CAAK;IAC7B,OAAO,CAAC,MAAM,CAAuB;IACrC,OAAO,CAAC,SAAS,CAAS;IAG1B,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,cAAc,CAAK;IAC3B,OAAO,CAAC,UAAU,CAAS;IAG3B,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,QAAQ,CAAmC;IACnD,OAAO,CAAC,gBAAgB,CAAmC;IAE3D,OAAgB,MAAM,4BAiOpB;IAEO,iBAAiB;IAwBjB,oBAAoB;IAoBpB,YAAY;IAaZ,OAAO,CAAC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC;IAwBpD,IAAI,cAAc;;;;;MAwEjB;IAED,IAAI,QAAQ,WAEX;IAED,OAAO,CAAC,cAAc;IA+EtB;;;OAGG;IACH,OAAO,CAAC,kBAAkB;IAwB1B;;;OAGG;IACH,OAAO,CAAC,KAAK,CAaX;IAEF,OAAO,CAAC,eAAe,CAOrB;IAEF,YAAY,GAAI,iBAAe,UAmB7B;IAEF,OAAO,CAAC,YAAY;IAqBpB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,cAAc;IAwCtB,OAAO,CAAC,iBAAiB;IAezB,OAAO,CAAC,gBAAgB;IAkBxB,OAAO,CAAC,eAAe;IAIvB,OAAO,CAAC,YAAY;IAoCpB,OAAO,CAAC,gBAAgB;IAgBxB,OAAO,CAAC,eAAe;IAMvB,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,mBAAmB;IAa3B,OAAO,CAAC,wBAAwB;IAYhC,OAAO,CAAC,iBAAiB;IA4ChB,MAAM;CAqIf;AAED,OAAO,CAAC,MAAM,CAAC;IACd,UAAU,qBAAqB;QAC9B,eAAe,EAAE,YAAY,CAAC;KAC9B;CACD"}
+{"version":3,"file":"moni-carousel.d.ts","sourceRoot":"","sources":["../../src/components/moni-carousel.ts"],"names":[],"mappings":"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"}