@neynar/ui 0.1.1 → 0.1.2

package/dist/components/ui/carousel.d.ts

@@ -1,30 +1,89 @@
 import * as React from "react";
 import useEmblaCarousel, { type UseEmblaCarouselType } from "embla-carousel-react";
 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 (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;
+/**
+ * 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
+ */
+declare function useCarousel(): CarouselContextProps;
 /**
  * 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, 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
@@ -44,9 +103,16 @@ type CarouselProps = {
  *
  * @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">
@@ -68,12 +134,13 @@ type CarouselProps = {
  *
  * @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">
@@ -91,47 +158,121 @@ type CarouselProps = {
  *
  * @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
@@ -139,16 +280,21 @@ type CarouselProps = {
  * @see {@link CarouselNext} Next navigation button
  * @since 1.0.0
  */
-declare function Carousel({ orientation, opts, setApi, plugins, className, children, ...props }: React.ComponentProps<"div"> & CarouselProps): import("react/jsx-runtime").JSX.Element;
+declare function Carousel({ orientation, opts, setApi, plugins, className, children, ...props }: CarouselProps & React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+/** 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
@@ -162,47 +308,75 @@ declare function Carousel({ orientation, opts, setApi, plugins, className, child
  *
  * @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
  */
-declare function CarouselContent({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+declare function CarouselContent({ className, ...props }: CarouselContentProps): import("react/jsx-runtime").JSX.Element;
+/** 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>
@@ -211,60 +385,95 @@ declare function CarouselContent({ className, ...props }: React.ComponentProps<"
  *
  * @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
  */
-declare function CarouselItem({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+declare function CarouselItem({ className, ...props }: CarouselItemProps): import("react/jsx-runtime").JSX.Element;
+/** 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>
@@ -277,9 +486,9 @@ declare 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"
  * />
@@ -287,41 +496,75 @@ declare 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
  * @see {@link Button} Underlying button component
  * @since 1.0.0
  */
-declare function CarouselPrevious({ className, variant, size, ...props }: React.ComponentProps<typeof Button>): import("react/jsx-runtime").JSX.Element;
+declare function CarouselPrevious({ className, variant, size, ...props }: CarouselPreviousProps): import("react/jsx-runtime").JSX.Element;
+/** 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>
@@ -334,9 +577,9 @@ declare function CarouselPrevious({ className, variant, size, ...props }: React.
  *
  * @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"
  * />
@@ -344,26 +587,53 @@ declare function CarouselPrevious({ className, variant, size, ...props }: React.
  *
  * @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
  * @see {@link Button} Underlying button component
  * @since 1.0.0
  */
-declare function CarouselNext({ className, variant, size, ...props }: React.ComponentProps<typeof Button>): import("react/jsx-runtime").JSX.Element;
-export { type CarouselApi, Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext, };
+declare function CarouselNext({ className, variant, size, ...props }: CarouselNextProps): import("react/jsx-runtime").JSX.Element;
+export { type CarouselApi, type CarouselProps, type CarouselContentProps, type CarouselItemProps, type CarouselPreviousProps, type CarouselNextProps, Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext, useCarousel, };
 //# sourceMappingURL=carousel.d.ts.map