@tfdesign/b-end 1.0.16 → 1.0.18

package/src/_b_end_runtime/components/Filter.jsx

@@ -1,18 +1,19 @@
 /**
  * Filter — B 端筛选胶囊项
  *
- * 用于筛选栏中的单个触发器/已选筛选条件；传入 options 时内置多选下拉面板。
+ * 用于筛选栏中的单个触发器/已选筛选条件；传入 options 时内置下拉面板。
  *
  * @prop {string} [label='筛选项'] — 筛选项名称
  * @prop {string|number|null} [value=null] — 已选值，存在时显示在 label 后
- * @prop {Array<{label:string,value:string|number,disabled?:boolean}>} [options=[]] — 多选下拉选项
- * @prop {Array<string|number>} [selectedValues] — 受控多选值
- * @prop {Array<string|number>} [defaultValue=[]] — 非受控初始多选值
- * @prop {function|null} [onChange=null] — 多选变更回调
+ * @prop {Array<{label:string,value:string|number,disabled?:boolean}>} [options=[]] — 下拉选项
+ * @prop {boolean} [multiple=true] — 是否多选；`false` 进入单选模式（点击即提交并关闭面板，行尾用 ✓ 而非 checkbox 方框，触发器仅显示 1 项 label，aria-multiselectable=false）
+ * @prop {Array<string|number>|string|number} [selectedValues] — 受控值；多选传数组、单选传单值（也兼容单元素数组）
+ * @prop {Array<string|number>|string|number} [defaultValue=[]] — 非受控初始值
+ * @prop {function|null} [onChange=null] — 变更回调；多选返回数组，单选返回单值（或 null 已清空）
  * @prop {boolean} [selected=false] — 品牌色选中态
  * @prop {boolean} [filled=false] — 中性填充态，适合 hover/轻强调容器
  * @prop {boolean} [disabled=false] — 禁用态
- * @prop {boolean} [closable=false] — 有展示值时是否显示清除图标；已选多选值默认显示清除入口
+ * @prop {boolean} [closable=false] — 有展示值时是否显示清除图标；已选值默认显示清除入口
  * @prop {function|null} [onClear=null] — 清除回调
  * @prop {string} [className=''] — 附加类名
  */
