@regenbio/regenbio-components-react 1.2.14 → 1.2.16

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

@@ -0,0 +1,310 @@
+import { CloseOutlined, ProfileOutlined } from '@ant-design/icons';
+import { ProProvider, isNeedOpenHash } from '@ant-design/pro-provider';
+import { coverToNewToken } from '@ant-design/pro-utils';
+import { Card, ConfigProvider, Menu } from 'antd';
+import useMergedState from 'rc-util/es/hooks/useMergedState';
+import React, { useContext, useMemo, useState } from 'react';
+import type { ProHelpDataSource } from './HelpProvide';
+import { ProHelpProvide } from './HelpProvide';
+import { ProHelpContentPanel } from './ProHelpContentPanel';
+import { ProHelpSelect } from './Search';
+import { useStyle } from './style';
+
+export const SelectKeyProvide = React.createContext<{
+  selectedKey: string | undefined;
+  setSelectedKey: (key: string | undefined) => void;
+}>({
+  selectedKey: undefined,
+  setSelectedKey: () => {},
+});
+
+export type ProHelpPanelProps = {
+  /**
+   * 帮助面板的标题
+   */
+  title?: string;
+  /**
+   * 帮助面板首次打开时的默认选中文档的键名
+   */
+  defaultSelectedKey?: string;
+  /**
+   * 当前选中的帮助文档的键名。如果提供了这个 prop，那么该组件将是一个受控组件，其状态将由父组件管理。如果未提供，那么该组件将是一个非受控组件，其状态将在组件内部管理。
+   */
+  selectedKey?: string;
+  /**
+   * 当选中的文档键名发生变化时调用的回调函数。新的键名将作为参数传递给该函数。
+   */
+  onSelectedKeyChange?: (key: string | undefined) => void;
+  /**
+   *控制左侧面板是否能够打开
+   */
+  showLeftPanel?: boolean;
+  /**
+   * 当左侧面板打开状态发生变化时调用的回调函数。新的打开状态将作为参数传递给该函数。
+   */
+  onShowLeftPanelChange?: (show: boolean) => void;
+  /**
+   * 是否显示边框
+   */
+  bordered?: boolean;
+
+  /**
+   * 当帮助面板关闭时调用的回调函数。
+   */
+  onClose?: () => void;
+
+  /**
+   * 帮助面板的高度，可以是数字或字符串类型。
+   */
+  height?: number | string;
+
+  /**
+   * 帮助面板的页脚
+   */
+  footer?: React.ReactNode;
+
+  /**
+   * 在一页内加载所有的 children 内容
+   */
+  infiniteScrollFull?: boolean;
+
+  /**
+   * 自定义渲染 extra 部分的内容
+   *
+   * @param {React.ReactNode} collapsePannelAction - 折叠收起的左侧按钮
+   * @param {React.ReactNode} helpSelectAction - 默认的帮助筛选按钮
+   * @param {React.ReactNode} closeAction - 关闭操作按钮
+   * @returns {React.ReactNode} - 返回自定义渲染的 extra 操作按钮
+   *
+   */
+  extraRender?: (
+    collapsePannelAction: React.ReactNode,
+    helpSelectAction: React.ReactNode,
+    closeAction: React.ReactNode,
+  ) => React.ReactNode;
+};
+/**
+ * ProHelpPanel 组件是一个帮助中心面板组件，具有可折叠的左侧菜单和右侧帮助内容区域。
+ * 左侧菜单显示了帮助文档的目录结构，右侧帮助内容区域显示了用户选中的帮助文档内容。
+ * 在左侧菜单中，用户可以通过点击目录来选择并显示相应的文档内容。
+ * @param param0
+ * @returns
+ */
+export const ProHelpPanel: React.FC<ProHelpPanelProps> = ({
+  title = '帮助中心',
+  bordered = true,
+  onClose,
+  footer,
+  height,
+  extraRender,
+  ...props
+}) => {
+  const { getPrefixCls } = useContext(ConfigProvider.ConfigContext);
+  const className = getPrefixCls('pro-help');
+  const { wrapSSR, hashId } = useStyle(className);
+  const { dataSource } = useContext(ProHelpProvide);
+  const [selectedKey, setSelectedKey] = useMergedState<string | undefined>(
+    undefined,
+    {
+      defaultValue: props.defaultSelectedKey,
+      value: props.selectedKey,
+      onChange: props.onSelectedKeyChange,
+    },
+  );
+  const [openKey, setOpenKey] = useState('');
+  const { token } = useContext(ProProvider);
+  const [showLeftPanel, setShowLeftPanel] = useMergedState(true, {
+    value: props.showLeftPanel,
+    onChange: props.onShowLeftPanelChange,
+  });
+
+  const dataSourceKeyMap = useMemo(() => {
+    const map = new Map<
+      React.Key,
+      ProHelpDataSource<any> & {
+        parentKey?: React.Key;
+      }
+    >();
+    dataSource.forEach((page) => {
+      map.set(page.key, page);
+      page.children?.forEach((item) => {
+        map.set(item.key || item.title, {
+          parentKey: page.key,
+          ...item,
+        } as unknown as ProHelpDataSource<any>);
+      });
+    });
+    return map;
+  }, [dataSource]);
+
+  const parentKey = useMemo(
+    () => dataSourceKeyMap.get(selectedKey!)?.parentKey as string,
+    [dataSourceKeyMap, selectedKey],
+  );
+
+  const defaultExtraActions = {
+    collapsePanelAction: (
+      <div className={`${className}-actions-item ${hashId}`.trim()}>
+        <ProfileOutlined
+          title="collapse panel"
+          onClick={() => {
+            setShowLeftPanel(!showLeftPanel);
+          }}
+        />
+      </div>
+    ),
+    helpSelectAction: (
+      <ProHelpSelect
+        iconClassName={`${className}-actions-item`}
+        className={`${hashId} ${className}-actions-input`}
+        value={selectedKey}
+        onChange={(value, item) => {
+          setSelectedKey(value);
+          setOpenKey((item as any)?.dataItemKey);
+        }}
+      />
+    ),
+    closeAction: (
+      <div className={`${className}-actions-item ${hashId}`.trim()}>
+        <CloseOutlined
+          title="close panel"
+          onClick={() => {
+            onClose?.();
+          }}
+        />
+      </div>
+    ),
+  };
+
+  const extraDomList = () => {
+    return (
+      <div className={`${className}-actions ${hashId}`.trim()}>
+        {extraRender ? (
+          extraRender(
+            defaultExtraActions.collapsePanelAction,
+            defaultExtraActions.helpSelectAction,
+            defaultExtraActions.closeAction,
+          )
+        ) : (
+          <>
+            {defaultExtraActions.collapsePanelAction}
+            {defaultExtraActions.helpSelectAction}
+            {onClose ? defaultExtraActions.closeAction : null}
+          </>
+        )}
+      </div>
+    );
+  };
+
+  return wrapSSR(
+    <SelectKeyProvide.Provider
+      value={{
+        selectedKey: selectedKey,
+        setSelectedKey: setSelectedKey,
+      }}
+    >
+      <Card
+        bordered={bordered}
+        title={title}
+        bodyStyle={{
+          display: 'flex',
+          padding: 0,
+          margin: 0,
+          height: '100%',
+          width: '100%',
+        }}
+        size="small"
+        extra={extraDomList()}
+      >
+        {showLeftPanel ? (
+          <div
+            className={`${hashId} ${className}-left-panel `}
+            style={{
+              height,
+            }}
+          >
+            <ConfigProvider
+              theme={{
+                hashed: isNeedOpenHash(),
+                token: {
+                  lineHeight: 1.2,
+                  fontSize: 12,
+                  controlHeightLG: 26,
+                },
+                components: {
+                  Menu: coverToNewToken({
+                    radiusItem: token.borderRadius,
+                    colorActiveBarWidth: 0,
+                    colorActiveBarBorderSize: 0,
+                    colorItemBgSelected:
+                      token.layout?.sider?.colorBgMenuItemSelected ||
+                      'rgba(0, 0, 0, 0.04)',
+                    colorItemBgActive:
+                      token.layout?.sider?.colorBgMenuItemHover ||
+                      'rgba(0, 0, 0, 0.04)',
+                    colorItemText:
+                      token.layout?.sider?.colorTextMenu ||
+                      'rgba(0, 0, 0, 0.65)',
+                    colorItemTextHover:
+                      token.layout?.sider?.colorTextMenuActive ||
+                      'rgba(0, 0, 0, 0.85)',
+                    colorItemTextSelected:
+                      token.layout?.sider?.colorTextMenuSelected ||
+                      'rgba(0, 0, 0, 1)',
+                    colorItemBg: 'transparent',
+                    colorSubItemBg: 'transparent',
+                    popupBg: token?.colorBgElevated,
+                    darkPopupBg: token?.colorBgElevated,
+                  }),
+                },
+              }}
+            >
+              <Menu
+                className={`${hashId} ${className}-left-panel-menu`}
+                openKeys={[parentKey, openKey]}
+                onOpenChange={(keys) => {
+                  setOpenKey(keys.at(-1) || '');
+                }}
+                selectedKeys={selectedKey ? [selectedKey] : []}
+                onSelect={({ selectedKeys }) => {
+                  setSelectedKey(selectedKeys.at(-1) || '');
+                }}
+                mode="inline"
+                items={dataSource.map((item) => {
+                  return {
+                    key: item.key,
+                    label: item.title,
+                    children: item.children.map((child) => {
+                      return {
+                        key: child.key,
+                        label: child.title,
+                      };
+                    }),
+                  };
+                })}
+              />
+            </ConfigProvider>
+          </div>
+        ) : null}
+        <div
+          className={`${hashId} ${className}-content-panel`}
+          style={{
+            height,
+          }}
+        >
+          {selectedKey ? (
+            <ProHelpContentPanel
+              parentItem={dataSourceKeyMap.get(parentKey)}
+              className={`${className}-content-render`}
+              selectedKey={selectedKey}
+              onScroll={(key) => setSelectedKey(key)}
+            />
+          ) : null}
+          {footer ? (
+            <div className={`${hashId} ${className}-footer`}>{footer}</div>
+          ) : null}
+        </div>
+      </Card>
+    </SelectKeyProvide.Provider>,
+  );
+};

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

