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

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

@@ -0,0 +1,168 @@
+'use client';
+
+import { useMemo } from 'react';
+
+import { searchDepartments } from '@client/src/components/business-ui/api/departments/service';
+import { DepartmentItem } from '@client/src/components/business-ui/department-select/department-item';
+import { DepartmentSelectTag } from '@client/src/components/business-ui/department-select/department-select-tag';
+import type {
+  Department,
+  DepartmentSelectProps,
+} from '@client/src/components/business-ui/department-select/types';
+import { departmentInfoToDepartment } from '@client/src/components/business-ui/department-select/utils';
+import { BaseCombobox } from '@client/src/components/business-ui/entity-combobox/base-combobox';
+import { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+
+function createDepartmentsFetcher(pageSize = 100) {
+  return async (search: string) => {
+    const response = await searchDepartments({ query: search, pageSize });
+    const departmentList = response?.data?.departmentList || [];
+
+    return {
+      items: departmentList.map(departmentInfoToDepartment),
+    };
+  };
+}
+
+// 内部包装组件用于获取 context 中的 size
+const DepartmentItemWrapper = ({
+  departmentValue,
+  isSelected,
+  className,
+  disabled,
+}: {
+  departmentValue: Department;
+  isSelected: boolean;
+  className?: string;
+  disabled?: boolean;
+}) => {
+  const { size, searchValue } = useEntityComboboxContext();
+  return (
+    <DepartmentItem
+      departmentValue={departmentValue}
+      isSelected={isSelected}
+      className={className}
+      size={size}
+      searchKeyword={searchValue}
+      disabled={disabled}
+    />
+  );
+};
+
+const DepartmentSelectTagWrapper = ({
+  departmentValue,
+  onClose,
+  className,
+  disabled,
+}: {
+  departmentValue: Department;
+  onClose: (value: Department, e: React.MouseEvent) => void;
+  className?: string;
+  disabled?: boolean;
+}) => {
+  const { size } = useEntityComboboxContext();
+  return (
+    <DepartmentSelectTag
+      departmentValue={departmentValue}
+      onClose={onClose}
+      className={className}
+      size={size}
+      disabled={disabled}
+    />
+  );
+};
+
+export const DepartmentSelect = (props: DepartmentSelectProps) => {
+  const {
+    size = 'medium',
+    triggerType = 'button',
+    renderTrigger,
+    multiple,
+    value,
+    defaultValue,
+    onChange,
+    defaultOpen,
+    disabled,
+    autoFocus,
+    required,
+    name,
+    className,
+    classNames,
+    placeholder = '请选择部门',
+    emptyText = '没有匹配结果，换个关键词试试吧',
+    tagClosable,
+    maxTagCount,
+    onSelect,
+    onDeselect,
+    onClear,
+    onFocus,
+    onBlur,
+    slotProps,
+    getOptionDisabled,
+  } = props;
+
+  const fetchFn = useMemo(() => createDepartmentsFetcher(), []);
+
+  return (
+    <BaseCombobox
+      classNames={classNames}
+      fetchFn={fetchFn}
+      size={size}
+      triggerType={triggerType}
+      renderTrigger={renderTrigger}
+      multiple={multiple}
+      value={value}
+      defaultValue={defaultValue}
+      onChange={onChange}
+      defaultOpen={defaultOpen}
+      disabled={disabled}
+      autoFocus={autoFocus}
+      required={required}
+      name={name}
+      className={className}
+      placeholder={placeholder}
+      emptyText={emptyText}
+      tagClosable={tagClosable}
+      maxTagCount={maxTagCount}
+      onSelect={onSelect}
+      onDeselect={onDeselect}
+      onClear={onClear}
+      onFocus={onFocus}
+      onBlur={onBlur}
+      showSearch
+      searchPlaceholder=""
+      debounce={300}
+      getItemValue={(departmentValue) => departmentValue}
+      getItemLabel={(departmentValue) => departmentValue.name}
+      getOptionDisabled={getOptionDisabled}
+      renderItem={(
+        departmentValue,
+        isSelected,
+        itemClassName,
+        itemDisabled,
+      ) => (
+        <DepartmentItemWrapper
+          key={departmentValue.id}
+          departmentValue={departmentValue}
+          isSelected={isSelected}
+          className={itemClassName}
+          disabled={itemDisabled}
+        />
+      )}
+      renderTag={(departmentValue, onClose, tagDisabled) => (
+        <DepartmentSelectTagWrapper
+          key={departmentValue.id}
+          departmentValue={departmentValue}
+          onClose={onClose}
+          disabled={tagDisabled}
+        />
+      )}
+      slotProps={slotProps}
+    />
+  );
+};
+
+export type {
+  DepartmentInfo,
+  Department,
+} from '@client/src/components/business-ui/department-select/types';

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

@@ -0,0 +1,22 @@
+'use client';
+
+import type { SVGProps } from 'react';
+
+export const IconDepartment = (props: SVGProps<SVGSVGElement>) => {
+  return (
+    <svg
+      width="20"
+      height="20"
+      viewBox="0 0 20 20"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+      {...props}
+    >
+      <rect width="20" height="20" rx="10" fill="#1456F0" />
+      <path
+        d="M7.6267 11.8751H12.3734C12.4775 11.8126 12.5896 11.7626 12.7084 11.7272L12.7084 10.833C12.7084 10.7225 12.6645 10.6165 12.5863 10.5384C12.5082 10.4602 12.4022 10.4163 12.2917 10.4163H7.70838C7.59787 10.4163 7.49189 10.4602 7.41375 10.5384C7.33561 10.6165 7.29171 10.7225 7.29171 10.833L7.2917 11.7272C7.41045 11.7626 7.52274 11.8126 7.6267 11.8751ZM6.45837 11.7272L6.45838 10.833C6.45838 10.5015 6.59008 10.1835 6.8245 9.94911C7.05892 9.71469 7.37686 9.58299 7.70838 9.58299H9.58338V8.69716C9.1906 8.59574 8.8483 8.35456 8.62063 8.01882C8.39296 7.68308 8.29555 7.27583 8.34666 6.87341C8.39778 6.47099 8.5939 6.10102 8.89828 5.83286C9.20266 5.56469 9.59439 5.41675 10 5.41675C10.4057 5.41675 10.7974 5.56469 11.1018 5.83286C11.4062 6.10102 11.6023 6.47099 11.6534 6.87341C11.7045 7.27583 11.6071 7.68308 11.3795 8.01882C11.1518 8.35456 10.8095 8.59574 10.4167 8.69716V9.58299H12.2917C12.6232 9.58299 12.9412 9.71469 13.1756 9.94911C13.41 10.1835 13.5417 10.5015 13.5417 10.833L13.5417 11.7272C13.8623 11.8227 14.1403 12.0256 14.329 12.3018C14.5178 12.5779 14.6059 12.9106 14.5786 13.244C14.5512 13.5774 14.41 13.8913 14.1788 14.133C13.9475 14.3747 13.6402 14.5295 13.3083 14.5715C12.9764 14.6135 12.6402 14.5402 12.356 14.3637C12.0718 14.1873 11.8568 13.9185 11.7472 13.6025C11.6377 13.2864 11.6401 12.9423 11.7541 12.6278C11.8681 12.3133 12.0867 12.0475 12.3734 11.8751H7.6267C7.91336 12.0475 8.13201 12.3133 8.24601 12.6278C8.36 12.9423 8.36241 13.2864 8.25282 13.6025C8.14324 13.9185 7.92832 14.1873 7.64411 14.3637C7.35989 14.5402 7.02366 14.6135 6.69179 14.5715C6.35992 14.5295 6.05258 14.3747 5.8213 14.133C5.59003 13.8913 5.44887 13.5774 5.42151 13.244C5.39415 12.9106 5.48225 12.5779 5.67102 12.3018C5.8598 12.0256 6.13779 11.8227 6.45837 11.7272ZM10 7.91632C10.2211 7.91632 10.433 7.82853 10.5893 7.67225C10.7456 7.51597 10.8334 7.304 10.8334 7.08299C10.8334 6.86198 10.7456 6.65002 10.5893 6.49374C10.433 6.33746 10.2211 6.24966 10 6.24966C9.77903 6.24966 9.56707 6.33746 9.41079 6.49374C9.25451 6.65002 9.16671 6.86198 9.16671 7.08299C9.16671 7.304 9.25451 7.51597 9.41079 7.67225C9.56707 7.82853 9.77903 7.91632 10 7.91632ZM13.125 13.7501C13.2908 13.7501 13.4498 13.6842 13.567 13.567C13.6842 13.4498 13.75 13.2908 13.75 13.1251C13.75 12.9593 13.6842 12.8004 13.567 12.6831C13.4498 12.5659 13.2908 12.5001 13.125 12.5001C12.9593 12.5001 12.8003 12.5659 12.6831 12.6831C12.5659 12.8004 12.5 12.9593 12.5 13.1251C12.5 13.2908 12.5659 13.4498 12.6831 13.567C12.8003 13.6842 12.9593 13.7501 13.125 13.7501ZM6.87504 13.7501C7.0408 13.7501 7.19977 13.6842 7.31698 13.567C7.43419 13.4498 7.50004 13.2908 7.50004 13.1251C7.50004 12.9593 7.43419 12.8004 7.31698 12.6831C7.19977 12.5659 7.0408 12.5001 6.87504 12.5001C6.70928 12.5001 6.5503 12.5659 6.43309 12.6831C6.31588 12.8004 6.25004 12.9593 6.25004 13.1251C6.25004 13.2908 6.31588 13.4498 6.43309 13.567C6.5503 13.6842 6.70928 13.7501 6.87504 13.7501Z"
+        fill="white"
+      />
+    </svg>
+  );
+};

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

@@ -0,0 +1,7 @@
+export { DepartmentSelect } from '@client/src/components/business-ui/department-select/department-select';
+export { DepartmentSelectField } from '@client/src/components/business-ui/department-select/department-select-field';
+export type {
+  DepartmentInfo as Department,
+  DepartmentSelectProps,
+  Department as DepartmentValue,
+} from '@client/src/components/business-ui/department-select/types';

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

@@ -0,0 +1,15 @@
+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 DepartmentInfo = {
+  departmentID: string;
+  larkDepartmentID: string;
+  name: I18nText;
+};
+
+export type Department = ItemValue<DepartmentInfo>;
+
+export type DepartmentSelectProps = BaseEntitySelectProps<Department>;

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

@@ -0,0 +1,17 @@
+import type { DepartmentInfo } from '@lark-apaas/client-toolkit/tools/services';
+
+import type { Department } from './types';
+
+export function getDepartmentDisplayName(name: DepartmentInfo['name']): string {
+  return name?.zh_cn || name?.en_us || '';
+}
+
+export function departmentInfoToDepartment(
+  departmentInfo: DepartmentInfo,
+): Department {
+  return {
+    id: departmentInfo.departmentID,
+    name: getDepartmentDisplayName(departmentInfo.name),
+    raw: departmentInfo,
+  };
+}

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

@@ -0,0 +1,35 @@
+'use client';
+
+import { type PopoverSlotProps } from '@client/src/components/business-ui/entity-combobox/shared-types';
+import { cn } from '@/lib/utils';
+import { Command } from '@client/src/components/ui/command';
+import { PopoverContent } from '@client/src/components/ui/popover';
+
+export const BaseComboboxContent = ({
+  children,
+  className,
+  side,
+  align,
+  sideOffset,
+  popoverProps,
+}: {
+  children: React.ReactNode;
+  className?: string;
+  side?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+  sideOffset?: number;
+  popoverProps?: PopoverSlotProps['popover'];
+}) => {
+  return (
+    <PopoverContent
+      className={cn('w-[270px] p-0', className)}
+      side={side}
+      align={align}
+      sideOffset={sideOffset}
+      forceMount
+      {...popoverProps}
+    >
+      <Command shouldFilter={false}>{children}</Command>
+    </PopoverContent>
+  );
+};

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

@@ -0,0 +1,28 @@
+'use client';
+
+import { CommandEmpty } from 'cmdk';
+
+import { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+import { cn } from '@/lib/utils';
+
+export const BaseComboboxEmpty = ({
+  text = '没有匹配结果，换个关键词试试吧',
+  className,
+}: {
+  text?: string;
+  className?: string;
+}) => {
+  const { size } = useEntityComboboxContext();
+
+  return (
+    <CommandEmpty
+      className={cn(
+        'px-2 text-sm leading-normal text-muted-foreground',
+        size === 'xs' ? 'pt-3' : 'pt-4',
+        className,
+      )}
+    >
+      {text}
+    </CommandEmpty>
+  );
+};

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

@@ -0,0 +1,35 @@
+'use client';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@client/src/components/ui/button';
+
+export type BaseComboboxErrorProps = {
+  onRetry?: () => void;
+  className?: string;
+};
+
+export const BaseComboboxError = ({
+  onRetry,
+  className,
+}: BaseComboboxErrorProps) => {
+  return (
+    <div
+      className={cn(
+        'flex gap-2 px-2 pt-4 text-sm leading-normal text-muted-foreground',
+        className,
+      )}
+    >
+      <div className="max-w-full truncate text-muted-foreground">
+        加载失败，请检查网络后重试
+      </div>
+      <Button
+        variant="ghost"
+        size="sm"
+        onClick={onRetry}
+        className="h-auto px-0 text-primary"
+      >
+        刷新
+      </Button>
+    </div>
+  );
+};

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

@@ -0,0 +1,55 @@
+'use client';
+
+import { Check } from 'lucide-react';
+
+import { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+import type { ItemValue } from '@client/src/components/business-ui/entity-combobox/types';
+import { cn } from '@/lib/utils';
+import { CommandItem } from '@client/src/components/ui/command';
+
+export type BaseComboboxItemProps<T = unknown> = {
+  item: T;
+  getItemValue: (item: T) => ItemValue;
+  isSelected: boolean;
+  children: React.ReactNode;
+  onSelect?: () => void;
+  className?: string;
+  /**
+   * 是否禁用该选项
+   * 禁用时不能改变选中状态
+   */
+  disabled?: boolean;
+};
+
+export function BaseComboboxItem<T>({
+  item,
+  getItemValue,
+  isSelected,
+  children,
+  onSelect,
+  className,
+  disabled,
+}: BaseComboboxItemProps<T>) {
+  const { handleSelect } = useEntityComboboxContext();
+  const itemValue = getItemValue(item);
+
+  return (
+    <CommandItem
+      value={itemValue.id}
+      disabled={disabled}
+      onSelect={() => {
+        if (disabled) return;
+        handleSelect(itemValue);
+        onSelect?.();
+      }}
+      className={cn(
+        'flex items-center gap-2',
+        disabled && 'cursor-not-allowed opacity-50',
+        className,
+      )}
+    >
+      {children}
+      {isSelected && <Check className="ml-auto h-4 w-4 text-primary" />}
+    </CommandItem>
+  );
+}

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

@@ -0,0 +1,174 @@
+'use client';
+
+import React, { useCallback } from 'react';
+
+import { BaseComboboxEmpty } from '@client/src/components/business-ui/entity-combobox/base-combobox-empty';
+import { BaseComboboxError } from '@client/src/components/business-ui/entity-combobox/base-combobox-error';
+import { BaseComboboxLoading } from '@client/src/components/business-ui/entity-combobox/base-combobox-loading';
+import { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+import {
+  skeletonAvatarVariants,
+  skeletonItemVariants,
+} from '@client/src/components/business-ui/entity-combobox/size-variants';
+import type { ItemValue } from '@client/src/components/business-ui/entity-combobox/types';
+import { CommandGroup, CommandList } from '@client/src/components/ui/command';
+import { ScrollArea } from '@client/src/components/ui/scroll-area';
+import { Skeleton } from '@client/src/components/ui/skeleton';
+
+export type BaseComboboxListProps<T = unknown> = {
+  renderItem: (
+    item: T,
+    isSelected: boolean,
+    itemClassName?: string,
+    disabled?: boolean,
+  ) => React.ReactNode;
+  getItemValue: (item: T) => ItemValue;
+  /**
+   * 判断选项是否禁用
+   */
+  getOptionDisabled?: (value: ItemValue) => boolean;
+  emptyText?: string;
+  loadingText?: string;
+  classNames?: {
+    list?: string;
+    listItem?: string;
+    empty?: string;
+    loading?: string;
+    error?: string;
+  };
+};
+
+export function BaseComboboxList<T>({
+  renderItem,
+  getItemValue,
+  getOptionDisabled,
+  emptyText,
+  loadingText,
+  classNames = {},
+}: BaseComboboxListProps<T>) {
+  const {
+    data,
+    isFetching,
+    selectedValue,
+    debouncedSearch,
+    isError,
+    refetch,
+    isSuccess,
+    size,
+  } = useEntityComboboxContext();
+
+  const isItemSelected = useCallback(
+    (item: T) => {
+      const itemValue = getItemValue(item);
+      if (Array.isArray(selectedValue)) {
+        return selectedValue.some((v) => v.id === itemValue.id);
+      }
+      return selectedValue?.id === itemValue.id;
+    },
+    [getItemValue, selectedValue],
+  );
+
+  const isItemDisabled = useCallback(
+    (item: T) => {
+      if (!getOptionDisabled) return false;
+      const itemValue = getItemValue(item);
+      return getOptionDisabled(itemValue);
+    },
+    [getItemValue, getOptionDisabled],
+  );
+
+  const hasSearchQuery = debouncedSearch.trim() !== '';
+
+  // 1. 没有搜索词时显示 placeholder
+  const shouldShowPlaceHolder = !hasSearchQuery;
+  // 2. 搜索出错时显示错误状态
+  const shouldShowError = isError && hasSearchQuery;
+  // 3. 首次搜索无已有数据时显示骨架屏
+  const shouldShowSkeleton =
+    isFetching && (data === undefined || data?.length === 0) && hasSearchQuery;
+  // 4. 有已有内容触发搜索时显示蒙层 loading
+  const shouldShowSpinner =
+    isFetching && data !== undefined && data.length > 0 && hasSearchQuery;
+  // 5. 搜索完成结果为空时显示空状态
+  const shouldShowEmpty =
+    !isFetching && isSuccess && data?.length === 0 && hasSearchQuery;
+
+  const content = (() => {
+    if (shouldShowPlaceHolder) {
+      return (
+        <BaseComboboxEmpty text={'请输入关键词'} className={classNames.empty} />
+      );
+    }
+
+    if (shouldShowError) {
+      return (
+        <BaseComboboxError onRetry={refetch} className={classNames.error} />
+      );
+    }
+
+    if (shouldShowSpinner) {
+      return (
+        <>
+          <div className="absolute inset-0 z-50 flex items-center justify-center bg-popover opacity-40">
+            <BaseComboboxLoading
+              text={loadingText}
+              className={classNames.loading}
+            />
+          </div>
+          {(data as T[]).map((item) =>
+            renderItem(
+              item,
+              isItemSelected(item),
+              classNames.listItem,
+              isItemDisabled(item),
+            ),
+          )}
+        </>
+      );
+    }
+
+    if (shouldShowSkeleton) {
+      return (
+        <div className="absolute inset-0 overflow-hidden! bg-background p-1 py-1.5">
+          {Array.from({ length: 5 }).map((_, index) => (
+            <div key={index} className={skeletonItemVariants({ size })}>
+              <Skeleton className={skeletonAvatarVariants({ size })} />
+              <div className="flex-1 space-y-1">
+                <Skeleton className="h-4 w-full" />
+                <Skeleton className="h-3 w-3/4" />
+              </div>
+            </div>
+          ))}
+        </div>
+      );
+    }
+
+    if (shouldShowEmpty) {
+      return (
+        <BaseComboboxEmpty text={emptyText} className={classNames.empty} />
+      );
+    }
+
+    return ((data as T[]) ?? []).map((item) =>
+      renderItem(
+        item,
+        isItemSelected(item),
+        classNames.listItem,
+        isItemDisabled(item),
+      ),
+    );
+  })();
+
+  return (
+    <CommandList className={classNames.list} autoFocus>
+      <div className="relative">
+        <ScrollArea
+          className={`max-h-[300px] [&>[data-radix-scroll-area-viewport]>div]:block! ${size === 'xs' ? 'min-h-[54px]' : 'min-h-[58px]'}`}
+          onWheel={(e: React.WheelEvent<HTMLDivElement>) => e.stopPropagation()}
+        >
+          <CommandGroup className="w-full">{content}</CommandGroup>
+        </ScrollArea>
+      </div>
+    </CommandList>
+  );
+}

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

@@ -0,0 +1,19 @@
+'use client';
+
+import { cn } from '@/lib/utils';
+import { Spinner } from '@client/src/components/ui/spinner';
+
+export const BaseComboboxLoading = ({
+  className,
+}: {
+  text?: string;
+  className?: string;
+}) => {
+  return (
+    <div
+      className={cn('flex items-center justify-center gap-2 py-6', className)}
+    >
+      <Spinner className="size-4.5 text-primary" />
+    </div>
+  );
+};

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

@@ -0,0 +1,31 @@
+'use client';
+
+import { useEntityComboboxContext } from '@client/src/components/business-ui/entity-combobox/context';
+import { searchInputVariants } from '@client/src/components/business-ui/entity-combobox/size-variants';
+import { cn } from '@/lib/utils';
+import { CommandInput } from '@client/src/components/ui/command';
+
+export type BaseComboboxSearchProps = {
+  placeholder?: string;
+  className?: string;
+  ref?: React.Ref<HTMLInputElement>;
+};
+
+export const BaseComboboxSearch = ({
+  placeholder = '搜索...',
+  className,
+  ref,
+}: BaseComboboxSearchProps) => {
+  const { searchValue, setSearchValue, size } = useEntityComboboxContext();
+
+  return (
+    <CommandInput
+      ref={ref}
+      autoFocus
+      value={searchValue}
+      onValueChange={setSearchValue}
+      placeholder={placeholder}
+      className={cn(searchInputVariants({ size }), className)}
+    />
+  );
+};