xertica-ui 2.2.1 → 2.4.0

package/components/ui/pagination/pagination.tsx

@@ -1,140 +1,140 @@
-import * as React from 'react';
-import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from 'lucide-react';
-
-import { cn } from '../../shared/utils';
-import { Button, buttonVariants } from '../button';
-
-/**
- * Page navigation controls for paginated data sets.
- *
- * @description
- * Composes horizontal pagination with numbered links, ellipses, and
- * Previous/Next controls. Follows ARIA navigation landmark patterns.
- *
- * @ai-rules
- * 1. Compose in order: `Pagination > PaginationContent > PaginationItem > (PaginationLink | PaginationNext | PaginationPrevious)`.
- * 2. In SPAs, set `href="#"` on `<PaginationLink>` and handle page change via `onClick` to prevent native page reloads.
- * 3. Mark the currently active page with `isActive={true}` on `<PaginationLink>`.
- */
-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}
-    />
-  );
-}
-
-function PaginationContent({ className, ...props }: React.ComponentProps<'ul'>) {
-  return (
-    <ul
-      data-slot="pagination-content"
-      className={cn('flex flex-row items-center gap-1', className)}
-      {...props}
-    />
-  );
-}
-
-function PaginationItem({ ...props }: React.ComponentProps<'li'>) {
-  return <li data-slot="pagination-item" {...props} />;
-}
-
-type PaginationLinkProps = {
-  isActive?: boolean;
-  disabled?: boolean;
-} & Pick<React.ComponentProps<typeof Button>, 'size'> &
-  React.ComponentProps<'a'>;
-
-function PaginationLink({
-  className,
-  isActive,
-  disabled,
-  size = 'icon',
-  href,
-  ...props
-}: PaginationLinkProps) {
-  return (
-    <a
-      aria-current={isActive ? 'page' : undefined}
-      aria-disabled={disabled || undefined}
-      tabIndex={disabled ? -1 : undefined}
-      data-slot="pagination-link"
-      data-active={isActive}
-      href={disabled ? undefined : (href ?? '#')}
-      className={cn(
-        buttonVariants({
-          variant: isActive ? 'outline' : 'ghost',
-          size,
-        }),
-        disabled && 'pointer-events-none opacity-50',
-        className
-      )}
-      {...props}
-    />
-  );
-}
-
-function PaginationPrevious({
-  className,
-  disabled,
-  ...props
-}: React.ComponentProps<typeof PaginationLink>) {
-  return (
-    <PaginationLink
-      aria-label="Go to previous page"
-      size="default"
-      disabled={disabled}
-      className={cn('gap-1 px-2.5 sm:pl-2.5', className)}
-      {...props}
-    >
-      <ChevronLeftIcon />
-      <span className="hidden sm:block">Previous</span>
-    </PaginationLink>
-  );
-}
-
-function PaginationNext({
-  className,
-  disabled,
-  ...props
-}: React.ComponentProps<typeof PaginationLink>) {
-  return (
-    <PaginationLink
-      aria-label="Go to next page"
-      size="default"
-      disabled={disabled}
-      className={cn('gap-1 px-2.5 sm:pr-2.5', className)}
-      {...props}
-    >
-      <span className="hidden sm:block">Next</span>
-      <ChevronRightIcon />
-    </PaginationLink>
-  );
-}
-
-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,
-  PaginationLink,
-  PaginationItem,
-  PaginationPrevious,
-  PaginationNext,
-  PaginationEllipsis,
-};
+import * as React from 'react';
+import { ChevronLeftIcon, ChevronRightIcon, MoreHorizontalIcon } from 'lucide-react';
+
+import { cn } from '../../shared/utils';
+import { Button, buttonVariants } from '../button';
+
+/**
+ * Page navigation controls for paginated data sets.
+ *
+ * @description
+ * Composes horizontal pagination with numbered links, ellipses, and
+ * Previous/Next controls. Follows ARIA navigation landmark patterns.
+ *
+ * @ai-rules
+ * 1. Compose in order: `Pagination > PaginationContent > PaginationItem > (PaginationLink | PaginationNext | PaginationPrevious)`.
+ * 2. In SPAs, set `href="#"` on `<PaginationLink>` and handle page change via `onClick` to prevent native page reloads.
+ * 3. Mark the currently active page with `isActive={true}` on `<PaginationLink>`.
+ */
+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}
+    />
+  );
+}
+
+function PaginationContent({ className, ...props }: React.ComponentProps<'ul'>) {
+  return (
+    <ul
+      data-slot="pagination-content"
+      className={cn('flex flex-row items-center gap-1', className)}
+      {...props}
+    />
+  );
+}
+
+function PaginationItem({ ...props }: React.ComponentProps<'li'>) {
+  return <li data-slot="pagination-item" {...props} />;
+}
+
+type PaginationLinkProps = {
+  isActive?: boolean;
+  disabled?: boolean;
+} & Pick<React.ComponentProps<typeof Button>, 'size'> &
+  React.ComponentProps<'a'>;
+
+function PaginationLink({
+  className,
+  isActive,
+  disabled,
+  size = 'icon',
+  href,
+  ...props
+}: PaginationLinkProps) {
+  return (
+    <a
+      aria-current={isActive ? 'page' : undefined}
+      aria-disabled={disabled || undefined}
+      tabIndex={disabled ? -1 : undefined}
+      data-slot="pagination-link"
+      data-active={isActive}
+      href={disabled ? undefined : (href ?? '#')}
+      className={cn(
+        buttonVariants({
+          variant: isActive ? 'outline' : 'ghost',
+          size,
+        }),
+        disabled && 'pointer-events-none opacity-50',
+        className
+      )}
+      {...props}
+    />
+  );
+}
+
+function PaginationPrevious({
+  className,
+  disabled,
+  ...props
+}: React.ComponentProps<typeof PaginationLink>) {
+  return (
+    <PaginationLink
+      aria-label="Go to previous page"
+      size="default"
+      disabled={disabled}
+      className={cn('gap-1 px-2.5 sm:pl-2.5', className)}
+      {...props}
+    >
+      <ChevronLeftIcon />
+      <span className="hidden sm:block">Previous</span>
+    </PaginationLink>
+  );
+}
+
+function PaginationNext({
+  className,
+  disabled,
+  ...props
+}: React.ComponentProps<typeof PaginationLink>) {
+  return (
+    <PaginationLink
+      aria-label="Go to next page"
+      size="default"
+      disabled={disabled}
+      className={cn('gap-1 px-2.5 sm:pr-2.5', className)}
+      {...props}
+    >
+      <span className="hidden sm:block">Next</span>
+      <ChevronRightIcon />
+    </PaginationLink>
+  );
+}
+
+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,
+  PaginationLink,
+  PaginationItem,
+  PaginationPrevious,
+  PaginationNext,
+  PaginationEllipsis,
+};

