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

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

@@ -0,0 +1,102 @@
+import type {
+  BaseEntitySelectProps,
+  ItemValue,
+} from '@client/src/components/business-ui/entity-combobox/shared-types';
+import type { I18nText } from '@client/src/components/business-ui/entity-combobox/types';
+
+export type { I18nText };
+
+/**
+ * 群组原始信息（对应 SearchChatEntity）
+ */
+export type ChatInfo = {
+  /** 群组 ID */
+  chatID: string;
+  /** 群组名称（国际化文本） */
+  name: I18nText;
+  /** 头像：URL 或 16 进制 RGB 颜色 */
+  avatar: string;
+  /** 是否是外部群 */
+  isExternal?: boolean;
+  /** 群成员数量（不包括机器人） */
+  userCount?: number;
+};
+
+/**
+ * 标准化后的群组数据（用于 BaseCombobox）
+ */
+export type Chat = ItemValue<ChatInfo>;
+
+/**
+ * 值类型
+ * - 'string': value 为 chatID 字符串
+ * - 'object': value 为 Chat 对象
+ * @default 'string'
+ */
+export type ValueType = 'string' | 'object';
+
+/**
+ * 根据 valueType 和 multiple 推断 value 类型
+ */
+export type InferValue<
+  V extends ValueType,
+  M extends boolean,
+> = V extends 'string'
+  ? M extends true
+    ? string[]
+    : string | null
+  : M extends true
+    ? Chat[]
+    : Chat | null;
+
+type ChatSelectBaseProps<
+  V extends ValueType = 'string',
+  M extends boolean = false,
+> = Omit<
+  BaseEntitySelectProps<Chat>,
+  'value' | 'defaultValue' | 'onChange'
+> & {
+  /**
+   * 值类型
+   * - 'string': value 为 chatID 字符串
+   * - 'object': value 为 Chat 对象
+   * @default 'string'
+   */
+  valueType?: V;
+  /**
+   * 是否多选
+   * @default false
+   */
+  multiple?: M;
+  /**
+   * 当前值
+   */
+  value?: InferValue<V, M>;
+  /**
+   * 默认值
+   */
+  defaultValue?: InferValue<V, M>;
+  /**
+   * 值变化回调
+   */
+  onChange?: (value: InferValue<V, M>) => void;
+};
+
+/**
+ * ChatSelect 组件 Props
+ *
+ * 类型组合：
+ * | valueType | multiple | value 类型 |
+ * |-----------|----------|------------|
+ * | 'string'  | false    | string \| null |
+ * | 'string'  | true     | string[] |
+ * | 'object'  | false    | Chat \| null |
+ * | 'object'  | true     | Chat[] |
+ */
+export type ChatSelectProps =
+  | ChatSelectBaseProps<'string', false>
+  | ChatSelectBaseProps<'string', true>
+  | ChatSelectBaseProps<'object', false>
+  | ChatSelectBaseProps<'object', true>;
+
+export type ChatSelectValue = Chat | Chat[] | string | string[] | null;

package/template/client/src/components/business-ui/chat-select/use-chat-value.ts

