@tangle-network/ui 11.22.3 → 11.24.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @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
+
+- 57f4e3d: `Tag` takes `wrap` to break a long label across lines instead of truncating it, for text that must be read in full without a hover (model-written part names on a phone or on paper).
+
 ## 11.22.3
 
 ### Patch 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/dist/primitives/tag.d.ts

@@ -30,6 +30,12 @@ export interface TagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "c
    * the label is a string; pass it when the label is not plain text.
    */
   removeLabel?: string;
+  /**
+   * Wraps a long label onto more lines instead of truncating it. Use it where
+   * the full text matters and no hover is available to read a `title`, such
+   * as model-written part names read on a phone or on paper.
+   */
+  wrap?: boolean;
 }
 declare const Tag: React.ForwardRefExoticComponent<TagProps & React.RefAttributes<HTMLSpanElement>>;
 //#endregion

package/dist/primitives/tag.js

@@ -6,23 +6,38 @@ import { jsx, jsxs } from "react/jsx-runtime";
 import { X } from "lucide-react";
 //#region src/primitives/tag.tsx
 const SIZE = {
-	sm: "h-6 gap-1 px-2 text-xs [&_svg]:size-3",
-	md: "h-7 gap-1.5 px-2.5 text-sm [&_svg]:size-3.5"
+	sm: "gap-1 px-2 text-xs [&_svg]:size-3",
+	md: "gap-1.5 px-2.5 text-sm [&_svg]:size-3.5"
 };
