@linhey/rhine-design 0.4.0 → 0.6.0

package/components/Data.tsx

@@ -1,6 +1,9 @@
-import type { ReactNode } from 'react';
+import { Fragment, useId, useLayoutEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
 import { Button, EmptyState, Notice, Skeleton } from './components';
 import { Text } from './Typography';
+import { Checkbox } from './Forms';
+import { Select } from './Select';
+import './data.css';
 
 export function Metric({ label, value, unit, description, loading = false }: { label: string; value: ReactNode; unit?: string; description?: string; loading?: boolean }) {
   return <div className="rhine-metric" aria-busy={loading}><Text variant="caption" tone="muted">{label}</Text>{loading ? <Skeleton lines={1} label={`正在读取${label}`} /> : <Text variant="metric">{value ?? '—'}{unit && <span className="rhine-metric__unit"> {unit}</span>}</Text>}{description && <Text variant="caption" tone="muted">{description}</Text>}</div>;
@@ -8,35 +11,112 @@ export function Metric({ label, value, unit, description, loading = false }: { l
 export function KeyValue({ items }: { items: { key: string; label: string; value: ReactNode }[] }) {
   return <dl className="rhine-key-value">{items.map(item => <div key={item.key}><dt>{item.label}</dt><dd>{item.value ?? '—'}</dd></div>)}</dl>;
 }
-export interface DataColumn<T> { key: string; header: string; render: (row: T) => ReactNode; align?: 'left' | 'right'; sortable?: boolean }
+export interface DataColumn<T> { key: string; header: string; render: (row: T) => ReactNode; align?: 'left' | 'right'; sortable?: boolean; width?: number; sticky?: 'left' | 'right'; stickyOffset?: number; rowHeader?: boolean }
 export interface TableSort { key: string; direction: 'asc' | 'desc' }
 export interface DataTableProps<T> {
   caption: string; columns: DataColumn<T>[]; rows: T[]; rowKey: (row: T) => string;
   loading?: boolean; error?: string; emptyTitle?: string; sort?: TableSort;
-  onSortChange?: (sort: TableSort) => void; onRetry?: () => void;
+  onSortChange?: (sort: TableSort) => void; onSortReset?: () => void; onRetry?: () => void;
+  selection?: { keys: string[]; onChange: (keys: string[]) => void; isDisabled?: (row: T) => boolean; mode?: 'multiple' | 'single'; hideSelectAll?: boolean };
+  expansion?: { keys: string[]; onChange: (keys: string[]) => void; getChildren?: (row: T) => T[]; renderDetail?: (row: T) => ReactNode; canExpand?: (row: T) => boolean };
+  rowLabel?: (row: T) => string; density?: 'comfortable' | 'compact'; stickyHeader?: boolean; maxHeight?: number;
 }
-export function DataTable<T>({ caption, columns, rows, rowKey, loading = false, error, emptyTitle = '暂无记录', sort, onSortChange, onRetry }: DataTableProps<T>) {
-  return <div className="rhine-data" aria-busy={loading}>
+export function DataTable<T>({ caption, columns, rows, rowKey, loading = false, error, emptyTitle = '暂无记录', sort, onSortChange, onSortReset, onRetry, selection, expansion, rowLabel = rowKey, density = 'comfortable', stickyHeader, maxHeight }: DataTableProps<T>) {
+  const id = useId();
+  const table = useRef<HTMLTableElement>(null);
+  const [columnWidths, setColumnWidths] = useState<Record<string, number>>({});
+  useLayoutEffect(() => {
+    if (!table.current || !columns.some(column => column.sticky)) return;
+    const headers = Array.from(table.current.querySelectorAll<HTMLElement>('thead [data-column-key]'));
+    const measure = () => {
+      // Layout widths remain in CSS pixels under zoom/transform; visual bounds do not.
+      const widths = Object.fromEntries(headers.map(header => [header.dataset.columnKey!, header.offsetWidth]));
+      setColumnWidths(previous => Object.keys(widths).length === Object.keys(previous).length && Object.entries(widths).every(([key, width]) => previous[key] === width) ? previous : widths);
+    };
+    measure();
+    if (typeof ResizeObserver === 'undefined') return;
+    const observer = new ResizeObserver(measure);
+    headers.forEach(header => observer.observe(header));
+    return () => observer.disconnect();
+  }, [columns]);
+  const offsets: Record<string, number> = {};
+  for (const side of ['left', 'right'] as const) {
+    let offset = 0;
+    for (const column of side === 'left' ? columns : [...columns].reverse()) {
+      if (column.sticky !== side) continue;
+      offsets[column.key] = column.stickyOffset ?? offset;
+      offset = offsets[column.key] + (columnWidths[column.key] || column.width || 0);
+    }
+  }
+  const visible: { row: T; depth: number; expandable: boolean }[] = [];
+  const visit = (items: T[], depth: number, ancestors: Set<string>) => items.forEach(row => {
+    const key = rowKey(row);
+    if (ancestors.has(key)) return;
+    const children = expansion?.getChildren?.(row) ?? [];
+    const expandable = !!expansion && (expansion.canExpand ? expansion.canExpand(row) : !!children.length || !!expansion.renderDetail);
+    visible.push({ row, depth, expandable });
+    if (expandable && expansion?.keys.includes(key)) visit(children, depth + 1, new Set([...ancestors, key]));
+  });
+  visit(rows, 0, new Set());
+  const eligible = visible.filter(({ row }) => !selection?.isDisabled?.(row)).map(({ row }) => rowKey(row));
+  const selectedCount = eligible.filter(key => selection?.keys.includes(key)).length;
+  const toggle = (keys: string[], key: string) => keys.includes(key) ? keys.filter(item => item !== key) : [...keys, key];
+  const columnStyle = (column: DataColumn<T>): CSSProperties => ({ width: column.width, minWidth: column.width, [column.sticky ?? 'left']: column.sticky ? offsets[column.key] : undefined });
+  return <div className="rhine-data" aria-busy={loading} data-density={density}>
     {error && <Notice tone="error" title="读取失败" action={onRetry && <Button variant="secondary" onClick={onRetry} disabled={loading}>重试</Button>}>{error}{rows.length > 0 && ' · 以下保留上次读取的记录。'}</Notice>}
     {loading && <p role="status" className="rhine-text rhine-text--caption rhine-text--muted">{rows.length ? '正在刷新，保留当前记录…' : '正在读取…'}</p>}
-    <div className="rhine-table-scroll" role="region" aria-label={`${caption}，可横向滚动`} tabIndex={0}>
-      <table className="rhine-table"><caption>{caption}</caption><thead><tr>{columns.map(column => <th scope="col" key={column.key} data-align={column.align} aria-sort={column.sortable ? sort?.key === column.key ? sort.direction === 'asc' ? 'ascending' : 'descending' : 'none' : undefined}>{column.sortable && onSortChange ? <button type="button" disabled={loading} onClick={() => onSortChange({ key: column.key, direction: sort?.key === column.key && sort.direction === 'asc' ? 'desc' : 'asc' })}>{column.header}<span aria-hidden="true">{sort?.key === column.key ? sort.direction === 'asc' ? ' ↑' : ' ↓' : ' ↕'}</span></button> : column.header}</th>)}</tr></thead>
-      <tbody>{rows.map(row => <tr key={rowKey(row)}>{columns.map(column => <td key={column.key} data-align={column.align}>{column.render(row) ?? '—'}</td>)}</tr>)}</tbody></table>
+    {sort && onSortReset && <Button variant="quiet" disabled={loading} onClick={() => {
+      const header = Array.from(table.current?.querySelectorAll<HTMLElement>('thead [data-column-key]') ?? []).find(cell => cell.dataset.columnKey === sort.key);
+      (header?.querySelector<HTMLButtonElement>('button') ?? table.current?.parentElement)?.focus();
+      onSortReset();
+    }}>清除排序</Button>}
+    <div className="rhine-table-scroll" role="region" aria-label={`${caption}，可横向滚动`} tabIndex={0} style={{ maxHeight }}>
+      <table ref={table} className="rhine-table" data-sticky-header={stickyHeader}><caption>{caption}</caption><thead><tr>
+        {selection && <th scope="col">{selection.mode === 'single' || selection.hideSelectAll ? '选择' : <Checkbox label="选择当前可见行" checked={!!eligible.length && selectedCount === eligible.length} indeterminate={selectedCount > 0 && selectedCount < eligible.length} disabled={loading || !eligible.length} onChange={() => selection.onChange(selectedCount === eligible.length ? selection.keys.filter(key => !eligible.includes(key)) : [...new Set([...selection.keys, ...eligible])])} />}</th>}
+        {expansion && <th scope="col">层级 / 详情</th>}
+        {columns.map(column => <th scope="col" key={column.key} data-column-key={column.key} data-align={column.align} data-sticky={column.sticky} style={columnStyle(column)} aria-sort={column.sortable ? sort?.key === column.key ? sort.direction === 'asc' ? 'ascending' : 'descending' : 'none' : undefined}>{column.sortable && onSortChange ? <button type="button" disabled={loading} title={`按${sort?.key === column.key && sort.direction === 'asc' ? '降' : '升'}序排列${column.header}`} onClick={() => onSortChange({ key: column.key, direction: sort?.key === column.key && sort.direction === 'asc' ? 'desc' : 'asc' })}>{column.header}<span aria-hidden="true">{sort?.key === column.key ? sort.direction === 'asc' ? ' ↑' : ' ↓' : ' ↕'}</span></button> : column.header}</th>)}</tr></thead>
+      <tbody>{visible.map(({ row, depth, expandable }) => {
+        const key = rowKey(row), expanded = expandable && expansion?.keys.includes(key);
+        const detailId = `${id}-detail-${encodeURIComponent(key)}`;
+        const detail = expanded ? expansion?.renderDetail?.(row) : null;
+        const hasDetail = detail !== null && detail !== undefined && typeof detail !== 'boolean';
+        return <Fragment key={key}><tr data-selected={selection?.mode === 'single' ? selection.keys[0] === key : selection?.keys.includes(key)}>
+          {selection && <td>{selection.mode === 'single' ? <label className="rhine-table__radio"><input type="radio" name={`${id}-selection`} checked={selection.keys[0] === key} disabled={loading || selection.isDisabled?.(row)} onChange={() => selection.onChange([key])} /><span>{`选择${rowLabel(row)}`}</span></label> : <Checkbox label={`选择${rowLabel(row)}`} checked={selection.keys.includes(key)} disabled={loading || selection.isDisabled?.(row)} onChange={() => selection.onChange(toggle(selection.keys, key))} />}</td>}
+          {expansion && <td><span className="rhine-table__depth">第 {depth + 1} 层</span>{expandable && <Button variant="quiet" aria-label={`${expanded ? '收起' : '展开'}${rowLabel(row)}`} aria-expanded={!!expanded} aria-controls={hasDetail ? detailId : undefined} onClick={() => expansion.onChange(toggle(expansion.keys, key))}>{expanded ? '−' : '+'}</Button>}</td>}
+          {columns.map(column => { const Cell = column.rowHeader ? 'th' : 'td'; return <Cell scope={column.rowHeader ? 'row' : undefined} key={column.key} data-align={column.align} data-sticky={column.sticky} style={columnStyle(column)}>{column.render(row) ?? '—'}</Cell>; })}
+        </tr>{hasDetail && <tr><td colSpan={columns.length + Number(!!selection) + Number(!!expansion)}><div id={detailId} role="region" aria-label={`${rowLabel(row)}详情`}>{detail}</div></td></tr>}</Fragment>;
+      })}</tbody></table>
     </div>
     {!rows.length && !loading && !error && <EmptyState title={emptyTitle} description="当前条件下没有可展示的数据。" />}
   </div>;
 }
-export function Pagination({ page, pageSize, total, hasNext = false, loading = false, onPageChange }: {
-  page: number; pageSize: number; total?: number; hasNext?: boolean; loading?: boolean; onPageChange: (page: number) => void;
-}) {
-  const size = Math.max(1, Math.floor(pageSize));
-  const count = total === undefined ? undefined : Math.max(0, Math.floor(total));
+export interface PaginationProps {
+  page: number; pageSize: number; total?: number; hasNext?: boolean; loading?: boolean; disabled?: boolean; onPageChange: (page: number) => void;
+  pageSizeOptions?: number[]; onPageSizeChange?: (size: number) => void; showFirstButton?: boolean; showLastButton?: boolean; label?: string;
+}
+export function Pagination({ page, pageSize, total, hasNext = false, loading = false, disabled = false, onPageChange, pageSizeOptions = [10, 25, 50], onPageSizeChange, showFirstButton = false, showLastButton = false, label = '分页' }: PaginationProps) {
+  const root = useRef<HTMLElement>(null), focusedAction = useRef<HTMLButtonElement | null>(null);
+  const size = Number.isFinite(pageSize) ? Math.max(1, Math.floor(pageSize)) : 1;
+  const count = total === undefined || !Number.isFinite(total) || total < 0 ? undefined : Math.floor(total);
   const pages = count === undefined ? undefined : Math.max(1, Math.ceil(count / size));
-  const current = Math.max(1, Math.floor(page));
+  const current = Number.isFinite(page) ? Math.max(1, Math.floor(page)) : 1;
   const next = pages === undefined ? hasNext : current < pages;
-  return <nav className="rhine-pagination" aria-label="分页">
-    <span className="rhine-text rhine-text--caption rhine-text--numeric">{count === undefined ? `第 ${current} 页` : `第 ${current} / ${pages} 页 · 共 ${count} 条`}</span>
-    <Button variant="secondary" disabled={loading || current <= 1} onClick={() => onPageChange(current - 1)}>上一页</Button>
-    <Button variant="secondary" disabled={loading || !next} onClick={() => onPageChange(current + 1)}>下一页</Button>
+  const unavailable = loading || disabled;
+  useLayoutEffect(() => {
+    const focused = focusedAction.current;
+    if (!root.current || !focused || !focused.disabled || !root.current.contains(focused)) return;
+    if (document.activeElement !== focused && document.activeElement !== document.body) return;
+    const actions = Array.from(root.current.querySelectorAll<HTMLButtonElement>('[data-pagination-action]'));
+    const index = actions.indexOf(focused);
+    const fallback = actions.slice(index + 1).find(action => !action.disabled) ?? actions.slice(0, index).reverse().find(action => !action.disabled);
+    fallback?.focus();
+  }, [current, pages, next, unavailable, showFirstButton, showLastButton]);
+  return <nav ref={root} className="rhine-pagination" aria-label={label} aria-busy={loading} onFocusCapture={event => { focusedAction.current = event.target instanceof HTMLButtonElement && event.target.hasAttribute('data-pagination-action') ? event.target : null; }} onBlurCapture={event => { if (event.relatedTarget && !event.currentTarget.contains(event.relatedTarget)) focusedAction.current = null; }}>
+    <span className="rhine-text rhine-text--caption rhine-text--numeric" role="status">{count === undefined ? `第 ${current} 页` : current > pages! ? `第 ${current} 页（已超出 ${pages} 页） · 共 ${count} 条` : `第 ${current} / ${pages} 页 · 共 ${count} 条`}</span>
+    {onPageSizeChange && <Select label="每页条数" value={size} disabled={unavailable} onChange={event => onPageSizeChange(Number(event.target.value))}>{[...new Set([size, ...pageSizeOptions.filter(value => Number.isInteger(value) && value > 0)])].sort((a, b) => a - b).map(value => <option value={value} key={value}>{value} 条</option>)}</Select>}
+    {showFirstButton && <Button variant="secondary" data-pagination-action="first" disabled={unavailable || current <= 1} onClick={() => onPageChange(1)}>首页</Button>}
+    <Button variant="secondary" data-pagination-action="previous" disabled={unavailable || current <= 1} onClick={() => onPageChange(Math.min(current - 1, pages ?? current - 1))}>上一页</Button>
+    <Button variant="secondary" data-pagination-action="next" disabled={unavailable || !next} onClick={() => onPageChange(current + 1)}>下一页</Button>
+    {showLastButton && <Button variant="secondary" data-pagination-action="last" disabled={unavailable || pages === undefined || current === pages} onClick={() => { if (pages !== undefined) onPageChange(pages); }}>末页</Button>}
   </nav>;
 }

package/components/Forms.tsx

@@ -33,32 +33,38 @@ export interface ComboboxProps {
   label: string; query: string; onQueryChange: (query: string) => void;
   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;
 }
-export function Combobox({ label, query, onQueryChange, value, onValueChange, options, loading = false, error, disabled = false }: ComboboxProps) {
-  const id = useId(); const composing = useRef(false);
+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) {
+  const generatedId = useId(), id = suppliedId || generatedId; const composing = useRef(false);
   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);
+  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);
   const activeId = activeIndex >= 0 && !loading && !error ? `${id}-option-${activeIndex}` : undefined;
   useEffect(() => { if (!open || !activeId) return; document.getElementById(activeId)?.scrollIntoView?.({ block: 'nearest' }); }, [activeId, open]);
-  const choose = (option: Choice) => { onValueChange(option); setOpen(false); setActive(null); };
+  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>
-    <PopoverBase.Root open={open && !disabled} onOpenChange={setOpen}><PopoverBase.Anchor asChild><div className="rhine-combobox__input"><input id={id} role="combobox" aria-autocomplete="list" aria-expanded={open && !disabled} aria-controls={open && !disabled ? `${id}-list` : undefined} aria-activedescendant={open ? activeId : undefined} aria-invalid={!!error || undefined} aria-describedby={`${id}-status`} value={draft ?? query} disabled={disabled}
-      onClick={() => setOpen(true)} onFocus={() => setOpen(true)} onChange={event => { if (composing.current) setDraft(event.target.value); else onQueryChange(event.target.value); setActive(null); setOpen(true); }}
-      onCompositionStart={() => { composing.current = true; setDraft(query); }} onCompositionEnd={event => { composing.current = false; setDraft(null); onQueryChange(event.currentTarget.value); }}
+    <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 (composing.current || event.nativeEvent.isComposing || event.keyCode === 229) return;
+        if (readOnly || disabled || composing.current || event.nativeEvent.isComposing || event.keyCode === 229) return;
+        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-busy={loading}>{!loading && !error && options.map((option, index) => <div role="option" id={`${id}-option-${index}`} key={option.value} aria-selected={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>
+      <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.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>}
   </div>;
 }

package/components/MOTION.md

@@ -63,6 +63,14 @@
 
 参考站是设计来源，组件复用入口仍是本仓库。当前CSS/Web Animations及Radix已能承载上述方案，本次不引入额外动画库、CLI、远程Builder或评分流程。未来需要复用外部源码时单独核对许可与依赖，参考授权不等于已取得代码授权。
 
+### 轨道装饰的复用边界（0.6.0）
+
+授权移交的 `OrbitBackdrop` 是独立艺术背景，保留原有环节点、曲线、发射箭头、光晕与透视；不修改通用 Logo、加载或交互配方。组件拥有 Canvas 绘制和生命周期，默认提供暂停 / 继续按钮；业务只组合布局，不另写一套动画。它不表示加载、进度或操作成功，普通业务刷新不触发重播。
+
+系统、显式 prop 和祖先的减少动态偏好均可停帧，内层跟随系统不覆盖外层减少动态，`reducedMotion={false}` 不能覆盖系统偏好。窗口不超过 760px、页面隐藏、组件离屏或零尺寸时也保持静态；恢复沿冻结时间继续，不追赶。resize 静态重绘，DPR 上限为 2，卸载清理 rAF、监听器与 observers；Canvas 不可用时保留静态艺术和内容。
+
+展台 `/#orbit` 使用真实公开组件，提供暂停 / 继续、局部重播、手动减少动态及系统 / 全局偏好继承。重播只重建艺术组件，外层业务内容不重建。此艺术背景不计入 `/#motion` 的 12 组配方；npm 0.5.0 及以前不包含它。API、三主题可读性与验收清单见[轨道背景契约](../docs/ORBIT_BACKDROP.md)。
+
 ## 后续验收
 
 每项候选先在真实组件展台展示，再更新实现状态。检查鼠标/键盘、快速反向、重复点击、加载成功与失败、长文本、400/520/880宽度、200%缩放、系统/手动减少动态；浮层额外检查四向避让与嵌套Escape。对比前后截图核对布局，对动画全过程录屏或采样核对时序，中间帧与最终帧分别记录。
@@ -71,6 +79,6 @@
 
 2026-10-22展台验证：Chrome通过400/520/880/1200宽度、200%缩放、10组播放/复位、快速重播取消旧结果、四向位置/位移采样、菜单键盘、弹窗内重播保焦点与关闭归还、折叠中途反向、通知关闭、Tooltip Escape、逐例/全局/系统减少动态。采样确认4倍慢放的内容淡入720ms、反馈480ms、浮层640ms、折叠800ms及品牌960ms；未将合成浏览器结果扩展为原生或业务验收。
 
-## 导航与流程动效（main，未发布）
+## 导航与流程动效（0.4.0）
 
 新增抽屉与步骤两组示例，实验室现为12组。Drawer继承160ms浮层token，从右侧3px淡入；弹层内重播只重启CSS动画，焦点与内容不重建。Steps当前段使用180ms/3px进入，由业务校验推进。表单错误直接呈现并定位，无抖动效果。完整适用场景、减少动态与告警规则见[交互规范](../docs/INTERACTION_PATTERNS.md)。

package/components/Media.tsx

@@ -0,0 +1,82 @@
+import { useId, useLayoutEffect, useRef, useState, type ComponentPropsWithRef, type CSSProperties, type ReactElement, type ReactNode } from 'react';
+import * as DialogBase from '@radix-ui/react-dialog';
+import { Checkbox } from './Forms';
+import './media-parity.css';
+
+export interface MediaCardProps extends Omit<ComponentPropsWithRef<'article'>, 'title' | 'children'> {
+  title: string; date?: string; kind: 'photo' | 'video' | 'RAW' | 'Live';
+  preview?: ReactNode; state?: 'ready' | 'loading' | 'error' | 'empty'; aspectRatio?: string;
+  onOpen: () => void; selected?: boolean; onSelectedChange?: (selected: boolean) => void;
+  disabled?: boolean; actions?: ReactNode;
+}
+export function MediaCard({ title, date, kind, preview, state = preview != null && preview !== false ? 'ready' : 'empty', aspectRatio = '4 / 3', onOpen, selected = false, onSelectedChange, disabled, actions, className = '', ...props }: MediaCardProps) {
+  const statusId = useId();
+  return <article {...props} className={`rhine-media-card ${className}`} data-selected={selected}>
+    <button type="button" className="rhine-media-card__open" onClick={event => { event.currentTarget.focus({ preventScroll: true }); onOpen(); }} disabled={disabled} aria-label={`打开${title}`} aria-describedby={statusId}>
+      <span className="rhine-media-card__preview" style={{ aspectRatio }} aria-busy={state === 'loading'}>
+        {(state === 'ready' || state === 'loading') && <span className="rhine-media-card__asset" hidden={state === 'loading'}>{preview}</span>}
+        {state !== 'ready' && <span>{state === 'loading' ? '正在加载预览…' : state === 'error' ? '预览无法解码' : '暂无预览'}</span>}
+        <span className="rhine-media-card__kind">{kind === 'photo' ? '照片' : kind === 'video' ? '视频' : kind}</span>
+      </span><span className="rhine-media-card__caption"><strong>{title}</strong><span>{date || '日期未知'}</span></span>
+    </button>
+    <span id={statusId} role="status" className="rhine-sr-only">{state === 'loading' ? `${title}：预览加载中` : state === 'error' ? `${title}：预览失败` : state === 'empty' ? `${title}：缺少预览` : ''}</span>
+    {onSelectedChange && <Checkbox label={`选择${title}`} checked={selected} disabled={disabled} onChange={event => onSelectedChange(event.target.checked)} />}
+    {actions != null && <div className="rhine-media-card__actions">{actions}</div>}
+  </article>;
+}
+
+export interface MediaViewerProps {
+  trigger: ReactElement; title: string; description: string; children: ReactNode;
+  open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void;
+  onPrevious?: () => void; onNext?: () => void; actions?: ReactNode;
+  previousDisabled?: boolean; nextDisabled?: boolean; keyboardNavigation?: boolean;
+  metadata?: ReactNode; metadataOpen?: boolean; defaultMetadataOpen?: boolean; onMetadataOpenChange?: (open: boolean) => void;
+  className?: string; style?: CSSProperties;
+}
+export function MediaViewer({ trigger, title, description, children, open, defaultOpen, onOpenChange, onPrevious, onNext, previousDisabled = false, nextDisabled = false, keyboardNavigation = true, actions, metadata, metadataOpen, defaultMetadataOpen = false, onMetadataOpenChange, className = '', style }: MediaViewerProps) {
+  const root = useRef<HTMLSpanElement>(null), [container, setContainer] = useState<HTMLElement>();
+  const opener = useRef<HTMLElement | null>(null);
+  const contentRef = useRef<HTMLDivElement>(null), previousRef = useRef<HTMLButtonElement>(null), nextRef = useRef<HTMLButtonElement>(null);
+  const focusedNavigation = useRef<'previous' | 'next' | null>(null);
+  const [localMetadataOpen, setLocalMetadataOpen] = useState(defaultMetadataOpen);
+  const showMetadata = metadataOpen ?? localMetadataOpen, metadataId = useId();
+  const hasMetadata = metadata != null && metadata !== false;
+  const previousEnabled = !!onPrevious && !previousDisabled, nextEnabled = !!onNext && !nextDisabled;
+  const changeMetadata = () => {
+    if (metadataOpen === undefined) setLocalMetadataOpen(!showMetadata);
+    onMetadataOpenChange?.(!showMetadata);
+  };
+  useLayoutEffect(() => {
+    const focused = focusedNavigation.current;
+    if ((focused === 'previous' && !previousEnabled) || (focused === 'next' && !nextEnabled)) {
+      const button = focused === 'previous' ? previousRef.current : nextRef.current;
+      // Browsers blur a focused button when it becomes disabled at the collection boundary.
+      if (document.activeElement === button || document.activeElement === document.body) contentRef.current?.focus({ preventScroll: true });
+    }
+  }, [previousEnabled, nextEnabled]);
+  useLayoutEffect(() => { setContainer(root.current?.closest<HTMLElement>('.rhine-theme') ?? document.body); }, []);
+  return <span ref={root} className="rhine-overlay-anchor"><DialogBase.Root open={open} defaultOpen={defaultOpen} onOpenChange={onOpenChange}>
+    <DialogBase.Trigger asChild>{trigger}</DialogBase.Trigger><DialogBase.Portal container={container}>
+      <DialogBase.Overlay className="rhine-overlay" />
+      <DialogBase.Content ref={contentRef} className={`rhine-media-viewer ${className}`} onOpenAutoFocus={() => { opener.current = document.activeElement instanceof HTMLElement ? document.activeElement : null; }} onCloseAutoFocus={event => { if (opener.current?.isConnected && opener.current !== document.body) { event.preventDefault(); opener.current.focus(); } }} style={{ '--rhine-media-columns': hasMetadata && showMetadata ? 'minmax(0, 1fr) min(320px, 32%)' : 'minmax(0, 1fr)', ...style } as CSSProperties}
+        onFocusCapture={event => { const target = event.target as HTMLElement; focusedNavigation.current = target === previousRef.current ? 'previous' : target === nextRef.current ? 'next' : null; }}
+        onBlurCapture={event => { if (event.relatedTarget && !event.currentTarget.contains(event.relatedTarget)) focusedNavigation.current = null; }}
+        onKeyDown={event => {
+          if (!keyboardNavigation || event.defaultPrevented || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey || event.nativeEvent.isComposing) return;
+          const target = event.target;
+          // Embedded editors, media controls and nested portals own their arrow keys.
+          if (!(target instanceof HTMLElement) || !event.currentTarget.contains(target) || target.closest('input, textarea, select, video, audio, [contenteditable]:not([contenteditable="false"]), [role="slider"], [role="listbox"], [role="tree"], [role="tablist"], [role="menu"]')) return;
+          if (event.key === 'ArrowLeft' && previousEnabled) { event.preventDefault(); onPrevious?.(); }
+          if (event.key === 'ArrowRight' && nextEnabled) { event.preventDefault(); onNext?.(); }
+        }}>
+        <header className="rhine-media-viewer__header"><div><DialogBase.Title>{title}</DialogBase.Title><DialogBase.Description>{description}</DialogBase.Description></div>
+          <div className="rhine-media-viewer__actions"><button ref={previousRef} type="button" disabled={!previousEnabled} aria-keyshortcuts={keyboardNavigation ? 'ArrowLeft' : undefined} onClick={onPrevious}>上一项</button><button ref={nextRef} type="button" disabled={!nextEnabled} aria-keyshortcuts={keyboardNavigation ? 'ArrowRight' : undefined} onClick={onNext}>下一项</button>
+            {hasMetadata && <button type="button" aria-controls={metadataId} aria-expanded={showMetadata} onClick={changeMetadata}>{showMetadata ? '收起信息' : '显示信息'}</button>}
+            {actions}<DialogBase.Close asChild><button type="button" aria-label="关闭媒体查看器">关闭</button></DialogBase.Close>
+          </div>
+        </header>
+        <div className="rhine-media-viewer__body"><div className="rhine-media-viewer__canvas">{children}</div>{hasMetadata && <aside id={metadataId} hidden={!showMetadata} className="rhine-media-viewer__metadata" aria-label="媒体信息">{metadata}</aside>}</div>
+      </DialogBase.Content>
+    </DialogBase.Portal>
+  </DialogBase.Root></span>;
+}

package/components/OrbitBackdrop.tsx

@@ -0,0 +1,33 @@
+import { useEffect, useRef, useState, type HTMLAttributes } from 'react';
+import { Button } from './components';
+import { mountOrbit, type OrbitRenderer, type OrbitState } from './orbitRenderer';
+
+export interface OrbitBackdropProps extends HTMLAttributes<HTMLDivElement> {
+  /** Adds a static preference; false never overrides the system or an ancestor. */
+  reducedMotion?: boolean;
+}
+
+export function OrbitBackdrop({ reducedMotion = false, children, className = '', ...props }: OrbitBackdropProps) {
+  const canvas = useRef<HTMLCanvasElement>(null);
+  const renderer = useRef<OrbitRenderer | null>(null);
+  const [paused, setPaused] = useState(false);
+  const [state, setState] = useState<OrbitState>('empty');
+
+  useEffect(() => {
+    const scene = mountOrbit(canvas.current!, setState);
+    renderer.current = scene;
+    return () => { scene.dispose(); renderer.current = null; };
+  }, []);
+  useEffect(() => { renderer.current?.setPaused(paused); }, [paused]);
+  useEffect(() => { renderer.current?.setReducedMotion(reducedMotion); }, [reducedMotion]);
+
+  const canControl = state === 'playing' || state === 'paused';
+  const label = state === 'reduced' ? '已减少动态' : state === 'compact' ? '窄屏静态画面'
+    : canControl ? paused ? '继续动效' : '暂停动效' : '静态画面';
+
+  return <div {...props} className={`rhine-orbit ${className}`} data-rhine-orbit-state={state}>
+    <canvas ref={canvas} className="rhine-orbit-canvas" aria-hidden="true" />
+    <div className="rhine-orbit-content">{children}</div>
+    <div className="rhine-orbit-controls"><Button variant="secondary" disabled={!canControl} onClick={() => setPaused(value => !value)}>{label}</Button></div>
+  </div>;
+}

package/components/Overlays.tsx

@@ -6,6 +6,7 @@ import * as MenuBase from '@radix-ui/react-dropdown-menu';
 import * as TooltipBase from '@radix-ui/react-tooltip';
 import { Button, Notice } from './components';
 import { IconButton } from './Actions';
+import './drawer-placement.css';
 
 // Keep portal content inside the root theme so tokens and reduced-motion overrides inherit.
 function useScope() {
@@ -18,13 +19,13 @@ export interface DialogProps { trigger: ReactElement; title: string; description
 export function Dialog(props: DialogProps) {
   return <DialogFrame {...props}/>;
 }
-export function Drawer(props: Omit<DialogProps, 'sidePanel'>) { return <DialogFrame {...props} drawer />; }
-function DialogFrame({ trigger, title, description, children, open, onOpenChange, sidePanel, drawer = false }: DialogProps & { drawer?: boolean }) {
+export function Drawer(props: Omit<DialogProps, 'sidePanel'> & { side?: 'left' | 'right' }) { return <DialogFrame {...props} drawer />; }
+function DialogFrame({ trigger, title, description, children, open, onOpenChange, sidePanel, drawer = false, side = 'right' }: DialogProps & { drawer?: boolean; side?: 'left' | 'right' }) {
   const { ref, container } = useScope();
   const sideNavigation = typeof sidePanel === 'function';
   const closeButton = <DialogBase.Close asChild><IconButton label={drawer ? '关闭抽屉' : '关闭对话框'} icon="close" /></DialogBase.Close>;
   return <span className="rhine-overlay-anchor" ref={ref}><DialogBase.Root open={open} onOpenChange={onOpenChange}><DialogBase.Trigger asChild>{trigger}</DialogBase.Trigger><DialogBase.Portal container={container}>
-    <DialogBase.Overlay className="rhine-overlay" /><DialogBase.Content className={`rhine-dialog${drawer ? ' rhine-drawer' : ''}${sidePanel ? ' rhine-dialog--split' : ''}${sideNavigation ? ' rhine-dialog--side-navigation' : ''}`}><div className="rhine-dialog__main"><div className="rhine-dialog__head"><DialogBase.Title className="rhine-text rhine-text--section">{title}</DialogBase.Title>{!sideNavigation && closeButton}</div><DialogBase.Description className="rhine-text rhine-text--body rhine-text--muted">{description}</DialogBase.Description><div className="rhine-dialog__body">{children}</div></div>{sidePanel && <div className="rhine-dialog__side">{typeof sidePanel === 'function' ? sidePanel(closeButton) : sidePanel}</div>}</DialogBase.Content>
+    <DialogBase.Overlay className="rhine-overlay" /><DialogBase.Content data-side={drawer ? side : undefined} className={`rhine-dialog${drawer ? ' rhine-drawer' : ''}${sidePanel ? ' rhine-dialog--split' : ''}${sideNavigation ? ' rhine-dialog--side-navigation' : ''}`}><div className="rhine-dialog__main"><div className="rhine-dialog__head"><DialogBase.Title className="rhine-text rhine-text--section">{title}</DialogBase.Title>{!sideNavigation && closeButton}</div><DialogBase.Description className="rhine-text rhine-text--body rhine-text--muted">{description}</DialogBase.Description><div className="rhine-dialog__body">{children}</div></div>{sidePanel && <div className="rhine-dialog__side">{typeof sidePanel === 'function' ? sidePanel(closeButton) : sidePanel}</div>}</DialogBase.Content>
   </DialogBase.Portal></DialogBase.Root></span>;
 }
 export function ConfirmDialog({ trigger, title, description, confirmLabel = '确认操作', danger = false, onConfirm }: { trigger: ReactElement; title: string; description: string; confirmLabel?: string; danger?: boolean; onConfirm: () => Promise<void> | void }) {

package/components/README.md

@@ -2,7 +2,7 @@
 
 本目录提供[莱茵设计 · Rhine Design](../README.md)的 React 组件、设计变量和 API 契约。组件接收应用传入的数据与动作，不绑定特定后端或原生平台。包名为`@linhey/rhine-design`；样式变量和类名使用`rhine-`命名空间。
 
-0.4.0 共48个组件；0.3.0为40个。新增导航、表单流程及健康时间轴组件见[场景与交互规范](../docs/INTERACTION_PATTERNS.md)，原24个扩展组件见[常用组件契约](./COMMON_COMPONENTS.md)。[字体与文字规范](./TYPOGRAPHY.md)与[主流系统对照与缺口](../docs/DESIGN_SYSTEM_AUDIT.md)共同约束复用。静态页面样稿也使用同源Toolbar/Select CSS，不运行React。
+0.6.0 共60个组件；0.5.0为59个，0.4.0为48个，0.3.0为40个。新增导航、表单流程及健康时间轴组件见[场景与交互规范](../docs/INTERACTION_PATTERNS.md)，原24个扩展组件见[常用组件契约](./COMMON_COMPONENTS.md)。[字体与文字规范](./TYPOGRAPHY.md)与[主流系统对照与缺口](../docs/DESIGN_SYSTEM_AUDIT.md)共同约束复用。静态页面样稿也使用同源Toolbar/Select CSS，不运行React。
 
 页面改动遵循：优先复用组件 → 先在设计稿/展台修改并验证 → 再按任务授权实现到App。缺组件先补组件与展台，不在业务页另写同用途样式；同一任务已授权设计和实现时连续推进，无需重复确认。
 
@@ -46,6 +46,8 @@ export function Example() {
 
 ## 组件契约
 
+0.5.0 的 Background、AppShell、MediaCard、MediaViewer、DateField、DateRangePicker、NumberField、TreeSelect、RemoteMultiSelect、TrendChart、StackedBar，以及 DataTable/Pagination 和 StatusTimeline 详情扩展见[应用组件契约](../docs/APPLICATION_COMPONENTS.md)。新增 11 个，总数 59；npm 0.4.0 为 48 个。
+
 | 组件 | 关键输入 | 状态与边界 |
 | --- | --- | --- |
 | Button | variant=primary/secondary/quiet/danger；busy；busyLabel；原生按钮属性 | 默认 type=button；busy 保留焦点并拦截再次 click，不自动把业务标记成功；disabled 使用原生禁用 |
@@ -55,6 +57,7 @@ export function Example() {
 | Toolbar | title；description；children；HTML div属性 | 自适应控件组合，role=group与普通Tab顺序；不伪装为需要方向键导航的ARIA toolbar；不含业务状态 |
 | Badge | tone=neutral/success/warning/error；children | 只读短状态，颜色必须配文字，不做可点击按钮 |
 | Surface | HTML div 属性 | 静态分区，无点击语义；不是弹窗或导航 |
+| Background（0.5.0） | roleTone=canvas/content/sidebar/surface/overlay/media；decoration=auto/theme/none；appearance={color,textColor,texture,textureSize}；HTML div 属性 | 默认正文纯色；仅画布默认使用主题纹理；局部覆盖不创建主题根或定位上下文；完整配置见[场景背景](../docs/THEMING.md#场景背景050) |
 | SelectionCard | label；selected；onSelectedChange；disabled；children | 原生 checkbox 可取消；是否单选由上层控制；内部不嵌套按钮/链接/其他输入 |
 | TextField | label；hint；error；原生 input 属性 | label 与 id 自动关联；错误与提示组成 aria-describedby；输入值由调用方管理 |
 | Tabs | label；items[{value,label,content,disabled?}]；value；onValueChange | value 必须指向有效可用项；唯一 value；左右/Home/End，跳过禁用项；隐藏面板保留挂载但退出可访问树 |
@@ -143,3 +146,11 @@ export function Example() {
 在仓库根执行npm run check。浏览器核对400/520/880/1200宽度、200%缩放、键盘/焦点、展开反向、减少动态中断与加载宽度。JSDOM不代替视觉或原生辅助技术验收。
 
 本仓构建产物是独立展台；消费项目只导入组件入口，避免把preview中的模拟流程打入业务产物。版本变化和迁移见[CHANGELOG](../CHANGELOG.md)。
+
+## 背景与外壳（0.5.0）
+
+新增 `Background` 与 `AppShell`，0.5.0 共 59 个组件；npm 0.4.0 仍为 48 个。Background 支持六类 roleTone、auto/theme/none 装饰策略及 appearance 局部覆盖；AppShell 提供组合展台使用的固定顶部操作区与响应式侧栏。完整 API、最小接入、背景滚动及 Portal 边界见[背景与应用外壳契约](../docs/APPLICATION_COMPONENTS.md)。
+
+## 轨道背景（0.6.0）
+
+`OrbitBackdrop` 接收 `HTMLAttributes<HTMLDivElement>` 和 `reducedMotion?: boolean`，包含可选 `children`。它提供固定深色轨道艺术与内置暂停 / 继续按钮，Canvas 为 `aria-hidden` 装饰。系统、显式减少动态、祖先偏好、窄窗、页面隐藏、离屏及零尺寸时停帧；恢复沿冻结时间继续，不追赶。Canvas 不可用时保留静态艺术与内容。宿主只组合布局，不复制动画或覆盖组件状态。完整生命周期、主题及接入约束见[轨道背景契约](../docs/ORBIT_BACKDROP.md)，真实组件展台为 `/#orbit`。自 0.6.0 起共 60 个组件。

package/components/StatusTimeline.tsx

@@ -1,26 +1,64 @@
-import { useId, useState } from 'react';
+import { useId, useLayoutEffect, useRef, useState } from 'react';
+import * as PopoverBase from '@radix-ui/react-popover';
 import { Text } from './Typography';
+import { KeyValue } from './Data';
+import { Button } from './components';
 
 export type TimelineStatus = 'healthy' | 'recovered' | 'degraded' | 'failed' | 'unknown';
-export interface TimelineSegment { id: string; label: string; status: TimelineStatus }
+export interface TimelineDetail {
+  start: string; end: string; reason?: string;
+  counts?: { id: string; label: string; value: number | null; unit?: string }[];
+  methodology?: string;
+}
+export interface TimelineSegment { id: string; label: string; status: TimelineStatus; detail?: TimelineDetail }
+export interface StatusTimelineProps {
+  label: string; segments: TimelineSegment[]; startLabel: string; endLabel: string; compact?: boolean; disabled?: boolean;
+  activeId?: string; defaultActiveId?: string; onActiveChange?: (id: string) => void;
+  open?: boolean; defaultOpen?: boolean; onOpenChange?: (open: boolean) => void;
+}
 export const timelineLabels: Record<TimelineStatus, string> = { healthy: '有输出·未见异常', recovered: '重试已恢复', degraded: '异常·结果待确认', failed: '存在最终失败', unknown: '未知 / 无数据' };
 
 /** Host supplies ordered, validated evidence; this component never computes a health score. */
-export function StatusTimeline({ label, segments, startLabel, endLabel, compact = false }: { label: string; segments: TimelineSegment[]; startLabel: string; endLabel: string; compact?: boolean }) {
-  const [index, setIndex] = useState<number>();
+export function StatusTimeline({ label, segments, startLabel, endLabel, compact = false, disabled = false, activeId, defaultActiveId, onActiveChange, open: controlledOpen, defaultOpen = false, onOpenChange }: StatusTimelineProps) {
+  const [localId, setLocalId] = useState(defaultActiveId);
+  const [localOpen, setLocalOpen] = useState(defaultOpen), [container, setContainer] = useState<HTMLElement>();
+  const open = controlledOpen ?? localOpen;
+  const setOpen = (next: boolean) => { if (disabled && next) return; if (controlledOpen === undefined) setLocalOpen(next); if (next !== open) onOpenChange?.(next); };
+  const root = useRef<HTMLDivElement>(null), slider = useRef<HTMLInputElement>(null), popup = useRef<HTMLDivElement>(null), returning = useRef(false), focusDetail = useRef(false);
+  useLayoutEffect(() => { setContainer(root.current?.closest<HTMLElement>('.rhine-theme') ?? document.body); }, []);
   const detailId = useId();
-  const selected = Math.min(index ?? segments.length - 1, segments.length - 1);
+  const matched = segments.findIndex(item => item.id === (activeId ?? localId));
+  const selected = matched < 0 ? segments.length - 1 : matched;
+  const select = (index: number) => { const next = segments[index]?.id; if (!next || disabled) return; if (activeId === undefined) setLocalId(next); if (next !== segments[selected]?.id) onActiveChange?.(next); };
   const segment = segments[selected];
-  return <div className={`rhine-timeline${compact ? ' rhine-timeline--compact' : ''}`}>
-    <div className="rhine-timeline__track">
+  const summary = segment ? `${segment.label} · ${timelineLabels[segment.status]}` : '暂无记录';
+  const hasPopup = !disabled && !!segment && (compact || !!segment.detail);
+  return <div ref={root} className={`rhine-timeline${compact ? ' rhine-timeline--compact' : ''}`}>
+    <PopoverBase.Root open={open && hasPopup} onOpenChange={setOpen}><PopoverBase.Anchor asChild><div className="rhine-timeline__track">
       <div className="rhine-timeline__bars" aria-hidden="true">{segments.map((item, i) => <span key={item.id} data-status={item.status} data-selected={i === selected} />)}</div>
-      <input type="range" min={0} max={Math.max(0, segments.length - 1)} value={Math.max(0, selected)} disabled={!segments.length}
+      <input ref={slider} type="range" min={0} max={Math.max(0, segments.length - 1)} value={Math.max(0, selected)} disabled={disabled || !segments.length}
         aria-label={label} aria-valuetext={segment ? `${segment.label} · ${timelineLabels[segment.status]}` : '暂无记录'} aria-describedby={detailId}
-        onChange={event => setIndex(Number(event.target.value))}
-        onPointerMove={event => { if (event.pointerType !== 'mouse' || !segments.length) return; const rect = event.currentTarget.getBoundingClientRect(); setIndex(Math.min(segments.length - 1, Math.max(0, Math.floor((event.clientX - rect.left) / rect.width * segments.length)))); }} />
-    </div>
+        aria-details={open && hasPopup ? `${detailId}-popup` : undefined} aria-controls={open && hasPopup ? `${detailId}-popup` : undefined} aria-haspopup={hasPopup ? 'dialog' : undefined}
+        onFocus={() => { if (!returning.current) setOpen(true); returning.current = false; }}
+        onKeyDown={event => {
+          if (event.key === 'Escape' && open && hasPopup) { event.preventDefault(); event.stopPropagation(); setOpen(false); }
+          if ((event.key === 'Enter' || event.key === ' ') && hasPopup) { event.preventDefault(); if (open) popup.current?.querySelector<HTMLButtonElement>('button')?.focus(); else { focusDetail.current = true; setOpen(true); } }
+        }}
+        onChange={event => { select(Number(event.target.value)); setOpen(true); }}
+        onPointerDown={() => setOpen(true)}
+        onPointerMove={event => { if (disabled || event.pointerType !== 'mouse' || !segments.length) return; const rect = event.currentTarget.getBoundingClientRect(); if (rect.width) select(Math.min(segments.length - 1, Math.max(0, Math.floor((event.clientX - rect.left) / rect.width * segments.length)))); setOpen(true); }} />
+    </div></PopoverBase.Anchor><PopoverBase.Portal container={container}><PopoverBase.Content ref={popup} id={`${detailId}-popup`} className="rhine-timeline-popover" side="top" sideOffset={8} collisionPadding={12} aria-label={`${label}时段详情`}
+      onOpenAutoFocus={event => { event.preventDefault(); if (focusDetail.current) { focusDetail.current = false; popup.current?.querySelector<HTMLButtonElement>('button')?.focus(); } }} onCloseAutoFocus={event => { event.preventDefault(); focusDetail.current = false; if (document.activeElement === document.body || popup.current?.contains(document.activeElement)) { returning.current = true; slider.current?.focus(); } }}
+      onInteractOutside={event => { if (root.current?.contains(event.target as Node)) event.preventDefault(); }}>
+      <div className="rhine-dialog__head"><strong>{summary}</strong><PopoverBase.Close asChild><Button variant="quiet" aria-label="关闭时段详情">关闭</Button></PopoverBase.Close></div>
+      {segment?.detail && <><KeyValue items={[
+        { key: 'start', label: '开始时间', value: segment.detail.start }, { key: 'end', label: '结束时间', value: segment.detail.end },
+        { key: 'reason', label: '状态原因', value: segment.detail.reason || '未提供' },
+        ...(segment.detail.counts ?? []).map(item => ({ key: `count-${item.id}`, label: item.label, value: item.value === null || !Number.isFinite(item.value) ? '未知' : `${item.value}${item.unit ? ` ${item.unit}` : ''}` })),
+      ]} /><p className="rhine-text rhine-text--caption">统计口径：{segment.detail.methodology || '未提供，需向数据来源确认。'}</p></>}
+    </PopoverBase.Content></PopoverBase.Portal></PopoverBase.Root>
     <div className={compact ? 'rhine-sr-only' : 'rhine-timeline__range'}><Text variant="caption" tone="muted">{startLabel}</Text><Text variant="caption" tone="muted">{endLabel}</Text></div>
-    <Text id={detailId} className="rhine-timeline__detail" variant="caption">{segment ? `${segment.label} · ${timelineLabels[segment.status]}` : '暂无记录'}</Text>
+    <Text id={detailId} className={compact && segment ? 'rhine-sr-only' : 'rhine-timeline__summary'} variant="caption">{summary}</Text>
   </div>;
 }
 

package/components/background.css

@@ -0,0 +1,43 @@
+/* Each container resets its paint so local overrides never leak into nested scenes.
+   Background paint does not create a containing block or intercept pointer events. */
+.rhine-background {
+  --rhine-background-color: var(--rhine-content-bg);
+  --rhine-background-foreground: var(--rhine-content-text);
+  --rhine-background-image: var(--rhine-content-texture);
+  --rhine-background-size: var(--rhine-background-scale);
+  min-width: 0;
+  color: var(--rhine-background-foreground);
+  background-color: var(--rhine-background-color);
+  background-image: var(--rhine-background-image);
+  background-size: var(--rhine-background-size);
+  background-position: 0 0;
+  background-attachment: scroll;
+}
+.rhine-background[data-tone=canvas] {
+  --rhine-background-color: var(--rhine-canvas-bg);
+  --rhine-background-foreground: var(--rhine-canvas-text);
+  --rhine-background-image: var(--rhine-canvas-texture);
+}
+.rhine-background[data-tone=sidebar] {
+  --rhine-background-color: var(--rhine-sidebar-bg);
+  --rhine-background-foreground: var(--rhine-sidebar-text);
+  --rhine-background-image: var(--rhine-sidebar-texture);
+}
+.rhine-background[data-tone=surface] {
+  --rhine-background-color: var(--rhine-surface-bg);
+  --rhine-background-foreground: var(--rhine-surface-text);
+  --rhine-background-image: var(--rhine-surface-texture);
+}
+.rhine-background[data-tone=overlay] {
+  --rhine-background-color: var(--rhine-overlay-bg);
+  --rhine-background-foreground: var(--rhine-overlay-text);
+  --rhine-background-image: var(--rhine-overlay-texture);
+}
+.rhine-background[data-tone=media] {
+  --rhine-background-color: var(--rhine-media-bg);
+  --rhine-background-foreground: var(--rhine-media-text);
+  --rhine-background-image: var(--rhine-media-texture);
+  color-scheme: dark;
+}
+.rhine-background[data-decoration=theme] { --rhine-background-image: var(--rhine-background-texture); }
+.rhine-background[data-decoration=none] { background-image: none; }

package/components/charts.css

@@ -0,0 +1,27 @@
+.rhine-chart { min-width:0; margin:0; display:grid; gap:16px; }
+.rhine-chart figcaption { display:grid; gap:4px; overflow-wrap:anywhere; }
+.rhine-chart figcaption strong { font-size:16px; line-height:24px; }
+.rhine-chart figcaption>span,.rhine-chart figcaption p { font-size:12px; line-height:20px; color:var(--rhine-muted); margin:0; }
+.rhine-chart__plot { width:100%; height:180px; overflow:visible; }
+.rhine-chart__scale,.rhine-chart__range { display:flex; justify-content:space-between; gap:16px; font-size:12px; line-height:20px; color:var(--rhine-muted); overflow-wrap:anywhere; }
+.rhine-chart__range>* { min-width:0; }
+.rhine-chart__range>:last-child { text-align:right; }
+.rhine-chart__grid { fill:none; stroke:var(--rhine-chart-grid); stroke-width:1; }
+.rhine-chart__highlight { fill:var(--rhine-selected); stroke:var(--rhine-green); stroke-width:1; vector-effect:non-scaling-stroke; }
+.rhine-chart__inspection { margin:0; min-height:44px; font-size:14px; line-height:22px; overflow-wrap:anywhere; }
+.rhine-chart__line { fill:none; stroke:var(--rhine-chart-series-1); stroke-width:2; }
+.rhine-chart__bar,.rhine-chart__point { fill:var(--rhine-chart-series-1); }
+.rhine-chart__missing { fill:none; stroke:var(--rhine-chart-missing); stroke-width:2; }
+.rhine-chart__legend { margin:0; font-size:12px; line-height:20px; }
+.rhine-chart__legend>span { display:inline-block; width:12px; height:12px; background:var(--rhine-chart-series-1); margin-right:8px; }
+.rhine-chart__data { min-width:0; }
+.rhine-chart__data summary { min-height:44px; padding:12px 4px; cursor:pointer; }
+.rhine-chart__stack { height:32px; display:flex; gap:2px; border:1px solid var(--rhine-line); }
+.rhine-chart__stack>span { flex-basis:0; min-width:0; }
+.rhine-chart [data-tone="1"] { background:var(--rhine-chart-series-1); }
+.rhine-chart [data-tone="2"] { background:var(--rhine-chart-series-2); }
+.rhine-chart [data-tone="3"] { background:var(--rhine-chart-series-3); }
+.rhine-chart [data-tone="4"] { background:var(--rhine-chart-series-4); }
+.rhine-chart__parts { list-style:none; padding:0; margin:0; display:flex; flex-wrap:wrap; gap:8px 16px; font-size:14px; line-height:22px; }
+.rhine-chart__parts li { min-width:0; overflow-wrap:anywhere; }
+.rhine-chart__parts li>span { display:inline-block; width:12px; height:12px; margin-right:8px; border:1px solid var(--rhine-control); }