@lark-apaas/coding-template-nestjs-react-fullstack 0.1.0-alpha.1

package/template/client/src/components/business-ui/tiptap-editor/tiptap-editor.tsx

@@ -0,0 +1,169 @@
+'use client';
+
+import * as React from 'react';
+import {
+  EditorContent,
+  EditorContext,
+  useCurrentEditor,
+  useEditor,
+  type EditorContentProps,
+  type Extensions,
+} from '@tiptap/react';
+import { Slot } from 'radix-ui';
+
+import { LinkHoverToolbar } from '@/components/business-ui/tiptap-editor/components/link-hover-toolbar';
+import { CompleteKit } from '@/components/business-ui/tiptap-editor/extensions/complete-kit';
+import { cn } from '@/lib/utils';
+import { Separator } from '@/components/ui/separator';
+
+export interface TiptapEditorProps extends React.ComponentProps<'div'> {
+  /** 受控 value (HTML)。 */
+  value?: string;
+  /** 默认值 (HTML)。 */
+  defaultValue?: string;
+  /** 当编辑器更新时，触发并传递最新的 HTML。 */
+  onValueChange?: (value: string) => void;
+  children?: React.ReactNode;
+  className?: string;
+  /**
+   * 自定义 Tiptap 扩展。
+   * @default [CompleteKit]
+   */
+  extensions?: Extensions;
+  /** 是否为只读模式。 */
+  readOnly?: boolean;
+  asChild?: boolean;
+}
+
+const defaultExtensions = [CompleteKit];
+
+export function TiptapEditor({
+  value,
+  defaultValue,
+  onValueChange,
+  children,
+  className,
+  extensions = defaultExtensions,
+  readOnly = false,
+  asChild = false,
+  autoFocus = false,
+  'aria-disabled': ariaDisabled,
+  ...props
+}: TiptapEditorProps) {
+  const Comp = asChild ? Slot.Root : 'div';
+
+  const initialContent = value !== undefined ? value : defaultValue;
+  const editable = !readOnly && !ariaDisabled;
+
+  const editor = useEditor({
+    autofocus: autoFocus,
+    editable,
+    editorProps: {
+      attributes: {
+        class: cn('prose max-w-none flex-1 px-3 py-2 dark:prose-invert'),
+      },
+    },
+    immediatelyRender: false,
+    content: initialContent,
+    onUpdate: ({ editor }) => {
+      onValueChange?.(editor.getHTML());
+    },
+    extensions,
+  });
+
+  const valueRef = React.useRef(value);
+  React.useEffect(() => {
+    if (!editor || value === undefined) return;
+    valueRef.current = value;
+
+    // Tiptap 内部会使用 flushSync，因此我们将内容更新延迟到微任务队列
+    queueMicrotask(() => {
+      const current = editor.getHTML();
+      if (valueRef.current !== current) {
+        editor.commands.setContent(value);
+      }
+    });
+  }, [value, editor]);
+
+  React.useEffect(() => {
+    if (!editor) return;
+    editor.setEditable(editable);
+  }, [editor, editable]);
+
+  const contextValue = React.useMemo(() => ({ editor }), [editor]);
+
+  return (
+    <EditorContext value={contextValue}>
+      <Comp
+        aria-disabled={ariaDisabled}
+        className={cn(
+          "relative flex w-full flex-col rounded-md border ring-offset-background focus-within:border-ring focus-within:ring-[3px] focus-within:ring-ring/20 focus-within:outline-hidden hover:border-ring aria-disabled:cursor-not-allowed aria-disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 **:data-[type='taskList']:list-none **:data-[type='taskList']:p-0 [&_[data-type='taskList']>li]:flex [&_[data-type='taskList']>li]:items-start [&_[data-type='taskList']>li]:gap-2 [&_[data-type='taskList']>li>div]:min-w-0 [&_[data-type='taskList']>li>div]:flex-1 [&_[data-type='taskList']>li>div>p]:m-0 [&_[data-type='taskList']>li>label]:mt-0.5 [&_[data-type='taskList']>li>label]:shrink-0 **:[a]:cursor-pointer",
+          className,
+        )}
+        data-slot="tiptap-editor"
+        {...props}
+      >
+        {children}
+        <LinkHoverToolbar />
+      </Comp>
+    </EditorContext>
+  );
+}
+
+export function TiptapEditorContent({
+  className,
+  ...props
+}: Omit<EditorContentProps, 'editor'>) {
+  const { editor } = useCurrentEditor();
+
+  return (
+    <EditorContent
+      editor={editor}
+      className={cn(
+        'flex flex-1 flex-col overflow-y-auto outline-hidden',
+        className,
+      )}
+      data-slot="tiptap-editor-content"
+      {...props}
+    />
+  );
+}
+
+export function TiptapEditorToolbar({
+  className,
+  children,
+  asChild,
+  ...props
+}: React.ComponentProps<'div'> & { asChild?: boolean }) {
+  const Comp = asChild ? Slot.Root : 'div';
+
+  return (
+    <Comp
+      className={cn(
+        'flex flex-wrap items-center gap-x-1 gap-y-2 p-1.5',
+        className,
+      )}
+      data-slot="tiptap-editor-toolbar"
+      {...props}
+    >
+      {children}
+    </Comp>
+  );
+}
+
+export function TiptapEditorToolbarSeparator({
+  className,
+  ...props
+}: React.ComponentProps<typeof Separator>) {
+  return (
+    <Separator
+      orientation="vertical"
+      className={cn(
+        'mx-0.5 h-4 w-px bg-border data-[orientation=vertical]:h-4',
+        className,
+      )}
+      data-slot="tiptap-editor-toolbar-separator"
+      {...props}
+    />
+  );
+}

