iter(g273): 新增区域加载遮罩组件

.ua/index.json

@@ -1,6 +1,6 @@
 {
   "$schema": "ui-arch-registry-index/0.1",
-  "generatedAt": "2026-10-26T14:56:09.624Z",
+  "generatedAt": "2026-10-26T14:58:51.630Z",
   "repoRoot": ".",
   "packages": [
     {
@@ -224,7 +224,8 @@
           "jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑",
           "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
           "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮",
-          "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）"
+          "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）",
+          "loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁"
         ],
         "keyTypes": [
           "ButtonProps",
@@ -4347,6 +4348,46 @@
               "需要判空用 handle.isEmpty()，取图用 handle.toDataURL()；两者与信号同源，不会出现「有图但信号是空」",
               "禁用传布尔或信号：布尔直接置位，信号随状态变灰并挡住手写；移动端画布已关掉浏览器手势，不会边签边滚页"
             ]
+          },
+          {
+            "id": "loading",
+            "title": "区域加载遮罩 Loading",
+            "demo": "sec-loading",
+            "props": [
+              {
+                "n": "active",
+                "t": "boolean | Signal<boolean>",
+                "d": "是否加载中：布尔直接置位，传信号则随状态显隐"
+              },
+              {
+                "n": "text",
+                "t": "string",
+                "d": "遮罩文案；缺省只显示转圈（读屏仍报「内容加载中」）"
+              },
+              {
+                "n": "delay",
+                "t": "number",
+                "d": "出场延迟（ms）；缺省 120，快请求不闪遮罩"
+              },
+              {
+                "n": "spinnerSize",
+                "t": "number",
+                "d": "转圈直径（px）；缺省 20"
+              },
+              {
+                "n": "minHeight",
+                "t": "number",
+                "d": "最小高度（px）；内容为空时兜住遮罩高度"
+              }
+            ],
+            "example": "loading({ active: busy, text: '正在刷新订单' }, dataTable({ ... }))",
+            "steps": [
+              "把要遮挡的那块内容作为 children 交进来，active 传布尔或信号：刷新时盖上遮罩，数据回来后自动收起",
+              "内容不隐藏、只降透明度——布局与尺寸原地保留，遮罩收起时不会跳一下",
+              "默认延迟 120ms 出场：接口快于这个时间就不闪遮罩；想立刻显示传 delay: 0",
+              "遮罩文案写明在等什么（「正在刷新订单」），读屏同一句也会播报；只要转圈就省略 text",
+              "内容可能为空时给 minHeight，否则高度塌成 0 遮罩无处可盖"
+            ]
           }
         ]
       },

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）：81 个 DOM 组件（表单 / 反馈 / 浮层 / 导航 / 表格），样式只消费令牌
+- `packages/skin/ui`（@ui-arch/ui）：82 个 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/               # 81 个组件 + ui.css
+│   │   └── ui/               # 82 个组件 + 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 可查漂移）
 ```
 
-## 组件（共 81 个）
+## 组件（共 82 个）
 
 <!-- ua:components -->
-accordion · affix · alert · anchor · autoComplete · avatar · avatarGroup · backTop · badge · breadcrumb · button · calendar · carousel · card · cascader · checkbox · checkboxGroup · codeBlock · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · signaturePad · 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 · codeBlock · colorPicker · commandPalette · copyButton · countdown · dataTable · datePicker · descriptions · diffView · divider · drawer · empty · floatButton · form · grid · highlight · image · inputNumber · inputTag · jsonViewer · kbd · layout · link · list · loading · menu · modal · mentions · multiSelect · notification · pagination · pinInput · popover · popconfirm · progress · radioGroup · rate · result · segmented · select · signaturePad · 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 / signaturePad / textField / inputNumber / inputTag / 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 / jsonViewer / diffView / codeBlock / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。
+分组：表单（button / copyButton / signaturePad / textField / inputNumber / inputTag / textarea / checkbox / checkboxGroup / colorPicker / switchButton / select / mentions / multiSelect / radioGroup / slider / rate / autoComplete / datePicker / timePicker / pinInput / segmented / upload / form + formItem / transfer / cascader）、反馈（alert / loading / 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 / jsonViewer / diffView / codeBlock / descriptions / card / list / kbd / highlight / timeline / tag / avatar / avatarGroup / image / carousel / calendar / typography / virtualList）、其他（floatButton / grid / layout / link / space / divider / splitter / backTop / affix / tour / watermark）。
 
 ## 可访问性约定
 
@@ -34,7 +34,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：81 个 DOM 组件 + ui.css（只消费 `--ua-*` 令牌） |
+| `packages/skin/ui` | @ui-arch/ui：82 个 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

@@ -50,6 +50,7 @@ import {
   inputTag,
   grid,
   link,
+  loading,
   list,
   carousel,
   treeSelect,
@@ -1795,6 +1796,23 @@ const content = h(
       return h('div', null, pad.el, h('div', { class: 'out' }, () => (sign() ? '已签字（dataURL 长度 ' + sign().length + '）' : '尚未签字')));
     })(),
   ),
+  section(
+    'sec-loading',
+    '区域加载遮罩',
+    'loading：把要遮挡的块交进 children，active 为真时盖上遮罩；默认延迟 120ms 出场——接口快于这个时间就不闪，慢于它必有反馈。',
+    (() => {
+      const busy = signal(false);
+      const box = loading({
+        active: busy,
+        text: '正在刷新订单',
+        minHeight: 120,
+      }, card({ title: '订单概览' }, typography({ variant: 'paragraph', type: 'secondary', content: '这里是一块会被整体刷新的内容：遮罩盖住时它仍在原位、只是变淡。' })));
+      return h('div', { style: 'display:flex;flex-direction:column;gap:8px' },
+        button({ label: '切换刷新状态', onClick: () => busy(!busy()) }),
+        box,
+      );
+    })(),
+  ),
 );
 
 // 悬浮按钮：fixed 定位，挂 body 不参与页面布局

llms-full.txt

@@ -1,6 +1,6 @@
 # @ui-arch 组件库 Agent 文档（无图形版）
 
-> 自动生成于 2026-10-26T14:56:09.624Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
+> 自动生成于 2026-10-26T14:58:51.630Z，数据源：各包 ua.manifest.json，勿手改。人类版文档站：apps/docs/index.html。
 > 组件 = 普通函数，传 props 返回 DOM；状态用 signal 双向绑定：读 signal() 写 signal(v)。
 
 ## 快速上手
@@ -2315,6 +2315,32 @@ const pad = signaturePad({ value: sign, height: 140 }); mount('#box', () => pad.
 
 现场演示：apps/docs/demo.html#sec-sign
 
+### loading — 区域加载遮罩 Loading
+
+参数：
+
+- active：boolean | Signal<boolean> —— 是否加载中：布尔直接置位，传信号则随状态显隐
+- text：string —— 遮罩文案；缺省只显示转圈（读屏仍报「内容加载中」）
+- delay：number —— 出场延迟（ms）；缺省 120，快请求不闪遮罩
+- spinnerSize：number —— 转圈直径（px）；缺省 20
+- minHeight：number —— 最小高度（px）；内容为空时兜住遮罩高度
+
+示例：
+
+```
+loading({ active: busy, text: '正在刷新订单' }, dataTable({ ... }))
+```
+
+手把手：
+
+1. 把要遮挡的那块内容作为 children 交进来，active 传布尔或信号：刷新时盖上遮罩，数据回来后自动收起
+2. 内容不隐藏、只降透明度——布局与尺寸原地保留，遮罩收起时不会跳一下
+3. 默认延迟 120ms 出场：接口快于这个时间就不闪遮罩；想立刻显示传 delay: 0
+4. 遮罩文案写明在等什么（「正在刷新订单」），读屏同一句也会播报；只要转圈就省略 text
+5. 内容可能为空时给 minHeight，否则高度塌成 0 遮罩无处可盖
+
+现场演示：apps/docs/demo.html#sec-loading
+
 API 速览：
 
 - button(props)：按钮，variant 三档视觉强度，disabled / loading 支持布尔或信号动态同步（loading 转圈并禁点），onClick 点击回调
@@ -2400,6 +2426,7 @@ API 速览：
 - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计
 - codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮
 - signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）
+- loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁
 
 一行用法：
 

llms.txt

@@ -130,6 +130,7 @@
   - diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计
   - codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮
   - signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）
+  - loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁
 - 用法: `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/index.ts

