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

package/es/nocobase-buildin-plugin/currentUserAuthStatus.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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 CurrentUserAuthStatus = 'unknown' | 'authenticated' | 'unauthenticated' | 'redirecting';
+export declare function setCurrentUserAuthStatus(app: object, status: CurrentUserAuthStatus): void;
+export declare function useCurrentUserAuthStatus(app: object): CurrentUserAuthStatus;

package/es/nocobase-buildin-plugin/index.d.ts

@@ -39,4 +39,13 @@ export declare class NocoBaseBuildInPlugin extends Plugin<any, Application> {
     addComponents(): void;
     addPlugins(): Promise<void>;
 }
+/**
+ * Internal built-in runtime for the standalone Client V2 settings entry.
+ * It intentionally shares the existing plugin lane and runtime providers but
+ * does not register the Admin Layout.
+ */
+export declare class SettingsBuildInPlugin extends Plugin<any, Application> {
+    afterAdd(): Promise<void>;
+    load(): Promise<void>;
+}
 export { NocoBaseBuildInPlugin as NocoBaseBuildInPluginV2 };

package/es/settings-app/SettingsApplication.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 { Application, type ApplicationOptions } from '../index';
+import { SettingsPluginSettingsManager } from './SettingsPluginSettingsManager';
+import { SettingsRouterManager } from './SettingsRouterManager';
+export declare class SettingsApplication extends Application {
+    /** 设置中心的标记，插件通过 `isSettingsApp(app)` 读它，避免反向依赖这个类。 */
+    readonly isSettingsApp = true;
+    protected addCustomProviders(): void;
+    protected createRouterManager(options: ApplicationOptions): SettingsRouterManager<this>;
+    protected createPluginSettingsManager(_options: ApplicationOptions): SettingsPluginSettingsManager<this>;
+}

package/es/settings-app/SettingsBrand.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 React from 'react';
+/**
+ * 设置中心顶栏品牌区。
+ *
+ * 沿用系统设置里的站点 logo / 标题，并在其后补一个弱化的「设置中心」副标题，
+ * 用于区分设置中心和业务端。
+ */
+export declare const SettingsBrand: React.MemoExoticComponent<import("@formily/reactive-react").ReactFC<unknown>>;

package/es/settings-app/SettingsBuildInPlugin.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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 { SettingsBuildInPlugin } from '../nocobase-buildin-plugin';

package/es/settings-app/SettingsDocumentRedirect.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 React from 'react';
+export declare function SettingsDocumentRedirect(): React.ReactElement<any, string | React.JSXElementConstructor<any>>;

package/es/settings-app/SettingsGroupNav.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 React from 'react';
+/**
+ * 设置中心顶栏的一级导航。
+ *
+ * 应用、插件管理各自只有一个页面，直接当一级入口；其余全部收在「系统设置」下，
+ * 鼠标移上去展开下拉，也可以点进去从左栏走。
+ */
+export declare const SettingsGroupNav: React.FC;
+export default SettingsGroupNav;

package/es/settings-app/SettingsPluginSettingsManager.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 { PluginSettingsManager } from '../PluginSettingsManager';
+export declare class SettingsPluginSettingsManager<TApp extends BaseApplication<any> = BaseApplication<any>> extends PluginSettingsManager<TApp> {
+    getRouteName(name: string): string;
+    getRoutePath(name: string): string;
+}

package/es/settings-app/SettingsRouterManager.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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, type RouteType } from '../RouterManager';
+export declare class SettingsRouterManager<TApp extends BaseApplication<any> = BaseApplication<any>> extends RouterManager<TApp> {
+    private rebaseScopedSettingsRoute;
+    private rebaseAuthenticationRoute;
+    add(name: string, route: RouteType): void;
+}

package/es/settings-app/SettingsSearch.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 React from 'react';
+/**
+ * 设置中心的搜索入口。
+ *
+ * 顶栏放一个轻量触发器，真正的搜索在弹层里进行；关键词为空时展示最近访问，
+ * 这样分组化之后被收进左侧栏的深层页面仍然一步可达。支持 `Cmd/Ctrl + K` 唤起。
+ */
+export declare const SettingsSearch: React.FC;
+export default SettingsSearch;

package/es/settings-app/SettingsShell.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 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 FC } from 'react';
+export declare const SettingsShell: FC;

package/es/settings-app/isSettingsApp.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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 `SettingsApplication`
+ * 本身——那会让插件反向依赖壳的实现。
+ *
+ * @param {any} app 应用实例
+ * @returns {boolean} 是设置中心返回 true
+ */
+export declare function isSettingsApp(app?: any): boolean;

