@teamix-evo/ui 0.2.0 → 0.3.0

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

@@ -0,0 +1,568 @@
+import * as React from 'react';
+import { cva, type VariantProps } from 'class-variance-authority';
+import { ChevronDown, ChevronUp, Search, RotateCcw } from 'lucide-react';
+import {
+  type UseFormReturn,
+  type FieldValues,
+  useFormContext,
+} from 'react-hook-form';
+
+import { cn } from '@/utils/cn';
+import { Button } from '@/components/button/button';
+import {
+  Collapsible,
+  CollapsibleContent,
+  CollapsibleTrigger,
+} from '@/components/collapsible/collapsible';
+import { Row, Col } from '@/components/grid/grid';
+import { useDebounceCallback } from '@/hooks/use-debounce-callback';
+import {
+  useBreakpoint,
+  pickByBreakpoint,
+  type ResponsiveValue,
+} from '@/hooks/use-breakpoint';
+
+// ─── Context ─────────────────────────────────────────────────────────────────
+
+interface FilterBarContextValue {
+  expanded: boolean;
+  setExpanded: React.Dispatch<React.SetStateAction<boolean>>;
+  onFilter?: (values: Record<string, any>) => void;
+  onReset?: (values: Record<string, any>) => void;
+  filterDebounce: number;
+  /** Label 对齐模式 — 右对齐仅适用于筛选区短标签。@default 'left' */
+  labelAlign: 'left' | 'right';
+  /** 输入域最大宽度(px) — 未设时以有效列数推断(≤2 列为 600，否则 400)。@default undefined */
+  inputMaxWidth?: number;
+}
+
+const FilterBarContext = React.createContext<FilterBarContextValue | null>(
+  null,
+);
+
+function useFilterBarContext() {
+  const ctx = React.useContext(FilterBarContext);
+  if (!ctx) {
+    throw new Error('FilterBar 子组件必须在 <FilterBar> 内使用。');
+  }
+  return ctx;
+}
+
+// ─── FilterBar (root) ────────────────────────────────────────────────────────
+
+const filterBarVariants = cva('flex flex-col gap-3 w-full', {
+  variants: {
+    /**
+     * 容器外观变体。
+     * @default "plain"
+     */
+    variant: {
+      plain: '',
+      bordered: 'rounded-md border border-border p-4',
+    },
+  },
+  defaultVariants: {
+    variant: 'plain',
+  },
+});
+
+export interface FilterBarProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    VariantProps<typeof filterBarVariants> {
+  /**
+   * react-hook-form 实例 — 由 `useForm()` 创建,管理所有筛选字段的状态。
+   */
+  form: UseFormReturn<any>;
+  /**
+   * 面板是否默认展开。
+   * @default false
+   */
+  defaultExpanded?: boolean;
+  /**
+   * 筛选回调 — inline 模式防抖后触发,或面板模式点"搜索"按钮触发。
+   */
+  onFilter?: (values: Record<string, any>) => void;
+  /**
+   * 重置回调 — 点"重置"按钮后触发,参数为重置后的表单值。
+   */
+  onReset?: (values: Record<string, any>) => void;
+  /**
+   * inline 区 onChange 事件的防抖时间(ms)。
+   * @default 300
+   */
+  filterDebounce?: number;
+  /**
+   * Label 对齐模式 — 右对齐仅适用于筛选区短标签。
+   * @default 'left'
+   */
+  labelAlign?: 'left' | 'right';
+  /**
+   * 输入域最大宽度(px) — 未设时走默认推断: 多栏(≥3 列)为 400，单栏/双栏为 600。
+   * @default undefined
+   */
+  inputMaxWidth?: number;
+}
+
+/**
+ * `FilterBar` 根容器 — 注入筛选上下文(form / expand 状态 / 回调),
+ * 子组件通过 context 读取和操作。
+ */
+const FilterBar = React.forwardRef<HTMLDivElement, FilterBarProps>(
+  (
+    {
+      form,
+      defaultExpanded = false,
+      onFilter,
+      onReset,
+      filterDebounce = 300,
+      labelAlign = 'left',
+      inputMaxWidth,
+      variant,
+      className,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const [expanded, setExpanded] = React.useState(defaultExpanded);
+
+    const ctxValue = React.useMemo<FilterBarContextValue>(
+      () => ({
+        expanded,
+        setExpanded,
+        onFilter,
+        onReset,
+        filterDebounce,
+        labelAlign,
+        inputMaxWidth,
+      }),
+      [expanded, onFilter, onReset, filterDebounce, labelAlign, inputMaxWidth],
+    );
+
+    return (
+      <FilterBarContext.Provider value={ctxValue}>
+        <Collapsible open={expanded} onOpenChange={setExpanded} asChild>
+          <div
+            ref={ref}
+            className={cn(filterBarVariants({ variant }), className)}
+            {...props}
+          >
+            {children}
+          </div>
+        </Collapsible>
+      </FilterBarContext.Provider>
+    );
+  },
+);
+FilterBar.displayName = 'FilterBar';
+
+// ─── FilterBarSearch ─────────────────────────────────────────────────────────
+
+export interface FilterBarSearchProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 是否启用 inline 实时筛选 — 开启后子字段 onChange 触发防抖 onFilter。
+   * @default true
+   */
+  autoFilter?: boolean;
+}
+
+/**
+ * `FilterBarSearch` 行内搜索区 — 放置高频筛选字段(Select / Input 等),
+ * 水平排列。`autoFilter=true` 时自动监听表单变更并防抖触发 `onFilter`。
+ */
+const FilterBarSearch = React.forwardRef<HTMLDivElement, FilterBarSearchProps>(
+  ({ autoFilter = true, className, children, ...props }, ref) => {
+    const { onFilter, filterDebounce } = useFilterBarContext();
+    const form = useFormContext();
+
+    const debouncedFilter = useDebounceCallback(
+      (values: Record<string, any>) => {
+        onFilter?.(values);
+      },
+      filterDebounce,
+    );
+
+    // 监听表单变更,防抖触发 onFilter
+    React.useEffect(() => {
+      if (!autoFilter || !form) return;
+      const subscription = form.watch((values) => {
+        debouncedFilter(values as Record<string, any>);
+      });
+      return () => subscription.unsubscribe();
+    }, [autoFilter, form, debouncedFilter]);
+
+    return (
+      <div
+        ref={ref}
+        className={cn('flex items-center gap-2 flex-wrap', className)}
+        {...props}
+      >
+        {children}
+      </div>
+    );
+  },
+);
+FilterBarSearch.displayName = 'FilterBarSearch';
+
+// ─── FilterBarTrigger ────────────────────────────────────────────────────────
+
+export interface FilterBarTriggerProps {
+  /**
+   * 展开时显示的文案。
+   * @default "高级筛选"
+   */
+  expandedLabel?: string;
+  /**
+   * 收起时显示的文案。
+   * @default "高级筛选"
+   */
+  collapsedLabel?: string;
+  /**
+   * 额外的 className。
+   */
+  className?: string;
+}
+
+/**
+ * `FilterBarTrigger` 展开/收起触发器 — 自动读取 expand 状态,
+ * 切换 ChevronDown / ChevronUp 图标。
+ */
+const FilterBarTrigger = React.forwardRef<
+  HTMLButtonElement,
+  FilterBarTriggerProps
+>(
+  (
+    { expandedLabel = '高级筛选', collapsedLabel = '高级筛选', className },
+    ref,
+  ) => {
+    const { expanded } = useFilterBarContext();
+
+    return (
+      <CollapsibleTrigger asChild>
+        <Button
+          ref={ref}
+          variant="outline"
+          color="default"
+          className={cn('gap-1', className)}
+        >
+          {expanded ? (
+            <ChevronUp className="size-4" />
+          ) : (
+            <ChevronDown className="size-4" />
+          )}
+          {expanded ? expandedLabel : collapsedLabel}
+        </Button>
+      </CollapsibleTrigger>
+    );
+  },
+);
+FilterBarTrigger.displayName = 'FilterBarTrigger';
+
+// ─── FilterBarPanel ──────────────────────────────────────────────────────────
+
+export interface FilterBarPanelProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 静态列数 — 面板内字段按此列数等分排列(走 Row/Col 24 栅格)。
+   * 传入 `responsiveColumns` 时被覆盖。
+   * @default 3
+   */
+  columns?: 1 | 2 | 3 | 4;
+  /**
+   * 响应式列数 — 标量或 5 档断点映射(对齐《Teamix UI 表单设计规范》§4.1):
+   *   - `base` < 432 / `xs` ≥ 432 / `s` ≥ 672 / `m` ≥ 944 / `l` ≥ 1200 / `xl` ≥ 1600
+   *
+   * 启用后走 CSS Grid + JS-side useBreakpoint 解析(不依赖客户 Tailwind 配置)。
+   * 优先级高于 `columns`。
+   *
+   * @example responsiveColumns={{ base: 1, xs: 2, m: 3, l: 4 }}
+   */
+  responsiveColumns?: ResponsiveValue<1 | 2 | 3 | 4>;
+}
+
+/**
+ * `FilterBarPanel` 可折叠面板 — 展开后显示更多筛选字段。
+ * 传入 `responsiveColumns` 时走 CSS Grid 响应式布局,否则走 Row/Col 栅格。
+ */
+const FilterBarPanel = React.forwardRef<HTMLDivElement, FilterBarPanelProps>(
+  ({ columns = 3, responsiveColumns, className, children, ...props }, ref) => {
+    const { labelAlign, inputMaxWidth } = useFilterBarContext();
+    const currentBp = useBreakpoint();
+
+    // 展开 Fragment,收集所有实际子元素
+    const flatChildren: React.ReactNode[] = [];
+    const flatten = (nodes: React.ReactNode) => {
+      React.Children.forEach(nodes, (child) => {
+        if (!React.isValidElement(child)) {
+          if (child != null) flatChildren.push(child);
+          return;
+        }
+        if (child.type === React.Fragment) {
+          flatten(child.props.children);
+        } else {
+          flatChildren.push(child);
+        }
+      });
+    };
+    flatten(children);
+
+    // 解析响应式列数:有响应式则按当前断点取值;无则用静态 columns
+    const resolvedCols =
+      pickByBreakpoint(responsiveColumns, currentBp) ?? columns;
+
+    // 输入域最大宽度推断(响应规范 §4.1:多栏 400 / 单双栏 600)
+    const maxW = inputMaxWidth ?? (resolvedCols <= 2 ? 600 : 400);
+    const fieldStyle: React.CSSProperties = { maxWidth: `${maxW}px` };
+
+    // label 对齐 class:右对齐仅适用于横向窗口下的短标签筛选区;
+    // viewport < xs(432px,规范 §4.1)时强制左对齐,避免上下结构时 label 右贴反直觉
+    const effectiveLabelAlign =
+      labelAlign === 'right' && currentBp === null ? 'left' : labelAlign;
+    const labelAlignClass =
+      effectiveLabelAlign === 'right' ? '[&_label]:text-right' : '';
+
+    let content: React.ReactNode;
+
+    if (responsiveColumns) {
+      // CSS Grid 响应式模式
+      const gridStyle: React.CSSProperties = {
+        display: 'grid',
+        gridTemplateColumns: `repeat(${resolvedCols}, minmax(0, 1fr))`,
+        columnGap: '1rem', // 16px,对齐规范 §3.1 规则 3
+        rowGap: '1.25rem', // 20px,对齐规范 §3.1 规则 4
+      };
+
+      const gridChildren = flatChildren.map((child, idx) => {
+        if (!React.isValidElement(child)) {
+          return <React.Fragment key={idx}>{child}</React.Fragment>;
+        }
+        if (child.type === FilterBarActions) {
+          return (
+            <div key={idx} style={{ gridColumn: '1 / -1' }}>
+              {child}
+            </div>
+          );
+        }
+        return (
+          <div key={idx} style={fieldStyle}>
+            {child}
+          </div>
+        );
+      });
+
+      content = <div style={gridStyle}>{gridChildren}</div>;
+    } else {
+      // Row/Col 栅格模式(静态 columns)
+      const colSpan = Math.floor(24 / columns);
+
+      const wrappedChildren = flatChildren.map((child, idx) => {
+        if (!React.isValidElement(child)) return child;
+        if (child.type === Col) return child;
+        if (child.type === FilterBarActions) {
+          return (
+            <Col key={idx} span={24}>
+              {child}
+            </Col>
+          );
+        }
+        return (
+          <Col key={idx} span={colSpan}>
+            <div style={fieldStyle}>{child}</div>
+          </Col>
+        );
+      });
+
+      content = <Row gutter={[4, 4]}>{wrappedChildren}</Row>;
+    }
+
+    return (
+      <CollapsibleContent>
+        <div
+          ref={ref}
+          data-label-align={effectiveLabelAlign}
+          className={cn('pt-4', labelAlignClass, className)}
+          {...props}
+        >
+          {content}
+        </div>
+      </CollapsibleContent>
+    );
+  },
+);
+FilterBarPanel.displayName = 'FilterBarPanel';
+
+// ─── FilterBarActions ────────────────────────────────────────────────────────
+
+export interface FilterBarActionsProps
+  extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 搜索按钮文案。
+   * @default "搜索"
+   */
+  submitText?: string;
+  /**
+   * 重置按钮文案。
+   * @default "重置"
+   */
+  resetText?: string;
+  /**
+   * 是否显示搜索按钮。
+   * @default true
+   */
+  showSubmit?: boolean;
+  /**
+   * 是否显示重置按钮。
+   * @default true
+   */
+  showReset?: boolean;
+}
+
+/**
+ * `FilterBarActions` 操作按钮区 — 搜索 + 重置按钮。
+ * 搜索走 `form.handleSubmit → onFilter`,重置走 `form.reset → onReset`。
+ */
+const FilterBarActions = React.forwardRef<
+  HTMLDivElement,
+  FilterBarActionsProps
+>(
+  (
+    {
+      submitText = '搜索',
+      resetText = '重置',
+      showSubmit = true,
+      showReset = true,
+      className,
+      children,
+      ...props
+    },
+    ref,
+  ) => {
+    const { onFilter, onReset } = useFilterBarContext();
+    const form = useFormContext();
+
+    const handleSubmit = React.useCallback(() => {
+      if (!form) return;
+      form.handleSubmit((values) => {
+        onFilter?.(values);
+      })();
+    }, [form, onFilter]);
+
+    const handleReset = React.useCallback(() => {
+      if (!form) return;
+      form.reset();
+      const values = form.getValues();
+      onReset?.(values);
+    }, [form, onReset]);
+
+    return (
+      <div
+        ref={ref}
+        className={cn('flex items-center justify-end gap-2 pt-3', className)}
+        {...props}
+      >
+        {children}
+        {showReset && (
+          <Button type="button" variant="outline" onClick={handleReset}>
+            <RotateCcw className="size-4" />
+            {resetText}
+          </Button>
+        )}
+        {showSubmit && (
+          <Button type="button" onClick={handleSubmit}>
+            <Search className="size-4" />
+            {submitText}
+          </Button>
+        )}
+      </div>
+    );
+  },
+);
+FilterBarActions.displayName = 'FilterBarActions';
+
+// ─── FilterBarPreset ─────────────────────────────────────────────────────────
+
+export interface FilterBarPresetProps extends Omit<FilterBarProps, 'children'> {
+  /**
+   * 行内区字段 — 放置高频筛选 FormField。
+   */
+  inlineFields: React.ReactNode;
+  /**
+   * 面板区字段 — 放置更多筛选 FormField,传入即显示展开按钮。
+   */
+  panelFields?: React.ReactNode;
+  /**
+   * 面板静态列数(走 Row/Col 24 栅格,被 `responsiveColumns` 覆盖)。
+   * @default 3
+   */
+  columns?: 1 | 2 | 3 | 4;
+  /**
+   * 面板响应式列数 — 标量或 5 档断点映射(base / xs / s / m / l / xl,
+   * 断点 432/672/944/1200/1600,对齐设计规范 §4.1)。优先级高于 `columns`。
+   *
+   * @example responsiveColumns={{ base: 1, xs: 2, m: 3, l: 4 }}
+   */
+  responsiveColumns?: ResponsiveValue<1 | 2 | 3 | 4>;
+  /**
+   * 搜索按钮文案。
+   * @default "搜索"
+   */
+  submitText?: string;
+  /**
+   * 重置按钮文案。
+   * @default "重置"
+   */
+  resetText?: string;
+}
+
+/**
+ * `FilterBarPreset` 预设组合 — 一个组件搞定行内搜索 + 可展开面板 + 栅格布局 + 按钮。
+ * 适用于标准列表页筛选场景,无需手动组合子组件。
+ */
+const FilterBarPreset = React.forwardRef<HTMLDivElement, FilterBarPresetProps>(
+  (
+    {
+      form,
+      inlineFields,
+      panelFields,
+      columns = 3,
+      responsiveColumns,
+      submitText = '搜索',
+      resetText = '重置',
+      ...filterBarProps
+    },
+    ref,
+  ) => {
+    return (
+      <FilterBar ref={ref} form={form} {...filterBarProps}>
+        <FilterBarSearch autoFilter={!panelFields}>
+          {inlineFields}
+          {panelFields && <FilterBarTrigger />}
+        </FilterBarSearch>
+        {panelFields && (
+          <FilterBarPanel
+            columns={columns}
+            responsiveColumns={responsiveColumns}
+          >
+            {panelFields}
+            <FilterBarActions submitText={submitText} resetText={resetText} />
+          </FilterBarPanel>
+        )}
+      </FilterBar>
+    );
+  },
+);
+FilterBarPreset.displayName = 'FilterBarPreset';
+
+// ─── Exports ─────────────────────────────────────────────────────────────────
+
+export {
+  FilterBar,
+  FilterBarSearch,
+  FilterBarTrigger,
+  FilterBarPanel,
+  FilterBarActions,
+  FilterBarPreset,
+  filterBarVariants,
+  useFilterBarContext,
+};