@linhey/rhine-design 0.5.0 → 0.8.0

package/skills/rhine-design/SKILL.md

@@ -2,7 +2,7 @@
 name: rhine-design
 description: Use Rhine Design components and specifications to design, implement, or review React UI, typography, themes, and motion. Apply when a project uses Rhine Design or the user requests its visual language or component system.
 metadata:
-  version: "0.5.0"
+  version: "0.8.0"
 ---
 
 # Rhine Design · 莱茵设计
@@ -13,7 +13,7 @@ Use the installed version's components and contracts to build consistent interfa
 
 ## Locate the matching source
 
-Package: `@linhey/rhine-design`. GitHub: `linhay/rhine-design` (different account spelling). This skill targets 0.5.0, including application shells, advanced forms, media, controlled tables and monitoring charts. Theme and navigation APIs require at least 0.4.0; the new application APIs require 0.5.0. Check installed exports before adoption.
+Package: `@linhey/rhine-design`. GitHub: `linhay/rhine-design` (different account spelling). This skill targets 0.8.0, including OrbitBackdrop, application shells, advanced forms, media, controlled tables and monitoring charts. Theme and navigation APIs require at least 0.4.0; application APIs require 0.5.0 and OrbitBackdrop requires 0.6.0. Check installed exports before adoption.
 
 Find the package in the host's dependencies, normally `node_modules/@linhey/rhine-design/`, or its registered source checkout. Verify `package.json` name/version before using the paths below. Paths in references are relative to that package root, not the copied skill directory. Read installed types and source when versions differ; do not infer a new API from this skill. If the package is unavailable, use the task's supplied design sources and identify the missing implementation evidence.
 
@@ -56,5 +56,6 @@ Required issue content:
 - Host state determines data, selection and operation outcomes. Search and pagination remain host/server responsibilities; busy indicators never imply success.
 - For multi-field failures, preserve input and focus a summary only after failed submission; links return to fields without changing routing. Use SideNav/Breadcrumbs/Steps only when exported by the installed source.
 - Monitoring shows units, freshness and stale/unknown states; errors must not rely on color, flashing or transient toasts.
+- Design from the user's current task: keep identity, available actions, results and decision-relevant consequences; remove duplicate state labels and implementation prose. Reveal history on demand. Inside an existing Surface prefer borderless read-only summaries and paired facts; never compress by shrinking business text, cropping values, hiding unknown/error states or merging distinct costs/expiry meanings. See `docs/COMPACT_ACCOUNT_PATTERNS.md` when present; its new APIs are source candidates, not npm 0.6.0 features.
 - Motion explains a change. Respect reduced motion, cancellation and replay; startup decoration never blocks real readiness. Preview-only experiments are not exported components.
 - Keep independent release boundaries: do not change unrelated products or publish packages merely because this skill was invoked.

package/skills/rhine-design/references/API_MAP.md

