iter(g238): 新增 highlight 关键词高亮，命中片段包 mark 并随信号实时联动（75 组件）

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T13:30:37.089Z",
+  "generatedAt": "2026-10-26T13:32:36.756Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -217,7 +217,8 @@
           "pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示",
           "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand",
           "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset",
-          "kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示"
+          "kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示",
+          "highlight(props)：关键词高亮，命中片段包 mark（大小写不敏感全部命中），text / keyword 支持信号响应式刷新"
         ],
         "keyTypes": [
           "ButtonProps",
@@ -3995,6 +3996,31 @@
               "传数组展示组合键：kbd({ keys: [\"Ctrl\", \"K\"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）",
               "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感"
             ]
+          },
+          {
+            "id": "highlight",
+            "title": "关键词高亮 Highlight",
+            "demo": "sec-highlight",
+            "props": [
+              {
+                "n": "text",
+                "t": "string | Signal<string>",
+                "r": 1,
+                "d": "原文；传信号则随信号变化响应式重画"
+              },
+              {
+                "n": "keyword",
+                "t": "string | Signal<string>",
+                "r": 1,
+                "d": "关键词（大小写不敏感、全部命中，首尾空白忽略）；空串不高亮、原样展示"
+              }
+            ],
+            "example": "highlight({ text: 'Alpha Beta', keyword: 'beta' })",
+            "steps": [
+              "传 text + keyword 即可，命中片段以淡黄 mark 底展示，适合搜索结果 / 补全列表的匹配说明",
+              "两个入参都接受信号：搜索框输入实时联动高亮，无需手动重渲染",
+              "大小写不敏感且全部命中（非只第一处）；关键词两侧空白自动忽略"
+            ]
           }
         ]
       },

AGENTS.md

@@ -21,7 +21,7 @@
 
 - `packages/core/table-core`（@ui-arch/table-core）：Headless 表格逻辑内核
 - `packages/core/frame`（@ui-arch/frame）：signal + hyperscript 微框架
-- `packages/skin/ui`（@ui-arch/ui）：74 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
+- `packages/skin/ui`（@ui-arch/ui）：75 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
 - `packages/design/tokens`（@ui-arch/tokens）：设计令牌
 - `packages/tools/cli`（@ui-arch/cli）：`ua` 命令行 + MCP 注册表服务（private）
 - `apps/demo`（@ui-arch/demo）：交互演示，产物 apps/demo/dist/demo.html

ARCHITECTURE.md

@@ -34,7 +34,7 @@ ui-arch-mvp/
 │   │   ├── table-core/       # 表格状态内核
 │   │   └── frame/            # 信号 + hyperscript 微框架
 │   ├── skin/                 # 皮肤层（DOM 组件，可发布）
-│   │   └── ui/               # 74 个组件 + ui.css
+│   │   └── ui/               # 75 个组件 + ui.css
 │   ├── design/               # 资产层（可发布）
 │   │   └── tokens/           # --ua-* 设计令牌
 │   └── tools/                # 工程层（private，不发布）

README.md

