@teamix-evo/ui 0.1.1 → 0.3.0

package/src/components/field/field.tsx

@@ -3,6 +3,16 @@ import { cva, type VariantProps } from 'class-variance-authority';
 
 import { cn } from '@/utils/cn';
 import { Label } from '@/components/label/label';
+import {
+  useBreakpoint,
+  pickByBreakpoint,
+  type ResponsiveValue,
+} from '@/hooks/use-breakpoint';
+
+// ─── 类型 ──────────────────────────────────────────────────────────────
+
+/** 输入域宽度档位 — 5 档系统，对应 104 / 216 / 328 / 440 / 552 px。 */
+export type InputWidth = 'xs' | 's' | 'm' | 'l' | 'xl';
 
 // ─── FieldSet / FieldLegend(分组的语义边框)────────────────────────────
 
@@ -13,7 +23,7 @@ const FieldSet = React.forwardRef<
   <fieldset
     ref={ref}
     className={cn(
-      'flex flex-col gap-4 rounded-md border bg-card p-4 disabled:cursor-not-allowed disabled:opacity-60',
+      'flex flex-col gap-4 rounded-md border border-border bg-card p-4 disabled:cursor-not-allowed disabled:opacity-60',
       className,
     )}
     {...props}
@@ -27,7 +37,7 @@ const FieldLegend = React.forwardRef<
 >(({ className, ...props }, ref) => (
   <legend
     ref={ref}
-    className={cn('px-1 text-sm font-semibold leading-none', className)}
+    className={cn('px-1 text-sm font-medium leading-none', className)}
     {...props}
   />
 ));
@@ -35,54 +45,121 @@ FieldLegend.displayName = 'FieldLegend';
 
 // ─── FieldGroup(纵向排列多个 Field 的容器)──────────────────────────────
 
-const FieldGroup = React.forwardRef<
-  HTMLDivElement,
-  React.HTMLAttributes<HTMLDivElement>
->(({ className, ...props }, ref) => (
-  <div ref={ref} className={cn('flex flex-col gap-4', className)} {...props} />
-));
+/**
+ * `FieldGroup` 行距密度 — 对齐《Teamix UI 表单设计规范》§3.5-3.6:
+ *   - `normal`(默认)20px 行距 — 标准表单与混合(详情+表单)模式
+ *   - `detail`        12px 行距 — 纯详情页(只展示不录入)
+ */
+export type FieldGroupDensity = 'normal' | 'detail';
+
+export interface FieldGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 行距密度。详情页用 `detail`(12px),其余(可编辑表单 / 部分展示+部分可编辑混合)用 `normal`(20px)。
+   * @default "normal"
+   */
+  density?: FieldGroupDensity;
+}
+
+const FieldGroup = React.forwardRef<HTMLDivElement, FieldGroupProps>(
+  ({ className, density = 'normal', ...props }, ref) => (
+    <div
+      ref={ref}
+      data-density={density}
+      className={cn(
+        'flex flex-col',
+        density === 'detail' ? 'gap-3' : 'gap-5',
+        className,
+      )}
+      {...props}
+    />
+  ),
+);
 FieldGroup.displayName = 'FieldGroup';
 
 // ─── Field(单个字段容器:Label + Control + Description + Error)────────
 
+export type FieldOrientation = 'vertical' | 'horizontal';
+
 const fieldVariants = cva('flex', {
   variants: {
     orientation: {
-      vertical: 'flex-col gap-1.5',
-      horizontal: 'flex-row items-start gap-3',
+      vertical: 'flex-col gap-1',
+      horizontal: 'flex-row items-start gap-4',
     },
   },
   defaultVariants: { orientation: 'vertical' },
 });
 
 export interface FieldProps