@@ -5,20 +5,28 @@ All paths are relative to the matching package root. `package.json` exports, `co
 | Exports | Source |
 | --- | --- |
 | TrendChart, StackedBar；StatusTimeline.detail（0.5.0） | `components/Charts.tsx`、`components/StatusTimeline.tsx`；`docs/APPLICATION_COMPONENTS.md`，未知不补零；键盘逐点查看、按ID受控高亮/详情、valueFormatter |
-| Background, AppShell（0.5.0） | `components/Background.tsx`、`components/AppShell.tsx`；`docs/APPLICATION_COMPONENTS.md`；桌面open与临时drawerOpen独立，断点为容器CSS布局宽度 |
+| Background, AppShell（0.5.0）；AppShellToggle（0.8.0） | `components/Background.tsx`、`components/AppShell.tsx`；`docs/APPLICATION_COMPONENTS.md`；桌面open与临时drawerOpen独立，断点为容器CSS布局宽度 |
+| AppShell.contentHeader（0.8.0） | `components/AppShell.tsx`；`docs/APPLICATION_COMPONENTS.md`；正文列常驻导航插槽，与正文滚动区分离，组合 AppShellToggle / Inline / 标题与上下文操作 |
 | MediaCard, MediaViewer（0.5.0） | `components/Media.tsx`；中性画布，不嵌套主题 |
+| Media 主题重设计（0.8.0） | `components/media-parity.css`；`docs/APPLICATION_COMPONENTS.md`；卡片、标签与查看器操作/信息栏随宿主主题，仅媒体画布中性；选择与重试独立 |
 | DateField, DateRangePicker, NumberField, TreeSelect, RemoteMultiSelect（0.5.0） | `components/AdvancedForms.tsx`；请求、时区和查询由宿主负责；只读/校验/多选键盘及AntD/MUI保留差异见 `docs/ANTD_MUI_AUDIT.md` |
+| Date presets + confirmed custom range（组合，无新增导出） | `docs/DATE_RANGE_FILTER.md`、`preview/DateRangeFilterGallery.tsx`；复用 SegmentedControl + Button + Popover + DateRangePicker，宿主负责时区、预设和查询 |
 | ThemeProvider, useTheme, themes, ThemeName, ThemeProviderProps (0.4.0；`@linhey/rhine-design/theme`) | `components/theme.tsx`；契约 `docs/THEMING.md` |
+| OrbitBackdrop, OrbitBackdropProps (0.6.0) | `components/OrbitBackdrop.tsx`；契约 `docs/ORBIT_BACKDROP.md`；`components/orbitRenderer.ts` 为内部绘制实现 |
+| NeutronStarBackdrop, NeutronStarBackdropProps (0.8.0) | `components/NeutronStarBackdrop.tsx`；契约 `docs/NEUTRON_STAR_BACKDROP.md`；Three.js drawing modules are internal |
 | Logo | `components/Logo.tsx` |
 | Text | `components/Typography.tsx` |
 | Select | `components/Select.tsx` |
 | Toolbar | `components/Toolbar.tsx` |
 | Icon, IconButton, Link, CopyButton | `components/Actions.tsx` |
+| ButtonLink（0.8.0） | `components/Actions.tsx`；`docs/COMPACT_ACCOUNT_PATTERNS.md`；原生 anchor/下载语义，同 Button 视觉，busy 保焦点并移除 href |
 | Divider, Stack, Inline, Grid | `components/Layout.tsx` |
 | Metric, KeyValue, DataTable, Pagination | `components/Data.tsx` |
 | Checkbox, RadioGroup, Switch, Textarea, SearchField, Combobox | `components/Forms.tsx` |
 | Dialog, Drawer (0.4.0), ConfirmDialog, Popover, Menu, Tooltip | `components/Overlays.tsx` |
 | StatusTimeline, TimelineLegend (0.4.0) | `components/StatusTimeline.tsx`；历史证据，不计算健康评分 |
+| TimelineLegend compact/items（0.8.0） | `components/StatusTimeline.tsx`；`docs/COMPACT_ACCOUNT_PATTERNS.md`；宿主短标签/完整规则，一行局部滚动，hover/focus/touch 详情 |
+| StatusTimelineList（0.8.0） | `components/StatusTimelineList.tsx`、`docs/APPLICATION_COMPONENTS.md`；稳定行 ID、标题/摘要/紧凑时间条组合、单一详情，宿主保留请求与分页；展台 `/#monitoring` |
 | SideNav, Breadcrumbs, Steps (0.4.0) | `components/Navigation.tsx` |
 | Fieldset, ErrorSummary (0.4.0) | `components/FormWorkflow.tsx` |
 | Toast | `components/Toast.tsx` |
@@ -35,8 +43,13 @@ rg -n 'ConfirmDialog|DataTable|Combobox' tests preview
 API decisions that commonly matter:
 
 - `Select` uses a native single-select; searchable candidates use `Combobox`.
+- `SelectionCard.showIndicator=false` visually hides the native input while preserving keyboard focus, accessible state and card selection styling (0.8.0).
 - `SelectionCard` uses checkbox semantics; the host determines single-selection policy. Do not nest other interactive controls in it.
 - `Text`'s `as` chooses semantics; `variant` chooses visual hierarchy.
 - `Logo` accepts `wordmark` and `label`; its `theme` affects the logo, not the full component library.
+- `OrbitBackdrop` is decorative artwork with built-in pause / resume. Its `reducedMotion` prop can strengthen but never override system reduction; see `docs/ORBIT_BACKDROP.md` for visibility, narrow-window and fallback behavior. In 0.8.0, theme artwork uses an origami paper bird, originium crystals or a strawberry donut; `appearance="original"` preserves the initial orbit. It does not express loading or business progress.
+- `NeutronStarBackdrop` preserves the separate neutron-star artwork. `appearance="theme"` follows existing theme tokens; `original` restores its deep-space palette without replacing the host control theme. It lazy-loads WebGL, freezes under reduction or visibility constraints, and retains static art on failure. It requires 0.8.0 or later; see `docs/NEUTRON_STAR_BACKDROP.md`.
 - `Toast` presents one notification, not a global queue. `DataTable` is not a query or table-state engine.
 - Components in `preview/` are demonstrations. Public API must resolve through a `package.json` export; theme APIs use the separate `/theme` entry.
+
+Available since 0.8.0 (check installed exports): `ThemePicker` / `ThemePreview` in `components/ThemePicker.tsx`, contract `docs/THEME_PICKER.md`; `Dialog.navigation` in `components/Overlays.tsx`, contract `docs/SETTINGS_DIALOG.md`; shared floating CSS zoom behavior in `docs/FLOATING_OVERLAYS.md`.

package/skills/rhine-design/references/TASK_MAP.md

