@linhey/rhine-design 0.4.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 版本记录
 
+## 0.6.0（2026-10-24）
+
+- 对应 [#8](https://github.com/linhay/rhine-design/issues/8)：新增 `OrbitBackdrop`，将授权移交的轨道艺术维护为公共组件，保留 420 个环节点、185 条空间曲线、箭头、光晕与透视；公共组件增至 60 个，无新增运行时依赖。
+- 内置暂停 / 继续，遵循系统、显式及祖先减少动态偏好；窄窗、页面隐藏、离屏与零尺寸停帧，恢复沿冻结时间继续，卸载清理资源；Canvas 不可用时保留静态艺术与内容。逻辑尺寸使用 client size，保持 CSS 缩放后的描线和静态重绘一致。
+- 固定深色艺术仅调整继承文字和 Logo，不覆写宿主控件的主题 tokens；表单、按钮及 Surface 保持各主题前景与背景成对。新增 `#orbit` 真实展台、[轨道背景契约](docs/ORBIT_BACKDROP.md)、生命周期测试与三主题组合示例。
+- 保留 0.5.0 的全部应用组件、受控状态与 Ant Design / MUI 契约改进。`OrbitBackdrop` 自 0.6.0 提供，0.5.0 及以前不包含此组件；建议固定精确版本并提交 lockfile。
+
+## 0.5.0（2026-10-24）
+
+- 完成 [Ant Design / MUI 逐项对标](docs/ANTD_MUI_AUDIT.md)：补齐表单只读/校验/键盘、连续多选、树字符导航、数据表单选/排序清除/自动固定列、分页首末页/边界焦点、受控左右抽屉、媒体方向键/首尾焦点、图表受控逐点查看与格式化、健康历史稳定 ID 与受控详情。RemoteMultiSelect 默认连续选择，`closeOnSelect=true` 可恢复选完关闭；原单选 Combobox 默认不变。无新增运行时依赖。
+- 发布审阅修正：数字未编辑时不重复提交，未指定 precision 时保留输入精度；加载中的媒体预览保持挂载以接收原生加载/失败事件；空图表不显示不可操作提示，时间轴移除不适用的 ARIA 属性；修正橙趣表格密度/表头主题变量、行悬停底色及仅 CSS 主题根的派生变量。
+
+- 对应 #1–#6：新增 Background/AppShell、MediaCard/MediaViewer、DateField/DateRangePicker/NumberField/TreeSelect/RemoteMultiSelect，加上 TrendChart/StackedBar，共 11 个公共组件。
+- DataTable 增加受控跨页选择、禁选/混合态、层级展开与详情、密度和固定表头/列；Pagination 增加页大小意图。
+- 新增三主题背景、表单、数据与中性媒体 tokens；提供六组真实 React 展台及[应用组件契约](docs/APPLICATION_COMPONENTS.md)。宿主继续负责请求、时区、导出、下载、虚拟列表和持久化。
+- StatusTimeline 增加开始/结束、原因、计数及统计口径的结构化详情，使用可避让视口的 Popover；新增柱形趋势、缺失断线和堆叠占比，未知值不补零，配套文字替代与空/陈旧/错误状态。
+- 本节 API 自 0.5.0 提供；0.4.0 不含这些能力。建议固定版本并提交 lockfile。
+
+- 补齐 Background 六类场景的底色、文字与纹理配置，新增局部 `appearance` 覆盖。`decoration` 默认 `auto`，仅画布使用主题纹理；正文与 AppShell 默认纯色，原有显式 `theme` / `none` 保留。Surface / Fieldset 与主要浮层接入语义底色，遮罩独立配置。新增展台 `#backgrounds`，包含实际弹窗、局部覆盖与纹理切换，仅展示当前主题的场景效果，跟随主题选择器更新。已有正文需要纹理时显式传 `decoration="theme"`。
+
 ## 0.4.0
 
 - 新增 `@linhey/rhine-design/theme`：`ThemeProvider`、`useTheme`、`themes`、`ThemeName` 与 `ThemeProviderProps`，自动加载三套内置主题，支持受控/非受控切换及并列 Provider；嵌套覆盖暂不支持。切换保留组件、表单与浮层状态，偏好存储由宿主管理。展台复用公共 API；主题 CSS 中的展台布局和 HUD/扫描/开机装饰移至 `preview/theme-*.css`。补齐接入文档及 API/展台回归测试。

package/README.md

@@ -16,10 +16,10 @@
   <a href="CHANGELOG.md">版本记录</a>
 </p>
 
-Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、管理界面和数据密集型应用。它将设计规范、48 个组件和动效示例放在一起，帮助团队建立一致、可复用的界面语言。
+Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、管理界面和数据密集型应用。它将设计规范、60 个组件和动效示例放在一起，帮助团队建立一致、可复用的界面语言。
 
 - **一致的视觉语言**：色彩、字体、文字层级、间距、几何与焦点规则。
-- **48 个可组合组件**：覆盖布局、表单、数据、导航、浮层和反馈。
+- **60 个可组合组件**：覆盖布局、表单、数据、导航、浮层和反馈。
 - **可验证的动效**：12 组播放 / 重播 / 复位演示，以及三角构架启动编排。
 - **面向开发协作**：组件契约、交互展台和 AI skill 帮助设计与实现保持一致。
 
@@ -27,6 +27,12 @@ Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、
 
 基于 React 与 Radix UI，采用 [Apache-2.0](LICENSE) 许可证。
 
+**0.5.0 新增能力**：新增背景与多侧栏、复杂表单、受控数据表、媒体与监控图表，共 59 个组件。API、最小接入与版本边界见[应用组件契约](docs/APPLICATION_COMPONENTS.md)。npm 0.4.0 不含这些能力。
+
+**0.6.0 新增能力**：新增 `OrbitBackdrop` 轨道艺术组件，提供暂停、减少动态与静态降级，总数增至 60。安装前核对[版本记录](CHANGELOG.md)与 registry；在线展台跟随 main。
+
+本轮新增 API 与交互已逐项核对 Ant Design / MUI，修复及明确保留的差异见[对标清单](docs/ANTD_MUI_AUDIT.md)。
+
 <a id="quick-start"></a>
 
 ## 快速接入
@@ -36,7 +42,7 @@ Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、
 在你的 React 项目中安装：
 
 ```sh
-npm install @linhey/rhine-design@0.4.0
+npm install --save-exact @linhey/rhine-design@0.6.0
 ```
 
 包与版本信息见 [npm](https://www.npmjs.com/package/@linhey/rhine-design)。如需使用未发版的源码，可安装 `git+https://github.com/linhay/rhine-design.git#<commit>`；建议固定版本并提交 lockfile。
@@ -65,6 +71,14 @@ export function Welcome() {
 
 入口自动加载样式，用 `.rhine-theme` 包裹页面即可使用默认主题。布局和颜色变量使用 `--rhine-*` 前缀；完整定义见 [tokens.css](components/tokens.css)。
 
+### 背景组件（0.5.0）
+
+0.5.0 提供 Background 与 AppShell，npm 0.4.0 不含这两项能力。背景层级、最小接入及兼容范围见[背景与应用外壳契约](docs/APPLICATION_COMPONENTS.md)，真实展台见 [场景背景](https://linhay.github.io/rhine-design/#backgrounds) 和 [背景与侧栏](https://linhay.github.io/rhine-design/#app-shell)。
+
+### 轨道背景（0.6.0）
+
+OrbitBackdrop 承接授权移交的轨道动画，保留环节点、曲线、箭头、光晕与透视，并提供暂停、减少动态和离屏停帧。它是纯装饰，不表示加载或业务进度。契约与接入见[轨道背景](docs/ORBIT_BACKDROP.md)，真实展台见[轨道星空](https://linhay.github.io/rhine-design/#orbit)。
+
 ### 一键切换主题（0.4.0）
 
 展台右上角可切换并记忆主题。新增 **橙趣 · 粗描边**：浅灰蓝点阵背景、米白圆角卡片、黑色粗边、向右下偏移的硬阴影与亮橙主按钮。打开 [在线订阅管理示例](https://linhay.github.io/rhine-design/?theme=neo-brutalism#subscriptions)，体验卡片详情、管理菜单与演示表单；本地开发访问 `http://127.0.0.1:18309/?theme=neo-brutalism#subscriptions`。
@@ -91,6 +105,8 @@ export function App() {
 
 完整变量、类型标签、交互与减少动态规则见 [橙趣主题规范](docs/THEME_NEO_BRUTALISM.md)。现有 CSS-only 用法仍支持；展台装饰独立放在 `preview/theme-*.css`。
 
+0.5.0 新增六类[场景背景配置](docs/THEMING.md#场景背景050)：画布、正文、侧栏、卡片表单、浮层和媒体。正文默认无纹理，支持局部配色与纹理覆盖；本地展台 `http://127.0.0.1:18309/#backgrounds` 可查看当前主题的六类场景，并通过主题选择器切换。
+
 类名、CSS 变量、动画名称与动态设置统一使用 `rhine-` 命名空间。升级到 0.3.0 时请同步迁移主题根、自定义样式与动效属性，具体见 [迁移说明](CHANGELOG.md#030)。
 
 ### 兼容范围
@@ -108,14 +124,14 @@ export function App() {
 | --- | --- |
 | 品牌与文字 | Logo · Text |
 | 操作 | Button · Icon · IconButton · Link · CopyButton |
-| 布局 | Surface · Toolbar · Divider · Stack · Inline · Grid |
-| 表单与选择 | TextField · Fieldset¹ · ErrorSummary¹ · Textarea · Select · Checkbox · RadioGroup · Switch · SearchField · Combobox · SelectionCard |
+| 布局与背景 | Surface · Toolbar · Divider · Stack · Inline · Grid · Background² · AppShell² · OrbitBackdrop³ |
+| 表单与选择 | TextField · Fieldset¹ · ErrorSummary¹ · Textarea · Select · Checkbox · RadioGroup · Switch · SearchField · Combobox · SelectionCard · DateField² · DateRangePicker² · NumberField² · TreeSelect² · RemoteMultiSelect² |
 | 导航与展开 | SideNav¹ · Breadcrumbs¹ · Steps¹ · Tabs · SegmentedControl · Disclosure |
-| 数据 | Metric · KeyValue · DataTable · Pagination · StatusTimeline¹ · TimelineLegend¹ |
+| 数据与媒体 | Metric · KeyValue · DataTable · Pagination · StatusTimeline¹ · TimelineLegend¹ · TrendChart² · StackedBar² · MediaCard² · MediaViewer² |
 | 浮层 | Drawer¹ · Dialog · ConfirmDialog · Popover · Menu · Tooltip |
 | 状态与反馈 | Badge · Notice · Toast · Progress · Skeleton · EmptyState |
 
-¹ 自 0.4.0 提供。
+¹ 自 0.4.0 提供。² 自 0.5.0 提供。³ 自 0.6.0 提供。
 
 参数、状态和组合示例见[组件 API](components/README.md)与[常用组件契约](components/COMMON_COMPONENTS.md)。
 
@@ -133,6 +149,7 @@ export function App() {
 | 品牌几何与 Logo | [Logo 契约](components/README.md#品牌标志) | [品牌标志](https://linhay.github.io/rhine-design/#brand) |
 | 动效、交互与减少动态 | [Motion](components/MOTION.md) | [动效实验室](https://linhay.github.io/rhine-design/#motion) |
 | 启动动画与就绪衔接 | [Startup](components/STARTUP.md) | [启动动画](https://linhay.github.io/rhine-design/#startup) |
+| 轨道装饰、暂停与静态降级 | [OrbitBackdrop](docs/ORBIT_BACKDROP.md) | [轨道星空](https://linhay.github.io/rhine-design/#orbit) |
 | 场景与交互选型 | [使用规范](docs/INTERACTION_PATTERNS.md) | [场景指南](https://linhay.github.io/rhine-design/#patterns) |
 | 导航与表单流程 | [组件契约](docs/INTERACTION_PATTERNS.md#新组件契约) | [导航](https://linhay.github.io/rhine-design/#navigation) · [表单](https://linhay.github.io/rhine-design/#form-workflow) |
 | 系统覆盖与演进方向 | [组件系统对照](docs/DESIGN_SYSTEM_AUDIT.md) | — |

package/components/AdvancedForms.tsx

@@ -0,0 +1,184 @@
+import { useEffect, useId, useLayoutEffect, useRef, useState, type KeyboardEvent } from 'react';
+import { Button, TextField, type Choice } from './components';
+import { Combobox } from './Forms';
+
+export interface DateFieldProps {
+  label: string; value: string; onValueChange: (value: string) => void;
+  min?: string; max?: string; disabled?: boolean; error?: string;
+  readOnly?: boolean; required?: boolean; id?: string; name?: string; hint?: string;
+  onValidationChange?: (error: string | null) => void;
+}
+function dateError(value: string, min?: string, max?: string): string | undefined {
+  if (min && max && min > max) return '最早日期不能晚于最晚日期。';
+  if (!value) return;
+  const parsed = new Date(`${value}T00:00:00Z`);
+  if (!/^\d{4}-\d{2}-\d{2}$/.test(value) || !Number.isFinite(parsed.getTime()) || parsed.toISOString().slice(0, 10) !== value) return '请输入有效日期。';
+  if (min && value < min) return `日期不能早于 ${min}。`;
+  if (max && value > max) return `日期不能晚于 ${max}。`;
+}
+function useDateValidation(error: string | undefined, onValidationChange?: (error: string | null) => void) {
+  const callback = useRef(onValidationChange);
+  useEffect(() => { callback.current = onValidationChange; }, [onValidationChange]);
+  useEffect(() => { callback.current?.(error || null); }, [error]);
+}
+/** Date-only ISO strings: conversion to timestamps and time zones belongs to the host. */
+export function DateField({ onValueChange, onValidationChange, error, ...props }: DateFieldProps) {
+  const invalid = error || dateError(props.value, props.min, props.max);
+  useDateValidation(invalid, onValidationChange);
+  return <TextField {...props} error={invalid} type="date" onChange={event => { if (!props.disabled && !props.readOnly) onValueChange(event.target.value); }} />;
+}
+export interface DateRange { start: string; end: string }
+export interface DateRangePickerProps {
+  label: string; value: DateRange; onValueChange: (value: DateRange) => void;
+  min?: string; max?: string; disabled?: boolean; error?: string;
+  presets?: { label: string; value: DateRange }[];
+  readOnly?: boolean; required?: boolean; clearable?: boolean; hint?: string;
+  startLabel?: string; endLabel?: string; startName?: string; endName?: string;
+  onValidationChange?: (error: string | null) => void;
+}
+export function DateRangePicker({ label, value, onValueChange, min, max, disabled, error, presets = [], readOnly = false, required, clearable = true, hint, startLabel = '开始日期', endLabel = '结束日期', startName, endName, onValidationChange }: DateRangePickerProps) {
+  const id = useId();
+  const rangeError = (range: DateRange) => dateError(range.start, min, max) || dateError(range.end, min, max) || (range.start && range.end && range.start > range.end ? '结束日期不能早于开始日期。' : undefined);
+  const invalid = error || rangeError(value);
+  useDateValidation(invalid, onValidationChange);
+  return <fieldset className="rhine-date-range" disabled={disabled} aria-describedby={[hint && `${id}-hint`, invalid && id].filter(Boolean).join(' ') || undefined}>
+    <legend>{label}</legend><div className="rhine-date-range__fields">
+      <DateField label={startLabel} name={startName} value={value.start} min={min} max={max} readOnly={readOnly} required={required} disabled={disabled} onValueChange={start => onValueChange({ ...value, start })} error={invalid ? '请检查日期范围' : undefined} />
+      <DateField label={endLabel} name={endName} value={value.end} min={value.start && (!min || value.start > min) ? value.start : min} max={max} readOnly={readOnly} required={required} disabled={disabled} onValueChange={end => onValueChange({ ...value, end })} />
+    </div><div className="rhine-inline">
+      {presets.map(preset => <Button key={preset.label} variant="secondary" disabled={disabled || readOnly || !!rangeError(preset.value) || !!(required && (!preset.value.start || !preset.value.end))} onClick={() => onValueChange(preset.value)}>{preset.label}</Button>)}
+      {clearable && <Button variant="quiet" disabled={disabled || readOnly || (!value.start && !value.end)} onClick={() => onValueChange({ start: '', end: '' })}>清空日期</Button>}
+    </div>{hint && <p id={`${id}-hint`} className="rhine-field__hint">{hint}</p>}{invalid && <p id={id} role="alert" className="rhine-field__error">{invalid}</p>}
+  </fieldset>;
+}
+
+export interface NumberFieldProps {
+  label: string; value: number | null; onValueChange: (value: number | null) => void;
+  min?: number; max?: number; step?: number; precision?: number; disabled?: boolean; error?: string;
+  readOnly?: boolean; required?: boolean; name?: string; id?: string; hint?: string;
+  controls?: boolean;
+}
+export function NumberField({ label, value, onValueChange, min, max, step = 1, precision, disabled, error, readOnly = false, required, name, id, hint, controls = true }: NumberFieldProps) {
+  const [draft, setDraft] = useState(value === null ? '' : String(value));
+  const [localError, setLocalError] = useState('');
+  const composing = useRef(false);
+  useEffect(() => { setDraft(value === null ? '' : String(value)); setLocalError(''); }, [value]);
+  const numericDraft = draft.trim() ? Number(draft) : null;
+  const boundsError = (min !== undefined && max !== undefined && min > max) ? '最小值不能大于最大值。' : numericDraft !== null && Number.isFinite(numericDraft) && ((min !== undefined && numericDraft < min) || (max !== undefined && numericDraft > max)) ? `请输入 ${min ?? '−∞'} 至 ${max ?? '+∞'} 之间的数字。` : undefined;
+  const blocked = disabled || readOnly || (min !== undefined && max !== undefined && min > max);
+  const normalize = (n: number) => Math.min(max ?? Infinity, Math.max(min ?? -Infinity, Number(n.toFixed(Math.max(0, Math.min(15, precision ?? 12))))));
+  const commit = () => {
+    if (composing.current || blocked) return;
+    if (!draft.trim()) { setLocalError(''); if (value !== null) onValueChange(null); return; }
+    const n = Number(draft);
+    if (!Number.isFinite(n)) { setLocalError('请输入有效数字。'); return; }
+    if ((min !== undefined && n < min) || (max !== undefined && n > max)) { setLocalError(`请输入 ${min ?? '−∞'} 至 ${max ?? '+∞'} 之间的数字。`); return; }
+    const next = precision === undefined ? n : normalize(n); setDraft(String(next)); setLocalError(''); if (next !== value) onValueChange(next);
+  };
+  const move = (direction: number) => {
+    if (blocked || composing.current) return;
+    const parsed = draft.trim() ? Number(draft) : value ?? 0;
+    const next = normalize((Number.isFinite(parsed) ? parsed : value ?? 0) + direction * (Number.isFinite(step) && step ? Math.abs(step) : 1));
+    setDraft(String(next)); setLocalError(''); onValueChange(next);
+  };
+  return <div className="rhine-number-field"><TextField label={label} id={id} name={name} hint={hint} required={required} readOnly={readOnly} inputMode="decimal" role="spinbutton" aria-valuenow={numericDraft !== null && Number.isFinite(numericDraft) ? numericDraft : undefined} aria-valuemin={min} aria-valuemax={max}
+    value={draft} disabled={disabled} error={error || localError || boundsError} onChange={event => { if (!blocked) { setDraft(event.target.value); setLocalError(''); } }} onBlur={commit}
+    onCompositionStart={() => { composing.current = true; }} onCompositionEnd={() => { composing.current = false; }}
+    onKeyDown={event => { if (event.nativeEvent.isComposing || composing.current || blocked) return; if (event.key === 'Escape' && (draft !== (value === null ? '' : String(value)) || localError)) { event.preventDefault(); event.stopPropagation(); setDraft(value === null ? '' : String(value)); setLocalError(''); } if (event.key === 'Enter') { event.preventDefault(); commit(); } if (event.key === 'ArrowUp' || event.key === 'ArrowDown') { event.preventDefault(); move(event.key === 'ArrowUp' ? 1 : -1); } }} />
+    {controls && <div className="rhine-inline"><Button variant="secondary" disabled={blocked || (numericDraft !== null && min !== undefined && numericDraft <= min)} onMouseDown={event => event.preventDefault()} onClick={() => move(-1)} aria-label={`减少${label}`}>−</Button><Button variant="secondary" disabled={blocked || (numericDraft !== null && max !== undefined && numericDraft >= max)} onMouseDown={event => event.preventDefault()} onClick={() => move(1)} aria-label={`增加${label}`}>+</Button></div>}
+  </div>;
+}
+
+export interface RemoteMultiSelectProps {
+  label: string; query: string; onQueryChange: (query: string) => void;
+  value: Choice[]; onValueChange: (value: Choice[]) => void; options: Choice[];
+  loading?: boolean; error?: string; disabled?: boolean;
+  readOnly?: boolean; clearable?: boolean; closeOnSelect?: boolean; clearQueryOnSelect?: boolean;
+  placeholder?: string; hint?: string; name?: string;
+}
+export function RemoteMultiSelect({ value, onValueChange, options, readOnly = false, clearable = true, closeOnSelect = false, clearQueryOnSelect = false, name, ...props }: RemoteMultiSelectProps) {
+  const inputId = useId();
+  const focusInput = () => document.getElementById(inputId)?.focus();
+  const remove = (key: string) => {
+    if (props.disabled || readOnly || value.find(item => item.value === key)?.disabled) return;
+    onValueChange(value.filter(item => item.value !== key)); focusInput();
+  };
+  return <div className="rhine-multi-select">
+    <Combobox {...props} id={inputId} readOnly={readOnly} selectedValues={value.map(item => item.value)} closeOnSelect={closeOnSelect} onEmptyBackspace={() => { const last = [...value].reverse().find(item => !item.disabled); if (last) remove(last.value); }} options={options.map(option => ({ ...option, disabled: option.disabled || value.some(item => item.value === option.value) }))} value={null} onValueChange={option => { const original = options.find(item => item.value === option.value); if (original && !value.some(item => item.value === original.value)) { onValueChange([...value, original]); if (clearQueryOnSelect) props.onQueryChange(''); } }} />
+    {name && value.map(item => <input key={item.value} type="hidden" name={name} value={item.value} disabled={props.disabled} />)}
+    <ul className="rhine-multi-select__tags" aria-label={`${props.label}已选项`}>{value.map(item => <li key={item.value}><span>{item.label}</span><Button variant="quiet" disabled={props.disabled || readOnly || item.disabled} aria-label={`移除${item.label}`} onClick={() => remove(item.value)}>×</Button></li>)}</ul>
+    {clearable && <Button variant="quiet" disabled={props.disabled || readOnly || !value.some(item => !item.disabled)} onClick={() => { onValueChange(value.filter(item => item.disabled)); focusInput(); }}>清空选择</Button>}
+  </div>;
+}
+
+export interface TreeNode { id: string; label: string; disabled?: boolean; selectable?: boolean; children?: TreeNode[] }
+export interface TreeSelectProps {
+  label: string; nodes: TreeNode[]; value: string[]; onValueChange: (value: string[]) => void;
+  expandedKeys: string[]; onExpandedChange: (keys: string[]) => void; multiple?: boolean;
+  disabled?: boolean; loading?: boolean; error?: string;
+  readOnly?: boolean; name?: string;
+}
+export function TreeSelect({ label, nodes, value, onValueChange, expandedKeys, onExpandedChange, multiple = false, disabled = false, loading, error, readOnly = false, name }: TreeSelectProps) {
+  const root = useRef<HTMLDivElement>(null), id = useId();
+  const [active, setActive] = useState<string>();
+  const hadFocus = useRef(false), typeahead = useRef({ text: '', time: 0 });
+  const visible: { node: TreeNode; parent?: string }[] = [];
+  const collect = (items: TreeNode[], parent?: string) => items.forEach(node => { visible.push({ node, parent }); if (expandedKeys.includes(node.id)) collect(node.children ?? [], node.id); });
+  collect(nodes);
+  const parents = new Map<string, string | undefined>();
+  const collectParents = (items: TreeNode[], parent?: string) => items.forEach(node => { parents.set(node.id, parent); collectParents(node.children ?? [], node.id); });
+  collectParents(nodes);
+  let ancestor = active;
+  while (ancestor && !visible.some(item => item.node.id === ancestor)) ancestor = parents.get(ancestor);
+  const current = ancestor || visible.find(item => value.includes(item.node.id))?.node.id || visible[0]?.node.id;
+  const itemId = (key: string) => `${id}-item-${encodeURIComponent(key)}`;
+  const focus = (key?: string) => { if (!key) return; setActive(key); document.getElementById(itemId(key))?.focus(); };
+  useLayoutEffect(() => {
+    if (hadFocus.current && active !== current && current) document.getElementById(itemId(current))?.focus();
+  }, [active, current, id]);
+  const expand = (node: TreeNode, next: boolean) => { if (!disabled) onExpandedChange(next ? [...new Set([...expandedKeys, node.id])] : expandedKeys.filter(key => key !== node.id)); };
+  const canChoose = (node: TreeNode) => !disabled && !readOnly && !loading && !error && !node.disabled && node.selectable !== false;
+  const choose = (node: TreeNode) => { if (!canChoose(node)) return; onValueChange(multiple ? value.includes(node.id) ? value.filter(key => key !== node.id) : [...value, node.id] : [node.id]); };
+  const keyDown = (event: KeyboardEvent, node: TreeNode) => {
+    if (event.nativeEvent.isComposing || event.keyCode === 229) return;
+    const index = visible.findIndex(item => item.node.id === node.id), expanded = expandedKeys.includes(node.id);
+    if (['ArrowDown','ArrowUp','ArrowLeft','ArrowRight','Home','End',' ','Enter'].includes(event.key)) { event.preventDefault(); event.stopPropagation(); }
+    if (event.key === 'ArrowDown') focus(visible[Math.min(visible.length - 1, index + 1)]?.node.id);
+    if (event.key === 'ArrowUp') focus(visible[Math.max(0, index - 1)]?.node.id);
+    if (event.key === 'Home') focus(visible[0]?.node.id);
+    if (event.key === 'End') focus(visible.at(-1)?.node.id);
+    if (event.key === 'ArrowRight' && node.children?.length) { if (!expanded) expand(node, true); else focus(node.children[0].id); }
+    if (event.key === 'ArrowLeft') { if (expanded && node.children?.length) expand(node, false); else focus(visible[index]?.parent); }
+    if (event.key === ' ' || event.key === 'Enter') choose(node);
+    if (event.key === '*' && !disabled) { event.preventDefault(); event.stopPropagation(); onExpandedChange([...new Set([...expandedKeys, ...visible.filter(item => item.parent === visible[index]?.parent && item.node.children?.length).map(item => item.node.id)])]); }
+    if (multiple && (event.ctrlKey || event.metaKey) && event.key.toLowerCase() === 'a') {
+      event.preventDefault(); event.stopPropagation();
+      if (disabled || readOnly || loading || error) return;
+      const eligible = visible.filter(item => canChoose(item.node)).map(item => item.node.id);
+      onValueChange(eligible.every(key => value.includes(key)) ? value.filter(key => !eligible.includes(key)) : [...new Set([...value, ...eligible])]);
+    } else if (event.key.length === 1 && event.key !== ' ' && event.key !== '*' && !event.ctrlKey && !event.metaKey && !event.altKey) {
+      event.stopPropagation();
+      const now = Date.now();
+      const previous = now - typeahead.current.time < 500 ? typeahead.current.text : '';
+      const typed = previous + event.key.toLocaleLowerCase();
+      typeahead.current = { text: typed, time: now };
+      const search = [...typed].every(character => character === typed[0]) ? typed[0] : typed;
+      const ordered = [...visible.slice(index + 1), ...visible.slice(0, index + 1)];
+      const match = ordered.find(item => item.node.label.toLocaleLowerCase().startsWith(search));
+      if (match) { event.preventDefault(); event.stopPropagation(); focus(match.node.id); }
+    }
+  };
+  const renderNodes = (items: TreeNode[]) => items.map(node => {
+    const expanded = expandedKeys.includes(node.id);
+    return <div role="treeitem" key={node.id} id={itemId(node.id)} tabIndex={current === node.id ? 0 : -1} aria-label={node.label} aria-expanded={node.children?.length ? expanded : undefined} aria-selected={!multiple && node.selectable !== false ? value.includes(node.id) : undefined} aria-checked={multiple && node.selectable !== false ? value.includes(node.id) : undefined} aria-disabled={disabled || loading || !!error || node.disabled || undefined}
+      onFocus={event => { if (event.target === event.currentTarget) setActive(node.id); }} onKeyDown={event => keyDown(event, node)}>
+      <div className="rhine-tree__row" data-selected={value.includes(node.id)} onClick={() => { focus(node.id); choose(node); }}>
+        {node.children?.length ? <button type="button" tabIndex={-1} disabled={disabled} aria-label={`${expanded ? '收起' : '展开'}${node.label}`} onClick={event => { event.stopPropagation(); focus(node.id); expand(node, !expanded); }}>{expanded ? '−' : '+'}</button> : <span className="rhine-tree__spacer" />}
+        {node.selectable !== false && <span aria-hidden="true">{value.includes(node.id) ? '✓' : '○'}</span>}<span>{node.label}</span>{node.disabled && <small>不可选</small>}
+      </div>{expanded && !!node.children?.length && <div role="group">{renderNodes(node.children)}</div>}
+    </div>;
+  });
+  return <div className="rhine-tree" ref={root} onFocusCapture={() => { hadFocus.current = true; }} onBlurCapture={event => { if (!event.currentTarget.contains(event.relatedTarget)) hadFocus.current = false; }}>
+    {name && value.map(key => <input key={key} type="hidden" name={name} value={key} disabled={disabled} />)}
+    <div role="tree" aria-label={label} aria-multiselectable={multiple || undefined} aria-readonly={readOnly || undefined} aria-busy={loading} aria-disabled={disabled || undefined}>{renderNodes(nodes)}</div>{(loading || error || !nodes.length) && <p role={error ? 'alert' : 'status'}>{loading ? '正在读取…' : error || '暂无节点'}</p>}</div>;
+}

package/components/AppShell.tsx

@@ -0,0 +1,71 @@
+import { useId, useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import { Button } from './components';
+import { Drawer } from './Overlays';
+import { Background, type BackgroundDecoration } from './Background';
+
+export interface ShellPanel {
+  label: string; content: ReactNode; open: boolean; onOpenChange: (open: boolean) => void;
+  drawerOpen?: boolean; defaultDrawerOpen?: boolean; onDrawerOpenChange?: (open: boolean) => void;
+  width?: number; breakpoint?: number;
+}
+export interface AppShellProps {
+  layout: 'single' | 'double-left' | 'left-right';
+  navigation: ShellPanel; secondary?: ShellPanel;
+  header?: ReactNode; children: ReactNode; label?: string; decoration?: BackgroundDecoration;
+  className?: string; style?: CSSProperties;
+}
+
+function Panel({ panel, overlay, side, id, drawerOpen, setDrawerOpen }: { panel: ShellPanel; overlay: boolean; side: 'left' | 'right'; id: string; drawerOpen: boolean; setDrawerOpen: (open: boolean) => void }) {
+  const floating = overlay || drawerOpen;
+  return <div className="rhine-shell__panel-control">
+    <Drawer title={panel.label} description="关闭后返回当前任务。" side={side} open={drawerOpen} onOpenChange={setDrawerOpen}
+      trigger={<Button id={`${id}-toggle`} variant="secondary" aria-controls={floating ? undefined : id} aria-expanded={floating ? drawerOpen : panel.open}
+        onClick={event => { if (!floating) { event.preventDefault(); panel.onOpenChange(!panel.open); } }}>{floating ? '' : panel.open ? '收起' : '展开'}{panel.label}</Button>}>{panel.content}</Drawer>
+  </div>;
+}
+
+export function AppShell({ layout, navigation, secondary, header, children, label = '应用工作区', decoration = 'auto', className = '', style }: AppShellProps) {
+  const ref = useRef<HTMLDivElement>(null);
+  const focusedPanel = useRef<'nav' | 'secondary' | null>(null);
+  const [width, setWidth] = useState(0);
+  const [localNavigationDrawer, setLocalNavigationDrawer] = useState(navigation.defaultDrawerOpen ?? false), [localSecondaryDrawer, setLocalSecondaryDrawer] = useState(secondary?.defaultDrawerOpen ?? false);
+  const navigationDrawer = navigation.drawerOpen ?? localNavigationDrawer, secondaryDrawer = secondary?.drawerOpen ?? localSecondaryDrawer;
+  const setNavigationDrawer = (next: boolean) => { if (navigation.drawerOpen === undefined) setLocalNavigationDrawer(next); navigation.onDrawerOpenChange?.(next); };
+  const setSecondaryDrawer = (next: boolean) => { if (secondary?.drawerOpen === undefined) setLocalSecondaryDrawer(next); secondary?.onDrawerOpenChange?.(next); };
+  const id = useId();
+  useLayoutEffect(() => {
+    if (!ref.current) return;
+    // CSS layout pixels stay stable under zoom and transforms; visual bounds do not.
+    const measure = () => setWidth(ref.current?.clientWidth ?? 0);
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(ref.current);
+    return () => observer.disconnect();
+  }, []);
+  const navOverlay = width < (navigation.breakpoint ?? 760), secondaryOverlay = width < (secondary?.breakpoint ?? 1120);
+  const hasSecondary = layout !== 'single' && !!secondary;
+  useLayoutEffect(() => {
+    const suffix = focusedPanel.current;
+    if (suffix) {
+      const pane = document.getElementById(`${id}-${suffix}`);
+      if (pane?.hidden && (document.activeElement === document.body || pane.contains(document.activeElement))) {
+        (document.getElementById(`${id}-${suffix}-toggle`) ?? document.getElementById(`${id}-nav-toggle`))?.focus();
+        focusedPanel.current = null;
+      }
+    }
+  }, [id, navOverlay, secondaryOverlay, hasSecondary, navigation.open, secondary?.open]);
+  return <div className={`rhine-shell ${className}`} style={style} ref={ref} role="region" aria-label={label} data-layout={layout}
+    onFocusCapture={event => { focusedPanel.current = document.getElementById(`${id}-nav`)?.contains(event.target) ? 'nav' : document.getElementById(`${id}-secondary`)?.contains(event.target) ? 'secondary' : null; }}
+    onBlurCapture={event => { if (event.relatedTarget && !event.currentTarget.contains(event.relatedTarget)) focusedPanel.current = null; }}>
+    <header className="rhine-shell__header">
+      <Panel panel={navigation} overlay={navOverlay} side="left" id={`${id}-nav`} drawerOpen={navigationDrawer} setDrawerOpen={setNavigationDrawer} />
+      {hasSecondary && <Panel panel={secondary} overlay={secondaryOverlay} side={layout === 'left-right' ? 'right' : 'left'} id={`${id}-secondary`} drawerOpen={secondaryDrawer} setDrawerOpen={setSecondaryDrawer} />}
+      {header}
+    </header>
+    <div className="rhine-shell__body">
+      <aside id={`${id}-nav`} className="rhine-shell__nav" style={{ flexBasis: navigation.width }} aria-label={navigation.label} hidden={navOverlay || navigationDrawer || !navigation.open}>{!navigationDrawer && navigation.content}</aside>
+      <aside id={`${id}-secondary`} className="rhine-shell__secondary" style={{ flexBasis: secondary?.width }} aria-label={secondary?.label} hidden={!hasSecondary || secondaryOverlay || secondaryDrawer || !secondary?.open}>{hasSecondary && !secondaryDrawer && secondary?.content}</aside>
+      <Background className="rhine-shell__content" decoration={decoration} tabIndex={0} role="region" aria-label="正文">{children}</Background>
+    </div>
+  </div>;
+}

package/components/Background.tsx

@@ -0,0 +1,29 @@
+import type { ComponentPropsWithRef, CSSProperties } from 'react';
+
+export type BackgroundRole = 'canvas' | 'content' | 'sidebar' | 'surface' | 'overlay' | 'media';
+export type BackgroundDecoration = 'auto' | 'theme' | 'none';
+
+export interface BackgroundAppearance {
+  color?: CSSProperties['backgroundColor'];
+  textColor?: CSSProperties['color'];
+  texture?: CSSProperties['backgroundImage'];
+  textureSize?: CSSProperties['backgroundSize'];
+}
+
+export interface BackgroundProps extends ComponentPropsWithRef<'div'> {
+  roleTone?: BackgroundRole;
+  decoration?: BackgroundDecoration;
+  appearance?: BackgroundAppearance;
+}
+
+/** Paints on this element, without a positioning context or an intercepting overlay. */
+export function Background({ roleTone = 'content', decoration = 'auto', appearance, style, className = '', ...props }: BackgroundProps) {
+  const paint = {
+    '--rhine-background-color': appearance?.color,
+    '--rhine-background-foreground': appearance?.textColor,
+    '--rhine-background-image': appearance?.texture,
+    '--rhine-background-size': appearance?.textureSize,
+    ...style,
+  } as CSSProperties;
+  return <div {...props} style={paint} className={`rhine-background ${className}`} data-tone={roleTone} data-decoration={decoration} />;
+}

package/components/COMMON_COMPONENTS.md

@@ -2,9 +2,9 @@
 
 本文件定义[莱茵设计](../README.md)的常用组件契约。先固定契约和组件展台，再验证；默认优先复用本目录，页面先改设计稿，再按授权接入App。具体业务由宿主定义，不进入通用契约。
 
-## 新增导航与流程能力（main，未发布）
+## 导航与流程能力（0.4.0）
 
-SideNav、Breadcrumbs、Steps、Drawer、Fieldset、ErrorSummary、StatusTimeline、TimelineLegend 的 API、键盘与场景契约见[交互选型](../docs/INTERACTION_PATTERNS.md)。main 共48个导出组件；下表保留原24个扩展组件的契约。
+SideNav、Breadcrumbs、Steps、Drawer、Fieldset、ErrorSummary、StatusTimeline、TimelineLegend 的 API、键盘与场景契约见[交互选型](../docs/INTERACTION_PATTERNS.md)。0.4.0 共48个导出组件；下表保留原24个扩展组件的契约。0.5.0 新增11个组件及DataTable/Pagination扩展，见[应用组件契约](../docs/APPLICATION_COMPONENTS.md)。
 
 ## 范围与契约
 

package/components/Charts.tsx

@@ -0,0 +1,94 @@
+import { useId, useState, type CSSProperties, type ReactNode } from 'react';
+import { DataTable } from './Data';
+import { EmptyState, Notice } from './components';
+
+export interface ChartPoint { id: string; label: string; value: number | null }
+interface ChartContext { label: string; unit: string; rangeLabel: string; description: string; stale?: string; error?: string; loading?: boolean; valueFormatter?: (value: number | null) => string }
+export interface TrendChartProps extends ChartContext {
+  points: ChartPoint[]; kind?: 'bar' | 'line';
+  activePointId?: string | null; defaultActivePointId?: string; onActivePointChange?: (id: string | null) => void;
+}
+const known = (value: number | null): value is number => value !== null && Number.isFinite(value);
+
+function ChartFrame({ label, unit, rangeLabel, description, stale, error, loading, children }: ChartContext & { children: ReactNode }) {
+  return <figure className="rhine-chart" aria-label={label} aria-busy={loading}>
+    <figcaption><strong>{label}</strong><span>{rangeLabel} · 单位：{unit}</span><p>{description}</p></figcaption>
+    {error && <Notice title="图表读取失败" tone="error">{error} · 已有数据仅供参考。</Notice>}
+    {stale && <Notice title="数据已陈旧" tone="warning">{stale}</Notice>}
+    {loading && <p role="status">正在读取，保留已有数据。</p>}{children}
+  </figure>;
+}
+
+/** The host provides bucket order, timestamps, units, and aggregation semantics. */
+export function TrendChart({ points, kind = 'bar', activePointId, defaultActivePointId, onActivePointChange, ...context }: TrendChartProps) {
+  const id = useId(), finite = points.map(point => point.value).filter(known);
+  const [localActive, setLocalActive] = useState<string | null>(defaultActivePointId ?? null);
+  const [focused, setFocused] = useState(false);
+  const active = activePointId === undefined ? localActive : activePointId;
+  const activeIndex = points.findIndex(point => point.id === active), activePoint = points[activeIndex];
+  const select = (next: string | null) => { if (activePointId === undefined) setLocalActive(next); if (next !== active) onActivePointChange?.(next); };
+  const format = (value: number | null) => context.valueFormatter ? context.valueFormatter(known(value) ? value : null) : known(value) ? String(value) : '未知';
+  const minimum = finite.reduce((min, value) => Math.min(min, value), 0), maximum = finite.reduce((max, value) => Math.max(max, value), 0);
+  // Normalize first so opposite finite extremes cannot overflow the coordinate span.
+  const magnitude = Math.max(Math.abs(minimum), Math.abs(maximum), 1), span = (maximum / magnitude - minimum / magnitude) || 1;
+  const x = (index: number) => (index + 0.5) * 600 / Math.max(1, points.length);
+  const y = (value: number) => 170 - (value / magnitude - minimum / magnitude) / span * 160;
+  let connected = false;
+  const path = points.map((point, index) => {
+    if (!known(point.value)) { connected = false; return ''; }
+    const command = connected ? 'L' : 'M'; connected = true;
+    return `${command}${x(index)},${y(point.value)}`;
+  }).join(' ');
+  return <ChartFrame {...context}>
+    {!finite.length ? <EmptyState title={points.length ? '所有采样值均未知' : '暂无采样'} description="缺失值不会补零。" /> : <>
+      <div className="rhine-chart__scale"><span>{format(maximum)} {context.unit}</span><span>{format(minimum)} {context.unit}</span></div>
+      <svg className="rhine-chart__plot" viewBox="0 0 600 180" preserveAspectRatio="none" role="img" aria-labelledby={`${id}-title ${id}-description`} aria-describedby={`${id}-inspection`} tabIndex={0}
+        onFocus={() => { setFocused(true); if (!activePoint) select(points[0]?.id ?? null); }} onBlur={() => setFocused(false)}
+        onKeyDown={event => {
+          if (event.altKey || event.ctrlKey || event.metaKey) return;
+          const next = event.key === 'Home' ? 0 : event.key === 'End' ? points.length - 1 : event.key === 'ArrowLeft' ? Math.max(0, activeIndex - 1) : event.key === 'ArrowRight' ? Math.min(points.length - 1, activeIndex + 1) : undefined;
+          if (next !== undefined) { event.preventDefault(); select(points[next]?.id ?? null); }
+        }}
+        onPointerMove={event => {
+          if (event.pointerType !== 'mouse' && !event.buttons) return;
+          const rect = event.currentTarget.getBoundingClientRect();
+          if (rect.width) select(points[Math.max(0, Math.min(points.length - 1, Math.floor((event.clientX - rect.left) / rect.width * points.length)))]?.id ?? null);
+        }}
+        onPointerLeave={() => { if (!focused) select(null); }}
+        onClick={event => {
+          const rect = event.currentTarget.getBoundingClientRect();
+          event.currentTarget.focus();
+          if (rect.width) select(points[Math.max(0, Math.min(points.length - 1, Math.floor((event.clientX - rect.left) / rect.width * points.length)))]?.id ?? null);
+        }}>
+        <title id={`${id}-title`}>{context.label} · {kind === 'bar' ? '柱形趋势' : '历史折线'}</title>
+        <desc id={`${id}-description`}>{context.description}；{points.length} 个时段，{points.length - finite.length} 个未知值。完整标签与数值见下方数据表。</desc>
+        <path className="rhine-chart__grid" d={`M0,${y(0)}H600 M0,10H600 M0,170H600`} />
+        {activePoint && <rect className="rhine-chart__highlight" x={activeIndex * 600 / points.length} y={0} width={600 / points.length} height={180} />}
+        {kind === 'line' && <path className="rhine-chart__line" d={path} vectorEffect="non-scaling-stroke" />}
+        {points.map((point, index) => !known(point.value) ? <path key={point.id} className="rhine-chart__missing" d={`M${x(index) - 3},174l6,6m0,-6l-6,6`} vectorEffect="non-scaling-stroke" /> : kind === 'bar' ?
+          <rect key={point.id} className="rhine-chart__bar" x={x(index) - 210 / points.length} y={Math.min(y(0), y(point.value))} width={420 / points.length} height={Math.abs(y(point.value) - y(0))}><title>{point.label}：{point.value} {context.unit}</title></rect> :
+          <circle key={point.id} className="rhine-chart__point" cx={x(index)} cy={y(point.value)} r={3}><title>{point.label}：{point.value} {context.unit}</title></circle>)}
+      </svg>
+      <div className="rhine-chart__range"><span>{points[0]?.label}</span><span>{points.at(-1)?.label}</span></div>
+      <p className="rhine-chart__legend"><span aria-hidden="true" />{context.label} · × 表示缺失；折线在缺失处断开。</p>
+      <p id={`${id}-inspection`} className="rhine-chart__inspection" aria-live="polite" aria-atomic="true">{activePoint ? `${activePoint.label}：${format(activePoint.value)}${known(activePoint.value) ? ` ${context.unit}` : ''}` : '聚焦图形后用左右键、Home / End 查看采样；也可悬停或轻触。'}</p>
+    </>}
+    <details className="rhine-chart__data"><summary>查看{context.label}数据表</summary><DataTable caption={`${context.label}原始采样`} rows={points} rowKey={point => point.id} columns={[
+      { key: 'label', header: '时段', render: point => point.label }, { key: 'value', header: `值（${context.unit}）`, render: point => known(point.value) ? point.value : '未知' },
+    ]} /></details>
+  </ChartFrame>;
+}
+
+export interface ChartPart extends ChartPoint { tone?: 1 | 2 | 3 | 4 }
+export interface StackedBarProps extends ChartContext { parts: ChartPart[] }
+export function StackedBar({ parts, ...context }: StackedBarProps) {
+  const incomplete = parts.some(part => !known(part.value)), invalid = parts.some(part => known(part.value) && part.value < 0);
+  const total = parts.reduce((sum, part) => sum + (known(part.value) ? part.value : 0), 0);
+  const complete = parts.length > 0 && !incomplete && !invalid && Number.isFinite(total) && total > 0;
+  return <ChartFrame {...context}>
+    {complete ? <div className="rhine-chart__stack" role="img" aria-label={`${context.label}：${parts.map(part => `${part.label} ${part.value} ${context.unit}`).join('；')}。完整比例见图例。`}>
+      {parts.map((part, index) => part.value! > 0 && <span key={part.id} data-tone={part.tone ?? index % 4 + 1} style={{ flexGrow: part.value! / total } as CSSProperties} />)}
+    </div> : <p role="status">{invalid ? '包含负数，无法绘制占比。' : incomplete ? '总量未知，不计算占比。' : total === 0 && parts.length ? '已知总量为 0，无占比。' : '暂无可绘制的占比。'}</p>}
+    <ul className="rhine-chart__parts" aria-label={`${context.label}图例`}>{parts.map((part, index) => <li key={part.id}><span aria-hidden="true" data-tone={part.tone ?? index % 4 + 1} />{part.label}：{context.valueFormatter ? context.valueFormatter(known(part.value) ? part.value : null) : known(part.value) ? part.value : '未知'}{known(part.value) ? ` ${context.unit}` : ''}{complete ? `（${(part.value! / total * 100).toFixed(1)}%）` : ''}</li>)}</ul>
+  </ChartFrame>;
+}