@mohou/ui 1.0.20

package/src/blocks/list-detail.tsx

@@ -0,0 +1,120 @@
+
+import type { ReactNode } from 'react';
+
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from '@mohou/ui/components/resizable';
+import { useIsMobile } from '@mohou/ui/hooks/use-mobile';
+import { useLabels } from '@mohou/ui/i18n/context';
+import { cn } from '@mohou/ui/lib/utils';
+
+export type ListDetailProps = {
+  /** The collection pane: list, table, board — anything you scroll through. */
+  list: ReactNode
+  /** The record pane. Pass `undefined` for "nothing selected" — `empty` renders instead. */
+  detail?: ReactNode
+  /** Placeholder for the record pane while nothing is selected. */
+  empty?: ReactNode
+  /** Search / filters / create button. Fixed above the panes; it never scrolls. */
+  toolbar?: ReactNode
+  /** Narrow screens show one pane at a time. The app owns which one. */
+  mobileView?: 'list' | 'detail';
+  /** Renders a back control on the record pane below `md`. No-op on wide screens. */
+  onMobileBack?: () => void
+  /** Collection pane share of the width, 0-100. Default 34. */
+  defaultSize?: number
+  /** Collection pane floor, so a long record title cannot push it away. Default 18. */
+  minSize?: number
+  className?: string
+}
+
+/** One scroll container per pane, and nothing above it that also scrolls. */
+const PANE = 'h-full min-h-0 w-full overflow-y-auto';
+
+/**
+ * Two-pane record browser: the list holds its place while the selected record scrolls on its own.
+ *
+ * This is the shape agents get wrong without help — a flex child with no `min-h-0` grows to fit
+ * its content, so the whole page scrolls, the toolbar slides away, and the two panes are never
+ * independent. Both panes scroll here by construction, and the record pane collapses to a
+ * full-width view below `md` instead of squashing.
+ *
+ * @when Page shape: click a row, then read or edit that one record beside the list — orders, tickets, contacts, log lines
+ * @example
+ * <ListDetail
+ *   toolbar={<SearchInput />}
+ *   list={<OrderList />}
+ *   detail={order ? <OrderCard order={order} /> : undefined}
+ *   empty={<div>Pick an order</div>}
+ *   mobileView={order ? "detail" : "list"}
+ *   onMobileBack={() => setOrder(null)}
+ * />
+ * @family Layout & structure
+ */
+export function ListDetail({
+  list,
+  detail,
+  empty,
+  toolbar,
+  mobileView = 'list',
+  onMobileBack,
+  defaultSize = 34,
+  minSize = 18,
+  className,
+}: ListDetailProps) {
+  const isMobile = useIsMobile()
+  const t = useLabels('listDetail');
+
+  const listPane = (
+    <div className={PANE} data-testid="list-detail-list">
+      {list}
+    </div>
+  )
+
+  const detailPane = (
+    <div className={PANE} data-testid="list-detail-detail">
+      {isMobile && detail && onMobileBack ? (
+        <button
+          type="button"
+          onClick={onMobileBack}
+          className="text-muted-foreground -mb-2 px-4 pt-3 pb-1 text-sm underline-offset-4 hover:underline"
+          data-testid="list-detail-back"
+        >
+          {t.back}
+        </button>
+      ) : null}
+      {detail ?? empty ?? null}
+    </div>
+  )
+
+  return (
+    <div
+      className={cn('flex h-full min-h-0 w-full flex-col', className)}
+      data-testid="list-detail"
+    >
+      {toolbar ? (
+        <div className="shrink-0" data-testid="list-detail-toolbar">
+          {toolbar}
+        </div>
+      ) : null}
+
+      {isMobile ? (
+        <div className="min-h-0 flex-1">
+          {mobileView === 'detail' ? detailPane : listPane}
+        </div>
+      ) : (
+        <ResizablePanelGroup orientation="horizontal" className="min-h-0 flex-1">
+          <ResizablePanel defaultSize={defaultSize} minSize={minSize}>
+            {listPane}
+          </ResizablePanel>
+          <ResizableHandle withHandle />
+          <ResizablePanel defaultSize={100 - defaultSize} minSize={30}>
+            {detailPane}
+          </ResizablePanel>
+        </ResizablePanelGroup>
+      )}
+    </div>
+  )
+}

package/src/blocks/notification-center.tsx

