@slipstream-ui/core 0.3.0 → 0.4.0

package/src/components/file-upload/FileUpload.tsx

@@ -0,0 +1,143 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '../../utils/cn';
+
+export type FileUploadProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'value' | 'onChange'> & {
+  /** Controlled selection. */
+  files?: File[];
+  /** Initial selection when uncontrolled. */
+  defaultFiles?: File[];
+  /** Fired whenever the list changes (add, remove, drop, clear). */
+  onFilesChange?: (files: File[]) => void;
+  /** Drag-and-drop area copy. */
+  label?: string;
+  hint?: string;
+  /** Per-file progress (0-100) keyed by file name, rendered as a bar. */
+  progress?: Record<string, number>;
+};
+
+function formatSize(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+/**
+ * Drag-and-drop file picker with a removable list. The native input drives
+ * selection (keyboard + mobile camera/file dialogs); the drop zone is a
+ * progressive enhancement. Files are plain `File` objects, so you own the
+ * upload transport and can render progress per file.
+ */
+export const FileUpload = React.forwardRef<HTMLInputElement, FileUploadProps>(function FileUpload(
+  {
+    files,
+    defaultFiles,
+    onFilesChange,
+    label = 'Drop files here or click to browse',
+    hint,
+    progress,
+    multiple = true,
+    accept,
+    disabled,
+    className,
+    id,
+    ...props
+  },
+  ref
+) {
+  const [internal, setInternal] = React.useState<File[]>(defaultFiles ?? []);
+  const [dragging, setDragging] = React.useState(false);
+  const current = files ?? internal;
+  const generatedId = React.useId();
+  const inputId = id ?? generatedId;
+
+  const commit = (next: File[]) => {
+    if (files === undefined) setInternal(next);
+    onFilesChange?.(next);
+  };
+
+  const add = (incoming: FileList | null) => {
+    if (!incoming || incoming.length === 0) return;
+    const list = Array.from(incoming);
+    commit(multiple ? [...current, ...list] : list.slice(0, 1));
+  };
+
+  return (
+    <div className={cn('flex flex-col gap-3', className)}>
+      <div
+        onDragOver={(event) => {
+          if (disabled) return;
+          event.preventDefault();
+          setDragging(true);
+        }}
+        onDragLeave={() => setDragging(false)}
+        onDrop={(event) => {
+          if (disabled) return;
+          event.preventDefault();
+          setDragging(false);
+          add(event.dataTransfer.files);
+        }}
+        className={cn(
+          'rounded-lg border border-dashed border-border p-6 text-center transition-colors',
+          dragging && 'border-primary bg-primary/5',
+          disabled && 'opacity-50'
+        )}
+      >
+        <label htmlFor={inputId} className={cn('block text-sm', disabled ? 'cursor-not-allowed' : 'cursor-pointer')}>
+          {label}
+          <input
+            ref={ref}
+            id={inputId}
+            type="file"
+            multiple={multiple}
+            accept={accept}
+            disabled={disabled}
+            className="sr-only"
+            onChange={(event) => {
+              add(event.target.files);
+              event.target.value = '';
+            }}
+            {...props}
+          />
+        </label>
+        <p className="mt-1 text-xs text-muted-foreground">
+          {hint ?? (accept ? `Accepted: ${accept}` : 'Any file type')}
+        </p>
+      </div>
+
+      {current.length > 0 && (
+        <ul aria-label="Selected files" className="space-y-2">
+          {current.map((file) => (
+            <li key={file.name} className="flex items-center justify-between gap-3 rounded-md border border-border px-3 py-2">
+              <div className="min-w-0">
+                <p className="truncate text-sm">{file.name}</p>
+                <p className="text-xs text-muted-foreground">{formatSize(file.size)}</p>
+                {progress?.[file.name] !== undefined && (
+                  <div
+                    role="progressbar"
+                    aria-valuenow={progress[file.name]}
+                    aria-valuemin={0}
+                    aria-valuemax={100}
+                    aria-label={`Uploading ${file.name}`}
+                    className="mt-1 h-1.5 w-40 overflow-hidden rounded-full bg-muted"
+                  >
+                    <div className="h-full bg-primary" style={{ width: `${progress[file.name]}%` }} />
+                  </div>
+                )}
+              </div>
+              <button
+                type="button"
+                onClick={() => commit(current.filter((entry) => entry.name !== file.name))}
+                aria-label={`Remove ${file.name}`}
+                className="rounded p-1 text-muted-foreground hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+              >
+                ✕
+              </button>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+});

package/src/components/file-upload/index.ts

@@ -0,0 +1 @@
+export * from './FileUpload';

package/src/components/filter-bar/FilterBar.test.tsx

@@ -0,0 +1,32 @@
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { axe } from 'jest-axe';
+import { describe, expect, it, vi } from 'vitest';
+import { FilterBar } from './FilterBar';
+
+describe('FilterBar', () => {
+  it('reports search input changes', async () => {
+    const user = userEvent.setup();
+    const onSearchChange = vi.fn();
+    render(<FilterBar searchValue="" onSearchChange={onSearchChange} searchPlaceholder="Search classes" />);
+    await user.type(screen.getByRole('searchbox', { name: 'Search classes' }), 'ab');
+    expect(onSearchChange).toHaveBeenCalled();
+  });
+
+  it('shows a reset button with the active count and fires it', async () => {
+    const user = userEvent.setup();
+    const onReset = vi.fn();
+    render(<FilterBar onReset={onReset} activeCount={2}><span>filters</span></FilterBar>);
+    await user.click(screen.getByRole('button', { name: 'Reset (2)' }));
+    expect(onReset).toHaveBeenCalledOnce();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <FilterBar searchValue="" onSearchChange={() => undefined} onReset={() => undefined}>
+        <select aria-label="Status"><option>All</option></select>
+      </FilterBar>
+    );
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/filter-bar/FilterBar.tsx

@@ -0,0 +1,71 @@
+'use client';
+
+import * as React from 'react';
+import { cn } from '../../utils/cn';
+import { Button } from '../button/Button';
+import { Input } from '../input/Input';
+
+export type FilterBarProps = React.HTMLAttributes<HTMLDivElement> & {
+  /** Controlled search text. */
+  searchValue?: string;
+  onSearchChange?: (value: string) => void;
+  /** Search placeholder; the search box is hidden when omitted. */
+  searchPlaceholder?: string;
+  /** Rendered after the search box — selects, toggles, date pickers. */
+  children?: React.ReactNode;
+  /** Shows a reset button when provided (pass the active filter count for the label). */
+  onReset?: () => void;
+  activeCount?: number;
+  /** Rendered at the far right (bulk actions, column settings). */
+  trailing?: React.ReactNode;
+};
+
+/**
+ * Horizontal filter strip for list pages: search field, filter controls and
+ * a reset affordance. Scrolls horizontally on narrow screens instead of
+ * wrapping into a tall stack.
+ */
+export const FilterBar = React.forwardRef<HTMLDivElement, FilterBarProps>(function FilterBar(
+  {
+    searchValue,
+    onSearchChange,
+    searchPlaceholder = 'Search…',
+    onReset,
+    activeCount = 0,
+    trailing,
+    className,
+    children,
+    ...props
+  },
+  ref
+) {
+  return (
+    <div
+      ref={ref}
+      role="search"
+      className={cn(
+        'flex flex-wrap items-center gap-2 rounded-lg border border-border bg-card p-2',
+        className
+      )}
+      {...props}
+    >
+      {onSearchChange !== undefined && (
+        <Input
+          type="search"
+          value={searchValue}
+          onChange={(event) => onSearchChange(event.target.value)}
+          placeholder={searchPlaceholder}
+          aria-label={searchPlaceholder}
+          className="h-9 w-full min-w-40 flex-1 sm:w-auto"
+        />
+      )}
+      <div className="flex flex-wrap items-center gap-2">{children}</div>
+      {onReset && (
+        <Button type="button" variant="ghost" size="sm" onClick={onReset}>
+          Reset{activeCount > 0 ? ` (${activeCount})` : ''}
+        </Button>
+      )}
+      {trailing && <div className="ml-auto flex items-center gap-2">{trailing}</div>}
+    </div>
+  );
+});

package/src/components/filter-bar/index.ts

@@ -0,0 +1 @@
+export * from './FilterBar';

package/src/components/input-group/InputGroup.test.tsx

@@ -15,9 +15,12 @@ describe('InputGroup', () => {
     );
     const group = container.querySelector('[data-slot="input-group"]')!;
     expect(group).toHaveClass('border', 'rounded-md', 'focus-within:ring-2');
-    // Chrome-stripping rides on descendant selectors in the group's class.
-    expect(group.className).toContain('[&_input]:border-0');
-    expect(group.className).toContain('[&_input]:bg-transparent');
+    // Chrome-stripping rides on important descendant selectors in the
+    // group's class so no inner border/outline can show at addon seams.
+    expect(group.className).toContain('[&_input]:!border-0');
+    expect(group.className).toContain('[&_input]:!bg-transparent');
+    expect(group.className).toContain('[&_input]:!ring-0');
+    expect(group.className).toContain('[&_input]:!outline-none');
     expect(group.className).toContain('[&_input]:flex-1');
     expect(group.querySelector('input')).toHaveAttribute('placeholder', 'Search');
   });

package/src/components/input-group/InputGroup.tsx

@@ -56,12 +56,15 @@ const InputGroup = React.forwardRef<HTMLDivElement, InputGroupProps>(
         className={cn(
           'flex h-10 w-full items-center overflow-hidden rounded-md border border-input bg-background',
           'ring-offset-background focus-within:ring-2 focus-within:ring-ring focus-within:ring-offset-2',
-          // The group is the control: strip chrome from nested fields so
-          // only the outer border shows. Literal variants survive purging.
-          '[&_input]:min-w-0 [&_input]:flex-1 [&_input]:border-0 [&_input]:bg-transparent [&_input]:px-3 [&_input]:py-2 [&_input]:shadow-none',
-          '[&_input]:focus-visible:ring-0 [&_input]:focus-visible:ring-offset-0',
-          '[&_textarea]:border-0 [&_textarea]:bg-transparent [&_textarea]:shadow-none [&_textarea]:focus-visible:ring-0',
-          '[&_select]:border-0 [&_select]:bg-transparent [&_select]:shadow-none [&_select]:focus-visible:ring-0',
+          // The group's outline is the only outline: force-strip every
+          // nested field's border, radius, ring, shadow and UA focus outline.
+          // Important flags defeat both the component's own utilities
+          // (Input ships `border` + `focus-visible:ring-2`) and browser
+          // defaults — no seams appear where an addon sits flush.
+          '[&_input]:h-full [&_input]:min-w-0 [&_input]:flex-1 [&_input]:rounded-none [&_input]:px-3 [&_input]:py-2',
+          '[&_input]:!border-0 [&_input]:!bg-transparent [&_input]:!shadow-none [&_input]:!outline-none [&_input]:!ring-0 [&_input]:!ring-offset-0',
+          '[&_textarea]:!border-0 [&_textarea]:!rounded-none [&_textarea]:!bg-transparent [&_textarea]:!shadow-none [&_textarea]:!outline-none [&_textarea]:!ring-0 [&_textarea]:!ring-offset-0',
+          '[&_select]:!border-0 [&_select]:!rounded-none [&_select]:!bg-transparent [&_select]:!shadow-none [&_select]:!outline-none [&_select]:!ring-0 [&_select]:!ring-offset-0',
           '[&_input:disabled]:cursor-not-allowed',
           className
         )}

package/src/components/menu/Menu.test.tsx

@@ -88,3 +88,24 @@ describe('Menu', () => {
     expect(await axe(container)).toHaveNoViolations();
   });
 });
+
+
+describe('MenuItem asChild', () => {
+  it('renders a link with menuitem semantics', async () => {
+    const user = userEvent.setup();
+    render(
+      <Menu>
+        <MenuTrigger>Options</MenuTrigger>
+        <MenuContent>
+          <MenuItem asChild>
+            <a href="/settings">Settings</a>
+          </MenuItem>
+        </MenuContent>
+      </Menu>
+    );
+    await user.click(screen.getByRole('button', { name: 'Options' }));
+    const item = screen.getByRole('menuitem', { name: 'Settings' });
+    expect(item.tagName).toBe('A');
+    expect(item).toHaveAttribute('href', '/settings');
+  });
+});

package/src/components/menu/Menu.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { createPortal } from 'react-dom';
+import { Slot } from '@radix-ui/react-slot';
 import { cn } from '../../utils/cn';
 
 type MenuContextValue = {
@@ -214,16 +215,20 @@ MenuContent.displayName = 'MenuContent';
 export type MenuItemProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
   /** Renders the item in a destructive style. */
   destructive?: boolean;
+  /** Render the child element (e.g. an <a>) as the menu item. */
+  asChild?: boolean;
 };
 
 /** A single action item in the menu. */
 const MenuItem = React.forwardRef<HTMLButtonElement, MenuItemProps>(
-  ({ className, destructive, onClick, ...props }, ref) => {
+  ({ className, destructive, asChild = false, onClick, ...props }, ref) => {
     const { setOpen } = React.useContext(MenuContext);
+    const Comp = asChild ? Slot : 'button';
+    const typeProp = asChild ? {} : { type: 'button' as const };
     return (
-      <button
+      <Comp
         ref={ref}
-        type="button"
+        {...typeProp}
         role="menuitem"
         onClick={(event) => {
           onClick?.(event);

package/src/components/metric-card/MetricCard.test.tsx

@@ -0,0 +1,28 @@
+import { render, screen } from '@testing-library/react';
+import { axe } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { MetricCard } from './MetricCard';
+
+describe('MetricCard', () => {
+  it('renders label, value, delta and hint with a direction glyph', () => {
+    render(<MetricCard label="Revenue" value="$12,480" delta="+12.4%" trend="up" hint="vs last month" />);
+    expect(screen.getByText('Revenue')).toBeInTheDocument();
+    expect(screen.getByText('$12,480')).toBeInTheDocument();
+    expect(screen.getByText(/12.4%/)).toBeInTheDocument();
+    expect(screen.getByText('vs last month')).toBeInTheDocument();
+  });
+
+  it('colors trends but never relies on color alone', () => {
+    const { rerender } = render(<MetricCard label="Churn" value="2.1%" delta="-0.4" trend="down" />);
+    const delta = screen.getByText(/-0.4/);
+    expect(delta).toHaveClass('text-destructive');
+    expect(delta.textContent).toContain('↓');
+    rerender(<MetricCard label="Churn" value="2.1%" delta="0" trend="flat" />);
+    expect(screen.getByText(/0/).textContent).toContain('→');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<MetricCard label="Users" value={1234} delta="+3%" trend="up" />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/metric-card/MetricCard.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { cn } from '../../utils/cn';
+
+export type MetricTrend = 'up' | 'down' | 'flat';
+
+export type MetricCardProps = Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> & {
+  label: string;
+  value: string | number;
+  /** Secondary line under the value. */
+  hint?: string;
+  /** Signed change, e.g. "+12.4%" or "-3". */
+  delta?: string;
+  /** Direction colors the delta (green up / red down / muted flat). */
+  trend?: MetricTrend;
+  icon?: React.ReactNode;
+};
+
+const trendClasses: Record<MetricTrend, string> = {
+  up: 'text-success',
+  down: 'text-destructive',
+  flat: 'text-muted-foreground',
+};
+
+const trendGlyph: Record<MetricTrend, string> = { up: '↑', down: '↓', flat: '→' };
+
+/**
+ * Compact KPI tile: label, value, optional delta with direction color and a
+ * supporting hint. Deltas always carry an arrow glyph so the direction is
+ * never communicated by color alone.
+ */
+export const MetricCard = React.forwardRef<HTMLDivElement, MetricCardProps>(function MetricCard(
+  { label, value, hint, delta, trend = 'flat', icon, className, ...props },
+  ref
+) {
+  return (
+    <div ref={ref} className={cn('rounded-xl border border-border bg-card p-5', className)} {...props}>
+      <div className="flex items-start justify-between gap-3">
+        <p className="text-sm text-muted-foreground">{label}</p>
+        {icon && <span className="text-muted-foreground [&_svg]:size-4">{icon}</span>}
+      </div>
+      <p className="mt-2 text-2xl font-semibold tabular-nums">{value}</p>
+      {(delta || hint) && (
+        <p className="mt-1 flex items-center gap-2 text-sm">
+          {delta && (
+            <span className={cn('font-medium tabular-nums', trendClasses[trend])}>
+              <span aria-hidden="true">{trendGlyph[trend]}</span> {delta}
+            </span>
+          )}
+          {hint && <span className="text-muted-foreground">{hint}</span>}
+        </p>
+      )}
+    </div>
+  );
+});

package/src/components/metric-card/index.ts

@@ -0,0 +1 @@
+export * from './MetricCard';

package/src/components/page-header/PageHeader.test.tsx

@@ -0,0 +1,31 @@
+import { render, screen } from '@testing-library/react';
+import { axe } from 'jest-axe';
+import { describe, expect, it } from 'vitest';
+import { PageHeader } from './PageHeader';
+
+describe('PageHeader', () => {
+  it('renders a level-1 heading with description and actions', () => {
+    render(
+      <PageHeader
+        title="Classes"
+        description="Manage your weekly schedule."
+        actions={<button type="button">New</button>}
+        breadcrumbs={<a href="/">Home</a>}
+      />
+    );
+    expect(screen.getByRole('heading', { level: 1, name: 'Classes' })).toBeInTheDocument();
+    expect(screen.getByText('Manage your weekly schedule.')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'New' })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'Home' })).toBeInTheDocument();
+  });
+
+  it('renders children under the title row', () => {
+    render(<PageHeader title="Reports"><span>tabs</span></PageHeader>);
+    expect(screen.getByText('tabs')).toBeInTheDocument();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(<PageHeader title="Dashboard" description="Overview" />);
+    expect(await axe(container)).toHaveNoViolations();
+  });
+});

package/src/components/page-header/PageHeader.tsx

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import { cn } from '../../utils/cn';
+
+export type PageHeaderProps = React.HTMLAttributes<HTMLDivElement> & {
+  title: string;
+  description?: string;
+  /** Breadcrumbs/eyebrow above the title. */
+  breadcrumbs?: React.ReactNode;
+  /** Right-aligned actions (buttons, menus). */
+  actions?: React.ReactNode;
+  /** Small slot under the title row (tabs, filters). */
+  children?: React.ReactNode;
+};
+
+/**
+ * Standard page heading block: optional breadcrumbs, title, description and
+ * a right-aligned action cluster. Pages stop inventing their own spacing
+ * and heading hierarchy.
+ */
+export const PageHeader = React.forwardRef<HTMLDivElement, PageHeaderProps>(function PageHeader(
+  { title, description, breadcrumbs, actions, className, children, ...props },
+  ref
+) {
+  return (
+    <div ref={ref} className={cn('flex flex-col gap-2', className)} {...props}>
+      {breadcrumbs && <div className="text-sm text-muted-foreground">{breadcrumbs}</div>}
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div className="min-w-0">
+          <h1 className="text-2xl font-semibold tracking-tight">{title}</h1>
+          {description && <p className="mt-1 max-w-2xl text-sm text-muted-foreground">{description}</p>}
+        </div>
+        {actions && <div className="flex shrink-0 items-center gap-2">{actions}</div>}
+      </div>
+      {children && <div className="mt-2">{children}</div>}
+    </div>
+  );
+});

package/src/components/page-header/index.ts

@@ -0,0 +1 @@
+export * from './PageHeader';

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

@@ -88,3 +88,28 @@ describe('Pagination boundaries and icons', () => {
     expect(screen.getByRole('button', { name: 'Last page' })).toHaveTextContent('⏭');
   });
 });
+
+
+describe('Pagination contracts and summary', () => {
+  it('accepts currentPage/totalPages aliases', () => {
+    render(<Pagination currentPage={3} totalPages={5} />);
+    expect(screen.getByRole('button', { name: 'Page 3' })).toHaveAttribute('aria-current', 'page');
+    expect(screen.getByRole('button', { name: 'Page 5' })).toBeInTheDocument();
+  });
+
+  it('derives the page count and renders a summary from total/pageSize', () => {
+    render(<Pagination page={2} pageSize={25} total={312} itemLabel="students" />);
+    expect(screen.getByText('Showing 26–50 of 312 students')).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: 'Page 13' })).toBeInTheDocument();
+  });
+
+  it('can hide the summary explicitly', () => {
+    render(<Pagination page={1} pageSize={10} total={40} showSummary={false} />);
+    expect(screen.queryByText(/Showing/)).not.toBeInTheDocument();
+  });
+
+  it('falls back to a page summary when totals are absent', () => {
+    render(<Pagination page={2} currentPage={2} pageSize={10} total={40} itemLabel="rows" />);
+    expect(screen.getByText('Showing 11–20 of 40 rows')).toBeInTheDocument();
+  });
+});

package/src/components/pagination/Pagination.tsx

@@ -15,10 +15,22 @@ export type PaginationIcons = {
 };
 
 export type PaginationProps = React.HTMLAttributes<HTMLElement> & {
-  /** Current page number (1-based). */
-  page: number;
-  /** Total number of pages. */
-  pageCount: number;
+  /** Current page number (1-based). Alias: currentPage. */
+  page?: number;
+  /** Total number of pages. Alias: totalPages (or derived from total/pageSize). */
+  pageCount?: number;
+  /** Alias for page (migration-friendly). */
+  currentPage?: number;
+  /** Alias for pageCount. */
+  totalPages?: number;
+  /** Rows per page — with `total`, enables the item-count summary. */
+  pageSize?: number;
+  /** Total item count — with `pageSize`, enables the summary and derives pageCount. */
+  total?: number;
+  /** Noun used in the summary ("Showing 26–50 of 312 classes"). Default "items". */
+  itemLabel?: string;
+  /** Force the summary on/off; defaults to on when total and pageSize are set. */
+  showSummary?: boolean;
   /** Called with the new page number. */
   onPageChange?: (page: number) => void;
   /** How many page buttons to show around the current page (default 1). */
@@ -38,16 +50,22 @@ const controlClass =
 
 /**
  * Numeric pagination with prev/next and optional boundary jumps. Renders
- * as a nav landmark with aria-current="page" on the active button. Each
- * control is a real <button> with an accessible name; glyphs are
- * swappable and each boundary button can be shown or hidden independently
- * (e.g. hide — instead of disabling — once you reach the list edge).
+ * as a nav landmark with aria-current="page" on the active button. Accepts
+ * either page/pageCount or the currentPage/totalPages aliases, and can
+ * derive the page count (plus a "Showing X–Y of Z" summary) from
+ * total/pageSize.
  */
 const Pagination = React.forwardRef<HTMLElement, PaginationProps>(
   (
     {
-      page,
-      pageCount,
+      page: pageProp,
+      pageCount: pageCountProp,
+      currentPage,
+      totalPages,
+      pageSize,
+      total,
+      itemLabel = 'items',
+      showSummary,
       onPageChange,
       siblings = 1,
       showBoundaries = false,
@@ -59,6 +77,11 @@ const Pagination = React.forwardRef<HTMLElement, PaginationProps>(
     },
     ref
   ) => {
+    const page = pageProp ?? currentPage ?? 1;
+    const derivedPageCount =
+      total !== undefined && pageSize !== undefined && pageSize > 0 ? Math.ceil(total / pageSize) : undefined;
+    const pageCount = Math.max(1, pageCountProp ?? totalPages ?? derivedPageCount ?? 1);
+
     // Build the page number list with ellipsis markers.
     const pages: (number | 'ellipsis')[] = [];
     const start = Math.max(2, page - siblings);
@@ -73,11 +96,16 @@ const Pagination = React.forwardRef<HTMLElement, PaginationProps>(
     const withFirst = showFirst ?? showBoundaries;
     const withLast = showLast ?? showBoundaries;
 
-    return (
+    const summaryEnabled = showSummary ?? (total !== undefined && pageSize !== undefined);
+    const rangeStart = pageSize !== undefined ? (page - 1) * pageSize + 1 : undefined;
+    const rangeEnd =
+      pageSize !== undefined && total !== undefined ? Math.min(total, page * pageSize) : undefined;
+
+    const nav = (
       <nav
         ref={ref}
         aria-label="Pagination"
-        className={cn('flex items-center justify-center gap-1', className)}
+        className={cn('flex items-center justify-center gap-1', summaryEnabled ? undefined : className)}
         {...props}
       >
         {withFirst && (
@@ -150,6 +178,19 @@ const Pagination = React.forwardRef<HTMLElement, PaginationProps>(
         )}
       </nav>
     );
+
+    if (!summaryEnabled) return nav;
+
+    return (
+      <div className={cn('flex flex-wrap items-center justify-between gap-3', className)}>
+        <p className="text-sm text-muted-foreground">
+          {rangeStart !== undefined && rangeEnd !== undefined && total !== undefined
+            ? `Showing ${rangeStart}–${rangeEnd} of ${total} ${itemLabel}`
+            : `Page ${page} of ${pageCount}`}
+        </p>
+        {nav}
+      </div>
+    );
   }
 );
 Pagination.displayName = 'Pagination';