package/es/settings-app/runtimePaths.d.ts

@@ -0,0 +1,18 @@
+/**
+ * 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';
+type SettingsRuntimeApp = Pick<BaseApplication<any>, 'name'> & {
+    getPublicPath?: () => string;
+    router?: {
+        basename?: string;
+        getBasename?: () => string | undefined;
+    };
+};
+export declare function resolveStandaloneSettingsPath(app: SettingsRuntimeApp, pathLike: string, contextPathname?: string): string;
+export {};

package/es/settings-app/settingsDocumentPath.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 SettingsAppScope = '' | `/${'apps' | '_app'}/${string}`;
+export declare function normalizeSettingsRootPublicPath(value?: string): string;
+export declare function resolveSettingsAppScope(pathname?: string): SettingsAppScope;
+export declare function resolveSettingsAppScopeWithinPublicPath(publicPath: string, pathname?: string): SettingsAppScope;
+export declare function resolveSettingsDocumentPath(rootPublicPath: string, appScope: SettingsAppScope, settingsRoutePath: string): string;
+export declare function resolveSettingsDocumentBasename(rootPublicPath: string, appScope: SettingsAppScope): string;

package/es/settings-app/settingsTheme.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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, ThemeConfig } from 'antd';
+/**
+ * 粗略判断一个颜色是不是深色背景。
+ *
+ * 只支持 `#rgb` / `#rrggbb`，解析不出来时按浅色处理。
+ *
+ * @param {string | undefined} color 背景色
+ * @returns {boolean} 是否为深色
+ */
+export declare function isDarkColor(color?: string): boolean;
+/**
+ * 取顶栏配色。
+ *
+ * 设置中心的顶栏刻意**不跟随**主题编辑器里的 `colorBgHeader`：那套深色顶栏是给业务端的，
+ * 设置中心用容器底色（浅色主题下就是白色）+ 一条细分割线，和业务端在视觉上分开。
+ * 文字和图标一律走正文色，深色主题下由 `colorBgContainer` 自动翻成浅色。
+ *
+ * @param {GlobalToken} token 外层主题 token
+ * @returns 顶栏底色、文字色、hover / active 色，以及顶栏是否为深色
+ */
+export declare function getSettingsHeaderColors(token: GlobalToken): {
+    bg: string;
+    dark: boolean;
+    text: string;
+    textHover: string;
+    textActive: string;
+    bgHover: string;
+    bgActive: string;
+};
+/**
+ * 顶栏一级导航专用主题。
+ *
+ * 顶栏自己是透明底（底色由 Layout.Header 给），下拉浮层跟着顶栏用容器色；
+ * 选中 / hover 的颜色一律交给外层主题，也就是默认蓝。
+ *
+ * @param {GlobalToken} token 外层主题 token
+ * @returns {ThemeConfig} 顶栏菜单主题
+ */
+export declare function buildSettingsHeaderMenuTheme(token: GlobalToken): ThemeConfig;
+/**
+ * 构造设置中心的外壳主题。
+ *
+ * 只做**顶栏**这一层：白（或深色主题下的容器色）底 + 细分割线，文字与图标走正文色，
+ * 和业务端那条深色顶栏区分开。
+ *
+ * 选中态一律用浅灰底 + 正文色，只有开关这类「开/关」控件才用纯黑填充。
+ * 各插件页面里 `controlItemBgActive` 常被当成纯背景用、文字色不跟着走，所以那个 token
+ * 也保持浅色，不然列表行会变成深底深字。
+ *
+ * @param {GlobalToken} token 外层主题 token
+ * @returns {ThemeConfig} 设置中心外壳主题
+ */
+export declare function buildSettingsNeutralTheme(token: GlobalToken): ThemeConfig;
+/**
+ * 给外部主题补上设置中心的顶栏配色。
+ *
+ * 顶栏那几个 token（`colorBgHeader`、`colorTextHeaderMenu` 系列、`Layout.headerBg`）
+ * 刻意不放进「简约」主题记录里：那条记录是通用的，业务端顶栏是深色的、logo 和图标都按
+ * 深底做的，一旦被改成白底就得连 logo 一起反色。设置中心的顶栏是白的，所以在这一层补。
+ *
+ * @param {ThemeConfig} theme 主题记录里读到的配置
+ * @param {GlobalToken} token 外层主题 token
+ * @returns {ThemeConfig} 补齐顶栏配色后的主题
+ */
+export declare function withSettingsHeaderTheme(theme: ThemeConfig, token: GlobalToken): ThemeConfig;
+/**
+ * 设置中心的全局补丁样式。
+ *
+ * 这几件事 antd 没给 token，只能落到 CSS：
+ * - 裸 `<a>` 的颜色。它吃的是**最外层** ConfigProvider 生成的全局 reset 样式，
+ *   我们这层嵌套 ConfigProvider 的 `colorLink` 够不着，只能在 CSS 里压一次。
+ * - 链接下划线（`colorLink` 只管颜色）
+ * - Switch 禁用态压得更淡，跟「未启用但可点」区分开
+ * - 顶栏选中项的下划线、左栏选中项的加粗
+ *
+ * @param {GlobalToken} token 外层主题 token
+ * @returns {string} 可直接塞进 `<style>` 的 CSS
+ */
+export declare function buildSettingsGlobalCss(token: GlobalToken): string;