@@ -5,20 +5,27 @@ Resolve the matching package root as described in SKILL.md. Open the first relev
 | Task | First reference (relative to package root) | Implementation / example |
 | --- | --- | --- |
 | Application shell, backgrounds, media, advanced inputs, controlled tables | `docs/APPLICATION_COMPONENTS.md` (0.5.0) | `preview/ExtensionsGallery.tsx`; `/#app-shell`, `/#advanced-forms`, `/#advanced-data`, `/#media` |
+| Workspace header, duplicate page titles, optional breadcrumbs | `docs/APPLICATION_COMPONENTS.md` → 平级工作区顶部操作区 (source guideline) | `preview/ExtensionsGallery.tsx`; `/#app-shell`; keep status/actions, navigation restore and accessible page identity |
 | Theme integration, switching, controlled preferences | `docs/THEMING.md` (0.4.0) | `components/theme.tsx`, `preview/GalleryShell.tsx` |
 | Scenario selection, navigation, form recovery, monitoring | `docs/INTERACTION_PATTERNS.md` (0.4.0; check installed version) | `preview/PatternGallery.tsx`; research in `docs/REFERENCE_RESEARCH.md` |
+| Date presets, visible date ranges, custom-range drafts and confirmation | `docs/DATE_RANGE_FILTER.md` (source pattern using existing 0.6.0 APIs) | `preview/DateRangeFilterGallery.tsx`; `/#date-range-filter`; no public DateRangeFilter component |
 | Visual direction, colors, spacing, layout | `docs/DESIGN_SYSTEM.md` | `components/tokens.css`, `components/Layout.tsx` |
 | Spacing, grouping, card composition | `components/SPACING.md` (0.4.0 docs; existing gap API works in 0.3.0) | `components/Layout.tsx`, `preview/SpacingGallery.tsx`; `/#spacing` |
 | Text hierarchy, line height, paragraphs, Chinese/Latin text, metrics | `components/TYPOGRAPHY.md` | `components/Typography.tsx`, `preview/LineHeightGallery.tsx`; `/#typography` |
 | Logo, light/dark variants, wordmark | `components/README.md` → 品牌标志 | `components/Logo.tsx`, `components/assets/logo.svg` |
 | Buttons, navigation, basic states | `components/README.md` → 组件契约 | `components/components.tsx` |
+| Task-centered content reduction, borderless account summaries, credential actions, compact legends | `docs/COMPACT_ACCOUNT_PATTERNS.md` (source candidates; not npm 0.6.0) | `preview/CompactAccountGallery.tsx`; `/#compact-account`; ButtonLink + StatusTimelineList + TimelineLegend |
 | Forms, selection, combobox, data tables | `components/COMMON_COMPONENTS.md` | Use API_MAP for the source file |
 | Modal, menu, popover, tooltip, feedback | `components/COMMON_COMPONENTS.md` | `components/Overlays.tsx`, `components/Toast.tsx` |
 | Transition, replay, cancellation, reduced motion | `components/MOTION.md` | `preview/`, `components/styles.css` |
 | Startup sequence, logo assembly, ready handoff | `components/STARTUP.md` | Search `startup` in `preview/`; not a public Startup component |
+| Orbit artwork, decorative Canvas, pause / resume, reduced motion | `docs/ORBIT_BACKDROP.md` (base 0.6.0, themed objects 0.8.0) | `components/OrbitBackdrop.tsx`, internal `components/orbitRenderer.ts`; `/#orbit` |
+| Neutron-star artwork, themed WebGL, async loading, static fallback | `docs/NEUTRON_STAR_BACKDROP.md` (0.8.0) | `components/NeutronStarBackdrop.tsx`; `preview/NeutronStarGallery.tsx`; `/#neutron-star` |
 | Missing capability or system coverage | `docs/DESIGN_SYSTEM_AUDIT.md` | Verify status against `components/index.ts` |
 | Version upgrade | `CHANGELOG.md` | Installed `package.json`, current types |
 
-Run the library showcase with `npm ci && npm run dev` in a source checkout. Default port is 18309; sections include `/#foundation`, `/#typography`, `/#brand`, `/#motion` and `/#startup`. Do not assume another project's server or local filesystem layout.
+Run the library showcase with `npm ci && npm run dev` in a source checkout. Default port is 18309; sections include `/#foundation`, `/#typography`, `/#brand`, `/#motion`, `/#startup` and `/#orbit`, plus `/#neutron-star` and `/#compact-account` in 0.8.0. Do not assume another project's server or local filesystem layout.
 
 For host pages, keep product-specific drafts in the host project. The library's `preview/` demonstrates reusable behavior, not business APIs. Labels such as “candidate” or “preview” in motion docs identify experiments; check whether the behavior is actually exported before integrating it.
+
+For 0.8.0 theme-comparison cards, settings navigation, or floating CSS zoom boundaries, read `docs/THEME_PICKER.md`, `docs/SETTINGS_DIALOG.md`, and `docs/FLOATING_OVERLAYS.md` respectively. Preview routes: `#theme-picker`, `#settings-dialog`, `#overlay-bounds`. Do not infer package availability from the main gallery.

