diff --git a/.ua/index.json b/.ua/index.json index 7f6117d..c054bff 100644 --- a/.ua/index.json +++ b/.ua/index.json @@ -1,6 +1,6 @@ { "$schema": "ui-arch-registry-index/0.1", - "generatedAt": "2026-10-26T13:28:41.290Z", + "generatedAt": "2026-10-26T13:30:37.089Z", "repoRoot": ".", "packages": [ { @@ -216,7 +216,8 @@ "timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起", "pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示", "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand", - "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset" + "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset", + "kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示" ], "keyTypes": [ "ButtonProps", @@ -3975,6 +3976,25 @@ "归零自动停表并触发 onFinish；之后 start() 会重开一轮，reset() 复位到总时长", "format 自定义展示：如只显示秒 (s) => `${s}s`，或带上小时位" ] + }, + { + "id": "kbd", + "title": "键盘按键 Kbd", + "demo": "sec-kbd", + "props": [ + { + "n": "keys", + "t": "string | string[]", + "r": 1, + "d": "按键内容：单键字符串或多键组合数组（组合以 + 连接展示）" + } + ], + "example": "kbd({ keys: 'Esc' })、kbd({ keys: ['Ctrl', 'K'] })", + "steps": [ + "传字符串展示单键帽：kbd({ keys: \"Esc\" })，适合文档里说明单个按键", + "传数组展示组合键：kbd({ keys: [\"Ctrl\", \"K\"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）", + "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感" + ] } ] }, diff --git a/AGENTS.md b/AGENTS.md index a8c10fe..05446d4 100644 --- a/AGENTS.md +++ b/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）：73 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌 +- `packages/skin/ui`（@ui-arch/ui）：74 个 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 diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md index d1ab00c..ae73bea 100644 --- a/ARCHITECTURE.md +++ b/ARCHITECTURE.md @@ -34,7 +34,7 @@ ui-arch-mvp/ │ │ ├── table-core/ # 表格状态内核 │ │ └── frame/ # 信号 + hyperscript 微框架 │ ├── skin/ # 皮肤层（DOM 组件，可发布） -│ │ └── ui/ # 73 个组件 + ui.css +│ │ └── ui/ # 74 个组件 + ui.css │ ├── design/ # 资产层（可发布） │ │ └── tokens/ # --ua-* 设计令牌 │ └── tools/ # 工程层（private，不发布） diff --git a/README.md b/README.md index 60f4803..b8e6958 100644 --- a/README.md +++ b/README.md @@ -12,13 +12,13 @@ npm run docs # 生成人类文档站 apps/docs/index.html + Agent 全 npm run changelog # 依据 git 提交史重写 CHANGELOG.md（发版前跑；changelog:check 可查漂移） ``` -## 组件（共 73 个） +## 组件（共 74 个） -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 · 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 · 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 -分组：表单（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 / 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 / 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：73 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | +| `packages/skin/ui` | @ui-arch/ui：74 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） | | `packages/design/tokens` | @ui-arch/tokens：设计令牌（暗色只换值不换名） | | `packages/tools/cli` | @ui-arch/cli：`ua` 命令行与 stdio MCP server | | `apps/demo` | 交互演示（esbuild 打包成单文件） | diff --git a/apps/demo/main.ts b/apps/demo/main.ts index 90715b0..7c6edcf 100644 --- a/apps/demo/main.ts +++ b/apps/demo/main.ts @@ -30,6 +30,7 @@ import { copyButton, countdown, dataTable, + kbd, datePicker, transfer, descriptions, @@ -1121,6 +1122,19 @@ const content = h( h('span', { class: 'out' }, '第二个示例初始暂停，点按钮重开'), ), ), + section( + 'sec-kbd', + '键盘按键', + 'kbd：键帽样式展示按键提示，单键直传字符串，组合键传数组以 + 连接（+ 对读屏隐藏）。', + h( + 'div', + { class: 'row' }, + kbd({ keys: 'Esc' }), + kbd({ keys: ['Ctrl', 'K'] }), + kbd({ keys: ['Shift', 'Enter'] }), + h('span', { class: 'out' }, '按 ', kbd({ keys: ['Ctrl', 'K'] }), ' 唤起演示页命令面板'), + ), + ), section( 'sec-affix', '固钉', diff --git a/llms-full.txt b/llms-full.txt index 671c952..28a7b2b 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -1,6 +1,6 @@ # @ui-arch 组件库 Agent 文档（无图形版） -> 自动生成于 2026-10-26T13:28:41.290Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 +> 自动生成于 2026-10-26T13:30:37.089Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。 ## 快速上手 @@ -2097,6 +2097,26 @@ const cd = countdown({ seconds: 60, onFinish: () => console.log('结束') }); // 现场演示：apps/docs/demo.html#sec-countdown +### kbd — 键盘按键 Kbd + +参数： + +- keys（必填）：string | string[] —— 按键内容：单键字符串或多键组合数组（组合以 + 连接展示） + +示例： + +``` +kbd({ keys: 'Esc' })、kbd({ keys: ['Ctrl', 'K'] }) +``` + +手把手： + +1. 传字符串展示单键帽：kbd({ keys: "Esc" })，适合文档里说明单个按键 +2. 传数组展示组合键：kbd({ keys: ["Ctrl", "K"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏） +3. 常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感 + +现场演示：apps/docs/demo.html#sec-kbd + API 速览： - button(props)：按钮，variant = primary | ghost | danger，disabled 支持布尔或信号禁用；type 缺省 button（表单内不隐式提交） @@ -2174,6 +2194,7 @@ API 速览： - pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示 - copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand - countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset +- kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示 一行用法： diff --git a/llms.txt b/llms.txt index b416fbc..8105aac 100644 --- a/llms.txt +++ b/llms.txt @@ -122,6 +122,7 @@ - pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示 - copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand - countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset + - kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示 - 用法: `const checked = signal(false); checkbox({ label: '同意', checked }); const open = signal(false); modal({ title: '确认', open }, '内容')` - 约定: 皮肤不持有业务状态，一律委托 headless 内核或调用方信号 - 约定: 表单类组件统一约定：*Props.value/checked/active 为 Signal 双向绑定，onChange/onInput 为回调 diff --git a/packages/skin/ui/src/index.ts b/packages/skin/ui/src/index.ts index 9a1fcf4..7a63eab 100644 --- a/packages/skin/ui/src/index.ts +++ b/packages/skin/ui/src/index.ts @@ -73,3 +73,4 @@ export { timePicker } from './timePicker.js'; export { pinInput } from './pinInput.js'; export { copyButton } from './copyButton.js'; export { countdown } from './countdown.js'; +export { kbd } from './kbd.js'; diff --git a/packages/skin/ui/src/kbd.ts b/packages/skin/ui/src/kbd.ts new file mode 100644 index 0000000..ce1e8a1 --- /dev/null +++ b/packages/skin/ui/src/kbd.ts @@ -0,0 +1,10 @@ +import { h } from '@ui-arch/frame'; +import type { KbdProps } from './types.js'; + +/*** 键盘按键标记：键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示 ***/ +export function kbd(props: KbdProps): HTMLElement { + const keys = Array.isArray(props.keys) ? props.keys : [props.keys]; // 统一成数组：单键 / 组合键同一渲染路径 + const parts: (Node | null)[] = keys.map((k, i) => (i > 0 ? h('span', { class: 'ua-kbd-sep', 'aria-hidden': 'true' }, '+') : null)); // 分隔符占位 + keys.forEach((k, i) => parts[i * 2 + 1] = h('kbd', { class: 'ua-kbd-key' }, k)); // 键帽交错插入：sep, key, sep, key… + return h('span', { class: 'ua-kbd' }, ...parts); +} diff --git a/packages/skin/ui/src/types.ts b/packages/skin/ui/src/types.ts index 890d769..856326e 100644 --- a/packages/skin/ui/src/types.ts +++ b/packages/skin/ui/src/types.ts @@ -281,6 +281,11 @@ export interface CountdownHandle { reset: () => void; // 复位到总时长并停表 } +/*** 键盘按键入参 ***/ +export interface KbdProps { + keys: string | string[]; // 按键内容：单键字符串或多键组合数组（组合以 + 连接展示） +} + /*** 空状态入参 ***/ export interface EmptyProps { title?: string; // 主标题；缺省不渲染 diff --git a/packages/skin/ui/ua.manifest.json b/packages/skin/ui/ua.manifest.json index 092dbf5..d590670 100644 --- a/packages/skin/ui/ua.manifest.json +++ b/packages/skin/ui/ua.manifest.json @@ -87,7 +87,8 @@ "timePicker(props)：时间选择，时 / 分两列弹层，value 信号双向绑定 HH:mm，分钟可配步长，Esc 收起", "pinInput(props)：验证码输入，N 格单字符数字输入，输入自动进格、退格回删、方向键移格、粘贴自动分发，value 信号双向绑定，mask 可密文显示", "copyButton(props)：复制按钮，点击把 text 写入剪贴板并短暂显示已复制，text 可传函数取实时值，clipboard API 不可用时降级 execCommand", - "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset" + "countdown(props)：倒计时，秒级递减到 0 自动停表并触发 onFinish，缺省 mm:ss 展示，返回句柄 start/stop/reset", + "kbd(props)：键盘按键标记，键帽样式展示单个按键或组合键（多键以 + 连接），用于快捷键提示" ], "keyTypes": [ "ButtonProps", @@ -3846,6 +3847,25 @@ "归零自动停表并触发 onFinish；之后 start() 会重开一轮，reset() 复位到总时长", "format 自定义展示：如只显示秒 (s) => `${s}s`，或带上小时位" ] + }, + { + "id": "kbd", + "title": "键盘按键 Kbd", + "demo": "sec-kbd", + "props": [ + { + "n": "keys", + "t": "string | string[]", + "r": 1, + "d": "按键内容：单键字符串或多键组合数组（组合以 + 连接展示）" + } + ], + "example": "kbd({ keys: 'Esc' })、kbd({ keys: ['Ctrl', 'K'] })", + "steps": [ + "传字符串展示单键帽：kbd({ keys: \"Esc\" })，适合文档里说明单个按键", + "传数组展示组合键：kbd({ keys: [\"Ctrl\", \"K\"] })，键帽之间以弱化的 + 连接（+ 对读屏隐藏）", + "常与提示文案混排：行内 baseline 对齐，键帽底边加厚一线出立体感" + ] } ] } diff --git a/packages/skin/ui/ui.css b/packages/skin/ui/ui.css index 3846238..918ec21 100644 --- a/packages/skin/ui/ui.css +++ b/packages/skin/ui/ui.css @@ -5202,3 +5202,30 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); } .ua-countdown { font-variant-numeric: tabular-nums; /* 数字等宽：秒跳不抖动 */ } + +/* ---- 键盘按键标记（kbd） ---- */ +.ua-kbd { + display: inline-flex; + align-items: center; + gap: var(--ua-space-05); + vertical-align: middle; +} +.ua-kbd-key { + display: inline-flex; + align-items: center; + justify-content: center; + min-width: var(--ua-control-h-sm); + height: var(--ua-control-h-sm); + padding: 0 var(--ua-space-15); + border: 1px solid var(--ua-color-border); + border-bottom-width: 2px; /* 底边加厚一线：键帽立体感 */ + border-radius: var(--ua-radius-sm); + background: var(--ua-color-surface); + color: var(--ua-color-text); + font-size: var(--ua-font-size-sm); + line-height: var(--ua-leading-none); +} +.ua-kbd-sep { + color: var(--ua-color-text-muted); + font-size: var(--ua-font-size-xs); +}