package/es/settings-app/useSettingsThemeConfig.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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 ThemeConfig } from 'antd';
+/** 简约主题在 `themeConfig` 表里的固定标识，见 plugin-theme-editor 的 builtinThemes */
+export declare const MINIMAL_THEME_UID = "minimal";
+/**
+ * 读取设置中心主题。
+ *
+ * 设置中心的外观由 `themeConfig` 里那条「简约」记录约束，在主题编辑器里就能改；
+ * 它本身是一条普通的可选主题，别的应用要同一套观感直接选它即可。
+ * 读不到（主题编辑器插件没启、老实例还没迁移、请求失败）时返回 `null`，
+ * 由调用方回落到代码里的默认中性配色，避免设置中心突然变回一片蓝。
+ *
+ * @returns {ThemeConfig | null | undefined} 主题配置；`undefined` 表示还没读完
+ */
+export declare function useSettingsThemeConfig(): ThemeConfig | null | undefined;

package/es/settings-center/AdminSettingsLayout.d.ts

@@ -10,8 +10,8 @@ import React from 'react';
 /**
  * `client-v2` 的 settings 页面壳实现。
  *
- * 该组件负责左侧菜单、顶部 tabs、默认落点和两类空态，
- * 页面内容本身继续由各个 settings route 的 `<Outlet />` 渲染。
+ * 一级分组铺在顶栏（见 `SettingsGroupNav`），这里负责当前分组下的二三级嵌套菜单、
+ * 默认落点和两类空态，页面内容本身继续由各个 settings route 的 `<Outlet />` 渲染。
  */
 export declare const InternalAdminSettingsLayout: () => React.JSX.Element;
 /**

package/es/settings-center/groups.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 declare const SETTINGS_GROUPS: SettingsGroupDefinition[];
+export declare const DEFAULT_SETTINGS_GROUP: SettingsGroupKey;
+/**
+ * 解析某个顶级配置项所属的分组。
+ *
+ * @param {PluginSettingsPageType | null | undefined} setting 顶级配置项
+ * @returns {SettingsGroupKey} 分组 key
+ */
+export declare function getSettingsGroupKey(setting?: PluginSettingsPageType | null): SettingsGroupKey;
+/**
+ * 按分组切分顶级配置项，并丢掉没有任何配置项的空分组。
+ *
+ * @param {PluginSettingsPageType[]} settings 已排序的顶级配置项
+ * @returns 非空分组
+ */
+export declare function groupTopLevelSettings(settings?: readonly PluginSettingsPageType[]): {
+    settings: PluginSettingsPageType[];
+    key: SettingsGroupKey;
+    /** 未翻译的分组标题，交由调用方过 i18n */
+    title: string;
+    /**
+     * 分组的门面配置项。
+     *
+     * 它会被排到该分组的第一位，并作为点击顶栏分组时的落点；
+     * 不存在（插件没装 / 无权限）时自然退回到分组内的第一项。
+     */
+    primary?: string;
+}[];

package/es/settings-center/useSettingsGroups.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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';
+import { type SettingsGroupKey } from './groups';
+/**
+ * 设置中心分组导航的共享状态。
+ *
+ * 顶栏一级导航和左侧栏二三级菜单都从这里取数据，保证两边永远一致：
+ * 同一份可见配置树、同一套分组规则、同一个「当前分组」判定。
+ */
+export declare function useSettingsGroups(): {
+    activeGroupKey: SettingsGroupKey;
+    activeGroupSettings: PluginSettingsPageType[];
+    allSettings: PluginSettingsPageType[];
+    currentSetting: PluginSettingsPageType;
+    currentTopLevelSetting: PluginSettingsPageType;
+    getGroupEntryPath: (groupKey: string) => string;
+    groups: {
+        settings: PluginSettingsPageType[];
+        key: SettingsGroupKey;
+        title: string;
+        primary?: string; /**
+         * 设置中心分组导航的共享状态。
+         *
+         * 顶栏一级导航和左侧栏二三级菜单都从这里取数据，保证两边永远一致：
+         * 同一份可见配置树、同一套分组规则、同一个「当前分组」判定。
+         */
+    }[];
+    visibleSettings: PluginSettingsPageType[];
+};