@@ -81,3 +81,4 @@ export { jsonViewer } from './jsonViewer.js';
 export { diffView } from './diffView.js';
 export { codeBlock } from './codeBlock.js';
 export { signaturePad } from './signaturePad.js';
+export { loading } from './loading.js';

packages/skin/ui/src/loading.ts

@@ -0,0 +1,39 @@
+import { effect, h } from '@ui-arch/frame';
+import { spinner } from './spinner.js';
+import type { LoadingProps } from './types.js';
+
+// 缺省延迟：120ms 内的请求不闪遮罩，否则「点了就闪一下」比不显示更闹
+const DELAY = 120;
+
+/*** 区域加载遮罩：包住一块内容，active 为真时盖上层遮罩 + 转圈 + 文案；带延迟出场，快请求不闪、慢请求必有反馈 ***/
+export function loading(props: LoadingProps, ...children: unknown[]): HTMLElement {
+  const delay = props.delay ?? DELAY; // 延迟毫秒
+  let timer = 0;                       // 延迟计时器
+  const read = (): boolean => (typeof props.active === 'function' ? Boolean(props.active()) : props.active === true); // 布尔与信号同一口径
+  const mask = h(
+    'div',
+    { class: 'ua-loading-mask' },
+    spinner({ size: props.spinnerSize ?? 20, label: props.text ?? '内容加载中' }), // 转圈自带 role=status，这里只用它的可访问名
+    props.text ? h('span', { class: 'ua-loading-text' }, props.text) : null,
+  );
+  const wrap = h(
+    'div',
+    { class: 'ua-loading' },
+    h('div', { class: 'ua-loading-body' }, ...children), // 内容层：遮罩出现时整体降透明度，但仍留在原位不塌陷
+    mask,
+  );
+  if (props.minHeight !== undefined) wrap.style.minHeight = `${props.minHeight}px`; // 内容为空时也要撑出高度，遮罩才盖得住
+
+  /*** 状态落点：is-active 控制遮罩显隐，aria-busy 让读屏知道这块在等数据 ***/
+  const paint = (on: boolean): void => {
+    wrap.classList.toggle('is-active', on);
+    wrap.setAttribute('aria-busy', String(on));
+  };
+  effect(() => {
+    window.clearTimeout(timer);
+    if (!read()) { paint(false); return; } // 关得快：立刻收，不等延迟
+    timer = window.setTimeout(() => paint(true), delay); // 开得慢：先等一会儿，避免快速请求闪一下
+  });
+  paint(read()); // 首帧：初值为真时直接亮（延迟只管后续变化）
+  return wrap;
+}

