wally-ui 1.8.0 → 1.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wally-ui",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "About Where’s Wally? Right here — bringing you ready-to-use Angular components with Wally-UI. Stop searching, start building.",
   "bin": {
     "wally": "dist/cli.js"

package/playground/showcase/src/app/components/carousel/carousel.html

@@ -1,32 +1,46 @@
-<div class="w-full flex flex-col items-center gap-4">
-    <div class="relative w-96 h-96 overflow-hidden shadow rounded-lg" #carouselContainer>
-        <ng-content></ng-content>
-    </div>
+<div class="w-full h-full flex flex-col items-center gap-4 p-2">
+    <div class="w-full h-full flex items-center gap-3">
+        <div>
+            <button type="button"
+                class="group hidden sm:block bg-neutral-100 hover:bg-neutral-200 border-2 border-neutral-200 hover:border-neutral-300 dark:bg-[#1b1b1b] dark:hover:bg-[#1d1d1d] dark:border-neutral-700 hover:dark:border-neutral-600 p-2 rounded-full cursor-pointer transition-all duration-500 ease-in-out"
+                (click)="navigateToPreviousItem()" aria-label="Go to previous slide">
+                <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2"
+                    stroke="currentColor"
+                    class="size-5 text-neutral-500 dark:text-neutral-300 group-hover:dark:text-white transition-all duration-500 ease-in-out">
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M10.5 19.5 3 12m0 0 7.5-7.5M3 12h18" />
+                </svg>
+            </button>
+        </div>
+
+        <div class="relative w-full h-full overflow-hidden p-2 shadow rounded-lg" #carouselContainer>
+            <ng-content></ng-content>
+        </div>
 
-    <div class="flex items-center gap-3">
-        @for (navigationDot of navigationDotsArray; track $index; let dotIndex = $index) {
-            <button
-                class="size-2 rounded-full transition-all duration-500 ease-in-out cursor-pointer"
-                [ngClass]="{
-                    'bg-blue-500 border scale-150': dotIndex === currentVisibleItemIndex(),
-                    'bg-white hover:bg-gray-400 hover:scale-125': dotIndex !== currentVisibleItemIndex()
-                }"
-                (click)="navigateToSpecificItem(dotIndex)"
-                [attr.aria-label]="'Navigate to slide ' + (dotIndex + 1)">
+        <div>
+            <button type="button"
+                class="group hidden sm:block bg-neutral-100 hover:bg-neutral-200 border-2 border-neutral-200 hover:border-neutral-300 dark:bg-[#1b1b1b] dark:hover:bg-[#1d1d1d] dark:border-neutral-700 hover:dark:border-neutral-600 p-2 rounded-full cursor-pointer transition-all duration-500 ease-in-out"
+                (click)="navigateToNextItem()" aria-label="Go to next slide">
+                <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2"
+                    stroke="currentColor"
+                    class="size-5 text-neutral-500 dark:text-neutral-300 group-hover:dark:text-white transition-all duration-500 ease-in-out">
+                    <path stroke-linecap="round" stroke-linejoin="round" d="M13.5 4.5 21 12m0 0-7.5 7.5M21 12H3" />
+                </svg>
             </button>
-        }
+        </div>
     </div>
 
-    <div class="flex gap-4">
-        <button class="px-4 py-2 bg-gray-700 text-white rounded hover:bg-gray-600 transition-colors duration-200"
-                (click)="navigateToPreviousItem()"
-                aria-label="Go to previous slide">
-            Previous
-        </button>
-        <button class="px-4 py-2 bg-gray-700 text-white rounded hover:bg-gray-600 transition-colors duration-200"
-                (click)="navigateToNextItem()"
-                aria-label="Go to next slide">
-            Next
+    @if (isNavigationIndicator()) {
+    <div class="flex items-center gap-2">
+        @for (navigationIndicator of navigationIndicatorsArray; track $index; let indicatorIndex = $index) {
+        <button type="button"
+            class="w-3.5 h-1.5 rounded-sm transition-all duration-500 ease-in-out cursor-pointer focus:outline-none focus:ring-0 active:outline-none"
+            [ngClass]="{
+                        'bg-blue-500': indicatorIndex === currentVisibleItemIndex(),
+                        'bg-neutral-300 hover:bg-neutral-400 hover:scale-105 dark:bg-neutral-700': indicatorIndex !== currentVisibleItemIndex()
+                    }" (click)="navigateToSpecificItem(indicatorIndex)"
+            [attr.aria-label]="'Navigate to slide ' + (indicatorIndex + 1)">
         </button>
+        }
     </div>
+    }
 </div>

package/playground/showcase/src/app/components/carousel/carousel.ts

@@ -1,4 +1,4 @@
-import { Component, input, OnInit, signal, ViewChild, ElementRef, AfterViewInit, Renderer2, OnDestroy, HostListener } from '@angular/core';
+import { Component, signal, ViewChild, ElementRef, AfterViewInit, Renderer2, OnDestroy, HostListener, WritableSignal, input, InputSignal } from '@angular/core';
 import { CommonModule } from '@angular/common';
 
 @Component({
@@ -6,14 +6,14 @@ import { CommonModule } from '@angular/common';
   imports: [CommonModule],
   templateUrl: './carousel.html',
 })