package/template/client/src/components/business-ui/types/user.ts

@@ -0,0 +1,74 @@
+// client/src/types/user.ts
+
+import type { I18nText } from '@/components/business-ui/entity-combobox/types';
+import type { Department } from '@/components/business-ui/department-select/types';
+
+/**
+ * 重新导出相关类型，方便统一导入
+ */
+export type { I18nText, Department };
+
+/**
+ * 用户类型枚举
+ */
+export type UserType = '_employee' | '_externalUser' | '_anonymousUser';
+
+/**
+ * 统一的标准用户类型（单一事实来源）
+ * 使用下划线命名（与后端统一），larkUserId 除外
+ */
+export interface User {
+  /** 用户 ID（未注册外部联系人可能没有） */
+  user_id?: string;
+
+  /** 飞书用户 ID（保持驼峰） */
+  larkUserId?: string;
+
+  /**
+   * 用户名称
+   * 支持简单字符串或国际化文本
+   */
+  name?: I18nText | string;
+
+  /** 用户头像 URL */
+  avatar?: string;
+
+  /** 用户邮箱 */
+  email?: string;
+
+  /**
+   * 用户类型
+   * - '_employee': 内部员工
+   * - '_externalUser': 外部用户
+   * - '_anonymousUser': 匿名用户
+   */
+  user_type?: UserType;
+
+  /** 部门信息（引用 DepartmentSelect 的类型） */
+  department?: Department;
+
+  /** 租户名称（外部用户显示） */
+  tenantName?: string;
+
+  /** 用户状态 */
+  status?: number;
+}
+
+/**
+ * 用户数据输入类型（用于组件 Props）
+ * 兼容驼峰和下划线命名，内部自动转换为标准 User 类型
+ */
+export type UserInput =
+  | User
+  | {
+      user_id?: string;
+      userId?: string;         // 兼容驼峰
+      larkUserId?: string;
+      name?: I18nText | string;
+      avatar?: string;
+      email?: string;
+      user_type?: UserType;
+      userType?: UserType;     // 兼容驼峰
+      department?: Department | any;
+      status?: number;
+    };

package/template/client/src/components/business-ui/user-display/index.tsx

@@ -0,0 +1,2 @@
+export { UserDisplay } from '@client/src/components/business-ui/user-display/user-display';
+export type { UserWithAvatarProps } from '@client/src/components/business-ui/user-display/type';

package/template/client/src/components/business-ui/user-display/overflow-tooltip-text.tsx

