@nocobase/client-v2 2.2.0-beta.9 → 3.0.0-alpha.1

package/src/settings-center/useSettingsGroups.ts

@@ -0,0 +1,105 @@
+/**
+ * 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 { useCallback, useMemo } from 'react';
+import { useLocation } from 'react-router-dom';
+import { useACLSnippets } from '../acl';
+import { useApp } from '../hooks/useApp';
+import type { PluginSettingsPageType } from '../PluginSettingsManager';
+import { getSettingsGroupKey, groupTopLevelSettings, type SettingsGroupKey } from './groups';
+import {
+  createSettingsPathMap,
+  filterRenderableSettings,
+  filterVisibleSettings,
+  findFirstInternalSettingsPage,
+  matchSettingsRoute,
+  PLUGIN_MANAGER_SETTING_NAME,
+  sortTopLevelSettings,
+} from './utils';
+
+/**
+ * 设置中心分组导航的共享状态。
+ *
+ * 顶栏一级导航和左侧栏二三级菜单都从这里取数据，保证两边永远一致：
+ * 同一份可见配置树、同一套分组规则、同一个「当前分组」判定。
+ */
+export function useSettingsGroups() {
+  const app = useApp();
+  const location = useLocation();
+  const snippets = useACLSnippets();
+
+  const allSettings = useMemo(
+    () => filterRenderableSettings(app.pluginSettingsManager.getList(false) as PluginSettingsPageType[]),
+    [app.pluginSettingsManager],
+  );
+
+  const visibleSettings = useMemo(() => {
+    const list = filterVisibleSettings(
+      filterRenderableSettings(app.pluginSettingsManager.getList(true) as PluginSettingsPageType[]),
+    );
+    return sortTopLevelSettings(
+      list.filter((item) => item.name !== PLUGIN_MANAGER_SETTING_NAME || snippets.includes('pm')),
+    );
+  }, [app.pluginSettingsManager, snippets]);
+
+  const groups = useMemo(() => groupTopLevelSettings(visibleSettings), [visibleSettings]);
+
+  const registeredSettingsMapByPath = useMemo(() => createSettingsPathMap(allSettings), [allSettings]);
+
+  const currentSetting = useMemo(
+    () => matchSettingsRoute(registeredSettingsMapByPath, location.pathname),
+    [location.pathname, registeredSettingsMapByPath],
+  );
+
+  const currentTopLevelSetting = useMemo(() => {
+    if (!currentSetting) {
+      return null;
+    }
+    return allSettings.find((item) => item.name === currentSetting.topLevelName) || currentSetting;
+  }, [allSettings, currentSetting]);
+
+  const activeGroupKey = useMemo<SettingsGroupKey | null>(() => {
+    if (!currentTopLevelSetting) {
+      return groups[0]?.key ?? null;
+    }
+    const key = getSettingsGroupKey(currentTopLevelSetting);
+    return groups.some((group) => group.key === key) ? key : groups[0]?.key ?? null;
+  }, [currentTopLevelSetting, groups]);
+
+  const activeGroup = useMemo(() => groups.find((group) => group.key === activeGroupKey), [activeGroupKey, groups]);
+  const activeGroupSettings = activeGroup?.settings ?? [];
+
+  /**
+   * 计算某个分组被点击后的落点。
+   *
+   * @param {string} groupKey 分组 key
+   * @returns {string | undefined} 该分组内第一个可内部打开的页面路径
+   */
+  const getGroupEntryPath = useCallback(
+    (groupKey: string) => {
+      const group = groups.find((item) => item.key === groupKey);
+      if (!group) {
+        return undefined;
+      }
+      return findFirstInternalSettingsPage(group.settings)?.path;
+    },
+    [groups],
+  );
+
+  return {
+    activeGroupKey,
+    activeGroupSettings,
+    allSettings,
+    currentSetting,
+    currentTopLevelSetting,
+    getGroupEntryPath,
+    groups,
+    visibleSettings,
+  };
+}

package/src/settings-center/useSettingsSearch.ts

