iter(g110): 下拉选择支持清空

.ua/backlog.json

@@ -1236,6 +1236,14 @@
       "acceptance": "触摸指针（pointerType=touch）不走 hover 分支，改为按下即出场、抬手后延迟 1.2s 收起；鼠标与键盘路径行为不变；re-enter 时清掉上一轮的延迟收起计时；文档手把手与 api 说明补触摸语义；npm run check 全绿",
       "notes": "自补：可用性；只在原文件加两个分支与一个计时器，未改签名",
       "status": "done"
+    },
+    {
+      "id": "g110",
+      "title": "下拉选择支持清空",
+      "motivation": "筛选项一旦选中就回不到「未选」：城市、负责人这类可选筛选的下拉没有清空出口，用户只能刷新页面或换一个值。textField 早有 clearable，select 一直没有对应能力",
+      "acceptance": "SelectProps 新增 clearable（缺省 false）：有值时触发器右缘出现 ×，点它把值写成空串并回调 onChange('')；收起态按 Delete / Backspace 等价清空；按钮不进 Tab 序、无值自动隐藏；文档参数表 / 手把手 / api 说明与演示（城市下拉开启清空）同步；npm run check 全绿",
+      "notes": "自补：可用性；复用既有 value 信号与 onChange，不新增状态",
+      "status": "open"
     }
   ]
 }

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T06:01:43.914Z",
+  "generatedAt": "2026-10-26T06:03:06.956Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -149,7 +149,7 @@
           "slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值",
           "checkbox(props)：复选框，checked 信号双向绑定，disabled 支持布尔或信号禁用",
           "switchButton(props)：开关，checked 信号双向绑定，disabled 支持布尔或信号禁用",
-          "select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框",
+          "select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框，clearable 有值时给清空按钮",
           "menu(props)：下拉菜单，触发器 + 自绘弹层，条目支持禁用 / 危险 / 分隔线，↑↓ 环形导航，点外部 / Esc 关闭，空间不足自动翻转，键入字母快跳菜单项",
           "flip(trigger, panel, preferred)：浮层上下翻转判定，按触发器与面板的视口几何决定 preferred 方位放不下时是否翻转，返回实际生效方位 'top' | 'bottom'",
           "radioGroup(props)：单选组，options + value 信号双向绑定，disabled 整组禁用",
@@ -664,6 +664,11 @@
                 "t": "boolean",
                 "d": "弹层顶部带搜索框，按标签包含匹配过滤；缺省 false"
               },