packages/skin/ui/src/types.ts

@@ -1069,3 +1069,12 @@ export interface SignaturePadHandle {
   toDataURL(): string;                   // 取当前签字 PNG dataURL（未签也返回空白图）
   isEmpty(): boolean;                    // 是否尚未落笔
 }
+
+/*** 区域加载遮罩入参 ***/
+export interface LoadingProps {
+  active?: boolean | Signal<boolean>;  // 是否加载中：布尔直接置位，传信号则随状态显隐
+  text?: string;                       // 遮罩文案；缺省只显示转圈（读屏仍报「内容加载中」）
+  delay?: number;                      // 出场延迟（ms）；缺省 120，快请求不闪遮罩
+  spinnerSize?: number;                // 转圈直径（px）；缺省 20
+  minHeight?: number;                  // 最小高度（px）；内容为空时兜住遮罩高度
+}

packages/skin/ui/ua.manifest.json

@@ -95,7 +95,8 @@
       "jsonViewer(props)：JSON 树查看，按层折叠、分支带计数摘要、叶子按类型着色，只读不编辑",
       "diffView(props)：文本差异对比，行级 LCS 对齐 + 增删着色 + 双行号列，顶部带 +N / −N 统计",
       "codeBlock(props)：代码块，等宽多行 + 行号列 + 标题行 + 一键复制原文，只展示不高亮",