package/components/ui/pagination/use-pagination.ts

@@ -1,173 +1,173 @@
-import { useState, useCallback, useMemo } from 'react';
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Types
-// ─────────────────────────────────────────────────────────────────────────────
-
-/** A page item rendered in the pagination bar. */
-export type PaginationPageItem = { type: 'page'; page: number } | { type: 'ellipsis'; key: string };
-
-export interface UsePaginationProps {
-  /** Total number of items in the data set. */
-  totalItems: number;
-  /** Number of items per page. @default 10 */
-  pageSize?: number;
-  /** Initial page (1-indexed). @default 1 */
-  initialPage?: number;
-  /**
-   * Controlled current page (1-indexed).
-   * When provided, page state is managed externally via `onPageChange`.
-   */
-  page?: number;
-  /** Called whenever the page changes. */
-  onPageChange?: (page: number) => void;
-  /**
-   * Number of page buttons to show on each side of the current page.
-   * @default 1
-   */
-  siblingCount?: number;
-}
-
-export interface UsePaginationReturn {
-  // ── State ─────────────────────────────────────────────────────────────────
-  /** The currently active page (1-indexed). */
-  currentPage: number;
-  /** Total number of pages. */
-  totalPages: number;
-  /** Index of the first item on the current page (0-indexed, useful for slicing). */
-  startIndex: number;
-  /** Index of the last item on the current page (exclusive, useful for slicing). */
-  endIndex: number;
-
-  // ── Flags ─────────────────────────────────────────────────────────────────
-  /** Whether there is a previous page available. */
-  canGoPrev: boolean;
-  /** Whether there is a next page available. */
-  canGoNext: boolean;
-  /** Whether the current page is the first page. */
-  isFirstPage: boolean;
-  /** Whether the current page is the last page. */
-  isLastPage: boolean;
-
-  // ── Computed ──────────────────────────────────────────────────────────────
-  /**
-   * Ordered list of items to render in the pagination bar.
-   * Each item is either a `{ type: 'page', page: number }` or
-   * `{ type: 'ellipsis', key: string }`.
-   */
-  items: PaginationPageItem[];
-
-  // ── Handlers ──────────────────────────────────────────────────────────────
-  /** Navigate to a specific page (1-indexed, clamped to valid range). */
-  goTo: (page: number) => void;
-  /** Navigate to the next page (no-op if already on the last page). */
-  next: () => void;
-  /** Navigate to the previous page (no-op if already on the first page). */
-  prev: () => void;
-  /** Navigate to the first page. */
-  first: () => void;
-  /** Navigate to the last page. */
-  last: () => void;
-}
-
-// ─────────────────────────────────────────────────────────────────────────────
-// Hook
-// ─────────────────────────────────────────────────────────────────────────────
-
-/**
- * Headless hook for pagination logic.
- *
- * @description
- * Computes the current page, total pages, slice indices, and the ordered list
- * of page items (numbers + ellipses) to render. Supports both controlled and
- * uncontrolled modes. Pair with any custom pagination UI or with the
- * `<Pagination>` visual components.
- *
- * @example
- * ```tsx
- * const { currentPage, totalPages, items, next, prev, goTo, canGoPrev, canGoNext } =
- *   usePagination({ totalItems: 200, pageSize: 20 });
- * ```
- */
-export function usePagination({
-  totalItems,
-  pageSize = 10,
-  initialPage = 1,
-  page: controlledPage,
-  onPageChange,
-  siblingCount = 1,
-}: UsePaginationProps): UsePaginationReturn {
-  const [internalPage, setInternalPage] = useState(initialPage);
-
-  const isControlled = controlledPage !== undefined;
-  const currentPage = isControlled ? controlledPage! : internalPage;
-
-  const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
-
-  const setPage = useCallback(
-    (p: number) => {
-      const clamped = Math.min(Math.max(1, p), totalPages);
-      if (!isControlled) setInternalPage(clamped);
-      onPageChange?.(clamped);
-    },
-    [isControlled, onPageChange, totalPages]
-  );
-
-  // ── Derived ───────────────────────────────────────────────────────────────
-
-  const startIndex = (currentPage - 1) * pageSize;
-  const endIndex = Math.min(startIndex + pageSize, totalItems);
-  const canGoPrev = currentPage > 1;
-  const canGoNext = currentPage < totalPages;
-  const isFirstPage = currentPage === 1;
-  const isLastPage = currentPage === totalPages;
-
-  // ── Page items (numbers + ellipses) ───────────────────────────────────────
-
-  const items = useMemo((): PaginationPageItem[] => {
-    const pageSet = new Set<number>();
-    pageSet.add(1);
-    if (totalPages > 1) pageSet.add(totalPages);
-    for (
-      let p = Math.max(2, currentPage - siblingCount);
-      p <= Math.min(totalPages - 1, currentPage + siblingCount);
-      p++
-    ) {
-      pageSet.add(p);
-    }
-    const sorted = Array.from(pageSet).sort((a, b) => a - b);
-    const result: PaginationPageItem[] = [];
-    for (let i = 0; i < sorted.length; i++) {
-      result.push({ type: 'page', page: sorted[i] });
-      if (i < sorted.length - 1 && sorted[i + 1] - sorted[i] > 1) {
-        result.push({ type: 'ellipsis', key: `ellipsis-${sorted[i]}` });
-      }
-    }
-    return result;
-  }, [currentPage, siblingCount, totalPages]);
-
-  // ── Handlers ──────────────────────────────────────────────────────────────
-
-  const goTo = useCallback((p: number) => setPage(p), [setPage]);
-  const next = useCallback(() => setPage(currentPage + 1), [currentPage, setPage]);
-  const prev = useCallback(() => setPage(currentPage - 1), [currentPage, setPage]);
-  const first = useCallback(() => setPage(1), [setPage]);
-  const last = useCallback(() => setPage(totalPages), [setPage, totalPages]);
-
-  return {
-    currentPage,
-    totalPages,
-    startIndex,
-    endIndex,
-    canGoPrev,
-    canGoNext,
-    isFirstPage,
-    isLastPage,
-    items,
-    goTo,
-    next,
-    prev,
-    first,
-    last,
-  };
-}
+import { useState, useCallback, useMemo } from 'react';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** A page item rendered in the pagination bar. */
+export type PaginationPageItem = { type: 'page'; page: number } | { type: 'ellipsis'; key: string };
+
+export interface UsePaginationProps {
+  /** Total number of items in the data set. */
+  totalItems: number;
+  /** Number of items per page. @default 10 */
+  pageSize?: number;
+  /** Initial page (1-indexed). @default 1 */
+  initialPage?: number;
+  /**
+   * Controlled current page (1-indexed).
+   * When provided, page state is managed externally via `onPageChange`.
+   */
+  page?: number;
+  /** Called whenever the page changes. */
+  onPageChange?: (page: number) => void;
+  /**
+   * Number of page buttons to show on each side of the current page.
+   * @default 1
+   */
+  siblingCount?: number;
+}
+
+export interface UsePaginationReturn {
+  // ── State ─────────────────────────────────────────────────────────────────
+  /** The currently active page (1-indexed). */
+  currentPage: number;
+  /** Total number of pages. */
+  totalPages: number;
+  /** Index of the first item on the current page (0-indexed, useful for slicing). */
+  startIndex: number;
+  /** Index of the last item on the current page (exclusive, useful for slicing). */
+  endIndex: number;
+
+  // ── Flags ─────────────────────────────────────────────────────────────────
+  /** Whether there is a previous page available. */
+  canGoPrev: boolean;
+  /** Whether there is a next page available. */
+  canGoNext: boolean;
+  /** Whether the current page is the first page. */
+  isFirstPage: boolean;
+  /** Whether the current page is the last page. */
+  isLastPage: boolean;
+
+  // ── Computed ──────────────────────────────────────────────────────────────
+  /**
+   * Ordered list of items to render in the pagination bar.
+   * Each item is either a `{ type: 'page', page: number }` or
+   * `{ type: 'ellipsis', key: string }`.
+   */
+  items: PaginationPageItem[];
+
+  // ── Handlers ──────────────────────────────────────────────────────────────
+  /** Navigate to a specific page (1-indexed, clamped to valid range). */
+  goTo: (page: number) => void;
+  /** Navigate to the next page (no-op if already on the last page). */
+  next: () => void;
+  /** Navigate to the previous page (no-op if already on the first page). */
+  prev: () => void;
+  /** Navigate to the first page. */
+  first: () => void;
+  /** Navigate to the last page. */
+  last: () => void;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Headless hook for pagination logic.
+ *
+ * @description
+ * Computes the current page, total pages, slice indices, and the ordered list
+ * of page items (numbers + ellipses) to render. Supports both controlled and
+ * uncontrolled modes. Pair with any custom pagination UI or with the
+ * `<Pagination>` visual components.
+ *
+ * @example
+ * ```tsx
+ * const { currentPage, totalPages, items, next, prev, goTo, canGoPrev, canGoNext } =
+ *   usePagination({ totalItems: 200, pageSize: 20 });
+ * ```
+ */
+export function usePagination({
+  totalItems,
+  pageSize = 10,
+  initialPage = 1,
+  page: controlledPage,
+  onPageChange,
+  siblingCount = 1,
+}: UsePaginationProps): UsePaginationReturn {
+  const [internalPage, setInternalPage] = useState(initialPage);
+
+  const isControlled = controlledPage !== undefined;
+  const currentPage = isControlled ? controlledPage! : internalPage;
+
+  const totalPages = Math.max(1, Math.ceil(totalItems / pageSize));
+
+  const setPage = useCallback(
+    (p: number) => {
+      const clamped = Math.min(Math.max(1, p), totalPages);
+      if (!isControlled) setInternalPage(clamped);
+      onPageChange?.(clamped);
+    },
+    [isControlled, onPageChange, totalPages]
+  );
+
+  // ── Derived ───────────────────────────────────────────────────────────────
+
+  const startIndex = (currentPage - 1) * pageSize;
+  const endIndex = Math.min(startIndex + pageSize, totalItems);
+  const canGoPrev = currentPage > 1;
+  const canGoNext = currentPage < totalPages;
+  const isFirstPage = currentPage === 1;
+  const isLastPage = currentPage === totalPages;
+
+  // ── Page items (numbers + ellipses) ───────────────────────────────────────
+
+  const items = useMemo((): PaginationPageItem[] => {
+    const pageSet = new Set<number>();
+    pageSet.add(1);
+    if (totalPages > 1) pageSet.add(totalPages);
+    for (
+      let p = Math.max(2, currentPage - siblingCount);
+      p <= Math.min(totalPages - 1, currentPage + siblingCount);
+      p++
+    ) {
+      pageSet.add(p);
+    }
+    const sorted = Array.from(pageSet).sort((a, b) => a - b);
+    const result: PaginationPageItem[] = [];
+    for (let i = 0; i < sorted.length; i++) {
+      result.push({ type: 'page', page: sorted[i] });
+      if (i < sorted.length - 1 && sorted[i + 1] - sorted[i] > 1) {
+        result.push({ type: 'ellipsis', key: `ellipsis-${sorted[i]}` });
+      }
+    }
+    return result;
+  }, [currentPage, siblingCount, totalPages]);
+
+  // ── Handlers ──────────────────────────────────────────────────────────────
+
+  const goTo = useCallback((p: number) => setPage(p), [setPage]);
+  const next = useCallback(() => setPage(currentPage + 1), [currentPage, setPage]);
+  const prev = useCallback(() => setPage(currentPage - 1), [currentPage, setPage]);
+  const first = useCallback(() => setPage(1), [setPage]);
+  const last = useCallback(() => setPage(totalPages), [setPage, totalPages]);
+
+  return {
+    currentPage,
+    totalPages,
+    startIndex,
+    endIndex,
+    canGoPrev,
+    canGoNext,
+    isFirstPage,
+    isLastPage,
+    items,
+    goTo,
+    next,
+    prev,
+    first,
+    last,
+  };
+}

package/components/ui/popover/index.ts

@@ -1 +1 @@
-export * from './popover';
+export * from './popover';