@linhey/rhine-design 0.3.0 → 0.5.0

package/tests/ShellMediaParity.test.tsx

@@ -0,0 +1,180 @@
+import { createRef, useState } from 'react';
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { AppShell, Background, Dialog, Drawer, MediaCard, MediaViewer } from '../components';
+import { ThemeProvider } from '../components/theme';
+
+afterEach(() => { vi.restoreAllMocks(); vi.unstubAllGlobals(); });
+
+function shellWidth(initialWidth: number) {
+  let width = initialWidth, onResize = () => {};
+  vi.spyOn(HTMLElement.prototype, 'clientWidth', 'get').mockImplementation(() => width);
+  vi.spyOn(HTMLElement.prototype, 'getBoundingClientRect').mockImplementation(() => ({ width: width * 2 } as DOMRect));
+  vi.stubGlobal('ResizeObserver', class {
+    constructor(callback: () => void) { onResize = callback; }
+    observe() {} disconnect() {}
+  });
+  return (next: number) => act(() => { width = next; onResize(); });
+}
+
+describe('Ant Design / MUI shell and background contracts', () => {
+  it('exposes the background DOM ref without creating another theme root or hiding native attributes', () => {
+    const ref = createRef<HTMLDivElement>();
+    const { container } = render(<ThemeProvider><Background ref={ref} role="region" aria-label="局部背景" className="custom" style={{ padding: 12 }} appearance={{ color: 'pink' }} decoration="none">正文</Background></ThemeProvider>);
+    expect(ref.current).toBe(screen.getByRole('region', { name: '局部背景' }));
+    expect(ref.current).toHaveClass('rhine-background', 'custom');
+    expect(ref.current).toHaveStyle({ padding: '12px', '--rhine-background-color': 'pink' });
+    expect(container.querySelectorAll('.rhine-theme')).toHaveLength(1);
+  });
+
+  it('lets the host control the mobile drawer independently from the desktop open state', async () => {
+    shellWidth(400);
+    const onDrawerOpenChange = vi.fn(), onOpenChange = vi.fn();
+    const navigation = { label: '导航', content: <button>导航项目</button>, open: true, onOpenChange, drawerOpen: false, onDrawerOpenChange };
+    const { rerender } = render(<AppShell layout="single" navigation={navigation}>正文</AppShell>);
+    fireEvent.click(screen.getByRole('button', { name: '导航' }));
+    expect(onDrawerOpenChange).toHaveBeenLastCalledWith(true);
+    expect(onOpenChange).not.toHaveBeenCalled();
+    expect(screen.queryByRole('dialog')).not.toBeInTheDocument();
+    rerender(<AppShell layout="single" navigation={{ ...navigation, drawerOpen: true }}>正文</AppShell>);
+    expect(screen.getByRole('dialog', { name: '导航' })).toHaveAttribute('data-side', 'left');
+    fireEvent.click(screen.getByRole('button', { name: '关闭抽屉' }));
+    expect(onDrawerOpenChange).toHaveBeenLastCalledWith(false);
+    expect(screen.getByRole('dialog')).toBeInTheDocument();
+    rerender(<AppShell layout="single" navigation={navigation}>正文</AppShell>);
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+  });
+
+  it('supports a default-open drawer and keeps its side aligned with the desktop panel', async () => {
+    shellWidth(400);
+    const panel = { label: '导航', content: <p>导航内容</p>, open: true, onOpenChange: vi.fn() };
+    const secondary = { ...panel, label: '详情', defaultDrawerOpen: true };
+    const { rerender } = render(<AppShell layout="left-right" navigation={panel} secondary={secondary}>正文</AppShell>);
+    expect(screen.getByRole('dialog', { name: '详情' })).toHaveAttribute('data-side', 'right');
+    fireEvent.click(screen.getByRole('button', { name: '关闭抽屉' }));
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+    rerender(<AppShell layout="double-left" navigation={panel} secondary={secondary}>正文</AppShell>);
+    fireEvent.click(screen.getByRole('button', { name: '详情' }));
+    expect(screen.getByRole('dialog', { name: '详情' })).toHaveAttribute('data-side', 'left');
+  });
+
+  it('uses custom container breakpoints and widths while returning focus when a pane hides', () => {
+    const resize = shellWidth(1000);
+    render(<AppShell layout="single" className="custom-shell" style={{ height: 600 }} navigation={{ label: '导航', content: <button>导航项目</button>, open: true, onOpenChange: vi.fn(), width: 300, breakpoint: 900 }}>正文</AppShell>);
+    const pane = screen.getByRole('complementary', { name: '导航' });
+    expect(pane).toHaveStyle({ flexBasis: '300px' });
+    expect(screen.getByRole('region', { name: '应用工作区' })).toHaveClass('custom-shell');
+    expect(screen.getByRole('region', { name: '应用工作区' })).toHaveStyle({ height: '600px' });
+    screen.getByRole('button', { name: '导航项目' }).focus();
+    resize(899);
+    expect(pane).not.toBeVisible();
+    expect(screen.getByRole('button', { name: '导航' })).toHaveFocus();
+    resize(900);
+    expect(pane).toBeVisible();
+  });
+
+  it('restores focus when the secondary prop is removed without stealing focus from outside the shell', () => {
+    shellWidth(1200);
+    const navigation = { label: '导航', content: <button>导航项目</button>, open: true, onOpenChange: vi.fn() };
+    const secondary = { ...navigation, label: '详情', content: <button>详情操作</button> };
+    const demo = (show: boolean) => <><button>外部操作</button><AppShell layout="left-right" navigation={navigation} secondary={show ? secondary : undefined}>正文</AppShell></>;
+    const { rerender } = render(demo(true));
+    screen.getByRole('button', { name: '详情操作' }).focus();
+    rerender(demo(false)); expect(screen.getByRole('button', { name: '收起导航' })).toHaveFocus();
+    rerender(demo(true)); screen.getByRole('button', { name: '详情操作' }).focus();
+    screen.getByRole('button', { name: '外部操作' }).focus();
+    rerender(demo(false)); expect(screen.getByRole('button', { name: '外部操作' })).toHaveFocus();
+  });
+
+  it('keeps the existing Drawer default on the right and supports an explicit left side', () => {
+    const props = { trigger: <button>打开</button>, title: '抽屉', description: '描述', open: true, children: <p>内容</p> };
+    const { rerender } = render(<Drawer {...props} />);
+    expect(screen.getByRole('dialog')).toHaveAttribute('data-side', 'right');
+    rerender(<Drawer {...props} side="left" />);
+    expect(screen.getByRole('dialog')).toHaveAttribute('data-side', 'left');
+  });
+});
+
+describe('Ant Design / MUI media contracts', () => {
+  it.each(['load', 'error'] as const)('mounts a hidden loading preview so its %s event can complete the host state', event => {
+    const completed = vi.fn();
+    function Demo() {
+      const [state, setState] = useState<'loading' | 'ready' | 'error'>('loading');
+      return <MediaCard title="预览" kind="photo" state={state} onOpen={() => {}} preview={<img alt="缩略图" src="/preview.png" onLoad={() => { completed(); setState('ready'); }} onError={() => { completed(); setState('error'); }} />} />;
+    }
+    render(<Demo />); const preview = screen.getByAltText('缩略图');
+    expect(preview).toBeInTheDocument(); expect(preview).not.toBeVisible();
+    expect(screen.getByText('正在加载预览…')).toBeVisible();
+    fireEvent[event](preview); expect(completed).toHaveBeenCalledOnce();
+    expect(screen.queryByText('正在加载预览…')).not.toBeInTheDocument();
+    if (event === 'load') { expect(screen.getByAltText('缩略图')).toBe(preview); expect(preview).toBeVisible(); }
+    else expect(screen.getByText('预览无法解码')).toBeVisible();
+  });
+
+  it('keeps card actions separate from selection and opening, including an error retry', () => {
+    const onOpen = vi.fn(), onSelectedChange = vi.fn(), retry = vi.fn(), ref = createRef<HTMLElement>();
+    const { rerender } = render(<MediaCard ref={ref} title="照片" kind="photo" state="error" onOpen={onOpen} onSelectedChange={onSelectedChange} className="custom-card" style={{ maxWidth: 320 }} actions={<button onClick={retry}>重新加载</button>} />);
+    fireEvent.click(screen.getByRole('button', { name: '重新加载' }));
+    expect(retry).toHaveBeenCalledOnce(); expect(onOpen).not.toHaveBeenCalled(); expect(onSelectedChange).not.toHaveBeenCalled();
+    expect(ref.current).toHaveClass('custom-card'); expect(ref.current).toHaveStyle({ maxWidth: '320px' });
+    fireEvent.click(screen.getByRole('checkbox')); expect(onSelectedChange).toHaveBeenCalledWith(true);
+    rerender(<MediaCard title="照片" kind="photo" onOpen={onOpen} onSelectedChange={onSelectedChange} disabled />);
+    expect(screen.getByRole('button', { name: '打开照片' })).toBeDisabled(); expect(screen.getByRole('checkbox')).toBeDisabled();
+  });
+
+  it('has an uncontrolled default-open viewer and a working uncontrolled metadata toggle', async () => {
+    render(<MediaViewer trigger={<button>打开</button>} title="照片" description="描述" defaultOpen defaultMetadataOpen metadata={0} className="custom-viewer" style={{ paddingTop: 4 }}><p>预览</p></MediaViewer>);
+    const dialog = screen.getByRole('dialog');
+    expect(dialog).toHaveClass('custom-viewer'); expect(dialog).toHaveStyle({ paddingTop: '4px' });
+    const information = screen.getByRole('complementary', { name: '媒体信息' });
+    expect(information).toHaveTextContent('0');
+    expect(screen.getByRole('button', { name: '收起信息' })).toHaveAttribute('aria-controls', information.id);
+    fireEvent.click(screen.getByRole('button', { name: '收起信息' })); expect(information).not.toBeVisible();
+    fireEvent.click(screen.getByRole('button', { name: '显示信息' })); expect(information).toBeVisible();
+    fireEvent.click(screen.getByRole('button', { name: '关闭媒体查看器' }));
+    await waitFor(() => expect(screen.queryByRole('dialog')).not.toBeInTheDocument());
+  });
+
+  it('does not mutate controlled metadata until the host updates the prop', () => {
+    const change = vi.fn();
+    const props = { trigger: <button>打开</button>, title: '照片', description: '描述', open: true, metadata: <p>详细信息</p>, onMetadataOpenChange: change, children: <p>预览</p> };
+    const { rerender } = render(<MediaViewer {...props} metadataOpen={false} />);
+    fireEvent.click(screen.getByRole('button', { name: '显示信息' }));
+    expect(change).toHaveBeenCalledWith(true); expect(screen.getByText('详细信息')).not.toBeVisible();
+    rerender(<MediaViewer {...props} metadataOpen />);
+    expect(screen.getByRole('complementary', { name: '媒体信息' })).toBeVisible();
+  });
+
+  it('navigates by arrow keys, respects independent boundaries, and allows opting out', () => {
+    const previous = vi.fn(), next = vi.fn();
+    const props = { trigger: <button>打开</button>, title: '照片', description: '描述', open: true, onPrevious: previous, onNext: next, children: <p>预览</p> };
+    const { rerender } = render(<MediaViewer {...props} previousDisabled />);
+    const dialog = screen.getByRole('dialog');
+    expect(screen.getByRole('button', { name: '上一项' })).toBeDisabled();
+    fireEvent.keyDown(dialog, { key: 'ArrowLeft' }); expect(previous).not.toHaveBeenCalled();
+    fireEvent.keyDown(dialog, { key: 'ArrowRight' }); expect(next).toHaveBeenCalledOnce();
+    screen.getByRole('button', { name: '下一项' }).focus();
+    rerender(<MediaViewer {...props} nextDisabled />);
+    expect(dialog).toHaveFocus();
+    fireEvent.keyDown(dialog, { key: 'ArrowLeft' }); expect(previous).toHaveBeenCalledOnce();
+    fireEvent.keyDown(dialog, { key: 'ArrowRight' }); expect(next).toHaveBeenCalledOnce();
+    rerender(<MediaViewer {...props} keyboardNavigation={false} />);
+    fireEvent.keyDown(dialog, { key: 'ArrowLeft' }); expect(previous).toHaveBeenCalledOnce();
+    expect(screen.getByRole('button', { name: '上一项' })).not.toHaveAttribute('aria-keyshortcuts');
+    fireEvent.click(screen.getByRole('button', { name: '下一项' })); expect(next).toHaveBeenCalledTimes(2);
+  });
+
+  it('leaves editor, media, modified, composition and nested dialog arrow keys to their owners', () => {
+    const next = vi.fn();
+    render(<MediaViewer trigger={<button>打开</button>} title="照片" description="描述" open onNext={next} actions={<Dialog trigger={<button>编辑详情</button>} title="编辑" description="编辑媒体"><button>内部按钮</button></Dialog>}>
+      <input aria-label="文件名" /><video aria-label="播放视频" controls /><div contentEditable suppressContentEditableWarning aria-label="注释">文字</div><div role="slider" aria-label="缩放" tabIndex={0} />
+    </MediaViewer>);
+    for (const control of [screen.getByRole('textbox'), screen.getByLabelText('播放视频'), screen.getByLabelText('注释'), screen.getByRole('slider')]) fireEvent.keyDown(control, { key: 'ArrowRight' });
+    const dialog = screen.getByRole('dialog');
+    fireEvent.keyDown(dialog, { key: 'ArrowRight', ctrlKey: true });
+    fireEvent.keyDown(dialog, { key: 'ArrowRight', isComposing: true });
+    fireEvent.click(screen.getByRole('button', { name: '编辑详情' }));
+    fireEvent.keyDown(within(screen.getByRole('dialog', { name: '编辑' })).getByRole('button', { name: '内部按钮' }), { key: 'ArrowRight' });
+    expect(next).not.toHaveBeenCalled();
+  });
+});

