@dashforge/tw 0.4.0-beta → 0.5.0-beta

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

@@ -0,0 +1,314 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, afterEach } from 'vitest';
+import { render, screen, fireEvent, cleanup } from '@testing-library/react';
+import { Pagination } from './Pagination.js';
+import { computePageRange } from './pagination.helpers.js';
+
+void React;
+afterEach(() => cleanup());
+
+describe('computePageRange — helper', () => {
+  it('returns empty for totalPages=0', () => {
+    expect(computePageRange(1, 0, 1, 1)).toEqual([]);
+  });
+
+  it('returns [1] for totalPages=1', () => {
+    expect(computePageRange(1, 1, 1, 1)).toEqual([1]);
+  });
+
+  it('lists all pages when totalPages <= window size', () => {
+    expect(computePageRange(1, 5, 1, 1)).toEqual([1, 2, 3, 4, 5]);
+  });
+
+  it('inserts ellipsis on the right when current is near start', () => {
+    const r = computePageRange(2, 20, 1, 1);
+    expect(r).toContain(1);
+    expect(r).toContain(2);
+    expect(r).toContain(3);
+    expect(r).toContain('ellipsis');
+    expect(r).toContain(20);
+    expect(r).not.toContain(10);
+  });
+
+  it('inserts ellipsis on both sides when current is in the middle', () => {
+    const r = computePageRange(10, 20, 1, 1);
+    expect(r.filter((x) => x === 'ellipsis').length).toBeGreaterThanOrEqual(1);
+    expect(r).toContain(1);
+    expect(r).toContain(9);
+    expect(r).toContain(10);
+    expect(r).toContain(11);
+    expect(r).toContain(20);
+  });
+
+  it('inserts ellipsis on the left when current is near end', () => {
+    const r = computePageRange(19, 20, 1, 1);
+    expect(r).toContain(1);
+    expect(r).toContain('ellipsis');
+    expect(r).toContain(18);
+    expect(r).toContain(19);
+    expect(r).toContain(20);
+  });
+
+  it('respects siblingCount=2', () => {
+    const r = computePageRange(10, 20, 2, 1);
+    expect(r).toContain(8);
+    expect(r).toContain(9);
+    expect(r).toContain(10);
+    expect(r).toContain(11);
+    expect(r).toContain(12);
+  });
+
+  it('respects boundaryCount=2', () => {
+    const r = computePageRange(10, 20, 1, 2);
+    expect(r).toContain(1);
+    expect(r).toContain(2);
+    expect(r).toContain(19);
+    expect(r).toContain(20);
+  });
+});
+
+describe('Pagination — rendering (default variant)', () => {
+  it('renders nav landmark with aria-label', () => {
+    render(<Pagination page={1} pageSize={10} totalCount={50} onPageChange={() => {}} />);
+    expect(screen.getByRole('navigation', { name: 'Pagination' })).not.toBeNull();
+  });
+
+  it('renders the "Showing X-Y of Z" summary', () => {
+    render(<Pagination page={1} pageSize={10} totalCount={50} onPageChange={() => {}} />);
+    expect(screen.getByText(/Showing 1-10 of 50/)).not.toBeNull();
+  });
+
+  it('renders correct summary on last page (partial fill)', () => {
+    render(<Pagination page={5} pageSize={10} totalCount={47} onPageChange={() => {}} />);
+    expect(screen.getByText(/Showing 41-47 of 47/)).not.toBeNull();
+  });
+
+  it('marks active page with aria-current=page', () => {
+    render(<Pagination page={3} pageSize={10} totalCount={50} onPageChange={() => {}} />);
+    const active = screen.getByRole('button', { name: 'Page 3' });
+    expect(active.getAttribute('aria-current')).toBe('page');
+  });
+
+  it('disables Prev + First on page 1', () => {
+    render(<Pagination page={1} pageSize={10} totalCount={50} onPageChange={() => {}} />);
+    expect((screen.getByRole('button', { name: 'Previous' }) as HTMLButtonElement).disabled).toBe(true);
+    expect((screen.getByRole('button', { name: 'First' }) as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it('disables Next + Last on last page', () => {
+    render(<Pagination page={5} pageSize={10} totalCount={50} onPageChange={() => {}} />);
+    expect((screen.getByRole('button', { name: 'Next' }) as HTMLButtonElement).disabled).toBe(true);
+    expect((screen.getByRole('button', { name: 'Last' }) as HTMLButtonElement).disabled).toBe(true);
+  });
+});
+
+describe('Pagination — interactions', () => {
+  it('emits onPageChange when a page button is clicked', () => {
+    let last = 0;
+    render(
+      <Pagination
+        page={1}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={(p) => (last = p)}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Page 3' }));
+    expect(last).toBe(3);
+  });
+
+  it('Prev decrements page', () => {
+    let last = 0;
+    render(
+      <Pagination
+        page={3}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={(p) => (last = p)}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Previous' }));
+    expect(last).toBe(2);
+  });
+
+  it('Next increments page', () => {
+    let last = 0;
+    render(
+      <Pagination
+        page={3}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={(p) => (last = p)}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Next' }));
+    expect(last).toBe(4);
+  });
+
+  it('First/Last jump to extremes', () => {
+    let last = 0;
+    const { rerender } = render(
+      <Pagination
+        page={3}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={(p) => (last = p)}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'First' }));
+    expect(last).toBe(1);
+    rerender(
+      <Pagination
+        page={3}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={(p) => (last = p)}
+      />,
+    );
+    fireEvent.click(screen.getByRole('button', { name: 'Last' }));
+    expect(last).toBe(5);
+  });
+
+  it('emits onPageSizeChange when selector changes', () => {
+    let lastSize = 0;
+    render(
+      <Pagination
+        page={1}
+        pageSize={10}
+        totalCount={100}
+        onPageChange={() => {}}
+        onPageSizeChange={(s) => (lastSize = s)}
+      />,
+    );
+    const selector = screen.getByLabelText('per page') as HTMLSelectElement;
+    fireEvent.change(selector, { target: { value: '50' } });
+    expect(lastSize).toBe(50);
+  });
+
+  it('hides page-size selector if onPageSizeChange not provided', () => {
+    render(<Pagination page={1} pageSize={10} totalCount={50} onPageChange={() => {}} />);
+    expect(screen.queryByLabelText('per page')).toBeNull();
+  });
+});
+
+describe('Pagination — variants', () => {
+  it('compact variant hides summary + selector', () => {
+    render(
+      <Pagination
+        variant="compact"
+        page={1}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={() => {}}
+        onPageSizeChange={() => {}}
+      />,
+    );
+    expect(screen.queryByText(/Showing/)).toBeNull();
+    expect(screen.queryByLabelText('per page')).toBeNull();
+  });
+
+  it('minimal variant shows "Page X of Y" + only Prev/Next', () => {
+    render(
+      <Pagination
+        variant="minimal"
+        page={3}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={() => {}}
+      />,
+    );
+    expect(screen.getByText(/Page 3 of 5/)).not.toBeNull();
+    // Page-number buttons should NOT exist
+    expect(screen.queryByRole('button', { name: 'Page 1' })).toBeNull();
+    // Prev / Next remain
+    expect(screen.queryByRole('button', { name: 'Previous' })).not.toBeNull();
+    expect(screen.queryByRole('button', { name: 'Next' })).not.toBeNull();
+  });
+});
+
+describe('Pagination — i18n', () => {
+  it('honors custom labels', () => {
+    render(
+      <Pagination
+        page={1}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={() => {}}
+        labels={{ showing: 'Mostro', of: 'di', prev: 'Indietro', next: 'Avanti' }}
+      />,
+    );
+    expect(screen.getByText(/Mostro 1-10 di 50/)).not.toBeNull();
+    expect(screen.queryByRole('button', { name: 'Indietro' })).not.toBeNull();
+    expect(screen.queryByRole('button', { name: 'Avanti' })).not.toBeNull();
+  });
+});
+
+describe('Pagination — disabled', () => {
+  it('disables all buttons when disabled=true', () => {
+    render(
+      <Pagination
+        page={3}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={() => {}}
+        disabled
+      />,
+    );
+    expect((screen.getByRole('button', { name: 'Previous' }) as HTMLButtonElement).disabled).toBe(true);
+    expect((screen.getByRole('button', { name: 'Next' }) as HTMLButtonElement).disabled).toBe(true);
+    expect((screen.getByRole('button', { name: 'Page 2' }) as HTMLButtonElement).disabled).toBe(true);
+  });
+});
+
+describe('Pagination — sx + slotProps', () => {
+  it('applies sx to root', () => {
+    const { container } = render(
+      <Pagination
+        page={1}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={() => {}}
+        sx="my-custom-root"
+      />,
+    );
+    expect(container.querySelector('nav')!.className).toContain('my-custom-root');
+  });
+
+  it('applies slotProps.pageButton.className', () => {
+    render(
+      <Pagination
+        page={1}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={() => {}}
+        slotProps={{ pageButton: { className: 'slot-page' } }}
+      />,
+    );
+    expect(screen.getByRole('button', { name: 'Page 2' }).className).toContain('slot-page');
+  });
+});
+
+describe('Pagination — edge cases', () => {
+  it('renders correctly with totalCount=0', () => {
+    render(<Pagination page={1} pageSize={10} totalCount={0} onPageChange={() => {}} />);
+    expect(screen.getByText(/Showing 0-0 of 0/)).not.toBeNull();
+    expect((screen.getByRole('button', { name: 'Previous' }) as HTMLButtonElement).disabled).toBe(true);
+    expect((screen.getByRole('button', { name: 'Next' }) as HTMLButtonElement).disabled).toBe(true);
+  });
+
+  it('clamps page > totalPages internally without crashing', () => {
+    let last = 0;
+    render(
+      <Pagination
+        page={99}
+        pageSize={10}
+        totalCount={50}
+        onPageChange={(p) => (last = p)}
+      />,
+    );
+    // Component computes safePage=5 (last valid). User clicks Prev → goes to 4.
+    fireEvent.click(screen.getByRole('button', { name: 'Previous' }));
+    expect(last).toBe(4);
+  });
+});

package/src/components/Pagination/Pagination.tsx

@@ -0,0 +1,275 @@
+import { useState, useCallback, type ChangeEvent, type KeyboardEvent } from 'react';
+import { cn } from '../../utils/cn.js';
+import { paginationVariants } from './pagination.variants.js';
+import { computePageRange } from './pagination.helpers.js';
+import type { PaginationProps, PaginationLabels } from './pagination.types.js';
+
+const DEFAULT_LABELS: Required<PaginationLabels> = {
+  first: 'First',
+  prev: 'Previous',
+  next: 'Next',
+  last: 'Last',
+  page: 'Page',
+  of: 'of',
+  showing: 'Showing',
+  perPage: 'per page',
+  goToPage: 'Go to page',
+};
+
+const DEFAULT_PAGE_SIZE_OPTIONS = [10, 20, 50, 100];
+
+/**
+ * Dashforge TW `<Pagination>` — controlled pagination primitive.
+ *
+ * Three variants:
+ *  - `default`  — page-size selector + summary + page numbers + nav buttons + jump input
+ *  - `compact`  — page numbers + nav buttons only (no summary, no selector, no jump)
+ *  - `minimal`  — "Page X of Y" + prev/next only
+ *
+ * Always controlled (no internal state besides the jump-input draft).
+ *
+ * A11Y:
+ *  - `<nav aria-label="Pagination">` root
+ *  - `aria-current="page"` on the active page button
+ *  - `aria-label` on every interactive element
+ *
+ * @example
+ * ```tsx
+ * const [page, setPage] = useState(1);
+ * const [pageSize, setPageSize] = useState(20);
+ *
+ * <Pagination
+ *   page={page}
+ *   pageSize={pageSize}
+ *   totalCount={1437}
+ *   onPageChange={setPage}
+ *   onPageSizeChange={setPageSize}
+ * />
+ * ```
+ */
+export function Pagination(props: PaginationProps) {
+  const {
+    page,
+    pageSize,
+    totalCount,
+    onPageChange,
+    onPageSizeChange,
+    pageSizeOptions = DEFAULT_PAGE_SIZE_OPTIONS,
+    siblingCount = 1,
+    boundaryCount = 1,
+    showFirstLast = true,
+    showJumpInput = true,
+    disabled = false,
+    labels: labelsProp,
+    variant = 'default',
+    size = 'md',
+    sx,
+    slotProps,
+  } = props;
+
+  const labels = { ...DEFAULT_LABELS, ...labelsProp };
+  const v = paginationVariants({ variant, size });
+
+  const totalPages = Math.max(1, Math.ceil(totalCount / pageSize));
+  const safePage = Math.min(Math.max(1, page), totalPages);
+
+  const pages = computePageRange(safePage, totalPages, siblingCount, boundaryCount);
+
+  // Summary range
+  const firstItem = totalCount === 0 ? 0 : (safePage - 1) * pageSize + 1;
+  const lastItem = Math.min(safePage * pageSize, totalCount);
+
+  // Jump input local state (commit on Enter or blur)
+  const [jumpDraft, setJumpDraft] = useState('');
+
+  const goTo = useCallback(
+    (nextPage: number) => {
+      if (disabled) return;
+      const clamped = Math.min(Math.max(1, nextPage), totalPages);
+      if (clamped !== safePage) onPageChange(clamped);
+    },
+    [disabled, totalPages, safePage, onPageChange],
+  );
+
+  const commitJump = useCallback(() => {
+    const parsed = Number(jumpDraft);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+      setJumpDraft('');
+      return;
+    }
+    goTo(Math.floor(parsed));
+    setJumpDraft('');
+  }, [jumpDraft, goTo]);
+
+  const onJumpKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLInputElement>) => {
+      if (e.key === 'Enter') {
+        e.preventDefault();
+        commitJump();
+      }
+    },
+    [commitJump],
+  );
+
+  const handlePageSize = useCallback(
+    (e: ChangeEvent<HTMLSelectElement>) => {
+      if (!onPageSizeChange) return;
+      const next = Number(e.target.value);
+      if (Number.isFinite(next) && next > 0) onPageSizeChange(next);
+    },
+    [onPageSizeChange],
+  );
+
+  const isMinimal = variant === 'minimal';
+
+  return (
+    <nav
+      aria-label="Pagination"
+      className={cn(v.root(), sx, slotProps?.root?.className)}
+    >
+      {/* Summary — only in `default` variant. `compact` skips it entirely.
+          `minimal` renders a different "Page X of Y" summary below. */}
+      {variant === 'default' && (
+        <span className={cn(v.summary(), slotProps?.summary?.className)}>
+          {labels.showing} {firstItem}-{lastItem} {labels.of} {totalCount}
+        </span>
+      )}
+
+      {/* Minimal-mode summary (text-only "Page X of Y") */}
+      {isMinimal && (
+        <span className={cn(v.summary(), 'text-sm', slotProps?.summary?.className)}>
+          {labels.page} {safePage} {labels.of} {totalPages}
+        </span>
+      )}
+
+      {/* Nav buttons + page list */}
+      <ul className={cn(v.list(), slotProps?.list?.className)}>
+        {showFirstLast && !isMinimal && (
+          <li>
+            <button
+              type="button"
+              aria-label={labels.first}
+              disabled={disabled || safePage === 1}
+              onClick={() => goTo(1)}
+              className={cn(v.navButton(), slotProps?.navButton?.className)}
+            >
+              «
+            </button>
+          </li>
+        )}
+        <li>
+          <button
+            type="button"
+            aria-label={labels.prev}
+            disabled={disabled || safePage === 1}
+            onClick={() => goTo(safePage - 1)}
+            className={cn(v.navButton(), slotProps?.navButton?.className)}
+          >
+            ‹
+          </button>
+        </li>
+        {/* Page-number buttons hidden in minimal mode */}
+        {!isMinimal &&
+          pages.map((entry, idx) =>
+            entry === 'ellipsis' ? (
+              <li key={`e-${idx}`}>
+                <span
+                  aria-hidden="true"
+                  className={cn(v.ellipsis(), slotProps?.ellipsis?.className)}
+                >
+                  …
+                </span>
+              </li>
+            ) : (
+              <li key={entry}>
+                <button
+                  type="button"
+                  aria-label={`${labels.page} ${entry}`}
+                  aria-current={entry === safePage ? 'page' : undefined}
+                  disabled={disabled}
+                  onClick={() => goTo(entry)}
+                  className={cn(
+                    v.pageButton(),
+                    entry === safePage && v.activeButton(),
+                    slotProps?.pageButton?.className,
+                    entry === safePage && slotProps?.activeButton?.className,
+                  )}
+                >
+                  {entry}
+                </button>
+              </li>
+            ),
+          )}
+        <li>
+          <button
+            type="button"
+            aria-label={labels.next}
+            disabled={disabled || safePage === totalPages}
+            onClick={() => goTo(safePage + 1)}
+            className={cn(v.navButton(), slotProps?.navButton?.className)}
+          >
+            ›
+          </button>
+        </li>
+        {showFirstLast && !isMinimal && (
+          <li>
+            <button
+              type="button"
+              aria-label={labels.last}
+              disabled={disabled || safePage === totalPages}
+              onClick={() => goTo(totalPages)}
+              className={cn(v.navButton(), slotProps?.navButton?.className)}
+            >
+              »
+            </button>
+          </li>
+        )}
+      </ul>
+
+      {/* Page-size selector + jump input — only in default variant */}
+      {variant === 'default' && onPageSizeChange && (
+        <label
+          className={cn(v.pageSizeSelector(), slotProps?.pageSizeSelector?.className)}
+        >
+          <span className="sr-only">{labels.perPage}</span>
+          <select
+            value={pageSize}
+            onChange={handlePageSize}
+            disabled={disabled}
+            aria-label={labels.perPage}
+            className={cn(
+              'rounded-md border border-neutral-300 dark:border-neutral-700 bg-white dark:bg-neutral-900 px-2 py-1',
+              'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+            )}
+          >
+            {pageSizeOptions.map((opt) => (
+              <option key={opt} value={opt}>
+                {opt}
+              </option>
+            ))}
+          </select>
+          <span>{labels.perPage}</span>
+        </label>
+      )}
+
+      {variant === 'default' && showJumpInput && (
+        <label className="inline-flex items-center gap-2">
+          <span className="sr-only">{labels.goToPage}</span>
+          <input
+            type="number"
+            min={1}
+            max={totalPages}
+            value={jumpDraft}
+            placeholder={labels.goToPage}
+            disabled={disabled}
+            onChange={(e) => setJumpDraft(e.target.value)}
+            onKeyDown={onJumpKeyDown}
+            onBlur={commitJump}
+            aria-label={labels.goToPage}
+            className={cn(v.jumpInput(), slotProps?.jumpInput?.className)}
+          />
+        </label>
+      )}
+    </nav>
+  );
+}

package/src/components/Pagination/pagination.helpers.ts

@@ -0,0 +1,102 @@
+/**
+ * Compute the array of page indices (or `'ellipsis'` sentinels) to
+ * render for a `<Pagination>`.
+ *
+ * Algorithm (standard "siblings + boundaries + ellipsis fill"):
+ *  1. Always show `boundaryCount` pages at the start and `boundaryCount`
+ *     at the end.
+ *  2. Show `siblingCount` pages on each side of the current page.
+ *  3. Fill gaps wider than 1 with `'ellipsis'`.
+ *  4. If a gap is exactly 1 page wide, include that page directly
+ *     (no ellipsis for a single hidden number).
+ *
+ * Output is 1-indexed page numbers OR the literal string `'ellipsis'`.
+ *
+ * @example
+ * ```ts
+ * range(1, 10, 1, 1)  // [1, 'ellipsis', 5, 'ellipsis', 10] when current=5
+ * range(1, 5, 1, 1)   // [1, 2, 3, 4, 5]
+ * range(1, 100, 1, 1) // edges varying with current
+ * ```
+ */
+export function computePageRange(
+  currentPage: number,
+  totalPages: number,
+  siblingCount: number,
+  boundaryCount: number,
+): (number | 'ellipsis')[] {
+  if (totalPages <= 0) return [];
+  if (totalPages === 1) return [1];
+
+  // Budget: if `totalPages` fits within boundaries + siblings + current
+  // (plus the 2 hypothetical ellipsis slots), don't bother with ellipses
+  // at all — list every page. Avoids the "[1, 2, …, 5]" footgun where
+  // the user expected to see 3 and 4 explicitly.
+  const minPagesForEllipsis = 2 * boundaryCount + 2 * siblingCount + 3;
+  if (totalPages <= minPagesForEllipsis) {
+    return range(1, totalPages);
+  }
+
+  const startBoundary = range(1, Math.min(boundaryCount, totalPages));
+  const endBoundary = range(
+    Math.max(totalPages - boundaryCount + 1, boundaryCount + 1),
+    totalPages,
+  );
+
+  const siblingsStart = Math.max(currentPage - siblingCount, boundaryCount + 2);
+  const siblingsEnd = Math.min(
+    currentPage + siblingCount,
+    totalPages - boundaryCount - 1,
+  );
+  const siblings = range(siblingsStart, siblingsEnd);
+
+  const showStartEllipsis = siblingsStart > boundaryCount + 2;
+  const showEndEllipsis = siblingsEnd < totalPages - boundaryCount - 1;
+
+  const out: (number | 'ellipsis')[] = [...startBoundary];
+
+  if (showStartEllipsis) {
+    out.push('ellipsis');
+  } else if (siblingsStart === boundaryCount + 2) {
+    // Single hidden page → fill it directly instead of an ellipsis.
+    out.push(boundaryCount + 1);
+  }
+
+  out.push(...siblings);
+
+  if (showEndEllipsis) {
+    out.push('ellipsis');
+  } else if (siblingsEnd === totalPages - boundaryCount - 1) {
+    out.push(totalPages - boundaryCount);
+  }
+
+  out.push(...endBoundary);
+
+  // Dedupe while preserving order (overlapping ranges produce duplicates
+  // when totalPages is small). Two distinct rules:
+  //   1. Number entries: keep only the first occurrence.
+  //   2. Ellipsis entries: collapse adjacent ellipses to one.
+  const seen = new Set<number>();
+  const deduped: (number | 'ellipsis')[] = [];
+  let prevWasEllipsis = false;
+  for (const entry of out) {
+    if (entry === 'ellipsis') {
+      if (!prevWasEllipsis) {
+        deduped.push('ellipsis');
+        prevWasEllipsis = true;
+      }
+      continue;
+    }
+    if (!seen.has(entry)) {
+      seen.add(entry);
+      deduped.push(entry);
+      prevWasEllipsis = false;
+    }
+  }
+  return deduped;
+}
+
+function range(start: number, end: number): number[] {
+  if (end < start) return [];
+  return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+}