@neynar/ui 0.1.1

package/src/components/ui/pagination.tsx

@@ -0,0 +1,456 @@
+import {
+  ChevronLeftIcon,
+  ChevronRightIcon,
+  MoreHorizontalIcon,
+} from "lucide-react";
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+import { Button, buttonVariants } from "@/components/ui/button";
+
+/**
+ * Pagination navigation component for large datasets
+ *
+ * A comprehensive pagination component built on shadcn/ui standards that provides
+ * intuitive navigation through pages of content. Features responsive design,
+ * accessibility compliance, and flexible composition patterns for different use cases.
+ *
+ * Ideal for data tables, search results, product listings, and any paginated content.
+ * Integrates seamlessly with React frameworks like Next.js through customizable link components.
+ *
+ * @example
+ * ```tsx
+ * // Basic pagination with numbered pages
+ * <Pagination>
+ *   <PaginationContent>
+ *     <PaginationItem>
+ *       <PaginationPrevious href="/page/1" />
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/page/1">1</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/page/2" isActive>2</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/page/3">3</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationNext href="/page/3" />
+ *     </PaginationItem>
+ *   </PaginationContent>
+ * </Pagination>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With ellipsis for large page ranges
+ * <Pagination>
+ *   <PaginationContent>
+ *     <PaginationItem>
+ *       <PaginationPrevious href="/page/4" />
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/page/1">1</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationEllipsis />
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/page/5" isActive>5</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationEllipsis />
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/page/50">50</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationNext href="/page/6" />
+ *     </PaginationItem>
+ *   </PaginationContent>
+ * </Pagination>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js Link integration
+ * <Pagination>
+ *   <PaginationContent>
+ *     <PaginationItem>
+ *       <PaginationLink asChild>
+ *         <Link href="/products?page=1">1</Link>
+ *       </PaginationLink>
+ *     </PaginationItem>
+ *   </PaginationContent>
+ * </Pagination>
+ * ```
+ *
+ * @accessibility
+ * - Semantic nav element with role="navigation" and aria-label="pagination"
+ * - aria-current="page" automatically applied to active page links
+ * - Descriptive aria-labels on Previous/Next buttons for screen readers
+ * - Full keyboard navigation support with Tab and Enter keys
+ * - High contrast focus indicators and proper color contrast ratios
+ * - Screen reader friendly ellipsis with "More pages" hidden text
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/pagination} shadcn/ui Pagination
+ * @see {@link PaginationContent} Container for pagination items
+ * @see {@link PaginationLink} Individual page number links
+ * @see {@link PaginationPrevious} Previous page navigation button
+ * @see {@link PaginationNext} Next page navigation button
+ * @see {@link PaginationEllipsis} Ellipsis indicator for omitted pages
+ * @since 1.0.0
+ */
+function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
+  return (
+    <nav
+      role="navigation"
+      aria-label="pagination"
+      data-slot="pagination"
+      className={cn("mx-auto flex w-full justify-center", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Container for pagination navigation items
+ *
+ * A semantic unordered list that houses all pagination controls in a
+ * responsive horizontal layout. Provides proper spacing and alignment
+ * for pagination items while maintaining accessibility standards.
+ *
+ * @example
+ * ```tsx
+ * <PaginationContent>
+ *   <PaginationItem>
+ *     <PaginationPrevious href="/prev" />
+ *   </PaginationItem>
+ *   <PaginationItem>
+ *     <PaginationLink href="/page/1">1</PaginationLink>
+ *   </PaginationItem>
+ * </PaginationContent>
+ * ```
+ *
+ * @accessibility
+ * - Semantic ul element for proper list structure
+ * - Flexible gap spacing for touch-friendly interaction
+ * - Horizontal scrolling support on narrow viewports
+ */
+function PaginationContent({
+  className,
+  ...props
+}: React.ComponentProps<"ul">) {
+  return (
+    <ul
+      data-slot="pagination-content"
+      className={cn("flex flex-row items-center gap-1", className)}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Individual list item wrapper for pagination controls
+ *
+ * A semantic list item that wraps pagination links, buttons, or ellipsis elements.
+ * Provides consistent structure and enables proper keyboard navigation between
+ * pagination controls.
+ *
+ * @example
+ * ```tsx
+ * <PaginationItem>
+ *   <PaginationLink href="/page/1">1</PaginationLink>
+ * </PaginationItem>
+ *
+ * <PaginationItem>
+ *   <PaginationEllipsis />
+ * </PaginationItem>
+ * ```
+ */
+function PaginationItem({ ...props }: React.ComponentProps<"li">) {
+  return <li data-slot="pagination-item" {...props} />;
+}
+
+/**
+ * Props for pagination link components
+ */
+type PaginationLinkProps = {
+  /**
+   * Whether this link represents the currently active page
+   *
+   * When true, applies active styling and adds aria-current="page"
+   * for screen reader accessibility.
+   *
+   * @default false
+   */
+  isActive?: boolean;
+} & Pick<React.ComponentProps<typeof Button>, "size"> &
+  React.ComponentProps<"a">;
+
+/**
+ * Clickable link for individual page numbers
+ *
+ * Interactive link component that navigates to specific pages within
+ * paginated content. Features automatic active state styling and
+ * accessibility attributes. Can be used with framework routers like
+ * Next.js Link or React Router through the asChild pattern.
+ *
+ * @example
+ * ```tsx
+ * // Basic page links
+ * <PaginationLink href="/products?page=1">1</PaginationLink>
+ * <PaginationLink href="/products?page=2" isActive>2</PaginationLink>
+ * <PaginationLink href="/products?page=3">3</PaginationLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With Next.js Link
+ * <PaginationLink asChild>
+ *   <Link href="/search?q=react&page=1">1</Link>
+ * </PaginationLink>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With onClick handlers for client-side pagination
+ * <PaginationLink
+ *   href="#"
+ *   onClick={(e) => {
+ *     e.preventDefault();
+ *     onPageChange(1);
+ *   }}
+ * >
+ *   1
+ * </PaginationLink>
+ * ```
+ *
+ * @accessibility
+ * - Automatically applies aria-current="page" when isActive is true
+ * - Button-style focus indicators for keyboard navigation
+ * - Sufficient color contrast for active/inactive states
+ * - Touch-friendly minimum 44px target size
+ */
+function PaginationLink({
+  className,
+  isActive,
+  size = "icon",
+  ...props
+}: PaginationLinkProps) {
+  return (
+    <a
+      aria-current={isActive ? "page" : undefined}
+      data-slot="pagination-link"
+      data-active={isActive}
+      className={cn(
+        buttonVariants({
+          variant: isActive ? "outline" : "ghost",
+          size,
+        }),
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * Previous page navigation button
+ *
+ * Navigates to the previous page in the pagination sequence. Features
+ * responsive design that shows only an icon on mobile devices and
+ * icon with text on larger screens for optimal user experience.
+ *
+ * @example
+ * ```tsx
+ * // Basic previous button
+ * <PaginationPrevious href="/products?page=1" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With disabled state (typically for first page)
+ * <PaginationPrevious
+ *   href="#"
+ *   className="pointer-events-none opacity-50"
+ *   aria-disabled="true"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With click handler for client-side navigation
+ * <PaginationPrevious
+ *   href="#"
+ *   onClick={(e) => {
+ *     e.preventDefault();
+ *     if (currentPage > 1) {
+ *       onPageChange(currentPage - 1);
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * @accessibility
+ * - Built-in aria-label="Go to previous page" for screen readers
+ * - Chevron icon provides visual direction context
+ * - Responsive text label appears on larger screens
+ * - Keyboard accessible through Tab navigation
+ * - Should be disabled on first page to prevent confusion
+ */
+function PaginationPrevious({
+  className,
+  ...props
+}: React.ComponentProps<typeof PaginationLink>) {
+  return (
+    <PaginationLink
+      aria-label="Go to previous page"
+      size="default"
+      className={cn("gap-1 px-2.5 sm:pl-2.5", className)}
+      {...props}
+    >
+      <ChevronLeftIcon />
+      <span className="hidden sm:block">Previous</span>
+    </PaginationLink>
+  );
+}
+
+/**
+ * Next page navigation button
+ *
+ * Navigates to the next page in the pagination sequence. Features
+ * responsive design that shows only an icon on mobile devices and
+ * text with icon on larger screens for optimal user experience.
+ *
+ * @example
+ * ```tsx
+ * // Basic next button
+ * <PaginationNext href="/products?page=3" />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With disabled state (typically for last page)
+ * <PaginationNext
+ *   href="#"
+ *   className="pointer-events-none opacity-50"
+ *   aria-disabled="true"
+ * />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With click handler for client-side navigation
+ * <PaginationNext
+ *   href="#"
+ *   onClick={(e) => {
+ *     e.preventDefault();
+ *     if (currentPage < totalPages) {
+ *       onPageChange(currentPage + 1);
+ *     }
+ *   }}
+ * />
+ * ```
+ *
+ * @accessibility
+ * - Built-in aria-label="Go to next page" for screen readers
+ * - Chevron icon provides visual direction context
+ * - Responsive text label appears on larger screens
+ * - Keyboard accessible through Tab navigation
+ * - Should be disabled on last page to prevent confusion
+ */
+function PaginationNext({
+  className,
+  ...props
+}: React.ComponentProps<typeof PaginationLink>) {
+  return (
+    <PaginationLink
+      aria-label="Go to next page"
+      size="default"
+      className={cn("gap-1 px-2.5 sm:pr-2.5", className)}
+      {...props}
+    >
+      <span className="hidden sm:block">Next</span>
+      <ChevronRightIcon />
+    </PaginationLink>
+  );
+}
+
+/**
+ * Visual indicator for omitted page numbers
+ *
+ * Displays a horizontal ellipsis (three dots) to indicate that
+ * page numbers have been omitted from the pagination display.
+ * Used to maintain clean UI when dealing with large page ranges.
+ *
+ * @example
+ * ```tsx
+ * // Between page ranges
+ * <PaginationItem>
+ *   <PaginationLink href="/page/1">1</PaginationLink>
+ * </PaginationItem>
+ * <PaginationItem>
+ *   <PaginationEllipsis />
+ * </PaginationItem>
+ * <PaginationItem>
+ *   <PaginationLink href="/page/25" isActive>25</PaginationLink>
+ * </PaginationItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Common pagination pattern with ellipsis
+ * // 1 ... 23 24 [25] 26 27 ... 100
+ * <PaginationContent>
+ *   <PaginationItem>
+ *     <PaginationLink href="/page/1">1</PaginationLink>
+ *   </PaginationItem>
+ *   <PaginationItem>
+ *     <PaginationEllipsis />
+ *   </PaginationItem>
+ *   <PaginationItem>
+ *     <PaginationLink href="/page/25" isActive>25</PaginationLink>
+ *   </PaginationItem>
+ *   <PaginationItem>
+ *     <PaginationEllipsis />
+ *   </PaginationItem>
+ *   <PaginationItem>
+ *     <PaginationLink href="/page/100">100</PaginationLink>
+ *   </PaginationItem>
+ * </PaginationContent>
+ * ```
+ *
+ * @accessibility
+ * - Visual element is aria-hidden from screen readers
+ * - Hidden "More pages" text provides context for assistive technology
+ * - Non-interactive, purely decorative indicator
+ * - Consistent sizing with pagination links for visual harmony
+ */
+function PaginationEllipsis({
+  className,
+  ...props
+}: React.ComponentProps<"span">) {
+  return (
+    <span
+      aria-hidden
+      data-slot="pagination-ellipsis"
+      className={cn("flex size-9 items-center justify-center", className)}
+      {...props}
+    >
+      <MoreHorizontalIcon className="size-4" />
+      <span className="sr-only">More pages</span>
+    </span>
+  );
+}
+
+export {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+};

package/src/components/ui/popover.tsx

@@ -0,0 +1,216 @@
+import * as React from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * Popover displays rich content in a portal, triggered by a button
+ *
+ * A versatile floating panel component built on Radix UI primitives that displays
+ * interactive content without navigating away from the current context. Unlike tooltips,
+ * popovers support complex layouts, forms, and user interactions while maintaining
+ * proper focus management and accessibility standards.
+ *
+ * @example
+ * ```tsx
+ * // Basic popover with information
+ * <Popover>
+ *   <PopoverTrigger asChild>
+ *     <Button variant="outline">Open popover</Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent>
+ *     <div className="grid gap-4">
+ *       <h4 className="font-medium leading-none">Dimensions</h4>
+ *       <p className="text-sm text-muted-foreground">
+ *         Set the dimensions for the layer.
+ *       </p>
+ *     </div>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Controlled popover with form interactions
+ * const [open, setOpen] = useState(false);
+ *
+ * <Popover open={open} onOpenChange={setOpen}>
+ *   <PopoverTrigger asChild>
+ *     <Button>Settings</Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent className="w-80">
+ *     <div className="grid gap-4">
+ *       <div className="space-y-2">
+ *         <h4 className="font-medium leading-none">Settings</h4>
+ *         <p className="text-sm text-muted-foreground">
+ *           Configure your preferences
+ *         </p>
+ *       </div>
+ *       <div className="grid gap-2">
+ *         <Label htmlFor="width">Width</Label>
+ *         <Input id="width" defaultValue="100%" />
+ *       </div>
+ *     </div>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Positioned popover with custom alignment
+ * <Popover>
+ *   <PopoverTrigger asChild>
+ *     <Button variant="ghost" size="icon">
+ *       <HelpCircle className="h-4 w-4" />
+ *     </Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent side="top" align="start" className="w-80">
+ *     <div className="space-y-2">
+ *       <h4 className="font-medium">Help Information</h4>
+ *       <p className="text-sm text-muted-foreground">
+ *         Additional context and helpful tips for this feature.
+ *       </p>
+ *     </div>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ *
+ * @accessibility
+ * - **Keyboard Navigation**: Tab to focus, Enter/Space to open, Escape to close
+ * - **Focus Management**: Focus trapped within popover when open, returns to trigger on close
+ * - **Screen Reader Support**: Proper ARIA attributes and announcements
+ * - **Auto-positioning**: Automatically repositions to stay within viewport bounds
+ * - **Dismissible**: Closes on outside click or focus loss
+ *
+ * @see {@link https://ui.shadcn.com/docs/components/popover} shadcn/ui Popover
+ * @see {@link https://www.radix-ui.com/primitives/docs/components/popover} Radix Popover Primitive
+ * @since 1.0.0
+ */
+/**
+ * Root popover component that manages open/closed state
+ *
+ * @param open - Controls the open state of the popover
+ * @param onOpenChange - Event handler called when the open state changes
+ * @param defaultOpen - The initial open state for uncontrolled usage
+ * @param modal - Whether the popover should be modal (default: false)
+ */
+function Popover({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Root>) {
+  return <PopoverPrimitive.Root data-slot="popover" {...props} />;
+}
+
+/**
+ * PopoverTrigger - The element that triggers the popover
+ *
+ * @param asChild - Changes the default rendered element to the one passed as a child,
+ *                  merging their props and behavior. Recommended for custom triggers.
+ *
+ * @example
+ * ```tsx
+ * // Using asChild with custom button
+ * <PopoverTrigger asChild>
+ *   <Button variant="outline">Open Settings</Button>
+ * </PopoverTrigger>
+ *
+ * // Direct usage (renders as button)
+ * <PopoverTrigger className="custom-trigger">
+ *   Click me
+ * </PopoverTrigger>
+ * ```
+ *
+ * @since 1.0.0
+ */
+function PopoverTrigger({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Trigger>) {
+  return <PopoverPrimitive.Trigger data-slot="popover-trigger" {...props} />;
+}
+
+/**
+ * PopoverContent - The content container for the popover
+ *
+ * @param side - The preferred side of the trigger to render against ("top" | "right" | "bottom" | "left")
+ * @param align - How to align the popover relative to the trigger ("start" | "center" | "end")
+ * @param sideOffset - Distance in pixels from the trigger (default: 4)
+ * @param alignOffset - Offset in pixels along the align axis
+ * @param avoidCollisions - Whether to automatically avoid collisions with viewport edges (default: true)
+ * @param collisionBoundary - Boundary element(s) to consider for collision detection
+ * @param sticky - Whether to stick to the boundary edges when colliding ("partial" | "always")
+ *
+ * @example
+ * ```tsx
+ * // Basic content with default positioning
+ * <PopoverContent>
+ *   <div className="grid gap-4">
+ *     <h4 className="font-medium">Title</h4>
+ *     <p className="text-sm text-muted-foreground">Description</p>
+ *   </div>
+ * </PopoverContent>
+ *
+ * // Positioned content with custom width
+ * <PopoverContent side="top" align="start" className="w-80">
+ *   <form className="grid gap-4">
+ *     <Input placeholder="Enter value" />
+ *     <Button type="submit">Save</Button>
+ *   </form>
+ * </PopoverContent>
+ * ```
+ *
+ * @since 1.0.0
+ */
+function PopoverContent({
+  className,
+  align = "center",
+  sideOffset = 4,
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Content>) {
+  return (
+    <PopoverPrimitive.Portal>
+      <PopoverPrimitive.Content
+        data-slot="popover-content"
+        align={align}
+        sideOffset={sideOffset}
+        className={cn(
+          "bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-72 origin-(--radix-popover-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden",
+          className,
+        )}
+        {...props}
+      />
+    </PopoverPrimitive.Portal>
+  );
+}
+
+/**
+ * PopoverAnchor - Optional anchor element for custom positioning
+ *
+ * Use PopoverAnchor when you need the popover to position relative to an element
+ * other than the trigger. This is useful for complex layouts where the visual
+ * trigger and positioning reference should be different elements.
+ *
+ * @example
+ * ```tsx
+ * <Popover>
+ *   <PopoverAnchor asChild>
+ *     <div className="relative">
+ *       <span>Reference element for positioning</span>
+ *     </div>
+ *   </PopoverAnchor>
+ *   <PopoverTrigger asChild>
+ *     <Button>Open (positioned relative to anchor)</Button>
+ *   </PopoverTrigger>
+ *   <PopoverContent>
+ *     <p>This popover positions relative to the anchor, not the trigger</p>
+ *   </PopoverContent>
+ * </Popover>
+ * ```
+ *
+ * @since 1.0.0
+ */
+function PopoverAnchor({
+  ...props
+}: React.ComponentProps<typeof PopoverPrimitive.Anchor>) {
+  return <PopoverPrimitive.Anchor data-slot="popover-anchor" {...props} />;
+}
+
+export { Popover, PopoverTrigger, PopoverContent, PopoverAnchor };