@@ -0,0 +1,29 @@
+import { Item, ItemContent, ItemDescription, ItemTitle } from '@mohou/ui/components/item'
+
+export type NotificationItem = {
+  id: string
+  title: string
+  body?: string
+}
+
+/**
+ * Grouped notification list with unread state.
+ * @when Inbox/alert panel. Audit log (read-only, with time) → `ActivityFeed`.
+ * @example
+ * <NotificationCenter items={[{ id: "n1", title: "构建失败", unread: true }]} />
+ * @family Feedback & status
+ */
+export function NotificationCenter({ items }: { items: NotificationItem[] }) {
+  return (
+    <div className="flex flex-col gap-1" data-testid="notification-center">
+      {items.map(item => (
+        <Item key={item.id} variant="outline">
+          <ItemContent>
+            <ItemTitle>{item.title}</ItemTitle>
+            {item.body ? <ItemDescription>{item.body}</ItemDescription> : null}
+          </ItemContent>
+        </Item>
+      ))}
+    </div>
+  )
+}

package/src/blocks/page-header.tsx

@@ -0,0 +1,31 @@
+import type { ReactNode } from 'react'
+
+export type PageHeaderProps = {
+  title: string
+  description?: string
+  actions?: ReactNode
+}
+
+/**
+ * Page title row with optional description and right-side actions.
+ * @when Top of a page inside AppShell main
+ * @example
+ * <PageHeader title="QA Runs" description="Last 24h" actions={<Button>New</Button>} />
+ * @family Layout & structure
+ */
+export function PageHeader({ title, description, actions }: PageHeaderProps) {
+  return (
+    <div
+      className="flex flex-wrap items-start justify-between gap-3"
+      data-testid="page-header"
+    >
+      <div className="flex min-w-0 flex-col gap-1">
+        <h1 className="font-heading text-xl font-medium">{title}</h1>
+        {description ? (
+          <p className="text-muted-foreground text-sm">{description}</p>
+        ) : null}
+      </div>
+      {actions ? <div className="flex items-center gap-2">{actions}</div> : null}
+    </div>
+  )
+}

package/src/blocks/progress-ring.tsx

@@ -0,0 +1,43 @@
+import { cn } from '../lib/utils'
+
+/**
+ * Circular determinate progress.
+ * @when One percent-done value in a tight space (card corner, table cell).
+ * @example
+ * <ProgressRing value={45} size={56} />
+ * @family Feedback & status
+ */
+export function ProgressRing({
+  value,
+  size,
+  className,
+}: {
+  value: number
+  size?: number
+  className?: string
+}) {
+  const clamped = Math.min(100, Math.max(0, value))
+  const r = 16
+  const c = 2 * Math.PI * r
+  const offset = c - (clamped / 100) * c
+  return (
+    <svg
+      data-testid="progress-ring"
+      viewBox="0 0 40 40"
+      style={size ? { width: size, height: size } : undefined}
+      className={cn('-rotate-90 size-10', className)}
+    >
+      <circle cx="20" cy="20" r={r} className="fill-none stroke-muted" strokeWidth="4" />
+      <circle
+        cx="20"
+        cy="20"
+        r={r}
+        className="fill-none stroke-primary"
+        strokeWidth="4"
+        strokeDasharray={c}
+        strokeDashoffset={offset}
+        strokeLinecap="round"
+      />
+    </svg>
+  )
+}

package/src/blocks/radar-chart.tsx

@@ -0,0 +1,47 @@
+
+import { PolarAngleAxis, PolarGrid, Radar, RadarChart as ReRadar } from 'recharts'
+
+import {
+  ChartContainer,
+  ChartTooltip,
+  ChartTooltipContent,
+  type ChartConfig,
+} from '@mohou/ui/components/chart'
+import { cn } from '@mohou/ui/lib/utils'
+
+/**
+ * Multi-axis radar chart.
+ * @when Comparing an item across 4–8 dimensions (scores, coverage).
+ * @example
+ * <RadarChart data={[{ label: "性能", value: 70 }]} />
+ * @family Chart & data
+ */
+export function RadarChart({
+  data,
+  config,
+  dataKey = 'value',
+  size,
+  className,
+}: {
+  data: { label: string; value: number }[]
+  config: ChartConfig
+  dataKey?: string
+  size?: number
+  className?: string
+}) {
+  return (
+    <ChartContainer
+      config={config}
+      className={cn('mx-auto aspect-square', size ? '' : 'w-full max-w-80', className)}
+      style={size ? { width: size, height: size } : undefined}
+      data-testid="radar-chart"
+    >
+      <ReRadar data={data}>
+        <PolarGrid />
+        <PolarAngleAxis dataKey="label" />
+        <ChartTooltip content={<ChartTooltipContent />} />
+        <Radar dataKey={dataKey} fill="var(--color-value)" fillOpacity={0.35} />
+      </ReRadar>
+    </ChartContainer>
+  )
+}

