@tangle-network/ui 11.23.0 → 11.24.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @tangle-network/ui
 
+## 11.24.0
+
+### Minor Changes
+
+- 6098fc6: Pagination: add a link mode for lists paged by URL. Pass `hrefFor` (zero-based page in, URL out) instead of `onPageChange` and each enabled control renders as a link, through `linkComponent` (default `"a"`) when a router link is needed. The current page carries `aria-current="page"`, and a disabled previous or next renders as a `<span aria-disabled="true">` with no `href`. `PaginationProps` is now a union of `PaginationButtonProps` and `PaginationLinkProps`; button mode is unchanged.
+
 ## 11.23.0
 
 ### Minor Changes

package/dist/primitives/pagination.d.ts

@@ -1,19 +1,57 @@
 import * as React from "react";
 //#region src/primitives/pagination.d.ts
+interface PaginationBaseProps extends Omit<React.HTMLAttributes<HTMLElement>, "onChange" | "children"> {
+  /** The current page, zero-based. */
+  page: number;
+  pageCount: number;
+  /** Pages shown on each side of the current one before an ellipsis. */
+  siblings?: number;
+}
+export interface PaginationButtonProps extends PaginationBaseProps {
+  onPageChange: (page: number) => void;
+  hrefFor?: never;
+  linkComponent?: never;
+}
+export interface PaginationLinkProps extends PaginationBaseProps {
+  /** The URL of a page, given the zero-based page. */
+  hrefFor: (page: number) => string;
+  /** Renders each enabled control. Receives `href`; defaults to `"a"`. */
+  linkComponent?: React.ElementType;
+  /**
+   * Called with the target page when a link to another page is clicked, unless
+   * the click opens it in another tab or window.
+   */
+  onPageChange?: (page: number) => void;
+}
 /**
  * Page controls for a paged list or table: previous, the page numbers around
  * the current one with the first and last always reachable, and next.
  *
  * Pages are zero-based in the API and one-based on screen. With one page or
  * none there is nothing to choose, so it renders nothing.
+ *
+ * Give `onPageChange` to render buttons, or `hrefFor` to render links for a
+ * list paged by URL. In link mode each enabled control is rendered by
+ * `linkComponent` (an `<a>` by default) with `href`, `className`,
+ * `aria-label`, `aria-current` and children; a disabled previous or next is a
+ * `<span aria-disabled="true">` with no `href`. A router whose link takes `to`
+ * instead of `href` needs a small adapter:
+ *
+ * ```tsx
+ * import { Link } from "react-router";
+ *
+ * const RouterLink = ({ href, ...props }: React.ComponentProps<"a">) => (
+ *   <Link to={href ?? ""} {...props} />
+ * );
+ *
+ * <Pagination
+ *   page={page}
+ *   pageCount={pageCount}
+ *   hrefFor={(p) => `?page=${p + 1}`}
+ *   linkComponent={RouterLink}
+ * />
+ * ```
  */
-export interface PaginationProps extends Omit<React.HTMLAttributes<HTMLElement>, "onChange" | "children"> {
-  /** The current page, zero-based. */
-  page: number;
-  pageCount: number;
-  onPageChange: (page: number) => void;
-  /** Pages shown on each side of the current one before an ellipsis. */
-  siblings?: number;
-}
-export declare function Pagination({ page, pageCount, onPageChange, siblings, className, "aria-label": ariaLabel, ...rest }: PaginationProps): React.JSX.Element | null;
+export type PaginationProps = PaginationButtonProps | PaginationLinkProps;
+export declare function Pagination({ page, pageCount, onPageChange, hrefFor, linkComponent: LinkComponent, siblings, className, "aria-label": ariaLabel, ...rest }: PaginationProps): React.JSX.Element | null;
 //#endregion

package/dist/primitives/pagination.js

@@ -1,7 +1,7 @@
 import { cn } from "../lib/utils.js";
 import { buttonVariants } from "./button.js";
 import "react";
