@neynar/ui 0.4.0 → 0.5.0

package/src/components/ui/pagination.tsx

@@ -1,226 +1,17 @@
+import * as React from "react";
+
+import { cn } from "@/lib/utils";
+import { Button } from "@/components/ui/button";
 import {
   ChevronLeftIcon,
   ChevronRightIcon,
   MoreHorizontalIcon,
 } from "lucide-react";
-import * as React from "react";
 
-import { cn } from "@/lib/utils";
-import { buttonVariants } from "@/components/ui/button";
+type PaginationProps = React.ComponentProps<"nav">;
 
 /**
- * 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. 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
- *
- * 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
- * // Basic pagination with numbered pages
- * <Pagination>
- *   <PaginationContent>
- *     <PaginationItem>
- *       <PaginationPrevious href="/products?page=1" />
- *     </PaginationItem>
- *     <PaginationItem>
- *       <PaginationLink href="/products?page=1">1</PaginationLink>
- *     </PaginationItem>
- *     <PaginationItem>
- *       <PaginationLink href="/products?page=2" isActive>2</PaginationLink>
- *     </PaginationItem>
- *     <PaginationItem>
- *       <PaginationLink href="/products?page=3">3</PaginationLink>
- *     </PaginationItem>
- *     <PaginationItem>
- *       <PaginationNext href="/products?page=3" />
- *     </PaginationItem>
- *   </PaginationContent>
- * </Pagination>
- * ```
- *
- * @example
- * ```tsx
- * // Complete pagination with ellipsis for large datasets
- * <Pagination>
- *   <PaginationContent>
- *     <PaginationItem>
- *       <PaginationPrevious href="/search?q=react&page=4" />
- *     </PaginationItem>
- *     <PaginationItem>
- *       <PaginationLink href="/search?q=react&page=1">1</PaginationLink>
- *     </PaginationItem>
- *     <PaginationItem>
- *       <PaginationEllipsis />
- *     </PaginationItem>
- *     <PaginationItem>
- *       <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="/search?q=react&page=50">50</PaginationLink>
- *     </PaginationItem>
- *     <PaginationItem>
- *       <PaginationNext href="/search?q=react&page=6" />
- *     </PaginationItem>
- *   </PaginationContent>
- * </Pagination>
- * ```
- *
- * @example
- * ```tsx
- * // 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 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>
- * ```
- *
- * @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 (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
- * @see {@link PaginationNext} Next page navigation button
- * @see {@link PaginationEllipsis} Ellipsis indicator for omitted pages
- * @since 1.0.0
+ * Root pagination navigation container.
  */
 function Pagination({ className, ...props }: PaginationProps) {
   return (
@@ -234,296 +25,38 @@ function Pagination({ className, ...props }: PaginationProps) {
   );
 }
 
-/**
- * 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>;
+type PaginationContentProps = React.ComponentProps<"ul">;
 
 /**
- * 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
- *
- * 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
+ * Container for pagination items. Renders as a flex list.
  */
 function PaginationContent({ className, ...props }: PaginationContentProps) {
   return (
     <ul
       data-slot="pagination-content"
-      className={cn("flex flex-row items-center gap-1", className)}
+      className={cn("gap-1 flex items-center", className)}
       {...props}
     />
   );
 }
 
-/**
- * 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">;
+type PaginationItemProps = React.ComponentProps<"li">;
 
 /**
- * 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>
- * ```
+ * Wrapper for individual pagination elements (links, ellipsis, controls).
  */
 function PaginationItem({ ...props }: PaginationItemProps) {
   return <li data-slot="pagination-item" {...props} />;
 }
 
-/**
- * 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 (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
-   */
+  /** Whether this page link is the current active page. */
   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;
-} & Omit<
-  React.ComponentProps<"a">,
-  "size" | "href" | "children" | "className" | "onClick" | "tabIndex"
->;
+} & 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. 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 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>
- * ```
- *
- * @example
- * ```tsx
- * // 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
- * ```tsx
- * // With onClick handlers for client-side pagination
- * <PaginationLink
- *   href="#"
- *   onClick={(e) => {
- *     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
- * - 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
+ * Clickable page number link. Use `isActive` to highlight the current page.
  */
 function PaginationLink({
   className,
@@ -532,393 +65,78 @@ function PaginationLink({
   ...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}
+    <Button
+      variant={isActive ? "outline" : "ghost"}
+      size={size}
+      className={cn(className)}
+      nativeButton={false}
+      render={
+        <a
+          aria-current={isActive ? "page" : undefined}
+          data-slot="pagination-link"
+          data-active={isActive}
+          {...props}
+        />
+      }
     />
   );
 }
 
-/**
- * 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"
->;
+type PaginationPreviousProps = React.ComponentProps<typeof PaginationLink>;
 
 /**
- * Previous page navigation button
- *
- * 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
- * // 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"
- *   tabIndex={-1}
- * />
- * ```
- *
- * @example
- * ```tsx
- * // With click handler for client-side navigation
- * <PaginationPrevious
- *   href="#"
- *   onClick={(e) => {
- *     e.preventDefault();
- *     if (currentPage > 1) {
- *       onPageChange(currentPage - 1);
- *     }
- *   }}
- * />
- * ```
- *
- * @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
- * - 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
+ * Previous page button with chevron icon and "Previous" text (hidden on mobile).
  */
 function PaginationPrevious({ className, ...props }: PaginationPreviousProps) {
   return (
     <PaginationLink
       aria-label="Go to previous page"
       size="default"
-      className={cn("gap-1 px-2.5 sm:pl-2.5", className)}
+      className={cn("pl-2!", className)}
       {...props}
     >
-      <ChevronLeftIcon />
+      <ChevronLeftIcon data-icon="inline-start" />
       <span className="hidden sm:block">Previous</span>
     </PaginationLink>
   );
 }
 
