@neynar/ui 0.3.1 → 0.5.0

package/src/components/ui/carousel.tsx

@@ -1,287 +1,43 @@
+"use client";
+
 import * as React from "react";
-import { useCallback } from "react";
 import useEmblaCarousel, {
   type UseEmblaCarouselType,
 } from "embla-carousel-react";
-import { ArrowLeft, ArrowRight } from "lucide-react";
 
 import { cn } from "@/lib/utils";
 import { Button } from "@/components/ui/button";
+import { ChevronLeftIcon, ChevronRightIcon } from "lucide-react";
 
-/** 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 {}
-   */
+type CarouselProps = React.ComponentProps<"div"> & {
+  /** Embla carousel options (loop, align, slidesToScroll, etc.) */
   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
-   */
+  /** Embla carousel plugins */
   plugins?: CarouselPlugin;
-
-  /**
-   * Carousel orientation/layout direction
-   *
-   * - "horizontal": Default horizontal layout with left/right navigation
-   * - "vertical": Vertical layout with up/down navigation
-   * @default "horizontal"
-   */
+  /** Carousel scroll direction. @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 */
+  /** Callback to receive the carousel API instance for programmatic control */
   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;
 
 const CarouselContext = React.createContext<CarouselContextProps | null>(null);
 
 /**
- * Hook to access carousel context and controls
- *
- * Must be used within a Carousel component. Provides access to the carousel
- * API and navigation methods for building custom carousel interactions.
- *
- * @returns Carousel context containing API, navigation controls, and state
- * @throws Error when used outside of Carousel component
- *
- * @example
- * ```tsx
- * function CarouselDots() {
- *   const { api, scrollNext, canScrollNext } = useCarousel();
- *   const [current, setCurrent] = useState(0);
- *
- *   useEffect(() => {
- *     if (!api) return;
- *     setCurrent(api.selectedScrollSnap());
- *     api.on('select', () => setCurrent(api.selectedScrollSnap()));
- *   }, [api]);
- *
- *   return (
- *     <div className="flex gap-2">
- *       {Array.from({ length: 5 }).map((_, i) => (
- *         <button
- *           key={i}
- *           className={current === i ? "active" : ""}
- *           onClick={() => api?.scrollTo(i)}
- *         />
- *       ))}
- *     </div>
- *   );
- * }
- * ```
- *
- * @see {@link Carousel} - Main carousel component
- * @since 1.0.0
+ * Hook to access carousel context. Must be used within a Carousel component.
  */
 function useCarousel() {
   const context = React.useContext(CarouselContext);
@@ -294,210 +50,8 @@ function useCarousel() {
 }
 
 /**
- * A responsive carousel/slider component for content presentation
- *
- * 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, infinite scroll,
- * momentum scrolling, and both horizontal and vertical orientations.
- *
- * Features include responsive breakpoints, plugin system, smooth animations,
- * focus management, RTL support, and extensive customization options.
- *
- * @example
- * ```tsx
- * // Basic image carousel
- * <Carousel className="w-full max-w-xs">
- *   <CarouselContent>
- *     {images.map((src, index) => (
- *       <CarouselItem key={index}>
- *         <img src={src} alt={`Slide ${index + 1}`} className="w-full" />
- *       </CarouselItem>
- *     ))}
- *   </CarouselContent>
- *   <CarouselPrevious />
- *   <CarouselNext />
- * </Carousel>
- * ```
- *
- * @example
- * ```tsx
- * // Multi-item responsive carousel with custom spacing
- * <Carousel
- *   opts={{
- *     align: "start",
- *     loop: true,
- *     slidesToScroll: "auto",
- *     breakpoints: {
- *       "(min-width: 768px)": { slidesToScroll: 2 }
- *     }
- *   }}
- *   className="w-full"
- * >
- *   <CarouselContent className="-ml-2 md:-ml-4">
- *     {products.map((product, index) => (
- *       <CarouselItem key={index} className="pl-2 md:pl-4 md:basis-1/2 lg:basis-1/3">
- *         <Card>
- *           <CardContent className="p-4">
- *             <h3>{product.name}</h3>
- *             <p>{product.price}</p>
- *           </CardContent>
- *         </Card>
- *       </CarouselItem>
- *     ))}
- *   </CarouselContent>
- *   <CarouselPrevious />
- *   <CarouselNext />
- * </Carousel>
- * ```
- *
- * @example
- * ```tsx
- * // Vertical carousel with autoplay plugin
- * import Autoplay from "embla-carousel-autoplay";
- *
- * <Carousel
- *   orientation="vertical"
- *   opts={{ loop: true, align: "center" }}
- *   plugins={[Autoplay({ delay: 3000, stopOnInteraction: true, stopOnMouseEnter: true })]}
- *   className="h-[400px]"
- * >
- *   <CarouselContent className="h-full">
- *     {testimonials.map((testimonial, index) => (
- *       <CarouselItem key={index} className="basis-1/2">
- *         <div className="p-6">
- *           <blockquote>{testimonial.quote}</blockquote>
- *           <cite>{testimonial.author}</cite>
- *         </div>
- *       </CarouselItem>
- *     ))}
- *   </CarouselContent>
- * </Carousel>
- * ```
- *
- * @example
- * ```tsx
- * // 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;
- *
- *     setCount(api.scrollSnapList().length);
- *     setCurrent(api.selectedScrollSnap() + 1);
- *
- *     api.on('select', () => {
- *       setCurrent(api.selectedScrollSnap() + 1);
- *     });
- *   }, [api]);
- *
- *   return (
- *     <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>
- *
- *       // Custom indicators
- *       <div className="flex justify-center gap-2">
- *         {Array.from({ length: count }).map((_, i) => (
- *           <button
- *             key={i}
- *             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**: 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
- * @see {@link CarouselPrevious} Previous navigation button
- * @see {@link CarouselNext} Next navigation button
- * @since 1.0.0
+ * Carousel root component. Provides context and manages scroll state.
+ * Supports both horizontal and vertical orientations with keyboard navigation.
  */
 function Carousel({
   orientation = "horizontal",
@@ -507,7 +61,7 @@ function Carousel({
   className,
   children,
   ...props
-}: CarouselProps & React.ComponentProps<"div">) {
+}: CarouselProps) {
   const [carouselRef, api] = useEmblaCarousel(
     {
       ...opts,
@@ -518,29 +72,32 @@ function Carousel({
   const [canScrollPrev, setCanScrollPrev] = React.useState(false);
   const [canScrollNext, setCanScrollNext] = React.useState(false);
 
-  const onSelect = useCallback((api: CarouselApi) => {
+  const onSelect = React.useCallback((api: CarouselApi) => {
     if (!api) return;
     setCanScrollPrev(api.canScrollPrev());
     setCanScrollNext(api.canScrollNext());
   }, []);
 
-  const scrollPrev = () => {
+  const scrollPrev = React.useCallback(() => {
     api?.scrollPrev();
-  };
+  }, [api]);
 
-  const scrollNext = () => {
+  const scrollNext = React.useCallback(() => {
     api?.scrollNext();
-  };
-
-  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
-    if (event.key === "ArrowLeft") {
-      event.preventDefault();
-      scrollPrev();
-    } else if (event.key === "ArrowRight") {
-      event.preventDefault();
-      scrollNext();
-    }
-  };
+  }, [api]);
+
+  const handleKeyDown = React.useCallback(
+    (event: React.KeyboardEvent<HTMLDivElement>) => {
+      if (event.key === "ArrowLeft") {
+        event.preventDefault();
+        scrollPrev();
+      } else if (event.key === "ArrowRight") {
+        event.preventDefault();
+        scrollNext();
+      }
+    },
+    [scrollPrev, scrollNext],
+  );
 
   React.useEffect(() => {
     if (!api || !setApi) return;
@@ -586,81 +143,10 @@ 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">;
+type CarouselContentProps = React.ComponentProps<"div">;
 
 /**
- * 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,
- * overflow behavior, and slide spacing. The outer div provides overflow clipping
- * while the inner div contains the flex layout for slides.
- *
- * @example
- * ```tsx
- * // Basic usage
- * <CarouselContent>
- *   <CarouselItem>Slide 1</CarouselItem>
- *   <CarouselItem>Slide 2</CarouselItem>
- *   <CarouselItem>Slide 3</CarouselItem>
- * </CarouselContent>
- * ```
- *
- * @example
- * ```tsx
- * // Multi-item carousel with responsive spacing
- * <CarouselContent className="-ml-2 md:-ml-4">
- *   <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 with custom height
- * <CarouselContent className="-mt-4 h-[300px]">
- *   <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
- * - 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
+ * Container for carousel items. Handles overflow and flex layout.
  */
 function CarouselContent({ className, ...props }: CarouselContentProps) {
   const { carouselRef, orientation } = useCarousel();
@@ -683,101 +169,10 @@ function CarouselContent({ className, ...props }: CarouselContentProps) {
   );
 }
 
-/** 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">;
+type CarouselItemProps = React.ComponentProps<"div">;
 
 /**
- * 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. Each slide is a flex item
- * with configurable basis for responsive layouts.
- *
- * @example
- * ```tsx
- * // Basic slide with content
- * <CarouselItem>
- *   <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>
- * </CarouselItem>
- * ```
- *
- * @example
- * ```tsx
- * // Card-based slide with structured content
- * <CarouselItem>
- *   <Card className="h-full">
- *     <CardHeader>
- *       <CardTitle>Product Name</CardTitle>
- *       <CardDescription>Product category</CardDescription>
- *     </CardHeader>
- *     <CardContent>
- *       <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 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
- * // Image gallery slide with aspect ratio
- * <CarouselItem className="basis-4/5">
- *   <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
- * - **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
+ * Individual carousel slide. Use `basis-*` classes to control items per view.
  */
 function CarouselItem({ className, ...props }: CarouselItemProps) {
   const { orientation } = useCarousel();
@@ -797,101 +192,15 @@ function CarouselItem({ className, ...props }: CarouselItemProps) {
   );
 }
 
-/** 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">;
+type CarouselPreviousProps = React.ComponentProps<typeof Button>;
 
 /**
- * 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 (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 with default styling
- * <Carousel>
- *   <CarouselContent>
- *     <CarouselItem>Slide 1</CarouselItem>
- *     <CarouselItem>Slide 2</CarouselItem>
- *   </CarouselContent>
- *   <CarouselPrevious />
- *   <CarouselNext />
- * </Carousel>
- * ```
- *
- * @example
- * ```tsx
- * // Custom positioned button
- * <CarouselPrevious
- *   className="-left-8 bg-background shadow-md hover:shadow-lg"
- *   variant="ghost"
- *   size="sm"
- * />
- * ```
- *
- * @example
- * ```tsx
- * // Vertical carousel with rotated icons
- * <Carousel orientation="vertical" className="h-[400px]">
- *   <CarouselContent>...</CarouselContent>
- *   <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 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
- * @see {@link Button} Underlying button component
- * @since 1.0.0
+ * Button to navigate to previous slide. Automatically disabled when at start (unless loop is enabled).
  */
 function CarouselPrevious({
   className,
   variant = "outline",
-  size = "icon",
+  size = "icon-sm",
   ...props
 }: CarouselPreviousProps) {
   const { orientation, scrollPrev, canScrollPrev } = useCarousel();
@@ -902,7 +211,7 @@ function CarouselPrevious({
       variant={variant}
       size={size}
       className={cn(
-        "absolute size-8 rounded-full",
+        "rounded-full absolute touch-manipulation",
         orientation === "horizontal"
           ? "top-1/2 -left-12 -translate-y-1/2"
           : "-top-12 left-1/2 -translate-x-1/2 rotate-90",
@@ -912,107 +221,21 @@ function CarouselPrevious({
       onClick={scrollPrev}
       {...props}
     >
-      <ArrowLeft />
+      <ChevronLeftIcon />
       <span className="sr-only">Previous slide</span>
     </Button>
   );
 }
 
-/** 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">;
+type CarouselNextProps = React.ComponentProps<typeof Button>;
 
 /**
- * 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 (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 with default styling
- * <Carousel>
- *   <CarouselContent>
- *     <CarouselItem>Slide 1</CarouselItem>
- *     <CarouselItem>Slide 2</CarouselItem>
- *   </CarouselContent>
- *   <CarouselPrevious />
- *   <CarouselNext />
- * </Carousel>
- * ```
- *
- * @example
- * ```tsx
- * // Custom positioned button
- * <CarouselNext
- *   className="-right-8 bg-background shadow-md hover:shadow-lg"
- *   variant="ghost"
- *   size="sm"
- * />
- * ```
- *
- * @example
- * ```tsx
- * // Vertical carousel with rotated icons
- * <Carousel orientation="vertical" className="h-[400px]">
- *   <CarouselContent>...</CarouselContent>
- *   <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 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
- * @see {@link Button} Underlying button component
- * @since 1.0.0
+ * Button to navigate to next slide. Automatically disabled when at end (unless loop is enabled).
  */
 function CarouselNext({
   className,
   variant = "outline",
-  size = "icon",
+  size = "icon-sm",
   ...props
 }: CarouselNextProps) {
   const { orientation, scrollNext, canScrollNext } = useCarousel();
@@ -1023,7 +246,7 @@ function CarouselNext({
       variant={variant}
       size={size}
       className={cn(
-        "absolute size-8 rounded-full",
+        "rounded-full absolute touch-manipulation",
         orientation === "horizontal"
           ? "top-1/2 -right-12 -translate-y-1/2"
           : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90",
@@ -1033,7 +256,7 @@ function CarouselNext({
       onClick={scrollNext}
       {...props}
     >
-      <ArrowRight />
+      <ChevronRightIcon />
       <span className="sr-only">Next slide</span>
     </Button>
   );