@neynar/ui 0.1.1 → 0.1.2

package/src/components/ui/pagination.tsx

@@ -6,17 +6,51 @@ import {
 import * as React from "react";
 
 import { cn } from "@/lib/utils";
-import { Button, buttonVariants } from "@/components/ui/button";
+import { buttonVariants } from "@/components/ui/button";
+
+/**
+ * Props for Pagination component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred HTML element types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PaginationDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Child elements - typically PaginationContent */
+  children?: React.ReactNode;
+  /** ARIA role for the navigation element @default "navigation" */
+  role?: string;
+  /** ARIA label describing the navigation's purpose @default "pagination" */
+  "aria-label"?: string;
+  /** Custom id attribute for the pagination navigation */
+  id?: string;
+  /** Tab index for focus management @default 0 */
+  tabIndex?: number;
+} & React.HTMLAttributes<HTMLElement>;
+
+/**
+ * Component prop type using inferred HTML nav element props
+ */
+type PaginationProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Child elements - typically PaginationContent */
+  children?: React.ReactNode;
+} & Omit<React.ComponentProps<"nav">, "className" | "children">;
 
 /**
  * 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.
+ * intuitive navigation through pages of content. All interactive elements use
+ * buttonVariants from the Button component for consistent styling and behavior:
+ * - PaginationLink uses "outline" variant when active, "ghost" when inactive
+ * - PaginationPrevious/PaginationNext use "ghost" variant by default
+ * - All components inherit Button's focus management, hover states, and accessibility
  *
- * Ideal for data tables, search results, product listings, and any paginated content.
- * Integrates seamlessly with React frameworks like Next.js through customizable link components.
+ * Features responsive design, full accessibility compliance, and flexible composition
+ * patterns for different use cases. Ideal for data tables, search results, product
+ * listings, and any paginated content that needs professional navigation controls.
  *
  * @example
  * ```tsx
@@ -24,19 +58,19 @@ import { Button, buttonVariants } from "@/components/ui/button";
  * <Pagination>
  *   <PaginationContent>
  *     <PaginationItem>
- *       <PaginationPrevious href="/page/1" />
+ *       <PaginationPrevious href="/products?page=1" />
  *     </PaginationItem>
  *     <PaginationItem>
- *       <PaginationLink href="/page/1">1</PaginationLink>
+ *       <PaginationLink href="/products?page=1">1</PaginationLink>
  *     </PaginationItem>
  *     <PaginationItem>
- *       <PaginationLink href="/page/2" isActive>2</PaginationLink>
+ *       <PaginationLink href="/products?page=2" isActive>2</PaginationLink>
  *     </PaginationItem>
  *     <PaginationItem>
- *       <PaginationLink href="/page/3">3</PaginationLink>
+ *       <PaginationLink href="/products?page=3">3</PaginationLink>
  *     </PaginationItem>
  *     <PaginationItem>
- *       <PaginationNext href="/page/3" />
+ *       <PaginationNext href="/products?page=3" />
  *     </PaginationItem>
  *   </PaginationContent>
  * </Pagination>
@@ -44,29 +78,35 @@ import { Button, buttonVariants } from "@/components/ui/button";
  *
  * @example
  * ```tsx
- * // With ellipsis for large page ranges
+ * // Complete pagination with ellipsis for large datasets
  * <Pagination>
  *   <PaginationContent>
  *     <PaginationItem>
- *       <PaginationPrevious href="/page/4" />
+ *       <PaginationPrevious href="/search?q=react&page=4" />
  *     </PaginationItem>
  *     <PaginationItem>
- *       <PaginationLink href="/page/1">1</PaginationLink>
+ *       <PaginationLink href="/search?q=react&page=1">1</PaginationLink>
  *     </PaginationItem>
  *     <PaginationItem>
  *       <PaginationEllipsis />
  *     </PaginationItem>
  *     <PaginationItem>
- *       <PaginationLink href="/page/5" isActive>5</PaginationLink>
+ *       <PaginationLink href="/search?q=react&page=4">4</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/search?q=react&page=5" isActive>5</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/search?q=react&page=6">6</PaginationLink>
  *     </PaginationItem>
  *     <PaginationItem>
  *       <PaginationEllipsis />
  *     </PaginationItem>
  *     <PaginationItem>
- *       <PaginationLink href="/page/50">50</PaginationLink>
+ *       <PaginationLink href="/search?q=react&page=50">50</PaginationLink>
  *     </PaginationItem>
  *     <PaginationItem>
- *       <PaginationNext href="/page/6" />
+ *       <PaginationNext href="/search?q=react&page=6" />
  *     </PaginationItem>
  *   </PaginationContent>
  * </Pagination>
@@ -74,13 +114,81 @@ import { Button, buttonVariants } from "@/components/ui/button";
  *
  * @example
  * ```tsx
- * // With Next.js Link integration
+ * // Client-side pagination with state management
+ * function PaginatedResults() {
+ *   const [currentPage, setCurrentPage] = useState(1);
+ *   const totalPages = 25;
+ *
+ *   return (
+ *     <Pagination>
+ *       <PaginationContent>
+ *         <PaginationItem>
+ *           <PaginationPrevious
+ *             href="#"
+ *             onClick={(e) => {
+ *               e.preventDefault();
+ *               if (currentPage > 1) setCurrentPage(currentPage - 1);
+ *             }}
+ *             className={currentPage === 1 ? "pointer-events-none opacity-50" : ""}
+ *             aria-disabled={currentPage === 1}
+ *           />
+ *         </PaginationItem>
+ *
+ *         {[1, 2, 3].map((page) => (
+ *           <PaginationItem key={page}>
+ *             <PaginationLink
+ *               href="#"
+ *               isActive={currentPage === page}
+ *               onClick={(e) => {
+ *                 e.preventDefault();
+ *                 setCurrentPage(page);
+ *               }}
+ *             >
+ *               {page}
+ *             </PaginationLink>
+ *           </PaginationItem>
+ *         ))}
+ *
+ *         <PaginationItem>
+ *           <PaginationNext
+ *             href="#"
+ *             onClick={(e) => {
+ *               e.preventDefault();
+ *               if (currentPage < totalPages) setCurrentPage(currentPage + 1);
+ *             }}
+ *             className={currentPage === totalPages ? "pointer-events-none opacity-50" : ""}
+ *             aria-disabled={currentPage === totalPages}
+ *           />
+ *         </PaginationItem>
+ *       </PaginationContent>
+ *     </Pagination>
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Different sizes for various use cases
+ * // Compact pagination for data tables
  * <Pagination>
  *   <PaginationContent>
  *     <PaginationItem>
- *       <PaginationLink asChild>
- *         <Link href="/products?page=1">1</Link>
- *       </PaginationLink>
+ *       <PaginationLink href="/data?page=1" size="sm">1</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/data?page=2" size="sm" isActive>2</PaginationLink>
+ *     </PaginationItem>
+ *   </PaginationContent>
+ * </Pagination>
+ *
+ * // Large pagination for primary content
+ * <Pagination>
+ *   <PaginationContent>
+ *     <PaginationItem>
+ *       <PaginationLink href="/articles?page=1" size="lg">1</PaginationLink>
+ *     </PaginationItem>
+ *     <PaginationItem>
+ *       <PaginationLink href="/articles?page=2" size="lg" isActive>2</PaginationLink>
  *     </PaginationItem>
  *   </PaginationContent>
  * </Pagination>
@@ -90,11 +198,23 @@ import { Button, buttonVariants } from "@/components/ui/button";
  * - 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
+ * - Full keyboard navigation support (Tab, Enter, Space keys)
+ * - High contrast focus indicators (3px ring) meeting WCAG 2.1 AA standards
+ * - Screen reader friendly ellipsis with hidden "More pages" text
+ * - Proper disabled states communicated via aria-disabled
+ * - Touch-friendly minimum 44px target sizes on all interactive elements
+ * - Respects user's reduced motion preferences in transitions
+ *
+ * @variant outline - Used for active page links (PaginationLink with isActive=true)
+ * @variant ghost - Used for inactive page links and navigation buttons (default state)
+ *
+ * @size icon - Default for PaginationLink (36px × 36px) optimized for page numbers
+ * @size default - Used for PaginationPrevious/Next (36px height with more padding)
+ * @size sm - Available for compact layouts (32px height)
+ * @size lg - Available for prominent pagination (40px height)
  *
  * @see {@link https://ui.shadcn.com/docs/components/pagination} shadcn/ui Pagination
+ * @see {@link buttonVariants} CVA configuration for all button styling
  * @see {@link PaginationContent} Container for pagination items
  * @see {@link PaginationLink} Individual page number links
  * @see {@link PaginationPrevious} Previous page navigation button
@@ -102,7 +222,7 @@ import { Button, buttonVariants } from "@/components/ui/button";
  * @see {@link PaginationEllipsis} Ellipsis indicator for omitted pages
  * @since 1.0.0
  */