package/tests/StatusTimeline.test.tsx

@@ -0,0 +1,15 @@
+import { fireEvent, render, screen } from '@testing-library/react';
+import { expect, it } from 'vitest';
+import { StatusTimeline, TimelineLegend } from '../components';
+
+it('announces time and evidence with a single native range control, including unknown and empty states',()=>{
+  const {rerender}=render(<><StatusTimeline label="账号历史" startLabel="昨天" endLabel="今天" segments={[{id:'a',label:'10:00',status:'failed'},{id:'b',label:'10:15',status:'unknown'}]}/><TimelineLegend/></>);
+  const slider=screen.getByRole('slider',{name:'账号历史'});
+  expect(slider).toHaveAttribute('aria-valuetext','10:15 · 未知 / 无数据');
+  fireEvent.change(slider,{target:{value:'0'}});
+  expect(slider).toHaveAttribute('aria-valuetext','10:00 · 存在最终失败');
+  expect(screen.getByRole('list',{name:'健康记录图例'})).toHaveTextContent('重试已恢复');
+  rerender(<StatusTimeline label="账号历史" startLabel="昨天" endLabel="今天" segments={[]}/>);
+  expect(screen.getByRole('slider')).toBeDisabled();
+  expect(screen.getByText('暂无记录')).toBeVisible();
+});

