@linhey/rhine-design 0.3.0 → 0.5.0

package/docs/ANTD_MUI_AUDIT.md

@@ -0,0 +1,38 @@
+# Ant Design / MUI：应用组件逐项核对
+
+2026-10-24，issues #1–#6 的 0.5.0 API。核对覆盖全部 11 个新组件及 DataTable、Pagination、StatusTimeline 的扩展。依据官方在线文档，再用本库测试和真实展台验证行为；未安装这两套 UI 库，也不声称 API 兼容或完整功能等价。
+
+## 组件覆盖与修复
+
+| 本库组件 | Ant Design 对应 | MUI 对应 | 本轮落地 |
+| --- | --- | --- | --- |
+| DateField | DatePicker | X DateField | 只读/表单标识、动态日期范围错误、校验通知 |
+| DateRangePicker | RangePicker | X DateRangePicker | 两端校验、无效预设禁用、只读/清空配置、可定制字段标签 |
+| NumberField | InputNumber | Number Field 官方 Base UI 组合示例 | 只读、Escape 撤销、空值步进修正、动态边界反馈、控制按钮配置 |
+| RemoteMultiSelect | Select multiple | Autocomplete multiple | 连续选择、多选语义、空查询 Backspace、删除后焦点、只读、原生表单提交 |
+| TreeSelect | TreeSelect / Tree | X Tree View | 已选项进入焦点、字符定位、批量键盘操作、结构节点、收起后焦点、只读 |
+| DataTable 扩展 | Table | Table / X Data Grid | 单选/隐藏全选、取消排序、禁止展开约束、稳定详情 ID、行标题、多固定列自动偏移 |
+| Pagination 扩展 | Pagination | TablePagination | 首末页、独立禁用/名称、未知总量和越界恢复、边界焦点 |
+| Background | Layout / ConfigProvider tokens | Box / Paper / theme | 保留六场景语义与局部覆盖；补 DOM ref |
+| AppShell | Layout.Sider / Drawer | permanent / temporary Drawer | 独立受控移动抽屉、正确左右方向、栏宽/断点配置、缩放下容器判断 |
+| MediaCard | Card / Image | CardActionArea / CardMedia / CardActions | 独立重试等 actions、原生属性/ref、打开与选择保持分离 |
+| MediaViewer | Image PreviewGroup / Modal | Dialog + 自定义画廊 | 方向键、首尾禁用与焦点、defaultOpen、可直接切换信息栏、嵌套编辑与播放按键隔离 |
+| StatusTimeline 扩展 | Slider + Popover | Slider + 浮层 | 稳定 ID、受控/默认选中与开关、禁用、键盘进入详情 |
+| TrendChart | 独立 Ant Design Charts Line / Column | X LineChart / BarChart | 键盘/指针逐点查看、受控高亮、格式化、原始数据保留、极值坐标修正 |
+| StackedBar | Ant Design Charts Bar percent | X stacked BarChart | 数值格式化、零值不留假色段；保留未知总量保护 |
+
+## 详细 API 与交互证据
+
+- [表单逐项对照](audits/FORMS_ANTD_MUI.md)：5 个组件、官方 API 链接、数据类型、事件、键盘、状态、表单关联及保留差异。
+- [数据表与分页逐项对照](audits/DATA_ANTD_MUI.md)：选择、排序、展开、固定列、分页与焦点。
+- [背景、外壳与媒体逐项对照](audits/SHELL_MEDIA_ANTD_MUI.md)：组合、受控状态、响应式、浮层及媒体导航。
+- [监控逐项对照](audits/MONITORING_ANTD_MUI.md)：时段与事件轴区分、图表数值/键盘、缺失数据及格式化。
+- [最终验证](ISSUE_VALIDATION.md)：以本轮实测结果为准；官方库自身能力不能替代 Rhine 的验证。
+
+## 接入变化与范围
+
+原有必填参数保持兼容。RemoteMultiSelect 默认选择后保持候选打开，便于连续选择；如需原行为设 `closeOnSelect`。原单选 Combobox 仍默认选完关闭。其他新参数均为可选，现有受控调用无需迁移。新导出的 `PaginationProps`、`StatusTimelineProps` 与原有组件 Props 一同从包入口可用。
+
+保留 ISO 日期字符串、宿主服务端查询与分页、树父子独立选择、原生 table、单序列轻图表及 slot 媒体内容。自绘日历/时区适配器、树级联与虚拟化、可编辑网格、多轴图表、图像旋转缩放/播放引擎未纳入；各分项说明了为何不采用以及对应差异。组件 props 不增加 AntD/MUI 同义别名，不新增运行时依赖，不迁移消费应用。
+
+这些变化自 0.5.0 提供，npm 0.4.0 不包含本页 API；精确制品与消费验证见[版本验收](ISSUE_VALIDATION.md)。

package/docs/APPLICATION_COMPONENTS.md