@@ -12,13 +12,13 @@ npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全
 npm run changelog       # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移）
 ```
 
-## 组件（共 74 个）
+## 组件（共 75 个）
 
 <!-- ua:components -->
-accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · countdown · kbd · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · image · inputNumber · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
+accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · kbd · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · skeleton · slider · space · spinner · splitter · statistic · stepper · switchButton · tabs · tag · textField · textarea · timeline · timePicker · toast · tooltip · tour · transfer · tree · treeSelect · typography · upload · virtualList · watermark
 <!-- /ua:components -->
 
-分组：表单（button / copyButton / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / kbd / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。
+分组：表单（button / copyButton / textField / inputNumber / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / toast / notification / result / spinner / progress / skeleton / badge / empty / statistic / countdown）、浮层（tooltip / popover / popconfirm / modal / drawer / menu / commandPalette）、导航（tabs / breadcrumb / pagination / accordion / stepper / tree / treeSelect / anchor）、数据展示（dataTable / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / link / space / divider / splitter / backTop / affix / tour / watermark）。
 
 ## 可访问性约定
 
@@ -32,7 +32,7 @@ accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup
 |---|---|
 | `packages/core/frame` | @ui-arch/frame：signal / computed / effect + hyperscript（无虚拟 DOM） |
 | `packages/core/table-core` | @ui-arch/table-core：headless 表格（filter → sort → paginate 派生管线） |
-| `packages/skin/ui` | @ui-arch/ui：74 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
+| `packages/skin/ui` | @ui-arch/ui：75 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
 | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） |
 | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server |
 | `apps/demo` | 交互演示（esbuild 打包成单文件） |

apps/demo/main.ts

@@ -31,6 +31,7 @@ import {
   countdown,
   dataTable,
   kbd,
+  highlight,
   datePicker,
   transfer,
   descriptions,
@@ -254,6 +255,8 @@ const acValue = signal(''); // 自动补全输入值（外部受控演示）
 const pinCode = signal(''); // 验证码输入值（外部受控演示）
 const pinMask = signal(''); // 密文验证码输入值（mask 演示）
 const resendCd = countdown({ seconds: 90, running: false, format: (s) => `重发(${s}s)` }); // 重发倒计时（手动启动演示）
+const highlightText = signal('数据不出端、预测低于 50ms、习惯本地学习是输入法增强系统的三条底线'); // 高亮演示原文
+const highlightKw = signal('本地'); // 高亮演示关键词（与搜索框信号联动）
 const treeChecked = signal<string[]>(['core']); // 多选树勾选集合（外部受控演示）
 const treePick = signal('core'); // 树形选中节点 key
 const transferKeys = signal<string[]>(['a11y']); // 穿梭框右侧集合（外部受控演示）
@@ -1135,6 +1138,22 @@ const content = h(
       h('span', { class: 'out' }, '按 ', kbd({ keys: ['Ctrl', 'K'] }), ' 唤起演示页命令面板'),
     ),
   ),
+  section(
+    'sec-highlight',
+    '关键词高亮',
+    'highlight：命中片段包 mark（大小写不敏感全部命中），text / keyword 接受信号实时联动，空关键词原样展示。',
+    h(
+      'div',
+      { class: 'row' },
+      highlight({ text: highlightText, keyword: highlightKw }),
+      h('span', { class: 'out' }, () => `关键词：${highlightKw() || '（空）'}`),
+    ),
+    h(
+      'div',
+      { class: 'row' },
+      textField({ placeholder: '输入关键词试试实时联动', value: highlightKw, size: 'sm' }),
+    ),
+  ),
   section(
     'sec-affix',
     '固钉',

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T13:30:37.089Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T13:32:36.756Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2117,6 +2117,27 @@ kbd({ keys: 'Esc' })、kbd({ keys: ['Ctrl', 'K'] })
 
 现场演示：apps/docs/demo.html#sec-kbd
 
+### highlight — 关键词高亮 Highlight
+
+参数：
+
+- text（必填）：string | Signal<string> —— 原文；传信号则随信号变化响应式重画
+- keyword（必填）：string | Signal<string> —— 关键词（大小写不敏感、全部命中，首尾空白忽略）；空串不高亮、原样展示
+
+示例：
+
+```
+highlight({ text: 'Alpha Beta', keyword: 'beta' })
+```
+
+手把手：
+
+1. 传 text + keyword 即可，命中片段以淡黄 mark 底展示，适合搜索结果 / 补全列表的匹配说明
+2. 两个入参都接受信号：搜索框输入实时联动高亮，无需手动重渲染
+3. 大小写不敏感且全部命中（非只第一处）；关键词两侧空白自动忽略
+
+现场演示：apps/docs/demo.html#sec-highlight
+
 API 速览：
 
 - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交）
@@ -2195,6 +2216,7 @@ API 速览：
 - copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand
 - countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset
 - kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示
+- highlight(props)：关键词高亮，命中片段包 mark（大小写不敏感全部命中），text / keyword 支持信号响应式刷新
 
 一行用法：
 

llms.txt

@@ -123,6 +123,7 @@
   - copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand
   - countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset
   - kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示
+  - highlight(props)：关键词高亮，命中片段包 mark（大小写不敏感全部命中），text / keyword 支持信号响应式刷新
 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')`
 - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号
 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调

packages/skin/ui/src/highlight.ts