@@ -0,0 +1,180 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useState } from 'react';
+
+import { listChatsByIds } from '@client/src/components/business-ui/api/chats/service';
+import type {
+  Chat,
+  ChatSelectValue,
+  ValueType,
+} from '@client/src/components/business-ui/chat-select/types';
+import {
+  chatInfoToChat,
+  createUnknownChat,
+  extractIdsFromValue,
+} from '@client/src/components/business-ui/chat-select/utils';
+
+export type UseChatValueResult = {
+  /**
+   * 标准化后的内部 value（Chat 对象格式）
+   * 用于传递给 BaseCombobox
+   */
+  internalValue: Chat | Chat[] | null;
+
+  /**
+   * 是否正在加载群组信息
+   */
+  isLoading: boolean;
+
+  /**
+   * 将内部 Chat 对象转换回外部格式
+   * ID 模式时返回字符串，对象模式时返回 Chat
+   */
+  toExternalValue: (
+    internalVal: Chat | Chat[] | null,
+    multiple: boolean,
+  ) => ChatSelectValue;
+};
+
+/**
+ * 处理 ChatSelect 的 value 类型转换
+ *
+ * - 根据 valueType 决定 value 是 chatID 字符串还是 Chat 对象
+ * - ID 模式下调用搜索 API 获取完整群组信息
+ * - 无效 ID 生成 "未知群组" 占位
+ *
+ * @param value - 外部传入的 value
+ * @param multiple - 是否多选模式
+ * @param valueType - 值类型，'string' 表示 ID 模式，'object' 表示 Chat 对象模式
+ */
+export function useChatValue(
+  value: ChatSelectValue,
+  multiple: boolean = false,
+  valueType: ValueType = 'string',
+): UseChatValueResult {
+  const isIdMode = valueType === 'string';
+
+  const [resolvedChats, setResolvedChats] = useState<Map<string, Chat>>(
+    new Map(),
+  );
+  const [isLoading, setIsLoading] = useState(false);
+
+  const currentIds = useMemo(() => extractIdsFromValue(value), [value]);
+
+  const missingIds = useMemo(() => {
+    if (!isIdMode) return [];
+    return currentIds.filter((id) => !resolvedChats.has(String(id)));
+  }, [isIdMode, currentIds, resolvedChats]);
+
+  // 稳定化 missingIds 引用
+  const missingIdsKey = missingIds.join(',');
+
+  useEffect(() => {
+    if (!missingIdsKey) {
+      return;
+    }
+
+    const ids = missingIdsKey.split(',');
+    let cancelled = false;
+
+    const fetchData = async () => {
+      setIsLoading(true);
+      try {
+        const response = await listChatsByIds(ids);
+        if (cancelled) return;
+
+        const chatInfoMap = response?.data?.chatInfoMap || {};
+        setResolvedChats((prev) => {
+          const next = new Map(prev);
+          for (const [chatId, chatInfo] of Object.entries(chatInfoMap)) {
+            const chat = chatInfoToChat(chatInfo);
+            next.set(String(chatId), chat);
+          }
+          // 标记未找到的 ID 为未知群组
+          for (const id of ids) {
+            if (!next.has(String(id))) {
+              next.set(String(id), createUnknownChat(id));
+            }
+          }
+          return next;
+        });
+      } catch (error) {
+        console.error('Failed to resolve chat IDs:', error);
+        if (!cancelled) {
+          setResolvedChats((prev) => {
+            const next = new Map(prev);
+            for (const id of ids) {
+              if (!next.has(String(id))) {
+                next.set(String(id), createUnknownChat(id));
+              }
+            }
+            return next;
+          });
+        }
+      } finally {
+        if (!cancelled) {
+          setIsLoading(false);
+        }
+      }
+    };
+
+    fetchData();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [missingIdsKey]);
+
+  const internalValue = useMemo((): Chat | Chat[] | null => {
+    if (value === null || value === undefined) {
+      return multiple ? [] : null;
+    }
+
+    if (Array.isArray(value) && value.length === 0) {
+      return [];
+    }
+
+    if (!isIdMode) {
+      return value as Chat | Chat[];
+    }
+
+    const chats = currentIds
+      .map((id) => resolvedChats.get(String(id)))
+      .filter((c): c is Chat => c !== undefined);
+
+    if (multiple) {
+      return chats;
+    }
+
+    return chats[0] ?? null;
+  }, [value, isIdMode, currentIds, resolvedChats, multiple]);
+
+  const toExternalValue = useCallback(
+    (
+      internalVal: Chat | Chat[] | null,
+      isMultiple: boolean,
+    ): ChatSelectValue => {
+      if (internalVal === null) {
+        return null;
+      }
+
+      if (isIdMode) {
+        // ID 模式：返回 string 或 string[]
+        if (isMultiple) {
+          return (internalVal as Chat[]).map((c) => String(c.id));
+        }
+        return String((internalVal as Chat).id);
+      }
+
+      // Object 模式：直接返回 Chat 对象
+      return internalVal;
+    },
+    [isIdMode],
+  );
+
+  return {
+    internalValue,
+    isLoading,
+    toExternalValue,
+  };
+}

package/template/client/src/components/business-ui/chat-select/utils.ts

@@ -0,0 +1,81 @@
+import type { Chat, ChatInfo, ChatSelectValue, I18nText } from './types';
+
+/**
+ * 获取国际化文本显示值（独立实现，不依赖其他组件）
+ */
+function getI18nText(text: I18nText | string | undefined): string {
+  if (!text) return '';
+  if (typeof text === 'string') return text;
+  return text.zh_cn || text.en_us || text.ja_jp || '';
+}
+
+/**
+ * 获取群组显示名称
+ */
+export function getChatDisplayName(name: ChatInfo['name']): string {
+  return getI18nText(name);
+}
+
+/**
+ * ChatInfo → Chat 标准化转换
+ */
+export function chatInfoToChat(chatInfo: ChatInfo): Chat {
+  return {
+    id: chatInfo.chatID,
+    name: getChatDisplayName(chatInfo.name),
+    avatar: chatInfo.avatar,
+    raw: chatInfo,
+  };
+}
+
+/**
+ * 创建未知群组占位（ID 无法解析时使用）
+ */
+export function createUnknownChat(id: string): Chat {
+  return {
+    id,
+    name: '未知群组',
+    avatar: '',
+    raw: undefined,
+  };
+}
+
+/**
+ * 判断 value 是否为 ID 模式（字符串或字符串数组）
+ */
+export function isIdModeValue(
+  value: ChatSelectValue,
+): value is string | string[] {
+  if (value === null || value === undefined) {
+    return false;
+  }
+  if (typeof value === 'string') {
+    return true;
+  }
+  if (Array.isArray(value) && value.length > 0) {
+    return typeof value[0] === 'string';
+  }
+  return false;
+}
+
+/**
+ * 从 value 中提取 ID 列表
+ */
+export function extractIdsFromValue(value: ChatSelectValue): string[] {
+  if (value === null || value === undefined) {
+    return [];
+  }
+  if (typeof value === 'string') {
+    return [value];
+  }
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return [];
+    }
+    if (typeof value[0] === 'string') {
+      return value as string[];
+    }
+    return (value as Chat[]).map((c) => c.id);
+  }
+  return [(value as Chat).id];
+}