+              {
+                "n": "clearable",
+                "t": "boolean",
+                "d": "有值时触发器右缘出现清空按钮（收起态按 Delete / Backspace 也能清）；缺省 false，用于「可选筛选项」"
+              },
               {
                 "n": "disabled",
                 "t": "boolean | Signal<boolean>",
@@ -683,7 +688,8 @@
               "点击触发器展开弹层，点选项写回信号并收起；点外部或按 Esc 也会收起",
               "选中项在弹层中用淡色弱化标记，不抢视觉焦点",
               "弹层展开时按 Esc 只收起下拉并回焦触发器；若下拉在弹窗/抽屉内，再按一次 Esc 才关外层（逐层关闭）",
-              "searchable: true 时打开即聚焦搜索框，输入实时过滤；↑↓/Home/End 只在可见项间移动，无命中显示「无匹配选项」"
+              "searchable: true 时打开即聚焦搜索框，输入实时过滤；↑↓/Home/End 只在可见项间移动，无命中显示「无匹配选项」",
+              "需要允许「不选」的筛选项就开 clearable：有值时右缘出现 ×，点它把值写成空串并回调 onChange('')，键盘在收起态按 Delete / Backspace 等价"
             ]
           },
           {

apps/demo/main.ts

@@ -267,7 +267,7 @@ const content = h(
     h('div', { class: 'row' }, checkbox({ label: '同意条款', checked: agreed }), h('span', { class: 'out' }, () => (agreed() ? '已同意' : '未同意'))),
     h('div', { class: 'row' }, switchButton({ label: '夜间模式', checked: nightMode }), h('span', { class: 'out' }, () => (nightMode() ? '开' : '关'))),
     h('div', { class: 'row' }, switchButton({ checked: sound, ariaLabel: '通知声音' }), h('span', { class: 'out' }, () => `无可见文案的开关（ariaLabel 兜底，读屏念「通知声音」）：${sound() ? '开' : '关'}`)),
-    h('div', { class: 'row' }, select({ options: cities.map((c) => ({ value: c, label: c })), value: city, placeholder: '选择城市…' }), h('span', { class: 'out' }, () => (city() ? `城市：${city()}` : '未选择'))),
+    h('div', { class: 'row' }, select({ options: cities.map((c) => ({ value: c, label: c })), value: city, placeholder: '选择城市…', clearable: true }), h('span', { class: 'out' }, () => (city() ? `城市：${city()}（点 × 或按 Delete 清空）` : '未选择'))),
     h('div', { class: 'row' }, radioGroup({ options: [{ value: 's', label: '小' }, { value: 'm', label: '中' }, { value: 'l', label: '大' }], value: size })),
     textarea({ placeholder: '一句话介绍…', value: bio, rows: 2, maxCount: 30 }),
     h('span', { class: 'out' }, () => `简介 ${bio().length} 字`),

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T06:01:43.914Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T06:03:06.956Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -266,6 +266,7 @@ const night = signal(true); switchButton({ label: '夜间模式', checked: night
 - value：Signal<string> —— 选中值信号，双向绑定
 - placeholder：string —— 未选中时触发器显示的占位文案
 - searchable：boolean —— 弹层顶部带搜索框，按标签包含匹配过滤；缺省 false
+- clearable：boolean —— 有值时触发器右缘出现清空按钮（收起态按 Delete / Backspace 也能清）；缺省 false，用于「可选筛选项」
 - disabled：boolean | Signal<boolean> —— 禁用态：布尔直接置位，传信号则动态同步；禁用时触发器置灰且不展开弹层
 - onChange（回调）：(value: string) => void —— 选中回调
 
@@ -283,6 +284,7 @@ const city = signal(''); select({ options: [{ value: 'bj', label: '北京' }], v
 4. 选中项在弹层中用淡色弱化标记，不抢视觉焦点
 5. 弹层展开时按 Esc 只收起下拉并回焦触发器；若下拉在弹窗/抽屉内，再按一次 Esc 才关外层（逐层关闭）
 6. searchable: true 时打开即聚焦搜索框，输入实时过滤；↑↓/Home/End 只在可见项间移动，无命中显示「无匹配选项」
+7. 需要允许「不选」的筛选项就开 clearable：有值时右缘出现 ×，点它把值写成空串并回调 onChange('')，键盘在收起态按 Delete / Backspace 等价
 
 现场演示：apps/docs/demo.html#sec-form
 
@@ -1629,7 +1631,7 @@ API 速览：
 - slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值
 - checkbox(props)：复选框，checked 信号双向绑定，disabled 支持布尔或信号禁用
 - switchButton(props)：开关，checked 信号双向绑定，disabled 支持布尔或信号禁用
-- select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框
+- select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框，clearable 有值时给清空按钮
 - menu(props)：下拉菜单，触发器 + 自绘弹层，条目支持禁用 / 危险 / 分隔线，↑↓ 环形导航，点外部 / Esc 关闭，空间不足自动翻转，键入字母快跳菜单项
 - flip(trigger, panel, preferred)：浮层上下翻转判定，按触发器与面板的视口几何决定 preferred 方位放不下时是否翻转，返回实际生效方位 'top' | 'bottom'
 - radioGroup(props)：单选组，options + value 信号双向绑定，disabled 整组禁用

llms.txt

@@ -54,7 +54,7 @@
   - slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值
   - checkbox(props)：复选框，checked 信号双向绑定，disabled 支持布尔或信号禁用
   - switchButton(props)：开关，checked 信号双向绑定，disabled 支持布尔或信号禁用
-  - select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框
+  - select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框，clearable 有值时给清空按钮
   - menu(props)：下拉菜单，触发器 + 自绘弹层，条目支持禁用 / 危险 / 分隔线，↑↓ 环形导航，点外部 / Esc 关闭，空间不足自动翻转，键入字母快跳菜单项
   - flip(trigger, panel, preferred)：浮层上下翻转判定，按触发器与面板的视口几何决定 preferred 方位放不下时是否翻转，返回实际生效方位 'top' | 'bottom'
   - radioGroup(props)：单选组，options + value 信号双向绑定，disabled 整组禁用

packages/skin/ui/src/select.ts

@@ -24,6 +24,13 @@ export function select(props: SelectProps): HTMLElement {
     props.onChange?.(v);
   };
 
+  /*** 清空：可选筛选项回到「未选」态，信号与回调同源写回 ***/
+  const clear = () => {
+    if (!value()) return; // 卫语句：本来就没选，不重复派发回调
+    value('');
+    props.onChange?.('');
+  };
+
   // —— 触发器 ——
   const trigger = h(
     'button',
@@ -72,7 +79,17 @@ export function select(props: SelectProps): HTMLElement {
     blank,
   );
 
-  const root = h('div', { class: () => `ua-select${open() ? ' ua-open' : ''}` }, trigger, pop); // 根带开合类，供箭头旋转
+  // —— 清空按钮：clearable 且有值时出现，绝对定位压在触发器右缘（与箭头错开）——
+  const clearBtn = h('button', {
+    type: 'button',
+    class: 'ua-select-clear',
+    'aria-label': '清空选择',
+    tabindex: '-1', // 不进 Tab 序：清空是鼠标 / 触屏便利，键盘用 Delete / Backspace
+    onClick: () => clear(),
+  }, '×');
+  effect(() => { clearBtn.hidden = !props.clearable || !value(); }); // 无值或未开启时藏起来（不进 Tab 序，隐藏即失效）
+
+  const root = h('div', { class: () => `ua-select${open() ? ' ua-open' : ''}` }, trigger, props.clearable ? clearBtn : null, pop); // 根带开合类，供箭头旋转
 
   // —— 键入快跳缓冲（非 searchable 时生效，逻辑与 menu 一致）——
   let typed = '';          // 最近键入的字母串，用于前缀匹配
@@ -90,6 +107,7 @@ export function select(props: SelectProps): HTMLElement {
 
   root.addEventListener('keydown', (e: KeyboardEvent) => {
     const list = visibleIdx();
+    if (props.clearable && !open() && (e.key === 'Backspace' || e.key === 'Delete')) { e.preventDefault(); clear(); return; } // 键盘等价：收起态下 Delete / Backspace 清空
     if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
       e.preventDefault(); // 阻止页面滚动
       if (!open()) { open(true); options[list[0] ?? 0]?.focus(); return; } // 未展开：展开并聚焦首个可见选项

packages/skin/ui/src/types.ts

@@ -108,6 +108,7 @@ export interface SelectProps {
   placeholder?: string;     // 未选中时的占位项文案
   disabled?: boolean | Signal<boolean>; // 禁用态：布尔直接置位，传信号则动态同步
   searchable?: boolean;     // 弹层顶部带搜索框，按标签包含匹配过滤；缺省 false
+  clearable?: boolean;      // 有值时触发器右缘出现清空按钮（删除 / Backspace 亦可清）；缺省 false
   onChange?: (value: string) => void; // 变更回调
 }
 

packages/skin/ui/ua.manifest.json

@@ -20,7 +20,7 @@
       "slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值",
       "checkbox(props)：复选框，checked 信号双向绑定，disabled 支持布尔或信号禁用",
       "switchButton(props)：开关，checked 信号双向绑定，disabled 支持布尔或信号禁用",
-      "select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框",
+      "select(props)：自绘下拉选择（非原生 select），value 信号双向绑定，点外部 / Esc 关闭，选项弹层带微动画，disabled 支持布尔或信号禁用，空间不足自动翻转，键入字母快跳选项；searchable 开启弹层搜索框，clearable 有值时给清空按钮",
       "menu(props)：下拉菜单，触发器 + 自绘弹层，条目支持禁用 / 危险 / 分隔线，↑↓ 环形导航，点外部 / Esc 关闭，空间不足自动翻转，键入字母快跳菜单项",
       "flip(trigger, panel, preferred)：浮层上下翻转判定，按触发器与面板的视口几何决定 preferred 方位放不下时是否翻转，返回实际生效方位 'top' | 'bottom'",
       "radioGroup(props)：单选组，options + value 信号双向绑定，disabled 整组禁用",
@@ -535,6 +535,11 @@
             "t": "boolean",
             "d": "弹层顶部带搜索框，按标签包含匹配过滤；缺省 false"
           },
+          {
+            "n": "clearable",
+            "t": "boolean",
+            "d": "有值时触发器右缘出现清空按钮（收起态按 Delete / Backspace 也能清）；缺省 false，用于「可选筛选项」"
+          },
           {
             "n": "disabled",
             "t": "boolean | Signal<boolean>",
@@ -554,7 +559,8 @@
           "点击触发器展开弹层，点选项写回信号并收起；点外部或按 Esc 也会收起",
           "选中项在弹层中用淡色弱化标记，不抢视觉焦点",
           "弹层展开时按 Esc 只收起下拉并回焦触发器；若下拉在弹窗/抽屉内，再按一次 Esc 才关外层（逐层关闭）",
-          "searchable: true 时打开即聚焦搜索框，输入实时过滤；↑↓/Home/End 只在可见项间移动，无命中显示「无匹配选项」"
+          "searchable: true 时打开即聚焦搜索框，输入实时过滤；↑↓/Home/End 只在可见项间移动，无命中显示「无匹配选项」",
+          "需要允许「不选」的筛选项就开 clearable：有值时右缘出现 ×，点它把值写成空串并回调 onChange('')，键盘在收起态按 Delete / Backspace 等价"
         ]
       },
       {

packages/skin/ui/ui.css

@@ -3751,3 +3751,36 @@ button.ua-step-dot:hover {
 .ua-form-summary[hidden] {
   display: none;
 }
+
+/* —— 下拉清空按钮 —— */
+.ua-select-clear {
+  position: absolute;
+  top: 50%;
+  right: 24px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  padding: 0;
+  border: none;
+  border-radius: 50%;
+  background: none;
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-md);
+  line-height: 1;
+  cursor: pointer;
+  transform: translateY(-50%);
+  transition: color 0.15s, background-color 0.15s;
+}
+.ua-select-clear:hover {
+  color: var(--ua-color-text);
+  background: color-mix(in srgb, var(--ua-color-accent) 12%, transparent);
+}
+.ua-select-clear:focus-visible {
+  outline: 2px solid var(--ua-color-accent);
+  outline-offset: 1px;
+}
+.ua-select-clear[hidden] {
+  display: none;
+}