@teamix-evo/ui 0.4.0 → 0.5.0

package/src/components/field/field.tsx

@@ -1,392 +0,0 @@
-import * as React from 'react';
-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(分组的语义边框)────────────────────────────
-
-const FieldSet = React.forwardRef<
-  HTMLFieldSetElement,
-  React.FieldsetHTMLAttributes<HTMLFieldSetElement>
->(({ className, ...props }, ref) => (
-  <fieldset
-    ref={ref}
-    className={cn(
-      'flex flex-col gap-4 rounded-md border border-border bg-card p-4 disabled:cursor-not-allowed disabled:opacity-60',
-      className,
-    )}
-    {...props}
-  />
-));
-FieldSet.displayName = 'FieldSet';
-
-const FieldLegend = React.forwardRef<
-  HTMLLegendElement,
-  React.HTMLAttributes<HTMLLegendElement>
->(({ className, ...props }, ref) => (
-  <legend
-    ref={ref}
-    className={cn('px-1 text-sm font-medium leading-none', className)}
-    {...props}
-  />
-));
-FieldLegend.displayName = 'FieldLegend';
-
-// ─── FieldGroup(纵向排列多个 Field 的容器)──────────────────────────────
-
-/**
- * `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',
-      horizontal: 'flex-row items-start gap-4',
-    },
-  },
-  defaultVariants: { orientation: 'vertical' },
-});
-
-export interface FieldProps
-  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'>,
-    Omit<VariantProps<typeof fieldVariants>, 'orientation'> {
-  /**
-   * 字段方向 — 标量或 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?: 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;
-  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, 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';
-
-// ─── FieldLabel(label,继承 invalid 着色)──────────────────────────────
-
-export interface FieldLabelProps
-  extends React.ComponentPropsWithoutRef<typeof Label> {
-  /**
-   * 在 label 末尾追加 "*" 强调必填（antd Form `required` 并集）— 仅视觉，业务侧需在校验层确保必填。
-   * 顺序为 `文字 ⓘ *`，与 Label / FormLabel 保持一致。
-   * @default false
-   */
-  required?: boolean;
-}
-
-const FieldLabel = React.forwardRef<
-  React.ElementRef<typeof Label>,
-  FieldLabelProps
->(({ 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}
-      required={required}
-      style={mergedStyle}
-      maxWidth={maxWidth}
-      className={cn(
-        invalid && 'text-destructive',
-        // 启用了 maxWidth 时强制截断,保留 hover tooltip 由 Label 内置(若 tooltip prop 传入)
-        autoMaxWidth && 'truncate',
-        className,
-      )}
-      {...props}
-    >
-      {children}
-    </Label>
-  );
-});
-FieldLabel.displayName = 'FieldLabel';
-
-// ─── FieldDescription / FieldError ────────────────────────────────────
-
-const FieldDescription = React.forwardRef<
-  HTMLParagraphElement,
-  React.HTMLAttributes<HTMLParagraphElement>
->(({ className, ...props }, ref) => (
-  <p
-    ref={ref}
-    className={cn('text-xs text-muted-foreground', className)}
-    {...props}
-  />
-));
-FieldDescription.displayName = 'FieldDescription';
-
-const FieldError = React.forwardRef<
-  HTMLParagraphElement,
-  React.HTMLAttributes<HTMLParagraphElement>
->(({ className, children, ...props }, ref) => {
-  const { invalid } = React.useContext(FieldContext);
-  if (!invalid || !children) return null;
-  return (
-    <p
-      ref={ref}
-      role="alert"
-      className={cn('-mt-1 text-xs font-medium text-destructive', className)}
-      {...props}
-    >
-      {children}
-    </p>
-  );
-});
-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,
-  FieldDescription,
-  FieldError,
-  FieldGroup,
-  FieldSet,
-  FieldLegend,
-  FieldSection,
-  FieldActions,
-  fieldVariants,
-  useField,
-};

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

@@ -1,92 +0,0 @@
----
-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`（避免某个字段被拉伸过宽）