@regenbio/regenbio-components-react 1.2.14 → 1.2.16

package/packages/layout/src/components/Help/AsyncContentPanel.tsx

@@ -0,0 +1,62 @@
+import { Spin } from 'antd';
+import { useContext, useEffect, useState } from 'react';
+import type {
+  ProHelpDataSource,
+  ProHelpDataSourceChildren,
+} from './HelpProvide';
+import { ProHelpProvide } from './HelpProvide';
+import { RenderContentPanel } from './RenderContentPanel';
+
+/**
+ * 异步加载内容的面板组件
+ * @param item 指向当前面板的 ProHelpDataSource
+ */
+export const AsyncContentPanel: React.FC<{
+  item: ProHelpDataSource<any>['children'][number];
+  onInit?: (ref: HTMLDivElement) => void;
+}> = ({ item, onInit }) => {
+  const { onLoadContext } = useContext(ProHelpProvide); // 获取上下文中的 onLoadContext
+  const [loading, setLoading] = useState(false); // 加载状态
+  const [content, setContent] = useState<ProHelpDataSourceChildren<any>[]>(); // 内容数据
+
+  useEffect(() => {
+    if (!item.key) return; // 如果没有key则返回
+    setLoading(true); // 开始加载
+    onLoadContext?.(item.key, item).then((res) => {
+      // 调用加载方法
+      setLoading(false); // 加载完成
+      setContent(res); // 设置内容数据
+    });
+  }, [item.key]);
+
+  // 如果没有key，则返回null
+  if (!item.key) return null;
+
+  // 如果正在加载并且有key，则显示加载中的状态
+  if (loading && item.key) {
+    return (
+      <div
+        key={item.key}
+        style={{
+          display: 'flex',
+          justifyContent: 'center',
+          width: '100%',
+          boxSizing: 'border-box',
+          padding: 24,
+        }}
+      >
+        <Spin />
+      </div>
+    );
+  }
+
+  // 加载完成后，渲染内容面板
+  return (
+    <RenderContentPanel
+      onInit={(ref) => {
+        onInit?.(ref);
+      }}
+      dataSourceChildren={content!}
+    />
+  );
+};

package/packages/layout/src/components/Help/HelpProvide.tsx

