@teamix-evo/ui 0.3.0 → 0.5.0

package/src/components/filter-bar/index.tsx

@@ -0,0 +1,976 @@
+/**
+ * 筛选栏 FilterBar
+ *
+ * 表格 / 列表页顶部的组合式筛选区域。形态由子组件组合决定：
+ * - `FilterBarHeader` 行内多字段并排（截图 1）
+ * - `FilterBarHeader` + `FilterBarTrigger` + `FilterBarContent` 行内+折叠面板（截图 2）
+ * - 仅 `FilterBarTrigger` + `FilterBarContent` 纯面板（截图 3）
+ * - `FilterBarSearch` 紧凑搜索条 + 高级筛选面板（截图 4 / 5）
+ *
+ * 内置 react-hook-form `FormProvider`，行内字段防抖触发 `onFilter`，
+ * 面板字段需点击搜索或 Enter 触发。
+ *
+ * @when
+ * - 列表页 / 表格页顶部多条件筛选
+ * - 需要 RHF 表单托管的查询区域
+ * - 需要"行内 + 高级筛选面板"两段式 UX
+ */
+'use client';
+
+import * as React from 'react';
+import { ChevronDown, Search } from 'lucide-react';
+import {
+  Controller,
+  FormProvider,
+  useController,
+  type Control,
+  type ControllerFieldState,
+  type ControllerRenderProps,
+  type FieldPath,
+  type FieldValues,
+  type SubmitHandler,
+  type UseFormReturn,
+  type UseFormStateReturn,
+} from 'react-hook-form';
+
+import { cn } from '@/lib/utils';
+import { Button } from '@/components/button';
+import {
+  Field,
+  FieldInsetBox,
+  FieldLabel,
+  FieldDescription,
+} from '@/components/field';
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from '@/components/collapsible';
+import { Input } from '@/components/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/select';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/** 列数：纯数字或响应式断点对象。 */
+export type FilterBarColumns =
+  | number
+  | {
+      base?: number;
+      sm?: number;
+      md?: number;
+      lg?: number;
+    };
+
+/** FilterBarSearchKey 的可切换字段选项。 */
+export interface FilterBarSearchOption {
+  /** RHF 字段名。 */
+  name: string;
+  /** 字段标签（出现在选择器与 placeholder）。 */
+  label: string;
+  /** 自定义 placeholder，缺省为 "请输入{label}"。 */
+  placeholder?: string;
+}
+
+interface FilterBarSearchContextValue {
+  activeName: string | undefined;
+  setActiveName: (name: string) => void;
+  exclusive: boolean;
+  options: FilterBarSearchOption[];
+  setOptions: (opts: FilterBarSearchOption[]) => void;
+}
+
+const FilterBarSearchContext =
+  React.createContext<FilterBarSearchContextValue | null>(null);
+
+function useFilterBarSearch(): FilterBarSearchContextValue {
+  const ctx = React.useContext(FilterBarSearchContext);
+  if (!ctx) {
+    throw new Error(
+      'FilterBarSearchKey / FilterBarSearchValue / FilterBarSearchAction 必须在 <FilterBarSearch> 内部使用',
+    );
+  }
+  return ctx;
+}
+
+interface FilterBarContextValue {
+  form: UseFormReturn<FieldValues>;
+  debounceMs: number;
+  clearOnReset: boolean;
+  open: boolean;
+  setOpen: (next: boolean) => void;
+  addonBefore?: React.ReactNode;
+  addonAfter?: React.ReactNode;
+  columns: FilterBarColumns;
+  triggerFilter: () => void;
+  triggerReset: () => void;
+}
+
+const FilterBarContext = React.createContext<FilterBarContextValue | null>(
+  null,
+);
+
+function useFilterBar(): FilterBarContextValue {
+  const ctx = React.useContext(FilterBarContext);
+  if (!ctx) {
+    throw new Error('FilterBar.* 必须在 <FilterBar> 内部使用');
+  }
+  return ctx;
+}
+
+/** 子区上下文：决定 FilterBarField / FilterBarFooter 的布局形态。 */
+type FilterBarSection = 'header' | 'content';
+const FilterBarSectionContext = React.createContext<FilterBarSection>('header');
+
+// ─── Tailwind 静态映射（grid 类名禁止动态拼接） ────────────────────────────
+
+const COLS_BASE: Record<number, string> = {
+  1: 'grid-cols-1',
+  2: 'grid-cols-2',
+  3: 'grid-cols-3',
+  4: 'grid-cols-4',
+  5: 'grid-cols-5',
+  6: 'grid-cols-6',
+};
+const COLS_SM: Record<number, string> = {
+  1: 'sm:grid-cols-1',
+  2: 'sm:grid-cols-2',
+  3: 'sm:grid-cols-3',
+  4: 'sm:grid-cols-4',
+  5: 'sm:grid-cols-5',
+  6: 'sm:grid-cols-6',
+};
+const COLS_MD: Record<number, string> = {
+  1: 'md:grid-cols-1',
+  2: 'md:grid-cols-2',
+  3: 'md:grid-cols-3',
+  4: 'md:grid-cols-4',
+  5: 'md:grid-cols-5',
+  6: 'md:grid-cols-6',
+};
+const COLS_LG: Record<number, string> = {
+  1: 'lg:grid-cols-1',
+  2: 'lg:grid-cols-2',
+  3: 'lg:grid-cols-3',
+  4: 'lg:grid-cols-4',
+  5: 'lg:grid-cols-5',
+  6: 'lg:grid-cols-6',
+};
+const COLSPAN: Record<number, string> = {
+  1: '',
+  2: 'col-span-2',
+  3: 'col-span-3',
+  4: 'col-span-4',
+  5: 'col-span-5',
+  6: 'col-span-6',
+};
+
+function clamp(n: number, min = 1, max = 6) {
+  return Math.max(min, Math.min(max, Math.floor(n)));
+}
+
+function resolveColumnsClass(columns: FilterBarColumns): string {
+  if (typeof columns === 'number') {
+    return COLS_BASE[clamp(columns)] ?? 'grid-cols-3';
+  }
+  const cls: string[] = [];
+  if (columns.base) cls.push(COLS_BASE[clamp(columns.base)] ?? '');
+  if (columns.sm) cls.push(COLS_SM[clamp(columns.sm)] ?? '');
+  if (columns.md) cls.push(COLS_MD[clamp(columns.md)] ?? '');
+  if (columns.lg) cls.push(COLS_LG[clamp(columns.lg)] ?? '');
+  const joined = cls.filter(Boolean).join(' ');
+  return joined || 'grid-cols-3';
+}
+
+// ─── FilterBar (Root) ───────────────────────────────────────────────────────
+
+export interface FilterBarProps<TForm extends FieldValues = FieldValues>
+  extends Omit<
+    React.ComponentProps<'form'>,
+    'onSubmit' | 'onReset' | 'onChange' | 'children'
+  > {
+  /** RHF 表单实例（必传），通常来自 `useForm()`。 */
+  form: UseFormReturn<TForm>;
+  /** 提交筛选回调（点击搜索 / 行内防抖 / Enter 触发）。 */
+  onFilter?: SubmitHandler<TForm>;
+  /** 重置回调（在 form.reset 之后触发）。 */
+  onReset?: () => void;
+  /** 表单值变化回调（任意字段变化即触发，未防抖）。 */
+  onChange?: (values: TForm) => void;
+  /** 首次挂载回调，可在此调 `form.setValue` 注入异步默认值。 */
+  onInit?: (form: UseFormReturn<TForm>) => void;
+  /** 高级筛选面板默认是否展开。 @default false */
+  defaultOpen?: boolean;
+  /** 高级筛选面板展开状态（受控）。 */
+  open?: boolean;
+  /** 展开状态变化回调。 */
+  onOpenChange?: (open: boolean) => void;
+  /** 行内字段防抖触发 onFilter 的延迟（毫秒）。 @default 300 */
+  debounceMs?: number;
+  /** 重置时是否丢弃 defaultValues（true=完全清空）。 @default false */
+  clearOnReset?: boolean;
+  /** 是否在行内字段变化时自动触发 onFilter（防抖）。 @default false */
+  autoFilter?: boolean;
+  /** Header 左侧槽位，常用于"+创建任务"等主操作按钮。 */
+  addonBefore?: React.ReactNode;
+  /** Header 右侧槽位，常用于⚙️等次要操作。 */
+  addonAfter?: React.ReactNode;
+  /** 面板栅格列数，默认 3。 */
+  columns?: FilterBarColumns;
+  children?: React.ReactNode;
+}
+
+function FilterBar<TForm extends FieldValues = FieldValues>({
+  form,
+  onFilter,
+  onReset,
+  onChange,
+  onInit,
+  defaultOpen = false,
+  open: openProp,
+  onOpenChange,
+  debounceMs = 300,
+  clearOnReset = false,
+  autoFilter = false,
+  addonBefore,
+  addonAfter,
+  columns = 3,
+  className,
+  children,
+  ...rest
+}: FilterBarProps<TForm>) {
+  const [internalOpen, setInternalOpen] = React.useState(defaultOpen);
+  const open = openProp ?? internalOpen;
+  const setOpen = React.useCallback(
+    (next: boolean) => {
+      if (openProp === undefined) setInternalOpen(next);
+      onOpenChange?.(next);
+    },
+    [openProp, onOpenChange],
+  );
+
+  // onInit — 仅在首次挂载执行一次
+  const initRef = React.useRef(false);
+  React.useEffect(() => {
+    if (initRef.current) return;
+    initRef.current = true;
+    onInit?.(form);
+  }, [form, onInit]);
+
+  // onChange — 订阅 form watch
+  React.useEffect(() => {
+    if (!onChange) return;
+    const sub = form.watch((values) => onChange(values as TForm));
+    return () => sub.unsubscribe();
+  }, [form, onChange]);
+
+  const triggerFilter = React.useCallback(() => {
+    void form.handleSubmit((values) => {
+      onFilter?.(values as TForm);
+    })();
+  }, [form, onFilter]);
+
+  const triggerReset = React.useCallback(() => {
+    if (clearOnReset) {
+      form.reset(undefined, { keepDefaultValues: false });
+    } else {
+      form.reset();
+    }
+    onReset?.();
+    triggerFilter();
+  }, [form, clearOnReset, onReset, triggerFilter]);
+
+  // autoFilter — 行内字段防抖触发 onFilter
+  React.useEffect(() => {
+    if (!autoFilter) return;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const sub = form.watch(() => {
+      if (timer) clearTimeout(timer);
+      timer = setTimeout(triggerFilter, debounceMs);
+    });
+    return () => {
+      if (timer) clearTimeout(timer);
+      sub.unsubscribe();
+    };
+  }, [form, autoFilter, debounceMs, triggerFilter]);
+
+  const ctx = React.useMemo<FilterBarContextValue>(
+    () => ({
+      form: form as unknown as UseFormReturn<FieldValues>,
+      debounceMs,
+      clearOnReset,
+      open,
+      setOpen,
+      addonBefore,
+      addonAfter,
+      columns,
+      triggerFilter,
+      triggerReset,
+    }),
+    [
+      form,
+      debounceMs,
+      clearOnReset,
+      open,
+      setOpen,
+      addonBefore,
+      addonAfter,
+      columns,
+      triggerFilter,
+      triggerReset,
+    ],
+  );
+
+  return (
+    <FilterBarContext.Provider value={ctx}>
+      <FormProvider {...form}>
+        <Collapsible open={open} onOpenChange={setOpen} asChild>
+          <form
+            data-slot="filter-bar"
+            onSubmit={(e) => {
+              e.preventDefault();
+              triggerFilter();
+            }}
+            className={cn('flex flex-col', className)}
+            {...rest}
+          >
+            {children}
+          </form>
+        </Collapsible>
+      </FormProvider>
+    </FilterBarContext.Provider>
+  );
+}
+
+// ─── FilterBarHeader ────────────────────────────────────────────────────────
+
+function FilterBarHeader({
+  className,
+  children,
+  ...props
+}: React.ComponentProps<'div'>) {
+  const { addonBefore, addonAfter } = useFilterBar();
+  return (
+    <FilterBarSectionContext.Provider value="header">
+      <div
+        data-slot="filter-bar-header"
+        className={cn('flex flex-wrap items-center gap-3', className)}
+        {...props}
+      >
+        {addonBefore && (
+          <div
+            data-slot="filter-bar-addon-before"
+            className="flex shrink-0 items-center"
+          >
+            {addonBefore}
+          </div>
+        )}
+        <div className="flex min-w-0 flex-1 flex-wrap items-center gap-3">
+          {children}
+        </div>
+        {addonAfter && (
+          <div
+            data-slot="filter-bar-addon-after"
+            className="flex shrink-0 items-center"
+          >
+            {addonAfter}
+          </div>
+        )}
+      </div>
+    </FilterBarSectionContext.Provider>
+  );
+}
+
+// ─── FilterBarSearch ────────────────────────────────────────────────────────
+
+export interface FilterBarSearchProps
+  extends Omit<React.ComponentProps<'div'>, 'children'> {
+  /** 切换搜索字段时是否清空其它字段。 @default true */
+  exclusive?: boolean;
+  /** 三段 children：`FilterBarSearchKey` + `FilterBarSearchValue` + `FilterBarSearchAction`。 */
+  children?: React.ReactNode;
+}
+
+function FilterBarSearch({
+  exclusive = true,
+  className,
+  children,
+  ...props
+}: FilterBarSearchProps) {
+  const [activeName, setActiveName] = React.useState<string | undefined>(
+    undefined,
+  );
+  const [options, setOptions] = React.useState<FilterBarSearchOption[]>([]);
+
+  const ctx = React.useMemo<FilterBarSearchContextValue>(
+    () => ({ activeName, setActiveName, exclusive, options, setOptions }),
+    [activeName, exclusive, options],
+  );
+
+  return (
+    <FilterBarSearchContext.Provider value={ctx}>
+      <div
+        data-slot="filter-bar-search"
+        className={cn(
+          'flex h-8 items-center overflow-hidden rounded-md border border-input bg-card',
+          'focus-within:border-ring focus-within:ring-1 focus-within:ring-ring',
+          className,
+        )}
+        {...props}
+      >
+        {children}
+      </div>
+    </FilterBarSearchContext.Provider>
+  );
+}
+
+// ─── FilterBarSearchKey ─────────────────────────────────────
+
+export interface FilterBarSearchKeyProps {
+  /** 可切换的字段选项。 */
+  options: FilterBarSearchOption[];
+  className?: string;
+}
+
+function FilterBarSearchKey({ options, className }: FilterBarSearchKeyProps) {
+  const search = useFilterBarSearch();
+  const { form } = useFilterBar();
+
+  // 注册 options 到 SearchContext + 默认 active 首项
+  React.useEffect(() => {
+    search.setOptions(options);
+    if (!search.activeName && options[0]) {
+      search.setActiveName(options[0].name);
+    }
+  }, [options]);
+
+  const active =
+    options.find((o) => o.name === search.activeName) ?? options[0];
+
+  const onChange = (name: string) => {
+    if (search.exclusive) {
+      options.forEach((o) => {
+        if (o.name !== name) {
+          form.setValue(o.name as FieldPath<FieldValues>, '');
+        }
+      });
+    }
+    search.setActiveName(name);
+  };
+
+  if (!active) return null;
+
+  return (
+    <Select value={active.name} onValueChange={onChange}>
+      <SelectTrigger
+        size="sm"
+        className={cn(
+          'h-full rounded-none border-0 border-r border-input bg-transparent shadow-none focus-visible:ring-0',
+          className,
+        )}
+      >
+        <SelectValue />
+      </SelectTrigger>
+      <SelectContent>
+        {options.map((o) => (
+          <SelectItem key={o.name} value={o.name}>
+            {o.label}
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
+
+// ─── FilterBarSearchValue ───────────────────────────────────
+
+export interface FilterBarSearchValueProps
+  extends Omit<
+    React.ComponentProps<typeof Input>,
+    'name' | 'value' | 'onChange'
+  > {
+  /** 自定义 placeholder（缺省取 active option 的 placeholder 或「请输入{label}」）。 */
+  placeholder?: string;
+}
+
+function FilterBarSearchValue({
+  placeholder,
+  className,
+  ...props
+}: FilterBarSearchValueProps) {
+  const search = useFilterBarSearch();
+  const { form, triggerFilter } = useFilterBar();
+  const active = search.options.find((o) => o.name === search.activeName);
+
+  if (!active) return null;
+
+  const ph = placeholder ?? active.placeholder ?? `请输入${active.label}`;
+
+  return (
+    <Controller
+      control={form.control}
+      name={active.name as FieldPath<FieldValues>}
+      render={({ field }) => (
+        <Input
+          {...props}
+          value={(field.value as string | undefined) ?? ''}
+          onChange={field.onChange}
+          onBlur={field.onBlur}
+          onKeyDown={(e) => {
+            if (e.key === 'Enter') {
+              e.preventDefault();
+              triggerFilter();
+            }
+          }}
+          placeholder={ph}
+          className={cn(
+            'h-full flex-1 rounded-none border-0 shadow-none focus-visible:border-0 focus-visible:ring-0',
+            className,
+          )}
+        />
+      )}
+    />
+  );
+}
+
+// ─── FilterBarSearchAction ──────────────────────────────────
+
+export interface FilterBarSearchActionProps
+  extends React.ComponentProps<'button'> {}
+
+function FilterBarSearchAction({
+  className,
+  children,
+  onClick,
+  ...props
+}: FilterBarSearchActionProps) {
+  const { triggerFilter } = useFilterBar();
+  return (
+    <button
+      type="button"
+      aria-label="搜索"
+      onClick={(e) => {
+        onClick?.(e);
+        if (!e.defaultPrevented) triggerFilter();
+      }}
+      className={cn(
+        'flex h-full w-8 cursor-pointer items-center justify-center border-l border-input text-muted-foreground transition-colors hover:bg-muted hover:text-foreground',
+        className,
+      )}
+      {...props}
+    >
+      {children ?? <Search className="size-3.5" />}
+    </button>
+  );
+}
+
+// ─── FilterBarTrigger ───────────────────────────────────────────────────────
+
+export interface FilterBarTriggerProps
+  extends React.ComponentProps<typeof Button> {}
+
+function FilterBarTrigger({
+  className,
+  children,
+  ...props
+}: FilterBarTriggerProps) {
+  const { open } = useFilterBar();
+  return (
+    <CollapsibleTrigger asChild>
+      <Button
+        type="button"
+        variant="outline"
+        data-slot="filter-bar-trigger"
+        className={className}
+        {...props}
+      >
+        {children ?? '高级筛选'}
+        <ChevronDown
+          className={cn('transition-transform', open && 'rotate-180')}
+        />
+      </Button>
+    </CollapsibleTrigger>
+  );
+}
+
+// ─── FilterBarContent ───────────────────────────────────────────────────────
+
+export interface FilterBarContentProps
+  extends React.ComponentProps<typeof CollapsibleContent> {
+  /** 覆盖 Root 的 columns 配置。 */
+  columns?: FilterBarColumns;
+}
+
+function FilterBarContent({
+  columns: columnsProp,
+  className,
+  children,
+  ...props
+}: FilterBarContentProps) {
+  const { columns: ctxColumns } = useFilterBar();
+  const columns = columnsProp ?? ctxColumns;
+  const colClass = resolveColumnsClass(columns);
+  return (
+    <FilterBarSectionContext.Provider value="content">
+      <CollapsibleContent
+        data-slot="filter-bar-content"
+        className={cn('overflow-hidden pt-2', className)}
+        {...props}
+      >
+        <div
+          className={cn(
+            'grid gap-x-4 gap-y-3 rounded-md bg-muted px-4 py-4',
+            '[&_[data-slot=input]]:bg-card [&_[data-slot=select-trigger]]:bg-card [&_[data-slot=input-number]]:bg-card [&_[data-slot=textarea]]:bg-card',
+            // 面板内表单控件统一全宽（仅作用于 FilterBarContent 子树）
+            '[&_[data-slot=input]]:w-full [&_[data-slot=input-group]]:w-full [&_[data-slot=input-number]]:w-full [&_[data-slot=input-ip]]:w-full [&_[data-slot=textarea]]:w-full',
+            '[&_[data-slot=select-trigger]]:w-full [&_[data-slot=cascader-select-trigger]]:w-full [&_[data-slot=tree-select-trigger]]:w-full',
+            '[&_[data-slot=date-picker]]:w-full [&_[data-slot=date-range-picker]]:w-full [&_[data-slot=time-picker]]:w-full [&_[data-slot=time-range-picker]]:w-full [&_[data-slot=mentions]]:w-full',
+            colClass,
+          )}
+        >
+          {children}
+        </div>
+      </CollapsibleContent>
+    </FilterBarSectionContext.Provider>
+  );
+}
+
+// ─── FilterBarFooter ────────────────────────────────────────────────────────
+
+export interface FilterBarActionsProps extends React.ComponentProps<'div'> {
+  /**
+   * 自定义按钮组（完全替换默认「重置 + 搜索」）。
+   * 不传时默认渲染重置与搜索两按钮。
+   */
+  children?: React.ReactNode;
+}
+
+function FilterBarActions({
+  className,
+  children,
+  ...props
+}: FilterBarActionsProps) {
+  const section = React.useContext(FilterBarSectionContext);
+  const { triggerFilter, triggerReset } = useFilterBar();
+  const inContent = section === 'content';
+  return (
+    <div
+      data-slot="filter-bar-actions"
+      className={cn(
+        'flex items-center justify-end gap-2',
+        inContent ? 'col-span-full' : 'shrink-0',
+        className,
+      )}
+      {...props}
+    >
+      {children ?? (
+        <>
+          <Button
+            type="button"
+            variant="outline"
+            style={{ minWidth: 60 }}
+            onClick={triggerReset}
+          >
+            重置
+          </Button>
+          <Button
+            type="button"
+            style={{ minWidth: 60 }}
+            onClick={triggerFilter}
+          >
+            搜索
+          </Button>
+        </>
+      )}
+    </div>
+  );
+}
+
+// ─── FilterBarField ─────────────────────────────────────────────────────────
+
+/**
+ * children 模式下的 prop 桥接适配表（ADR 0037 v2.1）。
+ *
+ * 用 child element 的 `type.displayName || type.name` 识别身份，决定注入的 prop 形态。
+ * 不在表中的子元素退化为 `value` + `onChange` 默认对。
+ */
+function getControlBindings(
+  child: React.ReactElement,
+  field: ControllerRenderProps<FieldValues>,
+): Record<string, unknown> {
+  const type = child.type as { displayName?: string; name?: string } | string;
+  const id =
+    typeof type === 'string' ? type : type?.displayName || type?.name || '';
+
+  // boolean 二态：checked + onCheckedChange
+  if (id === 'Checkbox' || id === 'Switch') {
+    return {
+      checked: field.value as boolean | undefined,
+      onCheckedChange: field.onChange,
+      name: field.name,
+      ref: field.ref,
+      onBlur: field.onBlur,
+    };
+  }
+
+  // value-by-value（Radix 风格 onValueChange）
+  if (
+    id === 'Select' ||
+    id === 'RadioGroup' ||
+    id === 'Slider' ||
+    id === 'ToggleGroup'
+  ) {
+    return {
+      value: field.value,
+      onValueChange: field.onChange,
+      name: field.name,
+      ref: field.ref,
+      onBlur: field.onBlur,
+    };
+  }
+
+  // 默认：value + event-style onChange（Input/Textarea/InputNumber/未知）
+  if (
+    process.env.NODE_ENV !== 'production' &&
+    id &&
+    !['Input', 'Textarea', 'InputNumber'].includes(id)
+  ) {
+    // 兜底匹配但提示用户：未识别控件请考虑用 render prop
+
+    console.warn(
+      `[FilterBarField] 未识别的受控控件 (displayName=${id})，已默认注入 value + onChange。如行为不符，请改用 render prop。`,
+    );
+  }
+  return {
+    value: field.value,
+    onChange: field.onChange,
+    name: field.name,
+    ref: field.ref,
+    onBlur: field.onBlur,
+  };
+}
+
+/** FilterBarField 布局模式（ADR 0037 v2.3）。 */
+export type FilterBarFieldLayout =
+  | 'inline'
+  | 'outline'
+  | 'vertical'
+  | 'horizontal';
+
+export interface FilterBarFieldProps<
+  TForm extends FieldValues = FieldValues,
+  TName extends FieldPath<TForm> = FieldPath<TForm>,
+> {
+  /** RHF 字段名。 */
+  name: TName;
+  /** 字段标签。outline 模式必填（主视觉元素）。 */
+  label?: React.ReactNode;
+  /** 字段说明（仅 vertical / horizontal 布局显示）。 */
+  description?: React.ReactNode;
+  /** 容器自定义 className。 */
+  className?: string;
+  /**
+   * 布局模式。不传时按 section 推断：Header → `outline`；Content → `horizontal`。
+   *
+   * - `inline`：label 左外 + 控件横向（控件自带边框）
+   * - `outline`：label 嵌入外框内左侧（控件去边框）
+   * - `vertical`：label 上 + 控件下
+   * - `horizontal`：label 左外 + 控件右
+   */
+  layout?: FilterBarFieldLayout;
+  /** 占用栅格列数（仅 Content section 生效）。 @default 1 */
+  colSpan?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Header 形态（inline / outline）下控件最大宽度（px）。 @default 240 */
+  inlineMaxWidth?: number;
+  /** 显式指定 RHF control（默认从 FilterBar 上下文取）。 */
+  control?: Control<TForm>;
+  /**
+   * 静态 JSX 子元素（首选，AI 友好）。内部按子元素身份自动桥接 RHF field 到 `value`/`checked` + 对应 onChange。
+   * 适配 Input / Select / Checkbox / Switch / RadioGroup / Slider / Textarea；
+   * 不在适配表中的自定义控件请改用 `render` prop。
+   */
+  children?: React.ReactElement;
+  /** 渲染输入控件（逆出舱，适配表不覆盖时使用）。 */
+  render?: (props: {
+    field: ControllerRenderProps<TForm, TName>;
+    fieldState: ControllerFieldState;
+    formState: UseFormStateReturn<TForm>;
+  }) => React.ReactElement;
+}
+
+/**
+ * children 模式下的内部桥接组件：用 useController 拿 field，再 cloneElement 注入 prop。
+ * 必须在 FormProvider 子树内调用（FilterBar Root 已提供）。
+ */
+function FilterBarFieldChildBridge({
+  name,
+  control,
+  child,
+}: {
+  name: string;
+  control?: Control<FieldValues>;
+  child: React.ReactElement;
+}) {
+  const { field } = useController({ name, control });
+  return React.cloneElement(child, getControlBindings(child, field));
+}
+
+function FilterBarField<
+  TForm extends FieldValues = FieldValues,
+  TName extends FieldPath<TForm> = FieldPath<TForm>,
+>({
+  name,
+  label,
+  description,
+  className,
+  layout: layoutProp,
+  colSpan = 1,
+  inlineMaxWidth = 240,
+  control,
+  children,
+  render,
+}: FilterBarFieldProps<TForm, TName>) {
+  const { form } = useFilterBar();
+  const section = React.useContext(FilterBarSectionContext);
+  const ctrl = control ?? (form.control as unknown as Control<TForm>);
+
+  // 默认推断：Header → outline；Content → horizontal
+  const layout: FilterBarFieldLayout =
+    layoutProp ?? (section === 'header' ? 'outline' : 'horizontal');
+  const inHeader = section === 'header';
+  const colSpanClass = inHeader ? '' : COLSPAN[colSpan] ?? '';
+  const useMaxWidth = layout === 'inline' || layout === 'outline';
+
+  if (process.env.NODE_ENV !== 'production') {
+    if (children && render) {
+      console.warn(
+        '[FilterBarField] children 与 render 同时传入，children 优先生效。',
+      );
+    }
+    if (layout === 'outline' && !label) {
+      console.warn(
+        `[FilterBarField name="${String(
+          name,
+        )}"] outline 布局下 label 为主视觉元素，必须传 label。`,
+      );
+    }
+  }
+
+  // 控件渲染体：children（首选） > render（逆出舱）
+  let control$: React.ReactNode;
+  if (children) {
+    const only = React.Children.only(children) as React.ReactElement;
+    control$ = (
+      <FilterBarFieldChildBridge
+        name={name as string}
+        control={ctrl as unknown as Control<FieldValues>}
+        child={only}
+      />
+    );
+  } else if (render) {
+    control$ = (
+      <Controller control={ctrl} name={name} render={(p) => render(p)} />
+    );
+  } else {
+    if (process.env.NODE_ENV !== 'production') {
+      console.warn(
+        `[FilterBarField name="${String(
+          name,
+        )}"] 必须提供 children 或 render 之一。`,
+      );
+    }
+    control$ = null;
+  }
+
+  const showDescription =
+    description && (layout === 'vertical' || layout === 'horizontal');
+
+  // outline → Field inset + FieldInsetBox（共享 INSET_INNER_RESET，覆盖所有控件）
+  if (layout === 'outline') {
+    return (
+      <Field
+        orientation="inset"
+        data-slot="filter-bar-field"
+        data-layout="outline"
+        className={cn(colSpanClass, className)}
+        style={useMaxWidth ? { maxWidth: inlineMaxWidth } : undefined}
+      >
+        <FieldInsetBox>
+          {label && <FieldLabel>{label}</FieldLabel>}
+          <div className="flex h-full min-w-0 flex-1 items-center">
+            {control$}
+          </div>
+        </FieldInsetBox>
+      </Field>
+    );
+  }
+
+  // vertical → Field vertical + FieldLabel + FieldDescription
+  if (layout === 'vertical') {
+    return (
+      <Field
+        orientation="vertical"
+        data-slot="filter-bar-field"
+        data-layout="vertical"
+        className={cn(colSpanClass, className)}
+      >
+        {label && <FieldLabel>{label}</FieldLabel>}
+        {control$}
+        {showDescription && <FieldDescription>{description}</FieldDescription>}
+      </Field>
+    );
+  }
+
+  // horizontal / inline → FieldLabel + FieldDescription（无对应 Field orientation）
+  return (
+    <div
+      data-slot="filter-bar-field"
+      data-layout={layout}
+      className={cn(
+        layout === 'inline'
+          ? 'flex items-center gap-2'
+          : 'grid grid-cols-[1fr_3fr] items-center gap-4',
+        colSpanClass,
+        className,
+      )}
+      style={useMaxWidth ? { maxWidth: inlineMaxWidth } : undefined}
+    >
+      {label && (
+        <FieldLabel
+          className={cn(
+            'shrink-0',
+            layout === 'horizontal' && 'w-full justify-end',
+          )}
+        >
+          {label}
+        </FieldLabel>
+      )}
+      <div className="min-w-0">{control$}</div>
+      {showDescription && (
+        <FieldDescription className="col-start-2">
+          {description}
+        </FieldDescription>
+      )}
+    </div>
+  );
+}
+
+// ─── Exports ────────────────────────────────────────────────────────────────
+
+export {
+  FilterBar,
+  FilterBarHeader,
+  FilterBarSearch,
+  FilterBarSearchKey,
+  FilterBarSearchValue,
+  FilterBarSearchAction,
+  FilterBarTrigger,
+  FilterBarContent,
+  FilterBarActions,
+  FilterBarField,
+};