@teamix-evo/ui 0.4.0 → 0.5.0

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

@@ -0,0 +1,57 @@
+# FilterBar
+
+> 本文件由 `pnpm gen:meta` 自动生成，**请勿手动编辑**。
+
+## 描述
+
+筛选栏 FilterBar
+表格 / 列表页顶部的组合式筛选区域。形态由子组件组合决定：
+- `FilterBarHeader` 行内多字段并排（截图 1）
+- `FilterBarHeader` + `FilterBarTrigger` + `FilterBarContent` 行内+折叠面板（截图 2）
+- 仅 `FilterBarTrigger` + `FilterBarContent` 纯面板（截图 3）
+- `FilterBarSearch` 紧凑搜索条 + 高级筛选面板（截图 4 / 5）
+内置 react-hook-form `FormProvider`，行内字段防抖触发 `onFilter`，
+面板字段需点击搜索或 Enter 触发。
+
+## 使用场景
+
+- 列表页 / 表格页顶部多条件筛选
+- 需要 RHF 表单托管的查询区域
+- 需要"行内 + 高级筛选面板"两段式 UX
+
+## Props
+
+| 名称 | 类型 | 默认值 | 必填 | 说明 |
+| --- | --- | --- | --- | --- |
+| `form` | `UseFormReturn<TForm>` | – | ✓ | RHF 表单实例（必传），通常来自 `useForm()`。 |
+| `onFilter` | `SubmitHandler<TForm>` | – | – | 提交筛选回调（点击搜索 / 行内防抖 / Enter 触发）。 |
+| `onReset` | `() => void` | – | – | 重置回调（在 form.reset 之后触发）。 |
+| `onChange` | `(values: TForm) => void` | – | – | 表单值变化回调（任意字段变化即触发，未防抖）。 |
+| `onInit` | `(form: UseFormReturn<TForm>) => void` | – | – | 首次挂载回调，可在此调 `form.setValue` 注入异步默认值。 |
+| `defaultOpen` | `boolean` | `false` | – | 高级筛选面板默认是否展开。 |
+| `open` | `boolean` | – | – | 高级筛选面板展开状态（受控）。 |
+| `onOpenChange` | `(open: boolean) => void` | – | – | 展开状态变化回调。 |
+| `debounceMs` | `number` | `300` | – | 行内字段防抖触发 onFilter 的延迟（毫秒）。 |
+| `clearOnReset` | `boolean` | `false` | – | 重置时是否丢弃 defaultValues（true=完全清空）。 |
+| `autoFilter` | `boolean` | `false` | – | 是否在行内字段变化时自动触发 onFilter（防抖）。 |
+| `addonBefore` | `React.ReactNode` | – | – | Header 左侧槽位，常用于"+创建任务"等主操作按钮。 |
+| `addonAfter` | `React.ReactNode` | – | – | Header 右侧槽位，常用于⚙️等次要操作。 |
+| `columns` | `FilterBarColumns` | – | – | 面板栅格列数，默认 3。 |
+| `children` | `React.ReactNode` | – | – | – |
+| `exclusive` | `boolean` | `true` | – | 切换搜索字段时是否清空其它字段。 |
+| `children` | `React.ReactNode` | – | – | 三段 children：`FilterBarSearchKey` + `FilterBarSearchValue` + `FilterBarSearchAction`。 |
+| `options` | `FilterBarSearchOption[]` | – | ✓ | 可切换的字段选项。 |
+| `className` | `string` | – | – | – |
+| `placeholder` | `string` | – | – | 自定义 placeholder（缺省取 active option 的 placeholder 或「请输入{label}」）。 |
+| `columns` | `FilterBarColumns` | – | – | 覆盖 Root 的 columns 配置。 |
+| `children` | `React.ReactNode` | – | – | 自定义按钮组（完全替换默认「重置 + 搜索」）。 不传时默认渲染重置与搜索两按钮。 |
+| `name` | `TName` | – | ✓ | RHF 字段名。 |
+| `label` | `React.ReactNode` | – | – | 字段标签。outline 模式必填（主视觉元素）。 |
+| `description` | `React.ReactNode` | – | – | 字段说明（仅 vertical / horizontal 布局显示）。 |
+| `className` | `string` | – | – | 容器自定义 className。 |
+| `layout` | `FilterBarFieldLayout` | – | – | 布局模式。不传时按 section 推断：Header → `outline`；Content → `horizontal`。 - `inline`：label 左外 + 控件横向（控件自带边框） - `outline`：label 嵌入外框内左侧（控件去边框） - `vertical`：label 上 + 控件下 - `horizontal`：label 左外 + 控件右 |
+| `colSpan` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `1` | – | 占用栅格列数（仅 Content section 生效）。 |
+| `inlineMaxWidth` | `number` | `240` | – | Header 形态（inline / outline）下控件最大宽度（px）。 |
+| `control` | `Control<TForm>` | – | – | 显式指定 RHF control（默认从 FilterBar 上下文取）。 |
+| `children` | `React.ReactElement` | – | – | 静态 JSX 子元素（首选，AI 友好）。内部按子元素身份自动桥接 RHF field 到 `value`/`checked` + 对应 onChange。 适配 Input / Select / Checkbox / Switch / RadioGroup / Slider / Textarea； 不在适配表中的自定义控件请改用 `render` prop。 |
+| `render` | `(props: { field: ControllerRenderProps<TForm, TName>; fieldState: ControllerFieldState; formState: UseFormStateReturn<TForm>; }) => React.ReactElement` | – | – | 渲染输入控件（逆出舱，适配表不覆盖时使用）。 |

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