@@ -0,0 +1,187 @@
+import type { ImageProps } from 'antd';
+import type { AnchorHTMLAttributes } from 'react';
+import React from 'react';
+
+/**
+ * ProHelp 数据源子项内容类型。
+ * 该类型定义了多种数据源子项内容类型，例如 h1、h2、link、text、image等。
+ * 其中，link 和 inlineLink 属性都是链接类型的数据源子项内容，不同的是 inlineLink 是内联链接，而 link 是块级链接。
+ *
+ * @typedef {object} ProHelpDataSourceContentType
+ * @property {string} h1 标题1类型的数据源子项内容。
+ * @property {string} h2 标题2类型的数据源子项内容。
+ * @property {{ children: string } & React.AnchorHTMLAttributes<HTMLAnchorElement>} link 链接类型的数据源子项内容。
+ * @property {{ children: string } & React.AnchorHTMLAttributes<HTMLAnchorElement>} inlineLink 内联链接类型的数据源子项内容。
+ * @property {string} text 文本类型的数据源子项内容。
+ * @property {ImageProps} image 图片类型的数据源子项内容。
+ */
+type ProHelpDataSourceContentType = {
+  /**
+   * h1 标题1类型的数据源子项内容。
+   */
+  h1: string;
+  /**
+   * h2 标题1类型的数据源子项内容。
+   */
+  h2: string;
+  /**
+   * link 链接类型的数据源子项内容。
+   */
+  link: {
+    children: string;
+  } & AnchorHTMLAttributes<HTMLAnchorElement>;
+  /**
+   * 行内链接类型的数据源子项内容。
+   */
+  inlineLink: {
+    children: string;
+  } & AnchorHTMLAttributes<HTMLAnchorElement>;
+
+  /**
+   * navigation 类型链接，或切换菜单
+   */
+  navigationSwitch: {
+    selectKey: string;
+    children: string;
+  };
+
+  /**
+   * text 文本类型的数据源子项内容。
+   */
+  text: string;
+
+  /**
+   * image 图片类型的数据源子项内容。
+   */
+  image: ImageProps;
+
+  /**
+   * markdown 类型的渲染，支持 基本的 markdown 语法
+   * 会包在一个叫 inner-html 为 markdown 的 div 中
+   */
+  html: {
+    className: string;
+    children: string;
+  };
+};
+
+/**
+ * ProHelp 数据源子项内容类型的类型，可能的取值为 "h1"、"h2"、"link"、"inlineLink"、"text" 和 "image"。
+ * @typedef {'h1' | 'h2' | 'link' | 'inlineLink' | 'text' | 'image'} ProHelpDataSourceChildrenType
+ */
+type ProHelpDataSourceChildrenType = Extract<
+  keyof ProHelpDataSourceContentType,
+  any
+>;
+
+/**
+ * ProHelp 数据源子项内容属性类型。
+ * @template ValueType 数据源项值的类型，默认为 'text'。
+ * 该类型定义了一个名为 children 的对象属性，根据 valueType 属性的值来确定该属性对象的具体类型，
+ * 如果 valueType 的类型是 ProHelpDataSourceChildrenType，
+ * 则使用 ProHelpDataSourceContentType 中 ProHelpDataSourceChildrenType 所对应的属性类型；
+ * 否则，使用 ProHelpDataSourceContentType 中 ValueType 所对应的属性类型。
+ */
+type ProHelpDataSourceContentProps<ValueTypeMap, ValueType> =
+  ValueType extends ProHelpDataSourceChildrenType
+    ? ProHelpDataSourceContentType[ValueType]
+    : ValueType extends keyof ValueTypeMap
+    ? ValueTypeMap[ValueType]
+    : ProHelpDataSourceContentType[ProHelpDataSourceChildrenType];
+
+/**
+ * ProHelp 数据源子项类型。
+ * @template ValueTypeMap 数据源项值的类型，默认为 'text'。
+ * @property {(ValueType | ProHelpDataSourceChildrenType)} valueType 数据源子项值的类型，可以为指定的类型，也可以是自定义类型。
+ * @property {ProHelpDataSourceContentProps<ValueType>} children 包含数据源子项内容的对象。
+ */
+export type ProHelpDataSourceChildren<
+  ValueTypeMap = {
+    text: string;
+  },
+> = {
+  /**
+   * 包含数据源子项内容的对象。
+   * @template ValueType 数据源项值的类型，默认为 'text'。
+   */
+  valueType: ValueTypeMap extends Map<infer ValueType, any>
+    ? ValueType
+    : keyof ValueTypeMap | ProHelpDataSourceChildrenType;
+  /**
+   * 数据源子项值的类型。
+   * @typedef {(ValueTypeMap | ProHelpDataSourceChildrenType)} ProHelpDataSourceChildrenType
+   */
+  children: ProHelpDataSourceContentProps<
+    ValueTypeMap,
+    keyof ValueTypeMap | ProHelpDataSourceChildrenType
+  >;
+};
+
+/**
+ * ProHelp 数据源类型。
+ * @template ValueType 数据源项值的类型，默认为 'text'。
+ * @property {string} key 数据源项的唯一标识。
+ * @property {string} title 数据源项的标题。
+ * @property children 包含子项的数组，每个子项包含一个唯一标识，标题以及子子项数组。
+ */
+export type ProHelpDataSource<ValueType = 'text'> = {
+  /**
+   * key 数据源项的唯一标识
+   */
+  key: string;
+  /**
+   * title 数据源项的标题。
+   */
+  title: string;
+
+  /**
+   * 在一页内加载所有的 children 内容
+   */
+  infiniteScrollFull?: boolean;
+  /**
+   * children 包含子项的数组，每个子项包含一个唯一标识，标题以及子子项数组。
+   */
+  children: {
+    key: string;
+    title: string;
+    /**
+     * 是否远程加载children
+     */
+    asyncLoad?: boolean;
+    children?: ProHelpDataSourceChildren<ValueType>[];
+  }[];
+};
+
+/**
+ * 这段代码定义了一个名为 ProHelpProvide 的 React 上下文对象，并且指定了该上下文对象的初始值为 { dataSource: [] }。
+ * 这个上下文对象中包含了一个名为 dataSource 的属性，该属性的值是一个数组，类型为 ProHelpDataSource<any>[]。
+ * 该上下文对象通常用于在 React 组件树中共享数据，即可以通过在组件中使用 ProHelpProvide.Provider 包裹一组组件，
+ * 将 dataSource 和 valueTypeMap 数据源传递给这些组件，这些组件即可从上下文中获取 dataSource 数据源，实现数据的共享和传递。
+ */
+export const ProHelpProvide = React.createContext<{
+  /**
+   * 帮助文档的数据源，包含一组帮助文档数据，每个数据包含标题和内容等信息。
+   */
+  dataSource: ProHelpDataSource<any>[];
+  /**
+   * 帮助组件的子组件，用于渲染自定义的帮助内容。
+   * 是一个键值对结构的集合，其中：
+   * 键（key）为字符串类型；
+   * 值（value）为一个函数类型，该函数接受两个参数：一个名为 item 的 ProHelpDataSourceChildren 类型的对象，表示一个 ProHelp 数据源子项的子项；
+   * 一个名为 index 的数字类型参数，表示该子项在父级子项数组中的索引。
+   * 该函数返回一个 ReactNode 类型的元素，用于表示该 ProHelp 数据源子项子项应该渲染的 UI 元素。
+   * 这个 Map 的作用是将 ProHelp 数据源子项子项的 valueType 属性与对应的渲染函数进行映射，从而实现在渲染 ProHelp 数据源时动态地选择渲染方法。
+   * 在实际使用时，我们可以通过判断子项的 valueType 属性，从 valueTypeMap 中取出对应的渲染函数，再将该子项和渲染函数作为参数传入 renderDataSourceItem 函数中即可。
+   */
+  valueTypeMap: Map<
+    string,
+    (item: ProHelpDataSourceChildren<any>, index: number) => React.ReactNode
+  >;
+  /**
+   * 加载数据源的函数,如果把数据源设置为 async load就可以使用这个功能。
+   */
+  onLoadContext?: (
+    key: React.Key,
+    context: ProHelpDataSource<any>['children'][number],
+  ) => Promise<ProHelpDataSourceChildren<any>[]>;
+}>({ dataSource: [], valueTypeMap: new Map() });

