@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/carousel.tsx

@@ -8,24 +8,238 @@ import { ArrowLeft, ArrowRight } from "lucide-react";
 import { cn } from "@/lib/utils";
 import { Button } from "@/components/ui/button";
 
+/** Embla Carousel API instance type for programmatic control */
 type CarouselApi = UseEmblaCarouselType[1];
+
+/** Parameters for the useEmblaCarousel hook */
 type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
+
+/** Embla Carousel configuration options */
 type CarouselOptions = UseCarouselParameters[0];
+
+/** Array of Embla Carousel plugins */
 type CarouselPlugin = UseCarouselParameters[1];
 
+/**
+ * Props for Carousel component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace embla-carousel inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type CarouselDocsProps = {
+  /**
+   * Embla Carousel configuration options
+   *
+   * Supports all Embla options including:
+   * - `active`: Enable/disable the carousel (default: true)
+   * - `align`: Slide alignment - "start", "center", "end", or custom function (default: "center")
+   * - `axis`: Scroll direction - "x" for horizontal, "y" for vertical (default: "x")
+   * - `breakpoints`: Responsive configuration object with media queries
+   * - `container`: Custom container element selector or HTMLElement
+   * - `containScroll`: Handle empty space - false, "trimSnaps", "keepSnaps" (default: "trimSnaps")
+   * - `direction`: Content direction - "ltr" or "rtl" (default: "ltr")
+   * - `dragFree`: Enable momentum scrolling (default: false)
+   * - `dragThreshold`: Drag threshold in pixels (default: 10)
+   * - `duration`: Scroll duration for API methods, 20-60 recommended (default: 25)
+   * - `inViewThreshold`: Intersection Observer threshold (default: 0)
+   * - `loop`: Enable infinite looping (default: false)
+   * - `skipSnaps`: Allow skipping snaps on vigorous drag (default: false)
+   * - `slides`: Custom slide elements selector or HTMLElement array
+   * - `slidesToScroll`: Number of slides to scroll or "auto" (default: 1)
+   * - `startIndex`: Initial scroll snap index (default: 0)
+   * - `watchDrag`: Enable drag interactions (default: true)
+   * - `watchFocus`: Enable focus-based scrolling (default: true)
+   * - `watchResize`: Enable auto-reinit on resize (default: true)
+   * - `watchSlides`: Enable auto-reinit when slides change (default: true)
+   * @default {}
+   */
+  opts?: CarouselOptions;
+
+  /**
+   * Array of Embla Carousel plugins for extended functionality
+   *
+   * Common plugins include:
+   * - `Autoplay`: Automatic slide progression
+   * - `AutoScroll`: Continuous smooth scrolling
+   * - `ClassNames`: CSS class management based on carousel state
+   * - `WheelGestures`: Mouse wheel navigation
+   * - `Fade`: Fade transition effects
+   * @default undefined
+   */
+  plugins?: CarouselPlugin;
+
+  /**
+   * Carousel orientation/layout direction
+   *
+   * - "horizontal": Default horizontal layout with left/right navigation
+   * - "vertical": Vertical layout with up/down navigation
+   * @default "horizontal"
+   */
+  orientation?: "horizontal" | "vertical";
+
+  /**
+   * Callback to receive the Embla Carousel API instance
+   *
+   * The API provides methods for programmatic control:
+   * - Navigation: `scrollNext()`, `scrollPrev()`, `scrollTo(index)`
+   * - State: `selectedScrollSnap()`, `canScrollNext()`, `canScrollPrev()`
+   * - Events: `on(event, callback)`, `off(event, callback)`
+   * - Elements: `slideNodes()`, `rootNode()`, `containerNode()`
+   * @param api - The Embla Carousel API instance
+   */
+  setApi?: (api: CarouselApi) => void;
+
+  /** Additional CSS classes for styling */
+  className?: string;
+
+  /** Carousel content and navigation elements */
+  children?: React.ReactNode;
+} & Omit<React.ComponentProps<"div">, "className" | "children" | "orientation">;
+
+/**
+ * Props for CarouselContent component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type CarouselContentDocsProps = {
+  /**
+   * Additional CSS classes for custom spacing and styling
+   *
+   * Common patterns:
+   * - Horizontal: `-ml-2 md:-ml-4` for negative margin spacing
+   * - Vertical: `-mt-4 h-[300px]` for vertical layout with fixed height
+   * - Gap control: Adjust negative margins to control slide spacing
+   */
+  className?: string;
+
+  /** CarouselItem components and other slide content */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "className" | "children">;
+
+/**
+ * Props for CarouselItem component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type CarouselItemDocsProps = {
+  /**
+   * Additional CSS classes for sizing, spacing, and styling
+   *
+   * Common sizing patterns:
+   * - `basis-full`: Full width slide (default)
+   * - `basis-1/2`: Half width (2 slides visible)
+   * - `basis-1/3`: Third width (3 slides visible)
+   * - `basis-auto`: Auto-sizing based on content
+   * - `md:basis-1/2 lg:basis-1/3`: Responsive sizing
+   *
+   * Spacing patterns:
+   * - `pl-2 md:pl-4`: Left padding (horizontal carousels)
+   * - `pt-4`: Top padding (vertical carousels)
+   */
+  className?: string;
+
+  /** Content to display within the slide */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "className" | "children">;
+
+/**
+ * Props for CarouselPrevious component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type CarouselPreviousDocsProps = {
+  /**
+   * Additional CSS classes for custom positioning and styling
+   *
+   * Default positioning:
+   * - Horizontal: `top-1/2 -left-12 -translate-y-1/2`
+   * - Vertical: `-top-12 left-1/2 -translate-x-1/2 rotate-90`
+   */
+  className?: string;
+
+  /**
+   * Button variant styling
+   * @default "outline"
+   */
+  variant?:
+    | "default"
+    | "destructive"
+    | "outline"
+    | "secondary"
+    | "ghost"
+    | "link";
+
+  /**
+   * Button size
+   * @default "icon"
+   */
+  size?: "default" | "sm" | "lg" | "icon";
+} & Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "className" | "variant" | "size"
+>;
+
+/**
+ * Props for CarouselNext component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type CarouselNextDocsProps = {
+  /**
+   * Additional CSS classes for custom positioning and styling
+   *
+   * Default positioning:
+   * - Horizontal: `top-1/2 -right-12 -translate-y-1/2`
+   * - Vertical: `-bottom-12 left-1/2 -translate-x-1/2 rotate-90`
+   */
+  className?: string;
+
+  /**
+   * Button variant styling
+   * @default "outline"
+   */
+  variant?:
+    | "default"
+    | "destructive"
+    | "outline"
+    | "secondary"
+    | "ghost"
+    | "link";
+
+  /**
+   * Button size
+   * @default "icon"
+   */
+  size?: "default" | "sm" | "lg" | "icon";
+} & Omit<
+  React.ButtonHTMLAttributes<HTMLButtonElement>,
+  "className" | "variant" | "size"
+>;
+
+/** Props for Carousel component (used in component implementation) */
 type CarouselProps = {
+  /** Embla Carousel configuration options */
   opts?: CarouselOptions;
+  /** Array of Embla Carousel plugins for extended functionality */
   plugins?: CarouselPlugin;
+  /** Carousel orientation/layout direction */
   orientation?: "horizontal" | "vertical";
+  /** Callback to receive the Embla Carousel API instance */
   setApi?: (api: CarouselApi) => void;
 };
 