package/src/blocks/request-inspector.tsx

@@ -0,0 +1,41 @@
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '@mohou/ui/components/tabs'
+import { CodeBlock } from '@mohou/ui/products/code-block'
+
+/**
+ * Side-by-side HTTP request/response panel.
+ * @when Debugging one API call: method, url, bodies. Multiple calls streaming → `LogViewer`.
+ * @example
+ * <RequestInspector method="POST" url="/api/x" response="{\"ok\":true}" />
+ * @family Discovery & inspect
+ */
+export function RequestInspector({
+  method,
+  url,
+  request,
+  response,
+}: {
+  method: string
+  url: string
+  request?: string
+  response?: string
+}) {
+  return (
+    <div data-testid="request-inspector" className="flex flex-col gap-2">
+      <div className="font-mono text-sm">
+        <span className="font-medium">{method}</span> {url}
+      </div>
+      <Tabs defaultValue="response">
+        <TabsList>
+          <TabsTrigger value="request">Request</TabsTrigger>
+          <TabsTrigger value="response">Response</TabsTrigger>
+        </TabsList>
+        <TabsContent value="request">
+          <CodeBlock code={request ?? ''} language="json" />
+        </TabsContent>
+        <TabsContent value="response">
+          <CodeBlock code={response ?? ''} language="json" />
+        </TabsContent>
+      </Tabs>
+    </div>
+  )
+}

package/src/blocks/reveal.tsx

@@ -0,0 +1,56 @@
+import { motion, useReducedMotion, type MotionStyle } from 'motion/react'
+
+import { cn } from '../lib/utils'
+
+/**
+ * Entrance reveal — fade and rise, with a per-item `delay` for a stagger.
+ *
+ * This is the kit's front door to the platform `motion` build (`/mma/vendors/motion.js`,
+ * one shared React). Use it for the common case and reach for
+ * `import { motion, AnimatePresence } from "motion/react"` when you need exit, layout,
+ * or gesture animation — `AnimatePresence` in particular is what keeps a removing row
+ * from vanishing mid-transition.
+ *
+ * @when A card, row, or section appearing on first paint or after a filter change. Not
+ *   for a hover/press response (one property: use a Tailwind `transition`) and not for
+ *   animating an element out (use `AnimatePresence`).
+ * @example
+ * {rows.map((r, i) => (
+ *   <Reveal key={r.id} delay={i * 60}>
+ *     <Card>{r.title}</Card>
+ *   </Reveal>
+ * ))}
+ * @family Animation
+ */
+export function Reveal({
+  children,
+  delay = 0,
+  distance = 8,
+  className,
+  style,
+}: {
+  children: React.ReactNode
+  /** Stagger in ms — pass `i * 60` for a list. */
+  delay?: number | undefined
+  /** Rise distance in px. `0` fades in place. */
+  distance?: number | undefined
+  className?: string | undefined
+  style?: React.CSSProperties | undefined
+}) {
+  // OS "reduce motion" wins over the design: no travel, no stagger, just present.
+  const reduce = useReducedMotion()
+  return (
+    <motion.div
+      data-mma-reveal=""
+      className={cn(className)}
+      style={(style ?? {}) as MotionStyle}
+      initial={reduce ? false : { opacity: 0, y: distance }}
+      animate={{ opacity: 1, y: 0 }}
+      transition={
+        reduce ? { duration: 0 } : { duration: 0.32, delay: delay / 1000, ease: 'easeOut' }
+      }
+    >
+      {children}
+    </motion.div>
+  )
+}

package/src/blocks/run-timeline.tsx

@@ -0,0 +1,12 @@
+import { Timeline, type TimelineItem } from '@mohou/ui/products/timeline'
+
+/**
+ * Timeline of run phases with duration + status.
+ * @when CI/agent/job phases on a time axis. Plain ordered events → `Timeline`.
+ * @example
+ * <RunTimeline items={[{ id: "p1", title: "checkout", status: "pass", time: "3s" }]} />
+ * @family Realtime
+ */
+export function RunTimeline({ items }: { items: TimelineItem[] }) {
+  return <Timeline items={items} />
+}

package/src/blocks/scrollspy.tsx

