@dashforge/tw 0.3.0-beta → 0.5.0-beta

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);
+}

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

@@ -0,0 +1,117 @@
+import type { PaginationVariants } from './pagination.variants.js';
+
+export interface PaginationSlotProps {
+  root?: { className?: string };
+  summary?: { className?: string };
+  list?: { className?: string };
+  pageButton?: { className?: string };
+  activeButton?: { className?: string };
+  navButton?: { className?: string };
+  ellipsis?: { className?: string };
+  pageSizeSelector?: { className?: string };
+  jumpInput?: { className?: string };
+}
+
+/**
+ * I18n strings for `<Pagination>`. Default = English. Override the
+ * subset you need to translate; the rest fall back to defaults.
+ */
+export interface PaginationLabels {
+  first?: string;
+  prev?: string;
+  next?: string;
+  last?: string;
+  page?: string;
+  of?: string;
+  showing?: string;
+  perPage?: string;
+  goToPage?: string;
+}
+
+/**
+ * Props for `<Pagination>`.
+ *
+ * Controlled component: the consumer owns `page` + `pageSize`. The
+ * component emits `onPageChange` / `onPageSizeChange` and recomputes
+ * the visible page range from `totalCount`.
+ *
+ * @example
+ * ```tsx
+ * const [page, setPage] = useState(1);
+ * const [pageSize, setPageSize] = useState(20);
+ *
+ * <Pagination
+ *   page={page}
+ *   pageSize={pageSize}
+ *   totalCount={1437}
+ *   onPageChange={setPage}
+ *   onPageSizeChange={setPageSize}
+ *   pageSizeOptions={[10, 20, 50, 100]}
+ * />
+ * ```
+ */
+export interface PaginationProps extends Pick<PaginationVariants, 'variant' | 'size'> {
+  /** Current page, **1-indexed**. */
+  page: number;
+
+  /** Items per page. */
+  pageSize: number;
+
+  /** Total items in the underlying data set (NOT total pages — we compute that). */
+  totalCount: number;
+
+  /** Fired when the user picks a different page. */
+  onPageChange: (page: number) => void;
+
+  /**
+   * Fired when the user picks a different page size. Omit (or pass
+   * undefined) to hide the page-size selector.
+   */
+  onPageSizeChange?: (pageSize: number) => void;
+
+  /**
+   * Options shown in the page-size selector.
+   * @default [10, 20, 50, 100]
+   */
+  pageSizeOptions?: number[];
+
+  /**
+   * How many page buttons to show on each side of the current page.
+   * @default 1
+   */
+  siblingCount?: number;
+
+  /**
+   * How many page buttons to always show at the start/end of the
+   * sequence (acts as "boundary"). @default 1
+   */
+  boundaryCount?: number;
+
+  /**
+   * Show first/last buttons (`«` / `»`). @default true
+   */
+  showFirstLast?: boolean;
+
+  /**
+   * Show the direct page-jump input (variant=`default` only).
+   * @default true
+   */
+  showJumpInput?: boolean;
+
+  /**
+   * Disable all interactive elements (kept rendered but inert).
+   */
+  disabled?: boolean;
+
+  /**
+   * I18n strings. Defaults are English; pass the subset you need
+   * to translate.
+   */
+  labels?: PaginationLabels;
+
+  /** Root-level Tailwind override. */
+  sx?: string;
+
+  /** Per-slot overrides. */
+  slotProps?: PaginationSlotProps;
+}

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

