@linhey/rhine-design 0.6.0 → 0.9.0

package/components/Overlays.tsx

@@ -7,6 +7,10 @@ import * as TooltipBase from '@radix-ui/react-tooltip';
 import { Button, Notice } from './components';
 import { IconButton } from './Actions';
 import './drawer-placement.css';
+import './dialog-settings.css';
+import { useFloatingScale, useFloatingSide } from './useFloatingScale';
+
+const dialogDismiss = new WeakMap<Element, () => void>();
 
 // Keep portal content inside the root theme so tokens and reduced-motion overrides inherit.
 function useScope() {
@@ -15,17 +19,36 @@ function useScope() {
   useLayoutEffect(() => { setContainer((ref.current?.closest('.rhine-theme') as HTMLElement) || document.body); }, []);
   return { ref, container };
 }
-export interface DialogProps { trigger: ReactElement; title: string; description: string; children: ReactNode; open?: boolean; onOpenChange?: (open: boolean) => void; sidePanel?: ReactNode | ((closeButton: ReactElement) => ReactNode) }
+export interface DialogProps { trigger: ReactElement; title: string; description: string; children: ReactNode; open?: boolean; onOpenChange?: (open: boolean) => void; navigation?: ReactNode; sidePanel?: ReactNode | ((closeButton: ReactElement) => ReactNode); onCloseAutoFocus?: (event: Event) => void }
 export function Dialog(props: DialogProps) {
   return <DialogFrame {...props}/>;
 }
-export function Drawer(props: Omit<DialogProps, 'sidePanel'> & { side?: 'left' | 'right' }) { return <DialogFrame {...props} drawer />; }
-function DialogFrame({ trigger, title, description, children, open, onOpenChange, sidePanel, drawer = false, side = 'right' }: DialogProps & { drawer?: boolean; side?: 'left' | 'right' }) {
+export function Drawer(props: Omit<DialogProps, 'sidePanel' | 'navigation'> & { side?: 'left' | 'right' }) { return <DialogFrame {...props} drawer />; }
+function DialogFrame({ trigger, title, description, children, open, onOpenChange, sidePanel, navigation, onCloseAutoFocus, drawer = false, side = 'right' }: DialogProps & { drawer?: boolean; side?: 'left' | 'right' }) {
   const { ref, container } = useScope();
+  const [localOpen, setLocalOpen] = useState(false);
+  const [content, setContent] = useState<HTMLDivElement | null>(null);
+  const changeOpen = (next: boolean) => { setLocalOpen(next); onOpenChange?.(next); };
+  useLayoutEffect(() => {
+    if (!content) return;
+    dialogDismiss.set(content, () => { setLocalOpen(false); onOpenChange?.(false); });
+    return () => { dialogDismiss.delete(content); };
+  }, [content, onOpenChange]);
+  const escape = (event: KeyboardEvent) => {
+    if (event.defaultPrevented || !(event.target instanceof Element)) return;
+    const owner = event.target.closest('[role="dialog"], [role="alertdialog"], [role="menu"], [role="listbox"]');
+    if (!owner || owner === content) return;
+    // Radix's top layer may lag a newly focused nested dialog until its passive
+    // effect runs. Redirect only that stale callback; keep Tooltip/Menu priority.
+    event.preventDefault();
+    dialogDismiss.get(owner)?.();
+  };
   const sideNavigation = typeof sidePanel === 'function';
+  const settings = navigation != null && navigation !== false;
+  if (settings && sidePanel) throw new Error('Dialog navigation and sidePanel are mutually exclusive.');
   const closeButton = <DialogBase.Close asChild><IconButton label={drawer ? '关闭抽屉' : '关闭对话框'} icon="close" /></DialogBase.Close>;
-  return <span className="rhine-overlay-anchor" ref={ref}><DialogBase.Root open={open} onOpenChange={onOpenChange}><DialogBase.Trigger asChild>{trigger}</DialogBase.Trigger><DialogBase.Portal container={container}>
-    <DialogBase.Overlay className="rhine-overlay" /><DialogBase.Content data-side={drawer ? side : undefined} className={`rhine-dialog${drawer ? ' rhine-drawer' : ''}${sidePanel ? ' rhine-dialog--split' : ''}${sideNavigation ? ' rhine-dialog--side-navigation' : ''}`}><div className="rhine-dialog__main"><div className="rhine-dialog__head"><DialogBase.Title className="rhine-text rhine-text--section">{title}</DialogBase.Title>{!sideNavigation && closeButton}</div><DialogBase.Description className="rhine-text rhine-text--body rhine-text--muted">{description}</DialogBase.Description><div className="rhine-dialog__body">{children}</div></div>{sidePanel && <div className="rhine-dialog__side">{typeof sidePanel === 'function' ? sidePanel(closeButton) : sidePanel}</div>}</DialogBase.Content>
+  return <span className="rhine-overlay-anchor" ref={ref}><DialogBase.Root open={open ?? localOpen} onOpenChange={changeOpen}><DialogBase.Trigger asChild>{trigger}</DialogBase.Trigger><DialogBase.Portal container={container}>
+    <DialogBase.Overlay className="rhine-overlay" /><DialogBase.Content ref={setContent} onEscapeKeyDown={escape} onCloseAutoFocus={onCloseAutoFocus} data-side={drawer ? side : undefined} className={`rhine-dialog${drawer ? ' rhine-drawer' : ''}${settings ? ' rhine-dialog--settings' : ''}${sidePanel ? ' rhine-dialog--split' : ''}${sideNavigation ? ' rhine-dialog--side-navigation' : ''}`}><div className="rhine-dialog__main"><div className="rhine-dialog__head"><DialogBase.Title className="rhine-text rhine-text--section">{title}</DialogBase.Title>{!sideNavigation && closeButton}</div><DialogBase.Description className="rhine-text rhine-text--body rhine-text--muted">{description}</DialogBase.Description><div className="rhine-dialog__body">{settings ? <div className="rhine-dialog__settings-grid"><div className="rhine-dialog__navigation">{navigation}</div><div className="rhine-dialog__settings-content">{children}</div></div> : children}</div></div>{sidePanel && <div className="rhine-dialog__side">{typeof sidePanel === 'function' ? sidePanel(closeButton) : sidePanel}</div>}</DialogBase.Content>
   </DialogBase.Portal></DialogBase.Root></span>;
 }
 export function ConfirmDialog({ trigger, title, description, confirmLabel = '确认操作', danger = false, onConfirm }: { trigger: ReactElement; title: string; description: string; confirmLabel?: string; danger?: boolean; onConfirm: () => Promise<void> | void }) {
@@ -47,14 +70,20 @@ export function ConfirmDialog({ trigger, title, description, confirmLabel = '确
 interface OverlayControl { open?: boolean; onOpenChange?: (open: boolean) => void; side?: 'top' | 'right' | 'bottom' | 'left' }
 export function Popover({ trigger, title, children, open, onOpenChange, side }: OverlayControl & { trigger: ReactElement; title: string; children: ReactNode }) {
   const { ref, container } = useScope();
-  return <span className="rhine-overlay-anchor" ref={ref}><PopoverBase.Root open={open} onOpenChange={onOpenChange}><PopoverBase.Trigger asChild>{trigger}</PopoverBase.Trigger><PopoverBase.Portal container={container}><PopoverBase.Content className="rhine-popover" aria-label={title} side={side} sideOffset={8} collisionPadding={12}><div className="rhine-dialog__head"><strong>{title}</strong><PopoverBase.Close asChild><IconButton label="关闭详情" icon="close" /></PopoverBase.Close></div>{children}</PopoverBase.Content></PopoverBase.Portal></PopoverBase.Root></span>;
+  const floatingRef = useFloatingScale(undefined, 'popover');
+  const floatingSide = useFloatingSide(ref, side, 300);
+  return <span className="rhine-overlay-anchor" ref={ref}><PopoverBase.Root open={open} onOpenChange={onOpenChange}><PopoverBase.Trigger asChild>{trigger}</PopoverBase.Trigger><PopoverBase.Portal container={container}><PopoverBase.Content ref={floatingRef} className="rhine-popover" aria-label={title} side={floatingSide} sideOffset={8} collisionPadding={12}><div className="rhine-dialog__head"><strong>{title}</strong><PopoverBase.Close asChild><IconButton label="关闭详情" icon="close" /></PopoverBase.Close></div>{children}</PopoverBase.Content></PopoverBase.Portal></PopoverBase.Root></span>;
 }
 export interface MenuItem { id: string; label: string; disabled?: boolean; danger?: boolean; onSelect: () => void }
 export function Menu({ trigger, label, items, open, onOpenChange, side }: OverlayControl & { trigger: ReactElement; label: string; items: MenuItem[] }) {
   const { ref, container } = useScope();
-  return <span className="rhine-overlay-anchor" ref={ref}><MenuBase.Root open={open} onOpenChange={onOpenChange}><MenuBase.Trigger asChild>{trigger}</MenuBase.Trigger><MenuBase.Portal container={container}><MenuBase.Content className="rhine-menu" aria-label={label} side={side} sideOffset={8} collisionPadding={12}>{items.map(item => <MenuBase.Item key={item.id} disabled={item.disabled} onSelect={item.onSelect} className="rhine-menu__item" data-danger={item.danger}>{item.label}</MenuBase.Item>)}</MenuBase.Content></MenuBase.Portal></MenuBase.Root></span>;
+  const floatingRef = useFloatingScale(undefined, 'dropdown-menu');
+  const floatingSide = useFloatingSide(ref, side, 180);
+  return <span className="rhine-overlay-anchor" ref={ref}><MenuBase.Root open={open} onOpenChange={onOpenChange}><MenuBase.Trigger asChild>{trigger}</MenuBase.Trigger><MenuBase.Portal container={container}><MenuBase.Content ref={floatingRef} className="rhine-menu" aria-label={label} side={floatingSide} sideOffset={8} collisionPadding={12}>{items.map(item => <MenuBase.Item key={item.id} disabled={item.disabled} onSelect={item.onSelect} className="rhine-menu__item" data-danger={item.danger}>{item.label}</MenuBase.Item>)}</MenuBase.Content></MenuBase.Portal></MenuBase.Root></span>;
 }
 export function Tooltip({ children, content, open, onOpenChange, side }: OverlayControl & { children: ReactElement; content: string }) {
   const { ref, container } = useScope();
-  return <span className="rhine-overlay-anchor" ref={ref}><TooltipBase.Provider delayDuration={300}><TooltipBase.Root open={open} onOpenChange={onOpenChange}><TooltipBase.Trigger asChild>{children}</TooltipBase.Trigger><TooltipBase.Portal container={container}><TooltipBase.Content className="rhine-tooltip" side={side} sideOffset={8} collisionPadding={12}>{content}</TooltipBase.Content></TooltipBase.Portal></TooltipBase.Root></TooltipBase.Provider></span>;
+  const floatingRef = useFloatingScale(undefined, 'tooltip');
+  const floatingSide = useFloatingSide(ref, side, 280);
+  return <span className="rhine-overlay-anchor" ref={ref}><TooltipBase.Provider delayDuration={300}><TooltipBase.Root open={open} onOpenChange={onOpenChange}><TooltipBase.Trigger asChild>{children}</TooltipBase.Trigger><TooltipBase.Portal container={container}><TooltipBase.Content ref={floatingRef} className="rhine-tooltip" side={floatingSide} sideOffset={8} collisionPadding={12}>{content}</TooltipBase.Content></TooltipBase.Portal></TooltipBase.Root></TooltipBase.Provider></span>;
 }

package/components/README.md

@@ -2,7 +2,9 @@
 
 本目录提供[莱茵设计 · Rhine Design](../README.md)的 React 组件、设计变量和 API 契约。组件接收应用传入的数据与动作，不绑定特定后端或原生平台。包名为`@linhey/rhine-design`；样式变量和类名使用`rhine-`命名空间。
 
-0.6.0 共60个组件；0.5.0为59个，0.4.0为48个，0.3.0为40个。新增导航、表单流程及健康时间轴组件见[场景与交互规范](../docs/INTERACTION_PATTERNS.md)，原24个扩展组件见[常用组件契约](./COMMON_COMPONENTS.md)。[字体与文字规范](./TYPOGRAPHY.md)与[主流系统对照与缺口](../docs/DESIGN_SYSTEM_AUDIT.md)共同约束复用。静态页面样稿也使用同源Toolbar/Select CSS，不运行React。
+0.8.0 共66个组件，新增 NeutronStarBackdrop、StatusTimelineList、AppShellToggle 与 ButtonLink；0.6.0 为60个；0.5.0为59个，0.4.0为48个，0.3.0为40个。新增导航、表单流程及健康时间轴组件见[场景与交互规范](../docs/INTERACTION_PATTERNS.md)，原24个扩展组件见[常用组件契约](./COMMON_COMPONENTS.md)。[字体与文字规范](./TYPOGRAPHY.md)与[主流系统对照与缺口](../docs/DESIGN_SYSTEM_AUDIT.md)共同约束复用。静态页面样稿也使用同源Toolbar/Select CSS，不运行React。
+
+中子星艺术、主题物品和生命周期见[中子星契约](../docs/NEUTRON_STAR_BACKDROP.md)与[轨道背景契约](../docs/ORBIT_BACKDROP.md)。安装版本与源码导出分别核对。
 
 页面改动遵循：优先复用组件 → 先在设计稿/展台修改并验证 → 再按任务授权实现到App。缺组件先补组件与展台，不在业务页另写同用途样式；同一任务已授权设计和实现时连续推进，无需重复确认。
 
@@ -51,14 +53,16 @@ export function Example() {
 | 组件 | 关键输入 | 状态与边界 |
 | --- | --- | --- |
 | Button | variant=primary/secondary/quiet/danger；busy；busyLabel；原生按钮属性 | 默认 type=button；busy 保留焦点并拦截再次 click，不自动把业务标记成功；disabled 使用原生禁用 |
+| ButtonLink（0.8.0） | 必填 href；原生 anchor 属性与 ref；Button 同款 variant/busy/busyLabel；disabled | 原生导航/下载；disabled 退出 Tab；busy 保焦点；两者移除 href、阻止主/辅助点击；[契约](../docs/COMPACT_ACCOUNT_PATTERNS.md) |
 | Logo | variant=mark/icon/lockup；theme=light/dark/auto；size；animate；decorative；label；wordmark | 第三版三角构架；默认静态、48px、浅色单标志；最小16px；无点击/业务状态 |
 | Text | variant；as；tone；numeric；HTML属性 | 默认p/body；视觉层级不决定HTML语义；长文本可换行；不转换数值或截断文本 |
 | Select | label；hint；error；原生单选select属性；option子节点 | 标签与描述自动关联；原生菜单和键盘；受控或defaultValue；不支持multiple/size列表模式；箭头装饰性且不接收点击 |
 | Toolbar | title；description；children；HTML div属性 | 自适应控件组合，role=group与普通Tab顺序；不伪装为需要方向键导航的ARIA toolbar；不含业务状态 |
+| ListFilterBar（0.9.0） | label；search；primary/filters 字段；onReset；refresh；一个 action；result/pending/error | 最多两个常显条件，超出项进入同一 Drawer；宿主维护即时状态、查询和权限；[契约与版本边界](../docs/LIST_FILTER_BAR.md) |
 | Badge | tone=neutral/success/warning/error；children | 只读短状态，颜色必须配文字，不做可点击按钮 |
 | Surface | HTML div 属性 | 静态分区，无点击语义；不是弹窗或导航 |
 | Background（0.5.0） | roleTone=canvas/content/sidebar/surface/overlay/media；decoration=auto/theme/none；appearance={color,textColor,texture,textureSize}；HTML div 属性 | 默认正文纯色；仅画布默认使用主题纹理；局部覆盖不创建主题根或定位上下文；完整配置见[场景背景](../docs/THEMING.md#场景背景050) |
-| SelectionCard | label；selected；onSelectedChange；disabled；children | 原生 checkbox 可取消；是否单选由上层控制；内部不嵌套按钮/链接/其他输入 |
+| SelectionCard | label；selected；onSelectedChange；disabled；showIndicator=true；children | 原生 checkbox 可取消；是否单选由上层控制；showIndicator=false 仅视觉隐藏勾选框，保留键盘与读屏，卡片边界表达选中；内部不嵌套按钮/链接/其他输入 |
 | TextField | label；hint；error；原生 input 属性 | label 与 id 自动关联；错误与提示组成 aria-describedby；输入值由调用方管理 |
 | Tabs | label；items[{value,label,content,disabled?}]；value；onValueChange | value 必须指向有效可用项；唯一 value；左右/Home/End，跳过禁用项；隐藏面板保留挂载但退出可访问树 |
 | SegmentedControl | label；items[{value,label,disabled?}]；value；onValueChange | 原生 radio，独立 name 防多组干扰；方向键和禁用行为由浏览器提供 |
@@ -70,6 +74,8 @@ export function Example() {
 
 新增24项API与组合示例见[常用组件契约](./COMMON_COMPONENTS.md)。TextField封装单行输入，Select使用原生单选；需要查询候选时用Combobox。复杂浮层采用Radix Dialog、AlertDialog、Popover、DropdownMenu、Tooltip的无样式基础，莱茵设计提供视觉与动效。Toast只处理单条通知；不加入全局队列、表格引擎、图表包或业务数据层。
 
+0.8.0 的 `StatusTimelineList` 与 `TimelineLegend compact/items` 提供紧凑历史组合及一行短图例；宿主传入完整规则，悬停/聚焦/点按查看。无参 TimelineLegend 仍兼容既有标签。真实样机 `/#compact-account` 同时验证无框额度摘要、配对事实与渐进展示的凭证操作，见[紧凑组合规范](../docs/COMPACT_ACCOUNT_PATTERNS.md)。npm 0.6.0 不提供这些扩展。
+
 浏览状态不等于执行结果；页面使用宿主的真实状态决定selected/busy/notice，视觉反馈不能提前宣称业务完成。
 
 ## 动效规范
@@ -151,6 +157,25 @@ export function Example() {
 
 新增 `Background` 与 `AppShell`，0.5.0 共 59 个组件；npm 0.4.0 仍为 48 个。Background 支持六类 roleTone、auto/theme/none 装饰策略及 appearance 局部覆盖；AppShell 提供组合展台使用的固定顶部操作区与响应式侧栏。完整 API、最小接入、背景滚动及 Portal 边界见[背景与应用外壳契约](../docs/APPLICATION_COMPONENTS.md)。
 
+0.8.0 新增可选 `AppShell.contentHeader`：工作区导航常驻正文列顶部，正文独立滚动；组合现有 `AppShellToggle`、`Inline`、标题与操作。0.8.0 媒体组件同步更新主题边界：卡片、标签、查看器工具栏与信息栏跟随宿主主题，仅媒体画布保持中性。以上不包含于 npm 0.6.0，交互与验证边界见[应用组件契约](../docs/APPLICATION_COMPONENTS.md)。
+
 ## 轨道背景（0.6.0）
 
-`OrbitBackdrop` 接收 `HTMLAttributes<HTMLDivElement>` 和 `reducedMotion?: boolean`，包含可选 `children`。它提供固定深色轨道艺术与内置暂停 / 继续按钮，Canvas 为 `aria-hidden` 装饰。系统、显式减少动态、祖先偏好、窄窗、页面隐藏、离屏及零尺寸时停帧；恢复沿冻结时间继续，不追赶。Canvas 不可用时保留静态艺术与内容。宿主只组合布局，不复制动画或覆盖组件状态。完整生命周期、主题及接入约束见[轨道背景契约](../docs/ORBIT_BACKDROP.md)，真实组件展台为 `/#orbit`。自 0.6.0 起共 60 个组件。
+`OrbitBackdrop` 自 0.6.0 提供，接收 `HTMLAttributes<HTMLDivElement>` 和 `reducedMotion?: boolean`，包含可选 `children`。0.6.0 提供固定深色轨道艺术与内置暂停 / 继续按钮，Canvas 为 `aria-hidden` 装饰。系统、显式减少动态、祖先偏好、窄窗、页面隐藏、离屏及零尺寸时停帧；恢复沿冻结时间继续，不追赶。Canvas 不可用时保留静态艺术与内容。宿主只组合布局，不复制动画或覆盖组件状态。完整生命周期、主题及接入约束见[轨道背景契约](../docs/ORBIT_BACKDROP.md)，真实组件展台为 `/#orbit`。自 0.6.0 起共 60 个组件。
+
+0.8.0 新增 `appearance?: 'theme' | 'original'`：莱茵展示暖白纸纹、浅绿折面、轻微振翅与悬浮纸屑的折纸鸟；战术展示带倒角晶面、矿物纹理、琥珀裂纹与漂浮碎片的源石晶簇；橙趣展示有烘焙纹理、糖霜、糖针与糖尘的草莓甜甜圈。三套物品按需加载 Three.js，窄屏可播放，遵循同一暂停、减少动态、隐藏与离屏规则；WebGL 失败回退 Canvas2D，Canvas 不可用时使用本地 SVG。`original` 保留初版完整深色轨道。切换主题复用时钟和绘制器，保留暂停与内容草稿。详见[轨道背景契约](../docs/ORBIT_BACKDROP.md)。
+
+0.8.0 新增 `AppShellToggle` 与 `AppShell.controls="inline"`。品牌区/正文区成对放置与可达性要求见[内联控制契约](../docs/APPLICATION_COMPONENTS.md#内联控制按钮080)。
+## 中子星背景（0.8.0）
+
+`NeutronStarBackdrop` 接收 `HTMLAttributes<HTMLDivElement>`、`reducedMotion?: boolean`、`appearance?: 'theme' | 'original'` 和可选 `children`。默认从当前主题取得艺术配色，`original` 保留原始深空；切换颜色不重置时间，实体内容控件仍用宿主主题。按需加载 Three.js，保留 28 条磁场线、560 个流粒、700 颗星尘、极向喷流与星核；星系以 28 秒有效播放时间完成一轮深度公转，镜头保持固定。
+
+内置暂停 / 继续；系统、显式和祖先减少动态、隐藏、离屏或零尺寸停帧，恢复不追赶。SSR 不访问浏览器绘制环境，异步初始化晚于卸载时不创建渲染器；无 WebGL、导入失败或 context lost 保留静态艺术和业务内容，context restored 按当前偏好恢复，卸载释放监听、帧循环及 GPU 资源。宿主负责尺寸和普通内容布局，正文不模糊；不以装饰状态控制业务。完整用法与验收见[中子星背景契约](../docs/NEUTRON_STAR_BACKDROP.md)，真实源码展台为 `/#neutron-star`。
+
+内容层只预留底部 `44px + 2 × --rhine-space-4` 控件安全区，不强制正文四边 padding；宿主在自己的 Stack 或页面容器设置边距，避免重复叠加。静态 fallback 保留当前配色的星核、磁场意图，不保证与三维画面逐像素一致。
+
+## 0.8.0 补充
+
+- [浮层缩放与边界](../docs/FLOATING_OVERLAYS.md)：Popover、Menu、Tooltip 与时间轴共享 CSS zoom 修正。
+- [设置 Dialog](../docs/SETTINGS_DIALOG.md)：`navigation` 插槽及窄窗/缩放重排。
+- [主题选择](../docs/THEME_PICKER.md)：`ThemePicker` / `ThemePreview`，候选源码新增两项组件至 66；旧版安装包仍按自身导出判断。

package/components/StatusTimeline.tsx

@@ -1,5 +1,6 @@
-import { useId, useLayoutEffect, useRef, useState } from 'react';
+import { useEffect, useId, useLayoutEffect, useRef, useState, type RefObject } from 'react';
 import * as PopoverBase from '@radix-ui/react-popover';
+import { useFloatingScale } from './useFloatingScale';
 import { Text } from './Typography';
 import { KeyValue } from './Data';
 import { Button } from './components';
@@ -18,6 +19,17 @@ export interface StatusTimelineProps {
 }
 export const timelineLabels: Record<TimelineStatus, string> = { healthy: '有输出·未见异常', recovered: '重试已恢复', degraded: '异常·结果待确认', failed: '存在最终失败', unknown: '未知 / 无数据' };
 
+function useTimelineHoverExit(trigger: RefObject<HTMLElement | null>, popup: RefObject<HTMLDivElement | null>, close: () => void) {
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const cancel = () => { clearTimeout(timer.current); timer.current = undefined; };
+  const leave = () => { cancel(); timer.current = setTimeout(() => {
+    const keyboardFocus = document.activeElement === trigger.current && trigger.current?.matches(':focus-visible');
+    if (!keyboardFocus && !popup.current?.contains(document.activeElement)) close();
+  }, 150); };
+  useEffect(() => cancel, []);
+  return { cancel, leave };
+}
+
 /** Host supplies ordered, validated evidence; this component never computes a health score. */
 export function StatusTimeline({ label, segments, startLabel, endLabel, compact = false, disabled = false, activeId, defaultActiveId, onActiveChange, open: controlledOpen, defaultOpen = false, onOpenChange }: StatusTimelineProps) {
   const [localId, setLocalId] = useState(defaultActiveId);
@@ -25,6 +37,7 @@ export function StatusTimeline({ label, segments, startLabel, endLabel, compact
   const open = controlledOpen ?? localOpen;
   const setOpen = (next: boolean) => { if (disabled && next) return; if (controlledOpen === undefined) setLocalOpen(next); if (next !== open) onOpenChange?.(next); };
   const root = useRef<HTMLDivElement>(null), slider = useRef<HTMLInputElement>(null), popup = useRef<HTMLDivElement>(null), returning = useRef(false), focusDetail = useRef(false);
+  const detailHadFocus = useRef(false);
   useLayoutEffect(() => { setContainer(root.current?.closest<HTMLElement>('.rhine-theme') ?? document.body); }, []);
   const detailId = useId();
   const matched = segments.findIndex(item => item.id === (activeId ?? localId));
@@ -33,7 +46,11 @@ export function StatusTimeline({ label, segments, startLabel, endLabel, compact
   const segment = segments[selected];
   const summary = segment ? `${segment.label} · ${timelineLabels[segment.status]}` : '暂无记录';
   const hasPopup = !disabled && !!segment && (compact || !!segment.detail);
-  return <div ref={root} className={`rhine-timeline${compact ? ' rhine-timeline--compact' : ''}`}>
+  const attachPopup = useFloatingScale(popup);
+  const hover = useTimelineHoverExit(slider, popup, () => setOpen(false));
+  return <div ref={root} className={`rhine-timeline${compact ? ' rhine-timeline--compact' : ''}`}
+    onPointerEnter={hover.cancel}
+    onPointerLeave={event => { if (event.pointerType === 'mouse' && !(event.relatedTarget instanceof Node && popup.current?.contains(event.relatedTarget))) hover.leave(); }}>
     <PopoverBase.Root open={open && hasPopup} onOpenChange={setOpen}><PopoverBase.Anchor asChild><div className="rhine-timeline__track">
       <div className="rhine-timeline__bars" aria-hidden="true">{segments.map((item, i) => <span key={item.id} data-status={item.status} data-selected={i === selected} />)}</div>
       <input ref={slider} type="range" min={0} max={Math.max(0, segments.length - 1)} value={Math.max(0, selected)} disabled={disabled || !segments.length}
@@ -47,8 +64,12 @@ export function StatusTimeline({ label, segments, startLabel, endLabel, compact
         onChange={event => { select(Number(event.target.value)); setOpen(true); }}
         onPointerDown={() => setOpen(true)}
         onPointerMove={event => { if (disabled || event.pointerType !== 'mouse' || !segments.length) return; const rect = event.currentTarget.getBoundingClientRect(); if (rect.width) select(Math.min(segments.length - 1, Math.max(0, Math.floor((event.clientX - rect.left) / rect.width * segments.length)))); setOpen(true); }} />
-    </div></PopoverBase.Anchor><PopoverBase.Portal container={container}><PopoverBase.Content ref={popup} id={`${detailId}-popup`} className="rhine-timeline-popover" side="top" sideOffset={8} collisionPadding={12} aria-label={`${label}时段详情`}
-      onOpenAutoFocus={event => { event.preventDefault(); if (focusDetail.current) { focusDetail.current = false; popup.current?.querySelector<HTMLButtonElement>('button')?.focus(); } }} onCloseAutoFocus={event => { event.preventDefault(); focusDetail.current = false; if (document.activeElement === document.body || popup.current?.contains(document.activeElement)) { returning.current = true; slider.current?.focus(); } }}
+    </div></PopoverBase.Anchor><PopoverBase.Portal container={container}><PopoverBase.Content ref={attachPopup} id={`${detailId}-popup`} className="rhine-timeline-popover" side="top" sideOffset={8} collisionPadding={12} aria-label={`${label}时段详情`}
+      onPointerEnter={hover.cancel}
+      onPointerLeave={event => { if (event.pointerType === 'mouse' && !(event.relatedTarget instanceof Node && root.current?.contains(event.relatedTarget))) hover.leave(); }}
+      onFocusCapture={() => { detailHadFocus.current = true; }}
+      onBlurCapture={event => { if (event.relatedTarget && event.relatedTarget !== document.body && !event.currentTarget.contains(event.relatedTarget)) detailHadFocus.current = false; }}
+      onOpenAutoFocus={event => { event.preventDefault(); if (focusDetail.current) { focusDetail.current = false; popup.current?.querySelector<HTMLButtonElement>('button')?.focus(); } }} onCloseAutoFocus={event => { event.preventDefault(); focusDetail.current = false; if (detailHadFocus.current && (document.activeElement === document.body || popup.current?.contains(document.activeElement))) { returning.current = true; slider.current?.focus(); } detailHadFocus.current = false; }}
       onInteractOutside={event => { if (root.current?.contains(event.target as Node)) event.preventDefault(); }}>
       <div className="rhine-dialog__head"><strong>{summary}</strong><PopoverBase.Close asChild><Button variant="quiet" aria-label="关闭时段详情">关闭</Button></PopoverBase.Close></div>
       {segment?.detail && <><KeyValue items={[
@@ -62,6 +83,51 @@ export function StatusTimeline({ label, segments, startLabel, endLabel, compact
   </div>;
 }
 
-export function TimelineLegend() {
-  return <ul className="rhine-timeline__legend" aria-label="健康记录图例">{Object.entries(timelineLabels).map(([status, label]) => <li key={status}><span data-status={status} aria-hidden="true"/>{label}</li>)}</ul>;
+export interface TimelineLegendItem { status: TimelineStatus; label: string; description?: string }
+export interface TimelineLegendProps { label?: string; compact?: boolean; items?: TimelineLegendItem[] }
+const defaultLegendItems: TimelineLegendItem[] = Object.entries(timelineLabels).map(([status, label]) => ({ status: status as TimelineStatus, label }));
+
+/** Short labels describe evidence; hosts provide the precise rules rather than relying on color. */
+export function TimelineLegend({ label = '健康记录图例', compact = false, items = defaultLegendItems }: TimelineLegendProps) {
+  const root = useRef<HTMLUListElement>(null);
+  const [container, setContainer] = useState<HTMLElement>();
+  const [active, setActive] = useState<TimelineStatus | null>(null);
+  useLayoutEffect(() => { setContainer(root.current?.closest<HTMLElement>('.rhine-theme') ?? document.body); }, []);
+  useEffect(() => { if (active && !items.some(item => item.status === active && item.description)) setActive(null); }, [active, items]);
+  return <ul ref={root} className={`rhine-timeline__legend${compact ? ' rhine-timeline__legend--compact' : ''}`} aria-label={label}>
+    {items.map(item => <LegendItem key={item.status} item={item} container={container} open={active === item.status}
+      onOpenChange={next => setActive(current => next ? item.status : current === item.status ? null : current)} />)}
+  </ul>;
+}
+
+function LegendItem({ item, container, open, onOpenChange }: { item: TimelineLegendItem; container?: HTMLElement; open: boolean; onOpenChange: (open: boolean) => void }) {
+  const id = useId(), trigger = useRef<HTMLButtonElement>(null), popup = useRef<HTMLDivElement>(null), returning = useRef(false);
+  const detailHadFocus = useRef(false);
+  const hover = useTimelineHoverExit(trigger, popup, () => onOpenChange(false));
+  const attachPopup = useFloatingScale(popup);
+  const marker = <span data-status={item.status} aria-hidden="true" />;
+  if (!item.description) return <li>{marker}{item.label}</li>;
+  return <li><PopoverBase.Root open={open} onOpenChange={onOpenChange}><PopoverBase.Anchor asChild>
+    <button ref={trigger} type="button" className="rhine-timeline__legend-trigger" aria-haspopup="dialog" aria-expanded={open} aria-controls={open ? id : undefined}
+      onFocus={() => { if (!returning.current) onOpenChange(true); returning.current = false; }}
+      onClick={() => onOpenChange(true)}
+      onPointerEnter={event => { if (event.pointerType === 'mouse') { hover.cancel(); onOpenChange(true); } }}
+      onPointerLeave={event => { if (event.pointerType === 'mouse' && !(event.relatedTarget instanceof Node && popup.current?.contains(event.relatedTarget))) hover.leave(); }}
+      onKeyDown={event => {
+        if (event.key === 'Escape' && open) { event.preventDefault(); event.stopPropagation(); onOpenChange(false); }
+        if ((event.key === 'Enter' || event.key === ' ') && open) { event.preventDefault(); popup.current?.querySelector<HTMLButtonElement>('button')?.focus(); }
+      }}>
+      {marker}{item.label}
+    </button>
+  </PopoverBase.Anchor><PopoverBase.Portal container={container}><PopoverBase.Content ref={attachPopup} id={id} className="rhine-timeline-popover" aria-label={`${item.label}规则`} side="top" sideOffset={8} collisionPadding={12}
+    onFocusCapture={() => { detailHadFocus.current = true; }}
+    onBlurCapture={event => { if (event.relatedTarget && event.relatedTarget !== document.body && !event.currentTarget.contains(event.relatedTarget)) detailHadFocus.current = false; }}
+    onOpenAutoFocus={event => event.preventDefault()}
+    onCloseAutoFocus={event => { event.preventDefault(); if (detailHadFocus.current && (popup.current?.contains(document.activeElement) || document.activeElement === document.body)) { returning.current = true; trigger.current?.focus(); } detailHadFocus.current = false; }}
+    onInteractOutside={event => { if (event.target === trigger.current || trigger.current?.contains(event.target as Node)) event.preventDefault(); }}
+    onPointerEnter={hover.cancel}
+    onPointerLeave={event => { if (event.pointerType === 'mouse' && !(event.relatedTarget instanceof Node && trigger.current?.contains(event.relatedTarget))) hover.leave(); }}>
+    <div className="rhine-dialog__head"><strong>{item.label}</strong><PopoverBase.Close asChild><Button variant="quiet" aria-label={`关闭${item.label}规则`}>关闭</Button></PopoverBase.Close></div>
+    <Text>{item.description}</Text>
+  </PopoverBase.Content></PopoverBase.Portal></PopoverBase.Root></li>;
 }

package/components/StatusTimelineList.tsx

@@ -0,0 +1,38 @@
+import { useEffect, useState, type ReactNode } from 'react';
+import { Text } from './Typography';
+import { StatusTimeline, type StatusTimelineProps } from './StatusTimeline';
+
+export interface StatusTimelineItem {
+  id: string;
+  title: string;
+  summary?: ReactNode;
+  note?: string;
+  timeline: Pick<StatusTimelineProps, 'segments' | 'startLabel' | 'endLabel' | 'disabled'> | null;
+  unavailableLabel?: string;
+}
+export interface StatusTimelineListProps {
+  label: string;
+  items: StatusTimelineItem[];
+  emptyLabel?: string;
+}
+
+/** Hosts supply ordering, summaries and evidence; the list only coordinates presentation. */
+export function StatusTimelineList({ label, items, emptyLabel = '暂无历史记录' }: StatusTimelineListProps) {
+  const [openId, setOpenId] = useState<string | null>(null);
+  useEffect(() => {
+    const item = items.find(item => item.id === openId);
+    if (openId !== null && (!item?.timeline || item.timeline.disabled || !item.timeline.segments.length)) setOpenId(null);
+  }, [items, openId]);
+  if (!items.length) return <Text variant="caption">{emptyLabel}</Text>;
+  return <ul className="rhine-timeline-list" aria-label={label}>
+    {items.map(item => <li className="rhine-timeline-list__item" key={item.id}>
+      <div className="rhine-timeline-list__heading"><Text as="h4" variant="body">{item.title}</Text>
+        {item.summary != null && <Text variant="caption" tone="muted">{item.summary}</Text>}
+      </div>
+      {item.note && <Text variant="caption" tone="muted">{item.note}</Text>}
+      {item.timeline ? <StatusTimeline {...item.timeline} compact label={`${item.title} 历史时段`}
+        open={openId === item.id} onOpenChange={next => setOpenId(current => next ? item.id : current === item.id ? null : current)} />
+        : <Text variant="caption" tone="muted">{item.unavailableLabel ?? '历史记录暂不可用 · 未知'}</Text>}
+    </li>)}
+  </ul>;
+}

package/components/ThemePicker.tsx

@@ -0,0 +1,49 @@
+import { useId, useState } from 'react';
+import { themes, type ThemeName } from './themeMetadata';
+import rhine from './assets/theme-previews/rhine.png?no-inline';
+import arknights from './assets/theme-previews/arknights.png?no-inline';
+import neoBrutalism from './assets/theme-previews/neo-brutalism.png?no-inline';
+import './theme-picker.css';
+
+const sources: Record<ThemeName, string> = { rhine, arknights, 'neo-brutalism': neoBrutalism };
+const descriptions: Record<ThemeName, string> = {
+  rhine: '暖白纸面、苔绿操作与细线边界。',
+  arknights: '深色工作区、明亮信号与切角边界。',
+  'neo-brutalism': '米白表面、亮橙操作与墨色硬阴影。',
+};
+
+export interface ThemePreviewProps { theme: ThemeName; src?: string }
+function PreviewImage({ src }: { src: string }) {
+  const [state, setState] = useState<'loading' | 'ready' | 'error'>('loading');
+  return <span className="rhine-theme-preview" aria-hidden="true" data-state={state}>
+    {state === 'error' ? <span>预览暂不可用</span> : <><img src={src} alt="" width={960} height={600} decoding="async" onLoad={() => setState('ready')} onError={() => setState('error')} />{state === 'loading' && <span className="rhine-theme-preview__loading">正在加载预览</span>}</>}
+  </span>;
+}
+/** Decorative, versioned snapshot; it never mounts a nested ThemeProvider. */
+export function ThemePreview({ theme, src = sources[theme] }: ThemePreviewProps) {
+  return <PreviewImage key={src} src={src} />;
+}
+
+export interface ThemePickerOption {
+  value: ThemeName; label?: string; description?: string; disabled?: boolean; previewSrc?: string;
+}
+export interface ThemePickerProps {
+  label?: string; value: ThemeName; onValueChange: (value: ThemeName) => void;
+  options?: readonly ThemePickerOption[]; disabled?: boolean;
+}
+/** Controlled native radios: the host owns applying and persisting the theme. */
+export function ThemePicker({ label = '界面主题', value, onValueChange, options = themes.map(theme => ({ value: theme.name })), disabled = false }: ThemePickerProps) {
+  const id = useId();
+  return <fieldset className="rhine-theme-picker" disabled={disabled}><legend>{label}</legend>
+    <div className="rhine-theme-picker__options">{options.map(option => {
+      const title = option.label ?? themes.find(theme => theme.name === option.value)!.label;
+      const selected = value === option.value;
+      const descriptionId = `${id}-${option.value}`;
+      return <label className="rhine-theme-option" key={option.value}>
+        <input className="rhine-sr-only" type="radio" name={id} value={option.value} checked={selected} disabled={option.disabled} aria-label={title} aria-describedby={descriptionId} onChange={() => onValueChange(option.value)} />
+        <ThemePreview theme={option.value} src={option.previewSrc} />
+        <span className="rhine-theme-option__copy"><strong>{title}</strong><span className="rhine-theme-option__description" id={descriptionId}>{option.description ?? descriptions[option.value]}</span><span className="rhine-theme-option__status" aria-hidden="true">{selected ? '✓ 已使用' : option.disabled || disabled ? '暂不可用' : '选择应用'}</span></span>
+      </label>;
+    })}</div>
+  </fieldset>;
+}