@eui/ecl 19.3.0-snapshot-1749041696283 → 19.3.0-snapshot-1749064223062

package/fesm2022/eui-ecl-components-ecl-carousel.mjs

@@ -18,21 +18,48 @@ class EclSlideEvent extends EclBaseEvent {
     }
 }
 
+/**
+ * Represents a single item (slide) within the ECL Carousel.
+ * Each slide can optionally include an EclBannerComponent and supports click events.
+ */
 class EclCarouselItemComponent extends ECLBaseDirective {
     constructor(el) {
         super();
         this.el = el;
+        /**
+         * Sets the ARIA `role` attribute to indicate this is a tab panel.
+         */
         this.role = 'tabpanel';
+        /**
+         * Sets a more descriptive ARIA role, identifying this element as a slide.
+         */
         this.roleDescription = 'slide';
+        /**
+         * Indicates whether this slide is currently active/visible.
+         * Automatically coerced to a boolean value.
+         */
         this.isCurrent = false;
+        /**
+         * Emits an event when the slide is clicked.
+         */
         this.slideClick = new EventEmitter();
     }
+    /**
+     * Computes and binds the slide's CSS class.
+     */
     get cssClasses() {
         return [super.getCssClasses('ecl-carousel__slide')].join(' ').trim();
     }
+    /**
+     * Adds the `inert` attribute if the slide is not active.
+     * This disables interaction and focus on inactive slides.
+     */
     get isInert() {
         return !this.isCurrent || undefined;
     }
+    /**
+     * Handles click events on the slide and emits a slideClick event.
+     */
     onSlideClick() {
         this.slideClick.next(new EclSlideEvent(this));
     }
@@ -75,6 +102,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "19.2.12", ngImpo
                 args: ['click']
             }] } });
 
