iter(g18): textField 可清空按钮

.ua/backlog.json

@@ -500,6 +500,14 @@
       "acceptance": "select 展开时键入可打印字符循环聚焦 label 前缀匹配项（不区分大小写），1 秒无输入重置缓冲；既有 ↑↓/Home/End 行为不变；npm run check 全绿",
       "status": "done",
       "notes": "自补：既有组件可用性细节"
+    },
+    {
+      "id": "g18",
+      "title": "textField 可清空按钮",
+      "motivation": "长文本输入后逐字删除太慢，主流输入框都提供 clearable 一键清空",
+      "acceptance": "clearable 开启后有值时显示清空按钮，点击清空并同步信号与 onInput；空值自动隐藏；npm run check 全绿",
+      "status": "open",
+      "notes": "自补：既有组件可用性细节"
     }
   ]
 }

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T02:59:40.484Z",
+  "generatedAt": "2026-10-26T03:02:53.444Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -143,7 +143,7 @@
         "entry": "src/index.ts",
         "exports": [
           "button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用",
-          "textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块",
+          "textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块，clearable 开启后有值即显一键清空按钮",
           "inputNumber(props)：数字输入，−/+ 按钮与键盘 ↑↓ 调节，min/max/step 夹取；prefix/suffix 可选渲染为整组前后附加块",
           "textarea(props)：多行输入，value 信号双向绑定，disabled 支持布尔或信号，rows 控行数；prefix/suffix 可选渲染为上下附加块",
           "slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值",

apps/demo/main.ts

@@ -205,10 +205,10 @@ const content = h(
   section(
     'sec-bind',
     '双向绑定',
-    'textField 与信号双向同步：输入即回显；prefix/suffix 渲染为输入框内侧附加块。',
+    'textField 与信号双向同步：输入即回显；prefix/suffix 渲染为输入框内侧附加块；clearable 开启后有值即显一键清空。',
     textField({ placeholder: '输入名字…', value: name }),
-    textField({ placeholder: '搜索…', value: name, prefix: '🔍' }),
+    textField({ placeholder: '搜索…', value: name, prefix: '🔍', clearable: true }),
-    textField({ value: price, suffix: '元' }),
+    textField({ value: price, suffix: '元', clearable: true }),
     h('span', { class: 'out' }, () => (name() ? `你好，${name()}！` : '等待输入…')),
   ),
   section(

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T02:59:40.484Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T03:02:53.444Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -1008,7 +1008,7 @@ const gmv = signal(128000); statistic({ title: '本月 GMV', value: gmv, prefix:
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用
-- textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块
+- textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块，clearable 开启后有值即显一键清空按钮
 - inputNumber(props)：数字输入，−/+ 按钮与键盘 ↑↓ 调节，min/max/step 夹取；prefix/suffix 可选渲染为整组前后附加块
 - textarea(props)：多行输入，value 信号双向绑定，disabled 支持布尔或信号，rows 控行数；prefix/suffix 可选渲染为上下附加块
 - slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值

llms.txt

@@ -48,7 +48,7 @@
 - 描述: DOM 皮肤组件库：button / textField / textarea / slider / checkbox / switch / select / menu / radioGroup / accordion / breadcrumb / card / badge / image / tag / avatar / alert / toast / tooltip / popover / skeleton / spinner / progress / tabs / pagination / modal / drawer / form / formItem / dataTable，构建在 @ui-arch/frame 与 @ui-arch/table-core 之上，样式只消费 --ua-* 令牌。
 - API:
   - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用
-  - textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块
+  - textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块，clearable 开启后有值即显一键清空按钮
   - inputNumber(props)：数字输入，−/+ 按钮与键盘 ↑↓ 调节，min/max/step 夹取；prefix/suffix 可选渲染为整组前后附加块
   - textarea(props)：多行输入，value 信号双向绑定，disabled 支持布尔或信号，rows 控行数；prefix/suffix 可选渲染为上下附加块
   - slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值

packages/skin/ui/src/textField.ts

@@ -2,7 +2,7 @@ import { effect, h } from '@ui-arch/frame';
 import { addonWrap } from './addons.js';
 import type { TextFieldProps } from './types.js';
 
-/*** 文本输入：value 信号双向绑定，disabled 支持布尔或信号禁用，onInput 为输入回调；prefix/suffix 包附加组 ***/
+/*** 文本输入：value 信号双向绑定，disabled 支持布尔或信号禁用，onInput 为输入回调；prefix/suffix 包附加组，clearable 一键清空 ***/
 export function textField(props: TextFieldProps): HTMLElement {
   const el = h('input', { class: 'ua-input', placeholder: props.placeholder ?? '', disabled: props.disabled }) as HTMLInputElement; // false/undefined 移除属性，Signal 走响应式
   if (props.value) {
@@ -13,5 +13,23 @@ export function textField(props: TextFieldProps): HTMLElement {
     });
   }
   if (props.onInput) el.addEventListener('input', () => props.onInput!(el.value));
-  return addonWrap(el, props.prefix, props.suffix);
+  let clearBtn: HTMLElement | null = null; // 一键清空按钮；clearable 关闭时不创建
+  if (props.clearable) {
+    clearBtn = h(
+      'button',
+      {
+        type: 'button',
+        class: 'ua-input-clear is-hidden', // 初始无值隐藏
+        'aria-label': '清空输入',
+        tabIndex: -1,                      // 不进 Tab 序，清空走鼠标/触屏
+        onClick: () => { el.value = ''; props.value?.(''); props.onInput?.(''); el.focus(); }, // 清空并同步信号与回调
+      },
+      '×',
+    );
+    const syncClear = (): void => { clearBtn!.classList.toggle('is-hidden', el.value === ''); }; // 有值才显示
+    el.addEventListener('input', syncClear);                                                 // 用户输入时同步
+    effect(() => { if (props.value) props.value(); syncClear(); });                          // 外部写回时同步（读信号建依赖）
+  }
+  const suffix = clearBtn ? h('span', { class: 'ua-input-clear-group' }, clearBtn, props.suffix ?? null) : props.suffix; // 清空按钮并入后置附加组
+  return addonWrap(el, props.prefix, suffix);
 }

packages/skin/ui/src/types.ts

@@ -34,6 +34,7 @@ export interface TextFieldProps {
   onInput?: (value: string) => void; // 输入回调
   prefix?: string | HTMLElement;     // 输入框内侧前置附加块（如图标、货币符）；缺省不渲染
   suffix?: string | HTMLElement;     // 输入框内侧后置附加块（如单位）；缺省不渲染
+  clearable?: boolean;               // 开启后有值时显示一键清空按钮；缺省不渲染
 }
 
 /*** 卡片入参 ***/

packages/skin/ui/ua.manifest.json

@@ -14,7 +14,7 @@
     "entry": "src/index.ts",
     "exports": [
       "button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用",
-      "textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块",
+      "textField(props)：文本输入，value 信号双向绑定，disabled 支持布尔或信号，onInput 输入回调；prefix/suffix 可选渲染为输入框内侧附加块，clearable 开启后有值即显一键清空按钮",
       "inputNumber(props)：数字输入，−/+ 按钮与键盘 ↑↓ 调节，min/max/step 夹取；prefix/suffix 可选渲染为整组前后附加块",
       "textarea(props)：多行输入，value 信号双向绑定，disabled 支持布尔或信号，rows 控行数；prefix/suffix 可选渲染为上下附加块",
       "slider(props)：滑块，value 信号双向绑定，min/max/step 可配，原生 range 承载键盘交互，右侧可显示当前值",

packages/skin/ui/ui.css

@@ -1669,6 +1669,26 @@ button.ua-step-dot:hover {
   font-size: var(--ua-font-size-md);
   user-select: none;
 }
+.ua-input-clear-group {
+  display: inline-flex;      /* 清空按钮 + 原有 suffix 并排 */
+  align-items: center;
+  gap: 4px;
+}
+.ua-input-clear {
+  border: none;              /* 一键清空：小圆钮，弱化视觉 */
+  background: none;
+  padding: 0 2px;
+  color: var(--ua-color-text-muted);
+  font-size: var(--ua-font-size-md);
+  line-height: 1;
+  cursor: pointer;
+}
+.ua-input-clear:hover {
+  color: var(--ua-color-text);
+}
+.ua-input-clear.is-hidden {
+  display: none;             /* 空值时隐藏 */
+}
 
 /* —— 时间线：纵向轴线 + 语义色节点，mode=right 时轴线居右 —— */
 .ua-tl {