@@ -0,0 +1,173 @@
+/**
+ * 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 { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
+import { useTranslation } from 'react-i18next';
+import type { PluginSettingsPageType } from '../PluginSettingsManager';
+import { useSettingsGroups } from './useSettingsGroups';
+import { hasOwnSettingsPage } from './utils';
+
+const RECENT_STORAGE_KEY = 'nb-settings-recent';
+const RECENT_MAX = 5;
+
+export type SettingsSearchItem = {
+  /** 配置项名称，同时用作最近访问的存储标识 */
+  name: string;
+  title: string;
+  /** 分组名 + 上级菜单名，用于在结果里给出上下文 */
+  breadcrumb: string;
+  path: string;
+  /** 外链配置项跳转到站外 */
+  link?: string;
+  icon?: ReactNode;
+  /** 预先拼好并转小写的匹配文本 */
+  searchText: string;
+};
+
+/**
+ * 读取最近访问过的配置项名称。
+ *
+ * 存的是名称而不是整个配置项：插件卸载、改名、权限收回之后，解析不到的记录会自然消失。
+ *
+ * @returns {string[]} 由近到远的配置项名称
+ */
+function readRecentNames(): string[] {
+  try {
+    const raw = localStorage.getItem(RECENT_STORAGE_KEY);
+    const parsed = raw ? JSON.parse(raw) : null;
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    // 存量数据可能是别的版本写的，统一在读取处去重并截断，别让脏数据一直传下去。
+    return [...new Set(parsed.filter((item): item is string => typeof item === 'string' && !!item))].slice(
+      0,
+      RECENT_MAX,
+    );
+  } catch (error) {
+    return [];
+  }
+}
+
+/**
+ * 把一次访问记到最近列表最前面。
+ *
+ * @param {string} name 配置项名称
+ * @returns {string[]} 写入后的名称列表
+ */
+function writeRecentName(name: string): string[] {
+  const next = [name, ...readRecentNames().filter((item) => item !== name)].slice(0, RECENT_MAX);
+
+  try {
+    localStorage.setItem(RECENT_STORAGE_KEY, JSON.stringify(next));
+  } catch (error) {
+    // 隐私模式下 localStorage 会抛异常，最近访问是锦上添花，静默降级即可。
+  }
+
+  return next;
+}
+
+/**
+ * 取配置项标题的纯文本形式。
+ *
+ * `title` 类型上是 ReactNode，实际都是 i18n 出来的字符串；拿不到字符串时退回名称。
+ *
+ * @param {PluginSettingsPageType} setting 配置项
+ * @returns {string} 可用于展示和匹配的标题
+ */
+function getSettingTitleText(setting: PluginSettingsPageType): string {
+  return typeof setting.title === 'string' ? setting.title : setting.name;
+}
+
+/**
+ * 设置中心的搜索与最近访问。
+ *
+ * 一级分组只剩五个、二三级收进左侧栏之后，深层页面变得不好够；这里把整棵可见配置树拍平成
+ * 一份可搜索的清单，并记住最近去过的几个，作为搜索框的空态。
+ *
+ * @returns 搜索清单、匹配函数、最近访问项，以及记录访问的回调
+ */
+export function useSettingsSearch() {
+  const { t } = useTranslation();
+  const { groups, currentSetting } = useSettingsGroups();
+  const [recentNames, setRecentNames] = useState<string[]>(() => readRecentNames());
+
+  const items = useMemo<SettingsSearchItem[]>(() => {
+    const result: SettingsSearchItem[] = [];
+
+    const walk = (setting: PluginSettingsPageType, groupTitle: string, ancestorTitles: string[]) => {
+      const title = getSettingTitleText(setting);
+      const selfHasPage = hasOwnSettingsPage(setting);
+
+      if (selfHasPage) {
+        // 上级里跟自己同名的那一层（典型是承载默认内容的 index 子页）没有信息量，去掉。
+        const breadcrumb = [groupTitle, ...ancestorTitles.filter((item) => item !== title)].join(' / ');
+
+        result.push({
+          name: setting.name,
+          title,
+          breadcrumb,
+          path: setting.path,
+          link: setting.link,
+          icon: setting.icon,
+          searchText: [title, breadcrumb, setting.name].join(' ').toLowerCase(),
+        });
+      }
+
+      const childAncestors = [...ancestorTitles, title];
+      setting.children?.forEach((child) => {
+        const childSetting = child as PluginSettingsPageType;
+
+        // 插件常用一个与菜单同名的 index 子页承载默认内容（`addPageTabItem({ key: 'index' })`），
+        // 它和菜单本身指向同一件事，只在菜单没有自己的页面时才需要作为入口出现。
+        if (selfHasPage && getSettingTitleText(childSetting) === title) {
+          return;
+        }
+
+        walk(childSetting, groupTitle, childAncestors);
+      });
+    };
+
+    groups.forEach((group) => {
+      const groupTitle = t(group.title);
+      group.settings.forEach((setting) => walk(setting, groupTitle, []));
+    });
+
+    return result;
+  }, [groups, t]);
+
+  const search = useCallback(
+    (keyword: string) => {
+      const normalized = keyword.trim().toLowerCase();
+
+      if (!normalized) {
+        return [];
+      }
+
+      // 空格分词后全部命中才算匹配，方便用「用户 角色」这种写法逐步收窄。
+      const terms = normalized.split(/\s+/);
+      return items.filter((item) => terms.every((term) => item.searchText.includes(term)));
+    },
+    [items],
+  );
+
+  const recentItems = useMemo(
+    () => recentNames.map((name) => items.find((item) => item.name === name)).filter(Boolean) as SettingsSearchItem[],
+    [items, recentNames],
+  );
+
+  // 当前停留的页面即为一次访问；由所在页面自身触发，避免每个入口都要记一次。
+  useEffect(() => {
+    if (!currentSetting?.name) {
+      return;
+    }
+    setRecentNames(writeRecentName(currentSetting.name));
+  }, [currentSetting?.name]);
+
+  return { items, recentItems, search };
+}