-  extends React.HTMLAttributes<HTMLDivElement>,
-    VariantProps<typeof fieldVariants> {
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,
+    Omit<VariantProps<typeof fieldVariants>, 'orientation'> {
   /**
-   * 字段方向 — `vertical`(默认)Label 在控件上;`horizontal` Label 在控件左侧(配长表单)。
+   * 字段方向 — 标量或 5 档断点响应式映射:
+   *   - `vertical`(默认)Label 在控件上;
+   *   - `horizontal` Label 在控件左侧(配长表单);
+   *   - 响应式对象 `{ base, xs, s, m, l, xl }` 按视口断点自动切换
+   *     (对齐设计规范 §4.2:单栏表单 < 432 应改上下结构)。
+   *
    * @default "vertical"
+   * @example orientation={{ base: 'vertical', xs: 'horizontal' }}  // <432 上下,≥432 左右
    */
-  orientation?: 'vertical' | 'horizontal';
+  orientation?: ResponsiveValue<FieldOrientation>;
   /**
    * 标记字段为 invalid — 子组件的 ring / 文字色会跟随;同时把内部 `<FieldError>` 渲染为可见。
    * @default false
    */
   invalid?: boolean;
+  /**
+   * 输入域宽度档位 — 5 档系统，对应 104 / 216 / 328 / 440 / 552 px。
+   * 通过 Context 下发，并在 Field 容器上注入 CSS 变量 `--field-input-width`，子组件可消费。
+   */
+  inputWidth?: InputWidth;
+  children?: React.ReactNode;
 }
 
-const FieldContext = React.createContext<{ invalid: boolean }>({ invalid: false });
+const FieldContext = React.createContext<{
+  invalid: boolean;
+  inputWidth?: InputWidth;
+  orientation: FieldOrientation;
+}>({ invalid: false, orientation: 'vertical' });
+
+/** 在受控/自定义子组件中读取当前 Field 的状态(invalid / inputWidth / 解析后的 orientation)。 */
+const useField = () => React.useContext(FieldContext);
 
 const Field = React.forwardRef<HTMLDivElement, FieldProps>(
-  ({ orientation, invalid = false, className, ...props }, ref) => (
-    <FieldContext.Provider value={{ invalid }}>
-      <div
-        ref={ref}
-        data-invalid={invalid ? '' : undefined}
-        className={cn(fieldVariants({ orientation }), className)}
-        {...props}
-      />
-    </FieldContext.Provider>
-  ),
+  (
+    { orientation, invalid = false, inputWidth, className, style, ...props },
+    ref,
+  ) => {
+    const currentBp = useBreakpoint();
+    const resolvedOrientation: FieldOrientation =
+      pickByBreakpoint(orientation, currentBp) ?? 'vertical';
+
+    return (
+      <FieldContext.Provider
+        value={{ invalid, inputWidth, orientation: resolvedOrientation }}
+      >
+        <div
+          ref={ref}
+          data-invalid={invalid ? '' : undefined}
+          data-orientation={resolvedOrientation}
+          className={cn(
+            fieldVariants({ orientation: resolvedOrientation }),
+            className,
+          )}
+          style={
+            {
+              ...(inputWidth
+                ? { '--field-input-width': `var(--input-width-${inputWidth})` }
+                : null),
+              ...style,
+            } as React.CSSProperties
+          }
+          {...props}
+        />
+      </FieldContext.Provider>
+    );
+  },
 );
 Field.displayName = 'Field';
 
@@ -91,7 +168,8 @@ Field.displayName = 'Field';
 export interface FieldLabelProps
   extends React.ComponentPropsWithoutRef<typeof Label> {
   /**
-   * 在 label 末尾追加 "*" 强调必填(antd Form `required` 并集) — 仅视觉,业务侧需在校验层确保必填。
+   * 在 label 末尾追加 "*" 强调必填（antd Form `required` 并集）— 仅视觉，业务侧需在校验层确保必填。
+   * 顺序为 `文字 ⓘ *`，与 Label / FormLabel 保持一致。
    * @default false
    */
   required?: boolean;
@@ -100,20 +178,38 @@ export interface FieldLabelProps
 const FieldLabel = React.forwardRef<
   React.ElementRef<typeof Label>,
   FieldLabelProps
->(({ required = false, className, children, ...props }, ref) => {
-  const { invalid } = React.useContext(FieldContext);
+>(({ required = false, className, style, maxWidth, children, ...props }, ref) => {
+  const { invalid, inputWidth, orientation } = React.useContext(FieldContext);
+
+  // horizontal 模式下,Label 默认 maxWidth = ⅓ 输入域宽(对齐规范 §七 "Label 最大宽 ⅓");
+  // 业务显式传 maxWidth 仍优先。inputWidth 未设时退化为 ⅓ 容器宽(100%/3)。
+  const autoMaxWidth =
+    orientation === 'horizontal' && maxWidth === undefined
+      ? inputWidth
+        ? `calc(var(--input-width-${inputWidth}) / 3)`
+        : '33.333%'
+      : undefined;
+
+  const mergedStyle: React.CSSProperties = {
+    ...(autoMaxWidth && { maxWidth: autoMaxWidth }),
+    ...style,
+  };
+
   return (
     <Label
       ref={ref}
-      className={cn(invalid && 'text-destructive', className)}
+      required={required}
+      style={mergedStyle}
+      maxWidth={maxWidth}
+      className={cn(
+        invalid && 'text-destructive',
+        // 启用了 maxWidth 时强制截断,保留 hover tooltip 由 Label 内置(若 tooltip prop 传入)
+        autoMaxWidth && 'truncate',
+        className,
+      )}
       {...props}
     >
       {children}
-      {required ? (
-        <span aria-hidden="true" className="ml-0.5 text-destructive">
-          *
-        </span>
-      ) : null}
     </Label>
   );
 });
@@ -143,7 +239,7 @@ const FieldError = React.forwardRef<
     <p
       ref={ref}
       role="alert"
-      className={cn('text-xs font-medium text-destructive', className)}
+      className={cn('-mt-1 text-xs font-medium text-destructive', className)}
       {...props}
     >
       {children}
@@ -152,6 +248,135 @@ const FieldError = React.forwardRef<
 });
 FieldError.displayName = 'FieldError';
 
+// ─── FieldSection(带可选标题的字段分组)────────────────────────────────
+
+export interface FieldSectionProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** 组标题 — 14px medium，有值时渲染标题行；多个 FieldSection 之间应由父容器提供 32px 间距(gap-8)。 */
+  title?: React.ReactNode;
+  /**
+   * 多栏 grid 列数 — 留空走 `flex-col`(单列纵向);设值时切到 CSS Grid,
+   * 列内 4px(`gap-x-4`)、行间 20px(`gap-y-5`,对齐规范 §3.1 规则 4)。
+   * @default undefined
+   */
+  columns?: 1 | 2 | 3 | 4;
+}
+
+const FieldSection = React.forwardRef<HTMLDivElement, FieldSectionProps>(
+  ({ title, columns, className, children, ...props }, ref) => (
+    <div ref={ref} className={cn('flex flex-col gap-5', className)} {...props}>
+      {title ? (
+        <h3 className="text-sm font-medium leading-none">{title}</h3>
+      ) : null}
+      {columns && columns > 1 ? (
+        <div
+          className={cn(
+            'grid gap-x-4 gap-y-5',
+            columns === 2 && 'grid-cols-2',
+            columns === 3 && 'grid-cols-3',
+            columns === 4 && 'grid-cols-4',
+          )}
+        >
+          {children}
+        </div>
+      ) : (
+        children
+      )}
+    </div>
+  ),
+);
+FieldSection.displayName = 'FieldSection';
+
+// ─── FieldActions(表单底部操作区)──────────────────────────────────────
+
+/**
+ * 按钮容器场景 — 对齐《Teamix UI 表单设计规范》§六:
+ *   - `page`         页面基础/分组表单:跟随表单流(`inline`)、左对齐、与输入域基线对齐
+ *   - `page-stepper` 页面分步表单:吸底(`sticky`)、左对齐、不基线对齐(离侧导 24px 留给业务定 className)
+ *   - `modal`        弹窗:跟随(`inline`)、右对齐、不基线对齐
+ *   - `drawer`       抽屉:吸底(`sticky`)、左对齐、不基线对齐
+ *
+ * 显式 `position` / `align` / `alignWithInput` 优先级高于 `container` 推导。
+ */
+export type FieldActionsContainer = 'page' | 'page-stepper' | 'modal' | 'drawer';
+
+const CONTAINER_DEFAULTS: Record<
+  FieldActionsContainer,
+  { position: 'inline' | 'sticky'; align: 'start' | 'end'; alignWithInput: boolean }
+> = {
+  page: { position: 'inline', align: 'start', alignWithInput: true },
+  'page-stepper': { position: 'sticky', align: 'start', alignWithInput: false },
+  modal: { position: 'inline', align: 'end', alignWithInput: false },
+  drawer: { position: 'sticky', align: 'start', alignWithInput: false },
+};
+
+export interface FieldActionsProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * 容器场景预设 — 一次性配齐 `position` / `align` / `alignWithInput`,
+   * 对齐设计规范 §六按容器分类的按钮位置规则。显式传入的同名 prop 优先。
+   *
+   * @example container="modal"   // 弹窗:inline + end + 不基线对齐
+   * @example container="drawer"  // 抽屉:sticky + start + 不基线对齐
+   */
+  container?: FieldActionsContainer;
+  /**
+   * 定位模式 — `inline` 跟随表单流；`sticky` 吸附在容器底部并带顶部分割线与背景。
+   * 未设时由 `container` 推导,默认 `inline`。
+   */
+  position?: 'inline' | 'sticky';
+  /**
+   * 对齐方向 — `end` 右对齐(主操作在右,弹窗默认);`start` 左对齐(页面/抽屉默认)。
+   * 未设时由 `container` 推导,默认 `end`。
+   */
+  align?: 'start' | 'end';
+  /**
+   * 与输入域基线对齐 — 水平表单(Field `orientation="horizontal"`)时预留 label 列宽度,
+   * 让按钮起点对齐输入框左边界(对齐设计规范 §六 "基础/分组表单按钮跟随基线对齐")。
+   * 通过 CSS 变量 `--form-label-width` 读取列宽,默认 `33.333%`(对齐规范 §七 label max ⅓)。
+   * 未设时由 `container` 推导,默认 `false`(仅 `container="page"` 时默认 `true`)。
+   */
+  alignWithInput?: boolean;
+}
+
+const FieldActions = React.forwardRef<HTMLDivElement, FieldActionsProps>(
+  (
+    { container, position, align, alignWithInput, className, style, ...props },
+    ref,
+  ) => {
+    const preset = container ? CONTAINER_DEFAULTS[container] : undefined;
+    const resolvedPosition = position ?? preset?.position ?? 'inline';
+    const resolvedAlign = align ?? preset?.align ?? 'end';
+    const resolvedAlignWithInput =
+      alignWithInput ?? preset?.alignWithInput ?? false;
+
+    const mergedStyle: React.CSSProperties = {
+      // 基线对齐用 inline style 表达 calc + CSS var(Tailwind arbitrary value 触 lint
+      // 且无法表达 calc 嵌套 var,inline 是规范允许的例外)
+      ...(resolvedAlignWithInput && {
+        paddingLeft: 'calc(var(--form-label-width, 33.333%) + 0.75rem)',
+      }),
+      ...style,
+    };
+
+    return (
+      <div
+        ref={ref}
+        data-container={container}
+        style={mergedStyle}
+        className={cn(
+          'flex gap-2 pt-4',
+          resolvedPosition === 'sticky' &&
+            'sticky bottom-0 border-t border-border bg-background py-4',
+          resolvedAlign === 'end' ? 'justify-end' : 'justify-start',
+          className,
+        )}
+        {...props}
+      />
+    );
+  },
+);
+FieldActions.displayName = 'FieldActions';
+
 export {
   Field,
   FieldLabel,
@@ -160,5 +385,8 @@ export {
   FieldGroup,
   FieldSet,
   FieldLegend,
+  FieldSection,
+  FieldActions,
   fieldVariants,
+  useField,
 };

package/src/components/filter-bar/filter-bar.meta.md

@@ -0,0 +1,92 @@
+---
+id: filter-bar
+name: FilterBar
+displayName: 筛选栏
+type: component
+category: data-entry
+since: 0.1.0
+package: '@teamix-evo/ui'
+---
+
+# FilterBar 筛选栏
+
+筛选栏 — 面向 Table/List 上方的筛选表单变体，支持行内实时筛选 + 可折叠高级面板栅格布局。混合式架构：复合子组件自由组合 + FilterBarPreset 开箱即用。
+
+## When to use
+
+- 列表页/表格上方需要筛选数据
+- 条件较少时行内实时触发（inline 模式）
+- 条件较多时需要展开面板叠加筛选（panel 模式）
+- 需要搜索 + 重置按钮的标准筛选场景
+
+## When NOT to use
+
+- 全局搜索框 → 用 `Input` + `Command`
+- 侧栏持久筛选面板（永久可见） → 直接用 `Form` + `Card` 自行布局
+- 单字段快速搜索 → 用 `Input` 配 `onKeyDown`
+
+## Props
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成。FilterBar 是复合组件，下表按子组件分节列出各自的 Props。
+
+<!-- auto:props:begin -->
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `form` | `UseFormReturn<any>` | – | ✓ | react-hook-form 实例 — 由 `useForm()` 创建,管理所有筛选字段的状态。 |
+| `defaultExpanded` | `boolean` | `false` | – | 面板是否默认展开。 |
+| `onFilter` | `(values: Record<string, any>) => void` | – | – | 筛选回调 — inline 模式防抖后触发,或面板模式点"搜索"按钮触发。 |
+| `onReset` | `(values: Record<string, any>) => void` | – | – | 重置回调 — 点"重置"按钮后触发,参数为重置后的表单值。 |
+| `filterDebounce` | `number` | `300` | – | inline 区 onChange 事件的防抖时间(ms)。 |
+| `labelAlign` | `'left' \| 'right'` | `'left'` | – | Label 对齐模式 — 右对齐仅适用于筛选区短标签。 |
+| `inputMaxWidth` | `number` | `undefined` | – | 输入域最大宽度(px) — 未设时走默认推断: 多栏(≥3 列)为 400，单栏/双栏为 600。 |
+<!-- auto:props:end -->
+
+## 依赖
+
+> 以下表格由 `pnpm --filter @teamix-evo/ui gen:meta` 自动生成,数据源是 [`manifest.json`](../../../manifest.json)。**手工编辑 marker 之间的内容会在下次生成时被覆盖**。
+
+<!-- auto:deps:begin -->
+### 同库依赖
+
+> `teamix-evo ui add filter-bar` 时,以下 entry 会被自动连带安装(无需手动 add)。
+
+| Entry | 类型 | 描述 |
+| --- | --- | --- |
+| `cn` | util | Tailwind className 合并工具(clsx + tailwind-merge) |
+| `button` | component | 通用按钮 — shadcn 实现 + cloud-design 能力并集(loading / icon / shape / block / dashed variant / color 语义双 prop / disabledTooltip)。同文件合一导出 ButtonGroup + ButtonGroupText(等价 antd Space.Compact + cd SplitButton)。 |
+| `form` | component | 表单 — react-hook-form + shadcn 7 件套(FormField/FormItem/Label/Control/Description/Message),配 zod 做 schema 校验 |
+| `grid` | component | 24 栅格(Row + Col) — antd 独有补足。等价 antd Row + Col,基于 CSS Grid 的 24 列容器,支持 span / offset / order / flex / gutter / justify / align |
+| `collapsible` | component | 单区域展开收起 — Radix Collapsible 薄包装(shadcn-only) |
+| `use-debounce-callback` | hook | 防抖回调 hook — 返回一个防抖包装后的函数，在指定 delay 毫秒内连续调用只执行最后一次 |
+| `use-breakpoint` | hook | 响应式断点 hook + pickByBreakpoint 工具 — 5 档断点(432/672/944/1200/1600,对齐《Teamix UI 表单设计规范》§4.1),给 Field 响应式 orientation / FilterBarPanel 响应式列数共用 |
+
+### npm 依赖
+
+> 业务侧需要先 `pnpm add` / `npm install` 这些包。CLI 在 `ui add` 完成后会列出此提示。
+
+```bash
+pnpm add lucide-react@^0.460.0 class-variance-authority@^0.7.0 @radix-ui/react-collapsible@^1.1.0
+```
+<!-- auto:deps:end -->
+
+## 新增 Props 说明
+
+除上表中的核心 FilterBar Props 外，本轮补充以下骨架能力：
+
+- **`FilterBar.labelAlign`**：`'left' \| 'right'`，label 在 horizontal 模式下的对齐方式。默认 `'left'`；短标签成片场景可用 `'right'` 对齐 input。
+- **`FilterBar.inputMaxWidth`**：`number`，统一限制 FilterBar 内控件的最大宽度（px），避免多栏下某列过宽拉伸。
+- **`FilterBarPanel.responsiveColumns`**：`ResponsiveValue<1 \| 2 \| 3 \| 4>`,5 档断点映射(对齐《Teamix UI 表单设计规范》§4.1):`base` < 432 / `xs` ≥ 432 / `s` ≥ 672 / `m` ≥ 944 / `l` ≥ 1200 / `xl` ≥ 1600。优先级高于 `columns`。底层走 `useBreakpoint` hook + JS 计算 grid-template-columns,不依赖客户 Tailwind 配置。示例:`responsiveColumns={{ base: 1, xs: 2, m: 3, l: 4 }}`。
+
+## AI 生成纪律
+
+- **FilterBar 必须接受 form 实例**：`<FilterBar form={form}>...</FilterBar>`，由外部 `useForm()` 创建
+- **筛选字段必须走 FormField**：无论 inline 还是 panel 内的字段，都必须用 `<FormField name="..." control={form.control} render={...} />`
+- **FilterBarPanel 内字段自动栅格**：直接放 FormItem 即可，Panel 会自动用 Row/Col 包裹
+- **不要在 FilterBarSearch 和 FilterBarPanel 放同名字段**：两个区域的字段名必须唯一，否则会冲突
+- **inline 模式不要放 FilterBarActions**：行内区自动防抖触发 onFilter，不需要搜索按钮
+- **面板模式推荐关闭 autoFilter**：有面板时设置 `<FilterBarSearch autoFilter={false}>`，筛选由 FilterBarActions 的搜索按钮统一触发
+- **重置会清空所有字段**：`form.reset()` 清空所有默认值之外的数据，包括 inline 和 panel
+- **FilterBarPreset 是快捷方式**：如果标准布局满足需求，优先用 FilterBarPreset 而非手动组合子组件
+- ✅ 需要响应式时使用 `responsiveColumns`（5 档断点 base/xs/s/m/l/xl,不要用 `columns` + 手写媒体查询或 `lg:grid-cols-*`）
+- ✅ 右对齐 label 仅适用于短标签筛选区（`labelAlign="right"`），长标签不要用;**viewport < 432px 自动改左对齐**(避免上下结构时 label 右贴反直觉,组件已内置响应式联动)
+- ✅ 多栏筛选建议设置 `inputMaxWidth`（避免某个字段被拉伸过宽）