@djangocfg/ui-core 2.1.293 → 2.1.297

package/README.md

@@ -83,28 +83,62 @@ Default **`TooltipContent`** styling uses semantic **popover** tokens (`bg-popov
 ### Specialized (7)
 `Kbd` `TokenIcon` `Item` `Portal` `ImageWithFallback` `CopyButton` `CopyField`
 
-## Hooks (17)
+## Hooks (30+)
+
+Hooks are organized by domain inside the package (`src/hooks/<group>/`).
+Public import path is the single barrel:
+
+```tsx
+import { useIsMobile, useScroll, useNavigate } from '@djangocfg/ui-core/hooks';
+```
+
+### `dom/` — DOM & viewport
 
 | Hook | Description |
 |------|-------------|
-| `useMediaQuery(query)` | Raw media query — pass any CSS query string. Exports `BREAKPOINTS` constants (Tailwind v4 defaults) |
-| `useIsPhone()` | `< 640px` — phones only |
-| `useIsMobile()` | `< 768px` — phones + small tablets |
-| `useIsTabletOrBelow()` | `< 1024px` — phones + tablets |
-| `useBodyScrollLock(locked)` | Lock body scroll while `locked=true`; counter-based (multi-consumer safe), iOS-safe via `position: fixed` fallback |
-| `useCopy` | Copy to clipboard |
-| `useCountdown` | Countdown timer |
-| `useDebounce` | Debounce values |
-| `useDebouncedCallback` | Debounced callbacks |
-| `useImageLoader` | Image loading state |
-| `useToast` / `toast` | Toast notifications (Sonner) |
-| `useEventListener` | Event bus |
-| `useDebugTools` | Debug utilities |
-| `useHotkey` | Keyboard shortcuts (react-hotkeys-hook) |
-| `useShortcutModLabel()` | Returns `⌘` or `Ctrl` for shortcut hints (Apple vs Windows/Linux); pairs with `metaKey \|\| ctrlKey` handlers |
-| `useBrowserDetect` | Browser detection (Chrome, Safari, in-app browsers, etc.) |
-| `useDeviceDetect` | Device detection (mobile, tablet, desktop, OS, etc.) |
-| `useResolvedTheme` | Current resolved theme (light/dark/system) |
+| `useScroll(target?)` | Reactive `{ x, y, direction, isScrolling }` for window or any scrollable element. `useSyncExternalStore` + module-level shared store + rAF throttle + passive listener. |
+| `useScrollPosition(target?)` / `useScrollDirection(target?)` / `useIsScrolling(target?)` | Single-field variants — re-render only when their slice changes. |
+| `useBodyScrollLock(locked)` | Lock body scroll while `locked=true`; counter-based (multi-consumer safe), iOS-safe via `position: fixed` fallback. |
+| `useCopy` | Copy to clipboard. |
+| `useImageLoader` | Image loading state. |
+
+### `media/` — viewport size
+
+| Hook | Description |
+|------|-------------|
+| `useMediaQuery(query)` | Raw media query — pass any CSS query string. Exports `BREAKPOINTS` constants (Tailwind v4 defaults). |
+| `useIsPhone()` | `< 640px` — phones only. |
+| `useIsMobile()` | `< 768px` — phones + small tablets. |
+| `useIsTabletOrBelow()` | `< 1024px` — phones + tablets. |
+
+### `state/` — state primitives
+
+| Hook | Description |
+|------|-------------|
+| `useDebounce` | Debounce values. |
+| `useDebouncedCallback` | Debounced callbacks. |
+| `useLocalStorage` / `useSessionStorage` | Type-safe wrappers with TTL. |
+| `useStoredValue` | Unified API over local/session storage. |
+
+### `device/` — environment detection
+
+| Hook | Description |
+|------|-------------|
+| `useBrowserDetect` | Browser detection (Chrome, Safari, in-app browsers, etc.). |
+| `useDeviceDetect` | Device detection (mobile, tablet, desktop, OS, etc.). |
+| `useShortcutModLabel()` | Returns `⌘` or `Ctrl` for shortcut hints (Apple vs Windows/Linux); pairs with `metaKey \|\| ctrlKey` handlers. |
+
+### Other groups
+
+| Group | Hooks |
+|-------|-------|
+| `feedback/` | `useToast`, `toast` (Sonner). |
+| `theme/` | `useResolvedTheme` — current resolved theme (light/dark/system). |
+| `time/` | `useCountdown`, `useCountdownFromSeconds`. |
+| `events/` | `useEventListener`, `events` (PubSub bus). |
+| `hotkey/` | `useHotkey`, `HotkeysProvider` (react-hotkeys-hook). |
+| `debug/` | `useDebugTools`. |
+| `router/` | See [Router Hooks](#router-hooks) below — its own subsection. |
 
 ```tsx
 import { useMediaQuery, useIsPhone, useIsMobile, BREAKPOINTS } from '@djangocfg/ui-core/hooks'
@@ -116,8 +150,61 @@ const isMobile = useIsMobile()  // < 768px
 // custom with constants
 const isNarrow = useMediaQuery(`(max-width: ${BREAKPOINTS.sm - 1}px)`)
 const isDark   = useMediaQuery('(prefers-color-scheme: dark)')
+
+// scroll snapshot — direction-aware navbar
+const { direction, isScrolling } = useScroll()
+const hideNav = direction === 'down' && isScrolling
+```
+
+## Router Hooks
+
+Framework-agnostic navigation primitives — work on plain History API by default, plug into any router via the adapter pattern. Full docs in [`src/hooks/router/README.md`](./src/hooks/router/README.md).
+
+| Hook | Purpose |
+|------|---------|
+| `useLocation()` | Reactive `{ pathname, search, hash, href }`. |
+| `useLocationProperty(get, getSsr)` | Subscribe to ONE field — skip re-renders on unrelated changes. |
+| `useNavigate()` | `navigate`, `navigateExternal`, `push`, `replace`, `back`, `forward`. |
+| `useQueryParams()` | Record-style read/write of `?key=value` URL state. |
+| `useQueryState(key, parser)` | Typed `useState`-style hook bound to one URL key (with `clearOnDefault`). |
+| `useBackOrFallback()` | Smart Back that falls back to a route when there's no in-app history. |
+| `useUrlBuilder()` | Pure URL assembly: `build`, `withCurrentParams`. |
+| `useSmartLink(href)` | Make any element a link (cmd-click, middle-click, Enter, Space). |
+| `useIsActive(href)` | Boolean for nav-item highlighting. |
+| `useRouter()` | Convenience facade composing everything. |
+| `RouterAdapterProvider` | Swap the navigation backend. |
+| `parseAsString` / `parseAsInteger` / `parseAsFloat` / `parseAsBoolean` / `parseAsIsoDate` / `parseAsStringEnum` / `parseAsArrayOf` / `parseAsJson` | Parsers for `useQueryState`. Each has `.withDefault(value)`. |
+
+```tsx
+import {
+  useNavigate,
+  useQueryState,
+  parseAsInteger,
+} from '@djangocfg/ui-core/hooks';
+
+const { navigate } = useNavigate();
+const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
+
+navigate('/products');
+setPage((p) => p + 1);  // ?page=2 — `page=1` is dropped (clearOnDefault)
 ```
 
+### Next.js adapter
+
+In Next apps, mount both adapters once near the root so navigation flows through `next/navigation` (server components + prefetch keep working) and `<Link>` delegates to `next/link`:
+
+```tsx
+import { NextRouterAdapter, NextLinkProvider } from '@djangocfg/ui-core/adapters/nextjs';
+
+<NextRouterAdapter>
+  <NextLinkProvider>
+    <App />
+  </NextLinkProvider>
+</NextRouterAdapter>
+```
+
+`next` is an **optional peer dependency** — Wails / Electron / Vite consumers don't pull it in. `@djangocfg/layouts/BaseApp` mounts both adapters automatically.
+
 ## Theme Palette Hooks
 
 Hooks for accessing theme colors from CSS variables (useful for Canvas, SVG, charts, diagrams, etc.):
@@ -290,7 +377,8 @@ import '@djangocfg/ui-core/styles/globals';
 |------|---------|
 | `@djangocfg/ui-core` | All components & hooks |
 | `@djangocfg/ui-core/components` | Components only |
-| `@djangocfg/ui-core/hooks` | Hooks only |
+| `@djangocfg/ui-core/hooks` | Hooks only (incl. router hooks) |
+| `@djangocfg/ui-core/adapters/nextjs` | `<NextRouterAdapter>` + `<NextLinkProvider>` for Next.js apps (optional peer: `next`) |
 | `@djangocfg/ui-core/lib` | Utilities (cn, etc.) |
 | `@djangocfg/ui-core/lib/dialog-service` | Dialog service |
 | `@djangocfg/ui-core/utils` | Runtime utilities (emitRuntimeError) |
@@ -311,18 +399,31 @@ try {
 }
 ```
 
+## Links
+
+`<Link>` and `<ButtonLink>` ship in `ui-core` itself — no Next.js required.
+Default behavior renders `<a>` and routes clicks through `useNavigate`.
+
+In Next.js apps, mount `NextLinkProvider` (from `@djangocfg/ui-core/adapters/nextjs`)
+near the root and the same components delegate to `next/link` automatically.
+`@djangocfg/layouts/BaseApp` does this for you.
+
+```tsx
+import { Link, ButtonLink } from '@djangocfg/ui-core/components';
+
+<Link href="/about">About</Link>
+<ButtonLink href="/docs" variant="outline">Docs</ButtonLink>
+```
+
 ## What's NOT included (use ui-nextjs)
 
 These features require Next.js or browser storage APIs:
 
-- `Sidebar` — uses next/link
-- `Breadcrumb`, `BreadcrumbNavigation` — uses next/link
-- `NavigationMenu`, `Menubar` — uses next/link
-- `Pagination`, `SSRPagination` — uses next/link
-- `DropdownMenu` — uses next/link
+- `Sidebar` — `'use client'` heavy, lives in ui-nextjs
+- `Breadcrumb`, `BreadcrumbNavigation` — same
+- `Pagination`, `SSRPagination` — same
 - `DownloadButton` — uses localStorage
 - `useTheme` — uses next-themes
-- `useQueryParams`, `useCfgRouter` — uses next/router
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.293",
+  "version": "2.1.297",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -48,6 +48,11 @@
       "import": "./src/hooks/index.ts",
       "require": "./src/hooks/index.ts"
     },
