@linhey/rhine-design 0.6.0 → 0.8.0

package/components/StatusTimeline.tsx

@@ -1,5 +1,6 @@
-import { useId, useLayoutEffect, useRef, useState } from 'react';
+import { useEffect, useId, useLayoutEffect, useRef, useState, type RefObject } from 'react';
 import * as PopoverBase from '@radix-ui/react-popover';
+import { useFloatingScale } from './useFloatingScale';
 import { Text } from './Typography';
 import { KeyValue } from './Data';
 import { Button } from './components';
@@ -18,6 +19,17 @@ export interface StatusTimelineProps {
 }
 export const timelineLabels: Record<TimelineStatus, string> = { healthy: '有输出·未见异常', recovered: '重试已恢复', degraded: '异常·结果待确认', failed: '存在最终失败', unknown: '未知 / 无数据' };
 
+function useTimelineHoverExit(trigger: RefObject<HTMLElement | null>, popup: RefObject<HTMLDivElement | null>, close: () => void) {
+  const timer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  const cancel = () => { clearTimeout(timer.current); timer.current = undefined; };
+  const leave = () => { cancel(); timer.current = setTimeout(() => {
+    const keyboardFocus = document.activeElement === trigger.current && trigger.current?.matches(':focus-visible');
+    if (!keyboardFocus && !popup.current?.contains(document.activeElement)) close();
+  }, 150); };
+  useEffect(() => cancel, []);
+  return { cancel, leave };
+}
+
 /** Host supplies ordered, validated evidence; this component never computes a health score. */
 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);