@@ -0,0 +1,90 @@
+import * as React from 'react';
+
+import { cn } from '@/lib/utils';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@client/src/components/ui/tooltip';
+
+export interface OverflowTooltipTextProps extends React.HTMLAttributes<HTMLSpanElement> {
+  text: string;
+}
+
+/**
+ * Displays truncated inline text and shows a tooltip with the full content when overflowed.
+ */
+export function OverflowTooltipText({
+  text,
+  className,
+  ...props
+}: OverflowTooltipTextProps) {
+  const textRef = React.useRef<HTMLSpanElement>(null);
+  const [isOverflowing, setIsOverflowing] = React.useState(false);
+
+  const checkOverflow = React.useCallback(() => {
+    const el = textRef.current;
+    if (!el) {
+      return;
+    }
+
+    setIsOverflowing(el.scrollWidth > el.clientWidth + 1);
+  }, []);
+
+  React.useLayoutEffect(() => {
+    checkOverflow();
+  }, [checkOverflow]);
+
+  React.useEffect(() => {
+    const el = textRef.current;
+    if (!el) {
+      return;
+    }
+    const observer = new ResizeObserver(() => {
+      checkOverflow();
+    });
+    observer.observe(el);
+    return () => {
+      observer.disconnect();
+    };
+  }, [checkOverflow]);
+
+  React.useEffect(() => {
+    const handleResize = () => {
+      checkOverflow();
+    };
+    window.addEventListener('resize', handleResize);
+    return () => {
+      window.removeEventListener('resize', handleResize);
+    };
+  }, [checkOverflow]);
+
+  const textNode = (
+    <span
+      ref={textRef}
+      className={cn('inline-block truncate', className)}
+      {...props}
+    >
+      {text}
+    </span>
+  );
+
+  if (!isOverflowing) {
+    return textNode;
+  }
+
+  return (
+    <TooltipProvider>
+      <Tooltip delayDuration={80}>
+        <TooltipTrigger asChild>{textNode}</TooltipTrigger>
+        <TooltipContent
+          sideOffset={4}
+          className="bg-[rgb(31,35,41)] text-white ring-0"
+        >
+          {text}
+        </TooltipContent>
+      </Tooltip>
+    </TooltipProvider>
+  );
+}

package/template/client/src/components/business-ui/user-display/type.ts

@@ -0,0 +1,27 @@
+import type { AccountType } from '@lark-apaas/client-toolkit/tools/services';
+import type { UserInput } from '@client/src/components/business-ui/types/user';
+
+export interface UserWithAvatarProps {
+  /**
+   * 用户数据，可以只传 userId，组件会自动查询 name 和 avatar
+   */
+  data: UserInput;
+  /**
+   * @default medium
+   */
+  size?: 'small' | 'medium' | 'large';
+  /**
+   * @default tag
+   */
+  mode?: 'tag' | 'plain';
+  className?: string;
+  /**
+   * @default true
+   */
+  showLabel?: boolean;
+  /**
+   * 账户类型，用于查询用户信息
+   * @default 'apaas'
+   */
+  accountType?: AccountType;
+}

package/template/client/src/components/business-ui/user-display/user-display.tsx

