@nocobase/client-v2 2.1.0-beta.22 → 2.1.0-beta.24

package/src/flow/admin-shell/admin-layout/AdminLayoutModel.tsx

@@ -0,0 +1,330 @@
+/**
+ * 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 { define, observable, reaction } from '@formily/reactive';
+import { type FlowEngine, FlowModel } from '@nocobase/flow-engine';
+import type { NocoBaseDesktopRoute } from '../../../flow-compat';
+import { AdminLayoutRouteCoordinator, type RoutePageMeta } from '../AdminLayoutRouteCoordinator';
+import { ADMIN_LAYOUT_MODEL_UID } from './constants';
+import { type AdminLayoutMenuItemModel } from './AdminLayoutMenuModels';
+import {
+  getAdminLayoutMenuInitializerButton,
+  reconcileAdminLayoutMenuItems,
+  type AdminLayoutMenuRouteOptions,
+} from './AdminLayoutMenuUtils';
+import { AdminLayoutComponent } from './AdminLayoutComponent';
+import React from 'react';
+import { TopbarActionModel } from '../../models/topbar/TopbarActionModel';
+import { TopbarActionsBar } from './TopbarActionsBar';
+
+export type AdminLayoutStructure = {
+  subModels: {
+    menuItems?: AdminLayoutMenuItemModel[];
+  };
+};
+
+type GetAdminLayoutModelOptions<TModel extends FlowModel = AdminLayoutModel> = {
+  required?: boolean;
+  create?: boolean;
+  props?: any;
+  use?: new (...args: any[]) => TModel;
+};
+
+/**
+ * Admin Layout 的纯运行时 host model。
+ *
+ * 该模型只负责菜单树、页面路由桥接和上下文注入，
+ * 不负责任何 React 渲染。
+ *
+ * @example
+ * ```typescript
+ * const model = getAdminLayoutModel(flowEngine, { required: true });
+ * model.syncMenuRoutes(routes);
+ * ```
+ */
+export class AdminLayoutModel extends FlowModel<AdminLayoutStructure> {
+  isMobileLayout = false;
+  private routeCoordinator?: AdminLayoutRouteCoordinator;
+  private routeDisposer?: () => void;
+  private activePageUid = '';
+  private layoutContentElement: HTMLElement | null = null;
+  private readonly routePageMetaMap = new Map<string, RoutePageMeta>();
+
+  constructor(options: any) {
+    super(options);
+    define(this, {
+      isMobileLayout: observable.ref,
+    });
+  }
+
+  /**
+   * 注册页面运行时信息。
+   *
+   * @param {string} pageUid 页面 UID
+   * @param {RoutePageMeta} meta 页面运行时元数据
+   * @returns {FlowModel} 对应的页面模型
+   */
+  registerRoutePage(pageUid: string, meta: RoutePageMeta) {
+    this.routePageMetaMap.set(pageUid, meta);
+    return this.getCoordinator().registerPage(pageUid, meta);
+  }
+
+  /**
+   * 更新页面运行时信息。
+   *
+   * @param {string} pageUid 页面 UID
+   * @param {Partial<RoutePageMeta>} meta 待更新的页面元数据
+   * @returns {void}
+   */
+  updateRoutePage(pageUid: string, meta: Partial<RoutePageMeta>) {
+    const prev = this.routePageMetaMap.get(pageUid) || { active: false };
+    const next = {
+      ...prev,
+      ...meta,
+      active: typeof meta.active === 'boolean' ? meta.active : prev.active,
+    };
+    this.routePageMetaMap.set(pageUid, next);
+    this.getCoordinator().syncPageMeta(pageUid, meta);
+  }
+
+  /**
+   * 注销页面运行时信息。
+   *
+   * @param {string} pageUid 页面 UID
+   * @returns {void}
+   */
+  unregisterRoutePage(pageUid: string) {
+    this.routePageMetaMap.delete(pageUid);
+    if (this.activePageUid === pageUid) {
+      this.activePageUid = '';
+    }
+    this.getCoordinator().unregisterPage(pageUid);
+  }
+
+  /**
+   * 使用当前可访问菜单路由刷新 Layout 菜单树。
+   *
+   * @param {NocoBaseDesktopRoute[]} routes 当前用户可访问的桌面路由
+   * @returns {void}
+   */
+  syncMenuRoutes(routes: NocoBaseDesktopRoute[]) {
+    reconcileAdminLayoutMenuItems(this, Array.isArray(routes) ? routes : []);
+  }
+
+  /**
+   * 将菜单模型转换为 ProLayout 路由树。
+   *
+   * @param {Omit<AdminLayoutMenuRouteOptions, 'depth'>} options 路由转换参数
+   * @returns {{ path: string; children: any[] }} ProLayout 路由树
+   */
+  toProLayoutRoute(options: Omit<AdminLayoutMenuRouteOptions, 'depth'>) {
+    const result =
+      (this.subModels.menuItems || [])
+        .map((item) =>
+          item.toProLayoutRoute({
+            ...options,
+            depth: 0,
+          }),
+        )
+        .filter(Boolean) || [];
+
+    if (options.designable) {
+      options.isMobile
+        ? result.push(getAdminLayoutMenuInitializerButton('schema-initializer-Menu-header', this))
+        : result.unshift(getAdminLayoutMenuInitializerButton('schema-initializer-Menu-header', this));
+    }
+
+    return {
+      path: '/',
+      children: result,
+    };
+  }
+
+  /**
+   * 设置布局内容容器元素。
+   *
+   * @param {HTMLElement | null} element 布局内容容器
+   * @returns {void}
+   */
+  setLayoutContentElement(element: HTMLElement | null) {
+    this.layoutContentElement = element;
+    this.getCoordinator().setLayoutContentElement(element);
+  }
+
+  /**
+   * 设置是否为移动端布局。
+   *
+   * @param {boolean} isMobileLayout 是否为移动端布局
+   * @returns {void}
+   */
+  setIsMobileLayout(isMobileLayout: boolean) {
+    this.isMobileLayout = !!isMobileLayout;
+  }
+
+  protected onMount(): void {
+    super.onMount();
+    this.setupContextBindings();
+    this.setupRouteReaction();
+  }
+
+  protected onUnmount(): void {
+    this.teardownRuntime();
+    super.onUnmount();
+  }
+
+  /**
+   * 安装运行时上下文属性。
+   *
+   * @returns {void}
+   */
+  private setupContextBindings() {
+    this.flowEngine.context.defineProperty('currentRoute', {
+      get: () => this.getCurrentRouteByActivePage(),
+      // 切页后需要立即读取当前激活页面的路由，不能复用首次访问时的缓存值。
+      cache: false,
+    });
+    this.flowEngine.context.defineProperty('layoutContentElement', {
+      get: () => this.layoutContentElement,
+      // 布局容器 ref 会在挂载和卸载时变化，这里必须实时读取。
+      cache: false,
+    });
+    this.flowEngine.context.defineProperty('isMobileLayout', {
+      get: () => this.isMobileLayout,
+      observable: true,
+      cache: false,
+    });
+  }
+
+  /**
+   * 安装路由同步 reaction。
+   *
+   * @returns {void}
+   */
+  private setupRouteReaction() {
+    if (this.routeDisposer) {
+      return;
+    }
+
+    this.routeDisposer = reaction(
+      () => this.flowEngine.context.route,
+      (route) => {
+        this.activePageUid = route?.params?.name || '';
+        this.getCoordinator().syncRoute(route || {});
+      },
+      {
+        fireImmediately: true,
+      },
+    );
+  }
+
+  /**
+   * 释放运行时状态。
+   *
+   * @returns {void}
+   */
+  private teardownRuntime() {
+    this.routeDisposer?.();
+    this.routeDisposer = undefined;
+    this.routeCoordinator?.destroy();
+    this.routeCoordinator = undefined;
+    this.routePageMetaMap.clear();
+    this.activePageUid = '';
+    this.layoutContentElement = null;
+  }
+
+  /**
+   * 获取当前激活页面对应的路由对象。
+   *
+   * @returns {any} 当前激活页面对应的路由对象
+   */
+  private getCurrentRouteByActivePage() {
+    return this.getCurrentRouteByPageUid(this.activePageUid);
+  }
+
+  /**
+   * 根据页面 UID 获取路由对象。
+   *
+   * @param {string} pageUid 页面 UID
+   * @returns {any} 路由对象
+   */
+  private getCurrentRouteByPageUid(pageUid: string) {
+    return this.flowEngine.context.routeRepository?.getRouteBySchemaUid?.(pageUid) || {};
+  }
+
+  /**
+   * 懒加载页面路由协调器。
+   *
+   * @returns {AdminLayoutRouteCoordinator} 路由协调器实例
+   */
+  private getCoordinator() {
+    if (!this.routeCoordinator) {
+      this.routeCoordinator = new AdminLayoutRouteCoordinator(this.flowEngine);
+    }
+    return this.routeCoordinator;
+  }
+
+  render() {
+    return <AdminLayoutComponent {...this.props} />;
+  }
+}
+
+AdminLayoutModel.registerFlow({
+  key: 'topbarAction',
+  steps: {
+    step1: {
+      handler: async (ctx, params) => {
+        const topbarActionModels = await ctx.engine.getSubclassesOfAsync('TopbarActionModel');
+        const actions = [...topbarActionModels.keys()].map<TopbarActionModel>((name) => {
+          return ctx.engine.createModel({
+            use: name,
+            uid: `topbar-action-${name}`,
+          });
+        });
+        ctx.model.props.actionsRender = (props) => {
+          return [<TopbarActionsBar key="topbar-actions" actions={actions} isMobile={props?.isMobile} />];
+        };
+      },
+    },
+  },
+});
+
+/**
+ * 获取或创建 admin-layout host model。
+ *
+ * @param {FlowEngine} flowEngine FlowEngine 实例
+ * @param {GetAdminLayoutModelOptions<TModel>} options 获取选项
+ * @returns {TModel | undefined} 命中的 admin-layout model
+ * @throws {Error} 当 required 为 true 且模型不存在时抛错
+ */
+export function getAdminLayoutModel<TModel extends FlowModel = AdminLayoutModel>(
+  flowEngine: FlowEngine,
+  options: GetAdminLayoutModelOptions<TModel> = {},
+) {
+  const { required = false, create = false, props, use } = options;
+  let model = flowEngine.getModel<TModel>(ADMIN_LAYOUT_MODEL_UID);
+
+  if (!model && create) {
+    const ModelClass = (use || AdminLayoutModel) as new (...args: any[]) => TModel;
+    model = flowEngine.createModel<TModel>({
+      uid: ADMIN_LAYOUT_MODEL_UID,
+      use: ModelClass,
+      props,
+    });
+  }
+
+  if (model && props) {
+    model.setProps(props);
+  }
+
+  if (!model && required) {
+    throw new Error('[NocoBase] FlowRoute requires admin-layout-model. Please render FlowRoute under AdminLayout.');
+  }
+
+  return model;
+}