package/packages/layout/src/components/Help/ProHelpContentPanel.tsx

@@ -0,0 +1,162 @@
+import { ProProvider } from '@ant-design/pro-provider';
+import { useDebounceFn } from '@ant-design/pro-utils';
+import classNames from 'classnames';
+import React, { useContext, useEffect, useMemo, useRef } from 'react';
+import { AsyncContentPanel } from './AsyncContentPanel';
+import type { ProHelpDataSource } from './HelpProvide';
+import { ProHelpProvide } from './HelpProvide';
+import { RenderContentPanel } from './RenderContentPanel';
+
+export type ProHelpContentPanelProps = {
+  /**
+   * 控制当前选中的帮助文档
+   */
+  selectedKey: React.Key;
+  className?: string;
+  parentItem?: ProHelpDataSource<any>;
+
+  onScroll?: (key?: string) => void;
+};
+
+/**
+ * 控制具体的帮助文档显示组件
+ * selectedKey 来展示对应的内容。它会根据不同的item.valueType值来展示不同的内容，包括标题、图片、超链接等。
+ * @param ProHelpContentPanelProps
+ * @returns
+ */
+export const ProHelpContentPanel: React.FC<ProHelpContentPanelProps> = ({
+  className,
+  parentItem,
+  selectedKey,
+  onScroll,
+}) => {
+  const { dataSource } = useContext(ProHelpProvide);
+  const { hashId } = useContext(ProProvider);
+  // 记录每个面板的滚动高度
+  const scrollHeightMap = useRef<Map<React.Key, HTMLDivElement>>(new Map());
+
+  const divRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    if (!selectedKey || !parentItem?.infiniteScrollFull) return;
+    const div = scrollHeightMap.current.get(selectedKey);
+
+    if (div?.offsetTop && divRef.current) {
+      if (
+        Math.abs(divRef.current!.scrollTop - div?.offsetTop + 40) >
+        div?.clientHeight
+      ) {
+        divRef.current!.scrollTop = div?.offsetTop - 40;
+      }
+    }
+  }, [selectedKey]);
+
+  /**
+   * debounce（防抖）处理滚动事件，并根据滚动位置来实现找到当前列表的 key
+   */
+  const onScrollEvent = useDebounceFn(async (e: Event) => {
+    const dom = e?.target as HTMLDivElement;
+
+    // 根据滚动位置来找到当前列表的 key
+    const list = Array.from(scrollHeightMap.current.entries()).find(
+      ([, value]) => {
+        if (dom?.scrollTop < value.offsetTop) {
+          return true;
+        }
+        return false;
+      },
+    );
+
+    if (!list) {
+      return;
+    }
+
+    // 如果获取的 key 和当前 key 不同丢弃掉
+    if (list.at(0) !== selectedKey) {
+      // 如果不同，则触发 onScroll 事件
+      onScroll?.(list.at(0) as string | undefined);
+    }
+  }, 200);
+
+  /**
+   * 当 parentItem 组件中的 infiniteScrollFull 属性变化时
+   * 如果该属性为真值，则开始监听滚动事件；
+   * 如果为假值，则停止监听滚动事件并取消防抖处理。
+   * 在监听滚动事件时，可以实现分页（瀑布流）效果。同时，该代码还会根据 selectedKey 的变化来触发跳转
+   */
+  useEffect(() => {
+    if (!parentItem?.infiniteScrollFull) return;
+    onScrollEvent.cancel();
+    divRef.current?.addEventListener('scroll', onScrollEvent.run, false);
+    return () => {
+      onScrollEvent.cancel();
+      divRef.current?.removeEventListener('scroll', onScrollEvent.run, false);
+    };
+  }, [parentItem?.infiniteScrollFull, selectedKey]);
+
+  /**
+   * 生成一个  Map  能根据 key 找到所有的 index
+   */
+  const dataSourceMap = useMemo(() => {
+    const map = new Map<
+      React.Key,
+      ProHelpDataSource<any>['children'][number] & {
+        parentKey?: React.Key;
+      }
+    >();
+    dataSource.forEach((page) => {
+      page.children.forEach((item) => {
+        map.set(item.key || item.title, { ...item, parentKey: page.key });
+      });
+    });
+    return map;
+  }, [dataSource]);
+
+  const renderItem = (item: ProHelpDataSource<any>['children'][number]) => {
+    if (item?.asyncLoad) {
+      return (
+        <div className={classNames(className, hashId)} id={item.title}>
+          <AsyncContentPanel
+            key={item?.key}
+            item={item!}
+            onInit={(ref) => {
+              if (!scrollHeightMap.current) return;
+              scrollHeightMap.current.set(item.key, ref);
+            }}
+          />
+        </div>
+      );
+    }
+
+    return (
+      <div className={classNames(className, hashId)} id={item.title}>
+        <RenderContentPanel
+          onInit={(ref) => {
+            if (!scrollHeightMap.current) return;
+            scrollHeightMap.current.set(item.key, ref);
+          }}
+          dataSourceChildren={item?.children || []}
+        />
+      </div>
+    );
+  };
+
+  if (parentItem && parentItem.infiniteScrollFull) {
+    return (
+      <div
+        ref={divRef}
+        className={classNames(`${className}-infinite-scroll`, hashId)}
+        style={{
+          overflow: 'auto',
+        }}
+      >
+        {parentItem.children?.map((item) => {
+          return (
+            <React.Fragment key={item.key}>{renderItem(item)}</React.Fragment>
+          );
+        })}
+      </div>
+    );
+  }
+  return renderItem(dataSourceMap.get(selectedKey!)!);
+};