package/template/client/src/components/business-ui/department-select/department-item.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { IconDepartment } from '@client/src/components/business-ui/department-select/icon-department';
+import type { Department } from '@client/src/components/business-ui/department-select/types';
+import { BaseComboboxItem } from '@client/src/components/business-ui/entity-combobox/base-combobox-item';
+import { HighlightText } from '@client/src/components/business-ui/entity-combobox/highlight-text';
+import {
+  listItemAvatarVariants,
+  listItemNameVariants,
+  listItemVariants,
+  type ComboboxSize,
+} from '@client/src/components/business-ui/entity-combobox/size-variants';
+import { cn } from '@/lib/utils';
+
+export const DepartmentItem = ({
+  departmentValue,
+  isSelected,
+  className,
+  size = 'medium',
+  searchKeyword,
+  disabled,
+}: {
+  departmentValue: Department;
+  isSelected: boolean;
+  className?: string;
+  size?: ComboboxSize;
+  searchKeyword?: string;
+  disabled?: boolean;
+}) => {
+  return (
+    <BaseComboboxItem
+      item={departmentValue}
+      getItemValue={(item) => item}
+      isSelected={isSelected}
+      className={cn(listItemVariants({ size }), className)}
+      disabled={disabled}
+    >
+      <div
+        className={cn(
+          'flex items-center justify-center',
+          listItemAvatarVariants({ size }),
+        )}
+      >
+        <IconDepartment className={listItemAvatarVariants({ size })} />
+      </div>
+      <div className="flex min-w-0 flex-1 flex-col">
+        <HighlightText
+          text={departmentValue.name}
+          highlight={searchKeyword}
+          className={listItemNameVariants({ size })}
+        />
+      </div>
+    </BaseComboboxItem>
+  );
+};

package/template/client/src/components/business-ui/department-select/department-select-field.tsx