@@ -0,0 +1,30 @@
+import { effect, h, type Signal } from '@ui-arch/frame';
+import type { HighlightProps } from './types.js';
+
+/*** 作用：读信号或原始值（string | Signal<string> 统一取值） ***/
+const read = (v: string | Signal<string>): string => (typeof v === 'function' ? v() : v);
+
+/*** 关键词高亮：命中片段包进 mark（大小写不敏感、全部命中），text / keyword 均支持信号响应式刷新，空关键词原样展示 ***/
+export function highlight(props: HighlightProps): HTMLSpanElement {
+  const root = h('span', { class: 'ua-highlight' }) as HTMLSpanElement;
+
+  /*** 作用：按当前 text / keyword 重画内容：命中段包 mark，未命中段原样拼接（effect 追踪两个信号，任一变化重画） ***/
+  const render = (): void => {
+    const text = read(props.text);
+    const kw = read(props.keyword).trim();
+    root.textContent = '';
+    if (!kw) { root.textContent = text; return; } // 空关键词不高亮
+    const lower = text.toLowerCase();
+    const k = kw.toLowerCase();
+    let cursor = 0;
+    for (let idx = lower.indexOf(k); idx !== -1; idx = lower.indexOf(k, cursor)) {
+      if (idx > cursor) root.append(text.slice(cursor, idx)); // 命中前缀原样
+      root.append(h('mark', { class: 'ua-highlight-mark' }, text.slice(idx, idx + k.length))); // 命中段包 mark
+      cursor = idx + k.length;
+    }
+    if (cursor < text.length) root.append(text.slice(cursor)); // 尾段原样
+  };
+
+  effect(render);
+  return root;
+}

packages/skin/ui/src/index.ts

@@ -74,3 +74,4 @@ export { pinInput } from './pinInput.js';
 export { copyButton } from './copyButton.js';
 export { countdown } from './countdown.js';
 export { kbd } from './kbd.js';
+export { highlight } from './highlight.js';

packages/skin/ui/src/types.ts

@@ -286,6 +286,12 @@ export interface KbdProps {
   keys: string | string[]; // 按键内容：单键字符串或多键组合数组（组合以 + 连接展示）
 }
 
+/*** 关键词高亮入参 ***/
+export interface HighlightProps {
+  text: string | Signal<string>;    // 原文；传信号则响应式刷新
+  keyword: string | Signal<string>; // 关键词（大小写不敏感、全部命中，首尾空白忽略）；空串不高亮
+}
+
 /*** 空状态入参 ***/
 export interface EmptyProps {
   title?: string;       // 主标题；缺省不渲染

packages/skin/ui/ua.manifest.json

@@ -88,7 +88,8 @@
       "pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示",
       "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand",
       "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset",
-      "kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示"
+      "kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示",
+      "highlight(props)：关键词高亮，命中片段包 mark（大小写不敏感全部命中），text / keyword 支持信号响应式刷新"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -3866,6 +3867,31 @@
           "传数组展示组合键：kbd({ keys: [\"Ctrl\", \"K\"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）",
           "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感"
         ]
+      },
+      {
+        "id": "highlight",
+        "title": "关键词高亮 Highlight",
+        "demo": "sec-highlight",
+        "props": [
+          {
+            "n": "text",
+            "t": "string | Signal<string>",
+            "r": 1,
+            "d": "原文；传信号则随信号变化响应式重画"
+          },
+          {
+            "n": "keyword",
+            "t": "string | Signal<string>",
+            "r": 1,
+            "d": "关键词（大小写不敏感、全部命中，首尾空白忽略）；空串不高亮、原样展示"
+          }
+        ],
+        "example": "highlight({ text: 'Alpha Beta', keyword: 'beta' })",
+        "steps": [
+          "传 text + keyword 即可，命中片段以淡黄 mark 底展示，适合搜索结果 / 补全列表的匹配说明",
+          "两个入参都接受信号：搜索框输入实时联动高亮，无需手动重渲染",
+          "大小写不敏感且全部命中（非只第一处）；关键词两侧空白自动忽略"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -5229,3 +5229,12 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
   color: var(--ua-color-text-muted);
   font-size: var(--ua-font-size-xs);
 }
+
+/* ---- 关键词高亮（highlight） ---- */
+.ua-highlight-mark {
+  padding: 0 var(--ua-space-05);
+  border-radius: var(--ua-radius-sm);
+  background: color-mix(in srgb, var(--ua-color-warning) var(--ua-alpha-tint), transparent); /* 高亮淡底：警示黄浅混，不抢正文 */
+  color: inherit;
+  font-weight: var(--ua-weight-medium);
+}