@@ -0,0 +1,78 @@
+import { ProProvider } from '@ant-design/pro-provider';
+import type { PopoverProps } from 'antd';
+import { ConfigProvider, Popover } from 'antd';
+import classNames from 'classnames';
+import React, { useContext } from 'react';
+import { ProHelpContentPanel } from './ProHelpContentPanel';
+import { useStyle } from './style';
+
+export type ProHelpPopoverProps = Omit<PopoverProps, 'content'> & {
+  /**
+   * 悬浮提示文字的 CSS 类名
+   */
+  textClassName?: string;
+
+  /**
+   * Popover 内容的 content 的 CSS 类名
+   */
+  popoverContextClassName?: string;
+
+  /**
+   * 悬浮提示文字的 CSS 样式对象
+   */
+  textStyle?: React.CSSProperties;
+
+  /**
+   * 当前选中的帮助文档的 key 值
+   */
+  selectedKey: string;
+
+  /**
+   * 可选的悬浮提示 Popover 组件的 Props，用于自定义悬浮提示的样式和行为。
+   * 该属性可以传递 Ant Design Popover 组件的 props，如位置、大小、触发方式等等
+   * @see 注意，content 属性已经被从 PopoverProps 中删除，因为这个属性由 ProHelpPopover 内部控制。
+   */
+  popoverProps?: PopoverProps;
+};
+
+/**
+ * 渲染一个弹出式提示框，其中显示了一个ProHelpContentPanel，展示帮助文案的详情
+ * @param popoverProps 要传递给 Drawer 组件的属性。
+ * @param props 要传递给 ProHelpPanel 组件的属性。
+ */
+export const ProHelpPopover: React.FC<ProHelpPopoverProps> = (props) => {
+  const { getPrefixCls } = useContext(ConfigProvider.ConfigContext);
+  const className = getPrefixCls('pro-help');
+  const { hashId } = useContext(ProProvider);
+
+  const { wrapSSR } = useStyle(className);
+  return wrapSSR(
+    <Popover
+      overlayInnerStyle={{
+        padding: 0,
+      }}
+      content={
+        <div
+          className={classNames(
+            `${className}-popover-content`,
+            hashId,
+            props.popoverContextClassName,
+          )}
+        >
+          <ProHelpContentPanel selectedKey={props.selectedKey} />
+        </div>
+      }
+      {...props.popoverProps}
+    >
+      <span
+        className={classNames(
+          `${className}-popover-text`,
+          hashId,
+          props.textClassName,
+        )}
+      >
+        {props.children}
+      </span>
+    </Popover>,
+  );
+};

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

