feat: new navigation api * 2

Author: tenphi

src/components/actions/Link/Link.docs.mdx

@@ -128,7 +128,7 @@ Notes:
 ```
 
 Behavior:
-- Uses `navigate(delta)` from the navigation adapter
+- Uses `navigate(delta)` from the navigation adapter with overload signature
 - The default adapter calls `window.history.go(delta)`
 
 ---
@@ -140,21 +140,27 @@ Behavior:
 ### Interface
 
 ```ts
+type NavigateLike = {
+  (to: To, options?: NavigateOptions): void;
+  (delta: number): void;
+};
+
 interface NavigationAdapter {
   useHref: (to: To, opts?: { relative?: 'route' | 'path' }) => string;
-  useNavigate: () => (to: To | number, opts?: NavigateOptions) => void;
+  useNavigate: () => NavigateLike;
 }
 ```
 
 ### React Router v6+ (Recommended)
 
-React Router hooks are directly compatible with our `NavigationAdapter` interface:
+React Router v6+ hooks are directly compatible with our `NavigationAdapter` interface:
 
 ```jsx
 import { Root } from '@cube-dev/ui-kit';
 import { useHref, useNavigate } from 'react-router-dom';
 
 const navigation = { useHref, useNavigate };
+// React Router's useNavigate supports both overloads: navigate(to, options) and navigate(delta)
 
 export function App() {
   return (
@@ -179,13 +185,15 @@ function MyRouterAdapter() {
       return typeof to === 'string' ? to : `${to.pathname || ''}${to.search || ''}${to.hash || ''}`;
     },
     useNavigate: () => {
-      return (to, options) => {
+      // Return function with overload signatures
+      const navigate = (to, options) => {
         if (typeof to === 'number') {
           window.history.go(to);
         } else {
           myRouter.navigate(to, options);
         }
       };
+      return navigate;
     },
   };
 }

src/components/actions/use-action.ts

@@ -23,6 +23,7 @@ const BUTTON_PRESS_EVENT = 'Button Press';
 
 // Re-export types for convenience
 export type {
+  NavigateLike,
   Path,
   To,
   NavigateArg,
@@ -196,7 +197,7 @@ export function performClickHandler(
   }
 
   // Handle new tab (via ! prefix or user modifiers)
-  if (evt.shiftKey || evt.metaKey || newTab) {
+  if (evt.shiftKey || evt.metaKey || (evt as any).ctrlKey || newTab) {
     openLink(resolvedHref, true);
     tracking.event(
       LINK_PRESS_EVENT,
@@ -263,11 +264,6 @@ export const useAction = function useAction(
   const navigation = useContext(UIKitContext).navigation;
   const isDisabled = props.isDisabled;
 
-  // Always call navigation hooks (using fallback when to is not provided)
-  const fallbackTo = to || '.';
-  const navigate = navigation.useNavigate();
-  const resolvedHref = navigation.useHref(fallbackTo);
-
   const {
     newTab,
     nativeRoute,
@@ -277,6 +273,13 @@ export const useAction = function useAction(
     isExternal,
   } = parseTo(to);
 
+  // Always call navigation hooks (using fallback when to is not provided)
+  const fallbackTo = to || '.';
+  const navigate = navigation.useNavigate();
+  const resolvedHref = navigation.useHref(fallbackTo);
+  // Always resolve cleanTo href to avoid conditional hook calls
+  const cleanToHref = navigation.useHref(cleanTo || '.');
+
   // Determine element type: 'a' for navigation, 'button' for actions
   as = to && !isHistoryNavigation ? 'a' : as || 'button';
 
@@ -291,7 +294,7 @@ export const useAction = function useAction(
       href =
         typeof cleanTo === 'string' && isExternal
           ? cleanTo // External URLs as-is
-          : navigation.useHref(cleanTo);
+          : cleanToHref;
     } else {
       // Regular navigation
       href = resolvedHref;

src/index.ts

@@ -37,6 +37,7 @@ export type { CubeRootProps } from './components/Root';
 // Navigation types and helpers
 export type {
   NavigationAdapter,
+  NavigateLike,
   Path,
   To,
   NavigateArg,

src/providers/navigation.types.ts

@@ -16,8 +16,14 @@ export interface NavigateOptions {
   preventScrollReset?: boolean;
 }
 
+// Overload-style type (NOT a union in the first arg)
+export type NavigateLike = {
+  (to: To, options?: NavigateOptions): void;
+  (delta: number): void;
+};
+
 export interface NavigationAdapter {
   // React Router compatible hook signatures
   useHref: (to: To, options?: { relative?: RelativeRoutingType }) => string;
-  useNavigate: () => (to: To | number, options?: NavigateOptions) => void;
+  useNavigate: () => NavigateLike;
 }

src/providers/navigationAdapter.default.ts

@@ -1,4 +1,5 @@
 import {
+  NavigateLike,
   NavigateOptions,
   NavigationAdapter,
   Path,
@@ -31,7 +32,7 @@ export const defaultNavigationAdapter: NavigationAdapter = {
   },
 
   useNavigate: () => {
-    return (to: To | number, options?: NavigateOptions) => {
+    const navigate: NavigateLike = (to: any, options?: NavigateOptions) => {
       // Handle history navigation (numbers)
       if (typeof to === 'number') {
         if (typeof window !== 'undefined') {
@@ -51,5 +52,6 @@ export const defaultNavigationAdapter: NavigationAdapter = {
         }
       }
     };
+    return navigate;
   },
 };