@linhey/rhine-design 0.6.0 → 0.8.0

package/docs/ORBIT_BACKDROP.md

@@ -1,81 +1,73 @@
-# OrbitBackdrop · 轨道背景（0.6.0）
+# OrbitBackdrop · 主题艺术背景
 
-`OrbitBackdrop` 将授权移交的轨道动画作为通用装饰组件维护：固定深色星空衬底、420 个环节点、185 条曲线、80 个深度桶，以及发射箭头、光晕和透视关系。它适合登录、欢迎等入口区域；不包含产品文案、账号逻辑或网络请求。需求与移交记录见 [Issue #8](https://github.com/linhay/rhine-design/issues/8)。
+`OrbitBackdrop` 是带暂停控制的装饰组件。0.8.0 根据主题展示折纸鸟、源石晶簇或草莓甜甜圈，也可通过 `appearance="original"` 保留初版深色轨道。它适合欢迎、登录和品牌展示区域，不表达业务进度，不包含账号逻辑或外部资源请求。移交来源见 [Issue #8](https://github.com/linhay/rhine-design/issues/8)。
 
-**版本边界：**此组件自 `@linhey/rhine-design@0.6.0` 提供，0.5.0 及以前不包含它。采用前核对安装版本与 `components/index.ts`，固定精确版本并提交 lockfile。组件源于 [OrbitBackdrop.tsx](../components/OrbitBackdrop.tsx)，绘制实现在 [orbitRenderer.ts](../components/orbitRenderer.ts)；后者是内部实现，不作为公共 API 导入。
+**版本边界：**基础组件自 `@linhey/rhine-design@0.6.0` 提供；`appearance` 与三套主题物品需要 0.8.0。0.6.0 默认固定深色轨道，升级后默认跟随主题；需要保持旧视觉时显式使用 `appearance="original"`。固定精确版本并提交 lockfile。
 
 ## 使用与契约
 
 ```tsx
 import { Logo, OrbitBackdrop, Text } from '@linhey/rhine-design';
 
-// 此示例要求 0.6.0 或以上，并放在现有主题根内。
 export function WelcomeArtwork() {
-  return (
-    <OrbitBackdrop className="welcome-artwork" style={{ minHeight: 360 }}>
-      <Logo decorative />
-      <Text as="h1" variant="title">开始新的工作</Text>
-      <Text>从这里进入你的工作空间。</Text>
-    </OrbitBackdrop>
-  );
+  return <OrbitBackdrop style={{ minHeight: 360 }}>
+    <Logo decorative />
+    <Text as="h1" variant="title">开始新的工作</Text>
+    <Text>从这里进入你的工作空间。</Text>
+  </OrbitBackdrop>;
 }
 ```
 
 | 输入 | 契约 |
 | --- | --- |
-| `HTMLAttributes<HTMLDivElement>` | 接收容器原生属性，如 `className`、`style`、`id`；宿主负责尺寸、位置和相邻内容布局 |
-| `reducedMotion?: boolean` | `true` 加强减少动态偏好；`false` 或省略均不能覆盖系统、祖先或环境的停帧条件 |
-| `children` | 放入 `.rhine-orbit-content` 内容层，可组合 Logo、标题、正文、表单、动作和页脚，也可用 Surface 分组；宿主 class 控制内容布局，避免遮挡主要艺术或暂停控件 |
+| `HTMLAttributes<HTMLDivElement>` | 宿主负责尺寸、位置、相邻内容布局与可访问名称 |
+| `appearance?: 'theme' \| 'original'` | 默认跟随主题；`original` 固定初版深色轨道，切换保留播放位置与暂停状态 |
+| `reducedMotion?: boolean` | `true` 加强减少动态；`false` 不能覆盖系统或祖先偏好 |
+| `children` | 普通 HTML 内容层，可组合表单、按钮、Logo 与 Surface；不得遮挡暂停控件 |
 
-组件持有绘制配方、内部类名、样式与暂停状态。宿主不复制 Canvas 实现，不另写同用途动画，不通过覆盖内部样式重建其视觉。没有速度、节点数量、业务进度或主题配色参数；需要新能力时先在设计系统中补契约与展台。
+组件持有绘制算法、内部类名、主题配方和暂停状态。没有任意速度、粒子数、业务进度或调色板参数。宿主不复制绘制器、不嵌套 ThemeProvider，也不通过覆盖内部样式重建视觉。内部文件 `orbitRenderer.ts`、`orbitObjectsThree.ts`、`orbitObjectMaterials.ts`、`orbitDonutThree.ts` 不作为公共 API 导入。
 
-Canvas 绝对定位在内容层下方。内容层为直接置于星空上的文字提供浅色前景，普通 Text 与非 icon Logo 继承当前前景，muted Text 沿当前前景降低透明度；不修改宿主颜色 tokens，也不新建或嵌套 `ThemeProvider`。Surface、Notice 等有底色的组件继续使用自己的语义前景，表单与按钮保留宿主主题的前景 / 背景组合。默认内置 Rhine `Button`，在独立控件区域提供“暂停 / 继续”的明确操作。Canvas 为 `aria-hidden` 纯装饰，不接收键盘焦点，不提供进度或业务状态。有效信息仍由普通 HTML 内容表达；动画暂停、减少动态或 Canvas 不可用均不影响内容与业务操作。
+## 四套画面
 
-## 动效生命周期
-
-下列任一条件成立时停止逐帧调度，保留静态画面：
+| 风格 | 物品与细节 |
+| --- | --- |
+| 莱茵 · 纸面 | 折纸鸟：578 个实际三角折面、暖白纤维纸纹、扇形褶皱与叠层双翼、立体细颈与三片尾羽、弧线飞行与振翅转弯、42 片随行纸屑与 120 颗微尘 |
+| 战术终端 | 悬浮源石晶簇：五块不同姿态的倒角晶体、程序矿物纹理、琥珀裂纹、48 块环绕碎片、420 颗余烬与断续约束环 |
+| 橙趣 · 粗描边 | 草莓甜甜圈：烘焙纹理、立体糖霜、280 根糖针、110 颗糖珠、100 根环绕糖粒、460 颗糖尘与奶油色背景 |
+| `original` | 完整初版轨道：420 个环节点、185 条空间曲线、80 个深度桶、箭头、光晕与原始配色 |
 
-- 用户主动暂停；
-- 系统 `prefers-reduced-motion: reduce`，或 `reducedMotion` 为 `true`；
-- 祖先的 `data-rhine-motion="reduced"` 偏好生效（内层跟随系统不覆盖外层减少动态）；
-- 当前窗口宽度不超过 760px；
-- `document.hidden`、组件离屏或可用绘制尺寸为零。
+折纸鸟以舒展的翼面与轻盈的飞行呼应莱茵纸面主题；源石晶簇采用坚硬、暗色的矿物质感。原始模式不随主题改变。
 
-“暂停 / 继续”使用随当前动作变化的按钮名称，不同时声明 `aria-pressed` 切换语义。“继续”只解除用户主动暂停，不越过其他停帧条件。恢复时沿冻结的动画时间继续，不累计隐藏期间的时间，也不追赶错过的帧。偏好或可见性改变时即时重新判断；窗口调整会以当前冻结时间重绘静态画面。设备像素比上限为 2，卸载清理 rAF、监听器和 observers，离开页面不会继续后台绘制。
+莱茵物品在飞行中连续变形成纸蝴蝶：原有 578 个三角折面保持连接，鸟颈收为蝶首、尾羽重塑为触须与腹尖、左右翼展开为四瓣蝶翼；折痕与纸纹随顶点移动，不更换模型或交叉淡化。42 秒有效播放周期为纸鸟 4 秒、折叠变形 14 秒、纸蝴蝶 6 秒、折回 14 秒、纸鸟 4 秒。变形依次收翼、松开折痕、展开为近乎平面的中间纸形，短暂停留后重新折出新形态；翼根、内侧折线与翼尖以独立时间窗依次松开、重新折起，相邻动作错开约 0.8–1 秒；纸面由内向外展平，外缘延后跟随，鸟颈与尾羽绕根部打开。中途暂停扑翼，让折纸动作清晰可见，完成后平滑恢复；蝶形阶段转为较快的扑翼。暂停和减少动态同时冻结形态、翼拍与飞行位置，恢复后接续当前折叠进度。Canvas2D 使用同一组对应顶点与变形函数；静态 SVG 保留纸鸟初始形态。
 
-Canvas 不可用时保留静态艺术 fallback 与 `children`。此降级不表示浏览器或页面业务失败，也不以加载提示掩盖缺失的装饰能力。
+主题物品按需加载 Three.js，环境反射与表面纹理均在本地生成，无模型下载、CDN 或外部纹理。种子固定，运动由唯一的有效播放时间决定；物品、振翅、纸屑、碎片和着色器共用宿主时钟。切换主题复用已创建的绘制器，未激活的画布隐藏并停止绘制。异步导入完成时复核当前主题及挂载状态。
 
-## 主题与可读性
+甜甜圈保留已校准的原版相机与构图：yaw -0.72、tilt 0.22、roll 0.34，透视距离 3.6；中心位于宽度 62%、高度 57%，缩放为 `min(width × .66, height × .39)`。环半径 .84、管半径 .34、糖霜厚度 .022，约 22.4 秒有效播放时间转一圈，不额外摆动。折纸鸟从略高的角度展示宽翼与折面，沿 14 秒弧线往返、起伏并侧倾转弯，双翼以约 2.4 秒周期振动，振幅随飞行阶段变化；纸屑沿稍早的飞行位置散开。Three.js 与 Canvas2D 共用姿态函数，全部运动使用宿主有效播放时间，暂停或减少动态时保持同一姿态。晶簇按竖向轮廓取景。两者都为底部操作区留空间。
 
-轨道采用同一固定深色美术配方；切换 Rhine、Arknights 或 Neo Brutalism 时保留动画构图。艺术文字采用浅色前景，控件、语义容器、独立操作区与外框继续使用完整宿主主题 tokens；不能只改控件的前景而保留白色背景。直接叠加的提示和透明 quiet 操作继承当前内容前景；quiet 的有底色 hover / disabled 状态保持宿主配色，键盘焦点使用当前文字颜色的内描边。可按产品分组需要使用 Surface，不以它作为控件可读性的前提。宿主应提供足够的布局空间，避免正文与主要曲线重叠，也不能遮住暂停入口。
+## 动效与降级
 
-轨道动画不替代 `Progress`、`Skeleton` 或 `Logo`。登录提交、校验失败、数据刷新不重播动画；动画时间不决定业务何时就绪。仅为重播装饰而更换 key 时，将 key 限于 `OrbitBackdrop`，输入状态由重播边界外的宿主持有，不能因重播重置表单或其他业务状态。
+下列条件停止逐帧调度：用户暂停，系统/prop/祖先减少动态，页面隐藏，组件离屏，或尺寸为零。`original` 在窗口不超过 760px 时还会静态降级；三套主题物品在窄屏继续播放。恢复时沿冻结时间继续，不追赶隐藏期间的时间。静态状态调整尺寸或主题仍会重绘当前帧。
 
-## 真实组件展台与验收
+Canvas2D 像素比上限 2，WebGL 上限 1.5。Three.js 无独立 rAF；卸载取消调度、断开 observers，移除监听器，释放几何、材质、纹理、实例缓存、renderer 与 WebGL 上下文。
 
-本地展台 `http://127.0.0.1:18309/#orbit` 复用公开组件，提供暂停 / 继续、局部重播、手动减少动态，以及系统和全局偏好继承。重播只重新挂载装饰组件，不重执行业务动作、不清空外层内容。此条目与 `/#motion` 的 12 组交互配方、`/#startup` 的启动编排分别维护。
+WebGL 不可用、模块加载失败、运行时绘制失败或上下文丢失时，回退到对应物品的 Canvas2D 插画。上下文恢复后沿当前时间继续。Canvas 也不可用时，三主题各展示随包提供的静态 SVG；原始模式保留 CSS 星场。所有降级保留内容与可用业务操作。
 
-验收应覆盖以下行为；本节是验收要求，不代表浏览器检查已执行：
+## 内容与可读性
 
-1. 原动画的环节点、曲线、箭头、光晕与透视仍可辨识；采样不同时间的中间帧，不能只检查单张截图。
-2. 鼠标与键盘可暂停 / 继续；暂停时画面冻结，恢复不跳过冻结期间的时间。
-3. 系统、显式 prop、祖先偏好均可中断动画；将 `reducedMotion` 设为 `false` 不能覆盖系统减少动态。
-4. 检查 400 / 520 / 880 宽度、200% 缩放和三套主题，确认窄窗静态呈现、控件可见、焦点可读且无横向溢出。组合 TextField、主 / 次按钮及 Surface，检查输入文字、placeholder、默认 / hover / disabled 状态和容器内 Text 的前景与背景。
-5. 页面隐藏、离屏、零尺寸时停帧，恢复及 resize 行为一致；卸载无残留调度或监听。
-6. Canvas 不可用时仍显示静态艺术和内容；业务表单、请求与路由不依赖动画。
+Canvas 是 `aria-hidden` 装饰，不接收键盘焦点。有效信息由 HTML 内容表达。内置 Button 提供随动作变化的“暂停动效 / 继续动效”名称，不额外声明 `aria-pressed`。
 
-宿主接入后仍需验证自己的页面布局与业务交互；单元测试、展台检查不等于宿主原生平台或完整辅助技术验收。
+直接置于原始深色艺术上的正文与非 icon Logo 继承浅色前景；主题模式继承宿主文本色。Surface、Notice、输入框和有底色按钮保留完整宿主 tokens。透明 quiet 操作和提示继承内容前景，焦点使用内描边；不覆盖全局颜色变量。
 
-### 2026-10-24 初始源码候选验证
+## 真实组件展台与验收
 
-`npm ci`、`npm run check` 通过：65 项测试（轨道新增 10 项）、TypeScript 类型检查、展台生产构建及 CSS / SVG 产物检查。轨道测试覆盖完整节点绘制、DPR 上限、暂停时间冻结、系统 / prop / 祖先偏好、隐藏 / 离屏 / 窄窗 / 零尺寸、resize、Strict Mode 清理、Canvas 失败降级和重播保焦点。逻辑绘制尺寸使用 CSS client size，避免 CSS zoom 后暂停或 resize 改变线宽；真实浏览器验证固定画幅在 zoom 1→2→1 及 resize 后静态像素保持一致。
+入口为 `/#orbit`。主画面只展示艺术与暂停控制，外侧提供主题/原始模式、重播与减少动态。控件组合示例默认折叠，展开可验证直接叠加的表单和 Surface。重播只重挂装饰组件，保留输入草稿和按钮焦点。
 
-本地 Chromium 真实展台通过 19 项检查：跨时间像素采样可见轨道运动；Space 键暂停 / 继续；系统、显式及祖先减少动态与恢复；三主题 × 400 / 520 / 880 宽度的静态 / 播放和无横向溢出；200% CSS 缩放与局部重播。另验证真实滚动离屏后像素冻结，返回可见区域后继续。页面错误为 0。页面隐藏与卸载由单元测试覆盖，不宣称已验证真实业务入口或原生平台。
+本轮 Chromium 检查通过 53 项交互检查及 18 组布局（3 主题 × 400/520/880px × 100%/200% CSS zoom），无横向溢出，按钮位于画框内，页面错误为 0。逐帧采样验证了三种物品随有效播放时间产生不同像素。暂停和主题往返保持像素；三种减少动态、离屏、模拟隐藏、上下文丢失/恢复、失败降级、迟到导入、重播草稿与卸载均通过。此处为本地开发构建证据，正式包消费及线上发布身份以发布记录为准。
 
-0.6.0 发布审阅发现初始候选的局部前景 tokens 会污染嵌入控件；现已移除这组覆盖。非 icon Logo 使用默认写法并继承所在内容的前景，无需按艺术底色另设 `theme="dark"`。上述初始截图与 19 项浏览器证据不代替修正后的组合控件验证。
+CSS zoom 不能替代浏览器原生缩放；`document.hidden` 事件模拟不能代表真实后台切换；未据此宣称原生端、任意 SSR 或宿主业务已验收。历史 0.6.0 轨道和甜甜圈单主题测试只对应当时源码，不代替本次三物品验收。
 
-合并 0.5.0 应用能力并准备 0.6.0 后，重新执行 `npm ci` 与 `npm run check`：16 个测试文件、136 项测试、TypeScript、展台构建及 CSS / SVG 产物检查全部通过。真实展台已加入 Surface 内的正文、提示、TextField 与主 / 次按钮，供发布时单独验证三主题可读性。
+![莱茵折纸鸟](assets/orbit-bird.png)
 
-仓库外生产构建验证进一步发现：动画帧可先于媒体 `change` 事件观察到减少动态，此时只停帧会留下过期的播放状态。帧检查现复用同一同步路径，更新按钮与状态并清空上一帧时间；不增加停帧后的轮询。新增该事件顺序与恢复不追赶的回归后，16 个测试文件、137 项测试（`--maxWorkers=2`）、类型检查及构建通过。
+![战术源石晶簇](assets/orbit-crystal.png)
 
-![真实组件展台](assets/orbit-backdrop.png)
+![草莓甜甜圈](assets/orbit-strawberry.png)

package/docs/SETTINGS_DIALOG.md

@@ -0,0 +1,21 @@
+# 设置导航 Dialog
+
+自 0.8.0 提供，对应 #18。默认 Dialog、Drawer 和 `sidePanel` 用法保持兼容。
+
+```tsx
+<Dialog title="设置" description="管理工作区偏好" trigger={<Button>设置</Button>}
+  navigation={<SideNav aria-label="设置导航" currentId={section} groups={groups}
+    onNavigate={(item, event) => { event.preventDefault(); setSection(item.id); }} />}>
+  <SettingsSection section={section} />
+</Dialog>
+```
+
+`navigation?: ReactNode` 专门承载左侧导航，`children` 为任务内容；不与辅助 `sidePanel` 同时使用，两者同时提供会抛出明确错误。Drawer 不提供此插槽。
+
+标题、说明和关闭动作在同一头部。内容实际宽度达到 560 CSS px 时分成约 1:3 两栏，否则导航在上、任务内容在下；容器查询会响应宿主宽度和 CSS zoom，而不是仅判断窗口宽度。长内容在弹窗内滚动，保留原字体和点击目标。
+
+应用拥有栏目、数据、权限、请求、草稿、保存和取消。库不改变 URL、不自动保存、也不会因为异步数据变化而关闭弹窗。需要保留切换栏目期间的草稿时，将状态提升到 Dialog 的宿主；关闭后的重置也由宿主明确执行。不要给 Dialog 或 ThemeProvider 使用随栏目/主题变化的 key。
+
+嵌套编辑继续使用 Radix 的焦点陷阱和焦点归还；Dialog 在布局阶段按焦点所属弹窗接管 Escape，避免快速打开内层时旧监听误关外层：先关闭内层并归还其触发器，外层仍保持打开。`onCloseAutoFocus` 仍可处理触发器已被宿主删除的场景。
+
+展台 `#settings-dialog` 包含账号草稿/异步保存/取消、长用户列表、嵌套编辑，以及项目加载/错误/空态。浏览器回归在 `scripts/check-settings-theme.js`，覆盖三主题、400/520/880/1440px、100%/200% CSS zoom、实际按钮边界、嵌套 Escape、焦点与宿主查询/URL 保持。

package/docs/THEME_PICKER.md

@@ -0,0 +1,26 @@
+# 主题预览与选择
+
+`ThemePicker` 与 `ThemePreview` 自 0.8.0 提供，对应 #20；0.6.0 及未发布的 0.7.0 候选不包含它们。
+
+```tsx
+function Appearance() {
+  const { theme, setTheme } = useTheme();
+  return <ThemePicker value={theme} onValueChange={setTheme} />;
+}
+```
+
+`ThemePicker` 是受控原生单选组：`value: ThemeName`、`onValueChange(theme)`、可选 `label`（默认“界面主题”）、`disabled` 和 `options`。默认列出三套内置主题；每个 option 的 `value` 必填，`label`、`description`、`disabled`、`previewSrc` 可选。自定义 options 不应包含重复 value。
+
+点击卡片、Space 或方向键选择会回传变更；Tab 聚焦和悬停不会应用主题。当前项同时使用勾选文字和原生 checked 状态。整组禁用及单项禁用遵循原生表单语义。库不访问 localStorage、网络业务接口或权限状态，偏好持久化由宿主决定。
+
+`ThemePreview({ theme, src? })` 是装饰性缩略图，需由外部标题描述；默认资源随组件包交付，也可传入业务自己的合成截图。加载时预留 8:5 空间，失败保留文字与选择入口；src 变化会重试。图片中的控制不能点击，也不应成为另一套可交互 UI。
+
+## 预览资源维护
+
+官方图片为 960×600 PNG，由 `preview/theme-sample.html` 使用公开组件、同一个合成场景分别渲染三种主题后生成。源码为 `preview/ThemeSample.tsx`，校验记录在 `components/assets/theme-previews/manifest.json`。不包含用户数据、业务地址或外部媒体请求。
+
+更新 tokens、主题或样本组件视觉时，同时重新生成三张图片、更新 manifest 的源文件/图片 SHA-256，并检查三张完整截图；不能只替换其中一套。使用开发服务器打开 `/preview/theme-sample.html?theme=<name>`，将视口设为 960×600，等待样本按钮和字体完成布局后截图到对应 PNG。预览是随包版本固定的样本，不跟随线上 Pages 自动变化。
+
+静态图片不会继承宿主 CSS 或 Portal 样式，因此可同时比较主题；禁止嵌套 ThemeProvider 来制作实时缩略图。正常切换只更新宿主 Provider 的 theme 属性，不为业务子树添加新的 key。
+
+展台 `#theme-picker` 包含三主题、长名称、加载/失败、禁用和弹窗内切换。浏览器回归覆盖 390/400/520/880/889/1440px、100%/200% CSS zoom、键盘选择、图片失败仍可选择、草稿节点与打开的 Dialog 保持。

package/docs/THEMING.md

@@ -143,3 +143,5 @@ import { Background, Surface } from '@linhey/rhine-design';
 若需全主题配置，在**主题根**通过 CSS 变量覆盖对应场景的底色、文字与纹理；局部调整优先用 `appearance`。局部背景不会传递给挂在主题根的 Portal，浮层仍使用主题的浮层变量。
 
 兼容已有源码调用：`roleTone` 的原有三种值与显式 `theme` / `none` 均保留；省略 `decoration` 的正文及 `AppShell` 改为 `auto`，默认纯色。需要旧版正文纹理的调用方显式传入 `decoration="theme"`。侧栏显式传入 `theme` 现在也会开启纹理；默认仍关闭。以上能力自 0.5.0 提供，不属于 npm 0.4.0。
+
+主题选择的新候选组合见 [ThemePicker / ThemePreview](THEME_PICKER.md)；静态预览避免嵌套 Provider，未发布能力需核对源码与实际安装包。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linhey/rhine-design",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public",
@@ -8,7 +8,10 @@
   },
   "type": "module",
   "description": "Rhine Design — independent design system, React components and motion patterns",
-  "repository": { "type": "git", "url": "git+https://github.com/linhay/rhine-design.git" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linhay/rhine-design.git"
+  },
   "homepage": "https://github.com/linhay/rhine-design#readme",
   "engines": {
     "node": "^22.12.0 || ^24.0.0 || >=26.0.0"
@@ -63,7 +66,9 @@
     "@radix-ui/react-dialog": "1.3.1",
     "@radix-ui/react-dropdown-menu": "2.2.1",
     "@radix-ui/react-popover": "1.3.1",
-    "@radix-ui/react-tooltip": "1.4.1"
+    "@radix-ui/react-tooltip": "1.4.1",
+    "@types/three": "0.186.0",
+    "three": "0.186.1"
   },
   "devDependencies": {
     "@testing-library/jest-dom": "7.0.1",

package/preview/CompactAccountGallery.tsx

@@ -0,0 +1,178 @@
+import { useState } from 'react';
+import {
+  Badge, Button, ButtonLink, Checkbox, Disclosure, Divider, Inline, KeyValue,
+  Notice, Progress, Select, Skeleton, Stack, StatusTimelineList, Surface, Text,
+  TextField, TimelineLegend, Tooltip, type TimelineSegment, type TimelineStatus,
+} from '../components';
+
+type AccountState = 'normal' | 'zero' | 'unknown' | 'long';
+type SubscriptionState = 'ready' | 'loading' | 'error' | 'no-link';
+
+export const compactAccountLegend = [
+  { status: 'healthy', label: '有输出', description: '有已确认输出，且此时段未见异常；历史记录不保证账号当前可用。' },
+  { status: 'recovered', label: '已恢复', description: '此时段发生过异常或重试，后续已有确认输出，且没有最终失败。' },
+  { status: 'degraded', label: '待确认', description: '此时段出现异常，但最终输出或恢复结果尚未确认；不能视作成功。' },
+  { status: 'failed', label: '失败', description: '此时段存在已确认的最终失败；其他请求有输出也不会覆盖失败证据。' },
+  { status: 'unknown', label: '未知', description: '没有可用记录、记录不完整或结果未知；未知不等于零，也不等于健康。' },
+] satisfies { status: TimelineStatus; label: string; description: string }[];
+
+const segments: TimelineSegment[] = Array.from({ length: 96 }, (_, index) => {
+  const status = compactAccountLegend[index % 13 === 0 ? 3 : index % 11 === 0 ? 2 : index % 7 === 0 ? 1 : index % 5 === 0 ? 4 : 0];
+  const start = `${String(Math.floor(index / 4)).padStart(2, '0')}:${String(index % 4 * 15).padStart(2, '0')}`;
+  const end = `${String(Math.floor((index + 1) / 4) % 24).padStart(2, '0')}:${String((index + 1) % 4 * 15).padStart(2, '0')}`;
+  return {
+    id: String(index), label: `10/23 ${start} · UTC+8`, status: status.status,
+    detail: {
+      start: `2026-10-23 ${start} · UTC+8`, end: `2026-10-${index === 95 ? '24' : '23'} ${end} · UTC+8`, reason: status.description,
+      counts: [{ id: 'output', label: '确认输出', value: status.status === 'unknown' ? null : status.status === 'failed' ? 0 : 12, unit: '次' }],
+      methodology: '按 15 分钟聚合的合成记录；缺失值保留未知，不计算健康分数。',
+    },
+  };
+});
+
+export function CompactAccountExample({ state = 'normal' }: { state?: AccountState }) {
+  const unknown = state === 'unknown', zero = state === 'zero', long = state === 'long';
+  return <Surface data-testid="compact-account-card"><Stack gap={4}>
+    <Inline gap={2} style={{ justifyContent: 'space-between' }}>
+      <Text as="h3" variant="heading">{long ? '跨区域协作工作空间 · LongResourceNameForWrappingAndReview' : '研究资源 A'}</Text>
+      <Badge tone={unknown ? 'warning' : 'success'}>{unknown ? '状态未知' : '可调度'}</Badge>
+    </Inline>
+    <Stack gap={2} data-testid="compact-quota">
+      {unknown ? <Text variant="caption">7D 剩余 — · 额度暂不可用</Text> : <Progress label="7D 剩余" value={zero ? 0 : 78} />}
+      <Text variant="caption" tone="muted">重置 {unknown ? '—' : '10/27 08:30 · 上海'}</Text>
+      <Divider />
+      <Text variant="caption" tone="muted">预测暂不可用</Text>
+    </Stack>
+    <Stack gap={1}>
+      <StatusTimelineList label="资源用量与异常记录" items={[{
+        id: 'resource-a', title: '用量与异常记录',
+        note: unknown ? '历史记录不完整，仅展示已确认的时段。' : undefined,
+        timeline: { startLabel: '10/23 00:00 · 上海', endLabel: '10/24 00:00 · 上海', segments: unknown ? segments.slice(0, 48) : segments },
+      }]} />
+      <TimelineLegend compact label="历史状态图例" items={compactAccountLegend} />
+    </Stack>
+    <Stack gap={2} data-testid="compact-account-facts">
+      <Inline gap={4}>
+        <Tooltip content="数值越小，调度优先级越高；这不是健康评分。"><Text as="span" variant="caption" tabIndex={0}>优先级 <strong>0</strong></Text></Tooltip>
+        <Text as="span" variant="caption">API-Key <strong>{unknown ? '—' : zero ? '0' : '3'}</strong></Text>
+      </Inline>
+      <KeyValue items={[
+        { key: 'expires', label: '到期', value: long ? '2027-10-24 23:59 · 上海（运营设置的账号期限）' : '未设置' },
+        ...(long ? [{ key: 'subscription-expires', label: '订阅到期', value: '2026-11-24 08:30 · 上海（当前服务套餐期限）' }] : []),
+      ]} />
+      <Inline gap={4} className="compact-gallery-fact-pair">
+        <Text as="span" variant="caption">今日消费 <strong>{unknown ? '—' : zero ? '$0.00' : long ? '$12,345.67 / $24,691.34' : '$2.40'}</strong></Text>
+        <Text as="span" variant="caption">本周期 <strong>{unknown ? '—' : zero ? '$0.00' : long ? '$123,456.78 / $246,913.56' : '$18.50'}</strong></Text>
+      </Inline>
+      <Inline gap={4} className="compact-gallery-fact-pair">
+        <Text as="span" variant="caption">今日生图 <strong>{unknown ? '—' : zero ? '0' : '8'}</strong></Text>
+        <Text as="span" variant="caption">本周期生图 <strong>{unknown ? '—' : zero ? '0' : '24'}</strong></Text>
+      </Inline>
+    </Stack>
+  </Stack></Surface>;
+}
+
+// Deliberately inert sample address and harmless download content: no service or credential is involved.
+const demoAddress = 'https://example.invalid/subscriptions/demo';
+const demoDownload = 'data:application/json;charset=utf-8,%7B%22demo%22%3Atrue%7D';
+
+export function CompactSubscriptionExample({ initialState = 'ready', showHistory = false, longValue = false }: {
+  initialState?: SubscriptionState; showHistory?: boolean; longValue?: boolean;
+}) {
+  const [state, setState] = useState(initialState);
+  const [revision, setRevision] = useState(1);
+  const [history, setHistory] = useState(showHistory ? ['2026-10-22 08:30 · 上海'] : []);
+  const [feedback, setFeedback] = useState('');
+  const [copyError, setCopyError] = useState(false);
+  const address = `${demoAddress}/${longValue ? 'cross-region-research-workspace-with-a-long-resource-name/' : ''}${revision}`;
+  const busy = state === 'loading';
+  const ready = state === 'ready';
+  function create() {
+    if (busy) return;
+    if (ready) setHistory(previous => ['2026-10-24 08:30 · 上海', ...previous]);
+    setRevision(previous => previous + 1); setState('ready'); setCopyError(false);
+    setFeedback(ready ? '已重置演示链接，旧链接失效。' : '已生成演示链接。');
+  }
+  async function copy() {
+    if (!ready) return;
+    try { await navigator.clipboard.writeText(address); setCopyError(false); setFeedback('已复制演示链接。'); }
+    catch { setCopyError(true); setFeedback('未能复制，请选择链接后手动复制。'); }
+  }
+  return <Surface data-testid="compact-subscription"><Stack gap={3}>
+    <Inline gap={2}><Text as="h3" variant="heading">我的订阅</Text><Badge>研究资源 A</Badge></Inline>
+    <Text variant="caption" tone="muted">链接可下载凭证，请勿分享。</Text>
+    {busy ? <Skeleton label="正在读取订阅链接" lines={2} /> : state === 'error' ?
+      <Notice tone="error" title="订阅链接读取失败" action={<Button variant="secondary" onClick={() => { setState('ready'); setFeedback('已重新读取演示链接。'); }}>重试</Button>} /> :
+      ready ? <TextField label="订阅链接" readOnly value={address} onFocus={event => event.currentTarget.select()} /> :
+        <Text>尚未生成订阅链接</Text>}
+    <Inline gap={2}>
+      {state === 'no-link' ? <Button onClick={create}>获取订阅链接</Button> : <>
+        <Button disabled={!ready} onClick={copy}>复制链接</Button>
+        <ButtonLink href={demoDownload} download="rhine-demo.json" rel="noreferrer" variant="secondary" disabled={!ready}>下载文件</ButtonLink>
+      </>}
+    </Inline>
+    {ready && <Stack gap={1}>
+      <Inline gap={2}>
+        <Button variant="quiet" onClick={create}>重置链接</Button>
+        <Button variant="quiet" onClick={() => { setHistory(previous => ['2026-10-24 08:30 · 上海', ...previous]); setState('no-link'); setCopyError(false); setFeedback('演示链接已撤销。'); }}>撤销链接</Button>
+      </Inline>
+      <Text variant="caption" tone="muted">重置或撤销后，旧链接失效。</Text>
+    </Stack>}
+    {!!history.length && <Disclosure title={`历史链接（${history.length}）`}>
+      <Stack gap={3}>{history.map((date, index) => <Stack gap={1} key={`${date}-${index}`}>
+        <Text variant="caption" tone="muted">{date} · 已失效</Text>
+        <Text variant="code">{demoAddress}/retired-{index + 1}</Text>
+      </Stack>)}</Stack>
+    </Disclosure>}
+    {feedback && <Text variant="caption" tone={copyError ? 'error' : 'success'} role={copyError ? 'alert' : 'status'}>{feedback}</Text>}
+  </Stack></Surface>;
+}
+
+export function CompactAccountGallery() {
+  const [accountState, setAccountState] = useState<AccountState>('normal');
+  const [subscriptionState, setSubscriptionState] = useState<SubscriptionState>('ready');
+  const [history, setHistory] = useState(false);
+  const [longValue, setLongValue] = useState(false);
+  const [width, setWidth] = useState('880');
+  const [zoom, setZoom] = useState('1');
+  return <div id="compact-account" className="compact-gallery"><Stack gap={6}>
+    <Stack gap={2}>
+      <Text as="h2" variant="section">紧凑账号摘要与凭证操作</Text>
+      <Text tone="muted">去掉重复边框和说明，保留判断与操作所需的事实。所有内容均为合成数据。</Text>
+    </Stack>
+    <Surface><Stack gap={3}>
+      <Inline gap={3}>
+        <Select label="账号读数" value={accountState} onChange={event => setAccountState(event.target.value as AccountState)}>
+          <option value="normal">正常</option><option value="zero">有效零值</option><option value="unknown">未知 / 不完整</option><option value="long">长名称 / 双成本 / 两种到期</option>
+        </Select>
+        <Select label="订阅状态" value={subscriptionState} onChange={event => setSubscriptionState(event.target.value as SubscriptionState)}>
+          <option value="ready">有链接</option><option value="loading">读取中</option><option value="error">读取失败</option><option value="no-link">尚未生成</option>
+        </Select>
+        <Select label="样机宽度" value={width} onChange={event => setWidth(event.target.value)}>
+          <option value="400">400px</option><option value="520">520px</option><option value="880">880px</option>
+        </Select>
+        <Select label="内容缩放" value={zoom} onChange={event => setZoom(event.target.value)}><option value="1">100%</option><option value="2">200%</option></Select>
+      </Inline>
+      <Inline gap={4}>
+        <Checkbox label="包含历史链接" checked={history} onChange={event => setHistory(event.target.checked)} />
+        <Checkbox label="长订阅链接" checked={longValue} onChange={event => setLongValue(event.target.checked)} />
+      </Inline>
+    </Stack></Surface>
+    <div className="compact-gallery-stage" style={{ width: Number(width) }} data-testid="compact-stage">
+      <div className="compact-gallery-examples" style={{ zoom: Number(zoom) }}>
+        <CompactAccountExample state={accountState} />
+        <CompactSubscriptionExample key={`${subscriptionState}-${history}-${longValue}`} initialState={subscriptionState} showHistory={history} longValue={longValue} />
+      </div>
+    </div>
+    <Disclosure title="按钮式链接状态"><Inline gap={3} data-testid="compact-link-states">
+      <ButtonLink href={demoDownload} download="rhine-demo.json" busy busyLabel="正在准备演示文件">准备中的下载</ButtonLink>
+      <ButtonLink href={demoDownload} download="rhine-demo.json" disabled variant="secondary">不可用的下载</ButtonLink>
+      <ButtonLink href="#compact-account" target="_blank" rel="noreferrer" variant="secondary">在新标签页打开样机</ButtonLink>
+    </Inline></Disclosure>
+    <Disclosure title="跨卡历史交互"><Stack gap={6} data-testid="compact-independent-timelines">
+      {['独立卡片 A', '独立卡片 B'].map(title => <Surface key={title}><StatusTimelineList label={`${title}历史`} items={[{
+        id: title, title, timeline: { startLabel: '10/23 00:00', endLabel: '10/24 00:00', segments },
+      }]} /></Surface>)}
+    </Stack></Disclosure>
+  </Stack></div>;
+}

package/preview/DateRangeFilterGallery.tsx

@@ -0,0 +1,109 @@
+import { useState } from 'react';
+import { Button, DateRangePicker, Divider, Icon, Inline, Popover, SegmentedControl, Stack, Surface, Text, type DateRange } from '../components';
+
+const quickRanges = [
+  { value: 'today', label: '今天', range: { start: '2026-10-24', end: '2026-10-24' } },
+  { value: 'yesterday', label: '昨天', range: { start: '2026-10-23', end: '2026-10-23' } },
+  { value: 'week', label: '本周', range: { start: '2026-10-19', end: '2026-10-24' } },
+];
+const moreRanges = [
+  { label: '最近 7 天', range: { start: '2026-10-18', end: '2026-10-24' } },
+  { label: '最近 30 天', range: { start: '2026-09-25', end: '2026-10-24' } },
+  { label: '本月', range: { start: '2026-10-01', end: '2026-10-24' } },
+  { label: '上月', range: { start: '2026-09-01', end: '2026-09-30' } },
+];
+const min = '2025-01-01', max = '2026-12-31';
+const rangeLabel = ({ start, end }: DateRange) => `${start} — ${end}`;
+
+// Preview composition only: the host owns presets, calendar boundaries and data queries.
+export function DateRangeFilterExample({ label = '时间范围', initialValue = quickRanges[0].range, disabled = false, longLabels = false }: {
+  label?: string; initialValue?: DateRange; disabled?: boolean; longLabels?: boolean;
+}) {
+  const [value, setValue] = useState(initialValue);
+  const [draft, setDraft] = useState(value);
+  const [open, setOpen] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [applied, setApplied] = useState(0);
+  const selected = quickRanges.find(item => item.range.start === value.start && item.range.end === value.end)?.value ?? '';
+  const canApply = !disabled && !!draft.start && !!draft.end && draft.start <= draft.end && draft.start >= min && draft.end <= max && !error;
+  const commit = (range: DateRange) => {
+    if (disabled) return;
+    setValue(range); setApplied(count => count + 1); setOpen(false);
+  };
+  const changeOpen = (next: boolean) => {
+    if (next && disabled) return;
+    if (next) { setDraft(value); setError(null); }
+    setOpen(next);
+  };
+  return <Stack gap={3}>
+    <Inline gap={2} role="group" aria-label={label}>
+      <Text variant="caption" tone="muted">{label}</Text>
+      <SegmentedControl label={`${label}快捷选择`} items={quickRanges.map(item => ({
+        value: item.value, label: longLabels ? `${item.label}的完整自然日范围` : item.label, disabled,
+      }))} value={selected} onValueChange={key => {
+        const preset = quickRanges.find(item => item.value === key);
+        if (preset) commit(preset.range);
+      }} />
+      <Popover title={`${label}设置`} open={open} onOpenChange={changeOpen} trigger={
+        <Button variant="secondary" disabled={disabled} aria-label={`${label}：${rangeLabel(value)}，选择日期`}>
+          {rangeLabel(value)} <Icon name="chevronDown" size={16} />
+        </Button>
+      }>
+        <Stack gap={4}>
+          <Stack gap={2}>
+            <Text variant="caption" tone="muted">选择预设后立即应用</Text>
+            <Inline gap={2} aria-label="更多时间预设">
+              {moreRanges.map(item => <Button key={item.label} variant="secondary" onClick={() => commit(item.range)}>{item.label}</Button>)}
+            </Inline>
+          </Stack>
+          <Divider />
+          <form onSubmit={event => {
+            event.preventDefault();
+            if (canApply && event.currentTarget.checkValidity()) commit(draft);
+          }}>
+            <Stack gap={3}>
+              <DateRangePicker label="自定义日期" value={draft} onValueChange={setDraft} onValidationChange={setError}
+                min={min} max={max} required clearable={false} hint="填写完整日期后，点击应用。" />
+              <Inline gap={2}>
+                <Button variant="secondary" onClick={() => setOpen(false)}>取消</Button>
+                <Button type="submit" disabled={!canApply}>应用日期</Button>
+              </Inline>
+            </Stack>
+          </form>
+        </Stack>
+      </Popover>
+    </Inline>
+    <Text variant="caption" tone="muted" role="status">已应用：{rangeLabel(value)} · 本次操作 {applied} 次</Text>
+  </Stack>;
+}
+
+export function DateRangeFilterGallery() {
+  return <section id="date-range-filter">
+    <div className="ds-section-title"><span>RANGE</span><h2>日期筛选 · 快捷选择与自定义</h2></div>
+    <p className="ds-caption">常用日期是一组互斥选项；具体日期持续可见。更多预设即选即用，自定义日期在确认后生效。</p>
+    <Stack gap={4}>
+      <Surface>
+        <Stack gap={4}>
+          <Text as="h3" variant="heading">日常筛选</Text>
+          <DateRangeFilterExample />
+          <Text variant="caption" tone="muted">固定演示日期为 2026-10-24。选择只更新本地样例，不请求业务数据。</Text>
+        </Stack>
+      </Surface>
+      <Surface>
+        <Stack gap={4}>
+          <Text as="h3" variant="heading">跨年范围与长标签</Text>
+          <DateRangeFilterExample label="对比时间范围" initialValue={{ start: '2025-12-28', end: '2026-01-06' }} longLabels />
+          <Text variant="caption" tone="muted">超出快捷项的日期不冒充任何预设。窄容器允许换行，完整年份和操作保留。</Text>
+        </Stack>
+      </Surface>
+      <Surface>
+        <Stack gap={4}>
+          <Text as="h3" variant="heading">暂不可更改</Text>
+          <DateRangeFilterExample label="归档日期范围" disabled />
+          <Text variant="caption" tone="muted">归档结果的统计范围固定，保持日期可读。</Text>
+        </Stack>
+      </Surface>
+      <Text variant="caption" tone="muted">方向键切换快捷项；Escape 或取消退出草稿并归还焦点，点击外部控件按原生焦点行为继续。所有主题使用同一组公开组件。</Text>
+    </Stack>
+  </section>;
+}