@@ -79,7 +80,7 @@ const CLEAR_CLASS = [
   'rounded-full cursor-pointer',
   'text-foreground-disabled hover:text-foreground-secondary',
   'transition-opacity duration-150',
-  'bg-transparent border-none p-0 mr-1',
+  'bg-transparent border-none p-0 mr-[var(--spacing-1)]',
 ].join(' ');
 const PANEL_CLASS = [
   'rounded-[var(--radius-md)] border border-solid border-border-default',
@@ -150,8 +151,11 @@ function normalizeOptions(options) {
 }
 
 function normalizeValueList(raw) {
-  if (!Array.isArray(raw)) return [];
-  return raw.filter((item) => item !== undefined && item !== null && item !== '');
+  if (raw === undefined || raw === null || raw === '') return [];
+  if (Array.isArray(raw)) {
+    return raw.filter((item) => item !== undefined && item !== null && item !== '');
+  }
+  return [raw];
 }
 
 function measurePanelPosition(triggerEl) {
@@ -172,8 +176,9 @@ export default function Filter({
   label = '筛选项',
   value = null,
   options = [],
+  multiple = true,
   selectedValues,
-  defaultValue = [],
+  defaultValue,
   onChange = null,
   selected = false,
   filled = false,
@@ -191,7 +196,12 @@ export default function Filter({
   const normalizedOptions = useMemo(() => normalizeOptions(options), [options]);
   const hasDropdown = normalizedOptions.length > 0;
   const isControlled = selectedValues !== undefined;
-  const [innerValues, setInnerValues] = useState(() => normalizeValueList(defaultValue));
+  const initialValues = useMemo(
+    () => normalizeValueList(defaultValue !== undefined ? defaultValue : []),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  );
+  const [innerValues, setInnerValues] = useState(() => (multiple ? initialValues : initialValues.slice(0, 1)));
   const [open, setOpen] = useState(false);
   const [panelStyle, setPanelStyle] = useState({
     top: 0,
@@ -199,7 +209,9 @@ export default function Filter({
     width: 180,
     maxHeight: PANEL_MAX_HEIGHT,
   });
-  const currentValues = isControlled ? normalizeValueList(selectedValues) : innerValues;
+  const currentValues = isControlled
+    ? (multiple ? normalizeValueList(selectedValues) : normalizeValueList(selectedValues).slice(0, 1))
+    : innerValues;
   const selectedKeySet = useMemo(
     () => new Set(currentValues.map(getValueKey)),
     [currentValues],
@@ -211,9 +223,10 @@ export default function Filter({
   const derivedValue = useMemo(() => {
     if (value !== null && value !== undefined && value !== '') return value;
     if (selectedOptions.length === 1) return selectedOptions[0].label;
+    if (!multiple) return null;
     if (selectedOptions.length > 1) return `已选 ${selectedOptions.length} 项`;
     return null;
-  }, [selectedOptions, value]);
+  }, [multiple, selectedOptions, value]);
   const hasValue = derivedValue !== null && derivedValue !== undefined && derivedValue !== '';
   const isSelected = selected || selectedOptions.length > 0;
   const tone = disabled
@@ -230,18 +243,30 @@ export default function Filter({
     if (!isControlled) {
       setInnerValues(nextValues);
     }
-    onChange?.(nextValues, event);
-  }, [isControlled, onChange]);
+    if (multiple) {
+      onChange?.(nextValues, event);
+    } else {
+      onChange?.(nextValues[0] ?? null, event);
+    }
+  }, [isControlled, multiple, onChange]);
 
   const toggleOption = useCallback((option, event) => {
     if (option.disabled) return;
     const optionKey = getValueKey(option.value);
     const exists = selectedKeySet.has(optionKey);
-    const nextValues = exists
-      ? currentValues.filter((item) => getValueKey(item) !== optionKey)
-      : [...currentValues, option.value];
+    if (multiple) {
+      const nextValues = exists
+        ? currentValues.filter((item) => getValueKey(item) !== optionKey)
+        : [...currentValues, option.value];
+      commitValues(nextValues, event);
+      return;
+    }
+    // 单选：再次点击已选项视为反选；否则替换为该值并关闭面板
+    const nextValues = exists ? [] : [option.value];
     commitValues(nextValues, event);
-  }, [commitValues, currentValues, selectedKeySet]);
+    setOpen(false);
+    triggerRef.current?.focus();
+  }, [commitValues, currentValues, multiple, selectedKeySet]);
 
   const toggleOpen = useCallback(() => {
     if (disabled || !hasDropdown) return;
@@ -300,7 +325,7 @@ export default function Filter({
       ref={panelRef}
       id={listboxId}
       role="listbox"
-      aria-multiselectable="true"
+      aria-multiselectable={multiple ? 'true' : 'false'}
       className={PANEL_CLASS}
       style={{
         position: 'fixed',
@@ -327,14 +352,21 @@ export default function Filter({
             onMouseDown={(event) => event.preventDefault()}
             onClick={(event) => toggleOption(option, event)}
           >
-            <span className={[
-              CHECKBOX_BOX_BASE,
-              checked ? CHECKBOX_BOX_ON : CHECKBOX_BOX_OFF,
-              option.disabled ? 'border-border-default bg-disabled text-foreground-disabled' : '',
-            ].filter(Boolean).join(' ')}>
-              {checked ? <CheckIcon /> : null}
-            </span>
+            {multiple ? (
+              <span className={[
+                CHECKBOX_BOX_BASE,
+                checked ? CHECKBOX_BOX_ON : CHECKBOX_BOX_OFF,
+                option.disabled ? 'border-border-default bg-disabled text-foreground-disabled' : '',
+              ].filter(Boolean).join(' ')}>
+                {checked ? <CheckIcon /> : null}
+              </span>
+            ) : null}
             <span className="min-w-0 flex-1 truncate">{option.label}</span>
+            {!multiple && checked ? (
+              <span className="inline-flex size-[var(--spacing-4)] shrink-0 items-center justify-center text-brand-500" aria-hidden="true">
+                <CheckIcon />
+              </span>
+            ) : null}
           </div>
         );
       })}
@@ -358,6 +390,7 @@ export default function Filter({
         data-open={open || undefined}
         data-selected={isSelected || undefined}
         data-filled={filled || undefined}
+        data-multiple={multiple ? undefined : 'false'}
         aria-expanded={hasDropdown ? open : undefined}
         aria-haspopup={hasDropdown ? 'listbox' : undefined}
         aria-controls={hasDropdown ? listboxId : undefined}

package/src/_b_end_runtime/components/NavBar.jsx

@@ -95,7 +95,7 @@ const OLA_ROOT = [
 ].join(' ');
 
 const OLA_BRAND = 'flex w-full flex-col items-center gap-1 px-4 py-6';
-const OLA_BRAND_TEXT = 'm-0 text-sm leading-5 text-foreground uppercase';
+const OLA_BRAND_TEXT = 'm-0 text-sm leading-5 text-foreground';
 const OLA_BRAND_TEXT_STYLE = {
   fontFamily: '"Arial Black", Arial, sans-serif',
   fontWeight: 900,

package/src/_b_end_runtime/components/NavBar.tokens.js

@@ -1,6 +1,7 @@
 export const NAVBAR_TOKEN_MAP = {
   品牌: [
     { label: '品牌语义', cssProp: 'content', value: '顶部文案展示真实平台名称；OLA 仅为模板示意，不是固定文案' },
+    { label: '大小写', cssProp: 'text-transform', value: '保留 brandName 原始大小写，不强制 uppercase；允许中文、英文大小写和中英混排' },
     { label: '平台默认', cssProp: 'variant', value: '默认使用 OLA 类型菜单栏结构；ByteHi 仅限明确“客服工作台”场景' },
     { label: '文字色', cssProp: 'color', token: '--color-foreground', value: '#182230', semanticRef: 'text-primary' },
     { label: '字号', cssProp: 'font-size', token: '--text-sm', value: '14px' },

package/src/_b_end_runtime/components/Select.jsx

@@ -139,10 +139,15 @@ const OPTION_ACTIVE = 'bg-brand-50 text-brand-500';
 /* ── 选项禁用 ── */
 const OPTION_DISABLED = 'opacity-50 cursor-not-allowed pointer-events-none text-foreground-disabled';
 const TAG_OPTION_BASE = [
-  'flex min-h-[36px] cursor-pointer items-center px-3 py-2',
+  'mx-1 flex min-h-[36px] cursor-pointer items-center justify-between gap-2 rounded-sm px-2 py-2',
+  'text-sm leading-[20px] text-foreground',
   'transition-colors duration-100',
 ].join(' ');
-const TAG_OPTION_ACTIVE = 'bg-fill';
+const TAG_OPTION_HOVER = 'hover:bg-fill';
+const TAG_OPTION_ACTIVE = 'bg-brand-50 text-brand-500 hover:bg-brand-50';
+const TAG_OPTION_HIGHLIGHT = 'bg-fill';
+const TAG_OPTION_LABEL = 'min-w-0 flex-1 truncate';
+const TAG_OPTION_CHECK = 'inline-flex size-[16px] shrink-0 items-center justify-center text-brand-500';
 
 function getValueKey(value) {
   return String(value);
@@ -629,8 +634,9 @@ export default function Select({
           const hi = highlight === i;
           const cls = [
             isTagMode ? TAG_OPTION_BASE : OPTION_BASE,
-            !opt.disabled && OPTION_HOVER,
-            (selectedOpt || hi) && !opt.disabled ? (isTagMode ? TAG_OPTION_ACTIVE : OPTION_ACTIVE) : '',
+            !opt.disabled && (isTagMode ? (selectedOpt ? '' : TAG_OPTION_HOVER) : OPTION_HOVER),
+            hi && !selectedOpt && !opt.disabled && isTagMode ? TAG_OPTION_HIGHLIGHT : '',
+            selectedOpt && !opt.disabled ? (isTagMode ? TAG_OPTION_ACTIVE : OPTION_ACTIVE) : '',
             opt.disabled ? OPTION_DISABLED : '',
           ].filter(Boolean).join(' ');
           return (
@@ -645,14 +651,14 @@ export default function Select({
               onClick={() => pick(opt)}
             >
               {isTagMode ? (
-                <Tag
-                  variant={opt.variant || DEFAULT_TAG_VARIANT}
-                  size={DEFAULT_TAG_SIZE}
-                  radius={DEFAULT_TAG_RADIUS}
-                  className={selectedOpt ? 'ring-1 ring-primary/40' : ''}
-                >
-                  {opt.label}
-                </Tag>
+                <>
+                  <span className={TAG_OPTION_LABEL}>{opt.label}</span>
+                  <span className={`${TAG_OPTION_CHECK} ${selectedOpt ? 'opacity-100' : 'opacity-0'}`} aria-hidden>
+                    <svg viewBox="0 0 16 16" fill="none" className="size-[16px]">
+                      <path d="M3.5 8.25L6.5 11.25L12.5 4.75" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" />
+                    </svg>
+                  </span>
+                </>
               ) : opt.label}
             </div>
           );

package/src/_b_end_runtime/components/Select.tokens.js

@@ -25,12 +25,16 @@ export const SELECT_TOKEN_MAP = {
   ],
   标签选择: [
     { label: '分类归属', cssProp: 'mode', value: 'tag 属于 Select 的标签选择分类' },
-    { label: '已选标签', cssProp: 'component', value: 'Tag，默认规格与 TagInput 保持一致；可按 option.variant 覆盖颜色' },
+    { label: '已选标签', cssProp: 'component', value: '触发器内回显使用 Tag，默认规格与 TagInput 保持一致；可按 option.variant 覆盖颜色' },
     { label: '折叠项', cssProp: 'component', value: 'Tag children="+N"，沿用 TagInput 默认规格，宽度不足时显示' },
     { label: '更多浮窗', cssProp: 'component', value: 'Tooltip tone=light，仅展示被折叠的标签' },
     { label: '标签间距', cssProp: 'gap', token: '--spacing-1', value: '4px' },
+    { label: '下拉项形态', cssProp: 'component', value: '标准多选列表项：左侧文字，右侧 check；下拉面板内不再渲染 Tag' },
     { label: '下拉项高度', cssProp: 'min-height', token: '--size-control-md', value: '36px' },
-    { label: '下拉项内容', cssProp: 'component', value: 'Tag' },
+    { label: '下拉项圆角', cssProp: 'border-radius', token: '--radius-sm', value: '6px' },
+    { label: '下拉项左右内距', cssProp: 'padding-inline', token: '--spacing-2', value: '8px' },
+    { label: '选中背景', cssProp: 'background', token: '--color-brand-50', value: '#EAFAF6', semanticRef: 'status-primary.bg', state: 'selected' },
+    { label: '选中文字/图标', cssProp: 'color', token: '--color-brand-500', value: '#56D3BC', semanticRef: 'status-primary', state: 'selected' },
   ],
   下拉箭头: [
     { label: '颜色', cssProp: 'color', token: '--color-foreground-muted', value: '#667085', semanticRef: 'text-tertiary' },

package/src/_b_end_runtime/components/Table.jsx

@@ -120,8 +120,8 @@ const TYPE_MIN_HEIGHT = {
 /* ── 容器 / 表格 ──
  * Table 自身不带白色背景、不带四周 padding、不带圆角；
  * 由外部容器（业务白卡 / 预览容器）决定外观与留白。
- * 内部行（HEADER_ROW / BODY_ROW）以及 sticky 列仍保留 bg-surface，
- * 用于保证 sticky 表头与固定列在滚动时不透明、表格行有清晰的可读底色。
+ * 表头默认使用 Blue Grey 100，sticky 固定列保持不透明，
+ * 用于保证横向滚动时表头、固定列和内容层级清晰。
  */
 const WRAPPER = [
   'tfds-table',
@@ -140,11 +140,10 @@ const TABLE_CONTENT = 'flex w-full flex-1 min-h-0 flex-col';
 const TABLE_BODY = 'flex-1 min-h-0 w-full';
 
 /* ── 表头 / 单元格 ──
- * Table 自身不带任何背景色，行/单元格全部透明，由外部容器决定底色。
- * sticky 表头与固定列因此在滚动时会与内容色一致；如业务需要遮挡，
- * 请在外层容器设置背景色（白卡 / 灰底 page 等）。
+ * Table 自身不带外层背景；表头统一使用 Blue Grey 100，
+ * 表体由外部容器或默认 surface 决定底色。
  */
-const HEADER_ROW = 'sticky top-0 z-40 grid w-full min-w-0 bg-surface';
+const HEADER_ROW = 'sticky top-0 z-40 grid w-full min-w-0 bg-blueGrey-100';
 const BODY_ROW = 'grid w-full min-w-0';
 
 const HEADER_CELL = [
@@ -226,6 +225,7 @@ const PAGE_ELLIPSIS = 'inline-flex size-8 items-center justify-center text-sm fo
 
 /* ── 空态 ── */
 const EMPTY_CELL = 'px-4 py-10 text-center text-sm font-normal leading-5 text-foreground-muted';
+const TABLE_HEADER_BACKGROUND = 'var(--color-blueGrey-100, #F9FAFB)';
 const PINNED_SURFACE_BACKGROUND = 'var(--color-surface, #FFFFFF)';
 
 /* ── 卡片型表单 ── */
@@ -371,7 +371,7 @@ function getPinnedCellStyle({
   }
 
   style.position = 'sticky';
-  style.background = PINNED_SURFACE_BACKGROUND;
+  style.background = isHeader ? TABLE_HEADER_BACKGROUND : PINNED_SURFACE_BACKGROUND;
   style.backgroundClip = 'padding-box';
   style.zIndex = isHeader ? 50 : 30;
 

package/src/_b_end_runtime/components.js

@@ -925,6 +925,7 @@ export const COMPONENTS = [
       LOCAL_MEMBER_AVATAR_RULE,
       '【平台默认】NavBar 默认一律使用 platform="ola" 的 OLA 类型菜单栏结构。这里的 OLA 指导航结构类型，不代表顶部品牌文案必须固定显示为“OLA”；图中的“OLA”仅为模板示意。',
       '【品牌文案】brandName 是顶部平台名称展示入口，必须根据真实页面类型动态传入对应平台名称，例如“体验服务”“抖音体验与服务”“服务治理”等；不要把“OLA”当成所有页面固定品牌名。只有在缺少真实平台名称的组件预览或模板占位中，才允许继续显示 OLA。',
+      '【品牌大小写】顶部品牌文案必须保留业务传入的 brandName 原始大小写，不做 uppercase / lowercase / capitalize 等强制转换；允许中文、英文大小写、中英混排和产品专有写法（如 Ola AI、dataPilot、TFDesign）。',
       '【ByteHi 限定】platform="bytehi" 仅限明确提到“客服工作台”相关页面场景时使用，例如“客服工作台首页”“在线客服工作台”“客服工作台会话页”。普通客服、服务、体验、治理、策略、知识、工具、洞察等页面都不要自动切换 ByteHi，仍默认使用 OLA 类型菜单栏。',
       '【提示词】未显式传 platform 时，默认使用 OLA；只有 prompt / promptText 明确包含“客服工作台”时才默认使用 ByteHi。显式传 platform 时以显式值为准，但 AI 生成页面时不得在非客服工作台场景主动传 platform="bytehi"。',
       '【站点级骨架】`NavBar` 是平台级站点导航锚点，不是普通内容区组件。只要页面使用 `NavBar`，一级骨架默认必须是左侧固定导航 + 右侧弹性主工作区的横向 app shell；`NavBar` 永远默认位于页面最左侧',
@@ -948,6 +949,7 @@ export const COMPONENTS = [
     examples: [
       { label: '默认导航栏', code: '<NavBar />' },
       { label: '真实平台名称', code: '<NavBar brandName="体验服务" selectedItemId="home" onSelect={(nextId) => setCurrentNavId(nextId)} />' },
+      { label: '保留平台英文大小写', code: '<NavBar brandName="Ola AI" />' },
       { label: '业务方切换', code: '<NavBar appBusinesses={[{ id: "douyin-community", label: "抖音社区", iconSrc: "icon-logo-douyin" }, { id: "douyin-local-services", label: "抖音生活服务", iconSrc: "icon-logo-douyin" }, { id: "douyin-ecommerce", label: "抖音电商", iconSrc: "icon-logo-douyin" }]} />' },
       { label: '显示底部操作', code: '<NavBar showUtilityActions />' },
       { label: 'ByteHi 平台', code: '<NavBar platform="bytehi" />' },
@@ -2361,9 +2363,10 @@ export const COMPONENTS = [
       '【选型·与 Radio】选项 ≤5 且表单内需并排展示全部文案 → Radio；选项多、需占位窄、或选项会动态增长 → Select',
       '【选型·与 Checkbox】同一字段要选多个离散值 → CheckboxGroup 或 Select mode=tag；仅单个开/关语义 → Switch 或单个 Checkbox',
       '【数据】options 为 { value, label, disabled? }；value 与 option.value 用字符串比较',
-      '【TagSelect】mode="tag" 属于 Select 的标签选择分类，不新增独立基础组件；触发器内已选项、+N 折叠项、下拉项都必须复用 Tag 组件',
+      '【TagSelect】mode="tag" 属于 Select 的标签选择分类，不新增独立基础组件；触发器内已选项与 +N 折叠项必须复用 Tag 组件，但下拉面板必须使用标准多选列表项（左侧文案 + 右侧 check），不要把下拉项渲染成一列 Tag',
       '【TagSelect 规格】Tag 默认颜色与尺寸跟 TagInput 保持一致，不单独暴露颜色或尺寸配置；如需特殊颜色可在单个 option.variant 上覆盖',
-      '【TagSelect 交互】mode="tag" 时 value/defaultValue 为数组；点击下拉标签多选/取消，触发器内标签可关闭，宽度不足时折叠为 +N 并用白底 Tooltip 展示隐藏标签',
+      '【TagSelect 交互】mode="tag" 时 value/defaultValue 为数组；点击下拉选项多选/取消且面板保持打开，触发器内标签可关闭，宽度不足时折叠为 +N 并用白底 Tooltip 展示隐藏标签',
+      '【TagSelect 选中态】多选下拉项用整行热区承载点击，已选项使用品牌浅底 + 品牌色文字 + 右侧 check；hover 仅使用浅灰底，避免与 selected 混淆；禁用项降低透明度且不可点',
       '【AI推荐】仅 mode="default" 支持 `aiSuggestion` / `aiSuggestions`；推荐区展示在 Select 触发器下方，视觉样式、关闭逻辑、hover 展开和刷新交互与 Input 的 AI 推荐保持一致',
       '【AI推荐默认触发】当需求、字段说明或页面描述中出现“AI推荐”“智能推荐”“推荐回复”“刷新推荐”“智能建议”“推荐文案”“建议填写”“推荐选项”等语义时，Select 默认应展示 AI 推荐区，而不是只渲染普通下拉态。',
       '【AI推荐默认形态】命中上述语义后，AI 推荐区固定展示在 Select 组件下方，推荐内容应贴合页面场景，并优先给出适合当前任务的推荐选项或推荐分类。',
@@ -2386,7 +2389,7 @@ export const COMPONENTS = [
     ],
     examples: [
       { label: '基础', code: '<Select options={[{ value: "a", label: "选项 A" }, { value: "b", label: "选项 B" }]} placeholder="请选择" />' },
-      { label: '标签选择', code: '<Select mode="tag" defaultValue={["a", "b"]} options={[{ value: "a", label: "标签", variant: "grey" }, { value: "b", label: "标签", variant: "grey" }]} />' },
+      { label: '标签选择', code: '<Select mode="tag" defaultValue={["brand", "risk"]} options={[{ value: "brand", label: "品牌连锁", variant: "grey" }, { value: "risk", label: "风险预警", variant: "grey" }]} />' },
       { label: '默认选中', code: '<Select options={[{ value: "a", label: "选项 A" }]} defaultValue="a" />' },
       { label: '可清除', code: '<Select allowClear options={[{ value: "x", label: "已选" }]} defaultValue="x" />' },
       { label: 'AI推荐-单条', code: '<Select options={[{ value: "zj", label: "浙江省" }, { value: "js", label: "江苏省" }, { value: "sh", label: "上海市" }]} aiSuggestion="江苏省" onRefreshAiSuggestions={() => {}} onAdoptSuggestion={(value, option) => console.log(value, option)} placeholder="请选择" />' },
@@ -2399,7 +2402,7 @@ export const COMPONENTS = [
       { label: '❌ Bad（原生 select，黑色边框）', code: '/* 禁止！原生 select 黑边、字号错位、不可定制 */\n<select className="border rounded px-2"><option>doubao</option><option>gpt-4o</option></select>' },
       { label: '✅ Good（Select + options）', code: '<Select options={[{ value: "doubao", label: "doubao-seed-1.8" }, { value: "gpt-4o", label: "GPT-4o" }]} placeholder="选择模型" />' },
       { label: '❌ Bad（手写 div+ul 模拟下拉）', code: '/* 禁止！手写 div 下拉缺少键盘、Portal、aria，黑边/层级错乱 */\n<div className="border rounded"><ul><li>选项 A</li><li>选项 B</li></ul></div>' },
-      { label: '✅ Good（多选用 mode="tag"）', code: '<Select mode="tag" defaultValue={["a", "b"]} options={[{ value: "a", label: "标签 A" }, { value: "b", label: "标签 B" }]} />' },
+      { label: '✅ Good（多选用 mode="tag"）', code: '<Select mode="tag" defaultValue={["brand", "risk"]} options={[{ value: "brand", label: "品牌连锁" }, { value: "risk", label: "风险预警" }]} />' },
     ],
     keywords: [
       'Select', 'select', '下拉框', '下拉选择', '下拉菜单', '选择器', 'dropdown', 'combobox',
@@ -3295,8 +3298,9 @@ export const COMPONENTS = [
       '【选型·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 优先用于自定义展示。',
+      '【下拉单/多选】传入 options 后点击胶囊展开下拉面板；通过 `multiple` 切换：默认 `multiple={true}` 多选（行尾 checkbox 方框，可同时勾多项）；`multiple={false}` 单选（行尾 ✓，点击即提交并自动关闭面板，再次点击已选项可反选清空）。两种模式都支持 selectedValues 受控、defaultValue 非受控、onChange 回调；点击外部或 Escape 关闭。',
+      '【受控/回调签名】多选：selectedValues 传数组，onChange 返回数组；单选：selectedValues 可传单值或单元素数组，onChange 返回单值（清空时返回 null）。defaultValue 同样支持单值/数组两种形态。',
+      '【值展示】未显式传 value 时，单选/多选选中 1 项都展示该项 label，多选选中 ≥2 项展示“已选 N 项”，单选始终最多 1 项 label；显式 value 优先用于自定义展示。',
       '【状态】selected=true 使用品牌浅底 + 品牌描边 + 品牌文字；filled=true 使用中性填充底；disabled=true 使用禁用文字与禁用底，且不可点击。',
       '【图标】无选中值时显示 12px 下拉箭头；closable=true 或已选中且未禁用时显示 16px 清除按钮（视觉与 Select 清除入口一致），点击清空多选值、关闭下拉并触发 onClear，不触发展开。',
       '【语义结构】外层使用 role="combobox/button" 的 div 触发器，避免清除 button 嵌套在 button 内；不要改回 button 包 button 的非法 DOM。',
@@ -3305,9 +3309,12 @@ export const COMPONENTS = [
     ],
     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={[{ label: "选项一", value: "1" }, { label: "选项二", value: "2" }]} />' },
+      { label: '单选下拉', code: '<Filter label="状态" multiple={false} options={[{ label: "全部", value: "all" }, { label: "进行中", value: "running" }, { label: "已完成", value: "done" }]} />' },
+      { label: '默认已选（多选）', code: '<Filter label="筛选项" options={options} defaultValue={["1"]} />' },
+      { label: '默认已选（单选）', code: '<Filter label="状态" multiple={false} options={options} defaultValue="running" />' },
       { label: '受控多选', code: '<Filter label="筛选项" options={options} selectedValues={values} onChange={setValues} />' },
+      { label: '受控单选', code: '<Filter label="状态" multiple={false} options={options} selectedValues={current} onChange={setCurrent} />' },
       { 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={() => {}} />' },
@@ -3320,7 +3327,8 @@ export const COMPONENTS = [
     keywords: [
       'Filter', 'filter', '筛选', '筛选项', '筛选组件', '筛选胶囊', '筛选 chip',
       '筛选触发器', '已选筛选', '过滤条件', 'filter item', 'filter chip', 'pill filter',
-      'closable', 'clear', '清除筛选', '下拉筛选', '多选筛选', 'selected filter',
+      'closable', 'clear', '清除筛选', '下拉筛选', '多选筛选', '单选筛选', 'single select filter', 'multi select filter',
+      'multiple', 'multiple={false}', 'selected filter',
       'span rounded-full border', '手搓筛选', '自制筛选 chip',
     ],
   },