-      "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）"
+      "signaturePad(props)：手写签名板，指针绘制 + DPR 位图，返回 handle（el / clear / toDataURL / isEmpty）",
+      "loading(props, ...children)：区域加载遮罩，内容原地降透明度 + 转圈文案，带延迟出场避免快请求闪烁"
     ],
     "keyTypes": [
       "ButtonProps",
@@ -4218,6 +4219,46 @@
           "需要判空用 handle.isEmpty()，取图用 handle.toDataURL()；两者与信号同源，不会出现「有图但信号是空」",
           "禁用传布尔或信号：布尔直接置位，信号随状态变灰并挡住手写；移动端画布已关掉浏览器手势，不会边签边滚页"
         ]
+      },
+      {
+        "id": "loading",
+        "title": "区域加载遮罩 Loading",
+        "demo": "sec-loading",
+        "props": [
+          {
+            "n": "active",
+            "t": "boolean | Signal<boolean>",
+            "d": "是否加载中：布尔直接置位，传信号则随状态显隐"
+          },
+          {
+            "n": "text",
+            "t": "string",
+            "d": "遮罩文案；缺省只显示转圈（读屏仍报「内容加载中」）"
+          },
+          {
+            "n": "delay",
+            "t": "number",
+            "d": "出场延迟（ms）；缺省 120，快请求不闪遮罩"
+          },
+          {
+            "n": "spinnerSize",
+            "t": "number",
+            "d": "转圈直径（px）；缺省 20"
+          },
+          {
+            "n": "minHeight",
+            "t": "number",
+            "d": "最小高度（px）；内容为空时兜住遮罩高度"
+          }
+        ],
+        "example": "loading({ active: busy, text: '正在刷新订单' }, dataTable({ ... }))",
+        "steps": [
+          "把要遮挡的那块内容作为 children 交进来，active 传布尔或信号：刷新时盖上遮罩，数据回来后自动收起",
+          "内容不隐藏、只降透明度——布局与尺寸原地保留，遮罩收起时不会跳一下",
+          "默认延迟 120ms 出场：接口快于这个时间就不闪遮罩；想立刻显示传 delay: 0",
+          "遮罩文案写明在等什么（「正在刷新订单」），读屏同一句也会播报；只要转圈就省略 text",
+          "内容可能为空时给 minHeight，否则高度塌成 0 遮罩无处可盖"
+        ]
       }
     ]
   }

packages/skin/ui/ui.css

@@ -5740,3 +5740,42 @@ h5.ua-type-title { font-size: var(--ua-font-size-md); }
   color: var(--ua-color-text-faint);
   cursor: not-allowed;
 }
+
+/* ---- 区域加载遮罩：内容原样留在原位、只降透明度，遮罩盖在其上；不做模糊（糊字会让等待更焦虑） ---- */
+.ua-loading {
+  position: relative;
+  border-radius: var(--ua-radius-md);
+}
+
+.ua-loading-body {
+  transition: opacity var(--ua-duration-base) var(--ua-ease);
+}
+
+/* 遮罩：定位铺满整块，默认不可见也不拦事件；只有 is-active 才出场 */
+.ua-loading-mask {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--ua-space-2);
+  border-radius: inherit;
+  background: color-mix(in srgb, var(--ua-color-surface) var(--ua-alpha-strong), transparent);
+  opacity: 0;
+  visibility: hidden;
+  transition: opacity var(--ua-duration-fast) var(--ua-ease), visibility var(--ua-duration-fast) var(--ua-ease);
+}
+
+.ua-loading.is-active .ua-loading-mask {
+  opacity: 1;
+  visibility: visible;
+}
+
+.ua-loading.is-active .ua-loading-body {
+  opacity: 0.5; /* 内容降透明度而不是隐藏：保留位置与尺寸，遮罩挡住操作但不让布局跳动 */
+}
+
+.ua-loading-text {
+  color: var(--ua-color-text-secondary);
+  font-size: var(--ua-font-size-sm);
+}