@@ -0,0 +1,111 @@
+import { tv, type VariantProps } from 'tailwind-variants';
+
+/**
+ * `<Pagination>` variant recipe.
+ *
+ * Slots:
+ *  - `root`             — outer `<nav>` container
+ *  - `summary`          — "Showing X-Y of Z" text
+ *  - `list`             — `<ul>` of page buttons
+ *  - `pageButton`       — individual page number button
+ *  - `activeButton`     — modifier applied to the current page
+ *  - `navButton`        — first/prev/next/last buttons
+ *  - `ellipsis`         — `…` rendered when range gap
+ *  - `pageSizeSelector` — native `<select>` for page size
+ *  - `jumpInput`        — direct page jump `<input>`
+ *
+ * Variant axes:
+ *  - `variant` — `default` (full kit) | `compact` (number buttons +
+ *    prev/next only) | `minimal` ("X / Y pages" + prev/next only).
+ *  - `size` — `sm` | `md` (default) | `lg`. Drives padding + text
+ *    size on the buttons.
+ */
+export const paginationVariants = tv({
+  slots: {
+    root: 'flex flex-wrap items-center gap-3',
+    summary: 'text-neutral-600 dark:text-neutral-400',
+    list: 'inline-flex items-center gap-1',
+    pageButton: [
+      'inline-flex items-center justify-center rounded-md',
+      'border border-neutral-300 dark:border-neutral-700',
+      'bg-white dark:bg-neutral-900',
+      'text-neutral-700 dark:text-neutral-300',
+      'hover:bg-neutral-50 dark:hover:bg-neutral-800',
+      'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+      'transition-colors motion-reduce:transition-none',
+      'disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none',
+    ],
+    activeButton: [
+      'bg-primary-500 text-white border-primary-500',
+      'hover:bg-primary-600 dark:hover:bg-primary-400',
+    ],
+    navButton: [
+      'inline-flex items-center justify-center rounded-md',
+      'border border-neutral-300 dark:border-neutral-700',
+      'bg-white dark:bg-neutral-900',
+      'text-neutral-700 dark:text-neutral-300',
+      'hover:bg-neutral-50 dark:hover:bg-neutral-800',
+      'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+      'transition-colors motion-reduce:transition-none',
+      'disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none',
+    ],
+    ellipsis: 'inline-flex items-center justify-center text-neutral-500 px-1',
+    pageSizeSelector: [
+      'inline-flex items-center gap-2',
+      'text-neutral-700 dark:text-neutral-300',
+    ],
+    jumpInput: [
+      'rounded-md border border-neutral-300 dark:border-neutral-700',
+      'bg-white dark:bg-neutral-900',
+      'text-neutral-900 dark:text-neutral-50',
+      'focus:outline-none focus-visible:ring-2 focus-visible:ring-primary-500',
+      'transition-colors motion-reduce:transition-none',
+    ],
+  },
+  variants: {
+    // Note: variant-driven visibility is enforced via conditional JSX
+    // rendering (in `Pagination.tsx`), NOT via `hidden` Tailwind class.
+    // Reason: `display: none` keeps the elements in the DOM (and in the
+    // a11y tree depending on how it's applied), which leaks into
+    // testing-library `queryByText` and feels semantically wrong for
+    // "this UI piece doesn't exist in this variant". So compact and
+    // minimal slots stay empty here.
+    variant: {
+      default: {},
+      compact: {},
+      minimal: {},
+    },
+    size: {
+      sm: {
+        summary: 'text-xs',
+        pageButton: 'h-7 min-w-7 px-2 text-xs',
+        navButton: 'h-7 min-w-7 px-2 text-xs',
+        ellipsis: 'h-7 min-w-5 text-xs',
+        pageSizeSelector: 'text-xs',
+        jumpInput: 'h-7 px-2 text-xs w-14',
+      },
+      md: {
+        summary: 'text-sm',
+        pageButton: 'h-9 min-w-9 px-3 text-sm',
+        navButton: 'h-9 min-w-9 px-3 text-sm',
+        ellipsis: 'h-9 min-w-6 text-sm',
+        pageSizeSelector: 'text-sm',
+        jumpInput: 'h-9 px-2 text-sm w-16',
+      },
+      lg: {
+        summary: 'text-base',
+        pageButton: 'h-10 min-w-10 px-4 text-base',
+        navButton: 'h-10 min-w-10 px-4 text-base',
+        ellipsis: 'h-10 min-w-7 text-base',
+        pageSizeSelector: 'text-base',
+        jumpInput: 'h-10 px-3 text-base w-20',
+      },
+    },
+  },
+  defaultVariants: {
+    variant: 'default',
+    size: 'md',
+  },
+});
+
+export type PaginationVariants = VariantProps<typeof paginationVariants>;

package/src/components/Popover/Popover.test.tsx

@@ -0,0 +1,72 @@
+// @vitest-environment jsdom
+import * as React from 'react';
+import { describe, it, expect, afterEach, beforeAll } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+import { Popover } from './Popover.js';
+
+void React;
+afterEach(() => cleanup());
+
+// jsdom doesn't implement ResizeObserver — Radix Floating UI requires it.
+beforeAll(() => {
+  if (typeof globalThis.ResizeObserver === 'undefined') {
+    (globalThis as unknown as { ResizeObserver: unknown }).ResizeObserver = class {
+      observe() {}
+      unobserve() {}
+      disconnect() {}
+    };
+  }
+});
+
+describe('Popover — rendering', () => {
+  it('renders the trigger always', () => {
+    render(
+      <Popover content={<p>Panel</p>}>
+        <button>Open panel</button>
+      </Popover>
+    );
+    expect(screen.queryByRole('button', { name: 'Open panel' })).not.toBeNull();
+  });
+
+  it('renders content when controlled open=true', () => {
+    render(
+      <Popover content={<p>Panel content</p>} open onOpenChange={() => {}}>
+        <button>Open panel</button>
+      </Popover>
+    );
+    expect(screen.queryByText('Panel content')).not.toBeNull();
+  });
+
+  it('does not render content when open=false', () => {
+    render(
+      <Popover content={<p>Panel content</p>} open={false} onOpenChange={() => {}}>
+        <button>Open panel</button>
+      </Popover>
+    );
+    expect(screen.queryByText('Panel content')).toBeNull();
+  });
+});
+
+describe('Popover — placement', () => {
+  it.each(['top', 'right', 'bottom', 'left'] as const)(
+    'renders side=%s without crashing',
+    (side) => {
+      render(
+        <Popover content={<p>Panel</p>} open side={side} onOpenChange={() => {}}>
+          <button>T</button>
+        </Popover>
+      );
+      expect(screen.queryByText('Panel')).not.toBeNull();
+    }
+  );
+
+  it('applies width style', () => {
+    render(
+      <Popover content={<p>Panel</p>} open width="300px" onOpenChange={() => {}}>
+        <button>T</button>
+      </Popover>
+    );
+    const content = screen.getByText('Panel').closest('[role="dialog"]') as HTMLElement | null;
+    expect(content?.style.width).toBe('300px');
+  });
+});