@teamix-evo/ui 0.2.0 → 0.4.0

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

@@ -0,0 +1,1086 @@
+import * as React from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { useForm, FormProvider } from 'react-hook-form';
+// `as never` cast on zodResolver(...) below: zod 3.25.x ships zod v4
+// internals while @hookform/resolvers@3.x still types Resolver against
+// zod v3 Schema. Remove when upgrading to @hookform/resolvers v4.
+import { zodResolver } from '@hookform/resolvers/zod';
+import { z } from 'zod';
+import {
+  FilterBar,
+  FilterBarSearch,
+  FilterBarTrigger,
+  FilterBarPanel,
+  FilterBarActions,
+  FilterBarPreset,
+} from './filter-bar';
+import {
+  FormField,
+  FormItem,
+  FormLabel,
+  FormControl,
+  FormMessage,
+} from '@/components/form/form';
+import { Input } from '@/components/input/input';
+import { Select } from '@/components/select/select';
+import {
+  DatePicker,
+  DateRangePicker,
+} from '@/components/date-picker/date-picker';
+import type { DateRange } from 'react-day-picker';
+import { Switch } from '@/components/switch/switch';
+import { Checkbox } from '@/components/checkbox/checkbox';
+import { CheckboxGroup } from '@/components/checkbox/checkbox';
+import { RadioGroup } from '@/components/radio-group/radio-group';
+import { Button } from '@/components/button/button';
+
+// ─── Meta ────────────────────────────────────────────────────────────────────
+
+const meta: Meta<typeof FilterBar> = {
+  title: '数据录入 · Data Entry/FilterBar',
+  component: FilterBar,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          '筛选栏 —— 面向 Table/List 的筛选表单变体，行内实时筛选 + 可折叠高级面板栅格布局。Radix Collapsible 实现面板展开收起 + react-hook-form 表单状态管理 + Grid 栅格面板布局；对齐 SAP Fiori FilterBar 的 basic/advanced 双模式，补齐 antd-pro QueryFilter 的 inline/panel 实时触发与防抖能力：`form` / `defaultExpanded` / `onFilter` / `onReset` / `filterDebounce` / `columns`。视觉走 OpenTrek semantic tokens，所有样式来自 `@teamix-evo/tokens`，无 mock。',
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof FilterBar>;
+
+// ─── Story: InlineFilter ─────────────────────────────────────────────────────
+
+export const InlineFilter: Story = {
+  name: '行内筛选（实时触发）',
+  render: () => {
+    const form = useForm({
+      defaultValues: { keyword: '', status: '', enabled: false },
+    });
+    const [result, setResult] = React.useState<Record<string, any>>({});
+
+    return (
+      <div className="w-full space-y-4 p-6">
+        <FormProvider {...form}>
+          <FilterBar form={form} onFilter={setResult}>
+            <FilterBarSearch>
+              <FormField
+                control={form.control}
+                name="keyword"
+                render={({ field }) => (
+                  <FormItem className="flex-row items-center gap-2">
+                    <FormControl>
+                      <Input
+                        placeholder="搜索关键词..."
+                        className="w-48"
+                        {...field}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="status"
+                render={({ field }) => (
+                  <FormItem className="flex-row items-center gap-2">
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'running', label: '运行中' },
+                          { value: 'stopped', label: '已停止' },
+                          { value: 'error', label: '异常' },
+                        ]}
+                        placeholder="状态"
+                        value={field.value}
+                        onChange={field.onChange}
+                        className="w-36"
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="enabled"
+                render={({ field }) => (
+                  <FormItem className="flex-row items-center gap-2">
+                    <FormLabel className="text-xs">仅显示启用</FormLabel>
+                    <FormControl>
+                      <Switch
+                        checked={field.value}
+                        onCheckedChange={field.onChange}
+                        size="sm"
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+            </FilterBarSearch>
+          </FilterBar>
+        </FormProvider>
+        {Object.keys(result).length > 0 && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            onFilter: {JSON.stringify(result, null, 2)}
+          </pre>
+        )}
+      </div>
+    );
+  },
+};
+
+// ─── Story: WithPanel ────────────────────────────────────────────────────────
+
+export const WithPanel: Story = {
+  name: '行内 + 可展开面板',
+  render: () => {
+    const form = useForm({
+      defaultValues: {
+        keyword: '',
+        region: '',
+        org: '',
+        dateRange: undefined as DateRange | undefined,
+        tagGroup: '',
+        instanceId: '',
+        cpu: '',
+      },
+    });
+    const [result, setResult] = React.useState<Record<string, any>>({});
+
+    return (
+      <div className="w-full space-y-4 p-6">
+        <FormProvider {...form}>
+          <FilterBar
+            form={form}
+            onFilter={setResult}
+            onReset={() => setResult({})}
+          >
+            <FilterBarSearch autoFilter={false}>
+              <FormField
+                control={form.control}
+                name="keyword"
+                render={({ field }) => (
+                  <FormItem className="flex-row items-center gap-2">
+                    <FormControl>
+                      <Input
+                        placeholder="实例 ID / 名称"
+                        className="w-56"
+                        {...field}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FilterBarTrigger />
+            </FilterBarSearch>
+            <FilterBarPanel columns={3}>
+              <FormField
+                control={form.control}
+                name="dateRange"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>起止时间</FormLabel>
+                    <FormControl>
+                      <DateRangePicker
+                        value={field.value}
+                        onChange={field.onChange}
+                        placeholders={['起始日期', '结束日期']}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="org"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>组织</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'dev', label: '研发部' },
+                          { value: 'ops', label: '运维部' },
+                          { value: 'test', label: '测试部' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="tagGroup"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>标签选择组</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'web', label: 'Web 应用' },
+                          { value: 'api', label: 'API 服务' },
+                          { value: 'db', label: '数据库' },
+                          { value: 'cache', label: '缓存' },
+                        ]}
+                        placeholder="请选择或输入标签键或标签值"
+                        searchable
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="region"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>区域</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'cn-hangzhou', label: '华东1（杭州）' },
+                          { value: 'cn-shanghai', label: '华东2（上海）' },
+                          { value: 'cn-beijing', label: '华北2（北京）' },
+                          { value: 'cn-shenzhen', label: '华南1（深圳）' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="instanceId"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>实例 ID</FormLabel>
+                    <FormControl>
+                      <Input placeholder="输入实例 ID" {...field} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="cpu"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>CPU</FormLabel>
+                    <FormControl>
+                      <Input placeholder="输入 CPU 核数" {...field} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FilterBarActions />
+            </FilterBarPanel>
+          </FilterBar>
+        </FormProvider>
+        {Object.keys(result).length > 0 && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            onFilter: {JSON.stringify(result, null, 2)}
+          </pre>
+        )}
+      </div>
+    );
+  },
+};
+
+// ─── Story: PurePanel ────────────────────────────────────────────────────────
+
+export const PurePanel: Story = {
+  name: '纯面板模式（默认展开）',
+  render: () => {
+    const form = useForm({
+      defaultValues: {
+        startDate: undefined as Date | undefined,
+        org: '',
+        resourceGroup: [] as string[],
+        region: '',
+        instanceId: '',
+        enableMonitor: false,
+      },
+    });
+    const [result, setResult] = React.useState<Record<string, any>>({});
+
+    return (
+      <div className="w-full space-y-4 p-6">
+        <FormProvider {...form}>
+          <FilterBar
+            form={form}
+            defaultExpanded
+            onFilter={setResult}
+            onReset={() => setResult({})}
+          >
+            <FilterBarPanel columns={3}>
+              <FormField
+                control={form.control}
+                name="startDate"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel required>起始日期</FormLabel>
+                    <FormControl>
+                      <DatePicker
+                        value={field.value}
+                        onChange={field.onChange}
+                        placeholder="选择日期"
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="org"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel required>组织</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'dev', label: '研发部' },
+                          { value: 'ops', label: '运维部' },
+                          { value: 'test', label: '测试部' },
+                          { value: 'product', label: '产品部' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="resourceGroup"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>资源集</FormLabel>
+                    <FormControl>
+                      <CheckboxGroup
+                        options={[
+                          { value: 'ecs', label: 'ECS' },
+                          { value: 'rds', label: 'RDS' },
+                          { value: 'oss', label: 'OSS' },
+                          { value: 'slb', label: 'SLB' },
+                        ]}
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="region"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>区域</FormLabel>
+                    <FormControl>
+                      <RadioGroup
+                        orientation="horizontal"
+                        className="flex flex-row gap-4"
+                        options={[
+                          { value: 'cn-hangzhou', label: '杭州' },
+                          { value: 'cn-shanghai', label: '上海' },
+                          { value: 'cn-beijing', label: '北京' },
+                        ]}
+                        value={field.value}
+                        onValueChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="instanceId"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>实例 ID</FormLabel>
+                    <FormControl>
+                      <Input placeholder="输入实例 ID" {...field} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="enableMonitor"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>启用监控</FormLabel>
+                    <FormControl>
+                      <Switch
+                        checked={field.value}
+                        onCheckedChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FilterBarActions />
+            </FilterBarPanel>
+          </FilterBar>
+        </FormProvider>
+        {Object.keys(result).length > 0 && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            onFilter: {JSON.stringify(result, null, 2)}
+          </pre>
+        )}
+      </div>
+    );
+  },
+};
+
+// ─── Story: PresetUsage ──────────────────────────────────────────────────────
+
+export const PresetUsage: Story = {
+  name: 'FilterBarPreset 快捷用法',
+  render: () => {
+    const form = useForm({
+      defaultValues: {
+        keyword: '',
+        status: '',
+        dateRange: undefined as DateRange | undefined,
+        org: '',
+        region: '',
+        enableHA: false,
+      },
+    });
+    const [result, setResult] = React.useState<Record<string, any>>({});
+
+    const inlineFields = (
+      <>
+        <FormField
+          control={form.control}
+          name="keyword"
+          render={({ field }) => (
+            <FormItem className="flex-row items-center gap-2">
+              <FormControl>
+                <Input placeholder="搜索..." className="w-48" {...field} />
+              </FormControl>
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="status"
+          render={({ field }) => (
+            <FormItem className="flex-row items-center gap-2">
+              <FormControl>
+                <Select
+                  options={[
+                    { value: 'active', label: '活跃' },
+                    { value: 'inactive', label: '非活跃' },
+                    { value: 'archived', label: '已归档' },
+                  ]}
+                  placeholder="全部状态"
+                  value={field.value}
+                  onChange={field.onChange}
+                  className="w-36"
+                />
+              </FormControl>
+            </FormItem>
+          )}
+        />
+      </>
+    );
+
+    const panelFields = (
+      <>
+        <FormField
+          control={form.control}
+          name="dateRange"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>起止时间</FormLabel>
+              <FormControl>
+                <DateRangePicker
+                  value={field.value}
+                  onChange={field.onChange}
+                  placeholders={['起始日期', '结束日期']}
+                />
+              </FormControl>
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="org"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>组织</FormLabel>
+              <FormControl>
+                <Select
+                  options={[
+                    { value: 'dev', label: '研发部' },
+                    { value: 'ops', label: '运维部' },
+                    { value: 'test', label: '测试部' },
+                  ]}
+                  placeholder="请选择"
+                  value={field.value}
+                  onChange={field.onChange}
+                />
+              </FormControl>
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="region"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>区域</FormLabel>
+              <FormControl>
+                <Select
+                  options={[
+                    { value: 'cn-hangzhou', label: '华东1（杭州）' },
+                    { value: 'cn-shanghai', label: '华东2（上海）' },
+                    { value: 'cn-beijing', label: '华北2（北京）' },
+                  ]}
+                  placeholder="请选择"
+                  value={field.value}
+                  onChange={field.onChange}
+                />
+              </FormControl>
+            </FormItem>
+          )}
+        />
+        <FormField
+          control={form.control}
+          name="enableHA"
+          render={({ field }) => (
+            <FormItem>
+              <FormLabel>高可用</FormLabel>
+              <FormControl>
+                <Switch
+                  checked={field.value}
+                  onCheckedChange={field.onChange}
+                  checkedChildren="开"
+                  unCheckedChildren="关"
+                />
+              </FormControl>
+            </FormItem>
+          )}
+        />
+      </>
+    );
+
+    return (
+      <div className="w-full space-y-4 p-6">
+        <FormProvider {...form}>
+          <FilterBarPreset
+            form={form}
+            inlineFields={inlineFields}
+            panelFields={panelFields}
+            columns={3}
+            onFilter={setResult}
+            onReset={() => setResult({})}
+          />
+        </FormProvider>
+        {Object.keys(result).length > 0 && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            onFilter: {JSON.stringify(result, null, 2)}
+          </pre>
+        )}
+      </div>
+    );
+  },
+};
+
+// ─── Story: WithValidation ───────────────────────────────────────────────────
+
+const filterSchema = z.object({
+  keyword: z.string().optional(),
+  org: z.string().min(1, '请选择组织'),
+  region: z.string().optional(),
+  agreeTerms: z.literal(true, {
+    errorMap: () => ({ message: '请勾选同意条款' }),
+  }),
+});
+
+export const WithValidation: Story = {
+  name: '带 Zod 校验',
+  render: () => {
+    const form = useForm<z.infer<typeof filterSchema>>({
+      resolver: zodResolver(filterSchema as never),
+      defaultValues: {
+        keyword: '',
+        org: '',
+        region: '',
+        agreeTerms: false as unknown as true,
+      },
+    });
+    const [result, setResult] = React.useState<Record<string, any>>({});
+
+    return (
+      <div className="w-full space-y-4 p-6">
+        <FormProvider {...form}>
+          <FilterBar
+            form={form}
+            defaultExpanded
+            onFilter={setResult}
+            onReset={() => setResult({})}
+          >
+            <FilterBarPanel columns={3}>
+              <FormField
+                control={form.control}
+                name="keyword"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>关键词</FormLabel>
+                    <FormControl>
+                      <Input placeholder="搜索..." {...field} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="org"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel required>组织</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'dev', label: '研发部' },
+                          { value: 'ops', label: '运维部' },
+                          { value: 'test', label: '测试部' },
+                        ]}
+                        placeholder="必填"
+                        value={field.value}
+                        onChange={field.onChange}
+                        error={!!form.formState.errors.org}
+                      />
+                    </FormControl>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="region"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>区域</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'cn-hangzhou', label: '华东1（杭州）' },
+                          { value: 'cn-shanghai', label: '华东2（上海）' },
+                          { value: 'cn-beijing', label: '华北2（北京）' },
+                        ]}
+                        placeholder="可选"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="agreeTerms"
+                render={({ field }) => (
+                  <FormItem>
+                    <div className="flex items-center gap-2">
+                      <FormControl>
+                        <Checkbox
+                          checked={field.value}
+                          onCheckedChange={field.onChange}
+                        />
+                      </FormControl>
+                      <FormLabel>同意数据使用条款</FormLabel>
+                    </div>
+                    <FormMessage />
+                  </FormItem>
+                )}
+              />
+              <FilterBarActions />
+            </FilterBarPanel>
+          </FilterBar>
+        </FormProvider>
+        {Object.keys(result).length > 0 && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            onFilter: {JSON.stringify(result, null, 2)}
+          </pre>
+        )}
+      </div>
+    );
+  },
+};
+
+// ─── Story: Responsive ──────────────────────────────────────────────────────
+
+export const Responsive: Story = {
+  name: '响应式多栏（responsiveColumns）',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '传入 `responsiveColumns` 后面板切换为 CSS Grid 响应式布局。5 档断点对齐设计规范 §4.1: `base` <432 / `xs` ≥432 / `s` ≥672 / `m` ≥944 / `l` ≥1200 / `xl` ≥1600。拖动 viewport 观察 1 → 2 → 4 列切换。',
+      },
+    },
+  },
+  render: () => {
+    const form = useForm({
+      defaultValues: {
+        keyword: '',
+        org: '',
+        region: '',
+        status: '',
+        instanceId: '',
+        cpu: '',
+      },
+    });
+    const [result, setResult] = React.useState<Record<string, any>>({});
+
+    return (
+      <div className="w-full space-y-4 p-6">
+        <FormProvider {...form}>
+          <FilterBar
+            form={form}
+            defaultExpanded
+            onFilter={setResult}
+            onReset={() => setResult({})}
+          >
+            <FilterBarPanel
+              responsiveColumns={{ base: 1, xs: 2, m: 3, l: 4 }}
+            >
+              <FormField
+                control={form.control}
+                name="keyword"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>关键词</FormLabel>
+                    <FormControl>
+                      <Input placeholder="输入关键词" {...field} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="org"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>组织</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'dev', label: '研发部' },
+                          { value: 'ops', label: '运维部' },
+                          { value: 'test', label: '测试部' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="region"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>区域</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'cn-hangzhou', label: '华东1（杭州）' },
+                          { value: 'cn-shanghai', label: '华东2（上海）' },
+                          { value: 'cn-beijing', label: '华北2（北京）' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="status"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>状态</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'running', label: '运行中' },
+                          { value: 'stopped', label: '已停止' },
+                          { value: 'error', label: '异常' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="instanceId"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>实例 ID</FormLabel>
+                    <FormControl>
+                      <Input placeholder="输入实例 ID" {...field} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="cpu"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>CPU</FormLabel>
+                    <FormControl>
+                      <Input placeholder="输入 CPU 核数" {...field} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FilterBarActions />
+            </FilterBarPanel>
+          </FilterBar>
+        </FormProvider>
+        {Object.keys(result).length > 0 && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            onFilter: {JSON.stringify(result, null, 2)}
+          </pre>
+        )}
+      </div>
+    );
+  },
+};
+
+// ─── Story: RightAligned ─────────────────────────────────────────────────
+export const RightAligned: Story = {
+  name: 'Label 右对齐（labelAlign="right"）',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`labelAlign="right"` 将面板内所有 `<label>` 右对齐，适用于表单式筛选区。结合 `inputMaxWidth` 可得到经典右对齐表单视觉。',
+      },
+    },
+  },
+  render: () => {
+    const form = useForm({
+      defaultValues: { keyword: '', org: '', region: '', status: '' },
+    });
+    const [result, setResult] = React.useState<Record<string, any>>({});
+
+    return (
+      <div className="w-full space-y-4 p-6">
+        <FormProvider {...form}>
+          <FilterBar
+            form={form}
+            defaultExpanded
+            labelAlign="right"
+            onFilter={setResult}
+            onReset={() => setResult({})}
+          >
+            <FilterBarPanel columns={2}>
+              <FormField
+                control={form.control}
+                name="keyword"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>关键词</FormLabel>
+                    <FormControl>
+                      <Input placeholder="输入关键词" {...field} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="org"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>组织</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'dev', label: '研发部' },
+                          { value: 'ops', label: '运维部' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="region"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>区域</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'cn-hangzhou', label: '华东1（杭州）' },
+                          { value: 'cn-beijing', label: '华北2（北京）' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="status"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>运行状态</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'running', label: '运行中' },
+                          { value: 'stopped', label: '已停止' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FilterBarActions />
+            </FilterBarPanel>
+          </FilterBar>
+        </FormProvider>
+        {Object.keys(result).length > 0 && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            onFilter: {JSON.stringify(result, null, 2)}
+          </pre>
+        )}
+      </div>
+    );
+  },
+};
+
+// ─── Story: WithMaxWidth ─────────────────────────────────────────────────
+export const WithMaxWidth: Story = {
+  name: '输入域最大宽度（inputMaxWidth）',
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`inputMaxWidth` 为面板内每个输入域设置最大宽度（默认多栏 400px / 双栏 600px）。本例显式约束为 320px，防止输入域过宽。',
+      },
+    },
+  },
+  render: () => {
+    const form = useForm({
+      defaultValues: { keyword: '', org: '', region: '' },
+    });
+    const [result, setResult] = React.useState<Record<string, any>>({});
+
+    return (
+      <div className="w-full space-y-4 p-6">
+        <FormProvider {...form}>
+          <FilterBar
+            form={form}
+            defaultExpanded
+            inputMaxWidth={320}
+            onFilter={setResult}
+            onReset={() => setResult({})}
+          >
+            <FilterBarPanel columns={3}>
+              <FormField
+                control={form.control}
+                name="keyword"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>关键词</FormLabel>
+                    <FormControl>
+                      <Input placeholder="输入关键词" {...field} />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="org"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>组织</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'dev', label: '研发部' },
+                          { value: 'ops', label: '运维部' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FormField
+                control={form.control}
+                name="region"
+                render={({ field }) => (
+                  <FormItem>
+                    <FormLabel>区域</FormLabel>
+                    <FormControl>
+                      <Select
+                        options={[
+                          { value: 'cn-hangzhou', label: '华东1（杭州）' },
+                          { value: 'cn-shanghai', label: '华东2（上海）' },
+                        ]}
+                        placeholder="请选择"
+                        value={field.value}
+                        onChange={field.onChange}
+                      />
+                    </FormControl>
+                  </FormItem>
+                )}
+              />
+              <FilterBarActions />
+            </FilterBarPanel>
+          </FilterBar>
+        </FormProvider>
+        {Object.keys(result).length > 0 && (
+          <pre className="rounded-md bg-muted p-3 text-xs">
+            onFilter: {JSON.stringify(result, null, 2)}
+          </pre>
+        )}
+      </div>
+    );
+  },
+};