feat(carousel): implement circular layout and enhance navigation logic

src/app/shared/components/carousel/carousel.component.ts

@@ -21,6 +21,16 @@ export interface CarouselItemContext<T> {
 
 export type CarouselTrackBy<T> = (index: number, item: T) => unknown;
 
+interface CarouselPageItem<T> {
+  item: T;
+  index: number;
+}
+
+interface CarouselPage<T> {
+  slot: 'previous' | 'current' | 'next';
+  items: CarouselPageItem<T>[];
+}
+
 @Component({
   selector: 'app-carousel',
   imports: [NgTemplateOutlet],
@@ -48,8 +58,25 @@ export class CarouselComponent<T> implements AfterViewInit {
   protected readonly canScrollNext = signal(false);
   protected readonly hasOverflow = signal(false);
   protected readonly viewportWidth = signal<number | null>(null);
+  protected readonly itemsPerPage = signal(Number.MAX_SAFE_INTEGER);
+  protected readonly currentPage = signal(0);
+  protected readonly transitionDirection = signal<-1 | 0 | 1>(0);
   protected readonly hasMultipleItems = computed(() => this.items().length > 1);
   protected readonly resolvedGap = computed(() => Math.max(this.gap(), 0));
+  protected readonly pageCount = computed(() =>
+    Math.max(1, Math.ceil(this.items().length / this.itemsPerPage())),
+  );
+  protected readonly isCircularLayout = computed(() => this.circular() && this.pageCount() > 1);
+  protected readonly circularPages = computed<CarouselPage<T>[]>(() => {
+    const pageCount = this.pageCount();
+    const currentPage = this.normalizePage(this.currentPage(), pageCount);
+
+    return [
+      this.createPage('previous', currentPage - 1),
+      this.createPage('current', currentPage),
+      this.createPage('next', currentPage + 1),
+    ];
+  });
   protected readonly isPreviousDisabled = computed(
     () => !this.hasOverflow() || (!this.circular() && !this.canScrollPrevious()),
   );
@@ -73,7 +100,7 @@ export class CarouselComponent<T> implements AfterViewInit {
       typeof MutationObserver === 'undefined'
         ? null
         : new MutationObserver(() => this.refreshLayout());
-    mutationObserver?.observe(viewport, { childList: true });
+    mutationObserver?.observe(viewport, { childList: true, subtree: true });
 
     this.destroyRef.onDestroy(() => {
       resizeObserver?.disconnect();
@@ -82,8 +109,8 @@ export class CarouselComponent<T> implements AfterViewInit {
   }
 
   previous(): void {
-    if (this.circular() && this.hasOverflow() && !this.canScrollPrevious()) {
-      this.scrollToEdge('end');
+    if (this.circular()) {
+      this.moveCircular(-1);
       return;
     }
 
@@ -91,8 +118,8 @@ export class CarouselComponent<T> implements AfterViewInit {
   }
 
   next(): void {
-    if (this.circular() && this.hasOverflow() && !this.canScrollNext()) {
-      this.scrollToEdge('start');
+    if (this.circular()) {
+      this.moveCircular(1);
       return;
     }
 
@@ -100,6 +127,16 @@ export class CarouselComponent<T> implements AfterViewInit {
   }
 
   scrollTo(index: number): void {
+    if (this.circular()) {
+      if (index < 0 || index >= this.items().length) {
+        return;
+      }
+
+      this.currentPage.set(Math.floor(index / this.itemsPerPage()));
+      this.transitionDirection.set(0);
+      return;
+    }
+
     const item = this.viewport().nativeElement.children.item(index) as HTMLElement | null;
 
     item?.scrollIntoView({
@@ -110,9 +147,28 @@ export class CarouselComponent<T> implements AfterViewInit {
   }
 
   protected handleScroll(): void {
+    if (this.circular()) {
+      return;
+    }
+
     this.refreshNavigation();
   }
 
+  protected finishCircularTransition(event: TransitionEvent): void {
+    if (event.target !== event.currentTarget || event.propertyName !== 'transform') {
+      return;
+    }
+
+    const direction = this.transitionDirection();
+
+    if (direction === 0) {
+      return;
+    }
+
+    this.currentPage.update((page) => this.normalizePage(page + direction, this.pageCount()));
+    this.transitionDirection.set(0);
+  }
+
   protected handleKeydown(event: KeyboardEvent): void {
     if (event.key === 'ArrowLeft') {
       event.preventDefault();
@@ -139,6 +195,14 @@ export class CarouselComponent<T> implements AfterViewInit {
     });
   }
 
+  private moveCircular(direction: -1 | 1): void {
+    if (!this.hasOverflow() || this.transitionDirection() !== 0) {
+      return;
+    }
+
+    this.transitionDirection.set(direction);
+  }
+
   private refreshNavigation(): void {
     const viewport = this.viewport().nativeElement;
     const maxScrollLeft = Math.max(viewport.scrollWidth - viewport.clientWidth, 0);
@@ -149,18 +213,9 @@ export class CarouselComponent<T> implements AfterViewInit {
     this.canScrollNext.set(viewport.scrollLeft < maxScrollLeft - tolerance);
   }
 
-  private scrollToEdge(edge: 'start' | 'end'): void {
-    const viewport = this.viewport().nativeElement;
-
-    viewport.scrollTo({
-      left: edge === 'start' ? 0 : viewport.scrollWidth - viewport.clientWidth,
-      behavior: 'smooth',
-    });
-  }
-
   private refreshLayout(): void {
     const viewport = this.viewport().nativeElement;
-    const firstItem = viewport.firstElementChild as HTMLElement | null;
+    const firstItem = viewport.querySelector<HTMLElement>('.carousel__item');
     const availableWidth = this.host.nativeElement.clientWidth;
 
     if (!firstItem || availableWidth <= 0) {
@@ -179,10 +234,41 @@ export class CarouselComponent<T> implements AfterViewInit {
 
     const gap = this.resolvedGap();
     const fittingItems = Math.max(1, Math.floor((availableWidth + gap) / (itemWidth + gap)));
-    const visibleItems = Math.min(fittingItems, viewport.children.length);
+    const visibleItems = Math.min(fittingItems, this.items().length);
     const fittedWidth = visibleItems * itemWidth + Math.max(visibleItems - 1, 0) * gap;
 
+    if (this.itemsPerPage() !== fittingItems) {
+      this.itemsPerPage.set(fittingItems);
+      this.currentPage.set(0);
+      this.transitionDirection.set(0);
+    }
+
     this.viewportWidth.set(Math.min(Math.ceil(fittedWidth), availableWidth));
-    this.refreshNavigation();
+    if (this.circular()) {
+      const hasOverflow = this.items().length > fittingItems;
+      this.hasOverflow.set(hasOverflow);
+      this.canScrollPrevious.set(hasOverflow);
+      this.canScrollNext.set(hasOverflow);
+    } else {
+      this.refreshNavigation();
+    }
+  }
+
+  private createPage(slot: CarouselPage<T>['slot'], page: number): CarouselPage<T> {
+    const pageCount = this.pageCount();
+    const normalizedPage = this.normalizePage(page, pageCount);
+    const start = normalizedPage * this.itemsPerPage();
+    const end = Math.min(start + this.itemsPerPage(), this.items().length);
+    const items: CarouselPageItem<T>[] = [];
+
+    for (let index = start; index < end; index += 1) {
+      items.push({ item: this.items()[index], index });
+    }
+
+    return { slot, items };
+  }
+
+  private normalizePage(page: number, pageCount: number): number {
+    return ((page % pageCount) + pageCount) % pageCount;
   }
 }