@neynar/ui 0.1.1

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

@@ -0,0 +1,369 @@
+import * as React from "react";
+import useEmblaCarousel, { type UseEmblaCarouselType } from "embla-carousel-react";
+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;
+};
+/**
+ * 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
+ */
+declare function Carousel({ orientation, opts, setApi, plugins, className, children, ...props }: React.ComponentProps<"div"> & CarouselProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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
+ */
+declare function CarouselContent({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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
+ */
+declare function CarouselItem({ className, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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
+ */
+declare function CarouselPrevious({ className, variant, size, ...props }: React.ComponentProps<typeof Button>): import("react/jsx-runtime").JSX.Element;
+/**
+ * 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
+ */
+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, };
+//# sourceMappingURL=carousel.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"carousel.d.ts","sourceRoot":"","sources":["../../../src/components/ui/carousel.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,gBAAgB,EAAE,EACvB,KAAK,oBAAoB,EAC1B,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAC;AAEhD,KAAK,WAAW,GAAG,oBAAoB,CAAC,CAAC,CAAC,CAAC;AAC3C,KAAK,qBAAqB,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAC;AACjE,KAAK,eAAe,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;AAChD,KAAK,cAAc,GAAG,qBAAqB,CAAC,CAAC,CAAC,CAAC;AAE/C,KAAK,aAAa,GAAG;IACnB,IAAI,CAAC,EAAE,eAAe,CAAC;IACvB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,WAAW,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACxC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,WAAW,KAAK,IAAI,CAAC;CACrC,CAAC;AA6DF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+HG;AACH,iBAAS,QAAQ,CAAC,EAChB,WAA0B,EAC1B,IAAI,EACJ,MAAM,EACN,OAAO,EACP,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,GAAG,aAAa,2CA6E7C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,iBAAS,eAAe,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAmB5E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,iBAAS,YAAY,CAAC,EAAE,SAAS,EAAE,GAAG,KAAK,EAAE,EAAE,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC,2CAgBzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,iBAAS,gBAAgB,CAAC,EACxB,SAAS,EACT,OAAmB,EACnB,IAAa,EACb,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,MAAM,CAAC,2CAuBrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,iBAAS,YAAY,CAAC,EACpB,SAAS,EACT,OAAmB,EACnB,IAAa,EACb,GAAG,KAAK,EACT,EAAE,KAAK,CAAC,cAAc,CAAC,OAAO,MAAM,CAAC,2CAuBrC;AAED,OAAO,EACL,KAAK,WAAW,EAChB,QAAQ,EACR,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,YAAY,GACb,CAAC"}