@neynar/ui 0.1.1

package/src/components/ui/carousel.tsx

@@ -0,0 +1,624 @@
+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";
+
+type CarouselApi = UseEmblaCarouselType[1];
+type UseCarouselParameters = Parameters<typeof useEmblaCarousel>;
+type CarouselOptions = UseCarouselParameters[0];
+type CarouselPlugin = UseCarouselParameters[1];
+
+type CarouselProps = {
+  opts?: CarouselOptions;
+  plugins?: CarouselPlugin;
+  orientation?: "horizontal" | "vertical";
+  setApi?: (api: CarouselApi) => void;
+};
+
+type CarouselContextProps = {
+  carouselRef: ReturnType<typeof useEmblaCarousel>[0];
+  api: ReturnType<typeof useEmblaCarousel>[1];
+  scrollPrev: () => void;
+  scrollNext: () => void;
+  canScrollPrev: boolean;
+  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
+ */
+function useCarousel() {
+  const context = React.useContext(CarouselContext);
+
+  if (!context) {
+    throw new Error("useCarousel must be used within a <Carousel />");
+  }
+
+  return context;
+}
+
+/**
+ * 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.
+ *
+ * @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)
+ *
+ * @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
+ * <Carousel
+ *   opts={{ align: "start", loop: true }}
+ *   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
+ * import Autoplay from "embla-carousel-autoplay";
+ *
+ * <Carousel
+ *   orientation="vertical"
+ *   plugins={[Autoplay({ delay: 3000, stopOnInteraction: 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
+ * function ControlledCarousel() {
+ *   const [api, setApi] = useState<CarouselApi>();
+ *   const [current, setCurrent] = useState(0);
+ *
+ *   useEffect(() => {
+ *     if (!api) return;
+ *     setCurrent(api.selectedScrollSnap());
+ *     api.on('select', () => setCurrent(api.selectedScrollSnap()));
+ *   }, [api]);
+ *
+ *   return (
+ *     <div>
+ *       <Carousel setApi={setApi}>
+ *         <CarouselContent>...</CarouselContent>
+ *       </Carousel>
+ *       <div className="flex justify-center gap-2 mt-4">
+ *         {Array.from({ length: 5 }).map((_, i) => (
+ *           <button
+ *             key={i}
+ *             className={current === i ? "bg-primary" : "bg-muted"}
+ *             onClick={() => api?.scrollTo(i)}
+ *           />
+ *         ))}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @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
+ *
+ * @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 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
+ */
+function Carousel({
+  orientation = "horizontal",
+  opts,
+  setApi,
+  plugins,
+  className,
+  children,
+  ...props
+}: React.ComponentProps<"div"> & CarouselProps) {
+  const [carouselRef, api] = useEmblaCarousel(
+    {
+      ...opts,
+      axis: orientation === "horizontal" ? "x" : "y",
+    },
+    plugins,
+  );
+  const [canScrollPrev, setCanScrollPrev] = React.useState(false);
+  const [canScrollNext, setCanScrollNext] = React.useState(false);
+
+  const onSelect = useCallback((api: CarouselApi) => {
+    if (!api) return;
+    setCanScrollPrev(api.canScrollPrev());
+    setCanScrollNext(api.canScrollNext());
+  }, []);
+
+  const scrollPrev = () => {
+    api?.scrollPrev();
+  };
+
+  const scrollNext = () => {
+    api?.scrollNext();
+  };
+
+  const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === "ArrowLeft") {
+      event.preventDefault();
+      scrollPrev();
+    } else if (event.key === "ArrowRight") {
+      event.preventDefault();
+      scrollNext();
+    }
+  };
+
+  React.useEffect(() => {
+    if (!api || !setApi) return;
+    setApi(api);
+  }, [api, setApi]);
+
+  React.useEffect(() => {
+    if (!api) return;
+    onSelect(api);
+    api.on("reInit", onSelect);
+    api.on("select", onSelect);
+
+    return () => {
+      api?.off("select", onSelect);
+    };
+  }, [api, onSelect]);
+
+  return (
+    <CarouselContext.Provider
+      value={{
+        carouselRef,
+        api: api,
+        opts,
+        orientation:
+          orientation || (opts?.axis === "y" ? "vertical" : "horizontal"),
+        scrollPrev,
+        scrollNext,
+        canScrollPrev,
+        canScrollNext,
+      }}
+    >
+      <div
+        onKeyDownCapture={handleKeyDown}
+        className={cn("relative", className)}
+        role="region"
+        aria-roledescription="carousel"
+        data-slot="carousel"
+        {...props}
+      >
+        {children}
+      </div>
+    </CarouselContext.Provider>
+  );
+}
+
+/**
+ * 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
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <CarouselContent>
+ *   <CarouselItem>Slide 1</CarouselItem>
+ *   <CarouselItem>Slide 2</CarouselItem>
+ *   <CarouselItem>Slide 3</CarouselItem>
+ * </CarouselContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With custom spacing (horizontal)
+ * <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>
+ * </CarouselContent>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical orientation spacing
+ * <CarouselContent className="-mt-4 h-[300px]">
+ *   <CarouselItem className="pt-4">Slide 1</CarouselItem>
+ *   <CarouselItem className="pt-4">Slide 2</CarouselItem>
+ * </CarouselContent>
+ * ```
+ *
+ * @accessibility
+ * - Provides scrollable container with proper overflow handling
+ * - Maintains responsive layout for horizontal/vertical orientations
+ * - Works with screen readers for content navigation
+ *
+ * @see {@link Carousel} Main carousel component
+ * @see {@link CarouselItem} Individual carousel slides
+ * @since 1.0.0
+ */
+function CarouselContent({ className, ...props }: React.ComponentProps<"div">) {
+  const { carouselRef, orientation } = useCarousel();
+
+  return (
+    <div
+      ref={carouselRef}
+      className="overflow-hidden"
+      data-slot="carousel-content"
+    >
+      <div
+        className={cn(
+          "flex",
+          orientation === "horizontal" ? "-ml-4" : "-mt-4 flex-col",
+          className,
+        )}
+        {...props}
+      />
+    </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.
+ *
+ * @param className - Additional CSS classes for sizing (basis-*) and spacing
+ * @param children - Content to display within the slide
+ *
+ * @example
+ * ```tsx
+ * // Basic slide with content
+ * <CarouselItem>
+ *   <div className="p-6">
+ *     <h3 className="text-lg font-semibold">Slide Title</h3>
+ *     <p className="text-muted-foreground">Slide description</p>
+ *   </div>
+ * </CarouselItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Card-based slide
+ * <CarouselItem>
+ *   <Card>
+ *     <CardHeader>
+ *       <CardTitle>Product Name</CardTitle>
+ *     </CardHeader>
+ *     <CardContent>
+ *       <img src="product.jpg" alt="Product" className="w-full" />
+ *       <p className="mt-2">$99.99</p>
+ *     </CardContent>
+ *   </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" />
+ * </CarouselItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom sizing with fixed width
+ * <CarouselItem className="basis-4/5">
+ *   <div className="w-full h-48 bg-gradient-to-r from-blue-500 to-purple-600" />
+ * </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
+ *
+ * @see {@link Carousel} Main carousel component
+ * @see {@link CarouselContent} Container for carousel items
+ * @since 1.0.0
+ */
+function CarouselItem({ className, ...props }: React.ComponentProps<"div">) {
+  const { orientation } = useCarousel();
+
+  return (
+    <div
+      role="group"
+      aria-roledescription="slide"
+      data-slot="carousel-item"
+      className={cn(
+        "min-w-0 shrink-0 grow-0 basis-full",
+        orientation === "horizontal" ? "pl-4" : "pt-4",
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * 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")
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Carousel>
+ *   <CarouselContent>
+ *     <CarouselItem>Slide 1</CarouselItem>
+ *     <CarouselItem>Slide 2</CarouselItem>
+ *   </CarouselContent>
+ *   <CarouselPrevious />
+ *   <CarouselNext />
+ * </Carousel>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling
+ * <CarouselPrevious
+ *   className="-left-8 bg-background shadow-md"
+ *   variant="ghost"
+ *   size="sm"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical carousel positioning
+ * <Carousel orientation="vertical">
+ *   <CarouselContent>...</CarouselContent>
+ *   <CarouselPrevious />
+ *   <CarouselNext />
+ * </Carousel>
+ * ```
+ *
+ * @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
+ *
+ * @see {@link Carousel} Main carousel component
+ * @see {@link CarouselNext} Next navigation button
+ * @see {@link Button} Underlying button component
+ * @since 1.0.0
+ */
+function CarouselPrevious({
+  className,
+  variant = "outline",
+  size = "icon",
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { orientation, scrollPrev, canScrollPrev } = useCarousel();
+
+  return (
+    <Button
+      data-slot="carousel-previous"
+      variant={variant}
+      size={size}
+      className={cn(
+        "absolute size-8 rounded-full",
+        orientation === "horizontal"
+          ? "top-1/2 -left-12 -translate-y-1/2"
+          : "-top-12 left-1/2 -translate-x-1/2 rotate-90",
+        className,
+      )}
+      disabled={!canScrollPrev}
+      onClick={scrollPrev}
+      {...props}
+    >
+      <ArrowLeft />
+      <span className="sr-only">Previous slide</span>
+    </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. 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")
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Carousel>
+ *   <CarouselContent>
+ *     <CarouselItem>Slide 1</CarouselItem>
+ *     <CarouselItem>Slide 2</CarouselItem>
+ *   </CarouselContent>
+ *   <CarouselPrevious />
+ *   <CarouselNext />
+ * </Carousel>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Custom styling
+ * <CarouselNext
+ *   className="-right-8 bg-background shadow-md"
+ *   variant="ghost"
+ *   size="sm"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Vertical carousel positioning
+ * <Carousel orientation="vertical">
+ *   <CarouselContent>...</CarouselContent>
+ *   <CarouselPrevious />
+ *   <CarouselNext />
+ * </Carousel>
+ * ```
+ *
+ * @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
+ *
+ * @see {@link Carousel} Main carousel component
+ * @see {@link CarouselPrevious} Previous navigation button
+ * @see {@link Button} Underlying button component
+ * @since 1.0.0
+ */
+function CarouselNext({
+  className,
+  variant = "outline",
+  size = "icon",
+  ...props
+}: React.ComponentProps<typeof Button>) {
+  const { orientation, scrollNext, canScrollNext } = useCarousel();
+
+  return (
+    <Button
+      data-slot="carousel-next"
+      variant={variant}
+      size={size}
+      className={cn(
+        "absolute size-8 rounded-full",
+        orientation === "horizontal"
+          ? "top-1/2 -right-12 -translate-y-1/2"
+          : "-bottom-12 left-1/2 -translate-x-1/2 rotate-90",
+        className,
+      )}
+      disabled={!canScrollNext}
+      onClick={scrollNext}
+      {...props}
+    >
+      <ArrowRight />
+      <span className="sr-only">Next slide</span>
+    </Button>
+  );
+}
+
+export {
+  type CarouselApi,
+  Carousel,
+  CarouselContent,
+  CarouselItem,
+  CarouselPrevious,
+  CarouselNext,
+};