@linhey/rhine-design 0.3.0 → 0.5.0

package/components/Charts.tsx

@@ -0,0 +1,94 @@
+import { useId, useState, type CSSProperties, type ReactNode } from 'react';
+import { DataTable } from './Data';
+import { EmptyState, Notice } from './components';
+
+export interface ChartPoint { id: string; label: string; value: number | null }
+interface ChartContext { label: string; unit: string; rangeLabel: string; description: string; stale?: string; error?: string; loading?: boolean; valueFormatter?: (value: number | null) => string }
+export interface TrendChartProps extends ChartContext {
+  points: ChartPoint[]; kind?: 'bar' | 'line';
+  activePointId?: string | null; defaultActivePointId?: string; onActivePointChange?: (id: string | null) => void;
+}
+const known = (value: number | null): value is number => value !== null && Number.isFinite(value);
+
+function ChartFrame({ label, unit, rangeLabel, description, stale, error, loading, children }: ChartContext & { children: ReactNode }) {
+  return <figure className="rhine-chart" aria-label={label} aria-busy={loading}>
+    <figcaption><strong>{label}</strong><span>{rangeLabel} · 单位：{unit}</span><p>{description}</p></figcaption>
+    {error && <Notice title="图表读取失败" tone="error">{error} · 已有数据仅供参考。</Notice>}
+    {stale && <Notice title="数据已陈旧" tone="warning">{stale}</Notice>}
+    {loading && <p role="status">正在读取，保留已有数据。</p>}{children}
+  </figure>;
+}
+
+/** The host provides bucket order, timestamps, units, and aggregation semantics. */
+export function TrendChart({ points, kind = 'bar', activePointId, defaultActivePointId, onActivePointChange, ...context }: TrendChartProps) {
+  const id = useId(), finite = points.map(point => point.value).filter(known);
+  const [localActive, setLocalActive] = useState<string | null>(defaultActivePointId ?? null);
+  const [focused, setFocused] = useState(false);
+  const active = activePointId === undefined ? localActive : activePointId;
+  const activeIndex = points.findIndex(point => point.id === active), activePoint = points[activeIndex];
+  const select = (next: string | null) => { if (activePointId === undefined) setLocalActive(next); if (next !== active) onActivePointChange?.(next); };
+  const format = (value: number | null) => context.valueFormatter ? context.valueFormatter(known(value) ? value : null) : known(value) ? String(value) : '未知';
+  const minimum = finite.reduce((min, value) => Math.min(min, value), 0), maximum = finite.reduce((max, value) => Math.max(max, value), 0);
+  // Normalize first so opposite finite extremes cannot overflow the coordinate span.
+  const magnitude = Math.max(Math.abs(minimum), Math.abs(maximum), 1), span = (maximum / magnitude - minimum / magnitude) || 1;
+  const x = (index: number) => (index + 0.5) * 600 / Math.max(1, points.length);
+  const y = (value: number) => 170 - (value / magnitude - minimum / magnitude) / span * 160;
+  let connected = false;
+  const path = points.map((point, index) => {
+    if (!known(point.value)) { connected = false; return ''; }
+    const command = connected ? 'L' : 'M'; connected = true;
+    return `${command}${x(index)},${y(point.value)}`;
+  }).join(' ');
+  return <ChartFrame {...context}>
+    {!finite.length ? <EmptyState title={points.length ? '所有采样值均未知' : '暂无采样'} description="缺失值不会补零。" /> : <>
+      <div className="rhine-chart__scale"><span>{format(maximum)} {context.unit}</span><span>{format(minimum)} {context.unit}</span></div>
+      <svg className="rhine-chart__plot" viewBox="0 0 600 180" preserveAspectRatio="none" role="img" aria-labelledby={`${id}-title ${id}-description`} aria-describedby={`${id}-inspection`} tabIndex={0}
+        onFocus={() => { setFocused(true); if (!activePoint) select(points[0]?.id ?? null); }} onBlur={() => setFocused(false)}
+        onKeyDown={event => {
+          if (event.altKey || event.ctrlKey || event.metaKey) return;
+          const next = event.key === 'Home' ? 0 : event.key === 'End' ? points.length - 1 : event.key === 'ArrowLeft' ? Math.max(0, activeIndex - 1) : event.key === 'ArrowRight' ? Math.min(points.length - 1, activeIndex + 1) : undefined;
+          if (next !== undefined) { event.preventDefault(); select(points[next]?.id ?? null); }
+        }}
+        onPointerMove={event => {
+          if (event.pointerType !== 'mouse' && !event.buttons) return;
+          const rect = event.currentTarget.getBoundingClientRect();
+          if (rect.width) select(points[Math.max(0, Math.min(points.length - 1, Math.floor((event.clientX - rect.left) / rect.width * points.length)))]?.id ?? null);
+        }}
+        onPointerLeave={() => { if (!focused) select(null); }}
+        onClick={event => {
+          const rect = event.currentTarget.getBoundingClientRect();
+          event.currentTarget.focus();
+          if (rect.width) select(points[Math.max(0, Math.min(points.length - 1, Math.floor((event.clientX - rect.left) / rect.width * points.length)))]?.id ?? null);
+        }}>
+        <title id={`${id}-title`}>{context.label} · {kind === 'bar' ? '柱形趋势' : '历史折线'}</title>
+        <desc id={`${id}-description`}>{context.description}；{points.length} 个时段，{points.length - finite.length} 个未知值。完整标签与数值见下方数据表。</desc>
+        <path className="rhine-chart__grid" d={`M0,${y(0)}H600 M0,10H600 M0,170H600`} />
+        {activePoint && <rect className="rhine-chart__highlight" x={activeIndex * 600 / points.length} y={0} width={600 / points.length} height={180} />}
+        {kind === 'line' && <path className="rhine-chart__line" d={path} vectorEffect="non-scaling-stroke" />}
+        {points.map((point, index) => !known(point.value) ? <path key={point.id} className="rhine-chart__missing" d={`M${x(index) - 3},174l6,6m0,-6l-6,6`} vectorEffect="non-scaling-stroke" /> : kind === 'bar' ?
+          <rect key={point.id} className="rhine-chart__bar" x={x(index) - 210 / points.length} y={Math.min(y(0), y(point.value))} width={420 / points.length} height={Math.abs(y(point.value) - y(0))}><title>{point.label}：{point.value} {context.unit}</title></rect> :
+          <circle key={point.id} className="rhine-chart__point" cx={x(index)} cy={y(point.value)} r={3}><title>{point.label}：{point.value} {context.unit}</title></circle>)}
+      </svg>
+      <div className="rhine-chart__range"><span>{points[0]?.label}</span><span>{points.at(-1)?.label}</span></div>
+      <p className="rhine-chart__legend"><span aria-hidden="true" />{context.label} · × 表示缺失；折线在缺失处断开。</p>
+      <p id={`${id}-inspection`} className="rhine-chart__inspection" aria-live="polite" aria-atomic="true">{activePoint ? `${activePoint.label}：${format(activePoint.value)}${known(activePoint.value) ? ` ${context.unit}` : ''}` : '聚焦图形后用左右键、Home / End 查看采样；也可悬停或轻触。'}</p>
+    </>}
+    <details className="rhine-chart__data"><summary>查看{context.label}数据表</summary><DataTable caption={`${context.label}原始采样`} rows={points} rowKey={point => point.id} columns={[
+      { key: 'label', header: '时段', render: point => point.label }, { key: 'value', header: `值（${context.unit}）`, render: point => known(point.value) ? point.value : '未知' },
+    ]} /></details>
+  </ChartFrame>;
+}
+
+export interface ChartPart extends ChartPoint { tone?: 1 | 2 | 3 | 4 }
+export interface StackedBarProps extends ChartContext { parts: ChartPart[] }
+export function StackedBar({ parts, ...context }: StackedBarProps) {
+  const incomplete = parts.some(part => !known(part.value)), invalid = parts.some(part => known(part.value) && part.value < 0);
+  const total = parts.reduce((sum, part) => sum + (known(part.value) ? part.value : 0), 0);
+  const complete = parts.length > 0 && !incomplete && !invalid && Number.isFinite(total) && total > 0;
+  return <ChartFrame {...context}>
+    {complete ? <div className="rhine-chart__stack" role="img" aria-label={`${context.label}：${parts.map(part => `${part.label} ${part.value} ${context.unit}`).join('；')}。完整比例见图例。`}>
+      {parts.map((part, index) => part.value! > 0 && <span key={part.id} data-tone={part.tone ?? index % 4 + 1} style={{ flexGrow: part.value! / total } as CSSProperties} />)}
+    </div> : <p role="status">{invalid ? '包含负数，无法绘制占比。' : incomplete ? '总量未知，不计算占比。' : total === 0 && parts.length ? '已知总量为 0，无占比。' : '暂无可绘制的占比。'}</p>}
+    <ul className="rhine-chart__parts" aria-label={`${context.label}图例`}>{parts.map((part, index) => <li key={part.id}><span aria-hidden="true" data-tone={part.tone ?? index % 4 + 1} />{part.label}：{context.valueFormatter ? context.valueFormatter(known(part.value) ? part.value : null) : known(part.value) ? part.value : '未知'}{known(part.value) ? ` ${context.unit}` : ''}{complete ? `（${(part.value! / total * 100).toFixed(1)}%）` : ''}</li>)}</ul>
+  </ChartFrame>;
+}

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/FormWorkflow.tsx