@@ -0,0 +1,48 @@
+
+import * as React from 'react'
+
+/**
+ * Anchor nav that highlights the section in view.
+ * @when Long settings/report page with jump links.
+ * @example
+ * <Scrollspy sections={[{ id: "overview", label: "概览" }]} />
+ * @family Navigation
+ */
+export function Scrollspy({
+  sections,
+}: {
+  sections: { id: string; label: string }[]
+}) {
+  const [active, setActive] = React.useState(sections[0]?.id)
+  React.useEffect(() => {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        const visible = entries.find(entry => entry.isIntersecting)
+        if (visible?.target.id) setActive(visible.target.id)
+      },
+      { rootMargin: '-40% 0px -50% 0px' },
+    )
+    sections.forEach((section) => {
+      const el = document.getElementById(section.id)
+      if (el) observer.observe(el)
+    })
+    return () => observer.disconnect()
+  }, [sections])
+  return (
+    <nav className="flex flex-col gap-1 text-sm" data-testid="scrollspy">
+      {sections.map(section => (
+        <a
+          key={section.id}
+          href={`#${section.id}`}
+          className={
+            active === section.id
+              ? 'text-foreground font-medium'
+              : 'text-muted-foreground'
+          }
+        >
+          {section.label}
+        </a>
+      ))}
+    </nav>
+  )
+}

package/src/blocks/settings-split.tsx

@@ -0,0 +1,153 @@
+
+import * as React from 'react';
+import type { ReactNode } from 'react';
+
+import { Scrollspy } from '@mohou/ui/blocks/scrollspy';
+import { useIsMobile } from '@mohou/ui/hooks/use-mobile';
+import { useLabels } from '@mohou/ui/i18n/context';
+import { cn } from '@mohou/ui/lib/utils';
+
+export type SettingsSection = {
+  /** The anchor id. The preset puts it on the section **and** hands the same value to the jump
+   *  list, so a nav that silently never highlights is not reachable from outside. */
+  id: string
+  label: string
+  /** One line under the heading — what this section is for. */
+  description?: string
+  content: ReactNode
+}
+
+export type SettingsSplitProps = {
+  /** The page's sections, in nav order. */
+  sections: SettingsSection[]
+  /** Anything above the jump list: page title, search, a plan badge. */
+  nav?: ReactNode
+  /** Pinned to the bottom of the **content** pane — an unsaved-changes bar belongs to what it
+   *  applies to, not to the window. */
+  footer?: ReactNode
+  /** Jump-list width on wide screens, px. Default 224. */
+  navWidth?: number
+  className?: string
+}
+
+/**
+ * Preferences / long-form page: a jump list that always matches the sections it scrolls to.
+ *
+ * Hand-rolled, this shape fails in three quiet ways: the nav's `href="#x"` and the section's
+ * `id` drift apart and the highlight never moves; the whole page scrolls so the nav scrolls out
+ * of view with the content it navigates; and a save bar placed after the content disappears
+ * below the fold. Here the ids come from one array, the nav and the content are independent
+ * scrollers, the jump list collapses to a pinned row when the panel is narrow, and `footer` is a
+ * sibling of the scroller — always visible, never part of the scroll.
+ *
+ * @when Page shape: a settings page, integration config, or a long report with anchored sections
+ * @example
+ * <SettingsSplit
+ *   sections={[
+ *     { id: "general", label: "通用", content: <GeneralForm /> },
+ *     { id: "hooks", label: "Webhook", description: "出站事件", content: <HooksForm /> },
+ *   ]}
+ *   nav={<PageHeader title="设置" />}
+ *   footer={dirty ? <UnsavedBar onSave={save} /> : undefined}
+ * />
+ * @family Layout & structure
+ */
+export function SettingsSplit({
+  sections,
+  nav,
+  footer,
+  navWidth = 224,
+  className,
+}: SettingsSplitProps) {
+  const isNarrow = useIsMobile()
+  const t = useLabels('settingsSplit');
+
+  // Scrollspy re-observes whenever this array identity changes, so derive it once per section list.
+  const anchors = React.useMemo(
+    () => sections.map(({ id, label }) => ({ id, label })),
+    [sections],
+  )
+
+  const jumpList = <Scrollspy sections={anchors} />
+
+  const content = (
+    <div
+      className="flex min-h-0 flex-1 flex-col"
+      data-testid="settings-split-content"
+    >
+      <div
+        className="min-h-0 flex-1 overflow-y-auto"
+        data-testid="settings-split-scroll"
+      >
+        {sections.map(s => (
+          <section
+            key={s.id}
+            id={s.id}
+            className="border-border scroll-mt-4 border-b px-6 py-6 last:border-b-0"
+          >
+            <h2 className="text-base font-semibold tracking-tight">
+              {s.label}
+            </h2>
+            {s.description ? (
+              <p className="text-muted-foreground mt-1 text-sm">
+                {s.description}
+              </p>
+            ) : null}
+            <div className="mt-4">{s.content}</div>
+          </section>
+        ))}
+      </div>
+      {footer ? (
+        // Sibling of the scroller, not its last child: the bar cannot scroll out of view.
+        <div
+          className="border-border bg-background shrink-0 border-t px-6 py-3"
+          data-testid="settings-split-footer"
+        >
+          {footer}
+        </div>
+      ) : null}
+    </div>
+  )
+
+  if (isNarrow) {
+    return (
+      <div
+        className={cn('flex h-full min-h-0 w-full flex-col', className)}
+        data-testid="settings-split"
+      >
+        <div
+          className="border-border bg-background shrink-0 overflow-x-auto border-b px-4 py-2"
+          data-testid="settings-split-nav"
+          aria-label={t.nav}
+        >
+          <div className="flex min-w-max items-center gap-4">
+            {nav ? (
+              <div className="text-muted-foreground text-xs">{nav}</div>
+            ) : null}
+            {jumpList}
+          </div>
+        </div>
+        {content}
+      </div>
+    )
+  }
+
+  return (
+    <div
+      className={cn('flex h-full min-h-0 w-full', className)}
+      data-testid="settings-split"
+      data-slot="settings-split-wide"
+    >
+      <aside
+        className="border-border min-h-0 w-56 shrink-0 overflow-y-auto border-r px-4 py-6"
+        data-testid="settings-split-nav"
+        aria-label={t.nav}
+        style={{ width: navWidth }}
+      >
+        {nav ? <div className="mb-4">{nav}</div> : null}
+        {jumpList}
+      </aside>
+      {content}
+    </div>
+  )
+}

