@linhey/rhine-design 0.11.0 → 0.11.2

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # 版本记录
 
+## 0.11.2（2026-10-28）
+
+#18 设置 Dialog 修复基于精确候选 `02cc2c2`，默认行为保持兼容；正式发布状态以 registry 回读为准。
+
+- settings宽度不再被后置公共CSS覆盖；复用 `height` / `footer`，固定标题/关闭与右对齐底部动作，正文和长导航独立有界滚动。
+- 极窄容器的底部操作间距压缩至 2px，覆盖 400px 带边框 iframe 实际 398px / 200% CSS zoom；保留 44px 点击目标，避免三项短动作仅因边框差值换行挤压正文。
+- `Dialog.description` 可省略，省略时没有说明占位或悬空 `aria-describedby`；普通短 Dialog、Drawer 及 sidePanel 策略保留。
+- 自动高度 footer 按可用视口及祖先 CSS zoom 限制，纯文本有界正文提供命名键盘滚动入口；长操作末项保持可达。
+- 真实展台覆盖30行、长导航/按钮、异步栏目、错误/冲突、嵌套搜索多选与草稿行为；补充生产构建次序、固定 tarball 消费和短屏回归。
+- npm 制品：`@linhey/rhine-design@0.11.2`；消费方仍需固定版本并提交 lockfile。正式发布与 registry 回读见本次发布记录。
+
+## 未发布
+
+- #46：战术主题danger按钮使用可读的深色文字/红底配对（修复原默认约2.77:1文字对比）；Button新增size="standard"（默认）/"large"，补动作语义→variant矩阵和真实并排展台；退出登录不自动等同不可逆删除，large为16/24、至少52px。未包含在0.11.0。
+
+- #41：紧凑选择组合，Button内容两端对齐、Tabs显式content/fill布局（新默认content）、Dialog实例height/footer及内部滚动，草稿预览/保存契约和展台；不进入冻结0.11.0制品。摘要Tabs若需保持旧隐式铺满，显式传layout="fill"。
+
+- #42：TextField 新增 `labelVisibility` 与公开 `TextFieldProps`，默认可见；非空标签、正文级单输入搜索组合及异步/IME展台见[契约](docs/SINGLE_SEARCH.md)。此项不包含在 0.11.0 发布候选中。
+
+- #45：SideNav 支持可选行尾 actions，空动作不占位，复用 Menu/IconButton，提供受控 Dialog 归焦组合与真实展台；不包含在0.11.0中。
+- #43：新增 `ChatThread` / `ChatCard` 聊天组合候选，提供多成员分组、卡片状态与详情、只读动作约束、历史锚点和显式恢复跟随；附三组合成展台及[规范与参考取舍](docs/AGENT_CHAT.md)。不包含模型调用、消费迁移或依赖发布。Button 尊重 `aria-disabled` 并阻止激活，支持保留不可操作控件焦点。
+
+其余候选仍按各自发布记录管理；消费方应固定精确版本并提交 registry lockfile。
+
+## 0.11.1（2026-10-27）
+
+- 补齐嵌套下拉退出到父Modal焦点约束恢复之间的快速Tab保护；连续Shift+Tab不再把焦点留在背景，正常导航恢复后仍可循环。
+
+- 候选列表保持240px上限并按视口缩放约束，避免可用高度反馈；多选内部动作等click完成再收起，避免窄屏缩放中pointerdown/抬起之间位置移动丢失清空。
+
+- 修复 Combobox / RemoteMultiSelect 在祖先 CSS zoom 下的候选浮层定位与视口边界，复用既有浮层缩放处理；保留主题 Portal、搜索、多选与键盘行为。
+- RemoteMultiSelect 可再次点击或方向键+Enter取消已选项，保留真正禁用/锁定项；“完成选择”只收起候选并归焦，不提交宿主表单；支持输入框Tab进入完成、Shift+Tab返回及继续Tab到后继控件；标签×移除和清空后保持收起，输入框Backspace保留原展开态，无可移除项时隐藏清空按钮。
+- `#compact-filters` 补充弹窗内多选与真实浏览器回归；参见[浮层契约](docs/FLOATING_OVERLAYS.md)。
+- 补丁制品从 `v0.11.0` 回补上述修复，主入口仍为67项；本节上方的未发布新功能不包含在0.11.1中。消费方固定版本并提交 registry lockfile。
+
 ## 0.11.0（2026-10-27）
 
 本版本新增产品评审工具及以下已合并能力；npm 0.10.0 不包含这些新增 API。组件主入口仍为 67 项，默认行为保持兼容；消费方固定 0.11.0 并提交 lockfile。实际发布可用性以 registry 为准。

package/CONTRIBUTING.md

@@ -35,6 +35,8 @@ README 面向首次接触项目的开发者，优先解释用途、安装、示
 
 组件 API 变更时，更新契约、示例以及 skill 的 `references/API_MAP.md` 或 `TASK_MAP.md`。索引指向真实源码，不复制第二份 API 定义；skill 的版本信息随包版本更新。
 
+skill 会被单独复制安装，Markdown 相对链接必须留在 `skills/rhine-design/` 内。包根路径使用代码格式；在线契约链接固定提交或版本，并说明与已安装包的关系。运行 `npm test -- tests/SkillInstallation.test.tsx`，在仓库外的临时空目录验证 README 复制安装与独立 skill 安装，检查内部文件/标题链接、越界路径及浮动源码链接。此检查不发网络请求，新增在线快照仍需核对对应远端文件可访问。
+
 展台包版本由 `preview/packageInfo.ts` 从 `package.json` 读取；组件数量只统计 `components/index.ts` 的公开组件，不计类型与独立主题入口。新增导出时同步该数量、README 完整清单与组件入口。发布后的源码新增能力写入 CHANGELOG 的“未发布”部分，并在相关契约标明旧包不包含；不要因为源码仍使用同一版本字段，就将新能力归入已发布版本。历史版本介绍与验收记录保留原时点。
 
 ## 提交 Pull Request