@@ -0,0 +1,156 @@
+import type { ImageProps } from 'antd';
+import { Image, Typography } from 'antd';
+import type { AnchorHTMLAttributes } from 'react';
+import React, { useContext, useEffect, useRef } from 'react';
+import type { ProHelpDataSourceChildren } from './HelpProvide';
+import { ProHelpProvide } from './HelpProvide';
+import { SelectKeyProvide } from './ProHelpPanel';
+
+// HTML渲染组件，接收一个字符串形式的html作为props
+// 可选接收className作为组件的样式类名
+const HTMLRender: React.FC<{
+  children: string;
+  className?: string;
+}> = (props) => {
+  const ref = useRef<HTMLDivElement>(null);
+
+  // 当html发生变化时，将其渲染到ref.current的innerHTML中
+  useEffect(() => {
+    if (ref.current) ref.current.innerHTML = props.children;
+  }, [props.children]);
+  // 返回一个div元素作为容器，并传递ref和className作为props
+  return <div ref={ref} className={props.className || 'inner-html'} />;
+};
+
+const NavigationSwitch: React.FC<{
+  children: string;
+  selectKey: string;
+}> = (props) => {
+  const context = useContext(SelectKeyProvide);
+  return (
+    <Typography.Text>
+      <a
+        data-testid="navigation-switch"
+        onClick={() => {
+          context.setSelectedKey(props.selectKey);
+        }}
+      >
+        {props.children}
+      </a>
+    </Typography.Text>
+  );
+};
+
+export const RenderContentPanel: React.FC<{
+  dataSourceChildren: ProHelpDataSourceChildren<any>[];
+  onInit?: (ref: HTMLDivElement) => void;
+}> = ({ dataSourceChildren, onInit }) => {
+  const { valueTypeMap } = useContext(ProHelpProvide);
+  const divRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    onInit?.(divRef.current!);
+  }, [dataSourceChildren]);
+
+  /**
+   * itemRender 的定义
+   * @param {ProHelpDataSourceChildren} item
+   * @param {number} index
+   * @return {*}
+   */
+  const itemRender = (item: ProHelpDataSourceChildren, index: number) => {
+    // 自定义的渲染，优先级最高
+    if (valueTypeMap.has(item.valueType)) {
+      return (
+        <React.Fragment key={index}>
+          {valueTypeMap.get(item.valueType)?.(item, index)}
+        </React.Fragment>
+      );
+    }
+    if (item.valueType === 'html') {
+      return (
+        <HTMLRender
+          key={index}
+          {...(item.children as {
+            className: string;
+            children: string;
+          })}
+        />
+      );
+    }
+
+    if (item.valueType === 'h1') {
+      return (
+        <Typography.Title
+          key={index}
+          style={{
+            marginTop: 0,
+          }}
+          level={3}
+        >
+          {item.children as string}
+        </Typography.Title>
+      );
+    }
+
+    if (item.valueType === 'h2') {
+      return (
+        <Typography.Title
+          key={index}
+          style={{
+            marginTop: 20,
+          }}
+          level={5}
+        >
+          {item.children as string}
+        </Typography.Title>
+      );
+    }
+    if (item.valueType === 'image') {
+      return (
+        <div
+          key={index}
+          style={{
+            marginBlock: 12,
+          }}
+        >
+          <Image {...(item.children as ImageProps)} />
+        </div>
+      );
+    }
+    if (item.valueType === 'inlineLink') {
+      return (
+        <Typography.Text key={index}>
+          <a {...(item.children as AnchorHTMLAttributes<HTMLAnchorElement>)} />
+        </Typography.Text>
+      );
+    }
+    if (item.valueType === 'link') {
+      return (
+        <div key={index}>
+          <Typography.Text key={index}>
+            <a
+              {...(item.children as AnchorHTMLAttributes<HTMLAnchorElement>)}
+            />
+          </Typography.Text>
+        </div>
+      );
+    }
+    if (item.valueType === 'navigationSwitch') {
+      return (
+        <NavigationSwitch
+          key={index}
+          {...(item.children as {
+            children: string;
+            selectKey: string;
+          })}
+        />
+      );
+    }
+    return (
+      <Typography.Text key={index}>{item.children as string}</Typography.Text>
+    );
+  };
+
+  return <div ref={divRef}>{dataSourceChildren?.map(itemRender)}</div>;
+};

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