@@ -0,0 +1,25 @@
+import { useEffect, useId, useRef, type FieldsetHTMLAttributes, type ReactNode } from 'react';
+
+export interface FieldsetProps extends FieldsetHTMLAttributes<HTMLFieldSetElement> { legend: string; hint?: string; children: ReactNode }
+export function Fieldset({ legend, hint, children, className = '', 'aria-describedby': describedBy, ...props }: FieldsetProps) {
+  const id = useId();
+  return <fieldset {...props} className={`rhine-fieldset ${className}`} aria-describedby={[describedBy, hint ? id : undefined].filter(Boolean).join(' ') || undefined}>
+    <legend>{legend}</legend>{hint && <p id={id}>{hint}</p>}<div className="rhine-fieldset__body">{children}</div>
+  </fieldset>;
+}
+
+export interface FieldError { fieldId: string; message: string }
+export interface ErrorSummaryProps { errors: readonly FieldError[]; title?: string; focusKey?: number }
+export function ErrorSummary({ errors, title = '请修正以下问题', focusKey }: ErrorSummaryProps) {
+  const ref = useRef<HTMLDivElement>(null), id = useId();
+  const hasErrors = errors.length > 0;
+  // Focus only on a failed submission, never on each keystroke. Increment focusKey for retries.
+  useEffect(() => { if (hasErrors && focusKey !== undefined) ref.current?.focus(); }, [focusKey, hasErrors]);
+  if (!hasErrors) return null;
+  return <div className="rhine-error-summary" ref={ref} tabIndex={-1} role="region" aria-labelledby={id}>
+    <h3 id={id}>{title}</h3><ul>{errors.map(error => <li key={error.fieldId}><a href={`#${error.fieldId}`} onClick={event => {
+      const field = document.getElementById(error.fieldId);
+      if (field) { event.preventDefault(); field.focus(); field.scrollIntoView?.({ block: 'center' }); }
+    }}>{error.message}</a></li>)}</ul>
+  </div>;
+}

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

