@fragments-sdk/ui 0.8.7 → 0.8.8

package/src/components/Pagination/Pagination.fragment.tsx

@@ -0,0 +1,152 @@
+import React from 'react';
+import { defineFragment } from '@fragments-sdk/cli/core';
+import { Pagination } from '.';
+
+export default defineFragment({
+  component: Pagination,
+
+  meta: {
+    name: 'Pagination',
+    description: 'Page navigation for paginated data. Supports controlled/uncontrolled, page counts, and edge/sibling customization.',
+    category: 'navigation',
+    status: 'stable',
+    tags: ['pagination', 'paging', 'pages', 'navigation'],
+    since: '0.8.2',
+  },
+
+  usage: {
+    when: [
+      'Navigating through paginated data sets',
+      'Table or list pagination controls',
+      'Search results with multiple pages',
+      'Any content split across multiple pages',
+    ],
+    whenNot: [
+      'Small lists that fit on one page',
+      'Infinite scroll patterns (use IntersectionObserver)',
+      'Tab-based navigation (use Tabs)',
+      'Step-by-step wizards (use Stepper)',
+    ],
+    guidelines: [
+      'Place below the content being paginated',
+      'Use edgeCount to always show first/last pages',
+      'Use siblingCount to control how many pages surround the current page',
+      'Pair with Table component for data table pagination',
+    ],
+    accessibility: [
+      'Uses nav element with aria-label="Pagination"',
+      'aria-current="page" marks the active page',
+      'Previous/Next buttons have descriptive aria-labels',
+      'Disabled buttons at boundaries prevent invalid navigation',
+    ],
+  },
+
+  props: {
+    totalPages: {
+      type: 'number',
+      description: 'Total number of pages',
+      required: true,
+    },
+    page: {
+      type: 'number',
+      description: 'Controlled current page (1-indexed)',
+    },
+    defaultPage: {
+      type: 'number',
+      description: 'Default page (uncontrolled)',
+      default: '1',
+    },
+    onPageChange: {
+      type: 'function',
+      description: 'Called when page changes',
+    },
+    edgeCount: {
+      type: 'number',
+      description: 'Number of pages shown at edges',
+      default: '1',
+    },
+    siblingCount: {
+      type: 'number',
+      description: 'Number of pages shown around current',
+      default: '1',
+    },
+  },
+
+  relations: [
+    { component: 'Table', relationship: 'sibling', note: 'Commonly paired for table pagination' },
+    { component: 'Listbox', relationship: 'alternative', note: 'Use Listbox for small sets of options' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'totalPages: number - total page count (required)',
+      'page: number - controlled current page (1-indexed)',
+      'defaultPage: number - initial page (default: 1)',
+      'onPageChange: (page) => void - page change handler',
+      'edgeCount: number - pages at edges (default: 1)',
+      'siblingCount: number - pages around current (default: 1)',
+    ],
+    scenarioTags: [
+      'navigation.pagination',
+      'data.table',
+      'search.results',
+    ],
+    a11yRules: ['A11Y_NAV_LABEL', 'A11Y_CURRENT_PAGE'],
+  },
+
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Previous', 'Next', 'Items', 'Item', 'Ellipsis'],
+    requiredChildren: ['Items'],
+    commonPatterns: [
+      '<Pagination totalPages={totalPages} page={currentPage} onPageChange={setPage}><Pagination.Previous /><Pagination.Items /><Pagination.Next /></Pagination>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic pagination with 10 pages',
+      render: () => (
+        <Pagination totalPages={10} defaultPage={1}>
+          <Pagination.Previous />
+          <Pagination.Items />
+          <Pagination.Next />
+        </Pagination>
+      ),
+    },
+    {
+      name: 'With Edge Pages',
+      description: 'Shows 2 pages at each edge',
+      render: () => (
+        <Pagination totalPages={20} defaultPage={10} edgeCount={2} siblingCount={1}>
+          <Pagination.Previous />
+          <Pagination.Items />
+          <Pagination.Next />
+        </Pagination>
+      ),
+    },
+    {
+      name: 'Compact',
+      description: 'No siblings, minimal display',
+      render: () => (
+        <Pagination totalPages={20} defaultPage={10} siblingCount={0}>
+          <Pagination.Previous />
+          <Pagination.Items />
+          <Pagination.Next />
+        </Pagination>
+      ),
+    },
+    {
+      name: 'Controlled',
+      description: 'Controlled pagination at page 3',
+      render: () => (
+        <Pagination totalPages={5} page={3}>
+          <Pagination.Previous />
+          <Pagination.Items />
+          <Pagination.Next />
+        </Pagination>
+      ),
+    },
+  ],
+});