+/**
+ * Component responsible for rendering a carousel (slideshow) with autoplay, keyboard navigation,
+ * and support for RTL layouts. Extends the ECLBaseDirective for consistent styling and behavior.
+ */
 class EclCarouselComponent extends ECLBaseDirective {
     constructor(cdkBreakpointObserver, cd, renderer2, eclRtlService) {
         super();
@@ -82,13 +113,37 @@ class EclCarouselComponent extends ECLBaseDirective {
         this.cd = cd;
         this.renderer2 = renderer2;
         this.eclRtlService = eclRtlService;
+        /**
+         * Aria-label for screen readers to describe the carousel.
+         */
         this.ariaLabel = 'Carousel description here';
+        /**
+         * Aria-role description for screen readers, identifying this component as a carousel.
+         */
         this.ariaRoleDescription = 'carousel';
+        /**
+         * Interval in milliseconds between automatic slide transitions.
+         */
         this.playInterval = 5000;
+        /**
+         * Event emitted when a slide change occurs.
+         */
         this.slide = new EventEmitter();
+        /**
+         * Indicates whether autoplay is currently active.
+         */
         this.isPlaying = false;
+        /**
+         * Indicates whether autoplay was manually paused.
+         */
         this.isPausedForced = false;
+        /**
+         * Indicates whether the layout is currently in RTL mode.
+         */
         this.isRtl = false;
+        /**
+         * Duration of the slide transition animation (in seconds).
+         */
         this.transitionDuration = 0.4;
         this.isMobileBreakpoint = false;
         this.isSmallTabletBreakpoint = false;
@@ -97,6 +152,9 @@ class EclCarouselComponent extends ECLBaseDirective {
         this.playSubject = new Subject();
         this.stopSubject = new Subject();
         this.destroy$ = new Subject();
+        /**
+         * Debounce interval (ms) used internally for timing and transitions.
+         */
         this.TIMEOUT_INTERVAL = 400;
         afterNextRender(() => {
             this.observeElementSizeChanges();
@@ -104,18 +162,30 @@ class EclCarouselComponent extends ECLBaseDirective {
             this.observeBreakpointChanges();
         });
     }
+    /**
+     * Returns the computed CSS class list for the component.
+     */
     get cssClasses() {
         return [super.getCssClasses('ecl-carousel')].join(' ').trim();
     }
+    /**
+     * Angular lifecycle hook: initializes autoplay and RTL detection.
+     */
     ngOnInit() {
         this.initAutoplay();
         this.handleRtlChangeState();
     }
+    /**
+     * Angular lifecycle hook: called after content (slides) is initialized.
+     */
     ngAfterContentInit() {
         setTimeout(() => {
             this.initializeSlider();
         });
     }
+    /**
+     * Angular lifecycle hook: cleans up subscriptions and event listeners.
+     */
     ngOnDestroy() {
         this.destroy$.next(true);
         this.destroy$.unsubscribe();
@@ -123,14 +193,23 @@ class EclCarouselComponent extends ECLBaseDirective {
             this.unsubscribeListener();
         }
     }
+    /**
+     * Starts autoplay and focuses the pause button.
+     */
     onPlayClick() {
         this.startPlaying();
         this.focusOnButton(this.pauseButton);
     }
+    /**
+     * Stops autoplay and focuses the play button.
+     */
     onPauseClick() {
         this.stopPlaying();
         this.focusOnButton(this.playButton);
     }
+    /**
+     * Handles key press on the first carousel element to stop autoplay if TAB is pressed.
+     */
     onFirstCarouselElementPress(e) {
         if (e.key === KeyCode.TAB) {
             if (this.isPlaying) {
@@ -138,6 +217,9 @@ class EclCarouselComponent extends ECLBaseDirective {
             }
         }
     }
+    /**
+     * Handles keyboard interaction on the play button.
+     */
     onPlayKeyboardPress(e) {
         if (e.key === KeyCode.TAB && e.shiftKey) {
             return;
@@ -156,6 +238,9 @@ class EclCarouselComponent extends ECLBaseDirective {
             this.focusOnButton(this.navigationButtons.get(this.getCurrentSlideIndex()));
         }
     }
+    /**
+     * Handles keyboard navigation for the navigation buttons.
+     */
     onNavBtnKeyboardPress(e, index) {
         if (e.key === KeyCode.ARROW_RIGHT) {
             this.onNavigationButtonArrowRight(e);
@@ -165,47 +250,81 @@ class EclCarouselComponent extends ECLBaseDirective {
         }
         return;
     }
+    /**
+     * Checks whether a given button is currently visible (not hidden via style).
+     */
     isButtonVisible(button) {
         if (!button) {
             return false;
         }
         return button.nativeElement.style.display === '';
     }
+    /**
+     * Sets focus on the specified button.
+     */
     focusOnButton(button) {
         if (!button) {
             return;
         }
         button.nativeElement.focus();
     }
+    /**
+     * Handles user interaction with a slide control button.
+     */
     onSlideControlClick(slide) {
         this.stopPlaying();
         this.activateSlide(slide, true);
     }
+    /**
+     * Navigates to the next slide and stops autoplay.
+     */
     onNextSlideClick() {
         this.stopPlaying();
         this.goToNextSlide(true);
     }
+    /**
+     * Navigates to the previous slide and stops autoplay.
+     */
     onPreviousSlideClick() {
         this.stopPlaying();
         this.goToPreviousSlide(true);
     }
+    /**
+     * Pauses autoplay on mouse hover.
+     */
     onSlideHover() {
         this.pausePlaying();
     }
+    /**
+     * Resumes autoplay on mouse leave, if not manually paused.
+     */
     onSlideHoverout() {
         if (!this.isStopButtonPressed()) {
             this.resumePlaying();
         }
     }
+    /**
+     * Returns whether the stop button (pause) has been pressed by the user.
+     */
     isStopButtonPressed() {
         return this.isPausedForced;
     }
+    /**
+     * Returns whether the carousel has padding applied (e.g., on desktop breakpoint).
+     */
     isPadded() {
         return this.isDesktopBreakpoint;
     }
+    /**
+     * Checks whether there are enough slides to render controls.
+     */
     hasControls() {
         return this.getSlidesCount() > 1;
     }
+    /**
+     * Retrieves the current active slide index.
+     * Corrects index for internal structure with hidden buffer slides.
+     */
     getCurrentSlideIndex() {
         let currentIndex;
         this.getAllSlidesArray().forEach((item, idx) => {
@@ -221,20 +340,35 @@ class EclCarouselComponent extends ECLBaseDirective {
         }
         return currentIndex - 1;
     }
+    /**
+     * Calculates the total width of the slides container based on the number of slides.
+     */
     getCarouselSlidesWidth() {
         return this.carouselContainerElement?.nativeElement.offsetWidth * this.getAllSlidesCount();
     }
+    /**
+     * Computes the left offset to shift the slides container.
+     */
     getCarouselSlidesOffsetLeft() {
         return -1 * this.carouselContainerElement?.nativeElement.offsetWidth * this.getCurrentItemIndex();
     }
+    /**
+     * Computes the right offset to shift the slides container (same logic as left in RTL).
+     */
     getCarouselSlidesOffsetRight() {
         return -1 * this.carouselContainerElement?.nativeElement.offsetWidth * this.getCurrentItemIndex();
     }
+    /**
+     * Subscribes to RTL layout state changes to adapt carousel behavior.
+     */
     handleRtlChangeState() {
         this.eclRtlService.currentRtlState$.pipe(takeUntil(this.destroy$)).subscribe((rtlState) => {
             this.isRtl = rtlState;
         });
     }
+    /**
+     * Initializes autoplay logic using RxJS intervals and subject triggers.
+     */
     initAutoplay() {
         const start$ = this.playSubject.asObservable();
         const stop$ = this.stopSubject.asObservable();
@@ -244,6 +378,9 @@ class EclCarouselComponent extends ECLBaseDirective {
             this.goToNextSlide(true);
         });
     }
+    /**
+     * Returns the index of the currently active slide item.
+     */
     getCurrentItemIndex() {
         let result = 0;
         this.getAllSlidesArray().forEach((item, index) => {
@@ -253,6 +390,9 @@ class EclCarouselComponent extends ECLBaseDirective {
         });
         return result;
     }
+    /**
+     * Initializes slides, hidden buffer items, and sets default active slide.
+     */
     initializeSlider() {
         this.slides.forEach((item, idx) => {
             this.initSlide(item, idx);
@@ -264,6 +404,9 @@ class EclCarouselComponent extends ECLBaseDirective {
             }
         }
     }
+    /**
+     * Initializes hidden first and last slide clones used for infinite scroll illusion.
+     */
     initHiddenItems() {
         this.firstHiddenItem.el.nativeElement.innerHTML = this.getLastContentChild();
         this.firstHiddenItem.isCurrent = false;
@@ -272,6 +415,9 @@ class EclCarouselComponent extends ECLBaseDirective {
         this.slideWidth = this.slides.first.width;
         this.unsubscribeListener = this.renderer2.listen(this.slidesContainer.nativeElement, 'transitionend', () => this.checkIndex());
     }
+    /**
+     * Verifies current index and resets to actual slide if hidden clone is reached.
+     */
     checkIndex() {
         if (this.getCurrentItemIndex() === this.getAllSlidesCount() - 1) {
             const item = this.slides.first;
@@ -282,23 +428,41 @@ class EclCarouselComponent extends ECLBaseDirective {
             this.activateSlide(item, false);
         }
     }
+    /**
+     * Returns the inner HTML of the last real slide (used for buffer item).
+     */
     getLastContentChild() {
         return this.getSlidesCount() > 0 ? this.slides.get(this.getSlidesCount() - 1).el.nativeElement.innerHTML : '';
     }
+    /**
+     * Returns the inner HTML of the first real slide (used for buffer item).
+     */
     getFirstContentChild() {
         return this.getSlidesCount() > 0 ? this.slides.get(0).el.nativeElement.innerHTML : '';
     }
+    /**
+     * Sets up a slide with index, ARIA label, and calculated width.
+     */
     initSlide(item, idx) {
         item.index = idx;
         item.ariaLabel = `slide ${idx + 1} of ${this.getSlidesCount()}`;
         item.width = 100 / this.getAllSlidesCount();
     }
+    /**
+     * Activates the next slide, with option to loop.
+     */
     goToNextSlide(isLoop) {
         this.activateSlide(this.getNextSlide(isLoop), true);
     }
+    /**
+     * Activates the previous slide, with option to loop.
+     */
     goToPreviousSlide(isLoop) {
         this.activateSlide(this.getPreviousSlide(isLoop), true);
     }
+    /**
+     * Activates a specific slide and triggers slide change event if needed.
+     */
     activateSlide(slideItem, withTransition) {
         if (withTransition) {
             this.transitionDuration = 0.4;
@@ -317,35 +481,56 @@ class EclCarouselComponent extends ECLBaseDirective {
             this.slide.next(new EclSlideEvent(this.slides.get(this.getCurrentSlideIndex())));
         }
     }
+    /**
+     * Checks if the currently focused button is the last in the list.
+     */
     isLastButton(index) {
         const buttonsList = this.navigationButtons;
         return index + 1 >= buttonsList.length;
     }
+    /**
+     * Checks if the currently focused button is the first in the list.
+     */
     isFirstButton(index) {
         return index <= 0;
     }
+    /**
+     * Starts autoplay mode and updates state.
+     */
     startPlaying() {
         this.isPlaying = true;
         this.cd.detectChanges();
         this.isPausedForced = false;
         this.playSubject.next();
     }
+    /**
+     * Stops autoplay mode and updates state.
+     */
     stopPlaying() {
         this.isPlaying = false;
         this.cd.detectChanges();
         this.isPausedForced = true;
         this.stopSubject.next();
     }
+    /**
+     * Temporarily pauses autoplay (e.g. on mouse hover).
+     */
     pausePlaying() {
         this.isPlaying = false;
         this.cd.detectChanges();
         this.stopSubject.next();
     }
+    /**
+     * Resumes autoplay after being paused.
+     */
     resumePlaying() {
         this.isPlaying = true;
         this.cd.detectChanges();
         this.playSubject.next();
     }
+    /**
+     * Retrieves the next slide based on the current index and loop setting.
+     */
     getNextSlide(isLoop) {
         const slidesCount = this.getSlidesCount();
         const currentIndex = this.getCurrentSlideIndex();
@@ -361,9 +546,15 @@ class EclCarouselComponent extends ECLBaseDirective {
             return this.slides.get(currentIndex + 1);
         }
     }
+    /**
+     * Returns all slides, including the hidden buffer items.
+     */
     getAllSlidesArray() {
         return [...[this.firstHiddenItem], ...this.slides.toArray(), ...[this.lastHiddenItem]];
     }
+    /**
+     * Retrieves the previous slide based on the current index and loop setting.
+     */
     getPreviousSlide(isLoop) {
         const currentIndex = this.getCurrentSlideIndex();
         if (currentIndex <= 0) {
@@ -378,9 +569,15 @@ class EclCarouselComponent extends ECLBaseDirective {
             return this.slides.get(currentIndex - 1);
         }
     }
+    /**
+     * Returns the number of actual visible slides (excluding hidden buffer).
+     */
     getSlidesCount() {
         return this.slides.length;
     }
+    /**
+     * Returns total number of slides, including buffer (hidden) items.
+     */
     getAllSlidesCount() {
         if (this.hasControls()) {
             return this.slides.length + 2;
@@ -389,9 +586,15 @@ class EclCarouselComponent extends ECLBaseDirective {
             return this.slides.length;
         }
     }
+    /**
+     * Determines whether no slide is currently marked as active.
+     */
     isNoSlideSelected() {
         return !this.slides.some((item) => item.isCurrent);
     }
+    /**
+     * Handles right arrow key navigation for buttons.
+     */
     onNavigationButtonArrowRight(e) {
         setTimeout(() => {
             this.goToNextSlide(false);
@@ -400,6 +603,9 @@ class EclCarouselComponent extends ECLBaseDirective {
         }, this.TIMEOUT_INTERVAL);
         e.preventDefault();
     }
+    /**
+     * Handles left arrow key navigation for buttons.
+     */
     onNavigationButtonArrowLeft(e, index) {
         if (this.isFirstButton(index)) {
             if (this.playButton) {
@@ -418,6 +624,9 @@ class EclCarouselComponent extends ECLBaseDirective {
             e.preventDefault();
         }
     }
+    /**
+     * Observes screen breakpoint changes to adjust autoplay and layout behavior.
+     */
     observeBreakpointChanges() {
         this.cdkBreakpointObserver
             .observe([
@@ -442,6 +651,9 @@ class EclCarouselComponent extends ECLBaseDirective {
             }
         });
     }
+    /**
+     * Observes changes to the carousel's container element size using ResizeObserver.
+     */
     observeElementSizeChanges() {
         new ResizeObserver(() => {
             setTimeout(() => {
@@ -455,6 +667,9 @@ class EclCarouselComponent extends ECLBaseDirective {
             }, this.TIMEOUT_INTERVAL);
         }).observe(this.carouselContainerElement.nativeElement);
     }
+    /**
+     * Normalizes the height of all banners to match the tallest banner.
+     */
     checkBannerHeights() {
         const heightValues = this.slides.map((slide) => {
             const height = slide.banner?.el.nativeElement.offsetHeight;
@@ -482,6 +697,9 @@ class EclCarouselComponent extends ECLBaseDirective {
             this.resetHiddenItems();
         }
     }
+    /**
+     * Clears all explicit banner height and aspect ratio styling for smaller breakpoints.
+     */
     resetHeight() {
         this.getAllSlidesArray().forEach((slide) => {
             const banner = slide.banner;
@@ -499,6 +717,9 @@ class EclCarouselComponent extends ECLBaseDirective {
         });
         this.resetHiddenItems();
     }
+    /**
+     * Re-renders the content of hidden buffer items after style reset.
+     */
     resetHiddenItems() {
         if (this.hasControls()) {
             this.firstHiddenItem.el.nativeElement.innerHTML = this.getLastContentChild();