+/** Props for the carousel context provider */
 type CarouselContextProps = {
+  /** Ref for the Embla carousel viewport element */
   carouselRef: ReturnType<typeof useEmblaCarousel>[0];
+  /** Embla Carousel API instance for programmatic control */
   api: ReturnType<typeof useEmblaCarousel>[1];
+  /** Function to scroll to the previous slide */
   scrollPrev: () => void;
+  /** Function to scroll to the next slide */
   scrollNext: () => void;
+  /** Whether the carousel can scroll to previous slide */
   canScrollPrev: boolean;
+  /** Whether the carousel can scroll to next slide */
   canScrollNext: boolean;
 } & CarouselProps;
 
@@ -84,15 +298,11 @@ function useCarousel() {
  *
  * The Carousel component provides a touch-friendly, keyboard-accessible way to
  * browse through multiple items. Built on Embla Carousel, it supports various
- * configurations including autoplay, loop, drag scrolling, and both horizontal
- * and vertical orientations.
+ * configurations including autoplay, loop, drag scrolling, infinite scroll,
+ * momentum scrolling, and both horizontal and vertical orientations.
  *
- * @param opts - Embla Carousel configuration options (align, loop, etc.)
- * @param plugins - Array of Embla Carousel plugins (autoplay, etc.)
- * @param orientation - Layout direction: "horizontal" or "vertical" (default: "horizontal")
- * @param setApi - Callback to receive the carousel API instance
- * @param className - Additional CSS classes
- * @param children - Carousel content (typically CarouselContent and navigation buttons)
+ * Features include responsive breakpoints, plugin system, smooth animations,
+ * focus management, RTL support, and extensive customization options.
  *
  * @example
  * ```tsx
@@ -112,9 +322,16 @@ function useCarousel() {
  *
  * @example
  * ```tsx
- * // Multi-item responsive carousel
+ * // Multi-item responsive carousel with custom spacing
  * <Carousel
- *   opts={{ align: "start", loop: true }}
+ *   opts={{
+ *     align: "start",
+ *     loop: true,
+ *     slidesToScroll: "auto",
+ *     breakpoints: {
+ *       "(min-width: 768px)": { slidesToScroll: 2 }
+ *     }
+ *   }}
  *   className="w-full"
  * >
  *   <CarouselContent className="-ml-2 md:-ml-4">
@@ -136,12 +353,13 @@ function useCarousel() {
  *
  * @example
  * ```tsx
- * // Vertical carousel with autoplay
+ * // Vertical carousel with autoplay plugin
  * import Autoplay from "embla-carousel-autoplay";
  *
  * <Carousel
  *   orientation="vertical"
- *   plugins={[Autoplay({ delay: 3000, stopOnInteraction: true })]}
+ *   opts={{ loop: true, align: "center" }}
+ *   plugins={[Autoplay({ delay: 3000, stopOnInteraction: true, stopOnMouseEnter: true })]}
  *   className="h-[400px]"
  * >
  *   <CarouselContent className="h-full">
@@ -159,47 +377,121 @@ function useCarousel() {
  *
  * @example
  * ```tsx
- * // Controlled carousel with custom indicators
+ * // Controlled carousel with custom indicators and API access
+ * import { useState, useEffect } from "react";
+ *
  * function ControlledCarousel() {
  *   const [api, setApi] = useState<CarouselApi>();
  *   const [current, setCurrent] = useState(0);
+ *   const [count, setCount] = useState(0);
  *
  *   useEffect(() => {
  *     if (!api) return;
- *     setCurrent(api.selectedScrollSnap());
- *     api.on('select', () => setCurrent(api.selectedScrollSnap()));
+ *
+ *     setCount(api.scrollSnapList().length);
+ *     setCurrent(api.selectedScrollSnap() + 1);
+ *
+ *     api.on('select', () => {
+ *       setCurrent(api.selectedScrollSnap() + 1);
+ *     });
  *   }, [api]);
  *
  *   return (
- *     <div>
- *       <Carousel setApi={setApi}>
- *         <CarouselContent>...</CarouselContent>
+ *     <div className="space-y-4">
+ *       <Carousel setApi={setApi} opts={{ loop: true }}>
+ *         <CarouselContent>
+ *           {slides.map((slide, index) => (
+ *             <CarouselItem key={index}>{slide.content}</CarouselItem>
+ *           ))}
+ *         </CarouselContent>
+ *         <CarouselPrevious />
+ *         <CarouselNext />
  *       </Carousel>
- *       <div className="flex justify-center gap-2 mt-4">
- *         {Array.from({ length: 5 }).map((_, i) => (
+ *
+ *       // Custom indicators
+ *       <div className="flex justify-center gap-2">
+ *         {Array.from({ length: count }).map((_, i) => (
  *           <button
  *             key={i}
- *             className={current === i ? "bg-primary" : "bg-muted"}
+ *             className={cn(
+ *               "w-2 h-2 rounded-full transition-colors",
+ *               current === i + 1 ? "bg-primary" : "bg-muted"
+ *             )}
  *             onClick={() => api?.scrollTo(i)}
  *           />
  *         ))}
  *       </div>
+ *
+ *       <div className="text-center text-sm text-muted-foreground">
+ *         Slide {current} of {count}
+ *       </div>
  *     </div>
  *   );
  * }
  * ```
  *
+ * @example
+ * ```tsx
+ * // Momentum scrolling carousel with drag-free mode
+ * <Carousel
+ *   opts={{
+ *     dragFree: true,
+ *     containScroll: false,
+ *     skipSnaps: true
+ *   }}
+ *   className="w-full"
+ * >
+ *   <CarouselContent>
+ *     {items.map((item, index) => (
+ *       <CarouselItem key={index} className="basis-auto">
+ *         <div className="w-32 h-32 bg-muted rounded-lg" />
+ *       </CarouselItem>
+ *     ))}
+ *   </CarouselContent>
+ * </Carousel>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Breakpoint-responsive carousel that disables on larger screens
+ * <Carousel
+ *   opts={{
+ *     active: true,
+ *     breakpoints: {
+ *       "(min-width: 768px)": { active: false }
+ *     }
+ *   }}
+ *   className="md:hidden"
+ * >
+ *   <CarouselContent>
+ *     {mobileItems.map((item, index) => (
+ *       <CarouselItem key={index}>{item}</CarouselItem>
+ *     ))}
+ *   </CarouselContent>
+ *   <CarouselPrevious />
+ *   <CarouselNext />
+ * </Carousel>
+ * ```
+ *
  * @accessibility
- * - Keyboard navigation with arrow keys and tab focus
- * - Touch/swipe gestures and mouse drag support
- * - Screen reader announcements for slide changes
- * - ARIA roles and labels for navigation elements
- * - Focus management and visible focus indicators
- * - Respects reduced motion preferences
- * - RTL layout support
+ * - **Keyboard Navigation**: Arrow keys for slide navigation, Tab for focus management
+ * - **Touch/Drag Support**: Multi-touch gestures, mouse drag, momentum scrolling
+ * - **Screen Reader**: ARIA roles, labels, and announcements for slide changes
+ * - **Focus Management**: Automatic focus handling, visible focus indicators
+ * - **Motion**: Respects `prefers-reduced-motion` for accessibility
+ * - **RTL Support**: Right-to-left layout support with `direction: "rtl"` option
+ * - **High Contrast**: Proper color contrast for navigation elements
+ *
+ * **Keyboard Shortcuts:**
+ * - `←/→` or `↑/↓`: Navigate slides (based on orientation)
+ * - `Home`: Go to first slide
+ * - `End`: Go to last slide
+ * - `Tab`: Focus navigation elements
  *
  * @see {@link https://ui.shadcn.com/docs/components/carousel} shadcn/ui carousel documentation
  * @see {@link https://www.embla-carousel.com/} Embla Carousel documentation
+ * @see {@link https://www.embla-carousel.com/api/options/} Embla options reference
+ * @see {@link https://www.embla-carousel.com/plugins/} Available Embla plugins
  * @see {@link useCarousel} Hook for accessing carousel controls
  * @see {@link CarouselContent} Container for carousel items
  * @see {@link CarouselItem} Individual carousel slide
@@ -215,7 +507,7 @@ function Carousel({
   className,
   children,
   ...props
-}: React.ComponentProps<"div"> & CarouselProps) {
+}: CarouselProps & React.ComponentProps<"div">) {
   const [carouselRef, api] = useEmblaCarousel(
     {
       ...opts,
@@ -294,15 +586,21 @@ function Carousel({
   );
 }
 
+/** Props for CarouselContent component (used in component implementation) */
+type CarouselContentProps = {
+  /** Additional CSS classes for custom spacing and styling */
+  className?: string;
+  /** CarouselItem components and other slide content */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "className" | "children">;
+
 /**
  * Container component for carousel items that handles the scrolling viewport
  *
  * Wraps all carousel items and manages the scrollable area. This component
- * must be a direct child of Carousel and handles orientation-specific layouts
- * and overflow behavior.
- *
- * @param className - Additional CSS classes for custom spacing and styling
- * @param children - CarouselItem components
+ * must be a direct child of Carousel and handles orientation-specific layouts,
+ * overflow behavior, and slide spacing. The outer div provides overflow clipping
+ * while the inner div contains the flex layout for slides.
  *
  * @example
  * ```tsx
@@ -316,32 +614,55 @@ function Carousel({
  *
  * @example
  * ```tsx
- * // With custom spacing (horizontal)
+ * // Multi-item carousel with responsive spacing
  * <CarouselContent className="-ml-2 md:-ml-4">
- *   <CarouselItem className="pl-2 md:pl-4">Slide 1</CarouselItem>
- *   <CarouselItem className="pl-2 md:pl-4">Slide 2</CarouselItem>
+ *   <CarouselItem className="pl-2 md:pl-4 md:basis-1/2 lg:basis-1/3">
+ *     <Card>Product 1</Card>
+ *   </CarouselItem>
+ *   <CarouselItem className="pl-2 md:pl-4 md:basis-1/2 lg:basis-1/3">
+ *     <Card>Product 2</Card>
+ *   </CarouselItem>
  * </CarouselContent>
  * ```
  *
  * @example
  * ```tsx
- * // Vertical orientation spacing
+ * // Vertical orientation with custom height
  * <CarouselContent className="-mt-4 h-[300px]">
- *   <CarouselItem className="pt-4">Slide 1</CarouselItem>
- *   <CarouselItem className="pt-4">Slide 2</CarouselItem>
+ *   <CarouselItem className="pt-4 basis-1/2">
+ *     <div className="h-full bg-muted rounded-lg">Slide 1</div>
+ *   </CarouselItem>
+ *   <CarouselItem className="pt-4 basis-1/2">
+ *     <div className="h-full bg-muted rounded-lg">Slide 2</div>
+ *   </CarouselItem>
+ * </CarouselContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom slide spacing with CSS variables
+ * <CarouselContent
+ *   className="-ml-4"
+ *   style={{ '--slide-spacing': '1rem' } as React.CSSProperties}
+ * >
+ *   <CarouselItem className="pl-4">
+ *     Content with custom spacing
+ *   </CarouselItem>
  * </CarouselContent>
  * ```
  *
  * @accessibility
  * - Provides scrollable container with proper overflow handling
  * - Maintains responsive layout for horizontal/vertical orientations
- * - Works with screen readers for content navigation
+ * - Supports screen reader navigation through slide content
+ * - Preserves focus management within slides
+ * - Uses semantic HTML structure for assistive technologies
  *
  * @see {@link Carousel} Main carousel component
  * @see {@link CarouselItem} Individual carousel slides
  * @since 1.0.0
  */
-function CarouselContent({ className, ...props }: React.ComponentProps<"div">) {
+function CarouselContent({ className, ...props }: CarouselContentProps) {
   const { carouselRef, orientation } = useCarousel();
 
   return (
@@ -362,21 +683,27 @@ function CarouselContent({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** Props for CarouselItem component (used in component implementation) */
+type CarouselItemProps = {
+  /** Additional CSS classes for sizing, spacing, and styling */
+  className?: string;
+  /** Content to display within the slide */
+  children?: React.ReactNode;
+} & Omit<React.HTMLAttributes<HTMLDivElement>, "className" | "children">;
+
 /**
  * Individual slide/item component within the carousel
  *
  * Represents a single slide in the carousel that can contain any content.
  * Automatically handles sizing, spacing, and orientation-specific layouts
- * based on the parent carousel configuration.
- *
- * @param className - Additional CSS classes for sizing (basis-*) and spacing
- * @param children - Content to display within the slide
+ * based on the parent carousel configuration. Each slide is a flex item
+ * with configurable basis for responsive layouts.
  *
  * @example
  * ```tsx
  * // Basic slide with content
  * <CarouselItem>
- *   <div className="p-6">
+ *   <div className="p-6 bg-muted rounded-lg">
  *     <h3 className="text-lg font-semibold">Slide Title</h3>
  *     <p className="text-muted-foreground">Slide description</p>
  *   </div>
@@ -385,46 +712,74 @@ function CarouselContent({ className, ...props }: React.ComponentProps<"div">) {
  *
  * @example
  * ```tsx
- * // Card-based slide
+ * // Card-based slide with structured content
  * <CarouselItem>
- *   <Card>
+ *   <Card className="h-full">
  *     <CardHeader>
  *       <CardTitle>Product Name</CardTitle>
+ *       <CardDescription>Product category</CardDescription>
  *     </CardHeader>
  *     <CardContent>
- *       <img src="product.jpg" alt="Product" className="w-full" />
- *       <p className="mt-2">$99.99</p>
+ *       <img src="product.jpg" alt="Product" className="w-full aspect-square object-cover" />
+ *       <p className="mt-2 text-2xl font-bold">$99.99</p>
  *     </CardContent>
+ *     <CardFooter>
+ *       <Button className="w-full">Add to Cart</Button>
+ *     </CardFooter>
  *   </Card>
  * </CarouselItem>
  * ```
  *
  * @example
  * ```tsx
- * // Responsive sizing - multiple items visible
- * <CarouselItem className="md:basis-1/2 lg:basis-1/3">
- *   <div className="aspect-square bg-muted rounded-lg" />
+ * // Responsive multi-item carousel
+ * <CarouselItem className="pl-4 basis-full sm:basis-1/2 lg:basis-1/3">
+ *   <div className="aspect-square bg-gradient-to-br from-blue-400 to-purple-600 rounded-lg p-6 text-white">
+ *     <h4 className="font-semibold">Feature {index + 1}</h4>
+ *     <p className="text-sm opacity-90">Description text</p>
+ *   </div>
+ * </CarouselItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Auto-sized slides for variable content
+ * <CarouselItem className="basis-auto">
+ *   <Badge variant="secondary" className="text-nowrap px-4 py-2">
+ *     {tag.label}
+ *   </Badge>
  * </CarouselItem>
  * ```
  *
  * @example
  * ```tsx
- * // Custom sizing with fixed width
+ * // Image gallery slide with aspect ratio
  * <CarouselItem className="basis-4/5">
- *   <div className="w-full h-48 bg-gradient-to-r from-blue-500 to-purple-600" />
+ *   <div className="relative aspect-video bg-muted rounded-lg overflow-hidden">
+ *     <img
+ *       src={image.src}
+ *       alt={image.alt}
+ *       className="object-cover w-full h-full"
+ *     />
+ *     <div className="absolute inset-0 bg-black/20 flex items-end p-4">
+ *       <h5 className="text-white font-medium">{image.title}</h5>
+ *     </div>
+ *   </div>
  * </CarouselItem>
  * ```
  *
  * @accessibility
- * - Labeled as a slide with proper ARIA role for screen readers
- * - Maintains focus behavior and keyboard navigation
- * - Preserves content structure for assistive technologies
+ * - **ARIA Role**: Labeled as "slide" with proper role for screen readers
+ * - **Focus Management**: Maintains focus behavior and keyboard navigation
+ * - **Content Structure**: Preserves semantic structure for assistive technologies
+ * - **Interactive Elements**: Supports focusable elements within slides
+ * - **Screen Reader**: Announces slide position and content appropriately
  *
  * @see {@link Carousel} Main carousel component
  * @see {@link CarouselContent} Container for carousel items
  * @since 1.0.0
  */
-function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
+function CarouselItem({ className, ...props }: CarouselItemProps) {
   const { orientation } = useCarousel();
 
   return (
@@ -442,20 +797,28 @@ function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
   );
 }
 
+/** Props for CarouselPrevious component (used in component implementation) */
+type CarouselPreviousProps = {
+  /** Additional CSS classes for custom positioning and styling */
+  className?: string;
+  /** Button variant styling */
+  variant?: React.ComponentProps<typeof Button>["variant"];
+  /** Button size */
+  size?: React.ComponentProps<typeof Button>["size"];
+} & Omit<React.ComponentProps<typeof Button>, "className" | "variant" | "size">;
+
 /**
  * Navigation button to go to the previous carousel slide
  *
  * Renders a previous navigation button that automatically handles disabled
- * states when at the beginning of the carousel. Supports both horizontal
- * and vertical orientations with appropriate positioning.
- *
- * @param className - Additional CSS classes for custom positioning and styling
- * @param variant - Button variant (default: "outline")
- * @param size - Button size (default: "icon")
+ * states when at the beginning of the carousel (unless loop is enabled).
+ * Supports both horizontal and vertical orientations with appropriate
+ * positioning and icon rotation. Integrates with the carousel context
+ * to provide seamless navigation.
  *
  * @example
  * ```tsx
- * // Basic usage
+ * // Basic usage with default styling
  * <Carousel>
  *   <CarouselContent>
  *     <CarouselItem>Slide 1</CarouselItem>
@@ -468,9 +831,9 @@ function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
  *
  * @example
  * ```tsx
- * // Custom styling
+ * // Custom positioned button
  * <CarouselPrevious
- *   className="-left-8 bg-background shadow-md"
+ *   className="-left-8 bg-background shadow-md hover:shadow-lg"
  *   variant="ghost"
  *   size="sm"
  * />
@@ -478,20 +841,47 @@ function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
  *
  * @example
  * ```tsx
- * // Vertical carousel positioning
- * <Carousel orientation="vertical">
+ * // Vertical carousel with rotated icons
+ * <Carousel orientation="vertical" className="h-[400px]">
  *   <CarouselContent>...</CarouselContent>
- *   <CarouselPrevious />
- *   <CarouselNext />
+ *   <CarouselPrevious className="-top-8" />
+ *   <CarouselNext className="-bottom-8" />
  * </Carousel>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Inside carousel bounds positioning
+ * <div className="relative">
+ *   <Carousel>
+ *     <CarouselContent>...</CarouselContent>
+ *     <CarouselPrevious className="absolute left-4 top-1/2 -translate-y-1/2 z-10" />
+ *     <CarouselNext className="absolute right-4 top-1/2 -translate-y-1/2 z-10" />
+ *   </Carousel>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom button content and accessibility
+ * <CarouselPrevious
+ *   variant="secondary"
+ *   className="w-auto px-4"
+ *   aria-label="Go to previous product"
+ * >
+ *   <ArrowLeft className="w-4 h-4 mr-2" />
+ *   Previous
+ * </CarouselPrevious>
+ * ```
+ *
  * @accessibility
- * - Keyboard accessible with proper focus management
- * - Screen reader label "Previous slide" for context
- * - Automatically disabled when cannot scroll further
- * - High contrast focus indicators
- * - Supports reduced motion preferences
+ * - **Keyboard Navigation**: Accessible via Tab and Enter/Space
+ * - **Screen Reader**: Built-in "Previous slide" label with sr-only text
+ * - **Disabled State**: Automatically disabled when cannot scroll further
+ * - **Focus Indicators**: High contrast focus ring for keyboard navigation
+ * - **Motion**: Respects `prefers-reduced-motion` for animations
+ * - **Touch**: Large enough touch target (44px minimum) for mobile accessibility
+ * - **Icon**: ArrowLeft icon rotated appropriately for vertical orientation
  *
  * @see {@link Carousel} Main carousel component
  * @see {@link CarouselNext} Next navigation button
@@ -503,7 +893,7 @@ function CarouselPrevious({
   variant = "outline",
   size = "icon",
   ...props
-}: React.ComponentProps<typeof Button>) {
+}: CarouselPreviousProps) {
   const { orientation, scrollPrev, canScrollPrev } = useCarousel();
 
   return (
@@ -528,20 +918,28 @@ function CarouselPrevious({
   );
 }
 
+/** Props for CarouselNext component (used in component implementation) */
+type CarouselNextProps = {
+  /** Additional CSS classes for custom positioning and styling */
+  className?: string;
+  /** Button variant styling */
+  variant?: React.ComponentProps<typeof Button>["variant"];
+  /** Button size */
+  size?: React.ComponentProps<typeof Button>["size"];
+} & Omit<React.ComponentProps<typeof Button>, "className" | "variant" | "size">;
+
 /**
  * Navigation button to go to the next carousel slide
  *
  * Renders a next navigation button that automatically handles disabled
- * states when at the end of the carousel. Supports both horizontal
- * and vertical orientations with appropriate positioning.
- *
- * @param className - Additional CSS classes for custom positioning and styling
- * @param variant - Button variant (default: "outline")
- * @param size - Button size (default: "icon")
+ * states when at the end of the carousel (unless loop is enabled).
+ * Supports both horizontal and vertical orientations with appropriate
+ * positioning and icon rotation. Integrates with the carousel context
+ * to provide seamless navigation.
  *
  * @example
  * ```tsx
- * // Basic usage
+ * // Basic usage with default styling
  * <Carousel>
  *   <CarouselContent>
  *     <CarouselItem>Slide 1</CarouselItem>
@@ -554,9 +952,9 @@ function CarouselPrevious({
  *
  * @example
  * ```tsx
- * // Custom styling
+ * // Custom positioned button
  * <CarouselNext
- *   className="-right-8 bg-background shadow-md"
+ *   className="-right-8 bg-background shadow-md hover:shadow-lg"
  *   variant="ghost"
  *   size="sm"
  * />
@@ -564,20 +962,47 @@ function CarouselPrevious({
  *
  * @example
  * ```tsx
- * // Vertical carousel positioning
- * <Carousel orientation="vertical">
+ * // Vertical carousel with rotated icons
+ * <Carousel orientation="vertical" className="h-[400px]">
  *   <CarouselContent>...</CarouselContent>
- *   <CarouselPrevious />
- *   <CarouselNext />
+ *   <CarouselPrevious className="-top-8" />
+ *   <CarouselNext className="-bottom-8" />
  * </Carousel>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Inside carousel bounds positioning
+ * <div className="relative">
+ *   <Carousel>
+ *     <CarouselContent>...</CarouselContent>
+ *     <CarouselPrevious className="absolute left-4 top-1/2 -translate-y-1/2 z-10" />
+ *     <CarouselNext className="absolute right-4 top-1/2 -translate-y-1/2 z-10" />
+ *   </Carousel>
+ * </div>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom button content and accessibility
+ * <CarouselNext
+ *   variant="secondary"
+ *   className="w-auto px-4"
+ *   aria-label="Go to next product"
+ * >
+ *   Next
+ *   <ArrowRight className="w-4 h-4 ml-2" />
+ * </CarouselNext>
+ * ```
+ *
  * @accessibility
- * - Keyboard accessible with proper focus management
- * - Screen reader label "Next slide" for context
- * - Automatically disabled when cannot scroll further
- * - High contrast focus indicators
- * - Supports reduced motion preferences
+ * - **Keyboard Navigation**: Accessible via Tab and Enter/Space
+ * - **Screen Reader**: Built-in "Next slide" label with sr-only text
+ * - **Disabled State**: Automatically disabled when cannot scroll further
+ * - **Focus Indicators**: High contrast focus ring for keyboard navigation
+ * - **Motion**: Respects `prefers-reduced-motion` for animations
+ * - **Touch**: Large enough touch target (44px minimum) for mobile accessibility
+ * - **Icon**: ArrowRight icon rotated appropriately for vertical orientation
  *
  * @see {@link Carousel} Main carousel component
  * @see {@link CarouselPrevious} Previous navigation button
@@ -589,7 +1014,7 @@ function CarouselNext({
   variant = "outline",
   size = "icon",
   ...props
-}: React.ComponentProps<typeof Button>) {
+}: CarouselNextProps) {
   const { orientation, scrollNext, canScrollNext } = useCarousel();
 
   return (
@@ -616,9 +1041,15 @@ function CarouselNext({
 
 export {
   type CarouselApi,
+  type CarouselProps,
+  type CarouselContentProps,
+  type CarouselItemProps,
+  type CarouselPreviousProps,
+  type CarouselNextProps,
   Carousel,
   CarouselContent,
   CarouselItem,
   CarouselPrevious,
   CarouselNext,
+  useCarousel,
 };