@djangocfg/layouts 2.1.277 → 2.1.280

package/README.md

@@ -87,7 +87,7 @@ Wraps `BaseApp` and picks **admin → private → public** layout by path (`matc
 
 | Component | Use |
 |---|---|
-| **`PublicLayout`** | Marketing / docs. Slots for navbar + footer. **[See PublicLayout README](./src/layouts/PublicLayout/README.md)** for full props, navbar variants (`FloatingNavbar` / `FlushNavbar` / `MinimalNavbar`), `DefaultFooter`, `NavAction`, and hooks. |
+| **`PublicLayout`** | Marketing / docs. Slots for navbar + footer. Supports `LinkComponentProvider` to inject an i18n-aware `Link` (e.g. `next-intl`) so every anchor picks up the locale prefix. **[See PublicLayout README](./src/layouts/PublicLayout/README.md)** for full props, navbar variants (`FloatingNavbar` / `FlushNavbar` / `MinimalNavbar`), `DefaultFooter`, `NavAction`, and hooks. |
 | **`PrivateLayout`** | App shell — sidebar + header. |
 | **`AuthLayout`** | Sign-in flows. |
 | **`AdminLayout`** | Admin console. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/layouts",
-  "version": "2.1.277",
+  "version": "2.1.280",
   "description": "Simple, straightforward layout components for Next.js - import and use with props",
   "keywords": [
     "layouts",
@@ -74,19 +74,19 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/api": "^2.1.277",
-    "@djangocfg/centrifugo": "^2.1.277",
-    "@djangocfg/debuger": "^2.1.277",
-    "@djangocfg/i18n": "^2.1.277",
-    "@djangocfg/monitor": "^2.1.277",
-    "@djangocfg/ui-core": "^2.1.277",
-    "@djangocfg/ui-nextjs": "^2.1.277",
-    "@djangocfg/ui-tools": "^2.1.277",
+    "@djangocfg/api": "^2.1.280",
+    "@djangocfg/centrifugo": "^2.1.280",
+    "@djangocfg/debuger": "^2.1.280",
+    "@djangocfg/i18n": "^2.1.280",
+    "@djangocfg/monitor": "^2.1.280",
+    "@djangocfg/ui-core": "^2.1.280",
+    "@djangocfg/ui-nextjs": "^2.1.280",
+    "@djangocfg/ui-tools": "^2.1.280",
     "@hookform/resolvers": "^5.2.2",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
-    "next": "^16.0.10",
+    "next": "^16.2.2",
     "p-retry": "^7.0.0",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
@@ -110,15 +110,15 @@
     "uuid": "^11.1.0"
   },
   "devDependencies": {
-    "@djangocfg/api": "^2.1.277",
-    "@djangocfg/centrifugo": "^2.1.277",
-    "@djangocfg/debuger": "^2.1.277",
-    "@djangocfg/i18n": "^2.1.277",
-    "@djangocfg/monitor": "^2.1.277",
-    "@djangocfg/typescript-config": "^2.1.277",
-    "@djangocfg/ui-core": "^2.1.277",
-    "@djangocfg/ui-nextjs": "^2.1.277",
-    "@djangocfg/ui-tools": "^2.1.277",
+    "@djangocfg/api": "^2.1.280",
+    "@djangocfg/centrifugo": "^2.1.280",
+    "@djangocfg/debuger": "^2.1.280",
+    "@djangocfg/i18n": "^2.1.280",
+    "@djangocfg/monitor": "^2.1.280",
+    "@djangocfg/typescript-config": "^2.1.280",
+    "@djangocfg/ui-core": "^2.1.280",
+    "@djangocfg/ui-nextjs": "^2.1.280",
+    "@djangocfg/ui-tools": "^2.1.280",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/layouts/PublicLayout/README.md

@@ -23,6 +23,30 @@ import { PublicLayout, FloatingNavbar, DefaultFooter } from '@djangocfg/layouts'
 | `contentTopSpacing` | `'auto' \| 'none'` | `'auto'` | Auto pads `<main>` based on the navbar variant. |
 | `contentBottomSpacing` | `'auto' \| 'none' \| 'compact'` | `'auto'` | Bottom breathing room before footer. |
 
+## `LinkComponentProvider` — inject a custom Link
+
+All internal anchors (navbar, footer, mobile drawer) render through a single
+injectable `Link` component. Default is plain `next/link`. Wrap the layout in
+`LinkComponentProvider` to swap it — for example to pipe in a locale-aware
+`Link` from `next-intl`:
+
+```tsx
+import { LinkComponentProvider, PublicLayout, FloatingNavbar } from '@djangocfg/layouts';
+import { Link } from '@/i18n/navigation'; // next-intl createNavigation().Link
+
+<LinkComponentProvider value={Link}>
+  <PublicLayout navbar={<FloatingNavbar config={…} />} footer={…}>
+    {children}
+  </PublicLayout>
+</LinkComponentProvider>
+```
+
+Why: with `next-intl`'s `localePrefix: 'as-needed'`, plain `next/link` does
+not prepend the active locale, so every navbar item drops the `/ru/` prefix
+on click. Injecting the i18n-aware `Link` fixes that once for the whole tree.
+
+Monolingual apps don't need the provider — the default `next/link` is fine.
+
 ## Navbar variants
 
 Three variants. All share the same core props (below); only the chrome differs.
@@ -131,7 +155,7 @@ Three variants: `full` (default) with brand column + menus + controls; `compact`
 
 ## Primitives
 
-`NavBrand`, `NavActions`, `NavActionItem`, `NavDesktopItems`, `ThemeBrandMark`, `ThemeBrandMarkImg`, `PublicLayoutProvider`, `usePublicLayout`.
+`NavBrand`, `NavActions`, `NavActionItem`, `NavDesktopItems`, `ThemeBrandMark`, `ThemeBrandMarkImg`, `LinkComponentProvider`, `useLinkComponent`, `PublicLayoutProvider`, `usePublicLayout`.
 
 ## Context
 

package/src/layouts/PublicLayout/footers/DefaultFooter/DefaultFooter.tsx

@@ -13,7 +13,7 @@ import { Button } from '@djangocfg/ui-core/components';
 import { useThemeContext } from '@djangocfg/ui-nextjs/theme';
 
 import { LocaleSwitcher } from '../../../_components/LocaleSwitcher';
-import { SmartNavLink } from '../../primitives/SmartNavLink';
+import { useLinkComponent } from '../../primitives/LinkComponentContext';
 import { FooterMenuSections } from './FooterMenuSections';
 import { FooterProjectInfo } from './FooterProjectInfo';
 
@@ -69,6 +69,7 @@ function ThemeModeControl() {
 }
 
 export function DefaultFooter({ config }: DefaultFooterProps) {
+  const Link = useLinkComponent();
   const variant = config.variant ?? 'full';
   const shellClass = config.shell?.className;
   const brandSlot = config.brand?.slot;
@@ -132,13 +133,13 @@ export function DefaultFooter({ config }: DefaultFooterProps) {
                       {link.label}
                     </a>
                   ) : (
-                    <SmartNavLink
+                    <Link
                       key={link.path}
                       href={link.path}
                       className="text-sm text-muted-foreground hover:text-foreground transition-colors"
                     >
                       {link.label}
-                    </SmartNavLink>
+                    </Link>
                   )
                 )}
               </div>
@@ -195,13 +196,13 @@ export function DefaultFooter({ config }: DefaultFooterProps) {
                     {link.label}
                   </a>
                 ) : (
-                  <SmartNavLink
+                  <Link
                     key={link.path}
                     href={link.path}
                     className="text-xs text-muted-foreground hover:text-primary transition-colors"
                   >
                     {link.label}
-                  </SmartNavLink>
+                  </Link>
                 )
               )}
             </div>
@@ -302,9 +303,9 @@ export function DefaultFooter({ config }: DefaultFooterProps) {
                     {link.label}
                   </a>
                 ) : (
-                  <SmartNavLink key={link.path} href={link.path} className="hover:text-foreground transition-colors whitespace-nowrap">
+                  <Link key={link.path} href={link.path} className="hover:text-foreground transition-colors whitespace-nowrap">
                     {link.label}
-                  </SmartNavLink>
+                  </Link>
                 )
               )}
             </div>

package/src/layouts/PublicLayout/footers/DefaultFooter/FooterBottom.tsx

@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { SmartNavLink } from '../../primitives/SmartNavLink';
+import { useLinkComponent } from '../../primitives/LinkComponentContext';
 import { DjangoCFGLogo } from './DjangoCFGLogo';
 
 import type { FooterLink } from './types';
@@ -23,6 +23,7 @@ export function FooterBottom({
   links = [],
   variant = 'desktop',
 }: FooterBottomProps) {
+  const Link = useLinkComponent();
   const isMobile = variant === 'mobile';
 
   if (isMobile) {
@@ -95,13 +96,13 @@ export function FooterBottom({
                   {link.label}
                 </a>
               ) : (
-                <SmartNavLink
+                <Link
                   key={link.path}
                   href={link.path}
                   className="text-xs text-muted-foreground hover:text-primary transition-colors"
                 >
                   {link.label}
-                </SmartNavLink>
+                </Link>
               )
             )}
           </div>

package/src/layouts/PublicLayout/footers/DefaultFooter/FooterMenuSections.tsx

@@ -2,7 +2,7 @@
 
 import React from 'react';
 
-import { SmartNavLink } from '../../primitives/SmartNavLink';
+import { useLinkComponent } from '../../primitives/LinkComponentContext';
 
 import type { FooterMenuSection } from './types';
 
@@ -17,6 +17,7 @@ export function FooterMenuSections({
   minColumnWidth = 180,
   maxColumns = 5,
 }: FooterMenuSectionsProps) {
+  const Link = useLinkComponent();
   if (menuSections.length === 0) return null;
 
   const effectiveColumns = Math.max(1, Math.min(maxColumns, menuSections.length));
@@ -34,12 +35,12 @@ export function FooterMenuSections({
           <ul className="space-y-2">
             {section.items.map((item) => (
               <li key={item.path}>
-                <SmartNavLink
+                <Link
                   href={item.path}
                   className="text-sm text-foreground/90 hover:text-foreground transition-colors"
                 >
                   {item.label}
-                </SmartNavLink>
+                </Link>
               </li>
             ))}
           </ul>

package/src/layouts/PublicLayout/index.ts

@@ -36,18 +36,16 @@ export {
   NavDesktopItems,
   ThemeBrandMark,
   ThemeBrandMarkImg,
-  ExternalPrefixesProvider,
-  useExternalPrefixes,
-  isExternalPrefixHref,
-  SmartNavLink,
+  LinkComponentProvider,
+  useLinkComponent,
 } from './primitives';
 export type {
   NavAction,
   ThemeBrandMarkProps,
   ThemeBrandMarkImgProps,
-  ExternalPrefixes,
-  ExternalPrefixesProviderProps,
-  SmartNavLinkProps,
+  LinkComponent,
+  LinkComponentProps,
+  LinkComponentProviderProps,
 } from './primitives';
 
 // Navbar variants

package/src/layouts/PublicLayout/navbars/FloatingNavbar/FloatingNavbar.tsx

@@ -11,7 +11,6 @@ import React from 'react';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { publicFloatingChromeClassName } from '../../publicShellShadow';
-import { ExternalPrefixesProvider } from '../../primitives/ExternalPrefixesContext';
 import type { NavAction } from '../../primitives/NavActionItem';
 import { NavbarShell } from '../../shared';
 import type {
@@ -52,14 +51,6 @@ export interface FloatingNavbarConfig {
   actionsLeadingSlot?: React.ReactNode;
   /** Arbitrary ReactNode after the mobile toggle. */
   actionsTrailingSlot?: React.ReactNode;
-  /**
-   * Path prefixes that should be navigated with a plain `<a>` (full page load)
-   * instead of `next/link`. Use this for routes served by a catch-all handler
-   * outside the Next.js App Router (e.g. Nextra at `/docs/*`) — those routes
-   * cannot return an RSC payload, so `next/link` client navigation fails.
-   * @default []
-   */
-  externalPrefixes?: readonly string[];
 }
 
 export interface FloatingNavbarProps {
@@ -71,7 +62,6 @@ export function FloatingNavbar({ config }: FloatingNavbarProps) {
   const rounding = config.shell?.rounding;
   const containerClassName = config.shell?.className;
   const position = config.navbarPosition ?? 'sticky';
-  const externalPrefixes = config.externalPrefixes;
 
   const outerClassName = cn(
     position === 'fixed' ? 'fixed' : position === 'static' ? 'static' : 'sticky',
@@ -87,7 +77,7 @@ export function FloatingNavbar({ config }: FloatingNavbarProps) {
   );
 
   return (
-    <ExternalPrefixesProvider value={externalPrefixes}>
+    <>
       <NavbarShell
         variant="floating"
         position={position}
@@ -122,6 +112,6 @@ export function FloatingNavbar({ config }: FloatingNavbarProps) {
         containerClassName={containerClassName}
         rounding={rounding}
       />
-    </ExternalPrefixesProvider>
+    </>
   );
 }

package/src/layouts/PublicLayout/navbars/FlushNavbar/FlushNavbar.tsx

@@ -10,7 +10,6 @@ import React from 'react';
 
 import { cn } from '@djangocfg/ui-core/lib';
 
-import { ExternalPrefixesProvider } from '../../primitives/ExternalPrefixesContext';
 import type { NavAction } from '../../primitives/NavActionItem';
 import { NavbarShell } from '../../shared';
 import type {
@@ -51,14 +50,6 @@ export interface FlushNavbarConfig {
   actionsLeadingSlot?: React.ReactNode;
   /** Arbitrary ReactNode after the mobile toggle. */
   actionsTrailingSlot?: React.ReactNode;
-  /**
-   * Path prefixes that should be navigated with a plain `<a>` (full page load)
-   * instead of `next/link`. Use this for routes served by a catch-all handler
-   * outside the Next.js App Router (e.g. Nextra at `/docs/*`) — those routes
-   * cannot return an RSC payload, so `next/link` client navigation fails.
-   * @default []
-   */
-  externalPrefixes?: readonly string[];
 }
 
 export interface FlushNavbarProps {
@@ -69,7 +60,6 @@ export function FlushNavbar({ config }: FlushNavbarProps) {
   const navigation = config.navigation ?? [];
   const containerClassName = config.shell?.className;
   const position = config.navbarPosition ?? 'sticky';
-  const externalPrefixes = config.externalPrefixes;
 
   const outerClassName = cn(
     position === 'fixed' ? 'fixed' : position === 'static' ? 'static' : 'sticky',
@@ -83,7 +73,7 @@ export function FlushNavbar({ config }: FlushNavbarProps) {
   );
 
   return (
-    <ExternalPrefixesProvider value={externalPrefixes}>
+    <>
       <NavbarShell
         variant="flush"
         position={position}
@@ -117,6 +107,6 @@ export function FlushNavbar({ config }: FlushNavbarProps) {
         userMenu={config.userMenu}
         containerClassName={containerClassName}
       />
-    </ExternalPrefixesProvider>
+    </>
   );
 }

package/src/layouts/PublicLayout/navbars/MinimalNavbar/MinimalNavbar.tsx

@@ -17,7 +17,6 @@ import { Button } from '@djangocfg/ui-core/components';
 import { cn } from '@djangocfg/ui-core/lib';
 
 import { UserMenu } from '../../../_components/UserMenu';
-import { ExternalPrefixesProvider } from '../../primitives/ExternalPrefixesContext';
 import { NavActionItem, type NavAction } from '../../primitives/NavActionItem';
 import { NavbarShell, type NavbarActionsContext } from '../../shared';
 import type {
@@ -68,15 +67,6 @@ export interface MinimalNavbarConfig {
    * @default 'mx-auto max-w-[1400px] px-4 sm:px-6 lg:px-10'
    */
   containerClassName?: string;
-
-  /**
-   * Path prefixes that should be navigated with a plain `<a>` (full page load)
-   * instead of `next/link`. Use this for routes served by a catch-all handler
-   * outside the Next.js App Router (e.g. Nextra at `/docs/*`) — those routes
-   * cannot return an RSC payload, so `next/link` client navigation fails.
-   * @default []
-   */
-  externalPrefixes?: readonly string[];
 }
 
 export interface MinimalNavbarProps {
@@ -131,7 +121,6 @@ export function MinimalNavbar({ config }: MinimalNavbarProps) {
   const position = config.navbarPosition ?? 'sticky';
   const transparent = config.transparent ?? true;
   const containerClassName = config.containerClassName ?? 'mx-auto max-w-[1400px] px-4 sm:px-6 lg:px-10';
-  const externalPrefixes = config.externalPrefixes;
 
   const outerClassName = cn(
     position === 'fixed' ? 'fixed' : position === 'static' ? 'static' : 'sticky',
@@ -142,7 +131,7 @@ export function MinimalNavbar({ config }: MinimalNavbarProps) {
   const shapeClassName = 'w-full rounded-none border-0 shadow-none';
 
   return (
-    <ExternalPrefixesProvider value={externalPrefixes}>
+    <>
       <NavbarShell
         variant="minimal"
         position={position}
@@ -175,6 +164,6 @@ export function MinimalNavbar({ config }: MinimalNavbarProps) {
         userMenu={config.userMenu}
         containerClassName={containerClassName}
       />
-    </ExternalPrefixesProvider>
+    </>
   );
 }

package/src/layouts/PublicLayout/primitives/LinkComponentContext.tsx

@@ -0,0 +1,50 @@
+/**
+ * LinkComponentContext
+ *
+ * Dependency-injects the Link component used by navbars, footers, and mobile
+ * drawers. Apps wire in their own i18n-aware Link (e.g. next-intl's
+ * `createNavigation().Link`) so internal navigation picks up the locale
+ * prefix. Default falls back to plain `next/link`.
+ */
+
+'use client';
+
+import NextLink, { type LinkProps as NextLinkProps } from 'next/link';
+import React, {
+  createContext,
+  useContext,
+  type AnchorHTMLAttributes,
+  type ComponentType,
+  type ReactNode,
+} from 'react';
+
+type AnchorProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>;
+
+export type LinkComponentProps = Omit<NextLinkProps, 'passHref' | 'legacyBehavior'> &
+  AnchorProps & {
+    children?: ReactNode;
+  };
+
+export type LinkComponent = ComponentType<LinkComponentProps>;
+
+const LinkComponentContext = createContext<LinkComponent>(NextLink as LinkComponent);
+
+export interface LinkComponentProviderProps {
+  value: LinkComponent;
+  children: ReactNode;
+}
+
+export function LinkComponentProvider({
+  value,
+  children,
+}: LinkComponentProviderProps) {
+  return (
+    <LinkComponentContext.Provider value={value}>
+      {children}
+    </LinkComponentContext.Provider>
+  );
+}
+
+export function useLinkComponent(): LinkComponent {
+  return useContext(LinkComponentContext);
+}

package/src/layouts/PublicLayout/primitives/NavActionItem.tsx

@@ -11,7 +11,7 @@ import React, { type ReactNode } from 'react';
 
 import { cn } from '@djangocfg/ui-core/lib';
 
-import { SmartNavLink } from './SmartNavLink';
+import { useLinkComponent } from './LinkComponentContext';
 
 export interface NavAction {
   label: string;
@@ -55,6 +55,7 @@ interface NavActionItemProps {
 }
 
 export function NavActionItem({ action, className }: NavActionItemProps) {
+  const Link = useLinkComponent();
   const variant = action.variant ?? 'ghost';
   const cls = cn(
     baseCls,
@@ -88,8 +89,8 @@ export function NavActionItem({ action, className }: NavActionItemProps) {
     );
   }
   return (
-    <SmartNavLink href={action.href} className={cls} onClick={action.onClick}>
+    <Link href={action.href} className={cls} onClick={action.onClick}>
       {content}
-    </SmartNavLink>
+    </Link>
   );
 }

package/src/layouts/PublicLayout/primitives/NavBrand.tsx

@@ -2,7 +2,7 @@
 
 import React, { type ReactNode } from 'react';
 
-import { SmartNavLink } from './SmartNavLink';
+import { useLinkComponent } from './LinkComponentContext';
 
 interface NavBrandProps {
   brand?: ReactNode;
@@ -10,16 +10,18 @@ interface NavBrandProps {
 }
 
 export function NavBrand({ brand, brandHref = '/' }: NavBrandProps) {
+  const Link = useLinkComponent();
+
   if (brand == null || brand === '' || brand === false) return null;
 
   if (typeof brand === 'string') {
     return (
-      <SmartNavLink
+      <Link
         href={brandHref}
         className="font-bold text-[15px] text-foreground hover:opacity-90 transition-opacity"
       >
         {brand}
-      </SmartNavLink>
+      </Link>
     );
   }
 

package/src/layouts/PublicLayout/primitives/NavDesktopItems.tsx

@@ -10,7 +10,7 @@ import type { NavigationItem } from '../../types';
 import type { UseDropdownMenuReturn } from '../hooks/useDropdownMenu';
 import { useResponsiveOverflow } from '../hooks/useResponsiveOverflow';
 import type { PublicDesktopDropdownRenderer } from '../navbarTypes';
-import { SmartNavLink } from './SmartNavLink';
+import { useLinkComponent } from './LinkComponentContext';
 
 interface NavDesktopItemsProps {
   /** Full ordered item list; overflow is computed responsively. */
@@ -57,6 +57,7 @@ export function NavDesktopItems({
   dropdown,
   renderDesktopDropdown,
 }: NavDesktopItemsProps) {
+  const Link = useLinkComponent();
   const { openDropdownKey, scheduleOpen, scheduleClose, closeDropdown } = dropdown;
 
   const { visibleCount, containerRef, itemRef, measured } = useResponsiveOverflow({
@@ -91,9 +92,9 @@ export function NavDesktopItems({
                     <span className="min-w-0 truncate" title={sub.label}>{sub.label}</span>
                   </a>
                 ) : (
-                  <SmartNavLink href={sub.href} className={subMenuLinkCls(subActive)}>
+                  <Link href={sub.href} className={subMenuLinkCls(subActive)}>
                     <span className="min-w-0 truncate" title={sub.label}>{sub.label}</span>
-                  </SmartNavLink>
+                  </Link>
                 )}
               </div>
             );
@@ -149,13 +150,13 @@ export function NavDesktopItems({
 
     const active = isActivePath(item.href);
     return (
-      <SmartNavLink
+      <Link
         key={item.href}
         href={item.href}
         className={cn(navItemCls, active && navItemActiveCls)}
       >
         <span className={labelCls} title={item.label}>{item.label}</span>
-      </SmartNavLink>
+      </Link>
     );
   };
 
@@ -235,9 +236,9 @@ export function NavDesktopItems({
                   const active = isGroupActive(item);
                   return (
                     <div key={`overflow-${item.href}`} className="rounded-full">
-                      <SmartNavLink href={item.href} className={subMenuLinkCls(active)}>
+                      <Link href={item.href} className={subMenuLinkCls(active)}>
                         <span className="min-w-0 truncate" title={item.label}>{item.label}</span>
-                      </SmartNavLink>
+                      </Link>
                     </div>
                   );
                 })}

package/src/layouts/PublicLayout/primitives/index.ts

@@ -6,13 +6,11 @@ export { NavDesktopItems } from './NavDesktopItems';
 export { ThemeBrandMark, ThemeBrandMarkImg } from './ThemeBrandMark';
 export type { ThemeBrandMarkProps, ThemeBrandMarkImgProps } from './ThemeBrandMark';
 export {
-  ExternalPrefixesProvider,
-  useExternalPrefixes,
-  isExternalPrefixHref,
-} from './ExternalPrefixesContext';
+  LinkComponentProvider,
+  useLinkComponent,
+} from './LinkComponentContext';
 export type {
-  ExternalPrefixes,
-  ExternalPrefixesProviderProps,
-} from './ExternalPrefixesContext';
-export { SmartNavLink } from './SmartNavLink';
-export type { SmartNavLinkProps } from './SmartNavLink';
+  LinkComponent,
+  LinkComponentProps,
+  LinkComponentProviderProps,
+} from './LinkComponentContext';

package/src/layouts/PublicLayout/shared/MobileDrawerShell.tsx

@@ -19,7 +19,7 @@ import { usePathnameWithoutLocale } from '../../../hooks';
 import { UserMenu } from '../../_components/UserMenu';
 import { usePublicLayoutOptional } from '../context';
 import { useMobileNavPanel } from '../hooks';
-import { SmartNavLink } from '../primitives/SmartNavLink';
+import { useLinkComponent } from '../primitives/LinkComponentContext';
 
 import type { NavigationItem, UserMenuConfig } from '../../types';
 
@@ -35,6 +35,7 @@ export interface MobileDrawerShellProps {
 }
 
 export function MobileDrawerShell(props: MobileDrawerShellProps) {
+  const Link = useLinkComponent();
   const context = usePublicLayoutOptional();
   const mobileMenuOpen = props.isOpen ?? context?.mobileMenuOpen ?? false;
   const closeMobileMenu = props.onClose ?? context?.closeMobileMenu ?? (() => {});
@@ -133,7 +134,7 @@ export function MobileDrawerShell(props: MobileDrawerShellProps) {
                   const parentOnlySectionOpen = hasChildNav && anyChildActive;
                   return (
                     <div key={item.href}>
-                      <SmartNavLink
+                      <Link
                         href={item.href}
                         onClick={closeMobileMenu}
                         title={item.label}
@@ -148,13 +149,13 @@ export function MobileDrawerShell(props: MobileDrawerShellProps) {
                         )}
                       >
                         {item.label}
-                      </SmartNavLink>
+                      </Link>
                       {hasChildNav && (
                         <div className="ml-3 mt-1.5 space-y-1 border-l border-border/40 pl-3">
                           {childItems.map((subItem) => {
                             const subActive = isActivePath(subItem.href);
                             return (
-                              <SmartNavLink
+                              <Link
                                 key={`${item.href}-${subItem.href}`}
                                 href={subItem.href}
                                 onClick={closeMobileMenu}
@@ -168,7 +169,7 @@ export function MobileDrawerShell(props: MobileDrawerShellProps) {
                                 )}
                               >
                                 {subItem.label}
-                              </SmartNavLink>
+                              </Link>
                             );
                           })}
                         </div>
@@ -182,7 +183,7 @@ export function MobileDrawerShell(props: MobileDrawerShellProps) {
 
           {showSignInFooter && (
             <div className="shrink-0 border-t border-border/50 p-4">
-              <SmartNavLink
+              <Link
                 href={userMenu?.authPath || '/auth'}
                 onClick={closeMobileMenu}
                 className="block"
@@ -194,7 +195,7 @@ export function MobileDrawerShell(props: MobileDrawerShellProps) {
                     aria-hidden
                   />
                 </Button>
-              </SmartNavLink>
+              </Link>
             </div>
           )}
         </div>

package/src/layouts/PublicLayout/primitives/ExternalPrefixesContext.tsx

@@ -1,69 +0,0 @@
-/**
- * ExternalPrefixesContext
- *
- * Provides a list of path prefixes that should be treated as "outside" the
- * Next.js App Router (e.g. a catch-all served by Nextra). Consumers inside the
- * navbar (`SmartNavLink`) check whether the `href` starts with any configured
- * prefix; if so, they render a native `<a>` (full page load) instead of a
- * `next/link` that would fetch an RSC payload the route cannot produce.
- *
- * Default: `[]` — so behaviour is unchanged for consumers who do not opt in.
- */
-
-'use client';
-
-import React, { createContext, useContext, useMemo, type ReactNode } from 'react';
-
-export type ExternalPrefixes = readonly string[];
-
-const ExternalPrefixesContext = createContext<ExternalPrefixes>([]);
-
-export interface ExternalPrefixesProviderProps {
-  /** List of path prefixes treated as external to the App Router. */
-  value?: ExternalPrefixes;
-  children: ReactNode;
-}
-
-export function ExternalPrefixesProvider({
-  value,
-  children,
-}: ExternalPrefixesProviderProps) {
-  const resolved = useMemo<ExternalPrefixes>(() => value ?? [], [value]);
-  return (
-    <ExternalPrefixesContext.Provider value={resolved}>
-      {children}
-    </ExternalPrefixesContext.Provider>
-  );
-}
-
-export function useExternalPrefixes(): ExternalPrefixes {
-  return useContext(ExternalPrefixesContext);
-}
-
-/**
- * Returns true if `href` is a string that starts with any of the provided
- * external prefixes. Non-string hrefs (objects, `next/link` URL shape) always
- * return false — those are App Router internal.
- *
- * Matches the prefix exactly or at a path-boundary (`/`, `?`, `#`) so that
- * `/docs` in the prefix list matches `/docs`, `/docs/`, `/docs/foo`, `/docs?x=1`,
- * `/docs#bar` — but NOT `/docsearch` (which should stay an App Router link).
- */
-export function isExternalPrefixHref(
-  href: unknown,
-  prefixes: ExternalPrefixes,
-): href is string {
-  if (typeof href !== 'string' || prefixes.length === 0) return false;
-  for (const prefix of prefixes) {
-    if (!prefix) continue;
-    if (href === prefix) return true;
-    if (
-      href.startsWith(`${prefix}/`) ||
-      href.startsWith(`${prefix}?`) ||
-      href.startsWith(`${prefix}#`)
-    ) {
-      return true;
-    }
-  }
-  return false;
-}

package/src/layouts/PublicLayout/primitives/SmartNavLink.tsx

@@ -1,81 +0,0 @@
-/**
- * SmartNavLink
- *
- * Drop-in replacement for `next/link` used inside PublicLayout navbars/footers.
- *
- * If the `href` is a string that starts with one of the prefixes configured
- * via `ExternalPrefixesProvider`, renders a plain `<a>` (full page navigation).
- * This is required for routes owned by a catch-all handler outside App Router
- * (e.g. Nextra `/docs/*`), where `next/link` client navigation asks for an
- * RSC payload the route cannot produce — resulting in a hard error banner.
- *
- * Otherwise falls back to `next/link` so existing behaviour is preserved.
- */
-
-'use client';
-
-import Link, { type LinkProps } from 'next/link';
-import React, { forwardRef, type AnchorHTMLAttributes, type ReactNode } from 'react';
-
-import {
-  isExternalPrefixHref,
-  useExternalPrefixes,
-  type ExternalPrefixes,
-} from './ExternalPrefixesContext';
-
-type AnchorProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>;
-
-export interface SmartNavLinkProps
-  extends Omit<LinkProps, 'href' | 'passHref' | 'legacyBehavior'>,
-    AnchorProps {
-  href: LinkProps['href'];
-  children?: ReactNode;
-  /** Optional override — falls back to context value. */
-  externalPrefixes?: ExternalPrefixes;
-}
-
-export const SmartNavLink = forwardRef<HTMLAnchorElement, SmartNavLinkProps>(
-  function SmartNavLink(props, ref) {
-    const {
-      href,
-      children,
-      externalPrefixes,
-      // LinkProps-specific fields we should NOT forward to a plain <a>.
-      prefetch,
-      replace,
-      scroll,
-      shallow,
-      locale,
-      // Rest are anchor-compatible attributes.
-      ...anchorProps
-    } = props;
-
-    const contextPrefixes = useExternalPrefixes();
-    const prefixes = externalPrefixes ?? contextPrefixes;
-
-    const shouldUseAnchor = isExternalPrefixHref(href, prefixes);
-
-    if (shouldUseAnchor) {
-      return (
-        <a ref={ref} href={href} {...anchorProps}>
-          {children}
-        </a>
-      );
-    }
-
-    return (
-      <Link
-        ref={ref}
-        href={href}
-        prefetch={prefetch}
-        replace={replace}
-        scroll={scroll}
-        shallow={shallow}
-        locale={locale}
-        {...anchorProps}
-      >
-        {children}
-      </Link>
-    );
-  },
-);