@monkey-mini-app/ui 0.1.1 → 0.1.5

package/dist/src/products/stepper.tsx

@@ -1,89 +1,238 @@
-"use client"
+"use client";
 
-import { Check } from "lucide-react"
+import * as React from "react";
+import { Check } from "lucide-react";
 
-import { cn } from "@monkey-mini-app/ui/lib/utils"
+import { cn } from "@monkey-mini-app/ui/lib/utils";
 
-export type Step = { id: string; title: string; description?: string }
+export type StepStatus = "default" | "active" | "completed";
 
-export function Stepper({
-  steps,
-  current,
-  orientation = "vertical",
-  onStepClick,
-}: {
-  steps: Step[]
-  current: number
-  orientation?: "vertical" | "horizontal"
-  onStepClick?: (index: number) => void
-}) {
-  const horizontal = orientation === "horizontal"
+export interface StepperProps {
+  /** StepperItem elements. */
+  children: React.ReactNode;
+  /** Layout direction. Defaults to "vertical". */
+  orientation?: "vertical" | "horizontal";
+  className?: string;
+}
+
+export interface StepperItemProps {
+  /** Step heading text. */
+  title: string;
+  /** Optional description below the title. */
+  description?: string;
+  /** Override the auto-incremented step number. */
+  step?: number;
+  /** Visual status of this step. Defaults to "default". */
+  status?: StepStatus;
+  /** Custom icon to replace the step number circle. */
+  icon?: React.ReactNode;
+  /** Content rendered below the step header (code blocks, text, etc.). */
+  children?: React.ReactNode;
+  className?: string;
+}
+
+/**
+ * One step inside `Stepper` (title, description, status).
+ * @family Feedback & status
+ * @when As a child of `Stepper` only — status is `default | active | completed` (lowercase).
+ */
+export function StepperItem({
+  title,
+  description,
+  step,
+  status = "default",
+  icon,
+  children,
+  className,
+}: StepperItemProps) {
+  const stepNumber = step ?? 1;
 
   return (
-    <ol
-      data-testid="stepper"
-      data-orientation={orientation}
-      className={cn(horizontal ? "flex items-start gap-0" : "flex flex-col gap-3")}
+    <div
+      data-slot="stepper-item"
+      data-status={status}
+      className={cn("group/step relative", className)}
     >
-      {steps.map((step, index) => {
-        const state =
-          index < current ? "done" : index === current ? "current" : "todo"
-        const clickable = Boolean(onStepClick)
-        return (
-          <li
-            key={step.id}
+      <div className="flex gap-3">
+        <div className="flex shrink-0 flex-col items-center self-stretch">
+          <div
             className={cn(
-              horizontal
-                ? "flex min-w-0 flex-1 flex-col items-center text-center"
-                : "flex gap-3"
+              "relative z-10 flex size-8 shrink-0 items-center justify-center rounded-full border-2 text-sm font-semibold transition-colors",
+              status === "completed" &&
+                "border-primary bg-primary text-primary-foreground",
+              status === "active" &&
+                "border-primary bg-primary/10 text-primary",
+              status === "default" &&
+                "border-border bg-background text-muted-foreground"
             )}
           >
-            <div
-              className={cn(
-                "flex items-center",
-                horizontal ? "w-full justify-center" : "flex-col"
-              )}
-            >
-              {horizontal && index > 0 ? (
-                <span
+            {icon ? (
+              icon
+            ) : status === "completed" ? (
+              <Check className="size-3.5" aria-hidden="true" />
+            ) : (
+              <span className="text-xs">{stepNumber}</span>
+            )}
+          </div>
+
+          <div
+            className={cn(
+              "w-px min-h-4 grow",
+              status === "completed"
+                ? "bg-primary"
+                : "bg-border dark:bg-muted-foreground/25",
+              "group-last/step:hidden"
+            )}
+          />
+        </div>
+
+        <div className="flex min-w-0 flex-col gap-1 pb-6 pt-1 group-last/step:pb-0">
+          <div className="flex flex-col gap-0.5">
+            <h3 className="text-sm font-semibold leading-tight text-foreground">
+              {title}
+            </h3>
+            {description ? (
+              <p className="text-sm text-muted-foreground">{description}</p>
+            ) : null}
+          </div>
+          {children ? <div className="mt-2">{children}</div> : null}
+        </div>
+      </div>
+    </div>
+  );
+}
+
+function VerticalStepper({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) {
+  const items = React.Children.toArray(children).filter(React.isValidElement);
+
+  return (
+    <div
+      data-testid="stepper"
+      data-slot="stepper"
+      data-orientation="vertical"
+      className={cn("flex flex-col", className)}
+    >
+      {items.map((child, index) => {
+        if (!React.isValidElement<StepperItemProps>(child)) return child;
+        return React.cloneElement(child, {
+          step: child.props.step ?? index + 1,
+          key: child.key ?? index,
+        });
+      })}
+    </div>
+  );
+}
+
+function HorizontalStepper({
+  children,
+  className,
+}: {
+  children: React.ReactNode;
+  className?: string;
+}) {
+  const items = React.Children.toArray(children).filter(React.isValidElement);
+
+  return (
+    <div
+      data-testid="stepper"
+      data-slot="stepper"
+      data-orientation="horizontal"
+      className={cn("flex flex-col gap-4", className)}
+    >
+      <div className="flex items-center">
+        {items.map((child, index) => {
+          if (!React.isValidElement<StepperItemProps>(child)) return null;
+          const { status = "default", icon, step: stepProp } = child.props;
+          const stepNumber = stepProp ?? index + 1;
+          const isLast = index === items.length - 1;
+
+          return (
+            <React.Fragment key={child.key ?? index}>
+              <div className="flex flex-col items-center gap-1.5">
+                <div
                   className={cn(
-                    "mr-2 h-px min-w-4 flex-1",
-                    index <= current ? "bg-primary" : "bg-border"
+                    "flex size-8 shrink-0 items-center justify-center rounded-full border-2 text-sm font-semibold transition-colors",
+                    status === "completed" &&
+                      "border-primary bg-primary text-primary-foreground",
+                    status === "active" &&
+                      "border-primary bg-primary/10 text-primary",
+                    status === "default" &&
+                      "border-border bg-background text-muted-foreground"
                   )}
-                />
-              ) : null}
-              <button
-                type="button"
-                disabled={!clickable}
-                onClick={() => onStepClick?.(index)}
-                className={cn(
-                  "flex size-7 shrink-0 items-center justify-center rounded-full text-xs font-medium",
-                  state === "done" && "bg-primary text-primary-foreground",
-                  state === "current" && "border-2 border-primary text-primary",
-                  state === "todo" && "border text-muted-foreground",
-                  clickable && "cursor-pointer"
-                )}
-              >
-                {state === "done" ? <Check className="size-3.5" /> : index + 1}
-              </button>
-              {horizontal && index < steps.length - 1 ? (
+                >
+                  {icon ? (
+                    icon
+                  ) : status === "completed" ? (
+                    <Check className="size-3.5" aria-hidden="true" />
+                  ) : (
+                    <span className="text-xs">{stepNumber}</span>
+                  )}
+                </div>
                 <span
                   className={cn(
-                    "ml-2 h-px min-w-4 flex-1",
-                    index < current ? "bg-primary" : "bg-border"
+                    "max-w-[8rem] text-center text-xs font-medium",
+                    status === "default"
+                      ? "text-muted-foreground"
+                      : "text-foreground"
+                  )}
+                >
+                  {child.props.title}
+                </span>
+              </div>
+              {!isLast ? (
+                <div
+                  className={cn(
+                    "mb-5 h-px flex-1",
+                    status === "completed" ? "bg-primary" : "bg-border"
                   )}
                 />
               ) : null}
-            </div>
-            <div className={cn(horizontal ? "mt-2 px-1" : "")}>
-              <div className="text-sm font-medium">{step.title}</div>
-              {step.description ? (
-                <p className="text-muted-foreground text-xs">{step.description}</p>
-              ) : null}
-            </div>
-          </li>
-        )
+            </React.Fragment>
+          );
+        })}
+      </div>
+
+      {items.map((child, index) => {
+        if (!React.isValidElement<StepperItemProps>(child)) return null;
+        const { status = "default", description, children: stepChildren } =
+          child.props;
+        if (status !== "active") return null;
+
+        return (
+          <div key={child.key ?? index} className="flex flex-col gap-1.5">
+            {description ? (
+              <p className="text-sm text-muted-foreground">{description}</p>
+            ) : null}
+            {stepChildren ? <div>{stepChildren}</div> : null}
+          </div>
+        );
       })}
-    </ol>
-  )
+    </div>
+  );
+}
+
+/**
+ * Numbered steps with status; children are `StepperItem`.
+ * @family Feedback & status
+ * @when Wizard/progress of an ordered process. Time axis → `RunTimeline`.
+ * @example
+ * <Stepper><StepperItem title="上传" status="pass" /><StepperItem title="校验" status="running" /></Stepper>
+ */
+export function Stepper({
+  children,
+  orientation = "vertical",
+  className,
+}: StepperProps) {
+  if (orientation === "horizontal") {
+    return (
+      <HorizontalStepper className={className}>{children}</HorizontalStepper>
+    );
+  }
+  return <VerticalStepper className={className}>{children}</VerticalStepper>;
 }

package/dist/src/products/timeline.tsx

@@ -7,6 +7,13 @@ export type TimelineItem = {
   time?: string
 }
 
+/**
+ * Vertical ordered events.
+ * @when Statuses/history without durations. Durations → `RunTimeline`.
+ * @example
+ * <Timeline items={[{ id: "1", title: "已创建", time: "09:00" }]} />
+ * @family Realtime
+ */
 export function Timeline({ items }: { items: TimelineItem[] }) {
   return (
     <ol className="relative space-y-4 border-l pl-4" data-testid="timeline">

package/dist/src/products/tree-view.tsx

@@ -45,6 +45,13 @@ function Node({
   )
 }
 
+/**
+ * Generic expandable node list.
+ * @when Any hierarchy without file semantics. Files → `FileTree`.
+ * @example
+ * <TreeView nodes={[{ id: "a", label: "华东" }]} />
+ * @family Data & tables
+ */
 export function TreeView({ nodes }: { nodes: TreeNode[] }) {
   return (
     <div data-testid="tree-view">

package/dist/src/sdk/app-error-boundary.tsx

@@ -0,0 +1,240 @@
+import * as React from "react";
+
+import { useLabels } from "../i18n/context";
+import { AppIdContext } from "./app-id";
+
+/** Where a captured failure came from — drives the hint the human sees. */
+export type AppErrorKind = "render" | "module" | "uncaught" | "async";
+
+export type ReportedAppError = {
+  kind: AppErrorKind;
+  message: string;
+  file?: string;
+  line?: number;
+  column?: number;
+  stack?: string;
+  componentStack?: string;
+};
+
+/**
+ * Hand an error to the host so `mini_app_errors` can see it.
+ *
+ * The app iframe is same-origin with the host, but the panel embedding it is not — so the
+ * only channel that works in both directions is the iframe POSTing to its own host. This
+ * is deliberately fire-and-forget: a diagnostic path must never be able to break the app
+ * that is reporting through it.
+ */
+export function reportAppError(appId: string, err: ReportedAppError): void {
+  if (!appId) return;
+  try {
+    const body = JSON.stringify(err);
+    const url = `/api/app/${encodeURIComponent(appId)}/errors`;
+    // sendBeacon survives the unmount that a crashing app often triggers right after.
+    if (typeof navigator !== "undefined" && typeof navigator.sendBeacon === "function") {
+      const sent = navigator.sendBeacon(url, new Blob([body], { type: "application/json" }));
+      if (sent) return;
+    }
+    void fetch(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+      keepalive: true,
+    }).catch(() => {});
+  } catch {
+    /* never throw from a failure handler */
+  }
+}
+
+const HINT_KEY: Record<AppErrorKind, "renderHint" | "moduleHint" | "uncaughtHint" | "asyncHint"> = {
+  render: "renderHint",
+  module: "moduleHint",
+  uncaught: "uncaughtHint",
+  async: "asyncHint",
+};
+
+function ErrorCard(props: {
+  appId: string;
+  kind: AppErrorKind;
+  message: string;
+  stack?: string;
+  componentStack?: string;
+  onRetry: () => void;
+}) {
+  const t = useLabels("appError");
+  const [open, setOpen] = React.useState(false);
+  const detail = [props.componentStack, props.stack].filter(Boolean).join("\n");
+
+  return (
+    <div
+      role="alert"
+      style={{
+        boxSizing: "border-box",
+        margin: "24px",
+        padding: "16px 18px",
+        borderRadius: 12,
+        border: "1px solid var(--destructive,#dc2626)",
+        background: "var(--card,#fff)",
+        color: "var(--foreground,#111)",
+        font: "13px/1.6 var(--font-sans,ui-sans-serif,system-ui,sans-serif)",
+        maxWidth: 720,
+      }}
+    >
+      <div style={{ display: "flex", alignItems: "center", gap: 8, marginBottom: 6 }}>
+        <span
+          style={{
+            width: 8,
+            height: 8,
+            borderRadius: "50%",
+            background: "var(--destructive,#dc2626)",
+            flex: "0 0 auto",
+          }}
+        />
+        <strong style={{ fontSize: 14 }}>{t.title}</strong>
+        <code
+          style={{
+            marginLeft: "auto",
+            padding: "1px 6px",
+            borderRadius: 6,
+            background: "var(--muted,#f3f4f6)",
+            color: "var(--muted-foreground,#6b7280)",
+            fontSize: 11,
+          }}
+        >
+          {props.appId}
+        </code>
+      </div>
+
+      <p style={{ margin: "0 0 8px", color: "var(--muted-foreground,#6b7280)" }}>{t[HINT_KEY[props.kind]]}</p>
+
+      <pre
+        style={{
+          margin: 0,
+          padding: "10px 12px",
+          borderRadius: 8,
+          background: "var(--muted,#f3f4f6)",
+          whiteSpace: "pre-wrap",
+          wordBreak: "break-word",
+          fontFamily: "var(--font-mono,ui-monospace,SFMono-Regular,monospace)",
+          fontSize: 12,
+        }}
+      >
+        {props.message}
+      </pre>
+
+      <div style={{ display: "flex", gap: 8, alignItems: "center", marginTop: 12 }}>
+        <button
+          type="button"
+          onClick={props.onRetry}
+          style={{
+            padding: "5px 12px",
+            borderRadius: 8,
+            border: "1px solid var(--border,#e5e7eb)",
+            background: "var(--primary,#2563eb)",
+            color: "var(--primary-foreground,#fff)",
+            font: "inherit",
+            cursor: "pointer",
+          }}
+        >
+          {t.retry}
+        </button>
+        {detail ? (
+          <button
+            type="button"
+            onClick={() => setOpen((v) => !v)}
+            style={{
+              padding: "5px 12px",
+              borderRadius: 8,
+              border: "1px solid var(--border,#e5e7eb)",
+              background: "transparent",
+              color: "var(--foreground,#111)",
+              font: "inherit",
+              cursor: "pointer",
+            }}
+          >
+            {open ? t.hideDetails : t.details}
+          </button>
+        ) : null}
+        <span style={{ marginLeft: "auto", fontSize: 11, color: "var(--muted-foreground,#6b7280)" }}>
+          {t.reported}
+        </span>
+      </div>
+
+      {open && detail ? (
+        <pre
+          style={{
+            margin: "10px 0 0",
+            padding: "10px 12px",
+            borderRadius: 8,
+            background: "var(--muted,#f3f4f6)",
+            color: "var(--muted-foreground,#6b7280)",
+            whiteSpace: "pre-wrap",
+            wordBreak: "break-word",
+            maxHeight: 260,
+            overflow: "auto",
+            fontFamily: "var(--font-mono,ui-monospace,SFMono-Regular,monospace)",
+            fontSize: 11,
+          }}
+        >
+          {detail}
+        </pre>
+      ) : null}
+    </div>
+  );
+}
+
+type BoundaryProps = { children: React.ReactNode };
+/** Never `null`: React types `state` as `Readonly<S>`, and a nullable S is not a valid JSX element type. */
+type BoundaryState = { error?: Error; componentStack?: string };
+
+class AppErrorBoundaryClass extends React.Component<
+  BoundaryProps & { appId: string },
+  BoundaryState
+> {
+  /** Required: without an initializer `this.state` is null and the first render throws. */
+  state: BoundaryState = {};
+
+  static getDerivedStateFromError(error: Error): BoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: { componentStack?: string }): void {
+    const componentStack = typeof info?.componentStack === "string" ? info.componentStack : undefined;
+    this.setState({ componentStack });
+    reportAppError(this.props.appId, {
+      kind: "render",
+      message: error?.message || String(error),
+      stack: error?.stack,
+      componentStack,
+    });
+  }
+
+  render(): React.ReactNode {
+    const error = this.state.error;
+    if (error) {
+      return (
+        <ErrorCard
+          appId={this.props.appId}
+          kind="render"
+          message={error.message || String(error)}
+          stack={error.stack}
+          componentStack={this.state.componentStack}
+          onRetry={() => this.setState({ error: undefined, componentStack: undefined })}
+        />
+      );
+    }
+    return this.props.children;
+  }
+}
+
+/**
+ * Runtime crash guard for a mini-app UI. The host injects this around the app entry when
+ * it compiles `ui.tsx`, so authors never have to add it — and an app that throws during
+ * render shows a real message instead of a blank iframe.
+ *
+ * @when Not used from mini-app code: it is already wrapped around your `ui.tsx` by the host.
+ * @family Feedback & status
+ */
+export function AppErrorBoundary(props: { children: React.ReactNode }) {
+  const appId = React.useContext(AppIdContext);
+  return <AppErrorBoundaryClass appId={appId} key={appId} {...props} />;
+}

package/dist/src/sdk/app-id.ts

@@ -0,0 +1,7 @@
+import { createContext } from "react";
+
+/**
+ * App id injected by `<AppRuntime>`. Its own module so the error boundary can read it
+ * without importing `use-app` (which would make the two mutually dependent).
+ */
+export const AppIdContext = createContext("");