+    "./adapters/nextjs": {
+      "types": "./src/hooks/router/adapters/nextjs.tsx",
+      "import": "./src/hooks/router/adapters/nextjs.tsx",
+      "require": "./src/hooks/router/adapters/nextjs.tsx"
+    },
     "./lib": {
       "types": "./src/lib/index.ts",
       "import": "./src/lib/index.ts",
@@ -86,10 +91,11 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.293",
+    "@djangocfg/i18n": "^2.1.297",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
+    "next": ">=14.0.0",
     "react": "^19.1.0",
     "react-device-detect": "^2.2.3",
     "react-dom": "^19.1.0",
@@ -98,6 +104,11 @@
     "zod": "^4.3.6",
     "zustand": "^5.0.0"
   },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",
     "@radix-ui/react-accordion": "^1.2.12",
@@ -148,13 +159,14 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.293",
+    "@djangocfg/i18n": "^2.1.297",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.293",
+    "@djangocfg/typescript-config": "^2.1.297",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",
     "lucide-react": "^0.545.0",
+    "next": "^16.2.4",
     "typescript": "^5.9.3"
   },
   "publishConfig": {

package/src/components/feedback/sonner/index.tsx

@@ -1,7 +1,7 @@
 "use client"
 
 import { Toaster as Sonner } from 'sonner';
-import { useResolvedTheme } from '../../../hooks/useResolvedTheme';
+import { useResolvedTheme } from '../../../hooks';
 
 type ToasterProps = React.ComponentProps<typeof Sonner>
 

package/src/components/forms/button/index.tsx

@@ -7,6 +7,7 @@ import * as React from 'react';
 import { Slot } from '@radix-ui/react-slot';
 
 import { cn } from '../../../lib/utils';
+import { Link } from '../../navigation/link';
 
 const buttonVariants = cva(
   "inline-flex cursor-pointer items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-semibold transition-colors focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:size-4 [&_svg]:shrink-0",
@@ -101,24 +102,39 @@ const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
 )
 Button.displayName = "Button"
 
-// ButtonLink using native anchor tag (no Next.js dependency)
+/**
+ * ButtonLink — anchor styled as a Button.
+ *
+ * Renders the framework-agnostic `<Link>` underneath, so SPA navigation,
+ * cmd-click, and the Next.js adapter (if mounted) all work out of the box.
+ * Drop-in replacement for the previous native-`<a>` version.
+ */
 export interface ButtonLinkProps
-  extends React.AnchorHTMLAttributes<HTMLAnchorElement>,
+  extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'href'>,
     VariantProps<typeof buttonVariants> {
   href: string
+  /** Use replaceState instead of pushState. Default: false. */
+  replace?: boolean
+  /** Scroll to top after SPA navigation. Default: false. */
+  scroll?: boolean
+  /** Hint for the host framework's prefetcher (Next.js). */
+  prefetch?: boolean | null
 }
 
 const ButtonLink = React.forwardRef<HTMLAnchorElement, ButtonLinkProps>(
-  ({ className, variant, size, href, children, ...props }, ref) => {
+  ({ className, variant, size, href, replace, scroll, prefetch, children, ...props }, ref) => {
     return (
-      <a
+      <Link
         href={href}
+        replace={replace}
+        scroll={scroll}
+        prefetch={prefetch}
         className={cn(buttonVariants({ variant, size, className }))}
         ref={ref}
         {...props}
       >
         {children}
-      </a>
+      </Link>
     )
   }
 )

package/src/components/forms/button-download/index.tsx

@@ -5,7 +5,7 @@ import * as React from 'react';
 
 import { Button, type ButtonProps } from '../../forms/button';
 import { cn } from '../../../lib';
-import { useLocalStorage } from '../../../hooks/useLocalStorage';
+import { useLocalStorage } from '../../../hooks';
 
 // Token key used by the API client
 const TOKEN_KEY = "auth_token"

package/src/components/forms/input/index.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 
-import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../../hooks/useStoredValue';
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../../hooks';
 import { cn } from '../../../lib/utils';
 
 export interface InputProps extends React.ComponentProps<"input"> {

package/src/components/forms/otp/index.tsx

@@ -5,7 +5,7 @@ import * as React from 'react';
 
 import { InputOTP, InputOTPGroup, InputOTPSlot } from '../input-otp';
 import { cn } from '../../../lib';
-import { useIsMobile } from '../../../hooks/useMobile';
+import { useIsMobile } from '../../../hooks';
 
 import { createPasteHandler, useSmartOTP } from './use-otp-input';
 

package/src/components/forms/slider/index.tsx

@@ -4,7 +4,7 @@ import * as React from 'react';
 
 import * as SliderPrimitive from '@radix-ui/react-slider';
 
-import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../../hooks/useStoredValue';
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../../hooks';
 import { cn } from '../../../lib/utils';
 
 export interface SliderProps extends React.ComponentPropsWithoutRef<typeof SliderPrimitive.Root> {

package/src/components/forms/textarea/index.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 
-import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../../hooks/useStoredValue';
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../../hooks';
 import { cn } from '../../../lib/utils';
 
 export interface TextareaProps extends React.ComponentProps<"textarea"> {

package/src/components/index.ts

@@ -60,6 +60,8 @@ export { Tabs, TabsContent, TabsList, TabsTrigger } from './navigation/tabs';
 export { Accordion, AccordionContent, AccordionItem, AccordionTrigger } from './navigation/accordion';
 export { Collapsible, CollapsibleContent, CollapsibleTrigger } from './navigation/collapsible';
 export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut } from './navigation/command';
+export { Link, LinkProvider, LinkComponentContext, useLinkComponent } from './navigation/link';
+export type { LinkProps, LinkComponent, LinkComponentProps, LinkProviderProps } from './navigation/link';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Layout

package/src/components/layout/sticky/index.tsx

@@ -35,7 +35,7 @@
 import * as React from 'react';
 import StickyBox from 'react-sticky-box';
 
-import { useIsMobile } from '../../../hooks/useMobile';
+import { useIsMobile } from '../../../hooks';
 
 export interface StickyProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Stick to bottom instead of top */

package/src/components/navigation/accordion/index.tsx

@@ -5,7 +5,7 @@ import * as React from 'react';
 import * as AccordionPrimitive from '@radix-ui/react-accordion';
 import { ChevronDownIcon } from '@radix-ui/react-icons';
 
-import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../../hooks/useStoredValue';
+import { useStoredValue, type StorageType, type UseStoredValueOptions } from '../../../hooks';
 import { cn } from '../../../lib/utils';
 
 type AccordionSingleProps = React.ComponentPropsWithoutRef<typeof AccordionPrimitive.Root> & {

package/src/components/navigation/dropdown-menu/index.tsx

@@ -5,6 +5,7 @@ import * as React from 'react';
 
 import { cn } from '../../../lib';
 import * as DropdownMenuPrimitive from '@radix-ui/react-dropdown-menu';
+import { Link } from '../link';
 
 const DropdownMenu = DropdownMenuPrimitive.Root
 
@@ -92,9 +93,9 @@ const DropdownMenuItem = React.forwardRef<
   if (href) {
     return (
       <DropdownMenuPrimitive.Item asChild ref={ref} {...props}>
-        <a href={href} className={classes}>
+        <Link href={href} className={classes}>
           {children}
-        </a>
+        </Link>
       </DropdownMenuPrimitive.Item>
     )
   }

package/src/components/navigation/link/Link.tsx

@@ -0,0 +1,124 @@
+'use client';
+
+/**
+ * <Link> — framework-agnostic link component.
+ *
+ * WHY:
+ *   We want a single Link import everywhere, regardless of whether the
+ *   host app is Next.js, Wails, Electron, Vite, or plain CRA. When a
+ *   framework adapter is mounted (e.g. NextLinkProvider) the native
+ *   component handles prefetch / locale / RSC wiring. Otherwise we
+ *   render a plain <a> and route clicks through the active router
+ *   adapter (which itself defaults to History API).
+ *
+ *   Behavior parity with `<a>`:
+ *     - Cmd/Ctrl/Shift+click and middle-click open a new tab natively
+ *       (we let the browser handle modifier clicks — DON'T preventDefault).
+ *     - External / non-internal hrefs (http://, mailto:, tel:, target=_blank)
+ *       skip SPA nav entirely and behave as the browser would.
+ *
+ * @example
+ *   import { Link } from '@djangocfg/ui-core/components';
+ *   <Link href="/dashboard">Dashboard</Link>
+ *   <Link href="/dashboard" replace scroll>Reset</Link>
+ *   <Link href="https://example.com" target="_blank" rel="noopener noreferrer">External</Link>
+ */
+
+import { forwardRef, useCallback, type AnchorHTMLAttributes, type MouseEvent, type ReactNode } from 'react';
+import { useNavigate } from '../../../hooks/router/useNavigate';
+import { useLinkComponent } from './LinkContext';
+
+type AnchorProps = Omit<
+  AnchorHTMLAttributes<HTMLAnchorElement>,
+  'href' | 'onClick'
+>;
+
+export interface LinkProps extends AnchorProps {
+  href: string;
+  /** Use replaceState instead of pushState. Default: false. */
+  replace?: boolean;
+  /** Scroll to top after SPA navigation. Default: false. */
+  scroll?: boolean;
+  /**
+   * Hint for the host framework's prefetcher (Next.js).
+   * Ignored by the agnostic fallback.
+   */
+  prefetch?: boolean | null;
+  children?: ReactNode;
+  onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+}
+
+/** True for protocols / schemes the browser must handle natively. */
+function isExternalHref(href: string): boolean {
+  // Allow same-origin absolute paths (`/foo`, `./foo`, `#hash`, `?q=1`).
+  if (href.startsWith('/') && !href.startsWith('//')) return false;
+  if (href.startsWith('#') || href.startsWith('?')) return false;
+  // Anything with a scheme (http:, https:, mailto:, tel:, ipfs:, …).
+  if (/^[a-z][a-z0-9+.-]*:/i.test(href)) return true;
+  // `//example.com` protocol-relative.
+  if (href.startsWith('//')) return true;
+  return false;
+}
+
+/**
+ * True when the click should be left to the browser:
+ * modifier keys, non-primary mouse button, or `target=_blank`.
+ */
+function shouldBypassClick(event: MouseEvent<HTMLAnchorElement>, target?: string): boolean {
+  if (event.defaultPrevented) return true;
+  if (event.button !== 0) return true;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return true;
+  if (target && target !== '' && target !== '_self') return true;
+  return false;
+}
+
+export const Link = forwardRef<HTMLAnchorElement, LinkProps>(function Link(
+  { href, replace, scroll, prefetch, target, rel, onClick, children, ...rest },
+  ref
+) {
+  const Adapter = useLinkComponent();
+  const { navigate } = useNavigate();
+
+  const handleClick = useCallback(
+    (event: MouseEvent<HTMLAnchorElement>) => {
+      onClick?.(event);
+      if (event.defaultPrevented) return;
+      if (isExternalHref(href)) return;
+      if (shouldBypassClick(event, target)) return;
+      event.preventDefault();
+      navigate(href, { replace, scroll });
+    },
+    [onClick, href, target, navigate, replace, scroll]
+  );
+
+  if (Adapter) {
+    return (
+      <Adapter
+        href={href}
+        replace={replace}
+        scroll={scroll}
+        prefetch={prefetch}
+        target={target}
+        rel={rel}
+        ref={ref}
+        onClick={onClick}
+        {...rest}
+      >
+        {children}
+      </Adapter>
+    );
+  }
+
+  return (
+    <a
+      href={href}
+      target={target}
+      rel={rel}
+      ref={ref}
+      onClick={handleClick}
+      {...rest}
+    >
+      {children}
+    </a>
+  );
+});

package/src/components/navigation/link/LinkContext.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+/**
+ * LinkContext
+ *
+ * Adapter slot for the framework's native link component (e.g. `next/link`).
+ * `<Link>` reads this context: when populated, it delegates rendering so
+ * the host framework's prefetching / locale handling kicks in. When empty,
+ * `<Link>` falls back to a pure `<a>` driven by `useNavigate`.
+ *
+ * Mount once near the root via the matching adapter
+ * (e.g. `NextLinkProvider` from `@djangocfg/ui-core/adapters/nextjs`).
+ */
+
+import { createContext, useContext, type ComponentType, type ReactNode, type Ref } from 'react';
+
+export interface LinkComponentProps {
+  href: string;
+  replace?: boolean;
+  scroll?: boolean;
+  prefetch?: boolean | null;
+  className?: string;
+  children?: ReactNode;
+  target?: string;
+  rel?: string;
+  ref?: Ref<HTMLAnchorElement>;
+  onClick?: (event: React.MouseEvent<HTMLAnchorElement>) => void;
+  [dataAttr: `data-${string}`]: unknown;
+  [ariaAttr: `aria-${string}`]: unknown;
+}
+
+export type LinkComponent = ComponentType<LinkComponentProps>;
+
+export const LinkComponentContext = createContext<LinkComponent | null>(null);
+
+export interface LinkProviderProps {
+  value: LinkComponent;
+  children: ReactNode;
+}
+
+export function LinkProvider({ value, children }: LinkProviderProps) {
+  return (
+    <LinkComponentContext.Provider value={value}>
+      {children}
+    </LinkComponentContext.Provider>
+  );
+}
+
+/** Returns the host-framework Link if a provider is mounted, else `null`. */
+export function useLinkComponent(): LinkComponent | null {
+  return useContext(LinkComponentContext);
+}

package/src/components/navigation/link/index.ts

@@ -0,0 +1,8 @@
+export { Link } from './Link';
+export type { LinkProps } from './Link';
+export {
+  LinkComponentContext,
+  LinkProvider,
+  useLinkComponent,
+} from './LinkContext';
+export type { LinkComponent, LinkComponentProps, LinkProviderProps } from './LinkContext';

package/src/components/navigation/menubar/index.tsx

@@ -5,6 +5,7 @@ import * as React from 'react';
 
 import { cn } from '../../../lib';
 import * as MenubarPrimitive from '@radix-ui/react-menubar';
+import { Link } from '../link';
 
 function MenubarMenu({
   ...props
@@ -144,9 +145,9 @@ const MenubarItem = React.forwardRef<
   if (href) {
     return (
       <MenubarPrimitive.Item asChild ref={ref} {...props}>
-        <a href={href} className={classes}>
+        <Link href={href} className={classes}>
           {children}
-        </a>
+        </Link>
       </MenubarPrimitive.Item>
     )
   }

package/src/components/navigation/navigation-menu/index.tsx

@@ -6,6 +6,7 @@ import * as React from 'react';
 
 import { cn } from '../../../lib';
 import * as NavigationMenuPrimitive from '@radix-ui/react-navigation-menu';
+import { Link } from '../link';
 
 const NavigationMenu = React.forwardRef<
   React.ElementRef<typeof NavigationMenuPrimitive.Root>,
@@ -88,7 +89,7 @@ const NavigationMenuLink = React.forwardRef<
   if (href) {
     return (
       <NavigationMenuPrimitive.Link asChild ref={ref} {...props}>
-        <a href={href}>{children}</a>
+        <Link href={href}>{children}</Link>
       </NavigationMenuPrimitive.Link>
     )
   }

package/src/components/navigation/tabs/index.tsx

@@ -6,7 +6,7 @@ import * as React from 'react';
 import * as TabsPrimitive from '@radix-ui/react-tabs';
 
 import { useIsMobile } from '../../../hooks';
-import { useStoredValue, type StorageType } from '../../../hooks/useStoredValue';
+import { useStoredValue, type StorageType } from '../../../hooks';
 import { useAppT } from '@djangocfg/i18n';
 import { cn } from '../../../lib/utils';
 import { Button } from '../../forms/button';

package/src/components/overlay/responsive-sheet/index.tsx

@@ -9,7 +9,7 @@
 
 import * as React from 'react';
 
-import { useIsMobile } from '../../../hooks/useMobile';
+import { useIsMobile } from '../../../hooks';
 
 import {
   Dialog,