package/src/settings-center/utils.tsx

@@ -7,12 +7,16 @@
  * For more information, please refer to: https://www.nocobase.com/agreement.
  */
 
+import type { MenuProps } from 'antd';
 import { Outlet } from 'react-router-dom';
 import type { PluginSettingsPageType } from '../PluginSettingsManager';
 
+export type SidebarMenuItem = NonNullable<MenuProps['items']>[number];
+
 export const ADMIN_SETTINGS_LAYOUT_MODEL_UID = 'admin-settings-layout-model';
 export const PLUGIN_MANAGER_SETTING_NAME = 'plugin-manager';
 export const SYSTEM_SETTINGS_SETTING_NAME = 'system-settings';
+export const MULTI_PORTAL_SETTING_NAME = 'multi-portal';
 
 /**
  * 判断配置项是否拥有可直接渲染的页面。
@@ -218,7 +222,8 @@ export function findSettingsByName(
  * @returns {string | undefined} 默认跳转路径
  */
 export function getDefaultSettingsPath(settings: readonly PluginSettingsPageType[] = []) {
-  const preferredNames = [SYSTEM_SETTINGS_SETTING_NAME, PLUGIN_MANAGER_SETTING_NAME];
+  // Portal 中心是设置中心的门面：登录后先落在应用入口，再往下走系统配置。
+  const preferredNames = [MULTI_PORTAL_SETTING_NAME, SYSTEM_SETTINGS_SETTING_NAME, PLUGIN_MANAGER_SETTING_NAME];
 
   for (const name of preferredNames) {
     const preferred = findSettingsByName(settings, name);
@@ -239,6 +244,50 @@ export function getDefaultSettingsPath(settings: readonly PluginSettingsPageType
   return findFirstInternalSettingsPage(settings)?.path;
 }
 
+/**
+ * 构造左侧栏菜单。
+ *
+ * 左栏只铺**一级**配置项，不下钻子菜单：备份管理器、通知管理这类插件的子页面统一走页头下的
+ * Tab（和 v1 设置中心一致），左栏折叠展开再叠一层反而多一次点击、也和 Tab 表达重复。
+ *
+ * @param {PluginSettingsPageType[]} settings 某个分组下的配置项
+ * @returns {SidebarMenuItem[]} antd Menu items
+ */
+export function getSidebarMenuItems(settings: readonly PluginSettingsPageType[] = []): SidebarMenuItem[] {
+  return settings
+    .filter((item) => !item.hidden)
+    .map((item) => ({
+      key: item.name,
+      label: item.label ?? item.title,
+      title: typeof item.title === 'string' ? item.title : undefined,
+      icon: item.icon,
+    }));
+}
+
+/**
+ * 把当前命中的配置项换算成左侧栏里真实存在的菜单 key。
+ *
+ * 左栏只有一级，命中的可能是某个子页面（它在左栏没有自己的条目），
+ * 这里回退到它所属的那个一级项。
+ *
+ * @param {PluginSettingsPageType[]} settings 某个分组下的配置项
+ * @param {string | undefined} activeName 当前命中的配置项名称
+ * @returns {string | undefined} 左栏应选中的 key
+ */
+export function getSidebarSelectedKey(
+  settings: readonly PluginSettingsPageType[] = [],
+  activeName?: string,
+): string | undefined {
+  if (!activeName) {
+    return undefined;
+  }
+
+  const contains = (items: readonly PluginSettingsPageType[]): boolean =>
+    items.some((item) => item.name === activeName || contains(item.children || []));
+
+  return settings.find((item) => item.name === activeName || contains(item.children || []))?.name;
+}
+
 /**
  * 把 settings 结构转换成 antd Menu items。
  *

package/src/theme/index.tsx

@@ -101,5 +101,6 @@ export const GlobalThemeProvider: FC<GlobalThemeProviderProps> = ({ children, th
 
 export { default as compatOldTheme } from './compatOldTheme';
 export { addCustomAlgorithmToTheme, customAlgorithm } from './customAlgorithm';
+export { getItemActiveColors } from './itemActive';
 export * from './type';
 export { defaultTheme };

package/src/theme/itemActive.ts

@@ -0,0 +1,31 @@
+/**
+ * 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 { GlobalToken } from 'antd';
+import type { CustomToken } from './type';
+
+/**
+ * 取「选中项」的底色与文字色。
+ *
+ * antd 只有 `controlItemBgActive` 一个背景 token，没有配对的文字色，页面各自写背景、
+ * 文字色照旧，底色一被主题改深就成了深底深字。这里统一读 `colorBgItemActive` /
+ * `colorTextItemActive` 这一对自定义 token，没设置时回落到 antd 的默认表现，
+ * 于是同一段代码在默认主题和设置中心的黑白主题下都对。
+ *
+ * @param {GlobalToken} token antd token
+ * @returns {{ bg: string; color: string | undefined }} 选中项底色，以及需要显式指定的文字色（回落时为 undefined）
+ */
+export function getItemActiveColors(token: GlobalToken) {
+  const customToken = token as Partial<CustomToken>;
+
+  return {
+    bg: customToken.colorBgItemActive || token.controlItemBgActive,
+    color: customToken.colorTextItemActive || undefined,
+  };
+}

package/src/theme/type.ts

@@ -26,6 +26,16 @@ export interface CustomToken extends AliasToken {
   colorBgSiderMenuHover: string;
   colorBgSiderMenuActive: string;
 
+  /**
+   * 「选中项」的底色与压在其上的文字色。
+   *
+   * antd 只给了 `controlItemBgActive` 一个背景 token，没有配对的文字色，于是各页面
+   * 自己写背景、文字色照旧，底色一变深就成了深底深字。这一对补齐了那半边：
+   * 列表行、树节点、卡片这类自绘选中态统一读它，未设置时回落到 antd 的默认表现。
+   */
+  colorBgItemActive: string;
+  colorTextItemActive: string;
+
   colorSettings: string;
   colorBgSettingsHover: string;
   colorTemplateBgSettingsHover: string;

package/src/utils/getRouteRuntimeVersion.ts

@@ -0,0 +1,185 @@
+/**
+ * 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.
+ */
+
+export type RouteRuntimeVersion = 'legacy' | 'modern';
+
+declare global {
+  interface Window {
+    __nocobase_modern_client_prefix__?: string;
+    __nocobase_public_path__?: string;
+  }
+}
+
+function hasModernClientPrefix() {
+  return (
+    typeof window !== 'undefined' &&
+    typeof window.__nocobase_modern_client_prefix__ === 'string' &&
+    window.__nocobase_modern_client_prefix__.trim().length > 0
+  );
+}
+
+function hasConfiguredPublicPath() {
+  return typeof window !== 'undefined' && typeof window.__nocobase_public_path__ === 'string';
+}
+
+/** Normalize any app/public-path-like input into a root-relative pathname:
+ *
+ * - `nocobase//v/` -> `/nocobase/v`
+ * - `/` -> `/`
+ */
+function normalizeRootRelativePath(value = '/') {
+  const normalized = `/${String(value || '/').trim() || '/'}`.replace(/\/{2,}/g, '/');
+  if (normalized !== '/' && normalized.endsWith('/')) {
+    return normalized.replace(/\/+$/g, '');
+  }
+  return normalized;
+}
+
+/** Public-path form always ends with `/`, so it can be compared as a base path:
+ *
+ * - `/nocobase/v` -> `/nocobase/v/`
+ * - `/` -> `/`
+ */
+function normalizePublicPath(value = '/') {
+  const normalized = normalizeRootRelativePath(value);
+  return normalized.endsWith('/') ? normalized : `${normalized}/`;
+}
+
+/** Check whether a concrete pathname is rendered under a runtime base path:
+ *
+ * - pathname `/nocobase/v/admin/workflow/workflows/1`
+ *   basePath `/nocobase/v/`
+ *   => true
+ *
+ * - pathname `/nocobase/admin/settings/workflow/workflows/1`
+ *   basePath `/nocobase/v/`
+ *   => false
+ */
+function isPathnameInsideBasePath(pathname: string, basePath: string) {
+  const normalizedPathname = normalizeRootRelativePath(pathname);
+  const normalizedBasePath = normalizePublicPath(basePath);
+  const trimmedBasePath = normalizedBasePath.replace(/\/+$/g, '') || '/';
+
+  if (trimmedBasePath === '/') {
+    return true;
+  }
+
+  return normalizedPathname === trimmedBasePath || normalizedPathname.startsWith(`${trimmedBasePath}/`);
+}
+
+function getNormalizedModernClientPrefix() {
+  if (typeof window === 'undefined') {
+    return '';
+  }
+
+  const prefix = window.__nocobase_modern_client_prefix__?.trim();
+  return prefix ? prefix.replace(/^\/+|\/+$/g, '') : '';
+}
+
+/** Derive the actual modern-client base path from injected globals.
+ *
+ * Only returns a value when `__nocobase_public_path__` itself already points to
+ * the modern client shell:
+ *
+ * - legacy shell:
+ *   `__nocobase_public_path__ = "/nocobase/"`
+ *   `__nocobase_modern_client_prefix__ = "v"`
+ *   => `""`
+ *
+ * - modern shell:
+ *   `__nocobase_public_path__ = "/nocobase/v/"`
+ *   `__nocobase_modern_client_prefix__ = "v"`
+ *   => `"/nocobase/v/"`
+ */
+function getModernClientBasePath() {
+  const normalizedPrefix = getNormalizedModernClientPrefix();
+  if (!normalizedPrefix) {
+    return '';
+  }
+
+  if (typeof window === 'undefined') {
+    return '';
+  }
+
+  const publicPath = window.__nocobase_public_path__?.trim();
+  if (publicPath && normalizePublicPath(publicPath).endsWith(`/${normalizedPrefix}/`)) {
+    return normalizePublicPath(publicPath);
+  }
+
+  return '';
+}
+
+/** True only when the current page is actually running under the resolved
+ * modern-client base path.
+ *
+ * Example:
+ * - pathname `/v/admin/workflow/workflows/1`, modern base `/v/` => true
+ * - pathname `/admin/settings/workflow/workflows/1`, modern base `/v/` => false
+ */
+function isPathnameInModernClientRuntime() {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  const pathname = window.location?.pathname ?? '';
+  const modernClientBasePath = getModernClientBasePath();
+  if (!pathname || !modernClientBasePath) {
+    return false;
+  }
+
+  return isPathnameInsideBasePath(pathname, modernClientBasePath);
+}
+
+/** Fallback for incomplete/mocked environments where public path was not
+ * injected but the modern prefix still exists.
+ *
+ * Example:
+ * - pathname `/v/admin/workflow/workflows/1`
+ *   `__nocobase_modern_client_prefix__ = "v"`
+ *   `__nocobase_public_path__` missing
+ *   => true
+ */
+function isPathnameInModernClientRuntimeByPrefix() {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  const normalizedPrefix = getNormalizedModernClientPrefix();
+  const pathname = window.location?.pathname ?? '';
+  if (!normalizedPrefix || !pathname) {
+    return false;
+  }
+
+  return isPathnameInsideBasePath(pathname, normalizePublicPath(normalizedPrefix));
+}
+
+/** Resolve which client shell currently owns the route.
+ *
+ * - returns `modern` when the current page is actually mounted under the modern
+ *   client base path (`/v/`, `/nocobase/v/`, ...)
+ * - returns `legacy` when the route is still under the legacy shell, even if the
+ *   modern prefix global has been injected into the page
+ */
+export function getRouteRuntimeVersion(): RouteRuntimeVersion {
+  if (typeof window === 'undefined') {
+    return hasModernClientPrefix() ? 'modern' : 'legacy';
+  }
+
+  if (hasConfiguredPublicPath()) {
+    return isPathnameInModernClientRuntime() ? 'modern' : 'legacy';
+  }
+
+  // Defensive fallback for incomplete test/mocked environments where public
+  // path was not injected but the modern prefix still exists.
+  if (isPathnameInModernClientRuntimeByPrefix()) {
+    return 'modern';
+  }
+
+  return 'legacy';
+}

package/src/utils/index.tsx

@@ -11,6 +11,7 @@ import React, { ComponentType, FC } from 'react';
 import { BlankComponent } from '../components';
 
 export * from './appVersionHTML';
+export * from './getRouteRuntimeVersion';
 
 export function normalizeContainer(container: Element | ShadowRoot | string): Element | null {
   if (!container) {