-function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
+function Pagination({ className, ...props }: PaginationProps) {
   return (
     <nav
       role="navigation"
@@ -114,6 +234,34 @@ function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
   );
 }
 
+/**
+ * Props for PaginationContent component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred HTML element types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PaginationContentDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Child elements - typically PaginationItem components */
+  children?: React.ReactNode;
+  /** Custom id attribute for the pagination list */
+  id?: string;
+  /** Tab index for focus management @default 0 */
+  tabIndex?: number;
+  /** ARIA label for the pagination list */
+  "aria-label"?: string;
+} & React.HTMLAttributes<HTMLUListElement>;
+
+/**
+ * Component prop type using inferred HTML ul element props
+ */
+type PaginationContentProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Child elements - typically PaginationItem components */
+  children?: React.ReactNode;
+} & Omit<React.ComponentProps<"ul">, "className" | "children">;
+
 /**
  * Container for pagination navigation items
  *
@@ -138,10 +286,7 @@ function Pagination({ className, ...props }: React.ComponentProps<"nav">) {
  * - Flexible gap spacing for touch-friendly interaction
  * - Horizontal scrolling support on narrow viewports
  */
-function PaginationContent({
-  className,
-  ...props
-}: React.ComponentProps<"ul">) {
+function PaginationContent({ className, ...props }: PaginationContentProps) {
   return (
     <ul
       data-slot="pagination-content"
@@ -151,6 +296,34 @@ function PaginationContent({
   );
 }
 
+/**
+ * Props for PaginationItem component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred HTML element types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PaginationItemDocsProps = {
+  /** Child elements - typically PaginationLink, PaginationPrevious, PaginationNext, or PaginationEllipsis */
+  children?: React.ReactNode;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Custom id attribute for the pagination item */
+  id?: string;
+  /** Tab index for focus management @default 0 */
+  tabIndex?: number;
+  /** ARIA label for the pagination item */
+  "aria-label"?: string;
+} & React.HTMLAttributes<HTMLLIElement>;
+
+/**
+ * Component prop type using inferred HTML li element props
+ */
+type PaginationItemProps = {
+  /** Child elements - typically PaginationLink, PaginationPrevious, PaginationNext, or PaginationEllipsis */
+  children?: React.ReactNode;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+} & Omit<React.ComponentProps<"li">, "children" | "className">;
+
 /**
  * Individual list item wrapper for pagination controls
  *
@@ -169,37 +342,131 @@ function PaginationContent({
  * </PaginationItem>
  * ```
  */
-function PaginationItem({ ...props }: React.ComponentProps<"li">) {
+function PaginationItem({ ...props }: PaginationItemProps) {
   return <li data-slot="pagination-item" {...props} />;
 }
 
 /**
- * Props for pagination link components
+ * Props for PaginationLink component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred HTML element types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PaginationLinkDocsProps = {
+  /**
+   * Whether this link represents the currently active page
+   *
+   * When true, applies active styling (outline variant) and adds aria-current="page"
+   * for screen reader accessibility. Active links use the "outline" button variant
+   * while inactive links use the "ghost" variant from buttonVariants.
+   *
+   * @default false
+   */
+  isActive?: boolean;
+  /**
+   * Size variant inherited from Button component
+   *
+   * Controls the dimensions and padding of the pagination link:
+   * - "default": Standard height (36px) with balanced padding
+   * - "sm": Small height (32px) for compact interfaces
+   * - "lg": Large height (40px) for prominent actions
+   * - "icon": Square (36px × 36px) optimized for icon-only usage
+   *
+   * @default "icon"
+   */
+  size?: "default" | "sm" | "lg" | "icon";
+  /** URL or path to navigate to when the link is clicked */
+  href?: string;
+  /** Child content - typically page numbers or navigation text */
+  children?: React.ReactNode;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Click handler for custom navigation logic or analytics tracking */
+  onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+  /** ARIA label for screen readers - especially important for icon-only links */
+  "aria-label"?: string;
+  /** Indicates current page state for screen readers when isActive is true */
+  "aria-current"?: "page" | "step" | "location" | "date" | "time" | boolean;
+  /** References elements that describe this link */
+  "aria-describedby"?: string;
+  /** Indicates if the link is disabled (use with appropriate styling) */
+  "aria-disabled"?: boolean;
+  /** Tab index for focus management @default 0 */
+  tabIndex?: number;
+  /** Custom id attribute for the pagination link */
+  id?: string;
+  /** Title attribute for additional context on hover */
+  title?: string;
+  /** Target window for link navigation @default "_self" */
+  target?: "_self" | "_blank" | "_parent" | "_top";
+  /** Relationship between current document and linked document */
+  rel?: string;
+} & React.AnchorHTMLAttributes<HTMLAnchorElement>;
+
+/**
+ * Component prop type using inferred HTML anchor element props
  */
 type PaginationLinkProps = {
   /**
    * Whether this link represents the currently active page
    *
-   * When true, applies active styling and adds aria-current="page"
-   * for screen reader accessibility.
+   * When true, applies active styling (outline variant) and adds aria-current="page"
+   * for screen reader accessibility. Active links use the "outline" button variant
+   * while inactive links use the "ghost" variant from buttonVariants.
    *
    * @default false
    */
   isActive?: boolean;
-} & Pick<React.ComponentProps<typeof Button>, "size"> &
-  React.ComponentProps<"a">;
+  /**
+   * Size variant inherited from Button component
+   *
+   * Controls the dimensions and padding of the pagination link:
+   * - "default": Standard height (36px) with balanced padding
+   * - "sm": Small height (32px) for compact interfaces
+   * - "lg": Large height (40px) for prominent actions
+   * - "icon": Square (36px × 36px) optimized for icon-only usage
+   *
+   * @default "icon"
+   */
+  size?: "default" | "sm" | "lg" | "icon";
+  /** URL or path to navigate to when the link is clicked */
+  href?: string;
+  /** Child content - typically page numbers or navigation text */
+  children?: React.ReactNode;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Click handler for custom navigation logic or analytics tracking */
+  onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+  /** ARIA label for screen readers - especially important for icon-only links */
+  "aria-label"?: string;
+  /** Indicates current page state for screen readers when isActive is true */
+  "aria-current"?: "page" | "step" | "location" | "date" | "time" | boolean;
+  /** References elements that describe this link */
+  "aria-describedby"?: string;
+  /** Indicates if the link is disabled (use with appropriate styling) */
+  "aria-disabled"?: boolean;
+  /** Tab index for focus management @default 0 */
+  tabIndex?: number;
+} & Omit<
+  React.ComponentProps<"a">,
+  "size" | "href" | "children" | "className" | "onClick" | "tabIndex"
+>;
 
 /**
  * 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.
+ * paginated content. Uses buttonVariants from the Button component to provide
+ * consistent styling - applies "outline" variant when active and "ghost" variant
+ * when inactive. Features automatic active state styling and comprehensive
+ * accessibility attributes.
+ *
+ * The component automatically inherits focus management, hover states, and
+ * proper spacing from the Button component's CVA configuration while maintaining
+ * semantic link behavior for proper navigation and SEO.
  *
  * @example
  * ```tsx
- * // Basic page links
+ * // Basic page links with different states
  * <PaginationLink href="/products?page=1">1</PaginationLink>
  * <PaginationLink href="/products?page=2" isActive>2</PaginationLink>
  * <PaginationLink href="/products?page=3">3</PaginationLink>
@@ -207,10 +474,10 @@ type PaginationLinkProps = {
  *
  * @example
  * ```tsx
- * // With Next.js Link
- * <PaginationLink asChild>
- *   <Link href="/search?q=react&page=1">1</Link>
- * </PaginationLink>
+ * // Different sizes using Button size variants
+ * <PaginationLink href="/page/1" size="sm">1</PaginationLink>
+ * <PaginationLink href="/page/2" size="default">2</PaginationLink>
+ * <PaginationLink href="/page/3" size="lg">3</PaginationLink>
  * ```
  *
  * @example
@@ -222,16 +489,41 @@ type PaginationLinkProps = {
  *     e.preventDefault();
  *     onPageChange(1);
  *   }}
+ *   aria-label="Go to page 1"
  * >
  *   1
  * </PaginationLink>
  * ```
  *
+ * @example
+ * ```tsx
+ * // Disabled state for out-of-bounds pages
+ * <PaginationLink
+ *   href="#"
+ *   className="pointer-events-none opacity-50"
+ *   aria-disabled="true"
+ *   tabIndex={-1}
+ * >
+ *   5
+ * </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
+ * - Inherits button-style focus indicators from buttonVariants (3px ring)
+ * - High color contrast for active/inactive states meeting WCAG 2.1 AA
+ * - Touch-friendly minimum target size from Button component
+ * - Full keyboard navigation support (Tab, Enter, Space)
+ * - Screen reader friendly with proper link semantics
+ * - Supports aria-disabled for unavailable pages
+ *
+ * @variant outline - Applied when isActive=true, provides clear active state indication
+ * @variant ghost - Applied when isActive=false, subtle hover states for navigation
+ *
+ * @size icon - Default size (36px × 36px) optimized for single digit page numbers
+ * @size default - Standard height (36px) with more horizontal padding for longer content
+ * @size sm - Compact height (32px) for dense pagination layouts
+ * @size lg - Large height (40px) for prominent pagination controls
  */
 function PaginationLink({
   className,
@@ -256,12 +548,71 @@ function PaginationLink({
   );
 }
 
+/**
+ * Props for PaginationPrevious component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace PaginationLink inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PaginationPreviousDocsProps = {
+  /** URL to navigate to for the previous page */
+  href?: string;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Click handler for custom navigation logic */
+  onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+  /** Override default aria-label for screen readers @default "Go to previous page" */
+  "aria-label"?: string;
+  /** Indicates if the button is disabled (use with appropriate styling) */
+  "aria-disabled"?: boolean;
+  /** Tab index for focus management @default 0 */
+  tabIndex?: number;
+  /** Custom id attribute for the previous button */
+  id?: string;
+  /** Title attribute for additional context on hover */
+  title?: string;
+  /** Target window for link navigation @default "_self" */
+  target?: "_self" | "_blank" | "_parent" | "_top";
+  /** Relationship between current document and linked document */
+  rel?: string;
+} & React.AnchorHTMLAttributes<HTMLAnchorElement>;
+
+/**
+ * Component prop type using PaginationLink props with size and isActive omitted
+ */
+type PaginationPreviousProps = {
+  /** URL to navigate to for the previous page */
+  href?: string;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Click handler for custom navigation logic */
+  onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+  /** Override default aria-label for screen readers @default "Go to previous page" */
+  "aria-label"?: string;
+  /** Indicates if the button is disabled (use with appropriate styling) */
+  "aria-disabled"?: boolean;
+  /** Tab index for focus management @default 0 */
+  tabIndex?: number;
+} & Omit<
+  React.ComponentProps<typeof PaginationLink>,
+  | "href"
+  | "className"
+  | "onClick"
+  | "aria-label"
+  | "tabIndex"
+  | "size"
+  | "isActive"
+>;
+
 /**
  * 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.
+ * Navigates to the previous page in the pagination sequence. Built on PaginationLink
+ * with fixed "default" size and includes a chevron-left icon for visual direction.
+ * Features responsive design that shows only an icon on mobile devices and
+ * icon with "Previous" text on larger screens for optimal user experience.
+ *
+ * Uses buttonVariants with "ghost" variant by default, inheriting all focus management,
+ * hover states, and accessibility features from the Button component.
  *
  * @example
  * ```tsx
@@ -276,6 +627,7 @@ function PaginationLink({
  *   href="#"
  *   className="pointer-events-none opacity-50"
  *   aria-disabled="true"
+ *   tabIndex={-1}
  * />
  * ```
  *
@@ -293,17 +645,25 @@ function PaginationLink({
  * />
  * ```
  *
+ * @example
+ * ```tsx
+ * // With custom aria-label for internationalization
+ * <PaginationPrevious
+ *   href="/page/4"
+ *   aria-label="Ir a la página anterior"
+ * />
+ * ```
+ *
  * @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
+ * - ChevronLeftIcon provides visual direction context
+ * - Responsive "Previous" text appears on sm screens and larger
+ * - Full keyboard navigation support (Tab, Enter, Space)
+ * - Inherits button focus indicators (3px ring) from buttonVariants
+ * - Should be disabled (aria-disabled="true") on first page to prevent confusion
+ * - Maintains semantic link behavior for proper navigation
  */
-function PaginationPrevious({
-  className,
-  ...props
-}: React.ComponentProps<typeof PaginationLink>) {
+function PaginationPrevious({ className, ...props }: PaginationPreviousProps) {
   return (
     <PaginationLink
       aria-label="Go to previous page"
@@ -317,12 +677,71 @@ function PaginationPrevious({
   );
 }
 
+/**
+ * Props for PaginationNext component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace PaginationLink inferred types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PaginationNextDocsProps = {
+  /** URL to navigate to for the next page */
+  href?: string;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Click handler for custom navigation logic */
+  onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+  /** Override default aria-label for screen readers @default "Go to next page" */
+  "aria-label"?: string;
+  /** Indicates if the button is disabled (use with appropriate styling) */
+  "aria-disabled"?: boolean;
+  /** Tab index for focus management @default 0 */
+  tabIndex?: number;
+  /** Custom id attribute for the next button */
+  id?: string;
+  /** Title attribute for additional context on hover */
+  title?: string;
+  /** Target window for link navigation @default "_self" */
+  target?: "_self" | "_blank" | "_parent" | "_top";
+  /** Relationship between current document and linked document */
+  rel?: string;
+} & React.AnchorHTMLAttributes<HTMLAnchorElement>;
+
+/**
+ * Component prop type using PaginationLink props with size and isActive omitted
+ */
+type PaginationNextProps = {
+  /** URL to navigate to for the next page */
+  href?: string;
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Click handler for custom navigation logic */
+  onClick?: React.MouseEventHandler<HTMLAnchorElement>;
+  /** Override default aria-label for screen readers @default "Go to next page" */
+  "aria-label"?: string;
+  /** Indicates if the button is disabled (use with appropriate styling) */
+  "aria-disabled"?: boolean;
+  /** Tab index for focus management @default 0 */
+  tabIndex?: number;
+} & Omit<
+  React.ComponentProps<typeof PaginationLink>,
+  | "href"
+  | "className"
+  | "onClick"
+  | "aria-label"
+  | "tabIndex"
+  | "size"
+  | "isActive"
+>;
+
 /**
  * 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.
+ * Navigates to the next page in the pagination sequence. Built on PaginationLink
+ * with fixed "default" size and includes a chevron-right icon for visual direction.
+ * Features responsive design that shows only an icon on mobile devices and
+ * "Next" text with icon on larger screens for optimal user experience.
+ *
+ * Uses buttonVariants with "ghost" variant by default, inheriting all focus management,
+ * hover states, and accessibility features from the Button component.
  *
  * @example
  * ```tsx
@@ -337,6 +756,7 @@ function PaginationPrevious({
  *   href="#"
  *   className="pointer-events-none opacity-50"
  *   aria-disabled="true"
+ *   tabIndex={-1}
  * />
  * ```
  *
@@ -354,17 +774,25 @@ function PaginationPrevious({
  * />
  * ```
  *
+ * @example
+ * ```tsx
+ * // With custom aria-label for internationalization
+ * <PaginationNext
+ *   href="/page/6"
+ *   aria-label="Ir a la página siguiente"
+ * />
+ * ```
+ *
  * @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
+ * - ChevronRightIcon provides visual direction context
+ * - Responsive "Next" text appears on sm screens and larger
+ * - Full keyboard navigation support (Tab, Enter, Space)
+ * - Inherits button focus indicators (3px ring) from buttonVariants
+ * - Should be disabled (aria-disabled="true") on last page to prevent confusion
+ * - Maintains semantic link behavior for proper navigation
  */
-function PaginationNext({
-  className,
-  ...props
-}: React.ComponentProps<typeof PaginationLink>) {
+function PaginationNext({ className, ...props }: PaginationNextProps) {
   return (
     <PaginationLink
       aria-label="Go to next page"
@@ -378,12 +806,47 @@ function PaginationNext({
   );
 }
 
+/**
+ * Props for PaginationEllipsis component (Documentation only - NOT used in component implementation)
+ * These types are for documentation generation and should not replace inferred HTML element types
+ */
+// eslint-disable-next-line unused-imports/no-unused-vars
+type PaginationEllipsisDocsProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Override default aria-hidden behavior for custom accessibility @default true */
+  "aria-hidden"?: boolean;
+  /** Custom id attribute for the ellipsis element */
+  id?: string;
+  /** Tab index for focus management @default -1 */
+  tabIndex?: number;
+  /** Title attribute for additional context on hover */
+  title?: string;
+  /** ARIA label for screen readers (usually omitted as element is aria-hidden) */
+  "aria-label"?: string;
+} & React.HTMLAttributes<HTMLSpanElement>;
+
+/**
+ * Component prop type using inferred HTML span element props
+ */
+type PaginationEllipsisProps = {
+  /** Additional CSS classes for custom styling */
+  className?: string;
+  /** Override default aria-hidden behavior for custom accessibility @default true */
+  "aria-hidden"?: boolean;
+} & Omit<React.ComponentProps<"span">, "className" | "aria-hidden">;
+
 /**
  * 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.
+ * Displays a horizontal ellipsis (MoreHorizontalIcon from Lucide React) to indicate
+ * that page numbers have been omitted from the pagination display. Used to maintain
+ * clean UI when dealing with large page ranges without overwhelming users.
+ *
+ * The component is sized consistently with PaginationLink components (36px × 36px)
+ * to maintain visual harmony in the pagination layout. Includes accessible hidden
+ * text for screen readers while keeping the visual element hidden from assistive
+ * technology to avoid confusion.
  *
  * @example
  * ```tsx
@@ -402,7 +865,7 @@ function PaginationNext({
  * @example
  * ```tsx
  * // Common pagination pattern with ellipsis
- * // 1 ... 23 24 [25] 26 27 ... 100
+ * // Layout: 1 ... 23 24 [25] 26 27 ... 100
  * <PaginationContent>
  *   <PaginationItem>
  *     <PaginationLink href="/page/1">1</PaginationLink>
@@ -411,9 +874,21 @@ function PaginationNext({
  *     <PaginationEllipsis />
  *   </PaginationItem>
  *   <PaginationItem>
+ *     <PaginationLink href="/page/23">23</PaginationLink>
+ *   </PaginationItem>
+ *   <PaginationItem>
+ *     <PaginationLink href="/page/24">24</PaginationLink>
+ *   </PaginationItem>
+ *   <PaginationItem>
  *     <PaginationLink href="/page/25" isActive>25</PaginationLink>
  *   </PaginationItem>
  *   <PaginationItem>
+ *     <PaginationLink href="/page/26">26</PaginationLink>
+ *   </PaginationItem>
+ *   <PaginationItem>
+ *     <PaginationLink href="/page/27">27</PaginationLink>
+ *   </PaginationItem>
+ *   <PaginationItem>
  *     <PaginationEllipsis />
  *   </PaginationItem>
  *   <PaginationItem>
@@ -422,16 +897,20 @@ function PaginationNext({
  * </PaginationContent>
  * ```
  *
+ * @example
+ * ```tsx
+ * // With custom styling for different themes
+ * <PaginationEllipsis className="text-muted-foreground/60" />
+ * ```
+ *
  * @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
+ * - Visual MoreHorizontalIcon is aria-hidden from screen readers to avoid clutter
+ * - Hidden "More pages" text (sr-only) provides context for assistive technology
+ * - Non-interactive, purely decorative indicator that doesn't receive focus
+ * - Consistent 36px × 36px sizing matches PaginationLink for visual alignment
+ * - Screen readers understand this indicates omitted content without confusion
  */
-function PaginationEllipsis({
-  className,
-  ...props
-}: React.ComponentProps<"span">) {
+function PaginationEllipsis({ className, ...props }: PaginationEllipsisProps) {
   return (
     <span
       aria-hidden
@@ -454,3 +933,6 @@ export {
   PaginationNext,
   PaginationPrevious,
 };
+
+// Note: Component prop types are internal to this module and not exported
+// DocsProps types are for documentation generation only