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

package/template/client/src/components/business-ui/entity-combobox/item-pill.tsx

@@ -0,0 +1,179 @@
+'use client';
+
+import React from 'react';
+
+import {
+  itemPillTextVariants,
+  itemPillVariants,
+  tagAvatarVariants,
+  type ComboboxSize,
+} from '@client/src/components/business-ui/entity-combobox/size-variants';
+import { cn } from '@/lib/utils';
+import {
+  Avatar,
+  AvatarFallback,
+  AvatarImage,
+} from '@client/src/components/ui/avatar';
+import { Badge } from '@client/src/components/ui/badge';
+
+export type ItemPillProps = {
+  /**
+   * 显示的文本
+   */
+  label: string;
+
+  /**
+   * 尺寸
+   * @default "medium"
+   */
+  size?: ComboboxSize;
+
+  /**
+   * 头像 URL
+   */
+  avatarUrl?: string;
+
+  /**
+   * 头像内容（用于自定义头像显示）
+   */
+  avatar?: React.ReactNode;
+
+  /**
+   * 是否显示头像占位符（当没有头像 URL 时显示）
+   * @default false
+   *
+   */
+  avatarFallback?: boolean;
+
+  /**
+   * 自定义样式
+   */
+  className?: string;
+  /**
+   * 是否禁用
+   */
+  disabled?: boolean;
+  /**
+   * 最大文本长度
+   */
+  maxTextLength?: number;
+
+  /**
+   * 后缀
+   */
+  suffix?: React.ReactNode;
+};
+
+// 检查是否是 16 进制 RGB 颜色（如 #RRGGBB 或 #RGB）
+export const isHexColor = (str?: string): boolean => {
+  if (!str) return false;
+  return /^#([0-9A-Fa-f]{3}|[0-9A-Fa-f]{6})$/.test(str);
+};
+
+/**
+ * renderPillAvatar 的参数类型
+ */
+export type RenderPillAvatarOptions = {
+  /**
+   * 头像 URL
+   */
+  avatarUrl?: string;
+  /**
+   * 显示的文本（用于 fallback 首字母）
+   */
+  label: string;
+  /**
+   * 尺寸
+   * @default "medium"
+   */
+  size?: ComboboxSize;
+  /**
+   * 是否显示头像占位符（当没有头像 URL 时显示）
+   * @default true
+   */
+  avatarFallback?: boolean;
+};
+
+/**
+ * 渲染 Pill 头像的辅助函数
+ * 可被其他组件复用（如 UserPill）
+ */
+export const renderPillAvatar = ({
+  avatarUrl,
+  label,
+  size = 'medium',
+  avatarFallback = true,
+}: RenderPillAvatarOptions): React.ReactNode => {
+  if (avatarUrl) {
+    // 如果是 16 进制颜色，渲染带背景色的头像和用户名首字
+    if (isHexColor(avatarUrl)) {
+      return (
+        <Avatar className={tagAvatarVariants({ size })}>
+          <AvatarFallback style={{ backgroundColor: avatarUrl }}>
+            {label?.charAt?.(0).toUpperCase()}
+          </AvatarFallback>
+        </Avatar>
+      );
+    }
+    return (
+      <Avatar className={tagAvatarVariants({ size })}>
+        <AvatarImage src={avatarUrl} alt={label} loading="eager" />
+      </Avatar>
+    );
+  }
+
+  if (avatarFallback) {
+    return (
+      <Avatar className={tagAvatarVariants({ size })}>
+        <AvatarFallback>{label?.charAt?.(0).toUpperCase()}</AvatarFallback>
+      </Avatar>
+    );
+  }
+
+  return null;
+};
+
+export const ItemPill: React.FC<ItemPillProps> = ({
+  className,
+  avatarUrl,
+  disabled,
+  label,
+  maxTextLength,
+  suffix,
+  avatar,
+  avatarFallback = true,
+  size = 'medium',
+}) => {
+  const displayLabel = React.useMemo(() => {
+    if (!maxTextLength || label?.length <= maxTextLength) {
+      return label;
+    }
+    return label.slice(0, maxTextLength) + '...';
+  }, [maxTextLength, label]);
+
+  const avatarElement = React.useMemo(() => {
+    if (avatar) {
+      return avatar;
+    }
+
+    return renderPillAvatar({ avatarUrl, label, size, avatarFallback });
+  }, [avatar, avatarUrl, avatarFallback, label, size]);
+
+  return (
+    <Badge
+      variant="secondary"
+      className={cn(
+        itemPillVariants({ size }),
+        disabled && 'cursor-not-allowed opacity-50',
+        className,
+      )}
+    >
+      {/* 头像 */}
+      {avatarElement}
+      {/* 文本 */}
+      <span className={itemPillTextVariants({ size })}>{displayLabel}</span>
+
+      {suffix}
+    </Badge>
+  );
+};

