@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/cascader/cascader.tsx

@@ -1,5 +1,12 @@
 import * as React from 'react';
-import { ChevronDown, ChevronRight } from 'lucide-react';
+import {
+  Check,
+  ChevronDown,
+  ChevronRight,
+  Loader2,
+  Search,
+  X,
+} from 'lucide-react';
 
 import { cn } from '@/utils/cn';
 import { Button } from '@/components/button/button';
@@ -9,6 +16,8 @@ import {
   PopoverTrigger,
 } from '@/components/popover/popover';
 
+// ─── Types ─────────────────────────────────────────────────────────────────
+
 export interface CascaderOption {
   /** 级联节点 value(同级 value 必须唯一)。 */
   value: string;
@@ -18,45 +27,70 @@ export interface CascaderOption {
   children?: CascaderOption[];
   /** 禁用此项。 */
   disabled?: boolean;
+  /**
+   * 显式标记为叶子节点(用于 loadData 模式:当 children 为空但 isLeaf=false 时,
+   * 点击该节点触发异步加载;若 isLeaf=true 则直接当叶子处理)。
+   * @default 自动推断(无 children 即为叶子)
+   */
+  isLeaf?: boolean;
 }
 
-export interface CascaderProps {
+interface CascaderBaseProps {
   /** 级联选项树(antd `options` 并集)。 */
   options: CascaderOption[];
-  /** 受控值(每层 value 数组)。 */
-  value?: string[];
-  /** uncontrolled 初值。 */
-  defaultValue?: string[];
-  /** 值变化回调 — 触发条件:点选叶子节点或显式 changeOnSelect。 */
-  onChange?: (value: string[], selectedOptions: CascaderOption[]) => void;
   /**
    * 每选中一级即触发 onChange(antd `changeOnSelect` 并集) — 默认仅选叶子触发。
    * @default false
    */
   changeOnSelect?: boolean;
-  /**
-   * 占位文本。
-   * @default "请选择"
-   */
+  /** 占位文本。 @default "请选择" */
   placeholder?: string;
-  /**
-   * 路径展示的分隔符。
-   * @default " / "
-   */
+  /** 路径展示的分隔符。 @default " / " */
   separator?: string;
   /** 整体禁用。 */
   disabled?: boolean;
+  /** 触发器 className。 */
+  className?: string;
+  /** 触发器尺寸。 @default "md" */
+  size?: 'sm' | 'md' | 'default' | 'lg';
   /**
-   * 触发器 className(给外层 Button)。
+   * 启用搜索(面板顶部输入框,过滤匹配路径)。
+   * @default false
    */
-  className?: string;
+  showSearch?: boolean;
   /**
-   * 触发器尺寸。
-   * @default "default"
+   * 异步加载子节点 — 当点击非叶子且无 children 时触发。
+   * 消费者在回调内 fetch 数据后更新 `options` prop。
    */
-  size?: 'sm' | 'default' | 'lg';
+  loadData?: (selectedOptions: CascaderOption[]) => void;
 }
 
+export interface CascaderSingleProps extends CascaderBaseProps {
+  /** 单选模式(默认)。 */
+  multiple?: false | undefined;
+  /** 受控值(路径 value 数组)。 */
+  value?: string[];
+  /** 非受控初值。 */
+  defaultValue?: string[];
+  /** 值变化回调。 */
+  onChange?: (value: string[], selectedOptions: CascaderOption[]) => void;
+}
+
+export interface CascaderMultipleProps extends CascaderBaseProps {
+  /** 多选模式。 */
+  multiple: true;
+  /** 受控值(多条路径,每条为 value 数组)。 */
+  value?: string[][];
+  /** 非受控初值。 */
+  defaultValue?: string[][];
+  /** 值变化回调。 */
+  onChange?: (value: string[][], selectedOptions: CascaderOption[][]) => void;
+}
+
+export type CascaderProps = CascaderSingleProps | CascaderMultipleProps;
+
+// ─── Helpers ───────────────────────────────────────────────────────────────
+
 function findPath(
   options: CascaderOption[],
   value: string[],
@@ -64,7 +98,9 @@ function findPath(
   const path: CascaderOption[] = [];
   let cursor: CascaderOption[] | undefined = options;
   for (const v of value) {
-    const found: CascaderOption | undefined = cursor?.find((o) => o.value === v);
+    const found: CascaderOption | undefined = cursor?.find(
+      (o) => o.value === v,
+    );
     if (!found) break;
     path.push(found);
     cursor = found.children;
@@ -72,68 +108,284 @@ function findPath(
   return path;
 }
 
+function isNodeLeaf(opt: CascaderOption): boolean {
+  if (opt.isLeaf !== undefined) return opt.isLeaf;
+  return !opt.children || opt.children.length === 0;
+}
+
+/** 用于 multiple 去重的 path → key。 */
+const pathKey = (p: string[]): string => p.join('\0');
+
+/** 将 options 树展开为 [path, labels] 列表(用于搜索)。 */
+function flattenOptions(
+  options: CascaderOption[],
+  parentPath: CascaderOption[] = [],
+): { path: CascaderOption[]; values: string[] }[] {
+  const results: { path: CascaderOption[]; values: string[] }[] = [];
+  for (const opt of options) {
+    const currentPath = [...parentPath, opt];
+    const values = currentPath.map((o) => o.value);
+    if (opt.children && opt.children.length > 0) {
+      // 有子级则递归
+      results.push(...flattenOptions(opt.children, currentPath));
+    } else {
+      // 叶子节点加入结果
+      results.push({ path: currentPath, values });
+    }
+  }
+  return results;
+}
+
+function getLabel(node: React.ReactNode): string {
+  if (typeof node === 'string') return node;
+  if (typeof node === 'number') return String(node);
+  return '';
+}
+
+// ─── Component ─────────────────────────────────────────────────────────────
+
 /**
- * 级联选择 — antd 独有补足。**等价 antd `Cascader`**。多级联动选择(地区 / 分类 / 组织架构),
- * 选项树由 `options.children` 表达;点击触发器弹出多列面板,**叶子触发 onChange**(可改 `changeOnSelect` 为每级触发)。
+ * 级联选择 — antd 独有补足。多级联动选择(地区 / 分类 / 组织架构),
+ * 支持单选 / 多选(checkbox) / 搜索过滤 / 异步加载(loadData)。
  */
 const Cascader = React.forwardRef<HTMLButtonElement, CascaderProps>(
-  (
-    {
+  (props, ref) => {
+    const {
       options,
-      value,
-      defaultValue,
-      onChange,
       changeOnSelect = false,
       placeholder = '请选择',
       separator = ' / ',
       disabled = false,
       className,
-      size = 'default',
-    },
-    ref,
-  ) => {
-    const isControlled = value !== undefined;
-    const [internal, setInternal] = React.useState<string[]>(defaultValue ?? []);
-    const current = isControlled ? value! : internal;
+      size = 'md',
+      showSearch = false,
+      loadData,
+      multiple = false,
+    } = props;
+
+    // ─── Single mode state ───────────────────────────────
+    const singleValue = !multiple
+      ? (props as CascaderSingleProps).value
+      : undefined;
+    const singleDefault = !multiple
+      ? (props as CascaderSingleProps).defaultValue
+      : undefined;
+    const singleOnChange = !multiple
+      ? (props as CascaderSingleProps).onChange
+      : undefined;
+
+    const isSingleControlled = !multiple && singleValue !== undefined;
+    const [singleInternal, setSingleInternal] = React.useState<string[]>(
+      singleDefault ?? [],
+    );
+    const currentSingle = isSingleControlled ? singleValue! : singleInternal;
 
+    // ─── Multiple mode state ─────────────────────────────
+    const multiValue = multiple
+      ? (props as CascaderMultipleProps).value
+      : undefined;
+    const multiDefault = multiple
+      ? (props as CascaderMultipleProps).defaultValue
+      : undefined;
+    const multiOnChange = multiple
+      ? (props as CascaderMultipleProps).onChange
+      : undefined;
+
+    const isMultiControlled = multiple && multiValue !== undefined;
+    const [multiInternal, setMultiInternal] = React.useState<string[][]>(
+      multiDefault ?? [],
+    );
+    const currentMulti = isMultiControlled ? multiValue! : multiInternal;
+
+    // ─── Shared state ────────────────────────────────────
     const [open, setOpen] = React.useState(false);
-    const [activePath, setActivePath] = React.useState<string[]>(current);
+    const [activePath, setActivePath] = React.useState<string[]>(
+      multiple ? [] : currentSingle,
+    );
+    const [searchText, setSearchText] = React.useState('');
+    const [loadingKeys, setLoadingKeys] = React.useState<Set<string>>(
+      new Set(),
+    );
+
+    React.useEffect(() => {
+      if (open) {
+        setActivePath(multiple ? [] : currentSingle);
+        setSearchText('');
+      }
+    }, [open]);
 
+    // ─── loadData 响应:当 options 更新时清除对应 loading ──
     React.useEffect(() => {
-      if (open) setActivePath(current);
-    }, [open, current]);
+      if (loadingKeys.size === 0) return;
+      setLoadingKeys((prev) => {
+        const next = new Set(prev);
+        for (const key of prev) {
+          const parts = key.split('\0');
+          const path = findPath(options, parts);
+          const last = path[path.length - 1];
+          if (last?.children && last.children.length > 0) {
+            next.delete(key);
+          }
+        }
+        return next.size === prev.size ? prev : next;
+      });
+    }, [options, loadingKeys]);
 
-    const selectedPath = findPath(options, current);
+    // ─── Handlers ────────────────────────────────────────
 
     const handleSelect = (level: number, opt: CascaderOption) => {
       if (opt.disabled) return;
       const next = [...activePath.slice(0, level), opt.value];
       setActivePath(next);
-      const hasChildren = !!opt.children && opt.children.length > 0;
-      if (!hasChildren || changeOnSelect) {
+
+      const leaf = isNodeLeaf(opt);
+
+      // loadData: 非叶子且无子级时触发异步加载
+      if (!leaf && (!opt.children || opt.children.length === 0) && loadData) {
         const path = findPath(options, next);
-        if (!isControlled) setInternal(next);
-        onChange?.(next, path);
-        if (!hasChildren) setOpen(false);
+        const key = pathKey(next);
+        setLoadingKeys((prev) => new Set(prev).add(key));
+        loadData(path);
+        return;
       }
+
+      if (!leaf && !changeOnSelect) return;
+
+      if (multiple) {
+        // multiple: toggle selection
+        const existing = currentMulti.findIndex(
+          (p) => pathKey(p) === pathKey(next),
+        );
+        let nextMulti: string[][];
+        if (existing >= 0) {
+          nextMulti = currentMulti.filter((_, i) => i !== existing);
+        } else {
+          nextMulti = [...currentMulti, next];
+        }
+        if (!isMultiControlled) setMultiInternal(nextMulti);
+        const paths = nextMulti.map((v) => findPath(options, v));
+        multiOnChange?.(nextMulti, paths);
+        // 不自动关闭
+      } else {
+        // single
+        const path = findPath(options, next);
+        if (!isSingleControlled) setSingleInternal(next);
+        singleOnChange?.(next, path);
+        if (leaf) setOpen(false);
+      }
+    };
+
+    const handleSearchSelect = (values: string[]) => {
+      if (multiple) {
+        const existing = currentMulti.findIndex(
+          (p) => pathKey(p) === pathKey(values),
+        );
+        let nextMulti: string[][];
+        if (existing >= 0) {
+          nextMulti = currentMulti.filter((_, i) => i !== existing);
+        } else {
+          nextMulti = [...currentMulti, values];
+        }
+        if (!isMultiControlled) setMultiInternal(nextMulti);
+        const paths = nextMulti.map((v) => findPath(options, v));
+        multiOnChange?.(nextMulti, paths);
+      } else {
+        const path = findPath(options, values);
+        if (!isSingleControlled) setSingleInternal(values);
+        singleOnChange?.(values, path);
+        setOpen(false);
+      }
+    };
+
+    const handleRemoveTag = (idx: number) => {
+      const nextMulti = currentMulti.filter((_, i) => i !== idx);
+      if (!isMultiControlled) setMultiInternal(nextMulti);
+      const paths = nextMulti.map((v) => findPath(options, v));
+      multiOnChange?.(nextMulti, paths);
     };
 
-    // Render columns based on activePath
+    // ─── Columns ─────────────────────────────────────────
     const columns: CascaderOption[][] = [options];
     let cursor: CascaderOption[] | undefined = options;
     for (const v of activePath) {
-      const found: CascaderOption | undefined = cursor?.find((o) => o.value === v);
+      const found: CascaderOption | undefined = cursor?.find(
+        (o) => o.value === v,
+      );
       if (found?.children && found.children.length > 0) {
         columns.push(found.children);
         cursor = found.children;
       } else break;
     }
 
-    const display =
-      selectedPath.length > 0
-        ? selectedPath.map((o) => o.label).join(separator)
-        : '';
+    // ─── Search results ──────────────────────────────────
+    const searchResults = React.useMemo(() => {
+      if (!showSearch || !searchText.trim()) return [];
+      const term = searchText.trim().toLowerCase();
+      const all = flattenOptions(options);
+      return all.filter((item) =>
+        item.path.some((opt) =>
+          getLabel(opt.label).toLowerCase().includes(term),
+        ),
+      );
+    }, [showSearch, searchText, options]);
+
+    // ─── Display ─────────────────────────────────────────
+    let triggerContent: React.ReactNode;
+    if (multiple) {
+      if (currentMulti.length === 0) {
+        triggerContent = (
+          <span className="text-muted-foreground">{placeholder}</span>
+        );
+      } else {
+        triggerContent = (
+          <span className="flex flex-wrap items-center gap-1 overflow-hidden">
+            {currentMulti.slice(0, 3).map((path, i) => {
+              const opts = findPath(options, path);
+              const label = opts.map((o) => getLabel(o.label)).join(separator);
+              return (
+                <span
+                  key={pathKey(path)}
+                  className="inline-flex max-w-32 items-center gap-0.5 truncate rounded bg-muted px-1.5 py-0.5 text-xs"
+                >
+                  <span className="truncate">{label}</span>
+                  <X
+                    className="size-3 shrink-0 cursor-pointer opacity-60 hover:opacity-100"
+                    onClick={(e) => {
+                      e.stopPropagation();
+                      handleRemoveTag(i);
+                    }}
+                  />
+                </span>
+              );
+            })}
+            {currentMulti.length > 3 && (
+              <span className="text-xs text-muted-foreground">
+                +{currentMulti.length - 3}
+              </span>
+            )}
+          </span>
+        );
+      }
+    } else {
+      const selectedPath = findPath(options, currentSingle);
+      const display =
+        selectedPath.length > 0
+          ? selectedPath.map((o) => o.label).join(separator)
+          : '';
+      triggerContent = (
+        <span className={cn('truncate', !display && 'text-muted-foreground')}>
+          {display || placeholder}
+        </span>
+      );
+    }
+
+    // ─── selectedSet (multiple) ──────────────────────────
+    const selectedSet = React.useMemo(
+      () => new Set(currentMulti.map(pathKey)),
+      [currentMulti],
+    );
 
+    // ─── Render ──────────────────────────────────────────
     return (
       <Popover open={open} onOpenChange={setOpen}>
         <PopoverTrigger asChild>
@@ -144,50 +396,141 @@ const Cascader = React.forwardRef<HTMLButtonElement, CascaderProps>(
             size={size}
             disabled={disabled}
             className={cn(
-              'min-w-[200px] justify-between font-normal',
-              !display && 'text-muted-foreground',
+              'min-w-panel-sm justify-between font-normal',
               className,
             )}
           >
-            <span className="truncate">{display || placeholder}</span>
+            {triggerContent}
             <ChevronDown className="ml-2 size-4 shrink-0 opacity-50" />
           </Button>
         </PopoverTrigger>
-        <PopoverContent className="flex w-auto p-0" align="start">
-          {columns.map((col, level) => (
+        <PopoverContent className="w-auto p-0" align="start">
+          {/* Search input */}
+          {showSearch && (
+            <div className="flex items-center gap-2 border-b border-border px-3 py-2">
+              <Search className="size-4 text-muted-foreground" />
+              <input
+                type="text"
+                value={searchText}
+                onChange={(e) => setSearchText(e.target.value)}
+                placeholder="搜索..."
+                className="flex-1 bg-transparent text-xs outline-none placeholder:text-muted-foreground"
+                autoFocus
+              />
+            </div>
+          )}
+
+          {/* Search results */}
+          {showSearch && searchText.trim() ? (
             <ul
-              key={level}
               role="listbox"
-              className={cn(
-                'min-w-[160px] max-h-72 overflow-auto py-1 text-sm',
-                level > 0 && 'border-l',
-              )}
+              className="max-h-72 min-w-48 overflow-auto p-1 text-xs"
             >
-              {col.map((opt) => {
-                const isActive = activePath[level] === opt.value;
-                const hasChildren = !!opt.children && opt.children.length > 0;
-                return (
-                  <li
-                    key={opt.value}
-                    role="option"
-                    aria-selected={isActive}
-                    onClick={() => handleSelect(level, opt)}
-                    className={cn(
-                      'flex cursor-pointer items-center justify-between gap-2 px-3 py-1.5',
-                      !opt.disabled && 'hover:bg-accent',
-                      isActive && !opt.disabled && 'bg-accent text-accent-foreground',
-                      opt.disabled && 'cursor-not-allowed opacity-50',
-                    )}
-                  >
-                    <span className="truncate">{opt.label}</span>
-                    {hasChildren ? (
-                      <ChevronRight className="size-3.5 shrink-0 opacity-60" />
-                    ) : null}
-                  </li>
-                );
-              })}
+              {searchResults.length === 0 ? (
+                <li className="px-2 py-4 text-center text-muted-foreground">
+                  无匹配结果
+                </li>
+              ) : (
+                searchResults.map((item) => {
+                  const key = pathKey(item.values);
+                  const isSelected = multiple
+                    ? selectedSet.has(key)
+                    : pathKey(currentSingle) === key;
+                  return (
+                    <li
+                      key={key}
+                      role="option"
+                      aria-selected={isSelected}
+                      onClick={() => handleSearchSelect(item.values)}
+                      className={cn(
+                        'flex cursor-pointer items-center gap-2 rounded-sm px-2 py-1.5 transition-colors hover:bg-accent/50',
+                        isSelected &&
+                          'bg-accent font-medium text-accent-foreground',
+                      )}
+                    >
+                      {multiple && (
+                        <span
+                          className={cn(
+                            'flex size-4 shrink-0 items-center justify-center rounded border border-primary',
+                            isSelected && 'bg-primary text-primary-foreground',
+                          )}
+                        >
+                          {isSelected && <Check className="size-3" />}
+                        </span>
+                      )}
+                      <span className="truncate">
+                        {item.path
+                          .map((o) => getLabel(o.label))
+                          .join(separator)}
+                      </span>
+                    </li>
+                  );
+                })
+              )}
             </ul>
-          ))}
+          ) : (
+            /* Column panels */
+            <div className="flex">
+              {columns.map((col, level) => (
+                <ul
+                  key={level}
+                  role="listbox"
+                  className={cn(
+                    'min-w-submenu max-h-72 overflow-auto p-1 text-xs',
+                    level > 0 && 'border-l border-l-border',
+                  )}
+                >
+                  {col.map((opt) => {
+                    const isActive = activePath[level] === opt.value;
+                    const leaf = isNodeLeaf(opt);
+                    const hasChildren = !leaf;
+                    const nodeKey = pathKey([
+                      ...activePath.slice(0, level),
+                      opt.value,
+                    ]);
+                    const isLoading = loadingKeys.has(nodeKey);
+                    const isChecked = multiple && selectedSet.has(nodeKey);
+                    return (
+                      <li
+                        key={opt.value}
+                        role="option"
+                        aria-selected={isActive}
+                        onClick={() => handleSelect(level, opt)}
+                        className={cn(
+                          'flex cursor-pointer items-center justify-between gap-2 rounded-sm px-2 py-1.5 transition-colors',
+                          !opt.disabled && 'hover:bg-accent/50',
+                          isActive &&
+                            !opt.disabled &&
+                            'bg-accent font-medium text-accent-foreground',
+                          opt.disabled && 'cursor-not-allowed opacity-50',
+                        )}
+                      >
+                        <span className="flex items-center gap-1.5 truncate">
+                          {multiple && leaf && (
+                            <span
+                              className={cn(
+                                'flex size-4 shrink-0 items-center justify-center rounded border border-primary',
+                                isChecked &&
+                                  'bg-primary text-primary-foreground',
+                              )}
+                            >
+                              {isChecked && <Check className="size-3" />}
+                            </span>
+                          )}
+                          <span className="truncate">{opt.label}</span>
+                        </span>
+                        {isLoading ? (
+                          <Loader2 className="size-3.5 shrink-0 animate-spin text-muted-foreground" />
+                        ) : hasChildren ? (
+                          <ChevronRight className="size-3.5 shrink-0 text-muted-foreground" />
+                        ) : null}
+                      </li>
+                    );
+                  })}
+                </ul>
+              ))}
+            </div>
+          )}
         </PopoverContent>
       </Popover>
     );