@nocobase/client-v2 2.2.0-beta.8 → 2.2.0

package/lib/locale/languageCodes.js

@@ -64,6 +64,7 @@ const languageCodes = {
   "ml-IN": { label: "\u0D2E\u0D32\u0D2F\u0D3E\u0D33\u0D02" },
   "mn-MN": { label: "\u041C\u043E\u043D\u0433\u043E\u043B \u0445\u044D\u043B" },
   "ms-MY": { label: "\u0628\u0647\u0627\u0633 \u0645\u0644\u0627\u064A\u0648" },
+  "my-MM": { label: "\u1019\u103C\u1014\u103A\u1019\u102C\u1018\u102C\u101E\u102C" },
   "nb-NO": { label: "Norsk bokm\xE5l" },
   "ne-NP": { label: "\u0928\u0947\u092A\u093E\u0932\u0940" },
   "nl-BE": { label: "Vlaams" },
@@ -83,7 +84,8 @@ const languageCodes = {
   "tk-TK": { label: "Turkmen" },
   "tr-TR": { label: "T\xFCrk\xE7e" },
   "uk-UA": { label: "\u0423\u043A\u0440\u0430\u0457\u043D\u0441\u044C\u043A\u0430" },
-  "ur-PK": { label: "O\u02BBzbekcha" },
+  "ur-PK": { label: "\u0627\u0631\u062F\u0648" },
+  "uz-UZ": { label: "O\u02BBzbekcha" },
   "vi-VN": { label: "Ti\u1EBFng Vi\u1EC7t" },
   "zh-CN": { label: "\u7B80\u4F53\u4E2D\u6587" },
   "zh-HK": { label: "\u7E41\u9AD4\u4E2D\u6587\uFF08\u9999\u6E2F\uFF09" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nocobase/client-v2",
-  "version": "2.2.0-beta.8",
+  "version": "2.2.0",
   "license": "Apache-2.0",
   "main": "lib/index.js",
   "module": "es/index.mjs",
@@ -27,11 +27,11 @@
     "@formily/antd-v5": "1.2.3",
     "@formily/react": "^2.2.27",
     "@formily/shared": "^2.2.27",
-    "@nocobase/evaluators": "2.2.0-beta.8",
-    "@nocobase/flow-engine": "2.2.0-beta.8",
-    "@nocobase/sdk": "2.2.0-beta.8",
-    "@nocobase/shared": "2.2.0-beta.8",
-    "@nocobase/utils": "2.2.0-beta.8",
+    "@nocobase/evaluators": "2.2.0",
+    "@nocobase/flow-engine": "2.2.0",
+    "@nocobase/sdk": "2.2.0",
+    "@nocobase/shared": "2.2.0",
+    "@nocobase/utils": "2.2.0",
     "ahooks": "^3.7.2",
     "antd": "5.24.2",
     "antd-style": "3.7.1",
@@ -42,9 +42,11 @@
     "html5-qrcode": "^2.3.8",
     "i18next": "^22.4.9",
     "json5": "^2.2.3",
+    "jsqr": "^1.4.0",
     "lodash": "4.17.21",
+    "react-device-detect": "2.2.3",
     "react-i18next": "^11.15.1",
     "react-router-dom": "^6.30.1"
   },
-  "gitHead": "fa2502c1e9faf6d74b3f51b42dbc6546638d46af"
+  "gitHead": "d5052cae37177054c236f1bf7bba3aed6ef029d0"
 }

package/src/APIClient.ts

@@ -7,7 +7,69 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
-import { APIClient as APIClientSDK, type APIClientOptions, hasHeaderValue } from '@nocobase/sdk';
+import { APIClient as APIClientSDK, hasHeaderValue } from '@nocobase/sdk';
+import type { NotificationInstance } from 'antd/es/notification/interface';
+import type { AxiosRequestConfig } from 'axios';
+import React from 'react';
+
+type ResponseMessage = string | { message?: unknown };
+
+interface APIClientApplication {
+  getName?: () => string | undefined;
+  context?: {
+    notification?: NotificationInstance;
+  };
+}
+
+interface NotificationError {
+  config?: AxiosRequestConfig & {
+    skipNotify?: boolean | ((error: unknown) => boolean);
+  };
+}
+
+const notificationCache = new Map<string, number>();
+
+function getMessageText(item: ResponseMessage): string {
+  if (typeof item === 'string') {
+    return item;
+  }
+  return typeof item?.message === 'string' ? item.message : '';
+}
+
+function deduplicateMessages(messages: ResponseMessage[]): ResponseMessage[] {
+  if (notificationCache.size > 10) {
+    notificationCache.clear();
+  }
+  const now = Date.now();
+  return messages.filter((item) => {
+    const message = getMessageText(item);
+    if (!message) {
+      return false;
+    }
+    const lastTime = notificationCache.get(message);
+    if (lastTime && now - lastTime < 500) {
+      return false;
+    }
+    notificationCache.set(message, now);
+    return true;
+  });
+}
+
+function notify(type: 'success' | 'error', messages: ResponseMessage[], instance?: NotificationInstance) {
+  if (!instance || messages.length === 0) {
+    return;
+  }
+  const filteredMessages = deduplicateMessages(messages);
+  if (filteredMessages.length === 0) {
+    return;
+  }
+  instance[type]({
+    message: filteredMessages.map((item, index) => {
+      const message = getMessageText(item);
+      return React.createElement('div', { key: `${index}_${message}` }, message);
+    }),
+  });
+}
 
 function offsetToTimeZone(offset: number) {
   const hours = Math.floor(Math.abs(offset));
@@ -23,13 +85,10 @@ function getCurrentTimezone() {
 }
 
 export class APIClient extends APIClientSDK {
-  appName?: string;
+  app?: APIClientApplication;
 
-  constructor(options?: APIClientOptions) {
-    super(options);
-    if (options && typeof options !== 'function') {
-      this.appName = options.appName;
-    }
+  get notification() {
+    return this.app?.context?.notification;
   }
 
   getHostname() {
@@ -64,5 +123,29 @@ export class APIClient extends APIClientSDK {
       return config;
     });
     super.interceptors();
+    this.useNotificationMiddleware();
+  }
+
+  handleNotificationError(error: unknown) {
+    const notificationError = error as NotificationError;
+    const skipNotify = notificationError.config?.skipNotify;
+    if (skipNotify && (skipNotify === true || (typeof skipNotify === 'function' && skipNotify(error)))) {
+      throw error;
+    }
+    const messages = this.toErrMessages(error);
+    if (Array.isArray(messages)) {
+      notify('error', messages, this.notification);
+    }
+    throw error;
+  }
+
+  useNotificationMiddleware() {
+    this.axios.interceptors.response.use((response) => {
+      const messages = response.data?.messages;
+      if (Array.isArray(messages)) {
+        notify('success', messages, this.notification);
+      }
+      return response;
+    }, this.handleNotificationError.bind(this));
   }
 }

package/src/Application.tsx

@@ -45,10 +45,16 @@ export class Application extends BaseApplication<
   public hasLoadError = false;
 
   protected createApiClient(options: ApplicationOptions) {
-    return new APIClient({
+    const apiClient = new APIClient({
+      // Cross-origin API deployments rely on cookies for auth (e.g. permanent file
+      // URLs); trust is enforced server-side via the CORS origin whitelist and the
+      // CSRF middleware, not by omitting credentials.
+      withCredentials: true,
       ...options.apiClient,
       appName: options.name || getSubAppName(options.publicPath),
     });
+    apiClient.app = this;
+    return apiClient;
   }
 
   protected configureRuntimeAdapters() {

package/src/BaseApplication.tsx

@@ -30,10 +30,12 @@ import AntdAppProvider from './theme/AntdAppProvider';
 import { GlobalThemeProvider } from './theme';
 import { AIManager } from './ai';
 import { AppError, AppMaintaining, AppMaintainingDialog, AppNotFound, AppSpin, BlankComponent } from './components';
+import { EntryActionManager } from './entry-actions';
 import { SystemSettingsSource } from './flow/system-settings';
 import { LayoutManager } from './layout-manager/LayoutManager';
 import type { PluginClass, PluginManager, PluginType } from './PluginManager';
 import { RouteRepository } from './RouteRepository';
+import { stripModernClientPrefix } from './authRedirect';
 import type {
   ComponentTypeAndString,
   RenderableComponentType,
@@ -80,6 +82,10 @@ const trimTrailingSlashes = (value: string) => {
   return match ? value.slice(0, -match[0].length) : value;
 };
 
+const ensureTrailingSlash = (value: string) => {
+  return `${trimTrailingSlashes(value)}/`;
+};
+
 const isRenderableComponentType = (value: unknown): value is AnyComponent => isValidElementType(value);
 
 export type DevDynamicImport = (packageName: string) => Promise<{ default: PluginClass }>;
@@ -126,6 +132,7 @@ export abstract class BaseApplication<
   public pluginManager: TPluginManager;
   public pluginSettingsManager: TPluginSettingsManager;
   public layoutManager: LayoutManager<this>;
+  public entryActionManager = new EntryActionManager();
   public aiManager!: AIManager;
   public devDynamicImport?: DevDynamicImport;
   public requirejs!: RequireJS;
@@ -396,7 +403,7 @@ export abstract class BaseApplication<
       this.favicon = favicon || '';
     }
 
-    const iconHref = this.favicon || '/favicon/favicon.ico';
+    const iconHref = this.favicon || this.getCdnUrl() + 'favicon/favicon.ico';
 
     if (faviconLinkElement) {
       faviconLinkElement.href = iconHref;
@@ -431,12 +438,12 @@ export abstract class BaseApplication<
     return getSubAppName(this.getPublicPath()) || null;
   }
 
+  getCdnUrl() {
+    return ensureTrailingSlash(window['__webpack_public_path__'] || stripModernClientPrefix(this.getPublicPath()));
+  }
+
   getPublicPath() {
-    let publicPath = this.options.publicPath || '/';
-    if (!publicPath.endsWith('/')) {
-      publicPath += '/';
-    }
-    return publicPath;
+    return ensureTrailingSlash(this.options.publicPath || '/');
   }
 
   getApiUrl(pathname = '') {

package/src/RouteRepository.ts

@@ -268,6 +268,16 @@ export class RouteRepository {
     return this.findRoute(this.listAccessible(), schemaUid);
   }
 
+  /**
+   * 通过路由 id 反查对应路由节点。
+   *
+   * @param routeId 桌面路由主键
+   * @returns 匹配到的路由节点
+   */
+  getRouteById(routeId: string | number): NocoBaseDesktopRoute | undefined {
+    return this.findRouteById(this.listAccessible(), routeId);
+  }
+
   protected getAPIClient(): APIClient {
     if (!this.ctx?.api) {
       throw new Error('[NocoBase] RouteRepository requires context.api.');
@@ -346,4 +356,19 @@ export class RouteRepository {
     }
     return undefined;
   }
+
+  private findRouteById(routes: NocoBaseDesktopRoute[], routeId: string | number): NocoBaseDesktopRoute | undefined {
+    for (const route of routes) {
+      if (route.id != null && String(route.id) === String(routeId)) {
+        return route;
+      }
+      if (route.children) {
+        const found = this.findRouteById(route.children, routeId);
+        if (found) {
+          return found;
+        }
+      }
+    }
+    return undefined;
+  }
 }

package/src/RouterManager.tsx

@@ -26,6 +26,7 @@ import type { BaseApplication } from './BaseApplication';
 import { BlankComponent, RouterContextCleaner } from './components';
 import { RouterBridge } from './components/RouterBridge';
 import { Router } from '@remix-run/router';
+import { getV2EffectiveBasePath } from './authRedirect';
 
 export interface BrowserRouterOptions extends Omit<BrowserRouterProps, 'children'> {
   type?: 'browser';
@@ -55,6 +56,87 @@ export interface RouteType extends Omit<RouteObject, 'children' | 'Component'> {
 export type RenderComponentType = (Component: ComponentTypeAndString, props?: any) => React.ReactNode;
 export type RouterComponentType = React.FC<{ BaseLayout?: ComponentType }>;
 
+const DEFAULT_ADMIN_ROUTE_PATH = '/admin';
+
+type AdminRouteNavigationTarget = {
+  currentPathname?: string;
+  targetPathname: unknown;
+  basePath?: string;
+  adminRoutePath?: string;
+  replace?: boolean;
+};
+
+function trimPathSearchAndHash(pathname: string) {
+  return pathname.split(/[?#]/)[0];
+}
+
+function splitPathSearchAndHash(pathname: string) {
+  const match = pathname.match(/^([^?#]*)(.*)$/);
+  return {
+    pathname: match?.[1] || '',
+    suffix: match?.[2] || '',
+  };
+}
+
+function normalizeRootPath(pathname?: string) {
+  const trimmed = trimPathSearchAndHash(pathname || '').trim();
+  if (!trimmed || trimmed === '/') {
+    return '/';
+  }
+  return `/${trimmed.replace(/^\/+|\/+$/g, '')}`;
+}
+
+function isRootRelativePath(pathname: string) {
+  return pathname.startsWith('/') && !pathname.startsWith('//') && !pathname.startsWith('/\\');
+}
+
+function removeBasePath(pathname: string, basePath?: string) {
+  const normalizedPathname = normalizeRootPath(pathname);
+  const normalizedBasePath = normalizeRootPath(basePath);
+
+  if (normalizedBasePath === '/') {
+    return normalizedPathname;
+  }
+  if (normalizedPathname === normalizedBasePath) {
+    return '/';
+  }
+  if (normalizedPathname.startsWith(`${normalizedBasePath}/`)) {
+    return normalizeRootPath(normalizedPathname.slice(normalizedBasePath.length));
+  }
+  return normalizedPathname;
+}
+
+function removeAppSegment(pathname: string) {
+  return normalizeRootPath(pathname).replace(/^\/(?:apps|_app)\/[^/]+(?=\/|$)/, '') || '/';
+}
+
+function normalizePortalRoutePath(pathname: string, basePath?: string) {
+  return removeAppSegment(removeBasePath(pathname, basePath));
+}
+
+function isSameOrChildPath(pathname: string, basePath: string) {
+  const normalizedPathname = normalizeRootPath(pathname);
+  const normalizedBasePath = normalizeRootPath(basePath);
+  return normalizedPathname === normalizedBasePath || normalizedPathname.startsWith(`${normalizedBasePath}/`);
+}
+
+export function shouldOpenAdminRouteInNewWindow(options: AdminRouteNavigationTarget) {
+  if (options.replace || typeof options.targetPathname !== 'string') {
+    return false;
+  }
+
+  const targetPathname = options.targetPathname.trim();
+  if (!isRootRelativePath(targetPathname)) {
+    return false;
+  }
+
+  const adminRoutePath = normalizeRootPath(options.adminRoutePath || DEFAULT_ADMIN_ROUTE_PATH);
+  const currentRoutePath = normalizePortalRoutePath(options.currentPathname || '/', options.basePath);
+  const targetRoutePath = normalizePortalRoutePath(targetPathname, options.basePath);
+
+  return !isSameOrChildPath(currentRoutePath, adminRoutePath) && isSameOrChildPath(targetRoutePath, adminRoutePath);
+}
+
 function removeBasename(pathname: string, basename?: string) {
   if (!basename || basename === '/') {
     return pathname;
@@ -72,6 +154,7 @@ function removeBasename(pathname: string, basename?: string) {
 export class RouterManager<TApp extends BaseApplication<any> = BaseApplication<any>> {
   protected routes: Record<string, RouteType> = {};
   protected options: RouterOptions;
+  private routerNavigate?: Router['navigate'];
   public app: TApp;
   public router!: Router;
   get basename() {
@@ -81,7 +164,7 @@ export class RouterManager<TApp extends BaseApplication<any> = BaseApplication<a
     return this.router.state;
   }
   get navigate() {
-    return this.router.navigate;
+    return this.navigateWithPortalPolicy;
   }
 
   constructor(options: RouterOptions = {}, app: TApp) {
@@ -90,6 +173,62 @@ export class RouterManager<TApp extends BaseApplication<any> = BaseApplication<a
     this.routes = options.routes || {};
   }
 
+  private navigateWithPortalPolicy: Router['navigate'] = ((to, opts) => {
+    if (this.shouldOpenAdminRouteInNewWindow(to, opts)) {
+      window.open(this.getAdminRouteNavigationHref(to as string), '_blank', 'noopener,noreferrer');
+      return Promise.resolve();
+    }
+
+    const navigate = this.routerNavigate || this.router.navigate.bind(this.router);
+    return navigate(to, opts);
+  }) as Router['navigate'];
+
+  private shouldOpenAdminRouteInNewWindow(
+    to: Parameters<Router['navigate']>[0],
+    opts?: Parameters<Router['navigate']>[1],
+  ) {
+    if (this.options.type && this.options.type !== 'browser') {
+      return false;
+    }
+
+    return shouldOpenAdminRouteInNewWindow({
+      currentPathname:
+        typeof window !== 'undefined' ? window.location.pathname : this.router?.state?.location?.pathname,
+      targetPathname: to,
+      basePath: this.getRuntimeBasePath(),
+      adminRoutePath: this.getAdminRoutePath(),
+      replace: opts?.replace,
+    });
+  }
+
+  private getRuntimeBasePath() {
+    return getV2EffectiveBasePath(this.app);
+  }
+
+  private getAdminRoutePath() {
+    try {
+      return this.app.layoutManager?.getLayout?.('admin')?.routePath || DEFAULT_ADMIN_ROUTE_PATH;
+    } catch {
+      return DEFAULT_ADMIN_ROUTE_PATH;
+    }
+  }
+
+  private getAdminRouteNavigationHref(pathname: string) {
+    const { pathname: rawPathname, suffix } = splitPathSearchAndHash(pathname.trim());
+    const normalizedPathname = normalizeRootPath(rawPathname);
+    const runtimeBasePath = this.getRuntimeBasePath();
+    const normalizedBasePath = normalizeRootPath(runtimeBasePath);
+
+    if (
+      normalizedBasePath !== '/' &&
+      (normalizedPathname === normalizedBasePath || normalizedPathname.startsWith(`${normalizedBasePath}/`))
+    ) {
+      return `${normalizedPathname}${suffix}`;
+    }
+
+    return `${this.app.getHref(normalizePortalRoutePath(normalizedPathname, runtimeBasePath))}${suffix}`;
+  }
+
   protected resolveLoadedComponent(moduleOrComponent: ComponentLoaderResult): ComponentTypeAndString | undefined {
     if (!moduleOrComponent) {
       return undefined;
@@ -257,6 +396,8 @@ export class RouterManager<TApp extends BaseApplication<any> = BaseApplication<a
       ],
       opts,
     );
+    this.routerNavigate = this.router.navigate.bind(this.router) as Router['navigate'];
+    this.router.navigate = this.navigateWithPortalPolicy;
 
     const RenderRouter: RouterComponentType = ({ BaseLayout = BlankComponent }) => {
       return (

package/src/__tests__/APIClient.test.tsx

@@ -0,0 +1,58 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import { APIClient } from '@nocobase/client-v2';
+import type { NotificationInstance } from 'antd/es/notification/interface';
+import MockAdapter from 'axios-mock-adapter';
+import React from 'react';
+import { renderToStaticMarkup } from 'react-dom/server';
+
+function createAPIClient() {
+  const notification = {
+    error: vi.fn(),
+    success: vi.fn(),
+  } as unknown as NotificationInstance;
+  const apiClient = new APIClient();
+  apiClient.app = { context: { notification } };
+  const apiMock = new MockAdapter(apiClient.axios);
+  return { apiClient, apiMock, notification };
+}
+
+describe('APIClient response notifications', () => {
+  it('shows error messages returned by failed requests', async () => {
+    const { apiClient, apiMock, notification } = createAPIClient();
+    apiMock.onPost('/posts:create').reply(400, { errors: [{ message: 'Request rejected by workflow' }] });
+
+    await expect(apiClient.request({ url: '/posts:create', method: 'post' })).rejects.toBeDefined();
+
+    expect(notification.error).toHaveBeenCalledOnce();
+    const [{ message }] = vi.mocked(notification.error).mock.calls[0];
+    expect(renderToStaticMarkup(<>{message}</>)).toContain('Request rejected by workflow');
+  });
+
+  it('does not show errors when skipNotify is enabled', async () => {
+    const { apiClient, apiMock, notification } = createAPIClient();
+    apiMock.onGet('/health').reply(500, { errors: [{ message: 'Health check failed' }] });
+
+    await expect(apiClient.request({ url: '/health', skipNotify: true })).rejects.toBeDefined();
+
+    expect(notification.error).not.toHaveBeenCalled();
+  });
+
+  it('shows messages returned by successful requests', async () => {
+    const { apiClient, apiMock, notification } = createAPIClient();
+    apiMock.onPost('/posts:create').reply(200, { messages: [{ message: 'Created successfully' }] });
+
+    await apiClient.request({ url: '/posts:create', method: 'post' });
+
+    expect(notification.success).toHaveBeenCalledOnce();
+    const [{ message }] = vi.mocked(notification.success).mock.calls[0];
+    expect(renderToStaticMarkup(<>{message}</>)).toContain('Created successfully');
+  });
+});

package/src/__tests__/RouteRepository.test.ts

@@ -140,6 +140,29 @@ describe('RouteRepository', () => {
     expect(repository.getRouteBySchemaUid('custom-page')).toBeUndefined();
   });
 
+  it('should find nested routes by id', () => {
+    const { repository } = createRouteRepository();
+
+    repository.setRoutes([
+      {
+        id: 1,
+        schemaUid: 'group-1',
+        children: [
+          {
+            id: 11,
+            schemaUid: 'page-1',
+          },
+        ],
+      },
+    ] as NocoBaseDesktopRoute[]);
+
+    expect(repository.getRouteById('11')).toMatchObject({
+      id: 11,
+      schemaUid: 'page-1',
+    });
+    expect(repository.getRouteById('missing')).toBeUndefined();
+  });
+
   it('should notify only subscribers for the changed layout cache', () => {
     const { repository } = createRouteRepository();
     const adminEvents: string[][] = [];

package/src/__tests__/RouterManager.test.ts

@@ -0,0 +1,125 @@
+/**
+ * This file is part of the NocoBase (R) project.
+ * Copyright (c) 2020-2024 NocoBase Co., Ltd.
+ * Authors: NocoBase Team.
+ *
+ * This project is dual-licensed under AGPL-3.0 and NocoBase Commercial License.
+ * For more information, please refer to: https://www.nocobase.com/agreement.
+ */
+
+import type { BaseApplication } from '../BaseApplication';
+import { RouterManager, shouldOpenAdminRouteInNewWindow } from '../RouterManager';
+
+describe('RouterManager', () => {
+  describe('shouldOpenAdminRouteInNewWindow', () => {
+    it('opens admin route in a new window from a non-admin portal', () => {
+      expect(
+        shouldOpenAdminRouteInNewWindow({
+          currentPathname: '/v/test',
+          targetPathname: '/admin/settings',
+          basePath: '/v',
+          adminRoutePath: '/admin',
+        }),
+      ).toBe(true);
+    });
+
+    it('supports target pathname with the v2 base path', () => {
+      expect(
+        shouldOpenAdminRouteInNewWindow({
+          currentPathname: '/nocobase/v/test',
+          targetPathname: '/nocobase/v/admin/settings',
+          basePath: '/nocobase/v',
+          adminRoutePath: '/admin',
+        }),
+      ).toBe(true);
+    });
+
+    it('supports custom portal routes in sub-apps', () => {
+      expect(
+        shouldOpenAdminRouteInNewWindow({
+          currentPathname: '/v/apps/a_9xlild35jir/crm-amd/ekeisumx1zu',
+          targetPathname: '/v/apps/a_9xlild35jir/admin/settings',
+          basePath: '/v',
+          adminRoutePath: '/admin',
+        }),
+      ).toBe(true);
+    });
+
+    it('keeps admin route navigation in the current window when already in sub-app admin', () => {
+      expect(
+        shouldOpenAdminRouteInNewWindow({
+          currentPathname: '/v/apps/a_9xlild35jir/admin',
+          targetPathname: '/v/apps/a_9xlild35jir/admin/settings',
+          basePath: '/v',
+          adminRoutePath: '/admin',
+        }),
+      ).toBe(false);
+    });
+
+    it('keeps admin route navigation in the current window when already in admin', () => {
+      expect(
+        shouldOpenAdminRouteInNewWindow({
+          currentPathname: '/v/admin',
+          targetPathname: '/admin/settings',
+          basePath: '/v',
+          adminRoutePath: '/admin',
+        }),
+      ).toBe(false);
+    });
+
+    it('keeps non-admin portal navigation in the current window', () => {
+      expect(
+        shouldOpenAdminRouteInNewWindow({
+          currentPathname: '/v/test',
+          targetPathname: '/test/page',
+          basePath: '/v',
+          adminRoutePath: '/admin',
+        }),
+      ).toBe(false);
+    });
+
+    it('does not intercept replace navigation or relative paths', () => {
+      expect(
+        shouldOpenAdminRouteInNewWindow({
+          currentPathname: '/v/test',
+          targetPathname: '/admin/settings',
+          basePath: '/v',
+          adminRoutePath: '/admin',
+          replace: true,
+        }),
+      ).toBe(false);
+      expect(
+        shouldOpenAdminRouteInNewWindow({
+          currentPathname: '/v/test',
+          targetPathname: 'admin/settings',
+          basePath: '/v',
+          adminRoutePath: '/admin',
+        }),
+      ).toBe(false);
+    });
+  });
+
+  it('opens admin route in a new window through the underlying router navigate from a sub-app portal', async () => {
+    const app = {
+      name: 'a_9xlild35jir',
+      getPublicPath: () => '/v/',
+      getHref: (pathname: string) => `/v/apps/a_9xlild35jir/${pathname.replace(/^\/+/, '')}`,
+      layoutManager: {
+        getLayout: () => ({ routePath: '/admin' }),
+      },
+      renderComponent: () => null,
+    } as unknown as BaseApplication<unknown>;
+    const manager = new RouterManager({ type: 'browser' }, app);
+    const open = vi.spyOn(window, 'open').mockImplementation(() => null);
+
+    window.history.pushState({}, '', '/v/apps/a_9xlild35jir/crm-amd/ekeisumx1zu');
+    manager.getRouterComponent();
+    await manager.router.navigate('/admin/settings/version-control/list');
+
+    expect(open).toHaveBeenCalledWith(
+      '/v/apps/a_9xlild35jir/admin/settings/version-control/list',
+      '_blank',
+      'noopener,noreferrer',
+    );
+  });
+});