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

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

@@ -0,0 +1,246 @@
+import type { ReactNode } from 'react';
+
+import type {
+  ClassNamesConfig,
+  ComboboxSize,
+  ItemValue,
+  PopoverSlotProps,
+  TriggerRenderProps,
+  TriggerType,
+} from '@client/src/components/business-ui/entity-combobox/shared-types';
+
+// 重新导出共享类型
+export type {
+  ItemValue,
+  TriggerType,
+  TriggerRenderProps,
+  ClassNamesConfig,
+  PopoverSlotProps,
+  ComboboxSize,
+};
+
+/**
+ * EntityCombobox 组件的 Props
+ */
+export type EntityComboboxProps<
+  T = unknown,
+  TRaw = unknown,
+  TValue extends ItemValue<TRaw> = ItemValue<TRaw>,
+> = {
+  // 尺寸
+  size?: ComboboxSize;
+
+  // 数据获取
+  fetchFn: (search: string) => Promise<{ items: T[] }>;
+
+  // 受控/非受控
+  multiple?: boolean;
+  value?: TValue | TValue[] | null;
+  defaultValue?: TValue | TValue[] | null;
+  onChange?: (value: TValue | TValue[] | null) => void;
+
+  // 弹层控制
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+
+  // 配置
+  pageSize?: number;
+  debounce?: number;
+  disabled?: boolean;
+
+  // 回调
+  onSelect?: (value: TValue) => void;
+  onDeselect?: (value: TValue) => void;
+  onSearch?: (value: string) => void;
+  onClear?: () => void;
+
+  children: ReactNode;
+
+  // 转换函数
+  getItemValue: (item: T) => TValue;
+};
+
+/**
+ * EntityCombobox Context 值
+ */
+export type EntityComboboxContextValue<
+  T = unknown,
+  TRaw = unknown,
+  TValue extends ItemValue<TRaw> = ItemValue<TRaw>,
+> = {
+  // 状态
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  searchValue: string;
+  setSearchValue: (value: string) => void;
+  selectedValue: TValue | TValue[] | null;
+  debouncedSearch: string;
+
+  // 方法
+  handleSelect: (value: TValue) => void;
+  handleDeselect: (value: TValue) => void;
+  handleClear: () => void;
+
+  // 数据
+  data: T[];
+  isFetching: boolean;
+  isPending: boolean;
+  isError: boolean;
+  refetch: () => void;
+
+  // 配置
+  multiple: boolean;
+  disabled: boolean;
+  size: ComboboxSize;
+  isSuccess?: boolean;
+  fetchStatus?: string;
+  isPlaceholderData?: boolean;
+
+  // 转换函数
+  getItemValue: (item: T) => TValue;
+};
+
+/**
+ * BaseCombobox 组件的 Props
+ */
+export type BaseComboboxProps<
+  T = unknown,
+  TRaw = unknown,
+  TValue extends ItemValue<TRaw> = ItemValue<TRaw>,
+> = {
+  // 尺寸
+  size?: ComboboxSize;
+
+  // 数据获取
+  fetchFn: (search: string) => Promise<{ items: T[] }>;
+
+  // 触发器
+  triggerType?: TriggerType;
+  renderTrigger?: (props: TriggerRenderProps<TRaw>) => ReactNode;
+
+  // 受控/非受控
+  multiple?: boolean;
+  value?: TValue | TValue[] | null;
+  defaultValue?: TValue | TValue[] | null;
+  onChange?: (value: TValue | TValue[] | null) => void;
+
+  // 弹层控制
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+
+  // 配置
+  debounce?: number;
+  disabled?: boolean;
+  showSearch?: boolean;
+  autoFocus?: boolean;
+  required?: boolean;
+  name?: string;
+
+  // 渲染函数
+  renderItem: (
+    item: T,
+    isSelected: boolean,
+    className?: string,
+    disabled?: boolean,
+  ) => ReactNode;
+  renderTag?: (
+    value: TValue,
+    onClose: (value: TValue, e: React.MouseEvent) => void,
+    disabled?: boolean,
+  ) => ReactNode;
+  /**
+   * 判断选项是否禁用
+   * @param value 选项值
+   * @returns 如果返回 true，该选项将被禁用
+   */
+  getOptionDisabled?: (value: TValue) => boolean;
+  getItemLabel?: (item: T) => string;
+
+  // Placeholder
+  placeholder?: string;
+  searchPlaceholder?: string;
+  emptyText?: string;
+  loadingText?: string;
+
+  // 样式
+  className?: string;
+  classNames?: ClassNamesConfig;
+
+  // 标签（多选）
+  tagClosable?: boolean;
+  maxTagCount?: number | 'responsive';
+  maxTagTextLength?: number;
+
+  // Popover 配置
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+  sideOffset?: number;
+
+  // 回调
+  onSelect?: (value: TValue) => void;
+  onDeselect?: (value: TValue) => void;
+  onSearch?: (value: string) => void;
+  onClear?: () => void;
+  onFocus?: (event: React.FocusEvent<HTMLElement>) => void;
+  onBlur?: (event: React.FocusEvent<HTMLElement>) => void;
+
+  // 转换函数
+  getItemValue?: (item: T) => TValue;
+
+  slotProps?: PopoverSlotProps;
+  children?: ReactNode;
+};
+
+/**
+ * PopoverWrapper 组件的 Props
+ */
+export type PopoverWrapperProps<
+  T = unknown,
+  TRaw = unknown,
+  TValue extends ItemValue<TRaw> = ItemValue<TRaw>,
+> = {
+  size?: ComboboxSize;
+  triggerType?: TriggerType;
+  renderTrigger?: (props: TriggerRenderProps<TRaw>) => ReactNode;
+  placeholder?: string;
+  maxTagCount?: number | 'responsive';
+  maxTagTextLength?: number;
+  tagClosable?: boolean;
+  className?: string;
+  classNames?: ClassNamesConfig;
+  placement?: 'top' | 'bottom' | 'left' | 'right';
+  align?: 'start' | 'center' | 'end';
+  sideOffset?: number;
+  showSearch?: boolean;
+  searchPlaceholder?: string;
+  renderItem: (
+    item: T,
+    isSelected: boolean,
+    className?: string,
+    disabled?: boolean,
+  ) => ReactNode;
+  renderTag?: (
+    value: TValue,
+    onClose: (value: TValue, e: React.MouseEvent) => void,
+    disabled?: boolean,
+  ) => ReactNode;
+  getItemValue: (item: T) => TValue;
+  getOptionDisabled?: (value: TValue) => boolean;
+  emptyText?: string;
+  loadingText?: string;
+  onFocus?: (event: React.FocusEvent<HTMLElement>) => void;
+  onBlur?: (event: React.FocusEvent<HTMLElement>) => void;
+  slotProps?: PopoverSlotProps;
+  children?: ReactNode;
+};
+
+/**
+ * 国际化文本类型
+ */
+export type I18nText = {
+  zh_cn: string;
+  en_us?: string;
+  ja_jp?: string;
+};

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

