@brcarddev/frontend-commons 1.0.2

package/src/components/molecules/PaginationDotGroup/pagination-dot-group.stories.tsx

@@ -0,0 +1,211 @@
+import { useState } from 'react';
+
+import { Meta, StoryObj } from '@storybook/react';
+
+import { PaginationDotGroup } from './pagination-dot-group';
+
+const meta: Meta<typeof PaginationDotGroup> = {
+  title: 'Components/Navigation/PaginationDotGroup',
+  component: PaginationDotGroup,
+  tags: [ 'autodocs' ],
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'A pagination component that displays dots representing pages with interactive navigation capabilities.',
+      },
+    },
+  },
+  argTypes: {
+    'pages': {
+      control: { type: 'number', min: 1, max: 20 },
+      description: 'Total number of pages',
+    },
+    'currentPage': {
+      control: { type: 'number', min: 0, max: 19 },
+      description: 'Current active page (0-indexed)',
+    },
+    'onPageChange': {
+      description: 'Callback function when a page is selected',
+    },
+    'disabled': {
+      control: { type: 'boolean' },
+      description: 'Whether the pagination is disabled',
+    },
+    'data-testid': {
+      control: { type: 'text' },
+      description: 'Test identifier',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    pages: 5,
+    currentPage: 0,
+    onPageChange: (page: number) => console.log('Page changed to:', page),
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    pages: 6,
+    currentPage: 2,
+    disabled: true,
+    onPageChange: (page: number) => console.log('Page changed to:', page),
+  },
+};
+
+export const FewPages: Story = {
+  name: 'Few Pages',
+  args: {
+    pages: 3,
+    currentPage: 1,
+    onPageChange: (page: number) => console.log('Page changed to:', page),
+  },
+};
+
+export const Interactive: Story = {
+  name: 'Interactive Example',
+  render: () => <InteractiveExample pages={8} />,
+  parameters: {
+    docs: {
+      description: {
+        story: 'An interactive example showing the pagination component with working navigation and helper buttons.',
+      },
+    },
+  },
+};
+
+export const ManyPages: Story = {
+  name: 'Many Pages',
+  args: {
+    pages: 15,
+    currentPage: 7,
+    onPageChange: (page: number) => console.log('Page changed to:', page),
+  },
+};
+
+export const SinglePage: Story = {
+  name: 'Single Page (Hidden)',
+  args: {
+    pages: 1,
+    currentPage: 0,
+    onPageChange: (page: number) => console.log('Page changed to:', page),
+  },
+};
+
+export const VariousSizes: Story = {
+  name: 'Various Sizes Showcase',
+  render: () => (
+    <div className="space-y-6">
+      <div className="text-center">
+        <h3 className="text-sm font-medium text-gray-700 mb-2">3 Pages</h3>
+        <PaginationDotGroup
+          pages={3}
+          currentPage={1}
+          onPageChange={(page: number) => console.log('3-pages changed to:', page)}
+        />
+      </div>
+      <div className="text-center">
+        <h3 className="text-sm font-medium text-gray-700 mb-2">5 Pages</h3>
+        <PaginationDotGroup
+          pages={5}
+          currentPage={2}
+          onPageChange={(page: number) => console.log('5-pages changed to:', page)}
+        />
+      </div>
+      <div className="text-center">
+        <h3 className="text-sm font-medium text-gray-700 mb-2">8 Pages</h3>
+        <PaginationDotGroup
+          pages={8}
+          currentPage={4}
+          onPageChange={(page: number) => console.log('8-pages changed to:', page)}
+        />
+      </div>
+      <div className="text-center">
+        <h3 className="text-sm font-medium text-gray-700 mb-2">12 Pages</h3>
+        <PaginationDotGroup
+          pages={12}
+          currentPage={6}
+          onPageChange={(page: number) => console.log('12-pages changed to:', page)}
+        />
+      </div>
+      <div className="text-center">
+        <h3 className="text-sm font-medium text-gray-700 mb-2">Disabled State</h3>
+        <PaginationDotGroup
+          pages={6}
+          currentPage={3}
+          disabled={true}
+          onPageChange={(page: number) => console.log('disabled changed to:', page)}
+        />
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'A showcase of different pagination sizes and states to demonstrate the component flexibility.',
+      },
+    },
+  },
+};
+
+export const WithMiddlePage: Story = {
+  name: 'With Middle Page Active',
+  args: {
+    pages: 7,
+    currentPage: 3,
+    onPageChange: (page: number) => console.log('Page changed to:', page),
+  },
+};
+
+const InteractiveExample = ({ pages = 8 }: { pages?: number }) => {
+  const [ currentPage, setCurrentPage ] = useState(0);
+
+  return (
+    <div className="space-y-4">
+      <div className="text-center">
+        <p className="text-sm text-gray-600 mb-2">
+          Current Page: {currentPage + 1} of {pages}
+        </p>
+        <PaginationDotGroup
+          pages={pages}
+          currentPage={currentPage}
+          onPageChange={setCurrentPage}
+        />
+      </div>
+      <div className="text-center">
+        <button
+          onClick={() => setCurrentPage(0)}
+          className="px-3 py-1 text-xs bg-gray-200 hover:bg-gray-300 rounded mr-2"
+        >
+          Reset to First
+        </button>
+        <button
+          onClick={() => setCurrentPage(Math.floor(pages / 2))}
+          className="px-3 py-1 text-xs bg-gray-200 hover:bg-gray-300 rounded mr-2"
+        >
+          Go to Middle
+        </button>
+        <button
+          onClick={() => setCurrentPage(pages - 1)}
+          className="px-3 py-1 text-xs bg-gray-200 hover:bg-gray-300 rounded"
+        >
+          Go to Last
+        </button>
+      </div>
+    </div>
+  );
+};
+
+export const WithoutCallback: Story = {
+  name: 'Without Click Handler',
+  args: {
+    pages: 4,
+    currentPage: 1,
+  },
+};