@@ -25,6 +37,7 @@ export function StatusTimeline({ label, segments, startLabel, endLabel, compact
   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);
+  const detailHadFocus = useRef(false);
   useLayoutEffect(() => { setContainer(root.current?.closest<HTMLElement>('.rhine-theme') ?? document.body); }, []);
   const detailId = useId();
   const matched = segments.findIndex(item => item.id === (activeId ?? localId));
@@ -33,7 +46,11 @@ export function StatusTimeline({ label, segments, startLabel, endLabel, compact
   const segment = segments[selected];
   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' : ''}`}>
+  const attachPopup = useFloatingScale(popup);
+  const hover = useTimelineHoverExit(slider, popup, () => setOpen(false));
+  return <div ref={root} className={`rhine-timeline${compact ? ' rhine-timeline--compact' : ''}`}
+    onPointerEnter={hover.cancel}
+    onPointerLeave={event => { if (event.pointerType === 'mouse' && !(event.relatedTarget instanceof Node && popup.current?.contains(event.relatedTarget))) hover.leave(); }}>
     <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 ref={slider} type="range" min={0} max={Math.max(0, segments.length - 1)} value={Math.max(0, selected)} disabled={disabled || !segments.length}
@@ -47,8 +64,12 @@ export function StatusTimeline({ label, segments, startLabel, endLabel, compact
         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(); } }}
+    </div></PopoverBase.Anchor><PopoverBase.Portal container={container}><PopoverBase.Content ref={attachPopup} id={`${detailId}-popup`} className="rhine-timeline-popover" side="top" sideOffset={8} collisionPadding={12} aria-label={`${label}时段详情`}
+      onPointerEnter={hover.cancel}
+      onPointerLeave={event => { if (event.pointerType === 'mouse' && !(event.relatedTarget instanceof Node && root.current?.contains(event.relatedTarget))) hover.leave(); }}
+      onFocusCapture={() => { detailHadFocus.current = true; }}
+      onBlurCapture={event => { if (event.relatedTarget && event.relatedTarget !== document.body && !event.currentTarget.contains(event.relatedTarget)) detailHadFocus.current = false; }}
+      onOpenAutoFocus={event => { event.preventDefault(); if (focusDetail.current) { focusDetail.current = false; popup.current?.querySelector<HTMLButtonElement>('button')?.focus(); } }} onCloseAutoFocus={event => { event.preventDefault(); focusDetail.current = false; if (detailHadFocus.current && (document.activeElement === document.body || popup.current?.contains(document.activeElement))) { returning.current = true; slider.current?.focus(); } detailHadFocus.current = false; }}
       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={[
@@ -62,6 +83,51 @@ export function StatusTimeline({ label, segments, startLabel, endLabel, compact
   </div>;
 }
 
-export function TimelineLegend() {
-  return <ul className="rhine-timeline__legend" aria-label="健康记录图例">{Object.entries(timelineLabels).map(([status, label]) => <li key={status}><span data-status={status} aria-hidden="true"/>{label}</li>)}</ul>;
+export interface TimelineLegendItem { status: TimelineStatus; label: string; description?: string }
+export interface TimelineLegendProps { label?: string; compact?: boolean; items?: TimelineLegendItem[] }
+const defaultLegendItems: TimelineLegendItem[] = Object.entries(timelineLabels).map(([status, label]) => ({ status: status as TimelineStatus, label }));
+
+/** Short labels describe evidence; hosts provide the precise rules rather than relying on color. */
+export function TimelineLegend({ label = '健康记录图例', compact = false, items = defaultLegendItems }: TimelineLegendProps) {
+  const root = useRef<HTMLUListElement>(null);
+  const [container, setContainer] = useState<HTMLElement>();
+  const [active, setActive] = useState<TimelineStatus | null>(null);
+  useLayoutEffect(() => { setContainer(root.current?.closest<HTMLElement>('.rhine-theme') ?? document.body); }, []);
+  useEffect(() => { if (active && !items.some(item => item.status === active && item.description)) setActive(null); }, [active, items]);
+  return <ul ref={root} className={`rhine-timeline__legend${compact ? ' rhine-timeline__legend--compact' : ''}`} aria-label={label}>
+    {items.map(item => <LegendItem key={item.status} item={item} container={container} open={active === item.status}
+      onOpenChange={next => setActive(current => next ? item.status : current === item.status ? null : current)} />)}
+  </ul>;
+}
+
+function LegendItem({ item, container, open, onOpenChange }: { item: TimelineLegendItem; container?: HTMLElement; open: boolean; onOpenChange: (open: boolean) => void }) {
+  const id = useId(), trigger = useRef<HTMLButtonElement>(null), popup = useRef<HTMLDivElement>(null), returning = useRef(false);
+  const detailHadFocus = useRef(false);
+  const hover = useTimelineHoverExit(trigger, popup, () => onOpenChange(false));
+  const attachPopup = useFloatingScale(popup);
+  const marker = <span data-status={item.status} aria-hidden="true" />;
+  if (!item.description) return <li>{marker}{item.label}</li>;
+  return <li><PopoverBase.Root open={open} onOpenChange={onOpenChange}><PopoverBase.Anchor asChild>
+    <button ref={trigger} type="button" className="rhine-timeline__legend-trigger" aria-haspopup="dialog" aria-expanded={open} aria-controls={open ? id : undefined}
+      onFocus={() => { if (!returning.current) onOpenChange(true); returning.current = false; }}
+      onClick={() => onOpenChange(true)}
+      onPointerEnter={event => { if (event.pointerType === 'mouse') { hover.cancel(); onOpenChange(true); } }}
+      onPointerLeave={event => { if (event.pointerType === 'mouse' && !(event.relatedTarget instanceof Node && popup.current?.contains(event.relatedTarget))) hover.leave(); }}
+      onKeyDown={event => {
+        if (event.key === 'Escape' && open) { event.preventDefault(); event.stopPropagation(); onOpenChange(false); }
+        if ((event.key === 'Enter' || event.key === ' ') && open) { event.preventDefault(); popup.current?.querySelector<HTMLButtonElement>('button')?.focus(); }
+      }}>
+      {marker}{item.label}
+    </button>
+  </PopoverBase.Anchor><PopoverBase.Portal container={container}><PopoverBase.Content ref={attachPopup} id={id} className="rhine-timeline-popover" aria-label={`${item.label}规则`} side="top" sideOffset={8} collisionPadding={12}
+    onFocusCapture={() => { detailHadFocus.current = true; }}
+    onBlurCapture={event => { if (event.relatedTarget && event.relatedTarget !== document.body && !event.currentTarget.contains(event.relatedTarget)) detailHadFocus.current = false; }}
+    onOpenAutoFocus={event => event.preventDefault()}
+    onCloseAutoFocus={event => { event.preventDefault(); if (detailHadFocus.current && (popup.current?.contains(document.activeElement) || document.activeElement === document.body)) { returning.current = true; trigger.current?.focus(); } detailHadFocus.current = false; }}
+    onInteractOutside={event => { if (event.target === trigger.current || trigger.current?.contains(event.target as Node)) event.preventDefault(); }}
+    onPointerEnter={hover.cancel}
+    onPointerLeave={event => { if (event.pointerType === 'mouse' && !(event.relatedTarget instanceof Node && trigger.current?.contains(event.relatedTarget))) hover.leave(); }}>
+    <div className="rhine-dialog__head"><strong>{item.label}</strong><PopoverBase.Close asChild><Button variant="quiet" aria-label={`关闭${item.label}规则`}>关闭</Button></PopoverBase.Close></div>
+    <Text>{item.description}</Text>
+  </PopoverBase.Content></PopoverBase.Portal></PopoverBase.Root></li>;
 }

package/components/StatusTimelineList.tsx

@@ -0,0 +1,38 @@
+import { useEffect, useState, type ReactNode } from 'react';
+import { Text } from './Typography';
+import { StatusTimeline, type StatusTimelineProps } from './StatusTimeline';
+
+export interface StatusTimelineItem {
+  id: string;
+  title: string;
+  summary?: ReactNode;
+  note?: string;
+  timeline: Pick<StatusTimelineProps, 'segments' | 'startLabel' | 'endLabel' | 'disabled'> | null;
+  unavailableLabel?: string;
+}
+export interface StatusTimelineListProps {
+  label: string;
+  items: StatusTimelineItem[];
+  emptyLabel?: string;
+}
+
+/** Hosts supply ordering, summaries and evidence; the list only coordinates presentation. */
+export function StatusTimelineList({ label, items, emptyLabel = '暂无历史记录' }: StatusTimelineListProps) {
+  const [openId, setOpenId] = useState<string | null>(null);
+  useEffect(() => {
+    const item = items.find(item => item.id === openId);
+    if (openId !== null && (!item?.timeline || item.timeline.disabled || !item.timeline.segments.length)) setOpenId(null);
+  }, [items, openId]);
+  if (!items.length) return <Text variant="caption">{emptyLabel}</Text>;
+  return <ul className="rhine-timeline-list" aria-label={label}>
+    {items.map(item => <li className="rhine-timeline-list__item" key={item.id}>
+      <div className="rhine-timeline-list__heading"><Text as="h4" variant="body">{item.title}</Text>
+        {item.summary != null && <Text variant="caption" tone="muted">{item.summary}</Text>}
+      </div>
+      {item.note && <Text variant="caption" tone="muted">{item.note}</Text>}
+      {item.timeline ? <StatusTimeline {...item.timeline} compact label={`${item.title} 历史时段`}
+        open={openId === item.id} onOpenChange={next => setOpenId(current => next ? item.id : current === item.id ? null : current)} />
+        : <Text variant="caption" tone="muted">{item.unavailableLabel ?? '历史记录暂不可用 · 未知'}</Text>}
+    </li>)}
+  </ul>;
+}

package/components/ThemePicker.tsx

@@ -0,0 +1,49 @@
+import { useId, useState } from 'react';
+import { themes, type ThemeName } from './themeMetadata';
+import rhine from './assets/theme-previews/rhine.png?no-inline';
+import arknights from './assets/theme-previews/arknights.png?no-inline';
+import neoBrutalism from './assets/theme-previews/neo-brutalism.png?no-inline';
+import './theme-picker.css';
+
+const sources: Record<ThemeName, string> = { rhine, arknights, 'neo-brutalism': neoBrutalism };
+const descriptions: Record<ThemeName, string> = {
+  rhine: '暖白纸面、苔绿操作与细线边界。',
+  arknights: '深色工作区、明亮信号与切角边界。',
+  'neo-brutalism': '米白表面、亮橙操作与墨色硬阴影。',
+};
+
+export interface ThemePreviewProps { theme: ThemeName; src?: string }
+function PreviewImage({ src }: { src: string }) {
+  const [state, setState] = useState<'loading' | 'ready' | 'error'>('loading');
+  return <span className="rhine-theme-preview" aria-hidden="true" data-state={state}>
+    {state === 'error' ? <span>预览暂不可用</span> : <><img src={src} alt="" width={960} height={600} decoding="async" onLoad={() => setState('ready')} onError={() => setState('error')} />{state === 'loading' && <span className="rhine-theme-preview__loading">正在加载预览</span>}</>}
+  </span>;
+}
+/** Decorative, versioned snapshot; it never mounts a nested ThemeProvider. */
+export function ThemePreview({ theme, src = sources[theme] }: ThemePreviewProps) {
+  return <PreviewImage key={src} src={src} />;
+}
+
+export interface ThemePickerOption {
+  value: ThemeName; label?: string; description?: string; disabled?: boolean; previewSrc?: string;
+}
+export interface ThemePickerProps {
+  label?: string; value: ThemeName; onValueChange: (value: ThemeName) => void;
+  options?: readonly ThemePickerOption[]; disabled?: boolean;
+}
+/** Controlled native radios: the host owns applying and persisting the theme. */
+export function ThemePicker({ label = '界面主题', value, onValueChange, options = themes.map(theme => ({ value: theme.name })), disabled = false }: ThemePickerProps) {
+  const id = useId();
+  return <fieldset className="rhine-theme-picker" disabled={disabled}><legend>{label}</legend>
+    <div className="rhine-theme-picker__options">{options.map(option => {
+      const title = option.label ?? themes.find(theme => theme.name === option.value)!.label;
+      const selected = value === option.value;
+      const descriptionId = `${id}-${option.value}`;
+      return <label className="rhine-theme-option" key={option.value}>
+        <input className="rhine-sr-only" type="radio" name={id} value={option.value} checked={selected} disabled={option.disabled} aria-label={title} aria-describedby={descriptionId} onChange={() => onValueChange(option.value)} />
+        <ThemePreview theme={option.value} src={option.previewSrc} />
+        <span className="rhine-theme-option__copy"><strong>{title}</strong><span className="rhine-theme-option__description" id={descriptionId}>{option.description ?? descriptions[option.value]}</span><span className="rhine-theme-option__status" aria-hidden="true">{selected ? '✓ 已使用' : option.disabled || disabled ? '暂不可用' : '选择应用'}</span></span>
+      </label>;
+    })}</div>
+  </fieldset>;
+}