package/packages/layout/src/components/Help/ProHelpDrawer.tsx

@@ -0,0 +1,54 @@
+import type { DrawerProps } from 'antd';
+import { Drawer } from 'antd';
+import useMergedState from 'rc-util/es/hooks/useMergedState';
+import type { ProHelpPanelProps } from './ProHelpPanel';
+import { ProHelpPanel } from './ProHelpPanel';
+
+export type ProHelpDrawerProps = {
+  /**
+   * Ant Design Drawer 组件的 Props，可以传递一些选项，如位置、大小、关闭方式等等。
+   */
+  drawerProps: DrawerProps;
+} & Omit<ProHelpPanelProps, 'onClose'>;
+
+/**
+ * 渲染一个抽屉，其中显示了一个 ProHelpPanel。
+ * @param drawerProps 要传递给 Drawer 组件的属性。
+ * @param props 要传递给 ProHelpPanel 组件的属性。
+ */
+export const ProHelpDrawer: React.FC<ProHelpDrawerProps> = ({
+  drawerProps,
+  ...props
+}) => {
+  const [drawerOpen, setDrawerOpen] = useMergedState<boolean>(false, {
+    value: drawerProps.open,
+    onChange: drawerProps.afterOpenChange,
+  });
+  return (
+    <Drawer
+      width={720}
+      closeIcon={null}
+      styles={{
+        header: {
+          display: 'none',
+        },
+        body: {
+          padding: 0,
+        },
+      }}
+      maskClosable
+      {...drawerProps}
+      open={drawerOpen}
+      onClose={() => setDrawerOpen(false)}
+      afterOpenChange={(open) => {
+        setDrawerOpen(open);
+      }}
+    >
+      <ProHelpPanel
+        {...props}
+        onClose={() => setDrawerOpen(false)}
+        bordered={false}
+      />
+    </Drawer>
+  );
+};