package/src/components/molecules/PaginationDotGroup/pagination-dot-group.test.tsx

@@ -0,0 +1,385 @@
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+import { PaginationDotGroup, PaginationDotGroupProps } from './pagination-dot-group';
+
+describe('<PaginationDotGroup />', () => {
+  const defaultProps: PaginationDotGroupProps = {
+    pages: 5,
+    currentPage: 0,
+    onPageChange: vi.fn(),
+  };
+
+  const renderPaginationDotGroup = (props: Partial<PaginationDotGroupProps> = {}) =>
+    render(<PaginationDotGroup data-testid="pagination-dot-group" {...defaultProps} {...props} />);
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Rendering', () => {
+    it('renders correctly with default props', () => {
+      renderPaginationDotGroup();
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      expect(container).toBeInTheDocument();
+      expect(dots).toHaveLength(5);
+    });
+
+    it('renders with custom data-testid', () => {
+      renderPaginationDotGroup({ 'data-testid': 'custom-pagination' });
+
+      const container = screen.getByTestId('custom-pagination');
+      expect(container).toBeInTheDocument();
+    });
+
+    it('does not render when pages is 1 or less', () => {
+      const { container } = renderPaginationDotGroup({ pages: 1 });
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('does not render when pages is 0', () => {
+      const { container } = renderPaginationDotGroup({ pages: 0 });
+      expect(container.firstChild).toBeNull();
+    });
+
+    it('does not render when pages is negative', () => {
+      const { container } = renderPaginationDotGroup({ pages: -1 });
+      expect(container.firstChild).toBeNull();
+    });
+  });
+
+  describe('Page Validation', () => {
+    it('handles non-integer pages by flooring the value', () => {
+      renderPaginationDotGroup({ pages: 3.7 });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+      expect(dots).toHaveLength(3);
+    });
+
+    it('handles currentPage out of range (too high)', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 5 });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const activeDot = container.querySelector('[aria-current="page"]');
+      const [ , , lastDot ] = container.querySelectorAll('[role="button"]');
+
+      expect(activeDot).toBe(lastDot);
+    });
+
+    it('handles currentPage out of range (negative)', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: -1 });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const activeDot = container.querySelector('[aria-current="page"]');
+      const [ firstDot ] = container.querySelectorAll('[role="button"]');
+
+      expect(activeDot).toBe(firstDot);
+    });
+  });
+
+  describe('Active State', () => {
+    it('marks the correct dot as active', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 1 });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+      const activeDot = container.querySelector('[aria-current="page"]');
+
+      expect(activeDot).toBe(dots[1]);
+      expect(dots[0]).not.toHaveAttribute('aria-current');
+      expect(dots[2]).not.toHaveAttribute('aria-current');
+    });
+
+    it('applies active styles to the current page dot', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 1 });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      expect(dots[1]).toHaveClass('bg-primary');
+      expect(dots[0]).toHaveClass('bg-gray-200');
+      expect(dots[2]).toHaveClass('bg-gray-200');
+    });
+  });
+
+  describe('Click Interactions', () => {
+    it('calls onPageChange when a dot is clicked', async () => {
+      const onPageChange = vi.fn();
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      await userEvent.click(dots[1]);
+
+      expect(onPageChange).toHaveBeenCalledTimes(1);
+      expect(onPageChange).toHaveBeenCalledWith(1);
+    });
+
+    it('calls onPageChange with correct index for each dot', async () => {
+      const onPageChange = vi.fn();
+      renderPaginationDotGroup({ pages: 4, currentPage: 0, onPageChange });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      for (let i = 0; i < dots.length; i++) {
+        fireEvent.click(dots[i]);
+        expect(onPageChange).toHaveBeenCalledWith(i);
+      }
+
+      expect(onPageChange).toHaveBeenCalledTimes(4);
+    });
+
+    it('does not call onPageChange when onPageChange is not provided', async () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange: undefined });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      await userEvent.click(dots[1]);
+      expect(true).toBe(true);
+    });
+  });
+
+  describe('Keyboard Interactions', () => {
+    it('responds to Enter key press', async () => {
+      const onPageChange = vi.fn();
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      (dots[1] as HTMLElement).focus();
+      fireEvent.keyDown(dots[1], { key: 'Enter' });
+
+      expect(onPageChange).toHaveBeenCalledWith(1);
+    });
+
+    it('responds to Space key press', async () => {
+      const onPageChange = vi.fn();
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      (dots[2] as HTMLElement).focus();
+      fireEvent.keyDown(dots[2], { key: ' ' });
+
+      expect(onPageChange).toHaveBeenCalledWith(2);
+    });
+
+    it('does not respond to other keys', async () => {
+      const onPageChange = vi.fn();
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      (dots[1] as HTMLElement).focus();
+      fireEvent.keyDown(dots[1], { key: 'ArrowLeft' });
+      fireEvent.keyDown(dots[1], { key: 'Tab' });
+
+      expect(onPageChange).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Disabled State', () => {
+    it('applies disabled styles when disabled', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, disabled: true });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      dots.forEach(dot => {
+        expect(dot).toHaveClass('opacity-50', 'cursor-not-allowed');
+        expect(dot).toHaveAttribute('aria-disabled', 'true');
+        expect(dot).toHaveAttribute('tabIndex', '-1');
+      });
+    });
+
+    it('does not call onPageChange when disabled and clicked', async () => {
+      const onPageChange = vi.fn();
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange, disabled: true });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      await userEvent.click(dots[1]);
+
+      expect(onPageChange).not.toHaveBeenCalled();
+    });
+
+    it('does not respond to keyboard when disabled', async () => {
+      const onPageChange = vi.fn();
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange, disabled: true });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      fireEvent.keyDown(dots[1], { key: 'Enter' });
+      fireEvent.keyDown(dots[1], { key: ' ' });
+
+      expect(onPageChange).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Interactive State', () => {
+    it('applies interactive styles when onPageChange is provided', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange: vi.fn() });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      dots.forEach(dot => {
+        expect(dot).toHaveClass('cursor-pointer', 'hover:scale-110');
+      });
+    });
+
+    it('applies non-interactive styles when onPageChange is not provided', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange: undefined });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      dots.forEach(dot => {
+        expect(dot).not.toHaveClass('cursor-pointer', 'hover:scale-110');
+      });
+    });
+
+    it('applies hover styles to inactive dots when interactive', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, onPageChange: vi.fn() });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      expect(dots[1]).toHaveClass('hover:bg-gray-300');
+      expect(dots[2]).toHaveClass('hover:bg-gray-300');
+
+      expect(dots[0]).not.toHaveClass('hover:bg-gray-300');
+    });
+  });
+
+  describe('Accessibility', () => {
+    it('has proper ARIA attributes', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 1 });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      expect(container).toHaveAttribute('role', 'navigation');
+      expect(container).toHaveAttribute('aria-label', 'Pagination');
+
+      dots.forEach((dot, index) => {
+        expect(dot).toHaveAttribute('role', 'button');
+        expect(dot).toHaveAttribute('aria-label', `Go to page ${index + 1}`);
+        expect(dot).toHaveAttribute('tabIndex', '0');
+      });
+
+      expect(dots[1]).toHaveAttribute('aria-current', 'page');
+      expect(dots[0]).not.toHaveAttribute('aria-current');
+      expect(dots[2]).not.toHaveAttribute('aria-current');
+    });
+
+    it('has correct tabIndex for disabled state', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 0, disabled: true });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      dots.forEach(dot => {
+        expect(dot).toHaveAttribute('tabIndex', '-1');
+      });
+    });
+  });
+
+  describe('CSS Classes', () => {
+    it('applies base classes correctly', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 0 });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      expect(container).toHaveClass('gap-3');
+
+      dots.forEach(dot => {
+        expect(dot).toHaveClass('w-2', 'h-2', 'rounded-full', 'transition-all', 'duration-200');
+      });
+    });
+
+    it('applies correct color classes', () => {
+      renderPaginationDotGroup({ pages: 3, currentPage: 1 });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+
+      expect(dots[0]).toHaveClass('bg-gray-200');
+      expect(dots[1]).toHaveClass('bg-primary');
+      expect(dots[2]).toHaveClass('bg-gray-200');
+    });
+  });
+
+  describe('Component Structure', () => {
+    it('has correct display names', () => {
+      expect(PaginationDotGroup.displayName).toBe('PaginationDotGroup');
+    });
+
+    it('is memoized', () => {
+      const props1 = { pages: 3, currentPage: 0 };
+      const props2 = { pages: 3, currentPage: 0 };
+
+      const { rerender } = render(<PaginationDotGroup {...props1} />);
+      const component1 = PaginationDotGroup;
+
+      rerender(<PaginationDotGroup {...props2} />);
+      const component2 = PaginationDotGroup;
+
+      expect(component1).toBe(component2);
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles very large number of pages', () => {
+      renderPaginationDotGroup({ pages: 100, currentPage: 50 });
+
+      const container = screen.getByTestId('pagination-dot-group');
+      const dots = container.querySelectorAll('[role="button"]');
+      const activeDot = container.querySelector('[aria-current="page"]');
+
+      expect(dots).toHaveLength(100);
+      expect(activeDot).toBe(dots[50]);
+    });
+
+    it('handles single page correctly (should not render)', () => {
+      const { container } = renderPaginationDotGroup({ pages: 1, currentPage: 0 });
+      expect(container.firstChild).toBeNull();
+    });
+  });
+
+  describe('Snapshots', () => {
+    it('matches snapshot with default props', () => {
+      const { container } = renderPaginationDotGroup();
+      expect(container).toMatchSnapshot();
+    });
+
+    it('matches snapshot when disabled', () => {
+      const { container } = renderPaginationDotGroup({ disabled: true });
+      expect(container).toMatchSnapshot('disabled-state');
+    });
+
+    it('matches snapshot with different current page', () => {
+      const { container } = renderPaginationDotGroup({ pages: 5, currentPage: 2 });
+      expect(container).toMatchSnapshot('different-current-page');
+    });
+
+    it('matches snapshot without onPageChange', () => {
+      const { container } = renderPaginationDotGroup({ onPageChange: undefined });
+      expect(container).toMatchSnapshot('non-interactive');
+    });
+  });
+});