package/skills/rhine-design/references/integration.md

@@ -2,7 +2,7 @@
 
 ## Supported baseline
 
-Rhine Design 0.5.0 ships TypeScript/TSX, CSS and SVG source for React 19 + Vite. Install `@linhey/rhine-design`; GitHub remains `linhay/rhine-design`. Check the installed package's engine and peer dependencies. Node 24 is the development baseline. Do not assume precompiled JavaScript, arbitrary SSR support or a complete dark theme.
+Rhine Design 0.8.0 ships TypeScript/TSX, CSS and SVG source for React 19 + Vite. Install `@linhey/rhine-design`; GitHub remains `linhay/rhine-design`. Check the installed package's engine and peer dependencies. Node 24 is the development baseline. Do not assume precompiled JavaScript, arbitrary SSR support or a complete dark theme.
 
 ```tsx
 import { Button, Surface, Text } from '@linhey/rhine-design';

package/tests/AppShellControls.test.tsx

@@ -0,0 +1,82 @@
+import { useState } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { AppShell, AppShellToggle } from '../components';
+import { ThemeProvider } from '../components/theme';
+
+function Demo({ navigationBar = false }: { navigationBar?: boolean }) {
+  const [open, setOpen] = useState(true);
+  return <ThemeProvider><AppShell controls="inline" layout="single" navigation={{ label: '导航', open, onOpenChange: setOpen,
+    content: <div aria-label="品牌区"><strong>Workspace</strong><AppShellToggle placement="panel" iconOnly /><button>导航项</button></div> }}
+    contentHeader={navigationBar ? <nav aria-label="工作区导航"><AppShellToggle placement="content" iconOnly /><h1>收件箱</h1></nav> : undefined}>
+    {!navigationBar && <AppShellToggle placement="content" iconOnly />}<input aria-label="草稿" defaultValue="保留" />
+  </AppShell></ThemeProvider>;
+}
+
+afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); });
+describe('inline shell controls', () => {
+  it('keeps navigation outside the body and preserves drafts when navigation changes', () => {
+    vi.stubGlobal('ResizeObserver', class { observe() {} disconnect() {} });
+    vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockReturnValue(1040);
+    const { rerender } = render(<Demo navigationBar />);
+    const input = screen.getByLabelText('草稿');
+    fireEvent.change(input, { target: { value: '未保存的编辑' } });
+    expect(screen.getByRole('region', { name: '正文' })).not.toContainElement(screen.getByRole('navigation', { name: '工作区导航' }));
+    const collapse = screen.getByRole('button', { name: '收起导航' });
+    collapse.focus(); fireEvent.click(collapse);
+    const expand = within(screen.getByRole('navigation', { name: '工作区导航' })).getByRole('button', { name: '展开导航' });
+    expect(expand).toHaveFocus();
+    fireEvent.click(expand);
+    rerender(<Demo />);
+    expect(screen.getByLabelText('草稿')).toBe(input);
+    expect(input).toHaveValue('未保存的编辑');
+  });
+  it('collapses from the brand and restores focus without a standalone header', () => {
+    vi.stubGlobal('ResizeObserver', class { observe() {} disconnect() {} });
+    vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockReturnValue(1040);
+    const { container } = render(<Demo />);
+    expect(container.querySelector('.rhine-shell__header')).toBeNull();
+    const input = screen.getByLabelText('草稿');
+    const collapse = within(screen.getByLabelText('品牌区')).getByRole('button', { name: '收起导航' });
+    collapse.focus(); fireEvent.click(collapse);
+    const expand = screen.getByRole('button', { name: '展开导航' });
+    expect(expand).toHaveFocus();
+    fireEvent.click(expand);
+    expect(screen.getByRole('button', { name: '收起导航' })).toHaveFocus();
+    expect(screen.getByLabelText('草稿')).toBe(input);
+    expect(screen.queryByRole('dialog')).toBeNull();
+  });
+  it('opens the narrow drawer and returns focus after Escape', async () => {
+    vi.stubGlobal('ResizeObserver', class { observe() {} disconnect() {} });
+    vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockReturnValue(400);
+    render(<Demo />);
+    const trigger = screen.getByRole('button', { name: '导航' });
+    trigger.focus(); fireEvent.click(trigger);
+    const dialog = await screen.findByRole('dialog', { name: '导航' });
+    expect(within(dialog).getByText('Workspace')).toBeVisible();
+    expect(screen.queryByRole('button', { name: '收起导航' })).toBeNull();
+    fireEvent.keyDown(dialog, { key: 'Escape' });
+    await waitFor(() => expect(trigger).toHaveFocus());
+  });
+  it('moves focused navigation to the content trigger when the container becomes narrow', () => {
+    let resize = () => {};
+    vi.stubGlobal('ResizeObserver', class { constructor(callback: () => void) { resize = callback; } observe() {} disconnect() {} });
+    const width = vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockReturnValue(1040);
+    render(<Demo />);
+    screen.getByRole('button', { name: '导航项' }).focus();
+    width.mockReturnValue(400); act(resize);
+    expect(screen.getByRole('button', { name: '导航' })).toHaveFocus();
+  });
+  it('returns to the brand after closing a drawer that was resized to desktop', async () => {
+    let resize = () => {};
+    vi.stubGlobal('ResizeObserver', class { constructor(callback: () => void) { resize = callback; } observe() {} disconnect() {} });
+    const width = vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockReturnValue(400);
+    render(<Demo />);
+    fireEvent.click(screen.getByRole('button', { name: '导航' }));
+    const dialog = await screen.findByRole('dialog', { name: '导航' });
+    width.mockReturnValue(1040); act(resize);
+    expect(dialog).toBeVisible();
+    fireEvent.keyDown(dialog, { key: 'Escape' });
+    await waitFor(() => expect(screen.getByRole('button', { name: '收起导航' })).toHaveFocus());
+  });
+});

package/tests/ButtonLink.test.tsx

@@ -0,0 +1,94 @@
+import { createRef } from 'react';
+import { fireEvent, render, screen } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { ButtonLink } from '../components';
+
+describe('ButtonLink', () => {
+  it('keeps native link and download attributes and forwards the anchor ref', () => {
+    const ref = createRef<HTMLAnchorElement>();
+    render(<ButtonLink ref={ref} href="#download" download="example.json" target="_blank" rel="noopener" variant="secondary" className="host-action">下载文件</ButtonLink>);
+    const link = screen.getByRole('link', { name: '下载文件' });
+    expect(link.tagName).toBe('A');
+    expect(ref.current).toBe(link);
+    expect(link).toHaveAttribute('href', '#download');
+    expect(link).toHaveAttribute('download', 'example.json');
+    expect(link).toHaveAttribute('target', '_blank');
+    expect(link).toHaveAttribute('rel', 'noopener');
+    expect(link).toHaveClass('rhine-button', 'rhine-button--secondary', 'host-action');
+    expect(link).not.toHaveAttribute('aria-disabled');
+    expect(link).not.toHaveAttribute('aria-busy');
+    expect(link.tabIndex).toBe(0);
+  });
+
+  it('leaves primary, modified and auxiliary clicks to the browser and caller', () => {
+    const click = vi.fn();
+    const auxiliary = vi.fn();
+    render(<ButtonLink href="#download" onClick={click} onAuxClick={auxiliary}>下载文件</ButtonLink>);
+    const link = screen.getByRole('link');
+    for (const modifiers of [{}, { ctrlKey: true }, { metaKey: true }, { shiftKey: true }]) {
+      const event = new MouseEvent('click', { bubbles: true, cancelable: true, ...modifiers });
+      expect(fireEvent(link, event)).toBe(true);
+      expect(event.defaultPrevented).toBe(false);
+      expect(click.mock.lastCall?.[0].ctrlKey).toBe(Boolean('ctrlKey' in modifiers && modifiers.ctrlKey));
+      expect(click.mock.lastCall?.[0].metaKey).toBe(Boolean('metaKey' in modifiers && modifiers.metaKey));
+    }
+    const event = new MouseEvent('auxclick', { button: 1, bubbles: true, cancelable: true });
+    expect(fireEvent(link, event)).toBe(true);
+    expect(event.defaultPrevented).toBe(false);
+    expect(click).toHaveBeenCalledTimes(4);
+    expect(auxiliary).toHaveBeenCalledTimes(1);
+  });
+
+  it('lets the caller cancel native navigation', () => {
+    render(<ButtonLink href="#download" onClick={event => event.preventDefault()}>下载文件</ButtonLink>);
+    expect(fireEvent.click(screen.getByRole('link'))).toBe(false);
+  });
+
+  it('removes disabled destinations and blocks primary and auxiliary activation', () => {
+    const click = vi.fn();
+    const auxiliary = vi.fn();
+    const delegated = vi.fn();
+    render(<div onClick={delegated} onAuxClick={delegated}><ButtonLink href="#download" disabled tabIndex={0} onClick={click} onAuxClick={auxiliary}>下载文件</ButtonLink></div>);
+    const link = screen.getByRole('link', { name: '下载文件' });
+    expect(link).not.toHaveAttribute('href');
+    expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link.tabIndex).toBe(-1);
+    expect(fireEvent.click(link, { ctrlKey: true })).toBe(false);
+    expect(fireEvent(link, new MouseEvent('auxclick', { button: 1, bubbles: true, cancelable: true }))).toBe(false);
+    expect(click).not.toHaveBeenCalled();
+    expect(auxiliary).not.toHaveBeenCalled();
+    expect(delegated).not.toHaveBeenCalled();
+  });
+
+  it('retains focus while busy and restores the destination when ready', () => {
+    const click = vi.fn();
+    const auxiliary = vi.fn();
+    const { rerender } = render(<ButtonLink href="#download" onClick={click} onAuxClick={auxiliary}>下载文件</ButtonLink>);
+    const link = screen.getByRole('link');
+    link.focus();
+    rerender(<ButtonLink href="#download" busy busyLabel="准备文件" onClick={click} onAuxClick={auxiliary}>下载文件</ButtonLink>);
+    expect(link).toHaveFocus();
+    expect(link).toHaveAttribute('aria-busy', 'true');
+    expect(link).toHaveAttribute('aria-disabled', 'true');
+    expect(link).toHaveAccessibleName('准备文件');
+    expect(link).not.toHaveAttribute('href');
+    expect(link.tabIndex).toBe(0);
+    expect(fireEvent.click(link)).toBe(false);
+    expect(fireEvent(link, new MouseEvent('auxclick', { button: 1, bubbles: true, cancelable: true }))).toBe(false);
+    expect(click).not.toHaveBeenCalled();
+    expect(auxiliary).not.toHaveBeenCalled();
+    rerender(<ButtonLink href="#ready" onClick={click}>下载文件</ButtonLink>);
+    expect(link).toHaveFocus();
+    expect(link).toHaveAttribute('href', '#ready');
+    expect(link).not.toHaveAttribute('aria-disabled');
+    expect(link).not.toHaveAttribute('aria-busy');
+  });
+
+  it('keeps caller focus policy while busy and gives disabled precedence', () => {
+    const { rerender } = render(<ButtonLink href="#download" busy tabIndex={-1}>下载文件</ButtonLink>);
+    expect(screen.getByRole('link').tabIndex).toBe(-1);
+    rerender(<ButtonLink href="#download" busy disabled tabIndex={0}>下载文件</ButtonLink>);
+    expect(screen.getByRole('link').tabIndex).toBe(-1);
+    expect(screen.getByRole('link')).toHaveAttribute('data-disabled', 'true');
+  });
+});

package/tests/CompactAccountGallery.test.tsx

@@ -0,0 +1,116 @@
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { CompactAccountExample, CompactAccountGallery, CompactSubscriptionExample } from '../preview/CompactAccountGallery';
+
+const originalClipboard = Object.getOwnPropertyDescriptor(navigator, 'clipboard');
+afterEach(() => {
+  vi.restoreAllMocks();
+  if (originalClipboard) Object.defineProperty(navigator, 'clipboard', originalClipboard);
+  else Reflect.deleteProperty(navigator, 'clipboard');
+});
+function demo(content: React.ReactNode) { return render(<div className="rhine-theme">{content}</div>); }
+
+describe('compact account composition', () => {
+  it('preserves valid zero, unknown values and distinct expiry meanings', () => {
+    const view = demo(<CompactAccountExample state="zero" />);
+    expect(screen.getByRole('progressbar', { name: '7D 剩余' })).toHaveAttribute('aria-valuenow', '0');
+    expect(within(screen.getByTestId('compact-account-facts')).getAllByText('0')).toHaveLength(4);
+    expect(within(screen.getByTestId('compact-account-facts')).getAllByText('$0.00')).toHaveLength(2);
+    view.rerender(<div className="rhine-theme"><CompactAccountExample state="unknown" /></div>);
+    expect(screen.queryByRole('progressbar')).not.toBeInTheDocument();
+    expect(screen.getByText('7D 剩余 — · 额度暂不可用')).toBeVisible();
+    expect(screen.getByText('历史记录不完整，仅展示已确认的时段。')).toBeVisible();
+    expect(within(screen.getByTestId('compact-account-facts')).getAllByText('—')).toHaveLength(5);
+    view.rerender(<div className="rhine-theme"><CompactAccountExample state="long" /></div>);
+    expect(screen.getByText('到期')).toBeVisible();
+    expect(screen.getByText('订阅到期')).toBeVisible();
+    expect(screen.getByText('$12,345.67 / $24,691.34')).toBeVisible();
+    expect(screen.getByText('$123,456.78 / $246,913.56')).toBeVisible();
+  });
+
+  it('uses the shared timeline with inspectable evidence and compact custom legend', async () => {
+    demo(<CompactAccountExample />);
+    expect(screen.getByRole('list', { name: '资源用量与异常记录' })).toBeInTheDocument();
+    const slider = screen.getByRole('slider', { name: '用量与异常记录 历史时段' });
+    act(() => slider.focus());
+    const details = await screen.findByRole('dialog', { name: '用量与异常记录 历史时段时段详情' });
+    expect(within(details).getByText(/按 15 分钟聚合的合成记录/)).toBeVisible();
+    const legend = screen.getByRole('list', { name: '历史状态图例' });
+    for (const label of ['有输出', '已恢复', '待确认', '失败', '未知']) expect(within(legend).getByText(label)).toBeVisible();
+  });
+
+  it('exposes long, narrow and scaled review settings without changing business values', () => {
+    demo(<CompactAccountGallery />);
+    fireEvent.change(screen.getByLabelText('账号读数'), { target: { value: 'long' } });
+    fireEvent.change(screen.getByLabelText('样机宽度'), { target: { value: '400' } });
+    fireEvent.change(screen.getByLabelText('内容缩放'), { target: { value: '2' } });
+    expect(screen.getByTestId('compact-stage')).toHaveStyle({ width: '400px' });
+    expect(screen.getByText('$123,456.78 / $246,913.56')).toBeVisible();
+    fireEvent.click(screen.getByLabelText('包含历史链接'));
+    expect(screen.getByText('历史链接（1）')).toBeVisible();
+  });
+});
+
+describe('compact credential actions composition', () => {
+  it('shows a native download action and no redundant empty history or repeated state', () => {
+    demo(<CompactSubscriptionExample />);
+    const download = screen.getByRole('link', { name: '下载文件' });
+    expect(download.tagName).toBe('A');
+    expect(download).toHaveAttribute('download', 'rhine-demo.json');
+    expect(download).toHaveClass('rhine-button');
+    expect(download.getAttribute('href')).toMatch(/^data:application\/json/);
+    expect(screen.queryByText(/历史链接/)).not.toBeInTheDocument();
+    expect(screen.queryByText('当前链接')).not.toBeInTheDocument();
+    expect(screen.queryByText('已生成')).not.toBeInTheDocument();
+    expect(screen.getByText('链接可下载凭证，请勿分享。')).toBeVisible();
+    expect(screen.getByText('重置或撤销后，旧链接失效。')).toBeVisible();
+  });
+
+  it('copies only the synthetic address and leaves it available after clipboard failure', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined);
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } });
+    demo(<CompactSubscriptionExample />);
+    fireEvent.click(screen.getByRole('button', { name: '复制链接' }));
+    await screen.findByText('已复制演示链接。');
+    expect(writeText).toHaveBeenCalledWith('https://example.invalid/subscriptions/demo/1');
+    writeText.mockRejectedValueOnce(new Error('clipboard unavailable'));
+    fireEvent.click(screen.getByRole('button', { name: '复制链接' }));
+    await screen.findByRole('alert');
+    expect(screen.getByLabelText('订阅链接')).toHaveValue('https://example.invalid/subscriptions/demo/1');
+    expect(screen.getByRole('button', { name: '复制链接' })).toBeEnabled();
+  });
+
+  it('keeps history collapsed, then resets, revokes and explicitly regenerates a link', async () => {
+    demo(<CompactSubscriptionExample showHistory />);
+    const previous = screen.getByText('https://example.invalid/subscriptions/demo/retired-1');
+    expect(previous).not.toBeVisible();
+    fireEvent.click(screen.getByText('历史链接（1）'));
+    await waitFor(() => expect(previous).toBeVisible());
+    fireEvent.click(screen.getByRole('button', { name: '重置链接' }));
+    expect(screen.getByLabelText('订阅链接')).toHaveValue('https://example.invalid/subscriptions/demo/2');
+    expect(screen.getByText('历史链接（2）')).toBeVisible();
+    fireEvent.click(screen.getByRole('button', { name: '撤销链接' }));
+    expect(screen.getByText('尚未生成订阅链接')).toBeVisible();
+    expect(screen.queryByRole('link', { name: '下载文件' })).not.toBeInTheDocument();
+    expect(screen.queryByRole('button', { name: '撤销链接' })).not.toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: '获取订阅链接' }));
+    expect(screen.getByLabelText('订阅链接')).toHaveValue('https://example.invalid/subscriptions/demo/3');
+  });
+
+  it('blocks loading actions and does not generate from an error or no-link state', () => {
+    const view = demo(<CompactSubscriptionExample initialState="loading" />);
+    expect(screen.getByRole('status')).toHaveTextContent('正在读取订阅链接');
+    expect(screen.getByRole('button', { name: '复制链接' })).toBeDisabled();
+    expect(screen.getByText('下载文件').closest('a')).toHaveAttribute('aria-disabled', 'true');
+    expect(screen.queryByLabelText('订阅链接')).not.toBeInTheDocument();
+    view.rerender(<div className="rhine-theme"><CompactSubscriptionExample key="error" initialState="error" /></div>);
+    expect(screen.getByRole('alert')).toHaveTextContent('订阅链接读取失败');
+    expect(screen.queryByLabelText('订阅链接')).not.toBeInTheDocument();
+    fireEvent.click(screen.getByRole('button', { name: '重试' }));
+    expect(screen.getByLabelText('订阅链接')).toHaveValue('https://example.invalid/subscriptions/demo/1');
+    view.rerender(<div className="rhine-theme"><CompactSubscriptionExample key="empty" initialState="no-link" /></div>);
+    expect(screen.getByRole('button', { name: '获取订阅链接' })).toBeEnabled();
+    expect(screen.queryByLabelText('订阅链接')).not.toBeInTheDocument();
+    expect(screen.queryByText(/历史链接/)).not.toBeInTheDocument();
+  });
+});

package/tests/DateRangeFilterGallery.test.tsx

@@ -0,0 +1,85 @@
+import { fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { describe, expect, it } from 'vitest';
+import { DateRangeFilterExample } from '../preview/DateRangeFilterGallery';
+
+function demo(props = {}) {
+  render(<div className="rhine-theme"><DateRangeFilterExample {...props} /></div>);
+}
+const trigger = () => screen.getByRole('button', { name: /时间范围：.+选择日期/ });
+async function open() {
+  trigger().focus(); fireEvent.click(trigger());
+  return screen.findByRole('dialog', { name: '时间范围设置' });
+}
+
+describe('date range filtering composition', () => {
+  it('applies a quick preset immediately and always displays its dates', () => {
+    demo();
+    fireEvent.click(screen.getByRole('radio', { name: '昨天' }));
+    expect(screen.getByRole('radio', { name: '昨天' })).toBeChecked();
+    expect(trigger()).toHaveTextContent('2026-10-23 — 2026-10-23');
+    expect(screen.getByRole('status')).toHaveTextContent('本次操作 1 次');
+  });
+
+  it('keeps edits as drafts, discards cancellation and restores trigger focus', async () => {
+    demo(); const dialog = await open();
+    fireEvent.change(within(dialog).getByLabelText('开始日期'), { target: { value: '2026-10-01' } });
+    expect(screen.getByRole('status')).toHaveTextContent('2026-10-24 — 2026-10-24 · 本次操作 0 次');
+    fireEvent.click(within(dialog).getByRole('button', { name: '取消' }));
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+    await waitFor(() => expect(trigger()).toHaveFocus());
+    const reopened = await open();
+    expect(within(reopened).getByLabelText('开始日期')).toHaveValue('2026-10-24');
+  });
+
+  it('does not commit on Escape or the overlay close button', async () => {
+    demo();
+    for (const close of ['escape', 'button']) {
+      const dialog = await open();
+      fireEvent.change(within(dialog).getByLabelText('开始日期'), { target: { value: '2026-10-02' } });
+      if (close === 'escape') fireEvent.keyDown(document.activeElement!, { key: 'Escape' });
+      else fireEvent.click(within(dialog).getByRole('button', { name: '关闭详情' }));
+      await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+      expect(screen.getByRole('status')).toHaveTextContent('本次操作 0 次');
+      await waitFor(() => expect(trigger()).toHaveFocus());
+    }
+  });
+
+  it('blocks incomplete, reversed and out-of-range dates before applying one valid range', async () => {
+    demo(); const dialog = await open();
+    const start = within(dialog).getByLabelText('开始日期'), end = within(dialog).getByLabelText('结束日期');
+    const apply = within(dialog).getByRole('button', { name: '应用日期' });
+    for (const [from, to] of [['', '2026-10-24'], ['2026-10-24', ''], ['2026-10-25', '2026-10-24'], ['2024-12-31', '2026-10-24'], ['2026-10-24', '2027-01-01']]) {
+      fireEvent.change(start, { target: { value: from } });
+      fireEvent.change(end, { target: { value: to } });
+      expect(apply).toBeDisabled();
+      fireEvent.submit(apply.closest('form')!);
+      expect(screen.getByRole('status')).toHaveTextContent('本次操作 0 次');
+    }
+    fireEvent.change(start, { target: { value: '2025-12-28' } });
+    fireEvent.change(end, { target: { value: '2026-01-06' } });
+    await waitFor(() => expect(apply).toBeEnabled());
+    fireEvent.click(apply);
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+    expect(screen.getByRole('status')).toHaveTextContent('2025-12-28 — 2026-01-06 · 本次操作 1 次');
+    expect(screen.getAllByRole('radio').every(radio => !(radio as HTMLInputElement).checked)).toBe(true);
+    await waitFor(() => expect(trigger()).toHaveFocus());
+  });
+
+  it('applies additional presets immediately instead of submitting an unfinished draft', async () => {
+    demo(); const dialog = await open();
+    fireEvent.change(within(dialog).getByLabelText('开始日期'), { target: { value: '' } });
+    fireEvent.click(within(dialog).getByRole('button', { name: '最近 30 天' }));
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+    expect(trigger()).toHaveTextContent('2026-09-25 — 2026-10-24');
+    expect(screen.getByRole('status')).toHaveTextContent('本次操作 1 次');
+  });
+
+  it('keeps a disabled range readable and prevents all entry points', () => {
+    demo({ disabled: true });
+    expect(trigger()).toBeDisabled();
+    expect(screen.getAllByRole('radio').every(radio => (radio as HTMLInputElement).disabled)).toBe(true);
+    fireEvent.click(trigger());
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    expect(screen.getByRole('status')).toHaveTextContent('2026-10-24 — 2026-10-24 · 本次操作 0 次');
+  });
+});