@nocobase/client-v2 2.3.0-alpha.1 → 3.0.0-alpha.2

package/src/settings-center/groups.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 { PluginSettingsPageType } from '../PluginSettingsManager';
+
+/**
+ * Settings 顶层分组。
+ *
+ * 顶栏铺一级（分组），左侧栏铺该分组下的二级 / 三级菜单。
+ * 分组归属优先取配置项自身的 `group` 字段，其次落到内置映射表，最后兜底到 `system`，
+ * 因此第三方插件不改代码也能出现在设置中心里。
+ */
+export type SettingsGroupKey = 'applications' | 'plugins' | 'data' | 'access' | 'automation' | 'ai' | 'system';
+
+export type SettingsGroupDefinition = {
+  key: SettingsGroupKey;
+  /** 未翻译的分组标题，交由调用方过 i18n */
+  title: string;
+  /**
+   * 分组的门面配置项。
+   *
+   * 它会被排到该分组的第一位，并作为点击顶栏分组时的落点；
+   * 不存在（插件没装 / 无权限）时自然退回到分组内的第一项。
+   */
+  primary?: string;
+};
+
+/**
+ * 顶栏铺六个独立入口 + 一个「其他设置」兜底分组。
+ *
+ * 前六个各自只有一个配置项、且都是日常高频，直接当一级入口（标题取配置项自己的名字，
+ * 顺带继承插件的翻译）；其余零散配置全部收进其他设置，靠左栏和悬浮下拉展开。
+ *
+ * 兜底分组不叫「系统设置」：它下面本来就有一个同名的配置项（站点标题、logo 那个），
+ * 分组和子项重名会让人以为点进去是同一个东西。
+ */
+export const SETTINGS_GROUPS: SettingsGroupDefinition[] = [
+  { key: 'applications', title: 'Applications', primary: 'multi-portal' },
+  { key: 'plugins', title: 'Plugin manager', primary: 'plugin-manager' },
+  { key: 'data', title: 'Data sources', primary: 'data-source-manager' },
+  { key: 'access', title: 'Users & Permissions', primary: 'users-permissions' },
+  { key: 'automation', title: 'Workflow', primary: 'workflow' },
+  { key: 'ai', title: 'AI employees', primary: 'ai' },
+  { key: 'system', title: 'Other settings' },
+];
+
+export const DEFAULT_SETTINGS_GROUP: SettingsGroupKey = 'system';
+
+/**
+ * 内置配置项到分组的映射。
+ *
+ * key 为 `pluginSettingsManager.addMenuItem` 时传入的 `key`；
+ * 没列出来的一律落到其他设置，第三方插件不改代码也能出现。
+ */
+const BUILTIN_SETTINGS_GROUP_MAP: Record<string, SettingsGroupKey> = {
+  'multi-portal': 'applications',
+  'plugin-manager': 'plugins',
+  'data-source-manager': 'data',
+  'users-permissions': 'access',
+  workflow: 'automation',
+  ai: 'ai',
+};
+
+/**
+ * 解析某个顶级配置项所属的分组。
+ *
+ * @param {PluginSettingsPageType | null | undefined} setting 顶级配置项
+ * @returns {SettingsGroupKey} 分组 key
+ */
+export function getSettingsGroupKey(setting?: PluginSettingsPageType | null): SettingsGroupKey {
+  if (!setting) {
+    return DEFAULT_SETTINGS_GROUP;
+  }
+
+  const declared = (setting as PluginSettingsPageType & { group?: string }).group;
+  if (declared && SETTINGS_GROUPS.some((group) => group.key === declared)) {
+    return declared as SettingsGroupKey;
+  }
+
+  return BUILTIN_SETTINGS_GROUP_MAP[setting.name] || DEFAULT_SETTINGS_GROUP;
+}
+
+/**
+ * 按分组切分顶级配置项，并丢掉没有任何配置项的空分组。
+ *
+ * @param {PluginSettingsPageType[]} settings 已排序的顶级配置项
+ * @returns 非空分组
+ */
+export function groupTopLevelSettings(settings: readonly PluginSettingsPageType[] = []) {
+  return SETTINGS_GROUPS.map((group) => {
+    const members = settings.filter((setting) => getSettingsGroupKey(setting) === group.key);
+    const primaryIndex = group.primary ? members.findIndex((item) => item.name === group.primary) : -1;
+
+    return {
+      ...group,
+      settings:
+        primaryIndex > 0
+          ? [members[primaryIndex], ...members.slice(0, primaryIndex), ...members.slice(primaryIndex + 1)]
+          : members,
+    };
+  }).filter((group) => group.settings.length > 0);
+}

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;