package/template/client/src/components/business-ui/entity-combobox/popover-wrapper.tsx

@@ -0,0 +1,149 @@
+'use client';
+
+import { BaseComboboxContent } from '@client/src/components/business-ui/entity-combobox/base-combobox-content';
+import { BaseComboboxList } from '@client/src/components/business-ui/entity-combobox/base-combobox-list';
+import { BaseComboboxSearch } from '@client/src/components/business-ui/entity-combobox/base-combobox-search';
+import { BaseComboboxTrigger } from '@client/src/components/business-ui/entity-combobox/base-combobox-trigger';
+import { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+import type {
+  ItemValue,
+  PopoverWrapperProps,
+} from '@client/src/components/business-ui/entity-combobox/types';
+import { cn } from '@/lib/utils';
+import { Popover, PopoverTrigger } from '@client/src/components/ui/popover';
+
+/**
+ * 统一的浮层包装组件
+ * 根据 triggerType 渲染不同的交互模式
+ */
+export function PopoverWrapper<
+  T = unknown,
+  TRaw = unknown,
+  TValue extends ItemValue<TRaw> = ItemValue<TRaw>,
+>(props: PopoverWrapperProps<T, TRaw, TValue>) {
+  const {
+    size,
+    triggerType = 'button',
+    renderTrigger,
+    placeholder,
+    maxTagCount,
+    maxTagTextLength,
+    tagClosable,
+    className,
+    classNames,
+    placement,
+    align,
+    sideOffset,
+    showSearch,
+    searchPlaceholder,
+    renderItem,
+    renderTag,
+    getItemValue,
+    getOptionDisabled,
+    emptyText,
+    loadingText,
+    onFocus,
+    onBlur,
+    slotProps,
+    children,
+  } = props;
+
+  const { open, setOpen, disabled } = useEntityComboboxContext();
+
+  // 处理打开状态变化，如果 disabled 则不允许打开
+  const handleOpenChange = (newOpen: boolean) => {
+    if (disabled && newOpen) return;
+    setOpen(newOpen);
+  };
+
+  // 渲染 Popover 内容
+  const renderPopoverContent = () => (
+    <BaseComboboxContent
+      popoverProps={slotProps?.popover}
+      className={classNames?.popover}
+      side={placement}
+      align={align}
+      sideOffset={sideOffset}
+    >
+      {children || (
+        <>
+          {(showSearch || triggerType === 'search') && (
+            <BaseComboboxSearch
+              placeholder={searchPlaceholder}
+              className={classNames?.search}
+            />
+          )}
+          <BaseComboboxList
+            renderItem={renderItem}
+            getItemValue={getItemValue}
+            getOptionDisabled={
+              getOptionDisabled as ((value: ItemValue) => boolean) | undefined
+            }
+            emptyText={emptyText}
+            loadingText={loadingText}
+            classNames={classNames}
+          />
+        </>
+      )}
+    </BaseComboboxContent>
+  );
+
+  // button 类型：标签在外部，Popover 只包裹加号按钮
+  if (triggerType === 'button') {
+    return (
+      <div className={cn(className, classNames?.root)}>
+        <Popover open={open} onOpenChange={handleOpenChange}>
+          <BaseComboboxTrigger
+            triggerType={triggerType}
+            size={size}
+            placeholder={placeholder}
+            renderTrigger={renderTrigger as any}
+            maxTagCount={maxTagCount}
+            maxTagTextLength={maxTagTextLength}
+            tagClosable={tagClosable}
+            classNames={classNames}
+            onFocus={onFocus}
+            onBlur={onBlur}
+            renderTag={renderTag as any}
+            getOptionDisabled={
+              getOptionDisabled as ((value: ItemValue) => boolean) | undefined
+            }
+            renderAddButton={(buttonProps) => (
+              <PopoverTrigger asChild>{buttonProps}</PopoverTrigger>
+            )}
+          />
+          {renderPopoverContent()}
+        </Popover>
+      </div>
+    );
+  }
+
+  // search 和 custom 类型：整个 trigger 包裹在 Popover 中
+  return (
+    <div className={cn(className, classNames?.root)}>
+      <Popover open={open} onOpenChange={handleOpenChange}>
+        <PopoverTrigger asChild>
+          <div>
+            <BaseComboboxTrigger
+              triggerType={triggerType}
+              size={size}
+              placeholder={placeholder}
+              renderTrigger={renderTrigger as any}
+              maxTagCount={maxTagCount}
+              maxTagTextLength={maxTagTextLength}
+              tagClosable={tagClosable}
+              classNames={classNames}
+              onFocus={onFocus}
+              onBlur={onBlur}
+              renderTag={renderTag as any}
+              getOptionDisabled={
+                getOptionDisabled as ((value: ItemValue) => boolean) | undefined
+              }
+            />
+          </div>
+        </PopoverTrigger>
+        {renderPopoverContent()}
+      </Popover>
+    </div>
+  );
+}

package/template/client/src/components/business-ui/entity-combobox/search-trigger.tsx

@@ -0,0 +1,262 @@
+'use client';
+
+import { ChevronDown, ChevronUp, CircleX, X } from 'lucide-react';
+
+import { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+import {
+  searchTagVariants,
+  searchTriggerVariants,
+  tagCloseIconVariants,
+  type ComboboxSize,
+} from '@client/src/components/business-ui/entity-combobox/size-variants';
+import type {
+  ClassNamesConfig,
+  ItemValue,
+} from '@client/src/components/business-ui/entity-combobox/types';
+import { cn } from '@/lib/utils';
+import { Badge } from '@client/src/components/ui/badge';
+import { Button } from '@client/src/components/ui/button';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from '@client/src/components/ui/tooltip';
+
+export type SearchTriggerProps = {
+  size?: ComboboxSize;
+  placeholder?: string;
+  maxTagCount?: number | 'responsive';
+  maxTagTextLength?: number;
+  tagClosable?: boolean;
+  classNames?: ClassNamesConfig;
+  onFocus?: (e: React.FocusEvent<HTMLDivElement>) => void;
+  onBlur?: (e: React.FocusEvent<HTMLDivElement>) => void;
+  /**
+   * 自定义渲染单个标签
+   * @param value 标签的值对象
+   * @param onClose 关闭标签的回调
+   * @param disabled 是否禁用
+   * @returns ReactNode
+   */
+  renderTag?: (
+    value: ItemValue,
+    onClose: (value: ItemValue, e: React.MouseEvent) => void,
+    disabled?: boolean,
+  ) => React.ReactNode;
+  /**
+   * 判断选项是否禁用
+   */
+  getOptionDisabled?: (value: ItemValue) => boolean;
+  ref?: React.Ref<HTMLDivElement>;
+};
+
+export const SearchTrigger = ({
+  size = 'medium',
+  placeholder = '请选择',
+  maxTagCount,
+  maxTagTextLength,
+  tagClosable = true,
+  classNames,
+  onFocus,
+  onBlur,
+  renderTag,
+  getOptionDisabled,
+  ref,
+}: SearchTriggerProps) => {
+  const {
+    selectedValue,
+    multiple,
+    handleDeselect,
+    handleClear,
+    open,
+    disabled,
+  } = useEntityComboboxContext();
+
+  const selectedArray = Array.isArray(selectedValue) ? selectedValue : [];
+
+  // 计算显示的标签
+  const getDisplayTags = () => {
+    if (!multiple) return [];
+
+    if (typeof maxTagCount === 'number') {
+      return selectedArray.slice(0, maxTagCount);
+    }
+
+    // TODO: responsive 模式需要根据容器宽度计算
+    return selectedArray;
+  };
+
+  const displayTags = getDisplayTags();
+  const hiddenCount =
+    multiple && typeof maxTagCount === 'number'
+      ? Math.max(0, selectedArray.length - maxTagCount)
+      : 0;
+
+  const hiddenTags =
+    multiple && typeof maxTagCount === 'number'
+      ? selectedArray.slice(maxTagCount)
+      : [];
+
+  const handleTagClose = (value: ItemValue, e: React.MouseEvent) => {
+    e.stopPropagation();
+    if (getOptionDisabled?.(value)) return;
+    if (!multiple) {
+      handleClear(); // 单选模式清空
+    } else {
+      handleDeselect(value); // 多选模式删除指定项
+    }
+  };
+
+  const truncateText = (text: string) => {
+    if (!maxTagTextLength || text.length <= maxTagTextLength) {
+      return text;
+    }
+    return text.slice(0, maxTagTextLength) + '...';
+  };
+
+  // 单选模式下显示选中值
+  const displayValue =
+    !multiple && selectedValue && !Array.isArray(selectedValue)
+      ? selectedValue.name
+      : '';
+
+  return (
+    <div
+      ref={ref}
+      tabIndex={disabled ? -1 : 0}
+      role="combobox"
+      aria-expanded={open}
+      aria-controls="combobox-content"
+      aria-disabled={disabled}
+      data-state={open ? 'open' : 'closed'}
+      className={cn(
+        'group',
+        searchTriggerVariants({ size }),
+        disabled && 'cursor-not-allowed bg-muted hover:border-input',
+        classNames?.trigger,
+      )}
+      onFocus={disabled ? undefined : onFocus}
+      onBlur={disabled ? undefined : onBlur}
+    >
+      <div className="flex min-w-0 flex-1 items-center gap-1">
+        {!multiple && displayValue ? (
+          renderTag ? (
+            renderTag(
+              selectedValue as ItemValue,
+              handleTagClose,
+              getOptionDisabled?.(selectedValue as ItemValue),
+            )
+          ) : (
+            <span className="truncate">{displayValue}</span>
+          )
+        ) : multiple && selectedArray.length > 0 ? (
+          <div className="flex flex-wrap gap-1">
+            {displayTags.map((value) =>
+              renderTag ? (
+                renderTag(value, handleTagClose, getOptionDisabled?.(value))
+              ) : (
+                <Badge
+                  key={value.id}
+                  variant="secondary"
+                  className={cn(searchTagVariants({ size }), classNames?.tag)}
+                >
+                  <span>{truncateText(value.name)}</span>
+                  {tagClosable && (
+                    <button
+                      type="button"
+                      className="ml-1 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100"
+                      onClick={(e) => handleTagClose(value, e)}
+                    >
+                      <X className={tagCloseIconVariants({ size })} />
+                    </button>
+                  )}
+                </Badge>
+              ),
+            )}
+            {hiddenCount > 0 && (
+              <Tooltip delayDuration={200}>
+                <TooltipTrigger asChild>
+                  <Badge
+                    variant="secondary"
+                    className={cn(
+                      searchTagVariants({ size }),
+                      'cursor-pointer',
+                    )}
+                  >
+                    +{hiddenCount}
+                  </Badge>
+                </TooltipTrigger>
+                <TooltipContent className="w-auto max-w-80 p-2" align="start">
+                  <div className="flex flex-wrap gap-1">
+                    {hiddenTags.map((value) =>
+                      renderTag ? (
+                        renderTag(
+                          value,
+                          handleTagClose,
+                          getOptionDisabled?.(value),
+                        )
+                      ) : (
+                        <Badge
+                          key={value.id}
+                          variant="secondary"
+                          className={cn(
+                            searchTagVariants({ size }),
+                            classNames?.tag,
+                          )}
+                        >
+                          <span>{truncateText(value.name)}</span>
+                          {tagClosable && (
+                            <button
+                              type="button"
+                              className="ml-1 rounded-sm opacity-70 ring-offset-background transition-opacity hover:opacity-100"
+                              onClick={(e) => handleTagClose(value, e)}
+                            >
+                              <X className={tagCloseIconVariants({ size })} />
+                            </button>
+                          )}
+                        </Badge>
+                      ),
+                    )}
+                  </div>
+                </TooltipContent>
+              </Tooltip>
+            )}
+          </div>
+        ) : (
+          <span className="text-muted-foreground">{placeholder}</span>
+        )}
+      </div>
+
+      {selectedArray.length > 0 && (
+        <Button
+          variant="ghost"
+          size="icon"
+          data-slot="combobox-clear"
+          disabled={disabled}
+          aria-disabled={disabled}
+          className={cn(
+            'flex h-4 w-4 items-center rounded-full text-muted-foreground opacity-0 group-hover:opacity-100 not-disabled:hover:bg-transparent not-disabled:hover:text-primary aria-disabled:opacity-0',
+            classNames?.clear,
+          )}
+          onClick={(e) => {
+            e.stopPropagation();
+            handleClear();
+          }}
+        >
+          <>
+            <CircleX className="h-3! w-3!" />
+            <span className="sr-only">Clear all</span>
+          </>
+        </Button>
+      )}
+
+      <div className={cn('ml-1', classNames?.suffix)}>
+        {open ? (
+          <ChevronUp className="h-4 w-4 shrink-0 opacity-50" />
+        ) : (
+          <ChevronDown className="h-4 w-4 shrink-0 opacity-50" />
+        )}
+      </div>
+    </div>
+  );
+};