@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/combobox/index.tsx

@@ -0,0 +1,687 @@
+/**
+ * 组合选择器 Combobox
+ *
+ * 可搜索的下拉选择器，支持单选与多选。多选模式下触发区以可关闭的 Tag 组展示
+ * 选中项，超出 `maxTagCount` 自动折叠为 `+N` 摘要。
+ *
+ * @when
+ * - 选项数量较多需要边输入边过滤时
+ * - 需要多选并以可关闭标签形式展示已选时
+ * - Select 无法满足搜索 / 多选 / 远程数据等场景时
+ *
+ * 触发区内置 search input，输入即过滤选项；多选模式下已选 Tag 与 input 共占触发区。
+ *
+ * 组合结构：Combobox > ComboboxTrigger ( ComboboxValue ) + ComboboxContent > ComboboxList > ( ComboboxEmpty | ComboboxGroup > ComboboxItem | ComboboxSeparator )
+ */
+
+'use client';
+
+import * as React from 'react';
+import { Popover as PopoverPrimitive } from 'radix-ui';
+import { Command as CommandPrimitive } from 'cmdk';
+import { CheckIcon, ChevronDownIcon, XIcon } from 'lucide-react';
+
+import { cn } from '@/lib/utils';
+import { PopoverContent } from '@/components/popover';
+import {
+  CommandEmpty,
+  CommandGroup,
+  CommandList,
+  CommandSeparator,
+} from '@/components/command';
+import { Tag } from '@/components/tag';
+
+// ─── Context ────────────────────────────────────────────────────────────
+
+type ComboboxValueState = string | string[] | undefined;
+
+interface ComboboxContextValue {
+  /** 多选开关。 */
+  multiple: boolean;
+  /** 当前值；单选 string、多选 string[]。 */
+  value: ComboboxValueState;
+  /** 切换某项选中状态。 */
+  toggleValue: (next: string) => void;
+  /** 清空所有选中。 */
+  clearValue: () => void;
+  /** value → label 映射（从 children 静态提取），供 Tag 显示。 */
+  itemLabels: Map<string, React.ReactNode>;
+  /** 触发区内联 search 文本（受控）。 */
+  search: string;
+  /** 设置触发区 search 文本。 */
+  setSearch: (search: string) => void;
+  /** 多选 Tag 显示上限，超出折叠为 +N。 */
+  maxTagCount?: number;
+  /** 禁用状态。 */
+  disabled: boolean;
+  /** 当前面板是否打开。 */
+  open: boolean;
+  /** 打开 / 关闭面板。 */
+  setOpen: (open: boolean) => void;
+  /** 触发区容器 ref，供 Content 判定 outside 点击。 */
+  triggerRef: React.RefObject<HTMLDivElement | null>;
+}
+
+const ComboboxContext = React.createContext<ComboboxContextValue | null>(null);
+
+function useComboboxContext(slot: string): ComboboxContextValue {
+  const ctx = React.useContext(ComboboxContext);
+  if (!ctx) {
+    throw new Error(`<${slot}> 必须置于 <Combobox> 内部使用。`);
+  }
+  return ctx;
+}
+
+// ─── Root ───────────────────────────────────────────────────────────────
+
+interface ComboboxSingleProps {
+  /** 单选模式：`multiple` 缺省或为 `false`。 */
+  multiple?: false;
+  /** 受控选中项 value。 */
+  value?: string;
+  /** 非受控初始选中项 value。 */
+  defaultValue?: string;
+  /**
+   * 选中项变化回调。
+   * @param value 当前选中项 value，未选时为空字符串
+   */
+  onValueChange?: (value: string) => void;
+}
+
+interface ComboboxMultipleProps {
+  /** 多选模式。 */
+  multiple: true;
+  /** 受控选中项 value 数组。 */
+  value?: string[];
+  /** 非受控初始选中项 value 数组。 */
+  defaultValue?: string[];
+  /**
+   * 选中项变化回调。
+   * @param value 当前选中项 value 数组
+   */
+  onValueChange?: (value: string[]) => void;
+}
+
+interface ComboboxBaseProps {
+  /** 受控面板是否打开。 */
+  open?: boolean;
+  /** 非受控初始面板是否打开。 @default false */
+  defaultOpen?: boolean;
+  /**
+   * 面板状态变化回调。
+   * @param open 当前是否打开
+   */
+  onOpenChange?: (open: boolean) => void;
+  /** 禁用整个组件，触发器无法打开面板。 @default false */
+  disabled?: boolean;
+  /**
+   * 多选模式下触发区 Tag 显示数量上限，超出自动折叠为不可关闭的 `+N` 摘要 Tag。
+   * 仅 `multiple=true` 时生效。
+   */
+  maxTagCount?: number;
+  /** 是否启用 cmdk 内置过滤逻辑；关闭后由外部接管搜索结果。 @default true */
+  shouldFilter?: boolean;
+  /** 自定义匹配评分函数：返回 0 表示不匹配，>0 越大越靠前。 */
+  filter?: (value: string, search: string, keywords?: string[]) => number;
+  /** 到达列表末尾时是否循环回到起点。 @default false */
+  loop?: boolean;
+  /** 命令面板的可访问性标签。 */
+  label?: string;
+  /** 触发区 search 文本变化回调。 */
+  onSearchChange?: (search: string) => void;
+  /** 子节点（ComboboxTrigger / ComboboxContent）。 */
+  children?: React.ReactNode;
+}
+
+export type ComboboxProps = ComboboxBaseProps &
+  (ComboboxSingleProps | ComboboxMultipleProps);
+
+function Combobox(props: ComboboxProps) {
+  const {
+    multiple = false,
+    open: openProp,
+    defaultOpen,
+    onOpenChange,
+    disabled = false,
+    maxTagCount,
+    shouldFilter = true,
+    filter,
+    loop,
+    label,
+    onSearchChange,
+    children,
+  } = props;
+
+  // value 受控 / 非受控（兼容单选 string 与多选 string[]）
+  const isValueControlled = (props as { value?: unknown }).value !== undefined;
+  const [internalValue, setInternalValue] = React.useState<ComboboxValueState>(
+    () => {
+      if (multiple) {
+        return (props as ComboboxMultipleProps).defaultValue ?? [];
+      }
+      return (props as ComboboxSingleProps).defaultValue ?? '';
+    },
+  );
+  const value: ComboboxValueState = isValueControlled
+    ? ((props as { value?: ComboboxValueState }).value as ComboboxValueState)
+    : internalValue;
+
+  const emit = React.useCallback(
+    (next: ComboboxValueState) => {
+      if (!isValueControlled) setInternalValue(next);
+      if (multiple) {
+        (props as ComboboxMultipleProps).onValueChange?.(
+          (next as string[]) ?? [],
+        );
+      } else {
+        (props as ComboboxSingleProps).onValueChange?.((next as string) ?? '');
+      }
+    },
+    [isValueControlled, multiple, props],
+  );
+
+  // open 受控 / 非受控
+  const isOpenControlled = openProp !== undefined;
+  const [internalOpen, setInternalOpen] = React.useState(defaultOpen ?? false);
+  const open = isOpenControlled ? !!openProp : internalOpen;
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (!isOpenControlled) setInternalOpen(next);
+      onOpenChange?.(next);
+    },
+    [isOpenControlled, onOpenChange],
+  );
+
+  // value → label 映射：静态从 children 树中递归提取 ComboboxItem 的 props.value 与 children，
+  // 不依赖运行时 mount，触发区在面板未打开时也能拿到 label 用于 Tag 渲染。
+  const itemLabels = React.useMemo(() => {
+    const map = new Map<string, React.ReactNode>();
+    collectComboboxLabels(children, map);
+    return map;
+  }, [children]);
+
+  // 触发区 search 状态（受控），驱动 cmdk 过滤
+  const [searchState, setSearchState] = React.useState('');
+  const setSearch = React.useCallback(
+    (next: string) => {
+      setSearchState(next);
+      onSearchChange?.(next);
+    },
+    [onSearchChange],
+  );
+
+  const toggleValue = React.useCallback(
+    (next: string) => {
+      if (multiple) {
+        const arr = Array.isArray(value) ? value : [];
+        const has = arr.includes(next);
+        emit(has ? arr.filter((v) => v !== next) : [...arr, next]);
+        // 多选保持面板打开（与 antd 一致），但清空搜索词以便继续选其它项
+        setSearchState('');
+      } else {
+        emit(next);
+        setOpen(false);
+        setSearchState('');
+      }
+    },
+    [multiple, value, emit, setOpen],
+  );
+
+  const clearValue = React.useCallback(() => {
+    emit(multiple ? [] : '');
+  }, [emit, multiple]);
+
+  // 触发区容器 ref：供 Content 判定 outside 点击是否落在 Trigger 上
+  const triggerRef = React.useRef<HTMLDivElement>(null);
+
+  const ctxValue = React.useMemo<ComboboxContextValue>(
+    () => ({
+      multiple,
+      value,
+      toggleValue,
+      clearValue,
+      itemLabels,
+      maxTagCount,
+      disabled,
+      open,
+      setOpen,
+      search: searchState,
+      setSearch,
+      triggerRef,
+    }),
+    [
+      multiple,
+      value,
+      toggleValue,
+      clearValue,
+      itemLabels,
+      maxTagCount,
+      disabled,
+      open,
+      setOpen,
+      searchState,
+      setSearch,
+    ],
+  );
+
+  return (
+    <ComboboxContext.Provider value={ctxValue}>
+      <CommandPrimitive
+        data-slot="combobox-root"
+        // display:contents 让 cmdk 容器 div 在视觉上"透明"，
+        // Trigger 与 Content 直接成为父节点的布局子项
+        className="contents"
+        shouldFilter={shouldFilter}
+        filter={filter}
+        loop={loop}
+        label={label}
+      >
+        <PopoverPrimitive.Root open={open} onOpenChange={setOpen} modal={false}>
+          {children}
+        </PopoverPrimitive.Root>
+      </CommandPrimitive>
+    </ComboboxContext.Provider>
+  );
+}
+
+// ─── Trigger ────────────────────────────────────────────────────────────
+
+export interface ComboboxTriggerProps
+  extends Omit<React.ComponentProps<'div'>, 'onChange'> {
+  /** 触发器尺寸，对齐 SelectTrigger 三档：sm 28px / default 32px / lg 36px。 */
+  size?: 'sm' | 'default' | 'lg';
+  /**
+   * 清除回调：传入后右侧 chevron 切换为 × 按钮，点击调用此回调清空选中。
+   * 受控模式下由调用方传入 `() => setValue([])`；不传则不展示清除按钮。
+   */
+  onClear?: () => void;
+}
+
+function ComboboxTrigger({
+  className,
+  size = 'default',
+  onClear,
+  children,
+  ...props
+}: ComboboxTriggerProps) {
+  const ctx = useComboboxContext('ComboboxTrigger');
+  const inputRef = React.useRef<HTMLInputElement>(null);
+
+  const hasValue = ctx.multiple
+    ? Array.isArray(ctx.value) && ctx.value.length > 0
+    : !!ctx.value;
+  const showClear = !ctx.disabled && hasValue && typeof onClear === 'function';
+
+  // 提取 ComboboxValue 的 placeholder 注入到内联 search input
+  const placeholder = React.useMemo(() => {
+    let p = '';
+    React.Children.forEach(children, (child) => {
+      if (
+        React.isValidElement(child) &&
+        (child.type as unknown) === ComboboxValue
+      ) {
+        const ph = (
+          child as React.ReactElement<{ placeholder?: React.ReactNode }>
+        ).props.placeholder;
+        if (typeof ph === 'string') p = ph;
+      }
+    });
+    return p;
+  }, [children]);
+
+  // 多选已有 Tag 时不再显示 placeholder（避免与 Tag 重叠）
+  const inputPlaceholder = ctx.multiple && hasValue ? '' : placeholder;
+
+  return (
+    <PopoverPrimitive.Anchor asChild>
+      <div
+        ref={ctx.triggerRef as React.Ref<HTMLDivElement>}
+        data-slot="combobox-trigger"
+        data-size={size}
+        data-state={ctx.open ? 'open' : 'closed'}
+        data-disabled={ctx.disabled || undefined}
+        onMouseDown={(e) => {
+          // 点击触发区空白处时阻止默认以避免 input 失焦闪烁
+          if (e.target !== inputRef.current) e.preventDefault();
+        }}
+        onClick={() => {
+          if (ctx.disabled) return;
+          // 面板开启由 input.onFocus 统一接管；这里只负责将焦点转给 input，
+          // 避免重复调用 setOpen 导致 onOpenChange / Popover 重复触发
+          inputRef.current?.focus();
+        }}
+        className={cn(
+          // 视觉与 SelectTrigger 对齐；focus-within 产生 ring；min-h 容纳多行 Tag
+          "flex w-fit cursor-text items-center justify-between gap-1.5 rounded-md border border-input bg-transparent py-1 pr-2 pl-2.5 text-xs transition-colors outline-none has-[input:focus]:border-ring has-[input:focus]:ring-1 has-[input:focus]:ring-ring data-[disabled]:pointer-events-none data-[disabled]:cursor-not-allowed data-[disabled]:opacity-50 data-[size=default]:min-h-8 data-[size=sm]:min-h-7 data-[size=lg]:min-h-9 data-[size=lg]:text-sm aria-invalid:border-destructive aria-invalid:ring-1 aria-invalid:ring-destructive/20 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+          className,
+        )}
+        {...props}
+      >
+        <div
+          data-slot="combobox-value-wrapper"
+          className="flex min-w-0 flex-1 flex-wrap items-center gap-1"
+        >
+          {children}
+          <CommandPrimitive.Input
+            ref={inputRef}
+            data-slot="combobox-search"
+            value={ctx.search}
+            onValueChange={ctx.setSearch}
+            placeholder={inputPlaceholder}
+            disabled={ctx.disabled}
+            onFocus={() => {
+              if (!ctx.open) ctx.setOpen(true);
+            }}
+            onKeyDown={(e) => {
+              if (
+                e.key === 'Backspace' &&
+                !e.currentTarget.value &&
+                ctx.multiple
+              ) {
+                const arr = Array.isArray(ctx.value) ? ctx.value : [];
+                const last = arr[arr.length - 1];
+                if (last !== undefined) {
+                  e.preventDefault();
+                  ctx.toggleValue(last);
+                }
+              } else if (e.key === 'Escape') {
+                e.preventDefault();
+                ctx.setOpen(false);
+              }
+            }}
+            className="min-w-10 flex-1 bg-transparent text-xs outline-none placeholder:text-muted-foreground disabled:cursor-not-allowed"
+          />
+        </div>
+        {showClear ? (
+          <span
+            role="button"
+            aria-label="清除"
+            tabIndex={-1}
+            data-slot="combobox-clear"
+            onPointerDown={(event) => {
+              event.preventDefault();
+              event.stopPropagation();
+            }}
+            onClick={(event) => {
+              event.preventDefault();
+              event.stopPropagation();
+              onClear?.();
+              ctx.setSearch('');
+              inputRef.current?.focus();
+            }}
+            className="inline-flex size-4 shrink-0 cursor-pointer items-center justify-center rounded-sm text-muted-foreground transition-colors hover:text-foreground"
+          >
+            <XIcon className="size-3.5" />
+          </span>
+        ) : (
+          <ChevronDownIcon className="size-4 shrink-0 text-muted-foreground" />
+        )}
+      </div>
+    </PopoverPrimitive.Anchor>
+  );
+}
+
+// ─── Value（触发区显示：单选文本 / 多选 Tag 组） ────────────────────────
+
+export interface ComboboxValueProps extends React.ComponentProps<'span'> {
+  /** 未选时占位文案。 */
+  placeholder?: React.ReactNode;
+}
+
+function ComboboxValue({
+  className: _className,
+  placeholder: _placeholder,
+  ...props
+}: ComboboxValueProps) {
+  const ctx = useComboboxContext('ComboboxValue');
+
+  const isEmpty = ctx.multiple
+    ? !Array.isArray(ctx.value) || ctx.value.length === 0
+    : !ctx.value;
+
+  // 未选时由 Trigger 内联 input 的 placeholder 接管占位文案，无需渲染节点
+  if (isEmpty) return null;
+
+  // 单选：渲染选中文本；输入搜索时让 input 占据可视区
+  if (!ctx.multiple) {
+    if (ctx.search) return null;
+    const v = ctx.value as string;
+    return (
+      <span
+        data-slot="combobox-value"
+        className={cn('line-clamp-1', _className)}
+        {...props}
+      >
+        {ctx.itemLabels.get(v) ?? v}
+      </span>
+    );
+  }
+
+  // 多选：用 Fragment 渲染 Tag 组，让其直接成为 Trigger flex 容器的子项，
+  // 与内联 search input 并排换行，达到 antd Select multiple 的视觉效果
+  const values = ctx.value as string[];
+  const max = ctx.maxTagCount;
+  const showAll = max === undefined || values.length <= max;
+  const visible = showAll ? values : values.slice(0, max);
+  const omitted = showAll ? [] : values.slice(max);
+
+  const omittedTitle = omitted
+    .map((v) => {
+      const label = ctx.itemLabels.get(v);
+      return typeof label === 'string' ? label : v;
+    })
+    .join(', ');
+
+  return (
+    <>
+      {visible.map((v) => (
+        <Tag
+          key={v}
+          size="sm"
+          closable
+          disabled={ctx.disabled}
+          onClose={(e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            if (ctx.disabled) return;
+            ctx.toggleValue(v);
+          }}
+          onClick={(e) => {
+            e.stopPropagation();
+          }}
+          onPointerDown={(e) => {
+            e.stopPropagation();
+          }}
+        >
+          {ctx.itemLabels.get(v) ?? v}
+        </Tag>
+      ))}
+      {omitted.length > 0 ? (
+        <Tag key="__rest__" size="sm" variant="outline" title={omittedTitle}>
+          {`+${omitted.length}`}
+        </Tag>
+      ) : null}
+    </>
+  );
+}
+
+// ─── Content ────────────────────────────────────────────────────────────
+
+export type ComboboxContentProps = React.ComponentProps<typeof PopoverContent>;
+
+function ComboboxContent({
+  className,
+  align = 'start',
+  sideOffset = 4,
+  children,
+  ...props
+}: ComboboxContentProps) {
+  const ctx = useComboboxContext('ComboboxContent');
+  return (
+    <PopoverContent
+      data-slot="combobox-content"
+      align={align}
+      sideOffset={sideOffset}
+      // 对齐触发器宽度，与 SelectContent 行为一致
+      className={cn(
+        'w-(--radix-popover-trigger-width) min-w-(--radix-popover-trigger-width) overflow-hidden bg-popover p-0 text-xs text-popover-foreground',
+        className,
+      )}
+      onOpenAutoFocus={(e) => {
+        // 焦点保持在 Trigger 内联 search input
+        e.preventDefault();
+      }}
+      onInteractOutside={(e) => {
+        // Trigger 是 Anchor，Radix 默认会将其视为 content 外部，
+        // pointerdown / focus 均会触发 dismiss，紧接着 onClick 又 setOpen(true)
+        // 造成面板先关后开的闪烁。这里领局拦截：只要交互 target 落在
+        // 触发区内，一律不关闭面板。
+        const target = e.target as Node | null;
+        if (target && ctx.triggerRef.current?.contains(target)) {
+          e.preventDefault();
+        }
+      }}
+      {...props}
+    >
+      {children}
+    </PopoverContent>
+  );
+}
+
+// ─── Input / List / Empty / Group / Separator ──────────────────────────
+
+function ComboboxList({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandList>) {
+  return (
+    <CommandList
+      data-slot="combobox-list"
+      className={cn('max-h-72', className)}
+      {...props}
+    />
+  );
+}
+
+function ComboboxEmpty({
+  className,
+  ...props
+}: React.ComponentProps<typeof CommandEmpty>) {
+  // 覆盖 CommandEmpty 默认 text-sm，遵循项目默认 12px 字号规范
+  return (
+    <CommandEmpty
+      data-slot="combobox-empty"
+      className={cn('text-xs', className)}
+      {...props}
+    />
+  );
+}
+
+function ComboboxGroup({
+  ...props
+}: React.ComponentProps<typeof CommandGroup>) {
+  return <CommandGroup data-slot="combobox-group" {...props} />;
+}
+
+function ComboboxSeparator({
+  ...props
+}: React.ComponentProps<typeof CommandSeparator>) {
+  return <CommandSeparator data-slot="combobox-separator" {...props} />;
+}
+
+// ─── Item ──────────────────────────────────────────────────────────────
+
+export interface ComboboxItemProps
+  extends Omit<
+    React.ComponentProps<typeof CommandPrimitive.Item>,
+    'onSelect' | 'value'
+  > {
+  /** 选项值，必填，用于受控状态匹配。 */
+  value: string;
+  /** 是否禁用。 */
+  disabled?: boolean;
+  /** cmdk 搜索关键字（除 children 文本外补充匹配项）。 */
+  keywords?: string[];
+}
+
+function ComboboxItem({
+  className,
+  value,
+  children,
+  keywords,
+  disabled,
+  ...props
+}: ComboboxItemProps) {
+  const ctx = useComboboxContext('ComboboxItem');
+
+  const checked = ctx.multiple
+    ? Array.isArray(ctx.value) && ctx.value.includes(value)
+    : ctx.value === value;
+
+  return (
+    <CommandPrimitive.Item
+      data-slot="combobox-item"
+      data-state={checked ? 'checked' : 'unchecked'}
+      value={value}
+      keywords={keywords}
+      disabled={disabled}
+      onSelect={() => {
+        if (disabled) return;
+        ctx.toggleValue(value);
+      }}
+      className={cn(
+        // 与 SelectItem 视觉对齐：h-8、左侧勾选位、选中态 text-primary
+        "group/combobox-item relative flex h-8 w-full cursor-pointer items-center gap-1.5 rounded-md py-1 pr-2 pl-7 text-xs outline-hidden select-none data-[disabled=true]:pointer-events-none data-[disabled=true]:opacity-50 data-[selected=true]:bg-accent data-[selected=true]:text-accent-foreground data-[state=checked]:text-primary [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        className,
+      )}
+      {...props}
+    >
+      <span className="pointer-events-none absolute left-2 flex size-4 items-center justify-center">
+        {checked ? <CheckIcon className="text-primary" /> : null}
+      </span>
+      {children}
+    </CommandPrimitive.Item>
+  );
+}
+
+// ─── Helper：静态提取 value → label ────────────────────────────────────
+
+/**
+ * 递归遍历 React children 树，找出所有 `<ComboboxItem>` 元素并把
+ * `value -> children` 写入 map。借助 React element tree 的静态结构，
+ * 即便 ComboboxContent 未挂载，触发区也能拿到完整的 label 映射。
+ */
+function collectComboboxLabels(
+  nodes: React.ReactNode,
+  map: Map<string, React.ReactNode>,
+): void {
+  React.Children.forEach(nodes, (child) => {
+    if (!React.isValidElement(child)) return;
+    const element = child as React.ReactElement<{
+      value?: string;
+      children?: React.ReactNode;
+    }>;
+    if (element.type === ComboboxItem) {
+      const v = element.props.value;
+      if (typeof v === 'string') {
+        map.set(v, element.props.children);
+      }
+      return;
+    }
+    if (element.props && 'children' in element.props) {
+      collectComboboxLabels(element.props.children, map);
+    }
+  });
+}
+
+export {
+  Combobox,
+  ComboboxContent,
+  ComboboxEmpty,
+  ComboboxGroup,
+  ComboboxItem,
+  ComboboxList,
+  ComboboxSeparator,
+  ComboboxTrigger,
+  ComboboxValue,
+};