@@ -0,0 +1,496 @@
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import * as React from 'react';
+import { useForm } from 'react-hook-form';
+import { Plus, Settings2 } from 'lucide-react';
+
+import {
+  FilterBar,
+  FilterBarActions,
+  FilterBarContent,
+  FilterBarField,
+  FilterBarHeader,
+  FilterBarSearch,
+  FilterBarSearchAction,
+  FilterBarSearchKey,
+  FilterBarSearchValue,
+  FilterBarTrigger,
+} from '.';
+import { Button } from '@/components/button';
+import { Input } from '@/components/input';
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@/components/select';
+
+// Storybook dynamic source 会把完整 form 实例（RHF UseFormReturn）序列化出一大块内部字段，
+// 这里用括号配对算法将 `form={...}` 整体替换为可读的 `form={useForm()}` 占位。
+function stripFormProp(code: string): string {
+  const marker = 'form={';
+  const idx = code.indexOf(marker);
+  if (idx === -1) return code;
+  let depth = 0;
+  let i = idx + marker.length;
+  while (i < code.length) {
+    const ch = code[i];
+    if (ch === '{') depth++;
+    else if (ch === '}') {
+      if (depth === 0) {
+        return code.slice(0, idx) + 'form={useForm()}' + code.slice(i + 1);
+      }
+      depth--;
+    }
+    i++;
+  }
+  return code;
+}
+
+const meta: Meta<typeof FilterBar> = {
+  title: '数据录入 · Data Entry/FilterBar 筛选栏',
+  component: FilterBar,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      // 保留默认 dynamic source 生成，仅对 form prop 做可读化清洗。
+      source: {
+        transform: (code: string) => stripFormProp(code),
+      },
+      description: {
+        component:
+          '组合式筛选栏 — 由 `FilterBarHeader` / `FilterBarSearch`（三段 children：Key/Value/Action） / `FilterBarTrigger` / `FilterBarContent` / `FilterBarActions` / `FilterBarField` 组合，形态由 children 决定（不引入 mode）。`FilterBarField` 推荐用 children 静态 JSX 写法（自动桥接 RHF），逆出舱场景再用 `render` prop（ADR 0037 v2.1 + v2.2）。',
+      },
+    },
+  },
+  // form / 事件回调 / addon 等运行时 prop 不进控制面板与 Props 表
+  argTypes: {
+    form: { control: false, table: { disable: true } },
+    onFilter: { control: false, table: { disable: true } },
+    onReset: { control: false, table: { disable: true } },
+    onChange: { control: false, table: { disable: true } },
+    onInit: { control: false, table: { disable: true } },
+    onOpenChange: { control: false, table: { disable: true } },
+    addonBefore: { control: false, table: { disable: true } },
+    addonAfter: { control: false, table: { disable: true } },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof FilterBar>;
+
+// ─── 工具：业务字段 demo 数据 ───────────────────────────────────────────────
+
+// 说明：Radix Select 不允许 SelectItem.value 为空字符串（'' 被保留为“未选”语义）。
+// “全部” 状态交给 placeholder + Footer 重置按钮承载，不入选项表。
+const STATUS_OPTIONS = [
+  { value: 'running', label: '运行中' },
+  { value: 'stopped', label: '已停止' },
+  { value: 'error', label: '异常' },
+];
+
+const REGION_OPTIONS = [
+  { value: 'cn-hangzhou', label: '杭州' },
+  { value: 'cn-shanghai', label: '上海' },
+  { value: 'cn-beijing', label: '北京' },
+];
+
+const TYPE_OPTIONS = [
+  { value: 'ecs', label: 'ECS' },
+  { value: 'rds', label: 'RDS' },
+  { value: 'oss', label: 'OSS' },
+];
+
+function FilteredPreview({ values }: { values: Record<string, unknown> }) {
+  const printed = Object.entries(values)
+    .filter(([, v]) => v !== '' && v !== undefined && v !== null)
+    .map(([k, v]) => `${k}=${String(v)}`)
+    .join(' · ');
+  return (
+    <div className="mt-3 rounded-md bg-muted/40 px-3 py-2 text-xs text-muted-foreground">
+      <span className="text-foreground">当前筛选：</span>
+      {printed || '— 无 —'}
+    </div>
+  );
+}
+
+// ─── 1. Inline — 多字段并排实时筛选（截图 1） ───────────────────────────────
+
+export const Inline: Story = {
+  name: '1. 行内多字段（实时筛选）',
+  render: () => {
+    const form = useForm({
+      defaultValues: { status: '', region: '', keyword: '' },
+    });
+    const [filtered, setFiltered] = React.useState({});
+    return (
+      <div>
+        <FilterBar
+          form={form}
+          autoFilter
+          onFilter={(values) => setFiltered(values)}
+        >
+          <FilterBarHeader>
+            <FilterBarField name="status" label="状态">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {STATUS_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="region" label="地域">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {REGION_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="keyword" label="关键词">
+              <Input placeholder="请输入实例名称" />
+            </FilterBarField>
+          </FilterBarHeader>
+        </FilterBar>
+        <FilteredPreview values={filtered} />
+      </div>
+    );
+  },
+};
+
+// ─── 2. WithAdvancedPanel — 行内+折叠高级筛选（截图 2） ─────────────────────
+
+export const WithAdvancedPanel: Story = {
+  name: '2. 行内 + 高级筛选面板',
+  render: () => {
+    const form = useForm({
+      defaultValues: {
+        status: '',
+        region: '',
+        type: '',
+        keyword: '',
+        owner: '',
+        tag: '',
+      },
+    });
+    const [filtered, setFiltered] = React.useState({});
+    return (
+      <div>
+        <FilterBar
+          form={form}
+          columns={3}
+          onFilter={(values) => setFiltered(values)}
+        >
+          <FilterBarHeader>
+            <FilterBarField name="status" label="状态">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {STATUS_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="region" label="地域">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {REGION_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="keyword" label="关键词">
+              <Input placeholder="请输入" />
+            </FilterBarField>
+            <FilterBarTrigger />
+          </FilterBarHeader>
+          <FilterBarContent>
+            <FilterBarField name="type" label="类型">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {TYPE_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="owner" label="负责人">
+              <Input placeholder="请输入负责人" />
+            </FilterBarField>
+            <FilterBarField name="tag" label="标签">
+              <Input placeholder="请输入标签" />
+            </FilterBarField>
+            <FilterBarActions />
+          </FilterBarContent>
+        </FilterBar>
+        <FilteredPreview values={filtered} />
+      </div>
+    );
+  },
+};
+
+// ─── 3. PurePanel — 纯面板模式（截图 3 上） ─────────────────────────────────
+
+export const PurePanel: Story = {
+  name: '3. 纯面板模式',
+  render: () => {
+    const form = useForm({
+      defaultValues: { status: '', region: '', type: '', owner: '' },
+    });
+    const [filtered, setFiltered] = React.useState({});
+    return (
+      <div>
+        <FilterBar
+          form={form}
+          defaultOpen
+          columns={{ base: 2, md: 4 }}
+          onFilter={(values) => setFiltered(values)}
+        >
+          <FilterBarContent>
+            <FilterBarField name="status" label="状态">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {STATUS_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="region" label="地域">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {REGION_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="type" label="类型">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {TYPE_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="owner" label="负责人">
+              <Input placeholder="请输入" />
+            </FilterBarField>
+            <FilterBarActions />
+          </FilterBarContent>
+        </FilterBar>
+        <FilteredPreview values={filtered} />
+      </div>
+    );
+  },
+};
+
+// ─── 4. WithKeySearch — 紧凑模式（截图 4 / 5） ─────────────────────────────────
+
+export const WithKeySearch: Story = {
+  name: '4. 紧凑模式',
+  render: () => {
+    const form = useForm({
+      defaultValues: {
+        instanceId: '',
+        instanceName: '',
+        ip: '',
+        status: '',
+        region: '',
+        type: '',
+      },
+    });
+    const [filtered, setFiltered] = React.useState({});
+    return (
+      <div>
+        <FilterBar
+          form={form}
+          columns={3}
+          onFilter={(values) => setFiltered(values)}
+          addonBefore={
+            <Button>
+              <Plus />
+              创建任务
+            </Button>
+          }
+          addonAfter={
+            <Button variant="outline" aria-label="设置">
+              <Settings2 />
+            </Button>
+          }
+        >
+          <FilterBarHeader>
+            <FilterBarSearch className="w-80">
+              <FilterBarSearchKey
+                options={[
+                  { name: 'instanceId', label: '实例 ID' },
+                  { name: 'instanceName', label: '实例名称' },
+                  { name: 'ip', label: 'IP 地址' },
+                ]}
+              />
+              <FilterBarSearchValue />
+              <FilterBarSearchAction />
+            </FilterBarSearch>
+            <FilterBarTrigger />
+          </FilterBarHeader>
+          <FilterBarContent>
+            <FilterBarField name="status" label="状态">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {STATUS_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="region" label="地域">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {REGION_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="type" label="类型">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {TYPE_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarActions />
+          </FilterBarContent>
+        </FilterBar>
+        <FilteredPreview values={filtered} />
+      </div>
+    );
+  },
+};
+
+// ─── 5. CustomActions — 自定义按钮组（截图 5 上） ───────────────────────────
+
+export const CustomActions: Story = {
+  name: '5. 自定义按钮组',
+  render: () => {
+    const form = useForm({
+      defaultValues: { status: '', keyword: '' },
+    });
+    const [savedFilter, setSavedFilter] = React.useState<string | null>(null);
+    return (
+      <div>
+        <FilterBar
+          form={form}
+          onFilter={(values) =>
+            setSavedFilter(`筛选 → ${JSON.stringify(values)}`)
+          }
+        >
+          <FilterBarHeader>
+            <FilterBarField name="status" label="状态">
+              <Select>
+                <SelectTrigger className="w-full">
+                  <SelectValue placeholder="全部" />
+                </SelectTrigger>
+                <SelectContent>
+                  {STATUS_OPTIONS.map((o) => (
+                    <SelectItem key={o.value} value={o.value}>
+                      {o.label}
+                    </SelectItem>
+                  ))}
+                </SelectContent>
+              </Select>
+            </FilterBarField>
+            <FilterBarField name="keyword" label="关键词">
+              <Input placeholder="请输入" />
+            </FilterBarField>
+            <FilterBarActions>
+              <Button
+                type="button"
+                variant="outline"
+                onClick={() => form.reset()}
+              >
+                清空
+              </Button>
+              <Button
+                type="button"
+                variant="outline"
+                onClick={() =>
+                  setSavedFilter(`已保存 → ${JSON.stringify(form.getValues())}`)
+                }
+              >
+                保存条件
+              </Button>
+              <Button type="submit">立即查询</Button>
+            </FilterBarActions>
+          </FilterBarHeader>
+        </FilterBar>
+        <div className="mt-3 rounded-md bg-muted/40 px-3 py-2 text-xs text-muted-foreground">
+          <span className="text-foreground">最近动作：</span>
+          {savedFilter ?? '— 无 —'}
+        </div>
+      </div>
+    );
+  },
+};