@brcarddev/frontend-commons 1.0.2

package/src/components/molecules/Pagination/pagination.test.tsx

@@ -0,0 +1,448 @@
+import { composeStories } from '@storybook/react';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+
+import { Pagination } from './pagination';
+import * as stories from './pagination.stories';
+
+const { Default } = composeStories(stories);
+
+describe('<Pagination />', () => {
+  const defaultProps = {
+    pageCount: 10,
+    pageIndex: 0,
+    setPageIndex: vi.fn(),
+    canPreviousPage: false,
+    canNextPage: true,
+    pageSize: 10,
+    setPageSize: vi.fn(),
+    previousPage: vi.fn(),
+    nextPage: vi.fn(),
+  };
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('should render the pagination component with navigation role', () => {
+      render(<Pagination {...defaultProps} />);
+
+      expect(screen.getByRole('navigation')).toBeInTheDocument();
+      expect(screen.getByLabelText('Paginação')).toBeInTheDocument();
+    });
+
+    it('should render page size selector by default', () => {
+      render(<Pagination {...defaultProps} />);
+
+      expect(screen.getByRole('combobox', { name: /itens por página/i })).toBeInTheDocument();
+    });
+
+    it('should hide page size selector when showPageSizeSelector is false', () => {
+      render(<Pagination {...defaultProps} showPageSizeSelector={false} />);
+
+      expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
+    });
+
+    it('should render custom aria-label', () => {
+      const customLabel = 'Navegação de páginas customizada';
+      render(<Pagination {...defaultProps} aria-label={customLabel} />);
+
+      expect(screen.getByLabelText(customLabel)).toBeInTheDocument();
+    });
+
+    it('should apply custom className', () => {
+      const customClass = 'custom-pagination-class';
+      render(<Pagination {...defaultProps} className={customClass} />);
+
+      expect(screen.getByRole('navigation')).toHaveClass(customClass);
+    });
+  });
+
+  describe('Page Navigation', () => {
+    it('should render previous and next buttons', () => {
+      render(<Pagination {...defaultProps} />);
+
+      expect(screen.getByRole('button', { name: /ir para página anterior/i })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: /ir para próxima página/i })).toBeInTheDocument();
+    });
+
+    it('should disable previous button when canPreviousPage is false', () => {
+      render(<Pagination {...defaultProps} canPreviousPage={false} />);
+
+      expect(screen.getByRole('button', { name: /ir para página anterior/i })).toBeDisabled();
+    });
+
+    it('should disable next button when canNextPage is false', () => {
+      render(<Pagination {...defaultProps} canNextPage={false} />);
+
+      expect(screen.getByRole('button', { name: /ir para próxima página/i })).toBeDisabled();
+    });
+
+    it('should call previousPage when previous button is clicked', async () => {
+      const user = userEvent.setup();
+      render(<Pagination {...defaultProps} canPreviousPage={true} />);
+
+      await user.click(screen.getByRole('button', { name: /ir para página anterior/i }));
+
+      expect(defaultProps.previousPage).toHaveBeenCalledTimes(1);
+    });
+
+    it('should call nextPage when next button is clicked', async () => {
+      const user = userEvent.setup();
+      render(<Pagination {...defaultProps} />);
+
+      await user.click(screen.getByRole('button', { name: /ir para próxima página/i }));
+
+      expect(defaultProps.nextPage).toHaveBeenCalledTimes(1);
+    });
+
+    it('should render custom button texts', () => {
+      render(
+        <Pagination
+          {...defaultProps}
+          previousPageText="Voltar"
+          nextPageText="Avançar"
+        />
+      );
+
+      expect(screen.getByText('Voltar')).toBeInTheDocument();
+      expect(screen.getByText('Avançar')).toBeInTheDocument();
+    });
+
+    it('should support keyboard navigation', async () => {
+      const user = userEvent.setup();
+      render(<Pagination {...defaultProps} canPreviousPage={true} />);
+
+      const previousButton = screen.getByRole('button', { name: /ir para página anterior/i });
+
+      await user.click(previousButton);
+      await user.keyboard('{Enter}');
+
+      expect(defaultProps.previousPage).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('Page Numbers', () => {
+    it('should render page numbers for few pages', () => {
+      render(<Pagination {...defaultProps} pageCount={5} />);
+
+      expect(screen.getByRole('button', { name: /página atual 1/i })).toBeInTheDocument();
+
+      for (let i = 2; i <= 5; i++) {
+        expect(screen.getByRole('button', { name: new RegExp(`ir para página ${i}`, 'i') })).toBeInTheDocument();
+      }
+    });
+
+    it('should render ellipsis for many pages', () => {
+      render(<Pagination {...defaultProps} pageCount={20} />);
+
+      expect(screen.getByText('...')).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: /página atual 1/i })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: /ir para página 20/i })).toBeInTheDocument();
+    });
+
+    it('should highlight current page', () => {
+      render(<Pagination {...defaultProps} pageIndex={2} />);
+
+      const currentPageButton = screen.getByRole('button', { name: /página atual 3/i });
+      expect(currentPageButton).toHaveAttribute('aria-current', 'page');
+    });
+
+    it('should call setPageIndex when page number is clicked', async () => {
+      const user = userEvent.setup();
+      render(<Pagination {...defaultProps} pageCount={5} />);
+
+      await user.click(screen.getByRole('button', { name: /ir para página 3/i }));
+
+      expect(defaultProps.setPageIndex).toHaveBeenCalledWith(2);
+    });
+
+    it('should not render page numbers when pageCount is 1', () => {
+      render(<Pagination {...defaultProps} pageCount={1} />);
+
+      expect(screen.queryByRole('group', { name: /páginas/i })).not.toBeInTheDocument();
+    });
+
+    it('should disable page buttons when pageCount is 1', () => {
+      render(<Pagination {...defaultProps} pageCount={1} />);
+
+      expect(screen.queryByRole('group', { name: /páginas/i })).not.toBeInTheDocument();
+    });
+
+    it('should render correct page structure for boundary values', () => {
+      render(<Pagination {...defaultProps} pageCount={7} />);
+
+      expect(screen.getByRole('button', { name: /página atual 1/i })).toBeInTheDocument();
+
+      for (let i = 2; i <= 7; i++) {
+        expect(screen.getByRole('button', { name: new RegExp(`ir para página ${i}`, 'i') })).toBeInTheDocument();
+      }
+
+      expect(screen.queryByText('...')).not.toBeInTheDocument();
+    });
+
+    it('should show ellipsis only when pageCount is greater than maxVisiblePages', () => {
+      render(<Pagination {...defaultProps} pageCount={8} maxVisiblePages={7} />);
+
+      expect(screen.getByText('...')).toBeInTheDocument();
+    });
+  });
+
+  describe('Page Size Selector', () => {
+    it('should render default page size options', () => {
+      render(<Pagination {...defaultProps} />);
+
+      const selector = screen.getByRole('combobox');
+      expect(selector).toHaveAttribute('aria-label', 'Itens por página: 10');
+    });
+
+    it('should render custom page size options', async () => {
+      const user = userEvent.setup();
+      const customOptions = [ 5, 15, 25 ];
+
+      render(<Pagination {...defaultProps} pageSizeOptions={customOptions} />);
+
+      await user.click(screen.getByRole('combobox'));
+
+      customOptions.forEach(size => {
+        expect(screen.getByText(`${size} itens`)).toBeInTheDocument();
+      });
+    });
+
+    it('should call setPageSize when page size is changed', async () => {
+      const user = userEvent.setup();
+      render(<Pagination {...defaultProps} />);
+
+      await user.click(screen.getByRole('combobox'));
+      await user.click(screen.getByText('20 itens'));
+
+      expect(defaultProps.setPageSize).toHaveBeenCalledWith(20);
+    });
+
+    it('should render custom page size label', async () => {
+      const user = userEvent.setup();
+      render(<Pagination {...defaultProps} pageSizeLabel="registros" />);
+
+      await user.click(screen.getByRole('combobox'));
+
+      expect(screen.getAllByText('10 registros')[0]).toBeInTheDocument();
+    });
+
+    it('should handle empty page size options gracefully', async () => {
+      const user = userEvent.setup();
+      render(<Pagination {...defaultProps} pageSizeOptions={[]} />);
+
+      await user.click(screen.getByRole('combobox'));
+
+      expect(screen.getByRole('listbox')).toBeInTheDocument();
+    });
+
+    it('should update display value when pageSize prop changes', () => {
+      const { rerender } = render(<Pagination {...defaultProps} pageSize={10} />);
+
+      expect(screen.getByLabelText('Itens por página: 10')).toBeInTheDocument();
+
+      rerender(<Pagination {...defaultProps} pageSize={20} />);
+
+      expect(screen.getByLabelText('Itens por página: 20')).toBeInTheDocument();
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('should have proper ARIA labels for navigation buttons', () => {
+      render(<Pagination {...defaultProps} pageIndex={1} canPreviousPage={true} />);
+
+      expect(screen.getByLabelText(/ir para página anterior, página 1/i)).toBeInTheDocument();
+      expect(screen.getByLabelText(/ir para próxima página, página 3/i)).toBeInTheDocument();
+    });
+
+    it('should have proper ARIA labels for page buttons', () => {
+      render(<Pagination {...defaultProps} pageCount={5} pageIndex={1} />);
+
+      expect(screen.getByLabelText(/página atual 2/i)).toBeInTheDocument();
+      expect(screen.getByLabelText(/ir para página 1/i)).toBeInTheDocument();
+      expect(screen.getByLabelText(/ir para página 3/i)).toBeInTheDocument();
+    });
+
+    it('should hide ellipsis from screen readers', () => {
+      render(<Pagination {...defaultProps} pageCount={20} />);
+
+      const ellipsisButton = screen.getByText('...');
+      expect(ellipsisButton).toHaveAttribute('aria-hidden', 'true');
+    });
+
+    it('should have proper page size selector label', () => {
+      render(<Pagination {...defaultProps} pageSize={20} />);
+
+      expect(screen.getByLabelText('Itens por página: 20')).toBeInTheDocument();
+    });
+
+    it('should support screen reader navigation with tab key', async () => {
+      const user = userEvent.setup();
+      render(<Pagination {...defaultProps} pageCount={5} canPreviousPage={true} />);
+
+      await user.tab();
+      expect(screen.getByRole('combobox')).toHaveFocus();
+
+      await user.tab();
+      expect(screen.getByRole('button', { name: /ir para página anterior/i })).toHaveFocus();
+
+      await user.tab();
+      expect(screen.getByRole('button', { name: /página atual 1/i })).toHaveFocus();
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('should handle pageCount of 0', () => {
+      render(<Pagination {...defaultProps} pageCount={0} />);
+
+      expect(screen.getByRole('navigation')).toBeInTheDocument();
+      expect(screen.queryByRole('group', { name: /páginas/i })).not.toBeInTheDocument();
+    });
+
+    it('should handle negative pageIndex gracefully', () => {
+      render(<Pagination {...defaultProps} pageIndex={-1} />);
+
+      expect(screen.getByRole('navigation')).toBeInTheDocument();
+    });
+
+    it('should respect maxVisiblePages prop', () => {
+      render(<Pagination {...defaultProps} pageCount={20} maxVisiblePages={5} />);
+
+      expect(screen.getByText('...')).toBeInTheDocument();
+    });
+
+    it('should handle pageIndex greater than pageCount', () => {
+      render(<Pagination {...defaultProps} pageCount={5} pageIndex={10} />);
+
+      expect(screen.getByRole('navigation')).toBeInTheDocument();
+    });
+
+    it('should handle very large pageCount values', () => {
+      render(<Pagination {...defaultProps} pageCount={9999} />);
+
+      expect(screen.getByRole('button', { name: /página 9999/i })).toBeInTheDocument();
+      expect(screen.getByText('...')).toBeInTheDocument();
+    });
+
+    it('should handle pageSize of 0', () => {
+      render(<Pagination {...defaultProps} pageSize={0} />);
+
+      expect(screen.getByLabelText('Itens por página: 0')).toBeInTheDocument();
+    });
+  });
+
+  describe('Responsive Design', () => {
+    it('should hide button text on small screens', () => {
+      render(<Pagination {...defaultProps} />);
+
+      const previousButton = screen.getByRole('button', { name: /ir para página anterior/i });
+      const nextButton = screen.getByRole('button', { name: /ir para próxima página/i });
+
+      expect(previousButton.querySelector('.hidden.sm\\:inline')).toBeInTheDocument();
+      expect(nextButton.querySelector('.hidden.sm\\:inline')).toBeInTheDocument();
+    });
+
+    it('should maintain button functionality even when text is hidden', async () => {
+      const user = userEvent.setup();
+      render(<Pagination {...defaultProps} canPreviousPage={true} />);
+
+      const previousButton = screen.getByRole('button', { name: /ir para página anterior/i });
+
+      await user.click(previousButton);
+
+      expect(defaultProps.previousPage).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe('Performance', () => {
+    it('should not re-render unnecessarily when props are stable', () => {
+      const { rerender } = render(<Pagination {...defaultProps} />);
+
+      const initialNavigation = screen.getByRole('navigation');
+
+      rerender(<Pagination {...defaultProps} />);
+
+      expect(screen.getByRole('navigation')).toBe(initialNavigation);
+    });
+
+    it('should memoize page generation correctly', () => {
+      const spy = vi.spyOn(console, 'log');
+      const { rerender } = render(<Pagination {...defaultProps} pageCount={10} />);
+
+      rerender(<Pagination {...defaultProps} pageCount={10} />);
+
+      rerender(<Pagination {...defaultProps} pageCount={15} />);
+
+      spy.mockRestore();
+    });
+  });
+
+  describe('Integration Tests', () => {
+    it('should work correctly in a typical user workflow', async () => {
+      const user = userEvent.setup();
+      const setPageIndex = vi.fn();
+      const setPageSize = vi.fn();
+      const nextPage = vi.fn();
+
+      render(
+        <Pagination
+          {...defaultProps}
+          pageCount={50}
+          pageIndex={0}
+          setPageIndex={setPageIndex}
+          setPageSize={setPageSize}
+          nextPage={nextPage}
+          canPreviousPage={false}
+          canNextPage={true}
+        />
+      );
+
+      await user.click(screen.getByRole('combobox'));
+      await user.click(screen.getByText('20 itens'));
+      expect(setPageSize).toHaveBeenCalledWith(20);
+
+      await user.click(screen.getByRole('button', { name: /ir para próxima página/i }));
+      expect(nextPage).toHaveBeenCalledTimes(1);
+
+      await user.click(screen.getByRole('button', { name: /ir para página 3/i }));
+      expect(setPageIndex).toHaveBeenCalledWith(2);
+    });
+
+    it('should handle rapid interactions gracefully', async () => {
+      const user = userEvent.setup();
+      const setPageIndex = vi.fn();
+
+      render(
+        <Pagination
+          {...defaultProps}
+          pageCount={10}
+          setPageIndex={setPageIndex}
+        />
+      );
+
+      const promises = [ 1, 2, 3 ].map(async (pageNum) => {
+        await user.click(screen.getByRole('button', { name: new RegExp(`ir para página ${pageNum}`, 'i') }));
+      });
+
+      await Promise.all(promises);
+
+      expect(setPageIndex).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe('Stories Integration', () => {
+    it('should render Default story correctly', () => {
+      render(<Default />);
+
+      expect(screen.getByRole('navigation')).toBeInTheDocument();
+    });
+
+    it('matches snapshot', () => {
+      const { container } = render(<Default />);
+      expect(container).toMatchSnapshot();
+    });
+  });
+});

package/src/components/molecules/Pagination/pagination.tsx

@@ -0,0 +1,206 @@
+import { useCallback, useMemo } from 'react';
+
+import { ArrowLeft, ArrowRight } from 'lucide-react';
+
+import { Button, Flex, Popover, PopoverContent, PopoverTrigger, RenderCondition, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@/components';
+import { cn } from '@/utils';
+
+interface PaginationProps {
+  pageCount: number;
+  pageIndex: number;
+  setPageIndex: (pageIndex: number) => void;
+  canPreviousPage: boolean;
+  canNextPage: boolean;
+  pageSize: number;
+  setPageSize: (pageSize: number) => void;
+  previousPage: () => void;
+  nextPage: () => void;
+  nextPageText?: string;
+  previousPageText?: string;
+  pageSizeOptions?: number[];
+  pageSizeLabel?: string;
+  showPageSizeSelector?: boolean;
+  maxVisiblePages?: number;
+  className?: string;
+  'aria-label'?: string;
+}
+
+function Pagination ({
+  pageCount,
+  pageIndex,
+  setPageIndex,
+  canPreviousPage,
+  canNextPage,
+  pageSize,
+  setPageSize,
+  previousPage,
+  nextPage,
+  nextPageText,
+  previousPageText,
+  pageSizeOptions = [ 10, 20, 30, 40, 50 ],
+  pageSizeLabel = 'itens',
+  showPageSizeSelector = true,
+  maxVisiblePages = 7,
+  className = '',
+  'aria-label': ariaLabel = 'Paginação',
+}: PaginationProps) {
+  const displayPages = useMemo(() => {
+    if (pageCount <= maxVisiblePages) {
+      return Array.from({ length: pageCount }, (_, i) => i + 1);
+    }
+
+    const pages: (number | string)[] = [];
+
+    pages.push(1, 2, 3);
+
+    if (pageCount > maxVisiblePages - 1) {
+      pages.push('...');
+    }
+
+    pages.push(pageCount - 2, pageCount - 1, pageCount);
+
+    return pages;
+  }, [ pageCount, maxVisiblePages ]);
+
+  const handlePageSizeChange = useCallback((value: string) => {
+    setPageSize(Number(value));
+  }, [ setPageSize ]);
+
+  const handlePageClick = useCallback((page: number) => {
+    setPageIndex(page - 1);
+  }, [ setPageIndex ]);
+
+  return (
+    <Flex
+      className={cn('items-center gap-2 w-full', className, {
+        'justify-between': showPageSizeSelector,
+        'justify-end': !showPageSizeSelector,
+      })}
+      role="navigation"
+      aria-label={ariaLabel}
+    >
+      <RenderCondition condition={showPageSizeSelector}>
+        <Flex className="items-center gap-2">
+          <Select
+            value={`${pageSize}`}
+            onValueChange={handlePageSizeChange}
+          >
+            <SelectTrigger
+              size="lg"
+              className="w-[150px]"
+              id="rows-per-page"
+              aria-label={`Itens por página: ${pageSize}`}
+              disabled={pageCount <= 1 && pageSize === pageSizeOptions[0]}
+            >
+              <SelectValue placeholder={pageSize.toString()} />
+            </SelectTrigger>
+            <SelectContent side="top">
+              {pageSizeOptions.map(size => (
+                <SelectItem key={size} value={`${size}`}>
+                  {size} {pageSizeLabel}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+
+        </Flex>
+      </RenderCondition>
+
+      <Flex className="ml-auto items-center lg:ml-0">
+        <Button
+          variant="outline"
+          role="button"
+          size="sm"
+          className="rounded-l-md rounded-r-none"
+          onClick={previousPage}
+          disabled={!canPreviousPage}
+          aria-label={`Ir para página anterior${pageIndex > 0 ? `, página ${pageIndex}` : ''}`}
+        >
+          <ArrowLeft className="text-gray-400" size={16} />
+          <span className="hidden sm:inline ml-1">
+            {previousPageText || 'Anterior'}
+          </span>
+        </Button>
+
+        <RenderCondition condition={pageCount > 1}>
+          <Flex className="items-center" role="group" aria-label="Páginas">
+            {displayPages.map((page, index) => {
+              if (page === '...') {
+                return (
+                  <Popover>
+                    <PopoverTrigger asChild>
+                      <Button
+                        key={`ellipsis-${index}`}
+                        variant="outline"
+                        role="button"
+                        size="sm"
+                        className="w-10 h-10 p-0 rounded-none"
+                        aria-hidden="true"
+                      >
+                      ...
+                      </Button>
+                    </PopoverTrigger>
+
+                    <PopoverContent className='w-fit px-3 py-2 flex items-center justify-center'>
+                      <input
+                        autoFocus
+                        type="number"
+                        min={1}
+                        max={pageCount}
+                        defaultValue={pageIndex + 1}
+                        onBlur={e => setPageIndex(Number(e.target.value) - 1)}
+                        onKeyDown={e => {
+                          if (e.key === 'Enter') {
+                            setPageIndex(Number(e.currentTarget.value) - 1);
+                          }
+                        }}
+                        className='w-12 p-0 rounded-none border-none outline-none'
+                      />
+                    </PopoverContent>
+                  </Popover>
+                );
+              }
+
+              const isCurrentPage = pageIndex + 1 === page;
+
+              return (
+                <Button
+                  key={page}
+                  variant={isCurrentPage ? 'primary' : 'outline'}
+                  role="button"
+                  size="sm"
+                  className="w-10 h-10 p-0 rounded-none"
+                  onClick={() => handlePageClick(page as number)}
+                  disabled={pageCount === 1}
+                  aria-label={`${isCurrentPage ? 'Página atual' : 'Ir para página'} ${page}`}
+                  aria-current={isCurrentPage ? 'page' : undefined}
+                >
+                  {page}
+                </Button>
+              );
+            })}
+          </Flex>
+        </RenderCondition>
+
+        <Button
+          variant="outline"
+          role="button"
+          size="sm"
+          className="rounded-r-md rounded-l-none h-10"
+          onClick={nextPage}
+          disabled={!canNextPage}
+          aria-label={`Ir para próxima página${canNextPage ? `, página ${pageIndex + 2}` : ''}`}
+        >
+          <span className="hidden sm:inline mr-1">
+            {nextPageText || 'Próximo'}
+          </span>
+          <ArrowRight className="text-gray-500" size={16} />
+        </Button>
+      </Flex>
+    </Flex>
+  );
+}
+
+export type { PaginationProps };
+export { Pagination };
+

package/src/components/molecules/PaginationDotGroup/index.ts

@@ -0,0 +1 @@
+export * from './pagination-dot-group';