@@ -0,0 +1,86 @@
+import {
+  DepartmentSelect,
+  type DepartmentSelectProps,
+} from '@client/src/components/business-ui/department-select';
+import type { Department } from '@client/src/components/business-ui/department-select/types';
+import { useFormGlobalProps } from '@client/src/components/business-ui/form/context';
+import { FieldLayout } from '@client/src/components/business-ui/form/field-layout';
+import { useFieldContext } from '@client/src/components/business-ui/form/hooks/form-context';
+import {
+  useFieldName,
+  useFieldValidation,
+} from '@client/src/components/business-ui/form/hooks/form-utils';
+import type {
+  CommonFieldProps,
+  FieldLayoutClassNames,
+  FieldLayoutStyles,
+} from '@client/src/components/business-ui/form/types';
+
+type DepartmentSelectFieldProps = CommonFieldProps &
+  Omit<
+    DepartmentSelectProps,
+    'value' | 'onChange' | 'defaultValue' | 'name' | 'required'
+  > & {
+    classNames?: Partial<
+      FieldLayoutClassNames & {
+        DepartmentSelect: string;
+      }
+    >;
+    styles?: Partial<
+      FieldLayoutStyles & {
+        DepartmentSelect: React.CSSProperties;
+      }
+    >;
+  };
+
+export function DepartmentSelectField(props: DepartmentSelectFieldProps) {
+  const {
+    label,
+    description,
+    required,
+    disabled,
+    classNames,
+    layout = 'vertical',
+    styles,
+    multiple,
+    ...departmentSelectProps
+  } = props;
+
+  const field = useFieldContext<Department | Department[] | null>();
+  const { isInvalid, errorMessage } = useFieldValidation();
+  const { layout: formLayout } = useFormGlobalProps();
+  const name = useFieldName();
+
+  const {
+    DepartmentSelect: departmentSelectClassName,
+    ...fieldLayoutClassNames
+  } = classNames ?? {};
+  const fieldLayoutStyles = styles ?? {};
+
+  return (
+    <FieldLayout
+      label={label}
+      description={description}
+      isInvalid={isInvalid}
+      required={required ?? false}
+      layout={layout ?? formLayout ?? 'vertical'}
+      classNames={fieldLayoutClassNames ?? {}}
+      styles={fieldLayoutStyles ?? {}}
+      errorMessage={errorMessage}
+      name={name}
+    >
+      <DepartmentSelect
+        {...departmentSelectProps}
+        multiple={multiple}
+        value={field.state.value ?? (multiple ? [] : null)}
+        onChange={(value: Department | Department[] | null) => {
+          field.handleChange(value);
+        }}
+        disabled={disabled ?? false}
+        name={name}
+        required={required}
+        className={departmentSelectClassName}
+      />
+    </FieldLayout>
+  );
+}

package/template/client/src/components/business-ui/department-select/department-select-tag.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import { X } from 'lucide-react';
+
+import { IconDepartment } from '@client/src/components/business-ui/department-select/icon-department';
+import type { Department } from '@client/src/components/business-ui/department-select/types';
+import { ItemPill } from '@client/src/components/business-ui/entity-combobox/item-pill';
+import {
+  tagCloseIconVariants,
+  tagIconVariants,
+  type ComboboxSize,
+} from '@client/src/components/business-ui/entity-combobox/size-variants';
+
+export const DepartmentSelectTag = ({
+  departmentValue,
+  onClose,
+  maxTextLength,
+  className,
+  size = 'medium',
+  disabled,
+}: {
+  departmentValue: Department;
+  onClose: (value: Department, e: React.MouseEvent) => void;
+  maxTextLength?: number;
+  className?: string;
+  size?: ComboboxSize;
+  disabled?: boolean;
+}) => {
+  const handleClose = (e: React.MouseEvent) => {
+    e.stopPropagation();
+    onClose(departmentValue, e);
+  };
+
+  const closeButton = !disabled ? (
+    <button
+      type="button"
+      className="rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100 focus:outline-none"
+      onClick={handleClose}
+    >
+      <X className={tagCloseIconVariants({ size })} />
+      <span className="sr-only">移除 {departmentValue.name}</span>
+    </button>
+  ) : null;
+
+  return (
+    <ItemPill
+      label={departmentValue.name}
+      avatar={<IconDepartment className={tagIconVariants({ size })} />}
+      avatarFallback={false}
+      className={className}
+      maxTextLength={maxTextLength}
+      suffix={closeButton}
+      size={size}
+    />
+  );
+};