@@ -0,0 +1,175 @@
+# 应用组件与状态契约
+
+本页对应 GitHub issues [#1](https://github.com/linhay/rhine-design/issues/1)、[#2](https://github.com/linhay/rhine-design/issues/2)、[#3](https://github.com/linhay/rhine-design/issues/3)、[#4](https://github.com/linhay/rhine-design/issues/4)、[#5](https://github.com/linhay/rhine-design/issues/5)、[#6](https://github.com/linhay/rhine-design/issues/6)。新增 11 个组件，公共组件总数为 59。
+
+**版本边界：以下 API 自 0.5.0 提供，npm 0.4.0 不含这些能力。** 本次不改变现有组件必填参数；DataTable/Pagination 的参数均为新增可选项。使用 `npm install --save-exact @linhey/rhine-design@0.5.0` 并提交 lockfile。组件库升级不代表消费应用已经迁移。
+
+公开类型从包主入口导出，真实实现是 API 权威：`Background.tsx`、`AppShell.tsx`、`AdvancedForms.tsx`、`Media.tsx`、`Data.tsx`。兼容范围沿用 React 19 + Vite；native WebView、其他构建器、SSR 和屏幕阅读器组合需消费项目另行验证。无需新增依赖。
+
+2026-10-24 已对全部新增组件及扩展逐项核对 Ant Design / MUI 官方 API 与交互，修复与保留差异见[对标清单](ANTD_MUI_AUDIT.md)。以下契约包含本轮补齐；原有必填参数保持兼容。
+
+## 背景层级
+
+| 区域 | token / API | 规则 |
+| --- | --- | --- |
+| 应用画布 | `--rhine-canvas-bg`，`roleTone="canvas"` | 整体底色，允许主题纹理 |
+| 正文区域 | `--rhine-content-bg`，`roleTone="content"`（默认） | 默认纯色；显式 `decoration="theme"` 可启用主题纹理 |
+| 全局 / 上下文 / 辅助侧栏 | `--rhine-sidebar-bg`，`roleTone="sidebar"` | 不透明纯色，边界使用 `--rhine-line` |
+| 卡片 / 表单 | `--rhine-surface-bg`，`roleTone="surface"` | 不透明阅读表面，默认无纹理 |
+| 弹窗 / 浮层 | `--rhine-overlay-bg`，`roleTone="overlay"` | 默认无纹理，遮罩独立使用 `--rhine-backdrop-bg` |
+| 图片 / 视频 | `--rhine-media-bg`，`roleTone="media"` | 中性深色底与配套浅色文字，默认无纹理 |
+
+纸面默认无纹理；战术终端使用 32px 低对比网格；橙趣使用 14px 点阵。主题统一提供 `--rhine-background-texture`、`--rhine-background-scale`、`--rhine-background-mark`，无需消费者复制渐变。`decoration="auto"` 为默认值，仅 canvas 使用主题纹理，正文和 AppShell 默认纯色。`theme` 显式启用主题纹理，`none` 关闭本区域装饰，主题切换不会重新启用它。Background 另提供 surface/overlay/media 场景及局部 appearance 覆盖，完整六场景配置见[主题契约](THEMING.md#场景背景050)。
+
+`decoration` 默认 `auto`，仅画布默认跟随主题纹理，AppShell 正文默认纯色。`appearance` 支持局部底色、文字色、纹理与尺寸覆盖，完整变量及优先级见[场景背景配置](THEMING.md#场景背景050)。展台 `#backgrounds` 仅展示当前主题，随右上角选择器同步切换。
+
+```tsx
+import { Background, Surface } from '@linhey/rhine-design';
+import { ThemeProvider } from '@linhey/rhine-design/theme';
+
+<ThemeProvider defaultTheme="neo-brutalism">
+  {/* 用 Background 替换原本 background: var(--rhine-bg) 的正文 div。 */}
+  <Background roleTone="content">
+    <Surface>不透明的内容卡片</Surface>
+  </Background>
+</ThemeProvider>
+```
+
+背景直接绘制在元素上，无伪元素、无点击拦截层、无 transform/contain/position 副作用。纹理从该区域左上角开始，`background-attachment: scroll` 固定在滚动容器的框上：滚动其内部内容时图案不重置、不跟随内容漂移；外层移动整个区域时背景随框移动。各独立区域拥有独立原点，不承诺跨两个元素接缝完全对齐。使用 CSS 默认背景裁剪；内容和焦点在背景上方，裁剪、滚动和 Portal 不受 Background 改变。背景无动画，也无需嵌套 ThemeProvider。
+
+## 三种外壳布局
+
+`AppShell` 接收 `layout="single" | "double-left" | "left-right"`；`navigation` 必填、`secondary` 在后两种布局可选。面板形状为 `{ label, content, open, onOpenChange }`；`header` 放当前任务操作、`children` 为正文，`decoration` 控制正文背景。
+
+| 方案 | 用途 | 顺序 |
+| --- | --- | --- |
+| single | 简单管理或设置工具 | 全局导航 + 正文 |
+| double-left | 目录、列表与编辑任务 | 全局导航 + 上下文目录 + 正文 |
+| left-right | 检查器、对象属性与预览 | 全局导航 + 正文 + 辅助详情 |
+
+全局栏宽 224px，次栏宽 256px，正文伸展，三栏同时展开时至少留约 638px 正文空间。判断依据是外壳容器宽度，适用于嵌入展台或桌面应用：小于 1120px 先将次栏转为 Drawer，小于 760px 再将全局栏转为 Drawer。抽屉初始关闭；桌面 `open` 偏好保留，回到宽窗后恢复。已经打开的 Drawer 在扩宽窗口时保持到用户关闭，避免中断操作；不会自动丢弃正文或选中项。
+
+外壳需要父级提供明确高度（例如 `height: 100dvh`，展台用固定高度）。header 是不滚动的同级区域，body 填满余高；导航、次栏和正文各自 `overflow:auto`。宿主不应再给这些区域内的整页容器设置第二个垂直滚动。表格的局部横向/有限高度滚动是显式例外。没有拖拽宽度、持久化或停靠管理器。
+
+```tsx
+const [navigationOpen, setNavigationOpen] = useState(true);
+const [detailsOpen, setDetailsOpen] = useState(true);
+// currentId、draft 等业务状态放在 AppShell 的上层。
+<div style={{ height: '100dvh' }}>
+  <AppShell layout="left-right"
+    navigation={{ label: '全局导航', open: navigationOpen,
+      onOpenChange: setNavigationOpen, content: <SideNav {...navigationProps} /> }}
+    secondary={{ label: '辅助详情', open: detailsOpen,
+      onOpenChange: setDetailsOpen, content: <ObjectDetails value={object} /> }}
+    header={<Button onClick={save}>保存</Button>}>
+    <Editor value={draft} onChange={setDraft} />
+  </AppShell>
+</div>
+```
+
+SideNav 继续负责当前项、长名称和 aria-current；Drawer 继续负责 Tab、Escape 和触发器焦点归还。正文不因切换布局或主题重建。面板在抽屉与内联之间转换时可能重新挂载，因此选中、展开、输入和请求状态必须提升到宿主；不要在面板 render 时启动不可取消的副作用。主题切换不改变 React key。切换或隐藏面板时将位于其中的焦点送回对应操作按钮。
+
+`ShellPanel.drawerOpen/defaultDrawerOpen/onDrawerOpenChange` 独立控制临时抽屉，桌面 `open` 偏好不受影响；宿主选完导航项后可设置 drawerOpen=false。`width` 和 `breakpoint` 使用 CSS px，默认仍为上述数值；断点按容器布局宽度判断。全局导航与双左次栏从左侧打开，左右布局的辅助栏从右侧打开。AppShell 支持 className/style，Background 支持原生属性及 ref。受控与非受控模式在组件生命周期内保持一致。
+
+## 表单
+
+| 组件 | 主要 API | 数据与键盘契约 |
+| --- | --- | --- |
+| DateField | `label/value/onValueChange/min/max/disabled/error` | 原生 `input type=date`；ISO 日期字符串或空字符串，无 UTC/时区转换，原生日历和键盘由浏览器实现 |
+| DateRangePicker | 上述范围 + `value={start,end}`、`presets=[{label,value}]` | 两个原生日期输入，自定义范围、受控预设、清空；结束日期下界取 start/min 较晚者；反向范围显示错误，不静默调换 |
+| NumberField | `value: number\|null`、`onValueChange/min/max/step/precision/disabled/error` | 编辑中保存字符串；失焦/Enter 提交；无效及越界输入保留并报错；上下键/按钮步进与钳制边界；空字符串提交 null |
+| TreeSelect | `nodes/value/onValueChange/expandedKeys/onExpandedChange/multiple`、loading/error/disabled | 节点为 `{id,label,disabled?,children?}`；父子独立选择，默认单选；调用方提供搜索后的树，不做全量过滤 |
+| RemoteMultiSelect | `query/onQueryChange/value/onValueChange/options`、loading/error/disabled | value 是完整 `{value,label,disabled?}[]`，已选标签不依赖本次结果；不重复选中；清空保留禁选标签 |
+
+日期 min/max 约束原生日历和表单有效性；手动编辑、业务校验及最终提交由宿主验证。原生日期面板位于浏览器 UI，不放在受裁剪的自定义浮层。日历外观、屏幕阅读器和移动 WebView 行为由具体浏览器决定，不声称提供自绘日历。预设必须使用宿主计算好的日期；不得以本机时区代替产品时区。没有“今天”隐式计算。
+
+DateField 新增 `readOnly/required/id/name/hint/onValidationChange`；外部日期或 min/max 改变会更新格式/范围错误，不自动回写值。DateRangePicker 同样支持 readOnly/required/hint/onValidationChange，另有 `clearable`（默认 true）、`startLabel/endLabel/startName/endName`。预设含非法日期、反向区间或任一端越界时禁用。onValidationChange 回传格式/范围/显式 error，required 仍走提交时的原生表单校验。只读时保留浏览与聚焦，预设、清空、步进和选择不能更改值。
+
+NumberField 支持小数步进（默认 1）；precision 限制为 0–15 位，未指定时普通提交保留解析后的 JS 数值，步进清除至 12 位的浮点尾差；IEEE-754 数值精度不适用于高精度货币账本。`-`、`1.` 等草稿在编辑时不改写；外部 value 真正变化时覆盖草稿。未改变值的失焦/Enter 不触发 onValueChange；输入法组词时不提交或步进。
+
+NumberField 另有 `readOnly/required/id/name/hint/controls`（按钮默认显示）；Escape 取消未提交草稿并恢复受控值，第二次 Escape 可交给外层浮层。min/max 变化会直接标明当前越界，不伪造用户输入或自动修改宿主值。空值步进按有效范围处理，不再把空字符串当成已达到零边界。
+
+TreeSelect 使用 tree/treeitem/group，Tab 进入一个可见节点，上下/Home/End 移动，右键展开或进入首个子项，左键收起或返回父项，Space/Enter 选择。禁选节点可导航和展开，但不能勾选。多选用 aria-checked，单选用 aria-selected。节点 ID 全树唯一稳定；过滤后的祖先与展开状态由宿主提供，选择状态不随结果集消失。
+
+首次进入优先已选可见节点；字符前缀定位不改变选择，`*` 展开同层分支，Ctrl/⌘+A 仅切换可见可选节点。外部收起时焦点回可见祖先。节点 `selectable=false` 用于结构分组；readOnly 允许浏览展开而禁止选择。`name` 为选中 key 生成同名 hidden inputs，disabled 不提交。
+
+RemoteMultiSelect 复用 Combobox 的方向键、Enter、Escape 和 IME 防误提交。加载或失败时禁止选择旧候选，已选项仍显示且可移除；默认选中后保持候选列表打开，`closeOnSelect=true` 恢复选完关闭。`clearQueryOnSelect` 默认 false；新增 readOnly/clearable/placeholder/hint/name。空查询 Backspace 删除最后一个可移除标签，标签删除/清空后回输入框；锁定标签保留。name 以同名 hidden inputs 提交受控 keys。单选 Combobox 的默认关闭行为不变。异步取消、序列检查、服务端查询和时区解释全部归宿主。展台有可取消的本地延迟结果演示，但不是生产数据层。
+
+分组底色 `--rhine-field-group-bg`；树缩进 `--rhine-tree-indent`；其余输入、选择、错误和焦点继续用既有语义 tokens，字号不低于 12px。
+
+## DataTable 与 Pagination
+
+所有新参数可选，原表格保持原生 table 语义。此处提供可展开的层级表格，不实现可编辑 ARIA treegrid；键盘使用 Tab 与原生 checkbox/button，不冒充网格方向键导航。
+
+- `selection={keys,onChange,isDisabled?}`：keys 为稳定 rowKey 数组，可包含其他页/查询中的记录。表头只选择/取消当前可见且未禁选的行；保留不可见和禁选键，部分选中为 mixed。加载时禁用选择。
+- `expansion={keys,onChange,getChildren?,renderDetail?,canExpand?}`：子行按宿主顺序展开，层级有文字说明；renderDetail 为独立 region，可与子行共存。keys 由宿主管理，折叠不清空选择；不请求子数据、不更改导出范围。大树的加载与虚拟化由宿主决定，本组件不内置虚拟表格。
+- `rowLabel` 默认 rowKey，建议传业务可读名称，供选择/展开按钮命名。所有层级 rowKey 必须全局唯一稳定。
+- `stickyHeader/maxHeight`：提供明确局部滚动区；列可设 `width/sticky/stickyOffset`。多列固定默认按实测 CSS 布局宽度自动累计 offset，显式 stickyOffset 优先；需为正文至少保留一个可读列，不将多列固定到遮满窄屏。展台固定右侧两个窄列。
+- `density="comfortable" | "compact"`：默认单元格内距为 12/16px 或 6/12px；橙趣 comfortable 为 16/12px，compact 同为 6/12px。业务文字 14px、层级说明 12px，操作仍为 44px。tokens：`--rhine-table-cell-padding`、`--rhine-table-header-bg`、`--rhine-table-hover-bg`、`--rhine-table-selected-bg`；选中底色优先于悬停，固定列使用不透明底色。
+- `Pagination.onPageSizeChange` 和 `pageSizeOptions`：仅回传页大小意图，宿主决定是否回到第一页、是否取消请求。total 已知时推导页数；未知时依赖 hasNext。库不筛选、排序、请求或切割全量 rows。
+
+```tsx
+<DataTable caption="记录" rows={response.rows} columns={columns}
+  rowKey={row => row.id} rowLabel={row => row.name}
+  selection={{ keys: selected, onChange: setSelected, isDisabled: row => !row.canSelect }}
+  expansion={{ keys: expanded, onChange: setExpanded, getChildren: row => row.children ?? [] }}
+  stickyHeader maxHeight={480} loading={loading} error={error} />
+<Pagination page={page} pageSize={pageSize} total={response.total}
+  hasNext={response.hasNext} onPageChange={requestPage} onPageSizeChange={requestPageSize} />
+```
+
+迁移必须保留选择、导出、查询和层级状态。错误与刷新保留已有行，空数据不伪装成错误；已有 sort/onSortChange 不变。
+
+`selection.mode` 默认 multiple，可选 single 使用原生 radio（读取 keys 第一项）；新选择回传单个 key，替换旧单选。`hideSelectAll` 保留单行操作但不显示全选。`DataColumn.rowHeader` 输出 th scope=row；`onSortReset` 提供显式取消排序，宿主清空 sort 后生效。canExpand=false 同时阻止旧展开 key 渲染子行/详情，详情 ID 按行 key 稳定。
+
+Pagination 新增 `disabled/label/showFirstButton/showLastButton`；首末页按钮默认不显示，未知总量时末页不可操作。负数与非有限 total 视作未知；总量缩小导致当前页超界时明确标注，上一页返回已知末页，不自动发请求。翻页到边界时焦点移至相邻可用按钮，页码摘要有状态播报。
+
+## 媒体
+
+`MediaCard` 接收 title、date、kind（photo/video/RAW/Live）、preview、state（ready/loading/error/empty）、aspectRatio（默认 4/3）、onOpen；可选 selected/onSelectedChange/disabled。preview 内的 img/video 使用 contain 保持原比例；媒体类型及失败均有文字。打开按钮与选择 checkbox 为兄弟元素，选择不会触发打开；卡片没有内置网络、轮播、虚拟列表或滚轮监听。preview 应为非交互缩略图，不在打开按钮里嵌套视频控制器。loading 时预览保持隐藏挂载，宿主可在 img.onError/onLoad 后设置 state；缺预览默认 empty，日期为空显示未知。
+
+`MediaViewer` 接收 trigger/title/description/children、受控 open/onOpenChange、onPrevious/onNext、actions、metadata/metadataOpen/onMetadataOpenChange。复用 Radix Dialog 的焦点范围与 Escape，关闭归还实际打开它的卡片/触发器；宿主若卸载或虚拟化掉触发器，应在 onOpenChange 中安排替代焦点。
+
+MediaCard 支持原生 article 属性、ref 与独立 actions（重试等操作不能嵌套在打开按钮里）。MediaViewer 支持 defaultOpen、defaultMetadataOpen 及 className/style；不传 metadataOpen 时，信息栏按钮即可管理内部状态。`previousDisabled/nextDisabled` 显式表达边界，左右键默认触发上/下一项，可用 `keyboardNavigation=false` 关闭；输入框、选择器、媒体播放器和嵌套浮层保留自身按键。导航按钮到达边界变禁用时焦点留在查看器内，可继续反向浏览。
+
+查看器采用同一主题根中的中性媒体 tokens：canvas `#101214`、overlay `#202428`、text `#f6f7f8`、muted `#bcc3ca`、border `#68727c`、focus `#9bceff`。不把战术主题当暗色媒体模式，也不嵌套 Provider。顶部操作可换行，触控目标至少 44px；桌面 metadata 位于右侧，760px 以下移到底部。短窗口内容可滚动，关闭按钮始终在顶部可达。
+
+媒体 children、下载链接和资源版本选择通过 slots 提供；库不持有下载路径、播放状态或路由。actions 中使用原生 button/select/a 可自动使用中性叠加样式。宿主可将 scroll-snap 列表放入画布，并保留原有 Masonic 或其他虚拟列表。仅复用模态的背景滚动管理，没有增加 wheel 事件锁或自定义手势拦截。内部 Dialog/Popover 优先响应 Escape，下一次 Escape 再关闭查看器；媒体自身不播放进场动画，减少动态遵循同一主题根。
+
+## 健康详情与运维图表（issue #6）
+
+`TimelineSegment.detail` 可选，形状为 `{ start, end, reason?, counts?: [{ id, label, value: number|null, unit? }], methodology? }`。开始/结束时间是宿主格式化的含时区字符串；计数 0 与 null 分别呈现为零和未知，NaN/Infinity 也视为未知。统计口径缺失时明确标注未提供，不猜测原因或成功率。旧版只有 label/status 的调用仍兼容。
+
+完整与 compact 健康条均复用同一结构化详情。键盘聚焦和方向键、鼠标定位、触屏按下均打开同一个非模态 Popover；默认优先向上，空间不足自动转向下方，距离视口 12px，内容超过可用高度时内部滚动。Escape 或关闭按钮收起，点击外部也可退出。Popovers 挂到同一主题根，不受侧栏/卡片裁剪。保留当前时段的 aria-valuetext，并用 aria-details 指向已展开详情；焦点不因鼠标悬停被抢走。减少动态无新增例外。
+
+StatusTimeline 通过 `activeId/defaultActiveId/onActiveChange` 按稳定时段 ID 控制选中；未指定或当前 ID 消失时显示最后一个时段。`open/defaultOpen/onOpenChange` 控制详情，`disabled` 禁止操作及显示详情。Enter/Space 将键盘焦点送入详情关闭按钮，退出后返回健康条且不会立即重开。
+
+`TrendChart({ label, unit, rangeLabel, description, points, kind, stale?, error?, loading? })` 提供 `kind="bar" | "line"`，每个 point 是 `{id,label,value:number|null}`。宿主负责时间桶、排序、聚合、单位与统计说明；组件只映射坐标。零是有效采样，未知值不补零、不插值，折线路径在缺失点处断开；图内 ×、SVG 可访问说明和可展开的原始数据表共同表示缺失。单位、范围与图例均为 HTML 文字，避免窄屏 SVG 缩放导致文字小于 12px。多条资源指标使用多个命名图表组合，不内置数据请求或图表引擎。
+
+`StackedBar` 使用相同的 label/unit/rangeLabel/description/反馈字段，接收 `parts=[{id,label,value:number|null,tone?:1|2|3|4}]`。只在每项计数均已知、非负、有限且总和大于零时按传入计数绘制占比；任意未知值会停止归一化并显示“总量未知”，仍列出全部已知/未知计数。全零和负数各有说明。百分比是图例中对这组计数的数学占比，保留一位小数，不是健康分数或成功率。宿主必须提供互斥分类，不能把重叠统计相加当作总量。
+
+两类图表新增 `valueFormatter(value:number|null)`；非有限值以 null 传入。TrendChart 刻度与逐点文字采用格式化，原始数据表保留原数值；StackedBar 格式化图例但不改变比例算法，零分段不占色带空间。TrendChart 可聚焦图形后用左右/Home/End，或悬停/轻触查看同一时段。`activePointId/defaultActivePointId/onActivePointChange` 支持受控高亮与多图联动；null 清除高亮，丢失 ID 不替代为别的样本。高亮值以 HTML 文字播报，缺失桶仍可查看。
+
+图表 `stale` 显示采集陈旧说明，`error` 显示错误并保留旧数据，loading 同样保留旧数据；空数组与全未知区分。图例逐项提供名称与数值，不只靠颜色。`--rhine-chart-series-1/2/3/4`、`--rhine-chart-grid`、`--rhine-chart-missing` 是语义 tokens；前两色跟随主题主色/信号色，后两色供独立分类使用。图形不闪烁、不扫光、不内置告警阈值。相关 API 自 0.5.0 提供，npm 0.4.0 不包含。
+
+```tsx
+<StatusTimeline label="请求历史" segments={segmentsWithDetail}
+  startLabel="10:00 UTC+8" endLabel="11:00 UTC+8" />
+<TrendChart kind="line" label="CPU 使用率" unit="%" rangeLabel={range}
+  description="每分钟采样，缺失保持未知" points={serverPoints}
+  stale={staleMessage} error={requestError} />
+<StackedBar label="互斥结果分类" unit="次" rangeLabel={range}
+  description="按最终结果分类" parts={serverCounts} />
+```
+
+## 真实展台入口
+
+开发服务 `npm run dev` 后访问：
+
+- `/#app-shell`：三种布局、独立背景、Surface、固定顶部操作、Drawer/Dialog、状态与可编辑草稿。
+- `/#advanced-forms`：日期预设/自定义/清空、数字草稿、树单多选、远程延迟/取消/IME，以及加载/失败/空/禁用。
+- `/#advanced-data`：跨页选中键、禁选、层级/详情、密度、已知/未知总数和局部固定列。
+- `/#media`：默认、长标题、加载、错误、缺预览，媒体查看器中的版本/下载与分层 Escape。
+- `/#monitoring`：结构化时段详情与紧凑条、柱形趋势、缺失点折线、已知/未知占比、文本替代及空/陈旧/错误状态。
+
+页首切换三主题及减少动态不重建当前展台；切换章节会卸载演示。自动测试验证受控行为，浏览器与版本验收单独记录于 [验证记录](ISSUE_VALIDATION.md)。精确版本的制品校验和与消费验证按 [发布流程](RELEASING.md)保留。

package/docs/DESIGN_SYSTEM.md

@@ -14,12 +14,18 @@
 - 组件优先：先更新规范、组件与真实展台，再由消费项目选择版本；业务流程不进入通用组件。
 - 动效克制：反馈服务于状态理解，就绪不等待装饰，减少动态不削弱功能。
 
+密集任务浮层的落地规则：先按用户决策划分常显/按需信息；区域标题、数量和操作集中到导航行；短内容自然撑高、默认单层滚动；可见间距与44px操作范围分别验证。详见[场景与交互规范](INTERACTION_PATTERNS.md#弹窗高度与滚动归属)和[间距组合](../components/SPACING.md#视觉间距与操作范围)，选择即保存仅按其适用边界使用。
+
 ## 3. 视觉变量
 
 公开样式接口统一使用 `rhine-`：主题根 `.rhine-theme`、变量 `--rhine-*`、组件类与关键帧 `rhine-*`、减少动态属性 `data-rhine-motion="reduced"`。消费项目的品牌名称只通过内容与组件参数传入，不进入共享命名空间。
 
 ### 3.1 色彩
 
+健康历史使用独立的明亮图形色：`--rhine-health-healthy: #19B88A`、`--rhine-health-recovered: #42B8C8`、`--rhine-health-degraded: #EFA629`、`--rhine-health-failed: #EF6464`、`--rhine-health-unknown: #C5CCD3`。这些颜色只用于健康条和图例，不替换苔绿品牌色或正文/错误文字色；恢复态叠加斜纹，选中时段提供文字与可访问名称。不能把图形色用于小号文字或只凭颜色区分状态。
+
+密集账号列表只常显身份、额度和健康条，日期、粒度、优先级机制等共享说明移至按需入口；未知/不完整/错误仍常显。`StatusTimeline compact`将重复时段说明改为悬停/聚焦浮层，保持44px操作区与键盘浏览，不以健康百分比替代历史证据。
+
 | Token | 值 | 用途 |
 | --- | --- | --- |
 | `--rhine-bg` | `#F2F1E9` | 窗口底色 |
@@ -53,9 +59,11 @@
 
 正常视图不出现小于 12px 的业务信息。英文短标签可使用 0.08em 字距；中文不刻意拉大字距。大写英文只作为少量层级辅助。
 
+行高与字号成对消费token；正文14/22、辅助说明12/18、卡片标题16/24、分区标题18/26。多行自然增高，独立正文段落默认12px间距，不用增大行高代替段间距。按钮14/22，点击高度由padding/min-height负责。完整规则及组件例外见[行高规范](../components/TYPOGRAPHY.md#行高段落与控件)。
+
 ### 3.3 几何与布局
 
-- 间距序列 4/8/12/16/24/32/48px。窗口内容边距 24px；宽度低于 480 时 20px。
+- 间距序列 4/8/12/16/24/32/48px。默认卡片采用24px内边距、8px标题/说明、16px内容/操作；具体用途、组合与响应式规则见[间距规范](../components/SPACING.md)与展台`#spacing`。窗口内容边距24px；既有窄窗20px边距为布局例外，不新增gap token。
 - 展台内容按容器重排；卡片最小宽度按信息密度设定，不能由某个产品窗口宽度推导所有宿主布局。状态区预留文字换行空间。
 - 卡片圆角 4px，按钮 3px；保留原生窗口圆角，不在 WebView 内再画一层假窗口。
 - 控件最小高度 40px，主要操作 44px；移动预览/触屏按至少 44px 目标校验。
@@ -67,7 +75,7 @@
 
 ## 4. 组件与内容契约
 
-使用[40项组件契约](../components/README.md)及[常用组合](../components/COMMON_COMPONENTS.md)。表单标签持续可见，提示与错误关联；交互元素使用原生语义或可访问基础。选择、筛选、排序和分页向宿主回传意图，宿主决定数据来源及操作结果。
+使用[组件契约](../components/README.md)、[常用组合](../components/COMMON_COMPONENTS.md)及[场景与交互选型](./INTERACTION_PATTERNS.md)。0.4.0现有48个组件，npm 0.3.0为40个；接入时核对安装版本的实际导出。表单标签持续可见，提示与错误关联；交互元素使用原生语义或可访问基础。选择、筛选、排序和分页向宿主回传意图，宿主决定数据来源及操作结果。
 
 错误说明发生了什么及可执行的下一步，避免内部堆栈和秘密；成功、警告、未知与空态有文字区分。通知不得依赖颜色或短暂动画才能理解。品牌、实体名、时区和业务单位由宿主定义，具体文案规则见[字体与文字](../components/TYPOGRAPHY.md)。
 
@@ -79,6 +87,8 @@
 
 ## 6. 独立迭代与验收
 
+展台浏览采用左右分栏：桌面目录固定在左侧并可独立滚动，右侧一次展示一个章节；窄屏收为顶部目录按钮。目录使用普通链接与`aria-current="page"`，保留深链接、前进/后退，切换后将焦点移到内容区。展开目录按Escape收起并归还焦点。全局动效偏好保持，章节内演示离开后卸载，避免隐藏动画或浮层继续运行。主题根不加transform、contain或裁剪，浮层继续挂载到主题根。此为`preview/GalleryShell.tsx`展台导航模式，未新增公共组件API。
+
 在本仓运行npm run check，新增组件同步契约和默认/禁用/加载/错误/长文本/键盘/动效示例。展台浏览器验收400/520/880宽度、200%缩放、焦点、快速中断、重播和减少动态；独立消费构建验证CSS及SVG资源。
 
 变化记录在CHANGELOG并按语义版本提供迁移说明。消费项目显式选择版本，不随主线自动升级。库验收不依赖某个App迁移完成；真实业务、原生平台与辅助技术由宿主按适用范围补验。剩余能力见[系统对照](DESIGN_SYSTEM_AUDIT.md)。

package/docs/DESIGN_SYSTEM_AUDIT.md

@@ -1,6 +1,8 @@
 # 莱茵设计 · 主流系统对照与补齐顺序
 
-调研日期：2026-10-22。对照[莱茵设计](../README.md)的`components/`与通用表单、数据展示、反馈和导航场景。以下优先级是本项目判断；引用用于说明参考系统的原则，不代表它们要求采用我们的尺寸、配色或组件清单。独立展台使用18309的`/#…`入口。
+本页保留早期组件基线与补齐顺序。2026-10-24 对 issues #1–#6 的 11 个新增组件及 3 个扩展另有[Ant Design / MUI 逐项审计](ANTD_MUI_AUDIT.md)，包含本轮修复、验证和有意差异；当前候选 API 见[应用组件契约](APPLICATION_COMPONENTS.md)。
+
+初次调研：2026-10-22；2026-10-23追加[GitHub项目与skills调研](./REFERENCE_RESEARCH.md)，main新增六个组件、14类场景指南和两组动效。对照[莱茵设计](../README.md)的`components/`与通用表单、数据展示、反馈和导航场景。以下优先级是本项目判断；引用用于说明参考系统的原则，不代表它们要求采用我们的尺寸、配色或组件清单。独立展台使用18309的`/#…`入口。
 
 ## 参考与取舍
 
@@ -29,7 +31,7 @@ V1.3新增Text/Select/Toolbar、9档文字样式和[字体/文案规范](../comp
 | P0 | 统一状态矩阵 | 默认/悬停/按下/焦点/禁用/选中/只读/加载/错误，按适用范围验收；信息不可只靠颜色 | 规则已补；完整逐组件辅助技术审计待做 |
 | P1 | 数据展示组合 | Metric、KeyValue、DataTable、Pagination；未知/零、刷新加载/失败、窄窗局部滚动；请求明细业务组合由页面负责 | V1.4已实现，待业务接入 |
 | P1 | 链接、功能图标、图标按钮 | 16/20px统一图标网格、明确名称、44px操作目标、禁用与focus；链接跳转和按钮动作区分 | V1.4已实现Link/Icon/IconButton/CopyButton |
-| P1 | 表单Field公共结构 | 输入/Select统一label/hint/error，必填和只读；多字段失败时焦点与错误汇总 | 现有TextField/Select满足单字段；多字段流程出现后提取 |
+| P1 | 表单Field公共结构 | 输入/Select统一label/hint/error，必填和只读；多字段失败时焦点与错误汇总 | 0.4.0已提供Fieldset与ErrorSummary及失败提交焦点示例 |
 | P1 | 完整主题语义 | 表面、文字、边界、选中、焦点、错误与图表在深色下成对校验 | 未实现完整深色模式；不能只反转颜色 |
 | P1 | 焦点与原生平台验收 | WebView、VoiceOver/Narrator、纯键盘、纯文本缩放、系统高对比与字体差异 | 浏览器证据不能替代原生验证 |
 | P2 | Dialog/ConfirmDialog/Popover/Tooltip/Menu | Escape、焦点进入/归还、遮罩、滚动、层级和减少动态一起处理 | V1.4采用Radix无样式基础并提供真实展台 |
@@ -37,7 +39,7 @@ V1.3新增Text/Select/Toolbar、9档文字样式和[字体/文案规范](../comp
 | P2 | 搜索、Checkbox/Radio/Switch、Textarea、Combobox | 原生表单习惯、受控值、IME保护；Switch不混同选择账号 | V1.4已实现；查询与过期响应仍由业务层处理 |
 | P2 | Divider/Stack/Inline/Grid | 同源间距、自适应网格、换行与缩放 | V1.4已用于展台布局 |
 
-常用组件补齐后，下一步按用户授权先改页面设计稿，再将同一组件接入正式App。剩余明确缺口是完整深色主题、多字段错误汇总及原生辅助技术验收；不因Logo支持深色而标记整套主题完成。40个组件存在不等于正式业务页已迁移。
+常用组件补齐后，下一步按用户授权先改页面设计稿，再将同一组件接入正式App。剩余明确缺口是完整深色主题及原生辅助技术验收；不因Logo支持深色而标记整套主题完成。40个组件存在不等于正式业务页已迁移。
 
 ## 状态与交互补充规范
 
@@ -58,6 +60,6 @@ V1.3新增Text/Select/Toolbar、9档文字样式和[字体/文案规范](../comp
 
 ## 消融与范围
 
-- 不增加侧栏、面包屑、命令面板、日期选择器、拖拽、富文本编辑器：现有两个主功能无对应任务入口。
+- 独立通用库现已提供SideNav、Breadcrumbs、Steps、Drawer、Fieldset、ErrorSummary，不再沿用原产品仅有两个页面的限制。命令面板、日期选择器、拖拽、富文本与图表引擎仍需具体交互需求后再补。
 - 不引入动画框架、主题生成器或整体UI库。V1.4用户已授权完整浮层能力，采用Radix的5个无样式primitive包处理焦点/键盘/边缘避让；视觉和动效仍使用Rhine Design CSS。
 - 不把每种视觉模式封装成组件：先出现稳定复用，再抽取；业务数据契约与服务端状态继续保留在调用方。

package/docs/INTERACTION_PATTERNS.md

@@ -0,0 +1,129 @@
+# 场景、组件与交互选型
+
+本规范面向通用工具、管理界面和数据应用。先确定用户任务、信息是否需要持续可见、是否允许中断，再选组件。视觉沿用莱茵设计；行为参考成熟模式。`preview/PatternGallery.tsx` 提供可操作的选型示例。
+
+**版本边界：**本页新增的 SideNav、Breadcrumbs、Steps、Drawer、Fieldset、ErrorSummary、StatusTimeline、TimelineLegend 及 Dialog.sidePanel 自 0.4.0 提供。npm 0.3.0 不包含它们；接入前核对安装版本及 `components/index.ts`。
+
+## 选择与关联证据并排
+
+在提交前需要比较资源、额度或健康记录时，使用 `Dialog sidePanel={预览}`：children放左侧选择与提交，sidePanel放右侧只读证据；description保留任务影响说明。最大宽960px，左/右约40/60，24px内边距与分栏间距；720px及以下上下排列，模态整体可滚动。避免将选择、长列表、图例与提交挤在同一窄列。右侧有导航区时，使用`sidePanel={closeButton => ...}`将唯一关闭按钮与右侧标题、说明入口放在同一行；导航与左侧标题顶端对齐，下面直接展示内容，不再预留关闭按钮空行。渲染函数必须展示传入的closeButton，保留Escape与焦点归还；纯内容sidePanel保持原布局。左右仍是一个模态、同一个焦点范围；默认选择不提交，即时保存模式须按下方规范明确说明。主任务先于预览的DOM顺序保留键盘阅读关系，使用默认160ms浮层动画，减少动态立即呈现。
+
+## 弹窗高度与滚动归属
+
+短任务和有界分页预览默认随内容增高，不为了固定外观给内部列表设置独立高度上限。少量溢出先让弹窗长高；现有Dialog仅在超过`100dvh - 32px`时整体滚动。保留服务端分页，不以取消内层滚动为由一次加载全部记录。
+
+- 默认只有弹窗这一层滚动。短列表不声明“可滚动”，不为不可滚动容器增加Tab停靠点。
+- 只有需要持续比较两个独立长内容区域、固定编辑器工作区等明确场景，才采用分区滚动；需有可识别的滚动边界、可达的关闭/操作入口，并单独验证键盘和窄屏。
+- 最后一项的提示、焦点环与分页也计入所需空间。不能只让静态内容刚好装下，却裁切悬停或键盘详情。
+- 高度由CSS与内容决定，不为内容变化添加整页高度动画。具体产品的每页条数、列表高度不固化为通用token。
+
+## 信息密度与渐进展示
+
+先确定用户在这里做什么决定，再决定常显内容；消融的是重复解释，不是决策依据或异常状态。
+
+| 信息 | 默认位置 | 保留边界 |
+| --- | --- | --- |
+| 对象身份、核心指标、决定是否可操作的状态 | 每条记录常显 | 单位与统计周期明确；未知不能变成0 |
+| 标题/数量、共享说明入口、关闭 | 区域顶部同一导航行 | 单一关闭入口；加载、空、错误状态仍可退出 |
+| 重复的时间范围、粒度、排序机制、图例 | 共用说明Popover | 不藏起改变用户决策的影响或风险 |
+| 某时段的时间与状态 | 悬停、键盘聚焦时显示 | 同时提供可访问名称；触屏也能聚焦/操作 |
+| 失败、未知、数据不完整、关键陈旧状态 | 相关区域常显 | 不用减少文字来掩盖数据质量问题 |
+
+## 历史健康记录
+
+`StatusTimeline({label,segments,startLabel,endLabel})` 接收按时间排序的 `{id,label,status}`；status仅限 healthy/recovered/degraded/failed/unknown。宿主负责证据分类、时区、缺失时段补unknown和陈旧说明；组件不计算评分、不查询后端。`TimelineLegend()`提供五种状态的文字和色块，恢复态另加纹理。两者从公共barrel导入并使用同一主题。
+
+时间轴44px操作区，鼠标定位时段，键盘方向键及Home/End浏览；当前时间与状态同时提供文字和aria-valuetext，不能只用红绿表达。默认模式显示时间范围及详情；`compact`用于重复列表行，仅在悬停/聚焦时显示详情，日期范围仍供辅助技术读取。明亮健康色采用独立health tokens，恢复态斜纹，不扩散到正文颜色。空数组禁用滑块；宿主必须常显无数据原因。没有数据、采集不全或只有未确认输出时不得标为健康；历史有输出也不代表当前可用保证。时段颜色与数值原位更新，不做进度扫光、闪烁或数字滚动。展台“场景与交互 → 监控数据与告警”提供默认及紧凑双栏示例。
+
+## 选择即保存的适用边界
+
+适用于独立单项设置，且用户在选择前能够理解改变的对象与影响；不默认推广到多字段编辑、批量修改或不可逆操作。需要比较未提交方案时仍采用显式提交。
+
+仅当宿主明确采用“选择即保存”，在选择前说明语义；初始回显/打开不提交，用户选择后锁定控件并显示保存中，服务端确认后显示已保存；有版本校验的接口使用返回的新revision继续操作。失败/未知结果不可显示成功或自动重试。此模式去掉重复提交按钮；说明信息按需查看，但影响范围不能消融。保存成功后可保持上下文继续查看关联证据；关闭只退出视图，不暗示撤销已保存内容。
+
+## 侧栏导航
+
+SideNav采用44px最小操作行、14/22文字、4px行间距，组间16px；图标可选，使用20px线性Icon且不替代文字。当前页用苔绿底、左侧2px细边界和aria-current表达，不使用容易误解为外链的箭头。少量并列页面优先一个分组；长名称自然换行、不截断、保持图标宽度。悬停仅120ms背景过渡，键盘焦点即时，减少动态沿用全局规则。
+
+## 快速决策
+
+| 场景 | 组件组合 | 交互与状态 | 不宜使用 |
+| --- | --- | --- | --- |
+| 跨工作区、跨模块 | SideNav + Breadcrumbs | 当前页有文字、边界与 aria-current；路由变化后由宿主聚焦主内容 | Tabs 不代替全局导航；面包屑不显示浏览历史 |
+| 同一对象的内容页签 | Tabs | 方向键选项、隐藏面板退出可访问树；焦点留在选项 | 不用一串按钮伪装页签 |
+| 单视图指标或显示模式 | SegmentedControl | 原生单选，状态即时更新 | 不用于独立页面或执行命令 |
+| 多字段配置 | Fieldset + TextField/Select + ErrorSummary | 提交后校验，摘要聚焦，链接回字段，保留已填值 | 不只弹 Toast；不在每次输入时抢焦点 |
+| 线性配置流程 | Steps + Fieldset | 业务验证后推进，已完成步骤可返回；保留跨步数据 | 不自动走步骤，不拿步骤数估计后台进度 |
+| 列表记录临时详情 | Drawer + KeyValue | 模态详情保留底层列表；进入限制焦点，Escape 关闭并归还 | 长编辑、需要分享链接的详情用独立页 |
+| 短时独立任务 | Dialog | 一个明确任务，标题、说明、关闭路径齐全 | 不叠加多层任务弹窗 |
+| 不可逆操作 | ConfirmDialog | 具体对象、影响、取消与明确动作；等真实结果，失败保留上下文 | 常规保存无需二次确认；可撤销优先撤销 |
+| 简短成功反馈 | Toast | 不抢焦点；自动消失前允许 hover/focus 暂停 | 不能作为关键错误唯一载体 |
+| 持续错误、离线或权限状态 | Notice | 就地说明原因、影响、下一步；需行动的信息持续显示 | 不用自动消失通知掩盖失败 |
+| 首次加载 | Skeleton / Progress | 已知结构用骨架，未知进度不写百分比 | 不伪造进度，不循环品牌标志 |
+| 保存、刷新 | Button busy + 保留旧数据 | 防重复提交；刷新明确旧值和更新时间；真实响应决定成败 | 不清空阅读上下文，不提前显示成功 |
+| 大列表查询 | SearchField / Combobox + DataTable + Pagination | 宿主处理防抖、IME、取消与过期响应；服务端返回筛选排序分页 | 不为 UI 便利拉取全量本地筛选 |
+| 少量/较多互斥选项 | RadioGroup / Select | Radio 展开选项便于比较，Select 压缩较长清单 | Menu 是命令，不能代替选择器 |
+| 多选 / 即时二态设置 | Checkbox / Switch | Checkbox 选择项；Switch 即时偏好，若需保存明确说明 | 不混同“选中”与“已生效” |
+| 补充说明 / 局部交互 | Tooltip / Popover | Tooltip 不放操作；Popover 可交互；鼠标、键盘均可触发 | 必要说明必须常驻，不能只在 hover 下出现 |
+| 次级命令 | Menu | 动词命名、危险动作区分；键盘导航，Escape 返回入口 | 不把长表单放入菜单 |
+| 尚无数据 / 筛选无结果 | EmptyState | 分别给创建或清除筛选；读失败用 Notice | 不能把错误、无权限当作空列表 |
+| 监控与告警 | Metric + Badge + DataTable + Notice | 数值、单位、时间范围、最后更新时间齐全；陈旧数据标记；告警有文字和处理路径 | 未知不能填 0；红绿不能是唯一编码；告警不闪烁 |
+| 启动与品牌识别 | Logo / 启动编排 | 三角、细线、分块归位；仅启动或主动重播；就绪立即进入 | 日常数据变化不反复播放品牌动画 |
+
+## 新组件契约
+
+| 导出 | 输入与责任 | 键盘、焦点、边界 |
+| --- | --- | --- |
+| SideNav | `groups[{label,items[{id,label,href,icon?}]}]`、`currentId`、`onNavigate(item,event)`；icon为IconName，支持 nav 原生属性 | 原生链接可 Tab、打开新页；宿主接管路由时自行决定是否 preventDefault，保留修饰键语义；不自动滚动、鉴权或请求 |
+| Breadcrumbs | `items[{label,href?}]`、`label`；最后一项是当前位置 | 带名称的 nav/ol；最后项 aria-current=page；只传真实父子层级，无 href 项为文本 |
+| Steps | `items[{id,label,description?}]`、`current`、`error?`、`onStepChange?` | current 为从 0 开始的位置，等于项数代表完成；只允许点击已完成步骤；当前项 aria-current=step；错误有文字，不自动推进 |
+| Drawer | 与 Dialog 相同：`trigger,title,description,children,open?,onOpenChange?` | 右侧模态面板；Radix 管理焦点限制、Escape 和归还；最近主题根继承动效偏好；可编辑内容需宿主保留草稿并在受控 onOpenChange 中处理未保存规则 |
+| Fieldset | `legend,hint?,children` + 原生 fieldset 属性 | 原生 legend 分组、提示关联；disabled 禁用组内表单控件；不替代单字段标签 |
+| ErrorSummary | `errors[{fieldId,message}]`、`title?`、`focusKey?` | 非空且 focusKey 变化时聚焦摘要；每次失败提交递增；链接聚焦已有字段并滚动到可见位置，不修改 hash 路由；fieldId 必须指向唯一、可聚焦字段；无错误不渲染 |
+
+```tsx
+// 提交时验证；不要在每次键入时递增 attempt。
+const [errors, setErrors] = useState<FieldError[]>([]);
+const [attempt, setAttempt] = useState(0);
+function submit(event: FormEvent) {
+  event.preventDefault();
+  const next = name.trim() ? [] : [{ fieldId: 'name', message: '请输入名称' }];
+  setErrors(next);
+  setAttempt(value => value + 1);
+  if (!next.length) { /* 宿主执行真实提交并处理 pending / success / failure */ }
+}
+// 在 form 内：
+<ErrorSummary errors={errors} focusKey={attempt} />
+<Fieldset legend="基本信息">
+  <TextField id="name" label="名称" required value={name}
+    onChange={event => setName(event.target.value)} error={errors[0]?.message} />
+</Fieldset>
+```
+
+示例是组合片段；React hooks/types、组件导入、state 及 form 由宿主提供。异步校验必须忽略过期结果；摘要不负责业务验证。
+
+## 动效按意图选择
+
+| 意图 | 参数与效果 | 触发/结束 | 减少动态 |
+| --- | --- | --- | --- |
+| 指明可操作、选中 | 120ms 颜色/边界，按下 80ms | hover/press/选择；语义立即更新 | 即时颜色变化 |
+| 呈现新内容、步骤 | 180ms opacity + 最多 3px | 新面板或当前步骤出现；单次 | 直接显示最终态 |
+| 临时浮层、抽屉 | 160ms opacity，抽屉从右侧 3px | 打开；关闭立即解除遮挡并归还焦点 | 保留同样焦点规则，无位移 |
+| 表单错误 | 即时文字、边界、摘要焦点 | 失败提交；纠正后重新验证 | 行为一致，无抖动 |
+| 刷新数值、告警 | 原位替换，文字说明时间/严重性 | 真实数据更新 | 行为一致，无数字翻转 |
+| 加载占位 | 已有 Skeleton/Progress 配方 | 请求结束或卸载终止 | 静态占位仍显示加载文字 |
+
+共享 CSS token 是参数来源。仅声明必要属性，不使用 transition:all；优先 transform/opacity，不做整页高度动画、循环滤镜或滚动监听驱动的装饰。DOM 测量先读后写；能使用 CSS 的交互不另引动画运行时。
+
+`/#motion` 有 12 组播放/重播/复位、4 倍慢放、逐例/全局减少动态示例。新增 Drawer 的弹层内重播只重启动画，不重新挂载、不清空输入或移动焦点；Steps 只模拟一次本步完成。错误反馈不加入“错误动画”，直接在 `/#form-workflow` 验证聚焦与纠错。
+
+## 验收清单
+
+1. 明确默认、加载、空、错误、成功、禁用、长文本各状态；不能仅凭颜色理解。
+2. 键盘顺序符合阅读顺序；可见焦点；浮层 Escape 与焦点归还；错误定位不改变页面路由。
+3. 400/520/880 宽度与 200% 等效重排无关键内容丢失；窄屏模态可滚动且关闭入口可达。
+4. 系统/手动减少动态都保留信息；重复播放不会重执行业务动作或留下计时器。
+5. 当前浏览器验证不代表原生 WebView、VoiceOver/Narrator 或完整 WCAG 审计通过。
+6. 分别检查内容刚好装下、仅溢出少量、明显超出窗口三种高度；确认滚动归属，末条详情不裁切、不遮挡分页。间距同时测可见边界和命中区，不只读gap配置。
+
+参考来源与取舍见 [GitHub 调研](./REFERENCE_RESEARCH.md)。

package/docs/ISSUE_4_VALIDATION.md

@@ -0,0 +1,21 @@
+# Issue #4 主线整合验证
+
+2026-10-23。此记录对应 #4 专项源码整合，不表示 npm 已发布。包版本保持 0.4.0，新增 API 等待下次 npm 发布窗口。
+
+## 范围
+
+从候选提交 `2e08ebb` 提取 Background、AppShell（组合展台依赖）、背景语义 tokens、三主题表面样式、两组真实 React 展台及相关契约。没有纳入复杂表单、受控数据表、媒体查看器和监控图表。原候选分支保留，后续整合需保留本次背景能力并处理共享文件差异。
+
+## 本轮验证
+
+- Node 24 下 `npm ci` 与 `npm run check` 通过：55 项测试、TypeScript、Vite 生产构建、CSS/SVG 产物检查。
+- Chromium 使用本次生产构建：三主题 × 场景背景/应用外壳两个展台 × 400/520/880/1600px，共 24 组，无页面、主工作区或外壳横向溢出。
+- 三主题 × 两个展台，在 1040px 视口 CSS `zoom:2` 下无页面横向溢出，共 6 组。此证据不等同于浏览器菜单 200% 缩放，后者留待发布验收。
+- 三主题的正文纹理开关、纯色降级、内部滚动后图案不重置及顶部操作位置不变通过；纸面无纹理，战术网格与橙趣点阵可独立绘制。
+- Dialog 实际可输入，Escape 关闭后焦点回到触发按钮；正文草稿保留，全页唯一主题根。
+- 系统减少动态偏好下背景无动画；浏览器运行时错误为零。
+- 实际截图：[橙趣正文与侧栏](assets/issue4-shell.png)。
+
+## 后续
+
+等下次 npm 窗口完成最终版本号、干净提交制品、registry 回读及仓库外固定版本安装验证，再更新并关闭 #4。当前仅交付 main 源码与展台，不能按 npm 0.4.0 消费新增 Background/AppShell。

package/docs/ISSUE_VALIDATION.md

@@ -0,0 +1,52 @@
+# Issues #1–#6 验证记录
+
+2026-10-24 更新，0.5.0 源码与发布前验证。下方保留历史候选证据及其精确提交；正式版本、制品身份与 registry 回读见 [v0.5.0 发布记录](https://github.com/linhay/rhine-design/releases/tag/v0.5.0)。组件库发布不代表消费应用已迁移。
+
+## 0.5.0 发布复核（2026-10-24）
+
+- 完成 PR #7 全部有效审阅：数字重复提交与未指定精度的数据损失、加载媒体挂载、空图表提示、slider ARIA、表格主题/密度/悬停及 CSS-only 根派生变量。AppShell 移除辅助栏焦点已有修复，本轮补充清除面板与外部焦点保护回归。
+- Node 24 `npm run check`：**126 项测试、15 个文件通过**；类型、生产构建及 CSS/SVG 检查通过。本轮发布审阅新增 7 项测试。最终 JS/CSS 为 `index-ZdseTmxg.js` / `index-DenpVIW5.css`。
+- Chrome 155 原生“网页缩放”设为 **200%**，设置控件显示选中200%；相同窗口下 innerWidth 从1040变为520，devicePixelRatio从1变为2，HTML/body CSS zoom仍为1。最终产物三主题×六展台×有效400/520px共 **36组布局**、**15组跨组件交互+12组背景/外壳交互**全部通过，意外横向溢出0、运行时错误0。验后恢复100%。这补齐 issue #4 预留的浏览器实际缩放验收。
+- 浏览器补验媒体隐藏节点发起请求并在 onLoad 后显示原节点、长小数/极小数保留且不重复提交；CSS 修前41个断言失败，修后三主题×两密度、主题根 palette 继承/显式场景覆盖与不透明固定单元格底色全部通过。
+- 证据保存在忽略目录 `output/playwright/release-browser-zoom-*`、`release-css-review*`。原生缩放下 Playwright 截图裁剪异常，验收依据设置文本、DPR/尺寸、DOM几何及实际交互，不以截图外观替代行为证据。系统日历、读屏软件、移动WebView和真实媒体解码仍属宿主验收边界。
+
+## Ant Design / MUI 对标补齐（2026-10-24）
+
+- [逐项清单](ANTD_MUI_AUDIT.md)覆盖 11 个新增组件与 DataTable/Pagination/StatusTimeline 的扩展，每组记录官方链接、修复项及保留差异。没有安装或复制上游库。
+- Node 24 `npm run check`：**119 项测试、15 个文件全部通过**，包含本轮新增 45 项回归及合入主线保留的 2 项背景专项测试。TypeScript、生产构建及 CSS/SVG 产物检查通过。旧 Shell 测试宽度 mock 同步为 clientWidth，以覆盖真实的 CSS 布局宽度契约。
+- 已合入主线 `0d19c8e` 的背景子集，保留其专项记录与截图并消除 PR 冲突；组件和展台代码与已验候选一致。合并后重新构建的 JS/CSS 文件名仍为 `index-93MfkO6O.js` / `index-BZ6ALQ8I.css`，浏览器及消费包证据仍对应相同运行实现。
+- 生产构建 18319：三主题 × 六展台 × 390/400/520/880/1600 共 **90 组宽度**，document/main/shell 无意外横向溢出、运行时错误 0；三主题 × 六展台共 **18 组 CSS 200% 缩放**，并验证 520px 重排和减少动态。局部表格横向滚动属于预期。
+- 三主题 400px 的生产实际交互：日期只读和无效预设、数字 Escape 撤销、远程多选连续选两项/空查询 Backspace/标签焦点；数据表单选、取消排序焦点、双固定列相邻、末页禁用后的焦点、未知总量末页禁用；左侧导航抽屉选项后受控关闭；卡片重试与打开分离、媒体到末项后可反向键盘浏览、嵌套弹窗不串方向键、Escape 回到实际卡片；双图键盘联动、零/未知时段、健康详情 Enter 进入/Escape 退出。15 组组合流程全部通过，运行时错误 0。
+- 分项开发浏览器另验证：树字符与批选、FormData/只读；多固定列 3 主题 × 3 宽度及 3 次 CSS zoom；左右抽屉边缘、CSS transform 不改变 Shell 断点。详细证据见各审计文档。
+- 独立复审发现 StackedBar 原始小数作为 flex-grow 时总和小于 1 会留下多余空白，已改为归一化权重并补回归；图例和原始计数不变。
+- 从干净提交 `d3685ab` 导出并打包，在仓库外 React 19/Vite 8 消费项目安装实际 tarball；全部 11 个新组件、扩展 API 和新导出的 Props 类型通过严格 TypeScript 检查（Vite client 类型）与生产构建。浏览器验证图表键盘、非受控媒体信息栏和单一主题根；小数权重 0.1/0.2 在 300px 色带内两段实测 98.66/197.34px，加 2px 间距正好填满 298px 内宽，比例与图例一致。消费壳需使用 Stack 留出 compact 时间轴的 44px 命中范围，不能把独立控件无间距堆叠。临时消费项目仅有 favicon 404，无组件运行时错误。
+  测试包仍为本地 0.4.0 标识，未上传 registry；SHA-256：`d051b84e5544b697e436620c9f0c64f7f4875ed08ed956235c03cfdce86dd798`。包清单 116 个文件，不含工作区私有目录与浏览器产物。
+- 本轮浏览器脚本与截图在忽略目录 `output/playwright/parity-*`。只读屏幕像素不能证明键盘/原生辅助技术；没有宣称操作系统日历、移动 WebView、实际屏幕阅读器或浏览器菜单缩放验收。
+
+## 初次候选验证（2026-10-23）
+
+- Node 24 下 `npm run check`：72 个测试通过（原有 53 个 + 新增 19 个）；TypeScript、Vite 生产构建与 CSS/SVG 产物检查通过。
+- 新增测试覆盖：日期范围限制/预设/清空、数字中间态/精度/越界/空值/IME、远程查询与跨结果选中、树键盘与禁选/父子独立、表格跨页选择/禁选/展开/独立详情、分页意图、背景单一主题根、布局切换保留草稿、媒体选择分离、分层 Escape 与焦点归还。
+- Chromium 生产构建入口（本地 `vite preview`）：三主题 × 五展台（场景背景、多侧栏、复杂表单、数据表、媒体）× 390/400/520/880/1600px 共 75 组。document、主工作区和外壳均无意外横向溢出，页面运行时错误为零。表格允许局部横向滚动。
+- 三主题分别验证：侧栏折叠与布局切换保留正文、背景纹理开关、窄窗 Drawer 与 Dialog、选择保留跨页键且跳过禁选、失败保留旧行、媒体版本选择、媒体查看器各宽度、嵌套弹窗实际可点击、Escape 逐层退出、焦点返回原卡片。
+- 400px 三主题真实键盘：数字中间态/错误/提交/步进，日期自定义与清空，远程候选方向键选择及标签保留，树父子独立勾选，加载禁止选择旧候选、禁用输入，候选浮层不超出视口。
+- 三主题 × 五展台共 15 组：1040px 视口下 CSS `zoom:2` 无横向溢出，主要输入/关闭操作可达；另验 520px 有效宽度的媒体查询重排和系统减少动态。此为缩放与重排证据，不冒充浏览器菜单 200% 或原生 WebView 结果。
+- `git diff --check` 通过。包清单检查确认包含新增源码/CSS/文档，未包含工作区私有目录或浏览器产物。
+- 从干净提交 `7bf45ef` 导出源码并 `npm pack`，在仓库外的 React 19/Vite 8 项目安装该 tarball；9 个新增组件及 DataTable/Pagination、主题子入口、CSS、Logo SVG 的生产构建通过。测试包仍标记 0.4.0，仅为本地制品，未上传 registry。tarball SHA-256：`2658d2b8ef5da85b922380b4ecbf8afa0e9d2f95bbaedec5284373aa840a9499`。
+  消费产物的真实浏览器中媒体查看器可打开/关闭，数字输入、唯一主题根和点阵正常；Logo SVG 返回 200。临时消费壳仅有未配置 favicon 的 404，没有组件运行时错误。
+
+真实浏览器验收等待 Radix 完成挂载、可点击性和异步焦点归还后判断；仅等待 `dialog` 可见并立即检查 `pointer-events` 会读到过渡状态。JSDOM 不验证叠层和裁剪，不能替代这部分浏览器证据。
+
+补充 issue #6：三主题 × 390/400/520/880/1600px 共 15 组监控展台，以及三主题 CSS 200% 缩放通过（累计 90 组宽度、18 组缩放）。验证了健康详情在顶部空间不足时转向下方、完整计数/口径、未知计数、键盘 Home/方向键/Escape/焦点归还；图表缺失断线、空/陈旧/失败/未知总量和原始数据表均通过。
+
+包含 #6 与审阅修正的干净提交 `2e08ebb` 再次打包，在同一仓库外消费项目安装全部 11 个新增组件及结构化时间轴并通过生产构建。浏览器验证详情中未知计数、Escape、折线两段路径和总量未知不计算占比。最终测试 tarball SHA-256：`12f6b5052b9569b9d8e1bd83a4c273e51b7636c99aab5953ae02d12af490da75`，仍未上传 registry。
+
+审阅回归修正：全局禁用树不展开、移除/窄化侧栏后恢复焦点、数值 0 详情仍生成合法表格行、媒体卡片显式聚焦并播报加载/失败状态、Markdown 表格中的类型分隔符正确转义。侧栏窗口从 1600px 缩至 880px 的真实浏览器焦点归还另验通过。
+
+## 交付边界
+
+- 日期输入复用浏览器原生日历；操作系统日历 UI、读屏软件、移动 WebView、触屏实机和完整视频解码/播放尚未验收。没有增加自绘日期日历或媒体播放引擎。
+- 表格使用原生 table 加层级展开按钮，未实现可编辑 ARIA treegrid。大数据虚拟化、导出和服务端请求需要宿主保留。
+- 本地截图在被 Git 忽略的 `output/playwright/`：`shell-desktop.png`、`media-400.png`、`forms-400.png`。页面可从 `npm run dev` 的 `#app-shell`、`#advanced-forms`、`#advanced-data`、`#media`、`#backgrounds` 复查。
+- 可审阅截图：[桌面多栏](assets/application-shell.png)、[400px 媒体查看器](assets/media-viewer-mobile.png)。截图只作布局参考，交互证据来自上述真实 React 展台和浏览器检查。
+- issues 的发布验收按 [RELEASING](RELEASING.md) 从干净提交打包、固定版本安装并回读 registry，不能将候选源码等同于 npm 能力；实际结果以对应版本发布记录为准。

package/docs/REFERENCE_RESEARCH.md

@@ -0,0 +1,38 @@
+# GitHub 与主流设计系统调研
+
+此页保留 2026-10-23 的初次调研记录。后续 issues #1–#6 已新增应用组件，并于 2026-10-24 完成 [Ant Design / MUI 逐项 API 与交互对照](ANTD_MUI_AUDIT.md)；当前能力和明确保留差异以该清单及应用组件契约为准。
+
+查询日期：2026-10-23（本地日期）。星标来自当次 GitHub API，是关注度快照，不是质量或安全认证。许可证状态也需在实际复制代码时重新核对。
+
+| 项目 / skill | 星标 | 许可 | 本轮采用的原则 |
+| --- | ---: | --- | --- |
+| [shadcn/ui](https://github.com/shadcn-ui/ui) | 126,213 | MIT | 按任务组织导航、表单、Sheet 等常用能力；用自己的组件 API 与莱茵样式实现，不整套安装皮肤 |
+| [Impeccable](https://github.com/pbakaus/impeccable) | 84,840 | Apache-2.0 | 区分操作界面与阅读界面，保留现有设计语言；在真实尺寸检查结果 |
+| [Vercel agent-skills](https://github.com/vercel-labs/agent-skills) | 32,820 | API 未返回许可 | web-design-guidelines 的面向实际源码审阅方法；未复制源码或安装其执行入口 |
+| [Radix Primitives](https://github.com/radix-ui/primitives) | 19,415 | MIT | Drawer 复用库内已经依赖的 Dialog primitive，统一焦点、Escape、Portal |
+| [React Spectrum / React Aria](https://github.com/adobe/react-spectrum) | 15,975 | Apache-2.0 | 语义、标签、输入方式与焦点作为组件契约；没有引入第二套交互基础库 |
+| [UI Skills](https://github.com/ibelick/ui-skills) | 10,020 | MIT | fixing-accessibility 与 fixing-motion-performance：原生语义、可访问名称、焦点归还、合成属性优先、停止无期限动画 |
+| [Carbon](https://github.com/carbon-design-system/carbon) | 9,572 | Apache-2.0 | 区分组件和任务模式；步骤指示、通知与复杂表单的使用场景 |
+
+已读 skill 文件：[Vercel web-design-guidelines](https://github.com/vercel-labs/agent-skills/blob/main/skills/web-design-guidelines/SKILL.md)、[Impeccable](https://github.com/pbakaus/impeccable/blob/main/.agents/skills/impeccable/SKILL.md)、[UI Skills motion](https://github.com/ibelick/ui-skills/blob/main/skills/fixing-motion-performance/SKILL.md)、[UI Skills accessibility](https://github.com/ibelick/ui-skills/blob/main/skills/fixing-accessibility/SKILL.md)。
+
+本轮把外部 skill 作为调研材料，未运行其中的安装脚本、下载二进制或改变 agent 权限。只将适用规则写入本项目的场景规范与现有 rhine-design skill；没有复制第三方实现代码，也未增加运行时依赖。
+
+## 组件行为的官方依据
+
+- [WAI-ARIA Breadcrumb Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/)：有名称的导航区与当前页语义，非历史记录。
+- [GOV.UK Error summary](https://design-system.service.gov.uk/components/error-summary/)：字段错误之外提供集中定位入口；本库采用失败提交聚焦与原位修正。
+- [Carbon Progress indicator](https://www.carbondesignsystem.com/building-blocks/core/components/progress-indicator/guidelines)：区分当前、已完成和未来步骤；不是进度百分比。
+- [Carbon Notifications](https://www.carbondesignsystem.com/building-blocks/core/patterns/notifications)：依任务上下文选择通知位置和持续性。
+- [Carbon Forms](https://www.carbondesignsystem.com/building-blocks/core/patterns/forms)：按任务组织表单层次、标签与反馈。
+- [Radix Dialog](https://www.radix-ui.com/primitives/docs/components/dialog)：模态焦点与关闭交互由成熟 primitive 处理。
+- [shadcn Sheet](https://ui.shadcn.com/docs/components/base/sheet)：临时侧面板的组件分类参考；当前文档有 Base/Radix 路线，本库继续使用现有 Radix。
+- [React Aria Quality](https://react-aria.adobe.com/quality)：键盘、辅助技术、移动与不同输入方式是独立验证项，不能因依赖库具备这些能力就宣称本库合规。
+
+## 莱茵设计的取舍
+
+新增 SideNav、Breadcrumbs、Steps、Drawer、Fieldset、ErrorSummary；增加 14 类场景指南和两组动效示例，六个组件均进入公共导出。侧栏与面包屑已被展台自身复用，不再依赖“原产品只有两个页面”的历史范围判断。
+
+继续保留暖白、苔绿、三角构架、细线和 120–240ms 日常动效。表单错误不抖动，数字不翻转，告警不闪烁，启动不阻塞真实就绪。移除这些效果不会损害任务理解，反而保持文字和操作目标稳定。
+
+暂不加入日历/日期范围、树、拖拽、富文本、图表引擎、全局命令面板：需要先确定数据规模、选择规则和真实使用入口。完整深色语义主题、原生辅助技术和强制颜色模式仍是独立缺口；这次新增组件不意味着覆盖所有设计系统能力。