@@ -0,0 +1,81 @@
+'use client';
+
+import { logger } from '@lark-apaas/client-toolkit/logger';
+import { useCallback, useEffect, useState } from 'react';
+
+export type UseFetchDataOptions<T> = {
+  fetchFn: (search: string) => Promise<{ items: T[] }>;
+  enabled: boolean;
+  search: string;
+  onSearch?: (search: string) => void;
+};
+
+export type UseFetchDataResult<T> = {
+  data: T[] | undefined;
+  isFetching: boolean;
+  isError: boolean;
+  isSuccess: boolean;
+  fetchStatus: 'fetching' | 'idle';
+  refetch: () => Promise<void>;
+};
+
+export function useFetchData<T>({
+  fetchFn,
+  enabled,
+  search,
+  onSearch,
+}: UseFetchDataOptions<T>): UseFetchDataResult<T> {
+  const [data, setData] = useState<T[] | undefined>();
+  const [isFetching, setIsFetching] = useState(false);
+  const [isError, setIsError] = useState(false);
+  const [isSuccess, setIsSuccess] = useState(false);
+
+  const fetchData = useCallback(async () => {
+    if (!enabled || search.trim() === '') {
+      setData([]);
+      setIsSuccess(true);
+      return;
+    }
+
+    try {
+      setIsFetching(true);
+      setIsError(false);
+
+      const result = await fetchFn(search);
+
+      setData(result?.items || []);
+      setIsSuccess(true);
+      setIsError(false);
+    } catch (error) {
+      logger.error('Failed to fetch data:', error);
+      setIsError(true);
+      setIsSuccess(false);
+      setData([]);
+    } finally {
+      setIsFetching(false);
+    }
+  }, [enabled, search, fetchFn]);
+
+  useEffect(() => {
+    if (enabled && search.trim() !== '') {
+      fetchData();
+    } else {
+      setData(undefined);
+      setIsSuccess(true);
+    }
+  }, [search, enabled, fetchData]);
+
+  // 单独处理 onSearch 回调
+  useEffect(() => {
+    onSearch?.(search);
+  }, [search, onSearch]);
+
+  return {
+    data,
+    isFetching,
+    isError,
+    isSuccess,
+    fetchStatus: isFetching ? 'fetching' : 'idle',
+    refetch: fetchData,
+  };
+}

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