package/packages/layout/src/components/Help/ProHelpModal.tsx

@@ -0,0 +1,51 @@
+import type { ModalProps } from 'antd';
+import { Modal } from 'antd';
+import useMergedState from 'rc-util/es/hooks/useMergedState';
+import type { ProHelpPanelProps } from './ProHelpPanel';
+import { ProHelpPanel } from './ProHelpPanel';
+export type ProHelpModalProps = {
+  /**
+   * Ant Design Modal 组件的 props，可以传递一些选项，如位置、大小、关闭方式等等。
+   */
+  modalProps?: ModalProps;
+} & Omit<ProHelpPanelProps, 'onClose'>;
+
+/**
+ * 渲染一个模态对话框，其中显示了一个 ProHelpPanel。
+ * @param modalProps 要传递给 Modal 组件的属性。
+ * @param props 要传递给 ProHelpPanel 组件的属性。
+ */
+export const ProHelpModal: React.FC<ProHelpModalProps> = ({
+  modalProps,
+  ...props
+}) => {
+  const [modalOpen, setModalOpen] = useMergedState<boolean>(false, {
+    value: modalProps?.open,
+    onChange: modalProps?.afterClose,
+  });
+  return (
+    <Modal
+      onCancel={() => {
+        setModalOpen(false);
+      }}
+      styles={{
+        body: {
+          margin: -24,
+        },
+      }}
+      centered
+      closable={false}
+      footer={null}
+      width={720}
+      open={modalOpen}
+      maskClosable
+      {...modalProps}
+    >
+      <ProHelpPanel
+        height={648}
+        {...props}
+        onClose={() => setModalOpen(false)}
+      />
+    </Modal>
+  );
+};