iter(e04): 新增 empty 空状态组件

.ua/backlog.json

@@ -300,6 +300,14 @@
       "acceptance": "packages/skin/ui 新增 rate.ts：rate({value, max?, disabled?, onChange?})，max 缺省 5，hover 预览移出还原，键盘 ←→/↑↓ 调节，aria 星标语义；只消费 --ua-* 令牌；导出、manifest、文档、llms-full.txt、README 清单同步；demo 加一节演示；npm run check 全绿",
       "status": "done",
       "notes": "rate(props)：hover 预览用组件内局部 hover 信号（容器 mouseleave 归零），shown = hover || value 决定点亮数；value/hover 变化整条重渲染（与 stepper 同款 effect + replaceWith 模式）；键盘 →/↑ 加分 ←/↓ 减分并 clamp [1,max]；role=slider + aria-valuenow；选中色取 --ua-color-warning 金黄；demo 新增 sec-rate（可交互 + 只读两实例共用 score 信号）；README 同步 31 组件"
+    },
+    {
+      "id": "e04",
+      "title": "新增 empty 空状态组件",
+      "motivation": "列表、表格、搜索无结果时需要统一的占位提示，dataTable 内置空态样式但独立场景（卡片、面板、筛选结果）没有可复用组件",
+      "acceptance": "packages/skin/ui 新增 empty.ts：empty({title?, description?, action?})，居中排版，action 为可选 DOM 操作区（常见放按钮）；只消费 --ua-* 令牌；导出、manifest、文档、llms-full.txt、README 清单同步；demo 加一节演示；npm run check 全绿",
+      "status": "done",
+      "notes": "empty(props)：纯静态组件（无信号），role=status 由读屏播报；装饰符号 ⌀ 弱化为边框色且 aria-hidden；min-height 120px 撑留白（令牌只到 space-4）；demo 新增 sec-empty（信号切换有数据/无结果对比，内容用响应式函数渲染）；README 同步 32 组件"
     }
   ]
 }

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-23T10:03:21.198Z",
+  "generatedAt": "2026-10-23T10:11:22.346Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -169,6 +169,7 @@
           "tabs(props)：标签页，active 信号双向绑定，滑动指示条 + 方向键环形导航，支持禁用页签",
           "stepper(props)：步骤条，done/current/upcoming 三态，active 信号双向绑定，clickable 时已完成步骤可回跳",
           "rate(props)：评分星标，value 信号双向绑定，hover 预览移出还原，键盘方向键调节，max 可配",
+          "empty(props)：空状态占位，title/description 可选，action 放操作区",
           "modal(props, ...children)：弹窗，open 信号驱动显隐，Esc / 遮罩 / × 关闭，size 三档宽度，footer 提供底部操作区",
           "drawer(props, ...children)：抽屉，open 信号驱动侧滑面板，placement 左右可配、width 可调、footer 操作区，遮罩 / × / Esc 关闭",
           "form(props, items)：表单容器，布局 + 聚合校验，全部通过才触发 onSubmit",
@@ -1181,6 +1182,34 @@
               "max 可调整星标总数；disabled 支持布尔或信号禁用"
             ]
           },
+          {
+            "id": "empty",
+            "title": "空状态 Empty",
+            "demo": "sec-empty",
+            "props": [
+              {
+                "n": "title",
+                "t": "string",
+                "d": "主标题；缺省不渲染"
+              },
+              {
+                "n": "description",
+                "t": "string",
+                "d": "补充说明；缺省不渲染"
+              },
+              {
+                "n": "action",
+                "t": "unknown",
+                "d": "操作区内容（常见为按钮）；缺省不渲染"
+              }
+            ],
+            "example": "empty({ title: '暂无数据', description: '调整筛选条件后再试', action: button({ label: '重置筛选', variant: 'ghost' }) })",
+            "steps": [
+              "在列表 / 表格 / 筛选结果为空时渲染 empty 占位",
+              "title 一句话说明状态，description 补充原因或建议",
+              "action 传入 DOM（如 ghost 按钮）引导用户下一步操作"
+            ]
+          },
           {
             "id": "pagination",
             "title": "分页器 Pagination",
@@ -1482,6 +1511,7 @@
           "ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt",
           "ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1",
           "ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）",
+          "ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1",
           "ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components"
         ],
         "keyTypes": [
@@ -1489,7 +1519,7 @@
           "MCP tool 入参 schema"
         ]
       },
