@teamix-evo/ui 0.1.1 → 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,
+};

package/src/components/flex/flex.meta.md

@@ -1,28 +1,36 @@
 ---
 id: flex
 name: Flex
+displayName: 弹性布局
 type: component
 category: layout
 since: 0.1.0
-package: "@teamix-evo/ui"
+package: '@teamix-evo/ui'
 ---
 
-# Flex
+# Flex 弹性布局
 
-Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+),把 Tailwind flex 的常用配置(对齐 / 间距 / 换行 / 方向 / 渲染元素)收敛为枚举,避免散落的 `flex flex-col items-start gap-4 ...` 反复手写。
+Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+) ∪ **antd `Space`**——一个原子覆盖 layout 类目两个原子场景:
+
+- **完整布局容器**(页头 / 卡片体 / 整页): `<Flex as="header" justify="between" align="center" />`
+- **inline 小集合**(按钮组 / tag 组 / 链接组,等价 antd `Space`): `<Flex inline gap="sm" align="center" />`
+- **链接组带分隔**(等价 antd `Space.split`): `<Flex inline gap="sm" split={<Separator orientation="vertical" />} />`
 
 ## When to use
 
-- 完整页面 / 卡片 / Section 的容器布局
+- 页面 / 卡片 / Section 的容器布局
 - 需要语义化 HTML 标签(`<header>` `<aside>` `<main>` `<nav>`)时用 `as`
+- 按钮组 / tag 组 / 表单 label-value 对 / 列表行末操作链接组(原 Space 场景 — 加 `inline`)
 - 多次重复的相同对齐组合(可以靠 Flex 收敛模板)
 
 ## When NOT to use
 
-- 小集合 inline 间距 → `Space`
-- 网格 → `Grid`(`Row + Col`)
+- 网格列分配 → `Grid`(`Row + Col`)
+- 按钮粘连共享边线 → `ButtonGroup`
 - 仅一次性自由布局 → 直接写 className 也行,不强求
 
+## Props
+
 <!-- auto:props:begin -->
 | 名称 | 类型 | 默认值 | 必填 | 说明 |
 | --- | --- | --- | --- | --- |
@@ -33,8 +41,11 @@ Flex 布局容器 — antd 独有补足。**等价 antd `Flex`**(v5.10+),把 Tai
 | `wrap` | `boolean` | `false` | – | 是否允许换行(antd `wrap` 并集)。 |
 | `inline` | `boolean` | `false` | – | inline-flex 而非 block-flex。 |
 | `as` | `keyof Pick< React.JSX.IntrinsicElements, 'div' \| 'section' \| 'header' \| 'footer' \| 'aside' \| 'main' \| 'nav' \| 'article' >` | `"div"` | – | 渲染元素(antd `component` 并集) — 支持 `section / header / aside / main / nav` 等语义标签。 |
+| `split` | `React.ReactNode` | – | – | 子项之间的分隔节点(antd `Space.split` 并集) — 常用 `<Separator orientation="vertical" />`、`'·'`、`'\|'`。 设置后会在每两个相邻子项之间插入该节点。 |
 <!-- auto:props:end -->
 
+## 依赖
+
 <!-- auto:deps:begin -->
 ### 同库依赖
 
@@ -54,13 +65,37 @@ _无 — 本组件不依赖任何 npm 包。_
 - **`gap` 是档位枚举**(none / xs / sm / default / lg / xl),**不接受 number** — 走 design 间距刻度
 - **`direction="column"` 等价 antd `vertical`** — antd 的 `vertical={true}` 我们没沿用 boolean,直接走 direction 更直观
 - **`as` 仅限语义化标签集**(`section / header / aside / main / nav / footer / article / div`)— 不要传 `'span' / 'h1'` 等非 block 标签
+- **`inline` 是原 Space 的入口** — 表达 inline 小集合请加 `inline gap="sm" align="center"`,不要再去找 `Space`(已与 Flex 合并)
+- **`split` 应是无状态轻节点**(Separator / `|` / dot 字符),不要传 Button 等复杂组件,语义混乱
 - **不要嵌套 Flex 表达栅格** — 用 `Grid (Row/Col)`
 - **align/justify 默认值**:`align="stretch"`(子项填满高度)、`justify="start"`(主轴起始)— 大部分场景符合直觉
 
+## 从 antd `Space` 迁移
+
+v0.x 起 `Space` 已合并进 `Flex`。迁移 mapping(IDE 全局替换可解):
+
+```tsx
+// before
+<Space size="sm" align="center">…</Space>
+// after
+<Flex inline gap="sm" align="center">…</Flex>
+
+// before
+<Space split={<Separator orientation="vertical" />} size="sm">…</Space>
+// after
+<Flex inline gap="sm" align="center" split={<Separator orientation="vertical" />}>…</Flex>
+
+// before
+<Space direction="vertical" align="start">…</Space>
+// after
+<Flex direction="column" gap="sm" align="start">…</Flex>
+```
+
 ## Examples
 
 ```tsx
 import { Flex } from '@/components/ui/flex';
+import { Separator } from '@/components/ui/separator';
 
 // 居中对话框
 <Flex justify="center" align="center" className="min-h-screen">
@@ -87,6 +122,19 @@ import { Flex } from '@/components/ui/flex';
   <Button>提交</Button>
 </Flex>
 
+// inline 小集合(原 Space 场景)
+<Flex inline gap="sm" align="center">
+  <Button variant="outline">取消</Button>
+  <Button>确定</Button>
+</Flex>
+
+// 链接组 + split(原 Space.split 场景)
+<Flex inline gap="sm" align="center" split={<Separator orientation="vertical" className="h-4" />}>
+  <a href="#">查看</a>
+  <a href="#">编辑</a>
+  <a href="#">删除</a>
+</Flex>
+
 // 标签云
 <Flex wrap gap="sm">
   {tags.map((t) => <Tag key={t}>{t}</Tag>)}