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

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

@@ -0,0 +1,281 @@
+'use client';
+
+import { Plus } from 'lucide-react';
+
+import { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+import { SearchTrigger } from '@client/src/components/business-ui/entity-combobox/search-trigger';
+import {
+  addButtonIconVariants,
+  addButtonVariants,
+  type ComboboxSize,
+} from '@client/src/components/business-ui/entity-combobox/size-variants';
+import type {
+  ClassNamesConfig,
+  ItemValue,
+  TriggerRenderProps,
+  TriggerType,
+} 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 BaseComboboxTriggerProps = {
+  triggerType?: TriggerType;
+  size?: ComboboxSize;
+  placeholder?: string;
+  renderTrigger?: (props: TriggerRenderProps) => React.ReactNode;
+  maxTagCount?: number | 'responsive';
+  maxTagTextLength?: number;
+  tagClosable?: boolean;
+  classNames?: ClassNamesConfig;
+  onFocus?: (e: React.FocusEvent<HTMLElement>) => void;
+  onBlur?: (e: React.FocusEvent<HTMLElement>) => void;
+  renderTag?: (
+    value: ItemValue,
+    onClose: (value: ItemValue, e: React.MouseEvent) => void,
+    disabled?: boolean,
+  ) => React.ReactNode;
+  /**
+   * 判断选项是否禁用
+   */
+  getOptionDisabled?: (value: ItemValue) => boolean;
+  /**
+   * button 模式下，自定义渲染加号按钮的包裹器
+   * 用于将按钮包裹在 PopoverTrigger 中，使浮层跟随加号按钮而非整个容器
+   */
+  renderAddButton?: (button: React.ReactNode) => React.ReactNode;
+  ref?: React.Ref<HTMLButtonElement>;
+} & Omit<React.ComponentPropsWithoutRef<'button'>, 'children'>;
+
+export const BaseComboboxTrigger = ({
+  triggerType = 'button',
+  size = 'medium',
+  placeholder = '请选择',
+  renderTrigger,
+  maxTagCount,
+  maxTagTextLength,
+  tagClosable = true,
+  classNames,
+  onFocus,
+  onBlur,
+  renderTag,
+  getOptionDisabled,
+  renderAddButton,
+  ref,
+  ...props
+}: BaseComboboxTriggerProps) => {
+  const {
+    selectedValue,
+    multiple,
+    open,
+    disabled,
+    handleClear,
+    handleDeselect,
+  } = useEntityComboboxContext();
+
+  // 自定义渲染 (custom 类型)
+  if (triggerType === 'custom' && renderTrigger) {
+    return <>{renderTrigger({ selectedValue, multiple, open, disabled })}</>;
+  }
+
+  // search 类型
+  if (triggerType === 'search') {
+    return (
+      <SearchTrigger
+        size={size}
+        placeholder={placeholder}
+        maxTagCount={maxTagCount}
+        maxTagTextLength={maxTagTextLength}
+        tagClosable={tagClosable}
+        classNames={classNames}
+        onFocus={onFocus as (e: React.FocusEvent<HTMLDivElement>) => void}
+        onBlur={onBlur as (e: React.FocusEvent<HTMLDivElement>) => void}
+        renderTag={renderTag}
+        getOptionDisabled={getOptionDisabled}
+      />
+    );
+  }
+
+  // button 类型（默认）
+  const hasValue = !multiple
+    ? !!selectedValue
+    : Array.isArray(selectedValue) && selectedValue.length > 0;
+
+  // 计算最大显示标签数
+  const maxDisplayCount =
+    typeof maxTagCount === 'number' ? maxTagCount : Infinity;
+
+  // 计算隐藏的标签
+  const hiddenCount =
+    multiple && Array.isArray(selectedValue) && typeof maxTagCount === 'number'
+      ? Math.max(0, selectedValue.length - maxTagCount)
+      : 0;
+
+  const hiddenTags =
+    multiple && Array.isArray(selectedValue) && typeof maxTagCount === 'number'
+      ? selectedValue.slice(maxTagCount)
+      : [];
+
+  // 标签关闭回调
+  const handleTagClose = (value: ItemValue, e: React.MouseEvent) => {
+    e.stopPropagation(); // 阻止触发按钮点击
+    // 禁用的选项不允许关闭
+    if (getOptionDisabled?.(value)) return;
+    if (!multiple) {
+      handleClear(); // 单选模式清空
+    } else {
+      handleDeselect(value); // 多选模式删除指定项
+    }
+  };
+
+  return (
+    <div
+      className={cn(
+        'flex w-full flex-wrap items-center gap-2',
+        classNames?.trigger,
+      )}
+    >
+      {/* 已选择的标签显示区域 */}
+      {hasValue && (
+        <>
+          {!multiple && selectedValue ? (
+            renderTag ? (
+              renderTag(
+                selectedValue as ItemValue,
+                handleTagClose,
+                getOptionDisabled?.(selectedValue as ItemValue),
+              )
+            ) : (
+              <Badge
+                variant="secondary"
+                className={cn('h-7 text-xs', classNames?.tag)}
+              >
+                {(selectedValue as ItemValue).name}
+              </Badge>
+            )
+          ) : multiple &&
+            Array.isArray(selectedValue) &&
+            selectedValue.length > 0 ? (
+            <>
+              {renderTag ? (
+                <>
+                  {selectedValue
+                    .slice(0, maxDisplayCount)
+                    .map((item) =>
+                      renderTag(
+                        item,
+                        handleTagClose,
+                        getOptionDisabled?.(item),
+                      ),
+                    )}
+                  {hiddenCount > 0 && (
+                    <Tooltip delayDuration={200}>
+                      <TooltipTrigger asChild>
+                        <Badge
+                          variant="secondary"
+                          className={cn(
+                            'h-7 cursor-pointer text-xs',
+                            classNames?.tag,
+                          )}
+                        >
+                          +{hiddenCount}
+                        </Badge>
+                      </TooltipTrigger>
+                      <TooltipContent
+                        className="w-auto max-w-80 p-2"
+                        align="start"
+                      >
+                        <div className="flex flex-wrap gap-1">
+                          {hiddenTags.map((item) =>
+                            renderTag(
+                              item,
+                              handleTagClose,
+                              getOptionDisabled?.(item),
+                            ),
+                          )}
+                        </div>
+                      </TooltipContent>
+                    </Tooltip>
+                  )}
+                </>
+              ) : (
+                <>
+                  {selectedValue.slice(0, maxDisplayCount).map((item) => (
+                    <Badge
+                      key={item.id}
+                      variant="secondary"
+                      className={cn('h-7 text-xs', classNames?.tag)}
+                    >
+                      {item.name}
+                    </Badge>
+                  ))}
+                  {hiddenCount > 0 && (
+                    <Tooltip delayDuration={200}>
+                      <TooltipTrigger asChild>
+                        <Badge
+                          variant="secondary"
+                          className={cn(
+                            'h-7 cursor-pointer text-xs',
+                            classNames?.tag,
+                          )}
+                        >
+                          +{hiddenCount}
+                        </Badge>
+                      </TooltipTrigger>
+                      <TooltipContent
+                        className="w-auto max-w-80 p-2"
+                        align="start"
+                      >
+                        <div className="flex flex-wrap gap-1">
+                          {hiddenTags.map((item) => (
+                            <Badge
+                              key={item.id}
+                              variant="secondary"
+                              className={cn('h-7 text-xs', classNames?.tag)}
+                            >
+                              {item.name}
+                            </Badge>
+                          ))}
+                        </div>
+                      </TooltipContent>
+                    </Tooltip>
+                  )}
+                </>
+              )}
+            </>
+          ) : null}
+        </>
+      )}
+
+      {/* 加号按钮 - 紧跟标签 */}
+      {(() => {
+        const addButton = (
+          <Button
+            ref={ref}
+            variant="secondary"
+            size="icon"
+            role="combobox"
+            aria-expanded={open}
+            data-state={open ? 'open' : 'closed'}
+            aria-controls="combobox-content"
+            disabled={disabled}
+            className={addButtonVariants({ size })}
+            onFocus={
+              onFocus as (e: React.FocusEvent<HTMLButtonElement>) => void
+            }
+            onBlur={onBlur as (e: React.FocusEvent<HTMLButtonElement>) => void}
+            {...props}
+          >
+            <Plus className={addButtonIconVariants({ size })} />
+          </Button>
+        );
+        return renderAddButton ? renderAddButton(addButton) : addButton;
+      })()}
+    </div>
+  );
+};

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

@@ -0,0 +1,132 @@
+'use client';
+
+import { BaseComboboxContent } from '@client/src/components/business-ui/entity-combobox/base-combobox-content';
+import { BaseComboboxEmpty } from '@client/src/components/business-ui/entity-combobox/base-combobox-empty';
+import { BaseComboboxItem } from '@client/src/components/business-ui/entity-combobox/base-combobox-item';
+import { BaseComboboxList } from '@client/src/components/business-ui/entity-combobox/base-combobox-list';
+import { BaseComboboxLoading } from '@client/src/components/business-ui/entity-combobox/base-combobox-loading';
+import { BaseComboboxSearch } from '@client/src/components/business-ui/entity-combobox/base-combobox-search';
+import { EntityCombobox } from '@client/src/components/business-ui/entity-combobox/entity-combobox';
+import { PopoverWrapper } from '@client/src/components/business-ui/entity-combobox/popover-wrapper';
+import type {
+  BaseComboboxProps,
+  ItemValue,
+} from '@client/src/components/business-ui/entity-combobox/types';
+
+export function BaseCombobox<
+  T = unknown,
+  TRaw = unknown,
+  TValue extends ItemValue<TRaw> = ItemValue<TRaw>,
+>(props: BaseComboboxProps<T, TRaw, TValue>) {
+  const {
+    fetchFn,
+    size = 'medium',
+    triggerType = 'button',
+    renderTrigger,
+    multiple = false,
+    value,
+    defaultValue,
+    onChange,
+    open,
+    defaultOpen,
+    onOpenChange,
+    debounce = 300,
+    disabled = false,
+    showSearch = true,
+    renderItem,
+    renderTag,
+    placeholder = '请选择',
+    searchPlaceholder = '',
+    emptyText = '没有匹配结果，换个关键词试试吧',
+    loadingText = '加载中...',
+    className,
+    classNames = {},
+    tagClosable = true,
+    maxTagCount,
+    maxTagTextLength,
+    placement = 'bottom',
+    align = 'start',
+    sideOffset = 4,
+    onSelect,
+    onDeselect,
+    onSearch,
+    onClear,
+    onFocus,
+    onBlur,
+    getItemValue = (item: unknown) =>
+      ({
+        id:
+          (item as { id?: string; value?: string }).id ||
+          (item as { id?: string; value?: string }).value ||
+          '',
+        name:
+          (item as { name?: string; label?: string }).name ||
+          (item as { name?: string; label?: string }).label ||
+          '',
+        avatar: (item as { avatar?: string }).avatar,
+        raw: item,
+      }) as TValue,
+    getOptionDisabled,
+    slotProps,
+    children,
+  } = props;
+
+  // 浮层包装组件的通用 props
+  const popoverProps = {
+    size,
+    triggerType,
+    renderTrigger,
+    placeholder,
+    maxTagCount,
+    maxTagTextLength,
+    tagClosable,
+    className,
+    classNames,
+    placement,
+    align,
+    sideOffset,
+    showSearch,
+    searchPlaceholder,
+    renderItem: renderItem!,
+    renderTag,
+    getItemValue,
+    getOptionDisabled,
+    emptyText,
+    loadingText,
+    onFocus,
+    onBlur,
+    slotProps,
+    children,
+  };
+
+  return (
+    <EntityCombobox
+      fetchFn={fetchFn}
+      size={size}
+      multiple={multiple}
+      value={value}
+      defaultValue={defaultValue}
+      onChange={onChange}
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      debounce={debounce}
+      disabled={disabled}
+      onSelect={onSelect}
+      onDeselect={onDeselect}
+      onSearch={onSearch}
+      onClear={onClear}
+      getItemValue={getItemValue}
+    >
+      <PopoverWrapper {...popoverProps} />
+    </EntityCombobox>
+  );
+}
+
+// 导出子组件以支持自定义使用
+BaseCombobox.Content = BaseComboboxContent;
+BaseCombobox.Search = BaseComboboxSearch;
+BaseCombobox.List = BaseComboboxList;
+BaseCombobox.Item = BaseComboboxItem;
+BaseCombobox.Empty = BaseComboboxEmpty;
+BaseCombobox.Loading = BaseComboboxLoading;

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

@@ -0,0 +1,19 @@
+'use client';
+
+import { createContext, useContext } from 'react';
+
+import type { EntityComboboxContextValue } from '@client/src/components/business-ui/entity-combobox/types';
+
+const EntityComboboxContext = createContext<any | undefined>(undefined);
+
+export const EntityComboboxProvider = EntityComboboxContext.Provider;
+
+export function useEntityComboboxContext(): EntityComboboxContextValue {
+  const context = useContext(EntityComboboxContext);
+  if (!context) {
+    throw new Error(
+      'useEntityComboboxContext must be used within EntityCombobox',
+    );
+  }
+  return context;
+}

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

@@ -0,0 +1,145 @@
+'use client';
+
+import { useCallback, useState } from 'react';
+import { useControllableState } from 'radix-ui/internal';
+
+import { EntityComboboxProvider } from '@client/src/components/business-ui/entity-combobox/context';
+import { useDebounce } from '@client/src/components/business-ui/entity-combobox/hooks';
+import type {
+  EntityComboboxProps,
+  ItemValue,
+} from '@client/src/components/business-ui/entity-combobox/types';
+import { useFetchData } from '@client/src/components/business-ui/entity-combobox/use-fetch-data';
+
+export function EntityCombobox<
+  T = unknown,
+  TRaw = unknown,
+  TValue extends ItemValue<TRaw> = ItemValue<TRaw>,
+>(props: EntityComboboxProps<T, TRaw, TValue>) {
+  const {
+    fetchFn,
+    size = 'medium',
+    multiple = false,
+    value: valueProp,
+    defaultValue,
+    onChange,
+    open: openProp,
+    defaultOpen = false,
+    onOpenChange,
+    debounce = 300,
+    disabled = false,
+    onSelect,
+    onDeselect,
+    onSearch,
+    onClear,
+    children,
+    getItemValue,
+  } = props;
+
+  // 受控状态
+  const [selectedValue, setSelectedValue] = useControllableState({
+    prop: valueProp,
+    defaultProp: defaultValue ?? (!multiple ? null : []),
+    onChange,
+  });
+
+  const [searchValue, setSearchValue] = useState('');
+  const debouncedSearch = useDebounce(searchValue, debounce);
+
+  // 代理 onOpenChange，关闭时清空搜索
+  const handleOpenChange = useCallback(
+    (newOpen: boolean) => {
+      if (!newOpen) {
+        setSearchValue('');
+      }
+      onOpenChange?.(newOpen);
+    },
+    [onOpenChange],
+  );
+
+  const [open, setOpen] = useControllableState({
+    prop: openProp,
+    defaultProp: defaultOpen,
+    onChange: handleOpenChange,
+  });
+
+  // 使用自定义 hook 处理数据请求
+  const { data, isFetching, isError, isSuccess, fetchStatus, refetch } =
+    useFetchData<T>({
+      fetchFn,
+      enabled: open,
+      search: debouncedSearch,
+      onSearch,
+    });
+
+  // 选择逻辑
+  const handleSelect = useCallback(
+    (itemValue: TValue) => {
+      if (!multiple) {
+        setSelectedValue(itemValue);
+        setOpen(false);
+        onSelect?.(itemValue);
+      } else {
+        const current = Array.isArray(selectedValue) ? selectedValue : [];
+        const isSelected = current.some((v) => v.id === itemValue.id);
+
+        if (isSelected) {
+          const newValue = current.filter((v) => v.id !== itemValue.id);
+          setSelectedValue(newValue);
+          onDeselect?.(itemValue);
+        } else {
+          const newValue = [...current, itemValue];
+          setSelectedValue(newValue);
+          onSelect?.(itemValue);
+        }
+      }
+    },
+    [multiple, selectedValue, setSelectedValue, setOpen, onSelect, onDeselect],
+  );
+
+  const handleDeselect = useCallback(
+    (itemValue: TValue) => {
+      if (multiple && Array.isArray(selectedValue)) {
+        const newValue = selectedValue.filter((v) => v.id !== itemValue.id);
+        setSelectedValue(newValue);
+        onDeselect?.(itemValue);
+      }
+    },
+    [multiple, selectedValue, setSelectedValue, onDeselect],
+  );
+
+  const handleClear = useCallback(() => {
+    setSelectedValue(!multiple ? null : []);
+    onClear?.();
+  }, [multiple, setSelectedValue, onClear]);
+
+  // Context 值
+  const contextValue = {
+    open,
+    setOpen,
+    searchValue,
+    setSearchValue,
+    selectedValue: selectedValue ?? (!multiple ? null : []),
+    debouncedSearch,
+    handleSelect,
+    handleDeselect,
+    handleClear,
+    data,
+    isFetching,
+    isError,
+    refetch,
+    isSuccess,
+    fetchStatus,
+    isPlaceholderData: false,
+    multiple,
+    disabled,
+    size,
+    getItemValue: getItemValue as (item: unknown) => ItemValue,
+  };
+
+  return (
+    <EntityComboboxProvider value={contextValue}>
+      {children}
+    </EntityComboboxProvider>
+  );
+}

package/template/client/src/components/business-ui/entity-combobox/highlight-text.tsx

@@ -0,0 +1,52 @@
+'use client';
+
+import { useMemo } from 'react';
+
+export type HighlightTextProps = {
+  text: string;
+  highlight?: string;
+  className?: string;
+  highlightClassName?: string;
+};
+
+/**
+ * 高亮文本组件
+ * 将文本中匹配的部分用高亮样式标记
+ */
+export const HighlightText = ({
+  text,
+  highlight,
+  className,
+  highlightClassName = 'text-primary',
+}: HighlightTextProps) => {
+  const parts = useMemo(() => {
+    if (!highlight?.trim()) {
+      return [{ text, isMatch: false }];
+    }
+
+    const escapedHighlight = highlight.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const regex = new RegExp(`(${escapedHighlight})`, 'gi');
+    const splitParts = text.split(regex);
+
+    return splitParts
+      .filter((part) => part !== '')
+      .map((part) => ({
+        text: part,
+        isMatch: part.toLowerCase() === highlight.toLowerCase(),
+      }));
+  }, [text, highlight]);
+
+  return (
+    <span className={className}>
+      {parts.map((part, index) =>
+        part.isMatch ? (
+          <span key={index} className={highlightClassName}>
+            {part.text}
+          </span>
+        ) : (
+          <span key={index}>{part.text}</span>
+        ),
+      )}
+    </span>
+  );
+};

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

@@ -0,0 +1,21 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+
+export function useDebounce<T>(value: T, delay: number): T {
+  const [debouncedValue, setDebouncedValue] = useState(value);
+
+  useEffect(() => {
+    const handler = setTimeout(() => {
+      setDebouncedValue(value);
+    }, delay);
+
+    return () => {
+      clearTimeout(handler);
+    };
+  }, [value, delay]);
+
+  return debouncedValue;
+}

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

@@ -0,0 +1,31 @@
+// Entity Combobox
+export { EntityCombobox } from '@client/src/components/business-ui/entity-combobox/entity-combobox';
+export { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+export type {
+  EntityComboboxProps,
+  EntityComboboxContextValue,
+} from '@client/src/components/business-ui/entity-combobox/types';
+
+// Base Combobox
+export { BaseCombobox } from '@client/src/components/business-ui/entity-combobox/base-combobox';
+export { BaseComboboxItem } from '@client/src/components/business-ui/entity-combobox/base-combobox-item';
+export { BaseComboboxList } from '@client/src/components/business-ui/entity-combobox/base-combobox-list';
+export { BaseComboboxSearch } from '@client/src/components/business-ui/entity-combobox/base-combobox-search';
+export { BaseComboboxTrigger } from '@client/src/components/business-ui/entity-combobox/base-combobox-trigger';
+export { BaseComboboxContent } from '@client/src/components/business-ui/entity-combobox/base-combobox-content';
+export { BaseComboboxEmpty } from '@client/src/components/business-ui/entity-combobox/base-combobox-empty';
+export { BaseComboboxLoading } from '@client/src/components/business-ui/entity-combobox/base-combobox-loading';
+export { BaseComboboxError } from '@client/src/components/business-ui/entity-combobox/base-combobox-error';
+
+// Components
+export { ItemPill } from '@client/src/components/business-ui/entity-combobox/item-pill';
+
+// Types
+export type {
+  ItemValue,
+  TriggerType,
+  TriggerRenderProps,
+  BaseEntitySelectProps,
+  ClassNamesConfig,
+  PopoverSlotProps,
+} from '@client/src/components/business-ui/entity-combobox/shared-types';