@monkey-mini-app/ui 0.1.1 → 0.1.5

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

@@ -0,0 +1,83 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import { cn } from "@monkey-mini-app/ui/lib/utils";
+
+export type TablePageProps = {
+  /** Page-level actions above the table: search, filters, "New". Pinned; it never scrolls away. */
+  toolbar?: ReactNode;
+  /** The table itself (a `DataGrid`, usually). The only slot that scrolls. */
+  grid?: ReactNode;
+  /** First-run / no-match placeholder. Renders when `grid` is not given. */
+  empty?: ReactNode;
+  /** A pager you own. `DataGrid` already renders its own when `features.pagination` is on. */
+  pagination?: ReactNode;
+  /** Bulk actions. Floats over the bottom of the grid instead of pushing the rows around. */
+  bulk?: ReactNode;
+  className?: string;
+};
+
+/**
+ * Full-height table page: toolbar pinned, one scrolling band for the grid, bulk bar floating.
+ *
+ * Without it a `DataGrid` is dropped into a plain flex column, the tallest child wins, and the
+ * page scrolls instead of the table: the toolbar slides off, pagination ends up below the fold,
+ * and selecting 200 rows shoves the table down every time the bulk bar appears. The band owns
+ * `min-h-0` + `overflow-y-auto` here, and the bulk bar is out of flow with `pointer-events-none`
+ * on its track so the rows under it stay clickable.
+ *
+ * @when Page shape: one wide filterable table is the product — inventories, ledgers, saved views
+ * @example
+ * <TablePage
+ *   toolbar={<FilterBar {...{ query, onQueryChange, filters }} />}
+ *   grid={rows.length ? <DataGrid columns={columns} data={rows} /> : undefined}
+ *   empty={<FirstRun onImport={import} />}
+ *   bulk={selected.size ? <BulkBar count={selected.size} onClear={clear} /> : undefined}
+ * />
+ * @family Layout & structure
+ */
+export function TablePage({
+  toolbar,
+  grid,
+  empty,
+  pagination,
+  bulk,
+  className,
+}: TablePageProps) {
+  return (
+    <div
+      className={cn("relative flex h-full min-h-0 w-full flex-col", className)}
+      data-testid="table-page"
+    >
+      {toolbar ? (
+        <div className="shrink-0" data-testid="table-page-toolbar">
+          {toolbar}
+        </div>
+      ) : null}
+
+      {/* The one scroller. `grid ?? empty` keeps "no rows" the app's decision, not a prop. */}
+      <div
+        className="min-h-0 flex-1 overflow-y-auto"
+        data-testid="table-page-grid"
+      >
+        {grid ?? empty ?? null}
+      </div>
+
+      {pagination ? (
+        <div className="shrink-0" data-testid="table-page-pagination">
+          {pagination}
+        </div>
+      ) : null}
+
+      {bulk ? (
+        <div
+          className="pointer-events-none absolute inset-x-0 bottom-0 flex justify-center px-4 pb-4"
+          data-testid="table-page-bulk"
+        >
+          <div className="pointer-events-auto">{bulk}</div>
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/dist/src/blocks/terminal.tsx

@@ -1,10 +1,28 @@
-export function Terminal({ lines }: { lines: string[] }) {
+import { cn } from "@monkey-mini-app/ui/lib/utils";
+
+/**
+ * Fixed-width console block.
+ * @when Showing a command + its output verbatim. Timestamped levels/scrolling → `LogViewer`.
+ * @example
+ * <Terminal lines={["$ df -h", "/dev/disk1  62%"]} />
+ * @family Realtime
+ */
+export function Terminal({
+  lines,
+  className,
+}: {
+  lines: string[];
+  className?: string;
+}) {
   return (
     <pre
       data-testid="terminal"
-      className="overflow-auto rounded-xl bg-zinc-950 p-3 font-mono text-xs leading-6 text-zinc-100"
+      className={cn(
+        "overflow-auto rounded-xl bg-zinc-950 p-3 font-mono text-xs leading-6 text-zinc-100",
+        className,
+      )}
     >
       {lines.join("\n")}
     </pre>
-  )
+  );
 }

package/dist/src/blocks/test-step-list.tsx

@@ -2,6 +2,13 @@ import { StatusBadge, type StatusKey } from "@monkey-mini-app/ui/blocks/status-b
 
 export type TestStep = { id: string; title: string; status: StatusKey | string }
 
+/**
+ * Numbered test steps with expected/actual + status.
+ * @when QA cases, checklists that get executed and graded.
+ * @example
+ * <TestStepList steps={[{ id: "s1", name: "登录", status: "pass" }]} />
+ * @family Data & tables
+ */
 export function TestStepList({ steps }: { steps: TestStep[] }) {
   return (
     <ol className="flex flex-col gap-2" data-testid="test-step-list">

package/dist/src/blocks/trend-card.tsx

@@ -17,6 +17,13 @@ const chartConfig = {
   value: { label: "Value", color: "var(--chart-1)" },
 } satisfies ChartConfig
 
+/**
+ * KPI card with a trend series.
+ * @when Metric + direction over time. Metric only → `StatCard`.
+ * @example
+ * <TrendCard title="请求数" value="1.2k" trend="up" data={[{ value: 9 }, { value: 12 }]} />
+ * @family Chart & data
+ */
 export function TrendCard({
   title,
   value,

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

@@ -0,0 +1,132 @@
+"use client";
+
+import type { ReactNode } from "react";
+
+import { Button } from "@monkey-mini-app/ui/components/button";
+import { Stepper, StepperItem } from "@monkey-mini-app/ui/products/stepper";
+import { useLabels } from "@monkey-mini-app/ui/i18n/context";
+import { cn } from "@monkey-mini-app/ui/lib/utils";
+
+export type WizardStep = {
+  id: string;
+  label: string;
+  /** Pass `false` while the step's form is incomplete — Next disables itself. Omit to allow. */
+  valid?: boolean;
+};
+
+export type WizardShellProps = {
+  /** The steps, in order. The rail is generated from this, so it cannot disagree with the body. */
+  steps: WizardStep[];
+  /** Which step is showing. The app owns it — the preset never navigates on its own. */
+  index: number;
+  /** Current step's content. The only scrolling area. */
+  body: ReactNode;
+  /** Replaces the generated Back/Next/Finish row (a preview pane, a second action…). */
+  footer?: ReactNode;
+  onBack?: () => void;
+  onNext?: () => void;
+  /** Fires on the last step's primary action. Without it the last step still shows Next. */
+  onSubmit?: () => void;
+  /** Greys the primary action and swaps in the busy label. */
+  submitting?: boolean;
+  className?: string;
+};
+
+/**
+ * Multi-step flow: step rail on top, scrolling body, action row that never moves.
+ *
+ * Hand-rolled, a wizard's footer rides along inside the scrolling column, so every step change
+ * jumps the buttons to a different height and the user chases them with the cursor; and Next is
+ * enabled into an invalid step because the validity check lives in the form and the button lives
+ * outside it. Here the footer is a `shrink-0` sibling of the scroller, and Next/Finish are
+ * disabled straight from `steps[index].valid`, which is the only place that can know.
+ *
+ * @when Page shape: create / import / onboarding, one step at a time with validation per step
+ * @example
+ * <WizardShell
+ *   steps={[{ id: "pick", label: "Choose file", valid: Boolean(file) }, { id: "map", label: "Map columns", valid: mapped }]}
+ *   index={step}
+ *   body={<StepBody />}
+ *   onBack={() => setStep((s) => s - 1)}
+ *   onNext={() => setStep((s) => s + 1)}
+ *   onSubmit={() => void run()}
+ * />
+ * @family Layout & structure
+ */
+export function WizardShell({
+  steps,
+  index,
+  body,
+  footer,
+  onBack,
+  onNext,
+  onSubmit,
+  submitting = false,
+  className,
+}: WizardShellProps) {
+  const t = useLabels("wizardShell");
+  const current = steps[index];
+  const last = index >= steps.length - 1;
+  const canAdvance = current?.valid !== false;
+  const primary = last && onSubmit ? t.finish : t.next;
+
+  return (
+    <div
+      className={cn("flex h-full min-h-0 w-full flex-col", className)}
+      data-testid="wizard-shell"
+    >
+      <div
+        className="border-border shrink-0 border-b px-4 py-3"
+        data-testid="wizard-rail"
+      >
+        <Stepper orientation="horizontal">
+          {steps.map((s, i) => (
+            <StepperItem
+              key={s.id}
+              step={i + 1}
+              title={s.label}
+              status={
+                i < index ? "completed" : i === index ? "active" : "default"
+              }
+            />
+          ))}
+        </Stepper>
+      </div>
+
+      <div
+        className="min-h-0 flex-1 overflow-y-auto px-4 py-4"
+        data-testid="wizard-body"
+      >
+        {body}
+      </div>
+
+      <div
+        className="border-border bg-background flex shrink-0 items-center justify-between gap-3 border-t px-4 py-3"
+        data-testid="wizard-footer"
+      >
+        {footer ?? (
+          <>
+            <Button
+              variant="ghost"
+              onClick={onBack}
+              disabled={index === 0 || submitting}
+              data-testid="wizard-back"
+            >
+              {t.back}
+            </Button>
+            <span className="text-muted-foreground text-xs tabular-nums">
+              {t.stepOf(index + 1, steps.length)}
+            </span>
+            <Button
+              onClick={last && onSubmit ? onSubmit : onNext}
+              disabled={!canAdvance || submitting}
+              data-testid="wizard-next"
+            >
+              {submitting ? t.working : primary}
+            </Button>
+          </>
+        )}
+      </div>
+    </div>
+  );
+}

package/dist/src/cdn-modules.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Heavy editors load CodeMirror / shiki from esm.sh on demand (not npm peers).
+ * Ambient so `import("https://esm.sh/...")` type-checks in the IDE.
+ */
+declare module "https://esm.sh/*";

package/dist/src/components/accordion.tsx

@@ -3,6 +3,13 @@ import { Accordion as AccordionPrimitive } from "@base-ui/react/accordion"
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { ChevronDownIcon, ChevronUpIcon } from "lucide-react"
 
+/**
+ * Vertically expanding sections.
+ * @when Collapsible groups in settings/details.
+ * @example
+ * <Accordion type="single"><AccordionItem value="s1"><AccordionTrigger>高级</AccordionTrigger><AccordionContent>…</AccordionContent></AccordionItem></Accordion>
+ * @family Surface
+ */
 function Accordion({ className, ...props }: AccordionPrimitive.Root.Props) {
   return (
     <AccordionPrimitive.Root

package/dist/src/components/alert-dialog.tsx

@@ -4,6 +4,13 @@ import { AlertDialog as AlertDialogPrimitive } from "@base-ui/react/alert-dialog
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { Button } from "@monkey-mini-app/ui/components/button"
 
+/**
+ * Blocking confirm modal (no click-outside dismiss).
+ * @when Deleting/irreversible actions that must be answered.
+ * @example
+ * <AlertDialog open={ask} onOpenChange={setAsk}><AlertDialogContent><AlertDialogTitle>确定删除？</AlertDialogTitle><AlertDialogAction onClick={del}>删除</AlertDialogAction></AlertDialogContent></AlertDialog>
+ * @family Surface
+ */
 function AlertDialog({ ...props }: AlertDialogPrimitive.Root.Props) {
   return <AlertDialogPrimitive.Root data-slot="alert-dialog" {...props} />
 }

package/dist/src/components/alert.tsx

@@ -19,6 +19,13 @@ const alertVariants = cva(
   }
 )
 
+/**
+ * Inline message block (info/warning/error).
+ * @when Explaining a failed state in place. Transient → `toast()`.
+ * @example
+ * <Alert variant="destructive"><AlertTitle>拉取失败</AlertTitle><AlertDescription>上游 502，已用缓存</AlertDescription></Alert>
+ * @family Feedback & status
+ */
 function Alert({
   className,
   variant,

package/dist/src/components/aspect-ratio.tsx

@@ -1,5 +1,9 @@
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * @family Layout & structure
+ * @when Keeping an image/video/embed from shifting the layout while loading.
+ */
 function AspectRatio({
   ratio,
   className,

package/dist/src/components/attachment.tsx

@@ -24,6 +24,10 @@ const attachmentVariants = cva(
   }
 )
 
+/**
+ * @family Discovery & inspect
+ * @when One selected file inside a form. A grid of many → `AttachmentGallery`.
+ */
 function Attachment({
   className,
   state = "done",

package/dist/src/components/avatar.tsx

@@ -3,6 +3,10 @@ import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * @family Layout & structure
+ * @when User initials/photo next to a name in rows, comments, pickers.
+ */
 function Avatar({
   className,
   size = "default",

package/dist/src/components/badge.tsx

@@ -27,6 +27,13 @@ const badgeVariants = cva(
   }
 )
 
+/**
+ * Inline label chip.
+ * @when Static tags/counts. Status → `StatusBadge`, severity → `SeverityChip`.
+ * @example
+ * <Badge variant="secondary">草稿</Badge>
+ * @family Feedback & status
+ */
 function Badge({
   className,
   variant = "default",

package/dist/src/components/breadcrumb.tsx

@@ -5,6 +5,10 @@ import { useRender } from "@base-ui/react/use-render"
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { ChevronRightIcon, MoreHorizontalIcon } from "lucide-react"
 
+/**
+ * @family Navigation
+ * @when Deep mini-app views; usually one level is enough — prefer `Tabs`/`AppShell` nav.
+ */
 function Breadcrumb({ className, ...props }: React.ComponentProps<"nav">) {
   return (
     <nav

package/dist/src/components/bubble.tsx

@@ -42,6 +42,10 @@ const bubbleVariants = cva(
   }
 )
 
+/**
+ * @family Surface
+ * @when Conversational UI (assistant turns). Records/logs → `ActivityFeed` / `Message`.
+ */
 function Bubble({
   variant = "default",
   align = "start",

package/dist/src/components/button-group.tsx

@@ -22,6 +22,12 @@ const buttonGroupVariants = cva(
   }
 )
 
+/**
+ * @family Form
+ * @when 2–5 mutually related actions (view switch, alignment). Tabs of content → `Tabs`.
+ * @example
+ * <ButtonGroup><Button variant="outline">List</Button><Button variant="outline">Board</Button></ButtonGroup>
+ */
 function ButtonGroup({
   className,
   orientation,

package/dist/src/components/button.tsx

@@ -40,6 +40,13 @@ const buttonVariants = cva(
   }
 )
 
+/**
+ * Action button with variants and icon sizing.
+ * @when Every click target. `variant="destructive"` for delete, `size="icon*"` for icon-only (add aria-label).
+ * @example
+ * <Button variant="outline" size="sm" onClick={run}>刷新</Button>
+ * @family Form
+ */
 function Button({
   className,
   variant = "default",

package/dist/src/components/calendar.tsx

@@ -12,6 +12,10 @@ import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { Button, buttonVariants } from "@monkey-mini-app/ui/components/button"
 import { ChevronLeftIcon, ChevronRightIcon, ChevronDownIcon } from "lucide-react"
 
+/**
+ * @family Calendar & date
+ * @when An inline calendar inside your own layout. As a field with input → `DatePicker`.
+ */
 function Calendar({
   className,
   classNames,

package/dist/src/components/card.tsx

@@ -2,6 +2,13 @@ import * as React from "react"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Surface with header/content/footer.
+ * @when The default container for a block of related UI.
+ * @example
+ * <Card><CardHeader><CardTitle>今日摘要</CardTitle></CardHeader><CardContent>…</CardContent></Card>
+ * @family Surface
+ */
 function Card({
   className,
   size = "default",
@@ -12,7 +19,7 @@ function Card({
       data-slot="card"
       data-size={size}
       className={cn(
-        "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-xl bg-card py-(--card-spacing) text-sm text-card-foreground ring-1 ring-foreground/10 [--card-spacing:--spacing(4)] has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(3)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
+        "group/card flex flex-col gap-(--card-spacing) overflow-hidden rounded-xl border border-border bg-card py-(--card-spacing) text-sm text-card-foreground [--card-spacing:--spacing(4)] has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:[--card-spacing:--spacing(3)] data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
         className
       )}
       {...props}

package/dist/src/components/chart.tsx

@@ -37,6 +37,13 @@ function useChart() {
   return context
 }
 
+/**
+ * Recharts container + theme CSS vars + tooltip/legend parts.
+ * @when Only when no `*Chart` block fits — then you own the series. Prefer `DonutChart` / `StackedBarChart` / `Sparkline` / `Gauge` / `RadarChart`.
+ * @example
+ * <ChartContainer config={cfg} className="h-40 w-full"><Bar data={rows} dataKey="v" /></ChartContainer>
+ * @family Chart & data
+ */
 function ChartContainer({
   id,
   className,

package/dist/src/components/checkbox.tsx

@@ -5,6 +5,11 @@ import { Checkbox as CheckboxPrimitive } from "@base-ui/react/checkbox"
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { CheckIcon } from "lucide-react"
 
+/**
+ * Single boolean box.
+ * @when Multi-select rows / opt-in.
+ * @family Form
+ */
 function Checkbox({ className, ...props }: CheckboxPrimitive.Root.Props) {
   return (
     <CheckboxPrimitive.Root

package/dist/src/components/collapsible.tsx

@@ -1,5 +1,9 @@
 import { Collapsible as CollapsiblePrimitive } from "@base-ui/react/collapsible"
 
+/**
+ * @family Layout & structure
+ * @when A single disclosure (advanced options). Several stacked → `Accordion`.
+ */
 function Collapsible({ ...props }: CollapsiblePrimitive.Root.Props) {
   return <CollapsiblePrimitive.Root data-slot="collapsible" {...props} />
 }

package/dist/src/components/combobox.tsx

@@ -11,6 +11,10 @@ import {
 } from "@monkey-mini-app/ui/components/input-group"
 import { ChevronDownIcon, XIcon, CheckIcon } from "lucide-react"
 
+/**
+ * @family Form
+ * @when When you need full control of the popover list. Simple suggestion box → `Autocomplete`.
+ */
 const Combobox = ComboboxPrimitive.Root
 
 function ComboboxValue({ ...props }: ComboboxPrimitive.Value.Props) {

package/dist/src/components/command.tsx

@@ -17,6 +17,12 @@ import {
 } from "@monkey-mini-app/ui/components/input-group"
 import { SearchIcon, CheckIcon } from "lucide-react"
 
+/**
+ * @family Navigation
+ * @when Jump between views/actions inside one app.
+ * @example
+ * <CommandDialog open={open} onOpenChange={setOpen}><CommandInput placeholder="跳转…" /><CommandList><CommandItem onSelect={go}>今日</CommandItem></CommandList></CommandDialog>
+ */
 function Command({
   className,
   ...props

package/dist/src/components/context-menu.tsx

@@ -6,6 +6,10 @@ import { ContextMenu as ContextMenuPrimitive } from "@base-ui/react/context-menu
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { ChevronRightIcon, CheckIcon } from "lucide-react"
 
+/**
+ * @family Navigation
+ * @when Row/canvas operations. Trigger-button actions → `DropdownMenu`.
+ */
 function ContextMenu({ ...props }: ContextMenuPrimitive.Root.Props) {
   return <ContextMenuPrimitive.Root data-slot="context-menu" {...props} />
 }

package/dist/src/components/dialog.tsx

@@ -5,6 +5,13 @@ import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { Button } from "@monkey-mini-app/ui/components/button"
 import { XIcon } from "lucide-react"
 
+/**
+ * Modal overlay: Trigger + Content(+Header/Footer).
+ * @when Focused edit/confirm flow. Needs no focus takeover → `Sheet`. Destructive yes/no → `ConfirmDialog`. Size it with `width` on `DialogContent`: the base caps at `sm:max-w-sm`, so a `max-w-*` in `className` loses at ≥sm.
+ * @example
+ * <Dialog open={open} onOpenChange={setOpen}><DialogTrigger asChild><Button>编辑</Button></DialogTrigger><DialogContent><DialogHeader><DialogTitle>标题</DialogTitle></DialogHeader>…<DialogFooter><Button onClick={save}>保存</Button></DialogFooter></DialogContent></Dialog>
+ * @family Surface
+ */
 function Dialog({ ...props }: DialogPrimitive.Root.Props) {
   return <DialogPrimitive.Root data-slot="dialog" {...props} />
 }
@@ -41,15 +48,29 @@ function DialogContent({
   className,
   children,
   showCloseButton = true,
+  width,
+  style,
   ...props
 }: DialogPrimitive.Popup.Props & {
   showCloseButton?: boolean
+  /**
+   * Dialog width — a number is px. Inline `maxWidth`, because the base class caps the dialog at
+   * `sm:max-w-sm` and that utility outranks one the caller passes in `className`.
+   */
+  width?: string | number
 }) {
+  const maxWidth =
+    width == null
+      ? undefined
+      : typeof width === "number"
+        ? `${width}px`
+        : width
   return (
     <DialogPortal>
       <DialogOverlay />
       <DialogPrimitive.Popup
         data-slot="dialog-content"
+        style={maxWidth == null ? style : { ...style, maxWidth }}
         className={cn(
           "fixed top-1/2 left-1/2 z-50 grid w-full max-w-[calc(100%-2rem)] -translate-x-1/2 -translate-y-1/2 gap-4 rounded-xl bg-popover p-4 text-sm text-popover-foreground ring-1 ring-foreground/10 duration-100 outline-none sm:max-w-sm data-open:animate-in data-open:fade-in-0 data-open:zoom-in-95 data-closed:animate-out data-closed:fade-out-0 data-closed:zoom-out-95",
           className

package/dist/src/components/drawer.tsx

@@ -22,6 +22,10 @@ function useDrawer() {
   return context
 }
 
+/**
+ * @family Surface
+ * @when Mobile-ish bottom sheet on narrow panels. Desktop detail → `Sheet`.
+ */
 function Drawer({
   modal = true,
   showSwipeHandle = false,

package/dist/src/components/dropdown-menu.tsx

@@ -6,6 +6,13 @@ import { Menu as MenuPrimitive } from "@base-ui/react/menu"
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 import { ChevronRightIcon, CheckIcon } from "lucide-react"
 
+/**
+ * Command menu on a trigger.
+ * @when Row `MoreHorizontal` actions. Free-form panel content → `Popover`.
+ * @example
+ * <DropdownMenu><DropdownMenuTrigger asChild><Button><Icon.MoreHorizontal /></Button></DropdownMenuTrigger><DropdownMenuContent><DropdownMenuItem onClick={edit}>编辑</DropdownMenuItem></DropdownMenuContent></DropdownMenu>
+ * @family Navigation
+ */
 function DropdownMenu({ ...props }: MenuPrimitive.Root.Props) {
   return <MenuPrimitive.Root data-slot="dropdown-menu" {...props} />
 }

package/dist/src/components/empty.tsx

@@ -2,6 +2,13 @@ import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * Empty-state block: media + title + description + action.
+ * @when Any list/panel with no rows — pair media with an `Illu*`.
+ * @example
+ * <Empty><EmptyHeader><EmptyMedia variant="icon"><IlluEmpty /></EmptyMedia><EmptyTitle>还没有数据</EmptyTitle><EmptyDescription>点右上角添加</EmptyDescription></EmptyHeader></Empty>
+ * @family Feedback & status
+ */
 function Empty({
   className,
   title,

package/dist/src/components/field.tsx

@@ -67,6 +67,12 @@ const fieldVariants = cva(
   }
 )
 
+/**
+ * @family Form
+ * @when Any form row that must read well and stay accessible.
+ * @example
+ * <Field><FieldLabel htmlFor="n">名称</FieldLabel><Input id="n" /><FieldDescription>显示在列表里</FieldDescription></Field>
+ */
 function Field({
   className,
   orientation = "vertical",

package/dist/src/components/hover-card.tsx

@@ -2,6 +2,10 @@ import { PreviewCard as PreviewCardPrimitive } from "@base-ui/react/preview-card
 
 import { cn } from "@monkey-mini-app/ui/lib/utils"
 
+/**
+ * @family Surface
+ * @when Peek a user/issue without navigating. Needs a decision → `Dialog`.
+ */
 function HoverCard({ ...props }: PreviewCardPrimitive.Root.Props) {
   return <PreviewCardPrimitive.Root data-slot="hover-card" {...props} />
 }