@@ -0,0 +1,99 @@
+'use client';
+
+import React from 'react';
+
+import { normalizeUser, isValidUserId } from '@client/src/components/business-ui/utils/user';
+import type { UserInput } from '@client/src/components/business-ui/types/user';
+import { UserWithAvatar } from '@client/src/components/business-ui/user-display/user-with-avatar';
+import { UserProfile } from '@client/src/components/business-ui/user-profile/user-profile';
+import { cn } from '@/lib/utils';
+import {
+  Popover,
+  PopoverContent,
+  PopoverTrigger,
+} from '@client/src/components/ui/popover';
+
+export interface IUserDisplayProps {
+  /**
+   * 用户列表
+   */
+  value?: string | string[] | UserInput | UserInput[];
+  size?: 'small' | 'medium' | 'large';
+  className?: string;
+  style?: React.CSSProperties;
+  showLabel?: boolean;
+  showUserProfile?: boolean;
+  userId?: string;
+  user_id?: string;
+}
+
+export const UserDisplay: React.FC<IUserDisplayProps> = ({
+  userId,
+  user_id,
+  value,
+  size,
+  className,
+  style,
+  showLabel = true,
+}) => {
+  // 统一规范化为 User[]，兼容所有格式
+  const normalizedUsers = React.useMemo(() => {
+    let list: UserInput[];
+
+    if (value) {
+      // 处理 value 的不同类型
+      if (Array.isArray(value)) {
+        // string[] 或 UserInput[]
+        list = value.map((item: string | UserInput) =>
+          typeof item === 'string' ? { user_id: item } : item,
+        );
+      } else {
+        // string 或 UserInput
+        list = [typeof value === 'string' ? { user_id: value } : value];
+      }
+    } else if (userId) {
+      // userId 快捷方式：转换为对象
+      list = [{ user_id: userId }];
+    } else if (user_id) {
+      // user_id 快捷方式：转换为对象
+      list = [{ user_id }];
+    } else {
+      return [];
+    }
+
+    // 转换为标准 User 类型并过滤无效 ID
+    return list
+      .map(normalizeUser)
+      .filter((user) => isValidUserId(user.user_id));
+  }, [value, userId, user_id]);
+
+  if (!normalizedUsers.length) {
+    return null;
+  }
+
+  return (
+    <div className={cn('flex flex-wrap gap-1', className)} style={style}>
+      {normalizedUsers.map((user) => (
+        <Popover key={user.user_id}>
+          <PopoverTrigger asChild>
+            <div>
+              <UserWithAvatar
+                data={user}
+                size={size}
+                showLabel={showLabel}
+                className="cursor-pointer hover:bg-[rgba(31,35,41,0.15)] active:bg-[rgba(31,35,41,0.2)]"
+              />
+            </div>
+          </PopoverTrigger>
+          <PopoverContent
+            align="start"
+            sideOffset={8}
+            className="w-[320px] border-0 border-border/50 bg-card p-0 shadow-[0px_8px_24px_8px_rgba(31,35,41,0.04),0px_6px_12px_rgba(31,35,41,0.04),0px_4px_8px_-8px_rgba(31,35,41,0.06)]"
+          >
+            <UserProfile value={user} />
+          </PopoverContent>
+        </Popover>
+      ))}
+    </div>
+  );
+};

package/template/client/src/components/business-ui/user-display/user-with-avatar.tsx