-export class Carousel implements OnInit, AfterViewInit, OnDestroy {
+export class Carousel implements AfterViewInit, OnDestroy {
   @ViewChild('carouselContainer', { static: false }) carouselContainer!: ElementRef;
 
-  totalItemsCount = signal<number>(0);
-  currentVisibleItemIndex = signal<number>(0);
+  isNavigationIndicator: InputSignal<boolean> = input<boolean>(false);
+  totalItemsCount: WritableSignal<number> = signal<number>(0);
+  currentVisibleItemIndex: WritableSignal<number> = signal<number>(0);
   carouselItemElements: HTMLElement[] = [];
 
-  // Touch and swipe gesture state
   private gestureState = {
     startPositionX: 0,
     startPositionY: 0,
@@ -23,22 +23,19 @@ export class Carousel implements OnInit, AfterViewInit, OnDestroy {
     gestureStartTime: 0
   };
 
-  // Configuration constants for touch and swipe behavior
-  private readonly MINIMUM_SWIPE_DISTANCE = 50; // minimum pixels to register as swipe
-  private readonly MINIMUM_SWIPE_VELOCITY = 0.3; // minimum velocity to register as swipe
-  private readonly MAXIMUM_SWIPE_DURATION = 300; // maximum milliseconds for swipe gesture
+  private readonly MINIMUM_SWIPE_DISTANCE = 50;
+  private readonly MINIMUM_SWIPE_VELOCITY = 0.3;
+  private readonly MAXIMUM_SWIPE_DURATION = 300;
 
-  // Event listener cleanup functions
   private eventListenerCleanupFunctions: (() => void)[] = [];
 
-  get navigationDotsArray() {
+  get navigationIndicatorsArray() {
     return Array(this.totalItemsCount()).fill(0);
   }
 
-  constructor(private renderer: Renderer2) { }
-
-  ngOnInit(): void {
-  }
+  constructor(
+    private renderer: Renderer2
+  ) { }
 
   ngAfterViewInit(): void {
     if (this.carouselContainer) {
@@ -49,16 +46,76 @@ export class Carousel implements OnInit, AfterViewInit, OnDestroy {
   }
 
   ngOnDestroy(): void {
-    // Clean up all event listeners to prevent memory leaks
     this.eventListenerCleanupFunctions.forEach(cleanupFunction => cleanupFunction());
   }
 
+  calculateNextItemIndex(currentItemIndex: number): number {
+    return (currentItemIndex + 1) % this.totalItemsCount();
+  }
+
+  calculatePreviousItemIndex(currentItemIndex: number): number {
+    return (currentItemIndex - 1 + this.totalItemsCount()) % this.totalItemsCount();
+  }
+
+  navigateToNextItem(): void {
+    this.currentVisibleItemIndex.set(this.calculateNextItemIndex(this.currentVisibleItemIndex()));
+    this.updateAllItemElementPositions();
+  }
+
+  navigateToPreviousItem(): void {
+    this.currentVisibleItemIndex.set(this.calculatePreviousItemIndex(this.currentVisibleItemIndex()));
+    this.updateAllItemElementPositions();
+  }
+
+  navigateToSpecificItem(targetItemIndex: number): void {
+    this.currentVisibleItemIndex.set(targetItemIndex);
+    this.updateAllItemElementPositions();
+  }
+
+  updateItemElementPosition(carouselItemElement: HTMLElement, itemIndex: number): void {
+    const currentVisibleIndex = this.currentVisibleItemIndex();
+
+    if (itemIndex === currentVisibleIndex) {
+      this.renderer.setStyle(carouselItemElement, 'transform', 'translateX(0)');
+    } else if (itemIndex > currentVisibleIndex) {
+      this.renderer.setStyle(carouselItemElement, 'transform', 'translateX(110%)');
+    } else {
+      this.renderer.setStyle(carouselItemElement, 'transform', 'translateX(-110%)');
+    }
+  }
+
+  updateAllItemElementPositions(): void {
+    this.carouselItemElements.forEach((itemElement, itemIndex) => {
+      this.updateItemElementPosition(itemElement, itemIndex);
+    });
+  }
+
+  @HostListener('keydown', ['$event'])
+  handleKeyboardNavigation(keyboardEvent: KeyboardEvent): void {
+    switch (keyboardEvent.key) {
+      case 'ArrowLeft':
+        keyboardEvent.preventDefault();
+        this.navigateToPreviousItem();
+        break;
+      case 'ArrowRight':
+        keyboardEvent.preventDefault();
+        this.navigateToNextItem();
+        break;
+      case 'Home':
+        keyboardEvent.preventDefault();
+        this.navigateToSpecificItem(0);
+        break;
+      case 'End':
+        keyboardEvent.preventDefault();
+        this.navigateToSpecificItem(this.totalItemsCount() - 1);
+        break;
+    }
+  }
+
   private initializeCarouselItems(): void {
-    // Get all direct children elements of the carousel container
     this.carouselItemElements = Array.from(this.carouselContainer.nativeElement.children);
     this.totalItemsCount.set(this.carouselItemElements.length);
 
-    // Apply positioning and styling to each carousel item using Renderer2
     this.carouselItemElements.forEach((itemElement, itemIndex) => {
       this.renderer.setStyle(itemElement, 'position', 'absolute');
       this.renderer.setStyle(itemElement, 'inset', '0');
@@ -73,18 +130,15 @@ export class Carousel implements OnInit, AfterViewInit, OnDestroy {
   private setupTouchAndMouseEvents(): void {
     const carouselContainerElement = this.carouselContainer.nativeElement;
 
-    // Touch events for mobile devices
     const touchStartListener = this.renderer.listen(carouselContainerElement, 'touchstart', (event) => this.handleTouchStart(event));
     const touchMoveListener = this.renderer.listen(carouselContainerElement, 'touchmove', (event) => this.handleTouchMove(event));
     const touchEndListener = this.renderer.listen(carouselContainerElement, 'touchend', () => this.handleTouchEnd());
 
-    // Mouse events for desktop devices
     const mouseDownListener = this.renderer.listen(carouselContainerElement, 'mousedown', (event) => this.handleMouseDown(event));
     const mouseMoveListener = this.renderer.listen(carouselContainerElement, 'mousemove', (event) => this.handleMouseMove(event));
     const mouseUpListener = this.renderer.listen(carouselContainerElement, 'mouseup', () => this.handleMouseUp());
     const mouseLeaveListener = this.renderer.listen(carouselContainerElement, 'mouseleave', () => this.handleMouseUp());
 
-    // Store all cleanup functions for proper memory management
     this.eventListenerCleanupFunctions.push(
       touchStartListener,
       touchMoveListener,
@@ -95,48 +149,24 @@ export class Carousel implements OnInit, AfterViewInit, OnDestroy {
       mouseLeaveListener
     );
 
-    // Optimize touch performance by restricting to horizontal panning only
     this.renderer.setStyle(carouselContainerElement, 'touch-action', 'pan-x');
   }
 
   private setupAccessibilityAttributes(): void {
     const carouselContainerElement = this.carouselContainer.nativeElement;
 
-    // Set ARIA attributes for screen readers and accessibility
     this.renderer.setAttribute(carouselContainerElement, 'role', 'region');
     this.renderer.setAttribute(carouselContainerElement, 'aria-label', 'Carousel');
     this.renderer.setAttribute(carouselContainerElement, 'tabindex', '0');
   }
 
-  updateItemElementPosition(carouselItemElement: HTMLElement, itemIndex: number): void {
-    const currentVisibleIndex = this.currentVisibleItemIndex();
-
-    if (itemIndex === currentVisibleIndex) {
-      // Position the currently visible item at center (0% translation)
-      this.renderer.setStyle(carouselItemElement, 'transform', 'translateX(0)');
-    } else if (itemIndex > currentVisibleIndex) {
-      // Position items to the right of current item (110% translation to the right)
-      this.renderer.setStyle(carouselItemElement, 'transform', 'translateX(110%)');
-    } else {
-      // Position items to the left of current item (110% translation to the left)
-      this.renderer.setStyle(carouselItemElement, 'transform', 'translateX(-110%)');
-    }
-  }
-
-  updateAllItemElementPositions(): void {
-    this.carouselItemElements.forEach((itemElement, itemIndex) => {
-      this.updateItemElementPosition(itemElement, itemIndex);
-    });
-  }
-
-  // Touch event handlers for mobile devices
   private handleTouchStart(touchEvent: TouchEvent): void {
     this.initializeGesture(touchEvent.touches[0].clientX, touchEvent.touches[0].clientY);
   }
 
   private handleTouchMove(touchEvent: TouchEvent): void {
     if (this.gestureState.isCurrentlyDragging) {
-      touchEvent.preventDefault(); // Prevent page scrolling during swipe
+      touchEvent.preventDefault();
       this.updateGesturePosition(touchEvent.touches[0].clientX, touchEvent.touches[0].clientY);
     }
   }
@@ -145,14 +175,13 @@ export class Carousel implements OnInit, AfterViewInit, OnDestroy {
     this.finalizeGestureAndNavigate();
   }
 
-  // Mouse event handlers for desktop devices
   private handleMouseDown(mouseEvent: MouseEvent): void {
     this.initializeGesture(mouseEvent.clientX, mouseEvent.clientY);
   }
 
   private handleMouseMove(mouseEvent: MouseEvent): void {
     if (this.gestureState.isCurrentlyDragging) {
-      mouseEvent.preventDefault(); // Prevent text selection during drag
+      mouseEvent.preventDefault();
       this.updateGesturePosition(mouseEvent.clientX, mouseEvent.clientY);
     }
   }
@@ -161,7 +190,6 @@ export class Carousel implements OnInit, AfterViewInit, OnDestroy {
     this.finalizeGestureAndNavigate();
   }
 
-  // Unified gesture handling methods
   private initializeGesture(xPosition: number, yPosition: number): void {
     this.gestureState = {
       startPositionX: xPosition,
@@ -188,70 +216,18 @@ export class Carousel implements OnInit, AfterViewInit, OnDestroy {
     const gestureDuration = Date.now() - this.gestureState.gestureStartTime;
     const gestureVelocity = Math.abs(horizontalDistanceMoved) / gestureDuration;
 
-    // Only process horizontal swipes (ignore vertical movements)
     if (Math.abs(horizontalDistanceMoved) > Math.abs(verticalDistanceMoved)) {
-      // Check if gesture meets minimum requirements for navigation
       const isValidSwipeGesture = Math.abs(horizontalDistanceMoved) > this.MINIMUM_SWIPE_DISTANCE ||
         (gestureVelocity > this.MINIMUM_SWIPE_VELOCITY && gestureDuration < this.MAXIMUM_SWIPE_DURATION);
 
       if (isValidSwipeGesture) {
         if (horizontalDistanceMoved > 0) {
-          this.navigateToPreviousItem(); // Swipe right = go to previous item
+          this.navigateToPreviousItem();
         } else {
-          this.navigateToNextItem(); // Swipe left = go to next item
+          this.navigateToNextItem();
         }
       }
     }
-
-    // Reset gesture state after processing
     this.gestureState.isCurrentlyDragging = false;
   }
-
-  // Keyboard navigation handler
-  @HostListener('keydown', ['$event'])
-  handleKeyboardNavigation(keyboardEvent: KeyboardEvent): void {
-    switch (keyboardEvent.key) {
-      case 'ArrowLeft':
-        keyboardEvent.preventDefault();
-        this.navigateToPreviousItem();
-        break;
-      case 'ArrowRight':
-        keyboardEvent.preventDefault();
-        this.navigateToNextItem();
-        break;
-      case 'Home':
-        keyboardEvent.preventDefault();
-        this.navigateToSpecificItem(0);
-        break;
-      case 'End':
-        keyboardEvent.preventDefault();
-        this.navigateToSpecificItem(this.totalItemsCount() - 1);
-        break;
-    }
-  }
-
-  // Circular buffer algorithm implementation for infinite carousel navigation
-  calculateNextItemIndex(currentItemIndex: number): number {
-    return (currentItemIndex + 1) % this.totalItemsCount();
-  }
-
-  calculatePreviousItemIndex(currentItemIndex: number): number {
-    return (currentItemIndex - 1 + this.totalItemsCount()) % this.totalItemsCount();
-  }
-
-  navigateToNextItem(): void {
-    this.currentVisibleItemIndex.set(this.calculateNextItemIndex(this.currentVisibleItemIndex()));
-    this.updateAllItemElementPositions();
-  }
-
-  navigateToPreviousItem(): void {
-    this.currentVisibleItemIndex.set(this.calculatePreviousItemIndex(this.currentVisibleItemIndex()));
-    this.updateAllItemElementPositions();
-  }
-
-  navigateToSpecificItem(targetItemIndex: number): void {
-    this.currentVisibleItemIndex.set(targetItemIndex);
-    this.updateAllItemElementPositions();
-  }
-  // end test Circular Buffer ---
-}
+}

package/playground/showcase/src/app/pages/documentation/components/carousel-docs/carousel-docs.examples.ts

@@ -18,6 +18,45 @@ export const CarouselCodeExamples = {
   <div>Item 2</div>
 </wally-carousel>`,
 
+  // With navigation indicators
+  withNavigationIndicators: `<wally-carousel [isNavigationIndicator]="true">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</wally-carousel>`,
+
+  // Image carousel
+  imageCarousel: `<div class="w-full h-80">
+  <wally-carousel>
+    <div class="w-full h-full">
+      <img src="/api/placeholder/600/320" alt="Image 1" class="w-full h-full object-cover">
+    </div>
+    <div class="w-full h-full">
+      <img src="/api/placeholder/600/320" alt="Image 2" class="w-full h-full object-cover">
+    </div>
+    <div class="w-full h-full">
+      <img src="/api/placeholder/600/320" alt="Image 3" class="w-full h-full object-cover">
+    </div>
+  </wally-carousel>
+</div>`,
+
+  // Product showcase
+  productShowcase: `<div class="w-full h-96">
+  <wally-carousel>
+    <div class="w-full h-full bg-white border-2 border-gray-200 rounded-lg p-6 flex flex-col items-center justify-center">
+      <div class="w-20 h-20 bg-blue-500 rounded-lg mb-4"></div>
+      <h3 class="text-lg font-semibold text-gray-900">Product A</h3>
+      <p class="text-gray-600 text-center">Amazing features and benefits</p>
+      <span class="text-xl font-bold text-blue-600 mt-2">$99</span>
+    </div>
+    <div class="w-full h-full bg-white border-2 border-gray-200 rounded-lg p-6 flex flex-col items-center justify-center">
+      <div class="w-20 h-20 bg-green-500 rounded-lg mb-4"></div>
+      <h3 class="text-lg font-semibold text-gray-900">Product B</h3>
+      <p class="text-gray-600 text-center">Premium quality guaranteed</p>
+      <span class="text-xl font-bold text-green-600 mt-2">$149</span>
+    </div>
+  </wally-carousel>
+</div>`,
+
   // Custom content example
   customContent: `<wally-carousel>
   <div class="w-full h-full bg-gradient-to-r from-blue-500 to-purple-600 text-white flex flex-col items-center justify-center p-6">
@@ -30,19 +69,64 @@ export const CarouselCodeExamples = {
   </div>
 </wally-carousel>`,
 
-  // Properties
-  properties: `// Component properties
-// The carousel automatically detects child elements and creates navigation
-// Currently no input properties - content projection only
-
-// Available interactions:
-// • Click navigation buttons (Previous/Next)
-// • Click dot indicators for direct navigation
-// • Touch/swipe gestures on mobile and desktop
-// • Keyboard navigation (Arrow keys, Home, End)
-
-// Auto-detected features:
-totalItemsCount: number;              // Automatically set based on child elements
-currentVisibleItemIndex: number;     // Currently visible slide index (0-based)
-navigationDotsArray: any[];          // Auto-generated dot indicators`
+  // Responsive design example
+  responsiveExample: `<!-- Different sizes for different use cases -->
+
+<!-- Hero carousel - full width, tall -->
+<div class="w-full h-96">
+  <wally-carousel>
+    <div>Hero slide 1</div>
+    <div>Hero slide 2</div>
+  </wally-carousel>
+</div>
+
+<!-- Product gallery - square aspect ratio -->
+<div class="w-full aspect-square max-w-md">
+  <wally-carousel>
+    <div>Product image 1</div>
+    <div>Product image 2</div>
+  </wally-carousel>
+</div>
+
+<!-- Mobile testimonials - compact -->
+<div class="w-full h-48 sm:h-64">
+  <wally-carousel>
+    <div>Testimonial 1</div>
+    <div>Testimonial 2</div>
+  </wally-carousel>
+</div>`,
+
+  // Individual properties
+  propertyIsNavigationIndicator: `isNavigationIndicator: InputSignal<boolean> = input<boolean>(false);`,
+  propertyTotalItemsCount: `totalItemsCount: number (read-only);`,
+  propertyCurrentVisibleItemIndex: `currentVisibleItemIndex: number (read-only);`,
+  propertyNavigationIndicatorsArray: `navigationIndicatorsArray: any[] (read-only);`,
+
+  // API Methods
+  apiMethods: `// Public navigation methods
+navigateToNextItem(): void;           // Go to next slide
+navigateToPreviousItem(): void;       // Go to previous slide
+navigateToSpecificItem(index: number): void;  // Jump to specific slide
+
+// Public calculation methods
+calculateNextItemIndex(current: number): number;     // Get next index
+calculatePreviousItemIndex(current: number): number; // Get previous index
+
+// Public positioning methods
+updateItemElementPosition(element: HTMLElement, index: number): void;
+updateAllItemElementPositions(): void;`,
+
+  // Keyboard shortcuts
+  keyboardShortcuts: `// Keyboard navigation (when carousel is focused)
+ArrowLeft  → Previous slide
+ArrowRight → Next slide
+Home       → First slide
+End        → Last slide`,
+
+  // Touch gestures
+  touchGestures: `// Touch and mouse gestures
+Swipe Left  → Next slide
+Swipe Right → Previous slide
+Click Dots  → Jump to specific slide
+Drag        → Same as swipe (desktop)`
 };

package/playground/showcase/src/app/pages/documentation/components/carousel-docs/carousel-docs.html

@@ -7,18 +7,10 @@
     <h1 class="text-2xl font-bold mb-4 text-[#0a0a0a] dark:text-white">
       Carousel
     </h1>
-    <p class="text-gray-700 dark:text-gray-400 mb-4">
-      A carousel component with navigation controls, touch gestures, and smooth transitions.
+    <p class="text-gray-700 dark:text-gray-400 mb-6">
+      A fully responsive carousel component with navigation controls, touch/swipe gestures, keyboard accessibility, and smooth transitions. Built with comprehensive accessibility features and optimized performance.
     </p>
 
-    <!-- Under Construction Badge -->
-    <div class="mb-6">
-      <span class="text-xs bg-yellow-500 text-black px-3 py-1 rounded-full font-medium">Under Construction</span>
-      <p class="text-sm text-gray-600 dark:text-gray-400 mt-2">
-        This component is actively being developed. Touch gestures, accessibility, and customization options are coming soon.
-      </p>
-    </div>
-
     <!-- AI Prompts -->
     <div class="flex flex-wrap gap-2 mb-6">
       <a [href]="claudeUrl" target="_blank"
@@ -63,17 +55,20 @@
       <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">Preview</h2>
       <div class="p-6 border rounded-lg bg-white dark:bg-[#121212]">
         <div class="flex justify-center">
-          <wally-carousel>
-            <div class="w-full h-full bg-blue-500 text-white flex items-center justify-center text-lg font-semibold">
-              Slide 1
-            </div>
-            <div class="w-full h-full bg-green-500 text-white flex items-center justify-center text-lg font-semibold">
-              Slide 2
-            </div>
-            <div class="w-full h-full bg-purple-500 text-white flex items-center justify-center text-lg font-semibold">
-              Slide 3
-            </div>
-          </wally-carousel>
+          <div class="w-96 h-96">
+            <wally-carousel>
+              <div class="w-full h-full bg-blue-500 text-white flex items-center justify-center text-lg font-semibold">
+                Slide 1
+              </div>
+              <div class="w-full h-full bg-green-500 text-white flex items-center justify-center text-lg font-semibold">
+                Slide 2
+              </div>
+              <div
+                class="w-full h-full bg-purple-500 text-white flex items-center justify-center text-lg font-semibold">
+                Slide 3
+              </div>
+            </wally-carousel>
+          </div>
         </div>
       </div>
     </section>
@@ -95,23 +90,96 @@
     <!-- Basic Usage -->
     <section class="mb-8">
       <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">Basic Usage</h2>
-      <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg mb-4">
-        <pre><code [innerHTML]="basicUsageCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
-      </div>
-      <div class="p-6 border rounded-lg bg-white dark:bg-[#121212]">
-        <div class="flex justify-center">
-          <wally-carousel>
-            <div class="w-full h-full bg-blue-400 text-white flex items-center justify-center">
-              Item 1
+      <p class="text-gray-700 dark:text-gray-400 mb-4">
+        Simple carousel setup - just wrap your content elements. No configuration required.
+      </p>
+
+      <!-- Simple Example -->
+      <div class="mb-8">
+        <h3 class="text-md font-medium mb-3 text-[#0a0a0a] dark:text-white">Simple Carousel</h3>
+        <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg mb-4">
+          <pre><code [innerHTML]="basicUsageCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+        </div>
+        <div class="p-6 border rounded-lg bg-white dark:bg-[#121212]">
+          <div class="flex justify-center">
+            <div class="w-96 h-96">
+              <wally-carousel>
+                <div class="w-full h-full bg-blue-400 text-white flex items-center justify-center text-lg font-semibold">
+                  Item 1
+                </div>
+                <div class="w-full h-full bg-green-400 text-white flex items-center justify-center text-lg font-semibold">
+                  Item 2
+                </div>
+              </wally-carousel>
             </div>
-            <div class="w-full h-full bg-green-400 text-white flex items-center justify-center">
-              Item 2
+          </div>
+        </div>
+      </div>
+
+      <!-- With Navigation Indicators -->
+      <div class="mb-8">
+        <h3 class="text-md font-medium mb-3 text-[#0a0a0a] dark:text-white">With Navigation Indicators</h3>
+        <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg mb-4">
+          <pre><code [innerHTML]="withNavigationIndicatorsCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+        </div>
+        <div class="p-6 border rounded-lg bg-white dark:bg-[#121212]">
+          <div class="flex justify-center">
+            <div class="w-96 h-96">
+              <wally-carousel [isNavigationIndicator]="true">
+                <div class="w-full h-full bg-orange-400 text-white flex items-center justify-center text-lg font-semibold">
+                  Item 1
+                </div>
+                <div class="w-full h-full bg-red-400 text-white flex items-center justify-center text-lg font-semibold">
+                  Item 2
+                </div>
+              </wally-carousel>
             </div>
-          </wally-carousel>
+          </div>
         </div>
       </div>
+
+      <!-- Product Showcase -->
+      <div class="mb-8">
+        <h3 class="text-md font-medium mb-3 text-[#0a0a0a] dark:text-white">Product Showcase</h3>
+        <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg mb-4">
+          <pre><code [innerHTML]="productShowcaseCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+        </div>
+        <div class="p-6 border rounded-lg bg-white dark:bg-[#121212]">
+          <div class="w-full h-96">
+            <wally-carousel>
+              <div class="w-full h-full bg-white dark:bg-[#1a1a1a] border border-gray-200 dark:border-gray-700 rounded-lg p-8 flex flex-col items-center justify-center">
+                <div class="w-24 h-24 bg-blue-500 rounded mb-6"></div>
+                <h3 class="text-xl font-semibold text-gray-900 dark:text-white mb-2">MacBook Pro</h3>
+                <p class="text-gray-600 dark:text-gray-400 text-center mb-4">M3 chip, 16GB RAM, 512GB SSD</p>
+                <span class="text-2xl font-bold text-blue-600">$1,999</span>
+              </div>
+              <div class="w-full h-full bg-white dark:bg-[#1a1a1a] border border-gray-200 dark:border-gray-700 rounded-lg p-8 flex flex-col items-center justify-center">
+                <div class="w-24 h-24 bg-green-500 rounded mb-6"></div>
+                <h3 class="text-xl font-semibold text-gray-900 dark:text-white mb-2">iPhone 15</h3>
+                <p class="text-gray-600 dark:text-gray-400 text-center mb-4">128GB, Dynamic Island, USB-C</p>
+                <span class="text-2xl font-bold text-green-600">$799</span>
+              </div>
+              <div class="w-full h-full bg-white dark:bg-[#1a1a1a] border border-gray-200 dark:border-gray-700 rounded-lg p-8 flex flex-col items-center justify-center">
+                <div class="w-24 h-24 bg-purple-500 rounded mb-6"></div>
+                <h3 class="text-xl font-semibold text-gray-900 dark:text-white mb-2">iPad Air</h3>
+                <p class="text-gray-600 dark:text-gray-400 text-center mb-4">10.9-inch, M2 chip, Wi-Fi</p>
+                <span class="text-2xl font-bold text-purple-600">$599</span>
+              </div>
+            </wally-carousel>
+          </div>
+        </div>
+      </div>
+
+      <div class="mt-6 p-4 bg-amber-50 dark:bg-amber-900/20 border border-amber-200 dark:border-amber-800 rounded-lg">
+        <h3 class="font-medium text-amber-900 dark:text-amber-100 mb-2">Tip</h3>
+        <p class="text-sm text-amber-800 dark:text-amber-200">
+          The carousel automatically detects child elements and creates navigation.
+          Try swiping on mobile or using keyboard arrows when focused!
+        </p>
+      </div>
     </section>
 
+
     <!-- Advanced Examples -->
     <section class="mb-8">
       <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">Advanced Examples</h2>
@@ -124,33 +192,394 @@
         </div>
         <div class="p-6 border rounded-lg bg-white dark:bg-[#121212]">
           <div class="flex justify-center">
-            <wally-carousel>
-              <div class="w-full h-full bg-gradient-to-r from-blue-500 to-purple-600 text-white flex flex-col items-center justify-center p-6">
-                <h3 class="text-xl font-bold mb-2">Feature 1</h3>
-                <p class="text-center text-sm">This is a custom slide with rich content</p>
-              </div>
-              <div class="w-full h-full bg-gradient-to-r from-green-500 to-blue-500 text-white flex flex-col items-center justify-center p-6">
-                <h3 class="text-xl font-bold mb-2">Feature 2</h3>
-                <p class="text-center text-sm">Another slide with different styling</p>
+            <div class="w-96 h-96">
+              <wally-carousel>
+                <div
+                  class="w-full h-full bg-gradient-to-r from-blue-500 to-purple-600 text-white flex flex-col items-center justify-center p-6">
+                  <h3 class="text-xl font-bold mb-2">Feature 1</h3>
+                  <p class="text-center text-sm">This is a custom slide with rich content</p>
+                </div>
+                <div
+                  class="w-full h-full bg-gradient-to-r from-green-500 to-blue-500 text-white flex flex-col items-center justify-center p-6">
+                  <h3 class="text-xl font-bold mb-2">Feature 2</h3>
+                  <p class="text-center text-sm">Another slide with different styling</p>
+                </div>
+                <div
+                  class="w-full h-full bg-gradient-to-r from-purple-500 to-pink-500 text-white flex flex-col items-center justify-center p-6">
+                  <h3 class="text-xl font-bold mb-2">Feature 3</h3>
+                  <p class="text-center text-sm">Beautiful gradients and typography</p>
+                </div>
+              </wally-carousel>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <!-- Responsive Design -->
+    <section class="mb-8">
+      <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">Responsive Design</h2>
+      <p class="text-gray-700 dark:text-gray-400 mb-4">
+        The carousel is 100% responsive and adapts to any container size. Simply set the parent container dimensions and
+        the carousel will fill it completely.
+      </p>
+      <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg mb-4">
+        <pre><code [innerHTML]="responsiveExampleCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+      </div>
+
+      <!-- Live Examples -->
+      <div class="space-y-6">
+        <!-- Hero style -->
+        <div>
+          <h3 class="text-md font-medium mb-2 text-[#0a0a0a] dark:text-white">Hero Carousel (w-full h-96)</h3>
+          <div class="p-4 border rounded-lg bg-white dark:bg-[#121212]">
+            <div class="w-full h-96">
+              <wally-carousel>
+                <div
+                  class="w-full h-full bg-gradient-to-r from-indigo-500 to-purple-600 text-white flex flex-col items-center justify-center p-6">
+                  <h3 class="text-2xl font-bold mb-2">Hero Slide 1</h3>
+                  <p class="text-center">Perfect for landing page heroes</p>
+                </div>
+                <div
+                  class="w-full h-full bg-gradient-to-r from-purple-600 to-pink-600 text-white flex flex-col items-center justify-center p-6">
+                  <h3 class="text-2xl font-bold mb-2">Hero Slide 2</h3>
+                  <p class="text-center">Responsive and touch-friendly</p>
+                </div>
+              </wally-carousel>
+            </div>
+          </div>
+        </div>
+
+        <!-- Compact style -->
+        <div>
+          <h3 class="text-md font-medium mb-2 text-[#0a0a0a] dark:text-white">Compact Carousel (w-full h-48)</h3>
+          <div class="p-4 border rounded-lg bg-white dark:bg-[#121212]">
+            <div class="w-full h-48">
+              <wally-carousel>
+                <div
+                  class="w-full h-full bg-gradient-to-r from-emerald-500 to-teal-600 text-white flex items-center justify-center p-4">
+                  <div class="text-center">
+                    <h4 class="text-lg font-semibold mb-1">Compact Design</h4>
+                    <p class="text-sm">Great for testimonials</p>
+                  </div>
+                </div>
+                <div
+                  class="w-full h-full bg-gradient-to-r from-teal-600 to-cyan-600 text-white flex items-center justify-center p-4">
+                  <div class="text-center">
+                    <h4 class="text-lg font-semibold mb-1">Mobile Friendly</h4>
+                    <p class="text-sm">Swipe gestures included</p>
+                  </div>
+                </div>
+              </wally-carousel>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <!-- Accessibility -->
+    <section class="mb-8">
+      <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">Accessibility</h2>
+      <p class="text-gray-700 dark:text-gray-400 mb-6">
+        The carousel is built with comprehensive accessibility features and follows WCAG guidelines for inclusive design.
+      </p>
+
+      <div class="space-y-8">
+        <!-- ARIA Attributes -->
+        <div>
+          <h3 class="text-md font-medium mb-3 text-[#0a0a0a] dark:text-white">ARIA Attributes</h3>
+          <div class="p-6 border rounded-lg bg-white dark:bg-[#121212]">
+            <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+              <div class="space-y-3">
+                <div>
+                  <code class="text-sm dark:text-white bg-gray-200 dark:bg-[#1a1a1a] px-2 py-1 rounded">role="region"</code>
+                  <p class="text-xs text-gray-600 dark:text-gray-400 mt-1">Identifies the carousel as a landmark region</p>
+                </div>
+                <div>
+                  <code class="text-sm dark:text-white bg-gray-200 dark:bg-[#1a1a1a] px-2 py-1 rounded">aria-label="Carousel"</code>
+                  <p class="text-xs text-gray-600 dark:text-gray-400 mt-1">Provides accessible name for screen readers</p>
+                </div>
               </div>
-              <div class="w-full h-full bg-gradient-to-r from-purple-500 to-pink-500 text-white flex flex-col items-center justify-center p-6">
-                <h3 class="text-xl font-bold mb-2">Feature 3</h3>
-                <p class="text-center text-sm">Beautiful gradients and typography</p>
+              <div class="space-y-3">
+                <div>
+                  <code class="text-sm dark:text-white bg-gray-200 dark:bg-[#1a1a1a] px-2 py-1 rounded">tabindex="0"</code>
+                  <p class="text-xs text-gray-600 dark:text-gray-400 mt-1">Makes carousel keyboard focusable</p>
+                </div>
+                <div>
+                  <code class="text-sm dark:text-white bg-gray-200 dark:bg-[#1a1a1a] px-2 py-1 rounded">aria-label="Navigate to slide X"</code>
+                  <p class="text-xs text-gray-600 dark:text-gray-400 mt-1">Descriptive labels for navigation indicators</p>
+                </div>
               </div>
-            </wally-carousel>
+            </div>
           </div>
         </div>
+
+        <!-- Keyboard Navigation -->
+        <div>
+          <h3 class="text-md font-medium mb-3 text-[#0a0a0a] dark:text-white">Keyboard Navigation Example</h3>
+          <div class="p-6 border rounded-lg bg-white dark:bg-[#121212]">
+            <p class="text-sm text-gray-700 dark:text-gray-400 mb-4">
+              Click the carousel below to focus it, then use keyboard arrows to navigate:
+            </p>
+            <div class="w-full h-64">
+              <wally-carousel>
+                <div class="w-full h-full bg-gradient-to-r from-indigo-500 to-purple-600 text-white flex flex-col items-center justify-center p-6">
+                  <h3 class="text-xl font-bold mb-2">Keyboard Accessible</h3>
+                  <p class="text-center text-sm">Use ← → arrows when focused</p>
+                </div>
+                <div class="w-full h-full bg-gradient-to-r from-purple-600 to-pink-600 text-white flex flex-col items-center justify-center p-6">
+                  <h3 class="text-xl font-bold mb-2">Screen Reader Friendly</h3>
+                  <p class="text-center text-sm">Proper ARIA attributes included</p>
+                </div>
+                <div class="w-full h-full bg-gradient-to-r from-pink-600 to-rose-600 text-white flex flex-col items-center justify-center p-6">
+                  <h3 class="text-xl font-bold mb-2">WCAG Compliant</h3>
+                  <p class="text-center text-sm">WCAG accessibility standards</p>
+                </div>
+              </wally-carousel>
+            </div>
+          </div>
+        </div>
+
       </div>
     </section>
 
     <!-- Properties -->
     <section class="mb-8">
       <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">Properties</h2>
+      <p class="text-gray-700 dark:text-gray-400 mb-4">
+        The carousel component accepts one optional input property and automatically manages its internal state.
+      </p>
+
+      <div class="space-y-6">
+        <!-- Input Properties -->
+        <div>
+          <h3 class="text-md font-medium mb-3 text-[#0a0a0a] dark:text-white">Input Properties</h3>
+          <div class="space-y-2">
+            <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg">
+              <pre><code [innerHTML]="propertyIsNavigationIndicatorCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+            </div>
+            <p class="text-sm text-gray-700 dark:text-gray-400">
+              Controls whether navigation indicators (dots) are displayed below the carousel.
+            </p>
+          </div>
+        </div>
+
+        <!-- Read-only Properties -->
+        <div>
+          <h3 class="text-md font-medium mb-3 text-[#0a0a0a] dark:text-white">Read-only Properties</h3>
+          <div class="space-y-4">
+            <div class="space-y-2">
+              <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg">
+                <pre><code [innerHTML]="propertyTotalItemsCountCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+              </div>
+              <p class="text-sm text-gray-700 dark:text-gray-400">Automatically detected number of child elements in the carousel</p>
+            </div>
+
+            <div class="space-y-2">
+              <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg">
+                <pre><code [innerHTML]="propertyCurrentVisibleItemIndexCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+              </div>
+              <p class="text-sm text-gray-700 dark:text-gray-400">Zero-based index of the currently visible slide</p>
+            </div>
+
+            <div class="space-y-2">
+              <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg">
+                <pre><code [innerHTML]="propertyNavigationIndicatorsArrayCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+              </div>
+              <p class="text-sm text-gray-700 dark:text-gray-400">Auto-generated array used for rendering navigation indicators</p>
+            </div>
+          </div>
+        </div>
+      </div>
+    </section>
+
+    <!-- API Methods -->
+    <section class="mb-8">
+      <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">API Methods</h2>
+      <p class="text-gray-700 dark:text-gray-400 mb-4">
+        Public methods available for programmatic control of the carousel. Access these methods through a template reference or ViewChild.
+      </p>
+
+      <div class="overflow-x-auto">
+        <table class="w-full border-collapse border border-gray-200 dark:border-gray-700 rounded-lg">
+          <thead>
+            <tr class="bg-gray-50 dark:bg-[#1a1a1a]">
+              <th class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-left text-sm font-semibold text-[#0a0a0a] dark:text-white">Method</th>
+              <th class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-left text-sm font-semibold text-[#0a0a0a] dark:text-white">Parameters</th>
+              <th class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-left text-sm font-semibold text-[#0a0a0a] dark:text-white">Return</th>
+              <th class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-left text-sm font-semibold text-[#0a0a0a] dark:text-white">Description</th>
+            </tr>
+          </thead>
+          <tbody>
+            <!-- Navigation Methods -->
+            <tr class="bg-blue-50 dark:bg-blue-900/20">
+              <td colspan="4" class="border border-gray-200 dark:border-gray-700 px-4 py-2 text-sm font-medium text-blue-900 dark:text-blue-100">Navigation Methods</td>
+            </tr>
+            <tr>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm">
+                <code class="bg-gray-100 dark:bg-[#1a1a1a] dark:text-white px-2 py-1 rounded text-xs">navigateToNextItem()</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">None</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">void</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Navigate to the next slide with circular navigation</td>
+            </tr>
+            <tr>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm">
+                <code class="bg-gray-100 dark:bg-[#1a1a1a] dark:text-white px-2 py-1 rounded text-xs">navigateToPreviousItem()</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">None</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">void</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Navigate to the previous slide with circular navigation</td>
+            </tr>
+            <tr>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm">
+                <code class="bg-gray-100 dark:bg-[#1a1a1a] dark:text-white px-2 py-1 rounded text-xs">navigateToSpecificItem()</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">
+                <code class="text-xs">index: number</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">void</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Jump directly to a specific slide by index (0-based)</td>
+            </tr>
+
+            <!-- Calculation Methods -->
+            <tr class="bg-green-50 dark:bg-green-900/20">
+              <td colspan="4" class="border border-gray-200 dark:border-gray-700 px-4 py-2 text-sm font-medium text-green-900 dark:text-green-100">Calculation Methods</td>
+            </tr>
+            <tr>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm">
+                <code class="bg-gray-100 dark:bg-[#1a1a1a] dark:text-white px-2 py-1 rounded text-xs">calculateNextItemIndex()</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">
+                <code class="text-xs">current: number</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">number</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Calculate the next index using circular buffer algorithm</td>
+            </tr>
+            <tr>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm">
+                <code class="bg-gray-100 dark:bg-[#1a1a1a] dark:text-white px-2 py-1 rounded text-xs">calculatePreviousItemIndex()</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">
+                <code class="text-xs">current: number</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">number</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Calculate the previous index using circular buffer algorithm</td>
+            </tr>
+
+            <!-- Positioning Methods -->
+            <tr class="bg-purple-50 dark:bg-purple-900/20">
+              <td colspan="4" class="border border-gray-200 dark:border-gray-700 px-4 py-2 text-sm font-medium text-purple-900 dark:text-purple-100">Positioning Methods</td>
+            </tr>
+            <tr>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm">
+                <code class="bg-gray-100 dark:bg-[#1a1a1a] dark:text-white px-2 py-1 rounded text-xs">updateItemElementPosition()</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">
+                <code class="text-xs">element: HTMLElement<br>index: number</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">void</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Update position of a specific carousel item element</td>
+            </tr>
+            <tr>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm">
+                <code class="bg-gray-100 dark:bg-[#1a1a1a] dark:text-white px-2 py-1 rounded text-xs">updateAllItemElementPositions()</code>
+              </td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">None</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-600 dark:text-gray-400">void</td>
+              <td class="border border-gray-200 dark:border-gray-700 px-4 py-3 text-sm text-gray-700 dark:text-gray-300">Update positions of all carousel item elements</td>
+            </tr>
+          </tbody>
+        </table>
+      </div>
+    </section>
+
+    <!-- Keyboard Navigation -->
+    <section class="mb-8">
+      <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">Keyboard Navigation</h2>
+      <p class="text-gray-700 dark:text-gray-400 mb-4">
+        When the carousel has focus, users can navigate using these keyboard shortcuts.
+      </p>
       <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg">
-        <pre><code [innerHTML]="propertiesCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+        <pre><code [innerHTML]="keyboardShortcutsCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
       </div>
     </section>
 
+    <!-- Touch Gestures -->
+    <section class="mb-8">
+      <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">Touch & Mouse Gestures</h2>
+      <p class="text-gray-700 dark:text-gray-400 mb-4">
+        Interactive gestures supported on both mobile and desktop devices.
+      </p>
+      <div class="bg-gray-200 dark:bg-[#121212] p-4 rounded-lg">
+        <pre><code [innerHTML]="touchGesturesCode" class="text-sm text-[#0a0a0a] dark:text-white"></code></pre>
+      </div>
+    </section>
+
+    <!-- Features -->
+    <section class="mb-8">
+      <h2 class="text-lg font-semibold mb-4 text-[#0a0a0a] dark:text-white">Features</h2>
+      <div class="grid grid-cols-1 md:grid-cols-2 gap-4">
+        <div class="p-4 border rounded-lg bg-white dark:bg-[#121212]">
+          <div class="flex items-center gap-3 mb-2">
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="size-5 text-blue-500">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M10.5 1.5H8.25A2.25 2.25 0 0 0 6 3.75v16.5a2.25 2.25 0 0 0 2.25 2.25h7.5A2.25 2.25 0 0 0 18 20.25V3.75a2.25 2.25 0 0 0-2.25-2.25H13.5m-3 0V3h3V1.5m-3 0h3m-3 18.75h3" />
+            </svg>
+            <h3 class="font-medium text-[#0a0a0a] dark:text-white">Touch & Swipe</h3>
+          </div>
+          <p class="text-sm text-gray-700 dark:text-gray-400">Full touch gesture support with configurable thresholds for distance and velocity detection.</p>
+        </div>
 
+        <div class="p-4 border rounded-lg bg-white dark:bg-[#121212]">
+          <div class="flex items-center gap-3 mb-2">
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="size-5 text-green-500">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M9 12.75 11.25 15 15 9.75M21 12a9 9 0 1 1-18 0 9 9 0 0 1 18 0Z" />
+            </svg>
+            <h3 class="font-medium text-[#0a0a0a] dark:text-white">Accessibility</h3>
+          </div>
+          <p class="text-sm text-gray-700 dark:text-gray-400">ARIA attributes, keyboard navigation (arrows, home, end), and screen reader support built-in.</p>
+        </div>
+
+        <div class="p-4 border rounded-lg bg-white dark:bg-[#121212]">
+          <div class="flex items-center gap-3 mb-2">
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="size-5 text-purple-500">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M3.75 3.75v4.5m0-4.5h4.5m-4.5 0L9 9M3.75 20.25v-4.5m0 4.5h4.5m-4.5 0L9 15M20.25 3.75h-4.5m4.5 0v4.5m0-4.5L15 9m5.25 11.25h-4.5m4.5 0v-4.5m0 4.5L15 15" />
+            </svg>
+            <h3 class="font-medium text-[#0a0a0a] dark:text-white">100% Responsive</h3>
+          </div>
+          <p class="text-sm text-gray-700 dark:text-gray-400">Adapts to any container size automatically. Set parent dimensions and carousel fills completely.</p>
+        </div>
+
+        <div class="p-4 border rounded-lg bg-white dark:bg-[#121212]">
+          <div class="flex items-center gap-3 mb-2">
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="size-5 text-orange-500">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M3.75 13.5 10 4.5m0 0L16.25 13.5M10 4.5V21" />
+            </svg>
+            <h3 class="font-medium text-[#0a0a0a] dark:text-white">Performance</h3>
+          </div>
+          <p class="text-sm text-gray-700 dark:text-gray-400">GPU-accelerated animations, optimized event handling, and proper memory cleanup.</p>
+        </div>
+
+        <div class="p-4 border rounded-lg bg-white dark:bg-[#121212]">
+          <div class="flex items-center gap-3 mb-2">
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="size-5 text-indigo-500">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M16.023 9.348h4.992v-.001M2.985 19.644v-4.992m0 0h4.992m-4.993 0 3.181 3.183a8.25 8.25 0 0 0 13.803-3.7M4.031 9.865a8.25 8.25 0 0 1 13.803-3.7l3.181 3.182m0-4.991v4.99" />
+            </svg>
+            <h3 class="font-medium text-[#0a0a0a] dark:text-white">Infinite Loop</h3>
+          </div>
+          <p class="text-sm text-gray-700 dark:text-gray-400">Circular buffer algorithm provides seamless infinite navigation between slides.</p>
+        </div>
+
+        <div class="p-4 border rounded-lg bg-white dark:bg-[#121212]">
+          <div class="flex items-center gap-3 mb-2">
+            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke-width="2" stroke="currentColor" class="size-5 text-red-500">
+              <path stroke-linecap="round" stroke-linejoin="round" d="M12 3v2.25m6.364.386-1.591 1.591M21 12h-2.25m-.386 6.364-1.591-1.591M12 18.75V21m-6.364-.386 1.591-1.591M3 12h2.25m.386-6.364 1.591 1.591" />
+            </svg>
+            <h3 class="font-medium text-[#0a0a0a] dark:text-white">Zero Config</h3>
+          </div>
+          <p class="text-sm text-gray-700 dark:text-gray-400">No configuration required. Just wrap your content and it works. Automatically detects child elements.</p>
+        </div>
+      </div>
+    </section>
   </div>
-</div>
+</div>

package/playground/showcase/src/app/pages/documentation/components/carousel-docs/carousel-docs.ts

@@ -29,8 +29,20 @@ export class CarouselDocs {
   importCode = getFormattedCode(CarouselCodeExamples.import, 'typescript');
   componentImportCode = getFormattedCode(CarouselCodeExamples.componentImport, 'typescript');
   basicUsageCode = getFormattedCode(CarouselCodeExamples.basicUsage, 'html');
+  withNavigationIndicatorsCode = getFormattedCode(CarouselCodeExamples.withNavigationIndicators, 'html');
+  imageCarouselCode = getFormattedCode(CarouselCodeExamples.imageCarousel, 'html');
+  productShowcaseCode = getFormattedCode(CarouselCodeExamples.productShowcase, 'html');
   customContentCode = getFormattedCode(CarouselCodeExamples.customContent, 'html');
-  propertiesCode = getFormattedCode(CarouselCodeExamples.properties, 'typescript');
+  responsiveExampleCode = getFormattedCode(CarouselCodeExamples.responsiveExample, 'html');
+
+  propertyIsNavigationIndicatorCode = getFormattedCode(CarouselCodeExamples.propertyIsNavigationIndicator, 'typescript');
+  propertyTotalItemsCountCode = getFormattedCode(CarouselCodeExamples.propertyTotalItemsCount, 'typescript');
+  propertyCurrentVisibleItemIndexCode = getFormattedCode(CarouselCodeExamples.propertyCurrentVisibleItemIndex, 'typescript');
+  propertyNavigationIndicatorsArrayCode = getFormattedCode(CarouselCodeExamples.propertyNavigationIndicatorsArray, 'typescript');
+
+  apiMethodsCode = getFormattedCode(CarouselCodeExamples.apiMethods, 'typescript');
+  keyboardShortcutsCode = getFormattedCode(CarouselCodeExamples.keyboardShortcuts, 'typescript');
+  touchGesturesCode = getFormattedCode(CarouselCodeExamples.touchGestures, 'typescript');
 
   constructor(
     private aiPromptService: AiPromptService