@codeforamerica/marcomms-design-system 1.19.0 → 1.19.1

package/src/components/carousel.js

@@ -0,0 +1,662 @@
+import { LitElement, html, css } from "lit";
+import { commonStyles } from "../shared/common";
+import "./icon";
+
+/**
+ * Carousel Component - Pagination-based content carousel with fade transitions
+ * 
+ * Supports HTML attributes (kebab-case):
+ * - items-per-view: Number of items to show per page (default: 3 on desktop, 1 on mobile)
+ * - auto-play: Enable/disable auto-play (default: true)
+ * - auto-play-duration: Duration in milliseconds for auto-play (default: 10000)
+ * 
+ * Example usage:
+ * <cfa-carousel items-per-view="3" auto-play="true" auto-play-duration="5000">
+ *   <cfa-slide>...</cfa-slide>
+ *   <cfa-slide>...</cfa-slide>
+ * </cfa-carousel>
+ * 
+ * CSS Custom Properties (for styling):
+ * - --carousel-fade-duration: Fade transition duration (default: 300ms)
+ * - --carousel-dot-color: Pagination dot color (default: var(--black-20))
+ * - --carousel-dot-active-color: Active dot progress bar color (default: var(--purple-60))
+ */
+class Carousel extends LitElement {
+  // Configuration constants
+  static SWIPE_THRESHOLD = 50;
+  static SHADOW_SPACE = 32;
+  static PROGRESS_UPDATE_INTERVAL = 100;
+  static AUTOPLAY_DURATION = 10000;
+  static DESKTOP_BREAKPOINT = 768;
+  static ITEMS_PER_VIEW_DESKTOP = 3;
+  static ITEMS_PER_VIEW_MOBILE = 1;
+
+  static properties = {
+    currentPage: { type: Number, state: true },
+    totalSlides: { type: Number, state: true },
+    progressPercentage: { type: Number, state: true },
+    isPaused: { type: Boolean, state: true },
+    prefersReducedMotion: { type: Boolean, state: true },
+    itemsPerView: { type: Number },
+    autoPlay: { type: Boolean },
+    autoPlayDuration: { type: Number },
+  };
+
+  static styles = [
+    commonStyles,
+    css`
+      :host {
+        --carousel-fade-duration: 300ms;
+        --carousel-control-size: var(--spacing-layout-2);
+        --carousel-dot-size: var(--spacing-component-3);
+        --carousel-dot-gap: var(--spacing-component-3);
+        --carousel-dot-color: var(--black-20);
+        --carousel-dot-active-color: var(--purple-60);
+        --carousel-gap: var(--spacing-layout-1);
+      }
+
+      .carousel-container {
+        display: flex;
+        flex-direction: column;
+        gap: var(--spacing-component-3);
+      }
+
+      .carousel-slides {
+        width: 100%;
+        overflow: hidden;
+        transition: height 400ms ease-in-out;
+        height: auto;
+      }
+
+      .carousel-track {
+        display: flex;
+        gap: var(--carousel-gap);
+      }
+
+      ::slotted(*) {
+        flex: 0 0 calc((100% - (var(--items-per-view, 3) - 1) * var(--carousel-gap)) / var(--items-per-view, 3));
+        display: none;
+        opacity: 0;
+        transition: opacity var(--carousel-fade-duration) ease-in-out;
+      }
+
+      ::slotted([data-slide-active]) {
+        display: block;
+        opacity: 1;
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        .carousel-slides {
+          transition: none;
+        }
+        
+        ::slotted(*) {
+          transition: none;
+        }
+      }
+
+      .carousel-controls {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        gap: var(--spacing-component-3);
+      }
+
+      .carousel-button {
+        background-color: transparent;
+        border: 0;
+        border-radius: 50%;
+        color: var(--text-color);
+        cursor: pointer;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        font-size: 1.5rem;
+        height: var(--carousel-control-size);
+        width: var(--carousel-control-size);
+        transition: all 0.2s ease-in-out;
+        flex-shrink: 0;
+      }
+
+      .carousel-button:hover {
+        background-color: var(--purple-20);
+        border-color: var(--purple-60);
+        color: var(--purple-80);
+      }
+
+      .carousel-button:focus-visible {
+        outline: var(--focus-outline);
+        outline-offset: 2px;
+      }
+
+      .carousel-button cfa-icon {
+        --size: var(--font-size-base);
+        color: var(--purple-80);
+      }
+
+      .carousel-pagination {
+        display: flex;
+        align-items: center;
+        gap: var(--carousel-dot-gap);
+        flex-wrap: wrap;
+        justify-content: center;
+      }
+
+      .carousel-dot {
+        background-color: var(--carousel-dot-color);
+        border: none;
+        border-radius: 50%;
+        cursor: pointer;
+        height: var(--carousel-dot-size);
+        min-width: var(--carousel-dot-size);
+        padding: 0;
+        position: relative;
+        transition: all 0.3s ease-in-out;
+      }
+
+      .carousel-dot:hover {
+        background-color: var(--gray-60);
+      }
+
+      .carousel-dot:focus-visible {
+        outline: var(--focus-outline);
+        outline-offset: 3px;
+      }
+
+      .carousel-dot[aria-current="true"] {
+        background-color: var(--carousel-dot-color);
+        border-radius: var(--carousel-dot-size);
+        min-width: calc(var(--carousel-dot-size) * 4);
+        overflow: hidden;
+      }
+
+      .carousel-dot-progress {
+        background-color: var(--carousel-dot-active-color);
+        height: 100%;
+        width: 0%;
+        transition: width 100ms linear;
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        .carousel-dot-progress {
+          transition: none;
+        }
+      }
+
+      @media (max-width: 768px) {
+        /* Note: 768px matches Carousel.DESKTOP_BREAKPOINT - keep in sync */
+        .carousel-button {
+          font-size: 1.25rem;
+          height: calc(var(--carousel-control-size) * 0.85);
+          width: calc(var(--carousel-control-size) * 0.85);
+        }
+
+        .carousel-dot {
+          height: calc(var(--carousel-dot-size) * 0.8);
+          min-width: calc(var(--carousel-dot-size) * 0.8);
+        }
+      }
+    `,
+  ];
+
+  constructor() {
+    super();
+    this.currentPage = 0;
+    this.totalSlides = 0;
+    this.progressPercentage = 0;
+    this.isPaused = true;
+    this.prefersReducedMotion = window.matchMedia(
+      "(prefers-reduced-motion: reduce)"
+    ).matches;
+    this.itemsPerView = Carousel.ITEMS_PER_VIEW_DESKTOP;
+    this.autoPlay = true;
+    // Clamp autoPlayDuration to positive value
+    this.autoPlayDuration = Math.max(100, Carousel.AUTOPLAY_DURATION);
+    this.autoPlayTimer = null;
+    this.autoPlayTimeout = null;
+    this.touchStartX = null;
+    this.touchEndX = null;
+    this._initialized = false;
+    this._resizeTimerId = null;
+    this._mouseEnterListener = null;
+    this._mouseLeaveListener = null;
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+
+    // Parse items-per-view attribute before setting CSS property
+    const attrValue = this.getAttribute('items-per-view');
+    if (attrValue !== null) {
+      const parsedValue = parseInt(attrValue, 10);
+      if (!isNaN(parsedValue)) {
+        this.itemsPerView = parsedValue;
+      }
+    }
+
+    this.style.setProperty("--items-per-view", this.itemsPerView);
+
+    this.addEventListener("keydown", (e) => this._handleKeydown(e));
+    this.addEventListener("touchstart", (e) => this._handleTouchStart(e), false);
+    this.addEventListener("touchend", (e) => this._handleTouchEnd(e), false);
+    
+    // Store debounced resize listener for proper cleanup
+    this._resizeListener = () => {
+      if (this._resizeTimerId) {
+        clearTimeout(this._resizeTimerId);
+      }
+      this._resizeTimerId = setTimeout(() => {
+        this.updateItemsPerView();
+        this.updateCarouselHeight();
+      }, 150);
+    };
+    window.addEventListener("resize", this._resizeListener);
+  }
+
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.stopAutoPlay();
+    if (this._resizeListener) {
+      window.removeEventListener("resize", this._resizeListener);
+    }
+    if (this._resizeTimerId) {
+      clearTimeout(this._resizeTimerId);
+    }
+    // Clean up mouse listeners if they were attached
+    const slidesContainer = this.shadowRoot?.querySelector(".carousel-slides");
+    if (slidesContainer && this._mouseEnterListener && this._mouseLeaveListener) {
+      slidesContainer.removeEventListener("mouseenter", this._mouseEnterListener);
+      slidesContainer.removeEventListener("mouseleave", this._mouseLeaveListener);
+    }
+  }
+
+  updated(changedProperties) {
+    if (changedProperties.has("itemsPerView")) {
+      this.style.setProperty("--items-per-view", this.itemsPerView);
+    }
+    if (changedProperties.has("currentPage")) {
+      this.updateItemVisibility();
+    }
+  }
+
+  firstUpdated() {
+    const slot = this.shadowRoot.querySelector("slot");
+    const slidesContainer = this.shadowRoot.querySelector(".carousel-slides");
+    
+    // Set up the slotchange listener which will actually initialize when elements are assigned
+    if (slot && !this._slotChangeSetup) {
+      this._slotChangeSetup = true;
+      slot.addEventListener('slotchange', () => {
+        // Debounce initialization - wait for DOM to stabilize
+        if (this._slotChangeTimeout) {
+          clearTimeout(this._slotChangeTimeout);
+        }
+        this._slotChangeTimeout = setTimeout(() => {
+          if (!this._initialized) {
+            this._initializeCarousel();
+          }
+        }, 50);
+      });
+    }
+
+    // Only pause when hovering over the carousel items, not the controls
+    // Store listeners for cleanup on disconnect
+    if (slidesContainer && !this._mouseEnterListener) {
+      this._mouseEnterListener = () => {
+        this.stopAutoPlay();
+      };
+      this._mouseLeaveListener = () => {
+        if (!this.isPaused) {
+          this._scheduleNextPage();
+        }
+      };
+      slidesContainer.addEventListener("mouseenter", this._mouseEnterListener);
+      slidesContainer.addEventListener("mouseleave", this._mouseLeaveListener);
+    }
+  }
+
+  _initializeCarousel() {
+    if (this._initialized) {
+      return;
+    }
+
+    const slot = this.shadowRoot.querySelector("slot");
+    if (!slot) {
+      return;
+    }
+
+    const items = slot.assignedElements();
+
+    if (items.length === 0) {
+      return;
+    }
+
+    this._initialized = true;
+    this.totalSlides = items.length;
+    this.updateItemsPerView();
+    this.updateItemVisibility();
+    this.startAutoPlay();
+
+    // Recalculate height after images load with timeout guard
+    this._waitForImages(items, 5000).then(() => {
+      this.updateCarouselHeight();
+    });
+  }
+
+  _waitForImages(items, timeout = 3000) {
+    return Promise.race([
+      Promise.all(
+        Array.from(items).map(item =>
+          Promise.all(
+            Array.from(item.querySelectorAll('img')).map(img =>
+              img.complete
+                ? Promise.resolve()
+                : new Promise(resolve => {
+                    img.addEventListener('load', resolve, { once: true });
+                    img.addEventListener('error', resolve, { once: true });
+                  })
+            )
+          )
+        )
+      ),
+      new Promise((_, reject) =>
+        setTimeout(() => reject(new Error('Image load timeout')), timeout)
+      )
+    ]).catch(() => {
+      // If timeout or error, continue anyway
+      return Promise.resolve();
+    });
+  }
+
+  get totalPages() {
+    return Math.ceil(this.totalSlides / this.itemsPerView);
+  }
+
+  updateItemsPerView() {
+    // If itemsPerView was explicitly set via attribute, don't override it with responsive defaults
+    if (this.hasAttribute('items-per-view')) {
+      return;
+    }
+
+    const isDesktop = window.innerWidth >= Carousel.DESKTOP_BREAKPOINT;
+    const newItemsPerView = isDesktop
+      ? Carousel.ITEMS_PER_VIEW_DESKTOP
+      : Carousel.ITEMS_PER_VIEW_MOBILE;
+    
+    if (newItemsPerView !== this.itemsPerView) {
+      this.itemsPerView = newItemsPerView;
+      this.style.setProperty("--items-per-view", this.itemsPerView);
+      // Reset to first page if current page is out of bounds
+      if (this.currentPage >= this.totalPages) {
+        this.currentPage = 0;
+      }
+      this.requestUpdate();
+    }
+  }
+
+  updateItemVisibility() {
+    const slot = this.shadowRoot.querySelector("slot");
+    if (!slot) {
+      return;
+    }
+
+    const items = slot.assignedElements();
+    
+    if (items.length === 0) {
+      return;
+    }
+    
+    const startIdx = this.currentPage * this.itemsPerView;
+    const endIdx = startIdx + this.itemsPerView;
+    
+    items.forEach((item, idx) => {
+      if (idx >= startIdx && idx < endIdx) {
+        item.setAttribute("data-slide-active", "");
+      } else {
+        item.removeAttribute("data-slide-active");
+      }
+    });
+
+    // Update carousel height to match current page content
+    this.updateCarouselHeight();
+  }
+
+  updateCarouselHeight() {
+    const slot = this.shadowRoot.querySelector("slot");
+    const slidesContainer = this.shadowRoot.querySelector(".carousel-slides");
+    
+    if (!slot || !slidesContainer) {
+      return;
+    }
+
+    const items = slot.assignedElements();
+    if (items.length === 0) {
+      return;
+    }
+
+    const startIdx = this.currentPage * this.itemsPerView;
+    const endIdx = startIdx + this.itemsPerView;
+
+    // Use multiple animation frames and a small delay to ensure layout is complete
+    // after CSS changes have been applied to show/hide slides
+    requestAnimationFrame(() => {
+      requestAnimationFrame(() => {
+        // Small timeout to ensure layout has been computed
+        setTimeout(() => {
+          let maxHeight = 0;
+          
+          for (let i = startIdx; i < endIdx && i < items.length; i++) {
+            const item = items[i];
+            const height = item.offsetHeight;
+            maxHeight = Math.max(maxHeight, height);
+          }
+          
+          // Set height (minimum SHADOW_SPACE to accommodate buttons/controls)
+          const totalHeight = Math.max(maxHeight, Carousel.SHADOW_SPACE);
+          slidesContainer.style.height = totalHeight + "px";
+        }, 0);
+      });
+    });
+  }
+
+  startAutoPlay() {
+    if (!this.autoPlay || this.prefersReducedMotion || this.totalSlides === 0) {
+      this.isPaused = true;
+      return;
+    }
+    this.isPaused = false;
+    this.progressPercentage = 0;
+    this._scheduleNextPage();
+  }
+
+  play() {
+    if (!this.prefersReducedMotion) {
+      this.startAutoPlay();
+    }
+  }
+
+  pause() {
+    this.isPaused = true;
+    this.stopAutoPlay();
+  }
+
+  stopAutoPlay() {
+    if (this.autoPlayTimer) {
+      clearInterval(this.autoPlayTimer);
+      this.autoPlayTimer = null;
+    }
+    if (this.autoPlayTimeout) {
+      clearTimeout(this.autoPlayTimeout);
+      this.autoPlayTimeout = null;
+    }
+  }
+
+  _scheduleNextPage() {
+    this.stopAutoPlay();
+
+    // Progress bar animation - calculate increment dynamically
+    const totalUpdates = this.autoPlayDuration / Carousel.PROGRESS_UPDATE_INTERVAL;
+    const increment = 100 / totalUpdates;
+    
+    this.autoPlayTimer = setInterval(() => {
+      this.progressPercentage = Math.min(100, this.progressPercentage + increment);
+    }, Carousel.PROGRESS_UPDATE_INTERVAL);
+
+    // Advance to next page after configured duration
+    this.autoPlayTimeout = setTimeout(() => {
+      if (!this.isPaused) {
+        this.nextPage();
+        this.startAutoPlay();
+      }
+    }, this.autoPlayDuration);
+  }
+
+  nextPage() {
+    this.currentPage = (this.currentPage + 1) % this.totalPages;
+    this.progressPercentage = 0;
+    this.stopAutoPlay();
+    this.requestUpdate();
+    this.play();
+  }
+
+  previousPage() {
+    this.currentPage =
+      (this.currentPage - 1 + this.totalPages) % this.totalPages;
+    this.progressPercentage = 0;
+    this.stopAutoPlay();
+    this.requestUpdate();
+    this.play();
+  }
+
+  goToPage(pageIndex) {
+    if (pageIndex >= 0 && pageIndex < this.totalPages) {
+      // Only update if page is different
+      if (pageIndex !== this.currentPage) {
+        this.currentPage = pageIndex;
+        this.progressPercentage = 0;
+        this.stopAutoPlay();
+        this.requestUpdate();
+        this.play();
+      }
+    }
+  }
+
+  _handleKeydown(event) {
+    if (event.key === "ArrowRight") {
+      event.preventDefault();
+      this.nextPage();
+      this.pause();
+    } else if (event.key === "ArrowLeft") {
+      event.preventDefault();
+      this.previousPage();
+      this.pause();
+    }
+  }
+
+  _handleTouchStart(event) {
+    if (event.changedTouches && event.changedTouches.length > 0) {
+      this.touchStartX = event.changedTouches[0].screenX;
+    }
+  }
+
+  _handleTouchEnd(event) {
+    if (event.changedTouches && event.changedTouches.length > 0) {
+      this.touchEndX = event.changedTouches[0].screenX;
+      this._handleSwipe();
+    }
+  }
+
+  _handleSwipe() {
+    // Validate that touch coordinates were captured
+    if (this.touchStartX === null || this.touchEndX === null) {
+      return;
+    }
+    
+    const diff = this.touchStartX - this.touchEndX;
+
+    if (Math.abs(diff) > Carousel.SWIPE_THRESHOLD) {
+      if (diff > 0) {
+        // Swiped left - go to next page
+        this.nextPage();
+        this.pause();
+      } else {
+        // Swiped right - go to previous page
+        this.previousPage();
+        this.pause();
+      }
+    }
+  }
+
+  render() {
+    return html`
+      <div
+        class="carousel-container"
+        role="region"
+        aria-label="Content carousel"
+      >
+        <div class="carousel-slides">
+          <div class="carousel-track">
+            <slot @slotchange=${() => {
+              // Only update if not already initialized in firstUpdated
+              if (!this._initialized) {
+                const slot = this.shadowRoot.querySelector("slot");
+                if (slot) {
+                  const items = slot.assignedElements();
+                  this.totalSlides = items.length;
+                  this.updateItemVisibility();
+                  this.requestUpdate();
+                }
+              }
+            }}></slot>
+          </div>
+        </div>
+
+        ${this.totalSlides > 0
+          ? html`
+              <div class="carousel-controls">
+                <button
+                  class="carousel-button"
+                  @click=${() => this.previousPage()}
+                  aria-label="Previous page"
+                >
+                  <cfa-icon>arrow_back</cfa-icon>
+                </button>
+
+                <div class="carousel-pagination">
+                  ${Array.from({ length: this.totalPages }).map(
+                    (_, idx) => html`
+                      <button
+                        class="carousel-dot"
+                        @click=${() => this.goToPage(idx)}
+                        aria-label="Go to page ${idx + 1} of ${this.totalPages}"
+                        aria-current=${idx === this.currentPage ? "true" : "false"}
+                      >
+                        ${idx === this.currentPage && !this.prefersReducedMotion
+                          ? html`<div
+                              class="carousel-dot-progress"
+                              style="width: ${this.progressPercentage}%"
+                            ></div>`
+                          : ""}
+                      </button>
+                    `
+                  )}
+                </div>
+
+                <button
+                  class="carousel-button"
+                  @click=${() => this.nextPage()}
+                  aria-label="Next page"
+                >
+                  <cfa-icon>arrow_forward</cfa-icon>
+                </button>
+              </div>
+            `
+          : ""}
+      </div>
+    `;
+  }
+}
+
+if (!customElements.get("cfa-carousel")) {
+  customElements.define("cfa-carousel", Carousel);
+}