@@ -0,0 +1,172 @@
+import { SearchOutlined } from '@ant-design/icons';
+import { ProProvider, useStyle } from '@ant-design/pro-provider';
+import { compatibleBorder, useDebounceFn } from '@ant-design/pro-utils';
+import type { SelectProps } from 'antd';
+import { ConfigProvider, Select } from 'antd';
+import classNames from 'classnames';
+import React, { useContext, useState } from 'react';
+import { ProHelpProvide } from './HelpProvide';
+
+/**
+ * 在一段文本中高亮显示指定的关键词，将文本和匹配项分别处理并放入数组中，最终返回包含高亮文本的组件。
+ * 在组件中使用了正则表达式来匹配关键词。
+ * 在渲染文本时，使用了React.createElement来创建元素。
+ */
+export const Highlight: React.FC<{
+  /**
+   * 要高亮的文本
+   */
+  label: string;
+  /**
+   * 高亮的关键词数组
+   */
+  words: string[];
+}> = ({ label, words }) => {
+  const { getPrefixCls } = useContext(ConfigProvider.ConfigContext);
+  const lightCls = getPrefixCls('pro-help-search-list-item-content-light');
+  const optionCls = getPrefixCls('pro-help-search-list-item-content');
+
+  // css
+  const { wrapSSR } = useStyle('Highlight', (token) => {
+    return {
+      [`.${lightCls}`]: {
+        color: token.colorPrimary,
+      },
+      [`.${optionCls}`]: {
+        flex: 'auto',
+        overflow: 'hidden',
+        whiteSpace: 'nowrap',
+        textOverflow: 'ellipsis',
+      },
+    };
+  });
+
+  if (words.length === 0) return <>{label}</>;
+
+  // 创建正则表达式匹配关键词
+  const matchKeywordsRE = new RegExp(
+    words
+      .map((word) => word.replace(/[-[\]/{}()*+?.\\^$|]/g, '\\$&'))
+      .join('|'),
+    'gi',
+  );
+
+  let matchText = label;
+
+  const elements: React.ReactNode[] = [];
+
+  // 遍历匹配的文本，将匹配项和非匹配项分别处理并放入elements数组中
+  while (matchText.length) {
+    const match = matchKeywordsRE.exec(matchText);
+    if (!match) {
+      elements.push(matchText);
+      break;
+    }
+
+    const start = match.index;
+    const matchLength = match[0].length + start;
+
+    elements.push(
+      matchText.slice(0, start),
+      React.createElement(
+        'span',
+        {
+          className: lightCls,
+        },
+        matchText.slice(start, matchLength),
+      ),
+    );
+    matchText = matchText.slice(matchLength);
+  }
+  return wrapSSR(
+    React.createElement(
+      'div',
+      {
+        title: label,
+        className: optionCls,
+      },
+      ...elements,
+    ),
+  );
+};
+
+export const ProHelpSelect: React.FC<
+  Omit<
+    SelectProps,
+    'onSearch' | 'optionFilterProp' | 'options' | 'filterOption'
+  > & {
+    iconClassName?: string;
+  }
+> = ({ iconClassName, ...props }) => {
+  const { dataSource } = useContext(ProHelpProvide);
+  const [keyWord, setKeyWork] = useState<string>('');
+  const { hashId } = useContext(ProProvider);
+  const debounceSetKeyWork = useDebounceFn(async (key) => setKeyWork(key), 20);
+
+  const [open, setOpen] = useState<boolean>(false);
+
+  return (
+    <>
+      {!open ? (
+        <div className={classNames(iconClassName, hashId)}>
+          <SearchOutlined
+            title="search panel"
+            onClick={() => {
+              setOpen(true);
+            }}
+          />
+        </div>
+      ) : null}
+      {open ? (
+        <Select<{
+          label: React.ReactNode;
+          title: string;
+          value: string;
+          dataItemKey: string;
+        }>
+          placeholder="please input search text"
+          showSearch
+          {...compatibleBorder(false)}
+          onBlur={() => {
+            setOpen(false);
+          }}
+          size="small"
+          {...props}
+          onSearch={(value) => {
+            debounceSetKeyWork.cancel();
+            debounceSetKeyWork.run(value);
+          }}
+          filterOption={(input, option) =>
+            (option?.title ?? '').toLowerCase().includes(input.toLowerCase())
+          }
+          popupMatchSelectWidth={false}
+          options={dataSource.map((item) => {
+            return {
+              label: (
+                <Highlight
+                  label={item.title}
+                  words={[keyWord].filter(Boolean)}
+                />
+              ),
+              title: item.title,
+              value: item.key,
+              options: item.children?.map((sunItem) => {
+                return {
+                  label: (
+                    <Highlight
+                      label={sunItem.title}
+                      words={[keyWord].filter(Boolean)}
+                    />
+                  ),
+                  title: sunItem.title,
+                  value: sunItem.key,
+                  dataItemKey: item.key,
+                };
+              }),
+            };
+          })}
+        />
+      ) : null}
+    </>
+  );
+};