-/**
- * 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>;
+type PaginationNextProps = React.ComponentProps<typeof PaginationLink>;
 
 /**
- * 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. 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
- * // 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"
- *   tabIndex={-1}
- * />
- * ```
- *
- * @example
- * ```tsx
- * // With click handler for client-side navigation
- * <PaginationNext
- *   href="#"
- *   onClick={(e) => {
- *     e.preventDefault();
- *     if (currentPage < totalPages) {
- *       onPageChange(currentPage + 1);
- *     }
- *   }}
- * />
- * ```
- *
- * @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
- * - 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
+ * Next page button with chevron icon and "Next" text (hidden on mobile).
  */
 function PaginationNext({ className, ...props }: PaginationNextProps) {
   return (
     <PaginationLink
       aria-label="Go to next page"
       size="default"
-      className={cn("gap-1 px-2.5 sm:pr-2.5", className)}
+      className={cn("pr-2!", className)}
       {...props}
     >
       <span className="hidden sm:block">Next</span>
-      <ChevronRightIcon />
+      <ChevronRightIcon data-icon="inline-end" />
     </PaginationLink>
   );
 }
 
-/**
- * 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">;
+type PaginationEllipsisProps = React.ComponentProps<"span">;
 
 /**
- * Visual indicator for omitted page numbers
- *
- * 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
- * // 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
- * // Layout: 1 ... 23 24 [25] 26 27 ... 100
- * <PaginationContent>
- *   <PaginationItem>
- *     <PaginationLink href="/page/1">1</PaginationLink>
- *   </PaginationItem>
- *   <PaginationItem>
- *     <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>
- *     <PaginationLink href="/page/100">100</PaginationLink>
- *   </PaginationItem>
- * </PaginationContent>
- * ```
- *
- * @example
- * ```tsx
- * // With custom styling for different themes
- * <PaginationEllipsis className="text-muted-foreground/60" />
- * ```
- *
- * @accessibility
- * - 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
+ * Ellipsis indicator for skipped pages. Use between page numbers to show truncated ranges.
  */
 function PaginationEllipsis({ className, ...props }: PaginationEllipsisProps) {
   return (
     <span
       aria-hidden
       data-slot="pagination-ellipsis"
-      className={cn("flex size-9 items-center justify-center", className)}
+      className={cn(
+        "size-9 items-center justify-center [&_svg:not([class*='size-'])]:size-4 flex items-center justify-center",
+        className,
+      )}
       {...props}
     >
-      <MoreHorizontalIcon className="size-4" />
+      <MoreHorizontalIcon />
       <span className="sr-only">More pages</span>
     </span>
   );
@@ -932,7 +150,11 @@ export {
   PaginationLink,
   PaginationNext,
   PaginationPrevious,
+  type PaginationProps,
+  type PaginationContentProps,
+  type PaginationItemProps,
+  type PaginationLinkProps,
+  type PaginationPreviousProps,
+  type PaginationNextProps,
+  type PaginationEllipsisProps,
 };
-
-// Note: Component prop types are internal to this module and not exported
-// DocsProps types are for documentation generation only