@monkey-mini-app/ui 0.1.0 → 0.1.4

package/dist/src/blocks/form-sheet.tsx

@@ -0,0 +1,160 @@
+"use client";
+
+import * as React from "react";
+import type { FormEvent, ReactNode } from "react";
+
+import {
+  AlertDialog,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogAction,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@monkey-mini-app/ui/components/alert-dialog";
+import {
+  Sheet,
+  SheetContent,
+  SheetDescription,
+  SheetHeader,
+  SheetTitle,
+} from "@monkey-mini-app/ui/components/sheet";
+import { useLabels } from "@monkey-mini-app/ui/i18n/context";
+import { cn } from "@monkey-mini-app/ui/lib/utils";
+
+export type FormSheetProps = {
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+  title: ReactNode;
+  description?: ReactNode;
+  /** Anything below the title: a badge, a record id, a tab strip. */
+  header?: ReactNode;
+  /** The scrolling form fields. */
+  children: ReactNode;
+  /** Action row, pinned. Put the primary control in here with `type="submit"`. */
+  footer?: ReactNode;
+  /** One submit path for the whole sheet: Enter in a field and the footer button land here. */
+  onSubmit?: (e: FormEvent<HTMLFormElement>) => void;
+  side?: "top" | "right" | "bottom" | "left";
+  width?: string | number;
+  /** Ask before throwing edits away. The app owns the check; the preset owns the prompt. */
+  dirty?: boolean;
+  className?: string;
+};
+
+/**
+ * Create / edit form over a list you do not want to lose.
+ *
+ * The usual build has three cracks: the header and footer scroll away with the fields (so the
+ * Cancel button is somewhere the user has to hunt for), Enter in a text field submits *something
+ * else* or nothing because there is no form around the inputs, and Escape closes a sheet full of
+ * unsaved edits. Here only the body is a scroller — header, form and footer are siblings inside a
+ * flex column — the fields and the footer share one `<form onSubmit>`, and a dirty sheet asks
+ * first.
+ *
+ * @when Page shape: focused create/edit over a list — new record, edit record, wizard-less config
+ * @example
+ * <FormSheet
+ *   open={Boolean(editing)}
+ *   onOpenChange={(o) => !o && setEditing(null)}
+ *   title="Edit issue"
+ *   dirty={dirty}
+ *   onSubmit={save}
+ *   footer={<Button type="submit">Save</Button>}
+ * >
+ *   <Input name="summary" />
+ * </FormSheet>
+ * @family Layout & structure
+ */
+export function FormSheet({
+  open,
+  onOpenChange,
+  title,
+  description,
+  header,
+  children,
+  footer,
+  onSubmit,
+  side = "right",
+  width = 480,
+  dirty = false,
+  className,
+}: FormSheetProps) {
+  const t = useLabels("formSheet");
+  const [guard, setGuard] = React.useState(false);
+
+  const request = (next: boolean) => {
+    if (!next && dirty) {
+      setGuard(true);
+      return;
+    }
+    onOpenChange(next);
+  };
+
+  return (
+    <>
+      <Sheet open={open} onOpenChange={request}>
+        <SheetContent
+          side={side}
+          width={width}
+          className={cn("flex min-h-0 flex-col gap-0 p-0", className)}
+          data-testid="form-sheet"
+        >
+          <SheetHeader className="border-border shrink-0 border-b px-6 py-4 text-left">
+            <SheetTitle className="text-base">{title}</SheetTitle>
+            {description ? (
+              <SheetDescription>{description}</SheetDescription>
+            ) : null}
+            {header}
+          </SheetHeader>
+
+          {/* One form wraps the scroller *and* the footer, so Enter and the button are the same path. */}
+          <form
+            className="flex min-h-0 flex-1 flex-col"
+            onSubmit={(e) => {
+              e.preventDefault();
+              onSubmit?.(e);
+            }}
+            data-testid="form-sheet-form"
+          >
+            <div
+              className="min-h-0 flex-1 overflow-y-auto px-6 py-4"
+              data-testid="form-sheet-body"
+            >
+              {children}
+            </div>
+            {footer ? (
+              <div
+                className="border-border bg-background shrink-0 border-t px-6 py-3"
+                data-testid="form-sheet-footer"
+              >
+                {footer}
+              </div>
+            ) : null}
+          </form>
+        </SheetContent>
+      </Sheet>
+
+      <AlertDialog open={guard} onOpenChange={setGuard}>
+        <AlertDialogContent data-testid="form-sheet-guard">
+          <AlertDialogHeader>
+            <AlertDialogTitle>{t.discardTitle}</AlertDialogTitle>
+            <AlertDialogDescription>{t.discardBody}</AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel>{t.keepEditing}</AlertDialogCancel>
+            <AlertDialogAction
+              onClick={() => {
+                setGuard(false);
+                onOpenChange(false);
+              }}
+            >
+              {t.discard}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  );
+}

package/dist/src/blocks/gauge.tsx

@@ -1,13 +1,36 @@
 import { ProgressRing } from "@monkey-mini-app/ui/blocks/progress-ring"
+import { cn } from "@monkey-mini-app/ui/lib/utils"
 
-export function Gauge({ value, label }: { value: number; label?: string }) {
+/**
+ * Arc gauge for one 0–100 metric.
+ * @when A single health/capacity number that needs a zone (SLO, disk). Series over time → `Sparkline`.
+ * @example
+ * <Gauge value={73} label="磁盘" />
+ * @family Chart & data
+ */
+export function Gauge({
+  value,
+  label,
+  size = 112,
+  className,
+}: {
+  value: number
+  label?: string
+  size?: number
+  className?: string
+}) {
   return (
-    <div className="flex items-center gap-2" data-testid="gauge">
-      <ProgressRing value={value} />
-      <div>
-        <div className="text-sm font-medium">{value}%</div>
-        {label ? <div className="text-muted-foreground text-xs">{label}</div> : null}
+    <div
+      className={cn("flex flex-col items-center gap-2", className)}
+      data-testid="gauge"
+    >
+      <div className="relative" style={{ width: size, height: size }}>
+        <ProgressRing value={value} className="h-full w-full" />
+        <div className="absolute inset-0 flex flex-col items-center justify-center">
+          <span className="text-2xl font-semibold tabular-nums">{value}%</span>
+        </div>
       </div>
+      {label ? <div className="text-xs text-muted-foreground">{label}</div> : null}
     </div>
   )
 }

package/dist/src/blocks/list-detail.tsx

@@ -0,0 +1,121 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import {
+  ResizableHandle,
+  ResizablePanel,
+  ResizablePanelGroup,
+} from "@monkey-mini-app/ui/components/resizable";
+import { useIsMobile } from "@monkey-mini-app/ui/hooks/use-mobile";
+import { useLabels } from "@monkey-mini-app/ui/i18n/context";
+import { cn } from "@monkey-mini-app/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/dist/src/blocks/notification-center.tsx

@@ -6,6 +6,13 @@ export type NotificationItem = {
   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">

package/dist/src/blocks/page-header.tsx

@@ -11,6 +11,7 @@ export type PageHeaderProps = {
  * @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 (

package/dist/src/blocks/progress-ring.tsx

@@ -1,4 +1,21 @@
-export function ProgressRing({ value }: { value: number }) {
+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
@@ -7,7 +24,8 @@ export function ProgressRing({ value }: { value: number }) {
     <svg
       data-testid="progress-ring"
       viewBox="0 0 40 40"
-      className="size-10 -rotate-90"
+      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

package/dist/src/blocks/radar-chart.tsx

@@ -8,18 +8,35 @@ import {
   ChartTooltipContent,
   type ChartConfig,
 } from "@monkey-mini-app/ui/components/chart"
+import { cn } from "@monkey-mini-app/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="mx-auto aspect-square h-56" data-testid="radar-chart">
+    <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" />

package/dist/src/blocks/request-inspector.tsx

@@ -1,6 +1,13 @@
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@monkey-mini-app/ui/components/tabs"
 import { CodeBlock } from "@monkey-mini-app/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,

package/dist/src/blocks/reveal.tsx

@@ -0,0 +1,56 @@
+import { motion, useReducedMotion } 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
+  /** Rise distance in px. `0` fades in place. */
+  distance?: number
+  className?: string
+  style?: React.CSSProperties
+}) {
+  // 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}
+      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/dist/src/blocks/run-timeline.tsx

@@ -1,5 +1,12 @@
 import { Timeline, type TimelineItem } from "@monkey-mini-app/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/dist/src/blocks/scrollspy.tsx

@@ -2,6 +2,13 @@
 
 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,
 }: {

package/dist/src/blocks/settings-split.tsx

@@ -0,0 +1,154 @@
+"use client";
+
+import * as React from "react";
+import type { ReactNode } from "react";
+
+import { Scrollspy } from "@monkey-mini-app/ui/blocks/scrollspy";
+import { useIsMobile } from "@monkey-mini-app/ui/hooks/use-mobile";
+import { useLabels } from "@monkey-mini-app/ui/i18n/context";
+import { cn } from "@monkey-mini-app/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/dist/src/blocks/severity-chip.tsx

@@ -14,6 +14,13 @@ const tone = {
 
 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