@@ -0,0 +1,99 @@
+'use client';
+
+import { useCallback, useEffect, useRef } from 'react';
+
+export type UseInfiniteScrollOptions = {
+  /**
+   * 加载更多数据的回调函数
+   */
+  onLoadMore: () => void;
+  /**
+   * 是否还有更多数据
+   */
+  hasMore: boolean;
+  /**
+   * 是否正在加载中
+   */
+  isLoading: boolean;
+  /**
+   * 是否启用无限滚动
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * IntersectionObserver 的 threshold
+   * @default 0.1
+   */
+  threshold?: number;
+  /**
+   * IntersectionObserver 的 rootMargin，用于提前触发加载
+   * @default '50px'
+   */
+  rootMargin?: string;
+};
+
+export type UseInfiniteScrollResult = {
+  /**
+   * 绑定到触发元素的 ref
+   */
+  triggerRef: React.RefObject<HTMLDivElement | null>;
+};
+
+/**
+ * 无限滚动加载 hook
+ * 使用 IntersectionObserver 检测滚动触底，自动触发加载更多
+ *
+ * @example
+ * ```tsx
+ * const { triggerRef } = useInfiniteScroll({
+ *   onLoadMore: fetchMore,
+ *   hasMore,
+ *   isLoading: isFetchingMore,
+ * })
+ *
+ * return (
+ *   <ScrollArea>
+ *     {items.map(item => <Item key={item.id} />)}
+ *     <div ref={triggerRef} />
+ *   </ScrollArea>
+ * )
+ * ```
+ */
+export function useInfiniteScroll({
+  onLoadMore,
+  hasMore,
+  isLoading,
+  enabled = true,
+  threshold = 0.1,
+  rootMargin = '50px',
+}: UseInfiniteScrollOptions): UseInfiniteScrollResult {
+  const triggerRef = useRef<HTMLDivElement>(null);
+
+  const handleIntersect = useCallback(
+    (entries: IntersectionObserverEntry[]) => {
+      const [entry] = entries;
+      if (entry?.isIntersecting && hasMore && !isLoading && enabled) {
+        onLoadMore();
+      }
+    },
+    [hasMore, isLoading, enabled, onLoadMore],
+  );
+
+  useEffect(() => {
+    const element = triggerRef.current;
+    if (!element || !enabled) return;
+
+    const observer = new IntersectionObserver(handleIntersect, {
+      threshold,
+      rootMargin,
+    });
+
+    observer.observe(element);
+
+    return () => {
+      observer.disconnect();
+    };
+  }, [handleIntersect, threshold, rootMargin, enabled]);
+
+  return { triggerRef };
+}

package/template/client/src/components/business-ui/entity-combobox/use-popover-outside-click.tsx

@@ -0,0 +1,32 @@
+import { useEffect } from 'react';
+
+/**
+ * 处理点击外部关闭浮层的 Hook
+ * 仅在 search 模式下使用
+ */
+export function usePopoverOutsideClick(
+  open: boolean,
+  enabled: boolean,
+  popoverRef: React.RefObject<HTMLElement | null>,
+  triggerRef: React.RefObject<HTMLElement | null>,
+  onClose: () => void,
+) {
+  useEffect(() => {
+    if (!open || !enabled) return;
+
+    const handleClickOutside = (event: MouseEvent) => {
+      const target = event.target as Node;
+      if (
+        popoverRef.current &&
+        triggerRef.current &&
+        !popoverRef.current.contains(target) &&
+        !triggerRef.current.contains(target)
+      ) {
+        onClose();
+      }
+    };
+
+    document.addEventListener('mousedown', handleClickOutside);
+    return () => document.removeEventListener('mousedown', handleClickOutside);
+  }, [open, enabled, popoverRef, triggerRef, onClose]);
+}

package/template/client/src/components/business-ui/form/checkbox-field.tsx