package/es/settings-center/useSettingsSearch.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 ReactNode } from 'react';
+export type SettingsSearchItem = {
+    /** 配置项名称，同时用作最近访问的存储标识 */
+    name: string;
+    title: string;
+    /** 分组名 + 上级菜单名，用于在结果里给出上下文 */
+    breadcrumb: string;
+    path: string;
+    /** 外链配置项跳转到站外 */
+    link?: string;
+    icon?: ReactNode;
+    /** 预先拼好并转小写的匹配文本 */
+    searchText: string;
+};
+/**
+ * 设置中心的搜索与最近访问。
+ *
+ * 一级分组只剩五个、二三级收进左侧栏之后，深层页面变得不好够；这里把整棵可见配置树拍平成
+ * 一份可搜索的清单，并记住最近去过的几个，作为搜索框的空态。
+ *
+ * @returns 搜索清单、匹配函数、最近访问项，以及记录访问的回调
+ */
+export declare function useSettingsSearch(): {
+    items: SettingsSearchItem[];
+    recentItems: SettingsSearchItem[];
+    search: (keyword: string) => SettingsSearchItem[];
+};

package/es/settings-center/utils.d.ts

@@ -6,10 +6,13 @@
  * 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 { MenuProps } from 'antd';
 import type { PluginSettingsPageType } from '../PluginSettingsManager';
+export type SidebarMenuItem = NonNullable<MenuProps['items']>[number];
 export declare const ADMIN_SETTINGS_LAYOUT_MODEL_UID = "admin-settings-layout-model";
 export declare const PLUGIN_MANAGER_SETTING_NAME = "plugin-manager";
 export declare const SYSTEM_SETTINGS_SETTING_NAME = "system-settings";
+export declare const MULTI_PORTAL_SETTING_NAME = "multi-portal";
 /**
  * 判断配置项是否拥有可直接渲染的页面。
  *
@@ -85,6 +88,27 @@ export declare function findSettingsByName(settings: readonly PluginSettingsPage
  * @returns {string | undefined} 默认跳转路径
  */
 export declare function getDefaultSettingsPath(settings?: readonly PluginSettingsPageType[]): string;
+/**
+ * 构造左侧栏菜单。
+ *
+ * 左栏只铺**一级**配置项，不下钻子菜单：备份管理器、通知管理这类插件的子页面统一走页头下的
+ * Tab（和 v1 设置中心一致），左栏折叠展开再叠一层反而多一次点击、也和 Tab 表达重复。
+ *
+ * @param {PluginSettingsPageType[]} settings 某个分组下的配置项
+ * @returns {SidebarMenuItem[]} antd Menu items
+ */
+export declare function getSidebarMenuItems(settings?: readonly PluginSettingsPageType[]): SidebarMenuItem[];
+/**
+ * 把当前命中的配置项换算成左侧栏里真实存在的菜单 key。
+ *
+ * 左栏只有一级，命中的可能是某个子页面（它在左栏没有自己的条目），
+ * 这里回退到它所属的那个一级项。
+ *
+ * @param {PluginSettingsPageType[]} settings 某个分组下的配置项
+ * @param {string | undefined} activeName 当前命中的配置项名称
+ * @returns {string | undefined} 左栏应选中的 key
+ */
+export declare function getSidebarSelectedKey(settings?: readonly PluginSettingsPageType[], activeName?: string): string | undefined;
 /**
  * 把 settings 结构转换成 antd Menu items。
  *

package/es/theme/index.d.ts

@@ -32,5 +32,6 @@ interface GlobalThemeProviderProps {
 export declare const GlobalThemeProvider: FC<GlobalThemeProviderProps>;
 export { default as compatOldTheme } from './compatOldTheme';
 export { addCustomAlgorithmToTheme, customAlgorithm } from './customAlgorithm';
+export { getItemActiveColors } from './itemActive';
 export * from './type';
 export { defaultTheme };

package/es/theme/itemActive.d.ts

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

package/es/theme/type.d.ts

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