package/src/components/Pagination/Pagination.module.scss

@@ -0,0 +1,109 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Navigation wrapper
+// ============================================
+
+.pagination {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+// ============================================
+// List container
+// ============================================
+
+.list {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, 0.25rem);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+// ============================================
+// Page item button
+// ============================================
+
+.item {
+  @include button-reset;
+  @include text-base;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 2rem;
+  height: 2rem;
+  padding: 0 var(--fui-space-2, 0.5rem);
+  border-radius: var(--fui-radius-md, 0.375rem);
+  font-size: var(--fui-font-size-sm, 0.875rem);
+  font-weight: var(--fui-font-weight-medium, 500);
+  color: var(--fui-text-primary);
+  cursor: pointer;
+  transition: background-color 0.1s ease, color 0.1s ease;
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+// Active page
+.itemActive {
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-text-inverse, $fui-text-inverse);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+}
+
+// Disabled state (prev/next at boundaries)
+.itemDisabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+// ============================================
+// Nav buttons (Previous/Next)
+// ============================================
+
+.navButton {
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+// ============================================
+// Ellipsis
+// ============================================
+
+.ellipsis {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 2rem;
+  height: 2rem;
+  font-size: var(--fui-font-size-sm, 0.875rem);
+  color: var(--fui-text-secondary);
+  user-select: none;
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .itemActive {
+    outline: 2px solid var(--fui-color-accent);
+    outline-offset: -2px;
+  }
+}

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

@@ -0,0 +1,171 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { Pagination } from './index';
+
+function renderPagination(props: Partial<React.ComponentProps<typeof Pagination>> = {}) {
+  return render(
+    <Pagination totalPages={10} defaultPage={1} {...props}>
+      <Pagination.Previous />
+      <Pagination.Items />
+      <Pagination.Next />
+    </Pagination>
+  );
+}
+
+describe('Pagination', () => {
+  it('renders correct page range', () => {
+    renderPagination({ totalPages: 5 });
+
+    expect(screen.getByLabelText('Go to page 1')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 2')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 3')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 4')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 5')).toBeInTheDocument();
+  });
+
+  it('current page is highlighted', () => {
+    renderPagination({ defaultPage: 3, totalPages: 5 });
+
+    const page3 = screen.getByLabelText('Go to page 3');
+    expect(page3).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('click page changes selection', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    renderPagination({ totalPages: 5, onPageChange });
+
+    await user.click(screen.getByLabelText('Go to page 3'));
+    expect(onPageChange).toHaveBeenCalledWith(3);
+  });
+
+  it('Previous/Next buttons work', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    renderPagination({ totalPages: 5, defaultPage: 3, onPageChange });
+
+    await user.click(screen.getByLabelText('Go to previous page'));
+    expect(onPageChange).toHaveBeenCalledWith(2);
+
+    await user.click(screen.getByLabelText('Go to next page'));
+    // After clicking prev (now on 2), clicking next goes to 3
+    expect(onPageChange).toHaveBeenCalledWith(3);
+  });
+
+  it('Previous disabled on page 1', () => {
+    renderPagination({ defaultPage: 1, totalPages: 5 });
+
+    expect(screen.getByLabelText('Go to previous page')).toBeDisabled();
+  });
+
+  it('Next disabled on last page', () => {
+    renderPagination({ defaultPage: 5, totalPages: 5 });
+
+    expect(screen.getByLabelText('Go to next page')).toBeDisabled();
+  });
+
+  it('ellipsis renders for large ranges', () => {
+    renderPagination({ totalPages: 20, defaultPage: 10 });
+
+    const ellipses = document.querySelectorAll('[aria-hidden="true"]');
+    // Should have at least one ellipsis (excluding SVG icons)
+    const textEllipses = Array.from(ellipses).filter(
+      (el) => el.tagName !== 'svg' && el.textContent === '\u2026'
+    );
+    expect(textEllipses.length).toBeGreaterThan(0);
+  });
+
+  it('edge count customization', () => {
+    renderPagination({ totalPages: 20, defaultPage: 10, edgeCount: 2 });
+
+    // With edgeCount=2, pages 1,2 and 19,20 should show
+    expect(screen.getByLabelText('Go to page 1')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 2')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 19')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 20')).toBeInTheDocument();
+  });
+
+  it('sibling count customization', () => {
+    renderPagination({ totalPages: 20, defaultPage: 10, siblingCount: 2 });
+
+    // With siblingCount=2, pages 8,9,10,11,12 should show
+    expect(screen.getByLabelText('Go to page 8')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 9')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 10')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 11')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 12')).toBeInTheDocument();
+  });
+
+  it('controlled mode (page prop)', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    const { rerender } = render(
+      <Pagination totalPages={5} page={3} onPageChange={onPageChange}>
+        <Pagination.Previous />
+        <Pagination.Items />
+        <Pagination.Next />
+      </Pagination>
+    );
+
+    expect(screen.getByLabelText('Go to page 3')).toHaveAttribute('aria-current', 'page');
+
+    await user.click(screen.getByLabelText('Go to page 5'));
+    expect(onPageChange).toHaveBeenCalledWith(5);
+
+    // Re-render with updated page prop
+    rerender(
+      <Pagination totalPages={5} page={5} onPageChange={onPageChange}>
+        <Pagination.Previous />
+        <Pagination.Items />
+        <Pagination.Next />
+      </Pagination>
+    );
+
+    expect(screen.getByLabelText('Go to page 5')).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('keyboard navigation (Tab between buttons)', async () => {
+    const user = userEvent.setup();
+    renderPagination({ totalPages: 3 });
+
+    const prevButton = screen.getByLabelText('Go to previous page');
+    prevButton.focus();
+
+    await user.tab();
+    // Focus should move to a page button
+    expect(document.activeElement?.getAttribute('aria-label')).toMatch(/Go to page/);
+  });
+
+  it('totalPages=0 renders empty nav', () => {
+    const { container } = renderPagination({ totalPages: 0 });
+
+    expect(container.querySelector('nav')).toBeInTheDocument();
+    expect(container.querySelector('ul')).not.toBeInTheDocument();
+  });
+
+  it('totalPages=1 renders single page, no prev/next disabled correctly', () => {
+    renderPagination({ totalPages: 1 });
+
+    expect(screen.getByLabelText('Go to page 1')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to previous page')).toBeDisabled();
+    expect(screen.getByLabelText('Go to next page')).toBeDisabled();
+  });
+
+  it('out-of-range controlled page clamps to valid range', () => {
+    render(
+      <Pagination totalPages={5} page={99}>
+        <Pagination.Previous />
+        <Pagination.Items />
+        <Pagination.Next />
+      </Pagination>
+    );
+
+    expect(screen.getByLabelText('Go to page 5')).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = renderPagination({ totalPages: 10, defaultPage: 5 });
+
+    await expectNoA11yViolations(container);
+  });
+});