package/tests/Theme.test.tsx

@@ -0,0 +1,112 @@
+import { useState } from 'react';
+import { fireEvent, render, screen, within } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+import { ThemeProvider, themes, useTheme, type ThemeName } from '@linhey/rhine-design/theme';
+import { Button, Dialog } from '../components';
+
+function Controls() {
+  const { theme, setTheme } = useTheme();
+  const [count, setCount] = useState(0);
+  return <>
+    <output aria-label="当前主题">{theme}</output>
+    {themes.map(item => <button key={item.name} onClick={() => setTheme(item.name)}>{item.label}</button>)}
+    <button onClick={() => setCount(count + 1)}>计数 {count}</button>
+    <input aria-label="草稿" defaultValue="" />
+  </>;
+}
+
+describe('public theme API', () => {
+  it('defaults to rhine and preserves the DOM, state and input across all themes', () => {
+    const onThemeChange = vi.fn();
+    render(<ThemeProvider onThemeChange={onThemeChange} className="host" id="app" data-rhine-motion="reduced"><Controls /></ThemeProvider>);
+    const root = document.getElementById('app')!;
+    expect(root).toHaveClass('rhine-theme', 'host');
+    expect(root).toHaveAttribute('data-rhine-motion', 'reduced');
+    expect(root).toHaveAttribute('data-rhine-theme', 'rhine');
+    fireEvent.click(screen.getByRole('button', { name: '计数 0' }));
+    const input = screen.getByRole('textbox', { name: '草稿' });
+    fireEvent.change(input, { target: { value: '未保存的内容' } });
+    for (const name of ['arknights', 'neo-brutalism', 'rhine'] as const) {
+      fireEvent.click(screen.getByRole('button', { name: themes.find(item => item.name === name)!.label }));
+      expect(root).toHaveAttribute('data-rhine-theme', name);
+      expect(screen.getByLabelText('当前主题')).toHaveTextContent(name);
+      expect(screen.getByRole('textbox')).toBe(input);
+      expect(input).toHaveValue('未保存的内容');
+      expect(screen.getByRole('button', { name: '计数 1' })).toBeInTheDocument();
+    }
+    expect(onThemeChange.mock.calls).toEqual([['arknights'], ['neo-brutalism'], ['rhine']]);
+    fireEvent.click(screen.getByRole('button', { name: '莱茵 · 纸面' }));
+    expect(onThemeChange).toHaveBeenCalledTimes(3);
+  });
+
+  it('uses defaultTheme only on mount', () => {
+    const { rerender } = render(<ThemeProvider defaultTheme="arknights"><Controls /></ThemeProvider>);
+    expect(screen.getByLabelText('当前主题')).toHaveTextContent('arknights');
+    rerender(<ThemeProvider defaultTheme="neo-brutalism"><Controls /></ThemeProvider>);
+    expect(screen.getByLabelText('当前主题')).toHaveTextContent('arknights');
+  });
+
+  it('leaves controlled updates to the host and follows subsequent props', () => {
+    const onThemeChange = vi.fn();
+    const { rerender } = render(<ThemeProvider theme="rhine" onThemeChange={onThemeChange}><Controls /></ThemeProvider>);
+    fireEvent.click(screen.getByRole('button', { name: '明日方舟 · 战术终端' }));
+    expect(onThemeChange).toHaveBeenCalledWith('arknights');
+    expect(screen.getByLabelText('当前主题')).toHaveTextContent('rhine');
+    rerender(<ThemeProvider theme="arknights" onThemeChange={onThemeChange}><Controls /></ThemeProvider>);
+    expect(screen.getByLabelText('当前主题')).toHaveTextContent('arknights');
+    expect(onThemeChange).toHaveBeenCalledTimes(1);
+  });
+
+  it('keeps sibling providers independent', () => {
+    render(<><ThemeProvider aria-label="A"><Controls /></ThemeProvider><ThemeProvider aria-label="B" defaultTheme="neo-brutalism"><Controls /></ThemeProvider></>);
+    const a = screen.getByLabelText('A'), b = screen.getByLabelText('B');
+    fireEvent.click(within(a).getByRole('button', { name: '明日方舟 · 战术终端' }));
+    expect(a).toHaveAttribute('data-rhine-theme', 'arknights');
+    expect(b).toHaveAttribute('data-rhine-theme', 'neo-brutalism');
+    expect(within(b).getByLabelText('当前主题')).toHaveTextContent('neo-brutalism');
+  });
+
+  it('does not read or write host storage', () => {
+    const read = vi.spyOn(Storage.prototype, 'getItem');
+    const write = vi.spyOn(Storage.prototype, 'setItem');
+    try {
+      render(<ThemeProvider><Controls /></ThemeProvider>);
+      fireEvent.click(screen.getByRole('button', { name: '明日方舟 · 战术终端' }));
+      expect(read).not.toHaveBeenCalled();
+      expect(write).not.toHaveBeenCalled();
+    } finally { read.mockRestore(); write.mockRestore(); }
+  });
+
+  it('keeps an open dialog in the same theme root, preserving its draft and focus', () => {
+    render(<ThemeProvider><Dialog trigger={<Button>打开</Button>} title="主题测试" description="保持浮层状态"><Controls /></Dialog></ThemeProvider>);
+    const trigger = screen.getByRole('button', { name: '打开' });
+    fireEvent.click(trigger);
+    const dialog = screen.getByRole('dialog');
+    const root = trigger.closest('.rhine-theme');
+    expect(dialog.closest('.rhine-theme')).toBe(root);
+    fireEvent.change(within(dialog).getByRole('textbox'), { target: { value: '浮层草稿' } });
+    const switcher = within(dialog).getByRole('button', { name: '明日方舟 · 战术终端' });
+    switcher.focus();
+    fireEvent.click(switcher);
+    expect(root).toHaveAttribute('data-rhine-theme', 'arknights');
+    expect(screen.getByRole('dialog')).toBe(dialog);
+    expect(within(dialog).getByRole('textbox')).toHaveValue('浮层草稿');
+    expect(switcher).toHaveFocus();
+  });
+
+  it('explains missing providers, nested providers and invalid theme names', () => {
+    expect(() => render(<Controls />)).toThrow('useTheme must be used within');
+    expect(() => render(<ThemeProvider><ThemeProvider /></ThemeProvider>)).toThrow('Nested Rhine ThemeProvider is not supported');
+    expect(() => render(<ThemeProvider theme={'unknown' as ThemeName} />)).toThrow('Unknown Rhine theme');
+  });
+
+  it('rejects invalid imperative requests without updating state or notifying the host', () => {
+    let setTheme: (theme: ThemeName) => void = () => {};
+    function Capture() { setTheme = useTheme().setTheme; return null; }
+    const onThemeChange = vi.fn();
+    render(<ThemeProvider onThemeChange={onThemeChange}><Capture /><Controls /></ThemeProvider>);
+    expect(() => setTheme('unknown' as ThemeName)).toThrow('Unknown Rhine theme');
+    expect(screen.getByLabelText('当前主题')).toHaveTextContent('rhine');
+    expect(onThemeChange).not.toHaveBeenCalled();
+  });
+});