package/src/flow/admin-shell/admin-layout/AdminLayoutSlotModels.tsx

@@ -0,0 +1,127 @@
+/**
+ * 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 { HighlightOutlined } from '@ant-design/icons';
+import { css } from '@emotion/css';
+import { observer, useFlowEngine } from '@nocobase/flow-engine';
+import { Result, theme as antdTheme } from 'antd';
+import React, { FC, useCallback, useMemo } from 'react';
+import { useTranslation } from 'react-i18next';
+import { Outlet, useLocation } from 'react-router-dom';
+
+type AdminLayoutContentProps = {
+  onContentElementChange?: (element: HTMLDivElement | null) => void;
+};
+
+const layoutContentClass = css`
+  display: flex;
+  flex-direction: column;
+  position: relative;
+  height: calc(100vh - var(--nb-header-height));
+  > div {
+    position: relative;
+  }
+  .ant-layout-footer {
+    position: absolute;
+    bottom: 0;
+    text-align: center;
+    width: 100%;
+    z-index: 0;
+    padding: 0px 50px;
+  }
+`;
+
+const pageContentStyle: React.CSSProperties = {
+  flex: 1,
+  overflowY: 'auto',
+};
+
+const mobileHeight = {
+  height: `calc(100dvh - var(--nb-header-height))`,
+};
+
+/**
+ * 检测当前浏览器是否支持 dvh，移动端支持时优先使用它计算可视区域高度。
+ *
+ * @returns {boolean} 是否支持 dvh 单位
+ */
+function isDvhSupported() {
+  if (typeof document === 'undefined') {
+    return false;
+  }
+
+  const testEl = document.createElement('div');
+  testEl.style.height = '1dvh';
+  return testEl.style.height === '1dvh';
+}
+
+const ShowTipWhenNoPages = observer(() => {
+  const flowEngine = useFlowEngine();
+  const { token } = antdTheme.useToken();
+  const { t } = useTranslation();
+  const location = useLocation();
+  const allAccessRoutes = flowEngine.context.routeRepository?.listAccessible?.() || [];
+  const designable = !!flowEngine.context.flowSettingsEnabled;
+
+  if (allAccessRoutes.length === 0 && !designable && ['/admin', '/admin/'].includes(location.pathname)) {
+    return (
+      <Result
+        icon={<HighlightOutlined style={{ fontSize: '8em', color: token.colorText }} />}
+        title={t('No pages yet, please configure first')}
+        subTitle={t(`Click the "UI Editor" icon in the upper right corner to enter the UI Editor mode`)}
+      />
+    );
+  }
+
+  return null;
+});
+
+/**
+ * AdminLayout 内部使用的内容区容器。
+ *
+ * 内容区不再依赖独立 FlowModel，而是通过回调把挂载目标同步给 root model。
+ */
+export const AdminLayoutContent: FC<AdminLayoutContentProps> = ({ onContentElementChange }) => {
+  const style = useMemo(() => (isDvhSupported() ? mobileHeight : undefined), []);
+  const bindLayoutContentRef = useCallback(
+    (node: HTMLDivElement | null) => {
+      // shell 直接渲染内容区时，仍需把挂载目标同步给 root model。
+      onContentElementChange?.(node);
+    },
+    [onContentElementChange],
+  );
+
+  return (
+    <div
+      ref={bindLayoutContentRef}
+      className={`${layoutContentClass} nb-subpages-slot-without-header-and-side`}
+      style={style}
+    >
+      <div style={pageContentStyle}>
+        <Outlet />
+        <ShowTipWhenNoPages />
+      </div>
+    </div>
+  );
+};
+
+/**
+ * 兼容旧 API 的独立 LayoutContent 组件。
+ *
+ * 旧调用方可能只需要一个不带顶部和侧边栏的内容容器，
+ * 这时不一定存在 AdminLayout root model，因此这里保留一个可独立渲染的版本。
+ *
+ * @example
+ * ```typescript
+ * <LayoutContent />
+ * ```
+ */
+export const LayoutContent: FC = () => {
+  return <AdminLayoutContent />;
+};