package/src/blocks/severity-chip.tsx

@@ -0,0 +1,34 @@
+import { Badge } from '@mohou/ui/components/badge'
+import { cn } from '@mohou/ui/lib/utils'
+
+const tone = {
+  P0: 'bg-destructive/15 text-destructive',
+  P1: 'bg-orange-500/15 text-orange-700 dark:text-orange-400',
+  P2: 'bg-amber-500/15 text-amber-700 dark:text-amber-400',
+  P3: 'bg-muted text-muted-foreground',
+  critical: 'bg-destructive/15 text-destructive',
+  high: 'bg-orange-500/15 text-orange-700 dark:text-orange-400',
+  medium: 'bg-amber-500/15 text-amber-700 dark:text-amber-400',
+  low: 'bg-muted text-muted-foreground',
+} as const
+
+export type Severity = keyof typeof tone
+
+/**
+ * Chip for severity/blocker level.
+ * @when P0–P4, blocker/critical columns. Run outcome → `StatusBadge`.
+ * @example
+ * <SeverityChip severity="critical" />
+ * @family Feedback & status
+ */
+export function SeverityChip({ severity }: { severity: Severity | string }) {
+  return (
+    <Badge
+      variant="outline"
+      data-testid="severity-chip"
+      className={cn('border-transparent uppercase', tone[severity as Severity] ?? tone.low)}
+    >
+      {severity}
+    </Badge>
+  )
+}

package/src/blocks/sparkline.tsx

@@ -0,0 +1,27 @@
+
+import { Line, LineChart, YAxis } from 'recharts'
+
+import { ChartContainer, type ChartConfig } from '@mohou/ui/components/chart'
+import { cn } from '@mohou/ui/lib/utils'
+
+const config = {
+  value: { label: 'Value', color: 'var(--primary)' },
+} satisfies ChartConfig
+
+/**
+ * Tiny inline trend line, no axes.
+ * @when Trend inside a table row or KPI card.
+ * @example
+ * <Sparkline data={[{ value: 3 }, { value: 9 }, { value: 6 }]} />
+ * @family Chart & data
+ */
+export function Sparkline({ data, className }: { data: { value: number }[]; className?: string }) {
+  return (
+    <ChartContainer config={config} className={cn('h-20 w-full', className)} data-testid="sparkline">
+      <LineChart data={data}>
+        <YAxis hide domain={['dataMin', 'dataMax']} />
+        <Line dataKey="value" type="monotone" stroke="var(--color-value)" strokeWidth={1.5} dot={false} />
+      </LineChart>
+    </ChartContainer>
+  )
+}