rift-ds 1.11.0 → 1.12.0

package/behaviors/LinkProvider.d.ts

@@ -0,0 +1,36 @@
+import { default as React } from 'react';
+/**
+ * The props a link component receives: every anchor attribute, the ref, and
+ * an `href` that is always a string. Next.js's `Link` takes these as they
+ * are; a router whose link takes `to` instead needs a one-line adapter:
+ * `({ href, ...props }) => <RouterLink to={href} {...props} />`.
+ */
+export type LinkComponentProps = React.ComponentPropsWithRef<'a'> & {
+    href: string;
+};
+/** A component that renders a link in place of a plain `<a>`, such as a router's. */
+export type LinkComponent = React.ElementType<LinkComponentProps>;
+export interface LinkProviderProps {
+    /**
+     * The link component every rift-ds link under this provider renders, such
+     * as Next.js's `Link`. Named like the instance prop it stands in for.
+     */
+    linkComponent: LinkComponent;
+    /** The part of the app whose links it applies to, usually the whole app. */
+    children?: React.ReactNode;
+}
+/**
+ * Sets the link component for every client-rendered rift-ds component below
+ * it that takes an `href`, so their links navigate through the app's router
+ * instead of reloading the page. A component's own `linkComponent` prop
+ * wins over it. The link components that can render on the server cannot
+ * read a provider and take the prop alone (design.md's Components intro
+ * names them, and scripts/validate-component-contract.mjs keeps them off
+ * the provider).
+ */
+export declare function LinkProvider({ linkComponent, children }: LinkProviderProps): React.JSX.Element;
+/**
+ * The link component to render: the component's own `linkComponent` prop,
+ * else the nearest LinkProvider's, else a plain `<a>`.
+ */
+export declare function useLinkComponent(override?: LinkComponent): LinkComponent;

package/behaviors/LinkProvider.js