@@ -0,0 +1,83 @@
+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';
+import { Checkbox } from '@client/src/components/ui/checkbox';
+import { Field, FieldLabel } from '@client/src/components/ui/field';
+
+type CheckboxFieldProps = CommonFieldProps &
+  React.ComponentProps<typeof Checkbox> & {
+    options?: {
+      label: string;
+      value: boolean | 'indeterminate';
+    }[];
+    classNames?: Partial<FieldLayoutClassNames & Record<'checkbox', string>>;
+    styles?: Partial<
+      FieldLayoutStyles & Record<'checkbox', React.CSSProperties>
+    >;
+  };
+
+export function CheckboxField({
+  label,
+  description,
+  disabled,
+  required,
+  layout,
+  classNames,
+  styles,
+  ...rest
+}: CheckboxFieldProps) {
+  const field = useFieldContext<boolean | 'indeterminate'>();
+  const { layout: formLayout } = useFormGlobalProps();
+  const { isInvalid, errorMessage } = useFieldValidation();
+  const name = useFieldName();
+
+  const { checkbox: checkboxClassName, ...fieldLayoutClassNames } =
+    classNames ?? {};
+  const { checkbox: checkboxStyle, ...fieldLayoutStyles } = styles ?? {};
+
+  return (
+    <FieldLayout
+      description={description}
+      isInvalid={isInvalid}
+      layout={layout ?? formLayout ?? 'vertical'}
+      required={required ?? false}
+      classNames={fieldLayoutClassNames ?? {}}
+      styles={fieldLayoutStyles ?? {}}
+      errorMessage={errorMessage}
+      name={name}
+    >
+      <Field orientation="horizontal">
+        <Checkbox
+          {...rest}
+          id={name}
+          name={name}
+          className={checkboxClassName ?? ''}
+          style={checkboxStyle ?? {}}
+          required={required ?? false}
+          aria-invalid={isInvalid}
+          checked={field.state.value}
+          disabled={disabled}
+          onCheckedChange={(checked) => {
+            field.handleChange(checked);
+          }}
+        />
+        <FieldLabel
+          style={styles?.label}
+          className={classNames?.['label']}
+          htmlFor={name}
+        >
+          {label}
+        </FieldLabel>
+      </Field>
+    </FieldLayout>
+  );
+}

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

@@ -0,0 +1,38 @@
+'use client';
+
+import React from 'react';
+
+export interface FormGlobalProps {
+  layout: 'vertical' | 'responsive' | 'horizontal';
+}
+
+export type FormContextType = FormGlobalProps | null;
+
+export const FormContext = React.createContext<FormContextType>(null);
+
+export const useFormContext = () => {
+  const context = React.useContext(FormContext);
+  if (!context) {
+    throw new Error('useFormContext must be used within a FormProvider');
+  }
+  return context as FormGlobalProps;
+};
+
+export const FormProvider: React.FC<{
+  layout: 'vertical' | 'responsive' | 'horizontal';
+  children: React.ReactNode;
+}> = ({ layout, children }) => {
+  const value = React.useMemo(
+    () => ({
+      layout: layout,
+    }),
+    [layout],
+  );
+
+  return <FormContext.Provider value={value}>{children}</FormContext.Provider>;
+};
+
+export const useFormGlobalProps = () => {
+  const context = useFormContext();
+  return context;
+};

package/template/client/src/components/business-ui/form/field-layout.tsx

@@ -0,0 +1,91 @@
+import { Asterisk } from 'lucide-react';
+
+import type { FieldLayoutProps } from '@client/src/components/business-ui/form/types';
+import { cn } from '@/lib/utils';
+import {
+  Field,
+  FieldContent,
+  FieldDescription,
+  FieldError,
+  FieldLabel,
+} from '@client/src/components/ui/field';
+
+export function FieldLayout({
+  label,
+  children,
+  description,
+  layout = 'vertical',
+  isInvalid,
+  errorMessage,
+  name,
+  required,
+  classNames,
+  styles,
+}: React.PropsWithChildren<FieldLayoutProps>) {
+  const descriptionComponent = description && (
+    <FieldDescription
+      className={classNames?.['description']}
+      style={styles?.['description']}
+    >
+      {description}
+    </FieldDescription>
+  );
+
+  const labelComponent = label && (
+    <FieldLabel
+      className={cn('gap-0.5', classNames?.['label'])}
+      htmlFor={name}
+      style={styles?.['label']}
+    >
+      {label}
+      {required && (
+        <span className="text-red-500">
+          <Asterisk size={12} />
+        </span>
+      )}
+    </FieldLabel>
+  );
+
+  const errorComponent = isInvalid && (
+    <FieldError className={classNames?.['error']} style={styles?.['error']}>
+      {errorMessage}
+    </FieldError>
+  );
+
+  if (layout !== 'vertical') {
+    return (
+      <Field
+        orientation={layout}
+        className={cn(classNames?.['root'])}
+        style={styles?.['root']}
+      >
+        {descriptionComponent ? (
+          <FieldContent>
+            {labelComponent}
+            {descriptionComponent}
+          </FieldContent>
+        ) : (
+          labelComponent
+        )}
+        <FieldContent className={'has-[>[role=switch]]:flex-initial'}>
+          {children}
+          {errorComponent}
+        </FieldContent>
+      </Field>
+    );
+  }
+  return (
+    <Field
+      orientation={layout}
+      className={classNames?.['root']}
+      style={styles?.['root']}
+    >
+      {labelComponent}
+      <FieldContent className={'has-[>[role=switch]]:flex-initial'}>
+        {children}
+        {errorComponent}
+      </FieldContent>
+      {descriptionComponent}
+    </Field>
+  );
+}