@monkey-mini-app/ui 0.1.1 → 0.1.4

package/dist/src/blocks/activity-feed.tsx

@@ -1,5 +1,12 @@
 import { Timeline, type TimelineItem } from "@monkey-mini-app/ui/products/timeline"
 
+/**
+ * Chronological activity list (avatar + text + time).
+ * @when Read-only “who did what when” — commits, deploys, agent runs. For steps with status use `RunTimeline`.
+ * @example
+ * <ActivityFeed items={[{ id: "1", title: "部署完成", time: "10:24" }]} />
+ * @family Realtime
+ */
 export function ActivityFeed({ items }: { items: TimelineItem[] }) {
   return (
     <div data-testid="activity-feed">

package/dist/src/blocks/app-shell.tsx

@@ -9,6 +9,7 @@ import { cn } from "@monkey-mini-app/ui/lib/utils"
  * <AppShell sidebar={<nav />} header={<PageHeader title="Home" />}>
  *   {children}
  * </AppShell>
+ * @family Layout & structure
  */
 export function AppShell({
   sidebar,

package/dist/src/blocks/attachment-gallery.tsx

@@ -10,6 +10,13 @@ import {
 
 export type GalleryFile = { name: string; url?: string }
 
+/**
+ * Thumbnail grid of files with open/copy.
+ * @when A record has N files/images and you show them as tiles, not a table.
+ * @example
+ * <AttachmentGallery files={[{ name: "log.txt", url: "https://…" }]} />
+ * @family Discovery & inspect
+ */
 export function AttachmentGallery({ files }: { files: GalleryFile[] }) {
   return (
     <AttachmentGroup data-testid="attachment-gallery">

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

@@ -10,6 +10,17 @@ import {
 } from "@monkey-mini-app/ui/components/chart"
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Stacked bar chart over flat rows.
+ * @family Chart & data
+ * @when Comparing several series across categories (pass/fail per day). Single ratio → `DonutChart`; trend → `Sparkline`.
+ * @example
+ * <StackedBarChart
+ *   data={[{ label: "09-01", ok: 12, fail: 2 }]}
+ *   keys={["ok", "fail"]}
+ *   config={{ ok: { label: "通过", color: "var(--primary)" }, fail: { label: "失败", color: "var(--destructive)" } }}
+ * />
+ */
 export function StackedBarChart({
   data,
   config,

package/dist/src/blocks/comment-thread.tsx

@@ -2,6 +2,13 @@ import { Avatar, AvatarFallback } from "@monkey-mini-app/ui/components/avatar"
 
 export type Comment = { id: string; author: string; body: string; time?: string }
 
+/**
+ * Nested comments with author + time.
+ * @when Issue/ticket discussion, review comments. Editing a comment is your job, not the component's.
+ * @example
+ * <CommentThread comments={[{ id: "c1", author: "P.Wang", text: "这里再确认下" }]} />
+ * @family Realtime
+ */
 export function CommentThread({ comments }: { comments: Comment[] }) {
   return (
     <div className="flex flex-col gap-3" data-testid="comment-thread">

package/dist/src/blocks/dashboard-shell.tsx

@@ -0,0 +1,109 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import { useIsMobile } from "@monkey-mini-app/ui/hooks/use-mobile";
+import { cn } from "@monkey-mini-app/ui/lib/utils";
+
+export type DashboardShellProps = {
+  /** Title row / `PageHeader`. Pinned: it stays while the content scrolls under it. */
+  header?: ReactNode;
+  /** KPI strip. Pinned with the header — the point of a dashboard is that the numbers hold. */
+  kpis?: ReactNode;
+  /** Charts and tables. The scrolling body. */
+  main: ReactNode;
+  /** Activity feed / top offenders. Sits beside `main` on wide screens, stacks under it when narrow. */
+  aside?: ReactNode;
+  /** Aside width in px on wide screens. Default 320. */
+  asideWidth?: number;
+  className?: string;
+};
+
+/**
+ * Overview page with a pinned header + KPI strip and exactly one scrolling body.
+ *
+ * The failure this exists for: the page is a plain column, `overflow-auto` ends up on the
+ * outermost div, and the first chart the user scrolls past takes the header and the KPI row
+ * with it — a dashboard whose numbers scroll away is not a dashboard. The aside gets its own
+ * scroller when there is room for two, and folds under `main` into the single body scroller
+ * when there is not, rather than becoming a third half-height pane.
+ *
+ * @when Page shape: metrics up top, charts below, optional activity rail — ops overviews, monitor walls
+ * @example
+ * <DashboardShell
+ *   header={<PageHeader title="值班" description="每 5 秒" />}
+ *   kpis={<div className="grid grid-cols-4 gap-3">{cards}</div>}
+ *   main={<Charts />}
+ *   aside={<ActivityFeed items={items} />}
+ * />
+ * @family Layout & structure
+ */
+export function DashboardShell({
+  header,
+  kpis,
+  main,
+  aside,
+  asideWidth = 320,
+  className,
+}: DashboardShellProps) {
+  const isNarrow = useIsMobile();
+
+  const pinned = (
+    <>
+      {header ? (
+        <div className="shrink-0" data-testid="dashboard-header">
+          {header}
+        </div>
+      ) : null}
+      {kpis ? (
+        <div className="shrink-0" data-testid="dashboard-kpis">
+          {kpis}
+        </div>
+      ) : null}
+    </>
+  );
+
+  return (
+    <div
+      className={cn("flex h-full min-h-0 w-full flex-col", className)}
+      data-testid="dashboard-shell"
+    >
+      {pinned}
+
+      {aside && !isNarrow ? (
+        // Room for two panes: each scrolls on its own, neither can push the other.
+        <div className="flex min-h-0 flex-1" data-testid="dashboard-body">
+          <div
+            className="min-h-0 flex-1 overflow-y-auto"
+            data-testid="dashboard-main"
+          >
+            {main}
+          </div>
+          <div
+            className="border-border bg-muted/30 min-h-0 shrink-0 overflow-y-auto border-l"
+            data-testid="dashboard-aside"
+            style={{ width: asideWidth }}
+          >
+            {aside}
+          </div>
+        </div>
+      ) : (
+        // One body scroller; the aside folds to the bottom of it instead of a squeezed pane.
+        <div
+          className="min-h-0 flex-1 overflow-y-auto"
+          data-testid="dashboard-body"
+        >
+          <div data-testid="dashboard-main">{main}</div>
+          {aside ? (
+            <div
+              className="border-border border-t px-4 py-4"
+              data-testid="dashboard-aside"
+            >
+              {aside}
+            </div>
+          ) : null}
+        </div>
+      )}
+    </div>
+  );
+}

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

@@ -1,3 +1,10 @@
+/**
+ * Label/value pairs, two columns.
+ * @when Detail/inspector panel of a selected row — the default “show one record” view.
+ * @example
+ * <DescriptionList items={[{ label: "状态", value: "运行中" }]} />
+ * @family Layout & structure
+ */
 export function DescriptionList({
   items,
 }: {

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

@@ -15,6 +15,7 @@ import {
  * @when Master-detail after row/card click
  * @example
  * <DetailPanel open={!!id} onOpenChange={() => setId(null)} title="Run #12">{body}</DetailPanel>
+ * @family Surface
  */
 export function DetailPanel({
   open,

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

@@ -13,6 +13,13 @@ import { cn } from "@monkey-mini-app/ui/lib/utils"
 
 export type Slice = { name: string; value: number; fill: string }
 
+/**
+ * Ring chart with centre label.
+ * @when Part-of-whole (≤6 slices): storage usage, status split. More categories → `StackedBarChart`.
+ * @example
+ * <DonutChart data={[{ label: "OK", value: 82, color: "var(--primary)" }]} center="82%" />
+ * @family Chart & data
+ */
 export function DonutChart({
   data,
   config,

package/dist/src/blocks/env-badge.tsx

@@ -10,6 +10,13 @@ const tone: Record<string, string> = {
   local: "bg-muted text-muted-foreground",
 }
 
+/**
+ * Coloured pill for an environment name.
+ * @when prd / stg / dev markers in headers and tables.
+ * @example
+ * <EnvBadge env="production" />
+ * @family Feedback & status
+ */
 export function EnvBadge({ env }: { env: string }) {
   return (
     <Badge

package/dist/src/blocks/env-table.tsx

@@ -0,0 +1,316 @@
+"use client";
+
+import * as React from "react";
+import { Check, ClipboardList, Copy, Eye, EyeOff } from "lucide-react";
+
+import { useLabels } from "@monkey-mini-app/ui/i18n/context";
+import { writeClipboard } from "@monkey-mini-app/ui/lib/clipboard";
+import { cn } from "@monkey-mini-app/ui/lib/utils";
+
+export type Environment =
+  | "production"
+  | "preview"
+  | "development"
+  | (string & {});
+
+export type EnvVariable = {
+  /** Variable name (e.g. DATABASE_URL). */
+  key: string;
+  /** Variable value. Masked by default. */
+  value: string;
+  /** Target environment. When provided, renders as a pill. */
+  environment?: Environment;
+  /** Optional description shown below the key. */
+  description?: string;
+};
+
+export type EnvTableProps = Omit<
+  React.ComponentProps<"div">,
+  "children" | "title"
+> & {
+  /** Environment variables to display. */
+  variables: EnvVariable[];
+  /** Optional heading above the table. */
+  title?: string;
+  /** Start with all values revealed. Defaults to false. */
+  defaultRevealed?: boolean;
+};
+
+function envBadgeColor(env: Environment): string {
+  switch (env) {
+    case "production":
+      return "bg-emerald-500/15 text-emerald-700 dark:text-emerald-400";
+    case "preview":
+      return "bg-sky-500/15 text-sky-700 dark:text-sky-400";
+    case "development":
+      return "bg-amber-500/15 text-amber-700 dark:text-amber-400";
+    default:
+      return "bg-muted text-muted-foreground";
+  }
+}
+
+function maskValue(value: string): string {
+  if (value.length <= 4) return "••••••••";
+  return `${value.slice(0, 4)}••••••••`;
+}
+
+function CopyButton({
+  value,
+  label,
+  className,
+}: {
+  value: string;
+  label: string;
+  className?: string;
+}) {
+  const [copied, setCopied] = React.useState(false);
+
+  const handleCopy = React.useCallback(() => {
+    void writeClipboard(value).then((ok) => {
+      if (!ok) return;
+      setCopied(true);
+      setTimeout(() => setCopied(false), 1500);
+    });
+  }, [value]);
+
+  return (
+    <button
+      type="button"
+      onClick={handleCopy}
+      aria-label={label}
+      className={cn(
+        "inline-flex items-center justify-center rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring",
+        className,
+      )}
+    >
+      {copied ? (
+        <Check className="size-3.5 text-emerald-500" />
+      ) : (
+        <Copy className="size-3.5" />
+      )}
+    </button>
+  );
+}
+
+function RevealButton({
+  revealed,
+  onToggle,
+  label,
+}: {
+  revealed: boolean;
+  onToggle: () => void;
+  label: string;
+}) {
+  return (
+    <button
+      type="button"
+      onClick={onToggle}
+      aria-label={label}
+      className="inline-flex items-center justify-center rounded-md p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+    >
+      {revealed ? (
+        <EyeOff className="size-3.5" />
+      ) : (
+        <Eye className="size-3.5" />
+      )}
+    </button>
+  );
+}
+
+function EnvRow({
+  variable,
+  revealed,
+  onToggleReveal,
+}: {
+  variable: EnvVariable;
+  revealed: boolean;
+  onToggleReveal: () => void;
+}) {
+  const t = useLabels("envTable");
+  const displayValue = revealed ? variable.value : maskValue(variable.value);
+
+  return (
+    <div
+      data-slot="env-row"
+      className="group flex items-start gap-3 px-3 py-2.5 sm:items-center sm:px-4"
+    >
+      <div className="flex min-w-0 flex-1 flex-col gap-1.5 sm:flex-row sm:items-center sm:gap-4">
+        <div className="flex shrink-0 items-center gap-2 sm:w-[220px]">
+          <span className="truncate font-mono text-xs font-semibold text-foreground">
+            {variable.key}
+          </span>
+          {variable.environment ? (
+            <span
+              className={cn(
+                "shrink-0 rounded-full px-2 py-0.5 text-[10px] font-medium leading-none",
+                envBadgeColor(variable.environment),
+              )}
+            >
+              {variable.environment}
+            </span>
+          ) : null}
+        </div>
+
+        <div className="min-w-0 flex-1">
+          <span
+            className={cn(
+              "break-all font-mono text-xs",
+              revealed ? "text-foreground" : "text-muted-foreground",
+            )}
+          >
+            {displayValue}
+          </span>
+          {variable.description ? (
+            <p className="mt-0.5 text-[11px] text-muted-foreground/70">
+              {variable.description}
+            </p>
+          ) : null}
+        </div>
+      </div>
+
+      <div className="flex shrink-0 items-center gap-0.5">
+        <RevealButton
+          revealed={revealed}
+          onToggle={onToggleReveal}
+          label={revealed ? t.hideKey(variable.key) : t.revealKey(variable.key)}
+        />
+        <CopyButton value={variable.value} label={t.copyValue(variable.key)} />
+      </div>
+    </div>
+  );
+}
+
+/**
+ * Read-only env var table with masked values and copy.
+ * @when Settings / deploy preview / secrets display
+ * @example
+ * <EnvTable variables={[{ key: "API_URL", value: "https://…", environment: "production" }]} />
+ * @family Data & tables
+ */
+export function EnvTable({
+  variables,
+  title,
+  defaultRevealed = false,
+  className,
+  ...props
+}: EnvTableProps) {
+  const t = useLabels("envTable");
+  const [revealedIndices, setRevealedIndices] = React.useState<Set<number>>(
+    () => (defaultRevealed ? new Set(variables.map((_, i) => i)) : new Set()),
+  );
+  const [copiedAll, setCopiedAll] = React.useState(false);
+
+  const allRevealed =
+    variables.length > 0 && revealedIndices.size === variables.length;
+
+  const toggleIndex = React.useCallback((index: number) => {
+    setRevealedIndices((prev) => {
+      const next = new Set(prev);
+      if (next.has(index)) {
+        next.delete(index);
+      } else {
+        next.add(index);
+      }
+      return next;
+    });
+  }, []);
+
+  const toggleAll = React.useCallback(() => {
+    if (allRevealed) {
+      setRevealedIndices(new Set());
+    } else {
+      setRevealedIndices(new Set(variables.map((_, i) => i)));
+    }
+  }, [allRevealed, variables]);
+
+  const copyAllAsEnv = React.useCallback(() => {
+    const text = variables.map((v) => `${v.key}=${v.value}`).join("\n");
+    void writeClipboard(text).then((ok) => {
+      if (!ok) return;
+      setCopiedAll(true);
+      setTimeout(() => setCopiedAll(false), 1500);
+    });
+  }, [variables]);
+
+  if (variables.length === 0) {
+    return (
+      <div
+        data-testid="env-table"
+        data-slot="env-table"
+        className={cn(
+          "flex items-center justify-center rounded-xl border border-border/60 bg-card py-10 text-sm text-muted-foreground shadow-sm",
+          className,
+        )}
+        {...props}
+      >
+        {t.empty}
+      </div>
+    );
+  }
+
+  return (
+    <div
+      data-testid="env-table"
+      data-slot="env-table"
+      className={cn(
+        "overflow-hidden rounded-xl border border-border/60 bg-card shadow-sm",
+        className,
+      )}
+      {...props}
+    >
+      <div className="flex items-center justify-between border-b border-border/40 px-3 py-2.5 sm:px-4">
+        <div className="flex items-center gap-2">
+          {title ? (
+            <h3 className="text-sm font-semibold text-foreground">{title}</h3>
+          ) : null}
+          <span className="rounded-full bg-muted px-2 py-0.5 text-[10px] font-medium text-muted-foreground">
+            {variables.length}
+          </span>
+        </div>
+        <div className="flex items-center gap-1">
+          <button
+            type="button"
+            onClick={toggleAll}
+            aria-label={allRevealed ? t.hideAllValues : t.revealAllValues}
+            className="inline-flex items-center gap-1.5 rounded-md px-2 py-1.5 text-xs text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {allRevealed ? (
+              <EyeOff className="size-3.5" />
+            ) : (
+              <Eye className="size-3.5" />
+            )}
+            <span className="hidden sm:inline">
+              {allRevealed ? t.hideAll : t.revealAll}
+            </span>
+          </button>
+          <button
+            type="button"
+            onClick={copyAllAsEnv}
+            aria-label={t.copyEnv}
+            className="inline-flex items-center gap-1.5 rounded-md px-2 py-1.5 text-xs text-muted-foreground transition-colors hover:bg-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {copiedAll ? (
+              <Check className="size-3.5 text-emerald-500" />
+            ) : (
+              <ClipboardList className="size-3.5" />
+            )}
+            <span className="hidden sm:inline">
+              {copiedAll ? t.copied : t.copyEnv}
+            </span>
+          </button>
+        </div>
+      </div>
+
+      <div className="divide-y divide-border/40">
+        {variables.map((variable, i) => (
+          <EnvRow
+            key={`${variable.key}-${i}`}
+            variable={variable}
+            revealed={revealedIndices.has(i)}
+            onToggleReveal={() => toggleIndex(i)}
+          />
+        ))}
+      </div>
+    </div>
+  );
+}

package/dist/src/blocks/file-tree.tsx

@@ -1,5 +1,12 @@
 import { TreeView, type TreeNode } from "@monkey-mini-app/ui/products/tree-view"
 
+/**
+ * Expandable file/dir tree (icons built in).
+ * @when Repo/zip contents where selection matters. Plain nested list → `TreeView`.
+ * @example
+ * <FileTree nodes={[{ name: "src", children: [{ name: "main.api.ts" }] }]} />
+ * @family Data & tables
+ */
 export function FileTree({ nodes }: { nodes: TreeNode[] }) {
   return <TreeView nodes={nodes} />
 }

package/dist/src/blocks/filter-bar.tsx

@@ -8,6 +8,7 @@ import type { ReactNode } from "react"
  *   <DateRangePicker value={range} onChange={setRange} />
  *   <SearchInput value={q} onChange={setQ} />
  * </FilterBar>
+ * @family Data & tables
  */
 export function FilterBar({ children }: { children: ReactNode }) {
   return (