@teamix-evo/ui 0.4.0 → 0.5.0

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

@@ -1,568 +0,0 @@
-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,142 +0,0 @@
----
-id: flex
-name: Flex
-displayName: 弹性布局
-type: component
-category: layout
-since: 0.1.0
-package: '@teamix-evo/ui'
----
-
-# Flex 弹性布局
-
-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 的容器布局
-- 需要语义化 HTML 标签(`<header>` `<aside>` `<main>` `<nav>`)时用 `as`
-- 按钮组 / tag 组 / 表单 label-value 对 / 列表行末操作链接组(原 Space 场景 — 加 `inline`)
-- 多次重复的相同对齐组合(可以靠 Flex 收敛模板)
-
-## When NOT to use
-
-- 网格列分配 → `Grid`(`Row + Col`)
-- 按钮粘连共享边线 → `ButtonGroup`
-- 仅一次性自由布局 → 直接写 className 也行,不强求
-
-## Props
-
-<!-- auto:props:begin -->
-| 名称 | 类型 | 默认值 | 必填 | 说明 |
-| --- | --- | --- | --- | --- |
-| `direction` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | `"row"` | – | 方向(antd `vertical` 并集) — `row`(默认)/ `column` 直观可读;antd `vertical` boolean 映射为 `column`。 |
-| `gap` | `'none' \| 'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'` | `"default"` | – | 子项之间的间距档位(走 design 间距刻度,不接受任意 number)。 |
-| `align` | `keyof typeof alignMap` | `"stretch"` | – | 副轴对齐方式。 |
-| `justify` | `keyof typeof justifyMap` | `"start"` | – | 主轴对齐方式。 |
-| `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 -->
-### 同库依赖
-
-> `teamix-evo ui add flex` 时,以下 entry 会被自动连带安装(无需手动 add)。
-
-| Entry | 类型 | 描述 |
-| --- | --- | --- |
-| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
-
-### npm 依赖
-
-_无 — 本组件不依赖任何 npm 包。_
-<!-- auto:deps:end -->
-
-## AI 生成纪律
-
-- **`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">
-  <Dialog />
-</Flex>
-
-// 页头:logo + 导航 + 头像
-<Flex as="header" justify="between" align="center" className="border-b px-6 py-3">
-  <Logo />
-  <Nav />
-  <Avatar />
-</Flex>
-
-// 纵向卡片体
-<Flex direction="column" gap="sm" className="p-6">
-  <Title>标题</Title>
-  <Paragraph>正文...</Paragraph>
-  <Button>操作</Button>
-</Flex>
-
-// 工具栏(右对齐)
-<Flex justify="end" gap="sm">
-  <Button variant="outline">取消</Button>
-  <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>)}
-</Flex>
-```