-import { jsx, jsxs } from "react/jsx-runtime";
+import { Fragment as Fragment$1, jsx, jsxs } from "react/jsx-runtime";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 //#region src/primitives/pagination.tsx
 /**
@@ -24,13 +24,46 @@ const pageButton = cn(buttonVariants({
 	variant: "ghost",
 	size: "sm"
 }), "min-w-8 px-2 tabular-nums");
-function Pagination({ page, pageCount, onPageChange, siblings = 1, className, "aria-label": ariaLabel = "Pagination", ...rest }) {
+/** A click that opens the link in another tab or window leaves this page where it is. */
+function opensElsewhere(event) {
+	return event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey;
+}
+function Pagination({ page, pageCount, onPageChange, hrefFor, linkComponent: LinkComponent = "a", siblings = 1, className, "aria-label": ariaLabel = "Pagination", ...rest }) {
 	if (pageCount <= 1) return null;
 	const last = pageCount - 1;
 	const current = Math.min(Math.max(page, 0), last);
 	const go = (next) => {
 		const target = Math.min(Math.max(next, 0), last);
-		if (target !== current) onPageChange(target);
+		if (target !== current) onPageChange?.(target);
+	};
+	const control = ({ target, label, className: controlClass, disabled, current: isCurrent, children }) => {
+		const ariaCurrent = isCurrent ? "page" : void 0;
+		if (!hrefFor) return /* @__PURE__ */ jsx("button", {
+			type: "button",
+			"aria-label": label,
+			"aria-current": ariaCurrent,
+			disabled,
+			onClick: () => go(target),
+			className: controlClass,
+			children
+		});
+		if (disabled) return /* @__PURE__ */ jsx("span", {
+			role: "link",
+			"aria-label": label,
+			"aria-disabled": "true",
+			className: cn(controlClass, "pointer-events-none"),
+			children
+		});
+		return /* @__PURE__ */ jsx(LinkComponent, {
+			href: hrefFor(target),
+			"aria-label": label,
+			"aria-current": ariaCurrent,
+			onClick: onPageChange ? (event) => {
+				if (!opensElsewhere(event)) go(target);
+			} : void 0,
+			className: controlClass,
+			children
+		});
 	};
 	return /* @__PURE__ */ jsx("nav", {
 		"aria-label": ariaLabel,
@@ -39,22 +72,20 @@ function Pagination({ page, pageCount, onPageChange, siblings = 1, className, "a
 		children: /* @__PURE__ */ jsxs("ul", {
 			className: "flex flex-wrap items-center gap-1",
 			children: [
-				/* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("button", {
-					type: "button",
-					"aria-label": "Previous page",
+				/* @__PURE__ */ jsx("li", { children: control({
+					target: current - 1,
+					label: "Previous page",
 					disabled: current === 0,
-					onClick: () => go(current - 1),
 					className: cn(pageButton, "gap-1 pl-1.5"),
-					children: [/* @__PURE__ */ jsx(ChevronLeft, { "aria-hidden": "true" }), /* @__PURE__ */ jsx("span", {
+					children: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx(ChevronLeft, { "aria-hidden": "true" }), /* @__PURE__ */ jsx("span", {
 						className: "hidden sm:inline",
 						children: "Previous"
-					})]
+					})] })
 				}) }),
-				pageSlots(current, pageCount, siblings).map((slot) => typeof slot === "number" ? /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsx("button", {
-					type: "button",
-					"aria-label": `Page ${slot + 1}`,
-					"aria-current": slot === current ? "page" : void 0,
-					onClick: () => go(slot),
+				pageSlots(current, pageCount, siblings).map((slot) => typeof slot === "number" ? /* @__PURE__ */ jsx("li", { children: control({
+					target: slot,
+					label: `Page ${slot + 1}`,
+					current: slot === current,
 					className: cn(pageButton, slot === current && "border-border bg-card font-semibold text-foreground hover:bg-card"),
 					children: slot + 1
 				}) }, slot) : /* @__PURE__ */ jsx("li", {
@@ -62,16 +93,15 @@ function Pagination({ page, pageCount, onPageChange, siblings = 1, className, "a
 					className: "flex min-w-8 justify-center text-sm text-muted-foreground",
 					children: "…"
 				}, slot)),
-				/* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("button", {
-					type: "button",
-					"aria-label": "Next page",
+				/* @__PURE__ */ jsx("li", { children: control({
+					target: current + 1,
+					label: "Next page",
 					disabled: current === last,
-					onClick: () => go(current + 1),
 					className: cn(pageButton, "gap-1 pr-1.5"),
-					children: [/* @__PURE__ */ jsx("span", {
+					children: /* @__PURE__ */ jsxs(Fragment$1, { children: [/* @__PURE__ */ jsx("span", {
 						className: "hidden sm:inline",
 						children: "Next"
-					}), /* @__PURE__ */ jsx(ChevronRight, { "aria-hidden": "true" })]
+					}), /* @__PURE__ */ jsx(ChevronRight, { "aria-hidden": "true" })] })
 				}) })
 			]
 		})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/ui",
-  "version": "11.23.0",
+  "version": "11.24.0",
   "description": "Generic React UI components for Tangle products — primitives, chat, run, files, editor, markdown.",
   "type": "module",
   "license": "MIT",

package/src/primitives/pagination-alert.stories.tsx

@@ -25,6 +25,41 @@ export const PaginationLengths: StoryObj = {
   ),
 }
 
+/** Keeps the story in place; a real app passes its router's link. */
+function StoryLink({ onClick, ...props }: React.ComponentProps<'a'>) {
+  return (
+    <a
+      {...props}
+      onClick={(event) => {
+        event.preventDefault()
+        onClick?.(event)
+      }}
+    />
+  )
+}
+
+function LinkedTable({ pageCount }: { pageCount: number }) {
+  const [page, setPage] = React.useState(0)
+  return (
+    <Pagination
+      page={page}
+      pageCount={pageCount}
+      hrefFor={(p) => `?page=${p + 1}`}
+      linkComponent={StoryLink}
+      onPageChange={setPage}
+    />
+  )
+}
+
+export const PaginationLinks: StoryObj = {
+  render: () => (
+    <div className="flex flex-col gap-6 bg-background p-6 text-foreground">
+      <LinkedTable pageCount={4} />
+      <LinkedTable pageCount={48} />
+    </div>
+  ),
+}
+
 export const AlertTones: StoryObj = {
   render: () => (
     <div className="flex max-w-xl flex-col gap-3 bg-background p-6 text-foreground">

package/src/primitives/pagination-alert.test.tsx

@@ -1,5 +1,6 @@
 import { render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
+import type * as React from "react";
 import { describe, expect, it, vi } from "vitest";
 import { Alert, AlertDescription, AlertTitle } from "./alert";
 import { Pagination, pageSlots } from "./pagination";
@@ -63,6 +64,95 @@ describe("Pagination", () => {
   });
 });
 
+describe("Pagination link mode", () => {
+  const hrefFor = (page: number) => `?page=${page + 1}`;
+
+  it("renders links to one-based URLs from zero-based pages", () => {
+    render(<Pagination page={4} pageCount={12} hrefFor={hrefFor} />);
+
+    expect(screen.queryByRole("button")).not.toBeInTheDocument();
+    expect(screen.getByRole("link", { name: "Previous page" })).toHaveAttribute("href", "?page=4");
+    expect(screen.getByRole("link", { name: "Next page" })).toHaveAttribute("href", "?page=6");
+    expect(screen.getByRole("link", { name: "Page 1" })).toHaveAttribute("href", "?page=1");
+    expect(screen.getByRole("link", { name: "Page 12" })).toHaveAttribute("href", "?page=12");
+
+    const current = screen.getByRole("link", { name: "Page 5" });
+    expect(current.tagName).toBe("A");
+    expect(current).toHaveAttribute("href", "?page=5");
+    expect(current).toHaveAttribute("aria-current", "page");
+    expect(screen.getByRole("link", { name: "Page 4" })).not.toHaveAttribute("aria-current");
+  });
+
+  it("renders a disabled previous or next as a span without an href", () => {
+    const { rerender } = render(<Pagination page={0} pageCount={3} hrefFor={hrefFor} />);
+    const previous = screen.getByRole("link", { name: "Previous page" });
+    expect(previous.tagName).toBe("SPAN");
+    expect(previous).toHaveAttribute("aria-disabled", "true");
+    expect(previous).not.toHaveAttribute("href");
+    expect(previous.className).toContain("aria-disabled:opacity-50");
+    expect(screen.getByRole("link", { name: "Next page" })).toHaveAttribute("href", "?page=2");
+
+    rerender(<Pagination page={2} pageCount={3} hrefFor={hrefFor} />);
+    const next = screen.getByRole("link", { name: "Next page" });
+    expect(next.tagName).toBe("SPAN");
+    expect(next).toHaveAttribute("aria-disabled", "true");
+    expect(next).not.toHaveAttribute("href");
+  });
+
+  it("renders each enabled control with a custom link component", () => {
+    const received: string[] = [];
+    const RouterLink = ({ href, ...props }: React.ComponentProps<"a">) => {
+      received.push(href ?? "");
+      return <a data-router-link="" href={href} {...props} />;
+    };
+    render(<Pagination page={1} pageCount={3} hrefFor={hrefFor} linkComponent={RouterLink} />);
+
+    expect(received).toEqual(["?page=1", "?page=1", "?page=2", "?page=3", "?page=3"]);
+    const current = screen.getByRole("link", { name: "Page 2" });
+    expect(current).toHaveAttribute("data-router-link");
+    expect(current).toHaveAttribute("aria-current", "page");
+  });
+
+  it("reports a plain click on another page and ignores the current page and new-tab clicks", async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    render(
+      <Pagination
+        page={1}
+        pageCount={3}
+        hrefFor={hrefFor}
+        linkComponent={({ onClick, ...props }: React.ComponentProps<"a">) => (
+          <a
+            {...props}
+            onClick={(event) => {
+              onClick?.(event);
+              event.preventDefault();
+            }}
+          />
+        )}
+        onPageChange={onPageChange}
+      />,
+    );
+
+    await user.click(screen.getByRole("link", { name: "Next page" }));
+    await user.click(screen.getByRole("link", { name: "Page 2" }));
+    await user.keyboard("{Meta>}");
+    await user.click(screen.getByRole("link", { name: "Page 1" }));
+    await user.keyboard("{/Meta}");
+    expect(onPageChange.mock.calls).toEqual([[2]]);
+  });
+
+  it("requires onPageChange or hrefFor, and a link component only with hrefFor", () => {
+    const rejected = [
+      // @ts-expect-error neither onPageChange nor hrefFor
+      () => <Pagination page={0} pageCount={2} />,
+      // @ts-expect-error linkComponent without hrefFor
+      () => <Pagination page={0} pageCount={2} onPageChange={vi.fn()} linkComponent="a" />,
+    ];
+    expect(rejected).toHaveLength(2);
+  });
+});
+
 describe("Alert", () => {
   it("paints a tone from the matched Brand status triple", () => {
     render(

package/src/primitives/pagination.tsx

@@ -3,23 +3,64 @@ import * as React from "react";
 import { cn } from "../lib/utils";
 import { buttonVariants } from "./button";
 
-/**
- * Page controls for a paged list or table: previous, the page numbers around
- * the current one with the first and last always reachable, and next.
- *
- * Pages are zero-based in the API and one-based on screen. With one page or
- * none there is nothing to choose, so it renders nothing.
- */
-export interface PaginationProps
+interface PaginationBaseProps
   extends Omit<React.HTMLAttributes<HTMLElement>, "onChange" | "children"> {
   /** The current page, zero-based. */
   page: number;
   pageCount: number;
-  onPageChange: (page: number) => void;
   /** Pages shown on each side of the current one before an ellipsis. */
   siblings?: number;
 }
 
+export interface PaginationButtonProps extends PaginationBaseProps {
+  onPageChange: (page: number) => void;
+  hrefFor?: never;
+  linkComponent?: never;
+}
+
+export interface PaginationLinkProps extends PaginationBaseProps {
+  /** The URL of a page, given the zero-based page. */
+  hrefFor: (page: number) => string;
+  /** Renders each enabled control. Receives `href`; defaults to `"a"`. */
+  linkComponent?: React.ElementType;
+  /**
+   * Called with the target page when a link to another page is clicked, unless
+   * the click opens it in another tab or window.
+   */
+  onPageChange?: (page: number) => void;
+}
+
+/**
+ * Page controls for a paged list or table: previous, the page numbers around
+ * the current one with the first and last always reachable, and next.
+ *
+ * Pages are zero-based in the API and one-based on screen. With one page or
+ * none there is nothing to choose, so it renders nothing.
+ *
+ * Give `onPageChange` to render buttons, or `hrefFor` to render links for a
+ * list paged by URL. In link mode each enabled control is rendered by
+ * `linkComponent` (an `<a>` by default) with `href`, `className`,
+ * `aria-label`, `aria-current` and children; a disabled previous or next is a
+ * `<span aria-disabled="true">` with no `href`. A router whose link takes `to`
+ * instead of `href` needs a small adapter:
+ *
+ * ```tsx
+ * import { Link } from "react-router";
+ *
+ * const RouterLink = ({ href, ...props }: React.ComponentProps<"a">) => (
+ *   <Link to={href ?? ""} {...props} />
+ * );
+ *
+ * <Pagination
+ *   page={page}
+ *   pageCount={pageCount}
+ *   hrefFor={(p) => `?page=${p + 1}`}
+ *   linkComponent={RouterLink}
+ * />
+ * ```
+ */
+export type PaginationProps = PaginationButtonProps | PaginationLinkProps;
+
 type PageSlot = number | "gap-start" | "gap-end";
 
 /**
@@ -43,10 +84,26 @@ export function pageSlots(page: number, pageCount: number, siblings = 1): PageSl
 
 const pageButton = cn(buttonVariants({ variant: "ghost", size: "sm" }), "min-w-8 px-2 tabular-nums");
 
+/** A click that opens the link in another tab or window leaves this page where it is. */
+function opensElsewhere(event: React.MouseEvent) {
+  return event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey;
+}
+
+interface ControlProps {
+  target: number;
+  label: string;
+  className: string;
+  disabled?: boolean;
+  current?: boolean;
+  children: React.ReactNode;
+}
+
 export function Pagination({
   page,
   pageCount,
   onPageChange,
+  hrefFor,
+  linkComponent: LinkComponent = "a",
   siblings = 1,
   className,
   "aria-label": ariaLabel = "Pagination",
@@ -58,40 +115,82 @@ export function Pagination({
   const current = Math.min(Math.max(page, 0), last);
   const go = (next: number) => {
     const target = Math.min(Math.max(next, 0), last);
-    if (target !== current) onPageChange(target);
+    if (target !== current) onPageChange?.(target);
+  };
+
+  const control = ({ target, label, className: controlClass, disabled, current: isCurrent, children }: ControlProps) => {
+    const ariaCurrent = isCurrent ? ("page" as const) : undefined;
+    if (!hrefFor) {
+      return (
+        <button
+          type="button"
+          aria-label={label}
+          aria-current={ariaCurrent}
+          disabled={disabled}
+          onClick={() => go(target)}
+          className={controlClass}
+        >
+          {children}
+        </button>
+      );
+    }
+    if (disabled) {
+      return (
+        <span role="link" aria-label={label} aria-disabled="true" className={cn(controlClass, "pointer-events-none")}>
+          {children}
+        </span>
+      );
+    }
+    return (
+      <LinkComponent
+        href={hrefFor(target)}
+        aria-label={label}
+        aria-current={ariaCurrent}
+        onClick={
+          onPageChange
+            ? (event: React.MouseEvent) => {
+                if (!opensElsewhere(event)) go(target);
+              }
+            : undefined
+        }
+        className={controlClass}
+      >
+        {children}
+      </LinkComponent>
+    );
   };
 
   return (
     <nav aria-label={ariaLabel} className={cn("flex items-center", className)} {...rest}>
       <ul className="flex flex-wrap items-center gap-1">
         <li>
-          <button
-            type="button"
-            aria-label="Previous page"
-            disabled={current === 0}
-            onClick={() => go(current - 1)}
-            className={cn(pageButton, "gap-1 pl-1.5")}
-          >
-            <ChevronLeft aria-hidden="true" />
-            <span className="hidden sm:inline">Previous</span>
-          </button>
+          {control({
+            target: current - 1,
+            label: "Previous page",
+            disabled: current === 0,
+            className: cn(pageButton, "gap-1 pl-1.5"),
+            children: (
+              <>
+                <ChevronLeft aria-hidden="true" />
+                <span className="hidden sm:inline">Previous</span>
+              </>
+            ),
+          })}
         </li>
         {pageSlots(current, pageCount, siblings).map((slot) =>
           typeof slot === "number" ? (
             <li key={slot}>
-              <button
-                type="button"
-                aria-label={`Page ${slot + 1}`}
-                aria-current={slot === current ? "page" : undefined}
-                onClick={() => go(slot)}
-                className={cn(
+              {control({
+                target: slot,
+                label: `Page ${slot + 1}`,
+                current: slot === current,
+                className: cn(
                   pageButton,
                   slot === current &&
                     "border-border bg-card font-semibold text-foreground hover:bg-card",
-                )}
-              >
-                {slot + 1}
-              </button>
+                ),
+                children: slot + 1,
+              })}
             </li>
           ) : (
             <li key={slot} aria-hidden="true" className="flex min-w-8 justify-center text-sm text-muted-foreground">
@@ -100,16 +199,18 @@ export function Pagination({
           ),
         )}
         <li>
-          <button
-            type="button"
-            aria-label="Next page"
-            disabled={current === last}
-            onClick={() => go(current + 1)}
-            className={cn(pageButton, "gap-1 pr-1.5")}
-          >
-            <span className="hidden sm:inline">Next</span>
-            <ChevronRight aria-hidden="true" />
-          </button>
+          {control({
+            target: current + 1,
+            label: "Next page",
+            disabled: current === last,
+            className: cn(pageButton, "gap-1 pr-1.5"),
+            children: (
+              <>
+                <span className="hidden sm:inline">Next</span>
+                <ChevronRight aria-hidden="true" />
+              </>
+            ),
+          })}
         </li>
       </ul>
     </nav>