@@ -0,0 +1,15 @@
+"use client";
+import { jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const LinkContext = createContext(null);
+function LinkProvider({ linkComponent, children }) {
+  return /* @__PURE__ */ jsx(LinkContext.Provider, { value: linkComponent, children });
+}
+function useLinkComponent(override) {
+  const provided = useContext(LinkContext);
+  return override ?? provided ?? "a";
+}
+export {
+  LinkProvider,
+  useLinkComponent
+};

package/chat/ChatProvider.d.ts

@@ -36,7 +36,11 @@ export interface ChatProviderProps {
     renderers?: ChatCardRenderers;
     /** Draws an artifact's preview by kind, for artifacts that are live React content rather than a document or a URL. */
     artifactRenderers?: ChatArtifactRenderers;
-    /** Renders a same-site link in an answer. The default is a plain anchor; a Next.js host passes its Link. */
+    /**
+     * Renders a same-site link in an answer. The default renders through the
+     * nearest LinkProvider's link component, else a plain anchor; passing
+     * this wins over both.
+     */
     renderLink?: ChatLinkRenderer;
     /** Which hrefs in an answer become links. Everything else renders as text. */
     isInternalHref?: (href: string) => boolean;

package/chat/ChatProvider.js

@@ -7,7 +7,17 @@ import { createFollowupsFetcher, followupTarget, DEFAULT_FALLBACK_FOLLOWUPS, pic
 import { useThreads } from "./threads.js";
 import { createFetchTransport } from "./transport.js";
 import { DEFAULT_PLACEHOLDER_COPY, useChat } from "./useChat.js";
-const defaultRenderLink = ({ href, children, onNavigate }) => /* @__PURE__ */ jsx("a", { href, onClick: onNavigate, children });
+import { useLinkComponent } from "../behaviors/LinkProvider.js";
+function DefaultChatLink({ href, children, onNavigate }) {
+  const Link = useLinkComponent();
+  return (
+    // The hook returns a stable reference from context (or 'a'), never a
+    // component created here, which is what the rule guards against.
+    // eslint-disable-next-line react-hooks/static-components
+    /* @__PURE__ */ jsx(Link, { href, onClick: onNavigate, children })
+  );
+}
+const defaultRenderLink = (props) => /* @__PURE__ */ jsx(DefaultChatLink, { ...props });
 function ChatProvider({
   transport,
   endpoint = "/api/chat",

package/components/AiButton/AiButton.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 import { PromptSuggestion } from '../PromptSuggestions/PromptSuggestions';
 /** The content of AiButton's summary panel. */
 export interface AiButtonSummary {
@@ -59,6 +60,12 @@ type AiButtonOwnProps = {
     suggestionsLabel?: string;
     /** Additional CSS classes */
     className?: string;
+    /**
+     * The component the link renders with, such as Next.js's `Link`, so it
+     * navigates through the app's router. Wins over a LinkProvider's; a plain
+     * `<a>` when neither is set.
+     */
+    linkComponent?: LinkComponent;
 };
 export interface AiButtonProps extends AiButtonOwnProps, Omit<React.ComponentPropsWithoutRef<'button'>, keyof AiButtonOwnProps | 'type'> {
 }

package/components/AiButton/AiButton.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import React, { useState, useRef, useEffect } from "react";
+import { useLinkComponent } from "../../behaviors/LinkProvider.js";
 import { PromptSuggestions } from "../PromptSuggestions/PromptSuggestions.js";
 import { Skeleton } from "../Skeleton/Skeleton.js";
 import { StreamingText } from "../StreamingText/StreamingText.js";
@@ -25,9 +26,11 @@ const AiButton = React.forwardRef(
     dismissLabel = "Dismiss summary",
     suggestionsLabel = "Suggested prompts",
     className = "",
+    linkComponent,
     ...rest
   }, ref) => {
     const baseClass = "ds-ai-button";
+    const Link = useLinkComponent(linkComponent);
     const [hoverOpen, setHoverOpen] = useState(false);
     const [dismissed, setDismissed] = useState(false);
     const [phase, setPhase] = useState("skeleton");
@@ -91,7 +94,7 @@ const AiButton = React.forwardRef(
       /* @__PURE__ */ jsx("span", { className: `${baseClass}__text`, children: label })
     ] });
     const control = href && !disabled ? /* @__PURE__ */ jsx(
-      "a",
+      Link,
       {
         ...rest,
         ref,

package/components/AppLayout/AppLayout.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
 import { AppSidebarSection, AppSidebarProfile } from '../AppSidebar/AppSidebar';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 /** Props owned by AppLayout itself — everything else falls through to the outer wrapper `<div>`. */
 type AppLayoutOwnProps = {
     /** Sidebar navigation sections */
@@ -28,6 +29,12 @@ type AppLayoutOwnProps = {
      * follows the surrounding data-theme like any other component.
      */
     theme?: 'dark' | 'inherit';
+    /**
+     * The component its links render with, such as Next.js's `Link`, so they
+     * navigate through the app's router; passed on to the AppSidebar rail. Wins over a
+     * LinkProvider's; a plain `<a>` when neither is set.
+     */
+    linkComponent?: LinkComponent;
     /** Additional CSS classes on outer wrapper */
     className?: string;
 };

package/components/AppLayout/AppLayout.js

@@ -16,6 +16,7 @@ const AppLayout = React.forwardRef(
     logo,
     children,
     theme = "dark",
+    linkComponent,
     className = "",
     ...rest
   }, ref) => {
@@ -49,7 +50,8 @@ const AppLayout = React.forwardRef(
               expanded,
               onExpandedChange: handleExpandedChange,
               logoText,
-              logo
+              logo,
+              linkComponent
             }
           ),
           /* @__PURE__ */ jsx("main", { className: `${baseClass}__main`, children: /* @__PURE__ */ jsx("div", { className: `${baseClass}__content`, children }) })

package/components/AppSidebar/AppSidebar.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 export interface AppSidebarSubItem {
     /** Unique key for this sub-item */
     key: string;
@@ -108,6 +109,12 @@ type AppSidebarOwnProps = {
     footerSlot?: React.ReactNode;
     /** Additional CSS classes */
     className?: string;
+    /**
+     * The component its links render with, such as Next.js's `Link`, so they
+     * navigate through the app's router. Wins over a LinkProvider's; a plain
+     * `<a>` when neither is set.
+     */
+    linkComponent?: LinkComponent;
     /** Logo element — defaults to the built-in brand mark */
     logo?: React.ReactNode;
     /** Text shown next to logo when expanded */

package/components/AppSidebar/AppSidebar.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsxs, Fragment, jsx } from "react/jsx-runtime";
 import React, { useState, useRef, useEffect, useCallback, useId } from "react";
+import { useLinkComponent } from "../../behaviors/LinkProvider.js";
 import { useLayer } from "../../behaviors/useLayer.js";
 import { useFocusScope } from "../../behaviors/useFocusScope.js";
 import { useScrollLock } from "../../behaviors/useScrollLock.js";
@@ -56,9 +57,11 @@ const AppSidebar = React.forwardRef(function AppSidebar2({
   collapseLabel = "Collapse sidebar",
   profileMoreLabel = "Profile options",
   menuLabel = "Menu",
+  linkComponent,
   ...rest
 }, ref) {
   const baseClass = "ds-app-sidebar";
+  const Link = useLinkComponent(linkComponent);
   const avatarSeed = (item) => typeof item.pixelAvatar === "string" ? item.pixelAvatar : item.label;
   const avatarItems = sections.flatMap(
     (section) => section.items.filter((item) => item.pixelAvatar)
@@ -279,6 +282,7 @@ const AppSidebar = React.forwardRef(function AppSidebar2({
         mobileOpen && drilled && panelSource ? /* @__PURE__ */ jsx(
           SidebarPanel,
           {
+            linkComponent: Link,
             className: `${baseClass}__drill`,
             items: panelSource.items,
             title: panelSource.label,
@@ -327,8 +331,8 @@ const AppSidebar = React.forwardRef(function AppSidebar2({
               )
             ] });
             return /* @__PURE__ */ jsxs(React.Fragment, { children: [
-              isLink ? /* @__PURE__ */ jsx(
-                "a",
+              isLink && item.href ? /* @__PURE__ */ jsx(
+                Link,
                 {
                   className: itemClasses,
                   href: item.href,
@@ -408,7 +412,7 @@ const AppSidebar = React.forwardRef(function AppSidebar2({
                           children: subLabel
                         }
                       ) : sub.href ? /* @__PURE__ */ jsx(
-                        "a",
+                        Link,
                         {
                           className: subClasses,
                           href: sub.href,
@@ -467,6 +471,7 @@ const AppSidebar = React.forwardRef(function AppSidebar2({
     panelSource && !mobileOpen && /* @__PURE__ */ jsx(
       SidebarPanel,
       {
+        linkComponent: Link,
         id: panelId,
         className: [
           `${baseClass}__panel`,

package/components/BottomNav/BottomNav.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 export interface BottomNavItem {
     /** Unique key for this destination */
     key: string;
@@ -67,6 +68,12 @@ type BottomNavOwnProps = {
     badgeLabel?: (badge: number | string | true) => string;
     /** Additional CSS classes */
     className?: string;
+    /**
+     * The component its links render with, such as Next.js's `Link`, so they
+     * navigate through the app's router. Wins over a LinkProvider's; a plain
+     * `<a>` when neither is set.
+     */
+    linkComponent?: LinkComponent;
 };
 export interface BottomNavProps extends BottomNavOwnProps, Omit<React.ComponentPropsWithoutRef<'nav'>, keyof BottomNavOwnProps> {
 }

package/components/BottomNav/BottomNav.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsxs, jsx, Fragment } from "react/jsx-runtime";
 import React from "react";
+import { useLinkComponent } from "../../behaviors/LinkProvider.js";
 import "./BottomNav.css";
 import "../../fonts/material-symbols.css";
 const defaultBadgeLabel = (badge) => badge === true ? ", new" : `, ${badge} new`;
@@ -17,9 +18,11 @@ const BottomNav = React.forwardRef(
     badgeLabel = defaultBadgeLabel,
     className = "",
     style,
+    linkComponent,
     ...rest
   }, ref) => {
     const baseClass = "ds-bottom-nav";
+    const Link = useLinkComponent(linkComponent);
     const isIos = platform === "ios";
     const destinations = search && !isIos ? [...items, { key: "__search", label: search.label, icon: search.icon ?? "search", href: search.href, onClick: search.onClick }] : items;
     const activeIndex = destinations.findIndex((item) => item.key === activeKey);
@@ -69,7 +72,7 @@ const BottomNav = React.forwardRef(
               className: `${baseClass}__slot`,
               inert: isMinimized && !isActive,
               children: item.href ? /* @__PURE__ */ jsx(
-                "a",
+                Link,
                 {
                   className: itemClasses,
                   href: item.href,
@@ -92,7 +95,7 @@ const BottomNav = React.forwardRef(
           );
         }) })
       ] }),
-      isIos && search && (search.href ? /* @__PURE__ */ jsx("a", { className: `${baseClass}__search`, href: search.href, onClick: search.onClick, "aria-label": search.label, children: renderIcon(search.icon ?? "search") }) : /* @__PURE__ */ jsx("button", { type: "button", className: `${baseClass}__search`, onClick: search.onClick, "aria-label": search.label, children: renderIcon(search.icon ?? "search") }))
+      isIos && search && (search.href ? /* @__PURE__ */ jsx(Link, { className: `${baseClass}__search`, href: search.href, onClick: search.onClick, "aria-label": search.label, children: renderIcon(search.icon ?? "search") }) : /* @__PURE__ */ jsx("button", { type: "button", className: `${baseClass}__search`, onClick: search.onClick, "aria-label": search.label, children: renderIcon(search.icon ?? "search") }))
     ] });
   }
 );

package/components/Breadcrumb/Breadcrumb.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 export interface BreadcrumbItem {
     /** Display label */
     label: string;
@@ -19,6 +20,13 @@ type BreadcrumbOwnProps = {
      * @deprecated Pass the native `aria-label` attribute instead.
      */
     ariaLabel?: string;
+    /**
+     * The component its links render with, such as Next.js's `Link`, so they
+     * navigate through the app's router; a plain `<a>` when unset. This
+     * component can render on the server, so it never reads a LinkProvider:
+     * pass the prop even under one.
+     */
+    linkComponent?: LinkComponent;
 };
 export interface BreadcrumbProps extends BreadcrumbOwnProps, Omit<React.ComponentPropsWithoutRef<'nav'>, keyof BreadcrumbOwnProps | 'children'> {
 }

package/components/Breadcrumb/Breadcrumb.js

@@ -3,8 +3,9 @@ import React from "react";
 import "./Breadcrumb.css";
 import "../../fonts/material-symbols.css";
 const Breadcrumb = React.forwardRef(
-  ({ items, maxItems, className = "", ariaLabel, ...rest }, ref) => {
+  ({ items, maxItems, className = "", ariaLabel, linkComponent, ...rest }, ref) => {
     const baseClass = "ds-breadcrumb";
+    const Link = linkComponent ?? "a";
     const classes = [baseClass, className].filter(Boolean).join(" ");
     const shouldCollapse = maxItems !== void 0 && maxItems >= 2 && items.length > maxItems;
     let visibleItems;
@@ -28,7 +29,7 @@ const Breadcrumb = React.forwardRef(
       }
       return /* @__PURE__ */ jsxs("li", { className: `${baseClass}__item`, children: [
         index > 0 && /* @__PURE__ */ jsx("span", { className: `${baseClass}__separator material-symbols-rounded`, "aria-hidden": "true", children: "chevron_right" }),
-        isLast || !item.href ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__current`, "aria-current": "page", children: item.label }) : /* @__PURE__ */ jsx("a", { href: item.href, className: `${baseClass}__link`, children: item.label })
+        isLast || !item.href ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__current`, "aria-current": "page", children: item.label }) : /* @__PURE__ */ jsx(Link, { href: item.href, className: `${baseClass}__link`, children: item.label })
       ] }, index);
     }) }) });
   }

package/components/Button/Button.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 /** Props owned by Button itself — everything else falls through to the DOM node. */
 type ButtonOwnProps = {
     /** Button text content */
@@ -39,6 +40,12 @@ type ButtonOwnProps = {
     target?: string;
     /** Optional rel attribute for links */
     rel?: string;
+    /**
+     * The component the link renders with, such as Next.js's `Link`, so it
+     * navigates through the app's router. Wins over a LinkProvider's; a plain
+     * `<a>` when neither is set.
+     */
+    linkComponent?: LinkComponent;
     /** Marks this link as the current page (adds aria-current="page") */
     ariaCurrent?: boolean;
     /** Additional CSS classes */

package/components/Button/Button.js

@@ -2,6 +2,7 @@
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import React from "react";
 import { Spinner } from "../Spinner/Spinner.js";
+import { useLinkComponent } from "../../behaviors/LinkProvider.js";
 import "./Button.css";
 import "../../fonts/material-symbols.css";
 const LEGACY_VARIANTS = {
@@ -33,6 +34,7 @@ const Button = React.forwardRef(
     href,
     target,
     rel,
+    linkComponent,
     ariaCurrent,
     className = "",
     priority,
@@ -42,6 +44,7 @@ const Button = React.forwardRef(
     ...rest
   }, ref) => {
     const baseClass = "ds-button";
+    const Link = useLinkComponent(linkComponent);
     const resolvedVariant = resolveButtonCell(variant ?? priority ?? "primary", tone);
     const isDisabled = disabled ?? state === "disabled";
     const resolvedState = state ?? (isDisabled ? "disabled" : "default");
@@ -73,7 +76,7 @@ const Button = React.forwardRef(
     ] });
     if (href && !isDisabled && !isLoading) {
       return /* @__PURE__ */ jsx(
-        "a",
+        Link,
         {
           ...rest,
           ref,

package/components/Card/Card.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 /** Props owned by Card itself — everything else falls through to the DOM node. */
 type CardOwnProps = {
     /** Card variant */
@@ -34,6 +35,12 @@ type CardOwnProps = {
     dek?: string;
     /** Render as a disabled placeholder (no href, dimmed, not interactive) */
     placeholder?: boolean;
+    /**
+     * The component the link renders with, such as Next.js's `Link`, so it
+     * navigates through the app's router. Wins over a LinkProvider's; a plain
+     * `<a>` when neither is set.
+     */
+    linkComponent?: LinkComponent;
 };
 export interface CardProps extends CardOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof CardOwnProps> {
 }

package/components/Card/Card.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import React from "react";
+import { useLinkComponent } from "../../behaviors/LinkProvider.js";
 import "./Card.css";
 import "../../fonts/material-symbols.css";
 const Card = React.forwardRef(
@@ -20,8 +21,10 @@ const Card = React.forwardRef(
     companyName,
     dek,
     placeholder = false,
+    linkComponent,
     ...rest
   }, ref) => {
+    const Link = useLinkComponent(linkComponent);
     if (variant === "case-study") {
       const inner = /* @__PURE__ */ jsxs(Fragment, { children: [
         /* @__PURE__ */ jsx("div", { className: "ds-card--case-study__cover-wrap", children: cover ? /* @__PURE__ */ jsx("div", { className: "ds-card--case-study__cover-slot", children: cover }) : coverSrc ? /* @__PURE__ */ jsx(
@@ -67,7 +70,7 @@ const Card = React.forwardRef(
         );
       }
       return /* @__PURE__ */ jsx(
-        "a",
+        Link,
         {
           ...rest,
           ref,

package/components/CircularButton/CircularButton.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 /** Props owned by CircularButton itself — everything else falls through to the DOM node. */
 type CircularButtonOwnProps = {
     /** The icon — Material Symbol name (string) or custom element (ReactNode) */
@@ -65,6 +66,13 @@ type CircularButtonOwnProps = {
     rel?: string;
     /** Additional CSS classes */
     className?: string;
+    /**
+     * The component the link renders with, such as Next.js's `Link`, so it
+     * navigates through the app's router; a plain `<a>` when unset. This
+     * component can render on the server, so it never reads a LinkProvider:
+     * pass the prop even under one.
+     */
+    linkComponent?: LinkComponent;
 };
 export interface CircularButtonProps extends CircularButtonOwnProps, Omit<React.ComponentPropsWithoutRef<'button'>, keyof CircularButtonOwnProps | 'type'> {
 }

package/components/CircularButton/CircularButton.js

@@ -32,9 +32,11 @@ const CircularButton = React.forwardRef(
     target,
     rel,
     className = "",
+    linkComponent,
     ...rest
   }, ref) => {
     const baseClass = "ds-circular-button";
+    const Link = linkComponent ?? "a";
     const resolvedVariant = resolveCircularButtonCell(variant ?? priority ?? "primary", tone);
     const isDisabled = disabled ?? state === "disabled";
     const resolvedState = state ?? (isDisabled ? "disabled" : "default");
@@ -49,7 +51,7 @@ const CircularButton = React.forwardRef(
     ].filter(Boolean).join(" ");
     const children = isLoading ? /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon`, "aria-hidden": "true", children: /* @__PURE__ */ jsx(Spinner, { size: size === "compact" ? "sm" : "md", tone: "inherit" }) }) : /* @__PURE__ */ jsx("span", { className: `${baseClass}__icon${typeof icon === "string" ? " material-symbols-rounded" : ""}`, "aria-hidden": "true", children: icon });
     const control = href && !isDisabled && !isLoading ? /* @__PURE__ */ jsx(
-      "a",
+      Link,
       {
         ...rest,
         ref,

package/components/ContactCard/ContactCard.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 /** Props owned by ContactCard itself — everything else falls through to the root node. */
 type ContactCardOwnProps = {
     /** Primary label — e.g. "Email" */
@@ -40,6 +41,12 @@ type ContactCardOwnProps = {
     copyLabel?: string;
     /** Additional CSS classes */
     className?: string;
+    /**
+     * The component its links render with, such as Next.js's `Link`, so they
+     * navigate through the app's router. Wins over a LinkProvider's; a plain
+     * `<a>` when neither is set.
+     */
+    linkComponent?: LinkComponent;
 };
 export interface ContactCardProps extends ContactCardOwnProps, Omit<React.ComponentPropsWithoutRef<'a'>, keyof ContactCardOwnProps | 'children'> {
 }

package/components/ContactCard/ContactCard.js

@@ -1,6 +1,7 @@
 "use client";
 import { jsx, jsxs, Fragment } from "react/jsx-runtime";
 import React from "react";
+import { useLinkComponent } from "../../behaviors/LinkProvider.js";
 import "./ContactCard.css";
 import "../../fonts/material-symbols.css";
 const ContactCard = React.forwardRef(
@@ -16,9 +17,11 @@ const ContactCard = React.forwardRef(
     copyOnClick = false,
     copyLabel,
     className = "",
+    linkComponent,
     ...rest
   }, ref) => {
     const classes = ["ds-contact-card", className].filter(Boolean).join(" ");
+    const Link = useLinkComponent(linkComponent);
     const isProtocolLink = /^(mailto:|tel:)/i.test(href);
     const openInNewTab = external && !isProtocolLink;
     const trailingIcon = copyOnClick ? "content_copy" : external ? "open_in_new" : "arrow_forward";
@@ -74,7 +77,7 @@ const ContactCard = React.forwardRef(
       );
     }
     return /* @__PURE__ */ jsx(
-      "a",
+      Link,
       {
         ...rest,
         ref,

package/components/LinkList/LinkList.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 export interface LinkListItem {
     /** Link destination */
     href: string;
@@ -21,6 +22,13 @@ type LinkListOwnProps = {
     items: LinkListItem[];
     /** Additional CSS classes */
     className?: string;
+    /**
+     * The component its links render with, such as Next.js's `Link`, so they
+     * navigate through the app's router; a plain `<a>` when unset. This
+     * component can render on the server, so it never reads a LinkProvider:
+     * pass the prop even under one.
+     */
+    linkComponent?: LinkComponent;
 };
 export interface LinkListProps extends LinkListOwnProps, Omit<React.ComponentPropsWithoutRef<'div'>, keyof LinkListOwnProps | 'children'> {
 }

package/components/LinkList/LinkList.js

@@ -3,13 +3,14 @@ import React from "react";
 import "./LinkList.css";
 import "../../fonts/material-symbols.css";
 const LinkList = React.forwardRef(
-  ({ items, className = "", ...rest }, ref) => {
+  ({ items, className = "", linkComponent, ...rest }, ref) => {
     const classes = ["ds-link-list", className].filter(Boolean).join(" ");
+    const Link = linkComponent ?? "a";
     return /* @__PURE__ */ jsx("div", { ...rest, ref, className: classes, children: items.map((item) => {
       const subs = item.sub ? Array.isArray(item.sub) ? item.sub : [item.sub] : [];
       const newTab = item.newTab ?? true;
       return /* @__PURE__ */ jsxs(
-        "a",
+        Link,
         {
           href: item.href,
           target: newTab ? "_blank" : void 0,

package/components/NavList/NavList.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 export interface NavListItem {
     /** Row text. */
     label: string;
@@ -40,6 +41,12 @@ type NavListOwnProps = {
     expandLabel?: (label: string) => string;
     /** Accessible name of an expanded section's chevron toggle, given the row's label. Defaults to "Collapse <label>". */
     collapseLabel?: (label: string) => string;
+    /**
+     * The component its links render with, such as Next.js's `Link`, so they
+     * navigate through the app's router; passed on to each row's Button. Wins over a
+     * LinkProvider's; a plain `<a>` when neither is set.
+     */
+    linkComponent?: LinkComponent;
     /** Additional CSS classes */
     className?: string;
 };

package/components/NavList/NavList.js

@@ -16,6 +16,7 @@ const NavList = React.forwardRef(
     onNavigate,
     expandLabel = (label) => `Expand ${label}`,
     collapseLabel = (label) => `Collapse ${label}`,
+    linkComponent,
     className = "",
     ...rest
   }, ref) => {
@@ -45,6 +46,7 @@ const NavList = React.forwardRef(
           size: level === 1 ? "default" : "compact",
           label: item.label,
           href: item.href,
+          linkComponent,
           ariaCurrent: isCurrent,
           className: isCurrent ? "ds-button--active" : void 0,
           onClick: (event) => onNavigate?.(item, event)

package/components/SidebarPanel/SidebarPanel.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { LinkComponent } from '../../behaviors/LinkProvider';
 export interface SidebarPanelItem {
     /** Unique key for this item */
     key: string;
@@ -37,6 +38,12 @@ type SidebarPanelOwnProps = {
     backLabel?: string;
     /** Additional CSS classes */
     className?: string;
+    /**
+     * The component its links render with, such as Next.js's `Link`, so they
+     * navigate through the app's router. Wins over a LinkProvider's; a plain
+     * `<a>` when neither is set.
+     */
+    linkComponent?: LinkComponent;
 };
 export interface SidebarPanelProps extends SidebarPanelOwnProps, Omit<React.ComponentPropsWithoutRef<'nav'>, keyof SidebarPanelOwnProps> {
 }