package/README.md

@@ -16,10 +16,10 @@
   <a href="CHANGELOG.md">版本记录</a>
 </p>
 
-Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、管理界面和数据密集型应用。它将设计规范、67 个组件和动效示例放在一起，帮助团队建立一致、可复用的界面语言。
+Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、管理界面和数据密集型应用。它将设计规范、69 个组件和动效示例放在一起，帮助团队建立一致、可复用的界面语言。
 
 - **一致的视觉语言**：色彩、字体、文字层级、间距、几何与焦点规则。
-- **67 个可组合组件**：覆盖布局、表单、数据、导航、浮层和反馈。
+- **69 个可组合组件**：覆盖布局、表单、数据、导航、浮层和反馈。
 - **可验证的动效**：12 组播放 / 重播 / 复位演示，以及三角构架启动编排。
 - **面向开发协作**：组件契约、交互展台和 AI skill 帮助设计与实现保持一致。
 
@@ -27,8 +27,9 @@ Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、
 
 ## 版本与源码范围
 
-- **本源码包版本：0.11.0**。主入口导出 67 个组件，统计不含类型及独立 `/theme` 入口的 ThemeProvider、hook 和元数据。发布是否可安装以 npm registry 为准。
+- **本源码包版本：0.11.2**。0.11.0 制品主入口为 67 个组件；当前源码含未发布 ChatThread / ChatCard，共 69 个组件，统计不含类型及独立 `/theme` 入口的 ThemeProvider、hook 和元数据。发布是否可安装以 npm registry 为准。
 - **0.11.0 新增**：产品评审 `/review`、`/review/vite`，摘要页签 `Tabs description/status`、`Toast placement="floating"`、`SegmentedControl size="compact"` 及相邻 Disclosure 分隔线与生产动效修正。npm 0.10.0 不包含这些新增 API。
+- **未发布聊天组合**：消息分组、结构化卡片及历史跟随见 [Agent Chat](docs/AGENT_CHAT.md)，不在 0.11.0 制品中。
 - **展台随源码更新**，在线部署跟随 main；安装包的能力以精确版本和实际导出/实现为准。上述源码变更、历史版本与接入边界统一见[版本记录](CHANGELOG.md)。
 
 三套主题、轨道艺术、设置导航与主题选择等已有能力见下方组件和规范入口；应用组件的 Ant Design / MUI 对照见[对标清单](docs/ANTD_MUI_AUDIT.md)。