@@ -4,7 +4,7 @@
 
 2026-10-22，用户指定 [Transitions.dev](https://transitions.dev/) 作为UX与动画参考。本文件补充[组件规范](./README.md#动效规范)，保留Rhine Design的苔绿、暖白、三角几何与清晰文字。以下参数是本项目设计决定，不是对参考站时长或曲线的测量结果。
 
-用户已进一步授权实现展台：`/#motion`提供10组可播放、重播、复位的真实示例，支持原速/4倍慢放、逐例减少动态及全局偏好。组件总数保持40；新配方仍限定于展台，后续按“展台评审 → 通用组件采用 → App接入”推进。
+用户已进一步授权实现展台：`/#motion`目前提供12组可播放、重播、复位的真实示例，支持原速/4倍慢放、逐例减少动态及全局偏好。main组件共46个（npm0.3.0为40个）；实验性配方仍限定于展台，后续按“展台评审 → 通用组件采用 → App接入”推进。
 
 ## 参考依据
 
@@ -20,7 +20,7 @@
 4. **动效可被主动比较。** 展台后续为每种动效提供静态起点、播放/切换、重播、参数说明及减少动态对照。重播只改变本地演示状态，不重新执行复制、请求、确认等真实动作。
 5. **解释适用条件。** 示例卡写清“触发 → 变化 → 结束状态”，并显示已实现/设计候选；筛选只改变展台展示范围，不改变组件业务值。宽屏并排对照，窄屏单列，播放按钮位置稳定。
 
-动效实验室已为10组配方提供上述播放控制、状态说明、参数和逐例减少动态开关；并排卡片可分别设置偏好作比较。既有组件目录保留普通交互示例，不给每个无动画组件添加播放按钮。
+动效实验室已为12组配方提供上述播放控制、状态说明、参数和逐例减少动态开关；并排卡片可分别设置偏好作比较。既有组件目录保留普通交互示例，不给每个无动画组件添加播放按钮。
 
 ## Rhine Design 动效映射
 
@@ -70,3 +70,7 @@
 首次内容切换不闪空白、不让操作目标跳位；刷新不丢旧数据；退出后无透明遮挡层和遗留焦点；无隐藏控件可Tab到。文档参数、DOM存在与单张截图不能代替完整动效或宿主原生平台原生验收。
 
 2026-10-22展台验证：Chrome通过400/520/880/1200宽度、200%缩放、10组播放/复位、快速重播取消旧结果、四向位置/位移采样、菜单键盘、弹窗内重播保焦点与关闭归还、折叠中途反向、通知关闭、Tooltip Escape、逐例/全局/系统减少动态。采样确认4倍慢放的内容淡入720ms、反馈480ms、浮层640ms、折叠800ms及品牌960ms；未将合成浏览器结果扩展为原生或业务验收。
+
+## 导航与流程动效（main，未发布）
+
+新增抽屉与步骤两组示例，实验室现为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/Navigation.tsx

@@ -0,0 +1,42 @@
+import type { HTMLAttributes, MouseEvent } from 'react';
+import { Icon, type IconName } from './Actions';
+
+export interface NavItem { id: string; label: string; href: string; icon?: IconName }
+export interface NavGroup { label: string; items: readonly NavItem[] }
+export interface SideNavProps extends HTMLAttributes<HTMLElement> {
+  groups: readonly NavGroup[]; currentId: string;
+  onNavigate?: (item: NavItem, event: MouseEvent<HTMLAnchorElement>) => void;
+}
+export function SideNav({ groups, currentId, onNavigate, className = '', 'aria-label': label = '主导航', ...props }: SideNavProps) {
+  return <nav {...props} aria-label={label} className={`rhine-side-nav ${className}`}>
+    {groups.map(group => <div className="rhine-side-nav__group" key={group.label}><p>{group.label}</p><ul>
+      {group.items.map(item => <li key={item.id}><a href={item.href} aria-current={currentId === item.id ? 'page' : undefined} onClick={event => onNavigate?.(item, event)}>{item.icon && <Icon name={item.icon} size={20}/>}<span className="rhine-side-nav__label">{item.label}</span></a></li>)}
+    </ul></div>)}
+  </nav>;
+}
+
+export interface BreadcrumbItem { label: string; href?: string }
+export interface BreadcrumbsProps { items: readonly BreadcrumbItem[]; label?: string }
+export function Breadcrumbs({ items, label = '当前位置' }: BreadcrumbsProps) {
+  return <nav className="rhine-breadcrumbs" aria-label={label}><ol>{items.map((item, index) => <li key={index}>
+    {index > 0 && <span aria-hidden="true" className="rhine-breadcrumbs__separator">/</span>}
+    {item.href ? <a href={item.href} aria-current={index === items.length - 1 ? 'page' : undefined}>{item.label}</a> : <span aria-current={index === items.length - 1 ? 'page' : undefined}>{item.label}</span>}
+  </li>)}</ol></nav>;
+}
+
+export interface StepItem { id: string; label: string; description?: string }
+export interface StepsProps {
+  items: readonly StepItem[]; current: number; label?: string; error?: string;
+  onStepChange?: (index: number) => void;
+}
+export function Steps({ items, current, label = '任务步骤', error, onStepChange }: StepsProps) {
+  const position = Math.max(0, Math.min(current, items.length));
+  return <ol className="rhine-steps" aria-label={label}>{items.map((item, index) => {
+    const state = index < position ? 'complete' : index === position ? (error ? 'error' : 'current') : 'pending';
+    const status = { complete: '已完成', current: '进行中', error: '需要修正', pending: '未开始' }[state];
+    const content = <><span className="rhine-steps__number" aria-hidden="true">{state === 'complete' ? '✓' : String(index + 1).padStart(2, '0')}</span><span><strong>{item.label}</strong><small>{status}{item.description ? ` · ${item.description}` : ''}{state === 'error' ? ` · ${error}` : ''}</small></span></>;
+    return <li key={item.id} data-state={state} aria-current={index === position ? 'step' : undefined}>
+      {onStepChange && index < position ? <button type="button" onClick={() => onStepChange(index)} aria-label={`返回${item.label}`}>{content}</button> : <div>{content}</div>}
+    </li>;
+  })}</ol>;
+}

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() {
@@ -14,11 +15,17 @@ function useScope() {
   useLayoutEffect(() => { setContainer((ref.current?.closest('.rhine-theme') as HTMLElement) || document.body); }, []);
   return { ref, container };
 }
-export interface DialogProps { trigger: ReactElement; title: string; description: string; children: ReactNode; open?: boolean; onOpenChange?: (open: boolean) => void }
-export function Dialog({ trigger, title, description, children, open, onOpenChange }: DialogProps) {
+export interface DialogProps { trigger: ReactElement; title: string; description: string; children: ReactNode; open?: boolean; onOpenChange?: (open: boolean) => void; sidePanel?: ReactNode | ((closeButton: ReactElement) => ReactNode) }
+export function Dialog(props: DialogProps) {
+  return <DialogFrame {...props}/>;
+}
+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"><div className="rhine-dialog__head"><DialogBase.Title className="rhine-text rhine-text--section">{title}</DialogBase.Title><DialogBase.Close asChild><IconButton label="关闭对话框" icon="close" /></DialogBase.Close></div><DialogBase.Description className="rhine-text rhine-text--body rhine-text--muted">{description}</DialogBase.Description><div className="rhine-dialog__body">{children}</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 }) {