-const Tag = React.forwardRef(({ className, children, tone = "neutral", emphasis = "soft", size = "sm", icon, onRemove, removeLabel, ...props }, ref) => {
+const WRAP = {
+	sm: {
+		box: "items-start",
+		label: "py-[3px]",
+		icon: "h-[22px] items-center"
+	},
+	md: {
+		box: "items-start",
+		label: "py-[3px]",
+		icon: "h-[26px] items-center"
+	}
+};
+const Tag = React.forwardRef(({ className, children, tone = "neutral", emphasis = "soft", size = "sm", icon, onRemove, removeLabel, wrap = false, ...props }, ref) => {
 	const classes = TONE_CLASSES[tone];
 	const label = removeLabel ?? (typeof children === "string" ? `Remove ${children}` : "Remove");
 	return /* @__PURE__ */ jsxs("span", {
 		ref,
-		className: cn("inline-flex min-w-0 max-w-full shrink-0 items-center rounded-md border font-medium", SIZE[size], emphasis === "outline" ? classes.outline : classes.surface, onRemove && (size === "sm" ? "pr-0.5" : "pr-1"), className),
+		className: cn("inline-flex min-w-0 max-w-full shrink-0 rounded-md border font-medium", SIZE[size], wrap ? WRAP[size].box : ["items-center", size === "sm" ? "h-6" : "h-7"], emphasis === "outline" ? classes.outline : classes.surface, onRemove && (size === "sm" ? "pr-0.5" : "pr-1"), className),
 		...props,
 		children: [
 			icon ? /* @__PURE__ */ jsx("span", {
 				"aria-hidden": "true",
-				className: cn("inline-flex shrink-0", classes.icon),
+				className: cn("inline-flex shrink-0", wrap && WRAP[size].icon, classes.icon),
 				children: icon
 			}) : null,
-			/* @__PURE__ */ jsx("span", {
+			wrap ? /* @__PURE__ */ jsx("span", {
+				className: cn("min-w-0 [overflow-wrap:anywhere]", WRAP[size].label),
+				children
+			}) : /* @__PURE__ */ jsx("span", {
 				className: "min-w-0 truncate",
 				title: typeof children === "string" ? children : void 0,
 				children
@@ -31,7 +46,7 @@ const Tag = React.forwardRef(({ className, children, tone = "neutral", emphasis
 				type: "button",
 				"aria-label": label,
 				onClick: onRemove,
-				className: cn("relative inline-flex shrink-0 items-center justify-center rounded-sm opacity-70 transition-[opacity,background-color] duration-150 ease-out hover:bg-[color-mix(in_srgb,currentColor_14%,transparent)] hover:opacity-100 before:absolute before:-inset-1.5 before:content-['']", size === "sm" ? "size-5" : "size-6", focusRing),
+				className: cn("relative inline-flex shrink-0 items-center justify-center rounded-sm opacity-70 transition-[opacity,background-color] duration-150 ease-out hover:bg-[color-mix(in_srgb,currentColor_14%,transparent)] hover:opacity-100 before:absolute before:-inset-1.5 before:content-['']", size === "sm" ? "size-5" : "size-6", wrap && "mt-px", focusRing),
 				children: /* @__PURE__ */ jsx(X, { "aria-hidden": "true" })
 			}) : null
 		]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/ui",
-  "version": "11.22.3",
+  "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/chip.test.tsx

@@ -124,6 +124,28 @@ describe("Tag", () => {
   });
 });
 
+describe("Tag wrap", () => {
+  const LONG = "Adafruit-BME680-Temperature-Humidity-Pressure-Gas-Sensor-Breakout";
+
+  it("truncates a long label by default and names it in a title", () => {
+    render(<Tag>{LONG}</Tag>);
+    const label = screen.getByText(LONG);
+    expect(label.className).toContain("truncate");
+    expect(label.getAttribute("title")).toBe(LONG);
+    expect(label.parentElement?.className).toContain("h-6");
+  });
+
+  it("wraps a long label across lines when asked, aligned to its first line", () => {
+    render(<Tag wrap size="md">{LONG}</Tag>);
+    const label = screen.getByText(LONG);
+    expect(label.className).not.toContain("truncate");
+    expect(label.className).toContain("[overflow-wrap:anywhere]");
+    expect(label.className).toContain("py-[3px]");
+    expect(label.parentElement?.className).toContain("items-start");
+    expect(label.parentElement?.className).not.toMatch(/(^|\s)h-7(\s|$)/);
+  });
+});
+
 describe("IconTile", () => {
   it("falls back from a broken image to the glyph, then to initials", () => {
     const { container, rerender } = render(<IconTile src="https://example.invalid/logo.png" name="Acme Robotics" />);

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>

package/src/primitives/tag-chip.stories.tsx

@@ -224,3 +224,27 @@ export const WorstCase: Story = {
     </BothThemes>
   ),
 };
+
+const PART = "Adafruit-BME680-Temperature-Humidity-Pressure-Gas-Sensor-Breakout";
+
+/** `wrap` keeps the whole label readable: one line matches a fixed tag's height; more lines grow it, with the icon and remove button on the first line. */
+export const Wrap: Story = {
+  render: () => (
+    <BothThemes>
+      <div className="flex w-full max-w-[220px] flex-col items-start gap-2" data-testid="wrap-column">
+        {(["sm", "md"] as const).map((size) => (
+          <div key={size} className="flex flex-col items-start gap-2">
+            <div className="flex items-start gap-2">
+              <Tag size={size} data-probe={`fixed-${size}`}>Short</Tag>
+              <Tag size={size} wrap data-probe={`wrap-one-${size}`}>Short</Tag>
+              <Tag size={size} wrap onRemove={() => {}} data-probe={`wrap-remove-${size}`}>Short</Tag>
+            </div>
+            <Tag size={size} wrap tone="teal" icon={<FileText />} onRemove={() => {}} data-probe={`wrap-long-${size}`}>
+              {PART}
+            </Tag>
+          </div>
+        ))}
+      </div>
+    </BothThemes>
+  ),
+};

package/src/primitives/tag.tsx

@@ -33,16 +33,31 @@ export interface TagProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, "c
    * the label is a string; pass it when the label is not plain text.
    */
   removeLabel?: string;
+  /**
+   * Wraps a long label onto more lines instead of truncating it. Use it where
+   * the full text matters and no hover is available to read a `title`, such
+   * as model-written part names read on a phone or on paper.
+   */
+  wrap?: boolean;
 }
 
 const SIZE = {
-  sm: "h-6 gap-1 px-2 text-xs [&_svg]:size-3",
-  md: "h-7 gap-1.5 px-2.5 text-sm [&_svg]:size-3.5",
+  sm: "gap-1 px-2 text-xs [&_svg]:size-3",
+  md: "gap-1.5 px-2.5 text-sm [&_svg]:size-3.5",
+} as const;
+
+// A truncating tag has one fixed height. A wrapping tag carries its vertical
+// padding on the label instead, sized so one line is exactly that height
+// (sm: 16px line + 6 + 2px border = 24; md: 20 + 6 + 2 = 28), and aligns the
+// icon and remove button to the first line rather than the middle.
+const WRAP = {
+  sm: { box: "items-start", label: "py-[3px]", icon: "h-[22px] items-center" },
+  md: { box: "items-start", label: "py-[3px]", icon: "h-[26px] items-center" },
 } as const;
 
 const Tag = React.forwardRef<HTMLSpanElement, TagProps>(
   (
-    { className, children, tone = "neutral", emphasis = "soft", size = "sm", icon, onRemove, removeLabel, ...props },
+    { className, children, tone = "neutral", emphasis = "soft", size = "sm", icon, onRemove, removeLabel, wrap = false, ...props },
     ref,
   ) => {
     const classes = TONE_CLASSES[tone];
@@ -51,8 +66,9 @@ const Tag = React.forwardRef<HTMLSpanElement, TagProps>(
       <span
         ref={ref}
         className={cn(
-          "inline-flex min-w-0 max-w-full shrink-0 items-center rounded-md border font-medium",
+          "inline-flex min-w-0 max-w-full shrink-0 rounded-md border font-medium",
           SIZE[size],
+          wrap ? WRAP[size].box : ["items-center", size === "sm" ? "h-6" : "h-7"],
           emphasis === "outline" ? classes.outline : classes.surface,
           onRemove && (size === "sm" ? "pr-0.5" : "pr-1"),
           className,
@@ -60,15 +76,20 @@ const Tag = React.forwardRef<HTMLSpanElement, TagProps>(
         {...props}
       >
         {icon ? (
-          <span aria-hidden="true" className={cn("inline-flex shrink-0", classes.icon)}>
+          <span aria-hidden="true" className={cn("inline-flex shrink-0", wrap && WRAP[size].icon, classes.icon)}>
             {icon}
           </span>
         ) : null}
-        {/* A long label truncates here rather than pushing the remove button
-            out; the title gives its full text on hover. */}
-        <span className="min-w-0 truncate" title={typeof children === "string" ? children : undefined}>
-          {children}
-        </span>
+        {/* By default a long label truncates here rather than pushing the
+            remove button out, and the title gives its full text on hover.
+            `wrap` breaks it across lines instead, even inside one long token. */}
+        {wrap ? (
+          <span className={cn("min-w-0 [overflow-wrap:anywhere]", WRAP[size].label)}>{children}</span>
+        ) : (
+          <span className="min-w-0 truncate" title={typeof children === "string" ? children : undefined}>
+            {children}
+          </span>
+        )}
         {onRemove ? (
           <button
             type="button"
@@ -79,6 +100,8 @@ const Tag = React.forwardRef<HTMLSpanElement, TagProps>(
               // the hit area without moving the tag's layout.
               "relative inline-flex shrink-0 items-center justify-center rounded-sm opacity-70 transition-[opacity,background-color] duration-150 ease-out hover:bg-[color-mix(in_srgb,currentColor_14%,transparent)] hover:opacity-100 before:absolute before:-inset-1.5 before:content-['']",
               size === "sm" ? "size-5" : "size-6",
+              // Centred on the first line box (22px sm, 26px md) when wrapping.
+              wrap && "mt-px",
               focusRing,
             )}
           >