@@ -0,0 +1,158 @@
+'use client';
+import React from 'react';
+
+import { useMemo } from 'react';
+
+import { OverflowTooltipText } from '@client/src/components/business-ui/user-display/overflow-tooltip-text';
+import { type UserWithAvatarProps } from '@client/src/components/business-ui/user-display/type';
+import {
+  userInfoToUser,
+  createUnknownUser,
+} from '@client/src/components/business-ui/user-display/utils';
+import { normalizeUser, getI18nText } from '@client/src/components/business-ui/utils/user';
+import type { User } from '@client/src/components/business-ui/types/user';
+import { useUsersByIds } from '@client/src/components/business-ui/api/users/queries';
+import { cn } from '@/lib/utils';
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+} from '@client/src/components/ui/avatar';
+import { cva } from 'class-variance-authority';
+
+const userWithAvatarVariants = cva(
+  'flex min-w-0 items-center gap-1 rounded-full',
+  {
+    variants: {
+      size: {
+        small: 'max-w-37',
+        medium: 'max-w-43',
+        large: 'max-w-49',
+      },
+      showLabel: {
+        true: '',
+        false: '',
+      },
+      mode: {
+        tag: 'bg-muted',
+        plain: '',
+      },
+    },
+    compoundVariants: [
+      { size: 'small', showLabel: true, class: 'py-0.5 pr-1.5 pl-0.5' },
+      { size: 'medium', showLabel: true, class: 'py-0.5 pr-2 pl-0.5' },
+      { size: 'large', showLabel: true, class: 'py-1 pr-2.5 pl-1' },
+      { size: 'small', showLabel: false, class: '' },
+      { size: 'medium', showLabel: false, class: '' },
+      { size: 'large', showLabel: false, class: '' },
+    ],
+    defaultVariants: {
+      size: 'medium',
+      mode: 'tag',
+      showLabel: true,
+    },
+  },
+);
+
+const avatarVariants = cva('', {
+  variants: {
+    size: {
+      small: 'h-4 w-4',
+      medium: 'h-5 w-5',
+      large: 'h-6 w-6',
+    },
+  },
+  defaultVariants: {
+    size: 'medium',
+  },
+});
+
+const avatarFallbackVariants = cva('leading-none text-foreground', {
+  variants: {
+    size: {
+      small: 'text-[10px]',
+      medium: 'text-[12px]',
+      large: 'text-[14px]',
+    },
+  },
+  defaultVariants: {
+    size: 'medium',
+  },
+});
+
+const textVariants = cva('text-card-foreground', {
+  variants: {
+    size: {
+      small: 'text-[12px] leading-4',
+      medium: 'text-[14px] leading-5',
+      large: 'text-[16px] leading-6',
+    },
+  },
+  defaultVariants: {
+    size: 'medium',
+  },
+});
+
+export function UserWithAvatar({
+  data,
+  size = 'medium',
+  mode = 'tag',
+  className,
+  showLabel = true,
+  accountType = 'apaas',
+}: UserWithAvatarProps) {
+  // 统一转换为标准 User 类型
+  const user: User = normalizeUser(data);
+  const { user_id, avatar: propsAvatar, name: propsName } = user;
+
+  // 判断是否需要从 API 获取用户信息
+  const needsFetch = !propsName && !propsAvatar && !!user_id;
+
+  // 使用 react-query hook 获取用户信息
+  const idsToFetch = useMemo(
+    () => (needsFetch ? [user_id] : []),
+    [needsFetch, user_id],
+  );
+  const { data: response, isLoading } = useUsersByIds(idsToFetch, accountType);
+
+  // 从原始 API 响应中提取并转换用户信息
+  const fetchedUser = useMemo(() => {
+    if (!needsFetch) return null;
+    const userInfoMap = response?.data?.userInfoMap || {};
+    const userInfo = userInfoMap[user_id];
+    return userInfo
+      ? userInfoToUser(userInfo, accountType)
+      : createUnknownUser(user_id);
+  }, [response, needsFetch, user_id, accountType]);
+
+  const avatar = propsAvatar || fetchedUser?.avatar;
+  const name = propsName || fetchedUser?.name;
+
+  // 直接使用已合并的 name，通过 getI18nText 处理国际化
+  const displayName = isLoading ? '' : (getI18nText(name) || '无效人员');
+  const formatSize = ['small', 'medium', 'large'].includes(size)
+    ? size
+    : 'medium';
+
+  return (
+    <div
+      className={cn(
+        userWithAvatarVariants({ size: formatSize, showLabel, mode }),
+        className,
+      )}
+    >
+      <Avatar className={cn(avatarVariants({ size: formatSize }))}>
+        <AvatarImage className="m-0" src={avatar} alt={displayName} />
+        <AvatarFallback
+          className={cn(avatarFallbackVariants({ size: formatSize }))}
+        />
+      </Avatar>
+      {showLabel && (
+        <OverflowTooltipText
+          text={displayName}
+          className={cn(textVariants({ size: formatSize }))}
+        />
+      )}
+    </div>
+  );
+}

package/template/client/src/components/business-ui/user-display/utils.ts

@@ -0,0 +1,37 @@
+import { normalizeUser, isValidUserId } from '@client/src/components/business-ui/utils/user';
+import type { User } from '@client/src/components/business-ui/types/user';
+import type { UserInfo } from '@lark-apaas/client-toolkit/tools/services';
+import type { AccountType } from '@client/src/components/business-ui/api/users/service';
+
+// 直接导出统一的函数
+export { normalizeUser, isValidUserId };
+
+// user-display 专用的转换函数
+export function userInfoToUser(
+  userInfo: (UserInfo & { avatar?: any }) | any,
+  accountType: AccountType,
+): User {
+  let avatarUrl: string | undefined;
+
+  if (typeof userInfo.avatar === 'string') {
+    avatarUrl = userInfo.avatar;
+  } else if (userInfo.avatar?.image?.large) {
+    avatarUrl = userInfo.avatar.image.large;
+  }
+
+  return {
+    user_id: accountType === 'lark' ? userInfo.larkUserID : userInfo.userID,
+    larkUserId: userInfo.larkUserID,
+    name: userInfo.name,
+    avatar: avatarUrl,
+    user_type: userInfo.userType,
+    department: userInfo.department as any,
+  };
+}
+
+export function createUnknownUser(user_id: string): User {
+  return {
+    user_id,
+    name: '未知用户',
+  };
+}