@tfdesign/b-end 1.0.12 → 1.0.13

package/src/_b_end_runtime/components.js

@@ -9,6 +9,7 @@
 // AvatarGroup：同一语境下「多人」的缩略表达（固定 5 人交叠），不做可配人数列表头。
 // Icon：装饰性或功能性矢量符号（按钮内、列表前缀、空状态），不承担「人像」语义。
 // Button：触发提交/打开弹窗/行内操作等离散动作；不负责「切换同页多块内容」。
+// Filter：筛选栏中的单个筛选胶囊/筛选触发器；传入 options 时内置多选下拉面板。
 // Tabs：同一容器内多块平级内容的视图切换（不离开当前页）；不负责路由级站点导航。
 // Input：用户自造字符串（名称、搜索词、备注）；选项来自固定枚举时不要用 Input 冒充选择器。
 // Select：从较多或会增长的枚举里选一个/多选（tag 模式）；选项很少且需一眼比较时用 Radio。
@@ -570,6 +571,30 @@ const TAG_PREVIEW = {
   },
 };
 
+const FILTER_PREVIEW = {
+  state: {
+    outline: { bgColor: '#FFFFFF', borderColor: '#E4E7EC', textColor: '#182230' },
+    fill: { bgColor: 'rgba(83, 96, 143, 0.07)', borderColor: '#E4E7EC', textColor: '#182230' },
+    selected: { bgColor: '#EAFAF6', borderColor: '#87DEC9', textColor: '#129683' },
+    disabled: { bgColor: '#F9FAFB', borderColor: '#E6E7EA', textColor: '#98A2B3' },
+    selectedDisabled: { bgColor: '#EAFAF6', borderColor: '#A8E8D7', textColor: '#87DEC9' },
+  },
+  base: {
+    height: '36px',
+    paddingLeft: '12px',
+    paddingRight: '12px',
+    paddingY: 'auto',
+    gap: '8px',
+    borderRadius: '9999px',
+    fontSize: '14px',
+    lineHeight: '20px',
+    labelWeight: '600',
+    valueWeight: '400',
+    iconSize: '12px',
+    clearIconSize: '16px',
+  },
+};
+
 const TAGINPUT_PREVIEW = {
   status: {
     default: { bgColor: '#FFFFFF', borderColor: 'rgba(45,66,107,0.12)', hoverBorderColor: '#D0D5DD', focusBorderColor: '#56D3BC' },
@@ -1610,7 +1635,7 @@ export const COMPONENTS = [
       '【消息原子】一个 ChatMessage = AI 对话页中的一条消息原子，role="ai" 渲染 AI 消息（适配容器宽度），role="user" 渲染用户气泡（右对齐 + 8% 容器宽度左缩进 ≈ 500px 容器下 40px 缩进）',
       '【AI 友好命名】props 一律用最短同义词：header / thinking / plan / confirms / followUps / actions / userContent；读 props 即知 DOM 结构（<ChatMessage header thinking plan ... />）',
       '【7 类子组件】内部按 AI 头像 / 文本回复 / 执行流 / 卡片回复 / 深度思考 / 操作栏 / 用户气泡 7 类子组件按需组合，全部通过 props 启用，互相正交不冲突',
-      '【theme 必引】入口 CSS 必须 @import "@tf-designsystem/b-end/theme.css"。ChatMessage 子区块使用 --color-border-default、--color-neutral、--color-neutral-500/300/700、--tfds-ai-execution-* 等；未引入 theme 时 var() 无效，描边易退化为浏览器默认深黑（追问按钮等）。',
+      '【theme 必引】入口 CSS 必须 @import "@tfdesign/b-end/theme.css"。ChatMessage 子区块使用 --color-border-default、--color-neutral、--color-neutral-500/300/700、--tfds-ai-execution-* 等；未引入 theme 时 var() 无效，描边易退化为浏览器默认深黑（追问按钮等）。',
       '【禁止手搓描边】勿包一层 div 并加 border-black / ring-black；追问 followUps 为白底 + border-border-default + hover:border-border-strong。',
 
       /* —— 1. AI 头像 —— */
@@ -3220,6 +3245,72 @@ export const COMPONENTS = [
       'span rounded bg-', '手搓 Tag', '自制状态标签', 'px-2 py-1 bg-red-100',
     ],
   },
+  {
+    id: 'filter',
+    name: 'Filter',
+    element: 'div',
+    category: 'basic',
+    description:
+      '筛选胶囊项：用于筛选栏中的单个筛选触发器或已选条件展示，36px 高、全圆角、标签 semibold + 值 regular。支持点击展开下拉面板、多选、白底常态、填充态、品牌选中态、禁用态和可清除态。',
+    componentFile: './components/Filter.jsx',
+    tokensFile: './components/Filter.tokens.js',
+    props: [
+      { name: 'label', type: 'string', default: '筛选项' },
+      { name: 'value', type: 'string|number|null', default: null },
+      { name: 'options', type: 'array', default: [] },
+      { name: 'selectedValues', type: 'array', default: undefined },
+      { name: 'defaultValue', type: 'array', default: [] },
+      { name: 'onChange', type: 'function', default: null },
+      { name: 'selected', type: 'boolean', default: false },
+      { name: 'filled', type: 'boolean', default: false },
+      { name: 'disabled', type: 'boolean', default: false },
+      { name: 'closable', type: 'boolean', default: false },
+      { name: 'onClear', type: 'function', default: null },
+      { name: 'className', type: 'string', default: '' },
+    ],
+    labels: {
+      selected: { true: '选中', false: '未选中' },
+      filled: { true: '填充态', false: '白底态' },
+      closable: { true: '清除图标', false: '下拉箭头' },
+      disabled: { true: '禁用', false: '可交互' },
+    },
+    _preview: FILTER_PREVIEW,
+    rules: [
+      FONT_WEIGHT_RUNTIME_RULE,
+      '【定位】Filter 是筛选栏中的单个胶囊触发器/已选筛选项，不是完整筛选条；完整筛选区域由多个 Filter 横向组合。',
+      '【选型·vs Tag】Tag 是展示型短标签，不承载打开筛选面板；Filter 可点击、可打开筛选面板、可展示筛选值和清除入口。',
+      '【选型·vs Button】Filter 只用于筛选条件选择/收起/清除；普通动作（提交、取消、导出、新建）仍使用 Button。',
+      '【尺寸】固定高度 36px（--size-control-md），左右内距 12px（--spacing-3，对齐 Select md），内容 gap 8px（--spacing-2）；不要随意压缩为 24px 或 32px，以保证和 B 端 Input/Select 默认高度对齐。',
+      '【文字】label 使用 semibold 600，value 使用 normal 400；文案建议 label 2-6 字、value 1-8 字，过长值应在业务层截断或改用 Tooltip。',
+      '【下拉多选】传入 options 后点击胶囊展开下拉面板；支持 selectedValues 受控、defaultValue 非受控、onChange(nextValues) 回调；点击外部或 Escape 关闭。',
+      '【值展示】未显式传 value 时，单选中展示选项 label，多选中展示“已选 N 项”；显式 value 优先用于自定义展示。',
+      '【状态】selected=true 使用品牌浅底 + 品牌描边 + 品牌文字；filled=true 使用中性填充底；disabled=true 使用禁用文字与禁用底，且不可点击。',
+      '【图标】无选中值时显示 12px 下拉箭头；closable=true 或已选中且未禁用时显示 16px 清除按钮（视觉与 Select 清除入口一致），点击清空多选值、关闭下拉并触发 onClear，不触发展开。',
+      '【语义结构】外层使用 role="combobox/button" 的 div 触发器，避免清除 button 嵌套在 button 内；不要改回 button 包 button 的非法 DOM。',
+      '【组合】有值但仍可展开修改时传 options；已选条件需要一键移除时使用 closable 或依赖默认已选清除入口。',
+      '【禁止手搓】不要用 div/span + rounded-full 自行拼筛选 chip；筛选入口统一使用 Filter 保证 token、字重、焦点态与禁用态一致。',
+    ],
+    examples: [
+      { label: '基础筛选项', code: '<Filter label="筛选项" />' },
+      { label: '多选下拉', code: '<Filter label="筛选项" options={[{ label: "选项一", value: "1" }, { label: "选项二", value: "2" }]} />' },
+      { label: '默认已选', code: '<Filter label="筛选项" options={options} defaultValue={["1"]} />' },
+      { label: '受控多选', code: '<Filter label="筛选项" options={options} selectedValues={values} onChange={setValues} />' },
+      { label: '选中态', code: '<Filter label="筛选项" options={options} defaultValue={["1"]} selected />' },
+      { label: '填充态', code: '<Filter label="筛选项" filled />' },
+      { label: '可清除', code: '<Filter label="筛选项" options={options} defaultValue={["1"]} filled closable onClear={() => {}} />' },
+      { label: '选中可清除', code: '<Filter label="筛选项" options={options} defaultValue={["1"]} selected closable onClear={() => {}} />' },
+      { label: '禁用态', code: '<Filter label="筛选项" disabled />' },
+      { label: '禁用选中态', code: '<Filter label="筛选项" options={options} defaultValue={["1"]} selected disabled />' },
+      { label: '❌ Bad（手搓筛选 chip）', code: '/* 禁止！筛选入口不要手写 span/div */\n<span className="rounded-full border px-4 py-2">筛选项</span>' },
+      { label: '✅ Good（用 Filter）', code: '<Filter label="筛选项" options={options} defaultValue={["1"]} selected />' },
+    ],
+    keywords: [
+      'Filter', 'filter', '筛选', '筛选项', '筛选组件', '筛选胶囊', '筛选 chip',
+      '筛选触发器', '已选筛选', '过滤条件', 'filter item', 'filter chip', 'pill filter',
+      'closable', 'clear', '清除筛选', '下拉筛选', '多选筛选', 'selected filter',
+      'span rounded-full border', '手搓筛选', '自制筛选 chip',
+    ],
+  },
   {
     id: 'toast',
     name: 'Toast',

package/src/_b_end_runtime/page-patterns/McpManagementPage.jsx

@@ -34,7 +34,20 @@ import {
  */
 
 const PAGE_TITLE = 'MCP 工具管理';
-const MCP_FILTERS = ['MCP 类型', '创建人', '状态'];
+const MCP_FILTERS = [
+  {
+    label: 'MCP 类型',
+    options: ['数据接入', '画像服务', '订单服务', '营销服务', '推荐服务', '策略服务'],
+  },
+  {
+    label: '创建人',
+    options: ['林小北', '陈一诺', '周知远', '顾清禾'],
+  },
+  {
+    label: '状态',
+    options: ['已启用', '调试中', '已停用', '审核中'],
+  },
+];
 const MCP_TAGBAR_WIDTH_LIMITS = {
   initial: 260,
   min: 200,

package/src/_b_end_runtime/page-patterns/StrategyListPage.jsx

@@ -1,6 +1,7 @@
 import { useState } from 'react';
 import Modal from '../components/Modal';
 import Button from '../components/Button';
+import Filter from '../components/Filter';
 import Icon from '../components/Icon';
 import Input from '../components/Input';
 import Table from '../components/Table';
@@ -93,7 +94,20 @@ const MOCK_STRATEGIES = [
   },
 ];
 
-const STRATEGY_FILTERS = ['管理员', '发布状态', '策略类型'];
+const STRATEGY_FILTERS = [
+  {
+    label: '管理员',
+    options: ['林小北', '陈一诺', '周知远', '顾清禾'],
+  },
+  {
+    label: '发布状态',
+    options: ['线上生效', '实验中', '暂未生效', '草稿中', '已发布'],
+  },
+  {
+    label: '策略类型',
+    options: ['账号服务', '权益申诉', '账号处罚', '举报处理', '售后协同'],
+  },
+];
 
 export default function StrategyListPage() {
   const [expandedId, setExpandedId] = useState('experience-1');
@@ -170,19 +184,12 @@ function StrategyFilterBar({ filters = [] }) {
       <Input
         placeholder="搜索"
         prefix={<Icon name="search-md-stroked" />}
-        className="max-w-full"
-        style={{ flex: '0 1 240px', width: '240px', minWidth: '200px', '--size-input-width': '100%' }}
+        className="shrink-0"
+        style={{ flex: '0 0 240px', '--size-input-width': '240px' }}
       />
 
-      {filters.map((label) => (
-        <button
-          key={label}
-          type="button"
-          className="inline-flex h-8 shrink-0 cursor-pointer items-center gap-2 rounded-full border border-border-default bg-white px-3 text-sm [font-weight:var(--font-semibold)] text-blueGrey-800 transition-colors duration-150 hover:bg-fill"
-        >
-          <span>{label}</span>
-          <Icon name="chevron-down-stroked" className="text-blueGrey-600" />
-        </button>
+      {filters.map((item) => (
+        <Filter key={item.label} {...item} />
       ))}
     </div>
   );

package/src/_b_end_runtime/page-patterns/TabTopBarListPage.jsx

@@ -26,7 +26,20 @@ import { FilterBar, WHITE_CARD_STYLE } from './pageListShared';
  */
 
 const SCENE_LABEL = '渠道切换';
-const FILTERS = ['知识类型', '创建人', '状态'];
+const FILTERS = [
+  {
+    label: '知识类型',
+    options: ['QA', '文档', '案例'],
+  },
+  {
+    label: '创建人',
+    options: ['林小北', '陈一诺', '周知远', '顾清禾'],
+  },
+  {
+    label: '状态',
+    options: ['生效', '已发布', '草稿', '审核中', '已停用'],
+  },
+];
 const DETAIL_WIDTH = 'min(460px, 40vw)';
 
 /* 状态 → Tag 颜色变体（Tag.variant） */

package/src/_b_end_runtime/page-patterns/VariableManagementPage.jsx

@@ -16,7 +16,7 @@ import {
  *
  * 模板结构（自上而下）：
  *   · 标题栏：左侧竖条 + 标题 + 业务上下文胶囊 + 右侧"新建变量"按钮
- *   · 筛选栏：搜索框 + 下拉筛选胶囊 + Checkbox"我创建的"
+ *   · 筛选栏：搜索框 + 标准 Filter 下拉筛选项
  *   · 表格：列定义共享自 pageListShared
  *
  * 业务接入：
@@ -25,7 +25,20 @@ import {
  */
 
 const PAGE_TITLE = '变量管理';
-const VARIABLE_FILTERS = ['变量类型', '创建人', '流程引用'];
+const VARIABLE_FILTERS = [
+  {
+    label: '变量类型',
+    options: ['String', 'Number', 'Boolean', 'Enum'],
+  },
+  {
+    label: '创建人',
+    options: ['林小北', '陈一诺', '周知远', '顾清禾'],
+  },
+  {
+    label: '流程引用',
+    options: ['已引用', '未引用'],
+  },
+];
 
 const VARIABLE_DATA = [
   { name: 'user_id', tag: 'String', desc: '当前对话用户的统一标识，登录态自动注入。' },

package/src/_b_end_runtime/page-patterns/pageListShared.jsx

@@ -6,7 +6,7 @@
  * 业务接入时只需替换数据源（list）和文案配置（标题/筛选项/按钮）。
  */
 
-import Checkbox from '../components/Checkbox';
+import Filter from '../components/Filter';
 import FormTitle from '../components/FormTitle';
 import Icon from '../components/Icon';
 import Input from '../components/Input';
@@ -45,6 +45,15 @@ const STATUS_OPTIONS = [
   { label: '审核中', tone: 'warning' },
 ];
 
+const DEFAULT_FILTER_OPTIONS = {
+  创建人: TEAM_MEMBERS.slice(0, 4).map((member) => ({ label: member.name, value: member.name })),
+  状态: STATUS_OPTIONS.map((item) => ({ label: item.label, value: item.label })),
+  '我创建的': [
+    { label: '是', value: 'yes' },
+    { label: '否', value: 'no' },
+  ],
+};
+
 const UPDATED_AT_POOL = [
   '2026-04-21 10:30:00',
   '2026-04-20 18:45:00',
@@ -68,6 +77,36 @@ function makeStatus(index) {
   return STATUS_OPTIONS[index % STATUS_OPTIONS.length];
 }
 
+function fallbackFilterOptions(label) {
+  return ['选项一', '选项二', '选项三'].map((suffix) => ({
+    label: `${label}${suffix}`,
+    value: `${label}-${suffix}`,
+  }));
+}
+
+function getFilterOptions(label, options) {
+  if (Array.isArray(options) && options.length > 0) return options;
+  return DEFAULT_FILTER_OPTIONS[label] || fallbackFilterOptions(label);
+}
+
+function normalizeFilterItem(item) {
+  if (typeof item === 'string') {
+    return {
+      label: item,
+      options: getFilterOptions(item),
+    };
+  }
+
+  if (!item || typeof item !== 'object') return null;
+  const label = item.label;
+  if (!label) return null;
+
+  return {
+    ...item,
+    options: getFilterOptions(label, item.options),
+  };
+}
+
 /**
  * 把"业务原始数据"批量套上 mock 的创建人 / 状态 / 更新时间 / 操作按钮，
  * 形成 Table 可直接消费的 dataSource。
@@ -127,51 +166,30 @@ export function PageHeader({ title, contextLabel, actions }) {
 
 /**
  * 筛选栏（白卡内、标题栏之下）
- * 结构：左侧 300px 搜索框 + 一组 FilterPill（白底圆角胶囊 + 文字 + 下拉箭头）
- *       + 1 个 Checkbox 胶囊"我创建的"。
+ * 结构：左侧固定 240px 搜索框 + 一组标准 Filter 基础组件
+ *       + 1 个标准 Filter"我创建的"。
  *
- * @param {string[]} filters — 下拉筛选项的标签文案数组
- * @param {string} [checkboxLabel='我创建的'] — 末尾 Checkbox 胶囊文案；传 null 则隐藏
+ * @param {Array<string|{label:string,options?:Array}>} filters — 下拉筛选项配置
+ * @param {string} [checkboxLabel='我创建的'] — 末尾"我创建的"筛选项文案；传 null 则隐藏
  */
 export function FilterBar({ filters = [], checkboxLabel = '我创建的' }) {
+  const filterItems = filters.map(normalizeFilterItem).filter(Boolean);
+  const ownerFilter = checkboxLabel
+    ? normalizeFilterItem({ label: checkboxLabel, options: DEFAULT_FILTER_OPTIONS[checkboxLabel] })
+    : null;
+
   return (
     <div className="flex items-center shrink-0 flex-wrap" style={{ gap: '8px' }}>
       <Input
         placeholder="搜索"
         prefix={<Icon name="search-md-stroked" />}
-        className="max-w-full"
-        style={{ flex: '0 1 240px', width: '240px', minWidth: '200px', '--size-input-width': '100%' }}
+        className="shrink-0"
+        style={{ flex: '0 0 240px', '--size-input-width': '240px' }}
       />
-      {filters.map((label) => (
-        <FilterPill key={label} label={label} />
+      {filterItems.map((item) => (
+        <Filter key={item.label} {...item} />
       ))}
-      {checkboxLabel && <FilterCheckPill label={checkboxLabel} />}
-    </div>
-  );
-}
-
-/* 单个筛选触发器：白底 + 描边 + 圆角胶囊 + 文字 + chevron */
-function FilterPill({ label }) {
-  return (
-    <button
-      type="button"
-      className="inline-flex items-center shrink-0 cursor-pointer bg-white rounded-full border border-border-default text-sm font-semibold text-blueGrey-800 hover:bg-fill transition-colors duration-150"
-      style={{ height: '32px', padding: '0 12px', gap: '8px' }}
-    >
-      <span>{label}</span>
-      <Icon name="chevron-down-stroked" className="text-blueGrey-600" />
-    </button>
-  );
-}
-
-/* Checkbox 类型的筛选项：白底圆角胶囊里嵌一个 Checkbox */
-function FilterCheckPill({ label }) {
-  return (
-    <div
-      className="inline-flex items-center shrink-0 bg-white rounded-full border border-border-default"
-      style={{ height: '32px', padding: '0 12px' }}
-    >
-      <Checkbox size="md">{label}</Checkbox>
+      {ownerFilter && <Filter key={ownerFilter.label} {...ownerFilter} />}
     </div>
   );
 }

package/src/_b_end_runtime/patterns.js

@@ -121,7 +121,7 @@ export default function CustomerServicePage() {
       '【NavBar】通过 navItems 自定义菜单项（id / label / iconName），通过 selectedItemId 高亮当前菜单；菜单 id 与右侧模板一一对应',
       '【列表页结构】标题栏 → 筛选栏 → 表格，垂直 16px 间距，与白卡四边各 24px 边距',
       '【标题栏·FormTitle】新写页面时白卡顶栏主标题必须用 `<FormTitle variant="level-1" title="…" />`（默认不显示副标题），标题旁状态/数量 Tag 用 `titleSuffix` 贴主标题；与右侧主按钮同一行用 `flex items-start justify-between gap-3` 组合；左侧标题区 `min-w-[120px] flex-1`，右侧操作区 `shrink-0 flex-wrap`，**禁止**再手写竖条 + `h2`，也禁止把标题挤成竖排。`pageListShared.jsx` 中的 `PageHeader` 仅为既有模板实现参考。',
-      '【筛选栏】搜索 Input 与筛选项同栏时不要撑满整行，默认使用约 240px 的中等宽度（空间不足再换行）；后接多个 FilterPill（白底圆角胶囊 + 文字 + chevron）+ 末尾 Checkbox 胶囊"我创建的"；项与项之间 8px、整体 36px 高、wrap 多行容错',
+      '【筛选栏】搜索 Input 必须和 Filter 在同一 flex 行，默认固定 240px（`flex: 0 0 240px` + `--size-input-width: 240px`），禁止 `--size-input-width: 100%` / `flex-1` / `w-full` 撑满整行；后接多个带 options 的标准 `<Filter />` 基础组件，包含"我创建的"也必须使用 Filter；项与项之间 8px、整体 36px 高、wrap 多行容错，禁止再手写 FilterPill / Checkbox 胶囊 / rounded-full 筛选按钮',
       '【表单宽度判断】所有 form 类型组件都要按字段语义决定宽度，而不是统一 `w-full`：搜索/短关键词=中宽；枚举筛选/状态/时间范围=窄到中宽；名称/标题=中到宽；描述/备注/多行文本=宽或全宽；多值标签输入按内容与容器宽度决定',
       '【双白卡变体】当列表需要左侧维度筛选（如按分类树过滤）时，在主白卡左侧再加一张**独立白圆角辅助大卡**包住 `TagBar`。该类“横向并列的大卡工作区”默认就要支持宽度拖拽：左卡用 `width + onWidthChange + minWidth + maxWidth + resizable`，外层保持 `overflow-visible` 以露出拖拽把手，右侧主卡保持 `flex-1 min-w-0` 弹性撑满；两白卡间距 8px。**勿**用 `tone="panel"` 代替白卡（panel 为浅灰侧条，不是白卡片）。参见 McpManagementPage',
       '【多白卡分区（通用）】当页面右侧需要多个业务板块时，必须拆分为多个独立白卡（而不是一整张通栏白底背景）。推荐：灰底内容区外层统一用 `padding: 16px` 或等价 `margin: 16px` 外框节奏；框架层最外层白卡统一 `纯白背景 + 12px 圆角`，不加浅灰描边；白卡之间 `gap: 8px`；白卡内部布局用 `padding: 24px` + `gap: 16px`（参见 VariableManagementPage / McpManagementPage）。内部卡片、列表项、表单控件原有边框/描边保持不变。',
@@ -207,7 +207,7 @@ export default function MyPage({ defaultSelectedItemId = 'example-1' }) {
       '【反例扫描】如果同一右侧首页函数里同时出现 `ChatInput`、模板 `Card` 网格，并且外层存在 `background: var(--color-surface)` / `bg-surface rounded-*` 包住 Hero + 输入框 + Tabs + 网格，说明 AI 把入口页误生成成白卡管理页，必须拆掉这层 wrapper。',
       '【框架不动】外框灰底 + 左侧 `NavBar` 固定不变；右侧内容区必须 `flex-1 min-w-0 min-h-0 overflow-y-auto overflow-x-hidden`，由右侧内容区作为唯一滚动容器承载整体页面滚动；Hero、ChatInput、筛选行、卡片网格要一起被滑动，禁止只让下方卡片列表单独 `overflow-y-auto`。',
       '【Hero 区】居中欢迎标题 + 最大宽 680px 的 ChatInput 直接坐浅灰底；Hero 主标题使用 `text-4xl leading-10`；默认使用 `ChatInput variant="default"` 作为入口主输入；标准节奏为 `padding: 84px 40px 80px`，标题区较旧版整体上移 36px。标题区副标题与 ChatInput 之间必须保留 48px 间距（比普通标题说明节奏额外增加 24px），保证输入框不贴近标题区。AI 渐变只用于输入框内部 / AI 标识，不作为整块 Hero 白底。',
-      '【筛选与分类】分类切换必须用 `Tabs size="sm"`；筛选行 `padding: 16px 40px`，左 Tabs、右搜索。模板/助手搜索框是辅助筛选入口，不是页面主输入，必须固定宽度并自动对齐到页面右侧：用外层 `<div className="ml-auto shrink-0" style={{ flex: "0 0 240px", width: "240px", minWidth: "240px", maxWidth: "240px" }}>` 包裹 `Input`。注意 Input 组件的 `style` 会透传到原生 input，不要把固定宽直接写在 Input 上；Tabs 外层使用 `flex shrink-0` 保持左侧胶囊 Tabs 可见。筛选行容器禁止使用 `flex-wrap`、`justify-between`、`space-y-*`、`flex-col`；禁止让筛选搜索框 `flex-1`、`w-full`、撑满 Tabs 右侧剩余空间，或换到 Tabs 下方单独占一行。',
+      '【筛选与分类】分类切换必须用 `Tabs size="sm"`；筛选行 `padding: 16px 40px`，左 Tabs、右搜索。模板/助手搜索框是辅助筛选入口，不是页面主输入，必须固定宽度并自动对齐到页面右侧：可用外层 `<div className="ml-auto shrink-0" style={{ flex: "0 0 240px", width: "240px", minWidth: "240px", maxWidth: "240px" }}>` 包裹 `Input`，也可直接给 `Input` 传 `style={{ flex: "0 0 240px", "--size-input-width": "240px" }}`；`Input` 的 `style` 作用于根容器。Tabs 外层使用 `flex shrink-0` 保持左侧胶囊 Tabs 可见。筛选行容器禁止使用 `flex-wrap`、`justify-between`、`space-y-*`、`flex-col`；禁止让筛选搜索框 `flex-1`、`w-full`、撑满 Tabs 右侧剩余空间，或换到 Tabs 下方单独占一行。',
       '【卡片列表】使用自适应 grid（优先 `repeat(auto-fit, minmax(min(320px, 100%), 1fr))`），网格 `gap-4`，禁止固定列宽导致窄屏横向溢出；卡片使用 `Card color="white"`；列表区域作为普通内容块跟随右侧页面整体滚动，使用 `shrink-0` + `padding: 0 40px 40px`，禁止在卡片列表自身设置 `overflow-y-auto` 造成只有卡片区滚动。',
       '【内容可扩展】Tab 项数量和卡片数据替换为业务真实数据；卡片 stats/tags 按业务维度自定义',
     ],

package/src/_b_end_runtime/preview-registry.jsx

@@ -37,6 +37,7 @@ import DatePicker from './components/DatePicker';
 import TimePicker from './components/TimePicker';
 import Toast from './components/Toast';
 import Tag from './components/Tag';
+import Filter from './components/Filter';
 import TagInput from './components/TagInput';
 import TagGridPreview from './components/TagGridPreview';
 import TablePreview, {
@@ -77,6 +78,7 @@ import { DATEPICKER_TOKEN_MAP } from './components/DatePicker.tokens';
 import { TIMEPICKER_TOKEN_MAP } from './components/TimePicker.tokens';
 import { TOAST_TOKEN_MAP } from './components/Toast.tokens';
 import { TAG_TOKEN_MAP } from './components/Tag.tokens';
+import { FILTER_TOKEN_MAP } from './components/Filter.tokens';
 import { TAGINPUT_TOKEN_MAP } from './components/TagInput.tokens';
 import { TABLE_TOKEN_MAP } from './components/Table.tokens';
 import { TOOLTIP_TOKEN_MAP } from './components/Tooltip.tokens';
@@ -112,6 +114,7 @@ import datePickerJsxRaw from './components/DatePicker.jsx?raw';
 import timePickerJsxRaw from './components/TimePicker.jsx?raw';
 import toastJsxRaw from './components/Toast.jsx?raw';
 import tagJsxRaw from './components/Tag.jsx?raw';
+import filterJsxRaw from './components/Filter.jsx?raw';
 import tagInputJsxRaw from './components/TagInput.jsx?raw';
 import tableJsxRaw from './components/Table.jsx?raw';
 import tooltipJsxRaw from './components/Tooltip.jsx?raw';
@@ -136,6 +139,37 @@ function SwitchPreview({ variant = 'brand', defaultChecked, disabled }) {
   );
 }
 
+const FILTER_SAMPLE_OPTIONS = [
+  { label: '选项一', value: 'option-1' },
+  { label: '选项二', value: 'option-2' },
+  { label: '选项三', value: 'option-3' },
+  { label: '禁用项', value: 'option-4', disabled: true },
+];
+
+function FilterPreview({
+  initial = 'empty',
+  disabled = false,
+}) {
+  const [singleValues, setSingleValues] = useState(
+    initial === 'selected' ? ['option-1'] : [],
+  );
+
+  useEffect(() => {
+    setSingleValues(initial === 'selected' ? ['option-1'] : []);
+  }, [initial]);
+
+  return (
+    <Filter
+      label="筛选项"
+      options={FILTER_SAMPLE_OPTIONS}
+      selectedValues={singleValues}
+      onChange={setSingleValues}
+      disabled={disabled}
+      onClear={() => {}}
+    />
+  );
+}
+
 const FORM_CONTROL_PREVIEW_WIDTH_STYLE = {
   width: 'min(300px, 100%)',
   maxWidth: '100%',
@@ -4158,6 +4192,67 @@ export const PREVIEW_REGISTRY = {
     },
   },
 
+  filter: {
+    component: FilterPreview,
+    tokenMap: FILTER_TOKEN_MAP,
+    jsxSource: filterJsxRaw,
+
+    getPreviewAreaStyle: () => ({
+      alignItems: 'center',
+      justifyContent: 'center',
+      overflow: 'auto',
+      padding: '32px',
+    }),
+
+    controls: [
+      {
+        id: 'initial',
+        label: '初始值',
+        type: 'seg',
+        options: [
+          { id: 'empty', label: '空' },
+          { id: 'selected', label: '已选' },
+        ],
+        default: 'empty',
+      },
+      {
+        id: 'state',
+        label: '交互',
+        type: 'seg',
+        options: [
+          { id: 'default', label: '可点' },
+          { id: 'disabled', label: '禁用' },
+        ],
+        default: 'default',
+      },
+    ],
+
+    mapProps: (cv) => ({
+      initial: cv.initial || 'empty',
+      disabled: cv.state === 'disabled',
+    }),
+
+    generateUsage: (_enums, cv) => {
+      const lines = [`import Filter from './components/Filter';`];
+      const props = ['label="筛选项"'];
+      props.push('options={options}');
+      if ((cv.initial || 'empty') === 'selected') props.push('defaultValue={["option-1"]}');
+      if (cv.state === 'disabled') props.push('disabled');
+
+      lines.push('');
+      lines.push('const options = [');
+      lines.push('  { label: "选项一", value: "option-1" },');
+      lines.push('  { label: "选项二", value: "option-2" },');
+      lines.push('  { label: "选项三", value: "option-3" },');
+      lines.push('];');
+      lines.push('');
+      lines.push('<Filter');
+      props.forEach((p) => lines.push(`  ${p}`));
+      lines.push('/>');
+      return lines.join('\n');
+    },
+  },
+
   'tag-input': {
     component: TagInputPreview,
     tokenMap: TAGINPUT_TOKEN_MAP,

package/src/index.d.ts

@@ -951,6 +951,33 @@ export interface TagProps extends TfdsCommonProps {
 }
 export const Tag: React.FC<TagProps>;
 
+/** Filter — 筛选胶囊项：用于筛选栏中的单个筛选触发器或已选条件展示，36px 高、全圆角、标签 semibold + 值 regular。支持点击展开下拉面板、多选、白底常态、填充态、品牌选中态、禁用态和可清除态。 */
+export interface FilterProps extends TfdsCommonProps {
+  /** string, default: "筛选项" */
+  label?: string;
+  /** string|number|null, default: null */
+  value?: unknown;
+  /** array, default: [] */
+  options?: unknown[];
+  /** array, default: undefined */
+  selectedValues?: unknown[];
+  /** array, default: [] */
+  defaultValue?: unknown[];
+  /** function, default: null */
+  onChange?: (...args: any[]) => any;
+  /** boolean, default: false */
+  selected?: boolean;
+  /** boolean, default: false */
+  filled?: boolean;
+  /** boolean, default: false */
+  disabled?: boolean;
+  /** boolean, default: false */
+  closable?: boolean;
+  /** function, default: null */
+  onClear?: (...args: any[]) => any;
+}
+export const Filter: React.FC<FilterProps>;
+
 /** Toast — 轻量反馈条：信息/成功/警示/错误四态，左侧状态图标（相对行首额外 4px 左边距）+ 主文案 + 可选文字操作（绿色文字 Button）+ 可关闭；宽度随内容收缩（w-fit），最大不超过 min(100%,560px)；圆角 12px、可选语义描边（bordered）、内距 12px、主文案 14px 半粗，行内纵向居中对齐。规范仅覆盖单条条目视觉；全局队列、停留时长与 Portal 由业务集成（对齐 HiUI Toast）。 */
 export interface ToastProps extends TfdsCommonProps {
   /** enum<info | success | warning | error>, default: "info" */

package/src/index.js

@@ -1,5 +1,5 @@
 /**
- * @tf-designsystem/b-end 公开 API（由 scripts/generate-tfds-b-end-bundle.mjs 生成，勿手改）
+ * @tfdesign/b-end 公开 API（由 scripts/generate-tfds-b-end-bundle.mjs 生成，勿手改）
  * 实现位于包内 ./src/_b_end_runtime/（与主仓 src/data/systems/b-end 同步，可独立 npm 安装）
  */
 
@@ -35,6 +35,7 @@ export { default as Modal } from './_b_end_runtime/components/Modal.jsx';
 export { default as Sheet } from './_b_end_runtime/components/Sheet.jsx';
 export { default as TagInput } from './_b_end_runtime/components/TagInput.jsx';
 export { default as Tag } from './_b_end_runtime/components/Tag.jsx';
+export { default as Filter } from './_b_end_runtime/components/Filter.jsx';
 export { default as Toast } from './_b_end_runtime/components/Toast.jsx';
 export { default as Tooltip } from './_b_end_runtime/components/Tooltip.jsx';
 export { default as Empty } from './_b_end_runtime/components/Empty.jsx';