package/src/flow/admin-shell/admin-layout/HelpLite.tsx

@@ -0,0 +1,193 @@
+/**
+ * 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 { QuestionCircleOutlined } from '@ant-design/icons';
+import { css } from '@emotion/css';
+import { observer, useFlowEngine } from '@nocobase/flow-engine';
+import { parseHTML } from '@nocobase/utils/client';
+import { Dropdown, Menu, Popover, theme as antdTheme } from 'antd';
+import type { MenuItemType, MenuDividerType } from 'antd/es/menu/interface';
+import React, { useEffect, useMemo, useState } from 'react';
+import { useTranslation } from 'react-i18next';
+import { usePlugin } from '../../../flow-compat';
+import type { CustomToken } from '../../../theme';
+
+type SettingsMenuItemType = MenuItemType | MenuDividerType;
+
+/**
+ * 读取当前应用信息，避免继续依赖旧的 CurrentAppInfoProvider。
+ */
+function useCurrentAppInfoLite() {
+  const flowEngine = useFlowEngine();
+  const [data, setData] = useState<any>();
+
+  useEffect(() => {
+    let active = true;
+
+    Promise.resolve(flowEngine.context.appInfo)
+      .then((info) => {
+        if (active) {
+          setData(info);
+        }
+      })
+      .catch((error) => {
+        console.error(error);
+      });
+
+    return () => {
+      active = false;
+    };
+  }, [flowEngine]);
+
+  return data;
+}
+
+const helpClassName = css`
+  display: inline-block;
+  vertical-align: top;
+  width: 46px;
+  height: 46px;
+  &:hover {
+    background: rgba(255, 255, 255, 0.1) !important;
+  }
+`;
+
+const SettingsMenu: React.FC = () => {
+  const { t } = useTranslation();
+  const appInfo = useCurrentAppInfoLite();
+  const { token } = antdTheme.useToken();
+  const isSimplifiedChinese = appInfo?.lang === 'zh-CN';
+
+  const items: SettingsMenuItemType[] = useMemo(
+    () => [
+      {
+        key: 'nocobase',
+        disabled: true,
+        label: (
+          <div style={{ cursor: 'text' }}>
+            <div style={{ color: token.colorText }}>NocoBase</div>
+            <div style={{ fontSize: '0.8em', color: token.colorTextDescription }}>v{appInfo?.version}</div>
+          </div>
+        ),
+      },
+      {
+        key: 'divider_1',
+        type: 'divider',
+      },
+      {
+        key: 'homePage',
+        label: (
+          <a
+            href={isSimplifiedChinese ? 'https://www.nocobase.com/cn/' : 'https://www.nocobase.com'}
+            target="_blank"
+            rel="noreferrer"
+          >
+            {t('Home page')}
+          </a>
+        ),
+      },
+      {
+        key: 'userManual',
+        label: (
+          <a
+            href={
+              isSimplifiedChinese ? 'https://v2.docs.nocobase.com/cn/guide/' : 'https://v2.docs.nocobase.com/guide/'
+            }
+            target="_blank"
+            rel="noreferrer"
+          >
+            {t('Handbook')}
+          </a>
+        ),
+      },
+      {
+        key: 'license',
+        label: (
+          <a
+            href={
+              isSimplifiedChinese ? 'https://www.nocobase.com/cn/agreement' : 'https://www.nocobase.com/en/agreement'
+            }
+            target="_blank"
+            rel="noreferrer"
+          >
+            {t('License')}
+          </a>
+        ),
+      },
+    ],
+    [appInfo?.version, isSimplifiedChinese, t, token.colorText, token.colorTextDescription],
+  );
+
+  return <Menu items={items} />;
+};
+
+/**
+ * flow 内的轻量帮助入口。
+ */
+export const HelpLite = observer(
+  () => {
+    const [visible, setVisible] = useState(false);
+    const { token } = antdTheme.useToken();
+    const customToken = token as CustomToken;
+    const customBrandPlugin: any = usePlugin('@nocobase/plugin-custom-brand');
+    const appInfo = useCurrentAppInfoLite();
+
+    const icon = (
+      <span
+        data-testid="help-button"
+        className={css`
+          max-width: 160px;
+          overflow: hidden;
+          display: inline-block;
+          line-height: 12px;
+          white-space: nowrap;
+          text-overflow: ellipsis;
+        `}
+        style={{ cursor: 'pointer', padding: '16px', color: customToken.colorTextHeaderMenu }}
+      >
+        <QuestionCircleOutlined />
+      </span>
+    );
+
+    if (customBrandPlugin?.options?.options?.about) {
+      const appVersion = `<span class="nb-app-version">v${appInfo?.version}</span>`;
+      const content = parseHTML(customBrandPlugin.options.options.about, { appVersion });
+
+      return (
+        <div className={helpClassName}>
+          <Popover
+            rootClassName="nb-about"
+            placement="bottomRight"
+            arrow={false}
+            content={<div dangerouslySetInnerHTML={{ __html: content }}></div>}
+          >
+            {icon}
+          </Popover>
+        </div>
+      );
+    }
+
+    return (
+      <div className={helpClassName}>
+        <Dropdown
+          open={visible}
+          onOpenChange={(nextVisible) => {
+            setVisible(nextVisible);
+          }}
+          dropdownRender={() => {
+            return <SettingsMenu />;
+          }}
+        >
+          {icon}
+        </Dropdown>
+      </div>
+    );
+  },
+  { displayName: 'HelpLite' },
+);