-      "usage": "node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|style|verify|mcp>；仓库内等价于 npm run index / docs / style / verify",
+      "usage": "node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify",
       "conventions": [
         "零依赖：只用 node 标准库，Node >= 18",
         "清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生",

.ua/iterations.log

@@ -37,3 +37,4 @@
 {"ts":"2026-10-23T17:50:14+08:00","id":"e01","result":"done","commit":"20d7b94","summary":"新增 inputNumber 数字输入：−/+ 按钮 + 键盘上下步进，信号双向绑定，min/max/step 夹取，门禁全绿"}
 {"ts":"2026-10-23T17:57:31+08:00","id":"e02","result":"done","commit":"fc7a1e8","summary":"新增 stepper 步骤条：三态流转 + active 信号双向绑定 + clickable 回跳，门禁全绿"}
 {"ts":"2026-10-23T18:03:34+08:00","id":"e03","result":"done","commit":"ee20322","summary":"新增 rate 评分组件：星标点选 + hover 预览 + 键盘方向键调节，信号双向绑定，门禁全绿"}
+{"ts":"2026-10-23T18:11:46+08:00","id":"e04","result":"done","commit":"pending","summary":"新增 empty 空状态组件：title/description/action 居中占位，静态零依赖，门禁全绿"}

README.md

@@ -11,13 +11,13 @@ npm run demo            # 打开演示：apps/demo/dist/demo.html
 npm run docs            # 生成人类文档站 apps/docs/index.html + Agent 全量文档 llms-full.txt
 ```
 
-## 组件（共 31 个）
+## 组件（共 32 个）
 
 <!-- ua:components -->
-accordion · alert · avatar · badge · breadcrumb · button · card · checkbox · dataTable · drawer · form · inputNumber · menu · modal · pagination · popover · progress · radioGroup · rate · select · skeleton · slider · spinner · stepper · switchButton · tabs · tag · textField · textarea · toast · tooltip
+accordion · alert · avatar · badge · breadcrumb · button · card · checkbox · dataTable · drawer · empty · form · inputNumber · menu · modal · pagination · popover · progress · radioGroup · rate · select · skeleton · slider · spinner · stepper · switchButton · tabs · tag · textField · textarea · toast · tooltip
 <!-- /ua:components -->
 
-分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / form / formItem）、反馈（alert / toast / spinner / progress / skeleton / badge）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper）、数据（dataTable / tag / avatar / card）。
+分组：表单（button / textField / inputNumber / textarea / checkbox / switchButton / select / radioGroup / slider / rate / form / formItem）、反馈（alert / toast / spinner / progress / skeleton / badge / empty）、浮层（tooltip / popover / modal / drawer / menu）、导航（tabs / breadcrumb / pagination / accordion / stepper）、数据（dataTable / tag / avatar / card）。
 
 ## 目录
 
@@ -25,7 +25,7 @@ accordion · alert · avatar · badge · breadcrumb · button · card · checkbo
 |---|---|
 | `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：31 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
+| `packages/skin/ui` | @ui-arch/ui：32 个 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

@@ -10,6 +10,7 @@ import {
   checkbox,
   dataTable,
   drawer,
+  empty,
   form,
   formItem,
   inputNumber,
@@ -123,6 +124,9 @@ const stepIdx = signal(0);
 // —— 评分：满意度演示，与只读实例共用同一信号 ——
 const score = signal(0);
 
+// —— 空状态：搜索无结果演示 ——
+const noResult = signal(true);
+
 // —— 受控选中：dataTable 内部勾选实时写回，外部可清空 ——
 const picked = signal<RowKey[]>([]);
 
@@ -379,6 +383,20 @@ const content = h(
     ),
     h('div', { class: 'row' }, rate({ value: score, disabled: true })),
   ),
+  section(
+    'sec-empty',
+    '空状态',
+    'empty：无数据 / 无结果的统一占位，action 放引导按钮，点击按钮切回有数据态可对比。',
+    h('div', { class: 'row' }, h('span', { class: 'out' }, () => (noResult() ? '当前：无结果' : '当前：有数据'))),
+    h(
+      'div',
+      { class: 'row' },
+      button({ label: '切换数据态', onClick: () => noResult(!noResult()) }),
+    ),
+    () => (noResult()
+      ? empty({ title: '暂无匹配结果', description: '试试放宽筛选条件，或清空关键词重新搜索。', action: button({ label: '重置筛选', variant: 'ghost', onClick: () => noResult(false) }) })
+      : card({ title: '搜索结果' }, h('p', null, '这里展示命中的数据列表。'))),
+  ),
   section(
     'sec-menu',
     '下拉菜单',

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-23T10:03:21.198Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-23T10:11:22.346Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -674,6 +674,28 @@ const score = signal(0); rate({ value: score, max: 5, onChange: (v) => console.l
 
 现场演示：apps/docs/demo.html#sec-rate
 
+### empty — 空状态 Empty
+
+参数：
+
+- title：string —— 主标题；缺省不渲染
+- description：string —— 补充说明；缺省不渲染
+- action：unknown —— 操作区内容（常见为按钮）；缺省不渲染
+
+示例：
+
+```
+empty({ title: '暂无数据', description: '调整筛选条件后再试', action: button({ label: '重置筛选', variant: 'ghost' }) })
+```
+
+手把手：
+
+1. 在列表 / 表格 / 筛选结果为空时渲染 empty 占位
+2. title 一句话说明状态，description 补充原因或建议
+3. action 传入 DOM（如 ghost 按钮）引导用户下一步操作
+
+现场演示：apps/docs/demo.html#sec-empty
+
 ### pagination — 分页器 Pagination
 
 参数：
@@ -851,6 +873,7 @@ API 速览：
 - tabs(props)：标签页，active 信号双向绑定，滑动指示条 + 方向键环形导航，支持禁用页签
 - stepper(props)：步骤条，done/current/upcoming 三态，active 信号双向绑定，clickable 时已完成步骤可回跳
 - rate(props)：评分星标，value 信号双向绑定，hover 预览移出还原，键盘方向键调节，max 可配
+- empty(props)：空状态占位，title/description 可选，action 放操作区
 - modal(props, ...children)：弹窗，open 信号驱动显隐，Esc / 遮罩 / × 关闭，size 三档宽度，footer 提供底部操作区
 - drawer(props, ...children)：抽屉，open 信号驱动侧滑面板，placement 左右可配、width 可调、footer 操作区，遮罩 / × / Esc 关闭
 - form(props, items)：表单容器，布局 + 聚合校验，全部通过才触发 onSubmit
@@ -953,12 +976,13 @@ API 速览：
 - ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
 - ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
 - ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）
+- ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
 - ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components
 
 一行用法：
 
 ```
-node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|style|verify|mcp>；仓库内等价于 npm run index / docs / style / verify
+node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify
 ```
 
 约定：

llms.txt

@@ -74,6 +74,7 @@
   - tabs(props)：标签页，active 信号双向绑定，滑动指示条 + 方向键环形导航，支持禁用页签
   - stepper(props)：步骤条，done/current/upcoming 三态，active 信号双向绑定，clickable 时已完成步骤可回跳
   - rate(props)：评分星标，value 信号双向绑定，hover 预览移出还原，键盘方向键调节，max 可配
+  - empty(props)：空状态占位，title/description 可选，action 放操作区
   - modal(props, ...children)：弹窗，open 信号驱动显隐，Esc / 遮罩 / × 关闭，size 三档宽度，footer 提供底部操作区
   - drawer(props, ...children)：抽屉，open 信号驱动侧滑面板，placement 左右可配、width 可调、footer 操作区，遮罩 / × / Esc 关闭
   - form(props, items)：表单容器，布局 + 聚合校验，全部通过才触发 onSubmit
@@ -96,8 +97,9 @@
   - ua docs：生成人类文档站 apps/docs/index.html + demo.html 与 Agent 全量文档 llms-full.txt
   - ua style：注释规范门禁（导出必须 /*** ***/、接口字段行尾注释、行注释中文），违规退出码 1
   - ua verify：清单一致性门禁（id 唯一 / exports 对应 / props 必带 n t d / steps≥3 / demo 锚点存在）
+  - ua commit-lint <文件|message>：提交信息门禁（type 枚举 / scope 规则 / subject 中文祈使 ≤50 字符），规范见 COMMITTING.md，违规退出码 1
   - ua mcp：零依赖 stdio MCP server，暴露 list_components / get_component / search_components
-- 用法: `node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|style|verify|mcp>；仓库内等价于 npm run index / docs / style / verify`
+- 用法: `node packages/tools/cli/bin/ua.js <index|list|info <name>|docs|style|verify|commit-lint|mcp>；仓库内等价于 npm run index / docs / style / verify`
 - 约定: 零依赖：只用 node 标准库，Node >= 18
 - 约定: 清单是单一来源：代码注释、文档站、llms-full.txt、MCP 全部从 ua.manifest.json 派生
 - 约定: 门禁只增不改：新增校验必须能被人手复现，报错要指出文件与字段

packages/skin/ui/src/empty.ts

@@ -0,0 +1,14 @@
+import { h } from '@ui-arch/frame';
+import type { EmptyProps } from './types.js';
+
+/*** 空状态：居中占位提示，title/description 可选，action 放操作区（常见为按钮） ***/
+export function empty(props: EmptyProps): HTMLDivElement {
+  return h(
+    'div',
+    { class: 'ua-empty', role: 'status' }, // role=status 由读屏播报
+    h('div', { class: 'ua-empty-icon', 'aria-hidden': 'true' }, '⌀'), // 装饰符号，读屏跳过
+    props.title ? h('div', { class: 'ua-empty-title' }, props.title) : null,
+    props.description ? h('div', { class: 'ua-empty-desc' }, props.description) : null,
+    props.action ? h('div', { class: 'ua-empty-action' }, props.action) : null,
+  ) as HTMLDivElement;
+}

packages/skin/ui/src/index.ts

@@ -26,6 +26,7 @@ export { progress } from './progress.js';
 export { tabs } from './tabs.js';
 export { stepper } from './stepper.js';
 export { rate } from './rate.js';
+export { empty } from './empty.js';
 export { modal } from './modal.js';
 export { drawer } from './drawer.js';
 export { form, formItem } from './form.js';

packages/skin/ui/src/types.ts

@@ -197,6 +197,13 @@ export interface RateProps {
   onChange?: (value: number) => void;   // 评分变化回调
 }
 
+/*** 空状态入参 ***/
+export interface EmptyProps {
+  title?: string;       // 主标题；缺省不渲染
+  description?: string; // 补充说明；缺省不渲染
+  action?: unknown;     // 操作区内容（常见为按钮）；缺省不渲染
+}
+
 /*** 徽标入参 ***/
 export interface BadgeProps {
   label: string; // 徽标文案

packages/skin/ui/ua.manifest.json

@@ -40,6 +40,7 @@
       "tabs(props)：标签页，active 信号双向绑定，滑动指示条 + 方向键环形导航，支持禁用页签",
       "stepper(props)：步骤条，done/current/upcoming 三态，active 信号双向绑定，clickable 时已完成步骤可回跳",
       "rate(props)：评分星标，value 信号双向绑定，hover 预览移出还原，键盘方向键调节，max 可配",
+      "empty(props)：空状态占位，title/description 可选，action 放操作区",
       "modal(props, ...children)：弹窗，open 信号驱动显隐，Esc / 遮罩 / × 关闭，size 三档宽度，footer 提供底部操作区",
       "drawer(props, ...children)：抽屉，open 信号驱动侧滑面板，placement 左右可配、width 可调、footer 操作区，遮罩 / × / Esc 关闭",
       "form(props, items)：表单容器，布局 + 聚合校验，全部通过才触发 onSubmit",
@@ -1052,6 +1053,34 @@
           "max 可调整星标总数；disabled 支持布尔或信号禁用"
         ]
       },
+      {
+        "id": "empty",
+        "title": "空状态 Empty",
+        "demo": "sec-empty",
+        "props": [
+          {
+            "n": "title",
+            "t": "string",
+            "d": "主标题；缺省不渲染"
+          },
+          {
+            "n": "description",
+            "t": "string",
+            "d": "补充说明；缺省不渲染"
+          },
+          {
+            "n": "action",
+            "t": "unknown",
+            "d": "操作区内容（常见为按钮）；缺省不渲染"
+          }
+        ],
+        "example": "empty({ title: '暂无数据', description: '调整筛选条件后再试', action: button({ label: '重置筛选', variant: 'ghost' }) })",
+        "steps": [
+          "在列表 / 表格 / 筛选结果为空时渲染 empty 占位",
+          "title 一句话说明状态，description 补充原因或建议",
+          "action 传入 DOM（如 ghost 按钮）引导用户下一步操作"
+        ]
+      },
       {
         "id": "pagination",
         "title": "分页器 Pagination",

packages/skin/ui/ui.css

@@ -814,6 +814,35 @@ button.ua-step-dot:hover {
   border-radius: 4px;
 }
 
+/* —— 空状态 —— */
+.ua-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: var(--ua-space-2);
+  padding: var(--ua-space-4);
+  min-height: 120px; /* 撑出足够留白感 */
+  justify-content: center;
+  text-align: center;
+}
+.ua-empty-icon {
+  font-size: 34px;
+  line-height: 1;
+  color: var(--ua-color-border); /* 装饰符号弱化为边框色 */
+}
+.ua-empty-title {
+  font-size: var(--ua-font-size-md);
+  font-weight: 600;
+  color: var(--ua-color-text);
+}
+.ua-empty-desc {
+  font-size: var(--ua-font-size-sm);
+  color: var(--ua-color-text-muted);
+}
+.ua-empty-action {
+  margin-top: var(--ua-space-1);
+}
+
 /* —— 徽标 —— */
 .ua-badge {
   display: inline-block;