@moheng-design/ui-skill 1.0.0 → 3.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,21 +2,21 @@
2
2
 
3
3
  # @moheng-design/ui 完整参考
4
4
 
5
- 适用版本:v1.0.0 —— 本文件随包分发,永远与所安装的 `@moheng-design/ui` 版本配套。
5
+ 适用版本:v3.0.0 —— 本文件随包分发,永远与所安装的 `@moheng-design/ui` 版本配套。
6
6
 
7
- 共 91 个组件。每个组件含:契约 JSDoc 原文、完整 props 表、
7
+ 共 94 个组件。每个组件含:契约 JSDoc 原文、完整 props 表、
8
8
  关联类型,以及手写的组合约定(何时使用 / 何时改用其他组件 / 组合约定 / 禁止与使用边界)。
9
- 文末另有两份全表:150 条 lint 规则,以及 356 条 design token 的名值对照。
9
+ 文末另有两份全表:165 条 lint 规则,以及 389 条 design token 的名值对照。
10
10
 
11
11
  ## 目录
12
12
 
13
13
  - **Foundation · icon** —— [Icon](#icon)
14
14
  - **Foundation · actions** —— [Button](#button)、[ButtonGroup](#buttongroup)、[Toggle](#toggle)、[ToggleGroup](#togglegroup)
15
- - **Foundation · input-selection** —— [Calendar](#calendar)、[Checkbox](#checkbox)、[Combobox](#combobox)、[Field](#field)、[Input](#input)、[InputGroup](#inputgroup)、[InputOTP](#inputotp)、[Label](#label)、[NativeSelect](#nativeselect)、[RadioGroup](#radiogroup)、[Select](#select)、[Slider](#slider)、[Switch](#switch)、[Textarea](#textarea)
15
+ - **Foundation · input-selection** —— [Calendar](#calendar)、[Checkbox](#checkbox)、[Combobox](#combobox)、[DateInput](#dateinput)、[Field](#field)、[Input](#input)、[InputGroup](#inputgroup)、[InputOTP](#inputotp)、[Label](#label)、[NativeSelect](#nativeselect)、[RadioGroup](#radiogroup)、[Select](#select)、[Slider](#slider)、[Switch](#switch)、[Textarea](#textarea)
16
16
  - **Foundation · navigation-command** —— [Accordion](#accordion)、[Breadcrumb](#breadcrumb)、[Command](#command)、[ContextMenu](#contextmenu)、[Menubar](#menubar)、[NavigationMenu](#navigationmenu)、[Pagination](#pagination)、[Sidebar](#sidebar)、[Tabs](#tabs)
17
17
  - **Foundation · data-content-layout** —— [AspectRatio](#aspectratio)、[Avatar](#avatar)、[Badge](#badge)、[Bubble](#bubble)、[Card](#card)、[Carousel](#carousel)、[Chart](#chart)、[Empty](#empty)、[Item](#item)、[Kbd](#kbd)、[Message](#message)、[MessageScroller](#messagescroller)、[Progress](#progress)、[Resizable](#resizable)、[ScrollArea](#scrollarea)、[Separator](#separator)、[Skeleton](#skeleton)、[Table](#table)
18
- - **Foundation · feedback-overlay** —— [Alert](#alert)、[AlertDialog](#alertdialog)、[Collapsible](#collapsible)、[Dialog](#dialog)、[Drawer](#drawer)、[DropdownMenu](#dropdownmenu)、[HoverCard](#hovercard)、[Popover](#popover)、[Sheet](#sheet)、[Sonner](#sonner)、[Spinner](#spinner)、[Tooltip](#tooltip)
19
- - **Application Atomic** —— [ApplicationFilterMenu](#applicationfiltermenu)、[ListSelectionCheckbox](#listselectioncheckbox)、[ListTablePagination](#listtablepagination)、[SearchField](#searchfield)、[SidebarAppLinkButton](#sidebarapplinkbutton)、[SidebarRailButton](#sidebarrailbutton)、[SystemButton](#systembutton)
18
+ - **Foundation · feedback-overlay** —— [Alert](#alert)、[AlertDialog](#alertdialog)、[Collapsible](#collapsible)、[Dialog](#dialog)、[Drawer](#drawer)、[DropdownMenu](#dropdownmenu)、[HoverCard](#hovercard)、[Popover](#popover)、[Sheet](#sheet)、[Sonner](#sonner)、[SonnerProvider](#sonnerprovider)、[Spinner](#spinner)、[Tooltip](#tooltip)
19
+ - **Application Atomic** —— [ApplicationDateRangeFilter](#applicationdaterangefilter)、[ApplicationFilterMenu](#applicationfiltermenu)、[ListSelectionCheckbox](#listselectioncheckbox)、[ListTablePagination](#listtablepagination)、[SearchField](#searchfield)、[SidebarAppLinkButton](#sidebarapplinkbutton)、[SidebarRailButton](#sidebarrailbutton)、[SystemButton](#systembutton)
20
20
  - **Application Module · navigation** —— [ApplicationModuleSwitcher](#applicationmoduleswitcher)、[ApplicationPrimaryNavigation](#applicationprimarynavigation)、[ApplicationSecondaryNavigation](#applicationsecondarynavigation)、[GlobalSidebar](#globalsidebar)、[TopNavigationPrimaryBar](#topnavigationprimarybar)
21
21
  - **Application Module · statistics** —— [ApplicationMetricChart](#applicationmetricchart)、[ApplicationMetricPrimarySecondary](#applicationmetricprimarysecondary)、[ApplicationMetricStatus](#applicationmetricstatus)、[ApplicationMetricStrip](#applicationmetricstrip)、[ApplicationMetricTrend](#applicationmetrictrend)
22
22
  - **Application Module · content** —— [ApplicationDataDisplay](#applicationdatadisplay)、[ApplicationFilterList](#applicationfilterlist)、[ApplicationPageHeader](#applicationpageheader)、[ApplicationPageLayoutContainer](#applicationpagelayoutcontainer)、[ApplicationQueryToolbar](#applicationquerytoolbar)、[ApplicationRecordDetailBody](#applicationrecorddetailbody)、[ApplicationSplitListSidebar](#applicationsplitlistsidebar)
@@ -47,8 +47,10 @@
47
47
  | `--application-*` / `--ui-*` | 公共接口,稳定契约 | 应用代码、页面布局 |
48
48
 
49
49
  业务代码只读 `--application-*` 与 `--ui-*`。下探 `--ds-*` 等于依赖内部实现,
50
- 小版本即可能失效。唯一的例外是换肤入口 `--ds-color-theme-primary`,
51
- 应用层可以且应当覆盖它。
50
+ 小版本即可能失效。例外只有两处:换肤入口 `--ds-color-theme-primary`,
51
+ 应用层可以且应当覆盖它;焦点环几何 `--ds-focus-ring-width` 与 `--ds-focus-ring-offset`,
52
+ 自定义可聚焦元素画焦点环时读取(不得覆盖)—— 焦点环的粗细与偏移全产品必须一致,
53
+ 本库不为它另开别名,组件内部读的也是这两个。
52
54
 
53
55
  **任何情况下都不得在业务代码中写字面色值、圆角与间距去对齐组件。**
54
56
  需要与组件对齐时读同一个 token。
@@ -84,7 +86,9 @@
84
86
 
85
87
  ### 滚动
86
88
 
87
- Content Canvas 是页面唯一的主垂直滚动权持有者。
89
+ 每个页面有且只有一个页面级纵向滚动持有者,按页型划分(06 · D-4):结果集页面由
90
+ `ApplicationDataDisplay` 的主体滚动,`WORKBENCH` / `DETAIL` / 多面板 `ANALYSIS` 等无结果集页面由
91
+ Content Canvas 滚动,见「五层 Canvas 模型」的「纵向滚动归属」。
88
92
  `ScrollArea` 与 `MessageScroller` 只用于**正交方向**(水平)或**局部有界**的溢出,
89
93
  且必须给出显式高度或最大高度。不得堆叠无界的垂直滚动容器。
90
94
 
@@ -101,6 +105,11 @@ Content Canvas 是页面唯一的主垂直滚动权持有者。
101
105
  Partial Failure 六种状态的文案各不相同,不得共用。
102
106
  Mock 数据用已登记的占位符,`模块1 / 模块2` 被明令禁止。
103
107
 
108
+ UI 文案不用第二人称,也不写「请」:写 `无权查看本模块`,不写 `你没有权限`。
109
+ 表单与说明文案(02 §8):校验错误写字段名与不满足的条件(`任务名称不能为空`);
110
+ 确认说明写后果(`删除后 3 条记录不可恢复`),不写请求;占位文字写示例或范围
111
+ (`例如:季度巡检记录`),不写指令;无权限的出路点明找谁(`联系本模块管理员开通`)。
112
+
104
113
  ## 五层 Canvas 模型
105
114
 
106
115
  <!-- 手写文件。被 generate.mjs 嵌入 SKILL.md 的「五层 Canvas 模型」一节与 reference.md。
@@ -118,26 +127,123 @@ Application
118
127
  └─ Overlay Dialog / Drawer / Popover / Menu / Toast
119
128
  ```
120
129
 
121
- ### Shell 四带
130
+ ### Shell 导航带
131
+
132
+ 固定骨架,**没有左侧全局栏**。导航带永不滚动。几何以 GAP Design kit「框架结构」为准,外壳有两种形态:
122
133
 
123
- 固定骨架,**没有左侧全局栏**。三条导航带 `position: fixed`,永不滚动。
134
+ | 形态 | 带(自上而下) | Standard 总高 | Compact 总高 |
135
+ |---|---|---:|---:|
136
+ | 基础版 | 应用一级 + 应用二级 | 96px | 80px |
137
+ | 集团版 | 集团顶部 + 应用一级 + 应用二级 | 144px | 120px |
124
138
 
125
139
  | 带 | 组件 | Standard | Compact |
126
140
  |---|---|---:|---:|
127
- | 顶部导航 `PLATFORM.TOP_USER_BAR` | `TopNavigationPrimaryBar` | 52px | 44px |
128
- | 应用一级导航 `APPLICATION.PRIMARY_NAV` | `ApplicationPrimaryNavigation` | 64px | 52px |
141
+ | 集团顶部导航 `PLATFORM.TOP_USER_BAR`(仅集团版) | `TopNavigationPrimaryBar` | 48px | 40px |
142
+ | 应用一级导航 `APPLICATION.PRIMARY_NAV` | `ApplicationPrimaryNavigation` | 48px | 40px |
129
143
  | 应用二级导航 `APPLICATION.SECONDARY_NAV` | `ApplicationSecondaryNavigation` | 48px | 40px |
130
144
  | Content Canvas | `ApplicationPageLayoutContainer` | 剩余视口 | 剩余视口 |
131
145
 
132
- **Content Canvas 是页面唯一的垂直滚动持有者。** 宿主 padding 为零 —— padding 属于页面内容根。
146
+ 账户头像在基础版里是 `ApplicationPrimaryNavigation` 的 `account`,在集团版里在 `TopNavigationPrimaryBar`,
147
+ 一个外壳只有一处。外壳总高读 `--ui-shell-application-total-height`:渲染了 `TopNavigationPrimaryBar` 时它自动计入
148
+ 集团顶栏,宿主不必区分两种形态。
149
+
150
+ Compact 档在视口宽 ≤1180px 或高 ≤720px 时生效(`--ui-viewport-compact-max-width` / `-height`),
151
+ 各带高度由同一组 `@media` 一并切换,宿主不得自行复刻断点。
152
+
153
+ 宿主 padding 为零 —— padding 属于页面内容根。
154
+
155
+ ### 宿主布局
156
+
157
+ 本库不提供宿主组件(07 · C-5:组件留到第二个真实项目再抽),导航带 + Canvas 的宿主由应用
158
+ 自己写,标准写法如下(类名由宿主自定,只读 `--application-*` 与 `--ui-*`):
159
+
160
+ ```css
161
+ html,
162
+ body {
163
+ block-size: 100%;
164
+ margin: 0;
165
+ }
166
+
167
+ .app-shell { /* 导航带 + Canvas,整体占满视口 */
168
+ display: flex;
169
+ flex-direction: column;
170
+ block-size: 100dvh;
171
+ background: var(--application-canvas);
172
+ }
173
+
174
+ .app-shell__bands { /* 包住全部导航带;不进滚动容器,即永不滚动 */
175
+ flex: none;
176
+ z-index: var(--ui-z-shell);
177
+ }
178
+
179
+ .app-shell__canvas { /* Content Canvas:必须是列向 flex */
180
+ display: flex;
181
+ flex: 1;
182
+ flex-direction: column;
183
+ min-block-size: 0;
184
+ overflow: auto;
185
+ }
186
+
187
+ .app-shell__page { /* 页面根(ApplicationPageLayoutContainer 的 className) */
188
+ flex: 1;
189
+ }
190
+ ```
191
+
192
+ **Canvas 必须是列向 flex 容器。** 写成块级 + `overflow: auto`(最自然的写法)时,
193
+ `ApplicationPageLayoutContainer` 按内容撑高,`ApplicationDataDisplay`「自身滚动、分页固定在底部」
194
+ 随之失效 —— 05 · P2-1 实测 46 行时分页被推到首屏以下 533px。页面根 `flex: 1` 让内容不足一屏时
195
+ 数据展示区的边框仍画到底。`DETAIL` 页的容器随内容增高,由同一个 Canvas 滚动,宿主不必区分页型。
196
+
197
+ **`GlobalSidebar` 与内容区并排**(工作台):两者包一层横向 flex 作为 Canvas 的直接子元素,
198
+ 菜单栏 `sticky` 停在 Canvas 顶部、自己不滚动,内容区随内容撑高、由 Canvas 滚动:
199
+
200
+ ```css
201
+ .workbench { /* Canvas 的直接子元素 */
202
+ display: flex;
203
+ flex: 1 0 auto;
204
+ align-items: flex-start;
205
+ }
206
+
207
+ .workbench__rail { /* GlobalSidebar 的 className */
208
+ position: sticky;
209
+ inset-block-start: 0;
210
+ flex: none;
211
+ block-size: calc(100dvh - var(--ui-shell-application-total-height));
212
+ }
213
+
214
+ .workbench__main { /* ApplicationPageLayoutContainer 的 className */
215
+ flex: 1;
216
+ min-inline-size: 0;
217
+ align-self: stretch;
218
+ }
219
+ ```
220
+
221
+ ### 纵向滚动归属
222
+
223
+ 每个页面**有且只有一个**页面级纵向滚动持有者,按页型划分(06 · D-4 裁决):
224
+
225
+ | 页面 | 纵向滚动持有者 | 理由 |
226
+ |---|---|---|
227
+ | 结果集页面(见下「五层认知模型」) | `ApplicationDataDisplay` 的主体 | 上下文区、工具栏、分页条与批量条固定,只有结果滚动 |
228
+ | `WORKBENCH` / `DETAIL` / `ANALYSIS` 多面板 / 无结果集页面 | Content Canvas | 内容是若干面板或分节,整页一起滚;放进 DataDisplay 会只剩约 290px 可视高度 |
229
+
133
230
  表格、看板、标签页、日历可以拥有正交的水平滚动或局部有界滚动;
134
- 不得堆叠无界的垂直滚动容器。
231
+ 不得堆叠无界的垂直滚动容器。多面板的 `ANALYSIS` 页不得把面板组塞进 `ApplicationDataDisplay`。
135
232
 
136
233
  Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑、通知铃铛、页面标题、卡片、阴影。
137
234
 
138
235
  ### 五层认知模型
139
236
 
140
- 新页面必须把五层**全部**声明为状态字段。缺一层即为结构不完整。
237
+ 必填字段按页面有没有**结果集**划分(06 · D-1 裁决)。判据是页面是否有一份由
238
+ `ApplicationQueryToolbar` 驱动、由 `ApplicationDataDisplay` 展示的记录集合:
239
+
240
+ | 页面 | 必须声明的字段 | 典型 |
241
+ |---|---|---|
242
+ | 结果集页面 | 五层**全部**,缺一层即为结构不完整 | `MANAGEMENT` / `LEDGER` / `REPORT` 的列表页;以查询结果为主体的 `ANALYSIS` 页(单模式时 `pageMode` 取 `LIST`,切换器不渲染) |
243
+ | 无结果集页面 | 只声明 `pageType`,其余四层**不写**;不得为凑字段塞一个 `ApplicationDataDisplay` 或空工具栏 | `WORKBENCH` 工作台、`DETAIL` 详情页、配置页、协作工作台、编辑器型工作面 |
244
+
245
+ 无结果集页面的 `pageType` 按所属业务取值:工作台取 `WORKBENCH`,详情页取 `DETAIL`,
246
+ 配置页与协作工作台取其所属模块的类型(多为 `MANAGEMENT`),报表设计器随报表取 `REPORT`。
141
247
 
142
248
  | 层 | 字段 | 取值 |
143
249
  |---|---|---|
@@ -145,7 +251,7 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
145
251
  | L2 页面模式 | `pageMode` | `LIST` / `CARD` / `SPLIT` / `BOARD` / `CALENDAR` |
146
252
  | L3 业务视图 | `businessView` | 2–4 个稳定工作视角(全部 / 我的责任 / 最近处理) |
147
253
  | L4 数据控制 | `dataControl` | search / filters / sort / pagination / appliedFilterTags |
148
- | L5 数据呈现 | `dataPresentation` | `DataTable` / `CardList` / `KanbanBoard` / `Calendar` / `Chart` / `Timeline` |
254
+ | L5 数据呈现 | `dataPresentation` | `DataTable` / `RecordList` / `CardList` / `KanbanBoard` / `Calendar` / `Chart` / `Timeline` |
149
255
 
150
256
  `DETAIL` 与 `COMPOSITE` **不是**页面模式,是特殊物理结构资产。
151
257
  `Embedded` 是 `integrationMode`,不是页面模式。
@@ -155,14 +261,76 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
155
261
  自上而下固定,不得重排:
156
262
 
157
263
  ```
158
- 上下文区 ApplicationPageHeader L1 / L2 / L3 的承载者
264
+ 内容根 ApplicationPageLayoutContainer L1,pageType 必填;包住以下四个区域
265
+ 上下文区 ApplicationPageHeader L2 / L3 的承载者
159
266
  指标区 ApplicationMetric*(可选) 不是每个页面都有
160
267
  数据控制 ApplicationQueryToolbar L4
161
268
  ApplicationFilterList L4 的已应用筛选标签
162
269
  数据展示 ApplicationDataDisplay L5
163
270
  ```
164
271
 
165
- `SPLIT` 模式另有左栏 `ApplicationSplitListSidebar`(360px,Compact 300px)。
272
+ 上表是结果集页面的顺序。`SPLIT` 与无结果集页面的结构见下两节。
273
+
274
+ ### SPLIT 的标准组件树
275
+
276
+ 工具栏服务右栏,但放在横跨两栏的 `dataControl` 槽位 —— 它管的是右栏的结果集,
277
+ 左栏目录只改变查询范围(06 · D-4 裁决):
278
+
279
+ ```
280
+ ApplicationPageLayoutContainer pageType, dataControl
281
+ ├─ header ApplicationPageHeader pageMode="SPLIT"
282
+ ├─ dataControl ApplicationQueryToolbar businessView、search / filters / sort、viewModeSwitch
283
+ │ └─ moreFilters Popover > ApplicationFilterList(不得用 Collapsible 就地展开)
284
+ └─ children Resizable 左栏宽度取 --ui-sidebar-list-width(360 / Compact 300)
285
+ ├─ ApplicationSplitListSidebar 目录定位,只改变查询范围
286
+ └─ ApplicationDataDisplay presentation = 当前 View Mode
287
+ └─ ApplicationRecordList / Table / 呈现配方
288
+ ```
289
+
290
+ 右栏需要再分「结果 / 概况」等内容标签时,`Tabs` 放在右栏顶部、`ApplicationDataDisplay`
291
+ 作为当前标签的面板;概况标签下工具栏仍在,但不得为它另起第二个工具栏。
292
+
293
+ ### 无结果集页面的结构
294
+
295
+ 这类页面只声明 `pageType`,由 Content Canvas 整页滚动,没有工具栏与数据展示区。
296
+
297
+ ```
298
+ WORKBENCH ApplicationPageLayoutContainer pageType="WORKBENCH"
299
+ ├─ header ApplicationPageHeader(标题、数据时刻、刷新;不渲染 Page Mode Switch)
300
+ └─ children 分区导航 GlobalSidebar + 面板网格(指标区、待办、动态、应用入口)
301
+
302
+ DETAIL ApplicationPageLayoutContainer pageType="DETAIL"
303
+ ├─ header ApplicationPageHeader(breadcrumb 返回来源列表;对象级动作放 actions)
304
+ └─ children ApplicationRecordDetailBody(分节;分节级动作放分节标题行)
305
+
306
+ 编辑器 ApplicationPageLayoutContainer pageType 随所属业务
307
+ ├─ header ApplicationPageHeader(标题、保存 / 发布等页面动作)
308
+ ├─ dataControl Menubar(编辑命令就是这页的「数据控制」)
309
+ └─ children 工作面:Resizable 两栏,各栏自带有界 ScrollArea
310
+ ```
311
+
312
+ **对象级动作的落点**:详情页与协作工作台里针对「当前对象」的动作(编辑、指派、删除)
313
+ 放 `ApplicationPageHeader` 的 `actions`;`ApplicationRecordDetailBody` 只放分节级动作。
314
+
315
+ ### 呈现配方
316
+
317
+ `KanbanBoard` / `Calendar` / `Timeline` 暂无专属组件,按下面的标准拼装写法承载
318
+ (06 · D-2 裁决:先登记配方,组件留到第二个真实项目再抽)。三者都放在
319
+ `ApplicationDataDisplay` 的 `children` 里,仅 `state="ready"` 时渲染,不得自画外框。
320
+
321
+ - **看板(`KanbanBoard`)**:`ScrollArea horizontal` 包一行等宽列,列宽取
322
+ `--ui-card-min-width`;每列是「列标题 + 计数」与一串 `Card density="sm" interactive`;
323
+ 卡片内勾选用 `ListSelectionCheckbox`,行级动作用 `DropdownMenu`(「更多 → 移至」代替拖拽)。
324
+ 看板是「不得嵌套 `ScrollArea`」的登记例外(07 · C-14):外层 `ScrollArea horizontal` 撑满数据展示区
325
+ 主体的高度、只管横向,每列的卡片串放进一个纵向 `ScrollArea`、高度取列的剩余高度,列内纵向滚动。
326
+ 横向滚动条因此始终贴在可视区底部,不会被推到五列溢出的纵向末尾(06 · P2-7)。除看板外仍不得嵌套。
327
+ - **月历(`Calendar`)**:自拼 7 列月格,`role="grid"` / `row` / `gridcell`,周一起始,
328
+ 月末空位补白格;每格最多列 3 条,其余收进「+N」按钮。月份游标(上一月 / 下一月 / 本月)
329
+ 放在月格上方、数据展示区之内,不进工具栏。不得用 Foundation `Calendar` 控件充当月格。
330
+ - **时间轴(`Timeline`)**:按日期分组,每组是 `<section aria-label>` + `Separator label`
331
+ (分组标题)+ `<ol>`;每条用 `Message`(作者、时间、正文)。时间轴只按时间排序,
332
+ 不提供行选择,切到时间轴时清空已选并不渲染批量条。
333
+
166
334
  `DETAIL` 结构用 `ApplicationRecordDetailBody`。
167
335
 
168
336
  ### 三个绝不能混为一谈的切换器
@@ -171,18 +339,27 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
171
339
  仅当页面真正开放 2 个以上模式时渲染,否则不占位。改 `pageMode`。
172
340
  - **View Mode Switch** —— 仅 `SPLIT` 右栏。改 `dataPresentation`,**绝不改** `pageMode`。
173
341
  - **Presentation Settings** —— 是一个*概念*,不是一个按钮名。
174
- 按钮必须按当前呈现方式命名:`列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
342
+ 按钮必须按当前呈现方式命名:`列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
175
343
  **禁止通用的「视图设置」按钮。** 呈现设置不得改变搜索、筛选、业务视图或页面模式,
176
- 它只调整当前呈现方式的展示细节。
344
+ 它只调整当前呈现方式的展示细节。面板一律用 `Popover` 承载,与更多筛选同一承载(07 · C-7)。
177
345
 
178
346
  ### 六种数据状态
179
347
 
180
348
  `ApplicationDataDisplay` 的 `state` 取六值:
181
349
  `ready` / `loading` / `empty` / `error` / `no-permission` / `not-found`。
182
350
 
183
- **六种状态的文案绝不共用同一句话。** 「当前视角下无数据」「你没有权限」「请求失败」
351
+ **六种状态的文案绝不共用同一句话。** 「当前视角下无数据」「无权查看本模块」「请求失败」
184
352
  是三句不同的话,成因不同,用户的下一步动作也不同。
185
- 另有 Partial Failure —— 部分数据加载失败,不等同于 `error`。
353
+ 另有 Partial Failure —— 部分数据加载失败,不等同于 `error`:`state` 仍为 `ready`,
354
+ 呈现照常渲染,缺失的那部分用 `Alert` 放进 `ApplicationDataDisplay` 的 `notice` 槽位说明并给出重试。
355
+ `notice` 固定在批量条之下、呈现之上,不随内容滚动,只在 `ready` 态渲染。
356
+
357
+ **空态按成因分两句**(07 · C-6):有搜索或筛选生效时是「没有符合当前筛选条件的记录」,
358
+ 出路 `清除筛选`;当前视图下本就没有数据时是「当前视图下还没有记录」,出路 `新建`。
359
+ 空态只由 `ApplicationDataDisplay` 的 `empty` 槽位承担,被承载的 `Table` 不再另设 `empty`。
360
+
361
+ **非 ready 状态下的工具栏**:`no-permission` 与 `not-found` 时不渲染 `ApplicationQueryToolbar`
362
+ (查询条件对这两种状态没有意义);`error` 时保留,改条件即可重新查询。
186
363
 
187
364
  页面头部的数据状态(`ApplicationPageHeader` 的 `dataStatus`)另有三值:
188
365
  `normal`(附最后更新时间)/ `refreshing` / `failed`(附重试入口)。
@@ -190,8 +367,11 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
190
367
  ### 关键尺寸
191
368
 
192
369
  抽屉宽 680px(`--application-drawer-width: 1280px` 是宽/全屏变体);
193
- 表单对话框 720px / 960px;`SPLIT` 左栏 360px(Compact 300px);
370
+ 表单对话框 720px / 960px / 1280px;`SPLIT` 左栏 360px(Compact 300px);
194
371
  卡片网格默认 ≥1440 五列、Condensed 四列、Compact 三列,卡片最小宽 220px。
372
+ 列数读 `--ui-card-columns-default`,三档由 `viewport.css` 的 `@media` 在 `:root` 上改写(5 / 4 / 3),
373
+ 最小宽读 `--ui-card-min-width`,卡间距读 `--ui-card-gap`;系统内没有卡片网格组件,
374
+ `CARD` 呈现的网格由调用方用这三个 token 写,不得在组件或页面里另写断点改列数。
195
375
 
196
376
  ### Mock 数据
197
377
 
@@ -200,6 +380,9 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
200
380
  `示例应用`(应用名)· `应用说明信息`(应用描述)· `模块名称`(当前模块)·
201
381
  `模块 A` / `模块 B` / `模块 C`(模块菜单)· `Tab 1` / `Tab 2`(业务标签)· `企业名称`(品牌兜底)。
202
382
 
383
+ 业务记录的占位符(07 · C-8):`成员 A` / `成员 B` / `成员 C`(人名)· `对象 A` / `对象 B` / `对象 C`(业务对象名)·
384
+ `编号 0001` / `编号 0002`(记录编号,四位补零递增)。同类条目按字母或序号顺延,不得换用真实人名。
385
+
203
386
  `模块1` / `模块2` 作为标签文案被明令禁止。
204
387
 
205
388
 
@@ -231,7 +414,7 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
231
414
 
232
415
  | prop | 类型 | 必填 | 说明 |
233
416
  |---|---|:---:|---|
234
- | `name` | `string` | 是 | 图标名。接受 kebab 或 Pascal 形式(`chevron-down` / `ChevronDown`) |
417
+ | `name` | `IconName` | 是 | 图标名,只收已登记字形的 kebab-case 名(`chevron-down`)。 类型是生成的 `IconName` 字面量联合(05 · P1-6):此前是 `string`,未登记名 过 tsc、过 strict lint,运行时渲染成空方盒。现在清单外的名字在 tsc 与 `prop-enum` 两处被拒。数据里存图标名时把字段类型写成 `IconName`, 不要写 `string` 再断言。 类型层不再收 Pascal 写法(`ChevronDown`):两种写法并收会让取值表翻倍, 且收窄当时库内、文档站示例与验证页里没有一处 Pascal 用法。运行时仍把 Pascal / 下划线写法归一成 kebab,未经类型检查的 JS 调用方不受影响。 |
235
418
  | `size` | `14 \| 16 \| 18 \| 20 \| 24` | 否 | 尺寸,单位 px。取值即登记档: 14(chevron)· 16(顶栏)· 18(全局动作 / 模块字形)· 20(工具 / 模块触发器)· 24(应用 logo mock 字形)。 写成字面量联合而非 `number`,是 01 §7.1 对枚举的要求: 档外尺寸须在类型层就被拒绝,`build-icons.mjs` 不校验尺寸, 只写进 JSDoc 等于把这条约束留在文字里(§1.4 点名的反模式)。 控件自身的指示符字形(复选框的勾、关闭按钮的叉)尺寸落在档外, 它们内联在组件内,本就不走 Icon。 |
236
419
  | `strokeWidth` | `number` | 否 | 描边宽度。字形集为 2px 描边、圆头几何 |
237
420
  | `color` | `string` | 否 | 颜色。默认 `currentColor`,通常不应传入 |
@@ -241,7 +424,7 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
241
424
 
242
425
  **用途。** 已登记字形集中的单色图标,是内容图标在系统内出现的唯一渲染入口。
243
426
 
244
- **何时使用。** 凡界面上出现一个图标形状,该图标必须由本组件渲染。字形几何在构建时内联进包,运行时零外部依赖,SSR 直出完整 SVG,不存在首屏空盒子。`name` 接受 kebab 与 Pascal 两种书写形式(`chevron-down` 与 `ChevronDown` 等价)。承载图标槽位的组件(`Tabs` 的 `TabItem.icon`、`SidebarRailButton` 的 `icon`、`ToggleGroupItem` 的 `icon`)应当接收一个本组件的元素作为该槽位的值。
427
+ **何时使用。** 凡界面上出现一个图标形状,该图标必须由本组件渲染。字形几何在构建时内联进包,运行时零外部依赖,SSR 直出完整 SVG,不存在首屏空盒子。`name` 的类型是生成的 `IconName` 字面量联合,只收已登记字形的 kebab-case 名(`chevron-down`);Pascal 写法不再过类型检查,运行时仍归一处理。承载图标槽位的组件(`Tabs` 的 `TabItem.icon`、`SidebarRailButton` 的 `icon`、`ToggleGroupItem` 的 `icon`)应当接收一个本组件的元素作为该槽位的值。
245
428
 
246
429
  **何时改用其他组件。**
247
430
 
@@ -250,7 +433,7 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
250
433
  - 品牌标识不是图标。应用 logo 缺失时按登记的 mock 规则渲染纯色块,不得用本组件拼一个替代标识。
251
434
  - 系统内无其他相邻组件,内容图标的渲染由本组件独占。
252
435
 
253
- **组合约定。** `name` 必须已登记在 `src/icon/registry.json`;构建时的双向校验只覆盖库内 `src/`,业务代码里的未登记名字要到运行时才暴露 —— 渲染为等尺寸的隐藏占位盒,开发构建下 `console.warn`,生产构建静默。因此图标位会消失但布局不塌。`size` 取登记档 14 / 16 / 18 / 20 / 24:14 用于 chevron 类指示符,16 用于顶栏,18 用于全局动作与模块字形,20 用于工具与模块触发器,24 用于应用 logo mock 字形;12px 只登记给控件内的清除叉一处,业务代码不得取用。本组件恒为装饰件,渲染 `aria-hidden="true"` 与 `focusable="false"`,可访问名必须由承载它的控件提供 —— `Button` 与 `Toggle` 在 `iconOnly` 为 true 时必须给 `aria-label`。颜色继承 `currentColor`,由父级的 `color` 决定,`color` prop 通常不传。尺寸走 SVG 的 `width` / `height` 属性,图标容器宽度必须稳定,使 active 与 hover 的字重变化不会横向推移标签。图标与文字并排时的间隙由承载控件负责(`Button` 与 `Toggle` 的 4px gap),本组件不带外边距。二级导航的业务标签必须是图标加文字标签,窄屏下也不得丢弃图标。
436
+ **组合约定。** `name` 必须已登记在 `src/icon/registry.json`。业务代码里写错的字面量名在 tsc(`IconName` 联合)与 `prop-enum` 规则两处被拒;数据里存图标名时字段类型写 `IconName`(从 `@moheng-design/ui` 导入),不得写 `string` 再断言 —— 断言绕过类型后,未登记名字要到运行时才暴露:渲染为等尺寸的隐藏占位盒,开发构建下 `console.warn`,生产构建静默,图标位消失但布局不塌。`size` 取登记档 14 / 16 / 18 / 20 / 24:14 用于 chevron 类指示符,16 用于顶栏,18 用于全局动作与模块字形,20 用于工具与模块触发器,24 用于应用 logo mock 字形;12px 只登记给控件内的清除叉一处,业务代码不得取用。本组件恒为装饰件,渲染 `aria-hidden="true"` 与 `focusable="false"`,可访问名必须由承载它的控件提供 —— `SystemButton`、`Button` 与 `Toggle` 在 `iconOnly` 为 true 时必须给 `aria-label`。颜色继承 `currentColor`,由父级的 `color` 决定,`color` prop 通常不传。尺寸走 SVG 的 `width` / `height` 属性,图标容器宽度必须稳定,使 active 与 hover 的字重变化不会横向推移标签。图标与文字并排时的间隙由承载控件负责(`Button` 与 `Toggle` 的 4px gap),本组件不带外边距。二级导航的业务标签必须是图标加文字标签,窄屏下也不得丢弃图标。
254
437
 
255
438
  **禁止 / 使用边界。**
256
439
 
@@ -268,42 +451,42 @@ Shell 契约禁止在导航带内增加未登记元素:搜索框、面包屑
268
451
 
269
452
  Foundation 按钮 —— 按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。
270
453
 
271
- 已登记契约:14/20 字号、12px 行内内边距、4px 图标间隙、16px 圆角、32px 默认高度。
272
- 16px 圆角在 32px 高度下使等宽图标按钮自然成圆,系统内**没有**独立的 pill / circle token。
454
+ 已登记契约:14/20 字号、12px 行内内边距、4px 图标间隙、12px 圆角、32px 默认高度。
455
+ 圆角取控件角色 `--ds-radius-control`(GAP Design kit「圆角12」);等宽图标按钮为 12 圆角方形。
273
456
 
274
- 应用层存在稳定语义适配器时应优先使用 `SystemButton`。
457
+ **业务页面一律用 `SystemButton`**,本组件只供库内组件使用(实践报告 P1-1 裁决)。
275
458
  业务页面不得再造第二套基础按钮视觉。
276
459
 
277
460
  按下态只有颜色变化 —— 不得有缩放、位移或阴影变化。
278
461
 
279
- **替换原生元素:** `<button>`
462
+ 原生 `<button>` 的替换目标是 `SystemButton`,替换登记写在那份契约的 JSDoc 上。
280
463
 
281
464
  **Props**
282
465
 
283
466
  | prop | 类型 | 必填 | 说明 |
284
467
  |---|---|:---:|---|
285
- | `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'link'` | 否 | 视觉语义。 `primary` 用于页面主操作,每个动作组内至多一个; `secondary` 用于次要操作,是默认值; `destructive` 用于不可逆的删除类操作; `link` 用于行内跳转,无内边距、带下划线。 |
468
+ | `variant` | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'destructive-outline' \| 'link'` | 否 | 视觉语义。 `primary` 用于页面主操作,每个动作组内至多一个; `secondary` 用于次要操作,是默认值; `destructive` 用于不可逆的删除类操作(实心危险色); `destructive-outline` 白底、危险色描边与文字,用于与次要按钮并排的删除类动作; `link` 用于行内跳转,无内边距、带下划线。 |
286
469
  | `size` | `'xs' \| 'sm' \| 'default' \| 'lg'` | 否 | 尺寸,映射高度 24 / 28 / 32 / 40px。 `default` 读取 `--application-button-height`; `sm` 用于表格行内等紧凑布局;`xs` 用于标签内嵌。 |
287
470
  | `iconOnly` | `boolean` | 否 | 等宽图标按钮。宽度收敛为与高度相等,行内内边距归零。 为 true 时**必须**提供 `aria-label`,因为按钮没有可见文字。 |
288
- | `disabled` | `boolean` | 否 | 禁用。禁用时不触发 onClick 并移出 tab 顺序。 禁用作用于整个交互单元 —— 不得只禁用文字而保留图标可点。 |
471
+ | `disabled` | `boolean` | 否 | 禁用。禁用时不触发 onClick 并移出 tab 顺序。 禁用作用于整个交互单元 —— 不得只禁用文字而保留图标可点。 传 `aria-disabled="true"` 得到同一套禁用外观但保持可聚焦(`SystemButton` 的 loading 即此写法);本组件不拦截事件,阻断动作由设置它的一方负责。 |
289
472
  | `children` | `ReactNode` | 是 | 按钮文字。`iconOnly` 为 true 时改放单个 `Icon`,此时必须另给 `aria-label` |
290
473
 
291
474
  继承 `ButtonHTMLAttributes<HTMLButtonElement>` 的全部原生属性,其中 `size` 已被本组件重新定义或移除。
292
475
 
293
476
  **用途。** Foundation 按钮,是按钮排版、几何、圆角与基础交互的唯一 Foundation Owner。
294
477
 
295
- **何时使用。** 库内组件需要一个按钮时使用本组件。业务页面只在没有稳定应用语义可用时降级到本组件 —— 有稳定语义时一律用 `SystemButton`。已登记契约为 14/20 字号、12px 行内内边距、4px 图标间隙、16px 圆角、32px 默认高度;16px 圆角在 32px 高度下使等宽图标按钮自然成圆,系统内没有独立的 pill 或 circle token。
478
+ **何时使用。** 本组件只供库内组件使用。业务页面的按钮一律用 `SystemButton`,不存在降级到本组件的情形。已登记契约为 14/20 字号、12px 行内内边距、4px 图标间隙、12px 圆角、32px 默认高度;等宽图标按钮为 12 圆角方形,系统内没有独立的 pill 或 circle token。
296
479
 
297
480
  **何时改用其他组件。**
298
481
 
299
- - 产品页面的常规动作按钮改用 `SystemButton`,它是整个产品的默认动作按钮,并承载 `loading` 与产品状态。
482
+ - 业务页面的任何按钮改用 `SystemButton`,它是整个产品的默认动作按钮,并承载 `loading` 与产品状态。
300
483
  - 跳转到另一个 URL 用原生 `<a>`;`variant="link"` 只用于行为是按钮、视觉为行内链接的动作。
301
484
  - 表达持续的两态状态改用 `Toggle`,一组互斥的显示选择改用 `ToggleGroup`。
302
485
  - 工作台菜单栏条目改用 `SidebarRailButton`,应用入口改用 `SidebarAppLinkButton`。
303
486
  - 页面区域内的内容分节切换改用 `Tabs`,不得用一排 ghost 按钮模拟。
304
487
  - 原生 `<button>` 一律改用本组件(`mappings.json` · `no-native-button`)。
305
488
 
306
- **组合约定。** `size` 与 `iconOnly` 是两根正交的轴(04 · A1):`size` 映射高度 24 / 28 / 32 / 40px,`iconOnly` 把宽度收敛为与高度相等并把行内内边距归零,两者可任意组合。`iconOnly` 为 true 时必须提供 `aria-label`,因为按钮没有可见文字。`children` 是必填的 —— 等宽图标按钮的 `children` 就是那个 `Icon` 元素。一个动作组内至多一个 `variant="primary"`;上下文区的页面动作组由 `ApplicationPageHeader` 的 `actions` 承载,同样至多一个。外边距一律由容器负责:动作对交给 `ButtonGroup`(未拼接态以 8px 分隔),页面动作组交给 `ApplicationPageHeader`,批量动作交给 `ListBatchActionBar` 的 `actions`,按钮自身不得带 margin。图标与文字的 4px 间隙由按钮的 gap 提供,不得再包一层带间距的容器。破坏性动作用 `variant="destructive"`,且必须经 `AlertDialog` 确认,批量场景的标题中写明受影响对象的数量。本组件不持有任何状态,无 `"use client"`,可直接作为 server component 使用。`size` 已从 `ButtonHTMLAttributes` 中 `Omit`,契约的四档尺寸取代原生 `size` 属性。
489
+ **组合约定。** `size` 与 `iconOnly` 是两根正交的轴(04 · A1):`size` 映射高度 24 / 28 / 32 / 40px,`iconOnly` 把宽度收敛为与高度相等并把行内内边距归零,两者可任意组合。`iconOnly` 为 true 时必须提供 `aria-label`,因为按钮没有可见文字。`children` 是必填的 —— 等宽图标按钮的 `children` 就是那个 `Icon` 元素。一个动作组内至多一个 `variant="primary"`;上下文区的页面动作组由 `ApplicationPageHeader` 的 `actions` 承载,同样至多一个。外边距一律由容器负责:动作对交给 `ButtonGroup`(未拼接态以 8px 分隔),页面动作组交给 `ApplicationPageHeader`,批量动作交给 `ListBatchActionBar` 的 `actions`,按钮自身不得带 margin。图标与文字的 4px 间隙由按钮的 gap 提供,不得再包一层带间距的容器。破坏性动作用 `variant="destructive"`,且必须经 `AlertDialog` 确认,批量场景的标题中写明受影响对象的数量。本组件不持有任何状态,无 `"use client"`,可直接作为 server component 使用。`aria-disabled="true"` 与原生 `disabled` 同一套禁用外观但保持可聚焦,本组件不拦截事件,阻断动作由设置它的一方负责。`size` 已从 `ButtonHTMLAttributes` 中 `Omit`,契约的四档尺寸取代原生 `size` 属性。
307
490
 
308
491
  **禁止 / 使用边界。**
309
492
 
@@ -313,6 +496,7 @@ Foundation 按钮 —— 按钮排版、几何、圆角与基础交互的唯一
313
496
  - 不得在同一个动作组内出现两个 `variant="primary"`。
314
497
  - 不得只禁用文字而保留图标可点,禁用作用于整个交互单元。
315
498
  - 禁止在业务页面自建第二套基础按钮视觉。
499
+ - 不得在业务页面直接使用本组件 —— 一律改用 `SystemButton`。
316
500
 
317
501
  ### ButtonGroup
318
502
 
@@ -336,7 +520,7 @@ Page Mode Switch 是页面级控件,位于上下文区右侧,属于 `Applica
336
520
 
337
521
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
338
522
 
339
- **用途。** 把一组相关 `Button` 合并为一个分段控件或间隔簇。
523
+ **用途。** 把一组相关按钮合并为一个分段控件或间隔簇。业务页面里组内一律是 `SystemButton`。
340
524
 
341
525
  **何时使用。** 动作对(`重置` 与 `应用`)与分离式控件(主动作加「更多」触发器)用本组件。该组只负责拼接与分隔,不管理任何选中态。默认 `attached` 为 true,子项拼接为一个整体;`attached` 为 false 时子项以 8px 分隔、各自保留完整圆角。
342
526
 
@@ -346,9 +530,9 @@ Page Mode Switch 是页面级控件,位于上下文区右侧,属于 `Applica
346
530
  - 页面模式切换改用 `ApplicationPageHeader` 的 `pageModes` / `pageMode` / `onPageModeChange`。
347
531
  - 页面区域内的内容分节切换改用 `Tabs`,Shell 的二级导航改用 `ApplicationSecondaryNavigation`。
348
532
  - 翻页控件改用 `Pagination`,列表与表格的翻页改用 `ListTablePagination`。
349
- - 单个动作不成组,直接用 `Button` 或 `SystemButton`。
533
+ - 单个动作不成组,直接用 `SystemButton`。
350
534
 
351
- **组合约定。** `children` 是 slot 而非数据 prop,这与 `ToggleGroup` 的 `items` 形态相反,分工是实质性的(04 · A4):本组只做拼接、不管状态,因此接受任意子节点,包括 Fragment、数组与条件渲染,子组件也不必接受或转发 `style`。拼接态的圆角压平与 1px 边框重叠由 CSS 结构伪类完成,不做属性注入,子组件的 `className` 优先级不受影响。组内按钮的 `size` 必须一致,否则拼接边缘对不齐。拼接态要求子项都有可见边框才对得上,因此不得在拼接态里混入 `variant="ghost"` 与 `variant="link"`。组渲染 `role="group"`,若该组表达的是互斥选择,说明组件选错了。组自身不带外边距,与相邻元素的距离由容器负责。子项中至多一个 `variant="primary"`。
535
+ **组合约定。** `children` 是 slot 而非数据 prop,这与 `ToggleGroup` 的 `items` 形态相反,分工是实质性的(04 · A4):本组只做拼接、不管状态,因此接受任意子节点,包括 Fragment、数组与条件渲染,子组件也不必接受或转发 `style`。拼接态的圆角压平与 1px 边框重叠由 CSS 结构伪类完成,不做属性注入,子组件的 `className` 优先级不受影响。组内按钮的 `size` 必须一致,否则拼接边缘对不齐。拼接态要求子项都有可见边框才对得上,因此不得在拼接态里混入 `intent="quiet"` 与 `intent="link"`(库内为 `variant="ghost"` 与 `variant="link"`)。组渲染 `role="group"`,若该组表达的是互斥选择,说明组件选错了。组自身不带外边距,与相邻元素的距离由容器负责。子项中至多一个 primary。
352
536
 
353
537
  **禁止 / 使用边界。**
354
538
 
@@ -366,8 +550,8 @@ Page Mode Switch 是页面级控件,位于上下文区右侧,属于 `Applica
366
550
 
367
551
  在多个选项中择一请用 `ToggleGroup`;页面模式切换一律不用本组件。
368
552
 
369
- 选中态为淡强调色洗(`--application-selected`)+ 强调前景。
370
- 纯文字内容下选中**不得仅靠颜色**表达。
553
+ 选中态为淡强调色洗(`--application-selected`)+ 强调前景,另有 1px 前景色描边 ——
554
+ 描边是非颜色标识,纯文字内容下选中也不只靠颜色表达,调用方无须另补。
371
555
 
372
556
  通过 `aria-pressed` 上报状态。
373
557
 
@@ -380,7 +564,7 @@ Page Mode Switch 是页面级控件,位于上下文区右侧,属于 `Applica
380
564
  | `onPressedChange` | `(pressed: boolean) => void` | 否 | 按下态变化回调。受控与非受控两种用法下都会触发 |
381
565
  | `size` | `'sm' \| 'default' \| 'lg'` | 否 | 尺寸,映射高度 28 / 32 / 40px |
382
566
  | `iconOnly` | `boolean` | 否 | 等宽图标开关。宽度收敛为与高度相等,行内内边距归零。 为 true 时**必须**提供 `aria-label`,因为控件没有可见文字。 |
383
- | `children` | `ReactNode` | 否 | 开关内容。`iconOnly` 为 true 时放单个 `Icon`;纯文字内容下选中不得仅靠颜色表达 |
567
+ | `children` | `ReactNode` | 否 | 开关内容。`iconOnly` 为 true 时放单个 `Icon` |
384
568
 
385
569
  继承 `ButtonHTMLAttributes<HTMLButtonElement>` 的全部原生属性,其中 `onChange`、`size` 已被本组件重新定义或移除。
386
570
 
@@ -393,17 +577,17 @@ Page Mode Switch 是页面级控件,位于上下文区右侧,属于 `Applica
393
577
  - 在多个选项中择一,或一组同族的分段开关,改用 `ToggleGroup`。
394
578
  - 立即生效的设置项(列可见性、通知开关、密度)改用 `Switch`。
395
579
  - 等待「应用」或「提交」的表单数据改用 `Checkbox`,列表与表格的行选择改用 `ListSelectionCheckbox`。
396
- - 触发一次性动作改用 `Button` 或 `SystemButton` —— 本组件表达的是持续状态,不是动作。
580
+ - 触发一次性动作改用 `SystemButton` —— 本组件表达的是持续状态,不是动作。
397
581
  - 页面模式切换改用 `ApplicationPageHeader`。
398
582
 
399
- **组合约定。** `pressed` 与 `defaultPressed` 互斥:受控用法传 `pressed` 并配 `onPressedChange`,非受控用法传 `defaultPressed`;`onPressedChange` 在两种用法下都会触发。`iconOnly` 为 true 时必须提供 `aria-label`。纯文字内容下选中不得仅靠颜色表达,须同时有图标或文案上的区分。尺寸轴比 `Button` 少一档 `xs`,只有 `sm` / `default` / `lg`,映射高度 28 / 32 / 40px(04 · A2)—— 需要 24px 高的可按下控件说明取错了组件族。本组件持有非受控状态,带 `"use client"`;受控用法下内部状态不参与,但指令按模块边界生效,客户端边界落在本组件上,父级无须整体转为客户端组件。多个 `Toggle` 并排时的间隔由容器的 gap 负责,本组件不带外边距。图标子节点用 `Icon`,与文字的 4px 间隙由控件的 gap 提供。
583
+ **组合约定。** `pressed` 与 `defaultPressed` 互斥:受控用法传 `pressed` 并配 `onPressedChange`,非受控用法传 `defaultPressed`;`onPressedChange` 在两种用法下都会触发。`iconOnly` 为 true 时必须提供 `aria-label`。选中态除色洗与强调前景外另有 1px 前景色描边,这是非颜色标识,纯文字内容下也不只靠颜色区分选中,调用方无须另补。尺寸轴比 `Button` 少一档 `xs`,只有 `sm` / `default` / `lg`,映射高度 28 / 32 / 40px(04 · A2)—— 需要 24px 高的可按下控件说明取错了组件族。本组件持有非受控状态,带 `"use client"`;受控用法下内部状态不参与,但指令按模块边界生效,客户端边界落在本组件上,父级无须整体转为客户端组件。多个 `Toggle` 并排时的间隔由容器的 gap 负责,本组件不带外边距。图标子节点用 `Icon`,与文字的 4px 间隙由控件的 gap 提供。
400
584
 
401
585
  **禁止 / 使用边界。**
402
586
 
403
587
  - 不得用一排 `Toggle` 模拟单选组,互斥语义一律交给 `ToggleGroup`。
404
588
  - 不得用本组件承载立即落库的设置项,那是 `Switch` 的职责。
405
589
  - 禁止用于 `pageMode` 切换。
406
- - 不得在纯文字内容上只用颜色表达选中。
590
+ - 不得覆盖掉选中态的描边 —— 它是纯文字内容下选中态唯一的非颜色标识。
407
591
  - 不得省略 `iconOnly` 形态的 `aria-label`。
408
592
  - 不得把选中态改写为抬升式白色表面 —— 抬升是分段控件的表达,独立开关用淡色洗(04 · A5)。
409
593
 
@@ -456,7 +640,7 @@ ToggleGroup 的单个选项
456
640
  - 页面模式切换改用 `ApplicationPageHeader` 的 `pageModes` / `pageMode` / `onPageModeChange`;SPLIT 右栏的 View Mode Switch 改的是 `dataPresentation`,绝不改 `pageMode`。
457
641
  - 呈现设置的入口按钮按当前呈现方式命名(`列设置` / `卡片设置` / `看板设置`),由 `ApplicationQueryToolbar` 承载,不由本组件表达。
458
642
 
459
- **组合约定。** `items` 是数据 prop 而非 slot,与 `ButtonGroup` 的 `children` 形态相反,分工是实质性的(04 · A4):本组管理受控选中态,必须知道有哪些值。每个选项的 `label` 与 `icon` 至少提供其一,只有 `icon` 而无 `label` 时该项收敛为等宽方格。`type` 决定 `value` 的形态与无障碍语义:`single` 渲染 radio 语义、`value` 为 string,`multiple` 上报 `aria-pressed`、`value` 为 string[],两者必须匹配。受控用 `value` 配 `onValueChange`,非受控用 `defaultValue`;`single` 且未提供 `defaultValue` 时默认选中 `items[0].value`,因此单选组永远有一个选中项,不存在空态。整组禁用用 `disabled`,单个选项禁用用 `ToggleGroupItem.disabled`,两者可叠加。容器高度为 28 / 32 / 40px,选项高度是容器高度减去上下各 2px 的轨道内边距,得 24 / 28 / 36px;36px 是派生值而非标尺档位,不得为它新增 token。本组件持有非受控状态,带 `"use client"`。组自身不带外边距,与相邻控件的距离由容器负责。
643
+ **组合约定。** `items` 是数据 prop 而非 slot,与 `ButtonGroup` 的 `children` 形态相反,分工是实质性的(04 · A4):本组管理受控选中态,必须知道有哪些值。每个选项的 `label` 与 `icon` 至少提供其一,只有 `icon` 而无 `label` 时该项收敛为等宽方格。`type` 决定 `value` 的形态与无障碍语义:`single` 渲染 radio 语义、`value` 为 string,`multiple` 上报 `aria-pressed`、`value` 为 string[],两者必须匹配。`single` 组整组只占一个 Tab 停靠点,← / → 移动并同时选中、首尾相接,Home / End 跳到首末个可用项;`multiple` 组每项各是一个停靠点。受控用 `value` 配 `onValueChange`,非受控用 `defaultValue`;`single` 且未提供 `defaultValue` 时默认选中 `items[0].value`,因此单选组永远有一个选中项,不存在空态。整组禁用用 `disabled`,单个选项禁用用 `ToggleGroupItem.disabled`,两者可叠加。容器高度为 28 / 32 / 40px,选项高度是容器高度减去上下各 2px 的轨道内边距,得 24 / 28 / 36px;36px 是派生值而非标尺档位,不得为它新增 token。本组件持有非受控状态,带 `"use client"`。组自身不带外边距,与相邻控件的距离由容器负责。
460
644
 
461
645
  **禁止 / 使用边界。**
462
646
 
@@ -486,23 +670,25 @@ ToggleGroup 的单个选项
486
670
 
487
671
  | prop | 类型 | 必填 | 说明 |
488
672
  |---|---|:---:|---|
489
- | `month` | `Date` | 否 | 初始显示的月份。仅取年月,日被忽略 |
673
+ | `month` | `Date` | 否 | 显示的月份。仅取年月,日被忽略。 年月变化时视图跟随;年月不变的重渲染不重置用户已翻到的月份。 |
490
674
  | `selected` | `Date` | 否 | 选中日期 |
491
675
  | `onSelect` | `(date: Date) => void` | 否 | 选中日期变化回调 |
676
+ | `today` | `Date` | 否 | 「今天」。仅取年月日,按本地时区解读。默认取当前本地日期(06 · P2-20)。 决定今日高亮(`aria-current="date"`)、未传 `month` 时的初始月份、以及没有 选中日时 Tab 停顿的回落位置。以服务端时间为准的业务、服务端渲染(避免跨零点 的水合不一致)与测试(固定日期)传入它;其余场景不传。 |
492
677
 
493
678
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `onSelect` 已被本组件重新定义或移除。
494
679
 
495
680
  **用途。** 月格日期选择器控件,周一为一周起始(一…日),固定 252px 宽;今日为淡强调色洗,选中为强调色实心填充。
496
681
 
497
- **何时使用。** 作为日期字段的取值面板使用,与 `Input` 一同放进 `Popover`。筛选区间由调用方持有起止两个值,各配一个该组件。**该组件是控件,不是承载面** —— `CALENDAR` 页面模式与它同名但不同层,不得混用。
682
+ **何时使用。** 作为日期取值面板使用。表单里的单个日期直接用已封装好的 `DateInput`,工具栏的日期区间筛选用 `ApplicationDateRangeFilter`,两者内部都是本组件;只有这两者都不适用的自定义面板才直接把本组件放进 `Popover`。**该组件是控件,不是承载面** —— `CALENDAR` 页面模式与它同名但不同层,不得混用。
498
683
 
499
684
  **何时改用其他组件。**
500
- - 整页的日历承载面(`pageMode` 为 `CALENDAR`):由 `ApplicationPageLayoutContainer` 承担。
685
+ - 整页的日历承载面(`pageMode` 为 `CALENDAR`):`ApplicationDataDisplay` 的 `presentation="Calendar"`,月格按 SKILL.md「呈现配方」的月历写法拼装。
501
686
  - 粒度切换加月格加当日议程栏的工作台面:`ScheduleCollaborationWorkspace`。
502
687
  - 查询工具栏中作为 `dataPresentation` 的日历呈现方式:由数据呈现区承担,不是本控件。
503
- - 日期已知且可直接键入:`Input`。
688
+ - 表单里的单个日期字段:`DateInput`。
689
+ - 查询工具栏里的日期区间筛选:`ApplicationDateRangeFilter`。
504
690
 
505
- **组合约定。** `onSelect` 收到的是本地零点的 `Date`;落库、比较与按日期匹配一律使用本地时区的 ISO 日期串。`month` 只作用于首次渲染的初始月份,翻月游标由组件内部持有,后续更改 `month` 不会重置视图,调用方不得把它当受控 prop 使用。`selected` 为单值,该组件不表达区间高亮。置于 `Popover` 内时面板宽度不得小于 252px,`Popover` 的默认 320px 已足够容纳。星期名、上一月与下一月的无障碍名称、以及「年」「月」标题为中文常量,本库单语言。
691
+ **组合约定。** `onSelect` 收到的是本地零点的 `Date`;落库、比较与按日期匹配一律使用本地时区的 ISO 日期串。翻月游标由组件内部持有;`month` 的年月变化时视图跟随,年月不变的重渲染不重置用户已翻到的月份。网格只占一个 Tab 停顿,方向键逐日 / 逐周、Home / End 到周首 / 周末、PageUp / PageDown 跨月(加 Shift 跨年),Enter / 空格选中;日格的无障碍名称为完整日期加星期。`selected` 为单值,该组件不表达区间高亮。「今天」默认取当前本地日期;以服务端时间为准、服务端渲染或测试需要固定日期时传 `today`(`Date`,只取本地年月日),它同时决定今日高亮、未传 `month` 时的初始月份与无选中日时的 Tab 停顿。置于 `Popover` 内时面板宽度不得小于 252px,`Popover` 的默认 320px 已足够容纳。星期名、上一月与下一月的无障碍名称、以及「年」「月」标题为中文常量,本库单语言。
506
692
 
507
693
  **禁止 / 使用边界。**
508
694
  - 不得用 `toISOString()` 生成或比较日期串 —— 该写法在 UTC+8 下必然错位一天,今日高亮与选中判断会整体错一格。
@@ -534,6 +720,7 @@ ToggleGroup 的单个选项
534
720
  | `indeterminate` | `boolean` | 否 | 半选态,用于「全选」这类父级行。 视觉为一条横线,并上报 `aria-checked="mixed"`。优先级高于 `checked`。 |
535
721
  | `onCheckedChange` | `(checked: boolean) => void` | 否 | 选中态变化回调 |
536
722
  | `label` | `ReactNode` | 否 | 可见标签,渲染在方框右侧,与方框同属一个 `<label>` 因而可点击 |
723
+ | `invalid` | `boolean` | 否 | 校验失败态。方框描边转为 danger 色,内部 `<input>` 带 `aria-invalid`(06 · P1-16)。 置于 `Field` 内时须与 `Field.error` 同时设置 —— 两者不联动,见 I5。 |
537
724
 
538
725
  继承 `InputHTMLAttributes<HTMLInputElement>` 的全部原生属性,其中 `onChange`、`type` 已被本组件重新定义或移除。
539
726
 
@@ -552,6 +739,7 @@ ToggleGroup 的单个选项
552
739
 
553
740
  - `checked` 必须与 `onCheckedChange` 配对使用。非受控用 `defaultChecked`,与 `checked` 互斥。
554
741
  - `indeterminate` 优先级高于 `checked`,只用于「全选」这类父级行。
742
+ - `invalid` 把方框描边转为 danger 色并在内部 `<input>` 上输出 `aria-invalid`,与 `Field.error` 不联动,校验失败时两者必须同时设置。
555
743
  - `className` 与 `style` 作用于外层可见的 `<label>`,其余属性透传给内部 `<input>`(04 · I8)。因此 `id`、`name`、`value`、`aria-*` 会正确落在控件上,而布局类样式必须走 `className`。
556
744
  - 未传 `label` 时必须给 `aria-label` 或 `aria-labelledby`,否则该控件没有无障碍名称。
557
745
  - `label` 与方框同属一个 `<label>`,点击文字即可切换。放进 `Field` 时不得再用 `Field.label` 标注同一个控件。
@@ -582,9 +770,10 @@ ToggleGroup 的单个选项
582
770
  | `value` | `string` | 否 | 受控选中值 |
583
771
  | `defaultValue` | `string` | 否 | 非受控初始值 |
584
772
  | `onValueChange` | `(value: string) => void` | 否 | 选中值变化回调。选中后浮层关闭并清空输入 |
585
- | `placeholder` | `string` | 否 | 输入框占位文字 |
773
+ | `placeholder` | `string` | 否 | 输入框占位文字。默认「搜索选项」—— 写范围而非指令(02 §8 表单与说明文案) |
586
774
  | `emptyText` | `string` | 否 | 筛选无结果时的提示文字 |
587
775
  | `disabled` | `boolean` | 否 | 禁用 |
776
+ | `invalid` | `boolean` | 否 | 校验失败态。外壳边框转为 danger 色,输入框带 `aria-invalid`(06 · P1-16)。 置于 `Field` 内时须与 `Field.error` 同时设置 —— 两者不联动,见 I5。 |
588
777
 
589
778
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `defaultValue` 已被本组件重新定义或移除。
590
779
 
@@ -610,7 +799,7 @@ Combobox 的单个选项
610
799
  - 查询工具栏中的常驻筛选维度:`ApplicationFilterMenu`。
611
800
  - 2–5 个选项且要求全部可见:`RadioGroup`。
612
801
 
613
- **组合约定。** `ComboboxOption.label` 为非字符串时必须提供 `searchText`,否则该项永远无法被筛选命中,且无任何报错。`searchText` 同时用于收起状态下输入框内的回显,因此必须是完整可读的文本,不得写成匹配用的关键词缩写。该组件不提供 `invalid`,校验失败一律由包裹它的 `Field` 的 `error` 表达。宽度由父容器决定,浮层与输入框外壳等宽。选中后浮层关闭且输入被清空,调用方不得依赖输入内容作为提交值。
802
+ **组合约定。** `ComboboxOption.label` 为非字符串时必须提供 `searchText`,否则该项永远无法被筛选命中,且无任何报错。`searchText` 同时用于收起状态下输入框内的回显,因此必须是完整可读的文本,不得写成匹配用的关键词缩写。`invalid` 把外壳边框转为 danger 色并在输入框上输出 `aria-invalid`,与包裹它的 `Field` 的 `error` 不联动,校验失败时两者必须同时设置。`id`、`aria-label`、`aria-labelledby`、`aria-describedby` 落在输入框上,`Field htmlFor` 因此直接关联到输入框。聚焦不展开浮层,输入、↓ / ↑、Alt+↓ 或点击才展开,Tab 与失焦即收起。宽度由父容器决定,浮层与输入框外壳等宽。选中后浮层关闭且输入被清空,调用方不得依赖输入内容作为提交值。
614
803
 
615
804
  **禁止 / 使用边界。**
616
805
  - 不得把它当搜索框使用 —— 该组件没有提交回调,逐字实时搜索也被规范禁止。
@@ -618,6 +807,52 @@ Combobox 的单个选项
618
807
  - 不得把 `emptyText` 复用为加载中或加载失败的文案 —— 它只表达筛选无结果,六种状态各有各的措辞。
619
808
  - 不得在 `ComboboxOption.label` 中放入可交互元素。
620
809
 
810
+ ### DateInput
811
+
812
+ `import { DateInput } from '@moheng-design/ui'` · 契约 `contracts/foundation/input-selection/date-input.ts`
813
+
814
+ 单个日期的录入控件:与 `Input` 同高同壳(32px、12px 圆角、1px 描边),右侧带 16px
815
+ 日历图标,点击弹出 `Calendar` 月格,选中即回填并收起。
816
+
817
+ 值一律是本地时区的 ISO 日期串 `yyyy-mm-dd`(不是 `Date`,也不是带时区的时间戳)——
818
+ 表单提交与接口对接都按字符串走,组件内部用本地时区换算,不经 `toISOString()`。
819
+
820
+ 只选一个日期。日期区间筛选用 `ApplicationDateRangeFilter`;带时分的时刻本库暂无组件。
821
+
822
+ 在 `Field` 里使用时,`Field` 的 `htmlFor` 指向本组件的 `id`(落在触发按钮上)。
823
+
824
+ **Props**
825
+
826
+ | prop | 类型 | 必填 | 说明 |
827
+ |---|---|:---:|---|
828
+ | `value` | `string` | 否 | 受控值,ISO `yyyy-mm-dd`。空串或不传表示未选 |
829
+ | `defaultValue` | `string` | 否 | 非受控初始值,ISO `yyyy-mm-dd` |
830
+ | `onValueChange` | `(value: string) => void` | 否 | 值变化回调,给出 ISO `yyyy-mm-dd`;清空时给出空串 |
831
+ | `placeholder` | `string` | 否 | 未选时的占位文字。写明格式或含义,如「选择开票日期」 |
832
+ | `disabled` | `boolean` | 否 | 禁用 |
833
+ | `invalid` | `boolean` | 否 | 校验失败态。边框转为 danger 色并设置 `aria-invalid`。 置于 `Field` 内时须与 `Field.error` 同时设置 —— 两者不联动,与 `Input` 相同。 |
834
+ | `today` | `Date` | 否 | 「今天」,透传给 `Calendar`。以服务端时间为准、服务端渲染或测试时传入 |
835
+
836
+ 继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `defaultValue`、`onChange` 已被本组件重新定义或移除。
837
+
838
+ **用途。** 单个日期的录入控件:与 `Input` 同高同壳(32px、12px 圆角、1px 描边),右侧带 16px 日历图标,点击弹出 `Calendar` 月格,选中即回填并收起。
839
+
840
+ **何时使用。** 表单里需要录入一个日期(开票日期、到期日、生效日)时,必须使用本组件。值一律是本地时区的 ISO 日期串 `yyyy-mm-dd`,经 `value` / `onValueChange` 受控,或经 `defaultValue` 非受控;清空时回调给出空串。外壳是按钮而不是可键入的输入框,日期只能从月格里选。
841
+
842
+ **何时改用其他组件。**
843
+ - 查询工具栏里的日期区间筛选:改用 `ApplicationDateRangeFilter`。
844
+ - 自由文本或数字:改用 `Input`。
845
+ - 需要月格常驻展开、不收起的面板:直接用 `Calendar`。
846
+ - 整页的日历承载面:`ApplicationDataDisplay` 的 `presentation="Calendar"`。
847
+
848
+ **组合约定。** 置于 `Field` 内时,`Field.htmlFor` 与本组件的 `id` 成对设置,`id` 落在触发按钮上。`Field.error` 与本组件的 `invalid` 必须同时设置,两者不联动,与 `Input` 相同。`placeholder` 写明字段含义,如「选择开票日期」。以服务端时间为准、服务端渲染或测试需要固定日期时传 `today`,它透传给 `Calendar`。该组件不自带外边距,宽度撑满父容器,列宽由字段网格负责。
849
+
850
+ **禁止 / 使用边界。**
851
+ - 不得用 `Input` 加占位示例(「2026-07-28」)代替本组件录入日期。
852
+ - 不得用 `toISOString()` 生成或换算 `value` —— 在 UTC+8 下会错一天,一律用本地时区的 `yyyy-mm-dd`。
853
+ - 不得用两个本组件拼装工具栏里的日期区间筛选,那是 `ApplicationDateRangeFilter` 的职责,且它带「应用」提交与筛选标签回写。
854
+ - 禁止覆盖触发器的高度、圆角与描边,`className` 只用于布局定位。
855
+
621
856
  ### Field
622
857
 
623
858
  `import { Field } from '@moheng-design/ui'` · 契约 `contracts/foundation/input-selection/field.ts`
@@ -635,9 +870,10 @@ Combobox 的单个选项
635
870
  |---|---|:---:|---|
636
871
  | `label` | `ReactNode` | 否 | 标签文字。14/20 字号,色值 `--ds-color-text-label` |
637
872
  | `description` | `ReactNode` | 否 | 辅助说明,12/16 字号。`error` 存在时被其取代 |
638
- | `error` | `ReactNode` | 否 | 错误文字,12/16 字号 danger 色。设置后取代 `description`。 **不会自动把内部控件切到 invalid 态** —— 控件的 `invalid` 需另行设置。见 I5。 |
873
+ | `error` | `ReactNode` | 否 | 错误文字,12/16 字号 danger 色。设置后取代 `description`。 **不会自动把内部控件切到 invalid 态** —— 控件的 `invalid` 需另行设置。见 I5。 给了 `htmlFor` 时,错误(或说明)并入该控件的 `aria-describedby`,有错误时控件 若没有 `aria-invalid` 则补上 —— 只是读屏语义,失败态视觉仍归控件的 `invalid`。 |
639
874
  | `required` | `boolean` | 否 | 必填标记。在标签文字后追加 danger 色星号 |
640
- | `htmlFor` | `string` | 否 | 关联内部控件的 id。透传给内部 `<label for>` |
875
+ | `htmlFor` | `string` | 否 | 关联内部控件的 id。透传给内部 `<label for>`,并据此把说明 / 错误关联到控件 (`aria-describedby`)。控件包在别的组件里(`InputGroup`、`Popover`)时同样生效 |
876
+ | `span` | `'full'` | 否 | 网格跨度。`full` 时本行占满所在网格的全部列(输出 `data-span`,由本组件 CSS 写 `grid-column: 1 / -1`)。父级不是网格时无效果。 取代此前登记的 `style={{ gridColumn: '1 / -1' }}` —— 内联 style 违反 §1.7 (实践报告 P1-3,裁决:以规范为准)。 |
641
877
  | `children` | `ReactNode` | 否 | 受本行管辖的控件。仅一个 |
642
878
 
643
879
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
@@ -657,16 +893,17 @@ Combobox 的单个选项
657
893
 
658
894
  - `children` 只放一个控件。一行两个控件(如日期区间的起止)须拆成两个 Field,或由调用方容器自行排布。
659
895
  - 标签由 `Label` 渲染,`Label` 是标签视觉的 Foundation Owner。不得在 `children` 里另写一份标签实现(04 · I4)。
660
- - `htmlFor` 与控件的 `id` 必须成对设置。该组件不生成 id。
896
+ - `htmlFor` 与控件的 `id` 必须成对设置。该组件不生成 id。给了 `htmlFor` 时,说明与错误取 `<htmlFor>-description` / `<htmlFor>-error` 为 id 并并入该控件的 `aria-describedby`,控件包在 `InputGroup` 或 `Popover` 里同样生效;不给 `htmlFor` 则标签与说明都关联不到控件。错误带 `role="alert"`,出现即播报。
661
897
  - `error` 存在时取代 `description`,两者不同时显示。因此说明性信息不得成为错误文案的必要补充。
662
- - `error` 与内部控件的 `invalid` 必须同时设置。该组件不会把控件切到失败态(04 · I5),这是有意保留的不联动,漏写由阶段 5 的 lint 规则拦截。
898
+ - `error` 与内部控件的 `invalid` 必须同时设置。该组件不会把控件切到失败态视觉(04 · I5),这是有意保留的不联动;它只在控件没有 `aria-invalid` 时补上读屏语义。
663
899
  - `required` 只渲染标签后的星号,且该星号带 `aria-hidden`。必填语义必须由控件自身的 `required` 承担。
664
- - 字段之间的间距由 `ApplicationFormDialog` 的网格负责,该组件不自带外边距。跨列写法是给该组件传 `style={{ gridColumn: '1 / -1' }}`,这是 `ApplicationFormDialog` 契约登记的写法。
900
+ - 字段之间的间距由 `ApplicationFormDialog` 的网格负责,该组件不自带外边距。跨列写法是给该组件传 `span="full"`,规则由该组件自己的 CSS 承担,在任何网格父级内都生效。
665
901
 
666
902
  **禁止 / 使用边界。**
667
903
 
668
904
  - 不得用该组件改动内部控件的边框、高度或圆角 —— 控件视觉归控件自己所有。
669
905
  - 不得只设 `error` 而不设控件的 `invalid`:错误文字会出现,控件边框仍是常态色,且没有任何报错。
906
+ - 不得用内联 `style={{ gridColumn: … }}` 让本行跨列 —— 改传 `span="full"`;内联属性优先级最高,调用方的 `className` 覆盖随之失效(01 §1.7)。
670
907
  - 禁止在一个 Field 内放多个录入控件。
671
908
  - 不得用该组件包裹只读内容充当详情页布局。
672
909
  - 不得让 Loading / Empty / Error / No Permission / Not Found / Partial Failure 六种状态共用同一句 `error` 文案。
@@ -677,10 +914,10 @@ Combobox 的单个选项
677
914
 
678
915
  单行文本控件。
679
916
 
680
- 用于 `Field` 内的自由文本、数字与日期录入。
917
+ 用于 `Field` 内的自由文本与数字录入。单个日期用 `DateInput`。
681
918
  搜索请用 `SearchField` —— 它拥有紧凑工具栏外壳,不要用 Input 自行拼装。
682
919
 
683
- 最小高度 32px,8px 圆角。
920
+ 最小高度 32px,12px 圆角(GAP Design kit)。
684
921
  **焦点只在外层壳表达一次,内部不得再套第二圈焦点环。**
685
922
 
686
923
  **替换原生元素:** `<input>`
@@ -693,13 +930,14 @@ Combobox 的单个选项
693
930
 
694
931
  继承 `InputHTMLAttributes<HTMLInputElement>` 的全部原生属性。
695
932
 
696
- **用途。** 单行文本控件,承担表单行与筛选行内的自由文本、数字与日期录入。
933
+ **用途。** 单行文本控件,承担表单行与筛选行内的自由文本与数字录入。
697
934
 
698
- **何时使用。** 值由用户自由键入、不来自固定选项集合时,该控件是默认选择。最小高度 32px、圆角 8px、字号 14/20px,宽度撑满父容器。置于 `Field` 内构成标准表单行;置于 `InputGroup` 内构成带前后附加物的单一焦点单元;日期录入由该控件与 `Calendar` 一起放进 `Popover` 组成。
935
+ **何时使用。** 值由用户自由键入、不来自固定选项集合时,该控件是默认选择。最小高度 32px、圆角 12px、字号 14/20px,宽度撑满父容器。置于 `Field` 内构成标准表单行;置于 `InputGroup` 内构成带前后附加物的单一焦点单元。
699
936
 
700
937
  **何时改用其他组件。**
701
938
 
702
939
  - 纯文本搜索 → `SearchField`。产品内每一处搜索共用该入口,不得用该控件自行拼装工具栏搜索框。
940
+ - 单个日期 → `DateInput`;工具栏里的日期区间筛选 → `ApplicationDateRangeFilter`。
703
941
  - 多行备注、说明与事由 → `Textarea`。
704
942
  - 定长验证码 → `InputOTP`。
705
943
  - 值来自固定集合 → `Select`;选项极多或密集的行内编辑器 → `NativeSelect`;需要输入筛选 → `Combobox`;2–5 个选项且需全部可见 → `RadioGroup`。
@@ -713,6 +951,7 @@ Combobox 的单个选项
713
951
  - 置于 `Field` 内时,`Field.htmlFor` 与该控件的 `id` 必须成对设置。`Field` 不生成 id,缺一则标签点击不聚焦控件。
714
952
  - `Field.error` 与该控件的 `invalid` 必须同时设置。两者不联动(04 · I5):只设 `error` 时错误文字出现而边框仍为常态色,且没有任何报错。
715
953
  - 无可见标签的位置(工具栏、表格单元格编辑器)必须给 `aria-label`。
954
+ - `ref` 落到原生 `<input>` 本身(React 19;React 18 不把 `ref` 交给函数组件),取 DOM 不必再按 id 查询。
716
955
  - 置于 `InputGroup` 内时必须是壳的直接子元素,一个壳只放一个控件。焦点只在最外层壳表达一次。
717
956
 
718
957
  **禁止 / 使用边界。**
@@ -742,6 +981,7 @@ Combobox 的单个选项
742
981
  | `trailing` | `ReactNode` | 否 | 后置附加物,位于控件右侧。清除按钮、单位或提交动作 |
743
982
  | `children` | `ReactNode` | 否 | 受本壳管辖的控件。仅一个 |
744
983
  | `disabled` | `boolean` | 否 | 禁用整组。背景转为 `--ds-color-bg-3` |
984
+ | `invalid` | `boolean` | 否 | 校验失败态。外壳边框转为 danger 色(06 · P1-16)。 只管外壳视觉:壳是包装元素而非控件,`aria-invalid` 不落在它上面。读屏语义由 内部控件承担 —— 内部 `Input` 同设 `invalid`(壳内它的边框已被剥掉,只剩 `aria-invalid` 生效),或经 `Field.htmlFor` 由 Field 补上。 置于 `Field` 内时须与 `Field.error` 同时设置 —— 两者不联动,见 I5。 |
745
985
 
746
986
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
747
987
 
@@ -763,11 +1003,12 @@ Combobox 的单个选项
763
1003
  - 附加物一律走 `leading` 与 `trailing`,不得混写进 `children`。
764
1004
  - 附加物中的图标必须用 `Icon` 组件并取登记尺寸 14 / 16 / 18 / 20 / 24。
765
1005
  - 该组件的 `disabled` 只改外壳视觉,不会禁用内部控件。整组禁用时该组件的 `disabled` 与内部控件的 `disabled` 必须同时设置,否则外壳呈禁用色而输入框仍可键入。
1006
+ - `invalid` 同理只改外壳视觉:边框转为 danger 色,聚焦时焦点环也转为 danger 色,但不输出 `aria-invalid` —— 外壳是包装元素,失败语义属于内部控件。校验失败时该组件的 `invalid`、内部控件的 `invalid` 与 `Field.error` 三者必须同时设置。
766
1007
  - 外边距由父容器负责,该组件不自带 margin。
767
1008
 
768
1009
  **禁止 / 使用边界。**
769
1010
 
770
- - 不得依赖内部控件的 `invalid` 表达可见的校验失败态 —— 外壳已把内部控件的边框剥掉,该位置的 `invalid` 只保留 `aria-invalid` 语义。可见失败态由包裹该组件的 `Field` 的 `error` 承担。
1011
+ - 不得只设内部控件的 `invalid` 表达校验失败 —— 外壳已把内部控件的边框剥掉,该位置的 `invalid` 只保留 `aria-invalid` 语义,边框仍是常态色。可见失败态由该组件自己的 `invalid` 承担。
771
1012
  - 不得让内部控件再绘制第二圈焦点环。焦点由外壳的 `:focus-within` 表达一次。
772
1013
  - 禁止把该组件的外壳样式复制进业务代码,用来自制搜索框、单位输入框或带按钮的输入框。
773
1014
  - 不得在一个壳内放两个及以上录入控件。
@@ -792,6 +1033,7 @@ Combobox 的单个选项
792
1033
  | `defaultValue` | `string` | 否 | 非受控初始值 |
793
1034
  | `onValueChange` | `(value: string) => void` | 否 | 值变化回调。每输入一个字符触发一次 |
794
1035
  | `disabled` | `boolean` | 否 | 禁用整组 |
1036
+ | `invalid` | `boolean` | 否 | 校验失败态。全部方框边框转为 danger 色,每个方框带 `aria-invalid`(06 · P1-16)。 置于 `Field` 内时须与 `Field.error` 同时设置 —— 两者不联动,见 I5。 |
795
1037
 
796
1038
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `defaultValue` 已被本组件重新定义或移除。
797
1039
 
@@ -810,6 +1052,7 @@ Combobox 的单个选项
810
1052
  - `value` 与 `onValueChange` 必须成对使用。只传 `value` 不传回调,该组件不可输入。非受控用 `defaultValue`,与 `value` 二者不得同时给。
811
1053
  - 值以空格占位保持「第 i 个字符对应第 i 格」,尾部空格被裁掉。调用方在提交前必须同时判定「不含空格」与「长度等于 `length`」,只比长度会把跳格漏填的码判为已填完。
812
1054
  - 粘贴由该组件接管:从当前格起依次填入,并把焦点移到最后一个填充位。调用方不得再自行绑定粘贴处理。
1055
+ - `invalid` 把全部方框边框转为 danger 色并逐格输出 `aria-invalid`,与 `Field.error` 不联动,校验失败时两者必须同时设置。
813
1056
  - 每个方框自带中文 `aria-label`(第 N 位),该文案不可覆盖 —— 单语言是既定裁决(04 · I16),不是遗漏。
814
1057
  - 外边距与整体对齐由父容器负责,该组件不自带 margin。
815
1058
 
@@ -944,6 +1187,7 @@ NativeSelect 的单个选项。label 为纯文本 —— 原生 `<option>` 不
944
1187
  | `name` | `string` | 否 | 原生 radio 的 name,同组共享。 不传时自动生成 —— 生成方式见 I7,当前实现在 SSR 下有缺陷。 |
945
1188
  | `orientation` | `'vertical' \| 'horizontal'` | 否 | 排列方向。垂直间距 `--ds-space-2`,水平间距 `--ds-space-4` |
946
1189
  | `disabled` | `boolean` | 否 | 整组禁用。单个选项的禁用用 `RadioGroupItem.disabled` |
1190
+ | `invalid` | `boolean` | 否 | 校验失败态。全部圆点描边转为 danger 色,`role="radiogroup"` 的根元素带 `aria-invalid`(06 · P1-16)。 置于 `Field` 内时须与 `Field.error` 同时设置 —— 两者不联动,见 I5。 |
947
1191
 
948
1192
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `defaultValue` 已被本组件重新定义或移除。
949
1193
 
@@ -968,7 +1212,7 @@ RadioGroup 的单个选项
968
1212
  - 立即生效的开关:`Switch`。
969
1213
  - 该维度需要多选:`ApplicationFilterMenu` 或 `ToggleGroup`。
970
1214
 
971
- **组合约定。** 组内间距由组件自身负责,垂直排列为 `--ds-space-2`、水平排列为 `--ds-space-4`,调用方不得再给选项加外边距。`name` 不传时自动生成且在 SSR 下稳定,仅当该组需参与原生 `<form>` 序列化时才显式设置。整组禁用用 `disabled`,单个选项的禁用用 `RadioGroupItem.disabled`,两者不得互相替代。剩余属性落在 `role="radiogroup"` 的根元素上,因此 `aria-label` 可用于给出组名。每个选项整行是一个 `<label>`,点击行内任意位置都会切换选中。
1215
+ **组合约定。** 组内间距由组件自身负责,垂直排列为 `--ds-space-2`、水平排列为 `--ds-space-4`,调用方不得再给选项加外边距。`name` 不传时自动生成且在 SSR 下稳定,仅当该组需参与原生 `<form>` 序列化时才显式设置。整组禁用用 `disabled`,单个选项的禁用用 `RadioGroupItem.disabled`,两者不得互相替代。`invalid` 把全部圆点描边转为 danger 色,并在 `role="radiogroup"` 的根元素上输出 `aria-invalid`;与 `Field.error` 不联动,校验失败时两者必须同时设置。剩余属性落在 `role="radiogroup"` 的根元素上,因此 `aria-label` 可用于给出组名。每个选项整行是一个 `<label>`,点击行内任意位置都会切换选中。
972
1216
 
973
1217
  **禁止 / 使用边界。**
974
1218
  - 不得逐个渲染单选项后手工拼组,那会丢掉分组的键盘导航与 `name` 绑定。
@@ -1000,7 +1244,7 @@ RadioGroup 的单个选项
1000
1244
  | `value` | `string` | 否 | 受控选中值 |
1001
1245
  | `defaultValue` | `string` | 否 | 非受控初始值 |
1002
1246
  | `onValueChange` | `(value: string) => void` | 否 | 选中值变化回调。选中后浮层自动关闭 |
1003
- | `placeholder` | `string` | 否 | 未选中时的占位文字,以 placeholder 色显示 |
1247
+ | `placeholder` | `string` | 否 | 未选中时的占位文字,以 placeholder 色显示。默认「未选择」—— 写状态而非指令, 不写「请选择」(02 §8 表单与说明文案,07 · C-4) |
1004
1248
  | `disabled` | `boolean` | 否 | 禁用 |
1005
1249
  | `invalid` | `boolean` | 否 | 校验失败态。边框转为 danger 色 |
1006
1250
 
@@ -1029,7 +1273,7 @@ Select 的单个选项
1029
1273
  - 条目是动作而非取值(编辑、删除、导出):`DropdownMenu`。
1030
1274
  - 该维度需要多选:`ApplicationFilterMenu` 或 `ToggleGroup`。该组件只承载单值。
1031
1275
 
1032
- **组合约定。** 触发器宽度撑满父容器,浮层与触发器等宽,因此宽度必须由父级布局或 `Field` 决定,组件自身不设宽度、不带外边距。`SelectOption` 的 label 在触发器与选项内均以省略号截断,故标签必须在触发器宽度内读完。受控用法下 `value` 与 `onValueChange` 必须成对出现;只给 `value` 而不给 `onValueChange` 会得到一个永不改变的控件。`invalid` 与包裹它的 `Field` 的 `error` 不联动,校验失败时两者必须同时设置。剩余属性落在根 `<div>` 上而非触发器,因此 `Field.htmlFor` 对该组件无效,可见标签必须由 `Field.label` 或 `Label` 给出。占位文字默认为「请选择」,本库单语言,不接受运行时本地化。
1276
+ **组合约定。** 触发器宽度撑满父容器,浮层与触发器等宽,因此宽度必须由父级布局或 `Field` 决定,组件自身不设宽度、不带外边距。`SelectOption` 的 label 在触发器与选项内均以省略号截断,故标签必须在触发器宽度内读完。受控用法下 `value` 与 `onValueChange` 必须成对出现;只给 `value` 而不给 `onValueChange` 会得到一个永不改变的控件。`invalid` 与包裹它的 `Field` 的 `error` 不联动,校验失败时两者必须同时设置。`id`、`aria-label`、`aria-labelledby`、`aria-describedby` 落在触发按钮上,其余属性落在根 `<div>`;因此 `Field.htmlFor` 配触发器的 `id` 即关联到按钮,无可见标签的场景(排序控件)用 `aria-label` 命名。按钮名称来自标签时,当前值经 `aria-describedby` 补报。占位文字默认为「未选择」,写状态而非指令,不得改回「请选择」一类祈使句(07 · C-4);本库单语言,不接受运行时本地化。
1033
1277
 
1034
1278
  **禁止 / 使用边界。**
1035
1279
  - 不得向 `value` 传数组充当多选。
@@ -1101,6 +1345,7 @@ Select 的单个选项
1101
1345
  | `defaultChecked` | `boolean` | 否 | 非受控初始开启态。与 `checked` 互斥 |
1102
1346
  | `onCheckedChange` | `(checked: boolean) => void` | 否 | 开启态变化回调。因为立即生效,回调应直接落库或落配置 |
1103
1347
  | `label` | `ReactNode` | 否 | 可见标签,渲染在轨道右侧,与轨道同属一个 `<label>` 因而可点击 |
1348
+ | `busy` | `boolean` | 否 | 落库中(06 · P3-17)。`onCheckedChange` 发起的保存尚未返回时设为 true。 期间控件**保持可聚焦**、带 `aria-busy`,点击与空格不再切换(不改内部状态、 不调 `onCheckedChange`),滑块内显示进行中指示。不要用 `disabled` 表达这段 等待 —— 它让按钮失焦,焦点掉到 `body`,键盘用户得从页首重新找回来。 |
1104
1349
 
1105
1350
  继承 `ButtonHTMLAttributes<HTMLButtonElement>` 的全部原生属性,其中 `onChange` 已被本组件重新定义或移除。
1106
1351
 
@@ -1115,13 +1360,14 @@ Select 的单个选项
1115
1360
  - 一组互斥的显示选项:`ToggleGroup`。
1116
1361
  - 列表与表格的行选择:`ListSelectionCheckbox`。
1117
1362
 
1118
- **组合约定。** `className` 与 `style` 作用于外层可见的 `<label>`,其余属性透传给内部 `<button role="switch">`,这条分流是既定约定,调用方须按此预期传参。可见标签一律走 `label` prop,它与轨道同属一个 `<label>` 因而可点击;没有可见标签时必须提供 `aria-label`。`onCheckedChange` 应直接落库或落配置,回调内不得再排队等待外部提交。成组出现时的行距由容器负责,组件自身不带外边距。
1363
+ **组合约定。** `className` 与 `style` 作用于外层可见的 `<label>`,其余属性透传给内部 `<button role="switch">`,这条分流是既定约定,调用方须按此预期传参。可见标签一律走 `label` prop,它与轨道同属一个 `<label>` 因而可点击;没有可见标签时必须提供 `aria-label`。`onCheckedChange` 应直接落库或落配置,回调内不得再排队等待外部提交。保存未返回期间设 `busy`:控件保持可聚焦并带 `aria-busy`,点击与空格不再切换,滑块内显示进行中指示。成组出现时的行距由容器负责,组件自身不带外边距。
1119
1364
 
1120
1365
  **禁止 / 使用边界。**
1121
1366
  - 不得把它放进 `ApplicationFormDialog` 的 `Field` 行充当表单字段 —— 表单行承载的是等待提交的数据,与立即生效语义相反。
1122
1367
  - 不得为它另配「应用」按钮。
1123
1368
  - 不得用它触发不可逆或破坏性操作,那类操作必须先经 `AlertDialog` 确认。
1124
1369
  - 禁止覆盖 36×20 轨道与 16px 滑块的已登记几何。
1370
+ - 不得用 `disabled` 表达保存中的等待 —— 禁用会让按钮失焦,键盘焦点掉到 `body`;改用 `busy`。
1125
1371
 
1126
1372
  ### Textarea
1127
1373
 
@@ -1159,7 +1405,7 @@ Select 的单个选项
1159
1405
  - `Field.error` 与该控件的 `invalid` 必须同时设置(04 · I5),两者不联动。
1160
1406
  - 置于 `Field` 内时,`Field.htmlFor` 与该控件的 `id` 必须成对设置。
1161
1407
  - 无可见标签的位置必须给 `aria-label`。
1162
- - 置于 `ApplicationFormDialog` 的字段网格中时,跨列由外层 `Field` 承担 —— 契约登记的写法是给 `Field` 传 `style={{ gridColumn: '1 / -1' }}`,该控件本身不参与网格定位。
1408
+ - 置于 `ApplicationFormDialog` 的字段网格中时,跨列由外层 `Field` 承担 —— 给 `Field` 传 `span="full"`,该控件本身不参与网格定位。
1163
1409
  - 外边距由父容器负责,该控件不自带 margin。
1164
1410
 
1165
1411
  **禁止 / 使用边界。**
@@ -1210,7 +1456,7 @@ Accordion 的单个折叠区
1210
1456
 
1211
1457
  **何时改用其他组件。** 只有一个折叠区、且该区是「更多筛选」这类单一显隐入口时,改用 `Collapsible`。需要在页面区域内切换互斥内容、且切换后内容占满同一块区域时,改用 `Tabs`。业务详情的字段分节改用 `ApplicationRecordDetailBody` 的 `sections`,它已登记标题行、字段网格与分节级动作。原生 `<details>` / `<summary>` 一律不得出现,替换目标见 `mappings.json` 的 `no-native-details` 与 `no-native-summary`。
1212
1458
 
1213
- **组合约定。** 该组件根节点自带上边线,每个折叠区自带下边线,因此两个 Accordion 直接相邻时接缝处会出现 2px 线;两者之间必须存在其他内容,或改为合并进同一个 `items`。组件不带任何外边距,与上下内容的间距由容器负责。`type` 为 `single` 时组件只在自身的展开动作中收敛为至多一项,外部通过 `open` 传入的数组原样渲染 —— 受控模式下调用方必须自行保证 `single` 时数组长度为 0 或 1。`open` 与 `onOpenChange` 必须成对提供,只传 `open` 会使全部触发行失效。`title` 已由组件负责渲染展开箭头,调用方不得在 `title` 内再放一个方向字形。
1459
+ **组合约定。** 该组件根节点自带上边线,每个折叠区自带下边线,因此两个 Accordion 直接相邻时接缝处会出现 2px 线;两者之间必须存在其他内容,或改为合并进同一个 `items`。组件不带任何外边距,与上下内容的间距由容器负责。`type` 为 `single` 时组件只在自身的展开动作中收敛为至多一项,外部通过 `open` 传入的数组原样渲染 —— 受控模式下调用方必须自行保证 `single` 时数组长度为 0 或 1。`open` 与 `onOpenChange` 必须成对提供,只传 `open` 会使全部触发行失效。`title` 已由组件负责渲染展开箭头,调用方不得在 `title` 内再放一个方向字形。标题行以 `aria-controls` 指向展开的内容区,内容区是以标题行命名的 `region`;↑ / ↓ 在标题行间移动焦点、首尾相接,Home / End 跳到首末项,每个标题行仍是各自的 Tab 停靠点。
1214
1460
 
1215
1461
  **禁止 / 使用边界。**
1216
1462
  - 不得用于页面级或区域级的内容切换,那是 `Tabs` 的职责。
@@ -1254,10 +1500,10 @@ Breadcrumb 的单个层级
1254
1500
 
1255
1501
  **何时改用其他组件。** 表达「当前处于哪个模块」以及模块间切换,改用 `ApplicationModuleSwitcher`。SPLIT 页面模式中表达「当前在目录的哪个位置」,改用 `ApplicationSplitListSidebar`。同层级之间的并列切换改用 `Tabs` 或 `NavigationMenu`。
1256
1502
 
1257
- **组合约定。** 该组件只能作为 `ApplicationPageHeader` 的 `breadcrumb` 内容传入,间距与位置由上下文区负责,组件自身无外边距。中间层级按三态渲染:提供 `href` 渲染链接,仅提供 `onClick` 渲染按钮,两者都不提供渲染静态文本 —— 不可点击的层级必须走第三态,不得以空字符串或占位地址伪造链接。使用前端路由时必须同时提供 `href` 与 `onClick`,并在 `onClick` 内自行阻止默认跳转,组件不代为调用 `preventDefault`。末项无论是否提供 `href` 或 `onClick` 都渲染为当前页文本,两者在末项上均无效果。
1503
+ **组合约定。** 该组件只能作为 `ApplicationPageHeader` 的 `breadcrumb` 内容传入,间距与位置由上下文区负责,组件自身无外边距。中间层级按三态渲染:提供 `href` 渲染链接,仅提供 `onClick` 渲染按钮,两者都不提供渲染静态文本 —— 不可点击的层级必须走第三态,不得以空字符串或占位地址伪造链接。使用前端路由时必须同时提供 `href` 与 `onClick`,并在 `onClick` 内自行阻止默认跳转,组件不代为调用 `preventDefault`。末项无论是否提供 `href` 或 `onClick` 都渲染为当前页文本,两者在末项上均无效果。组件输出 `nav > ol > li` 结构,分隔字形在 `li` 内且对读屏隐藏。
1258
1504
 
1259
1505
  **禁止 / 使用边界。**
1260
- - 不得放进 Shell 的三条导航带 —— `TopNavigationPrimaryBar` 契约已明令禁止在其中添加面包屑。
1506
+ - 不得放进 Shell 的导航带 —— `TopNavigationPrimaryBar` 契约已明令禁止在其中添加面包屑。
1261
1507
  - 不得在页面并无真实层级时把面包屑作为装饰渲染。
1262
1508
  - 不得把末项写成链接,当前页不是可跳转目标。
1263
1509
  - 禁止用面包屑承担模块导航或页面动作。
@@ -1267,10 +1513,17 @@ Breadcrumb 的单个层级
1267
1513
 
1268
1514
  `import { Command } from '@moheng-design/ui'` · 契约 `contracts/foundation/navigation-command/command.ts`
1269
1515
 
1270
- 键盘优先的命令面板 —— 放进 `Dialog` 里作为全局搜索与执行入口。
1516
+ 键盘优先的命令面板 —— 以 `dialog` 形态作为全局搜索与执行入口。
1271
1517
 
1272
1518
  本地筛选。**筛选后无命中的分组整组消失**,不显示空标题。
1273
1519
 
1520
+ #### `dialog` 形态(06 · P1-15)
1521
+ 面板自身就是模态框:与 `Dialog` 共用同一个基座(遮罩、Esc、焦点陷阱、关闭后
1522
+ 焦点恢复、滚动锁定),打开时焦点落在输入框,没有标题栏与关闭按钮 —— 搜索行
1523
+ 就是头部;宽度受视口边距约束,不溢出。此前只能把本组件放进 `Dialog`:不传
1524
+ `title` 仍渲染空标题栏、初始焦点落在「关闭」、420px 宽在 Dialog 主体内溢出,
1525
+ 且与「不得被带边框的容器包裹」互相矛盾。
1526
+
1274
1527
  目录中已登记,但**尚未在生产业务代码中集成**。见 I20。
1275
1528
 
1276
1529
  **Props**
@@ -1278,9 +1531,12 @@ Breadcrumb 的单个层级
1278
1531
  | prop | 类型 | 必填 | 说明 |
1279
1532
  |---|---|:---:|---|
1280
1533
  | `groups` | `CommandGroup[]` | 是 | 命令分组集合 |
1281
- | `placeholder` | `string` | 否 | 输入框占位文字 |
1534
+ | `placeholder` | `string` | 否 | 输入框占位文字。默认「搜索命令」—— 写范围而非指令(02 §8 表单与说明文案) |
1282
1535
  | `emptyText` | `string` | 否 | 筛选无结果时的提示文字 |
1283
- | `onSelect` | `(value: string) => void` | 否 | 命令选中回调 |
1536
+ | `onSelect` | `(value: string) => void` | 否 | 命令选中回调。`dialog` 形态下选中后是否收起由调用方在这里决定 |
1537
+ | `dialog` | `boolean` | 否 | 以模态外壳渲染。可访问名取 `aria-label` / `aria-labelledby`(同时落在模态框与 输入框上),缺省时回落到 `placeholder` |
1538
+ | `open` | `boolean` | 否 | `dialog` 形态下是否打开。为 false 时渲染 `null`;非 `dialog` 形态忽略 |
1539
+ | `onOpenChange` | `(open: boolean) => void` | 否 | `dialog` 形态下的开合回调:Esc 与遮罩点击以 `false` 调用 |
1284
1540
 
1285
1541
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `onSelect` 已被本组件重新定义或移除。
1286
1542
 
@@ -1307,14 +1563,15 @@ Command 的命令分组
1307
1563
 
1308
1564
  **用途。** 键盘优先的命令面板,本地筛选并执行已登记命令。
1309
1565
 
1310
- **何时使用。** 作为全局命令与跳转入口时使用该组件,命令按 `groups` 分组,筛选后为空的分组连标题一起消失。面板宽 420px、列表区最高 320px,自带 1px 边框、12px 圆角与浮层阴影。上下键在跨分组的扁平序列上移动,回车执行当前项。
1566
+ **何时使用。** 作为全局命令与跳转入口时使用该组件,命令按 `groups` 分组,筛选后为空的分组连标题一起消失。面板宽 420px、列表区最高 320px,自带 1px 边框、12px 圆角与浮层阴影。上下键在跨分组的扁平序列上移动,回车执行当前项。有命中时首项自动高亮,打完字直接回车即执行。
1311
1567
 
1312
1568
  **何时改用其他组件。** 列表页的数据查询改用 `ApplicationQueryToolbar` 的搜索行,独立的纯文本搜索入口改用 `SearchField`(`mappings.json` 的 `no-native-search` 指向它)。表单内「输入即筛选」的单选控件改用 `Combobox`。上下文区或行尾收纳低频动作改用 `DropdownMenu`。
1313
1569
 
1314
- **组合约定。** 该组件必须由 `Dialog` 承载,作为 `children` 传入;它自带边框、圆角与浮层阴影,不得再被 `Card`、`Popover` 或任何带边框的容器包裹。承载它的 `Dialog` 不得再传 `title`、`description` 或 `footer` —— 搜索行就是面板的头部。关闭由 `Dialog` 负责,该组件自身不处理关闭。`CommandGroup.label` 是组件的 React key,必须在整个面板内唯一。`CommandItem.label` 为非字符串时必须提供 `searchText`,否则该项永远不会被筛选命中,且不产生任何报错。`shortcut` 仅作展示,真实快捷键必须由应用层自行注册,两处文本必须一致。
1570
+ **组合约定。** 作为全局命令入口时必须用 `dialog` 形态,以 `open` 与 `onOpenChange` 受控:面板自身就是模态框,与 `Dialog` 共用同一个模态基座(遮罩、Esc 与遮罩点击关闭、焦点陷阱、关闭后焦点恢复、背景滚动锁定),打开时焦点落在输入框,没有标题栏与关闭按钮 —— 搜索行就是面板的头部;宽度受视口边距约束;关闭时清空输入。选中命令后是否收起由调用方在 `onSelect` 里调用自己的关闭逻辑。它自带边框、圆角与浮层阴影,不得再放进 `Dialog`,也不得被 `Card`、`Popover` 或任何带边框的容器包裹。输入框是 `role="combobox"`,以 `aria-activedescendant` 指向高亮项;可访问名取传给本组件的 `aria-label` / `aria-labelledby`(落在输入框上,`dialog` 形态下同时落在模态框上),缺省时回落到 `placeholder`。`CommandGroup.label` 是组件的 React key,必须在整个面板内唯一。`CommandItem.label` 为非字符串时必须提供 `searchText`,否则该项永远不会被筛选命中,且不产生任何报错。`shortcut` 仅作展示,真实快捷键必须由应用层自行注册,两处文本必须一致。
1315
1571
 
1316
1572
  **禁止 / 使用边界。**
1317
1573
  - 不得把该组件直接放进页面内容流,它是浮层面板。
1574
+ - 不得把该组件放进 `Dialog` 承载,模态用法一律用 `dialog` 形态。
1318
1575
  - 不得在 `label` 为非字符串时省略 `searchText`。
1319
1576
  - 禁止在 `shortcut` 中声明应用层并未注册的按键组合。
1320
1577
  - 禁止分组标题重名。
@@ -1329,6 +1586,11 @@ Command 的命令分组
1329
1586
  ⚠ **绝不能是某个动作的唯一入口。** 记录级动作必须同时出现在行尾或详情中 ——
1330
1587
  右键是加速器,不是可达性路径。
1331
1588
 
1589
+ 菜单内的点击、指针与键盘事件在菜单根截停,**不冒泡**到 `children` 及其祖先 ——
1590
+ 放在可点击的记录行里,选中条目不会连带触发行的 `onClick` / 回车。
1591
+ 高亮项每次打开都清空;Esc 关闭或选中后,焦点回到打开菜单前持有焦点的元素。
1592
+ 任一祖先滚动或窗口尺寸变化时菜单收起。
1593
+
1332
1594
  **Props**
1333
1595
 
1334
1596
  | prop | 类型 | 必填 | 说明 |
@@ -1354,14 +1616,15 @@ ContextMenu 的单个条目。`separator: true` 时其余字段忽略
1354
1616
 
1355
1617
  **用途。** 内容区域上的右键加速器 —— 列表行、卡片、看板块。
1356
1618
 
1357
- **何时使用。** 已在别处可达的记录级动作需要一条更快的路径时使用该组件。条目支持图标、禁用、危险色与分隔线;键盘导航跳过禁用项与分隔线,回车确认,Esc 与外部点击关闭。菜单按点击坐标定位,并在打开后按实测尺寸收回视口内。
1619
+ **何时使用。** 已在别处可达的记录级动作需要一条更快的路径时使用该组件。条目支持图标、禁用、危险色与分隔线;键盘导航跳过禁用项与分隔线,回车确认,Esc、Tab、外部点击、任一祖先滚动与窗口尺寸变化都会关闭。高亮项每次打开都清空,不沿用上一次停留的条目。Esc 关闭或选中后,焦点回到打开菜单前持有焦点的元素。菜单按点击坐标定位,并在绘制前按实测尺寸收回视口内。
1358
1620
 
1359
1621
  **何时改用其他组件。** 需要一个可见的触发器(上下文区或行尾的「更多」)改用 `DropdownMenu`,它另有 `heading` 字段可渲染分组标题。编辑器型工作面的常驻菜单条改用 `Menubar`。整行可点击的目录或选择器行改用 `Item`,业务记录行改用 `ApplicationRecordList`。
1360
1622
 
1361
- **组合约定。** `children` 是右键触发区域,组件会在其外包一层 `position: relative` 的块级元素;在表格行或网格布局内使用时必须确认该额外层不破坏既有布局。任何动作都不得以右键菜单为唯一入口,记录级动作必须同时出现在行尾或详情中 —— 右键是加速器,不是可达性路径。可点击条目必须提供 `value`,缺少 `value` 的非分隔线条目会渲染出来却永不触发 `onSelect`。`destructive` 只把文字转为 danger 色,不改变确认流程,不可逆动作仍须由 `AlertDialog` 二次确认。`separator` 不得作为首项或末项。
1623
+ **组合约定。** `children` 是右键触发区域,组件会在其外包一层 `position: relative` 的块级元素;在表格行或网格布局内使用时必须确认该额外层不破坏既有布局。任何动作都不得以右键菜单为唯一入口,记录级动作必须同时出现在行尾或详情中 —— 右键是加速器,不是可达性路径。可点击条目必须提供 `value`,缺少 `value` 的非分隔线条目会渲染出来却永不触发 `onSelect`。`destructive` 只把文字转为 danger 色,不改变确认流程,不可逆动作仍须由 `AlertDialog` 二次确认。`separator` 不得作为首项或末项。菜单内的点击、指针与键盘事件在菜单根截停,不冒泡到 `children` 及其祖先,因此该组件可以直接包在带 `onOpen` 的可点击记录行内 —— 选中条目不会连带触发行的点击或回车;外层若需要感知菜单动作,必须经 `onSelect` 获取,不得依赖事件冒泡。
1362
1624
 
1363
1625
  **禁止 / 使用边界。**
1364
1626
  - 不得把任何动作只放在右键菜单里。
1627
+ - 不得依赖菜单内的点击或按键冒泡到外层元素,菜单动作一律经 `onSelect` 获取。
1365
1628
  - 禁止嵌套两层 ContextMenu —— 右键事件会冒泡,内外两个菜单将同时打开。
1366
1629
  - 不得省略可点击条目的 `value`。
1367
1630
  - 禁止用连续的 `separator` 模拟分组标题,需要标题的菜单改用 `DropdownMenu`。
@@ -1376,6 +1639,11 @@ ContextMenu 的单个条目。`separator: true` 时其余字段忽略
1376
1639
  ⚠ **只能位于 Content Canvas 内部。** Shell 拥有自己的导航,不承载菜单条。
1377
1640
  **绝不用作页面导航** —— 那是 Shell 的职责。
1378
1641
 
1642
+ 键盘按 WAI-ARIA menubar 模式:菜单条只有一个 Tab 停靠点,← / → 在顶级菜单项间
1643
+ 循环;Enter / 空格 / ↓ 打开并高亮首个可用项,↑ 打开并高亮末项;面板内 ↑ / ↓ /
1644
+ Home / End 移动并跳过禁用项,Enter / 空格选中,← / → 切到相邻顶级菜单;
1645
+ 选中与 Esc 后焦点回到顶级菜单项,Tab 收起面板并离开菜单条。
1646
+
1379
1647
  目录中已登记,但**尚未在生产业务代码中集成**。见 I20。
1380
1648
 
1381
1649
  **Props**
@@ -1410,11 +1678,11 @@ Menubar 的单个顶级菜单
1410
1678
 
1411
1679
  **用途。** 桌面风格的水平菜单条,用于编辑器型工作面 —— 报表设计器、看板配置器。
1412
1680
 
1413
- **何时使用。** 一个工作面同时拥有 2 个及以上顶级菜单、且每个菜单内含多条低频命令时使用该组件。菜单条高 32px、顶级菜单项高 24px、自带 1px 边框与 8px 圆角。菜单条已展开时,鼠标划过其他顶级菜单直接切换,这是桌面菜单的既定惯例。
1681
+ **何时使用。** 一个工作面同时拥有 2 个及以上顶级菜单、且每个菜单内含多条低频命令时使用该组件。菜单条高 32px、顶级菜单项高 24px、自带 1px 边框与 8px 圆角。菜单条已展开时,鼠标划过其他顶级菜单直接切换,这是桌面菜单的既定惯例。键盘按 WAI-ARIA menubar 模式:菜单条只有一个 Tab 停靠点,← / → 在顶级菜单项间循环,Home / End 跳到首末项;Enter / 空格 / ↓ 打开并高亮首个可用项,↑ 打开并高亮末项;面板内 ↑ / ↓ / Home / End 移动并跳过禁用项,Enter / 空格选中并收起,← / → 切到相邻顶级菜单并打开;选中与 Esc 后焦点回到顶级菜单项,Tab 收起面板并离开菜单条。
1414
1682
 
1415
1683
  **何时改用其他组件。** 只有一个下拉时改用 `DropdownMenu`。页面或区域之间的导航改用 `NavigationMenu`、`Tabs` 或 `Sidebar`。应用二级导航改用 `ApplicationSecondaryNavigation`。右键加速器改用 `ContextMenu`。
1416
1684
 
1417
- **组合约定。** 该组件只能位于 Content Canvas 内部,Shell 拥有自己的导航,不承载菜单条。`MenubarMenu.label` 同时是 React key 与展开态标识,必须在菜单条内唯一,重名会导致两个菜单同时展开。组件不接受子元素,顶级菜单只能来自 `menus` 数组 —— 不得在菜单项之间插入其他控件;工具按钮应放在菜单条之外的同一行容器内,间距由该容器负责。可点击条目必须提供 `value`。`shortcut` 仅作展示,真实按键绑定由承载它的工作面自行注册。
1685
+ **组合约定。** 该组件只能位于 Content Canvas 内部,Shell 拥有自己的导航,不承载菜单条。`MenubarMenu.label` 是顶级菜单的 React key,必须在菜单条内唯一,重名会导致面板挂载错乱。组件不接受子元素,顶级菜单只能来自 `menus` 数组 —— 不得在菜单项之间插入其他控件;工具按钮应放在菜单条之外的同一行容器内,间距由该容器负责。可点击条目必须提供 `value`。`shortcut` 仅作展示,真实按键绑定由承载它的工作面自行注册。
1418
1686
 
1419
1687
  **禁止 / 使用边界。**
1420
1688
  - 不得用作页面导航,那是 Shell 的职责。
@@ -1434,6 +1702,10 @@ Menubar 的单个顶级菜单
1434
1702
  ⚠ 这是 Foundation 基元。**应用二级导航请用 `ApplicationSecondaryNavigation`** ——
1435
1703
  那里每个标签强制 `图标 + 文字`,本基元不施加该约束。
1436
1704
 
1705
+ 面板在悬停、聚焦或点击时展开;指针离开槽位后延时 150ms 收起,其间移入面板即取消。
1706
+ Esc 收起面板,焦点在面板内时回到条目。激活项标 `aria-current`,取值由 `current`
1707
+ 区分「切换页面」(默认 `page`)与「页内切换」(`true`)。
1708
+
1437
1709
  **Props**
1438
1710
 
1439
1711
  | prop | 类型 | 必填 | 说明 |
@@ -1442,6 +1714,7 @@ Menubar 的单个顶级菜单
1442
1714
  | `value` | `string` | 否 | 受控选中值 |
1443
1715
  | `defaultValue` | `string` | 否 | 非受控初始值 |
1444
1716
  | `onValueChange` | `(value: string) => void` | 否 | 选中值变化回调 |
1717
+ | `current` | `'page' \| 'true'` | 否 | 激活项输出的 `aria-current` 取值(06 · P3-13)。条目各自对应一个页面时用默认的 `page`;条目只切换同一页面内的区域或主题时传 `true` —— 读屏不再报成「当前页面」 |
1445
1718
 
1446
1719
  继承 `HTMLAttributes<HTMLElement>` 的全部原生属性。
1447
1720
 
@@ -1458,11 +1731,11 @@ NavigationMenu 的单个导航项
1458
1731
 
1459
1732
  **用途。** 水平导航基元,条目可展开一个富内容浮层面板。
1460
1733
 
1461
- **何时使用。** 页面区域之间的水平切换,且部分入口需要展开二级内容时使用该组件。激活态是 2px 强调色下划线加 medium 字重,条目高 32px、横向内边距 12px。面板在悬停或聚焦时展开,最小宽 320px,12px 圆角,带浮层阴影。
1734
+ **何时使用。** 页面区域之间的水平切换,且部分入口需要展开二级内容时使用该组件。激活态是 2px 强调色下划线加 medium 字重,条目高 32px、横向内边距 12px。面板在悬停、聚焦或点击时展开,Esc 收起(焦点在面板内时回到条目),最小宽 320px,12px 圆角,带浮层阴影。
1462
1735
 
1463
- **何时改用其他组件。** 应用二级导航一律改用 `ApplicationSecondaryNavigation` —— 那里每个业务标签强制「图标 + 文字」并由类型强制,本基元不施加该约束。同一页内切换内容区改用 `Tabs`,它另有 `count` 徽标与面板槽位。垂直排列的导航面改用 `Sidebar`。编辑器型工作面的命令菜单改用 `Menubar`。
1736
+ **何时改用其他组件。** 应用二级导航一律改用 `ApplicationSecondaryNavigation` —— 那里每个业务标签强制「图标 + 文字」并由类型强制,本基元不施加该约束。同一页内切换内容区、且没有条目需要展开面板时改用 `Tabs`(它另有 `count` 徽标与面板槽位)或 `ToggleGroup`。垂直排列的导航面改用 `Sidebar`。编辑器型工作面的命令菜单改用 `Menubar`。
1464
1737
 
1465
- **组合约定。** 面板从条目左边缘向右展开,组件不做视口碰撞翻转,因此带 `panel` 的条目不得放在导航行的最右端。面板的开合是组件内部状态,没有对应的 prop,调用方不得试图从外部控制。鼠标移出条目槽位即收起面板,与焦点无关,因此 `panel` 内不得放置需要多步操作的表单。`NavigationMenuItem` 没有禁用字段 —— 无权限的入口必须从 `items` 中移除,不得渲染成看似可点的项。受控使用时 `value` 与 `onValueChange` 必须成对提供。组件自身无外边距,与相邻内容的间距由容器负责。
1738
+ **组合约定。** 面板从条目左边缘向右展开,组件不做视口碰撞翻转,因此带 `panel` 的条目不得放在导航行的最右端。面板的开合是组件内部状态,没有对应的 prop,调用方不得试图从外部控制。鼠标移出条目槽位 150ms 后收起面板(其间移入面板即取消),与焦点无关,因此 `panel` 内不得放置需要多步操作的表单。激活项标 `aria-current`,取值由 `current` 决定:条目各自对应一个页面时用默认的 `"page"`;条目只切换同一页面内的区域或主题时必须传 `current="true"`,否则读屏会把它报成「当前页面」。`NavigationMenuItem` 没有禁用字段 —— 无权限的入口必须从 `items` 中移除,不得渲染成看似可点的项。受控使用时 `value` 与 `onValueChange` 必须成对提供。组件自身无外边距,与相邻内容的间距由容器负责。
1466
1739
 
1467
1740
  **禁止 / 使用边界。**
1468
1741
  - 不得用作应用二级导航。
@@ -1470,18 +1743,23 @@ NavigationMenu 的单个导航项
1470
1743
  - 不得把带 `panel` 的条目放在行末。
1471
1744
  - 不得在 `panel` 内放置输入框、多步表单或分页控件。
1472
1745
  - 不得渲染无权限的条目。
1746
+ - 不得在页内切换时沿用默认的 `current`(`"page"`)。
1473
1747
 
1474
1748
  ### Pagination
1475
1749
 
1476
1750
  `import { Pagination } from '@moheng-design/ui'` · 契约 `contracts/foundation/navigation-command/pagination.ts`
1477
1751
 
1478
- 裸分页步进器。
1752
+ 裸分页步进器:首页 · 上一页 · 页码窗口 · 下一页 · 末页。
1479
1753
 
1480
1754
  **数据展示区的列表/表格分页请用 `ListTablePagination`** ——
1481
- 那是 Application Atomic 适配器,额外承载结果总数与每页条数。
1482
- 本组件只在没有那些附加信息时使用。
1755
+ 那是 Application Atomic 适配器,内部渲染本组件,另承载结果总数、每页条数与跳页。
1756
+ 本组件只在没有那些附加信息时单独使用。
1483
1757
 
1484
- 当前页带 `aria-current="page"` 加强调色描边,**不只靠颜色**表达。
1758
+ 外观按 GAP Design kit「分页元素」:每一格 32×32、1px 线条描边、圆角 12、白底,间隔 4;
1759
+ 页码 14/20 medium;四个步进键是 16px 纯图标,可访问名为「首页 / 上一页 / 下一页 / 末页」;
1760
+ 跳空处是同款方块里的省略号字形。
1761
+
1762
+ 当前页带 `aria-current="page"`、强调色描边与主色 6% 底,**不只靠颜色**表达。
1485
1763
 
1486
1764
  **Props**
1487
1765
 
@@ -1493,26 +1771,28 @@ NavigationMenu 的单个导航项
1493
1771
 
1494
1772
  继承 `HTMLAttributes<HTMLElement>` 的全部原生属性。
1495
1773
 
1496
- **用途。** 裸分页步进器,只承担页码窗口与翻页。
1774
+ **用途。** 裸分页步进器,承担「首页 · 上一页 · 页码窗口 · 下一页 · 末页」。
1497
1775
 
1498
- **何时使用。** 仅在确实不需要结果总数与每页条数时使用该组件。页码窗口固定为「首页 + 当前页前后各 1 页 + 末页」,跳空处插省略号,最多 7 个槽位,不可配置。当前页带 `aria-current="page"`、强调色描边与淡强调色底,不只靠颜色表达。按钮高 28px,页码使用等宽数字,翻页时按钮不左右跳动。
1776
+ **何时使用。** 仅在确实不需要结果总数与每页条数时单独使用该组件。页码窗口固定为「首页 + 当前页前后各 1 页 + 末页」,跳空处插省略号,最多 7 个槽位,不可配置。外观按 GAP Design kit「分页元素」:每一格 32×32、1px 线条描边、圆角 12、白底,间隔 4;四个步进键是 16px 纯图标,可访问名为「首页」「上一页」「下一页」「末页」。当前页带 `aria-current="page"`、强调色描边与主色 6% 底,不只靠颜色表达。页码按钮视觉上只显示数字(14/20 medium),可访问名为「第 N 页」;页码使用等宽数字,翻页时按钮不左右跳动。
1499
1777
 
1500
- **何时改用其他组件。** 数据展示区的列表与表格页脚一律改用 `ListTablePagination`,它额外承载结果区间、总数与每页条数选择器。两者是替代关系而非包含关系:`ListTablePagination` 的形态是「上一页 · 当前页/总页数 · 下一页」两键步进,不渲染页码窗口。系统内无限滚动不作为分页的替代方案。
1778
+ **何时改用其他组件。** 数据展示区的列表与表格页脚一律改用 `ListTablePagination`。两者是包含关系:`ListTablePagination` 内部渲染本组件作为页码区,另外承载摘要、每页条数选择器与跳页框(业财平台 round-01 起,兑现 04 · T6 的原裁决)。系统内无限滚动不作为分页的替代方案。
1501
1779
 
1502
- **组合约定。** 调用方必须保证 `1 ≤ page ≤ pageCount`,组件不对越界值做钳制。`pageCount` 为 1 时组件仍渲染两枚禁用的翻页按钮与单个页码,只有一页时调用方应自行不渲染整个组件。分页状态必须跨 Page Mode 与 Business View 切换存活,从详情返回时也必须还原,该状态由调用方 Module 持有 —— 组件不持有任何页码状态。组件自身无外边距,与数据展示区的间距由容器负责。
1780
+ **组合约定。** 调用方必须保证 `1 ≤ page ≤ pageCount`,组件不对越界值做钳制。`pageCount` 为 1 时组件仍渲染四枚禁用的步进键与单个页码,只有一页时调用方应自行不渲染整个组件。分页状态在数据展示区内的规则与 `ListTablePagination` 相同(按业务视图各记一份,搜索、筛选、排序变化时复位到第 1 页,07 · C-13),该状态由调用方 Module 持有 —— 组件不持有任何页码状态。组件自身无外边距,与数据展示区的间距由容器负责。
1503
1781
 
1504
1782
  **禁止 / 使用边界。**
1505
1783
  - 不得在列表或表格的标准页脚使用该组件。
1506
1784
  - 不得把该组件用作步骤指示器、轮播指示器或进度表达。
1507
1785
  - 禁止传入越界的 `page`。
1508
1786
  - 不得依赖该组件表达结果总数或每页条数,它不承载这两项。
1509
- - 不得在同一数据展示区内同时渲染 Pagination 与 `ListTablePagination`。
1787
+ - 不得在同一数据展示区内同时渲染 Pagination 与 `ListTablePagination` —— 后者已经包含前者。
1788
+ - 不得把四个步进键改回文字按钮,也不得去掉首页与末页。
1510
1789
 
1511
1790
  ### Sidebar
1512
1791
 
1513
1792
  `import { Sidebar } from '@moheng-design/ui'` · 契约 `contracts/foundation/navigation-command/sidebar.ts`
1514
1793
 
1515
- Content Canvas 内部的垂直导航面 —— SPLIT 左侧目录、设置导航、模块子导航。
1794
+ Content Canvas 内部的垂直导航面 —— 设置页目录。
1795
+ SPLIT 左栏不用本组件,一律用 `ApplicationSplitListSidebar`(07 · C-15)。
1516
1796
 
1517
1797
  ⚠ **这不是 Shell。** Shell 没有左侧全局栏;工作台侧栏是 `GlobalSidebar`,
1518
1798
  属于 Application Module 层。两者不可互相替代。
@@ -1550,13 +1830,13 @@ Sidebar 的导航分组
1550
1830
  | `label` | `string` | 否 | 分组标题,12/16 label 色。折叠态下不渲染 |
1551
1831
  | `items` | `SidebarItem[]` | 是 | 组内导航项 |
1552
1832
 
1553
- **用途。** Content Canvas 内部的垂直导航面 —— 设置导航、模块子导航。
1833
+ **用途。** Content Canvas 内部的垂直导航面 —— 设置页目录。SPLIT 页面模式的左栏不用本组件,一律用 `ApplicationSplitListSidebar`(07 · C-15)。
1554
1834
 
1555
1835
  **何时使用。** 一个工作面需要按分组罗列 5 项及以上的垂直入口时使用该组件。展开宽默认 240px,折叠宽固定 56px,导航项高 36px,分组标题 12/16。选中态是淡强调色洗加强调色文字加 medium 字重,字重是颜色之外的第二信号。
1556
1836
 
1557
1837
  **何时改用其他组件。** 工作台左侧 72px 图标栏改用 `GlobalSidebar`,它由 `SidebarRailButton` 构成,是另一个组件,两者不可互相替代。SPLIT 页面模式的左栏改用 `ApplicationSplitListSidebar`,它已登记目录搜索、结果数与目录设置三件事。水平方向的导航改用 `NavigationMenu` 或 `Tabs`。
1558
1838
 
1559
- **组合约定。** 该组件不是 Shell —— 应用外层 Shell 是刻意设计的无侧栏四带堆叠,不得因为存在本组件就往 Shell 上加一条全局左栏。组件是 `flex: 0 0 auto` 且高度 100% 的 flex 项,必须置于一个高度确定的横向 flex 容器内。该组件只有受控模式:`value` 与 `onValueChange` 必须成对提供,缺少 `onValueChange` 时点击不产生任何变化。`collapsed` 为 true 时图标是唯一可见内容,因此可能折叠的侧栏中每个 `SidebarItem` 都必须提供 `icon`;`label` 为非字符串时还必须提供 `labelText`,否则折叠态的悬浮提示不可用。折叠态不渲染分组标题与 `badge`,唯一的状态提示不得只放在 `badge` 上。`width` 只作用于展开态,折叠宽固定 56px 不随其变化。`SidebarGroup.label` 用作 React key,应在侧栏内唯一。
1839
+ **组合约定。** 该组件不是 Shell —— 应用外层 Shell 是刻意设计的无侧栏导航带堆叠(基础版两带、集团版三带),不得因为存在本组件就往 Shell 上加一条全局左栏。组件是 `flex: 0 0 auto` 且高度 100% 的 flex 项,必须置于一个高度确定的横向 flex 容器内。该组件只有受控模式:`value` 与 `onValueChange` 必须成对提供,缺少 `onValueChange` 时点击不产生任何变化。`collapsed` 为 true 时图标是唯一可见内容,因此可能折叠的侧栏中每个 `SidebarItem` 都必须提供 `icon`;`label` 为非字符串时还必须提供 `labelText`,否则折叠态条目既无可访问名也无提示。折叠态条目以 `aria-label` 命名,并由内置 `Tooltip` 在悬停与聚焦时向右提示同一名称,调用方不得再包一层 `Tooltip`。有标题的分组输出以标题命名的 `role="group"`。折叠态不渲染分组标题与 `badge`,唯一的状态提示不得只放在 `badge` 上。`width` 只作用于展开态,折叠宽固定 56px 不随其变化。`SidebarGroup.label` 用作 React key,应在侧栏内唯一。
1560
1840
 
1561
1841
  **禁止 / 使用边界。**
1562
1842
  - 不得把该组件当作应用外层 Shell 的全局左栏。
@@ -1579,6 +1859,8 @@ Sidebar 的导航分组
1579
1859
 
1580
1860
  这是页面区域内的控件,不是 Shell 的二级导航(那是 `ApplicationSecondaryNavigation`)。
1581
1861
 
1862
+ 传入的 `aria-label` / `aria-labelledby` 落在 `role="tablist"` 上,不落在根节点。
1863
+
1582
1864
  **Props**
1583
1865
 
1584
1866
  | prop | 类型 | 必填 | 说明 |
@@ -1587,7 +1869,7 @@ Sidebar 的导航分组
1587
1869
  | `value` | `string` | 否 | 受控选中值 |
1588
1870
  | `defaultValue` | `string` | 否 | 非受控初始值。未提供时默认选中 `items[0].value` |
1589
1871
  | `onValueChange` | `(value: string) => void` | 否 | 选中值变化回调 |
1590
- | `children` | `ReactNode` | 否 | 标签面板内容。提供时渲染在标签行下方,带 `--ds-space-3` 上边距 |
1872
+ | `children` | `ReactNode` | 否 | 标签面板内容。提供时渲染在标签行下方,带 `--ds-space-3` 上边距。 根与面板都是列向 flex,面板吃掉根的剩余高度:根在定高父级里拿到高度时 (调用方给根 `flex: 1; min-block-size: 0` 一类的类名),面板内的 `ApplicationDataDisplay` 拿到有界高度、自己滚动。面板的直接子节点各成一个 flex 项 —— 行内混排的文字须包一层块级元素。 渲染面板时,激活标签以 `aria-controls` 指向它,它以 `aria-labelledby` 指回激活标签。 |
1591
1873
 
1592
1874
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `defaultValue` 已被本组件重新定义或移除。
1593
1875
 
@@ -1605,11 +1887,11 @@ Tabs 的单个标签
1605
1887
 
1606
1888
  **用途。** 页面区域内的局部标签页 —— SPLIT 右栏内容标签、详情分节切换。
1607
1889
 
1608
- **何时使用。** 同一块区域内需要在 2 个及以上互斥内容之间切换时使用该组件。标签高 32px、内边距 6/12、文字 14/20,激活态是 2px 强调色下划线加 medium 字重,明确不是 pill 背景。标签行下方有 1px 分隔线,`count` 徽标为 12px 等宽数字。左右方向键在标签之间移动焦点,选中须再按回车或空格。
1890
+ **何时使用。** 同一块区域内需要在 2 个及以上互斥内容之间切换时使用该组件。标签高 32px、内边距 6/12、文字 14/20,激活态是 2px 强调色下划线加 medium 字重,明确不是 pill 背景。标签行下方有 1px 分隔线,`count` 徽标为 12px 等宽数字。标签行只占一个 Tab 停靠点,左右方向键在可用标签之间移动焦点、首尾相接,Home / End 跳到首末项,选中须再按回车或空格;焦点离开后停靠点回到选中标签。
1609
1891
 
1610
- **何时改用其他组件。** Shell 第三带的业务标签改用 `ApplicationSecondaryNavigation`,那里的图标是必填。L3 业务视图标签由 `ApplicationQueryToolbar` 承担,其第一行内部已组合本组件,不得在工具栏之外另起一行 Tabs 表达业务视图。Page Mode Switch 属于 `ApplicationPageHeader`,不得用 Tabs 或 `ToggleGroup` 搭建。密度、对齐这类局部显示选择改用 `ToggleGroup`。带浮层面板的水平导航改用 `NavigationMenu`。
1892
+ **何时改用其他组件。** Shell 应用二级导航带的业务标签改用 `ApplicationSecondaryNavigation`,那里的图标是必填。L3 业务视图标签由 `ApplicationQueryToolbar` 承担,其第一行内部已组合本组件,不得在工具栏之外另起一行 Tabs 表达业务视图。Page Mode Switch 属于 `ApplicationPageHeader`,不得用 Tabs 或 `ToggleGroup` 搭建。密度、对齐这类局部显示选择改用 `ToggleGroup`。带浮层面板的水平导航改用 `NavigationMenu`。
1611
1893
 
1612
- **组合约定。** `children` 原样渲染,组件不做面板切换 —— 调用方必须自行依据当前 `value` 渲染对应内容。面板的 12px 上边距由组件负责,调用方不得再补上边距。`items` 为空数组时整个组件渲染 `null`,不渲染空标签行、不画分隔线、不保留高度,因此调用方不得为「暂无标签」另行渲染占位。未提供 `defaultValue` 时组件默认选中 `items[0].value` 且不检查其禁用状态,`items[0]` 为 `disabled` 时必须显式提供 `defaultValue`。受控使用时 `value` 与 `onValueChange` 必须成对提供。`count` 只接受数字。
1894
+ **组合约定。** `children` 原样渲染,组件不做面板切换 —— 调用方必须自行依据当前 `value` 渲染对应内容。面板的 12px 上边距由组件负责,调用方不得再补上边距。根与面板都是列向 flex,面板吃掉根的剩余高度:要让面板内的 `ApplicationDataDisplay` 拿到有界高度、自己滚动,调用方只需让 Tabs 根在定高父级里拿到高度(给根加 `flex: 1; min-block-size: 0` 的类名),不得再在面板外另造一个 `role="tabpanel"` 容器;面板的直接子节点各成一个 flex 项,行内混排的文字须包一层块级元素。可访问名称以 `aria-label` 或 `aria-labelledby` 传入,组件把它落在 `role="tablist"` 上;渲染面板时激活标签与面板以 `aria-controls` / `aria-labelledby` 互相关联,调用方不必补。`items` 为空数组时整个组件渲染 `null`,不渲染空标签行、不画分隔线、不保留高度,因此调用方不得为「暂无标签」另行渲染占位。未提供 `defaultValue` 时组件默认选中 `items[0].value` 且不检查其禁用状态,`items[0]` 为 `disabled` 时必须显式提供 `defaultValue`。受控使用时 `value` 与 `onValueChange` 必须成对提供。`count` 只接受数字。
1613
1895
 
1614
1896
  **禁止 / 使用边界。**
1615
1897
  - 不得用作 Shell 的二级导航。
@@ -1659,7 +1941,9 @@ Tabs 的单个标签
1659
1941
 
1660
1942
  人员或组织的身份标记 —— 人员选择器、联系人列表、审计轨迹、记录负责人。
1661
1943
 
1662
- 无图片时回退为文字缩写:**中文名取首字,拉丁名取首字母缩写**。
1944
+ 无图片时回退为文字缩写:**中文名取末字,拉丁名取首字母缩写**。
1945
+ 取末字(07 · C-8):「张伟」→「伟」,占位符「成员 A」→「A」—— 取首字时同姓者与
1946
+ 同一占位符前缀下的头像缩写全相同,无从区分。
1663
1947
 
1664
1948
  ⚠ **绝不用 Emoji 或装饰性字形代替头像。**
1665
1949
 
@@ -1667,7 +1951,7 @@ Tabs 的单个标签
1667
1951
 
1668
1952
  | prop | 类型 | 必填 | 说明 |
1669
1953
  |---|---|:---:|---|
1670
- | `name` | `string` | 否 | 姓名或组织名。用于生成回退缩写,同时作为悬浮提示 |
1954
+ | `name` | `string` | 否 | 姓名或组织名。用于生成回退缩写,同时作为头像图片的替代文本(不渲染原生悬浮提示) |
1671
1955
  | `src` | `string` | 否 | 真实头像地址。存在时优先于文字缩写 |
1672
1956
  | `size` | `'sm' \| 'default' \| 'lg' \| number` | 否 | 尺寸。已登记档位为 24 / 32 / 40px。 也接受任意数字,但**应优先使用档位** —— 任意值会绕开标尺。 |
1673
1957
  | `shape` | `'circle' \| 'rounded'` | 否 | 形状。人员用 `circle`,组织用 `rounded` |
@@ -1676,7 +1960,7 @@ Tabs 的单个标签
1676
1960
 
1677
1961
  **用途。** 人员或组织的身份标记,承载头像图片或其文字缩写回退。
1678
1962
 
1679
- **何时使用。** 人员选择器、联系人列表、审计轨迹、记录负责人处必须使用该组件表达身份。已登记档位为 24 / 32 / 40px,与控件高度标尺同值,因此该组件与同行的按钮、输入框天然等高。无图片时该组件回退为文字缩写:中文名取首字,拉丁名按空格分词取各词首字母(最多两个)。人员用 `circle`,组织用 `rounded`。
1963
+ **何时使用。** 人员选择器、联系人列表、审计轨迹、记录负责人处必须使用该组件表达身份。已登记档位为 24 / 32 / 40px,与控件高度标尺同值,因此该组件与同行的按钮、输入框天然等高。无图片时该组件回退为文字缩写:含中文的名字取末字(「张伟」→「伟」,占位符「成员 A」→「A」),拉丁名按空格分词取各词首字母(最多两个)。取末字而非首字,是因为同姓者与同一占位符前缀下的头像取首字时缩写全相同。人员用 `circle`,组织用 `rounded`。
1680
1964
 
1681
1965
  **何时改用其他组件。**
1682
1966
  - 应用身份与品牌区不属于本组件,由 `ApplicationPrimaryNavigation` 的 logo 瓦片承担,该瓦片是 8% 强调色混入表面色,绝不是饱和强调色块。
@@ -1684,7 +1968,7 @@ Tabs 的单个标签
1684
1968
  - 纯内容字形改用 `Icon`,字形必须取自已登记清单。
1685
1969
  - 身份加标题加描述构成的整行改用 `Item`,本组件放进它的 `leading` 槽位。
1686
1970
 
1687
- **组合约定。** 传 `src` 时必须同时传 `name` —— `name` 同时充当图片替代文本与悬浮提示,缺失即该头像对读屏软件不可读。该组件已自带 `title`,调用方不得再包一层 `Tooltip`(`Tooltip` 的职责是为纯图标控件命名)。外边距由宿主槽位负责:`Item` 的 `leading`、`Message` 的 `avatar`、三栏工作台的成员行;本组件自身不带 margin,也不参与换行。`ContactsCollaborationWorkspace` 与 `PeoplePickerDialog` 的成员行已内置 24px 头像,调用方不再另行渲染。`size` 传任意数字会绕开标尺,仅当确实无法落到 24 / 32 / 40 时使用。同一列表内 `shape` 必须统一。
1971
+ **组合约定。** 传 `src` 时必须同时传 `name` —— `name` 充当图片替代文本,缺失即该头像对读屏软件不可读。该组件不渲染原生 `title`(否则放进 `HoverCard` 触发区时会叠出两层提示),调用方也不得再包一层 `Tooltip`(`Tooltip` 的职责是为纯图标控件命名)。头像紧挨着可见姓名时应传 `aria-hidden`,免得读屏把缩写或姓名多读一遍。外边距由宿主槽位负责:`Item` 的 `leading`、`Message` 的 `avatar`、三栏工作台的成员行;本组件自身不带 margin,也不参与换行。`ContactsCollaborationWorkspace` 与 `PeoplePickerDialog` 的成员行已内置 24px 头像,调用方不再另行渲染。`size` 传任意数字会绕开标尺,仅当确实无法落到 24 / 32 / 40 时使用。同一列表内 `shape` 必须统一。
1688
1972
 
1689
1973
  **禁止 / 使用边界。**
1690
1974
  - 不得用 Emoji、系统字体符号或装饰性字形代替头像。
@@ -1698,40 +1982,42 @@ Tabs 的单个标签
1698
1982
 
1699
1983
  紧凑的状态或分类标签 —— 行、卡片、指标、详情头。
1700
1984
 
1701
- 20px 高,4px 圆角,12/16 字号。
1985
+ 24px 高,20px 圆角(胶囊),左右 10 上下 4,12/16 字号(GAP Design kit「标签」)。
1986
+ soft 档底色为 tone 语义色 10% 透明(neutral 为文字色 6%),前景取 tone 语义色。
1702
1987
 
1703
1988
  ⚠ **状态色只来自功能状态色板。** 图表分类色(20 色)绝不能用来表达状态。
1704
1989
 
1705
- 一个 tone 在整个产品内只能有一个含义 —— 不要在 A 页面用 warning 表示「待整改」、
1706
- 在 B 页面用它表示「即将到期」。
1990
+ 一个 tone 在同一维度内只能有一个含义 —— 不要在 A 页面用 warning 表示「待整改」、
1991
+ 在 B 页面用它表示「即将到期」。同屏有两个状态维度(处理状态与风险等级)时,
1992
+ 用 `variant` 区分维度:一个维度 `soft`、另一个 `outline`,tone 可以跨维度复用(07 · C-9)。
1707
1993
 
1708
1994
  **Props**
1709
1995
 
1710
1996
  | prop | 类型 | 必填 | 说明 |
1711
1997
  |---|---|:---:|---|
1712
- | `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'info'` | 否 | 语义色调。每个 tone 在全产品内含义唯一 |
1998
+ | `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'info'` | 否 | 语义色调。每个 tone 在同一维度内含义唯一;不同维度用 `variant` 区分 |
1713
1999
  | `variant` | `'soft' \| 'outline'` | 否 | 视觉变体。`soft` 为淡色底,`outline` 为透明底加描边 |
1714
2000
  | `children` | `ReactNode` | 否 | 徽标文字。2–4 字名词短语,不承载交互 —— 需要点击请改用 `Button` |
1715
2001
 
1716
2002
  继承 `HTMLAttributes<HTMLSpanElement>` 的全部原生属性。
1717
2003
 
1718
- **用途。** 紧凑的状态或分类标签,20px 高、4px 圆角、12/16 字号。
2004
+ **用途。** 紧凑的状态或分类标签,24px 高、20px 圆角(胶囊)、左右 10 上下 4 内边距、12/16 字号。
1719
2005
 
1720
- **何时使用。** 列表行、卡片、指标、详情头需要一个短状态词或分类词时,必须使用该组件。`RecordListItem` 与 `WorkspacePerson` 的 `status` 槽位、`Card` 的 `extra` 槽位、`Item` 的 `trailing` 槽位登记的默认内容即为本组件。`tone` 的六档全部来自功能状态色板,一个 tone 在整个产品内只能有一个含义。
2006
+ **何时使用。** 列表行、卡片、指标、详情头需要一个短状态词或分类词时,必须使用该组件。`RecordListItem` 与 `WorkspacePerson` 的 `status` 槽位、`Card` 的 `extra` 槽位、`Item` 的 `trailing` 槽位登记的默认内容即为本组件。`tone` 的六档全部来自功能状态色板,一个 tone 在同一维度内只能有一个含义。
1721
2007
 
1722
2008
  **何时改用其他组件。**
1723
2009
  - 指标区里的「功能状态 + 计数」改用 `ApplicationMetricStatus`,该卡由圆点、文字、颜色三者共同承载状态。
1724
- - 已生效的筛选条件改用 `ApplicationQueryToolbar` 的 `appliedTags`,它自带逐项移除与重置全部。
2010
+ - 已生效的筛选条件改用 `ApplicationQueryToolbar` 的 `appliedTags`,它自带逐项移除与「清空」。
1725
2011
  - 需要说明成因并给出重试出路的整段提示改用 `Alert`。
1726
2012
  - 一级导航上的未读提示改用 `ApplicationPrimaryNavigation` 的 `actionBadges` 圆点;消息条目的未读态改用 `Message` 的 `unread`。
1727
- - 键盘按键提示改用 `Kbd`,二者同为 20px 高,语义不同,不得互换。
2013
+ - 键盘按键提示改用 `Kbd`,二者语义不同,不得互换。
1728
2014
 
1729
- **组合约定。** `tone` 与业务状态的对应关系必须在应用侧集中定义一次,禁止逐页面各写一份。外边距由宿主槽位负责,本组件自身不带 margin 且不换行,内容超长时由宿主决定截断。`variant="outline"` 的边框取 tone 的语义色,而 `warning` 的前景为保证对比度取中性色,这是已裁决的刻意不同构(04 · D3),应用侧不得把前景「修正」回同色系。`children` 必须是 2–4 字裸名词短语。
2015
+ **组合约定。** `tone` 与业务状态的对应关系必须在应用侧集中定义一次,禁止逐页面各写一份。tone 只在同一维度内含义唯一:同屏出现两个状态维度(如处理状态与风险等级)时,用 `variant` 区分维度 —— 一个维度用 `soft`(淡色实底),另一个用 `outline`(描边),两个维度可以各用到同一个 tone(07 · C-9);同一维度内的不同取值不得共用 tone。外边距由宿主槽位负责,本组件自身不带 margin 且不换行,内容超长时由宿主决定截断。`soft` 档的底色一律是 tone 语义色的 10% 透明(`neutral` 为文字色 6%),前景与描边取 tone 的语义色,`warning` 也不例外(GAP Design kit;此前 `warning` 前景取中性灰,已随警示色调深为 #ff7b00 改回同色系)。`children` 必须是 2–4 字裸名词短语。
1730
2016
 
1731
2017
  **禁止 / 使用边界。**
1732
2018
  - 不得用图表分类色表达状态 —— 分类色只编码分类。
1733
2019
  - 禁止给本组件绑定点击或做成可移除标签。
1734
- - 不得在不同页面给同一 tone 指派不同含义。
2020
+ - 不得在不同页面给同一维度的同一 tone 指派不同含义。
1735
2021
  - 不得用本组件承载多行文字、长句或数值单位说明。
1736
2022
 
1737
2023
  ### Bubble
@@ -1780,13 +2066,14 @@ Tabs 的单个标签
1780
2066
  标准页面承载面 —— CardList 磁贴、工作台面板、图表容器、表单分节。
1781
2067
 
1782
2068
  已登记契约:**只有两档密度** —— `default`(16px 节奏)与 `sm`(12px),
1783
- 16px 圆角,1px 边框,**默认无装饰阴影**。不要给它加阴影。
2069
+ `default` 的节奏随视口密度档收为 16 / 12 / 10(07 · C-17),`sm` 在 Compact 档同取 10;
2070
+ 20px 圆角(GAP Design kit「圆角20」),1px 边框,**默认无装饰阴影**。不要给它加阴影。
1784
2071
 
1785
2072
  **Props**
1786
2073
 
1787
2074
  | prop | 类型 | 必填 | 说明 |
1788
2075
  |---|---|:---:|---|
1789
- | `density` | `'default' \| 'sm'` | 否 | 密度。`default` 内边距与间隙均 16px,`sm` 均 12px。没有第三档 |
2076
+ | `density` | `'default' \| 'sm'` | 否 | 密度。`default` 内边距与间隙均 16px(Condensed 视口 12、Compact 视口 10), `sm` 均 12px(Compact 视口 10)。没有第三档 —— 视口档不是 prop,由 `@media` 自动生效 |
1790
2077
  | `title` | `ReactNode` | 否 | 卡片标题。16/24 medium 字重,超长省略 |
1791
2078
  | `extra` | `ReactNode` | 否 | 标题行尾部槽位:一个状态 `Badge` 或一个安静的动作 |
1792
2079
  | `footer` | `ReactNode` | 否 | 页脚区。渲染时自带上边框与一段上内边距 |
@@ -1806,11 +2093,11 @@ Tabs 的单个标签
1806
2093
  - 承载的是可折叠的分节 —— 改用 `Collapsible`;多个互斥折叠项改用 `Accordion`。
1807
2094
  - 承载的是一行可扫视的记录 —— 改用 `Item` 或 `ApplicationRecordList`。
1808
2095
 
1809
- **组合约定。** 本组件不持有外边距,卡片之间的间距(Standard 12px、Condensed 10px、Compact 8px)由父级栅格或 `ApplicationPageLayoutContainer` 负责。`title` 与 `extra` 同处标题行,`extra` 只放一个状态 `Badge` 或一个安静的动作。`footer` 自带上边框与一段上内边距,不需要再在它上面放 `Separator`。`interactive` 只是把光标与边框反馈打开,跳转行为仍由调用方自己挂在卡片上 —— 因此 `interactive` 为 true 时必须同时给出真实的跳转处理,只设 `interactive` 而不跳转会得到一个骗人的指针。`interactive` 为 true 时卡内不得再放独立的可点控件,除非该控件自行阻止事件冒泡。
2096
+ **组合约定。** 本组件不持有外边距,卡片之间的间距(Standard 12px、Condensed 10px、Compact 8px)由父级栅格或 `ApplicationPageLayoutContainer` 负责。`title` 与 `extra` 同处标题行,`extra` 只放一个状态 `Badge` 或一个安静的动作。内边距与内部间隙随视口密度档自动收紧:`default` 为 Standard 16px、Condensed 12px、Compact 10px,`sm` 为 12px、Compact 10px,由 token 层的 `@media` 驱动,调用方不得另写断点改卡片内边距。`footer` 自带上边框与一段上内边距,不需要再在它上面放 `Separator`。`interactive` 只是把光标与边框反馈打开,跳转行为仍由调用方自己挂在卡片上 —— 因此 `interactive` 为 true 时必须同时给出真实的跳转处理(`onClick`),只设 `interactive` 而不跳转会得到一个骗人的指针。`interactive` 且给了 `onClick` 时组件自带键盘入口:标题读作按钮、进 Tab 序列,Enter / 空格触发同一个 `onClick`,焦点环画在整张卡上;无标题时整卡可聚焦。调用方不得再自行补 `tabIndex` / `role` / `onKeyDown` —— 显式传入 `tabIndex` 或 `role` 即视为接管,组件不再加自己那一份。标题行最小高度 32px,有无 `extra` 都一样高。`interactive` 为 true 时卡内不得再放独立的可点控件,除非该控件自行阻止事件冒泡。
1810
2097
 
1811
2098
  **禁止 / 使用边界。**
1812
- - 不得给卡片添加阴影 —— 已登记契约为 16px 圆角、1px 边框、无默认装饰阴影,边框负责分隔。
1813
- - 禁止发明第三档密度:只有 `default`(16px 节奏)与 `sm`(12px)两档。
2099
+ - 不得给卡片添加阴影 —— 已登记契约为 20px 圆角、1px 边框、无默认装饰阴影,边框负责分隔。
2100
+ - 禁止发明第三档密度:只有 `default`(16px 节奏)与 `sm`(12px)两档,随视口收紧的是这两档的取值,不是新的档。
1814
2101
  - 不得在只读的指标卡语义上设置 `interactive` —— 指标卡必须保持 `cursor: default`,整卡绝不成为导航入口。
1815
2102
  - 不得在 Card 外面再包一层自带 padding 的容器,那会与页面内容根的内边距叠成双重外边距。
1816
2103
 
@@ -1848,7 +2135,7 @@ Tabs 的单个标签
1848
2135
  - 只是一条需要横向滚动的标签条或筛选条 —— 改用 `ScrollArea` 并设 `horizontal`。
1849
2136
  - 内容是消息流 —— 改用 `MessageScroller` 配 `Bubble` 或 `Message`。
1850
2137
 
1851
- **组合约定。** `slides` 的每一项占满一页宽度,各项应当结构同构、高度一致,否则翻页会带来容器高度跳动。`index` 与 `defaultIndex` 二选一:给了 `index` 即进入受控模式,此时必须同时提供 `onIndexChange`,否则页索引永远停在初始值。本组件不持有外边距,与相邻区块的间隙由父级负责。左右导航按钮与页点绝对定位在内容之上,因此 `slides` 内容的四角区域不应放置必须可点的元素。页点带 `aria-hidden`,页序信息不由它传达。
2138
+ **组合约定。** `slides` 的每一项占满一页宽度;各页高度由本组件取最高的一页统一撑开,翻页时容器高度不跳,调用方不必让各页等高,也不必为此把正文截成固定行数。`index` 与 `defaultIndex` 二选一:给了 `index` 即进入受控模式,此时必须同时提供 `onIndexChange`,否则页索引永远停在初始值。本组件不持有外边距,与相邻区块的间隙由父级负责。左右导航按钮与页点绝对定位在内容之上,因此 `slides` 内容的四角区域不应放置必须可点的元素。页点带 `aria-hidden`,页序信息由每页的名称「第 N 页,共 M 页」传达。根是 `aria-roledescription="carousel"` 的 `region`,名称应以 `aria-label` 或 `aria-labelledby` 传入,缺省为「轮播」。焦点在轮播内时 ← / → 翻页(文本框内除外),不在当前页的各页不可聚焦。
1852
2139
 
1853
2140
  **禁止 / 使用边界。**
1854
2141
  - 禁止用定时器驱动 `onIndexChange` 模拟自动播放 —— 系统动效只表达状态变化,无入场编排与自动轮转。
@@ -1862,8 +2149,10 @@ Tabs 的单个标签
1862
2149
 
1863
2150
  图表基元 —— ANALYSIS 分析页、指标卡、报表摘要。
1864
2151
 
1865
- 系列配色按顺序取自共享的 20 色分类色板
2152
+ 系列配色取自共享的 20 色分类色板
1866
2153
  (`--application-categorical-01…20`,`hsl(H, 24%, 53%)`,H 每 18° 一步)。
2154
+ 按系列数跳步取色:共 n 条系列时,从 01 号色起每隔 ⌊20/n⌋ 号取一色,使相邻系列的
2155
+ 色相拉开(2 条差 180°、3 条差 108°;11 条起才逐号取)。首条系列恒为 01 号色。
1867
2156
  同亮度设计使整组图表读起来是一家人。
1868
2157
 
1869
2158
  ⚠ **分类色只编码分类,绝不能替代功能状态色。**
@@ -1872,16 +2161,20 @@ Tabs 的单个标签
1872
2161
  ⚠ 当图表是当前的 Data Presentation 时,
1873
2162
  其设置按钮**必须**写作「图表设置」,不得写成通用的「视图设置」。
1874
2163
 
2164
+ 根节点渲染为 `role="figure"`,可访问名称由调用方以 `aria-label`(或
2165
+ `aria-labelledby`)给出,落在该 figure 上;绘图 svg 是 `aria-hidden` 的,
2166
+ 标签行与图例文字对读屏器保持可读。
2167
+
1875
2168
  **Props**
1876
2169
 
1877
2170
  | prop | 类型 | 必填 | 说明 |
1878
2171
  |---|---|:---:|---|
1879
- | `type` | `'line' \| 'area' \| 'bar'` | 否 | 图表类型 |
1880
- | `series` | `ChartSeries[]` | 是 | 数据系列集合。配色按数组顺序分配 |
1881
- | `labels` | `string[]` | 否 | X 轴标签。见 D6 —— 当前实现按均分排布,与数据点不对齐 |
1882
- | `height` | `number` | 否 | 绘图区高度,单位 px |
1883
- | `showLegend` | `boolean` | 否 | 显示图例 |
1884
- | `showGrid` | `boolean` | 否 | 显示水平网格线 |
2172
+ | `type` | `'line' \| 'area' \| 'bar'` | 否 | 图表类型。默认 `'line'` |
2173
+ | `series` | `ChartSeries[]` | 是 | 数据系列集合。配色按数组顺序与系列总数分配(跳步规则见组件说明) |
2174
+ | `labels` | `string[]` | 否 | X 轴标签。见 D6 —— 折线 / 面积图按均分排布,与数据点不对齐; 柱状图按等宽列居中,标签数等于类目数时落在各柱组中心。 标签不折行,放不下时以省略号截断,完整文字见悬停提示 |
2175
+ | `height` | `number` | 否 | 绘图区高度,单位 px。默认 200 |
2176
+ | `showLegend` | `boolean` | 否 | 显示图例。默认 `true` |
2177
+ | `showGrid` | `boolean` | 否 | 显示水平网格线。默认 `true` |
1885
2178
 
1886
2179
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
1887
2180
 
@@ -1896,7 +2189,7 @@ Chart 的单条数据系列
1896
2189
 
1897
2190
  **用途。** 折线、面积、柱状三型的示意图基元,用于读趋势形状。
1898
2191
 
1899
- **何时使用。** ANALYSIS 分析页、报表摘要,以及关注走势形状而非精确读数的位置,应使用该组件。系列配色按 `series` 的数组顺序取自共享的 20 色分类色板(`hsl(H, 24%, 53%)`,H 每 18 度一步),同亮度设计使整组图表读起来是一家人。该组件是示意图基元,不是精确图表。
2192
+ **何时使用。** ANALYSIS 分析页、报表摘要,以及关注走势形状而非精确读数的位置,应使用该组件。系列配色取自共享的 20 色分类色板(`hsl(H, 24%, 53%)`,H 每 18 度一步),按系列数跳步取色:共 n 条系列时从 01 号色起每隔 ⌊20/n⌋ 号取一色,2 条相差 180 度、3 条相差 108 度,11 条起才逐号取。同亮度设计使整组图表读起来是一家人。该组件是示意图基元,不是精确图表。
1900
2193
 
1901
2194
  **何时改用其他组件。**
1902
2195
  - 指标卡内的迷你走势改用 `ApplicationMetricChart`。二者是两个组件:本组件是 Foundation 绘图基元,后者是 Application Module 的只读指标卡,自带卡片壳、指标名与主数值,不得互换。
@@ -1904,11 +2197,11 @@ Chart 的单条数据系列
1904
2197
  - 需要逐值读数的明细改用 `Table`。
1905
2198
  - 需要坐标轴刻度、交互取值、精确对齐的真实图表时,系统内无对应组件,必须按 02 §9 规则 9 记为规范缺口上报,不得把本基元调准来顶替。
1906
2199
 
1907
- **组合约定。** `series` 必填,各系列的 `data` 长度应一致;配色按数组顺序分配,因此跨页面比较同一组数据时系列顺序必须固定,否则同一业务口径会换色。该组件不渲染标题,可访问名称由调用方在根节点以 `aria-label` 给出。作为 Canvas 的 Data Presentation 使用时,图表由 `ApplicationDataDisplay` 承载,其呈现设置按钮属于 `ApplicationQueryToolbar` 且文案必须写作「图表设置」,通用的「视图设置」被明令禁止。Loading / Empty / Error / No Permission / Not Found 五种状态各有各的槽位,全部由 `ApplicationDataDisplay` 承担,本组件自身不渲染任何状态节点。外边距由宿主区域负责;`height` 只控制绘图区,标签行与图例在其下方另占高度。
2200
+ **组合约定。** `series` 必填,各系列的 `data` 长度应一致;配色由数组顺序与系列总数共同决定,因此跨页面比较同一组数据时系列顺序与条数都必须固定,否则同一业务口径会换色。该组件不渲染标题,根节点是 `role="figure"`,可访问名称由调用方在根节点以 `aria-label`(或 `aria-labelledby`)给出;绘图 svg 对读屏器隐藏,标签行与图例文字保持可读,因此名称应概括图表主题(如「近 6 月收入走势」),不必复述图例。作为 Canvas 的 Data Presentation 使用时,图表由 `ApplicationDataDisplay` 承载,其呈现设置按钮属于 `ApplicationQueryToolbar` 且文案必须写作「图表设置」,通用的「视图设置」被明令禁止。Loading / Empty / Error / No Permission / Not Found 五种状态各有各的槽位,全部由 `ApplicationDataDisplay` 承担,本组件自身不渲染任何状态节点。外边距由宿主区域负责;`height` 只控制绘图区,标签行与图例在其下方另占高度。
1908
2201
 
1909
2202
  **禁止 / 使用边界。**
1910
2203
  - 不得用分类色表达状态 —— 红色系列不等于危险,状态一律交给 `Badge` 或 `ApplicationMetricStatus`。
1911
- - 不得把 `labels` 当作与数据点一一对齐的刻度:标签沿轴均分排布,这是已裁决接受的限制(04 · D6)。
2204
+ - 不得把 `labels` 当作与数据点一一对齐的刻度:折线与面积图的标签沿轴均分排布,这是已裁决接受的限制(04 · D6);柱状图的标签按等宽列居中,只在标签数等于类目数时落在柱组中心。标签不折行,放不下时以省略号截断。
1912
2205
  - 禁止依赖柱宽的视觉比例做判断,非等比拉伸会使柱宽随容器宽高比变形。
1913
2206
  - 不得给图表添加图例之外的装饰、渐变或阴影。
1914
2207
 
@@ -1944,13 +2237,13 @@ Chart 的单条数据系列
1944
2237
  **何时改用其他组件。**
1945
2238
  - 状态是 Loading —— 改用 `Skeleton`,且骨架必须贴近最终结构;短时的原地等待改用 `Spinner`。
1946
2239
  - 状态是 Error、No Permission 或 Not Found —— 仍可用本组件渲染节点,但文案必须各自独立;`ApplicationDataDisplay` 为这四种状态各留了独立槽位,不得共用同一个节点。
1947
- - 状态是 Partial Failure —— 改用 `Alert`,它就地提示、提供重试,且不阻断主任务。
2240
+ - 状态是 Partial Failure —— 改用 `Alert`,它就地提示、提供重试,且不阻断主任务;数据区里经 `ApplicationDataDisplay` 的 `notice` 槽位放置。
1948
2241
  - 需要的是不可逆动作的阻塞确认 —— 改用 `AlertDialog`。
1949
2242
 
1950
2243
  **组合约定。** `title` 没有默认值,调用方必须自己写出这一句 —— 组件刻意不提供泛化兜底。本组件自带内边距并居中排布,父容器不得再为它补内边距;说明文字限宽 320px,超出部分自动换行。`icon` 应传 `Icon` 组件并取已登记尺寸档,以弱化前景色显示。`action` 只在调用方确有权限创建缺失之物时提供,且按钮文案是 2–4 字裸名词短语(`新建`、`重置`)。用作 `Table` 的 `empty` 或 `ApplicationDataDisplay` 的 `empty` 槽位时,应设 `compact`。
1951
2244
 
1952
2245
  **禁止 / 使用边界。**
1953
- - 禁止让 Empty 与 Error、No Permission、Not Found 共用同一句文案 ——「当前口径下无数据」「你没有权限」「未找到该记录」「请求失败」是四句不同的话。
2246
+ - 禁止让 Empty 与 Error、No Permission、Not Found 共用同一句文案 ——「当前口径下无数据」「无权查看本模块」「未找到该记录」「请求失败」是四句不同的话。
1954
2247
  - 不得写「暂无数据」这类不带口径的泛化措辞。
1955
2248
  - 不得在数据仍在加载时渲染本组件,Loading 有它自己的节点。
1956
2249
  - 禁止在空态中出现 Emoji、插画或装饰图形。
@@ -2032,7 +2325,7 @@ Chart 的单条数据系列
2032
2325
 
2033
2326
  **禁止 / 使用边界。**
2034
2327
  - 不得用本组件承载状态、计数、标签等非按键内容。
2035
- - 禁止在本组件上绑定点击 —— 它是提示,真实触发一律交给 `Button`。
2328
+ - 禁止在本组件上绑定点击 —— 它是提示,真实触发一律交给 `SystemButton`。
2036
2329
  - 不得在其中写「点击」「请按」一类引导语,按键名裸用。
2037
2330
  - 不得为本组件另行指定字族,等宽字族已由组件固定。
2038
2331
 
@@ -2068,7 +2361,7 @@ Chart 的单条数据系列
2068
2361
  - 业务记录行改用 `ApplicationRecordList`;表格行改用 `Table`。
2069
2362
  - 需要说明成因并提供重试出路的整段提示改用 `Alert`。
2070
2363
 
2071
- **组合约定。** `avatar` 槽位应传 `Avatar`。一组本组件作为 `ApplicationGlobalActionPanel` 的 `children` 传入,该面板是消息、待办、运行总览、风险预警四个全局动作共享的同一个面板,绝不为每个动作单独造一个弹层。行内边距由本组件自身承担,条目之间不得再加外边距,间距由容器的排列负责。`unread` 为 true 时淡色底与圆点必须同时出现,不得只保留其一。`author` 为 14/20,`time` 为 12/16,二者按基线对齐,因此传入内容应是短文本,不得塞入块级结构。无条目时的空态由 `ApplicationGlobalActionPanel` 的 `emptyState` 承担,应传 `Empty`,其文案须区别于无权限与加载失败。
2364
+ **组合约定。** `avatar` 槽位应传 `Avatar`。一组本组件作为 `ApplicationGlobalActionPanel` 的 `children` 传入,该面板是消息、待办、总览、风险预警四个全局动作共享的同一个面板,绝不为每个动作单独造一个弹层。行内边距由本组件自身承担,条目之间不得再加外边距,间距由容器的排列负责。`unread` 为 true 时淡色底与圆点必须同时出现,不得只保留其一。`author` 为 14/20,`time` 为 12/16,二者按基线对齐,因此传入内容应是短文本,不得塞入块级结构。整条可点开时直接给 `onClick`:组件随之给出指针与 hover 反馈,读作按钮、进 Tab 序列,Enter / 空格触发同一回调,调用方不得再自行补键盘处理。无条目时的空态由 `ApplicationGlobalActionPanel` 的 `emptyState` 承担,应传 `Empty`,其文案须区别于无权限与加载失败。
2072
2365
 
2073
2366
  **禁止 / 使用边界。**
2074
2367
  - 不得把本组件当作会话气泡使用。
@@ -2082,8 +2375,8 @@ Chart 的单条数据系列
2082
2375
 
2083
2376
  消息流的滚动容器。
2084
2377
 
2085
- ⚠ 这是一个**有界的、正交的**滚动区域,是 Content Canvas 单一垂直滚动权的
2086
- 合法局部例外。**必须给显式高度** —— 不得在 Content Canvas 内堆叠无界的
2378
+ ⚠ 这是一个**有界的、正交的**滚动区域,是页面级纵向滚动持有者(按页型归属,06 · D-4)
2379
+ 之外的合法局部例外。**必须给显式高度** —— 不得在 Content Canvas 内堆叠无界的
2087
2380
  垂直滚动容器。
2088
2381
 
2089
2382
  **Props**
@@ -2091,21 +2384,21 @@ Chart 的单条数据系列
2091
2384
  | prop | 类型 | 必填 | 说明 |
2092
2385
  |---|---|:---:|---|
2093
2386
  | `height` | `number \| string` | 否 | 容器高度。数字按 px。必须显式给出,否则失去「有界」前提 |
2094
- | `stickToBottom` | `boolean` | 否 | 新内容到达时自动滚到底部。 见 D7 —— 当前实现无条件拉到底,用户翻阅历史时会被打断。 |
2387
+ | `stickToBottom` | `boolean` | 否 | 新内容到达时自动滚到底部 —— 仅当用户此前已贴近底部(48px 阈值内)时生效, 翻阅历史时不打断(D7 已在阶段 4 修正)。 |
2095
2388
  | `children` | `ReactNode` | 否 | 消息流内容。通常是一串 `Bubble`(会话)或 `Message`(活动流) |
2096
2389
 
2097
2390
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
2098
2391
 
2099
2392
  **用途。** 消息流的有界滚动容器,并按条件贴底。
2100
2393
 
2101
- **何时使用。** 需要在 Content Canvas 内部开一块有界的、正交的垂直滚动区域时使用该组件 —— 消息面板、评论流、办理讨论。这是 Content Canvas 单一垂直滚动权的合法局部例外,前提是高度有界。
2394
+ **何时使用。** 需要在 Content Canvas 内部开一块有界的、正交的垂直滚动区域时使用该组件 —— 消息面板、评论流、办理讨论。这是页面级纵向滚动持有者(结果集页面为 DataDisplay 主体,其余为 Content Canvas)之外的合法局部例外,前提是高度有界。
2102
2395
 
2103
2396
  **何时改用其他组件。**
2104
2397
  - 长筛选列表、宽表格、必须单行的标签条等通用溢出改用 `ScrollArea`,单个实例只承担一个滚动方向。
2105
- - 页面级垂直滚动不需要组件,Content Canvas 本身是唯一的主垂直滚动权持有者。
2398
+ - 页面级垂直滚动不需要组件:结果集页面由 `ApplicationDataDisplay` 主体滚动,其余页面由 Content Canvas 滚动(06 · D-4)。
2106
2399
  - 靠翻页而非滚动浏览的长列表改用 `ApplicationDataDisplay` 配 `ListTablePagination`。
2107
2400
 
2108
- **组合约定。** `height` 必须显式给出(数字按 px),否则失去「有界」前提;内置的 320px 只是兜底默认值,不是可依赖的版式。`children` 是一组 `Bubble` 或一组 `Message`,条目间距由本容器承担,条目自身不得再加外边距。`stickToBottom` 仅在用户当前已贴近底部(48px 阈值内)时生效(04 · D7),业务侧不得另写「新消息到达即拉到底」的逻辑把它覆盖回去。该组件持有交互状态并带 `"use client"`,在 Server Component 中只能作为子树引入。滚动监听(加载更多历史)挂在透传的 `onScroll` 上,不得另行注册事件监听器。
2401
+ **组合约定。** `height` 必须显式给出(数字按 px),否则失去「有界」前提;内置的 320px 只是兜底默认值,不是可依赖的版式。`children` 是一组 `Bubble` 或一组 `Message`,条目间距由本容器承担,条目自身不得再加外边距。`stickToBottom` 仅在用户当前已贴近底部(48px 阈值内)时生效(04 · D7),业务侧不得另写「新消息到达即拉到底」的逻辑把它覆盖回去。根节点是 `role="log"`,新增的条目由读屏以 polite 方式播报;静默加载历史时可传 `aria-live="off"` 覆盖。该组件持有交互状态并带 `"use client"`,在 Server Component 中只能作为子树引入。滚动监听(加载更多历史)挂在透传的 `onScroll` 上,不得另行注册事件监听器。
2109
2402
 
2110
2403
  **禁止 / 使用边界。**
2111
2404
  - 不得省略高度,也不得把它挂进本身高度不定的父容器再靠百分比撑开。
@@ -2132,7 +2425,7 @@ Chart 的单条数据系列
2132
2425
  | `tone` | `'accent' \| 'success' \| 'warning' \| 'danger'` | 否 | 语义色调。默认强调色;用状态色时须与该状态的含义一致 |
2133
2426
  | `showValue` | `boolean` | 否 | 在右上角显示整数百分比,等宽数字 |
2134
2427
  | `height` | `number` | 否 | 轨道高度,单位 px |
2135
- | `label` | `ReactNode` | 否 | 轨道上方的说明文字,12/16 label 色 |
2428
+ | `label` | `ReactNode` | 否 | 轨道上方的说明文字,12/16 label 色。同时是 progressbar 的可访问名称 (以 `aria-labelledby` 关联)。不给 `label` 时应传 `aria-label`, 它同样落在 progressbar 上而不是根节点 |
2136
2429
 
2137
2430
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
2138
2431
 
@@ -2146,7 +2439,7 @@ Chart 的单条数据系列
2146
2439
  - 可拖拽取值的输入改用 `Slider`,原生 `<input type="range">` 由 `no-native-range` 规则禁止。
2147
2440
  - 功能状态加计数改用 `ApplicationMetricStatus`;数值加环比改用 `ApplicationMetricTrend`。
2148
2441
 
2149
- **组合约定。** 百分比由 `value` 与 `max` 得出并钳制在 0–100,`max` 缺省为 100,因此直接传百分比时不必再给 `max`。指标区内使用时,该组件作为 `ApplicationMetricStrip` 的 `children` 之一传入,卡片壳由指标区提供,本组件自身不带卡片;指标卡默认只读,整卡不得成为导航入口。`label` 与 `showValue` 共处同一行左右分列,二者都不给时该行不渲染。`tone` 使用状态色时,其含义必须与该状态在全产品内的含义一致。外边距由宿主承担;`height` 只改轨道厚度,不影响说明行。填充过渡受 `prefers-reduced-motion` 约束,业务侧不得另加动画。
2442
+ **组合约定。** 百分比由 `value` 与 `max` 得出并钳制在 0–100,`max` 缺省为 100,因此直接传百分比时不必再给 `max`。指标区内使用时,该组件作为 `ApplicationMetricStrip` 的 `children` 之一传入,卡片壳由指标区提供,本组件自身不带卡片;指标卡默认只读,整卡不得成为导航入口。`label` 与 `showValue` 共处同一行左右分列,二者都不给时该行不渲染。`label` 同时是进度条的可访问名称(组件以 `aria-labelledby` 关联);不显示 `label` 时须传 `aria-label`,组件把它落在 `role="progressbar"` 上而不是根节点。`tone` 使用状态色时,其含义必须与该状态在全产品内的含义一致。外边距由宿主承担;`height` 只改轨道厚度,不影响说明行。填充过渡受 `prefers-reduced-motion` 约束,业务侧不得另加动画。
2150
2443
 
2151
2444
  **禁止 / 使用边界。**
2152
2445
  - 不得用本组件表达不确定的等待,禁止做成来回往复的假进度。
@@ -2160,7 +2453,13 @@ Chart 的单条数据系列
2160
2453
 
2161
2454
  带可拖拽分隔条的双栏布局,支撑 SPLIT 工作面。
2162
2455
 
2163
- 默认左栏 360px,与 `--ui-sidebar-list-width` 一致。
2456
+ 默认左栏 360px,与 `--ui-sidebar-list-width` 的 Standard 档一致。
2457
+
2458
+ 宽度类 prop 收**数字或 CSS 长度字符串**(06 · P1-20):数字按 px,字符串原样
2459
+ 交给 CSS —— 传 `'var(--ui-sidebar-list-width)'` 即跟随密度档(360 / 300),
2460
+ 也可以写 `'30%'`、`'20rem'`。**拖拽与方向键调整后回调的恒为 px 数字**,按调整
2461
+ 那一刻的渲染宽度换算;受控方把它写回 `size` 之后,该栏就不再跟随原字符串里的
2462
+ `var()` / 百分比 —— 要恢复跟随,把 `size` 写回原字符串。
2164
2463
 
2165
2464
  ⚠ **拖动分栏永远不改变 `pageMode`。** 它只是布局调整。
2166
2465
 
@@ -2173,11 +2472,11 @@ Chart 的单条数据系列
2173
2472
  |---|---|:---:|---|
2174
2473
  | `left` | `ReactNode` | 否 | 左栏内容 |
2175
2474
  | `right` | `ReactNode` | 否 | 右栏内容,占据剩余宽度 |
2176
- | `defaultSize` | `number` | 否 | 左栏初始宽度,单位 px |
2177
- | `size` | `number` | 否 | 受控左栏宽度 |
2178
- | `onSizeChange` | `(size: number) => void` | 否 | 宽度变化回调。拖动过程中持续触发 |
2179
- | `min` | `number` | 否 | 左栏最小宽度,单位 px |
2180
- | `max` | `number` | 否 | 左栏最大宽度,单位 px |
2475
+ | `defaultSize` | `number \| string` | 否 | 左栏初始宽度。数字按 px,字符串为任意 CSS 长度。默认 360 |
2476
+ | `size` | `number \| string` | 否 | 受控左栏宽度。数字按 px,字符串为任意 CSS 长度(如 `'var(--ui-sidebar-list-width)'`) |
2477
+ | `onSizeChange` | `(size: number) => void` | 否 | 宽度变化回调。拖动过程中持续触发。 **参数恒为 px 数字**(已钳在 `min`–`max` 之间),不回传字符串 |
2478
+ | `min` | `number \| string` | 否 | 左栏最小宽度,只约束拖拽与方向键。数字按 px,字符串为任意 CSS 长度。默认 240 |
2479
+ | `max` | `number \| string` | 否 | 左栏最大宽度,只约束拖拽与方向键。数字按 px,字符串为任意 CSS 长度。默认 720 |
2181
2480
 
2182
2481
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
2183
2482
 
@@ -2191,7 +2490,7 @@ Chart 的单条数据系列
2191
2490
  - 需要的是三栏工作台 —— 改用 `ContactsCollaborationWorkspace`、`FilesCollaborationWorkspace`、`ScheduleCollaborationWorkspace`,三栏外壳已在这三者中收敛。
2192
2491
  - 两栏宽度固定、用户无需调整 —— 不使用本组件,直接由页面布局承担。
2193
2492
 
2194
- **组合约定。** 本组件不持有外边距,与相邻区块的间隙由父级负责。`size` 与 `defaultSize` 二选一:给了 `size` 即进入受控模式,此时必须同时提供 `onSizeChange`,否则分隔条拖不动。`min` 与 `max` 应成对给出,且必须落在调用方界面真实可用的范围内 —— 组件会把宽度钳制在这两个值之间。两个栏位均裁剪溢出,因此需要滚动的内容必须自带有界滚动容器(`ScrollArea` 或 `MessageScroller`),不得指望栏位自己滚。分隔条是 5px 宽的命中区并带焦点环,其两侧不得再叠加其他绝对定位元素。
2493
+ **组合约定。** 本组件不持有外边距,与相邻区块的间隙由父级负责。`size`、`defaultSize`、`min`、`max` 收数字或 CSS 长度字符串:数字按 px,字符串原样交给 CSS。左栏要跟随密度档(360 / 300)时传 `'var(--ui-sidebar-list-width)'`,不得在挂载时读出 token 的像素值再传数字 —— 那样换档后不跟随。拖拽与方向键调整后 `onSizeChange` 回传的恒为 px 数字(按调整那一刻的渲染宽度换算,已钳在 `min`–`max` 之间);受控方写回之后该栏不再跟随原字符串,要恢复跟随须把 `size` 写回原字符串。`min` 与 `max` 只约束拖拽与方向键,不钳制调用方写进 `size` 的值。`size` 与 `defaultSize` 二选一:给了 `size` 即进入受控模式,此时必须同时提供 `onSizeChange`,否则分隔条拖不动。`min` 与 `max` 应成对给出,且必须落在调用方界面真实可用的范围内 —— 组件会把宽度钳制在这两个值之间。两个栏位均裁剪溢出,因此需要滚动的内容必须自带有界滚动容器(`ScrollArea` 或 `MessageScroller`),不得指望栏位自己滚。分隔条是 5px 宽的命中区并带焦点环,其两侧不得再叠加其他绝对定位元素。分隔条的可访问名为「分栏宽度」,`aria-valuenow` 取整数像素。
2195
2494
 
2196
2495
  **禁止 / 使用边界。**
2197
2496
  - 不得让拖动分栏改变 `pageMode` —— 它只是布局调整,与页面模式无关。
@@ -2205,7 +2504,8 @@ Chart 的单条数据系列
2205
2504
 
2206
2505
  有界滚动区域,带细样式滚动条 —— 长筛选列表、宽表格、必须单行的标签条。
2207
2506
 
2208
- ⚠ **Content Canvas 是页面唯一的主垂直滚动权持有者。**
2507
+ ⚠ **每个页面只有一个页面级纵向滚动持有者**:结果集页面是 `ApplicationDataDisplay`
2508
+ 的主体,其余页面是 Content Canvas(06 · D-4)。
2209
2509
  本组件只用于**正交方向**(水平)或**局部有界**的溢出。
2210
2510
  绝不堆叠无界的垂直滚动容器。
2211
2511
 
@@ -2228,12 +2528,12 @@ Chart 的单条数据系列
2228
2528
  - 滚动的是消息流 —— 改用 `MessageScroller`,它是消息流已登记的有界滚动容器并自带贴底行为。
2229
2529
  - 溢出的是表格的横向内容 —— 不使用本组件,`Table` 自身已持有横向滚动。
2230
2530
  - 需要的是固定比例的槽位而非滚动 —— 改用 `AspectRatio`。
2231
- - 页面主体内容超出视口 —— 不使用本组件,Content Canvas 是页面唯一的垂直滚动持有者。
2531
+ - 页面主体内容超出视口 —— 不使用本组件,页面级纵向滚动的归属按页型划分,见 SKILL.md「五层 Canvas 模型 · 纵向滚动归属」。
2232
2532
 
2233
- **组合约定。** `height` 与 `maxHeight` 传数字时按 px 解释;两者可同时缺省,但缺省的垂直 ScrollArea 等于没有约束。`horizontal` 为 true 时垂直方向为 `hidden` —— 单个 ScrollArea 只承担一个方向,需要两个方向必须重新设计布局而不是嵌套两层。本组件不持有内边距与外边距,内容的留白由被包裹的内容自身负责。被包裹内容若自带外边距,滚动区末尾会出现视觉上的空白,应改由内容内部处理。
2533
+ **组合约定。** `height` 与 `maxHeight` 传数字时按 px 解释;两者可同时缺省,但缺省的垂直 ScrollArea 等于没有约束。`horizontal` 为 true 时垂直方向为 `hidden` —— 单个 ScrollArea 只承担一个方向,需要两个方向必须重新设计布局而不是嵌套两层。唯一的登记例外是看板(07 · C-14):外层 `horizontal` 只管横向,列内各一个纵向 ScrollArea,写法见 SKILL.md「五层 Canvas 模型 · 呈现配方」。本组件不持有内边距与外边距,内容的留白由被包裹的内容自身负责。被包裹内容若自带外边距,滚动区末尾会出现视觉上的空白,应改由内容内部处理。`horizontal` 且内容确实溢出时,区域本身成为 Tab 停靠点并以 `region` 暴露,调用方应以 `aria-label` 写明区域内容(缺省为「横向滚动区域」);不溢出时不加停靠点。该组件为测量溢出带 `"use client"`。
2234
2534
 
2235
2535
  **禁止 / 使用边界。**
2236
- - 禁止在 Content Canvas 内堆叠无界的垂直滚动容器 —— Content Canvas 是唯一的垂直滚动权持有者。
2536
+ - 禁止在 Content Canvas 内堆叠无界的垂直滚动容器 —— 每个页面只有一个页面级纵向滚动持有者,按页型划分。
2237
2537
  - 不得用本组件包裹 `ApplicationPageLayoutContainer` 或 `ApplicationDataDisplay`,那会制造第二个页面级垂直滚动。
2238
2538
  - 不得在同一个 ScrollArea 上同时开启两个滚动方向。
2239
2539
  - 不得用本组件包裹 `Table` 以求横向滚动 —— 会得到两层横向滚动条。
@@ -2257,7 +2557,7 @@ Chart 的单条数据系列
2257
2557
  |---|---|:---:|---|
2258
2558
  | `orientation` | `'horizontal' \| 'vertical'` | 否 | 方向。垂直分隔线需要父容器有确定高度 |
2259
2559
  | `label` | `ReactNode` | 否 | 居中标签。提供时线被文字断开,用于长列表的分段标题 |
2260
- | `spacing` | `string \| number` | 否 | 分隔线两侧的外边距。应传 token,如 `var(--ds-space-2)` |
2560
+ | `spacing` | `string \| number` | 否 | 分隔线两侧的外边距。应传 token,如 `var(--application-space-2)` |
2261
2561
 
2262
2562
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
2263
2563
 
@@ -2271,7 +2571,7 @@ Chart 的单条数据系列
2271
2571
  - 需要的是菜单条目之间的分隔 —— 不使用本组件,`DropdownMenu` 的条目数据自带分隔线形态。
2272
2572
  - 需要的是表格行之间的分隔 —— 不使用本组件,`Table` 自带 1px 行分隔线。
2273
2573
 
2274
- **组合约定。** 本组件自己持有两侧外边距,默认一档 12px,调用方通过 `spacing` 调整。`spacing` 必须传 token(如 `var(--ds-space-2)`)或数字,不得传字面 px 字符串。因为外边距归本组件所有,相邻元素不得再为分隔线补 margin —— 否则得到双份间距。`orientation` 为 `vertical` 时需要父容器有确定高度,实际做法是把它放进一个 `align-items: stretch` 的 flex 行;父容器高度不确定时垂直线不可见。带 `label` 的形态只用于分段标题,`label` 应是 2–4 字裸名词短语。
2574
+ **组合约定。** 本组件自己持有两侧外边距,默认一档 12px,调用方通过 `spacing` 调整。`spacing` 必须传 token(如 `var(--application-space-2)`)或数字,不得传字面 px 字符串。因为外边距归本组件所有,相邻元素不得再为分隔线补 margin —— 否则得到双份间距。`orientation` 为 `vertical` 时需要父容器有确定高度,实际做法是把它放进一个 `align-items: stretch` 的 flex 行;父容器高度不确定时垂直线不可见。带 `label` 的形态只用于分段标题,`label` 应是 2–4 字裸名词短语。
2275
2575
 
2276
2576
  **禁止 / 使用边界。**
2277
2577
  - 不得用本组件替代 `Card` 的 `footer` 上边框 —— `footer` 已自带上边框与上内边距。
@@ -2329,7 +2629,8 @@ Chart 的单条数据系列
2329
2629
 
2330
2630
  DataTable 承载面 —— LIST 页面模式、LEDGER 台账页、SPLIT 右栏。
2331
2631
 
2332
- 表头位于 `--application-table-header`,行与行之间用 1px 分隔线,**不是阴影**。
2632
+ 表头位于 `--application-table-header`,高 44;表体行最小高 56(两行内容 72)。
2633
+ 行与行之间、表头列与列之间是 0.5px 分隔线(`--application-hairline`),**不是投影**。
2333
2634
 
2334
2635
  ⚠ 当本组件是当前的 Data Presentation 时,
2335
2636
  其上方的设置按钮**必须**写作「列设置」,不得写成通用的「视图设置」。
@@ -2348,11 +2649,12 @@ DataTable 承载面 —— LIST 页面模式、LEDGER 台账页、SPLIT 右栏
2348
2649
  | `selectable` | `boolean` | 否 | 启用行选择,首列渲染选择框 |
2349
2650
  | `selected` | `string[]` | 否 | 已选中的行标识集合 |
2350
2651
  | `onSelectedChange` | `(ids: string[]) => void` | 否 | 选中集合变化回调。表头全选框会一次性给出全部或空数组 |
2351
- | `onRowClick` | `(row: R) => void` | 否 | 行点击回调。设置后整行 `cursor: pointer` |
2652
+ | `onRowClick` | `(row: R) => void` | 否 | 行点击回调。设置后整行 `cursor: pointer`、可聚焦,Enter / 空格同样触发 |
2352
2653
  | `sort` | `TableSort` | 否 | 受控排序状态 |
2353
2654
  | `onSortChange` | `(sort: TableSort) => void` | 否 | 排序变化回调。同列再次点击在 asc / desc 间切换 |
2354
2655
  | `empty` | `ReactNode` | 否 | `rows` 为空时替代行区域渲染的内容。 **应当传入 `<Empty />`** —— 空态文案不得与无权限、未找到、加载失败共用。 |
2355
2656
  | `density` | `'default' \| 'sm'` | 否 | 密度。影响单元格内边距 |
2657
+ | `trailingRow` | `TableTrailingRow` | 否 | 数据行之后追加的一条通栏行,横跨全部列。用于「识别中…」「正在加载更多」这类 附着在列表末尾的进行中状态。`rows` 为空时不渲染(此时显示 `empty`)。 **不得**用它承载数据行、合计行或分组标题 —— 那些有各自的列语义。 |
2356
2658
 
2357
2659
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
2358
2660
 
@@ -2369,6 +2671,16 @@ Table 的单列定义
2369
2671
  | `sortable` | `boolean` | 否 | 该列可排序。表头显示排序指示器并可点击 |
2370
2672
  | `priority` | `'primary' \| 'default' \| 'low'` | 否 | 列优先级,决定窄视口下**先压缩谁、先隐藏谁**。 对应 02 §9 规则 8「先压间距,再压列数,再压优先级」。 **每一列都应显式设置**,否则窄视口下的降级顺序不可预期。 |
2371
2673
  | `render` | `(row: R) => ReactNode` | 否 | 单元格渲染函数。提供时取代按 `key` 取值 |
2674
+ | `fixed` | `'left' \| 'right'` | 否 | 固定列。横向滚动时该列贴住表格左缘或右缘,朝滚动内容一侧带 16px 渐隐阴影。 **只允许首列声明 `'left'`、末列声明 `'right'`,每侧至多一列** —— 不计算多列叠加偏移。声明在中间列上不报错,但滚动时会与相邻列重叠。 典型用法:末列「操作」固定在右侧。有选择列时,首列固定会连同选择列一起固定。 |
2675
+
2676
+ **`TableTrailingRow`**
2677
+
2678
+ 数据行之后的通栏行
2679
+
2680
+ | prop | 类型 | 必填 | 说明 |
2681
+ |---|---|:---:|---|
2682
+ | `content` | `ReactNode` | 是 | 行内容,横跨全部列居中显示。例如「识别中…」「正在加载更多」 |
2683
+ | `busy` | `boolean` | 否 | 进行中。叠加一层扫光动效;系统开启减少动效时不播放 |
2372
2684
 
2373
2685
  **`TableSort`**
2374
2686
 
@@ -2381,7 +2693,7 @@ Table 的单列定义
2381
2693
 
2382
2694
  **用途。** DataTable 呈现方式的承载面 —— LIST 页面模式、LEDGER 台账页、SPLIT 右栏共用同一份表。
2383
2695
 
2384
- **何时使用。** 数据需要按列对齐、逐列比较、按列排序时,必须使用本组件。它是数据驱动的:列写在 `columns`,行数据写在 `rows`。表头位于 `--application-table-header`,行与行之间用 1px 分隔线而非阴影。密度分 `default` 与 `sm` 两档,只影响单元格内边距。
2696
+ **何时使用。** 数据需要按列对齐、逐列比较、按列排序时,必须使用本组件。它是数据驱动的:列写在 `columns`,行数据写在 `rows`。表头位于 `--application-table-header`,高 44px;表体单元格四边 16px 内边距,行最小高 56px(两行内容 72px);选择列 48px;行与行之间、表头列与列之间是 0.5px 分隔线而非阴影。密度分 `default` 与 `sm` 两档,只影响单元格内边距与行高下限。
2385
2697
 
2386
2698
  **何时改用其他组件。**
2387
2699
  - 列数过剩、但行仍需扫视 —— 改用 `ApplicationRecordList`,它是非表格形态的结构化列表。
@@ -2390,7 +2702,7 @@ Table 的单列定义
2390
2702
  - 只是一组同构的目录行,无列对齐需求 —— 改用 `Item`。
2391
2703
  - 需要手写 `<table>` / `<tr>` / `<td>` —— 一律改用本组件,手写表格拿不到已登记的表头底色、行分隔线与列宽约定。
2392
2704
 
2393
- **组合约定。** 本组件不持有外边距,与相邻区块的间隙由 `ApplicationDataDisplay` 与 `ApplicationPageLayoutContainer` 负责;横向溢出在组件内部消化,外部不得再套横向滚动容器。`selectable` 为 true 时必须同时提供 `selected` 与 `onSelectedChange`,否则勾选框点了没有任何反应;选择框由 `ListSelectionCheckbox` 承担,勾选不会顺带触发 `onRowClick`。任一列设了 `sortable` 时必须同时提供 `sort` 与 `onSortChange`,同列再次点击在 `asc` 与 `desc` 间切换。`rowKey` 必须指向 `rows` 中真实存在且唯一的字段,缺省值是 `id`。每一列都应显式设置 `priority`:`low` 列在 1180px 宽或 720px 高以下整列隐藏,单元格内边距在 1439px 以下先行压缩,顺序即「先压间距,再压列数,再压优先级」。`rows` 为空时必须提供 `empty`,且应当传 `<Empty />`。批量动作条与分页不属于本组件,分别走 `ApplicationDataDisplay` 的 `batchBar` 与 `pagination` 槽位,前者传 `ListBatchActionBar`,后者传 `ListTablePagination`。
2705
+ **组合约定。** 本组件不持有外边距,与相邻区块的间隙由 `ApplicationDataDisplay` 与 `ApplicationPageLayoutContainer` 负责;横向溢出在组件内部消化,外部不得再套横向滚动容器。`selectable` 为 true 时必须同时提供 `selected` 与 `onSelectedChange`,否则勾选框点了没有任何反应;选择框由 `ListSelectionCheckbox` 承担,勾选不会顺带触发 `onRowClick`;它的可访问名是「选择」加标题列(首个 `priority: 'primary'` 的列,未声明取首列)单元格的内容。给了 `onRowClick` 的行可聚焦,Enter / 空格触发同一回调,行保留表格行语义、不改作按钮。行点击与按键忽略来自行内可交互元素(按钮、链接、勾选框、菜单等)的事件,`render` 里放这类控件时调用方不必再手动阻止冒泡。任一列设了 `sortable` 时必须同时提供 `sort` 与 `onSortChange`,同列再次点击在 `asc` 与 `desc` 间切换。放进 `ApplicationDataDisplay` 时,表头排序是工具栏 `sort` 槽位(`Select`)的第二入口,`sort` 必须与工具栏取自同一份排序状态(07 · C-2)。`rowKey` 必须指向 `rows` 中真实存在且唯一的字段,缺省值是 `id`。每一列都应显式设置 `priority`:`low` 列在 1180px 宽或 720px 高以下整列隐藏,单元格内边距在 1439px 以下先行压缩,顺序即「先压间距,再压列数,再压优先级」。单独使用时 `rows` 为空必须提供 `empty`,且应当传 `<Empty />`;放进 `ApplicationDataDisplay` 时不另设 `empty`,空结果由数据展示区的 `state="empty"` 与 `empty` 槽位承担(07 · C-6)。批量动作条与分页不属于本组件,分别走 `ApplicationDataDisplay` 的 `batchBar` 与 `pagination` 槽位,前者传 `ListBatchActionBar`,后者传 `ListTablePagination`。有设计稿时,每一列的 `width` 取设计稿的列宽:固定宽的列写数字,弹性列不写 `width`,由表格均分剩余宽度 —— 不得全部留空交给浏览器按内容分配。列数多、需要横向滚动时,末列「操作」写 `fixed: 'right'` 贴住右缘,首列标题列可写 `fixed: 'left'`;只允许首列声明 `left`、末列声明 `right`,每侧至多一列。附着在列表末尾的进行中状态(「识别中…」「正在加载更多」)经 `trailingRow` 渲染为一条横跨全部列的通栏行,`busy` 为 true 时带扫光动效;`rows` 为空时它不渲染。
2394
2706
 
2395
2707
  **禁止 / 使用边界。**
2396
2708
  - 禁止手写 `<tr>` / `<td>` 作为子元素传入 —— 本组件不接受复合子组件,列与行只能来自 `columns` 与 `rows`。
@@ -2398,6 +2710,8 @@ Table 的单列定义
2398
2710
  - 不得为 LIST 页面模式与 SPLIT 右栏各写一份近乎相同的表,同一份业务数据只允许一份实现。
2399
2711
  - 不得在单元格内嵌套第二个 `Table`。
2400
2712
  - 不得省略 `priority`,缺省会让窄视口下的降级顺序不可预期。
2713
+ - 不得用 `trailingRow` 承载数据行、合计行或分组标题,它只表达列表末尾的进行中状态。
2714
+ - 不得给中间列声明 `fixed`,也不得在同一侧固定两列 —— 组件不计算多列叠加偏移,滚动时会重叠。
2401
2715
 
2402
2716
  ## Foundation · feedback-overlay
2403
2717
 
@@ -2436,7 +2750,7 @@ Table 的单列定义
2436
2750
  - 整个区域或结果集无数据改用 `Empty`,其文案须区别于无权限与加载失败。
2437
2751
  - 结构性加载占位改用 `Skeleton`,短时原地等待改用 `Spinner`。
2438
2752
 
2439
- **组合约定。** 该组件无开合状态,由调用方条件渲染。`action` 槽位应传单个 `Button`,文案为 2–4 字裸名词短语(`重试`)。状态图标由 `tone` 推导,不接受外部传入的图标。`tone="danger"` 时该组件以 `role="alert"` 打断式播报,其余三个 tone 为 `role="status"`,调用方不得再手动覆盖 `role`。该组件不带外边距,与相邻内容的间距由父容器的 `gap` 负责。`ApplicationFormDialog` 的 `error` 槽位必须传 `<Alert tone="danger">`,渲染在表单主体顶部。
2753
+ **组合约定。** 该组件无开合状态,由调用方条件渲染。`action` 槽位应传单个 `SystemButton`,文案为 2–4 字裸名词短语(`重试`)。状态图标由 `tone` 推导,不接受外部传入的图标。`tone="danger"` 时该组件以 `role="alert"` 打断式播报,其余三个 tone 为 `role="status"`,调用方不得再手动覆盖 `role`。该组件不带外边距,与相邻内容的间距由父容器的 `gap` 负责。`ApplicationFormDialog` 的 `error` 槽位必须传 `<Alert tone="danger">`,渲染在表单主体顶部。数据区的 Partial Failure 传进 `ApplicationDataDisplay` 的 `notice` 槽位,不放进呈现组件之内。
2440
2754
 
2441
2755
  **禁止 / 使用边界。**
2442
2756
  - 不得用本组件承载必须阻断的确认,那是 `AlertDialog` 的职责。
@@ -2458,19 +2772,24 @@ Table 的单列定义
2458
2772
 
2459
2773
  需要用户填写内容的一律用 `Dialog`。
2460
2774
 
2775
+ 版式照 GAP Design kit「弹窗 / 提示」(188:687):宽 680、最小高 240,不接受尺寸调整;
2776
+ 面板圆角 20,与其余模态弹窗同取 `--ds-radius-dialog`。页头、主体、页脚与 `Dialog` 同一套三段结构,
2777
+ 页头在标题前多一个 20px 的提示图标(`circle-alert`,警示色),图标、标题、关闭键间隔 8;
2778
+ 说明在主体内居中,16/20。
2779
+
2461
2780
  **Props**
2462
2781
 
2463
2782
  | prop | 类型 | 必填 | 说明 |
2464
2783
  |---|---|:---:|---|
2465
2784
  | `open` | `boolean` | 否 | 是否打开。为 false 时组件渲染 `null` |
2466
2785
  | `title` | `ReactNode` | 否 | 标题。须写明后果与受影响数量 |
2467
- | `description` | `ReactNode` | 否 | 说明文字。用于补充不可恢复性等关键信息 |
2786
+ | `description` | `ReactNode` | 否 | 说明文字,主体内居中,16/20 文字1。用于补充不可恢复性等关键信息 |
2468
2787
  | `confirmText` | `string` | 否 | 确认按钮文案。应是具体动词(「删除」)而非泛化的「确定」 |
2469
2788
  | `cancelText` | `string` | 否 | 取消按钮文案 |
2470
- | `destructive` | `boolean` | 否 | 破坏性动作。确认按钮转为 danger 色 |
2789
+ | `destructive` | `boolean` | 否 | 破坏性动作。确认按钮转为 danger 色;页头的提示图标不随之变化,仍取警示色 |
2471
2790
  | `onConfirm` | `() => void` | 否 | 确认回调 |
2472
2791
  | `onCancel` | `() => void` | 否 | 取消回调。关闭按钮亦触发 |
2473
- | `children` | `ReactNode` | 否 | 额外内容,插在说明与按钮之间。用于列出受影响对象等 |
2792
+ | `children` | `ReactNode` | 否 | 额外内容,在主体内排在说明之后。用于列出受影响对象等 |
2474
2793
 
2475
2794
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `title` 已被本组件重新定义或移除。
2476
2795
 
@@ -2483,23 +2802,25 @@ Table 的单列定义
2483
2802
  - 可撤销的已完成事实改用 `Sonner`,并把撤销放进它的 `action`。
2484
2803
  - 不阻断主任务的失败提示改用 `Alert`。
2485
2804
 
2486
- **组合约定。** 该组件宽度固定为 420px,不接受尺寸调整。点击遮罩不关闭 —— 破坏性确认必须是显式选择;Esc 仍然可用,等同于取消,不会误触发确认。`onCancel` 同时承担取消按钮、右上角关闭按钮与 Esc 三条路径,缺省它会使该组件无法关闭。`cancelText` 同时作为右上角关闭按钮的无障碍名称,因此必须是 2–4 字裸名词短语,不得写成句子。确认与取消按钮由该组件内部渲染,调用方不得再在 `children` 中放置一组按钮;`children` 只用于列出受影响对象。
2805
+ **组合约定。** 该组件宽度固定为 680px、最小高 240px,不接受尺寸调整;面板圆角 20(GAP Design kit「弹窗 / 提示」),与其余模态弹窗同一角色。页头、主体、页脚与 `Dialog` 同一套三段结构:页头在标题前固定显示 20px 的 `circle-alert` 提示图标(警示色,`destructive` 与否都不变 —— 破坏性只由确认按钮的 danger 色表达),`description` 在主体内上下居中、16/20 居中排版。点击遮罩不关闭 —— 破坏性确认必须是显式选择;Esc 仍然可用,等同于取消,不会误触发确认。`onCancel` 同时承担取消按钮、右上角关闭按钮与 Esc 三条路径,缺省它会使该组件无法关闭。右上角关闭按钮的无障碍名称固定为「关闭」,与取消按钮可区分;打开时初始焦点落在取消按钮,误按 Enter 不会触发确认。`cancelText` 必须是 2–4 字裸名词短语,不得写成句子。面板以 `role="alertdialog"` 输出,`title` 与 `description` 分别作为它的可访问名与描述。确认与取消按钮由该组件内部渲染,调用方不得再在 `children` 中放置一组按钮;`children` 只用于列出受影响对象。
2487
2806
 
2488
2807
  **禁止 / 使用边界。**
2489
2808
  - 不得在 `children` 中放置输入控件或表单字段。
2490
2809
  - 禁止把标题写成不含数量与后果的泛化问句。
2491
- - 不得在本组件之上再叠加第二层模态浮层。
2810
+ - 不得在本组件之上再叠加任何模态浮层 —— 它本身就是「模态之上放行的那一层」,再往上即超过一层(06 · D-3)。
2492
2811
  - 不得依赖点击遮罩关闭,该路径已按契约关闭。
2812
+ - 不得在 `title` 或 `children` 里再放一个警示图标 —— 页头已固定显示,重复出现即为两枚。
2493
2813
 
2494
2814
  ### Collapsible
2495
2815
 
2496
2816
  `import { Collapsible } from '@moheng-design/ui'` · 契约 `contracts/foundation/feedback-overlay/collapsible.ts`
2497
2817
 
2498
- 单个显隐区域,由一个触发器控制 —— 查询工具栏里的「更多筛选」模式。
2818
+ 单个显隐区域,由一个触发器控制 —— 详情页的次要分节、表单里的高级选项。
2499
2819
 
2500
- ⚠ **折叠只改变入口,绝不移除能力。** 被收起的筛选项仍然存在、仍可使用。
2820
+ ⚠ **折叠只改变入口,绝不移除能力。** 被收起的内容仍然存在、仍可使用。
2501
2821
 
2502
- 「更多筛选」通过「应用」提交,生效的条件须回写到筛选标签行。
2822
+ ⚠ 查询工具栏的「更多筛选」**不用本组件**,一律用 `Popover`:就地展开会把工具栏
2823
+ 撑高(实测 99px → 452px),SPLIT 页的两栏随之被压扁(06 · D-4)。
2503
2824
 
2504
2825
  多个并列的折叠区请用 `Accordion`。
2505
2826
 
@@ -2509,7 +2830,7 @@ Table 的单列定义
2509
2830
 
2510
2831
  | prop | 类型 | 必填 | 说明 |
2511
2832
  |---|---|:---:|---|
2512
- | `label` | `ReactNode` | 否 | 触发器文字,如「更多筛选」 |
2833
+ | `label` | `ReactNode` | 否 | 触发器文字,如「版本记录」 |
2513
2834
  | `defaultOpen` | `boolean` | 否 | 非受控初始展开状态 |
2514
2835
  | `open` | `boolean` | 否 | 受控展开状态 |
2515
2836
  | `onOpenChange` | `(open: boolean) => void` | 否 | 展开状态变化回调 |
@@ -2517,14 +2838,14 @@ Table 的单列定义
2517
2838
 
2518
2839
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
2519
2840
 
2520
- **用途。** 单个显隐区域,由一个触发器控制 —— 查询工具栏里的「更多筛选」模式。
2841
+ **用途。** 单个显隐区域,由一个触发器控制 —— 详情页的次要分节、表单里的高级选项。
2521
2842
 
2522
- **何时使用。** 当低频能力需要收进入口、但能力本身必须保留时,该组件是默认选择。查询工具栏内常驻 2–3 个高频筛选维度,其余维度一律收进本组件。触发器文字通过 `label` 传入,写作 2–4 字裸名词短语(`更多筛选`)。
2843
+ **何时使用。** 当低频能力需要收进入口、但能力本身必须保留时,该组件是默认选择。触发器文字通过 `label` 传入,写作 2–4 字裸名词短语(`版本记录`)。
2523
2844
 
2524
2845
  **何时改用其他组件。**
2525
2846
  - 多个并列或互斥的折叠区改用 `Accordion`。
2526
2847
  - 页面级的区域切换改用 `Tabs`。
2527
- - 需要锚定浮出而非就地展开的「更多筛选」改用 `Popover`,两者都可填入 `ApplicationQueryToolbar` 的 `moreFilters` 槽位。
2848
+ - 查询工具栏的「更多筛选」一律改用 `Popover`,填入 `ApplicationQueryToolbar` 的 `moreFilters` 槽位。本组件就地展开会把工具栏撑高(实测 99px → 452px),SPLIT 页的两栏随之被压扁(06 · D-4)。
2528
2849
  - 辅助性内容的侧滑面板改用 `Sheet`。
2529
2850
 
2530
2851
  **组合约定。** 折叠只改变入口,绝不移除能力 —— 被收起的筛选项仍然存在、仍可使用,调用方不得在收起时把它们从状态中移除。「更多筛选」通过「应用」提交,生效的条件必须回写到 `ApplicationQueryToolbar` 第三行的筛选标签行。受控模式下 `open` 与 `onOpenChange` 必须成对出现,只传 `open` 会得到一个永不展开的区域。内容区的上边距由该组件自身声明,调用方不得再叠加外边距。触发器沿用 32px 高度与 16px 圆角的按钮几何,但它不是 `Button`,不接受 `variant` 一类的按钮属性。
@@ -2541,7 +2862,13 @@ Table 的单列定义
2541
2862
 
2542
2863
  模态容器,用于用户必须完成或放弃的聚焦任务 —— 新建、编辑、导入映射。
2543
2864
 
2544
- 已登记宽度:`small` 720px、`large` 960px。
2865
+ 已登记宽度:`small` 720px、`large` 960px。面板圆角 20(GAP Design kit「抽屉弹窗 / 弹窗」,
2866
+ 模态弹窗角色 `--ds-radius-dialog`,与 `AlertDialog`、`ApplicationFormDialog`、`PeoplePickerDialog` 一致)。
2867
+
2868
+ 三段结构照 kit「弹窗」类型=默认(188:685):页头最小高 48、内边距 8/12、标题与关闭键间隔 10,
2869
+ 底边 0.5px 分隔线;主体内边距 12;页脚内边距 12、动作间隔 4,顶边 0.5px 分隔线。
2870
+ 三段同为导航背景色(`--ds-color-canvas`),关闭键 32×32、圆角 12。面板最小高 240,
2871
+ 视口更矮时让位于「绝不超出有效视口」。
2545
2872
 
2546
2873
  ⚠ **Overlay 只是物理容器。** 它绝不创造新的 Page Type 或 Page Mode,
2547
2874
  也**绝不超出有效视口**。
@@ -2556,31 +2883,34 @@ Table 的单列定义
2556
2883
  | prop | 类型 | 必填 | 说明 |
2557
2884
  |---|---|:---:|---|
2558
2885
  | `open` | `boolean` | 否 | 是否打开。为 false 时组件渲染 `null` |
2559
- | `title` | `ReactNode` | 否 | 标题,16/24 medium 字重 |
2886
+ | `title` | `ReactNode` | 否 | 标题,16/20 medium 字重 |
2560
2887
  | `description` | `ReactNode` | 否 | 标题下的补充说明,12/16 label 色 |
2561
2888
  | `size` | `'small' \| 'large' \| number` | 否 | 宽度。`small` 720px、`large` 960px,也接受任意数字。 无论取值如何都受 `max-width: 100%` 与视口边距约束 |
2562
2889
  | `footer` | `ReactNode` | 否 | 底部动作区,右对齐。取消在左、主操作在右 |
2890
+ | `footerNote` | `ReactNode` | 否 | 页脚左侧的说明,12/16 label 色,占满动作左侧的剩余宽度(kit「弹窗」操作插槽 188:662)。 只传它不传 `footer` 时页脚照样渲染 |
2563
2891
  | `onClose` | `() => void` | 否 | 关闭回调。点击遮罩与关闭按钮都会触发 |
2892
+ | `initialFocus` | `RefObject<HTMLElement \| null>` | 否 | 打开时的初始焦点(06 · P3-1)。缺省时落在面板内首个可聚焦元素 —— 标题栏的 关闭按钮。键盘优先的内容(首个输入框、搜索框)应把它的 ref 传进来。 目标须在本组件内;关闭后焦点照常回到打开前的元素 |
2564
2893
  | `children` | `ReactNode` | 否 | 主体内容。超长时本区域内部滚动,标题与页脚保持固定 |
2565
2894
 
2566
2895
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `title` 已被本组件重新定义或移除。
2567
2896
 
2568
2897
  **用途。** 模态容器,用于用户必须完成或放弃的聚焦任务 —— 新建、编辑、导入映射。
2569
2898
 
2570
- **何时使用。** 当任务需要用户在离开前完成或明确放弃、且不适合占用整页时,该组件是默认的物理容器。已登记宽度为 `small` 720px、`large` 960px;`size` 也接受任意数字,但无论取值如何都受 `max-width: 100%` 与视口边距约束。命令面板(`Command`)作为全局搜索与执行入口时放进本组件。
2899
+ **何时使用。** 当任务需要用户在离开前完成或明确放弃、且不适合占用整页时,该组件是默认的物理容器。已登记宽度为 `small` 720px、`large` 960px;`size` 也接受任意数字,但无论取值如何都受 `max-width: 100%` 与视口边距约束。面板圆角 20(GAP Design kit「抽屉弹窗 / 弹窗」),取模态弹窗角色 `--ds-radius-dialog`,与 `AlertDialog`、`ApplicationFormDialog`、`PeoplePickerDialog` 一致。版式照 kit 类型=默认:页头、主体、页脚三段同为导航背景色,页头最小高 48、标题 16/20 medium、右侧 32×32 关闭键,页脚动作间隔 4,两处分隔线均为 0.5px;面板最小高 240。
2571
2900
 
2572
2901
  **何时改用其他组件。**
2573
2902
  - 完整业务表单改用 `ApplicationFormDialog`,它拥有已登记的字段网格与提交语义。
2574
2903
  - 不可逆动作的确认改用 `AlertDialog`。
2575
2904
  - 业务对象详情改用 `Drawer` 或独立详情页。
2576
- - 辅助性内容(设置、帮助、附件预览)改用 `Sheet`。
2905
+ - 辅助性内容(帮助、附件预览)改用 `Sheet`;全局设置是 `ApplicationSecondaryNavigation` 里的设置模块,不进任何浮层。
2577
2906
  - 无需阻断背景的锚定面板改用 `Popover`。
2907
+ - 全局命令面板改用 `Command` 的 `dialog` 形态,不要把 `Command` 放进本组件。
2578
2908
 
2579
- **组合约定。** 该组件与 `AlertDialog`、`Drawer`、`Sheet` 共用同一个模态基座,因此自带遮罩、Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定,调用方不得再自行实现这五件事,也不得自行设置 `z-index`。`onClose` 同时承担遮罩点击与关闭按钮两条路径。`footer` 右对齐,取消在左、主操作在右,其中至多一个 `Button` 用 `variant="primary"`。主体区域内部滚动而标题与页脚固定,调用方不得在 `children` 外层再套一个滚动容器。`open` 为 false 时该组件渲染 null,内部状态随之丢失 —— 需要保留草稿的调用方必须自行持有该状态。
2909
+ **组合约定。** 该组件与 `AlertDialog`、`Drawer`、`Sheet` 共用同一个模态基座,因此自带遮罩、Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定,调用方不得再自行实现这五件事,也不得自行设置 `z-index`。`onClose` 同时承担遮罩点击与关闭按钮两条路径。打开时焦点默认落在面板内首个可聚焦元素,即标题栏的关闭按钮;主体以输入为主(新建、编辑)时应以 `initialFocus` 传入首个字段的 ref,焦点一次落定,不先经过关闭按钮。`footer` 右对齐,取消在左、主操作在右,其中至多一个 `SystemButton` 用 `intent="primary"`。页脚左侧的补充信息(条数、当前位置、保存状态)传 `footerNote`,由该组件排成 12/16 label 色并把动作挤到右侧,调用方不得在 `footer` 里自行拼一段说明文字。主体区域内部滚动而标题与页脚固定,调用方不得在 `children` 外层再套一个滚动容器。`open` 为 false 时该组件渲染 null,内部状态随之丢失 —— 需要保留草稿的调用方必须自行持有该状态。
2580
2910
 
2581
2911
  **禁止 / 使用边界。**
2582
2912
  - 不得在本组件内改变 `pageType` 或 `pageMode` —— 浮层只是物理容器,绝不创造新的页面类型或页面模式。
2583
- - 禁止在本组件内嵌套第二个模态浮层。
2913
+ - 禁止在本组件内嵌套第二个对话框、抽屉或侧板。模态之上至多再叠一层确认框(`AlertDialog`)或选择器(`PeoplePickerDialog`),更深的嵌套一律禁止(06 · D-3):表单里的选人字段打开 `PeoplePickerDialog`、破坏性动作打开 `AlertDialog` 都属于放行的那一层,基座的 Esc 层级栈与焦点陷阱保证只有最上层响应。
2584
2914
  - 不得为完整业务表单手工拼装本组件的字段布局。
2585
2915
  - 不得传入使面板超出有效视口的宽度。
2586
2916
 
@@ -2607,7 +2937,7 @@ Table 的单列定义
2607
2937
  | `open` | `boolean` | 否 | 是否打开。为 false 时组件渲染 `null` |
2608
2938
  | `title` | `ReactNode` | 否 | 标题,16/24 medium 字重,超长省略 |
2609
2939
  | `width` | `number` | 否 | 宽度,单位 px。推荐 680 |
2610
- | `side` | `'right' \| 'left'` | 否 | 停靠侧。见 F2 —— 当前实现下 `left` 不生效 |
2940
+ | `side` | `'right' \| 'left'` | 否 | 停靠侧,默认 `right`。两侧均生效(F2 已在阶段 4 修正) |
2611
2941
  | `footer` | `ReactNode` | 否 | 底部动作区,右对齐且固定 |
2612
2942
  | `onClose` | `() => void` | 否 | 关闭回调。点击遮罩与关闭按钮都会触发 |
2613
2943
  | `children` | `ReactNode` | 否 | 主体内容,本区域内部滚动 |
@@ -2620,7 +2950,8 @@ Table 的单列定义
2620
2950
 
2621
2951
  **何时改用其他组件。**
2622
2952
  - 已登记的业务详情结构改用 `ApplicationDetailDrawer`,其主体须传 `ApplicationRecordDetailBody`。
2623
- - 辅助性内容(帮助、附件预览)改用 `Sheet`,它在结构上更轻,不承载业务记录。全局设置是例外,它由 `ApplicationPrimaryNavigation` 的 settings 动作以 `kind='drawer'` 打开,本组件与 `Sheet` 均可承载。
2953
+ - 辅助性内容(帮助、附件预览)改用 `Sheet`,它在结构上更轻,不承载业务记录。
2954
+ - 全局设置改用 `ApplicationSecondaryNavigation` 的设置模块 —— `ApplicationPrimaryNavigation` 的设置动作给出的 `kind` 是 `'module'`,不打开抽屉(GAP Design kit「框架结构 / 结构=设置」)。
2624
2955
  - 需要用户完成或放弃的聚焦任务改用 `Dialog`。
2625
2956
  - 需要深链接指向的详情改用独立详情页,不得用抽屉承接。
2626
2957
 
@@ -2629,8 +2960,8 @@ Table 的单列定义
2629
2960
  **禁止 / 使用边界。**
2630
2961
  - 不得把深链接指向抽屉状态。
2631
2962
  - 禁止把关闭动作的文案写成「返回」。
2632
- - 不得在抽屉内再打开第二个抽屉或对话框。
2633
- - 不得承载帮助、附件预览一类辅助性面板 —— 那些走 `Sheet`;全局设置是唯一例外,它由 `ApplicationPrimaryNavigation` 的 settings 动作以 `kind='drawer'` 打开。
2963
+ - 不得在抽屉内再打开第二个抽屉、对话框或侧板。模态之上至多再叠一层确认框(`AlertDialog`)或选择器(`PeoplePickerDialog`),更深的嵌套一律禁止(06 · D-3):抽屉里的删除必须经 `AlertDialog` 确认,确认框直接叠在抽屉之上,不得为此先关抽屉。
2964
+ - 不得承载帮助、附件预览一类辅助性面板 —— 那些走 `Sheet`;也不得承载全局设置 —— 它是二级导航里的设置模块。
2634
2965
 
2635
2966
  ### DropdownMenu
2636
2967
 
@@ -2642,6 +2973,10 @@ Table 的单列定义
2642
2973
  ⚠ **Page Mode Switch 绝不能被折叠进来。** 它必须始终可见 ——
2643
2974
  这是 Shell 契约的硬性要求,不是布局偏好。
2644
2975
 
2976
+ 键盘打开(Enter / 空格 / ↓)高亮首个可用项,↑ 高亮末项,鼠标打开不预先高亮;
2977
+ Tab 收起菜单。Esc 关闭或选中后焦点回到 `trigger` —— 选中时先归还焦点再调
2978
+ `onSelect`,在 `onSelect` 里打开的 `AlertDialog` 关闭后焦点因此回到触发器。
2979
+
2645
2980
  **Props**
2646
2981
 
2647
2982
  | prop | 类型 | 必填 | 说明 |
@@ -2679,7 +3014,7 @@ DropdownMenu 的单个条目。
2679
3014
  - 查询工具栏中的筛选维度改用 `ApplicationFilterMenu`。
2680
3015
  - 面板内需要放置任意内容而非条目清单时改用 `Popover`。
2681
3016
 
2682
- **组合约定。** `trigger` 通常是 `iconOnly` 的 `Button`,此时必须同时提供 `aria-label`。该组件向 `trigger` 注入 `aria-expanded` 与 `aria-haspopup`,因此 `trigger` 必须是单个能接收这两个属性的 React 元素;传入纯字符串时属性不会注入,读屏用户无从得知此处有菜单。`separator` 与 `heading` 条目不需要 `value`,其余每个条目的 `value` 必填 —— 缺失时该条目不可选中且不触发 `onSelect`。面板与条目样式与 `ContextMenu`、`Menubar`、`Command` 共用同一套,最小宽度 168px。
3017
+ **组合约定。** `trigger` 通常是 `iconOnly` 的 `SystemButton`,此时必须同时提供 `aria-label`。该组件向 `trigger` 注入 `aria-expanded` 与 `aria-haspopup`,因此 `trigger` 必须是单个能接收这两个属性的 React 元素;传入纯字符串时属性不会注入,读屏用户无从得知此处有菜单。`separator` 与 `heading` 条目不需要 `value`,其余每个条目的 `value` 必填 —— 缺失时该条目不可选中且不触发 `onSelect`。面板与条目样式与 `ContextMenu`、`Menubar`、`Command` 共用同一套,最小宽度 168px。键盘打开(Enter / 空格 / ↓)高亮首个可用项,↑ 高亮末项,鼠标打开不预先高亮;Tab 收起菜单。Esc 关闭或选中后焦点回到 `trigger`,且选中时先归还焦点再调 `onSelect` —— 在 `onSelect` 里打开 `AlertDialog` 是既定用法,对话框关闭后焦点回到触发器,调用方不得再自行管理这段焦点。
2683
3018
 
2684
3019
  **禁止 / 使用边界。**
2685
3020
  - 不得把 Page Mode Switch 折叠进本组件 —— 它必须始终可见,这是 Shell 契约的硬性要求。
@@ -2719,7 +3054,7 @@ DropdownMenu 的单个条目。
2719
3054
  - 需要在面板内执行动作或提交内容改用 `Popover`。
2720
3055
  - 完整的记录详情改用 `Drawer` 或独立详情页。
2721
3056
 
2722
- **组合约定。** 该组件永远只是补充。悬停对键盘用户与触屏用户不可用,因此同样的信息必须能通过点击或详情视图获得 —— 这条由调用方保证,组件本身无法约束。`content` 只放只读预览,动作入口留在行尾或详情中。`trigger` 应是行内元素,该组件的锚点包装为 `inline-flex`,不改变所在文本行的排版。宽度由 `width` 控制,超出高度时面板内部滚动。
3057
+ **组合约定。** 该组件永远只是补充。触发器获得键盘焦点时同样打开、焦点离开即关闭,Esc 随时可关且与库内其他浮层共用 Esc 层级栈;但面板与触发器没有可访问关联,读屏不播报,触屏上也无从悬停,因此同样的信息必须能通过点击或详情视图获得 —— 这条由调用方保证,组件本身无法约束。`content` 只放只读预览,动作入口留在行尾或详情中。`trigger` 应是行内元素,该组件的锚点包装为 `inline-flex`,不改变所在文本行的排版。宽度由 `width` 控制,超出高度时面板内部滚动。
2723
3058
 
2724
3059
  **禁止 / 使用边界。**
2725
3060
  - 不得让本组件成为某项信息的唯一入口。
@@ -2734,7 +3069,7 @@ DropdownMenu 的单个条目。
2734
3069
  锚定式浮层面板 —— 筛选器、呈现设置、日期选择器。
2735
3070
 
2736
3071
  ⚠ **呈现设置面板必须按当前呈现方式命名**
2737
- (列设置 / 卡片设置 / 看板设置 / 日历设置 / 图表设置 / 时间轴设置),
3072
+ (列设置 / 列表设置 / 卡片设置 / 看板设置 / 日历设置 / 图表设置 / 时间轴设置),
2738
3073
  禁止通用的「视图设置」。
2739
3074
 
2740
3075
  ⚠ **呈现设置不得改变**搜索、筛选、业务视图或页面模式 ——
@@ -2743,11 +3078,15 @@ DropdownMenu 的单个条目。
2743
3078
  共享的全局动作弹层(720px 宽、20px 圆角、680px 最高)
2744
3079
  由 `ApplicationGlobalActionPanel` 承载,不要用本组件手工拼装。
2745
3080
 
3081
+ 关闭时焦点若在面板内(Esc,或面板内的控件经 `onOpenChange(false)` 收起),
3082
+ 焦点回到 `trigger`。
3083
+
2746
3084
  **Props**
2747
3085
 
2748
3086
  | prop | 类型 | 必填 | 说明 |
2749
3087
  |---|---|:---:|---|
2750
- | `trigger` | `ReactNode` | 否 | 触发元素 |
3088
+ | `trigger` | `ReactNode` | 否 | 触发元素。组件向它注入 `aria-expanded`,须为单个能接收该属性的 React 元素 |
3089
+ | `anchor` | `HTMLElement \| null` | 否 | 外部锚点。触发器由别的组件渲染、只经回调交出元素时传入(例如 `TopNavigationPrimaryBar` 的 `onAppSwitch` / `onAccount`):面板贴它定位, 点它不算外部点击(开合由它自己的点击切换),收起时焦点还给它;Tab 顺序按 「锚点 → 面板 → 锚点之后的元素」接上,面板在 DOM 中不必紧跟锚点。 传了本项即不再渲染 `trigger`,组件根也不占布局;`aria-expanded` 不会注入, 须由渲染该触发器的组件输出。必须受控使用(`open` + `onOpenChange`)。 |
2751
3090
  | `open` | `boolean` | 否 | 受控开合状态 |
2752
3091
  | `defaultOpen` | `boolean` | 否 | 非受控初始开合状态 |
2753
3092
  | `onOpenChange` | `(open: boolean) => void` | 否 | 开合状态变化回调。点击外部关闭时也会触发 |
@@ -2760,16 +3099,16 @@ DropdownMenu 的单个条目。
2760
3099
 
2761
3100
  **用途。** 锚定式浮层面板 —— 筛选器、呈现设置、日期选择器。
2762
3101
 
2763
- **何时使用。** 当面板内容需要贴近触发器、且背景仍应保持可交互时,该组件是默认选择。默认宽度 320px,空间不足时自动翻转到对侧并限制高度,永不超出有效视口。呈现设置面板必须按当前呈现方式命名 —— 列设置 / 卡片设置 / 看板设置 / 日历设置 / 图表设置 / 时间轴设置。
3102
+ **何时使用。** 当面板内容需要贴近触发器、且背景仍应保持可交互时,该组件是默认选择。默认宽度 320px,空间不足时自动翻转到对侧并限制高度,永不超出有效视口。呈现设置面板必须按当前呈现方式命名 —— 列设置 / 列表设置 / 卡片设置 / 看板设置 / 日历设置 / 图表设置 / 时间轴设置。
2764
3103
 
2765
3104
  **何时改用其他组件。**
2766
3105
  - 条目清单式的低频动作改用 `DropdownMenu`。
2767
3106
  - 表单与筛选行中的取值改用 `Select`,需要输入筛选改用 `Combobox`。
2768
3107
  - 查询工具栏的筛选维度改用 `ApplicationFilterMenu`。
2769
- - 消息 / 待办 / 运行总览 / 风险预警四个全局动作共享的弹层改用 `ApplicationGlobalActionPanel`,其 720px 宽、20px 圆角、680px 最高的几何已登记。
3108
+ - 消息 / 待办 / 总览 / 风险预警四个全局动作共享的弹层改用 `ApplicationGlobalActionPanel`,其 720px 宽、20px 圆角、680px 最高的几何已登记。
2770
3109
  - 用户必须完成或放弃的任务改用 `Dialog`。
2771
3110
 
2772
- **组合约定。** 该组件是非模态浮层:不锁背景滚动、不陷阱焦点,Esc 与外部点击都会关闭并触发 `onOpenChange`。受控模式下 `open` 与 `onOpenChange` 必须成对出现。触发器包装元素已带 `aria-expanded`,调用方不得在 `trigger` 上再写一个。`radius` 应传 token 而非字面值。作为「更多筛选」入口时,生效条件必须回写到 `ApplicationQueryToolbar` 第三行的筛选标签行。层级由已登记的浮层 z-index 承担,调用方不得自行设置。
3111
+ **组合约定。** 该组件是非模态浮层:不锁背景滚动、不陷阱焦点,Esc、外部点击与焦点离开(焦点从 `trigger` 或面板移到两者之外,如 Tab 出去)都会关闭并触发 `onOpenChange`;焦点离开引起的关闭不归还焦点。关闭时焦点若在面板内(Esc,或面板内的控件经 `onOpenChange(false)` 收起),焦点回到 `trigger`,因此在 `Dialog` 内使用时焦点不会逃出对话框。受控模式下 `open` 与 `onOpenChange` 必须成对出现。组件向 `trigger` 注入 `aria-expanded`,因此 `trigger` 必须是单个能接收该属性的 React 元素,调用方不得在 `trigger` 上再写一个;传入纯字符串时属性不会注入。触发器由别的组件渲染、只经回调交出元素时(`TopNavigationPrimaryBar` 的 `onAppSwitch` / `onAccount`),把该元素传给 `anchor` 并受控使用:面板贴它定位,点它不算外部点击,收起时焦点还给它,Tab 从它直接进入面板、从面板末项接着走它之后的元素;此时不渲染 `trigger`、组件根不占布局,`aria-expanded` 由渲染触发器的那个组件输出。`radius` 应传 token 而非字面值。作为「更多筛选」入口时,生效条件必须回写到 `ApplicationQueryToolbar` 第三行的筛选标签行。层级由已登记的浮层 z-index 承担,调用方不得自行设置。
2773
3112
 
2774
3113
  **禁止 / 使用边界。**
2775
3114
  - 不得用本组件手工拼装四个全局动作的共享弹层。
@@ -2781,8 +3120,10 @@ DropdownMenu 的单个条目。
2781
3120
 
2782
3121
  `import { Sheet } from '@moheng-design/ui'` · 契约 `contracts/foundation/feedback-overlay/sheet.ts`
2783
3122
 
2784
- 从任意边缘滑出的面板,用于**辅助性内容** ——
2785
- 从一级导航打开的「设置」面板、帮助面板、附件预览。
3123
+ 从任意边缘滑出的面板,用于**辅助性内容** —— 帮助面板、附件预览。
3124
+
3125
+ ⚠ **全局设置也不属于这里。** 一级导航的「设置」让 `ApplicationSecondaryNavigation`
3126
+ 换成设置模块(GAP Design kit「框架结构 / 结构=设置」),不打开任何侧板。
2786
3127
 
2787
3128
  ⚠ **业务对象详情不属于这里。** 详情用 `Drawer`(680px)
2788
3129
  或独立详情页 —— Sheet 在结构上比 Drawer 更轻,不承载业务记录。
@@ -2800,22 +3141,24 @@ DropdownMenu 的单个条目。
2800
3141
 
2801
3142
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `title` 已被本组件重新定义或移除。
2802
3143
 
2803
- **用途。** 从任意边缘滑出的面板,用于辅助性内容 —— 从一级导航打开的「设置」面板、帮助面板、附件预览。
3144
+ **用途。** 从任意边缘滑出的面板,用于辅助性内容 —— 帮助面板、附件预览。
2804
3145
 
2805
- **何时使用。** 当内容是全局性的辅助配置或参考信息、不属于任何一条业务记录时,该组件是默认选择。四个 `side` 方向均实际生效:左右向时 `size` 为宽度,上下向时为高度,正交方向一律铺满。默认尺寸 420px。
3146
+ **何时使用。** 当内容是辅助性的参考信息、不属于任何一条业务记录时,该组件是默认选择。四个 `side` 方向均实际生效:左右向时 `size` 为宽度,上下向时为高度,正交方向一律铺满。默认尺寸 420px。
2806
3147
 
2807
3148
  **何时改用其他组件。**
2808
3149
  - 业务对象详情改用 `Drawer`(680px)或独立详情页 —— 本组件在结构上比抽屉更轻,不承载业务记录。
2809
3150
  - 已登记的业务详情结构改用 `ApplicationDetailDrawer`。
2810
3151
  - 需要用户完成或放弃的聚焦任务改用 `Dialog`。
2811
- - 消息 / 待办 / 运行总览 / 风险预警四个全局动作改用 `ApplicationGlobalActionPanel`;设置不走该面板,走本组件或 `Drawer`。
3152
+ - 消息 / 待办 / 总览 / 风险预警四个全局动作改用 `ApplicationGlobalActionPanel`。
3153
+ - 全局设置改用 `ApplicationSecondaryNavigation` 的设置模块 —— 一级导航的设置动作让二级导航整带换成设置模块,不打开本组件(GAP Design kit「框架结构 / 结构=设置」)。
3154
+ - 工具栏的呈现设置面板(列设置、看板设置等)改用 `Popover`,与更多筛选同一承载(07 · C-7)。
2812
3155
 
2813
- **组合约定。** 该组件与 `Dialog`、`AlertDialog`、`Drawer` 共用同一个模态基座,因此自带 Esc 关闭、焦点陷阱、焦点恢复与背景滚动锁定。该组件没有固定底部动作区 —— 需要提交按钮常驻底部的载体改用 `Drawer`。主体区域内部滚动,标题栏高度对齐内容区标题栏。全局设置在整个产品中只能有一个入口,该入口打开本组件或 `Drawer`,不得同时存在第二处。
3156
+ **组合约定。** 该组件与 `Dialog`、`AlertDialog`、`Drawer` 共用同一个模态基座,因此自带 Esc 关闭、焦点陷阱、焦点恢复与背景滚动锁定。该组件没有固定底部动作区 —— 需要提交按钮常驻底部的载体改用 `Drawer`。主体区域内部滚动,标题栏高度对齐内容区标题栏。全局设置在整个产品中只有一个入口(一级导航的设置动作),它打开的是二级导航里的设置模块,不经本组件承载。
2814
3157
 
2815
3158
  **禁止 / 使用边界。**
2816
3159
  - 不得用本组件承载业务对象详情。
2817
3160
  - 禁止在本组件内放置需要固定在底部的提交动作。
2818
- - 不得为「设置」建立第二个入口。
3161
+ - 不得用本组件承载全局设置,也不得为「设置」建立第二个入口。
2819
3162
  - 不得在本组件之上再叠加抽屉或对话框。
2820
3163
 
2821
3164
  ### Sonner
@@ -2836,7 +3179,7 @@ DropdownMenu 的单个条目。
2836
3179
  |---|---|:---:|---|
2837
3180
  | `toasts` | `SonnerToast[]` | 是 | 当前显示的提示集合。由调用方持有并维护 |
2838
3181
  | `onDismiss` | `(id: string) => void` | 否 | 消除回调。自动消失与点击关闭都会触发 |
2839
- | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | 否 | 堆栈位置 |
3182
+ | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | 否 | 堆栈位置,默认 `top-right`(07 · C-20)。 右下角会盖住批量栏、弹窗页脚一类底部动作条,因此不作默认 |
2840
3183
 
2841
3184
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
2842
3185
 
@@ -2862,8 +3205,9 @@ Sonner 的单条提示
2862
3205
  - 需要用户确认的不可逆动作改用 `AlertDialog`。
2863
3206
  - 需要用户填写或选择的内容改用 `Dialog`。
2864
3207
  - 结果集为空改用 `Empty`。
3208
+ - 只是要在页面里弹一条提示、不需要自己持有提示集合时,改用 `SonnerProvider` 挂在应用根、页面里调 `useToast()`,不必再自建一层 context。
2865
3209
 
2866
- **组合约定。** 整个应用只挂一个本组件,位置固定在应用根,`position` 决定四个角中的一个,默认 `bottom-right`。`toasts` 由调用方持有并维护;`onDismiss` 必须真的把该 `id` 从数组中移除,否则计时到期后提示不会消失。`action` 只放可选的加速器(`撤销`),错过它不得造成损失。`SonnerToast.id` 必须稳定唯一,复用同一个 id 会使计时错乱。四个 `tone` 决定左侧色条,单条宽度约束在 280–420px。
3210
+ **组合约定。** 整个应用只挂一个本组件(`SonnerProvider` 内部渲染的那一个也算),位置固定在应用根,`position` 决定四个角中的一个,默认 `top-right` —— 右下角会在提示停留的 5 秒里盖住批量栏、弹窗页脚一类底部动作条,因此不作默认。`toasts` 由调用方持有并维护;`onDismiss` 必须真的把该 `id` 从数组中移除,否则计时到期后提示不会消失。`action` 只放可选的加速器(`撤销`),错过它不得造成损失。`SonnerToast.id` 必须稳定唯一,复用同一个 id 会使计时错乱。四个 `tone` 决定左侧色条,单条宽度约束在 280–420px。
2867
3211
 
2868
3212
  **禁止 / 使用边界。**
2869
3213
  - 不得用 toast 承载提交失败或任何用户必须处理的信息。
@@ -2871,6 +3215,52 @@ Sonner 的单条提示
2871
3215
  - 不得把 `duration` 设为 0 使提示常驻 —— 不会自己消失的提示不是 toast。
2872
3216
  - 不得在单条提示内放置表单、多步动作或需要滚动的内容。
2873
3217
 
3218
+ ### SonnerProvider
3219
+
3220
+ `import { SonnerProvider } from '@moheng-design/ui'` · 契约 `contracts/foundation/feedback-overlay/sonner-provider.ts`
3221
+
3222
+ `Sonner` 的调用入口 —— 挂在应用根,子树里任何位置用 `useToast()` 弹出提示。
3223
+
3224
+ 内部持有提示集合并渲染唯一的 `Sonner`(07 · C-10)。
3225
+
3226
+ 此前 `Sonner` 只有受控用法:「全应用只挂一个」+「`toasts` 由调用方持有」意味着
3227
+ 每个项目都要先自建一层 context 才能在页面里弹一条提示(05 · P2-8)。本组件就是
3228
+ 那层 context,收进库内后各项目不再各写一份。受控的 `Sonner` 保留不变。
3229
+
3230
+ **Props**
3231
+
3232
+ | prop | 类型 | 必填 | 说明 |
3233
+ |---|---|:---:|---|
3234
+ | `children` | `ReactNode` | 否 | 应用根的子树。其中任何位置都可以用 `useToast()` |
3235
+ | `position` | `'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left'` | 否 | 堆栈位置,原样传给内部的 `Sonner`。默认 `top-right`,理由见 `Sonner` 的 `position` |
3236
+ | `className` | `string` | 否 | 追加到内部 `Sonner` 堆栈根上的类名 |
3237
+
3238
+ **`ToastFunction`**
3239
+
3240
+ `useToast()` 的返回值。本身可调用:`toast({ title: '已保存', tone: 'success' })`
3241
+ 弹出一条提示并返回其 id。
3242
+
3243
+ | prop | 类型 | 必填 | 说明 |
3244
+ |---|---|:---:|---|
3245
+ | `dismiss` | `(id: string) => void` | 是 | 按 id 提前消除一条提示,如点了「撤销」之后。自动消失与关闭按钮不需要调它 |
3246
+
3247
+ **用途。** `Sonner` 的调用入口:挂在应用根,内部持有提示集合并渲染唯一的 `Sonner`,子树里任何位置用 `useToast()` 取到 `toast()` 即可弹出一条提示。
3248
+
3249
+ **何时使用。** 应用需要在页面里弹出 toast 时,该组件是默认选择,必须挂在应用根、包住全部页面。页面里写 `const toast = useToast()`,再调 `toast({ title: '已保存', tone: 'success' })`;返回值是该条提示的 id,`toast.dismiss(id)` 可提前消除它。入参与 `SonnerToast` 相同,只是不带 `id` —— id 由本组件生成。`position` 原样传给内部的 `Sonner`,默认 `top-right`。
3250
+
3251
+ **何时改用其他组件。**
3252
+ - 需要自己持有提示集合(如从服务端推送恢复、跨标签页同步)时改用受控的 `Sonner`,二者不得同时挂载。
3253
+ - 用户必须读到并处理的失败改用 `Alert`,就地呈现在受影响区域顶部。
3254
+ - 需要用户确认的不可逆动作改用 `AlertDialog`。
3255
+
3256
+ **组合约定。** 整个应用只挂一个本组件;它渲染的 `Sonner` 即全应用唯一的提示堆栈,因此不得再另挂 `Sonner`。`useToast()` 必须在本组件的子树内调用,否则直接抛错 —— 静默吞掉的提示比报错更难查。`toast()` 函数引用在本组件存活期间保持稳定,可放进 effect 或 `useCallback` 的依赖。提示内容的约束与 `Sonner` 完全相同:`title` 是已完成事实的陈述,`action` 只放可选的加速器(`撤销`),点了加速器之后应调 `toast.dismiss(id)` 收起该条。
3257
+
3258
+ **禁止 / 使用边界。**
3259
+ - 不得嵌套挂载本组件,也不得与受控的 `Sonner` 同时挂载 —— 两个堆栈会叠在同一个角上。
3260
+ - 不得用 `toast()` 承载提交失败或任何用户必须处理的信息。
3261
+ - 禁止在本组件之外调用 `useToast()`,也不得为绕开报错自建一层同名 context。
3262
+ - 不得在渲染过程中调用 `toast()`,只在事件处理或 effect 中调用。
3263
+
2874
3264
  ### Spinner
2875
3265
 
2876
3266
  `import { Spinner } from '@moheng-design/ui'` · 契约 `contracts/foundation/feedback-overlay/spinner.ts`
@@ -2933,14 +3323,14 @@ Sonner 的单条提示
2933
3323
 
2934
3324
  **用途。** 悬停或聚焦时出现的短标签,用于为纯图标控件命名 —— 五个全局动作触发器、工具栏图标按钮。
2935
3325
 
2936
- **何时使用。** 当控件没有可见文字、需要一个名称时,该组件是默认选择。28px 高、8px 圆角、背景为 92% 文字色。显示延迟 220ms,避免在密集工具栏上划过时连闪一串;悬停与聚焦两种方式都会触发。
3326
+ **何时使用。** 当控件没有可见文字、需要一个名称时,该组件是默认选择。28px 高、8px 圆角、背景为 92% 文字色。显示延迟 220ms,避免在密集工具栏上划过时连闪一串;悬停与聚焦两种方式都会触发,Esc 关闭提示且不移动焦点,与库内其他浮层共用 Esc 层级栈(上层先响应)。
2937
3327
 
2938
3328
  **何时改用其他组件。**
2939
3329
  - 富预览内容改用 `HoverCard`。
2940
3330
  - 需要在面板内执行动作改用 `Popover`。
2941
3331
  - 需要长期可见的说明改用 `Field` 的说明文字或 `Alert`。
2942
3332
 
2943
- **组合约定。** 工具提示不是可访问名称 —— 被提示的控件必须同时带真实的 `aria-label`,纯图标 `Button`(`iconOnly` 为 true)尤其如此,且两者文案应一致。`content` 是控件的名称而非操作说明,写作 2–4 字裸名词短语(`列设置`、`关闭`)。`children` 应是单个可聚焦控件;该组件的锚点包装为 `inline-flex`,不改变所在行的排版。提示面板不接收指针事件,因此它绝不会挡住刚刚触发它的按钮,但也意味着其中的任何内容都不可点击。
3333
+ **组合约定。** 工具提示不是可访问名称 —— 被提示的控件必须同时带真实的 `aria-label`,纯图标 `SystemButton`(`iconOnly` 为 true)尤其如此,且两者文案应一致。`content` 是控件的名称而非操作说明,写作 2–4 字裸名词短语(`列设置`、`关闭`)。`children` 应是单个可聚焦控件;该组件的锚点包装为 `inline-flex`,不改变所在行的排版。提示面板不接收指针事件,因此它绝不会挡住刚刚触发它的按钮,但也意味着其中的任何内容都不可点击。
2944
3334
 
2945
3335
  **禁止 / 使用边界。**
2946
3336
  - 不得用本组件替代控件自身的 `aria-label`。
@@ -2950,6 +3340,59 @@ Sonner 的单条提示
2950
3340
 
2951
3341
  ## Application Atomic
2952
3342
 
3343
+ ### ApplicationDateRangeFilter
3344
+
3345
+ `import { ApplicationDateRangeFilter } from '@moheng-design/ui'` · 契约 `contracts/application-atomic/application-date-range-filter.ts`
3346
+
3347
+ 查询工具栏主控制行中的**日期区间**快捷筛选,与 `ApplicationFilterMenu` 同为一个
3348
+ 常驻维度,放进 `ApplicationQueryToolbar` 的 `commonFilters`。
3349
+
3350
+ 触发器与 `ApplicationFilterMenu` 同高同壳,生效时回显「接收时间:2026-07-01 – 2026-07-28」。
3351
+ 面板里是起止两张 `Calendar` 月格,由「应用」提交、「清空」撤销 —— 选到一半不生效。
3352
+
3353
+ ⚠ **已生效的区间必须回写到工具栏第三行的筛选标签行**(`appliedTags`),且标签可移除。
3354
+ 与 `ApplicationFilterMenu` 同一条规矩:筛选状态只存在于触发器上是不合规的。
3355
+
3356
+ **Props**
3357
+
3358
+ | prop | 类型 | 必填 | 说明 |
3359
+ |---|---|:---:|---|
3360
+ | `label` | `ReactNode` | 是 | 维度名称,显示在触发器上,如「接收时间」 |
3361
+ | `labelText` | `string` | 否 | 维度名称的纯文本,用于触发器回显与可访问名。 `label` 为非字符串时**必须**提供,否则回显为 `[object Object]`。 |
3362
+ | `value` | `DateRangeValue` | 否 | 受控值。两端都缺省即未生效 |
3363
+ | `onValueChange` | `(value: DateRangeValue) => void` | 否 | 「应用」提交时的回调。「清空」提交 `{}` |
3364
+ | `disabled` | `boolean` | 否 | 禁用 |
3365
+ | `today` | `Date` | 否 | 「今天」,透传给两张 `Calendar` |
3366
+
3367
+ 继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `defaultValue`、`onChange` 已被本组件重新定义或移除。
3368
+
3369
+ **`DateRangeValue`**
3370
+
3371
+ 日期区间。两端均为本地时区 ISO `yyyy-mm-dd`,缺省一端表示该端不限
3372
+
3373
+ | prop | 类型 | 必填 | 说明 |
3374
+ |---|---|:---:|---|
3375
+ | `start` | `string` | 否 | 起始日期(含) |
3376
+ | `end` | `string` | 否 | 结束日期(含) |
3377
+
3378
+ **用途。** 查询工具栏主控制行中的日期区间快捷筛选,承载**一个**日期维度(接收时间、开票日期)的起止区间。
3379
+
3380
+ **何时使用。** 结果集需要按某个日期维度的区间筛选、且该维度高频使用时,必须使用本组件。触发器与 `ApplicationFilterMenu` 同高同壳,生效时回显「维度名:起 – 止」;面板里起止各一张 `Calendar`,选择是草稿,「应用」提交、「清空」撤销。值为 `{ start?, end? }`,两端都是本地时区 ISO `yyyy-mm-dd`,缺省一端表示该端不限。
3381
+
3382
+ **何时改用其他组件。**
3383
+ - 取值为有限枚举的维度:改用 `ApplicationFilterMenu`。
3384
+ - 表单里的单个日期字段:改用 `DateInput`。
3385
+ - 低频的日期维度:收进 `moreFilters` 的 `ApplicationFilterList` 面板,不常驻工具栏。
3386
+ - 整页按日期浏览:改用 `pageMode` 为 `CALENDAR` 的日历承载面。
3387
+
3388
+ **组合约定。** 该组件必须作为 `ApplicationQueryToolbar` 的 `commonFilters` 内容出现,与 `ApplicationFilterMenu` 合计常驻不超过 3 个。生效区间必须由调用方回写到 `appliedTags`(标签文案如「接收时间:2026-07-01 – 2026-07-28」),并在 `onRemoveTag` 里把区间清回 `{}`。`label` 为非字符串时必须提供 `labelText`,它同时是触发器回显与可访问名的来源。结束日期早于开始日期时「应用」禁用,组件不替调用方交换两端。区间两端都是闭区间(含当天),调用方换算成接口参数时自行补足时分。
3389
+
3390
+ **禁止 / 使用边界。**
3391
+ - 不得让已生效的区间只停留在触发器上而不回写筛选标签行。
3392
+ - 不得在面板外再包一层 `Popover` 或 `DropdownMenu`,面板自带定位与外点击关闭。
3393
+ - 不得放进 `ApplicationPageHeader` —— 上下文区禁止出现筛选。
3394
+ - 禁止在选到一半时发起查询,区间只经「应用」提交。
3395
+
2953
3396
  ### ApplicationFilterMenu
2954
3397
 
2955
3398
  `import { ApplicationFilterMenu } from '@moheng-design/ui'` · 契约 `contracts/application-atomic/application-filter-menu.ts`
@@ -2989,7 +3432,7 @@ Sonner 的单条提示
2989
3432
 
2990
3433
  **用途。** 查询工具栏主控制行中的常驻快捷筛选触发器,承载**一个**高频筛选维度的取值。
2991
3434
 
2992
- **何时使用。** 该维度在结果集上高频使用、取值为短词且数量有限时,必须选用本组件。面板已登记 180px 最小宽与 280px 最高,取值控制在 8 项以内方能一屏读完。工具栏内至多常驻 2–3 个,其余维度一律下沉到「更多筛选」。触发器高 32px、圆角 16px,与同排的 `SearchField` 读作一行。
3435
+ **何时使用。** 该维度在结果集上高频使用、取值为短词且数量有限时,必须选用本组件。面板已登记 180px 最小宽与 280px 最高,取值控制在 8 项以内方能一屏读完。工具栏内至多常驻 2–3 个,其余维度一律下沉到「更多筛选」。触发器高 32px、圆角 12px,与同排的 `SearchField` 读作一行。
2993
3436
 
2994
3437
  **何时改用其他组件。**
2995
3438
  - 低频维度、或需要一次性提交多个维度:改用 `ApplicationFilterList`,它是「更多筛选」的面板主体,持有草稿并由「应用」提交。
@@ -2997,7 +3440,8 @@ Sonner 的单条提示
2997
3440
  - 选项极多、或密集的表格行内编辑器:改用 `NativeSelect`。
2998
3441
  - 需要输入即筛选:改用 `Combobox`。
2999
3442
  - 局部显示选择(密度、对齐方式、局部视图标记):改用 `ToggleGroup`。
3000
- - 键盘优先的全局搜索与执行:改用 `Command`,且必须放进 `Dialog`。
3443
+ - 键盘优先的全局搜索与执行:改用 `Command` 的 `dialog` 形态。
3444
+ - 日期区间维度:改用 `ApplicationDateRangeFilter`,同样放进 `commonFilters`。
3001
3445
 
3002
3446
  **组合约定。** 该组件必须作为 `ApplicationQueryToolbar` 的 `commonFilters` 内容出现,传 2–3 个;不得独立散落在页面其他位置。该组件只持有本维度的取值,已生效条件必须由调用方回写到 `ApplicationQueryToolbar` 的 `appliedTags`,并实现 `onRemoveTag` 与 `onResetTags`;筛选状态只存在于菜单内部是不合规的。`ApplicationFilterOption.label` 传入非字符串时,必须同时提供 `labelText`,否则触发器回显退化为 `[object Object]`。`multiple` 为 true 时 `value` 与 `defaultValue` 必须是数组,为 false 时必须是字符串;单选状态下再次点选当前值会清空该维度,`onValueChange` 必须能接收空字符串。面板自带定位、碰撞翻转与外点击关闭,调用方不得再包一层 `Popover` 或 `DropdownMenu`。`count` 必须与数据展示区当前口径下的结果数一致。该组件不自带外边距,横向间距由工具栏的 `--ui-control-gap` 负责。
3003
3447
 
@@ -3056,13 +3500,19 @@ Sonner 的单条提示
3056
3500
 
3057
3501
  `import { ListTablePagination } from '@moheng-design/ui'` · 契约 `contracts/application-atomic/list-table-pagination.ts`
3058
3502
 
3059
- 列表 / 表格分页 —— 结果区间、总数、每页条数与翻页步进。
3503
+ 列表 / 表格分页 —— 摘要、每页条数、页码窗口与跳页。
3060
3504
  数据展示区的标准页脚,LIST 页面模式的默认配置。
3061
3505
 
3062
- ⚠ **分页语义必须跨 Page Mode 与 Business View 切换存活**,
3063
- 从详情返回时也必须还原 —— 规范要求恢复来源上下文。
3506
+ 形态按 GAP Design kit「分页行」(业财平台 round-01 · pagination/structure 裁决,2026-11-10):
3507
+ 左侧摘要「每页 N 条,共 Z 条数据」12/20 三级文字色,右侧依次为每页条数选择器、
3508
+ Foundation `Pagination`(首页 · 上一页 · 页码窗口 · 下一页 · 末页)与「第 [ ] 页」跳页框,
3509
+ 控件一律 32 高、圆角 12、间隔 4。**本组件包含 `Pagination`**,两者不再是替代关系。
3510
+
3511
+ ⚠ **分页状态按业务视图各记一份**:切换 Business View 时回到该视图上次所在的页,
3512
+ 切换 Page Mode 与从详情返回时保持当前页 —— 规范要求恢复来源上下文。
3513
+ 搜索、筛选、排序变化时复位到第 1 页(07 · C-13)。
3064
3514
 
3065
- 没有总数与每页条数需求时,用 Foundation `Pagination`。
3515
+ 没有总数与每页条数需求时,直接用 Foundation `Pagination`。
3066
3516
 
3067
3517
  **Props**
3068
3518
 
@@ -3072,20 +3522,21 @@ Sonner 的单条提示
3072
3522
  | `pageSize` | `number` | 否 | 每页条数 |
3073
3523
  | `total` | `number` | 否 | 结果总数。用于计算区间与总页数 |
3074
3524
  | `pageSizeOptions` | `number[]` | 否 | 每页条数的可选值 |
3525
+ | `showJumper` | `boolean` | 否 | 是否显示「第 [ ] 页」跳页框,默认 `true`(kit 分页行恒有)。回车提交,越界时夹到 1 与总页数之间,提交后清空。总页数很少、跳页没有意义时可传 `false` |
3075
3526
  | `onPageChange` | `(page: number) => void` | 否 | 页码变化回调 |
3076
3527
  | `onPageSizeChange` | `(pageSize: number) => void` | 否 | 每页条数变化回调。变更后通常应重置到第 1 页,由调用方决定 |
3077
3528
 
3078
3529
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
3079
3530
 
3080
- **用途。** 数据展示区的标准页脚 —— 结果区间、结果总数、每页条数与翻页步进。
3531
+ **用途。** 数据展示区的标准页脚 —— 摘要、每页条数、页码窗口与跳页。
3081
3532
 
3082
- **何时使用。** 结果集同时具备总数与每页条数需求时必须使用本组件,它是 LIST 页面模式的默认配置。形态固定为「第 X–Y 条 / 共 Z 条」加每页条数选择器加上一页 / 位置 / 下一页三件。每页条数默认档为 20 / 50 / 100,业务确有别的档位时通过 `pageSizeOptions` 覆盖。
3533
+ **何时使用。** 结果集同时具备总数与每页条数需求时必须使用本组件,它是 LIST 页面模式的默认配置。形态按 GAP Design kit「分页行」固定为:左侧「每页 N 条,共 Z 条数据」摘要(12/20 三级文字色),右侧依次为每页条数选择器、`Pagination`(首页 · 上一页 · 页码窗口 · 下一页 · 末页)与「第 [ ] 页」跳页框,控件一律 32 高、圆角 12、间隔 4。跳页框回车提交,输入越界时夹到 1 与总页数之间,提交后清空;总页数很少时可传 `showJumper={false}` 隐去。每页条数默认档为 20 / 50 / 100,业务确有别的档位时通过 `pageSizeOptions` 覆盖。
3083
3534
 
3084
3535
  **何时改用其他组件。**
3085
- - 既无总数也无每页条数需求:改用 `Pagination`,它是裸页码步进器,带首页 + 当前页 ±1 + 末页的页码窗口。
3086
- - 两者是替代关系而非包含关系:同一个数据展示区内只能出现其中一个。
3536
+ - 既无总数也无每页条数需求:改用 `Pagination`,它是本组件内部的页码区,可以单独使用。
3537
+ - 两者是包含关系:本组件已经渲染了 `Pagination`,同一个数据展示区内不得再另放一个。
3087
3538
 
3088
- **组合约定。** 该组件必须放进 `ApplicationDataDisplay` 的 `pagination` 槽位,固定在区域底部;该槽位不随 `state` 隐藏,因此 `state` 不为 `ready` 时调用方不得传入分页。分页语义必须跨 `pageMode` 与 `businessView` 切换存活,从详情返回时也必须还原 —— 该组件是全受控的,这份状态由调用方持有。`onPageSizeChange` 之后通常应重置到第 1 页,调用方必须显式再调一次 `onPageChange`,组件不代劳。`total` 与 `ApplicationQueryToolbar` 的 `resultSummary` 必须取自同一口径的同一个数,否则页脚与摘要会互相打脸。每页条数选择器内部已复用 `NativeSelect`,调用方不得在旁边再挂一个 `Select`。该组件不自带外边距,与上方结果集的间距由数据展示区负责。
3539
+ **组合约定。** 该组件必须放进 `ApplicationDataDisplay` 的 `pagination` 槽位,固定在区域底部;该槽位不随 `state` 隐藏,因此 `state` 不为 `ready` 时调用方不得传入分页。分页状态按业务视图各记一份:切换 `businessView` 时回到该视图上次所在的页,切换 `pageMode` 与从详情返回时保持当前页;搜索、筛选、排序变化时复位到第 1 页(07 · C-13)。该组件是全受控的,这份状态由调用方持有。`onPageSizeChange` 之后通常应重置到第 1 页,调用方必须显式再调一次 `onPageChange`,组件不代劳。`total` 与 `ApplicationQueryToolbar` 的 `resultSummary` 必须取自同一口径的同一个数,否则页脚与摘要会互相打脸。每页条数选择器内部已复用 `NativeSelect`、页码区已复用 `Pagination`、跳页框已复用 `Input`,调用方不得在旁边再挂一个 `Select`、页码条或跳页输入。该组件不自带外边距,与上方结果集的间距由数据展示区负责。
3089
3540
 
3090
3541
  **禁止 / 使用边界。**
3091
3542
  - 不得在同一数据展示区内出现两处分页控件。
@@ -3100,7 +3551,7 @@ Sonner 的单条提示
3100
3551
  共享的紧凑搜索入口 —— **产品内每一处纯文本搜索**:
3101
3552
  查询工具栏、目录搜索、人员与文件选择器。
3102
3553
 
3103
- 32px 最小高度,16px 圆角,焦点只在外壳表达一次。
3554
+ 32px 最小高度,12px 圆角,白底 1px 描边(GAP Design kit「表单/输入」),焦点只在外壳表达一次。
3104
3555
 
3105
3556
  ⚠ **只在 Enter 时提交。** 规范禁止逐字实时搜索作为默认行为。
3106
3557
 
@@ -3135,9 +3586,9 @@ Sonner 的单条提示
3135
3586
  - 普通单行文本录入:改用 `Input`。
3136
3587
  - 带前后缀或附加按钮的组合输入:改用 `InputGroup`;它是本组件适配的 Foundation 基座,页面不得把它的外壳复制一份充当搜索框。
3137
3588
  - 在已知选项集合内做本地筛选、且不构成一次数据查询:改用 `Combobox`。
3138
- - 键盘优先的全局搜索与命令执行:改用 `Command`,放进 `Dialog`。
3589
+ - 键盘优先的全局搜索与命令执行:改用 `Command` 的 `dialog` 形态。
3139
3590
 
3140
- **组合约定。** `ariaLabel` 是必填项,且必须写明搜索范围(如「搜索监管对象」),不得写成泛泛的「搜索」。`onSubmit` 仅在 Enter 时触发,调用方不得在 `onChange` 里发起查询 —— `onChange` 只用于受控回显。清除按钮同样触发 `onChange`,其事件对象只保证 `target.value` 一个字段,处理函数不得访问其他事件属性。`ApplicationQueryToolbar` 内部已经渲染了一个 `SearchField`,工具栏场景必须走 `searchValue` / `onSearchChange` / `onSearchSubmit` / `searchPlaceholder`,不得再往 `commonFilters` 或 `moreFilters` 里塞第二个;`PeoplePickerDialog` 同理,其搜索由组件自身持有。`ApplicationFilterList` 的 `search` 槽位应当传入本组件。需要提示提交方式时,配一个 `Kbd` 写「Enter」。调用方拥有搜索范围、提交时机与查询数据;布局宽度可以设,颜色、边框、圆角、背景与焦点视觉不得覆盖。该组件不自带外边距。
3591
+ **组合约定。** `ariaLabel` 是必填项,且必须写明搜索范围(如「搜索监管对象」),不得写成泛泛的「搜索」。`onSubmit` 仅在 Enter 时触发,调用方不得在 `onChange` 里发起查询 —— `onChange` 只用于受控回显。清除按钮同样触发 `onChange`,其事件对象只保证 `target.value` 一个字段,处理函数不得访问其他事件属性。`ApplicationQueryToolbar` 内部已经渲染了一个 `SearchField`,工具栏场景必须走 `searchValue` / `onSearchChange` / `onSearchSubmit` / `searchPlaceholder` / `searchAriaLabel`,不得再往 `commonFilters` 或 `moreFilters` 里塞第二个;`PeoplePickerDialog` 同理,其搜索由组件自身持有。`ApplicationFilterList` 的 `search` 槽位应当传入本组件。需要提示提交方式时,配一个 `Kbd` 写「Enter」。调用方拥有搜索范围、提交时机与查询数据;布局宽度可以设,颜色、边框、圆角、背景与焦点视觉不得覆盖。该组件不自带外边距。
3141
3592
 
3142
3593
  **禁止 / 使用边界。**
3143
3594
  - 不得把逐字输入直接接到查询上,实时搜索禁止作为默认行为。
@@ -3172,7 +3623,7 @@ Sonner 的单条提示
3172
3623
  **何时改用其他组件。**
3173
3624
  - 同一应用内的模块切换:改用 `ApplicationModuleSwitcher`,它是应用二级导航的左半部分。
3174
3625
  - 工作台菜单栏的图标条目:改用 `SidebarRailButton`。
3175
- - Content Canvas 内部的垂直导航面(SPLIT 左侧目录、设置导航、模块子导航):改用 `Sidebar`。
3626
+ - Content Canvas 内部的垂直导航面(设置页目录):改用 `Sidebar`;SPLIT 左栏改用 `ApplicationSplitListSidebar`。
3176
3627
  - 通用的「前置槽位 · 标题 + 描述 · 尾部槽位」列表行:改用 `Item`。
3177
3628
  - 触发的是动作而非跳转:改用 `SystemButton`。
3178
3629
 
@@ -3211,18 +3662,18 @@ Sonner 的单条提示
3211
3662
  **何时使用。** 工作台左侧图标栏的导航条目必须使用本组件。图标登记尺寸 20px,标签 12/16 且限宽 52px、超长省略,激活态是淡强调色洗并渲染 `aria-current="page"`。
3212
3663
 
3213
3664
  **何时改用其他组件。**
3214
- - 该栏整体由 `GlobalSidebar` 渲染:改为向 `GlobalSidebar` 的 `items` 传数据(`icon` / `label` / `badge` / `separator`),本组件由它在内部渲染。
3665
+ - 该栏整体由 `GlobalSidebar` 渲染:改为向 `GlobalSidebar` 的 `items` 传数据(`icon` / `label` / `badge` / `separator`),本组件由它在内部渲染。栏底入口例外:`GlobalSidebar` 的 `footer` 直接放本组件(07 · C-15)。
3215
3666
  - 跨应用的快捷入口:改用 `SidebarAppLinkButton`。
3216
3667
  - Content Canvas 内部的通用垂直导航:改用 `Sidebar`,其折叠态即是 56px 图标栏。
3217
- - Shell 的四带导航:改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`、`ApplicationModuleSwitcher`。
3668
+ - Shell 的导航带:改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`、`ApplicationModuleSwitcher`。
3218
3669
 
3219
- **组合约定。** `label` 不可省略 —— 规范禁止纯图标导航项。图标与标签是一个交互单元,禁用或淡化必须作用于整个条目。同一栏内至多一个条目设 `active`。`badge` 只承载未读计数或极短文本,长文案会溢出 14px 高的药丸。标签必须是 2–4 字裸名词短语,超出即被截断。分隔线通过 `GlobalSidebarEntry.separator` 表达,调用方不得在 `items` 之间手工插入 `Separator`。直接使用本组件时(即不经 `GlobalSidebar`),必须放进 56px 宽的列容器,条目之间的纵向间距由该容器负责,该组件不自带外边距。
3670
+ **组合约定。** `label` 不可省略 —— 规范禁止纯图标导航项。图标与标签是一个交互单元,禁用或淡化必须作用于整个条目。同一栏内至多一个条目设 `active`。`badge` 只承载未读计数或极短文本,长文案会溢出 14px 高的药丸;数字或文本徽标的视觉部分对读屏隐藏,条目名读作「标签,N 条」,调用方不得再把计数拼进 `label`。标签必须是 2–4 字裸名词短语,超出即被截断。分隔线通过 `GlobalSidebarEntry.separator` 表达,调用方不得在 `items` 之间手工插入 `Separator`。直接使用本组件时(即不经 `GlobalSidebar`),必须放进 56px 宽的列容器,条目之间的纵向间距由该容器负责,该组件不自带外边距。
3220
3671
 
3221
3672
  **禁止 / 使用边界。**
3222
3673
  - 不得省略 `label`,纯图标导航项被规范禁止。
3223
3674
  - 不得只禁用图标或只淡化标签,二者必须整体一致。
3224
- - 禁止在 `GlobalSidebar` 的 `items` 之外再向该栏手工插入条目。
3225
- - 不得把它挪进应用外层 Shell —— Shell 是刻意设计的无侧栏、全宽四带堆叠。
3675
+ - 禁止在 `GlobalSidebar` 的 `items` 与 `footer` 之外再向该栏手工插入条目。
3676
+ - 不得把它挪进应用外层 Shell —— Shell 是刻意设计的无侧栏、全宽导航带堆叠。
3226
3677
 
3227
3678
  ### SystemButton
3228
3679
 
@@ -3236,37 +3687,41 @@ Sonner 的单条提示
3236
3687
  ⚠ **页面不得自建平台级或业务级的按钮变体。** 改一次应用强调色,
3237
3688
  全部 SystemButton 同时换肤 —— 逐页 fork 会摧毁这个性质。
3238
3689
 
3239
- 只有在没有稳定应用语义可用时才降级到 Foundation `Button`。
3690
+ **业务页面的按钮一律用本组件**,Foundation `Button` 只供库内组件使用
3691
+ (实践报告 P1-1 裁决)。
3692
+
3693
+ **替换原生元素:** `<button>`
3240
3694
 
3241
3695
  **Props**
3242
3696
 
3243
3697
  | prop | 类型 | 必填 | 说明 |
3244
3698
  |---|---|:---:|---|
3245
- | `intent` | `'primary' \| 'secondary' \| 'quiet' \| 'icon' \| 'link' \| 'destructive'` | 否 | 应用意图。映射到 Foundation Button 的 variant: `quiet` → ghost,`icon` → ghost + 等宽,其余同名。 |
3246
- | `size` | `'default' \| 'compact' \| 'icon'` | 否 | 尺寸。见 T2 —— `compact` 目前与 `default` 无视觉差异 |
3247
- | `loading` | `boolean` | 否 | 加载中。阻断交互并设置 `aria-busy`,同时渲染一个行内转圈。 与 `disabled` 都会阻断动作,但语义不同:loading 是暂时的。 |
3248
- | `children` | `ReactNode` | 否 | 纯图标按钮(`intent="icon"` 或 `size="icon"`)**必须**提供 `aria-label` |
3699
+ | `intent` | `'primary' \| 'secondary' \| 'quiet' \| 'link' \| 'destructive' \| 'destructive-outline'` | 否 | 应用意图。映射到 Foundation Button 的 variant:`quiet` → ghost,其余同名。 删除类动作两档:`destructive-outline`(白底、危险色描边与文字)用于与次要按钮 并排出现的删除,例如表单里「删除此附件」;`destructive`(实心危险色)只用于 确认弹窗里那个不可逆的最终动作。同一动作组内不得同时出现两档。 |
3700
+ | `size` | `'default' \| 'compact' \| 'sm'` | 否 | 尺寸。见 T2 —— `compact` 目前与 `default` 无视觉差异。 `sm` 映射 Foundation Button 的 28px 档,只用于嵌进 32px 控件内部的动作 (`InputGroup` 的尾部按钮),不得用来压缩页面上的独立按钮。 |
3701
+ | `iconOnly` | `boolean` | 否 | 等宽图标按钮:宽度收敛为与高度相等,行内内边距归零。直接映射到 Foundation `Button` 的 `iconOnly`,与 `intent` / `size` 正交。为 true 时**必须**提供 `aria-label`。 |
3702
+ | `loading` | `boolean` | 否 | 加载中。阻断交互并设置 `aria-busy`,同时渲染一个行内转圈;`iconOnly` 时转圈 替换原图标的位置,按钮尺寸不变。与 `disabled` 都会阻断动作,但语义不同:loading 是暂时的。 实现不用原生 `disabled`:渲染 `aria-disabled="true"` 并在 `onClick` 中 `preventDefault`(同时挡住 `type="submit"` 的表单提交),按钮保持可聚焦, 焦点不会在点击后掉到 `<body>`。 |
3703
+ | `children` | `ReactNode` | 否 | 按钮内容。`iconOnly` 时为单个 `Icon` 元素 |
3249
3704
 
3250
3705
  继承 `ButtonHTMLAttributes<HTMLButtonElement>` 的全部原生属性。
3251
3706
 
3252
3707
  **用途。** 整个产品的默认动作按钮,是 Foundation `Button` 之上只承载应用意图、loading 与产品状态的薄适配层。
3253
3708
 
3254
- **何时使用。** 应用层与业务页面中的每一个动作按钮都必须优先使用本组件 —— 应用层存在稳定语义适配器时应优先使用 `SystemButton` 而非 `Button`。改一次应用强调色,全部 `SystemButton` 同时换肤,这个性质正是它存在的理由。该组件绝不重新实现按钮的排版与几何:14/20 字号、32px 高度、16px 圆角全部来自 Foundation `Button`。
3709
+ **何时使用。** 业务页面中的每一个按钮都必须使用本组件,没有例外;Foundation `Button` 只供库内组件使用。改一次应用强调色,全部 `SystemButton` 同时换肤,这个性质正是它存在的理由。该组件绝不重新实现按钮的排版与几何:14/20 字号、32px 高度、12px 圆角全部来自 Foundation `Button`。删除类动作分两档:`intent="destructive-outline"`(白底、危险色描边与文字)用于与次要按钮并排的删除,如表单里「删除此附件」;`intent="destructive"`(实心危险色)只用于 `AlertDialog` 里那个不可逆的最终确认,同一动作组内不得同时出现两档。
3255
3710
 
3256
3711
  **何时改用其他组件。**
3257
- - 确无稳定应用语义可用时才降级到 `Button`,这是唯一的降级条件。
3258
3712
  - 一组相关按钮需要拼接为分段控件或间隔簇:外层用 `ButtonGroup`,组内仍是 `SystemButton`。
3259
3713
  - 一个局部显示选择(密度、对齐方式、局部视图标记):改用 `ToggleGroup`;单个独立开关改用 `Toggle`。
3260
3714
  - 立即生效的设置:改用 `Switch`。
3261
3715
  - 页面模式切换:改用 `ApplicationPageHeader` 的 `pageModes` / `pageMode` / `onPageModeChange`,不得用按钮自造 Page Mode Switch。
3262
3716
 
3263
- **组合约定。** `intent="icon"` 或 `size="icon"` 时必须提供 `aria-label`,该组件此时映射到 Foundation `Button` 的 `iconOnly`,按钮上没有可见文字。一个动作组内至多一个 `intent="primary"`。`loading` 与 `disabled` 都阻断动作但语义不同:loading 是暂时的且设置 `aria-busy`,等待中的动作必须用 `loading` 表达,不得用 `disabled` 冒充;loading 期间 `children` 必须保持不变,否则按钮宽度会跳动。`intent="destructive"` 只表达外观,破坏性动作仍必须经 `AlertDialog` 确认,批量场景下标题须写明受影响对象的数量。页面级动作放进 `ApplicationPageHeader` 的 `actions`,批量动作放进 `ListBatchActionBar` 的 `actions`,记录级动作放在行尾且必须阻止事件冒泡。该组件不自带外边距,动作之间的间距由 `ButtonGroup` 或容器的 gap 负责。`size="compact"` 当前与 `default` 同为 32px,该值为密度分档预留,不得用它做视觉压缩。换肤只有一个入口 `--ds-color-theme-primary`,覆盖 `--application-accent` 只会改到引用它的那一部分组件。
3717
+ **组合约定。** `iconOnly` 为 true 时必须提供 `aria-label`,按钮上没有可见文字;它直接映射到 Foundation `Button` 的 `iconOnly`,与 `intent`、`size` 正交,常规图标按钮写 `intent="quiet" iconOnly`。一个动作组内至多一个 `intent="primary"`。`loading` 与 `disabled` 都阻断动作但语义不同:loading 是暂时的且设置 `aria-busy`,等待中的动作必须用 `loading` 表达,不得用 `disabled` 冒充;loading 期间按钮渲染 `aria-disabled="true"` 而非原生 `disabled`,保持可聚焦(点击后焦点不会掉到页首),点击与 `type="submit"` 的表单提交由组件拦截,调用方不必在 `onClick` 里自行判断 loading;loading 期间 `children` 必须保持不变,否则按钮宽度会跳动;`iconOnly` 时转圈替换原图标的位置,按钮尺寸与可访问名不变。`intent="destructive"` 只表达外观,破坏性动作仍必须经 `AlertDialog` 确认,批量场景下标题须写明受影响对象的数量。页面级动作放进 `ApplicationPageHeader` 的 `actions`,批量动作放进 `ListBatchActionBar` 的 `actions`,记录级动作放在行尾:放进 `Table` 的单元格或 `ApplicationRecordList` 的行内时,行已忽略来自行内按钮的点击与按键,不必再阻止事件冒泡;放进自建的可点击容器(自己挂 `onClick` 的卡片、条目)时必须自行阻止冒泡。该组件不自带外边距,动作之间的间距由 `ButtonGroup` 或容器的 gap 负责。`size="compact"` 当前与 `default` 同为 32px,该值为密度分档预留,不得用它做视觉压缩。`size="sm"` 为 28px,只用于嵌进 32px 控件内部的动作(`InputGroup` 的尾部按钮)。换肤只有一个入口 `--ds-color-theme-primary`,覆盖 `--application-accent` 只会改到引用它的那一部分组件。
3264
3718
 
3265
3719
  **禁止 / 使用边界。**
3266
3720
  - 不得自建平台级或业务级的按钮变体,逐页 fork 会摧毁统一换肤这个性质。
3267
3721
  - 不得使用原生 `<button>` 承担动作。
3268
3722
  - 禁止用 `disabled` 表达加载中,等待状态必须用 `loading`。
3269
3723
  - 不得省略纯图标按钮的 `aria-label`。
3724
+ - 不得写 `intent="icon"` 或 `size="icon"` —— 两者已移除,等宽图标按钮一律走 `iconOnly`。
3270
3725
  - 不得在同一个动作组内出现两个 `intent="primary"`。
3271
3726
 
3272
3727
  ## Application Module · navigation
@@ -3277,21 +3732,26 @@ Sonner 的单条提示
3277
3732
 
3278
3733
  应用二级导航的**左半部分** —— 你在哪个模块,以及如何切换。
3279
3734
 
3280
- ### 触发器
3281
- Standard 最小宽 168 / 高 40,Compact 148 / 32;
3282
- 深色 32×32 图标块(8px 圆角,18px 白色字形),
3283
- 名称 16/20 **700**,14px chevron 右对齐。
3735
+ #### 触发器(GAP Design kit「应用二级模块切换」)
3736
+ Standard 168×48,Compact 148×40;内边距 4/12,**没有图标块**;
3737
+ 名称 16/20 **medium**,20px chevron 右对齐;右侧 0.5px 分隔线;悬停与展开时 6% 淡底。
3284
3738
 
3285
3739
  ⚠ **绝不能简化成一个小图标,也绝不能移除。**
3286
3740
 
3287
- ### 面板
3288
- `position: fixed`,`top: --ui-shell-application-total-height`,
3289
- `left: 0`,`bottom: 0`,宽 392px(受视口限制),白色表面,
3290
- **1px 右边线,无圆角,无阴影**,自带垂直滚动。
3291
- 条目最小高 40,内边距 8/12,圆角 12,文字 14/22。
3741
+ #### 面板
3742
+ 挂在触发器正下方(`position: absolute`),与触发器同宽 168、最窄 128,
3743
+ 底色为导航背景与表面色各半,内边距 4,条目间隔 2,
3744
+ **1px 右边线,无圆角,无阴影**,限高到视口底、自带垂直滚动。
3745
+ 条目最小高 40,内边距 8/12,圆角 12,文字 14/22;悬停取导航背景;
3746
+ 当前模块为强调色 semibold,右侧 14px 对勾。
3292
3747
 
3293
3748
  ⚠ **点击当前模块不发生跳转。** 路由计算由调用方负责。
3294
3749
 
3750
+ #### 键盘
3751
+ 按 WAI-ARIA menu button 模式:打开即聚焦首个可用模块(触发器上按 ↑ 打开则聚焦末项),
3752
+ ↑ / ↓ / Home / End 在模块间移动并跳过禁用项,Esc 与外部点击经 `onOpenChange(false)`
3753
+ 收起,Esc 后焦点回到触发器,Tab 收起面板并离开。
3754
+
3295
3755
  **Props**
3296
3756
 
3297
3757
  | prop | 类型 | 必填 | 说明 |
@@ -3299,7 +3759,6 @@ Standard 最小宽 168 / 高 40,Compact 148 / 32;
3299
3759
  | `moduleName` | `string` | 否 | 触发器上显示的当前模块名 |
3300
3760
  | `modules` | `ModuleItem[]` | 否 | 可切换的模块集合 |
3301
3761
  | `currentModule` | `string` | 否 | 当前模块值。点击它不触发 `onSelect` |
3302
- | `glyph` | `ReactNode` | 否 | 触发器图标块内的字形,18px |
3303
3762
  | `open` | `boolean` | 否 | 受控面板开合 |
3304
3763
  | `onOpenChange` | `(open: boolean) => void` | 否 | 面板开合变化回调 |
3305
3764
  | `onSelect` | `(value: string) => void` | 否 | 模块选中回调。点击当前模块不触发 |
@@ -3327,11 +3786,12 @@ Standard 最小宽 168 / 高 40,Compact 148 / 32;
3327
3786
  - 跨应用(而非跨模块)跳转:改用 `TopNavigationPrimaryBar` 的 `onAppSwitch`,条目用 `SidebarAppLinkButton`。
3328
3787
  - 工作台的图标菜单栏:改用 `GlobalSidebar`;Content Canvas 内的通用垂直导航:改用 `Sidebar`。
3329
3788
 
3330
- **组合约定。** `open` 与 `onOpenChange` 必须成对提供 —— 触发器点击只调用 `onOpenChange`,不提供该回调时面板永远无法打开。`currentModule` 必须命中 `modules` 中的一项。点击当前模块既不触发 `onSelect` 也不关闭面板;路由计算由调用方在 `onSelect` 中完成,组件不做任何跳转。面板是 `position: fixed`,顶边贴 `--ui-shell-application-total-height`,底边贴视口底,宽 392px 并受视口宽度限制;因此本组件的任何祖先元素都不得设置 `transform`、`filter` 或 `contain`,否则固定定位会改以该祖先为包含块而错位。触发器最小宽 168px、高 40px(Compact 148 / 32),几何由 Shell token 决定,调用方不得改写。`ModuleItem.icon` 与触发器的 `glyph` 均走 `Icon`,`glyph` 的登记尺寸是 18px。
3789
+ **组合约定。** `open` 与 `onOpenChange` 必须成对提供 —— 触发器点击只调用 `onOpenChange`,不提供该回调时面板永远无法打开。`currentModule` 必须命中 `modules` 中的一项。点击当前模块既不触发 `onSelect` 也不关闭面板;路由计算由调用方在 `onSelect` 中完成,组件不做任何跳转。几何按 GAP Design kit「应用二级模块切换」:触发器 168×48(Compact 148×40)、内边距 4/12、没有图标块,模块名 16/20 medium,20px chevron 右对齐,右侧 0.5px 分隔线,悬停与展开时 6% 淡底;面板挂在触发器正下方,与触发器同宽 168(最窄 128),内边距 4、条目间隔 2,限高到视口底、自身滚动;条目 40 高、内边距 8/12、圆角 12,悬停取导航背景,当前模块为强调色 semibold 加 14px 对勾。几何由 Shell token 决定,调用方不得改写。`ModuleItem.icon` 可选,kit 的模块条目不带图标,需要时走 `Icon`。键盘按 menu button 模式:打开即聚焦首个可用模块(触发器上按 ↑ 打开则聚焦末项),↑ / ↓ / Home / End 在模块间移动;Esc、外部点击与 Tab 都经 `onOpenChange(false)` 收起,Esc 后焦点回到触发器 —— 调用方不得再自行监听 Esc 或外部点击。
3331
3790
 
3332
3791
  **禁止 / 使用边界。**
3333
3792
  - 不得把触发器简化成一个小图标,也不得在窄屏下移除它。
3334
- - 禁止给面板加圆角、阴影或遮罩 —— 它只有 1px 右边线,是被推开的一块面而非浮起的卡片。
3793
+ - 禁止给面板加圆角、阴影或遮罩 —— 它只有 1px 右边线,是从触发器垂下的一截而非浮起的卡片。
3794
+ - 不得给触发器加回图标块,也不得把面板做成贴视口的整高侧板。
3335
3795
  - 不得把本组件放到 `ApplicationSecondaryNavigation` 之外的位置。
3336
3796
  - 不得由本组件承担路由跳转,`onSelect` 只是通知。
3337
3797
  - 不得用它切换应用、切换页面模式或切换业务视图。
@@ -3340,75 +3800,114 @@ Standard 最小宽 168 / 高 40,Compact 148 / 32;
3340
3800
 
3341
3801
  `import { ApplicationPrimaryNavigation } from '@moheng-design/ui'` · 契约 `contracts/application-module/navigation/application-primary-navigation.ts`
3342
3802
 
3343
- `APPLICATION.PRIMARY_NAV` —— 固定 Shell 的**第二带**。
3344
- Standard 64px / Compact 52px。
3803
+ `APPLICATION.PRIMARY_NAV` —— GAP Design kit「通用导航 / 应用一级导航」。
3804
+ Standard 48px / Compact 40px,内边距 8/12。
3805
+
3806
+ 外壳有两种形态(kit「导航组合」):
3345
3807
 
3346
- **左侧**:应用身份 —— logo 48×48(Compact 40×40)置于 8% 强调色瓦片上,
3347
- 名称 16/24 **700**,说明 12/16 400(Compact 可隐藏)。
3808
+ | 形态 | 带 | 总高 |
3809
+ |---|---|---:|
3810
+ | 基础版 | 本带 + `ApplicationSecondaryNavigation` | 96 |
3811
+ | 集团版 | `TopNavigationPrimaryBar` + 本带 + `ApplicationSecondaryNavigation` | 144 |
3812
+
3813
+ **左侧**:应用身份 —— 32×32 logo 瓦片(8px 圆角,8% 强调色混入表面色)+ 4px 间隙 +
3814
+ 应用名 14/20 regular 文字1。kit 里没有应用说明行。
3348
3815
 
3349
3816
  **右侧**:**恰好这五个已登记全局动作,且顺序固定**:
3350
3817
 
3351
- 消息 → 待办 → 运行总览 → 风险预警 → 设置
3818
+ 消息 → 待办 → 总览 → 风险预警 → 设置
3352
3819
 
3353
- 32×32 触发器,18px 字形,8px 间距。
3354
- 前四个打开共享 Popover,**设置打开 Drawer**。
3820
+ 每个动作是「18px 字形 + 文字」:32 高,左右 10,字形与文字间隔 4,圆角 12,文字 14/20 文字2;
3821
+ 动作之间 4px。前四个打开共享 Popover;**设置不弹浮层**,而是让 `ApplicationSecondaryNavigation`
3822
+ 整带换成设置模块(kit「框架结构 / 结构=设置」:模块切换器显示设置模块名,标签换成设置项,
3823
+ 最右的「导航设置」按钮换成关闭叉号)。
3824
+ 基础版传 `account` 时,头像(24×24 圆形)在动作组之后,间隔 8px。
3355
3825
 
3356
- ### ⚠ 硬性约束
3826
+ #### ⚠ 硬性约束
3357
3827
  - **绝不渲染第二个设置入口**
3358
3828
  - logo 瓦片是 8% 强调色混入表面色,**绝不是饱和强调色块**
3359
- - Compact 档可隐藏说明,但**必须保留** logo、名称与全部五个动作入口
3829
+ - Compact 档必须保留 logo、名称与全部五个动作入口
3360
3830
 
3361
3831
  **Props**
3362
3832
 
3363
3833
  | prop | 类型 | 必填 | 说明 |
3364
3834
  |---|---|:---:|---|
3365
- | `appName` | `string` | 否 | 应用名称,16/24 700。mock 文案登记为「示例应用」 |
3366
- | `appDescription` | `string` | 否 | 应用说明,12/16 400。mock 文案登记为「应用说明信息」 |
3367
- | `appGlyph` | `string` | 否 | 应用 logo mock 字形的图标名(24px) |
3835
+ | `appName` | `string` | 否 | 应用名称,14/20 regular。mock 文案登记为「示例应用」 |
3836
+ | `appGlyph` | `IconName` | 否 | 应用 logo mock 字形的图标名(20px),默认 `'shield-check'`。 与 `<Icon name>` 同为已登记字形名(05 · P1-6),清单外的名字在类型层被拒 |
3368
3837
  | `activeAction` | `GlobalActionKey` | 否 | 当前激活的全局动作面板 |
3369
3838
  | `actionBadges` | `Partial<Record<GlobalActionKey, boolean>>` | 否 | 各动作的未读圆点 |
3370
- | `onAction` | `(key: GlobalActionKey, kind: 'popover' \| 'drawer') => void` | 否 | 动作点击回调。`kind` 指明该动作打开 Popover 还是 Drawer |
3371
- | `compact` | `boolean` | 否 | Compact 档。隐藏应用说明,其余一律保留 |
3839
+ | `onAction` | `(key: GlobalActionKey, kind: GlobalActionKind) => void` | 否 | 动作点击回调。`kind` 指明该动作的承载:`'popover'` 打开共享的 `ApplicationGlobalActionPanel`, `'module'`(只有设置)把 `ApplicationSecondaryNavigation` 换成设置模块 |
3840
+ | `account` | `ApplicationPrimaryNavigationAccount` | 否 | 基础版外壳的账户入口。传入即在动作组之后渲染头像;集团版外壳(渲染了 `TopNavigationPrimaryBar`)不得传,否则一个外壳里会有两个账户入口 |
3372
3841
 
3373
3842
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
3374
3843
 
3375
- **用途。** Shell 第二带 `APPLICATION.PRIMARY_NAV`,左侧是当前应用的身份,右侧是五个已登记全局动作的入口。
3844
+ **`ApplicationPrimaryNavigationAccount`**
3376
3845
 
3377
- **何时使用。** 应用外壳必须在第一带之下渲染一条本组件。它是全局动作(消息、待办、运行总览、风险预警、设置)在整个产品中的唯一入口位置。应用级、跨页面、与当前业务页面无关的动作放在这里;只与当前页面有关的动作一律不放。
3846
+ 基础版外壳里本带承载的账户入口(GAP Design kit「导航组合 / 基础版本」:用户头像在应用一级
3847
+ 导航的最右端)。集团版外壳的账户入口在 `TopNavigationPrimaryBar`,此时不传本项。
3848
+
3849
+ | prop | 类型 | 必填 | 说明 |
3850
+ |---|---|:---:|---|
3851
+ | `name` | `string` | 否 | 账户名。同时是头像按钮的可访问名与缩写来源,缩写规则与 `Avatar` 相同 —— 中文取末字(「成员 A」→「A」),拉丁名取首字母(07 · C-8)。缺省时头像显示「账」 |
3852
+ | `open` | `boolean` | 否 | 账户面板是否展开。传入(含 `false`)即输出 `aria-haspopup="dialog"` 与 `aria-expanded`; 缺省时两者都不输出。面板内容根应声明 `role="dialog"` 与可访问名 |
3853
+ | `onToggle` | `(trigger: HTMLButtonElement) => void` | 否 | 头像点击回调。参数是被点的触发器,传给 `Popover` 的 `anchor` 锚定; 回调里切换开合并回写 `open`(与 `TopNavigationPrimaryBar.onAccount` 同一接法) |
3854
+
3855
+ **用途。** Shell 的应用一级导航带 `APPLICATION.PRIMARY_NAV`(GAP Design kit「应用一级导航」),左侧是当前应用的身份,右侧是五个已登记全局动作的入口;基础版外壳里账户头像也在这一带的最右端。
3856
+
3857
+ **何时使用。** 应用外壳必须渲染一条本组件:基础版里它是第一带,集团版里它在 `TopNavigationPrimaryBar` 之下。它是全局动作(消息、待办、总览、风险预警、设置)在整个产品中的唯一入口位置。应用级、跨页面、与当前业务页面无关的动作放在这里;只与当前页面有关的动作一律不放。
3378
3858
 
3379
3859
  **何时改用其他组件。**
3380
3860
  - 页面级动作组(新建 / 导入 / 导出 / 更多、刷新):改用 `ApplicationPageHeader` 的动作槽位,按钮用 `SystemButton`。
3381
3861
  - 搜索、常用筛选、排序、列设置:改用 `ApplicationQueryToolbar`。
3382
3862
  - 模块切换与业务标签:改用 `ApplicationSecondaryNavigation`。
3383
- - 前四个动作打开的浮层内容:改用 `ApplicationGlobalActionPanel`;设置打开的浮层:改用 `Drawer` 或 `Sheet`。
3863
+ - 前四个动作打开的浮层内容:改用 `ApplicationGlobalActionPanel`;设置打开的设置模块:改用 `ApplicationSecondaryNavigation`(传 `onCloseSettings`)。
3384
3864
 
3385
- **组合约定。** 五个动作及其顺序(消息 → 待办 → 运行总览 → 风险预警 → 设置)固化在实现内部,不接受外部传入,「已登记」即指此。`onAction` 的第二个参数 `kind` 指明该动作应接哪一类浮层:四个 `popover` 动作必须共用同一个 `ApplicationGlobalActionPanel` 实例,一个面板四套内容;`drawer` 动作接抽屉。`activeAction` 与 `onAction` 必须成对使用,`activeAction` 只对 popover 动作产生 `aria-expanded`。`actionBadges` 的键只能取五个已登记动作键,且它只表达「有未读」而不表达数量。`appGlyph` 取图标 `registry.json` 中已登记的字形名。`compact` 为 true 时仅隐藏 `appDescription`,logo、`appName` 与全部五个动作入口必须保留。本带自持内边距与底部分隔线,宿主不得再加外边距。
3865
+ **组合约定。** 五个动作及其顺序(消息 → 待办 → 总览 → 风险预警 → 设置)固化在实现内部,不接受外部传入,「已登记」即指此。`onAction` 的第二个参数 `kind`(`GlobalActionKind`)指明该动作的承载:四个 `popover` 动作必须共用同一个 `ApplicationGlobalActionPanel` 实例,一个面板四套内容;设置是唯一的 `module` 动作,调用方据此把 `ApplicationSecondaryNavigation` 换成设置模块并传 `onCloseSettings`(GAP Design kit「框架结构 / 结构=设置」),不打开任何浮层。`activeAction` 与 `onAction` 必须成对使用:设置模块开着时 `activeAction` 为 `'settings'`,设置动作随之带激活态;`activeAction` 只对 popover 动作产生 `aria-expanded`。`actionBadges` 的键只能取五个已登记动作键,且它只表达「有未读」而不表达数量。`appGlyph` 取图标 `registry.json` 中已登记的字形名(20px),类型与 `<Icon name>` 同为 `IconName`。几何按 kit:48 高(Compact 40)、内边距 8/12;logo 瓦片 32×32、圆角 8,应用名 14/20 regular,没有应用说明行;每个动作是「18px 字形 + 文字」,32 高、左右 10、圆角 12,文字 14/20 二级文字色,动作之间 4px。动作文字常显,不内置 `Tooltip`,调用方也不得再为它们包一层。基础版外壳传 `account`(`name` / `open` / `onToggle`),头像 24×24 圆形接在动作组之后 8px,面板接法与 `TopNavigationPrimaryBar.onAccount` 相同:`onToggle` 的参数是触发器,传给 `Popover` 的 `anchor`;集团版不得传 `account`。本带自持内边距与 0.5px 底部分隔线,宿主不得再加外边距。
3386
3866
 
3387
3867
  **禁止 / 使用边界。**
3388
3868
  - 禁止渲染第二个设置入口,无论它出现在本带、账户菜单还是页面内。
3389
3869
  - 不得增加、删除或重排五个全局动作,也不得把其中任意一个折叠进「更多」。
3390
3870
  - 不得把 logo 瓦片画成饱和强调色块 —— 它是 8% 强调色混入表面色的淡底。
3871
+ - 不得把五个动作改回纯图标,也不得在 Compact 档隐去它们的文字。
3391
3872
  - 不得为每个全局动作各造一个浮层,四个 popover 动作共用同一个面板。
3873
+ - 不得把设置接到 `Drawer`、`Sheet` 或 `ApplicationGlobalActionPanel` —— 它是二级导航里的设置模块。
3392
3874
  - 不得在本带承载页面标题、页面动作或数据控制。
3393
3875
 
3394
3876
  ### ApplicationSecondaryNavigation
3395
3877
 
3396
3878
  `import { ApplicationSecondaryNavigation } from '@moheng-design/ui'` · 契约 `contracts/application-module/navigation/application-secondary-navigation.ts`
3397
3879
 
3398
- `APPLICATION.SECONDARY_NAV` —— 固定 Shell 的**第三带**。
3399
- Standard 48px / Compact 40px。
3880
+ `APPLICATION.SECONDARY_NAV` —— GAP Design kit「应用二级导航」,外壳的最后一带
3881
+ (基础版第二带、集团版第三带)。Standard 48px / Compact 40px,右侧内边距 12。
3882
+
3883
+ **左侧**:完整的模块切换器,贴左缘。**中间**:当前模块的业务标签,间隔 8。
3884
+ **最右**:一枚已登记的 32×32 纯图标按钮 —— 平时是「导航设置」,设置模块打开时是「关闭设置」。
3885
+
3886
+ #### 尾部按钮(kit「二级导航设置」24:134 与「结构=设置」230:1104)
3887
+ 32×32、圆角 12、透明底,悬停是 6% 文字色淡底。两种形态互斥,同一时刻至多一枚:
3400
3888
 
3401
- **左侧**:完整的模块切换器。**右侧**:当前模块的业务标签。
3889
+ | 形态 | 何时渲染 | 字形 | 可访问名 |
3890
+ |---|---|---|---|
3891
+ | 导航设置 | 传了 `onNavigationSettings`,且未传 `onCloseSettings` | 16px `sliders-horizontal`,文字2 | 「导航设置」 |
3892
+ | 关闭设置 | 传了 `onCloseSettings` | 16px 叉号,文字1 | 「关闭设置」 |
3402
3893
 
3403
- ### ⚠ 每个标签都是「图标 + 文字」
3894
+ 两个回调都不传时不渲染,也不占位。
3895
+
3896
+ #### 设置模块
3897
+ 全局动作「设置」不弹抽屉:它让本带整体换成设置模块 —— `moduleSwitcher` 显示设置模块名,
3898
+ `tabs` 换成设置项,同时传 `onCloseSettings`,尾部按钮随之变为关闭叉号,根元素输出
3899
+ `data-mode="settings"`。关闭时由调用方把模块切换器、标签与 `value` 换回进入设置前的那一组。
3900
+
3901
+ #### ⚠ 每个标签都是「图标 + 文字」
3404
3902
  图标在左、可见文字在右。**纯文字标签被禁止**,
3405
3903
  **为适应窄屏而丢弃全部图标同样被禁止** —— 标签保持单行并横向滚动,绝不换行。
3406
3904
 
3407
- 标签几何:32px 高,内边距 6/12,文字 14/20。
3408
- 激活态是已登记的 **2px 下划线**,绝不是 pill 背景。
3905
+ 标签几何:32px 高,内边距 6/12,文字 14/20 文字2。
3906
+ 激活态是已登记的 **2px 下划线**(两端各缩进 12,贴标签底边)加强调色 medium 文字,
3907
+ 绝不是 pill 背景;悬停是 6% 文字色淡底、圆角 12,文字不变色。
3409
3908
  图标容器宽度固定,使字重变化不会横向推移文字。
3410
3909
 
3411
- ### ⚠ 本带不得承载
3910
+ #### ⚠ 本带不得承载
3412
3911
  Page Mode、Business View、搜索、筛选、对象动作、页面级主操作。
3413
3912
 
3414
3913
  标准 mock 文案是 `Tab 1 / Tab 2`(带图标);**`模块1 / 模块2` 被明令禁止**。
@@ -3421,6 +3920,9 @@ Page Mode、Business View、搜索、筛选、对象动作、页面级主操作
3421
3920
  | `tabs` | `SecondaryNavTab[]` | 否 | 业务标签集合 |
3422
3921
  | `value` | `string` | 否 | 当前标签 |
3423
3922
  | `onValueChange` | `(value: string) => void` | 否 | 标签变化回调 |
3923
+ | `onNavigationSettings` | `(event: MouseEvent<HTMLButtonElement>) => void` | 否 | 「导航设置」按钮的点击回调(kit「二级导航设置」)。传入即在本带最右端渲染该按钮; 不传即不渲染、不占位。参数是点击事件,`event.currentTarget` 即按钮元素,可传给 `Popover` 的 `anchor` 锚定面板,也是面板关闭后焦点的归还目标。 设置模块打开时(传了 `onCloseSettings`)本按钮不渲染 —— 那个位置换成关闭叉号 |
3924
+ | `navigationSettingsOpen` | `boolean` | 否 | 导航设置面板是否展开。传入(含 `false`)即在按钮上输出 `aria-haspopup="dialog"` 与 `aria-expanded`;缺省时两者都不输出。应与 `onNavigationSettings` 成对提供, 面板内容根相应声明 `role="dialog"` 与可访问名 |
3925
+ | `onCloseSettings` | `(event: MouseEvent<HTMLButtonElement>) => void` | 否 | 设置模块的关闭回调(kit「框架结构 / 结构=设置」)。传入即声明本带当前承载的是设置模块: 最右端渲染关闭叉号(可访问名「关闭设置」)取代「导航设置」按钮,根元素输出 `data-mode="settings"`。回调里由调用方换回进入设置前的模块切换器、`tabs` 与 `value` |
3424
3926
 
3425
3927
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
3426
3928
 
@@ -3435,9 +3937,9 @@ Page Mode、Business View、搜索、筛选、对象动作、页面级主操作
3435
3937
  | `icon` | `ReactNode` | 是 | 前置图标,**契约要求必填** —— 每个业务标签都是「图标 + 文字」。 必须来自已登记字形集:绝不用 Emoji、绝不用系统字体符号。 图标的业务含义必须稳定 —— 不得在 hover 或 active 时换成另一含义的字形。 |
3436
3938
  | `disabled` | `boolean` | 否 | 禁用。禁用作用于整个标签,不得只禁文字而留图标可点 |
3437
3939
 
3438
- **用途。** Shell 第三带 `APPLICATION.SECONDARY_NAV`,左侧是完整的模块切换器,右侧是当前模块的业务标签。
3940
+ **用途。** Shell 的应用二级导航带 `APPLICATION.SECONDARY_NAV`(GAP Design kit「应用二级导航」),左侧是完整的模块切换器,中间是当前模块的业务标签,最右是一枚已登记的尾部按钮 —— 平时是「导航设置」,设置模块里是「关闭设置」。
3439
3941
 
3440
- **何时使用。** 应用外壳必须在第二带之下渲染一条本组件。右侧标签表达的是「当前模块内的功能分区」,其集合随模块切换而整体更换。标签数量与内容由模块决定,不由页面决定。
3942
+ **何时使用。** 应用外壳必须在 `ApplicationPrimaryNavigation` 之下渲染一条本组件,它是外壳的最后一带。标签表达的是「当前模块内的功能分区」,其集合随模块切换而整体更换。标签数量与内容由模块决定,不由页面决定。全局动作「设置」打开时,本带整体换成设置模块(GAP Design kit「框架结构 / 结构=设置」):模块切换器显示设置模块名,标签换成设置项,尾部按钮变为关闭叉号 —— 设置不进任何抽屉、侧板或弹窗。
3441
3943
 
3442
3944
  **何时改用其他组件。**
3443
3945
  - 页面区域内的局部标签页(详情分节、SPLIT 右栏内容标签):改用 `Tabs`,那里图标是可选的。
@@ -3445,11 +3947,14 @@ Page Mode、Business View、搜索、筛选、对象动作、页面级主操作
3445
3947
  - Page Mode Switch:改用 `ApplicationPageHeader`。
3446
3948
  - 不强制图标的水平导航基元:改用 `NavigationMenu`。
3447
3949
  - Content Canvas 内的垂直导航:改用 `Sidebar`。
3950
+ - 导航设置打开的面板:改用 `Popover`,以 `onNavigationSettings` 交出的按钮为锚点。
3448
3951
 
3449
- **组合约定。** `moduleSwitcher` 槽位只接 `ApplicationModuleSwitcher`,不得传入 `Select`、`DropdownMenu` 或自制触发器。`SecondaryNavTab.icon` 在契约中是必填字段,图标必须来自已登记字形并通过 `Icon` 渲染,且其业务含义在 hover 与 active 下保持不变。`value` 与 `onValueChange` 必须成对使用;`tabs` 非空时 `value` 必须命中其中一项。切换模块时必须同时更换 `tabs` 与 `value`,不得让上一个模块的标签残留。标签行保持单行并横向滚动,滚动条已隐藏,调用方不得在外层再包一层滚动容器。激活态的 2px 下划线由组件绘制,调用方不得通过 `className` 叠加背景或边框。本带自持内边距与底部分隔线,宿主不得再加外边距。
3952
+ **组合约定。** `moduleSwitcher` 槽位只接 `ApplicationModuleSwitcher`,不得传入 `Select`、`DropdownMenu` 或自制触发器。`SecondaryNavTab.icon` 在契约中是必填字段,图标必须来自已登记字形并通过 `Icon` 渲染,且其业务含义在 hover 与 active 下保持不变。`value` 与 `onValueChange` 必须成对使用;`tabs` 非空时 `value` 必须命中其中一项。切换模块时必须同时更换 `tabs` 与 `value`,不得让上一个模块的标签残留。标签行保持单行并横向滚动,滚动条已隐藏,调用方不得在外层再包一层滚动容器。标签图标取 16px 档。几何按 kit:48 高(Compact 40),模块切换器贴左缘、右侧内边距 12,标签间隔 8;标签 32 高、内边距 6/12、文字 14/20 二级文字色;激活态为强调色 medium 文字加 2px 下划线(两端各缩进 12,贴标签底边);悬停为 6% 文字色淡底、圆角 12,文字不变色。激活态的下划线由组件绘制,调用方不得通过 `className` 叠加背景或边框。本带自持内边距与 0.5px 底部分隔线,宿主不得再加外边距。尾部按钮只有两种已登记形态,由回调决定,同一时刻至多一枚:传 `onNavigationSettings` 渲染「导航设置」(kit「二级导航设置」:32×32、圆角 12、透明底、16px `sliders-horizontal` 取二级文字色、悬停 6% 淡底,可访问名与提示「导航设置」),回调参数是点击事件,`event.currentTarget` 即 `Popover` 的锚点,面板开合回写 `navigationSettingsOpen`,按钮据此输出 `aria-haspopup="dialog"` 与 `aria-expanded`;传 `onCloseSettings` 即声明本带承载的是设置模块,尾部换成同一几何的关闭叉号(主要文字色,可访问名与提示「关闭设置」),根元素带 `data-mode="settings"`,此时不渲染导航设置。两个回调都不传时不渲染、不占位。设置模块由调用方组装:`ApplicationPrimaryNavigation` 的 `onAction` 收到 `kind='module'` 时,`moduleSwitcher` 照旧传 `ApplicationModuleSwitcher`(`moduleName` 为设置模块名、`modules` 为设置模块清单),`tabs` 换成设置项(同样必须带图标),`activeAction` 置为 `'settings'`,Content Canvas 渲染当前设置项的页面;`onCloseSettings` 里把模块切换器、`tabs` 与 `value` 换回进入设置前的那一组,并清掉 `activeAction`。
3450
3953
 
3451
3954
  **禁止 / 使用边界。**
3452
3955
  - 不得在本带承载 Page Mode、Business View、搜索、筛选、对象动作或页面级主操作。
3956
+ - 不得往尾部按钮的位置放其他元素 —— 它只有「导航设置」与「关闭设置」两种已登记形态。
3957
+ - 禁止把设置做成 `Drawer`、`Sheet` 或弹窗,也禁止在设置模块里省掉关闭叉号。
3453
3958
  - 禁止纯文字标签,也禁止为适应窄屏而丢弃全部图标。
3454
3959
  - 不得让标签换行 —— 单行横向滚动是已登记行为。
3455
3960
  - 不得把激活态改成 pill 背景,激活态是已登记的 2px 下划线。
@@ -3476,7 +3981,7 @@ Content Canvas 内的通用垂直导航请用 Foundation `Sidebar`;
3476
3981
  | `items` | `GlobalSidebarEntry[]` | 否 | 条目集合 |
3477
3982
  | `value` | `string` | 否 | 当前选中条目的 key |
3478
3983
  | `onValueChange` | `(key: string) => void` | 否 | 选中变化回调 |
3479
- | `footer` | `ReactNode` | 否 | 栏底内容 |
3984
+ | `footer` | `ReactNode` | 否 | 栏底内容。栏底入口(如「设置」)直接放 `SidebarRailButton`(07 · C-15) |
3480
3985
 
3481
3986
  继承 `HTMLAttributes<HTMLElement>` 的全部原生属性。
3482
3987
 
@@ -3497,16 +4002,16 @@ Content Canvas 内的通用垂直导航请用 Foundation `Sidebar`;
3497
4002
  **何时使用。** `pageType` 为 `WORKBENCH` 的工作台面需要一列固定的图标入口时使用本组件。它是工作台这一种页面的构件,其存在与否由页面决定,不由应用外壳决定。
3498
4003
 
3499
4004
  **何时改用其他组件。**
3500
- - Content Canvas 内的通用垂直导航(SPLIT 左栏目录、设置导航、模块子导航):改用 `Sidebar`。
4005
+ - Content Canvas 内的通用垂直导航(设置页目录):改用 `Sidebar`。
3501
4006
  - SPLIT 左栏的记录列表:改用 `ApplicationSplitListSidebar`。
3502
4007
  - 模块级导航:改用 `ApplicationSecondaryNavigation`。
3503
4008
  - 编辑器型工作面的水平菜单条:改用 `Menubar`。
3504
4009
  - 单个图标入口按钮:改用 `SidebarRailButton`;跨应用入口:改用 `SidebarAppLinkButton`。
3505
4010
 
3506
- **组合约定。** `items` 是数据而非元素 —— 组件内部渲染 `SidebarRailButton` 并自行控制 `active` 与点击,调用方不得先构造好按钮元素再传入。`GlobalSidebarEntry.label` 在类型上可选,在规范上必填:规范禁止纯图标导航项,只给 `icon` 不给 `label` 能通过类型检查但不合规。`icon` 的登记尺寸是 20px,走 `Icon`。`separator` 为 true 时其余字段被忽略,但该条目的 `key` 仍必须在栏内唯一。`value` 与 `onValueChange` 成对使用。`footer` 被推到栏底,与条目之间不需要额外间隔元素。本组件自持内边距与右侧 1px 边线,宿主用 flex 把它与内容区并排即可,不得再加外边距。
4011
+ **组合约定。** `items` 是数据而非元素 —— 组件内部渲染 `SidebarRailButton` 并自行控制 `active` 与点击,调用方不得先构造好按钮元素再传入。`GlobalSidebarEntry.label` 在类型上可选,在规范上必填:规范禁止纯图标导航项,只给 `icon` 不给 `label` 能通过类型检查但不合规。`icon` 的登记尺寸是 20px,走 `Icon`。`separator` 为 true 时其余字段被忽略,但该条目的 `key` 仍必须在栏内唯一。`value` 与 `onValueChange` 成对使用。`footer` 被推到栏底,与条目之间不需要额外间隔元素;栏底的入口(如「设置」)直接放 `SidebarRailButton`(07 · C-15)。本组件自持内边距与右侧 1px 边线,宿主用 flex 把它与内容区并排即可(写法见 SKILL.md「五层 Canvas 模型 · 宿主布局」),不得再加外边距。
3507
4012
 
3508
4013
  **禁止 / 使用边界。**
3509
- - 不得把本组件当作应用外壳的全局左栏 —— Shell 是刻意设计的无侧栏、全宽四带堆叠。
4014
+ - 不得把本组件当作应用外壳的全局左栏 —— Shell 是刻意设计的无侧栏、全宽导航带堆叠。
3510
4015
  - 不得给本组件设置 `position: fixed` 或让它跨出 Content Canvas。
3511
4016
  - 禁止渲染只有图标而没有标签的条目。
3512
4017
  - 不得用它替代 `Sidebar` 承载带分组标题的多层导航。
@@ -3515,36 +4020,51 @@ Content Canvas 内的通用垂直导航请用 Foundation `Sidebar`;
3515
4020
 
3516
4021
  `import { TopNavigationPrimaryBar } from '@moheng-design/ui'` · 契约 `contracts/application-module/navigation/top-navigation-primary-bar.ts`
3517
4022
 
3518
- `PLATFORM.TOP_USER_BAR` —— 固定 Shell 的**第一带**。
3519
- Standard 52px / Compact 44px,**没有第三种高度**。
4023
+ `PLATFORM.TOP_USER_BAR` —— GAP Design kit「集团顶部导航」,**只在集团版外壳出现**
4024
+ (本带 + 应用一级 + 应用二级,共 144)。基础版外壳不渲染本组件,账户入口由
4025
+ `ApplicationPrimaryNavigation` 的 `account` 承载。
4026
+ Standard 48px / Compact 40px,**没有第三种高度**;内边距 8/12,底部 0.5px 分隔线。
3520
4027
 
3521
- 栅格 `auto minmax(0,1fr) auto`;应用切换与账户触发器 32×32,
3522
- 动作簇间距 10px,右边距 12px。
4028
+ 渲染本组件时,其 CSS 在 `:root` 上把 `--ui-shell-top-bar-offset` 抬到本带高度,
4029
+ `--ui-shell-application-total-height` 随之计入本带 —— 宿主不必区分两种外壳。
3523
4030
 
3524
- ### ⚠ 品牌标识必须始终可见
3525
- 没有真实的 120×32 资产时,渲染已登记的 mock:
3526
- **28×28 纯色块 + 8px 间隙 + 企业名称(14/20 700)**。
4031
+ 栅格 `auto minmax(0,1fr) auto`;应用切换触发器 32×32、圆角 12,账户头像 24×24 圆形
4032
+ (32×32 命中区),动作簇间距 10px,右边距 12px。
4033
+
4034
+ #### ⚠ 品牌标识必须始终可见
4035
+ 品牌区按 GAP Design kit「集团顶部导航」(24:249):
4036
+ **36×36 图形 + 8px 间隙 + 企业名称(20/30 semibold)**,宽度按内容。
4037
+ 名称恒为可见文字;图形位放 `brandLogoSrc`,缺省时渲染已登记的 mock 纯色块。
3527
4038
  色块内部**不得**再绘制伪 Logo。
3528
4039
 
3529
- ### ⚠ Shell 契约禁止添加未登记元素
4040
+ #### ⚠ Shell 契约禁止添加未登记元素
3530
4041
  不得加搜索框、面包屑、通知铃铛、页面标题、卡片或阴影。
3531
4042
 
4043
+ #### 两个面板的接法(06 · P1-13)
4044
+ 回调交出被点的触发器,传给 `Popover` 的 `anchor` 即可锚定;开合由调用方受控,
4045
+ 同时回写 `appSwitchOpen` / `accountOpen`,触发器据此输出 `aria-expanded`。
4046
+ 再点触发器即收起 —— Popover 不把外部锚点上的点击当作外部点击。写法:回调里
4047
+ 记下触发器并切换开合(`setAnchor(trigger); setOpen((v) => !v)`),Popover 传
4048
+ `anchor={anchor} open={open} onOpenChange={setOpen}`。
4049
+
3532
4050
  **Props**
3533
4051
 
3534
4052
  | prop | 类型 | 必填 | 说明 |
3535
4053
  |---|---|:---:|---|
3536
4054
  | `brandName` | `string` | 否 | 企业名称。mock 兜底文案登记为「企业名称」 |
3537
- | `brandLogoSrc` | `string` | 否 | 真实品牌资产地址(120×32)。缺省时回退到已登记 mock |
4055
+ | `brandLogoSrc` | `string` | 否 | 品牌图形地址,按 36×36 渲染(`object-fit: contain`),与 `brandName` 并排; 图形是装饰,可访问名由旁边的名称文字承担。缺省时图形位回退到已登记 mock 色块。 传的是图形标(kit 里的 36px 图形),不是含企业名的横版字标 —— 名称由组件以文字渲染, 再传字标会让名字出现两遍 |
3538
4056
  | `center` | `ReactNode` | 否 | 中间区域内容。默认为空 —— 加东西前请确认它是已登记元素 |
3539
- | `accountName` | `string` | 否 | 账户名 |
3540
- | `onAppSwitch` | `() => void` | 否 | 应用切换回调 |
3541
- | `onAccount` | `() => void` | 否 | 账户菜单回调 |
4057
+ | `accountName` | `string` | 否 | 账户名。同时是账户按钮的可访问名与头像缩写的来源;缩写规则与 `Avatar` 相同 —— 中文取末字(「成员 A」→「A」),拉丁名取首字母(07 · C-8)。缺省时头像显示「账」 |
4058
+ | `onAppSwitch` | `(trigger: HTMLButtonElement) => void` | 否 | 应用切换回调。参数是被点的触发器,供 `Popover` 的 `anchor` 锚定; 不需要锚定的调用方照旧写无参函数 |
4059
+ | `onAccount` | `(trigger: HTMLButtonElement) => void` | 否 | 账户菜单回调。参数同 `onAppSwitch` |
4060
+ | `appSwitchOpen` | `boolean` | 否 | 应用切换面板是否展开。传入(含 `false`)即声明该触发器控制一个弹出面板: 输出 `aria-haspopup="dialog"` 与 `aria-expanded`。缺省时两者都不输出 —— 不知道面板开没开,宁可不说也不能说错。面板内容根应声明 `role="dialog"` 与可访问名 |
4061
+ | `accountOpen` | `boolean` | 否 | 账户面板是否展开。语义同 `appSwitchOpen` |
3542
4062
 
3543
4063
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
3544
4064
 
3545
- **用途。** Shell 第一带 `PLATFORM.TOP_USER_BAR`,承载平台级身份(品牌)与账户入口,跨全部应用与全部页面不变。
4065
+ **用途。** 集团版外壳的最上一带 `PLATFORM.TOP_USER_BAR`(GAP Design kit「集团顶部导航」),承载集团级身份(品牌)、应用切换与账户入口,跨全部应用与全部页面不变。
3546
4066
 
3547
- **何时使用。** 一个应用外壳必须且只能渲染一条本组件,作为四带堆叠的最上一层。它表达的是「用户在哪个平台、以什么身份」,与当前打开的是哪个应用、哪个模块、哪个页面全部无关。凡是随应用切换而变化的内容,均不属于本带。
4067
+ **何时使用。** 外壳有两种形态:基础版是「应用一级导航 + 应用二级导航」两带共 96px,不渲染本组件;集团版在两带之上再加本组件,三带共 144px。产品需要跨应用切换与集团品牌时用集团版,此时一个外壳必须且只能渲染一条本组件。它表达的是「用户在哪个集团、以什么身份」,与当前打开的是哪个应用、哪个模块、哪个页面全部无关。凡是随应用切换而变化的内容,均不属于本带。
3548
4068
 
3549
4069
  **何时改用其他组件。**
3550
4070
  - 应用身份(logo、应用名、应用说明)与五个全局动作:改用 `ApplicationPrimaryNavigation`。
@@ -3553,13 +4073,14 @@ Standard 52px / Compact 44px,**没有第三种高度**。
3553
4073
  - 层级回溯路径:改用 `Breadcrumb`,且只能出现在上下文区。
3554
4074
  - 跨应用跳转的条目:改用 `SidebarAppLinkButton` 渲染在 `onAppSwitch` 打开的面板内。
3555
4075
 
3556
- **组合约定。** 本带高度由 `--ui-shell-primary-height` 决定(Standard 52px / Compact 44px),只有这两档;调用方不得用 `className` 或行内样式改高。三条导航带的 `position: fixed` 与层级由宿主布局承担,组件本身按普通流元素渲染并输出 `data-shell-slot="top-navigation"` 供布局定位;堆叠总高读 `--ui-shell-application-total-height`,Content Canvas 据此让位。本带自持左右内边距与底部分隔线,宿主不得再加外边距。`brandLogoSrc` 缺省时自动回退到已登记 mock:28×28 纯色块 + 8px 间隙 + `brandName`;提供 `onAccount` 时应一并提供 `accountName`,账户按钮的可访问名与头像首字均取自它。`center` 默认为空,写入内容前必须确认该元素在 Shell 契约中已登记。
4076
+ **组合约定。** 本带高度由 `--ui-shell-primary-height` 决定(Standard 48px / Compact 40px),只有这两档;调用方不得用 `className` 或行内样式改高。导航带的固定与层级由宿主布局承担(标准宿主 CSS 见 SKILL.md「五层 Canvas 模型 · 宿主布局」),组件本身按普通流元素渲染并输出 `data-shell-slot="top-navigation"` 供布局定位;堆叠总高读 `--ui-shell-application-total-height`,Content Canvas 据此让位 —— 本组件在场时它的 CSS 把 `--ui-shell-top-bar-offset` 计入总高(96 → 144),宿主不必区分两种外壳。集团版的账户入口只在本带,`ApplicationPrimaryNavigation` 不得再传 `account`。本带自持左右内边距与 0.5px 底部分隔线,宿主不得再加外边距。品牌区按 GAP Design kit「集团顶部导航」:36×36 图形 + 8px 间隙 + `brandName`(20/30 semibold),宽度按内容;名称恒以文字渲染,图形位放 `brandLogoSrc`(图形标,按 36×36 `contain` 渲染,是装饰,`alt` 为空),缺省时自动回退到已登记 mock 纯色块 —— 不得传含企业名的横版字标,那会让名字出现两遍;提供 `onAccount` 时应一并提供 `accountName`,账户按钮的可访问名与头像缩写均取自它,缩写规则与 `Avatar` 相同(中文取末字,「成员 A」→「A」;拉丁名取首字母)。`center` 默认为空,写入内容前必须确认该元素在 Shell 契约中已登记。 应用切换与账户两个面板用 `Popover` 承载:`onAppSwitch` / `onAccount` 的参数是被点的触发器,必须传给 `Popover` 的 `anchor` 锚定,不得另放空锚点凑位置;开合由调用方受控,回调里切换开合(再点触发器即收起),并把同一份状态回写到 `appSwitchOpen` / `accountOpen`,触发器据此输出 `aria-haspopup="dialog"` 与 `aria-expanded`,面板内容根相应声明 `role="dialog"` 与可访问名。
3557
4077
 
3558
4078
  **禁止 / 使用边界。**
3559
4079
  - 不得在本带内加入搜索框、面包屑、通知铃铛、页面标题、卡片或阴影 —— Shell 契约禁止添加未登记元素。
3560
- - 禁止在 28×28 纯色块内部再绘制伪 Logo,该色块是占位而非标识。
4080
+ - 禁止在 36×36 纯色块内部再绘制伪 Logo,该色块是占位而非标识。
3561
4081
  - 不得出现第三种高度,也不得随 Condensed 档改变高度。
3562
4082
  - 不得在一个页面内渲染第二条本组件,也不得把它嵌进 Content Canvas。
4083
+ - 不得在基础版外壳里渲染本组件来承载账户入口 —— 基础版的账户入口是 `ApplicationPrimaryNavigation` 的 `account`。
3563
4084
 
3564
4085
  ## Application Module · statistics
3565
4086
 
@@ -3576,7 +4097,7 @@ Standard 52px / Compact 44px,**没有第三种高度**。
3576
4097
  | `label` | `ReactNode` | 否 | 指标名 |
3577
4098
  | `value` | `ReactNode` | 否 | 指标值 |
3578
4099
  | `unit` | `string` | 否 | 单位 |
3579
- | `data` | `number[]` | 否 | 走势数据点 |
4100
+ | `data` | `number[]` | 否 | 走势数据点。纵轴按本组数据的 min–max 归一化(不从 0 起算), 只表达形状、不表达绝对量级;全部相等时画在中线 |
3580
4101
  | `colorIndex` | `number` | 否 | 分类色序号,索引 `--application-categorical-01…20`。**不是状态色** |
3581
4102
 
3582
4103
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
@@ -3589,7 +4110,8 @@ MetricStrip 内置的基础指标条目(numeric / icon 语义)
3589
4110
  |---|---|:---:|---|
3590
4111
  | `key` | `string` | 否 | React key。**应显式提供** —— 见 M2 |
3591
4112
  | `label` | `ReactNode` | 是 | 指标名,12/16 label 色 |
3592
- | `value` | `ReactNode` | 是 | 指标值,24/32 semibold,等宽数字 |
4113
+ | `value` | `ReactNode` | 是 | 指标值,32/32 semibold,等宽数字 |
4114
+ | `description` | `ReactNode` | 否 | 口径说明,渲染在数值下方一行,12/16 次要文字色。例如「2026 年 · 不含已冲红」。 只写统计口径(时间范围、包含与排除),**不得**写趋势、环比或操作提示 —— 变化量用 `ApplicationMetricTrend`,操作入口不属于只读的指标卡。 |
3593
4115
  | `unit` | `string` | 否 | 单位,紧随数值以 12px regular 显示 |
3594
4116
  | `icon` | `ReactNode` | 否 | 图标。提供时语义从 `numeric` 变为 `icon`,渲染 32px 淡强调色方块 |
3595
4117
 
@@ -3612,7 +4134,7 @@ primary-secondary 语义中的单个次级数字
3612
4134
  - 表达占比或完成度:改用 `Progress`。
3613
4135
  - 无形状信息、只有一个数:改用 `ApplicationMetricStrip` 的 `metrics`。
3614
4136
 
3615
- **组合约定。** 本卡必须作为 `ApplicationMetricStrip` 的 `children` 渲染,等高与卡间距由容器负责,本卡不得自带外边距。走势图形是 `aria-hidden` 的装饰性 SVG,指标的可读信息必须完整地由 `label` 与 `value` 表达;`data` 与 `value` 必须成对提供。`data` 为空数组时不渲染走势图形,卡片仍保留数值并参与等高。`colorIndex` 索引的是 20 色图表分类色板 `--application-categorical-01…20`,仅编码分类,与好坏无关。绘图区是 88×28px 的版式常量,调用方不得改写。
4137
+ **组合约定。** 本卡必须作为 `ApplicationMetricStrip` 的 `children` 渲染,等高与卡间距由容器负责,本卡不得自带外边距。走势图形是 `aria-hidden` 的装饰性 SVG,指标的可读信息必须完整地由 `label` 与 `value` 表达;`data` 与 `value` 必须成对提供。`data` 为空数组时不渲染走势图形,卡片仍保留数值并参与等高。走势线纵轴按 `data` 自身的最小值–最大值归一化、不从 0 起算,因此只表达形状、不表达绝对量级与幅度;`data` 全部相等时画成中线。`colorIndex` 索引的是 20 色图表分类色板 `--application-categorical-01…20`,仅编码分类,与好坏无关。绘图区是 88×28px 的版式常量,调用方不得改写。
3616
4138
 
3617
4139
  **禁止 / 使用边界。**
3618
4140
  - 不得用本卡替代 `Chart` 承担分析职责,它没有坐标轴、图例与数值刻度。
@@ -3647,7 +4169,8 @@ MetricStrip 内置的基础指标条目(numeric / icon 语义)
3647
4169
  |---|---|:---:|---|
3648
4170
  | `key` | `string` | 否 | React key。**应显式提供** —— 见 M2 |
3649
4171
  | `label` | `ReactNode` | 是 | 指标名,12/16 label 色 |
3650
- | `value` | `ReactNode` | 是 | 指标值,24/32 semibold,等宽数字 |
4172
+ | `value` | `ReactNode` | 是 | 指标值,32/32 semibold,等宽数字 |
4173
+ | `description` | `ReactNode` | 否 | 口径说明,渲染在数值下方一行,12/16 次要文字色。例如「2026 年 · 不含已冲红」。 只写统计口径(时间范围、包含与排除),**不得**写趋势、环比或操作提示 —— 变化量用 `ApplicationMetricTrend`,操作入口不属于只读的指标卡。 |
3651
4174
  | `unit` | `string` | 否 | 单位,紧随数值以 12px regular 显示 |
3652
4175
  | `icon` | `ReactNode` | 否 | 图标。提供时语义从 `numeric` 变为 `icon`,渲染 32px 淡强调色方块 |
3653
4176
 
@@ -3709,7 +4232,8 @@ MetricStrip 内置的基础指标条目(numeric / icon 语义)
3709
4232
  |---|---|:---:|---|
3710
4233
  | `key` | `string` | 否 | React key。**应显式提供** —— 见 M2 |
3711
4234
  | `label` | `ReactNode` | 是 | 指标名,12/16 label 色 |
3712
- | `value` | `ReactNode` | 是 | 指标值,24/32 semibold,等宽数字 |
4235
+ | `value` | `ReactNode` | 是 | 指标值,32/32 semibold,等宽数字 |
4236
+ | `description` | `ReactNode` | 否 | 口径说明,渲染在数值下方一行,12/16 次要文字色。例如「2026 年 · 不含已冲红」。 只写统计口径(时间范围、包含与排除),**不得**写趋势、环比或操作提示 —— 变化量用 `ApplicationMetricTrend`,操作入口不属于只读的指标卡。 |
3713
4237
  | `unit` | `string` | 否 | 单位,紧随数值以 12px regular 显示 |
3714
4238
  | `icon` | `ReactNode` | 否 | 图标。提供时语义从 `numeric` 变为 `icon`,渲染 32px 淡强调色方块 |
3715
4239
 
@@ -3748,13 +4272,19 @@ primary-secondary 语义中的单个次级数字
3748
4272
 
3749
4273
  其他语义的卡片作为 `children` 传入,由本容器统一等高排列。
3750
4274
 
4275
+ ⚠ 加载与失败由 `state` 表达(06 · P2-10):`loading` 渲染与卡片同壳同高的骨架,
4276
+ `error` 渲染一张横跨整行的卡片承载 `error` 节点。两者都不是「无指标」的替身 ——
4277
+ 页面没有真实指标时仍是整个区域不渲染。
4278
+
3751
4279
  **Props**
3752
4280
 
3753
4281
  | prop | 类型 | 必填 | 说明 |
3754
4282
  |---|---|:---:|---|
3755
4283
  | `metrics` | `Metric[]` | 否 | 基础指标集合 |
3756
- | `columns` | `number` | 否 | 列数。默认取指标数量,上限 6 |
4284
+ | `columns` | `number` | 否 | 列数。默认取卡片总数 —— `metrics` 条目数加 `children` 中的卡片数 (null / false / undefined 不计入),钳在 1–6 之间 |
3757
4285
  | `children` | `ReactNode` | 否 | 其他语义的指标卡(trend / chart / status / primary-secondary) |
4286
+ | `state` | `MetricStripState` | 否 | 加载状态,默认 `ready`。`loading` 时不渲染 `metrics` 与 `children`,改渲染 内置骨架:张数同 `columns` 的缺省算法(无卡片时为 4),每张与指标卡同壳同高; `error` 时渲染一张横跨整行的卡片,内容取 `error` |
4287
+ | `error` | `ReactNode` | 否 | `state="error"` 时的内容。应说明失败原因并提供重试(如「指标加载失败」+「重试」), 措辞不得与数据展示区的 Error 共用。不传时显示内置的「指标加载失败」 |
3758
4288
 
3759
4289
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
3760
4290
 
@@ -3766,7 +4296,8 @@ MetricStrip 内置的基础指标条目(numeric / icon 语义)
3766
4296
  |---|---|:---:|---|
3767
4297
  | `key` | `string` | 否 | React key。**应显式提供** —— 见 M2 |
3768
4298
  | `label` | `ReactNode` | 是 | 指标名,12/16 label 色 |
3769
- | `value` | `ReactNode` | 是 | 指标值,24/32 semibold,等宽数字 |
4299
+ | `value` | `ReactNode` | 是 | 指标值,32/32 semibold,等宽数字 |
4300
+ | `description` | `ReactNode` | 否 | 口径说明,渲染在数值下方一行,12/16 次要文字色。例如「2026 年 · 不含已冲红」。 只写统计口径(时间范围、包含与排除),**不得**写趋势、环比或操作提示 —— 变化量用 `ApplicationMetricTrend`,操作入口不属于只读的指标卡。 |
3770
4301
  | `unit` | `string` | 否 | 单位,紧随数值以 12px regular 显示 |
3771
4302
  | `icon` | `ReactNode` | 否 | 图标。提供时语义从 `numeric` 变为 `icon`,渲染 32px 淡强调色方块 |
3772
4303
 
@@ -3790,14 +4321,15 @@ primary-secondary 语义中的单个次级数字
3790
4321
  - 行内或表格单元中的状态标签:改用 `Badge`。
3791
4322
  - 承载业务内容而非数字的卡片:改用 `Card`。
3792
4323
 
3793
- **组合约定。** 本组件必须放进 `ApplicationPageLayoutContainer` 的 `metrics` 槽位,区域之间的间隙由该容器的 `--ui-section-gap` 负责;卡片之间的间隙由本组件的 `--ui-card-gap` 负责(Standard 12px / Condensed 10px / Compact 8px)。单张指标卡不得自带外边距。`trend` / `status` / `chart` / `primary-secondary` 四种语义的卡片必须作为 `children` 写在本组件内部,与 `metrics` 生成的基础卡共用同一个 grid,等高才能成立;把它们平级另起一行会破坏等高。每区 4–6 张,`columns` 缺省取指标数量、上限 6。`Metric.key` 应显式提供 —— `label` 是 ReactNode,用它作 React key 在传入 JSX 时无效。`Metric.icon` 走 `Icon`,提供后该卡语义从 `numeric` 变为 `icon`。
4324
+ **组合约定。** 本组件必须放进 `ApplicationPageLayoutContainer` 的 `metrics` 槽位,区域之间的间隙由该容器的 `--ui-section-gap` 负责;卡片之间的间隙由本组件的 `--ui-card-gap` 负责(Standard 12px / Condensed 10px / Compact 8px)。单张指标卡不得自带外边距。`trend` / `status` / `chart` / `primary-secondary` 四种语义的卡片必须作为 `children` 写在本组件内部,与 `metrics` 生成的基础卡共用同一个 grid,等高才能成立;把它们平级另起一行会破坏等高。每区 4–6 张,`columns` 缺省取卡片总数(`metrics` 条目数加 `children` 中的卡片数,条件渲染为 `null` / `false` 的不计入)、上限 6。`Metric.key` 应显式提供 —— `label` 是 ReactNode,用它作 React key 在传入 JSX 时无效。`Metric.icon` 走 `Icon`,提供后该卡语义从 `numeric` 变为 `icon`。`Metric.description` 是数值下方一行 12/16 的口径说明(「2026 年 · 不含已冲红」),只写统计口径,不写趋势或操作提示;有设计稿时照稿给出,同一区内要么都写要么都不写,否则等高的卡片里文字基线不齐。指标壳不是卡片:无边框、无底色、无内边距,直接落在页面底色上,高 76px,数值 32/32 semibold。指标数据在途或失败时用 `state` 表达,取值只有 `ready` / `loading` / `error` 三种:`loading` 由组件渲染与指标卡同壳同高的骨架(张数同 `columns` 的缺省算法,无卡片时为 4),调用方不得自拼骨架卡;`error` 渲染一张横跨整行的失败卡,内容经 `error` 传入,应说明失败原因并提供「重试」,不传时显示内置的「指标加载失败」。两种状态下 `metrics` 与 `children` 都不渲染;读屏经组件内置的状态播报获知「指标加载中」/「指标加载失败」。
3794
4325
 
3795
4326
  **禁止 / 使用边界。**
4327
+ - 不得用 `state="loading"` 长期占位来顶替「无真实指标」—— 无指标时整个区域不渲染。
3796
4328
  - 不得用占位卡凑数:页面没有真实指标时整个区域不渲染,向 `ApplicationPageLayoutContainer` 传 `metrics={undefined}`。
3797
4329
  - 不得给指标卡挂点击跳转,整卡默认只读,`cursor: default` 是已登记行为。
3798
4330
  - 不得一行超过 6 张,也不得让同一区内的卡片高度不一致。
3799
4331
  - 不得在指标区放置页面动作按钮、搜索框或筛选控件。
3800
- - 禁止给指标卡加阴影 —— 卡片壳是 16px 圆角 + 1px 边框,无阴影。
4332
+ - 禁止给指标卡加阴影、边框或白底 —— 指标直接落在页面底色上。
3801
4333
 
3802
4334
  ### ApplicationMetricTrend
3803
4335
 
@@ -3829,7 +4361,8 @@ MetricStrip 内置的基础指标条目(numeric / icon 语义)
3829
4361
  |---|---|:---:|---|
3830
4362
  | `key` | `string` | 否 | React key。**应显式提供** —— 见 M2 |
3831
4363
  | `label` | `ReactNode` | 是 | 指标名,12/16 label 色 |
3832
- | `value` | `ReactNode` | 是 | 指标值,24/32 semibold,等宽数字 |
4364
+ | `value` | `ReactNode` | 是 | 指标值,32/32 semibold,等宽数字 |
4365
+ | `description` | `ReactNode` | 否 | 口径说明,渲染在数值下方一行,12/16 次要文字色。例如「2026 年 · 不含已冲红」。 只写统计口径(时间范围、包含与排除),**不得**写趋势、环比或操作提示 —— 变化量用 `ApplicationMetricTrend`,操作入口不属于只读的指标卡。 |
3833
4366
  | `unit` | `string` | 否 | 单位,紧随数值以 12px regular 显示 |
3834
4367
  | `icon` | `ReactNode` | 否 | 图标。提供时语义从 `numeric` 变为 `icon`,渲染 32px 淡强调色方块 |
3835
4368
 
@@ -3879,6 +4412,7 @@ Canvas 的**数据展示区**。
3879
4412
  ⚠ **六种状态各有各的节点与各自的措辞。**
3880
4413
  Loading / Empty / Error / No Permission / Not Found 绝不共用文案 ——
3881
4414
  「当前口径下无数据」「你没有权限」「未找到」「请求失败」是四句不同的话。
4415
+ 第六种 Partial Failure 不替换呈现,而是在 ready 态经 `notice` 叠一条 `Alert`。
3882
4416
 
3883
4417
  **Props**
3884
4418
 
@@ -3887,6 +4421,7 @@ Loading / Empty / Error / No Permission / Not Found 绝不共用文案 ——
3887
4421
  | `presentation` | `DataPresentation` | 否 | 当前呈现方式。应与 `ApplicationQueryToolbar` 的取值保持一致 |
3888
4422
  | `state` | `DataDisplayState` | 否 | 当前系统状态。`ready` 渲染 `children`,其余渲染对应槽位 |
3889
4423
  | `batchBar` | `ReactNode` | 否 | 批量动作条,应传 `ListBatchActionBar`。有记录被选中时才出现 |
4424
+ | `notice` | `ReactNode` | 否 | 区域级提示,承载 **Partial Failure**(05 · P2-2):应传 `Alert`,说明哪部分没取到并给出重试。 固定在批量条之下、呈现之上,**不随内容滚动**;**只在 `state="ready"` 时渲染** —— 其余五种状态整块换成对应槽位,部分失败无从谈起。此前没有这个位置,调用方只能把 Alert 塞进 `children` 顶部,与呈现组件同处滚动区,滚走后读者就看不到哪些字段缺失。 |
3890
4425
  | `pagination` | `ReactNode` | 否 | 分页,应传 `ListTablePagination`。固定在区域底部 |
3891
4426
  | `loading` | `ReactNode` | 否 | Loading 状态内容。应传贴近最终结构的 `Skeleton`,而非通用转圈 |
3892
4427
  | `empty` | `ReactNode` | 否 | Empty 状态内容。应传 `Empty`,文案须点明「当前口径」 |
@@ -3894,6 +4429,7 @@ Loading / Empty / Error / No Permission / Not Found 绝不共用文案 ——
3894
4429
  | `noPermission` | `ReactNode` | 否 | No Permission 状态内容。措辞必须区别于 Empty |
3895
4430
  | `notFound` | `ReactNode` | 否 | Not Found 状态内容。措辞必须区别于 Empty 与 No Permission |
3896
4431
  | `children` | `ReactNode` | 否 | `state="ready"` 时渲染的呈现组件 |
4432
+ | `bodyRef` | `Ref<HTMLDivElement>` | 否 | 主体滚动容器的 ref —— 批量条与分页之间、自身滚动的那一层(06 · P2-4)。 供「从详情返回列表时还原滚动位置」:离开前读它的 `scrollTop` 存进跨路由存活的 状态,回来后在 `state` 首次变为 `ready` 时写回。主体容器跨状态切换不重建, 同一个 ref 在 loading → ready 之间一直指向同一个元素。 走具名 prop 而不是 `ref`:`ref` 在 React 18 不交给函数组件,且根元素也不是 滚动的那一层;具名 prop 在 18 与 19 下行为一致。 |
3897
4433
 
3898
4434
  继承 `HTMLAttributes<HTMLElement>` 的全部原生属性。
3899
4435
 
@@ -3902,7 +4438,7 @@ Loading / Empty / Error / No Permission / Not Found 绝不共用文案 ——
3902
4438
  **何时使用。** 页面需要展示结果集时使用。LIST 页面模式与 SPLIT 右栏共用同一个该组件与同一个呈现组件。该区域只负责展示与选择,不负责查询。
3903
4439
 
3904
4440
  **何时改用其他组件。**
3905
- - 具体的呈现形态由被承载的组件决定:结构化记录列表用 `ApplicationRecordList`,表格用 `Table`,图表用 `Chart`,日历用 `Calendar`。
4441
+ - 具体的呈现形态由被承载的组件决定:结构化记录列表用 `ApplicationRecordList`(`presentation="RecordList"`),表格用 `Table`,卡片网格用 `Card`,图表用 `Chart`。看板、月历、时间轴三种暂无专属组件,一律按 SKILL.md「五层 Canvas 模型 · 呈现配方」的标准拼装写法承载(06 · D-2);月历不得用 Foundation `Calendar` 控件充当。
3906
4442
  - 单条记录的详情主体改用 `ApplicationRecordDetailBody`。
3907
4443
  - 指标概览属于指标区,改用 `ApplicationMetricStrip` 与四个语义指标卡。
3908
4444
  - 只需要一个带边框的静态面板时改用 `Card`。
@@ -3911,14 +4447,20 @@ Loading / Empty / Error / No Permission / Not Found 绝不共用文案 ——
3911
4447
  **组合约定。**
3912
4448
  - `state` 为 `ready` 时渲染 `children`,其余五种状态各自渲染对应槽位。使用某个状态前必须提供该状态的节点,否则该区域为空白。
3913
4449
  - 六种状态的文案必须区分成因:`loading` 传贴近最终结构的 `Skeleton`,`empty` 传 `Empty` 且点明当前口径,`error` 说明失败原因并提供重试,`noPermission` 与 `notFound` 各写各的措辞。
4450
+ - 第六种 Partial Failure 不替换呈现:`state` 保持 `ready`,把 `Alert` 传进 `notice`,说明哪部分没取到并给出重试;受影响的字段在呈现里以「—」或「暂不可用」占位。`notice` 固定在批量条之下、呈现之上,位于滚动区之外,不随内容滚走;非 `ready` 态不渲染。不得把这条 `Alert` 放进 `children` 顶部 —— 那样它与呈现共用滚动区,一滚就看不到。
4451
+ - `empty` 按成因分两句(07 · C-6):有搜索或筛选生效时写「没有符合当前筛选条件的记录」,出路是 `清除筛选`;当前视图下本就没有数据时写「当前视图下还没有记录」,出路是 `新建`(仅当有创建权限)。
4452
+ - 被承载的 `Table` 不再另设 `empty`:结果为空时把 `state` 置为 `empty`,空态只由本组件的 `empty` 槽位承担。
4453
+ - `state` 为 `no-permission` 或 `not-found` 时页面不渲染 `ApplicationQueryToolbar`(`dataControl` 不传);`error` 时保留工具栏,改条件即可重新查询。
3914
4454
  - `presentation` 必须与 `ApplicationQueryToolbar` 的同名 prop 取自同一处状态,否则呈现设置按钮会命名错误。
3915
4455
  - `batchBar` 应传 `ListBatchActionBar`,仅在有记录被选中时才出现;`pagination` 应传 `ListTablePagination`,固定在区域底部。
4456
+ - 分页状态按业务视图各记一份:切换 `businessView` 时回到该视图上次所在的页,切换 `pageMode` 与从详情返回时保持当前页;搜索、筛选、排序变化时复位到第 1 页(07 · C-13)。
3916
4457
  - 展示区自身滚动,批量条与分页固定在上下两端。调用方不得在 `children` 外再包一层滚动容器。
4458
+ - 还原滚动位置:主体滚动容器经 `bodyRef` 暴露,跨状态切换不重建。从列表进入详情前读 `bodyRef.current.scrollTop`,与查询条件一起存进跨路由存活的状态(layout 级 context 或 URL);回到列表后在 `state` 首次变为 `ready` 时于 `useLayoutEffect` 中写回,只写一次。存下的位置只对原来那一份结果集有意义,离开期间查询条件变了就不还原。
3917
4459
  - 该组件在列向 flex 中吃掉剩余高度,必须作为 `ApplicationPageLayoutContainer` 的 `children` 使用,否则拿不到剩余高度,内部滚动失效。
3918
4460
  - 边框、圆角与背景由该组件持有,被承载的呈现组件不得再画一层外框。
3919
4461
 
3920
4462
  **禁止 / 使用边界。**
3921
- - 不得在该区域内持有第二套查询状态 —— 搜索、筛选、排序全部属于 `ApplicationQueryToolbar`。
4463
+ - 不得在该区域内持有第二套查询状态 —— 搜索、筛选、排序全部属于 `ApplicationQueryToolbar`;`Table` 表头排序只是同一份排序状态的第二入口。
3922
4464
  - 禁止 Loading / Empty / Error / No Permission / Not Found 共用同一句文案。
3923
4465
  - 不得为 LIST 页面模式与 SPLIT 右栏各写一份近乎相同的呈现实现。
3924
4466
  - 不得在一个展示区内同时渲染两种 Data Presentation。
@@ -3930,8 +4472,8 @@ Loading / Empty / Error / No Permission / Not Found 绝不共用文案 ——
3930
4472
 
3931
4473
  完整的筛选维度列表 —— **「更多筛选」的面板主体**。
3932
4474
 
3933
- ⚠ **必须包含搜索**,外加每一个可筛选维度 ——
3934
- 「更多筛选」是筛选能力的全集入口,不是常用筛选的补充。
4475
+ ⚠ **必须包含搜索**,外加常用筛选之外的每一个可筛选维度 ——
4476
+ 常用筛选里出现的维度不再进「更多筛选」,同一维度只有一个入口(07 · C-11)。
3935
4477
 
3936
4478
  ⚠ **它持有草稿:在点「应用」之前,任何改动都不生效。**
3937
4479
 
@@ -3973,7 +4515,7 @@ Loading / Empty / Error / No Permission / Not Found 绝不共用文案 ——
3973
4515
 
3974
4516
  **用途。** 「更多筛选」的面板主体 —— 全量筛选维度列表,持有草稿并由「应用」提交。
3975
4517
 
3976
- **何时使用。** 页面的可筛选维度多于工具栏能常驻的 2–3 个时使用。它是筛选能力的全集入口,而非常用筛选的补充。每个提供筛选的页面至多一份。
4518
+ **何时使用。** 页面的可筛选维度多于工具栏能常驻的 2–3 个时使用。它承载常用筛选之外的全部维度,常用筛选里出现的维度不再进本面板(07 · C-11)。每个提供筛选的页面至多一份。
3977
4519
 
3978
4520
  **何时改用其他组件。**
3979
4521
  - 常驻在工具栏主控制行的单个高频维度改用 `ApplicationFilterMenu`。
@@ -3994,7 +4536,8 @@ Loading / Empty / Error / No Permission / Not Found 绝不共用文案 ——
3994
4536
  **禁止 / 使用边界。**
3995
4537
  - 不得在 `onChange` 中直接提交查询 —— 草稿只有经「应用」才生效。
3996
4538
  - 禁止把生效的筛选条件只保留在面板内部而不回写筛选标签行。
3997
- - 不得只放部分维度 —— 该面板必须覆盖每一个可筛选维度,否则它不能被称作「更多筛选」。
4539
+ - 不得只放部分维度 —— 该面板必须覆盖常用筛选之外的每一个可筛选维度,否则它不能被称作「更多筛选」。
4540
+ - 不得重复放入常用筛选里已有的维度 —— 同一维度两处入口生效语义不同(常用筛选点即生效,本面板经「应用」才生效),先后改动时无从判定以谁为准。
3998
4541
  - 不得用该组件替代工具栏内常驻的 2–3 个常用筛选。
3999
4542
  - 禁止在该组件内放置排序、呈现设置或页面模式相关的控件。
4000
4543
 
@@ -4004,59 +4547,86 @@ Loading / Empty / Error / No Permission / Not Found 绝不共用文案 ——
4004
4547
 
4005
4548
  Canvas 的**上下文区**(源仓库名 `application-page-header`)。
4006
4549
 
4007
- 左侧:品牌强调色条 · 16px 标题 · 数据状态 + 刷新。
4550
+ 左侧:可选的「返回」· 16px 标题 · 竖线 · 更新时间与刷新。中部:可选的任务状态胶囊(`taskStatus`)。
4008
4551
  右侧:页面动作组,再经分隔线之后是**页面级的 Page Mode Switch**。
4009
4552
 
4010
- ### 允许出现在这里
4011
- 新建 / 导入 / 导出 / 更多、刷新、面包屑、Page Mode Switch。
4553
+ 左侧按 GAP Design kit「数据更新」(业财平台 round-01 裁决,2026-11-10):
4554
+ - 二级页面以「返回」幽灵按钮(16px chevron + 文字,32 高、左右 12、圆角 12)开头,
4555
+ 与标题间隔 8 —— 传 `onBack` 即渲染
4556
+ - 标题之后是一条 12px 高的竖线,再接更新时间:完整日期时间(`2026-07-28 10:00`)
4557
+ 14/20 文字1,不加「更新于」前缀;传了 `onRefresh` 时时间与其后的 16px 刷新字形
4558
+ 合成一枚幽灵按钮(32 高、左右 12、圆角 12),点它即刷新
4012
4559
 
4013
- ### ⚠ 禁止出现在这里
4560
+ 外观(GAP Design kit,业财平台 round-01):48px 高的通栏,落在页面底色上、只有一条
4561
+ 0.5px 下边线,不是卡片。放在 `ApplicationPageLayoutContainer` 的 `header` 槽位时
4562
+ 向两侧与顶部吃掉页面留白,贴满内容区宽度。此前左侧的 3×16 强调色条已移除。
4563
+
4564
+ #### 允许出现在这里
4565
+ 新建 / 导入 / 导出 / 更多、刷新、返回、面包屑、Page Mode Switch。
4566
+
4567
+ #### ⚠ 禁止出现在这里
4014
4568
  **搜索、常用筛选、排序、SPLIT 视图模式切换、列设置、行级或批量动作。**
4015
4569
  这些全部属于 `ApplicationQueryToolbar`。
4016
4570
 
4017
- ### Page Mode Switch 的硬性规则
4571
+ #### Page Mode Switch 的硬性规则
4018
4572
  - 仅当 `pageModes.length >= 2` 时渲染;只有一种模式时**完全不渲染且不占位**
4019
4573
  - **绝不能被折叠进「更多」菜单**
4020
4574
  - 在每一种模式下都停留在**同一个物理位置**
4021
4575
 
4022
- ### 刷新的语义
4576
+ #### 刷新的语义
4023
4577
  刷新**只更新数据**,绝不重置业务视图、搜索、筛选、排序或页面模式。
4024
4578
 
4025
4579
  **Props**
4026
4580
 
4027
4581
  | prop | 类型 | 必填 | 说明 |
4028
4582
  |---|---|:---:|---|
4029
- | `title` | `ReactNode` | 否 | 页面标题,16/24 medium 字重,超长省略 |
4583
+ | `title` | `ReactNode` | 否 | 页面标题,16/32 regular 字重,超长省略 |
4030
4584
  | `subtitle` | `ReactNode` | 否 | 副标题,紧随标题以 12px label 色显示 |
4031
4585
  | `dataStatus` | `'normal' \| 'refreshing' \| 'failed'` | 否 | 数据状态。决定状态文案与刷新按钮的可用性 |
4032
- | `updatedAt` | `string` | 否 | 最后更新时刻,仅在 `normal` 状态显示为「更新于 …」 |
4033
- | `onRefresh` | `() => void` | 否 | 刷新回调。`refreshing` 状态下按钮禁用 |
4586
+ | `updatedAt` | `string` | 否 | 数据更新时间,写完整日期时间 `YYYY-MM-DD HH:mm`(如 `2026-07-28 10:00`),原样显示、 不加前缀(GAP Design kit「数据更新」;推翻 07 · C-12 的「只写 HH:mm」)。 仅在 `normal` 状态显示;`refreshing` / `failed` 显示「刷新中」/「刷新失败」 |
4587
+ | `onRefresh` | `() => void` | 否 | 刷新回调。提供时更新时间与刷新字形合成一枚按钮,`refreshing` 状态下不可点、字形转圈。 **未提供时不渲染刷新字形,时间按纯文字显示** —— 没有刷新能力的页面(草稿、向导、 一次性结果)不得出现一个点了没反应的按钮。状态文案(时间 / 刷新中 / 刷新失败)不受影响。 |
4588
+ | `onBack` | `() => void` | 否 | 返回回调。提供时标题前渲染「返回」幽灵按钮(kit「数据更新-二级页面」)。 组件不做路由跳转,回到哪里、还原哪些上下文由调用方决定。 与 `breadcrumb` 不得同时传 —— 二级页面用返回,需要展示多级路径时才用面包屑 |
4589
+ | `backLabel` | `string` | 否 | 返回按钮文案,默认「返回」。只在 `onBack` 提供时生效 |
4590
+ | `taskStatus` | `ApplicationPageHeaderTaskStatus` | 否 | 页面级进行中任务的状态胶囊,居中显示在页头中部。例如批量识别的「正在识别 14/100」。 `busy` 为 true 时胶囊前带转圈。 只表达**本页正在进行的一项任务**的进度;**不得**用它显示数据刷新状态(那是 `dataStatus`)、页面说明(那是 `subtitle`)或筛选摘要(那属于 `ApplicationQueryToolbar`)。 |
4034
4591
  | `actions` | `ReactNode` | 否 | 页面级动作组。**至多一个 primary** |
4035
4592
  | `pageModes` | `PageMode[]` | 否 | 本页**真正开放**的页面模式。少于 2 个则开关完全不渲染 |
4036
4593
  | `pageMode` | `PageMode` | 否 | 当前页面模式 |
4037
4594
  | `onPageModeChange` | `(mode: PageMode) => void` | 否 | 页面模式变化回调 |
4038
- | `breadcrumb` | `ReactNode` | 否 | 面包屑。仅当页面确有层级时提供 |
4595
+ | `breadcrumb` | `ReactNode` | 否 | 面包屑。仅当页面需要展示多级路径时提供;单纯「回到上一层」用 `onBack`,两者不得同时传。 面包屑在标题上方另占一行,页头因此高于 48 |
4039
4596
 
4040
4597
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `title` 已被本组件重新定义或移除。
4041
4598
 
4599
+ **`ApplicationPageHeaderTaskStatus`**
4600
+
4601
+ 页头中部的任务状态胶囊
4602
+
4603
+ | prop | 类型 | 必填 | 说明 |
4604
+ |---|---|:---:|---|
4605
+ | `label` | `ReactNode` | 是 | 胶囊文案,如「正在识别 14/100」 |
4606
+ | `busy` | `boolean` | 否 | 任务进行中。为 true 时胶囊前带转圈,任务结束后改为 false 或移除整个 `taskStatus` |
4607
+
4042
4608
  **用途。** Canvas 的上下文区,承载页面身份、数据新鲜度与页面级 Page Mode Switch。
4043
4609
 
4044
- **何时使用。** 每个业务页面的第一个区域必须是该组件。页面标题、面包屑、数据状态与刷新、页面级动作组、Page Mode Switch 全部集中在这里,且只有这里。该组件回答的是「这是哪个页面、数据是什么时候的、用哪种模式看」。
4610
+ **何时使用。** 每个业务页面的第一个区域必须是该组件。返回、页面标题、面包屑、数据状态与刷新、页面级动作组、Page Mode Switch 全部集中在这里,且只有这里。该组件回答的是「这是哪个页面、数据是什么时候的、用哪种模式看」。
4045
4611
 
4046
4612
  **何时改用其他组件。**
4047
4613
  - 跨页身份与应用、模块导航属于 Shell,改用 `TopNavigationPrimaryBar`、`ApplicationPrimaryNavigation`、`ApplicationSecondaryNavigation`。
4048
4614
  - 搜索、常用筛选、排序、呈现设置、SPLIT 右栏的 View Mode Switch 一律改用 `ApplicationQueryToolbar`。
4049
4615
  - 批量动作改用 `ListBatchActionBar`,它出现在结果集上方而非上下文区。
4050
4616
  - 记录对象的头部改用 `ApplicationRecordDetailBody` 的 `summary` 与 `ApplicationDetailDrawer` 的标题区。
4051
- - 面包屑本体用 `Breadcrumb`,经 `breadcrumb` 槽位传入。
4617
+ - 面包屑本体用 `Breadcrumb`,经 `breadcrumb` 槽位传入;单纯回到上一层(二级页面)不用面包屑,改传 `onBack`。
4052
4618
 
4053
4619
  **组合约定。**
4054
- - `actions` 承载页面级动作组,元素应为 `Button` 或 `SystemButton`,至多一个 primary。中文标签为 2–4 字裸名词短语:`新建`、`导入`、`导出`、`更多`。
4055
- - Page Mode Switch 由 `pageModes`、`pageMode`、`onPageModeChange` 三者共同驱动,三者必须成组提供;只给 `pageModes` 会得到一个点不动的开关。
4620
+ - `actions` 承载页面级动作组,元素应为 `SystemButton`,至多一个 primary。中文标签为 2–4 字裸名词短语:`新建`、`导入`、`导出`、`更多`。
4621
+ - Page Mode Switch 由 `pageModes`、`pageMode`、`onPageModeChange` 三者共同驱动,三者必须成组提供;只给 `pageModes` 会得到一个点不动的开关。它按 radiogroup 模式只占一个 Tab 停靠点,← / → 切换模式并首尾相接,Home / End 跳到首末项 —— 方向键同样触发 `onPageModeChange`。
4056
4622
  - `pageModes` 只列该页面真正开放的模式。少于 2 个时开关完全不渲染且不占位。
4057
- - `dataStatus` 为 `normal` 时应同时提供 `updatedAt`,否则状态区只剩一个刷新按钮,数据新鲜度无从判断。
4058
- - 三种数据状态各有各的措辞与可用性:`normal` 显示更新时刻,`refreshing` 显示刷新中且刷新按钮禁用,`failed` 显示刷新失败且按钮读作 `重试`。
4623
+ - 左侧按 GAP Design kit「数据更新」排布:可选的「返回」→ 标题 → 12px 竖线 → 更新时间。传 `onBack` 时标题前渲染「返回」幽灵按钮(16px chevron + 文字,32 高、圆角 12),文案经 `backLabel` 可改,组件不跳转、回到哪里由调用方决定;二级页面用它回到来源页。`onBack` 与 `breadcrumb` 不得同时传。
4624
+ - `dataStatus` 为 `normal` 时应同时提供 `updatedAt`,否则数据新鲜度无从判断。`updatedAt` 写完整日期时间 `YYYY-MM-DD HH:mm`(24 小时制、两位补零,如 `2026-07-28 10:00`),组件原样显示为 14/20 正文色,不加「更新于」前缀;不得传秒或「刚刚」「5 分钟前」一类相对时间。此条取代 07 · C-12 的「只写 HH:mm」(业财平台 round-01 按 kit 裁决)。
4625
+ - 传了 `onRefresh` 时,更新时间与其后的 16px 刷新字形合成一枚幽灵按钮,点它即刷新,可访问名为「刷新,2026-07-28 10:00」;没有刷新能力的页面(草稿、向导、一次性结果)不传,时间按纯文字显示,不出现刷新字形。
4626
+ - 三种数据状态各有各的措辞与可用性:`normal` 显示更新时间,`refreshing` 显示刷新中、字形转圈且按钮不可点,`failed` 显示刷新失败(危险色)且按钮读作 `重试`。
4059
4627
  - `title` 为字符串时才会得到悬浮提示。需要悬浮提示又需要补充信息时,标题主体传 `title`,补充信息走 `subtitle`。
4628
+ - 页面级进行中任务(批量识别、批量导入)的进度经 `taskStatus` 渲染为页头正中的胶囊,`label` 写「正在识别 14/100」,`busy` 为 true 时带转圈;任务结束后移除 `taskStatus`,结果写进 `Sonner` 或页面内容。进度不得写进 `subtitle`。
4629
+ - 外观是 48px 通栏:落在页面底色上、只有一条 0.5px 下边线,不是卡片;放在 `ApplicationPageLayoutContainer` 的 `header` 槽位时自动吃掉顶部与两侧留白。
4060
4630
  - 该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 的区域间隙负责。
4061
4631
  - Page Mode Switch 的选中态与 `ToggleGroup` 同为分段控件表达(选中项抬升为表面色),不得改为淡色洗 —— 淡色洗属于独立开关 `Toggle`。
4062
4632
 
@@ -4066,6 +4636,9 @@ Canvas 的**上下文区**(源仓库名 `application-page-header`)。
4066
4636
  - 不得让刷新重置业务视图、搜索、筛选、排序或页面模式 —— 刷新只更新数据。
4067
4637
  - 不得在 `actions` 中放置行级动作或批量动作。
4068
4638
  - 禁止渲染只有一种取值的 Page Mode Switch,也不得为它保留空位。
4639
+ - 不得用 `taskStatus` 显示数据刷新状态、页面说明或筛选摘要 —— 三者各有 `dataStatus`、`subtitle` 与工具栏。
4640
+ - 禁止同时传 `onBack` 与 `breadcrumb`,也不得用 `actions` 里的按钮充当返回。
4641
+ - 不得给 `updatedAt` 拼上「更新于」等前缀 —— 组件按 kit 原样显示时间。
4069
4642
 
4070
4643
  ### ApplicationPageLayoutContainer
4071
4644
 
@@ -4086,10 +4659,14 @@ Content Canvas 宿主自身内边距为零,因此不会产生双重外边距
4086
4659
 
4087
4660
  ⚠ 页面没有真实指标时传 `metrics={undefined}`,**绝不用占位卡凑数**。
4088
4661
 
4662
+ `pageType` 必填:五层 Canvas 模型的 L1 只有本组件这一个承载者,
4663
+ 不传即结构不完整(实践报告 P1-2)。
4664
+
4089
4665
  **Props**
4090
4666
 
4091
4667
  | prop | 类型 | 必填 | 说明 |
4092
4668
  |---|---|:---:|---|
4669
+ | `pageType` | `'WORKBENCH' \| 'MANAGEMENT' \| 'LEDGER' \| 'ANALYSIS' \| 'REPORT' \| 'DETAIL'` | 是 | L1 页面类型。输出为根节点的 `data-page-type`,不改变区域顺序与留白。 唯一受它影响的是纵向尺寸:`DETAIL` 页的容器随内容增高、由 Content Canvas 滚动;其余页型的容器可收缩到 Canvas 高度,数据展示区拿到剩余高度后 由 `ApplicationDataDisplay` 内部滚动。 `DETAIL` 页的内容结构用 `ApplicationRecordDetailBody`,仍以本组件为内容根。 |
4093
4670
  | `header` | `ReactNode` | 否 | 上下文区,应传 `ApplicationPageHeader` |
4094
4671
  | `metrics` | `ReactNode` | 否 | 指标区,应传 `ApplicationMetricStrip`。无真实指标时整体省略 |
4095
4672
  | `dataControl` | `ReactNode` | 否 | 数据控制区,应传 `ApplicationQueryToolbar` |
@@ -4108,7 +4685,8 @@ Content Canvas 宿主自身内边距为零,因此不会产生双重外边距
4108
4685
  - SPLIT 的两栏切分改用 `Resizable`,它落在该组件的数据展示区之内,不替代该组件。
4109
4686
 
4110
4687
  **组合约定。**
4111
- - 四个槽位与 Canvas 五层模型逐一对应:`header` 承载上下文区,`metrics` 承载指标区,`dataControl` 承载 L3 业务视图与 L4 数据控制,`children` 承载 L5 数据呈现。
4688
+ - `pageType` 必填,取值 `WORKBENCH` / `MANAGEMENT` / `LEDGER` / `ANALYSIS` / `REPORT` / `DETAIL`,输出为根节点的 `data-page-type`。它是 L1 页面类型唯一的 prop 落点,不改变区域顺序与留白;唯一受它影响的是纵向尺寸 —— `DETAIL` 页的容器随内容增高、由 Content Canvas 滚动,其余页型的容器收缩到 Canvas 高度、由数据展示区内的 `ApplicationDataDisplay` 内部滚动。
4689
+ - 四个槽位与 Canvas 五层模型逐一对应:`header` 承载上下文区,`metrics` 承载指标区,`dataControl` 承载 L3 业务视图与 L4 数据控制,`children` 承载 L5 数据呈现。无结果集页面(工作台、详情、配置、协作、编辑器)只传 `pageType`,`dataControl` 不传(编辑器例外:`Menubar` 放这里),`children` 承载面板网格、详情分节或工作面,由 Content Canvas 整页滚动(06 · D-1、D-4)。
4112
4690
  - `header` 应传 `ApplicationPageHeader`,`metrics` 应传 `ApplicationMetricStrip`,`dataControl` 应传 `ApplicationQueryToolbar`,`children` 应传 `ApplicationDataDisplay`。
4113
4691
  - 区域顺序由槽位固定,不由调用方书写次序决定:把上下文区传进 `metrics` 不会让它落到指标区的位置上。
4114
4692
  - 外边距归属唯一:Content Canvas 宿主内边距为零,页面内边距与区域间隙(Standard 12px / Condensed 10px / Compact 8px)全部由该组件持有。四个区域自身不得再带外边距。
@@ -4121,7 +4699,8 @@ Content Canvas 宿主自身内边距为零,因此不会产生双重外边距
4121
4699
  - 不得在该组件外层再包一层带内边距的容器 —— 页面留白只有一个持有者,两边都加会得到双倍留白。
4122
4700
  - 禁止用占位指标卡凑满 `metrics`,无真实指标时该区域整体不渲染。
4123
4701
  - 不得在该组件内部再嵌套一个 `ApplicationPageLayoutContainer`。
4124
- - 禁止在页面内堆叠第二个无界垂直滚动容器 —— Content Canvas 是唯一的垂直滚动持有者。
4702
+ - 不得把 `pageType` 写成常量、注释或自造的 `data-*` 属性来代替该 prop。
4703
+ - 禁止在页面内堆叠第二个无界垂直滚动容器 —— 页面级纵向滚动只有一个持有者:结果集页面是 `ApplicationDataDisplay` 的主体,其余页面是 Content Canvas。
4125
4704
 
4126
4705
  ### ApplicationQueryToolbar
4127
4706
 
@@ -4129,29 +4708,40 @@ Content Canvas 宿主自身内边距为零,因此不会产生双重外边距
4129
4708
 
4130
4709
  **数据控制区** —— 统一承载 Canvas 五层模型的 L3 业务视图与 L4 数据控制。
4131
4710
 
4132
- ### 固定三行契约
4711
+ #### 固定三行契约
4133
4712
 
4134
4713
  | 行 | 内容 | 渲染条件 |
4135
4714
  |---|---|---|
4136
4715
  | 1 | 业务视图标签(2–4 个稳定工作视角) | 仅当确有视图 |
4137
- | 2 | 结果摘要 │ 搜索 + 常用筛选 + 更多 │ 排序 + 呈现设置 | always |
4138
- | 3 | 已生效筛选标签(可移除 + 重置全部) | 仅当有筛选生效 |
4716
+ | 2 | 结果摘要 │ 搜索 + 排序 + 常用筛选 + 更多 ‖ 视图切换 + 呈现设置 | always |
4717
+ | 3 | 已生效筛选标签(可移除 + 「清空」全部) | 仅当有筛选生效 |
4718
+
4719
+ 第 2 行左组的顺序固定为「结果摘要 → 搜索 → 排序 → 常用筛选 → 更多」—— 排序紧跟搜索、
4720
+ 在筛选之前(GAP Design kit「数据筛选搜索」的标注;业财平台 round-01 裁决,2026-11-10)。
4721
+ 右组只放 `viewModeSwitch` 与呈现设置。
4139
4722
 
4140
- ### ⚠ 搜索
4723
+ 几何按 kit「数据筛选搜索」(84:2803):三行之间 8;第 2 行左组控件之间 4,摘要与搜索之间
4724
+ 由组件画一条 1×20 的线条色竖线(只在传了 `resultSummary` 时出现);右组之间 4;左右两组之间 12。
4725
+ 调用方传入的排序与筛选控件不得自带外边距 —— 间隔由组件统一给出。
4726
+
4727
+ #### ⚠ 搜索
4141
4728
  **通过 Enter 或明确的搜索动作提交,绝不逐字实时搜索。**
4142
4729
 
4143
- ### ⚠ 筛选
4730
+ #### ⚠ 筛选
4144
4731
  工具栏内常驻 **2–3 个**常用筛选,其余进「更多筛选」,
4145
4732
  由「应用」提交,并**回写到第三行的标签**。
4146
4733
 
4147
- ### ⚠ 呈现设置按钮必须按当前呈现方式命名
4148
- DataTable → 列设置 · CardList → 卡片设置 · KanbanBoard → 看板设置 ·
4734
+ #### ⚠ 呈现设置按钮必须按当前呈现方式命名
4735
+ 按钮是 32×32 纯图标(16px `sliders-horizontal`,白底描边、圆角 12,kit「列表工具」),
4736
+ 名字落在可访问名与悬停提示上:
4737
+ DataTable → 列设置 · RecordList → 列表设置 · CardList → 卡片设置 · KanbanBoard → 看板设置 ·
4149
4738
  Calendar → 日历设置 · Chart → 图表设置 · Timeline → 时间轴设置。
4150
- **通用的「视图设置」被明令禁止。**
4151
- 无真实可配置项时(`hasPresentationSettings={false}`)按钮不渲染且不占位。
4739
+ **通用的「视图设置」被明令禁止**,「自定义」同理 —— 它不说明设的是什么。
4740
+ 无真实可配置项时(`hasPresentationSettings={false}`,或不传
4741
+ `onPresentationSettings`)按钮不渲染且不占位。
4152
4742
  每种呈现方式**各自独立存储**其设置。
4153
4743
 
4154
- ### ⚠ Page Mode Switch 不属于本组件
4744
+ #### ⚠ Page Mode Switch 不属于本组件
4155
4745
  它位于上下文区(`ApplicationPageHeader`)。
4156
4746
  `viewModeSwitch` **仅用于 SPLIT 右栏**,且只改 `dataPresentation`,永不改 `pageMode`。
4157
4747
 
@@ -4162,20 +4752,22 @@ Calendar → 日历设置 · Chart → 图表设置 · Timeline → 时间轴设
4162
4752
  | `businessViews` | `BusinessViewTab[]` | 否 | 业务视图标签集合。2–4 个 |
4163
4753
  | `businessView` | `string` | 否 | 当前业务视图 |
4164
4754
  | `onBusinessViewChange` | `(value: string) => void` | 否 | 业务视图变化回调 |
4165
- | `resultSummary` | `ReactNode` | 否 | 结果摘要,如「共 1,284 条」 |
4755
+ | `resultSummary` | `ReactNode` | 否 | 结果摘要,渲染为一枚胶囊,如 `<>共 <strong>1,284</strong> 条</>`。 数字用 `<strong>` 包裹即加粗为正文色;有勾选时紧随写已选数(「已选 3 条」)。 |
4166
4756
  | `searchValue` | `string` | 否 | 搜索框受控值 |
4167
4757
  | `onSearchChange` | `(event: ChangeEvent<HTMLInputElement> \| { target: { value: string } }) => void` | 否 | 搜索框值变化回调 |
4168
4758
  | `onSearchSubmit` | `(value: string) => void` | 否 | 搜索提交回调。**仅 Enter 触发** |
4169
- | `searchPlaceholder` | `string` | 否 | 搜索占位文字。应写明搜索范围 |
4759
+ | `searchPlaceholder` | `string` | 否 | 搜索占位文字。应写明搜索范围,如「搜索任务名称或编号」。 **无默认值**(05 · P1-7):此前缺省为 `'搜索'`,不传即违反 SearchField 「不得写成不含范围的『搜索』」,且同时充当可访问名。缺省时占位文字取 `searchAriaLabel`,二者都缺省则不显示占位文字。 |
4760
+ | `searchAriaLabel` | `string` | 否 | 搜索框的可访问名,必须写明搜索范围。优先级:本 prop → `searchPlaceholder`。 占位文字写示例、可访问名写范围时分开传;二者同文时只传 `searchPlaceholder` 即可。两者都缺省时可访问名回落为「搜索当前结果」并在开发构建下告警一次 —— SearchField 的 `ariaLabel` 必填,不能留空,而写明范围只有调用方做得到(05 · P1-7) |
4170
4761
  | `commonFilters` | `ReactNode` | 否 | 常用筛选,传 2–3 个 `ApplicationFilterMenu` |
4171
- | `moreFilters` | `ReactNode` | 否 | 「更多筛选」触发器,通常是 `Collapsible` 或 `Popover` |
4172
- | `sort` | `ReactNode` | 否 | 排序控件 |
4762
+ | `moreFilters` | `ReactNode` | 否 | 「更多筛选」触发器,一律是 `Popover` 承载的 `ApplicationFilterList`;不得用 `Collapsible` 就地展开(06 · D-4) |
4763
+ | `sort` | `ReactNode` | 否 | 排序控件,传 `Select`,渲染在搜索框之后、常用筛选之前。 DataTable 呈现下表头排序是第二入口,两处共享同一份排序状态(07 · C-2) |
4173
4764
  | `appliedTags` | `AppliedFilterTag[]` | 否 | 已生效的筛选标签 |
4174
4765
  | `onRemoveTag` | `(id: string) => void` | 否 | 移除单个标签回调 |
4175
- | `onResetTags` | `() => void` | 否 | 重置全部筛选回调 |
4766
+ | `onResetTags` | `() => void` | 否 | 清空全部筛选回调。按钮文案为「清空」,与筛选标签同款胶囊 |
4176
4767
  | `presentation` | `DataPresentation` | 否 | 当前呈现方式。**决定呈现设置按钮的文案** |
4177
- | `hasPresentationSettings` | `boolean` | 否 | 是否有可配置的呈现设置。false 时按钮不渲染且不占位 |
4178
- | `onPresentationSettings` | `() => void` | 否 | 呈现设置点击回调 |
4768
+ | `hasPresentationSettings` | `boolean` | 否 | 是否有可配置的呈现设置。false 时按钮不渲染且不占位。 缺省时按是否提供 `onPresentationSettings` 推断(05 · P1-7):此前缺省为 `true`,不传即渲染一个点了没反应的设置按钮,默认值站在了违规一边。 显式传入仍优先 |
4769
+ | `onPresentationSettings` | `(event: MouseEvent<HTMLButtonElement>) => void` | 否 | 呈现设置点击回调。参数是按钮的点击事件,`event.currentTarget` 即设置按钮本身, 供调用方把面板锚定在它上面、或关闭后把焦点还给它(06 · P2-6)。 不读参数的无参回调照旧可用 |
4770
+ | `presentationSettingsOpen` | `boolean` | 否 | 呈现设置面板当前是否展开。传入后设置按钮输出 `aria-expanded`,读屏据此报出开合; 不传则不输出 —— 面板由调用方持有,组件无从得知开合,宁可不报也不报错(06 · P2-6) |
4179
4771
  | `viewModeSwitch` | `ReactNode` | 否 | **仅 SPLIT 右栏使用**的视图模式切换器 |
4180
4772
 
4181
4773
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
@@ -4206,8 +4798,8 @@ L3 业务视图标签
4206
4798
 
4207
4799
  **何时改用其他组件。**
4208
4800
  - Page Mode Switch 属于 `ApplicationPageHeader`,不得在此重建。
4209
- - 单个高频筛选维度的触发器改用 `ApplicationFilterMenu`,经 `commonFilters` 传入。
4210
- - 完整的筛选维度面板改用 `ApplicationFilterList`,装进 `Collapsible` 或 `Popover` 后经 `moreFilters` 传入。
4801
+ - 单个高频筛选维度的触发器改用 `ApplicationFilterMenu`,日期区间维度改用 `ApplicationDateRangeFilter`,都经 `commonFilters` 传入。
4802
+ - 完整的筛选维度面板改用 `ApplicationFilterList`,装进 `Popover` 后经 `moreFilters` 传入;不得装进 `Collapsible` 就地展开(06 · D-4)。
4211
4803
  - 纯文本搜索输入已由该组件内置的 `SearchField` 承担,不得在工具栏内另置搜索控件。
4212
4804
  - 分页改用 `ListTablePagination`,它属于 `ApplicationDataDisplay` 的底部。
4213
4805
  - 批量动作改用 `ListBatchActionBar`。
@@ -4216,20 +4808,32 @@ L3 业务视图标签
4216
4808
  - 三行的渲染条件固定:第一行业务视图仅当确有视图时渲染,第二行恒在,第三行仅当有筛选生效时渲染。
4217
4809
  - `businessViews` 传 2–4 个稳定工作视角,`businessView` 与 `onBusinessViewChange` 必须成对提供。
4218
4810
  - 搜索经 `searchValue` 与 `onSearchChange` 受控,提交只经 `onSearchSubmit`,由 Enter 触发。
4219
- - `commonFilters` 常驻 2–3 个 `ApplicationFilterMenu`,其余维度一律收进 `moreFilters`。折叠只改变入口,不移除能力。
4220
- - 生效条件必须回写 `appliedTags`,并同时提供 `onRemoveTag` 与 `onResetTags`。`AppliedFilterTag.label` 为非字符串时必须提供 `labelText`,否则移除按钮的无障碍名称为空。
4221
- - `presentation` 决定呈现设置按钮的文案,必须与 `ApplicationDataDisplay` 的同名 prop 取自同一处状态。
4222
- - 无真实可配置项时传 `hasPresentationSettings={false}`,按钮不渲染且不占位;提供设置时 `onPresentationSettings` 必须一并给出。
4811
+ - 搜索框的可访问名优先取 `searchAriaLabel`,其次取 `searchPlaceholder`,二者至少给一个且必须写明搜索范围;占位文字写示例、可访问名写范围时分开传,同文时只传 `searchPlaceholder`。`searchPlaceholder` 没有默认值,缺省时占位文字取 `searchAriaLabel`;二者都缺省时可访问名回落为「搜索当前结果」并在开发构建下告警一次。
4812
+ - `commonFilters` 常驻 2–3 个 `ApplicationFilterMenu` 或 `ApplicationDateRangeFilter`,其余维度一律收进 `moreFilters`;常用筛选里出现的维度不再进更多筛选(07 · C-11)。折叠只改变入口,不移除能力。
4813
+ - 第二行左组的顺序固定为「结果摘要 → 搜索 → 排序 → 常用筛选 → 更多」,右组只放 `viewModeSwitch` 与呈现设置(GAP Design kit「数据筛选搜索」:排序在搜索后面、筛选前面;业财平台 round-01 裁决)。
4814
+ - 间隔按 kit「数据筛选搜索」:三行之间 8;第二行左组控件之间 4、右组之间 4、左右两组之间 12;摘要与搜索之间由组件画一条 1×20 的线条色竖线,只在传了 `resultSummary` 时出现。间隔与竖线都由组件给出,传入的排序与筛选控件不带外边距。
4815
+ - `sort` 传 `Select`(无可见标签,用 `aria-label` 命名)。DataTable 呈现下表头排序是第二入口:`Table` 的 `sort` 与这里的 `Select` 读写同一份排序状态,任一处改动另一处同步回显(07 · C-2)。
4816
+ - `resultSummary` 渲染为一枚胶囊,数字用 `<strong>` 包裹即加粗为正文色,如 `<>共 <strong>46</strong> 张</>`;有勾选时紧随写已选数。
4817
+ - 生效条件必须回写 `appliedTags`,并同时提供 `onRemoveTag` 与 `onResetTags`;清除全部的按钮文案为「清空」,与筛选标签同款胶囊。`AppliedFilterTag.label` 为非字符串时必须提供 `labelText`,否则移除按钮的无障碍名称为空。
4818
+ - 呈现设置按钮按 kit 是 32×32 纯图标(16px `sliders-horizontal`,白底描边、圆角 12),名字落在可访问名与悬停提示上;`presentation` 决定这个名字,必须与 `ApplicationDataDisplay` 的同名 prop 取自同一处状态。
4819
+ - `hasPresentationSettings` 缺省时按是否提供 `onPresentationSettings` 推断:给了回调即渲染设置按钮,不给即不渲染且不占位;显式传入优先。无真实可配置项时不传回调即可,或显式传 `hasPresentationSettings={false}`。
4820
+ - `onPresentationSettings` 收到设置按钮的点击事件,`event.currentTarget` 即按钮元素,可作面板锚点或关闭后的焦点归还目标;不读参数的无参回调照旧可用。面板由调用方持有,其开合状态经 `presentationSettingsOpen` 回传,按钮据此输出 `aria-expanded` —— 二者应当成对提供,不传则按钮不报开合。
4821
+ - 呈现设置面板一律用 `Popover` 承载、锚定在呈现设置按钮上,与 `moreFilters` 同一承载;不得改用 `Sheet`、`Dialog` 或 `Drawer`(07 · C-7)。
4223
4822
  - 每种呈现方式各自独立存储其设置,切换呈现方式不得沿用上一种的设置。
4224
4823
  - `viewModeSwitch` 仅允许出现在服务 SPLIT 右栏的那一份工具栏上,且只改 `dataPresentation`。
4225
- - 搜索框固定 240px,该组件自身不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 负责。
4824
+ - 搜索框宽 240px,白底、1px 描边、圆角 12(GAP Design kit),占位文字写短的搜索范围;确需更宽时调用方覆盖 `--mh-query-toolbar-search-max-width`。放进 `ApplicationPageLayoutContainer` 时,该组件与数据展示区同处一张白卡(圆角 20、内边距 12),自身不再画卡片;单独使用时自身就是那张卡的上半。该组件不带外边距,与相邻区域的间距由 `ApplicationPageLayoutContainer` 负责。
4825
+ - 数据展示区的 `state` 为 `no-permission` 或 `not-found` 时不渲染本组件;处于 `error` 时保留,条件改动后重新查询(07 · C-6)。
4226
4826
 
4227
4827
  **禁止 / 使用边界。**
4228
4828
  - 禁止逐字实时搜索,不得在 `onSearchChange` 中直接发起查询。
4229
- - 禁止出现通用的「视图设置」按钮 —— 按钮必须按当前呈现方式命名:`列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
4829
+ - 不得同时省略 `searchAriaLabel` 与 `searchPlaceholder`,也不得把任一写成不含范围的「搜索」。
4830
+ - 不得显式传 `hasPresentationSettings` 为 true 而不给 `onPresentationSettings` —— 那是一个点了没反应的按钮。
4831
+ - 禁止出现通用的「视图设置」或「自定义」按钮 —— 按钮必须按当前呈现方式命名:`列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
4832
+ - 不得把排序挪回右组,也不得把它排在常用筛选之后。
4833
+ - 不得在摘要与搜索之间自行再画分隔线,也不得给传入的排序与筛选控件加外边距来改间隔。
4230
4834
  - 不得在该组件内渲染 Page Mode Switch,也不得用 `viewModeSwitch` 改动 `pageMode`。
4231
4835
  - 不得让筛选状态只存在于菜单或面板内部而不回写 `appliedTags`。
4232
- - 禁止为同一个结果集放置两份工具栏,也不得把搜索、筛选、排序下沉进 `ApplicationDataDisplay`。
4836
+ - 禁止为同一个结果集放置两份工具栏,也不得把搜索、筛选、排序下沉进 `ApplicationDataDisplay`。表头排序不算下沉,但不得另持一份与工具栏 `sort` 分离的排序状态。
4233
4837
 
4234
4838
  ### ApplicationRecordDetailBody
4235
4839
 
@@ -4249,6 +4853,7 @@ L3 业务视图标签
4249
4853
  |---|---|:---:|---|
4250
4854
  | `summary` | `ReactNode` | 否 | 对象头:标题、状态徽标、关键标识 |
4251
4855
  | `sections` | `DetailSection[]` | 否 | 分节集合,按顺序渲染 |
4856
+ | `aside` | `DetailSection` | 否 | 侧栏分节。提供时主体变为两栏:左栏(`summary` + `sections`)弹性伸展, 右栏固定 360px,两栏各是一张白卡,间距 12。用于「处理记录」「审批流转」这类 **伴随主内容、随它一起看**的内容。 只放一个分节;**不得**把主要字段分节挪进侧栏,也不得用它放对象级动作 (动作在载体的动作区)。可用宽度不足 960px 时侧栏落到主栏下方。 |
4252
4857
 
4253
4858
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
4254
4859
 
@@ -4258,8 +4863,8 @@ L3 业务视图标签
4258
4863
 
4259
4864
  | prop | 类型 | 必填 | 说明 |
4260
4865
  |---|---|:---:|---|
4261
- | `label` | `ReactNode` | 是 | 字段名,12/16 label 色 |
4262
- | `value` | `ReactNode` | 是 | 字段值,14/20,长值自动断行 |
4866
+ | `label` | `ReactNode` | 是 | 字段名,14/20 label 色,固定 160px 宽,与值横排 |
4867
+ | `value` | `ReactNode` | 是 | 字段值,14/20 medium 字重,长值自动断行 |
4263
4868
  | `key` | `string` | 否 | React key。`label` 为非字符串时**必须**提供。见 M8 |
4264
4869
 
4265
4870
  **`DetailSection`**
@@ -4269,7 +4874,7 @@ L3 业务视图标签
4269
4874
  | prop | 类型 | 必填 | 说明 |
4270
4875
  |---|---|:---:|---|
4271
4876
  | `key` | `string` | 否 | React key。`title` 为非字符串时**必须**提供。见 M8 |
4272
- | `title` | `ReactNode` | 是 | 分节标题,16/24 medium 字重 |
4877
+ | `title` | `ReactNode` | 是 | 分节标题,16/20 medium 字重,左侧带 2×14 强调色竖条 |
4273
4878
  | `fields` | `DetailField[]` | 否 | 字段列表,自适应多列网格排布 |
4274
4879
  | `content` | `ReactNode` | 否 | 自定义内容,排在字段之后。用于时间轴、附件列表等 |
4275
4880
  | `action` | `ReactNode` | 否 | 分节级动作,右对齐于标题行 |
@@ -4288,8 +4893,9 @@ L3 业务视图标签
4288
4893
  **组合约定。**
4289
4894
  - `summary` 承载对象头:标题、状态徽标(应为 `Badge`)、关键标识。
4290
4895
  - `sections` 按数组顺序渲染。`DetailSection.title` 为非字符串时必须提供 `key`;契约同样为 `DetailField` 登记了 `key`,`label` 为非字符串时必须提供。
4291
- - 字段以 `dl` / `dt` / `dd` 输出为名值对,列数随可用宽度自适应,字段列最窄 240px —— 680px 抽屉里排两列,独立详情页全宽下排更多列,两个载体不需要各写一套。
4292
- - 分节级动作经 `DetailSection.action` 右对齐于标题行;对象级主动作属于载体,写在抽屉右下角的固定动作区。
4896
+ - 字段以 `dl` / `dt` / `dd` 输出为横排名值对:字段名 160px 宽、14/20 三级文字色,值 14/20 medium。列数随可用宽度自适应,字段列最窄 360px,两个载体不需要各写一套。主体内容落在白卡里,载体负责灰底;分节间距 16,分节标题带 2×14 强调色竖条。
4897
+ - 伴随主内容一起看的一个分节(处理记录、审批流转)经 `aside` 传入,主体变为两栏:左栏弹性、右栏 360px,间距 12;可用宽度不足 960px 时侧栏落到主栏下方。主要字段分节不得挪进 `aside`。
4898
+ - 分节级动作经 `DetailSection.action` 右对齐于标题行;对象级主动作属于载体:抽屉写在页头右侧的动作区,独立详情页写在 `ApplicationPageHeader` 的 `actions`。
4293
4899
  - 时间轴、附件列表等非名值对内容走 `DetailSection.content`,排在字段之后。
4294
4900
  - 该组件不带外边距也不自持滚动,留白与滚动一律由载体负责。
4295
4901
  - 允许存在抽屉专用变体的条件是:超过 3 个分节、超过 15 个字段、动作流程有实质差异、性能要求不同,四者任一成立。即便成立,该变体只保留核心内容。
@@ -4301,6 +4907,7 @@ L3 业务视图标签
4301
4907
  - 不得在分节顺序可变时省略 `key` —— 重排序会导致内部状态错位。
4302
4908
  - 禁止在该组件内部再嵌套一个 `ApplicationRecordDetailBody`。
4303
4909
  - 不得在该组件内承载搜索、筛选、排序或分页。
4910
+ - 不得向 `aside` 放对象级动作或第二组主要字段,侧栏只放一个伴随分节。
4304
4911
 
4305
4912
  ### ApplicationSplitListSidebar
4306
4913
 
@@ -4311,12 +4918,12 @@ SPLIT 页面模式的**左栏**。
4311
4918
  ⚠ **它的唯一职责是「你在哪」,不是「你看到什么」。**
4312
4919
  只承载:目录搜索、定位器/目录本身、目录设置。
4313
4920
 
4314
- ### ⚠ 禁止出现在这里
4921
+ #### ⚠ 禁止出现在这里
4315
4922
  - 第二个 Page Mode Switch(它在上下文区)
4316
4923
  - 右栏的 View Mode Switch
4317
4924
  - 呈现设置(那是右栏的事)
4318
4925
 
4319
- ### ⚠ 当前对象的合法取值
4926
+ #### ⚠ 当前对象的合法取值
4320
4927
  只能是 `null` 或**当前结果集中一个有权限的对象**。
4321
4928
  **绝不为了填满右栏而自动选中第一行** —— `null` 是完全合法的状态。
4322
4929
 
@@ -4328,8 +4935,9 @@ SPLIT 页面模式的**左栏**。
4328
4935
  |---|---|:---:|---|
4329
4936
  | `search` | `ReactNode` | 否 | 目录搜索,应传 `SearchField` |
4330
4937
  | `items` | `SplitSidebarItem[]` | 否 | 目录项集合 |
4331
- | `value` | `string` | 否 | 当前选中项。`undefined` / `null` 是合法状态 |
4332
- | `onValueChange` | `(value: string) => void` | 否 | 选中项变化回调 |
4938
+ | `value` | `string \| null` | 否 | 当前选中项。`undefined` 与 `null` 都表示未定位,是合法状态 |
4939
+ | `onValueChange` | `(value: string) => void` | 否 | 选中项变化回调。只回传条目值,不回传 `null` —— 取消定位走 `onClear` |
4940
+ | `onClear` | `() => void` | 否 | 取消定位回调(06 · P2-1)。提供时**再次选择当前项即取消定位**(点击或 Enter / 空格), 调用方在此把 `value` 写回 `null`;当前项另带描述「再次选择取消定位」。 不提供时再次选择当前项照旧回调 `onValueChange`,不会取消定位 |
4333
4941
  | `settings` | `ReactNode` | 否 | 目录设置触发器。**与呈现设置是两回事**,不要混用 |
4334
4942
  | `footer` | `ReactNode` | 否 | 栏底内容 |
4335
4943
  | `width` | `number \| string` | 否 | 宽度。默认 360px,Compact 档 300px |
@@ -4361,13 +4969,15 @@ SPLIT 左栏的单个目录项
4361
4969
 
4362
4970
  **组合约定。**
4363
4971
  - 该组件受控:`value` 与 `onValueChange` 必须成对提供。
4364
- - 当前对象的合法取值只有两种:空,或当前结果集中一个有权限的对象。
4972
+ - 当前对象的合法取值只有两种:空,或当前结果集中一个有权限的对象。空写作 `value={null}`(或不传),不得用空串或某个哨兵值冒充。
4973
+ - 取消定位的出口是 `onClear`:提供后再次选择当前项(点击或 Enter / 空格)即回调 `onClear`,调用方在此把 `value` 写回 `null`;`onValueChange` 只回传条目值,从不回传 `null`。这个操作没有可见提示(读屏经当前项的描述「再次选择取消定位」获知),因此可见的出口仍应放在 `footer`,例如「清除定位」按钮,与 `onClear` 写回同一处状态。
4365
4974
  - `SplitSidebarItem.depth` 从 0 起,每级缩进一档。树形目录必须逐项给出 `depth`,否则全部平铺。
4366
4975
  - `SplitSidebarItem.icon` 应传 `Icon`,字形须在 `src/icon/registry.json` 中登记。
4367
- - `width` 只在需要覆盖已登记宽度时传;不传则取 `--ui-sidebar-list-width`,三档密度自动生效。
4368
- - 该组件自身滚动,右侧分隔边框由它持有。调用方不得再加外边距或第二条分隔线。
4976
+ - `width` 只在需要覆盖已登记宽度时传;不传则取 `--ui-sidebar-list-width`,三档密度自动生效。放进 `Resizable` 的左栏时宽度自动交给栏位(填满栏宽、随拖拽变化),调用方不必再传 `width="100%"`;栏宽由 `Resizable` 的 `size` 决定,要跟随密度档就给它传 `'var(--ui-sidebar-list-width)'`。
4977
+ - 该组件自身滚动,右侧分隔边框由它持有。调用方不得再加外边距或第二条分隔线。放进 `Resizable` 的左栏等高度确定的父级时,它在父级内填满高度,目录区滚动、`footer` 贴底,调用方不必再补 `block-size`。
4978
+ - 目录项按 `depth` 渲染为嵌套列表,读屏可报出层级;它不是 `role="tree"`,没有展开 / 收起。
4369
4979
  - `settings` 是目录设置,与右栏的呈现设置是两回事,两者不得互相顶替。
4370
- - 目录项的计数经 `count` 传入,不得拼进 `label`。
4980
+ - 目录项的计数经 `count` 传入,不得拼进 `label`;条目名读作「标签,N 条」。
4371
4981
 
4372
4982
  **禁止 / 使用边界。**
4373
4983
  - 禁止在左栏放置第二个 Page Mode Switch。
@@ -4386,7 +4996,8 @@ SPLIT 左栏的单个目录项
4386
4996
 
4387
4997
  适用于表格列数过剩、但行仍需扫视的场景。
4388
4998
 
4389
- ⚠ **记录级动作位于行尾**,且必须阻止冒泡 —— 点动作绝不能顺带打开详情。
4999
+ ⚠ **记录级动作位于行尾** —— 点动作绝不能顺带打开详情。行点击忽略来自行内
5000
+ 可交互元素的事件,`renderRow` 接管时同样成立,调用方不必手动阻止冒泡。
4390
5001
  勾选记录应唤出 `ListBatchActionBar`。
4391
5002
 
4392
5003
  ⚠ 与 DataTable 一样,它的呈现设置按钮读作**「列设置」**。
@@ -4398,11 +5009,11 @@ SPLIT 左栏的单个目录项
4398
5009
  | prop | 类型 | 必填 | 说明 |
4399
5010
  |---|---|:---:|---|
4400
5011
  | `records` | `R[]` | 否 | 记录集合 |
4401
- | `selectable` | `boolean` | 否 | 启用行选择 |
5012
+ | `selectable` | `boolean` | 否 | 启用行选择。为 true 时行首渲染勾选框,列表顶部另有一行吸顶的全选框 (`ListSelectionCheckbox scope="all"`,06 · P3-2):全选 / 全不选只作用于本次传入的 `records`,`selected` 里不在 `records` 中的 id(如其他页已选)原样保留 |
4402
5013
  | `selected` | `string[]` | 否 | 已选记录 id 集合 |
4403
5014
  | `onSelectedChange` | `(ids: string[]) => void` | 否 | 选中集合变化回调 |
4404
- | `activeId` | `string` | 否 | SPLIT 右栏或抽屉流程中的当前对象 id |
4405
- | `onOpen` | `(record: R) => void` | 否 | 打开记录回调。点击行主体触发 |
5015
+ | `activeId` | `string` | 否 | SPLIT 右栏或抽屉流程中的当前对象 id。该行输出 `aria-current="true"` |
5016
+ | `onOpen` | `(record: R) => void` | 否 | 打开记录回调。点击行主体、或行聚焦时按 Enter / 空格触发 |
4406
5017
  | `renderRow` | `(record: R) => ReactNode` | 否 | 默认行结构不适用时,完全接管行主体的渲染 |
4407
5018
 
4408
5019
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
@@ -4418,7 +5029,7 @@ SPLIT 左栏的单个目录项
4418
5029
  | `meta` | `ReactNode` | 否 | 元信息行,如编号、负责人 |
4419
5030
  | `status` | `ReactNode` | 否 | 状态,通常是一个 `Badge` |
4420
5031
  | `value` | `ReactNode` | 否 | 关键数值 |
4421
- | `actions` | `ReactNode` | 否 | 行尾的记录级动作。**必须阻止事件冒泡**,以免误触打开详情 |
5032
+ | `actions` | `ReactNode` | 否 | 行尾的记录级动作。组件包一层阻止事件冒泡,点动作不会误触打开详情 |
4422
5033
 
4423
5034
  **用途。** 非表格形态的结构化列表,承载业务记录行 —— 每行是「标题 + 元信息 + 状态 + 关键数值 + 行尾动作」这一固定结构。
4424
5035
 
@@ -4431,13 +5042,13 @@ SPLIT 左栏的单个目录项
4431
5042
  - 消息流与活动流的条目改用 `Message`,会话气泡改用 `Bubble`。
4432
5043
  - 六种系统状态的承载、批量动作条与分页的挂载,由宿主 `ApplicationDataDisplay` 负责,不在本组件内解决。
4433
5044
 
4434
- **组合约定。** 本组件必须放进 `ApplicationDataDisplay` 的 `children`,仅在 `state="ready"` 时渲染。外边距由 `ApplicationPageLayoutContainer` 持有(`--ui-page-gutter` 与 `--ui-section-gap`),本组件与其行一律不自带 margin。`selectable` 为 true 时行首由组件自动渲染 `ListSelectionCheckbox`,调用方不得再自行插一个;`selected` 与 `onSelectedChange` 必须成对提供,本组件的选择是受控的。选择集合非空时,调用方必须把 `ListBatchActionBar` 交给 `ApplicationDataDisplay` 的 `batchBar`。`activeId` 与选择集合是两回事:前者是 SPLIT 右栏或抽屉流程中的当前对象,只有一个,视觉上是选中底色;后者是勾选集合,视觉上是 4% 淡洗。`RecordListItem.actions` 由组件包一层并阻止点击冒泡;一旦改用 `renderRow` 接管行主体,阻止冒泡的责任转移给调用方。行高 56px,容得下标题与元信息两行。呈现设置按钮读作「列设置」,且它属于 `ApplicationQueryToolbar`,不属于本组件。
5045
+ **组合约定。** 本组件必须放进 `ApplicationDataDisplay` 的 `children`,仅在 `state="ready"` 时渲染。外边距由 `ApplicationPageLayoutContainer` 持有(`--ui-page-gutter` 与 `--ui-section-gap`),本组件与其行一律不自带 margin。`selectable` 为 true 时行首由组件自动渲染 `ListSelectionCheckbox`,列表顶部另有一行吸顶的全选框(`scope="all"`,半选态按本次 `records` 里已选的条数派生),调用方不得再自行插一个行勾选框或全选行;全选 / 全不选只增删本次 `records` 的 id,`selected` 里其他页的选择原样保留,因此 `onSelectedChange` 的结果可以直接写回,不必再与别页的选择合并。可选时根节点是 `role="group"`、条目在内层的 list 里,`aria-label` 照旧传给本组件,即为该组与列表的名字。`selected` 与 `onSelectedChange` 必须成对提供,本组件的选择是受控的。选择集合非空时,调用方必须把 `ListBatchActionBar` 交给 `ApplicationDataDisplay` 的 `batchBar`。`activeId` 与选择集合是两回事:前者是 SPLIT 右栏或抽屉流程中的当前对象,只有一个,视觉上是选中底色;后者是勾选集合,视觉上是 4% 淡洗。行点击与 Enter / 空格忽略来自行内可交互元素的事件 —— 按钮、链接、表单控件、勾选框、菜单与菜单项(含经 portal 渲染的菜单面板)都不会顺带触发 `onOpen`;`RecordListItem.actions` 另由组件包一层阻止冒泡,连同动作区的留白一起不开行。改用 `renderRow` 接管行主体时同样成立,调用方不必再手动阻止冒泡。给了 `onOpen` 的行可聚焦、Enter / 空格打开,行保留列表项语义;`activeId` 那一行输出 `aria-current="true"`。行首勾选框的可访问名为「选择」加记录标题(`renderRow` 接管且 `title` 不是纯文本时回落为「选择此行」)。行高 56px,容得下标题与元信息两行。`presentation` 取 `RecordList`,不得谎报为 `DataTable`;呈现设置按钮读作「列表设置」,且它属于 `ApplicationQueryToolbar`,不属于本组件。
4435
5046
 
4436
5047
  **禁止 / 使用边界。**
4437
5048
  - 不得在本组件内持有搜索、筛选、排序状态 —— 那些全部属于 `ApplicationQueryToolbar`,数据展示区绝不持有第二套查询状态。
4438
5049
  - 不得把右键菜单作为某个记录级动作的唯一入口,该动作必须同时出现在行尾或详情中。
4439
5050
  - 不得为业务记录另写一套行结构,需要改写行主体时使用 `renderRow`。
4440
- - 禁止在 `renderRow` 返回的行主体里省略阻止冒泡 —— 点动作绝不能顺带打开详情。
5051
+ - 禁止在 `renderRow` 返回的行主体上另挂点击或按键处理来打开详情 —— 打开记录只走 `onOpen`,键盘入口与行内控件的排除由组件统一承担。
4441
5052
  - 不得把分页塞进本组件,分页固定在 `ApplicationDataDisplay` 区域底部。
4442
5053
 
4443
5054
  ### ListBatchActionBar
@@ -4475,7 +5086,7 @@ SPLIT 左栏的单个目录项
4475
5086
  - 破坏性批量动作的确认改用 `AlertDialog`,标题中必须写明受影响对象的数量。
4476
5087
  - 「已办结 3 条」这类事后确认改用 `Sonner`;需要用户处理的局部失败改用 `Alert`。
4477
5088
 
4478
- **组合约定。** 本组件与 `ListSelectionCheckbox` 成对出现 —— 页面提供了行选择能力就必须提供本组件,反之没有选择能力就不得渲染本组件。挂载位置固定为 `ApplicationDataDisplay` 的 `batchBar` 槽位,外边距由该宿主与 `ApplicationPageLayoutContainer` 负责。`count` 必须由选择集合的长度驱动,不得另设计数状态。`onClear` 必须真正清空选择集合,而不仅仅隐藏动作条。`actions` 内一律传 `Button`,右对齐由组件负责。区带高度 44px,比 32px 的工具栏行高一档 —— 这是区带尺度,不在控件高度标尺(24 / 28 / 32 / 40)上。
5089
+ **组合约定。** 本组件与 `ListSelectionCheckbox` 成对出现 —— 页面提供了行选择能力就必须提供本组件,反之没有选择能力就不得渲染本组件。挂载位置固定为 `ApplicationDataDisplay` 的 `batchBar` 槽位,外边距由该宿主与 `ApplicationPageLayoutContainer` 负责。`count` 必须由选择集合的长度驱动,不得另设计数状态。`onClear` 必须真正清空选择集合,而不仅仅隐藏动作条。`actions` 内一律传 `SystemButton`,右对齐由组件负责。区带高度 44px,比 32px 的工具栏行高一档 —— 这是区带尺度,不在控件高度标尺(24 / 28 / 32 / 40)上。
4479
5090
 
4480
5091
  **禁止 / 使用边界。**
4481
5092
  - 不得把批量动作条放进 Shell 的任何一带 —— 批量动作作用于当前选中的那些行,放远了读者看不出它作用于什么。
@@ -4491,9 +5102,14 @@ SPLIT 左栏的单个目录项
4491
5102
 
4492
5103
  DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后的列表。
4493
5104
 
4494
- 推荐宽度 680px,底部动作区固定。
5105
+ 推荐宽度 680px。
5106
+
5107
+ 页头(GAP Design kit「抽屉 / 常规」;业财平台 round-01 裁决,2026-11-10):48 高、左右 12、
5108
+ 0.5px 下边线;左侧标题与副标题同行 14/20,右侧依次为主动作、次要动作组、32×32 纯图标
5109
+ 关闭键,间隔 4。**没有底部动作区** —— 动作一律在页头。
4495
5110
 
4496
- ⚠ **它说「关闭」,独立详情页说「返回」。** 深链接只指向独立详情页。
5111
+ ⚠ **它的关闭键可访问名是「关闭」,独立详情页的退出是写着「返回」的按钮。**
5112
+ 深链接只指向独立详情页。
4497
5113
 
4498
5114
  ⚠ **关闭时必须还原来源页面的**:业务视图、搜索、筛选、排序、分页、
4499
5115
  页面模式、当前对象、滚动位置。少还原任何一项都算缺陷。
@@ -4509,8 +5125,9 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4509
5125
  | `subtitle` | `ReactNode` | 否 | 副标题,通常是对象编号 |
4510
5126
  | `status` | `ReactNode` | 否 | 对象状态徽标,紧邻标题 |
4511
5127
  | `width` | `number` | 否 | 宽度,单位 px。推荐 680 |
4512
- | `primaryAction` | `ReactNode` | 否 | **唯一**的主对象动作,固定在右下角 |
4513
- | `secondaryActions` | `ReactNode` | 否 | 次要动作组 |
5128
+ | `side` | `'left' \| 'right'` | 否 | 从哪一侧滑出。默认 `right`。来源在右侧(右栏、周末日格)时传 `left`, 免得 680px 的抽屉正好盖住刚点的那一处(06 · P2-8) |
5129
+ | `primaryAction` | `ReactNode` | 否 | **唯一**的主对象动作,渲染在页头右侧动作区的最左(kit:主按钮在前) |
5130
+ | `secondaryActions` | `ReactNode` | 否 | 次要动作组,渲染在主动作之后、关闭键之前。超过两三个时收进「更多」 |
4514
5131
  | `onClose` | `() => void` | 否 | 关闭回调。**必须在此还原来源页面上下文** |
4515
5132
  | `children` | `ReactNode` | 否 | 详情主体,应传 `ApplicationRecordDetailBody` |
4516
5133
 
@@ -4518,23 +5135,25 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4518
5135
 
4519
5136
  **用途。** DETAIL 的抽屉载体 —— 打开一条业务记录的详情,同时保持身后的列表上下文可见。
4520
5137
 
4521
- **何时使用。** 从列表打开单条记录且不希望丢失来源上下文时,该页面必须用本组件。推荐宽度 680px,底部动作区固定不随内容滚动。它与独立详情页共用同一个 `ApplicationRecordDetailBody`,是「一份详情,两个载体」中的抽屉那一个。
5138
+ **何时使用。** 从列表打开单条记录且不希望丢失来源上下文时,该页面必须用本组件。推荐宽度 680px,动作在页头右侧、没有底部动作区。它与独立详情页共用同一个 `ApplicationRecordDetailBody`,是「一份详情,两个载体」中的抽屉那一个。
4522
5139
 
4523
5140
  **何时改用其他组件。**
4524
5141
  - 非业务记录的侧边面板、或不需要已登记详情结构的裸抽屉,改用 Foundation `Drawer`。
4525
- - 设置、帮助、附件预览这类辅助性内容改用 `Sheet` —— 业务对象详情不属于那里。
5142
+ - 帮助、附件预览这类辅助性内容改用 `Sheet` —— 业务对象详情不属于那里;全局设置是二级导航里的设置模块,也不进抽屉。
4526
5143
  - 需要深链接的详情改用独立详情页,深链接永远只指向独立详情页。
4527
5144
  - 分节超过 3 个、字段超过 15 个、动作流程有实质差异或性能要求不同时,改用独立详情页承载完整内容;抽屉侧只保留核心内容。
4528
5145
  - 编辑与新建改用 `ApplicationFormDialog`;不可逆动作的确认改用 `AlertDialog`。
4529
5146
 
4530
- **组合约定。** `children` 必须传 `ApplicationRecordDetailBody`,不得为抽屉另写一份详情主体。`width` 默认 680px;`--application-drawer-width` 的 1280px 是宽 / 全屏变体,需要时经 `width` 显式传入。`primaryAction` 是唯一的主对象动作,固定在右下角,其余一律进 `secondaryActions`。关闭按钮由组件渲染并写作「关闭」,独立详情页写「返回」—— 这是结构区分,不是文案偏好。`onClose` 里调用方必须还原来源页面的八项上下文:业务视图、搜索、筛选、排序、分页、页面模式、当前对象、滚动位置,少还原任何一项都算缺陷。与列表配合时,来源侧用 `ApplicationRecordList` 的 `activeId` 或 `Table` 的 `onRowClick` 标记当前对象。视口边距、Esc、焦点陷阱、焦点恢复与滚动锁定由 Overlay 基座负责,调用方不得再实现一遍。
5147
+ **组合约定。** `children` 必须传 `ApplicationRecordDetailBody`,不得为抽屉另写一份详情主体。`width` 默认 680px;`--application-drawer-width` 的 1280px 是宽 / 全屏变体,需要时经 `width` 显式传入。`side` 默认 `right`;来源在页面右侧(SPLIT 右栏的条目、月格的周末日格)时传 `left`,不得让抽屉盖住刚打开它的那一处。`status` 紧邻抽屉标题,只在**抽屉标题就是对象名**时使用;抽屉标题是页面类型名(「进项发票详情」)、对象名写在 `ApplicationRecordDetailBody` 的 `summary` 里时,状态徽标随对象名放进 `summary`,不传 `status` —— 状态描述的是对象,必须紧邻对象名。抽屉为灰底、无投影,标题与副标题同行、均为 14/20。页头按 GAP Design kit「抽屉 / 常规」:右侧依次为 `primaryAction`、`secondaryActions` 与 32×32 纯图标关闭键,间隔 4,没有底部动作区(业财平台 round-01 裁决)。`primaryAction` 是唯一的主对象动作,其余一律进 `secondaryActions`,超过两三个时收进「更多」。关闭键由组件渲染,可访问名为「关闭」;独立详情页的退出是写着「返回」的按钮(`ApplicationPageHeader` 的 `onBack`)—— 这是结构区分,不是文案偏好。`onClose` 里调用方必须还原来源页面的八项上下文:业务视图、搜索、筛选、排序、分页、页面模式、当前对象、滚动位置,少还原任何一项都算缺陷。与列表配合时,来源侧用 `ApplicationRecordList` 的 `activeId` 或 `Table` 的 `onRowClick` 标记当前对象。视口边距、Esc、焦点陷阱、焦点恢复与滚动锁定由 Overlay 基座负责,调用方不得再实现一遍。
4531
5148
 
4532
5149
  **禁止 / 使用边界。**
4533
5150
  - 不得让深链接指向抽屉 —— 深链接只指向独立详情页。
4534
5151
  - 不得为抽屉与独立详情页各写一份详情主体。
4535
5152
  - 不得在 `onClose` 里做导航跳转 —— 抽屉是叠加层,关闭必须回到来源页面的原状态。
4536
- - 禁止把关闭按钮的文案写成「返回」,也禁止再加第二个退出入口。
5153
+ - 禁止把关闭键的可访问名写成「返回」,也禁止再加第二个退出入口。
5154
+ - 不得在抽屉底部另拼一条动作区 —— 动作一律在页头右侧。
4537
5155
  - 不得渲染第二个 `primaryAction`,主对象动作唯一。
5156
+ - 不得在抽屉标题是页面类型名时把对象状态传进 `status`,状态必须紧邻对象名。
4538
5157
 
4539
5158
  ### ApplicationFormDialog
4540
5159
 
@@ -4542,11 +5161,18 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4542
5161
 
4543
5162
  业务对象的新建与编辑表单对话框。
4544
5163
 
4545
- 已登记宽度:`small` 720px、`large` 960px,**只有这两种**,
4546
- 且**绝不超出有效视口**。
5164
+ 已登记宽度:`small` 720px、`large` 960px、`xlarge` 1280px,**只有这三种**,
5165
+ 且**绝不超出有效视口**。1280 是 GAP Design kit 弹窗宽度区间的上限(业财平台 round-01 裁决)。
4547
5166
 
4548
5167
  字段以 `Field` 子元素传入,默认排布在两列网格上;
4549
- 需要跨列的字段传 `style={{ gridColumn: '1 / -1' }}`。
5168
+ 需要跨列的字段给 `Field` 传 `span="full"`。
5169
+
5170
+ 页头右侧恒有一个纯图标的关闭按钮(可访问名「关闭」),行为等同 `onCancel`,
5171
+ 提交中禁用 —— 与 `Dialog` 一致。
5172
+
5173
+ 外观(GAP Design kit「抽屉弹窗 / 弹窗」188:685,业财平台 round-01 起):面板圆角 20;
5174
+ 48px 灰底页头,标题与关闭键间隔 10;主体灰底、内含一张白卡承载字段网格,字段间距 10;
5175
+ 底部动作区同为灰底、内边距 12、动作间隔 4、顶部 0.5px 分隔线。
4550
5176
 
4551
5177
  ⚠ **提交失败显示为主体顶部的 `Alert`,不是 toast** ——
4552
5178
  用户必须处理的失败绝不能放进转瞬即逝的提示里。
@@ -4557,37 +5183,41 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4557
5183
  |---|---|:---:|---|
4558
5184
  | `open` | `boolean` | 否 | 是否打开。为 false 时渲染 `null` |
4559
5185
  | `title` | `ReactNode` | 否 | 标题 |
4560
- | `description` | `ReactNode` | 否 | 标题下的补充说明 |
4561
- | `size` | `'small' \| 'large'` | 否 | 宽度档位。720px / 960px |
5186
+ | `description` | `ReactNode` | 否 | 补充说明,与标题同行、以 14/20 label 色跟在标题之后。只写一句短语 |
5187
+ | `size` | `'small' \| 'large' \| 'xlarge'` | 否 | 宽度档位。`small` 720px / `large` 960px / `xlarge` 1280px。 `xlarge` 是 GAP Design kit 弹窗宽度区间(680–1280)的上限,用于字段多、需要左右并排 原件与表单的编辑场景(业财平台 round-01 · editor/dialog/width 裁决,2026-11-10) |
4562
5188
  | `columns` | `number` | 否 | 字段网格列数。默认 2 |
4563
5189
  | `submitText` | `string` | 否 | 提交按钮文案 |
4564
5190
  | `cancelText` | `string` | 否 | 取消按钮文案 |
4565
5191
  | `submitting` | `boolean` | 否 | 提交中。阻断重复提交并给出忙态 |
4566
5192
  | `error` | `ReactNode` | 否 | 提交级失败,通常传 `<Alert tone="danger">`,渲染在主体顶部 |
4567
5193
  | `onSubmit` | `() => void` | 否 | 提交回调 |
4568
- | `onCancel` | `() => void` | 否 | 取消回调 |
5194
+ | `onCancel` | `() => void` | 否 | 取消回调。页头关闭按钮、Esc 与遮罩点击同样触发它 |
5195
+ | `secondaryActions` | `ReactNode` | 否 | 底部动作区的附加次要动作,排在「取消」与提交按钮之间,例如逐条编辑时的 「上一张」「下一张」。传 `SystemButton`(`intent="secondary"`)。 **不得**放第二个 primary,也不得放删除类动作 —— 删除不与提交并排出现在页脚。 |
5196
+ | `footerNote` | `ReactNode` | 否 | 底部动作区左侧的一段说明,12/16 label 色,例如「共 100 条,当前第 6 条」。 只写与本次提交相关的上下文;校验错误与提交失败**不得**写在这里(前者在字段、后者是 `error`)。 |
4569
5197
  | `children` | `ReactNode` | 否 | 表单字段,传 `Field` 子元素 |
4570
5198
 
4571
5199
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `title` 已被本组件重新定义或移除。
4572
5200
 
4573
5201
  **用途。** 业务对象新建与编辑的模态表单载体,拥有已登记的字段网格与提交 / 取消语义。
4574
5202
 
4575
- **何时使用。** 用户必须完成或放弃的表单任务一律用本组件。已登记宽度只有 `small` 720px 与 `large` 960px 两档,字段默认排布在两列网格上。提交中由 `submitting` 表达,提交级失败由 `error` 表达。该组件建立在共享 Overlay 基座上,因此自带 Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定。
5203
+ **何时使用。** 用户必须完成或放弃的表单任务一律用本组件。已登记宽度只有 `small` 720px、`large` 960px 与 `xlarge` 1280px 三档(1280 是 GAP Design kit 弹窗宽度区间 680–1280 的上限,业财平台 round-01 裁决),字段默认排布在两列网格上。`xlarge` 只给字段多、需要原件与表单左右并排的编辑场景。提交中由 `submitting` 表达,提交级失败由 `error` 表达。该组件建立在共享 Overlay 基座上,因此自带 Esc 关闭、焦点陷阱、关闭后焦点恢复与背景滚动锁定。
4576
5204
 
4577
5205
  **何时改用其他组件。**
4578
5206
  - 不含表单的聚焦任务(导入映射、确认预览)改用 Foundation `Dialog`。
4579
5207
  - 不可逆动作的确认改用 `AlertDialog` —— 它的遮罩点击不关闭,破坏性确认必须是显式选择。
4580
5208
  - 人员、组织、审核人、通知接收人的目录式选择改用 `PeoplePickerDialog`。
4581
5209
  - 只读的业务对象详情改用 `ApplicationDetailDrawer` 或独立详情页。
4582
- - 设置、帮助、附件预览这类辅助性面板改用 `Sheet`。
4583
- - 字段规模超出两档宽度可承载的范围时,改用独立编辑页承载。
5210
+ - 帮助、附件预览这类辅助性面板改用 `Sheet`;全局设置是二级导航里的设置模块。
5211
+ - 字段规模超出三档宽度可承载的范围时,改用独立编辑页承载。
4584
5212
 
4585
- **组合约定。** 字段一律以 `Field` 子元素传入 `children`,一个 `Field` 管辖一个控件。需要跨列的字段传 `style={{ gridColumn: '1 / -1' }}`;需要单列或三列时改 `columns`,不要用外部 CSS 重排网格。字段级错误交给 `Field` 的 `error`,并且控件自身的 `invalid` 需另行设置 —— 两者不联动。提交级失败传 `error`,内容应是 `<Alert tone="danger">`,由组件渲染在主体顶部、字段网格之前。`submitting` 为 true 时组件禁用主按钮并置忙态,调用方仍须在自己的提交回调里防止重复请求。底部动作区由组件持有,取消在左、主操作在右,文案经 `submitText` / `cancelText` 覆盖。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发,因此它必须是幂等的。视口边距由 Overlay 基座负责,调用方不得再包一层定位容器。
5213
+ **组合约定。** 字段一律以 `Field` 子元素传入 `children`,一个 `Field` 管辖一个控件。需要跨列的字段给 `Field` 传 `span="full"`,不得用内联 `style` 写 `gridColumn`;需要单列或三列时改 `columns`,不要用外部 CSS 重排网格。字段级错误交给 `Field` 的 `error`,并且控件自身的 `invalid` 需另行设置 —— 两者不联动。提交级失败传 `error`,内容应是 `<Alert tone="danger">`,由组件渲染在主体顶部、字段网格之前。主体与底部动作区包在一个 `<form>` 里,主按钮是提交按钮,字段内按 Enter 即提交并调用 `onSubmit`;浏览器自带校验已关闭,字段校验一律走 `Field`。`submitting` 为 true 时组件禁用主按钮并置忙态,同时屏蔽 Esc 与遮罩点击两条关闭路径,取消按钮仍可用;调用方仍须在自己的提交回调里防止重复请求。底部动作区由组件持有,取消在左、主操作在右,文案经 `submitText` / `cancelText` 覆盖;逐条编辑这类需要「上一张」「下一张」的场景经 `secondaryActions` 传入 `SystemButton`(`intent="secondary"`),排在取消与提交之间;与本次提交相关的上下文(「共 100 条,当前第 6 条」)经 `footerNote` 渲染在动作区左侧。页头右侧恒有纯图标的关闭按钮,行为等同取消,提交中禁用。外观按 GAP Design kit「抽屉弹窗 / 弹窗」:面板圆角 20;48px 灰底页头,标题与关闭键间隔 10;主体灰底内含一张白卡承载字段网格,字段间距 10;底部动作区同为灰底,内边距 12、动作间隔 4、顶部 0.5px 分隔线。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发(提交中只剩取消按钮),因此它必须是幂等的。视口边距由 Overlay 基座负责,调用方不得再包一层定位容器。
4586
5214
 
4587
5215
  **禁止 / 使用边界。**
4588
5216
  - 不得把提交失败呈现为 `Sonner` —— 用户必须处理的失败绝不能放进转瞬即逝的提示里。
4589
5217
  - 不得在 `children` 里自行渲染提交与取消按钮,底部动作区由组件持有。
4590
- - 禁止把宽度改到 720px / 960px 两档之外,也禁止让对话框超出有效视口。
5218
+ - 不得经 `secondaryActions` 放第二个 primary 或删除类动作,也不得把校验错误写进 `footerNote`。
5219
+ - 禁止把宽度改到 720px / 960px / 1280px 三档之外,也禁止让对话框超出有效视口。
5220
+ - 不得用 `className` 把面板圆角改回 16 或其他值 —— 四个模态弹窗同取 `--application-radius-dialog`。
4591
5221
  - 不得用本组件承载只读详情,详情有它自己的两个载体。
4592
5222
  - 不得在 `children` 内用内联 style 改写控件自身的边框、高度或圆角。
4593
5223
 
@@ -4596,15 +5226,19 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4596
5226
  `import { ApplicationGlobalActionPanel } from '@moheng-design/ui'` · 契约 `contracts/application-module/overlays/application-global-action-panel.ts`
4597
5227
 
4598
5228
  四个 popover 型全局动作**共享的同一个面板** ——
4599
- 消息 / 待办 / 运行总览 / 风险预警。
5229
+ 消息 / 待办 / 总览 / 风险预警。
4600
5230
 
4601
5231
  ⚠ **一个面板,四套内容。绝不为每个动作单独造一个弹层。**
4602
5232
 
4603
5233
  宽 720px(`--ui-shell-global-action-popover-width`),20px 圆角,
4604
- 最大高 680px,由 16px 边距约束在视口内,在整个 Shell 堆叠之下展开。
5234
+ 最大高 680px,由 16px 边距约束在视口内,在整个 Shell 堆叠之下展开 ——
5235
+ 视口约束按「视口高 − 外壳总高 − 16px」计算,底边不越出视口。
4605
5236
 
4606
- ⚠ **设置**打开的是 Drawer / Sheet,不走本面板;
4607
- 且**绝不能存在第二个设置入口**。
5237
+ 非模态:不锁滚动、不陷阱焦点。**Esc 关闭**由本组件承担(进库内的 Esc 层级栈,
5238
+ 上层浮层先响应),关闭后焦点归还给打开它的全局动作按钮。外点击关闭由调用方判定。
5239
+
5240
+ ⚠ **设置**不走本面板:它让 `ApplicationSecondaryNavigation` 换成设置模块
5241
+ (`onAction` 给它的 `kind` 是 `'module'`);且**绝不能存在第二个设置入口**。
4608
5242
 
4609
5243
  **Props**
4610
5244
 
@@ -4616,8 +5250,12 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4616
5250
  | `activeTab` | `string` | 否 | 当前标签 |
4617
5251
  | `onTabChange` | `(value: string) => void` | 否 | 标签变化回调 |
4618
5252
  | `footer` | `ReactNode` | 否 | 面板底部内容,如「全部标记为已读」 |
4619
- | `emptyState` | `ReactNode` | 否 | 无条目时的空态,应传 `Empty`。文案须区别于无权限与加载失败 |
4620
- | `onClose` | `() => void` | 否 | 关闭回调 |
5253
+ | `state` | `'ready' \| 'loading' \| 'empty' \| 'error' \| 'no-permission'` | 否 | 面板主体的系统状态(06 · P2-18)。`ready` 渲染 `children`,其余渲染对应槽位: `loading` → `loading`、`empty` → `emptyState`、`error` → `error`、 `no-permission` → `noPermission`。缺省时保持原行为:有 `children` 渲染它, 否则渲染 `emptyState` |
5254
+ | `loading` | `ReactNode` | 否 | Loading 状态内容。应传贴近条目结构的 `Skeleton`,而非通用转圈 |
5255
+ | `emptyState` | `ReactNode` | 否 | 无条目时的空态,应传 `Empty`。文案须点明当前标签的口径,区别于无权限与加载失败 |
5256
+ | `error` | `ReactNode` | 否 | Error 状态内容。应说明失败原因并提供重试 |
5257
+ | `noPermission` | `ReactNode` | 否 | No Permission 状态内容。措辞必须区别于空态 |
5258
+ | `onClose` | `() => void` | 否 | 关闭回调。关闭按钮与 Esc 都会调用;外点击由调用方自行调用 |
4621
5259
  | `children` | `ReactNode` | 否 | 面板内容,通常是一组 `Message` |
4622
5260
 
4623
5261
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性,其中 `title` 已被本组件重新定义或移除。
@@ -4632,23 +5270,23 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4632
5270
  | `label` | `ReactNode` | 是 | 标签文字 |
4633
5271
  | `count` | `number` | 否 | 计数 |
4634
5272
 
4635
- **用途。** 消息、待办、运行总览、风险预警这四个 popover 型全局动作共享的同一个面板。
5273
+ **用途。** 消息、待办、总览、风险预警这四个 popover 型全局动作共享的同一个面板。
4636
5274
 
4637
- **何时使用。** 该面板由 `ApplicationPrimaryNavigation` 的右侧动作簇触发,`onAction` 回调的 `kind` 为 `'popover'` 时打开本组件。四个动作复用同一个实例,切换的只是 `title`、`tabs` 与 `children`。它不是模态:背景仍可交互,因此不锁滚动、不陷阱焦点。
5275
+ **何时使用。** 该面板由 `ApplicationPrimaryNavigation` 的右侧动作簇触发,`onAction` 回调的 `kind` 为 `'popover'` 时打开本组件。四个动作复用同一个实例,切换的只是 `title`、`tabs` 与 `children`。它不是模态:背景仍可交互,因此不锁滚动、不陷阱焦点;但打开时焦点移入面板的首个可聚焦元素,Esc 关闭由本组件承担,并与库内其他浮层共用同一个 Esc 层级栈(上层浮层先响应),关闭后焦点归还给打开它的全局动作按钮。由于不陷阱焦点,面板在 DOM 中的挂载位置决定从它 Tab 出去之后的顺序,建议紧跟触发它的全局动作挂载。
4638
5276
 
4639
5277
  **何时改用其他组件。**
4640
- - 设置改用 `Drawer` 或 `Sheet` —— `onAction` 对它给出的 `kind` 是 `'drawer'`,它不走本面板。
5278
+ - 设置改用 `ApplicationSecondaryNavigation` 的设置模块 —— `onAction` 对它给出的 `kind` 是 `'module'`,它不走本面板。
4641
5279
  - 页面内的锚定浮层(常用筛选、更多筛选、呈现设置)改用 `Popover`,那是 Canvas 的事。
4642
5280
  - 必须完成或放弃的聚焦任务改用 `Dialog` 或 `ApplicationFormDialog`。
4643
5281
  - 业务页面内容一律留在 Canvas,不进入 Shell 层的任何浮层。
4644
5282
 
4645
- **组合约定。** `open` 与 `title` 必须与 `ApplicationPrimaryNavigation` 的 `activeAction` 同步,四个动作绝不各造一个弹层。`tabs` 传 `GlobalActionTab`(`value` / `label` / `count`),当前项由 `activeTab` 受控、`onTabChange` 回写。`children` 通常是一组 `Message`;条目多到需要独立滚动时用 `MessageScroller` 并给它显式 `height` —— 那是有界的正交滚动区,不得堆叠无界的垂直滚动容器。无条目时传 `emptyState`,内容应是 `Empty`,其文案必须区别于无权限与加载失败。整体性动作(例如「全部标记为已读」)放 `footer`。几何全部由 `--ui-shell-global-action-*` 登记:720px 宽、20px 圆角、680px 最高、16px 视口边距、位于整个 Shell 堆叠之下,调用方不得覆盖。由于本面板非模态,外点击关闭由调用方触发 `onClose`。
5283
+ **组合约定。** `open` 与 `title` 必须与 `ApplicationPrimaryNavigation` 的 `activeAction` 同步,四个动作绝不各造一个弹层。`tabs` 传 `GlobalActionTab`(`value` / `label` / `count`),当前项由 `activeTab` 受控、`onTabChange` 回写。`children` 通常是一组 `Message`;条目多到需要独立滚动时用 `MessageScroller` —— 面板主体是列向 flex,`MessageScroller` 的 `height` 在这里是上限而非定值:视口不够时它自动收缩到面板剩余高度、由它独自滚动,面板主体不再出现第二层纵向滚动;不得在它外面再包一层带高度或滚动的容器。面板主体的系统状态由 `state` 选择槽位,命名照 `ApplicationDataDisplay`:`ready` 渲染 `children`,`loading` 渲染 `loading`(贴近条目结构的 `Skeleton`,主体随之标 `aria-busy`),`empty` 渲染 `emptyState`(`Empty`,点明当前标签的口径),`error` 渲染 `error`(说明失败原因并提供重试),`no-permission` 渲染 `noPermission`;使用某个状态前必须提供该状态的节点,否则主体为空白。不传 `state` 时保持旧行为:有 `children` 渲染它,否则渲染 `emptyState`。非 `ready` 状态下 `footer` 里的整体性动作必须禁用。整体性动作(例如「全部标记为已读」)放 `footer`。几何全部由 `--ui-shell-global-action-*` 登记:720px 宽、20px 圆角、680px 最高、16px 视口边距、位于整个 Shell 堆叠之下,调用方不得覆盖。由于本面板非模态,外点击关闭由调用方触发 `onClose`(点另一个全局动作是切换而非关闭,这份判据只有调用方知道);Esc 已由本组件处理,调用方不得再自挂 keydown 监听处理 Esc —— 那份监听进不了 Esc 层级栈,会与上层浮层同时响应。
4646
5284
 
4647
5285
  **禁止 / 使用边界。**
4648
5286
  - 不得为四个全局动作分别造弹层 —— 一个面板,四套内容。
4649
5287
  - 不得在本面板内渲染设置,也不得在产品内存在第二个设置入口。
4650
5288
  - 不得把业务页面内容搬进本面板,Shell 不承载业务内容。
4651
- - 禁止让 Loading、Empty、No Permission、Error 共用 `emptyState` 一句文案。
5289
+ - 禁止让 Loading、Empty、No Permission、Error 共用一句文案,也不得把加载、失败或无权限的节点塞进 `emptyState` 或 `children`。
4652
5290
  - 不得覆盖已登记的宽度、圆角与最大高度。
4653
5291
 
4654
5292
  ### PeoplePickerDialog
@@ -4698,7 +5336,7 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4698
5336
  - 把人员作为筛选维度使用时改用 `ApplicationFilterMenu`,本组件不承担筛选。
4699
5337
  - 非人员的通用选择任务改用 `Dialog`。
4700
5338
 
4701
- **组合约定。** `Person.name` 必须是纯文本 —— 它参与搜索匹配,也用于已选项的移除按钮无障碍名称;`org` 同样参与匹配。`selected` 与 `onSelectedChange` 成对提供,选择受控。搜索框由组件内部以 `SearchField` 渲染,调用方不得再传一个;对应地,本组件没有搜索槽位。已选栏宽 240px,对话框宽度取 720px 一档、高度固定 520px,目录与已选清单各自滚动,人数增减不改变对话框尺寸。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发。作为表单字段的值选择器使用时,触发器与回显由调用方在 `Field` 内提供,本组件只负责选择过程。视口边距、焦点与滚动锁定由 Overlay 基座负责。
5339
+ **组合约定。** `Person.name` 必须是纯文本 —— 它参与搜索匹配,也用于已选项的移除按钮无障碍名称;`org` 同样参与匹配。`selected` 与 `onSelectedChange` 成对提供,选择受控。搜索框由组件内部以 `SearchField` 渲染,调用方不得再传一个;对应地,本组件没有搜索槽位。与 `SearchField` 的约定一致,检索只在 Enter 时生效,清空输入框即恢复全量目录。已选栏宽 240px,对话框宽度取 720px 一档、高度固定 520px,目录与已选清单各自滚动,人数增减不改变对话框尺寸。`onCancel` 同时被取消按钮、Esc 与遮罩点击触发。作为表单字段的值选择器使用时,触发器与回显由调用方在 `Field` 内提供,本组件只负责选择过程;表单本身在 `Dialog` / `Drawer` 里时,本组件就是模态之上放行的那一层(06 · D-3),本组件之上不得再开任何模态。视口边距、焦点与滚动锁定由 Overlay 基座负责。
4702
5340
 
4703
5341
  **禁止 / 使用边界。**
4704
5342
  - 不得把 `Person.name` 传成 JSX —— 那会让该条目搜索不到,也会让移除按钮的无障碍名称失效。
@@ -4720,6 +5358,10 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4720
5358
 
4721
5359
  详情栏应传 `ApplicationRecordDetailBody`,与其他详情载体保持同一份主体。
4722
5360
 
5361
+ ⚠ **系统状态与 `ApplicationDataDisplay` 同一套取值、同一套槽位命名**(06 · P1-17)。
5362
+ 非 `ready` 时对应槽位顶替成员栏与详情栏两栏,组织树定位器保留 —— 某个机构
5363
+ 加载失败、无权限或已撤销时,读者仍要能换一个机构。六种状态各写各的措辞。
5364
+
4723
5365
  **Props**
4724
5366
 
4725
5367
  | prop | 类型 | 必填 | 说明 |
@@ -4731,7 +5373,15 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4731
5373
  | `people` | `WorkspacePerson[]` | 否 | 当前机构下的成员 |
4732
5374
  | `activePerson` | `string` | 否 | 当前成员 |
4733
5375
  | `onPersonChange` | `(id: string) => void` | 否 | 成员变化回调 |
4734
- | `detail` | `ReactNode` | 否 | 成员详情,应传 `ApplicationRecordDetailBody` |
5376
+ | `detail` | `ReactNode` | 否 | 成员详情,应传 `ApplicationRecordDetailBody`。未选中成员时**不传**,详情栏显示 `detailEmpty` |
5377
+ | `peopleEmpty` | `ReactNode` | 否 | `ready` 且当前机构下没有成员时成员栏的内容。 缺省为内置的 `Empty`「此机构下无成员」;需要附带动作时覆盖 |
5378
+ | `detailEmpty` | `ReactNode` | 否 | 未传 `detail` 时详情栏的内容。缺省为内置的 `Empty`「未选择成员」。 不得为了填满详情栏而自动选中第一个成员 |
5379
+ | `state` | `DataDisplayState` | 否 | 当前系统状态,取值同 `ApplicationDataDisplay`。`ready` 渲染成员栏与详情栏, 其余状态渲染对应槽位,顶替成员栏与详情栏两栏;组织树始终保留 |
5380
+ | `loading` | `ReactNode` | 否 | Loading 状态内容。应传贴近「成员列表 · 详情」两栏结构的 `Skeleton` |
5381
+ | `empty` | `ReactNode` | 否 | Empty 状态内容(整个工作台无数据)。应传 `Empty`,文案须点明当前口径 |
5382
+ | `error` | `ReactNode` | 否 | Error 状态内容。应说明失败原因并提供重试 |
5383
+ | `noPermission` | `ReactNode` | 否 | No Permission 状态内容。措辞必须区别于 Empty |
5384
+ | `notFound` | `ReactNode` | 否 | Not Found 状态内容(如机构不存在或已撤销)。措辞必须区别于 Empty 与 No Permission |
4735
5385
 
4736
5386
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
4737
5387
 
@@ -4756,7 +5406,7 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4756
5406
  - 只需要详情主体本身改用 `ApplicationRecordDetailBody`。
4757
5407
  - 文件与日程各有自己的工作台:`FilesCollaborationWorkspace`、`ScheduleCollaborationWorkspace`。
4758
5408
 
4759
- **组合约定。** 本组件是受控的整体结构,整体复用,不得拆开抄进页面。`search` 应传 `SearchField`,其 `ariaLabel` 必填且应写明搜索范围。`orgTree` 复用 `SplitSidebarItem` 的条目结构(`value` / `label` / `icon` / `count` / `depth`),树形缩进走 `depth`,不要另造一套树数据。`detail` 应传 `ApplicationRecordDetailBody`。`activePerson` 为空是完全合法的状态,不得为了填满详情栏而自动选中第一个成员。成员行的头像、姓名、岗位、状态由 `WorkspacePerson` 的四个字段驱动,行本身复用 Foundation `Item`。本组件不设工具栏槽位 —— 页面级动作留在 `ApplicationPageHeader`。外壳的边框、16px 圆角与分栏滚动规则由三个 collaboration 组件共用同一份 CSS,`--mh-contacts-*` 是本组件的局部尺度而非公共接口。
5409
+ **组合约定。** 本组件是受控的整体结构,整体复用,不得拆开抄进页面。`search` 应传 `SearchField`,其 `ariaLabel` 必填且应写明搜索范围。`orgTree` 复用 `SplitSidebarItem` 的条目结构(`value` / `label` / `icon` / `count` / `depth`),树形缩进走 `depth`,不要另造一套树数据;组织树渲染为按 `depth` 嵌套的列表,恒为展开,不声明 `role="tree"`。`detail` 应传 `ApplicationRecordDetailBody`。`activePerson` 为空是完全合法的状态,不得为了填满详情栏而自动选中第一个成员;此时不传 `detail`,详情栏显示 `detailEmpty`(缺省为内置的「未选择成员」)。当前机构下没有成员时成员栏显示 `peopleEmpty`(缺省为内置的「此机构下无成员」)。系统状态经 `state` 与 `loading` / `empty` / `error` / `noPermission` / `notFound` 五个槽位表达,取值与命名同 `ApplicationDataDisplay`:非 `ready` 时槽位顶替成员栏与详情栏两栏,组织树保留,读者仍能换一个机构;`loading` 应传贴近「成员列表 · 详情」两栏的 `Skeleton`,五个槽位各写各的措辞。本组件不得放进 `ApplicationDataDisplay`,也不得在非 `ready` 时整块换成它 —— 那会画出双层外框并让分栏滚动失效。成员行的头像、姓名、岗位、状态由 `WorkspacePerson` 的四个字段驱动,行本身复用 Foundation `Item`。本组件不设工具栏槽位 —— 页面级动作留在 `ApplicationPageHeader`。外壳的边框、16px 圆角与分栏滚动规则由三个 collaboration 组件共用同一份 CSS,`--mh-contacts-*` 是本组件的局部尺度而非公共接口。
4760
5410
 
4761
5411
  **禁止 / 使用边界。**
4762
5412
  - 不得在每个页面重新搭一遍三栏布局 —— 复制出去的外壳会让下一次调整要改多处。
@@ -4764,6 +5414,7 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4764
5414
  - 不得为了填满详情栏自动选中第一个成员。
4765
5415
  - 禁止把本组件的外壳类名挪作其他三栏布局使用。
4766
5416
  - 不得在本组件外再包一层自己的 padding,页面内容根的内边距由 `ApplicationPageLayoutContainer` 持有。
5417
+ - 禁止 Loading / Empty / Error / No Permission / Not Found 共用同一句文案,成员栏与详情栏的空态也不得借用 `empty` 的措辞。
4767
5418
 
4768
5419
  ### FilesCollaborationWorkspace
4769
5420
 
@@ -4776,6 +5427,10 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4776
5427
  ⚠ **没有选中项时省略 `preview`**,而不是显示一条空的预览栏 ——
4777
5428
  与「无真实指标时不渲染指标区」同一条原则。
4778
5429
 
5430
+ ⚠ **系统状态与 `ApplicationDataDisplay` 同一套取值、同一套槽位命名**(06 · P1-17)。
5431
+ 非 `ready` 时对应槽位顶替文件表,预览栏不渲染;文件夹定位器与工具栏保留 ——
5432
+ 换个文件夹、在空目录里上传,都不该被状态挡住。
5433
+
4779
5434
  **Props**
4780
5435
 
4781
5436
  | prop | 类型 | 必填 | 说明 |
@@ -4790,7 +5445,12 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4790
5445
  | `onOpen` | `(file: WorkspaceFile) => void` | 否 | 打开文件回调 |
4791
5446
  | `toolbar` | `ReactNode` | 否 | 工具栏内容,如上传、新建文件夹 |
4792
5447
  | `preview` | `ReactNode` | 否 | 预览栏。**无选中项时不要传** |
4793
- | `empty` | `ReactNode` | 否 | 空态,应传 `Empty`。文案须点明是「此目录下」 |
5448
+ | `empty` | `ReactNode` | 否 | 空态,应传 `Empty`。文案须点明是「此目录下」。 `ready` 且 `files` 为空时由文件表显示,`state="empty"` 时顶替文件表显示 |
5449
+ | `state` | `DataDisplayState` | 否 | 当前系统状态,取值同 `ApplicationDataDisplay`。`ready` 渲染文件表与预览栏, 其余状态渲染对应槽位,顶替文件表;文件夹树与工具栏始终保留 |
5450
+ | `loading` | `ReactNode` | 否 | Loading 状态内容。应传贴近文件表结构的 `Skeleton` |
5451
+ | `error` | `ReactNode` | 否 | Error 状态内容。应说明失败原因并提供重试 |
5452
+ | `noPermission` | `ReactNode` | 否 | No Permission 状态内容。措辞必须区别于 Empty |
5453
+ | `notFound` | `ReactNode` | 否 | Not Found 状态内容(如文件夹不存在或已删除)。措辞必须区别于 Empty 与 No Permission |
4794
5454
 
4795
5455
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
4796
5456
 
@@ -4816,7 +5476,7 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4816
5476
  - 附件预览若属于业务详情的一部分,改由 `ApplicationRecordDetailBody` 的分节 `content` 承载。
4817
5477
  - 人员与日程各有自己的工作台:`ContactsCollaborationWorkspace`、`ScheduleCollaborationWorkspace`。
4818
5478
 
4819
- **组合约定。** 本组件是整装件,整体复用。`search` 应传 `SearchField`,`folders` 复用 `SplitSidebarItem` 的条目结构。`preview` 仅在确有选中项时传 —— 无选中项时整体省略该槽位,与「无真实指标时不渲染指标区」是同一条原则。`empty` 应传 `Empty`,文案须点明是「此目录下」无文件,且不得与无权限、未找到、加载失败共用措辞。上传、新建文件夹这类目录级动作放 `toolbar`。本组件不设 `batchBar` 槽位,选中文件后的批量动作同样由调用方放进 `toolbar`。行选择由内部 `Table` 承载,`selected` 与 `onSelectedChange` 成对提供;打开文件走 `onOpen`。文件夹树 280px、预览栏 320px,文件表占剩余宽度并独立滚动。
5479
+ **组合约定。** 本组件是整装件,整体复用。`search` 应传 `SearchField`,`folders` 复用 `SplitSidebarItem` 的条目结构。`preview` 仅在确有选中项时传 —— 无选中项时整体省略该槽位,与「无真实指标时不渲染指标区」是同一条原则。`empty` 应传 `Empty`,文案须点明是「此目录下」无文件,且不得与无权限、未找到、加载失败共用措辞;它在 `ready` 而目录为空时由文件表显示,`state="empty"` 时顶替文件表显示。系统状态经 `state` 与 `loading` / `empty` / `error` / `noPermission` / `notFound` 槽位表达,取值与命名同 `ApplicationDataDisplay`:非 `ready` 时槽位顶替文件表、预览栏不渲染,文件夹树与工具栏保留;本组件不得放进 `ApplicationDataDisplay`,也不得在非 `ready` 时整块换成它。上传、新建文件夹这类目录级动作放 `toolbar`,槽位内的多件横向排列并自带控件间距,调用方不得再包一层 flex 容器。本组件不设 `batchBar` 槽位,选中文件后的批量动作同样由调用方放进 `toolbar`。行选择由内部 `Table` 承载,`selected` 与 `onSelectedChange` 成对提供;打开文件走 `onOpen`。文件夹树 280px、预览栏 320px,文件表占剩余宽度并独立滚动,表头吸顶。
4820
5480
 
4821
5481
  **禁止 / 使用边界。**
4822
5482
  - 不得在没有选中项时传 `preview` —— 空的预览栏会白占一栏宽度。
@@ -4836,17 +5496,29 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4836
5496
  ⚠ 选择日历型承载面之前,**必须先命名日期字段与真实的观察粒度** ——
4837
5497
  `CALENDAR` 页面模式两者都要求。
4838
5498
 
5499
+ ⚠ **系统状态与 `ApplicationDataDisplay` 同一套取值、同一套槽位命名**(06 · P1-17)。
5500
+ 非 `ready` 时对应槽位顶替月格,议程栏不渲染;标题行(粒度切换、工具栏)保留 ——
5501
+ 某个月加载失败时读者仍要能翻到别的月份。
5502
+
4839
5503
  **Props**
4840
5504
 
4841
5505
  | prop | 类型 | 必填 | 说明 |
4842
5506
  |---|---|:---:|---|
4843
5507
  | `month` | `Date` | 否 | 当前显示的月份 |
5508
+ | `onMonthChange` | `(month: Date) => void` | 否 | 翻页回调,回传目标月份的 1 日。**提供时工作台内置「上一页 · 今天 · 下一页」三个控件**, 不提供时不渲染(翻页由调用方自理,保持旧行为)。 翻页按粒度走:月档翻一个月;周档、日档把焦点日前后移 7 天 / 1 天,经 `onSelectDate` 回传新的焦点日,跨月时同时回调本函数。周档、日档未提供 `onSelectDate` 时按月翻。 「今天」回调今天所在月份,并经 `onSelectDate` 选中今天 |
4844
5509
  | `events` | `ScheduleEvent[]` | 否 | 事件集合 |
4845
5510
  | `selectedDate` | `string` | 否 | 选中日期,ISO `yyyy-mm-dd` |
4846
5511
  | `onSelectDate` | `(date: string) => void` | 否 | 选中日期变化回调 |
4847
5512
  | `grain` | `ScheduleGrain` | 否 | 观察粒度 |
4848
5513
  | `onGrainChange` | `(grain: ScheduleGrain) => void` | 否 | 粒度变化回调 |
4849
5514
  | `toolbar` | `ReactNode` | 否 | 工具栏内容 |
5515
+ | `agendaEmpty` | `ReactNode` | 否 | 选中日期当天没有事件时议程栏的内容。缺省为内置的 `Empty`「当日无日程」; 需要附带「新建」之类的动作时覆盖 |
5516
+ | `state` | `DataDisplayState` | 否 | 当前系统状态,取值同 `ApplicationDataDisplay`。`ready` 渲染月格与议程栏, 其余状态渲染对应槽位,顶替月格;标题行始终保留 |
5517
+ | `loading` | `ReactNode` | 否 | Loading 状态内容。应传贴近月格结构的 `Skeleton` |
5518
+ | `empty` | `ReactNode` | 否 | Empty 状态内容。应传 `Empty`,文案须点明当前口径(如「本月」) |
5519
+ | `error` | `ReactNode` | 否 | Error 状态内容。应说明失败原因并提供重试 |
5520
+ | `noPermission` | `ReactNode` | 否 | No Permission 状态内容。措辞必须区别于 Empty |
5521
+ | `notFound` | `ReactNode` | 否 | Not Found 状态内容(如日历不存在或已删除)。措辞必须区别于 Empty 与 No Permission |
4850
5522
 
4851
5523
  继承 `HTMLAttributes<HTMLDivElement>` 的全部原生属性。
4852
5524
 
@@ -4863,14 +5535,14 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4863
5535
 
4864
5536
  **用途。** 「日程」工作台的整装模块件 —— 粒度切换、月格、当日议程栏。
4865
5537
 
4866
- **何时使用。** 需要在一个工作台面里同时看到月度分布与当日明细时使用本组件。周一为一周起始。日格最多平铺 2 条事件,其余折成「+N」;格高 76px,议程栏宽 280px。粒度在日、周、月三档之间切换,由 `grain` 与 `onGrainChange` 受控。
5538
+ **何时使用。** 需要在一个工作台面里同时看到月度分布与当日明细时使用本组件。周一为一周起始。日格最多平铺 2 条事件,其余折成「+N」;格高 76px,议程栏宽 280px。粒度在日、周、月三档之间切换,由 `grain` 与 `onGrainChange` 受控。周档显示焦点日所在的那一周(周一至周日,可跨月),日档只显示焦点日;焦点日取 `selectedDate`(须落在 `month` 当月内),否则取当月 1 日。周、日两档的事件全部平铺,不折叠。
4867
5539
 
4868
5540
  **何时改用其他组件。**
4869
5541
  - 表单里的日期字段与筛选区间,改用 Foundation `Calendar` 与 `Input` 一起放进 `Popover` —— 那是控件,本组件是工作台面。
4870
5542
  - 整页的日历承载面改用 `CALENDAR` 页面模式,即 `ApplicationPageHeader` 的 `pageMode` 与 `ApplicationDataDisplay` 的 `presentation="Calendar"` 组合。
4871
5543
  - 人员与文件各有自己的工作台:`ContactsCollaborationWorkspace`、`FilesCollaborationWorkspace`。
4872
5544
 
4873
- **组合约定。** 本组件是整装件,整体复用。`month` 是 `Date`,只取年月;`selectedDate` 与 `ScheduleEvent.date` 是 ISO `yyyy-mm-dd` 字符串 —— 它们是标识而非时间点,两者语义不同,不强行统一为同一种类型。事件日期串必须按本地时区生成,与组件内部的日期比较口径一致。`onGrainChange` 回传的是 `ScheduleGrain` 字面量,调用方不得回写其他值。`toolbar` 排在粒度切换之后,属于日程范围内的动作。外壳的边框、16px 圆角与分栏滚动规则与另外两个 collaboration 组件共用同一份 CSS;三者栏数并不相同:本组件是月格与议程栏两栏,`ContactsCollaborationWorkspace` 是三栏,`FilesCollaborationWorkspace` 视 `preview` 有无为两栏或三栏。选用任何日历型承载面之前,调用方必须先命名日期字段与真实的观察粒度。
5545
+ **组合约定。** 本组件是整装件,整体复用。`month` 是 `Date`,只取年月;`selectedDate` 与 `ScheduleEvent.date` 是 ISO `yyyy-mm-dd` 字符串 —— 它们是标识而非时间点,两者语义不同,不强行统一为同一种类型。事件日期串必须按本地时区生成,与组件内部的日期比较口径一致。`onGrainChange` 回传的是 `ScheduleGrain` 字面量,调用方不得回写其他值。`toolbar` 排在粒度切换之后,属于日程范围内的动作。翻页由组件内置:提供 `onMonthChange` 时标题行出现「上一页 · 今天 · 下一页」三个按钮,文案随粒度为「上月 / 下月」「上周 / 下周」「前一天 / 后一天」;月档翻一个月,周档、日档把焦点日前后移 7 天 / 1 天并经 `onSelectDate` 回传,跨月时同时回调 `onMonthChange`(周档、日档未提供 `onSelectDate` 时按月翻);「今天」回调今天所在月份并选中今天。`onMonthChange` 回传目标月份的 1 日。提供了 `onMonthChange` 就不得再往 `toolbar` 里塞一套翻月按钮;不提供时组件不渲染翻页控件。选中日期当天没有事件时议程栏显示 `agendaEmpty`(缺省为内置的「当日无日程」)。系统状态经 `state` 与 `loading` / `empty` / `error` / `noPermission` / `notFound` 槽位表达,取值与命名同 `ApplicationDataDisplay`:非 `ready` 时槽位顶替月格、议程栏不渲染,标题行保留;本组件不得放进 `ApplicationDataDisplay`,也不得在非 `ready` 时整块换成它。外壳的边框、16px 圆角与分栏滚动规则与另外两个 collaboration 组件共用同一份 CSS;三者栏数并不相同:本组件是月格与议程栏两栏,`ContactsCollaborationWorkspace` 是三栏,`FilesCollaborationWorkspace` 视 `preview` 有无为两栏或三栏。选用任何日历型承载面之前,调用方必须先命名日期字段与真实的观察粒度。
4874
5546
 
4875
5547
  **禁止 / 使用边界。**
4876
5548
  - 不得用本组件替代 `CALENDAR` 页面模式,两者同名不同层。
@@ -4878,6 +5550,7 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4878
5550
  - 不得把周日作为一周起始。
4879
5551
  - 禁止绕开「+N」折叠机制在单个日格内堆入超过 2 条事件。
4880
5552
  - 不得在缺少日期字段或未确定观察粒度的情况下选用本组件。
5553
+ - 禁止 Loading / Empty / Error / No Permission / Not Found 共用同一句文案。
4881
5554
 
4882
5555
  ## 反例
4883
5556
 
@@ -4896,18 +5569,33 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4896
5569
 
4897
5570
  ```jsx
4898
5571
  // 不要这样写
4899
- <Button variant="icon"><Icon name="rotate-cw" size={16} /></Button>
4900
- <Button size="icon"><Icon name="rotate-cw" size={16} /></Button>
5572
+ <SystemButton intent="icon"><Icon name="refresh-cw" size={16} /></SystemButton>
5573
+ <SystemButton size="icon"><Icon name="refresh-cw" size={16} /></SystemButton>
4901
5574
 
4902
- // 要这样写 —— 尺寸与形状是两根轴,iconOnly 控制形状
4903
- <Button iconOnly aria-label="刷新"><Icon name="rotate-cw" size={16} /></Button>
5575
+ // 要这样写 —— 意图与形状是两根轴,iconOnly 控制形状
5576
+ <SystemButton intent="quiet" iconOnly aria-label="刷新"><Icon name="refresh-cw" size={16} /></SystemButton>
4904
5577
  ```
4905
5578
 
4906
- `variant` 只有 `primary` / `secondary` / `outline` / `ghost` / `destructive` / `link`;
4907
- `size` 只有 `xs` / `sm` / `default` / `lg`。**shadcn 习惯的 `size="icon"` 在本库不存在。**
5579
+ `SystemButton` 的 `intent` 只有 `primary` / `secondary` / `quiet` / `link` / `destructive`;
5580
+ `size` 只有 `default` / `compact` / `sm`。**shadcn 习惯的 `size="icon"` 在本库不存在**,
5581
+ Foundation `Button` 同样只用 `iconOnly` 表达等宽图标按钮。
4908
5582
 
4909
5583
  `iconOnly` 为 true 时按钮没有可见文字,**必须**另给 `aria-label`。
4910
5584
 
5585
+ ### 业务页面用 Foundation Button
5586
+
5587
+ ```jsx
5588
+ // 不要这样写 —— Button 只供库内组件使用
5589
+ <Button variant="primary" onClick={create}>新建</Button>
5590
+
5591
+ // 要这样写 —— 业务页面的按钮一律用 SystemButton
5592
+ <SystemButton intent="primary" onClick={create}>新建</SystemButton>
5593
+ ```
5594
+
5595
+ `SystemButton` 是整个产品的默认动作按钮,承载应用意图、`loading` 与产品状态;
5596
+ 改一次应用强调色,全部 `SystemButton` 同时换肤。lint 的 `no-native-button` 把原生
5597
+ `<button>` 改写成的也是它。
5598
+
4911
5599
  ### 内联 style
4912
5600
 
4913
5601
  ```jsx
@@ -4928,10 +5616,10 @@ DETAIL 的**抽屉载体** —— 打开一条记录的详情而不丢失身后
4928
5616
  ```jsx
4929
5617
  // 不要这样写
4930
5618
  const [hover, setHover] = useState(false)
4931
- <Button onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
5619
+ <SystemButton onMouseEnter={() => setHover(true)} onMouseLeave={() => setHover(false)}>
4932
5620
 
4933
5621
  // 要这样写 —— 什么都不写,hover 已由 CSS 伪类实现
4934
- <Button>提交</Button>
5622
+ <SystemButton>提交</SystemButton>
4935
5623
  ```
4936
5624
 
4937
5625
  `useState` 会让组件强制成为 client component。状态一律用 CSS 伪类
@@ -4943,7 +5631,7 @@ const [hover, setHover] = useState(false)
4943
5631
  /* 不要这样写 —— 只会改到引用它的那部分组件 */
4944
5632
  :root { --application-accent: #16a34a; }
4945
5633
 
4946
- /* 也不要这样写 —— 别名层整层声明在 :root,挂在容器上一律无效 */
5634
+ /* 也不要这样写 —— 别名层整层声明在 :root,挂在容器上半生效 */
4947
5635
  <div className="dark">…</div>
4948
5636
 
4949
5637
  /* 要这样写 */
@@ -4952,7 +5640,8 @@ const [hover, setHover] = useState(false)
4952
5640
 
4953
5641
  `--ds-color-theme-primary` 是换肤契约的唯一入口。
4954
5642
  换肤与 `.dark` **必须挂在 `<html>` 上** —— `var()` 代换在声明所在元素就完成了,
4955
- 挂在 `<body>` 或容器 div 上无效(已实测)。系统内不存在「局部暗色区块」这种用法。
5643
+ 挂在 `<body>` 或容器 div 上是半生效(已实测):直接读 `--ds-*` 的部件变了,读 `--application-*`
5644
+ 的部件不变。半生效比无效更糟 —— 看上去像是生效了。系统内不存在「局部暗色区块」这种用法。
4956
5645
 
4957
5646
  ### 手写表格结构
4958
5647
 
@@ -4996,10 +5685,10 @@ const [hover, setHover] = useState(false)
4996
5685
  ```jsx
4997
5686
  // 不要这样写
4998
5687
  import { Button } from '@/components/ui/button'
4999
- import { Button } from '@moheng-design/ui/dist/components/foundation/actions/Button.js'
5688
+ import { SystemButton } from '@moheng-design/ui/dist/components/application-atomic/SystemButton.js'
5000
5689
 
5001
5690
  // 要这样写
5002
- import { Button } from '@moheng-design/ui'
5691
+ import { SystemButton } from '@moheng-design/ui'
5003
5692
  ```
5004
5693
 
5005
5694
  `@/components/ui/` 目录通常是 `npx shadcn add` 生成的第二套组件源码,
@@ -5012,10 +5701,10 @@ import { Button } from '@moheng-design/ui'
5012
5701
 
5013
5702
  ```jsx
5014
5703
  // 不要这样写 —— 组件渲染出来是无样式的裸结构
5015
- import { Button } from '@moheng-design/ui'
5704
+ import { SystemButton } from '@moheng-design/ui'
5016
5705
 
5017
5706
  // 要这样写 —— 应用入口引一次即可
5018
- import { Button } from '@moheng-design/ui'
5707
+ import { SystemButton } from '@moheng-design/ui'
5019
5708
  import '@moheng-design/ui/styles.css'
5020
5709
  ```
5021
5710
 
@@ -5025,16 +5714,18 @@ import '@moheng-design/ui/styles.css'
5025
5714
  ### 通用的「视图设置」按钮
5026
5715
 
5027
5716
  ```jsx
5028
- // 不要这样写
5029
- <Button>视图设置</Button>
5717
+ // 不要这样写 —— 自己拼一个设置按钮,名字还是通用的
5718
+ <SystemButton>视图设置</SystemButton>
5719
+ <SystemButton>自定义</SystemButton>
5030
5720
 
5031
- // 要这样写 —— 按当前呈现方式命名
5032
- <Button>列设置</Button> {/* DataTable */}
5033
- <Button>看板设置</Button> {/* KanbanBoard */}
5721
+ // 要这样写 —— 交给工具栏,它按当前呈现方式命名
5722
+ <ApplicationQueryToolbar presentation="DataTable" onPresentationSettings={openColumns} /> {/* 列设置 */}
5723
+ <ApplicationQueryToolbar presentation="KanbanBoard" onPresentationSettings={openBoard} /> {/* 看板设置 */}
5034
5724
  ```
5035
5725
 
5036
- 呈现设置是一个*概念*,不是一个按钮名。按钮必须按当前呈现方式命名:
5037
- `列设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
5726
+ 呈现设置是一个*概念*,不是一个按钮名。工具栏的设置按钮按 GAP Design kit 是 32×32 纯图标,
5727
+ 名字落在可访问名与悬停提示上,必须按当前呈现方式命名:
5728
+ `列设置` / `列表设置` / `卡片设置` / `看板设置` / `日历设置` / `图表设置` / `时间轴设置`。
5038
5729
 
5039
5730
  ### 六种数据状态共用一句话
5040
5731
 
@@ -5045,9 +5736,11 @@ import '@moheng-design/ui/styles.css'
5045
5736
  // 要这样写 —— 成因不同,用户的下一步动作也不同
5046
5737
  <ApplicationDataDisplay
5047
5738
  state={state}
5048
- empty={<Empty title="当前视角下无数据" description="切换业务视图或调整筛选条件" />}
5049
- noPermission={<Empty title="没有查看权限" description="请联系管理员申请" />}
5050
- error={<Empty title="加载失败" description="请稍后重试" />}
5739
+ empty={filtered
5740
+ ? <Empty title="没有符合当前筛选条件的记录" action={<SystemButton onClick={resetFilters}>清除筛选</SystemButton>} />
5741
+ : <Empty title="当前视图下还没有记录" action={<SystemButton onClick={create}>新建</SystemButton>} />}
5742
+ noPermission={<Empty title="无权查看本模块" description="联系本模块管理员开通" />}
5743
+ error={<Empty title="加载失败" description="服务暂时不可用,可重试" />}
5051
5744
  />
5052
5745
  ```
5053
5746
 
@@ -5066,7 +5759,7 @@ Loading / Empty / Error / No Permission / Not Found / Partial Failure
5066
5759
  <ScrollArea horizontal>…</ScrollArea>
5067
5760
  ```
5068
5761
 
5069
- Content Canvas 是页面唯一的主垂直滚动权持有者。
5762
+ 页面级纵向滚动持有者每页只有一个:结果集页面是 `ApplicationDataDisplay` 的主体,其余页面是 Content Canvas。
5070
5763
  `ScrollArea` 与 `MessageScroller` 只用于正交方向或局部有界的溢出,且必须给出高度。
5071
5764
 
5072
5765
  ### 用 Emoji 或系统字符代替图标
@@ -5124,11 +5817,11 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5124
5817
 
5125
5818
  ## 规则清单
5126
5819
 
5127
- 共 150 条。完整数据见 `generated/rules.json`。
5820
+ 共 165 条。完整数据见 `generated/rules.json`。
5128
5821
 
5129
5822
  | 规则 id | kind | scope | 级别 | 报错文案 |
5130
5823
  |---|---|---|---|---|
5131
- | `no-native-button` | forbid-element | consumer | error | 请使用 Button 组件替代原生 <button>。导入方式:import { Button } from '@moheng-design/ui' |
5824
+ | `no-native-button` | forbid-element | consumer | error | 请使用 SystemButton 组件替代原生 <button>,业务页面的按钮一律用它。导入方式:import { SystemButton } from '@moheng-design/ui' |
5132
5825
  | `no-native-input` | forbid-element | consumer | error | 请使用 Input 组件替代原生 <input>。导入方式:import { Input } from '@moheng-design/ui'。type 为 checkbox / radio / range / search 时另有专用组件,见 no-native-checkbox / no-native-radio / no-native-range / no-native-search |
5133
5826
  | `no-native-checkbox` | forbid-element | consumer | error | 请使用 Checkbox 组件替代 <input type="checkbox">。导入方式:import { Checkbox } from '@moheng-design/ui'。列表行内的批量选择另用 ListSelectionCheckbox |
5134
5827
  | `no-native-radio` | forbid-element | consumer | error | 请使用 RadioGroup 组件替代 <input type="radio">。RadioGroup 是组级控件,全部选项写在 items 数组里,不要逐个渲染单选项。导入方式:import { RadioGroup } from '@moheng-design/ui' |
@@ -5144,16 +5837,17 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5144
5837
  | `no-native-details` | forbid-element | consumer | error | 请使用 Collapsible 组件替代原生 <details>。导入方式:import { Collapsible } from '@moheng-design/ui'。多个互斥折叠项改用 Accordion |
5145
5838
  | `no-native-summary` | forbid-element | consumer | error | 请使用 Collapsible 组件的 label 替代原生 <summary>。触发器文字写进 label,被折叠的内容写进 children。导入方式:import { Collapsible } from '@moheng-design/ui' |
5146
5839
  | `no-native-kbd` | forbid-element | consumer | error | 请使用 Kbd 组件替代原生 <kbd>。导入方式:import { Kbd } from '@moheng-design/ui' |
5147
- | `no-inline-svg` | forbid-element | consumer | error | 请使用 Icon 组件替代逐页手写的内联 <svg>。导入方式:import { Icon } from '@moheng-design/ui',写作 <Icon name="登记名" size={16} />。name 只接受已登记字形,清单见 @moheng-design/ui 的 src/icon/registry.json(reference.md 亦有全表);未登记的名字渲染为等尺寸占位盒,确需新字形须先登记进该清单并随包发版。数据可视化改用 Chart 组件,不要手绘图形 |
5840
+ | `no-inline-svg` | forbid-element | consumer | error | 请使用 Icon 组件替代逐页手写的内联 <svg>。导入方式:import { Icon } from '@moheng-design/ui',写作 <Icon name="登记名" size={16} />。name 只接受已登记字形,可用名字见 @moheng-design/ui-skill 的 generated/reference.md「图标字形」一节;未登记的名字渲染为等尺寸占位盒,确需新字形须先登记进该清单并随包发版。数据可视化改用 Chart 组件,不要手绘图形 |
5148
5841
  | `no-shadcn-ui-import` | forbid-import | consumer | error | 禁止从 @/components/ui/* 导入。该目录通常是 npx shadcn add 生成的平行组件实现,与 @moheng-design/ui 并存会造成同一界面两套视觉。请改为 import { ... } from '@moheng-design/ui' |
5149
5842
  | `no-deep-import` | forbid-import | consumer | error | 禁止深引 @moheng-design/ui 的内部路径。请从包入口导入:import { ... } from '@moheng-design/ui'。样式表另有专用入口 @moheng-design/ui/styles.css |
5150
5843
  | `no-raw-hex-color` | forbid-value | internal | error | 禁止硬编码色值。请改用 --ds-color-* token,例如 color: var(--ds-color-text)。可用 token 见 packages/ui/tokens.json |
5151
5844
  | `no-raw-px-value` | forbid-value | internal | error | 禁止硬编码尺寸。间距用 --ds-space-0 至 --ds-space-5(后缀是档位序号,六档依次为 0/4/8/12/16/24px),圆角用 --ds-radius-0/4/8/12/16/20(后缀即像素值),字号用 --ds-font-size-12/14/16/20/24、行高用 --ds-line-height-16/20/24/28/32(后缀同为像素值)。系统内没有 20 / 32 / 48 间距档,出现这类值说明取错了标尺 |
5152
5845
  | `no-unregistered-font` | forbid-value | internal | error | 禁止直接书写字族。请改用 var(--ds-font-family),等宽场景用 var(--ds-font-family-mono)。系统只有单一字族,没有展示体,也没有搭配字体 |
5153
5846
  | `props-whitelist-icon` | props-whitelist | both | warn | <Icon> 不接受该 prop。已声明的 props:name、size、strokeWidth、color、style。继承自 SVGProps<SVGSVGElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5847
+ | `prop-enum-icon-name` | prop-enum | both | warn | <Icon> 的 name 取值须为 'activity' \| 'arrow-down' \| 'arrow-up' \| 'calendar' \| 'check' \| 'chevron-down' \| 'chevron-left' \| 'chevron-right' \| 'chevron-up' \| 'chevrons-left' \| 'chevrons-right' \| 'circle-alert' \| 'circle-check' \| 'circle-check-big' \| 'columns-2' \| 'download' \| 'ellipsis' \| 'funnel' \| 'info' \| 'kanban' \| 'layout-grid' \| 'list' \| 'message-square' \| 'minus' \| 'pencil' \| 'plus' \| 'refresh-cw' \| 'search' \| 'settings' \| 'shield-check' \| 'sliders-horizontal' \| 'trash-2' \| 'triangle-alert' \| 'upload' \| 'x' 之一 |
5154
5848
  | `prop-enum-icon-size` | prop-enum | both | warn | <Icon> 的 size 取值须为 14 \| 16 \| 18 \| 20 \| 24 之一 |
5155
5849
  | `props-whitelist-button` | props-whitelist | both | warn | <Button> 不接受该 prop。已声明的 props:variant、size、iconOnly、disabled、children。继承自 ButtonHTMLAttributes<HTMLButtonElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5156
- | `prop-enum-button-variant` | prop-enum | both | warn | <Button> 的 variant 取值须为 'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'link' 之一 |
5850
+ | `prop-enum-button-variant` | prop-enum | both | warn | <Button> 的 variant 取值须为 'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive' \| 'destructive-outline' \| 'link' 之一 |
5157
5851
  | `prop-enum-button-size` | prop-enum | both | warn | <Button> 的 size 取值须为 'xs' \| 'sm' \| 'default' \| 'lg' 之一 |
5158
5852
  | `props-whitelist-button-group` | props-whitelist | both | warn | <ButtonGroup> 不接受该 prop。已声明的 props:children、orientation、attached。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5159
5853
  | `prop-enum-button-group-orientation` | prop-enum | both | warn | <ButtonGroup> 的 orientation 取值须为 'horizontal' \| 'vertical' 之一 |
@@ -5162,28 +5856,30 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5162
5856
  | `props-whitelist-toggle-group` | props-whitelist | both | warn | <ToggleGroup> 不接受该 prop。已声明的 props:items、type、value、defaultValue、onValueChange、size、disabled。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5163
5857
  | `prop-enum-toggle-group-type` | prop-enum | both | warn | <ToggleGroup> 的 type 取值须为 'single' \| 'multiple' 之一 |
5164
5858
  | `prop-enum-toggle-group-size` | prop-enum | both | warn | <ToggleGroup> 的 size 取值须为 'sm' \| 'default' \| 'lg' 之一 |
5165
- | `props-whitelist-calendar` | props-whitelist | both | warn | <Calendar> 不接受该 prop。已声明的 props:month、selected、onSelect。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5166
- | `props-whitelist-checkbox` | props-whitelist | both | warn | <Checkbox> 不接受该 prop。已声明的 props:checked、defaultChecked、indeterminate、onCheckedChange、label。继承自 InputHTMLAttributes<HTMLInputElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5167
- | `props-whitelist-combobox` | props-whitelist | both | warn | <Combobox> 不接受该 prop。已声明的 props:options、value、defaultValue、onValueChange、placeholder、emptyText、disabled。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5168
- | `props-whitelist-field` | props-whitelist | both | warn | <Field> 不接受该 prop。已声明的 props:label、description、error、required、htmlFor、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5859
+ | `props-whitelist-calendar` | props-whitelist | both | warn | <Calendar> 不接受该 prop。已声明的 props:month、selected、onSelect、today。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5860
+ | `props-whitelist-checkbox` | props-whitelist | both | warn | <Checkbox> 不接受该 prop。已声明的 props:checked、defaultChecked、indeterminate、onCheckedChange、label、invalid。继承自 InputHTMLAttributes<HTMLInputElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5861
+ | `props-whitelist-combobox` | props-whitelist | both | warn | <Combobox> 不接受该 prop。已声明的 props:options、value、defaultValue、onValueChange、placeholder、emptyText、disabled、invalid。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5862
+ | `props-whitelist-date-input` | props-whitelist | both | warn | <DateInput> 不接受该 prop。已声明的 props:value、defaultValue、onValueChange、placeholder、disabled、invalid、today。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5863
+ | `props-whitelist-field` | props-whitelist | both | warn | <Field> 不接受该 prop。已声明的 props:label、description、error、required、htmlFor、span、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5169
5864
  | `props-whitelist-input` | props-whitelist | both | warn | <Input> 不接受该 prop。已声明的 props:invalid。继承自 InputHTMLAttributes<HTMLInputElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5170
- | `props-whitelist-input-group` | props-whitelist | both | warn | <InputGroup> 不接受该 prop。已声明的 props:leading、trailing、children、disabled。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5171
- | `props-whitelist-input-otp` | props-whitelist | both | warn | <InputOTP> 不接受该 prop。已声明的 props:length、value、defaultValue、onValueChange、disabled。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5865
+ | `props-whitelist-input-group` | props-whitelist | both | warn | <InputGroup> 不接受该 prop。已声明的 props:leading、trailing、children、disabled、invalid。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5866
+ | `props-whitelist-input-otp` | props-whitelist | both | warn | <InputOTP> 不接受该 prop。已声明的 props:length、value、defaultValue、onValueChange、disabled、invalid。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5172
5867
  | `props-whitelist-label` | props-whitelist | both | warn | <Label> 不接受该 prop。已声明的 props:required、children。继承自 LabelHTMLAttributes<HTMLLabelElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5173
5868
  | `props-whitelist-native-select` | props-whitelist | both | warn | <NativeSelect> 不接受该 prop。已声明的 props:options、placeholder、invalid。继承自 SelectHTMLAttributes<HTMLSelectElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5174
- | `props-whitelist-radio-group` | props-whitelist | both | warn | <RadioGroup> 不接受该 prop。已声明的 props:items、value、defaultValue、onValueChange、name、orientation、disabled。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5869
+ | `props-whitelist-radio-group` | props-whitelist | both | warn | <RadioGroup> 不接受该 prop。已声明的 props:items、value、defaultValue、onValueChange、name、orientation、disabled、invalid。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5175
5870
  | `prop-enum-radio-group-orientation` | prop-enum | both | warn | <RadioGroup> 的 orientation 取值须为 'vertical' \| 'horizontal' 之一 |
5176
5871
  | `props-whitelist-select` | props-whitelist | both | warn | <Select> 不接受该 prop。已声明的 props:options、value、defaultValue、onValueChange、placeholder、disabled、invalid。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5177
5872
  | `props-whitelist-slider` | props-whitelist | both | warn | <Slider> 不接受该 prop。已声明的 props:min、max、step、value、defaultValue、onValueChange、showValue。继承自 InputHTMLAttributes<HTMLInputElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5178
- | `props-whitelist-switch` | props-whitelist | both | warn | <Switch> 不接受该 prop。已声明的 props:checked、defaultChecked、onCheckedChange、label。继承自 ButtonHTMLAttributes<HTMLButtonElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5873
+ | `props-whitelist-switch` | props-whitelist | both | warn | <Switch> 不接受该 prop。已声明的 props:checked、defaultChecked、onCheckedChange、label、busy。继承自 ButtonHTMLAttributes<HTMLButtonElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5179
5874
  | `props-whitelist-textarea` | props-whitelist | both | warn | <Textarea> 不接受该 prop。已声明的 props:invalid、rows。继承自 TextareaHTMLAttributes<HTMLTextAreaElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5180
5875
  | `props-whitelist-accordion` | props-whitelist | both | warn | <Accordion> 不接受该 prop。已声明的 props:items、type、open、defaultOpen、onOpenChange。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5181
5876
  | `prop-enum-accordion-type` | prop-enum | both | warn | <Accordion> 的 type 取值须为 'single' \| 'multiple' 之一 |
5182
5877
  | `props-whitelist-breadcrumb` | props-whitelist | both | warn | <Breadcrumb> 不接受该 prop。已声明的 props:items。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5183
- | `props-whitelist-command` | props-whitelist | both | warn | <Command> 不接受该 prop。已声明的 props:groups、placeholder、emptyText、onSelect。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5878
+ | `props-whitelist-command` | props-whitelist | both | warn | <Command> 不接受该 prop。已声明的 props:groups、placeholder、emptyText、onSelect、dialog、open、onOpenChange。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5184
5879
  | `props-whitelist-context-menu` | props-whitelist | both | warn | <ContextMenu> 不接受该 prop。已声明的 props:items、children、onSelect。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5185
5880
  | `props-whitelist-menubar` | props-whitelist | both | warn | <Menubar> 不接受该 prop。已声明的 props:menus、onSelect。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5186
- | `props-whitelist-navigation-menu` | props-whitelist | both | warn | <NavigationMenu> 不接受该 prop。已声明的 props:items、value、defaultValue、onValueChange。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5881
+ | `props-whitelist-navigation-menu` | props-whitelist | both | warn | <NavigationMenu> 不接受该 prop。已声明的 props:items、value、defaultValue、onValueChange、current。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5882
+ | `prop-enum-navigation-menu-current` | prop-enum | both | warn | <NavigationMenu> 的 current 取值须为 'page' \| 'true' 之一 |
5187
5883
  | `props-whitelist-pagination` | props-whitelist | both | warn | <Pagination> 不接受该 prop。已声明的 props:page、pageCount、onPageChange。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5188
5884
  | `props-whitelist-sidebar` | props-whitelist | both | warn | <Sidebar> 不接受该 prop。已声明的 props:groups、value、onValueChange、collapsed、width。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5189
5885
  | `props-whitelist-tabs` | props-whitelist | both | warn | <Tabs> 不接受该 prop。已声明的 props:items、value、defaultValue、onValueChange、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
@@ -5212,76 +5908,132 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5212
5908
  | `props-whitelist-separator` | props-whitelist | both | warn | <Separator> 不接受该 prop。已声明的 props:orientation、label、spacing。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5213
5909
  | `prop-enum-separator-orientation` | prop-enum | both | warn | <Separator> 的 orientation 取值须为 'horizontal' \| 'vertical' 之一 |
5214
5910
  | `props-whitelist-skeleton` | props-whitelist | both | warn | <Skeleton> 不接受该 prop。已声明的 props:width、height、radius、lines。继承自 HTMLAttributes<HTMLSpanElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5215
- | `props-whitelist-table` | props-whitelist | both | warn | <Table> 不接受该 prop。已声明的 props:columns、rows、rowKey、selectable、selected、onSelectedChange、onRowClick、sort、onSortChange、empty、density。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5911
+ | `props-whitelist-table` | props-whitelist | both | warn | <Table> 不接受该 prop。已声明的 props:columns、rows、rowKey、selectable、selected、onSelectedChange、onRowClick、sort、onSortChange、empty、density、trailingRow。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5216
5912
  | `prop-enum-table-density` | prop-enum | both | warn | <Table> 的 density 取值须为 'default' \| 'sm' 之一 |
5217
5913
  | `props-whitelist-alert` | props-whitelist | both | warn | <Alert> 不接受该 prop。已声明的 props:tone、title、action、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5218
5914
  | `prop-enum-alert-tone` | prop-enum | both | warn | <Alert> 的 tone 取值须为 'info' \| 'success' \| 'warning' \| 'danger' 之一 |
5219
5915
  | `props-whitelist-alert-dialog` | props-whitelist | both | warn | <AlertDialog> 不接受该 prop。已声明的 props:open、title、description、confirmText、cancelText、destructive、onConfirm、onCancel、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5220
5916
  | `props-whitelist-collapsible` | props-whitelist | both | warn | <Collapsible> 不接受该 prop。已声明的 props:label、defaultOpen、open、onOpenChange、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5221
- | `props-whitelist-dialog` | props-whitelist | both | warn | <Dialog> 不接受该 prop。已声明的 props:open、title、description、size、footer、onClose、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5917
+ | `props-whitelist-dialog` | props-whitelist | both | warn | <Dialog> 不接受该 prop。已声明的 props:open、title、description、size、footer、footerNote、onClose、initialFocus、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5222
5918
  | `props-whitelist-drawer` | props-whitelist | both | warn | <Drawer> 不接受该 prop。已声明的 props:open、title、width、side、footer、onClose、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5223
5919
  | `prop-enum-drawer-side` | prop-enum | both | warn | <Drawer> 的 side 取值须为 'right' \| 'left' 之一 |
5224
5920
  | `props-whitelist-dropdown-menu` | props-whitelist | both | warn | <DropdownMenu> 不接受该 prop。已声明的 props:trigger、items、onSelect、align。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5225
5921
  | `prop-enum-dropdown-menu-align` | prop-enum | both | warn | <DropdownMenu> 的 align 取值须为 'start' \| 'end' 之一 |
5226
5922
  | `props-whitelist-hover-card` | props-whitelist | both | warn | <HoverCard> 不接受该 prop。已声明的 props:trigger、content、width、openDelay。继承自 HTMLAttributes<HTMLSpanElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5227
- | `props-whitelist-popover` | props-whitelist | both | warn | <Popover> 不接受该 prop。已声明的 props:trigger、open、defaultOpen、onOpenChange、width、align、radius、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5923
+ | `props-whitelist-popover` | props-whitelist | both | warn | <Popover> 不接受该 prop。已声明的 props:trigger、anchor、open、defaultOpen、onOpenChange、width、align、radius、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5228
5924
  | `prop-enum-popover-align` | prop-enum | both | warn | <Popover> 的 align 取值须为 'start' \| 'end' 之一 |
5229
5925
  | `props-whitelist-sheet` | props-whitelist | both | warn | <Sheet> 不接受该 prop。已声明的 props:open、side、size、title、onClose、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5230
5926
  | `prop-enum-sheet-side` | prop-enum | both | warn | <Sheet> 的 side 取值须为 'right' \| 'left' \| 'top' \| 'bottom' 之一 |
5231
5927
  | `props-whitelist-sonner` | props-whitelist | both | warn | <Sonner> 不接受该 prop。已声明的 props:toasts、onDismiss、position。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5232
5928
  | `prop-enum-sonner-position` | prop-enum | both | warn | <Sonner> 的 position 取值须为 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' 之一 |
5929
+ | `props-whitelist-sonner-provider` | props-whitelist | both | warn | <SonnerProvider> 不接受该 prop。已声明的 props:children、position、className。继承自 原生元素 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5930
+ | `prop-enum-sonner-provider-position` | prop-enum | both | warn | <SonnerProvider> 的 position 取值须为 'bottom-right' \| 'bottom-left' \| 'top-right' \| 'top-left' 之一 |
5233
5931
  | `props-whitelist-spinner` | props-whitelist | both | warn | <Spinner> 不接受该 prop。已声明的 props:size、label。继承自 HTMLAttributes<HTMLSpanElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5234
5932
  | `props-whitelist-tooltip` | props-whitelist | both | warn | <Tooltip> 不接受该 prop。已声明的 props:content、side、children。继承自 HTMLAttributes<HTMLSpanElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5235
5933
  | `prop-enum-tooltip-side` | prop-enum | both | warn | <Tooltip> 的 side 取值须为 'top' \| 'bottom' \| 'left' \| 'right' 之一 |
5934
+ | `props-whitelist-application-date-range-filter` | props-whitelist | both | warn | <ApplicationDateRangeFilter> 不接受该 prop。已声明的 props:label、labelText、value、onValueChange、disabled、today。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5236
5935
  | `props-whitelist-application-filter-menu` | props-whitelist | both | warn | <ApplicationFilterMenu> 不接受该 prop。已声明的 props:label、options、value、defaultValue、onValueChange、multiple、disabled。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5237
5936
  | `props-whitelist-list-selection-checkbox` | props-whitelist | both | warn | <ListSelectionCheckbox> 不接受该 prop。已声明的 props:checked、indeterminate、onCheckedChange、scope、disabled。继承自 HTMLAttributes<HTMLSpanElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5238
5937
  | `prop-enum-list-selection-checkbox-scope` | prop-enum | both | warn | <ListSelectionCheckbox> 的 scope 取值须为 'row' \| 'all' 之一 |
5239
- | `props-whitelist-list-table-pagination` | props-whitelist | both | warn | <ListTablePagination> 不接受该 prop。已声明的 props:page、pageSize、total、pageSizeOptions、onPageChange、onPageSizeChange。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5938
+ | `props-whitelist-list-table-pagination` | props-whitelist | both | warn | <ListTablePagination> 不接受该 prop。已声明的 props:page、pageSize、total、pageSizeOptions、showJumper、onPageChange、onPageSizeChange。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5240
5939
  | `props-whitelist-search-field` | props-whitelist | both | warn | <SearchField> 不接受该 prop。已声明的 props:value、defaultValue、onChange、onSubmit、placeholder、ariaLabel、disabled、inputProps。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5241
5940
  | `props-whitelist-sidebar-app-link-button` | props-whitelist | both | warn | <SidebarAppLinkButton> 不接受该 prop。已声明的 props:name、glyph、description。继承自 ButtonHTMLAttributes<HTMLButtonElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5242
5941
  | `props-whitelist-sidebar-rail-button` | props-whitelist | both | warn | <SidebarRailButton> 不接受该 prop。已声明的 props:icon、label、active、badge。继承自 ButtonHTMLAttributes<HTMLButtonElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5243
- | `props-whitelist-system-button` | props-whitelist | both | warn | <SystemButton> 不接受该 prop。已声明的 props:intent、size、loading、children。继承自 ButtonHTMLAttributes<HTMLButtonElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5244
- | `prop-enum-system-button-intent` | prop-enum | both | warn | <SystemButton> 的 intent 取值须为 'primary' \| 'secondary' \| 'quiet' \| 'icon' \| 'link' \| 'destructive' 之一 |
5245
- | `prop-enum-system-button-size` | prop-enum | both | warn | <SystemButton> 的 size 取值须为 'default' \| 'compact' \| 'icon' 之一 |
5246
- | `props-whitelist-application-module-switcher` | props-whitelist | both | warn | <ApplicationModuleSwitcher> 不接受该 prop。已声明的 props:moduleName、modules、currentModule、glyph、open、onOpenChange、onSelect。继承自 ButtonHTMLAttributes<HTMLButtonElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5247
- | `props-whitelist-application-primary-navigation` | props-whitelist | both | warn | <ApplicationPrimaryNavigation> 不接受该 prop。已声明的 props:appName、appDescription、appGlyph、activeAction、actionBadges、onAction、compact。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5942
+ | `props-whitelist-system-button` | props-whitelist | both | warn | <SystemButton> 不接受该 prop。已声明的 props:intent、size、iconOnly、loading、children。继承自 ButtonHTMLAttributes<HTMLButtonElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5943
+ | `prop-enum-system-button-intent` | prop-enum | both | warn | <SystemButton> 的 intent 取值须为 'primary' \| 'secondary' \| 'quiet' \| 'link' \| 'destructive' \| 'destructive-outline' 之一 |
5944
+ | `prop-enum-system-button-size` | prop-enum | both | warn | <SystemButton> 的 size 取值须为 'default' \| 'compact' \| 'sm' 之一 |
5945
+ | `props-whitelist-application-module-switcher` | props-whitelist | both | warn | <ApplicationModuleSwitcher> 不接受该 prop。已声明的 props:moduleName、modules、currentModule、open、onOpenChange、onSelect。继承自 ButtonHTMLAttributes<HTMLButtonElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5946
+ | `props-whitelist-application-primary-navigation` | props-whitelist | both | warn | <ApplicationPrimaryNavigation> 不接受该 prop。已声明的 props:appName、appGlyph、activeAction、actionBadges、onAction、account。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5947
+ | `prop-enum-application-primary-navigation-app-glyph` | prop-enum | both | warn | <ApplicationPrimaryNavigation> 的 appGlyph 取值须为 'activity' \| 'arrow-down' \| 'arrow-up' \| 'calendar' \| 'check' \| 'chevron-down' \| 'chevron-left' \| 'chevron-right' \| 'chevron-up' \| 'chevrons-left' \| 'chevrons-right' \| 'circle-alert' \| 'circle-check' \| 'circle-check-big' \| 'columns-2' \| 'download' \| 'ellipsis' \| 'funnel' \| 'info' \| 'kanban' \| 'layout-grid' \| 'list' \| 'message-square' \| 'minus' \| 'pencil' \| 'plus' \| 'refresh-cw' \| 'search' \| 'settings' \| 'shield-check' \| 'sliders-horizontal' \| 'trash-2' \| 'triangle-alert' \| 'upload' \| 'x' 之一 |
5248
5948
  | `prop-enum-application-primary-navigation-active-action` | prop-enum | both | warn | <ApplicationPrimaryNavigation> 的 activeAction 取值须为 'messages' \| 'todos' \| 'overview' \| 'risk' \| 'settings' 之一 |
5249
- | `props-whitelist-application-secondary-navigation` | props-whitelist | both | warn | <ApplicationSecondaryNavigation> 不接受该 prop。已声明的 props:moduleSwitcher、tabs、value、onValueChange。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5949
+ | `props-whitelist-application-secondary-navigation` | props-whitelist | both | warn | <ApplicationSecondaryNavigation> 不接受该 prop。已声明的 props:moduleSwitcher、tabs、value、onValueChange、onNavigationSettings、navigationSettingsOpen、onCloseSettings。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5250
5950
  | `props-whitelist-global-sidebar` | props-whitelist | both | warn | <GlobalSidebar> 不接受该 prop。已声明的 props:items、value、onValueChange、footer。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5251
- | `props-whitelist-top-navigation-primary-bar` | props-whitelist | both | warn | <TopNavigationPrimaryBar> 不接受该 prop。已声明的 props:brandName、brandLogoSrc、center、accountName、onAppSwitch、onAccount。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5951
+ | `props-whitelist-top-navigation-primary-bar` | props-whitelist | both | warn | <TopNavigationPrimaryBar> 不接受该 prop。已声明的 props:brandName、brandLogoSrc、center、accountName、onAppSwitch、onAccount、appSwitchOpen、accountOpen。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5252
5952
  | `props-whitelist-application-metric-chart` | props-whitelist | both | warn | <ApplicationMetricChart> 不接受该 prop。已声明的 props:label、value、unit、data、colorIndex。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5253
5953
  | `props-whitelist-application-metric-primary-secondary` | props-whitelist | both | warn | <ApplicationMetricPrimarySecondary> 不接受该 prop。已声明的 props:label、value、unit、secondary。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5254
5954
  | `props-whitelist-application-metric-status` | props-whitelist | both | warn | <ApplicationMetricStatus> 不接受该 prop。已声明的 props:label、value、status、statusText、note。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5255
5955
  | `prop-enum-application-metric-status-status` | prop-enum | both | warn | <ApplicationMetricStatus> 的 status 取值须为 'normal' \| 'warning' \| 'danger' \| 'info' 之一 |
5256
- | `props-whitelist-application-metric-strip` | props-whitelist | both | warn | <ApplicationMetricStrip> 不接受该 prop。已声明的 props:metrics、columns、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5956
+ | `props-whitelist-application-metric-strip` | props-whitelist | both | warn | <ApplicationMetricStrip> 不接受该 prop。已声明的 props:metrics、columns、children、state、error。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5957
+ | `prop-enum-application-metric-strip-state` | prop-enum | both | warn | <ApplicationMetricStrip> 的 state 取值须为 'ready' \| 'loading' \| 'error' 之一 |
5257
5958
  | `props-whitelist-application-metric-trend` | props-whitelist | both | warn | <ApplicationMetricTrend> 不接受该 prop。已声明的 props:label、value、unit、delta、direction、period。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5258
5959
  | `prop-enum-application-metric-trend-direction` | prop-enum | both | warn | <ApplicationMetricTrend> 的 direction 取值须为 'up' \| 'down' \| 'flat' 之一 |
5259
- | `props-whitelist-application-data-display` | props-whitelist | both | warn | <ApplicationDataDisplay> 不接受该 prop。已声明的 props:presentation、state、batchBar、pagination、loading、empty、error、noPermission、notFound、children。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5960
+ | `props-whitelist-application-data-display` | props-whitelist | both | warn | <ApplicationDataDisplay> 不接受该 prop。已声明的 props:presentation、state、batchBar、notice、pagination、loading、empty、error、noPermission、notFound、children、bodyRef。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5961
+ | `prop-enum-application-data-display-presentation` | prop-enum | both | warn | <ApplicationDataDisplay> 的 presentation 取值须为 'DataTable' \| 'RecordList' \| 'CardList' \| 'KanbanBoard' \| 'Calendar' \| 'Chart' \| 'Timeline' 之一 |
5260
5962
  | `prop-enum-application-data-display-state` | prop-enum | both | warn | <ApplicationDataDisplay> 的 state 取值须为 'ready' \| 'loading' \| 'empty' \| 'error' \| 'no-permission' \| 'not-found' 之一 |
5261
5963
  | `props-whitelist-application-filter-list` | props-whitelist | both | warn | <ApplicationFilterList> 不接受该 prop。已声明的 props:groups、values、onChange、onApply、onReset、search。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5262
- | `props-whitelist-application-page-header` | props-whitelist | both | warn | <ApplicationPageHeader> 不接受该 prop。已声明的 props:title、subtitle、dataStatus、updatedAt、onRefresh、actions、pageModes、pageMode、onPageModeChange、breadcrumb。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5964
+ | `props-whitelist-application-page-header` | props-whitelist | both | warn | <ApplicationPageHeader> 不接受该 prop。已声明的 props:title、subtitle、dataStatus、updatedAt、onRefresh、onBack、backLabel、taskStatus、actions、pageModes、pageMode、onPageModeChange、breadcrumb。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5263
5965
  | `prop-enum-application-page-header-data-status` | prop-enum | both | warn | <ApplicationPageHeader> 的 dataStatus 取值须为 'normal' \| 'refreshing' \| 'failed' 之一 |
5264
5966
  | `prop-enum-application-page-header-page-mode` | prop-enum | both | warn | <ApplicationPageHeader> 的 pageMode 取值须为 'LIST' \| 'CARD' \| 'SPLIT' \| 'BOARD' \| 'CALENDAR' 之一 |
5265
- | `props-whitelist-application-page-layout-container` | props-whitelist | both | warn | <ApplicationPageLayoutContainer> 不接受该 prop。已声明的 props:header、metrics、dataControl、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5266
- | `props-whitelist-application-query-toolbar` | props-whitelist | both | warn | <ApplicationQueryToolbar> 不接受该 prop。已声明的 props:businessViews、businessView、onBusinessViewChange、resultSummary、searchValue、onSearchChange、onSearchSubmit、searchPlaceholder、commonFilters、moreFilters、sort、appliedTags、onRemoveTag、onResetTags、presentation、hasPresentationSettings、onPresentationSettings、viewModeSwitch。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5267
- | `prop-enum-application-query-toolbar-presentation` | prop-enum | both | warn | <ApplicationQueryToolbar> 的 presentation 取值须为 'DataTable' \| 'CardList' \| 'KanbanBoard' \| 'Calendar' \| 'Chart' \| 'Timeline' 之一 |
5268
- | `props-whitelist-application-record-detail-body` | props-whitelist | both | warn | <ApplicationRecordDetailBody> 不接受该 prop。已声明的 props:summary、sections。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5269
- | `props-whitelist-application-split-list-sidebar` | props-whitelist | both | warn | <ApplicationSplitListSidebar> 不接受该 prop。已声明的 props:search、items、value、onValueChange、settings、footer、width。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5967
+ | `props-whitelist-application-page-layout-container` | props-whitelist | both | warn | <ApplicationPageLayoutContainer> 不接受该 prop。已声明的 props:pageType、header、metrics、dataControl、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5968
+ | `prop-enum-application-page-layout-container-page-type` | prop-enum | both | warn | <ApplicationPageLayoutContainer> 的 pageType 取值须为 'WORKBENCH' \| 'MANAGEMENT' \| 'LEDGER' \| 'ANALYSIS' \| 'REPORT' \| 'DETAIL' 之一 |
5969
+ | `props-whitelist-application-query-toolbar` | props-whitelist | both | warn | <ApplicationQueryToolbar> 不接受该 prop。已声明的 props:businessViews、businessView、onBusinessViewChange、resultSummary、searchValue、onSearchChange、onSearchSubmit、searchPlaceholder、searchAriaLabel、commonFilters、moreFilters、sort、appliedTags、onRemoveTag、onResetTags、presentation、hasPresentationSettings、onPresentationSettings、presentationSettingsOpen、viewModeSwitch。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5970
+ | `prop-enum-application-query-toolbar-presentation` | prop-enum | both | warn | <ApplicationQueryToolbar> 的 presentation 取值须为 'DataTable' \| 'RecordList' \| 'CardList' \| 'KanbanBoard' \| 'Calendar' \| 'Chart' \| 'Timeline' 之一 |
5971
+ | `props-whitelist-application-record-detail-body` | props-whitelist | both | warn | <ApplicationRecordDetailBody> 不接受该 prop。已声明的 props:summary、sections、aside。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5972
+ | `props-whitelist-application-split-list-sidebar` | props-whitelist | both | warn | <ApplicationSplitListSidebar> 不接受该 prop。已声明的 props:search、items、value、onValueChange、onClear、settings、footer、width。继承自 HTMLAttributes<HTMLElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5270
5973
  | `props-whitelist-application-record-list` | props-whitelist | both | warn | <ApplicationRecordList> 不接受该 prop。已声明的 props:records、selectable、selected、onSelectedChange、activeId、onOpen、renderRow。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5271
5974
  | `props-whitelist-list-batch-action-bar` | props-whitelist | both | warn | <ListBatchActionBar> 不接受该 prop。已声明的 props:count、onClear、actions、hint。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5272
- | `props-whitelist-application-detail-drawer` | props-whitelist | both | warn | <ApplicationDetailDrawer> 不接受该 prop。已声明的 props:open、title、subtitle、status、width、primaryAction、secondaryActions、onClose、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5273
- | `props-whitelist-application-form-dialog` | props-whitelist | both | warn | <ApplicationFormDialog> 不接受该 prop。已声明的 props:open、title、description、size、columns、submitText、cancelText、submitting、error、onSubmit、onCancel、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5274
- | `prop-enum-application-form-dialog-size` | prop-enum | both | warn | <ApplicationFormDialog> 的 size 取值须为 'small' \| 'large' 之一 |
5275
- | `props-whitelist-application-global-action-panel` | props-whitelist | both | warn | <ApplicationGlobalActionPanel> 不接受该 prop。已声明的 props:open、title、tabs、activeTab、onTabChange、footer、emptyState、onClose、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5975
+ | `props-whitelist-application-detail-drawer` | props-whitelist | both | warn | <ApplicationDetailDrawer> 不接受该 prop。已声明的 props:open、title、subtitle、status、width、side、primaryAction、secondaryActions、onClose、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5976
+ | `prop-enum-application-detail-drawer-side` | prop-enum | both | warn | <ApplicationDetailDrawer> 的 side 取值须为 'left' \| 'right' 之一 |
5977
+ | `props-whitelist-application-form-dialog` | props-whitelist | both | warn | <ApplicationFormDialog> 不接受该 prop。已声明的 props:open、title、description、size、columns、submitText、cancelText、submitting、error、onSubmit、onCancel、secondaryActions、footerNote、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5978
+ | `prop-enum-application-form-dialog-size` | prop-enum | both | warn | <ApplicationFormDialog> 的 size 取值须为 'small' \| 'large' \| 'xlarge' 之一 |
5979
+ | `props-whitelist-application-global-action-panel` | props-whitelist | both | warn | <ApplicationGlobalActionPanel> 不接受该 prop。已声明的 props:open、title、tabs、activeTab、onTabChange、footer、state、loading、emptyState、error、noPermission、onClose、children。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5980
+ | `prop-enum-application-global-action-panel-state` | prop-enum | both | warn | <ApplicationGlobalActionPanel> 的 state 取值须为 'ready' \| 'loading' \| 'empty' \| 'error' \| 'no-permission' 之一 |
5276
5981
  | `props-whitelist-people-picker-dialog` | props-whitelist | both | warn | <PeoplePickerDialog> 不接受该 prop。已声明的 props:open、title、people、selected、onSelectedChange、multiple、onConfirm、onCancel。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5277
- | `props-whitelist-contacts-collaboration-workspace` | props-whitelist | both | warn | <ContactsCollaborationWorkspace> 不接受该 prop。已声明的 props:search、orgTree、activeOrg、onOrgChange、people、activePerson、onPersonChange、detail。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5278
- | `props-whitelist-files-collaboration-workspace` | props-whitelist | both | warn | <FilesCollaborationWorkspace> 不接受该 prop。已声明的 props:search、folders、activeFolder、onFolderChange、files、selected、onSelectedChange、onOpen、toolbar、preview、empty。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5279
- | `props-whitelist-schedule-collaboration-workspace` | props-whitelist | both | warn | <ScheduleCollaborationWorkspace> 不接受该 prop。已声明的 props:month、events、selectedDate、onSelectDate、grain、onGrainChange、toolbar。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5982
+ | `props-whitelist-contacts-collaboration-workspace` | props-whitelist | both | warn | <ContactsCollaborationWorkspace> 不接受该 prop。已声明的 props:search、orgTree、activeOrg、onOrgChange、people、activePerson、onPersonChange、detail、peopleEmpty、detailEmpty、state、loading、empty、error、noPermission、notFound。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5983
+ | `prop-enum-contacts-collaboration-workspace-state` | prop-enum | both | warn | <ContactsCollaborationWorkspace> 的 state 取值须为 'ready' \| 'loading' \| 'empty' \| 'error' \| 'no-permission' \| 'not-found' 之一 |
5984
+ | `props-whitelist-files-collaboration-workspace` | props-whitelist | both | warn | <FilesCollaborationWorkspace> 不接受该 prop。已声明的 props:search、folders、activeFolder、onFolderChange、files、selected、onSelectedChange、onOpen、toolbar、preview、empty、state、loading、error、noPermission、notFound。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5985
+ | `prop-enum-files-collaboration-workspace-state` | prop-enum | both | warn | <FilesCollaborationWorkspace> 的 state 取值须为 'ready' \| 'loading' \| 'empty' \| 'error' \| 'no-permission' \| 'not-found' 之一 |
5986
+ | `props-whitelist-schedule-collaboration-workspace` | props-whitelist | both | warn | <ScheduleCollaborationWorkspace> 不接受该 prop。已声明的 props:month、onMonthChange、events、selectedDate、onSelectDate、grain、onGrainChange、toolbar、agendaEmpty、state、loading、empty、error、noPermission、notFound。继承自 HTMLAttributes<HTMLDivElement> 的属性(onClick、id、aria-* 等)可直接传,会透传到底层元素 |
5280
5987
  | `prop-enum-schedule-collaboration-workspace-grain` | prop-enum | both | warn | <ScheduleCollaborationWorkspace> 的 grain 取值须为 'day' \| 'week' \| 'month' 之一 |
5988
+ | `prop-enum-schedule-collaboration-workspace-state` | prop-enum | both | warn | <ScheduleCollaborationWorkspace> 的 state 取值须为 'ready' \| 'loading' \| 'empty' \| 'error' \| 'no-permission' \| 'not-found' 之一 |
5989
+
5990
+ ## 图标字形
5991
+
5992
+ 共 35 个。`<Icon name>` 只接受下表的名字(类型 `IconName`,清单外的名字在 tsc 与 `prop-enum` 两处被拒),尺寸只取登记档 14 / 16 / 18 / 20 / 24;
5993
+ 绕过类型检查的未登记名字渲染为等尺寸占位盒。确需新字形须先登记进 `@moheng-design/ui` 的图标清单并随包发版,
5994
+ 不得改用内联 `<svg>`。表中用途是该字形在库内的登记用途,业务侧可复用同一字形表达同义动作。
5995
+
5996
+ | 名字 | 登记用途 |
5997
+ |---|---|
5998
+ | `activity` | 全局动作「总览」的字形(18px 档) |
5999
+ | `arrow-down` | ApplicationMetricTrend 的下降方向字形(14px 档) |
6000
+ | `arrow-up` | ApplicationMetricTrend 的上升方向字形(14px 档) |
6001
+ | `calendar` | Page Mode Switch 的 CALENDAR 档字形(16px 档) |
6002
+ | `check` | Select / Combobox 浮层里的选中对勾;ApplicationModuleSwitcher 面板的当前模块(14px chevron 档) |
6003
+ | `chevron-down` | Collapsible 触发器的展开指示;下拉类控件的通用指示符(14px 档) |
6004
+ | `chevron-left` | Calendar 的上一月导航(14px 档);Pagination 上一页与 ApplicationPageHeader 返回按钮(16px 档) |
6005
+ | `chevron-right` | Breadcrumb 的层级分隔符;向前展开的通用指示符(14px 档);Pagination 下一页(16px 档) |
6006
+ | `chevrons-left` | Pagination 首页(16px 档) |
6007
+ | `chevrons-right` | Pagination 末页(16px 档) |
6008
+ | `chevron-up` | Table 表头的升序指示符(14px 档) |
6009
+ | `circle-alert` | Alert 的 danger 状态图标;AlertDialog 页头的提示图标(20px 档,警示色) |
6010
+ | `circle-check` | Alert 的 success 状态图标 |
6011
+ | `circle-check-big` | 全局动作「待办」的字形(18px 档) |
6012
+ | `columns-2` | Page Mode Switch 的 SPLIT 档字形(16px 档) |
6013
+ | `download` | 业务页「导出 / 下载」动作的前置字形(14 / 16px 档) |
6014
+ | `ellipsis` | 行内「更多操作」菜单的触发器字形;Pagination 页码跳空处(16px 档) |
6015
+ | `funnel` | 工具栏「筛选 / 更多筛选」触发器的字形(14 / 16px 档);lucide 已把 filter 更名为 funnel |
6016
+ | `info` | Alert 的 info 状态图标 |
6017
+ | `kanban` | Page Mode Switch 的 BOARD 档字形(16px 档) |
6018
+ | `layout-grid` | 顶栏「应用切换」触发器的字形(16px 档) |
6019
+ | `list` | Page Mode Switch 的 LIST 档字形(16px 档) |
6020
+ | `message-square` | 全局动作「消息」的字形(18px 档) |
6021
+ | `minus` | ApplicationMetricTrend 的持平方向字形(14px 档) |
6022
+ | `pencil` | 业务页「编辑」动作的字形,含行内操作(14 / 16px 档) |
6023
+ | `plus` | 业务页「新建」动作的前置字形(SystemButton 内 14 / 16px 档) |
6024
+ | `refresh-cw` | ApplicationPageHeader 的数据刷新触发器,接在更新时间之后(16px 档) |
6025
+ | `search` | Command 面板的搜索框前置图标;SearchField 同款(16px 档) |
6026
+ | `settings` | 全局动作「设置」的字形(18px 档) |
6027
+ | `shield-check` | ApplicationPrimaryNavigation 应用 logo 的 mock 字形默认值(20px 档) |
6028
+ | `sliders-horizontal` | ApplicationQueryToolbar 的呈现设置按钮与 ApplicationSecondaryNavigation 的导航设置按钮(16px 档,纯图标;kit「二级导航设置」字形逐点吻合) |
6029
+ | `trash-2` | 业务页「删除」动作的字形,含行内与批量条(14 / 16px 档) |
6030
+ | `triangle-alert` | Alert 的 warning 状态图标 |
6031
+ | `upload` | 业务页「导入 / 上传」动作的前置字形(14 / 16px 档) |
6032
+ | `x` | 业务页「移除 / 清空」内容动作的字形(14 / 16px 档);控件自身的关闭叉号仍走 internal/DismissGlyph,不用它 |
5281
6033
 
5282
6034
  ## Token 全表
5283
6035
 
5284
- 共 356 条:`--application-*` 91 条、`--ui-*` 134 条、`--ds-*` 131 条。源是 `packages/ui/src/tokens/*.css`(01 §4.1),
6036
+ 共 389 条:`--application-*` 101 条、`--ui-*` 145 条、`--ds-*` 143 条。源是 `packages/ui/src/tokens/*.css`(01 §4.1),
5285
6037
  本表由其导出产物 `tokens.json` 展平而来 —— CSS 是源,方向不可反转。
5286
6038
 
5287
6039
  值即 CSS 源里的字面量,可直接写进 `var()` 的回退位或用于比对;`var(--…)` 形式表示
@@ -5289,7 +6041,8 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5289
6041
 
5290
6042
  **应用代码只读 `--application-*` 与 `--ui-*`**(表中在前)。`--ds-*` 是 Foundation
5291
6043
  内部实现,不构成公开接口,任意小版本都可能改动,唯一可覆盖的是换肤入口
5292
- `--ds-color-theme-primary`。层内顺序即 CSS 源文件的书写顺序。
6044
+ `--ds-color-theme-primary`,唯一可读取的是焦点环几何 `--ds-focus-ring-width` /
6045
+ `--ds-focus-ring-offset`。层内顺序即 CSS 源文件的书写顺序。
5293
6046
 
5294
6047
  | token | 值 | 层 |
5295
6048
  |---|---|---|
@@ -5302,7 +6055,7 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5302
6055
  | `--application-placeholder` | `var(--ds-color-text-placeholder)` | `--application-*` |
5303
6056
  | `--application-border` | `var(--ds-color-border)` | `--application-*` |
5304
6057
  | `--application-divider` | `var(--ds-color-divider)` | `--application-*` |
5305
- | `--application-table-header` | `var(--ds-color-surface-subtle)` | `--application-*` |
6058
+ | `--application-table-header` | `var(--ds-color-canvas)` | `--application-*` |
5306
6059
  | `--application-drawer-action-secondary-border` | `var(--ds-color-divider)` | `--application-*` |
5307
6060
  | `--application-drawer-action-secondary-text` | `var(--ds-color-text)` | `--application-*` |
5308
6061
  | `--application-accent` | `var(--ds-color-theme-primary)` | `--application-*` |
@@ -5325,7 +6078,7 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5325
6078
  | `--application-font-size-body` | `var(--ds-font-size-14)` | `--application-*` |
5326
6079
  | `--application-font-size-title` | `var(--ds-font-size-16)` | `--application-*` |
5327
6080
  | `--application-font-size-heading` | `var(--ds-font-size-20)` | `--application-*` |
5328
- | `--application-font-size-metric` | `var(--ds-font-size-24)` | `--application-*` |
6081
+ | `--application-font-size-metric` | `var(--ds-font-size-32)` | `--application-*` |
5329
6082
  | `--application-metric-trend-up` | `var(--ds-color-text-tertiary)` | `--application-*` |
5330
6083
  | `--application-line-height-meta` | `var(--ds-line-height-16)` | `--application-*` |
5331
6084
  | `--application-line-height-body` | `var(--ds-line-height-20)` | `--application-*` |
@@ -5340,8 +6093,9 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5340
6093
  | `--application-space-5` | `var(--ds-space-5)` | `--application-*` |
5341
6094
  | `--application-form-dialog-width-small` | `720px` | `--application-*` |
5342
6095
  | `--application-form-dialog-width-large` | `960px` | `--application-*` |
6096
+ | `--application-form-dialog-width-xlarge` | `1280px` | `--application-*` |
5343
6097
  | `--application-content-header-height` | `48px` | `--application-*` |
5344
- | `--application-metric-strip-height` | `84px` | `--application-*` |
6098
+ | `--application-metric-strip-height` | `76px` | `--application-*` |
5345
6099
  | `--application-toolbar-height` | `32px` | `--application-*` |
5346
6100
  | `--application-drawer-width` | `1280px` | `--application-*` |
5347
6101
  | `--application-categorical-10` | `var(--ds-color-categorical-10)` | `--application-*` |
@@ -5370,6 +6124,10 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5370
6124
  | `--application-radius-12` | `var(--ds-radius-12)` | `--application-*` |
5371
6125
  | `--application-radius-16` | `var(--ds-radius-16)` | `--application-*` |
5372
6126
  | `--application-radius-20` | `var(--ds-radius-20)` | `--application-*` |
6127
+ | `--application-radius-control` | `var(--ds-radius-control)` | `--application-*` |
6128
+ | `--application-radius-card` | `var(--ds-radius-card)` | `--application-*` |
6129
+ | `--application-radius-tag` | `var(--ds-radius-tag)` | `--application-*` |
6130
+ | `--application-radius-dialog` | `var(--ds-radius-dialog)` | `--application-*` |
5373
6131
  | `--application-hover-neutral` | `var(--ds-color-hover-neutral)` | `--application-*` |
5374
6132
  | `--application-metric-delta` | `var(--application-metric-trend-up)` | `--application-*` |
5375
6133
  | `--application-active` | `var(--ds-color-active-accent)` | `--application-*` |
@@ -5384,14 +6142,20 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5384
6142
  | `--application-font-weight-bold` | `var(--ds-font-weight-bold)` | `--application-*` |
5385
6143
  | `--application-nav-item-height` | `var(--ds-nav-item-height)` | `--application-*` |
5386
6144
  | `--application-avatar-fallback-surface` | `var(--ds-color-bg-4)` | `--application-*` |
5387
- | `--ui-shell-primary-height` | `52px` | `--ui-*` |
6145
+ | `--application-hairline` | `var(--ds-hairline)` | `--application-*` |
6146
+ | `--application-spacing-6` | `var(--ds-spacing-6)` | `--application-*` |
6147
+ | `--application-spacing-10` | `var(--ds-spacing-10)` | `--application-*` |
6148
+ | `--application-spacing-20` | `var(--ds-spacing-20)` | `--application-*` |
6149
+ | `--application-tint-accent` | `var(--ds-color-tint-accent)` | `--application-*` |
6150
+ | `--ui-shell-primary-height` | `48px` | `--ui-*` |
5388
6151
  | `--ui-shell-secondary-height` | `44px` | `--ui-*` |
5389
- | `--ui-shell-application-title-height` | `64px` | `--ui-*` |
6152
+ | `--ui-shell-application-title-height` | `48px` | `--ui-*` |
5390
6153
  | `--ui-shell-application-subnav-height` | `48px` | `--ui-*` |
5391
- | `--ui-shell-application-total-height` | `calc(var(--ui-shell-primary-height) + var(--ui-shell-application-title-height) + var(--ui-shell-application-subnav-height))` | `--ui-*` |
6154
+ | `--ui-shell-application-total-height` | `calc(var(--ui-shell-top-bar-offset,0px) + var(--ui-shell-application-title-height) + var(--ui-shell-application-subnav-height))` | `--ui-*` |
6155
+ | `--ui-shell-band-divider` | `inset 0 calc(-1 * var(--ds-hairline)) 0 0 var(--ds-color-border)` | `--ui-*` |
5392
6156
  | `--ui-shell-navigation-z` | `10` | `--ui-*` |
5393
6157
  | `--ui-shell-topbar-gap` | `var(--ds-space-5)` | `--ui-*` |
5394
- | `--ui-shell-topbar-padding-block` | `var(--ds-space-3)` | `--ui-*` |
6158
+ | `--ui-shell-topbar-padding-block` | `var(--ds-space-2)` | `--ui-*` |
5395
6159
  | `--ui-shell-topbar-padding-inline` | `var(--ds-space-3)` | `--ui-*` |
5396
6160
  | `--ui-shell-topbar-backdrop-blur` | `20px` | `--ui-*` |
5397
6161
  | `--ui-shell-brand-min-width` | `120px` | `--ui-*` |
@@ -5399,27 +6163,32 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5399
6163
  | `--ui-shell-brand-height` | `32px` | `--ui-*` |
5400
6164
  | `--ui-shell-account-cluster-height` | `32px` | `--ui-*` |
5401
6165
  | `--ui-shell-account-gap` | `10px` | `--ui-*` |
6166
+ | `--ui-shell-account-avatar-size` | `24px` | `--ui-*` |
5402
6167
  | `--ui-shell-control-size` | `32px` | `--ui-*` |
5403
6168
  | `--ui-shell-topbar-icon-size` | `16px` | `--ui-*` |
5404
6169
  | `--ui-shell-utility-icon-size` | `20px` | `--ui-*` |
5405
6170
  | `--ui-shell-application-row-gap` | `var(--ds-space-3)` | `--ui-*` |
5406
- | `--ui-shell-application-row-padding-block` | `var(--ds-space-3)` | `--ui-*` |
6171
+ | `--ui-shell-application-row-padding-block` | `var(--ds-space-2)` | `--ui-*` |
5407
6172
  | `--ui-shell-application-row-padding-inline` | `var(--ds-space-3)` | `--ui-*` |
5408
- | `--ui-shell-application-identity-height` | `48px` | `--ui-*` |
5409
- | `--ui-shell-application-logo-size` | `48px` | `--ui-*` |
6173
+ | `--ui-shell-application-identity-height` | `32px` | `--ui-*` |
6174
+ | `--ui-shell-application-logo-size` | `32px` | `--ui-*` |
6175
+ | `--ui-shell-application-logo-radius` | `var(--ds-radius-8)` | `--ui-*` |
5410
6176
  | `--ui-shell-application-logo-background` | `color-mix(in srgb,var(--application-accent) 8%,var(--application-surface))` | `--ui-*` |
5411
6177
  | `--ui-shell-application-logo-foreground` | `var(--application-accent)` | `--ui-*` |
5412
- | `--ui-shell-application-identity-gap` | `var(--ds-space-2)` | `--ui-*` |
6178
+ | `--ui-shell-application-identity-gap` | `var(--ds-space-1)` | `--ui-*` |
5413
6179
  | `--ui-shell-title-line-gap` | `var(--ds-space-2)` | `--ui-*` |
5414
6180
  | `--ui-shell-actions-gap` | `var(--ds-space-2)` | `--ui-*` |
5415
6181
  | `--ui-shell-global-actions-height` | `var(--ui-shell-control-size)` | `--ui-*` |
5416
- | `--ui-shell-global-actions-gap` | `var(--ds-space-2)` | `--ui-*` |
5417
- | `--ui-shell-global-actions-padding-right` | `var(--ds-space-2)` | `--ui-*` |
6182
+ | `--ui-shell-global-actions-gap` | `var(--ds-space-1)` | `--ui-*` |
6183
+ | `--ui-shell-global-actions-padding-right` | `0px` | `--ui-*` |
6184
+ | `--ui-shell-global-actions-account-gap` | `var(--ds-space-2)` | `--ui-*` |
5418
6185
  | `--ui-shell-global-action-group-gap` | `var(--ds-space-1)` | `--ui-*` |
5419
6186
  | `--ui-shell-global-action-group-padding-left` | `var(--ds-space-2)` | `--ui-*` |
5420
6187
  | `--ui-shell-global-action-size` | `var(--ui-shell-control-size)` | `--ui-*` |
5421
6188
  | `--ui-shell-global-action-icon-size` | `18px` | `--ui-*` |
5422
- | `--ui-shell-global-action-radius` | `var(--ds-radius-16)` | `--ui-*` |
6189
+ | `--ui-shell-global-action-padding-inline` | `10px` | `--ui-*` |
6190
+ | `--ui-shell-global-action-label-gap` | `var(--ds-space-1)` | `--ui-*` |
6191
+ | `--ui-shell-global-action-radius` | `var(--ds-radius-12)` | `--ui-*` |
5423
6192
  | `--ui-shell-global-action-tooltip-offset` | `var(--ds-space-2)` | `--ui-*` |
5424
6193
  | `--ui-shell-global-action-tooltip-height` | `28px` | `--ui-*` |
5425
6194
  | `--ui-shell-global-action-tooltip-padding-inline` | `10px` | `--ui-*` |
@@ -5430,8 +6199,8 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5430
6199
  | `--ui-shell-global-action-popover-radius` | `var(--ds-radius-20)` | `--ui-*` |
5431
6200
  | `--ui-shell-global-action-panel-max-height` | `680px` | `--ui-*` |
5432
6201
  | `--ui-shell-global-action-panel-viewport-offset` | `120px` | `--ui-*` |
5433
- | `--ui-shell-module-row-gap` | `20px` | `--ui-*` |
5434
- | `--ui-shell-module-row-padding-block` | `var(--ds-space-2)` | `--ui-*` |
6202
+ | `--ui-shell-module-row-gap` | `var(--ds-space-2)` | `--ui-*` |
6203
+ | `--ui-shell-module-row-padding-block` | `0px` | `--ui-*` |
5435
6204
  | `--ui-shell-module-row-padding-inline` | `var(--ds-space-3)` | `--ui-*` |
5436
6205
  | `--ui-shell-module-trigger-size` | `32px` | `--ui-*` |
5437
6206
  | `--ui-shell-module-trigger-icon-size` | `20px` | `--ui-*` |
@@ -5440,6 +6209,8 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5440
6209
  | `--ui-shell-tab-gap` | `var(--ds-space-1)` | `--ui-*` |
5441
6210
  | `--ui-shell-tab-padding-block` | `6px` | `--ui-*` |
5442
6211
  | `--ui-shell-tab-padding-inline` | `var(--ds-space-3)` | `--ui-*` |
6212
+ | `--ui-shell-tab-radius` | `var(--ds-radius-12)` | `--ui-*` |
6213
+ | `--ui-shell-tab-indicator-inset` | `var(--ds-space-3)` | `--ui-*` |
5443
6214
  | `--ui-shell-tab-indicator-width` | `80px` | `--ui-*` |
5444
6215
  | `--ui-shell-tab-indicator-height` | `2px` | `--ui-*` |
5445
6216
  | `--ui-shell-tab-indicator-offset` | `-8px` | `--ui-*` |
@@ -5452,26 +6223,29 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5452
6223
  | `--ui-shell-content-background` | `var(--application-elevated)` | `--ui-*` |
5453
6224
  | `--ui-shell-content-padding` | `var(--ds-space-3)` | `--ui-*` |
5454
6225
  | `--ui-shell-content-gap` | `var(--ds-space-3)` | `--ui-*` |
5455
- | `--ui-shell-brand-fallback-mark-size` | `28px` | `--ui-*` |
6226
+ | `--ui-shell-brand-fallback-mark-size` | `36px` | `--ui-*` |
5456
6227
  | `--ui-shell-brand-fallback-mark-background` | `var(--application-text)` | `--ui-*` |
5457
6228
  | `--ui-shell-brand-fallback-mark-radius` | `var(--ds-radius-4)` | `--ui-*` |
5458
6229
  | `--ui-shell-brand-fallback-name-gap` | `var(--ds-space-2)` | `--ui-*` |
5459
- | `--ui-shell-brand-fallback-name-size` | `var(--ds-font-size-14)` | `--ui-*` |
5460
- | `--ui-shell-brand-fallback-name-line-height` | `var(--ds-line-height-20)` | `--ui-*` |
6230
+ | `--ui-shell-brand-fallback-name-size` | `var(--ds-font-size-20)` | `--ui-*` |
6231
+ | `--ui-shell-brand-fallback-name-line-height` | `var(--ds-line-height-30)` | `--ui-*` |
5461
6232
  | `--ui-shell-application-logo-mock-glyph-size` | `24px` | `--ui-*` |
5462
6233
  | `--ui-shell-module-switch-trigger-min-width` | `168px` | `--ui-*` |
5463
- | `--ui-shell-module-switch-trigger-height` | `40px` | `--ui-*` |
6234
+ | `--ui-shell-module-switch-trigger-height` | `48px` | `--ui-*` |
5464
6235
  | `--ui-shell-module-switch-trigger-padding-top` | `4px` | `--ui-*` |
5465
- | `--ui-shell-module-switch-trigger-padding-right` | `8px` | `--ui-*` |
6236
+ | `--ui-shell-module-switch-trigger-padding-right` | `var(--ds-space-3)` | `--ui-*` |
5466
6237
  | `--ui-shell-module-switch-trigger-padding-bottom` | `4px` | `--ui-*` |
5467
- | `--ui-shell-module-switch-trigger-padding-left` | `4px` | `--ui-*` |
6238
+ | `--ui-shell-module-switch-trigger-padding-left` | `var(--ds-space-3)` | `--ui-*` |
6239
+ | `--ui-shell-module-switch-trigger-divider` | `inset calc(-1 * var(--ds-hairline)) 0 0 0 var(--ds-color-border)` | `--ui-*` |
5468
6240
  | `--ui-shell-module-switch-trigger-gap` | `var(--ds-space-2)` | `--ui-*` |
5469
6241
  | `--ui-shell-module-switch-copy-gap` | `1px` | `--ui-*` |
5470
6242
  | `--ui-shell-module-switch-icon-box-size` | `32px` | `--ui-*` |
5471
6243
  | `--ui-shell-module-switch-icon-glyph-size` | `18px` | `--ui-*` |
5472
- | `--ui-shell-module-switch-chevron-size` | `14px` | `--ui-*` |
5473
- | `--ui-shell-module-switch-panel-width` | `320px` | `--ui-*` |
5474
- | `--ui-shell-module-switch-panel-padding` | `var(--ds-space-3)` | `--ui-*` |
6244
+ | `--ui-shell-module-switch-chevron-size` | `20px` | `--ui-*` |
6245
+ | `--ui-shell-module-switch-check-size` | `14px` | `--ui-*` |
6246
+ | `--ui-shell-module-switch-panel-width` | `168px` | `--ui-*` |
6247
+ | `--ui-shell-module-switch-panel-min-width` | `128px` | `--ui-*` |
6248
+ | `--ui-shell-module-switch-panel-padding` | `var(--ds-space-1)` | `--ui-*` |
5475
6249
  | `--ui-shell-module-switch-panel-gap` | `2px` | `--ui-*` |
5476
6250
  | `--ui-shell-module-switch-item-min-height` | `40px` | `--ui-*` |
5477
6251
  | `--ui-shell-module-switch-item-gap` | `var(--ds-space-2)` | `--ui-*` |
@@ -5480,11 +6254,11 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5480
6254
  | `--ui-shell-module-switch-item-line-height` | `22px` | `--ui-*` |
5481
6255
  | `--ui-shell-module-switch-icon-background` | `var(--ds-color-bg-4)` | `--ui-*` |
5482
6256
  | `--ui-shell-module-switch-icon-foreground` | `var(--ds-color-fg-4)` | `--ui-*` |
5483
- | `--ui-shell-module-switch-panel-background` | `var(--ds-color-canvas)` | `--ui-*` |
6257
+ | `--ui-shell-module-switch-panel-background` | `color-mix(in srgb,var(--ds-color-canvas) 50%,var(--ds-color-surface))` | `--ui-*` |
5484
6258
  | `--ui-shell-module-switch-panel-border` | `var(--ds-color-border)` | `--ui-*` |
5485
6259
  | `--ui-shell-module-switch-panel-border-rule` | `1px solid var(--ui-shell-module-switch-panel-border)` | `--ui-*` |
5486
- | `--ui-shell-module-switch-item-hover` | `var(--ds-color-hover-neutral)` | `--ui-*` |
5487
- | `--ui-shell-module-switch-item-active` | `color-mix(in srgb,var(--ds-color-surface-subtle) 12%,transparent)` | `--ui-*` |
6260
+ | `--ui-shell-module-switch-item-hover` | `var(--ds-color-canvas)` | `--ui-*` |
6261
+ | `--ui-shell-module-switch-item-active` | `transparent` | `--ui-*` |
5488
6262
  | `--ui-shell-module-switch-item-active-text` | `var(--ds-color-application-accent)` | `--ui-*` |
5489
6263
  | `--ui-shell-global-action-active-background` | `color-mix(in srgb,var(--ds-color-application-accent) 12%,transparent)` | `--ui-*` |
5490
6264
  | `--ui-shell-global-action-active-text` | `var(--ds-color-application-accent)` | `--ui-*` |
@@ -5508,7 +6282,7 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5508
6282
  | `--ui-overlay-viewport-gutter` | `var(--ds-space-4)` | `--ui-*` |
5509
6283
  | `--ui-application-title-max-width-compact` | `220px` | `--ui-*` |
5510
6284
  | `--ui-border-default` | `1px solid var(--application-border)` | `--ui-*` |
5511
- | `--ui-divider-default` | `1px solid var(--application-divider)` | `--ui-*` |
6285
+ | `--ui-divider-default` | `var(--ds-hairline) solid var(--application-divider)` | `--ui-*` |
5512
6286
  | `--ui-shadow-surface` | `0 4px 14px color-mix(in srgb,var(--ds-color-text) 4%,transparent)` | `--ui-*` |
5513
6287
  | `--ui-shadow-floating` | `0 18px 52px color-mix(in srgb,var(--ds-color-text) 14%,transparent)` | `--ui-*` |
5514
6288
  | `--ui-duration-fast` | `150ms` | `--ui-*` |
@@ -5525,6 +6299,7 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5525
6299
  | `--ds-font-size-16` | `16px` | `--ds-*` |
5526
6300
  | `--ds-font-size-20` | `20px` | `--ds-*` |
5527
6301
  | `--ds-font-size-24` | `24px` | `--ds-*` |
6302
+ | `--ds-font-size-32` | `32px` | `--ds-*` |
5528
6303
  | `--ds-font-size-caption` | `var(--ds-font-size-12)` | `--ds-*` |
5529
6304
  | `--ds-font-size-body` | `var(--ds-font-size-14)` | `--ds-*` |
5530
6305
  | `--ds-font-size-title` | `var(--ds-font-size-16)` | `--ds-*` |
@@ -5534,6 +6309,7 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5534
6309
  | `--ds-line-height-20` | `20px` | `--ds-*` |
5535
6310
  | `--ds-line-height-24` | `24px` | `--ds-*` |
5536
6311
  | `--ds-line-height-28` | `28px` | `--ds-*` |
6312
+ | `--ds-line-height-30` | `30px` | `--ds-*` |
5537
6313
  | `--ds-line-height-32` | `32px` | `--ds-*` |
5538
6314
  | `--ds-line-height-caption` | `var(--ds-line-height-16)` | `--ds-*` |
5539
6315
  | `--ds-line-height-body` | `var(--ds-line-height-20)` | `--ds-*` |
@@ -5545,20 +6321,20 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5545
6321
  | `--ds-font-weight-semibold` | `600` | `--ds-*` |
5546
6322
  | `--ds-font-weight-bold` | `700` | `--ds-*` |
5547
6323
  | `--ds-color-bg-1` | `#ffffff` | `--ds-*` |
5548
- | `--ds-color-bg-2` | `#FAFAF9` | `--ds-*` |
5549
- | `--ds-color-bg-3` | `#F2F2EF` | `--ds-*` |
6324
+ | `--ds-color-bg-2` | `#F5F4F1` | `--ds-*` |
6325
+ | `--ds-color-bg-3` | `#F0EEE9` | `--ds-*` |
5550
6326
  | `--ds-color-bg-4` | `#E7E6E2` | `--ds-*` |
5551
- | `--ds-color-bg-5` | `#DAD9D3` | `--ds-*` |
6327
+ | `--ds-color-bg-5` | `#DDDBD5` | `--ds-*` |
5552
6328
  | `--ds-color-bg-6` | `#B5A86D` | `--ds-*` |
5553
- | `--ds-color-fg-1` | `#B2B1AE` | `--ds-*` |
5554
- | `--ds-color-fg-2` | `#878682` | `--ds-*` |
5555
- | `--ds-color-fg-3` | `#53534E` | `--ds-*` |
5556
- | `--ds-color-fg-4` | `#282722` | `--ds-*` |
5557
- | `--ds-color-blue-1` | `#0080ff` | `--ds-*` |
6329
+ | `--ds-color-fg-1` | `#B9B8B6` | `--ds-*` |
6330
+ | `--ds-color-fg-2` | `#9A9994` | `--ds-*` |
6331
+ | `--ds-color-fg-3` | `#696865` | `--ds-*` |
6332
+ | `--ds-color-fg-4` | `#1F1E1A` | `--ds-*` |
6333
+ | `--ds-color-blue-1` | `#0066ff` | `--ds-*` |
5558
6334
  | `--ds-color-primary` | `#0071e3` | `--ds-*` |
5559
- | `--ds-color-green-1` | `#1fc16b` | `--ds-*` |
5560
- | `--ds-color-orange-1` | `#ff9e00` | `--ds-*` |
5561
- | `--ds-color-red-1` | `#f23030` | `--ds-*` |
6335
+ | `--ds-color-green-1` | `#0dbe73` | `--ds-*` |
6336
+ | `--ds-color-orange-1` | `#ff7b00` | `--ds-*` |
6337
+ | `--ds-color-red-1` | `#e11919` | `--ds-*` |
5562
6338
  | `--ds-color-blue-2` | `var(--ds-color-primary)` | `--ds-*` |
5563
6339
  | `--ds-color-static-white` | `#ffffff` | `--ds-*` |
5564
6340
  | `--ds-color-theme-primary` | `var(--ds-color-primary)` | `--ds-*` |
@@ -5608,7 +6384,7 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5608
6384
  | `--ds-color-info` | `var(--ds-color-status-info)` | `--ds-*` |
5609
6385
  | `--ds-color-hover-neutral` | `color-mix(in srgb,var(--ds-color-text) 6%,transparent)` | `--ds-*` |
5610
6386
  | `--ds-color-disabled` | `color-mix(in srgb,var(--ds-color-text) 38%,transparent)` | `--ds-*` |
5611
- | `--ds-color-overlay` | `color-mix(in srgb,var(--ds-color-text) 24%,transparent)` | `--ds-*` |
6387
+ | `--ds-color-overlay` | `color-mix(in srgb,var(--ds-color-text) 25%,transparent)` | `--ds-*` |
5612
6388
  | `--ds-color-drawer-border` | `var(--ds-color-divider)` | `--ds-*` |
5613
6389
  | `--ds-color-action-neutral` | `var(--ds-color-text)` | `--ds-*` |
5614
6390
  | `--ds-color-hover-accent` | `color-mix(in srgb,var(--ds-color-theme-primary) 8%,transparent)` | `--ds-*` |
@@ -5616,6 +6392,7 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5616
6392
  | `--ds-color-active-accent` | `color-mix(in srgb,var(--ds-color-theme-primary) 12%,transparent)` | `--ds-*` |
5617
6393
  | `--ds-color-active-neutral` | `color-mix(in srgb,var(--ds-color-text) 12%,transparent)` | `--ds-*` |
5618
6394
  | `--ds-color-focus` | `var(--ds-color-theme-primary)` | `--ds-*` |
6395
+ | `--ds-color-tint-accent` | `color-mix(in srgb,var(--ds-color-theme-primary) 6%,transparent)` | `--ds-*` |
5619
6396
  | `--ds-space-0` | `0px` | `--ds-*` |
5620
6397
  | `--ds-space-1` | `4px` | `--ds-*` |
5621
6398
  | `--ds-space-2` | `8px` | `--ds-*` |
@@ -5630,6 +6407,10 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5630
6407
  | `--ds-radius-12` | `12px` | `--ds-*` |
5631
6408
  | `--ds-radius-16` | `16px` | `--ds-*` |
5632
6409
  | `--ds-radius-20` | `20px` | `--ds-*` |
6410
+ | `--ds-radius-control` | `var(--ds-radius-12)` | `--ds-*` |
6411
+ | `--ds-radius-card` | `var(--ds-radius-20)` | `--ds-*` |
6412
+ | `--ds-radius-tag` | `var(--ds-radius-20)` | `--ds-*` |
6413
+ | `--ds-radius-dialog` | `var(--ds-radius-20)` | `--ds-*` |
5633
6414
  | `--ds-control-height-24` | `24px` | `--ds-*` |
5634
6415
  | `--ds-control-height-28` | `28px` | `--ds-*` |
5635
6416
  | `--ds-control-height-32` | `32px` | `--ds-*` |
@@ -5649,3 +6430,8 @@ Application Module 层的 26 个组件强绑定 `pageType` / `pageMode` / `busin
5649
6430
  | `--ds-tab-padding-inline` | `var(--ds-space-3)` | `--ds-*` |
5650
6431
  | `--ds-tab-underline-width` | `2px` | `--ds-*` |
5651
6432
  | `--ds-nav-item-height` | `36px` | `--ds-*` |
6433
+ | `--ds-card-padding` | `var(--ds-space-4)` | `--ds-*` |
6434
+ | `--ds-hairline` | `0.5px` | `--ds-*` |
6435
+ | `--ds-spacing-6` | `6px` | `--ds-*` |
6436
+ | `--ds-spacing-10` | `10px` | `--ds-*` |
6437
+ | `--ds-spacing-20` | `20px` | `--ds-*` |