@@ -42,7 +43,7 @@ Rhine Design 是面向 React 应用的开源设计系统，适合桌面工具、
 在你的 React 项目中安装：
 
 ```sh
-npm install --save-exact @linhey/rhine-design@0.11.0
+npm install --save-exact @linhey/rhine-design@0.11.2
 ```
 
 包与版本信息见 [npm](https://www.npmjs.com/package/@linhey/rhine-design)。如需使用未发版的源码，可安装 `git+https://github.com/linhay/rhine-design.git#<commit>`；建议固定版本并提交 lockfile。
@@ -133,6 +134,7 @@ export function App() {
 | 布局与背景 | Surface · Toolbar · Divider · Stack · Inline · Grid · Background² · AppShell² · AppShellToggle⁴ · OrbitBackdrop³ · NeutronStarBackdrop⁴ |
 | 表单与选择 | TextField · Fieldset¹ · ErrorSummary¹ · Textarea · Select · Checkbox · RadioGroup · Switch · SearchField · Combobox · SelectionCard · DateField² · DateRangePicker² · NumberField² · TreeSelect² · RemoteMultiSelect² · ThemePicker⁴ · ThemePreview⁴ |
 | 导航与展开 | SideNav¹ · Breadcrumbs¹ · Steps¹ · Tabs · SegmentedControl · Disclosure |
+| 聊天组合（源码候选） | ChatThread · ChatCard |
 | 搜索与筛选组合 | ListFilterBar⁵ |
 | 数据与媒体 | Metric · KeyValue · DataTable · Pagination · StatusTimeline¹ · StatusTimelineList⁴ · TimelineLegend¹ · TrendChart² · StackedBar² · MediaCard² · MediaViewer² |
 | 浮层 | Drawer¹ · Dialog · ConfirmDialog · Popover · Menu · Tooltip |
@@ -150,6 +152,7 @@ export function App() {
 
 | 主题 | 文档 | 在线预览 |
 | --- | --- | --- |
+| 聊天消息、卡片与历史（源码候选） | [Agent Chat](docs/AGENT_CHAT.md) | [聊天消息与记录](https://linhay.github.io/rhine-design/#agent-chat) |
 | 视觉基础与组合原则 | [设计规范](docs/DESIGN_SYSTEM.md) | [视觉基础](https://linhay.github.io/rhine-design/#foundation) |
 | 间距、分组与卡片组合 | [Spacing](components/SPACING.md) | [间距与组合](https://linhay.github.io/rhine-design/#spacing) |
 | 字体、文字层级与数值 | [Typography](components/TYPOGRAPHY.md) | [字体与文字](https://linhay.github.io/rhine-design/#typography) |
@@ -190,6 +193,8 @@ mkdir -p .agents/skills
 cp -R node_modules/@linhey/rhine-design/skills/rhine-design .agents/skills/
 ```
 
+复制后，skill 内部链接仍以 skill 目录为基准；以代码格式列出的 `docs/`、`components/` 等路径以已核对版本的组件包根目录为基准。独立安装 skill 且尚未安装组件包时，可使用其标明固定提交的在线契约后备链接；该快照不会跟随 main，也不代表当前安装版本的 API。
+
 然后向助手提出具体任务，例如：
 
 > 使用 $rhine-design 设计一个设置页面，包含搜索、选项开关和保存反馈；复用现有组件，并提供键盘操作与减少动态效果。

package/components/Actions.tsx

@@ -2,6 +2,7 @@ import { forwardRef, useEffect, useRef, useState, type AnchorHTMLAttributes, typ
 import { Button, type ButtonProps } from './components';
 
 const paths = {
+  settings: 'M3 5h3m4 0h7M3 15h3m4 0h7M3 10h8m4 0h2M6 3h4v4H6zM11 8h4v4h-4zM6 13h4v4H6z',
   menu: 'M3 5h14M3 10h14M3 15h14',
   close: 'm5 5 10 10M15 5 5 15',
   chevronDown: 'm5 8 5 5 5-5',

package/components/AdvancedForms.tsx

@@ -132,25 +132,33 @@ export interface RemoteMultiSelectProps {
 }
 export function RemoteMultiSelect({ value, onValueChange, options, readOnly = false, clearable = true, closeOnSelect = false, clearQueryOnSelect = false, name, maxVisibleTags, ...props }: RemoteMultiSelectProps) {
   const inputId = useId();
+  const [open, setOpen] = useState(false);
   const [expanded, setExpanded] = useState(false);
   const limit = maxVisibleTags !== undefined && Number.isFinite(maxVisibleTags) ? Math.max(0, Math.floor(maxVisibleTags)) : undefined;
   const collapsible = limit !== undefined && value.length > limit;
   // Clearing or replacing the selection below the limit starts a new compact view.
   if (expanded && !collapsible) setExpanded(false);
   const shown = collapsible && !expanded ? value.slice(0, limit) : value;
-  const focusInput = () => document.getElementById(inputId)?.focus();
-  const remove = (key: string) => {
+  const focusInput = (nextOpen = false) => { document.getElementById(inputId)?.focus(); setOpen(nextOpen); };
+  const remove = (key: string, nextOpen = false) => {
     if (props.disabled || readOnly || value.find(item => item.value === key)?.disabled) return;
-    onValueChange(value.filter(item => item.value !== key)); focusInput();
+    onValueChange(value.filter(item => item.value !== key)); focusInput(nextOpen);
   };
   return <div className={`rhine-multi-select${limit !== undefined ? ' rhine-multi-select--compact' : ''}`}>
-    <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(''); } }} />
+    <Combobox {...props} id={inputId} open={open} onOpenChange={setOpen} readOnly={readOnly} selectedValues={value.map(item => item.value)} closeOnSelect={closeOnSelect} completionLabel={closeOnSelect ? undefined : '完成选择'} onEmptyBackspace={() => { const last = [...value].reverse().find(item => !item.disabled); if (last) remove(last.value, open); }} options={options.map(option => ({ ...option, disabled: option.disabled || value.some(item => item.value === option.value && item.disabled) }))} value={null} onValueChange={option => {
+      const original = options.find(item => item.value === option.value);
+      if (!original || original.disabled || props.disabled || readOnly) return;
+      const selected = value.find(item => item.value === original.value);
+      if (selected?.disabled) return;
+      onValueChange(selected ? value.filter(item => item.value !== original.value) : [...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 id={`${inputId}-tags`} className="rhine-multi-select__tags" aria-label={`${props.label}已选项`} data-expanded={collapsible && expanded || undefined}>{shown.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>
     <div className="rhine-multi-select__actions">
       {limit !== undefined && <span className="rhine-text rhine-text--caption rhine-text--muted">已选 {value.length} 项</span>}
       {collapsible && <Button variant="quiet" aria-expanded={expanded} aria-controls={`${inputId}-tags`} onClick={() => setExpanded(current => !current)}>{expanded ? '收起已选项' : '展开已选项'}</Button>}
-      {clearable && <Button variant="quiet" disabled={props.disabled || readOnly || !value.some(item => !item.disabled)} onClick={() => { onValueChange(value.filter(item => item.disabled)); focusInput(); }}>清空选择</Button>}
+      {clearable && value.some(item => !item.disabled) && <Button type="button" variant="quiet" disabled={props.disabled || readOnly} onClick={() => { onValueChange(value.filter(item => item.disabled)); focusInput(); }}>清空选择</Button>}
     </div>
   </div>;
 }

package/components/AppShell.tsx

@@ -15,6 +15,7 @@ export interface AppShellProps {
   header?: ReactNode; contentHeader?: ReactNode; children: ReactNode; label?: string; decoration?: BackgroundDecoration;
   className?: string; style?: CSSProperties;
   controls?: 'header' | 'inline';
+  collapseEmptyContentHeader?: boolean;
 }
 
 interface PanelControl { panel: ShellPanel; overlay: boolean; side: 'left' | 'right'; id: string; drawerOpen: boolean; setDrawerOpen: (open: boolean) => void }
@@ -45,7 +46,7 @@ function Panel({ panel, overlay, side, id, drawerOpen, setDrawerOpen, hidden = f
   </div>;
 }
 
-export function AppShell({ layout, navigation, secondary, header, contentHeader, children, label = '应用工作区', decoration = 'auto', className = '', style, controls = 'header' }: AppShellProps) {
+export function AppShell({ layout, navigation, secondary, header, contentHeader, children, label = '应用工作区', decoration = 'auto', className = '', style, controls = 'header', collapseEmptyContentHeader = false }: AppShellProps) {
   const ref = useRef<HTMLDivElement>(null);
   const focusedPanel = useRef<'nav' | 'secondary' | null>(null);
   const focusedToggle = useRef<string | null>(null);
@@ -93,7 +94,7 @@ export function AppShell({ layout, navigation, secondary, header, contentHeader,
     <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>
-      <div className="rhine-shell__main">{contentHeader != null && <header className="rhine-shell__content-header">{contentHeader}</header>}
+      <div className="rhine-shell__main">{contentHeader != null && <header className="rhine-shell__content-header" data-collapse-empty={collapseEmptyContentHeader || undefined}>{contentHeader}</header>}
       <Background className="rhine-shell__content" decoration={decoration} tabIndex={0} role="region" aria-label="正文">{children}</Background></div>
     </div>
   </div></ShellControls.Provider>;

package/components/COMMON_COMPONENTS.md

@@ -26,7 +26,7 @@ SideNav、Breadcrumbs、Steps、Drawer、Fieldset、ErrorSummary、StatusTimelin
 | Combobox | 受控查询与选中值；候选由调用方返回；方向键/Enter/Escape，IME保护，加载/无结果/错误 |
 | Tooltip | 鼠标与键盘说明、Escape、可悬停；不可放交互控件或关键信息 |
 | Toast | 单条通知、关闭；成功可定时、警告错误持久；hover/focus/页面隐藏暂停计时，无全局队列 |
-| Dialog / ConfirmDialog | 标题描述、焦点限制及归还、Escape、滚动；确认默认聚焦取消，异步失败保留内容 |
+| Dialog / ConfirmDialog | 必填标题（Dialog说明可省略）、焦点限制及归还、Escape、滚动；确认默认聚焦取消，异步失败保留内容 |
 | Popover | 按钮触发非模态详情、边缘避让、Escape与焦点归还；不替代Tooltip |
 | Menu | 操作项/禁用/危险项；方向键/Home/End/输入字符跳转；不是表单选择器 |
 | Divider / Stack / Inline / Grid | 语义分隔线、纵排、可换行横排、自适应网格；只消费间距tokens |
@@ -75,3 +75,7 @@ SideNav、Breadcrumbs、Steps、Drawer、Fieldset、ErrorSummary、StatusTimelin
 展台使用当前源码的真实组件；本页重点覆盖数据、表单、操作/布局、反馈/浮层四组。合成数据只演示事件与状态；Clipboard仅复制明确的演示字符串。测试覆盖分页边界、请求状态、异步复制失败、IME、候选列表、通知计时、浮层焦点/Escape与窄窗；原生宿主原生平台和屏幕阅读器仍需App接入后单独验收。
 
 Toast 浮动通知（自 0.11.0，npm 0.10.0 不含，见[版本记录](../CHANGELOG.md#01102026-10-27)）：`placement="floating"` 通过 Portal 挂到最近主题根，位于视口右下角，距边缘 16px、最大宽度 400px，窄窗两侧各留 16px。默认 inline 行为保持；浮动通知不占内容流、不抢焦点，关闭后不拦截点击；继承主题与减少动态。反馈展台使用浮动模式。成功沿用 5 秒关闭及悬停/聚焦/隐藏暂停，关键错误仍持久。
+
+SideNav 可选 `NavItem.actions` / `NavAction`，空数组无按钮/空位；菜单触发器与链接为兄弟。菜单到受控 Dialog 的归焦见[导航行操作](../docs/SIDE_NAV_ACTIONS.md)（未发布）。
+
+Popover可选 `showHeader={false}`（未发布，默认true）省略可见标题/关闭行；非空title仍为可访问名称，触发器必须具名可聚焦。适用范围、退出与组合契约见[托盘用量](../docs/TRAY_USAGE.md)。

package/components/Chat.tsx

@@ -0,0 +1,160 @@
+import { createContext, useContext, useId, useLayoutEffect, useRef, useState, type ReactNode } from 'react';
+import { Badge, Button, Disclosure, Surface, type Tone } from './components';
+
+export type ChatStatus = 'pending' | 'accepted' | 'declined' | 'blocked' | 'running' | 'partial' | 'succeeded' | 'failed' | 'cancelled' | 'expired' | 'unknown';
+const statuses: Record<ChatStatus, [string, Tone]> = {
+  pending: ['待回应', 'neutral'], accepted: ['已接受', 'neutral'], declined: ['已拒绝', 'neutral'],
+  blocked: ['等待依赖', 'warning'], running: ['运行中', 'neutral'], partial: ['部分结果', 'warning'],
+  succeeded: ['已完成', 'success'], failed: ['失败', 'error'], cancelled: ['已取消', 'neutral'],
+  expired: ['已过期', 'warning'], unknown: ['状态未知', 'warning'],
+};
+const ReadOnlyContext = createContext(false);
+export interface ChatCardProps {
+  title: string;
+  status: ChatStatus;
+  /** Keep error/recovery or unknown-state context here, outside the disclosure. */
+  summary: ReactNode;
+  children?: ReactNode;
+  actions?: ReactNode;
+  readOnly?: boolean;
+}
+/** Structured content only. Business transitions and permissions belong to the host. */
+export function ChatCard({ title, status, summary, children, actions, readOnly = false }: ChatCardProps) {
+  const observing = useContext(ReadOnlyContext) || readOnly;
+  const [label, tone] = Object.hasOwn(statuses, status) ? statuses[status] : statuses.unknown;
+  return <Surface className="rhine-chat-card" padding="none">
+    <div className="rhine-chat-card__heading"><strong>{title}</strong><Badge tone={tone}>{label}</Badge></div>
+    <div className="rhine-chat-card__summary">{summary}</div>
+    {children && <Disclosure title={`${title} · 详情`}>{children}</Disclosure>}
+    {!observing && actions && <div className="rhine-chat-actions">{actions}</div>}
+  </Surface>;
+}
+export interface ChatMember { id: string; name: string; avatar?: ReactNode }
+interface ChatEntryBase { id: string; /** Host-localized day label, also a grouping boundary. */ day: string; content: ReactNode }
+export interface ChatMessage extends ChatEntryBase {
+  kind: 'message'; member: ChatMember;
+  /** ISO 8601 timestamp with explicit offset. */ dateTime: string;
+  /** Host-localized display time. */ time: string;
+  actions?: ReactNode;
+}
+export interface ChatEvent extends ChatEntryBase { kind: 'event' }
+export type ChatEntry = ChatMessage | ChatEvent;
+export interface ChatThreadProps {
+  label: string;
+  /** Stable unique ids in chronological order; prepend older entries without replacing existing ids. */
+  entries: readonly ChatEntry[];
+  readOnly?: boolean;
+  hasEarlier?: boolean;
+  loadingEarlier?: boolean;
+  historyError?: string;
+  onLoadEarlier?: () => void;
+  /** A coarse host-owned announcement. Do not pass every streamed token. */
+  announcement?: string;
+}
+function isContinuation(previous: ChatEntry | undefined, entry: ChatMessage) {
+  if (previous?.kind !== 'message' || previous.member.id !== entry.member.id || previous.day !== entry.day) return false;
+  const gap = Date.parse(entry.dateTime) - Date.parse(previous.dateTime);
+  return gap >= 0 && gap <= 5 * 60_000;
+}
+type Anchor = { id: string; offset: number };
+
+/** A non-virtualized, chronological reading viewport. No network, model or read receipts. */
+export function ChatThread({ label, entries, readOnly = false, hasEarlier = false, loadingEarlier = false, historyError, onLoadEarlier, announcement = '' }: ChatThreadProps) {
+  const id = useId();
+  const viewport = useRef<HTMLDivElement>(null);
+  const content = useRef<HTMLOListElement>(null);
+  const follow = useRef(true);
+  const anchor = useRef<Anchor | null>(null);
+  const previousFirst = useRef<string | undefined>(undefined);
+  const initialized = useRef(false);
+  const previousIds = useRef(new Set<string>());
+  const [hasNewMessages, setHasNewMessages] = useState(false);
+  const [following, setFollowing] = useState(true);
+  const rows = () => Array.from(content.current?.querySelectorAll<HTMLElement>('[data-chat-entry]') ?? []);
+  function remember() {
+    const el = viewport.current;
+    if (!el) return;
+    const row = rows().find(row => row.offsetTop + row.offsetHeight > el.scrollTop);
+    anchor.current = row ? { id: row.dataset.chatEntry!, offset: row.offsetTop - el.scrollTop } : null;
+  }
+  function pause() { follow.current = false; setFollowing(false); remember(); }
+  function restore() {
+    const el = viewport.current;
+    if (!el) return;
+    if (follow.current) el.scrollTop = el.scrollHeight;
+    else if (anchor.current) {
+      const row = rows().find(row => row.dataset.chatEntry === anchor.current!.id);
+      if (row) el.scrollTop = row.offsetTop - anchor.current.offset;
+    }
+    remember();
+  }
+  // Commit before paint: a prepend preserves the same visible row, even if streaming also appends.
+  useLayoutEffect(() => {
+    const first = entries[0]?.id;
+    const prepended = initialized.current && first !== previousFirst.current && entries.some(entry => entry.id === previousFirst.current);
+    if (prepended) { follow.current = false; setFollowing(false); }
+    const firstExisting = entries.findIndex(entry => previousIds.current.has(entry.id));
+    if (initialized.current && !follow.current && firstExisting >= 0 && entries.slice(firstExisting).some(entry => !previousIds.current.has(entry.id))) setHasNewMessages(true);
+    previousIds.current = new Set(entries.map(entry => entry.id));
+    restore();
+    previousFirst.current = first;
+    initialized.current = true;
+  });
+  useLayoutEffect(() => {
+    if (!content.current || !viewport.current || typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(restore);
+    observer.observe(content.current);
+    observer.observe(viewport.current);
+    return () => observer.disconnect();
+    // The observer reads mutable viewport/anchor/follow refs, not entry props.
+  }, []);
+  return <ReadOnlyContext.Provider value={readOnly}><div className="rhine-chat">
+    <div className="rhine-chat-toolbar">
+      <Button variant="quiet" aria-disabled={!hasEarlier || loadingEarlier || !onLoadEarlier} busy={loadingEarlier} busyLabel="正在加载更早消息"
+        onClick={() => { if (!hasEarlier || loadingEarlier || !onLoadEarlier) return; pause(); onLoadEarlier(); }}>
+        {loadingEarlier ? '正在加载更早消息' : hasEarlier ? '加载更早消息' : '已到最早消息'}
+      </Button>
+      {readOnly && <Badge>只读观察</Badge>}
+    </div>
+    {historyError && <p className="rhine-chat-history-error" role="alert">{historyError}</p>}
+    <div ref={viewport} id={id} className="rhine-chat-viewport" role="region" aria-label={label} tabIndex={0}
+      onScroll={() => {
+        const el = viewport.current!;
+        // Reaching the bottom does not silently cancel a disclosure/history pause.
+        if (el.scrollHeight - el.clientHeight - el.scrollTop > 8 && follow.current) { follow.current = false; setFollowing(false); }
+        remember();
+      }}
+      onClickCapture={event => {
+        const target = event.target as HTMLElement;
+        if (target.closest('summary, [aria-expanded]:not([aria-haspopup])')) pause();
+      }}
+      onFocusCapture={event => { if (event.target !== event.currentTarget) pause(); }}
+      onWheel={event => { if (event.deltaY < 0) pause(); }}
+      onKeyDown={event => { if (['ArrowUp', 'PageUp', 'Home'].includes(event.key)) pause(); }}>
+      <ol ref={content} className="rhine-chat-list">
+        {entries.map((entry, index) => {
+          const previous = entries[index - 1];
+          const continuation = entry.kind === 'message' && isContinuation(previous, entry);
+          return <li key={entry.id} data-chat-entry={entry.id} className="rhine-chat-entry" data-continuation={continuation}>
+            {previous?.day !== entry.day && <div className="rhine-chat-day">{entry.day}</div>}
+            {entry.kind === 'event' ? <div className="rhine-chat-event">{entry.content}</div> : <article aria-label={`${entry.member.name} · ${entry.time}`}>
+              <header className={continuation ? 'rhine-sr-only' : 'rhine-chat-meta'}>
+                {entry.member.avatar && <span aria-hidden="true" className="rhine-chat-avatar">{entry.member.avatar}</span>}
+                <strong>{entry.member.name}</strong><time dateTime={entry.dateTime}>{entry.time}</time>
+              </header>
+              <div className="rhine-chat-body">{entry.content}</div>
+              {!readOnly && entry.actions && <div className="rhine-chat-actions">{entry.actions}</div>}
+            </article>}
+          </li>;
+        })}
+      </ol>
+      {!entries.length && <p className="rhine-chat-empty">暂无消息</p>}
+    </div>
+    <div className="rhine-chat-footer">
+      <span role="status" aria-live="polite">{[announcement, following ? '正在跟随最新消息' : `${hasNewMessages ? '有新消息 · ' : ''}已暂停跟随，可继续阅读历史`].filter(Boolean).join(' · ')}</span>
+      <Button variant="quiet" aria-controls={id} aria-pressed={following} onClick={() => {
+        follow.current = true; setFollowing(true); setHasNewMessages(false); restore();
+      }}>回到最新并跟随</Button>
+    </div>
+  </div></ReadOnlyContext.Provider>;
+}

package/components/Forms.tsx

@@ -2,6 +2,7 @@ import { useEffect, useId, useLayoutEffect, useRef, useState, type InputHTMLAttr
 import * as PopoverBase from '@radix-ui/react-popover';
 import { Button, type Choice } from './components';
 import { Icon, IconButton } from './Actions';
+import { useFloatingScale } from './useFloatingScale';
 import './checkbox-row.css';
 
 export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type'> {
@@ -47,14 +48,21 @@ export interface ComboboxProps {
   value: string | null; onValueChange: (option: Choice) => void; options: Choice[];
   loading?: boolean; error?: string; disabled?: boolean;
   readOnly?: boolean; placeholder?: string; hint?: string; id?: string;
-  selectedValues?: string[]; closeOnSelect?: boolean; onEmptyBackspace?: () => void;
+  selectedValues?: string[]; closeOnSelect?: boolean; onEmptyBackspace?: () => void; completionLabel?: string;
+  open?: boolean; onOpenChange?: (open: boolean) => void;
 }
-export function Combobox({ label, query, onQueryChange, value, onValueChange, options, loading = false, error, disabled = false, readOnly = false, placeholder, hint, id: suppliedId, selectedValues, closeOnSelect = true, onEmptyBackspace }: ComboboxProps) {
+export function Combobox({ label, query, onQueryChange, value, onValueChange, options, loading = false, error, disabled = false, readOnly = false, placeholder, hint, id: suppliedId, selectedValues, closeOnSelect = true, onEmptyBackspace, completionLabel, open: controlledOpen, onOpenChange }: ComboboxProps) {
   const generatedId = useId(), id = suppliedId || generatedId; const composing = useRef(false);
+  const floatingRef = useFloatingScale(undefined, 'popover', 240);
+  const exitingWithTab = useRef(false);
+  const releaseTabGuard = useRef<(() => void) | undefined>(undefined);
+  useEffect(() => () => releaseTabGuard.current?.(), []);
   const root = useRef<HTMLDivElement>(null);
   const [container, setContainer] = useState<HTMLElement>();
   useLayoutEffect(() => { setContainer((root.current?.closest('.rhine-theme') as HTMLElement) || document.body); }, []);
-  const [open, setOpen] = useState(false), [active, setActive] = useState<string | null>(null), [draft, setDraft] = useState<string | null>(null);
+  const [internalOpen, setInternalOpen] = useState(false), [active, setActive] = useState<string | null>(null), [draft, setDraft] = useState<string | null>(null);
+  const open = controlledOpen ?? internalOpen;
+  const setOpen = (next: boolean) => { if (controlledOpen === undefined) setInternalOpen(next); onOpenChange?.(next); };
   useEffect(() => { if (disabled || readOnly) { setOpen(false); setActive(null); setDraft(null); composing.current = false; } }, [disabled, readOnly]);
   const available = loading || error ? [] : options.filter(option => !option.disabled);
   const activeIndex = options.findIndex(option => option.value === active && !option.disabled);
@@ -62,20 +70,72 @@ export function Combobox({ label, query, onQueryChange, value, onValueChange, op
   useEffect(() => { if (!open || !activeId) return; document.getElementById(activeId)?.scrollIntoView?.({ block: 'nearest' }); }, [activeId, open]);
   const choose = (option: Choice) => { if (readOnly || disabled || loading || error) return; onValueChange(option); if (closeOnSelect) setOpen(false); setActive(null); };
   const visibleOpen = open && !disabled && !readOnly;
-  return <div ref={root} className="rhine-combobox rhine-field" onBlur={event => { if (!event.currentTarget.contains(event.relatedTarget)) setOpen(false); }}><label htmlFor={id}>{label}</label>
+  // Keep a multiselect action in place until its click finishes. Closing on
+  // pointerdown/blur can shift a zoomed page before pointerup reaches the button.
+  const containsInteractionTarget = (target: EventTarget | null) => target instanceof Node && (root.current?.closest('.rhine-multi-select') ?? root.current)?.contains(target);
+  const beginTabExit = () => {
+    exitingWithTab.current = true;
+    releaseTabGuard.current?.();
+    const dialog = root.current?.closest<HTMLElement>('.rhine-dialog[data-state="open"]');
+    if (!dialog) return;
+    const doc = dialog.ownerDocument;
+    let lastInside = doc.activeElement instanceof HTMLElement && dialog.contains(doc.activeElement) ? doc.activeElement : document.getElementById(id);
+    // The nested Radix scope resumes its parent asynchronously on unmount.
+    // Keep that short interval contained even for repeated keyboard events.
+    const guard = (event: FocusEvent) => {
+      if (!dialog.isConnected || dialog.dataset.state !== 'open') return;
+      const target = event.target;
+      if (!(target instanceof HTMLElement)) return;
+      if (dialog.contains(target)) lastInside = target;
+      else if (!document.getElementById(`${id}-popup`)?.contains(target) && lastInside?.isConnected) {
+        lastInside.focus({ preventScroll: true });
+        if (lastInside.id === id) { setOpen(false); setActive(null); }
+      }
+    };
+    doc.addEventListener('focusin', guard);
+    releaseTabGuard.current = () => { doc.removeEventListener('focusin', guard); releaseTabGuard.current = undefined; };
+  };
+  const complete = () => { document.getElementById(id)?.focus(); setOpen(false); setActive(null); };
+  return <div ref={root} className="rhine-combobox rhine-field" onBlur={event => { if (!containsInteractionTarget(event.relatedTarget) && !document.getElementById(`${id}-popup`)?.contains(event.relatedTarget)) setOpen(false); }}><label htmlFor={id}>{label}</label>
     <PopoverBase.Root open={visibleOpen} onOpenChange={setOpen}><PopoverBase.Anchor asChild><div className="rhine-combobox__input"><input id={id} role="combobox" aria-autocomplete="list" aria-expanded={visibleOpen} aria-controls={visibleOpen ? `${id}-list` : undefined} aria-activedescendant={visibleOpen ? activeId : undefined} aria-invalid={!!error || undefined} aria-describedby={[`${id}-status`, hint && `${id}-hint`].filter(Boolean).join(' ')} value={draft ?? query} disabled={disabled} readOnly={readOnly} placeholder={placeholder}
       onClick={() => { if (!readOnly && !disabled) setOpen(true); }} onFocus={() => { if (!readOnly && !disabled) setOpen(true); }} onChange={event => { if (readOnly || disabled) return; if (composing.current) setDraft(event.target.value); else onQueryChange(event.target.value); setActive(null); setOpen(true); }}
       onCompositionStart={() => { if (!readOnly && !disabled) { composing.current = true; setDraft(query); } }} onCompositionEnd={event => { composing.current = false; setDraft(null); if (!readOnly && !disabled) onQueryChange(event.currentTarget.value); }}
       onKeyDown={event => {
         if (readOnly || disabled || composing.current || event.nativeEvent.isComposing || event.keyCode === 229) return;
+        if (event.key === 'Tab' && open) {
+          if (!event.shiftKey && completionLabel) {
+            const completion = document.getElementById(`${id}-complete`);
+            if (completion) { event.preventDefault(); completion.focus(); return; }
+          }
+          beginTabExit();
+        }
         if (event.key === 'Backspace' && !event.currentTarget.value && onEmptyBackspace) { event.preventDefault(); onEmptyBackspace(); }
         if (event.key === 'Escape' && open) { event.preventDefault(); event.stopPropagation(); setOpen(false); setActive(null); }
         if (['ArrowDown', 'ArrowUp'].includes(event.key)) { event.preventDefault(); setOpen(true); const index = available.findIndex(option => option.value === active); const next = event.key === 'ArrowDown' ? (index + 1) % available.length : (index <= 0 ? available.length : index) - 1; setActive(available[next]?.value ?? null); }
         if (open && ['Home', 'End'].includes(event.key)) { event.preventDefault(); setActive((event.key === 'Home' ? available[0] : available.at(-1))?.value ?? null); }
         if (open && event.key === 'Enter') { event.preventDefault(); const option = available.find(item => item.value === active); if (option) choose(option); }
       }} /><span className="rhine-combobox__arrow"><Icon name="chevronDown" size={16} /></span></div></PopoverBase.Anchor>
-    <PopoverBase.Portal container={container}><PopoverBase.Content asChild sideOffset={4} collisionPadding={12} onOpenAutoFocus={event => event.preventDefault()} onCloseAutoFocus={event => event.preventDefault()} onInteractOutside={event => { if (root.current?.contains(event.target as Node)) event.preventDefault(); }}>
-      <div className="rhine-combobox__list" role="listbox" id={`${id}-list`} aria-label={label} aria-multiselectable={selectedValues ? true : undefined} aria-busy={loading}>{!loading && !error && options.map((option, index) => <div role="option" id={`${id}-option-${index}`} key={option.value} aria-selected={selectedValues ? selectedValues.includes(option.value) : option.value === value} aria-disabled={option.disabled || undefined} data-active={option.value === active} onMouseDown={event => event.preventDefault()} onMouseMove={() => { if (!option.disabled) setActive(option.value); }} onClick={() => { if (!option.disabled) choose(option); }}>{option.label}</div>)}{(loading || error || !options.length) && <div className="rhine-combobox__empty" role="presentation">{loading ? '正在读取…' : error ? '暂不可用' : '暂无匹配结果'}</div>}</div>
+    <PopoverBase.Portal container={container}><PopoverBase.Content asChild updatePositionStrategy="always" sideOffset={4} collisionPadding={12} onOpenAutoFocus={event => event.preventDefault()} onCloseAutoFocus={event => {
+      event.preventDefault();
+      releaseTabGuard.current?.();
+      if (!exitingWithTab.current) return;
+      exitingWithTab.current = false;
+      // Radix resumes the parent scope after this callback. Rapid Tab can
+      // reach a guard or the background during that interval; restore focus
+      // only for a keyboard exit from a still-open Rhine modal.
+      const dialog = root.current?.closest('.rhine-dialog[data-state="open"]');
+      const active = document.activeElement;
+      if (active?.hasAttribute('data-radix-focus-guard') || (dialog && !dialog.contains(active))) complete();
+    }} onInteractOutside={event => { if (containsInteractionTarget(event.target)) event.preventDefault(); }}>
+      <div ref={floatingRef} className="rhine-combobox__list" id={`${id}-popup`} onKeyDown={event => { if (event.key === 'Escape') { event.preventDefault(); event.stopPropagation(); complete(); } }}>
+        <div role="listbox" id={`${id}-list`} aria-label={label} aria-multiselectable={selectedValues ? true : undefined} aria-busy={loading}>{!loading && !error && options.map((option, index) => <div role="option" id={`${id}-option-${index}`} key={option.value} aria-selected={selectedValues ? selectedValues.includes(option.value) : option.value === value} aria-disabled={option.disabled || undefined} data-active={option.value === active} onMouseDown={event => event.preventDefault()} onMouseMove={() => { if (!option.disabled) setActive(option.value); }} onClick={() => { if (!option.disabled) choose(option); }}>{selectedValues && <span className="rhine-combobox__check" aria-hidden="true">{selectedValues.includes(option.value) ? '✓' : ''}</span>}{option.label}</div>)}{(loading || error || !options.length) && <div className="rhine-combobox__empty" role="presentation">{loading ? '正在读取…' : error ? '暂不可用' : '暂无匹配结果'}</div>}</div>
+        {completionLabel && <div className="rhine-combobox__completion"><Button id={`${id}-complete`} type="button" variant="quiet" onMouseDown={event => event.preventDefault()} onClick={complete} onKeyDown={event => {
+          if (event.key !== 'Tab') return;
+          if (event.shiftKey) { event.preventDefault(); document.getElementById(id)?.focus(); }
+          // Restore the input as the origin of the browser's normal forward Tab.
+          else { beginTabExit(); complete(); }
+        }}>{completionLabel}</Button></div>}
+      </div>
     </PopoverBase.Content></PopoverBase.Portal></PopoverBase.Root>
     <span id={`${id}-status`} role="status" className={`rhine-text rhine-text--caption ${error ? 'rhine-text--error' : 'rhine-text--muted'}`}>{loading ? '正在读取候选项…' : error || (options.length ? `${options.length} 个候选项` : '暂无匹配结果')}</span>
     {hint && <span id={`${id}-hint`} className="rhine-field__hint">{hint}</span>}

package/components/Navigation.tsx

@@ -1,7 +1,9 @@
-import type { HTMLAttributes, MouseEvent } from 'react';
-import { Icon, type IconName } from './Actions';
+import { useRef, type HTMLAttributes, type MouseEvent } from 'react';
+import { Menu, type MenuItem } from './Overlays';
+import { Icon, IconButton, type IconName } from './Actions';
 
-export interface NavItem { id: string; label: string; href: string; icon?: IconName }
+export interface NavAction extends Omit<MenuItem, 'onSelect'> { onSelect: (trigger: HTMLButtonElement) => void }
+export interface NavItem { id: string; label: string; href: string; icon?: IconName; actions?: readonly NavAction[] }
 export interface NavGroup { label: string; items: readonly NavItem[] }
 export interface SideNavProps extends HTMLAttributes<HTMLElement> {
   groups: readonly NavGroup[]; currentId: string;
@@ -10,11 +12,20 @@ export interface SideNavProps extends HTMLAttributes<HTMLElement> {
 export function SideNav({ groups, currentId, onNavigate, className = '', 'aria-label': label = '主导航', ...props }: SideNavProps) {
   return <nav {...props} aria-label={label} className={`rhine-side-nav ${className}`}>
     {groups.map(group => <div className="rhine-side-nav__group" key={group.label}><p>{group.label}</p><ul>
-      {group.items.map(item => <li key={item.id}><a href={item.href} aria-current={currentId === item.id ? 'page' : undefined} onClick={event => onNavigate?.(item, event)}>{item.icon && <Icon name={item.icon} size={20}/>}<span className="rhine-side-nav__label">{item.label}</span></a></li>)}
+      {group.items.map(item => <SideNavRow key={item.id} item={item} current={currentId === item.id} onNavigate={onNavigate} />)}
     </ul></div>)}
   </nav>;
 }
 
+function SideNavRow({ item, current, onNavigate }: { item: NavItem; current: boolean; onNavigate?: SideNavProps['onNavigate'] }) {
+  const trigger = useRef<HTMLButtonElement>(null);
+  const hasActions = !!item.actions?.length;
+  return <li className={hasActions ? 'rhine-side-nav__row--actions' : undefined}>
+    <a href={item.href} aria-current={current ? 'page' : undefined} onClick={event => onNavigate?.(item, event)}>{item.icon && <Icon name={item.icon} size={20}/>}<span className="rhine-side-nav__label">{item.label}</span></a>
+    {hasActions && <Menu label={`${item.label}：操作`} trigger={<IconButton ref={trigger} label={`${item.label}：更多操作`} icon="more" />} items={item.actions!.map(action => ({ ...action, onSelect: () => { if (trigger.current) action.onSelect(trigger.current); } }))} />}
+  </li>;
+}
+
 export interface BreadcrumbItem { label: string; href?: string }
 export interface BreadcrumbsProps { items: readonly BreadcrumbItem[]; label?: string }
 export function Breadcrumbs({ items, label = '当前位置' }: BreadcrumbsProps) {